@catalyst-cloud/cli 0.16.25 → 0.16.27

package/dist/onboard-runner.js

@@ -8,7 +8,7 @@ import { runnerAdmission, issueRunnerOrgKey, verifyRunnerRoutes } from "./onboar
 import { verifyOnboardRoutes } from "./onboard-capabilities.js";
 import { liveTeamKey, onboardTeamAdmission } from "./onboard-capacity.js";
 import { runnerVmCapabilities } from "./onboard-runner-probes.js";
-import { darwinThoughtsInstallException, darwinThoughtsInstallRefusal, installDarwinThoughtsCustody } from "./onboard-runner-custody.js";
+import { darwinThoughtsInstallAdvice, darwinThoughtsInstallException, darwinThoughtsInstallRefusal, installDarwinThoughtsCustody } from "./onboard-runner-custody.js";
 import { emitCustodyFailure } from "./onboard-runner-telemetry.js";
 import { canonicalDarwinThoughtsJson, parseDarwinThoughtsAuthority } from "../vendor/self-host/darwin-thoughts-custody/verifier.mjs";
 import { readExistingOnboardJson, readOnboardTeamInventory, selectedOnboardTeam, } from "./onboard-existing.js";
@@ -1161,7 +1161,9 @@ export function onboardRunnerAdapter(input = {}) {
                     const custodyReason = darwinThoughtsInstallRefusal(error);
                     const failureCase = custodyReturned ? "result_unverified" : "call_threw";
                     const details = { ...darwinThoughtsInstallException(error), ...(custodyReason ? { custodyReason } : {}) };
-                    return refuseCustody(ctx, journal, failureCase, `Setup could not verify local storage: ${custodyReturned ? "recording the result failed" : "the native check threw"} (${details.custodyErrorClass}: ${details.custodyErrorMessage}).`, details, signal);
+                    const advice = darwinThoughtsInstallAdvice(error);
+                    return refuseCustody(ctx, journal, failureCase, `Setup could not verify local storage: ${custodyReturned ? "recording the result failed" : "the native check threw"} (${details.custodyErrorClass}: ${details.custodyErrorMessage}).` +
+                        (advice ? " " + advice : ""), details, signal);
                 }
             }
             if (!writeEnv(want))

package/dist/onboard-runtime.js

@@ -5,6 +5,8 @@ import { openConsentBrowser } from "./consent-browser.js";
 import { defaultSkillsDirFor, loadConfig, normalizeBaseUrl, readManifest, } from "./config.js";
 import { CliError, UsageError } from "./errors.js";
 import { cmdLegacy, findLegacy } from "./legacy.js";
+import { findLocalSyncData, localSyncInventory } from "./local-sync-data.js";
+import { replicaStatus } from "./replica.js";
 import { personalConsentAdapter } from "./onboard-personal.js";
 import { boundedOnboardSignin } from "./onboard-signin.js";
 import { existingLinearAdapters } from "./onboard-existing.js";
@@ -134,8 +136,14 @@ export function createOnboardRuntime(args, ctx, hooks) {
             },
         };
     };
