@catalyst-cloud/cli 0.14.6 → 0.14.8

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.14.8
+
+- Onboarding on a computer with no browser, such as a Docker container, prints the Catalyst page that finishes each Linear and GitHub approval and keeps waiting, instead of stopping.
+- Onboarding accepts cloud repository IDs such as `tenant-9:owner__repo`, so registering a project no longer fails on them.
+- When the sign-in expires during a provider approval, onboarding stops and says to run `catalyst login`, instead of waiting for the approval to time out.
+- Steps that wait name the next action and the page to use, and the end of a run lists what is left.
+- `catalyst login` says the browser opened only when it did.
+- Onboarding finishes once everything work needs is in place. Repository settings, values and the daily update are listed as next steps instead of blocking.
+
+## 0.14.7
+
+- Setup uses cloud reads by default and offers local sync as an option. Onboarding preserves verified account and repository choices when it resumes.
+- Settings drafts stay private for review; keeping a draft does not approve it or import values.
+
 ## 0.14.6
 
 - A current Catalyst data folder no longer triggers a legacy-runtime cleanup warning. Legacy checks and removal keep current shared data and report it separately.

package/README.md

@@ -126,7 +126,7 @@ catalyst ready --onboarding --json
 
 The dry run writes no files. `--only <step>` runs one step and reports its scope separately from full onboarding. Exit 10 means a failed step, 11 means waiting, and 12 means a guard refused the action. The private receipt is `install/last-run.json` under your machine's Catalyst state directory; credentials stay in the login config. A fake HOME reports old services and keeps them intact.
 
-Local sync is optional. Include it in the plan with `--local-sync` when you need local SQL or offline access. A resume keeps that choice. Readiness distinguishes failed checks from missing evidence and reports observed project work separately from unfinished setup.
+Local sync is optional. Include it in the plan with `--local-sync` when you need local SQL or sustained local reads. A resume keeps that choice. Readiness distinguishes failed checks from missing evidence and reports observed project work separately from unfinished setup.
 
 ## Requirements
 
@@ -153,12 +153,14 @@ Nothing, by default. After `login`, every read, write, ask and explanation goes
 | process | needed for | what it holds on disk | lifetime |
 | --- | --- | --- | --- |
 | none | every read, write, ask and explain | `customer.json` and `contract.json` | the default after login |
-| `catalyst replica start` | local SQL, cheap repeated reads, and local event `tail`, `wait-for`, and `query` | one SQLite file plus a bounded event cache under `$XDG_STATE_HOME/catalyst/events/` (fallback `~/.local/state/catalyst/events/`) | one long-running process; foreground by default, `--detach` writes a pidfile beside the database and returns; `login --start-replica` does the same at the end of login |
+| `catalyst replica start` | local SQL, cheap repeated reads, and a shared local event cache read with `events ... --from-cache` | one SQLite file plus a bounded event cache under `$XDG_STATE_HOME/catalyst/events/` (fallback `~/.local/state/catalyst/events/`) | one long-running process; foreground by default, `--detach` writes a pidfile beside the database and returns; `login --start-replica` does the same at the end of login |
 | `catalyst watch` | a project owner reacting to its scope | one cursor file (`~/.config/catalyst-cloud/watch-cursor.json`) stamped with the account | lives inside the session that armed it; exits with it |
 
-The check every skill runs first is `catalyst replica status`, which needs no network: is the pidfile's process alive, is the writer-lock heartbeat younger than the staleness threshold, and is the cursor non-empty. It exits `0` for fresh, `1` for present but stale, `2` for not connected, `3` for absent, and prints one line either way (`--json` for scripts). A fresh replica is used; anything else falls back to the API and the skill says so in its answer. A skill never refuses to work because the replica is down and never silently reads a stale one. `replica status --probe` compares the local cursor against the cloud's head for the honest "how far behind" number; that is the only form that touches the network. `catalyst replica stop` stops a detached writer.
+CLI and skill reads use the cloud API by default, including on a machine with a fresh local replica. No background writer or local database is needed. `catalyst query ... --source replica` explicitly chooses the optional local view; the first stderr line names the source. Local sync does not promise offline browsing.
 
