@catalyst-cloud/catalyst-skills 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.5.0
+
+The local replica can now keep the durable tenant event backbone beside its entity database. `catalyst-skills replica start` owns both synchronizers in one process, while `catalyst-skills events tail`, `events wait-for`, and `events query` read the bounded local cache with exact event-type and ticket filters. A failed event synchronizer is reported without stopping a healthy entity replica. This requires `@catalyst-cloud/sdk` 0.10.0 or newer.
+
+You can release a stuck ticket yourself now. `catalyst-skills release <ticket> --because "<what changed>"` asks your tenant to release every park or hold on the ticket the right way for each one — after repeated failures, a spent repair-round cap, a repair that changed nothing, a validate failure that recurred — or to release nothing and name, for each thing it will not release, what a person has to do instead (close their own pull request, read a review that will not converge, answer the ask for a spent repair budget). `--dry-run` previews it and changes nothing; `--retry-unchanged` says something changed that the cloud cannot see, such as an outage that ended; `release --class <failure-class> --team <key>` does the same for every ticket on one team parked for the same reason. A refusal exits 1. Every release is recorded against your login, and `explain --history` now prints what holds the ticket and the ticket's past releases. The new `unstick` skill runs the whole loop — read why nothing runs, read the history, judge whether the cause is fixed, preview, release — and raises an ask only for what needs a person; the desk, the project owner and the failure references no longer say a park needs an operator. The eligibility explanation knows seven more reasons, including a parked phase and a person's own pull request. Needs a cloud that serves the release route (tenant contract 1.6.0); an older cloud says so.
+
+Every skill's scripts now work for a machine connected with the keyless login. Since 0.4.0 a keyless `login` stores a login session and no key, and every skill script except the new `unstick` one read that as "not connected" and stopped before doing anything; only a personal key worked. The scripts now accept either, spawn the CLI, and let it authenticate and refresh the session as it always has. The check lives in one file vendored into every skill, so the next kind of credential lands once, and the not-connected line now names the keyless login first.
+
+## 0.4.1
+
+`explain` now tells you when a whole team cannot start work. A team whose stages are not saved (no stage chosen for dispatch, PR, done and canceled, or a chosen stage since deleted in Linear) gets no dispatch queue at all, and `explain` used to answer a ticket in that team's Todo with "state Todo is not a dispatch state" — which sent people looking at the wrong setting. It now says the ticket cannot start because the team has no saved stage mapping, names the missing stages, and names the fix: a tenant owner or admin opens Settings → Linear teams, picks the team and presses Map my stages (or Adopt the Catalyst workflow). Needs a cloud that sends the team's dispatch gate; an older cloud prints what it did before. The reason table's wording for `workflow_mapping_unknown` and `ordering_never_published` no longer reads as a passing hiccup, since neither clears on its own for an unmapped team. The references now say plainly that `teams[].gitAutomation` in the contract is a stored consent for a feature that is not built — nothing reads it, so it never starts or stops work — where they used to say enabling it could delete a team's review automation. The catalyst-setup reference gains a section on setting up one team at a time as a pilot: what starts, what stays where it is, and that no other team's stages or tickets change.
+
 ## 0.4.0
 
 You can connect keyless now: run `catalyst-skills login` with no key and it opens a browser device-code login — it prints a short code and a URL, you approve in your browser (or from your phone on a machine with no browser), and this machine is connected as you, with nothing to mint or paste. The short-lived session token refreshes silently on every request and the config is rewritten atomically each time, so you stay connected for months and log in again only if the session is revoked or you have been away long enough to lapse — then one clear line tells you to run `login`. `customer.json` now holds exactly one of a login session (`auth`) or a personal key; `status` names which ("Credential: your login (expires …)" vs "Credential: personal key"). The personal key rail is unchanged and remains the fallback for scripts and unattended shells — `--key` or `CATALYST_CLOUD_TOKEN` — and keyless is the preferred rail everywhere the docs and the connect-me skill lead with it. Under the hood the auth layer is reworked around one credential provider (SDK 0.9): the replica and the live watch use the SDK's bearer auth strategy and resolve a fresh token per connect, so an OAuth session rotates underneath a long-running watch without a reconnect, and every HTTP read and write refreshes on the same path.

package/README.md

