@flame0510/project-aether 1.2.0 → 1.3.0

package/docs/rag/DATA-FRESHNESS.md

@@ -1,6 +1,6 @@
 # Data Freshness in Rev4a
 
-> **Last updated:** 2026-07-18
+> **Last updated:** 2026-09-13
 
 Understanding how current the data in Rev4a is — and what is truly real-time vs. periodically updated.
 
@@ -8,47 +8,60 @@ Understanding how current the data in Rev4a is — and what is truly real-time v
 
 ## Session data
 
-**Update frequency:** every 15–30 seconds
+**Update frequency:** every 30 seconds
 
-The daemon polls `openclaw sessions --json --all-agents` on this schedule:
-- 15 seconds when at least one session has status `working`
-- 30 seconds when no sessions are actively working
+The daemon polls `openclaw sessions --json --all-agents` on a fixed 30-second
+timer. Session statuses, token counts, and costs are therefore up to 30 seconds
+behind reality.
 
-This means session statuses, token counts, and costs are at most 30 seconds behind reality during quiet periods, and 15 seconds behind during active work.
+The code declares a shorter 15-second interval for when a session is `working`,
+but nothing uses it — the timer is always 30 seconds. Do not tell a user the
+dashboard speeds up during active work.
 
-**What this means for PULSE:** if you ask "is Argus working right now?", the answer reflects data that is up to 30 seconds old.
+**What this means for PULSE:** if you ask "is Argus working right now?", the
+answer reflects data that is up to 30 seconds old.
 
 ---
 
 ## Event feed
 
-**Update frequency:** ~3 seconds (via SSE stream)
+**Update frequency:** every 5 seconds (via SSE stream)
 
-The `/api/stream` endpoint pushes updates to the dashboard every ~3 seconds. This includes:
+The `/api/stream` endpoint pushes updates to the dashboard every 5 seconds. It
+sends exactly three things:
 - New events (spawn, complete, error, tool_call)
-- Updated session list
+- The session list
 - Today's cost total
-- Lineage data
 
-The event feed is as close to real-time as Rev4a gets. However, events are generated by the daemon's poll cycle, so an event that just happened may take up to 30 seconds to appear.
+Lineage is **not** pushed over the stream; the Lineage page fetches it itself.
+
+The event feed is as close to real-time as Rev4a gets. However, events are
+generated by the daemon's poll cycle, so an event that just happened may take up
+to 30 seconds to appear, plus up to 5 more to reach the browser.
 
 ---
 
 ## System metrics (CPU, RAM, disk)
 
-**Update frequency:** every daemon poll cycle (15–30 seconds)
+**Update frequency:** every daemon poll cycle (30 seconds)
+
+**Retention:** 30 days (older rows are pruned automatically each cycle)
 
-**Retention:** last 24 hours only (older rows are pruned automatically)
+These metrics are collected and stored, and served by `GET /api/metrics`. They
+are **not** shown on the dashboard — see the System Health note below.
 
 ---
 
 ## Cost totals
 
-**Update frequency:** every 15–30 seconds (recalculated from sessions on each API call)
+**Update frequency:** every 30 seconds (recalculated from sessions on each API call)
 
-The cost figures shown in the dashboard are always computed fresh from the database on each page load or SSE push. They are not cached.
+The cost figures shown in the dashboard are always computed fresh from the
+database on each page load or SSE push. They are not cached.
 
-**Cost override:** if a manual override is set for the current month, it is shown immediately after being saved — no delay.
+**Cost override:** `/api/cost-override` exists, but no page in the dashboard
+reads or writes it. There is no UI for setting one, so do not direct a user to
+"the cost override screen".
 
 ---
 
@@ -66,16 +79,25 @@ Cron status (last run, next run) is fetched directly from the OpenClaw gateway e
 
 **Update frequency:** on demand (read from `openclaw.json` on each request)
 
-The agents list, Telegram accounts, and bindings are read directly from `openclaw.json` each time the Agents Config page is accessed. Changes saved via the UI take effect immediately.
+The agents list, Telegram accounts, and bindings are read directly from
+`openclaw.json` each time they are requested.
+
+`GET /api/agents-config` serves this, but no page calls it — there is no "Agents
+Config page". Per-agent settings are reached from the agent's detail panel on the
+Agents page.
 
 ## Agent base image
 
-**Update frequency:** polled every 2 seconds during a build; on page load otherwise
+**Update frequency:** polled every 2 seconds, continuously
 
