@vellumai/vellum-gateway 0.4.55 → 0.4.57

package/AGENTS.md

@@ -35,7 +35,7 @@ All assistant API requests from clients, CLI, skills, and user-facing tooling **
 
 Gateway inbound events use a channel-discriminated union model (`GatewayInboundEvent`) with explicit identity fields:
 
-- **`conversationExternalId`**: Delivery/thread address (e.g., Telegram chat ID, phone number). Used for conversation binding and message routing. **Not** used for trust classification.
+- **`conversationExternalId`**: Delivery/conversation address (e.g., Telegram chat ID, phone number). Used for conversation binding and message routing. **Not** used for trust classification.
 - **`actorExternalId`**: Sender identity (e.g., Telegram user ID, WhatsApp phone number). Used for trust classification, guardian binding, and ACL enforcement. **Required** for all public channel ingress.
 - **"conversation"** is canonical vocabulary for delivery addresses. "thread" is reserved for provider-specific fields (Slack `thread_ts`, email thread IDs).
 - **"actor"** is canonical vocabulary for sender identity.

package/ARCHITECTURE.md

@@ -215,13 +215,13 @@ Channel readiness endpoints are exposed directly by the gateway and forwarded to
 
 ### Channel Binding Lifecycle (Lane Separation)
 
-Each channel (desktop, Telegram, etc.) operates in its own **lane**: conversations created by an external channel are never displayed in the desktop thread list, and desktop conversations are never exposed to external channels. The `channelBinding` metadata on a conversation is used solely for routing inbound/outbound messages within that lane and for filtering sessions during desktop session restoration.
+Each channel (desktop, Telegram, etc.) operates in its own **lane**: conversations created by an external channel are never displayed in the desktop conversation list, and desktop conversations are never exposed to external channels. The `channelBinding` metadata on a conversation is used solely for routing inbound/outbound messages within that lane and for filtering conversations during desktop conversation restoration.
 
 Channel bindings follow a three-phase lifecycle:
 
 1. **Bind** — An inbound message from an external channel (e.g., Telegram chat) arrives at the gateway, which normalizes it and forwards it to the runtime's `/v1/channels/inbound` endpoint. The runtime creates or reuses a conversation, establishing the channel binding (`sourceChannel` metadata on the conversation).
 
-2. **Route** — Subsequent messages on the same external chat are routed to the same conversation via the channel binding. Replies from the assistant are delivered back through the gateway's `/deliver/telegram` endpoint. The desktop client filters out channel-bound sessions during session restoration (`ThreadSessionRestorer`) so they never appear in the desktop thread list.
+2. **Route** — Subsequent messages on the same external chat are routed to the same conversation via the channel binding. Replies from the assistant are delivered back through the gateway's `/deliver/telegram` endpoint. The desktop client filters out channel-bound conversations during conversation restoration (`ConversationRestorer`) so they never appear in the desktop conversation list.
 
 3. **Rebind** — If a message arrives on an external chat whose conversation was previously deleted, the channel inbound handler treats it as a new conversation and establishes a fresh binding. The external chat ID is reused, but the conversation is new.
 
@@ -741,7 +741,7 @@ sequenceDiagram
     alt ASK_GUARDIAN pattern detected
         Ctrl->>CallStore: createPendingQuestion()
         Ctrl->>GuardianDispatch: dispatchGuardianQuestion()
-        GuardianDispatch->>Mac: notification_thread_created SSE
+        GuardianDispatch->>Mac: notification_conversation_created SSE
         GuardianDispatch->>TG: POST /deliver/{channel}
         Note over Mac,TG: First channel to respond wins
         Mac/TG->>Routes: guardian answer
@@ -923,9 +923,9 @@ When the LLM emits `[ASK_GUARDIAN: question]` during a voice call, the controlle
 1. **Request creation**: A `guardian_action_request` row is created with a unique 6-character hex request code, the question text, a `pending` status, and an expiry timestamp.
 
 2. **Delivery fan-out via notification pipeline**: The guardian dispatch calls `emitNotificationSignal()` and uses the same notification decision + broadcaster path as every other producer.
