vellum 0.2.9 → 0.2.11

package/src/daemon/handlers/identity.ts

@@ -0,0 +1,127 @@
+import * as net from 'node:net';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { getWorkspacePromptPath } from '../../util/platform.js';
+import { log, defineHandlers, type HandlerContext } from './shared.js';
+
+function handleIdentityGet(socket: net.Socket, ctx: HandlerContext): void {
+  const identityPath = getWorkspacePromptPath('IDENTITY.md');
+
+  if (!existsSync(identityPath)) {
+    ctx.send(socket, {
+      type: 'identity_get_response',
+      found: false,
+      name: '',
+      role: '',
+      personality: '',
+      emoji: '',
+      home: '',
+    });
+    return;
+  }
+
+  try {
+    const content = readFileSync(identityPath, 'utf-8');
+    const fields: Record<string, string> = {};
+    for (const line of content.split('\n')) {
+      const trimmed = line.trim();
+      const lower = trimmed.toLowerCase();
+      const extract = (prefix: string): string | null => {
+        if (!lower.startsWith(prefix)) return null;
+        return trimmed.split(':**').pop()?.trim() ?? null;
+      };
+
+      const name = extract('- **name:**');
+      if (name) { fields.name = name; continue; }
+      const role = extract('- **role:**');
+      if (role) { fields.role = role; continue; }
+      const personality = extract('- **personality:**') ?? extract('- **vibe:**');
+      if (personality) { fields.personality = personality; continue; }
+      const emoji = extract('- **emoji:**');
+      if (emoji) { fields.emoji = emoji; continue; }
+      const home = extract('- **home:**');
+      if (home) { fields.home = home; continue; }
+    }
+
+    // Read version from package.json
+    let version: string | undefined;
+    try {
+      const pkgPath = join(dirname(fileURLToPath(import.meta.url)), '../../../package.json');
+      const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+      version = pkg.version;
+    } catch {
+      // ignore
+    }
+
+    // Read createdAt from IDENTITY.md file birthtime
+    let createdAt: string | undefined;
+    try {
+      const stats = statSync(identityPath);
+      createdAt = stats.birthtime.toISOString();
+    } catch {
+      // ignore
+    }
+
+    // Read lockfile for assistantId, cloud, and originSystem
+    let assistantId: string | undefined;
+    let cloud: string | undefined;
+    let originSystem: string | undefined;
+    try {
+      const homedir = process.env.HOME ?? process.env.USERPROFILE ?? '';
+      const lockfilePaths = [
+        join(homedir, '.vellum.lock.json'),
+        join(homedir, '.vellum.lockfile.json'),
+      ];
+      for (const lockPath of lockfilePaths) {
+        if (!existsSync(lockPath)) continue;
+        const lockData = JSON.parse(readFileSync(lockPath, 'utf-8'));
+        const assistants = lockData.assistants as Array<Record<string, unknown>> | undefined;
+        if (assistants && assistants.length > 0) {
+          // Use the most recently hatched assistant
+          const sorted = [...assistants].sort((a, b) => {
+            const dateA = new Date(a.hatchedAt as string || 0).getTime();
+            const dateB = new Date(b.hatchedAt as string || 0).getTime();
+            return dateB - dateA;
+          });
+          const latest = sorted[0];
+          assistantId = latest.assistantId as string | undefined;
+          cloud = latest.cloud as string | undefined;
+          originSystem = cloud === 'local' ? 'local' : cloud;
+        }
+        break;
+      }
+    } catch {
+      // ignore — lockfile may not exist
+    }
+
+    ctx.send(socket, {
+      type: 'identity_get_response',
+      found: true,
+      name: fields.name ?? '',
+      role: fields.role ?? '',
+      personality: fields.personality ?? '',
+      emoji: fields.emoji ?? '',
+      home: fields.home ?? '',
+      version,
+      assistantId,
+      createdAt,
+      originSystem,
+    });
+  } catch (err) {
+    log.error({ err }, 'Failed to read identity');
+    ctx.send(socket, {
+      type: 'identity_get_response',
+      found: false,
+      name: '',
+      role: '',
+      personality: '',
+      emoji: '',
+      home: '',
+    });
+  }
+}
+
+export const identityHandlers = defineHandlers({
+  identity_get: (_msg, socket, ctx) => handleIdentityGet(socket, ctx),
+});

package/src/daemon/handlers/index.ts

