@catalyst-cloud/catalyst-skills 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.2.1
+
+Fixes five defects found by running 0.2.0's verbs against a live tenant. Three skills (catalyst-github, catalyst-setup, how-catalyst-works) carried a colon-and-space inside an unquoted description, which YAML reads as a nested map rather than text, so `npx skills add` skipped them and still reported success — every Codex, Cursor and OpenCode install of 0.2.0 quietly got five of the eight skills, and reinstalling with this version gives you all eight. `running` no longer asks for lease attributions it has no coordinates for, so the headline "what's happening?" verb works instead of failing for every tenant; the lease read is still available as `running --ticket T --phase P`. The CLI no longer truncates its own output at 64KB when a skill reads it through a pipe, which made `query issues --json` on a tenant past roughly eighty tickets return invalid JSON with a success code. `accounts` now actually reads your coding-account slots and renders them, `history <ticket>` (also `explain --history`) shows a ticket's execution history, and both say plainly when your cloud is older than this bundle rather than printing an empty success. `queue` with no `--team` reads every team on your tenant instead of being refused, as its help always promised. `query changes` works at all now: it reads the feed's NDJSON, where before it called any successful response a non-JSON body — nothing noticed because the documented `--since 0` is refused on any tenant whose feed has rotated, so a success was never reached. That refusal now names a cursor you can actually use, and `--since head` starts from now.
+
 ## 0.2.0
 
 Eight skills named from the executive's seat (whats-happening, what-needs-me, run-this-project, catalyst-setup, catalyst-linear, catalyst-github, how-catalyst-works, connect-me) replace the six; reads and the live event stream go through the Catalyst Cloud SDK and writes through the tenant's agent proxy, all behind catalyst-skills verbs (me, contract, query, replica, explain, running, queue, watch, write, ask, ready, accounts), with every stage id, label id, threshold and route read from the tenant contract; Node 22 is now required; installing the skills has moved to your agent's own command (the Claude Code plugin marketplace in this repository, or npx skills add for Codex, Cursor, OpenCode and the rest) and the CLI no longer copies them, leaving install only as a repair path; catalyst-skills login replaces join, which stays as a deprecated alias for one minor version, and login now prompts for the key without echoing it when no CATALYST_CLOUD_TOKEN is set; every SKILL.md declares allowed-tools scoped to this package's binary, so no skill needs a blanket shell grant; your existing customer.json is still read unchanged and gains the CLI path the next time you run catalyst-skills login, which also caches the tenant contract; run catalyst-skills ready to confirm.

package/bin/catalyst-skills.js

@@ -1,10 +1,50 @@
 #!/usr/bin/env node
 // Thin ESM launcher for @catalyst-cloud/catalyst-skills (CTC-1926). tsc does not carry a shebang
 // through emit, so the bin is this two-line wrapper and the program lives in dist/cli.js.
+//
+// ⛔ NEVER `process.exit(code)` STRAIGHT AFTER A WRITE. When stdout is a PIPE — which is how every
+// skill script spawns this CLI — writes are asynchronous, so `process.exit` severs whatever is
+// still in flight AND STILL REPORTS THE ORIGINAL EXIT CODE. The caller then reads a truncated body
+// with a success code and has no way to tell it from a complete one: `query issues --json` on a
+// tenant with ~80+ tickets came back as 65,528 bytes of invalid JSON, exit 0 (0.2.0). Interactive
+// use hid it, because a tty gives stdout a synchronous write path.
+//
+// So: park the code on `process.exitCode`, wait for both streams to drain, and only then exit. The
+// explicit exit stays — `fetch`'s keep-alive sockets can hold the event loop open for seconds after
+// the work is done, and a CLI that lingers is its own defect — but by then nothing is buffered.
 import("../dist/cli.js")
   .then((m) => m.main(process.argv.slice(2)))
-  .then((code) => process.exit(code))
+  .then((code) => finish(code))
   .catch((err) => {
     console.error(`catalyst-skills: failed to load: ${err instanceof Error ? err.message : String(err)}`);
-    process.exit(1);
+    finish(1);
   });