-The `GET /api/agents/image-status` endpoint compares the local image digest
-with the remote registry digest (ghcr.io). Download progress is shown inline
-via polling `GET /api/agents/image-status` and reading logs from
-`/tmp/rev4a-download-<timestamp>.log`.
+`GET /api/agents/image-status` compares the local image digest with the remote
+registry digest on ghcr.io. The banner polls it every 2 seconds for as long as the
+page is open, not only while something is running.
+
+The operation the banner triggers is a **`docker pull`**, not a build. While it
+runs the banner shows an indeterminate animated bar: there is no percentage, no
+byte count, and no log output in the UI. A log is written server-side to
+`/tmp/rev4a-download-<timestamp>.log`, but nothing in the dashboard reads it.
 
 ---
 
@@ -83,7 +105,9 @@ via polling `GET /api/agents/image-status` and reading logs from
 
 **Update frequency:** on demand (files read from disk on each request)
 
-Memory files (MEMORY.md, etc.) are read from disk each time they are requested. There is no caching.
+Memory files are read from disk each time they are requested. There is no caching.
+
+The tracked set is `USER.md`, `MEMORY.md`, `AGENTS.md`, `SOUL.md`, `HEARTBEAT.md`.
 
 ---
 
@@ -91,7 +115,7 @@ Memory files (MEMORY.md, etc.) are read from disk each time they are requested.
 
 | Data | Why it may be stale |
 |---|---|
-| Sessions ended more than 7 days ago | `agents-active` endpoint only looks back 7 days |
+| Cron sessions older than 7 days | The daemon prunes cron session rows after 7 days |
 | Sessions never polled by daemon | If the daemon was down, sessions from that window are missing |
 | Tool calls for a session | Only captured if the OpenClaw session export includes them |
 | Costs before Rev4a was installed | Historical data before the first daemon run is not available |
@@ -100,10 +124,15 @@ Memory files (MEMORY.md, etc.) are read from disk each time they are requested.
 
 ## How to check if data is fresh
 
-The System Health page shows a check like "last event X seconds ago". If this number is larger than ~60 seconds, the daemon may have stopped.
+System health is a card on the **Dashboard**, not a page of its own. Its checks
+cover session runtime, ingestion freshness, errors in the last 24 hours, today's
+usage-based cost, and cron jobs. It reports no CPU, RAM, or disk figures.
 
-You can also run this command on the server to check directly:
+To check directly on the server:
 ```bash
-sqlite3 data/events.db \
+sqlite3 ~/.config/rev4a/data/events.db \
   "SELECT datetime(MAX(ts)/1000, 'unixepoch', 'localtime') FROM events"
 ```
+
+The database lives under the Rev4a data directory, which defaults to
+`~/.config/rev4a/` and moves with `REV4A_DATA_DIR`. It is not inside the repo.

package/docs/rag/GLOSSARY.md

@@ -1,6 +1,6 @@
 # Rev4a Glossary
 
-> **Last updated:** 2026-08-28
+> **Last updated:** 2026-09-14
 
 Terms you'll encounter while using the Rev4a dashboard.
 
@@ -10,16 +10,16 @@ Terms you'll encounter while using the Rev4a dashboard.
 An AI assistant configured with a specific role, AI model, and workspace. Each agent has a name (e.g. "Argus") and can run multiple sessions over time. Agents are deployed as Docker containers with persistent data volumes.
 
 ## Agent Template
-A pre-built configuration used when creating a new agent. Templates include default files (AGENTS.md, SOUL.md, MEMORY.md, IDENTITY.md, TOOLS.md, HEARTBEAT.md, BOOTSTRAP.md) and settings. Located in `agent-templates/`. Available templates: **Atlas** (general dev), **Argus** (security/audit), **Prometheus** (client-facing), and **Custom** (blank slate — bootstraps identity interactively on first run).
+A pre-built configuration used when creating a new agent. Each template ships its own set of files. Atlas has AGENTS.md, SOUL.md, IDENTITY.md, TOOLS.md, MEMORY.md and HEARTBEAT.md; Argus and Prometheus have the same minus HEARTBEAT.md; Custom has only AGENTS.md, MEMORY.md and BOOTSTRAP.md. Located in `agent-templates/`. Available templates: **Atlas** (general dev), **Argus** (security/audit), **Prometheus** (client-facing), and **Custom** (blank slate — bootstraps identity interactively on first run).
 
 ## Badge
-A small inline label component used for status indicators and channel chips. Supports success, danger, warning, and neutral tones. Used for TG/WA chips on the agent list and pairing status in the Channel Manager.
+A small inline label component used for status indicators and channel chips. Six tones: neutral, accent, success, warning, danger, info. Used for the Telegram chip on the agent list and pairing status in the Channel Manager. There is no WhatsApp support anywhere in Rev4a.
 
 ## Backup (Agent)
 A compressed archive (`.tar.gz`) of an agent's persistent volume (`/root/`). Backups exclude the npm cache to keep sizes small (~1.5 MB). Stored in the `rev4a-backups` Docker volume. Used for restore operations and auto-created before each recreate.
 
 ## Container
