@catalyst-cloud/cli 0.16.27 → 0.16.29

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

package/dist/ready.js

@@ -16,7 +16,9 @@ import { installedBundleVersion } from "./skills.js";
 import { onboardingReadyReport, observeCloudOnboarding, } from "./onboard-ready.js";
 import { selectedOnboardTeam } from "./onboard-existing.js";
 import { dispatchGateCopy, teamCheckCopy, valuesFix, whoFixes } from "./ready-copy.js";
-import { onboardStatePath, readOnboardJournal } from "./onboard.js";
+import { onboardStatePath, onboardStateRoot, readOnboardJournal } from "./onboard.js";
+import { dockerRunnerEngine, readEnvFile, RUNNER_HOST_IMAGES } from "./onboard-runner.js";
+import { dockerRootAvailableBytes, runnerDiskCopy, runnerDiskVerdict } from "./onboard-runner-disk.js";
 export { semverOlder };
 /** `ready`'s own wording for the replica. It never recommends adopting the replica — until the
  *  mirror's snapshot path is safe for a large tenant, a customer following that advice is the
@@ -112,6 +114,35 @@ export function catalystCommandCheck(env, platform = process.platform) {
             "Keep using catalyst-skills on this machine, or put the npm global bin directory ahead of that one on PATH.",
     };
 }
+/** CTC-5929: the disk admission the supervisor applies, read from the runner installed here. The
+ * running catalyst-host project names its own directory, so a moved state root is still found; the
+ * state root is only the fallback when Docker shows no such project or cannot be listed.
+ * A Mac runs the engine in a VM, so only the native sample counts; Linux measures Docker's data root. */
+async function localRunnerDisk(ctx, engine) {
+    let dir = null;
+    const containers = await engine.projectContainers?.().catch(() => null);
+    if (containers?.some(row => row.service === "supervisor")) {
+        const installed = await engine.installation?.(ctx.home, ctx.env.CATALYST_SUPERVISOR_IMAGE ?? RUNNER_HOST_IMAGES.supervisor)
+            .catch(() => "unverified");
+        if (!installed || typeof installed === "string")
+            return { unverified: true };
+        dir = installed.dir;
+    }
+    else {
+        try {
+            dir = join(onboardStateRoot(ctx.home, ctx.env), "runner");
+        }
+        catch {
+            return null;
+        }
+    }
+    const saved = readEnvFile(join(dir, ".env"));
+    if (!saved?.CATALYST_SUPERVISOR_IMAGE)
+        return containers?.length ? { unverified: true } : null;
+    const vm = process.platform === "darwin";
+    return { vm, verdict: runnerDiskVerdict({ dir, saved, vm, nowMs: ctx.now().getTime(),
+            nativeAvailableBytes: () => dockerRootAvailableBytes(ctx.env) }) };
+}
 export async function readyReport(ctx, deps) {
     const checks = [];
     const facts = deps.runtime ?? detectRuntime();
@@ -311,6 +342,21 @@ export async function readyReport(ctx, deps) {
             who: "you",
         });
     }
