@flame0510/project-aether 1.1.15 → 1.3.0

package/app/api/agents/[id]/recreate/route.ts

@@ -3,12 +3,13 @@ import { execSync } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
 import { resolveAgentedContainer, isValidAgentId } from '@/lib/container';
-import { buildRev4aProviderConfig } from '@/app/api/gateway/sync';
+import { patchRev4aProvider } from '@/app/api/gateway/sync';
 import { getMountFlags, applyRuntimeConfig } from '@/lib/agent-setup';
 import { requireAuthJWT } from '@/lib/rev4a-auth';
+import { waitForGatewayReady } from '@/lib/agent-readiness';
 
 export const dynamic = 'force-dynamic';
-export const maxDuration = 180; // docker run (60s) + health check (60s) + config patch (60s)
+export const maxDuration = 180; // docker run (60s) + startup wait (60s) + config patch (60s)
 
 const BACKUP_VOLUME = 'rev4a-backups';
 
@@ -20,23 +21,6 @@ function ts(): string {
   return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}_${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}${ms}`;
 }
 
-/**
- * Wait for the container gateway to respond on port 3000.
- */
-function waitForContainerReady(name: string, timeoutMs = 60000): boolean {
-  const start = Date.now();
-  while (Date.now() - start < timeoutMs) {
-    try {
-      execSync(
-        `docker exec ${name} sh -c 'curl -sf http://127.0.0.1:3000/health >/dev/null 2>&1 || wget -qO- http://127.0.0.1:3000/health >/dev/null 2>&1'`,
-        { timeout: 5000 },
-      );
-      return true;
-    } catch { /* not ready */ }
-    execSync('sleep 2', { timeout: 3000 });
-  }
-  return false;
-}
 
 /**
  * POST /api/agents/[id]/recreate
@@ -159,11 +143,11 @@ export async function POST(request: Request,
 
     execSync(cmd, { timeout: 60000, encoding: 'utf-8' });
 
-    // Wait for the new container to be healthy
-    const ready = waitForContainerReady(id);
+    // Wait for the new container to finish starting — /startupz, not /health
+    const ready = await waitForGatewayReady(id);
     if (!ready) {
       return NextResponse.json(
-        { success: false, error: 'Container started but gateway did not become healthy within 60s.' },
+        { success: false, error: 'Container started but its gateway did not finish starting within 60s.' },
         { status: 500 },
       );
     }
@@ -174,18 +158,10 @@ export async function POST(request: Request,
       applyRuntimeConfig(id);
 
       // Also guarantee models.providers.rev4a (host-dependent, not in base image)
-      const providerConfig = buildRev4aProviderConfig();
-      const providerJson = JSON.stringify({ models: { providers: { rev4a: providerConfig } } });
-      execSync(
-        `docker exec -i ${id} sh -c 'openclaw config patch --stdin'`,
-        { timeout: 15000, stdio: 'pipe', input: providerJson },
-      );
-
-      // No gateway restart: `config patch` reports "Change will apply without
-      // restarting the gateway" for a models-only patch, and the Gateway watches
-      // openclaw.json with gateway.reload defaulting to hybrid.
-    } catch {
-      // config patch is best-effort on recreate
+      patchRev4aProvider(id);
+    } catch (e) {
+      // best-effort on recreate, but a skipped patch must show up in the log
+      console.error('[agent:recreate] runtime config patch failed:', (e as Error).message);
     }
 
     return NextResponse.json({ success: true, name: id, image, network, backup: backupFile });

package/app/api/agents/[id]/route.ts

@@ -3,10 +3,11 @@ import { execSync } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
 import { resolveAgentedContainer, isValidAgentId } from '@/lib/container';
-import { buildRev4aProviderConfig } from '@/app/api/gateway/sync';
+import { patchRev4aProvider } from '@/app/api/gateway/sync';
 import { getMountFlags, applyRuntimeConfig } from '@/lib/agent-setup';
 import { DB_FILE } from '@/lib/rev4a-paths';
 import { requireAuthJWT } from '@/lib/rev4a-auth';
+import { waitForGatewayReady } from '@/lib/agent-readiness';
 
 const BACKUP_VOLUME = 'rev4a-backups';
 
@@ -86,21 +87,6 @@ export async function DELETE(request: Request,
   }
 }
 
-function waitForContainerReady(name: string, timeoutMs = 60000): boolean {
-  const start = Date.now();
-  while (Date.now() - start < timeoutMs) {
-    try {
-      execSync(
-        `docker exec ${name} sh -c 'curl -sf http://127.0.0.1:3000/health >/dev/null 2>&1 || wget -qO- http://127.0.0.1:3000/health >/dev/null 2>&1'`,
-        { timeout: 5000 },
-      );
-      return true;
-    } catch { /* not ready */ }
-    execSync('sleep 2', { timeout: 3000 });
-  }
-  return false;
-}
-
 function shellQuote(value: string): string {
   return `'${value.replace(/'/g, `'\\''`)}'`;
 }
