@catalyst-cloud/cli 0.16.2 → 0.16.3

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.16.3
+
+Setup checks your local Docker engine's capabilities on macOS and explains mount or network problems.
+
 ## 0.16.2
 
 Setup keeps verified earlier Catalyst skill copies and reports where it moved them.

package/dist/onboard-next.js

@@ -122,7 +122,12 @@ const REASONS = {
     runner_session_network_misshaped: "A Docker network named catalyst-session-v1 exists with the wrong settings. Remove it with docker network rm catalyst-session-v1 when nothing uses it, then run catalyst onboard again.",
     runner_session_network_failed: "Docker could not create the catalyst-session-v1 network. Check that Docker is running, then run catalyst onboard again.",
     runner_docker_socket_unreadable: "Setup could not read the group of the Docker socket at /var/run/docker.sock. Check that Docker is running, then run catalyst onboard again.",
-    runner_engine_unsupported: "Runner setup needs local Docker Desktop or OrbStack on Mac, or native Linux Docker at /var/run/docker.sock. Select a supported local engine, then run catalyst onboard --runner.",
+    runner_engine_unsupported: "Runner setup needs a local Linux Docker engine with Compose on Mac, or native Linux Docker at /var/run/docker.sock. Select a local engine, then run catalyst onboard --runner.",
+    runner_engine_nonlocal: "The selected Docker endpoint is not a verified local unix:/// socket, or DOCKER_CONTEXT conflicts with DOCKER_HOST. Select a local Docker context and clear the conflicting variable, then run catalyst onboard --runner.",
+    runner_home_mount_unwritable: "A container could not read and write the runner home mounts as uid 10001. Share Catalyst's state directory with your Docker VM and enable writable mounts. For Colima, configure a writable home mount with ownership mapping for uid 10001, then restart the VM and run catalyst onboard --runner.",
+    runner_container_host_unreachable: "A container could not reach this Mac. Enable container-to-host networking in your Docker VM and allow the setup process through the Mac firewall, then run catalyst onboard --runner.",
+    runner_container_network_unreachable: "A container could not reach Catalyst's health endpoint. Check the Docker VM's DNS, proxy and outbound HTTPS access, then run catalyst onboard --runner.",
+    runner_engine_probe_unavailable: "Setup could not complete the container capability probe. Check Docker access and the pinned supervisor image, then run catalyst onboard --runner. Setup has not enrolled or started this machine.",
     runner_installation_unverified: "Setup found a possible existing machine installation but could not verify its Compose files and identity. Keep its files and credentials. Run docker compose -p catalyst-host logs supervisor to check it, then run catalyst setup --runner again.",
     runner_enrollment_unavailable: "Setup could not read this workspace's runner hosts. Run catalyst onboard again to retry.",
     runner_enrolled_for_other_team: "This runner is enrolled for another Linear team. Keep using that team, or ask your administrator to revoke the old enrollment before setting up this machine for the selected team.",

package/dist/onboard-runner-probes.js

@@ -0,0 +1,114 @@
+import { randomUUID } from "node:crypto";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { createServer } from "node:http";
+import { networkInterfaces } from "node:os";
+import { join } from "node:path";
+/** Runs as the supervisor's uid. A matching engine-side path is insufficient: both sides must
+ * read the fresh challenge, including a container write returned through the host mount. */
+export function runnerMountProbe(paths, challenge) {
+    return `const fs=require("node:fs");
+    try { for (const path of ${JSON.stringify(paths)}) {
+      if (fs.readFileSync(path+"/challenge","utf8")!==${JSON.stringify(challenge)}) process.exit(41);
+      fs.writeFileSync(path+"/pending",${JSON.stringify(challenge)},{mode:0o600,flag:"wx"});
+      fs.renameSync(path+"/pending",path+"/received");
+    } console.log(${JSON.stringify(challenge)}); } catch { process.exit(41); }`;
+}
+/** Contains no credentials. Host reach requires our exact fresh challenge response; public
+ * reach checks the configured Catalyst endpoint. Each request and the program have deadlines. */
+export function runnerNetworkProbe(hostUrls, networkUrl, challenge) {
+    return `(async()=>{
+    const deadline=setTimeout(()=>process.exit(44),20000);
+    try {
+      const hostStop=new AbortController();
+      try { await Promise.any(${JSON.stringify(hostUrls)}.map(async url=>{
+        const response=await fetch(url,{redirect:"error",
+          signal:AbortSignal.any([hostStop.signal,AbortSignal.timeout(12000)])});
+        if(!response.ok || await response.text()!==${JSON.stringify(challenge)}) throw Error("host");
+      })); } catch { process.exit(42); }
+      finally { hostStop.abort(); }
+      try { const response=await fetch(${JSON.stringify(networkUrl)},
+          {redirect:"error",signal:AbortSignal.timeout(5000)});
+        if(!response.ok) process.exit(43);
+        await response.body?.cancel();
+      } catch { process.exit(43); }
+      console.log(${JSON.stringify(challenge)});
+    } finally { clearTimeout(deadline); }
+  })().catch(()=>process.exit(44));`;
+}
+export async function runnerVmCapabilities(input) {
+    const challenge = randomUUID();
+    const scratch = [];
+    const options = { env: input.env, signal: input.signal, timeoutMs: 35_000 };
+    async function run(program, mounts = []) {
+        const name = `catalyst-engine-probe-${randomUUID()}`;
+        try {
+            return await input.exec(["run", "--rm", "--name", name, "--pull=never", "--read-only",
+                "--cap-drop=ALL", "--security-opt=no-new-privileges:true", "--user", "10001:10001",
+                "--tmpfs", "/tmp:size=16m,mode=1777", ...mounts.flatMap(path => ["--mount", `type=bind,src=${path},dst=${path}`]),
+                "--entrypoint", "bun", input.image, "-e", program], options);
+        }
+        finally {
+            // Killing a docker client does not stop its container. Clean up only our fresh exact name,
+            // even on abort, with an independent short deadline. Never touch any existing container.
+            const removed = await input.exec(["rm", "--force", name], { env: input.env, timeoutMs: 10_000 });
+            if (removed.code !== 0 && ![
+                `Error response from daemon: No such container: ${name}`, `Error: No such container: ${name}`,
+            ].includes(removed.stderr?.trim() ?? ""))
+                throw Error("probe_cleanup_unverified");
+        }
+    }
+    try {
+        if (input.paths.length === 0 || input.signal?.aborted)
+            return "runner_engine_probe_unavailable";
+        try {
+            for (const path of input.paths) {
+                const dir = mkdtempSync(join(path, ".catalyst-engine-probe-"));
+                scratch.push(dir);
+                writeFileSync(join(dir, "challenge"), challenge, { mode: 0o600, flag: "wx" });
+            }
+            const mounted = await run(runnerMountProbe(scratch, challenge), scratch);
+            if (mounted.code !== 0 || mounted.stdout.trim() !== challenge ||
+                scratch.some(path => readFileSync(join(path, "received"), "utf8") !== challenge))
+                return "runner_home_mount_unwritable";
+        }
+        catch {
+            return "runner_home_mount_unwritable";
+        }
+        const server = createServer((request, response) => {
+            const matches = request.method === "GET" && request.url === `/${challenge}`;
+            response.writeHead(matches ? 200 : 404, { "content-type": "text/plain", "connection": "close" });
+            response.end(matches ? challenge : "");
+        });
+        try {
+            await new Promise((resolve, reject) => {
+                server.once("error", reject);
+                server.listen(0, "0.0.0.0", resolve);
+            });
+            const address = server.address();
+            if (!address || typeof address === "string")
+                return "runner_engine_probe_unavailable";
+            const hosts = input.hostAddresses ?? ["host.docker.internal", ...Object.values(networkInterfaces())
+                    .flatMap(rows => rows ?? []).filter(row => row.family === "IPv4" && !row.internal)
+                    .map(row => row.address)];
+            const urls = [...new Set(hosts)].slice(0, 16)
+                .map(host => `http://${host}:${address.port}/${challenge}`);
+            const result = await run(runnerNetworkProbe(urls, new URL("/healthz", input.baseUrl).href, challenge));
+            if (result.code === 42)
+                return "runner_container_host_unreachable";
+            if (result.code === 43)
+                return "runner_container_network_unreachable";
+            return result.code === 0 && result.stdout.trim() === challenge ? "ready" : "runner_engine_probe_unavailable";
+        }
+        finally {
+            server.closeAllConnections();
+            await new Promise(resolve => server.close(() => resolve()));
+        }
+    }
+    catch {
+        return "runner_engine_probe_unavailable";
+    }
+    finally {
+        for (const path of scratch)
+            rmSync(path, { recursive: true, force: true });
+    }
+}

package/dist/onboard-runner.js

@@ -7,6 +7,7 @@ import { nativeEgressReady, NATIVE_EGRESS_DIR } from "./onboard-runner-egress.js
 import { runnerAdmission, issueRunnerOrgKey, verifyRunnerRoutes } from "./onboard-runner-cloud.js";
 import { verifyOnboardRoutes } from "./onboard-capabilities.js";
 import { liveTeamKey, onboardTeamAdmission } from "./onboard-capacity.js";
+import { runnerVmCapabilities } from "./onboard-runner-probes.js";
 import { readExistingOnboardJson, readOnboardTeamInventory, selectedOnboardTeam, } from "./onboard-existing.js";
 import { onboardStateRoot, } from "./onboard.js";
 // "Run Catalyst's work on this machine": the self-hosted host from catalyst-cloud's deploy/self-host
@@ -125,12 +126,15 @@ export function dockerRunnerEngine(deps = {}) {
                 return null;
             if ((await docker(["compose", "version"], { signal })).code !== 0)
                 return null;
-            const vm = /docker desktop|orbstack/i.test(String(body.OperatingSystem));
             const host = await endpoint(signal);
             const platform = deps.platform ?? process.platform;
+            const vm = platform === "darwin" || /docker desktop|orbstack/i.test(String(body.OperatingSystem));
+            const localSocket = host?.startsWith("unix:///") === true;
             nativeLocal = platform === "linux" && !vm && host === "unix:///var/run/docker.sock";
-            const supportedVm = platform === "darwin" && vm && host?.startsWith("unix:///");
-            return { arch, vm, ...(!nativeLocal && !supportedVm ? { unsupported: true } : {}) };
+            const supportedVm = platform === "darwin" && localSocket;
+            return { arch, vm, ...(!nativeLocal && !supportedVm ? {
+                    unsupported: true, ...(!localSocket ? { unsupportedReason: "runner_engine_nonlocal" } : {}),
+                } : {}) };
         },
         async installation(home, supervisorImage, signal) {
             const listed = await docker(["ps", "--all", "--filter", `label=com.docker.compose.project=${RUNNER_PROJECT}`,
@@ -247,6 +251,10 @@ export function dockerRunnerEngine(deps = {}) {
         async nativeEgressStatus(nowMs, signal) {
             return nativeLocal && (await nativeEgressReady(nowMs, signal));
         },
+        async vmCapabilities(dir, image, baseUrl, signal) {
+            return runnerVmCapabilities({ paths: DIRS.map(sub => join(dir, sub)), image, baseUrl,
+                exec: docker, env, signal });
+        },
         async socketGid() {
             if (!nativeLocal)
                 return null;
@@ -495,7 +503,7 @@ export function onboardRunnerAdapter(input = {}) {
         if (!info)
             return { state: "skipped", reason: "runner_docker_missing", evidence: selected };
         if (info.unsupported)
-            return waiting("runner_engine_unsupported", selected);
+            return waiting(info.unsupportedReason ?? "runner_engine_unsupported", selected);
         const cfg = loadConfig(ctx.home);
         const account = journal.account ?? journal.tenant;
         if (!cfg?.user ||
@@ -816,6 +824,11 @@ export function onboardRunnerAdapter(input = {}) {
                 if (arch !== p.info.arch)
                     return waiting("runner_image_emulated", { ...selected, image: ref });
             }
+            if (p.info.vm) {
+                const capability = await engine.vmCapabilities(p.dir, p.images.supervisor, p.baseUrl, signal);
+                if (capability !== "ready")
+                    return waiting(capability, selected);
+            }
             const network = await engine.network(RUNNER_SESSION_NETWORK, signal);
             if (network === "misshaped")
                 return waiting("runner_session_network_misshaped", selected);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catalyst-cloud/cli",
-  "version": "0.16.2",
+  "version": "0.16.3",
   "description": "Set up Catalyst Cloud, check your tickets and manage your account from the command line.",
   "license": "MIT",
   "type": "module",

package/skills/catalyst-github/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Catalyst's GitHub: show a ticket's pull request with its checks, reviews and review threads, say whether it is mergeable under this repository's policy, and explain what a PR accumulates as the ticket moves (the branch, the draft, the rewrite, the force-pushes, the labels, the queue). Use when someone asks "show me the PR", "what are the checks saying", "why hasn't it merged", "what does the queue need", "what does that label mean", or wants the branch and merge conventions Catalyst follows.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.2 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.3 — written in this repository for customer accounts -->
 
 # Catalyst's GitHub
 

package/skills/catalyst-linear/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Catalyst's view of Linear on the customer's own cloud account. Reads a ticket with its comments, relations, labels, linked pull requests and agent sessions inline, from the cloud API by default, with local replica reads available as an explicit opt-in, always naming the source; searches tickets, PRs, projects and initiatives; writes comments, card moves, labels and new tickets through the account's agent proxy as the app actor, with every route, stage id, label id and marker read from the account's contract. Knows what a ticket accumulates as Catalyst works it (phase-outcome comments, the document per phase, the agent session, the labels, the single blocks relation, the bookkeeping marker, the eyes acknowledgement). Use when a person says "show me the ticket", "what did Catalyst write on it", "comment on it", "move it", "label it" or "file a ticket". Not for raising a decision for a human (what-needs-me) and not for pull requests (catalyst-github).
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.2 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.3 — written in this repository for customer accounts -->
 
 # Catalyst Linear
 

package/skills/catalyst-onboard/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Set up Catalyst Cloud and say whether setup is working. Walks a person from nothing to their first ticket running, one step at a time: the coding account, the project, the integrations and connected accounts, each repository's settings file, then one real ticket moving. Also logs this machine in, reads the readiness verdict with who can fix each failure, and checks the optional local replica. Use when someone says "set me up", "onboard me", "I just signed up", "get me started", "what do I do first", "log me in", "which account is this machine on", "am I set up", "what is missing", "why does nothing happen" or "is the replica running", when a login expired, or when a skill script exits 2 saying this machine is not connected. Does every step a key can do through the catalyst CLI, hands over the exact page for the steps only a browser can do, and never claims a step it did not watch succeed.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.2 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.3 — written in this repository for customer accounts -->
 
 # Onboard me
 

package/skills/run-this-project/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Own one Catalyst Cloud project end to end until it closes. Use when the person says "run this project for me", "own this until it ships", "keep this moving", or hands you a project id or a set of tickets to drive. Subscribes to the account's event stream for the scope through the catalyst CLI, reacts to each change in the same turn, makes tickets ready and moves them to dispatch, parks what should stop, chases stalls, escalates inward, and keeps one status summary current. Writes to Linear as the app actor; never polls.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.2 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.3 — written in this repository for customer accounts -->
 
 # Run this project
 

package/skills/unstick/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Get a stuck Catalyst Cloud ticket moving again. Use when the person asks "why is this parked and can you release it?", "unpark this", "get things flowing again", "the outage is over, retry what failed", or hands you a ticket that is not moving. Reads why nothing runs and what holds the ticket through the catalyst CLI, decides whether the recorded cause is fixed, previews the release, releases every governor holding the ticket the right way (or one failure class across a team), and raises an ask only for what a person has to do. Never releases a cause it cannot show changed without saying so.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.2 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.3 — written in this repository for customer accounts -->
 
 # Unstick
 

package/skills/what-needs-me/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   The human's decision inbox on Catalyst Cloud, and the one way an agent raises a decision on their behalf. Use when the person asks "what needs me?", "what am I blocking?", or when active work is gated on a choice only they can make. Lists open asks ranked by how much open work each one holds, files an ask through the cloud's ask route with the account's own template, and records the answer so the held work releases. Never answers as the human, never duplicates an open ask.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.2 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.3 — written in this repository for customer accounts -->
 
 # What needs me
 

package/skills/what-this-repo-needs/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   What environment variable names does this repository need, and where does each one come from? Scans the repository offline (no login, no network) and lists the names in three groups (build/test, deploy-only, bindings), each with where it was found, what uses it, and where a local value would come from. Never reads a value or prints one. Also checks the environment variable table in `.catalyst/catalyst.toml` offline. Use when someone asks "what does catalyst.env.json mean", "what env vars does this repo need", "why does the container need this", or before reviewing or writing the declaration.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.2 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.3 — written in this repository for customer accounts -->
 
 # What this repository needs
 

package/skills/whats-happening/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Use for "what's happening?", "what machines do we have?", "how much capacity do we have?", "where are we?", "why is that stuck?", "what closed?", "what's next?", "how does this work?", "why did it do that?", "how does it prioritise?" and "what does this setting do, where is it set?" in Catalyst Cloud, or asks for something to be done rather than known. Reads the contract via catalyst CLI. Read-only: route work/decisions, never answer as the human.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.2 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.3 — written in this repository for customer accounts -->
 
 # What's happening