+
+/**
+ * Resolve once every byte already handed to `stream` has reached the other end. The empty write is
+ * ordered behind the real ones, so its callback is the drain signal; a destroyed or errored stream
+ * (a reader that hung up) resolves immediately rather than hanging the process forever.
+ */
+function drained(stream) {
+  return new Promise((resolve) => {
+    if (!stream || stream.destroyed || stream.writableEnded) return resolve();
+    let settled = false;
+    const done = () => {
+      if (settled) return;
+      settled = true;
+      resolve();
+    };
+    stream.once("error", done);
+    try {
+      stream.write("", done);
+    } catch {
+      done();
+    }
+  });
+}
+
+async function finish(code) {
+  process.exitCode = code;
+  await Promise.all([drained(process.stdout), drained(process.stderr)]);
+  process.exit(code);
+}

package/dist/args.js

@@ -38,11 +38,15 @@ export const FLAG_TABLES = {
         "stale-ms": { value: true, help: "status: heartbeat age that counts as stale (default 15000)" },
     },
     explain: {
-        history: { value: false, help: "per-ticket execution history (not visible to an account key yet)" },
+        history: { value: false, help: "per-ticket execution history instead of the eligibility reason" },
+    },
+    history: {},
+    running: {
+        ticket: { value: true, help: "with --phase: also the lease attributions for this (ticket, phase)" },
+        phase: { value: true, help: "with --ticket: the phase whose lease attributions to read" },
     },
