@catalyst-cloud/cli 0.16.29 → 0.16.31

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

@@ -4,6 +4,7 @@
 // reason instead of throwing: a customer who cannot reach npm must still get a verdict (CTC-2160).
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
+import { readApprovalCache, supportedReleaseLine } from "./approved-release.js";
 import { LEGACY_PACKAGE_NAME, publishedCachePathFor } from "./config.js";
 /** CTC-3479 — asks about the forwarder package whichever package is installed. The release publishes
  *  @catalyst-cloud/cli first and the forwarder last, at one version, so the forwarder's `latest`
@@ -77,3 +78,17 @@ export async function latestPublishedVersion(ctx, opts = {}) {
     writePublishedCache(ctx.home, { fetchedAt: ctx.now().toISOString(), latest });
     return { latest, reason: null, source: "network" };
 }
+/**
+ * CTC-6708 — the CLI's "newest" answer is the approved release once this install has read one: every
+ * applying release check records it, the 15-minute schedule included. Reading it is local, so this
+ * adds no network call. An install that has never read an approved release, or read one on another
+ * train, falls back to the npm lookup above, and its answer stays labelled the latest published version.
+ */
+export async function newestCliVersion(ctx, opts = {}) {
+    const approved = readApprovalCache(ctx.home)?.release;
+    const cli = approved?.members.cli;
+    // CTC-6741: a release on another train is never applied, so it is never the answer either.
+    if (approved && cli && approved.releaseLine === supportedReleaseLine())
+        return { latest: cli, reason: null, source: "approved", ...(approved.skills.cloud ? { skills: approved.skills.cloud.version } : {}) };
+    return latestPublishedVersion(ctx, opts);
+}

package/dist/ready.js

@@ -6,7 +6,7 @@ import { basename, delimiter, dirname, join } from "node:path";
 import { DEFAULT_BASE_URL, LEGACY_PACKAGE_NAME, PACKAGE_NAME, defaultSkillsDirFor, loadConfig, normalizeBaseUrl, readManifest, upgradeCommand, } from "./config.js";
 import { contractVersionInRange, readContractCache } from "./contract.js";
 import { CliError } from "./errors.js";
-import { latestPublishedVersion } from "./published.js";
+import { newestCliVersion } from "./published.js";
 import { replicaStatus, writerIsRunning, } from "./replica.js";
 import { loadHttpSdk } from "./sdk.js";
 import { FIX_COMMAND, detectRuntime, runtimeVerdict, supportedRangeText, } from "./runtime.js";
