@catalyst-cloud/cli 0.14.6 → 0.14.7

package/skills/catalyst-github/scripts/is-it-mergeable.mjs

@@ -2,18 +2,19 @@
 // is-it-mergeable.mjs — the three legs of merge evidence for one PR (checks, reviewer signal,
 // unresolved threads) judged under the policy the tenant contract resolves for its repository, plus
 // the prerequisites a queue applies before any leg counts (open, not a draft, no conflict). Every
-// input comes from `catalyst query`, `contract` and, when fresh, `replica sql`.
+// input comes from cloud-backed `catalyst query` and `contract`; --local-threads opts into `replica sql`.
 // Exit 0 no leg is red, 1 a leg or prerequisite is red, 2 this machine is not connected.
 import { parseJson, runCli, runCliOrExit } from "./lib/cli.mjs";
 import { resolvePull, truthy } from "./lib/pull.mjs";
 
-const HELP = `Usage: node scripts/is-it-mergeable.mjs <ticket | pr-node-id> [--json]
+const HELP = `Usage: node scripts/is-it-mergeable.mjs <ticket | pr-node-id> [--json] [--local-threads]
 
 Judges one pull request against the merge policy the tenant contract resolves for its repository:
   checks     every gating check at the head completed without failing (pending or absent is not green)
   reviewer   the reviewer signal the policy requires; the clean-pass reaction itself is not mirrored,
              so this leg is reported as inconclusive rather than guessed, unless the policy waives it
-  threads    zero unresolved review threads, read from the local replica when it is fresh
+  threads    inconclusive when the cloud PR detail carries no thread count;
+             --local-threads opts into reading a local replica caught up to a probed cloud head
 
 A red prerequisite (closed, draft, merge conflict) is also exit 1. Inconclusive legs never fail the
 exit code; the cloud's own evaluator, which holds the reaction and the thread ancestry, is authoritative.
@@ -32,14 +33,20 @@ if (!target) {
 }
 
 const { ticket, detail } = resolvePull(target);
-const merge = parseJson(runCliOrExit(["contract", "--path", "merge", "--json"]).stdout);
+const merge = parseJson(
+  runCliOrExit(["contract", "--path", "merge", "--json"]).stdout,
+);
 if (!merge || !Array.isArray(merge.policies)) {
-  console.error("the contract's merge block did not parse; run: catalyst contract --refresh");
+  console.error(
+    "the contract's merge block did not parse; run: catalyst contract --refresh",
+  );
   process.exit(1);
 }
 
-const repoId = String(detail.repo_id ?? "");
-const repoRow = (merge.repositories ?? []).find((r) => `${r.owner}/${r.name}`.toLowerCase() === repoId.toLowerCase());
+const repoId = typeof detail.repo_id === "string" ? detail.repo_id : "";
+const repoRow = (merge.repositories ?? []).find(
+  (r) => `${r.owner}/${r.name}`.toLowerCase() === repoId.toLowerCase(),
+);
 const policy = repoRow?.policy ?? merge.defaultPolicy;
 const policySource = repoRow ? repoRow.policySource : "default";
 const requiresReviewer = policy !== "checks-and-threads";
@@ -50,75 +57,233 @@ const add = (leg, state, line) => legs.push({ leg, state, line });
 
 // ── prerequisites the queue applies before any leg counts ──────────────────────────────────────
 if (truthy(detail.merged)) {
-  add("state", "pass", `already merged${detail.merged_at ? ` at ${new Date(Number(detail.merged_at)).toISOString()}` : ""}; nothing left to judge`);
+  add(
+    "state",
+    "pass",
+    `already merged${detail.merged_at ? ` at ${new Date(Number(detail.merged_at)).toISOString()}` : ""}; nothing left to judge`,
+  );
 } else {
   const state = String(detail.state ?? "").toLowerCase();
-  if (state && state !== "open") add("state", "fail", `the PR is ${state}, not open`);
-  else if (truthy(detail.draft)) add("state", "fail", "the PR is still a draft; the pr phase marks it ready for review, a queue never takes a draft");
+  if (state && state !== "open")
+    add("state", "fail", `the PR is ${state}, not open`);
+  else if (truthy(detail.draft))
+    add(
+      "state",
+      "fail",
+      "the PR is still a draft; the pr phase marks it ready for review, a queue never takes a draft",
+    );
   else add("state", "pass", "open and ready for review");
   const ms = String(detail.mergeable_state ?? "").toLowerCase();
-  if (ms === "dirty" || detail.mergeable === false || detail.mergeable === 0) add("conflict", "fail", `GitHub reports a merge conflict with the base branch (mergeable_state=${ms || "unknown"}); a remediate round rebases it`);
+  if (ms === "dirty" || detail.mergeable === false || detail.mergeable === 0)
+    add(
+      "conflict",
+      "fail",
+      `GitHub reports a merge conflict with the base branch (mergeable_state=${ms || "unknown"}); a remediate round rebases it`,
+    );
   else if (ms) add("conflict", "pass", `GitHub reports mergeable_state=${ms}`);
-  else add("conflict", "inconclusive", "GitHub has not reported a mergeable state for this head yet");
+  else
+    add(
+      "conflict",
+      "inconclusive",
+      "GitHub has not reported a mergeable state for this head yet",
+    );
 }
 
 // ── leg 1: checks ───────────────────────────────────────────────────────────────────────────────
 const checks = Array.isArray(detail.checks) ? detail.checks : [];
