@vellumai/assistant 0.11.2 → 0.11.3-staging.2

package/src/runtime/assistant-event-hub.ts

@@ -95,6 +95,20 @@ interface BaseSubscriberEntry {
   connectionId: string;
 }
 
+/**
+ * The presence states a desktop client may report. Single runtime source: the
+ * stored type and the route's wire enum both derive from this tuple.
+ */
+export const DESKTOP_PRESENCE_STATES = ["active", "idle", "away"] as const;
+
+export type DesktopPresenceState = (typeof DESKTOP_PRESENCE_STATES)[number];
+
+export interface ClientPresence {
+  state: DesktopPresenceState;
+  /** When the daemon last heard from the client. Drives staleness. */
+  reportedAt: Date;
+}
+
 interface ClientEntry extends BaseSubscriberEntry {
   type: "client";
   clientId: string;
@@ -111,6 +125,11 @@ interface ClientEntry extends BaseSubscriberEntry {
    * service-token connections that have no principal.
    */
   actorPrincipalId?: string;
+  /**
+   * Last desktop presence reported by this client, for clients that report it.
+   * In-memory only, so consumers must fail open when it is absent.
+   */
+  presence?: ClientPresence;
 }
 
 interface ProcessEntry extends BaseSubscriberEntry {
@@ -407,19 +426,30 @@ export class AssistantEventHub {
   }
 
   /**
-   * Return the active client subscriber with the given clientId, or
-   * `undefined` if no such subscriber exists.
+   * Yield every active client entry with the given clientId. `subscribe`
+   * disposes any prior entries for the same clientId, so at most one entry
+   * matches.
    */
-  getClientById(clientId: string): ClientEntry | undefined {
+  private *activeClientEntries(clientId: string): Generator<ClientEntry> {
     for (const entry of this.subscribers) {
       if (
         entry.active &&
         entry.type === "client" &&
         entry.clientId === clientId
       ) {
-        return entry;
+        yield entry;
       }
     }
+  }
+
+  /**
+   * Return the active client subscriber with the given clientId, or
+   * `undefined` if no such subscriber exists.
+   */
+  getClientById(clientId: string): ClientEntry | undefined {
+    for (const entry of this.activeClientEntries(clientId)) {
+      return entry;
+    }
     return undefined;
   }
 
@@ -435,6 +465,42 @@ export class AssistantEventHub {
     return this.getClientById(clientId)?.actorPrincipalId;
   }
 
+  /**
+   * Fill a missing `actorPrincipalId` on a live client subscription.
+   *
+   * Used by the SSE dev-bypass self-heal: when the guardian-delivery cache is
+   * cold at subscribe time, the registration lands without a principal; the
+   * route resolves it async and patches the record here. Keyed by
+   * `connectionId` (not clientId) so a reconnect race cannot patch the
+   * subscription that replaced the one being healed. No-op when the
+   * connection is gone or already carries a principal: this only fills a
+   * missing value, never overwrites one. The value must come from the
+   * daemon's own server-side guardian lookup, never from client input.
+   */
+  fillClientActorPrincipalId(
+    connectionId: string,
+    actorPrincipalId: string,
+  ): void {
+    for (const entry of this.subscribers) {
+      if (entry.connectionId !== connectionId) {
+        continue;
+      }
+      if (
+        !entry.active ||
+        entry.type !== "client" ||
+        entry.actorPrincipalId != null
+      ) {
+        return;
+      }
+      entry.actorPrincipalId = actorPrincipalId;
+      log.info(
+        { clientId: entry.clientId, connectionId },
+        "filled missing actorPrincipalId for client subscription",
+      );
+      return;
+    }
+  }
+
   /**
    * Returns true when at least one active subscriber would receive the given
    * event based on the same conversation matching rules as publish().
@@ -512,15 +578,24 @@ export class AssistantEventHub {
    */
   touchClient(clientId: string): void {
     const now = new Date();
-    for (const entry of this.subscribers) {
-      if (
-        entry.active &&
-        entry.type === "client" &&
-        entry.clientId === clientId
-      ) {
-        entry.lastActiveAt = now;
-      }
+    for (const entry of this.activeClientEntries(clientId)) {
+      entry.lastActiveAt = now;
+    }
+  }
+
+  /**
+   * Record the desktop presence state reported by a client. `reportedAt`
+   * always advances. Returns true when at least one active client entry
+   * matched.
+   */
+  setClientPresence(clientId: string, state: DesktopPresenceState): boolean {
+    const now = new Date();
+    let matched = false;
+    for (const entry of this.activeClientEntries(clientId)) {
+      entry.presence = { state, reportedAt: now };
+      matched = true;
     }
+    return matched;
   }
 
   /**

package/src/runtime/auth/__tests__/guard-tests.test.ts

@@ -276,6 +276,7 @@ describe("scope profile contract", () => {
       "internal.write",
     ],
     local_v1: ["local.all"],
+    speech_relay_v1: ["speech.relay"],
     ui_page_v1: ["settings.read"],
   };
 
@@ -299,6 +300,7 @@ describe("scope profile contract", () => {
       "gateway_ingress_v1",
       "gateway_service_v1",
       "local_v1",
+      "speech_relay_v1",
       "ui_page_v1",
     ];
 

package/src/runtime/auth/__tests__/scopes.test.ts

@@ -64,6 +64,26 @@ describe("resolveScopeProfile", () => {
     expect(scopes.size).toBe(7);
   });
 
+  test("speech_relay_v1 includes only speech.relay (ATL-1033 least-privilege)", () => {
+    const scopes = resolveScopeProfile("speech_relay_v1");
+    expect(scopes.has("speech.relay")).toBe(true);
+    expect(scopes.size).toBe(1);
+  });
+
+  test("unknown profiles resolve to no scopes, including prototype keys", () => {
+    // Claims come from JSON, so the ScopeProfile type does not protect at
+    // runtime. Unknown names and Object.prototype keys must both fail closed.
+    for (const profile of [
+      "bogus_v1",
+      "toString",
+      "constructor",
+      "__proto__",
+    ]) {
+      const scopes = resolveScopeProfile(profile as never);
+      expect(scopes.size).toBe(0);
+    }
+  });
+
   test("local_v1 includes only local.all", () => {
     const scopes = resolveScopeProfile("local_v1");
     expect(scopes.has("local.all")).toBe(true);

package/src/runtime/auth/same-actor.ts

@@ -18,9 +18,12 @@
  * Both paths log a single structured warn line on rejection with the
  * shape `{ sourceActorPrincipalId, targetClientId, targetActorPrincipalId,
  * op, reason }` so that bash, file, and CU rejections render identically
- * in the audit log.
+ * in the audit log. The user-facing wording differs by path: the proxy
+ * result names the failing comparison, while the HTTP 403 stays generic
+ * because it can reach a caller who does not own the target client.
  */
 import type { HostProxyCapability } from "../../channels/types.js";
+import { isHttpAuthDisabled } from "../../config/env.js";
 import { getLogger } from "../../util/logger.js";
 import type { AssistantEventHub } from "../assistant-event-hub.js";
 import { ForbiddenError } from "../routes/errors.js";
@@ -28,14 +31,39 @@ import { ForbiddenError } from "../routes/errors.js";
 const log = getLogger("same-actor");
 
 /**
- * Canonical user-facing rejection message. Used by both the proxy and
- * route paths so operators and auditors see identical wording regardless
- * of whether the failure surfaced as a tool-execution result or an HTTP
- * 403.
+ * Canonical user-facing rejection message for the HTTP/IPC route path,
+ * where the caller may be any principal and the reason must not describe
+ * the target client's internal state.
  */
 const REJECTION_MESSAGE =
   "Submitting actor does not match the target client's actor for this request. The targeted client's authenticated user must submit the result.";
 
+/**
+ * Per-reason rejection messages for the proxy path.
+ *
+ * The proxy's rejection is read by the agent (and, through the transcript,
+ * by the user) on their own turn, so it can and should name which of the
+ * three comparisons failed. Collapsing them into one sentence made a
+ * single-user desktop report that "the submitting actor does not match the
+ * target client's actor" in two cases where the two actors were never
+ * compared at all: the turn carried no actor principal, or the target
+ * client registered its SSE stream without one. Those have different fixes
+ * — re-establish the caller's identity versus reconnect the client — and
+ * neither is "sign in as the other user".
+ *
+ * The route path keeps {@link REJECTION_MESSAGE}: an HTTP 403 can reach a
+ * caller who is not the owner, and `missing_target` versus `mismatch` would
+ * describe a client that is not theirs.
+ */
+const PROXY_REJECTION_MESSAGES: Record<RejectionReason, string> = {
+  missing_source:
+    "This turn has no authenticated actor, so it cannot target a connected client. Host-proxy execution binds each request to the user who sent the message; retry from a signed-in client, or check that the assistant's guardian binding resolved.",
+  missing_target:
+    "The target client is connected but registered without an authenticated user, so it cannot be targeted. Quit and reopen the desktop app to re-register it, then retry.",
+  mismatch:
+    "Submitting actor does not match the target client's actor for this request. The target client is signed in as a different user — run `assistant clients list` to see which connected clients you own.",
+};
+
 /** OpenAPI 403 description for `*-result` endpoints, kept identical. */
 export const SAME_ACTOR_FORBIDDEN_DESCRIPTION =
   "Submitting client does not match the targeted client, or the submitting actor's principal does not match the target client's actor.";
@@ -74,6 +102,17 @@ export interface SameActorPersistedArgs {
   targetActorPrincipalId: string | undefined;
   targetClientId: string;
   op: SameActorOp;
+  /**
+   * Fill-if-missing fallback for dev-bypass deployments: when the PERSISTED
+   * target principal is absent (the request was registered before the SSE
+   * self-heal filled the target client's hub record), re-read the live hub
+   * record. Only consulted when `targetActorPrincipalId` is nullish AND HTTP
+   * auth is disabled. A present persisted value always wins, so a
+   * present-but-mismatched principal still rejects, and JWT-auth deployments
+   * are unaffected. The hub value is set server-side at SSE registration (or
+   * by the self-heal), never from client input.
+   */
+  hubForMissingTarget?: Pick<AssistantEventHub, "getActorPrincipalIdForClient">;
 }
 
 export type SameActorArgs = SameActorLiveArgs;
@@ -97,7 +136,12 @@ function detectRejection(
   const { sourceActorPrincipalId, targetClientId, op } = args;
   const targetActorPrincipalId = isLive(args)
     ? args.hub.getActorPrincipalIdForClient(targetClientId)
-    : args.targetActorPrincipalId;
+    : (args.targetActorPrincipalId ??
+      (isHttpAuthDisabled()
+        ? args.hubForMissingTarget?.getActorPrincipalIdForClient(
+            targetClientId,
+          )
+        : undefined));
 
   let reason: RejectionReason | undefined;
   if (sourceActorPrincipalId == null) {
@@ -147,14 +191,18 @@ export function enforceSameActorOrThrow(
  * on rejection (so the proxy can pass it directly back to the agent),
  * or `null` on success. Always uses the live hub lookup — proxy
  * registration runs while the target SSE subscription is active.
+ *
+ * The returned message names the failing comparison — see
+ * {@link PROXY_REJECTION_MESSAGES}.
  */
 export function enforceSameActorOrErrorResult(
   args: SameActorLiveArgs,
 ): { content: string; isError: true } | null {
-  if (detectRejection(args) == null) {
+  const reason = detectRejection(args);
+  if (reason == null) {
     return null;
   }
-  return { content: REJECTION_MESSAGE, isError: true };
+  return { content: PROXY_REJECTION_MESSAGES[reason], isError: true };
 }
 
 /**

package/src/runtime/auth/scopes.ts

@@ -38,15 +38,27 @@ const PROFILE_SCOPES: Record<ScopeProfile, ReadonlySet<Scope>> = {
     "internal.write",
   ]),
   local_v1: new Set<Scope>(["local.all"]),
+  // Managed speech relay only (ATL-1033): the daemon's relay-dial token must
+  // not open any other edge-scoped route.
+  speech_relay_v1: new Set<Scope>(["speech.relay"]),
   ui_page_v1: new Set<Scope>(["settings.read"]),
 };
 
+const EMPTY_SCOPES: ReadonlySet<Scope> = new Set();
+
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
 
 /** Resolve a scope profile name to its set of granted scopes. */
 export function resolveScopeProfile(profile: ScopeProfile): ReadonlySet<Scope> {
+  // Claims come from JSON, so an unrecognized profile (e.g. minted by a newer
+  // peer) can reach this despite the type. Resolve it to no scopes, not a
+  // TypeError in the caller. The own-property check keeps inherited keys
+  // ("toString", "constructor") failing closed too.
+  if (!Object.prototype.hasOwnProperty.call(PROFILE_SCOPES, profile)) {
+    return EMPTY_SCOPES;
+  }
   return PROFILE_SCOPES[profile];
 }
 

package/src/runtime/auth/types.ts

@@ -14,6 +14,7 @@ export type ScopeProfile =
   | "gateway_ingress_v1"
   | "gateway_service_v1"
   | "local_v1"
+  | "speech_relay_v1"
   | "ui_page_v1";
 
 // ---------------------------------------------------------------------------
@@ -35,6 +36,7 @@ export type Scope =
   | "internal.write"
   | "feature_flags.read"
   | "feature_flags.write"
+  | "speech.relay"
   | "local.all";
 
 // ---------------------------------------------------------------------------

package/src/runtime/background-job-runner.ts

@@ -22,11 +22,6 @@ import type { LLMCallSite } from "../config/schemas/llm.js";
 import { processMessage } from "../daemon/process-message.js";
 import type { SubagentToolGateMode } from "../daemon/tool-setup-types.js";
 import type { TrustContext } from "../daemon/trust-context-types.js";
-import {
-  commitDeferredConversation,
-  discardDeferredConversation,
-  registerDeferredConversation,
-} from "../notifications/deferred-emit.js";
 import { emitNotificationSignal } from "../notifications/emit-signal.js";
 import type { AttentionHints } from "../notifications/signal.js";
 import { bootstrapConversation } from "../persistence/conversation-bootstrap.js";
@@ -188,11 +183,6 @@ export interface RunBackgroundJobOptions {
    * the `assistant` role and cannot override the action prompt.
    */
   assistantSandwich?: { preamble: string; content: string; postamble: string };
-  /**
-   * Buffer in-band `notifications send` calls and only flush them after the
-   * run completes successfully. See `notifications/deferred-emit.ts`.
-   */
-  deferNotifications?: boolean;
   /**
    * Persist the kickoff `prompt` without indexing it — no memory segments,
    * no embeddings, no lexical-index entry. Opt-in for jobs whose prompt is a
@@ -304,10 +294,6 @@ export async function runBackgroundJob(
       ...(opts.scheduleJobId ? { scheduleJobId: opts.scheduleJobId } : {}),
     });
 
-    if (opts.deferNotifications) {
-      registerDeferredConversation(conversation.id);
-    }
-
     // Fire the sidebar-creation callback synchronously after bootstrap so
     // connected clients (macOS sidebar, etc.) see the conversation appear
     // immediately rather than after `processMessage` returns. Wrapped so a
@@ -382,23 +368,19 @@ export async function runBackgroundJob(
 
     const runResult = await Promise.race([work, timeout]);
     // Symmetric with the `work.catch` above: once `work` has won the race,
-    // the orphan timeout promise can still reject during the await below
-    // (commitDeferredConversation). Swallow so it doesn't surface as an
-    // unhandled rejection that Bun can use to terminate the process.
+    // the orphan timeout promise can still reject if the timer fires before
+    // the `finally` clears it. Swallow so it doesn't surface as an unhandled
+    // rejection that Bun can use to terminate the process.
     timeout.catch(() => {});
     // The turn completed but its LLM call failed (e.g. an invalid provider):
     // `processMessage` reports this via `turnFailure` instead of throwing.
-    // Rethrow so it flows through the shared failure path below (which
-    // discards any deferred notifications) rather than committing them and
-    // returning `ok: true`.
+    // Rethrow so it flows through the shared failure path below (logging +
+    // `activity.failed` emission) rather than returning `ok: true`.
     if (runResult.turnFailure) {
       throw new BackgroundJobTurnFailureError(
         runResult.turnFailure.failureCode,
       );
     }
-    if (opts.deferNotifications) {
-      await commitDeferredConversation(conversation.id);
-    }
     return { conversationId: conversation.id, ok: true };
   } catch (err) {
     const errorKind = classifyError(err);
@@ -411,10 +393,6 @@ export async function runBackgroundJob(
     // so the structured failure result still flows to the caller.
     const conversationId = conversation?.id ?? "";
 
-    if (opts.deferNotifications && conversationId) {
-      discardDeferredConversation(conversationId);
-    }
-
     log.error(
       {
         err: error.message,

package/src/runtime/channel-readiness-service.ts

@@ -212,6 +212,48 @@ const telegramProbe: ChannelProbe = {
       await checkIngress(true),
     ];
   },
+  /**
+   * Ask Telegram whether it is actually delivering. The local checks above
+   * only establish that credentials exist, which is a different claim: a
+   * registration that never landed leaves them all present and the channel
+   * dark.
+   *
+   * Three outcomes, not two:
+   *
+   *   - `healthy` is the only verified pass. Telegram holds the URL this
+   *     deployment recorded on its last successful registration, and reports
+   *     no recent delivery error.
+   *   - `skipped`, `unknown` and `unverified` are indeterminate. The
+   *     preconditions are absent, Telegram could not be reached, or no
+   *     registration was ever recorded to compare against. None is evidence of
+   *     a fault, so none may show the channel as broken; none is evidence of
+   *     delivery either, so none may make it ready.
+   *   - `not_registered`, `delivery_failing` and `url_mismatch` are failures
+   *     with a concrete cause in `detail`.
+   *
+   * The middle row is the point. Passing those three outright let an
+   * unreachable Telegram API or a missing precondition read as "Telegram is
+   * delivering", which the setup skill then reported to the user as confirmed.
+   */
+  async runRemoteChecks(): Promise<ReadinessCheckResult[]> {
+    // Imported here rather than at module scope: the health module pulls in
+    // the credential and config graph, and hoisting that into every consumer
+    // of this service makes unrelated tests resolve exports they never mock.
+    const { checkTelegramWebhookHealth } =
+      await import("../telegram/webhook-health.js");
+    const health = await checkTelegramWebhookHealth();
+    const indeterminate =
+      health.status === "skipped" ||
+      health.status === "unknown" ||
+      health.status === "unverified";
+    const result = check(
+      "webhook_delivery",
+      health.status === "healthy" || indeterminate,
+      "Telegram is delivering to this assistant",
+      health.detail,
+    );
+    return [indeterminate ? { ...result, indeterminate: true } : result];
+  },
 };
 
 // ── Email Probe ─────────────────────────────────────────────────────────────
@@ -469,10 +511,18 @@ export class ChannelReadinessService {
         remoteChecksAffectReadiness = false;
       }
 
-      const allLocalPassed = localChecks.every((c) => c.passed);
+      // Readiness requires positive confirmation, not merely the absence of a
+      // reported fault. A check that could not establish its claim (provider
+      // unreachable, ownership unprovable) is not a fault, so it must not be
+      // listed as a reason below, but it is also not evidence, so it cannot
+      // make a channel ready. Collapsing the two is how a channel reports
+      // itself live on the strength of a check that never ran.
+      const verified = (c: ReadinessCheckResult): boolean =>
+        c.passed && !c.indeterminate;
+      const allLocalPassed = localChecks.every(verified);
       const allRemotePassed =
         remoteChecks && remoteChecksAffectReadiness
-          ? remoteChecks.every((c) => c.passed)
+          ? remoteChecks.every(verified)
           : true;
       const ready = allLocalPassed && allRemotePassed;
 
@@ -481,7 +531,13 @@ export class ChannelReadinessService {
         ...localChecks,
         ...(remoteChecks && remoteChecksAffectReadiness ? remoteChecks : []),
       ];
-      const anyCheckPassed = consideredChecks.some((c) => c.passed);
+      // Also `verified`, not `passed`. A check that established nothing is not
+      // evidence that setup has begun: an install with no bot token at all
+      // returns `skipped` from the Telegram probe, and counting that as
+      // progress reports an untouched workspace as `incomplete`, which is what
+      // sends the Channels UI down the "finish setup" path instead of the
+      // normal setup flow.
+      const anyCheckPassed = consideredChecks.some(verified);
       const setupStatus: SetupStatus = !anyCheckPassed
         ? "not_configured"
         : ready

package/src/runtime/channel-readiness-types.ts

@@ -10,8 +10,26 @@ export type SetupStatus = "not_configured" | "incomplete" | "ready";
 /** Result of a single readiness check (local or remote). */
 export interface ReadinessCheckResult {
   name: string;
+  /**
+   * Whether the check found a fault. This drives the user-facing fault
+   * reporting: a check that did not fail must not be shown as broken.
+   */
   passed: boolean;
   message: string;
+  /**
+   * Set when the check could not establish its claim either way, as opposed to
+   * establishing that nothing is wrong.
+   *
+   * `passed` alone cannot express this. A probe that cannot reach a provider,
+   * or that lacks the evidence to confirm ownership, has found no fault, so
+   * failing it would paint working installs broken over a network blip. But it
+   * has also verified nothing, so counting it toward readiness lets a channel
+   * report itself live on the strength of a check that never ran. Consumers
+   * that report faults read `passed`; consumers that require proof (readiness,
+   * and the setup skills that gate their success message on it) additionally
+   * require this to be absent or false.
+   */
+  indeterminate?: boolean;
 }
 
 /** Point-in-time snapshot of a channel's readiness state. */

package/src/runtime/desktop-presence.ts

@@ -0,0 +1,69 @@
+/**
+ * Desktop presence policy.
+ *
+ * Answers exactly one question for notification producers: is the user
+ * demonstrably at their Mac right now? Producers use the answer to skip a
+ * push that the user would see on screen anyway.
+ *
+ * Fails open by design. Presence is in-memory, best-effort, and reported by
+ * a client that can drop off at any time, so anything short of a fresh
+ * `active` report from a `macos` client answers `false` and the push goes
+ * out. A missed notification is strictly worse than a redundant one.
+ */
+
+import { getLogger } from "../util/logger.js";
+import { assistantEventHub } from "./assistant-event-hub.js";
+
+const log = getLogger("desktop-presence");
+
+/**
+ * Bounds how long suppression can outlive the Mac going to sleep or dropping
+ * off, while still tolerating two dropped reports at the 30s report interval.
+ */
+export const PRESENCE_STALE_AFTER_MS = 90_000;
+
+export interface DesktopAttendanceOptions {
+  /**
+   * Only count macOS clients whose verified actor principal matches this id.
+   * A client that connected without a principal (legacy or service token)
+   * never matches a supplied id.
+   */
+  actorPrincipalId?: string;
+  /** Clock used for the staleness comparison. */
+  now?: Date;
+}
+
+/**
+ * Whether some macOS client has reported `active` recently enough to trust.
+ * Stale, absent, non-macOS, and error reads all answer `false`.
+ *
+ * Callers whose notification targets one recipient (guardian-scoped or
+ * otherwise per-recipient pushes) must pass that recipient's
+ * `actorPrincipalId`, or another user's attended Mac suppresses the push.
+ * Omitting it treats any attended macOS client as attendance, which only
+ * suits notifications with no single recipient.
+ */
+export function isDesktopAttended(
+  options: DesktopAttendanceOptions = {},
+): boolean {
+  const { actorPrincipalId, now = new Date() } = options;
+  try {
+    return assistantEventHub.listClientsByInterface("macos").some((client) => {
+      if (
+        actorPrincipalId !== undefined &&
+        client.actorPrincipalId !== actorPrincipalId
+      ) {
+        return false;
+      }
+      return (
+        client.presence?.state === "active" &&
+        now.getTime() - client.presence.reportedAt.getTime() <=
+          PRESENCE_STALE_AFTER_MS
+      );
+    });
+  } catch (err) {
+    // Returning false sends the push, which is the safe direction.
+    log.warn({ err }, "desktop presence read failed; treating as unattended");
+    return false;
+  }
+}

package/src/runtime/http-server.ts

@@ -33,6 +33,10 @@ import {
 } from "../live-voice/live-voice-connection.js";
 import { getLiveVoiceSessionManager } from "../live-voice/live-voice-manager.js";
 import { resolveStreamingTranscriber } from "../providers/speech-to-text/resolve.js";
+import {
+  startPluginScheduleReconcileSweep,
+  stopPluginScheduleReconcileSweep,
+} from "../schedule/plugin-schedule-reconciler.js";
 import {
   activeSttStreamSessions,
   SttStreamSession,
@@ -511,12 +515,20 @@ export class RuntimeHttpServer {
 
     startTelegramWebhookHealthSweep();
     log.info("Telegram webhook health sweep started");
+
+    // Backstop for plugin enable/disable, which flips the `.disabled`
+    // sentinel without poking the plugin source reconcile. The readiness
+    // guard lives inside reconcilePluginSchedules, which no-ops while
+    // migrations are unready.
+    startPluginScheduleReconcileSweep();
+    log.info("Plugin schedule reconcile sweep started");
   }
 
   async stop(): Promise<void> {
     stopGuardianExpirySweep();
     stopInferenceProfileSessionReaper();
     stopTelegramWebhookHealthSweep();
+    stopPluginScheduleReconcileSweep();
     if (this.retrySweepTimer) {
       clearInterval(this.retrySweepTimer);
       this.retrySweepTimer = null;