@catalyst-cloud/cli 0.13.0 → 0.13.1

package/dist/legacy.js

@@ -0,0 +1,224 @@
+// legacy.ts — `catalyst legacy`: leftovers of the old LOCAL Catalyst runtime (the archived repository
+// whose plugin, daemons, scheduled jobs and state folders a machine may still carry), found from a
+// FIXED list and removed only on a yes, through the tools that own each piece. The cloud runtime
+// replaced all of it; what is left can start old jobs or shadow current commands, so removal is
+// recommended, and never automatic: a run with no terminal and no --yes only reports.
+//
+// The list is fixed on purpose. A prefix match would one day catch a current job (the housekeeping
+// job, the sandbox credit guard, jobs a person made); this matches names the old runtime installed,
+// read at the source commit below, and nothing else. Data folders are a separate yes (--data).
+import { existsSync, lstatSync, readFileSync, readdirSync, rmSync, unlinkSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { join } from "node:path";
+import { flagBool, positionals } from "./args.js";
+import { UsageError } from "./errors.js";
+import { promptSecret, stdinIsTty } from "./prompt.js";
+/** The archived repository's commit the list below was read at. */
+export const LEGACY_SOURCE_COMMIT = "73bc0645252ce8be38f8c87be6b67b950b3f0b56";
+/** The old runtime's marketplace source, as Claude Code records it in known_marketplaces.json. */
+export const OLD_MARKETPLACE_REPO = "coalesce-labs/catalyst";
+/** launchd labels the old runtime installed under ~/Library/LaunchAgents (macOS). `com.catalyst.role.<name>`
+ *  is the old role supervisor's per-role instance, matched by that exact prefix. Never `dev.catalystcloud.*`
+ *  (the current housekeeping job and runner jobs) and never `dev.catalyst.*` (the sandbox credit guard). */
+export const OLD_LAUNCHD_LABELS = [
+    "com.catalyst.agent",
+    "com.catalyst.reaper-watch",
+    "com.catalyst.quiet-fleet",
+    "com.catalyst.dead-man",
+    "com.catalyst.holding-sentinel",
+    "com.catalyst.orch-monitor",
+    "com.catalyst.role",
+    "ai.coalesce.catalyst-stack",
+    "ai.coalesce.catalyst-thoughts-sync",
+    "ai.coalesce.catalyst-orphan-sweep",
+    "ai.coalesce.catalyst-log-shipper",
+    "ai.coalesce.catalyst-cloud-sync",
+    "ai.coalesce.catalyst-usage-page",
+    "ai.coalesce.catalyst-claude-update",
+    "ai.coalesce.catalyst-updater",
+    "ai.coalesce.catalyst-replica-sync",
+    "ai.coalesce.catalyst-channel-watcher",
+    "ai.coalesce.catalyst-event-mirror",
+    "ai.coalesce.catalyst-monitor",
+];
+const OLD_ROLE_PREFIX = "com.catalyst.role.";
+/** systemd user units (~/.config/systemd/user) the old runtime's workstation pieces used on Linux. System
+ *  units under /etc/systemd/system are a host's, current, and never looked at. */
+export const OLD_USER_UNITS = ["catalyst.service", "catalyst-monitor.service"];
+/** Command files the old runtime put on the person's PATH. `~/.local/bin/catalyst` is NOT one: that
+ *  name belongs to the current CLI wherever npm put it. */
+export const OLD_BINS = [".catalyst/bin", ".local/bin/catalyst-events", ".local/bin/catalyst-filter", ".local/bin/catalyst-hud", ".local/bin/catalyst-monitor", ".local/bin/catalyst-myown"];
+/** State the old runtime kept. `~/.config/catalyst-cloud` is the current CLI's and never touched. */
+export const OLD_DATA_DIRS = [".catalyst", ".config/catalyst", ".local/state/catalyst", ".local/state/catalyst-fleet-runner", ".local/state/catalyst-ledger"];
+const RECOMMEND = "Remove them: the cloud runtime replaced them, and left in place they can start old jobs or shadow current commands.";
+function readJson(path) {
+    try {
+        const v = JSON.parse(readFileSync(path, "utf8"));
+        return v !== null && typeof v === "object" ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Marketplaces whose recorded source is the old repository, and the plugins installed from them. */
+function findPlugins(home) {
+    const dir = join(home, ".claude", "plugins");
+    const marketplaces = readJson(join(dir, "known_marketplaces.json")) ?? {};
+    const old = Object.entries(marketplaces)
+        .filter(([, v]) => {
+        const src = v?.source;
+        return typeof src?.repo === "string" && src.repo.toLowerCase() === OLD_MARKETPLACE_REPO;
+    })
+        .map(([name]) => name);
+    if (old.length === 0)
+        return [];
+    const installed = (readJson(join(dir, "installed_plugins.json")) ?? {}).plugins ?? {};
+    const items = [];
+    for (const key of Object.keys(installed)) {
+        const at = key.lastIndexOf("@");
+        if (at > 0 && old.includes(key.slice(at + 1)))
+            items.push({ kind: "plugin", name: key, path: join(dir, "installed_plugins.json") });
+    }
+    for (const name of old)
+        items.push({ kind: "marketplace", name, path: join(dir, "known_marketplaces.json") });
+    return items;
+}
+function findJobs(home, platform) {
+    if (platform === "darwin") {
+        const dir = join(home, "Library", "LaunchAgents");
+        let files = [];
+        try {
+            files = readdirSync(dir);
+        }
+        catch {
+            return [];
+        }
+        return files
+            .filter((f) => f.endsWith(".plist"))
+            .map((f) => f.slice(0, -".plist".length))
+            .filter((label) => OLD_LAUNCHD_LABELS.includes(label) || label.startsWith(OLD_ROLE_PREFIX))
+            .sort()
+            .map((label) => ({ kind: "job", name: label, path: join(dir, `${label}.plist`) }));
+    }
+    if (platform === "linux") {
+        const dir = join(home, ".config", "systemd", "user");
+        return OLD_USER_UNITS.filter((u) => existsSync(join(dir, u))).map((u) => ({ kind: "job", name: u, path: join(dir, u) }));
+    }
+    return [];
+}
+const tilde = (rel) => `~/${rel}`;
+function findFiles(home) {
+    const bins = OLD_BINS.filter((rel) => existsSync(join(home, rel))).map((rel) => ({ kind: "bin", name: tilde(rel), path: join(home, rel) }));
+    const data = OLD_DATA_DIRS.filter((rel) => existsSync(join(home, rel))).map((rel) => ({ kind: "data", name: tilde(rel), path: join(home, rel), data: true }));
+    return [...bins, ...data];
+}
+/** Every old piece on this machine, in removal order: plugins, their marketplace, jobs, bins, data. Never writes. */
+export function findLegacy(home, platform) {
+    return [...findPlugins(home), ...findJobs(home, platform), ...findFiles(home)];
+}
+const defaultRun = (cmd, args) => {
+    const r = spawnSync(cmd, args, { encoding: "utf8", timeout: 60_000 });
+    return { status: r.status ?? 1, stdout: r.stdout ?? "", stderr: r.error ? r.error.message : (r.stderr ?? "") };
+};
+/** Remove one item through the tool that owns it. Returns null on success, else the reason it is still there. */
+function remove(item, run, platform, uid) {
+    const tool = (cmd, args, what) => {
+        const r = run(cmd, args);
+        return r.status === 0 ? null : `${what} failed: ${(r.stderr || r.stdout).trim().split("\n")[0] || `exit ${r.status}`}`;
+    };
+    try {
+        if (item.kind === "plugin")
+            return tool("claude", ["plugin", "uninstall", item.name], "claude plugin uninstall");
+        if (item.kind === "marketplace")
+            return tool("claude", ["plugin", "marketplace", "remove", item.name], "claude plugin marketplace remove");
+        if (item.kind === "job") {
+            const why = platform === "darwin" ? tool("launchctl", ["bootout", `gui/${uid}/${item.name}`], "launchctl bootout") : tool("systemctl", ["--user", "disable", "--now", item.name], "systemctl --user disable --now");
+            if (why !== null)
+                return why;
+            unlinkSync(item.path);
+            return null;
+        }
+        // a bin or a data folder: a file goes with unlink, a directory (~/.catalyst/bin, the data) with rm -rf
+        if (lstatSync(item.path).isDirectory())
+            rmSync(item.path, { recursive: true, force: true });
+        else
+            unlinkSync(item.path);
+        return null;
+    }
+    catch (err) {
+        return `could not remove: ${err instanceof Error ? err.message : String(err)}`;
+    }
+}
+export async function cmdLegacy(args, ctx, deps = {}) {
+    if (positionals(args).length > 0)
+        throw new UsageError("legacy takes no positional argument; flags are --remove, --data, --yes, --json");
+    const wantRemove = flagBool(args, "remove");
+    const withData = flagBool(args, "data");
+    if (withData && !wantRemove)
+        throw new UsageError("--data belongs with --remove");
+    const platform = deps.platform ?? process.platform;
+    const uid = deps.uid ?? (typeof process.getuid === "function" ? process.getuid() : 0);
+    const run = deps.run ?? defaultRun;
+    const found = findLegacy(ctx.home, platform);
+    const emit = (body, lines) => { if (args.json)
+        ctx.stdout(JSON.stringify(body));
+    else
+        for (const l of lines)
+            ctx.stdout(l); };
+    if (found.length === 0) {
+        emit({ sourceCommit: LEGACY_SOURCE_COMMIT, found: [], removed: [], remaining: [] }, ["no leftovers of the old local Catalyst runtime on this machine"]);
+        return 0;
+    }
+    const listLines = [
+        `Leftovers of the old local Catalyst runtime on this machine (${found.length}):`,
+        ...found.map((f) => `  ${f.kind}: ${f.name}${f.kind === "job" ? ` — ${f.path}` : f.data ? " (kept unless --data)" : ""}`),
+    ];
+    if (!wantRemove) {
+        emit({ sourceCommit: LEGACY_SOURCE_COMMIT, found, removed: [], remaining: found }, [...listLines, RECOMMEND, "Run: catalyst legacy --remove (add --data to delete its data folders too)"]);
+        return 1;
+    }
+    // the one question, only on a terminal; --yes answers it without asking
+    let go = flagBool(args, "yes");
+    if (!go) {
+        const tty = (deps.isTty ?? stdinIsTty)();
+        if (!tty) {
+            emit({ sourceCommit: LEGACY_SOURCE_COMMIT, found, removed: [], remaining: found, asked: false }, [...listLines, RECOMMEND, "nothing removed: no terminal to ask on; run catalyst legacy --remove --yes to remove these without a question (add --data for the data folders)"]);
+            return 1;
+        }
+        for (const l of listLines)
+            ctx.stdout(l);
+        ctx.stdout(RECOMMEND);
+        const answer = (await (deps.prompt ?? ((q) => promptSecret(q)))(`Remove ${found.length} item${found.length === 1 ? "" : "s"}${withData ? ", data folders included" : ", keeping the data folders"}? [y/N] `)).trim().toLowerCase();
+        go = answer === "y" || answer === "yes";
+        if (!go) {
+            emit({ sourceCommit: LEGACY_SOURCE_COMMIT, found, removed: [], remaining: found, asked: true }, ["nothing removed; run catalyst legacy --remove again when ready"]);
+            return 1;
+        }
+    }
+    const removed = [];
+    const failed = [];
+    const kept = [];
+    const lines = [];
+    for (const item of found) {
+        if (item.data && !withData) {
+            kept.push(item);
+            lines.push(`kept: ${item.kind} ${item.name} (run with --data to delete it)`);
+            continue;
+        }
+        const why = remove(item, run, platform, uid);
+        if (why === null) {
+            removed.push(item);
+            lines.push(`removed: ${item.kind} ${item.name}`);
+        }
+        else {
+            failed.push({ item, why });
+            lines.push(`still present: ${item.kind} ${item.name} (${why})`);
+        }
+    }
+    // re-check from the same list, so the report says what the machine holds now, not what was attempted
+    const remaining = findLegacy(ctx.home, platform).filter((f) => !(f.data && !withData));
+    const keptNote = kept.length > 0 ? " except the data folders you kept" : "";
+    lines.push(remaining.length === 0 ? `re-checked: nothing of the old runtime remains${keptNote}` : `re-checked: ${remaining.length} item${remaining.length === 1 ? "" : "s"} of the old runtime remain${remaining.length === 1 ? "s" : ""}${keptNote}: ${remaining.map((r) => `${r.kind} ${r.name}`).join(", ")}`);
+    emit({ sourceCommit: LEGACY_SOURCE_COMMIT, found, removed, remaining: [...remaining, ...kept], kept, failed }, lines);
+    return remaining.length === 0 ? 0 : 1;
+}

package/dist/project.js

@@ -0,0 +1,129 @@
+// project.ts — `catalyst project wip-limit get|set`: a project's new-start WIP limit, on the
+// person's own login. Any active member reads it; a workspace owner or admin sets it. The limit is
+// per Catalyst project (one Linear team across all its repositories): the project's stored value,
+// else the workspace value, else the default the cloud reports. It holds only NEW starts, so the
+// reply carries the work in progress beside the limit: that count, not a runner count, is what a
+// person compares. The route is the cloud's own member route; the reply shape is the cloud's, so a
+// field this CLI does not know is passed through under --json untouched.
+import { flagString, positionals } from "./args.js";
+import { requireConfig } from "./config.js";
+import { loadContract } from "./contract.js";
+import { UsageError } from "./errors.js";
+import { apiClient } from "./transport.js";
+/** The limit's bounds, as the cloud clamps them. A value outside is refused here, before any request. */
+export const WIP_LIMIT_MIN = 0;
+export const WIP_LIMIT_MAX = 9999;
+/** The agent twin of the member route: a bearer reads it with `?team=<key or id>` and writes it with a
+ *  body naming the team, the way the team-workflow verbs do. The contract's route table lists these
+ *  two strings, so `capabilities` can judge them. */
+export const WIP_LIMIT_ROUTE = "/api/v1/agent/team-wip-limit";
+export const wipLimitPath = (team) => `${WIP_LIMIT_ROUTE}?team=${encodeURIComponent(team)}`;
+const SOURCE_TEXT = { project: "set for this project", flag: "workspace value", default: "default" };
+const sourceText = (source) => SOURCE_TEXT[String(source)] ?? String(source ?? "unknown");
+/** The project `--team` names, or the only mapped project when the flag is absent. Never a guess between two. */
+export function resolveTeam(doc, wanted) {
+    const teams = Array.isArray(doc.teams) ? doc.teams : [];
+    if (wanted !== undefined) {
+        const lower = wanted.toLocaleLowerCase();
+        const found = teams.find((t) => (t.key ?? "").toLocaleLowerCase() === lower || t.id === wanted);
+        if (!found)
+            throw new UsageError(`no mapped project has the team key ${wanted}${teams.length ? ` (mapped: ${teams.map((t) => t.key ?? t.id).join(", ")})` : " (no project is mapped yet)"}`);
+        return found;
+    }
+    if (teams.length === 1)
+        return teams[0];
+    if (teams.length === 0)
+        throw new UsageError("no project is mapped yet; map one first (catalyst team map <KEY>)");
+    throw new UsageError(`--team is needed: ${teams.length} projects are mapped (${teams.map((t) => t.key ?? t.id).join(", ")})`);
+}
+/** `set`'s value: an integer inside the cloud's bounds, or the word default. Parsed before any request. */
+export function parseLimit(raw) {
+    if (raw === undefined)
+        throw new UsageError("project wip-limit set needs a value: an integer, or default");
+    if (raw === "default")
+        return null;
+    if (!/^-?\d+$/.test(raw))
+        throw new UsageError(`the limit must be an integer from ${WIP_LIMIT_MIN} to ${WIP_LIMIT_MAX}, or default (got ${raw})`);
+    const n = Number(raw);
+    if (n < WIP_LIMIT_MIN || n > WIP_LIMIT_MAX)
+        throw new UsageError(`the limit must be from ${WIP_LIMIT_MIN} to ${WIP_LIMIT_MAX} (got ${raw}); 0 holds every new start`);
+    return n;
+}
+/** The in-progress tickets as identifiers, tolerant of the cloud sending strings or objects; [] when absent. */
+export function ticketIds(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value
+        .map((t) => (typeof t === "string" ? t : t && typeof t === "object" ? String(t.identifier ?? t.id ?? "") : ""))
+        .filter((t) => t !== "");
+}
+/** One line naming what holds the WIP, capped so a big team does not scroll; null when the cloud sent none. */
+function inProgressLine(view) {
+    const ids = ticketIds(view.inProgressTickets);
+    if (ids.length === 0)
+        return null;
+    const shown = ids.slice(0, 12);
+    return `in progress: ${shown.join(", ")}${ids.length > shown.length ? ` and ${ids.length - shown.length} more` : ""} — these are what a new ticket waits on; unstick them, not the queue`;
+}
+function line(key, view) {
+    const limit = view.limit;
+    const inProgress = view.inProgress;
+    const at = typeof limit === "number" && typeof inProgress === "number" && inProgress >= limit ? " — at the limit: a new ticket waits until one in progress finishes" : "";
+    return `${key}: ${typeof inProgress === "number" ? inProgress : "?"} in progress, limit ${typeof limit === "number" ? limit : "?"} (${sourceText(view.source)})${at}`;
+}
+export async function cmdProject(args, ctx) {
+    const [sub, action, value, ...extra] = positionals(args);
+    if (sub !== "wip-limit")
+        throw new UsageError("project needs wip-limit <get|set <n>|default>");
+    if (action !== "get" && action !== "set")
+        throw new UsageError("project wip-limit needs get, or set <n>|default");
+    if (action === "get" && value !== undefined)
+        throw new UsageError("project wip-limit get takes no value; set does");
+    if (extra.length > 0)
+        throw new UsageError("project wip-limit takes one value at most");
+    const limit = action === "set" ? parseLimit(value) : null;
+    const cfg = requireConfig(ctx);
+    const { doc } = await loadContract(ctx, cfg);
+    const team = resolveTeam(doc, flagString(args, "team"));
+    const key = team.key ?? team.id;
+    const client = apiClient(cfg, ctx);
+    const accept = [400, 403, 404];
+    const emit = (body, lines) => { if (args.json)
+        ctx.stdout(JSON.stringify(body));
+    else
+        for (const l of lines)
+            ctx.stdout(l); };
+    const refuse = (status, reply) => {
+        // The cloud's error bodies carry `error` (the code to match on) and a human `message`.
+        const body = reply ?? {};
+        const detail = body.message || body.reason ? ` (${String(body.message ?? body.reason)})` : "";
+        const why = status === 403
+            ? `setting the limit needs a workspace owner or admin; any member can read it with catalyst project wip-limit get${detail}`
+            : status === 404 && body.error === "team-unknown"
+                ? `this cloud does not know a team ${key}; check the key with catalyst team list${detail}`
+                : status === 404
+                    ? "this Catalyst Cloud does not serve the wip-limit route yet (needs a newer cloud)"
+                    : `${String(body.error ?? body.code ?? "bad request")}${detail}`;
+        emit({ status, team: { id: team.id, key }, ...body }, [`refused (${status}): ${why}`]);
+        return 1;
+    };
+    const before = await client.getJson(wipLimitPath(team.id), { accept, parseAccepted: true });
+    if (before.status !== 200)
+        return refuse(before.status, before.body);
+    if (action === "get") {
+        emit({ team: { id: team.id, key }, ...before.body }, [
+            line(key, before.body),
+            ...(inProgressLine(before.body) === null ? [] : [inProgressLine(before.body)]),
+            `change it: catalyst project wip-limit set <n> --team ${key} (owner or admin; set default returns to the workspace value)`,
+        ]);
+        return 0;
+    }
+    const after = await client.postJson(WIP_LIMIT_ROUTE, { team: team.id, limit }, { accept });
+    if (after.status !== 200)
+        return refuse(after.status, after.body);
+    emit({ team: { id: team.id, key }, ...after.body, previous: { limit: before.body.limit, source: before.body.source } }, [
+        `${key}: limit ${String(before.body.limit)} (${sourceText(before.body.source)}) → ${String(after.body.limit)} (${sourceText(after.body.source)})${after.body.limit === 0 ? "; 0 holds every new start" : ""}`,
+        line(key, after.body),
+    ]);
+    return 0;
+}

package/dist/release.js

@@ -1,4 +1,4 @@
-// release.ts — `catalyst-skills release`: a person's release of a parked or held ticket, or of every
+// release.ts — `catalyst release`: a person's release of a parked or held ticket, or of every
 // ticket on one team parked under one failure class, through the contract's `ticket-release` and
 // `ticket-release-class` routes. The cloud reads every governor holding the ticket and either releases
 // all of them or releases nothing and names, per governor, the human action that does fix it; this verb

package/dist/repo.js

@@ -0,0 +1,297 @@
+// repo.ts — `catalyst repo agents-block` and `catalyst repo agent-setup`: a repository's agent setup,
+// read and changed in a checkout the person names, never through git and never through the cloud.
+//
+//   repo agents-block <path> [--write]        the one Catalyst block in AGENTS.md, marker-delimited,
+//                                             replaced in place on a rerun (never duplicated)
+//   repo agent-setup <path> [--apply] [--with-check]
+//                                             what the repository holds for agents, whether it is
+//                                             portable, the plan that would make it so, and --apply
+//
+// Portable means: AGENTS.md is canonical; CLAUDE.md is a thin file that imports it with a line that
+// is exactly `@AGENTS.md` plus Claude-only notes; `.agents/skills` and `.agents/rules` are canonical
+// and `.claude/skills` and `.claude/rules` are relative symlinks to them. Every write lands in the
+// working tree only: committing, branching and the pull request are the person's, in the open.
+import { existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, renameSync, statSync, symlinkSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { flagBool, positionals } from "./args.js";
+import { UsageError } from "./errors.js";
+export const BLOCK_START = "<!-- catalyst:start -->";
+export const BLOCK_END = "<!-- catalyst:end -->";
+/** The two skills the block names. ONE place each: the packs are being consolidated, and a rename
+ *  lands here, then `repo agents-block --write` brings every repository's block up to date. */
+export const BLOCK_PROCESS_SKILL = "whats-happening";
+export const BLOCK_DECISION_SKILL = "catalyst-sop";
+/** ⭐ THE block, word for word. Harness-agnostic; names the skills, never the process. */
+export const CATALYST_AGENTS_BLOCK = [
+    BLOCK_START,
+    "## Catalyst",
+    "",
+    `This repository is worked through Catalyst: tickets move through a pipeline of agent-run phases, and pull requests merge through its queue. Before you plan, branch, review or merge here, load the skill that explains the process instead of inferring it from this file: \`${BLOCK_PROCESS_SKILL}\` (how a ticket runs, what each phase produces, why work waits), and \`${BLOCK_DECISION_SKILL}\` when it is installed (what to do when work stalls on a decision). Keep this block as it is; onboarding maintains it.`,
+    BLOCK_END,
+].join("\n");
+/** Where the block sits in `text`, or null. Only the FIRST start marker and the first end after it count. */
+function locateBlock(text) {
+    const start = text.indexOf(BLOCK_START);
+    if (start === -1)
+        return null;
+    const endAt = text.indexOf(BLOCK_END, start);
+    if (endAt === -1)
+        return null;
+    return { start, end: endAt + BLOCK_END.length };
+}
+/** The block's state in an AGENTS.md text (`null` text = no file). */
+export function blockState(text) {
+    if (text === null)
+        return "absent";
+    const at = locateBlock(text);
+    if (at === null)
+        return "missing";
+    return text.slice(at.start, at.end) === CATALYST_AGENTS_BLOCK ? "current" : "stale";
+}
+/** The text with the block current: replaced in place, appended after one blank line, or the whole
+ *  file. Pure and idempotent: applying it to its own output changes nothing. */
+export function withBlock(text) {
+    if (text === null || text.trim() === "")
+        return `${CATALYST_AGENTS_BLOCK}\n`;
+    const at = locateBlock(text);
+    if (at !== null)
+        return `${text.slice(0, at.start)}${CATALYST_AGENTS_BLOCK}${text.slice(at.end)}`;
+    const body = text.replace(/\s+$/, "");
+    return `${body}\n\n${CATALYST_AGENTS_BLOCK}\n`;
+}
+function linkState(root, rel, canonicalRel) {
+    const p = join(root, rel);
+    let st;
+    try {
+        st = lstatSync(p);
+    }
+    catch {
+        return { kind: "absent" };
+    }
+    if (st.isSymbolicLink()) {
+        const target = readlinkSync(p);
+        const resolved = resolve(dirname(p), target);
+        return { kind: "symlink", target, resolvesToCanonical: resolved === resolve(root, canonicalRel) && existsSync(resolved) };
+    }
+    return st.isDirectory() ? { kind: "dir" } : { kind: "file" };
+}
+const OTHER_MARKERS = [".codex", ".cursor", ".cursorrules", ".windsurfrules", "GEMINI.md", ".github/copilot-instructions.md"];
+/** Read a checkout's agent setup. Never writes. */
+export function inspectRepo(root) {
+    const agentsPath = join(root, "AGENTS.md");
+    const claudePath = join(root, "CLAUDE.md");
+    const agentsText = existsSync(agentsPath) ? readFileSync(agentsPath, "utf8") : null;
+    const claudeText = existsSync(claudePath) ? readFileSync(claudePath, "utf8") : null;
+    const claudeLines = claudeText === null ? [] : claudeText.split("\n");
+    const importsAgentsMd = claudeLines.some((l) => l.trim() === "@AGENTS.md");
+    const otherLines = claudeLines.filter((l) => l.trim() !== "" && l.trim() !== "@AGENTS.md").length;
+    const report = {
+        path: root,
+        agentsMd: { present: agentsText !== null, lines: agentsText === null ? 0 : agentsText.replace(/\n$/, "").split("\n").length, bytes: agentsText === null ? 0 : Buffer.byteLength(agentsText), block: blockState(agentsText) },
+        claudeMd: { present: claudeText !== null, importsAgentsMd, otherLines },
+        agentsDir: { skills: isDir(join(root, ".agents", "skills")), rules: isDir(join(root, ".agents", "rules")) },
+        claudeDir: { skills: linkState(root, ".claude/skills", ".agents/skills"), rules: linkState(root, ".claude/rules", ".agents/rules") },
+        others: OTHER_MARKERS.filter((m) => existsSync(join(root, m))),
+        verdict: "portable",
+        plan: [],
+        blockers: [],
+    };
+    // CLAUDE.md with guidance of its own and no import: its content belongs in AGENTS.md.
+    if (report.claudeMd.present && !importsAgentsMd) {
+        report.plan.push(report.agentsMd.present
+            ? "append CLAUDE.md's content to AGENTS.md and leave CLAUDE.md as the thin importer (`@AGENTS.md` plus Claude-only notes)"
+            : "create AGENTS.md from CLAUDE.md's content and leave CLAUDE.md as the thin importer (`@AGENTS.md`)");
+    }
+    else if (!report.agentsMd.present && !report.claudeMd.present) {
+        report.plan.push("create AGENTS.md (the Catalyst block starts it; add the repository's own guidance there)");
+    }
+    for (const name of ["skills", "rules"]) {
+        const c = report.claudeDir[name];
+        const canonical = report.agentsDir[name];
+        if (c.kind === "dir" && !canonical)
+            report.plan.push(`move .claude/${name} to .agents/${name} and leave .claude/${name} as a relative symlink to it`);
+        else if (c.kind === "dir" && canonical)
+            report.blockers.push(`.claude/${name} and .agents/${name} are both real directories: merge them by hand, then leave .claude/${name} as a relative symlink`);
+        else if (c.kind === "symlink" && !c.resolvesToCanonical)
+            report.blockers.push(`.claude/${name} is a symlink to ${c.target}, not to .agents/${name}: point it there by hand`);
+        else if (c.kind === "absent" && canonical)
+            report.plan.push(`add .claude/${name} as a relative symlink to .agents/${name}`);
+        else if (c.kind === "file")
+            report.blockers.push(`.claude/${name} is a file, not a directory: look at it by hand`);
+    }
+    if (report.blockers.length > 0)
+        report.verdict = "needs_hand_merge";
+    else if (report.plan.length > 0)
+        report.verdict = "convertible";
+    return report;
+}
+function isDir(p) {
+    try {
+        return statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+const THIN_CLAUDE_MD = "# CLAUDE.md\n\nAll project context for any coding agent is in AGENTS.md, imported below. Only Claude-specific notes belong in this file.\n\n@AGENTS.md\n";
+/** Perform a convertible plan in the working tree. Refuses when anything needs a hand merge. */
+export function applyPlan(root, before) {
+    if (before.verdict === "needs_hand_merge")
+        throw new UsageError(`nothing applied: ${before.blockers.join("; ")}`);
+    const done = [];
+    const agentsPath = join(root, "AGENTS.md");
+    const claudePath = join(root, "CLAUDE.md");
+    if (before.claudeMd.present && !before.claudeMd.importsAgentsMd) {
+        const claudeText = readFileSync(claudePath, "utf8");
+        const existing = existsSync(agentsPath) ? readFileSync(agentsPath, "utf8").replace(/\s+$/, "") : "";
+        const merged = existing === "" ? claudeText.replace(/\s+$/, "") + "\n" : `${existing}\n\n${claudeText.replace(/\s+$/, "")}\n`;
+        writeFileSync(agentsPath, merged);
+        writeFileSync(claudePath, THIN_CLAUDE_MD);
+        done.push(before.agentsMd.present ? "appended CLAUDE.md's content to AGENTS.md; CLAUDE.md now imports it" : "created AGENTS.md from CLAUDE.md; CLAUDE.md now imports it");
+    }
+    else if (!before.agentsMd.present && !before.claudeMd.present) {
+        writeFileSync(agentsPath, withBlock(null));
+        done.push("created AGENTS.md holding the Catalyst block");
+    }
+    for (const name of ["skills", "rules"]) {
+        const c = before.claudeDir[name];
+        const canonicalPath = join(root, ".agents", name);
+        const claudeLink = join(root, ".claude", name);
+        if (c.kind === "dir" && !before.agentsDir[name]) {
+            mkdirSync(join(root, ".agents"), { recursive: true });
+            renameSync(claudeLink, canonicalPath);
+            symlinkSync(relative(dirname(claudeLink), canonicalPath), claudeLink, "dir");
+            done.push(`moved .claude/${name} to .agents/${name} and left a relative symlink`);
+        }
+        else if (c.kind === "absent" && before.agentsDir[name]) {
+            mkdirSync(join(root, ".claude"), { recursive: true });
+            symlinkSync(relative(dirname(claudeLink), canonicalPath), claudeLink, "dir");
+            done.push(`added .claude/${name} as a relative symlink to .agents/${name}`);
+        }
+    }
+    return done;
+}
+/** The lightweight check a customer can run in CI: node only, no dependencies, exit 1 on a finding. */
+export const AGENTS_MD_CHECK_SCRIPT = `#!/usr/bin/env node
+// agents-md-check.mjs — keeps this repository's agent setup portable. Run it in CI:
+//   node scripts/agents-md-check.mjs
+// It fails when CLAUDE.md stops importing AGENTS.md, when .claude/skills or .claude/rules stops being
+// a relative symlink into .agents/, when AGENTS.md outgrows its budget, or when a repository path
+// AGENTS.md cites no longer exists. Budgets: AGENTS_MD_MAX_LINES and AGENTS_MD_MAX_BYTES (env).
+import { existsSync, lstatSync, readFileSync, readlinkSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+
+const root = process.cwd();
+const maxLines = Number(process.env.AGENTS_MD_MAX_LINES ?? 120);
+const maxBytes = Number(process.env.AGENTS_MD_MAX_BYTES ?? 16 * 1024);
+const findings = [];
+const agents = existsSync("AGENTS.md") ? readFileSync("AGENTS.md", "utf8") : null;
+if (agents === null) findings.push("AGENTS.md is missing");
+else {
+  const lines = agents.replace(/\\n$/, "").split("\\n");
+  if (lines.length > maxLines) findings.push(\`AGENTS.md is \${lines.length} lines (budget \${maxLines})\`);
+  if (Buffer.byteLength(agents) > maxBytes) findings.push(\`AGENTS.md is \${Buffer.byteLength(agents)} bytes (budget \${maxBytes})\`);
+  for (const m of agents.matchAll(/\`([\\w.-]+(?:\\/[\\w.-]+)+)\`/g)) {
+    const p = m[1];
+    if (!existsSync(resolve(root, p))) findings.push(\`AGENTS.md cites \${p}, which does not exist\`);
+  }
+}
+if (existsSync("CLAUDE.md")) {
+  const n = readFileSync("CLAUDE.md", "utf8").split("\\n").filter((l) => l.trim() === "@AGENTS.md").length;
+  if (n !== 1) findings.push(\`CLAUDE.md must import AGENTS.md on exactly one line reading @AGENTS.md (found \${n})\`);
+}
+for (const name of ["skills", "rules"]) {
+  const link = \`.claude/\${name}\`;
+  const canonical = \`.agents/\${name}\`;
+  if (!existsSync(canonical) && !existsSync(link)) continue;
+  let st;
+  try { st = lstatSync(link); } catch { findings.push(\`\${link} is missing; make it a relative symlink to \${canonical}\`); continue; }
+  if (!st.isSymbolicLink()) { findings.push(\`\${link} is a real \${st.isDirectory() ? "directory" : "file"}; make \${canonical} canonical and \${link} a relative symlink\`); continue; }
+  const target = readlinkSync(link);
+  if (target.startsWith("/")) findings.push(\`\${link} is an absolute symlink (\${target}); make it relative\`);
+  if (resolve(dirname(link), target) !== resolve(root, canonical)) findings.push(\`\${link} points at \${target}, not \${canonical}\`);
+}
+for (const f of findings) console.error(\`agents-md-check: \${f}\`);
+if (findings.length > 0) process.exit(1);
+console.log("agents-md-check: portable");
+`;
+const describeLink = (s) => (s.kind === "symlink" ? `symlink → ${s.target}${s.resolvesToCanonical ? "" : " (not the canonical directory)"}` : s.kind === "dir" ? "real directory" : s.kind === "file" ? "a file" : "absent");
+export function reportLines(r) {
+    const lines = [
+        `repository: ${r.path}`,
+        `AGENTS.md: ${r.agentsMd.present ? `${r.agentsMd.lines} lines, ${r.agentsMd.bytes} bytes; Catalyst block ${r.agentsMd.block}` : "absent"}`,
+        `CLAUDE.md: ${r.claudeMd.present ? (r.claudeMd.importsAgentsMd ? `imports AGENTS.md${r.claudeMd.otherLines ? ` plus ${r.claudeMd.otherLines} lines of Claude-only notes` : ""}` : `${r.claudeMd.otherLines} lines of its own guidance, no @AGENTS.md import`) : "absent"}`,
+        `.agents/skills: ${r.agentsDir.skills ? "present" : "absent"}; .claude/skills: ${describeLink(r.claudeDir.skills)}`,
+        `.agents/rules: ${r.agentsDir.rules ? "present" : "absent"}; .claude/rules: ${describeLink(r.claudeDir.rules)}`,
+    ];
+    if (r.others.length > 0)
+        lines.push(`also present: ${r.others.join(", ")}`);
+    lines.push(`verdict: ${r.verdict === "portable" ? "portable (AGENTS.md canonical, Claude files import or link to it)" : r.verdict === "convertible" ? "convertible; --apply performs this plan in the working tree:" : "needs a hand merge before --apply:"}`);
+    for (const p of r.plan)
+        lines.push(`  - ${p}`);
+    for (const b of r.blockers)
+        lines.push(`  ⛔ ${b}`);
+    if (r.agentsMd.block !== "current")
+        lines.push(`  - the Catalyst block is ${r.agentsMd.block}: catalyst repo agents-block ${r.path} --write`);
+    return lines;
+}
+function checkoutRoot(args, sub) {
+    const [, path, ...extra] = positionals(args);
+    if (!path)
+        throw new UsageError(`repo ${sub} needs the checkout's path`);
+    if (extra.length > 0)
+        throw new UsageError(`repo ${sub} takes one path`);
+    const root = resolve(path);
+    if (!isDir(root))
+        throw new UsageError(`${path} is not a directory on this machine`);
+    return root;
+}
+export async function cmdRepo(args, ctx) {
+    const [sub] = positionals(args);
+    if (sub !== "agents-block" && sub !== "agent-setup")
+        throw new UsageError("repo needs agents-block <path> [--write] or agent-setup <path> [--apply] [--with-check]");
+    const root = checkoutRoot(args, sub);
+    const emit = (body, lines) => { if (args.json)
+        ctx.stdout(JSON.stringify(body));
+    else
+        for (const l of lines)
+            ctx.stdout(l); };
+    if (sub === "agents-block") {
+        if (flagBool(args, "apply") || flagBool(args, "with-check"))
+            throw new UsageError("--apply and --with-check belong to repo agent-setup");
+        const file = join(root, "AGENTS.md");
+        const before = existsSync(file) ? readFileSync(file, "utf8") : null;
+        const state = blockState(before);
+        if (!flagBool(args, "write")) {
+            const hint = state === "current" ? "nothing to do" : `run with --write to ${state === "absent" ? "create AGENTS.md with it" : state === "missing" ? "append it" : "bring it up to date"} (in the working tree; commit it on a branch and open a pull request)`;
+            emit({ path: root, agentsMd: before !== null, block: state, changed: false }, [`AGENTS.md: Catalyst block ${state} — ${hint}`]);
+            return state === "current" ? 0 : 1;
+        }
+        const after = withBlock(before);
+        const changed = after !== before;
+        if (changed)
+            writeFileSync(file, after);
+        emit({ path: root, agentsMd: true, block: "current", changed, was: state }, [
+            changed ? `AGENTS.md: Catalyst block ${state === "absent" ? "written to a new AGENTS.md" : state === "missing" ? "appended" : "updated in place"}; commit it on a branch and open a pull request` : "AGENTS.md: Catalyst block already current; nothing changed",
+        ]);
+        return 0;
+    }
+    if (flagBool(args, "write"))
+        throw new UsageError("--write belongs to repo agents-block");
+    const before = inspectRepo(root);
+    const applied = [];
+    if (flagBool(args, "apply"))
+        applied.push(...applyPlan(root, before));
+    if (flagBool(args, "with-check")) {
+        const dir = join(root, "scripts");
+        mkdirSync(dir, { recursive: true });
+        const target = join(dir, "agents-md-check.mjs");
+        const same = existsSync(target) && readFileSync(target, "utf8") === AGENTS_MD_CHECK_SCRIPT;
+        if (!same)
+            writeFileSync(target, AGENTS_MD_CHECK_SCRIPT, { mode: 0o755 });
+        applied.push(same ? "scripts/agents-md-check.mjs already current" : "wrote scripts/agents-md-check.mjs (run it in CI: node scripts/agents-md-check.mjs)");
+    }
+    const after = applied.length > 0 ? inspectRepo(root) : before;
+    emit({ ...after, applied }, [...(applied.length ? ["applied:", ...applied.map((a) => `  - ${a}`)] : []), ...reportLines(after)]);
+    return after.verdict === "portable" && after.agentsMd.block === "current" ? 0 : 1;
+}