@catalyst-cloud/catalyst-skills 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 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.
+
+## 0.3.1
+
+`ready` now names the person you connected as: when your key is a personal key, the config line reads "joined <tenant> as <you> (<role>)" instead of the generic "as service" that every api key showed, and an account (host) key still names the tenant with no person. `ready` also learns the bundle version your tenant expects, when the cloud publishes one: if this installed bundle is older than that minimum you get a one-line warning that names both versions and the upgrade command, but it stays a note — `ready` never refuses over a stale bundle, and a cloud that does not publish a minimum changes nothing. `explain` no longer calls every ticket with no dispatch row "unknown": a ticket that merely sits in Backlog (or any non-dispatch state) is now named as known to the mirror with the state it is in, and only a ticket the mirror has never seen keeps the unknown wording.
+
 ## 0.3.0
 
 You connect with your own personal key now, not the tenant's shared account key: mint it yourself at Settings → API keys in the Catalyst Cloud app (every member can; no admin needed), and `login` prints who you connected as beside which tenant. Your agent acts as you — an ask it raises names you, and "what needs me" means you: `ask list` (and the what-needs-me skill) keeps only the asks assigned to your Linear user by default, `--anyone` lists the whole tenant, and when your Linear identity is not matched yet it says so and shows everything rather than an empty list. `customer.json` gains a `user` block (id, label, role, your Linear user id); an older config is still read unchanged. Connecting with the account key still works — it is the right credential for a host or daemon — but `login` tells you it names no person. Every skill, reference and help line that said "account key", or said execution history and coding-account status were not readable, has been rewritten: `explain --history` and `accounts` read them, and the two things your key genuinely cannot do (release a park, read PR labels or reactions) are named instead. The catalyst-setup reference now lists all eleven team checks, including `environment_declared`. Needs a cloud that admits personal keys on the agent routes; on an older cloud the contract read says so by name, and the account key still works until it is updated.

package/README.md

@@ -55,27 +55,37 @@ Without `--all` the installer asks which skills to take and which agents to inst
 
 ### Then connect to your tenant
 
-The skills call one CLI, and the CLI holds your credential. Install it once and connect this machine with your own **personal key** — mint it at Settings → API keys in the Catalyst Cloud app (every member can; no admin needed):
+The skills call one CLI, and the CLI holds your credential. Install it once and connect this machine — the keyless way logs you in as yourself, with nothing to mint or paste:
 
 ```sh
 npm install -g @catalyst-cloud/catalyst-skills
-CATALYST_CLOUD_TOKEN=<your-personal-key> catalyst-skills login
+catalyst-skills login
 catalyst-skills ready
 ```
 
-Passing the key as an environment variable is the recommended form, because a key typed into a command line lands in your shell history. With no key in the environment and a terminal attached, `catalyst-skills login` prompts for it without echoing it; `--key <your-personal-key>` is the third form, for a script. `npx @catalyst-cloud/catalyst-skills login` works without the global install, and `bunx` works in place of `npx`. A non-default cloud is set with `CATALYST_CLOUD_BASE_URL` or `--base-url <url>`.
+`catalyst-skills login` with no key opens a device-code login: it prints a short code and a URL, you approve it in your browser, and this machine is connected as you. On a machine with no browser (a remote box, a container) the code and URL still work — approve them from your phone. The short-lived session refreshes silently afterwards, so you log in about once a year. `npx @catalyst-cloud/catalyst-skills login` works without the global install, and `bunx` works in place of `npx`. A non-default cloud is set with `CATALYST_CLOUD_BASE_URL` or `--base-url <url>`.
+
+Prefer a key? Pass one instead — mint a **personal key** at Settings → API keys in the Catalyst Cloud app (every member can; no admin needed). The environment form keeps it out of your shell history:
+
+```sh
+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.
 
 ## 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 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.
+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.
 
 ## What connecting does
 
-`login` does three things: it calls `GET /api/v1/me` with your key, which discovers your tenant and who you are from the key alone; it writes `~/.config/catalyst-cloud/customer.json` with file mode `0600`, holding your key, who you are (id, label, role, your Linear user id) and the absolute path of the CLI so every skill script can spawn the same binary; and it fetches the tenant contract (`GET /api/v1/agent/contract`) and caches it at `~/.config/catalyst-cloud/contract.json` with its ETag, so stage names and ids, label ids, the ask template, thresholds and the route table come from your tenant, live, and no skill restates them.
+`login` does three things: it calls `GET /api/v1/me` with your credential, which discovers your tenant and who you are from the credential alone; it writes `~/.config/catalyst-cloud/customer.json` with file mode `0600`, holding your credential (a keyless login session, or a personal key), who you are (id, label, role, your Linear user id) and the absolute path of the CLI so every skill script can spawn the same binary; and it fetches the tenant contract (`GET /api/v1/agent/contract`) and caches it at `~/.config/catalyst-cloud/contract.json` with its ETag, so stage names and ids, label ids, the ask template, thresholds and the route table come from your tenant, live, and no skill restates them.
+
+A keyless session's access token is short-lived and rotates on its own: every request refreshes it within a minute of expiry and rewrites the config atomically, so you stay connected for months without logging in again. You only log in again if the session is revoked or you have been away long enough to lapse — then one clear line tells you to run `login`.
 
-`login` does not install skills; the install command above did that. Re-running `login` after a key rotation rewrites the config. `catalyst-skills status` prints which tenant this machine is connected to and as whom, `catalyst-skills ready` prints one READY or NOT READY verdict with the fix for each failure and who can apply it, and `catalyst-skills --version` prints the package version and its pinned tenant contract range.
+`login` does not install skills; the install command above did that. Re-running `login` after a key rotation, or to switch rails, rewrites the config. `catalyst-skills status` prints which tenant this machine is connected to and as whom, `catalyst-skills ready` prints one READY or NOT READY verdict with the fix for each failure and who can apply it, and `catalyst-skills --version` prints the package version and its pinned tenant contract range.
 
 The setup skill Catalyst seeds into your repository ends by pointing at this same command. That served skill lives in the Catalyst Cloud application, not here; this is the only connect step a customer runs. The tenant's **account key** (Settings → Account keys, admin-minted) is a different credential — for a host or daemon that runs unattended — and is not what a person connects their own agent with: it would strip your name from everything your agent writes, and `login` says so if you use one.
 
@@ -145,10 +155,10 @@ The skill files themselves are written by whichever install command you ran, in
 
 ## Updating
 
-A plugin install updates when we ship. Skills copied by `npx skills add` do not; run `npx skills update -y` to refresh them. Update the CLI with `npm update -g @catalyst-cloud/catalyst-skills`, or run any command against the latest publish with `npx @catalyst-cloud/catalyst-skills@latest login`. The next `catalyst-skills` run prints a one-line notice:
+A plugin install updates when we ship. Skills copied by `npx skills add` do not; run `npx skills update -y` to refresh them. Update the CLI with `npm install -g @catalyst-cloud/catalyst-skills@latest && catalyst-skills login` — the re-login rewrites the CLI path the skills spawn, so they stop running the old bundle. To run one command against the latest publish without installing, use `npx @catalyst-cloud/catalyst-skills@latest login`. The next `catalyst-skills` run prints a one-line notice:
 
 ```
