@catalyst-cloud/catalyst-skills 0.5.0 → 0.7.0

package/dist/replica.js

@@ -21,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;
@@ -83,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);
@@ -116,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";
@@ -130,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 = {}) {
@@ -147,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)
@@ -201,41 +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();
-    const eventSync = await createEventSync(ctx, { loadSdk: deps.loadEventsSdk });
-    void eventSync.start().catch((error) => {
-        ctx.stderr(`[events] sync failed: ${error instanceof Error ? error.message : String(error)}; replica remains live`);
-    });
-    ctx.stdout(`replica live at ${dbPath} (cursor ${replica.cursor ?? "none"}); event cache active — Ctrl-C to stop`);
-    const wait = deps.waitForStop ??
-        (() => new Promise((resolve) => {
-            const done = () => resolve();
-            process.once("SIGINT", done);
-            process.once("SIGTERM", done);
-        }));
-    await wait();
-    await eventSync.stop();
-    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/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.5.0",
-  "description": "Customer skill bundle for Catalyst Cloud: nine skills named from the executive's seat (whats-happening, what-needs-me, run-this-project, unstick, 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": {
@@ -39,7 +39,9 @@
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
     "version:sync": "node scripts/sync-plugin-version.mjs",
-    "skill-lib:sync": "node scripts/sync-skill-lib.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.10.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-linear/SKILL.md

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

package/skills/catalyst-linear/references/reading-a-ticket.md

@@ -48,3 +48,5 @@ Per-ticket execution history beyond the comments (the attempt ledger, the remedi
 ## Searching and listing
 
 `node scripts/search.mjs <terms>` matches ticket identifiers and titles, PR titles, project and initiative names and returns a few of each. It is the only search; a list read with a filter is not a search and will hand back the ordinary first page, which reads as a false "not found". Lists (`catalyst-skills query issues --team <key>`, `query projects`, `query cycles`) are for a board view, not for finding one ticket.
+
+A list verb now says when the cloud cut it short: without `--all`, `query issues`/`query pulls` print `truncated at N of M` on stderr the moment a scope holds more than one page. `query issues --all` and `query pulls --all` follow the cloud's page cursor to the end of the scope instead of stopping at the first page — use `--all` when the count, not just a sample, has to be right.

package/skills/catalyst-onboard/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: catalyst-onboard
+description: >-
+  Walk a person from nothing to their first Catalyst Cloud ticket running, one step at a time, hand-held. Use when someone says "set me up", "onboard me", "I just signed up", "get me started", "what do I do first", or when they have the skills installed and nothing else. Reads each part of the setup with the instrument that owns it — this machine, the person, the account, one project, one repository — never folding one into another, does every step a key can do through the catalyst-skills CLI, and for the steps only a browser can do hands over the exact page and says what to come back with. Never claims a step it did not watch succeed.
+disable-model-invocation: true
+allowed-tools: Bash(catalyst-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
+---
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.7.0 — written in this repository for customer tenants -->
+
+# Onboard me
+
+You take one person from "the skills are installed" to "a ticket is running on my own tenant". You do it **one step at a time**: do the step, show them what actually came back, say what it means and what is next, then stop and let them answer. You never print the whole ladder at them and you never batch several steps into one turn.
+
+Setup has five parts and each is read by its own instrument: this **machine**, the **person**, the **account**, one **project** (a project is one Linear team), one **repository**. A failure in one is not a failure in another, and a failing part names who can fix it and where. Getting that wrong is the one mistake that wastes a person's afternoon: a project problem reported as a machine problem sends them retrying a local command that was never going to help.
+
+## Run first
+
+Scripts are run, never read. Each prints `--help`.
+
+- `node scripts/where-am-i.mjs` — every part, each with the instrument that read it, its verdict, and for anything unfinished who can fix it and the page it is on. Works before the machine is connected; that is one of the states it reports.
+- `node scripts/where-am-i.mjs --next` — the same reading, reduced to the single next step.
+- `node scripts/where-am-i.mjs --json` — the same document for you to branch on.
+
+Start every session with it, and run it again after every step the person completes. It is the only thing that decides where you are.
+
+## Load on demand
+
+| when | read |
+| -- | -- |
+| walking the steps — what each one does, what to read back, when it is done | `references/the-one-path.md` |
+| anything reports not ready, or you are about to say who should fix something | `references/who-fixes-what.md` |
+| the next step is a browser page, or a page said it worked and you have to confirm it | `references/what-the-browser-owns.md` |
+| the person asks what Catalyst actually is, or how a ticket gets worked | the `how-catalyst-works` skill |
+| the machine will not connect, or a login expired | the `connect-me` skill |
+| setup is finished and they want the standing readiness verdict | the `catalyst-setup` skill |
+| the first ticket did not start and you need the reason | the `how-catalyst-works` skill, then `unstick` |
+
+## Rules
+
+- **One step, then stop.** Say what you are about to do, do it, show the real output, say what it means and what comes next. Never queue several steps into one message, and never move on from a step you did not watch finish.
+- **Report what you observed, not what you expected.** Print the lines the command actually produced. "That worked" without the output it produced is the single easiest thing to get wrong here, and a person who later finds it did not work stops trusting every other step you reported.
+- **Each part by its own instrument.** Read the machine with the machine's instrument and the project with the project's, and label every finding with the part it belongs to. The script does this for you; keep it that way when you summarize.
+- **Not ready is a question about who, not a reason to retry.** When something reports not ready, name which check, who can fix it, and where. If the owner is not the person in front of you, say so and stop — re-running a local command cannot move a check that belongs to a tenant owner, an admin, or a browser page.
+- **Never invent a count or a list.** Every number and every name comes from what a command printed. If you want to tell them how many projects are mapped, read it off the script's output; do not carry one over from an earlier turn.
+- **Three steps belong to a browser and always will**: approving the login, connecting Linear, and installing the GitHub App. Hand over the page and say what you need back. Do not claim you did them.
+- **Some steps a key cannot do yet.** Listing every project, saving a stage mapping, adopting the workflow, registering a repository and declaring one repository's environment are settings-page work today; a key-callable path for them is being built. Route those through the browser and say plainly that it is a gap, not the design. Never guess at a route for them.
+- **The account-wide environment declaration is the exception, and the one setup write you can perform.** `catalyst-skills environment` reads it, proposes it and approves it. Use the verb; do not send them to a page for it.
+- **Their tenant, as them.** Everything goes through the CLI and the person's own login. You never name another tenant, and you never ask for a key you could avoid — the keyless login needs nothing pasted.
+- **Stop at a wall you cannot pass.** A suspended account, a seat that is not active, a person who is not an owner or admin where one is required: say what you found, name who can act, and stop. Do not loop.