@flame0510/project-aether 1.1.12 → 1.1.14

package/docs/REV4A.md

@@ -1,6 +1,6 @@
 # Rev4a — VPS Dashboard
 
-> **Last updated:** 2026-07-27
+> **Last updated:** 2026-08-09
 
 A Next.js 16 dashboard for monitoring and managing the OpenClaw ecosystem.
 
@@ -52,15 +52,24 @@ A Next.js 16 dashboard for monitoring and managing the OpenClaw ecosystem.
 
 ### Environment
 
-Rev4a reads the following environment variables. Set them in `/config` (UI) or directly in `.env`.
+Rev4a reads the following environment variables. Set them in `/config` (UI) or directly in `.env`. See [.env.example](../.env.example) for the canonical, always-current list.
 
 | Variable | Required | Description |
 |---|---|---|
 | `REV4A_PASSWORD` | Yes | Login password for the dashboard |
 | `REV4A_TOKEN` | Yes | Token used for programmatic API access |
 | `REV4A_JWT_SECRET` | Yes | Secret used to sign session JWT tokens |
-| `REV4A_DB` | No | Path to the events database (default: `data/events.db`) |
+| `REV4A_API_KEY` | No | API key for the Gateway provider endpoint (auto-generated) |
+| `GATEWAY_TOKEN` | No | Shared token handed to agent containers |
+| `REV4A_DATA_DIR` | No | Root of all persistent data (default: `~/.config/rev4a`) |
+| `REV4A_DB` | No | Path to the events database (default: `<data dir>/data/events.db`) |
+| `REV4A_CREDENTIALS_DB` | No | Path to the credentials vault database |
 | `REV4A_WORKSPACE_ROOT` | No | Filesystem path for the local file explorer |
+| `REV4A_ROOT` | No | Installation root, used by `rev4a update` to detect a git checkout |
+| `REV4A_TIMEZONE` | No | IANA timezone used for scheduling and timestamps |
+| `REV4A_FORCE_INSECURE_COOKIE` | No | Allow a non-Secure session cookie — plain-HTTP deployments only |
+
+See [Alerts](#alerts-telegram) below for the Telegram alert variables.
 
 ## Agent creation
 
@@ -138,6 +147,29 @@ REV4A_JWT_SECRET=***  # Secret for signing JWTs
 
 ---
 
+## Alerts (Telegram)
+
+Rev4a can send Telegram alerts when the events database goes stale (no
+recent writes — see `/api/system-health`). Implemented in `lib/alerts.ts`.
+
+**Env vars:**
+```
+REV4A_ALERTS_ENABLED=false        # Master switch — no alerts sent unless "true"
+REV4A_TELEGRAM_BOT_TOKEN=         # Telegram bot token
+REV4A_TELEGRAM_CHAT_ID=           # Telegram chat to notify
+REV4A_ALERT_COOLDOWN_MS=600000    # Minimum time between repeat alerts for the same condition
+REV4A_ALERT_STALE_SECONDS=120     # How long without a DB write before the system is considered stale
+REV4A_ALERT_SMOKE=false           # Set true to send a one-off test alert on startup
+```
+
+**Behavior:**
+- If `REV4A_ALERTS_ENABLED` is not `"true"`, `maybeSendAlert` is a no-op — nothing is sent, nothing is recorded.
+- If enabled but `REV4A_TELEGRAM_BOT_TOKEN` or `REV4A_TELEGRAM_CHAT_ID` is missing, alerts run in **dry-run**: state transitions are still recorded in the `alert_state` table (SQLite), but no Telegram message is sent — visible in server logs as `[alerts] dry-run`.
+- Alert state (`ok` / `alerted` / `resolved`) is tracked per `alert_key` in `alert_state`, so a resolved condition sends a follow-up "✅ resolved" message instead of staying silent.
+- `REV4A_ALERT_COOLDOWN_MS` prevents repeat-sending the same stale alert while the condition persists.
+
+---
+
 ## Service Management
 
 ```bash
@@ -167,8 +199,6 @@ Environment=REV4A_PASSWORD=***
 Environment=REV4A_TOKEN=***
 Environment=REV4A_JWT_SECRET=***
 Environment=REV4A_DB=/path/to/rev4a/data/events.db
-Environment=OPENCLAW_CONFIG_PATH=/path/to/openclaw-core.json
-Environment=SHARED_CONTEXT_DIR=/path/to/shared-context
 Environment=NODE_ENV=production
 Environment=NEXT_TELEMETRY_DISABLED=1
 ```
@@ -498,7 +528,7 @@ curl -b /tmp/cookies.txt -X PUT http://localhost:3740/api/workspace \
 ├── public/                  # Static assets
 ├── scripts/                 # Utility scripts (setup, helpers)
 ├── .env                     # Local env vars (gitignored)
-├── proxy.ts                  # Auth proxy
+├── proxy.ts                    # Auth gate — redirects to /login without a valid JWT cookie
 ├── next.config.mjs
 └── package.json
 ```

package/docs/dev/API-REFERENCE.md

@@ -197,6 +197,11 @@ Returns current provider configuration state.
 
 **Auth:** any auth method
 
+**Query params:**
+| Param | Effect |
+|---|---|
+| `summary=1` | Returns only `{ provider, label, configured }` per provider — no `models`, no `pricing`, no `apiKey`. The full response awaits live pricing from OpenRouter, a network round trip costing ~2.4s on a cold cache; callers that only need to know whether *any* provider is configured should use this. |
+
 **Response:**
 ```json
 {
@@ -543,9 +548,9 @@ List running agent containers (Docker containers with `AGENT_ID` label) with ful
     "ports": "",
     "ip": "172.19.0.5",
     "created": "2026-07-01T16:58:42.876829416Z",
-    "env": ["AGENT_ID=prometheus", "AGENT_HOSTNAME=<agent-name>.<your-domain>.com"],
+    "env": ["AGENT_ID=prometheus", "AGENT_TEMPLATE=prometheus"],
     "authToken": "***",
-    "traefikUrl": "http://187.77.156.41:3033#token=asdfghjkl"
+    "controlPort": "3033"
   }
 ]
 