-const required = Array.isArray(merge.cloudRemediateRequiredChecks) ? merge.cloudRemediateRequiredChecks : [];
-const notQueue = checks.filter((c) => !/mergify|^queue:|^summary$/i.test(String(c.name ?? "")));
+const required = Array.isArray(merge.cloudRemediateRequiredChecks)
+  ? merge.cloudRemediateRequiredChecks
+  : [];
+const notQueue = checks.filter(
+  (c) => !/mergify|^queue:|^summary$/i.test(String(c.name ?? "")),
+);
 const gating = notQueue.filter((c) => required.includes(String(c.name)));
 const judged = gating.length > 0 ? gating : notQueue;
 const ok = new Set(["success", "neutral", "skipped"]);
-const red = judged.filter((c) => String(c.status).toLowerCase() === "completed" && !ok.has(String(c.conclusion).toLowerCase()));
-const pending = judged.filter((c) => String(c.status).toLowerCase() !== "completed");
-const statuses = Array.isArray(detail.commit_statuses) ? detail.commit_statuses : [];
-const redStatuses = statuses.filter((s) => ["failure", "error"].includes(String(s.state).toLowerCase()));
-const scope = gating.length > 0 ? `the ${gating.length} required check(s) the contract names` : `every mirrored check (none of the contract's required names is present at this head)`;
-if (judged.length === 0 && redStatuses.length === 0) add("checks", "inconclusive", "no check has reported at this head; an unrun set is unknown, never green");
-else if (red.length > 0 || redStatuses.length > 0) add("checks", "fail", `red: ${[...red.map((c) => `${c.name} (${c.conclusion})`), ...redStatuses.map((s) => `${s.context} (${s.state})`)].join(", ")}`);
-else if (pending.length > 0) add("checks", "inconclusive", `still running: ${pending.map((c) => c.name).join(", ")} — judged over ${scope}`);
+const red = judged.filter(
+  (c) =>
+    String(c.status).toLowerCase() === "completed" &&
+    !ok.has(String(c.conclusion).toLowerCase()),
+);
+const pending = judged.filter(
+  (c) => String(c.status).toLowerCase() !== "completed",
+);
+const statuses = Array.isArray(detail.commit_statuses)
+  ? detail.commit_statuses
+  : [];
+const redStatuses = statuses.filter((s) =>
+  ["failure", "error"].includes(String(s.state).toLowerCase()),
+);
+const scope =
+  gating.length > 0
+    ? `the ${gating.length} required check(s) the contract names`
+    : `every mirrored check (none of the contract's required names is present at this head)`;
+if (judged.length === 0 && redStatuses.length === 0)
+  add(
+    "checks",
+    "inconclusive",
+    "no check has reported at this head; an unrun set is unknown, never green",
+  );
+else if (red.length > 0 || redStatuses.length > 0)
+  add(
+    "checks",
+    "fail",
+    `red: ${[...red.map((c) => `${c.name} (${c.conclusion})`), ...redStatuses.map((s) => `${s.context} (${s.state})`)].join(", ")}`,
+  );
+else if (pending.length > 0)
+  add(
+    "checks",
+    "inconclusive",
+    `still running: ${pending.map((c) => c.name).join(", ")} — judged over ${scope}`,
+  );
 else add("checks", "pass", `green over ${scope}`);
 
 // ── leg 2: the reviewer signal ─────────────────────────────────────────────────────────────────
 const reviews = Array.isArray(detail.reviews) ? detail.reviews : [];
 const login = String(merge.reviewerLogin ?? "");
