@flame0510/project-aether 1.2.0 → 1.3.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
  *
@@ -44,6 +44,17 @@ 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';
 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;
   }
 }
 
@@ -414,9 +472,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)) {

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-14
 > **Goal:** Transform Rev4a from a monitoring dashboard into a central orchestrator for a distributed multi-container agency.
 
 ---
@@ -119,6 +119,17 @@ 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.
 
 **Running commands inside containers** (`lib/docker-exec.ts`):
 
@@ -136,7 +147,8 @@ 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`,
   `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`
@@ -207,7 +219,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>
@@ -526,7 +538,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

package/docs/FRONTEND-ARCHITECTURE.md

@@ -1,6 +1,6 @@
 # Rev4a Frontend Architecture
 
-> **Last updated:** 2026-08-28
+> **Last updated:** 2026-09-14
 
 ## Layering
 
@@ -24,7 +24,8 @@ All shared UI primitives live in `app/components/ui/` and are exported from `app
 |-----------|------|---------|
 | `Button` | `Button.tsx` | Action button, 5 variants (`primary`, `secondary`, `danger`, `ghost`, `success`), 2 sizes (`sm`, `md`), loading spinner. |
 | `Input` | `Input.tsx` | Text input with label, error state, placeholder. |
-| `Select` | `Select.tsx` | Native select with typed options, label, error state. |
+| `Select` | `Select.tsx` | Native select with typed options, label, error state. An option can be `disabled`, to display a current value that may not be chosen again. |
+| `RemoveButton` | `RemoveButton.tsx` | The `×` that removes an item from a list — one `danger` style everywhere. Whether the removal is immediate or pending goes in `title`, not in the colour. Not for dismissing dialogs — see rule 8. |
 | `Modal` | `Modal.tsx` | Overlay modal, Escape-to-close, maxWidth prop, `type="button"` on close. |
 | `Toast` | `Toast.tsx` | Lightweight toast notification with auto-dismiss (4s), `success` / `error` variants. |
 | `LoadingSpinner` | `LoadingSpinner.tsx` | Inline or fullscreen spinner. |
@@ -41,6 +42,8 @@ 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`). |
+| `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. |
 | `useWizard` | `app/wizard/useWizard.ts` | Shared hook: wizard state, step transitions, provider save, restart. Receives server-side initial state to avoid a loading flash. |
 | Wizard icons | `app/wizard/icons.tsx` | Shared SVG icons (flyweight pattern): `ArrowRightIcon`, `CheckIcon`, `CheckCircleIcon`, `DockerIcon`, `GatewayIcon`, `AgentIcon`, `TemplateIcon`, `LinkIcon`, `ConfigIcon`, `InformationIcon`. |
@@ -62,6 +65,25 @@ All shared UI primitives live in `app/components/ui/` and are exported from `app
 6c. **An optimistic update moves every field the render derives from, together.** A row that decides its state by reading two fields against each other flips to a third, wrong state if the update touches only one of them — and holds it until the slow refresh lands. Update the whole set the derivation reads, or none of it.
 7. **New UI component** — add it to `app/components/ui/`, export from `index.ts`, document it here. If it's specific to one page, keep it page-local unless another page needs it.
 
+8. **`×` means remove, `✕` means dismiss.** They look alike and are not the same
+    action. Removing an item from a list uses `RemoveButton`; dismissing a dialog
+    is the `Modal` component's own close control. Do not build a third variant of
+    either, and do not reuse one for the other.
+
+    *Outstanding:* four dialogs predate the shared `Modal` and roll their own close
+    control — the edit dialog and the `openclaw.json` dialog in
+    `app/agents/PageClient.tsx` (both a `ghost` Button with `✕`), the drawer in
+    `app/components/SessionDrawer.tsx` (a bare `<button>`), and
+    `app/components/ModelPickerModal.tsx` (`model-picker__close`, which compounds
+    the problem by using `×`, the *remove* glyph, to dismiss, and omits
+    `type="button"`). The fix is to move them onto `Modal`, not to extract a
+    `CloseButton`: they also reimplement Escape-to-close and overlay behaviour.
+    `ModelPickerModal` has no importers at all, so deleting it is the cheaper fix
+    there.
+
+    Separately, `app/agents/PageClient.tsx` has a raw `×` delete-backup button with
+    no accessible name that should be `RemoveButton`.
+
 ## GoF pattern mapping
 
 Already used:

package/docs/REV4A.md

@@ -1,6 +1,6 @@
 # Rev4a — VPS Dashboard
 
-> **Last updated:** 2026-09-05
+> **Last updated:** 2026-09-14
 
 A Next.js 16 dashboard for monitoring and managing the OpenClaw ecosystem.
 
@@ -120,7 +120,7 @@ When environment variables are saved via the Config page (Save & Restart):
 | `/plugins` | Plugin manager |
 | `/skills` | Skill registry — browse/edit all skills (shared, per-agent workspace, bundled). Promote agent skills to shared with one click. |
 | `/tools` | Tool configuration |
-| `/gateway` | LLM provider sync + agent model configuration — see [GATEWAY.md](dev/GATEWAY.md) |
+| `/gateway` | LLM provider keys, model catalogue and sync — see [GATEWAY.md](dev/GATEWAY.md) |
 | `/config` | Environment management and server restart |
 | `/login` | Authentication page |
 
@@ -188,6 +188,18 @@ sudo systemctl status rev4a.service
 sudo journalctl -u rev4a -f
 ```
 
+### Start-up and Docker
+
+`rev4a serve` waits for the Docker daemon before its Docker-dependent steps, up to
+`REV4A_DOCKER_WAIT_SECONDS` (default 90, capped at 600; `0` checks once without
+waiting; a negative or non-numeric value means 90). It asks the daemon itself with
+`docker info`, so the wait works the same on any Docker install. The variable is
+read from the process environment, not from the `.env` file.
+
+If the daemon never answers, `serve` starts anyway, skips the network and image
+checks, and says so in the log. The startup sync then reaches no agent, and logs
+that too; run Sync All Agents once Docker is up.
+
 ### Systemd environment override
 
 File: `/etc/systemd/system/rev4a-next.service` (EnvironmentFile)
@@ -311,15 +323,16 @@ Available templates:
 **Post-creation pipeline:**
 1. The container boots with the **openclaw-agent-base:latest** image — 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 be fully ready (health check poll, up to 60 s).
+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)
    - `agents.defaults.model.primary` + fallbacks — the primary model selected in the wizard
