@catalyst-cloud/cli 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.9.0
+
+Onboarding now guides your own Linear and GitHub consent. `catalyst connections personal <linear|github> start` opens the provider's consent page in your browser and `status` confirms the grant landed; the tenant's own Linear connection and GitHub App install stay separate, and personal GitHub waits until the App is installed and a repository is registered.
+
+An unmatched Linear identity can be fixed from the terminal: `catalyst identity linear status`, `options` and `set <linearUserId>` choose your Linear user from the roster and read the choice back. An existing match is never replaced.
+
+The local replica and event cache report whether they are current. `catalyst replica status --probe` and `catalyst events status --probe` compare each local feed with its cloud head and require a live writer; onboarding starts the writer only when you opt in, and a missing local cache never blocks setup.
+
+Register, list and remove MCP servers with `catalyst mcp`, using vault-secret names for authentication. Custom HTTPS servers wait for account-admin approval; query strings, userinfo and fragments are refused. The cloud side shipped on 2026-09-28; registration does not yet make a server callable through the portal.
+
+This release needs `@catalyst-cloud/sdk` 0.12. `@catalyst-cloud/catalyst-skills` is deprecated in favour of `@catalyst-cloud/cli`; it still installs and forwards to this version.
+
 ## 0.8.0
 
 `catalyst-skills ready` loads the SDK on Node 26, the current Homebrew default, and has since 0.7.0: the type-stripping loader tries Node's `strip` mode before `transform`, because Node 26 accepts only `strip`. The 0.7.0 entry did not say so. If you saw `sdk: could not load` on Node 26 on 0.5.0 or earlier, updating is the fix.

package/README.md

@@ -84,7 +84,19 @@ CATALYST_CLOUD_TOKEN=<your-personal-key> catalyst-skills login
 
 `--key <your-personal-key>` is the third form, for a script.
 
-That is the whole setup. Everything below explains what you just installed.
+After a tenant owner connects the tenant's Linear workspace, connect your personal Linear account. Connect your personal GitHub account only after the tenant's GitHub App is installed and its repository is registered. These personal grants are separate from the tenant's Linear connection and GitHub App installation. Your agent can start each connection and check whether it landed, but you approve each one in your browser:
+
+```sh
+catalyst-skills connections personal linear start
+catalyst-skills connections personal linear status
+# First install the tenant's GitHub App and register its repository in Settings.
+catalyst-skills connections personal github start
+catalyst-skills connections personal github status
+```
+
+Each `start` prints a short-lived URL and attempts to open your browser. On a remote machine, open the printed URL on your own device. `status --json` gives the same result to an agent; `start --wait 60` waits up to one minute for approval. A connected result is the proof that the grant landed. If a provider reports unavailable, retry status later rather than starting a second approval.
+
+The `catalyst-onboard` skill checks both grants before taking you through the rest of tenant setup and the first ticket.
 
 ## What this is
 
@@ -128,7 +140,7 @@ Nothing, by default. After `login`, every read, write, ask and explanation goes
 
 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.
 
