@catalyst-cloud/cli 0.16.28 → 0.16.30

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.16.30
+
+An agent seat can now hold a ticket while it works on it. `catalyst lease take <ticket> --agent <seat>` takes the ticket for that seat for a set time (`--ttl <minutes>`). `catalyst lease renew <ticket>` keeps it, and each renewal names one piece of progress: a commit (`--commit`), an artifact (`--artifact`), a finding (`--finding`) or a pull request (`--pr`). `catalyst lease release <ticket>` hands it back, and `catalyst lease show <ticket>` prints who holds it. A refused renewal, for example one that names no new progress, prints the reason and exits 1. A renewal or release refused because the lease already lapsed, or because another seat took the ticket, forgets the lease this machine stored. The machine stores only the seat name and the lease generation, in a file only you can read. New: `catalyst work available` lists, per team, the tickets nobody holds, with the last holder and their progress, and the open pull requests no live lease covers, drafts included. Both commands use your login. Setup run unattended now says what it skipped and names the exact flags each skipped choice needs. The skill references now say how to see whether a repository is paused, and who can pause or resume it.
+
+## 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/args.js

@@ -508,6 +508,19 @@ export const FLAG_TABLES = {
             help: "with --remove: answer the question yes (a run with no terminal only reports otherwise)",
         },
     },
