@catalyst-cloud/cli 0.14.9 → 0.15.0

package/dist/onboard-next.js

@@ -1,9 +1,12 @@
+import { nativeEgressInstallCommands } from "./onboard-runner-egress.js";
 import { loadConfig, normalizeBaseUrl } from "./config.js";
+import { githubInstallationPage } from "./onboard-permissions.js";
 /** What a person reads for a step that is not done. Each line ends in an action they can take. */
 const REASONS = {
     account_identity_unverified: "Your login changed while coding accounts were checked. Run catalyst onboard again to verify your person and workspace.",
     account_inventory_unavailable: "Coding accounts could not be read. Run catalyst onboard again to retry.",
     account_inventory_unverified: "The server did not return a fresh supported coding-account list. Run catalyst onboard after the server update.",
+    coding_account_not_found: "The coding account named by --coding-account is not enrolled in this workspace. Run catalyst accounts to list the slots, then run catalyst onboard with one of them.",
     account_validation_admin_required: "An administrator must check the workspace's coding-account access.",
     account_login_refresh_required: "Renew your login with catalyst login, then run catalyst onboard.",
     account_validation_unavailable: "The provider check could not finish. Run catalyst onboard again to retry.",
@@ -32,6 +35,7 @@ const REASONS = {
     github_installation_admin_required: "A workspace owner or administrator approves the GitHub App installation.",
     github_installation_login_refresh_required: "Renew your login with catalyst login, then run catalyst onboard to resume.",
     github_installation_browser_unavailable: "This computer could not open a browser. Install the GitHub App from this workspace’s Integrations page in your browser, then run catalyst onboard to resume.",
+    skills_install_unverified: "The Catalyst skills are not in this user's skills folder. Run catalyst install, then run catalyst onboard.",
     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.",
@@ -54,6 +58,10 @@ const REASONS = {
     project_login_refresh_required: "Renew your login with catalyst onboard, then review the plan before creating this project.",
     project_create_unverified: "Project creation could not be confirmed. Run catalyst onboard to check for the project before trying again.",
     team_read_login_refresh_required: "Renew your login with catalyst login, then run catalyst onboard to resume.",
+    team_create_unavailable: "The Linear team could not be created, and nothing was created. Run catalyst onboard to try again, or create the team in Linear and pick it.",
+    team_create_unverified: "Setup could not confirm whether the Linear team was created. Check Linear for it before creating it again.",
+    team_create_grant_required: "Your own Linear connection is missing or has lapsed. Reconnect it in Settings → Connected accounts, then run catalyst onboard. Nothing was created.",
+    team_create_identity_unverified: "Your login changed while setup was creating a team. Resume with the original workspace and person.",
     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.",
@@ -71,13 +79,62 @@ const REASONS = {
     settings_draft_storage_timeout: "Keeping your settings draft took too long. Run catalyst onboard to retry.",
     settings_approval_unverified: "Settings still need review and approval; kept drafts do not count. Settings are optional for a first ticket. To finish them later, run catalyst onboard from the repository's checkout.",
     repository_selection_unverified: "Your selected repositories could not be verified. Run catalyst onboard --repo <owner/name> to choose again.",
+    workflow_adoption_declined: "Skipped for now. Run catalyst onboard to review the changes again.",
     workflow_identity_unverified: "Setup could not confirm the signed-in workspace, person or role for this team. Run catalyst onboard again as a workspace owner or administrator.",
     workflow_login_refresh_required: "Renew your login with catalyst login, then run catalyst onboard.",
     workflow_mapping_changed: "The team's workflow changed while setup checked it. Run catalyst onboard again.",
+    workflow_admin_required: "Applying the Catalyst workflow needs a workspace owner or administrator. Ask one to run catalyst onboard for this team.",
+    workflow_plan_changed: "The team's Linear workflow changed while setup was applying it. Run catalyst onboard again to see the new plan.",
+    verification_pending: "Setup made the change but could not confirm it yet. Run catalyst onboard again to check.",
+    automations_compatible: "Nothing to change.",
     workflow_unavailable: "Setup could not read the team's workflow. Run catalyst onboard again to retry.",
     capacity_admission_unverified: "No runner is allowed to take work for this workspace yet. Enroll a self-hosted runner host, or ask Catalyst to enable cloud runners for it. Then run catalyst onboard.",
     capacity_currently_full: "Every runner slot for this repository is in use. Run catalyst onboard again after current work finishes.",
     capacity_unavailable: "Setup could not read runner capacity. Run catalyst onboard again to retry.",
+    runner_not_selected: "This setup does not start a runner on this machine. To start one, run catalyst onboard --runner.",
+    runner_docker_missing: "A runner needs Docker with Compose (Docker Desktop, OrbStack or Docker Engine), and setup could not reach it. Start Docker, or install it, then run catalyst onboard --runner.",
+    runner_identity_unverified: "A workspace owner or administrator enrolls a runner. Sign in as one with catalyst login, then run catalyst onboard --runner.",
+    runner_context_unverified: "Setup could not confirm the selected Linear team. Run catalyst onboard again.",
+    runner_directory_unavailable: "Setup could not prepare the runner folder in Catalyst's state directory. Check its permissions, then run catalyst onboard again.",
+    runner_image_unpinned: "Each runner image must be pinned as name@sha256:<digest>, and Catalyst's runner image is not public yet. Ask Catalyst support to load it here and set CATALYST_RUNNER_IMAGE to the reference they give you. A CATALYST_SUPERVISOR_IMAGE or CATALYST_WATCHDOG_IMAGE override takes the same form. Then run catalyst onboard --runner.",
+    runner_image_emulated: "A runner image here is built for another processor, and Catalyst does not run work under emulation. Ask Catalyst support for the image built for this processor, then run catalyst onboard again.",
+    runner_session_network_misshaped: "A Docker network named catalyst-session-v1 exists with the wrong settings. Remove it with docker network rm catalyst-session-v1 when nothing uses it, then run catalyst onboard again.",
+    runner_session_network_failed: "Docker could not create the catalyst-session-v1 network. Check that Docker is running, then run catalyst onboard again.",
+    runner_docker_socket_unreadable: "Setup could not read the group of the Docker socket at /var/run/docker.sock. Check that Docker is running, then run catalyst onboard again.",
+    runner_engine_unsupported: "Runner setup needs local Docker Desktop or OrbStack on Mac, or native Linux Docker at /var/run/docker.sock. Select a supported local engine, then run catalyst onboard --runner.",
+    runner_enrollment_unavailable: "Setup could not read this workspace's runner hosts. Run catalyst onboard again to retry.",
+    runner_enrolled_for_other_team: "This runner is enrolled for another Linear team. Keep using that team, or ask your administrator to revoke the old enrollment before setting up this machine for the selected team.",
+    runner_enrollment_stale: "This machine still holds the credential of a runner enrollment that was revoked. Stop the runner with docker compose -p catalyst-host down, remove the credential with docker volume rm catalyst-host_host-credential (this also removes the organization key), then run catalyst onboard --runner.",
+    runner_login_refresh_required: "Renew your login with catalyst login, then run catalyst onboard.",
+    runner_join_token_unavailable: "Catalyst did not issue a join token for this machine. Run catalyst onboard again to retry.",
+    runner_session_network_unavailable: "Docker could not inspect the runner session network. Check engine access and run the same setup command again. Setup has not created a replacement network.",
+    runner_capability_unavailable: "Catalyst could not read runner setup support. Run the same setup command again.",
+    runner_capability_unverified: "Catalyst returned runner setup information this CLI cannot verify. Ask Catalyst support to check the server contract, then run the same setup command.",
+    runner_org_key_journal_unavailable: "Setup cannot safely use its saved runner credential request. Keep the request file and ask Catalyst support to inspect it.",
+    runner_org_key_recovery_required: "The previous runner key request may already have issued a key. Ask your workspace administrator to revoke that saved request and explicitly restart it. Setup will not mint another key automatically.",
+    runner_org_key_reconciliation_pending: "The previous runner key request is still uncertain. Run the same setup command to check its saved request again.",
+    runner_org_key_response_unverified: "Setup could not verify the runner key's tenant and scopes. Ask your workspace administrator to inspect the saved request.",
+    runner_cloud_unavailable: "Catalyst did not complete the runner setup request. Run the same setup command to check its saved request before continuing.",
+    runner_admission_disabled: "The selected team does not admit runner work. Run the same setup command with runner selection to explicitly enable its restricted admission policy.",
+    runner_org_key_file_invalid: "CATALYST_RUNNER_ORG_KEY_FILE must name a regular file that holds one organization key. Fix the file, then run catalyst onboard again.",
+    runner_org_key_invalid: "The runner account key is invalid, belongs to another workspace, or lacks mirror read, write and feed permissions. Supply a scoped key for this workspace with CATALYST_RUNNER_ORG_KEY_FILE, then run catalyst onboard --runner.",
+    runner_org_key_unavailable: "The runner account key could not be checked with Catalyst. Run catalyst onboard --runner to retry.",
+    runner_org_key_write_failed: "Setup could not place the organization key on the runner. Check that Docker is running, then run catalyst onboard again.",
+    runner_compose_failed: "Docker Compose could not start the runner. Run docker compose -p catalyst-host logs to see why, then run catalyst onboard again.",
+    runner_compose_not_running: "The runner's supervisor is not running. Run docker compose -p catalyst-host logs supervisor to see why, then run catalyst onboard again.",
+    runner_enrollment_unverified: "The runner started but has not enrolled yet. Run docker compose -p catalyst-host logs supervisor to see why, or run catalyst onboard again in a minute.",
+    runner_needs_runner_flag: "This machine was set up to run Catalyst's work, but its runner is not running or not enrolled. To bring it up, run catalyst onboard --runner.",
+    runner_capability_pending: "The runner enrolled but has not reported its capacity yet. Run catalyst onboard again in a minute.",
+    runner_admission_unverified: "Setup could not read whether the team's pool admits runner hosts. Run catalyst onboard again to retry.",
+    github_app_permissions_outdated: "GitHub App needs updated permissions. An organization owner on GitHub accepts the pending request on the App's installation page, then run catalyst onboard.",
+    github_app_repository_missing: "The GitHub App installation cannot reach a repository a project registers. An organization owner on GitHub adds it under the installation's Repository access, then run catalyst onboard.",
+    github_app_repository_not_installed: "No GitHub App installation can reach a repository a project registers. A workspace owner or administrator installs the GitHub App on its owner: run catalyst onboard.",
+    github_app_permissions_unverified: "The GitHub App installation works, but its granted permissions could not be checked. Run catalyst onboard to try again.",
+    github_app_repository_access_unverified: "Whether the GitHub App reaches every registered repository could not be checked. Run catalyst onboard to try again.",
+    linear_workspace_scope_outdated: "The workspace's Linear connection (the Catalyst app) is missing scopes this version needs. A workspace owner or administrator re-authorizes it from the workspace's Integrations page, then run catalyst onboard.",
+    linear_workspace_permissions_unverified: "The workspace's Linear connection works, but its granted scopes could not be checked. Run catalyst onboard to try again.",
+    linear_personal_scope_outdated: "Your personal Linear connection is missing scopes this version needs. Re-authorize it from Connected accounts, then run catalyst onboard.",
+    personal_permissions_unverified: "Your personal connection's granted scopes could not be checked. Run catalyst onboard to try again.",
     housekeeping_service_unverified: "The daily update needs a user service manager, launchd on macOS or systemd --user on Linux. Setup cannot schedule it on this computer. It is optional, and work does not depend on it.",
 };
 /** The saved login's web address, or nothing when the config is missing, unreadable or not http(s). */
@@ -115,17 +172,145 @@ export function onboardTeamKey(journal) {
         ? key
         : undefined;
 }
+/** Receipt evidence printed inside a sentence: names, scopes and permission labels only. */
+function evidenceText(value) {
+    return typeof value === "string" &&
+        /^[A-Za-z0-9 ._:;/(),-]{1,2000}$/.test(value)
+        ? value
+        : undefined;
+}
+const LINEAR_START = {
+    linear_workspace_scope_outdated: "/settings/connections",
+    linear_personal_scope_outdated: "/connect/linear/personal/start",
+};
+/** A receipt URL, printed only when it is the page this reason's action lives on: the exact
+ * installation's page on github.com, or this cloud's own OAuth start for the grant in question. */
+function actionUrl(step, baseUrl) {
+    const href = webUrl(step.evidence?.url);
+    if (!href)
+        return undefined;
+    const url = new URL(href);
+    if (url.protocol !== "https:" ||
+        url.hash ||
+        (url.search &&
+            !(step.reason === "linear_workspace_scope_outdated" &&
+                url.pathname === "/settings/connections" &&
+                url.search === "?reauthorize=linear")))
+        return undefined;
+    const evidence = step.evidence ?? {};
+    if (step.reason === "github_app_permissions_outdated" ||
+        step.reason === "github_app_repository_missing")
+        return githubInstallationPage(url, typeof evidence.installation === "string" ? evidence.installation : "", typeof evidence.org === "string" ? evidence.org : null, step.reason === "github_app_permissions_outdated")
+            ? href
+            : undefined;
+    const base = baseUrl ? webUrl(baseUrl) : undefined;
+    return base &&
+        new URL(base).origin === url.origin &&
+        url.pathname === LINEAR_START[step.reason ?? ""] &&
+        (step.reason !== "linear_workspace_scope_outdated" ||
+            url.search === "?reauthorize=linear")
+        ? href
+        : undefined;
+}
+/** CTC-4629: the outdated-connection lines, built from the evidence the adapters recorded. */
+function permissionText(step, baseUrl) {
+    const evidence = step.evidence ?? {};
+    const url = actionUrl(step, baseUrl);
+    const missing = evidenceText(evidence.missing);
+    const org = evidenceText(evidence.org);
+    const repository = evidenceText(evidence.repository);
+    const github = evidence.actor === "github-account-owner"
+        ? `The owner of the ${org ?? "installing"} GitHub account`
+        : "An organization owner on GitHub";
+    switch (step.reason) {
+        case "github_app_permissions_outdated":
+            if (!url)
+                return undefined;
+            return `GitHub App needs updated permissions${org ? ` on ${org}` : ""}${missing ? `: ${missing}` : ""}. ${github} reviews and accepts the request at ${url}, then run catalyst onboard.`;
+        case "github_app_repository_missing":
+            if (!url || !repository)
+                return undefined;
+            return `The GitHub App installation${org ? ` on ${org}` : ""} cannot reach ${repository}, which a project registers. ${github} adds it under Repository access at ${url}, then run catalyst onboard.`;
+        case "github_app_repository_not_installed":
+            if (!repository)
+                return undefined;
+            return `No GitHub App installation can reach ${repository}, which a project registers. A workspace owner or administrator installs the GitHub App on ${org ?? repository.split("/")[0]}: run catalyst onboard.`;
+        case "linear_workspace_scope_outdated":
+            if (!url)
+                return undefined;
+            return `The workspace's Linear connection (the Catalyst app) is missing scopes this version needs${missing ? `: ${missing}` : ""}. A workspace owner or administrator re-authorizes it at ${url}, then run catalyst onboard.`;
+        case "linear_personal_scope_outdated":
+            if (!url)
+                return undefined;
+            return `Your personal Linear connection is missing scopes this version needs${missing ? `: ${missing}` : ""}. Re-authorize it at ${url}, then run catalyst onboard.`;
+    }
+    return undefined;
+}
+/** A done step's detail line: what a connection was granted, when the check recorded it. */
+export function onboardStepDetail(step) {
+    const value = step.state === "done" ? step.evidence?.granted : undefined;
+    const granted = typeof value === "string" &&
+        value.length <= 512_000 &&
+        /^[A-Za-z0-9 ._:;/(),-]+$/.test(value)
+        ? value.length <= 2_000
+            ? value
+            : `${value.slice(0, 1_950)} (more permissions in the setup record)`
+        : undefined;
+    return granted ? `granted ${granted}` : undefined;
+}
 /** One step's next action. `waitsFor` names the unfinished step a prerequisite wait is blocked on. */
 export function onboardReasonText(step, context = {}) {
     const reason = step.reason ?? "";
+    if ([
+        "workspace_approval_required",
+        "personal_approval_required",
+        "github_installation_approval_required",
+    ].includes(reason)) {
+        const path = reason === "workspace_approval_required"
+            ? "/settings/connections?connect=linear"
+            : reason === "github_installation_approval_required"
+                ? "/settings/connections?install=github"
+                : `/settings/connected-accounts?connect=${step.id === "github.personal" ? "github" : "linear"}`;
+        const where = context.baseUrl
+            ? `${normalizeBaseUrl(context.baseUrl)}${path}`
+            : "Catalyst settings";
+        return `Open ${where} and approve this connection, then run catalyst onboard.`;
+    }
     if (reason === "workflow_mapping_unverified")
         return `This team's workflow mapping is not verified yet. Run catalyst team adopt ${onboardTeamKey(context.journal) ?? "<TEAM KEY>"} to preview the adoption plan. Run it again with the --yes --plan-hash value it prints. Then run catalyst onboard.`;
+    if (reason === "team_created_not_adopted" ||
+        reason === "team_create_unverified") {
+        const key = step.evidence?.teamKey;
+        const team = typeof key === "string" && /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/.test(key)
+            ? key
+            : undefined;
+        const adopt = (key) => `Run catalyst team adopt ${key} to preview the adoption plan. Run it again with the --yes --plan-hash value it prints. Then run catalyst onboard.`;
+        if (reason === "team_created_not_adopted")
+            return `Linear team ${team ?? "<TEAM KEY>"} was created, but Catalyst's workflow is not set up on it yet. ${adopt(team ?? "<TEAM KEY>")}`;
+        if (team)
+            return `Setup could not confirm whether Linear created the team ${team}. Check Linear for it. If it is there: ${adopt(team)} If it is not, run catalyst onboard to create it again.`;
+    }
     if (reason === "account_enrollment_required") {
         const where = context.baseUrl
             ? `at ${normalizeBaseUrl(context.baseUrl)}/settings/coding-accounts, the Settings → AI accounts page`
             : "in the web app on the Settings → AI accounts page";
         return `No coding account is enrolled. A workspace owner or administrator adds one ${where}. A Claude account needs its email and the token printed by \`claude setup-token\`. Then run catalyst onboard.`;
     }
+    if (reason === "automation_management_unavailable") {
+        const conflicts = typeof step.evidence?.automations === "string" &&
+            /^(?:open|review|ready|merge)(?:,(?:open|review|ready|merge))*$/.test(step.evidence.automations);
+        if (!conflicts)
+            return "could not read them; checked again before work starts";
+        const key = onboardTeamKey(context.journal);
+        const workspace = context.journal?.steps.find((row) => row.id === "linear.workspace" && row.state === "done");
+        const slug = workspace?.evidence?.workspaceSlug;
+        if (key &&
+            /^[A-Za-z0-9][A-Za-z0-9-]*$/.test(key) &&
+            typeof slug === "string" &&
+            /^[A-Za-z0-9][A-Za-z0-9-]*$/.test(slug))
+            return `Open https://linear.app/${slug}/settings/teams/${key}/workflow and set each pull request automation to No action.`;
+        return `Open your ${key ? `${key} team's` : "team's"} workflow settings in Linear and set each pull request automation to No action.`;
+    }
     if (reason === "cloud_capability_unavailable") {
         // The capability guard records the web page in evidence.path only when it printed it.
         const page = webUrl(step.evidence?.path);
@@ -133,7 +318,37 @@ export function onboardReasonText(step, context = {}) {
             ? `This setup step is not available on this server yet. Continue in the web app at ${page}, then run catalyst onboard.`
             : "This setup step is not available on this server yet. Run catalyst onboard after the server update.";
     }
+    if (reason === "runner_native_egress_setup_required") {
+        const commands = nativeEgressInstallCommands();
+        return "Native Linux needs a root-managed session egress producer before the runner can take work. Its elevated installation creates the isolated session network and private-range and host-isolation nftables rules. Review and authorize this separately; setup has not run it. It requires systemd, python3, Docker and nftables. " + (commands ? "Install the verified bundled artifacts, then run the same setup command:\n" + commands : "Setup could not verify its bundled artifacts. Reinstall the CLI before authorizing installation.");
+    }
+    if (reason === "runner_images_unavailable") {
+        const image = step.evidence?.image;
+        const named = typeof image === "string" &&
+            /^[a-z0-9][a-z0-9._:/-]{0,255}@sha256:[0-9a-f]{64}$/.test(image)
+            ? ` ${image}`
+            : "";
+        return `This machine does not have the Catalyst image${named}, and its pull did not complete. Check network access and run the same setup command to retry the anonymous pull.`;
+    }
+    if (reason === "runner_org_key_missing") {
+        const where = context.baseUrl
+            ? `at ${normalizeBaseUrl(context.baseUrl)}/settings/account-keys`
+            : "on the web app's Account API keys page";
+        return `The runner is enrolled, but it takes no work without an organization key. A workspace owner or administrator creates one with the mirror:read, mirror:write and mirror:feed scopes ${where} and saves it in a file only they can read. Then run catalyst onboard --runner with CATALYST_RUNNER_ORG_KEY_FILE set to that file.`;
+    }
+    if (reason === "runner_host_not_ready") {
+        const failing = step.evidence?.failing;
+        const checks = typeof failing === "string" && /^[a-z0-9.,_-]{1,500}$/.test(failing)
+            ? `: ${failing.split(",").join(", ")}`
+            : "";
+        return `The runner is enrolled but its readiness checks fail${checks}. Run docker compose -p catalyst-host logs supervisor for the remedy, then run catalyst onboard again.`;
+    }
+    if (reason === "runner_admission_operator")
+        return `The admission policy for team ${onboardTeamKey(context.journal) ?? "<TEAM KEY>"} needs a Catalyst operator to check it. Setup changes only restricted admission and preserves existing policy fields. Ask Catalyst support to confirm a compatible policy, then run the same setup command.`;
     if (reason === "prerequisite_not_ready" && context.waitsFor)
         return `Runs after "${context.waitsFor}".`;
+    const permission = permissionText(step, context.baseUrl);
+    if (permission)
+        return permission;
     return REASONS[reason] ?? reason.replaceAll("_", " ");
 }

package/dist/onboard-permissions.js

@@ -0,0 +1,100 @@
+/** CTC-4629: the cloud's typed permissions verdict on an existing connection, verified before use.
+ * A verdict that fails any check is a shape error, so no unverified URL is ever printed. */
+import { loadConfig, normalizeBaseUrl } from "./config.js";
+/** The saved login's origin, which a re-authorize URL must share; an unreadable one matches none. */
+export function savedOrigin(ctx) {
+    try {
+        const cfg = loadConfig(ctx.home);
+        return cfg ? new URL(normalizeBaseUrl(cfg.baseUrl)).origin : "";
+    }
+    catch {
+        return "";
+    }
+}
+const object = (v) => v !== null && typeof v === "object" && !Array.isArray(v)
+    ? v
+    : null;
+export const LINEAR_SCOPE = /^[A-Za-z][A-Za-z0-9:_-]{0,63}$/;
+export const GITHUB_PERMISSION = /^[A-Za-z0-9_-]{1,80} \((?:read|write|admin)\)$/;
+const UNKNOWN = new Set([
+    "not-run",
+    "unreachable",
+    "expired-or-revoked",
+    "not-connected",
+    "grant-unreadable",
+]);
+const labels = (value, label, min = 0) => Array.isArray(value) &&
+    value.length >= min &&
+    value.length <= 128 &&
+    value.every((item) => typeof item === "string" && label.test(item))
+    ? value
+    : null;
+/** `undefined` when the cloud sent no verdict (an older cloud); `null` when it sent a bad one. */
+export function parsePermissions(value, expected) {
+    if (value === undefined)
+        return undefined;
+    const row = object(value);
+    if (!row || row.grant !== expected.grant)
+        return null;
+    if (row.state === "unknown")
+        return typeof row.reason === "string" && UNKNOWN.has(row.reason)
+            ? { state: "unknown", reason: row.reason }
+            : null;
+    const granted = labels(row.granted, expected.label);
+    if (!granted)
+        return null;
+    if (row.state === "current")
+        return { state: "current", granted };
+    const missing = labels(row.missing, expected.label, 1);
+    const action = object(row.action);
+    if (row.state !== "outdated" ||
+        !missing ||
+        !action ||
+        action.kind !== expected.action ||
+        typeof action.url !== "string" ||
+        action.url.length > 2048 ||
+        typeof action.actor !== "string")
+        return null;
+    let url;
+    try {
+        url = new URL(action.url);
+    }
+    catch {
+        return null;
+    }
+    if (url.protocol !== "https:" ||
+        url.username ||
+        url.password ||
+        (url.search &&
+            !(expected.grant === "linear-workspace" &&
+                url.pathname === "/settings/connections" &&
+                url.search === "?reauthorize=linear")) ||
+        url.hash ||
+        expected.actorFor(url) !== action.actor)
+        return null;
+    return {
+        state: "outdated",
+        granted,
+        missing,
+        url: url.toString(),
+        actor: action.actor,
+    };
+}
+const GITHUB_INSTALLATION_PAGE = /^\/(?:organizations\/([A-Za-z0-9][A-Za-z0-9-]{0,38})\/)?settings\/installations\/([0-9]{1,20})(\/permissions\/update)?$/;
+/** github.com's page for one installation: its settings, or its permission-request review. The
+ * actor is GitHub's: an organization owner, or the owner of a personal account. */
+export function githubInstallationPage(url, installationId, org, review) {
+    const match = GITHUB_INSTALLATION_PAGE.exec(url.pathname);
+    if (url.origin !== "https://github.com" ||
+        !match ||
+        match[2] !== installationId ||
+        Boolean(match[3]) !== review)
+        return null;
+    const login = match[1] ?? null;
+    if (login && org && login.toLowerCase() !== org.toLowerCase())
+        return null;
+    return {
+        actor: login ? "github-org-admin" : "github-account-owner",
+        login,
+    };
+}

package/dist/onboard-personal.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 object = (value) => value !== null && typeof value === "object" && !Array.isArray(value)
     ? value
     : null;
@@ -160,15 +161,47 @@ export function personalConsentAdapter(options) {
             (body.reason !== undefined &&
                 (body.connected || body.reason !== "lapsed")))
             return { state: "failed", reason: "personal_status_shape" };
-        return body.connected
-            ? {
-                state: "done",
+        if (!body.connected)
+            return { state: "pending" };
+        // CTC-4629: only a Linear grant carries scopes; GitHub's are the App's, checked at installation.
+        const permissions = options.provider === "linear"
+            ? parsePermissions(body.permissions, {
+                grant: "linear-personal",
+                action: "reauthorize",
+                label: LINEAR_SCOPE,
+                actorFor: (url) => url.origin === savedOrigin(ctx) &&
+                    url.pathname === "/connect/linear/personal/start"
+                    ? "member"
+                    : null,
+            })
+            : undefined;
+        if (permissions === null)
+            return { state: "failed", reason: "personal_status_shape" };
+        if (permissions?.state === "unknown")
+            return waiting("personal_permissions_unverified");
+        if (permissions?.state === "outdated")
+            return {
+                state: "waiting",
+                reason: "linear_personal_scope_outdated",
                 evidence: {
-                    provider: options.provider,
-                    checkedAt: ctx.now().getTime(),
+                    provider: "linear",
+                    grant: "linear-personal",
+                    granted: permissions.granted.join(", "),
+                    missing: permissions.missing.join(", "),
+                    url: permissions.url,
+                    actor: permissions.actor,
                 },
-            }
-            : { state: "pending" };
+            };
+        return {
+            state: "done",
+            evidence: {
+                provider: options.provider,
+                checkedAt: ctx.now().getTime(),
+                ...(permissions?.state === "current"
+                    ? { granted: permissions.granted.join(", ") }
+                    : {}),
+            },
+        };
     };
     return {
         check: inspect,
@@ -181,6 +214,8 @@ export function personalConsentAdapter(options) {
             const before = await inspect(ctx, journal, signal);
             if (before.state !== "pending")
                 return before;
+            if (!options.wait)
+                return waiting("personal_approval_required");
             const start = await read(ctx, journal, `/connect/${options.provider}/personal/start`, timeout, signal);
             if ("status" in start &&
                 start.status === 409 &&
@@ -197,7 +232,6 @@ export function personalConsentAdapter(options) {
             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.
             let browserUnavailable = false;
             try {
@@ -218,7 +252,9 @@ export function personalConsentAdapter(options) {
                     latest = await inspect(ctx, journal, pollSignal);
                     if (latest.reason === "cloud_capability_unavailable")
                         return { outcome: "waiting", reason: latest.reason };
-                    if (latest.reason === "personal_login_refresh_required")
+                    // An outdated grant is re-authorized at its own URL; polling longer cannot finish it.
+                    if (latest.reason === "personal_login_refresh_required" ||
+                        (latest.reason === "linear_personal_scope_outdated" || latest.reason === "personal_permissions_unverified"))
                         return { outcome: "waiting", reason: latest.reason };
                     if (latest.state === "done")
                         return { outcome: "connected" };
@@ -232,7 +268,7 @@ export function personalConsentAdapter(options) {
             const result = options.wait
                 ? await options.wait(`Waiting for your ${name} approval`, run)
                 : await run();
-            if (result.state === "done")
+            if (result.state === "done" || (latest.reason === "linear_personal_scope_outdated" || latest.reason === "personal_permissions_unverified"))
                 return latest;
             return browserUnavailable && result.reason === "consent_timeout"
                 ? waiting("personal_browser_unavailable")