@catalyst-cloud/cli 0.16.25 → 0.16.27

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.16.27
+
+A large workspace's local replica now finishes its first download instead of stopping after 30 seconds: it waits as long as data keeps arriving, and gives up only after 150 seconds with no progress. New commands: `catalyst repo status` lists your repositories and whether each is paused, and `catalyst repo pause|resume` pauses or resumes one (owners and admins). `catalyst runner status|stop|start|uninstall` stops a self-hosted machine taking work, starts it again with the same registration, or removes it and revokes its registration. Setup with local sync off now lists an old local replica's files with their sizes and removes them only after you say yes. Setup with local sync on keeps using the replica you already have. On a Mac where Docker Desktop does not share your home folder, setup now says which setting to change (Settings, then Resources, then File sharing).
+
+## 0.16.26
+
+Not published. Its changes ship in 0.16.27.
+
 ## 0.16.25
 
 A self-hosted machine that runs several teams' work from one `compose.json` can now take each approved release by itself. Run `catalyst runner update --fleet --dir <the folder that holds compose.json>`, by hand or on a schedule. It switches only the supervisor to the approved images and leaves work that is already running alone. If the machine's teams are not ready again within four minutes, it puts the previous images back. `--check` shows what would change without changing anything.

package/README.md

@@ -166,6 +166,19 @@ With a person at the terminal, `catalyst onboard` starts each of these approvals
 
 With `--runner yes`, setup starts the self-hosted runner and verifies enrollment, advertised capacity and team admission. This needs Docker with Compose, pinned host images and an organization key file (`CATALYST_RUNNER_ORG_KEY_FILE`). When images, a key or admission are missing, exit 11 names that gate. A failed setup step exits 10. Use `--runner no` to skip the machine's runner. Unlike the interactive optional runner step, an explicitly requested headless runner must finish before exit 0.
 
+### Stopping or removing this machine's runner
+
+Run these on the machine itself:
+
+| command | what it does |
+| -- | -- |
+| `catalyst runner stop` | The machine takes no new work. Work it already started finishes or reaches its deadline. Its registration, settings and checkouts are kept, and `catalyst hosts` shows it as `stopped`. |
+| `catalyst runner start` | Starts it again with the same registration. |
+| `catalyst runner status` | Says whether it is running, stopped or not installed. |
+| `catalyst runner uninstall` | Asks first (`--yes` confirms without a terminal; an owner or admin login is needed). It stops new work, revokes the machine's registration and the runner key setup issued, and switches the project's runner admission off when no other machine runs it. Then it removes the runner's containers, their volumes and the session network, and the setup files in the runner folder. On macOS it also removes the storage LaunchAgent and its folders. On Linux it also removes the session-egress units, their script and state, and the `inet catalyst_session` nftables table, through `sudo`. |
+
+Uninstall removes only what setup created. Anything that does not match what setup wrote, such as a network with another label or a changed unit file, is left in place. Your repository and thoughts checkouts are kept unless you add `--delete-checkouts`. The command ends with a "Left behind" list naming everything it did not remove. When a step fails, such as a cloud call while you are offline, it says which one and exits 1. Run it again: it picks up where the last run stopped. Do not delete the runner folder by hand while the runner is installed. That deletes its settings while its containers keep running.
+
 With `--json`, stdout carries exactly one document: the onboarding receipt plus a `headless` block (`schema: "catalyst-onboard-headless/1"`). The block holds the resolved `inputs` (the key appears only as its source: `env`, `file` or `saved`), and lists of items under `missing`, `refused`, `failed`, `deferred` and `warnings`. Each item has `id`, `kind` (`input`, `grant` or `step`), `reason` and a one-line `text`, plus `flag`, `env` and `url` where they apply. Everything else goes to stderr.
 
 | Exit | Meaning |
