@catalyst-cloud/cli 0.14.7 → 0.14.8

package/dist/onboard-ui.js

@@ -1,5 +1,5 @@
 import { createOnboardProgress, } from "./onboard-progress.js";
-import { ONBOARD_STEPS, ONBOARD_TITLES, onboardIdentityLines, } from "./onboard.js";
+import { ONBOARD_STEPS, ONBOARD_TITLES, onboardIdentityLines, onboardNextActions, onboardReadyForWork, onboardStepAction, } from "./onboard.js";
 export function shouldUseOnboardUi(args, stdoutTty) {
     return (stdoutTty &&
         !args.json &&
@@ -194,81 +194,9 @@ export function createClackOnboardUi(prompts, streams, deps = {}) {
             }
             start(ONBOARD_TITLES[id]);
         },
-        stepEnd(step) {
+        stepEnd(step, journal) {
             stop();
-            const reasons = {
-                account_enrollment_required: "No coding account is enrolled. An administrator can add one in the workspace's coding-account settings, then run catalyst onboard again.",
-                account_identity_unverified: "Your login changed while coding accounts were checked. Run catalyst onboard again to verify your person and workspace.",
-                account_inventory_unavailable: "Coding accounts could not be read. Run catalyst onboard again to retry.",
-                account_inventory_unverified: "The server did not return a fresh supported coding-account list. Run catalyst onboard after the server update.",
-                account_validation_admin_required: "An administrator must check the workspace's coding-account access.",
-                account_login_refresh_required: "Renew your login with catalyst login, then run catalyst onboard.",
-                account_validation_unavailable: "The provider check could not finish. Run catalyst onboard again to retry.",
-                account_validation_unverified: "The server did not return a fresh provider check. Run catalyst onboard after the server update.",
-                account_provider_access_unverified: "Coding-account provider access is not freshly verified. Check the account in the workspace's coding-account settings, then resume setup.",
-                codex_provider_access_unverified: "Codex credentials are stored, but provider access is not freshly verified. Setup did not refresh or rotate the Codex login.",
-                account_provider_walled: "Claude's usage limit is spent for now. Check the account's reset time, then run catalyst onboard again.",
-                account_provider_rejected: "Claude refused the stored login. Replace it in the workspace's coding-account settings, then resume setup.",
-                personal_consent_handoff: "The browser approval link could not be verified. Run catalyst onboard to try again.",
-                personal_identity_refused: "Your current login no longer matches this setup. Resume with the original workspace and person.",
-                personal_login_refresh_required: "Renew your login with catalyst login, then run catalyst onboard to resume.",
-                onboard_login_refresh_required: "Renew your login with catalyst login, then run catalyst onboard to resume.",
-                personal_status_unavailable: "Your personal connection could not be checked. Run catalyst onboard to try again.",
-                personal_browser_unavailable: "The browser could not open. Run catalyst onboard to try again.",
-                cloud_capability_unavailable: "This setup step is not available on this server yet. Use the web app link shown above, then resume after the server update.",
-                onboarding_capability_unavailable: "The server's setup capabilities could not be checked. Run catalyst onboard to try again.",
-                onboarding_capability_identity_unverified: "The server's setup capabilities belong to another login or workspace. Sign in to the original workspace to resume.",
-                onboarding_capability_login_refresh_required: "Your login needs a refresh before setup capabilities can be checked. Run catalyst login, then catalyst onboard.",
-                workspace_consent_refused: "The server did not accept this login for Linear workspace setup. Sign in again or ask your workspace administrator.",
-                github_installation_status_unavailable: "Your GitHub App installation could not be checked. Run catalyst onboard to try again.",
-                github_installation_status_shape: "The server returned a GitHub installation result that could not be verified.",
-                github_installation_consent_handoff: "The GitHub installation approval link could not be verified. Run catalyst onboard to try again.",
-                github_installation_consent_refused: "The server did not accept this login for GitHub App setup. Sign in again or ask your workspace administrator.",
-                github_installation_identity_refused: "GitHub setup belongs to another login or workspace. Sign in to the original workspace to resume.",
-                github_installation_admin_required: "A workspace owner or administrator approves the GitHub App installation.",
-                github_installation_login_refresh_required: "Your login needs a refresh. Run catalyst onboard to resume.",
-                github_installation_browser_unavailable: "The GitHub App approval page could not be opened. Use your workspace's Connections page, then resume.",
-                step_not_available_in_this_release: "This setup step is not available yet.",
-                prerequisite_not_ready: "Waiting for an earlier setup step.",
-                local_sync_not_selected: "Using cloud reads. Local sync was not selected.",
-                local_sync_capability_unavailable: "Local sync was selected but could not be verified.",
-                member_scope: "Your workspace administrator handles this step.",
-                onboarding_checks_pending: "Some required checks are still unverified.",
-                interrupted: "Setup paused. Run the same command to resume.",
-                signin_timeout: "Sign-in timed out. Run catalyst onboard to try again.",
-                linear_workspace_unverified: "Your Linear workspace connection could not be verified.",
-                team_inventory_empty: "No existing Linear teams could be verified.",
-                team_inventory_shape: "The cloud returned a team list that could not be verified.",
-                team_read_unavailable: "Your existing Linear teams could not be read. Run catalyst onboard to try again.",
-                team_read_identity_unverified: "Your login changed while setup was reading this workspace. Resume with the original workspace and person.",
-                project_identity_unverified: "Your login changed while setup was checking this project. Resume with the original workspace and person.",
-                project_options_unavailable: "Available teams and repositories could not be checked. Run catalyst onboard to try again.",
-                project_provider_inventory_unavailable: "Linear or GitHub access could not be verified. Check this workspace's connections, then resume.",
-                project_options_unverified: "The server returned a team or repository list that could not be verified.",
-                project_registration_visibility_pending: "Your project exists, but its repository binding is not visible yet. Run catalyst onboard to check again.",
-                project_binding_conflict: "This team or repository is already bound to a project. Ask your workspace administrator to check its binding, then resume.",
-                project_login_refresh_required: "Renew your login with catalyst onboard, then review the plan before creating this project.",
-                project_create_unverified: "Project creation could not be confirmed. Run catalyst onboard to check for the project before trying again.",
-                team_read_login_refresh_required: "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.",
-                settings_review_timeout: "The settings review timed out. Run catalyst onboard to resume.",
-                settings_checkout_unverified: "A selected repository's local checkout or full settings file could not be verified. Resume from its checkout.",
-                settings_draft_storage_unavailable: "A private settings draft could not be kept. Run catalyst onboard to retry.",
-                settings_draft_storage_timeout: "Keeping your settings draft took too long. Run catalyst onboard to retry.",
-                settings_approval_unverified: "Settings still need review and approval. Kept drafts and local validation do not approve them.",
-                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 text = `${ONBOARD_TITLES[step.id]}${step.reason ? `: ${onboardStepAction(journal, step, deps.baseUrl?.())}` : ""}`;
             const kind = step.state === "done"
                 ? "info"
                 : step.state === "failed"
@@ -283,12 +211,22 @@ export function createClackOnboardUi(prompts, streams, deps = {}) {
         message,
         finish(journal, only) {
             stop();
-            let text = "Setup still needs checks. Run catalyst onboard to resume.";
+            let text = [
+                "Setup still needs these steps:",
+                ...onboardNextActions(journal, deps.baseUrl?.(), only),
+                "resume: catalyst onboard",
+            ].join("\n");
             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 (onboardReadyForWork(journal, only))
+                text = [
+                    "Ready for work.",
+                    "Next, when you want:",
+                    ...onboardNextActions(journal, deps.baseUrl?.()),
+                ].join("\n");
             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 });

package/dist/onboard-workspace.js

@@ -1,3 +1,4 @@
+import { finishOnTheWeb } from "./consent-browser.js";
 import { loadConfig, normalizeBaseUrl } from "./config.js";
 import { pollConsent } from "./onboard-consent.js";
 const STATUS = "/api/v1/me/connections/linear/workspace";
@@ -252,11 +253,15 @@ export function linearWorkspaceAdapter(options) {
                 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 {
-                options.openBrowser(url);
+                await options.openBrowser(url, signal);
             }
             catch {
-                return waiting("workspace_browser_unavailable");
+                if (signal?.aborted)
+                    return waiting("interrupted");
+                browserUnavailable = true;
+                ctx.stderr(finishOnTheWeb(current.baseUrl, "connections", "connect Linear"));
             }
             let latest = waiting("workspace_status_unavailable");
             const run = () => pollConsent({
@@ -271,6 +276,8 @@ export function linearWorkspaceAdapter(options) {
                             outcome: "waiting",
                             reason: "cloud_capability_unavailable",
                         };
+                    if (latest.reason === "workspace_login_refresh_required")
+                        return { outcome: "waiting", reason: latest.reason };
                     if (latest.state === "done")
                         return { outcome: "connected" };
                     if (latest.state === "refused" || latest.state === "failed")
@@ -283,7 +290,11 @@ export function linearWorkspaceAdapter(options) {
             const result = options.wait
                 ? await options.wait("Waiting for workspace approval", run)
                 : await run();
-            return result.state === "done" ? latest : result;
+            if (result.state === "done")
+                return latest;
+            return browserUnavailable && result.reason === "consent_timeout"
+                ? waiting("workspace_browser_unavailable")
+                : result;
         },
     };
 }

package/dist/onboard.js

@@ -8,6 +8,7 @@ import { machinePathsFile } from "../vendor/paths/node.js";
 import { configPathFor } from "./config.js";
 import { CliError, UsageError } from "./errors.js";
 import { onboardFileSnapshot } from "./onboard-file-snapshot.js";
+import { onboardReasonText, onboardTeamKey, savedOnboardBaseUrl, } from "./onboard-next.js";
 import { parseBootstrapPlan, bootstrapPlanHash, bootstrapPlanLines, } from "./onboard-bootstrap.js";
 export const ONBOARD_STEPS = [
     "machine",
@@ -102,15 +103,14 @@ export const ONBOARD_DEPENDENCIES = {
     values: ["settings"],
     capacity: ["projects"],
     daemon: ["signin"],
+    // What dispatch needs. Environment approval gates only implement and pr, and the first phase
+    // needs no imported values, so repository settings and local sync do not hold a first ticket.
     "first-ticket": [
         "projects",
         "linear.adopt",
         "linear.automations",
         "accounts",
-        "settings",
-        "values",
         "capacity",
-        "daemon",
     ],
 };
 const ADMIN_STEPS = new Set([
@@ -604,6 +604,41 @@ function stepSatisfied(step) {
                 (step.id === "linear.automations" &&
                     step.reason === "automation_management_unavailable"))));
 }
+/** Steps whose wait does not hold a full run's exit code: work runs without them. A failure still
+ * fails the run, and the receipt's `complete` still needs them satisfied. Never used for gating. */
+export const ONBOARD_DEFERRED_STEPS = new Set([
+    "settings",
+    "values",
+    "housekeeping",
+    "first-ticket",
+]);
+/** A full run that exited 0 with deferred steps still open: ready for work, not complete. */
+export function onboardReadyForWork(journal, only) {
+    return !only && journal.exit === 0 && !journal.complete;
+}
+/** A recorded step's next action; a prerequisite wait names the first unfinished step it needs. */
+export function onboardStepAction(journal, step, baseUrl) {
+    if (!step.reason)
+        return "Not checked yet. Run catalyst onboard.";
+    const waitsFor = journal &&
+        (ONBOARD_DEPENDENCIES[step.id] ?? []).find((parent) => !stepSatisfied(journalStep(journal, parent)));
+    return onboardReasonText(step, {
+        baseUrl,
+        journal,
+        ...(waitsFor ? { waitsFor: ONBOARD_TITLES[waitsFor] } : {}),
+    });
+}
+/** "<title>: <action>" for each recorded step still blocking onboarding, then the first-ticket hint
+ * once the steps a ticket needs are done. Display only: completeness and exits stay with the engine. */
+export function onboardNextActions(journal, baseUrl, only) {
+    const lines = journal.steps
+        .filter((step) => (!only || step.id === only) && !stepSatisfied(step))
+        .sort((a, b) => ONBOARD_STEPS.indexOf(a.id) - ONBOARD_STEPS.indexOf(b.id))
+        .map((step) => `${ONBOARD_TITLES[step.id]}: ${onboardStepAction(journal, step, baseUrl)}`);
+    if (["projects", "accounts", "linear.adopt", "capacity"].every((id) => journalStep(journal, id)?.state === "done"))
+        lines.push(`Move a ticket in ${onboardTeamKey(journal) ?? "<TEAM KEY>"} to Todo; \`catalyst explain <ticket>\` says why it is or is not starting.`);
+    return lines;
+}
 function requireMatchingIdentity(journal, identity) {
     const account = journal.account ?? journal.tenant;
     if ((account && (!identity || account !== identity.account)) ||
@@ -920,7 +955,10 @@ export async function cmdOnboard(args, ctx, deps = {}, cliVersion = "0.13.1") {
             process.on(name, interrupted);
     const finish = (code) => {
         journal.exit = code;
-        journal.complete = !only && code === 0;
+        journal.complete =
+            !only &&
+                code === 0 &&
+                ONBOARD_STEPS.every((id) => stepSatisfied(journalStep(journal, id)));
         writeOnboardJournal(statePath, journal);
         if (args.json)
             ctx.stdout(JSON.stringify(journal));
@@ -929,10 +967,19 @@ export async function cmdOnboard(args, ctx, deps = {}, cliVersion = "0.13.1") {
         else {
             if (journal.complete)
                 ctx.stdout("Onboarding complete.");
+            else if (onboardReadyForWork(journal, only)) {
+                ctx.stdout("Ready for work.");
+                ctx.stdout("Next, when you want:");
+                for (const line of onboardNextActions(journal, savedOnboardBaseUrl(ctx.home)))
+                    ctx.stdout(line);
+            }
             else if (only && code === 0)
                 ctx.stdout(`${ONBOARD_TITLES[only]} finished. Onboarding still has other steps.`);
-            else
+            else {
                 ctx.stdout(`Setup still needs ${journal.steps.filter((step) => !stepSatisfied(step)).length} checks.`);
+                for (const line of onboardNextActions(journal, savedOnboardBaseUrl(ctx.home), only))
+                    ctx.stdout(line);
+            }
             ctx.stdout(bootstrap && journalStep(journal, "machine")?.state !== "done"
                 ? "resume: run the original setup command"
                 : "resume: catalyst onboard");
@@ -1086,7 +1133,7 @@ export async function cmdOnboard(args, ctx, deps = {}, cliVersion = "0.13.1") {
                     reason: "member_scope",
                     at: isoNow(ctx, deps),
                 });
-                deps.ui?.stepEnd(journalStep(journal, id));
+                deps.ui?.stepEnd(journalStep(journal, id), journal);
                 continue;
             }
             const missing = (ONBOARD_DEPENDENCIES[id] ?? []).find((parent) => !stepSatisfied(journalStep(journal, parent)));
@@ -1098,7 +1145,7 @@ export async function cmdOnboard(args, ctx, deps = {}, cliVersion = "0.13.1") {
                     at: isoNow(ctx, deps),
                 });
                 writeOnboardJournal(statePath, journal);
-                deps.ui?.stepEnd(journalStep(journal, id));
+                deps.ui?.stepEnd(journalStep(journal, id), journal);
                 continue;
             }
             let adapter = deps.adapters?.[id];
@@ -1122,7 +1169,7 @@ export async function cmdOnboard(args, ctx, deps = {}, cliVersion = "0.13.1") {
                     at: isoNow(ctx, deps),
                 });
                 writeOnboardJournal(statePath, journal);
-                deps.ui?.stepEnd(journalStep(journal, id));
+                deps.ui?.stepEnd(journalStep(journal, id), journal);
                 continue;
             }
             try {
@@ -1142,7 +1189,7 @@ export async function cmdOnboard(args, ctx, deps = {}, cliVersion = "0.13.1") {
                                 at: isoNow(ctx, deps),
                             });
                             writeOnboardJournal(statePath, journal);
-                            deps.ui?.stepEnd(journalStep(journal, id));
+                            deps.ui?.stepEnd(journalStep(journal, id), journal);
                             continue;
                         }
                     }
@@ -1169,7 +1216,7 @@ export async function cmdOnboard(args, ctx, deps = {}, cliVersion = "0.13.1") {
                                 at: isoNow(ctx, deps),
                             });
                             writeOnboardJournal(statePath, journal);
-                            deps.ui?.stepEnd(journalStep(journal, id));
+                            deps.ui?.stepEnd(journalStep(journal, id), journal);
                             continue;
                         }
                     }