+    const disk = await (deps.runnerDisk ?? (() => localRunnerDisk(ctx, deps.runnerEngine ?? dockerRunnerEngine({ env: ctx.env }))))();
+    if (disk && "unverified" in disk) {
+        checks.push({ id: "runner:disk", ok: false, note: true,
+            line: "runner disk: a catalyst-host runner is installed here, but ready could not verify its installation to read its disk measurement",
+            fix: "run catalyst setup --runner, which checks the installation and names what is wrong" });
+    }
+    else if (disk) {
+        if (disk.verdict.state === "measured")
+            checks.push({ id: "runner:disk", ok: true,
+                line: `runner disk: ${disk.verdict.availableGiB} GiB free, at least ${disk.verdict.floorGiB} GiB needed` });
+        else {
+            const copy = runnerDiskCopy(disk.verdict, disk.vm);
+            checks.push({ id: "runner:disk", ok: false, line: `runner disk: ${copy.line}`, fix: copy.fix, who: "you" });
+        }
+    }
     const replica = replicaStatus(ctx, cfg);
     checks.push({
         id: "replica",

package/dist/runner.js

@@ -8,6 +8,7 @@ import { loadConfig } from "./config.js";
 import { CliError, UsageError } from "./errors.js";
 import { onboardStateRoot } from "./onboard.js";
 import { dockerRunnerEngine, RUNNER_PROJECT, RUNNER_SESSION_NETWORK } from "./onboard-runner.js";
+import { HOST_DISK_LABEL, hostDiskAgentOutput } from "./onboard-runner-disk.js";
 import { EGRESS_ARTIFACTS, NATIVE_EGRESS_DIR } from "./onboard-runner-egress.js";
 import { stdinIsTty } from "./prompt.js";
 import { apiClient } from "./transport.js";
@@ -23,7 +24,7 @@ const COMPOSE_VOLUMES = ["supervisor-state", "host-credential"].map(v => `${RUNN
 const COMPOSE_FILES = ["compose.yaml", "compose.darwin-thoughts.yaml"];
 /** Files setup writes into the runner directory. The work folders are listed separately. */
 const SETUP_FILES = [...COMPOSE_FILES, ".env", "key-request.json"];
-const SETUP_DIRS = ["session-egress", "host-disk"];
+const SETUP_DIRS = ["session-egress", "host-disk", "host-disk-sampler"];
 /** Repository checkouts, the thoughts checkout and their locks: kept unless the owner says so. */
 const WORK_DIRS = ["slots", "thoughts", "locks"];
 const DARWIN_SIBLINGS = ["darwin-thoughts-custody", "darwin-thoughts-requests", "darwin-thoughts-responses"];
@@ -68,6 +69,20 @@ const exists = (path) => { try {
 catch {
     return false;
 } };
+/** Setup's disk sampler publishes into this runner's own host-disk bind; a same-label agent that
+ * writes elsewhere is its operator's, as setup treats it (CTC-5929). */
+function samplerIsSetups(text, runnerDir) {
+    const output = hostDiskAgentOutput(text);
+    if (!output || !runnerDir || basename(output) !== "space.json")
+        return false;
+    const real = (path) => { try {
+        return realpathSync(path);
+    }
+    catch {
+        return path;
+    } };
+    return real(dirname(output)) === real(join(runnerDir, "host-disk"));
+}
 /** The onboarding engine's reads, through this command's own runner. */
 function dockerEnvRun(run) {
     return (args, options) => run("docker", args, { input: options.input, timeoutMs: options.timeoutMs });
@@ -512,7 +527,9 @@ async function uninstall(args, ctx, deps, inst) {
     for (const agent of darwinAgents) {
         let ours = false;
         try {
-            ours = owned(agent.plist, uid, "file") && readFileSync(agent.plist, "utf8").includes(`<string>${agent.label}</string>`);
+            const text = readFileSync(agent.plist, "utf8");
+            ours = owned(agent.plist, uid, "file") && text.includes(`<string>${agent.label}</string>`) &&
+                (agent.label !== HOST_DISK_LABEL || samplerIsSetups(text, runnerDir));
         }
         catch { /* unreadable */ }
         if (!ours) {

package/dist/watch/consumer.js

@@ -112,6 +112,7 @@ export function createLiveEventsClient(sdk, opts) {
         baseUrl: opts.baseUrl,
         accountId: opts.accountId,
         auth: opts.auth,
+        connectParams: () => opts.cliVersion ? { cli_version: opts.cliVersion } : undefined,
         reseed: reseedHead,
         getCursor: () => state?.cursor ?? null,
         onChange: (frame) => {

package/dist/watch.js

@@ -4,7 +4,7 @@
 // an issue reference to its project through GET /api/v1/issues/:ref, cached in memory.
 import { spawn } from "node:child_process";
 import { flagList, flagString } from "./args.js";
-import { apiBase, requireConfig, watchCursorPathFor } from "./config.js";
+import { apiBase, requireConfig, readManifest, watchCursorPathFor } from "./config.js";
 import { loadContract } from "./contract.js";
 import { CliError, UsageError } from "./errors.js";
 import { apiClient } from "./transport.js";
@@ -136,6 +136,7 @@ export async function runWatch(ctx, cfg, opts, deps = {}) {
         return createLiveEventsClient(sdk, {
             baseUrl: apiBase(cfg),
             accountId: cfg.account,
+            cliVersion: readManifest().version,
             auth: authStrategyFor(ctx, cfg),
             getToken: () => bearerFor(ctx, cfg),
             cursorFile: opts.cursorFile ?? watchCursorPathFor(ctx.home),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catalyst-cloud/cli",
-  "version": "0.16.27",
+  "version": "0.16.29",
   "description": "Set up Catalyst Cloud, check your tickets and manage your account from the command line.",
   "license": "MIT",
   "type": "module",
@@ -53,16 +53,16 @@
     "prepublishOnly": "node scripts/release-train-check.mjs --publish cli"
   },
   "dependencies": {
-    "@catalyst-cloud/sdk": "0.16.11",
+    "@catalyst-cloud/sdk": "0.16.19",
     "@clack/prompts": "1.8.1",
     "fast-string-width": "3.0.2",
     "fast-wrap-ansi": "0.2.2",
     "smol-toml": "^1.7.1",
     "yaml": "^2.9.0",
-    "@catalyst-cloud/sdk-replica-node": "0.16.11"
+    "@catalyst-cloud/sdk-replica-node": "0.16.19"
   },
   "devDependencies": {
-    "@catalyst-cloud/schema": "0.16.9",
+    "@catalyst-cloud/schema": "0.16.16",
     "@types/node": "^26.3.0",
     "@vitest/coverage-v8": "^4.1.11",
     "typescript": "^7.0.2",