-[catalyst-skills] updated 0.1.1 → 0.2.0: <that version's CHANGELOG.md summary> · update with: npm update -g @catalyst-cloud/catalyst-skills (or: npx @catalyst-cloud/catalyst-skills@latest login)
+[catalyst-skills] updated 0.1.1 → 0.2.0: <that version's CHANGELOG.md summary> · update with: npm install -g @catalyst-cloud/catalyst-skills@latest && catalyst-skills login
 ```
 
 A `customer.json` written by an older bundle is still read unchanged; it gains the CLI path and the cached contract the next time you run `catalyst-skills login`.

package/dist/args.js

@@ -94,7 +94,7 @@ export const FLAG_TABLES = {
     accounts: {},
 };
 export const VERB_USAGE = {
-    login: "login [--key <account-key>] [--base-url <url>] [--start-replica]",
+    login: "login [--base-url <url>] [--start-replica]   (keyless; or --key <personal-key> / CATALYST_CLOUD_TOKEN)",
     install: "install [--skills-dir <dir>] [--force]",
     status: "status",
     notice: "notice",

package/dist/ask.js

@@ -5,7 +5,7 @@ import { flagBool, flagList, flagString, positionals } from "./args.js";
 import { requireConfig } from "./config.js";
 import { loadContract, teamByKey } from "./contract.js";
 import { UsageError } from "./errors.js";
-import { apiClient } from "./http.js";
+import { apiClient } from "./transport.js";
 import { rowsOf } from "./query.js";
 import { fetchWorkflowStates, postAgent, resolveIssue } from "./write.js";
 export async function cmdAsk(args, ctx) {

package/dist/browser.js

@@ -0,0 +1,20 @@
+// browser.ts — open the device-flow verification page in the person's default browser. Best-effort:
+// a machine with no browser (a headless mini, a container) simply shows the code and URL instead, so
+// this never throws into the login flow — the caller wraps it, and a spawn failure is swallowed here.
+import { spawn } from "node:child_process";
+/** The platform's "open this URL" command. `open` on macOS, `start` via cmd on Windows, else xdg-open. */
+export function openBrowser(url) {
+    const [cmd, args] = process.platform === "darwin"
+        ? ["open", [url]]
+        : process.platform === "win32"
+            ? ["cmd", ["/c", "start", "", url]]
+            : ["xdg-open", [url]];
+    try {
+        const child = spawn(cmd, [...args], { stdio: "ignore", detached: true });
+        child.on("error", () => { }); // no opener installed — the printed URL is the fallback
+        child.unref();
+    }
+    catch {
+        // spawn itself threw (unusual) — the code and URL on screen are the fallback
+    }
+}

package/dist/cli.js

@@ -5,12 +5,14 @@ import { parseArgs, positionals, verbHelp } from "./args.js";
 import { CONFIG_MODE, DEFAULT_BASE_URL, PACKAGE_NAME, cliPath, configPathFor, contractPathFor, defaultCtx, defaultReplicaDbFor, defaultSkillsDirFor, formatMode, loadConfig, normalizeBaseUrl, readManifest, requireConfig, saveConfig, writeConfig, } from "./config.js";
 import { loadContract, pickPath } from "./contract.js";
 import { CliError, MeError, UsageError } from "./errors.js";
-import { fetchMe } from "./http.js";
+import { fetchMe } from "./transport.js";
+import { bearerFor, deviceFlowLogin } from "./oauth.js";
+import { openBrowser as defaultOpenBrowser } from "./browser.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";
-import { promptSecret, stdinIsTty } from "./prompt.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";
@@ -37,7 +39,8 @@ export function usageText() {
         `${PACKAGE_NAME} — the Catalyst Cloud customer CLI: connect to your tenant, read through the SDK, write through the agent proxy`,
         "",
         "Usage:",
-        "  catalyst-skills login [--key <personal-key>] [--base-url <url>] [--start-replica]",
+        "  catalyst-skills login [--base-url <url>] [--start-replica]   (keyless: logs you in as yourself)",
+        "  catalyst-skills login --key <personal-key> [--base-url <url>]   (or CATALYST_CLOUD_TOKEN, for a key)",
         "  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",
@@ -51,14 +54,16 @@ export function usageText() {
         "",
         "Every verb takes --help. --json makes the output machine-readable.",
         "",
-        "The key may also come from CATALYST_CLOUD_TOKEN; the base URL defaults to",
-        `CATALYST_CLOUD_BASE_URL or ${DEFAULT_BASE_URL}.`,
+        "With no key, login is keyless: it opens a WorkOS device-code flow, prints a short code and a URL,",
+        "and connects you as yourself once you approve in the browser — nothing to mint or paste. Pass",
+        "--key (or set CATALYST_CLOUD_TOKEN) to use a personal or account key instead. The base URL defaults",
+        `to CATALYST_CLOUD_BASE_URL or ${DEFAULT_BASE_URL}.`,
         "",
-        "login calls GET /api/v1/me to discover your tenant from the key alone, writes",
-        "~/.config/catalyst-cloud/customer.json (0600) with the key and this CLI's path, and caches the",
-        "tenant contract beside it. With no key in the environment and a terminal attached it prompts",
-        "for the key without echoing it. It does not install skills: your agent's own install command",
-        "does that, and `install` is only here to repair a copy this package made.",
+        "login discovers your tenant from GET /api/v1/me, writes ~/.config/catalyst-cloud/customer.json",
+        "(0600) holding your login session (or key) and this CLI's path, and caches the tenant contract",
+        "beside it. A keyless session's short-lived token refreshes silently on every request. login does",
+        "not install skills: your agent's own install command does that, and `install` is only here to",
+        "repair a copy this package made.",
     ].join("\n");
 }
 /**
@@ -190,14 +195,19 @@ export async function main(argv, ctx = defaultCtx(), deps = {}) {
 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]));
 async function cmdLogin(args, ctx, deps) {
     const manifest = readManifest();
-    let key = (args.key ?? ctx.env.CATALYST_CLOUD_TOKEN ?? "").trim();
-    if (!key && (deps.isTty ?? stdinIsTty)()) {
-        key = (await (deps.promptSecret ?? promptSecret)("Personal key (not echoed): ")).trim();
-    }
-    if (!key)
-        throw new UsageError("login needs your personal key: pass --key <personal-key> or set CATALYST_CLOUD_TOKEN");
+    const key = (args.key ?? ctx.env.CATALYST_CLOUD_TOKEN ?? "").trim();
     const baseUrl = normalizeBaseUrl(args.baseUrl ?? ctx.env.CATALYST_CLOUD_BASE_URL ?? DEFAULT_BASE_URL);
-    const me = await fetchMe(baseUrl, key, ctx.fetch);
+    // Keyless is the preferred rail: with no key in flag or env, run the WorkOS device flow and log in
+    // as the person. A key (flag or CATALYST_CLOUD_TOKEN) still takes the token rail unchanged.
+    let auth;
+    const bearer = key
+        ? key
+        : (auth = await deviceFlowLogin(ctx, baseUrl, {
+            isTty: deps.isTty ?? stdinIsTty,
+            openBrowser: deps.openBrowser ?? defaultOpenBrowser,
+            sleep: deps.sleep,
+        })).accessToken;
+    const me = await fetchMe(baseUrl, bearer, ctx.fetch);
     let existing;
     try {
         existing = loadConfig(ctx.home);
@@ -209,7 +219,8 @@ async function cmdLogin(args, ctx, deps) {
     const skillsDir = resolveSkillsDir(args, ctx, existing);
     const config = {
         baseUrl,
-        key,
+        ...(key ? { key } : {}),
+        ...(auth ? { auth } : {}),
         account: me.account,
         slug: me.slug,
         name: me.name,
@@ -230,7 +241,7 @@ async function cmdLogin(args, ctx, deps) {
     else {
         ctx.stderr(`[catalyst-skills] this is the tenant's account key (a host credential), not your own — the skills work, but nothing your agent writes will carry your name and "what needs me" cannot mean you. Mint a personal key at Settings → API keys and log in with that.`);
     }