@@ -584,7 +589,7 @@ Create a new agent container from a template.
 **Every agent is created with a host port mapping:**
 - Port block: `-p <start>-<end>:3000-<3000+offset>` — maps a range of host ports to the same range starting at container port 3000
 - Single port: `-p <port>:3000` — maps a single host port to container port 3000
-- URL format: `http://<host-ip>:<portStart>#token=...`
+- Control UI URL: composed by the browser as `http://<window.location.hostname>:<port>#token=<controlToken>` — the server returns the parts, not the URL
 - Port 3740 is reserved for Rev4a
 
 **Response:**
@@ -595,7 +600,7 @@ Create a new agent container from a template.
   "name": "my-agent",
   "image": "openclaw-agent-base:latest",
   "network": "rev4a-network",
-  "traefikUrl": "http://187.77.156.41:3700#token=asdfghjkl",
+  "controlToken": "asdfghjkl",
   "port": 3700,
   "portEnd": 3709,
   "isBlock": true,
@@ -1562,7 +1567,7 @@ Enable or disable a plugin.
 ## Skills
 
 Skill discovery across three sources:
-- **Shared:** skills in `/docker/shared-skills` on the VPS host (global, available to all agents)
+- **Shared:** skills in `~/.config/rev4a/shared/shared-skills` on the VPS host (global, available to all agents)
 - **Workspace:** skills in `<workspace>/skills` inside each agent container (discovered via `docker exec`)
 - **Bundled:** skills shipped with OpenClaw (read-only)
 
@@ -1578,8 +1583,8 @@ List all available skills from all sources.
     {
       "name": "code-review",
       "type": "shared",
-      "path": "/docker/shared-skills/code-review",
-      "skillMdPath": "/docker/shared-skills/code-review/SKILL.md",
+      "path": "~/.config/rev4a/shared/shared-skills/code-review",
+      "skillMdPath": "~/.config/rev4a/shared/shared-skills/code-review/SKILL.md",
       "hasSkillMd": true,
       "description": "Systematic code review patterns...",
       "version": "1.0"
@@ -1643,7 +1648,7 @@ Copy a skill from an agent's workspace to the shared skills directory, making it
   "skillName": "my-custom-skill",
   "agentId": "atlas",
   "containerName": "openclaw-atlas",
-  "destPath": "/docker/shared-skills/my-custom-skill",
+  "destPath": "~/.config/rev4a/shared/shared-skills/my-custom-skill",
   "overwritten": false,
   "extraCopied": 0
 }

package/docs/dev/GATEWAY.md