@@ -18,7 +18,7 @@ Or by hand. One command, for every coding agent on the machine:
 npx skills@latest add coalesce-labs/catalyst-cloud-skills --all
 ```
 
-It installs all eight skills for each agent it detects (Claude Code, Codex, Cursor, OpenCode and the rest). Add `-g` to install into your home directory instead of the project. Skills installed this way do not auto-update; run `npx skills update -y` to refresh them.
+It installs all nine skills for each agent it detects (Claude Code, Codex, Cursor, OpenCode and the rest). Add `-g` to install into your home directory instead of the project. Skills installed this way do not auto-update; run `npx skills update -y` to refresh them.
 
 <details><summary><strong>Alternative for Claude Code: the plugin marketplace</strong></summary>
 
@@ -77,7 +77,7 @@ That is the whole setup. Everything below explains what you just installed.
 
 ## What this is
 
-Eight skills that let your coding agent run your own Catalyst Cloud tenant (https://staging.catalystcloud.dev) from your seat: what is happening, what needs you, and what to do about it. They read your tenant through the Catalyst Cloud SDK, write to it through the tenant's agent proxy, and never compose a URL or run a tool of their own; every read, write and subscription is a `catalyst-skills` verb with `--help`. Every skill is plain Markdown under `skills/<name>/SKILL.md` in this repository, and your own login — a keyless device-code session, or a personal key — is the only credential. Your agent acts as you: the asks it raises and the comments it posts carry your name, and "what needs me" means you.
+Nine skills that let your coding agent run your own Catalyst Cloud tenant (https://staging.catalystcloud.dev) from your seat: what is happening, what needs you, and what to do about it. They read your tenant through the Catalyst Cloud SDK, write to it through the tenant's agent proxy, and never compose a URL or run a tool of their own; every read, write and subscription is a `catalyst-skills` verb with `--help`. Every skill is plain Markdown under `skills/<name>/SKILL.md` in this repository, and your own login — a keyless device-code session, or a personal key — is the only credential. Your agent acts as you: the asks it raises and the comments it posts carry your name, and "what needs me" means you.
 
 ## What connecting does
 
@@ -112,12 +112,14 @@ Nothing, by default. After `login`, every read, write, ask and explanation goes
 | process | needed for | what it holds on disk | lifetime |
 | --- | --- | --- | --- |
 | none | every read, write, ask and explain | `customer.json` and `contract.json` | the default after login |
-| `catalyst-skills replica start` | local SQL, cheap repeated reads, `replica sql` and `replica schema` | one SQLite file (`~/.config/catalyst-cloud/replica.db`), a writer lock with a heartbeat beside it, and a cursor row inside the database | long-running; foreground by default, `--detach` writes a pidfile beside the database and returns; `login --start-replica` does the same at the end of login |
+| `catalyst-skills replica start` | local SQL, cheap repeated reads, and local event `tail`, `wait-for`, and `query` | one SQLite file plus a bounded event cache under `$XDG_STATE_HOME/catalyst/events/` (fallback `~/.local/state/catalyst/events/`) | one long-running process; foreground by default, `--detach` writes a pidfile beside the database and returns; `login --start-replica` does the same at the end of login |
 | `catalyst-skills watch` | a project owner reacting to its scope | one cursor file (`~/.config/catalyst-cloud/watch-cursor.json`) stamped with the tenant | lives inside the session that armed it; exits with it |
 
 The check every skill runs first is `catalyst-skills replica status`, which needs no network: is the pidfile's process alive, is the writer-lock heartbeat younger than the staleness threshold, and is the cursor non-empty. It exits `0` for fresh, `1` for present but stale, `2` for not connected, `3` for absent, and prints one line either way (`--json` for scripts). A fresh replica is used; anything else falls back to the API and the skill says so in its answer. A skill never refuses to work because the replica is down and never silently reads a stale one. `replica status --probe` compares the local cursor against the cloud's head for the honest "how far behind" number; that is the only form that touches the network. `catalyst-skills replica stop` stops a detached writer.
 
-Nothing rotates. The replica is upserts and deletes into one file, the cursor is a row, and the watch cursor is a few bytes; there is no directory of old files to clean. It is a Node process, not a service: the supported path is the plain command, and `skills/connect-me/references/keeping-the-replica-running.md` gives launchd and systemd examples for people who want the writer to survive a reboot.
+`catalyst-skills events tail` follows new cached events, `events wait-for --type ... --ticket ... --timeout ...` performs a bounded wait, and `events query` reads retained history. These commands never write the cache or contact the cloud. The replica process is the single writer and reports an event-sync failure without terminating a healthy entity replica. The event cache keeps closed daily segments for at most seven days or 256 MiB per tenant and reports an explicit gap when a requested sequence has retired.
+
+The replica is a Node process, not a service: the supported path is the plain command, and `skills/connect-me/references/keeping-the-replica-running.md` gives launchd and systemd examples for people who want the writer to survive a reboot.
 
 ## The skills
 
@@ -130,26 +132,26 @@ Nothing rotates. The replica is upserts and deletes into one file, the cursor is
 | `catalyst-linear` | "Show me the ticket, the history, what Catalyst wrote on it." | Reads a ticket with its comments, relations, labels, linked pull requests and agent sessions inline, from the replica when fresh and the API otherwise, always naming the source; writes comments, card moves, labels and new tickets as the app actor; knows what a ticket accumulates as Catalyst works it. | [`SKILL.md`](skills/catalyst-linear/SKILL.md) |
 | `catalyst-github` | "Show me the PR, the checks, the review, the queue." | A ticket's pull request with its checks, reviews and review threads; whether it is mergeable under the repository's policy; what a PR accumulates as the ticket moves (the branch, the draft, the rewrite, the force-pushes, the labels, the queue). | [`SKILL.md`](skills/catalyst-github/SKILL.md) |
 | `how-catalyst-works` | "How does this work? Why did it do that? How does it prioritise?" | The execution model as references loaded on demand: the eight-phase ladder, the eleven board slots and this team's live stage map, what happens when a phase fails, how the queue is ordered and routed, every exclusion reason, and the coding-account model. Scripts explain one ticket's eligibility in plain English. | [`SKILL.md`](skills/how-catalyst-works/SKILL.md) |
+| `unstick` | "Why is this parked? Unpark it. Get things flowing again." | Reads why a ticket is not running and every park or hold on it, decides whether the recorded cause is fixed, previews the release and releases it the right way from your own login — or one failure class across a team — and raises an ask only for what a person has to do. | [`SKILL.md`](skills/unstick/SKILL.md) |
 | `connect-me` | "Connect this machine to my tenant." | Connects the machine to the tenant with your own personal key, caches the tenant contract, verifies, and offers to start the replica. | [`SKILL.md`](skills/connect-me/SKILL.md) |
 
-Four skills only read (`whats-happening`, `catalyst-setup`, `catalyst-github`, `how-catalyst-works`). The four that write anything (`catalyst-linear`, `what-needs-me`, `run-this-project`, `connect-me`) are marked so an agent cannot invoke them on its own; the person asks for them. Every skill declares `allowed-tools` scoped to this package's own binary, so none of them needs a blanket shell grant.
+Four skills only read (`whats-happening`, `catalyst-setup`, `catalyst-github`, `how-catalyst-works`). The five that write anything (`catalyst-linear`, `what-needs-me`, `run-this-project`, `connect-me`, `unstick`) are marked so an agent cannot invoke them on its own; the person asks for them. Every skill declares `allowed-tools` scoped to this package's own binary, so none of them needs a blanket shell grant.
 
 ## What a key cannot see yet
 
-Your personal key reads everything the skills need — tickets, pull requests, the eligibility explainer, the dispatch queue, fleet activity, per-ticket execution history (`catalyst-skills explain --history <ticket>`: phase attempts, remediation rounds, park state) and coding-account status (`catalyst-skills accounts`: provider, declared and observed state, window usage, walls, quarantine — never a credential; enrolling or pausing one is `<your cloud>/settings/coding-accounts`). Two things it cannot do, and the skills say so by name rather than guess:
+Your personal key reads everything the skills need — tickets, pull requests, the eligibility explainer, the dispatch queue, fleet activity, per-ticket execution history (`catalyst-skills explain --history <ticket>`: phase attempts, remediation rounds, park state) and coding-account status (`catalyst-skills accounts`: provider, declared and observed state, window usage, walls, quarantine — never a credential; enrolling or pausing one is `<your cloud>/settings/coding-accounts`). It also releases a parked or held ticket once its cause is fixed: `catalyst-skills release <ticket> --because <what changed>` (the `unstick` skill runs it), recorded against your name and shown in the ticket's history. One thing it cannot do, and the skills say so by name rather than guess:
 
-- Release a park. When a ticket is parked after repeated failures, an operator releases it; the skill names the park and points at `<your cloud>/settings`.
 - Read pull-request labels or the reviewer's reaction. The mirror does not carry them; GitHub's own page does.
 
 ## Versions and origins
 
-The package pins the tenant contract range `1.x`, recorded in `package.json` under `catalystCloud.tenantContractRange`, and reports it in `--version`, `status` and `login`. A tenant whose contract version falls outside that range is refused with one line naming both versions; update the bundle. Every skill carries a `vendored-from:` line naming this package as its origin; all eight are written in this repository for customer tenants.
+The package pins the tenant contract range `1.x`, recorded in `package.json` under `catalystCloud.tenantContractRange`, and reports it in `--version`, `status` and `login`. A tenant whose contract version falls outside that range is refused with one line naming both versions; update the bundle. Every skill carries a `vendored-from:` line naming this package as its origin; all nine are written in this repository for customer tenants.
 
 ## What it writes on your machine
 
 - `~/.config/catalyst-cloud/customer.json`, written with mode `0600`, holding your personal key, who you are, and the CLI path.
 - `~/.config/catalyst-cloud/contract.json`, the cached tenant contract.
-- Only if you start them: `~/.config/catalyst-cloud/replica.db` with its `.pid` and `.writer.lock` sidecars, and `~/.config/catalyst-cloud/watch-cursor.json`.
+- Only if you start them: `~/.config/catalyst-cloud/replica.db` with its `.pid` and `.writer.lock` sidecars, `$XDG_STATE_HOME/catalyst/events/<tenant>/backbone/` (or the home-directory fallback) with bounded daily event segments, and `~/.config/catalyst-cloud/watch-cursor.json`.
 
 The skill files themselves are written by whichever install command you ran, in that tool's own location. Your personal key goes into that one config file and nowhere else.
 
@@ -165,12 +167,13 @@ A `customer.json` written by an older bundle is still read unchanged; it gains t
 
 ## Uninstalling
 
-Remove the skills the way you installed them: `/plugin uninstall catalyst@catalyst-cloud` in Claude Code, or delete the eight directories (`catalyst-github`, `catalyst-linear`, `catalyst-setup`, `connect-me`, `how-catalyst-works`, `run-this-project`, `what-needs-me`, `whats-happening`) from wherever `npx skills add` wrote them. Then remove what the CLI wrote:
+Remove the skills the way you installed them: `/plugin uninstall catalyst@catalyst-cloud` in Claude Code, or delete the nine directories (`catalyst-github`, `catalyst-linear`, `catalyst-setup`, `connect-me`, `how-catalyst-works`, `run-this-project`, `unstick`, `what-needs-me`, `whats-happening`) from wherever `npx skills add` wrote them. Then remove what the CLI wrote:
 
 ```sh
 catalyst-skills replica stop
 rm -f ~/.config/catalyst-cloud/customer.json ~/.config/catalyst-cloud/contract.json ~/.config/catalyst-cloud/watch-cursor.json
 rm -f ~/.config/catalyst-cloud/replica.db ~/.config/catalyst-cloud/replica.db.pid ~/.config/catalyst-cloud/replica.db.writer.lock
