@flame0510/project-aether 1.1.15 → 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-06-30
+> **Last updated:** 2026-09-14
 > **Goal:** Transform Rev4a from a monitoring dashboard into a central orchestrator for a distributed multi-container agency.
 
 ---
@@ -64,15 +64,15 @@
 
 ---
 
-## 2. Current Architecture (as of 2026-06-24)
+## 2. Current Architecture (as of 2026-08-28)
 
 ### What's already been implemented
 
 **Container separation:** `openclaw-atlas` already runs as a standalone container with `AGENT_ID=atlas`, discovered dynamically by Rev4a. This proves the container-per-agent model works.
 
-**Vault system:** A credentials vault (`/vault` page) stores API keys and service tokens with per-agent permissions. File-backed vault system (removed - sensitive data is env-only).
+**Credentials vault:** The `/credentials` page stores third-party service tokens in `credentials.db` and installs them into containers on explicit sync. Provider API keys live separately in `provider-keys.json`, managed from the Gateway UI.
 
-**Container management UI:** The `/containers` page lists all running Docker containers with resource usage, logs, and quick links. Fully functional.
+**Container management UI:** The `/containers` page lists all running Docker containers with resource usage and quick links, and opens a web terminal into any of them. Fully functional.
 
 **Workspace API:** Lazy-loaded file tree explorer with real-time reads (no caching), supports both host and container workspaces via `docker exec`.
 
@@ -80,8 +80,8 @@
 
 | Feature | Status | Notes |
 |---|---|---|
-| Vault (UI + API) | 🟢 Implemented | SQLite + JSON, no encryption yet |
-| Container page | 🟢 Functional | Lists all containers, logs, resources |
+| Credentials (UI + API) | 🟢 Implemented | SQLite, no encryption yet |
+| Container page | 🟢 Functional | Lists all containers, resources, web terminal |
 | Agent creation wizard | 🟢 Implemented | One-click create with model/template selection |
 | Provider proxy | 🟢 Implemented | Agents route through Rev4a provider gateway |
 | Shared volumes | 🟢 Implemented | Skills + repos mounted on all agents |
@@ -103,7 +103,7 @@ The central container, running the Next.js dashboard + orchestration API.
 - Centralized credential management
 - Docker socket access for container management
 - SQLite DB for cross-container event monitoring