-`catalyst events status --probe` checks the event cache's own cursor and compares it with the cloud head; `replica status --probe` checks the separate entity-replica cursor. A fresh replica does not prove event freshness. `events tail` follows new cached events, `events wait-for --ticket ... --timeout ...` performs a bounded wait, and `events query` reads retained history. Those three commands only read the cache; `events status --probe` makes the cloud comparison. The replica process is the single writer and reports an event-sync failure without terminating a healthy entity replica. The event cache keeps closed daily segments for at most seven days or 256 MiB per account and reports an explicit gap when a requested sequence has retired.
+For a local view, `catalyst replica status` checks the writer, heartbeat and cursor. It exits `0` for fresh, `1` for present but stale, `2` for not connected, `3` for absent. `replica status --probe` compares its cursor with the cloud head. These diagnostics do not change the default read source, and an absent replica does not make `catalyst ready` fail.
+
+`catalyst events tail`, `wait-for`, `query` and `status` read from the cloud by default, with no local file. `events tail` prints one JSON line per new event and stays in the foreground; `events wait-for --ticket ... --timeout ...` prints the first match and exits 0, or exits 1 when none arrives in time; `events query` reads one page of filtered history (`--ticket`, `--type`, `--limit` up to 200, `--order desc|asc`, `--before`, `--after`); `events status` names the cloud head. Add `--from-cache` to read this machine's local event cache instead, which pays off when several agents on one machine share one cloud connection. `catalyst events status --from-cache --probe` checks the cache's own cursor against the cloud head; `replica status --probe` checks the separate entity-replica cursor. A fresh replica does not prove event freshness. The replica process is the single writer and reports an event-sync failure without terminating a healthy entity replica. The event cache keeps closed daily segments for at most seven days or 256 MiB per account and reports an explicit gap when a requested sequence has retired.
 
 The replica is a Node process, not a service: the supported path is the plain command, and `skills/catalyst-onboard/references/local-sync.md` gives launchd and systemd examples for people who want the writer to survive a reboot.
 
@@ -170,7 +172,7 @@ The replica is a Node process, not a service: the supported path is the plain co
 | `whats-happening` | "What's happening? Why is that stuck? How does this work? How does it prioritise?" | The desk for your account: reads the contract, what is running and queued, the eligibility explainer, the coding accounts and the open asks, and answers in one reply with ticket ids. Carries the facts behind the answers: the ladder, the stage map, failures, parks and holds, the queue order and every reason a ticket is excluded. Routes work to a project owner and decisions to `what-needs-me`. | [`SKILL.md`](skills/whats-happening/SKILL.md) |
 | `what-needs-me` | "What needs me? What am I blocking?" | The human's decision inbox, ranked by how much open work each ask holds, and the one way an agent raises a decision on their behalf: files an ask through the cloud's ask route with the account's own template and records the answer so the held work releases. | [`SKILL.md`](skills/what-needs-me/SKILL.md) |
 | `run-this-project` | "Run this project for me. Own it until it closes." | Single-threaded owner of one project: subscribes to the account's event stream for its scope, 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. Never polls. | [`SKILL.md`](skills/run-this-project/SKILL.md) |
-| `catalyst-linear` | "Show me the ticket, the history, what Catalyst wrote on it." | Reads a ticket with its comments, relations, labels, linked pull requests and agent sessions inline, from the replica when fresh and the API otherwise, always naming the source; writes comments, card moves, labels and new tickets as the app actor; knows what a ticket accumulates as Catalyst works it. | [`SKILL.md`](skills/catalyst-linear/SKILL.md) |
+| `catalyst-linear` | "Show me the ticket, the history, what Catalyst wrote on it." | Reads a ticket with its comments, relations, labels, linked pull requests and agent sessions inline, from the cloud API by default, with explicit local opt-in and the source named; writes comments, card moves, labels and new tickets as the app actor; knows what a ticket accumulates as Catalyst works it. | [`SKILL.md`](skills/catalyst-linear/SKILL.md) |
 | `catalyst-github` | "Show me the PR, the checks, the review, the queue." | A ticket's pull request with its checks, reviews and review threads; whether it is mergeable under the repository's policy; what a PR accumulates as the ticket moves (the branch, the draft, the rewrite, the force-pushes, the labels, the queue). | [`SKILL.md`](skills/catalyst-github/SKILL.md) |
 | `unstick` | "Why is this parked? Unpark it. Get things flowing again." | Reads why a ticket is not running and every park or hold on it, decides whether the recorded cause is fixed, previews the release and releases it the right way from your own login — or one failure class across a team — and raises an ask only for what a person has to do. | [`SKILL.md`](skills/unstick/SKILL.md) |
 | `what-this-repo-needs` | "What env vars does this repo need? What belongs in its environment declaration?" | Scans a repository offline — no login, no network — and lists the environment variable names it needs, grouped build/test, deploy-only and bindings, each with where it was found, what uses it, and where a local value would come from. Never reads or prints a value. Also checks TOML syntax and the environment variable table in `.catalyst/catalyst.toml`. | [`SKILL.md`](skills/what-this-repo-needs/SKILL.md) |