+rm -rf "${XDG_STATE_HOME:-$HOME/.local/state}/catalyst/events"
 npm uninstall -g @catalyst-cloud/catalyst-skills
 ```
 

package/dist/args.js

@@ -37,6 +37,14 @@ export const FLAG_TABLES = {
         probe: { value: false, help: "status: also fetch the cloud head and print the lag" },
         "stale-ms": { value: true, help: "status: heartbeat age that counts as stale (default 15000)" },
     },
+    events: {
+        type: { value: true, help: "exact event type" },
+        ticket: { value: true, help: "ticket identifier found in the event payload" },
+        after: { value: true, help: "event sequence to read after (tail/wait default to local head)" },
+        limit: { value: true, help: "query: maximum matching events (default 50)" },
+        timeout: { value: true, help: "wait-for: bounded wait in seconds (default 300)" },
+        directory: { value: true, help: "event cache directory (default: SDK XDG path)" },
+    },
     explain: {
         history: { value: false, help: "per-ticket execution history instead of the eligibility reason" },
     },
@@ -92,6 +100,14 @@ export const FLAG_TABLES = {
     },
     ready: {},
     accounts: {},
+    release: {
+        because: { value: true, help: "what changed since the ticket was held (required unless --dry-run)" },
+        "retry-unchanged": { value: false, help: "release even though nothing the mirror can see changed (say what did in --because)" },
+        "dry-run": { value: false, help: "show what a release would clear and refuse, and change nothing" },
+        class: { value: true, help: "release every ticket on --team parked under this failure class" },
+        team: { value: true, help: "with --class: the team key" },
+        limit: { value: true, help: "with --class: at most this many tickets (the cloud caps it at 25)" },
+    },
 };
 export const VERB_USAGE = {
     login: "login [--base-url <url>] [--start-replica]   (keyless; or --key <personal-key> / CATALYST_CLOUD_TOKEN)",
@@ -102,6 +118,7 @@ export const VERB_USAGE = {
     contract: "contract [--refresh] [--path <a.b.c>] [--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>]",
+    events: "events <tail|wait-for|query> [--type NAME] [--ticket CTC-N] [--after SEQUENCE] [--limit N] [--timeout SECONDS] [--directory PATH]",
     explain: "explain <ticket> [--history] [--json]",
     history: "history <ticket> [--json]",
     running: "running [--ticket T --phase P] [--json]",
@@ -111,6 +128,7 @@ export const VERB_USAGE = {
     ask: "ask <raise --team --title [--context] [--option]... [--default] --blocks <ticket>...|--nothing-to-block [--ask-key] | accept <askTicket> --answer <commentId> --role <role> | list [--anyone] [--json]>",
     ready: "ready [--json]",
     accounts: "accounts [--json]",
+    release: "release <ticket> --because <what changed> [--retry-unchanged] [--dry-run] [--json] | release --class <failure-class> --team <K> --because <what changed> [--retry-unchanged] [--dry-run] [--limit N] [--json]",
 };
 export function parseArgs(argv) {
     const out = {

package/dist/cli.js

@@ -12,12 +12,14 @@ import { cmdAccounts, cmdExplain, cmdHistory, cmdQueue, cmdRunning } from "./exe
 import { cmdQuery } from "./query.js";
 import { cmdReady } from "./ready.js";
 import { cmdReplica } from "./replica.js";
+import { cmdEvents } from "./events.js";
 import { stdinIsTty } from "./prompt.js";
 import { PROVENANCE_MARKER } from "./skill-shape.js";
 import { installSkills, parseChangelogEntry, readChangelog, resolveSkillsDir, skillsSourceDir, updateNoticeLine } from "./skills.js";
 import { cmdWatch } from "./watch.js";
 import { cmdWrite } from "./write.js";
 import { cmdAsk } from "./ask.js";
+import { cmdRelease } from "./release.js";
 export { CONFIG_MODE, DEFAULT_BASE_URL, PACKAGE_NAME, PROVENANCE_MARKER, CliError, MeError, UsageError, configPathFor, contractPathFor, defaultCtx, defaultReplicaDbFor, defaultSkillsDirFor, fetchMe, formatMode, installSkills, loadConfig, normalizeBaseUrl, parseArgs, parseChangelogEntry, readChangelog, readManifest, resolveSkillsDir, saveConfig, skillsSourceDir, updateNoticeLine, writeConfig, };
 export const CUSTOMER_SKILLS = [
     "catalyst-github",
@@ -26,6 +28,7 @@ export const CUSTOMER_SKILLS = [
     "connect-me",
     "how-catalyst-works",
     "run-this-project",
+    "unstick",
     "what-needs-me",
     "whats-happening",
 ];
@@ -47,10 +50,12 @@ export function usageText() {
         "  catalyst-skills contract [--refresh] [--path <a.b.c>]",
         "  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 events <tail|wait-for|query> [--type NAME] [--ticket CTC-N] [--after SEQUENCE]",
         "  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> ...",
+        "  catalyst-skills release <ticket> --because <what changed> [--retry-unchanged] [--dry-run] | release --class <c> --team <K> ...",
         "",
         "Every verb takes --help. --json makes the output machine-readable.",
         "",
@@ -151,6 +156,8 @@ export async function main(argv, ctx = defaultCtx(), deps = {}) {
                 return await cmdQuery(args, ctx, { engineDeps: deps.replica?.engineDeps });
             case "replica":
                 return await cmdReplica(args, ctx, deps.replica);
+            case "events":
+                return await cmdEvents(args, ctx, deps.events);
             case "explain":
                 return await cmdExplain(args, ctx);
             case "history":
@@ -169,6 +176,8 @@ export async function main(argv, ctx = defaultCtx(), deps = {}) {
                 return await cmdReady(args, ctx, { skillNames: CUSTOMER_SKILLS, loadSdk: deps.loadSdk });
             case "accounts":
                 return await cmdAccounts(args, ctx);
+            case "release":
+                return await cmdRelease(args, ctx);
             default:
                 ctx.stderr(`unknown command: ${args.command}`);
                 ctx.stderr(usageText());
@@ -192,7 +201,7 @@ export async function main(argv, ctx = defaultCtx(), deps = {}) {
         throw err;
     }
 }
-const VERB_HELP_KNOWN = Object.fromEntries(["login", "join", "install", "status", "notice", "me", "contract", "query", "replica", "explain", "running", "queue", "watch", "write", "ask", "ready", "accounts"].map((v) => [v, true]));
+const VERB_HELP_KNOWN = Object.fromEntries(["login", "join", "install", "status", "notice", "me", "contract", "query", "replica", "events", "explain", "running", "queue", "watch", "write", "ask", "ready", "accounts", "release"].map((v) => [v, true]));
 async function cmdLogin(args, ctx, deps) {
     const manifest = readManifest();
     const key = (args.key ?? ctx.env.CATALYST_CLOUD_TOKEN ?? "").trim();

package/dist/events.js

@@ -0,0 +1,106 @@
+import { flagInt, flagString, positionals } from "./args.js";
+import { apiBase, requireConfig } from "./config.js";
+import { CliError, UsageError } from "./errors.js";
+import { authStrategyFor } from "./oauth.js";
+const eventsModule = "@catalyst-cloud/sdk/events";
+export const loadEventsSdk = () => import(eventsModule);
+export async function createEventSync(ctx, deps = {}) {
+    const cfg = requireConfig(ctx);
+    const sdk = await (deps.loadSdk ?? loadEventsSdk)();
+    const auth = authStrategyFor(ctx, cfg);
+    if (auth.kind === "cookie")
+        throw new CliError("event sync requires a token or OAuth session", "events-auth");
+    return new sdk.CatalystEventSync({
+        baseUrl: apiBase(cfg),
+        auth,
+        tenantId: cfg.account,
+        fetch: ctx.fetch,
+    });
+}
+export async function cmdEvents(args, ctx, deps = {}) {
+    const [sub] = positionals(args);
+    if (!sub)
+        throw new UsageError("events needs a subcommand: tail | wait-for | query");
+    if (!["tail", "wait-for", "query"].includes(sub))
+        throw new UsageError(`unknown events subcommand: ${sub}`);
+    const cfg = requireConfig(ctx);
+    const sdk = await (deps.loadSdk ?? loadEventsSdk)();
+    const directory = flagString(args, "directory") ??
+        sdk.defaultEventCacheDirectory(cfg.account);
+    const after = startingCursor(args, sub === "query");
+    const matches = matcher(args);
+    if (sub === "query") {
+        const events = (await sdk.readCachedEvents({ tenantId: cfg.account, directory, after }))
+            .filter(matches)
+            .slice(-flagInt(args, "limit", 50));
+        for (const event of events)
+            ctx.stdout(JSON.stringify(event));
+        return 0;
+    }
+    const controller = new AbortController();
+    const abort = () => controller.abort(deps.signal?.reason);
+    if (deps.signal?.aborted)
+        abort();
+    else
+        deps.signal?.addEventListener("abort", abort, { once: true });
+    const timer = sub === "wait-for"
+        ? setTimeout(() => controller.abort(new Error("event wait timed out")), flagInt(args, "timeout", 300) * 1_000)
+        : undefined;
+    try {
+        for await (const event of sdk.tailCachedEvents({
+            tenantId: cfg.account,
+            directory,
+            after,
+            signal: controller.signal,
+        })) {
+            if (!matches(event))
+                continue;
+            ctx.stdout(JSON.stringify(event));
+            if (sub === "wait-for")
+                return 0;
+        }
+        return sub === "wait-for" ? 1 : 0;
+    }
+    catch (error) {
+        if (controller.signal.aborted)
+            return sub === "wait-for" ? 1 : 0;
+        if (error.code === "ENOENT")
+            throw new CliError(`event cache is absent at ${directory} — start it with: catalyst-skills replica start --detach`, "events-absent", 3);
+        throw error;
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+        deps.signal?.removeEventListener("abort", abort);
+    }
+}
+function startingCursor(args, history) {
+    const requested = flagString(args, "after");
+    if (requested !== undefined) {
+        const parsed = Number(requested);
+        if (!Number.isSafeInteger(parsed) || parsed < 0)
+            throw new UsageError("--after must be a non-negative event sequence");
+        return parsed;
+    }
+    if (history)
+        return undefined;
+    return undefined;
+}
+function matcher(args) {
+    const type = flagString(args, "type");
+    const ticket = flagString(args, "ticket")?.toUpperCase();
+    return (event) => (!type || event.type === type) &&
+        (!ticket || payloadReferences(event.payload, ticket));
+}
+function payloadReferences(value, ticket) {
+    if (typeof value === "string")
+        return value.toUpperCase() === ticket;
+    if (Array.isArray(value))
+        return value.some((item) => payloadReferences(item, ticket));
+    if (!value || typeof value !== "object")
+        return false;
+    return Object.entries(value).some(([key, item]) => ["ticket", "identifier", "workItemKey", "issueIdentifier"].includes(key) &&
+        typeof item === "string"
+        ? item.toUpperCase() === ticket
+        : payloadReferences(item, ticket));
+}

package/dist/execution.js

@@ -37,13 +37,20 @@ export const EXCLUSION_REASONS = {
     retry_backoff: "the failed phase is retrying in place and waiting out its backoff",
     routing_unavailable: "the unit was claimed and refused at kickoff (no route, no eligible coding-account slot, or the provider is unavailable)",
     repo_paused: "an operator paused the repository",
-    remediate_parked: "the remediate phase is parked, so the failing phase has nowhere to be repaired",
+    remediate_parked: "the remediate phase is parked, so the failing phase has nowhere to be repaired; `catalyst-skills release <ticket>` releases the park once its cause is fixed",
+    phase_parked: "the offered phase is parked after repeated failures or the repair-round cap; `catalyst-skills release <ticket>` releases it once its cause is fixed",
+    later_phase_lease_held: "an earlier phase is offered while a live container still holds a later phase of this ticket",
+    human_owned_pr: "a person's own pull request holds this ticket; it releases itself when that PR closes or merges",
+    review_not_converging: "review and repair kept finding new problems without converging; a person reads the findings and comments on the ticket to resume",
+    round_threshold: "the ticket spent its lifetime repair budget; answering its ask or pushing a fix buys one more cycle",
+    claim_storm: "this unit was claimed too many times in the last hour, so it waits out the hour; nothing to release",
+    repo_at_capacity: "the repository's runner seats are all in use; it starts when one frees",
 };
 /** Every fail-closed unknown the evaluator names. */
 export const UNKNOWN_REASONS = {
-    ordering_never_published: "the dispatch order has never been published for this team",
+    ordering_never_published: "the dispatch order has never been published for this team — usually because the team has no saved stage mapping, which does not clear by itself",
     ordering_stale: "the dispatch order is stale",
-    workflow_mapping_unknown: "the team's workflow mapping could not be read",
+    workflow_mapping_unknown: "the team has no saved stage mapping for dispatch, pr, done and canceled (or a mapped stage was deleted); it does not clear by itself — a tenant owner or admin maps the team in Settings → Linear teams",
     ticket_unknown: "the ticket is not in the mirror",
     dependency_snapshot_unknown: "the dependency snapshot has never completed",
     blocker_unknown: "a blocking relation could not be resolved",
@@ -61,7 +68,20 @@ export function describeReason(reason) {
         return "no reason was given";
     return EXCLUSION_REASONS[reason] ?? UNKNOWN_REASONS[reason] ?? `reason "${reason}" (not in this bundle's table; read it as the cloud spelled it)`;
 }
