@catalyst-cloud/cli 0.16.25 → 0.16.28

package/dist/legacy.js

@@ -6,17 +6,20 @@
 //
 // The list is fixed on purpose. A prefix match would one day catch a current job (the housekeeping
 // job, the sandbox credit guard, jobs a person made); this matches names the old runtime installed,
-// read at the source commit below, and nothing else. Shared data folders are always kept. The historical --data flag cannot remove them.
+// read at the source commit below, and nothing else. Shared data folders are always kept;
+// --data separately selects the enumerated replica and event-cache files.
 import { existsSync, lstatSync, readFileSync, readdirSync, unlinkSync, } from "node:fs";
 import { spawnSync } from "node:child_process";
 import { join } from "node:path";
 import { flagBool, positionals } from "./args.js";
 import { UsageError } from "./errors.js";
 import { promptSecret, stdinIsTty } from "./prompt.js";
+import { findLocalSyncData, localSyncInventory, removeLocalSyncData } from "./local-sync-data.js";
 /** The archived repository's commit the list below was read at. */
 export const LEGACY_SOURCE_COMMIT = "73bc0645252ce8be38f8c87be6b67b950b3f0b56";
 /** The old runtime's marketplace source, as Claude Code records it in known_marketplaces.json. */
 export const OLD_MARKETPLACE_REPO = "coalesce-labs/catalyst";
+const OLD_REPLICA_LABEL = "ai.coalesce.catalyst-replica-sync";
 /** launchd labels the old runtime installed under ~/Library/LaunchAgents (macOS). `com.catalyst.role.<name>`
  *  is the old role supervisor's per-role instance, matched by that exact prefix. Never `dev.catalystcloud.*`
  *  (the current housekeeping job and runner jobs) and never `dev.catalyst.*` (the sandbox credit guard). */
