@flame0510/project-aether 1.3.0 → 1.4.1

package/docs/ARCHITECTURE.md

@@ -1,7 +1,7 @@
 # Rev4a Architecture — Design & Vision
 
 > **Status:** Active — `main` branch
-> **Last updated:** 2026-09-14
+> **Last updated:** 2026-09-15
 > **Goal:** Transform Rev4a from a monitoring dashboard into a central orchestrator for a distributed multi-container agency.
 
 ---
@@ -130,6 +130,101 @@ The central container, running the Next.js dashboard + orchestration API.
   a key), `isModelOffered()` (enforced by the proxy and the assistant) and
   `catalogueStatus()`. A failed read of `models.config.json` falls back to the last
   good copy and never deletes overrides.
+- **Agent images and OpenClaw versions.** `lib/agent-versions.json` lists the supported
+  OpenClaw versions, newest first, with the model `input` list for each; the server reads
+  it through `lib/agent-versions.ts`, the `rev4a` CLI with `require`. The provider sync
+  takes each agent's own list (`containerVersionSync()`: image tag, else the entrypoint's
+  `.last-version` file), so a 2026.7.x agent is never sent an `input` value it would
+  reject — one unknown value discards the whole generated catalogue. The previous
+  versions stay listed while agents still run them: that is also what lets a rollback
+  pull the previous image. `lib/agent-images.ts`
+  lists local `openclaw-agent-base:<version>` images through the Docker API, reads an
+  agent's version (image label or tag, else `openclaw --version` in the container, cached
+  per image id), reads the registry tag list over HTTP (cached 10 min), pulls a version
+  and resolves the image a recreate uses. Images are never addressed as `:latest`: create
+  takes the newest supported version downloaded, recreate the agent's own.
+- **Cold backups** are `lib/cold-backup.ts`. The agent is stopped and a detached helper
+  container, `rev4a-backup-<id>` from the agent's own image, archives its volume to
+  `rev4a-backups` as `.partial`, reads it back and renames it; the agent is started
+  again if it was running. The helper and its labels are the job, so no request waits
+  on it and a Rev4a restart does not lose it (`reconcileColdBackups()` in
+  `instrumentation.ts`). While a helper runs, the routes that change the agent answer
+  409 (`isColdBackupRunning()`), and `syncAllAgents()` skips the agent.
+- **Agent updates** are `lib/agent-update.ts`, with their state in the `agent_upgrades`
+  table (`lib/agent-update-state.ts`). An update counts the agent's transcript events per
+  session and its cron jobs, takes a cold pre-update backup, recreates the container on
+  the newer version (`lib/agent-recreate.ts`, argv only, env values outside the process
+  table), waits for `/startupz` to report that version, re-applies Rev4a's config and
+  checks the counts. A rollback restores the pre-update backup on the previous version.
+  Both run inside the Rev4a process; `markInterruptedUpdates()` at startup turns an
+  unfinished one into `interrupted`. `lib/agent-busy.ts` gives the routes one 409 reason
+  for "edit, update, recreate, restore or backup running". After a successful update, `pruneAgentImages()`
+  keeps only images in use plus the newest and previous versions.
+- **Agent recreates** are `lib/agent-recreate.ts`, with their state in the
+  `agent_recreates` table (`lib/agent-recreate-state.ts`): the same-version counterpart
+  of an update. A cold backup, then the container rebuilt on the image the agent already
+  runs, then `/startupz`, then the runtime config. It answers `202` and runs in the
+  background, so a page reload or a Rev4a restart does not lose it; at startup a job
+  still active becomes `interrupted` and the agent is started again — after its backup
+  helper has finished, never while the archive is written. On success the older
+  `prerecreate` archives are pruned to the newest two. The same `recreateAgentContainer()`
+  serves the edit route (`PATCH` → 202, no backup) and the Update action.
+  `agentBusyReason()` (`lib/agent-busy.ts`) covers it for every route that changes an agent.
+- **Host ports** have one source of truth: `lib/agent-ports.ts` holds the pure rules
+  (`validatePortInput`, `findAvailablePortBlock`, `portMappingArgs`,
+  `hostPortsFromBindings`, `hostPortsFromArgs`) and `lib/agent-ports-server.ts` answers
+  which ports are taken (`getHostPortHolders()`, `getUsedHostPorts()`; server-only, it
+  talks to the Docker socket). Creation, the create form, the edit flow and every
+  container rebuild (update, recreate, rollback) read their numbers from there. One block
+  maps to the container's gateway port 3000 (`3700-3709` → `3700-3709:3000-3009`); all
+  flows produce the same validation messages, and a flow rebuilding a container excludes
+  that container's own ports, so its block never conflicts with itself.
+  **A stopped container still holds its block**, but neither `docker ps -a --format
+  '{{.Ports}}'` nor the Docker API's container list reports its ports (verified on Docker
+  29: both return nothing). The lookup therefore reads each container's
+  `HostConfig.PortBindings` — the only source covering the stopped ones. Without that, a
+  new agent could be handed the block of a stopped agent, and the clash only surfaced
+  later, when that agent was started again (`Bind for 0.0.0.0:3730 failed: port is
+  already allocated`), after the container it was replacing had been removed.
+  `recreateAgentContainer()` refuses such a clash **before** removing anything, naming the
+  container that holds each port, so the agent stays up and the operator changes the range
+  from the Edit panel; a failed `docker run` no longer leaves a container behind.
+- **Agent edits** are `lib/agent-edit.ts`, with their state in the `agent_edits` table
+  (`lib/agent-edit-state.ts`): the display name (`AGENT_NAME`) and/or the port range are
+  applied by rebuilding the container on the image it already runs — **no backup**, the
+  volume is never touched. Same 202-and-background shape as a restore; the parameters
+  live in the row, so recovery can tell what was being applied. The panel shows a banner
+  and the agent card an `EDITING` chip.
+- **Agent restores** are `lib/agent-restore.ts`, with their state in the `agent_restores`
+  table (`lib/agent-restore-state.ts`): the archive replaces the volume (stop, clear,
+  extract, start), up to 30 minutes. Same 202-and-background shape as a recreate, and the
+  same guarantees — a reload or a Rev4a restart does not lose the job, a second restore
+  is refused, an interrupted one starts the container again. The extract has no
+  percentage (it is a single `tar xzf`); the panel and the agent card show `RESTORING`.
+- **Browser access** to an agent's Control UI goes through `lib/agent-devices.ts`:
+  `openclaw devices list | approve | reject | rename | remove` and
+  `openclaw dashboard --json`, run inside the container with the async `dockerExec`.
+  The gateway token is resolved inside the container (`/root/.agent-token`, then its
+  environment), never passed in argv. Whether approval applies is decided by the
+  OpenClaw version: 9.x answers `/startupz` with JSON and always requires it;
+  2026.7.x follows `gateway.controlUi.dangerouslyDisableDeviceAuth`.
+  `buildInviteLink()` builds the plain token link for someone else; the invite route
+   refuses agents without approval. Every link's token is read inside the container,
+   and its host is the request's `Host` header (`hostnameFromHostHeader()`), never a
+   caller-supplied value.
+- **Telegram DM pairing** lives in `lib/channelManager.ts`. The bot binding is config
+  (`channels.telegram.botToken`/`dmPolicy`); *who* may talk is OpenClaw's pairing
+  store — on 2026.9.3 the SQLite rows in `~/.openclaw/state/openclaw.sqlite`, not the
+  `credentials/*.json` files older releases used. Reading and revoking go through the
+  store's own functions (`readChannelAllowFromStoreSync`,
+  `removeChannelAllowFromStoreEntry`): no CLI, RPC or documented export exposes them,
+  so a small script run inside the container finds OpenClaw's `pairing-store` module by
+  glob and its functions by name (the names survive minification; no hash or minified
+  symbol is hardcoded) and calls them, which uses the same state transaction the CLI
+  does. If a release stops exposing the store, the revoke fails with a message pointing
+  at `/allowlist remove` — it never reports success without changing anything. Approving
+  a pairing request (`openclaw pairing approve`) also bootstraps
+  `commands.ownerAllowFrom` for the first owner (OpenClaw's own behaviour).
 
 **Running commands inside containers** (`lib/docker-exec.ts`):
 
@@ -149,6 +244,7 @@ the rules for anything you touch, not as a description of the whole tree:
   container cannot blank an entire page. Callers: `app/api/skills/route.js`,
   `app/api/agents/models-summary/route.ts`,
   `app/api/agents/channels-summary/route.ts`,
+  `app/api/agents/devices-summary/route.ts`,
   `lib/openclaw-cron.ts`, `app/api/credentials/detect/route.ts`,
   `lib/credentials/delivery.ts`.
 - **Never interpolate a secret into a command string.** Pass it through the `env`
@@ -195,7 +291,9 @@ agent-{name}-data (named vol)         → /root                             (rw,
 All shared volumes are defined centrally in `lib/agent-setup.ts`
 (`REV4A_VOLUMES`) and used by both the create and recreate API routes.
 The `bootstrap-extra-files` hook is pre-wired in the base image Dockerfile
-and guaranteed at runtime by `applyRuntimeConfig()`.
+and guaranteed at runtime by `applyRuntimeConfig()`, which also applies the Control
+UI browser-origin policy (`withControlUiPolicy()`): the Host-header fallback on, an
+`allowedOrigins: ["*"]` list and the retired `dangerouslyDisableDeviceAuth` removed.
 
 **Injected environment variables:**
 ```
@@ -337,7 +435,7 @@ Rev4a Dashboard UI
 POST   /api/agents/create          Create new container agent (template + model)
 DELETE /api/agents/{id}            Destructive: remove container + volume + backups
 POST   /api/agents/{id}/restart    Restart container
-POST   /api/agents/{id}/recreate   Rebuild from latest image (volume preserved)
+POST   /api/agents/{id}/recreate   Rebuild on the agent's own version (volume preserved)
 GET    /api/agents                 List all agents (Docker containers with AGENT_ID)
 ```
 
@@ -422,7 +520,7 @@ networks:
 - Agent → Rev4a Gateway: `http://rev4a-control:3721`
 - Agent → Rev4a Dashboard: `http://rev4a-control:3720`
 - Rev4a → Agent (healthcheck): `http://agent-{id}:3000`
-- Traefik → Agent (external access): via Docker labels
+- Browser → Agent Control UI: the container's published host port, `http://<host>:<port>`. Rev4a sets no reverse-proxy labels
 
 ---
 
@@ -573,10 +671,10 @@ ALTER TABLE sessions ADD COLUMN ended_at INTEGER;
    - Distributed: per-agent memory, Rev4a indexes centrally — more resilient
    - Recommendation: distributed with central index
 
-3. **Traefik routing: should agents be externally reachable?**
-   - If yes: per-agent Traefik labels managed by Rev4a
-   - If no: internal Docker network only
-   - Recommendation: no by default, yes only for agents serving APIs/UI
+3. **External access to agents** — decided: each agent's Control UI is published on a
+   host port, and Rev4a sets no reverse-proxy labels. HTTPS or a domain means the
+   operator's own proxy in front of that port. A first-class integration, with routing
+   labels applied at `docker run`, would be a separate feature.
 
 4. **Hermes and other frameworks: dashboard integration?**
    - Hermes has its own session format
@@ -628,6 +726,6 @@ for the full rationale.
 | Memory | Per-agent SQLite + central index | New |
 | Config | Generated YAML/JSON | New |
 | Credential stores | SQLite + JSON | credentials.db for service tokens, provider-keys.json for provider API keys. Neither is encrypted |
-| Reverse proxy | Traefik | Already in use |
+| Reverse proxy | Optional, operator's choice | Rev4a sets no reverse-proxy labels on agent containers |
 | Monitoring | Rev4a daemon (extended) | Evolution of current daemon |
 | Version control | Git + GitHub | `github.com/Flame0510/rev4a.git` |

package/docs/FRONTEND-ARCHITECTURE.md

@@ -1,6 +1,6 @@
 # Rev4a Frontend Architecture
 
-> **Last updated:** 2026-09-14
+> **Last updated:** 2026-09-15
 
 ## Layering
 
@@ -42,6 +42,13 @@ All shared UI primitives live in `app/components/ui/` and are exported from `app
 | `Page` / `PageHeader` | `Page.tsx` | Full-page layout shell. |
 | `Icons` | `Icons.tsx` | SVG icons (`EyeIcon`, `EyeOffIcon`), 16/20px shared. |
 | `PasswordInput` | `PasswordInput.tsx` | Password input with inline show/hide toggle (`<button type="button">` with `aria-label`). |
+| `UpdateSection` | `app/agents/UpdateSection.tsx` | OPENCLAW VERSION section of the agent detail panel: the version the agent runs, **Update to <version>** when a newer supported version is downloaded (confirm modal, disabled while the agent is stopped), the running update's steps with backup progress, the outcome, and **Roll back to <version>** after an update. Polls `/api/agents/[id]/update` every 2 s while an update or rollback runs; one action at a time (keyed busy state). |
+| `BackupSection` | inline in `app/agents/PageClient.tsx` | BACKUP section of the agent detail panel, on the cold backup and the restore. **Backup Now** starts `POST /api/agents/[id]/cold-backup`; while the job runs a banner shows the file and its live percent with **Cancel** (`DELETE /cold-backup`). **Restore** (after a confirm) starts `POST /restore` and a banner shows `Restoring <file>…` (no percent: the extract is a single `tar xzf`, and there is no Cancel). Both sections poll their `GET` every 2 s while running, and on mount pick up a job that is already running — a backup lives in a Docker helper, a restore in `agent_restores`, so reloading the page or navigating away never loses them nor allows a second one (the server answers 409 anyway). Delete per row; all actions disabled while one runs; keyed busy state `{ kind, file }` so only the row in action shows the spinner. On the agent list, an activity Badge (fed by `/api/agents/activity-summary`, polled at 2 s only while something runs, otherwise riding the 15 s list poll) reads `BACKUP nn%`, `RESTORING`, `RECREATING`, `EDITING` or `UPDATING`. |
+| `RecreateSection` | inline in `app/agents/PageClient.tsx` | RECREATE section of the agent detail panel. **Recreate Container** starts `POST /api/agents/[id]/recreate` (202) after a confirm; a banner then shows the phase — *Backing up … nn%* while the cold backup runs, *Recreating container…* while the container is rebuilt and the gateway starts. The section polls `GET /recreate` every 2 s, and on mount picks up a recreate that is already running, so a reload or navigation never loses it; it refetches the agent once the job reports `done`. |
+| `ImageDownloadBanner` | `app/agents/ImageDownloadBanner.tsx` | Agent image banner on the Agents page. Polls `/api/agents/image-status` every 2 s; offers **Download Image** when no supported version is downloaded, **Download <version>** when the registry publishes a newer one, and shows the download in progress and its completion. Downloading changes no agent. |
+| `BrowserAccessSection` / `OpenControlUiButton` | `app/agents/BrowserAccessSection.tsx` | Browser access to one agent's Control UI, in its detail panel: requests waiting for approval (Approve / Reject) and approved browsers (Rename / Revoke), refreshed every 5 s while mounted. A successful approve, reject, rename or revoke updates the list at once, since the refresh behind it runs the OpenClaw CLI and takes seconds; a read started before the mutation is discarded. On agents that require approval, "Invite link" fetches `/api/agents/[id]/invite-link` and shows the link in a read-only field with Copy, which uses the Clipboard API in a secure context and the field's selection over plain HTTP, plus a warning when the link uses localhost. `OpenControlUiButton` opens `/api/agents/[id]/open-control-ui` in a new tab inside the click; that route redirects to a one-time link that pairs the browser with no approval, or to the plain token link when none can be issued. Used on the agent cards and in the panel. |
+| `ChannelManager` / `ChannelSection` | `app/agents/ChannelManager.tsx`, `ChannelSection` inline in `app/agents/PageClient.tsx` | Telegram, in the agent detail panel (`ChannelSection` is the card that opens the modal; the modal title is the agent's display name). Reads `GET /channels`; lists pending pairing requests with **Approve** (`POST /channels/pairing`) and approved senders with **Revoke** after a confirm (`DELETE /channels/pairing?senderId=`). Pending comes from `openclaw pairing list`, approved from OpenClaw's pairing store (`lib/channelManager.ts`). Polls pairings every 5 s while open; one keyed busy state per action. |
+| `EditAgentModal` / `EditBanner` | `app/agents/PageClient.tsx` | Rename/ports editing. The modal has **Display Name** and **Host Port** (same input and validation messages as the create wizard, from `lib/agent-ports.ts`), sends `PATCH /api/agents/[id]` and closes on `202`; `EditBanner` (top of the agent detail) polls `GET /api/agents/[id]` every 2 s while an edit is `rebuilding`, resumes on mount, and refetches the agent once it finishes, so a reload or a navigation shows the running edit instead of allowing a second (the server answers 409). No backup is taken: the volume is untouched. |
 | `ModelSection` | `app/agents/ModelSection.tsx` | Primary model and fallbacks for one agent, in its detail panel. Explicit save, no restart. The model is a property of the agent, not of the gateway. Tags models the catalogue marks `deprecated`. |
 | `ModelsProvider` / `useModels` | `app/lib/models-context.tsx` | The client's single model list, from `/api/models`. Whatever changes what is offered calls `refresh()`: the Gateway page after a toggle, a key save or removal, or a sync, and the first-run wizard after saving keys. Everything else only reads, PulseChat included. |
 | `WizardPageClient` + step components | `app/wizard/PageClient.tsx` | Multi-step first-run wizard plus its frame shell, with mobile-first CSS. |

package/docs/REV4A.md

@@ -1,6 +1,6 @@
 # Rev4a — VPS Dashboard
 
-> **Last updated:** 2026-09-14
+> **Last updated:** 2026-09-15
 
 A Next.js 16 dashboard for monitoring and managing the OpenClaw ecosystem.
 
@@ -68,6 +68,7 @@ Rev4a reads the following environment variables. Set them in `/config` (UI) or d
 | `REV4A_ROOT` | No | Installation root, used by `rev4a update` to detect a git checkout |
 | `REV4A_TIMEZONE` | No | IANA timezone used for scheduling and timestamps |
 | `REV4A_FORCE_INSECURE_COOKIE` | No | Allow a non-Secure session cookie — plain-HTTP deployments only |
+| `REV4A_AGENT_IMAGE_REGISTRY` | No | Registry repository agent images are pulled from (default: `ghcr.io/flame0510/rev4a/openclaw-agent-base`); a `localhost` registry is reached over plain HTTP |
 
 See [Alerts](#alerts-telegram) below for the Telegram alert variables.
 
@@ -76,9 +77,9 @@ See [Alerts](#alerts-telegram) below for the Telegram alert variables.
 Every agent is created with:
 
 - A host port mapping (`-p <port>:3000`) for direct access
-- URL format: `http://<host-public-ip>:<port>#token=...`
+- Control UI at `http://<host>:<port>`, opened from the Agents page through `GET /api/agents/[id]/open-control-ui`
 - The provider gateway at `http://host.docker.internal:3740/api/provider/v1`
-- `allowedOrigins: ['*']` for browser Control UI access
+- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback: true`, so the Control UI opens on whatever host the agent is reached on, and pages from other origins are refused
 
 The port is auto-assigned starting from 3000 (or user-specified).
 
@@ -302,9 +303,10 @@ Lists all agents (Docker containers with `AGENT_ID` label), with:
 - Name, image, template, status, ports, IP
 - TG channel status chip (green = connected, hidden if not configured)
 - **Shared gateway token** — text input with Save & Sync. Changing the token saves it to `data/agents-token.json` and pushes it to all running containers.
-- **Control UI link** — direct Traefik URL with `#token=<token>` hash, reads the token from `agents-token.json` (source of truth), not from the container's local config.
+- **Control UI link** — the **Open** buttons go through `GET /api/agents/[id]/open-control-ui`, which redirects to the agent's published port on the host the dashboard was reached on: a one-time link on OpenClaw 9.x, the plain `#token=` link otherwise, with the token read inside the container.
 - **Agent creation wizard** — multi-step form at `/agents/create`.
-- **Channel Manager** — each agent detail panel has a Channels section with Telegram configuration and pairing management.
+- **Channel Manager** — each agent detail panel has a Channels section with Telegram configuration and pairing management. Pending requests (a sender's `/start` creates one) show an **Approve** button; approved senders show **Revoke** with a confirmation. Approved senders are OpenClaw's pairing store, not the agent config: on 2026.9.x the SQLite store, read and revoked through OpenClaw's own store functions (see [ARCHITECTURE.md](ARCHITECTURE.md)).
+- **Browser access** — the detail panel section right after Channels. From OpenClaw 9.x each new browser must be approved once before the Control UI connects: the section lists requests waiting for approval (Approve / Reject) and approved browsers (Rename / Revoke), and the agent card shows a "browser waiting" badge. The **Open** buttons first ask the agent for a one-time link that pairs the browser with no approval, and open the plain token link when none can be issued (every 2026.7.x agent). **Invite link** (9.x agents only) gives a link to send to someone else: their browser passes gateway auth and waits in the approval list until approved. The link carries the gateway token every agent shares; changing the agents token invalidates every link sent. All of it runs the OpenClaw CLI inside the container asynchronously.
 
 ### Agent Creation Wizard (`/agents/create`)
 
@@ -318,20 +320,20 @@ Available templates:
 
 **Step 2 — Config:** Enter agent name, optional port, select a primary model from the available providers (pre-filtered by configured provider keys). The first model is pre-selected.
 
-**Step 3 — Deploy:** `POST /api/agents/create` creates the Docker container and returns the Traefik URL with the shared gateway token.
+**Step 3 — Deploy:** `POST /api/agents/create` creates the Docker container and returns its port and the shared gateway token; the wizard links to `http://<host>:<port>#token=<token>`.
 
 **Post-creation pipeline:**
-1. The container boots with the **openclaw-agent-base:latest** image — see [Agent Templates](#agent-templates) below.
+1. The container boots with the newest supported OpenClaw version downloaded here, `openclaw-agent-base:<version>`; the create answers `409` when none is — see [Agent Templates](#agent-templates) below.
 2. OpenClaw gateway starts automatically with `--allow-unconfigured`, generating its own default config.
 3. The route waits for the gateway to finish starting with `waitForGatewayReady()`, up
    to 60 s. On OpenClaw 9.x it waits for `/startupz` to report `started`. The
    2026.7.1-2 image has no `/startupz`, so there it waits for `/health`, which only
    shows the server is listening.
 4. Once ready, the route writes:
-   - `gateway.controlUi.allowedOrigins` — Rev4a dashboard URL + Traefik hostname (required for browser Control UI access)
+   - `gateway.controlUi` with the browser-origin policy (`withControlUiPolicy()` in `lib/agent-setup.ts`): the Host-header fallback on, so the Control UI is accepted from the host the browser connected to — a public IP is refused without it — while pages from other origins are refused; an `allowedOrigins: ["*"]` list and the retired `dangerouslyDisableDeviceAuth` are dropped, any other allowlist is kept. Recreate re-applies the policy. Each new browser still needs a one-time device approval
    - `agents.defaults.model.primary` + fallbacks — the primary model selected in the wizard
 5. The route builds `models.providers.rev4a` with `buildRev4aProviderConfig()` and writes it with `openclaw config patch --stdin`.
-6. The agent's control UI is immediately accessible at `https://<name>.<your-domain>.com#token=<gateway-token>`.
+6. The agent's Control UI is reachable at `http://<host>:<port>#token=<gateway-token>`. For HTTPS or a domain, put your own reverse proxy in front of the published port: Rev4a sets no reverse-proxy labels on agent containers.
 
 ---
 
@@ -341,8 +343,9 @@ Each agent is created with a **persistent Docker volume** `agent-<name>-data`
 mounted at `/root`. This cleanly separates two planes:
 
 - **Software → image.** OpenClaw, `gh`, `vercel`, `supabase`, `trello`, Node — all
-  live in `openclaw-agent-base:latest` (outside `/root`). Updated by rebuilding the
-  image and recreating the container.
+  live in the agent image `openclaw-agent-base:<version>` (outside `/root`). A recreate
+  keeps the agent's OpenClaw version; moving an agent to a newer version is a separate
+  update.
 - **Data → volume.** Config (`openclaw.json`), state DB (`openclaw.sqlite`),
   workspace files, and CLI credentials (`.config/gh`, `.local/share/com.vercel.cli`,
   `.supabase`, …) live in `/root` and survive container removal.
@@ -354,9 +357,12 @@ a re-created agent keeps the workspace the user edited.
 
 | Action | What it does |
 |---|---|
-| **Backup** | `tar` of `/root` (excl. npm cache) → `.tar.gz` in the `rev4a-backups` volume |
+| **Backup** | `tar` of `/root` (excl. npm cache) → `.tar.gz` in the `rev4a-backups` volume, while the agent runs |
+| **Cold backup** | stop → archive `/root` (excl. npm cache) as `.partial` in a helper container → read the archive back → rename → start again if it was running. Other operations on the agent answer 409 meanwhile. Survives a Rev4a restart. API only for now (`/api/agents/[id]/cold-backup`) |
+| **Update** | the agent panel's OPENCLAW VERSION section, when a newer supported version is downloaded: count transcript events and cron jobs → cold pre-update backup → recreate on the new version (its data migrates one way) → wait for that version → check nothing went missing. Unused agent images are removed afterwards |
+| **Rollback** | after an update: stop → restore the pre-update backup → recreate on the previous version. Everything since the backup is lost |
 | **Restore** | stop → replace `/root` with the backup (real wipe incl. dotfiles) → restart. Software/image untouched — only data goes back in time |
-| **Recreate** | auto-backup first (aborts if it fails) → rebuild from `openclaw-agent-base:latest` keeping the volume → picks up image/OpenClaw/CLI updates |
+| **Recreate** | auto-backup first (aborts if it fails) → rebuild on the agent's own OpenClaw version (`openclaw-agent-base:<version>`, tagged or pulled when missing) keeping the volume. Never changes version |
 | **Restart** | `docker restart`, nothing else |
 | **Delete** | **destructive**: removes container **+ volume + all backups**. Cannot be undone |
 
@@ -368,19 +374,50 @@ agent means rebuilding the image + Recreate, never `update` inside the container
 
 ## Agent Templates
 
-### Base Image (`openclaw-agent-base:latest`)
+### Base Image (`openclaw-agent-base:<version>`)
 
 **Dockerfile:** `agent-templates/base-image/Dockerfile`
 
+**Versions.** Images are kept locally per OpenClaw version, `openclaw-agent-base:<version>`;
+`:latest` is not used. The versions this release supports, newest first, and the model
+`input` list for each, are in `lib/agent-versions.json`, read by the server and the
+`rev4a` CLI. The Agents page banner offers the newest supported version the registry
+publishes (`ghcr.io/flame0510/rev4a/openclaw-agent-base`, or `REV4A_AGENT_IMAGE_REGISTRY`);
+downloading touches no agent. Create uses the newest supported version downloaded; recreate
+keeps the agent's version. An agent card shows **UPDATE AVAILABLE** when a newer supported
+version is downloaded.
+
 Built from `node:24-bookworm-slim`, includes:
-- OpenClaw CLI + DeepSeek provider plugin
+- OpenClaw, pinned by the `OPENCLAW_VERSION` build argument and recorded as the
+  `org.opencontainers.image.version` label
+- `gh`, `vercel`, `trello`, `supabase`
+- Plugins under `/opt/openclaw-plugins`, outside the agent volume and pinned to the same
+  OpenClaw release: DuckDuckGo web search
 - `openssl` (for local token generation)
 - Custom entrypoint `/agent-entrypoint.sh`
 
+See also [agent-templates/README.md](../agent-templates/README.md).
+
 **Entrypoint behavior:**
 - Resolves the auth token (file > env > local random)
 - Does NOT generate `openclaw.json` — OpenClaw creates its own default config on first boot
-- **Version-gated migration:** if the OpenClaw version differs from the one recorded in `/root/.openclaw/.last-version` (i.e. the image was rebuilt to a newer OpenClaw), runs `openclaw doctor --non-interactive` **before** starting the gateway. This applies only safe migrations (config normalization + on-disk state moves), skips service restarts, and aligns the persistent volume's state/config to the new binary. Best-effort — never blocks boot. Runs at most once per version change, not on every restart.
+- **Version-gated migration:** if the OpenClaw version differs from the one recorded in
+  `/root/.openclaw/.last-version` (a newer image, or a new volume), runs
+  `openclaw doctor --fix --non-interactive` **before** starting the gateway. `--fix` is
+  required from OpenClaw 9.x: the agent database schema is migrated only with the gateway
+  stopped, and the gateway refuses the old schema rather than migrating it. The version is
+  recorded only after a successful run, so a failed migration is retried on the next boot.
+  A failure does not block boot.
+- **Image defaults**, before the gateway starts, written only where missing:
+  - the image's plugin directories in `plugins.load.paths`
+  - `tools.web.search.provider: "duckduckgo"` when no provider is set
+  - `agents.defaults.heartbeat.every: "0m"` when unset: every heartbeat tick is a
+    model-calling turn, so the recurring cadence is opt-in
+
+  An explicit value, such as a heartbeat turned on for one agent, is never overwritten.
+  The config is read with one node process and written through `openclaw config patch`,
+  which validates; if `openclaw.json` cannot be read as JSON, the defaults are skipped and
+  the log says so.
 - Starts OpenClaw gateway with `--allow-unconfigured`: `openclaw gateway --bind lan --port 3000 --auth token --token "<token>" --allow-unconfigured`
 - Everything else (controlUi, model refs, providers) is handled by the create route and the Gateway sync module
 
@@ -437,7 +474,7 @@ Only models whose provider has a key in `data/provider-keys.json` are synced.
 
 | Property | Value |
 |---|---|
-| Image | `openclaw-agent-base:latest` (Node 24-bookworm-slim + OpenClaw) |
+| Image | `openclaw-agent-base:<version>` (Node 24-bookworm-slim + OpenClaw) |
 | Port | `0.0.0.0:3731 → 3000` |
 | IP | `172.19.0.3` |
 | AGENT_ID | `atlas` |