-    running: {},
     queue: {
-        team: { value: true, help: "team key" },
+        team: { value: true, help: "team key (default: every team the tenant contract names)" },
     },
     watch: {
         team: { value: true, help: "scope: a team key" },
@@ -95,16 +99,17 @@ export const VERB_USAGE = {
     notice: "notice",
     me: "me [--json]",
     contract: "contract [--refresh] [--path <a.b.c>] [--json]",
-    query: "query <issues|issue <id>|pulls|pull <id>|projects|cycles|search <terms>|changes --since <n>> [--team K] [--project P] [--state S] [--limit N] [--source replica|api] [--json]",
+    query: "query <issues|issue <id>|pulls|pull <id>|projects|cycles|search <terms>|changes --since <cursor|head>> [--team K] [--project P] [--state S] [--limit N] [--source replica|api] [--json]",
     replica: "replica <start [--detach]|stop|status [--probe] [--json]|sql \"<select>\"|schema [table]> [--db <path>]",
     explain: "explain <ticket> [--history] [--json]",
-    running: "running [--json]",
+    history: "history <ticket> [--json]",
+    running: "running [--ticket T --phase P] [--json]",
     queue: "queue [--team K] [--json]",
     watch: "watch [--team K] [--ticket T]... [--project P] [--exec CMD] [--cursor-file <path>] [--from cursor|head]",
     write: "write <comment <ticket> --body|--stdin [--parent] [--bookkeeping] [--as-user] | state <ticket> --slot|--state-id|--state-type | label <ticket> --add... --remove... | create --team --title [--label] [--priority] | reaction <ticket>|--comment <id> --emoji <e> | attachment <ticket> --title --url | session <ticket> [--title] [--plan-file] [--activity]>",
     ask: "ask <raise --team --title [--context] [--option]... [--default] --blocks <ticket>...|--nothing-to-block [--ask-key] | accept <askTicket> --answer <commentId> --role <role> | list [--json]>",
     ready: "ready [--json]",
-    accounts: "accounts",
+    accounts: "accounts [--json]",
 };
 export function parseArgs(argv) {
     const out = {

package/dist/cli.js

@@ -6,7 +6,7 @@ import { CONFIG_MODE, DEFAULT_BASE_URL, PACKAGE_NAME, cliPath, configPathFor, co
 import { loadContract, pickPath } from "./contract.js";
 import { CliError, MeError, UsageError } from "./errors.js";
 import { fetchMe } from "./http.js";
-import { cmdAccounts, cmdExplain, cmdQueue, cmdRunning } from "./execution.js";
+import { cmdAccounts, cmdExplain, cmdHistory, cmdQueue, cmdRunning } from "./execution.js";
 import { cmdQuery } from "./query.js";
 import { cmdReady } from "./ready.js";
 import { cmdReplica } from "./replica.js";
@@ -42,9 +42,9 @@ export function usageText() {
         "  catalyst-skills install [--skills-dir <dir>] [--force]   (repair path; your agent's own command installs the skills)",
         "  catalyst-skills status | notice | me | ready | accounts",
         "  catalyst-skills contract [--refresh] [--path <a.b.c>]",
-        "  catalyst-skills query <issues|issue <id>|pulls|pull <id>|projects|cycles|search <terms>|changes --since <n>>",
+        "  catalyst-skills query <issues|issue <id>|pulls|pull <id>|projects|cycles|search <terms>|changes --since <cursor|head>>",
         "  catalyst-skills replica <start [--detach]|stop|status [--probe]|sql \"<select>\"|schema [table]>",
-        "  catalyst-skills explain <ticket> | running | queue [--team K]",
+        "  catalyst-skills explain <ticket> | history <ticket> | running [--ticket T --phase P] | queue [--team K]",
         "  catalyst-skills watch [--team K] [--ticket T]... [--project P] [--exec CMD]",
         "  catalyst-skills write <comment|state|label|create|reaction|attachment|session> ...",
         "  catalyst-skills ask <raise|accept|list> ...",
@@ -148,6 +148,8 @@ export async function main(argv, ctx = defaultCtx(), deps = {}) {
                 return await cmdReplica(args, ctx, deps.replica);
             case "explain":
                 return await cmdExplain(args, ctx);
+            case "history":
+                return await cmdHistory(args, ctx);
             case "running":
                 return await cmdRunning(args, ctx);
             case "queue":
@@ -161,7 +163,7 @@ export async function main(argv, ctx = defaultCtx(), deps = {}) {
             case "ready":
                 return await cmdReady(args, ctx, { skillNames: CUSTOMER_SKILLS, loadSdk: deps.loadSdk });
             case "accounts":
-                return cmdAccounts(ctx);
+                return await cmdAccounts(args, ctx);
             default:
                 ctx.stderr(`unknown command: ${args.command}`);
                 ctx.stderr(usageText());

package/dist/execution.js

@@ -4,7 +4,7 @@
 import { flagBool, flagString, positionals } from "./args.js";
 import { normalizeBaseUrl, requireConfig } from "./config.js";
 import { loadContract } from "./contract.js";
-import { UsageError } from "./errors.js";
+import { CliError, UsageError } from "./errors.js";
 import { apiClient } from "./http.js";
 /** Every exclusion reason the eligibility evaluator names, in plain English. */
 export const EXCLUSION_REASONS = {
@@ -101,10 +101,9 @@ export async function cmdExplain(args, ctx) {
     if (!ticket)
         throw new UsageError("explain needs a ticket: explain <ticket>");
     const cfg = requireConfig(ctx);
-    if (flagBool(args, "history")) {
-        ctx.stdout(`${ticket}: per-ticket execution history is not visible to an account key yet — read it at ${normalizeBaseUrl(cfg.baseUrl)}/settings`);
-        return 0;
-    }
+    // `explain --history` is the same read as `history <ticket>`; both go to CTC-1954's route.
+    if (flagBool(args, "history"))
+        return await cmdHistory(args, ctx, ticket);
     const { doc } = await loadContract(ctx, cfg);
     const dash = ticket.indexOf("-");
     if (dash <= 0)
@@ -124,33 +123,186 @@ export async function cmdExplain(args, ctx) {
     }
     return 0;
 }
+/**
+ * `running` — the fleet-wide "what is Catalyst doing right now?".
+ *
+ * ⛔ `/api/v1/lease/attributions` IS NOT A FLEET-WIDE ROUTE. It answers "who wrote this transition,
+ * holding which lease?" for ONE (ticket, phase) pair and 400s `invalid_field` without both — 0.2.0
+ * called it bare on every `running`, so the headline verb (and `whats-running.mjs`, and
+ * `snapshot.mjs`) failed for every tenant. The tenant-wide question is answered by
+ * `/fleet-activity/current` (what is executing) and `/agent-roster/current` (who is coordinating),
+ * neither of which takes coordinates. Lease attributions stay available, behind the coordinates the
+ * route requires.
+ */
 export async function cmdRunning(args, ctx) {
     const cfg = requireConfig(ctx);
+    const ticket = flagString(args, "ticket");
+    const phase = flagString(args, "phase");
+    if ((ticket === undefined) !== (phase === undefined)) {
+        throw new UsageError("running: --ticket and --phase go together — lease attributions are recorded per (ticket, phase), and the route refuses either one alone");
+    }
     const api = apiClient(cfg, ctx);
-    const [activity, roster, leases] = await Promise.all([
+    const [activity, roster] = await Promise.all([
         api.getJson("/api/v1/fleet-activity/current"),
         api.getJson("/api/v1/agent-roster/current"),
-        api.getJson("/api/v1/lease/attributions"),
     ]);
-    const out = { fleetActivity: activity.body, agentRoster: roster.body, leaseAttributions: leases.body };
+    const out = { fleetActivity: activity.body, agentRoster: roster.body };
+    if (ticket !== undefined && phase !== undefined) {
+        const leases = await api.getJson("/api/v1/lease/attributions", { query: { ticket, phase } });
+        out.leaseAttributions = leases.body;
+    }
     if (args.json) {
         ctx.stdout(JSON.stringify(out));
         return 0;
     }
     ctx.stdout(`fleet activity: ${JSON.stringify(out.fleetActivity)}`);
     ctx.stdout(`agent roster: ${JSON.stringify(out.agentRoster)}`);
-    ctx.stdout(`lease attributions: ${JSON.stringify(out.leaseAttributions)}`);
+    if (out.leaseAttributions !== undefined) {
+        ctx.stdout(`lease attributions (${ticket} ${phase}): ${JSON.stringify(out.leaseAttributions)}`);
+    }
     return 0;
 }
+/**
+ * `queue` — the dispatch order. The route is per-team and REQUIRES `?team=` ("bad team", 400), but
+ * a customer asking "what is next?" rarely means one team, so an omitted `--team` reads every team
+ * the tenant contract names rather than sending a call the route will refuse.
+ */
 export async function cmdQueue(args, ctx) {
     const cfg = requireConfig(ctx);
     const api = apiClient(cfg, ctx);
-    const res = await api.getJson("/api/v1/dispatch-queue/current", { query: { team: flagString(args, "team") } });
-    ctx.stdout(args.json ? JSON.stringify(res.body) : JSON.stringify(res.body, null, 2));
+    const named = flagString(args, "team");
+    let teams;
+    if (named !== undefined) {
+        teams = [named];
+    }
+    else {
+        const { doc } = await loadContract(ctx, cfg);
+        teams = doc.teams.map((t) => t.key).filter((k) => typeof k === "string" && k !== "");
+        if (teams.length === 0) {
+            throw new UsageError("queue needs --team: the tenant contract names no team to read a queue for");
+        }
+    }
+    const bodies = await Promise.all(teams.map(async (team) => [team, (await api.getJson("/api/v1/dispatch-queue/current", { query: { team } })).body]));
+    // One team asked for → its envelope, unwrapped, exactly as before. Several → keyed by team, so a
+    // caller can tell whose queue a row belongs to.
+    const out = bodies.length === 1 && named !== undefined ? bodies[0][1] : Object.fromEntries(bodies);
+    ctx.stdout(args.json ? JSON.stringify(out) : JSON.stringify(out, null, 2));
     return 0;
 }
-export function cmdAccounts(ctx) {
+/** The five status words `/api/v1/coding-accounts` reports, in the words a customer reads. */
+export const ACCOUNT_STATUS = {
+    "expired-or-revoked": "expired or revoked — re-enrol it before it can take work",
+    walled: "walled — the provider's usage limit is spent for now",
+    active: "active — observed working",
+    attested: "attested — healthy at last check, no work observed since",
+    unobserved: "unobserved — enrolled, but nothing has been seen from it yet",
+};
+/** One slot as a line a human reads: who it is, what state it is in, and what it is spending on. */
+export function renderAccount(a) {
+    const name = a.label ? `${a.accountSlot ?? "?"} (${a.label})` : (a.accountSlot ?? "?");
+    const harness = a.harness ? `/${a.harness}` : "";
+    const status = a.status ? (ACCOUNT_STATUS[a.status] ?? a.status) : "status unknown";
+    const bits = [`${name}  ${a.provider ?? "?"}${harness}  ${status}`];
+    if (typeof a.bindingUsedPercent === "number") {
+        const resets = typeof a.bindingResetsAtMs === "number" ? `, resets ${new Date(a.bindingResetsAtMs).toISOString()}` : "";
+        bits.push(`usage ${a.bindingUsedPercent}% of the ${a.bindingWindow ?? "binding"} window${resets}`);
+    }
+    if (a.quarantined)
+        bits.push(`quarantined${a.quarantineReason ? `: ${a.quarantineReason}` : ""}`);
+    const holds = a.liveHolds ?? [];
+    if (holds.length > 0)
+        bits.push(`holding ${holds.map((h) => `${h.ticket}/${h.phase}`).join(", ")}`);
+    else if (a.liveHoldsCount)
+        bits.push(`${a.liveHoldsCount} live hold(s)`);
+    return bits.join("  ·  ");
+}
+/**
+ * ⛔ A ROUTE THIS TENANT'S CLOUD DOES NOT SERVE IS SAID OUT LOUD, never rendered as an empty success.
+ * `GET /api/v1/coding-accounts` (CTC-1953) and `GET /api/v1/issues/:id/execution` (CTC-1954) ship
+ * ahead of some tenants' deployed mirror; a 404 there means "your cloud is older than this bundle",
+ * which is a different fact from "you have no coding accounts" and must never print as the latter.
+ */
+function needsNewerCloud(what, cfg) {
+    return new CliError(`${what} needs a newer Catalyst Cloud than ${normalizeBaseUrl(cfg.baseUrl)} is running — the route answered 404. Nothing is wrong with your tenant; ask your operator when the mirror last deployed.`, "route-not-deployed", 3, 404);
+}
+export async function cmdAccounts(args, ctx) {
     const cfg = requireConfig(ctx);
-    ctx.stdout(`coding-account status is not visible to an account key yet — read it at ${normalizeBaseUrl(cfg.baseUrl)}/settings/coding-accounts`);
+    const api = apiClient(cfg, ctx);
+    const res = await api.getJson("/api/v1/coding-accounts", {
+        accept: [404],
+    });
+    if (res.status === 404)
+        throw needsNewerCloud("coding-account status", cfg);
+    const accounts = Array.isArray(res.body) ? res.body : (res.body?.accounts ?? []);
+    if (args.json) {
+        ctx.stdout(JSON.stringify(res.body));
+        return 0;
+    }
+    if (accounts.length === 0) {
+        ctx.stdout(`No coding accounts are enrolled on this tenant — enrol one at ${normalizeBaseUrl(cfg.baseUrl)}/settings/coding-accounts`);
+        return 0;
+    }
+    for (const a of accounts)
+        ctx.stdout(renderAccount(a));
     return 0;
 }
+/**
+ * `history <ticket>` (and `explain --history`) — the ticket's execution history: per-phase attempts
+ * and outcomes, remediate rounds against the cap, the park sentinel and what releases it, the live
+ * lease, the last advance. Reads `GET /api/v1/issues/:identifier/execution` (CTC-1954).
+ */
+export async function cmdHistory(args, ctx, ticketArg) {
+    const ticket = ticketArg ?? positionals(args)[0];
+    if (!ticket)
+        throw new UsageError("history needs a ticket: history <ticket>");
+    const cfg = requireConfig(ctx);
+    const api = apiClient(cfg, ctx);
+    const res = await api.getJson(`/api/v1/issues/${encodeURIComponent(ticket)}/execution`, {
+        accept: [404],
+    });
+    if (res.status === 404)
+        throw needsNewerCloud(`execution history for ${ticket}`, cfg);
+    if (args.json) {
+        ctx.stdout(JSON.stringify(res.body));
+        return 0;
+    }
+    for (const line of renderHistory(ticket, res.body))
+        ctx.stdout(line);
+    return 0;
+}
+/** ⛔ `null` is UNREADABLE, never "nothing happened" — the report's own contract, kept in the prose. */
+export function renderHistory(ticket, doc) {
+    const lines = [];
+    if (doc.hasLadderHistory === false) {
+        lines.push(`${ticket}: no ladder history recorded${doc.note ? ` — ${doc.note}` : ""}.`);
+    }
+    const phases = doc.phases;
+    if (phases === null || phases === undefined) {
+        lines.push(`${ticket}: the per-phase table could not be read (unreadable, not empty).`);
+    }
+    else {
+        lines.push(`${ticket} phases (${doc.attemptHistory ?? "latest-per-phase"}):`);
+        for (const p of phases) {
+            const fail = p.lastFailureClass ? `, last failure ${p.lastFailureClass}${p.consecutiveFailures ? ` ×${p.consecutiveFailures}` : ""}` : "";
+            lines.push(`  ${p.phase}: ${p.status ?? "?"} (attempt ${p.attempt ?? "?"})${fail}`);
+        }
+    }
+    if (doc.failure) {
+        const f = doc.failure;
+        lines.push(`Last failure: ${f.phase} — ${f.failureMode}${f.failureDetail ? ` (${f.failureDetail})` : ""}${f.summary ? `: ${f.summary}` : ""}`);
+    }
+    if (doc.remediate && typeof doc.remediate.roundsDispatched === "number") {
+        lines.push(`Remediate rounds dispatched: ${doc.remediate.roundsDispatched}${typeof doc.remediate.cap === "number" ? ` (cap ${doc.remediate.cap})` : ""}`);
+    }
+    if (doc.park) {
+        lines.push(`Parked at ${doc.park.phase ?? "?"} (${doc.park.sentinel}): ${doc.park.selfReleases ? "releases itself" : "needs an operator"} — ${doc.park.releasedBy}`);
+    }
+    for (const l of doc.lease ?? [])
+        lines.push(`Live lease: ${l.phase} held by ${l.holder ?? "?"} until ${new Date(l.deadlineMs).toISOString()}`);
+    if (doc.lastAdvance) {
+        lines.push(`Last advance: ${doc.lastAdvance.phase} → ${doc.lastAdvance.toSlot ?? "?"} (${doc.lastAdvance.landed ? "landed" : "not landed"})`);
+    }
+    for (const u of doc.unreadable ?? [])
+        lines.push(`Unreadable: ${u.table} (${u.error}) — absent from this report, not absent from the ticket.`);
+    return lines;
+}

package/dist/http.js

@@ -31,6 +31,39 @@ export class ApiClient {
         await this.refuseIfNotOk(res, `GET ${path}`);
         return { status: res.status, body: await this.parseBody(res, `GET ${path}`), headers: res.headers };
     }
+    /**
+     * A GET whose success body is NDJSON — one JSON object per line, the shape `streamNdjson` sends.
+     *
+     * ⛔ `/changes` and `/snapshot` ANSWER NDJSON ON 200 AND JSON ON A REFUSAL, so a caller that only
+     * has `getJson` reads every real success as "returned a non-JSON body" while its refusals parse
+     * perfectly. That asymmetry is why `query changes` looked like it worked: nothing reached a 200.
+     * `accept` behaves as it does on `getJson` — those statuses come back with `rows: []` for the
+     * caller to branch on, and their (JSON) body is deliberately not parsed here.
+     */
+    async getNdjson(path, opts = {}) {
+        const url = this.url(path, opts.query);
+        const res = await this.send(url, {
+            method: "GET",
+            headers: { authorization: `Bearer ${this.cfg.key}`, accept: "application/x-ndjson, application/json" },
+        });
+        if (opts.accept?.includes(res.status))
+            return { status: res.status, body: [], headers: res.headers };
+        await this.refuseIfNotOk(res, `GET ${path}`);
+        const text = await res.text();
+        const rows = [];
+        for (const line of text.split("\n")) {
+            const trimmed = line.trim();
+            if (trimmed === "")
+                continue;
+            try {
+                rows.push(JSON.parse(trimmed));
+            }
+            catch {
+                throw new MeError(`GET ${path} returned a line that is not JSON: ${trimmed.slice(0, 120)}`, "shape");
+            }
+        }
+        return { status: res.status, body: rows, headers: res.headers };
+    }
     async postJson(path, body) {
         const url = this.url(path);
         const res = await this.send(url, {

package/dist/query.js

@@ -4,7 +4,7 @@
 // them and the read-model package is not a declared dependency of this bundle).
 import { flagInt, flagString, positionals } from "./args.js";
 import { requireConfig, replicaDbPath } from "./config.js";
-import { UsageError } from "./errors.js";
+import { CliError, UsageError } from "./errors.js";
 import { apiClient } from "./http.js";
 import { engineFor, replicaStatus } from "./replica.js";
 import { loadSdk } from "./sdk.js";
@@ -125,14 +125,52 @@ async function fromApi(ctx, cfg, sub, rest, f, args) {
         case "changes": {
             const since = flagString(args, "since");
             if (since === undefined)
-                throw new UsageError("changes needs --since <cursor>");
-            const res = await api.getJson("/api/v1/changes", { query: { since, limit: f.limit } });
-            return res.body;
+                throw new UsageError("changes needs --since <cursor>, or --since head to start from now");
+            return await readChanges(api, since, f.limit);
         }
         default:
             throw new UsageError(`unknown query subcommand: ${sub}`);
     }
 }
+/** CTC-137 stamps the live head seq on EVERY `/changes` response — the 200 stream and both 409s. */
+const HEAD_SEQ_HEADER = "x-catalyst-head-seq";
+/**
+ * `query changes --since <cursor|head>`.
+ *
+ * ⛔ THE CHANGEFEED EVICTS, so a refusal must name a cursor that works. `buildChanges` answers a
+ * `since` below the oldest retained seq with 409 `cursor_underflow`, and one past the head with 409
+ * `cursor_ahead_of_head` — both `{resync: true}`. `--since 0`, the form the docs show, is therefore
+ * a 409 on any tenant whose log has rotated, and 0.2.0 surfaced it as a bare "GET /api/v1/changes
+ * failed (409)" that left the customer with no way to learn a usable cursor. The head is stamped on
+ * the refusal itself, so there is always something actionable to say.
+ */
+async function readChanges(api, since, limit) {
+    const resolved = since === "head" ? String(await headCursor(api)) : since;
+    // ⛔ NDJSON ON 200, JSON ON A REFUSAL — see `getNdjson`. Reading this with `getJson` turned every
+    // real success into "returned a non-JSON body" while every refusal parsed, which is why the verb
+    // looked fine: `--since 0` 409s on a rotated feed, so no 200 was ever reached to fail on.
+    const res = await api.getNdjson("/api/v1/changes", {
+        query: { since: resolved, limit },
+        accept: [409],
+    });
+    const head = res.headers.get(HEAD_SEQ_HEADER);
+    if (res.status !== 409) {
+        return { since: Number(resolved), head: head === null ? null : Number(head), changes: res.body };
+    }
+    const where = head === null ? "" : ` The feed's live cursor is ${head}.`;
+    throw new CliError(`cursor ${resolved} is not usable: it is either past the feed's head or no longer in the change log, which keeps only recent changes.${where} Re-run with \`--since head\` to start from now, or with a cursor the feed still holds.`, "changefeed-resync", 1, 409);
+}
+/** The live head, read off any `/changes` response's own header — a 409 carries it too, which is
+ *  what makes this work on a tenant whose log has rotated past every cursor the caller could guess. */
+async function headCursor(api) {
+    const probe = await api.getNdjson("/api/v1/changes", { query: { since: "0", limit: 1 }, accept: [409] });
+    const raw = probe.headers.get(HEAD_SEQ_HEADER);
+    const head = raw === null ? Number.NaN : Number(raw);
+    if (!Number.isFinite(head)) {
+        throw new CliError(`--since head needs the feed's live cursor, and this cloud did not send one (no ${HEAD_SEQ_HEADER} header). Pass an explicit --since <cursor>.`, "changefeed-head-unknown", 1);
+    }
+    return head;
+}
 function needArg(rest, usage) {
     const v = rest[0];
     if (!v)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catalyst-cloud/catalyst-skills",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Customer skill bundle for Catalyst Cloud: eight skills named from the executive's seat (whats-happening, what-needs-me, run-this-project, catalyst-setup, catalyst-linear, catalyst-github, how-catalyst-works, connect-me) plus the catalyst-skills CLI that reads through the Catalyst Cloud SDK, writes through the agent proxy, and connects your machine to your tenant with one command.",
   "license": "MIT",
   "type": "module",
@@ -35,7 +35,7 @@
   "scripts": {
     "typecheck": "tsc --noEmit",
     "build": "tsc -p tsconfig.build.json",
-    "prepack": "tsc -p tsconfig.build.json",
+    "prepare": "tsc -p tsconfig.build.json",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
     "version:sync": "node scripts/sync-plugin-version.mjs"
@@ -47,6 +47,7 @@
     "@types/node": "^26.3.0",
     "@vitest/coverage-v8": "^4.1.11",
     "typescript": "^7.0.2",
-    "vitest": "^4.1.11"
+    "vitest": "^4.1.11",
+    "yaml": "^2.9.0"
   }
 }

package/skills/catalyst-github/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: catalyst-github
-description:
+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-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
 ---

package/skills/catalyst-linear/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: catalyst-linear
-description:
+description: >-
   Catalyst's view of Linear on the customer's own tenant. Reads a ticket with its comments, relations, labels, linked pull requests and agent sessions inline, from the local replica when it is fresh and the origin-fresh API otherwise, always naming the source; searches tickets, PRs, projects and initiatives; writes comments, card moves, labels and new tickets through the tenant's agent proxy as the app actor, with every route, stage id, label id and marker read from the tenant 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-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
 disable-model-invocation: true

package/skills/catalyst-setup/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: catalyst-setup
-description:
+description: >-
   Am I set up? Machine readiness (Node, the tenant connection, the cached contract, the CLI path, the skills, the SDK, the optional replica) plus tenant readiness from the contract's ten per-team checks, in one verdict: what passes, what is blocked, what is merely waiting, and who can click what. Use when someone asks "am I set up", "what is missing", "why does nothing happen", "is the replica running", or right after connecting a new machine. Reports; never repairs.
 allowed-tools: Bash(catalyst-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
 ---

package/skills/connect-me/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: connect-me
-description:
+description: >-
   Connect this machine to the customer's Catalyst Cloud tenant with their account key, cache the tenant contract, and verify. Use when a person is getting started, when their config is missing or broken, when they rotated their key, when a skill script exits 2 saying the machine is not connected, or when they ask which tenant this machine belongs to. The key names the tenant, so nobody types an account id. Installing the skills is not this skill's job; the agent's own install command did that.
 disable-model-invocation: true
 allowed-tools: Bash(catalyst-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)

package/skills/how-catalyst-works/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: how-catalyst-works
-description:
+description: >-
   How Catalyst Cloud runs a ticket on the customer's own tenant, as facts an agent loads on demand: the eight-phase ladder and what each phase produces, the eleven board slots and this team's live stage map, what happens when a phase fails (retry, backoff, Remediate, park), how the queue is ordered and routed and every reason a ticket is excluded, and the coding-account model. Use when a person asks "how does this work?", "why did it do that?", "why is this stuck?", "what runs next?" or "how does it prioritise?". Read-only; its scripts explain one ticket's eligibility in plain English, show what is running and queued, and print the tenant's stage map and thresholds straight from the contract.
 allowed-tools: Bash(catalyst-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
 ---

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

@@ -1,6 +1,6 @@
 ---
 name: run-this-project
-description:
+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 tenant stream for the scope through the catalyst-skills 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.
 disable-model-invocation: true
 allowed-tools: Bash(catalyst-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)

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

@@ -1,6 +1,6 @@
 ---
 name: what-needs-me
-description:
+description: >-
   The human's decision inbox on a Catalyst Cloud tenant, 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 what each answer releases, files an ask through the cloud's ask route with the tenant's own template, and records the answer so the held work releases. Never answers as the human, never duplicates an open ask.
 disable-model-invocation: true
 allowed-tools: Bash(catalyst-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)

package/skills/whats-happening/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: whats-happening
-description:
+description: >-
   The desk for a Catalyst Cloud tenant. Use when the person asks "what's happening?", "where are we?", "why is that stuck?", "what closed?", "what's next?", or asks for something to be done rather than known. Reads the tenant contract, what is running and queued, the eligibility explainer and the open asks through the catalyst-skills CLI, and answers in one reply with ticket ids. Routes work to a project owner and decisions to what-needs-me. Never composes a URL, never polls, never answers as the human.
 allowed-tools: Bash(catalyst-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
 ---