@@ -36,7 +39,7 @@ export const OLD_LAUNCHD_LABELS = [
     "ai.coalesce.catalyst-usage-page",
     "ai.coalesce.catalyst-claude-update",
     "ai.coalesce.catalyst-updater",
-    "ai.coalesce.catalyst-replica-sync",
+    OLD_REPLICA_LABEL,
     "ai.coalesce.catalyst-channel-watcher",
     "ai.coalesce.catalyst-event-mirror",
     "ai.coalesce.catalyst-monitor",
@@ -129,6 +132,9 @@ function findJobs(home, platform) {
             kind: "job",
             name: label,
             path: join(dir, `${label}.plist`),
+            ...(label === OLD_REPLICA_LABEL || label === "ai.coalesce.catalyst-event-mirror"
+                ? { localSync: true, size: lstatSync(join(dir, `${label}.plist`)).size }
+                : {}),
         }));
     }
     if (platform === "linux") {
@@ -157,12 +163,12 @@ function findFiles(home) {
     return [...bins, ...data];
 }
 /** Every old piece on this machine, in removal order: plugins, their marketplace, jobs, bins, data. Never writes. */
-export function findLegacy(home, platform) {
+export function findLegacy(home, platform, options = {}) {
     return [
         ...findPlugins(home),
         ...findJobs(home, platform),
         ...findFiles(home),
-    ];
+    ].filter((item) => !(options.preserveReplica && "localSync" in item && item.localSync));
 }
 const defaultRun = (cmd, args) => {
     const r = spawnSync(cmd, args, { encoding: "utf8", timeout: 60_000 });
@@ -224,8 +230,9 @@ export async function cmdLegacy(args, ctx, deps = {}) {
     const platform = deps.platform ?? process.platform;
     const uid = deps.uid ?? (typeof process.getuid === "function" ? process.getuid() : 0);
     const run = deps.run ?? defaultRun;
-    const found = findLegacy(ctx.home, platform);
-    const legacy = found.filter((item) => !item.data);
+    const local = deps.preserveReplica ? [] : deps.localSyncFiles ?? await findLocalSyncData(ctx);
+    const found = [...findLegacy(ctx.home, platform, deps), ...local];
+    const legacy = found.filter((item) => !item.data && (item.kind === "job" || !item.localSync || withData));
     const shared = found.filter((item) => item.data);
     const emit = (body, lines) => {
         if (args.json)
@@ -234,24 +241,34 @@ export async function cmdLegacy(args, ctx, deps = {}) {
             for (const l of lines)
                 ctx.stdout(l);
     };
+    const inventory = localSyncInventory(local);
     if (legacy.length === 0) {
         emit({
             sourceCommit: LEGACY_SOURCE_COMMIT,
             found: [],
             removed: [],
             remaining: [],
-            kept: shared,
+            kept: [...shared, ...local],
+            ...(local.length ? { localSyncFiles: local } : {}),
+            ...(local.length && !deps.localSyncSelected ? { requiredFlag: "--remove --data" } : {}),
         }, [
             "no leftovers of the old local Catalyst runtime on this machine",
             ...(shared.length
                 ? ["shared current Catalyst data folders are present and kept"]
                 : []),
+            ...inventory,
+            ...(local.length
+                ? [deps.localSyncSelected
+                        ? "Local sync is on, so these files are current data and kept."
+                        : "Local sync data kept. If you no longer use local sync, run catalyst legacy --remove --data to review and remove it."]
+                : []),
         ]);
         return 0;
     }
     const listLines = [
         `Leftovers of the old local Catalyst runtime on this machine (${legacy.length}):`,
-        ...legacy.map((f) => `  ${f.kind}: ${f.name}${f.kind === "job" ? ` — ${f.path}` : ""}`),
+        ...legacy.map((f) => `  ${f.kind}: ${f.name}${f.kind === "job" ? ` — ${f.path} (${lstatSync(f.path).size} bytes)` : ""}`),
+        ...inventory,
         ...(shared.length
             ? [
                 "Shared current data folders (kept):",
@@ -286,14 +303,16 @@ export async function cmdLegacy(args, ctx, deps = {}) {
             }, [
                 ...listLines,
                 RECOMMEND,
-                "nothing removed: no terminal to ask on; run catalyst legacy --remove --yes to remove these without a question (all data folders are kept)",
+                withData
+                    ? "nothing removed: no terminal to ask on; run catalyst legacy --remove --data --yes to remove the listed local sync files (login, contract, settings and shared data folders are kept)"
+                    : "nothing removed: no terminal to ask on; run catalyst legacy --remove --yes to remove these without a question (all data folders are kept)",
             ]);
             return 1;
         }
         for (const l of listLines)
             ctx.stdout(l);
         ctx.stdout(RECOMMEND);
-        const answer = (await (deps.prompt ?? ((q) => promptSecret(q)))(`Remove ${legacy.length} item${legacy.length === 1 ? "" : "s"}, keeping all data folders? [y/N] `))
+        const answer = (await (deps.prompt ?? ((q) => promptSecret(q)))(`Remove ${legacy.length} item${legacy.length === 1 ? "" : "s"}${withData && local.length ? ", including the listed local sync files" : ", keeping all data folders"}? [y/N] `))
             .trim()
             .toLowerCase();
         go = answer === "y" || answer === "yes";
@@ -313,6 +332,11 @@ export async function cmdLegacy(args, ctx, deps = {}) {
     const kept = [];
     const lines = [];
     for (const item of found) {
+        if (item.localSync && item.kind === "data") {
+            if (!withData)
+                kept.push(item);
+            continue;
+        }
         if (item.data) {
             kept.push(item);
             lines.push(`kept: ${item.kind} ${item.name} (shared current state; always kept)`);
@@ -328,8 +352,25 @@ export async function cmdLegacy(args, ctx, deps = {}) {
             lines.push(`still present: ${item.kind} ${item.name} (${why})`);
         }
     }
+    if (withData && local.length) {
+        try {
+            if (failed.some(({ item }) => item.name === OLD_REPLICA_LABEL || item.name === "ai.coalesce.catalyst-event-mirror"))
+                throw new Error("local sync service did not stop; local data kept");
+            await removeLocalSyncData(local, deps.stopWriter);
+            removed.push(...local);
+            lines.push(...local.map((item) => `removed: local sync data ${item.path}`));
+        }
+        catch (error) {
+            kept.push(...local);
+            failed.push({ item: local[0], why: error instanceof Error ? error.message : String(error) });
+            lines.push("local sync cleanup failed; remaining local data kept");
+        }
+    }
     // re-check from the same list, so the report says what the machine holds now, not what was attempted
-    const remaining = findLegacy(ctx.home, platform).filter((f) => !f.data);
+    const remaining = [
+        ...findLegacy(ctx.home, platform, deps).filter((f) => !f.data),
+        ...(withData ? await findLocalSyncData(ctx) : []),
+    ];
     const keptNote = kept.length > 0 ? "; all shared data folders were kept" : "";
     lines.push(remaining.length === 0
         ? `re-checked: nothing of the old runtime remains${keptNote}`
@@ -342,5 +383,5 @@ export async function cmdLegacy(args, ctx, deps = {}) {
         kept,
         failed,
     }, lines);
-    return remaining.length === 0 ? 0 : 1;
+    return remaining.length === 0 && failed.length === 0 ? 0 : 1;
 }

package/dist/local-sync-data.js

@@ -0,0 +1,159 @@
+import { existsSync, lstatSync, readFileSync, readdirSync, unlinkSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { isAbsolute, join } from "node:path";
+import { configPathFor, defaultReplicaDbFor, replicaDbPath } from "./config.js";
+import { CliError } from "./errors.js";
+import { loadMachinePaths } from "../vendor/paths/node.js";
+function json(path) {
+    try {
+        const value = JSON.parse(readFileSync(path, "utf8"));
+        return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+    }
+    catch {
+        return {};
+    }
+}
+/** Read only known replica leaves and SDK event-cache segments, never a shared directory. */
+export async function findLocalSyncData(ctx) {
+    const cfg = json(configPathFor(ctx.home));
+    const env = { ...ctx.env, HOME: ctx.home };
+    const machine = await loadMachinePaths({ env });
+    const databases = new Set([
+        defaultReplicaDbFor(ctx.home),
+        join(ctx.home, ".config", "catalyst", "replica.db"),
+    ]);
+    if (typeof cfg.replicaDb === "string") {
+        if (!isAbsolute(cfg.replicaDb))
+            throw new CliError("the saved replica path is not absolute; local data kept", "local-sync-path-invalid");
+        databases.add(cfg.replicaDb);
+    }
+    try {
+        databases.add(replicaDbPath({ replicaDb: typeof cfg.replicaDb === "string" ? cfg.replicaDb : undefined }, ctx.home, ctx.env));
+    }
+    catch (error) {
+        if (!(error instanceof CliError && error.code === "replica-not-configured"))
+            throw error;
+    }
+    const paths = new Set();
+    for (const db of databases) {
+        if (/^(customer|contract|settings|config|paths)\.(json|toml)$/.test(db.split("/").at(-1) ?? ""))
+            throw new CliError(`local sync cleanup cannot delete login, contract or settings: ${db}`, "local-sync-path-protected");
+        for (const suffix of ["", "-wal", "-shm", ".pid", ".writer.lock", ".writer.state"])
+            paths.add(`${db}${suffix}`);
+    }
+    const roots = new Set([
+        join(ctx.env.XDG_STATE_HOME ?? join(ctx.home, ".local", "state"), "catalyst", "events"),
+        ...(ctx.env.CATALYST_EVENTS_DIR ? [ctx.env.CATALYST_EVENTS_DIR] : []),
+        ...(machine?.paths.events ? [machine.paths.events] : []),
+    ]);
+    const entries = (dir) => {
+        try {
+            if (!lstatSync(dir).isDirectory())
+                return [];
+            return readdirSync(dir);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return [];
+            throw error;
+        }
+    };
+    const cacheFiles = (dir) => {
+        for (const name of entries(dir))
+            if (/^\d{4}-\d{2}-\d{2}(?:-\d{3})?\.jsonl$/.test(name) || ["cursor.json", ".sync.writer.lock"].includes(name))
+                paths.add(join(dir, name));
+    };
+    for (const root of roots) {
+        cacheFiles(root);
+        for (const account of entries(root)) {
+            const dir = join(root, account);
+            if (lstatSync(dir).isDirectory())
+                cacheFiles(join(dir, "backbone"));
+        }
+    }
+    const files = [];
+    for (const path of paths) {
+        if (!existsSync(path))
+            continue;
+        const stat = lstatSync(path);
+        if (!stat.isFile())
+            throw new Error(`local sync cleanup requires a regular file: ${path}`);
+        files.push({ kind: "data", name: path, path, localSync: true, size: stat.size, dev: stat.dev, ino: stat.ino });
+    }
+    return files;
+}
+export function localSyncInventory(files) {
+    return files.map((file) => `${file.path} (${file.size} bytes)`);
+}
+/** Stop the replica writer a pidfile or lock names. A pid that is gone, belongs to another user
+ *  (EPERM: a writer this person started runs as them) or runs another command is a stale record
+ *  left by a crash or reboot: no signal is sent, and cleanup goes on. */
+async function stopWriter(pid) {
+    if (pid === process.pid)
+        throw new Error("refusing to stop the cleanup process as a replica writer");
+    const alive = () => {
+        try {
+            process.kill(pid, 0);
+            return true;
+        }
+        catch (error) {
+            const code = error.code;
+            if (code === "ESRCH" || code === "EPERM")
+                return false;
+            throw error;
+        }
+    };
+    if (!alive())
+        return;
+    const command = spawnSync("ps", ["-p", String(pid), "-o", "command="], { encoding: "utf8", timeout: 1000 });
+    if (command.status !== 0 || !/(?:^|[/\s])catalyst(?:-skills)?(?:\.js)?\s+replica\s+start\b|(?:^|[/\s])catalyst-replica-sync(?:\s|$)/.test(command.stdout))
+        return;
+    process.kill(pid, "SIGTERM");
+    const deadline = Date.now() + 5000;
+    while (alive()) {
+        if (Date.now() >= deadline)
+            throw new Error(`replica writer ${pid} did not stop; local data kept`);
+        await new Promise((resolve) => setTimeout(resolve, 50));
+    }
+}
+/** Internal test seam for the production writer stop, without a process override. */
+export const stopReplicaWriterForTest = stopWriter;
+/** Wait for every detached writer before unlinking. Refuse a replacement file after approval. */
+export async function removeLocalSyncData(files, stop = stopWriter) {
+    const pids = new Set();
+    const present = (file) => {
+        let current;
+        try {
+            current = lstatSync(file.path);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return false;
+            throw error;
+        }
+        if (!current.isFile() || current.dev !== file.dev || current.ino !== file.ino)
+            throw new Error(`local sync file changed after confirmation; kept: ${file.path}`);
+        return true;
+    };
+    // Check the whole approved inventory before reading ownership evidence or sending a signal.
+    for (const file of files)
+        present(file);
+    for (const file of files) {
+        if (!present(file))
+            continue;
+        let pid;
+        if (file.path.endsWith(".pid"))
+            pid = Number(readFileSync(file.path, "utf8").trim());
+        else if (file.path.endsWith(".writer.lock"))
+            pid = json(file.path).pid;
+        if (Number.isSafeInteger(pid) && Number(pid) > 0)
+            pids.add(Number(pid));
+    }
+    for (const pid of pids)
+        await stop(pid);
+    for (const file of files)
+        present(file);
+    for (const file of files)
+        if (present(file))
+            unlinkSync(file.path);
+}

package/dist/machine-inventory.js

@@ -12,6 +12,7 @@ function machine(value) {
         count(value.free) &&
         (value.lastCheckInAtMs === null || count(value.lastCheckInAtMs)) &&
         (value.status === "live" || value.status === "stale") &&
+        (value.stopped === undefined || typeof value.stopped === "boolean") &&
         typeof value.removable === "boolean" &&
         typeof value.renameable === "boolean");
 }

package/dist/messages.js

@@ -0,0 +1,47 @@
+import { flagString, positionals } from "./args.js";
+import { requireConfig } from "./config.js";
+import { CliError, UsageError } from "./errors.js";
+import { bearerFor } from "./oauth.js";
+import { loadHttpSdk } from "./sdk.js";
+function failure(result) {
+    const reason = "reason" in result && typeof result.reason === "string" ? `: ${result.reason}` : "";
+    return `messages: ${result.outcome}${"status" in result && result.status ? ` (${result.status})` : ""}${reason}`;
+}
+export async function cmdMessages(args, ctx, deps = {}) {
+    const [action, ...extra] = positionals(args);
+    if (action !== "read" || extra.length)
+        throw new UsageError("messages takes: read --ticket CTC-N [--since SEQUENCE]");
+    const ticket = flagString(args, "ticket")?.trim().toUpperCase();
+    if (!ticket)
+        throw new UsageError("messages read needs --ticket CTC-N");
+    const rawSince = flagString(args, "since");
+    const since = rawSince === undefined ? undefined : Number(rawSince);
+    if (since !== undefined && (!Number.isSafeInteger(since) || since < 0))
+        throw new UsageError("--since must be a non-negative message sequence");
+    const cfg = requireConfig(ctx);
+    const createClient = deps.createClient ?? (async (options) => (await loadHttpSdk()).createTenantClient(options));
+    const client = await createClient({ key: await bearerFor(ctx, cfg), baseUrl: cfg.baseUrl, fetch: ctx.fetch });
+    if (!client.messages)
+        throw new CliError("the installed SDK cannot read messages; upgrade the catalyst CLI", "sdk-upgrade-required");
+    const result = await client.messages.read({ ticket, ...(since === undefined ? {} : { since }) });
+    if (result.outcome !== "ok") {
+        if (args.json)
+            ctx.stdout(JSON.stringify(result));
+        else
+            ctx.stderr(failure(result));
+        return 1;
+    }
+    if (args.json)
+        ctx.stdout(JSON.stringify({ ticket: result.ticket, messages: result.messages, next: result.next }));
+    else if (result.messages.length === 0)
+        ctx.stdout(`${result.ticket}: no messages${since === undefined ? "" : ` at or after ${since}`}`);
+    else
+        for (const message of result.messages) {
+            ctx.stdout(`#${message.seq} ${message.sentAt} ${message.from.label} (${message.kind})`);
+            for (const line of message.body.split("\n"))
+                ctx.stdout(`  ${line}`);
+        }
+    if (result.next !== null)
+        ctx.stderr(`more: re-run with --since ${result.next}`);
+    return 0;
+}

package/dist/onboard-runner-custody.js

@@ -19,6 +19,14 @@ class CustodyInstallError extends Error {
 export function darwinThoughtsInstallRefusal(error) {
     return error instanceof CustodyInstallError ? error.reason : undefined;
 }
+/** What a person changes for a create refusal that names its cause; other refusals have no advice. */
+const CREATE_REFUSAL_ADVICE = {
+    bootstrap_create_mount_refused: "Docker Desktop refused to share a storage folder with the check container. In Docker Desktop, open Settings, then Resources, then File sharing, make sure your home folder is listed, apply, and run setup again.",
+};
+export function darwinThoughtsInstallAdvice(error) {
+    const reason = darwinThoughtsInstallRefusal(error);
+    return reason === undefined ? undefined : CREATE_REFUSAL_ADVICE[reason];
+}
 /** Unknown exception text can contain credentials. Keep its class, and explicitly redact it. */
 export function darwinThoughtsInstallException(error) {
     const known = error instanceof CustodyInstallError;
@@ -620,6 +628,7 @@ async function actualBootstrap(input) {
     let id;
     let cachedImage;
     let createAttempted = false;
+    let createRefused = false;
     const receiveIdentity = (received, acknowledgedId) => {
         if (received.code !== 0)
             fail("bootstrap_cleanup_unproved");
@@ -681,8 +690,10 @@ async function actualBootstrap(input) {
             "PATH=/usr/bin:/bin", "BUN_RUNTIME_TRANSPILER_CACHE_PATH=0", "/usr/local/bin/bun", "--config=/dev/null", "--no-env-file", "--cwd=/",
             "-e", program, canonicalDarwinThoughtsJson({ authority, deadlineMs: input.deadlineMs })]);
         // Docker's own refusal of a mount source is matched, never forwarded: stderr can carry secrets.
-        if (created.code !== 0 && /bind source path does not exist|[Mm]ounts denied/.test(created.stderr))
+        if (created.code !== 0 && /bind source path does not exist|[Mm]ounts denied/.test(created.stderr)) {
+            createRefused = true;
             fail("bootstrap_create_mount_refused");
+        }
         if (created.code !== 0 || !/^[a-f0-9]{64}$/.test(created.stdout))
             fail("bootstrap_create_unreceived");
         id = created.stdout;
@@ -726,7 +737,17 @@ async function actualBootstrap(input) {
                 image.stdout !== cachedImage)
                 fail("bootstrap_cleanup_unproved");
             let received;
-            for (let attempt = 0; attempt < 32; attempt++) {
+            // A refused create persists nothing; prove that by our random token label, and only
+            // fall back to recovering the exact helper when the Engine lists one anyway.
+            let refusedAbsent = false;
+            if (createRefused && id === undefined) {
+                const persisted = await cleanupDocker(["ps", "--all", "--no-trunc", "--quiet",
+                    "--filter", "label=dev.catalystcloud.custody-token=" + token]);
+                if (persisted.code !== 0)
+                    fail("bootstrap_cleanup_unproved");
+                refusedAbsent = persisted.stdout === "";
+            }
+            for (let attempt = 0; !refusedAbsent && attempt < 32; attempt++) {
                 const current = await cleanupDocker(["inspect", name]);
                 if (current.code === 0) {
                     received = current;
@@ -736,19 +757,21 @@ async function actualBootstrap(input) {
                     fail("bootstrap_cleanup_unproved");
                 await new Promise(resolve => setTimeout(resolve, 25));
             }
-            if (received === undefined)
-                fail("bootstrap_cleanup_unproved");
-            id = receiveIdentity(received, id);
-            const list = ["ps", "--all", "--no-trunc", "--quiet", "--filter", "id=" + id];
-            const present = await cleanupDocker(list);
-            if (present.code !== 0 || present.stdout !== id)
-                fail("bootstrap_cleanup_unproved");
-            const removed = await cleanupDocker(["rm", "--force", id]);
-            if (removed.code !== 0)
-                fail("bootstrap_cleanup_unproved");
-            const absent = await cleanupDocker(list);
-            if (absent.code !== 0 || absent.stdout !== "")
-                fail("bootstrap_cleanup_unproved");
+            if (!refusedAbsent) {
+                if (received === undefined)
+                    fail("bootstrap_cleanup_unproved");
+                id = receiveIdentity(received, id);
+                const list = ["ps", "--all", "--no-trunc", "--quiet", "--filter", "id=" + id];
+                const present = await cleanupDocker(list);
+                if (present.code !== 0 || present.stdout !== id)
+                    fail("bootstrap_cleanup_unproved");
+                const removed = await cleanupDocker(["rm", "--force", id]);
+                if (removed.code !== 0)
+                    fail("bootstrap_cleanup_unproved");
+                const absent = await cleanupDocker(list);
+                if (absent.code !== 0 || absent.stdout !== "")
+                    fail("bootstrap_cleanup_unproved");
+            }
         }
         catch {
             // Keep the refusal that started cleanup; without it every create failure reads as cleanup.

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 };