-A Docker container running on the server. Each agent runs in its own container. The Containers page shows all containers, including infrastructure ones (databases, reverse proxies, etc.), with CPU/memory metrics and a web terminal.
+A Docker container running on the server. Each agent runs in its own container. The Containers page shows all containers, including infrastructure ones such as databases and reverse proxies, with a web terminal link. It shows no CPU or memory metrics.
 
 ## Channel
 A communication channel (Telegram) configured on an agent. Channels allow users to send DMs to the agent via messaging apps. The Channel Manager modal lets you connect/disconnect Telegram and manage pairings (approve/reject senders).
@@ -31,7 +31,7 @@ Modal in the agent detail panel for configuring Telegram channels. Connect with
 The estimated cost of an agent session in USD, calculated from tokens used and per-model pricing. Rev4a shows cost by today, 7 days, 30 days, all-time, and by model.
 
 ## Cost Override
-A manual correction for a month's total cost. If the automatic calculation doesn't match the actual invoice, you can set an override value for that month with an optional note.
+A manual correction for a month's total cost, stored through `/api/cost-override`. There is currently no screen for it: no page in the dashboard reads or writes an override, so it can only be set by calling the API directly.
 
 ## Credential
 A third-party service token (GitHub PAT, Trello API key, Vercel token, Supabase access key, Notion API token) stored in the Rev4a vault. A credential is installed into a container only when the user syncs it, and removed on de-sync; any credential can be synced to any container. Every reveal is written to an audit table that no route or view reads.
