@tokenoftrust/cli 1.4.0 → 1.5.0

package/src/commands/app/dev.mjs

@@ -1,5 +1,5 @@
 /**
- * `tot app dev` — the local Private App harness (PrivateApps epic D6 Chunk D).
+ * `tot app dev` — the local Private App harness (PrivateApps epic).
  * Everything here is OFFLINE: no network beyond the localhost URL you point
  * it at, no MCP, no real ToT credentials. It generates and reuses its own
  * throwaway RS256 keypair per app directory (`.tot/dev-keys.json`) so signing
@@ -49,7 +49,10 @@ function randHex(bytes) {
   return Buffer.from(crypto.getRandomValues(new Uint8Array(bytes))).toString("hex");
 }
 
-/** Load or create the app's throwaway RS256 keypair at `<appDir>/.tot/dev-keys.json`. */
+/**
+ * Load or create the app's throwaway RS256 keypair at `<appDir>/.tot/dev-keys.json`.
+ * @param {string} appDir @param {{ kid?: string }} [opts]
+ */
 export async function ensureDevKeys(appDir, { kid } = {}) {
   const keysPath = join(appDir, ".tot", "dev-keys.json");
   const alg = { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" };
@@ -107,8 +110,9 @@ function runValidate(argv, { appDir }) {
     console.log(`✔ ${manifestPath} is a valid tot-app.json (contract v${result.manifest.contractVersion})`);
     return 0;
   }
-  console.log(`✖ ${manifestPath} — ${result.errors.length} error(s):`);
-  for (const e of result.errors) console.log(`  - ${e}`);
+  const errs = result.errors || [];
+  console.log(`✖ ${manifestPath} — ${errs.length} error(s):`);
+  for (const e of errs) console.log(`  - ${e}`);
   return 1;
 }
 

package/src/commands/app/index.mjs

@@ -1,6 +1,6 @@
 /**
  * `tot app` — the Storefront Private App developer subcommand group
- * (PrivateApps epic D6 Chunks C+D): scaffold a new app, then exercise its
+ * (PrivateApps epic): scaffold a new app, then exercise its
  * webhook/manifest/widget-launch loop entirely offline.
  *
  *   tot app scaffold <name>   materialize a runnable Private App skeleton
@@ -23,11 +23,11 @@ export async function run(argv, ctx) {
 
   if (sub === "scaffold") {
     const { run: runScaffold } = await import("./scaffold.mjs");
-    return runScaffold(rest, ctx);
+    return /** @type {any} */ (runScaffold)(rest, ctx);
   }
   if (sub === "dev") {
     const { run: runDev } = await import("./dev.mjs");
-    return runDev(rest, ctx);
+    return /** @type {any} */ (runDev)(rest, ctx);
   }
 
   console.error(fail(`unknown \`tot app\` subcommand: ${sub}`, "tot app --help"));

package/src/commands/app/scaffold.mjs

@@ -1,6 +1,6 @@
 /**
  * `tot app scaffold <name>` — materialize a runnable Storefront Private App
- * skeleton on disk (PrivateApps epic D6 Chunk C). See ../../app-scaffold.mjs
+ * skeleton on disk (PrivateApps epic). See ../../app-scaffold.mjs
  * for the offline, idempotent copy logic this wraps.
  *
  *   tot app scaffold <name>          scaffold ./<name>

package/src/commands/branches.mjs

@@ -0,0 +1,297 @@
+/**
+ * `tot branches` — the full branch-cleanup REPORT for one tenant's repo (per
+ * 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 (the `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) {
+  /** @type {{ tenant: string|null, repo: string|null, staleAfterDays: number|null, mcp: string|null, identity: string|null, json: boolean, help: boolean }} */
+  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,264 @@
+/**
+ * `tot cleanup` — owner-confirmed branch GC, per the
+ * branch-lifecycle-and-integration-preview contract's "Current gaps".
+ *
+ * `tot cleanup --dry-run` runs the SAME fresh server-side classification
+ * `tot branches` shows (the `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.
+ *
+ * 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. Reject closes the PR and
+  removes its hosted candidate artifact; cleanup deletes the terminal git ref.
+
+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) {
+  /** @type {{ tenant: string|null, repo: string|null, staleAfterDays: number|null, ref: string|null, dryRun: boolean, yes: boolean, mcp: string|null, identity: string|null, help: boolean }} */
+  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: /** @type {string} */ (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;
+  }
+}