@@ -201,6 +214,24 @@ Open a new session and ask about your own cloud account. The skills read the con
 
 `catalyst team list` inventories visible teams without running readiness checks. `team check ENG` prints readiness for one team; `team check --all` runs checks for every team. `team map ENG`, `team adopt ENG`, and `team migrate ENG` print a plan and exit 3 before changing configuration; review the plan and rerun the chosen command with `--yes --plan-hash <hash>` from that preview. `team adopt ENG --undo` previews the exact previously created stages, and `team migrate ENG --retire` requires its own confirmation after the ticket move. `team checklist ENG` prints the same manual setup lines as the browser. These commands use the member's own login; an admin or owner seat is required for setup, and Adopt and Migrate also need that member's personal Linear connection.
 
+## Repository status and pauses
+
+Use your existing login to list the repositories visible to you, their status and attached projects:
+
+```sh
+catalyst repo status
+catalyst repo status --json
+catalyst repo pause acme/app --reason "flaky deploy"
+catalyst repo resume acme/app --reason "deploy fixed"
+catalyst repo resume acme/app
+```
+
+Any workspace member can read status. Pausing or resuming requires a workspace owner or admin. Pause requires a reason; resume accepts an optional reason. A supplied reason must contain 1 to 500 characters after trimming. These commands work outside a local checkout.
+
+Paused rows show who paused the repository (their email, or the key or operator that paused it), when and why, when those details are available. An empty list means no repositories are visible to your login. After a write, the command reads and prints the repository's current state. If that read fails, it reports that the write succeeded and status could not be read; check `catalyst repo status` before repeating a write.
+
+`--json` preserves the list response for status and prints the refreshed repository row for a write. An older cloud reports that repository status is not served yet and needs a newer cloud. Agents can use `catalyst capabilities --json` to check route availability against the cached cloud contract.
+
 ## What has to be running
 
 Nothing, by default. After `login`, every read, write, ask and explanation goes to the cloud's origin-fresh API with the config file and the cached contract on disk. Two optional processes exist for people who want them:
@@ -270,6 +301,8 @@ A `customer.json` written by an older bundle is still read unchanged; it gains t
 
 ## Uninstalling
 
