@catalyst-cloud/cli 0.16.28 → 0.16.29

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.16.29
+
+The CLI now tells Catalyst Cloud which release you have installed: each request to Catalyst Cloud carries the installed version, and so does `catalyst watch` when it connects. Catalyst Cloud can then tell an out-of-date CLI from a current one. Nothing about your requests changes otherwise. On a Mac self-hosted machine, setup now installs a small agent that measures the Mac's disk, so the machine can take work instead of showing zero free slots. When a machine still shows zero free slots, setup and `catalyst ready` now say why: its disk has not been measured yet, or its free space is below the floor (25 GiB by default), with the numbers and the fix. An updated disk sampler also takes effect straight away: setup reloads the running disk agent whenever the sampler script changes, not only when its schedule file does.
+
 ## 0.16.28
 
 `catalyst events wait-for` can now wait on a repository (`--repo owner/name`), a branch (`--ref owner/name:branch`), a pull request (`--pr owner/name#n`), a work session (`--session KEY-123/phase#n`), events addressed to you (`--to me`) or a family of event types (`--type pr.*`). An agent can wait hours for a review or a conflict on its own branch: the wait holds one connection, prints each matching event as one JSON line, and after a dropped connection picks up where it left off without missing or repeating an event. Two new exit codes say why a wait ended without a match. 2 means the cloud refused the wait, for example on a ticket outside your teams, or the wait failed. 3 means `--from-cache` found no local event cache. A wait still exits 1 on a timeout and 4 on an outage, as before, and on a timeout it names the `--after` to resume from. New: `catalyst messages read --ticket KEY-123` prints the messages sent to a ticket on your teams, with each sender and time.

package/README.md

@@ -164,7 +164,7 @@ Before any network call, the run checks that every input is present. Each missin
 
 With a person at the terminal, `catalyst onboard` starts each of these approvals itself and prints the exact link to approve.
 
-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.
+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. On a Mac, setup also installs the `dev.catalystcloud.host-disk` LaunchAgent, which measures the Mac's free disk space every 10 seconds, because Docker's virtual machine cannot see it. It needs Python 3 from Apple's Command Line Tools or Homebrew. When the machine takes no work because the disk Docker uses has less than 25 GiB free (`CATALYST_HOST_FREE_FLOOR_GIB` changes the amount) or has no fresh measurement, exit 11 says which, with the fix, and `catalyst ready` fails its `runner:disk` check the same way. If setup cannot tell which folder holds your Docker engine's disk image, set `CATALYST_HOST_DISK_PATH` to that folder.
 
 ### Stopping or removing this machine's runner
 
@@ -175,9 +175,9 @@ Run these on the machine itself:
 | `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`. |