@@ -40,25 +40,25 @@ A third-party service token (GitHub PAT, Trello API key, Vercel token, Supabase
 A scheduled task that runs an agent automatically at a fixed time (e.g. every night at 3:15 AM). Configured with standard cron syntax. Jobs can be enabled/disabled per entry.
 
 ## Dashboard
-The main page of Rev4a (`/`). Shows live sessions, cost summary, system health metrics (CPU, RAM, disk, load average), and a real-time event feed. A setup banner appears if the first-run wizard is incomplete.
+The main page of Rev4a (`/`). Shows live sessions, cost summary, health cards for Rev4a's runtime, cron and lineage, and a real-time event feed. It shows no CPU, RAM, disk or load average, and there is no setup banner: an incomplete wizard redirects to `/wizard`.
 
 ## Event
-A lifecycle occurrence for a session: spawned, completed, errored, or a tool call made. Events appear in the live feed on the Dashboard and are pushed via SSE every ~3 seconds.
+A lifecycle occurrence for a session: spawned, completed, errored, or a tool call made. Events appear in the live feed on the Dashboard and are pushed via SSE every 5 seconds.
 
 ## Gateway
-The routing layer that connects agents to AI providers. The Gateway page has two panels: Provider Sync (push the model catalogue to all agents) and Agent Model Config (set each agent's primary model and fallbacks).
+The routing layer that connects agents to AI providers. The Gateway page manages provider API keys and the model catalogue, and pushes that catalogue to every agent. Which model a given agent runs is set elsewhere, in the Model section of that agent's detail panel.
 
 ## Lineage
-The parent-child relationship tree between sessions. When an agent spawns another agent to do work, that relationship is shown as an interactive graph on the Lineage page. Configurable time periods: 1d, 7d, 30d.
+The parent-child relationship tree between sessions. When an agent spawns another agent to do work, that relationship is shown as an interactive graph on the Lineage page. Configurable time periods: 1d, 3d, 7d, 15d, 30d and all.
 
 ## Memory
-Files that store an agent's persistent knowledge and personality: MEMORY.md, SOUL.md, IDENTITY.md, USER.md, AGENTS.md, TOOLS.md, HEARTBEAT.md. Editing them changes how an agent behaves. The Memory page shows all files with size and budget tracking.
+Files that store an agent's persistent knowledge and personality. The tracked set is USER.md, MEMORY.md, AGENTS.md, SOUL.md and HEARTBEAT.md. Editing them changes how an agent behaves. The Memory page shows these with size and budget tracking. A template may also ship IDENTITY.md or TOOLS.md, which are not tracked.
 
 ## Model
-The AI model used by an agent or session. Examples: GPT-5.4, Claude Sonnet 4, DeepSeek V4 Flash. Models are linked to specific providers. The Gateway page manages which models are enabled and which agent uses which model.
+The AI model used by an agent or session. Examples: GPT-5.4, Claude Sonnet 5, DeepSeek Flash. Models are linked to specific providers. The Gateway page controls which models are enabled for the whole deployment; the agent detail panel sets which one a given agent runs, plus its fallbacks. A model whose name the provider has retired is tagged `deprecated` on the agent card and in that panel. The Gateway page does not show it.
 
 ## First-run wizard
-First-time setup wizard at `/wizard`. Steps: Welcome → Providers → First Agent → Ready. Completion is recorded in `wizard.json` under the data directory. Always accessible from the sidebar or mobile navbar.
+First-time setup wizard at `/wizard`. Steps: Welcome → Providers → First Agent → Ready. Completion is recorded in `wizard.json` under the data directory. Always accessible from the sidebar. The mobile bottom navigation has five entries — Home, Agents, Workspace, Gateway, Containers — and the wizard is not one of them.
 
 ## Plugin
 An extension that adds new tools and capabilities to agents. Plugins are installed in the workspace and appear in the Plugins page with enable/disable toggles.
@@ -119,7 +119,9 @@ Optional reverse proxy for routing web traffic to agent containers. If configure
 Rev4a's store for third-party service tokens (GitHub, Trello, Vercel, Supabase, Notion). Provider API keys live separately in `provider-keys.json`, managed from the Gateway page. Supports reveal (written to an audit table no route or view reads), sync to and from containers, and live detection of which credentials are actually installed. Secrets are stored unencrypted.
 
 ## Workspace
-The directory where an agent's operational files live (config, memory files, skills, plugins, scripts). The Workspace page lets you browse, view, and edit files across the VPS host and all agent containers.
+The directory where an agent's operational files live (config, memory files, skills, plugins, scripts). The Workspace page lets you browse, view, and edit files across the host workspace, which appears as `Local`, and all agent containers.
 
 ## System Health
-Hardware metrics shown on the Dashboard: CPU usage (%), RAM used/total (MB), disk used/total (GB), system load average (1m). The System Health API (`/api/system-health`) also generates recommendations (e.g. "Consider archiving old sessions to reduce disk usage"). Status can be `ok`, `warn`, or `error`.
+A card on the Dashboard reporting whether Rev4a itself is working, not the hardware it runs on. `/api/system-health` returns checks for session runtime, feed ingestion freshness, errors in the last 24 hours, today's usage-based cost, and cron jobs, each with a health of `ok`, `warning` or `error`, plus a list of recommendations.
+
+It reports no CPU, RAM, disk or load average. Those metrics are collected by the daemon and stored for 30 days, and are served by `/api/metrics`, but no page displays them.

package/docs/rag/REV4A-OVERVIEW.md

@@ -1,13 +1,15 @@
 # What is Rev4a?
 
-> **Last updated:** 2026-09-05
+> **Last updated:** 2026-09-13
 
 Rev4a is the control panel for your AI agent infrastructure. It shows you everything your agents are doing, how much they cost, and whether the system is healthy — all in one dashboard.
 
 ## What can you do in Rev4a?
 
 ### Dashboard (`/`)
-The main page. See live sessions (who's working right now), cost summary by model and time period (today, 7 days, 30 days), system health (CPU, RAM, disk, load average), and a real-time event feed. Click any session row to open the Session Drawer and see every tool call the agent made. If the first-run wizard is incomplete, a banner appears at the top with a link to continue.
+The main page. See live sessions (who's working right now), cost summary, an overall health indicator, and a real-time event feed. Click any session row to open the Session Drawer and see every tool call the agent made.
+
+The health cards cover Rev4a's own runtime, cron and watchdog, and lineage. They do **not** show CPU, RAM, disk, or load average: those metrics are collected and stored, but no page displays them. There is no wizard banner on the dashboard; an incomplete setup redirects to `/wizard` instead.
 
 ### First-run wizard (`/wizard`)
 First-run setup wizard that guides new users through configuration. Four steps:
@@ -16,7 +18,7 @@ First-run setup wizard that guides new users through configuration. Four steps:
 3. **First Agent** — understand how agents work and what you need to create one
 4. **Ready** — site map of key sections with quick links
 
-The wizard is always accessible from the sidebar. A progress badge (e.g. "1/3") shows how many steps are complete. Once finished, the badge disappears and the dashboard banner goes away.
+The wizard is always accessible from the sidebar. There is no progress badge on that entry and no banner elsewhere.
 
 ### Agents (`/agents`)
 Manage Docker containers running OpenClaw agents. See which agents are running, stopped, or errored. Filter by status, view agent details (environment variables, ports, auth tokens, backups, Telegram channels), and create new agents. Each agent card shows its template, status, TG channel chip, and a direct link to its Control UI.
@@ -32,34 +34,29 @@ Manage Docker containers running OpenClaw agents. See which agents are running,
 
 The agent list also shows a compact TG chip next to each agent name (green = connected, hidden if not configured).
 
-The Agents page includes a banner for the **agent base image** (`openclaw-agent-base:latest`):
-- Green: image is up-to-date (no banner shown)
-- Yellow: image is outdated or missing — click "Rebuild Image" to start a build
-- Copper: a build is running in the background — click "View Progress" to open
-  the build modal
-
-The build modal shows live Docker build logs (polled every 2s). You can:
-- **Run in Background** — close the modal, build continues on the server
-- **Abort** — kill the build process; the existing image stays intact
-- **Refresh / re-enter** — opening the modal again resumes log streaming
-  from the last seen line
+The Agents page includes a banner for the **agent base image**
+(`openclaw-agent-base:latest`). It is hidden when the image is present and current.
+When the image is missing or outdated it appears with one button, labelled
+**Download Image** or **Download Update**.
 
-The build writes logs to `/tmp/rev4a-build-<timestamp>.log` so they survive
-page refreshes and modal closes.
+That button runs a `docker pull` from the registry. It is a download, not a build.
+While it runs the banner shows an indeterminate animated bar with no percentage and
+no log output; there is no modal, no "View Progress", no "Run in Background", and
+no way to abort from the UI. Status is polled every 2 seconds.
 
 ### Create Agent (`/agents/create`)
 Wizard to spin up a new agent. Steps: choose a template (Prometheus, Argus, Atlas, etc.), name your agent, pick a model, set an optional port range (default: auto-assigned 10-port block, e.g. 3700-3709). The agent is created as a Docker container with a persistent volume — all config, workspace files, and credentials survive container restarts.
 
 ### Lineage (`/lineage?period=7d`)
-Interactive graph showing session family trees — which agent spawned which child agent, across configurable time periods (1d, 7d, 30d). Click any node to inspect. Includes a live feed side panel.
+Interactive graph showing session family trees — which agent spawned which child agent, across configurable time periods: 1d, 3d, 7d, 15d, 30d, and all. Click any node to inspect. Includes a live feed side panel.
 
 ### Gateway (`/gateway`)
-Central hub connecting agents to AI providers. Two panels:
-- **Provider Sync** — reads the model catalogue from `models.config.json`, discovers which providers have API keys, and syncs the full model list to every agent container
-- **Agent Model Config** — set each agent's primary model and fallback models via `PUT /api/gateway/agent`
+Connects agents to AI providers. Add and remove provider API keys, enable or disable individual models in the catalogue read from `models.config.json`, and push the resulting model list to every agent container. It does not assign models to agents: choosing which model an agent runs is done per agent, in the Model section of the agent's detail panel on the Agents page.
 
 ### Containers (`/containers`)
-Full list of all Docker containers on the server. See name, image, status, ports, IP, CPU%, and memory usage. Click "Terminal" on any container to open an interactive shell. Use Start/Stop/Restart buttons to manage lifecycle.
+Full list of all Docker containers on the server, including stopped ones. Each row shows name, status, image, IP, ports, and an agent pill where applicable. Click "Terminal" to open an interactive shell into that container.
+
+The page shows no CPU or memory figures and has no start, stop, or restart buttons: it is read-only apart from the terminal link. Container lifecycle is managed from the Agents page.
 
 ### Container Terminal (`/containers/terminal/[id]`)
 Live web terminal into a Docker container. Run commands, inspect files, debug issues — like SSH but in the browser.
@@ -74,13 +71,15 @@ Manage third-party service credentials: GitHub, Trello, Vercel, Supabase, Notion
 Scheduled tasks auto-discovered from the host OpenClaw gateway (via `openclaw cron list --json`) and every running Docker container with the `AGENT_ID` label (via `docker exec openclaw cron list --json`). Filter jobs by agent using the toolbar tabs. Each job shows name, description, cron expression, next run, last run, and last status. Toggle on/off per job. The run history panel shows recent cron run executions for the selected job, loaded on demand from the container's gateway.
 
 ### Memory / Context (`/memory`)
-Browse agent memory files — MEMORY.md, SOUL.md, IDENTITY.md, USER.md, AGENTS.md, TOOLS.md, HEARTBEAT.md. These files define how agents behave, what they know, and their personality. Also shows total memory budget vs usage.
+Browse agent memory files. The tracked set is USER.md, MEMORY.md, AGENTS.md, SOUL.md and HEARTBEAT.md. These files define how agents behave, what they know, and their personality. Also shows total memory budget vs usage.
+
+A template may ship other files, such as IDENTITY.md or TOOLS.md, but those are not part of the tracked context set.
 
 ### Config (`/config`)
 Rev4a application settings. View and modify environment variables (password, tokens, secrets), restart the server. Changes are persisted to `.env`, synced to systemd, and a daemon-reload is triggered.
 
 ### Tools (`/tools`)
-Catalog of every tool available to agents — built-in commands, MCP server tools, plugin tools, and audio/TTS configuration. Includes timezone settings.
+Catalog of the OpenClaw built-in tools available to agents, grouped by area: file and code, shell, web, messaging, sessions, media, and others. The list is curated in the app, not discovered at runtime, so it covers built-ins only and does not enumerate MCP servers or plugin tools. The page also holds audio/TTS and timezone settings.
 
 ### Plugins (`/plugins`)
 Browse installed OpenClaw plugins. Enable/disable toggle per plugin. Plugins extend agent capabilities with new tools and integrations.
@@ -101,7 +100,7 @@ Password-protected access to the dashboard. Enter the Rev4a password to authenti
 
 ## What about Pulse?
 
-Pulse is the AI assistant embedded in Rev4a. She appears as a floating chat button in the bottom-right corner of every page. She can:
+Pulse is the AI assistant embedded in Rev4a. She appears as a floating chat button in the bottom-right corner, on every page except login, setup and the first-run wizard. She can:
 
 - Explain what any page does
 - Guide you through features ("how do I create an agent?")

package/docs/rag/WHAT-I-CAN-ANSWER.md

@@ -1,6 +1,6 @@
 # What PULSE Can Answer
 
-> **Last updated:** 2026-08-28
+> **Last updated:** 2026-09-14
 
 PULSE is the in-dashboard AI concierge for Rev4a. This document defines what she can and cannot answer.
 
@@ -12,7 +12,7 @@ PULSE is the in-dashboard AI concierge for Rev4a. This document defines what she
 - "How do I get to the container list?"
 - "Where can I see the first-run wizard?"
 - "Is there a page for cron jobs?"
-- "Where can I see my AI providers?" — The Gateway page (`/gateway`) shows providers, models, agent assignments.
+- "Where can I see my AI providers?" — The Gateway page (`/gateway`) shows providers and the model catalogue. Which model an agent runs is on the Agents page, in that agent's detail panel.
 - "How do I create a new agent?"
 - "What templates are available?"
 - "What is the Custom template?"
@@ -52,10 +52,10 @@ PULSE is the in-dashboard AI concierge for Rev4a. This document defines what she
 - "How do I delete an agent?"
 - "How do I restart the Rev4a server?"
 - "How do I change environment variables?"
-- "How do I add a cost override?"
+- "How do I add a cost override?" — There is no screen for it. The endpoint exists, but nothing in the dashboard calls it.
 - "How do I see the session lineage?"
 - "How do I log in to an agent's control UI?"
-- "How do I register a new provider via OAuth?"
+- "How do I register a new provider via OAuth?" — The endpoint exists but no page uses it. Providers are added by pasting an API key on the Gateway page.
 - "How do I manage agent model fallbacks?"
 - "How do I connect an agent to Telegram?"
 - "How do I approve a pairing code?"
@@ -97,9 +97,7 @@ PULSE is the in-dashboard AI concierge for Rev4a. This document defines what she
 - "What does the yellow diamond next to an agent mean?"
 - "Why is the agent base image banner showing?"
 - "How do I fix 'image is outdated'?"
-- "What happens if I abort a build?"
-- "Can I close the build modal while it's running?"
-- "How do agent image rebuilds work?"
+- "How do agent image updates work?" — The banner on the Agents page runs a `docker pull`. It is a download, not a build: there is no modal, no live log, and no way to abort from the UI.
 - "Why is my Telegram bot not connecting?"
 - "Why can't I approve a pairing code?"
 - "Why is the TG badge missing from my agent?"

package/instrumentation.ts

@@ -9,7 +9,15 @@ export async function register() {
   if (process.env.NEXT_RUNTIME === 'nodejs') {
     try {
       const { syncAllAgents } = await import('./app/api/gateway/sync');
-      syncAllAgents();
+      // The outcome used to be discarded. syncAllAgents reports failures instead of
+      // throwing, so the catch below never saw a sync that reached no container —
+      // Docker not yet up at boot left the fleet stale with nothing in the log.
+      const outcome = syncAllAgents();
+      if (outcome.ok) {
+        console.log(`[rev4a] Startup sync: ${outcome.summary}`);
+      } else {
+        console.warn(`[rev4a] Startup sync incomplete: ${outcome.summary} Run Sync All Agents once the cause is fixed.`);
+      }
     } catch {
       // Best-effort — don't block startup if sync fails
       console.warn('[rev4a] Failed to sync agents on startup');

package/lib/agent-readiness.ts

@@ -0,0 +1,110 @@
+/**
+ * Waiting for an agent's Gateway to finish starting.
+ *
+ * **Which endpoint.** OpenClaw exposes three, answering three different questions:
+ *
+ *   /health, /healthz    the HTTP server is listening
+ *   /startupz            startup finished and the Gateway is not draining
+ *   /readyz              the above, plus configured channels pass deep checks
+ *
+ * `/startupz` is the one callers need: the create route configures the agent as
+ * soon as this returns. A Gateway that refused readiness — for instance one that
+ * found a legacy session store and wants `doctor --fix` — still answers 200 on
+ * `/health`. `/readyz` would fail on an expired channel token, and the create
+ * route deletes the container when this probe times out, so a false negative
+ * there destroys a healthy agent over an unrelated channel.
+ *
+ * **Two OpenClaw majors.** `/startupz` exists from 9.x: 503 while starting or
+ * draining, 200 with `{"status":"started"}` when done. The 2026.7.1-2 image that
+ * `openclaw-agent-base` currently pins has no `/startupz`; its Gateway answers
+ * every unknown path with 200 and the web UI's HTML. So the probe reads the
+ * status code *and* the body, and falls back to `/health` only for a 200 that is
+ * not JSON — the old image. A 503, or no answer, means "not yet", never "use
+ * `/health`": reading an empty answer as "old image" makes a 9.x Gateway count as
+ * ready the moment it starts listening.
+ *
+ * Delete the `/health` fallback once every image is on 9.x.
+ *
+ * **Async.** A request path must not hold Node's single thread for up to a
+ * minute; see docs/ARCHITECTURE.md §3.1.
+ */
+import { dockerExecNoFail } from '@/lib/docker-exec';
+
+/** Interval between attempts. The Gateway takes seconds to boot, not milliseconds. */
+const POLL_INTERVAL_MS = 2_000;
+
+/** Per-attempt budget. Generous: a loaded host can be slow to answer. */
+const ATTEMPT_TIMEOUT_MS = 5_000;
+
+const sleep = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));
+
+/**
+ * One HTTP GET from inside the container, with its status code.
+ *
+ * `curl -w` appends the code as the last line. `status` is 0 when nothing usable
+ * came back. A deadline may reject, or resolve with truncated output because
+ * `docker exec` can exit 0 on the SIGTERM (docs/ARCHITECTURE.md, "A timeout does
+ * not reject"); either way a last line that is not a three-digit code counts as
+ * no answer. The image has `curl`, not `wget`.
+ */
+async function probe(container: string, path: string): Promise<{ status: number; body: string }> {
+  const out = await dockerExecNoFail(
+    container,
+    ['curl', '-s', '-o', '-', '-w', '\n%{http_code}', `http://127.0.0.1:3000${path}`],
+    { timeoutMs: ATTEMPT_TIMEOUT_MS },
+  );
+  if (!out) return { status: 0, body: '' };
+  const cut = out.lastIndexOf('\n');
+  const tail = (cut === -1 ? out : out.slice(cut + 1)).trim();
+  if (!/^\d{3}$/.test(tail)) return { status: 0, body: '' };
+  return { status: Number(tail), body: cut === -1 ? '' : out.slice(0, cut) };
+}
+
+function asJson(body: string): Record<string, unknown> | null {
+  if (!body.trimStart().startsWith('{')) return null;
+  try {
+    const v = JSON.parse(body);
+    return v && typeof v === 'object' ? (v as Record<string, unknown>) : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Poll a container's Gateway until it has finished starting.
+ *
+ * Resolves `true` on the first affirmative answer, `false` on timeout. Never
+ * throws: an unreachable container is indistinguishable from a slow one until the
+ * deadline passes, and every caller treats both the same way.
+ */
+export async function waitForGatewayReady(
+  container: string,
+  timeoutMs = 60_000,
+): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs;
+
+  while (Date.now() < deadline) {
+    const startupz = await probe(container, '/startupz');
+
+    if (startupz.status === 200) {
+      const json = asJson(startupz.body);
+      if (json) {
+        // 9.x: accept only the answer that means startup finished.
+        if (json.status === 'started') return true;
+      } else {
+        // 200 with a non-JSON body: the 2026.7.1-2 web UI catch-all, so this build
+        // has no /startupz. Liveness is the best signal it offers.
+        const health = await probe(container, '/health');
+        const h = health.status === 200 ? asJson(health.body) : null;
+        if (h && (h.ok === true || h.status === 'live')) return true;
+      }
+    }
+    // 503 (starting or draining), any other code, or no answer: not yet.
+
+    // Only sleep if there is still budget left to use afterwards.
+    if (Date.now() + POLL_INTERVAL_MS >= deadline) break;
+    await sleep(POLL_INTERVAL_MS);
+  }
+
+  return false;
+}

package/lib/channelManager.ts

@@ -21,7 +21,7 @@
  *     - gateway/config-channels.md
  *     - concepts/multi-agent.md (bindings)
  */
-import { execSync } from 'child_process';
+import { execSync, execFileSync } from 'child_process';
 
 // ── Types ────────────────────────────────────
 
@@ -232,7 +232,7 @@ export function removeTelegram(agentId: string): { success: boolean; error?: str
  * The agentId in the binding MUST be "main" (OpenClaw's default agent)
  * so that sessions are created as `agent:main:main`.
  * Using the container name as agentId would create sessions like
- * `agent:NOMEAGENTE:main` which breaks model bindings that target
+ * `agent:<AGENT_NAME>:main` which breaks model bindings that target
  * `agent:main:*`.
  *
  * Per multi-agent.md: bindings route (channel, accountId) to agentId.
@@ -360,33 +360,75 @@ export function approvePairing(agentId: string, code: string, channel: string =
   }
 }
 
-/** Revoke an approved sender from the allowlist */
+/**
+ * Script run inside the container to drop one sender from the allowlist file.
+ *
+ * The sender id arrives as `process.argv[1]`, never interpolated into the source.
+ * The previous version built this string by substitution, applying shell-style
+ * escaping to a value that lands inside a JavaScript string literal: an id
+ * containing an apostrophe closed the literal and the rest ran as code.
+ *
+ * It prints one of three sentinels so the caller can tell the outcomes apart —
+ * `docker exec` exits 0 even when killed by the timeout, so an empty result
+ * cannot be read as success (see docs/ARCHITECTURE.md §3.1).
+ */
+const REVOKE_SCRIPT = `
+const fs = require('fs');
+const [p, target] = [process.argv[1], process.argv[2]];
+try {
+  if (!fs.existsSync(p)) { console.log('revoke:no-store'); process.exit(0); }
+  const d = JSON.parse(fs.readFileSync(p, 'utf8'));
+  const before = (d.allowFrom || []).length;
+  d.allowFrom = (d.allowFrom || []).filter((e) => String(e) !== target);
+  if (d.allowFrom.length === before) { console.log('revoke:absent'); process.exit(0); }
+  fs.writeFileSync(p, JSON.stringify(d, null, 2), 'utf8');
+  console.log('revoke:ok');
+} catch (e) {
+  console.log('revoke:error ' + e.message);
+}
+`;
+
+/**
+ * Revoke an approved sender from the allowlist.
+ *
+ * There is no CLI for this. `openclaw pairing` exposes only `approve`, `list` and
+ * `help` — verified on both 2026.7.1-2 and 2026.9.3 — so the allowlist store has
+ * to be edited directly.
+ *
+ * The previous implementation tried `openclaw pairing revoke` first and treated
+ * any output that lacked "Unknown command" or "not found" as success. OpenClaw
+ * actually answers `OpenClaw does not know the command "revoke".`, which contains
+ * neither, so every revocation reported success, changed nothing, and never
+ * reached the fallback.
+ *
+ * On 2026.9.x this store moved into SQLite and the file is gone. Rather than
+ * silently doing nothing again, that case now fails loudly. Revocation against 9.x's SQLite store is not
+ * implemented yet.
+ */
 export function revokePairing(agentId: string, senderId: string, channel: string = 'telegram'): { success: boolean; error?: string } {
   const container = findContainerById(agentId);
   if (!container) return { success: false, error: `Agent container not found: ${agentId}` };
 
   try {
-    // Try native revoke command first, fall back to direct file manipulation
-    const nativeOut = containerExecNoFail(
-      container,
-      `openclaw pairing revoke ${channel} ${escapeShellArg(senderId)} 2>&1`,
-    );
-
-    if (nativeOut && !nativeOut.includes('Unknown command') && !nativeOut.includes('not found')) {
-      return { success: true };
-    }
+    // execFileSync, not a shell: argv is passed through untouched, so nothing in
+    // `senderId` can be read as syntax.
+    const out = execFileSync(
+      'docker',
+      ['exec', container, 'node', '-e', REVOKE_SCRIPT, pairingAllowFile(channel), senderId],
+      { encoding: 'utf-8', timeout: 15000, maxBuffer: 1024 * 1024 },
+    ).trim();
 
-    // Fallback: remove from credentials file directly
-    const filePath = pairingAllowFile(channel);
-    const fallbackOut = containerExecNoFail(
-      container,
-      `node -e "const p='${filePath}';try{const d=JSON.parse(require('fs').readFileSync(p,'utf8'));d.allowFrom=(d.allowFrom||[]).filter(e=>e!=='${senderId.replace(/'/g, "'\\''")}');require('fs').writeFileSync(p,JSON.stringify(d,null,2),'utf8')}catch(e){console.error('revoke fallback error:',e.message)}"`,
-    );
-    if (fallbackOut && fallbackOut.includes('revoke fallback error:')) {
-      return { success: false, error: fallbackOut };
+    if (out.includes('revoke:ok')) return { success: true };
+    if (out.includes('revoke:absent')) return { success: true }; // already gone — the desired state
+    if (out.includes('revoke:no-store')) {
+      return {
+        success: false,
+        error: 'No allowlist file in this container: nobody has been approved on this '
+             + 'channel yet, or the agent runs OpenClaw 9.x, whose pairing store is in '
+             + 'SQLite and cannot be revoked from here yet.',
+      };
     }
-
-    return { success: true };
+    return { success: false, error: out || 'revoke produced no output' };
   } catch (e) {
     return { success: false, error: (e as Error).message };
   }