vellum 0.2.8 → 0.2.9

package/src/runtime/routes/channel-routes.ts

@@ -42,6 +42,7 @@ export async function handleDeleteConversation(req: Request): Promise<Response>
 export async function handleChannelInbound(
   req: Request,
   processMessage?: MessageProcessor,
+  bearerToken?: string,
 ): Promise<Response> {
   const body = await req.json() as {
     sourceChannel?: string;
@@ -229,6 +230,7 @@ export async function handleChannelInbound(
       metadataHints,
       metadataUxBrief,
       replyCallbackUrl,
+      bearerToken,
     });
   }
 
@@ -250,6 +252,7 @@ interface BackgroundProcessingParams {
   metadataHints: string[];
   metadataUxBrief?: string;
   replyCallbackUrl?: string;
+  bearerToken?: string;
 }
 
 function processChannelMessageInBackground(params: BackgroundProcessingParams): void {
@@ -264,6 +267,7 @@ function processChannelMessageInBackground(params: BackgroundProcessingParams):
     metadataHints,
     metadataUxBrief,
     replyCallbackUrl,
+    bearerToken,
   } = params;
 
   (async () => {
@@ -285,7 +289,7 @@ function processChannelMessageInBackground(params: BackgroundProcessingParams):
       channelDeliveryStore.markProcessed(eventId);
 
       if (replyCallbackUrl) {
-        await deliverReplyViaCallback(conversationId, externalChatId, replyCallbackUrl);
+        await deliverReplyViaCallback(conversationId, externalChatId, replyCallbackUrl, bearerToken);
       }
     } catch (err) {
       log.error({ err, conversationId }, 'Background channel message processing failed');
@@ -298,6 +302,7 @@ async function deliverReplyViaCallback(
   conversationId: string,
   externalChatId: string,
   callbackUrl: string,
+  bearerToken?: string,
 ): Promise<void> {
   const msgs = conversationStore.getMessages(conversationId);
   for (let i = msgs.length - 1; i >= 0; i--) {
@@ -320,7 +325,7 @@ async function deliverReplyViaCallback(
           chatId: externalChatId,
           text: rendered.text || undefined,
           attachments: replyAttachments.length > 0 ? replyAttachments : undefined,
-        });
+        }, bearerToken);
       }
       break;
     }

package/src/runtime/routes/events-routes.ts

@@ -0,0 +1,79 @@
+/**
+ * Route handler for the assistant-events SSE endpoint.
+ *
+ * GET /v1/events?conversationKey=...
+ *
+ * Auth is enforced by RuntimeHttpServer before this handler is called.
+ * Subscribers receive all assistant events scoped to the given conversation.
+ */
+
+import { getOrCreateConversation } from '../../memory/conversation-key-store.js';
+import { assistantEventHub } from '../assistant-event-hub.js';
+import { formatSseFrame } from '../assistant-event.js';
+import type { AssistantEventSubscription } from '../assistant-event-hub.js';
+
+/**
+ * Stream assistant events as Server-Sent Events for a specific conversation.
+ *
+ * Query params:
+ *   conversationKey — required; scopes the stream to one conversation.
+ */
+export function handleSubscribeAssistantEvents(
+  req: Request,
+  url: URL,
+): Response {
+  const conversationKey = url.searchParams.get('conversationKey');
+  if (!conversationKey) {
+    return Response.json({ error: 'conversationKey is required' }, { status: 400 });
+  }
+
+  const mapping = getOrCreateConversation(conversationKey);
+  const encoder = new TextEncoder();
+  let sub: AssistantEventSubscription | null = null;
+
+  // Allow up to 16 queued frames before treating the consumer as stalled.
+  // This absorbs normal token-stream bursts without prematurely closing the
+  // connection, while still shedding genuinely slow clients.
+  const stream = new ReadableStream({
+    start(controller) {
+      // 'self' is the assistantId that RunOrchestrator assigns to all HTTP-run events
+      // (see buildAssistantEvent('self', ...) in run-orchestrator.ts). This endpoint
+      // is part of the HTTP runtime API, so only HTTP-run events are relevant here.
+      // IPC/daemon events use a different assistantId ('default') and reach desktop
+      // clients through a separate channel — they are intentionally excluded.
+      sub = assistantEventHub.subscribe(
+        { assistantId: 'self', sessionId: mapping.conversationId },
+        (event) => {
+          try {
+            // Shed stalled consumers: desiredSize <= 0 means the 16-event buffer
+            // is full and the client isn't draining it.
+            if (controller.desiredSize !== null && controller.desiredSize <= 0) {
+              sub?.dispose();
+              try { controller.close(); } catch { /* already closed */ }
+              return;
+            }
+            controller.enqueue(encoder.encode(formatSseFrame(event)));
+          } catch {
+            sub?.dispose();
+          }
+        },
+      );
+
+      req.signal.addEventListener('abort', () => {
+        sub?.dispose();
+        try { controller.close(); } catch { /* already closed */ }
+      }, { once: true });
+    },
+    cancel() {
+      sub?.dispose();
+    },
+  }, new CountQueuingStrategy({ highWaterMark: 16 }));
+
+  return new Response(stream, {
+    headers: {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      'Connection': 'keep-alive',
+    },
+  });
+}

