@catalyst-cloud/catalyst-skills 0.1.1 → 0.2.1

package/dist/contract.js

@@ -0,0 +1,178 @@
+// contract.ts — GET /api/v1/agent/contract, cached with its ETag at ~/.config/catalyst-cloud/contract.json.
+// Every tenant fact a verb needs (stage ids, label ids, route paths, the bookkeeping marker, thresholds)
+// is read from here; no verb carries a literal fallback for any of them.
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { contractPathFor, readManifest } from "./config.js";
+import { CliError, MeError } from "./errors.js";
+import { apiClient } from "./http.js";
+export const CONTRACT_ROUTE = "/api/v1/agent/contract";
+export function readContractCache(home) {
+    const path = contractPathFor(home);
+    if (!existsSync(path))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        if (typeof parsed.fetchedAt !== "string" || typeof parsed.contractVersion !== "string" || !parsed.doc)
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+export function writeContractCache(home, cache) {
+    const path = contractPathFor(home);
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp`;
+    writeFileSync(tmp, JSON.stringify(cache, null, 2) + "\n", { mode: 0o600 });
+    renameSync(tmp, path);
+    return path;
+}
+/** `1.x` → major 1; `1.2.3` → exact; `unpinned` → anything. Returns null when the range is unparseable. */
+export function contractVersionInRange(version, range) {
+    if (range === "unpinned")
+        return true;
+    const major = /^(\d+)\.x$/.exec(range);
+    if (major)
+        return version.split(".")[0] === major[1];
+    if (/^\d+\.\d+\.\d+$/.test(range))
+        return version === range;
+    return null;
+}
+export function assertContractRange(version, range) {
+    const ok = contractVersionInRange(version, range);
+    if (ok === null)
+        throw new CliError(`tenantContractRange "${range}" in package.json is not a range this CLI understands`, "contract-range");
+    if (!ok) {
+        throw new CliError(`the tenant serves contract version ${version} but this bundle accepts ${range} — update the bundle (npm update -g @catalyst-cloud/catalyst-skills) or ask your tenant admin which version is live`, "contract-version");
+    }
+}
+/**
+ * Load the contract per the cloud's own cache policy: a cache younger than `doc.cache.maxAgeSeconds`
+ * is used as-is; otherwise a conditional GET revalidates it (304 refreshes `fetchedAt`, 200 replaces
+ * the document). A network failure on a cache older than `staleRefusalSeconds` refuses; a 403 (a
+ * workstation key) refuses naming the account key; a major version outside the bundle's range refuses
+ * naming both versions.
+ */
+export async function loadContract(ctx, cfg, opts = {}) {
+    const path = contractPathFor(ctx.home);
+    const cached = readContractCache(ctx.home);
+    const nowMs = ctx.now().getTime();
+    const ageSeconds = cached ? Math.max(0, Math.floor((nowMs - Date.parse(cached.fetchedAt)) / 1000)) : Infinity;
+    const range = readManifest().tenantContractRange;
+    if (cached && !opts.refresh && ageSeconds < cached.doc.cache.maxAgeSeconds) {
+        assertContractRange(cached.contractVersion, range);
+        return { doc: cached.doc, source: "cache", ageSeconds, path };
+    }
+    if (opts.offline) {
+        if (cached) {
+            assertContractRange(cached.contractVersion, range);
+            return { doc: cached.doc, source: "cache", ageSeconds, path };
+        }
+        throw new CliError("no cached contract and network reads are disabled", "contract-missing");
+    }
+    const api = apiClient(cfg, ctx);
+    let res;
+    try {
+        res = await api.getJson(CONTRACT_ROUTE, { etag: cached?.etag ?? null, accept: [304] });
+    }
+    catch (err) {
+        if (err instanceof CliError && err.status === 403) {
+            throw new CliError(`GET ${CONTRACT_ROUTE} refused (403): the contract needs an account key (ctc_acct_…); this key is a workstation key — ask your tenant admin for an account key`, "contract-forbidden", 2, 403);
+        }
+        if (err instanceof MeError && err.kind === "network" && cached) {
+            if (ageSeconds >= cached.doc.cache.staleRefusalSeconds) {
+                throw new CliError(`the cached contract is ${ageSeconds}s old (refusal after ${cached.doc.cache.staleRefusalSeconds}s) and the refresh failed: ${err.message}`, "contract-stale");
+            }
+            assertContractRange(cached.contractVersion, range);
+            return { doc: cached.doc, source: "cache", ageSeconds, path };
+        }
+        throw err;
+    }
+    if (res.status === 304) {
+        if (!cached)
+            throw new CliError(`GET ${CONTRACT_ROUTE} answered 304 with no cache to revalidate`, "contract-shape");
+        assertContractRange(cached.contractVersion, range);
+        writeContractCache(ctx.home, { ...cached, fetchedAt: ctx.now().toISOString() });
+        return { doc: cached.doc, source: "revalidated", ageSeconds: 0, path };
+    }
+    const doc = res.body;
+    if (!doc || typeof doc !== "object" || typeof doc.contractVersion !== "string" || !Array.isArray(doc.teams) || !Array.isArray(doc.routes)) {
+        throw new CliError(`GET ${CONTRACT_ROUTE} returned an unexpected shape`, "contract-shape");
+    }
+    const version = res.headers.get("x-catalyst-contract-version") ?? doc.contractVersion;
+    assertContractRange(version, range);
+    writeContractCache(ctx.home, {
+        etag: res.headers.get("etag"),
+        fetchedAt: ctx.now().toISOString(),
+        contractVersion: version,
+        doc,
+    });
+    return { doc, source: "network", ageSeconds: 0, path };
+}
+// ── helpers every verb uses ──────────────────────────────────────────────────────────────────────
+export function teamByKey(doc, key) {
+    const wanted = key.toUpperCase();
+    const team = doc.teams.find((t) => (t.key ?? "").toUpperCase() === wanted);
+    if (!team) {
+        const known = doc.teams.map((t) => t.key ?? t.id).join(", ") || "none";
+        throw new CliError(`team "${key}" is not on this tenant's contract (teams: ${known})`, "team-unknown");
+    }
+    return team;
+}
+export function teamById(doc, id) {
+    return doc.teams.find((t) => t.id === id) ?? null;
+}
+/** The team a ticket identifier belongs to, by its `KEY-` prefix. */
+export function teamForTicket(doc, ticket) {
+    const dash = ticket.indexOf("-");
+    if (dash <= 0)
+        throw new CliError(`"${ticket}" is not a ticket identifier (expected KEY-123)`, "ticket-shape");
+    return teamByKey(doc, ticket.slice(0, dash));
+}
+export function stageIdForSlot(team, slot) {
+    const stage = team.stages[slot];
+    if (!stage) {
+        const mapped = Object.keys(team.stages).join(", ") || "none";
+        throw new CliError(`slot "${slot}" is not mapped for team ${team.key ?? team.id} (mapped: ${mapped})`, "slot-unmapped");
+    }
+    if (!stage.stateStillExists) {
+        throw new CliError(`slot "${slot}" on team ${team.key ?? team.id} maps to state ${stage.stateId}, which no longer exists in Linear — fix the mapping in settings first`, "slot-stale");
+    }
+    return stage.stateId;
+}
+/** Resolve a label by name through the contract's ask/hold/release lists; an unknown name is returned
+ *  as-is when it looks like an id (the contract only lists Catalyst's own labels). */
+export function labelId(team, nameOrId) {
+    const all = [...team.labels.ask, ...team.labels.hold, ...team.labels.release];
+    const hit = all.find((l) => l.name === nameOrId);
+    if (hit) {
+        if (!hit.preferredId) {
+            throw new CliError(`label "${nameOrId}" is absent from this workspace (contract scope: ${hit.scope}) — create it in Linear first`, "label-absent");
+        }
+        return hit.preferredId;
+    }
+    return nameOrId;
+}
+/** The route whose last path segment is `name` (e.g. `issue-comment`). The path itself is never assumed. */
+export function routePath(doc, name) {
+    const route = doc.routes.find((r) => r.path.split("/").filter(Boolean).at(-1) === name);
+    if (!route) {
+        throw new CliError(`the tenant contract serves no "${name}" route (routes: ${doc.routes.map((r) => r.path).join(", ")})`, "route-unknown");
+    }
+    return route.path;
+}
+export function bookkeepingPrefix(doc) {
+    return doc.vocabulary.bookkeeping.marker;
+}
+/** Walk a dotted path (`teams.0.stages`) into the document. */
+export function pickPath(doc, path) {
+    let cur = doc;
+    for (const seg of path.split(".").filter(Boolean)) {
+        if (cur === null || typeof cur !== "object")
+            return undefined;
+        cur = cur[seg];
+    }
+    return cur;
+}

