@vellumai/assistant 0.10.0 → 0.10.1-dev.202606240317.ea25efe

package/src/daemon/conversation.ts

@@ -15,7 +15,7 @@
  * - conversation-usage.ts        — recordUsage
  */
 
-import type { AgentLoopConfig, ResolvedSystemPrompt } from "../agent/loop.js";
+import type { AgentLoopConfig } from "../agent/loop.js";
 import { AgentLoop } from "../agent/loop.js";
 import type { AssistantActivityStateEvent } from "../api/events/assistant-activity-state.js";
 import type {
@@ -91,7 +91,7 @@ import {
   isActivationMomentParam,
 } from "../telemetry/activation-funnel.js";
 import { ToolExecutor } from "../tools/executor.js";
-import { getAllToolDefinitions } from "../tools/registry.js";
+import { getAllToolDefinitions, getTool } from "../tools/registry.js";
 import type { ToolLifecycleEvent } from "../tools/types.js";
 import type { OnboardingContext } from "../types/onboarding-context.js";
 import type { AbortReason } from "../util/abort-reasons.js";
@@ -296,7 +296,7 @@ export class Conversation {
     outputTokens: 0,
     estimatedCost: 0,
   };
-  /** @internal */ readonly systemPrompt: string;
+  /** @internal */ systemPrompt: string;
   /** @internal */ contextCompactedMessageCount = 0;
   /** @internal */ contextCompactedAt: number | null = null;
   /** @internal */ contextSummary: string | null = null;
@@ -376,7 +376,7 @@ export class Conversation {
    */
   wakePersonaOverride?: SystemPromptPersonaOverride;
   /** @internal */ currentTurnOverrideProfile?: string;
-  /** @internal */ toolRoutedProfile?: string;
+  /** @internal */ currentTurnIsNonInteractive?: boolean;
   /** @internal */ authContext?: AuthContext;
   /** @internal */ currentTurnAuthContext?: AuthContext;
   /** @internal */ currentTurnSourceActorPrincipalId?: string;
@@ -537,6 +537,7 @@ export class Conversation {
   };
   public readonly traceEmitter: TraceEmitter;
   /** @internal */ hasSystemPromptOverride: boolean;
+  /** @internal */ modelOverride: string | undefined;
   /** @internal */ readonly graphMemory: ConversationGraphMemory;
   /** @internal */ activeContextNodeIds?: string[];
   /** @internal */ streamThinking: boolean;
@@ -666,34 +667,9 @@ export class Conversation {
     const hasSystemPromptOverride = systemPrompt !== buildSystemPrompt();
     this.hasSystemPromptOverride = hasSystemPromptOverride;
 
-    // If an explicit modelOverride is supplied, use it verbatim. Otherwise
-    // leave the model unset and let `RetryProvider`'s call-site resolver pick
-    // it up from `llm.default` / `llm.callSites.<id>` on every turn.
-    const resolvedModel: string | undefined = modelOverride;
-
-    const resolveSystemPromptCallback = (
-      _history: Message[],
-    ): ResolvedSystemPrompt => {
-      const resolved: ResolvedSystemPrompt = {
-        systemPrompt: this.hasSystemPromptOverride
-          ? systemPrompt
-          : buildSystemPrompt({
-              hasNoClient: this.hasNoClient,
-              trustContext: this.currentTurnTrustContext,
-              channelCapabilities: this.currentTurnChannelCapabilities,
-              personaOverride: this.wakePersonaOverride,
-              onboardingContext: this.getOnboardingContext(),
-              conversationId: this.conversationId,
-            }),
-      };
-      if (configuredMaxTokens !== undefined) {
-        resolved.maxTokens = configuredMaxTokens;
-      }
-      if (resolvedModel !== undefined) {
-        resolved.model = resolvedModel;
-      }
-      return resolved;
-    };
+    // Store the model override for per-run resolution. The loop receives it
+    // as a top-level `model` param on `run()`.
+    this.modelOverride = modelOverride;
 
     const fastModeEnabled = isAssistantFeatureFlagEnabled("fast-mode", config);
     const resolvedSpeed = speedOverride ?? resolvedMainAgent.speed;
@@ -726,7 +702,9 @@ export class Conversation {
       tools: toolDefs.length > 0 ? toolDefs : undefined,
       toolExecutor: toolDefs.length > 0 ? toolExecutor : undefined,
       resolveTools,
-      resolveSystemPrompt: resolveSystemPromptCallback,
+      // A tool the registry marks exclusive (e.g. `advisor`) runs alone in its
+      // turn; the loop defers any sibling calls until the next turn.
+      isExclusiveTool: (name) => getTool(name)?.exclusive === true,
       resolveConversationDir: () => {
         const conv = getConversation(this.conversationId);
         if (!conv) return null;
@@ -738,7 +716,6 @@ export class Conversation {
     });
     createContextWindowManager({
       provider,
-      systemPrompt: () => resolveSystemPromptCallback([]).systemPrompt,
       config: initialContextWindowConfig,
       toolTokenBudget: this.agentLoop.getToolTokenBudget(),
       conversationId: this.conversationId,
@@ -799,6 +776,29 @@ export class Conversation {
     this.inferenceProfileExpiresAt = state.expiresAt;
   }
 
+  /**
+   * Build the system prompt for the current conversation state. When a
+   * system-prompt override was supplied at construction, use it as-is;
+   * otherwise rebuild the full prompt (picks up workspace file changes,
+   * live trust/channel context, persona overrides, onboarding context).
+   *
+   * Called by the caller before invoking `agentLoop.run()` — the loop
+   * itself never re-resolves the prompt mid-loop (re-resolving would bust
+   * the provider's prefix cache).
+   */
+  buildCurrentSystemPrompt(): string {
+    return this.hasSystemPromptOverride
+      ? this.systemPrompt
+      : buildSystemPrompt({
+          hasNoClient: this.hasNoClient,
+          trustContext: this.currentTurnTrustContext,
+          channelCapabilities: this.currentTurnChannelCapabilities,
+          personaOverride: this.wakePersonaOverride,
+          onboardingContext: this.getOnboardingContext(),
+          conversationId: this.conversationId,
+        });
+  }
+
   // ── Prompt Cache Warming ─────────────────────────────────────────
 
   /**
@@ -811,16 +811,7 @@ export class Conversation {
     const abort = new AbortController();
     this.cacheWarmAbort = abort;
 
-    const systemPrompt = this.hasSystemPromptOverride
-      ? this.systemPrompt
-      : buildSystemPrompt({
-          hasNoClient: this.hasNoClient,
-          trustContext: this.currentTurnTrustContext,
-          channelCapabilities: this.currentTurnChannelCapabilities,
-          personaOverride: this.wakePersonaOverride,
-          onboardingContext: this.getOnboardingContext(),
-          conversationId: this.conversationId,
-        });
+    const systemPrompt = this.buildCurrentSystemPrompt();
     const tools = getAllToolDefinitions();
     const provider = this.provider;
 
@@ -976,6 +967,18 @@ export class Conversation {
           const meta = JSON.parse(m.metadata);
           const isTail = index === arr.length - 1;
 
+          // `<non_interactive_context>` is the only rehydrated block that
+          // APPENDS to the tail (live injection appends it in Step 3), so it
+          // must land after the original content. Apply it first — before the
+          // prepends below — so the prepends stack in front of it and it stays
+          // last, matching the live layout.
+          if (!isTail && typeof meta.nonInteractiveContextBlock === "string") {
+            content = [
+              ...content,
+              { type: "text" as const, text: meta.nonInteractiveContextBlock },
+            ];
+          }
+
           // Rehydrate in reverse injection order (innermost block first)
           // so the resulting layout matches `applyRuntimeInjections`'s
           // after-memory-prefix splices in ascending injector order
@@ -1086,6 +1089,17 @@ export class Conversation {
             ];
           }
 
+          // `<channel_capabilities>` lands just below `<turn_context>`: live
+          // injection prepends it (Step 3) before the prepend-user-tail chain
+          // blocks (Step 4), so it must be prepended BEFORE turnContextBlock
+          // here to land one slot deeper than `<turn_context>`.
+          if (!isTail && typeof meta.channelCapabilitiesBlock === "string") {
+            content = [
+              { type: "text" as const, text: meta.channelCapabilitiesBlock },
+              ...content,
+            ];
+          }
+
           if (!isTail && typeof meta.turnContextBlock === "string") {
             content = [
               { type: "text" as const, text: meta.turnContextBlock },
@@ -1093,6 +1107,16 @@ export class Conversation {
             ];
           }
 
+          // `<background_turn>` lands between `<workspace>` and `<turn_context>`
+          // (injector order 15, between workspace 10 and unified-turn-context
+          // 20), so prepend it AFTER turnContextBlock and BEFORE workspaceBlock.
+          if (!isTail && typeof meta.backgroundTurnBlock === "string") {
+            content = [
+              { type: "text" as const, text: meta.backgroundTurnBlock },
+              ...content,
+            ];
+          }
+
           if (!isTail && typeof meta.workspaceBlock === "string") {
             content = [
               { type: "text" as const, text: meta.workspaceBlock },
@@ -1529,9 +1553,7 @@ export class Conversation {
 
   ensureHostProxiesForTurn(
     sourceInterface: import("../channels/types.js").InterfaceId | undefined,
-    sourceActorPrincipalId = this.currentTurnSourceActorPrincipalId ??
-      this.currentTurnAuthContext?.actorPrincipalId ??
-      this.authContext?.actorPrincipalId,
+    sourceActorPrincipalId = this.getTurnActorPrincipalId(),
   ): void {
     if (
       shouldAttachHostProxyForCapability(
@@ -1606,8 +1628,65 @@ export class Conversation {
     }
   }
 
+  /**
+   * Token count for `messages` used to render the user-facing `/compact` and
+   * `/clean` figures. Prefers the provider's real `count_tokens` tokenizer (so
+   * the numbers match the context-window indicator's provider-reported usage)
+   * and falls back to the context-window manager's local estimate when the
+   * provider has no count endpoint or the count call fails — both measure the
+   * same system-prompt + tools composition the manager sizes against.
+   *
+   * The count is a network round-trip with its own rate limit, so this is for
+   * user-initiated actions only, never the per-turn auto-compaction gate.
+   */
+  private async calculateTokens(messages: Message[]): Promise<number> {
+    const countInputTokens = this.provider.countInputTokens;
+    if (!countInputTokens) {
+      return this.contextWindowManager.estimateInputTokens(messages);
+    }
+    try {
+      const { systemPrompt, tools } =
+        this.contextWindowManager.tokenCountInputs;
+      return await countInputTokens.call(
+        this.provider,
+        messages,
+        systemPrompt,
+        tools,
+      );
+    } catch (err) {
+      log.warn(
+        { err, conversationId: this.conversationId },
+        "Provider token count failed — falling back to local estimate",
+      );
+      return this.contextWindowManager.estimateInputTokens(messages);
+    }
+  }
+
   async forceCompact(): Promise<ContextWindowResult> {
-    return this.runCompaction(true);
+    // Report the user-facing before/after using the provider's real tokenizer
+    // (count_tokens) so the `/compact` line matches the context-window
+    // indicator, which reflects the provider's actual reported usage — rather
+    // than the local chars/4 estimate the compaction pipeline runs internally
+    // (it under-counts by ~25% on typical histories). `calculateTokens`
+    // falls back to that estimate when the provider has no count endpoint or
+    // the count call fails, so behavior degrades gracefully.
+    //
+    // Only the *displayed* numbers are overridden — the compaction log and
+    // circuit-breaker accounting inside `runCompaction` keep the estimate-based
+    // figures, leaving calibration and historical logs untouched.
+    const before = await this.calculateTokens(this.messages);
+    const result = await this.runCompaction(true);
+    // `runCompaction` applies the compacted history to `this.messages` in
+    // place, so after a successful compaction this re-counts the new history;
+    // a no-op leaves the context unchanged, so before === after.
+    const after = result.compacted
+      ? await this.calculateTokens(this.messages)
+      : before;
+    return {
+      ...result,
+      previousEstimatedInputTokens: before,
+      estimatedInputTokens: after,
+    };
   }
 
   /**
@@ -1726,15 +1805,17 @@ export class Conversation {
    * activations are no longer deduped against the prior session.
    */
   async forceClean(): Promise<CleanResult> {
-    const previousEstimatedInputTokens =
-      this.contextWindowManager.estimateInputTokens(this.messages);
+    // Use the provider's real tokenizer for the displayed before/after (see
+    // `forceCompact` for why); falls back to the local estimate when count
+    // isn't available.
+    const previousEstimatedInputTokens = await this.calculateTokens(
+      this.messages,
+    );
     const stripped = stripInjectionsForCompaction(this.messages);
     this.messages = stripped;
     await this.graphMemory.onCompacted(0);
     setConversationHistoryStrippedAt(this.conversationId, Date.now());
-    const estimatedInputTokens = this.contextWindowManager.estimateInputTokens(
-      this.messages,
-    );
+    const estimatedInputTokens = await this.calculateTokens(this.messages);
     return {
       previousEstimatedInputTokens,
       estimatedInputTokens,
@@ -1767,6 +1848,21 @@ export class Conversation {
     return this.authContext;
   }
 
+  /**
+   * The actor principal that owns the current turn, for host-proxy routing.
+   * Prefers the in-flight turn's actor over the conversation's resting
+   * authContext so a /v1/messages turn (which sets only
+   * `currentTurnSourceActorPrincipalId`/`currentTurnAuthContext`) scopes
+   * correctly. Returns `undefined` when no actor identity is known.
+   */
+  getTurnActorPrincipalId(): string | undefined {
+    return (
+      this.currentTurnSourceActorPrincipalId ??
+      this.currentTurnAuthContext?.actorPrincipalId ??
+      this.authContext?.actorPrincipalId
+    );
+  }
+
   setVoiceCallControlPrompt(prompt: string | null): void {
     this.voiceCallControlPrompt = prompt ?? undefined;
   }

package/src/daemon/disk-pressure-guard.ts

@@ -24,6 +24,12 @@ export const DISK_PRESSURE_CLEAR_THRESHOLD_PERCENT = 90;
 // clears the warning state, which discards the banner's (state-scoped) dismissal
 // so it re-appears the moment usage ticks back up.
 export const DISK_PRESSURE_WARNING_CLEAR_THRESHOLD_PERCENT = 77;
+// Absolute free-space floor (MiB). Regardless of usage percentage, never enter
+// the warning or critical state while at least this much space remains free. A
+// high usage percentage on a large disk can still leave many gigabytes
+// available, where locking is pointless. Small volumes (where a high percentage
+// genuinely means near-full) drop below the floor and remain protected.
+export const DISK_PRESSURE_MIN_FREE_FLOOR_MB = 2048;
 export const DISK_PRESSURE_CHECK_INTERVAL_MS = 60_000;
 export const DISK_PRESSURE_OVERRIDE_CONFIRMATION = "I understand the risks";
 export const DISK_PRESSURE_BLOCKED_CAPABILITIES = [
@@ -219,7 +225,10 @@ export function evaluateDiskPressureNow(): DiskPressureStatus {
   const criticalThreshold = state.status.locked
     ? DISK_PRESSURE_CLEAR_THRESHOLD_PERCENT
     : DISK_PRESSURE_THRESHOLD_PERCENT;
-  const isCritical = usagePercent >= criticalThreshold;
+  // Absolute free-space floor overrides the percentage thresholds: while ample
+  // space remains free, report "ok" no matter how full the volume is by percent.
+  const hasAmpleFreeSpace = usageInfo.freeMb >= DISK_PRESSURE_MIN_FREE_FLOOR_MB;
+  const isCritical = !hasAmpleFreeSpace && usagePercent >= criticalThreshold;
   // Mirror the critical deadband for the warning band: once in an active
   // pressure state (warning or critical), hold warning until usage clears the
   // lower warning-clear threshold. Treating "critical" as active here matters
@@ -235,7 +244,8 @@ export function evaluateDiskPressureNow(): DiskPressureStatus {
   const warningThreshold = inActivePressureState
     ? DISK_PRESSURE_WARNING_CLEAR_THRESHOLD_PERCENT
     : DISK_PRESSURE_WARNING_THRESHOLD_PERCENT;
-  const isWarning = !isCritical && usagePercent >= warningThreshold;
+  const isWarning =
+    !hasAmpleFreeSpace && !isCritical && usagePercent >= warningThreshold;
   const lastCheckedAt = new Date().toISOString();
 
   if (!isCritical && !isWarning) {

package/src/daemon/event-loop-watchdog.test.ts

@@ -0,0 +1,85 @@
+/**
+ * Tests for the event-loop block watchdog.
+ *
+ * - `evaluateTick` must derive the blocked duration as elapsed-beyond-interval
+ *   and apply the threshold inclusively, clamping early/normal ticks to zero so
+ *   a healthy loop never reports.
+ * - `start`/`stop` must be idempotent and safe to call in any order so daemon
+ *   startup and the two shutdown paths can call them unconditionally.
+ */
+import { describe, expect, mock, test } from "bun:test";
+
+mock.module("../util/logger.js", () => ({
+  getLogger: () =>
+    new Proxy({} as Record<string, unknown>, { get: () => () => {} }),
+}));
+
+const { evaluateTick, startEventLoopWatchdog, stopEventLoopWatchdog } =
+  await import("./event-loop-watchdog.js");
+
+describe("evaluateTick", () => {
+  const INTERVAL = 1_000;
+  const THRESHOLD = 5_000;
+
+  test("a healthy tick at the scheduled interval is not a block", () => {
+    // GIVEN the timer fired right on schedule
+    // WHEN the tick is evaluated
+    const { blockedMs, exceeded } = evaluateTick(INTERVAL, INTERVAL, THRESHOLD);
+    // THEN no block is observed
+    expect(blockedMs).toBe(0);
+    expect(exceeded).toBe(false);
+  });
+
+  test("an early tick clamps the blocked duration to zero", () => {
+    // GIVEN the timer fired sooner than the interval (e.g. clock jitter)
+    // WHEN the tick is evaluated
+    const { blockedMs, exceeded } = evaluateTick(200, INTERVAL, THRESHOLD);
+    // THEN the blocked duration never goes negative
+    expect(blockedMs).toBe(0);
+    expect(exceeded).toBe(false);
+  });
+
+  test("lateness under the threshold is measured but not reported", () => {
+    // GIVEN the loop was blocked ~2s (below the 5s threshold)
+    // WHEN the tick is evaluated
+    const { blockedMs, exceeded } = evaluateTick(3_000, INTERVAL, THRESHOLD);
+    // THEN the block is quantified but does not trip a report
+    expect(blockedMs).toBe(2_000);
+    expect(exceeded).toBe(false);
+  });
+
+  test("the threshold is inclusive", () => {
+    // GIVEN the blocked duration lands exactly on the threshold
+    // WHEN the tick is evaluated
+    const { blockedMs, exceeded } = evaluateTick(
+      INTERVAL + THRESHOLD,
+      INTERVAL,
+      THRESHOLD,
+    );
+    // THEN it counts as exceeded
+    expect(blockedMs).toBe(THRESHOLD);
+    expect(exceeded).toBe(true);
+  });
+
+  test("a multi-minute freeze reports the full blocked duration", () => {
+    // GIVEN a ~123s freeze (the observed daemon-freeze magnitude) with a 1s tick
+    // WHEN the first tick after unblock is evaluated
+    const { blockedMs, exceeded } = evaluateTick(124_000, INTERVAL, THRESHOLD);
+    // THEN the reported block excludes the one normal interval of wait
+    expect(blockedMs).toBe(123_000);
+    expect(exceeded).toBe(true);
+  });
+});
+
+describe("start/stop lifecycle", () => {
+  test("start and stop are idempotent and order-independent", () => {
+    // GIVEN a fresh module
+    // WHEN start/stop are called repeatedly and out of order
+    // THEN none of the calls throw (daemon boot + both shutdown paths are safe)
+    expect(() => stopEventLoopWatchdog()).not.toThrow();
+    expect(() => startEventLoopWatchdog()).not.toThrow();
+    expect(() => startEventLoopWatchdog()).not.toThrow();
+    expect(() => stopEventLoopWatchdog()).not.toThrow();
+    expect(() => stopEventLoopWatchdog()).not.toThrow();
+  });
+});

package/src/daemon/event-loop-watchdog.ts

@@ -0,0 +1,133 @@
+/**
+ * Event-loop block watchdog.
+ *
+ * The daemon runs all request handling, synchronous `bun:sqlite` access, and
+ * background jobs on a single event-loop thread. Any synchronous operation that
+ * runs long — a large conversation-history load, a memory retrospective
+ * assembling an oversized conversation, a VACUUM or WAL checkpoint — blocks that
+ * thread, so the daemon stops answering health probes and SSE for the duration
+ * (a proxied `vellum ps` health check then reports `timeout` even though the
+ * process is alive). Such a freeze is otherwise invisible: the blocked thread is
+ * too busy to emit logs, so it leaves only a gap that self-heals when the
+ * operation returns, and is noticed only by chance.
+ *
+ * This watchdog makes those freezes observable. It schedules a timer every
+ * `TICK_INTERVAL_MS`; when the loop is blocked the callback cannot run, so it
+ * fires late by roughly the block duration. On the first tick after the loop
+ * frees up, the elapsed-since-last-tick beyond a normal interval is how long the
+ * loop was unavailable; above a threshold it emits a warn log + Sentry capture.
+ *
+ * What it does NOT do: capture the JS stack of the blocking operation. JS is
+ * single-threaded, so while the loop is blocked no callback — including this one
+ * — can run; by the time the tick fires, the offending synchronous call has
+ * returned and its stack is gone. The watchdog reports *that* and *how long* a
+ * freeze happened, not *what* caused it. The report lands at unblock, so the
+ * surrounding log lines (which job or turn was active) are the correlation
+ * handle. For deterministic attribution of a specific subsystem, time that
+ * subsystem's synchronous calls at their source.
+ *
+ * A cumulative event-loop-delay histogram is separately exposed pull-based over
+ * SSE diagnostics (`runtime/routes/events-routes.ts`); this watchdog is the
+ * push/alert counterpart and runs unconditionally for the daemon's lifetime.
+ */
+
+import * as Sentry from "@sentry/node";
+
+import { getLogger } from "../util/logger.js";
+
+const log = getLogger("event-loop-watchdog");
+
+/** How often the probe timer is scheduled. */
+const TICK_INTERVAL_MS = 1_000;
+
+/**
+ * Report only when the loop was unavailable for at least this long beyond a
+ * normal tick. Set above the floor of the daemon's known-legitimate
+ * multi-second main-thread operations so the signal stays actionable rather than
+ * noisy; tune here.
+ */
+const DEFAULT_BLOCK_THRESHOLD_MS = 5_000;
+
+/**
+ * Minimum spacing between reports. A single long freeze fires the timer once on
+ * unblock (an overdue interval is not replayed per missed tick), but a loop that
+ * blocks repeatedly could trip every tick; the cooldown bounds that to one
+ * report per window.
+ */
+const REPORT_COOLDOWN_MS = 30_000;
+
+let tickTimer: ReturnType<typeof setInterval> | null = null;
+let lastTickAt = 0;
+let lastReportAt = Number.NEGATIVE_INFINITY;
+
+/**
+ * Given the wall-clock elapsed since the previous tick and the scheduled tick
+ * interval, the loop was blocked for the excess over the interval. Pure so the
+ * threshold decision is unit-testable without real timers or a blocked loop.
+ */
+export function evaluateTick(
+  elapsedMs: number,
+  intervalMs: number,
+  thresholdMs: number,
+): { blockedMs: number; exceeded: boolean } {
+  const blockedMs = Math.max(0, elapsedMs - intervalMs);
+  return { blockedMs, exceeded: blockedMs >= thresholdMs };
+}
+
+function reportBlock(blockedMs: number, thresholdMs: number): void {
+  log.warn(
+    { blockedMs, thresholdMs, tickIntervalMs: TICK_INTERVAL_MS },
+    "event loop blocked",
+  );
+  try {
+    Sentry.withScope((scope) => {
+      scope.setLevel("warning");
+      scope.setTag("event_loop_blocked_ms", String(blockedMs));
+      scope.setContext("event_loop_block", {
+        blocked_ms: blockedMs,
+        threshold_ms: thresholdMs,
+        tick_interval_ms: TICK_INTERVAL_MS,
+      });
+      Sentry.captureMessage("event_loop_blocked");
+    });
+  } catch {
+    // Never let a telemetry failure escape the timer callback.
+  }
+}
+
+/**
+ * Start the event-loop block watchdog. Idempotent. The timer is `unref`'d so it
+ * never keeps the process alive on its own.
+ */
+export function startEventLoopWatchdog(
+  thresholdMs: number = DEFAULT_BLOCK_THRESHOLD_MS,
+): void {
+  if (tickTimer) return;
+  lastTickAt = performance.now();
+  lastReportAt = Number.NEGATIVE_INFINITY;
+  tickTimer = setInterval(() => {
+    const now = performance.now();
+    const { blockedMs, exceeded } = evaluateTick(
+      now - lastTickAt,
+      TICK_INTERVAL_MS,
+      thresholdMs,
+    );
+    lastTickAt = now;
+    if (exceeded && now - lastReportAt >= REPORT_COOLDOWN_MS) {
+      lastReportAt = now;
+      reportBlock(blockedMs, thresholdMs);
+    }
+  }, TICK_INTERVAL_MS);
+  tickTimer.unref?.();
+  log.info(
+    { tickIntervalMs: TICK_INTERVAL_MS, thresholdMs },
+    "Event-loop watchdog started",
+  );
+}
+
+export function stopEventLoopWatchdog(): void {
+  if (tickTimer) {
+    clearInterval(tickTimer);
+    tickTimer = null;
+  }
+}