package/src/runtime/routes/run-routes.ts

@@ -88,6 +88,7 @@ export function handleGetRun(
     status: run.status,
     messageId: run.messageId,
     pendingConfirmation: run.pendingConfirmation,
+    pendingSecret: run.pendingSecret,
     error: run.error,
     createdAt: new Date(run.createdAt).toISOString(),
     updatedAt: new Date(run.updatedAt).toISOString(),
@@ -217,3 +218,45 @@ export async function handleAddTrustRule(
     return Response.json({ error: 'Failed to add trust rule' }, { status: 500 });
   }
 }
+
+export async function handleRunSecret(
+  runId: string,
+  req: Request,
+  runOrchestrator: RunOrchestrator,
+): Promise<Response> {
+  const run = runOrchestrator.getRun(runId);
+  if (!run) {
+    return Response.json({ error: 'Run not found' }, { status: 404 });
+  }
+
+  const body = await req.json() as {
+    value?: string;
+    delivery?: string;
+  };
+
+  const { value, delivery } = body;
+
+  if (delivery !== undefined && delivery !== 'store' && delivery !== 'transient_send') {
+    return Response.json(
+      { error: 'delivery must be "store" or "transient_send"' },
+      { status: 400 },
+    );
+  }
+
+  const result = runOrchestrator.submitSecret(
+    runId,
+    value,
+    delivery as 'store' | 'transient_send' | undefined,
+  );
+  if (result === 'run_not_found') {
+    return Response.json({ error: 'Run not found' }, { status: 404 });
+  }
+  if (result === 'no_pending_secret') {
+    return Response.json(
+      { error: 'No secret pending for this run' },
+      { status: 409 },
+    );
+  }
+
+  return Response.json({ accepted: true });
+}

package/src/runtime/run-orchestrator.ts

@@ -3,11 +3,14 @@
  *
  * A "run" wraps a single agent-loop execution, tracking its state through:
  *   running → needs_confirmation → running → completed | failed
+ *   running → needs_secret       → running → completed | failed
  *
  * When a tool needs permission, the orchestrator intercepts the
  * confirmation_request from the session's prompter and records it in
- * the run store.  The web UI can then poll the run status and submit
- * a decision via the /decision endpoint.
+ * the run store.  Similarly, when a tool needs a secret (e.g.
+ * credential_store prompt), the orchestrator intercepts the
+ * secret_request and records it.  The client can then poll the run
+ * status and submit a decision or secret via the respective endpoints.
  */
 
 import * as runsStore from '../memory/runs-store.js';
@@ -113,11 +116,10 @@ export class RunOrchestrator {
     };
 
 
