@vellumai/assistant 0.10.12 → 0.11.0-staging.2

package/src/runtime/routes/upgrade-broadcast-routes.ts

@@ -8,8 +8,7 @@ import { z } from "zod";
 import type { ServiceGroupUpdateCompleteEvent } from "../../api/events/service-group-update-complete.js";
 import type { ServiceGroupUpdateProgressEvent } from "../../api/events/service-group-update-progress.js";
 import type { ServiceGroupUpdateStartingEvent } from "../../api/events/service-group-update-starting.js";
-import { buildAssistantEvent } from "../assistant-event.js";
-import { assistantEventHub } from "../assistant-event-hub.js";
+import { broadcastMessage } from "../assistant-event-hub.js";
 import { GATEWAY_PRINCIPALS } from "../auth/route-policy.js";
 import { BadRequestError } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
@@ -48,7 +47,7 @@ async function handleUpgradeBroadcast({ body }: RouteHandlerArgs) {
       expectedDowntimeSeconds: downtime,
     };
 
-    await assistantEventHub.publish(buildAssistantEvent(message));
+    broadcastMessage(message);
 
     return { ok: true };
   }
@@ -67,7 +66,7 @@ async function handleUpgradeBroadcast({ body }: RouteHandlerArgs) {
       statusMessage,
     };
 
-    await assistantEventHub.publish(buildAssistantEvent(message));
+    broadcastMessage(message);
 
     return { ok: true };
   }
@@ -108,7 +107,7 @@ async function handleUpgradeBroadcast({ body }: RouteHandlerArgs) {
         : {}),
     };
 
-    await assistantEventHub.publish(buildAssistantEvent(message));
+    broadcastMessage(message);
 
     return { ok: true };
   }

package/src/runtime/routes/webhook-routes.ts

@@ -3,9 +3,8 @@
  *
  * Serves two operations:
  *   - webhooks_register (POST webhooks/register): Resolve a stable callback URL
- *     for a webhook type, registering with the platform gateway on
- *     platform-managed assistants or using the configured ingress.publicBaseUrl
- *     on self-hosted assistants.
+ *     for a webhook type. See `handleWebhooksRegister` for the resolution
+ *     order.
  *   - webhooks_list (GET webhooks): List all webhook callback routes registered
  *     with the platform for this assistant.
  */
@@ -18,7 +17,10 @@ import {
   registerCallbackRoute,
   resolvePlatformCallbackRegistrationContext,
 } from "../../inbound/platform-callback-registration.js";