package/dist/detach.js

@@ -0,0 +1,10 @@
+// detach.ts — re-spawn this CLI detached (replica start --detach). Isolated so a test can stub it.
+import { spawn } from "node:child_process";
+/** Spawn `process.execPath <argv>` detached from this process, stdio ignored, and let it go. */
+export function detachSelf(argv, env = process.env) {
+    const child = spawn(process.execPath, argv, { detached: true, stdio: "ignore", env });
+    child.unref();
+    if (typeof child.pid !== "number")
+        throw new Error("detached spawn returned no pid");
+    return { pid: child.pid };
+}

package/dist/errors.js

@@ -0,0 +1,27 @@
+// errors.ts — the three error classes the exit contract is built on: usage → 1, MeError/CliError → 2.
+export class UsageError extends Error {
+}
+export class CliError extends Error {
+    code;
+    exitCode;
+    status;
+    constructor(message, code, 
+    /** Exit code the dispatcher returns for this error. Defaults to 2 (the CliError contract). */
+    exitCode = 2, 
+    /** The HTTP status that produced it, when one did. */
+    status) {
+        super(message);
+        this.code = code;
+        this.exitCode = exitCode;
+        this.status = status;
+    }
+}
+export class MeError extends Error {
+    kind;
+    status;
+    constructor(message, kind, status) {
+        super(message);
+        this.kind = kind;
+        this.status = status;
+    }
+}