-`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.
+`catalyst-skills events status --probe` checks the event cache's own cursor and compares it with the cloud head; `replica status --probe` checks the separate entity-replica cursor. A fresh replica does not prove event freshness. `events tail` follows new cached events, `events wait-for --ticket ... --timeout ...` performs a bounded wait, and `events query` reads retained history. Those three commands only read the cache; `events status --probe` makes the cloud comparison. 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.
 
@@ -136,7 +148,7 @@ The replica is a Node process, not a service: the supported path is the plain co
 
 | skill | what the person says | what it does | file |
 | --- | --- | --- | --- |
-| `catalyst-onboard` | "Set me up. Onboard me. I just signed up — what do I do first?" | Walks you from nothing to your first ticket running, one step at a time: connect this machine, connect Linear, map one project, register one repository, then watch a card move. Reads each part of setup with the instrument that owns it and says who can fix anything unfinished and where. Hands over the steps only a browser can do instead of pretending to have done them. | [`SKILL.md`](skills/catalyst-onboard/SKILL.md) |
+| `catalyst-onboard` | "Set me up. Onboard me. I just signed up — what do I do first?" | Walks you from nothing to your first ticket running, one step at a time: connect this machine, connect the tenant and your personal provider accounts, map one project, register one repository, then watch a card move. Reads each part of setup with the instrument that owns it and says who can fix anything unfinished and where. Hands over browser consent and settings steps without claiming they happened until a status check confirms them. | [`SKILL.md`](skills/catalyst-onboard/SKILL.md) |
 | `whats-happening` | "What's happening? Where are we? Why is that stuck? What's next?" | The desk for a tenant: reads the contract, what is running and queued, the eligibility explainer and the open asks, and answers in one reply with ticket ids. Routes work to a project owner and decisions to `what-needs-me`. | [`SKILL.md`](skills/whats-happening/SKILL.md) |
 | `what-needs-me` | "What needs me? What am I blocking?" | The human's decision inbox, ranked by what each answer releases, and the one way an agent raises a decision on their behalf: files an ask through the cloud's ask route with the tenant's own template and records the answer so the held work releases. | [`SKILL.md`](skills/what-needs-me/SKILL.md) |
 | `run-this-project` | "Run this project for me. Own it until it closes." | Single-threaded owner of one project: subscribes to the tenant stream for its scope, 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. Never polls. | [`SKILL.md`](skills/run-this-project/SKILL.md) |
@@ -203,3 +215,15 @@ npm uninstall -g @catalyst-cloud/catalyst-skills
 ## License
 
 MIT — see [LICENSE](LICENSE). How to contribute and how releases happen are described in [CONTRIBUTING.md](CONTRIBUTING.md). The install commands above are one canonical block kept in [`.agents/install-block.md`](.agents/install-block.md); change them there first.
+
+### Unmatched Linear identity
+
+Personal Linear consent normally binds the provider viewer automatically. For an unmatched identity, inspect your choices and explicitly select yourself:
+
+```sh
+catalyst-skills identity linear status
+catalyst-skills identity linear options --json
+catalyst-skills identity linear set <linearUserId>
+```
+
+The command uses your personal credential and reads the result back after selection. It cannot change another member, replace an automatic match, or take an already-claimed identity. A missing options field means no choice was offered, which can include a temporarily unreadable roster. This command depends on the pending SDK 0.12.0 release with identity support.

package/dist/args.js

@@ -14,6 +14,12 @@ export const FLAG_TABLES = {
     login: {
         "start-replica": { value: false, help: "run `replica start --detach` after connecting" },
     },
+    mcp: {
+        url: { value: true, help: "add: the upstream HTTPS endpoint" },
+        auth: { value: true, help: "add: none for an unauthenticated upstream" },
+        bearer: { value: true, help: "add: vault secret NAME for a bearer token, never its value" },
+        header: { value: true, repeat: true, help: "add: HEADER_NAME=VAULT_SECRET_NAME (repeatable)" },
+    },
     install: {},
     status: {},
     notice: {},
@@ -39,6 +45,7 @@ export const FLAG_TABLES = {
         "stale-ms": { value: true, help: "status: heartbeat age that counts as stale (default 15000)" },
     },
     events: {
+        probe: { value: false, help: "status: compare the local event cursor with the cloud event head" },
         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)" },
@@ -116,6 +123,10 @@ export const FLAG_TABLES = {
         command: { value: true, help: "set: run this command on this machine and store its output (e.g. 'op read op://Vault/item/field'); the command text is audited, so never put a value in it" },
         rotate: { value: true, repeat: true, help: "import: replace this name if it is already set (repeatable)" },
     },
+    identity: {},
+    connections: {
+        wait: { value: true, help: "start: wait up to this many seconds for browser approval (0-600)" },
+    },
     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)" },
@@ -135,7 +146,7 @@ export const VERB_USAGE = {
     query: "query <issues|issue <id>|pulls|pull <id>|projects|cycles|search <terms>|changes --since <cursor|head>> [--team K] [--project P] [--state S] [--limit N] [--all] [--source replica|api] [--json]",
     replica: "replica <start [--detach]|stop|status [--probe] [--json]|sql \"<select>\"|schema [table]> [--db <path>]",
     runtime: "runtime <status [--json]|install|path|uninstall>",
-    events: "events <tail|wait-for|query> [--type NAME] [--ticket CTC-N] [--after SEQUENCE] [--limit N] [--timeout SECONDS] [--directory PATH]",
+    events: "events <tail|wait-for|query|status [--probe] [--json]> [--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]",
@@ -145,8 +156,11 @@ 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] [--offline]",
     accounts: "accounts [--json]",
+    mcp: "mcp <add <name> --url URL <--auth none|--bearer SECRET_NAME|--header NAME=SECRET_NAME...>|list|remove <name>> [--json]",
     environment: "environment [read] [--json] | environment propose --file <path>|--stdin [--expect-revision N] [--approve] [--json] | environment approve [--revision N --hash H] [--json]",
     secret: "secret set <NAME> --repo <owner/name> [--command '<cmd>'] [--json]   (value from --command, stdin, or a hidden prompt) | secret import <file> --repo <owner/name> [--rotate NAME]... [--json]",
+    identity: "identity linear <status|options|set> [<linearUserId>] [--json]",
+    connections: "connections personal <linear|github> <start|status> [--wait <seconds>] [--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) {

package/dist/cli.js

@@ -20,9 +20,12 @@ import { installedBundleVersion, installSkills, parseChangelogEntry, readChangel
 import { cmdWatch } from "./watch.js";
 import { cmdWrite } from "./write.js";
 import { cmdAsk } from "./ask.js";
+import { cmdMcp } from "./mcp.js";
 import { cmdRelease } from "./release.js";
 import { cmdEnvironment } from "./environment.js";
 import { cmdSecret } from "./secret.js";
+import { cmdIdentity } from "./identity.js";
+import { cmdConnections } from "./connections.js";
 export { CONFIG_MODE, DEFAULT_BASE_URL, FIRST_STAMPED_VERSION, LEGACY_PACKAGE_NAME, PACKAGE_NAME, PROVENANCE_MARKER, CliError, MeError, UsageError, configPathFor, contractPathFor, defaultCtx, defaultReplicaDbFor, defaultSkillsDirFor, fetchMe, formatMode, installedBundleVersion, installSkills, loadConfig, modernCliPath, normalizeBaseUrl, parseArgs, parseChangelogEntry, parseProvenanceVersion, readChangelog, readManifest, resolveSkillsDir, saveConfig, skillsSourceDir, updateNoticeLine, writeConfig, };
 export const CUSTOMER_SKILLS = [
     "catalyst-github",
@@ -51,11 +54,12 @@ export function usageText() {
         "  catalyst-skills join ...   (deprecated alias of login; removed in the next minor version)",
         "  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 mcp add|list|remove (vault references only)",
         "  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 runtime <status [--json]|install|path|uninstall>   (a pinned Node this CLI manages itself)",
-        "  catalyst-skills events <tail|wait-for|query> [--type NAME] [--ticket CTC-N] [--after SEQUENCE]",
+        "  catalyst-skills events <tail|wait-for|query|status [--probe]> [--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> ...",
@@ -63,6 +67,8 @@ export function usageText() {
         "  catalyst-skills release <ticket> --because <what changed> [--retry-unchanged] [--dry-run] | release --class <c> --team <K> ...",
         "  catalyst-skills environment [read] | environment propose --file <path>|--stdin [--approve] | environment approve",
         "  catalyst-skills secret set <NAME> --repo <owner/name> [--command '<cmd>'] | secret import <file> --repo <owner/name>",
+        "  catalyst-skills identity linear <status|options|set> [<linearUserId>] [--json]",
+        "  catalyst-skills connections personal <linear|github> <start|status> [--wait <seconds>] [--json]",
         "",
         "Every verb takes --help. --json makes the output machine-readable.",
         "",
@@ -211,6 +217,8 @@ export async function main(argv, ctx = defaultCtx(), deps = {}) {
                 return await cmdAsk(args, ctx);
             case "ready":
                 return await cmdReady(args, ctx, { skillNames: CUSTOMER_SKILLS, loadSdk: deps.loadSdk, offline: args.flags.offline === true });
+            case "mcp":
+                return await cmdMcp(args, ctx);
             case "accounts":
                 return await cmdAccounts(args, ctx);
             case "release":
@@ -219,6 +227,10 @@ export async function main(argv, ctx = defaultCtx(), deps = {}) {
                 return await cmdEnvironment(args, ctx, deps.environment ?? {});
             case "secret":
                 return await cmdSecret(args, ctx, deps.secret ?? {});
+            case "identity":
+                return await cmdIdentity(args, ctx, deps.identity ?? {});
+            case "connections":
+                return await cmdConnections(args, ctx, deps.connections ?? {});
             default:
                 ctx.stderr(`unknown command: ${args.command}`);
                 ctx.stderr(usageText());
@@ -242,7 +254,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", "runtime", "events", "explain", "running", "queue", "watch", "write", "ask", "ready", "accounts", "release", "secret"].map((v) => [v, true]));
+const VERB_HELP_KNOWN = Object.fromEntries(["login", "join", "install", "status", "notice", "me", "contract", "query", "replica", "runtime", "events", "explain", "running", "queue", "watch", "write", "ask", "ready", "accounts", "release", "secret", "environment", "connections", "identity", "mcp"].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/connections.js

@@ -0,0 +1,85 @@
+import { flagInt, positionals } from "./args.js";
+import { openBrowser as defaultOpenBrowser } from "./browser.js";
+import { requireConfig } from "./config.js";
+import { CliError, UsageError } from "./errors.js";
+import { bearerFor } from "./oauth.js";
+import { loadHttpSdk } from "./sdk.js";
+const waitIntervalSeconds = 10;
+function parseCommand(args) {
+    const parts = positionals(args);
+    if (parts.length !== 3 || parts[0] !== "personal" || (parts[1] !== "linear" && parts[1] !== "github") ||
+        (parts[2] !== "start" && parts[2] !== "status")) {
+        throw new UsageError("connections takes: personal <linear|github> <start|status>");
+    }
+    const waitSeconds = flagInt(args, "wait", 0);
+    if (waitSeconds < 0 || waitSeconds > 600)
+        throw new UsageError("--wait must be between 0 and 600 seconds");
+    if (parts[2] !== "start" && args.flags.wait !== undefined)
+        throw new UsageError("--wait is only valid with connections personal <provider> start");
+    return { provider: parts[1], action: parts[2], waitSeconds };
+}
+function statusLine(provider, result) {
+    const name = provider === "linear" ? "Linear" : "GitHub";
+    switch (result.outcome) {
+        case "connected":
+            return `Personal ${name}: connected as ${result.provider === "linear" ? result.linearUserId : result.githubLogin}`;
+        case "absent":
+            return `Personal ${name}: not connected — run catalyst-skills connections personal ${provider} start`;
+        case "lapsed":
+            return `Personal ${name}: connection expired — run catalyst-skills connections personal ${provider} start`;
+        case "unavailable":
+            return `Personal ${name}: temporarily unavailable — the grant state is unknown; retry status later`;
+        default:
+            return `Personal ${name}: ${result.outcome}${"reason" in result ? ` (${result.reason})` : ""}`;
+    }
+}
+function statusExit(result) {
+    return result.outcome === "connected" || result.outcome === "absent" || result.outcome === "lapsed" ? 0 : 1;
+}
+export async function cmdConnections(args, ctx, deps = {}) {
+    const { provider, action, waitSeconds } = parseCommand(args);
+    const cfg = requireConfig(ctx);
+    if (!cfg.user)
+        throw new CliError("this machine uses a tenant account key, not a member credential — run catalyst-skills login as yourself", "member-required");
+    const createClient = deps.createClient ?? (async (options) => (await loadHttpSdk()).createTenantClient(options));
+    const client = await createClient({ key: await bearerFor(ctx, cfg), baseUrl: cfg.baseUrl, fetch: ctx.fetch });
+    if (action === "status") {
+        const result = await client.personalConnections.status(provider);
+        ctx.stdout(args.json ? JSON.stringify(result) : statusLine(provider, result));
+        return statusExit(result);
+    }
+    const started = await client.personalConnections.start(provider);
+    if (started.outcome !== "ok") {
+        ctx.stdout(args.json ? JSON.stringify(started) : `Personal ${provider} connection could not start: ${started.outcome}${"reason" in started ? ` (${started.reason})` : ""}`);
+        return 1;
+    }
+    if (!args.json) {
+        ctx.stdout(`Open this URL in your browser to approve your personal ${provider} connection:`);
+        ctx.stdout(started.authorizationUrl);
+        (deps.openBrowser ?? defaultOpenBrowser)(started.authorizationUrl);
+    }
+    if (waitSeconds === 0) {
+        if (args.json)
+            ctx.stdout(JSON.stringify(started));
+        else
+            ctx.stdout(`After approval, run: catalyst-skills connections personal ${provider} status`);
+        return 0;
+    }
+    const sleep = deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    let waitedSeconds = 0;
+    let status = await client.personalConnections.status(provider);
+    while ((status.outcome === "absent" || status.outcome === "lapsed") && waitedSeconds < waitSeconds) {
+        const seconds = Math.min(waitIntervalSeconds, waitSeconds - waitedSeconds);
+        await sleep(seconds * 1000);
+        waitedSeconds += seconds;
+        status = await client.personalConnections.status(provider);
+    }
+    if (args.json)
+        ctx.stdout(JSON.stringify({ start: started, status, waitedSeconds }));
+    else {
+        ctx.stdout(statusLine(provider, status));
+        if (status.outcome === "absent" || status.outcome === "lapsed")
+            ctx.stdout(`Approval has not appeared yet; run catalyst-skills connections personal ${provider} status later.`);
+    }
+    return status.outcome === "connected" ? 0 : status.outcome === "absent" || status.outcome === "lapsed" ? 2 : 1;
+}

package/dist/event-status.js

@@ -0,0 +1,66 @@
+// Read-only event cache freshness. The event cursor is separate from the replica snapshot cursor.
+import { readFileSync } from "node:fs";
+import { requireConfig } from "./config.js";
+import { apiClient } from "./transport.js";
+function jsonFile(path) {
+    try {
+        const value = JSON.parse(readFileSync(path, "utf8"));
+        return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+function livePid(value) {
+    if (!Number.isInteger(value) || Number(value) <= 0)
+        return false;
+    try {
+        process.kill(Number(value), 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+/** Compare the persisted event cursor with the cloud head without consuming events. */
+export async function eventCacheStatus(ctx, directory, probe) {
+    const checkpoint = jsonFile(`${directory}/cursor.json`);
+    const lock = jsonFile(`${directory}/.sync.writer.lock`);
+    const cursor = checkpoint?.version === 1 && Number.isSafeInteger(checkpoint.cursor) && Number(checkpoint.cursor) >= 0 ? Number(checkpoint.cursor) : null;
+    const heartbeatAgeMs = typeof lock?.heartbeat === "number" ? Math.max(0, ctx.now().getTime() - lock.heartbeat) : null;
+    const writerAlive = livePid(lock?.pid);
+    const reasons = [];
+    if (cursor === null)
+        reasons.push("event cache cursor is absent");
+    if (heartbeatAgeMs === null || heartbeatAgeMs >= 15_000)
+        reasons.push("event writer heartbeat is absent or stale");
+    if (!writerAlive)
+        reasons.push("event writer is not running");
+    let head = null;
+    if (probe && cursor !== null) {
+        try {
+            const cfg = requireConfig(ctx);
+            const response = await apiClient(cfg, ctx).getNdjson("/api/v1/events/backbone", { query: { since: cursor }, accept: [409] });
+            const rawHead = response.headers.get("x-catalyst-event-backbone-head-seq");
+            const value = rawHead === null || rawHead.trim() === "" ? NaN : Number(rawHead);
+            if (!Number.isSafeInteger(value) || value < 0)
+                reasons.push("cloud event head could not be verified");
+            else {
+                head = value;
+                if (response.status !== 200)
+                    reasons.push(`cloud refused the event cursor (HTTP ${response.status})`);
+            }
+        }
+        catch (error) {
+            reasons.push(`cloud event head is unknown: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    if (probe && head !== null && cursor !== head)
+        reasons.push(`event cache cursor ${cursor} differs from cloud head ${head}`);
+    if (!probe)
+        reasons.push("cloud event head was not probed");
+    const unknown = reasons.some((reason) => reason.includes("unknown") || reason.includes("could not be verified") || reason.includes("was not probed"));
+    const provenStale = reasons.some((reason) => reason.includes("heartbeat") || reason.includes("not running") || reason.includes("differs from cloud head") || reason.includes("refused the event cursor"));
+    const verdict = cursor === null ? "absent" : provenStale ? "stale" : unknown ? "unknown" : reasons.length === 0 ? "current" : "stale";
+    return { verdict, directory, cursor, head, heartbeatAgeMs, writerAlive, reasons };
+}

