@tokenoftrust/cli 1.4.0-rc.2 → 1.4.0-rc.20

package/src/commands/accept.mjs

@@ -0,0 +1,313 @@
+/**
+ * `tot accept --tenant <t> --pr <N>` (alias: `tot merge`) — OPERATOR verb: QUEUE a
+ * PR's integration into the protected `preview` AGGREGATE. This SUPERSEDES the
+ * retired `tot accept` = merge-PR→main semantics (operator-console U5): accepting a
+ * change no longer merges it to main — it enqueues it into the tenant's shared
+ * `preview` aggregate, where b07's tenant-serialized queue merges it (b06
+ * `candidate_accept`, preview-base only), rebuilds the aggregate, and moves the
+ * shared preview pointer ONLY when combined evidence is green.
+ *
+ * DISTINCT from `tot ship`: accept is NOT go-live. It touches NO `main` and NO live
+ * channel; a green aggregate is promoted live only by a later `tot ship`. And it is
+ * NOT `tot preview build` (which materializes ONE candidate's own preview in
+ * isolation) — accept lands the candidate into the SHARED aggregate other reviewers
+ * see.
+ *
+ * TARGET RESOLUTION — `--pr N --tenant t` names the PR; the server resolves it to its
+ * candidate from the tenant's ReviewEnvironment index (unit b04 — tenant + PR, NO
+ * chg-id). An explicit `--change-id` is still accepted (targets a specific record),
+ * but is no longer REQUIRED — the whole point of b08 is that a PR number is enough.
+ *
+ * TRANSPORT — the honest accept path is `POST /api/changes/integrate` (the ONE call
+ * site of b07's `TenantIntegrationQueue.enqueue`). Like `tot ship --pr` (U16) and
+ * `tot pr list --tenant` (U17), the CLI reaches it with the OPERATOR-SECRET Bearer
+ * transport (`resolveOperatorSecret` + `X-Tot-Owner` + `x-tot-capability`), since the
+ * CLI holds no storefront cookie. The response is the honest `IntegrateOutcome` —
+ * `queueState` / `runState` / `pointerMoved` / `aggregateSha` / `statusMessage` —
+ * which this verb renders VERBATIM, never a bare "merged".
+ *
+ * HUMAN GATE — integrating into the shared preview is a decision a human makes, so
+ * this ALWAYS states the EXACT plan (shared `planForAction`, unit U10: which PR,
+ * which tenant, "queue for integration into the preview aggregate — NO merge, NO
+ * go-live") and requires an explicit confirm. `--yes` is an explicit affirmative; a
+ * non-TTY without `--yes` is refused (mirrors `tot ship`'s non-TTY refusal).
+ *
+ * Dependency-free (global fetch + the shared plan module).
+ */
+import { fail } from "../errors.mjs";
+import { planForAction, printPlanAndConfirm } from "../plan.mjs";
+// Reuse `tot ship`'s operator-secret precedence verbatim so accept + ship + pr-list
+// speak ONE operator-auth contract, not three.
+import { resolveOperatorSecret } from "./ship.mjs";
+
+const DEFAULT_STOREFRONT_URL = "https://storefront.tokenoftrust.store";
+
+const USAGE = `tot accept — queue a PR's integration into the preview aggregate (alias: tot merge)
+
+  tot accept --tenant <t> --pr <N>
+  tot merge   --tenant <t> --pr <N>   (same command)
+
+  Queues the given PR for integration into the tenant's protected \`preview\`
+  aggregate: the serialized queue merges it into \`preview\` (preview-base only),
+  rebuilds the aggregate, runs combined evidence, and moves the shared preview
+  pointer ONLY when green. Accepting does NOT merge to main and does NOT go live —
+  a green aggregate is promoted live later by \`tot ship\`.
+
+  Integrating into the shared preview is a human decision: this ALWAYS prints the
+  exact plan and asks for an explicit confirm. There is no default-yes; a non-TTY
+  without --yes is refused rather than silently proceeding.
+
+Options:
+  --tenant <appDomain>   Target tenant (e.g. tokenoftrust.com). Defaults to the
+                         current checkout's tenant when run inside one.
+  --pr <N>               PR number to integrate. The server resolves it to its
+                         candidate from the tenant's queue (no --change-id needed).
+  --change-id <id>       Target a specific change record instead of a PR number.
+  --head-sha <sha>       Optional expected PR head sha (expectedHeadSha) — an
+                         optimistic-concurrency guard against a PR that moved.
+  --url <origin>         storefront origin (default: env TOT_STOREFRONT_URL)
+  --secret <s>           operator secret (prefer the env vars below)
+  --yes, -y              Skip the interactive confirm (still an explicit human
+                         affirmative — there is no default-yes).
+  --help, -h             Show this help.
+
+  Operator secret (from env, first found): PREVIEW_RECONCILE_SECRET,
+  GRANTS_ADMIN_SECRET, TOT_OPERATOR_SECRET (or pass --secret).`;
+
+/** Parse `tot accept` / `tot merge` argv. Pure — unit-testable. */
+export function parseAcceptArgs(argv) {
+  const a = {
+    tenant: null,
+    pr: null,
+    changeId: null,
+    headSha: null,
+    url: null,
+    secret: null,
+    identity: null,
+    yes: false,
+    help: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i];
+    if (t === "--tenant") a.tenant = argv[++i];
+    else if (t === "--pr") a.pr = argv[++i];
+    else if (t === "--change-id") a.changeId = argv[++i];
+    else if (t === "--head-sha" || t === "--head") a.headSha = argv[++i];
+    else if (t === "--url") a.url = argv[++i];
+    else if (t === "--secret") a.secret = argv[++i];
+    else if (t === "--identity") a.identity = argv[++i];
+    else if (t === "--yes" || t === "-y") a.yes = true;
+    else if (t === "--help" || t === "-h") a.help = true;
+  }
+  return a;
+}
+
+/**
+ * Normalise a `POST /api/changes/integrate` body to the honest terminal aggregate
+ * fields this verb renders. Reads defensively so a plausible field rename degrades
+ * rather than crashes. Pure — unit-tested.
+ * @param {any} data
+ * @returns {{ ok:boolean, queueState:string|null, runState:string|null,
+ *   pointerMoved:boolean, aggregateSha:string|null, statusMessage:string|null,
+ *   reason:string|null, changeId:string|null, prNumber:number|null, error:string|null, raw:any }}
+ */
+export function normalizeIntegrateResponse(data) {
+  const o = data && typeof data === "object" ? data : {};
+  return {
+    ok: o.ok === true,
+    queueState: typeof o.queueState === "string" ? o.queueState : null,
+    runState: typeof o.runState === "string" ? o.runState : null,
+    pointerMoved: o.pointerMoved === true,
+    aggregateSha: typeof o.aggregateSha === "string" ? o.aggregateSha : null,
+    statusMessage: typeof o.statusMessage === "string" ? o.statusMessage : null,
+    reason: typeof o.reason === "string" ? o.reason : null,
+    changeId: typeof o.changeId === "string" ? o.changeId : null,
+    prNumber: typeof o.prNumber === "number" ? o.prNumber : null,
+    error: typeof o.error === "string" ? o.error : null,
+    raw: data,
+  };
+}
+
+/**
+ * Render the terminal aggregate status in house style — the honest queue/run state,
+ * NEVER a bare "merged". Pure given its inputs; returns the process exit code.
+ * @param {ReturnType<typeof normalizeIntegrateResponse>} result
+ * @param {{ tenant:string, label:string }} ctx
+ * @returns {number}
+ */
+export function reportIntegrated(result, { tenant, label }) {
+  const state = `${result.queueState ?? "?"}/${result.runState ?? "—"}`;
+  if (result.ok) {
+    console.log(`\n  ✓ queued ${label} into ${tenant}'s preview aggregate — it is GREEN.`);
+    console.log(`  aggregate: ${state}${result.aggregateSha ? `  (${result.aggregateSha})` : ""}`);
+    if (result.pointerMoved) console.log("  the shared preview pointer moved to this aggregate.");
+    console.log("  → next: `tot ship` to promote this green aggregate live.");
+    return 0;
+  }
+  // Honest non-green: the candidate did NOT land in the shippable aggregate.
+  console.log(`\n  ✗ ${label} did NOT integrate into ${tenant}'s preview aggregate.`);
+  console.log(`  aggregate: ${state}${result.reason ? `  (${result.reason})` : ""}`);
+  if (result.statusMessage) console.log(`  why: ${result.statusMessage}`);
+  console.log("  → next: fix the candidate (re-`tot preview`), then re-run `tot accept`.");
+  return 1;
+}
+
+/**
+ * The accept-means-integrate flow after args are parsed: state the exact plan,
+ * confirm, then POST `/api/changes/integrate` (operator-secret transport) and render
+ * the honest terminal aggregate status. `fetch`/`confirmPlan` injected so it is
+ * unit-tested with no network/TTY.
+ *
+ * @param {{ tenant:string, pr:number|null, changeId:string|null, headSha:string|null,
+ *   secret:string, storefrontUrl?:string|null, yes?:boolean }} params
+ * @param {{ fetch?:typeof fetch, confirmPlan?:typeof printPlanAndConfirm }} [deps]
+ * @returns {Promise<number>} process exit code
+ */
+export async function runIntegrate(
+  { tenant, pr, changeId, headSha, secret, storefrontUrl = null, yes = false },
+  deps = {},
+) {
+  const fetchImpl = deps.fetch || globalThis.fetch;
+  const confirmPlan = deps.confirmPlan || printPlanAndConfirm;
+  const base = (storefrontUrl || DEFAULT_STOREFRONT_URL).trim().replace(/\/+$/, "");
+  const label = pr != null ? `PR #${pr}` : changeId;
+
+  // 1. State the EXACT plan (shared U10 affordance) — queue-integrate-into-preview,
+  //    NO merge, NO go-live — and gate on an explicit confirm.
+  const planLines = planForAction({ action: "accept", tenant, pr, changeId, headSha });
+  const { confirmed, reason } = await confirmPlan(planLines, {
+    yes,
+    question: `Queue ${label} for integration into ${tenant}'s preview aggregate?`,
+  });
+  if (!confirmed) {
+    if (reason === "non-tty") {
+      console.error(
+        fail(
+          "refusing to integrate without confirmation on a non-TTY.",
+          "re-run with --yes (an explicit human affirmative), or from an interactive terminal.",
+        ),
+      );
+      return 2;
+    }
+    console.log("Aborted — nothing was integrated.");
+    return 1;
+  }
+
+  // 2. Operator-secret transport — the CLI holds no storefront cookie, so the
+  //    Bearer + X-Tot-Owner path is its route (same as `tot ship --pr`).
+  if (!secret) {
+    console.error(
+      fail(
+        "integrating a PR is an OPERATOR action — it needs an operator secret",
+        "set PREVIEW_RECONCILE_SECRET (or GRANTS_ADMIN_SECRET / TOT_OPERATOR_SECRET), or pass --secret",
+      ),
+    );
+    return 2;
+  }
+  const authHeaders = {
+    "content-type": "application/json",
+    authorization: `Bearer ${secret}`,
+    "x-tot-owner": tenant,
+    "x-tot-capability": "ship-on-behalf",
+  };
+  const requestBody = {
+    repo: tenant,
+    ...(pr != null ? { prNumber: pr } : {}),
+    ...(changeId ? { changeId } : {}),
+    ...(headSha ? { expectedHeadSha: headSha } : {}),
+  };
+
+  // 3. POST the honest accept path (b07 queue enqueue) and render the terminal state.
+  let res;
+  try {
+    res = await fetchImpl(`${base}/api/changes/integrate`, {
+      method: "POST",
+      headers: authHeaders,
+      body: JSON.stringify(requestBody),
+    });
+  } catch (e) {
+    console.error(
+      fail(`couldn't reach the integration queue at ${base}: ${String(e?.message || e)}`, "check --url / your network, then re-run"),
+    );
+    return 1;
+  }
+
+  let data = {};
+  try {
+    data = await res.json();
+  } catch {
+    /* non-JSON / empty body */
+  }
+  const result = normalizeIntegrateResponse(data);
+
+  // A pre-flight error (auth, unknown tenant, candidate not found) is an HTTP 4xx
+  // with `{ error }` and no queue verdict — surface it distinctly from a red run.
+  if (!res.ok && result.queueState == null) {
+    const msg = result.error || `HTTP ${res.status}`;
+    console.error(
+      fail(
+        `the integration queue refused the request: ${msg}`,
+        res.status === 401 || res.status === 403
+          ? "check the operator secret and that it's authorised for this tenant"
+          : res.status === 404
+            ? `check that ${label} has a built candidate in ${tenant}'s queue (\`tot pr list --tenant ${tenant}\`)`
+            : "check --tenant / --url / --pr, then re-run",
+      ),
+    );
+    return 1;
+  }
+
+  return reportIntegrated(result, { tenant, label });
+}
+
+/**
+ * @param {string[]} argv
+ * @param {any} ctx
+ */
+export async function run(argv, ctx) {
+  const env = process.env;
+  const args = parseAcceptArgs(argv);
+  if (args.help) {
+    console.log(USAGE);
+    return 0;
+  }
+
+  const tenant = (args.tenant || ctx?.tenant || "").trim();
+  if (!tenant) {
+    console.error(
+      fail(
+        "no target tenant.",
+        "pass --tenant <appDomain> (e.g. --tenant tokenoftrust.com), or run inside a store checkout.",
+      ),
+    );
+    return 2;
+  }
+
+  const prRaw = args.pr;
+  const pr =
+    prRaw != null && `${prRaw}`.trim() && Number.isFinite(Number(prRaw)) ? Number(prRaw) : null;
+  const changeId = (args.changeId || "").trim() || null;
+  if (pr == null && !changeId) {
+    console.error(
+      fail(
+        "no PR or change to integrate.",
+        "pass --pr <N> (the PR number to queue), or --change-id <id> to target a specific record.",
+      ),
+    );
+    return 2;
+  }
+
+  const headSha = (args.headSha || "").trim() || null;
+  const storefrontUrl =
+    args.url || env.TOT_STOREFRONT_URL || env.STOREFRONT_BASE_URL || DEFAULT_STOREFRONT_URL;
+
+  return await runIntegrate({
+    tenant,
+    pr,
+    changeId,
+    headSha,
+    secret: resolveOperatorSecret(args.secret, env),
+    storefrontUrl,
+    yes: args.yes,
+  });
+}

