@vellumai/assistant 0.10.3-dev.202606281440.a7b42bb → 0.10.3-dev.202606281633.f2981fa

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.10.3-dev.202606281440.a7b42bb",
+  "version": "0.10.3-dev.202606281633.f2981fa",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/heartbeat-disk-pressure.test.ts

@@ -70,8 +70,8 @@ mock.module("../schedule/recurrence-engine.js", () => ({
 
 const createdConversations: Array<{ conversationType: string }> = [];
 mock.module("../memory/conversation-crud.js", () => ({
-    setConversationProcessingStartedAt: () => {},
-    isConversationProcessing: () => false,
+  setConversationProcessingStartedAt: () => {},
+  isConversationProcessing: () => false,
   getConversation: () => null,
   getMessages: () => [],
   createConversation: (opts: { conversationType: string }) => {
@@ -164,9 +164,7 @@ describe("HeartbeatService disk pressure gate", () => {
   });
 
   test("skips without creating heartbeat rows, conversations, or notifications", async () => {
-    const service = new HeartbeatService({
-      alerter: () => {},
-    });
+    const service = new HeartbeatService();
 
     const ran = await service.runOnce();
 
@@ -181,9 +179,7 @@ describe("HeartbeatService disk pressure gate", () => {
   });
 
   test("allows forced user-initiated heartbeat runs while locked", async () => {
-    const service = new HeartbeatService({
-      alerter: () => {},
-    });
+    const service = new HeartbeatService();
 
     const ran = await service.runOnce({ force: true });
 
@@ -199,9 +195,7 @@ describe("HeartbeatService disk pressure gate", () => {
 
   test("start recovery skips missed-run notifications while locked", async () => {
     mockMarkStaleRunsAsMissed.mockImplementationOnce(() => 1);
-    const service = new HeartbeatService({
-      alerter: () => {},
-    });
+    const service = new HeartbeatService();
 
     service.start();
     await service.stop();

package/src/__tests__/heartbeat-service.test.ts

@@ -137,8 +137,8 @@ const mockStoredMessages: Array<{
 }> = [];
 
 mock.module("../memory/conversation-crud.js", () => ({
-    setConversationProcessingStartedAt: () => {},
-    isConversationProcessing: () => false,
+  setConversationProcessingStartedAt: () => {},
+  isConversationProcessing: () => false,
   setConversationOriginChannelIfUnset: () => {},
   updateConversationContextWindow: () => {},
   deleteMessageById: () => {},
@@ -335,6 +335,23 @@ const LLM_DEFAULT = {
   },
 };
 
+// Capture broadcastMessage so tests can observe the alerts and
+// conversation-created events the heartbeat service emits directly.
+type BroadcastedMessage = { type: string; [key: string]: unknown };
+const broadcastedMessages: BroadcastedMessage[] = [];
+let onBroadcast: ((msg: BroadcastedMessage) => void) | null = null;
+
+mock.module("../runtime/assistant-event-hub.js", () => ({
+  assistantEventHub: {
+    publish: async () => {},
+    subscribe: () => () => {},
+  },
+  broadcastMessage: (msg: BroadcastedMessage) => {
+    broadcastedMessages.push(msg);
+    onBroadcast?.(msg);
+  },
+}));
+
 describe("HeartbeatService", () => {
   let processMessageCalls: Array<{
     conversationId: string;
@@ -353,6 +370,12 @@ describe("HeartbeatService", () => {
   beforeEach(() => {
     processMessageCalls = [];
     alerterCalls = [];
+    broadcastedMessages.length = 0;
+    onBroadcast = (msg) => {
+      if (msg.type === "heartbeat_alert") {
+        alerterCalls.push(msg as { type: string; title: string; body: string });
+      }
+    };
     createdConversations.length = 0;
     conversationIdCounter = 0;
     mockStoredMessages.length = 0;
@@ -413,19 +436,11 @@ describe("HeartbeatService", () => {
   function createService(overrides?: {
     processMessage?: (...args: unknown[]) => Promise<{ messageId: string }>;
     getCurrentHour?: () => number;
-    onConversationCreated?: (info: {
-      conversationId: string;
-      title: string;
-    }) => void;
   }) {
     if (overrides?.processMessage) {
       setTestProcessMessage(overrides.processMessage);
     }
     return new HeartbeatService({
-      alerter: (alert: { type: string; title: string; body: string }) => {
-        alerterCalls.push(alert);
-      },
-      onConversationCreated: overrides?.onConversationCreated,
       getCurrentHour: overrides?.getCurrentHour,
     });
   }
@@ -770,17 +785,14 @@ describe("HeartbeatService", () => {
   });
 
   test("conversation surfaces to the sidebar on every successful run", async () => {
-    const conversationCreatedCalls: Array<{
-      conversationId: string;
-      title: string;
-    }> = [];
-    const service = createService({
-      onConversationCreated: (info) => conversationCreatedCalls.push(info),
-    });
+    const service = createService();
 
     await service.runOnce();
     await new Promise((resolve) => setTimeout(resolve, 0));
 
+    const conversationCreatedCalls = broadcastedMessages
+      .filter((m) => m.type === "heartbeat_conversation_created")
+      .map((m) => ({ conversationId: m.conversationId, title: m.title }));
     expect(conversationCreatedCalls).toEqual([
       { conversationId: "conv-1", title: "Heartbeat" },
     ]);

package/src/background-wake/wake-intent-hooks.test.ts

@@ -235,10 +235,11 @@ describe("background wake intent publisher hooks", () => {
       "utf-8",
     );
 
-    // Match the three calls in order, tolerant of indentation, so the
-    // assertion survives reformatting/re-indentation of lifecycle.ts.
+    // The wake intent is published once, immediately after the scheduler and
+    // heartbeat are wired into the background-wake runtime. Tolerant of
+    // indentation so the assertion survives reformatting of lifecycle.ts.
     expect(lifecycleSource).toMatch(
-      /heartbeat\.start\(\);\n[ \t]*registerBackgroundWakeRuntime\(\{ scheduler, heartbeat \}\);\n[ \t]*refreshBackgroundWakeIntent\("daemon-startup"\);/,
+      /registerBackgroundWakeRuntime\(\{ scheduler, heartbeat \}\);\n[ \t]*refreshBackgroundWakeIntent\("daemon-startup"\);/,
     );
   });
 

package/src/daemon/lifecycle.ts

@@ -32,8 +32,8 @@ import {
   DEFAULT_CES_STARTUP_TIMEOUT_MS,
   injectCesClientWhenReady,
 } from "../credential-execution/startup-timeout.js";
-import { FilingService } from "../filing/filing-service.js";
-import { HeartbeatService } from "../heartbeat/heartbeat-service.js";
+import { startFilingService } from "../filing/filing-service.js";
+import { startHeartbeatService } from "../heartbeat/heartbeat-service.js";
 import { backfillRelationshipStateIfMissing } from "../home/relationship-state-writer.js";
 import { closeSentry, initSentry, setSentryDeviceId } from "../instrument.js";
 import { startGatewayFlagListener } from "../ipc/gateway-flag-listener.js";
@@ -104,7 +104,7 @@ import {
 } from "../work-items/work-item-store.js";
 import { getWorkflowRunManager } from "../workflows/run-manager.js";
 import { repairAdaptiveThinkingOnManagedProfiles } from "../workspace/adaptive-thinking-repair.js";
-import { WorkspaceHeartbeatService } from "../workspace/heartbeat-service.js";
+import { startWorkspaceHeartbeatService } from "../workspace/heartbeat-service.js";
 import { WORKSPACE_MIGRATIONS } from "../workspace/migrations/registry.js";
 import { runWorkspaceMigrations } from "../workspace/migrations/runner.js";
 import { writePid } from "./daemon-control.js";
@@ -1320,59 +1320,19 @@ export async function runDaemon(): Promise<void> {
     });
   }
 
-  const workspaceHeartbeat = new WorkspaceHeartbeatService();
-  workspaceHeartbeat.start();
+  startWorkspaceHeartbeatService();
 
-  const heartbeatConfig = config.heartbeat;
-  const heartbeat = new HeartbeatService({
-    alerter: (alert) => broadcastMessage(alert),
-    onConversationCreated: (info) =>
-      broadcastMessage({
-        type: "heartbeat_conversation_created",
-        conversationId: info.conversationId,
-        title: info.title,
-      }),
-  });
-  heartbeat.start();
+  const heartbeat = startHeartbeatService();
   registerBackgroundWakeRuntime({ scheduler, heartbeat });
   refreshBackgroundWakeIntent("daemon-startup");
-  log.info(
-    {
-      enabled: heartbeatConfig.enabled,
-      intervalMs: heartbeatConfig.intervalMs,
-    },
-    "Heartbeat service configured",
-  );
 
-  // Filing yields to the memory v2 consolidation job when v2 is enabled —
-  // both serve the same role (periodic background memory processing) and
-  // running both is redundant. The consolidation job runs through the
-  // memory jobs worker (see `maybeEnqueueGraphMaintenanceJobs`).
-  const memoryV2Enabled = config.memory.v2.enabled;
-  let filing: FilingService | null = null;
-  if (!memoryV2Enabled) {
-    const filingConfig = config.filing;
-    filing = new FilingService();
-    filing.start();
-    log.info(
-      {
-        enabled: filingConfig.enabled,
-        intervalMs: filingConfig.intervalMs,
-      },
-      "Filing service configured",
-    );
-  } else {
-    log.info(
-      "Filing service skipped — memory v2 consolidation is the active background memory job",
-    );
-  }
+  // Filing yields to the memory v2 consolidation job when v2 is enabled — both
+  // serve the same role (periodic background memory processing) and running both
+  // is redundant. The consolidation job runs through the memory jobs worker
+  // (see `maybeEnqueueGraphMaintenanceJobs`).
+  startFilingService();
 
-  installShutdownHandlers({
-    server,
-    workspaceHeartbeat,
-    heartbeat,
-    filing,
-  });
+  installShutdownHandlers({ server });
 
   log.info(
     {

package/src/daemon/shutdown-handlers.ts

@@ -1,7 +1,7 @@
 import * as Sentry from "@sentry/node";
 
-import type { FilingService } from "../filing/filing-service.js";
-import type { HeartbeatService } from "../heartbeat/heartbeat-service.js";
+import { stopFilingService } from "../filing/filing-service.js";
+import { stopHeartbeatService } from "../heartbeat/heartbeat-service.js";
 import { stopGatewayFlagListener } from "../ipc/gateway-flag-listener.js";
 import { stopMcpServerManager } from "../mcp/manager.js";
 import { getSqlite, resetDb } from "../memory/db-connection.js";
@@ -15,7 +15,10 @@ import { browserManager } from "../tools/browser/browser-manager.js";
 import { cleanupShellOutputTempFiles } from "../tools/shared/shell-output.js";
 import { getLogger } from "../util/logger.js";
 import { getEnrichmentService } from "../workspace/commit-message-enrichment-service.js";
-import type { WorkspaceHeartbeatService } from "../workspace/heartbeat-service.js";
+import {
+  commitAllPendingWorkspaceChanges,
+  stopWorkspaceHeartbeatService,
+} from "../workspace/heartbeat-service.js";
 import { cleanupPidFile } from "./daemon-control.js";
 import { stopEventLoopWatchdog } from "./event-loop-watchdog.js";
 import { stopDiskPressureGuardForLifecycle } from "./lifecycle.js";
@@ -40,9 +43,6 @@ function stopBackgroundServicesAndCleanupPidFile(): void {
 
 export interface ShutdownDeps {
   server: DaemonServer;
-  workspaceHeartbeat: WorkspaceHeartbeatService;
-  heartbeat: HeartbeatService;
-  filing: FilingService | null;
 }
 
 export function installShutdownHandlers(deps: ShutdownDeps): void {
@@ -70,9 +70,9 @@ export function installShutdownHandlers(deps: ShutdownDeps): void {
     }, 20_000);
     forceTimer.unref();
 
-    await deps.workspaceHeartbeat.stop();
-    await deps.heartbeat.stop();
-    if (deps.filing) await deps.filing.stop();
+    await stopWorkspaceHeartbeatService();
+    await stopHeartbeatService();
+    await stopFilingService();
 
     // Run registered skill shutdown hooks (e.g. meet-join session teardown)
     // before stopping the server so any HTTP round-trips and SSE emissions
@@ -87,7 +87,7 @@ export function installShutdownHandlers(deps: ShutdownDeps): void {
     // This ensures no workspace state is lost during graceful shutdown.
     try {
       log.info({ phase: "pre_stop" }, "Committing pending workspace changes");
-      await deps.workspaceHeartbeat.commitAllPending();
+      await commitAllPendingWorkspaceChanges();
     } catch (err) {
       log.warn({ err, phase: "pre_stop" }, "Shutdown workspace commit failed");
     }
@@ -98,7 +98,7 @@ export function installShutdownHandlers(deps: ShutdownDeps): void {
     // (e.g. in-flight tool executions completing during drain).
     try {
       log.info({ phase: "post_stop" }, "Final workspace commit sweep");
-      await deps.workspaceHeartbeat.commitAllPending();
+      await commitAllPendingWorkspaceChanges();
     } catch (err) {
       log.warn(
         { err, phase: "post_stop" },

package/src/filing/filing-service.ts

@@ -417,6 +417,26 @@ export class FilingService {
   }
 }
 
+/**
+ * Construct and start the filing service singleton. Skipped under memory v2 —
+ * the v2 consolidation job owns periodic background memory processing, so
+ * running filing too would be redundant.
+ */
+export function startFilingService(): void {
+  if (getConfig().memory.v2.enabled) {
+    log.info(
+      "Filing service skipped — memory v2 consolidation is the active background memory job",
+    );
+    return;
+  }
+  new FilingService().start();
+}
+
+/** Stop the filing service singleton if one is running; no-op otherwise. */
+export async function stopFilingService(): Promise<void> {
+  await FilingService.getInstance()?.stop();
+}
+
 function isWithinActiveHours(
   hour: number,
   start: number,

package/src/heartbeat/__tests__/heartbeat-service.test.ts

@@ -9,12 +9,21 @@ let workspaceDir: string;
 // no-op in these tests.
 const publishSpy = mock<(event: unknown) => Promise<void>>(async () => {});
 
+// Capture broadcastMessage calls so tests can assert on the alerts and
+// conversation-created events the heartbeat service emits directly.
+type BroadcastedMessage = { type: string; [key: string]: unknown };
+const broadcastedMessages: BroadcastedMessage[] = [];
+let onBroadcast: ((msg: BroadcastedMessage) => void) | null = null;
+
 mock.module("../../runtime/assistant-event-hub.js", () => ({
   assistantEventHub: {
     publish: publishSpy,
     subscribe: () => () => {},
   },
-  broadcastMessage: () => {},
+  broadcastMessage: (msg: BroadcastedMessage) => {
+    broadcastedMessages.push(msg);
+    onBroadcast?.(msg);
+  },
 }));
 
 // Stub workspace prompt reads so the heartbeat service doesn't try to
@@ -224,6 +233,8 @@ beforeEach(() => {
   origWorkspaceDir = process.env.VELLUM_WORKSPACE_DIR;
   process.env.VELLUM_WORKSPACE_DIR = workspaceDir;
   publishSpy.mockClear();
+  broadcastedMessages.length = 0;
+  onBroadcast = null;
   runBackgroundJobCalls.length = 0;
   skipHeartbeatRunCalls.length = 0;
   preFirstMessageGateOpen = true;
@@ -249,9 +260,7 @@ afterEach(() => {
 
 describe("HeartbeatService", () => {
   test("invokes runBackgroundJob with expected options on each tick", async () => {
-    const service = new HeartbeatService({
-      alerter: () => {},
-    });
+    const service = new HeartbeatService();
 
     await service.runOnce({ force: true });
 
@@ -286,13 +295,17 @@ describe("HeartbeatService", () => {
       return { conversationId: STUB_CONVERSATION_ID, ok: true };
     };
 
-    const service = new HeartbeatService({
-      alerter: () => {},
-      onConversationCreated: (info) => {
-        created.push(info);
+    onBroadcast = (msg) => {
+      if (msg.type === "heartbeat_conversation_created") {
+        created.push({
+          conversationId: msg.conversationId as string,
+          title: msg.title as string,
+        });
         callbackFiredBeforeRunnerResolved = !runnerHasResolved;
-      },
-    });
+      }
+    };
+
+    const service = new HeartbeatService();
 
     await service.runOnce({ force: true });
 
@@ -314,17 +327,16 @@ describe("HeartbeatService", () => {
       return { conversationId: STUB_CONVERSATION_ID, ok: true };
     };
 
-    const alerts: unknown[] = [];
-    const service = new HeartbeatService({
-      alerter: (alert) => alerts.push(alert),
-    });
+    const service = new HeartbeatService();
 
     await service.runOnce({ force: true });
 
     expect(runnerCompleted).toBe(true);
-    // No alerter call because the runner returned ok=true and there was no
-    // outer-timeout failure to surface.
-    expect(alerts).toHaveLength(0);
+    // No heartbeat_alert broadcast because the runner returned ok=true and
+    // there was no outer-timeout failure to surface.
+    expect(
+      broadcastedMessages.filter((m) => m.type === "heartbeat_alert"),
+    ).toHaveLength(0);
   });
 
   test("calls alerter with the failure message when the runner reports ok=false", async () => {
@@ -335,14 +347,13 @@ describe("HeartbeatService", () => {
       errorKind: "exception",
     });
 
-    const alerts: Array<{ type: string; title: string; body: string }> = [];
-    const service = new HeartbeatService({
-      alerter: (alert) =>
-        alerts.push(alert as { type: string; title: string; body: string }),
-    });
+    const service = new HeartbeatService();
 
     await service.runOnce({ force: true });
 
+    const alerts = broadcastedMessages.filter(
+      (m) => m.type === "heartbeat_alert",
+    );
     expect(alerts).toHaveLength(1);
     expect(alerts[0]).toMatchObject({
       type: "heartbeat_alert",
@@ -352,21 +363,18 @@ describe("HeartbeatService", () => {
   });
 
   test("does not call alerter when the runner reports ok=true", async () => {
-    const alerts: unknown[] = [];
-    const service = new HeartbeatService({
-      alerter: (alert) => alerts.push(alert),
-    });
+    const service = new HeartbeatService();
 
     await service.runOnce({ force: true });
 
-    expect(alerts).toHaveLength(0);
+    expect(
+      broadcastedMessages.filter((m) => m.type === "heartbeat_alert"),
+    ).toHaveLength(0);
   });
 
   test("scheduled run skips with reason 'pre_first_user_message' when the user has not yet interacted", async () => {
     preFirstMessageGateOpen = false;
-    const service = new HeartbeatService({
-      alerter: () => {},
-    });
+    const service = new HeartbeatService();
     // start() seeds `_pendingRunId` via `scheduleNextRun` so the skip is
     // recorded with the pending run id. Without start() the test still
     // passes the no-LLM-call assertion but the skip record would be a
@@ -393,9 +401,7 @@ describe("HeartbeatService", () => {
 
   test("forced run bypasses the pre-first-message gate (manual operator action)", async () => {
     preFirstMessageGateOpen = false;
-    const service = new HeartbeatService({
-      alerter: () => {},
-    });
+    const service = new HeartbeatService();
 
     await service.runOnce({ force: true });
 
@@ -408,7 +414,7 @@ describe("HeartbeatService", () => {
   describe("max consecutive runs cap", () => {
     test("skips with reason 'max_consecutive_runs' after the cap is hit", async () => {
       stubConfig.heartbeat.maxConsecutiveRuns = 2;
-      const service = new HeartbeatService({ alerter: () => {} });
+      const service = new HeartbeatService();
 
       expect(await service.runOnce({ force: false })).toBe(true);
       expect(await service.runOnce({ force: false })).toBe(true);
@@ -422,7 +428,7 @@ describe("HeartbeatService", () => {
 
     test("resetTimer() clears the counter so auto runs resume", async () => {
       stubConfig.heartbeat.maxConsecutiveRuns = 1;
-      const service = new HeartbeatService({ alerter: () => {} });
+      const service = new HeartbeatService();
       service.start();
       try {
         await service.runOnce({ force: false });
@@ -452,7 +458,7 @@ describe("HeartbeatService", () => {
         return { conversationId: STUB_CONVERSATION_ID, ok: true };
       };
 
-      const service = new HeartbeatService({ alerter: () => {} });
+      const service = new HeartbeatService();
       service.start();
       try {
         const runPromise = service.runOnce({ force: false });
@@ -480,7 +486,7 @@ describe("HeartbeatService", () => {
 
     test("null disables the cap entirely", async () => {
       stubConfig.heartbeat.maxConsecutiveRuns = null;
-      const service = new HeartbeatService({ alerter: () => {} });
+      const service = new HeartbeatService();
 
       for (let i = 0; i < 5; i++) {
         expect(await service.runOnce({ force: false })).toBe(true);
@@ -493,7 +499,7 @@ describe("HeartbeatService", () => {
 
     test("force runs bypass the cap and do not increment the counter", async () => {
       stubConfig.heartbeat.maxConsecutiveRuns = 2;
-      const service = new HeartbeatService({ alerter: () => {} });
+      const service = new HeartbeatService();
 
       // Five force runs would push us well past the cap if force counted.
       for (let i = 0; i < 5; i++) {
@@ -511,7 +517,7 @@ describe("HeartbeatService", () => {
 
     test("reconfigure() resets the counter", async () => {
       stubConfig.heartbeat.maxConsecutiveRuns = 1;
-      const service = new HeartbeatService({ alerter: () => {} });
+      const service = new HeartbeatService();
       service.start();
       try {
         await service.runOnce({ force: false });

package/src/heartbeat/heartbeat-service.ts

@@ -16,6 +16,7 @@ import {
   resolveGuardianPersona,
 } from "../prompts/persona-resolver.js";
 import { isTemplateContent } from "../prompts/system-prompt.js";
+import { broadcastMessage } from "../runtime/assistant-event-hub.js";
 import { runBackgroundJob } from "../runtime/background-job-runner.js";
 import { hasReceivedUserMessage } from "../runtime/pre-first-message-gate.js";
 import { computeNextRunAt } from "../schedule/recurrence-engine.js";
@@ -110,11 +111,6 @@ function refreshBackgroundWakeIntentSoon(reason: string): void {
 }
 
 export interface HeartbeatDeps {
-  alerter: (alert: HeartbeatAlert) => void;
-  onConversationCreated?: (info: {
-    conversationId: string;
-    title: string;
-  }) => void;
   /** Override for current hour (0-23), for testing. */
   getCurrentHour?: () => number;
 }
@@ -163,7 +159,7 @@ export class HeartbeatService {
   // after a guardian message can detect the reset and skip its increment.
   private _resetGeneration = 0;
 
-  constructor(deps: HeartbeatDeps) {
+  constructor(deps: HeartbeatDeps = {}) {
     this.deps = deps;
     HeartbeatService.instance = this;
   }
@@ -670,13 +666,13 @@ export class HeartbeatService {
     } catch (err) {
       log.error({ err }, "Credential health check failed");
       try {
-        this.deps.alerter({
+        broadcastMessage({
           type: "heartbeat_alert",
           title: "Credential Health Check Failed",
           body:
             "Could not verify OAuth credential health. " +
             (err instanceof Error ? err.message : String(err)),
-        });
+        } satisfies HeartbeatAlert);
       } catch {
         // Last resort — alerter itself failed. Already logged above.
       }
@@ -798,7 +794,8 @@ export class HeartbeatService {
       deferNotifications: true,
       onConversationCreated: (newConversationId) => {
         conversationId = newConversationId;
-        this.deps.onConversationCreated?.({
+        broadcastMessage({
+          type: "heartbeat_conversation_created",
           conversationId: newConversationId,
           title: "Heartbeat",
         });
@@ -860,11 +857,11 @@ export class HeartbeatService {
     // recovery sweep) already alerted for this run.
     if (transitioned) {
       try {
-        this.deps.alerter({
+        broadcastMessage({
           type: "heartbeat_alert",
           title: "Heartbeat Failed",
           body: result.error?.message ?? "Unknown error",
-        });
+        } satisfies HeartbeatAlert);
       } catch (alertErr) {
         log.error({ alertErr }, "Failed to broadcast heartbeat alert");
       }
@@ -919,6 +916,22 @@ This is one of your first heartbeats. Your user hasn't heard from you yet and ma
   }
 }
 
+/**
+ * Construct and start the heartbeat service singleton, returning it so callers
+ * can wire it into the background-wake runtime. start() self-gates on
+ * `heartbeat.enabled` and logs its own status.
+ */
+export function startHeartbeatService(): HeartbeatService {
+  const service = new HeartbeatService();
+  service.start();
+  return service;
+}
+
+/** Stop the heartbeat service singleton if one is running; no-op otherwise. */
+export async function stopHeartbeatService(): Promise<void> {
+  await HeartbeatService.getInstance()?.stop();
+}
+
 function isDiskPressureBackgroundLocked(logKey: string): boolean {
   const diskPressureGate = checkDiskPressureBackgroundGate("background-work");
   if (diskPressureGate.action === "allow") return false;

package/src/workspace/heartbeat-service.ts

@@ -374,6 +374,35 @@ export class WorkspaceHeartbeatService {
   }
 }
 
+// ---------------------------------------------------------------------------
+// Singleton
+// ---------------------------------------------------------------------------
+
+let instance: WorkspaceHeartbeatService | null = null;
+
+/** Construct and start the workspace heartbeat service singleton. */
+export function startWorkspaceHeartbeatService(): void {
+  instance = new WorkspaceHeartbeatService();
+  instance.start();
+}
+
+/**
+ * Stop the workspace heartbeat service singleton if one is running. The instance
+ * is retained so a final commitAllPendingWorkspaceChanges() during shutdown can
+ * still flush after the periodic loop has stopped.
+ */
+export async function stopWorkspaceHeartbeatService(): Promise<void> {
+  await instance?.stop();
+}
+
+/**
+ * Commit any uncommitted workspace changes via the singleton; no-op when the
+ * service was never started.
+ */
+export async function commitAllPendingWorkspaceChanges(): Promise<void> {
+  await instance?.commitAllPending();
+}
+
 /**
  * @internal Test-only: clear the dirty tracking state
  */