-- **Onboarding wizard** — first-run setup flow at `/onboarding`, tracks progress in `data/onboarding-progress.json`
+- **First-run wizard** — setup flow at `/wizard`; completion is recorded in `<data dir>/data/wizard.json` and read through `GET /api/wizard/status`
 
 **Volume mounts (target):**
 ```
@@ -119,6 +119,61 @@ 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`):
+
+This module is how a route reaches an agent container. The migration to it is
+not finished — routes predating it still shell out directly — so treat these as
+the rules for anything you touch, not as a description of the whole tree:
+
+- **Never `execSync`/`execFileSync` in a request path.** They block Node's single
+  thread: while one runs, no other request is served and no agent's stream
+  advances. A `docker exec` costs ~90 ms warm and the OpenClaw CLI costs
+  seconds, so a route that walks the fleet freezes the event loop for the sum of
+  all of them. Use `dockerExec` / `dockerExecShell` and their `…NoFail` variants.
+- **`mapWithConcurrency` is fail-fast, like `Promise.all`.** If the mapped
+  function rejects for one item, the whole call rejects and results already
+  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/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`
+  option and reference it as `"$KEY"`; command substitution inside an
+  interpolated value would otherwise execute on the host. Only the *name* reaches
+  argv, as `docker exec -e KEY` — docker forwards the value from its own
+  environment, so it appears neither in the host process table nor in any
+  rejection built from that argv.
+- **A timeout does not reject.** `docker exec` exits 0 on the SIGTERM Node sends
+  when the deadline passes, so a command killed halfway *resolves* with whatever
+  it had already printed. A `try/catch` therefore cannot tell a truncated read
+  from a complete one. Where that distinction matters, make the script prove it
+  finished — `detect.ts` emits a `probe:complete` sentinel before its slow calls,
+  `containerRead` prints a terminator after the file — and treat its absence as
+  failure. Anything that writes back what it read must refuse to write when the
+  proof is missing.
+- **A rejection carries `stderr`, never the command.** Node's own message is
+  `Command failed: <argv…>`, which reproduces whatever was interpolated into the
+  script. `dockerExec` replaces it with `docker exec <container>: <cause> —
+  <stderr>`, because these messages travel: `syncProfileToAgents` puts one into
+  `SyncResult.error` and the sync route returns it to the browser.
+
+`dockerExecWithInput` uses `spawn` rather than `execFile` because
+`promisify(exec)` silently ignores an `input` option: the process starts, stdin
+is never written, and the command hangs with no error to point at.
 
 ### 3.2 Agent Container Template (`openclaw-agent-base`)
 
@@ -164,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>
@@ -196,30 +251,34 @@ detailed documentation.
 
 ## 4. Credential Management (Vault)
 
-Provider API keys are stored in `data/provider-keys.json`. Third-party service credentials
-(GitHub, Trello, Vercel, Supabase) are stored in `data/credentials.db` (SQLite).
-At agent spawn time, Rev4a injects only the credentials the agent is permitted to use.
-
-```json
-{
-  "providers": {
-    "openai-codex": "sk-...",
-    "anthropic": "sk-ant-...",
-    "groq": "gsk_..."
-  },
-  "services": {
-    "github": { "token": "***", "user": "Flame0510" },
-    "vercel": { "token": "***", "team": "flame0510" }
-  },
-  "agent_permissions": {
-    "argus": ["providers:all", "services:github", "services:vercel"],
-    "atlas": ["providers:openai-codex", "services:github"],
-    "prometheus": ["providers:openai-codex"]
-  }
-}
-```
+Two separate stores:
+
+- **Provider API keys** — `<data dir>/data/provider-keys.json`, used by the Rev4a
+  provider proxy.
+- **Third-party service credentials** — `<data dir>/data/credentials.db` (SQLite),
+  managed from the Credentials page. Five providers: `github-pat`, `trello`,
+  `vercel`, `supabase`, `notion` (`lib/credentials/providers.ts`).
+
+**Secrets are stored unencrypted.** `credential_secrets.payload` holds raw JSON.
+Anything able to read that file, or to reach `POST /api/credentials/[id]/reveal`
+with a valid session, obtains them in the clear. Encryption (AES-256-GCM, or an
+external vault) is not implemented.
+
+**Delivery is explicit, not automatic.** Creating an agent installs nothing: a
+credential reaches a container only when the user syncs it
+(`POST /api/credentials/[id]/sync`), and leaves only on de-sync
+(`DELETE /api/credentials/[id]/sync`). There is no per-agent permission model —
+any stored credential can be synced to any container. Delivery writes each CLI's
+own config inside the container (`lib/credentials/delivery.ts`); OpenClaw's
+`secrets` subsystem covers only OpenClaw's own configuration credentials and
+offers nothing for third-party CLIs.
+
+`GET /api/credentials/detect` reports which credentials are actually installed,
+by SHA-256 hashing the token found in each container and matching it against the
+stored profiles.
 
-**Current implementation:** SQLite (`credentials.db`) for services, JSON file (`provider-keys.json`) for provider keys (no encryption yet). Future: encrypted with AES-256-GCM or integrated with HashiCorp Vault / Vaultwarden.
+**Planned:** encryption at rest, and a per-agent permission model so a credential
+can be restricted to a subset of agents.
 
 ---
 
@@ -479,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
@@ -568,7 +627,7 @@ for the full rationale.
 | Database | SQLite (WAL mode) | Current `events.db`, may need to scale |
 | Memory | Per-agent SQLite + central index | New |
 | Config | Generated YAML/JSON | New |
-| Vault | SQLite + JSON | Current: credentials.db + provider-keys.json. Future: encrypted |
+| 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 |
 | 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-07-19
+> **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,11 +42,14 @@ 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`). |
-| `OnboardingPageClient` + step components | `app/onboarding/PageClient.tsx` | 4-step wizard (`WelcomeStep`, `ProvidersStep`, `AgentsStep`, `DoneStep`) + `WizardFrame` shell with mobile-first CSS. |
-| `useOnboarding` | `app/onboarding/useOnboarding.ts` | Shared hook: onboarding state, step transitions, provider save, restart. Receives server-side initial state to avoid loading flash. |
-| `OnboardingIcons` | `app/onboarding/icons.tsx` | Shared SVG icons (flyweight pattern): `ArrowRightIcon`, `CheckIcon`, `DockerIcon`, `GatewayIcon`, etc. |
+| `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`. |
 | `tokens` | `tokens.ts` | TypeScript types for `Tone` and related token values. |
 | `Badge` | `Badge.tsx` | Inline status tag with tone variants (success, danger, warning, neutral). Used for channel chips, pairing labels, error/success messages. |