-import { getPublicBaseUrl } from "../../inbound/public-ingress-urls.js";
+import {
+  getPublicBaseUrl,
+  type IngressConfig,
+} from "../../inbound/public-ingress-urls.js";
 import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
 import {
   BadRequestError,
@@ -77,10 +79,66 @@ function deriveWebhookPath(type: string): string {
   return `webhooks/${type.replace(/_/g, "/")}`;
 }
 
+/**
+ * Register `webhookPath` with the platform gateway, mapping failures onto the
+ * route error vocabulary.
+ */
+async function registerWithPlatform(
+  webhookPath: string,
+  type: string,
+  source: string | undefined,
+): Promise<WebhooksRegisterResponse> {
+  let callbackUrl: string;
+  try {
+    callbackUrl = await registerCallbackRoute(webhookPath, type, source);
+  } catch (err) {
+    const msg = (err as Error).message;
+    if (msg.includes("missing platform registration context")) {
+      throw new UnprocessableEntityError(msg);
+    }
+    throw new InternalError(`Failed to register callback route: ${msg}`);
+  }
+  return { callbackUrl, type, path: webhookPath, mode: "platform" };
+}
+
+/**
+ * True when the user has explicitly switched public ingress off.
+ *
+ * An explicit opt-out is a decision not to accept inbound webhooks at all, so
+ * it must not be silently routed around via platform callbacks. An *absent*
+ * ingress config is merely "not set up yet" and is eligible for the platform
+ * fallback.
+ */
+function isPublicIngressDisabled(config: IngressConfig): boolean {
+  return config.ingress?.enabled === false;
+}
+
 // ---------------------------------------------------------------------------
 // Handlers
 // ---------------------------------------------------------------------------
 
+/**
+ * Resolve a stable callback URL for a webhook type.
+ *
+ * Resolution order:
+ *   1. **Platform pods** (`IS_PLATFORM`) always register with the platform
+ *      gateway: they have no ingress of their own to advertise.
+ *   2. **A configured public ingress wins** for everyone else. That URL is
+ *      either the user's own tunnel (ngrok, a custom domain) or the Velay
+ *      tunnel URL the gateway publishes into `ingress.publicBaseUrl`, so a
+ *      platform-connected local assistant with a live tunnel already resolves
+ *      to a stable platform-owned URL here.
+ *   3. **Platform-connected assistants with no ingress** register with the
+ *      platform gateway rather than failing. Connectivity is decided by
+ *      credentials (platform base URL + assistant ID + assistant API key), not
+ *      by `IS_PLATFORM`, which is only ever true on a platform pod.
+ *
+ * Ingress deliberately precedes platform registration: any logged-in local
+ * assistant holds platform credentials (it needs them for the LLM proxy), so
+ * treating credential presence as "managed" would silently reroute an
+ * explicitly configured self-hosted webhook through the platform. The gateway's
+ * Telegram and email registrars order the same two tiers the same way.
+ */
 async function handleWebhooksRegister(
   args: RouteHandlerArgs,
 ): Promise<WebhooksRegisterResponse> {
@@ -92,39 +150,40 @@ async function handleWebhooksRegister(
 
   const webhookPath =
     (pathOverride as string | undefined) ?? deriveWebhookPath(type as string);
+  const sourceIdentifier = source as string | undefined;
 
   if (getIsPlatform()) {
-    let callbackUrl: string;
-    try {
-      callbackUrl = await registerCallbackRoute(
-        webhookPath,
-        type as string,
-        source as string | undefined,
-      );
-    } catch (err) {
-      const msg = (err as Error).message;
-      if (msg.includes("missing platform registration context")) {
-        throw new UnprocessableEntityError(msg);
-      }
-      throw new InternalError(`Failed to register callback route: ${msg}`);
-    }
-    return { callbackUrl, type, path: webhookPath, mode: "platform" };
+    return registerWithPlatform(webhookPath, type, sourceIdentifier);
   }
 
-  // Self-hosted: use ingress.publicBaseUrl
   const config = getConfig();
-  let baseUrl: string;
+  if (isPublicIngressDisabled(config)) {
+    throw new UnprocessableEntityError(
+      "Public ingress is disabled. Ask the assistant to enable it, or update it from the Settings page.",
+    );
+  }
+
+  let ingressError: Error;
   try {
-    baseUrl = getPublicBaseUrl(config);
+    const baseUrl = getPublicBaseUrl(config);
+    return {
+      callbackUrl: `${baseUrl}/${webhookPath}`,
+      type,
+      path: webhookPath,
+      mode: "self-hosted",
+    };
   } catch (err) {
-    throw new UnprocessableEntityError((err as Error).message);
+    ingressError = err as Error;
   }
-  return {
-    callbackUrl: `${baseUrl}/${webhookPath}`,
-    type,
-    path: webhookPath,
-    mode: "self-hosted",
-  };
+
+  // No ingress configured. Fall back to the platform gateway when this
+  // assistant is connected to the platform.
+  const context = await resolvePlatformCallbackRegistrationContext();
+  if (context.enabled) {
+    return registerWithPlatform(webhookPath, type, sourceIdentifier);
+  }
+
+  throw new UnprocessableEntityError(ingressError.message);
 }
 
 async function handleWebhooksList(
@@ -189,7 +248,7 @@ export const ROUTES: RouteDefinition[] = [
     },
     summary: "Register a webhook callback URL",
     description:
-      "Resolves a stable callback URL for a webhook type. On platform-managed assistants, registers the route with the platform gateway. On self-hosted assistants, uses the configured ingress.publicBaseUrl.",
+      "Resolves a stable callback URL for a webhook type. On platform-managed assistants, registers the route with the platform gateway. Otherwise uses the configured ingress.publicBaseUrl, falling back to the platform gateway when no ingress is configured and the assistant is connected to the platform.",
     tags: ["webhooks"],
     requestBody: WebhooksRegisterRequestSchema,
     responseBody: WebhooksRegisterResponseSchema,

package/src/runtime/routes/workspace-routes.test.ts

@@ -17,8 +17,8 @@ import {
 import { join } from "node:path";
 import { beforeAll, describe, expect, test } from "bun:test";
 
+import type { AssistantEventEnvelope } from "../../api/index.js";
 import { SYNC_TAGS } from "../../daemon/message-types/sync.js";
-import type { AssistantEvent } from "../assistant-event.js";
 import { assistantEventHub } from "../assistant-event-hub.js";
 
 // ---------------------------------------------------------------------------
@@ -66,15 +66,18 @@ beforeAll(() => {
 
 function getRoute(operationId: string): RouteDefinition {
   const route = ROUTES.find((r) => r.operationId === operationId);
-  if (!route)
+  if (!route) {
     throw new Error(`No shared route found for operationId: ${operationId}`);
+  }
   return route;
 }
 
 async function waitFor(predicate: () => boolean): Promise<void> {
   const deadline = Date.now() + 500;
   while (Date.now() < deadline) {
-    if (predicate()) return;
+    if (predicate()) {
+      return;
+    }
     await new Promise((resolve) => setTimeout(resolve, 5));
   }
   throw new Error("Timed out waiting for workspace route event");
@@ -557,7 +560,7 @@ describe("POST /v1/workspace/write", () => {
   });
 
   test("publishes sounds sync events when writing sounds config", async () => {
-    const received: AssistantEvent[] = [];
+    const received: AssistantEventEnvelope[] = [];
     const subscription = assistantEventHub.subscribe({
       type: "process",
       callback: (event) => {

package/src/runtime/slack-reply-session.test.ts

@@ -28,7 +28,7 @@ mock.module("./gateway-client.js", () => ({
   },
 }));
 
-import type { ServerMessage } from "../daemon/message-protocol.js";
+import type { AssistantEvent } from "../api/index.js";
 import { SLACK_STREAM_MARKDOWN_LIMIT } from "../messaging/providers/slack/api.js";
 import {
   createSlackReplySession,
@@ -39,34 +39,34 @@ const CHANNEL = "D-STREAM";
 const THREAD_TS = "1700000000.000001";
 const CALLBACK_URL = `https://example.test/deliver/slack?channel=${CHANNEL}&threadTs=${THREAD_TS}`;
 
-const textDelta = (text: string): ServerMessage =>
+const textDelta = (text: string): AssistantEvent =>
   ({
     type: "assistant_text_delta",
     text,
     conversationId: "conv-stream",
-  }) as ServerMessage;
+  }) as AssistantEvent;
 
-const toolUseStart = (toolUseId: string): ServerMessage =>
+const toolUseStart = (toolUseId: string): AssistantEvent =>
   ({
     type: "tool_use_start",
     toolName: "web_search",
     input: { query: "example" },
     conversationId: "conv-stream",
     toolUseId,
-  }) as ServerMessage;
+  }) as AssistantEvent;
 
-const messageComplete = (messageId: string): ServerMessage =>
+const messageComplete = (messageId: string): AssistantEvent =>
   ({
     type: "message_complete",
     conversationId: "conv-stream",
     messageId,
-  }) as ServerMessage;
+  }) as AssistantEvent;
 
 const taskProgressShow = (
   surfaceId: string,
   steps: Array<{ label: string; status: string; detail?: string }>,
   templateTitle?: string,
-): ServerMessage =>
+): AssistantEvent =>
   ({
     type: "ui_surface_show",
     conversationId: "conv-stream",
@@ -80,18 +80,18 @@ const taskProgressShow = (
         steps,
       },
     },
-  }) as ServerMessage;
+  }) as AssistantEvent;
 
 const taskProgressUpdate = (
   surfaceId: string,
   steps: Array<{ label: string; status: string }>,
-): ServerMessage =>
+): AssistantEvent =>
   ({
     type: "ui_surface_update",
     conversationId: "conv-stream",
     surfaceId,
     data: { templateData: { steps } },
-  }) as ServerMessage;
+  }) as AssistantEvent;
 
 const tick = (ms: number): Promise<void> =>
   new Promise((resolve) => setTimeout(resolve, ms));