-   - **Vellum**: Conversation pairing happens in the notification broadcaster. The resulting `notification_thread_created` event surfaces the thread in the desktop UI.
+   - **Vellum**: Conversation pairing happens in the notification broadcaster. The resulting `notification_conversation_created` event surfaces the conversation in the desktop UI.
    - **Telegram**: Delivery is handled by channel adapters selected by the notification decision and guarded by configured bindings.
-   - Guardian dispatch records `guardian_action_deliveries` from pipeline delivery results. It also uses the per-dispatch `onThreadCreated` callback so vellum delivery rows are created as soon as thread pairing occurs (without waiting for slower channels).
+   - Guardian dispatch records `guardian_action_deliveries` from pipeline delivery results. It also uses the per-dispatch `onConversationCreated` callback so vellum delivery rows are created as soon as conversation pairing occurs (without waiting for slower channels).
 
 3. **Answer resolution**: The first channel to respond wins. Answer resolution uses an atomic `WHERE status = 'pending'` check on the `guardian_action_requests` table -- only the first writer succeeds in transitioning the request to `answered` status. The winning answer text and responding channel are recorded on the request row.
 
@@ -939,7 +939,7 @@ When the LLM emits `[ASK_GUARDIAN: question]` during a voice call, the controlle
 
 #### macOS Notification + Deep-Link Flow
 
-When a guardian question is dispatched while the macOS app is backgrounded, the Swift client posts a native `UNUserNotificationCenter` notification from the generic `notification_intent` payload (`NOTIFICATION_INTENT` category). The deep-link metadata includes the paired conversation ID, so tapping the notification routes directly to the guardian thread.
+When a guardian question is dispatched while the macOS app is backgrounded, the Swift client posts a native `UNUserNotificationCenter` notification from the generic `notification_intent` payload (`NOTIFICATION_INTENT` category). The deep-link metadata includes the paired conversation ID, so tapping the notification routes directly to the guardian conversation.
 
 ### SQLite Tables
 
@@ -994,8 +994,8 @@ This makes ingress URL updates smoother in local tunnel workflows because Twilio
 | POST   | `/v1/internal/twilio/voice-webhook`    | Internal voice webhook used by gateway; accepts JSON `{ params, originalUrl, assistantId? }`, creates inbound session or returns TwiML |
 | GET    | `/v1/calls/:callSessionId`             | Get call status, including any pending question                                                                                        |
 | POST   | `/v1/calls/:callSessionId/cancel`      | Cancel an active call                                                                                                                  |
-| POST   | `/v1/calls/:callSessionId/answer`      | Answer a pending question via HTTP (alternative to in-thread bridge)                                                                   |
-| POST   | `/v1/calls/:callSessionId/instruction` | Relay a steering instruction to an active call's controller (alternative to in-thread bridge)                                          |
+| POST   | `/v1/calls/:callSessionId/answer`      | Answer a pending question via HTTP (alternative to in-conversation bridge)                                                             |
+| POST   | `/v1/calls/:callSessionId/instruction` | Relay a steering instruction to an active call's controller (alternative to in-conversation bridge)                                    |
 | POST   | `/v1/internal/twilio/status`           | Internal status callback used by gateway; accepts JSON `{ params }`                                                                    |
 | POST   | `/v1/internal/twilio/connect-action`   | Internal connect action callback used by gateway; accepts JSON `{ params }`                                                            |
 | WS     | `/v1/calls/relay`                      | ConversationRelay WebSocket (bidirectional: prompt/interrupt/dtmf from Twilio, text tokens/end to Twilio)                              |

package/Dockerfile

@@ -18,7 +18,7 @@ FROM debian:trixie-slim@sha256:1d3c811171a08a5adaa4a163fbafd96b61b87aa871bbc7aa1
 
 WORKDIR /app
 
