@catalyst-cloud/cli 0.14.10 → 0.15.0

package/dist/onboard-workflow.js

@@ -3,6 +3,7 @@ import { readFileSync } from "node:fs";
 import { configPathFor, loadConfig, normalizeBaseUrl } from "./config.js";
 import { verifyOnboardRoutes } from "./onboard-capabilities.js";
 import { selectedOnboardTeam } from "./onboard-existing.js";
+import { onboardTeamKey } from "./onboard-next.js";
 import { ownedFetch } from "./owned-fetch.js";
 import { loadHttpSdk } from "./sdk.js";
 import { fetchMe } from "./transport.js";
@@ -36,6 +37,12 @@ const object = (value) => value !== null && typeof value === "object" && !Array.
     : null;
 const id = (value) => typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/.test(value);
 const integer = (value) => typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+const automationChecks = [
+    ["open", "linear_automation_pr_open"],
+    ["review", "linear_automation_pr_review"],
+    ["ready", "linear_automation_pr_ready"],
+    ["merge", "linear_automation_pr_merge"],
+];
 /** Existing mappings can satisfy this step by observation. This never means a preview was applied. */
 export function observeOnboardWorkflow(value, team, now) {
     const row = object(value), config = object(row?.config), readiness = object(row?.readiness);
@@ -120,191 +127,327 @@ export function observeOnboardWorkflow(value, team, now) {
         "labels_present",
     ].some((check) => checks.get(check) !== "pass"))
         return null;
+    const automations = automationChecks.map(([event, check]) => [
+        event,
+        checks.get(check),
+    ]);
+    const conflicts = automations
+        .filter(([, state]) => state === "fail")
+        .map(([event]) => event);
     return {
         mappingHash: row.mappingHash,
         mappingRevision: config.workflowRev,
         readinessRevision: readiness.workflowRev,
         checkedAt: readiness.checkedAt,
         mappedSlots: [...mapping.values()].filter((value) => value !== null).length,
+        ...(automations.every(([, state]) => state === "pass" || state === "fail")
+            ? { automations: conflicts.length ? conflicts.join(",") : "none" }
+            : {}),
     };
 }