package/src/commands/branches.mjs

@@ -0,0 +1,296 @@
+/**
+ * `tot branches` — the full branch-cleanup REPORT for one tenant's repo (P1
+ * item 9 of the branch-lifecycle-and-integration-preview contract: "join
+ * branch, PR, candidate, head SHA, actor, full zoned timestamp, age, evidence,
+ * aggregate status, and cleanup eligibility"). Distinct from `tot pr list`,
+ * which only shows OPEN PRs — this shows EVERY branch on the repo (protected,
+ * active, stale, integrated, closed, orphaned), because that is what a
+ * cleanup decision needs.
+ *
+ * The report itself is server-side classification (b13's `candidate_list` MCP
+ * tool → `classifyBranches`); this command is presentation only — it never
+ * re-derives eligibility, an "aggregate" verdict, or a classification bucket
+ * client-side. The contract's complaint about a "truncated human table" (see
+ * "Candidate branch retirement") is about hidden precision, not columns — so
+ * every SHA and timestamp is printed in full, never shortened.
+ *
+ * KNOWN GAP: the contract asks for an "actor" column, but neither Gitea's
+ * branch record nor its PR record (see `../../gitea/gitea-rest.ts`) carries a
+ * PR author — `candidate_list` does not surface one. Rather than fabricate it
+ * client-side, every row prints `actor: —` and the report states the gap once
+ * up top. Fixing this is a tot-mcp follow-up (surface the PR author from
+ * Gitea), not something this CLI can honestly synthesize.
+ *
+ * `tot cleanup` (cleanup.mjs) reuses `resolveRepoAndTenant` from here so the
+ * two commands resolve "which repo" identically.
+ *
+ * Dependency-free (global fetch via mcp.mjs's client + `git`).
+ */
+import { execFileSync } from "node:child_process";
+import { createMcpClient } from "../mcp.mjs";
+import { establishSession, AuthUnavailableError } from "../auth.mjs";
+import { fail } from "../errors.mjs";
+import { repoNameFromRemote } from "./submit.mjs";
+
+const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
+
+const USAGE = `tot branches — full branch-cleanup report (every branch, not just open PRs)
+
+  tot branches                       report for the current checkout's repo
+  tot branches --tenant <t>          report for <t> (works without a checkout)
+  tot branches --json                emit the raw classification report as JSON
+
+  Joins branch + PR (any state) + candidate ref + head SHA + full zoned
+  timestamp + age + evidence + aggregate status + cleanup eligibility for
+  EVERY branch on the repo — read-only, always safe to run, and the report
+  \`tot cleanup\` reuses before it deletes anything.
+
+Options:
+  --tenant <appDomain>       Target tenant/repo. Defaults to the current
+                             checkout's tenant when run inside one.
+  --repo <name>              Explicit repo name, if it differs from --tenant.
+  --stale-after-days <n>     Idle-day threshold for the "stale-open" warn
+                             bucket. Defaults to the server's policy (14).
+  --mcp <url>                MCP base URL (default: env MCP_BASE_URL / TOT_MCP_URL)
+  --identity <id>            Prefer this cached identity over the default.
+  --json                     Print the raw classification report as JSON.
+  --help, -h                 Show this help.`;
+
+/** Parse `tot branches` argv. Pure — unit-testable. */
+export function parseBranchesArgs(argv) {
+  const a = {
+    tenant: null,
+    repo: null,
+    staleAfterDays: null,
+    mcp: null,
+    identity: null,
+    json: false,
+    help: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i];
+    if (t === "--tenant") a.tenant = argv[++i];
+    else if (t === "--repo") a.repo = argv[++i];
+    else if (t === "--stale-after-days") a.staleAfterDays = Number(argv[++i]);
+    else if (t === "--mcp") a.mcp = argv[++i];
+    else if (t === "--identity") a.identity = argv[++i];
+    else if (t === "--json") a.json = true;
+    else if (t === "--help" || t === "-h") a.help = true;
+  }
+  return a;
+}
+
+/** Best-effort `git remote get-url origin` from a checkout ctx. Never throws. */
+function defaultReadRemoteUrl(ctx) {
+  try {
+    return execFileSync("git", ["-C", ctx.workspacePath, "remote", "get-url", "origin"], {
+      stdio: ["ignore", "pipe", "pipe"],
+    })
+      .toString()
+      .trim();
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Resolve which repo + tenant a branches/cleanup call targets: an explicit
+ * `--repo`/`--tenant` wins; otherwise, inside a checkout, the repo is derived
+ * from the checkout's forge remote (same derivation `tot pr` uses) and the
+ * tenant from the detected context. `repo` (the Gitea repo/tenant-appDomain
+ * name candidate_list expects) falls back to the tenant when neither an
+ * explicit `--repo` nor a checkout is available — this codebase's own naming
+ * convention is that the repo name IS the tenant appDomain. Pure given
+ * `deps.readRemoteUrl` — unit-testable with no real git/network.
+ * @param {{tenant?:string|null, repo?:string|null}} args
+ * @param {any} ctx
+ * @param {{ readRemoteUrl?: (ctx:any) => string }} [deps]
+ * @returns {{ repo: string|null, tenant: string|null, error: string|null }}
+ */
+export function resolveRepoAndTenant(args, ctx, deps = {}) {
+  const readRemoteUrl = deps.readRemoteUrl || defaultReadRemoteUrl;
+  const tenant = (args.tenant || ctx?.tenant || "").trim() || null;
+  let repo = (args.repo || "").trim() || null;
+  if (!repo && ctx?.mode === "checkout" && ctx?.workspacePath) {
+    const remote = readRemoteUrl(ctx);
+    repo = remote ? repoNameFromRemote(remote) : null;
+  }
+  if (!repo) repo = tenant;
+  if (!repo) {
+    return {
+      repo: null,
+      tenant,
+      error: fail(
+        "no target repo/tenant.",
+        "pass --tenant <appDomain> (e.g. --tenant tokenoftrust.com), or run inside a store checkout.",
+      ),
+    };
+  }
+  return { repo, tenant: tenant || repo, error: null };
+}
+
+const COLUMNS = [
+  ["branch", "BRANCH"],
+  ["pr", "PR"],
+  ["candidate", "CANDIDATE"],
+  ["sha", "HEAD SHA"],
+  ["actor", "ACTOR"],
+  ["updated", "UPDATED (UTC)"],
+  ["age", "AGE"],
+  ["evidence", "EVIDENCE"],
+  ["status", "STATUS"],
+  ["aggregate", "AGGREGATE"],
+  ["cleanup", "CLEANUP"],
+];
+
+/**
+ * Adapt one `candidate_list` `BranchCleanupRecord` to this table's row shape.
+ * Every value is printed in full — no truncated SHAs, no truncated
+ * timestamps (see module header re: the contract's "truncated human table"
+ * complaint). Pure — unit-tested.
+ * @param {any} b - a BranchCleanupRecord from the MCP `candidate_list` tool
+ */
+export function formatBranchRow(b) {
+  const pr = typeof b.prNumber === "number" ? `#${b.prNumber}` : "#—";
+  const candidate = b.changeId || "—";
+  const sha = b.sha || "—";
+  // KNOWN GAP — see module header: candidate_list does not surface a PR
+  // author today, so this is honestly "—", never fabricated.
+  const actor = "—";
+  const updated = b.commitTimestampUtc || "(unknown)";
+  const age = b.idleDays != null ? `${b.idleDays}d` : "(unknown)";
+  const evidence = b.evidence
+    ? `${b.evidence.checksTotal} check(s) ${b.evidence.allPass ? "all pass" : "NOT all pass"} @ ${b.evidence.generatedAtUtc}`
+    : "no evidence";
+  const aggregate =
+    b.classification === "protected" ? "—" : b.integratedIntoAggregate ? "in preview aggregate" : "not in aggregate";
+  const cleanup = b.eligibleForDelete ? "ELIGIBLE" : b.quarantine ? "QUARANTINED" : "keep";
+  return {
+    branch: b.ref,
+    pr,
+    candidate,
+    sha,
+    actor,
+    updated,
+    age,
+    evidence,
+    status: b.classification ?? "?",
+    aggregate,
+    cleanup,
+    reason: b.reason ?? "",
+  };
+}
+
+/**
+ * Render already-formatted rows as one padded, legible table (header + one
+ * row per branch + an indented `reason:` line — the reason text is often
+ * longer than any fixed column would comfortably hold). Pure — unit-tested.
+ * @param {ReturnType<typeof formatBranchRow>[]} rows
+ * @returns {string[]}
+ */
+export function renderBranchesTable(rows) {
+  if (!rows.length) return ["(no branches)"];
+  const widths = COLUMNS.map(([key, label]) =>
+    Math.max(label.length, ...rows.map((r) => String(r[key] ?? "").length)),
+  );
+  const renderLine = (vals) =>
+    COLUMNS.map(([key], i) => String(vals[key] ?? "").padEnd(widths[i])).join("  ").trimEnd();
+  const lines = [renderLine(Object.fromEntries(COLUMNS.map(([key, label]) => [key, label])))];
+  for (const r of rows) {
+    lines.push(renderLine(r));
+    if (r.reason) lines.push(`    reason: ${r.reason}`);
+  }
+  return lines;
+}
+
+/**
+ * Render the full `candidate_list` report: header, the table, then the
+ * server-computed summary/quarantine counts (never recomputed client-side —
+ * `candidate_list` already returns `summary` and `quarantined`). Pure —
+ * unit-tested.
+ * @param {any} report - the raw `candidate_list` result
+ * @returns {string[]}
+ */
+export function renderBranchesReport(report) {
+  const lines = [];
+  const repoLabel = report?.repo || "(unknown repo)";
+  lines.push(
+    `Branches for ${repoLabel} (org ${report?.org || "?"}) — generated ${report?.generatedAtUtc || "(unknown)"} ` +
+      `(stale-after ${report?.staleAfterDays ?? "?"}d)`,
+  );
+  lines.push('NOTE: "actor" is not yet surfaced by the server\'s branch-cleanup report — shown as "—" below.');
+  lines.push("");
+  lines.push(...renderBranchesTable((report?.branches || []).map(formatBranchRow)));
+  lines.push("");
+  const summary = report?.summary || {};
+  const summaryParts = Object.entries(summary)
+    .map(([k, v]) => `${k}: ${v}`)
+    .join(", ");
+  lines.push(`Summary — ${report?.branches?.length ?? 0} branch(es): ${summaryParts || "(none)"}`);
+  if (Array.isArray(report?.quarantined) && report.quarantined.length) {
+    lines.push(
+      `Quarantined orphans (${report.quarantined.length}) — no PR record in any state; NEVER auto-deleted: ` +
+        report.quarantined.join(", "),
+    );
+  }
+  return lines;
+}
+
+/** @param {string[]} argv @param {any} ctx */
+export async function run(argv, ctx) {
+  const env = process.env;
+  const args = parseBranchesArgs(argv);
+  if (args.help) {
+    console.log(USAGE);
+    return 0;
+  }
+
+  const { repo, tenant, error } = resolveRepoAndTenant(args, ctx);
+  if (error) {
+    console.error(error);
+    return 2;
+  }
+
+  const baseUrl = args.mcp || env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
+  const client = createMcpClient(baseUrl);
+  try {
+    await establishSession(client, { env, prefer: args.identity || undefined });
+    if (tenant) await client.callTool("client_switch", { tenant });
+
+    const report = await client.callTool("candidate_list", {
+      repo,
+      ...(args.staleAfterDays != null && Number.isFinite(args.staleAfterDays)
+        ? { staleAfterDays: args.staleAfterDays }
+        : {}),
+    });
+
+    if (report?.status === "error" || report?.status === "invalid_input" || report?.error) {
+      console.error(
+        fail(
+          `couldn't list branches for ${repo}: ${report.error || report.message || "unknown error"}`,
+          "check --tenant / --repo, then re-run",
+        ),
+      );
+      return 1;
+    }
+
+    if (args.json) {
+      console.log(JSON.stringify(report, null, 2));
+      return 0;
+    }
+    console.log(renderBranchesReport(report).join("\n"));
+    return 0;
+  } catch (e) {
+    if (e instanceof AuthUnavailableError) {
+      console.error(fail("sign in to list branches", e.hint || "run `tot login`, then re-run"));
+      return 1;
+    }
+    console.error(
+      fail(
+        `couldn't reach the candidate service: ${String(e?.message || e)}`,
+        "check your connection and that you're signed in, then re-run",
+      ),
+    );
+    return 1;
+  }
+}