@desplega.ai/agent-swarm 1.131.1 → 1.133.1

package/src/http/db-query.ts

@@ -1,15 +1,30 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import { z } from "zod";
-import { getDb } from "../be/db";
+import { executeReadOnlyQueryBounded } from "./db-query-bounded";
+import {
+  assertSingleStatement,
+  DbQueryConcurrencyCapError,
+  type DbQueryResult,
+  DbQueryTimeoutError,
+  executeReadOnlyQuery,
+  getDbQueryHttpBudgetMs,
+  getDbQueryHttpMaxRows,
+  isDbQueryBoundedEnabled,
+  stripTrailingSemicolon,
+  warnDbQueryBoundedDisabledOnce,
+} from "./db-query-shared";
 import { route } from "./route-def";
 import { json, jsonError } from "./utils";
 
-export interface DbQueryResult {
-  columns: string[];
-  rows: unknown[][];
-  elapsed: number;
-  total: number;
-}
+export type { DbQueryResult } from "./db-query-shared";
+export {
+  assertSingleStatement,
+  executeReadOnlyQuery,
+  getDbQueryHttpBudgetMs,
+  getDbQueryHttpMaxRows,
+  getDbQueryMcpBudgetMs,
+  isDbQueryBoundedEnabled,
+} from "./db-query-shared";
 
 export const DbQueryInputShape = {
   sql: z.string().min(1).max(10_000).optional(),
@@ -29,17 +44,6 @@ export function resolveDbQuerySql(input: Pick<DbQueryInput, "sql" | "query">): s
   return input.sql ?? input.query ?? "";
 }
 