-5. `syncAgent(name)` writes `models.providers.rev4a` into the container.
+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>`.
 
-**Key difference from the old pipeline:** the entrypoint no longer generates `openclaw.json`. The bootstrap config (including `controlUi.allowedOrigins`) is written by the create route after the gateway has already started. This eliminates the race condition where the entrypoint would overwrite synced provider config on boot.
-
 ---
 
 ## Agent persistence & lifecycle
@@ -385,23 +398,33 @@ repo. The copy is skipped when the workspace is already populated (see
 
 ## Gateway Page (`/gateway`)
 
-Two panels:
+One job: provider configuration. API keys, which catalogue models this deployment
+offers, and pushing that catalogue to every agent.
+
+- Reads the model catalogue from `models.config.json`, merged with user toggles in
+  `<data dir>/model-overrides.json`
+- Scans providers with keys in `<data dir>/provider-keys.json`
+- `PUT /api/gateway/provider` runs `syncAllAgents()`, which writes
+  `models.providers.rev4a` into every agent container
+- **Does NOT touch** `agents.defaults.model` or `agents.list[].model` — those are
+  per-agent settings
+
+### Per-agent model, elsewhere
 
-### Provider Sync
-- Reads active models from `models.config.json` (file-based model catalogue)
-- Scans providers with keys in `data/provider-keys.json`
-- `PUT /api/gateway/provider` runs `syncAllAgents()` which writes `models.providers.rev4a` to every agent container
-- **Does NOT touch** `agents.defaults.model` or `agents.list[].model` — model references are managed per-container from the Agents Tab
+Choosing which model one agent runs is not on this page. It lives in the Model
+section of that agent's detail panel on the Agents page
+(`app/agents/ModelSection.tsx`), which calls `PUT /api/gateway/agent` to write the
+model ref into that container's `openclaw.json`. No gateway restart: OpenClaw
+watches the file and hot-applies the change.
 
-### Agent Model Config
-- Select a container and set its primary model
-- `PUT /api/gateway/agent` writes the model ref (`primary`, `fallbacks`) directly into the container's `openclaw.json`
-- Does NOT restart the gateway — writes are live via file write
+The model is a property of the agent, not of the gateway. See
+[GATEWAY.md](dev/GATEWAY.md) for the write semantics: omitting `fallbacks` keeps the
+agent's current list, `[]` clears it.
 
 ### Model Catalogue (`models.config.json`)
 File-based, tracked in git. Each entry:
 ```json
-{ "id": "deepseek/deepseek-v4-flash", "name": "DeepSeek V4 Flash", "provider": "deepseek", "enabled": true }
+{ "id": "deepseek/deepseek-flash", "name": "DeepSeek Flash", "provider": "deepseek", "enabled": true }
 ```
 Models with `enabled: false` are ignored.
 Only models whose provider has a key in `data/provider-keys.json` are synced.