-    ctx.stdout(`Config written to ${written.path} (mode ${formatMode(written.mode)}, holds your key and the CLI path)${written.mode === CONFIG_MODE ? "" : ` — expected ${formatMode(CONFIG_MODE)}; chmod it by hand`}`);
+    ctx.stdout(`Config written to ${written.path} (mode ${formatMode(written.mode)}, holds your ${auth ? "login session" : "key"} and the CLI path)${written.mode === CONFIG_MODE ? "" : ` — expected ${formatMode(CONFIG_MODE)}; chmod it by hand`}`);
     ctx.stdout(`Tenant contract range: ${manifest.tenantContractRange}`);
     try {
         const loaded = await loadContract(ctx, config, { refresh: true });
@@ -280,21 +291,35 @@ function cmdStatus(ctx) {
     const manifest = readManifest();
     const cfg = loadConfig(ctx.home);
     if (!cfg) {
-        ctx.stdout(`Not connected yet — run: CATALYST_CLOUD_TOKEN=<your personal key> npx ${PACKAGE_NAME} login`);
+        ctx.stdout(`Not connected yet — run: npx ${PACKAGE_NAME} login (keyless; or pass --key / set CATALYST_CLOUD_TOKEN)`);
         return 0;
     }
     ctx.stdout(`Tenant: ${cfg.name} (${cfg.slug}) — account ${cfg.account}`);
     ctx.stdout(`API: ${cfg.baseUrl} (principal: ${cfg.principal})`);
     ctx.stdout(cfg.user ? `As: ${cfg.user.label} (${cfg.user.role})` : "As: the tenant's account key (a host credential — no person)");
+    ctx.stdout(cfg.auth ? `Credential: your login (expires ${relativeExpiry(cfg.auth.expiresAt, ctx.now())})` : "Credential: personal key");
     ctx.stdout(`Bundle: ${PACKAGE_NAME} ${manifest.version} (tenant contract range: ${manifest.tenantContractRange})`);
     if (cfg.cliPath)
         ctx.stdout(`CLI: ${cfg.cliPath}${existsSync(cfg.cliPath) ? "" : " (missing — re-run login)"}`);
     ctx.stdout(`Contract: ${existsSync(contractPathFor(ctx.home)) ? contractPathFor(ctx.home) : "not cached (run: catalyst-skills contract --refresh)"}`);
     return 0;
 }
+/** A short human relative time for an ISO expiry, e.g. "in 14m", "in 2h", "in 6d", or "now" once past. */
+function relativeExpiry(iso, now) {
+    const ms = Date.parse(iso) - now.getTime();
+    if (!Number.isFinite(ms) || ms <= 0)
+        return "now";
+    const mins = Math.round(ms / 60_000);
+    if (mins < 60)
+        return `in ${mins}m`;
+    const hours = Math.round(mins / 60);
+    if (hours < 48)
+        return `in ${hours}h`;
+    return `in ${Math.round(hours / 24)}d`;
+}
 async function cmdMe(args, ctx) {
     const cfg = requireConfig(ctx);
-    const me = await fetchMe(cfg.baseUrl, cfg.key, ctx.fetch);
+    const me = await fetchMe(cfg.baseUrl, await bearerFor(ctx, cfg), ctx.fetch);
     if (args.json)
         ctx.stdout(JSON.stringify(me));
     else {

package/dist/config.js

@@ -1,6 +1,7 @@
 // config.ts — ~/.config/catalyst-cloud/customer.json and its siblings. The ONLY place the base URL
 // and the `/api/v1` prefix are joined: the SDK wants the base with the prefix, GET /me without.
-import { chmodSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { randomBytes } from "node:crypto";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { CliError } from "./errors.js";
@@ -29,6 +30,10 @@ export function contractPathFor(home) {
 export function watchCursorPathFor(home) {
     return join(configDirFor(home), "watch-cursor.json");
 }
+/** CTC-2112 — where the cached CLI-auth discovery document lives (the `/api/v1/auth/cli` answer). */
+export function discoveryCachePathFor(home) {
+    return join(configDirFor(home), "auth-discovery.json");
+}
 export function defaultReplicaDbFor(home) {
     return join(configDirFor(home), "replica.db");
 }
@@ -61,28 +66,65 @@ export function loadConfig(home) {
         throw new CliError(`config at ${path} is not valid JSON — re-run login to rewrite it`, "config-corrupt");
     }
     const cfg = parsed;
-    if (typeof cfg.account !== "string" || typeof cfg.key !== "string" || typeof cfg.baseUrl !== "string") {
+    if (typeof cfg.account !== "string" || typeof cfg.baseUrl !== "string") {
         throw new CliError(`config at ${path} is missing required fields — re-run login to rewrite it`, "config-corrupt");
     }
+    const hasKey = typeof cfg.key === "string" && cfg.key !== "";
+    const hasOauth = isOauthAuth(cfg.auth);
+    if (hasKey === hasOauth) {
+        throw new CliError(`config at ${path} must hold exactly one of a personal key or an OAuth session — re-run login to rewrite it`, "config-corrupt");
+    }
     return cfg;
 }
 /** Load the config or refuse with the one line every verb prints when the machine is not connected. */
 export function requireConfig(ctx) {
     const cfg = loadConfig(ctx.home);
     if (!cfg) {
-        throw new CliError(`not connected yet — run: CATALYST_CLOUD_TOKEN=<your personal key> npx ${PACKAGE_NAME} login`, "not-configured");
+        throw new CliError(`not connected yet — run: npx ${PACKAGE_NAME} login (keyless; or pass --key / set CATALYST_CLOUD_TOKEN for a key)`, "not-configured");
     }
     return cfg;
 }
 export function saveConfig(home, cfg) {
     return writeConfig(home, cfg).path;
 }
-/** Write the config and return the mode the file ACTUALLY carries afterwards (chmod runs on every
- *  write: Node honours `mode` only when it creates the file). */
+/** True when `v` is a well-formed OAuth session block. */
+export function isOauthAuth(v) {
+    if (typeof v !== "object" || v === null)
+        return false;
+    const a = v;
+    return (a.kind === "oauth" &&
+        typeof a.accessToken === "string" &&
+        typeof a.refreshToken === "string" &&
+        typeof a.expiresAt === "string" &&
+        typeof a.sessionId === "string");
+}
+/**
+ * Write the config atomically (a rotated token must never be half-written under a crash) and return
+ * the mode the file ACTUALLY carries afterwards. Write to a sibling `.tmp` at 0600, then rename over
+ * the target — rename is atomic within a directory — and chmod once more (a pre-existing target keeps
+ * its own mode through the rename on some platforms).
+ */
 export function writeConfig(home, cfg) {
     const path = configPathFor(home);
     mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, JSON.stringify(cfg, null, 2) + "\n", { mode: CONFIG_MODE });
+    // A UNIQUE sibling temp per write (pid + randomness): two concurrent CLI processes reaching the
+    // OAuth refresh window must not share `customer.json.tmp`, or one renames/removes it out from under
+    // the other and the second write fails with ENOENT or lands the wrong contents (Codex P2).
+    const tmp = `${path}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
+    try {
+        writeFileSync(tmp, JSON.stringify(cfg, null, 2) + "\n", { mode: CONFIG_MODE });
+        chmodSync(tmp, CONFIG_MODE);
+        renameSync(tmp, path);
+    }
+    catch (err) {
+        try {
+            rmSync(tmp, { force: true });
+        }
+        catch {
+            // best-effort cleanup of the temp file
+        }
+        throw err;
+    }
     chmodSync(path, CONFIG_MODE);
     return { path, mode: statSync(path).mode & 0o777 };
 }

package/dist/contract.js

@@ -5,7 +5,7 @@ import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "
 import { dirname } from "node:path";
 import { contractPathFor, readManifest } from "./config.js";
 import { CliError, MeError } from "./errors.js";
-import { apiClient } from "./http.js";
+import { apiClient } from "./transport.js";
 export const CONTRACT_ROUTE = "/api/v1/agent/contract";
 export function readContractCache(home) {
     const path = contractPathFor(home);
@@ -45,7 +45,7 @@ export function assertContractRange(version, range) {
     if (ok === null)
         throw new CliError(`tenantContractRange "${range}" in package.json is not a range this CLI understands`, "contract-range");
     if (!ok) {
-        throw new CliError(`the tenant serves contract version ${version} but this bundle accepts ${range} — update the bundle (npm update -g @catalyst-cloud/catalyst-skills) or ask your tenant admin which version is live`, "contract-version");
+        throw new CliError(`the tenant serves contract version ${version} but this bundle accepts ${range} — update the bundle (npm install -g @catalyst-cloud/catalyst-skills@latest && catalyst-skills login) or ask your tenant admin which version is live`, "contract-version");
     }
 }
 /**

package/dist/execution.js

@@ -5,7 +5,7 @@ import { flagBool, flagString, positionals } from "./args.js";
 import { normalizeBaseUrl, requireConfig } from "./config.js";
 import { loadContract } from "./contract.js";
 import { CliError, UsageError } from "./errors.js";
-import { apiClient } from "./http.js";
+import { apiClient } from "./transport.js";
 /** Every exclusion reason the eligibility evaluator names, in plain English. */
 export const EXCLUSION_REASONS = {
     ticket_terminal: "the ticket is in a done or canceled state, so there is nothing left to run",
@@ -61,9 +61,15 @@ 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) {
-    if (!row)
+export function renderExplain(ticket, row, team, knownState) {
+    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
+        // dispatch column. Only a 404 (knownState null/absent) is truly unknown to the mirror.
+        if (knownState)
+            return `${ticket}: known to the mirror; state ${knownState} is not a dispatch state.`;
         return `${ticket}: not in the ${team} eligibility explainer — the ticket is unknown to the mirror, terminal, or on another team.`;
+    }
     const parts = [];
     const pos = typeof row.position === "number" ? `position ${row.position}` : "no queue position";
     const status = row.status ?? "unknown";
@@ -115,11 +121,20 @@ export async function cmdExplain(args, ctx) {
     });
     const rows = res.body.eligibility?.rows ?? res.body.rows ?? [];
     const row = rows.find((r) => String(r.ticket ?? "").toUpperCase() === ticket.toUpperCase()) ?? null;
+    // No dispatch row is not proof of non-existence: probe the mirror so a Backlog ticket reads as known.
+    // The mirror compares identifiers exactly, so normalize (uppercase) as the row lookup above does —
+    // otherwise `explain eng-7` probes a lowercase id, 404s, and reports an existing ENG-7 as unknown.
+    let knownState = null;
+    if (!row) {
+        const probe = await api.getJson(`/api/v1/issues/${encodeURIComponent(ticket.toUpperCase())}`, { accept: [404] });
+        if (probe.status !== 404)
+            knownState = typeof probe.body?.state === "string" ? probe.body.state : "unknown";
+    }
     if (args.json) {
-        ctx.stdout(JSON.stringify({ ticket, row, explanation: renderExplain(ticket, row, team) }));
+        ctx.stdout(JSON.stringify({ ticket, row, explanation: renderExplain(ticket, row, team, knownState) }));
     }
     else {
-        ctx.stdout(renderExplain(ticket, row, team));
+        ctx.stdout(renderExplain(ticket, row, team, knownState));
     }
     return 0;
 }

package/dist/oauth.js

@@ -0,0 +1,300 @@
+import { discoveryCachePathFor, loadConfig, normalizeBaseUrl, writeConfig } from "./config.js";
+import { CliError } from "./errors.js";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+const DISCOVERY_TTL_MS = 60 * 60_000;
+const REFRESH_SKEW_MS = 60_000;
+const REQUEST_TIMEOUT_MS = 15_000;
+const SLOW_DOWN_BUMP_MS = 5_000;
+const MAX_POLL_BACKOFF_MS = 30_000;
+const REFRESH_MAX_ATTEMPTS = 4;
+const REFRESH_BASE_BACKOFF_MS = 500;
+const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+let memo = null;
+/** Test seam: forget the cached discovery document. */
+export function resetDiscoveryCache() {
+    memo = null;
+}
+function readDiscoveryDisk(home) {
+    const path = discoveryCachePathFor(home);
+    if (!existsSync(path))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        if (isDiscovery(parsed.doc) && typeof parsed.fetchedAt === "number" && typeof parsed.baseUrl === "string")
+            return parsed;
+    }
+    catch {
+        // a corrupt cache is just a cache miss
+    }
+    return null;
+}
+function isDiscovery(v) {
+    if (typeof v !== "object" || v === null)
+        return false;
+    const d = v;
+    return ["clientId", "issuer", "deviceAuthorizationUrl", "tokenUrl", "jwksUrl"].every((k) => typeof d[k] === "string");
+}
+export async function fetchDiscovery(ctx, baseUrl, opts = {}) {
+    const base = normalizeBaseUrl(baseUrl);
+    const nowMs = ctx.now().getTime();
+    const fresh = (e) => e !== null && e.baseUrl === base && nowMs - e.fetchedAt < DISCOVERY_TTL_MS;
+    if (!opts.refresh) {
+        if (fresh(memo))
+            return memo.doc;
+        const disk = readDiscoveryDisk(ctx.home);
+        if (fresh(disk)) {
+            memo = disk;
+            return disk.doc;
+        }
+    }
+    const url = `${base}/api/v1/auth/cli`;
+    const res = await safeFetch(ctx, url, { headers: { accept: "application/json" } });
+    if (!res.ok) {
+        throw new CliError(`could not read the login discovery document (${res.status}) at ${url} — is this a Catalyst Cloud origin?`, "discovery-failed");
+    }
+    const doc = (await parseJson(res, url));
+    if (!isDiscovery(doc))
+        throw new CliError(`the login discovery document at ${url} is not the expected shape`, "discovery-shape");
+    const entry = { baseUrl: base, fetchedAt: nowMs, doc };
+    memo = entry;
+    try {
+        writeFileSync(discoveryCachePathFor(ctx.home), JSON.stringify(entry, null, 2) + "\n");
+    }
+    catch {
+        // the disk cache is an optimisation; the in-memory memo is enough
+    }
+    return doc;
+}
+/**
+ * Run the device-authorization grant to completion and return the stored session block. Prints the
+ * user code and where to enter it; on a TTY it also opens the completion URL. Polls at the server's
+ * `interval`, honours `slow_down`, and is bounded by `AbortSignal.timeout(expires_in)` so it can
+ * never poll past the device code's own lifetime.
+ */
+export async function deviceFlowLogin(ctx, baseUrl, deps = {}) {
+    const sleep = deps.sleep ?? defaultSleep;
+    const discovery = await fetchDiscovery(ctx, baseUrl);
+    const auth = await deviceAuthorize(ctx, discovery);
+    ctx.stdout("");
+    ctx.stdout(`To connect this machine, visit:  ${auth.verification_uri}`);
+    ctx.stdout(`and enter the code:              ${auth.user_code}`);
+    if ((deps.isTty ?? (() => false))()) {
+        try {
+            (deps.openBrowser ?? (() => { }))(auth.verification_uri_complete);
+            ctx.stdout("Opened your browser to that page — approve there, or use the code above.");
+        }
+        catch {
+            // a browser that will not open is not a failure; the code and URL still work
+        }
+    }
+    ctx.stdout("Waiting for you to approve… (Ctrl-C to cancel)");
+    // Terminal states print ONE clear, actionable line and exit 2 (CliError's default). The duration
+    // comes from the device code's own `expires_in`, so it is right whatever the server set.
+    const mins = Math.round(auth.expires_in / 60);
+    const expired = () => new CliError(`the login code expired${mins >= 1 ? ` after ${mins} minute${mins === 1 ? "" : "s"}` : ""} — run: catalyst-skills login again`, "login-expired");
+    const deadline = AbortSignal.timeout(auth.expires_in * 1_000);
+    let intervalMs = Math.max(1, auth.interval) * 1_000;
+    for (;;) {
+        await sleep(intervalMs);
+        // The device code's own lifetime bounds the loop: once it lapses, say so plainly rather than
+        // letting the next fetch's aborted signal surface as a generic network error (Codex P2).
+        if (deadline.aborted)
+            throw expired();
+        let res;
+        try {
+            res = await safeFetch(ctx, discovery.tokenUrl, { method: "POST", headers: formHeaders(), body: form({ grant_type: "urn:ietf:params:oauth:grant-type:device_code", device_code: auth.device_code, client_id: discovery.clientId }) }, deadline);
+        }
+        catch (err) {
+            // The deadline firing mid-fetch is an expiry, not a failure; anything else is a transient
+            // network blip — retry with backoff until the deadline, never abandon the login (CTC-2112 P1).
+            if (deadline.aborted)
+                throw expired();
+            intervalMs = backoff(intervalMs);
+            continue;
+        }
+        if (res.ok) {
+            const pair = (await parseJson(res, discovery.tokenUrl));
+            if (typeof pair.access_token !== "string" || typeof pair.refresh_token !== "string") {
+                throw new CliError("the login token response was missing a token", "login-shape");
+            }
+            return tokensToAuth(ctx, pair.access_token, pair.refresh_token);
+        }
+        const err = await oauthError(res, discovery.tokenUrl);
+        if (err === "authorization_pending")
+            continue;
+        if (err === "slow_down") {
+            intervalMs += SLOW_DOWN_BUMP_MS;
+            continue;
+        }
+        if (err === "access_denied")
+            throw new CliError("login was denied — run: catalyst-skills login to try again", "login-denied");
+        if (err === "expired_token")
+            throw expired();
+        // A transient HTTP failure (request timeout, rate limit, server error) is retried, honouring
+        // Retry-After for a 429; only a genuine, non-transient refusal ends the loop.
+        if (res.status === 408 || res.status === 429 || res.status >= 500) {
+            const retryAfter = Number(res.headers.get("retry-after"));
+            intervalMs = Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter * 1_000 : backoff(intervalMs);
+            continue;
+        }
+        throw new CliError(`login failed (${res.status}): ${err}`, "login-failed");
+    }
+}
+/** Grow the poll interval on a transient failure, capped, so retries never hammer the endpoint. */
+function backoff(intervalMs) {
+    return Math.min(intervalMs * 2, MAX_POLL_BACKOFF_MS);
+}
+/**
+ * Persist a rotated token pair WITHOUT clobbering a newer login (Codex P1). A long-running watch or
+ * detached replica holds the `cfg` it started with; if the person meanwhile re-ran `login` (a new
+ * session, a different tenant, or the key rail), that config is already on disk and must survive. So
+ * we reload disk and only write when it is still the same session we just refreshed — or when there
+ * is nothing on disk yet. The reloaded doc is written (not our in-memory `cfg`), so its tenant, user
+ * and CLI-path fields are preserved and only the auth block advances.
+ */
+function persistRotation(ctx, cfg, sessionId, rotated) {
+    let disk;
+    try {
+        disk = loadConfig(ctx.home);
+    }
+    catch {
+        return; // a corrupt/unreadable disk config: don't overwrite what we can't understand
+    }
+    if (disk && disk.auth?.sessionId !== sessionId)
+        return; // a newer login (or a switch to a key) — leave it
+    const target = disk ?? cfg;
+    target.auth = rotated;
+    writeConfig(ctx.home, target); // atomic; the rotated pair survives a crash
+}
+async function deviceAuthorize(ctx, discovery) {
+    const res = await safeFetch(ctx, discovery.deviceAuthorizationUrl, { method: "POST", headers: formHeaders(), body: form({ client_id: discovery.clientId }) });
+    if (!res.ok)
+        throw new CliError(`could not start login (${res.status}) at ${discovery.deviceAuthorizationUrl}`, "login-failed");
+    const d = (await parseJson(res, discovery.deviceAuthorizationUrl));
+    if (typeof d.device_code !== "string" || typeof d.user_code !== "string" || typeof d.verification_uri !== "string") {
+        throw new CliError("the login authorization response was not the expected shape", "login-shape");
+    }
+    return {
+        device_code: d.device_code,
+        user_code: d.user_code,
+        verification_uri: d.verification_uri,
+        verification_uri_complete: d.verification_uri_complete ?? d.verification_uri,
+        expires_in: typeof d.expires_in === "number" ? d.expires_in : 300,
+        interval: typeof d.interval === "number" ? d.interval : 5,
+    };
+}
+// ── the silent refresh ─────────────────────────────────────────────────────────────────────────
+const inFlight = new Map();
+/**
+ * The current bearer for `cfg`: the personal key verbatim, or (for an OAuth session) the access
+ * token, refreshed in place when it is within 60s of expiry. Concurrent callers that both hit the
+ * refresh window share one refresh (single-flight, keyed by the config's home) so the rotating
+ * refresh token is spent exactly once.
+ */
+export async function bearerFor(ctx, cfg, deps = {}) {
+    if (typeof cfg.key === "string" && cfg.key !== "")
+        return cfg.key;
+    if (!cfg.auth)
+        throw new CliError("this machine is not connected — run: catalyst-skills login", "not-configured");
+    const msToExpiry = Date.parse(cfg.auth.expiresAt) - ctx.now().getTime();
+    if (Number.isFinite(msToExpiry) && msToExpiry > REFRESH_SKEW_MS)
+        return cfg.auth.accessToken;
+    const pending = inFlight.get(ctx.home);
+    if (pending) {
+        const rotated = await pending;
+        return rotated.accessToken;
+    }
+    const promise = refreshAndPersist(ctx, cfg, deps).finally(() => inFlight.delete(ctx.home));
+    inFlight.set(ctx.home, promise);
+    const rotated = await promise;
+    return rotated.accessToken;
+}
+async function refreshAndPersist(ctx, cfg, deps) {
+    const sleep = deps.sleep ?? defaultSleep;
+    const discovery = await fetchDiscovery(ctx, cfg.baseUrl);
+    const current = cfg.auth;
+    let lastStatus = 0;
+    for (let attempt = 0; attempt < REFRESH_MAX_ATTEMPTS; attempt++) {
+        if (attempt > 0)
+            await sleep(REFRESH_BASE_BACKOFF_MS * 2 ** (attempt - 1));
+        const res = await safeFetch(ctx, discovery.tokenUrl, { method: "POST", headers: formHeaders(), body: form({ grant_type: "refresh_token", refresh_token: current.refreshToken, client_id: discovery.clientId }) });
+        if (res.ok) {
+            const pair = (await parseJson(res, discovery.tokenUrl));
+            if (typeof pair.access_token !== "string" || typeof pair.refresh_token !== "string")
+                throw new CliError("the refresh response was missing a token", "session-refresh-shape");
+            const rotated = tokensToAuth(ctx, pair.access_token, pair.refresh_token, current.sessionId);
+            cfg.auth = rotated; // this process keeps using its own refreshed token
+            persistRotation(ctx, cfg, current.sessionId, rotated);
+            return rotated;
+        }
+        lastStatus = res.status;
+        const err = await oauthError(res, discovery.tokenUrl);
+        if (err === "invalid_grant") {
+            // revocation or > inactivity window — the ONLY session-expired case; NOT routine expiry.
+            throw new CliError("your login expired or was revoked — run: catalyst-skills login", "session-expired");
+        }
+        const transient = res.status === 429 || res.status >= 500;
+        if (!transient)
+            throw new CliError(`could not refresh your login (${res.status}): ${err}`, "session-refresh-failed");
+        // transient: fall through to backoff + retry, keeping the stored tokens untouched
+    }
+    throw new CliError(`could not refresh your login after ${REFRESH_MAX_ATTEMPTS} attempts (last status ${lastStatus}) — your tokens are unchanged; try again`, "session-refresh-failed");
+}
+/** The SDK auth strategy for `cfg`: a static token for the key rail, a fresh-per-connect bearer for
+ *  the OAuth rail (its `getToken` runs the same refresh path as every HTTP request). */
+export function authStrategyFor(ctx, cfg) {
+    if (typeof cfg.key === "string" && cfg.key !== "")
+        return { kind: "token", token: cfg.key };
+    return { kind: "bearer", getToken: () => bearerFor(ctx, cfg) };
+}
+// ── helpers ──────────────────────────────────────────────────────────────────────────────────────
+function tokensToAuth(ctx, accessToken, refreshToken, fallbackSid) {
+    const claims = decodeJwtClaims(accessToken);
+    const exp = typeof claims.exp === "number" ? claims.exp * 1_000 : ctx.now().getTime() + 15 * 60_000;
+    const sid = typeof claims.sid === "string" ? claims.sid : (fallbackSid ?? "");
+    return { kind: "oauth", accessToken, refreshToken, expiresAt: new Date(exp).toISOString(), sessionId: sid };
+}
+function decodeJwtClaims(token) {
+    const parts = token.split(".");
+    if (parts.length < 2)
+        return {};
+    try {
+        return JSON.parse(Buffer.from(parts[1], "base64url").toString("utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+function formHeaders() {
+    return { "content-type": "application/x-www-form-urlencoded", accept: "application/json" };
+}
+function form(fields) {
+    return new URLSearchParams(fields).toString();
+}
+async function safeFetch(ctx, url, init, signal) {
+    const sig = signal ? AbortSignal.any([signal, AbortSignal.timeout(REQUEST_TIMEOUT_MS)]) : AbortSignal.timeout(REQUEST_TIMEOUT_MS);
+    try {
+        return await ctx.fetch(url, { ...init, signal: sig });
+    }
+    catch (err) {
+        throw new CliError(`could not reach ${url}: ${err instanceof Error ? err.message : String(err)}`, "network");
+    }
+}
+async function parseJson(res, url) {
+    try {
+        return await res.json();
+    }
+    catch {
+        throw new CliError(`${url} returned a non-JSON body`, "shape");
+    }
+}
+/** The OAuth `error` code from a 4xx body, or a short reason when there is none. */
+async function oauthError(res, url) {
+    try {
+        const body = (await res.json());
+        return body.error ?? body.error_description ?? `HTTP ${res.status}`;
+    }
+    catch {
+        return `HTTP ${res.status}`;
+    }
+}

package/dist/query.js

@@ -5,7 +5,7 @@
 import { flagInt, flagString, positionals } from "./args.js";
 import { requireConfig, replicaDbPath } from "./config.js";
 import { CliError, UsageError } from "./errors.js";
-import { apiClient } from "./http.js";
+import { apiClient } from "./transport.js";
 import { engineFor, replicaStatus } from "./replica.js";
 import { loadSdk } from "./sdk.js";
 const REPLICA_CAPABLE = new Set(["issues", "issue", "pulls", "projects"]);

package/dist/ready.js

@@ -8,6 +8,22 @@ import { contractVersionInRange, readContractCache } from "./contract.js";
 import { CliError } from "./errors.js";
 import { replicaStatus, statusLine } from "./replica.js";
 import { loadSdk } from "./sdk.js";
+/** True when `a` is a semver-older release than `b`. Prerelease/build metadata is ignored; a segment
+ *  that does not parse counts as 0. A tiny compare on purpose — no dependency for three fields. */
+export function semverOlder(a, b) {
+    const parse = (v) => {
+        const core = v.split("-")[0].split("+")[0];
+        const p = core.split(".");
+        return [Number(p[0]) || 0, Number(p[1]) || 0, Number(p[2]) || 0];
+    };
+    const [a0, a1, a2] = parse(a);
+    const [b0, b1, b2] = parse(b);
+    if (a0 !== b0)
+        return a0 < b0;
+    if (a1 !== b1)
+        return a1 < b1;
+    return a2 < b2;
+}
 function whoCanAnswer(doc) {
     const roles = doc.humans.map((h) => `${h.role} ${h.linearUserId}`);
     return roles.length ? roles.join(", ") : "a tenant owner or admin (none resolved on the contract)";
@@ -22,8 +38,17 @@ export async function readyReport(ctx, deps) {
     try {
         cfg = loadConfig(ctx.home);
         checks.push(cfg
-            ? { id: "config", ok: true, line: `config: joined ${cfg.name} (${cfg.slug}) as ${cfg.principal}` }
-            : { id: "config", ok: false, line: "config: not connected", fix: "CATALYST_CLOUD_TOKEN=<your personal key> npx @catalyst-cloud/catalyst-skills login", who: "you (mint the key at Settings → API keys)" });
+            ? {
+                id: "config",
+                ok: true,
+                // `principal` is "service" for every api key (it means "a key, not a browser session"); it
+                // never names a person. Since CTC-2076 a personal key's /me carries a `user` block, so name
+                // the connected person when there is one, and fall back to the account for a host key.
+                line: cfg.user
+                    ? `config: joined ${cfg.name} as ${cfg.user.label} (${cfg.user.role})`
+                    : `config: joined ${cfg.name} (${cfg.slug}) as ${cfg.principal}`,
+            }
+            : { id: "config", ok: false, line: "config: not connected", fix: "npx @catalyst-cloud/catalyst-skills login (keyless; or pass --key / set CATALYST_CLOUD_TOKEN)", who: "you (approve the login in your browser)" });
     }
     catch (err) {
         checks.push({ id: "config", ok: false, line: `config: ${err instanceof CliError ? err.message : String(err)}`, fix: "re-run login to rewrite it", who: "you" });
@@ -34,11 +59,26 @@ export async function readyReport(ctx, deps) {
         checks.push({ id: "contract", ok: false, line: "contract: not cached", fix: "catalyst-skills contract --refresh", who: "you" });
     }
     else if (contractVersionInRange(cache.contractVersion, range) !== true) {
-        checks.push({ id: "contract", ok: false, line: `contract: version ${cache.contractVersion} is outside this bundle's range ${range}`, fix: "npm update -g @catalyst-cloud/catalyst-skills", who: "you" });
+        checks.push({ id: "contract", ok: false, line: `contract: version ${cache.contractVersion} is outside this bundle's range ${range}`, fix: "npm install -g @catalyst-cloud/catalyst-skills@latest && catalyst-skills login", who: "you" });
     }
     else {
         checks.push({ id: "contract", ok: true, line: `contract: ${cache.contractVersion} cached ${cache.fetchedAt} (range ${range})` });
     }
+    // The cloud MAY publish the bundle it expects (catalyst-cloud#3746). Read it defensively: warn (never
+    // refuse) when this installed bundle is older than the minimum, and emit nothing when the field is
+    // absent (an older cloud) — a stale bundle is a degrading note, so `ready` still returns READY.
+    const minVersion = cache?.doc.skillsBundle?.minVersion;
+    if (minVersion) {
+        const installed = readManifest().version;
+        if (semverOlder(installed, minVersion)) {
+            checks.push({
+                id: "bundle",
+                ok: false,
+                note: true,
+                line: `bundle: ${installed} installed is older than the tenant's minimum ${minVersion} — upgrade: npm install -g @catalyst-cloud/catalyst-skills@latest && catalyst-skills login`,
+            });
+        }
+    }
     if (cfg) {
         checks.push(cfg.cliPath && existsSync(cfg.cliPath)
             ? { id: "cliPath", ok: true, line: `cliPath: ${cfg.cliPath}` }

package/dist/replica.js

@@ -10,7 +10,8 @@ import { flagBool, flagInt, flagString, positionals } from "./args.js";
 import { apiBase, loadConfig, replicaDbPath } from "./config.js";
 import { detachSelf } from "./detach.js";
 import { CliError, UsageError } from "./errors.js";
-import { apiClient } from "./http.js";
+import { apiClient } from "./transport.js";
+import { authStrategyFor } from "./oauth.js";
 import { loadSdk } from "./sdk.js";
 export const DEFAULT_STALE_MS = 15_000;
 export function pidfilePath(dbPath) {
@@ -204,7 +205,7 @@ async function cmdStart(args, ctx, cfg, dbPath, deps) {
         baseUrl: apiBase(cfg),
         account: cfg.account,
         accountSource: "declared",
-        auth: { kind: "token", token: cfg.key },
+        auth: authStrategyFor(ctx, cfg),
         dbPath,
         engine,
         fetchImpl: ctx.fetch,

package/dist/skills.js

@@ -70,5 +70,9 @@ export function readChangelog() {
 }
 export function updateNoticeLine(previous, current, entry) {
     const summary = entry ?? "see CHANGELOG.md";
-    return `[catalyst-skills] updated ${previous} → ${current}: ${summary} · update with: npm update -g ${PACKAGE_NAME} (or: npx ${PACKAGE_NAME}@latest login)`;
+    // `npm update -g` treats a global install as a caret range, and a caret below 1.0.0 never moves a
+    // minor — so it never crosses 0.2.x → 0.3.0. Pin @latest via `npm install`, THEN re-run login: the
+    // install alone does not rewrite customer.json.cliPath, so the skill helpers would keep spawning the
+    // stale recorded bundle and repeat this notice forever; the new global bin records its own path.
+    return `[catalyst-skills] updated ${previous} → ${current}: ${summary} · update with: npm install -g ${PACKAGE_NAME}@latest && catalyst-skills login`;
 }

package/dist/{http.js → transport.js}

@@ -1,16 +1,22 @@
 import { normalizeBaseUrl } from "./config.js";
 import { CliError, MeError } from "./errors.js";
+import { bearerFor } from "./oauth.js";
 export const REQUEST_TIMEOUT_MS = 15_000;
 export class ApiClient {
-    cfg;
+    baseUrl;
+    credential;
     fetchImpl;
-    constructor(cfg, fetchImpl) {
-        this.cfg = cfg;
+    constructor(baseUrl, 
+    /** Resolves the current bearer FRESH per request — a personal key verbatim, or the OAuth access
+     *  token refreshed within 60s of expiry (CTC-2112). Never captured once. */
+    credential, fetchImpl) {
+        this.baseUrl = baseUrl;
+        this.credential = credential;
         this.fetchImpl = fetchImpl;
     }
     /** `path` is absolute under the origin (e.g. `/api/v1/issues`). */
     url(path, query) {
-        const u = new URL(`${normalizeBaseUrl(this.cfg.baseUrl)}${path}`);
+        const u = new URL(`${normalizeBaseUrl(this.baseUrl)}${path}`);
         for (const [k, v] of Object.entries(query ?? {}))
             if (v !== undefined)
                 u.searchParams.set(k, String(v));
@@ -18,7 +24,7 @@ export class ApiClient {
     }
     async getJson(path, opts = {}) {
         const headers = {
-            authorization: `Bearer ${this.cfg.key}`,
+            authorization: `Bearer ${await this.credential()}`,
             accept: "application/json",
         };
         if (opts.etag)
@@ -44,7 +50,7 @@ export class ApiClient {
         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" },
+            headers: { authorization: `Bearer ${await this.credential()}`, accept: "application/x-ndjson, application/json" },
         });
         if (opts.accept?.includes(res.status))
             return { status: res.status, body: [], headers: res.headers };
@@ -69,7 +75,7 @@ export class ApiClient {
         const res = await this.send(url, {
             method: "POST",
             headers: {
-                authorization: `Bearer ${this.cfg.key}`,
+                authorization: `Bearer ${await this.credential()}`,
                 accept: "application/json",
                 "content-type": "application/json",
             },
@@ -121,8 +127,10 @@ export class ApiClient {
         throw new CliError(`${what} failed (${res.status})${reason ? `: ${reason}` : ""}`, "http", 2, res.status);
     }
 }
+/** Build the authenticated client for a config: the bearer resolves through {@link bearerFor}, so a
+ *  key config sends the key and an OAuth config sends a freshly-refreshed access token per request. */
 export function apiClient(cfg, ctx) {
-    return new ApiClient(cfg, ctx.fetch);
+    return new ApiClient(cfg.baseUrl, () => bearerFor(ctx, cfg), ctx.fetch);
 }
 /** GET /api/v1/me — how a key learns its own tenant. Unchanged contract from 0.1. */
 export async function fetchMe(baseUrl, key, fetchImpl, timeoutMs = REQUEST_TIMEOUT_MS) {

package/dist/watch/consumer.js

@@ -11,7 +11,7 @@ export function printFrame(frame) {
 }
 async function fetchHeadCursor(opts, signal) {
     const url = `${opts.baseUrl.replace(/\/+$/, "")}/snapshot?head=1`;
-    const res = await (opts.fetchImpl ?? fetch)(url, { headers: { authorization: `Bearer ${opts.token}` }, signal });
+    const res = await (opts.fetchImpl ?? fetch)(url, { headers: { authorization: `Bearer ${await opts.getToken()}` }, signal });
     if (!res.ok) {
         const body = (await res.text()).slice(0, 200);
         throw new Error(`head-only snapshot fetch failed: ${res.status} ${res.statusText} at ${url} — ${body}`);
@@ -111,7 +111,7 @@ export function createLiveEventsClient(sdk, opts) {
     const client = new sdk.LiveSyncClient({
         baseUrl: opts.baseUrl,
         accountId: opts.accountId,
-        auth: { kind: "token", token: opts.token },
+        auth: opts.auth,
         reseed: reseedHead,
         getCursor: () => state?.cursor ?? null,
         onChange: (frame) => {

package/dist/watch.js

@@ -7,7 +7,8 @@ import { flagList, flagString } from "./args.js";
 import { apiBase, requireConfig, watchCursorPathFor } from "./config.js";
 import { loadContract } from "./contract.js";
 import { CliError, UsageError } from "./errors.js";
-import { apiClient } from "./http.js";
+import { apiClient } from "./transport.js";
+import { authStrategyFor, bearerFor } from "./oauth.js";
 import { loadSdk } from "./sdk.js";
 import { createLiveEventsClient } from "./watch/consumer.js";
 import { CursorFileError } from "./watch/cursor-file.js";
@@ -135,7 +136,8 @@ export async function runWatch(ctx, cfg, opts, deps = {}) {
         return createLiveEventsClient(sdk, {
             baseUrl: apiBase(cfg),
             accountId: cfg.account,
-            token: cfg.key,
+            auth: authStrategyFor(ctx, cfg),
+            getToken: () => bearerFor(ctx, cfg),
             cursorFile: opts.cursorFile ?? watchCursorPathFor(ctx.home),
             fromHead: opts.fromHead,
             fetchImpl: ctx.fetch,

package/dist/write.js

@@ -6,7 +6,7 @@ import { flagBool, flagInt, flagList, flagString, positionals } from "./args.js"
 import { requireConfig } from "./config.js";
 import { bookkeepingPrefix, labelId, loadContract, routePath, stageIdForSlot, teamByKey, teamForTicket } from "./contract.js";
 import { CliError, UsageError } from "./errors.js";
-import { apiClient } from "./http.js";
+import { apiClient } from "./transport.js";
 /** A ticket identifier → its Linear id (and team/project) through GET /api/v1/issues/:identifier. */
 export async function resolveIssue(api, ticket) {
     const res = await api.getJson(`/api/v1/issues/${encodeURIComponent(ticket)}`, { accept: [404] });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catalyst-cloud/catalyst-skills",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "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",
@@ -41,7 +41,7 @@
     "version:sync": "node scripts/sync-plugin-version.mjs"
   },
   "dependencies": {
-    "@catalyst-cloud/sdk": "^0.8.49"
+    "@catalyst-cloud/sdk": "^0.9.0"
   },
   "devDependencies": {
     "@types/node": "^26.3.0",

package/skills/connect-me/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: connect-me
 description: >-
-  Connect this machine to the person's Catalyst Cloud tenant with their own personal 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 and the person, so nobody types an account id. Installing the skills is not this skill's job; the agent's own install command did that.
+  Connect this machine to the person's Catalyst Cloud tenant as themselves — keyless (a browser device-code login) or with their own personal key — cache the tenant contract, and verify. Use when a person is getting started, when their config is missing or broken, when their login expired or 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 login names the tenant and the person, 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:*)
 ---
@@ -9,28 +9,36 @@ allowed-tools: Bash(catalyst-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:
 
 # Connect me
 
-Connecting is one command. It asks the cloud who the key belongs to — which tenant, and which person — writes the config every skill and the CLI read, and caches the tenant contract beside it.
+Connecting is one command. Keyless is the preferred rail — with no key, `login` opens a browser device-code flow and logs the person in as themselves:
+
+```sh
+catalyst-skills login
+```
+
+It prints a short code and a URL; the person approves in a browser (or from a phone, on a machine with no browser) and this machine is connected as them. The short-lived session refreshes silently on every request, so they stay connected for months.
+
+A **personal key** still works for a script or an unattended shell — the environment form keeps it out of shell history; `--key <personal-key>` is the third form:
 
 ```sh
 CATALYST_CLOUD_TOKEN=<your-personal-key> catalyst-skills login
 ```
 
-With no environment variable and a terminal attached, `catalyst-skills login` prompts for the key without echoing it. `--key <personal-key>` is the third form, for a script. `npx @catalyst-cloud/catalyst-skills login` works when the package is not installed globally. A non-default cloud is pinned with `CATALYST_CLOUD_BASE_URL` or `--base-url`.
+`npx @catalyst-cloud/catalyst-skills login` works when the package is not installed globally. A non-default cloud is pinned with `CATALYST_CLOUD_BASE_URL` or `--base-url`.
 
 **This skill never installs skills.** You are already reading one, so the person's agent installed the set with its own command. Connecting is only about the credential and the contract.
 
-**What it writes.** `~/.config/catalyst-cloud/customer.json` (mode 0600) holding the key, the tenant it resolved, the person it resolved (`user`: id, label, role, Linear user id), and the absolute path of this CLI so skill scripts can spawn it; `~/.config/catalyst-cloud/contract.json`, the tenant contract with its ETag.
+**What it writes.** `~/.config/catalyst-cloud/customer.json` (mode 0600) holding the credential — a keyless login session (`auth`), or a personal key — the tenant it resolved, the person it resolved (`user`: id, label, role, Linear user id), and the absolute path of this CLI so skill scripts can spawn it; `~/.config/catalyst-cloud/contract.json`, the tenant contract with its ETag. A keyless session's token rotates on its own and the file is rewritten atomically each time.
 
 **The replica is optional and one command away.** Nothing has to be running for reads, writes, asks or explanations; the API is origin-fresh. `catalyst-skills replica start --detach` starts the local replica for cheap repeated reads and ad hoc SQL; `login --start-replica` does the same at the end. Every skill checks `catalyst-skills replica status` first and falls back to the API when the replica is absent or stale, saying so.
 
 ## What you do
 
-1. Ask the person to mint their **personal key** at Settings → API keys in the Catalyst Cloud web app (every active member can; no admin is needed) and hand it to the login command. It is shown once. Never put it in a file, a ticket, or this conversation beyond that one command. Do not ask an admin for the tenant's **account key** (`ctc_acct_`, Settings → Account keys): that is a host credential — runners, daemons, the host replica — and a person connected with it has no name on anything their agent writes, and "what needs me" cannot mean them. If they connect with one anyway, login says so on stderr and still works.
+1. Prefer keyless: run `catalyst-skills login` with no key and have the person approve the code in their browser (or from a phone). Nothing to mint, nothing to paste, nothing to keep out of the transcript. A **personal key** is the fallback for a script or unattended shell — they mint it at Settings → API keys (every active member can; no admin is needed) and hand it to the login command via `CATALYST_CLOUD_TOKEN`; it is shown once, so never put it in a file, a ticket, or this conversation beyond that one command. Either way, do not ask an admin for the tenant's **account key** (`ctc_acct_`, Settings → Account keys): that is a host credential — runners, daemons, the host replica — and a person connected with it has no name on anything their agent writes, and "what needs me" cannot mean them. If they connect with one anyway, login says so on stderr and still works.
 2. Run the login command. Its output names the tenant (`Connected to <name> (<slug>)`), the person (`Connected as <label> (<role>)`), the config path, and the cached contract version. If the person line says their Linear identity is not matched yet, tell them: an admin matches it in Settings → Members, and until then "what needs me" shows everyone's asks.
 3. Verify with `node scripts/verify-connection.mjs`: one line each for the tenant, the contract version, and the replica; exit 1 when the machine is not connected.
 4. Run `catalyst-skills ready` and read the verdict to them.
 5. Offer the replica: `catalyst-skills replica start --detach`, then `catalyst-skills replica status`. For keeping it alive across a reboot, load `references/keeping-the-replica-running.md`.
-6. If login fails: a `401` means a stale, mistyped or revoked key — mint a new one at Settings → API keys, never a retry loop; a network error names the URL, check `--base-url`. A `403` on the contract naming an older cloud means the cloud has not yet deployed personal-key access: update the cloud, or connect with the account key until it has. If login succeeds but prints a line naming two contract versions, the tenant serves a contract outside this bundle's range: update the bundle before using the other skills.
+6. If login fails: a keyless session that reports "your login expired or was revoked" needs one fresh `catalyst-skills login`, never a retry loop (it means the session was revoked or lapsed past the inactivity window — routine expiry refreshes silently and never surfaces). A `401` on the key rail means a stale, mistyped or revoked key — mint a new one at Settings → API keys, never a retry loop; a network error names the URL, check `--base-url`. A `403` on the contract naming an older cloud means the cloud has not yet deployed personal-key access: update the cloud, or connect with the account key until it has. If login succeeds but prints a line naming two contract versions, the tenant serves a contract outside this bundle's range: update the bundle before using the other skills.
 
 ## The verbs a session runs first
 
@@ -50,6 +58,6 @@ Every skill session opens with these, in this order, before doing anything else:
 
 ## Rules
 
-- **The key is a credential.** It goes into the login command or `CATALYST_CLOUD_TOKEN` and nowhere else: not into tickets, transcripts, or any file you write besides the one login writes.
-- **Never guess a tenant.** There is no `--account`; the key is the only tenant selector, on purpose. If the cloud names no tenant for the key, stop and say so.
+- **The credential is a secret.** Keyless is safest — nothing to handle. A key goes into the login command or `CATALYST_CLOUD_TOKEN` and nowhere else: not into tickets, transcripts, or any file you write besides the one login writes; and never read back the `auth` block a keyless session stores.
+- **Never guess a tenant.** There is no `--account`; the credential is the only tenant selector, on purpose. If the cloud names no tenant for the login, stop and say so.
 - **Read the update notice.** After a bundle update, the next command prints one line with the changelog entry and what to run; read it to the person if they are watching.