@@ -20,6 +20,8 @@ import { subagentHandlers } from './subagents.js';
 import { browserHandlers } from './browser.js';
 import { signingHandlers } from './signing.js';
 import { twitterAuthHandlers } from './twitter-auth.js';
+import { workspaceFileHandlers } from './workspace-files.js';
+import { identityHandlers } from './identity.js';
 
 // Re-export types and utilities for backwards compatibility
 export type {
@@ -102,6 +104,8 @@ const handlers = {
   ...browserHandlers,
   ...signingHandlers,
   ...twitterAuthHandlers,
+  ...workspaceFileHandlers,
+  ...identityHandlers,
   ...inlineHandlers,
 } satisfies DispatchMap;
 

package/src/daemon/handlers/workspace-files.ts

@@ -0,0 +1,75 @@
+import * as net from 'node:net';
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve, sep } from 'node:path';
+import { getWorkspaceDir } from '../../util/platform.js';
+import { log, defineHandlers, type HandlerContext } from './shared.js';
+import type { WorkspaceFileReadRequest } from '../ipc-protocol.js';
+
+/** Well-known workspace prompt files shown in the Identity panel. */
+const WORKSPACE_FILES = ['IDENTITY.md', 'SOUL.md', 'USER.md', 'skills/'];
+
+function handleWorkspaceFilesList(socket: net.Socket, ctx: HandlerContext): void {
+  const base = getWorkspaceDir();
+  const files = WORKSPACE_FILES.map((name) => ({
+    path: name,
+    name,
+    exists: existsSync(join(base, name)),
+  }));
+  ctx.send(socket, { type: 'workspace_files_list_response', files });
+}
+
+function handleWorkspaceFileRead(
+  msg: WorkspaceFileReadRequest,
+  socket: net.Socket,
+  ctx: HandlerContext,
+): void {
+  const base = getWorkspaceDir();
+  const requested = msg.path;
+
+  // Prevent path traversal — reject paths that escape the workspace root.
+  // Use resolve() to canonicalize and check with trailing separator to prevent
+  // sibling directory prefix matches (e.g. "../workspace-evil/secret").
+  const resolved = resolve(base, requested);
+  if (!resolved.startsWith(base + sep) && resolved !== base) {
+    log.warn({ path: requested }, 'Workspace file read blocked: path traversal attempt');
+    ctx.send(socket, {
+      type: 'workspace_file_read_response',
+      path: requested,
+      content: null,
+      error: 'Invalid path',
+    });
+    return;
+  }
+
+  try {
+    if (!existsSync(resolved)) {
+      ctx.send(socket, {
+        type: 'workspace_file_read_response',
+        path: requested,
+        content: null,
+        error: 'File not found',
+      });
+      return;
+    }
+    const content = readFileSync(resolved, 'utf-8');
+    ctx.send(socket, {
+      type: 'workspace_file_read_response',
+      path: requested,
+      content,
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    log.error({ err, path: requested }, 'Failed to read workspace file');
+    ctx.send(socket, {
+      type: 'workspace_file_read_response',
+      path: requested,
+      content: null,
+      error: message,
+    });
+  }
+}
+
+export const workspaceFileHandlers = defineHandlers({
+  workspace_files_list: (_msg, socket, ctx) => handleWorkspaceFilesList(socket, ctx),
+  workspace_file_read: handleWorkspaceFileRead,
+});

package/src/daemon/ipc-contract-inventory.json

@@ -31,6 +31,7 @@
     "GetSigningIdentityResponse",
     "HistoryRequest",
     "HomeBaseGetRequest",
+    "IdentityGetRequest",
     "ImageGenModelSetRequest",
     "IngressConfigRequest",
     "IntegrationConnectRequest",
@@ -103,7 +104,9 @@
     "WorkItemPreflightRequest",
     "WorkItemRunTaskRequest",
     "WorkItemUpdateRequest",
-    "WorkItemsListRequest"
+    "WorkItemsListRequest",
+    "WorkspaceFileReadRequest",
+    "WorkspaceFilesListRequest"
   ],
   "serverMessageTypes": [
     "AcceptStarterBundleResponse",
@@ -143,6 +146,7 @@
     "GetSigningIdentityRequest",
     "HistoryResponse",
     "HomeBaseGetResponse",
+    "IdentityGetResponse",
     "IngressConfigResponse",
     "IntegrationConnectResult",
     "IntegrationListResponse",
@@ -222,7 +226,9 @@
     "WorkItemRunTaskResponse",
     "WorkItemStatusChanged",
     "WorkItemUpdateResponse",
-    "WorkItemsListResponse"
+    "WorkItemsListResponse",
+    "WorkspaceFileReadResponse",
+    "WorkspaceFilesListResponse"
   ],
   "clientWireTypes": [
     "accept_starter_bundle",
@@ -256,6 +262,7 @@
     "get_signing_identity_response",
     "history_request",
     "home_base_get",
+    "identity_get",
     "image_gen_model_set",
     "ingress_config",
     "integration_connect",
@@ -328,7 +335,9 @@
     "work_item_preflight",
     "work_item_run_task",
     "work_item_update",
-    "work_items_list"
+    "work_items_list",
+    "workspace_file_read",
+    "workspace_files_list"
   ],
   "serverWireTypes": [
     "accept_starter_bundle_response",
@@ -368,6 +377,7 @@
     "get_signing_identity",
     "history_response",
     "home_base_get_response",
+    "identity_get_response",
     "ingress_config_response",
     "integration_connect_result",
     "integration_list_response",
@@ -446,6 +456,8 @@
     "work_item_run_task_response",
     "work_item_status_changed",
     "work_item_update_response",
-    "work_items_list_response"
+    "work_items_list_response",
+    "workspace_file_read_response",
+    "workspace_files_list_response"
   ]
 }