+| `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, and the disk-measuring LaunchAgent setup installed. 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.
+Uninstall removes only what setup created. Anything that does not match what setup wrote, such as a network with another label, a changed unit file or a disk-measuring LaunchAgent that writes somewhere else, 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.
 

package/dist/cli-version.js

@@ -0,0 +1,41 @@
+const HEADER = "x-catalyst-cli-version";
+const VERSION = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+/** Public package metadata on the selected cloud API transport. All fetch semantics stay intact. */
+export function reportCliVersion(transport, version, origins) {
+    if (version.length > 80 || !VERSION.test(version))
+        return transport;
+    return (input, init) => {
+        let url;
+        try {
+            url = new URL(input instanceof Request ? input.url : String(input));
+            const selected = origins().some(origin => {
+                try {
+                    return new URL(origin).origin === url.origin;
+                }
+                catch {
+                    return false;
+                }
+            });
+            if (!selected || !(url.pathname.startsWith("/api/v1/") || ["/snapshot", "/changes", "/events"].includes(url.pathname)))
+                return transport(input, init);
+        }
+        catch {
+            return transport(input, init);
+        }
+        return transport(input, { ...init, headers: withVersion(init?.headers ?? (input instanceof Request ? input.headers : undefined), version) });
+    };
+}
+function withVersion(headers, version) {
+    // A Headers from another realm or library fails instanceof, and Object.entries would read it as
+    // empty and drop every header the caller sent. Anything iterable that is not an array is copied.
+    if (headers instanceof Headers || (!Array.isArray(headers) && typeof headers?.forEach === "function")) {
+        const copy = new Headers(headers);
+        copy.set(HEADER, version);
+        return copy;
+    }
+    if (Array.isArray(headers))
+        return [...headers.filter(([name]) => name.toLowerCase() !== HEADER), [HEADER, version]];
+    const record = Object.fromEntries(Object.entries(headers ?? {}).filter(([name]) => name.toLowerCase() !== HEADER));
+    record[HEADER] = version;
+    return record;
+}

package/dist/cli.js

@@ -8,6 +8,7 @@ import { existsSync, openSync, closeSync } from "node:fs";
 import { ReadStream as TerminalInput } from "node:tty";
 import { Writable } from "node:stream";
 import { parseArgs, positionals, verbHelp } from "./args.js";
+import { reportCliVersion } from "./cli-version.js";
 import { CONFIG_MODE, DEFAULT_BASE_URL, LEGACY_PACKAGE_NAME, PACKAGE_NAME, cliPath, configPathFor, contractPathFor, defaultCtx, defaultReplicaDbFor, defaultSkillsDirFor, formatMode, installerOwnsSkills, INSTALL_COMMAND, loadConfig, modernCliPath, normalizeBaseUrl, readManifest, requireConfig, saveConfig, writeConfig, } from "./config.js";
 import { loadContract, pickPath } from "./contract.js";
 import { CliError, MeError, UsageError } from "./errors.js";
@@ -280,6 +281,19 @@ export async function main(argv, ctx = defaultCtx(), deps = {}) {
         command: args.command,
         version: manifest.version,
     });
+    ctx = {
+        ...ctx,
+        fetch: reportCliVersion(ctx.fetch, manifest.version, () => {
+            let configured;
+            try {
+                configured = loadConfig(ctx.home)?.baseUrl;
+            }
+            catch {
+                // The command reports its existing config error.
+            }
+            return [args.baseUrl, ctx.env.CATALYST_CLOUD_BASE_URL, configured, DEFAULT_BASE_URL].filter((origin) => typeof origin === "string");
+        }),
+    };
     try {
         if (args.command !== "onboard") {
             migrateLegacyCliPath(ctx);

package/dist/onboard-next.js

@@ -3,6 +3,7 @@ import { GITHUB_CONFIRM_ACCESS } from "./onboard-github-copy.js";
 import { INSTALL_COMMAND, loadConfig, normalizeBaseUrl } from "./config.js";
 import { githubInstallationPage } from "./onboard-permissions.js";
 import { valuesFacts, valuesFix } from "./ready-copy.js";
+import { DEFAULT_HOST_FREE_FLOOR_GIB, isRunnerDiskUnmeasured, runnerDiskCopy } from "./onboard-runner-disk.js";
 /** What a person reads for a step that is not done. Each line ends in an action they can take. */
 const REASONS = {
     legacy_cleanup_failed: "An earlier Catalyst installation could not be removed. Run catalyst legacy --remove to see the exact item and its blocker, fix that blocker, then run catalyst setup again. Shared data folders are kept.",
@@ -158,6 +159,10 @@ const REASONS = {
     runner_compose_not_running: "The runner's supervisor is not running. Run docker compose -p catalyst-host logs supervisor to see why, then run catalyst onboard again.",
     runner_enrollment_unverified: "The runner started but has not enrolled yet. Run docker compose -p catalyst-host logs supervisor to see why, or run catalyst onboard again in a minute.",
     runner_needs_runner_flag: "This machine was set up to run Catalyst's work, but its runner is not running or not enrolled. To bring it up, run catalyst onboard --runner.",
+    runner_host_disk_sampler_python_missing: "Setup needs Python 3 to measure this Mac's disk for the runner. Install Apple's Command Line Tools with xcode-select --install, or python3 from Homebrew, then run catalyst setup --runner.",
+    runner_host_disk_location_unverified: "Setup could not tell which disk holds your Docker engine's virtual machine, so it cannot measure this Mac's free space for the runner. Set CATALYST_HOST_DISK_PATH to that folder (for a relocated Docker Desktop disk image, the folder chosen in Settings, Resources, Advanced), then run catalyst setup --runner.",
+    runner_host_disk_sampler_failed: "Setup could not start the dev.catalystcloud.host-disk LaunchAgent that measures this Mac's disk, so the runner will advertise zero free slots. Run launchctl print gui/$(id -u)/dev.catalystcloud.host-disk, or user/$(id -u)/dev.catalystcloud.host-disk when no one is logged in at the console, to see why, then run catalyst setup --runner.",
+    runner_host_disk_sampler_not_repeating: "Setup loaded the dev.catalystcloud.host-disk LaunchAgent, but launchd did not keep it measuring this Mac's disk: it published no new sample within 25 seconds, so the runner will advertise zero free slots. launchd can hold back an agent loaded from an SSH session. Log in to this Mac's desktop, at the console or over Screen Sharing, and run catalyst setup --runner in Terminal there. To see what launchd did, run launchctl print gui/$(id -u)/dev.catalystcloud.host-disk and read its runs and pended lines.",
     runner_capability_pending: "The runner enrolled but has not reported its capacity yet. Run catalyst onboard again in a minute.",
     runner_admission_unverified: "Setup could not read whether the team's pool admits runner hosts. Run catalyst onboard again to retry.",
     github_app_permissions_outdated: `The existing GitHub App installation needs updated permissions accepted. ${GITHUB_CONFIRM_ACCESS} An organization owner on GitHub opens the App's installation page, chooses Review permissions, then Accept new permissions. Run catalyst onboard afterward.`,
@@ -454,6 +459,26 @@ export function onboardReasonText(step, context = {}) {
             : "on the web app's Account API keys page";
         return `The runner is enrolled, but it takes no work without an organization key. A workspace owner or administrator runs catalyst onboard --runner on this machine; it mints the key and stores it for the runner. If their cloud cannot mint one yet, they create one with the mirror:read, mirror:write and mirror:feed scopes ${where}, save it in a file only they can read, and run catalyst onboard --runner with CATALYST_RUNNER_ORG_KEY_FILE set to that file.`;
     }