package/dist/args.js

@@ -41,13 +41,29 @@ export const FLAG_TABLES = {
     },
     install: {},
     onboard: {
-        team: { value: true, help: "explicitly select an existing Linear team by ID or unique key" },
-        repo: { value: true, repeat: true, help: "explicitly select an accessible repository as owner/name (repeatable)" },
-        "local-sync": { value: false, help: "include the optional local sync setup in this plan" },
-        "resume-from": { value: true, help: "resume at a verified onboarding step" },
+        team: {
+            value: true,
+            help: "explicitly select an existing Linear team by ID or unique key",
+        },
+        repo: {
+            value: true,
+            repeat: true,
+            help: "explicitly select an accessible repository as owner/name (repeatable)",
+        },
+        "local-sync": {
+            value: false,
+            help: "include the optional local sync setup in this plan",
+        },
+        "resume-from": {
+            value: true,
+            help: "resume at a verified onboarding step",
+        },
         only: { value: true, help: "run only the named onboarding step" },
         yes: { value: false, help: "accept the plan's default choices" },
-        "dry-run": { value: false, help: "print the plan without taking the lock or changing files" },
+        "dry-run": {
+            value: false,
+            help: "print the plan without taking the lock or changing files",
+        },
     },
     status: {},
     notice: {},
