@vellumai/assistant 0.11.2 → 0.11.3-dev.202608080427.92f668a

package/src/runtime/routes/__tests__/plugins-routes.test.ts

@@ -38,6 +38,9 @@
  *     `plugins:list` tag via the canonical resource-sync publisher (enable and
  *     disable emit the SAME invalidation)
  *   - Threads `x-vellum-client-id` into the published event's `originClientId`
+ *   - Pokes the plugin-declared schedule reconcile on a successful toggle (and
+ *     not on a failed one), so the plugin's rows disarm / re-arm immediately
+ *     instead of at the reconciler's next backstop sweep
  *   - A broadcast failure does not fail a successful toggle (the publisher
  *     swallows hub errors)
  *   - Maps `InvalidPluginNameError` → BadRequestError (400)
@@ -106,6 +109,7 @@ import {
 } from "../../../cli/lib/uninstall-plugin.js";
 import {
   PluginMergeBaselineError,
+  PluginNotCuratedError,
   PluginNotUpgradableError,
   type PluginUpgradeResult,
   type UpgradePluginDeps,
@@ -249,6 +253,7 @@ const upgradeSpy = mock(
 
 mock.module("../../../cli/lib/upgrade-plugin.js", () => ({
   PluginMergeBaselineError,
+  PluginNotCuratedError,
   PluginNotUpgradableError,
   upgradePlugin: upgradeSpy,
 }));
@@ -311,6 +316,15 @@ mock.module("../../../cli/lib/toggle-plugin.js", () => ({
   enablePlugin: enablePluginSpy,
 }));
 
+// Spy on the plugin-schedule reconcile the toggle handlers poke. The handlers
+// import it lazily at call time, so this mock intercepts the dynamic import
+// and keeps the reconciler's persistence graph out of the test.
+const reconcilePluginSchedulesSpy = mock(() => Promise.resolve());
+
+mock.module("../../../schedule/plugin-schedule-reconciler.js", () => ({
+  reconcilePluginSchedules: reconcilePluginSchedulesSpy,
+}));
+
 // Spy on broadcastMessage so we can assert the sync_changed invalidation the
 // enable/disable handlers emit. The handlers publish through the canonical
 // `publishPluginsChanged` → `publishSyncInvalidation` path (both left real), so
@@ -1883,7 +1897,14 @@ function inspection(
     remoteError: overrides.remoteError ?? null,
     surfaces:
       overrides.surfaces === undefined
-        ? { skills: [], hooks: ["post-model-call"], tools: [] }
+        ? {
+            skills: [],
+            hooks: ["post-model-call"],
+            tools: [],
+            schedules: [
+              { name: "digest", cadence: "0 9 * * *", mode: "execute" },
+            ],
+          }
         : overrides.surfaces,
   };
 }
@@ -1913,6 +1934,26 @@ describe("GET /v1/plugins/:name/inspect", () => {
     expect(inspectSpy.mock.calls[0]?.[0]).toEqual({ name: "level-up" });
   });
 
+  test("the inspect wire schema carries the schedules surface", async () => {
+    // GIVEN an inspection whose surfaces declare a schedule
+    inspectSpy.mockImplementation(async () => inspection());
+    const result = await invokeInspect({ pathParams: { name: "level-up" } });
+
+    // WHEN the handler result is parsed through the route's response schema
+    // (zod strips undeclared keys, so an omission would drop the field)
+    const route = PLUGINS_ROUTES.find(
+      (r) => r.operationId === "plugins_inspect",
+    )!;
+    const parsed = (
+      route.responseBody as { parse: (v: unknown) => PluginInspection }
+    ).parse(result);
+
+    // THEN the declared schedules survive the wire contract
+    expect(parsed.surfaces?.schedules).toEqual([
+      { name: "digest", cadence: "0 9 * * *", mode: "execute" },
+    ]);
+  });
+
   test("a captured marketplace error is returned as 200 with remote-unavailable, not thrown", async () => {
     // GIVEN the catalog was unreachable but a local copy exists, so the lib
     // returns a status rather than throwing
@@ -2088,6 +2129,7 @@ describe("POST /v1/plugins/:name/upgrade", () => {
       name: "level-up",
       dryRun: false,
       strategy: undefined,
+      marketplaceOnly: false,
     });
   });
 
@@ -2109,6 +2151,7 @@ describe("POST /v1/plugins/:name/upgrade", () => {
       name: "level-up",
       dryRun: undefined,
       strategy: "ours",
+      marketplaceOnly: false,
     });
   });
 