-    // Hook into session to intercept confirmation_request events.
-    // When the prompter sends a confirmation_request, we record it in the
-    // run store so the web UI can poll and submit a decision.
-    // Do NOT set hasNoClient — run sessions have a client (the HTTP caller)
-    // and confirmations are handled via the /runs/:id/decision endpoint.
+    // Hook into session to intercept confirmation_request and secret_request events.
+    // When the prompter sends one of these, we record it in the run store so
+    // the client can poll and submit a decision/secret via the respective endpoint.
+    // Do NOT set hasNoClient — run sessions have a client (the HTTP caller).
     let lastError: string | null = null;
     session.updateClient((msg: ServerMessage) => {
       if (msg.type === 'confirmation_request') {
@@ -138,6 +140,21 @@ export class RunOrchestrator {
           prompterRequestId: msg.requestId,
           session,
         });
+      } else if (msg.type === 'secret_request') {
+        runsStore.setRunSecret(run.id, {
+          requestId: msg.requestId,
+          service: msg.service,
+          field: msg.field,
+          label: msg.label,
+          description: msg.description,
+          placeholder: msg.placeholder,
+          purpose: msg.purpose,
+          allowOneTimeSend: msg.allowOneTimeSend,
+        });
+        this.pending.set(run.id, {
+          prompterRequestId: msg.requestId,
+          session,
+        });
       }
       // Mirror every outbound message to the assistant-events hub so SSE
       // subscribers receive the same payload parity as IPC clients.
@@ -236,4 +253,44 @@ export class RunOrchestrator {
     // the client doesn't mistakenly treat the decision as accepted.
     return 'no_pending_decision';
   }
+
+  /**
+   * Submit a secret value for a pending secret request.
+   *
+   * Returns:
+   * - `'applied'`           – secret was forwarded to the session
+   * - `'run_not_found'`     – no run exists with the given ID
+   * - `'no_pending_secret'` – run exists but is not awaiting a secret
+   */
+  submitSecret(
+    runId: string,
+    value?: string,
+    delivery?: 'store' | 'transient_send',
+  ): 'applied' | 'run_not_found' | 'no_pending_secret' {
+    const pendingState = this.pending.get(runId);
+    if (pendingState) {
+      runsStore.clearRunSecret(runId);
+      pendingState.session.handleSecretResponse(
+        pendingState.prompterRequestId,
+        value,
+        delivery,
+      );
+      this.pending.delete(runId);
+      return 'applied';
+    }
+
+    const run = runsStore.getRun(runId);
+    if (!run) return 'run_not_found';
+
+    if (run.status === 'needs_secret') {
+      runsStore.failRun(runId, 'Secret prompter timed out (no active handler)');
+      return 'applied';
+    }
+
+    if (run.status === 'completed' || run.status === 'failed') {
+      return 'applied';
+    }
+
+    return 'no_pending_secret';
+  }
 }

package/src/security/oauth-callback-registry.ts

