vellum 0.2.7 → 0.2.8

package/bun.lock

@@ -12,7 +12,7 @@
         "@qdrant/js-client-rest": "^1.16.2",
         "@sentry/node": "^10.38.0",
         "@vellumai/cli": "0.1.8",
-        "@vellumai/vellum-gateway": "0.1.9",
+        "@vellumai/vellum-gateway": "0.1.10",
         "agentmail": "^0.1.0",
         "archiver": "^7.0.1",
         "commander": "^13.1.0",
@@ -544,7 +544,7 @@
 
     "@vellumai/cli": ["@vellumai/cli@0.1.8", "", { "dependencies": { "ink": "^6.7.0", "react": "^19.2.4" }, "bin": { "vellum-cli": "src/index.ts" } }, "sha512-36P6W1rV1dK9Qg0N3oFjffz1CSarkGBgqc2ZGEI1de9RPSkVWBI0QmKCZrPeg1/qDzEh3InUIsV1qjNIe7z1pg=="],
 
-    "@vellumai/vellum-gateway": ["@vellumai/vellum-gateway@0.1.9", "", { "dependencies": { "file-type": "^21.3.0", "pino": "^9.6.0", "pino-pretty": "^13.1.3", "zod": "^4.3.6" } }, "sha512-LNE5ueTWvyi4jJxIb99qKyanOX2H9DftR2CliC4vfU6jjLQdvvD3vZccx/VS5uVhfQsIQK08HF1XF9MtCwoJHA=="],
+    "@vellumai/vellum-gateway": ["@vellumai/vellum-gateway@0.1.10", "", { "dependencies": { "file-type": "^21.3.0", "pino": "^9.6.0", "pino-pretty": "^13.1.3", "zod": "^4.3.6" } }, "sha512-a41fGexW8RpWL4RTfZ3EM+XJMvz7t26D1axu2xAtZioXW3ZWMLGuogHnIJsgglzESl49E6VmmUsUGeD+dseV2w=="],
 
     "abort-controller": ["abort-controller@3.0.0", "", { "dependencies": { "event-target-shim": "^5.0.0" } }, "sha512-h8lQ8tacZYnR3vNQTgibj+tODHI5/+l06Au2Pcriv/Gmet0eaj4TwWH41sO9wnHDiQsEj19q0drzdWdeAHtweg=="],
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vellum",
-  "version": "0.2.7",
+  "version": "0.2.8",
   "type": "module",
   "bin": {
     "vellum": "./src/index.ts"
@@ -29,7 +29,7 @@
     "@qdrant/js-client-rest": "^1.16.2",
     "@sentry/node": "^10.38.0",
     "@vellumai/cli": "0.1.8",
-    "@vellumai/vellum-gateway": "0.1.9",
+    "@vellumai/vellum-gateway": "0.1.10",
     "agentmail": "^0.1.0",
     "archiver": "^7.0.1",
     "commander": "^13.1.0",

package/src/__tests__/asset-materialize-tool.test.ts

@@ -249,8 +249,8 @@ describe('AssetMaterializeTool size limit', () => {
     const db = getDb();
     const fakeId = 'oversized-attachment';
     db.run(
-      `INSERT INTO attachments (id, assistant_id, original_filename, mime_type, size_bytes, kind, data_base64, created_at)
-       VALUES ('${fakeId}', 'ast-1', 'huge.bin', 'application/octet-stream', ${51 * 1024 * 1024}, 'document', 'AAAA', ${Date.now()})`,
+      `INSERT INTO attachments (id, original_filename, mime_type, size_bytes, kind, data_base64, created_at)
+       VALUES ('${fakeId}', 'huge.bin', 'application/octet-stream', ${51 * 1024 * 1024}, 'document', 'AAAA', ${Date.now()})`,
     );
 
     const result = await assetMaterializeTool.execute(

package/src/__tests__/checker.test.ts

@@ -3854,3 +3854,107 @@ describe('computer-use tool permission defaults', () => {
     expect(risk).toBe(RiskLevel.Low);
   });
 });
+
+// ---------------------------------------------------------------------------
+// Scope-matching behavior: project-scoped vs everywhere rules
+// ---------------------------------------------------------------------------
+
+describe('scope matching behavior', () => {
+  beforeEach(() => {
+    clearCache();
+    testConfig.permissions = { mode: 'legacy' };
+    try { rmSync(join(checkerTestDir, 'protected', 'trust.json')); } catch { /* may not exist */ }
+  });
+
+  test('project-scoped rule matches tool invocations from within that directory', async () => {
+    const projectDir = '/home/user/my-project';
+    // Use the pattern format that file tools produce: "toolName:path/**"
+    addRule('file_write', 'file_write:/home/user/my-project/**', projectDir);
+
+    // Invocation from within the project directory should match
+    const result = await check('file_write', { path: '/home/user/my-project/src/index.ts' }, projectDir);
+    expect(result.decision).toBe('allow');
+    expect(result.matchedRule).toBeDefined();
+    expect(result.matchedRule!.scope).toBe(projectDir);
+  });
+
+  test('project-scoped rule matches tool invocations from subdirectory of project', async () => {
+    const projectDir = '/home/user/my-project';
+    addRule('file_write', 'file_write:/home/user/my-project/**', projectDir);
+
+    // Invocation from a subdirectory should also match (scope is a prefix match)
+    const result = await check('file_write', { path: '/home/user/my-project/src/index.ts' }, '/home/user/my-project/src');
+    expect(result.decision).toBe('allow');
+    expect(result.matchedRule).toBeDefined();
+    expect(result.matchedRule!.scope).toBe(projectDir);
+  });
+
+  test('project-scoped rule does NOT match invocations from sibling directory', async () => {
+    const projectDir = '/home/user/my-project';
+    // Use a broad pattern that matches any file, scoped to the project
+    addRule('file_write', 'file_write:*', projectDir);
+
+    // Invocation from a sibling directory should NOT match the project-scoped rule
+    const result = await check('file_write', { path: '/home/user/other-project/file.ts' }, '/home/user/other-project');
+    expect(result.decision).toBe('prompt');
+  });
+
+  test('project-scoped rule does NOT match invocations from parent directory', async () => {
+    const projectDir = '/home/user/my-project';
+    addRule('file_write', 'file_write:*', projectDir);
+
+    // Invocation from a parent directory should NOT match
+    const result = await check('file_write', { path: '/home/user/file.txt' }, '/home/user');
+    expect(result.decision).toBe('prompt');
+  });
+
+  test('project-scoped rule does NOT match directory with shared prefix', async () => {
+    // A rule for /home/user/project should NOT match /home/user/project-evil
+    // (directory-boundary enforcement in matchesScope)
+    const projectDir = '/home/user/project';
+    addRule('file_write', 'file_write:*', projectDir);
+
+    const result = await check('file_write', { path: '/home/user/project-evil/malicious.ts' }, '/home/user/project-evil');
+    expect(result.decision).toBe('prompt');
+  });
+
+  test('everywhere-scoped rule matches invocations from any directory', async () => {
+    addRule('file_write', 'file_write:*', 'everywhere');
+
+    // Should match from various directories
+    const r1 = await check('file_write', { path: 'file.ts' }, '/home/user/project-a');
+    expect(r1.decision).toBe('allow');
+    expect(r1.matchedRule).toBeDefined();
+    expect(r1.matchedRule!.scope).toBe('everywhere');
+
+    const r2 = await check('file_write', { path: 'output.txt' }, '/var/tmp');
+    expect(r2.decision).toBe('allow');
+    expect(r2.matchedRule!.scope).toBe('everywhere');
+
+    const r3 = await check('file_write', { path: 'file.json' }, '/opt/data');
+    expect(r3.decision).toBe('allow');
+    expect(r3.matchedRule!.scope).toBe('everywhere');
+  });
+
+  test('bash rule scoped to project matches commands within that project', async () => {
+    const projectDir = '/home/user/my-project';
+    addRule('bash', 'npm *', projectDir);
+
+    const result = await check('bash', { command: 'npm install' }, projectDir);
+    expect(result.decision).toBe('allow');
+    expect(result.matchedRule).toBeDefined();
+  });
+
+  test('bash rule scoped to project does NOT match commands from different project', async () => {
+    const projectDir = '/home/user/my-project';
+    addRule('bash', 'npm *', projectDir);
+
+    const result = await check('bash', { command: 'npm install' }, '/home/user/other-project');
+    // npm install is Low risk, so it falls through to auto-allow via the
+    // default sandbox bash rule, not via the project-scoped rule.
+    // The key assertion is that the project-scoped rule is NOT the matched rule.
+    if (result.matchedRule) {
+      expect(result.matchedRule.scope).not.toBe(projectDir);
+    }
+  });
+});

package/src/__tests__/gateway-only-enforcement.test.ts

@@ -0,0 +1,458 @@
+/**
+ * Tests for gateway-only ingress mode enforcement in the runtime HTTP server.
+ *
+ * Verifies:
+ * - Direct Twilio webhook routes return 410 in gateway_only mode
+ * - Internal forwarding routes (gateway→runtime) still work in gateway_only mode
+ * - Relay WebSocket upgrade blocked for non-localhost origins in gateway_only mode
+ * - Relay WebSocket upgrade allowed from localhost in gateway_only mode
+ * - All routes work normally in compat mode
+ * - Startup warning when RUNTIME_HTTP_HOST is not loopback in gateway_only mode
+ */
+import { describe, test, expect, beforeEach, afterEach, mock, spyOn } from 'bun:test';
+import { mkdtempSync, rmSync, realpathSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const testDir = realpathSync(mkdtempSync(join(tmpdir(), 'gw-only-enforcement-test-')));
+
+mock.module('../util/platform.js', () => ({
+  getRootDir: () => testDir,
+  getDataDir: () => testDir,
+  getWorkspaceConfigPath: () => join(testDir, 'config.json'),
+  isMacOS: () => process.platform === 'darwin',
+  isLinux: () => process.platform === 'linux',
+  isWindows: () => process.platform === 'win32',
+  getSocketPath: () => join(testDir, 'test.sock'),
+  getPidPath: () => join(testDir, 'test.pid'),
+  getDbPath: () => join(testDir, 'test.db'),
+  getLogPath: () => join(testDir, 'test.log'),
+  ensureDataDir: () => {},
+  migrateToDataLayout: () => {},
+  migrateToWorkspaceLayout: () => {},
+}));
+
+// Configurable ingress mode — tests toggle this between 'gateway_only' and 'compat'
+let mockIngressMode: 'gateway_only' | 'compat' = 'compat';
+
+const logMessages: { level: string; msg: string; args?: unknown }[] = [];
+
+mock.module('../util/logger.js', () => ({
+  getLogger: () => new Proxy({} as Record<string, unknown>, {
+    get: (_target, prop: string) => {
+      if (prop === 'child') return () => new Proxy({} as Record<string, unknown>, {
+        get: () => () => {},
+      });
+      return (...args: unknown[]) => {
+        if (typeof args[0] === 'string') {
+          logMessages.push({ level: prop, msg: args[0] });
+        } else if (typeof args[1] === 'string') {
+          logMessages.push({ level: prop, msg: args[1], args: args[0] });
+        }
+      };
+    },
+  }),
+}));
+
+mock.module('../config/loader.js', () => ({
+  loadConfig: () => ({
+    model: 'test',
+    provider: 'test',
+    apiKeys: {},
+    memory: { enabled: false },
+    rateLimit: { maxRequestsPerMinute: 0, maxTokensPerSession: 0 },
+    secretDetection: { enabled: false },
+    calls: {
+      enabled: true,
+      provider: 'twilio',
+      webhookBaseUrl: 'https://test.example.com',
+      maxDurationSeconds: 3600,
+      userConsultTimeoutSeconds: 120,
+      disclosure: { enabled: false, text: '' },
+      safety: { denyCategories: [] },
+    },
+    ingress: {
+      publicBaseUrl: 'https://test.example.com',
+      mode: mockIngressMode,
+    },
+  }),
+  getConfig: () => ({
+    model: 'test',
+    provider: 'test',
+    apiKeys: {},
+    memory: { enabled: false },
+    rateLimit: { maxRequestsPerMinute: 0, maxTokensPerSession: 0 },
+    secretDetection: { enabled: false },
+    ingress: {
+      publicBaseUrl: 'https://test.example.com',
+      mode: mockIngressMode,
+    },
+  }),
+  invalidateConfigCache: () => {},
+}));
+
+// Mock Twilio provider
+mock.module('../calls/twilio-provider.js', () => ({
+  TwilioConversationRelayProvider: class {
+    static getAuthToken() { return 'mock-auth-token'; }
+    static verifyWebhookSignature() { return true; }
+    async initiateCall() { return { callSid: 'CA_mock_sid' }; }
+    async endCall() { return; }
+  },
+}));
+
+// Mock Twilio config
+mock.module('../calls/twilio-config.js', () => ({
+  getTwilioConfig: () => ({
+    accountSid: 'AC_test',
+    authToken: 'test_token',
+    phoneNumber: '+15550001111',
+    webhookBaseUrl: 'https://test.example.com',
+    wssBaseUrl: 'wss://test.example.com',
+  }),
+}));
+
+mock.module('../security/secure-keys.js', () => ({
+  getSecureKey: () => null,
+  setSecureKey: () => true,
+  deleteSecureKey: () => {},
+}));
+
+mock.module('../inbound/public-ingress-urls.js', () => ({
+  getPublicBaseUrl: () => 'https://test.example.com',
+  getTwilioRelayUrl: () => 'wss://test.example.com/webhooks/twilio/relay',
+  getTwilioVoiceWebhookUrl: (_cfg: unknown, id: string) => `https://test.example.com/webhooks/twilio/voice?callSessionId=${id}`,
+  getTwilioStatusCallbackUrl: () => 'https://test.example.com/webhooks/twilio/status',
+  getTwilioConnectActionUrl: () => 'https://test.example.com/webhooks/twilio/connect-action',
+  getOAuthCallbackUrl: () => 'https://test.example.com/webhooks/oauth/callback',
+}));
+
+// Mock the oauth callback registry
+mock.module('../security/oauth-callback-registry.js', () => ({
+  consumeCallback: () => true,
+  consumeCallbackError: () => true,
+}));
+
+import { RuntimeHttpServer } from '../runtime/http-server.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const TEST_TOKEN = 'test-bearer-token-gw';
+const AUTH_HEADERS = { Authorization: `Bearer ${TEST_TOKEN}` };
+
+function makeFormBody(params: Record<string, string>): string {
+  return new URLSearchParams(params).toString();
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('gateway-only ingress enforcement', () => {
+  let server: RuntimeHttpServer;
+  let port: number;
+
+  beforeEach(async () => {
+    logMessages.length = 0;
+    port = 17800 + Math.floor(Math.random() * 1000);
+    server = new RuntimeHttpServer({
+      port,
+      hostname: '127.0.0.1',
+      bearerToken: TEST_TOKEN,
+    });
+    await server.start();
+  });
+
+  afterEach(async () => {
+    await server.stop();
+  });
+
+  // ── Direct Twilio webhook routes blocked in gateway_only mode ──────
+
+  describe('gateway_only mode — direct webhook routes', () => {
+    beforeEach(() => { mockIngressMode = 'gateway_only'; });
+    afterEach(() => { mockIngressMode = 'compat'; });
+
+    test('POST /webhooks/twilio/voice returns 410', async () => {
+      const res = await fetch(`http://127.0.0.1:${port}/webhooks/twilio/voice`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+        body: makeFormBody({ CallSid: 'CA123', AccountSid: 'AC_test' }),
+      });
+      expect(res.status).toBe(410);
+      const body = await res.json() as { error: string; code: string };
+      expect(body.code).toBe('GATEWAY_ONLY');
+      expect(body.error).toContain('gateway-only mode');
+    });
+
+    test('POST /webhooks/twilio/status returns 410', async () => {
+      const res = await fetch(`http://127.0.0.1:${port}/webhooks/twilio/status`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+        body: makeFormBody({ CallSid: 'CA123', CallStatus: 'completed' }),
+      });
+      expect(res.status).toBe(410);
+      const body = await res.json() as { error: string; code: string };
+      expect(body.code).toBe('GATEWAY_ONLY');
+    });
+
+    test('POST /webhooks/twilio/connect-action returns 410', async () => {
+      const res = await fetch(`http://127.0.0.1:${port}/webhooks/twilio/connect-action`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+        body: makeFormBody({ CallSid: 'CA123' }),
+      });
+      expect(res.status).toBe(410);
+      const body = await res.json() as { error: string; code: string };
+      expect(body.code).toBe('GATEWAY_ONLY');
+    });
+
+    test('POST /v1/calls/twilio/voice-webhook returns 410', async () => {
+      const res = await fetch(`http://127.0.0.1:${port}/v1/calls/twilio/voice-webhook`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+        body: makeFormBody({ CallSid: 'CA123' }),
+      });
+      expect(res.status).toBe(410);
+      const body = await res.json() as { error: string; code: string };
+      expect(body.code).toBe('GATEWAY_ONLY');
+    });
+
+    test('POST /v1/calls/twilio/status returns 410', async () => {
+      const res = await fetch(`http://127.0.0.1:${port}/v1/calls/twilio/status`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+        body: makeFormBody({ CallSid: 'CA123', CallStatus: 'completed' }),
+      });
+      expect(res.status).toBe(410);
+      const body = await res.json() as { error: string; code: string };
+      expect(body.code).toBe('GATEWAY_ONLY');
+    });
+  });
+
+  // ── Internal forwarding routes still work in gateway_only mode ─────
+
+  describe('gateway_only mode — internal forwarding routes', () => {
+    beforeEach(() => { mockIngressMode = 'gateway_only'; });
+    afterEach(() => { mockIngressMode = 'compat'; });
+
+    test('POST /v1/internal/twilio/voice-webhook is NOT blocked', async () => {
+      const res = await fetch(`http://127.0.0.1:${port}/v1/internal/twilio/voice-webhook`, {
+        method: 'POST',
+        headers: { ...AUTH_HEADERS, 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          params: { CallSid: 'CA123', AccountSid: 'AC_test' },
+          originalUrl: `http://127.0.0.1:${port}/v1/internal/twilio/voice-webhook?callSessionId=sess-123`,
+        }),
+      });
+      // Should NOT be 410 — it may 404 or 400 because the call session
+      // doesn't exist, but the gateway-only guard should NOT block it.
+      expect(res.status).not.toBe(410);
+    });
+
+    test('POST /v1/internal/twilio/status is NOT blocked', async () => {
+      const res = await fetch(`http://127.0.0.1:${port}/v1/internal/twilio/status`, {
+        method: 'POST',
+        headers: { ...AUTH_HEADERS, 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          params: { CallSid: 'CA123', CallStatus: 'completed' },
+        }),
+      });
+      expect(res.status).not.toBe(410);
+    });
+
+    test('POST /v1/internal/twilio/connect-action is NOT blocked', async () => {
+      const res = await fetch(`http://127.0.0.1:${port}/v1/internal/twilio/connect-action`, {
+        method: 'POST',
+        headers: { ...AUTH_HEADERS, 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          params: { CallSid: 'CA123' },
+        }),
+      });
+      expect(res.status).not.toBe(410);
+    });
+
+    test('POST /v1/internal/oauth/callback is NOT blocked', async () => {
+      const res = await fetch(`http://127.0.0.1:${port}/v1/internal/oauth/callback`, {
+        method: 'POST',
+        headers: { ...AUTH_HEADERS, 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          state: 'test-state',
+          code: 'test-code',
+        }),
+      });
+      // Should succeed or return a non-410 status
+      expect(res.status).not.toBe(410);
+    });
+  });
+
+  // ── Relay WebSocket upgrade in gateway_only mode ───────────────────
+
+  describe('gateway_only mode — relay WebSocket upgrade', () => {
+    beforeEach(() => { mockIngressMode = 'gateway_only'; });
+    afterEach(() => { mockIngressMode = 'compat'; });
+
+    test('blocks non-localhost origin', async () => {
+      const res = await fetch(`http://127.0.0.1:${port}/v1/calls/relay?callSessionId=sess-123`, {
+        headers: {
+          'Upgrade': 'websocket',
+          'Connection': 'Upgrade',
+          'Origin': 'https://external.example.com',
+          'Sec-WebSocket-Key': 'dGhlIHNhbXBsZSBub25jZQ==',
+          'Sec-WebSocket-Version': '13',
+        },
+      });
+      expect(res.status).toBe(403);
+      const body = await res.json() as { error: string; code: string };
+      expect(body.code).toBe('GATEWAY_ONLY');
+      expect(body.error).toContain('gateway-only mode');
+    });
+
+    test('allows request with no origin header (localhost)', async () => {
+      // Without an origin header, isLoopbackOrigin returns true
+      const res = await fetch(`http://127.0.0.1:${port}/v1/calls/relay?callSessionId=sess-123`, {
+        headers: {
+          'Upgrade': 'websocket',
+          'Connection': 'Upgrade',
+          'Sec-WebSocket-Key': 'dGhlIHNhbXBsZSBub25jZQ==',
+          'Sec-WebSocket-Version': '13',
+        },
+      });
+      // Should NOT be 403 — WebSocket upgrade may or may not succeed
+      // depending on test environment, but the gateway guard should pass.
+      expect(res.status).not.toBe(403);
+    });
+
+    test('allows localhost origin', async () => {
+      const res = await fetch(`http://127.0.0.1:${port}/v1/calls/relay?callSessionId=sess-123`, {
+        headers: {
+          'Upgrade': 'websocket',
+          'Connection': 'Upgrade',
+          'Origin': 'http://127.0.0.1:3000',
+          'Sec-WebSocket-Key': 'dGhlIHNhbXBsZSBub25jZQ==',
+          'Sec-WebSocket-Version': '13',
+        },
+      });
+      // Should NOT be 403
+      expect(res.status).not.toBe(403);
+    });
+  });
+
+  // ── Compat mode — everything works as before ───────────────────────
+
+  describe('compat mode — no enforcement', () => {
+    beforeEach(() => { mockIngressMode = 'compat'; });
+
+    test('POST /webhooks/twilio/voice is NOT blocked', async () => {
+      // In compat mode, disable webhook validation to focus on the ingress check
+      const savedDisable = process.env.TWILIO_WEBHOOK_VALIDATION_DISABLED;
+      process.env.TWILIO_WEBHOOK_VALIDATION_DISABLED = 'true';
+      try {
+        const res = await fetch(`http://127.0.0.1:${port}/webhooks/twilio/voice?callSessionId=test-compat`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+          body: makeFormBody({ CallSid: 'CA_compat', AccountSid: 'AC_test' }),
+        });
+        // Should NOT be 410 (gateway-only)
+        expect(res.status).not.toBe(410);
+      } finally {
+        if (savedDisable !== undefined) {
+          process.env.TWILIO_WEBHOOK_VALIDATION_DISABLED = savedDisable;
+        } else {
+          delete process.env.TWILIO_WEBHOOK_VALIDATION_DISABLED;
+        }
+      }
+    });
+
+    test('POST /webhooks/twilio/status is NOT blocked', async () => {
+      const savedDisable = process.env.TWILIO_WEBHOOK_VALIDATION_DISABLED;
+      process.env.TWILIO_WEBHOOK_VALIDATION_DISABLED = 'true';
+      try {
+        const res = await fetch(`http://127.0.0.1:${port}/webhooks/twilio/status`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+          body: makeFormBody({ CallSid: 'CA_compat', CallStatus: 'completed' }),
+        });
+        expect(res.status).not.toBe(410);
+      } finally {
+        if (savedDisable !== undefined) {
+          process.env.TWILIO_WEBHOOK_VALIDATION_DISABLED = savedDisable;
+        } else {
+          delete process.env.TWILIO_WEBHOOK_VALIDATION_DISABLED;
+        }
+      }
+    });
+
+    test('relay WebSocket upgrade is NOT blocked for external origin', async () => {
+      const res = await fetch(`http://127.0.0.1:${port}/v1/calls/relay?callSessionId=sess-compat`, {
+        headers: {
+          'Upgrade': 'websocket',
+          'Connection': 'Upgrade',
+          'Origin': 'https://external.example.com',
+          'Sec-WebSocket-Key': 'dGhlIHNhbXBsZSBub25jZQ==',
+          'Sec-WebSocket-Version': '13',
+        },
+      });
+      // In compat mode, the gateway-only guard should not activate
+      expect(res.status).not.toBe(403);
+    });
+  });
+
+  // ── Startup warning for non-loopback host ──────────────────────────
+
+  describe('startup guard — non-loopback host warning', () => {
+    test('logs warning when hostname is not loopback in gateway_only mode', async () => {
+      mockIngressMode = 'gateway_only';
+      logMessages.length = 0;
+
+      const warnServer = new RuntimeHttpServer({
+        port: port + 100,
+        hostname: '0.0.0.0',
+        bearerToken: TEST_TOKEN,
+      });
+      await warnServer.start();
+
+      const infoMsg = logMessages.find(
+        m => m.level === 'info' && m.msg.includes('gateway-only ingress mode'),
+      );
+      expect(infoMsg).toBeDefined();
+
+      const warnMsg = logMessages.find(
+        m => m.level === 'warn' && m.msg.includes('not bound to loopback'),
+      );
+      expect(warnMsg).toBeDefined();
+
+      await warnServer.stop();
+      mockIngressMode = 'compat';
+    });
+
+    test('does NOT log warning when hostname is loopback in gateway_only mode', async () => {
+      mockIngressMode = 'gateway_only';
+      logMessages.length = 0;
+
+      // The main test server already uses 127.0.0.1, so restart with
+      // a fresh server and capture logs
+      const loopbackServer = new RuntimeHttpServer({
+        port: port + 200,
+        hostname: '127.0.0.1',
+        bearerToken: TEST_TOKEN,
+      });
+      await loopbackServer.start();
+
+      const infoMsg = logMessages.find(
+        m => m.level === 'info' && m.msg.includes('gateway-only ingress mode'),
+      );
+      expect(infoMsg).toBeDefined();
+
+      const warnMsg = logMessages.find(
+        m => m.level === 'warn' && m.msg.includes('not bound to loopback'),
+      );
+      expect(warnMsg).toBeUndefined();
+
+      await loopbackServer.stop();
+      mockIngressMode = 'compat';
+    });
+  });
+});

package/src/__tests__/ipc-snapshot.test.ts

@@ -1429,6 +1429,17 @@ const serverMessages: Record<ServerMessageType, ServerMessage> = {
       sessionId: 'sub-sess-001',
     },
   },
+  agent_heartbeat_alert: {
+    type: 'agent_heartbeat_alert',
+    title: 'Agent unresponsive',
+    body: 'The agent has not responded for 5 minutes.',
+  },
+  task_run_thread_created: {
+    type: 'task_run_thread_created',
+    conversationId: 'conv-task-001',
+    workItemId: 'work-item-001',
+    title: 'Task run thread',
+  },
 };
 
 // ---------------------------------------------------------------------------