bunqueue-dashboard 0.0.38 → 0.0.40

package/README.md

@@ -26,7 +26,7 @@ The full dashboard running on sample data, no server needed.
 
 ![React 19](https://img.shields.io/badge/React-19-149ECA?logo=react&logoColor=white)
 ![Vite 8](https://img.shields.io/badge/Vite-8-646CFF?logo=vite&logoColor=white)
-![Bun](https://img.shields.io/badge/Bun-1.3-000?logo=bun&logoColor=white)
+![Bun](https://img.shields.io/badge/Bun-1.4-000?logo=bun&logoColor=white)
 ![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178C6?logo=typescript&logoColor=white)
 ![Oxlint + Oxfmt](https://img.shields.io/badge/Oxc-Oxlint%20%2B%20Oxfmt-7C3AED)
 
@@ -90,13 +90,13 @@ The full dashboard running on sample data, no server needed.
 bunqueue exposes a rich HTTP API, but operating it by hand (curl, ad-hoc scripts) is slow and
 error-prone. This dashboard is a production-oriented operator console: it exposes the verified,
 safe subset of the API, fails closed where
-[v2.8.59](https://github.com/egeominotti/bunqueue/releases/tag/v2.8.59) lacks atomic
+[Bunqueue 2.9.x](https://github.com/egeominotti/bunqueue/releases/tag/v2.9.2) lacks atomic
 flow-safety guarantees, and also manages the
 server *process* through a separate guarded agent.
 
 It uses Bunqueue's public HTTP API (`:6790`) for ordinary remote observability and a small local
 **control agent** for process, FlowProducer, Workflow Engine, database, and backup operations. The
-agent is pinned to the server it manages and uses the exact installed Bunqueue 2.8.59 client
+agent is pinned to the server it manages and uses the exact installable Bunqueue 2.9.2 npm client
 contracts; it never patches Bunqueue internals.
 
 ## Features
@@ -111,22 +111,24 @@ contracts; it never patches Bunqueue internals.
 | **Cron** | Control ▸ Cron Manager | Submit acknowledged cron/interval upserts and delete schedules |
 | **Workflow Engine** | Workflow ▸ Overview / Executions / Waiting / Compensation / Archive | Start, recover, signal, inspect, compensate, archive and clean durable executions |
 | **Job Flows** | Workflow ▸ Job Flows | Explore DAGs, run all FlowProducer create modes and operate safe Flow Job methods |
-| **DLQ** | Control ▸ DLQ | Inspect entries, failure history and CSV exports; retry and purge stay unavailable |
+| **DLQ** | Control ▸ DLQ | Inspect/export failures; removal, retry and purge stay unavailable without atomic generation/topology preconditions |
 | **Webhooks** | Control ▸ Webhooks | Create / enable / delete job-event webhooks |
 | **Ops** | Control ▸ Diagnostics | Health, ping, storage, memory, connections, totals |
 | **S3 backup** | Management ▸ S3 Backup | Configure, inspect, list, create and guarded-restore official snapshots |
 | **Browse** | Queues / Jobs / DLQ / Cron / Metrics / Workers / Logs | Read-only browsing with basic actions |
 
-> Job actions are gated by the v2.8.59 flow contract. Every DLQ retry and completed-job requeue is
+> Job actions are gated by the v2.9.2 flow contract. Every DLQ retry and completed-job requeue is
 > unavailable: the DLQ GET + POST sequence has no atomic generation/state/topology precondition and
 > can target a job recreated under the same ID, while `retryCompleted` does not rebuild dependency
 > registration or flow order. Cancel, Discard, Drain, Clean, Obliterate and DLQ Purge also fail
-> closed. DLQ `maxAge`/`maxEntries` are read-only, auto-retry can only be disabled, and Copilot's only
+> closed. Bunqueue 2.9's `Queue.removeDlqJob()` also accepts only queue + job ID, so custom-ID reuse
+> prevents the dashboard from proving that a later deletion still targets the observed generation.
+> DLQ `maxAge`/`maxEntries` are read-only, auto-retry can only be disabled, and Copilot's only
 > mutations are Promote, Pause and Resume.
 
 ## Quick start
 
-**Prerequisites:** [Bun](https://bun.sh) ≥ 1.3 and a reachable bunqueue server (or let the control
+**Prerequisites:** [Bun](https://bun.sh) 1.4.0 and a reachable bunqueue server (or let the control
 agent start one for you from the **Server** page).
 
 ### Run from npm (no clone)
@@ -145,7 +147,7 @@ standalone binaries: `PORT` · `BIND_ADDR` · `BUNQUEUE_URL` · `AGENT_PORT` ·
 Install it permanently instead of running via `bunx`:
 
 ```bash
-bun add -g bunqueue-dashboard   # or: npm i -g bunqueue-dashboard (still runs on Bun)
+bun add -g bunqueue-dashboard
 bunqueue-dashboard
 ```
 
@@ -297,9 +299,15 @@ The canonical gate must be green before a change is considered done; CI runs the
 bun run quality   # architecture, lint/build, size, docs, coverage, real E2E, packed-bin smoke, audit
 ```
 
-The E2E stage starts disposable Bunqueue 2.8.59 processes and exercises the complete FlowProducer,
+The E2E stage starts disposable Bunqueue 2.9.2 processes and exercises the complete FlowProducer,
 Workflow Engine, and Queue SDK operator bridges. Run it alone with `bun run test:e2e`.
 
+The blocking browser job builds the production bundle under `/e2e/dashboard`, starts an
+authenticated disposable Bunqueue server, and drives the UI with Playwright on Chromium, Firefox,
+and WebKit. It covers the token gate, every sidebar route, SSE recovery across a real server
+restart, confirmed Cron creation/deletion, and automated WCAG A/AA checks. Install the browser
+binaries once with `bun run test:e2e:browser:install`, then run `bun run test:e2e:browser`.
+
 CI enforces this on every push and pull request. See [Contributing](#contributing).
 
 ## Project structure

package/agent/backup/resultValidation.ts

@@ -81,5 +81,5 @@ function validIsoDate(value: string): boolean {
 }
 
 function invalid(label: string): never {
-  throw new Error(`Bunqueue ${label} has an invalid 2.8.59 contract`);
+  throw new Error(`Bunqueue ${label} has an invalid 2.9.2 contract`);
 }

package/agent/backup/routes.ts

@@ -10,36 +10,82 @@ export interface BackupRouteResponse {
   body: Record<string, unknown>;
 }
 
-export async function routeBackupRequest(
+export type PreparedBackupRequest =
+  | { operation: 'status' | 'list' | 'now'; query: URLSearchParams }
+  | { operation: 'configure'; query: URLSearchParams; environment: unknown }
+  | { operation: 'restore'; query: URLSearchParams; key: string; database: unknown };
+
+/** Read and validate the bounded HTTP payload before acquiring a lifecycle lease. */
+export async function prepareBackupRequest(
   request: Request,
   pathname: string,
   method: string,
-  config: ServerConfig,
-  serverRunning: boolean,
-  database: DbStats,
-  runner: BackupRunnerPort,
-  configure?: (extraEnv: Record<string, string>) => void,
+  config?: ServerConfig,
   targetPolicy?: ManagedTargetPolicy
-): Promise<BackupRouteResponse | null> {
+): Promise<PreparedBackupRequest | null> {
   const operation = routeOperation(pathname, method);
   if (!operation) return null;
   const query = exactTargetQuery(request.url);
-  assertManagedTarget(query, config, targetPolicy);
+  if (config) assertManagedTarget(query, config, targetPolicy);
   if (operation === 'configure') {
-    if (!configure) throw new Error('Backup configuration is unavailable');
     const body = await boundedRecord(request, ['environment']);
-    const next = mergeBackupEnvironment(config.extraEnv, body.environment);
-    configure(next);
-    return success({ configured: true, enabled: next.S3_BACKUP_ENABLED === 'true' });
+    return { operation, query, environment: body.environment };
   }
   if (operation === 'restore') {
-    if (serverRunning) throw new Error('Stop the managed Bunqueue server before restoring a backup');
     const body = await boundedRecord(request, ['key', 'database']);
-    const key = backupKey(body.key);
-    assertDatabaseSnapshot(body.database, database);
-    return success(await runner.execute(config, operation, key));
+    return { operation, query, key: backupKey(body.key), database: body.database };
+  }
+  return { operation, query };
+}
+
+/** Execute a prepared operation against one lifecycle-pinned config/database snapshot. */
+export async function executePreparedBackupRequest(
+  prepared: PreparedBackupRequest,
+  config: ServerConfig,
+  serverRunning: boolean,
+  database: DbStats,
+  runner: BackupRunnerPort,
+  configure?: (extraEnv: Record<string, string>) => void | Promise<void>,
+  targetPolicy?: ManagedTargetPolicy
+): Promise<BackupRouteResponse> {
+  assertManagedTarget(prepared.query, config, targetPolicy);
+  if (prepared.operation === 'configure') {
+    if (!configure) throw new Error('Backup configuration is unavailable');
+    const next = mergeBackupEnvironment(config.extraEnv, prepared.environment);
+    await configure(next);
+    return success({ configured: true, enabled: next.S3_BACKUP_ENABLED === 'true' });
+  }
+  if (prepared.operation === 'restore') {
+    if (serverRunning) throw new Error('Stop the managed Bunqueue server before restoring a backup');
+    assertDatabaseSnapshot(prepared.database, database);
+    return success(await runner.execute(config, prepared.operation, prepared.key));
   }
-  return success(await runner.execute(config, operation));
+  return success(await runner.execute(config, prepared.operation));
+}
+
+export async function routeBackupRequest(
+  request: Request,
+  pathname: string,
+  method: string,
+  config: ServerConfig,
+  serverRunning: boolean,
+  database: DbStats,
+  runner: BackupRunnerPort,
+  configure?: (extraEnv: Record<string, string>) => void,
+  targetPolicy?: ManagedTargetPolicy
+): Promise<BackupRouteResponse | null> {
+  const prepared = await prepareBackupRequest(request, pathname, method, config, targetPolicy);
+  return prepared
+    ? executePreparedBackupRequest(
+        prepared,
+        config,
+        serverRunning,
+        database,
+        runner,
+        configure,
+        targetPolicy
+      )
+    : null;
 }
 
 function routeOperation(pathname: string, method: string) {

package/agent/db/query.ts

@@ -47,7 +47,8 @@ export function dbQuery(path: string, sql: string): DbQueryResult {
       throw translateDbError(error);
     }
     let columns = statement.columnNames;
-    if (statement.columnTypes.length > columns.length) {
+    const hasDuplicateNames = new Set(columns).size !== columns.length;
+    if (statement.columnTypes.length > columns.length || hasDuplicateNames) {
       const disambiguated = disambiguateColumns(db, trimmed);
       if (disambiguated) {
         statement = disambiguated.stmt;

package/agent/index.ts

@@ -12,6 +12,7 @@
  *       BUNQUEUE_START_CMD, BUNQUEUE_MANAGED, BUNQUEUE_URL, BUNQUEUE_TOKEN,
  *       HTTP_PORT, TCP_PORT, BUNQUEUE_DATA_PATH
  */
+import { assertRequiredBunVersion } from '../scripts/bunVersion';
 import { logger } from './logger';
 import { ProcessManager } from './manager';
 import {
@@ -22,6 +23,8 @@ import {
 } from './server';
 import { installAgentShutdown } from './shutdown';
 
+assertRequiredBunVersion();
+
 const mgr = new ProcessManager();
 const PORT = Number(process.env.AGENT_PORT) || 6800;
 const allowedOrigins = resolveAllowedOrigins();

package/agent/manager/config.ts

@@ -10,7 +10,7 @@ const CONFIG_KEYS = new Set<keyof ServerConfig>([
 
 export function defaultConfig(): ServerConfig {
   return {
-    command: process.env.BUNQUEUE_START_CMD || 'bunx bunqueue@2.8.59 start',
+    command: process.env.BUNQUEUE_START_CMD || 'bunx bunqueue@2.9.2 start',
     httpPort: Number(process.env.HTTP_PORT) || 6790,
     tcpPort: Number(process.env.TCP_PORT) || 6789,
     dataPath: process.env.BUNQUEUE_DATA_PATH || './data/bunq.db',
@@ -76,6 +76,7 @@ export function validateServerConfig(value: unknown): ServerConfig {
   for (const key of CONFIG_KEYS) {
     if (!Object.hasOwn(value, key)) throw new Error(`Missing config key: ${key}`);
   }
+  if (config.httpPort === config.tcpPort) throw new Error('httpPort and tcpPort must differ');
   return config as ServerConfig;
 }
 

package/agent/manager/process.ts

@@ -1,6 +1,7 @@
 import { copyConfig, defaultConfig, validateConfigPatch, validateServerConfig } from './config';
 import { ProcessLogs } from './logs';
 import { databaseStats } from './storage';
+import { removeSqlitePaths, validateManagedStorage } from './storageMode';
 import type {
   DbStats,
   LogLine,
@@ -29,6 +30,9 @@ export class ProcessManager {
   private startedAt: number | null = null;
   private exitCode: number | null = null;
   private config: ServerConfig = defaultConfig();
+  // A per-agent random seed prevents stale compare-and-set tokens from a
+  // previous control-agent process matching again after a restart (ABA).
+  private configRevision = configRevisionSeed();
   private runningConfig: ServerConfig | null = null;
   private procToken = 0;
   private stopping: Promise<StatusSnapshot> | null = null;
@@ -42,13 +46,26 @@ export class ProcessManager {
     return copyConfig(this.config);
   }
 
-  setConfig(patch: Partial<ServerConfig>): ServerConfig {
+  getConfigRevision(): number {
+    return this.configRevision;
+  }
+
+  setConfig(patch: Partial<ServerConfig>, expectedRevision?: number): ServerConfig {
+    if (expectedRevision !== undefined && expectedRevision !== this.configRevision) {
+      throw new Error(
+        `Configuration changed since revision ${expectedRevision}; current revision is ${this.configRevision}`
+      );
+    }
     const valid = validateConfigPatch(patch);
-    this.config = {
+    const next = validateServerConfig({
       ...this.config,
       ...valid,
       extraEnv: valid.extraEnv ?? this.config.extraEnv,
-    };
+    });
+    if (!sameConfig(this.config, next)) {
+      this.config = next;
+      this.configRevision = nextConfigRevision(this.configRevision);
+    }
     return copyConfig(this.config);
   }
 
@@ -56,6 +73,7 @@ export class ProcessManager {
     return {
       status: this.status,
       generation: this.procToken,
+      configRevision: this.configRevision,
       pid: this.proc?.pid ?? null,
       startedAt: this.startedAt,
       exitCode: this.exitCode,
@@ -64,8 +82,10 @@ export class ProcessManager {
     };
   }
 
-  dbStats(): Promise<DbStats> {
-    return databaseStats(this.config.dataPath);
+  dbStats(dataPath?: string): Promise<DbStats> {
+    const effectivePath =
+      dataPath ?? (this.runningConfig ?? this.config).dataPath;
+    return databaseStats(effectivePath);
   }
 
   getLogs(): LogLine[] {
@@ -90,6 +110,7 @@ export class ProcessManager {
     }
 
     const launchConfig = validateServerConfig(this.config);
+    const storageMode = validateManagedStorage(launchConfig);
     const [command, ...args] = launchConfig.command.trim().split(/\s+/);
     this.status = 'starting';
     this.exitCode = null;
@@ -101,6 +122,7 @@ export class ProcessManager {
       TCP_PORT: String(launchConfig.tcpPort),
       BUNQUEUE_DATA_PATH: launchConfig.dataPath,
     };
+    if (storageMode !== 'sqlite') removeSqlitePaths(env);
 
     try {
       this.proc = Bun.spawn([command, ...args], {
@@ -231,3 +253,27 @@ export class ProcessManager {
     }
   }
 }
+
+function sameConfig(left: ServerConfig, right: ServerConfig): boolean {
+  const leftEnv = Object.entries(left.extraEnv).sort(([a], [b]) => a.localeCompare(b));
+  const rightEnv = Object.entries(right.extraEnv).sort(([a], [b]) => a.localeCompare(b));
+  return (
+    left.command === right.command &&
+    left.httpPort === right.httpPort &&
+    left.tcpPort === right.tcpPort &&
+    left.dataPath === right.dataPath &&
+    JSON.stringify(leftEnv) === JSON.stringify(rightEnv)
+  );
+}
+
+function configRevisionSeed(): number {
+  const words = crypto.getRandomValues(new Uint32Array(2));
+  return ((words[0] ?? 0) & 0x1f_ffff) * 0x1_0000_0000 + (words[1] ?? 0);
+}
+
+function nextConfigRevision(current: number): number {
+  if (current < Number.MAX_SAFE_INTEGER) return current + 1;
+  let next = configRevisionSeed();
+  while (next === current) next = configRevisionSeed();
+  return next;
+}

package/agent/manager/storageMode.ts

@@ -0,0 +1,41 @@
+import type { ServerConfig } from './types';
+
+export type ManagedStorageMode = 'memory' | 'sqlite' | 'postgres';
+
+/** Mirrors Bunqueue 2.9's explicit-driver, PostgreSQL-URL, then data-path precedence. */
+export function managedStorageMode(config: ServerConfig): ManagedStorageMode {
+  const explicit = config.extraEnv.BUNQUEUE_STORAGE_DRIVER ?? process.env.BUNQUEUE_STORAGE_DRIVER;
+  if (explicit === 'postgres' || explicit === 'memory' || explicit === 'sqlite') return explicit;
+  if (explicit) throw new Error(`Unsupported storage driver: ${explicit}`);
+  const postgresUrl = config.extraEnv.BUNQUEUE_POSTGRES_URL ?? process.env.BUNQUEUE_POSTGRES_URL;
+  if (postgresUrl) return 'postgres';
+  return config.dataPath ? 'sqlite' : 'memory';
+}
+
+export function managedPostgresUrl(config: ServerConfig): string | undefined {
+  return (config.extraEnv.BUNQUEUE_POSTGRES_URL ?? process.env.BUNQUEUE_POSTGRES_URL)?.trim() || undefined;
+}
+
+export function managedPostgresNamespace(config: ServerConfig): string {
+  return (
+    (config.extraEnv.BUNQUEUE_POSTGRES_NAMESPACE ?? process.env.BUNQUEUE_POSTGRES_NAMESPACE)?.trim() ||
+    'default'
+  );
+}
+
+/** Fail before spawning when Bunqueue would reject an incomplete PostgreSQL config. */
+export function validateManagedStorage(config: ServerConfig): ManagedStorageMode {
+  const mode = managedStorageMode(config);
+  if (mode === 'postgres' && !managedPostgresUrl(config)) {
+    throw new Error('PostgreSQL storage requires BUNQUEUE_POSTGRES_URL');
+  }
+  return mode;
+}
+
+/** Non-SQLite drivers cannot be combined with Bunqueue's legacy SQLite path aliases. */
+export function removeSqlitePaths(env: Record<string, string>): void {
+  delete env.BUNQUEUE_DATA_PATH;
+  delete env.BQ_DATA_PATH;
+  delete env.DATA_PATH;
+  delete env.SQLITE_PATH;
+}

package/agent/manager/types.ts

@@ -30,6 +30,8 @@ export interface StatusSnapshot {
   status: Status;
   /** Monotonic identity of the managed process generation. */
   generation: number;
+  /** Monotonic desired-config revision used for optimistic updates. */
+  configRevision?: number;
   pid: number | null;
   startedAt: number | null;
   exitCode: number | null;

package/agent/manager.ts

@@ -1,6 +1,7 @@
 /** Public compatibility entrypoint for managed bunqueue process supervision. */
 export { validateConfigPatch } from './manager/config';
 export { ProcessManager } from './manager/process';
+export { managedPostgresNamespace, managedStorageMode } from './manager/storageMode';
 export type {
   DbStats,
   LogLine,

package/agent/queue/routes.ts

@@ -13,14 +13,17 @@ import {
   exactJsonBody,
   exactQuery,
   metricsRange,
+  optionalMaxCount,
   optionalMaxJobs,
+  positiveSafeInteger,
   requiredDeduplicationId,
+  requiredGroupId,
   validateQueueName,
 } from './validation';
 
-const READ_ROUTE = /^\/queue-operations\/([^/]+)\/(limits|deduplication|metrics)$/;
+const READ_ROUTE = /^\/queue-operations\/([^/]+)\/(limits|groups|deduplication|metrics)$/;
 const MUTATION_ROUTE =
-  /^\/queue-operations\/([^/]+)\/(deduplication\/remove|events\/trim)$/;
+  /^\/queue-operations\/([^/]+)\/(groups\/(?:rate-limit|concurrency)(?:\/remove)?|deduplication\/remove|events\/trim)$/;
 
 export async function routeQueueOperationsRequest(
   request: Request,
@@ -51,6 +54,21 @@ export async function routeQueueOperationsRequest(
         ok({ jobId: await runtime.deduplicationJobId(current, queue, id) })
       );
     }
+    if (read[2] === 'groups') {
+      const query = pinnedQuery(
+        request,
+        config,
+        ['target', 'groupId', 'maxJobs', 'maxCount'],
+        targetPolicy
+      );
+      const groupId = requiredGroupId(query.get('groupId'));
+      const maxJobs = optionalMaxJobs(query);
+      const maxCount = optionalMaxCount(query);
+      assertRunning(running);
+      return admitted(query, config, running, admission, targetPolicy, async ({ config: current }) =>
+        ok({ group: await runtime.group(current, queue, groupId, maxJobs, maxCount) })
+      );
+    }
     const query = pinnedQuery(request, config, ['target', 'type', 'start', 'end'], targetPolicy);
     const type = metricType(query.get('type'));
     const range = metricsRange(query);
@@ -74,6 +92,42 @@ export async function routeQueueOperationsRequest(
         ok({ removed: await runtime.removeDeduplicationKey(current, queue, id) })
       );
     }
+    if (mutation[2].startsWith('groups/')) {
+      const remove = mutation[2].endsWith('/remove');
+      const rateLimit = mutation[2].includes('/rate-limit');
+      const allowed = remove
+        ? ['groupId']
+        : rateLimit
+          ? ['groupId', 'max', 'duration']
+          : ['groupId', 'concurrency'];
+      const body = await exactJsonBody(request, allowed);
+      const groupId = requiredGroupId(body.groupId);
+      return admitted(query, config, running, admission, targetPolicy, async ({ config: current }) => {
+        if (remove) {
+          const removed = rateLimit
+            ? await runtime.removeGroupRateLimit(current, queue, groupId)
+            : await runtime.removeGroupConcurrency(current, queue, groupId);
+          return ok({ removed });
+        }
+        if (rateLimit) {
+          await runtime.setGroupRateLimit(
+            current,
+            queue,
+            groupId,
+            positiveSafeInteger(body.max, 'max'),
+            positiveSafeInteger(body.duration, 'duration')
+          );
+        } else {
+          await runtime.setGroupConcurrency(
+            current,
+            queue,
+            groupId,
+            positiveSafeInteger(body.concurrency, 'concurrency')
+          );
+        }
+        return ok({ applied: true });
+      });
+    }
     const body = await exactJsonBody(request, ['maxLength']);
     const retention = eventRetention(body.maxLength);
     return admitted(query, config, running, admission, targetPolicy, async ({ config: current }) =>

package/agent/queue/runtime.ts

@@ -1,7 +1,7 @@
 import { Queue, type QueueMetricType, type QueueMetrics } from 'bunqueue/client';
 import { managedAuthToken } from '../managedTarget';
 import type { ServerConfig } from '../manager';
-import type { QueueLimitSnapshot, QueueOperationsPort } from './types';
+import type { QueueGroupSnapshot, QueueLimitSnapshot, QueueOperationsPort } from './types';
 import { QueueOperationsUnavailableError } from './types';
 
 export type QueueOperationsClient = Pick<
@@ -11,8 +11,19 @@ export type QueueOperationsClient = Pick<
   | 'getGlobalConcurrency'
   | 'getRateLimitTtl'
   | 'isMaxed'
+  | 'getGroupJobsCount'
+  | 'getGroupsJobsCount'
+  | 'getGroupActiveCount'
+  | 'setGroupRateLimit'
+  | 'getGroupRateLimit'
+  | 'removeGroupRateLimit'
+  | 'getGroupRateLimitTtl'
+  | 'setGroupConcurrency'
+  | 'getGroupConcurrency'
+  | 'removeGroupConcurrency'
   | 'getDeduplicationJobId'
   | 'removeDeduplicationKey'
+  | 'removeDlqJob'
   | 'getMetrics'
   | 'trimEvents'
   | 'close'
@@ -41,6 +52,57 @@ export class QueueOperationsRuntime implements QueueOperationsPort {
     });
   }
 
+  group(
+    config: ServerConfig,
+    queue: string,
+    groupId: string,
+    maxJobs?: number,
+    maxCount?: number
+  ): Promise<QueueGroupSnapshot> {
+    return this.withQueue(config, queue, async (client) => {
+      const [jobs, active, totalGrouped, rateLimit, rateLimitTtl, concurrency] = await Promise.all([
+        client.getGroupJobsCount(groupId),
+        client.getGroupActiveCount(groupId),
+        client.getGroupsJobsCount(maxCount),
+        client.getGroupRateLimit(groupId),
+        client.getGroupRateLimitTtl(groupId, maxJobs),
+        client.getGroupConcurrency(groupId),
+      ]);
+      return { jobs, active, totalGrouped, rateLimit, rateLimitTtl, concurrency };
+    });
+  }
+
+  setGroupRateLimit(
+    config: ServerConfig,
+    queue: string,
+    groupId: string,
+    max: number,
+    duration: number
+  ): Promise<void> {
+    return this.withQueue(config, queue, (client) =>
+      client.setGroupRateLimit(groupId, max, duration)
+    );
+  }
+
+  removeGroupRateLimit(config: ServerConfig, queue: string, groupId: string): Promise<number> {
+    return this.withQueue(config, queue, (client) => client.removeGroupRateLimit(groupId));
+  }
+
+  setGroupConcurrency(
+    config: ServerConfig,
+    queue: string,
+    groupId: string,
+    concurrency: number
+  ): Promise<void> {
+    return this.withQueue(config, queue, (client) =>
+      client.setGroupConcurrency(groupId, concurrency)
+    );
+  }
+
+  removeGroupConcurrency(config: ServerConfig, queue: string, groupId: string): Promise<number> {
+    return this.withQueue(config, queue, (client) => client.removeGroupConcurrency(groupId));
+  }
+
   deduplicationJobId(
     config: ServerConfig,
     queue: string,
@@ -59,6 +121,10 @@ export class QueueOperationsRuntime implements QueueOperationsPort {
     return this.withQueue(config, queue, (client) => client.removeDeduplicationKey(deduplicationId));
   }
 
+  removeDlqJob(config: ServerConfig, queue: string, jobId: string): Promise<boolean> {
+    return this.withQueue(config, queue, (client) => client.removeDlqJob(jobId));
+  }
+
   metrics(
     config: ServerConfig,
     queue: string,

package/agent/queue/types.ts

@@ -8,8 +8,39 @@ export interface QueueLimitSnapshot {
   maxed: boolean;
 }
 
+export interface QueueGroupSnapshot {
+  jobs: number;
+  active: number;
+  totalGrouped: number;
+  rateLimit: { max: number; duration: number } | null;
+  rateLimitTtl: number;
+  concurrency: number | null;
+}
+
 export interface QueueOperationsPort {
   limits(config: ServerConfig, queue: string, maxJobs?: number): Promise<QueueLimitSnapshot>;
+  group(
+    config: ServerConfig,
+    queue: string,
+    groupId: string,
+    maxJobs?: number,
+    maxCount?: number
+  ): Promise<QueueGroupSnapshot>;
+  setGroupRateLimit(
+    config: ServerConfig,
+    queue: string,
+    groupId: string,
+    max: number,
+    duration: number
+  ): Promise<void>;
+  removeGroupRateLimit(config: ServerConfig, queue: string, groupId: string): Promise<number>;
+  setGroupConcurrency(
+    config: ServerConfig,
+    queue: string,
+    groupId: string,
+    concurrency: number
+  ): Promise<void>;
+  removeGroupConcurrency(config: ServerConfig, queue: string, groupId: string): Promise<number>;
   deduplicationJobId(
     config: ServerConfig,
     queue: string,
@@ -20,6 +51,7 @@ export interface QueueOperationsPort {
     queue: string,
     deduplicationId: string
   ): Promise<number>;
+  removeDlqJob(config: ServerConfig, queue: string, jobId: string): Promise<boolean>;
   metrics(
     config: ServerConfig,
     queue: string,

package/agent/queue/validation.ts

@@ -40,6 +40,22 @@ export function optionalMaxJobs(query: URLSearchParams): number | undefined {
   return raw === null ? undefined : boundedInteger(raw, 'maxJobs', 0, 1_000_000);
 }
 
+export function optionalMaxCount(query: URLSearchParams): number | undefined {
+  const raw = query.get('maxCount');
+  return raw === null ? undefined : boundedInteger(raw, 'maxCount', 1, 1_000_000);
+}
+
+export function requiredGroupId(value: unknown): string {
+  if (typeof value !== 'string' || !value || value.length > 256 || value.includes('\0')) {
+    throw new Error('groupId must be a non-empty string of at most 256 characters without NUL');
+  }
+  return value;
+}
+
+export function positiveSafeInteger(value: unknown, label: string): number {
+  return bodyInteger(value, label, 1, Number.MAX_SAFE_INTEGER);
+}
+
 export function metricsRange(query: URLSearchParams): { start: number; end: number } {
   const start = optionalInteger(query.get('start'), 'start', 0, MAX_PAGE_INDEX, 0);
   const rawEnd = query.get('end');