+    lease: {
+        agent: { value: true, help: "the seat's name, 1 to 40 of a-z, 0-9 and - (take: required; renew, release: when this machine holds the ticket for several seats)" },
+        ttl: { value: true, help: "take, renew: minutes until the lease lapses without a renewal (the cloud keeps it between 5 and 60; default 30)" },
+        commit: { value: true, help: "renew: the full 40-character sha of a commit you pushed" },
+        artifact: { value: true, help: "renew: a thoughts path or check-run id you wrote" },
+        finding: { value: true, help: "renew: a comment or review id you posted" },
+        pr: { value: true, help: "renew: the number of a pull request you opened" },
+        note: { value: true, help: "renew: a few words about the progress (not part of what counts as new)" },
+        generation: { value: true, help: "renew, release: the generation the take printed (default: the one this machine stored)" },
+    },
+    work: {
+        team: { value: true, help: "available: one team's key (default: every team in the workspace contract)" },
+    },
     repo: {
         reason: { value: true, help: "pause: required; resume: optional; 1 to 500 characters after trimming (owner or admin)" },
         write: {
@@ -594,6 +607,8 @@ export const VERB_USAGE = {
     messages: "messages read --ticket CTC-N [--since SEQUENCE] [--json]",
     capabilities: "capabilities [--json]",
     project: "project <list [--json] | wip-limit <get|set <n>|set default> [--team K] [--json]>",
+    lease: "lease <take <ticket> --agent <seat> [--ttl <minutes>] | renew <ticket> (--commit <sha>|--artifact <path or id>|--finding <id>|--pr <number>) [--note <text>] [--agent <seat>] [--generation <n>] | release <ticket> [--agent <seat>] [--generation <n>] | show <ticket>> [--json]   (a seat's ticket lease: take, renew with new progress, release, read; needs login)",
+    work: "work available [--team K] [--json]   (per team: tickets nobody holds, with the last holder and progress, and open pull requests no live lease covers, drafts included)",
     repo: "repo <status|pause <owner/name> --reason <text>|resume <owner/name> [--reason <text>]|agents-block <path> [--write]|agent-setup <path> [--apply] [--with-check]> [--json]   (status: visible workspace repositories; agents-block/agent-setup: local checkout)",
     legacy: "legacy [--remove [--data] [--yes]] [--json]",
     connections: "connections personal <linear|github> <start|status> [--wait <seconds>] [--json]",

package/dist/capabilities.js

@@ -32,6 +32,8 @@ export const CAPABILITIES = [
     { verb: "project wip-limit set", does: "set a project's new-start WIP limit (0 to 9999, or back to the workspace default)", needs: "admin", routes: [agent("POST", "team-wip-limit")], since: "0.13.1" },
     { verb: "repo status", does: "list visible repositories with their state, pause details and projects", needs: "member", routes: [agent("GET", "repos")], since: "0.16.27" },
     { verb: "repo pause|resume", does: "pause or resume a repository as a workspace owner or admin", needs: "admin", routes: [agent("GET", "repos"), agent("POST", "repos/pause"), agent("POST", "repos/resume")], since: "0.16.27" },
+    { verb: "lease take|renew|release|show", does: "hold the ticket a seat works through a ticket lease that lapses without new progress, instead of a label", needs: "member", routes: [agent("POST", "ticket-lease/take"), agent("POST", "ticket-lease/renew"), agent("POST", "ticket-lease/release"), agent("GET", "ticket-lease")], since: "0.16.30" },
+    { verb: "work available", does: "list tickets nobody holds, with the last holder and progress, and open pull requests no lease covers", needs: "member", routes: [], since: "0.16.30" },
     { verb: "repo agents-block", does: "add or refresh the one Catalyst block in a checkout's AGENTS.md, in the working tree, for the person to commit and open as a pull request", needs: "member", routes: [], since: "0.13.1" },
     { verb: "repo agent-setup", does: "read a checkout's agent setup (AGENTS.md, CLAUDE.md, .agents and .claude skills and rules) and, on request, make it portable in the working tree", needs: "member", routes: [], since: "0.13.1" },
     { verb: "env shell", does: "open this repository's environment on this computer: Catalyst's image, the declared toolchain and variables (needs Docker; no login for Catalyst's image)", needs: "member", routes: [], since: "0.16.20" },

package/dist/cli-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";
@@ -45,6 +46,7 @@ import { cmdTeam } from "./team.js";
 import { cmdCapabilities } from "./capabilities.js";
 import { cmdProject } from "./project.js";
 import { cmdRepo } from "./repo.js";
+import { cmdLease, cmdWork } from "./lease.js";
 import { cmdLegacy } from "./legacy.js";
 import { cmdIdentity } from "./identity.js";
 import { cmdMessages } from "./messages.js";
@@ -112,6 +114,8 @@ export function usageText() {
         "  catalyst repo pause <owner/name> --reason <text> | repo resume <owner/name> [--reason <text>]   (owner or admin; reason: 1 to 500 trimmed characters)",
         "  catalyst repo status [--json]   (visible workspace repositories and their paused state; needs login)",
         "  catalyst repo <agents-block <path> [--write]|agent-setup <path> [--apply] [--with-check]>   (a checkout's AGENTS.md block and portable agent layout; working tree only)",
+        "  catalyst lease <take <ticket> --agent <seat> [--ttl <minutes>]|renew <ticket> --commit|--artifact|--finding|--pr <ref> [--note <text>]|release <ticket>|show <ticket>> [--json]   (a seat's ticket lease; needs login)",
+        "  catalyst work available [--team K] [--json]   (tickets nobody holds and open pull requests no lease covers)",
         "  catalyst legacy [--remove [--data] [--yes]]   (leftovers of the old local Catalyst runtime: list them; remove them only on a yes)",
         "  catalyst identity linear <status|options|set> [<linearUserId>] [--json]",
         "  catalyst messages read --ticket CTC-N [--since SEQUENCE] [--json]   (messages sent to a ticket on your teams)",
@@ -280,6 +284,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);
@@ -534,6 +551,10 @@ export async function main(argv, ctx = defaultCtx(), deps = {}) {
                 return await cmdProject(args, ctx);
             case "repo":
                 return await cmdRepo(args, ctx);
+            case "lease":
+                return await cmdLease(args, ctx);
+            case "work":
+                return await cmdWork(args, ctx);
             case "legacy":
                 return await cmdLegacy(args, ctx, { localSyncSelected: savedLocalSync(ctx), ...deps.legacy });
             case "identity":
@@ -610,6 +631,8 @@ const VERB_HELP_KNOWN = Object.fromEntries([
     "capabilities",
     "project",
     "repo",
+    "lease",
+    "work",
     "legacy",
     "onboard",
 ].map((v) => [v, true]));

package/dist/lease.js

@@ -0,0 +1,302 @@
+// lease.ts — `catalyst lease` and `catalyst work available` (CTC-6400): a seat or one-shot session
+// holds the ticket it works through a ticket lease, never a label, and sees what work is free.
+//
+//   lease take <TICKET> --agent <name> [--ttl <minutes>]     POST /api/v1/agent/ticket-lease/take
+//   lease renew <TICKET> --commit|--artifact|--finding|--pr <ref> [--note <text>]
+//                                                             POST /api/v1/agent/ticket-lease/renew
+//   lease release <TICKET>                                    POST /api/v1/agent/ticket-lease/release
+//   lease show <TICKET>                                       GET  /api/v1/agent/ticket-lease?ticket=
+//   work available [--team K]                                 GET  /api/v1/work-eligibility?team=
+//
+// ⛔ THE KEY IS THE CREDENTIAL. The cloud mints no lease credential (CTC-6398): it derives the holder
+// `seat:<keyId>:<agent>` from the login on every call. What this machine keeps per lease is only what
+// the next call must name: the seat name and the generation the take returned, in a 0600 file under
+// the config directory. Renew and release read it, so a seat names the ticket and its progress.
+//
+// ⭐ A REFUSAL IS A 200. The store answers `outcome: "refused"` with a reason (`no_new_progress`,
+// `ticket_lease_held`, `not_holder`, …); this module prints it and exits 1, so a script can stop on
+// it. A malformed request (400), a seat that does not reach the ticket's team (403) and an exhausted
+// budget (429) exit 1 the same way, with the server's reason.
+import { mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync, chmodSync } from "node:fs";
+import { join } from "node:path";
+import { flagString, positionals } from "./args.js";
+import { CONFIG_MODE, configDirFor, requireConfig } from "./config.js";
+import { loadContract } from "./contract.js";
+import { UsageError } from "./errors.js";
+import { apiClient } from "./transport.js";
+const ROUTE = "/api/v1/agent/ticket-lease";
+const TICKET = /^[A-Za-z][A-Za-z0-9]*-[1-9][0-9]*$/;
+const AGENT = /^[a-z0-9-]{1,40}$/;
+const ACCEPT = [400, 403, 404, 409, 429];
+function object(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function text(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+function leaseRow(value) {
+    return object(value) && typeof value.generation === "number" && typeof value.deadlineMs === "number";
+}
+function leaseDir(ctx) {
+    return join(configDirFor(ctx.home), "leases");
+}
+function leasePath(ctx, ticket, agent) {
+    return join(leaseDir(ctx), `${ticket}--${agent}.json`);
+}
+function saveLease(ctx, lease) {
+    mkdirSync(leaseDir(ctx), { recursive: true });
+    const path = leasePath(ctx, lease.ticket, lease.agent);
+    writeFileSync(path, JSON.stringify(lease) + "\n", { mode: CONFIG_MODE });
+    chmodSync(path, CONFIG_MODE);
+}
+function forgetLease(ctx, ticket, agent) {
+    rmSync(leasePath(ctx, ticket, agent), { force: true });
+}
+/** Refusals that mean this seat's lease is gone: it lapsed, or a later take replaced it. */
+const GONE = new Set(["expired", "not_holder", "stale_generation"]);
+/** Forget a stored lease the cloud says this seat no longer holds, so a later seat on the same
+ * ticket is not asked to name one with --agent. The exit stays 1: the renew or release did not happen. */
+function forgetIfGone(ctx, ticket, agent, body) {
+    if (!object(body) || !object(body.refusal) || !GONE.has(String(body.refusal.reason)))
+        return;
+    forgetLease(ctx, ticket, agent);
+    ctx.stderr(`[catalyst] ${agent} no longer holds ${ticket}; forgot its stored lease`);
+}
+/** The leases this machine holds on a ticket, one per seat that took it. */
+function storedLeases(ctx, ticket) {
+    let names;
+    try {
+        names = readdirSync(leaseDir(ctx));
+    }
+    catch {
+        return [];
+    }
+    const found = [];
+    for (const name of names.filter((n) => n.startsWith(`${ticket}--`) && n.endsWith(".json"))) {
+        try {
+            const value = JSON.parse(readFileSync(join(leaseDir(ctx), name), "utf8"));
+            if (object(value) && value.ticket === ticket && text(value.agent) && typeof value.generation === "number")
+                found.push({ ticket, agent: value.agent, generation: value.generation, holder: text(value.holder) ? value.holder : null });
+        }
+        catch {
+            // An unreadable file is not a lease this machine can name; --agent and --generation still can.
+        }
+    }
+    return found;
+}
+function parseTicket(raw, verb) {
+    if (!raw || !TICKET.test(raw))
+        throw new UsageError(`lease ${verb} needs one ticket such as ENG-123`);
+    return raw.toUpperCase();
+}
+function parseAgent(raw) {
+    if (raw === undefined)
+        return undefined;
+    if (!AGENT.test(raw))
+        throw new UsageError("--agent is the seat's name: 1 to 40 of a-z, 0-9 and -");
+    return raw;
+}
+/** The seat and generation a renew or release names: the flags, else the one lease this machine
+ *  stored for the ticket. Two stored seats need --agent to choose. */
+function heldLease(args, ctx, ticket) {
+    const agent = parseAgent(flagString(args, "agent"));
+    const rawGeneration = flagString(args, "generation");
+    let generation;
+    if (rawGeneration !== undefined) {
+        generation = Number(rawGeneration);
+        if (!Number.isSafeInteger(generation) || generation < 1)
+            throw new UsageError("--generation is the positive integer the take printed");
+    }
+    const stored = storedLeases(ctx, ticket).filter((s) => agent === undefined || s.agent === agent);
+    if (agent !== undefined && generation !== undefined)
+        return { agent, generation };
+    if (stored.length === 1)
+        return { agent: stored[0].agent, generation: generation ?? stored[0].generation };
+    if (stored.length > 1)
+        throw new UsageError(`this machine holds ${ticket} for ${stored.map((s) => s.agent).join(", ")}; name one with --agent`);
+    throw new UsageError(`this machine holds no lease on ${ticket}${agent ? ` for ${agent}` : ""}; take it first, or pass --agent and --generation`);
+}
+/** The one progress fact a renewal asserts, from exactly one of the four flags. */
+function parseProgress(args) {
+    const given = ["commit", "artifact", "finding", "pr"]
+        .map((kind) => ({ kind, ref: flagString(args, kind) }))
+        .filter((p) => p.ref !== undefined);
+    if (given.length !== 1)
+        throw new UsageError("lease renew needs exactly one of --commit <sha>, --artifact <path or id>, --finding <id> or --pr <number>");
+    const { kind } = given[0];
+    const ref = given[0].ref.trim();
+    if (kind === "commit" && !/^[0-9a-f]{40}$/.test(ref))
+        throw new UsageError("--commit is the full 40-character lowercase sha");
+    if (kind === "pr" && !/^[1-9][0-9]{0,9}$/.test(ref))
+        throw new UsageError("--pr is the pull request's number");
+    if ((kind === "artifact" || kind === "finding") && (ref === "" || /\s/.test(ref)))
+        throw new UsageError(`--${kind} is one token with no spaces`);
+    const note = flagString(args, "note");
+    return { kind, ref, ...(note !== undefined && note.trim() !== "" ? { note } : {}) };
+}
+function parseTtlMs(args) {
+    const raw = flagString(args, "ttl");
+    if (raw === undefined)
+        return {};
+    const minutes = Number(raw);
+    if (!Number.isFinite(minutes) || minutes <= 0)
+        throw new UsageError("--ttl is a number of minutes (the cloud keeps it between 5 and 60)");
+    return { ttlMs: Math.round(minutes * 60_000) };
+}
+function when(ms) {
+    return new Date(ms).toISOString();
+}
+function detail(body) {
+    if (!object(body))
+        return "";
+    const parts = [body.reason, body.error, body.message].filter(text);
+    return parts.length ? `: ${[...new Set(parts)].join(": ")}` : "";
+}
+/** Print a refusal or an HTTP failure and return the exit code 1. */
+function refuse(args, ctx, status, body, verb) {
+    if (args.json) {
+        ctx.stdout(JSON.stringify(object(body) ? { status, ...body } : { status }));
+        return 1;
+    }
+    if (status === 200 && object(body) && object(body.refusal)) {
+        const r = body.refusal;
+        const current = leaseRow(r.current) ? r.current : null;
+        const parts = [`refused: ${text(r.reason) ? r.reason : "unknown"}`];
+        if (current?.holder)
+            parts.push(`held by ${current.holder} until ${when(current.deadlineMs)}`);
+        if (typeof r.retryAtMs === "number")
+            parts.push(`retry at ${when(r.retryAtMs)}`);
+        ctx.stdout(parts.join("; "));
+        return 1;
+    }
+    const meaning = status === 404 ? `this Catalyst Cloud does not serve lease ${verb} yet (needs a newer cloud)`
+        : status === 403 ? "your login does not reach this ticket's team"
+            : status === 429 ? "your write budget is spent for now"
+                : `lease ${verb} failed`;
+    ctx.stdout(`refused (${status}): ${meaning}${detail(body)}`);
+    return 1;
+}
+function printLease(ctx, ticket, lease) {
+    ctx.stdout(`${ticket}: held by ${lease.holder ?? "nobody"} until ${when(lease.deadlineMs)}, generation ${lease.generation}`);
+    if (text(lease.lastProgress))
+        ctx.stdout(`  last progress: ${lease.lastProgress}`);
+}
+export async function cmdLease(args, ctx) {
+    const [action, rawTicket, ...extra] = positionals(args);
+    if (action !== "take" && action !== "renew" && action !== "release" && action !== "show")
+        throw new UsageError("lease needs take, renew, release or show");
+    if (extra.length)
+        throw new UsageError(`lease ${action} takes one ticket`);
+    const ticket = parseTicket(rawTicket, action);
+    const client = apiClient(requireConfig(ctx), ctx);
+    if (action === "show") {
+        const res = await client.getJson(ROUTE, { query: { ticket }, accept: ACCEPT, parseAccepted: true });
+        if (res.status >= 400)
+            return refuse(args, ctx, res.status, res.body, action);
+        if (args.json) {
+            ctx.stdout(JSON.stringify(res.body));
+            return 0;
+        }
+        const lease = object(res.body) && leaseRow(res.body.lease) ? res.body.lease : null;
+        if (lease === null)
+            ctx.stdout(`${ticket}: no ticket lease`);
+        else if (lease.live === false) {
+            ctx.stdout(`${ticket}: free; last held by ${lease.lastHolder ?? lease.holder ?? "nobody"}, generation ${lease.generation}`);
+            if (text(lease.lastProgress))
+                ctx.stdout(`  last progress: ${lease.lastProgress}`);
+        }
+        else
+            printLease(ctx, ticket, lease);
+        return 0;
+    }
+    if (action === "take") {
+        const agent = parseAgent(flagString(args, "agent"));
+        if (agent === undefined)
+            throw new UsageError("lease take needs --agent <seat name>");
+        const res = await client.postJson(`${ROUTE}/take`, { ticket, agent, ...parseTtlMs(args) }, { accept: ACCEPT });
+        if (res.status !== 200 || !object(res.body) || res.body.outcome !== "taken" || !leaseRow(res.body.lease))
+            return refuse(args, ctx, res.status, res.body, action);
+        const lease = res.body.lease;
+        saveLease(ctx, { ticket, agent, generation: lease.generation, holder: lease.holder });
+        if (args.json)
+            ctx.stdout(JSON.stringify(res.body));
+        else
+            printLease(ctx, ticket, lease);
+        return 0;
+    }
+    if (action === "renew") {
+        const progress = parseProgress(args);
+        const held = heldLease(args, ctx, ticket);
+        const res = await client.postJson(`${ROUTE}/renew`, { ticket, ...held, progress, ...parseTtlMs(args) }, { accept: ACCEPT });
+        if (res.status !== 200 || !object(res.body) || res.body.outcome !== "renewed" || !leaseRow(res.body.lease)) {
+            forgetIfGone(ctx, ticket, held.agent, res.body);
+            return refuse(args, ctx, res.status, res.body, action);
+        }
+        if (args.json)
+            ctx.stdout(JSON.stringify(res.body));
+        else
+            printLease(ctx, ticket, res.body.lease);
+        return 0;
+    }
+    const held = heldLease(args, ctx, ticket);
+    const res = await client.postJson(`${ROUTE}/release`, { ticket, ...held }, { accept: ACCEPT });
+    if (res.status !== 200 || !object(res.body) || res.body.outcome !== "released") {
+        forgetIfGone(ctx, ticket, held.agent, res.body);
+        return refuse(args, ctx, res.status, res.body, action);
+    }
+    forgetLease(ctx, ticket, held.agent);
+    if (args.json)
+        ctx.stdout(JSON.stringify(res.body));
+    else
+        ctx.stdout(`${ticket}: released by ${held.agent}`);
+    return 0;
+}
+/** The free tickets in one team's rows: offered, or offered with no capable runner (a seat can still
+ *  take it), with no live holder named on them. */
+function freeTickets(rows) {
+    return rows.filter((r) => text(r.ticket) && (r.status === "offered" || r.status === "capability_mismatch") && !text(r.holder));
+}
+/** `work available`: per team, the tickets nobody holds (with the last holder and progress when a
+ *  lease lapsed) and the open pull requests no live lease covers, drafts included. */
+export async function cmdWork(args, ctx) {
+    const [action, ...extra] = positionals(args);
+    if (action !== "available" || extra.length)
+        throw new UsageError("work needs available");
+    const cfg = requireConfig(ctx);
+    const client = apiClient(cfg, ctx);
+    const named = flagString(args, "team");
+    let teams;
+    if (named !== undefined)
+        teams = [named.toUpperCase()];
+    else {
+        const { doc } = await loadContract(ctx, cfg);
+        teams = doc.teams.map((t) => t.key).filter((k) => typeof k === "string" && k !== "");
+        if (teams.length === 0)
+            throw new UsageError("work available needs --team: the workspace contract names no team");
+    }
+    const results = {};
+    for (const team of teams) {
+        const res = await client.getJson("/api/v1/work-eligibility", { query: { team } });
+        const rows = Array.isArray(res.body.eligibility?.rows) ? res.body.eligibility.rows : [];
+        const pulls = Array.isArray(res.body.openPulls) ? res.body.openPulls : [];
+        results[team] = {
+            tickets: freeTickets(rows),
+            unownedPulls: pulls.filter((p) => object(p) && typeof p.number === "number" && p.owner === "unowned"),
+        };
+    }
+    if (args.json) {
+        ctx.stdout(JSON.stringify(named !== undefined ? results[teams[0]] : results));
+        return 0;
+    }
+    for (const team of teams) {
+        const { tickets, unownedPulls } = results[team];
+        ctx.stdout(`${team}: ${tickets.length} free ${tickets.length === 1 ? "ticket" : "tickets"}, ${unownedPulls.length} unowned open ${unownedPulls.length === 1 ? "pull request" : "pull requests"}`);
+        for (const row of tickets) {
+            const last = text(row.lastHolder) ? `; last held by ${row.lastHolder}${text(row.lastProgress) ? `, last progress ${row.lastProgress}` : ""}` : "";
+            ctx.stdout(`  ${row.ticket}${last}`);
+        }
+        for (const pull of unownedPulls)
+            ctx.stdout(`  #${pull.number}${pull.draft ? " (draft)" : ""}${text(pull.ticket) ? ` ${pull.ticket}` : ""}: unowned${text(pull.title) ? `, ${pull.title}` : ""}`);
+    }
+    return 0;
+}

package/dist/onboard-existing.js

@@ -7,6 +7,14 @@ const waiting = (reason) => ({
     state: "waiting",
     reason,
 });
+/**
+ * CTC-5932: at most 20 choices, so the advice stays one readable line, and the full count, so the
+ * advice never reports the cap as the workspace's total.
+ */
+export const choiceEvidence = (values) => {
+    const unique = [...new Set(values)].sort();
+    return { choices: unique.slice(0, 20).join(","), choiceTotal: unique.length };
+};
 const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value)
     ? value
     : null;
@@ -175,7 +183,8 @@ export function existingLinearAdapters(args, choose, nameNewTeam, message = () =
             evidence: { teamKey: uncertain.key },
         }
         : undefined;
-    const stopTeam = (reason) => uncertainResult() ?? waiting(reason);
+    const stopTeam = (reason, teams) => uncertainResult() ??
+        (teams?.length ? { ...waiting(reason), evidence: choiceEvidence(teams.map((team) => team.key)) } : waiting(reason));
     const requested = (teams, journal) => {
         const explicit = args.flags.team;
         if (typeof explicit === "string") {
@@ -210,7 +219,7 @@ export function existingLinearAdapters(args, choose, nameNewTeam, message = () =
                 return stopTeam("team_selection_unverified");
             return choose
                 ? (uncertainResult("pending") ?? { state: "pending" })
-                : stopTeam("team_choice_required");
+                : stopTeam("team_choice_required", list.teams);
         }
         const result = await observe(ctx, team.id, signal);
         if (!result || result.checks.get("team_visible") !== "pass")
@@ -257,7 +266,7 @@ export function existingLinearAdapters(args, choose, nameNewTeam, message = () =
                 if ("reason" in list)
                     return stopTeam(list.reason);
                 if (!choose)
-                    return stopTeam(list.teams.length ? "team_choice_required" : "team_inventory_empty");
+                    return stopTeam(list.teams.length ? "team_choice_required" : "team_inventory_empty", list.teams);
                 let offer = nameNewTeam && typeof args.flags.team !== "string"
                     ? await teamCreateOffer(ctx, journal, signal)
                     : undefined;

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.`,
@@ -320,9 +325,23 @@ function firstTicketText(reason, key, stage) {
     }
     return undefined;
 }
+/** CTC-5932: the choices a step recorded, for advice that names real flag values. */
+function recordedChoices(step) {
+    const value = step.evidence?.choices;
+    return typeof value === "string" ? value.split(",").filter(Boolean) : [];
+}
 /** One step's next action. `waitsFor` names the unfinished step a prerequisite wait is blocked on. */
 export function onboardReasonText(step, context = {}) {
     const reason = step.reason ?? "";
+    const choices = recordedChoices(step);
+    const recordedTotal = step.evidence?.choiceTotal;
+    const total = typeof recordedTotal === "number" && recordedTotal > choices.length ? recordedTotal : choices.length;
+    // The list is capped at 20, so a longer inventory says which part it shows.
+    const shown = total > choices.length ? `, the first ${choices.length} of them` : "";
+    if (reason === "team_choice_required" && choices.length)
+        return `This workspace has ${total} Linear ${total === 1 ? "team" : "teams"}${shown}: ${choices.join(", ")}. Add --team with one of them to the same command, for example --team ${choices[0]}.`;
+    if (reason === "repository_choice_required" && choices.length)
+        return `${total === 1 ? "One repository is" : `${total} repositories are`} available${shown}: ${choices.join(", ")}. Add --repo <owner/name> to the same command, for example --repo ${choices[0]}. Repeat --repo to choose more than one.`;
     if ([
         "workspace_approval_required",
         "personal_approval_required",
@@ -454,6 +473,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-projects.js

@@ -1,7 +1,7 @@
 import { verifyOnboardRoutes } from "./onboard-capabilities.js";
 import { loadConfig, normalizeBaseUrl } from "./config.js";
 import { readExistingOnboardJson, selectedOnboardTeam, } from "./onboard-existing.js";
-import { existingRepositoryAdapter, } from "./onboard-repositories.js";
+import { existingRepositoryAdapter, repositoryChoiceWait, } from "./onboard-repositories.js";
 const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value)
     ? value
     : null;
@@ -211,7 +211,7 @@ export function firstProjectAdapters(args, input = {}) {
                         : waiting("repository_selection_unverified");
                 return input.chooseFirst && list.rows.length
                     ? { state: "pending" }
-                    : waiting("repository_choice_required");
+                    : repositoryChoiceWait(list.rows);
             },
             act: async (ctx, journal, signal) => {
                 const live = await existing.check(ctx, journal, signal);
@@ -221,7 +221,7 @@ export function firstProjectAdapters(args, input = {}) {
                 if ("reason" in list)
                     return waiting(list.reason);
                 if (!input.chooseFirst || !list.rows.length)
-                    return waiting("repository_choice_required");
+                    return repositoryChoiceWait(list.rows);
                 if (list.truncated)
                     input.message?.("GitHub returned part of its repository list. Choose a displayed repository, or stop and adjust the App access before resuming.");
                 let remove = () => { };