@catalyst-cloud/cli 0.14.6 → 0.14.7

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 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
 
@@ -156,7 +156,9 @@ Nothing, by default. After `login`, every read, write, ask and explanation goes
 | `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 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.
+
+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 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.
 
@@ -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: {
@@ -235,8 +251,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 +266,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/cli.js

@@ -15,6 +15,7 @@ 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,9 @@ 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 { 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 = [
@@ -252,7 +253,10 @@ 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,
+                            });
                         }
                         catch (error) {
                             terminal?.destroy();
@@ -265,23 +269,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 +530,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

@@ -144,12 +144,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/daemon-authority-lifetime.js

@@ -0,0 +1,171 @@
+import { DaemonAuthorityError, readDaemonAuthority, } from "./daemon-authority.js";
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal.aborted) {
+            reject(signal.reason);
+            return;
+        }
+        const abort = () => {
+            clearTimeout(timer);
+            signal.removeEventListener("abort", abort);
+            reject(signal.reason);
+        };
+        const timer = setTimeout(() => {
+            signal.removeEventListener("abort", abort);
+            resolve();
+        }, ms);
+        signal.addEventListener("abort", abort, { once: true });
+    });
+}
+/** One joined task owns fresh /me renewal; no config refresh/write or token publication shortcut.
+ * An expired/changed proof aborts peers through onFailure before waiting for held reader cleanup. */
+export async function createDaemonAuthorityLifetime(ctx, parent) {
+    const owned = new AbortController(), lifetime = AbortSignal.any([parent, owned.signal]);
+    let proof = await readDaemonAuthority(ctx, lifetime);
+    const scope = proof.scope;
+    let running;
+    let fault;
+    let report;
+    let notice;
+    const failures = [];
+    const fail = (error) => {
+        if (fault)
+            return;
+        fault = error;
+        // Callback starts synchronously so the supervisor aborts both feeds before drain waits.
+        if (report) {
+            try {
+                notice = report(error.kind === "identity"
+                    ? "identity_mismatch"
+                    : "authentication_required");
+            }
+            catch (error) {
+                notice = Promise.reject(error);
+            }
+            void notice.catch(() => { });
+        }
+        owned.abort(error);
+    };
+    const assertCurrent = () => {
+        if (fault)
+            throw fault;
+        try {
+            proof.assertCurrent();
+        }
+        catch (error) {
+            if (error instanceof DaemonAuthorityError)
+                fail(error);
+            throw error;
+        }
+    };
+    return {
+        scope,
+        assertCurrent,
+        async getToken() {
+            assertCurrent();
+            const selected = proof;
+            try {
+                const token = await selected.getToken();
+                // Renewal may replace proof during the await; the returned bearer still needs its own
+                // ORIGINAL proof expiry, not the replacement's later authority window.
+                selected.assertCurrent();
+                assertCurrent();
+                return token;
+            }
+            catch (error) {
+                if (error instanceof DaemonAuthorityError)
+                    fail(error);
+                throw error;
+            }
+        },
+        run(signal, onFailure) {
+            if (running)
+                throw new Error("daemon_authority_already_running");
+            report = onFailure;
+            // An earlier synchronous cache guard may already have latched a fault before run starts.
+            if (fault && !notice) {
+                try {
+                    notice = report(fault.kind === "identity"
+                        ? "identity_mismatch"
+                        : "authentication_required");
+                }
+                catch (error) {
+                    notice = Promise.reject(error);
+                }
+                void notice.catch(() => { });
+            }
+            const active = AbortSignal.any([lifetime, signal]);
+            running = (async () => {
+                let timer;
+                const expire = () => {
+                    if (!active.aborted)
+                        fail(new DaemonAuthorityError("authentication", "daemon_authority_expired"));
+                };
+                const arm = () => {
+                    if (timer !== undefined)
+                        clearTimeout(timer);
+                    const remaining = proof.expiresAt - ctx.now().getTime();
+                    if (remaining <= 0) {
+                        expire();
+                        return;
+                    }
+                    timer = setTimeout(expire, remaining);
+                };
+                try {
+                    assertCurrent();
+                    arm();
+                    while (!active.aborted) {
+                        await sleep(10_000, active);
+                        if (active.aborted)
+                            break;
+                        // Old proof's timer stays armed throughout the read and its cleanup ACK.
+                        const fresh = await readDaemonAuthority(ctx, active);
+                        if (active.aborted)
+                            break;
+                        if (JSON.stringify(fresh.scope) !== JSON.stringify(scope))
+                            throw new DaemonAuthorityError("identity", "daemon_authority_changed");
+                        fresh.assertCurrent();
+                        proof = fresh;
+                        arm();
+                    }
+                }
+                catch (error) {
+                    if (error instanceof AggregateError) {
+                        if (!active.aborted) {
+                            const primary = error.errors[0];
+                            fail(primary instanceof DaemonAuthorityError
+                                ? primary
+                                : new DaemonAuthorityError("authentication", "daemon_authority_cleanup_failed"));
+                        }
+                        failures.push(error);
+                        throw error;
+                    }
+                    if (!active.aborted)
+                        fail(error instanceof DaemonAuthorityError
+                            ? error
+                            : new DaemonAuthorityError("authentication", "daemon_authority_unavailable"));
+                    // Only an actual parent/owned cancellation is an ordinary requested stop. The proof
+                    // failure callback persists its reason; no automatic restart renews that latch.
+                }
+                finally {
+                    if (timer !== undefined)
+                        clearTimeout(timer);
+                    if (notice)
+                        await notice;
+                }
+            })();
+            void running.catch((error) => {
+                if (!failures.includes(error))
+                    failures.push(error);
+            });
+            return running;
+        },
+        async stop() {
+            owned.abort(new Error("daemon_authority_stop"));
+            if (running)
+                await running.catch(() => { });
+            if (failures.length)
+                throw new AggregateError(failures, "daemon_authority_cleanup_failed");
+        },
+    };
+}