+    if (reason === "runner_host_disk_sampler_conflict") {
+        // Both settings are needed: a custom directory turns off setup's sampler, and the sample file
+        // name is then empty unless it is set too.
+        const safe = (value) => typeof value === "string" && /^\/[^\x00-\x1f'"]{0,500}$/.test(value) ? value : null;
+        const dir = safe(step.evidence?.sampleDir) ?? "<directory the other agent writes to>";
+        const file = safe(step.evidence?.sampleFile) ?? "/var/lib/catalyst/host-disk/<its file name>";
+        return `Another dev.catalystcloud.host-disk LaunchAgent on this Mac writes its disk sample somewhere else, so setup left it alone and the runner has no disk measurement. To use that agent's sample, set both CATALYST_HOST_DISK_SAMPLE_DIR=${dir} and CATALYST_HOST_DISK_SAMPLE_FILE=${file}, then run catalyst setup --runner; the directory alone leaves the runner without a sample file. Or remove the other agent: run launchctl bootout gui/$(id -u)/dev.catalystcloud.host-disk and launchctl bootout user/$(id -u)/dev.catalystcloud.host-disk (one of them reports it is not loaded), delete ~/Library/LaunchAgents/dev.catalystcloud.host-disk.plist, then run catalyst setup --runner.`;
+    }
+    if (reason === "runner_host_disk_below_floor" || reason === "runner_host_disk_unmeasured") {
+        const e = step.evidence ?? {};
+        const num = (value) => typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : null;
+        const floorGiB = num(e.floorGiB) ?? DEFAULT_HOST_FREE_FLOOR_GIB, availableGiB = num(e.availableGiB);
+        if (reason === "runner_host_disk_below_floor" && availableGiB === null)
+            return `The runner advertises zero free slots: the disk it measures has less than ${floorGiB} GiB free. Free disk space, then run catalyst ready to see how much is free.`;
+        const detail = typeof e.diskDetail === "string" && isRunnerDiskUnmeasured(e.diskDetail) ? e.diskDetail : "physical_host_disk_sample_required";
+        const copy = runnerDiskCopy(reason === "runner_host_disk_below_floor" && availableGiB !== null
+            ? { state: "below_floor", availableGiB, floorGiB }
+            : { state: "unmeasured", detail, floorGiB }, e.vm === true);
+        return `${copy.line} ${copy.fix}`;
+    }
     if (reason === "runner_host_not_ready") {
         const failing = step.evidence?.failing;
         const checks = typeof failing === "string" && /^[a-z0-9.,_-]{1,500}$/.test(failing)

package/dist/onboard-runner-disk.js

@@ -0,0 +1,345 @@
+import { spawnSync } from "node:child_process";
+import { chmodSync, existsSync, mkdirSync, readFileSync, realpathSync, renameSync, statfsSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { packageRoot } from "./config.js";
+// CTC-5929: a supervisor in a Docker VM cannot measure the Mac's disk, so it refuses all work
+// (`host_disk_unmeasured: physical_host_disk_sample_required`) until a native publisher writes a
+// fresh sample into the read-only `host-disk` bind. Setup installs catalyst-cloud's own publisher
+// (vendor/self-host, byte for byte) as a LaunchAgent, and names a zero-slot disk reason instead of
+// leaving it in the supervisor log. The admission rule itself stays the supervisor's.
+export const HOST_DISK_LABEL = "dev.catalystcloud.host-disk";
+/** The sample path inside the supervisor; compose binds the runner's `host-disk` directory here. */
+export const HOST_DISK_MOUNT = "/var/lib/catalyst/host-disk";
+export const HOST_DISK_SAMPLE_FILE = `${HOST_DISK_MOUNT}/space.json`;
+/** catalyst-cloud apps/host-agent/src/supervisor/disk/host-space.ts and the compose default. */
+const SAMPLE_MAX_AGE_MS = 30_000;
+const SAMPLE_FUTURE_MS = 5_000;
+const MAX_SAMPLE_BYTES = 4_096;
+export const DEFAULT_HOST_FREE_FLOOR_GIB = 25;
+const GIB = 1024 ** 3;
+const gib = (bytes) => Math.floor((bytes / GIB) * 100) / 100;
+function floorGiB(saved) {
+    const value = Number(saved?.CATALYST_HOST_FREE_FLOOR_GIB?.trim() || DEFAULT_HOST_FREE_FLOOR_GIB);
+    return Number.isFinite(value) && value > 0 ? value : DEFAULT_HOST_FREE_FLOOR_GIB;
+}
+/** The supervisor's sample rules: schema 1, at most 30 seconds old, never ahead of the clock. */
+export function hostDiskSampleBytes(text, nowMs) {
+    let sample;
+    try {
+        if (Buffer.byteLength(text) > MAX_SAMPLE_BYTES)
+            return "host_disk_sample_invalid";
+        const value = JSON.parse(text);
+        if (typeof value !== "object" || value === null || Array.isArray(value))
+            return "host_disk_sample_invalid";
+        sample = value;
+    }
+    catch {
+        return "host_disk_sample_invalid";
+    }
+    const { observedAtMs, availableBytes, totalBytes, path } = sample;
+    if (sample.schemaVersion !== 1 || typeof path !== "string" || !path.startsWith("/") ||
+        !Number.isSafeInteger(observedAtMs) || observedAtMs <= 0 ||
+        !Number.isSafeInteger(availableBytes) || availableBytes < 0 ||
+        !Number.isSafeInteger(totalBytes) || totalBytes <= 0 ||
+        availableBytes > totalBytes)
+        return "host_disk_sample_invalid";
+    if (nowMs - observedAtMs > SAMPLE_MAX_AGE_MS || observedAtMs > nowMs + SAMPLE_FUTURE_MS)
+        return "host_disk_sample_stale";
+    return availableBytes;
+}
+/** Where the supervisor's sample file lives on this machine, or null when it is not in the bind. */
+export function hostDiskSamplePath(dir, saved) {
+    const file = saved?.CATALYST_HOST_DISK_SAMPLE_FILE?.trim();
+    if (!file || !file.startsWith(`${HOST_DISK_MOUNT}/`) || file.split("/").some(part => part === ".."))
+        return null;
+    const source = saved?.CATALYST_HOST_DISK_SAMPLE_DIR?.trim() || "./host-disk";
+    return join(isAbsolute(source) ? source : resolve(dir, source), file.slice(HOST_DISK_MOUNT.length + 1));
+}
+/** The same verdict the supervisor reaches, read from this machine. Never an admission decision. */
+export function runnerDiskVerdict(input) {
+    const floor = floorGiB(input.saved);
+    const unmeasured = (detail) => ({ state: "unmeasured", detail, floorGiB: floor });
+    let bytes;
+    if (input.saved?.CATALYST_HOST_DISK_SAMPLE_FILE?.trim()) {
+        const path = hostDiskSamplePath(input.dir, input.saved);
+        if (!path)
+            return unmeasured("host_disk_unreadable");
+        let text;
+        try {
+            text = (input.readSample ?? ((file) => readFileSync(file, "utf8")))(path);
+        }
+        catch {
+            return unmeasured("host_disk_sample_missing");
+        }
+        const read = hostDiskSampleBytes(text, input.nowMs);
+        if (typeof read === "string")
+            return unmeasured(read);
+        bytes = read;
+    }
+    else if (input.vm) {
+        return unmeasured("physical_host_disk_sample_required");
+    }
+    else {
+        try {
+            bytes = input.nativeAvailableBytes?.() ?? null;
+        }
+        catch {
+            bytes = null;
+        }
+        if (bytes === null || !Number.isSafeInteger(bytes) || bytes < 0)
+            return unmeasured("host_disk_unreadable");
+    }
+    return { state: bytes >= floor * GIB ? "measured" : "below_floor", availableGiB: gib(bytes), floorGiB: floor };
+}
+/** Docker's data root, where the supervisor's named state volume lives on native Linux. */
+export function dockerRootAvailableBytes(env) {
+    const read = spawnSync("docker", ["info", "--format", "{{.DockerRootDir}}"], { encoding: "utf8", timeout: 10_000, env });
+    const root = read.status === 0 ? read.stdout.trim() : "";
+    if (!isAbsolute(root))
+        return null;
+    const space = statfsSync(root);
+    return space.bavail * space.bsize;
+}
+const defaultRun = (cmd, args, timeoutMs) => {
+    const r = spawnSync(cmd, args, { encoding: "utf8", timeout: timeoutMs });
+    return { status: r.status ?? 1, stdout: r.stdout ?? "", stderr: r.error ? r.error.message : (r.stderr ?? "") };
+};
+const within = (path, root) => {
+    const rel = relative(root, path);
+    return rel !== "" && !rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel);
+};
+/** Docker Desktop's disk image folder: the relocated one from its settings, else the default. */
+function desktopData(deps, exists) {
+    const read = deps.readText ?? ((path) => readFileSync(path, "utf8"));
+    for (const name of ["settings-store.json", "settings.json"]) {
+        let settings;
+        try {
+            settings = JSON.parse(read(join(deps.home, "Library/Group Containers/group.com.docker", name)));
+        }
+        catch {
+            continue;
+        }
+        const folder = settings.DataFolder ?? settings.dataFolder;
+        if (folder !== undefined)
+            return typeof folder === "string" && isAbsolute(folder) && exists(folder) ? folder : null;
+    }
+    const fallback = join(deps.home, "Library/Containers/com.docker.docker/Data/vms/0/data");
+    return exists(fallback) ? fallback : null;
+}
+/** The filesystem backing the ACTIVE engine's VM disk, from its socket; null when it cannot be
+ * verified, so setup asks for CATALYST_HOST_DISK_PATH instead of measuring the wrong disk. */
+export function engineDiskPath(deps) {
+    const exists = deps.exists ?? existsSync;
+    if (deps.explicitPath !== undefined && deps.explicitPath.trim() !== "")
+        return isAbsolute(deps.explicitPath) && exists(deps.explicitPath) ? deps.explicitPath : null;
+    if (!deps.dockerHost?.startsWith("unix://"))
+        return null;
+    let socket;
+    try {
+        socket = (deps.realpath ?? realpathSync)(deps.dockerHost.slice("unix://".length));
+    }
+    catch {
+        return null;
+    }
+    const home = deps.home;
+    if (within(socket, join(home, ".docker")) || within(socket, join(home, "Library/Containers/com.docker.docker")))
+        return desktopData(deps, exists);
+    if (within(socket, join(home, ".orbstack"))) {
+        const data = join(home, "Library/Group Containers/HUAQ24HBR6.dev.orbstack/data");
+        return exists(data) ? data : null;
+    }
+    // Lima and Colima keep each instance's disk in the instance directory that holds its socket.
+    const lima = /^(.*)\/sock\/docker\.sock$/.exec(socket)?.[1];
+    if (lima && within(lima, join(home, ".lima")) && exists(lima))
+        return lima;
+    const colima = /^(.*)\/docker\.sock$/.exec(socket)?.[1];
+    if (colima && within(colima, join(home, ".colima"))) {
+        const instance = join(home, ".colima", "_lima", `colima${colima.endsWith(`${sep}default`) ? "" : `-${colima.split(sep).at(-1)}`}`);
+        return exists(instance) ? instance : null;
+    }
+    return null;
+}
+/** A stable interpreter. /usr/bin/python3 is a stub that opens an install dialog until the
+ * Command Line Tools exist, so it is used only after xcode-select confirms them. */
+function python(run, exists) {
+    if (exists("/usr/bin/python3") && run("/usr/bin/xcode-select", ["-p"], 5_000).status === 0)
+        return "/usr/bin/python3";
+    return ["/opt/homebrew/bin/python3", "/usr/local/bin/python3"].find(exists) ?? null;
+}
+const xml = (text) => text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+function plan(dir, deps) {
+    const run = deps.run ?? defaultRun;
+    const exists = deps.exists ?? existsSync;
+    const measured = engineDiskPath(deps);
+    if (!measured)
+        return "runner_host_disk_location_unverified";
+    const interpreter = python(run, exists);
+    if (!interpreter)
+        return "runner_host_disk_sampler_python_missing";
+    const vendor = join(packageRoot(), "vendor", "self-host");
+    const script = join(dir, "host-disk-sampler", "host-disk-sample.py");
+    const output = join(dir, "host-disk", "space.json");
+    const values = {
+        __PYTHON__: interpreter, __SCRIPT__: script, __PATH__: measured, __OUTPUT__: output,
+    };
+    const template = readFileSync(join(vendor, "launchd", `${HOST_DISK_LABEL}.plist`), "utf8");
+    const plistText = template.replace(/<string>(__[A-Z]+__)<\/string>/g, (whole, key) => key in values ? `<string>${xml(values[key])}</string>` : whole);
+    const program = /<key>ProgramArguments<\/key>\s*<array>([\s\S]*?)<\/array>/.exec(template)?.[1] ?? "";
+    const command = [...program.matchAll(/<string>([^<]*)<\/string>/g)].map(m => values[m[1]] ?? m[1]);
+    const at = command.indexOf("--interval");
+    return {
+        script, output, plistText, command, interval: Number(command[at + 1]),
+        plist: join(deps.home, "Library", "LaunchAgents", `${HOST_DISK_LABEL}.plist`),
+        scriptBytes: readFileSync(join(vendor, "host-disk-sample.py")),
+    };
+}
+const readOr = (path) => {
+    try {
+        return readFileSync(path);
+    }
+    catch {
+        return null;
+    }
+};
+/** The file a host-disk agent's plist publishes to (its `--output`), unescaped; null when it names none. */
+export function hostDiskAgentOutput(text) {
+    const raw = /<string>--output<\/string>\s*<string>([^<]*)<\/string>/.exec(text)?.[1];
+    return raw === undefined ? null : raw.replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&amp;/g, "&");
+}
+/** A plist with this label that publishes somewhere else belongs to its operator. */
+function foreign(existing, output) {
+    return hostDiskAgentOutput(existing.toString("utf8")) !== output;
+}
+/** Where a same-label agent this setup does not own publishes, as the two settings that would
+ * point the runner at it: the bind directory and the in-container file name. */
+export function foreignHostDiskSample(home) {
+    const text = readOr(join(home, "Library", "LaunchAgents", `${HOST_DISK_LABEL}.plist`))?.toString("utf8");
+    const output = text && hostDiskAgentOutput(text);
+    if (!output || !isAbsolute(output) || !/^[^\x00-\x1f'"]+$/.test(output))
+        return {};
+    return { sampleDir: dirname(output), sampleFile: `${HOST_DISK_MOUNT}/${output.split("/").at(-1)}` };
+}
+/** The launchd domain holding the agent: gui when someone is logged in at the console, else user. */
+function loadedIn(run, uid) {
+    for (const domain of [`gui/${uid}`, `user/${uid}`])
+        if (run("/bin/launchctl", ["print", `${domain}/${HOST_DISK_LABEL}`], 5_000).status === 0)
+            return domain;
+    return null;
+}
+function writeAtomic(path, bytes, mode) {
+    mkdirSync(dirname(path), { recursive: true, mode: 0o755 });
+    const temporary = `${path}.${process.pid}.tmp`;
+    writeFileSync(temporary, bytes, { mode });
+    chmodSync(temporary, mode);
+    renameSync(temporary, path);
+}
+function observedAt(output) {
+    try {
+        const value = JSON.parse(readOr(output)?.toString("utf8") ?? "");
+        const at = value?.observedAtMs;
+        return Number.isSafeInteger(at) ? at : null;
+    }
+    catch {
+        return null;
+    }
+}
+const sleepSync = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+/** The positive cadence check: the agent itself publishes two new samples, one interval apart.
+ * Loaded is not running: launchd held every launch of an agent bootstrapped over SSH (CTC-5929). */
+function repeats(p, deps) {
+    const sleep = deps.sleep ?? sleepSync;
+    const seen = new Set();
+    const before = observedAt(p.output);
+    const deadline = deps.now() + (2 * p.interval + 5) * 1_000;
+    while (deps.now() < deadline) {
+        const at = observedAt(p.output);
+        if (at !== null && at !== before && sampleFresh(p.output, deps.now()))
+            seen.add(at);
+        if (seen.size >= 2)
+            return true;
+        sleep(1_000);
+    }
+    return false;
+}
+function sampleFresh(output, nowMs) {
+    const text = readOr(output);
+    return text !== null && typeof hostDiskSampleBytes(text.toString("utf8"), nowMs) === "number";
+}
+export function hostDiskSamplerStatus(dir, deps) {
+    const p = plan(dir, deps);
+    if (typeof p === "string")
+        return p;
+    const plist = readOr(p.plist);
+    if (plist && !plist.equals(Buffer.from(p.plistText)) && foreign(plist, p.output))
+        return "runner_host_disk_sampler_conflict";
+    return plist?.equals(Buffer.from(p.plistText)) && readOr(p.script)?.equals(p.scriptBytes) &&
+        loadedIn(deps.run ?? defaultRun, deps.uid) && sampleFresh(p.output, deps.now()) ? "installed" : "missing";
+}
+/** Installs or repairs the agent in place. Idempotent: an unchanged, loaded agent is left running.
+ * A same-label agent publishing elsewhere is never replaced. */
+export function installHostDiskSampler(dir, deps) {
+    const run = deps.run ?? defaultRun;
+    const p = plan(dir, deps);
+    if (typeof p === "string")
+        return p;
+    const existing = readOr(p.plist);
+    const plistChanged = !existing?.equals(Buffer.from(p.plistText));
+    if (existing && plistChanged && foreign(existing, p.output))
+        return "runner_host_disk_sampler_conflict";
+    try {
+        // The plist does not carry the script's bytes, so a changed script needs its own reload: a
+        // running agent keeps the code it started with until launchd starts it again.
+        const scriptChanged = !readOr(p.script)?.equals(p.scriptBytes);
+        if (scriptChanged)
+            writeAtomic(p.script, p.scriptBytes, 0o644);
+        // One synchronous sample proves the interpreter and the measured path before launchd owns it.
+        // Without --interval the script publishes once and exits; with it, it loops.
+        const loop = p.command.indexOf("--interval");
+        const oneShot = loop < 0 ? p.command : [...p.command.slice(0, loop), ...p.command.slice(loop + 2)];
+        const once = run(oneShot[0], oneShot.slice(1), 15_000);
+        if (once.status !== 0 || !sampleFresh(p.output, deps.now()))
+            return "runner_host_disk_sampler_failed";
+        if (plistChanged)
+            writeAtomic(p.plist, p.plistText, 0o644);
+        let domain = loadedIn(run, deps.uid);
+        if (domain && (plistChanged || scriptChanged)) {
+            run("/bin/launchctl", ["bootout", `${domain}/${HOST_DISK_LABEL}`], 15_000);
+            domain = null;
+        }
+        if (!domain) {
+            const gui = run("/bin/launchctl", ["bootstrap", `gui/${deps.uid}`, p.plist], 15_000).status === 0;
+            if (!gui && run("/bin/launchctl", ["bootstrap", `user/${deps.uid}`, p.plist], 15_000).status !== 0)
+                return "runner_host_disk_sampler_failed";
+        }
+        domain = loadedIn(run, deps.uid);
+        if (!domain)
+            return "runner_host_disk_sampler_failed";
+        // A demand start: launchd ran a kickstarted agent on mini-2 while it held RunAtLoad and the
+        // timer. The script loops by itself once started, and a running agent is left as it is.
+        run("/bin/launchctl", ["kickstart", `${domain}/${HOST_DISK_LABEL}`], 15_000);
+        return repeats(p, deps) ? "ready" : "runner_host_disk_sampler_not_repeating";
+    }
+    catch {
+        return "runner_host_disk_sampler_failed";
+    }
+}
+export const isRunnerDiskUnmeasured = (value) => value in UNMEASURED_WHY;
+const UNMEASURED_WHY = {
+    physical_host_disk_sample_required: "no disk sampler is set up for it",
+    host_disk_sample_missing: "the disk sample file is missing",
+    host_disk_sample_stale: "the last disk sample is more than 30 seconds old",
+    host_disk_sample_invalid: "the disk sample cannot be read",
+    host_disk_unreadable: "setup cannot read the disk it measures",
+};
+/** One wording for setup and `catalyst ready`: the reason for zero free slots, then the fix. */
+export function runnerDiskCopy(verdict, vm) {
+    if (verdict.state === "below_floor")
+        return {
+            line: `The runner advertises zero free slots: ${verdict.availableGiB} GiB of disk is free and it needs ${verdict.floorGiB} GiB.`,
+            fix: `Free at least ${Math.ceil(verdict.floorGiB - verdict.availableGiB)} GiB on ${vm ? "this Mac" : "the disk that holds Docker's data"}, for example with docker system prune. The runner takes work again by itself; run catalyst ready to confirm.`,
+        };
+    const line = `The runner advertises zero free slots: it has no fresh measurement of ${vm ? "this Mac's" : "this machine's"} disk, because ${UNMEASURED_WHY[verdict.detail]}.`;
+    return vm
+        ? { line, fix: `Run catalyst setup --runner. It installs and starts the ${HOST_DISK_LABEL} LaunchAgent, which measures the disk every 10 seconds. If it is already installed, run launchctl print gui/$(id -u)/${HOST_DISK_LABEL}, or user/$(id -u)/${HOST_DISK_LABEL} when no one is logged in at the console, to see why it stopped. If you publish your own sample with CATALYST_HOST_DISK_SAMPLE_DIR and CATALYST_HOST_DISK_SAMPLE_FILE, restart that publisher.` }
+        : { line, fix: "Run docker compose -p catalyst-host logs supervisor and look for host_disk_admission_refused, then run catalyst ready." };
+}

package/dist/onboard-runner.js

@@ -8,6 +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 { dockerRootAvailableBytes, foreignHostDiskSample, hostDiskSamplerStatus, installHostDiskSampler, runnerDiskVerdict, HOST_DISK_SAMPLE_FILE, } from "./onboard-runner-disk.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";
@@ -69,6 +70,8 @@ const DISK_POLICY_KEYS = [
     "CATALYST_SLOT_DISK_MODE", "CATALYST_SLOT_DISK_BUDGET_GIB", "CATALYST_DISK_BUDGET_GIB",
     "CATALYST_WORKSPACE_STORAGE", "CATALYST_WORKSPACE_RETENTION_HOURS",
     "CATALYST_HOST_FREE_FLOOR_GIB", "CATALYST_HOST_DISK_SAMPLE_DIR", "CATALYST_HOST_DISK_SAMPLE_FILE",
+    // Not read by Compose: where the Mac sampler measures, kept so unattended checks plan the same path.
+    "CATALYST_HOST_DISK_PATH",
 ];
 function isUnenrolled(value) {
     return value !== null && "unenrolled" in value;
@@ -549,6 +552,20 @@ export function dockerRunnerEngine(deps = {}) {
             return (read.code === 0 &&
                 read.stdout.split("\n").some((line) => line.trim() === "supervisor"));
         },
+        async hostDisk(dir, vm) {
+            return runnerDiskVerdict({ dir, saved: readEnvFile(join(dir, ".env")), vm, nowMs: Date.now(),
+                nativeAvailableBytes: () => dockerRootAvailableBytes(env) });
+        },
+        ...((deps.platform ?? process.platform) === "darwin" ? {
+            async hostDiskSamplerStatus(dir, options) {
+                return hostDiskSamplerStatus(dir, { home: deps.env?.HOME ?? process.env.HOME ?? "", uid: process.getuid?.() ?? 0,
+                    now: Date.now, dockerHost: await endpoint(), ...options });
+            },
+            async installHostDiskSampler(dir, options) {
+                return installHostDiskSampler(dir, { home: deps.env?.HOME ?? process.env.HOME ?? "", uid: process.getuid?.() ?? 0,
+                    now: Date.now, dockerHost: await endpoint(), ...options });
+            },
+        } : {}),
     };
 }
 const serves = (host, teamKey) => host.teams.includes(teamKey);
@@ -590,6 +607,7 @@ function parseHosts(body) {
             capacity: capability ? capability.runtimeLive
                 ? capability.placeableCapacity
                 : 0 : null,
+            live: capability?.runtimeLive === true,
             failing: capability ? capability.failingRequired : [],
         });
     }
