@vellumai/assistant 0.7.3 → 0.8.1

package/src/__tests__/update-bulletin-job.test.ts

@@ -1,17 +1,10 @@
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import {
-  afterEach,
-  beforeEach,
-  describe,
-  expect,
-  mock,
-  test,
-} from "bun:test";
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
 
 import { getWorkspacePromptPath } from "../util/platform.js";
 
-// ── fs.readFileSync override (for gap 3 test) ────────────────────────
+// ── fs.readFileSync override (for read-failure test) ─────────────────
 // We mock node:fs so we can inject a readFileSync that throws for the
 // workspace path. All other call sites fall through to the real fs.
 const realReadFileSync = readFileSync;
@@ -54,62 +47,58 @@ mock.module("../config/loader.js", () => ({
   getConfig: () => ({ updates: updatesConfig }),
 }));
 
-// ── bootstrapConversation + wakeAgentForOpportunity mocks ────────────
-let bootstrapCalls = 0;
-let bootstrapLastArgs: Record<string, unknown> | null = null;
-let wakeCalls = 0;
-let wakeLastArgs: Record<string, unknown> | null = null;
-let wakeShouldThrow = false;
-let wakeInvoked = true;
-let wakeProducedToolCalls = false;
-// A side-effect function invoked during wake. Lets tests simulate the
-// agent deleting UPDATES.md while the wake is in flight.
-let wakeSideEffect: (() => void) | null = null;
-
-mock.module("../memory/conversation-bootstrap.js", () => ({
-  bootstrapConversation: (opts: Record<string, unknown>) => {
-    bootstrapCalls += 1;
-    bootstrapLastArgs = opts;
-    return { id: `conv-${bootstrapCalls}` };
-  },
-}));
+// ── pre-first-message gate stub ──────────────────────────────────────
+// Default: gate open (user has interacted) so the existing happy/sad
+// paths exercise the bulletin logic. A dedicated test below flips this
+// to false to assert the gate trips.
+let preFirstMessageGateOpen = true;
 
