@catalyst-cloud/cli 0.16.29 → 0.16.30

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # 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.

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

@@ -46,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";
@@ -113,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)",
@@ -548,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":
@@ -624,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

@@ -325,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",

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 = () => { };

package/dist/onboard-repositories.js

@@ -1,7 +1,7 @@
 import { isRepositoryId } from "./repository-id.js";
 import { loadConfig, normalizeBaseUrl, readManifest, } from "./config.js";
 import { contractVersionInRange } from "./contract.js";
-import { readExistingOnboardJson, selectedOnboardTeam, } from "./onboard-existing.js";
+import { choiceEvidence, readExistingOnboardJson, selectedOnboardTeam, } from "./onboard-existing.js";
 const part = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,99}$/;
 const id = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
 const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value)
@@ -12,6 +12,13 @@ const waiting = (reason) => ({
     state: "waiting",
     reason,
 });
+/** CTC-5932: a choice no one was there to make, with the repositories it could have been. */
+export const repositoryChoiceWait = (rows) => rows.length
+    ? {
+        ...waiting("repository_choice_required"),
+        evidence: choiceEvidence(rows.map((row) => `${row.owner}/${row.name}`)),
+    }
+    : waiting("repository_choice_required");
 const valid = (value) => {
     const row = object(value);
     return (!!row &&
@@ -381,7 +388,7 @@ export function existingRepositoryAdapter(args, choose) {
                 ? waiting("repository_selection_unverified")
                 : choose
                     ? { state: "pending" }
-                    : waiting("repository_choice_required");
+                    : repositoryChoiceWait(list.repositories);
         return {
             state: "done",
             evidence: {
@@ -400,7 +407,7 @@ export function existingRepositoryAdapter(args, choose) {
             if (!list.repositories.length)
                 return waiting("repository_inventory_empty");
             if (!choose)
-                return waiting("repository_choice_required");
+                return repositoryChoiceWait(list.repositories);
             const teamId = list.repositories[0].teamId;
             const offers = list.canRegister
                 ? await offeredRepositories(ctx, journal, teamId, list.repositories, signal)

package/dist/onboard-ui.js

@@ -2,7 +2,7 @@ import { GITHUB_CONFIRM_ACCESS } from "./onboard-github-copy.js";
 import { COMPUTER_CHECKS, standalonePlan, standalonePlanNotes, pendingContinuation, } from "./onboard-standalone-copy.js";
 import { trackedPrompt } from "./setup-prompt-frame.js";
 import { createOnboardInterrupts } from "./onboard-interrupts.js";
-import { CLOUD_WORK, setupStepView, CONNECTION_REPAIR_REASONS, setupFinalScreen, setupBrowserInstruction, setupCommandWords as say, setupWaitsOnAdmin, TIMED_OUT_REASONS, setupPartHeading, setupPartProgress, setupTrackerRows, SETUP_PART_NUMBERS, SETUP_PART_OF, SETUP_PARTS, } from "./setup-onboard-copy.js";
+import { CLOUD_WORK, setupStepView, CONNECTION_REPAIR_REASONS, setupFinalScreen, setupBrowserInstruction, setupCommandWords as say, setupWaitsOnAdmin, TIMED_OUT_REASONS, setupPartHeading, setupPartProgress, setupTrackerRows, unattendedSkipLines, SETUP_PART_NUMBERS, SETUP_PART_OF, SETUP_PARTS, } from "./setup-onboard-copy.js";
 import { createOnboardProgress, } from "./onboard-progress.js";
 import { CREATE_TEAM_CHOICE, suggestTeamKey, teamKeyProblem, teamNameProblem, } from "./onboard-team-create.js";
 import { FIRST_TICKET_SAMPLE, FIRST_TICKET_SKIP, } from "./onboard-first-ticket.js";
@@ -297,6 +297,10 @@ export function createClackOnboardUi(prompts, streams, deps = {}) {
         if (screen.paused)
             renderer.line("Your progress is saved.");
         renderer.tracker(setupTrackerRows(setupPartProgress(journal, planned.scope), "end"));
+        // CTC-5932: with no one to ask, setup says what it left out instead of letting it pass unsaid.
+        if (!interactive && !screen.paused)
+            for (const line of unattendedSkipLines(journal, planned))
+                renderer.line(line);
         if (screen.readinessCause)
             renderer.line(say(screen.readinessCause));
         if (mine.length) {

package/dist/onboard.js

@@ -298,6 +298,9 @@ function normalizeStep(value, fallbackAt) {
         "passed",
         "team",
         "teamKey",
+        // CTC-5932: the comma-joined choices a run with no one to ask names in its flag advice.
+        "choices",
+        "choiceTotal",
         "selected",
         "hostName",
         "supervisorImage",

package/dist/setup-onboard-copy.js

@@ -1,4 +1,4 @@
-import { dependencySettled, ONBOARD_DEPENDENCIES, ONBOARD_STEPS, ONBOARD_TITLES, } from "./onboard.js";
+import { dependencySettled, stepSatisfied, ONBOARD_DEPENDENCIES, ONBOARD_STEPS, ONBOARD_TITLES, } from "./onboard.js";
 import { dispatchStageName, onboardReasonText } from "./onboard-next.js";
 /** The step numbers `--json` reports. People read SETUP_PART_NUMBERS instead (CTC-4680). */
 export const SETUP_NUMBERS = {
@@ -385,6 +385,9 @@ moment = "end") {
             {
                 // A member's own skip (no --team) is theirs to finish, so it is never counted done.
                 mark: memberOwnSkip(step) ? "act" : setupStepView(step, journal).mark,
+                // CTC-5932: a skipped step finishes its row only when it was skipped by choice. A skipped
+                // connection is still owed, so a part never reads "done" over it.
+                settled: step.state !== "skipped" || stepSatisfied(step),
                 working: step.state !== "done" && CLOUD_WORK.has(step.reason ?? ""),
                 kind: setupWaitsOnAdmin(step, journal)
                     ? "admin"
@@ -400,7 +403,8 @@ moment = "end") {
         const part = progress[Number(key.split(":")[0])];
         part.total++;
         const own = steps.filter((s) => s.kind === "own");
-        if (own.length === steps.length && own.every((s) => s.mark === "done" || s.mark === "skip"))
+        if (own.length === steps.length &&
+            own.every((s) => s.mark === "done" || (s.mark === "skip" && s.settled)))
             part.done++;
         else if (own.some((s) => s.mark === "act" || s.mark === "fail")) {
             part.needs++;
@@ -416,6 +420,41 @@ moment = "end") {
     }
     return progress;
 }
+/** The connections part 2 makes, each approved by a person in a browser. */
+const BROWSER_CONNECTIONS = [
+    "linear.workspace",
+    "linear.personal",
+    "github.install",
+    "github.personal",
+];
+/**
+ * CTC-5932: what a run that could not ask anyone left out, said plainly, with the command that
+ * resumes it. Empty when nothing was left out. A runner chosen or declined by flag is the person's
+ * choice and is not repeated back.
+ */
+export function unattendedSkipLines(journal, options = {}) {
+    const inScope = (id) => !options.scope || options.scope.includes(id);
+    const step = (id) => journal.steps.find((s) => s.id === id);
+    const lines = [];
+    const runner = step("runner");
+    if (options.runner === undefined &&
+        inScope("runner") &&
+        runner?.state === "skipped" &&
+        runner.reason === "runner_not_selected")
+        lines.push("Setup ran without questions, so it chose no runner: this computer will not run tickets.", "To add one, run in a terminal: catalyst setup --runner");
+    const open = BROWSER_CONNECTIONS.filter((id) => inScope(id) && step(id)?.state !== "done");
+    // Name only the providers still open, so a re-run with Linear connected never calls it skipped.
+    const providers = [
+        ...(open.some((id) => id.startsWith("linear.")) ? ["Linear"] : []),
+        ...(open.some((id) => id.startsWith("github.")) ? ["GitHub"] : []),
+    ];
+    const both = providers.length > 1;
+    if (open.length)
+        lines.push(`${providers.join(" and ")} ${both ? "were" : "was"} skipped, because ${both ? "they need" : "it needs"} you in a browser. Not connected: ${open
+            .map((id) => TITLES[id] ?? ONBOARD_TITLES[id])
+            .join(", ")}.`, `To connect ${both ? "them" : "it"}, run in a terminal: catalyst setup`);
+    return lines;
+}
 /**
  * The tracker's rows: on the first screen (`plan`, the part about to start), at a boundary
  * (`next`, the part about to start), or at the end. A part with no rows in this run is left out.

package/package.json

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

package/skills/catalyst-github/SKILL.md

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

package/skills/catalyst-linear/SKILL.md

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

package/skills/catalyst-onboard/SKILL.md

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

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

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

package/skills/run-this-project/references/stalls-and-escalation.md

@@ -24,7 +24,7 @@ Quote a reason the table does not know as the explainer spelled it.
 
 ## Shared causes are one note
 
-When several tickets are offered and nothing takes them, or the explainer names a routing, slot, provider or image condition, the cause is shared (coding-account headroom, a provider outage, a paused repository, a bad runner image). Write one summary line naming the condition and the tickets it holds. `catalyst accounts` reads coding-account status; enrolling or pausing one is the settings page.
+When several tickets are offered and nothing takes them, or the explainer names a routing, slot, provider or image condition, the cause is shared (coding-account headroom, a provider outage, a paused repository, a bad runner image). Write one summary line naming the condition and the tickets it holds. For a paused repository, `catalyst repo status` says who paused it, when and why; put that in the line, and leave resuming (`catalyst repo resume <owner/name>`) to a workspace owner or admin. `catalyst accounts` reads coding-account status; enrolling or pausing one is the settings page.
 
 ## Escalate inward
 

package/skills/unstick/SKILL.md

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

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

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

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

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

package/skills/whats-happening/SKILL.md

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

package/skills/whats-happening/references/what-runs-next.md

@@ -2,7 +2,7 @@
 
 Queues update within seconds. Dispatch sorts by priority, created time, identifier; mid-ladder tickets precede them by phases completed. Order never grants eligibility.
 
-An operator sets the repository concurrency cap, default 20, displayed in settings. Pause means zero, preserving the cap. Teams share capacity, including comment-wake.
+An operator sets the repository concurrency cap, default 20, displayed in settings. Pause means zero, preserving the cap. Any member reads which repositories are paused, by whom, when and why with `catalyst repo status`; a workspace owner or admin pauses one with `catalyst repo pause <owner/name> --reason <why>` and resumes it with `catalyst repo resume <owner/name>`. Teams share capacity, including comment-wake.
 
 WIP limits starts per project, one Linear team across repositories: project setting, operator's account value, then 12; zero prevents starts. Members read `catalyst project wip-limit get --team <KEY>`; owners/admins use `set <n>` or set default. Only first phases are held; later phases continue. Count live tickets past dispatch or granted a first phase, including waits/blocks/parks; exclude never-started, backlog and local-lane. Idle at the limit means started tickets wait; use unstick, catalyst-github or what-needs-me.
 

package/skills/whats-happening/references/why-is-it-stuck.md

@@ -25,7 +25,7 @@ Automatic waits, where no one acts: `retry_backoff`, `lease_held`, `intake_lease
 | `waiting_on` | the person, with their own login: unrepairable PR merge gate; read merge-wait comment for hold/review owed, using catalyst-github |
 | `externally_claimed` | the person, with their own login: outside worker owns it; worker/person removes local-lane label |
 | `environment_check_required` / `environment_check_failed` / `environment_check_expired` / `environment_check_hash_mismatch` | absent/failed/aged/changed environment check; a workspace owner or admin, in settings, runs or fixes it |
-| `repo_paused` | an operator resumes repository |
+| `repo_paused` | the repository is paused; `catalyst repo status` says by whom, when and why; a workspace owner or admin, in settings or with `catalyst repo resume <owner/name>`, resumes it |
 | `scope_overlap` | the person, with their own login: declared files overlap running work; choose order or wait |
 | `human_owned_pr` | the person, with their own login: only its human owner closes, merges or hands it over; release refused |
 | `review_not_converging` | the person, with their own login: read findings through catalyst-github, comment; release refused |