@@ -234,7 +234,7 @@ export async function readyReport(ctx, deps) {
     const skillsDir = cfg?.skillsDir ?? defaultSkillsDirFor(ctx.home);
     const offline = deps.offline === true || ctx.env.CATALYST_SKILLS_OFFLINE === "1";
     if (!offline) {
-        const pub = await (deps.fetchLatestRelease ?? (() => latestPublishedVersion(ctx)))();
+        const pub = await (deps.fetchLatestRelease ?? (() => newestCliVersion(ctx)))();
         if (pub.latest === null) {
             checks.push({
                 id: "cliRelease",
@@ -252,7 +252,10 @@ export async function readyReport(ctx, deps) {
                     id: "cliRelease",
                     ok: false,
                     note: true,
-                    line: `cliRelease: ${installedCli} installed is older than the latest published ${pub.latest} — upgrade: ${upgradeCommand()}`,
+                    // CTC-6708 — once this install has read an approved release, that is the answer.
+                    line: pub.source === "approved"
+                        ? `cliRelease: ${installedCli} installed is older than the approved ${pub.latest} — update: catalyst update`
+                        : `cliRelease: ${installedCli} installed is older than the latest published ${pub.latest} — upgrade: ${upgradeCommand()}`,
                 });
             }
             // clause 1 — the skill files on disk, read independently of whichever CLI is answering. Both
@@ -262,7 +265,8 @@ export async function readyReport(ctx, deps) {
             // older than any stamp, which is why the stamped half says "oldest STAMPED" and the unstamped
             // names are always printed rather than hidden behind whichever branch happened to win.
             const found = installedBundleVersion(skillsDir, deps.skillNames);
-            const stampBehind = found.version !== null && semverOlder(found.version, pub.latest);
+            const skillsTarget = pub.source === "approved" ? (pub.skills ?? pub.latest) : pub.latest;
+            const stampBehind = found.version !== null && semverOlder(found.version, skillsTarget);
             const unstampedBehind = found.unstamped.length > 0 &&
                 !semverOlder(pub.latest, FIRST_STAMPED_VERSION);
             if (stampBehind || unstampedBehind) {
@@ -277,7 +281,9 @@ export async function readyReport(ctx, deps) {
                     id: "skillsRelease",
                     ok: false,
                     note: true,
-                    line: `skillsRelease: in ${skillsDir} ${facts.join(", and ")}, while the published bundle is ${pub.latest} — update: npx skills update -y`,
+                    line: pub.source === "approved"
+                        ? `skillsRelease: in ${skillsDir} ${facts.join(", and ")}, while the approved bundle is ${skillsTarget} — update: catalyst update`
+                        : `skillsRelease: in ${skillsDir} ${facts.join(", and ")}, while the published bundle is ${pub.latest} — update: npx skills update -y`,
                 });
             }
         }

package/dist/replica.js

@@ -3,10 +3,11 @@
 // `status` is the check every skill runs first and it needs no network and no SDK: the pidfile, the
 // writer-lock heartbeat, and the `sync_meta.cursor` row (read through node:sqlite read-only). Exit
 // 0 fresh, 1 present but stale, 2 not configured, 3 absent. `--probe` adds the one network call.
-import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
 import { createRequire } from "node:module";
+import { join } from "node:path";
 import { flagBool, flagInt, flagString, positionals } from "./args.js";
-import { apiBase, loadConfig, replicaDbPath, replicaOptedIn } from "./config.js";
+import { apiBase, configDirFor, loadConfig, readManifest, replicaDbPath, replicaOptedIn } from "./config.js";
 import { detachSelf } from "./detach.js";
 import { CliError, UsageError } from "./errors.js";
 import { apiClient } from "./transport.js";
@@ -62,7 +63,8 @@ export function readWriterState(dbPath) {
             typeof rec.consecutiveFailures !== "number" ||
             !(rec.lastError === null || typeof rec.lastError === "string") ||
             !(rec.lastFailureAt === null || typeof rec.lastFailureAt === "number") ||
-            !stoppedOk) {
+            !stoppedOk ||
+            !(rec.version === undefined || typeof rec.version === "string")) {
             return null;
         }
         return rec;
@@ -72,7 +74,7 @@ export function readWriterState(dbPath) {
     }
 }
 export function writeWriterState(dbPath, s, nowMs) {
-    writeFileSync(writerStatePath(dbPath), JSON.stringify({ ...s, updatedAt: nowMs }));
+    writeFileSync(writerStatePath(dbPath), JSON.stringify({ ...s, version: readManifest().version, updatedAt: nowMs }));
 }
 /** Remove the writer state sidecar; a no-op (never throws) when it is already gone. */
 export function clearWriterState(dbPath) {
@@ -83,6 +85,25 @@ export function clearWriterState(dbPath) {
         // already gone
     }
 }
+/** A restart a release check began and has not finished (update-replica.ts, CTC-6708). The owner's
+ *  own `replica stop` clears it, so their stop is never undone. */
+export function pendingRestartPathFor(home) {
+    return join(configDirFor(home), "replica-restart.json");
+}
+/** The restart a release check began for `dbPath` and has not confirmed, with the CLI version it
+ *  expects the new writer to run when the record names one. */
+export function pendingRestart(home, dbPath) {
+    try {
+        const raw = JSON.parse(readFileSync(pendingRestartPathFor(home), "utf8"));
+        if (typeof raw !== "object" || raw === null || raw.dbPath !== dbPath)
+            return null;
+        const target = raw.target;
+        return { dbPath, target: typeof target === "string" ? target : null };
+    }
+    catch {
+        return null;
+    }
+}
 export function pidAlive(pid) {
     if (pid === null || !Number.isInteger(pid) || pid <= 0)
         return false;
@@ -348,7 +369,15 @@ async function cmdStatus(args, ctx) {
             status.lag = status.cursor === null ? head.body.cursor : head.body.cursor - status.cursor;
         }
     }
-    ctx.stdout(args.json ? JSON.stringify(status) : statusLine(status));
+    const restart = status.dbPath !== null && !writerIsRunning(status) ? pendingRestart(ctx.home, status.dbPath) : null;
+    if (args.json)
+        ctx.stdout(JSON.stringify(restart ? { ...status, pendingRestart: restart } : status));
+    else {
+        ctx.stdout(statusLine(status));
+        // CTC-6743: a writer a release check stopped and restarted is down for that reason, not its owner's.
+        if (restart)
+            ctx.stdout(`  a release check restarted it${restart.target ? ` on CLI ${restart.target}` : ""} and the new writer is not running; its synced data is kept at ${status.dbPath}, and the next release check starts it again`);
+    }
     return status.exitCode;
 }
 async function cmdStart(args, ctx, cfg, dbPath, deps) {
@@ -382,7 +411,9 @@ async function cmdStart(args, ctx, cfg, dbPath, deps) {
         if (recordOwned)
             return;
         recordOwned = true;
-        clearWriterState(dbPath);
+        // CTC-6743: a fresh, healthy record rather than none, so a release check can read the CLI
+        // version this writer runs without waiting for a failed pull to write one.
+        writeWriterState(dbPath, { pid: process.pid, consecutiveFailures: 0, lastError: null, lastFailureAt: null, stopped: null }, ctx.now().getTime());
     };
     const resetFailures = () => {
         if (failures === 0)
@@ -413,6 +444,11 @@ async function cmdStart(args, ctx, cfg, dbPath, deps) {
             log: (level, msg, extra) => ctx.stderr(`[replica ${level}] ${msg}${extra ? ` ${safeJson(extra)}` : ""}`),
             onStatus: (s) => {
                 ctx.stderr(`[replica] status=${s}`);
+                // CTC-6743: a status means start() already holds the writer lock, so this run owns the
+                // record. Taking it here, not after a long first seed, means a release check never reads a
+                // seeding writer as one with no version and restarts it every interval.
+                if (s === "resyncing" || s === "connecting")
+                    takeOwnershipOfRecord();
                 // A "live" that does NOT follow a re-seed is just the socket coming up — the warm failing
                 // loop passes through it every cycle, so it must not reset the count (CTC-2499).
                 if (s === "resyncing") {
@@ -544,6 +580,7 @@ async function cmdStart(args, ctx, cfg, dbPath, deps) {
     return 0;
 }
 function cmdStop(ctx, dbPath) {
+    rmSync(pendingRestartPathFor(ctx.home), { force: true });
     const pid = readPidfile(dbPath);
     if (pid === null) {
         ctx.stdout(`no pidfile at ${pidfilePath(dbPath)} — nothing to stop (a foreground writer is stopped with Ctrl-C)`);