docs(changes): record the break-glass backup console peer (§B4 Sync phase 2b)

# Break-glass "back up a world now" console peer (§B4 "Sync", phase 2b)

- **Type:** feature (addition)

- **Date:** 2026-07-07

- **Area:** `cmd/felis` (Go, oracle-verified); `internal/api` + `docs/openapi.yaml`

  (the internal endpoint's `os_user` accountability extension)

- **Commit:** `fc748d3`

- **Task:** #31 Phase B4 break-glass ops — the "Sync" operation. Per the user's

  **"两者都要"** decision the feature was built in two halves: the felis-api endpoint

  that does the real backup-Job orchestration (phase 1 `7a7c0d5` external face, phase

  2a `f2fc57c` internal face) and a break-glass menu peer that calls it while the API

  is alive. **This change is that peer — phase 2b — the last build step of "Sync".**

  (S3 remains open in B4; this does not close the phase.)

## What it does

Adds a **"Back up a world now (Sync)"** operation to the root-gated break-glass

console. The operator picks a server from the live fleet; the peer resolves the

`felis-api-internal` ClusterIP Service and the service token from the control

namespace, then POSTs the internal backup endpoint to snapshot that server's world

while felis-api is alive. It is the on-node counterpart to the halt op: an emergency

"snapshot this now" lever for when the panel is unreachable but the box still has

`root` + a kubeconfig and the API is running.

It also extends the internal backup endpoint (phase 2a) to accept an optional

`{"os_user":"..."}` body so the audit row names the operator at the keyboard rather

than the generic `break-glass`.

## Why

The console cannot render the backup Job itself — it lacks the deployment coordinates

(`FELIS_IMAGE`, `FELIS_BACKUP_PVC`) that only felis-api holds. So, unlike the halt peer

(which writes the `MinecraftServer` CRD directly), the backup peer must go **through**

the API. The internal face exists precisely so an on-node machine caller with the

service token — no browser session, no Cloudflare-Access Principal — can reach that

orchestration. This change is the client that knocks on that door.

## Design decisions

- **Goes through the API, does not orchestrate locally.** Mirrors the phase-2a

  rationale: deployment coordinates live only in felis-api. The peer's job is to

  resolve the endpoint, authenticate with the token, and translate the HTTP result

  into a friendly outcome card — not to build a Job.

- **ClusterIP resolution, not DNS.** `resolveInternalAPI` `Get`s the

  `platform.APIInternalServiceName` Service and dials its `Spec.ClusterIP:APIInternalPort`

  directly, erroring on an empty or `None` (headless) ClusterIP. The on-node console's

  host resolver is not CoreDNS, so the in-cluster Service DNS name would not resolve

  from the host; the ClusterIP is routable from the node and is what the `2ba9948`

  dedicated ClusterIP Service exists to provide.

- **`os_user` attribution, parity with halt.** The console sends the escalated OS user

  in the request body; the endpoint makes it the audit actor. The body is decoded

  whenever `ContentLength != 0` — **not** gated on `Content-Type` (`decodeJSON` checks

  only for unknown/trailing fields, not the header) — so a console that forgets the

  header still records the operator. Absent/blank falls back to `break-glass`. The

  console does **not** double-audit: the API audits at the boundary, single-sourced.

- **Stopped-gate stays server-side.** The world PVC is RWO, so the server must be

  stopped. The peer does not pre-check this; it lets the API's stopped-gate return

  `409 not_stopped` and renders that as a "must be stopped — halt it first" card. The

  safety check is single-sourced in the API, never duplicated (and possibly drifting)

  in the console.

- **A running pick ends the session with exit 1 — deliberately accepted.** The picker

  lists all servers (a running pick is easy to hit), and a `409` surfaces as an error

  through `backupResultMsg{err}` → root sets `m.err` → `breakglass.go` prints the

  friendly card to stderr and exits non-zero. A dedicated `not_stopped` non-error path

  was considered and **rejected**: every break-glass op ends the session anyway (all

  `tea.Quit`), so `409`-vs-success differs only in exit code — marginal for an

  interactive TUI. No error is swallowed; the friendly card is shown either way. Adding

  a soft-landing state machine for one status code is complexity the interactive

  surface does not earn.

- **Core/shell split, mirrors halt.** All decision logic (`resolveInternalAPI`,

  `requestBackup`, `backupErrorFromResponse`, `performBackupNow`) lives in `backupnow.go`

  and is unit-tested against a controller-runtime fake client + `httptest`.

  `tui_backupnow.go` is thin bubbletea/huh glue (untested by house convention, mirrors

  `tui_halt.go`). The picker **reuses** `listServersForHalt`/`haltableServer` rather

  than cloning a second server-listing path.

## Files

| File | Change |

|---|---|

| `cmd/felis/backupnow.go` | **new** — pure core: `resolveInternalAPI` (Service ClusterIP + token secret), `requestBackup` (POST + Bearer + `os_user` body, status→outcome), `backupErrorFromResponse` (409/503/404/error-body mapping), `performBackupNow` |

| `cmd/felis/backupnow_test.go` | **new** — table tests against a fake client + `httptest`: happy resolve, headless/empty-token errors; 202 asserts Bearer + `os_user` + path; 409/503/404 + transport-failure mapping |

| `cmd/felis/tui_backupnow.go` | **new** — bubbletea/huh shell mirroring `tui_halt.go`: load → pick → work → outcome card; empty-fleet guard; friendly error card |

| `cmd/felis/tui_menu.go` | `bgSyncBackup` enum + "Back up a world now (Sync)" menu option after the halt option |

| `cmd/felis/tui_root.go` | `bgSyncBackup` dispatch to `newBackupModel`; `backupResultMsg` terminal handling into `breakGlassResult` |

| `cmd/felis/breakglass.go` | `backedUp`/`backupServer`/`backupStatus` result fields; cancel guard; post-exit backup summary |

| `internal/api/handlers_backups.go` | `handleInternalBackup` decodes the optional `os_user` body (gated on `ContentLength`, not `Content-Type`) and passes it as the audit actor; defaults `break-glass` |

| `internal/api/handlers_backup_now_test.go` | **+subtest** in `TestInternalBackup`: `os_user` body attributes the audit to the operator |

| `docs/openapi.yaml` | document the `internalBackupNow` optional `os_user` request body |

## Verification

WSL oracle (go1.26.4, FedoraLinux-44, authoritative for Go):

```

go build ./...  &&  go vet ./...  &&  go test ./...   → ALL_GREEN

```

`cmd/felis` and `internal/api` both re-ran (not cached), so the new `backupnow_test.go`

and the added `TestInternalBackup` subtest executed. `TestOpenAPIMatchesServedRoutes`

still passes: the `os_user` body is an addition to an already-documented operation, so

the served⇔documented route match is unchanged. The core is covered against a real

`fake.Client` (resolves the Service/Secret) + `httptest.Server` (asserts the wire

request and maps every status), so the tests exercise persisted/observable behaviour,

not merely that a call was made. `tui_backupnow.go` is thin glue, untested per the

`tui_halt.go` convention.

## Self-review outcome

- **ponytail (over-engineering):** lean — no new abstraction beyond the four core

  functions two call sites (test + TUI) already justify; the picker reuses halt's

  server-list core rather than cloning it; the deliberate rejection of a `not_stopped`

  soft-landing path kept the state machine at four steps. Nothing cut.

- **correctness:** the `os_user` decode is gated on `ContentLength`, matching how

  `decodeJSON` actually works (no `Content-Type` check), so a header-less console still

  attributes correctly; the stopped-gate and audit stay single-sourced server-side, so

  the peer cannot drift from the endpoint on the RWO safety check or the audit record.

| 7a7c0d5 | 2026-07-07 | feat(api): add on-demand world backup endpoint and Job executor (§B4 Sync) |

| f2fc57c | 2026-07-07 | feat(api): add internal-face break-glass world backup endpoint (§B4 Sync) |

| 2ba9948 | 2026-07-07 | fix(platform): front the felis-api internal face on its own ClusterIP Service |

| fc748d3 | 2026-07-07 | feat(breakglass): add "back up a world now" console peer (§B4 Sync) |