-const byReviewer = reviews.filter((r) => String(r.reviewer_name ?? "") === login || String(r.reviewer_id ?? "") === `github:${login}`);
-if (!requiresReviewer) add("reviewer", "pass", `policy ${policy} needs no reviewer signal`);
+const byReviewer = reviews.filter(
+  (r) =>
+    String(r.reviewer_name ?? "") === login ||
+    String(r.reviewer_id ?? "") === `github:${login}`,
+);
+if (!requiresReviewer)
+  add("reviewer", "pass", `policy ${policy} needs no reviewer signal`);
 else if (byReviewer.length > 0) {
-  const states = [...new Set(byReviewer.map((r) => String(r.state ?? "?")))].join(", ");
-  add("reviewer", "inconclusive", `${login} left ${byReviewer.length} review object(s) (${states}); whether they stand at the current head or an earlier one, and whether a clean-pass reaction followed, is not mirrored${acceptsEarlierHead ? " — under this policy, findings on an earlier head plus green checks and zero unresolved threads are accepted" : " — this policy requires a clean pass at the current head"}`);
-} else add("reviewer", "inconclusive", `no review object from ${login} is mirrored; a clean pass is a reaction, which this read cannot see`);
+  const states = [
+    ...new Set(byReviewer.map((r) => String(r.state ?? "?"))),
+  ].join(", ");
+  add(
+    "reviewer",
+    "inconclusive",
+    `${login} left ${byReviewer.length} review object(s) (${states}); whether they stand at the current head or an earlier one, and whether a clean-pass reaction followed, is not mirrored${acceptsEarlierHead ? " — under this policy, findings on an earlier head plus green checks and zero unresolved threads are accepted" : " — this policy requires a clean pass at the current head"}`,
+  );
+} else
+  add(
+    "reviewer",
+    "inconclusive",
+    `no review object from ${login} is mirrored; a clean pass is a reaction, which this read cannot see`,
+  );
 