+If this machine runs Catalyst's work, run `catalyst runner uninstall` first (see "Stopping or removing this machine's runner").
+
 Remove the skills the way you installed them: `/plugin uninstall catalyst@catalyst-cloud` in Claude Code, or delete the skill directories (`catalyst-github`, `catalyst-linear`, `catalyst-onboard`, `run-this-project`, `unstick`, `what-needs-me`, `what-this-repo-needs`, `whats-happening`) from wherever `npx skills add` wrote them. Skills an earlier release shipped (`catalyst-setup`, `connect-me`, `how-catalyst-works`) go the same way; the CLI removes its own stamped copies of them when it installs or refreshes skills. Then remove what the CLI wrote:
 
 ```sh

package/dist/args.js

@@ -26,6 +26,8 @@ export const FLAG_TABLES = {
         auto: { value: false, help: "one-line output for the scheduled run" },
         dir: { value: true, help: "the runner directory (default: the one setup created)" },
         fleet: { value: false, help: "update a multi-team supervisor fleet's compose.json in --dir" },
+        yes: { value: false, help: "uninstall: confirm without a terminal" },
+        "delete-checkouts": { value: false, help: "uninstall: also delete the repository and thoughts checkouts" },
     },
     login: {
         "start-replica": {
@@ -66,6 +68,10 @@ export const FLAG_TABLES = {
             value: false,
             help: "include the optional local sync setup in this plan",
         },
+        "remove-local-data": {
+            value: false,
+            help: "with local sync off, stop existing local writers and delete the listed replica and event-cache files; keep login, contract and settings",
+        },
         runner: {
             value: false,
             optionalValue: true,
@@ -486,7 +492,7 @@ export const FLAG_TABLES = {
         },
         data: {
             value: false,
-            help: "historical flag; shared data folders are always kept",
+            help: "include the listed replica DB, sidecars and local event cache; shared data folders, login, contract and settings are kept",
         },
         yes: {
             value: false,
@@ -494,6 +500,7 @@ export const FLAG_TABLES = {
         },
     },
     repo: {
+        reason: { value: true, help: "pause: required; resume: optional; 1 to 500 characters after trimming (owner or admin)" },
         write: {
             value: false,
             help: "agents-block: write or update the block in AGENTS.md (working tree only)",
@@ -545,10 +552,10 @@ export const FLAG_TABLES = {
 };
 export const VERB_USAGE = {
     hosts: "hosts [list] | hosts remove <name-or-id> [--yes] | hosts rename <name-or-id> <new-name> [--json]",
-    runner: "runner update [--check] [--dir <runner directory>] [--fleet] | runner auto-update [status|on|off]",
+    runner: "runner [status] | runner stop | runner start | runner uninstall [--yes] [--delete-checkouts] | runner update [--check] [--dir <runner directory>] [--fleet] | runner auto-update [status|on|off] [--json]",
     setup: "setup [onboard options]   (sets up Catalyst step by step; same as catalyst onboard) | setup --engine <file> --engine-sha256 <hex> [-- <install options>]   (run by install.sh; install.sh --help lists the options)",
     login: "login [--base-url <url>] [--start-replica]   (keyless; or --key <personal-key> / CATALYST_CLOUD_TOKEN)",
-    onboard: "onboard [--team <ID|key>] [--repo <owner/name>]... [--coding-account <slot>] [--resume-from <step>] [--only <step>] [--local-sync] [--runner|--no-runner] [--no-color] [--yes] [--dry-run] [--json] | onboard --headless [--key-file <path>] [--team ...] [--repo ...]... [--coding-account ...] [--runner yes|no] [--json]",
+    onboard: "onboard [--team <ID|key>] [--repo <owner/name>]... [--coding-account <slot>] [--resume-from <step>] [--only <step>] [--local-sync] [--remove-local-data] [--runner|--no-runner] [--no-color] [--yes] [--dry-run] [--json] | onboard --headless [--key-file <path>] [--team ...] [--repo ...]... [--coding-account ...] [--runner yes|no] [--remove-local-data] [--json]",
     install: "install [--skills-dir <dir>] [--force]",
     status: "status",
     notice: "notice",
@@ -577,7 +584,7 @@ export const VERB_USAGE = {
     identity: "identity linear <status|options|set> [<linearUserId>] [--json]",
     capabilities: "capabilities [--json]",
     project: "project <list [--json] | wip-limit <get|set <n>|set default> [--team K] [--json]>",
-    repo: "repo <agents-block <path> [--write]|agent-setup <path> [--apply] [--with-check]> [--json]",
+    repo: "repo <status|pause <owner/name> --reason <text>|resume <owner/name> [--reason <text>]|agents-block <path> [--write]|agent-setup <path> [--apply] [--with-check]> [--json]   (status: visible workspace repositories; agents-block/agent-setup: local checkout)",
     legacy: "legacy [--remove [--data] [--yes]] [--json]",
     connections: "connections personal <linear|github> <start|status> [--wait <seconds>] [--json]",
     release: "release <ticket> --because <what changed> [--retry-unchanged] [--dry-run] [--json] | release --class <failure-class> --team <K> --because <what changed> [--retry-unchanged] [--dry-run] [--limit N] [--json]",

package/dist/capabilities.js

@@ -8,6 +8,8 @@ export const CAPABILITIES = [
     { verb: "hosts", does: "list this account's machines, current use and live capacity", needs: "member", routes: [], since: "0.16.0" },
     { verb: "hosts remove|rename", does: "remove or rename a self-hosted machine in this account", needs: "admin", routes: [], since: "0.16.0" },
     { verb: "runner update|auto-update", does: "move this machine's self-hosted runner to the release Catalyst approved, and check for one every 15 minutes", needs: "member", routes: [], since: "0.16.16" },
+    { verb: "runner status|stop|start", does: "stop this machine's self-hosted runner taking work, or start it again with the same registration", needs: "member", routes: [], since: "0.16.27" },
+    { verb: "runner uninstall", does: "remove this machine's self-hosted runner and revoke its registration and runner key", needs: "admin", routes: [], since: "0.16.27" },
     // CTC-4680: plain `catalyst setup` runs the onboard flow, so install.sh may hand off to it. install.sh
     // reads this flag rather than `setup --help`, which already exits 0 on 0.15.x.
     { verb: "setup", does: "set up Catalyst step by step, or show install.sh's plan, progress and sign-in in this terminal", needs: "member", routes: [], since: "0.15.0", engineProtocol: 1, bootstrapHandoff: true, bootstrapHandoffVersion: 2 },
@@ -28,6 +30,8 @@ export const CAPABILITIES = [
     { verb: "team checklist", does: "print what adopting the workflow would do to a team", needs: "admin", routes: [agent("GET", "team-workflow")], since: "0.9.5" },
     { verb: "project wip-limit get", does: "read a project's new-start WIP limit, where it comes from, and its work in progress now", needs: "member", routes: [agent("GET", "team-wip-limit")], since: "0.13.1" },
     { verb: "project wip-limit set", does: "set a project's new-start WIP limit (0 to 9999, or back to the workspace default)", needs: "admin", routes: [agent("POST", "team-wip-limit")], since: "0.13.1" },
+    { verb: "repo status", does: "list visible repositories with their state, pause details and projects", needs: "member", routes: [agent("GET", "repos")], since: "0.16.27" },
+    { verb: "repo pause|resume", does: "pause or resume a repository as a workspace owner or admin", needs: "admin", routes: [agent("GET", "repos"), agent("POST", "repos/pause"), agent("POST", "repos/resume")], since: "0.16.27" },
     { verb: "repo agents-block", does: "add or refresh the one Catalyst block in a checkout's AGENTS.md, in the working tree, for the person to commit and open as a pull request", needs: "member", routes: [], since: "0.13.1" },
     { verb: "repo agent-setup", does: "read a checkout's agent setup (AGENTS.md, CLAUDE.md, .agents and .claude skills and rules) and, on request, make it portable in the working tree", needs: "member", routes: [], since: "0.13.1" },
     { verb: "env shell", does: "open this repository's environment on this computer: Catalyst's image, the declared toolchain and variables (needs Docker; no login for Catalyst's image)", needs: "member", routes: [], since: "0.16.20" },

package/dist/cli.js

@@ -48,7 +48,7 @@ import { cmdRepo } from "./repo.js";
 import { cmdLegacy } from "./legacy.js";
 import { cmdIdentity } from "./identity.js";
 import { cmdConnections } from "./connections.js";
-import { cmdOnboard, onboardErrorJournal, } from "./onboard.js";
+import { cmdOnboard, onboardErrorJournal, onboardStatePath, readOnboardJournal, } from "./onboard.js";
 import { createClackOnboardUi, shouldUseOnboardUi, } from "./onboard-ui.js";
 import { createOnboardRuntime } from "./onboard-runtime.js";
 import { argvRequestsHeadless, headlessOnboardDeps, headlessUsageRefusal, onboardHeadlessRequested, runOnboardHeadless, } from "./onboard-headless.js";
@@ -85,6 +85,7 @@ export function usageText() {
         "  catalyst status | notice | me | ready | accounts",
         "  catalyst seat checkout --size big|med --harness claude,codex,opencode [--session-id ID] [--stage STAGE]",
         "  catalyst hosts [list] | hosts remove <name-or-id> [--yes] | hosts rename <name-or-id> <new-name>",
+        "  catalyst runner [status] | runner stop | runner start | runner uninstall [--yes] [--delete-checkouts]   (this machine's self-hosted runner)",
         "  catalyst runner update [--check] | runner auto-update [status|on|off]   (move this machine's runner to the approved release)",
         "  catalyst mcp add|list|remove (vault references only) | mcp status <name>   (a server's state, grants and last 50 tool calls)",
         "  catalyst contract [--refresh] [--path <a.b.c>]",
@@ -106,6 +107,8 @@ export function usageText() {
         "  catalyst project list [--json]   (all workspace projects, including those with no stage mapping)",
         "  catalyst stage <start|renew|done|fail> <ticket> <phase>   (a cloud-claimed local phase)",
         "  catalyst project wip-limit <get|set <n>|set default> [--team K]   (a project's new-start WIP limit; members read, owners and admins set)",
+        "  catalyst repo pause <owner/name> --reason <text> | repo resume <owner/name> [--reason <text>]   (owner or admin; reason: 1 to 500 trimmed characters)",
+        "  catalyst repo status [--json]   (visible workspace repositories and their paused state; needs login)",
         "  catalyst repo <agents-block <path> [--write]|agent-setup <path> [--apply] [--with-check]>   (a checkout's AGENTS.md block and portable agent layout; working tree only)",
         "  catalyst legacy [--remove [--data] [--yes]]   (leftovers of the old local Catalyst runtime: list them; remove them only on a yes)",
         "  catalyst identity linear <status|options|set> [<linearUserId>] [--json]",
@@ -131,6 +134,15 @@ export function usageText() {
  * the `catalyst` launcher beside it, once, on the next run of either name. Read and write back to
  * back, so the window for racing a concurrent OAuth refresh is as small as the update notice's.
  */
+/** Setup's saved local sync choice; an unreadable record reads as off, which only adds a hint. */
+function savedLocalSync(ctx) {
+    try {
+        return readOnboardJournal(onboardStatePath(ctx.home, ctx.env))?.localSync === true;
+    }
+    catch {
+        return false;
+    }
+}
 function migrateLegacyCliPath(ctx) {
     let cfg;
     try {
@@ -520,7 +532,7 @@ export async function main(argv, ctx = defaultCtx(), deps = {}) {
             case "repo":
                 return await cmdRepo(args, ctx);
             case "legacy":
-                return await cmdLegacy(args, ctx, deps.legacy ?? {});
+                return await cmdLegacy(args, ctx, { localSyncSelected: savedLocalSync(ctx), ...deps.legacy });
             case "identity":
                 return await cmdIdentity(args, ctx, deps.identity ?? {});
             case "hosts":

package/dist/hosts.js

@@ -8,7 +8,7 @@ async function confirmRemove(name) {
     return confirmYesNo(`Remove ${name} from this account? It will stop receiving work. [y/N] `);
 }
 export function machineLines(inventory) {
-    const lines = inventory.machines.map((m) => `${m.name} | ${m.ownership === "self_hosted" ? "Self-hosted" : "Catalyst's"} | ${m.teams.join(", ")} | ${m.slots} slots, ${m.inUse} in use, ${m.free} free | ${m.status} | last check-in ${m.lastCheckInAtMs === null ? "never" : new Date(m.lastCheckInAtMs).toISOString()}`);
+    const lines = inventory.machines.map((m) => `${m.name} | ${m.ownership === "self_hosted" ? "Self-hosted" : "Catalyst's"} | ${m.teams.join(", ")} | ${m.slots} slots, ${m.inUse} in use, ${m.free} free | ${m.stopped === true ? "stopped" : m.status} | last check-in ${m.lastCheckInAtMs === null ? "never" : new Date(m.lastCheckInAtMs).toISOString()}`);
     if (lines.length === 0)
         lines.push("No machines are enrolled for this account.");
     const c = inventory.capacity;

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/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.