package/dist/events.js

@@ -2,6 +2,7 @@ import { flagInt, flagString, positionals } from "./args.js";
 import { apiBase, requireConfig } from "./config.js";
 import { CliError, UsageError } from "./errors.js";
 import { authStrategyFor } from "./oauth.js";
+import { eventCacheStatus } from "./event-status.js";
 const eventsModule = "@catalyst-cloud/sdk/events";
 export const loadEventsSdk = () => import(eventsModule);
 export async function createEventSync(ctx, deps = {}) {
@@ -20,13 +21,18 @@ export async function createEventSync(ctx, deps = {}) {
 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("events needs a subcommand: tail | wait-for | query | status");
+    if (!["tail", "wait-for", "query", "status"].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);
+    if (sub === "status") {
+        const status = await eventCacheStatus(ctx, directory, args.flags.probe === true);
+        ctx.stdout(args.json ? JSON.stringify(status) : `events: ${status.verdict} at ${directory}${status.reasons.length ? ` (${status.reasons.join("; ")})` : ` (cursor ${status.cursor}, cloud head ${status.head})`}`);
+        return status.verdict === "current" ? 0 : status.verdict === "stale" ? 1 : status.verdict === "absent" ? 3 : 2;
+    }
     const after = startingCursor(args, sub === "query");
     const matches = matcher(args);
     if (sub === "query") {

package/dist/identity.js

@@ -0,0 +1,53 @@
+import { positionals } from "./args.js";
+import { requireConfig } from "./config.js";
+import { CliError, UsageError } from "./errors.js";
+import { bearerFor } from "./oauth.js";
+import { loadHttpSdk } from "./sdk.js";
+function render(result, choices) {
+    if (result.outcome !== "ok")
+        return `Linear identity: ${result.outcome}${"reason" in result ? ` (${result.reason})` : ""}`;
+    const { identity } = result;
+    const summary = `Linear identity: ${identity.resolution}${"linearUserId" in identity ? ` (${identity.linearUserId})` : ""}`;
+    if (!choices)
+        return summary;
+    if (result.options === undefined)
+        return `${summary}\nNo choices were offered. An automatic match cannot be replaced; an unmatched roster may need a retry.`;
+    if (result.options.length === 0)
+        return `${summary}\nThe workspace roster has no eligible people.`;
+    return [summary, ...result.options.map((o) => `${o.id}\t${o.displayName ?? o.name ?? "(unnamed)"}`), "Select your own identity explicitly: catalyst-skills identity linear set <linearUserId>"].join("\n");
+}
+export async function cmdIdentity(args, ctx, deps = {}) {
+    const parts = positionals(args);
+    const [provider, action, selected] = parts;
+    if (provider !== "linear" || !["status", "options", "set"].includes(action ?? "") ||
+        (action === "set" ? parts.length !== 3 || !selected?.trim() : parts.length !== 2)) {
+        throw new UsageError("identity takes: linear <status|options> or linear set <linearUserId>");
+    }
+    const cfg = requireConfig(ctx);
+    if (!cfg.user)
+        throw new CliError("this machine uses a tenant account key; run catalyst-skills login as yourself", "member-required");
+    const createClient = deps.createClient ?? (async (options) => (await loadHttpSdk()).createTenantClient(options));
+    const client = await createClient({ key: await bearerFor(ctx, cfg), baseUrl: cfg.baseUrl, fetch: ctx.fetch });
+    if (!client.linearIdentity)
+        throw new CliError("the installed SDK lacks identity recovery; upgrade catalyst-skills after the SDK release", "sdk-upgrade-required");
+    if (action === "set") {
+        // The arity check above requires a selection; never choose the first roster entry for a person.
+        if (selected === undefined)
+            throw new UsageError("linearUserId is required");
+        const written = await client.linearIdentity.set(selected);
+        if (written.outcome !== "ok") {
+            ctx.stdout(args.json ? JSON.stringify(written) : render(written, false));
+            return 1;
+        }
+        const verified = await client.linearIdentity.get();
+        if (verified.outcome !== "ok" || !("linearUserId" in verified.identity) || verified.identity.linearUserId !== selected) {
+            ctx.stdout(args.json ? JSON.stringify({ outcome: "not-confirmed", identity: verified }) : `Linear identity selection was not confirmed. Read the current status before retrying.\n${render(verified, false)}`);
+            return 1;
+        }
+        ctx.stdout(args.json ? JSON.stringify(verified) : render(verified, false));
+        return 0;
+    }
+    const result = await client.linearIdentity.get();
+    ctx.stdout(args.json ? JSON.stringify(result) : render(result, action === "options"));
+    return result.outcome === "ok" ? 0 : 1;
+}

package/dist/mcp.js

@@ -0,0 +1,101 @@
+import { flagList, flagString, positionals } from "./args.js";
+import { requireConfig } from "./config.js";
+import { CliError, UsageError } from "./errors.js";
+import { bearerFor } from "./oauth.js";
+import { loadTenantSdk } from "./sdk.js";
+const SECRET_NAME = /^[A-Z][A-Z0-9_]*$/;
+const HEADER_NAME = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/;
+const FORBIDDEN_HEADERS = new Set(["host", "connection", "transfer-encoding", "content-length"]);
+function secretName(value) {
+    if (!SECRET_NAME.test(value))
+        throw new UsageError("auth needs a vault secret NAME (A-Z, 0-9 and _, starting with a letter), never its value");
+    return value;
+}
+function parseAuth(args) {
+    const bearer = flagString(args, "bearer");
+    const headers = flagList(args, "header");
+    const auth = flagString(args, "auth");
+    if (Number(bearer !== undefined) + Number(headers.length > 0) + Number(auth !== undefined) !== 1) {
+        throw new UsageError("choose exactly one of --auth none, --bearer SECRET_NAME, or --header NAME=SECRET_NAME");
+    }
+    if (auth !== undefined) {
+        if (auth !== "none")
+            throw new UsageError("--auth accepts only none");
+        return { kind: "none" };
+    }
+    if (bearer !== undefined)
+        return { kind: "bearer", secretName: secretName(bearer) };
+    const seen = new Set();
+    return { kind: "headers", headers: headers.map((entry) => {
+            const equal = entry.indexOf("=");
+            if (equal < 1)
+                throw new UsageError("--header needs HEADER_NAME=VAULT_SECRET_NAME");
+            const name = entry.slice(0, equal);
+            const lower = name.toLowerCase();
+            if (!HEADER_NAME.test(name) || FORBIDDEN_HEADERS.has(lower) || lower.startsWith("proxy-")) {
+                throw new UsageError("--header contains an invalid or forbidden routing/framing header");
+            }
+            if (seen.has(lower))
+                throw new UsageError("--header names must be unique, ignoring case");
+            seen.add(lower);
+            return { name, secretName: secretName(entry.slice(equal + 1)) };
+        }) };
+}
+function registration(args, name) {
+    const raw = flagString(args, "url");
+    let url;
+    try {
+        url = new URL(raw ?? "");
+    }
+    catch {
+        throw new UsageError("mcp add needs --url with an absolute HTTPS URL");
+    }
+    if (url.protocol !== "https:" || url.username || url.password || raw?.includes("?") || raw?.includes("#") || (url.port && url.port !== "443")) {
+        throw new UsageError("MCP URLs require HTTPS on port 443, without userinfo, query strings or fragments");
+    }
+    // The cloud validates public DNS, catalog identity and admin approval. Never contact this URL here.
+    return { name, url: url.href, auth: parseAuth(args) };
+}
+function describeServer(server) {
+    const state = server.status === "pending" ? "waiting for admin approval"
+        : server.status === "pending_egress_guard" ? "waiting for public egress guard" : "ready";
+    const auth = server.auth.kind === "none" ? "none" : server.auth.kind === "bearer"
+        ? `bearer: ${server.auth.secretName}`
+        : server.auth.headers.map((header) => `${header.name}: ${header.secretName}`).join(", ");
+    return `${server.name} (${server.id}): ${state}\n  ${server.url}\n  auth: ${auth}`;
+}
+export async function cmdMcp(args, ctx) {
+    const [verb, ...rest] = positionals(args);
+    if (verb !== "add" && verb !== "list" && verb !== "remove")
+        throw new UsageError("mcp needs add, list or remove");
+    if (rest.length !== (verb === "list" ? 0 : 1))
+        throw new UsageError(`mcp ${verb}${verb === "list" ? "" : " <name>"}`);
+    const name = rest[0] ?? "";
+    if (verb !== "list" && !/^[a-z][a-z0-9_-]{0,63}$/.test(name))
+        throw new UsageError("server name must start with a lowercase letter and contain only lowercase letters, digits, _ or - (up to 64 characters)");
+    if (verb !== "add" && ["url", "auth", "bearer", "header"].some((key) => key in args.flags)) {
+        throw new UsageError("URL and auth options are only accepted by mcp add");
+    }
+    const input = verb === "add" ? registration(args, name) : null;
+    const cfg = requireConfig(ctx);
+    const key = await bearerFor(ctx, cfg);
+    const sdk = await loadTenantSdk();
+    const client = sdk.createTenantClient({ key, baseUrl: cfg.baseUrl, fetch: ctx.fetch, now: () => ctx.now().getTime() });
+    const result = input !== null ? await client.agent.portalServerRegister(input)
+        : verb === "list" ? await client.agent.portalServers()
+            : await client.agent.portalServerRemove({ name });
+    if (result.outcome !== "registered" && result.outcome !== "ok" && result.outcome !== "removed") {
+        const reason = result.outcome === "route-unknown" ? `cloud does not advertise ${result.route}`
+            : "reason" in result ? result.reason : result.outcome;
+        throw new CliError(String(reason), result.outcome);
+    }
+    if (args.json)
+        ctx.stdout(JSON.stringify(result));
+    else if (result.outcome === "registered")
+        ctx.stdout(describeServer(result.server));
+    else if (result.outcome === "ok")
+        ctx.stdout(result.servers.length === 0 ? "No portal servers registered." : result.servers.map(describeServer).join("\n"));
+    else
+        ctx.stdout(result.removed ? `Removed ${name}.` : `${name} was not registered.`);
+    return 0;
+}

package/dist/sdk.js

@@ -3,7 +3,19 @@ import { installTsDepsLoader } from "./ts-deps-loader.js";
 import { readManifest } from "./config.js";
 import { FIX_COMMAND, supportedRangeText } from "./runtime.js";
 let cached = null;
+let cachedHttp = null;
 const realImport = () => import("@catalyst-cloud/sdk/node");
+const realHttpImport = () => import("@catalyst-cloud/sdk");
+/** The isomorphic typed HTTP client; keeps the SDK import in this module. */
+export function loadHttpSdk(importer = realHttpImport) {
+    if (!cachedHttp) {
+        cachedHttp = importer().catch((err) => {
+            cachedHttp = null;
+            throw new CliError(`the Catalyst Cloud SDK HTTP client could not be loaded: ${err instanceof Error ? err.message : String(err)}`, "sdk-unavailable");
+        });
+    }
+    return cachedHttp;
+}
 /** Import the SDK's node entry, installing the type-stripping loader first. Cached per process. */
 export function loadSdk(importer = realImport) {
     if (!cached) {
@@ -26,4 +38,15 @@ export function loadSdk(importer = realImport) {
 /** Test seam: forget the cached import. */
 export function resetSdkCache() {
     cached = null;
+    cachedHttp = null;
+}
+/** HTTP tenant methods live on the SDK's root entry, separate from replica/node exports. */
+export async function loadTenantSdk() {
+    installTsDepsLoader();
+    try {
+        return await import("@catalyst-cloud/sdk");
+    }
+    catch {
+        throw new CliError("the Catalyst Cloud SDK could not be loaded; reinstall the skills bundle", "sdk-unavailable");
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catalyst-cloud/cli",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Customer skill bundle for Catalyst Cloud, named from the executive's seat — get set up, see what is happening, see what needs you, run a project, unstick what is stuck — plus the catalyst CLI that reads through the Catalyst Cloud SDK, writes through the agent proxy, and connects your machine to your tenant with one command. The skills directory is the roster; this line never counts it.",
   "license": "MIT",
   "type": "module",
@@ -48,7 +48,7 @@
     "paths:check": "node scripts/vendor-paths.mjs --check"
   },
   "dependencies": {
-    "@catalyst-cloud/sdk": "^0.10.0"
+    "@catalyst-cloud/sdk": "^0.12.0"
   },
   "devDependencies": {
     "@types/node": "^26.3.0",

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-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.8.0 — written in this repository for customer tenants -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.0 — written in this repository for customer tenants -->
 
 # Catalyst's GitHub
 

package/skills/catalyst-linear/SKILL.md

@@ -5,7 +5,7 @@ description: >-
 allowed-tools: Bash(catalyst-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
 disable-model-invocation: true
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.8.0 — written in this repository for customer tenants -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.0 — written in this repository for customer tenants -->
 
 # Catalyst Linear