@catalyst-cloud/cli 0.14.6 → 0.14.8

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.8 — 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. For a full run, exit 0 means work can start. If the receipt's `complete` is false, repository settings, local values, the daily update or the first ticket are still open, and the command lists them under "Next, when you want". 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.
 
@@ -57,6 +58,7 @@ Scripts are run, never read; each prints `--help`.
 | a browser step, or confirming a page that said it worked | `references/what-the-browser-owns.md` |
 | the repository's `.catalyst/catalyst.toml` and its approval; its AGENTS.md block and agent layout | `references/declaring-a-repository.md`; `references/repository-agent-setup.md` |
 | the replica or event cache | `references/local-sync.md` |
+| local SQL, only when `catalyst replica status --json` reports `configured: true` | `references/local-replica.md` |
 | installing, updating, or migrating Catalyst skills | `references/skill-sources.md` |
 | what Catalyst is, or why the first ticket did not start | the `whats-happening` skill, then `unstick` if something holds it |
 

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

@@ -0,0 +1,40 @@
+# Local SQL on an opted-in machine
+
+Load this only when `catalyst replica status --json` reports `configured: true`. On any other machine, setup is complete without a replica: every skill reads from the cloud, and `references/local-sync.md` explains how a person opts in if they ask for local SQL.
+
+`configured: true` means this machine opted in: `CATALYST_REPLICA_DB` is set, or the machine paths file declares `replicaDb`. It does not mean the writer is running. `references/local-sync.md` reads liveness and starts the writer.
+
+## Before any query
+
+Run `catalyst replica status --probe --json`. Trust local rows only when `verdict` is `fresh` and `cursor` equals `head`. A first start seeds the whole snapshot, so a new replica reads stale until its cursor appears.
+
+## Running SQL
+
+- `catalyst replica sql "<one SELECT>" --json` runs one read-only `SELECT` and prints rows. Anything else is refused.
+- `catalyst replica schema` prints every table with its columns; `catalyst replica schema <table>` prints one.
+- `catalyst query issues --source replica`, `issue`, `pulls` and `projects` read the local copy through the same verbs as the cloud read. Without `--source replica`, they read the cloud.
+
+Timestamps are milliseconds since the epoch. Rows with `removed_at` set were deleted upstream.
+
+## First checks after a start
+
+Is the copy populated?
+
+```sql
+select (select count(*) from issues where removed_at is null) as tickets,
+       (select count(*) from pull_requests) as pull_requests,
+       (select count(*) from projects) as projects
+```
+
+Which teams does it hold?
+
+```sql
+select team_key, count(*) as tickets from issues
+where removed_at is null group by team_key order by team_key
+```
+
+Compare these counts with what the person sees in Linear. A team missing here is a scope question for the account, not a replica fault.
+
+## Where the reading recipes live
+
+Ticket recipes are in the `catalyst-linear` skill's local replica reference, and pull request recipes in the `catalyst-github` skill's. Both carry the same gate as this page.

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

@@ -4,19 +4,23 @@ 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
 
 `node scripts/local-sync.mjs` shows the local state. Only after the person opts in, `--start` starts the replica and event cache writers and waits up to 90 seconds (`--wait <seconds>`, 0 to 300).
 
-Say `Local sync current` only when both writers have live heartbeats and each cursor equals its cloud head. A detached process starting, one fresh heartbeat, or replica freshness alone does not prove event freshness. `catalyst replica status --probe --json` checks the replica cursor; `catalyst events status --probe --json` checks the separate event cursor. Unknown means the comparison could not be proved, which is not stale. The script exits 0 current, 1 stale, 3 absent, and 2 for "not connected" or "unknown", with a printed reason. After a restart, check again before relying on local data.
+Say `Local sync current` only when both writers have live heartbeats and each cursor equals its cloud head. A detached process starting, one fresh heartbeat, or replica freshness alone does not prove event freshness. `catalyst replica status --probe --json` checks the replica cursor; `catalyst events status --from-cache --probe --json` checks the separate event cursor. Unknown means the comparison could not be proved, which is not stale. The script exits 0 current, 1 stale, 3 absent, and 2 for "not connected" or "unknown", with a printed reason. After a restart, check again before relying on local data.
 
 ## First ticket event
 
