@vellumai/assistant 0.12.2-dev.202609212016.fb4c53e → 0.12.2-dev.202609212215.5512e77

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
 
@@ -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.202609212016.fb4c53e",
+  "version": "0.12.2-dev.202609212215.5512e77",
   "license": "MIT",
   "type": "module",
   "exports": {

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/config/feature-flag-registry.json

@@ -170,14 +170,6 @@
       "description": "Enable Anthropic fast mode for Opus models (4.6, 4.7, 4.8), delivering up to 2.5x higher output tokens per second at premium pricing",
       "defaultEnabled": false
     },
-    {
-      "id": "teleport",
-      "scope": "client",
-      "key": "teleport",
-      "label": "Teleport",
-      "description": "Enable the local-to-platform teleport UI in General settings. Platform-to-local teleport is GA and not gated by this flag",
-      "defaultEnabled": false
-    },
     {
       "id": "apple-container",
       "scope": "client",

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);
+});

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

@@ -16,6 +16,7 @@ import {
   recordBillingSuccess,
 } from "./embedding-billing-breaker.js";
 import { GeminiEmbeddingBackend } from "./embedding-gemini.js";
+import type { LocalEmbeddingBackend } from "./embedding-local.js";
 import { OllamaEmbeddingBackend } from "./embedding-ollama.js";
 import {
   OpenAIEmbeddingBackend,
@@ -78,6 +79,13 @@ export const EMBEDDING_SHUTDOWN_BUDGET_MS = 8_000;
  * the failure is contained and other embedding backends can be used instead.
  */
 
+/**
+ * The local backend class, once {@link LazyLocalEmbeddingBackend} has loaded it.
+ * It lists every local backend this process owns, which process teardown needs
+ * and {@link backendCache} cannot supply.
+ */
+let localEmbeddingBackends: typeof LocalEmbeddingBackend | null = null;
+
 class LazyLocalEmbeddingBackend implements EmbeddingBackend {
   readonly provider = "local" as const;
   readonly model: string;
@@ -114,21 +122,9 @@ class LazyLocalEmbeddingBackend implements EmbeddingBackend {
     this.delegate?.dispose?.();
   }
 
-  terminateNow(): void {
-    this.delegate?.terminateNow?.();
-  }
-
-  async sweepOwnedWorkers(): Promise<void> {
-    await this.delegate?.sweepOwnedWorkers?.();
-  }
-
-  async shutdown(): Promise<void> {
-    // A delegate under construction still ends up owning a worker, so settle
-    // the in-flight import before tearing down rather than skipping it.
-    if (!this.delegate && this.initPromise) {
-      await this.initPromise.catch(() => undefined);
-    }
-    await this.delegate?.shutdown?.();
+  /** Settles once a delegate under construction has been handed out or failed. */
+  async loaded(): Promise<void> {
+    await this.initPromise?.catch(() => undefined);
   }
 
   resetForRetry(): void {
@@ -146,7 +142,8 @@ class LazyLocalEmbeddingBackend implements EmbeddingBackend {
         try {
           const { LocalEmbeddingBackend } =
             await import("./embedding-local.js");
-          this.delegate = new LocalEmbeddingBackend(this.model);
+          localEmbeddingBackends = LocalEmbeddingBackend;
+          this.delegate = LocalEmbeddingBackend.forModel(this.model);
           return this.delegate;
         } catch (err) {
           localBackendBroken = true;
@@ -270,7 +267,7 @@ export function clearEmbeddingBackendCache(): void {
 }
 
 /**
- * Tear down every cached backend's OS resources and empty the caches.
+ * Tear down every local embedding worker this process owns and empty the caches.
  *
  * Called on daemon shutdown so process-owned embedding workers exit with their
  * owner instead of being orphaned. `clearEmbeddingBackendCache()` is the
@@ -279,24 +276,18 @@ export function clearEmbeddingBackendCache(): void {
  */
 export async function shutdownEmbeddingBackends(): Promise<void> {
   embeddingBackendsShutDown = true;
-  const backends = new Set(backendCache.values());
+  const loading = [...backendCache.values()].filter(
+    (backend) => backend instanceof LazyLocalEmbeddingBackend,
+  );
   backendCache.clear();
   vectorCache.clear();
   vectorCacheBytes = 0;
   backendDimCache.clear();
 
-  const teardown = Promise.all(
-    [...backends].map(async (backend) => {
-      try {
-        await backend.shutdown?.();
-        await backend.sweepOwnedWorkers?.();
-      } catch (err) {
-        log.warn(
-          { err, provider: backend.provider, model: backend.model },
-          "Failed to shut down embedding backend",
-        );
-      }
-    }),
+  // A delegate under construction still ends up owning a worker, so let it
+  // join the class's list before tearing that list down.
+  const teardown = Promise.all(loading.map((backend) => backend.loaded())).then(
+    () => localEmbeddingBackends?.shutdownAll(),
   );
 
   const timedOut = Symbol("timeout");
@@ -313,7 +304,7 @@ export async function shutdownEmbeddingBackends(): Promise<void> {
 }
 
 /**
- * SIGKILL every cached backend's worker synchronously.
+ * SIGKILL every local embedding worker this process owns, synchronously.
  *
  * For a process that must exit immediately and cannot run the graceful
  * teardown: the memory worker on PID-file eviction, where staying alive to reap
@@ -322,16 +313,7 @@ export async function shutdownEmbeddingBackends(): Promise<void> {
  * sweep has passed, leaving two workers alive (JARVIS-1125).
  */
 export function terminateEmbeddingWorkersNow(): void {
-  for (const backend of new Set(backendCache.values())) {
-    try {
-      backend.terminateNow?.();
-    } catch (err) {
-      log.warn(
-        { err, provider: backend.provider, model: backend.model },
-        "Failed to terminate embedding worker",
-      );
-    }
-  }
+  localEmbeddingBackends?.terminateAllNow();
 }
 
 /** Reset the sticky local-backend failure flag without evicting live backends. */

package/src/persistence/embeddings/embedding-local.ts

@@ -7,6 +7,8 @@ import {
 } from "node:fs";
 import { join } from "node:path";
 
+import type { Subprocess } from "bun";
+
 import { getIsContainerized } from "../../config/env-registry.js";
 import { getLogger } from "../../util/logger.js";
 import {
@@ -22,6 +24,7 @@ import {
   listWorkerProcesses,
   pid1OwnsWorkers,
 } from "../../util/worker-ownership.js";
+import { writeWorkerLine } from "../../util/worker-pipe.js";
 import { EmbeddingRuntimeManager } from "./embedding-runtime-manager.js";
 import {
   type EmbeddingBackend,
@@ -106,9 +109,7 @@ export class LocalEmbeddingBackend implements EmbeddingBackend {
   readonly provider = "local" as const;
   readonly model: string;
 
-  // Subprocess — typed loosely to avoid coupling to Bun's Subprocess generics
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  private workerProc: any = null;
+  private workerProc: Subprocess<"pipe", "pipe", "pipe"> | null = null;
   private stdoutBuffer = "";
   private requestCounter = 0;
   private pendingRequests = new Map<
@@ -119,7 +120,10 @@ export class LocalEmbeddingBackend implements EmbeddingBackend {
   >();
   private stdoutReaderActive = false;
   private activeEmbeds = 0;
+  /** Release the worker once idle. {@link forModel} withdraws the request. */
   private disposeRequested = false;
+  /** Set by {@link shutdown}. The process is exiting, so nothing reopens this. */
+  private processExiting = false;
 
   private readonly initGuard = new PromiseGuard<void>();
   private initInFlight: Promise<void> | null = null;
@@ -130,7 +134,67 @@ export class LocalEmbeddingBackend implements EmbeddingBackend {
   /** Overridable so tests can exercise the escalation path without the wait. */
   private terminateGraceMs = WORKER_TERMINATE_GRACE_MS;
 
-  constructor(model: string) {
+  /**
+   * Every backend this process has handed out, one per model.
+   *
+   * {@link reclaimOwnedWorkers} terminates a same-model worker parented to this
+   * process that the instance holds no handle for. That is sound only while no
+   * other instance in this process can hold that worker, so instances come from
+   * {@link forModel} and are never constructed by callers.
+   *
+   * This is also the complete list of workers the process owns. The backend
+   * cache is not: it forgets a backend whose disposal is still pending.
+   */
+  private static readonly byModel = new Map<string, LocalEmbeddingBackend>();
+
+  /**
+   * The backend for `model`. A pending {@link dispose} is withdrawn, so embeds
+   * still running on the instance keep their worker.
+   */
+  static forModel(model: string): LocalEmbeddingBackend {
+    let backend = LocalEmbeddingBackend.byModel.get(model);
+    if (!backend) {
+      backend = new LocalEmbeddingBackend(model);
+      LocalEmbeddingBackend.byModel.set(model, backend);
+    }
+    if (!backend.processExiting) {
+      backend.disposeRequested = false;
+    }
+    return backend;
+  }
+
+  /** {@link shutdown} every backend, then reap any worker still parented here. */
+  static async shutdownAll(): Promise<void> {
+    await Promise.all(
+      [...LocalEmbeddingBackend.byModel.values()].map(async (backend) => {
+        try {
+          await backend.shutdown();
+          await backend.sweepOwnedWorkers();
+        } catch (err) {
+          log.warn(
+            { err, model: backend.model },
+            "Failed to shut down local embedding backend",
+          );
+        }
+      }),
+    );
+  }
+
+  /** {@link terminateNow} every backend. */
+  static terminateAllNow(): void {
+    for (const backend of LocalEmbeddingBackend.byModel.values()) {
+      try {
+        backend.terminateNow();
+      } catch (err) {
+        log.warn(
+          { err, model: backend.model },
+          "Failed to terminate local embedding worker",
+        );
+      }
+    }
+  }
+
+  private constructor(model: string) {
     this.model = model;
   }
 
@@ -193,19 +257,9 @@ export class LocalEmbeddingBackend implements EmbeddingBackend {
       }
       this.pendingRequests.set(id, { resolve });
 
-      // Writing to a worker that has already exited raises EPIPE. That must
-      // surface as an ordinary embed failure the caller can fall back from:
-      // an escaping EPIPE reaches the daemon's `unhandledRejection` handler,
-      // which tears down the whole process (JARVIS-1125).
-      //
-      // The guard covers `write` as well as `flush`: both are synchronous on
-      // Bun's FileSink, and `write` is the call that raises the broken pipe.
-      try {
-        proc.stdin.write(JSON.stringify({ id, texts }) + "\n");
-        proc.stdin.flush();
-      } catch (err) {
-        this.failPendingRequest(id, err);
-      }
+      writeWorkerLine(proc.stdin, JSON.stringify({ id, texts }), (err) =>
+        this.failPendingRequest(id, err),
+      );
     });
   }
 
@@ -929,6 +983,7 @@ export class LocalEmbeddingBackend implements EmbeddingBackend {
    * the OS confirms the worker is gone.
    */
   async shutdown(): Promise<void> {
+    this.processExiting = true;
     this.disposeRequested = true;
 
     // An initialization already in flight has not necessarily assigned

package/src/persistence/embeddings/embedding-types.ts

@@ -113,25 +113,6 @@ export interface EmbeddingBackend {
     options?: EmbeddingRequestOptions,
   ): Promise<number[][]>;
   dispose?(): void;
-  /**
-   * Deterministic teardown for daemon shutdown: release any OS resources the
-   * backend owns (e.g. a worker subprocess) and resolve only once they are
-   * confirmed gone. Unlike {@link dispose}, which may defer while embeds are
-   * in flight, this must not leave a child process behind.
-   */
-  shutdown?(): Promise<void>;
-  /**
-   * Release owned OS resources synchronously, for a process that must exit this
-   * tick. Unlike {@link shutdown} it cannot wait for confirmation, so it uses
-   * the uncatchable signal rather than the graceful one.
-   */
-  terminateNow?(): void;
-  /**
-   * Reap any owned child still attributable to this process, without needing a
-   * handle for it. Backstop for a teardown that could not resolve its handle in
-   * time.
-   */
-  sweepOwnedWorkers?(): Promise<void>;
 }
 
 /**

package/src/runtime/verification-outbound-actions.ts

@@ -278,7 +278,7 @@ async function startOutboundTelegram(
       success: false,
       error: "already_bound",
       message:
-        "A guardian is already bound for this channel. Set rebind: true to replace.",
+        "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,
     };
   }
@@ -820,7 +820,7 @@ async function startOutboundTextChannel(
       success: false,
       error: "already_bound",
       message:
-        "A guardian is already bound for this channel. Set rebind: true to replace.",
+        "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,
     };
   }

package/src/util/worker-pipe.test.ts

@@ -0,0 +1,100 @@
+import { afterEach, describe, expect, test } from "bun:test";
+
+import { writeWorkerLine } from "./worker-pipe.js";
+
+/** Comfortably larger than any OS pipe buffer, so the write cannot complete. */
+const OVERSIZED_LINE = "x".repeat(4 * 1024 * 1024);
+
+const spawned: { kill(signal?: NodeJS.Signals): void }[] = [];
+
+afterEach(() => {
+  for (const proc of spawned.splice(0)) {
+    try {
+      proc.kill("SIGKILL");
+    } catch {
+      /* already gone */
+    }
+  }
+});
+
+/** A live child that never reads stdin, the way a worker busy in ONNX does not. */
+function spawnBusyWorker() {
+  const proc = Bun.spawn({
+    cmd: [process.execPath, "-e", "setTimeout(() => {}, 60_000)"],
+    windowsHide: true,
+    stdin: "pipe",
+    stdout: "ignore",
+    stderr: "ignore",
+  });
+  spawned.push(proc);
+  return proc;
+}
+
+describe("writeWorkerLine", () => {
+  /**
+   * The production failure: the payload outruns the pipe buffer, Bun returns a
+   * pending promise, and the worker dies before draining it. Unobserved, that
+   * rejection is an `unhandledRejection`, which `bun test` reports as a failure
+   * of this test.
+   */
+  test("reports a write still pending when the worker dies", async () => {
+    const proc = spawnBusyWorker();
+    const failure = Promise.withResolvers<unknown>();
+
+    writeWorkerLine(proc.stdin, OVERSIZED_LINE, failure.resolve);
+    proc.kill("SIGKILL");
+
+    const err = await failure.promise;
+    expect(err).toBeInstanceOf(Error);
+    expect((err as NodeJS.ErrnoException).code).toBe("EPIPE");
+  });
+
+  test("reports a synchronous throw", () => {
+    const failures: unknown[] = [];
+    const epipe = Object.assign(new Error("EPIPE: broken pipe, write"), {
+      code: "EPIPE",
+    });
+    const stdin = {
+      write() {
+        throw epipe;
+      },
+      flush: () => 0,
+    };
+
+    writeWorkerLine(stdin, "line", (err) => failures.push(err));
+
+    expect(failures).toEqual([epipe]);
+  });
+
+  /** `write` and `flush` both report the same broken pipe. */
+  test("reports one failure when write and flush both reject", async () => {
+    const failures: unknown[] = [];
+    const epipe = new Error("EPIPE: broken pipe, send");
+    const stdin = {
+      write: () => Promise.reject(epipe),
+      flush: () => Promise.reject(epipe),
+    };
+
+    writeWorkerLine(stdin, "line", (err) => failures.push(err));
+    await Bun.sleep(0);
+
+    expect(failures).toEqual([epipe]);
+  });
+
+  test("stays silent when the line is delivered", async () => {
+    const failures: unknown[] = [];
+    const proc = Bun.spawn({
+      cmd: [process.execPath, "-e", "process.stdin.on('data', () => {})"],
+      windowsHide: true,
+      stdin: "pipe",
+      stdout: "ignore",
+      stderr: "ignore",
+    });
+    spawned.push(proc);
+
+    writeWorkerLine(proc.stdin, "hello", (err) => failures.push(err));
+    await Bun.sleep(50);
+
+    expect(failures).toEqual([]);
+  });
+});

package/src/util/worker-pipe.ts

@@ -0,0 +1,44 @@
+import type { FileSink } from "bun";
+
+/**
+ * Write one line to a worker subprocess's stdin, reporting a broken pipe to
+ * `onFailure` however Bun surfaces it.
+ *
+ * `FileSink.write` and `FileSink.flush` return `number | Promise<number>`.
+ * While the pipe has room they complete synchronously. Once a payload outruns
+ * the pipe buffer, which is what happens when the worker is busy and not
+ * draining stdin, they return a pending promise instead, and that promise
+ * rejects with EPIPE if the worker dies before the write completes. A
+ * `try/catch` sees only the synchronous half: the rejection escapes it, reaches
+ * the process's `unhandledRejection` handler, and in the daemon that handler
+ * shuts the whole process down.
+ *
+ * `onFailure` runs at most once per call, even though `write` and `flush` can
+ * each report the same broken pipe.
+ */
+export function writeWorkerLine(
+  stdin: Pick<FileSink, "write" | "flush">,
+  line: string,
+  onFailure: (err: unknown) => void,
+): void {
+  let failed = false;
+  const fail = (err: unknown): void => {
+    if (failed) {
+      return;
+    }
+    failed = true;
+    onFailure(err);
+  };
+  const observe = (result: number | Promise<number>): void => {
+    if (result instanceof Promise) {
+      result.catch(fail);
+    }
+  };
+
+  try {
+    observe(stdin.write(line + "\n"));
+    observe(stdin.flush());
+  } catch (err) {
+    fail(err);
+  }
+}