-RUN apt-get update && apt-get install -y \
+RUN apt-get update && apt-get upgrade -y && apt-get install -y \
     ca-certificates \
     && rm -rf /var/lib/apt/lists/*
 

package/README.md

@@ -26,11 +26,11 @@ bun run dev
 
 ## Configuration
 
-| Variable                  | Required | Default | Description                                                                                                                                                                                                                                                                                                                                                                        |
-| ------------------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `TELEGRAM_BOT_TOKEN`      | No       | —       | Bot token from @BotFather (Telegram disabled when unset). When not set as an env var, the gateway reads from the assistant's secure credential store: keychain broker first (UDS to the assistant daemon), then the encrypted file store (`~/.vellum/protected/keys.enc`). When the broker is unavailable (daemon not running or non-macOS), the encrypted store is used directly. |
-| `TELEGRAM_WEBHOOK_SECRET` | No       | —       | Secret for verifying webhook requests (Telegram disabled when unset). Same credential reader fallback behavior as `TELEGRAM_BOT_TOKEN`.                                                                                                                                                                                                                                            |
-| `GATEWAY_PORT`            | No       | `7830`  | Port for the gateway HTTP server                                                                                                                                                                                                                                                                                                                                                   |
+| Variable                  | Required | Default | Description                                                                                                                                                                                                                                                                                                                                                                            |
+| ------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `TELEGRAM_BOT_TOKEN`      | No       | —       | Bot token from @BotFather (Telegram disabled when unset). When not set as an env var, the gateway reads from the assistant's secure credential store: keychain broker first (UDS to the assistant process), then the encrypted file store (`~/.vellum/protected/keys.enc`). When the broker is unavailable (assistant not running or non-macOS), the encrypted store is used directly. |
+| `TELEGRAM_WEBHOOK_SECRET` | No       | —       | Secret for verifying webhook requests (Telegram disabled when unset). Same credential reader fallback behavior as `TELEGRAM_BOT_TOKEN`.                                                                                                                                                                                                                                                |
+| `GATEWAY_PORT`            | No       | `7830`  | Port for the gateway HTTP server                                                                                                                                                                                                                                                                                                                                                       |
 
 Most gateway behavior is now configured via hardcoded defaults or workspace config (`~/.vellum/workspace/config.json`) rather than environment variables. Channel operational settings (Telegram API base URL, timeouts, deliver auth bypass flags, runtime base URL, routing, proxy settings, attachment limits, shutdown drain) are managed via `workspace/config.json` through `ConfigFileCache`. See the channel-specific sections in `ARCHITECTURE.md` for details.
 
@@ -185,7 +185,7 @@ Use this flow when you are changing files under `gateway/` and need to validate
 ```bash
 # Terminal 1: restart assistant runtime HTTP server
 cd assistant
-bun run daemon:restart:http
+bun run assistant:restart:http
 
 # Terminal 2: run gateway from local source with runtime proxy enabled
 cd gateway

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/vellum-gateway",
-  "version": "0.4.55",
+  "version": "0.4.57",
   "type": "module",
   "exports": {
     "./twilio/verify": "./src/twilio/verify.ts",

package/src/__tests__/browser-relay-websocket.test.ts

@@ -41,7 +41,12 @@ function makeConfig(overrides: Partial<GatewayConfig> = {}): GatewayConfig {
     runtimeInitialBackoffMs: 500,
     maxWebhookPayloadBytes: 1048576,
     logFile: { dir: undefined, retentionDays: 30 },
-    maxAttachmentBytes: 20971520,
+    maxAttachmentBytes: {
+      telegram: 50 * 1024 * 1024,
+      slack: 100 * 1024 * 1024,
+      whatsapp: 16 * 1024 * 1024,
+      default: 50 * 1024 * 1024,
+    },
     maxAttachmentConcurrency: 3,
     gatewayInternalBaseUrl: "http://127.0.0.1:7830",
     trustProxy: false,

package/src/__tests__/channel-verification-session-proxy.test.ts

@@ -35,7 +35,12 @@ function makeConfig(overrides: Partial<GatewayConfig> = {}): GatewayConfig {
     runtimeInitialBackoffMs: 500,
     maxWebhookPayloadBytes: 1048576,
     logFile: { dir: undefined, retentionDays: 30 },
-    maxAttachmentBytes: 20971520,
+    maxAttachmentBytes: {
+      telegram: 50 * 1024 * 1024,
+      slack: 100 * 1024 * 1024,
+      whatsapp: 16 * 1024 * 1024,
+      default: 50 * 1024 * 1024,
+    },
     maxAttachmentConcurrency: 3,
     gatewayInternalBaseUrl: "http://127.0.0.1:7830",
     trustProxy: false,

package/src/__tests__/config-file-cache.test.ts

@@ -44,7 +44,7 @@ describe("ConfigFileCache: getString", () => {
     expect(cache.getString("email", "address")).toBe("a@b.com");
   });
 
-  test("returns undefined for empty string", () => {
+  test("returns undefined for empty string value", () => {
     writeConfig({ email: { address: "" } });
     const cache = new ConfigFileCache();
     expect(cache.getString("email", "address")).toBeUndefined();

package/src/__tests__/config.test.ts

@@ -9,7 +9,12 @@ describe("config: hardcoded defaults", () => {
     expect(config.runtimeMaxRetries).toBe(2);
     expect(config.runtimeInitialBackoffMs).toBe(500);
     expect(config.maxWebhookPayloadBytes).toBe(1024 * 1024);
-    expect(config.maxAttachmentBytes).toBe(20 * 1024 * 1024);
+    expect(config.maxAttachmentBytes).toEqual({
+      telegram: 20 * 1024 * 1024,
+      slack: 100 * 1024 * 1024,
+      whatsapp: 16 * 1024 * 1024,
+      default: 100 * 1024 * 1024,
+    });
     expect(config.maxAttachmentConcurrency).toBe(3);
     expect(config.runtimeProxyEnabled).toBe(false);
     expect(config.runtimeProxyRequireAuth).toBe(true);

package/src/__tests__/contacts-control-plane-proxy.test.ts

@@ -35,7 +35,12 @@ function makeConfig(overrides: Partial<GatewayConfig> = {}): GatewayConfig {
     runtimeInitialBackoffMs: 500,
     maxWebhookPayloadBytes: 1048576,
     logFile: { dir: undefined, retentionDays: 30 },
-    maxAttachmentBytes: 20971520,
+    maxAttachmentBytes: {
+      telegram: 50 * 1024 * 1024,
+      slack: 100 * 1024 * 1024,
+      whatsapp: 16 * 1024 * 1024,
+      default: 50 * 1024 * 1024,
+    },
     maxAttachmentConcurrency: 3,
     gatewayInternalBaseUrl: "http://127.0.0.1:7830",
     trustProxy: false,

package/src/__tests__/credential-reader.test.ts

@@ -78,24 +78,16 @@ function getMachineEntropy(): string {
   return parts.join(":");
 }
 
-function writeEncryptedStore(entries: Record<string, string>): void {
-  const storePath = join(testDir, ".vellum", "protected", "keys.enc");
-  mkdirSync(join(testDir, ".vellum", "protected"), { recursive: true });
-
-  const salt = randomBytes(16);
-  const key = pbkdf2Sync(
-    getMachineEntropy(),
-    salt,
-    PBKDF2_ITERATIONS,
-    KEY_LENGTH,
-    "sha512",
-  );
+function encryptEntries(
+  entries: Record<string, string>,
+  key: Buffer,
+): Record<string, { iv: string; tag: string; data: string }> {
   const encryptedEntries: Record<
     string,
     { iv: string; tag: string; data: string }
   > = {};
   for (const [account, value] of Object.entries(entries)) {
-    const iv = randomBytes(12);
+    const iv = randomBytes(16);
     const cipher = createCipheriv(ALGORITHM, key, iv, {
       authTagLength: AUTH_TAG_LENGTH,
     });
@@ -110,15 +102,48 @@ function writeEncryptedStore(entries: Record<string, string>): void {
       data: encrypted.toString("hex"),
     };
   }
+  return encryptedEntries;
+}
+
+function writeEncryptedStore(entries: Record<string, string>): void {
+  const storePath = join(testDir, ".vellum", "protected", "keys.enc");
+  mkdirSync(join(testDir, ".vellum", "protected"), { recursive: true });
+
+  const salt = randomBytes(16);
+  const key = pbkdf2Sync(
+    getMachineEntropy(),
+    salt,
+    PBKDF2_ITERATIONS,
+    KEY_LENGTH,
+    "sha512",
+  );
 
   const store = {
     version: 1,
     salt: salt.toString("hex"),
-    entries: encryptedEntries,
+    entries: encryptEntries(entries, key),
   };
   writeFileSync(storePath, JSON.stringify(store));
 }
 
+/**
+ * Write a v2 encrypted store with a random store.key file.
+ * The store.key is used directly as the AES-256-GCM key (no PBKDF2).
+ */
+function writeEncryptedStoreV2(entries: Record<string, string>): void {
+  const protectedDir = join(testDir, ".vellum", "protected");
+  mkdirSync(protectedDir, { recursive: true });
+
+  const storeKey = randomBytes(KEY_LENGTH);
+  writeFileSync(join(protectedDir, "store.key"), storeKey);
+
+  const store = {
+    version: 2,
+    entries: encryptEntries(entries, storeKey),
+  };
+  writeFileSync(join(protectedDir, "keys.enc"), JSON.stringify(store));
+}
+
 // ---------------------------------------------------------------------------
 // Broker test helpers — mock UDS server
 // ---------------------------------------------------------------------------