@@ -1223,8 +1270,11 @@ export async function cmdOnboard(args, ctx, deps = {}, cliVersion = "0.13.1") {
                 });
                 return finish(EXIT_WAITING);
             }
-            deps.ui?.stepEnd(journalStep(journal, id));
+            deps.ui?.stepEnd(journalStep(journal, id), journal);
             writeOnboardJournal(statePath, journal);
+            // Later steps share the same login; preserve the actionable cause instead of cascading failures.
+            if (journalStep(journal, id)?.reason?.endsWith("_login_refresh_required"))
+                return finish(EXIT_WAITING);
             if (refused)
                 break;
         }
@@ -1234,7 +1284,8 @@ export async function cmdOnboard(args, ctx, deps = {}, cliVersion = "0.13.1") {
             ? EXIT_REFUSED
             : scope.some((id) => journalStep(journal, id)?.state === "failed")
                 ? EXIT_FAILED
-                : scope.every((id) => stepSatisfied(journalStep(journal, id)))
+                : scope.every((id) => stepSatisfied(journalStep(journal, id)) ||
+                    (!only && ONBOARD_DEFERRED_STEPS.has(id)))
                     ? 0
                     : EXIT_WAITING;
         return finish(code);

package/dist/pagination.js

@@ -12,6 +12,8 @@
 import { CliError } from "./errors.js";
 export const NEXT_CURSOR_HEADER = "x-mirror-next-cursor";
 export const TOTAL_HEADER = "x-mirror-total";
+/** CTC-4556 — the `/issues` params that narrowed the page, comma-separated; absent on older mirrors. */
+export const SCOPE_HEADER = "x-mirror-scope";
 /** The server clamps every page to this regardless of the requested `limit` (MAX_VIEW_LIMIT). */
 export const SERVER_PAGE_CAP = 500;
 /** 100 pages × 500 rows = 50,000. Reaching it is a refusal, not an ending. */
@@ -29,6 +31,12 @@ export function rowsOf(body) {
     }
     return [];
 }