-Before the person moves a card, run `node scripts/local-sync.mjs --start` (after they opt in) and wait until it reports current. Then run `catalyst events status --probe --json` and record its `cursor` as `<cursor-before-move>`. Move the card only after this baseline is captured. Then run `catalyst events wait-for --ticket <ticket-identifier> --after <cursor-before-move> --timeout 300` with the identifier `explain` printed, and no guessed event type. The explicit cursor finds an event that reached the cache before the command began.
+The default wait reads the cloud and needs no local sync. Before the person moves a card, run `catalyst events status --json` and record its `head` as `<cursor-before-move>`. Move the card only after this baseline is captured. Then run `catalyst events wait-for --ticket <ticket-identifier> --after <cursor-before-move> --timeout 300` with the identifier `explain` printed, and no guessed event type. The explicit cursor finds an event that happened before the command began.
+
+Exit 0 prints a matching event after the baseline. Exit 1 means no matching event arrived within five minutes; check `catalyst explain <ticket-identifier>` before inferring a cloud or webhook failure. Exit 4 means the cloud event service was unreachable: an outage, not a timeout. Other errors are unknown. `explain` stays the API-backed answer to why a ticket can or cannot run.
 
-Exit 0 prints a matching event after the baseline, proving it reached this machine's cache. Exit 1 means no matching cached event arrived within five minutes; recheck `node scripts/local-sync.mjs` and report stale or unknown evidence without inferring a cloud or webhook failure. Exit 3 means the event cache is absent; ask before starting it. Other errors are unknown. `explain` stays the API-backed answer to why a ticket can or cannot run.
+On a machine that opted in to local sync, the same wait can also prove the event reached this machine's cache. Run `node scripts/local-sync.mjs --start` and wait until it reports current. Then run `catalyst events status --from-cache --probe --json` and record its `cursor` as `<cursor-before-move>`. Move the card only after this baseline is captured. Then run `catalyst events wait-for --from-cache --ticket <ticket-identifier> --after <cursor-before-move> --timeout 300`. Exit 1 means no matching cached event arrived within five minutes; recheck `node scripts/local-sync.mjs` and report stale or unknown evidence without inferring a cloud or webhook failure. Exit 3 means the event cache is absent; ask before starting it.
 
 ## The writer
 

package/skills/catalyst-onboard/scripts/local-sync.mjs

@@ -6,7 +6,7 @@ import { fileURLToPath } from "node:url";
 import { cliTarget } from "./lib/cli.mjs";
 
 const STATUS_COMMAND = ["replica", "status", "--probe", "--json"];
-const EVENTS_COMMAND = ["events", "status", "--probe", "--json"];
+const EVENTS_COMMAND = ["events", "status", "--from-cache", "--probe", "--json"];
 const START_COMMAND = ["replica", "start", "--detach"];
 const RECOVERY_COMMAND = "catalyst replica start --detach";
 
@@ -120,7 +120,7 @@ function readStatus(run) {
         current: false,
         reason: `event freshness is unknown: ${eventsResult.error || eventsResult.stderr.trim() || "invalid JSON"}`,
       },
-      recovery: "catalyst events status --probe --json",
+      recovery: "catalyst events status --from-cache --probe --json",
     };
   }
   return { status, events, assessment: assessLocalSync(status, events) };

package/skills/catalyst-onboard/scripts/where-am-i.mjs