@@ -790,6 +808,7 @@ export function onboardRunnerAdapter(input = {}) {
         const gid = p.info.vm ? 0 : await engine.socketGid();
         if (!HOST_NAME.test(name) || gid === null)
             return null;
+        const sampler = samplerManaged(p, ctx, saved);
         return {
             DOCKER_SOCKET_PATH: "/var/run/docker.sock",
             DOCKER_SOCKET_GID: String(gid),
@@ -808,10 +827,22 @@ export function onboardRunnerAdapter(input = {}) {
                 CATALYST_THOUGHTS_CUSTODY_RESPONSES_DIR: receivedCustody.result.responsesRoot,
             } : {}),
             CATALYST_SESSION_EGRESS_DIR: p.info.vm ? join(p.dir, "session-egress") : NATIVE_EGRESS_DIR,
+            ...(sampler ? { CATALYST_HOST_DISK_SAMPLE_FILE: HOST_DISK_SAMPLE_FILE } : {}),
             // Saved policy stays in merged(). An explicit value in this run overrides it.
             ...Object.fromEntries(DISK_POLICY_KEYS.flatMap(key => ctx.env[key] === undefined ? [] : [[key, ctx.env[key]]])),
         };
     }
+    /** CTC-5929: setup publishes the Mac's disk sample into the install's own `host-disk` bind. A
+     * custom sample directory or file belongs to its operator, who also runs its publisher. */
+    function samplerManaged(p, ctx, saved) {
+        const custom = (key) => (ctx.env[key] ?? saved?.[key] ?? "").trim();
+        return p.info.vm && engine.installHostDiskSampler !== undefined && custom("CATALYST_HOST_DISK_SAMPLE_DIR") === "" &&
+            ["", HOST_DISK_SAMPLE_FILE].includes(custom("CATALYST_HOST_DISK_SAMPLE_FILE"));
+    }
+    const samplerOptions = (ctx, saved) => {
+        const explicitPath = ctx.env.CATALYST_HOST_DISK_PATH ?? saved?.CATALYST_HOST_DISK_PATH;
+        return explicitPath ? { explicitPath } : {};
+    };
     /** The step owns its own keys only; a person's tuning (CATALYST_SLOTS and the rest) is kept. */
     const merged = (saved, want) => ({
         ...want,
@@ -947,6 +978,12 @@ export function onboardRunnerAdapter(input = {}) {
             const name = want.CATALYST_HOST_NAME;
             if (p.info.vm && persistedCustody(p.dir, saved) !== "installed")
                 return mayAct && !afterAct ? { state: "pending" } : waiting(mayAct ? "runner_thoughts_custody_unavailable" : "runner_needs_runner_flag", { ...selected, hostName: name });
+            if (samplerManaged(p, ctx, saved) && engine.hostDiskSamplerStatus) {
+                const sampler = await engine.hostDiskSamplerStatus(p.dir, samplerOptions(ctx, saved));
+                if (sampler !== "installed")
+                    return mayAct && !afterAct ? { state: "pending" } : waiting(!mayAct ? "runner_needs_runner_flag" : sampler === "missing" ? "runner_host_disk_sampler_failed" : sampler, { ...selected, hostName: name,
+                        ...(sampler === "runner_host_disk_sampler_conflict" ? foreignHostDiskSample(ctx.home) : {}) });
+            }
             let enrolled = null;
             const live = (hosts) => hosts?.find((host) => host.hostId === enrolled?.hostId && serves(host, p.teamKey) && !host.revoked);
             let hosts = await listHosts(ctx, p, signal);
@@ -1023,6 +1060,15 @@ export function onboardRunnerAdapter(input = {}) {
                 return pending();
             if (keyStatus !== "valid")
                 return waiting(keyStatus === "missing" ? "runner_org_key_missing" : keyStatus === "invalid" ? "runner_org_key_invalid" : "runner_org_key_unavailable", evidence);
+            if (host.capacity === 0 && host.live && host.failing.length === 0) {
+                // The supervisor advertises zero slots when disk admission refuses; its reason stays in its log.
+                const disk = await engine.hostDisk?.(p.dir, p.info.vm);
+                if (disk && disk.state !== "measured")
+                    return waiting(disk.state === "below_floor" ? "runner_host_disk_below_floor" : "runner_host_disk_unmeasured", {
+                        ...evidence, floorGiB: disk.floorGiB, vm: p.info.vm,
+                        ...(disk.state === "below_floor" ? { availableGiB: disk.availableGiB } : { diskDetail: disk.detail }),
+                    });
+            }
             if (host.capacity === 0 || host.failing.length > 0)
                 return waiting("runner_host_not_ready", { ...evidence, failing: host.failing.join(",") });
             if (p.cloud) {
@@ -1166,6 +1212,12 @@ export function onboardRunnerAdapter(input = {}) {
                         (advice ? " " + advice : ""), details, signal);
                 }
             }
+            if (samplerManaged(p, ctx, readEnvFile(join(p.dir, ".env"))) && engine.installHostDiskSampler) {
+                const sampler = await engine.installHostDiskSampler(p.dir, samplerOptions(ctx, readEnvFile(join(p.dir, ".env"))));
+                if (sampler !== "ready")
+                    return waiting(sampler, sampler === "runner_host_disk_sampler_conflict"
+                        ? { ...selected, ...foreignHostDiskSample(ctx.home) } : selected);
+            }
             if (!writeEnv(want))
                 return { state: "failed", reason: "runner_directory_unavailable", evidence: selected };
             const network = await engine.network(RUNNER_SESSION_NETWORK, signal);

package/dist/onboard.js

@@ -324,6 +324,14 @@ function normalizeStep(value, fallbackAt) {
         "custodyResultInstalled",
         "custodyAuthorityMatched",
         "custodyTelemetry",
+        // CTC-5929: the runner's disk reason and a foreign sampler's paths. Without them the saved
+        // step read back as "no disk sampler" on a Linux host that was below its floor.
+        "floorGiB",
+        "availableGiB",
+        "vm",
+        "diskDetail",
+        "sampleDir",
+        "sampleFile",
     ]) {
         const item = evidence?.[key];
         if (item === null ||