@catalyst-cloud/cli 0.16.14 → 0.16.16

package/dist/transport.js

@@ -2,6 +2,10 @@ import { normalizeBaseUrl } from "./config.js";
 import { CliError, MeError } from "./errors.js";
 import { bearerFor } from "./oauth.js";
 export const REQUEST_TIMEOUT_MS = 15_000;
+// CTC-5399 — a WorkOS sign-in with no organization behind it is refused with this reason on every
+// route. The person needs the invitation next step, never the raw reason.
+const NO_WORKSPACE_REASON = "jwt-org-unmapped";
+const NO_WORKSPACE_NEXT_STEP = "This sign-in has no Catalyst workspace yet. Ask your admin for an invitation, or accept the one in your email, then run the install command again.";
 export class ApiClient {
     baseUrl;
     credential;
@@ -161,7 +165,12 @@ export class ApiClient {
             throw new CliError(`${what} failed (401): credential not accepted. Run catalyst login to sign in again; an unattended machine needs a new personal key from Settings → API keys`, "unauthorized", 2, 401);
         }
         if (res.status === 403) {
-            throw new CliError(`${what} failed (403): this key may not reach that route${reason ? ` (${reason})` : ""} — a route that acts as a host (claiming work, publishing artifacts) needs the tenant's account key; every read and write a person makes takes your personal key`, "forbidden", 2, 403);
+            throw new CliError(
+            // CTC-5399: a no-workspace sign-in is not a route-permission problem; it maps to the
+            // invitation next step. Every other reason keeps the route line naming its own reason.
+            reason === NO_WORKSPACE_REASON
+                ? `${what} failed (403): ${NO_WORKSPACE_NEXT_STEP}`
+                : `${what} failed (403): this key may not reach that route${reason ? ` (${reason})` : ""} — a route that acts as a host (claiming work, publishing artifacts) needs the tenant's account key; every read and write a person makes takes your personal key`, "forbidden", 2, 403);
         }
         if (res.status === 429) {
             const retryAfter = res.headers.get("retry-after");
@@ -200,7 +209,9 @@ export async function fetchMe(baseUrl, key, fetchImpl, timeoutMs = REQUEST_TIMEO
         }
         const detail = res.status === 401
             ? "credential not accepted. Run catalyst login to sign in again; an unattended machine needs a new personal key from Settings → API keys"
-            : reason || `HTTP ${res.status}`;
+            : reason === NO_WORKSPACE_REASON
+                ? NO_WORKSPACE_NEXT_STEP
+                : reason || `HTTP ${res.status}`;
         throw new MeError(`GET /me failed (${res.status}): ${detail}`, "http", res.status);
     }
     let body;

package/dist/write.js

@@ -1,11 +1,12 @@
 // write.ts — writes to Linear as the app actor through the agent proxy. Every route path comes from
 // the contract's route table (never a literal); every stage id from `teams[].stages` by slot; every
 // label id from `teams[].labels`; the bookkeeping marker from `vocabulary`. `delegate` is never offered.
+// A label goes by its name in `labelNames` unless the value itself is a UUID (CTC-5871).
 import { readFileSync } from "node:fs";
 import { flagBool, flagInt, flagList, flagString, positionals } from "./args.js";
 import { requireConfig } from "./config.js";
 import { bookkeepingPrefix, labelId, loadContract, routePath, stageIdForSlot, teamByKey, teamForTicket } from "./contract.js";
-import { CliError, UsageError } from "./errors.js";
+import { CliError, MeError, UsageError } from "./errors.js";
 import { apiClient } from "./transport.js";
 /** A ticket identifier → its Linear id (and team/project) through GET /api/v1/issues/:identifier. */
 export async function resolveIssue(api, ticket) {
@@ -67,10 +68,34 @@ export function firstStateOfType(states, teamId, type) {
     }
     return hit;
 }
-/** Post to a contract route by name; a budget refusal names the contract's daily budget. */
+// The shape the mirror refuses in `labelIds` (CTC-5566): Linear label ids are UUIDs.
+const LABEL_ID_SHAPE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** CTC-5871 — `--label`/`--add`/`--remove` values split for the route: a UUID goes in labelIds and every
+ *  other value, a contract-known name included, goes in labelNames for the mirror to resolve. A Catalyst
+ *  label the contract lists as absent from the workspace still refuses before any write. */
+export function labelFields(team, values) {
+    const ids = [];
+    const names = [];
+    for (const value of values) {
+        if (LABEL_ID_SHAPE.test(value)) {
+            ids.push(value);
+            continue;
+        }
+        labelId(team, value); // throws label-absent for a Catalyst label this workspace lacks
+        names.push(value);
+    }
+    return { ...(ids.length ? { labelIds: ids } : {}), ...(names.length ? { labelNames: names } : {}) };
+}
+/** Post to a contract route by name; a budget refusal names the contract's daily budget. A 2xx whose body
+ *  says the write failed (issue-label answers a batch of failed items with 200) is a failure too. */
 export async function postAgent(api, doc, routeName, body) {
     try {
         const res = await api.postJson(routePath(doc, routeName), body);
+        const outcome = res.body && typeof res.body === "object" ? res.body.outcome : undefined;
+        if (outcome === "failed" || outcome === "rejected" || outcome === "exhausted") {
+            const reason = res.body.reason;
+            throw new CliError(`POST ${routePath(doc, routeName)} answered ${res.status} with outcome "${outcome}"${typeof reason === "string" && reason ? `: ${reason}` : ""}`, "write-failed", 2, res.status);
+        }
         return res.body;
     }
     catch (err) {
@@ -81,6 +106,23 @@ export async function postAgent(api, doc, routeName, body) {
     }
 }
 export async function cmdWrite(args, ctx, deps = {}) {
+    try {
+        return await runWrite(args, ctx, deps);
+    }
+    catch (err) {
+        // CTC-5871 — a script reading --json stdout learns the write failed; the dispatcher still prints
+        // the reason on stderr and returns the error's exit code.
+        if (args.json && (err instanceof CliError || err instanceof MeError)) {
+            ctx.stdout(JSON.stringify({
+                ok: false,
+                command: `write ${positionals(args)[0] ?? ""}`.trim(),
+                error: { code: err instanceof CliError ? err.code : err.kind, message: err.message, ...(err.status !== undefined ? { status: err.status } : {}) },
+            }));
+        }
+        throw err;
+    }
+}
+async function runWrite(args, ctx, deps) {
     const [sub, ...rest] = positionals(args);
     if (!sub)
         throw new UsageError("write needs a subcommand: comment | state | label | create | reaction | attachment | session");
@@ -138,9 +180,9 @@ export async function cmdWrite(args, ctx, deps = {}) {
             const team = teamForTicket(doc, issue.identifier);
             const results = [];
             if (add.length)
-                results.push(await postAgent(api, doc, "issue-label", { issueId: issue.id, labelIds: add.map((n) => labelId(team, n)), mode: "add" }));
+                results.push(await postAgent(api, doc, "issue-label", { issueId: issue.id, ...labelFields(team, add), mode: "add" }));
             if (remove.length)
-                results.push(await postAgent(api, doc, "issue-label", { issueId: issue.id, labelIds: remove.map((n) => labelId(team, n)), mode: "remove" }));
+                results.push(await postAgent(api, doc, "issue-label", { issueId: issue.id, ...labelFields(team, remove), mode: "remove" }));
             result = results.length === 1 ? results[0] : results;
             break;
         }
@@ -158,13 +200,13 @@ export async function cmdWrite(args, ctx, deps = {}) {
                     throw new UsageError("write create --stdin read an empty description");
             }
             const team = teamByKey(doc, teamKey);
-            const labels = flagList(args, "label").map((n) => labelId(team, n));
+            const labels = labelFields(team, flagList(args, "label"));
             const priority = flagString(args, "priority") !== undefined ? flagInt(args, "priority", 0) : undefined;
             result = await postAgent(api, doc, "issue-create", {
                 teamId: team.id,
                 title,
                 ...(description ? { description } : {}),
-                ...(labels.length ? { labelIds: labels } : {}),
+                ...labels,
                 ...(priority !== undefined ? { priority } : {}),
                 ...(asUser ? { createAsUser: true } : {}),
             });
@@ -190,7 +232,7 @@ export async function cmdWrite(args, ctx, deps = {}) {
             if (!title || !url)
                 throw new UsageError("write attachment needs --title <t> and --url <u>");
             const issue = await resolveIssue(api, ticket);
-            result = await postAgent(api, doc, "attachment", { issueId: issue.id, title, url });
+            result = await postAgent(api, doc, "attachment", { issueId: issue.id, title, url, metadata: {} });
             break;
         }
         case "session": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catalyst-cloud/cli",
-  "version": "0.16.14",
+  "version": "0.16.16",
   "description": "Set up Catalyst Cloud, check your tickets and manage your account from the command line.",
   "license": "MIT",
   "type": "module",
@@ -53,16 +53,16 @@
     "prepublishOnly": "node scripts/release-train-check.mjs --publish cli"
   },
   "dependencies": {
-    "@catalyst-cloud/sdk": "0.16.3",
+    "@catalyst-cloud/sdk": "0.16.6",
     "@clack/prompts": "1.8.1",
     "fast-string-width": "3.0.2",
     "fast-wrap-ansi": "0.2.2",
     "smol-toml": "^1.7.1",
     "yaml": "^2.9.0",
-    "@catalyst-cloud/sdk-replica-node": "0.16.3"
+    "@catalyst-cloud/sdk-replica-node": "0.16.6"
   },
   "devDependencies": {
-    "@catalyst-cloud/schema": "0.16.2",
+    "@catalyst-cloud/schema": "0.16.5",
     "@types/node": "^26.3.0",
     "@vitest/coverage-v8": "^4.1.11",
     "typescript": "^7.0.2",

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.16.14 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.16 — written in this repository for customer accounts -->
 
 # Catalyst's GitHub
 

package/skills/catalyst-linear/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Catalyst's view of Linear on the customer's own cloud account. Reads a ticket with its comments, relations, labels, linked pull requests and agent sessions inline, from the 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.16.14 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.16 — written in this repository for customer accounts -->
 
 # Catalyst Linear
 

package/skills/catalyst-linear/references/writing-to-linear.md

@@ -26,9 +26,9 @@ Every write spends one unit of the per-host daily budget (`thresholds.hostDailyW
 
 `--slot <slot>` resolves to the team's live state id from the contract, and refuses when the slot is unmapped or its state is gone (re-map first: `catalyst team map <KEY>`). Moving to `dispatch` dispatches work. `--state-type backlog` resolves the team's first backlog-type state and parks the card, stopping remediation rounds. Names are display fields that survive re-imports while ids do not, so there is no move by name.
 
-## Labels are by contract id
+## Labels are by name or UUID
 
-A name the contract lists for the team (the ask marker, the hold label, the release label) resolves to that team's preferred id; when the workspace has no such label the CLI refuses rather than inventing one. Any other value is sent as a label id as given, so a label outside Catalyst's own set needs its id, which the ticket record's `labels[]` shows.
+`--label`, `--add` and `--remove` take a label's name or its UUID. A UUID is sent as a label id; every other value is sent as a name, and the proxy resolves it in the ticket's team. When the contract lists one of Catalyst's own labels (the ask marker, the hold label, the release label) as absent from the workspace, the CLI refuses rather than inventing it.
 
 Two labels are a human's, not yours: the release label (which frees a ticket the shape detector held) is applied by a human; the hold labels on a pull request are `catalyst-github`'s subject.
 

package/skills/catalyst-linear/scripts/label.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-// label.mjs — add or remove labels on a ticket. A Catalyst label name (ask, hold, release) resolves
-// to the id the contract lists for this team; anything else is passed through as a label id.
+// label.mjs — add or remove labels on a ticket. A value shaped like a UUID goes as a label id; any other
+// value goes as a label name for the proxy to resolve in the ticket's team.
 import { exitOnFailure, parseFlags, parseJson, relayStderr, runCli, usage, wantsHelp } from "./lib/cli.mjs";
 
 const HELP = `Usage: node scripts/label.mjs <ticket> [--add <name|id>]... [--remove <name|id>]... [--json]
@@ -13,9 +13,10 @@ direction (add, remove), whatever the label count.
   --remove <name|id>    a label to remove (repeatable)
   --json                print the CLI's JSON result
 
-Names the contract knows (the ask marker, the hold label, the release label) resolve to this team's
-label id; a name the workspace lacks is refused rather than guessed. Any other value is sent as a
-label id unchanged.
+A value shaped like a UUID is sent as a label id. Any other value, Catalyst's own labels (the ask
+marker, the hold label, the release label) and the workspace's custom labels alike, is sent as a
+label name, and the proxy resolves it in the ticket's team. When the contract lists one of
+Catalyst's own labels as absent from the workspace, the CLI refuses before any write.
 
 Exit 0 written, 1 on a usage error, 2 when this machine is not connected to a tenant or the write
 was refused (a Catalyst label the workspace lacks, the daily budget spent; the line says which).`;

package/skills/catalyst-onboard/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Set up Catalyst Cloud and say whether setup is working. Walks a person from nothing to their first ticket running, one step at a time: the coding account, the project, the integrations and connected accounts, each repository's settings file, then one real ticket moving. Also logs this machine in, reads the readiness verdict with who can fix each failure, and checks the optional local replica. Use when someone says "set me up", "onboard me", "I just signed up", "get me started", "what do I do first", "log me in", "which account is this machine on", "am I set up", "what is missing", "why does nothing happen" or "is the replica running", when a login expired, or when a skill script exits 2 saying this machine is not connected. Does every step a key can do through the catalyst CLI, hands over the exact page for the steps only a browser can do, and never claims a step it did not watch succeed.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.14 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.16 — written in this repository for customer accounts -->
 
 # Onboard me
 
@@ -12,11 +12,12 @@ Guide setup through the same `catalyst onboard` flow that the installer runs. Th
 
 ## Use the onboarding command
 
-1. Run `catalyst capabilities --json`. If its `onboard` entry is available and advertises `bootstrapHandoff: true`, use this path. If absent, use the older step-by-step references below and name the CLI update needed for the continuous flow.
-2. For a requested setup, run `catalyst onboard`. To inspect first, run `catalyst onboard --dry-run --json`. Resume with `catalyst onboard`; the command rechecks saved results. Do not ask the person to confirm completed browser steps or add a separate approval before the command's plan question.
-3. In a terminal, the command shows the verified person, workspace and plan before approval. Without terminal input, or with `--json`, use `--yes` only when the person has accepted the displayed defaults; otherwise setup waits with exit 11 and keeps the saved connection and receipt. JSON keeps progress, identity and the plan on stderr and returns one result on stdout. A supplied key needs `catalyst login` before onboarding; browser sign-in does not replace it.
-4. For the current onboarding checks, run `catalyst ready --onboarding --json`. A failed check needs attention. An unknown check needs evidence. Report observed project work separately from incomplete setup; an unknown setup check does not prove work stopped.
-5. Exit 0 completes the requested scope. For a full run, exit 0 means work can start. If the receipt's `complete` is false, a repository value or the first ticket is still open, and the command lists it under "Next, when you want". The daily update never keeps `complete` false, and neither do repository settings this computer cannot review (no checkout here, or not yet approved); a settings review that timed out or could not keep its draft does. Only a person at a terminal picks the first ticket; `--yes`, `--json` and headless runs leave it waiting with an action. Exit 10 means a failed step, 11 means waiting, and 12 means a guard refused the action. A successful `--only` step does not mean onboarding is complete. Keep the command's safe fix and supported resume command in your reply.
+1. Accept the workspace invitation first. Catalyst has no self-serve sign-up: a person joins by accepting the invitation email their workspace admin sent. Until it is accepted, sign-in is refused with "This sign-in has no Catalyst workspace yet"; if no invitation ever arrived, asking that admin is the next step, and nothing below runs before it lands.
+2. Run `catalyst capabilities --json`. If its `onboard` entry is available and advertises `bootstrapHandoff: true`, use this path. If absent, use the older step-by-step references below and name the CLI update needed for the continuous flow.
+3. For a requested setup, run `catalyst onboard`. To inspect first, run `catalyst onboard --dry-run --json`. Resume with `catalyst onboard`; the command rechecks saved results. Do not ask the person to confirm completed browser steps or add a separate approval before the command's plan question.
+4. In a terminal, the command shows the verified person, workspace and plan before approval. Without terminal input, or with `--json`, use `--yes` only when the person has accepted the displayed defaults; otherwise setup waits with exit 11 and keeps the saved connection and receipt. JSON keeps progress, identity and the plan on stderr and returns one result on stdout. A supplied key needs `catalyst login` before onboarding; browser sign-in does not replace it.
+5. For the current onboarding checks, run `catalyst ready --onboarding --json`. A failed check needs attention. An unknown check needs evidence. Report observed project work separately from incomplete setup; an unknown setup check does not prove work stopped.
+6. Exit 0 completes the requested scope. For a full run, exit 0 means work can start. If the receipt's `complete` is false, a repository value or the first ticket is still open, and the command lists it under "Next, when you want". The daily update never keeps `complete` false, and neither do repository settings this computer cannot review (no checkout here, or not yet approved); a settings review that timed out or could not keep its draft does. Only a person at a terminal picks the first ticket; `--yes`, `--json` and headless runs leave it waiting with an action. Exit 10 means a failed step, 11 means waiting, and 12 means a guard refused the action. A successful `--only` step does not mean onboarding is complete. Keep the command's safe fix and supported resume command in your reply.
 
 Use cloud reads for ordinary workstation setup checks. Offer local sync for local SQL or sustained local reads inside the plan review. Local sync does not promise offline browsing. It is optional; do not make an absent replica a setup failure. Browser approval belongs to the person. Missing bearer capabilities stay unfinished; never call a session-only route from the CLI or invent a command.
 

package/skills/catalyst-onboard/references/connecting-this-machine.md

@@ -31,5 +31,6 @@ An unmatched Linear identity is the person's to match: `catalyst identity linear
 - **A 403 on the contract naming an older cloud.** The cloud lacks personal-key access: update the cloud, or use the account key until then.
 - **A line naming two contract versions.** `npm install -g @catalyst-cloud/cli@latest && catalyst login` before using the other skills.
 - **A refusal naming `jwt-no-membership`.** The cloud learns of a person at their first sign-in to the app. Hand over the app's sign-in link once, then offer to run `catalyst login` again. If it repeats, their seat is inactive and an owner or admin activates it.
+- **A refusal naming `jwt-org-unmapped`, or "no Catalyst workspace yet".** The sign-in reached Catalyst with no workspace behind it: Catalyst is joined by invitation, not sign-up. The invitation email (or the workspace admin who sends one) is the missing step; once it is accepted, run the install command or `catalyst login` again.
 
 Retry a failed login once, by hand, after the fix. A key goes into the login command or `CATALYST_CLOUD_TOKEN` and nowhere else: never a ticket, a transcript, or a file you write. After a bundle update, the next command prints a one-line notice; read it to the person if they are watching.

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

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

package/skills/unstick/SKILL.md

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

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

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

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

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

package/skills/whats-happening/SKILL.md

@@ -4,13 +4,13 @@ description: >-
   Use for "what's happening?", "what machines do we have?", "how much capacity do we have?", "where are we?", "why is that stuck?", "what closed?", "what's next?", "how does this work?", "why did it do that?", "how does it prioritise?" and "what does this setting do, where is it set?" in Catalyst Cloud, or asks for something to be done rather than known. Reads the contract via catalyst CLI. Read-only: route work/decisions, never answer as the human.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.14 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.16 — written in this repository for customer accounts -->
 
 # What's happening
 
 Use one snapshot and the person's login. Run scripts, never read them. --help explains usage; exit 2 needs onboard, exit 1 means failure.
 
-- `node scripts/snapshot.mjs` reads contract, running work, queue and ranked asks from the cloud. --board adds stages, --accounts coding accounts, --team K narrows. --replica adds optional local diagnostics.
+- `node scripts/snapshot.mjs` reads contract, running work, queue and ranked asks from the cloud. --board adds every open ticket's count per stage with up to 50 cards each; when boardTruncated is present, say how many it left out. --accounts adds coding accounts, --team K narrows. --replica adds optional local diagnostics.
 - `node scripts/explain.mjs <ticket>` explains eligibility; --history adds attempts, rounds, holds and releases.
 - `node scripts/show-my-map.mjs [--team K]` prints stages, labels, ladder and thresholds.
 

package/skills/whats-happening/scripts/snapshot.mjs

@@ -10,13 +10,22 @@ import {
   runCli,
 } from "./lib/cli.mjs";
 
+/** Cards listed per board column by default. Counts are never capped by this; the cards are. */
+const BOARD_CARDS_PER_COLUMN = 50;
+/** One page of `query issues` when the whole-scope read fails: the server's page cap. */
+const BOARD_FALLBACK_PAGE = 500;
+const TERMINAL_TYPES = new Set(["completed", "canceled", "cancelled"]);
+
 const SPEC = {
   team: { value: true, help: "limit the queue and the board to this team key" },
   board: {
     value: false,
     help: "also include open tickets grouped by stage, in the contract's slot order",
   },
-  limit: { value: true, help: "board: max tickets to read (default 200)" },
+  limit: {
+    value: true,
+    help: `board: max cards listed per column (default ${BOARD_CARDS_PER_COLUMN}); column counts always cover every ticket read`,
+  },
   "full-contract": {
     value: false,
     help: "include the whole contract instead of the trimmed `tenant` block",
@@ -39,7 +48,8 @@ if (help) {
     [
       "Reads catalyst contract, running, queue and ask list from the cloud (query issues with --board,",
       "accounts with --accounts, optional local diagnostics with --replica).",
-      "Output: one JSON document {takenAt, source, tenant, running, queue, waitingOnHuman, board?, accounts?, errors?}.",
+      "Output: one JSON document {takenAt, source, tenant, running, queue, waitingOnHuman, board?, boardTruncated?, accounts?, errors?}.",
+      "board.counts counts every open ticket in scope; boardTruncated is present whenever a card list or the read itself left tickets out.",
       "A section the cloud refused is reported under errors and the rest still prints; exit 1 in that case.",
       "Every account fact (stage names, thresholds, teams) comes from the contract in this output, never from prose.",
     ],
@@ -47,6 +57,12 @@ if (help) {
   process.exit(0);
 }
 
+const perColumn = flags.limit === undefined ? BOARD_CARDS_PER_COLUMN : Number(flags.limit);
+if (!Number.isInteger(perColumn) || perColumn < 1) {
+  process.stderr.write(`--limit must be a positive whole number, got ${flags.limit}\n`);
+  process.exit(1);
+}
+
 const errors = {};
 const section = (name, args) => {
   const r = runCli(args);
@@ -106,28 +122,14 @@ const out = {
 if (flags.accounts) out.accounts = section("accounts", ["accounts", "--json"]);
 
 if (flags.board) {
-  const args = [
-    "query",
-    "issues",
-    "--source",
-    "api",
-    "--limit",
-    String(flags.limit ?? 200),
-    "--json",
-  ];
-  if (flags.team) args.push("--team", flags.team);
-  const r = runCli(args);
-  const sourceLine = (r.stderr.match(/^source: .*$/m) ?? [null])[0];
-  // A board read is a window (`--limit` stays the default), and a window the cloud cut short must
-  // say so rather than reading as the whole team.
-  const truncatedLine = (r.stderr.match(/^truncated at .*$/m) ?? [null])[0];
-  if (r.code !== 0)
-    errors.board = (r.stderr || `exit ${r.code}`).trim().split("\n").at(-1);
+  const read = readBoard(flags.team);
+  if (read.error) errors.board = read.error;
   else {
-    const rows = parseJson(r.stdout, "issues");
-    out.board = groupByStage(rows, contract, flags.team);
-    if (sourceLine) out.source.board = sourceLine.replace(/^source: /, "");
-    if (truncatedLine) out.source.boardTruncated = truncatedLine;
+    out.board = groupByStage(read.rows, contract, flags.team, perColumn);
+    if (read.sourceLine) out.source.board = read.sourceLine.replace(/^source: /, "");
+    if (read.truncatedLine) out.source.boardTruncated = read.truncatedLine;
+    const truncated = boardTruncation(out.board, read, perColumn);
+    if (truncated) out.boardTruncated = truncated;
   }
 }
 
@@ -135,8 +137,10 @@ if (Object.keys(errors).length) out.errors = errors;
 process.stderr.write(
   `source: api for running/queue/asks; replica ${replica.verdict}${replica.cursor != null ? ` (cursor ${replica.cursor})` : ""}${out.source.board ? `; board from ${out.source.board}` : ""}\n`,
 );
+if (out.boardTruncated) process.stderr.write(`board truncated: ${out.boardTruncated.message}\n`);
 process.stdout.write(JSON.stringify(out, null, 2) + "\n");
-process.exit(Object.keys(errors).length ? 1 : 0);
+// exitCode, not exit(): a whole board is well past a pipe's buffer, and exit() would cut it off.
+process.exitCode = Object.keys(errors).length ? 1 : 0;
 
 /** The contract facts a status reply needs, and nothing a reply should not paste. */
 function trimContract(doc, teamKey) {
@@ -181,37 +185,125 @@ function trimContract(doc, teamKey) {
   };
 }
 
+/**
+ * Every ticket in scope, so the board counts are whole. The cloud caps one page at 500
+ * rows, so a single `--limit` read is a window over the most recently updated tickets, and the
+ * stages it happens to cover are not the board. `--all` follows the cloud's page cursor to the end.
+ * If that read is refused (a scope past the CLI's page ceiling, say), one full page is read instead
+ * and the result says exactly how much of the scope it covers.
+ */
+function readBoard(teamKey) {
+  const base = ["query", "issues", "--source", "api"];
+  const team = teamKey ? ["--team", teamKey] : [];
+  const lineOf = (stderr, re) => (stderr.match(re) ?? [null])[0];
+  const lastLine = (r) => (r.stderr || r.stdout || `exit ${r.code}`).trim().split("\n").at(-1);
+
+  const all = runCli([...base, "--all", "--json", ...team]);
+  if (all.code === 0) {
+    const rows = parseJson(all.stdout, "issues");
+    return {
+      rows,
+      complete: true,
+      read: { returned: rows.length, total: rows.length },
+      sourceLine: lineOf(all.stderr, /^source: .*$/m),
+      truncatedLine: null,
+    };
+  }
+  const allError = lastLine(all);
+  const page = runCli([...base, "--limit", String(BOARD_FALLBACK_PAGE), "--json", ...team]);
+  if (page.code !== 0) return { error: `${allError}; one page: ${lastLine(page)}` };
+  const rows = parseJson(page.stdout, "issues");
+  const truncatedLine = lineOf(page.stderr, /^truncated at .*$/m);
+  // The CLI's line: "truncated at N of M — …", where M is a count or "an unknown total (…)".
+  const m = truncatedLine?.match(/^truncated at (\d+) of (\d+)?/);
+  return {
+    rows,
+    complete: !truncatedLine,
+    read: {
+      returned: m ? Number(m[1]) : rows.length,
+      total: truncatedLine ? (m?.[2] ? Number(m[2]) : null) : rows.length,
+    },
+    readError: allError,
+    sourceLine: lineOf(page.stderr, /^source: .*$/m),
+    truncatedLine,
+  };
+}
+
+/** The top-level truncation report, or null when the board lists every open ticket in scope. */
+function boardTruncation(board, read, perColumn) {
+  const total = Object.values(board.counts).reduce((a, b) => a + b, 0);
+  const returned = Object.values(board.byStage).reduce((a, cards) => a + cards.length, 0);
+  if (read.complete && returned === total) return null;
+  const n = (v) => (v === null ? "an unknown number of" : v.toLocaleString("en-US"));
+  const parts = [];
+  if (returned < total)
+    parts.push(`lists ${n(returned)} of ${n(total)} open tickets (at most ${perColumn} per column; raise --limit for more)`);
+  parts.push(
+    read.complete
+      ? "column counts cover every ticket"
+      : `column counts cover only the ${n(read.read.returned)} most recently updated of ${n(read.read.total)} tickets read, so they are low`,
+  );
+  return {
+    returned,
+    total,
+    perColumn,
+    countsComplete: read.complete,
+    ...(read.complete ? {} : { read: read.read, reason: read.readError ?? null }),
+    message: `board ${parts.join("; ")}`,
+  };
+}
+
 /** Open tickets by stage name, ordered by the contract's slot order for the ticket's team; unmapped
- *  state names follow, alphabetically. Terminal-typed states are dropped so the board is work only. */
-function groupByStage(rows, doc, teamKey) {
+ *  state names follow, alphabetically. Terminal stages are dropped so the board is work only: a stage
+ *  in the done or canceled slot, a stage the contract types completed or canceled, and any state the
+ *  ticket itself carries a completed or canceled `state_type` for (Duplicate is canceled-typed and
+ *  sits in no slot). Terminal is judged per ticket, from the ticket's own `state_type` or its OWN
+ *  team's contract, never from a name blacklist: team A's open `Review` must survive team B's
+ *  completed `Review`. `counts` covers every row; `byStage` lists the first `perColumn` per stage. */
+function groupByStage(rows, doc, teamKey, perColumn) {
   const order = [];
   const seen = new Set();
   const terminal = new Set();
+  const terminalByTeam = new Map();
   for (const t of doc.teams ?? []) {
     if (teamKey && String(t.key ?? "").toUpperCase() !== teamKey.toUpperCase())
       continue;
+    const names = new Set();
     for (const slot of doc.slots ?? []) {
       const s = t.stages?.[slot];
       if (!s?.name) continue;
       if (
         slot === "done" ||
         slot === "canceled" ||
-        ["completed", "canceled", "cancelled"].includes(
-          String(s.type ?? "").toLowerCase(),
-        )
-      )
+        TERMINAL_TYPES.has(String(s.type ?? "").toLowerCase())
+      ) {
+        names.add(s.name);
         terminal.add(s.name);
-      else if (!seen.has(s.name)) {
+      } else if (!seen.has(s.name)) {
         seen.add(s.name);
         order.push(s.name);
       }
     }
+    terminalByTeam.set(String(t.key ?? "").toUpperCase(), names);
   }
+  for (const r of rows)
+    if (TERMINAL_TYPES.has(String(r.state_type ?? "").toLowerCase()))
+      terminal.add(String(r.state ?? "unknown"));
+  const rowIsTerminal = (r) =>
+    TERMINAL_TYPES.has(String(r.state_type ?? "").toLowerCase()) ||
+    (terminalByTeam
+      .get(String(r.team_key ?? "").toUpperCase())
+      ?.has(String(r.state ?? "unknown")) ??
+      false);
+  const counts = {};
   const byStage = {};
   for (const r of rows) {
     const state = String(r.state ?? "unknown");
-    if (terminal.has(state)) continue;
-    (byStage[state] ??= []).push({
+    if (rowIsTerminal(r)) continue;
+    counts[state] = (counts[state] ?? 0) + 1;
+    const cards = (byStage[state] ??= []);
+    if (cards.length >= perColumn) continue;
+    cards.push({
       identifier: r.identifier,
       title: r.title,
       priority: r.priority ?? null,
@@ -223,8 +315,10 @@ function groupByStage(rows, doc, teamKey) {
   const extra = Object.keys(byStage)
     .filter((s) => !seen.has(s))
     .sort();
+  const stageOrder = [...order, ...extra];
   return {
-    stageOrder: [...order, ...extra],
+    stageOrder,
+    counts: Object.fromEntries(stageOrder.map((s) => [s, counts[s] ?? 0])),
     byStage,
     terminalStagesDropped: [...terminal],
   };