@@ -30,7 +30,7 @@ const SPEC = {
 };
 const NOTES = [
   "Reads, in this order: `status` (machine), `ready --json` (machine checks and project checks, kept apart),",
-  "`replica status --probe --json` and `events status --probe --json` (optional local freshness),",
+  "`replica status --probe --json` and `events status --from-cache --probe --json` (optional local freshness),",
   "`me --json` and personal connection statuses (person), `contract --path …` for the account, the projects and the repositories,",
   "`contract --path codingAccounts` and `accounts --json` (coding accounts, and which one needs a new credential), and each",
   "project's hosts_current check with its fixedWhere (host), and each project's environment_declared check with its per-repository notes (repository declarations). The teams read is refreshed, so a mapping just saved reads back mapped.",

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.8 — 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.8 — written in this repository for customer accounts -->
 
 # Unstick
 

package/skills/what-needs-me/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   The human's decision inbox on Catalyst Cloud, and the one way an agent raises a decision on their behalf. Use when the person asks "what needs me?", "what am I blocking?", or when active work is gated on a choice only they can make. Lists open asks ranked by how much open work each one holds, files an ask through the cloud's ask route with the account's own template, and records the answer so the held work releases. Never answers as the human, never duplicates an open ask.
 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.8 — written in this repository for customer accounts -->
 
 # What needs me
 

package/skills/what-this-repo-needs/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   What environment variable names does this repository need, and where does each one come from? Scans the repository offline (no login, no network) and lists the names in three groups (build/test, deploy-only, bindings), each with where it was found, what uses it, and where a local value would come from. Never reads a value or prints one. Also checks the environment variable table in `.catalyst/catalyst.toml` offline. Use when someone asks "what does catalyst.env.json mean", "what env vars does this repo need", "why does the container need this", or before reviewing or writing the declaration.
 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.8 — written in this repository for customer accounts -->
 
 # What this repository needs
 

package/skills/whats-happening/SKILL.md

@@ -4,13 +4,13 @@ description: >-
   Use for "what's happening?", "where are we?", "why is that stuck?", "what closed?", "what's next?", "how does this work?", "why did it do that?", "how does it prioritise?" and "what does this setting do, where is it set?" in Catalyst Cloud, or asks for something to be done rather than known. Reads the contract via catalyst CLI. Read-only: route work/decisions, never answer as the human.
 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.8 — written in this repository for customer accounts -->
 
 # What's happening
 
 Use one snapshot and the person's login. Run scripts, never read them. --help explains usage; exit 2 needs onboard, exit 1 means failure.
 
-- `node scripts/snapshot.mjs` prints contract, running work, queue, ranked asks, replica verdict. --board adds stages, --accounts coding accounts, --team K narrows.
+- `node scripts/snapshot.mjs` reads contract, running work, queue and ranked asks from the cloud. --board adds stages, --accounts coding accounts, --team K narrows. --replica adds optional local diagnostics.
 - `node scripts/explain.mjs <ticket>` explains eligibility; --history adds attempts, rounds, holds and releases.
 - `node scripts/show-my-map.mjs [--team K]` prints stages, labels, ladder and thresholds.
 
@@ -29,5 +29,7 @@ Comments/relations: catalyst-linear. PRs: catalyst-github. Readiness: catalyst-o
 | columns or slots? | references/stages-and-mapping.md |
 | accounts, windows, quarantine or provider? | references/coding-accounts.md |
 | setting, screen, route or role? | references/settings-and-where-they-live.md |
+| which command answers it from the cloud? | references/reading-from-the-cloud.md |
+| local SQL? only if `catalyst replica status --json` says `configured: true` | references/local-replica.md |
 
 Read-only: give ids, source, release and actor. Route releases to `unstick`, decisions to what-needs-me before defaults, ownership to run-this-project. Subscribe, never poll. Report each system cause once.

package/skills/whats-happening/references/local-replica.md

@@ -0,0 +1,51 @@
+# Local replica (opt-in)
+
+Load this only when `catalyst replica status --json` reports `configured: true`. Otherwise answer from the cloud (`references/reading-from-the-cloud.md`) and never mention the replica.
+
+The replica is an on-machine SQLite copy of the account, present only after the person opted in to local sync. It adds ad hoc SQL over the board. It never holds running work, the queue, asks, eligibility or phase history; those stay cloud reads.
+
+## Freshness
+
+`catalyst replica status --probe --json` first. Use local rows only when `verdict` is `fresh` and `cursor` equals `head`, and quote the cursor. `stale` or `absent` with `configured: true` means the opted-in writer is down: answer from the cloud and say so in the source clause. Start it only when asked (`catalyst replica start --detach`).
+
+The snapshot's replica verdict line belongs in the status reply's source clause only on an opted-in machine.
+
+## SQL
+
+`catalyst replica sql "<one SELECT>" --json` runs one read-only `SELECT`. `catalyst replica schema <table>` prints columns. Timestamps are milliseconds since the epoch; filter `removed_at is null` for current rows. Replace `<team key>` and `KEY-123` with real values from the contract.
+
+Cards per stage on one team:
+
+```sql
+select state, count(*) as n from issues
+where team_key = '<team key>' and removed_at is null
+group by state order by n desc
+```
+
+What closed in the last day:
+
+```sql
+select identifier, title, completed_at from issues
+where completed_at > (strftime('%s', 'now') - 86400) * 1000 and removed_at is null
+order by completed_at desc
+```
+
+Stage moves in the last day, newest first:
+
+```sql
+select i.identifier, h.from_state, h.to_state, h.created_at
+from issue_history h join issues i on i.id = h.issue_id
+where h.to_state is not null and h.created_at > (strftime('%s', 'now') - 86400) * 1000
+order by h.created_at desc limit 50
+```
+
+Cards unmoved for three days in a stage, oldest first:
+
+```sql
+select identifier, state, updated_at from issues
+where team_key = '<team key>' and state = '<stage name>' and removed_at is null
+  and updated_at < (strftime('%s', 'now') - 3 * 86400) * 1000
+order by updated_at
+```
+
+An unmoved card may still be running, retrying or remediating. Check `catalyst history KEY-123` before calling it stuck.

package/skills/whats-happening/references/reading-from-the-cloud.md

@@ -0,0 +1,21 @@
+# Reading from the cloud
+
+Cloud reads are the default everywhere and need no local writer or database. Each command reads the cloud through the CLI.
+
+| question | command |
+| -- | -- |
+| ticket stage, owner, linked PRs | `catalyst query issue KEY-123` |
+| last phase, attempts, rounds, park, lease | `catalyst history KEY-123` |
+| why not running, what runs next | `node scripts/explain.mjs KEY-123` |
+| running now | `catalyst running` |
+| queue order | `catalyst queue` |
+| PR state and checks | `catalyst query pulls --ticket KEY-123`, then `catalyst query pull <node-id>` |
+| what changed since a point | `catalyst query changes --since head` |
+| a ticket's events, newest first | `catalyst events query --ticket KEY-123` |
+| wait for a phase to finish | `catalyst events wait-for --ticket KEY-123 --type relay.phase.completed --after <head> --timeout 300` |
+
+A status-only read of a ticket and of its execution history is coming. No CLI flag selects it yet; read the full record.
+
+Events: `catalyst events` reads the cloud by default. `events status --json` gives the `head` to wait after. Exit 4 from `wait-for` is an outage, not a timeout. `--from-cache` reads the local event cache, which exists only where local sync is on.
+
+Local SQL: `references/local-replica.md`, only when `configured: true`.

package/skills/whats-happening/references/status-reply.md

@@ -1,6 +1,6 @@
 # Status
 
-Open with takenAt, source and replica cursor/API reason. Then:
+Open with takenAt and the cloud source. Include a replica cursor only when optional local diagnostics were requested. Then:
 
 1. In flight: ticket, phase and elapsed time from running.
 2. Blocked: reason and release actor.

package/skills/whats-happening/scripts/snapshot.mjs

@@ -2,25 +2,48 @@
 // snapshot.mjs — one call that answers "where are we?": the account's contract (trimmed to what a
 // status reply needs), what is running, what is queued, what is waiting on a human, and whether the
 // local replica is fresh. Prints ONE JSON document on stdout and the source line on stderr.
-import { mustRun, parseFlags, parseJson, printHelp, runCli } from "./lib/cli.mjs";
+import {
+  mustRun,
+  parseFlags,
+  parseJson,
+  printHelp,
+  runCli,
+} from "./lib/cli.mjs";
 
 const SPEC = {
   team: { value: true, help: "limit the queue and the board to this team key" },
-  board: { value: false, help: "also include open tickets grouped by stage, in the contract's slot order" },
+  board: {
+    value: false,
+    help: "also include open tickets grouped by stage, in the contract's slot order",
+  },
   limit: { value: true, help: "board: max tickets to read (default 200)" },
-  "full-contract": { value: false, help: "include the whole contract instead of the trimmed `tenant` block" },
-  accounts: { value: false, help: "also include the coding accounts: provider, state, usage windows, walls, quarantine (never a credential)" },
+  "full-contract": {
+    value: false,
+    help: "include the whole contract instead of the trimmed `tenant` block",
+  },
+  accounts: {
+    value: false,
+    help: "also include the coding accounts: provider, state, usage windows, walls, quarantine (never a credential)",
+  },
+  replica: {
+    value: false,
+    help: "also read optional local replica diagnostics",
+  },
 };
 
 const { help, flags } = parseFlags(process.argv.slice(2), SPEC);
 if (help) {
-  printHelp("node scripts/snapshot.mjs [--team K] [--board] [--accounts] [--limit N] [--full-contract] [--help]", SPEC, [
-    "Runs, in order: catalyst contract, running, queue, ask list, replica status (query issues with --board,",
-    "accounts with --accounts).",
-    "Output: one JSON document {takenAt, source, tenant, running, queue, waitingOnHuman, board?, accounts?, errors?}.",
-    "A section the cloud refused is reported under errors and the rest still prints; exit 1 in that case.",
-    "Every account fact (stage names, thresholds, teams) comes from the contract in this output, never from prose.",
-  ]);
+  printHelp(
+    "node scripts/snapshot.mjs [--team K] [--board] [--accounts] [--limit N] [--full-contract] [--help]",
+    SPEC,
+    [
+      "Reads catalyst contract, running, queue and ask list from the cloud (query issues with --board,",
+      "accounts with --accounts, optional local diagnostics with --replica).",
+      "Output: one JSON document {takenAt, source, tenant, running, queue, waitingOnHuman, board?, accounts?, errors?}.",
+      "A section the cloud refused is reported under errors and the rest still prints; exit 1 in that case.",
+      "Every account fact (stage names, thresholds, teams) comes from the contract in this output, never from prose.",
+    ],
+  );
   process.exit(0);
 }
 
@@ -28,26 +51,40 @@ const errors = {};
 const section = (name, args) => {
   const r = runCli(args);
   if (r.code !== 0) {
-    errors[name] = (r.stderr || r.stdout || `exit ${r.code}`).trim().split("\n").at(-1);
+    errors[name] = (r.stderr || r.stdout || `exit ${r.code}`)
+      .trim()
+      .split("\n")
+      .at(-1);
     return null;
   }
   return parseJson(r.stdout, name);
 };
 
-const contract = parseJson(mustRun(["contract", "--json"], { quiet: true }).stdout, "contract");
+const contract = parseJson(
+  mustRun(["contract", "--json"], { quiet: true }).stdout,
+  "contract",
+);
 // `replica status` exits 0 fresh, 1 stale, 3 absent — all three are verdicts with JSON on stdout,
 // not failures; only a non-JSON answer is an error.
 const replica = (() => {
+  if (!flags.replica)
+    return { verdict: "not-selected", cursor: null, heartbeatAgeMs: null };
   const r = runCli(["replica", "status", "--json"]);
   try {
     return JSON.parse(r.stdout.trim());
   } catch {
-    errors.replica = (r.stderr || r.stdout || `exit ${r.code}`).trim().split("\n").at(-1);
+    errors.replica = (r.stderr || r.stdout || `exit ${r.code}`)
+      .trim()
+      .split("\n")
+      .at(-1);
     return { verdict: "unknown", cursor: null, heartbeatAgeMs: null };
   }
 })();
 const running = section("running", ["running", "--json"]);
-const queue = section("queue", flags.team ? ["queue", "--team", flags.team, "--json"] : ["queue", "--json"]);
+const queue = section(
+  "queue",
+  flags.team ? ["queue", "--team", flags.team, "--json"] : ["queue", "--json"],
+);
 const asks = section("waitingOnHuman", ["ask", "list", "--json"]);
 
 const out = {
@@ -58,7 +95,9 @@ const out = {
     replicaCursor: replica.cursor ?? null,
     replicaHeartbeatAgeMs: replica.heartbeatAgeMs ?? null,
   },
-  tenant: flags["full-contract"] ? contract : trimContract(contract, flags.team),
+  tenant: flags["full-contract"]
+    ? contract
+    : trimContract(contract, flags.team),
   running,
   queue,
   waitingOnHuman: asks,
@@ -67,14 +106,23 @@ const out = {
 if (flags.accounts) out.accounts = section("accounts", ["accounts", "--json"]);
 
 if (flags.board) {
-  const args = ["query", "issues", "--limit", String(flags.limit ?? 200), "--json"];
+  const args = [
+    "query",
+    "issues",
+    "--source",
+    "api",
+    "--limit",
+    String(flags.limit ?? 200),
+    "--json",
+  ];
   if (flags.team) args.push("--team", flags.team);
   const r = runCli(args);
   const sourceLine = (r.stderr.match(/^source: .*$/m) ?? [null])[0];
   // A board read is a window (`--limit` stays the default), and a window the cloud cut short must
   // say so rather than reading as the whole team.
   const truncatedLine = (r.stderr.match(/^truncated at .*$/m) ?? [null])[0];
-  if (r.code !== 0) errors.board = (r.stderr || `exit ${r.code}`).trim().split("\n").at(-1);
+  if (r.code !== 0)
+    errors.board = (r.stderr || `exit ${r.code}`).trim().split("\n").at(-1);
   else {
     const rows = parseJson(r.stdout, "issues");
     out.board = groupByStage(rows, contract, flags.team);
@@ -84,18 +132,27 @@ if (flags.board) {
 }
 
 if (Object.keys(errors).length) out.errors = errors;
-process.stderr.write(`source: api for running/queue/asks; replica ${replica.verdict}${replica.cursor != null ? ` (cursor ${replica.cursor})` : ""}${out.source.board ? `; board from ${out.source.board}` : ""}\n`);
+process.stderr.write(
+  `source: api for running/queue/asks; replica ${replica.verdict}${replica.cursor != null ? ` (cursor ${replica.cursor})` : ""}${out.source.board ? `; board from ${out.source.board}` : ""}\n`,
+);
 process.stdout.write(JSON.stringify(out, null, 2) + "\n");
 process.exit(Object.keys(errors).length ? 1 : 0);
 
 /** The contract facts a status reply needs, and nothing a reply should not paste. */
 function trimContract(doc, teamKey) {
-  const teams = (doc.teams ?? []).filter((t) => !teamKey || String(t.key ?? "").toUpperCase() === teamKey.toUpperCase());
+  const teams = (doc.teams ?? []).filter(
+    (t) =>
+      !teamKey || String(t.key ?? "").toUpperCase() === teamKey.toUpperCase(),
+  );
   return {
     contractVersion: doc.contractVersion,
     account: { slug: doc.account?.slug, name: doc.account?.name },
     slots: doc.slots,
-    ladder: { phases: doc.ladder?.phases, intakeEnabled: doc.ladder?.intakeEnabled, keying: doc.ladder?.keying },
+    ladder: {
+      phases: doc.ladder?.phases,
+      intakeEnabled: doc.ladder?.intakeEnabled,
+      keying: doc.ladder?.keying,
+    },
     thresholds: doc.thresholds,
     mergeDefaultPolicy: doc.merge?.defaultPolicy,
     teams: teams.map((t) => ({
@@ -106,7 +163,14 @@ function trimContract(doc, teamKey) {
       stages: Object.fromEntries(
         (doc.slots ?? Object.keys(t.stages ?? {}))
           .filter((slot) => t.stages?.[slot])
-          .map((slot) => [slot, { name: t.stages[slot].name, type: t.stages[slot].type, stateStillExists: t.stages[slot].stateStillExists }]),
+          .map((slot) => [
+            slot,
+            {
+              name: t.stages[slot].name,
+              type: t.stages[slot].type,
+              stateStillExists: t.stages[slot].stateStillExists,
+            },
+          ]),
       ),
       labels: {
         ask: (t.labels?.ask ?? []).map((l) => l.name),
@@ -124,11 +188,19 @@ function groupByStage(rows, doc, teamKey) {
   const seen = new Set();
   const terminal = new Set();
   for (const t of doc.teams ?? []) {
-    if (teamKey && String(t.key ?? "").toUpperCase() !== teamKey.toUpperCase()) continue;
+    if (teamKey && String(t.key ?? "").toUpperCase() !== teamKey.toUpperCase())
+      continue;
     for (const slot of doc.slots ?? []) {
       const s = t.stages?.[slot];
       if (!s?.name) continue;
-      if (slot === "done" || slot === "canceled" || ["completed", "canceled", "cancelled"].includes(String(s.type ?? "").toLowerCase())) terminal.add(s.name);
+      if (
+        slot === "done" ||
+        slot === "canceled" ||
+        ["completed", "canceled", "cancelled"].includes(
+          String(s.type ?? "").toLowerCase(),
+        )
+      )
+        terminal.add(s.name);
       else if (!seen.has(s.name)) {
         seen.add(s.name);
         order.push(s.name);
@@ -148,6 +220,12 @@ function groupByStage(rows, doc, teamKey) {
       projectId: r.project_id ?? null,
     });
   }
-  const extra = Object.keys(byStage).filter((s) => !seen.has(s)).sort();
-  return { stageOrder: [...order, ...extra], byStage, terminalStagesDropped: [...terminal] };
+  const extra = Object.keys(byStage)
+    .filter((s) => !seen.has(s))
+    .sort();
+  return {
+    stageOrder: [...order, ...extra],
+    byStage,
+    terminalStagesDropped: [...terminal],
+  };
 }

package/vendor/settings/index.d.ts

@@ -0,0 +1,4 @@
+export type FullSettingsValidation =
+  | { ok: false; errors: string[] }
+  | { ok: true; errors: []; linearTeam: string; variableNames: string[]; secretNames: string[] };
+export declare function validateFullSettings(text: string): FullSettingsValidation;