-// ── deleteConversation mock (orphan cleanup path) ────────────────────
-let deleteCalls = 0;
-const deletedIds: string[] = [];
-let deleteShouldThrow = false;
-
-mock.module("../memory/conversation-crud.js", () => ({
-  deleteConversation: (id: string) => {
-    deleteCalls += 1;
-    deletedIds.push(id);
-    if (deleteShouldThrow) {
-      throw new Error("simulated delete failure");
-    }
-    return { segmentIds: [], deletedSummaryIds: [] };
-  },
+mock.module("../runtime/pre-first-message-gate.js", () => ({
+  hasReceivedUserMessage: () => preFirstMessageGateOpen,
 }));
 
-mock.module("../runtime/agent-wake.js", () => ({
-  wakeAgentForOpportunity: async (opts: Record<string, unknown>) => {
-    wakeCalls += 1;
-    wakeLastArgs = opts;
-    if (wakeSideEffect) {
-      wakeSideEffect();
+// ── runBackgroundJob mock ────────────────────────────────────────────
+let runBackgroundJobCalls = 0;
+let runBackgroundJobLastArgs: Record<string, unknown> | null = null;
+let runBackgroundJobShouldThrow = false;
+let runBackgroundJobOk = true;
+let runBackgroundJobErrorKind:
+  | "timeout"
+  | "model_provider"
+  | "exception"
+  | undefined = undefined;
+let runBackgroundJobErrorMessage: string | undefined = undefined;
+// A side-effect function invoked during the job. Lets tests simulate the
+// agent deleting UPDATES.md while the job is running.
+let runBackgroundJobSideEffect: (() => void) | null = null;
+
+mock.module("../runtime/background-job-runner.js", () => ({
+  runBackgroundJob: async (opts: Record<string, unknown>) => {
+    runBackgroundJobCalls += 1;
+    runBackgroundJobLastArgs = opts;
+    if (runBackgroundJobSideEffect) {
+      runBackgroundJobSideEffect();
     }
-    if (wakeShouldThrow) {
-      throw new Error("simulated wake failure");
+    if (runBackgroundJobShouldThrow) {
+      throw new Error("simulated runner failure");
+    }
+    if (runBackgroundJobOk) {
+      return {
+        conversationId: `conv-${runBackgroundJobCalls}`,
+        ok: true,
+      };
     }
     return {
-      invoked: wakeInvoked,
-      producedToolCalls: wakeProducedToolCalls,
+      conversationId: `conv-${runBackgroundJobCalls}`,
+      ok: false,
+      error: new Error(runBackgroundJobErrorMessage ?? "simulated failure"),
+      errorKind: runBackgroundJobErrorKind ?? "exception",
     };
   },
 }));
 
-const { runUpdateBulletinJobIfNeeded } = await import(
-  "../prompts/update-bulletin-job.js"
-);
+const { runUpdateBulletinJobIfNeeded } =
+  await import("../prompts/update-bulletin-job.js");
 
 const HASH_CHECKPOINT_KEY = "updates:last_processed_hash";
 const EMPTY_HASH = "empty";
@@ -124,19 +113,16 @@ describe("runUpdateBulletinJobIfNeeded", () => {
   beforeEach(() => {
     store.clear();
     setCheckpointCallCount = 0;
-    bootstrapCalls = 0;
-    bootstrapLastArgs = null;
-    wakeCalls = 0;
-    wakeLastArgs = null;
-    wakeShouldThrow = false;
-    wakeInvoked = true;
-    wakeProducedToolCalls = false;
-    wakeSideEffect = null;
+    runBackgroundJobCalls = 0;
+    runBackgroundJobLastArgs = null;
+    runBackgroundJobShouldThrow = false;
+    runBackgroundJobOk = true;
+    runBackgroundJobErrorKind = undefined;
+    runBackgroundJobErrorMessage = undefined;
+    runBackgroundJobSideEffect = null;
     readFileSyncOverride = null;
     updatesConfig.enabled = true;
-    deleteCalls = 0;
-    deletedIds.length = 0;
-    deleteShouldThrow = false;
+    preFirstMessageGateOpen = true;
     if (existsSync(workspacePath)) {
       rmSync(workspacePath);
     }
@@ -148,38 +134,45 @@ describe("runUpdateBulletinJobIfNeeded", () => {
     }
   });
 
-  test("config disabled — no bootstrap, no wake, no checkpoint change", async () => {
+  test("config disabled — no job, no checkpoint change", async () => {
     updatesConfig.enabled = false;
     writeFileSync(workspacePath, "## Real content", "utf-8");
 
     await runUpdateBulletinJobIfNeeded();
 
-    expect(bootstrapCalls).toBe(0);
-    expect(wakeCalls).toBe(0);
+    expect(runBackgroundJobCalls).toBe(0);
+    expect(setCheckpointCallCount).toBe(0);
+    expect(store.has(HASH_CHECKPOINT_KEY)).toBe(false);
+  });
+
+  test("pre-first-message gate closed — no job, checkpoint left UNCHANGED so the job retries after the user interacts", async () => {
+    preFirstMessageGateOpen = false;
+    writeFileSync(workspacePath, "## Real content", "utf-8");
+
+    await runUpdateBulletinJobIfNeeded();
+
+    expect(runBackgroundJobCalls).toBe(0);
     expect(setCheckpointCallCount).toBe(0);
     expect(store.has(HASH_CHECKPOINT_KEY)).toBe(false);
   });
 
-  test("file missing, stored hash absent — no wake; stored becomes 'empty'", async () => {
+  test("file missing, stored hash absent — no job; stored becomes 'empty'", async () => {
     expect(existsSync(workspacePath)).toBe(false);
     expect(store.has(HASH_CHECKPOINT_KEY)).toBe(false);
 
     await runUpdateBulletinJobIfNeeded();
 
-    expect(bootstrapCalls).toBe(0);
-    expect(wakeCalls).toBe(0);
+    expect(runBackgroundJobCalls).toBe(0);
     expect(store.get(HASH_CHECKPOINT_KEY)).toBe(EMPTY_HASH);
   });
 
-  test("file missing, stored hash already 'empty' — no wake; no checkpoint write", async () => {
+  test("file missing, stored hash already 'empty' — no job; no checkpoint write", async () => {
     store.set(HASH_CHECKPOINT_KEY, EMPTY_HASH);
-    // Reset the counter to ignore the priming write above.
     setCheckpointCallCount = 0;
 
     await runUpdateBulletinJobIfNeeded();
 
-    expect(bootstrapCalls).toBe(0);
-    expect(wakeCalls).toBe(0);
+    expect(runBackgroundJobCalls).toBe(0);
     expect(setCheckpointCallCount).toBe(0);
     expect(store.get(HASH_CHECKPOINT_KEY)).toBe(EMPTY_HASH);
   });
@@ -189,28 +182,25 @@ describe("runUpdateBulletinJobIfNeeded", () => {
 
     await runUpdateBulletinJobIfNeeded();
 
-    expect(bootstrapCalls).toBe(0);
-    expect(wakeCalls).toBe(0);
+    expect(runBackgroundJobCalls).toBe(0);
     expect(store.get(HASH_CHECKPOINT_KEY)).toBe(EMPTY_HASH);
   });
 
-  test("file present with content, wake produced tool calls — bootstrap + wake; stored hash is sha256(trimmed); source/origin are snake_case", async () => {
+  test("file present, job ok=true, file unchanged — stored hash is sha256(trimmed); jobName/source are kebab-case", async () => {
     const content = "## Release 1.2.3\n\nNew thing.\n";
     writeFileSync(workspacePath, content, "utf-8");
-    wakeProducedToolCalls = true;
 
     await runUpdateBulletinJobIfNeeded();
 
-    expect(bootstrapCalls).toBe(1);
-    expect(wakeCalls).toBe(1);
+    expect(runBackgroundJobCalls).toBe(1);
     expect(store.get(HASH_CHECKPOINT_KEY)).toBe(sha256(content.trim()));
-    // Gap 4: confirm snake_case reached the downstream mocks.
-    expect(bootstrapLastArgs?.source).toBe("updates_bulletin");
-    expect(bootstrapLastArgs?.origin).toBe("updates_bulletin");
-    expect(wakeLastArgs?.source).toBe("updates_bulletin");
+    expect(runBackgroundJobLastArgs?.jobName).toBe("update-bulletin");
+    expect(runBackgroundJobLastArgs?.source).toBe("update-bulletin");
+    expect(runBackgroundJobLastArgs?.origin).toBe("updates_bulletin");
+    expect(runBackgroundJobLastArgs?.callSite).toBe("mainAgent");
   });
 
-  test("file present, stored hash matches current — no wake", async () => {
+  test("file present, stored hash matches current — no job", async () => {
     const content = "## Release 1.2.3\n\nSame content.\n";
     writeFileSync(workspacePath, content, "utf-8");
     store.set(HASH_CHECKPOINT_KEY, sha256(content.trim()));
@@ -218,138 +208,53 @@ describe("runUpdateBulletinJobIfNeeded", () => {
 
     await runUpdateBulletinJobIfNeeded();
 
-    expect(bootstrapCalls).toBe(0);
-    expect(wakeCalls).toBe(0);
-    expect(setCheckpointCallCount).toBe(0);
-  });
-
-  test("wake returns invoked:false — checkpoint UNCHANGED + orphan conversation is cleaned up", async () => {
-    const content = "## Release Q\n\nResolver-missing scenario.\n";
-    writeFileSync(workspacePath, content, "utf-8");
-    wakeInvoked = false;
-    wakeProducedToolCalls = false;
-
-    await runUpdateBulletinJobIfNeeded();
-
-    expect(bootstrapCalls).toBe(1);
-    expect(wakeCalls).toBe(1);
-    // Critical: do NOT poison the checkpoint (round-1 behavior preserved).
-    expect(store.has(HASH_CHECKPOINT_KEY)).toBe(false);
-    expect(setCheckpointCallCount).toBe(0);
-    // Belt-and-suspenders: the orphan background conversation bootstrapped
-    // before the wake must be deleted so we don't leak DB rows on every
-    // silent no-op.
-    expect(deleteCalls).toBe(1);
-    expect(deletedIds).toEqual(["conv-1"]);
-  });
-
-  test("wake returns invoked:false AND deleteConversation throws — function still returns (cleanup error is swallowed)", async () => {
-    const content = "## Release Q2\n\nDelete-throws scenario.\n";
-    writeFileSync(workspacePath, content, "utf-8");
-    wakeInvoked = false;
-    wakeProducedToolCalls = false;
-    deleteShouldThrow = true;
-
-    await expect(runUpdateBulletinJobIfNeeded()).resolves.toBeUndefined();
-
-    expect(bootstrapCalls).toBe(1);
-    expect(wakeCalls).toBe(1);
-    expect(deleteCalls).toBe(1);
-    // Checkpoint still untouched.
-    expect(store.has(HASH_CHECKPOINT_KEY)).toBe(false);
+    expect(runBackgroundJobCalls).toBe(0);
     expect(setCheckpointCallCount).toBe(0);
   });
 
-  test("wake invoked normally — deleteConversation is NOT called (happy path)", async () => {
-    const content = "## Release Q3\n\nNormal happy-path scenario.\n";
-    writeFileSync(workspacePath, content, "utf-8");
-    wakeInvoked = true;
-    wakeProducedToolCalls = true;
-
-    await runUpdateBulletinJobIfNeeded();
-
-    expect(bootstrapCalls).toBe(1);
-    expect(wakeCalls).toBe(1);
-    expect(deleteCalls).toBe(0);
-    expect(deletedIds).toEqual([]);
-  });
-
-  test("wake invoked but no tool calls AND file unchanged — checkpoint UNCHANGED (retry next startup)", async () => {
-    const content = "## Release R\n\nSilent no-op scenario.\n";
+  test("runBackgroundJob returns ok=false — checkpoint UNCHANGED so next startup retries", async () => {
+    const content = "## Release Q\n\nFailure scenario.\n";
     writeFileSync(workspacePath, content, "utf-8");
-    wakeInvoked = true;
-    wakeProducedToolCalls = false;
+    runBackgroundJobOk = false;
+    runBackgroundJobErrorKind = "exception";
+    runBackgroundJobErrorMessage = "boom";
 
     await runUpdateBulletinJobIfNeeded();
 
-    expect(bootstrapCalls).toBe(1);
-    expect(wakeCalls).toBe(1);
+    expect(runBackgroundJobCalls).toBe(1);
+    // Critical: do NOT poison the checkpoint when the job fails.
     expect(store.has(HASH_CHECKPOINT_KEY)).toBe(false);
     expect(setCheckpointCallCount).toBe(0);
   });
 
-  test("wake invoked, no tool calls, but file deleted mid-wake — checkpoint becomes 'empty'", async () => {
-    const content = "## Release S\n\nAgent deleted file.\n";
+  test("runBackgroundJob ok=true + agent deletes file mid-run — stored hash becomes 'empty'", async () => {
+    const content = "## Release X\n\nStuff to process.\n";
     writeFileSync(workspacePath, content, "utf-8");
-    wakeInvoked = true;
-    wakeProducedToolCalls = false;
-    wakeSideEffect = () => {
+    runBackgroundJobSideEffect = () => {
       rmSync(workspacePath);
     };
 
     await runUpdateBulletinJobIfNeeded();
 
-    expect(bootstrapCalls).toBe(1);
-    expect(wakeCalls).toBe(1);
+    expect(runBackgroundJobCalls).toBe(1);
     expect(existsSync(workspacePath)).toBe(false);
     expect(store.get(HASH_CHECKPOINT_KEY)).toBe(EMPTY_HASH);
   });
 
-  test("wake invoked + produced tool calls + file unchanged — checkpoint = hash of content (agent decided this is the right state)", async () => {
-    const content = "## Release T\n\nAgent processed, chose to leave file.\n";
-    writeFileSync(workspacePath, content, "utf-8");
-    wakeInvoked = true;
-    wakeProducedToolCalls = true;
-
-    await runUpdateBulletinJobIfNeeded();
-
-    expect(bootstrapCalls).toBe(1);
-    expect(wakeCalls).toBe(1);
-    expect(store.get(HASH_CHECKPOINT_KEY)).toBe(sha256(content.trim()));
-  });
-
-  test("file present, stored hash differs — wake invoked; stored hash updates", async () => {
+  test("file present, stored hash differs — job invoked; stored hash updates", async () => {
     const oldContent = "## Old";
     const newContent = "## New content v2";
     writeFileSync(workspacePath, newContent, "utf-8");
     store.set(HASH_CHECKPOINT_KEY, sha256(oldContent));
-    wakeProducedToolCalls = true;
 
     await runUpdateBulletinJobIfNeeded();
 
-    expect(bootstrapCalls).toBe(1);
-    expect(wakeCalls).toBe(1);
+    expect(runBackgroundJobCalls).toBe(1);
     expect(store.get(HASH_CHECKPOINT_KEY)).toBe(sha256(newContent.trim()));
     expect(store.get(HASH_CHECKPOINT_KEY)).not.toBe(sha256(oldContent));
   });
 
-  test("agent deletes file mid-wake (producedToolCalls=true) — stored hash becomes 'empty'", async () => {
-    const content = "## Release X\n\nStuff to process.\n";
-    writeFileSync(workspacePath, content, "utf-8");
-    wakeProducedToolCalls = true;
-    wakeSideEffect = () => {
-      rmSync(workspacePath);
-    };
-
-    await runUpdateBulletinJobIfNeeded();
-
-    expect(bootstrapCalls).toBe(1);
-    expect(wakeCalls).toBe(1);
-    expect(existsSync(workspacePath)).toBe(false);
-    expect(store.get(HASH_CHECKPOINT_KEY)).toBe(EMPTY_HASH);
-  });
-
-  test("file present but readFileSync throws — checkpoint UNCHANGED; warn logged (gap 3)", async () => {
+  test("file present but readFileSync throws — checkpoint UNCHANGED; warn logged", async () => {
     const content = "## Release U\n\nSimulated read failure.\n";
     writeFileSync(workspacePath, content, "utf-8");
 
@@ -366,22 +271,20 @@ describe("runUpdateBulletinJobIfNeeded", () => {
       readFileSyncOverride = null;
     }
 
-    expect(bootstrapCalls).toBe(0);
-    expect(wakeCalls).toBe(0);
+    expect(runBackgroundJobCalls).toBe(0);
     expect(store.has(HASH_CHECKPOINT_KEY)).toBe(false);
     expect(setCheckpointCallCount).toBe(0);
   });
 
-  test("wake throws — function does not reject; warning logged", async () => {
+  test("runBackgroundJob throws — function does not reject; warning logged", async () => {
     const content = "## Release Z";
     writeFileSync(workspacePath, content, "utf-8");
-    wakeShouldThrow = true;
+    runBackgroundJobShouldThrow = true;
 
     // Must not throw.
     await expect(runUpdateBulletinJobIfNeeded()).resolves.toBeUndefined();
 
-    expect(bootstrapCalls).toBe(1);
-    expect(wakeCalls).toBe(1);
+    expect(runBackgroundJobCalls).toBe(1);
     // Hash was never updated because the try/catch returned before the
     // self-healing step.
     expect(store.has(HASH_CHECKPOINT_KEY)).toBe(false);

package/src/__tests__/usage-cli.test.ts

@@ -1,3 +1,14 @@
+/**
+ * CLI plumbing tests for `assistant usage` (cli/commands/usage.ts).
+ *
+ * The `usage breakdown` subcommand is daemon-mediated via `cliIpcCall`; only
+ * argument validation runs in the CLI process. Table formatting and
+ * aggregation behavior are covered daemon-side in `usage-routes.test.ts`.
+ *
+ * Follow-up opportunity: mock `../ipc/cli-client.js` and assert CLI plumbing
+ * (table formatting, --json output shape) against canned IPC responses.
+ */
+
 import { beforeEach, describe, expect, mock, test } from "bun:test";
 
 import { Command } from "commander";
@@ -19,13 +30,8 @@ mock.module("../util/logger.js", () => ({
   }),
 }));
 
-const { initializeDb } = await import("../memory/db-init.js");
-const { getDb } = await import("../memory/db-connection.js");
-const { recordUsageEvent } = await import("../memory/llm-usage-store.js");
 const { registerUsageCommand } = await import("../cli/commands/usage.js");
 
-initializeDb();
-
 async function runCommand(args: string[]): Promise<{
   exitCode: number;
   output: string;
@@ -54,77 +60,9 @@ async function runCommand(args: string[]): Promise<{
   return { exitCode, output: logLines.join("\n") };
 }
 
-function insertUsage(
-  overrides: Partial<Parameters<typeof recordUsageEvent>[0]>,
-  estimatedCostUsd = 0.01,
-): void {
-  recordUsageEvent(
-    {
-      conversationId: null,
-      runId: null,
-      requestId: null,
-      actor: "main_agent",
-      provider: "anthropic",
-      model: "claude-sonnet-4-20250514",
-      inputTokens: 100,
-      outputTokens: 50,
-      cacheCreationInputTokens: 0,
-      cacheReadInputTokens: 0,
-      ...overrides,
-    },
-    { estimatedCostUsd, pricingStatus: "priced" },
-  );
-}
-
 describe("assistant usage CLI", () => {
   beforeEach(() => {
     logLines.length = 0;
-    getDb().run("DELETE FROM llm_usage_events");
-  });
-
-  test("breakdown JSON includes call-site display labels and groupKey", async () => {
-    insertUsage({ callSite: "mainAgent" });
-    insertUsage({ callSite: null, inputTokens: 200 }, 0.005);
-
-    const result = await runCommand([
-      "usage",
-      "breakdown",
-      "--range",
-      "all",
-      "--group-by",
-      "call_site",
-      "--json",
-    ]);
-
-    expect(result.exitCode).toBe(0);
-    const parsed = JSON.parse(result.output) as {
-      breakdown: Array<{ group: string; groupKey: string | null }>;
-    };
-    expect(parsed.breakdown.map((row) => row.group)).toEqual([
-      "Main Agent",
-      "Unknown Task",
-    ]);
-    expect(parsed.breakdown.map((row) => row.groupKey)).toEqual([
-      "mainAgent",
-      null,
-    ]);
-  });
-
-  test("breakdown table prints friendly profile fallback labels", async () => {
-    insertUsage({ inferenceProfile: null });
-
-    const result = await runCommand([
-      "usage",
-      "breakdown",
-      "--range",
-      "all",
-      "--group-by",
-      "inference_profile",
-    ]);
-
-    expect(result.exitCode).toBe(0);
-    expect(result.output).toContain("PROFILE");
-    expect(result.output).toContain("Default / Unset");
   });
 
   test("rejects invalid breakdown dimensions", async () => {

package/src/__tests__/user-plugin-loader.test.ts

@@ -230,4 +230,149 @@ registerPlugin({
     await loadUserPlugins();
     expect(getRegisteredPlugins()).toHaveLength(0);
   });
+
+  describe("experimental plugin framework branch", () => {
+    /**
+     * Write a directory-convention plugin (package.json + optional
+     * hooks/tools default exports). Mirrors `writePlugin()` above but
+     * targets the new experimental loader path.
+     */
+    function writeExperimentalPlugin(
+      name: string,
+      pkg: Record<string, unknown>,
+      files: Record<string, string> = {},
+    ): void {
+      const pluginDir = join(PLUGINS_DIR, name);
+      mkdirSync(pluginDir, { recursive: true });
+      writeFileSync(
+        join(pluginDir, "package.json"),
+        JSON.stringify(pkg, null, 2),
+      );
+      for (const [rel, body] of Object.entries(files)) {
+        const parts = rel.split("/");
+        parts.pop();
+        if (parts.length > 0) {
+          mkdirSync(join(pluginDir, ...parts), { recursive: true });
+        }
+        writeFileSync(join(pluginDir, rel), body);
+      }
+    }
+
+    test("loads a plugin via the package.json branch and registers it", async () => {
+      writeExperimentalPlugin(
+        "experimental-one",
+        { name: "experimental-one", version: "0.1.0" },
+        {
+          "hooks/init.ts":
+            "export default async function init(_ctx: unknown): Promise<void> {}\n",
+        },
+      );
+
+      await loadUserPlugins();
+
+      const names = getRegisteredPlugins().map((p) => p.manifest.name);
+      expect(names).toContain("experimental-one");
+      const registered = getRegisteredPlugins().find(
+        (p) => p.manifest.name === "experimental-one",
+      );
+      expect(typeof registered?.hooks?.init).toBe("function");
+    });
+
+    test("strips npm scope from package.json name", async () => {
+      writeExperimentalPlugin("scoped", {
+        name: "@vellumai/cool-plugin",
+        version: "0.1.0",
+      });
+
+      await loadUserPlugins();
+
+      const names = getRegisteredPlugins().map((p) => p.manifest.name);
+      expect(names).toContain("cool-plugin");
+    });
+
+    test("a broken experimental plugin is logged and skipped without affecting others", async () => {
+      // Plugin A has a malformed package.json; Plugin B is a healthy
+      // legacy register.ts. The loader must isolate A's failure and still
+      // register B — same per-plugin contract as the legacy path.
+      const brokenDir = join(PLUGINS_DIR, "broken-experimental");
+      mkdirSync(brokenDir, { recursive: true });
+      writeFileSync(join(brokenDir, "package.json"), "{ not valid json");
+
+      writePlugin(
+        "healthy-legacy",
+        `
+registerPlugin({
+  manifest: {
+    name: "healthy-legacy",
+    version: "0.0.1",
+    requires: { pluginRuntime: "v1" },
+  },
+});
+`,
+      );
+
+      await loadUserPlugins();
+
+      const names = getRegisteredPlugins().map((p) => p.manifest.name);
+      expect(names).toContain("healthy-legacy");
+      expect(names).not.toContain("broken-experimental");
+    });
+
+    test("experimental and legacy plugins coexist in one workspace", async () => {
+      writeExperimentalPlugin("new-style", {
+        name: "new-style",
+        version: "0.1.0",
+      });
+      writePlugin(
+        "old-style",
+        `
+registerPlugin({
+  manifest: {
+    name: "old-style",
+    version: "0.0.1",
+    requires: { pluginRuntime: "v1" },
+  },
+});
+`,
+      );
+
+      await loadUserPlugins();
+
+      const names = getRegisteredPlugins()
+        .map((p) => p.manifest.name)
+        .sort();
+      expect(names).toEqual(["new-style", "old-style"]);
+    });
+
+    test("package.json branch wins over a stale register.ts in the same dir", async () => {
+      // A migrated plugin may keep its old register.ts on disk while it
+      // adopts the new convention. The package.json gate takes the
+      // experimental path and the legacy register.ts is never imported,
+      // so the plugin must register exactly once.
+      const dir = join(PLUGINS_DIR, "migrated");
+      mkdirSync(dir, { recursive: true });
+      writeFileSync(
+        join(dir, "package.json"),
+        JSON.stringify({ name: "migrated", version: "0.1.0" }),
+      );
+      // A register.ts that would double-register if both paths fired.
+      const registryPath = join(
+        import.meta.dir,
+        "..",
+        "plugins",
+        "registry.ts",
+      );
+      writeFileSync(
+        join(dir, "register.ts"),
+        `import { registerPlugin } from ${JSON.stringify(registryPath)};
+registerPlugin({ manifest: { name: "migrated", version: "0.0.1", requires: { pluginRuntime: "v1" } } });
+`,
+      );
+
+      await loadUserPlugins();
+
+      const names = getRegisteredPlugins().map((p) => p.manifest.name);
+      expect(names.filter((n) => n === "migrated")).toHaveLength(1);
+    });
+  });
 });