-export function renderExplain(ticket, row, team, knownState) {
+export function renderDispatchGate(ticket, team, gate) {
+    const slots = (gate.missingSlots ?? []).join(", ");
+    const why = gate.cause === "mapping_state_unresolved"
+        ? `the stage team ${team} mapped for ${slots} no longer exists in Linear.`
+        : gate.cause === "mapping_missing"
+            ? `team ${team} has no saved stage mapping for ${slots}.`
+            : `team ${team} cannot be dispatched (${gate.cause}).`;
+    return [`${ticket} cannot start: ${why}`, gate.remedy].filter(Boolean).join(" ");
+}
+export function renderExplain(ticket, row, team, knownState, gate) {
+    // An unmapped team has no queue and so no rows; its gate is the whole answer, and it outranks the
+    // Backlog probe below, which would otherwise call the team's own Todo "not a dispatch state".
+    if (gate)
+        return renderDispatchGate(ticket, team, gate);
     if (!row) {
         // A null dispatch row is not proof the ticket does not exist — the explainer is a dispatch scan. When
         // `knownState` is set (the mirror answered GET /issues/:id) the ticket is real; it just sits outside a
@@ -130,11 +150,15 @@ export async function cmdExplain(args, ctx) {
         if (probe.status !== 404)
             knownState = typeof probe.body?.state === "string" ? probe.body.state : "unknown";
     }
+    // The gate is TEAM-wide: it can say why a real ticket in that team cannot start, never that this id
+    // exists. Applied only when the mirror probe above found the ticket; a 404 keeps the unknown wording.
+    const gate = !row && knownState ? (res.body.eligibility?.dispatchGate ?? null) : null;
+    const explanation = renderExplain(ticket, row, team, knownState, gate);
     if (args.json) {
-        ctx.stdout(JSON.stringify({ ticket, row, explanation: renderExplain(ticket, row, team, knownState) }));
+        ctx.stdout(JSON.stringify({ ticket, row, ...(gate ? { dispatchGate: gate } : {}), explanation }));
     }
     else {
-        ctx.stdout(renderExplain(ticket, row, team, knownState));
+        ctx.stdout(explanation);
     }
     return 0;
 }
@@ -237,7 +261,7 @@ export function renderAccount(a) {
  * 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) {
+export 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) {
@@ -310,7 +334,29 @@ export function renderHistory(ticket, doc) {
         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}`);
+        lines.push(`Parked at ${doc.park.phase ?? "?"} (${doc.park.sentinel}): ${doc.park.selfReleases ? "releases itself" : "does not release itself"} — ${doc.park.releasedBy}`);
+    }
+    // Absent (an older cloud) prints nothing; `null` is a table that could not be read.
+    if (doc.governors === null) {
+        lines.push("Held by: could not be read (unreadable, not empty)");
+    }
+    else if (doc.governors !== undefined && doc.governors.length > 0) {
+        lines.push("Held by:");
+        for (const g of doc.governors) {
+            lines.push(`  ${g.kind}${g.phase ? ` at ${g.phase}` : ""}${g.sentinel ? ` (${g.sentinel})` : ""} — ${g.release ?? "no release named"}`);
+        }
+    }
+    if (doc.releases === null) {
+        lines.push("Releases: could not be read (unreadable, not empty)");
+    }
+    else if (doc.releases !== undefined && doc.releases.length > 0) {
+        lines.push("Releases (newest first):");
+        for (const r of doc.releases) {
+            const what = r.outcome === "released"
+                ? `released: ${(r.released ?? []).map((a) => `${a.op}${a.phase ? ` ${a.phase}` : ""}`).join(", ")}`
+                : `refused: ${(r.refused ?? []).map((x) => x.code).join(", ")}`;
+            lines.push(`  ${new Date(r.atMs).toISOString()} ${r.outcome} by ${r.actor.kind}:${r.actor.id} — "${r.because}" — ${what}`);
+        }
     }
     for (const l of doc.lease ?? [])
         lines.push(`Live lease: ${l.phase} held by ${l.holder ?? "?"} until ${new Date(l.deadlineMs).toISOString()}`);

package/dist/release.js

@@ -0,0 +1,142 @@
+// release.ts — `catalyst-skills release`: a person's release of a parked or held ticket, or of every
+// ticket on one team parked under one failure class, through the contract's `ticket-release` and
+// `ticket-release-class` routes. The cloud reads every governor holding the ticket and either releases
+// all of them or releases nothing and names, per governor, the human action that does fix it; this verb
+// prints that answer and exits 1 on a refusal so a script can branch on it.
+//
+// ⛔ NOTHING IS RELEASED WITHOUT A REASON. `--because` (what changed) is required on a real release and
+// is recorded in the tenant's release audit; only `--dry-run` may omit it. `--retry-unchanged` is the
+// explicit statement that something the mirror cannot see changed — the cloud refuses an unchanged
+// cause without it.
+import { flagBool, flagString, positionals } from "./args.js";
+import { requireConfig } from "./config.js";
+import { loadContract } from "./contract.js";
+import { CliError, UsageError } from "./errors.js";
+import { needsNewerCloud } from "./execution.js";
+import { apiClient } from "./transport.js";
+/** One release written as a person reads it: "unparked implement", "cleared the validate hold". */
+export function describeAction(a) {
+    switch (a.op) {
+        case "unpark":
+            return `unparked ${a.phase ?? "a phase"}`;
+        case "clear_validate_hold":
+            return "cleared the validate hold";
+        case "clear_no_change_hold":
+            return "cleared the no-change hold";
+        case "grant_round_threshold_cycle":
+            return "bought one more repair cycle";
+        default:
+            return `${a.op}${a.phase ? ` at ${a.phase}` : ""}`;
+    }
+}
+const refusalLine = (r) => `  ${r.code}: ${r.humanAction}`;
+export function renderTicketRelease(ticket, r) {
+    if (r.error === "team_changed") {
+        return [`${ticket} moved from team ${r.expectedTeamKey ?? "(none)"} to ${r.teamKey ?? "(none)"} while the release was being checked — run it again`];
+    }
+    const lines = [];
+    const dry = r.dryRun === true;
+    if (r.outcome === "nothing-held") {
+        lines.push(`${ticket}: nothing holds this ticket — run \`catalyst-skills explain ${ticket}\` for why it is not running`);
+    }
+    else if (r.outcome === "refused") {
+        lines.push(dry ? `${ticket} (dry run): would be refused — nothing would be released:` : `${ticket}: refused — nothing was released:`);
+        for (const x of r.refused ?? [])
+            lines.push(refusalLine(x));
+        const blocked = r.releasable ?? [];
+        if (blocked.length > 0)
+            lines.push(`  (it would otherwise have ${blocked.map(describeAction).join(", ")})`);
+    }
+    else if (dry) {
+        lines.push(`${ticket} (dry run): would release — ${(r.releasable ?? []).map(describeAction).join(", ")}`);
+    }
+    else {
+        lines.push(`${ticket}: released — ${(r.released ?? []).map(describeAction).join(", ")}`);
+    }
+    for (const w of r.warnings ?? [])
+        lines.push(`warning: ${w}`);
+    return lines;
+}
+export function renderClassRelease(r) {
+    const released = r.released ?? [];
+    const refused = r.refused ?? [];
+    const nothing = r.nothingHeld ?? [];
+    const head = `${r.team ?? "?"} ${r.class ?? "?"}${r.dryRun ? " (dry run)" : ""}: released ${released.length}, refused ${refused.length}, nothing held ${nothing.length}${r.truncated ? " (more remain — run it again)" : ""}`;
+    const lines = [head];
+    for (const t of released) {
+        const actions = r.dryRun ? (t.releasable ?? []) : (t.released ?? []);
+        lines.push(`  ${r.dryRun ? "would release" : "released"} ${t.ticket ?? "?"}: ${actions.map(describeAction).join(", ")}`);
+    }
+    for (const t of refused) {
+        for (const x of t.refused ?? [])
+            lines.push(`  refused ${t.ticket ?? "?"} — ${x.code}: ${x.humanAction}`);
+    }
+    if (nothing.length > 0)
+        lines.push(`  nothing held: ${nothing.join(", ")}`);
+    return lines;
+}
+/** The contract's route by name, or the "your cloud is older" error when this tenant does not serve it. */
+function releaseRoute(doc, name, cfg) {
+    const route = doc.routes.find((r) => r.method === "POST" && r.path.split("/").filter(Boolean).at(-1) === name);
+    if (!route)
+        throw needsNewerCloud(`release (the tenant contract serves no "${name}" route)`, cfg);
+    return route.path;
+}
+export async function cmdRelease(args, ctx) {
+    const [ticket, ...extra] = positionals(args);
+    const failureClass = flagString(args, "class");
+    const team = flagString(args, "team");
+    const because = flagString(args, "because");
+    const dryRun = flagBool(args, "dry-run");
+    const retryUnchanged = flagBool(args, "retry-unchanged");
+    if (extra.length > 0)
+        throw new UsageError("release takes one ticket");
+    if (failureClass !== undefined && ticket !== undefined) {
+        throw new UsageError("release takes a ticket or --class with --team, not both");
+    }
+    if (failureClass === undefined && ticket === undefined) {
+        throw new UsageError("release needs a ticket, or --class <failure-class> --team <K>");
+    }
+    if (failureClass !== undefined && team === undefined)
+        throw new UsageError("release --class needs --team <K>");
+    if (because === undefined && !dryRun) {
+        throw new UsageError("release needs --because <what changed> (recorded in the release audit), or --dry-run to preview");
+    }
+    const limitRaw = flagString(args, "limit");
+    const limit = limitRaw === undefined ? undefined : Number(limitRaw);
+    if (limit !== undefined && !Number.isInteger(limit))
+        throw new UsageError("--limit must be an integer");
+    const cfg = requireConfig(ctx);
+    const { doc } = await loadContract(ctx, cfg);
+    const api = apiClient(cfg, ctx);
+    const common = { ...(because !== undefined ? { because } : {}), retryUnchanged, dryRun };
+    if (failureClass !== undefined) {
+        const path = releaseRoute(doc, "ticket-release-class", cfg);
+        const res = await api.postJson(path, {
+            team,
+            class: failureClass,
+            ...common,
+            ...(limit !== undefined ? { limit } : {}),
+        });
+        if (args.json)
+            ctx.stdout(JSON.stringify(res.body));
+        else
+            for (const line of renderClassRelease(res.body))
+                ctx.stdout(line);
+        // A real class release that refused any ticket exits 1, the same contract as a single refusal.
+        return res.body.dryRun !== true && (res.body.refused ?? []).length > 0 ? 1 : 0;
+    }
+    const id = ticket;
+    const path = releaseRoute(doc, "ticket-release", cfg);
+    const res = await api.postJson(path, { ticket: id, ...common }, { accept: [404, 409] });
+    if (res.status === 404) {
+        throw new CliError(`ticket ${id} is not in this tenant's mirror — check the identifier`, "ticket-unknown");
+    }
+    if (args.json)
+        ctx.stdout(JSON.stringify(res.body));
+    else
+        for (const line of renderTicketRelease(id, res.body))
+            ctx.stdout(line);
+    const refused = res.status === 409 || (res.body.outcome === "refused" && res.body.dryRun !== true);
+    return refused ? 1 : 0;
+}