-/** HTTP only, without rotating credentials or calling adopt/apply. Every entered fetch/body joins. */
-export function onboardWorkflowVerificationAdapter(input = {}) {
-    return {
-        check: async (ctx, journal, external) => {
-            let cfg;
-            try {
-                cfg = loadConfig(ctx.home);
-            }
-            catch {
-                return waiting("workflow_identity_unverified");
-            }
-            const team = selectedOnboardTeam(journal);
-            if (!team ||
-                !cfg?.user ||
-                (cfg.user.role !== "owner" && cfg.user.role !== "admin") ||
-                cfg.account !== (journal.account ?? journal.tenant) ||
-                cfg.user.id !== journal.membershipId ||
-                !journal.baseUrl ||
-                normalizeBaseUrl(cfg.baseUrl) !== normalizeBaseUrl(journal.baseUrl))
+const label = (text) => text
+    .replace(/[\u0000-\u001f\u007f-\u009f\u200b-\u200f\u2028-\u202e\u2066-\u2069\ufeff]/g, "")
+    .trim()
+    .slice(0, 80);
+const listed = (names) => names.length > 10
+    ? `${names.slice(0, 10).join(", ")}, and ${names.length - 10} more`
+    : names.join(", ");
+/** The adopt preview in plain words: stages and labels it creates or keeps. Linear's names are data. */
+export function adoptPlanLines(plan) {
+    const group = (rows, outcome) => rows.filter((row) => row.outcome === outcome).map((row) => label(row.name));
+    return [
+        ["Create stages", group(plan.stages, "would-create")],
+        ["Keep existing stages", group(plan.stages, "already-present")],
+        ["Linear refused stages", group(plan.stages, "refused")],
+        ["Create labels", group(plan.labels, "would-create")],
+        ["Labels already present", group(plan.labels, "already-present")],
+        ["Linear refused labels", group(plan.labels, "refused")],
+    ]
+        .filter(([, names]) => names.length > 0)
+        .map(([title, names]) => `${title}: ${listed(names)}`)
+        .concat(plan.unfilledLoadBearing?.length ? [`Required work stages still missing: ${plan.unfilledLoadBearing.length}`] : [], (plan.provenanceGaps?.length ?? 0) + (plan.labelProvenanceGaps?.length ?? 0) ? ["Some existing states or labels have no recorded creator; setup keeps them"] : [], plan.labelsNotCreated?.length ? [`Labels that cannot be added: ${plan.labelsNotCreated.length}`] : []);
+}
+/** The only adopt bodies setup sends: this team, and the approved mode and hash. */
+export function adoptRequestAllowed(body, team, allow) {
+    if (typeof body !== "string")
+        return false;
+    try {
+        const sent = object(JSON.parse(body));
+        return (!!sent &&
+            sent.team === team &&
+            sent.mode === allow.mode &&
+            Object.keys(sent).length === (allow.mode === "apply" ? 3 : 2) &&
+            (allow.mode === "preview" ||
+                (allow.team === team && sent.planHash === allow.planHash)));
+    }
+    catch {
+        return false;
+    }
+}
+/** One bounded, identity-pinned exchange. Reads are GETs on the workflow, /me and the contract;
+ * `adopt` also allows the one POST it names to the adopt route, the same route `catalyst team adopt`
+ * uses. No credential rotation, no config write. Every entered fetch/body joins before return. */
+async function workflowSession(ctx, journal, external, adopt, run, announce) {
+    let cfg;
+    try {
+        cfg = loadConfig(ctx.home);
+    }
+    catch {
+        return waiting("workflow_identity_unverified");
+    }
+    const team = selectedOnboardTeam(journal);
+    if (!team ||
+        !cfg?.user ||
+        (cfg.user.role !== "owner" && cfg.user.role !== "admin") ||
+        cfg.account !== (journal.account ?? journal.tenant) ||
+        cfg.user.id !== journal.membershipId ||
+        !journal.baseUrl ||
+        normalizeBaseUrl(cfg.baseUrl) !== normalizeBaseUrl(journal.baseUrl))
+        return waiting("workflow_identity_unverified");
+    if (adopt?.mode === "apply" && adopt.team !== team)
+        return waiting("workflow_identity_unverified");
+    const origin = normalizeBaseUrl(cfg.baseUrl), person = cfg.user.id, role = cfg.user.role;
+    let url;
+    try {
+        url = new URL(origin);
+    }
+    catch {
+        return waiting("workflow_identity_unverified");
+    }
+    if (url.protocol !== "https:" ||
+        url.origin !== origin ||
+        url.username ||
+        url.password)
+        return waiting("workflow_identity_unverified");
+    const credential = cfg.key ||
+        (cfg.auth && Date.parse(cfg.auth.expiresAt) - ctx.now().getTime() > 30_000
+            ? cfg.auth.accessToken
+            : undefined);
+    if (!credential)
+        return waiting("workflow_login_refresh_required");
+    const configWitness = () => createHash("sha256")
+        .update(readFileSync(configPathFor(ctx.home)))
+        .digest("hex");
+    let before;
+    try {
+        before = configWitness();
+    }
+    catch {
+        return waiting("workflow_identity_unverified");
+    }
+    const current = () => {
+        try {
+            const now = loadConfig(ctx.home);
+            return (now?.user?.id === person &&
+                now.user.role === role &&
+                now.account === cfg.account &&
+                normalizeBaseUrl(now.baseUrl) === origin &&
+                configWitness() === before &&
+                selectedOnboardTeam(journal) === team &&
+                (!!cfg.key ||
+                    (!!cfg.auth && Date.parse(cfg.auth.expiresAt) > ctx.now().getTime())));
+        }
+        catch {
+            return false;
+        }
+    };
+    const deadline = new AbortController();
+    const timer = setTimeout(() => deadline.abort(), 30_000);
+    const signal = external
+        ? AbortSignal.any([external, deadline.signal])
+        : deadline.signal;
+    const owned = ownedFetch(ctx.fetch, signal, { maxBodyBytes: 524_288 });
+    const read = (request, init) => {
+        if (!current() || signal.aborted)
+            return Promise.reject(new Error("workflow_read_stopped"));
+        const requested = new URL(request instanceof Request ? request.url : String(request));
+        const method = init?.method ?? (request instanceof Request ? request.method : "GET");
+        const write = !!adopt &&
+            method === "POST" &&
+            requested.pathname === `${path}/adopt` &&
+            requested.search === "" &&
+            !(request instanceof Request) &&
+            adoptRequestAllowed(init?.body, team, adopt);
+        if ((method !== "GET" && !write) ||
+            requested.origin !== origin ||
+            requested.username ||
+            requested.password ||
+            requested.hash ||
+            (!write &&
+                (!["/api/v1/me", "/api/v1/agent/contract", path].includes(requested.pathname) ||
+                    (requested.pathname === path
+                        ? requested.search !== `?team=${encodeURIComponent(team)}`
+                        : requested.search !== ""))))
+            return Promise.reject(new Error("workflow_read_scope"));
+        return owned.fetch(request, { ...init, signal, redirect: "error" });
+    };
+    const live = async () => {
+        const me = await fetchMe(origin, credential, read);
+        return (current() &&
+            !signal.aborted &&
+            me.account === cfg.account &&
+            me.user?.id === person &&
+            me.user.role === role);
+    };
+    const result = await (async () => {
+        try {
+            if (!(await live()))
                 return waiting("workflow_identity_unverified");
-            const origin = normalizeBaseUrl(cfg.baseUrl), person = cfg.user.id, role = cfg.user.role;
-            let url;
-            try {
-                url = new URL(origin);
+            const support = await verifyOnboardRoutes({ ...ctx, fetch: read }, journal, [{ method: "GET", path }], signal);
+            if ("reason" in support)
+                return waiting(support.reason);
+            if (adopt) {
+                // Onboarding's own route list does not carry adopt; the tenant contract does, and it is the
+                // list `catalyst team adopt` requires before it posts.
+                const reply = await read(`${origin}/api/v1/agent/contract`, {
+                    headers: {
+                        authorization: `Bearer ${credential}`,
+                        accept: "application/json",
+                    },
+                });
+                const routes = reply.ok ? object(await reply.json())?.routes : null;
+                if (!Array.isArray(routes) ||
+                    !routes.some((route) => object(route)?.method === "POST" &&
+                        object(route)?.path === `${path}/adopt`))
+                    return waiting("cloud_capability_unavailable");
             }
-            catch {
+            if (!current() || signal.aborted)
                 return waiting("workflow_identity_unverified");
-            }
-            if (url.protocol !== "https:" ||
-                url.origin !== origin ||
-                url.username ||
-                url.password)
+            const sdk = await loadHttpSdk();
+            if (!current() || signal.aborted)
                 return waiting("workflow_identity_unverified");
-            const credential = cfg.key ||
-                (cfg.auth &&
-                    Date.parse(cfg.auth.expiresAt) - ctx.now().getTime() > 30_000
-                    ? cfg.auth.accessToken
-                    : undefined);
-            if (!credential)
-                return waiting("workflow_login_refresh_required");
-            const configWitness = () => createHash("sha256")
-                .update(readFileSync(configPathFor(ctx.home)))
-                .digest("hex");
-            let before;
+            const client = sdk.createTenantClient({
+                baseUrl: origin,
+                key: credential,
+                fetch: read,
+                timeoutMs: 30_000,
+                now: () => ctx.now().getTime(),
+            });
+            return await run({ team, client: client.teamWorkflow, live });
+        }
+        catch {
+            return waiting(external?.aborted ? "interrupted" : "workflow_unavailable");
+        }
+        finally {
             try {
-                before = configWitness();
+                owned.abort(new Error("workflow_read_complete"));
+                await owned.settle();
             }
-            catch {
-                return waiting("workflow_identity_unverified");
+            finally {
+                clearTimeout(timer);
             }
-            const current = () => {
-                try {
-                    const now = loadConfig(ctx.home);
-                    return (now?.user?.id === person &&
-                        now.user.role === role &&
-                        now.account === cfg.account &&
-                        normalizeBaseUrl(now.baseUrl) === origin &&
-                        configWitness() === before &&
-                        selectedOnboardTeam(journal) === team &&
-                        (!!cfg.key ||
-                            (!!cfg.auth &&
-                                Date.parse(cfg.auth.expiresAt) > ctx.now().getTime())));
-                }
-                catch {
-                    return false;
-                }
-            };
-            const deadline = new AbortController();
-            const timer = setTimeout(() => deadline.abort(), 30_000);
-            const signal = external
-                ? AbortSignal.any([external, deadline.signal])
-                : deadline.signal;
-            const owned = ownedFetch(ctx.fetch, signal, { maxBodyBytes: 524_288 });
-            const read = (request, init) => {
-                if (!current() || signal.aborted)
-                    return Promise.reject(new Error("workflow_read_stopped"));
-                const requested = new URL(request instanceof Request ? request.url : String(request));
-                const method = init?.method ?? (request instanceof Request ? request.method : "GET");
-                if (method !== "GET" ||
-                    requested.origin !== origin ||
-                    requested.username ||
-                    requested.password ||
-                    requested.hash ||
-                    !["/api/v1/me", "/api/v1/agent/contract", path].includes(requested.pathname) ||
-                    (requested.pathname === path
-                        ? requested.search !== `?team=${encodeURIComponent(team)}`
-                        : requested.search !== ""))
-                    return Promise.reject(new Error("workflow_read_scope"));
-                return owned.fetch(request, { ...init, signal, redirect: "error" });
-            };
-            const live = async () => {
-                const me = await fetchMe(origin, credential, read);
-                return (current() &&
-                    !signal.aborted &&
-                    me.account === cfg.account &&
-                    me.user?.id === person &&
-                    me.user.role === role);
-            };
-            const result = await (async () => {
-                try {
-                    if (!(await live()))
-                        return waiting("workflow_identity_unverified");
-                    const support = await verifyOnboardRoutes({ ...ctx, fetch: read }, journal, [{ method: "GET", path }], signal);
-                    if ("reason" in support)
-                        return waiting(support.reason);
-                    if (!current() || signal.aborted)
-                        return waiting("workflow_identity_unverified");
-                    const sdk = await loadHttpSdk();
-                    if (!current() || signal.aborted)
-                        return waiting("workflow_identity_unverified");
-                    const client = sdk.createTenantClient({
-                        baseUrl: origin,
-                        key: credential,
-                        fetch: read,
-                        timeoutMs: 30_000,
-                        now: () => ctx.now().getTime(),
-                    });
-                    const first = await client.teamWorkflow.get(team);
-                    const observed = first.outcome === "ok"
-                        ? observeOnboardWorkflow(first, team, ctx.now().getTime())
-                        : null;
-                    if (!observed || !current() || signal.aborted) {
-                        input.message?.("Workflow adoption is waiting for a verified mapping or full-plan server support. Setup made no workflow change.");
-                        return waiting("workflow_mapping_unverified");
-                    }
-                    if (!(await live()))
-                        return waiting("workflow_identity_unverified");
-                    const last = await client.teamWorkflow.get(team);
-                    const verified = last.outcome === "ok"
-                        ? observeOnboardWorkflow(last, team, ctx.now().getTime())
-                        : null;
-                    if (!verified ||
-                        verified.mappingHash !== observed.mappingHash ||
-                        verified.mappingRevision !== observed.mappingRevision ||
-                        verified.readinessRevision !== observed.readinessRevision ||
-                        !current() ||
-                        signal.aborted)
-                        return waiting("workflow_mapping_changed");
-                    if (!(await live()))
-                        return waiting("workflow_identity_unverified");
-                    if (!current() || signal.aborted)
-                        return waiting("workflow_identity_unverified");
-                    return {
-                        state: "done",
-                        evidence: {
-                            team,
-                            revision: verified.readinessRevision,
-                            mappingRevision: verified.mappingRevision,
-                            checkedAt: verified.checkedAt,
-                            mappingHash: verified.mappingHash,
-                            count: verified.mappedSlots,
-                        },
-                    };
-                }
-                catch {
-                    return waiting(external?.aborted ? "interrupted" : "workflow_unavailable");
-                }
-                finally {
-                    try {
-                        owned.abort(new Error("workflow_read_complete"));
-                        await owned.settle();
-                    }
-                    finally {
-                        clearTimeout(timer);
+        }
+    })();
+    if (!current())
+        return waiting("workflow_identity_unverified");
+    if (signal.aborted)
+        return waiting(external?.aborted ? "interrupted" : "workflow_unavailable");
+    if (result.state === "done" && announce) {
+        // The display runs outside the bounded exchange, so identity is checked again after it.
+        announce();
+        if (!current() || signal.aborted)
+            return waiting("workflow_identity_unverified");
+    }
+    return result;
+}
+/** Verifies the selected team's mapping by observation. With a plan question or --yes, an unadopted
+ * team is `pending` and `act` previews, asks and applies the same adopt plan `catalyst team adopt`
+ * applies, then the engine checks again. Without either, setup never writes the workflow. */
+export function onboardWorkflowVerificationAdapter(input = {}) {
+    const adopts = !!input.confirm || input.yes === true;
+    const check = (ctx, journal, external) => workflowSession(ctx, journal, external, null, async ({ team, client, live }) => {
+        const first = await client.get(team);
+        const observed = first.outcome === "ok"
+            ? observeOnboardWorkflow(first, team, ctx.now().getTime())
+            : null;
+        if (!observed)
+            return first.outcome === "ok" && adopts && Array.isArray(first.rows) && first.rows.length === 0
+                ? { state: "pending", reason: "workflow_mapping_unverified" }
+                : waiting("workflow_mapping_unverified");
+        if (!(await live()))
+            return waiting("workflow_identity_unverified");
+        const last = await client.get(team);
+        const verified = last.outcome === "ok"
+            ? observeOnboardWorkflow(last, team, ctx.now().getTime())
+            : null;
+        if (!verified ||
+            verified.mappingHash !== observed.mappingHash ||
+            verified.mappingRevision !== observed.mappingRevision ||
+            verified.readinessRevision !== observed.readinessRevision)
+            return waiting("workflow_mapping_changed");
+        if (!(await live()))
+            return waiting("workflow_identity_unverified");
+        return {
+            state: "done",
+            evidence: {
+                team,
+                revision: verified.readinessRevision,
+                mappingRevision: verified.mappingRevision,
+                checkedAt: verified.checkedAt,
+                mappingHash: verified.mappingHash,
+                count: verified.mappedSlots,
+                ...(verified.automations
+                    ? { automations: verified.automations }
+                    : {}),
+            },
+        };
+    }, () => input.message?.(`${onboardTeamKey(journal) ?? "This team"} already has every state and label`));
+    if (!adopts)
+        return { check };
+    // A local non-admin never gets here; a 403 means the seat changed after login.
+    const refusal = (reply) => reply.outcome === "unauthorized"
+        ? waiting("workflow_login_refresh_required")
+        : "status" in reply && reply.status === 403
+            ? waiting("workflow_admin_required")
+            : waiting("workflow_unavailable");
+    return {
+        check,
+        act: async (ctx, journal, external) => {
+            // A plan that changed between preview and apply is planned and approved once more.
+            for (let attempt = 0; attempt < 2; attempt++) {
+                let plan, previewedTeam = "";
+                const previewed = await workflowSession(ctx, journal, external, { mode: "preview" }, async ({ team, client }) => {
+                    const reply = await client.adoptPreview(team);
+                    if (reply.outcome !== "ok")
+                        return refusal(reply);
+                    plan = reply;
+                    previewedTeam = team;
+                    return { state: "done" };
+                });
+                if (previewed.state !== "done" || !plan)
+                    return previewed;
+                const key = onboardTeamKey(journal) ?? (label(plan.teamKey) || "this team");
+                const lines = adoptPlanLines(plan);
+                if (!input.confirm)
+                    input.message?.([`Catalyst workflow plan for ${key}:`, ...lines].join("\n"));
+                const approved = input.confirm
+                    ? await input.confirm(key, lines)
+                    : input.yes === true;
+                if (external?.aborted)
+                    return waiting("interrupted");
+                if (!approved)
+                    return waiting("workflow_adoption_declined");
+                const hash = plan.planHash;
+                let stale = false, summary = "";
+                const applied = await workflowSession(ctx, journal, external, { mode: "apply", team: previewedTeam, planHash: hash }, async ({ team, client }) => {
+                    const reply = await client.adoptApply(team, hash);
+                    if (reply.outcome !== "ok") {
+                        stale =
+                            "status" in reply &&
+                                reply.status === 409 &&
+                                reply.error === "plan-stale";
+                        return stale ? waiting("workflow_plan_changed") : refusal(reply);
                     }
-                }
-            })();
-            if (!current())
-                return waiting("workflow_identity_unverified");
-            if (signal.aborted)
-                return waiting(external?.aborted ? "interrupted" : "workflow_unavailable");
-            if (result.state === "done") {
-                input.message?.("The selected team's existing workflow mapping and labels are verified. Setup made no workflow change.");
-                if (!current() || signal.aborted)
-                    return waiting("workflow_identity_unverified");
+                    const created = (rows) => rows.filter((row) => row.outcome === "created").length;
+                    const stages = created(reply.stages), labels = created(reply.labels);
+                    summary = `Applied the Catalyst workflow to ${key}: created ${stages} ${stages === 1 ? "stage" : "stages"} and ${labels} ${labels === 1 ? "label" : "labels"}.`;
+                    return { state: "done" };
+                }, () => input.message?.(summary));
+                // Only the server's own plan-stale answer plans again; a later identity refusal does not.
+                if (!input.confirm || !(stale && applied.reason === "workflow_plan_changed"))
+                    return applied;
             }
-            return result;
+            return waiting("workflow_plan_changed");
         },
     };
 }

package/dist/onboard-workspace.js

@@ -1,6 +1,7 @@
 import { finishOnTheWeb } from "./consent-browser.js";
 import { loadConfig, normalizeBaseUrl } from "./config.js";
 import { pollConsent } from "./onboard-consent.js";
+import { LINEAR_SCOPE, parsePermissions, savedOrigin, } from "./onboard-permissions.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}$/;
@@ -106,7 +107,7 @@ function readFailure(value) {
     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) {
+function observation(body, now, origin) {
     const row = object(body);
     const workspace = object(row?.workspace);
     const credential = object(row?.credential);
@@ -142,8 +143,42 @@ function observation(body, now) {
         return waiting("workspace_status_shape");
     if (verification.state === "unreachable")
         return waiting("workspace_status_unavailable");
+    // CTC-4629: an existing grant short of this version's scopes is re-authorized at the one URL the
+    // cloud names, and only when that URL is this cloud's own OAuth start.
+    const permissions = parsePermissions(row.permissions, {
+        grant: "linear-workspace",
+        action: "reauthorize",
+        label: LINEAR_SCOPE,
+        actorFor: (url) => url.origin === origin &&
+            url.pathname === "/settings/connections" &&
+            url.search === "?reauthorize=linear"
+            ? "workspace-admin"
+            : null,
+    });
+    // The verdict is derived from the verification: outdated only for missing-scope, current only
+    // for connected, and unknown may accompany either.
+    if (permissions === null ||
+        (permissions?.state === "outdated" &&
+            verification.state !== "missing-scope") ||
+        (permissions?.state === "current" && verification.state !== "connected"))
+        return waiting("workspace_status_shape");
+    if (permissions?.state === "outdated")
+        return {
+            state: "waiting",
+            reason: "linear_workspace_scope_outdated",
+            evidence: {
+                provider: "linear",
+                grant: "linear-workspace",
+                granted: permissions.granted.join(", "),
+                missing: permissions.missing.join(", "),
+                url: permissions.url,
+                actor: permissions.actor,
+            },
+        };
     if (!row.connected)
         return { state: "pending" };
+    if (permissions?.state === "unknown")
+        return waiting("linear_workspace_permissions_unverified");
     // A working credential alone cannot prove this account has a bound Linear workspace.
     if (!workspace.bound ||
         typeof workspace.workspaceId !== "string" ||
@@ -154,7 +189,13 @@ function observation(body, now) {
         evidence: {
             provider: "linear",
             workspace: workspace.workspaceId,
+            ...(typeof workspace.workspaceSlug === "string"
+                ? { workspaceSlug: workspace.workspaceSlug }
+                : {}),
             checkedAt: verification.checkedAt,
+            ...(permissions?.state === "current"
+                ? { granted: permissions.granted.join(", ") }
+                : {}),
         },
     };
 }
@@ -216,7 +257,7 @@ export function linearWorkspaceAdapter(options) {
         const failure = readFailure(result);
         return {
             result: failure ??
-                observation("body" in result ? result.body : undefined, ctx.now().getTime()),
+                observation("body" in result ? result.body : undefined, ctx.now().getTime(), savedOrigin(ctx)),
         };
     };
     return {
@@ -232,6 +273,8 @@ export function linearWorkspaceAdapter(options) {
                 return before.result;
             if (before.unsupported)
                 return waiting("cloud_capability_unavailable");
+            if (!options.wait)
+                return waiting("workspace_approval_required");
             const start = await read(ctx, journal, `${STATUS}/start`, timeoutMs, signal);
             if ("status" in start && [404, 405].includes(start.status))
                 return waiting("cloud_capability_unavailable");
@@ -251,7 +294,6 @@ export function linearWorkspaceAdapter(options) {
                 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.
             let browserUnavailable = false;
             try {
@@ -276,7 +318,10 @@ export function linearWorkspaceAdapter(options) {
                             outcome: "waiting",
                             reason: "cloud_capability_unavailable",
                         };
-                    if (latest.reason === "workspace_login_refresh_required")
+                    // An outdated grant is re-authorized at its own URL; polling longer cannot finish it.
+                    if (latest.reason === "workspace_login_refresh_required" ||
+                        latest.reason === "linear_workspace_scope_outdated" ||
+                        latest.reason === "linear_workspace_permissions_unverified")
                         return { outcome: "waiting", reason: latest.reason };
                     if (latest.state === "done")
                         return { outcome: "connected" };
@@ -290,7 +335,9 @@ export function linearWorkspaceAdapter(options) {
             const result = options.wait
                 ? await options.wait("Waiting for workspace approval", run)
                 : await run();
-            if (result.state === "done")
+            if (result.state === "done" ||
+                latest.reason === "linear_workspace_scope_outdated" ||
+                latest.reason === "linear_workspace_permissions_unverified")
                 return latest;
             return browserUnavailable && result.reason === "consent_timeout"
                 ? waiting("workspace_browser_unavailable")