@@ -67,7 +83,7 @@ export const FLAG_TABLES = {
         since: { value: true, help: "changes: the cursor to read after" },
         source: {
             value: true,
-            help: "replica | api (default: replica when fresh, else api)",
+            help: "replica | api (default: api; replica is an explicit local opt-in)",
         },
         ticket: { value: true, help: "pulls: only PRs linked to this ticket" },
         all: {
@@ -91,27 +107,39 @@ export const FLAG_TABLES = {
         },
     },
     events: {
+        "from-cache": {
+            value: false,
+            help: "read the local event cache instead of the cloud (opt-in local sync)",
+        },
         probe: {
             value: false,
-            help: "status: compare the local event cursor with the cloud event head",
+            help: "status --from-cache: compare the local event cursor with the cloud event head",
         },
         type: { value: true, help: "exact event type" },
         ticket: {
             value: true,
-            help: "ticket identifier found in the event payload",
+            help: "ticket identifier found in the event",
         },
         after: {
             value: true,
-            help: "event sequence to read after (tail/wait default to local head)",
+            help: "event sequence to read after (tail and wait-for default to new events only)",
+        },
+        before: {
+            value: true,
+            help: "query: event sequence to read before (newest-first paging)",
+        },
+        order: { value: true, help: "query: desc (newest first, default) or asc" },
+        limit: {
+            value: true,
+            help: "query: maximum matching events (default 50; at most 200 from the cloud)",
         },
-        limit: { value: true, help: "query: maximum matching events (default 50)" },
         timeout: {
             value: true,
             help: "wait-for: bounded wait in seconds (default 300)",
         },
         directory: {
             value: true,
-            help: "event cache directory (default: SDK XDG path)",
+            help: "with --from-cache: event cache directory (default: SDK XDG path)",
         },
     },
     explain: {
@@ -235,8 +263,14 @@ export const FLAG_TABLES = {
         role: { value: true, help: "accept: the role recording the answer" },
     },
     ready: {
-        onboarding: { value: false, help: "check current onboarding evidence and observed project work" },
-        "local-sync": { value: false, help: "include the selected local sync mode" },
+        onboarding: {
+            value: false,
+            help: "check current onboarding evidence and observed project work",
+        },
+        "local-sync": {
+            value: false,
+            help: "include the selected local sync mode",
+        },
         offline: {
             value: false,
             help: "skip the published-release check (no network)",
@@ -244,13 +278,29 @@ export const FLAG_TABLES = {
     },
     accounts: {},
     env: {
-        root: { value: true, help: "draft: repository directory (default: current directory)" },
-        write: { value: false, help: "draft: write a new .catalyst/catalyst.toml; refuse to overwrite" },
-        diff: { value: false, help: "draft: show the generated TOML as an additions-only diff" },
+        root: {
+            value: true,
+            help: "draft: repository directory (default: current directory)",
+        },
+        write: {
+            value: false,
+            help: "draft: write a new .catalyst/catalyst.toml; refuse to overwrite",
+        },
+        diff: {
+            value: false,
+            help: "draft: show the generated TOML as an additions-only diff",
+        },
     },
     var: {
-        repo: { value: true, help: "repository scope (owner/name); omit for tenant scope" },
-        names: { value: true, repeat: true, help: "import: only send these names (repeatable or comma-separated)" },
+        repo: {
+            value: true,
+            help: "repository scope (owner/name); omit for tenant scope",
+        },
+        names: {
+            value: true,
+            repeat: true,
+            help: "import: only send these names (repeatable or comma-separated)",
+        },
     },
     team: {
         all: { value: false, help: "check every team, one request at a time" },

package/dist/browser.js

@@ -3,12 +3,15 @@
 // this never throws into the login flow — the caller wraps it, and a spawn failure is swallowed here.
 import { spawn } from "node:child_process";
 /** The platform's "open this URL" command. `open` on macOS, `start` via cmd on Windows, else xdg-open. */
-export function openBrowser(url) {
-    const [cmd, args] = process.platform === "darwin"
+function opener(url, platform = process.platform) {
+    return platform === "darwin"
         ? ["open", [url]]
-        : process.platform === "win32"
+        : platform === "win32"
             ? ["cmd", ["/c", "start", "", url]]
             : ["xdg-open", [url]];
+}
+export function openBrowser(url) {
+    const [cmd, args] = opener(url);
     try {
         const child = spawn(cmd, [...args], { stdio: "ignore", detached: true });
         child.on("error", () => { }); // no opener installed — the printed URL is the fallback
@@ -18,3 +21,34 @@ export function openBrowser(url) {
         // spawn itself threw (unusual) — the code and URL on screen are the fallback
     }
 }
+/** Login's opener: rejects when no opener ran (none installed, or it exited non-zero, as xdg-open does
+ *  with no browser), so login claims an opened browser only when one did. An opener still running
+ *  after `waitMs` launched something and counts as opened. */
+export function openBrowserChecked(url, options = {}) {
+    const [cmd, args] = opener(url, options.platform);
+    const launch = options.launch ??
+        ((command, list) => spawn(command, [...list], { stdio: "ignore", detached: true }));
+    return new Promise((resolve, reject) => {
+        const fail = () => reject(new Error("browser-unavailable"));
+        let child;
+        try {
+            child = launch(cmd, args);
+        }
+        catch {
+            return fail();
+        }
+        child.unref();
+        const timer = setTimeout(resolve, options.waitMs ?? 3_000);
+        child.once("error", () => {
+            clearTimeout(timer);
+            fail();
+        });
+        child.once("exit", (code) => {
+            clearTimeout(timer);
+            if (code === 0)
+                resolve();
+            else
+                fail();
+        });
+    });
+}

package/dist/cli.js

@@ -8,13 +8,14 @@ import { loadContract, pickPath } from "./contract.js";
 import { CliError, MeError, UsageError } from "./errors.js";
 import { fetchMe } from "./transport.js";
 import { bearerFor, deviceFlowLogin } from "./oauth.js";
-import { openBrowser as defaultOpenBrowser } from "./browser.js";
+import { openBrowserChecked as defaultOpenBrowser } from "./browser.js";
 import { cmdAccounts, cmdExplain, cmdHistory, cmdQueue, cmdRunning, } from "./execution.js";
 import { cmdQuery } from "./query.js";
 import { cmdReady } from "./ready.js";
 import { cmdReplica } from "./replica.js";
 import { cmdRuntime } from "./runtime-verb.js";
 import { cmdEvents } from "./events.js";
+import { stageOnboardLogin } from "./onboard-login-candidate.js";
 import { stdinIsTty } from "./prompt.js";
 import { FIRST_STAMPED_VERSION, PROVENANCE_MARKER, parseProvenanceVersion, } from "./skill-shape.js";
 import { installedBundleVersion, installSkills, parseChangelogEntry, readChangelog, resolveSkillsDir, skillsSourceDir, updateNoticeLine, } from "./skills.js";
@@ -35,9 +36,10 @@ import { cmdLegacy } from "./legacy.js";
 import { cmdIdentity } from "./identity.js";
 import { cmdConnections } from "./connections.js";
 import { cmdOnboard, onboardErrorJournal } from "./onboard.js";
-import { createClackOnboardUi, shouldUseOnboardUi } from "./onboard-ui.js";
+import { createClackOnboardUi, shouldUseOnboardUi, } from "./onboard-ui.js";
 import { createOnboardRuntime } from "./onboard-runtime.js";
-import { onboardingReadyReport, observeCloudOnboarding } from "./onboard-ready.js";
+import { savedOnboardBaseUrl } from "./onboard-next.js";
+import { onboardingReadyReport, observeCloudOnboarding, } from "./onboard-ready.js";
 import { selectedOnboardTeam } from "./onboard-existing.js";
 export { CONFIG_MODE, DEFAULT_BASE_URL, FIRST_STAMPED_VERSION, LEGACY_PACKAGE_NAME, PACKAGE_NAME, PROVENANCE_MARKER, CliError, MeError, UsageError, configPathFor, contractPathFor, defaultCtx, defaultReplicaDbFor, defaultSkillsDirFor, fetchMe, formatMode, installedBundleVersion, installSkills, loadConfig, modernCliPath, normalizeBaseUrl, parseArgs, parseChangelogEntry, parseProvenanceVersion, readChangelog, readManifest, resolveSkillsDir, saveConfig, skillsSourceDir, updateNoticeLine, writeConfig, };
 export const CUSTOMER_SKILLS = [
@@ -71,7 +73,7 @@ export function usageText() {
         "  catalyst query <issues|issue <id>|pulls|pull <id>|projects|cycles|search <terms>|changes --since <cursor|head>>",
         '  catalyst replica <start [--detach]|stop|status [--probe]|sql "<select>"|schema [table]>',
         "  catalyst runtime <status [--json]|install|path|uninstall>   (a pinned Node this CLI manages itself)",
-        "  catalyst events <tail|wait-for|query|status [--probe]> [--type NAME] [--ticket CTC-N] [--after SEQUENCE]",
+        "  catalyst events <tail|wait-for|query|status> [--type NAME] [--ticket CTC-N] [--after SEQUENCE] [--from-cache]",
         "  catalyst explain <ticket> | history <ticket> | running [--ticket T --phase P] | queue [--team K]",
         "  catalyst watch [--team K] [--ticket T]... [--project P] [--exec CMD]",
         "  catalyst write <comment|state|label|create|reaction|attachment|session> ...",
@@ -252,7 +254,7 @@ export async function main(argv, ctx = defaultCtx(), deps = {}) {
                     }
                     if (input.isTTY) {
                         try {
-                            ui = createClackOnboardUi(await import("@clack/prompts"), { input, output: process.stdout });
+                            ui = createClackOnboardUi(await import("@clack/prompts"), { input, output: process.stdout }, { baseUrl: () => savedOnboardBaseUrl(ctx.home) });
                         }
                         catch (error) {
                             terminal?.destroy();
@@ -265,23 +267,64 @@ export async function main(argv, ctx = defaultCtx(), deps = {}) {
                         ...createOnboardRuntime(args, ctx, {
                             ui,
                             signinTimeoutMs: deps.onboardSigninTimeoutMs,
+                            stageSignin: (signal) => {
+                                if (args.key || ctx.env.CATALYST_CLOUD_TOKEN)
+                                    throw new CliError("Connect your personal key with catalyst login, then run catalyst onboard. Setup will not replace a supplied key with browser sign-in.", "onboard-person-required", 12);
+                                return stageOnboardLogin({ ...ctx, stdout: ctx.stderr }, {
+                                    baseUrl: args.baseUrl,
+                                    signal,
+                                    timeoutMs: deps.onboardSigninTimeoutMs,
+                                    device: {
+                                        isTty: deps.isTty ?? (() => Boolean(process.stdout.isTTY)),
+                                        openBrowser: deps.openBrowser ?? defaultOpenBrowser,
+                                        sleep: deps.sleep,
+                                        waitForApproval: ui
+                                            ? (run) => ui.wait("Waiting for Catalyst approval", run)
+                                            : undefined,
+                                    },
+                                });
+                            },
                             login: (stepCtx, signal) => cmdLogin({ ...args, command: "login", flags: {}, json: false }, stepCtx, {
-                                ...deps, signal, isTty: () => true,
-                                waitForApproval: ui ? run => ui.wait("Waiting for Catalyst approval", run) : undefined,
+                                ...deps,
+                                signal,
+                                isTty: () => true,
+                                waitForApproval: ui
+                                    ? (run) => ui.wait("Waiting for Catalyst approval", run)
+                                    : undefined,
                             }, true),
                             ready: async (stepCtx, journal) => {
                                 const team = selectedOnboardTeam(journal);
-                                const report = await onboardingReadyReport(stepCtx, { teamIds: team ? [team] : undefined, localSync: journal?.localSync ?? args.flags["local-sync"] === true, observe: observeCloudOnboarding });
-                                const failed = report.checks.some(check => check.required && check.state === "fail");
-                                return { state: report.state === "complete" ? "done" : failed ? "failed" : "waiting", reason: report.state === "complete" ? undefined : "onboarding_checks_pending",
-                                    evidence: { checks: report.checks.length, passed: report.checks.filter(check => check.state === "pass").length } };
+                                const report = await onboardingReadyReport(stepCtx, {
+                                    teamIds: team ? [team] : undefined,
+                                    localSync: journal?.localSync ?? args.flags["local-sync"] === true,
+                                    observe: observeCloudOnboarding,
+                                });
+                                const failed = report.checks.some((check) => check.required && check.state === "fail");
+                                return {
+                                    state: report.state === "complete"
+                                        ? "done"
+                                        : failed
+                                            ? "failed"
+                                            : "waiting",
+                                    reason: report.state === "complete"
+                                        ? undefined
+                                        : "onboarding_checks_pending",
+                                    evidence: {
+                                        checks: report.checks.length,
+                                        passed: report.checks.filter((check) => check.state === "pass").length,
+                                    },
+                                };
                             },
                             legacy: deps.legacy,
                             openBrowser: deps.openBrowser,
                             sleep: deps.sleep,
                             skillNames: CUSTOMER_SKILLS,
                         }),
+                        ...(deps.onboardBootstrap
+                            ? { bootstrap: deps.onboardBootstrap }
+                            : {}),
                         ...(deps.isTty ? { isTty: deps.isTty } : {}),
+                        ...(deps.signal ? { signal: deps.signal } : {}),
                     }, readManifest().version);
                 }
                 finally {
@@ -485,7 +528,10 @@ async function cmdLogin(args, ctx, deps, personalOnly = false) {
         : ` — expected ${formatMode(CONFIG_MODE)}; chmod it by hand`}`);
     ctx.stdout(`Tenant contract range: ${manifest.tenantContractRange}`);
     try {
-        const loaded = await loadContract(ctx, config, { refresh: true, signal: deps.signal });
+        const loaded = await loadContract(ctx, config, {
+            refresh: true,
+            signal: deps.signal,
+        });
         checkCancelled();
         ctx.stdout(`Tenant contract ${loaded.doc.contractVersion} cached at ${loaded.path}`);
     }

package/dist/config.js

@@ -1,5 +1,3 @@
-// config.ts — ~/.config/catalyst-cloud/customer.json and its siblings. The ONLY place the base URL
-// and the `/api/v1` prefix are joined: the SDK wants the base with the prefix, GET /me without.
 import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { randomBytes } from "node:crypto";
 import { dirname, join } from "node:path";
@@ -22,6 +20,7 @@ export function defaultCtx() {
         env: process.env,
         home: process.env.CATALYST_SKILLS_HOME ?? process.env.HOME ?? "/",
         stdout: (line) => console.log(line),
+        stdoutStream: process.stdout,
         stderr: (line) => console.error(line),
         fetch: fetch,
         now: () => new Date(),
@@ -144,12 +143,25 @@ function machineFilePresent(file) {
         throw error;
     }
 }
+/** The machine paths record, or null on a machine that has not run paths setup. */
+function declaredMachinePaths(home, env) {
+    const file = machinePathsFile({ env: { ...env, HOME: home } });
+    if (!file || (env.CATALYST_PATHS_FILE === undefined && !machineFilePresent(file)))
+        return null;
+    return parseMachinePaths(JSON.parse(readFileSync(file, "utf8")));
+}
+/** True only when this machine opted in to the local replica: CATALYST_REPLICA_DB is set, or the
+ *  machine paths file declares replicaDb. Every other machine reads the cloud (CTC-4508). */
+export function replicaOptedIn(home, env = {}) {
+    if (env.CATALYST_REPLICA_DB !== undefined)
+        return true;
+    return declaredMachinePaths(home, env)?.paths.replicaDb !== undefined;
+}
 export function replicaDbPath(cfg, home, env = {}) {
     if (env.CATALYST_REPLICA_DB !== undefined)
         return resolveCatalystPath("replicaDb", { env });
-    const file = machinePathsFile({ env: { ...env, HOME: home } });
-    if (file && (env.CATALYST_PATHS_FILE !== undefined || machineFilePresent(file))) {
-        const machine = parseMachinePaths(JSON.parse(readFileSync(file, "utf8")));
+    const machine = declaredMachinePaths(home, env);
+    if (machine) {
         if (machine.paths.replicaDb === undefined)
             throw new CliError("optional replica is not configured; set CATALYST_REPLICA_DB or declare replicaDb in the machine paths file", "replica-not-configured");
         return resolveCatalystPath("replicaDb", { env, machine });

package/dist/consent-browser.js

@@ -0,0 +1,58 @@
+import { spawn } from "node:child_process";
+/** Consent links are credentials. Keep them out of errors and join the opener before continuing. */
+export function createConsentBrowserOpener(options = {}) {
+    const platform = options.platform ?? process.platform;
+    const timeoutMs = options.timeoutMs ?? 5_000;
+    const killGraceMs = options.killGraceMs ?? 500;
+    const launch = options.launch ?? ((command, args) => spawn(command, [...args], { stdio: "ignore", detached: false }));
+    return async (url, signal) => {
+        if (signal?.aborted)
+            throw new DOMException("Browser opening interrupted", "AbortError");
+        const [command, args] = platform === "darwin"
+            ? ["open", [url]]
+            : platform === "win32"
+                ? ["cmd", ["/c", "start", "", url]]
+                : ["xdg-open", [url]];
+        let child;
+        try {
+            child = launch(command, args);
+        }
+        catch {
+            throw new Error("Browser could not open");
+        }
+        await new Promise((resolve, reject) => {
+            let interrupted = false;
+            let expired = false;
+            let failed = false;
+            let killTimer;
+            const stop = () => {
+                child.kill("SIGTERM");
+                killTimer ??= setTimeout(() => { child.kill("SIGKILL"); }, killGraceMs);
+            };
+            const abort = () => { interrupted = true; stop(); };
+            const timer = setTimeout(() => { expired = true; stop(); }, timeoutMs);
+            child.once("error", () => { failed = true; });
+            child.once("close", (code) => {
+                clearTimeout(timer);
+                if (killTimer)
+                    clearTimeout(killTimer);
+                signal?.removeEventListener("abort", abort);
+                if (interrupted)
+                    reject(new DOMException("Browser opening interrupted", "AbortError"));
+                else if (failed || expired || code !== 0)
+                    reject(new Error("Browser could not open"));
+                else
+                    resolve();
+            });
+            signal?.addEventListener("abort", abort, { once: true });
+            if (signal?.aborted)
+                abort();
+        });
+    };
+}
+export const openConsentBrowser = createConsentBrowserOpener();
+/** The web page that finishes a consent step when no browser opens here. The signed link stays private. */
+export function finishOnTheWeb(baseUrl, page, action) {
+    const origin = baseUrl.replace(/\/+$/, "");
+    return `No browser opened on this computer. In a browser signed in to Catalyst, open ${origin}/settings/${page} and ${action}. Setup keeps waiting here.`;
+}