@@ -351,7 +351,7 @@ describe("createSlackReplySession", () => {
   test("falls back when stopStream throws after streaming text", async () => {
     deliverImpl = async (_url, payload) => {
       const op = payload.slackStream as { action: string };
-      if (op.action === "stop") throw new Error("stop failed");
+      if (op.action === "stop") {throw new Error("stop failed");}
       return { ok: true, ts: "stream-ts-1" };
     };
     const session = createSlackReplySession({

package/src/runtime/slack-reply-session.ts

@@ -1,5 +1,6 @@
 import type { SlackStreamTask } from "@vellumai/gateway-client";
 
+import type { AssistantEvent } from "../api/index.js";
 import {
   extractThreadTsFromCallbackUrl,
   isSlackDeliveryCallbackUrl,
@@ -9,7 +10,6 @@ import {
   incompleteVellumLinkSuffixLength,
   stripVellumLinks,
 } from "../daemon/assistant-attachments.js";
-import type { ServerMessage } from "../daemon/message-protocol.js";
 import { SLACK_STREAM_MARKDOWN_LIMIT } from "../messaging/providers/slack/api.js";
 import { renderSlackBlocks } from "../messaging/providers/slack/render.js";
 import { getLogger } from "../util/logger.js";
@@ -51,7 +51,7 @@ export type SlackStreamReconciliation =
   | { mode: "fallback" };
 
 export type SlackReplySession = {
-  observeEvent: (msg: ServerMessage) => void;
+  observeEvent: (msg: AssistantEvent) => void;
   /**
    * Settle in-flight stream operations, finalize the stream, and report how
    * durable delivery should reconcile. Call once after processing completes.
@@ -79,12 +79,12 @@ export function shouldStreamSlackReply(params: {
   recipientUserId?: string;
   recipientTeamId?: string;
 }): boolean {
-  if (params.sourceChannel !== "slack") return false;
-  if (!isSlackDeliveryCallbackUrl(params.replyCallbackUrl)) return false;
+  if (params.sourceChannel !== "slack") {return false;}
+  if (!isSlackDeliveryCallbackUrl(params.replyCallbackUrl)) {return false;}
   if (extractThreadTsFromCallbackUrl(params.replyCallbackUrl) === null) {
     return false;
   }
-  if (params.chatType === "im") return true;
+  if (params.chatType === "im") {return true;}
   return Boolean(params.recipientUserId && params.recipientTeamId);
 }
 
@@ -130,7 +130,7 @@ export function createSlackReplySession(params: {
   const coalesceMs = params.coalesceMs ?? STREAM_COALESCE_MS;
   const replyCallbackUrl = params.replyCallbackUrl;
   const threadTs = extractThreadTsFromCallbackUrl(replyCallbackUrl);
-  if (threadTs === null) return undefined;
+  if (threadTs === null) {return undefined;}
 
   let state: StreamState = "idle";
   let started = false;
@@ -172,7 +172,7 @@ export function createSlackReplySession(params: {
   // (and `stripVellumLinks` can remove it). Once `finished`, no delta can
   // extend the text, so the full cleaned reply is safe to emit.
   const streamableText = (): string => {
-    if (finished) return cleanedText();
+    if (finished) {return cleanedText();}
     const hold = incompleteVellumLinkSuffixLength(rawText);
     const stable = hold > 0 ? rawText.slice(0, rawText.length - hold) : rawText;
     return stripVellumLinks(stable).replace(NO_RESPONSE_INLINE_RE, "");
@@ -205,7 +205,7 @@ export function createSlackReplySession(params: {
   const enqueueStart = (): void => {
     enqueue(async () => {
       const clean = streamableText();
-      if (clean.trim().length === 0) return;
+      if (clean.trim().length === 0) {return;}
       const firstChunk = clean.slice(0, SLACK_STREAM_MARKDOWN_LIMIT);
       const title = activeProgress?.title;
       const tasks = planTasks();
@@ -259,7 +259,7 @@ export function createSlackReplySession(params: {
 
   const enqueueAppend = (): void => {
     enqueue(async () => {
-      if (state !== "streaming" || !streamTs) return;
+      if (state !== "streaming" || !streamTs) {return;}
       const clean = streamableText();
       const title = activeProgress?.title;
       const tasks = planTasks();
@@ -329,9 +329,9 @@ export function createSlackReplySession(params: {
       clearTimeout(coalesceTimer);
       coalesceTimer = undefined;
     }
-    if (finished || state === "fallback") return;
+    if (finished || state === "fallback") {return;}
     if (!started) {
-      if (!hasDeliverableAssistantText(streamableText())) return;
+      if (!hasDeliverableAssistantText(streamableText())) {return;}
       started = true;
       enqueueStart();
       return;
@@ -340,7 +340,7 @@ export function createSlackReplySession(params: {
   };
 
   const scheduleFlush = (): void => {
-    if (coalesceTimer || finished) return;
+    if (coalesceTimer || finished) {return;}
     coalesceTimer = setTimeout(() => {
       coalesceTimer = undefined;
       flush();
@@ -356,15 +356,15 @@ export function createSlackReplySession(params: {
     }
   };
 
-  const observeTaskProgress = (msg: ServerMessage): void => {
+  const observeTaskProgress = (msg: AssistantEvent): void => {
     if (msg.type === "ui_surface_show") {
       const progress = getTaskProgressDataFromSurfaceData(msg.data);
-      if (!progress) return;
+      if (!progress) {return;}
       taskProgressBySurfaceId.set(msg.surfaceId, progress);
     } else if (msg.type === "ui_surface_update") {
       const existing = taskProgressBySurfaceId.get(msg.surfaceId);
       const progress = mergeTaskProgressData(existing, msg.data);
-      if (!progress) return;
+      if (!progress) {return;}
       taskProgressBySurfaceId.set(msg.surfaceId, progress);
     } else {
       return;
@@ -375,7 +375,7 @@ export function createSlackReplySession(params: {
 
   return {
     observeEvent(msg) {
-      if (finished) return;
+      if (finished) {return;}
 
       if (msg.type === "ui_surface_show" || msg.type === "ui_surface_update") {
         observeTaskProgress(msg);
@@ -415,7 +415,7 @@ export function createSlackReplySession(params: {
 
       enqueueAppend();
       enqueue(async () => {
-        if (state !== "streaming" || !streamTs) return;
+        if (state !== "streaming" || !streamTs) {return;}
         const clean = cleanedText();
         const remaining = clean.slice(confirmedLength);
         const blocks = imageBlocks(clean);

package/src/runtime/sync/sync-publisher.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, test } from "bun:test";
 
+import type { AssistantEventEnvelope } from "../../api/index.js";
 import { SYNC_TAGS } from "../../daemon/message-types/sync.js";
-import type { AssistantEvent } from "../assistant-event.js";
 import { assistantEventHub, broadcastMessage } from "../assistant-event-hub.js";
 import { publishSyncInvalidation } from "./sync-publisher.js";
 
@@ -18,7 +18,7 @@ async function waitFor(predicate: () => boolean): Promise<void> {
 
 describe("sync publisher", () => {
   test("publishes a deduped sync_changed event", async () => {
-    const received: AssistantEvent[] = [];
+    const received: AssistantEventEnvelope[] = [];
     const subscription = assistantEventHub.subscribe({
       type: "process",
       callback: (event) => {
@@ -104,7 +104,7 @@ describe("sync publisher", () => {
   });
 
   test("forwards originClientId when provided", async () => {
-    const received: AssistantEvent[] = [];
+    const received: AssistantEventEnvelope[] = [];
     const subscription = assistantEventHub.subscribe({
       type: "process",
       callback: (event) => {
@@ -132,7 +132,7 @@ describe("sync publisher", () => {
   });
 
   test("omits originClientId when not provided", async () => {
-    const received: AssistantEvent[] = [];
+    const received: AssistantEventEnvelope[] = [];
     const subscription = assistantEventHub.subscribe({
       type: "process",
       callback: (event) => {
@@ -141,7 +141,9 @@ describe("sync publisher", () => {
     });
 
     try {
-      const message = await publishSyncInvalidation([SYNC_TAGS.assistantAvatar]);
+      const message = await publishSyncInvalidation([
+        SYNC_TAGS.assistantAvatar,
+      ]);
 
       await waitFor(() => received.length === 1);
 

package/src/runtime/tool-grant-request-helper.ts

@@ -21,6 +21,7 @@ import {
   recordApprovalCardDelivery,
   recordGuardianRequestDeliveries,
 } from "../notifications/guardian-delivery-recorder.js";
+import { buildVellumCardAffinity } from "../notifications/vellum-card-affinity.js";
 import { getLogger } from "../util/logger.js";
 import { resolveApprovalSourceReference } from "./approval-source-link.js";
 import { getGuardianBinding } from "./channel-verification-service.js";
@@ -177,6 +178,9 @@ export async function createOrReuseToolGrantRequest(
     sourceChannel,
     sourceContextId: conversationId,
     requiresConversation: true,
+    // Pin the in-app (vellum) card to the conversation the escalated tool is
+    // running in, so the guardian decides it in context.
+    ...(buildVellumCardAffinity(conversationId) ?? {}),
     attentionHints: {
       requiresAction: true,
       urgency: "high",

package/src/schedule/schedule-store.ts

@@ -3,6 +3,7 @@ import { and, asc, desc, eq, isNull, lt, lte, sql } from "drizzle-orm";
 import { v4 as uuid } from "uuid";
 
 import { getDb } from "../persistence/db-connection.js";
+import { isLifecycleQuiesced } from "../persistence/lifecycle-quiesce.js";
 import { rawChanges } from "../persistence/raw-query.js";
 import { scheduleJobs, scheduleRuns } from "../persistence/schema/index.js";
 import { publishSchedulesChanged } from "../runtime/sync/resource-sync-events.js";
@@ -465,6 +466,15 @@ export async function deleteSchedule(id: string): Promise<boolean> {
  * next_run_at <= now and enabled = true and cron_expression IS NULL.
  */
 export async function claimDueSchedules(now: number): Promise<ScheduleJob[]> {
+  // Drain gate: while a quiesce lease is active, claim nothing so in-flight
+  // runs can drain before a stop. The check lives here — immediately before
+  // the claim writes — rather than at the tick boundary, to shrink the window
+  // in which a lease armed mid-tick could miss a claim that already passed an
+  // earlier check. Fail-open via the lease read.
+  if (isLifecycleQuiesced()) {
+    return [];
+  }
+
   const db = getDb();
   const claimed: ScheduleJob[] = [];
 
@@ -750,6 +760,27 @@ export async function createScheduleRun(
   return id;
 }
 
+/** Currently-running schedule runs with their job names, oldest first. */
+export function listRunningScheduleRuns(): Array<{
+  runId: string;
+  scheduleName: string | null;
+  startedAt: number;
+}> {
+  const db = getDb();
+  return db
+    .select({
+      runId: scheduleRuns.id,
+      scheduleName: scheduleJobs.name,
+      startedAt: scheduleRuns.startedAt,
+    })
+    .from(scheduleRuns)
+    .leftJoin(scheduleJobs, eq(scheduleRuns.jobId, scheduleJobs.id))
+    .where(eq(scheduleRuns.status, "running"))
+    .orderBy(asc(scheduleRuns.startedAt))
+    .limit(20)
+    .all();
+}
+
 export async function setScheduleRunConversationId(
   runId: string,
   conversationId: string,
@@ -1082,6 +1113,45 @@ export function describeCronExpression(expr: string | null): string {
   }
 }
 
+/**
+ * Return a claimed-but-not-started schedule to the queue (drain deferral).
+ *
+ * Restores everything the claim mutated before any execution began:
+ * `nextRunAt` is pulled to `nextRetryAt`, a one-shot's `firing` reverts to
+ * `active`, and `enabled` is restored — a bounded recurring schedule's final
+ * occurrence is claimed by exhausting the job (`enabled = false`,
+ * `nextRunAt = 0`), so without the restore that deferred final occurrence
+ * would never fire.
+ */
+export async function deferClaimedSchedule(
+  id: string,
+  nextRetryAt: number,
+): Promise<void> {
+  const db = getDb();
+  const now = Date.now();
+  await withSqliteRetry(
+    () => {
+      db.update(scheduleJobs)
+        .set({ nextRunAt: nextRetryAt, enabled: true, updatedAt: now })
+        .where(eq(scheduleJobs.id, id))
+        .run();
+      return rawChanges() > 0;
+    },
+    { op: "deferClaimedSchedule.requeue", context: { scheduleId: id } },
+  );
+  await withSqliteRetry(
+    () => {
+      db.update(scheduleJobs)
+        .set({ status: "active", updatedAt: now })
+        .where(and(eq(scheduleJobs.id, id), eq(scheduleJobs.status, "firing")))
+        .run();
+      return rawChanges() > 0;
+    },
+    { op: "deferClaimedSchedule.status", context: { scheduleId: id } },
+  );
+  notifySchedulesChanged();
+}
+
 /**
  * Set the next retry time for a schedule and revert one-shot status from
  * "firing" to "active" so the scheduler will claim it again when nextRetryAt

package/src/schedule/scheduler.ts

@@ -9,6 +9,7 @@ import { processMessage } from "../daemon/process-message.js";
 import { INTERNAL_GUARDIAN_TRUST_CONTEXT } from "../daemon/trust-context.js";
 import { emitNotificationSignal } from "../notifications/emit-signal.js";
 import { getConversation } from "../persistence/conversation-crud.js";
+import { isLifecycleQuiesced } from "../persistence/lifecycle-quiesce.js";
 import { invalidateAssistantInferredItemsForConversation } from "../plugins/defaults/memory/task-memory-cleanup.js";
 import { wakeAgentForOpportunity } from "../runtime/agent-wake.js";
 import { broadcastMessage } from "../runtime/assistant-event-hub.js";
@@ -33,6 +34,7 @@ import {
   completeOneShot,
   completeScheduleRun,
   createScheduleRun,
+  deferClaimedSchedule,
   failOneShotPermanently,
   getLastScheduleConversationId,
   resetRetryCount,
@@ -434,6 +436,9 @@ export async function runScheduleDueWorkOnce(
     return result;
   }
 
+  // The drain quiesce gates live inside claimDueWatchers and
+  // claimDueEnrollments, immediately before their claim writes.
+
   // ── Watchers (event-driven polling) ────────────────────────────────
   try {
     const watcherProcessed = await runWatchersOnce(emitWatcherNotifySignal);
@@ -463,6 +468,9 @@ export async function runScheduleDueWorkOnce(
  * (`worker.ts`). Claims are atomic in the schedule store, so overlapping ticks
  * cannot double-run a job another claim already took.
  */
+/** How far a claimed-but-quiesced schedule is pushed back into the queue. */
+const QUIESCE_DEFER_MS = 30_000;
+
 export async function runDueSchedulesOnce(
   now: number = Date.now(),
 ): Promise<SchedulerDueWorkResult> {
@@ -490,9 +498,28 @@ export async function runDueSchedulesOnce(
     return result;
   }
 
+  // The drain quiesce gate lives inside claimDueSchedules, immediately
+  // before the claim writes.
   const jobs = await claimDueSchedules(now);
   result.claimed = jobs.length;
   for (const job of jobs) {
+    // Lease re-check per claimed job: a lease armed between the batch claim
+    // and this job's start returns the job to the queue untouched instead of
+    // starting work the drain snapshot cannot see — notify mode especially,
+    // which emits before any run row exists.
+    if (isLifecycleQuiesced()) {
+      try {
+        await deferClaimedSchedule(job.id, Date.now() + QUIESCE_DEFER_MS);
+      } catch (err) {
+        log.warn(
+          { err, jobId: job.id },
+          "Failed to defer claimed schedule under quiesce",
+        );
+      }
+      result.skipped += 1;
+      continue;
+    }
+
     const isOneShot = job.expression == null;
 
     // ── Notify mode (one-shot or recurring) ─────────────────────────