@vellumai/assistant 0.12.2-dev.202609212114.08dacde → 0.12.2-dev.202609212314.ad5e307

package/README.md

@@ -70,16 +70,16 @@ bun run src/index.ts                # interactive CLI session
 
 ### CLI commands
 
-| Command                                            | Description                                      |
-| -------------------------------------------------- | ------------------------------------------------ |
-| `vellum wake`                                      | Start assistant + gateway from current checkout  |
-| `vellum sleep`                                     | Stop assistant + gateway processes               |
-| `vellum ps`                                        | List assistants and per-assistant process status |
-| `assistant`                                        | Launch interactive CLI session                   |
+| Command                                                    | Description                                      |
+| ---------------------------------------------------------- | ------------------------------------------------ |
+| `vellum wake`                                              | Start assistant + gateway from current checkout  |
+| `vellum sleep`                                             | Stop assistant + gateway processes               |
+| `vellum ps`                                                | List assistants and per-assistant process status |
+| `assistant`                                                | Launch interactive CLI session                   |
 | `assistant conversations list\|search\|new\|export\|clear` | Manage conversations                             |
-| `assistant config set\|get\|list`                  | Manage configuration                             |
-| `assistant keys set\|list\|delete`                 | Manage API keys in secure storage                |
-| `assistant trust list\|add\|update\|remove`        | Manage trust rules                               |
+| `assistant config set\|get\|list`                          | Manage configuration                             |
+| `assistant keys set\|list\|delete`                         | Manage API keys in secure storage                |
+| `assistant trust list\|add\|update\|remove`                | Manage trust rules                               |
 
 ## Project Structure
 
@@ -183,7 +183,7 @@ Internal forwarding routes (`/v1/internal/twilio/*`) are unaffected — these ac
 The `/channels/inbound` endpoint requires a JWT with the `svc_gateway` principal type and `ingress.write` scope to prove the request originated from the gateway. This ensures channel messages can only arrive via the gateway (which performs webhook-level verification) and not via direct HTTP calls that bypass signature checks.
 
 - **JWT-based enforcement:** The route policy in `route-policy.ts` restricts `/channels/inbound` to the `svc_gateway` principal type with `ingress.write` scope. Actor and local principals are rejected with 403.
-- **Auth bypass:** When `DISABLE_HTTP_AUTH=true` is set (platform-managed deployments), JWT verification is skipped and a synthetic context is used.
+- **Auth bypass:** When `DISABLE_HTTP_AUTH=true` is set (platform-managed deployments), a request that supplies no `Authorization` header gets a synthetic context. A request that supplies one is verified normally, and a token that fails verification is rejected.
 
 ## Twilio Setup Primitive
 
@@ -244,8 +244,8 @@ The channel guardian service generates verification challenge instructions with
 ### Operator Notes
 
 - **Verification input format:** Channel verification accepts a bare code reply only (6-digit numeric for identity-bound sessions; 64-char hex for unbound inbound/bootstrap compatibility).
-- **Rebind requirement:** Creating a new guardian challenge when a binding already exists requires `rebind: true` in the HTTP request. Without it, the assistant returns `already_bound`. This prevents accidental guardian replacement.
-- **Takeover prevention:** Verification is rejected when an active binding exists for a different external user. Same-user re-verification is allowed.
+- **Rebind requirement:** Creating a new guardian challenge when a binding already exists requires `rebind: true` in the HTTP request. Without it, the assistant returns `already_bound`. On text channels the resulting code can only be redeemed by the account already bound, which is how the same guardian verifies again; to move the guardian to a different account, revoke the binding first and verify again. An outbound phone verification is the exception: its code replaces the bound number.
+- **Takeover prevention:** On text channels, verification is rejected when an active binding exists for a different external user: the code is spent, the reply is the generic "invalid or expired", and the sender is made neither guardian nor contact. Same-user re-verification is allowed, including for a guardian who revoked their binding and is verifying the same account again. Phone differs: an outbound verification with `rebind: true` replaces the bound number once its code is entered, and an inbound call from a different number is not bound.
 
 ### Vellum Guardian Identity (Actor Tokens)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.12.2-dev.202609212114.08dacde",
