@tokenoftrust/cli 1.4.0-rc.15 → 1.4.0-rc.17

package/bin/tot.mjs

@@ -16,8 +16,11 @@
  *   tot preview               push your store to a reviewable preview   ← built (validate + push preview ref; MCP preview_status read-back). `submit`/`deploy` are teaching aliases.
  *   tot ship                  publish the current green aggregate live  ← built (GET/POST /api/changes/ship → b09 orchestrator; exact plan + y/N confirm; waits for VERIFIED live truth)
  *   tot accept / tot merge    queue a PR into the preview aggregate      ← built (b08: plan + y/N confirm → POST /api/changes/integrate = b07 queue enqueue; NO merge-to-main, NO go-live; refuses non-TTY without --yes)
+ *   tot sync                  fetch `preview` + merge it into your branch ← built (b16: the common accept-conflict recovery path; local-only, stops safely on conflict)
  *   tot rollback [<version>]  instant re-point to a prior live version  ← built (u3 promotion_status/promotion_rollback seam; diff + y/N confirm; refuses non-TTY / ineligible)
  *   tot pr                    list / view / close your candidate PRs    ← built (candidate_status/candidate_close; gh-pr-shaped)
+ *   tot branches              full branch-cleanup report (every branch, not just open PRs)  ← built (b14: candidate_list)
+ *   tot cleanup               owner-confirmed branch GC (deletes terminal branches only)     ← built (b14: candidate_list + candidate_delete; --dry-run classifies only)
  *   tot doctor                check this machine is ready
  *   tot ideas                 copy-paste AI prompts that reliably wow
  *   tot feedback              send a note to ToT + your recent CLI activity  ← built (activity-log.mjs → feedback_submit MCP tool)
@@ -66,10 +69,15 @@ tot — Token of Trust developer CLI
   tot preview               push your store to a reviewable preview
   tot ship                  publish the tenant's current green aggregate live (plan → confirm → ship)
   tot accept / tot merge    queue a PR into the preview aggregate — operator verb, no go-live (plan → confirm → integrate)