package/src/daemon/ipc-contract.ts

@@ -476,6 +476,7 @@ export interface IngressConfigRequest {
   type: 'ingress_config';
   action: 'get' | 'set';
   publicBaseUrl?: string;
+  enabled?: boolean;
 }
 
 export interface VercelApiConfigRequest {
@@ -875,6 +876,22 @@ export interface WorkItemCancelRequest {
   id: string;
 }
 
+// === Workspace File IPC ─────────────────────────────────────────────────────
+
+export interface WorkspaceFilesListRequest {
+  type: 'workspace_files_list';
+}
+
+export interface WorkspaceFileReadRequest {
+  type: 'workspace_file_read';
+  /** Relative path within the workspace directory (e.g. "IDENTITY.md"). */
+  path: string;
+}
+
+export interface IdentityGetRequest {
+  type: 'identity_get';
+}
+
 export type ClientMessage =
   | AuthMessage
   | UserMessage
@@ -979,7 +996,10 @@ export type ClientMessage =
   | SubagentAbortRequest
   | SubagentStatusRequest
   | SubagentMessageRequest
-  | SubagentDetailRequest;
+  | SubagentDetailRequest
+  | WorkspaceFilesListRequest
+  | WorkspaceFileReadRequest
+  | IdentityGetRequest;
 
 export interface IntegrationListRequest {
   type: 'integration_list';
@@ -1690,6 +1710,7 @@ export interface SlackWebhookConfigResponse {
 
 export interface IngressConfigResponse {
   type: 'ingress_config_response';
+  enabled: boolean;
   publicBaseUrl: string;
   /** Read-only gateway target computed from GATEWAY_PORT env var (default 7830) + loopback host. */
   localGatewayTarget: string;
@@ -2103,6 +2124,42 @@ export interface TaskRunThreadCreated {
   title: string;
 }
 
+// === Workspace File Responses ────────────────────────────────────────────────
+
+export interface WorkspaceFilesListResponse {
+  type: 'workspace_files_list_response';
+  files: Array<{
+    /** Relative path within the workspace (e.g. "IDENTITY.md", "skills/my-skill"). */
+    path: string;
+    /** Display name (e.g. "IDENTITY.md"). */
+    name: string;
+    /** Whether the file/directory exists. */
+    exists: boolean;
+  }>;
+}
+
+export interface WorkspaceFileReadResponse {
+  type: 'workspace_file_read_response';
+  path: string;
+  content: string | null;
+  error?: string;
+}
+
+export interface IdentityGetResponse {
+  type: 'identity_get_response';
+  /** Whether an IDENTITY.md file was found. When false, all fields are empty defaults. Optional for backwards compat with older daemons. */
+  found?: boolean;
+  name: string;
+  role: string;
+  personality: string;
+  emoji: string;
+  home: string;
+  version?: string;
+  assistantId?: string;
+  createdAt?: string;
+  originSystem?: string;
+}
+
 export type ServerMessage =
   | AuthResult
   | UserMessageEcho
@@ -2220,7 +2277,10 @@ export type ServerMessage =
   | SubagentSpawned
   | SubagentStatusChanged
   | SubagentEvent
-  | SubagentDetailResponse;
+  | SubagentDetailResponse
+  | WorkspaceFilesListResponse
+  | WorkspaceFileReadResponse
+  | IdentityGetResponse;
 
 // === Subagent IPC ─────────────────────────────────────────────────────
 

package/src/daemon/lifecycle.ts

@@ -21,6 +21,7 @@ import { initializeProviders } from '../providers/registry.js';
 import { initializeTools } from '../tools/registry.js';
 import { loadConfig } from '../config/loader.js';
 import { ensurePromptFiles } from '../config/system-prompt.js';
+import { loadPrebuiltHtml } from '../home-base/prebuilt/seed.js';
 import { DaemonServer } from './server.js';
 import { listWorkItems, updateWorkItem } from '../work-items/work-item-store.js';
 import { getLogger, initLogger } from '../util/logger.js';
@@ -278,6 +279,21 @@ export async function runDaemon(): Promise<void> {
     log.info({ seedDir, interfacesDir }, 'Seeded initial interface files');
   }
 
+  // Seed the vellum-desktop interface from the prebuilt Home Base HTML if it
+  // doesn't already exist. This ensures the Home tab renders immediately
+  // on first launch for both local and remote hatches.
+  const desktopIndexPath = join(getInterfacesDir(), 'vellum-desktop', 'index.html');
+  if (!existsSync(desktopIndexPath)) {
+    const prebuiltHtml = loadPrebuiltHtml();
+    if (prebuiltHtml) {
+      mkdirSync(join(getInterfacesDir(), 'vellum-desktop'), { recursive: true });
+      writeFileSync(desktopIndexPath, prebuiltHtml);
+      log.info('Seeded vellum-desktop/index.html from prebuilt Home Base');
+    } else {
+      log.warn('Could not seed vellum-desktop/index.html — prebuilt HTML not found (missing embedded index.html in home-base/prebuilt/)');
+    }
+  }
+
   log.info('Daemon startup: installing templates and initializing DB');
   installTemplates();
   ensurePromptFiles();

package/src/daemon/session-notifiers.ts

@@ -25,6 +25,8 @@ import { lastCommentaryBySession, lastSummaryBySession } from './watch-handler.j
 import {
   registerCallQuestionNotifier,
   unregisterCallQuestionNotifier,
+  registerCallTranscriptNotifier,
+  unregisterCallTranscriptNotifier,
   registerCallCompletionNotifier,
   unregisterCallCompletionNotifier,
 } from '../calls/call-state.js';
@@ -114,6 +116,32 @@ export function registerSessionNotifiers(
     });
   });
 
+  registerCallTranscriptNotifier(
+    conversationId,
+    (_callSessionId: string, speaker: 'caller' | 'assistant', text: string) => {
+      const speakerLabel = speaker === 'caller' ? 'Caller' : 'Assistant';
+      const transcriptText = `**Live call transcript**\n${speakerLabel}: ${text}`;
+
+      conversationStore.addMessage(
+        conversationId,
+        'assistant',
+        JSON.stringify([{ type: 'text', text: transcriptText }]),
+      );
+
+      ctx.messages.push(createAssistantMessage(transcriptText));
+
+      ctx.sendToClient({
+        type: 'assistant_text_delta',
+        text: transcriptText,
+        sessionId: conversationId,
+      });
+      ctx.sendToClient({
+        type: 'message_complete',
+        sessionId: conversationId,
+      });
+    },
+  );
+
   registerCallCompletionNotifier(conversationId, (callSessionId: string) => {
     const callSession = getCallSession(callSessionId);
     const events = getCallEvents(callSessionId);
@@ -160,5 +188,6 @@ export function unregisterWatchNotifiers(conversationId: string): void {
  */
 export function unregisterCallNotifiers(conversationId: string): void {
   unregisterCallQuestionNotifier(conversationId);
+  unregisterCallTranscriptNotifier(conversationId);
   unregisterCallCompletionNotifier(conversationId);
 }

package/src/daemon/session-surfaces.ts

@@ -407,10 +407,11 @@ export function handleSurfaceAction(ctx: SurfaceSessionContext, surfaceId: strin
 /**
  * After an app_update, refresh any active surface that displays the updated app.
  */
-export function refreshSurfacesForApp(ctx: SurfaceSessionContext, appId: string, opts?: { fileChange?: boolean; status?: string }): void {
+export function refreshSurfacesForApp(ctx: SurfaceSessionContext, appId: string, opts?: { fileChange?: boolean; status?: string }): boolean {
   const app = getApp(appId);
-  if (!app) return;
+  if (!app) return false;
 
+  let refreshed = false;
   for (const [surfaceId, stored] of ctx.surfaceState.entries()) {
     if (stored.surfaceType !== 'dynamic_page') continue;
     const data = stored.data as DynamicPageSurfaceData;
@@ -436,8 +437,10 @@ export function refreshSurfacesForApp(ctx: SurfaceSessionContext, appId: string,
       data: updatedData,
     });
 
+    refreshed = true;
     log.info({ conversationId: ctx.conversationId, surfaceId, appId }, 'Auto-refreshed surface after app_update');
   }
+  return refreshed;
 }
 
 export function buildCompletionSummary(surfaceType: string | undefined, actionId: string, data?: Record<string, unknown>): string {

package/src/daemon/session-tool-setup.ts

@@ -27,6 +27,7 @@ import {
 } from './session-surfaces.js';
 import type { SurfaceSessionContext } from './session-surfaces.js';
 import { updatePublishedAppDeployment } from '../services/published-app-updater.js';
+import { openAppViaSurface } from '../tools/apps/open-proxy.js';
 import { registerSessionSender } from '../tools/browser/browser-screencast.js';
 import type { ProxyApprovalCallback, ProxyApprovalRequest } from '../tools/network/script-proxy/index.js';
 import { projectSkillTools, type SkillProjectionCache } from './session-skill-tools.js';
@@ -265,13 +266,18 @@ export function createToolExecutor(
       },
     });
 
-    // Auto-refresh workspace surfaces when a persisted app is updated
+    // Auto-refresh workspace surfaces when a persisted app is updated.
+    // If no surface is currently showing the app, auto-open it.
     if (name === 'app_update' && !result.isError) {
       const appId = input.app_id as string | undefined;
       if (appId) {
-        refreshSurfacesForApp(ctx, appId);
+        const refreshed = refreshSurfacesForApp(ctx, appId);
         broadcastToAllClients?.({ type: 'app_files_changed', appId });
         void updatePublishedAppDeployment(appId);
+        if (!refreshed && !ctx.hasNoClient && !ctx.headlessLock) {
+          const resolver = (tn: string, pi: Record<string, unknown>) => surfaceProxyResolver(ctx, tn, pi);
+          void openAppViaSurface(appId, resolver);
+        }
       }
     }
 
@@ -286,14 +292,19 @@ export function createToolExecutor(
       broadcastToAllClients?.({ type: 'tasks_changed' });
     }
 
-    // Auto-refresh workspace surfaces when app files are edited
+    // Auto-refresh workspace surfaces when app files are edited.
+    // If no surface is currently showing the app, auto-open it.
     if ((name === 'app_file_edit' || name === 'app_file_write') && !result.isError) {
       const appId = input.app_id as string | undefined;
       const status = input.status as string | undefined;
       if (appId) {
-        refreshSurfacesForApp(ctx, appId, { fileChange: true, status });
+        const refreshed = refreshSurfacesForApp(ctx, appId, { fileChange: true, status });
         broadcastToAllClients?.({ type: 'app_files_changed', appId });
         void updatePublishedAppDeployment(appId);
+        if (!refreshed && !ctx.hasNoClient && !ctx.headlessLock) {
+          const resolver = (tn: string, pi: Record<string, unknown>) => surfaceProxyResolver(ctx, tn, pi);
+          void openAppViaSurface(appId, resolver);
+        }
       }
     }
 

package/src/home-base/bootstrap.ts

@@ -23,7 +23,7 @@ export interface HomeBaseBootstrapResult {
   created: boolean;
 }
 
-export function bootstrapHomeBaseAppLink(): HomeBaseBootstrapResult {
+export function bootstrapHomeBaseAppLink(): HomeBaseBootstrapResult | null {
   const linked = resolveExistingLink();
   if (linked) {
     return {
@@ -46,6 +46,8 @@ export function bootstrapHomeBaseAppLink(): HomeBaseBootstrapResult {
   }
 
   const seeded = ensurePrebuiltHomeBaseSeeded();
+  if (!seeded) return null;
+
   const next = setHomeBaseAppLink(seeded.appId, 'prebuilt_seed');
   log.info({ appId: next.appId, created: seeded.created }, 'Bootstrapped Home Base app link');
 

package/src/home-base/prebuilt/seed.ts

@@ -6,6 +6,8 @@ import {
   HOME_BASE_PREBUILT_DESCRIPTION_PREFIX,
   isPrebuiltHomeBaseApp,
 } from '../prebuilt-home-base-updater.js';
+// Static import so the JSON is bundled into compiled binaries (avoids ENOENT on $bunfs)
+import seedMetadataJson from './seed-metadata.json' with { type: 'json' };
 
 const log = getLogger('home-base-seed');
 
@@ -26,12 +28,16 @@ function getPrebuiltDir(): string {
 }
 
 function loadSeedMetadata(): SeedMetadata {
-  const raw = readFileSync(join(getPrebuiltDir(), 'seed-metadata.json'), 'utf-8');
-  return JSON.parse(raw) as SeedMetadata;
+  return seedMetadataJson as SeedMetadata;
 }
 
-function loadPrebuiltHtml(): string {
-  return readFileSync(join(getPrebuiltDir(), 'index.html'), 'utf-8');
+export function loadPrebuiltHtml(): string | null {
+  try {
+    return readFileSync(join(getPrebuiltDir(), 'index.html'), 'utf-8');
+  } catch {
+    log.warn('Could not load prebuilt index.html (expected in compiled binary)');
+    return null;
+  }
 }
 
 function buildDescription(metadata: SeedMetadata): string {
@@ -80,7 +86,7 @@ export function getPrebuiltHomeBaseTaskPayload(): PrebuiltHomeBaseTaskPayload {
   };
 }
 
-export function ensurePrebuiltHomeBaseSeeded(): { appId: string; created: boolean } {
+export function ensurePrebuiltHomeBaseSeeded(): { appId: string; created: boolean } | null {
   const existing = findSeededHomeBaseApp();
   if (existing) {
     return { appId: existing.id, created: false };
@@ -88,6 +94,11 @@ export function ensurePrebuiltHomeBaseSeeded(): { appId: string; created: boolea
 
   const metadata = loadSeedMetadata();
   const html = loadPrebuiltHtml();
+  if (html === null) {
+    log.warn('Skipping Home Base seed — prebuilt HTML not available');
+    return null;
+  }
+
   const created = createApp({
     name: metadata.appName,
     description: buildDescription(metadata),

package/src/inbound/public-ingress-urls.ts

@@ -20,14 +20,15 @@
  *   - The assistant's outbound callback URLs (Twilio webhooks, OAuth
  *     redirect URIs, etc.) match the gateway's inbound signature
  *     reconstruction URL.
- *   - Changing the URL in Settings propagates to the gateway on restart,
- *     eliminating Twilio signature mismatch risk.
+ *   - Changing the URL in Settings immediately updates outbound callback
+ *     registration, while the gateway can validate inbound Twilio signatures
+ *     using forwarded public URL headers from tunnels/proxies.
  *
  * All public-facing ingress URL construction is centralized here.
  */
 
 export interface IngressConfig {
-  ingress?: { publicBaseUrl?: string };
+  ingress?: { enabled?: boolean; publicBaseUrl?: string };
 }
 
 /**
@@ -41,9 +42,19 @@ function normalizeUrl(url: string): string {
  * Resolve the canonical public base URL using the precedence chain
  * documented at the top of this module.
  *
- * Throws if no source provides a non-empty value.
+ * When `ingress.enabled` is explicitly `false`, the public ingress is
+ * considered disabled regardless of whether a URL is configured. This
+ * allows the user to toggle ingress off without clearing the URL value.
+ *
+ * Throws if no source provides a non-empty value or if ingress is disabled.
  */
 export function getPublicBaseUrl(config: IngressConfig): string {
+  if (config.ingress?.enabled === false) {
+    throw new Error(
+      'Public ingress is disabled. Enable it in Settings to use public-facing webhooks.',
+    );
+  }
+
   const ingressValue = config.ingress?.publicBaseUrl;
   if (ingressValue) {
     const normalized = normalizeUrl(ingressValue);