@@ -19,6 +19,15 @@ export function registerPendingCallback(
   reject: (error: Error) => void,
   ttlMs = DEFAULT_TTL_MS,
 ): void {
+  // Clear any existing entry for this state to prevent timer leaks and
+  // cross-callback timeouts when the same state is registered twice.
+  const existing = pendingCallbacks.get(state);
+  if (existing) {
+    clearTimeout(existing.timer);
+    existing.reject(new Error('OAuth callback superseded by new registration'));
+    pendingCallbacks.delete(state);
+  }
+
   const timer = setTimeout(() => {
     const entry = pendingCallbacks.get(state);
     if (entry) {
@@ -51,6 +60,7 @@ export function consumeCallbackError(state: string, error: string): boolean {
 export function clearAllCallbacks(): void {
   for (const entry of pendingCallbacks.values()) {
     clearTimeout(entry.timer);
+    entry.reject(new Error('OAuth callback registry cleared'));
   }
   pendingCallbacks.clear();
 }

package/src/security/oauth2.ts

@@ -144,19 +144,18 @@ async function exchangeCodeForTokens(
 
 /**
  * Determine which callback transport to use when not explicitly specified.
- * Uses gateway if ingress.publicBaseUrl is configured, otherwise loopback.
+ * Uses gateway if a public base URL is configured (ingress.publicBaseUrl or
+ * INGRESS_PUBLIC_BASE_URL), otherwise loopback.
  */
 function detectTransport(): 'loopback' | 'gateway' {
   try {
-    // Dynamic import avoided — loadConfig is synchronous and already used elsewhere.
     const { loadConfig } = require('../config/loader.js') as typeof import('../config/loader.js');
+    const { getPublicBaseUrl } = require('../inbound/public-ingress-urls.js') as typeof import('../inbound/public-ingress-urls.js');
     const appConfig = loadConfig();
-    if (appConfig.ingress?.publicBaseUrl) {
-      return 'gateway';
-    }
+    getPublicBaseUrl(appConfig); // throws if no public URL configured
+    return 'gateway';
   } catch {
-    // Config loading failed — fall back to loopback
-    log.debug('Config not available for transport auto-detection, defaulting to loopback');
+    log.debug('No public base URL configured for transport auto-detection, defaulting to loopback');
   }
   return 'loopback';
 }
@@ -319,6 +318,41 @@ export async function startOAuth2Flow(
   const codeChallenge = generateCodeChallenge(codeVerifier);
   const state = generateState();
 
+  // In gateway_only mode, enforce gateway transport and require a public ingress URL
+  let ingressMode: string | undefined;
+  try {
+    const { loadConfig } = require('../config/loader.js') as typeof import('../config/loader.js');
+    ingressMode = loadConfig().ingress.mode;
+  } catch {
+    // Fail closed: if config can't be loaded (e.g., malformed config.json), default to the
+    // most restrictive mode to prevent loopback fallback from creating a fail-open path.
+    log.warn('Failed to load config for OAuth ingress mode detection; defaulting to gateway_only (fail closed)');
+    ingressMode = 'gateway_only';
+  }
+
+  if (ingressMode === 'gateway_only') {
+    // Verify a public ingress URL is configured; fail fast with actionable error if not
+    let hasPublicUrl = false;
+    try {
+      const { loadConfig } = require('../config/loader.js') as typeof import('../config/loader.js');
+      const { getPublicBaseUrl } = require('../inbound/public-ingress-urls.js') as typeof import('../inbound/public-ingress-urls.js');
+      getPublicBaseUrl(loadConfig());
+      hasPublicUrl = true;
+    } catch {
+      // No public URL configured
+    }
+
+    if (!hasPublicUrl) {
+      throw new Error(
+        'OAuth requires a public ingress URL in gateway-only mode. Set ingress.publicBaseUrl or INGRESS_PUBLIC_BASE_URL so OAuth callbacks can route through the gateway.',
+      );
+    }
+
+    // In gateway_only mode, always use gateway transport — never fall back to loopback
+    log.debug({ transport: 'gateway' }, 'OAuth2 flow starting (gateway_only mode)');
+    return runGatewayFlow(config, callbacks, codeVerifier, codeChallenge, state);
+  }
+
   const transport = options?.callbackTransport ?? detectTransport();
   log.debug({ transport }, 'OAuth2 flow starting');
 

package/src/subagent/manager.ts

@@ -57,6 +57,7 @@ export interface SubagentNotificationInfo {
   label: string;
   status: 'completed' | 'failed' | 'aborted';
   error?: string;
+  conversationId?: string;
 }
 
 export type ParentNotifyCallback = (
@@ -299,7 +300,7 @@ export class SubagentManager {
             managed.state.config.parentSessionId,
             message,
             managed.parentSendToClient,
-            { subagentId, label, status: 'aborted' },
+            { subagentId, label, status: 'aborted', conversationId: managed.state.conversationId },
           );
         } catch (err) {
           log.error({ subagentId, err }, 'Failed to notify parent about abort');
@@ -497,6 +498,7 @@ export class SubagentManager {
       subagentId: config.id,
       label: config.label,
       status: outcome,
+      conversationId: managed.state.conversationId,
       ...(outcome === 'failed' ? { error: managed.state.error ?? 'Unknown error' } : {}),
     };
 

package/src/tools/tasks/work-item-run.ts

@@ -0,0 +1,78 @@
+import type { ToolContext, ToolExecutionResult } from '../types.js';
+import { getWorkItem, listWorkItems, identifyEntityById, buildWorkItemMismatchError } from '../../work-items/work-item-store.js';
+import { runWorkItemInBackground } from '../../work-items/work-item-runner.js';
+import { getTask } from '../../tasks/task-store.js';
+
+export async function executeTaskQueueRun(
+  input: Record<string, unknown>,
+  _context: ToolContext,
+): Promise<ToolExecutionResult> {
+  const workItemId = input.work_item_id as string | undefined;
+  const taskName = input.task_name as string | undefined;
+  const title = input.title as string | undefined;
+
+  if (!workItemId && !taskName && !title) {
+    return {
+      content: 'Error: Provide work_item_id, task_name, or title to identify the task to run.',
+      isError: true,
+    };
+  }
+
+  try {
+    let resolvedId: string | undefined;
+
+    if (workItemId) {
+      const item = getWorkItem(workItemId);
+      if (!item) {
+        const entity = identifyEntityById(workItemId);
+        if (entity.type === 'task_template') {
+          return {
+            content: `Error: "${workItemId}" is a task template ID, not a work item. Use task_list_show to find the work item ID.`,
+            isError: true,
+          };
+        }
+        return { content: `Error: No work item found with ID "${workItemId}".`, isError: true };
+      }
+      resolvedId = item.id;
+    } else {
+      // Search by task_name or title among active work items
+      const needle = (taskName ?? title)!.toLowerCase();
+      const allItems = listWorkItems();
+      const activeItems = allItems.filter((i) => !['archived', 'done'].includes(i.status));
+      const matches = activeItems.filter((i) => i.title.toLowerCase().includes(needle));
+
+      if (matches.length === 0) {
+        return {
+          content: `Error: No active work item matching "${taskName ?? title}". Use task_list_show to see your task queue.`,
+          isError: true,
+        };
+      }
+
+      if (matches.length > 1) {
+        const lines = [`Multiple work items match "${taskName ?? title}". Please specify by ID:`, ''];
+        for (const m of matches) {
+          lines.push(`- ${m.title} (ID: ${m.id}, status: ${m.status})`);
+        }
+        return { content: lines.join('\n'), isError: true };
+      }
+
+      resolvedId = matches[0].id;
+    }
+
+    const result = runWorkItemInBackground(resolvedId);
+
+    if (!result.success) {
+      return { content: `Error: ${result.error}`, isError: true };
+    }
+
+    const item = getWorkItem(resolvedId)!;
+    const task = getTask(item.taskId);
+    return {
+      content: `Started running task "${item.title}"${task ? ` (template: ${task.title})` : ''}. It will execute in the background. Use task_list_show to check progress.`,
+      isError: false,
+    };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { content: `Error: ${msg}`, isError: true };
+  }
+}

package/src/util/platform.ts

@@ -124,7 +124,7 @@ export function getTCPPort(): number {
  *
  * The flag-file check makes it easy to enable TCP in dev without restarting
  * the shell: `touch ~/.vellum/tcp-enabled && kill -USR1 <daemon-pid>`.
- * The macOS DaemonLauncher also sets the env var for bundled-binary deployments.
+ * The macOS CLI (AssistantCli) also sets the env var for bundled-binary deployments.
  */
 export function isTCPEnabled(): boolean {
   const override = process.env.VELLUM_DAEMON_TCP_ENABLED?.trim();

package/src/work-items/work-item-runner.ts

@@ -0,0 +1,171 @@
+/**
+ * Module-level registry for running work items from tool context.
+ *
+ * The daemon server registers its `getOrCreateSession` and `broadcast`
+ * callbacks at startup. Tool implementations can then trigger async
+ * work item execution without needing direct access to HandlerContext.
+ */
+
+import { getLogger } from '../util/logger.js';
+import { getWorkItem, updateWorkItem, type WorkItemStatus } from './work-item-store.js';
+import { getTask } from '../tasks/task-store.js';
+import { runTask } from '../tasks/task-runner.js';
+import { sanitizeToolList, getRegisteredToolNames } from '../tasks/tool-sanitizer.js';
+import type { Session } from '../daemon/session.js';
+import type { ServerMessage } from '../daemon/ipc-protocol.js';
+
+const log = getLogger('work-item-runner');
+
+// ── Daemon callback registry ─────────────────────────────────────────
+
+interface DaemonCallbacks {
+  getOrCreateSession: (conversationId: string) => Promise<Session>;
+  broadcast: (msg: ServerMessage) => void;
+}
+
+let _callbacks: DaemonCallbacks | null = null;
+
+export function registerDaemonCallbacks(callbacks: DaemonCallbacks): void {
+  _callbacks = callbacks;
+}
+
+// ── Public API ───────────────────────────────────────────────────────
+
+function broadcastWorkItemStatus(broadcast: (msg: ServerMessage) => void, id: string): void {
+  const item = getWorkItem(id);
+  if (item) {
+    broadcast({
+      type: 'work_item_status_changed',
+      item: {
+        id: item.id,
+        taskId: item.taskId,
+        title: item.title,
+        status: item.status,
+        lastRunId: item.lastRunId,
+        lastRunConversationId: item.lastRunConversationId,
+        lastRunStatus: item.lastRunStatus,
+        updatedAt: item.updatedAt,
+      },
+    } as ServerMessage);
+  }
+}
+
+export interface RunWorkItemResult {
+  success: boolean;
+  error?: string;
+  errorCode?: string;
+}
+
+/**
+ * Run a work item in the background. Returns immediately after validation.
+ * The actual execution happens asynchronously.
+ *
+ * When called from a chat tool (e.g. Telegram), required tools are
+ * auto-approved since the user explicitly requested execution.
+ */
+export function runWorkItemInBackground(workItemId: string): RunWorkItemResult {
+  if (!_callbacks) {
+    return { success: false, error: 'Daemon callbacks not registered', errorCode: 'not_initialized' };
+  }
+
+  const workItem = getWorkItem(workItemId);
+  if (!workItem) {
+    return { success: false, error: 'Work item not found', errorCode: 'not_found' };
+  }
+
+  if (workItem.status === 'running') {
+    return { success: false, error: 'Work item is already running', errorCode: 'already_running' };
+  }
+
+  const NON_RUNNABLE_STATUSES: readonly string[] = ['archived'];
+  if (NON_RUNNABLE_STATUSES.includes(workItem.status)) {
+    return { success: false, error: `Work item has status '${workItem.status}' and cannot be run`, errorCode: 'invalid_status' };
+  }
+
+  const task = getTask(workItem.taskId);
+  if (!task) {
+    return { success: false, error: `Associated task not found: ${workItem.taskId}`, errorCode: 'no_task' };
+  }
+
+  // Resolve required tools
+  let requiredTools: string[];
+  if (workItem.requiredTools !== null && workItem.requiredTools !== undefined) {
+    requiredTools = sanitizeToolList(JSON.parse(workItem.requiredTools));
+  } else {
+    requiredTools = task.requiredTools
+      ? sanitizeToolList(JSON.parse(task.requiredTools))
+      : getRegisteredToolNames();
+  }
+
+  // Auto-approve all required tools for chat-initiated runs.
+  // The user explicitly asked to run the task, so we treat that as consent.
+  const approvedTools = requiredTools;
+
+  // Set status to running
+  updateWorkItem(workItemId, { status: 'running' });
+
+  const { getOrCreateSession, broadcast } = _callbacks;
+
+  // Broadcast the running state
+  broadcastWorkItemStatus(broadcast, workItemId);
+  broadcast({ type: 'tasks_changed' } as ServerMessage);
+
+  // Execute asynchronously
+  let session: Awaited<ReturnType<typeof getOrCreateSession>> | null = null;
+  void (async () => {
+    try {
+      const result = await runTask(
+        { taskId: workItem.taskId, workingDir: process.cwd(), approvedTools },
+        async (conversationId, message, taskRunId) => {
+          if (!session) {
+            updateWorkItem(workItemId, { lastRunConversationId: conversationId });
+            session = await getOrCreateSession(conversationId);
+
+            broadcast({
+              type: 'task_run_thread_created',
+              conversationId,
+              workItemId,
+              title: workItem.title,
+            } as ServerMessage);
+            (session as unknown as { taskRunId?: string }).taskRunId = taskRunId;
+            (session as unknown as { headlessLock: boolean }).headlessLock = true;
+          }
+          await session.processMessage(message, [], (event) => {
+            broadcast(event);
+          });
+        },
+      );
+
+      if (session) {
+        (session as unknown as { headlessLock: boolean }).headlessLock = false;
+      }
+
+      const current = getWorkItem(workItemId);
+      if (current?.status !== 'cancelled') {
+        const finalStatus: WorkItemStatus = result.status === 'completed' ? 'awaiting_review' : 'failed';
+        updateWorkItem(workItemId, {
+          status: finalStatus,
+          lastRunId: result.taskRunId,
+          lastRunConversationId: result.conversationId,
+          lastRunStatus: result.status,
+        });
+      }
+
+      broadcastWorkItemStatus(broadcast, workItemId);
+      broadcast({ type: 'tasks_changed' } as ServerMessage);
+    } catch (err) {
+      if (session) {
+        (session as unknown as { headlessLock: boolean }).headlessLock = false;
+      }
+      log.error({ err, workItemId }, 'work item background run failed');
+      updateWorkItem(workItemId, {
+        status: 'failed',
+        lastRunStatus: 'failed',
+      });
+      broadcastWorkItemStatus(broadcast, workItemId);
+      broadcast({ type: 'tasks_changed' } as ServerMessage);
+    }
+  })();
+
+  return { success: true };
+}