+  "version": "0.12.2-dev.202609212314.ad5e307",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/approval-routes-http.test.ts

@@ -241,8 +241,10 @@ function makeConfirmationEmittingSession(opts?: {
 // Tests
 // ---------------------------------------------------------------------------
 
-const TEST_TOKEN = "test-bearer-token-approvals";
-const AUTH_HEADERS = { Authorization: `Bearer ${TEST_TOKEN}` };
+// This suite mocks isHttpAuthDisabled() to true, so a request carrying no
+// bearer authenticates through the dev bypass. A bearer that is present is
+// verified against the signing key, which these tests do not set up.
+const AUTH_HEADERS: Record<string, string> = {};
 
 describe("standalone approval endpoints — HTTP layer", () => {
   let server: RuntimeHttpServer;

package/src/__tests__/call-routes-http.test.ts

@@ -82,8 +82,10 @@ await initializeDb();
 // Helpers
 // ---------------------------------------------------------------------------
 
-const TEST_TOKEN = "test-bearer-token-calls";
-const AUTH_HEADERS = { Authorization: `Bearer ${TEST_TOKEN}` };
+// This suite mocks isHttpAuthDisabled() to true, so a request carrying no
+// bearer authenticates through the dev bypass. A bearer that is present is
+// verified against the signing key, which these tests do not set up.
+const AUTH_HEADERS: Record<string, string> = {};
 
 let ensuredConvIds = new Set<string>();
 

package/src/__tests__/runtime-attachment-metadata.test.ts

@@ -55,8 +55,10 @@ afterAll(() => {
   resetDbForTesting();
 });
 
-const TEST_TOKEN = "test-bearer-token-attach";
-const AUTH_HEADERS = { Authorization: `Bearer ${TEST_TOKEN}` };
+// This suite mocks isHttpAuthDisabled() to true, so a request carrying no
+// bearer authenticates through the dev bypass. A bearer that is present is
+// verified against the signing key, which these tests do not set up.
+const AUTH_HEADERS: Record<string, string> = {};
 
 describe("Runtime attachment metadata", () => {
   let server: RuntimeHttpServer;

package/src/__tests__/send-endpoint-busy.test.ts

@@ -302,8 +302,10 @@ function makePendingApprovalConversation(
 // Tests
 // ---------------------------------------------------------------------------
 
-const TEST_TOKEN = "test-bearer-token-send";
-const AUTH_HEADERS = { Authorization: `Bearer ${TEST_TOKEN}` };
+// This suite mocks isHttpAuthDisabled() to true, so a request carrying no
+// bearer authenticates through the dev bypass. A bearer that is present is
+// verified against the signing key, which these tests do not set up.
+const AUTH_HEADERS: Record<string, string> = {};
 
 describe("POST /v1/messages — queue-if-busy and hub publishing", () => {
   let server: RuntimeHttpServer;

package/src/cli/commands/channel-verification-sessions.help.ts

@@ -44,7 +44,11 @@ Examples:
           description:
             "Destination address for outbound verification (handle, phone number, user ID, or email address)",
         },
-        { flags: "--rebind", description: "Replace existing guardian binding" },
+        {
+          flags: "--rebind",
+          description:
+            "Create a code although the channel already has a guardian (see below)",
+        },
         {
           flags: "--conversation-id <conversationId>",
           description: "Conversation ID for inbound challenges",
@@ -74,7 +78,13 @@ Routes between three creation modes based on the provided options:
   2. Outbound: --channel <ch> --destination <dest>
      Sends a verification code to the given destination. Supports telegram
      (handle or chat ID), phone (E.164 number), slack and discord (user ID),
-     and email. Use --rebind to replace an existing guardian binding.
+     and email.
+
+--rebind creates a code although the channel already has a guardian. On
+telegram, slack, discord and email, only the account already bound can redeem
+that code, which is how the same guardian verifies again. A code never moves
+the guardian to a different account there: run "revoke" first, then create
+without --rebind. On phone, an outbound code replaces the bound number.
 
   3. Inbound: --channel <ch> (no --destination)
      Generates a challenge secret for the guardian to send back on the

package/src/cli/lib/bundled-marketplace.json

@@ -176,16 +176,16 @@
       "icon": "\ud83d\udcbb"
     },
     {
-      "name": "ecommerce-wismo-supporter",
+      "name": "ecommerce-order-supporter",
       "description": "Resolves ecommerce Where-Is-My-Order (WISMO) support inquiries, cross-checks real-time carrier tracking milestones, flags delivery exceptions, and stages customer update drafts without helpdesk seat taxes.",
       "category": "commerce",
       "icon": "📦",
       "license": "MIT",
-      "homepage": "https://github.com/ZeebBoyBlue/ecommerce-wismo-supporter",
+      "homepage": "https://github.com/ZeebBoyBlue/ecommerce-order-supporter",
       "source": {
         "source": "github",
-        "repo": "ZeebBoyBlue/ecommerce-wismo-supporter",
-        "ref": "9218c23d325c749500d59b6ae651f38264a43cd1"
+        "repo": "ZeebBoyBlue/ecommerce-order-supporter",
+        "ref": "35e2165a14447a897aee750a198c3f166458226b"
       }
     },
     {

package/src/daemon/handlers/config-channels.ts

@@ -156,7 +156,9 @@ export async function createInboundChallenge(
       success: false,
       error: "already_bound",
       message:
-        "A guardian is already bound for this channel. Revoke the existing binding first, or set rebind: true to replace.",
+        resolvedChannel === "phone"
+          ? "A guardian is already bound for this channel. On phone, verify through an outbound call with rebind: true. To a new number, it replaces the bound number once the code is entered. To the bound number, it confirms that number again and leaves the binding as it is. An inbound challenge cannot be completed by phone: a call collects a six-digit code, which an inbound challenge does not issue."
+          : "A guardian is already bound for this channel. To verify a different account, revoke the existing binding first. Set rebind: true only to verify the same account again.",
       channel: resolvedChannel,
     };
   }

package/src/persistence/embeddings/__tests__/embedding-local-lifecycle.test.ts

@@ -27,9 +27,14 @@ import { LocalEmbeddingBackend } from "../embedding-local.js";
 type Internals = any;
 
 /**
- * A stand-in for a Bun subprocess whose stdin pipe is broken. `write` throws
- * EPIPE the way a real worker's pipe does once the child is gone.
+ * A backend of its own for one test. Production gets the per-model instance
+ * from `forModel`; constructing directly keeps tests from sharing state.
  */
+function newBackend(): Internals {
+  return new (LocalEmbeddingBackend as Internals)("test-model");
+}
+
+/** A stand-in for a Bun subprocess whose stdin `write` fails synchronously. */
 function brokenPipeProc(pid = 4242) {
   return {
     pid,
@@ -196,7 +201,7 @@ describe("PID file ownership", () => {
    */
   test("releasePidFile leaves an entry that names someone else's worker", () => {
     writeFileSync(pidPath, "777");
-    const backend = new LocalEmbeddingBackend("test-model") as Internals;
+    const backend = newBackend();
 
     backend.releasePidFile(888);
 
@@ -206,7 +211,7 @@ describe("PID file ownership", () => {
 
   test("releasePidFile drops the entry when it names our worker", () => {
     writeFileSync(pidPath, "777");
-    const backend = new LocalEmbeddingBackend("test-model") as Internals;
+    const backend = newBackend();
 
     backend.releasePidFile(777);
 
@@ -219,7 +224,7 @@ describe("PID file ownership", () => {
    */
   test("disposing an instance with no worker keeps another's PID entry", () => {
     writeFileSync(pidPath, "777");
-    const backend = new LocalEmbeddingBackend("test-model") as Internals;
+    const backend = newBackend();
     backend.disposeRequested = true;
     backend.workerProc = null;
 
@@ -232,12 +237,12 @@ describe("PID file ownership", () => {
 
 describe("broken worker pipe", () => {
   /**
-   * A write to a dead worker raises EPIPE. Escaping, it reached the daemon's
-   * `unhandledRejection` handler and terminated the process; it must instead
-   * come back as an ordinary failed embed the backend chain can fall back from.
+   * A broken pipe comes back as an ordinary failed embed the backend chain can
+   * fall back from. An escaping rejection reaches the daemon's
+   * `unhandledRejection` handler, which shuts the process down.
    */
   test("EPIPE on write resolves the request as an error", async () => {
-    const backend = new LocalEmbeddingBackend("test-model") as Internals;
+    const backend = newBackend();
     backend.workerProc = brokenPipeProc();
 
     const response = await backend.sendRequest(["hello"]);
@@ -247,7 +252,7 @@ describe("broken worker pipe", () => {
   });
 
   test("EPIPE surfaces to embed() as a rejection, not a process crash", async () => {
-    const backend = new LocalEmbeddingBackend("test-model") as Internals;
+    const backend = newBackend();
     backend.workerProc = brokenPipeProc();
     // Skip initialization: the worker is already (notionally) running.
     backend.ensureInitialized = async () => {};
@@ -257,8 +262,34 @@ describe("broken worker pipe", () => {
     );
   });
 
+  /**
+   * A real pipe, because the failure lives in Bun's behaviour rather than in
+   * ours: a batch larger than the pipe buffer, sent to a worker too busy to
+   * drain stdin, leaves the write pending, and the pending write rejects when
+   * the worker dies. A synchronous guard never sees that rejection.
+   */
+  test("a write still pending when the worker dies resolves the request as an error", async () => {
+    const backend = newBackend();
+    const proc = Bun.spawn({
+      cmd: [process.execPath, "-e", "setTimeout(() => {}, 60_000)"],
+      windowsHide: true,
+      stdin: "pipe",
+      stdout: "ignore",
+      stderr: "ignore",
+    });
+    spawned.push(proc);
+    backend.workerProc = proc;
+
+    const request = backend.sendRequest(["x".repeat(4 * 1024 * 1024)]);
+    proc.kill("SIGKILL");
+    const response = await request;
+
+    expect(response.error).toContain("worker pipe write failed");
+    expect(backend.pendingRequests.size).toBe(0);
+  });
+
   test("a failed write does not leak the pending request", async () => {
-    const backend = new LocalEmbeddingBackend("test-model") as Internals;
+    const backend = newBackend();
     backend.workerProc = brokenPipeProc();
 
     await backend.sendRequest(["hello"]);
@@ -274,7 +305,7 @@ describe("releasing ownership of a worker", () => {
    * strands it: no handle, no PID entry, invisible to every later reclaim.
    */
   test("stdout ending kills the child before clearing workerProc", async () => {
-    const backend = new LocalEmbeddingBackend("test-model") as Internals;
+    const backend = newBackend();
     const proc = liveProc();
     backend.workerProc = proc;
 
@@ -285,7 +316,7 @@ describe("releasing ownership of a worker", () => {
   });
 
   test("shutdown reaps the worker and resolves only once it exits", async () => {
-    const backend = new LocalEmbeddingBackend("test-model") as Internals;
+    const backend = newBackend();
     const proc = liveProc(555);
     backend.workerProc = proc;
     writeFileSync(getEmbedWorkerPidPath(), "555");
@@ -298,7 +329,7 @@ describe("releasing ownership of a worker", () => {
   });
 
   test("shutdown settles in-flight requests instead of hanging them", async () => {
-    const backend = new LocalEmbeddingBackend("test-model") as Internals;
+    const backend = newBackend();
     backend.workerProc = liveProc(556);
 
     const inFlight = backend.sendRequest(["hello"]);
@@ -315,7 +346,7 @@ describe("releasing ownership of a worker", () => {
    * pending requests are only settled after the wait.
    */
   test("a worker that ignores SIGTERM is escalated to SIGKILL, not waited on forever", async () => {
-    const backend = new LocalEmbeddingBackend("test-model") as Internals;
+    const backend = newBackend();
     backend.terminateGraceMs = 50;
     const signals: (string | undefined)[] = [];
     const wedged = {
@@ -354,7 +385,7 @@ describe("termination that cannot be confirmed", () => {
   }
 
   test("keeps the PID publication instead of unpublishing a possibly-live child", async () => {
-    const backend = new LocalEmbeddingBackend("test-model") as Internals;
+    const backend = newBackend();
     backend.terminateGraceMs = 20;
     const proc = wedgedProc();
     backend.workerProc = proc;
@@ -370,7 +401,7 @@ describe("termination that cannot be confirmed", () => {
   });
 
   test("refuses to start a replacement while the child may still be alive", async () => {
-    const backend = new LocalEmbeddingBackend("test-model") as Internals;
+    const backend = newBackend();
     // No workerPath recorded, so liveness falls back to a PID probe. Our own
     // PID is certainly alive, standing in for a child that will not die.
     backend.unconfirmedWorker = process.pid;
@@ -381,7 +412,7 @@ describe("termination that cannot be confirmed", () => {
   });
 
   test("surfaces the incomplete teardown through embed() rather than failing silently", async () => {
-    const backend = new LocalEmbeddingBackend("test-model") as Internals;
+    const backend = newBackend();
     backend.unconfirmedWorker = process.pid;
 
     await expect(backend.embed(["hello"])).rejects.toThrow(
@@ -401,7 +432,7 @@ describe("termination that cannot be confirmed", () => {
     });
     await Bun.sleep(400);
 
-    const backend = new LocalEmbeddingBackend("test-model") as Internals;
+    const backend = newBackend();
     backend.workerPath = scriptPath;
     backend.unconfirmedWorker = proc.pid;
     writeFileSync(getEmbedWorkerPidPath(), String(proc.pid));
@@ -440,7 +471,7 @@ describe("reclaiming before spawning a replacement", () => {
     await Bun.sleep(400);
     writeFileSync(getEmbedWorkerPidPath(), String(proc.pid));
 
-    const backend = new LocalEmbeddingBackend("test-model") as Internals;
+    const backend = newBackend();
     await backend.reclaimOwnedWorkers(scriptPath);
 
     // Confirmed gone by the time reclaim returns, not merely signalled.
@@ -464,7 +495,7 @@ describe("reclaiming before spawning a replacement", () => {
     spawned.push(proc);
     await Bun.sleep(400);
 
-    const backend = new LocalEmbeddingBackend("test-model") as Internals;
+    const backend = newBackend();
     backend.terminateGraceMs = 300;
     await backend.reclaimOwnedWorkers(scriptPath);
 
@@ -497,7 +528,7 @@ setTimeout(() => {}, 60_000);\n`,
     expect(workers.length).toBe(1);
     expect(workers[0].ppid).toBe(parent.pid);
 
-    const backend = new LocalEmbeddingBackend("test-model") as Internals;
+    const backend = newBackend();
     backend.terminateGraceMs = 300;
     await backend.reclaimOwnedWorkers(scriptPath);
 
@@ -521,7 +552,7 @@ describe("shutdown versus in-flight initialization", () => {
    * lets the initializer spawn a worker afterwards, with nobody left to reap it.
    */
   test("shutdown waits for an in-flight init and reaps the worker it creates", async () => {
-    const backend = new LocalEmbeddingBackend("test-model") as Internals;
+    const backend = newBackend();
     const proc = liveProc(600);
 
     let finishInit: () => void = () => {};
@@ -564,7 +595,7 @@ describe("parent exit orderings", () => {
    * process's and left it alone. So it kills its own child on the way out.
    */
   test("terminateNow kills the worker and releases the entry without waiting", () => {
-    const backend = new LocalEmbeddingBackend("test-model") as Internals;
+    const backend = newBackend();
     const signals: string[] = [];
     const proc = {
       pid: 909,
@@ -590,7 +621,7 @@ describe("parent exit orderings", () => {
    * process while the child was still being adopted.
    */
   test("shutdown does not inherit the model-load wait when init never settles", async () => {
-    const backend = new LocalEmbeddingBackend("test-model") as Internals;
+    const backend = newBackend();
     backend.terminateGraceMs = 50;
     // An initialization that never resolves, as during a cold model load.
     backend.initInFlight = new Promise<void>(() => {});
@@ -602,7 +633,7 @@ describe("parent exit orderings", () => {
   });
 
   test("a backend already shutting down refuses to spawn a replacement", async () => {
-    const backend = new LocalEmbeddingBackend("test-model") as Internals;
+    const backend = newBackend();
     backend.disposeRequested = true;
 
     await expect(backend.embed(["hello"])).rejects.toThrow(/shutting down/);
@@ -621,7 +652,7 @@ describe("transient failures stay transient", () => {
   const PERMANENT_FAILURE_SENTINEL = "Local embedding backend unavailable";
 
   test("an unconfirmed termination does not claim permanent unavailability", async () => {
-    const backend = new LocalEmbeddingBackend("test-model") as Internals;
+    const backend = newBackend();
     backend.unconfirmedWorker = process.pid;
 
     const err = await backend.ensureInitialized().catch((e: Error) => e);
@@ -631,7 +662,7 @@ describe("transient failures stay transient", () => {
   });
 
   test("shutting down does not claim permanent unavailability", async () => {
-    const backend = new LocalEmbeddingBackend("test-model") as Internals;
+    const backend = newBackend();
     backend.disposeRequested = true;
 
     const err = await backend.embed(["hello"]).catch((e: Error) => e);
@@ -652,7 +683,7 @@ describe("audit regressions", () => {
    * embed queued behind it.
    */
   test("a startup failure against a wedged worker does not hang", async () => {
-    const backend = new LocalEmbeddingBackend("test-model") as Internals;
+    const backend = newBackend();
     backend.terminateGraceMs = 30;
     const signals: (string | undefined)[] = [];
     backend.workerProc = {
@@ -680,7 +711,7 @@ describe("audit regressions", () => {
    * startup for the full two-minute timeout.
    */
   test("terminateNow clears the stdout buffer so a retry can parse ready", () => {
-    const backend = new LocalEmbeddingBackend("test-model") as Internals;
+    const backend = newBackend();
     backend.stdoutBuffer = '{"id":5,"vect';
     backend.workerProc = null;
 
@@ -707,7 +738,7 @@ describe("audit regressions", () => {
     spawned.push(proc);
     await Bun.sleep(400);
 
-    const backend = new LocalEmbeddingBackend("test-model") as Internals;
+    const backend = newBackend();
     backend.workerPath = scriptPath;
     backend.workerProc = null; // spawned, never adopted
 
@@ -722,7 +753,7 @@ describe("audit regressions", () => {
    * contract, so it must leave the instance able to start a replacement.
    */
   test("terminateNow leaves the instance reusable", () => {
-    const backend = new LocalEmbeddingBackend("test-model") as Internals;
+    const backend = newBackend();
     backend.workerProc = null;
     backend.stdoutReaderActive = true;
 
@@ -766,3 +797,97 @@ test("orphan reclaim outlasts the embedding reap it must not truncate", () => {
     EMBEDDING_SHUTDOWN_BUDGET_MS + 1_000,
   );
 });
+
+describe("one backend per model", () => {
+  test("forModel hands out one instance per model", () => {
+    const first = LocalEmbeddingBackend.forModel("per-model-a");
+
+    expect(LocalEmbeddingBackend.forModel("per-model-a")).toBe(first);
+    expect(LocalEmbeddingBackend.forModel("per-model-b")).not.toBe(first);
+  });
+
+  /**
+   * A backend-cache reset disposes the backend it evicts, and that disposal
+   * waits for in-flight embeds. The next embed needs the model again inside
+   * that window, and the embeds in flight keep their worker.
+   */
+  test("needing the model again while a disposal is pending keeps the busy worker", () => {
+    const backend = LocalEmbeddingBackend.forModel(
+      "per-model-reopen",
+    ) as Internals;
+    const proc = liveProc(7101);
+    backend.workerProc = proc;
+    backend.activeEmbeds = 1;
+    backend.dispose();
+
+    const again = LocalEmbeddingBackend.forModel(
+      "per-model-reopen",
+    ) as Internals;
+    backend.activeEmbeds = 0;
+    backend.disposeIfIdle();
+
+    expect(again).toBe(backend);
+    expect(again.workerProc).toBe(proc);
+    expect(proc.killed).toBe(false);
+  });
+
+  test("a pending disposal nobody withdraws still releases the worker once idle", () => {
+    const backend = LocalEmbeddingBackend.forModel(
+      "per-model-dispose",
+    ) as Internals;
+    const proc = liveProc(7102);
+    backend.workerProc = proc;
+    backend.activeEmbeds = 1;
+    backend.dispose();
+
+    backend.activeEmbeds = 0;
+    backend.disposeIfIdle();
+
+    expect(backend.workerProc).toBeNull();
+    expect(proc.killed).toBe(true);
+  });
+
+  /** The process is exiting, so nothing may spawn a worker behind the reap. */
+  test("a shut-down backend stays shut down", async () => {
+    const backend = LocalEmbeddingBackend.forModel("per-model-shutdown");
+    await backend.shutdown();
+
+    const again = LocalEmbeddingBackend.forModel("per-model-shutdown");
+
+    expect(again).toBe(backend);
+    await expect(again.embed(["hello"])).rejects.toThrow(/shutting down/);
+  });
+
+  /**
+   * The backend cache forgets a backend whose disposal is pending, so process
+   * teardown reaches it through the class's own list.
+   */
+  test("shutdownAll reaps a busy backend no cache still holds", async () => {
+    const backend = LocalEmbeddingBackend.forModel(
+      "per-model-evicted",
+    ) as Internals;
+    const proc = liveProc(7103);
+    backend.workerProc = proc;
+    backend.activeEmbeds = 1;
+    backend.dispose();
+
+    await LocalEmbeddingBackend.shutdownAll();
+
+    expect(proc.killed).toBe(true);
+    expect(backend.workerProc).toBeNull();
+  });
+
+  test("terminateAllNow kills a busy backend no cache still holds", () => {
+    const backend = LocalEmbeddingBackend.forModel(
+      "per-model-evicted-now",
+    ) as Internals;
+    const proc = liveProc(7104);
+    backend.workerProc = proc;
+    backend.activeEmbeds = 1;
+    backend.dispose();
+
+    LocalEmbeddingBackend.terminateAllNow();
+
+    expect(proc.killed).toBe(true);
+  });
+});

package/src/persistence/embeddings/embedding-backend-shutdown.test.ts

@@ -0,0 +1,47 @@
+/**
+ * Process teardown reaches every local embedding worker the process owns.
+ *
+ * Kept in its own file: `shutdownEmbeddingBackends` latches the module into its
+ * shut-down state for the rest of the process.
+ */
+import { expect, test } from "bun:test";
+
+import { AssistantConfigSchema } from "../../config/schema.js";
+import {
+  clearEmbeddingBackendCache,
+  selectEmbeddingBackend,
+  shutdownEmbeddingBackends,
+} from "./embedding-backend.js";
+
+/** Reach past `private`, which is compile-time only, so tests drive real state. */
+type Internals = any;
+
+/**
+ * A backend-cache reset forgets a backend whose disposal is waiting on
+ * in-flight embeds, while that backend still holds a live worker.
+ */
+test("shutdown reaps a busy local worker the cache has already forgotten", async () => {
+  const config = AssistantConfigSchema.parse({
+    memory: { embeddings: { provider: "local" } },
+  });
+  const { backend } = await selectEmbeddingBackend(config);
+  const delegate = await (backend as Internals).getDelegate();
+  let killed = false;
+  delegate.workerProc = {
+    pid: 7201,
+    exited: new Promise<number>(() => {}),
+    kill() {
+      killed = true;
+    },
+    stdin: { write: () => 0, flush: () => 0 },
+  };
+  delegate.terminateGraceMs = 10;
+  delegate.activeEmbeds = 1;
+
+  clearEmbeddingBackendCache();
+  expect(killed).toBe(false);
+
+  await shutdownEmbeddingBackends();
+
+  expect(killed).toBe(true);
+});