-    const legacyCheck = async (stepCtx) => {
-        const found = findLegacy(stepCtx.home, hooks.legacy?.platform ?? process.platform).filter((item) => !item.data).length;
+    const legacyDeps = (journal) => ({
+        ...hooks.legacy,
+        preserveReplica: journal?.localSync ?? args.flags["local-sync"] === true,
+    });
+    const legacyCheck = async (stepCtx, journal) => {
+        const services = findLegacy(stepCtx.home, hooks.legacy?.platform ?? process.platform, legacyDeps(journal)).filter((item) => !item.data);
+        const files = legacyDeps(journal).preserveReplica ? [] : await findLocalSyncData(stepCtx);
+        const found = services.length + files.length;
         if (!sameHome(stepCtx.home, (hooks.realHome ?? (() => userInfo().homedir))()))
             return {
                 state: "skipped",
@@ -218,10 +226,40 @@ export function createOnboardRuntime(args, ctx, hooks) {
         },
         legacy: {
             check: legacyCheck,
-            act: async (stepCtx) => {
-                const before = await legacyCheck(stepCtx);
+            act: async (stepCtx, journal) => {
+                const before = await legacyCheck(stepCtx, journal);
                 if (before.state !== "pending")
                     return before;
+                const options = legacyDeps(journal);
+                const files = options.preserveReplica ? [] : await findLocalSyncData(stepCtx);
+                const writers = findLegacy(stepCtx.home, options.platform ?? process.platform, options)
+                    .filter((item) => item.kind === "job" && item.localSync);
+                if (files.length || writers.length) {
+                    const inventory = [
+                        ...writers.map((writer) => `${writer.path} (${writer.size} bytes)`),
+                        ...localSyncInventory(files),
+                    ];
+                    const show = (lines) => {
+                        if (hooks.ui?.showLocalSyncInventory)
+                            hooks.ui.showLocalSyncInventory(lines);
+                        else
+                            for (const line of lines)
+                                hooks.ui ? hooks.ui.message(line) : stepCtx.stderr(line);
+                    };
+                    show(["Existing local sync files:", ...inventory]);
+                    if (args.flags["remove-local-data"] !== true) {
+                        if (!interactiveWait || (!options.prompt && !hooks.ui?.confirmLocalSyncRemoval)) {
+                            const line = "Local data kept. Run catalyst setup --remove-local-data to stop the writer and remove the listed files.";
+                            show([line]);
+                            return { state: "waiting", reason: "local_sync_cleanup_confirmation_required", evidence: { files: inventory.join("\n"), requiredFlag: "--remove-local-data" } };
+                        }
+                        const accepted = options.prompt
+                            ? /^(y|yes)$/i.test((await options.prompt("Stop the local writer and delete the listed local sync files, keeping login, contract and settings? [y/N] ")).trim())
+                            : await hooks.ui.confirmLocalSyncRemoval();
+                        if (!accepted)
+                            return waiting("local_sync_cleanup_declined");
+                    }
+                }
                 // Provider/process output is not trusted to be secret-free; keep it out of the receipt/log.
                 const quiet = { ...stepCtx, stdout: () => { }, stderr: () => { } };
                 const code = await cmdLegacy({
@@ -229,11 +267,11 @@ export function createOnboardRuntime(args, ctx, hooks) {
                     command: "legacy",
                     subcommand: null,
                     rest: [],
-                    flags: { remove: true, yes: true },
+                    flags: { remove: true, data: !options.preserveReplica, yes: true },
                     json: false,
-                }, quiet, hooks.legacy);
+                }, quiet, { ...options, localSyncFiles: files });
                 return code === 0
-                    ? legacyCheck(stepCtx)
+                    ? legacyCheck(stepCtx, journal)
                     : { state: "failed", reason: "legacy_cleanup_failed" };
             },
         },
@@ -350,13 +388,14 @@ export function createOnboardRuntime(args, ctx, hooks) {
         "linear.personal": personalAdapter("linear"),
         "github.personal": personalAdapter("github"),
         daemon: {
-            check: async (_stepCtx, journal) => (journal.localSync ?? args.flags["local-sync"] === true)
-                ? waiting("local_sync_capability_unavailable")
-                : {
-                    state: "skipped",
-                    reason: "local_sync_not_selected",
-                    evidence: { provider: "cloud" },
-                },
+            check: async (stepCtx, journal) => {
+                if (!(journal.localSync ?? args.flags["local-sync"] === true))
+                    return { state: "skipped", reason: "local_sync_not_selected", evidence: { provider: "cloud" } };
+                const status = replicaStatus(stepCtx, loadConfig(stepCtx.home));
+                return status.verdict === "fresh"
+                    ? { state: "done", evidence: { provider: "existing_replica", path: status.dbPath, cursor: status.cursor } }
+                    : waiting("local_sync_capability_unavailable");
+            },
         },
         housekeeping: onboardHousekeepingAdapter(hooks.scheduler),
         // CTC-4744: a settings read the cloud has not finished is waited on here, on one line.

package/dist/onboard-ui.js

@@ -402,6 +402,35 @@ export function createClackOnboardUi(prompts, streams, deps = {}) {
             message("Use cloud reads by default. Local sync is optional for SQL or sustained local reads.");
             message("Setup reads your AI accounts without sending them a request.");
         },
+        showLocalSyncInventory(lines) {
+            stop();
+            for (const line of lines)
+                if (renderer)
+                    renderer.detail(line);
+                else
+                    prompts.log.message(line, { output: streams.output });
+        },
+        async confirmLocalSyncRemoval() {
+            stop();
+            if (abort.signal.aborted || !interactive)
+                return false;
+            if (renderer)
+                question();
+            const answer = await select({
+                ...options,
+                message: "Stop the local writer and delete the listed files? Login, contract and settings are kept.",
+                initialValue: "keep",
+                options: [
+                    { value: "remove", label: "Yes, remove the listed local sync files" },
+                    { value: "keep", label: "No, keep them" },
+                ],
+            });
+            if (prompts.isCancel(answer)) {
+                abort.abort();
+                return false;
+            }
+            return answer === "remove";
+        },
         async confirmPlan(localSync, signin = "unavailable") {
             if (deps.consentGiven || !interactive)
                 return { proceed: true, localSync };

package/dist/replica.js

@@ -253,6 +253,11 @@ export async function engineFor(sdk, dbPath, ctx, deps = {}) {
         return deps.readonly ? sdk.nodeSqliteReadonlyEngine(dbPath) : sdk.nodeSqliteEngine(dbPath);
     }
 }
+/** How long a snapshot pull may go with no progress before the SDK aborts it (CTC-6569). The mirror
+ *  can spend up to 120 s preparing a large workspace's snapshot before its first byte, and the SDK's
+ *  old 30 s default aborted nearly every such pull, so the replica never synced. host-sync and the web
+ *  app pass the same 150 s. Still an idle bound: it re-arms on every chunk. */
+export const SNAPSHOT_IDLE_TIMEOUT_MS = 150_000;
 export const SNAPSHOT_BASE_BACKOFF_MS = 30_000;
 export const SNAPSHOT_MAX_BACKOFF_MS = 900_000; // 15 minutes
 export const SNAPSHOT_MAX_FAILURES = 5;
@@ -354,7 +359,7 @@ async function cmdStart(args, ctx, cfg, dbPath, deps) {
         ctx.stdout(`replica writer started in the background (pid ${pid}, db ${dbPath}); check with: catalyst replica status`);
         return 0;
     }
-    const sdk = await loadSdk();
+    const sdk = await (deps.loadSdk ?? loadSdk)();
     const sleep = deps.sleep ?? defaultSleep;
     const random = deps.random ?? Math.random;
     const baseMs = deps.snapshotRetry?.baseBackoffMs ?? SNAPSHOT_BASE_BACKOFF_MS;
@@ -404,6 +409,7 @@ async function cmdStart(args, ctx, cfg, dbPath, deps) {
             engine,
             fetchImpl: ctx.fetch,
             wsFactory: deps.wsFactory,
+            snapshotIdleTimeoutMs: deps.snapshotIdleTimeoutMs ?? SNAPSHOT_IDLE_TIMEOUT_MS,
             log: (level, msg, extra) => ctx.stderr(`[replica ${level}] ${msg}${extra ? ` ${safeJson(extra)}` : ""}`),
             onStatus: (s) => {
                 ctx.stderr(`[replica] status=${s}`);

package/dist/repo-status.js

@@ -0,0 +1,156 @@
+// Repository lifecycle commands use the key routes under /api/v1/agent/repos, independent of local checkouts.
+import { flagString, positionals } from "./args.js";
+import { requireConfig } from "./config.js";
+import { MeError, UsageError } from "./errors.js";
+import { apiClient } from "./transport.js";
+const LIST_ROUTE = "/api/v1/agent/repos";
+function object(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function text(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+function repository(value) {
+    return object(value) && text(value.id) && text(value.owner) && text(value.name) && text(value.status);
+}
+function decodeList(value) {
+    if (!object(value) || !Array.isArray(value.repositories) || !value.repositories.every(repository) || typeof value.canManage !== "boolean") {
+        throw new MeError(`GET ${LIST_ROUTE} returned an unexpected repository list shape`, "shape");
+    }
+    return { ...value, repositories: value.repositories, canManage: value.canManage };
+}
+function elapsedTime(value, now) {
+    if (typeof value !== "string" && typeof value !== "number")
+        return undefined;
+    const timestamp = new Date(value).getTime();
+    if (!Number.isFinite(timestamp))
+        return undefined;
+    const minutes = Math.max(0, Math.floor((now.getTime() - timestamp) / 60_000));
+    if (minutes === 0)
+        return "just now";
+    const [amount, unit] = minutes < 60 ? [minutes, "minute"] : minutes < 1440 ? [Math.floor(minutes / 60), "hour"] : [Math.floor(minutes / 1440), "day"];
+    return `${amount} ${unit}${amount === 1 ? "" : "s"} ago`;
+}
+function renderRow(row, ctx) {
+    let state = row.status;
+    if (state === "paused") {
+        const actor = text(row.pausedBy) ? row.pausedBy : object(row.pausedBy)
+            ? [row.pausedBy.email, row.pausedBy.actor, row.pausedBy.name, row.pausedBy.label].find(text) ?? "an operator"
+            : "an operator";
+        const time = elapsedTime(row.pausedAt, ctx.now());
+        state += ` by ${actor}${time ? ` ${time}` : ""}${text(row.pauseReason) ? `: ${row.pauseReason}` : ""}`;
+    }
+    ctx.stdout(`${row.owner}/${row.name}: ${state}`);
+    const projects = Array.isArray(row.projects) ? row.projects.filter(object).filter((p) => text(p.name)).map((p) => `${p.name}${text(p.teamKey) ? ` (${p.teamKey})` : ""}`) : [];
+    ctx.stdout(`  projects: ${projects.length ? projects.join(", ") : "none"}`);
+}
+function refuse(args, ctx, message, status, body = {}) {
+    if (args.json)
+        ctx.stdout(JSON.stringify({ ...(object(body) ? body : {}), ...(status === undefined ? {} : { status }), message }));
+    else
+        ctx.stdout(`refused${status === undefined ? "" : ` (${status})`}: ${message}`);
+    return 1;
+}
+function serverDetail(body) {
+    if (!object(body))
+        return "";
+    const details = [body.error, body.code, body.message, body.reason].filter(text);
+    return details.length ? ` (${[...new Set(details)].join(": ")})` : "";
+}
+export async function cmdRepoStatus(args, ctx) {
+    const [action, wanted, ...extra] = positionals(args);
+    if (action !== "status" && action !== "pause" && action !== "resume")
+        throw new UsageError("repo needs status, pause or resume");
+    if (["write", "apply", "with-check"].some((flag) => args.flags[flag] !== undefined)) {
+        throw new UsageError(`repo ${action} does not take local write flags`);
+    }
+    const rawReason = flagString(args, "reason");
+    const reason = rawReason?.trim();
+    if (action === "status") {
+        if (wanted !== undefined || extra.length || rawReason !== undefined)
+            throw new UsageError("repo status takes no arguments or --reason");
+    }
+    else {
+        if (!wanted || !/^[A-Za-z0-9][A-Za-z0-9-]*\/[A-Za-z0-9_.-]+$/.test(wanted) || extra.length) {
+            throw new UsageError(`repo ${action} needs one repository as owner/name`);
+        }
+        if (action === "pause" && reason === undefined)
+            throw new UsageError("repo pause needs --reason with 1 to 500 characters");
+        if (reason !== undefined && (reason.length === 0 || reason.length > 500))
+            throw new UsageError("--reason must contain 1 to 500 characters after trimming");
+    }
+    const cfg = requireConfig(ctx);
+    const client = apiClient(cfg, ctx);
+    const accept = [400, 403, 404, 409];
+    const response = await client.getJson(LIST_ROUTE, { accept, parseAccepted: true });
+    if (response.status >= 400) {
+        const message = response.status === 404
+            ? "this Catalyst Cloud does not serve repository status yet (needs a newer cloud)"
+            : response.status === 403 ? "your login cannot read repository status" : "repository status request failed";
+        return refuse(args, ctx, message + serverDetail(response.body), response.status, response.body);
+    }
+    const result = decodeList(response.body);
+    const role = cfg.user?.role ? `; your role is ${cfg.user.role}` : "";
+    if (action === "status") {
+        if (args.json)
+            ctx.stdout(JSON.stringify(result));
+        else {
+            for (const row of result.repositories)
+                renderRow(row, ctx);
+            if (result.repositories.length === 0)
+                ctx.stdout("No repositories are visible to your login.");
+            ctx.stdout(result.canManage
+                ? "You can pause or resume repositories as a workspace owner or admin."
+                : `Pause or resume requires a workspace owner or admin${role}.`);
+        }
+        return 0;
+    }
+    const roleRefusal = `pausing or resuming a repository requires a workspace owner or admin${role}`;
+    if (!result.canManage)
+        return refuse(args, ctx, roleRefusal, 403, { error: "forbidden" });
+    const matches = result.repositories.filter((row) => `${row.owner}/${row.name}`.toLowerCase() === wanted?.toLowerCase());
+    const selected = matches[0];
+    if (!selected)
+        return refuse(args, ctx, `no repository ${wanted} is visible to your login; check catalyst repo status`, undefined, { error: "repository-not-visible" });
+    if (matches.length !== 1)
+        return refuse(args, ctx, `repository ${wanted} is ambiguous; check catalyst repo status`, undefined, { error: "repository-ambiguous" });
+    if (selected.status === "archived")
+        return refuse(args, ctx, `${wanted} is archived and cannot be paused or resumed`, 409, { error: "repository-archived" });
+    const written = await client.postJson(`${LIST_ROUTE}/${action}`, reason === undefined ? { repoId: selected.id } : { repoId: selected.id, reason }, { accept });
+    if (written.status >= 400) {
+        const detail = serverDetail(written.body);
+        let message = `could not ${action} ${wanted}`;
+        if (written.status === 403)
+            message = roleRefusal;
+        else if (written.status === 404) {
+            // Use descriptive evidence rather than requiring an undocumented server code spelling.
+            if (/route|endpoint/i.test(detail))
+                message = `this Catalyst Cloud does not serve repository ${action} yet (needs a newer cloud)`;
+            else if (/repo(sitory)?/i.test(detail))
+                message = `repository ${wanted} is no longer available; check catalyst repo status`;
+            else
+                message = `${wanted}: the repository or this route is no longer available`;
+        }
+        return refuse(args, ctx, message + detail, written.status, written.body);
+    }
+    // POST envelopes are not established by this fixture. Only a fresh read establishes the row.
+    // Never repeat a successful POST if verification fails.
+    let refreshed;
+    try {
+        const after = await client.getJson(LIST_ROUTE);
+        const found = decodeList(after.body).repositories.find((row) => row.id === selected.id);
+        if (!found)
+            throw new Error("the repository is no longer visible to your login");
+        refreshed = found;
+    }
+    catch (error) {
+        return refuse(args, ctx, `the ${action} write succeeded, but repository status could not be read: ${error instanceof Error ? error.message : String(error)}`, undefined, {
+            error: "repository-status-unavailable", writeSucceeded: true, repoId: selected.id,
+        });
+    }
+    if (args.json)
+        ctx.stdout(JSON.stringify(refreshed));
+    else
+        renderRow(refreshed, ctx);
+    return 0;
+}

package/dist/repo.js

@@ -15,6 +15,7 @@ import { existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, renameSyn
 import { dirname, join, relative, resolve } from "node:path";
 import { flagBool, positionals } from "./args.js";
 import { UsageError } from "./errors.js";
+import { cmdRepoStatus } from "./repo-status.js";
 export const BLOCK_START = "<!-- catalyst:start -->";
 export const BLOCK_END = "<!-- catalyst:end -->";
 /** The two skills the block names. ONE place each: the packs are being consolidated, and a rename
@@ -248,8 +249,12 @@ function checkoutRoot(args, sub) {
 }
 export async function cmdRepo(args, ctx) {
     const [sub] = positionals(args);
+    if (sub === "status" || sub === "pause" || sub === "resume")
+        return cmdRepoStatus(args, ctx);
     if (sub !== "agents-block" && sub !== "agent-setup")
-        throw new UsageError("repo needs agents-block <path> [--write] or agent-setup <path> [--apply] [--with-check]");
+        throw new UsageError("repo needs status, pause <owner/name> --reason <text>, resume <owner/name> [--reason <text>], agents-block <path> [--write] or agent-setup <path> [--apply] [--with-check]");
+    if (args.flags.reason !== undefined)
+        throw new UsageError("--reason belongs to repo pause or resume");
     const root = checkoutRoot(args, sub);
     const emit = (body, lines) => { if (args.json)
         ctx.stdout(JSON.stringify(body));

package/dist/runner-command.js

@@ -4,7 +4,9 @@ import { UsageError } from "./errors.js";
 import { autoUpdateStatus, disableAutoUpdate, enableAutoUpdate, scheduledPath, } from "./runner-auto-update.js";
 import { dockerRunnerUpdateEngine, readReleaseState, runnerDir, runRunnerUpdate, updateResultLines, } from "./runner-update.js";
 import { dockerFleetUpdateEngine, runFleetUpdate } from "./runner-update-fleet.js";
-const USAGE = "catalyst runner update [--check] [--dir <runner directory>] [--fleet] | runner auto-update [status|on|off]";
+import { cmdRunnerLifecycle, RUNNER_LIFECYCLE_ACTIONS } from "./runner.js";
+const USAGE = "catalyst runner [status] | stop | start | uninstall [--yes] [--delete-checkouts] | runner update [--check] [--dir <runner directory>] [--fleet] | runner auto-update [status|on|off]";
+const UPDATE_FLAGS = ["check", "auto", "dir", "fleet"];
 function schedulerDeps(ctx, deps) {
     const cli = deps.scheduler?.cli ?? resolve(process.argv[1] ?? "catalyst");
     return {
@@ -41,6 +43,13 @@ export function enableRunnerAutoUpdate(ctx, dir) {
 export async function cmdRunner(args, ctx, deps = {}) {
     const parts = positionals(args);
     const action = parts[0];
+    if (action === undefined || RUNNER_LIFECYCLE_ACTIONS.includes(action)) {
+        if (UPDATE_FLAGS.some(flag => args.flags[flag] !== undefined))
+            throw new UsageError("--check, --auto, --dir and --fleet are only valid with runner update or auto-update");
+        return cmdRunnerLifecycle(args, ctx, deps);
+    }
+    if (args.flags.yes !== undefined || args.flags["delete-checkouts"] !== undefined)
+        throw new UsageError("--yes and --delete-checkouts are only valid with runner uninstall");
     const dirFlag = flagString(args, "dir");
     if (dirFlag !== undefined && !isAbsolute(dirFlag))
         throw new UsageError("--dir must be an absolute path");