@@ -2136,9 +2179,94 @@ describe("POST /v1/plugins/:name/upgrade", () => {
       name: "level-up",
       dryRun: undefined,
       strategy: "assistant",
+      marketplaceOnly: false,
     });
   });
 
+  test("refuses a concurrent upgrade of the same plugin with ConflictError (409)", async () => {
+    // Two upgrades of one plugin derive the same staging path in this
+    // process, so the second would delete the first's tree mid-swap. It is
+    // refused instead \u2014 the monitor's auto-update sweep and a user clicking
+    // Upgrade can now land at the same moment.
+    let releaseFirst: () => void = () => {};
+    const firstStarted = Promise.withResolvers<void>();
+    upgradeSpy.mockImplementation(async () => {
+      firstStarted.resolve();
+      await new Promise<void>((resolve) => {
+        releaseFirst = resolve;
+      });
+      return upgradeResult();
+    });
+
+    const first = invokeUpgrade({ pathParams: { name: "level-up" } });
+    await firstStarted.promise;
+
+    await expect(
+      invokeUpgrade({ pathParams: { name: "level-up" } }),
+    ).rejects.toBeInstanceOf(ConflictError);
+
+    releaseFirst();
+    await expect(first).resolves.toMatchObject({ outcome: "upgraded" });
+
+    // The guard is released once the first settles, so the next one runs.
+    upgradeSpy.mockImplementation(async () => upgradeResult());
+    await expect(
+      invokeUpgrade({ pathParams: { name: "level-up" } }),
+    ).resolves.toMatchObject({ outcome: "upgraded" });
+  });
+
+  test("a different plugin is not blocked by an in-flight upgrade", async () => {
+    let releaseFirst: () => void = () => {};
+    const firstStarted = Promise.withResolvers<void>();
+    upgradeSpy.mockImplementation(async (opts) => {
+      if (opts.name === "level-up") {
+        firstStarted.resolve();
+        await new Promise<void>((resolve) => {
+          releaseFirst = resolve;
+        });
+      }
+      return upgradeResult({ name: opts.name });
+    });
+
+    const first = invokeUpgrade({ pathParams: { name: "level-up" } });
+    await firstStarted.promise;
+
+    await expect(
+      invokeUpgrade({ pathParams: { name: "other-plugin" } }),
+    ).resolves.toMatchObject({ name: "other-plugin" });
+
+    releaseFirst();
+    await first;
+  });
+
+  test("a dry run neither takes nor respects the in-flight guard", async () => {
+    // Dry runs return before the swap boundary, so they never stage.
+    let releaseFirst: () => void = () => {};
+    const firstStarted = Promise.withResolvers<void>();
+    upgradeSpy.mockImplementation(async (opts) => {
+      if (!opts.dryRun) {
+        firstStarted.resolve();
+        await new Promise<void>((resolve) => {
+          releaseFirst = resolve;
+        });
+      }
+      return upgradeResult();
+    });
+
+    const first = invokeUpgrade({ pathParams: { name: "level-up" } });
+    await firstStarted.promise;
+
+    await expect(
+      invokeUpgrade({
+        pathParams: { name: "level-up" },
+        body: { dryRun: true },
+      }),
+    ).resolves.toMatchObject({ outcome: "upgraded" });
+
+    releaseFirst();
+    await first;
+  });
+
   test("PluginMergeBaselineError \u2192 ConflictError (409)", async () => {
     // A merge strategy whose install-time baseline can't be reconstructed: a
     // well-formed request that isn't actionable in the current state.
@@ -2177,6 +2305,10 @@ describe("POST /v1/plugins/:name/upgrade", () => {
     expect(upgradeSpy.mock.calls[0]?.[0]).toEqual({
       name: "level-up",
       dryRun: undefined,
+      strategy: undefined,
+      // Unlike dryRun, an absent flag here is a definite "no": the untrusted
+      // direct path stays available unless a caller opts out of it.
+      marketplaceOnly: false,
     });
   });
 
@@ -2220,6 +2352,41 @@ describe("POST /v1/plugins/:name/upgrade", () => {
     ).rejects.toBeInstanceOf(ConflictError);
   });
 
+  test("marketplaceOnly is forwarded so the lib enforces it, not the caller", async () => {
+    // The lib re-inspects the catalog inside the call, so the flag has to
+    // travel with the request: a caller's own pre-check cannot bind a decision
+    // the lib makes afterwards.
+    upgradeSpy.mockImplementation(async () => upgradeResult());
+
+    await invokeUpgrade({
+      pathParams: { name: "level-up" },
+      body: { marketplaceOnly: true },
+    });
+
+    expect(upgradeSpy.mock.calls[0]?.[0]).toEqual({
+      name: "level-up",
+      dryRun: undefined,
+      strategy: undefined,
+      marketplaceOnly: true,
+    });
+  });
+
+  test("PluginNotCuratedError → ConflictError (409)", async () => {
+    // A marketplaceOnly caller asked about an install the catalog does not
+    // claim. Retrying changes nothing: only a human upgrading it without the
+    // flag can move it.
+    upgradeSpy.mockImplementation(async () => {
+      throw new PluginNotCuratedError("level-up");
+    });
+
+    await expect(
+      invokeUpgrade({
+        pathParams: { name: "level-up" },
+        body: { marketplaceOnly: true },
+      }),
+    ).rejects.toBeInstanceOf(ConflictError);
+  });
+
   test("PluginNotFoundError → NotFoundError (404)", async () => {
     upgradeSpy.mockImplementation(async () => {
       throw new PluginNotFoundError("level-up", "main", "vellum-ai/level-up");
@@ -2414,6 +2581,21 @@ function invokeDisable(args: RouteHandlerArgs = {}): { ok: boolean } {
   return disableHandler(args) as { ok: boolean };
 }
 
+/**
+ * Wait for the toggle handlers' fire-and-forget reconcile poke to land. The
+ * lazy `import()` resolves off the microtask queue, so the assertion cannot
+ * run on the handler's synchronous return.
+ */
+async function waitForScheduleReconcile(): Promise<void> {
+  for (let i = 0; i < 50; i++) {
+    if (reconcilePluginSchedulesSpy.mock.calls.length > 0) {
+      return;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 2));
+  }
+  throw new Error("plugin schedule reconcile was never triggered");
+}
+
 /** Assert the spy received exactly one sync_changed carrying `plugins:list`. */
 function expectPluginsListBroadcast(): void {
   expect(broadcastMessageSpy.mock.calls).toHaveLength(1);
@@ -2426,6 +2608,15 @@ describe("POST /v1/plugins/:name/enable", () => {
   beforeEach(() => {
     enablePluginSpy.mockReset();
     broadcastMessageSpy.mockReset();
+    reconcilePluginSchedulesSpy.mockClear();
+  });
+
+  test("reconciles plugin-declared schedules so the plugin's rows re-arm now", async () => {
+    enablePluginSpy.mockImplementation((name) => toggleResult(name, "enable"));
+
+    invokeEnable({ pathParams: { name: "simple-memory" } });
+
+    await waitForScheduleReconcile();
   });
 
   test("enables the plugin and broadcasts sync_changed(plugins:list)", () => {
@@ -2504,6 +2695,31 @@ describe("POST /v1/plugins/:name/disable", () => {
   beforeEach(() => {
     disablePluginSpy.mockReset();
     broadcastMessageSpy.mockReset();
+    reconcilePluginSchedulesSpy.mockClear();
+  });
+
+  test("reconciles plugin-declared schedules so the plugin's rows disarm now", async () => {
+    disablePluginSpy.mockImplementation((name) =>
+      toggleResult(name, "disable"),
+    );
+
+    invokeDisable({ pathParams: { name: "simple-memory" } });
+
+    // Without this poke the rows stay armed until the reconciler's next
+    // backstop sweep.
+    await waitForScheduleReconcile();
+  });
+
+  test("a failed toggle does not poke the schedule reconcile", async () => {
+    disablePluginSpy.mockImplementation((name) => {
+      throw new PluginDirectoryNotFoundError(name);
+    });
+
+    expect(() => invokeDisable({ pathParams: { name: "ghost" } })).toThrow(
+      NotFoundError,
+    );
+    await new Promise((resolve) => setTimeout(resolve, 10));
+    expect(reconcilePluginSchedulesSpy).not.toHaveBeenCalled();
   });
 
   test("disables the plugin and broadcasts sync_changed(plugins:list)", () => {

package/src/runtime/routes/__tests__/question-routes.test.ts

@@ -394,4 +394,68 @@ describe("POST /v1/question-response", () => {
     // Pending interaction left in place.
     expect(pendingInteractions.get("req-legacy-multi")).toBeDefined();
   });
+
+  // A gone interaction must read as 404 for every body shape. Clients treat
+  // 404 as the terminal signal that retires a stale card; a 400 leaves the
+  // card on screen and surfaces a body-validation string the user cannot act
+  // on. The legacy shapes are the ones that matter here: the web client sends
+  // them for every single-question answer, which is the common prompt.
+  test("legacy option against a gone interaction is 404, not a validation 400", async () => {
+    let thrown: unknown;
+    try {
+      await call({
+        body: { requestId: "req-gone", kind: "option", optionId: "yes" },
+      });
+    } catch (err) {
+      thrown = err;
+    }
+    expect(thrown).toBeInstanceOf(NotFoundError);
+  });
+
+  test("legacy free-text against a gone interaction is 404, not a validation 400", async () => {
+    let thrown: unknown;
+    try {
+      await call({
+        body: { requestId: "req-gone", kind: "free_text", text: "maybe" },
+      });
+    } catch (err) {
+      thrown = err;
+    }
+    expect(thrown).toBeInstanceOf(NotFoundError);
+  });
+
+  test("close against a gone interaction is 404", async () => {
+    let thrown: unknown;
+    try {
+      await call({ body: { requestId: "req-gone", kind: "close" } });
+    } catch (err) {
+      thrown = err;
+    }
+    expect(thrown).toBeInstanceOf(NotFoundError);
+  });
+
+  test("legacy option against a confirmation requestId is 404, not a validation 400", async () => {
+    // Cross-talk safety has to hold for the legacy shapes too: the wrong-kind
+    // interaction carries no question metadata for the shim to read.
+    pendingInteractions.register("req-confirm-legacy", {
+      conversationId: "conv-1",
+      kind: "confirmation",
+    });
+
+    let thrown: unknown;
+    try {
+      await call({
+        body: {
+          requestId: "req-confirm-legacy",
+          kind: "option",
+          optionId: "y",
+        },
+      });
+    } catch (err) {
+      thrown = err;
+    }
+    expect(thrown).toBeInstanceOf(NotFoundError);
+    // The confirmation is left intact rather than consumed.
+    expect(pendingInteractions.get("req-confirm-legacy")).toBeDefined();
+  });
 });

package/src/runtime/routes/__tests__/retrospective-routes.test.ts

@@ -413,6 +413,26 @@ describe("getRetrospectiveConfig handler", () => {
     expect(result.success).toBe(true);
   });
 
+  test("available but not enabled when only the retrospective switch is off", async () => {
+    writeFileSync(
+      configPath,
+      JSON.stringify(
+        { memory: { retrospective: { enabled: false } } },
+        null,
+        2,
+      ) + "\n",
+    );
+
+    const handler = findHandler("getRetrospectiveConfig");
+    const result = (await handler({})) as ConfigResponse;
+
+    // `available` stays true so the Settings row still renders. It reads
+    // "Paused" rather than disappearing as it would with memory off.
+    expect(result.available).toBe(true);
+    expect(result.enabled).toBe(false);
+    expect(result.success).toBe(true);
+  });
+
   test("stays available when memory v2 is disabled (retrospectives do not gate on v2)", async () => {
     writeFileSync(
       configPath,

package/src/runtime/routes/__tests__/skill-history-route.test.ts

@@ -0,0 +1,116 @@
+/**
+ * Tests for the `getSkillHistory` route's current-resource boundary.
+ *
+ * The service layer reads retained git history, which outlives the skill it
+ * describes: a deleted skill's commits stay in the workspace repository
+ * forever. The route is therefore the only place that can decide whether an id
+ * still names something, and it must reach the same answer as the sibling file
+ * routes rather than serving history for a resource the rest of the API
+ * reports as gone.
+ *
+ * Both collaborators are mocked, because what is under test is the ordering
+ * between them: the existence check has to gate the history read, not run
+ * alongside it.
+ */
+
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+const skillExistsLocallyMock = mock((_id: string): boolean => true);
+const getSkillHistoryMock = mock(async (_id: string, _opts?: unknown) => ({
+  skillId: _id,
+  revisions: [{ id: "abc1234", changedAt: "", files: ["SKILL.md"], diff: "" }],
+  truncatedByCompaction: false,
+}));
+
+mock.module("../../../daemon/handlers/skills.js", () => ({
+  skillExistsLocally: skillExistsLocallyMock,
+  // The route module imports the whole handler surface; the rest is unused
+  // here and only needs to exist.
+  checkSkillUpdates: mock(),
+  configureSkill: mock(),
+  createSkill: mock(),
+  disableSkill: mock(),
+  draftSkill: mock(),
+  enableSkill: mock(),
+  getSkill: mock(),
+  getSkillFileContent: mock(),
+  getSkillFiles: mock(),
+  getSkillLocalDetail: mock(),
+  inspectSkill: mock(),
+  installSkill: mock(),
+  listSkills: mock(),
+  listSkillsFiltered: mock(),
+  searchSkills: mock(),
+  uninstallSkill: mock(),
+  updateSkill: mock(),
+}));
+
+mock.module("../../../skills/skill-history.js", () => ({
+  getSkillHistory: getSkillHistoryMock,
+}));
+
+const { ROUTES } = await import("../skills-routes.js");
+
+const handler = ROUTES.find(
+  (r) => r.operationId === "getSkillHistory",
+)!.handler;
+
+beforeEach(() => {
+  skillExistsLocallyMock.mockClear();
+  getSkillHistoryMock.mockClear();
+  skillExistsLocallyMock.mockImplementation(() => true);
+});
+
+describe("getSkillHistory route", () => {
+  test("returns history for a skill that currently exists", async () => {
+    const result = (await handler({
+      pathParams: { id: "release-triage" },
+    })) as {
+      revisions: unknown[];
+    };
+
+    expect(result.revisions).toHaveLength(1);
+    expect(getSkillHistoryMock).toHaveBeenCalledTimes(1);
+  });
+
+  test("404s for a deleted skill whose commits are still in the repository", async () => {
+    // The skill is gone from the resolver, but git would still answer.
+    skillExistsLocallyMock.mockImplementation(() => false);
+
+    await expect(
+      handler({ pathParams: { id: "release-triage" } }),
+    ).rejects.toThrow(/not found/i);
+  });
+
+  test("does not read history at all when the skill is gone", async () => {
+    skillExistsLocallyMock.mockImplementation(() => false);
+
+    await Promise.resolve(
+      handler({ pathParams: { id: "release-triage" } }),
+    ).catch(() => {});
+
+    // Ordering is the point: a check that ran after the read would still
+    // reject, but would have spent the git traversal to do it.
+    expect(getSkillHistoryMock).not.toHaveBeenCalled();
+  });
+
+  test("rejects a malformed id as the caller's error, not a server fault", async () => {
+    getSkillHistoryMock.mockImplementation(() => {
+      throw new Error("Invalid skill id: contains a path separator");
+    });
+
+    await expect(handler({ pathParams: { id: "bad" } })).rejects.toMatchObject({
+      statusCode: 400,
+    });
+  });
+
+  test("surfaces an unexpected service failure as a server error", async () => {
+    getSkillHistoryMock.mockImplementation(() => {
+      throw new Error("git exploded");
+    });
+
+    await expect(handler({ pathParams: { id: "ok" } })).rejects.toMatchObject({
+      statusCode: 500,
+    });
+  });
+});

package/src/runtime/routes/__tests__/sse-actor-principal-heal.test.ts

@@ -0,0 +1,165 @@
+/**
+ * Tests for the retrying SSE actor-principal self-heal.
+ *
+ * The invariant they pin: a single empty or failed guardian lookup must not
+ * strand the subscription without a principal. The read goes over the gateway
+ * IPC and comes back empty both when the transport fails and when no binding
+ * exists yet, and a subscription that stays principal-less rejects every
+ * host-proxy result its client submits with "Submitting actor does not match
+ * the target client's actor for this request" until it reconnects.
+ */
+import { describe, expect, mock, test } from "bun:test";
+
+import { startActorPrincipalHeal } from "../sse-actor-principal-heal.js";
+
+/** All-zero schedule so the retries run without real wall-clock delay. */
+const NO_DELAYS = [0, 0, 0];
+
+/** Minimal hub double: `needs` flips to false once a principal is filled. */
+function fakeHub(options?: { needs?: boolean }) {
+  let needs = options?.needs ?? true;
+  const filled: string[] = [];
+  return {
+    filled,
+    setNeeds(value: boolean) {
+      needs = value;
+    },
+    needsActorPrincipalHeal: mock(() => needs),
+    fillClientActorPrincipalId: mock((_connectionId: string, id: string) => {
+      filled.push(id);
+      needs = false;
+    }),
+  };
+}
+
+/** Let the heal's async loop run to completion. */
+async function settle(): Promise<void> {
+  for (let i = 0; i < 10; i++) {
+    await new Promise((resolve) => setTimeout(resolve, 0));
+  }
+}
+
+describe("startActorPrincipalHeal", () => {
+  test("fills the principal on the first successful attempt", async () => {
+    const hub = fakeHub();
+    startActorPrincipalHeal({
+      hub,
+      connectionId: "conn-1",
+      resolve: () => Promise.resolve("guardian-real-id"),
+      delaysMs: NO_DELAYS,
+    });
+    await settle();
+
+    expect(hub.filled).toEqual(["guardian-real-id"]);
+    expect(hub.needsActorPrincipalHeal).toHaveBeenCalledTimes(1);
+  });
+
+  test("retries after a lookup that resolves undefined (gateway unreachable)", async () => {
+    const hub = fakeHub();
+    let calls = 0;
+    startActorPrincipalHeal({
+      hub,
+      connectionId: "conn-1",
+      resolve: () => {
+        calls++;
+        // Two failed reads, then the gateway comes up.
+        return Promise.resolve(calls < 3 ? undefined : "guardian-real-id");
+      },
+      delaysMs: NO_DELAYS,
+    });
+    await settle();
+
+    expect(calls).toBe(3);
+    expect(hub.filled).toEqual(["guardian-real-id"]);
+  });
+
+  test("retries after a lookup that rejects", async () => {
+    const hub = fakeHub();
+    let calls = 0;
+    startActorPrincipalHeal({
+      hub,
+      connectionId: "conn-1",
+      resolve: () => {
+        calls++;
+        return calls === 1
+          ? Promise.reject(new Error("ipc timeout"))
+          : Promise.resolve("guardian-real-id");
+      },
+      delaysMs: NO_DELAYS,
+    });
+    await settle();
+
+    expect(calls).toBe(2);
+    expect(hub.filled).toEqual(["guardian-real-id"]);
+  });
+
+  test("stops retrying once the connection no longer needs healing", async () => {
+    // Models a disconnect (or a reconnect that replaced this subscription)
+    // between attempts: the loop must not keep polling the gateway for a
+    // connection that is gone.
+    const hub = fakeHub();
+    let calls = 0;
+    startActorPrincipalHeal({
+      hub,
+      connectionId: "conn-1",
+      resolve: () => {
+        calls++;
+        hub.setNeeds(false);
+        return Promise.resolve(undefined);
+      },
+      delaysMs: NO_DELAYS,
+    });
+    await settle();
+
+    expect(calls).toBe(1);
+    expect(hub.filled).toEqual([]);
+  });
+
+  test("never starts a lookup when the connection is already healed or gone", async () => {
+    const hub = fakeHub({ needs: false });
+    const resolve = mock(() => Promise.resolve("guardian-real-id"));
+    startActorPrincipalHeal({
+      hub,
+      connectionId: "conn-1",
+      resolve,
+      delaysMs: NO_DELAYS,
+    });
+    await settle();
+
+    expect(resolve).toHaveBeenCalledTimes(0);
+    expect(hub.filled).toEqual([]);
+  });
+
+  test("gives up after the schedule is exhausted without filling", async () => {
+    const hub = fakeHub();
+    let calls = 0;
+    startActorPrincipalHeal({
+      hub,
+      connectionId: "conn-1",
+      resolve: () => {
+        calls++;
+        return Promise.resolve(undefined);
+      },
+      delaysMs: NO_DELAYS,
+    });
+    await settle();
+
+    expect(calls).toBe(NO_DELAYS.length);
+    expect(hub.filled).toEqual([]);
+  });
+
+  test("dispatches the first attempt synchronously", () => {
+    const hub = fakeHub();
+    const resolve = mock(() => Promise.resolve("guardian-real-id"));
+    startActorPrincipalHeal({
+      hub,
+      connectionId: "conn-1",
+      resolve,
+      delaysMs: NO_DELAYS,
+    });
+
+    // No await: the leading zero delay must not cost a macrotask, so a
+    // warm-cache heal lands before the stream delivers its first event.
+    expect(resolve).toHaveBeenCalledTimes(1);
+  });
+});