package/dist/execution.js

@@ -0,0 +1,308 @@
+// execution.ts — what Catalyst is doing: `explain <ticket>`, `running`, `queue`, `accounts`.
+// `explain` turns one work-eligibility row into a paragraph a human can act on, translating every
+// exclusion reason and unknown the cloud names; an unlisted reason prints its raw string, never nothing.
+import { flagBool, flagString, positionals } from "./args.js";
+import { normalizeBaseUrl, requireConfig } from "./config.js";
+import { loadContract } from "./contract.js";
+import { CliError, UsageError } from "./errors.js";
+import { apiClient } from "./http.js";
+/** Every exclusion reason the eligibility evaluator names, in plain English. */
+export const EXCLUSION_REASONS = {
+    ticket_terminal: "the ticket is in a done or canceled state, so there is nothing left to run",
+    pipeline_complete: "every relay phase has already completed",
+    not_at_dispatch_stage: "the card is not in the team's dispatch column, so nothing is offered until it is moved there",
+    not_at_pr_stage: "merge is next but the card is not in the PR column",
+    blocked: "a live blocking relation holds it — the blocker has to close first",
+    cooling_down: "the offered phase is parked; a callback or an operator releases it, not a clock",
+    lease_held: "a live container already holds the lease for the offered phase",
+    intake_lease_held: "a later phase is offered while an intake container still holds this ticket",
+    ask_ticket: "it carries an ask label, and a question is never work",
+    ask_shape_suspected: "its own text reads as a decision request; a human releases it with the not-an-ask label",
+    externally_claimed: "a worker outside the cloud has claimed it",
+    environment_check_required: "the repository's environment check has not been run",
+    environment_check_running: "the repository's environment check is in flight",
+    environment_check_failed: "the repository's environment check failed",
+    environment_check_expired: "the repository's environment check verdict aged out",
+    environment_check_hash_mismatch: "the environment changed since its recorded verdict",
+    scope_overlap: "its declared file scope intersects a ticket already in flight",
+    waiting_on: "a merge-gate failure with no remediable cause holds the card at PR",
+    branch_missing: "the ticket branch has never been seen, so a branch-dependent phase has nothing to clone",
+    branch_gone: "the ticket branch was deleted after it existed",
+    pr_merged: "its PR has merged and no other PR is open — nothing is left to clone or re-merge",
+    no_change_hold: "a remediate round changed nothing; a human comment or a new push releases it",
+    validate_class_spent: "this validate failure already spent its one repair round in this episode",
+    stale_failure_episode: "the ladder advanced after the recorded failure, so the round would repair a phase already passed",
+    runner_image_breaker: "fleet-wide: the live runner image is failing every phase at startup; dispatch resumes when the pin moves",
+    no_branch_to_remediate: "a remediate round is queued on a ticket with no recorded branch",
+    retry_backoff: "the failed phase is retrying in place and waiting out its backoff",
+    routing_unavailable: "the unit was claimed and refused at kickoff (no route, no eligible coding-account slot, or the provider is unavailable)",
+    repo_paused: "an operator paused the repository",
+    remediate_parked: "the remediate phase is parked, so the failing phase has nowhere to be repaired",
+};
+/** Every fail-closed unknown the evaluator names. */
+export const UNKNOWN_REASONS = {
+    ordering_never_published: "the dispatch order has never been published for this team",
+    ordering_stale: "the dispatch order is stale",
+    workflow_mapping_unknown: "the team's workflow mapping could not be read",
+    ticket_unknown: "the ticket is not in the mirror",
+    dependency_snapshot_unknown: "the dependency snapshot has never completed",
+    blocker_unknown: "a blocking relation could not be resolved",
+    label_snapshot_unknown: "the labels poll has never completed, so ask labels cannot be read",
+    prior_artifact_unknown: "a prior phase artifact could not be read",
+    scope_unknown: "the ticket declared no scope, or the declaration was truncated",
+    scope_occupancy_unknown: "an in-flight ticket's state could not be resolved",
+    branch_snapshot_unknown: "the pull-request poll has never completed, so branch evidence cannot be read",
+};
+export const ADVISORIES = {
+    human_addressed_unlabeled_ask_suspect: "assigned to a human with no delegate: this may be an unlabelled ask",
+};
+export function describeReason(reason) {
+    if (!reason)
+        return "no reason was given";
+    return EXCLUSION_REASONS[reason] ?? UNKNOWN_REASONS[reason] ?? `reason "${reason}" (not in this bundle's table; read it as the cloud spelled it)`;
+}
+export function renderExplain(ticket, row, team) {
+    if (!row)
+        return `${ticket}: not in the ${team} eligibility explainer — the ticket is unknown to the mirror, terminal, or on another team.`;
+    const parts = [];
+    const pos = typeof row.position === "number" ? `position ${row.position}` : "no queue position";
+    const status = row.status ?? "unknown";
+    if (status === "offered" || status === "eligible") {
+        parts.push(`${ticket} is ${status} (${pos})${row.phase ? ` for phase ${row.phase}` : ""}.`);
+    }
+    else if (status === "unknown") {
+        parts.push(`${ticket} cannot be judged (${pos}): ${describeReason(row.unknown ?? row.reason)}.`);
+    }
+    else {
+        parts.push(`${ticket} is ${status} (${pos}): ${describeReason(row.reason)}.`);
+    }
+    if (row.detail)
+        parts.push(`Detail: ${row.detail}.`);
+    if (row.marker)
+        parts.push(`Marker: ${row.marker}.`);
+    if (row.nextPhase)
+        parts.push(`Next phase would be ${row.nextPhase}.`);
+    if (row.release)
+        parts.push(`Release: ${row.release}.`);
+    if (row.failure && typeof row.failure === "object") {
+        const f = row.failure;
+        const bits = ["phase", "class", "attempts", "consecutive", "lastFailedAt", "message", "summary"]
+            .filter((k) => f[k] !== undefined && f[k] !== null)
+            .map((k) => `${k}=${typeof f[k] === "string" ? f[k] : JSON.stringify(f[k])}`);
+        parts.push(`Last failure: ${bits.length ? bits.join(", ") : JSON.stringify(f)}.`);
+    }
+    if (row.advisories && row.advisories.length > 0) {
+        parts.push(`Advisories: ${row.advisories.map((a) => ADVISORIES[a] ?? a).join("; ")}.`);
+    }
+    return parts.join(" ");
+}
+export async function cmdExplain(args, ctx) {
+    const [ticket] = positionals(args);
+    if (!ticket)
+        throw new UsageError("explain needs a ticket: explain <ticket>");
+    const cfg = requireConfig(ctx);
+    // `explain --history` is the same read as `history <ticket>`; both go to CTC-1954's route.
+    if (flagBool(args, "history"))
+        return await cmdHistory(args, ctx, ticket);
+    const { doc } = await loadContract(ctx, cfg);
+    const dash = ticket.indexOf("-");
+    if (dash <= 0)
+        throw new UsageError(`"${ticket}" is not a ticket identifier (expected KEY-123)`);
+    const team = ticket.slice(0, dash).toUpperCase();
+    const api = apiClient(cfg, ctx);
+    const res = await api.getJson("/api/v1/work-eligibility", {
+        query: { team, capabilities: doc.ladder.phases.join(",") },
+    });
+    const rows = res.body.eligibility?.rows ?? res.body.rows ?? [];
+    const row = rows.find((r) => String(r.ticket ?? "").toUpperCase() === ticket.toUpperCase()) ?? null;
+    if (args.json) {
+        ctx.stdout(JSON.stringify({ ticket, row, explanation: renderExplain(ticket, row, team) }));
+    }
+    else {
+        ctx.stdout(renderExplain(ticket, row, team));
+    }
+    return 0;
+}
+/**
+ * `running` — the fleet-wide "what is Catalyst doing right now?".
+ *
+ * ⛔ `/api/v1/lease/attributions` IS NOT A FLEET-WIDE ROUTE. It answers "who wrote this transition,
+ * holding which lease?" for ONE (ticket, phase) pair and 400s `invalid_field` without both — 0.2.0
+ * called it bare on every `running`, so the headline verb (and `whats-running.mjs`, and
+ * `snapshot.mjs`) failed for every tenant. The tenant-wide question is answered by
+ * `/fleet-activity/current` (what is executing) and `/agent-roster/current` (who is coordinating),
+ * neither of which takes coordinates. Lease attributions stay available, behind the coordinates the
+ * route requires.
+ */
+export async function cmdRunning(args, ctx) {
+    const cfg = requireConfig(ctx);
+    const ticket = flagString(args, "ticket");
+    const phase = flagString(args, "phase");
+    if ((ticket === undefined) !== (phase === undefined)) {
+        throw new UsageError("running: --ticket and --phase go together — lease attributions are recorded per (ticket, phase), and the route refuses either one alone");
+    }
+    const api = apiClient(cfg, ctx);
+    const [activity, roster] = await Promise.all([
+        api.getJson("/api/v1/fleet-activity/current"),
+        api.getJson("/api/v1/agent-roster/current"),
+    ]);
+    const out = { fleetActivity: activity.body, agentRoster: roster.body };
+    if (ticket !== undefined && phase !== undefined) {
+        const leases = await api.getJson("/api/v1/lease/attributions", { query: { ticket, phase } });
+        out.leaseAttributions = leases.body;
+    }
+    if (args.json) {
+        ctx.stdout(JSON.stringify(out));
+        return 0;
+    }
+    ctx.stdout(`fleet activity: ${JSON.stringify(out.fleetActivity)}`);
+    ctx.stdout(`agent roster: ${JSON.stringify(out.agentRoster)}`);
+    if (out.leaseAttributions !== undefined) {
+        ctx.stdout(`lease attributions (${ticket} ${phase}): ${JSON.stringify(out.leaseAttributions)}`);
+    }
+    return 0;
+}
+/**
+ * `queue` — the dispatch order. The route is per-team and REQUIRES `?team=` ("bad team", 400), but
+ * a customer asking "what is next?" rarely means one team, so an omitted `--team` reads every team
+ * the tenant contract names rather than sending a call the route will refuse.
+ */
+export async function cmdQueue(args, ctx) {
+    const cfg = requireConfig(ctx);
+    const api = apiClient(cfg, ctx);
+    const named = flagString(args, "team");
+    let teams;
+    if (named !== undefined) {
+        teams = [named];
+    }
+    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("queue needs --team: the tenant contract names no team to read a queue for");
+        }
+    }
+    const bodies = await Promise.all(teams.map(async (team) => [team, (await api.getJson("/api/v1/dispatch-queue/current", { query: { team } })).body]));
+    // One team asked for → its envelope, unwrapped, exactly as before. Several → keyed by team, so a
+    // caller can tell whose queue a row belongs to.
+    const out = bodies.length === 1 && named !== undefined ? bodies[0][1] : Object.fromEntries(bodies);
+    ctx.stdout(args.json ? JSON.stringify(out) : JSON.stringify(out, null, 2));
+    return 0;
+}
+/** The five status words `/api/v1/coding-accounts` reports, in the words a customer reads. */
+export const ACCOUNT_STATUS = {
+    "expired-or-revoked": "expired or revoked — re-enrol it before it can take work",
+    walled: "walled — the provider's usage limit is spent for now",
+    active: "active — observed working",
+    attested: "attested — healthy at last check, no work observed since",
+    unobserved: "unobserved — enrolled, but nothing has been seen from it yet",
+};
+/** One slot as a line a human reads: who it is, what state it is in, and what it is spending on. */
+export function renderAccount(a) {
+    const name = a.label ? `${a.accountSlot ?? "?"} (${a.label})` : (a.accountSlot ?? "?");
+    const harness = a.harness ? `/${a.harness}` : "";
+    const status = a.status ? (ACCOUNT_STATUS[a.status] ?? a.status) : "status unknown";
+    const bits = [`${name}  ${a.provider ?? "?"}${harness}  ${status}`];
+    if (typeof a.bindingUsedPercent === "number") {
+        const resets = typeof a.bindingResetsAtMs === "number" ? `, resets ${new Date(a.bindingResetsAtMs).toISOString()}` : "";
+        bits.push(`usage ${a.bindingUsedPercent}% of the ${a.bindingWindow ?? "binding"} window${resets}`);
+    }
+    if (a.quarantined)
+        bits.push(`quarantined${a.quarantineReason ? `: ${a.quarantineReason}` : ""}`);
+    const holds = a.liveHolds ?? [];
+    if (holds.length > 0)
+        bits.push(`holding ${holds.map((h) => `${h.ticket}/${h.phase}`).join(", ")}`);
+    else if (a.liveHoldsCount)
+        bits.push(`${a.liveHoldsCount} live hold(s)`);
+    return bits.join("  ·  ");
+}
+/**
+ * ⛔ A ROUTE THIS TENANT'S CLOUD DOES NOT SERVE IS SAID OUT LOUD, never rendered as an empty success.
+ * `GET /api/v1/coding-accounts` (CTC-1953) and `GET /api/v1/issues/:id/execution` (CTC-1954) ship
+ * ahead of some tenants' deployed mirror; a 404 there means "your cloud is older than this bundle",
+ * which is a different fact from "you have no coding accounts" and must never print as the latter.
+ */
+function needsNewerCloud(what, cfg) {
+    return new CliError(`${what} needs a newer Catalyst Cloud than ${normalizeBaseUrl(cfg.baseUrl)} is running — the route answered 404. Nothing is wrong with your tenant; ask your operator when the mirror last deployed.`, "route-not-deployed", 3, 404);
+}
+export async function cmdAccounts(args, ctx) {
+    const cfg = requireConfig(ctx);
+    const api = apiClient(cfg, ctx);
+    const res = await api.getJson("/api/v1/coding-accounts", {
+        accept: [404],
+    });
+    if (res.status === 404)
+        throw needsNewerCloud("coding-account status", cfg);
+    const accounts = Array.isArray(res.body) ? res.body : (res.body?.accounts ?? []);
+    if (args.json) {
+        ctx.stdout(JSON.stringify(res.body));
+        return 0;
+    }
+    if (accounts.length === 0) {
+        ctx.stdout(`No coding accounts are enrolled on this tenant — enrol one at ${normalizeBaseUrl(cfg.baseUrl)}/settings/coding-accounts`);
+        return 0;
+    }
+    for (const a of accounts)
+        ctx.stdout(renderAccount(a));
+    return 0;
+}
+/**
+ * `history <ticket>` (and `explain --history`) — the ticket's execution history: per-phase attempts
+ * and outcomes, remediate rounds against the cap, the park sentinel and what releases it, the live
+ * lease, the last advance. Reads `GET /api/v1/issues/:identifier/execution` (CTC-1954).
+ */
+export async function cmdHistory(args, ctx, ticketArg) {
+    const ticket = ticketArg ?? positionals(args)[0];
+    if (!ticket)
+        throw new UsageError("history needs a ticket: history <ticket>");
+    const cfg = requireConfig(ctx);
+    const api = apiClient(cfg, ctx);
+    const res = await api.getJson(`/api/v1/issues/${encodeURIComponent(ticket)}/execution`, {
+        accept: [404],
+    });
+    if (res.status === 404)
+        throw needsNewerCloud(`execution history for ${ticket}`, cfg);
+    if (args.json) {
+        ctx.stdout(JSON.stringify(res.body));
+        return 0;
+    }
+    for (const line of renderHistory(ticket, res.body))
+        ctx.stdout(line);
+    return 0;
+}
+/** ⛔ `null` is UNREADABLE, never "nothing happened" — the report's own contract, kept in the prose. */
+export function renderHistory(ticket, doc) {
+    const lines = [];
+    if (doc.hasLadderHistory === false) {
+        lines.push(`${ticket}: no ladder history recorded${doc.note ? ` — ${doc.note}` : ""}.`);
+    }
+    const phases = doc.phases;
+    if (phases === null || phases === undefined) {
+        lines.push(`${ticket}: the per-phase table could not be read (unreadable, not empty).`);
+    }
+    else {
+        lines.push(`${ticket} phases (${doc.attemptHistory ?? "latest-per-phase"}):`);
+        for (const p of phases) {
+            const fail = p.lastFailureClass ? `, last failure ${p.lastFailureClass}${p.consecutiveFailures ? ` ×${p.consecutiveFailures}` : ""}` : "";
+            lines.push(`  ${p.phase}: ${p.status ?? "?"} (attempt ${p.attempt ?? "?"})${fail}`);
+        }
+    }
+    if (doc.failure) {
+        const f = doc.failure;
+        lines.push(`Last failure: ${f.phase} — ${f.failureMode}${f.failureDetail ? ` (${f.failureDetail})` : ""}${f.summary ? `: ${f.summary}` : ""}`);
+    }
+    if (doc.remediate && typeof doc.remediate.roundsDispatched === "number") {
+        lines.push(`Remediate rounds dispatched: ${doc.remediate.roundsDispatched}${typeof doc.remediate.cap === "number" ? ` (cap ${doc.remediate.cap})` : ""}`);
+    }
+    if (doc.park) {
+        lines.push(`Parked at ${doc.park.phase ?? "?"} (${doc.park.sentinel}): ${doc.park.selfReleases ? "releases itself" : "needs an operator"} — ${doc.park.releasedBy}`);
+    }
+    for (const l of doc.lease ?? [])
+        lines.push(`Live lease: ${l.phase} held by ${l.holder ?? "?"} until ${new Date(l.deadlineMs).toISOString()}`);
+    if (doc.lastAdvance) {
+        lines.push(`Last advance: ${doc.lastAdvance.phase} → ${doc.lastAdvance.toSlot ?? "?"} (${doc.lastAdvance.landed ? "landed" : "not landed"})`);
+    }
+    for (const u of doc.unreadable ?? [])
+        lines.push(`Unreadable: ${u.table} (${u.error}) — absent from this report, not absent from the ticket.`);
+    return lines;
+}