-function stripTrailingSemicolon(sql: string): string {
-  return sql.trim().replace(/;\s*$/, "").trim();
-}
-
-function assertSingleStatement(sql: string): void {
-  const stripped = stripTrailingSemicolon(sql);
-  if (stripped.includes(";")) {
-    throw new Error("Only one SQL statement is allowed");
-  }
-}
-
 export function assertSelectOnlyQuery(sql: string): void {
   assertSingleStatement(sql);
   const normalized = stripTrailingSemicolon(sql).toLowerCase();
@@ -49,34 +53,23 @@ export function assertSelectOnlyQuery(sql: string): void {
 }
 
 /**
- * Execute a read-only SQL query against the swarm database.
- * Detects write statements via bun:sqlite's columnNames (empty for INSERT/UPDATE/DELETE/DROP).
+ * Gate in front of the bounded executor (Fix 1). `DB_QUERY_BOUNDED_ENABLED`
+ * (default on) picks the path: enabled runs the bounded child-process
+ * executor unchanged; disabled restores the pre-fix synchronous path with no
+ * wall-clock budget and logs a one-time warning, so turning off the
+ * protection can't happen silently.
  */
-export function executeReadOnlyQuery(
+export async function executeReadOnlyQueryGated(
   sql: string,
   params: unknown[] = [],
+  budgetMs: number,
   maxRows?: number,
-): DbQueryResult {
-  assertSingleStatement(sql);
-  const stmt = getDb().prepare(sql);
-
-  // bun:sqlite: columnNames is empty for write statements, populated for SELECT/PRAGMA/EXPLAIN
-  if (stmt.columnNames.length === 0) {
-    throw new Error("Only read-only queries are allowed");
+): Promise<DbQueryResult> {
+  if (isDbQueryBoundedEnabled()) {
+    return executeReadOnlyQueryBounded(sql, params, budgetMs, maxRows);
   }
-
-  const columns = stmt.columnNames as string[];
-  const start = performance.now();
-  const rows = (params.length > 0 ? stmt.all(...(params as [string])) : stmt.all()) as Record<
-    string,
-    unknown
-  >[];
-  const elapsed = Math.round(performance.now() - start);
-
-  const capped = maxRows ? rows.slice(0, maxRows) : rows;
-  const rowArrays = capped.map((row) => columns.map((col) => row[col]));
-
-  return { columns, rows: rowArrays, elapsed, total: rows.length };
+  warnDbQueryBoundedDisabledOnce();
+  return executeReadOnlyQuery(sql, params, maxRows);
 }
 
 const dbQueryRoute = route({
@@ -97,6 +90,8 @@ const dbQueryRoute = route({
       }),
     },
     400: { description: "Invalid or disallowed SQL" },
+    408: { description: "Query exceeded its wall-clock budget and was terminated" },
+    429: { description: "Too many concurrent bounded db-query executions; retry shortly" },
   },
   auth: { apiKey: true },
 });
@@ -115,9 +110,26 @@ export async function handleDbQuery(
   if (!parsed) return true;
 
   try {
-    const result = executeReadOnlyQuery(resolveDbQuerySql(parsed.body), parsed.body.params);
+    const result = await executeReadOnlyQueryGated(
+      resolveDbQuerySql(parsed.body),
+      parsed.body.params,
+      getDbQueryHttpBudgetMs(),
+      getDbQueryHttpMaxRows(),
+    );
     json(res, result);
   } catch (err: unknown) {
+    if (err instanceof DbQueryConcurrencyCapError) {
+      // Machine-readable code + Retry-After so a caller can back off instead
+      // of treating this like a malformed request (the pre-existing generic
+      // 400 every other error path here returns).
+      res.setHeader("Retry-After", "1");
+      json(res, { error: "db_query_concurrency_cap", message: err.message }, 429);
+      return true;
+    }
+    if (err instanceof DbQueryTimeoutError) {
+      json(res, { error: "db_query_timeout", message: err.message }, 408);
+      return true;
+    }
     const message = err instanceof Error ? err.message : String(err);
     jsonError(res, message);
   }

package/src/http/events.ts

@@ -82,6 +82,7 @@ const getEventsRoute = route({
     agentId: z.string().optional(),
     taskId: z.string().optional(),
     sessionId: z.string().optional(),
+    dataField: z.string().optional(),
     since: z.string().optional(),
     until: z.string().optional(),
     limit: z.coerce.number().int().min(1).max(1000).optional(),
@@ -191,6 +192,7 @@ export async function handleEvents(
       agentId: parsed.query.agentId || undefined,
       taskId: parsed.query.taskId || undefined,
       sessionId: parsed.query.sessionId || undefined,
+      dataField: parsed.query.dataField || undefined,
       since: parsed.query.since || undefined,
       until: parsed.query.until || undefined,
       limit: parsed.query.limit ?? 100,

package/src/http/index.ts

@@ -31,6 +31,7 @@ import {
   withRemoteContext,
   withSpanContext,
 } from "../otel";
+import { startQueueStallAlarm, stopQueueStallAlarm } from "../queue-stall-alarm";
 import { clearAuditSink, isRbacEnabled, setAuditSink } from "../rbac";
 import { startScriptRunSupervisor, stopScriptRunSupervisor } from "../script-workflows/supervisor";
 import { getServerSessionsProcessed } from "../server-runtime-counters";
@@ -424,6 +425,9 @@ async function shutdown() {
   // Stop heartbeat triage
   stopHeartbeat();
 
+  // Stop the out-of-band queue alarm before disconnecting its Slack notifier.
+  stopQueueStallAlarm();
+
   // Stop durable script workflow subprocesses
   stopScriptRunSupervisor();
 
@@ -485,13 +489,26 @@ async function shutdown() {
 // Only register signal handlers once (avoid duplicates on hot reload)
 if (!globalState.__sigintRegistered) {
   globalState.__sigintRegistered = true;
+  // A rejected shutdown must not become an unhandled rejection: the signal
+  // handler is the last code that runs, so an error here is the only chance to
+  // learn why the process failed to exit cleanly.
   process.on("SIGINT", () => {
     shutdownSignal = "SIGINT";
-    shutdown();
+    shutdown().catch((err) =>
+      console.error(
+        "[shutdown] SIGINT shutdown failed:",
+        scrubSecrets(err instanceof Error ? err.message : String(err)),
+      ),
+    );
   });
   process.on("SIGTERM", () => {
     shutdownSignal = "SIGTERM";
-    shutdown();
+    shutdown().catch((err) =>
+      console.error(
+        "[shutdown] SIGTERM shutdown failed:",
+        scrubSecrets(err instanceof Error ? err.message : String(err)),
+      ),
+    );
   });
 }
 
@@ -608,6 +625,9 @@ httpServer
     // Start Slack bot (if configured)
     await startSlackApp();
 
+    // Independent of workers, scheduler targets, and heartbeat agent tasks.
+    startQueueStallAlarm();
+
     // Initialize GitHub webhook handler (if configured)
     initGitHub();
 

package/src/http/mcp-bridge.ts

@@ -1,10 +1,16 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import {
+  type AnySchema,
+  getParseErrorMessage,
+  normalizeObjectSchema,
+  safeParseAsync,
+} from "@modelcontextprotocol/sdk/server/zod-compat.js";
 import { z } from "zod";
 import { createServer } from "@/server";
 import { isMcpToolAllowedForScripts } from "../scripts-runtime/sdk-allowlist";
 import { markScriptSdkRequestOrigin } from "../tools/utils";
-import { route } from "./route-def";
+import { route, runtimeInstanceHeader } from "./route-def";
 import { json, jsonError } from "./utils";
 
 // Lazy singleton — created once on first bridge call to avoid boot-time cost.
@@ -23,7 +29,7 @@ function getBridgeServer(): McpServer {
 
 type RegisteredTool = {
   handler: (argsOrExtra: unknown, extra?: unknown) => unknown | Promise<unknown>;
-  inputSchema?: unknown;
+  inputSchema?: AnySchema;
   enabled?: boolean;
 };
 
@@ -35,6 +41,7 @@ const mcpBridgeRoute = route({
   pattern: ["api", "mcp-bridge"],
   summary: "Generic MCP tool proxy for the scripts SDK bridge",
   tags: ["Scripts"],
+  headers: runtimeInstanceHeader("acquire work through bridged tools"),
   body: z.object({
     tool: z.string().min(1).max(200),
     args: z.record(z.string(), z.unknown()).default({}),
@@ -87,6 +94,11 @@ export async function handleMcpBridge(
   const sourceTaskId = Array.isArray(req.headers["x-source-task-id"])
     ? req.headers["x-source-task-id"][0]
     : (req.headers["x-source-task-id"] as string | undefined);
+  // Runtime identity rides the bridge like the agent identity so the
+  // work-acquisition gates in bridged tools see the invoking worker process.
+  const runtimeInstanceId = Array.isArray(req.headers["x-runtime-instance-id"])
+    ? req.headers["x-runtime-instance-id"][0]
+    : (req.headers["x-runtime-instance-id"] as string | undefined);
 
   const extra = markScriptSdkRequestOrigin({
     sessionId: "mcp-bridge",
@@ -94,13 +106,35 @@ export async function handleMcpBridge(
       headers: {
         "x-agent-id": myAgentId ?? "",
         ...(sourceTaskId ? { "x-source-task-id": sourceTaskId } : {}),
+        ...(runtimeInstanceId ? { "x-runtime-instance-id": runtimeInstanceId } : {}),
       },
     },
   });
 
+  // Mirror the SDK's own tools/call validation (`validateToolInput` in
+  // @modelcontextprotocol/sdk server/mcp.js). The bridge bypasses the MCP
+  // transport, so without this parse raw script args reach handlers
+  // unchecked (2026-08-18 priority='high' incident) and the schema's
+  // `.default()`/`.transform()` never apply.
+  let handlerArgs: unknown = args;
+  if (tool.inputSchema) {
+    const inputObj = normalizeObjectSchema(tool.inputSchema);
+    const parseResult = await safeParseAsync(inputObj ?? tool.inputSchema, args);
+    if (!parseResult.success) {
+      const parseError = "error" in parseResult ? parseResult.error : "Unknown error";
+      jsonError(
+        res,
+        `Invalid arguments for tool '${toolName}': ${getParseErrorMessage(parseError)}`,
+        400,
+      );
+      return true;
+    }
+    handlerArgs = parseResult.data;
+  }
+
   try {
     const result = tool.inputSchema
-      ? await Promise.resolve(tool.handler(args, extra))
+      ? await Promise.resolve(tool.handler(handlerArgs, extra))
       : await Promise.resolve(tool.handler(extra));
 
     if (result && typeof result === "object" && "structuredContent" in result) {

package/src/http/mcp.ts

@@ -118,6 +118,18 @@ export async function handleMcp(
     }
     const body = JSON.parse(Buffer.concat(chunks).toString());
 
+    if (!sessionId && body.method === "server/discover") {
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(
+        JSON.stringify({
+          jsonrpc: "2.0",
+          error: { code: -32601, message: "Method not found" },
+          id: body.id ?? null,
+        }),
+      );
+      return true;
+    }
+
     let transport: StreamableHTTPServerTransport;
 
     if (sessionId && transports[sessionId]) {

package/src/http/memory.ts

@@ -21,6 +21,7 @@ import { getRetrievalsForAgent, hasRetrievalForTask } from "../be/memory/retriev
 import { getUsefulnessStats } from "../be/memory/usefulness-stats";
 import { shouldPersistAutomaticTaskMemory } from "../memory/automatic-task-gate";
 import { AgentMemorySchema, AgentMemoryScopeSchema, AgentMemorySourceSchema } from "../types";
+import { scrubSecrets } from "../utils/secret-scrubber";
 import { route } from "./route-def";
 import { jsonError, parseQueryParams } from "./utils";
 
@@ -725,7 +726,12 @@ export async function handleMemory(
       } catch (err) {
         console.error("[memory] Batch embedding failed:", (err as Error).message);
       }
-    })();
+    })().catch((err) =>
+      console.error(
+        "[memory] batch embed failed:",
+        scrubSecrets(err instanceof Error ? err.message : String(err)),
+      ),
+    );
 
     indexMemory.respond(res, 202, { queued: true, memoryIds: memories.map((m) => m.id) });
     return true;
@@ -1041,7 +1047,12 @@ export async function handleMemory(
         }
       }
       console.log(`[memory] Re-embedding complete: ${memories.length} memories`);
-    })();
+    })().catch((err) =>
+      console.error(
+        "[memory] re-embed batch failed:",
+        scrubSecrets(err instanceof Error ? err.message : String(err)),
+      ),
+    );
 
     return true;
   }

package/src/http/openapi.ts

@@ -65,6 +65,7 @@ export function generateOpenApiSpec(opts: OpenApiOptions): string {
     const request: Record<string, unknown> = {};
     if (routeDef.params) request.params = routeDef.params;
     if (routeDef.query) request.query = routeDef.query;
+    if (routeDef.headers) request.headers = routeDef.headers;
     if (routeDef.body) {
       request.body = {
         content: { "application/json": { schema: routeDef.body } },

package/src/http/poll.ts

@@ -23,9 +23,11 @@ import {
   hasCapacity,
   recordBudgetRefusalNotification,
   startTask,
+  updateAgentStatusFromCapacity,
   upsertChannelActivityCursor,
 } from "../be/db";
 import { renderIdentity, resolveIdentity } from "../be/identity";
+import { touchRuntimeInstance } from "../be/multi-runtime";
 import { hasCapability } from "../server";
 import { fetchChannelActivity } from "../slack/channel-activity";
 import { telemetry } from "../telemetry";
@@ -33,9 +35,12 @@ import {
   AgentTaskSchema,
   BudgetRefusedTriggerSchema,
   TaskAttachmentSchema,
+  UserCommsPrefsSchema,
   UserSchema,
 } from "../types";
-import { route } from "./route-def";
+import { isMultiRuntimeEnabled } from "../utils/multi-runtime";
+import { getUserCommsPrefs } from "../utils/requester-comms";
+import { route, runtimeInstanceHeader } from "./route-def";
 import { jsonError } from "./utils";
 
 // ─── Budget-refused trigger envelope ────────────────────────────────────────
@@ -93,12 +98,16 @@ const PollRequestedBySchema = UserSchema.pick({
   email: true,
   role: true,
   notes: true,
+}).extend({
+  // Structured communication preferences from `users.metadata.comms`.
+  comms: UserCommsPrefsSchema.optional(),
 });
 
 const PollTaskOfferedTriggerSchema = z.object({
   type: z.literal("task_offered"),
   taskId: z.string(),
   task: AgentTaskSchema,
+  requestedBy: PollRequestedBySchema.optional(),
 });
 
 const PollTaskAssignedTriggerSchema = z.object({
@@ -155,6 +164,7 @@ const pollTriggers = route({
   summary: "Poll for triggers (tasks, mentions)",
   tags: ["Poll"],
   auth: { apiKey: true, agentId: true },
+  headers: runtimeInstanceHeader("poll for work"),
   responses: {
     200: { description: "Trigger data or null", schema: pollResponseSchema },
     400: { description: "Missing X-Agent-ID" },
@@ -171,6 +181,33 @@ function getRequesterNotes(notes: string | undefined): string | undefined {
   return typeof notes === "string" && notes.trim().length > 0 ? notes : undefined;
 }
 
+/**
+ * Resolve the requester projection for a task trigger. If the task carries a
+ * machine-recorded external id (today: the Slack user field) but no
+ * requestedByUserId, render the explicit UNKNOWN sentinel instead of silently
+ * omitting the section: never a substituted human (Rule 33 /
+ * provenance-or-silence).
+ */
+function buildTriggerRequestedBy(task: {
+  requestedByUserId?: string | null;
+  slackUserId?: string | null;
+}): z.infer<typeof PollRequestedBySchema> | undefined {
+  const user = task.requestedByUserId ? getUserById(task.requestedByUserId) : undefined;
+  if (user) {
+    return {
+      name: user.name,
+      email: user.email,
+      role: user.role,
+      notes: getRequesterNotes(user.notes),
+      comms: getUserCommsPrefs(user),
+    };
+  }
+  if (task.slackUserId) {
+    return { name: renderIdentity(resolveIdentity("slack", task.slackUserId)) };
+  }
+  return undefined;
+}
+
 /**
  * Slim attachment projection for the `task_assigned` poll trigger — just
  * enough (id, name, mimeType, sizeBytes) for the worker to build a one-shot
@@ -223,6 +260,9 @@ export async function handlePoll(
   queryParams: URLSearchParams,
   myAgentId: string | undefined,
 ): Promise<boolean> {
+  const runtimeInstanceId = ((h) => (Array.isArray(h) ? h[0] : h))(
+    req.headers["x-runtime-instance-id"],
+  );
   // Handle cursor commit endpoint
   if (commitCursorsRoute.match(req.method, pathSegments)) {
     const parsed = await commitCursorsRoute.parse(req, res, pathSegments, queryParams);
@@ -266,18 +306,37 @@ export async function handlePoll(
           return { error: "Agent not found", status: 404 };
         }
 
+        // A process whose runtime has been retired must not be handed work: it
+        // would execute alongside whatever replaced it. Dispatch is gated on a
+        // live runtime identity rather than on X-Agent-ID alone, which only
+        // names the logical agent. Polling is worker activity, so this also
+        // refreshes liveness — it cannot revive a retired runtime, since the
+        // update only matches one that is still live.
+        if (
+          isMultiRuntimeEnabled() &&
+          !(runtimeInstanceId && touchRuntimeInstance(runtimeInstanceId, agent.id))
+        ) {
+          return { trigger: null };
+        }
+
         // Check for offered tasks first (highest priority for both workers and leads)
-        // Atomically claim the task for review to prevent duplicate processing
-        const offeredTasks = getOfferedTasksForAgent(myAgentId);
+        // Atomically claim the task for review to prevent duplicate processing.
+        // Capacity is checked in the same transaction as the claim: with
+        // several runtimes serving one agent these polls run concurrently, and
+        // an unguarded claim here would let each of them take a task past the
+        // agent's logical limit.
+        const offeredTasks = hasCapacity(myAgentId) ? getOfferedTasksForAgent(myAgentId) : [];
         const firstOfferedTask = offeredTasks[0];
         if (firstOfferedTask) {
           const claimedTask = claimOfferedTask(firstOfferedTask.id, myAgentId);
           if (claimedTask) {
+            const offeredRequestedBy = buildTriggerRequestedBy(claimedTask);
             return {
               trigger: {
                 type: "task_offered",
                 taskId: claimedTask.id,
                 task: claimedTask,
+                ...(offeredRequestedBy && { requestedBy: offeredRequestedBy }),
               },
             };
           }
@@ -337,6 +396,7 @@ export async function handlePoll(
 
             // Mark task as in_progress immediately to prevent duplicate polling
             startTask(pendingTask.id);
+            updateAgentStatusFromCapacity(myAgentId);
 
             ensure({
               id: "started",
@@ -360,19 +420,9 @@ export async function handlePoll(
               agentId: myAgentId,
             });
 
-            // Resolve requesting user if available. If the task carries a
-            // machine-recorded external id (today: the Slack user field) but
-            // no requestedByUserId, render the explicit UNKNOWN sentinel
-            // instead of silently omitting the section — never a substituted
-            // human (Rule 33 / provenance-or-silence).
-            const requestedByUser = pendingTask.requestedByUserId
-              ? getUserById(pendingTask.requestedByUserId)
-              : undefined;
-            const requestedByNotes = getRequesterNotes(requestedByUser?.notes);
-            const requestedByUnknownName =
-              !requestedByUser && pendingTask.slackUserId
-                ? renderIdentity(resolveIdentity("slack", pendingTask.slackUserId))
-                : undefined;
+            // Resolve requesting user if available (UNKNOWN sentinel handling
+            // lives in buildTriggerRequestedBy).
+            const assignedRequestedBy = buildTriggerRequestedBy(pendingTask);
 
             return {
               trigger: {
@@ -383,17 +433,7 @@ export async function handlePoll(
                   status: "in_progress",
                   attachments: attachmentsForTrigger(pendingTask.id),
                 },
-                ...(requestedByUser && {
-                  requestedBy: {
-                    name: requestedByUser.name,
-                    email: requestedByUser.email,
-                    role: requestedByUser.role,
-                    notes: requestedByNotes,
-                  },
-                }),
-                ...(requestedByUnknownName && {
-                  requestedBy: { name: requestedByUnknownName },
-                }),
+                ...(assignedRequestedBy && { requestedBy: assignedRequestedBy }),
               },
             };
           }
@@ -499,16 +539,19 @@ export async function handlePoll(
             for (const candidateId of unassignedIds) {
               const claimed = claimTask(candidateId, myAgentId);
               if (claimed) {
+                updateAgentStatusFromCapacity(myAgentId);
                 telemetry.taskEvent("claimed", {
                   taskId: claimed.id,
                   source: claimed.source,
                   agentId: myAgentId,
                 });
+                const claimedRequestedBy = buildTriggerRequestedBy(claimed);
                 return {
                   trigger: {
                     type: "task_assigned",
                     taskId: claimed.id,
                     task: { ...claimed, attachments: attachmentsForTrigger(claimed.id) },
+                    ...(claimedRequestedBy && { requestedBy: claimedRequestedBy }),
                   },
                 };
               }

package/src/http/route-def.ts

@@ -1,6 +1,7 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import { z } from "zod";
 import type { PermissionVerb } from "../rbac";
+import { scrubSecrets } from "../utils/secret-scrubber";
 import { jsonError, matchRoute, parseBody } from "./utils";
 
 // ─── Types ───────────────────────────────────────────────────────────────────
@@ -25,6 +26,24 @@ type ResponsesDef = Record<number, RouteResponseDef>;
 /** Extracts the payload type respond() accepts for one response def. */
 type ResponseData<R> = R extends { schema: infer S extends z.ZodType } ? z.input<S> : never;
 
+/**
+ * Optional `X-Runtime-Instance-ID` header shared by the lifecycle and poll
+ * routes. Optional in the schema because the requirement is conditional:
+ * only multi-runtime mode needs it, and legacy deployments must keep working
+ * without it.
+ */
+export const runtimeInstanceHeader = (operation: string) =>
+  z.object({
+    "X-Runtime-Instance-ID": z
+      .string()
+      .optional()
+      .describe(
+        "Identifies the concrete runtime instance (worker process) making the call, " +
+          `as generated at its boot. Required to ${operation} when multi-runtime mode ` +
+          "(MULTI_RUNTIME_ENABLED) is on; ignored otherwise.",
+      ),
+  });
+
 export interface RouteDef<
   TParams extends z.ZodType = z.ZodType,
   TQuery extends z.ZodType = z.ZodType,
@@ -41,6 +60,14 @@ export interface RouteDef<
   tags: string[];
   params?: TParams;
   query?: TQuery;
+  /**
+   * Request headers to publish as OpenAPI parameters, beyond the global
+   * `Authorization`/`X-Agent-ID` security schemes. Declaration-only: handlers
+   * still read headers off `req`, so adding this to a route changes the
+   * generated spec and nothing else. Mark each property `.optional()` unless
+   * the header is unconditionally required.
+   */
+  headers?: z.ZodObject;
   body?: TBody;
   responses: TResponses;
   auth?: {
@@ -187,10 +214,14 @@ export function describeRequestRoute(
 // ─── Factory ─────────────────────────────────────────────────────────────────
 
 /**
- * Runtime response validation gate for `respond()`. NODE_ENV is deliberately
- * unset on prod deploys, so this is opt-in outside `bun test` (which sets
- * NODE_ENV=test): response schemas must never introduce a production failure
- * mode — they fail loudly in tests and (opt-in) local dev instead.
+ * Runtime response validation gate for `respond()`. Only `bun test`
+ * (NODE_ENV=test) fails hard on a violation: one bad row must never take an
+ * endpoint down outside tests (2026-08-18 incident — a single priority='high'
+ * row 500'd every task listing). When the gate is on outside tests
+ * (NODE_ENV=development, or VALIDATE_HTTP_RESPONSES=true), `respond()` logs
+ * the violation and sends the response anyway. Note: the compiled Bun binary
+ * defaults NODE_ENV to "development", so deploys must also set
+ * NODE_ENV=production explicitly (see the deploy-env change in the fix PR).
  */
 const VALIDATE_RESPONSES =
   process.env.NODE_ENV === "test" ||
@@ -216,12 +247,15 @@ export function route<
         if (schema) {
           const result = schema.safeParse(data);
           if (!result.success) {
-            throw new Error(
+            const detail =
               `Response schema violation: ${def.method.toUpperCase()} ${def.path} ${code} — ` +
-                result.error.issues
-                  .map((i) => `${i.path.join(".") || "<root>"}: ${i.message}`)
-                  .join("; "),
-            );
+              result.error.issues
+                .map((i) => `${i.path.join(".") || "<root>"}: ${i.message}`)
+                .join("; ");
+            if (process.env.NODE_ENV === "test") {
+              throw new Error(detail);
+            }
+            console.error(`[route-def] ${scrubSecrets(detail)}`);
           }
         }
       }

package/src/http/schedules.ts

@@ -40,7 +40,7 @@ const scheduleUpdateBodySchema = z.object({
   taskTemplate: z.string().optional(),
   taskType: z.string().optional(),
   tags: z.array(z.string()).optional(),
-  priority: z.number().int().optional(),
+  priority: z.number().int().min(0).max(100).optional(),
   targetAgentId: z.string().nullable().optional(),
   enabled: z.boolean().optional(),
   timezone: z.string().optional(),
@@ -96,7 +96,7 @@ const createSchedule = route({
     taskTemplate: z.string().min(1).optional(),
     taskType: z.string().optional(),
     tags: z.array(z.string()).optional(),
-    priority: z.number().int().optional(),
+    priority: z.number().int().min(0).max(100).optional(),
     targetAgentId: z.string().optional(),
     enabled: z.boolean().optional(),
     timezone: z.string().optional(),