# API — Open Items

Only keep unfinished API-owned work here.

## Launch / validation active
- Normalize backup response shape: define canonical success bodies for list/create/restore/delete and a stable error envelope that preserves agent details.
- Live-validate billing backup mutation gates against a game backup fixture with backups available.
- Live-validate file read/list behavior against a responsive Agent while billing state is suspended/retained; policy should allow read/list/download and block mutations.
- Verify canonical and compatibility file routes still behave identically across list/stat/read/download/delete/put/revert/upload paths after helper extraction.
- Align merged live-status readiness fields so Portal-facing `agentReady` semantics fully match semantic `/ready`.
- Live-verify Velocity bridge lifecycle callbacks after `ZPACK_PROXY_STATUS_ENDPOINT` is set: confirm `registered_with_proxy`, `proxy_ping_ok`, and `proxy_ping_failed` land in `ContainerInstance.payload.proxy` and surface through `GET /api/servers/:id/status`.
- Verify Proxmox node resolution against all active container ranges; recent local smoke checks showed some DB VMIDs not present in `/cluster/resources` or on the configured node.
- Add queue staleness visibility/alerts for `provisioning`, `repair`, and `billing_enforcement` if not already covered by monitoring/controller logs.
- Remove or downgrade the temporary `MaxListenersExceededWarning` tracer in `src/app.js` after outbound Axios socket listener warnings are confirmed quiet in runtime logs.

## Launch architecture follow-ups
- Controller should remain conservative; Level 2 repairs such as agent/workload restart stay disabled until separately validated.
- Decide when to move controller from dry-run to default Level 1 auto-repair after observing noise and repair recommendations.
- Keep billing worker scoped to billing enforcement only; do not add new worker/systemd services before launch without a strong safety-boundary reason.
- Support ticket post-launch enhancements belong outside launch blocker scope: admin ticket list/view, support triage diagnostics, self-hosted helpdesk integration, inbound reply parsing, attachments.

## Cleanup / consolidation priorities
- Fold repeated ownership/auth/IP-guard patterns into small concrete helpers without hiding route intent.
- Split oversized route/service files by responsibility without changing route contracts.
- Keep backup/restore status shaping and async-dispatch logic explicit, but remove duplicated mapping/normalization paths where possible.
- Keep stream-vs-JSON forwarding rules centralized in one place and avoid route-local reimplementation.
- Keep legacy flows out of the live tree unless they are intentionally revived and revalidated against the current schema/contracts.

## Completed and moved out of active cleanup
- Node/runtime pinning is current repo state.
- `node-fetch` removal and built-in `fetch` migration are complete.
- Initial file-proxy route deduplication is complete; only compatibility verification remains open.
- Prisma config migration is complete.
- Baseline proxy cookie/log hardening is complete.
- Initial control-plane hardening is complete.
- Teardown workflow has been extracted into a service and live-verified.
- Repo hygiene pass removed checked-in key/token/artifact/legacy clutter and tightened ignore rules.
- Async provisioning worker is implemented, systemd-backed, and live-validated for game and dev creates.
- Provisioning idempotency/no-key guard and controlled failure handling have been validated.
- Controller/reconciler foundation, repair queue, Discord notifications, stale-operation repair, and live edge drift repair have been implemented and validated.
- Billing enforcement backend, Stripe idempotency, API gates, billing worker, and controller billing guards have been implemented and validated.
- Support ticket route, DB ticket creation, customer acknowledgement email, and Discord support alert have been implemented and validated.

## Cleanup rule
- Prefer behavior-preserving folding over broad refactors.
- Merge repeated flows, not concepts.
- Keep helpers small and concrete.
- Reduce route-local duplication before introducing new abstractions.
- Treat security/runtime changes as contract-sensitive validation work once they affect auth, cookies, or route compatibility.

## Verify before re-opening
- hosted IDE token + hosted URL flow
- backup forwarding semantics
- readiness polling/cache behavior
- quota enforcement on create flow
- restore async-start contract + status polling semantics
- streamed file edit/revert forwarding through both canonical and compatibility routes
- older-session re-login behavior after JWT tightening

## Not API-owned
- agent-local backup implementation details
- portal-only UX/polish
- PBS / infra backup strategy