@catalyst-cloud/catalyst-skills 0.4.0 → 0.7.0

package/dist/replica.js

@@ -13,6 +13,7 @@ import { CliError, UsageError } from "./errors.js";
 import { apiClient } from "./transport.js";
 import { authStrategyFor } from "./oauth.js";
 import { loadSdk } from "./sdk.js";
+import { createEventSync } from "./events.js";
 export const DEFAULT_STALE_MS = 15_000;
 export function pidfilePath(dbPath) {
     return `${dbPath}.pid`;
@@ -20,6 +21,47 @@ export function pidfilePath(dbPath) {
 export function lockPath(dbPath) {
     return `${dbPath}.writer.lock`;
 }
+export function writerStatePath(dbPath) {
+    return `${dbPath}.writer.state`;
+}
+/** Read the writer's state sidecar. A missing file, unparseable JSON, or a record with the wrong
+ *  shape (a hand-edited or truncated file) all read as "no record", never a throw — readLock's
+ *  contract, followed here. */
+export function readWriterState(dbPath) {
+    try {
+        const rec = JSON.parse(readFileSync(writerStatePath(dbPath), "utf8"));
+        const stoppedOk = rec.stopped === null ||
+            (typeof rec.stopped === "object" &&
+                rec.stopped !== null &&
+                typeof rec.stopped.at === "number" &&
+                typeof rec.stopped.reason === "string" &&
+                typeof rec.stopped.restartWith === "string");
+        if (typeof rec.updatedAt !== "number" ||
+            typeof rec.pid !== "number" ||
+            typeof rec.consecutiveFailures !== "number" ||
+            !(rec.lastError === null || typeof rec.lastError === "string") ||
+            !(rec.lastFailureAt === null || typeof rec.lastFailureAt === "number") ||
+            !stoppedOk) {
+            return null;
+        }
+        return rec;
+    }
+    catch {
+        return null;
+    }
+}
+export function writeWriterState(dbPath, s, nowMs) {
+    writeFileSync(writerStatePath(dbPath), JSON.stringify({ ...s, updatedAt: nowMs }));
+}
+/** Remove the writer state sidecar; a no-op (never throws) when it is already gone. */
+export function clearWriterState(dbPath) {
+    try {
+        unlinkSync(writerStatePath(dbPath));
+    }
+    catch {
+        // already gone
+    }
+}
 export function pidAlive(pid) {
     if (pid === null || !Number.isInteger(pid) || pid <= 0)
         return false;
@@ -82,12 +124,14 @@ export function replicaStatus(ctx, cfg, opts = {}) {
         pidfilePid: null,
         writerAlive: false,
         reasons: [],
+        writer: null,
     };
     if (!cfg)
         return { ...base, reasons: ["not connected"] };
     const dbPath = opts.dbPath ?? replicaDbPath(cfg, ctx.home);
+    const writer = readWriterState(dbPath);
     if (!existsSync(dbPath))
-        return { ...base, verdict: "absent", exitCode: 3, dbPath, reasons: ["no replica file"] };
+        return { ...base, verdict: "absent", exitCode: 3, dbPath, reasons: ["no replica file"], writer };
     const staleMs = opts.staleMs ?? DEFAULT_STALE_MS;
     const nowMs = opts.nowMs ?? ctx.now().getTime();
     const lock = readLock(dbPath);
@@ -115,9 +159,10 @@ export function replicaStatus(ctx, cfg, opts = {}) {
         pidfilePid,
         writerAlive,
         reasons,
+        writer,
     };
 }
-export function statusLine(s) {
+function baseStatusLine(s) {
     switch (s.verdict) {
         case "not-configured":
             return "replica: not configured — run login first";
@@ -129,6 +174,30 @@ export function statusLine(s) {
             return `replica: stale at ${s.dbPath} (${s.reasons.join("; ")}${s.cursor !== null ? `; cursor ${s.cursor}` : ""}) — reads fall back to the API`;
     }
 }
+/** Is a process that could still be writing this replica alive? The lock/pidfile liveness
+ *  `replicaStatus` already computed, or the pid the writer stamped on its own record. Both renderers
+ *  ask before describing that record in the present tense: the sidecar outlives a SIGKILL, a crash
+ *  and a reboot, and "is backing off" about a dead process sends a customer off to wait for a retry
+ *  that will never come (CTC-2499). */
+export function writerIsRunning(s) {
+    return s.writerAlive || pidAlive(s.writer?.pid ?? null);
+}
+export function statusLine(s) {
+    const base = baseStatusLine(s);
+    const w = s.writer;
+    if (w?.stopped) {
+        return (`${base} — the writer stopped ${new Date(w.stopped.at).toISOString()}: ${w.stopped.reason} ` +
+            `(last error: ${w.lastError}); restart it with: ${w.stopped.restartWith}`);
+    }
+    if (w && w.consecutiveFailures > 0) {
+        if (!writerIsRunning(s)) {
+            return (`${base} — the writer recorded ${w.consecutiveFailures} failed snapshot pulls and is no longer running ` +
+                `(last error: ${w.lastError}); restart it with: ${REPLICA_RESTART_COMMAND}`);
+        }
+        return `${base} — the writer has failed ${w.consecutiveFailures} snapshot pulls in a row and is backing off (last error: ${w.lastError})`;
+    }
+    return base;
+}
 /** better-sqlite3 when it resolves and constructs, else node:sqlite — with exactly one stderr line
  *  on the fallback so the choice is visible. */
 export async function engineFor(sdk, dbPath, ctx, deps = {}) {
@@ -146,6 +215,54 @@ export async function engineFor(sdk, dbPath, ctx, deps = {}) {
         return deps.readonly ? sdk.nodeSqliteReadonlyEngine(dbPath) : sdk.nodeSqliteEngine(dbPath);
     }
 }
+export const SNAPSHOT_BASE_BACKOFF_MS = 30_000;
+export const SNAPSHOT_MAX_BACKOFF_MS = 900_000; // 15 minutes
+export const SNAPSHOT_MAX_FAILURES = 5;
+/** How long a live session must hold before the supervisor calls the writer recovered. A warm boot
+ *  emits no "resyncing", so a writer that recovered WITHOUT a re-seed has no transition to reset its
+ *  count on; staying live is that signal. The failing warm loop never reaches it — its resync demand
+ *  fails and tears the attempt down first (CTC-2499). */
+export const SNAPSHOT_LIVE_STABLE_MS = 60_000;
+export const REPLICA_RESTART_COMMAND = "catalyst-skills replica start --detach";
+const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+function defaultWaitForStop() {
+    return new Promise((resolve) => {
+        const done = () => resolve();
+        process.once("SIGINT", done);
+        process.once("SIGTERM", done);
+    });
+}
+/** Full jitter (AWS "Exponential Backoff and Jitter"): a uniform draw from [0, bound), where the
+ *  bound doubles per consecutive failure and is clamped at the cap. */
+export function backoffDelayMs(consecutiveFailures, opts) {
+    const bound = Math.min(opts.baseMs * 2 ** Math.max(0, consecutiveFailures - 1), opts.maxMs);
+    return Math.floor(opts.random() * bound);
+}
+function releaseOwnPidfile(dbPath) {
+    try {
+        if (readPidfile(dbPath) === process.pid)
+            unlinkSync(pidfilePath(dbPath));
+    }
+    catch {
+        // pidfile already gone
+    }
+}
+function messageOf(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/** Classify a `start()` rejection: null when it is an ordinary failed snapshot pull and the
+ *  supervisor should count it, back off and retry. */
+export function classifyStartError(err) {
+    const reason = messageOf(err);
+    if (err?.name === "ReplicaAccountMismatchError")
+        return { reason, recordable: false };
+    if (reason.includes("another writer owns this replica"))
+        return { reason, recordable: false };
+    // start()'s own lifecycle guards: a caller bug, never a tenant-side failure.
+    if (reason.includes("start() already called") || reason.includes("start() after close()"))
+        return { reason, recordable: false };
+    return null;
+}
 export async function cmdReplica(args, ctx, deps = {}) {
     const [sub, ...rest] = positionals(args);
     if (!sub)
@@ -200,36 +317,185 @@ async function cmdStart(args, ctx, cfg, dbPath, deps) {
         return 0;
     }
     const sdk = await loadSdk();
-    const engine = await engineFor(sdk, dbPath, ctx, deps.engineDeps);
-    const replica = new sdk.CatalystReplica({
-        baseUrl: apiBase(cfg),
-        account: cfg.account,
-        accountSource: "declared",
-        auth: authStrategyFor(ctx, cfg),
-        dbPath,
-        engine,
-        fetchImpl: ctx.fetch,
-        wsFactory: deps.wsFactory,
-        log: (level, msg, extra) => ctx.stderr(`[replica ${level}] ${msg}${extra ? ` ${safeJson(extra)}` : ""}`),
-        onStatus: (s) => ctx.stderr(`[replica] status=${s}`),
+    const sleep = deps.sleep ?? defaultSleep;
+    const random = deps.random ?? Math.random;
+    const baseMs = deps.snapshotRetry?.baseBackoffMs ?? SNAPSHOT_BASE_BACKOFF_MS;
+    const maxMs = deps.snapshotRetry?.maxBackoffMs ?? SNAPSHOT_MAX_BACKOFF_MS;
+    const maxFailures = deps.snapshotRetry?.maxFailures ?? SNAPSHOT_MAX_FAILURES;
+    const liveStableMs = deps.snapshotRetry?.liveStableMs ?? SNAPSHOT_LIVE_STABLE_MS;
+    // Registered ONCE, not per attempt, so a supervised run does not pile up signal handlers.
+    let stopRequested = false;
+    const stopSignal = (deps.waitForStop ?? defaultWaitForStop)().then(() => {
+        stopRequested = true;
     });
-    await replica.start();
-    ctx.stdout(`replica live at ${dbPath} (cursor ${replica.cursor ?? "none"}) — Ctrl-C to stop`);
-    const wait = deps.waitForStop ??
-        (() => new Promise((resolve) => {
-            const done = () => resolve();
-            process.once("SIGINT", done);
-            process.once("SIGTERM", done);
-        }));
-    await wait();
-    await replica.close();
-    try {
-        if (readPidfile(dbPath) === process.pid)
-            unlinkSync(pidfilePath(dbPath));
-    }
-    catch {
-        // pidfile already gone
+    let eventSync = null;
+    let failures = 0;
+    /** A new run never inherits an old run's verdict — but it discards it only once it OWNS the
+     *  replica. `start()` claims the writer lock before it does anything else, so an attempt that gets
+     *  past that lock is ours; clearing up front deleted a LIVE writer's record whenever a second
+     *  `replica start` lost the lock race (CTC-2499). */
+    let recordOwned = false;
+    const takeOwnershipOfRecord = () => {
+        if (recordOwned)
+            return;
+        recordOwned = true;
+        clearWriterState(dbPath);
+    };
+    const resetFailures = () => {
+        if (failures === 0)
+            return;
+        failures = 0;
+        writeWriterState(dbPath, { pid: process.pid, consecutiveFailures: 0, lastError: null, lastFailureAt: null, stopped: null }, ctx.now().getTime());
+    };
+    for (;;) {
+        const engine = await engineFor(sdk, dbPath, ctx, deps.engineDeps);
+        let seedInFlight = false; // a /snapshot pull is running RIGHT NOW
+        let seedCompleted = false; // ...and the last one finished; what follows belongs to the socket
+        let attemptError = null;
+        // A box rather than a `let`: TypeScript narrows a captured `let` initialised to null down to
+        // `never`, and the supervisor below has to read what these callbacks wrote.
+        const fatal = { stop: null };
+        let signalFailure;
+        const failed = new Promise((res) => (signalFailure = res));
+        const replica = new sdk.CatalystReplica({
+            baseUrl: apiBase(cfg),
+            account: cfg.account,
+            accountSource: "declared",
+            auth: authStrategyFor(ctx, cfg),
+            dbPath,
+            engine,
+            fetchImpl: ctx.fetch,
+            wsFactory: deps.wsFactory,
+            log: (level, msg, extra) => ctx.stderr(`[replica ${level}] ${msg}${extra ? ` ${safeJson(extra)}` : ""}`),
+            onStatus: (s) => {
+                ctx.stderr(`[replica] status=${s}`);
+                // A "live" that does NOT follow a re-seed is just the socket coming up — the warm failing
+                // loop passes through it every cycle, so it must not reset the count (CTC-2499).
+                if (s === "resyncing") {
+                    seedInFlight = true;
+                    seedCompleted = false;
+                    return;
+                }
+                // openSocket() runs only after the seed has committed its cursor, so "connecting" is the
+                // SDK's one observable "the snapshot completed" edge. Everything after it is socket work: a
+                // blocked WebSocket upgrade is not a failed snapshot pull (CTC-2499).
+                if (s === "connecting") {
+                    if (seedInFlight) {
+                        seedInFlight = false;
+                        seedCompleted = true;
+                    }
+                    return;
+                }
+                if (s === "live") {
+                    if (seedCompleted) {
+                        seedCompleted = false;
+                        resetFailures();
+                    }
+                    return;
+                }
+                if ((s === "reconnecting" || s === "error") && seedInFlight && attemptError === null) {
+                    seedInFlight = false;
+                    attemptError = "the snapshot pull failed or ended early";
+                    // SYNCHRONOUS inside onStatus: LiveSyncClient.stop() sets `stopped = true` as its first
+                    // statement, and scheduleReconnect() — the very next statement in runResync() — returns
+                    // early on it. This is what keeps the SDK from re-entering its own loop.
+                    void replica.close().catch(() => { });
+                    signalFailure();
+                    return;
+                }
+                if (s === "auth-required" && attemptError === null) {
+                    // A refused credential is not something to retry against the tenant at all: it is stopped
+                    // and recorded, not counted towards maxFailures (CTC-2499).
+                    seedInFlight = false;
+                    seedCompleted = false;
+                    attemptError = "the tenant refused this machine's credential on /snapshot";
+                    fatal.stop = { reason: attemptError, recordable: true };
+                    void replica.close().catch(() => { });
+                    signalFailure();
+                }
+            },
+        });
+        // Always give start() a handler, so a rejection that loses the race is never unhandled.
+        const started = replica.start().then(() => "started", (err) => {
+            fatal.stop ??= classifyStartError(err);
+            attemptError ??= messageOf(err);
+            return "failed";
+        });
+        const outcome = await Promise.race([started, failed.then(() => "failed"), stopSignal.then(() => "stop")]);
+        // Something the SDK raised so the caller would STOP: retrying it is a hot loop against a wall,
+        // and two of the three fire while another process or another tenant owns this replica — so the
+        // record is left exactly as its owner wrote it (CTC-2499).
+        const stopNow = fatal.stop;
+        if (outcome === "failed" && stopNow !== null) {
+            await replica.close().catch(() => { });
+            await eventSync?.stop();
+            releaseOwnPidfile(dbPath);
+            if (stopNow.recordable) {
+                takeOwnershipOfRecord();
+                const nowMs = ctx.now().getTime();
+                writeWriterState(dbPath, { pid: process.pid, consecutiveFailures: failures, lastError: stopNow.reason, lastFailureAt: nowMs, stopped: { at: nowMs, reason: stopNow.reason, restartWith: REPLICA_RESTART_COMMAND } }, nowMs);
+            }
+            ctx.stderr(`[replica] stopping without a retry: ${stopNow.reason}`);
+            ctx.stdout(`replica writer stopped without retrying: ${stopNow.reason} ` +
+                `The replica is optional — every read still works through the API.`);
+            return 1;
+        }
+        // Past the writer lock, so this run owns the replica and may discard a previous run's verdict.
+        // A "stop" outcome proves nothing — it can race the lock claim — so it takes no ownership.
+        if (outcome !== "stop")
+            takeOwnershipOfRecord();
+        if (outcome === "started") {
+            // The event cache is started once for the whole supervised run, not per attempt.
+            if (eventSync === null) {
+                eventSync = await createEventSync(ctx, { loadSdk: deps.loadEventsSdk });
+                void eventSync.start().catch((error) => ctx.stderr(`[events] sync failed: ${messageOf(error)}; replica remains live`));
+            }
+            ctx.stdout(`replica live at ${dbPath} (cursor ${replica.cursor ?? "none"}); event cache active — Ctrl-C to stop`);
+            // A warm boot never emits "resyncing", so a writer that recovered without a re-seed has no
+            // transition to reset its count on, and its stale count would both mis-report a healthy writer
+            // and accumulate NON-consecutive failures up to the stop threshold. A live session that holds
+            // for liveStableMs is that missing signal (CTC-2499).
+            if (failures > 0) {
+                const settled = await Promise.race([
+                    failed.then(() => "failed"),
+                    stopSignal.then(() => "stop"),
+                    sleep(liveStableMs).then(() => "stable"),
+                ]);
+                if (settled === "stable")
+                    resetFailures();
+            }
+            // start() resolves at the FIRST "live", which is the socket, not the seed — keep watching.
+            await Promise.race([failed, stopSignal]);
+        }
+        await replica.close().catch(() => { });
+        if (stopRequested)
+            break;
+        failures += 1;
+        const lastError = attemptError ?? "the snapshot pull failed";
+        const nowMs = ctx.now().getTime();
+        const stopped = failures >= maxFailures
+            ? { at: nowMs, reason: `${failures} consecutive snapshot failures`, restartWith: "catalyst-skills replica start --detach" }
+            : null;
+        writeWriterState(dbPath, { pid: process.pid, consecutiveFailures: failures, lastError, lastFailureAt: nowMs, stopped }, nowMs);
+        if (stopped) {
+            await eventSync?.stop();
+            releaseOwnPidfile(dbPath);
+            ctx.stderr(`[replica] stopping: ${stopped.reason}; last error: ${lastError}`);
+            ctx.stdout(`replica writer stopped after ${failures} consecutive snapshot failures (last error: ${lastError}). ` +
+                `The replica is optional — every read still works through the API. ` +
+                `Restart it with: ${stopped.restartWith}`);
+            return 1;
+        }
+        const delay = backoffDelayMs(failures, { baseMs, maxMs, random });
+        ctx.stderr(`[replica] snapshot failure ${failures} of ${maxFailures}: ${lastError}; retrying in ${delay}ms`);
+        await Promise.race([sleep(delay), stopSignal]);
+        if (stopRequested)
+            break;
     }
+    await eventSync?.stop();
+    releaseOwnPidfile(dbPath);
+    if (recordOwned)
+        clearWriterState(dbPath); // never a record this run had no right to
     ctx.stdout("replica stopped");
     return 0;
 }

package/dist/semver.js

@@ -0,0 +1,18 @@
+// semver.ts — the one three-field comparator every version-drift check in this package shares
+// (the tenant-minimum bundle check, and CTC-2160's published-release checks).
+/** 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;
+}

package/dist/skill-shape.js

@@ -7,6 +7,16 @@ export const PROVENANCE_MARKER = "vendored-from: @catalyst-cloud/catalyst-skills
 export const MAX_SKILL_LINES = 80;
 export const MAX_REFERENCE_LINES = 150;
 export const MAX_DESCRIPTION_CHARS = 1024;
+/** The first release whose SKILL.md files carry a version on the provenance line. An installed
+ *  skill with the marker and no version predates this release — but that only PROVES staleness
+ *  once a release at or above it has actually been published (CTC-2160 D4). */
+export const FIRST_STAMPED_VERSION = "0.7.0";
+const PROVENANCE_VERSION_RE = new RegExp(`${PROVENANCE_MARKER.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}@(\\S+)`);
+/** The version stamped on a provenance comment line, or null when the line carries none. */
+export function parseProvenanceVersion(line) {
+    const m = PROVENANCE_VERSION_RE.exec(line);
+    return m ? m[1] : null;
+}
 /** Strings no customer-facing skill file may contain. */
 export const FORBIDDEN_CONTENT = [
     { name: "the maintainer tenant (tenant-0)", re: /tenant-0/ },

package/dist/skills.js

@@ -4,7 +4,8 @@ import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync } fr
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { PACKAGE_NAME, defaultSkillsDirFor } from "./config.js";
-import { PROVENANCE_MARKER } from "./skill-shape.js";
+import { semverOlder } from "./semver.js";
+import { PROVENANCE_MARKER, parseFrontmatter, parseProvenanceVersion } from "./skill-shape.js";
 export function skillsSourceDir() {
     return fileURLToPath(new URL("../skills", import.meta.url));
 }
@@ -49,6 +50,56 @@ export function installSkills(targetDir, opts, sourceDir = skillsSourceDir()) {
 export function resolveSkillsDir(args, ctx, cfg) {
     return args.skillsDir ?? ctx.env.CATALYST_SKILLS_CLAUDE_DIR ?? cfg?.skillsDir ?? defaultSkillsDirFor(ctx.home);
 }
+/** The provenance comment in a SKILL.md, wherever that file's frontmatter actually ends.
+ *
+ *  `validateSkillDir` requires the comment on the line right after the closing fence and caps the
+ *  FILE's length, never the frontmatter's — so a fixed head window was an unpinned assumption, and a
+ *  skill with a long wrapped `description` fell past it and became invisible: no version and not even
+ *  counted as unstamped, silently dropping out of the staleness check. A file whose shape is off
+ *  falls back to the whole-file scan `installSkills` already uses to recognise our own copies. */
+function provenanceLine(text) {
+    const lines = text.split("\n");
+    const fm = parseFrontmatter(lines);
+    if (fm && fm.closeIndex !== -1) {
+        const after = lines[fm.closeIndex + 1];
+        if (after?.includes(PROVENANCE_MARKER))
+            return after;
+    }
+    return lines.find((l) => l.includes(PROVENANCE_MARKER));
+}
+/** What skill-bundle version is actually sitting in `dir`. Reads only the provenance comment; a
+ *  directory this package did not write (no marker) is ignored, not counted as stale, and a name
+ *  that is not installed at all is skipped. */
+export function installedBundleVersion(dir, names) {
+    let version = null;
+    let skill = null;
+    const unstamped = [];
+    for (const name of names) {
+        const skillMd = join(dir, name, "SKILL.md");
+        if (!existsSync(skillMd))
+            continue;
+        let text;
+        try {
+            text = readFileSync(skillMd, "utf8");
+        }
+        catch {
+            continue;
+        }
+        const line = provenanceLine(text);
+        if (line === undefined)
+            continue;
+        const stamp = parseProvenanceVersion(line);
+        if (stamp === null) {
+            unstamped.push(name);
+            continue;
+        }
+        if (version === null || semverOlder(stamp, version)) {
+            version = stamp;
+            skill = name;
+        }
+    }
+    return { version, skill, unstamped };
+}
 export function parseChangelogEntry(changelog, version) {
     const lines = changelog.split("\n");
     const heading = `## ${version}`;

package/dist/transport.js

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

package/dist/ts-deps-loader.js

@@ -17,6 +17,51 @@ let installed = false;
 function inDeps(url) {
     return typeof url === "string" && url.startsWith("file:") && url.includes("/node_modules/");
 }
+/** Both modes this runtime offers refused the source. Naming the file and both refusals beats
+ *  surfacing Node's raw `options.mode` message, which names the mode Node rejected rather than the
+ *  syntax in the SOURCE that made both modes fail. */
+export class StripModeError extends Error {
+    sourceUrl;
+    refusals;
+    constructor(sourceUrl, refusals) {
+        super(`${sourceUrl}: could not be type-stripped by any mode this runtime offers. This usually means ` +
+            `the source uses TypeScript syntax with runtime semantics (an enum, a runtime namespace, a ` +
+            `parameter property, or \`export =\`) that Node's type-stripping can never erase, on a ` +
+            `runtime that also refuses \`transform\`. ` +
+            `strip refused: ${refusals.strip} | transform refused: ${refusals.transform}`);
+        this.name = "StripModeError";
+        this.sourceUrl = sourceUrl;
+        this.refusals = refusals;
+    }
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** CTC-2483 — strip types preferring the one mode EVERY supported Node accepts.
+ *
+ *  ⭐ `strip` is always tried first, and that ordering is the whole fix. Node 26's
+ *  `stripTypeScriptTypes` accepts only `{ mode: "strip" }` and throws ERR_INVALID_ARG_VALUE for
+ *  `"transform"`, so a loader that reaches for `transform` first dies there before it ever learns
+ *  whether `strip` would have worked. But `strip` is not a weaker `transform`: it REFUSES
+ *  TypeScript syntax with runtime semantics (enums, runtime namespaces, parameter properties,
+ *  `export =`) that `transform` erases, so `transform` stays reachable as a fallback on Node 22-25
+ *  for sources that need it. */
+export function stripPreferringStrip(strip, source, sourceUrl) {
+    try {
+        return strip(source, { mode: "strip", sourceUrl });
+    }
+    catch (stripError) {
+        try {
+            return strip(source, { mode: "transform", sourceUrl });
+        }
+        catch (transformError) {
+            throw new StripModeError(sourceUrl, {
+                strip: messageOf(stripError),
+                transform: messageOf(transformError),
+            });
+        }
+    }
+}
 /** Build the hook pair over a strip function. Pure, so a test can drive it with fake `next`s. */
 export function makeHooks(strip, fileExists = existsSync, readFile = (p) => readFileSync(p, "utf8")) {
     return {
@@ -37,7 +82,7 @@ export function makeHooks(strip, fileExists = existsSync, readFile = (p) => read
         },
         load(url, context, next) {
             if (inDeps(url) && url.endsWith(".ts")) {
-                return { format: "module", shortCircuit: true, source: strip(readFile(fileURLToPath(url)), { mode: "transform", sourceUrl: url }) };
+                return { format: "module", shortCircuit: true, source: stripPreferringStrip(strip, readFile(fileURLToPath(url)), url) };
             }
             return next(url, context);
         },

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@catalyst-cloud/catalyst-skills",
-  "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.",
+  "version": "0.7.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-skills 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",
   "publishConfig": {
@@ -38,10 +38,13 @@
     "prepare": "tsc -p tsconfig.build.json",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
-    "version:sync": "node scripts/sync-plugin-version.mjs"
+    "version:sync": "node scripts/sync-plugin-version.mjs",
+    "skill-lib:sync": "node scripts/sync-skill-lib.mjs",
+    "skills:scan": "node scripts/scan-skills.mjs",
+    "evals": "node scripts/run-evals.mjs"
   },
   "dependencies": {
-    "@catalyst-cloud/sdk": "^0.9.0"
+    "@catalyst-cloud/sdk": "^0.10.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 — written in this repository for customer tenants -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.7.0 — written in this repository for customer tenants -->
 
 # Catalyst's GitHub
 

package/skills/catalyst-github/scripts/lib/cli.mjs

@@ -8,9 +8,10 @@ import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { CONNECT_COMMAND, hasCredential } from "./credential.mjs";
 
 export const PACKAGE = "@catalyst-cloud/catalyst-skills";
-export const CONNECT_HINT = `this machine is not connected to a tenant yet — run: CATALYST_CLOUD_TOKEN=<your personal key> npx ${PACKAGE} login`;
+export const CONNECT_HINT = `this machine is not connected to a tenant yet — run: ${CONNECT_COMMAND}`;
 
 /** ~/.config/catalyst-cloud/customer.json, honouring CATALYST_SKILLS_HOME before HOME. */
 export function configPath() {
@@ -32,7 +33,7 @@ export function requireCustomerConfig() {
     console.error(`${path} could not be read (${err instanceof Error ? err.message : String(err)}) — ${CONNECT_HINT}`);
     process.exit(2);
   }
-  if (!cfg || typeof cfg !== "object" || typeof cfg.key !== "string" || typeof cfg.baseUrl !== "string") {
+  if (!hasCredential(cfg) || typeof cfg.baseUrl !== "string") {
     console.error(`${path} is missing required fields — ${CONNECT_HINT}`);
     process.exit(2);
   }

package/skills/catalyst-github/scripts/lib/credential.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+// lib/credential.mjs — is this machine connected? The ONE place a skill script decides it, vendored
+// byte-identical into every skill's scripts/lib/ from skill-lib/credential.mjs at the package root
+// (`npm run skill-lib:sync`; a test fails on any drift). Skills install one directory at a time, so
+// each carries its own copy. This file is a library — run a sibling script with --help for usage.
+//
+// customer.json carries exactly one credential: a personal key (`key`), or the keyless login's
+// session (`auth`, the recommended rail). A script never reads either for its value: it spawns the
+// catalyst-skills CLI, which authenticates with whichever is present and refreshes a login's token
+// itself. A new credential kind lands here, once.
+
+/** The command that connects this machine, as every not-connected line names it. */
+export const CONNECT_COMMAND =
+  "npx @catalyst-cloud/catalyst-skills login (or, with a personal key: CATALYST_CLOUD_TOKEN=<your personal key> npx @catalyst-cloud/catalyst-skills login)";
+
+/** True when `cfg` (parsed customer.json) holds a usable credential of either kind. Never throws. */
+export function hasCredential(cfg) {
+  if (cfg === null || typeof cfg !== "object") return false;
+  const key = cfg["key"];
+  if (typeof key === "string" && key !== "") return true;
+  const login = cfg["auth"];
+  return (
+    login !== null &&
+    typeof login === "object" &&
+    login["kind"] === "oauth" &&
+    typeof login["refreshToken"] === "string" &&
+    login["refreshToken"] !== ""
+  );
+}