+  tot sync                  fetch \`preview\` and merge it into your local branch (accept-conflict recovery)
   tot rollback [<version>]  instant re-point to a prior live version (list → confirm → rollback)
+  tot revert --preview <PR|sha>  remove already-integrated content from the preview aggregate via a new revert commit — no force-reset (plan → confirm → revert)
+  tot hotfix --pr <N>       OWNER-ONLY exception: release an urgent fix from main to live, bypassing unshipped preview work (plan → confirm → release → auto forward-integrate)
   tot retire                evict a candidate PR's preview to reclaim space — operator verb, rebuildable (plan → confirm → evict)
   tot go-live               cut the apex domain over to the storefront (readiness → confirm → cutover)
   tot pr                    list / view / close your candidate PRs
+  tot branches              full branch-cleanup report — every branch, any PR state, cleanup eligibility
+  tot cleanup               owner-confirmed branch GC (--dry-run to classify only; deletes terminal branches only)
   tot doctor                check this machine is ready
   tot ideas                 copy-paste AI prompts that reliably wow
   tot feedback "<msg>"      send feedback to Token of Trust (attaches recent activity)
@@ -184,11 +192,42 @@ async function dispatch(cmd, rest, ctx) {
     return run(rest, ctx);
   }
 
+  // `sync` is the common accept-conflict recovery path (P1 item 12): fetches the
+  // protected `preview` branch and merges it into the developer's local branch so
+  // they can resolve locally, then re-`tot preview`. Purely local — no push, no
+  // MCP call, never touches the shared `preview`/`main` refs themselves. See
+  // sync.mjs's header for the full contract.
+  if (cmd === "sync") {
+    const { run } = await import("../src/commands/sync.mjs");
+    return run(rest, ctx);
+  }
+
   if (cmd === "rollback") {
     const { run } = await import("../src/commands/rollback.mjs");
     return run(rest, ctx);
   }
 
+  // `revert --preview <PR|integration-sha>` removes already-integrated content from
+  // the protected `preview` aggregate via a NEW auditable revert commit (b21) — NO
+  // force-reset, NO touch to main/live. Backed by POST /api/changes/revert (b07's
+  // TenantIntegrationQueue.enqueueRevert). To undo something already LIVE, that's
+  // `tot rollback`, not this. See revert.mjs's header.
+  if (cmd === "revert") {
+    const { run } = await import("../src/commands/revert.mjs");
+    return run(rest, ctx);
+  }
+
+  // `hotfix --pr <N>` is the OWNER-ONLY EXCEPTION lane (b22): release an urgent fix
+  // from `main` to live while `preview` still holds other unshipped work, EXCLUDING
+  // that unshipped preview head, then automatically forward-integrate main → preview
+  // and re-validate. It is DELIBERATELY a distinct verb — never a `--base main` flag
+  // on `tot ship` (which publishes the whole green preview aggregate). Backed by
+  // GET/POST /api/changes/hotfix → b22's HotfixOrchestrator. See hotfix.mjs's header.
+  if (cmd === "hotfix") {
+    const { run } = await import("../src/commands/hotfix.mjs");
+    return run(rest, ctx);
+  }
+
   // `retire` evicts a candidate PR's hosted preview to reclaim space (unit U7) —
   // a DISTINCT operator verb from `accept`/reject: retire touches no change
   // lifecycle and is reversible-by-rebuild (`tot preview build`). See retire.mjs.
@@ -207,6 +246,24 @@ async function dispatch(cmd, rest, ctx) {
     return run(rest, ctx);
   }
 
+  // `branches` is the FULL branch-cleanup report (every branch, any PR state) —
+  // distinct from `tot pr list`, which only shows OPEN PRs (P1 item 9). Read-only;
+  // always safe to run, and the report `tot cleanup` reuses before deleting anything.
+  if (cmd === "branches") {
+    const { run } = await import("../src/commands/branches.mjs");
+    return run(rest, ctx);
+  }
+
+  // `cleanup` is owner-confirmed BRANCH GC (P1 items 9/10) — an irreversible git-ref
+  // delete, distinct from `tot retire`'s hosted-preview eviction (rebuildable, no
+  // branch touched). `--dry-run` classifies and prints; it never deletes. Age alone
+  // never makes a branch eligible; main/preview are always kept; orphans are
+  // quarantined, never auto-deleted. See cleanup.mjs's header.
+  if (cmd === "cleanup") {
+    const { run } = await import("../src/commands/cleanup.mjs");
+    return run(rest, ctx);
+  }
+
   if (cmd === "app") {
     const { run } = await import("../src/commands/app/index.mjs");
     return run(rest, ctx);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "1.4.0-rc.15",
+  "version": "1.4.0-rc.17",
   "description": "Token of Trust developer CLI — clone a tenant store, run it locally with save→reload, and submit it for preview. Installs the `tot` command.",
   "license": "Apache-2.0",
   "author": "Token of Trust",

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;
+  }
+}

package/src/commands/cleanup.mjs

@@ -0,0 +1,268 @@
+/**
+ * `tot cleanup` — owner-confirmed branch GC (P1 items 9+10 of the
+ * branch-lifecycle-and-integration-preview contract's "Current gaps").
+ *
+ * `tot cleanup --dry-run` runs the SAME fresh server-side classification
+ * `tot branches` shows (b13's `candidate_list` MCP tool) and prints exactly
+ * which refs are eligible to delete and WHY — no writes, ever, no matter what
+ * else is passed. An owner-confirmed execution mode (`--yes`, or an
+ * interactive y/N via the shared plan affordance) then deletes ONLY that
+ * exact eligible set: one `candidate_delete` call per ref. The server
+ * RE-CLASSIFIES FRESH before every single delete (see branch-cleanup-tools.ts)
+ * — this CLI's dry-run read is a convenience for the human, never the source
+ * of truth the delete trusts.
+ *
+ * Distinct from `tot retire` (evicts a HOSTED PREVIEW artifact, rebuildable,
+ * touches no git ref) — `tot cleanup` is branch GC: an irreversible ref
+ * delete. See retire.mjs's header for that distinction.
+ *
+ * THE CONTRACT'S HARD RULES, ENFORCED SERVER-SIDE AND NEVER RELAXED HERE:
+ *   - age alone NEVER makes an open candidate deletable (`stale-open` is a
+ *     WARN bucket only);
+ *   - `main`/`preview` classify as `protected` and are never eligible;
+ *   - an `orphan` (no PR record in any state) is quarantined for owner
+ *     review, never auto-deleted.
+ * This CLI does not re-derive eligibility — it only ever deletes a ref the
+ * server's `candidate_list` marked `eligibleForDelete: true` moments earlier,
+ * and the server independently re-checks that before acting.
+ *
+ * Dependency-free (global fetch via mcp.mjs's client + the shared plan module).
+ */
+import { createMcpClient } from "../mcp.mjs";
+import { establishSession, AuthUnavailableError } from "../auth.mjs";
+import { fail } from "../errors.mjs";
+import { planForAction, printPlanAndConfirm } from "../plan.mjs";
+import { resolveRepoAndTenant, renderBranchesTable, formatBranchRow } from "./branches.mjs";
+
+const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
+
+const USAGE = `tot cleanup — owner-confirmed branch GC (deletes terminal candidate branches only)
+
+  tot cleanup --dry-run              classify + print the eligible-to-delete set; delete nothing
+  tot cleanup                        classify, print the plan, then ask to confirm before deleting
+  tot cleanup --yes                  classify and delete the eligible set without prompting
+
+  Deletes ONLY branches the server just (re-)classified as "integrated" (PR
+  merged) or "closed-or-rejected" (PR closed without merging). NEVER deletes
+  by age alone, NEVER touches \`main\`/\`preview\`, and NEVER deletes an orphan
+  (no PR record) — orphans are reported, not removed. \`tot retire\` is a
+  DIFFERENT verb: it evicts a hosted preview artifact (rebuildable), not a
+  git branch.
+
+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).
+  --ref <ref>                Narrow deletion to exactly this one eligible ref
+                             (still refused if it isn't eligible).
+  --dry-run                  Classify and print the eligible set; delete nothing.
+  --yes, -y                  Skip the confirmation prompt.
+  --mcp <url>                MCP base URL (default: env MCP_BASE_URL / TOT_MCP_URL)
+  --identity <id>            Prefer this cached identity over the default.
+  --help, -h                 Show this help.`;
+
+/** Parse `tot cleanup` argv. Pure — unit-testable. */
+export function parseCleanupArgs(argv) {
+  const a = {
+    tenant: null,
+    repo: null,
+    staleAfterDays: null,
+    ref: null,
+    dryRun: false,
+    yes: false,
+    mcp: null,
+    identity: null,
+    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 === "--ref") a.ref = argv[++i];
+    else if (t === "--dry-run") a.dryRun = true;
+    else if (t === "--yes" || t === "-y") a.yes = true;
+    else if (t === "--mcp") a.mcp = argv[++i];
+    else if (t === "--identity") a.identity = argv[++i];
+    else if (t === "--help" || t === "-h") a.help = true;
+  }
+  return a;
+}
+
+/** Branches the fresh classification marked eligible. Pure. */
+export function eligibleRefs(report) {
+  return (report?.branches || []).filter((b) => b.eligibleForDelete === true);
+}
+
+/** Branches the fresh classification quarantined (orphans). Pure. */
+export function quarantinedRefs(report) {
+  return (report?.branches || []).filter((b) => b.quarantine === true);
+}
+
+/**
+ * Render the dry-run view: the same table `tot branches` renders, then the
+ * exact eligible set + why, then the quarantined orphans + why they are NOT
+ * in that set. Pure — unit-tested.
+ * @param {any} report
+ * @param {ReturnType<typeof eligibleRefs>} eligible
+ * @returns {string[]}
+ */
+export function renderCleanupDryRun(report, eligible) {
+  const lines = [];
+  const repoLabel = report?.repo || "(unknown repo)";
+  lines.push(
+    `Branch cleanup classification for ${repoLabel} — generated ${report?.generatedAtUtc || "(unknown)"} ` +
+      `(stale-after ${report?.staleAfterDays ?? "?"}d)`,
+  );
+  lines.push("");
+  lines.push(...renderBranchesTable((report?.branches || []).map(formatBranchRow)));
+  lines.push("");
+  if (!eligible.length) {
+    lines.push("Eligible to delete: none.");
+  } else {
+    lines.push(`Eligible to delete (${eligible.length}):`);
+    for (const b of eligible) {
+      lines.push(`  ${b.ref}  (${b.sha || "—"})`);
+      lines.push(`    reason: ${b.reason}`);
+    }
+  }
+  const quarantined = quarantinedRefs(report);
+  if (quarantined.length) {
+    lines.push("");
+    lines.push(
+      `Quarantined orphans (${quarantined.length}) — no PR record in any state; NOT deleted, needs owner review:`,
+    );
+    for (const b of quarantined) lines.push(`  ${b.ref}  (${b.sha || "—"})`);
+  }
+  return lines;
+}
+
+/** @param {string[]} argv @param {any} ctx */
+export async function run(argv, ctx) {
+  const env = process.env;
+  const args = parseCleanupArgs(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 classify branches for ${repo}: ${report.error || report.message || "unknown error"}`,
+          "check --tenant / --repo, then re-run",
+        ),
+      );
+      return 1;
+    }
+
+    let eligible = eligibleRefs(report);
+
+    if (args.ref) {
+      const only = eligible.find((b) => b.ref === args.ref);
+      if (!only) {
+        console.error(
+          fail(
+            `"${args.ref}" is not currently eligible for deletion`,
+            "run `tot cleanup --dry-run` to see the current eligible set",
+          ),
+        );
+        return 1;
+      }
+      eligible = [only];
+    }
+
+    console.log(renderCleanupDryRun(report, eligible).join("\n"));
+
+    if (args.dryRun) {
+      console.log("\nDry run — nothing was deleted.");
+      return 0;
+    }
+    if (!eligible.length) {
+      console.log("\nNothing eligible to delete.");
+      return 0;
+    }
+
+    const planLines = planForAction({
+      action: "cleanup",
+      tenant: tenant || repo,
+      refs: eligible.map((b) => ({ ref: b.ref, sha: b.sha, reason: b.reason })),
+    });
+    const { confirmed, reason } = await printPlanAndConfirm(planLines, {
+      yes: args.yes,
+      question: `Delete these ${eligible.length} eligible branch(es) now?`,
+    });
+    if (!confirmed) {
+      if (reason === "non-tty") {
+        console.error(
+          fail(
+            "refusing to delete branches 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 deleted.");
+      return 1;
+    }
+
+    let failures = 0;
+    for (const b of eligible) {
+      try {
+        const res = await client.callTool("candidate_delete", {
+          repo,
+          ref: b.ref,
+          expectedSha: b.sha,
+        });
+        if (res?.deleted) {
+          console.log(`✓ deleted ${b.ref}${res.alreadyAbsent ? " (already absent)" : ""}`);
+        } else {
+          failures++;
+          console.error(`✗ ${b.ref}: ${res?.error || res?.message || res?.status || "not deleted"}`);
+        }
+      } catch (e) {
+        failures++;
+        console.error(`✗ ${b.ref}: ${String(e?.message || e)}`);
+      }
+    }
+    if (failures) {
+      console.error(`\n${failures} of ${eligible.length} deletion(s) failed — see above.`);
+      return 1;
+    }
+    console.log(`\n✓ deleted ${eligible.length} branch(es).`);
+    return 0;
+  } catch (e) {
+    if (e instanceof AuthUnavailableError) {
+      console.error(fail("sign in to clean up 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;
+  }
+}