+function readScope(headers) {
+    const raw = headers.get(SCOPE_HEADER);
+    if (raw === null)
+        return null;
+    return raw.split(",").map((p) => p.trim()).filter(Boolean);
+}
 function readTotal(headers) {
     const raw = headers.get(TOTAL_HEADER);
     if (raw === null)
@@ -43,6 +51,7 @@ export async function fetchPage(api, path, query) {
         rows: rowsOf(res.body),
         nextCursor: next === null || next === "" ? null : next,
         total: readTotal(res.headers),
+        scope: readScope(res.headers),
     };
 }
 export async function fetchAllPages(api, path, query) {
@@ -50,13 +59,16 @@ export async function fetchAllPages(api, path, query) {
     const seen = new Set();
     let after;
     let total = null;
+    let scope = null;
     for (let pages = 1; pages <= MAX_PAGES; pages++) {
         const page = await fetchPage(api, path, { ...query, limit: SERVER_PAGE_CAP, after });
         rows.push(...page.rows);
         if (page.total !== null)
             total = page.total;
+        // A param counts as applied only if every page says so.
+        scope = pages === 1 ? page.scope : scope && page.scope && scope.filter((p) => page.scope?.includes(p));
         if (page.nextCursor === null)
-            return { rows, total, pages };
+            return { rows, total, pages, scope };
         // ⛔ A cursor that does not advance is an infinite loop, not a long read.
         if (seen.has(page.nextCursor)) {
             throw new CliError(`GET ${path} repeated a page cursor after ${rows.length} rows — the cloud is not advancing the keyset, so --all cannot finish`, "pagination-stalled", 1);

package/dist/query.js

@@ -20,9 +20,10 @@ export async function cmdQuery(args, ctx, deps = {}) {
         throw new UsageError("query needs a subcommand: issues | issue <id> | pulls | pull <id> | projects | cycles | search <terms> | changes --since <n>");
     const cfg = requireConfig(ctx);
     const filters = {
-        team: flagString(args, "team"),
-        project: flagString(args, "project"),
-        state: flagString(args, "state"),
+        // CTC-4556 — trimmed here, so the value sent and the value compared are the one the mirror reads.
+        team: trimmedFlag(args, "team"),
+        project: trimmedFlag(args, "project"),
+        state: trimmedFlag(args, "state"),
         limit: flagInt(args, "limit", 50),
         all: flagBool(args, "all"),
     };
@@ -115,23 +116,25 @@ async function fromReplica(ctx, cfg, sub, rest, f, deps) {
 }
 async function fromApi(ctx, cfg, sub, rest, f, args) {
     const api = apiClient(cfg, ctx);
-    const common = {
-        team: f.team,
+    // CTC-4556 — the mirror narrows `/issues` by `team_key` and `state_name`; `team` and a state name
+    // in `state` narrow nothing there.
+    const issueScope = {
+        team_key: f.team,
         project: f.project,
-        state: f.state,
-        limit: f.limit,
+        state_name: f.state,
     };
     switch (sub) {
         case "issues": {
             if (f.all) {
-                const { rows } = await fetchAllPages(api, "/api/v1/issues", {
-                    team: f.team,
-                    project: f.project,
-                    state: f.state,
-                });
+                const { rows, scope } = await fetchAllPages(api, "/api/v1/issues", issueScope);
+                requireIssueScope(scope, f);
                 return applyFilters(rows, f); // no .slice — --all means the whole scope
             }
-            const page = await fetchPage(api, "/api/v1/issues", common);
+            const page = await fetchPage(api, "/api/v1/issues", {
+                ...issueScope,
+                limit: f.limit,
+            });
+            requireIssueScope(page.scope, f);
             const rows = applyFilters(page.rows, f).slice(0, f.limit);
             const notice = truncationNotice(page);
             if (notice)
@@ -247,6 +250,27 @@ function needArg(rest, usage) {
         throw new UsageError(`query ${usage}`);
     return v;
 }
+/** CTC-4556 — refuse a page the cloud did not narrow by a filter the user asked for. Filtering it
+ *  here would print the matches among the newest rows and call that the answer. */
+function requireIssueScope(scope, f) {
+    const asked = [
+        ["--team", "team_key", f.team],
+        ["--state", "state_name", f.state],
+        ["--project", "project", f.project],
+    ];
+    for (const [flag, param, value] of asked) {
+        if (!value || scope?.includes(param))
+            continue;
+        throw new CliError(`the cloud did not apply ${flag} (${scope === null ? "it sent no x-mirror-scope header" : `it applied: ${scope.join(", ") || "nothing"}`}), so the page is not that scope; nothing printed. Read it with --source replica, or drop ${flag}`, "filter-not-applied", 1);
+    }
+}
+function trimmedFlag(args, name) {
+    const value = flagString(args, name)?.trim();
+    return value === "" ? undefined : value;
+}
+/** The mirror's comparison for team keys and state names: trimmed and lowercased, nothing more.
+ *  "In Progress" and "In_Progress" stay different names. */
+const sameName = (a, b) => String(a ?? "").trim().toLowerCase() === b.trim().toLowerCase();
 export function applyFilters(rows, f) {
     return rows.filter((r) => {
         if (f.team &&
@@ -254,12 +278,11 @@ export function applyFilters(rows, f) {
                 .toUpperCase()
                 .startsWith(`${f.team.toUpperCase()}-`) ||
                 r.team_id === f.team ||
-                r.team_key === f.team))
+                sameName(r.team_key, f.team)))
             return false;
         if (f.project && r.project_id !== f.project)
             return false;
-        if (f.state &&
-            String(r.state ?? "").toLowerCase() !== f.state.toLowerCase())
+        if (f.state && !sameName(r.state, f.state))
             return false;
         return true;
     });

package/dist/repository-id.js

@@ -0,0 +1,5 @@
+/** Repository row IDs are opaque cloud identifiers, including tenant-prefixed legacy names.
+ * Syntax validation never establishes tenant ownership; callers must join fresh ACL and contract reads. */
+export function isRepositoryId(value) {
+    return typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$/.test(value);
+}

package/package.json

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

package/skills/catalyst-github/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Catalyst's GitHub: show a ticket's pull request with its checks, reviews and review threads, say whether it is mergeable under this repository's policy, and explain what a PR accumulates as the ticket moves (the branch, the draft, the rewrite, the force-pushes, the labels, the queue). Use when someone asks "show me the PR", "what are the checks saying", "why hasn't it merged", "what does the queue need", "what does that label mean", or wants the branch and merge conventions Catalyst follows.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.14.7 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.14.8 — written in this repository for customer accounts -->
 
 # Catalyst's GitHub
 
@@ -23,6 +23,8 @@ Both read through `catalyst query` and `contract` from the cloud by default; the
 | -- | -- |
 | the person asks what Catalyst did to the branch or PR, why the title changed, why history was rewritten, what a label means, or what happens on merge | `references/what-a-pr-accumulates.md` |
 | the person asks why a PR has not merged, what the queue needs, what a clean review pass looks like, or what a policy requires | `references/is-it-mergeable.md` |
+| which command answers a PR question from the cloud, and what the cloud detail cannot see | `references/reading-from-the-cloud.md` |
+| local SQL or `--local-threads`, only when `catalyst replica status --json` reports `configured: true` | `references/local-replica.md` |
 
 ## Rules
 

package/skills/catalyst-github/references/local-replica.md

@@ -0,0 +1,78 @@
+# Reading pull requests from the local replica (opt-in)
+
+Load this only when `catalyst replica status --json` reports `configured: true`. On any other machine, read from the cloud (`references/reading-from-the-cloud.md`) and do not mention the replica.
+
+The replica is an on-machine SQLite copy of the account. It exists only when the person opted in to local sync. It adds ad hoc SQL over mirrored pull requests and one leg the cloud PR detail lacks: review-thread rows. It is never required.
+
+## Check it is caught up first
+
+Run `catalyst replica status --probe --json` before every local read. Read locally only when `verdict` is `fresh` and `cursor` equals `head`. `stale` or `absent` with `configured: true` means the person opted in and the writer is down. Answer from the cloud and say the local copy is behind.
+
+Quote the cursor with any local answer, for example "from the local replica at cursor 4810".
+
+## Threads: the one leg only the replica adds
+
+**Zero thread rows does not mean zero open threads.** The thread table is filled only by resolve and unresolve events, and nothing seeds it from GitHub. A thread opened and never touched leaves no row. So zero rows can mean every thread is still open. A local "all resolved" answers only "of the threads seen resolving, which are resolved now". It never replaces the cloud's merge evaluator, which also judges a resolution against force-pushes.
+
+`node scripts/is-it-mergeable.mjs <ticket> --local-threads` reads the thread leg from the replica. It does so only after a probe proves the replica is caught up with the cloud head. Without the flag, the thread leg is inconclusive and the cloud's evaluator decides.
+
+The query the script runs, for one pull request:
+
+```sql
+select resolved, count(*) as n from pr_review_threads
+where repo_id = 'acme/widgets' and pr_number = 42
+group by resolved
+```
+
+`resolved` is 1 for resolved, 0 for unresolved, and null when no flag was mirrored.
+
+## Running SQL yourself
+
+`catalyst replica sql "<one SELECT>" --json` runs one read-only `SELECT` and prints rows. `catalyst replica schema <table>` prints a table's columns; read them before querying a table this page does not cover. Timestamps are milliseconds since the epoch.
+
+| table | one row is | key |
+| -- | -- | -- |
+| `pull_requests` | a pull request: `state`, `draft`, `merged`, `merged_at`, `head_sha`, `head_ref`, `base_ref`, `mergeable`, `mergeable_state`, `auto_merge`, `linear_issue_identifier` | `repo_id`, `number`; also `node_id` |
+| `check_runs` | one check at one commit: `name`, `status`, `conclusion` | `repo_id`, `head_sha` |
+| `commit_statuses` | a legacy commit status: `context`, `state` | `repo_id`, `sha` |
+| `reviews` | a submitted review: `user_id`, `state`, `submitted_at` | `repo_id`, `pr_number` |
+| `pr_review_threads` | a review thread seen resolving: `resolved`, `resolved_at` | `repo_id`, `pr_number` |
+| `pr_review_comments`, `pr_conversation_comments` | an inline comment, and a PR conversation comment | `repo_id`, `pr_number` |
+
+Replace `acme/widgets`, `42` and `ENG-123` with real values.
+
+Every pull request that names a ticket:
+
+```sql
+select repo_id, number, state, draft, merged, head_sha, mergeable_state
+from pull_requests where linear_issue_identifier = 'ENG-123'
+```
+
+The checks at a pull request's current head:
+
+```sql
+select c.name, c.status, c.conclusion
+from check_runs c join pull_requests p
+  on p.repo_id = c.repo_id and p.head_sha = c.head_sha
+where p.repo_id = 'acme/widgets' and p.number = 42
+order by c.name
+```
+
+The reviews on a pull request, newest first:
+
+```sql
+select user_id, state, submitted_at from reviews
+where repo_id = 'acme/widgets' and pr_number = 42
+order by submitted_at desc
+```
+
+Open pull requests that GitHub reports in conflict:
+
+```sql
+select repo_id, number, linear_issue_identifier from pull_requests
+where state = 'open' and mergeable_state = 'dirty'
+```
+
+## What the replica does not answer
+
+Reactions, PR labels and the commit each review was submitted against are not mirrored anywhere a read can reach. The cloud's evaluator holds them. `references/is-it-mergeable.md` explains what that leaves inconclusive.

package/skills/catalyst-github/references/reading-from-the-cloud.md

@@ -0,0 +1,24 @@
+# Reading pull request facts from the cloud
+
+Cloud reads are the default on every machine. They need no local writer and no local database. Every command below reads the cloud through the `catalyst` CLI.
+
+| question | command |
+| -- | -- |
+| Which pull requests name this ticket? | `catalyst query pulls --ticket <KEY-123>` |
+| What state is the PR in: draft, merged, conflict, auto-merge? | `node scripts/read-pr.mjs <KEY-123>` |
+| Which checks are red or still running at the head? | `node scripts/read-pr.mjs <KEY-123>` |
+| Is it mergeable under this repository's policy? | `node scripts/is-it-mergeable.mjs <KEY-123>`, which also reads `catalyst contract --path merge` |
+| Which stage is the linked ticket in? | `catalyst query issue <KEY-123>` |
+| What did the last pr or merge phase do? | `catalyst history <KEY-123>` |
+
+The first stderr line names the source: `source: api (...)`. Quote it when freshness matters.
+
+## What the cloud PR detail does not carry
+
+The detail has no review-thread count. So the thread leg of `is-it-mergeable.mjs` is inconclusive from a cloud read, and the cloud's own merge evaluator decides. A queue-ready label on the PR means it already said yes. Reactions, PR labels and the commit each review was submitted against are not in the detail either.
+
+A smaller ticket read is coming: the cloud will answer with only the status fields and the linked pull requests. No CLI flag selects it yet, so read the full record.
+
+## The local replica
+
+Only on a machine where `catalyst replica status --json` reports `configured: true`, `references/local-replica.md` adds local SQL and the opt-in `--local-threads` read. Everywhere else, these cloud reads are the whole answer.

package/skills/catalyst-linear/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Catalyst's view of Linear on the customer's own cloud account. Reads a ticket with its comments, relations, labels, linked pull requests and agent sessions inline, from the cloud API by default, with local replica reads available as an explicit opt-in, always naming the source; searches tickets, PRs, projects and initiatives; writes comments, card moves, labels and new tickets through the account's agent proxy as the app actor, with every route, stage id, label id and marker read from the account's contract. Knows what a ticket accumulates as Catalyst works it (phase-outcome comments, the document per phase, the agent session, the labels, the single blocks relation, the bookkeeping marker, the eyes acknowledgement). Use when a person says "show me the ticket", "what did Catalyst write on it", "comment on it", "move it", "label it" or "file a ticket". Not for raising a decision for a human (what-needs-me) and not for pull requests (catalyst-github).
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.14.7 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.14.8 — written in this repository for customer accounts -->
 
 # Catalyst Linear
 
@@ -30,6 +30,8 @@ Exit codes: 0 done, 1 not found or a usage error, 2 this machine is not connecte
 | "what did Catalyst write on this ticket?", a comment shape, a label, the marker, the 👀 | `references/what-a-ticket-accumulates.md` |
 | before any read you will report on; "is this current?"; citing; searching | `references/reading-a-ticket.md` |
 | before any comment, move, label or new ticket; identity, budget, slots, ids | `references/writing-to-linear.md` |
+| which command answers a ticket question from the cloud: stage, last phase, PR, what changed | `references/reading-from-the-cloud.md` |
+| local SQL, only when `catalyst replica status --json` reports `configured: true` | `references/local-replica.md` |
 
 ## Rules