@@ -264,6 +289,74 @@ describe("readTelegramCredentials", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// Tests: v2 encrypted store (store.key)
+// ---------------------------------------------------------------------------
+
+describe("v2 encrypted store with store.key", () => {
+  test("reads credential from v2 store when store.key exists", async () => {
+    writeEncryptedStoreV2({
+      [credentialKey("test", "key")]: "v2-secret-value",
+    });
+
+    const result = await readCredential(credentialKey("test", "key"));
+    expect(result).toBe("v2-secret-value");
+  });
+
+  test("returns undefined for v2 store when store.key is missing", async () => {
+    // Write a v2 store but without the store.key file
+    const protectedDir = join(testDir, ".vellum", "protected");
+    mkdirSync(protectedDir, { recursive: true });
+
+    const storeKey = randomBytes(KEY_LENGTH);
+    const store = {
+      version: 2,
+      entries: encryptEntries(
+        { [credentialKey("test", "key")]: "v2-secret-value" },
+        storeKey,
+      ),
+    };
+    writeFileSync(join(protectedDir, "keys.enc"), JSON.stringify(store));
+    // Deliberately do NOT write store.key
+
+    const result = await readCredential(credentialKey("test", "key"));
+    expect(result).toBeUndefined();
+  });
+
+  test("returns Telegram credentials from v2 store", async () => {
+    writeMetadata([
+      { service: "telegram", field: "bot_token" },
+      { service: "telegram", field: "webhook_secret" },
+    ]);
+
+    writeEncryptedStoreV2({
+      [credentialKey("telegram", "bot_token")]: "v2-bot-token",
+      [credentialKey("telegram", "webhook_secret")]: "v2-webhook-secret",
+    });
+
+    const result = await readTelegramCredentials();
+    expect(result).toEqual({
+      botToken: "v2-bot-token",
+      webhookSecret: "v2-webhook-secret",
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Tests: v1 encrypted store backward compatibility
+// ---------------------------------------------------------------------------
+
+describe("v1 encrypted store backward compatibility", () => {
+  test("v1 store continues to work with entropy-based key derivation", async () => {
+    writeEncryptedStore({
+      [credentialKey("test", "key")]: "v1-secret-value",
+    });
+
+    const result = await readCredential(credentialKey("test", "key"));
+    expect(result).toBe("v1-secret-value");
+  });
+});
+
 // ---------------------------------------------------------------------------
 // Tests: broker credential reading
 // ---------------------------------------------------------------------------

package/src/__tests__/credential-watcher.test.ts

@@ -14,7 +14,7 @@ import {
   pbkdf2Sync,
   randomBytes as cryptoRandomBytes,
 } from "node:crypto";
-import { mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { mkdirSync, renameSync, writeFileSync, rmSync } from "node:fs";
 import { hostname, tmpdir, userInfo } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -68,7 +68,7 @@ function encrypt(
   value: string,
   key: Buffer,
 ): { iv: string; tag: string; data: string } {
-  const iv = cryptoRandomBytes(12);
+  const iv = cryptoRandomBytes(16);
   const cipher = createCipheriv(ALGORITHM, key, iv, {
     authTagLength: AUTH_TAG_LENGTH,
   });
@@ -115,38 +115,71 @@ function writeEncryptedStore(botToken: string, webhookSecret: string): void {
 }
 
 /**
- * Write credential metadata so readTelegramCredentials() knows to look
- * for bot_token and webhook_secret.
+ * Write Telegram credentials into a v2 encrypted store using a random
+ * store.key file (no PBKDF2 derivation).
  */
-function writeCredentialMetadata(): void {
+function writeEncryptedStoreV2(
+  botToken: string,
+  webhookSecret: string,
+): void {
+  const protectedDir = join(testDir, ".vellum", "protected");
+  mkdirSync(protectedDir, { recursive: true });
+
+  const storeKey = cryptoRandomBytes(KEY_LENGTH);
+  writeFileSync(join(protectedDir, "store.key"), storeKey);
+
+  const store = {
+    version: 2,
+    entries: {
+      "credential/telegram/bot_token": encrypt(botToken, storeKey),
+      "credential/telegram/webhook_secret": encrypt(webhookSecret, storeKey),
+    },
+  };
+
+  writeFileSync(join(protectedDir, "keys.enc"), JSON.stringify(store));
+}
+
+function metadataRecord(
+  credentialId: string,
+  service: string,
+  field: string,
+): Record<string, unknown> {
+  return {
+    credentialId,
+    service,
+    field,
+    allowedTools: [],
+    allowedDomains: [],
+    createdAt: Date.now(),
+    updatedAt: Date.now(),
+  };
+}
+
+/**
+ * Write credential metadata using the same atomic rename pattern as the
+ * production metadata store.
+ */
+function writeCredentialMetadata(
+  credentials: Record<string, unknown>[] = [
+    metadataRecord("test-bt", "telegram", "bot_token"),
+    metadataRecord("test-ws", "telegram", "webhook_secret"),
+  ],
+): void {
   const dir = join(testDir, ".vellum", "workspace", "data", "credentials");
   mkdirSync(dir, { recursive: true });
+  const metadataPath = join(dir, "metadata.json");
+  const tmpPath = join(
+    dir,
+    `.tmp-${cryptoRandomBytes(4).toString("hex")}-metadata.json`,
+  );
   writeFileSync(
-    join(dir, "metadata.json"),
+    tmpPath,
     JSON.stringify({
       version: 2,
-      credentials: [
-        {
-          credentialId: "test-bt",
-          service: "telegram",
-          field: "bot_token",
-          allowedTools: [],
-          allowedDomains: [],
-          createdAt: Date.now(),
-          updatedAt: Date.now(),
-        },
-        {
-          credentialId: "test-ws",
-          service: "telegram",
-          field: "webhook_secret",
-          allowedTools: [],
-          allowedDomains: [],
-          createdAt: Date.now(),
-          updatedAt: Date.now(),
-        },
-      ],
+      credentials,
     }),
   );
+  renameSync(tmpPath, metadataPath);
 }
 
 // ---------------------------------------------------------------------------
@@ -157,11 +190,11 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const gatewayRoot = join(__dirname, "..", "..");
 const gatewayEntry = join(gatewayRoot, "src", "index.ts");
 
-const port = 49152 + Math.floor(Math.random() * 16383);
-
 let gatewayProc: ChildProcess | null = null;
+let port = 0;
 
 async function startGateway(): Promise<void> {
+  port = 49152 + Math.floor(Math.random() * 16383);
   gatewayProc = spawn("bun", ["run", gatewayEntry], {
     env: {
       ...process.env,
@@ -238,4 +271,81 @@ describe("gateway telegram hot-reload (e2e)", () => {
     });
     expect(after.status).toBe(401);
   }, 15_000);
+
+  test("gateway keeps reloading credentials after multiple atomic metadata rewrites when metadata.json already existed at startup", async () => {
+    mkdirSync(testDir, { recursive: true });
+
+    // Start in file-watch mode by creating metadata.json before boot, but
+    // omit Telegram entries so the integration is initially unconfigured.
+    writeCredentialMetadata([metadataRecord("baseline", "github", "token")]);
+    writeEncryptedStore("fake-bot-token:ABC123", "fake-webhook-secret");
+
+    await startGateway();
+
+    const base = `http://localhost:${port}`;
+
+    const before = await fetch(`${base}/webhooks/telegram`, {
+      method: "POST",
+    });
+    expect(before.status).toBe(503);
+
+    // First rewrite after startup stales a file-scoped fs.watch() subscription
+    // on macOS when metadata.json is atomically replaced.
+    writeCredentialMetadata([
+      metadataRecord("baseline", "github", "token"),
+      metadataRecord("other", "openai", "api_key"),
+    ]);
+
+    await new Promise((resolve) => setTimeout(resolve, 1200));
+
+    // Second rewrite adds Telegram credentials. The gateway must still see
+    // this update without requiring a restart.
+    writeCredentialMetadata([
+      metadataRecord("baseline", "github", "token"),
+      metadataRecord("other", "openai", "api_key"),
+      metadataRecord("test-bt", "telegram", "bot_token"),
+      metadataRecord("test-ws", "telegram", "webhook_secret"),
+    ]);
+
+    await new Promise((resolve) => setTimeout(resolve, 2000));
+
+    const after = await fetch(`${base}/webhooks/telegram`, {
+      method: "POST",
+    });
+    expect(after.status).toBe(401);
+  }, 15_000);
+
+  test("gateway hot-reloads v2 encrypted store credentials written after startup", async () => {
+    // --- Setup: no credentials directory exists (fresh hatch) ---
+    mkdirSync(testDir, { recursive: true });
+
+    // Start the real gateway process
+    await startGateway();
+
+    const base = `http://localhost:${port}`;
+
+    // --- Step 1: confirm Telegram is NOT configured ---
+    const before = await fetch(`${base}/webhooks/telegram`, {
+      method: "POST",
+    });
+    expect(before.status).toBe(503);
+    const beforeBody = (await before.json()) as { error: string };
+    expect(beforeBody.error).toBe("Telegram integration not configured");
+
+    // --- Step 2: simulate daemon writing v2 credentials ---
+    writeEncryptedStoreV2("fake-v2-bot-token:XYZ", "fake-v2-webhook-secret");
+    writeCredentialMetadata();
+
+    // Wait for credential watcher debounce (500ms) + generous margin
+    await new Promise((resolve) => setTimeout(resolve, 2000));
+
+    // --- Step 3: query again — gateway should now recognize Telegram is configured.
+    // We expect 401 (webhook secret verification failed) rather than 503
+    // (not configured). Getting past the 503 gate proves the gateway
+    // hot-reloaded the v2 credentials from the credential store.
+    const after = await fetch(`${base}/webhooks/telegram`, {
+      method: "POST",
+    });
+    expect(after.status).toBe(401);
+  }, 15_000);
 });