RFC-0001 · P2 · cli — offboarding: `client delete` + `--uninstall` (R12; the k3d rebuild-orphan cure)

[saadqbal]

Context

There is no inverse of install. Nothing stops the heartbeat, de-registers the box, or clears local state — so every retired or rebuilt cluster becomes an orphan (RFC-0001 R12, and the R3 rebuild-orphan it feeds).

The sharp edge, hit in practice: the RFC anchors client identity on the kube-system namespace UID (§7.2 / backend#883). Tear down and recreate a cluster — k3d cluster delete tracebloc then re-create + re-run setup — and the fresh cluster gets a new kube-system UID. Re-provision therefore sees a different cluster, mints a duplicate client, and leaves the old one stranded: it stops heartbeating and lingers in the account forever with no way to remove it from the CLI. For a dev/test loop that rebuilds k3d constantly this manufactures an orphan on every cycle.

client delete doesn't exist yet — client.go wires only create / list / use. RFC-0001 §7.4 already specifies the delete semantics.

Recovery model (decided)

Honor the RFC: a rebuilt cluster = a new client. Re-attach is deliberately out of scope — §9 (RFC line 770) rejects a cluster_id change on an already-set client, and R3 states "rebuilt cluster = new client" is intended, with the reaper as the cure. So this ticket does not try to re-point an old client at a new cluster; it makes the orphan visible, cleanly removable, and non-silent.

Tasks

• client delete <id> (§7.4).
  • Confirms (the one justified interactive prompt — destructive; D1's "no prompts" is about setup, not destruction).
  • Refuses/warns if the client is online (recent heartbeat), holds datasets, or has a running experiment / training job; --force to override. (Heartbeat guard is advisory → gate on live job state too, so a delete mid-run doesn't silently lose work.)
  • Checks RBAC (write 403 → "ask an admin", reuse askAnAdmin).
  • Clears the stale active pointer afterward (§7.5) if it pointed at the deleted client.
• Delete must work when the cluster is already gone. The headline case (k3d cluster delete first) means there is no reachable cluster and no live Helm release to tear down. client delete / --uninstall must degrade gracefully: skip the Helm teardown, still de-register the backend EdgeDevice + clear local state. Don't require a reachable cluster to remove a zombie client.
• --uninstall (R12). When the cluster is reachable: tear down the local Helm release for the active client, de-register the EdgeDevice, clear the relevant ~/.tracebloc state. Coordinate with the installer's inverse (install-k8s.sh --uninstall).
• Warn on rebuild-mint (make the orphan non-silent). In client create, when about to mint because the cluster's UID doesn't match any client, but a same-name/same-derived-namespace client exists and is offline, surface it: "looks like a rebuilt cluster — client X is now orphaned; remove it with tracebloc client delete X." Today the orphan is created silently.

Related

• Parent flow: tracebloc/backend#880 (RFC-0001 · Uninstall / offboard — this is the CLI component of that flow).
• Reaper dependency: the automatic orphan sweep (R3) is backend — see the dedicated reaper ticket (links the "rebuilt = new client" cleanup end-to-end).
• RFC-0001 §7.4 (delete semantics), §7.5 (stale pointer), §9 line 770 (no cluster_id change), R12 & R3 (docs/rfcs/0001-cli-auth-and-client-provisioning.md)
• RFC-0001 · P1 · cli — §7.3 "selected is not connected": bind data commands to the active client + show connected state in client list #128 (§7.3 selected-vs-connected — surfaces the dead-heartbeat orphan in client list; this ticket removes it)
• cli: logout must call POST /auth/revoke to revoke the token server-side (RFC-0001 R2 / §7.5) #112 (logout→revoke, R2 — related but different action)

Part of tracebloc/backend#830.

[saadqbal]

Reaper dependency filed: tracebloc/backend#970 (orphaned-EdgeDevice reaper, R3) — the backend side that retires + credential-revokes the zombie clients this ticket makes removable from the CLI.

[LukasWodka]

Absorbed into the accepted §15 amendment (#139, A4): client delete owns the full inverse teardown (deprovision → helm uninstall → local cluster delete → clear pointer) — this ticket's scope, realized. The --uninstall binary-removal sliver gets re-cut against the post-amendment installer (the old draft PR #63 predates the tb alias and is closed as stale). Follow-ups already filed: #140 (e2e teardown verify), #141 (installer pre-flight vs hidden list). Board hygiene 2026-07-07 with Lukas.