@flame0510/project-aether 1.2.0 → 1.4.0

package/app/globals.css

@@ -1296,6 +1296,14 @@ html, body { height: 100%; height: 100dvh; background: var(--bg); color: var(--t
   background: rgba(var(--red-rgb,239,68,68),0.1);
   color: var(--red);
 }
+/* Saved, but not fully applied — e.g. a change stored while an agent sync failed. */
+.msg-warning {
+  padding: 8px 12px;
+  border-radius: 0;
+  font-size: 12px;
+  background: rgba(245,158,11,0.1);
+  color: var(--yellow);
+}
 
 /* --- Mobile Bottom Navigation --- */
 .mobile-bottom-nav {

package/app/lib/models-context.tsx

@@ -1,6 +1,20 @@
 'use client';
 
-import { createContext, useContext, useEffect, useState } from 'react';
+/**
+ * The model list, fetched once and shared by every client that needs it.
+ *
+ * There used to be two independent copies: this provider, and a private fetch
+ * inside PulseChat. Both ran on mount with an empty dependency list, and neither
+ * component ever unmounts — so unchecking a model on the Gateway page left the
+ * chat panel offering it for the rest of the session, and only a full page reload
+ * cleared it.
+ *
+ * The fix is not to refetch more often. It is to refetch when the answer
+ * changes: `refresh()` is called by whoever changes it — the Gateway page after a
+ * model toggle, a key save or removal, and a sync; the first-run wizard after
+ * saving keys. Everything else just reads.
+ */
+import { createContext, useCallback, useContext, useEffect, useRef, useState } from 'react';
 
 interface ProviderEntry {
   provider: string;
@@ -11,26 +25,48 @@ interface ProviderEntry {
 interface ModelsContextValue {
   providers: ProviderEntry[];
   loaded: boolean;
+  /** Re-read the catalogue. Call after changing which models are enabled. */
+  refresh: () => void;
 }
 
-const ModelsContext = createContext<ModelsContextValue>({ providers: [], loaded: false });
+const ModelsContext = createContext<ModelsContextValue>({
+  providers: [],
+  loaded: false,
+  refresh: () => {},
+});
 
 export function ModelsProvider({ children }: { children: React.ReactNode }) {
   const [providers, setProviders] = useState<ProviderEntry[]>([]);
   const [loaded, setLoaded] = useState(false);
 
-  useEffect(() => {
+  // Refreshes can overlap — two quick toggles — and responses can arrive out of
+  // order. Only the most recent request may write.
+  const seq = useRef(0);
+
+  const refresh = useCallback(() => {
+    const mine = ++seq.current;
     fetch('/api/models')
-      .then((r) => r.json())
+      .then((r) => {
+        if (!r.ok) throw new Error(`HTTP ${r.status}`);
+        return r.json();
+      })
       .then((data) => {
-        if (Array.isArray(data) && data.length) setProviders(data);
+        if (mine !== seq.current) return;
+        // An empty array is a real answer — every model disabled, or no provider
+        // key — so it must replace the list rather than be discarded as a failure.
+        if (Array.isArray(data)) setProviders(data);
         setLoaded(true);
       })
-      .catch(() => setLoaded(true)); // fallback silenzioso
+      .catch(() => {
+        // Keep the previous list: a failed refresh is not an empty catalogue.
+        if (mine === seq.current) setLoaded(true);
+      });
   }, []);
 
+  useEffect(() => { refresh(); }, [refresh]);
+
   return (
-    <ModelsContext.Provider value={{ providers, loaded }}>
+    <ModelsContext.Provider value={{ providers, loaded, refresh }}>
       {children}
     </ModelsContext.Provider>
   );

package/app/wizard/useWizard.ts

@@ -1,6 +1,7 @@
 'use client';
 
 import { useState, useCallback, useEffect } from 'react';
+import { useModels } from '../lib/models-context';
 import {
   isWizardComplete,
   markWizardComplete,
@@ -45,6 +46,9 @@ export function useWizard() {
     // Step tracking is in-memory only; the cookie is the source of truth
   }, []);
 
+  // Saving a key changes which models are offered; the shared list must follow.
+  const { refresh: refreshOfferedModels } = useModels();
+
   const saveProviders = useCallback(async () => {
     const entries = Object.entries(providerKeys).filter(([, v]) => v.trim());
     if (entries.length === 0) {
@@ -60,10 +64,11 @@ export function useWizard() {
           body: JSON.stringify({ provider, apiKey: apiKey.trim() }),
         });
       }
+      refreshOfferedModels();
       markStep('providers');
     } catch { /* API call failed — do not mark step as complete */ }
     setSaving(false);
-  }, [providerKeys, markStep]);
+  }, [providerKeys, markStep, refreshOfferedModels]);
 
   const goNext = useCallback(async () => {
     if (step === 'welcome') { markStep('welcome'); setStep('providers'); }

package/bin/rev4a.js

@@ -10,7 +10,7 @@
  * rev4a serve:
  *   1. Ensures .env exists (auto-generates on first run)
  *   2. Ensures .next build exists (builds if missing)
- *   3. Ensures Docker is installed (installs if missing + root)
+ *   3. Ensures Docker is installed (installs if missing + root) and waits for its daemon
  *   4. Ensures agent base image is built (builds if missing)
  *   5. Starts Next.js + daemon + terminal WS as a single process group
  *
@@ -41,9 +41,20 @@ const DATA_DIR = join(CONFIG_DIR, 'data');
 const ENV_SOURCE = join(CONFIG_DIR, '.env');
 const ENV_LINK = join(ROOT, '.env');
 const DOCKERFILE = join(ROOT, 'agent-templates', 'base-image', 'Dockerfile');
-const AGENT_IMAGE = 'openclaw-agent-base:latest';
-const AGENT_IMAGE_REGISTRY = 'ghcr.io/flame0510/rev4a/openclaw-agent-base:latest';
+// Supported OpenClaw versions and image repositories, shared with the server.
+const AGENT_VERSIONS = require(join(ROOT, 'lib', 'agent-versions.json'));
 const DOCKER_NETWORK = 'rev4a-network';
+// How long `serve` waits for the Docker daemon before starting without it. Like
+// REV4A_DATA_DIR it is read from the real process environment (a systemd
+// Environment= line, a shell export), because the .env file is loaded later.
+const DOCKER_WAIT_SECONDS = (() => {
+  const raw = (process.env.REV4A_DOCKER_WAIT_SECONDS || '').trim();
+  if (!raw) return 90;
+  const n = Number(raw);
+  // 0 means a single check. Non-numeric or infinite values fall back to the
+  // default, and the ceiling keeps a typo from holding start-up for hours.
+  return Number.isFinite(n) && n >= 0 ? Math.min(n, 600) : 90;
+})();
 
 // Fallback used only when package.json cannot be read — the published npm
 // package name is the single source of truth, so never hardcode it elsewhere.
@@ -97,25 +108,70 @@ function whichDistro() {
   }
 }
 
-// ── Docker auto-install ─────────────────────────────────────────────────────
+// ── Docker auto-install and daemon wait ─────────────────────────────────────
 
+/** Block this thread for `ms` without spawning a process (`sleep` is not on every OS). */
+function sleepSync(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+/**
+ * Wait until the Docker daemon answers, up to DOCKER_WAIT_SECONDS.
+ *
+ * Finding the `docker` command only proves the CLI is installed. At boot the
+ * daemon can still be starting — on the production host systemd started this
+ * service a second before Docker. Start-up still worked, by accident: the first
+ * `docker` call blocked on docker.socket until the daemon was up. With a daemon
+ * slower than a later call's 10 s timeout, the image check would have concluded
+ * the image was missing and tried to pull and rebuild it. Asking the daemon
+ * directly, with a short per-attempt timeout, makes the wait explicit, bounded
+ * and logged, whatever kind of Docker install this is.
+ */
+function waitForDockerDaemon() {
+  const deadline = Date.now() + DOCKER_WAIT_SECONDS * 1000;
+  let lastError = '';
+  let announced = false;
+  for (;;) {
+    try {
+      const version = execSync('docker info --format "{{.ServerVersion}}"', { stdio: 'pipe', timeout: 10_000 })
+        .toString().trim();
+      if (version) {
+        log('DOCKER', `Docker daemon ready (server ${version})`);
+        return true;
+      }
+    } catch (err) {
+      lastError = ((err.stderr && err.stderr.toString()) || err.message || '').trim().split('\n')[0];
+    }
+    if (Date.now() >= deadline) break;
+    if (!announced) {
+      log('DOCKER', `Waiting for the Docker daemon (up to ${DOCKER_WAIT_SECONDS}s)…`);
+      announced = true;
+    }
+    sleepSync(2000);
+  }
+  log('DOCKER', `⚠ Docker daemon not reachable after ${DOCKER_WAIT_SECONDS}s: ${lastError || 'no answer'}`);
+  log('DOCKER', '  Starting without it. Agents are unavailable and the startup sync reaches none; run Sync All Agents once Docker is up.');
+  return false;
+}
+
+/** True when the Docker daemon is reachable and the Docker-dependent steps can run. */
 function ensureDocker() {
   if (hasCmd('docker')) {
-    log('DOCKER', 'Docker is available');
-    return;
+    log('DOCKER', 'Docker CLI found');
+    return waitForDockerDaemon();
   }
 
   if (!isLinux()) {
     log('DOCKER', '⚠ Docker not found. Rev4a needs Docker to create agent containers.');
     log('DOCKER', '  Install Docker: https://docs.docker.com/get-docker/');
     log('DOCKER', '  Then run: rev4a serve');
-    return;
+    return false;
   }
 
   if (!isRoot()) {
     log('DOCKER', '⚠ Docker not found. Run Rev4a as root to auto-install:');
     log('DOCKER', '  sudo rev4a serve');
-    return;
+    return false;
   }
 
   const distro = whichDistro();
@@ -134,10 +190,12 @@ function ensureDocker() {
     );
 
     log('DOCKER', 'Docker installed successfully');
+    return waitForDockerDaemon();
   } catch (err) {
     log('DOCKER', '⚠ Docker auto-install failed. Install manually:');
     log('DOCKER', '  https://docs.docker.com/engine/install/');
     log('DOCKER', '  Then run: rev4a serve');
+    return false;
   }
 }
 
@@ -146,55 +204,57 @@ function ensureDocker() {
 function ensureAgentImage() {
   if (!hasCmd('docker')) return; // Docker not available — skip, warn later
 
-  // Check if image already exists locally
+  // The newest OpenClaw version this release supports, kept under its version tag.
+  // `:latest` is never used: an agent's version decides its data schema.
+  const version = AGENT_VERSIONS.supported[0].version;
+  const localRef = `${AGENT_VERSIONS.localRepository}:${version}`;
+  const registry = (process.env.REV4A_AGENT_IMAGE_REGISTRY || '').trim() || AGENT_VERSIONS.registryRepository;
+  const remoteRef = `${registry}:${version}`;
+
   try {
-    const r = execSync(
-      `docker image inspect ${AGENT_IMAGE} --format '{{.Id}}'`,
-      { stdio: 'pipe', timeout: 10_000 },
-    );
+    const r = execSync(`docker image inspect ${localRef} --format '{{.Id}}'`, { stdio: 'pipe', timeout: 10_000 });
     if (r.toString().trim()) {
-      log('IMAGE', `Agent base image ${AGENT_IMAGE} already exists`);
+      log('IMAGE', `Agent base image ${localRef} already exists`);
       return;
     }
   } catch {
-    // Image doesn't exist locally
+    // Not downloaded yet
   }
 
-  log('IMAGE', `Pulling agent base image from ${AGENT_IMAGE_REGISTRY}…`);
-
+  log('IMAGE', `Pulling agent base image ${remoteRef}…`);
   try {
-    execSync(`docker pull ${AGENT_IMAGE_REGISTRY}`, {
-      stdio: 'inherit',
-      timeout: 300_000, // 5 min timeout
-    });
-    // Tag locally for Rev4a internal use
-    execSync(`docker tag ${AGENT_IMAGE_REGISTRY} ${AGENT_IMAGE}`, {
-      stdio: 'inherit',
-      timeout: 10_000,
-    });
-    log('IMAGE', `Agent base image pulled and tagged as ${AGENT_IMAGE}`);
+    execSync(`docker pull ${remoteRef}`, { stdio: 'inherit', timeout: 1_800_000 });
+    execSync(`docker tag ${remoteRef} ${localRef}`, { stdio: 'inherit', timeout: 10_000 });
+    try {
+      execSync(`docker rmi ${remoteRef}`, { stdio: 'pipe', timeout: 30_000 }); // untag; the layers stay
+    } catch { /* keeping the registry reference is harmless */ }
+    log('IMAGE', `Agent base image pulled and tagged as ${localRef}`);
+    return;
   } catch {
-    log('IMAGE', `⚠ Pull from registry failed — attempting local build as fallback…`);
-
-    if (!existsSync(DOCKERFILE)) {
-      log('IMAGE', `⚠ Agent base image Dockerfile not found at ${DOCKERFILE}`);
-      log('IMAGE', '  Agent creation will be unavailable until the image is available.');
-      return;
-    }
+    log('IMAGE', '⚠ Pull from registry failed');
+  }
 
-    log('IMAGE', `Building agent base image ${AGENT_IMAGE} (this will take a few minutes)…`);
-    log('IMAGE', '  → pulling node:24-bookworm-slim + installing OpenClaw + tooling');
+  // A local build is only the same image when this Dockerfile builds that version.
+  const dockerfileVersion = existsSync(DOCKERFILE)
+    ? (/^ARG OPENCLAW_VERSION=(\S+)/m.exec(readFileSync(DOCKERFILE, 'utf-8')) || [])[1] || null
+    : null;
+  if (dockerfileVersion !== version) {
+    log('IMAGE', `  The Dockerfile here builds ${dockerfileVersion || 'no version'}, not ${version}: no local build.`);
+    log('IMAGE', '  Agent creation will be unavailable until the image is downloaded from the Agents page.');
+    return;
+  }
 
-    try {
-      execSync(`docker build -t ${AGENT_IMAGE} -f "${DOCKERFILE}" "${join(DOCKERFILE, '..')}"`, {
-        stdio: 'inherit',
-        timeout: 600_000, // 10 min timeout
-      });
-      log('IMAGE', `Agent base image built successfully`);
-    } catch {
-      log('IMAGE', '⚠ Agent base image build failed. Agent creation will be unavailable.');
-      log('IMAGE', '  Pull the image manually: docker pull ' + AGENT_IMAGE_REGISTRY);
-    }
+  log('IMAGE', `Building agent base image ${localRef} (this will take a few minutes)…`);
+  log('IMAGE', '  → pulling node:24-bookworm-slim + installing OpenClaw + tooling');
+  try {
+    execSync(
+      `docker build --build-arg OPENCLAW_VERSION=${version} -t ${localRef} -f "${DOCKERFILE}" "${join(DOCKERFILE, '..')}"`,
+      { stdio: 'inherit', timeout: 3_600_000 },
+    );
+    log('IMAGE', 'Agent base image built successfully');
+  } catch {
+    log('IMAGE', '⚠ Agent base image build failed. Agent creation will be unavailable.');
+    log('IMAGE', `  Pull it manually: docker pull ${remoteRef} && docker tag ${remoteRef} ${localRef}`);
   }
 }
 
@@ -414,9 +474,15 @@ function checkVersion() {
 function preflight() {
   log('PREFLIGHT', 'Running pre-flight checks…');
   ensureEnv();
-  ensureDocker();
-  ensureNetwork();
-  ensureAgentImage();
+  // Network and image need the daemon. Without it the image check fails and
+  // would start a pull and then a local build — up to fifteen minutes, before the
+  // dashboard is even up — for an image that is most likely already there.
+  if (ensureDocker()) {
+    ensureNetwork();
+    ensureAgentImage();
+  } else {
+    log('PREFLIGHT', 'Skipping network and agent image checks: Docker daemon not reachable.');
+  }
   ensureRev4aRules();
 
   if (!existsSync(NEXT_DIR)) {
@@ -575,7 +641,7 @@ EXAMPLES:
 On first run, rev4a serve automatically:
   • Generates .env (JWT secret + API token)
   • Installs Docker if missing (requires root)
-  • Builds the agent base image (openclaw-agent-base:latest)
+  • Downloads the agent base image for the newest supported OpenClaw version
   • Builds the Next.js app if no build is found
   • Starts Next.js, daemon, and terminal WebSocket as a single process group
   • Cleanly stops all services on Ctrl+C / SIGTERM

package/daemon.js

@@ -668,12 +668,12 @@ function pollSessions() {
   // ── Timeout Detection ────────────────────────────────────────────────────
   // Find sub-agents that were 'working' in the last snapshot but are no longer
   // present in the current output and have been missing for more than 10 minutes.
-  // Questi vengono marcati come 'timeout' nella tabella events.
-  const TIMEOUT_THRESHOLD_MS = 10 * 60 * 1000; // 10 minuti
+  // These are recorded as 'timeout' in the events table.
+  const TIMEOUT_THRESHOLD_MS = 10 * 60 * 1000; // 10 minutes
   for (const [session_id, snap] of knownSessions) {
     // Only sub-agents (contain 'subagent' in the key)
     if (!session_id.includes('subagent')) continue;
-    // Solo se erano working nell'ultimo poll
+    // Only if they were working in the last poll
     if (snap.status !== 'working') continue;
     // Only if not present in the current poll
     if (currentIds.has(session_id)) continue;
@@ -694,10 +694,10 @@ function pollSessions() {
       data: JSON.stringify({
         missing_for_ms: missingFor,
         last_status: snap.status,
-        message: `Subagente missing dopo ${Math.round(missingFor / 60000)}min senza completare`,
+        message: `Subagent missing for ${Math.round(missingFor / 60000)} min without completing`,
       }),
     });
-    log(`[TIMEOUT] ${session_id} missing da ${Math.round(missingFor / 60000)}min`);
+    log(`[TIMEOUT] ${session_id} missing for ${Math.round(missingFor / 60000)} min`);
 
     // Notify Michele via openclaw message (only if openclaw is available)
     try {
@@ -708,7 +708,7 @@ function pollSessions() {
         'message', 'send',
         '--account', 'ops',
         '--target', '297086793',
-        '--text', `⚠️ Rev4a: agent timeout\n\`${session_id.slice(-36)}\`\nMissing for ${Math.round(missingFor / 60000)} min senza completare.`,
+        '--text', `⚠️ Rev4a: agent timeout\n\`${session_id.slice(-36)}\`\nMissing for ${Math.round(missingFor / 60000)} min without completing.`,
       ], { encoding: 'utf8', timeout: 10_000, killSignal: 'SIGKILL' });
     } catch (e) {
       log(`[TIMEOUT] Telegram notification failed: ${e.message}`);

package/docs/ARCHITECTURE.md

@@ -1,7 +1,7 @@
 # Rev4a Architecture — Design & Vision
 
 > **Status:** Active — `main` branch
-> **Last updated:** 2026-08-28
+> **Last updated:** 2026-09-15
 > **Goal:** Transform Rev4a from a monitoring dashboard into a central orchestrator for a distributed multi-container agency.
 
 ---
@@ -119,6 +119,100 @@ The central container, running the Next.js dashboard + orchestration API.
 - Injected into every session via the `bootstrap-extra-files` hook (glob `.rev4a/*.md`)
 - Immutable by agents — enforced by the `:ro` mount
 - See `lib/agent-setup.ts` for the centralized volume + config guarantee logic
+- **Waiting for a new container** is `waitForGatewayReady()` in
+  `lib/agent-readiness.ts`, used by create, recreate and the agent route. On
+  OpenClaw 9.x it waits for `/startupz` to report `started` (503 while starting).
+  The 2026.7.1-2 image has no `/startupz` — its gateway serves the web UI with 200
+  for unknown paths — so there it falls back to `/health`, which only shows the
+  server is listening. Do not reimplement the wait in a route.
+- **The model catalogue** is read only through `lib/model-catalogue.ts`:
+  `loadModelsConfig()`, `loadOfferedModels()` (enabled after overrides, provider has
+  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** are shared between creation and the edit flow by `lib/agent-ports.ts`
+  (pure: `validatePortInput`, `findAvailablePortBlock`, `portMappingArgs`) and
+  `lib/agent-ports-server.ts` (`getUsedHostPorts()`, the Docker lookup, server-only since
+  client components cannot import `child_process`). One block maps to the container's
+  gateway port 3000 (`3700-3709` → `3700-3709:3000-3009`); both flows produce the same
+  validation messages, and the edit excludes the agent's own ports so its block never
+  conflicts with itself.
+- **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`):
 
@@ -136,7 +230,9 @@ the rules for anything you touch, not as a description of the whole tree:
   computed for other containers are discarded. Fanning out over a fleet requires
   the `…NoFail` variants, or an explicit per-item try/catch, so one unreachable
   container cannot blank an entire page. Callers: `app/api/skills/route.js`,
-  `app/api/gateway/route.ts`, `app/api/agents/channels-summary/route.ts`,
+  `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`
@@ -183,7 +279,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:**
 ```
@@ -207,7 +305,7 @@ Agent Container          Rev4a Gateway              Provider API
      │                         │                         │
      │ Authorization: Bearer <gateway-token>             │
      │ POST /api/provider/v1/chat/completions            │
-     │ model: rev4a/deepseek-v4-flash                  │
+     │ model: rev4a/deepseek-flash                     │
      │────────────────────────>│                         │
      │                         │ POST /v1/chat/completions│
      │                         │ Authorization: Bearer <real-key>
@@ -325,7 +423,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)
 ```
 
@@ -410,7 +508,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
 
 ---
 
@@ -526,7 +624,7 @@ ALTER TABLE sessions ADD COLUMN ended_at INTEGER;
 ### Phase 2 — Provider Gateway
 - [x] Implement proxy API on Rev4a (`/api/provider/v1/`)
 - [x] Gateway Page (`/gateway`) for provider key management
-- [x] Agent model configuration via Gateway Agents tab
+- [x] Agent model configuration in the agent detail panel
 - [x] Provider sync to agent containers (`PUT /api/gateway/provider`)
 - [x] Auth via rev4a token in `data/provider-keys.json`
 - [ ] Rate limiting per agent
@@ -561,10 +659,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
@@ -616,6 +714,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` |