@@ -247,11 +233,11 @@ export async function PATCH(
 
     execSync(cmd, { timeout: 60000, encoding: 'utf-8' });
 
-    // Wait for healthy
-    const ready = waitForContainerReady(id);
+    // Wait for startup to complete — /startupz, not /health
+    const ready = await waitForGatewayReady(id);
     if (!ready) {
       return NextResponse.json(
-        { error: 'Container started but gateway did not become healthy within 60s.' },
+        { error: 'Container started but its gateway did not finish starting within 60s.' },
         { status: 500 },
       );
     }
@@ -259,16 +245,11 @@ export async function PATCH(
     // Apply runtime config
     try {
       applyRuntimeConfig(id);
-      const providerConfig = buildRev4aProviderConfig();
-      const providerJson = JSON.stringify({ models: { providers: { rev4a: providerConfig } } });
-      execSync(
-        `docker exec -i ${id} sh -c 'openclaw config patch --stdin'`,
-        { timeout: 15000, stdio: 'pipe', input: providerJson },
-      );
-      // No gateway restart: `config patch` reports "Change will apply without
-      // restarting the gateway" for a models-only patch, and the Gateway watches
-      // openclaw.json with gateway.reload defaulting to hybrid.
-    } catch { /* non-fatal */ }
+      patchRev4aProvider(id);
+    } catch (e) {
+      // non-fatal, but a skipped patch must show up in the log
+      console.error('[agent:update] runtime config patch failed:', (e as Error).message);
+    }
 
     return NextResponse.json({
       success: true,

package/app/api/agents/create/route.ts

@@ -1,37 +1,15 @@
 import { NextResponse, type NextRequest } from 'next/server';
-import { execSync } from 'child_process';
+import { execSync, execFileSync } from 'child_process';
 import * as crypto from 'crypto';
 import * as fs from 'fs';
 import * as path from 'path';
-import { buildRev4aProviderConfig } from '../../gateway/sync';
+import { patchRev4aProvider } from '../../gateway/sync';
+import { extractProviderAndModel } from '@/app/api/provider/upstream';
 import { DB_FILE, AGENTS_TOKEN_FILE, PROVIDER_KEYS_FILE, templatesDir } from '@/lib/rev4a-paths';
 import { getMountFlags, applyRuntimeConfig } from '@/lib/agent-setup';
-import { loadModelsConfig } from '@/lib/model-catalogue';
+import { isModelOffered } from '@/lib/model-catalogue';
 import { requireAuthJWT } from '@/lib/rev4a-auth';
-
-/**
- * Wait for a Docker container gateway to be ready.
- * Checks that the gateway is responding on port 3000 inside the container.
- * Polls every 2s, gives up after timeoutMs.
- * Returns true if the gateway is reachable, false on timeout.
- */
-function waitForContainerReady(name: string, timeoutMs = 60000): boolean {
-  const start = Date.now();
-  while (Date.now() - start < timeoutMs) {
-    try {
-      execSync(
-        `docker exec ${name} sh -c 'curl -sf http://127.0.0.1:3000/health >/dev/null 2>&1 || wget -qO- http://127.0.0.1:3000/health >/dev/null 2>&1'`,
-        { timeout: 5000 },
-      );
-      return true;
-    } catch {
-      // gateway not ready yet
-    }
-    // Sleep 2s
-    execSync('sleep 2', { timeout: 3000 });
-  }
-  return false;
-}
+import { waitForGatewayReady } from '@/lib/agent-readiness';
 
 
 
@@ -107,12 +85,18 @@ function validatePortInput(input: string): { valid: true; isBlock: boolean; star
 }
 
 export const dynamic = 'force-dynamic';
-export const maxDuration = 180; // docker run (60s) + health check (60s) + seeding (60s)
+export const maxDuration = 180; // docker run (60s) + startup wait (60s) + seeding (60s)
 
 const TEMPLATES_DIR = templatesDir(process.cwd());
 const AGENTS_TOKEN_PATH = AGENTS_TOKEN_FILE;
 const DEFAULT_NETWORK = 'rev4a-network';
 
+/**
+ * Used when the request names no model. The full id: the agent cards compare the
+ * primary against catalogue ids, and the two-segment alias matches none of them.
+ */
+const DEFAULT_MODEL = 'rev4a/deepseek/deepseek-flash';
+
 function isDockerCompatibleName(name: string): boolean {
   return /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(name);
 }
@@ -191,9 +175,14 @@ export async function POST(request: NextRequest): Promise<NextResponse> {
     }
 
     // Validate model (if provided) exists in models.config.json
-    if (model && !isValidModel(model)) {
+    // A request without a model used to create an agent with no primary at all —
+    // the config write below was skipped — while the event log recorded a default
+    // the agent never had. The default is now applied for real, and validated like
+    // any other model, so it cannot produce an agent the proxy refuses.
+    const effectiveModel: string = typeof model === 'string' && model ? model : DEFAULT_MODEL;
+    if (!isValidModel(effectiveModel)) {
       return NextResponse.json(
-        { success: false, error: `Model '${model}' not found in models.config.json` },
+        { success: false, error: `Model '${effectiveModel}' is not offered by this deployment: it is not in the catalogue, is disabled, or its provider has no API key.` },
         { status: 400 },
       );
     }
@@ -248,6 +237,10 @@ export async function POST(request: NextRequest): Promise<NextResponse> {
       );
     }
 
+    // `rev4a serve` creates this network at start-up, but skips it when Docker was
+    // not ready yet; without it `docker run --network` fails. Idempotent.
+    ensureNetworkExists(network);
+
     // Every agent gets a host port range for direct access. The URL is composed
     // by the browser from `port` + `controlToken` in the response — only the
     // browser knows a hostname that actually reaches this machine.
@@ -310,7 +303,7 @@ export async function POST(request: NextRequest): Promise<NextResponse> {
           port: portStart,
           portEnd,
           isBlock,
-          model: model || 'rev4a/deepseek-v4-flash',
+          model: effectiveModel,
           fallbacks,
           containerId,
           containerName,
@@ -321,14 +314,14 @@ export async function POST(request: NextRequest): Promise<NextResponse> {
       // DB logging is optional, ignore failures
     }
 
-    // Wait for container to be ready (HTTP health check, up to 60s).
-    // If it doesn't come up, remove the container and return an error —
-    // a zombie agent with no config is worse than an explicit failure.
-    const ready = waitForContainerReady(containerName);
+    // Wait for startup to complete (/startupz, up to 60s). Not /health, which
+    // answers as soon as the HTTP server listens. If it does not come up, remove
+    // the container: a zombie agent with no config is worse than an explicit failure.
+    const ready = await waitForGatewayReady(containerName);
     if (!ready) {
       try { execSync(`docker rm -f ${containerName}`, { timeout: 10000 }); } catch { /* best-effort */ }
       return NextResponse.json(
-        { success: false, error: `Container started but gateway did not become healthy within 60s. Container removed — try again.` },
+        { success: false, error: `Container started but its gateway did not finish starting within 60s. Container removed — try again.` },
         { status: 500 },
       );
     }
@@ -388,11 +381,12 @@ export async function POST(request: NextRequest): Promise<NextResponse> {
       config.gateway = gatewaySection;
 
       // Model reference (primary + fallbacks)
-      if (model) {
-        const modelRef = model.startsWith('rev4a/') ? model : `rev4a/${model}`;
-        const fallbackRefs = (fallbacks || []).map((fb: string) =>
-          fb.startsWith('rev4a/') ? fb : `rev4a/${fb}`,
-        );
+      {
+        // Always the canonical `rev4a/<provider>/<model>`: the Agents chips and the
+        // Model panel look the primary up by catalogue id, so the alias form
+        // (`rev4a/deepseek-flash`) or a bare name would show as not in the catalogue.
+        const modelRef = toRev4aRef(effectiveModel);
+        const fallbackRefs = (fallbacks || []).map((fb: string) => toRev4aRef(fb));
         const agents = (config.agents || {}) as Record<string, unknown>;
         const defaults = (agents.defaults || {}) as Record<string, unknown>;
         defaults.model = {
@@ -434,19 +428,10 @@ export async function POST(request: NextRequest): Promise<NextResponse> {
     try {
       applyRuntimeConfig(containerName);
 
-      // Also guarantee models.providers.rev4a (host-dependent, not in base image)
-      const providerConfig = buildRev4aProviderConfig();
-      const providerJson = JSON.stringify({ models: { providers: { rev4a: providerConfig } } });
-      execSync(
-        `docker exec -i ${containerName} sh -c 'openclaw config patch --stdin'`,
-        { timeout: 15000, stdio: 'pipe', input: providerJson },
-      );
-
-      // No gateway restart: `config patch` reports "Change will apply without
-      // restarting the gateway" for a models-only patch, and the Gateway watches
-      // openclaw.json with gateway.reload defaulting to hybrid. The earlier
-      // restart in this route stays — that one follows a full-file rewrite that
-      // includes gateway.*, which is the one section that genuinely needs it.
+      // Also guarantee models.providers.rev4a (host-dependent, not in base image).
+      // This patch needs no restart; the earlier one follows a full-file rewrite
+      // that includes gateway.*, the one section that genuinely needs it.
+      patchRev4aProvider(containerName);
     } catch (e: unknown) {
       // runtime config patch is best-effort; log but don't fail the create
       console.error('[agent:create] runtime config patch failed:', (e as Error).message || String(e));
@@ -474,6 +459,12 @@ export async function POST(request: NextRequest): Promise<NextResponse> {
   }
 }
 
+/** `rev4a/<provider>/<model>`, whatever form the request used. */
+function toRev4aRef(modelId: string): string {
+  const { provider, model } = extractProviderAndModel({ model: modelId });
+  return `rev4a/${provider}/${model}`;
+}
+
 function getAvailableTemplates(): string[] {
   try {
     return fs.readdirSync(TEMPLATES_DIR).filter((f) => {
@@ -485,12 +476,23 @@ function getAvailableTemplates(): string[] {
   }
 }
 
+/**
+ * The model must be one this deployment offers, in any form the proxy accepts.
+ * Checking the raw catalogue let the API create an agent on a disabled model, or
+ * one whose provider has no key, which the proxy then refuses on its first turn.
+ */
 function isValidModel(modelId: string): boolean {
+  const { provider, model } = extractProviderAndModel({ model: modelId });
+  return isModelOffered(provider, model);
+}
+
+function ensureNetworkExists(name: string): void {
   try {
-    const config = loadModelsConfig();
-    return config.some((m) => m.id === modelId);
+    execFileSync('docker', ['network', 'inspect', name], { stdio: 'ignore', timeout: 5000 });
   } catch {
-    return true; // skip on errors
+    try {
+      execFileSync('docker', ['network', 'create', name], { stdio: 'ignore', timeout: 10000 });
+    } catch { /* let docker run report it */ }
   }
 }
 

package/app/api/agents/models-summary/route.ts

@@ -0,0 +1,163 @@
+/**
+ * GET /api/agents/models-summary
+ *
+ * One row per agent, running or not: which model it runs, and whether that model is in
+ * good standing. Feeds the model chip on the agent cards, so the list answers
+ * "what is this agent running, and is it fine?" without opening anything.
+ *
+ * That question had no cheap answer before: the model lived only inside each
+ * container's config, and the only route that read it walked the whole fleet.
+ * Three agents silently moved to DeepSeek V4.1, and one has been pointing at a
+ * model absent from its own catalogue, precisely because nothing surfaced it.
+ *
+ * Fan-out uses the NoFail variants: one unreachable container must degrade its
+ * own row, not blank the page. `mapWithConcurrency` is fail-fast, so a throwing
+ * mapper would discard every result already computed.
+ */
+import { NextResponse } from 'next/server';
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+import { dockerExecNoFail, mapWithConcurrency } from '@/lib/docker-exec';
+import { loadModelsConfig, loadOfferedModels } from '@/lib/model-catalogue';
+import { singleFileFromTar } from '@/lib/container-file';
+import { requireAuthJWT } from '@/lib/rev4a-auth';
+
+const execFileAsync = promisify(execFile);
+
+export const dynamic = 'force-dynamic';
+
+/** Matches the per-agent query cap used elsewhere for fleet walks. */
+const CONCURRENCY = 6;
+
+const CONFIG_PATH = '/root/.openclaw/openclaw.json';
+
+/** A not-running agent's config, through `docker cp`. Empty string when unreadable. */
+async function readNotRunningConfig(container: string): Promise<string> {
+  try {
+    const { stdout } = await execFileAsync('docker', ['cp', `${container}:${CONFIG_PATH}`, '-'], {
+      encoding: 'buffer', timeout: 8000, maxBuffer: 1024 * 1024,
+    });
+    return singleFileFromTar(stdout as unknown as Buffer).body.toString('utf-8');
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * - `missing`     the primary is not in the catalogue at all
+ * - `disabled`    in the catalogue but not offered: unchecked, or its provider has no key
+ * - `out-of-sync` offered by the gateway, absent from this container's synced copy
+ * - `deprecated`  works, on a name upstream has retired
+ */
+export type ModelHealth = 'ok' | 'deprecated' | 'missing' | 'disabled' | 'out-of-sync' | 'unset' | 'unknown';
+
+export interface AgentModelRow {
+  agentId: string;
+  containerName: string;
+  primary: string | null;
+  fallbackCount: number;
+  /** First fallback, for the one-line hint on the card. The rest stay in the panel. */
+  firstFallback: string | null;
+  health: ModelHealth;
+}
+
+export async function GET(request: Request): Promise<NextResponse> {
+  const denied = await requireAuthJWT(request);
+  if (denied) return denied as any;
+
+  let agents: { agentId: string; containerName: string; running: boolean }[] = [];
+  try {
+    // `-a`: a stopped agent is the likeliest to be sitting on a model that has
+    // since been removed or disabled, and it needs a chip as much as any.
+    const { stdout } = await execFileAsync(
+      'docker',
+      ['ps', '-a', '--filter', 'label=AGENT_ID', '--format', '{{.Label "AGENT_ID"}}\t{{.Names}}\t{{.State}}'],
+      { encoding: 'utf8', timeout: 5000 },
+    );
+    agents = stdout.trim().split('\n')
+      .map((line) => {
+        const [agentId, containerName, state] = line.split('\t');
+        if (!containerName?.trim()) return null;
+        return {
+          agentId: agentId?.trim() || containerName.trim(),
+          containerName: containerName.trim(),
+          running: state?.trim() === 'running',
+        };
+      })
+      .filter(Boolean) as { agentId: string; containerName: string; running: boolean }[];
+  } catch (e) {
+    // Not an empty list: that reads as "every agent is fine".
+    return NextResponse.json(
+      { agents: [], error: `Docker is unreachable: ${(e as Error).message.split('\n')[0]}` },
+      { status: 503 },
+    );
+  }
+
+  if (agents.length === 0) return NextResponse.json({ agents: [] });
+
+  // Deprecation is a property of the catalogue, not of the container: read it once.
+  const catalogue = new Map(loadModelsConfig().map((m) => [m.id, m]));
+  // What the gateway will actually serve. The proxy refuses anything outside it,
+  // so this set, not the container's copy, decides whether an agent can work.
+  const offered = new Set(loadOfferedModels().map((m) => m.id));
+
+  const rows = await mapWithConcurrency(agents, CONCURRENCY, async (agent): Promise<AgentModelRow> => {
+    const base: AgentModelRow = {
+      agentId: agent.agentId,
+      containerName: agent.containerName,
+      primary: null,
+      fallbackCount: 0,
+      firstFallback: null,
+      health: 'unknown',
+    };
+
+    const raw = agent.running
+      ? await dockerExecNoFail(agent.containerName, ['cat', CONFIG_PATH], { timeoutMs: 8000 })
+      : await readNotRunningConfig(agent.containerName);
+    // An empty body means unreachable *or* a read killed by the deadline —
+    // `docker exec` exits 0 either way, so both stay 'unknown' rather than
+    // being reported as a healthy agent with no model.
+    if (!raw) return base;
+
+    let config: Record<string, unknown>;
+    try { config = JSON.parse(raw); } catch { return base; }
+
+    const defaults = ((config.agents ?? {}) as Record<string, unknown>).defaults ?? {};
+    const model = (defaults as Record<string, unknown>).model;
+    const primary = typeof model === 'string'
+      ? model
+      : (model && typeof model === 'object' ? (model as Record<string, unknown>).primary : null);
+    const fallbacks = model && typeof model === 'object' && Array.isArray((model as Record<string, unknown>).fallbacks)
+      ? ((model as Record<string, unknown>).fallbacks as unknown[])
+      : [];
+
+    if (typeof primary !== 'string' || !primary) return { ...base, health: 'unset' };
+
+    const bare = primary.replace(/^rev4a\//, '');
+    const models = ((config.models ?? {}) as Record<string, unknown>).providers ?? {};
+    const rev4a = ((models as Record<string, unknown>).rev4a ?? {}) as Record<string, unknown>;
+    const ids = (Array.isArray(rev4a.models) ? rev4a.models : [])
+      .map((m) => (m && typeof m === 'object' ? (m as Record<string, unknown>).id : null))
+      .filter((id): id is string => typeof id === 'string');
+
+    const entry = catalogue.get(bare);
+    let health: ModelHealth;
+    // Ordered by remedy. Each case asks something different of the operator, and
+    // the single 'missing' this replaced pointed at the wrong fix half the time.
+    if (!entry) health = 'missing';                       // gone from the catalogue: pick another model
+    else if (!offered.has(bare)) health = 'disabled';     // exists, not offered: the proxy refuses it
+    else if (!ids.includes(bare)) health = 'out-of-sync'; // offered, never reached this container: Sync All
+    else if (entry.deprecated) health = 'deprecated';     // works, on a retired name
+    else health = 'ok';
+
+    return {
+      ...base,
+      primary,
+      fallbackCount: fallbacks.length,
+      firstFallback: typeof fallbacks[0] === 'string' ? (fallbacks[0] as string) : null,
+      health,
+    };
+  });
+
+  return NextResponse.json({ agents: rows });
+}

package/app/api/assistant/route.ts

@@ -2,8 +2,11 @@ import { NextResponse, type NextRequest } from 'next/server';
 import { readProviderKeys } from '@/app/api/gateway/provider/keys';
 import { extractProviderAndModel, getApiKey, callUpstream } from '@/app/api/provider/upstream';
 import { requireAuthJWT } from '@/lib/rev4a-auth';
+import { isModelOffered, loadOfferedModels } from '@/lib/model-catalogue';
 
-const FALLBACK_MODEL = 'deepseek/deepseek-v4-flash';
+// DeepSeek Flash (V4.1). Used only when the client names no model, and refused
+// like any other if it has been unchecked on the Gateway page.
+const FALLBACK_MODEL = 'deepseek/deepseek-flash';
 
 interface PageContext {
   title: string;
@@ -15,27 +18,27 @@ interface PageContext {
 const PAGE_CONTEXT: Record<string, PageContext> = {
   '/': {
     title: 'Dashboard',
-    description: 'Main overview with live session list, cost summary (today, 7 days, 30 days by model), system health metrics (CPU, RAM, disk, load), and a real-time event feed.',
+    description: 'Main overview with live session list, cost summary by model, health cards for Rev4a\'s own runtime, cron and lineage, and a real-time event feed. It shows no CPU, RAM, disk or load average: those are collected by the daemon but no page displays them.',
     actions: ['Click any session row to open the Session Drawer for full details and tool call history', 'View cost breakdown by model and time period', 'See live events as they happen', 'Take a screenshot of the dashboard (mobile)'],
     hints: 'The Session Drawer shows you the complete tool call history for any session — just click a row.',
   },
   '/agents': {
     title: 'Agents',
     description: 'List of all Docker containers that run OpenClaw agents. Shows status (running/exited/paused), image, ports, IP, and creation time. Includes a top banner for the agent base image status: yellow warning when outdated or missing, animated progress bar when downloading from registry.',
-    actions: ['Filter by status: all, running, or exited', 'Click an agent to see its details (environment variables, auth token, Traefik URL)', 'Create a new agent using the "Create Agent" button', 'Download the agent base image when the banner shows it missing or outdated'],
+    actions: ['Filter by status: all, running, or exited', 'Click an agent to see its details (environment variables, auth token, backups, Telegram channels, and the Model section that sets its primary model and fallbacks)', 'Create a new agent using the "Create Agent" button', 'Download the agent base image when the banner shows it missing or outdated'],
     hints: 'The status bullet tells you at a glance if an agent is running (green), exited (red), or paused (yellow). The base image banner shows when an updated version is available on the registry — download to pick up CLI updates.',
   },
   '/agents/create': {
     title: 'Create Agent',
-    description: 'Wizard to create a new agent from a template. Choose a template, give it a name, select a model, set environment variables, and configure optional Traefik routing.',
-    actions: ['Browse available agent templates', 'Name your agent and select its AI model', 'Add environment variables (KEY=*** pairs)', 'Optionally enable Traefik routing with a custom subdomain', 'Create the agent and start it immediately'],
-    hints: 'Templates provide pre-built agent configurations. You can customize the image, model, and env vars after selecting a template.',
+    description: 'Two-step wizard to create a new agent from a template. Pick a template, then name it and optionally set a port range and a model.',
+    actions: ['Browse available agent templates', 'Name your agent and select its AI model', 'Set an optional port range (auto-assigned by default)', 'Create the agent and start it immediately'],
+    hints: 'Templates provide pre-built agent configurations. The model can be changed later from the agent\'s detail panel on the Agents page.',
   },
   '/gateway': {
     title: 'Gateway',
-    description: 'Central gateway management page. Shows OpenClaw gateway status, all configured AI providers with their models, and each agent\'s model assignment with fallback models.',
-    actions: ['Toggle models on/off per provider to control availability', 'View which model each agent uses as default', 'See fallback models configured for each agent', 'Check gateway health status and last sync time', 'Sync providers from the gateway configuration'],
-    hints: 'The Gateway is the routing layer that connects agents to AI providers. Use this page to manage which models agents can access.',
+    description: 'Provider configuration: API keys, and which catalogue models this deployment offers. It does not assign models to agents.',
+    actions: ['Add, change or remove a provider API key', 'Toggle individual models on or off to control what the fleet is offered', 'Push the resulting catalogue to every agent container with Sync All Agents'],
+    hints: 'Unchecking a model here removes it everywhere, including for requests that name it directly. To change which model one agent runs, open that agent on the Agents page and use the Model section.',
   },
   '/crons': {
     title: 'Crons',
@@ -45,8 +48,8 @@ const PAGE_CONTEXT: Record<string, PageContext> = {
   },
   '/containers': {
     title: 'Containers',
-    description: 'List of all Docker containers running on the server (not just agents). Shows container ID, name, image, status, state, ports, and IP address.',
-    actions: ['View all running containers with their details', 'Click "Terminal" on any container to open an interactive shell', 'Monitor container status and resource usage'],
+    description: 'List of all Docker containers on the server, running or stopped (not just agents). Shows container ID, name, image, status, state, ports, and IP address.',
+    actions: ['View every container, running or stopped, with its details', 'Click "Terminal" on any container to open an interactive shell', 'Check each container\'s status, image, IP and ports (no CPU or memory figures are shown)'],
     hints: 'Containers marked with an agentId belong to OpenClaw agents. Others are infrastructure containers like databases or reverse proxies.',
   },
   '/containers/terminal/[id]': {
@@ -64,7 +67,7 @@ const PAGE_CONTEXT: Record<string, PageContext> = {
   '/lineage': {
     title: 'Lineage',
     description: 'Interactive graph showing parent-child relationships between agent sessions. Each node is a session, edges show who spawned whom.',
-    actions: ['View the session hierarchy tree', 'Select a time period (1d/7d/30d) to filter the view', 'Click any session node to inspect its details', 'Zoom and pan through the graph'],
+    actions: ['View the session hierarchy tree', 'Select a time period (1d, 3d, 7d, 15d, 30d or all) to filter the view', 'Click any session node to inspect its details', 'Zoom and pan through the graph'],
     hints: 'When an agent spawns a child agent to do work, that relationship is shown here. Use the period selector to see recent activity.',
   },
   '/memory': {
@@ -81,9 +84,9 @@ const PAGE_CONTEXT: Record<string, PageContext> = {
   },
   '/tools': {
     title: 'Tools',
-    description: 'Catalog of all tools available to agents — built-in tools, MCP (Model Context Protocol) tools, plugin tools, and audio transcription tools.',
-    actions: ['Browse the full tool catalog', 'See tool name, source package, and description', 'View audio/voice configuration settings', 'Check which MCP servers are connected'],
-    hints: 'Each tool has a source (built-in, plugin, or MCP server). If a tool is missing, check the relevant plugin or MCP connection.',
+    description: 'Curated catalog of the OpenClaw built-in tools available to agents, grouped by area, plus audio and timezone settings. It does not list MCP servers or plugin tools.',
+    actions: ['Browse the full tool catalog', 'See each tool\'s name, description and status (Configured, Available, Coming soon)', 'View the audio transcription and time zone settings'],
+    hints: 'The catalog is a fixed list of OpenClaw built-in tools, not read from the agents. It shows no MCP servers or plugin tools, so a tool missing here says nothing about what an agent has.',
   },
   '/plugins': {
     title: 'Plugins',
@@ -177,6 +180,24 @@ export async function POST(request: NextRequest): Promise<Response> {
   ];
 
   const { provider, model: upstreamModel } = extractProviderAndModel({ model: effectiveModel });
+
+  // The chat panel loads its model list once, at mount, and keeps the choice in
+  // localStorage — so it can name a model that was unchecked on the Gateway page
+  // an hour ago, or one already gone when the preference was saved. Enforce the
+  // catalogue here rather than trusting the client to hold a current list.
+  if (!isModelOffered(provider, upstreamModel)) {
+    const alternative = loadOfferedModels()[0];
+    return NextResponse.json(
+      {
+        error: `Model '${provider}/${upstreamModel}' is not enabled for this deployment.`
+             + (alternative
+                 ? ` Try ${alternative.id}, or enable it on the Gateway page.`
+                 : ' No model is currently enabled — check the Gateway page.'),
+      },
+      { status: 400 },
+    );
+  }
+
   const providerKeys = readProviderKeys();
   const apiKey = getApiKey(provider, providerKeys);
 

package/app/api/credentials/[id]/sync/route.ts

@@ -1,5 +1,5 @@
 import { NextResponse } from 'next/server';
-import { getProfile, markSynced } from '@/lib/credentials/vault';
+import { getProfile, markSynced, markDesynced } from '@/lib/credentials/vault';
 import { syncProfileToAgents, cleanAgentProviders } from '@/lib/credentials/delivery';
 import { requireAuthJWT } from '@/lib/rev4a-auth';
 
@@ -48,8 +48,8 @@ export async function DELETE(request: Request,
       return NextResponse.json({ error: 'container is required' }, { status: 400 });
     }
 
-    cleanAgentProviders(container, profile.providerId);
-    markSynced(id, 'active');
+    await cleanAgentProviders(container, profile.providerId);
+    markDesynced(id);
 
     return NextResponse.json({ ok: true });
   } catch (e: unknown) {