@@ -227,6 +227,11 @@ Updates model config for a single agent container (primary model only).
 
 Returns current provider configuration state.
 
+Add `?summary=1` for a cheap variant — `{ provider, label, configured }` only,
+skipping the live-pricing fetch. Used by the agents page, which needs nothing
+more than "is any provider configured" and shouldn't block on a network call to
+OpenRouter to find out.
+
 **Response:**
 ```json
 {
@@ -237,13 +242,49 @@ Returns current provider configuration state.
       "configured": true,
       "baseUrl": "https://api.deepseek.com",
       "models": [
-        { "id": "deepseek/deepseek-v4-flash", "name": "DeepSeek V4 Flash", "enabled": true }
+        {
+          "id": "deepseek/deepseek-v4-flash",
+          "name": "DeepSeek V4 Flash",
+          "enabled": true,
+          "pricing": { "input": 0.05, "output": 0.10 },
+          "pricingLive": true,
+          "modality": "text->text"
+        }
       ]
     }
   ]
 }
 ```
 
+`pricing` is USD per 1M tokens. `-1 / -1` means the model routes dynamically
+(OpenRouter Auto) — the UI renders "Dynamic" and shows "varies" for
+capabilities rather than concrete icons.
+
+#### Live pricing
+
+`model-pricing.json` is maintained by hand and drifts — 16 of 79 OpenRouter
+entries were wrong when this was added, one understating the real cost ~8x.
+`lib/openrouter-pricing.ts` overlays the live catalogue on top of it and sets
+`pricingLive: true` on the models it covers, which the UI marks with a `LIVE`
+pill.
+
+- Endpoint: `GET https://openrouter.ai/api/v1/models` — public, no API key,
+  CDN-cached, never billed.
+- Scope: **only** models whose provider is `openrouter`. The same model sold
+  direct (openai, anthropic, google…) has different rates, so applying
+  OpenRouter's price there would show the wrong vendor's number.
+- Cache mirrors what the endpoint itself declares: `max-age=300` for
+  freshness, `stale-if-error=3600` as the upper bound past which a stale
+  entry is dropped in favour of the static file. Failures back off for a
+  minute instead of retrying on every request.
+- Skipped entirely when OpenRouter isn't configured, so callers that only
+  read `configured` (the agents page) don't wait on a network round trip.
+- `modality` is **not** taken from upstream. `sync.ts` provisions agent
+  containers from the curated `models.config.json` value, so a different
+  capability set in the UI would advertise inputs the container never
+  accepted. (`moonshotai/kimi-k3` currently differs: `text+image` curated
+  vs `text+image+video` upstream.)
+
 ---
 
 ## Config Page (`/config`)

package/docs/dev/PROVIDERS.md

@@ -218,9 +218,10 @@ Key points:
 
 ## Security Notes
 
-- The `GET /api/vault/provider/key` endpoint is protected by the authentication
-  middleware (browser cookie or bearer token). Only authenticated users can reveal
-  keys.
+- The `GET /api/vault/provider/key` endpoint calls `requireAuthJWT` directly
+  (browser cookie or bearer token) — API routes are never covered by `proxy.ts`
+  (it explicitly exempts `/api/*`), so each route must guard itself. Only
+  authenticated users can reveal keys.
 - The UI **must never** log, screenshot, or otherwise persist the revealed key
   outside the active screen view.
 - All secrets in documentation, logs, or reports must be masked (e.g. `sk-...ast4`).

package/docs/rag/REV4A-OVERVIEW.md

@@ -87,7 +87,7 @@ Browse installed OpenClaw plugins. Enable/disable toggle per plugin. Plugins ext
 
 ### Skills (`/skills`)
 Skill registry showing all skills across three sources:
-- **Shared** — global skills from `/docker/shared-skills`, available to all agents
+- **Shared** — global skills from `~/.config/rev4a/shared/shared-skills`, available to all agents
 - **Per-agent** — skills in each agent's workspace (`<workspace>/skills`), shown with agent label
 - **Bundled** — skills shipped with OpenClaw (read-only)
 

package/instrumentation.ts

@@ -0,0 +1,18 @@
+/**
+ * Next.js instrumentation hook — runs once at server startup.
+ *
+ * Syncs the provider gateway baseUrl to all agent containers on boot.
+ * This ensures agents pick up any domain/env changes after a restart,
+ * VPS reboot, or crash recovery — no manual Sync button needed.
+ */
+export async function register() {
+  if (process.env.NEXT_RUNTIME === 'nodejs') {
+    try {
+      const { syncAllAgents } = await import('./app/api/gateway/sync');
+      syncAllAgents();
+    } catch {
+      // Best-effort — don't block startup if sync fails
+      console.warn('[rev4a] Failed to sync agents on startup');
+    }
+  }
+}

