@catalyst-cloud/catalyst-skills 0.5.0 → 0.8.0

package/dist/execution.js

@@ -1,369 +0,0 @@
-// 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 "./transport.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; `catalyst-skills release <ticket>` releases the park once its cause is fixed",
-    phase_parked: "the offered phase is parked after repeated failures or the repair-round cap; `catalyst-skills release <ticket>` releases it once its cause is fixed",
-    later_phase_lease_held: "an earlier phase is offered while a live container still holds a later phase of this ticket",
-    human_owned_pr: "a person's own pull request holds this ticket; it releases itself when that PR closes or merges",
-    review_not_converging: "review and repair kept finding new problems without converging; a person reads the findings and comments on the ticket to resume",
-    round_threshold: "the ticket spent its lifetime repair budget; answering its ask or pushing a fix buys one more cycle",
-    claim_storm: "this unit was claimed too many times in the last hour, so it waits out the hour; nothing to release",
-    repo_at_capacity: "the repository's runner seats are all in use; it starts when one frees",
-};
-/** Every fail-closed unknown the evaluator names. */
-export const UNKNOWN_REASONS = {
-    ordering_never_published: "the dispatch order has never been published for this team — usually because the team has no saved stage mapping, which does not clear by itself",
-    ordering_stale: "the dispatch order is stale",
-    workflow_mapping_unknown: "the team has no saved stage mapping for dispatch, pr, done and canceled (or a mapped stage was deleted); it does not clear by itself — a tenant owner or admin maps the team in Settings → Linear teams",
-    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 renderDispatchGate(ticket, team, gate) {
-    const slots = (gate.missingSlots ?? []).join(", ");
-    const why = gate.cause === "mapping_state_unresolved"
-        ? `the stage team ${team} mapped for ${slots} no longer exists in Linear.`
-        : gate.cause === "mapping_missing"
-            ? `team ${team} has no saved stage mapping for ${slots}.`
-            : `team ${team} cannot be dispatched (${gate.cause}).`;
-    return [`${ticket} cannot start: ${why}`, gate.remedy].filter(Boolean).join(" ");
-}
-export function renderExplain(ticket, row, team, knownState, gate) {
-    // An unmapped team has no queue and so no rows; its gate is the whole answer, and it outranks the
-    // Backlog probe below, which would otherwise call the team's own Todo "not a dispatch state".
-    if (gate)
-        return renderDispatchGate(ticket, team, gate);
-    if (!row) {
-        // A null dispatch row is not proof the ticket does not exist — the explainer is a dispatch scan. When
-        // `knownState` is set (the mirror answered GET /issues/:id) the ticket is real; it just sits outside a
-        // dispatch column. Only a 404 (knownState null/absent) is truly unknown to the mirror.
-        if (knownState)
-            return `${ticket}: known to the mirror; state ${knownState} is not a dispatch state.`;
-        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;
-    // No dispatch row is not proof of non-existence: probe the mirror so a Backlog ticket reads as known.
-    // The mirror compares identifiers exactly, so normalize (uppercase) as the row lookup above does —
-    // otherwise `explain eng-7` probes a lowercase id, 404s, and reports an existing ENG-7 as unknown.
-    let knownState = null;
-    if (!row) {
-        const probe = await api.getJson(`/api/v1/issues/${encodeURIComponent(ticket.toUpperCase())}`, { accept: [404] });
-        if (probe.status !== 404)
-            knownState = typeof probe.body?.state === "string" ? probe.body.state : "unknown";
-    }
-    // The gate is TEAM-wide: it can say why a real ticket in that team cannot start, never that this id
-    // exists. Applied only when the mirror probe above found the ticket; a 404 keeps the unknown wording.
-    const gate = !row && knownState ? (res.body.eligibility?.dispatchGate ?? null) : null;
-    const explanation = renderExplain(ticket, row, team, knownState, gate);
-    if (args.json) {
-        ctx.stdout(JSON.stringify({ ticket, row, ...(gate ? { dispatchGate: gate } : {}), explanation }));
-    }
-    else {
-        ctx.stdout(explanation);
-    }
-    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.
- */
-export 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" : "does not release itself"} — ${doc.park.releasedBy}`);
-    }
-    // Absent (an older cloud) prints nothing; `null` is a table that could not be read.
-    if (doc.governors === null) {
-        lines.push("Held by: could not be read (unreadable, not empty)");
-    }
-    else if (doc.governors !== undefined && doc.governors.length > 0) {
-        lines.push("Held by:");
-        for (const g of doc.governors) {
-            lines.push(`  ${g.kind}${g.phase ? ` at ${g.phase}` : ""}${g.sentinel ? ` (${g.sentinel})` : ""} — ${g.release ?? "no release named"}`);
-        }
-    }
-    if (doc.releases === null) {
-        lines.push("Releases: could not be read (unreadable, not empty)");
-    }
-    else if (doc.releases !== undefined && doc.releases.length > 0) {
-        lines.push("Releases (newest first):");
-        for (const r of doc.releases) {
-            const what = r.outcome === "released"
-                ? `released: ${(r.released ?? []).map((a) => `${a.op}${a.phase ? ` ${a.phase}` : ""}`).join(", ")}`
-                : `refused: ${(r.refused ?? []).map((x) => x.code).join(", ")}`;
-            lines.push(`  ${new Date(r.atMs).toISOString()} ${r.outcome} by ${r.actor.kind}:${r.actor.id} — "${r.because}" — ${what}`);
-        }
-    }
-    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;
-}

package/dist/oauth.js

@@ -1,300 +0,0 @@
-import { discoveryCachePathFor, loadConfig, normalizeBaseUrl, writeConfig } from "./config.js";
-import { CliError } from "./errors.js";
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
-const DISCOVERY_TTL_MS = 60 * 60_000;
-const REFRESH_SKEW_MS = 60_000;
-const REQUEST_TIMEOUT_MS = 15_000;
-const SLOW_DOWN_BUMP_MS = 5_000;
-const MAX_POLL_BACKOFF_MS = 30_000;
-const REFRESH_MAX_ATTEMPTS = 4;
-const REFRESH_BASE_BACKOFF_MS = 500;
-const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
-let memo = null;
-/** Test seam: forget the cached discovery document. */
-export function resetDiscoveryCache() {
-    memo = null;
-}
-function readDiscoveryDisk(home) {
-    const path = discoveryCachePathFor(home);
-    if (!existsSync(path))
-        return null;
-    try {
-        const parsed = JSON.parse(readFileSync(path, "utf8"));
-        if (isDiscovery(parsed.doc) && typeof parsed.fetchedAt === "number" && typeof parsed.baseUrl === "string")
-            return parsed;
-    }
-    catch {
-        // a corrupt cache is just a cache miss
-    }
-    return null;
-}
-function isDiscovery(v) {
-    if (typeof v !== "object" || v === null)
-        return false;
-    const d = v;
-    return ["clientId", "issuer", "deviceAuthorizationUrl", "tokenUrl", "jwksUrl"].every((k) => typeof d[k] === "string");
-}
-export async function fetchDiscovery(ctx, baseUrl, opts = {}) {
-    const base = normalizeBaseUrl(baseUrl);
-    const nowMs = ctx.now().getTime();
-    const fresh = (e) => e !== null && e.baseUrl === base && nowMs - e.fetchedAt < DISCOVERY_TTL_MS;
-    if (!opts.refresh) {
-        if (fresh(memo))
-            return memo.doc;
-        const disk = readDiscoveryDisk(ctx.home);
-        if (fresh(disk)) {
-            memo = disk;
-            return disk.doc;
-        }
-    }
-    const url = `${base}/api/v1/auth/cli`;
-    const res = await safeFetch(ctx, url, { headers: { accept: "application/json" } });
-    if (!res.ok) {
-        throw new CliError(`could not read the login discovery document (${res.status}) at ${url} — is this a Catalyst Cloud origin?`, "discovery-failed");
-    }
-    const doc = (await parseJson(res, url));
-    if (!isDiscovery(doc))
-        throw new CliError(`the login discovery document at ${url} is not the expected shape`, "discovery-shape");
-    const entry = { baseUrl: base, fetchedAt: nowMs, doc };
-    memo = entry;
-    try {
-        writeFileSync(discoveryCachePathFor(ctx.home), JSON.stringify(entry, null, 2) + "\n");
-    }
-    catch {
-        // the disk cache is an optimisation; the in-memory memo is enough
-    }
-    return doc;
-}
-/**
- * Run the device-authorization grant to completion and return the stored session block. Prints the
- * user code and where to enter it; on a TTY it also opens the completion URL. Polls at the server's
- * `interval`, honours `slow_down`, and is bounded by `AbortSignal.timeout(expires_in)` so it can
- * never poll past the device code's own lifetime.
- */
-export async function deviceFlowLogin(ctx, baseUrl, deps = {}) {
-    const sleep = deps.sleep ?? defaultSleep;
-    const discovery = await fetchDiscovery(ctx, baseUrl);
-    const auth = await deviceAuthorize(ctx, discovery);
-    ctx.stdout("");
-    ctx.stdout(`To connect this machine, visit:  ${auth.verification_uri}`);
-    ctx.stdout(`and enter the code:              ${auth.user_code}`);
-    if ((deps.isTty ?? (() => false))()) {
-        try {
-            (deps.openBrowser ?? (() => { }))(auth.verification_uri_complete);
-            ctx.stdout("Opened your browser to that page — approve there, or use the code above.");
-        }
-        catch {
-            // a browser that will not open is not a failure; the code and URL still work
-        }
-    }
-    ctx.stdout("Waiting for you to approve… (Ctrl-C to cancel)");
-    // Terminal states print ONE clear, actionable line and exit 2 (CliError's default). The duration
-    // comes from the device code's own `expires_in`, so it is right whatever the server set.
-    const mins = Math.round(auth.expires_in / 60);
-    const expired = () => new CliError(`the login code expired${mins >= 1 ? ` after ${mins} minute${mins === 1 ? "" : "s"}` : ""} — run: catalyst-skills login again`, "login-expired");
-    const deadline = AbortSignal.timeout(auth.expires_in * 1_000);
-    let intervalMs = Math.max(1, auth.interval) * 1_000;
-    for (;;) {
-        await sleep(intervalMs);
-        // The device code's own lifetime bounds the loop: once it lapses, say so plainly rather than
-        // letting the next fetch's aborted signal surface as a generic network error (Codex P2).
-        if (deadline.aborted)
-            throw expired();
-        let res;
-        try {
-            res = await safeFetch(ctx, discovery.tokenUrl, { method: "POST", headers: formHeaders(), body: form({ grant_type: "urn:ietf:params:oauth:grant-type:device_code", device_code: auth.device_code, client_id: discovery.clientId }) }, deadline);
-        }
-        catch (err) {
-            // The deadline firing mid-fetch is an expiry, not a failure; anything else is a transient
-            // network blip — retry with backoff until the deadline, never abandon the login (CTC-2112 P1).
-            if (deadline.aborted)
-                throw expired();
-            intervalMs = backoff(intervalMs);
-            continue;
-        }
-        if (res.ok) {
-            const pair = (await parseJson(res, discovery.tokenUrl));
-            if (typeof pair.access_token !== "string" || typeof pair.refresh_token !== "string") {
-                throw new CliError("the login token response was missing a token", "login-shape");
-            }
-            return tokensToAuth(ctx, pair.access_token, pair.refresh_token);
-        }
-        const err = await oauthError(res, discovery.tokenUrl);
-        if (err === "authorization_pending")
-            continue;
-        if (err === "slow_down") {
-            intervalMs += SLOW_DOWN_BUMP_MS;
-            continue;
-        }
-        if (err === "access_denied")
-            throw new CliError("login was denied — run: catalyst-skills login to try again", "login-denied");
-        if (err === "expired_token")
-            throw expired();
-        // A transient HTTP failure (request timeout, rate limit, server error) is retried, honouring
-        // Retry-After for a 429; only a genuine, non-transient refusal ends the loop.
-        if (res.status === 408 || res.status === 429 || res.status >= 500) {
-            const retryAfter = Number(res.headers.get("retry-after"));
-            intervalMs = Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter * 1_000 : backoff(intervalMs);
-            continue;
-        }
-        throw new CliError(`login failed (${res.status}): ${err}`, "login-failed");
-    }
-}
-/** Grow the poll interval on a transient failure, capped, so retries never hammer the endpoint. */
-function backoff(intervalMs) {
-    return Math.min(intervalMs * 2, MAX_POLL_BACKOFF_MS);
-}
-/**
- * Persist a rotated token pair WITHOUT clobbering a newer login (Codex P1). A long-running watch or
- * detached replica holds the `cfg` it started with; if the person meanwhile re-ran `login` (a new
- * session, a different tenant, or the key rail), that config is already on disk and must survive. So
- * we reload disk and only write when it is still the same session we just refreshed — or when there
- * is nothing on disk yet. The reloaded doc is written (not our in-memory `cfg`), so its tenant, user
- * and CLI-path fields are preserved and only the auth block advances.
- */
-function persistRotation(ctx, cfg, sessionId, rotated) {
-    let disk;
-    try {
-        disk = loadConfig(ctx.home);
-    }
-    catch {
-        return; // a corrupt/unreadable disk config: don't overwrite what we can't understand
-    }
-    if (disk && disk.auth?.sessionId !== sessionId)
-        return; // a newer login (or a switch to a key) — leave it
-    const target = disk ?? cfg;
-    target.auth = rotated;
-    writeConfig(ctx.home, target); // atomic; the rotated pair survives a crash
-}
-async function deviceAuthorize(ctx, discovery) {
-    const res = await safeFetch(ctx, discovery.deviceAuthorizationUrl, { method: "POST", headers: formHeaders(), body: form({ client_id: discovery.clientId }) });
-    if (!res.ok)
-        throw new CliError(`could not start login (${res.status}) at ${discovery.deviceAuthorizationUrl}`, "login-failed");
-    const d = (await parseJson(res, discovery.deviceAuthorizationUrl));
-    if (typeof d.device_code !== "string" || typeof d.user_code !== "string" || typeof d.verification_uri !== "string") {
-        throw new CliError("the login authorization response was not the expected shape", "login-shape");
-    }
-    return {
-        device_code: d.device_code,
-        user_code: d.user_code,
-        verification_uri: d.verification_uri,
-        verification_uri_complete: d.verification_uri_complete ?? d.verification_uri,
-        expires_in: typeof d.expires_in === "number" ? d.expires_in : 300,
-        interval: typeof d.interval === "number" ? d.interval : 5,
-    };
-}
-// ── the silent refresh ─────────────────────────────────────────────────────────────────────────
-const inFlight = new Map();
-/**
- * The current bearer for `cfg`: the personal key verbatim, or (for an OAuth session) the access
- * token, refreshed in place when it is within 60s of expiry. Concurrent callers that both hit the
- * refresh window share one refresh (single-flight, keyed by the config's home) so the rotating
- * refresh token is spent exactly once.
- */
-export async function bearerFor(ctx, cfg, deps = {}) {
-    if (typeof cfg.key === "string" && cfg.key !== "")
-        return cfg.key;
-    if (!cfg.auth)
-        throw new CliError("this machine is not connected — run: catalyst-skills login", "not-configured");
-    const msToExpiry = Date.parse(cfg.auth.expiresAt) - ctx.now().getTime();
-    if (Number.isFinite(msToExpiry) && msToExpiry > REFRESH_SKEW_MS)
-        return cfg.auth.accessToken;
-    const pending = inFlight.get(ctx.home);
-    if (pending) {
-        const rotated = await pending;
-        return rotated.accessToken;
-    }
-    const promise = refreshAndPersist(ctx, cfg, deps).finally(() => inFlight.delete(ctx.home));
-    inFlight.set(ctx.home, promise);
-    const rotated = await promise;
-    return rotated.accessToken;
-}
-async function refreshAndPersist(ctx, cfg, deps) {
-    const sleep = deps.sleep ?? defaultSleep;
-    const discovery = await fetchDiscovery(ctx, cfg.baseUrl);
-    const current = cfg.auth;
-    let lastStatus = 0;
-    for (let attempt = 0; attempt < REFRESH_MAX_ATTEMPTS; attempt++) {
-        if (attempt > 0)
-            await sleep(REFRESH_BASE_BACKOFF_MS * 2 ** (attempt - 1));
-        const res = await safeFetch(ctx, discovery.tokenUrl, { method: "POST", headers: formHeaders(), body: form({ grant_type: "refresh_token", refresh_token: current.refreshToken, client_id: discovery.clientId }) });
-        if (res.ok) {
-            const pair = (await parseJson(res, discovery.tokenUrl));
-            if (typeof pair.access_token !== "string" || typeof pair.refresh_token !== "string")
-                throw new CliError("the refresh response was missing a token", "session-refresh-shape");
-            const rotated = tokensToAuth(ctx, pair.access_token, pair.refresh_token, current.sessionId);
-            cfg.auth = rotated; // this process keeps using its own refreshed token
-            persistRotation(ctx, cfg, current.sessionId, rotated);
-            return rotated;
-        }
-        lastStatus = res.status;
-        const err = await oauthError(res, discovery.tokenUrl);
-        if (err === "invalid_grant") {
-            // revocation or > inactivity window — the ONLY session-expired case; NOT routine expiry.
-            throw new CliError("your login expired or was revoked — run: catalyst-skills login", "session-expired");
-        }
-        const transient = res.status === 429 || res.status >= 500;
-        if (!transient)
-            throw new CliError(`could not refresh your login (${res.status}): ${err}`, "session-refresh-failed");
-        // transient: fall through to backoff + retry, keeping the stored tokens untouched
-    }
-    throw new CliError(`could not refresh your login after ${REFRESH_MAX_ATTEMPTS} attempts (last status ${lastStatus}) — your tokens are unchanged; try again`, "session-refresh-failed");
-}
-/** The SDK auth strategy for `cfg`: a static token for the key rail, a fresh-per-connect bearer for
- *  the OAuth rail (its `getToken` runs the same refresh path as every HTTP request). */
-export function authStrategyFor(ctx, cfg) {
-    if (typeof cfg.key === "string" && cfg.key !== "")
-        return { kind: "token", token: cfg.key };
-    return { kind: "bearer", getToken: () => bearerFor(ctx, cfg) };
-}
-// ── helpers ──────────────────────────────────────────────────────────────────────────────────────
-function tokensToAuth(ctx, accessToken, refreshToken, fallbackSid) {
-    const claims = decodeJwtClaims(accessToken);
-    const exp = typeof claims.exp === "number" ? claims.exp * 1_000 : ctx.now().getTime() + 15 * 60_000;
-    const sid = typeof claims.sid === "string" ? claims.sid : (fallbackSid ?? "");
-    return { kind: "oauth", accessToken, refreshToken, expiresAt: new Date(exp).toISOString(), sessionId: sid };
-}
-function decodeJwtClaims(token) {
-    const parts = token.split(".");
-    if (parts.length < 2)
-        return {};
-    try {
-        return JSON.parse(Buffer.from(parts[1], "base64url").toString("utf8"));
-    }
-    catch {
-        return {};
-    }
-}
-function formHeaders() {
-    return { "content-type": "application/x-www-form-urlencoded", accept: "application/json" };
-}
-function form(fields) {
-    return new URLSearchParams(fields).toString();
-}
-async function safeFetch(ctx, url, init, signal) {
-    const sig = signal ? AbortSignal.any([signal, AbortSignal.timeout(REQUEST_TIMEOUT_MS)]) : AbortSignal.timeout(REQUEST_TIMEOUT_MS);
-    try {
-        return await ctx.fetch(url, { ...init, signal: sig });
-    }
-    catch (err) {
-        throw new CliError(`could not reach ${url}: ${err instanceof Error ? err.message : String(err)}`, "network");
-    }
-}
-async function parseJson(res, url) {
-    try {
-        return await res.json();
-    }
-    catch {
-        throw new CliError(`${url} returned a non-JSON body`, "shape");
-    }
-}
-/** The OAuth `error` code from a 4xx body, or a short reason when there is none. */
-async function oauthError(res, url) {
-    try {
-        const body = (await res.json());
-        return body.error ?? body.error_description ?? `HTTP ${res.status}`;
-    }
-    catch {
-        return `HTTP ${res.status}`;
-    }
-}