-// ── leg 3: unresolved threads, from the replica when it is fresh ───────────────────────────────
-const replica = parseJson(runCli(["replica", "status", "--json"]).stdout);
-if (replica && replica.verdict === "fresh") {
-  const num = Number(detail.number);
-  const esc = repoId.replace(/'/g, "''");
-  const sql = `select resolved, count(*) as n from pr_review_threads where repo_id = '${esc}' and pr_number = ${Number.isInteger(num) ? num : -1} group by resolved`;
-  const rows = parseJson(runCli(["replica", "sql", sql, "--json"]).stdout) ?? [];
-  const count = (want) => rows.filter((r) => (want === null ? r.resolved === null || r.resolved === undefined : Number(r.resolved) === want)).reduce((a, r) => a + Number(r.n ?? 0), 0);
-  const unresolved = count(0);
-  const unknown = count(null);
-  if (unresolved > 0) add("threads", "fail", `${unresolved} unresolved review thread(s)`);
-  else if (unknown > 0) add("threads", "inconclusive", `${unknown} thread(s) with no resolved flag mirrored`);
-  else add("threads", "pass", `${count(1)} thread(s), all resolved (ancestry against force-pushes is judged by the cloud, not here)`);
+// The default cloud read requires no local writer or database. Thread ancestry remains the
+// cloud evaluator's responsibility; absence of thread evidence never becomes a green leg.
+const localThreads = args.includes("--local-threads");
+const replicaResult = localThreads
+  ? runCli(["replica", "status", "--probe", "--json"])
+  : null;
+const replica =
+  replicaResult?.code === 0 ? parseJson(replicaResult.stdout) : null;
+if (
+  localThreads &&
+  replica?.verdict === "fresh" &&
+  Number.isSafeInteger(replica.cursor) &&
+  replica.cursor >= 0 &&
+  replica.cursor === replica.head
+) {
+  const num = detail.number;
+  if (
+    typeof num !== "number" ||
+    !Number.isSafeInteger(num) ||
+    num <= 0 ||
+    !repoId ||
+    repoId !== repoId.trim() ||
+    repoId.length > 512 ||
+    /[\u0000-\u001f\u007f-\u009f]/.test(repoId)
+  ) {
+    add(
+      "threads",
+      "inconclusive",
+      "the PR identity is incomplete; local thread evidence could not be read",
+    );
+  } else {
+    const esc = repoId.replace(/'/g, "''");
+    const sql = `select resolved, count(*) as n from pr_review_threads where repo_id = '${esc}' and pr_number = ${num} group by resolved`;
+    const result = runCli(["replica", "sql", sql, "--json"]);
+    const rows = parseJson(result.stdout);
+    if (
+      result.code !== 0 ||
+      !Array.isArray(rows) ||
+      rows.some(
+        (row) =>
+          !row ||
+          ![0, 1, null].includes(row.resolved) ||
+          typeof row.n !== "number" ||
+          !Number.isSafeInteger(row.n) ||
+          row.n < 0,
+      )
+    ) {
+      add(
+        "threads",
+        "inconclusive",
+        "the optional local thread read could not be verified; the cloud evaluator decides",
+      );
+    } else {
+      const count = (want) =>
+        rows
+          .filter((r) =>
+            want === null
+              ? r.resolved === null || r.resolved === undefined
+              : r.resolved === want,
+          )
+          .reduce((a, r) => a + Number(r.n ?? 0), 0);
+      const unresolved = count(0);
+      const unknown = count(null);
+      if (unresolved > 0)
+        add("threads", "fail", `${unresolved} unresolved review thread(s)`);
+      else if (unknown > 0)
+        add(
+          "threads",
+          "inconclusive",
+          `${unknown} thread(s) with no resolved flag mirrored`,
+        );
+      else
+        add(
+          "threads",
+          "pass",
+          `${count(1)} thread(s), all resolved (ancestry against force-pushes is judged by the cloud, not here)`,
+        );
+    }
+  }
 } else {
-  add("threads", "inconclusive", `the PR detail carries no thread count and the replica is ${replica?.verdict ?? "unavailable"}; start it (catalyst replica start --detach) for a local read`);
+  add(
+    "threads",
+    "inconclusive",
+    localThreads
+      ? "the optional local replica has not proven that it is caught up to the cloud head; the cloud evaluator decides"
+      : "the cloud PR detail carries no thread count; the cloud evaluator decides",
+  );
 }
 
 const failed = legs.filter((l) => l.state === "fail");
 const open = legs.filter((l) => l.state === "inconclusive");
 let verdict;
-if (failed.length > 0) verdict = `NOT MERGEABLE: ${failed.map((l) => l.leg).join(", ")}`;
-else if (open.length > 0) verdict = `NOT PROVEN MERGEABLE from this read (${open.map((l) => l.leg).join(", ")} inconclusive); the cloud's evaluator decides`;
+if (failed.length > 0)
+  verdict = `NOT MERGEABLE: ${failed.map((l) => l.leg).join(", ")}`;
+else if (open.length > 0)
+  verdict = `NOT PROVEN MERGEABLE from this read (${open.map((l) => l.leg).join(", ")} inconclusive); the cloud's evaluator decides`;
 else verdict = "MERGEABLE as far as this read can see";
 
 const header = `${repoId}#${detail.number ?? "?"}${ticket ? ` (${ticket})` : ""} head ${String(detail.head_sha ?? "").slice(0, 12)} — policy ${policy} (${policySource})`;
 if (json) {
-  console.log(JSON.stringify({ pr: { repo_id: repoId, number: detail.number, node_id: detail.node_id, ticket, head_sha: detail.head_sha }, policy: { name: policy, source: policySource }, legs, verdict }));
+  console.log(
+    JSON.stringify({
+      pr: {
+        repo_id: repoId,
+        number: detail.number,
+        node_id: detail.node_id,
+        ticket,
+        head_sha: detail.head_sha,
+      },
+      policy: { name: policy, source: policySource },
+      legs,
+      verdict,
+    }),
+  );
 } else {
   console.log(header);
-  for (const l of legs) console.log(`${l.state === "pass" ? "ok  " : l.state === "fail" ? "FAIL" : "?   "}  ${l.leg}: ${l.line}`);
+  for (const l of legs)
+    console.log(
+      `${l.state === "pass" ? "ok  " : l.state === "fail" ? "FAIL" : "?   "}  ${l.leg}: ${l.line}`,
+    );
   console.log(verdict);
 }
 process.exit(failed.length > 0 ? 1 : 0);

package/skills/catalyst-github/scripts/read-pr.mjs

@@ -12,7 +12,7 @@ const HELP = `Usage: node scripts/read-pr.mjs <ticket | pr-node-id> [--all] [--j
   --json         print the raw detail document instead of the summary
 
 Exit 0 shown, 1 not found or no PR yet, 2 this machine is not connected to a tenant.
-The first stderr line names the source the CLI read from (a fresh replica, or the API).`;
+The first stderr line names the source the CLI read from (the API by default, or an explicitly selected replica).`;
 
 const args = process.argv.slice(2);
 if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
@@ -52,8 +52,15 @@ if (all) {
     process.exit(1);
   }
   for (const p of pulls) {
-    const flags = [truthy(p.draft) ? "draft" : null, truthy(p.merged) ? "merged" : null].filter(Boolean).join(" ");
-    console.log(`${fmt(p.repo_id)}#${fmt(p.number)}  ${fmt(p.state)}${flags ? ` ${flags}` : ""}  ${fmt(p.title, "")}  [${fmt(p.node_id, "")}]`);
+    const flags = [
+      truthy(p.draft) ? "draft" : null,
+      truthy(p.merged) ? "merged" : null,
+    ]
+      .filter(Boolean)
+      .join(" ");
+    console.log(
+      `${fmt(p.repo_id)}#${fmt(p.number)}  ${fmt(p.state)}${flags ? ` ${flags}` : ""}  ${fmt(p.title, "")}  [${fmt(p.node_id, "")}]`,
+    );
   }
   process.exit(0);
 }
@@ -66,23 +73,44 @@ if (json) {
 
 const checks = Array.isArray(detail.checks) ? detail.checks : [];
 const reviews = Array.isArray(detail.reviews) ? detail.reviews : [];
-const statuses = Array.isArray(detail.commit_statuses) ? detail.commit_statuses : [];
-const state = [fmt(detail.state), truthy(detail.draft) ? "draft" : null, truthy(detail.merged) ? `merged ${when(detail.merged_at)}` : null].filter(Boolean).join(", ");
+const statuses = Array.isArray(detail.commit_statuses)
+  ? detail.commit_statuses
+  : [];
+const state = [
+  fmt(detail.state),
+  truthy(detail.draft) ? "draft" : null,
+  truthy(detail.merged) ? `merged ${when(detail.merged_at)}` : null,
+]
+  .filter(Boolean)
+  .join(", ");
 
-console.log(`${fmt(detail.repo_id)}#${fmt(detail.number)}  ${fmt(detail.title, "(no title yet)")}`);
-console.log(`state: ${state}  by ${fmt(detail.author_login)}  opened ${when(detail.created_at)}  updated ${when(detail.updated_at)}`);
-console.log(`branch: ${fmt(detail.head_ref)} → ${fmt(detail.base_ref)}  head ${fmt(detail.head_sha).slice(0, 12)}`);
-console.log(`ticket: ${fmt(ticket ?? detail.linear_issue_identifier, "none named")}${detail.linked_issue_state ? ` (stage: ${detail.linked_issue_state})` : ""}`);
-console.log(`github says: mergeable=${fmt(detail.mergeable, "unknown")} state=${fmt(detail.mergeable_state, "unknown")} auto-merge=${truthy(detail.auto_merge) ? "on" : "off"}`);
+console.log(
+  `${fmt(detail.repo_id)}#${fmt(detail.number)}  ${fmt(detail.title, "(no title yet)")}`,
+);
+console.log(
+  `state: ${state}  by ${fmt(detail.author_login)}  opened ${when(detail.created_at)}  updated ${when(detail.updated_at)}`,
+);
+console.log(
+  `branch: ${fmt(detail.head_ref)} → ${fmt(detail.base_ref)}  head ${fmt(detail.head_sha).slice(0, 12)}`,
+);
+console.log(
+  `ticket: ${fmt(ticket ?? detail.linear_issue_identifier, "none named")}${detail.linked_issue_state ? ` (stage: ${detail.linked_issue_state})` : ""}`,
+);
+console.log(
+  `github says: mergeable=${fmt(detail.mergeable, "unknown")} state=${fmt(detail.mergeable_state, "unknown")} auto-merge=${truthy(detail.auto_merge) ? "on" : "off"}`,
+);
 if (detail.blocked_on_ask && typeof detail.blocked_on_ask === "object") {
   const b = detail.blocked_on_ask;
-  console.log(`blocked on an ask: ${fmt(b.identifier ?? b.id, "")} ${fmt(b.title, "")}`.trim());
+  console.log(
+    `blocked on an ask: ${fmt(b.identifier ?? b.id, "")} ${fmt(b.title, "")}`.trim(),
+  );
 }
 console.log(`node id: ${fmt(detail.node_id)}`);
 
 console.log(`checks (${checks.length}):`);
 if (checks.length === 0) console.log("  none reported at this head yet");
-for (const c of checks) console.log(`  ${fmt(c.status)}/${fmt(c.conclusion, "-")}  ${fmt(c.name)}`);
+for (const c of checks)
+  console.log(`  ${fmt(c.status)}/${fmt(c.conclusion, "-")}  ${fmt(c.name)}`);
 
 if (statuses.length > 0) {
   console.log(`commit statuses (${statuses.length}):`);
@@ -90,8 +118,16 @@ if (statuses.length > 0) {
 }
 
 console.log(`reviews (${reviews.length}):`);
-if (reviews.length === 0) console.log("  none mirrored; a reviewer's clean pass is a reaction, which this read does not carry");
-for (const r of reviews) console.log(`  ${fmt(r.state)}  ${fmt(r.reviewer_name, fmt(r.reviewer_id))}  ${when(r.submitted_at)}`);
+if (reviews.length === 0)
+  console.log(
+    "  none mirrored; a reviewer's clean pass is a reaction, which this read does not carry",
+  );
+for (const r of reviews)
+  console.log(
+    `  ${fmt(r.state)}  ${fmt(r.reviewer_name, fmt(r.reviewer_id))}  ${when(r.submitted_at)}`,
+  );
 
-console.log("not mirrored here: PR labels (holds, queue attestation) and the reviewer's reaction — see references/what-a-pr-accumulates.md");
+console.log(
+  "not mirrored here: PR labels (holds, queue attestation) and the reviewer's reaction — see references/what-a-pr-accumulates.md",
+);
 process.exit(0);

package/skills/catalyst-linear/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: catalyst-linear
 description: >-
-  Catalyst's view of Linear on the customer's own cloud account. Reads a ticket with its comments, relations, labels, linked pull requests and agent sessions inline, from the local replica when it is fresh and the origin-fresh API otherwise, always naming the source; searches tickets, PRs, projects and initiatives; writes comments, card moves, labels and new tickets through the account's agent proxy as the app actor, with every route, stage id, label id and marker read from the account's contract. Knows what a ticket accumulates as Catalyst works it (phase-outcome comments, the document per phase, the agent session, the labels, the single blocks relation, the bookkeeping marker, the eyes acknowledgement). Use when a person says "show me the ticket", "what did Catalyst write on it", "comment on it", "move it", "label it" or "file a ticket". Not for raising a decision for a human (what-needs-me) and not for pull requests (catalyst-github).
+  Catalyst's view of Linear on the customer's own cloud account. Reads a ticket with its comments, relations, labels, linked pull requests and agent sessions inline, from the cloud API by default, with local replica reads available as an explicit opt-in, always naming the source; searches tickets, PRs, projects and initiatives; writes comments, card moves, labels and new tickets through the account's agent proxy as the app actor, with every route, stage id, label id and marker read from the account's contract. Knows what a ticket accumulates as Catalyst works it (phase-outcome comments, the document per phase, the agent session, the labels, the single blocks relation, the bookkeeping marker, the eyes acknowledgement). Use when a person says "show me the ticket", "what did Catalyst write on it", "comment on it", "move it", "label it" or "file a ticket". Not for raising a decision for a human (what-needs-me) and not for pull requests (catalyst-github).
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.14.6 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.14.7 — written in this repository for customer accounts -->
 
 # Catalyst Linear
 
-You read tickets and write to them in the person's cloud account, as Catalyst. Reads come from the replica when it is fresh, else the API, and name their source. Writes go out as the app actor, with routes, stage ids, label ids and the bookkeeping marker resolved from the contract by the `catalyst` CLI.
+You read tickets and write to them in the person's cloud account, as Catalyst. Reads come from the cloud API by default and name their source. A person may explicitly choose a local replica read; setup does not require a replica. Writes go out as the app actor, with routes, stage ids, label ids and the bookkeeping marker resolved from the contract by the `catalyst` CLI.
 
 ## Run first
 

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

@@ -4,13 +4,13 @@
 
 Every `query` verb, and therefore `node scripts/read-ticket.mjs` and `node scripts/search.mjs`, prints one stderr line before the answer:
 
-- `source: replica (cursor N)`: the local replica was fresh, so the answer is local and cheap.
-- `source: api (replica stale|absent|not configured)`: the answer came from the origin-fresh cloud API; a stale replica always falls back.
+- `source: replica (--source replica)`: the person explicitly selected the optional local replica.
+- `source: api (cloud reads by default)`: the answer came from the cloud API; no local replica is needed.
 - `source: api (<verb> is api-only)`: search, cycles, pull detail and change feeds never come from the replica.
 
 Quote the source when a fact's freshness matters ("as of the replica at cursor N", "from the API just now").
 
-`--source replica` or `--source api` forces one. Forcing the replica when it is absent or stale is refused.
+`--source replica` or `--source api` forces one. Forcing the replica when it is absent is refused. No offline-browsing promise is made.
 
 ## Then the row
 

package/skills/catalyst-linear/scripts/read-ticket.mjs

@@ -1,8 +1,15 @@
 #!/usr/bin/env node
 // read-ticket.mjs — one ticket with its comments, relations, labels, linked pull requests and agent
-// sessions inline, from the replica when it is fresh, else the origin-fresh API. The source line the
+// sessions inline, from the cloud API by default, or an explicitly chosen local replica. The source line the
 // CLI prints on stderr is the freshness verdict; it is always shown.
-import { parseFlags, parseJson, relayStderr, runCli, usage, wantsHelp } from "./lib/cli.mjs";
+import {
+  parseFlags,
+  parseJson,
+  relayStderr,
+  runCli,
+  usage,
+  wantsHelp,
+} from "./lib/cli.mjs";
 
 const HELP = `Usage: node scripts/read-ticket.mjs <ticket> [--comments] [--source replica|api] [--json]
 
@@ -10,11 +17,10 @@ Reads one ticket record. Wraps: catalyst query issue.
 
   <ticket>               the Linear identifier, e.g. KEY-123
   --comments             also print every comment (id, author, time, body)
-  --source replica|api   force one source; default is the replica when fresh, else the API
+  --source replica|api   choose one source; default is the cloud API
   --json                 print the full record as JSON
 
-The first stderr line names the source ("source: replica (cursor N)" or "source: api (replica
-stale|absent|not configured)"); quote it when the freshness of the answer matters.
+The first stderr line names the source ("source: api (cloud reads by default)" or "source: replica (--source replica)"); quote it when the freshness of the answer matters.
 
 Exit 0 found, 1 not found or a usage error, 2 when this machine is not connected to a tenant or the
 cloud refused the read (the line says which).`;
@@ -24,7 +30,10 @@ if (wantsHelp(argv)) {
   console.log(HELP);
   process.exit(0);
 }
-const { flags, positionals } = parseFlags(argv, { bool: ["comments", "json"], value: ["source"] });
+const { flags, positionals } = parseFlags(argv, {
+  bool: ["comments", "json"],
+  value: ["source"],
+});
 const ticket = positionals[0];
 if (!ticket) usage("read-ticket needs a ticket identifier (see --help)");
 
@@ -49,9 +58,16 @@ if (flags.json) {
 
 const line = (label, value) => {
   if (value === undefined || value === null || value === "") return;
-  console.log(`${label}: ${typeof value === "string" ? value : JSON.stringify(value)}`);
+  console.log(
+    `${label}: ${typeof value === "string" ? value : JSON.stringify(value)}`,
+  );
 };
-const names = (list, key) => (Array.isArray(list) ? list.map((x) => (x && typeof x === "object" ? (x[key] ?? JSON.stringify(x)) : String(x))) : []);
+const names = (list, key) =>
+  Array.isArray(list)
+    ? list.map((x) =>
+        x && typeof x === "object" ? (x[key] ?? JSON.stringify(x)) : String(x),
+      )
+    : [];
 
 line("ticket", row.identifier ?? row.id);
 line("title", row.title);
@@ -68,13 +84,20 @@ line("url", row.url);
 line("updated", row.updated_at);
 if (Array.isArray(row.relations) && row.relations.length) {
   console.log(`relations (${row.relations.length}):`);
-  for (const rel of row.relations) console.log(`  ${rel.type ?? "?"}: ${rel.issue_identifier ?? ""} -> ${rel.related_identifier ?? JSON.stringify(rel)}`);
+  for (const rel of row.relations)
+    console.log(
+      `  ${rel.type ?? "?"}: ${rel.issue_identifier ?? ""} -> ${rel.related_identifier ?? JSON.stringify(rel)}`,
+    );
 }
 if (Array.isArray(row.linked_pulls) && row.linked_pulls.length) {
   console.log(`linked pull requests (${row.linked_pulls.length}):`);
-  for (const pr of row.linked_pulls) console.log(`  #${pr.number ?? "?"} ${pr.repo_id ?? ""} [${pr.node_id ?? ""}]`);
+  for (const pr of row.linked_pulls)
+    console.log(
+      `  #${pr.number ?? "?"} ${pr.repo_id ?? ""} [${pr.node_id ?? ""}]`,
+    );
 }
-if (Array.isArray(row.agent_sessions)) line("agent sessions", row.agent_sessions.length);
+if (Array.isArray(row.agent_sessions))
+  line("agent sessions", row.agent_sessions.length);
 if (Array.isArray(row.activity)) line("activity entries", row.activity.length);
 if (Array.isArray(row.comments)) line("comments", row.comments.length);
 if (row.description) {
@@ -87,7 +110,9 @@ if (flags.comments && Array.isArray(row.comments)) {
     const who = c.author_name ?? c.author_id ?? "?";
     const bot = c.is_bot ? " [bot]" : "";
     const parent = c.parent_id ? ` reply-to ${c.parent_id}` : "";
-    console.log(`-- ${c.id} · ${who}${bot} · ${c.updated_at ?? c.created_at ?? ""}${parent}`);
+    console.log(
+      `-- ${c.id} · ${who}${bot} · ${c.updated_at ?? c.created_at ?? ""}${parent}`,
+    );
     console.log(String(c.body ?? "").trimEnd());
   }
 }

package/skills/catalyst-onboard/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Set up Catalyst Cloud and say whether setup is working. Walks a person from nothing to their first ticket running, one step at a time: the coding account, the project, the integrations and connected accounts, each repository's settings file, then one real ticket moving. Also logs this machine in, reads the readiness verdict with who can fix each failure, and checks the optional local replica. Use when someone says "set me up", "onboard me", "I just signed up", "get me started", "what do I do first", "log me in", "which account is this machine on", "am I set up", "what is missing", "why does nothing happen" or "is the replica running", when a login expired, or when a skill script exits 2 saying this machine is not connected. Does every step a key can do through the catalyst CLI, hands over the exact page for the steps only a browser can do, and never claims a step it did not watch succeed.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.14.6 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.14.7 — written in this repository for customer accounts -->
 
 # Onboard me
 
@@ -14,10 +14,11 @@ Guide setup through the same `catalyst onboard` flow that the installer runs. Th
 
 1. Run `catalyst capabilities --json`. If its `onboard` entry is available and advertises `bootstrapHandoff: true`, use this path. If absent, use the older step-by-step references below and name the CLI update needed for the continuous flow.
 2. For a requested setup, run `catalyst onboard`. To inspect first, run `catalyst onboard --dry-run --json`. Resume with `catalyst onboard`; the command rechecks saved results. Do not ask the person to confirm completed browser steps or add a separate approval before the command's plan question.
-3. For the current onboarding checks, run `catalyst ready --onboarding --json`. A failed check needs attention. An unknown check needs evidence. Report observed project work separately from incomplete setup; an unknown setup check does not prove work stopped.
-4. Exit 0 completes the requested scope. Exit 10 means a failed step, 11 means waiting, and 12 means a guard refused the action. A successful `--only` step does not mean onboarding is complete. Keep the command's safe fix and supported resume command in your reply.
+3. In a terminal, the command shows the verified person, workspace and plan before approval. Without terminal input, or with `--json`, use `--yes` only when the person has accepted the displayed defaults; otherwise setup waits with exit 11 and keeps the saved connection and receipt. JSON keeps progress, identity, the plan and quota disclosure on stderr and returns one result on stdout. A supplied key needs `catalyst login` before onboarding; browser sign-in does not replace it.
+4. For the current onboarding checks, run `catalyst ready --onboarding --json`. A failed check needs attention. An unknown check needs evidence. Report observed project work separately from incomplete setup; an unknown setup check does not prove work stopped.
+5. Exit 0 completes the requested scope. Exit 10 means a failed step, 11 means waiting, and 12 means a guard refused the action. A successful `--only` step does not mean onboarding is complete. Keep the command's safe fix and supported resume command in your reply.
 
-Use cloud reads for ordinary workstation setup checks. Offer local sync for local SQL, offline access or sustained reads inside the plan review. It is optional; do not make an absent replica a setup failure. Browser approval belongs to the person. Missing bearer capabilities stay unfinished; never call a session-only route from the CLI or invent a command.
+Use cloud reads for ordinary workstation setup checks. Offer local sync for local SQL or sustained local reads inside the plan review. Local sync does not promise offline browsing. It is optional; do not make an absent replica a setup failure. Browser approval belongs to the person. Missing bearer capabilities stay unfinished; never call a session-only route from the CLI or invent a command.
 
 Choose an existing Linear team explicitly in the command's team picker or with `catalyst onboard --team <team ID or unique key>`. Unattended setup does not pick the first team, even when only one is visible. Resume rechecks the saved selection; final readiness reads only that team. A team used to verify the workspace grant is not a project selection. Setup does not create a Linear team. Native sign-in waits for up to ten minutes across all device-code rounds; a timeout saves progress for the next run.
 

package/skills/catalyst-onboard/references/local-sync.md

@@ -4,7 +4,9 @@ The replica is an on-machine SQLite copy of the account for cheap repeated reads
 
 ## The replica's exit codes
 
-`catalyst replica status` needs no network. Exit 0 is fresh (a live writer, a heartbeat under 15 seconds, a cursor), and skills read the replica. Exit 1 is stale and 3 is absent; skills read the API, and `catalyst replica start --detach` restarts a stale one. Exit 2 is not connected (`references/connecting-this-machine.md`). `--probe` adds one network call comparing the local cursor with the cloud head. Every read verb names its source on standard error.
+`catalyst replica status` needs no network. Exit 0 is fresh (a live writer, a heartbeat under 15 seconds, a cursor), exit 1 is stale and 3 is absent. Skills use cloud reads by default; a fresh replica is used only with explicit `--source replica`. `catalyst replica start --detach` restarts a stale writer after local sync is selected. Exit 2 is not connected (`references/connecting-this-machine.md`). `--probe` adds one network call comparing the local cursor with the cloud head. Every read verb names its source on standard error.
+
+Local sync is opt-in. `catalyst replica status --json` carries `configured`, which is true only when this machine opted in: `CATALYST_REPLICA_DB` is set, or the machine paths file declares `replicaDb`. A machine that never opted in prints `replica: not configured (cloud reads; local sync is opt-in)` and reads the cloud. A machine with `configured: true` and exit 1 or 3 opted in and its writer is down.
 
 ## Checking and starting both
 

package/skills/run-this-project/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Own one Catalyst Cloud project end to end until it closes. Use when the person says "run this project for me", "own this until it ships", "keep this moving", or hands you a project id or a set of tickets to drive. Subscribes to the account's event stream for the scope through the catalyst CLI, reacts to each change in the same turn, makes tickets ready and moves them to dispatch, parks what should stop, chases stalls, escalates inward, and keeps one status summary current. Writes to Linear as the app actor; never polls.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.14.6 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.14.7 — written in this repository for customer accounts -->
 
 # Run this project
 

package/skills/unstick/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Get a stuck Catalyst Cloud ticket moving again. Use when the person asks "why is this parked and can you release it?", "unpark this", "get things flowing again", "the outage is over, retry what failed", or hands you a ticket that is not moving. Reads why nothing runs and what holds the ticket through the catalyst CLI, decides whether the recorded cause is fixed, previews the release, releases every governor holding the ticket the right way (or one failure class across a team), and raises an ask only for what a person has to do. Never releases a cause it cannot show changed without saying so.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.14.6 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.14.7 — written in this repository for customer accounts -->
 
 # Unstick