package/dist/replica.js

@@ -13,6 +13,7 @@ import { CliError, UsageError } from "./errors.js";
 import { apiClient } from "./transport.js";
 import { authStrategyFor } from "./oauth.js";
 import { loadSdk } from "./sdk.js";
+import { createEventSync } from "./events.js";
 export const DEFAULT_STALE_MS = 15_000;
 export function pidfilePath(dbPath) {
     return `${dbPath}.pid`;
@@ -214,7 +215,11 @@ async function cmdStart(args, ctx, cfg, dbPath, deps) {
         onStatus: (s) => ctx.stderr(`[replica] status=${s}`),
     });
     await replica.start();
-    ctx.stdout(`replica live at ${dbPath} (cursor ${replica.cursor ?? "none"}) — Ctrl-C to stop`);
+    const eventSync = await createEventSync(ctx, { loadSdk: deps.loadEventsSdk });
+    void eventSync.start().catch((error) => {
+        ctx.stderr(`[events] sync failed: ${error instanceof Error ? error.message : String(error)}; replica remains live`);
+    });
+    ctx.stdout(`replica live at ${dbPath} (cursor ${replica.cursor ?? "none"}); event cache active — Ctrl-C to stop`);
     const wait = deps.waitForStop ??
         (() => new Promise((resolve) => {
             const done = () => resolve();
@@ -222,6 +227,7 @@ async function cmdStart(args, ctx, cfg, dbPath, deps) {
             process.once("SIGTERM", done);
         }));
     await wait();
+    await eventSync.stop();
     await replica.close();
     try {
         if (readPidfile(dbPath) === process.pid)

package/dist/transport.js

@@ -70,7 +70,9 @@ export class ApiClient {
         }
         return { status: res.status, body: rows, headers: res.headers };
     }
-    async postJson(path, body) {
+    /** `opts.accept` lists non-2xx statuses returned to the caller with their JSON body instead of thrown
+     *  — the release route answers a refusal as 409 with the refusals the caller has to print. */
+    async postJson(path, body, opts = {}) {
         const url = this.url(path);
         const res = await this.send(url, {
             method: "POST",
@@ -81,7 +83,8 @@ export class ApiClient {
             },
             body: JSON.stringify(body),
         });
-        await this.refuseIfNotOk(res, `POST ${path}`);
+        if (!opts.accept?.includes(res.status))
+            await this.refuseIfNotOk(res, `POST ${path}`);
         return { status: res.status, body: await this.parseBody(res, `POST ${path}`), headers: res.headers };
     }
     async send(url, init) {