+| `Skeleton` + shape helpers | `app/components/Skeleton.tsx` | Shimmer placeholders. `Skeleton` is the primitive; the rest mirror one specific layout each: `TreeSkeleton`, `CodeSkeleton`, `CronJobsSkeleton`, `CronRunsSkeleton`, `CredentialCardsSkeleton`, `AgentSyncRowsSkeleton`, `SkeletonLines`, `SkeletonMetric`, `CardRowSkeleton`. A shape helper must match the real markup it stands in for — same row structure, same paddings, same element count where the count is known — so nothing reflows when data replaces it. |
 
 ### Rules
 
@@ -53,10 +57,33 @@ All shared UI primitives live in `app/components/ui/` and are exported from `app
 2. **No inline styles on interactive elements.** Buttons, inputs, selects use the `app/components/ui/*` component with component props. Only layout/wrapping containers use inline style.
 3. **No Italian in code, labels, or comments.** UI strings, error messages, aria-labels — all English.
 4. **Clickable/custom interactive elements must be `<button type="button">`.** Not `<span onClick>`, not `<div onClick>`. Always include `aria-label` for icon-only buttons.
+4a. **A control gated on another field stays visible and disabled** — never conditionally unmounted. Rendering it only once its dependency is filled makes it appear out of nowhere, and any hint that references it is pointing at something not on screen. Show it disabled, with the reason beside it, so the shape of the form is stable from the first render.
 5. **Modals inside forms** — close button has `type="button"` to prevent accidental form submission.
-6. **Loading buttons** — set `loading={true}` on `Button`, do not render separate loaders next to the button. The spinner is built-in.
+6. **Loading buttons** — set `loading={true}` on `Button`, do not render separate loaders next to the button. The spinner is built-in. The label must also change for the duration (`Saving…`, `Deleting…`, `Syncing…`).
+6a. **One in-flight mutation, keyed.** Hold a single `busy` string identifying the running action (`delete:<id>`, `sync:<id>:<container>`), plus a `useRef` mirror as the authoritative guard — state is read from the render that produced the click, so two fast clicks would otherwise both pass. `loading` compares against the exact key; `disabled` is set for any busy value, so a control that would be refused looks refused. Never key a mutation on one dimension when the same control is rendered per row of another: a key holding only a container name puts every profile's button for that container into a spinner.
+6b. **Do not hold the lock across a slow refresh.** Release it when the mutation itself completes and refresh derived state afterwards, unawaited. Show the pending state by fading the stale values only — never the buttons, since `opacity` on an ancestor cannot be undone by a child and makes live controls read as disabled.
+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:
@@ -108,6 +135,9 @@ For interactive pages that can change view/file/tab quickly:
 2. Guard against stale updates after `await` boundaries.
 3. On navigation/context switch, kill in-flight requests before starting new ones.
 4. Mobile layout changes must not wait on network completion.
+5. After a mutation, refresh the cheap endpoint and await it; fire the expensive one without awaiting. A page that re-reads everything makes the user wait on work their change did not need.
+6. A refresh helper invoked from a mutation must never reject. The mutation has already succeeded by then, so a failed re-read surfacing as the caller's error reports a completed action as failed.
+7. Check `res.ok` before reading the body. An error response is still valid JSON, so `json.items ?? []` silently turns a 401 into an empty result presented as fact.
 
 ## Migration rule