package/lib/agent-setup.ts

@@ -10,6 +10,7 @@
 
 import { execSync } from 'child_process';
 import * as fs from 'fs';
+import { SHARED_SKILLS_DIR, REV4A_RULES_DIR } from '@/lib/rev4a-paths';
 
 // ── Volumes ──────────────────────────────────────────────────────────────────
 
@@ -28,12 +29,12 @@ export interface Rev4aVolume {
  */
 export const REV4A_VOLUMES: Rev4aVolume[] = [
   {
-    source: '/docker/shared-skills',
+    source: SHARED_SKILLS_DIR,
     target: '/data/.openclaw/shared-skills',
     mode: 'ro',
   },
   {
-    source: '/docker/rev4a-rules',
+    source: REV4A_RULES_DIR,
     target: '/root/.openclaw/workspace/.rev4a',
     mode: 'ro',
   },
@@ -60,14 +61,12 @@ export function getMountFlags(): string[] {
  * multiple times.
  */
 export function ensureHostDirs(): void {
+  // Plain mkdir: these now live under the user's own data directory, so no
+  // elevation is needed. The previous `sudo mkdir` with a plain fallback was
+  // only required because the paths sat at the filesystem root, and it could
+  // hang on a password prompt when run non-interactively.
   for (const vol of REV4A_VOLUMES) {
-    if (!fs.existsSync(vol.source)) {
-      try {
-        execSync(`sudo mkdir -p ${escapeShell(vol.source)}`, { stdio: 'pipe' });
-      } catch {
-        execSync(`mkdir -p ${escapeShell(vol.source)}`, { stdio: 'pipe' });
-      }
-    }
+    fs.mkdirSync(vol.source, { recursive: true });
   }
 }
 

package/lib/buildAgentImage.ts

@@ -193,7 +193,11 @@ async function pullFromRegistry(
 
     child.on('error', (err: Error) => {
       appendLog(`Pull process error: ${err.message}`);
-      releaseLock();
+      // Do NOT release the lock here: the caller falls through to
+      // localBuild(), which must stay protected. Releasing early let a
+      // concurrent request past getIsDownloading() and start a second
+      // `docker build` against the same tag. The lock is released by
+      // localBuild's own close/error handlers, or by the success path.
       resolve(false);
     });
   });

package/lib/channelManager.ts

@@ -97,6 +97,28 @@ function findContainerById(agentId: string): string | null {
 
 // ── Public API ───────────────────────────────
 
+/**
+ * Read the Telegram channel out of an already-parsed openclaw.json.
+ *
+ * Pure — no container access — so callers that have obtained the config some
+ * other way (in bulk, asynchronously) can share the same interpretation instead
+ * of reimplementing it.
+ */
+export function parseTelegramChannel(config: Record<string, unknown>): TelegramChannel | null {
+  const telegram = (config.channels as Record<string, unknown>)?.telegram as Record<string, unknown> | undefined;
+  if (!telegram || telegram.enabled === false) return null;
+
+  const botToken = (telegram.botToken ?? '') as string;
+  if (typeof botToken !== 'string' || botToken.length === 0) return null;
+
+  return {
+    connected: true,
+    botToken: maskToken(botToken),
+    dmPolicy: (telegram.dmPolicy ?? 'pairing') as string,
+    allowFrom: (Array.isArray(telegram.allowFrom) ? telegram.allowFrom : []) as string[],
+  };
+}
+
 export function getChannels(agentId: string): AgentChannels {
   const container = findContainerById(agentId);
   const result: AgentChannels = { agentId, telegram: null };
@@ -106,22 +128,7 @@ export function getChannels(agentId: string): AgentChannels {
   const config = readConfigJson(container);
   if (!config) return result;
 
-  // ── Telegram ──
-  const telegram = (config.channels as Record<string, unknown>)?.telegram as Record<string, unknown> | undefined;
-  if (telegram && telegram.enabled !== false) {
-    const botToken = (telegram.botToken ?? '') as string;
-    const hasToken = typeof botToken === 'string' && botToken.length > 0;
-
-    if (hasToken) {
-      result.telegram = {
-        connected: true,
-        botToken: maskToken(botToken),
-        dmPolicy: (telegram.dmPolicy ?? 'pairing') as string,
-        allowFrom: (Array.isArray(telegram.allowFrom) ? telegram.allowFrom : []) as string[],
-      };
-    }
-  }
-
+  result.telegram = parseTelegramChannel(config);
   return result;
 }
 

package/lib/db.ts

@@ -1,19 +1,9 @@
 // Shared DB helpers for API routes
 import Database from 'better-sqlite3';
-import type { NextRequest } from 'next/server';
-import { NextResponse } from 'next/server';
 import { initializeRev4aDb } from './db-bootstrap.mjs';
 import { DB_FILE } from './rev4a-paths';
 
 export const DB_PATH = process.env.REV4A_DB || DB_FILE;
-export const TOKEN = process.env.REV4A_TOKEN ?? '';
-
-export function requireAuth(request: NextRequest): NextResponse | null {
-  const token = new URL(request.url).searchParams.get('token');
-  const auth = request.headers.get('authorization');
-  const ok = token === TOKEN || auth === `Bearer ${TOKEN}`;
-  return ok ? null : NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
-}
 
 export function ensureDbReady(): void {
   initializeRev4aDb(DB_PATH);

package/lib/docker-exec.ts

@@ -0,0 +1,195 @@
+/**
+ * Running commands inside agent containers, without blocking the server.
+ *
+ * Every route that needed something from a container used to call `execSync` or
+ * `execFileSync` directly. Those are synchronous: while one runs, Node's single
+ * thread does nothing else — no other request is served, no agent's stream
+ * advances. Node's own guidance names `execSync` in a server as a
+ * denial-of-service vector, and the numbers here bear that out: a bare
+ * `docker exec … echo` costs ~260ms, and the OpenClaw CLI inside a container
+ * takes 2.5–6s per invocation because it boots a whole Node process.
+ *
+ * Routes that walk every agent multiplied that: `/api/crons` measured 19.2s on a
+ * seven-agent host, all of it with the event loop frozen.
+ *
+ * Everything here is async. The commands are still as slow as they were — that
+ * cost belongs to the OpenClaw CLI — but they no longer stop the rest of the
+ * server while they run.
+ */
+import { execFile, spawn } from 'child_process';
+import { promisify } from 'util';
+import { resolveDockerSocket } from '@/lib/docker-socket';
+
+const execFileAsync = promisify(execFile);
+
+/** Commands are expected to answer quickly; the OpenClaw CLI needs the headroom. */
+const DEFAULT_TIMEOUT_MS = 15_000;
+
+/** Matches what the previous callers passed, and covers `openclaw models list --json`. */
+const DEFAULT_MAX_BUFFER = 1024 * 1024;
+
+export interface DockerExecOptions {
+  timeoutMs?: number;
+  /** Extra environment for the command, passed as `-e KEY=VALUE`. */
+  env?: Record<string, string>;
+  maxBuffer?: number;
+  signal?: AbortSignal;
+}
+
+function baseArgs(container: string, opts?: DockerExecOptions): string[] {
+  const args = ['exec'];
+  for (const [k, v] of Object.entries(opts?.env ?? {})) args.push('-e', `${k}=${v}`);
+  args.push(container);
+  return args;
+}
+
+/**
+ * Run a command inside a container, passing argv directly.
+ *
+ * Prefer this over {@link dockerExecShell}: with no shell in between there is
+ * nothing to quote and nothing to escape, so a filename with a space or a quote
+ * cannot turn into a second command.
+ *
+ * Rejects when the command fails, the container is missing, or the timeout hits.
+ */
+export async function dockerExec(
+  container: string,
+  argv: string[],
+  opts?: DockerExecOptions,
+): Promise<string> {
+  if (!resolveDockerSocket()) throw new Error('Docker is not available');
+
+  const { stdout } = await execFileAsync(
+    'docker',
+    [...baseArgs(container, opts), ...argv],
+    {
+      encoding: 'utf-8',
+      timeout: opts?.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+      maxBuffer: opts?.maxBuffer ?? DEFAULT_MAX_BUFFER,
+      signal: opts?.signal,
+    },
+  );
+  return stdout;
+}
+
+/**
+ * Run a shell command inside a container. Only for commands that genuinely need
+ * a shell — pipes, redirection, globbing. Anything interpolated into `cmd` is
+ * shell syntax, so callers must quote it themselves.
+ */
+export async function dockerExecShell(
+  container: string,
+  cmd: string,
+  opts?: DockerExecOptions,
+): Promise<string> {
+  return dockerExec(container, ['sh', '-c', cmd], opts);
+}
+
+/**
+ * As {@link dockerExec}, but resolves to '' instead of rejecting.
+ *
+ * This is the shape most of the existing callers want: a container that is
+ * stopped, or an OpenClaw subcommand that isn't available on that agent, is a
+ * normal condition here — not something to fail a whole page over.
+ */
+export async function dockerExecNoFail(
+  container: string,
+  argv: string[],
+  opts?: DockerExecOptions,
+): Promise<string> {
+  try {
+    return await dockerExec(container, argv, opts);
+  } catch {
+    return '';
+  }
+}
+
+/** Shell variant of {@link dockerExecNoFail}. */
+export async function dockerExecShellNoFail(
+  container: string,
+  cmd: string,
+  opts?: DockerExecOptions,
+): Promise<string> {
+  return dockerExecNoFail(container, ['sh', '-c', cmd], opts);
+}
+
+/**
+ * Run a command inside a container and write `input` to its stdin.
+ *
+ * This uses `spawn` rather than `execFile` on purpose: `promisify(exec)` and
+ * `promisify(execFile)` silently ignore an `input` option — the process starts,
+ * stdin is never written, and the command hangs or reads nothing, with no error
+ * to point at. `openclaw config patch --stdin` is the case that needs this.
+ */
+export function dockerExecWithInput(
+  container: string,
+  argv: string[],
+  input: string,
+  opts?: DockerExecOptions,
+): Promise<string> {
+  if (!resolveDockerSocket()) return Promise.reject(new Error('Docker is not available'));
+
+  return new Promise((resolve, reject) => {
+    const child = spawn('docker', ['exec', '-i', ...baseArgs(container, opts).slice(1), ...argv], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+
+    let stdout = '';
+    let stderr = '';
+    const timer = setTimeout(() => {
+      child.kill('SIGKILL');
+      reject(new Error(`docker exec timed out after ${opts?.timeoutMs ?? DEFAULT_TIMEOUT_MS}ms`));
+    }, opts?.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+
+    child.stdout.on('data', (c) => { stdout += c; });
+    child.stderr.on('data', (c) => { stderr += c; });
+    child.on('error', (err) => { clearTimeout(timer); reject(err); });
+    child.on('close', (code) => {
+      clearTimeout(timer);
+      if (code === 0) resolve(stdout);
+      else reject(new Error(stderr.trim() || `docker exec exited with code ${code}`));
+    });
+
+    child.stdin.on('error', () => { /* the close handler reports the real failure */ });
+    child.stdin.end(input);
+  });
+}
+
+/**
+ * Map over items with a cap on how many run at once.
+ *
+ * The point of making these calls async is to run an agent fleet's worth of them
+ * concurrently instead of one after another. Doing that with a bare
+ * `Promise.all` would spawn one `docker exec` per agent simultaneously, which is
+ * fine for seven agents and not fine for seventy — each one is a process, and
+ * the Docker daemon serialises past a point anyway. The cap keeps the win
+ * without trading a frozen event loop for a swamped daemon.
+ *
+ * Results keep the order of `items`, regardless of completion order.
+ *
+ * Fail-fast, like `Promise.all`: if `fn` rejects for one item the whole call
+ * rejects. That is deliberate — silently swallowing failures here would hide
+ * real errors — but it means callers fanning out over an agent fleet should pass
+ * a function that handles its own failures (the `…NoFail` variants above, or an
+ * explicit try/catch), so one unreachable container can't blank an entire page.
+ */
+export async function mapWithConcurrency<T, R>(
+  items: readonly T[],
+  limit: number,
+  fn: (item: T, index: number) => Promise<R>,
+): Promise<R[]> {
+  if (items.length === 0) return [];
+  const results = new Array<R>(items.length);
+  let next = 0;
+
+  const workers = Array.from({ length: Math.max(1, Math.min(limit, items.length)) }, async () => {
+    while (true) {
+      const i = next++;
+      if (i >= items.length) return;
+      results[i] = await fn(items[i], i);
+    }
+  });
+
+  await Promise.all(workers);
+  return results;
+}