@vellumai/assistant 0.10.3-dev.202606301846.839df2b → 0.10.3-dev.202606301940.da6000c

package/openapi.yaml

@@ -17916,6 +17916,44 @@ paths:
                           additionalProperties: false
                         backgroundToolNotification:
                           type: boolean
+                        backgroundToolCompletion:
+                          type: object
+                          properties:
+                            id:
+                              type: string
+                            toolName:
+                              type: string
+                            conversationId:
+                              type: string
+                            command:
+                              type: string
+                            startedAt:
+                              type: number
+                            status:
+                              type: string
+                              enum:
+                                - completed
+                                - failed
+                                - cancelled
+                            exitCode:
+                              anyOf:
+                                - type: number
+                                - type: "null"
+                            output:
+                              type: string
+                            completedAt:
+                              type: number
+                          required:
+                            - id
+                            - toolName
+                            - conversationId
+                            - command
+                            - startedAt
+                            - status
+                            - exitCode
+                            - output
+                            - completedAt
+                          additionalProperties: false
                         slackMessage:
                           type: object
                           properties:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.10.3-dev.202606301846.839df2b",
+  "version": "0.10.3-dev.202606301940.da6000c",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/background-shell-bash.test.ts

@@ -189,6 +189,10 @@ describe("bash tool background mode", () => {
     // Command stdout is fenced as untrusted output, not inlined in the hint.
     expect(wakeCall.untrustedOutput?.content).toContain("bg_output_12345");
     expect(wakeCall.untrustedOutput?.source).toBe("tool_result");
+    // Durable completion record stamped onto the persisted wake.
+    expect(wakeCall.backgroundToolCompletion?.id).toBe("bg-test1234");
+    expect(wakeCall.backgroundToolCompletion?.status).toBe("completed");
+    expect(wakeCall.backgroundToolCompletion?.exitCode).toBe(0);
   });
 
   test("failing background process delivers an error hint via wake", async () => {
@@ -210,6 +214,9 @@ describe("bash tool background mode", () => {
     expect(wakeCall.hint).toContain("bg-test1234");
     // The command fails with exit code 1, so the hint should reflect failure
     expect(wakeCall.hint).toContain("exit=1");
+    expect(wakeCall.backgroundToolCompletion?.id).toBe("bg-test1234");
+    expect(wakeCall.backgroundToolCompletion?.status).toBe("failed");
+    expect(wakeCall.backgroundToolCompletion?.exitCode).toBe(1);
   });
 
   test("cancelled background process wakes with the cancellation, not a completed result", async () => {
@@ -234,6 +241,8 @@ describe("bash tool background mode", () => {
     expect(wakeCall.hint).toContain("cancelled");
     expect(wakeCall.hint).not.toContain("completed");
     expect(wakeCall.untrustedOutput?.content).toContain("cancelled");
+    expect(wakeCall.backgroundToolCompletion?.id).toBe("bg-test1234");
+    expect(wakeCall.backgroundToolCompletion?.status).toBe("cancelled");
   });
 
   test("foreground mode still works when background is not set", async () => {

package/src/__tests__/background-shell-host-bash.test.ts

@@ -118,6 +118,7 @@ mock.module("../daemon/host-bash-proxy.js", () => ({
 // Import under test — MUST come after mock.module calls.
 // ---------------------------------------------------------------------------
 
+import type { CompletedBackgroundTool } from "../tools/background-tool-registry.js";
 import { hostShellTool } from "../tools/host-terminal/host-shell.js";
 import type { ToolContext, ToolExecutionResult } from "../tools/types.js";
 
@@ -258,6 +259,11 @@ describe("host_bash background mode — proxy path", () => {
       maxChars: 40_000,
     });
     expect(wakeCall.source).toBe("background-tool");
+    const completion =
+      wakeCall.backgroundToolCompletion as CompletedBackgroundTool;
+    expect(completion.id).toBe("bg-test-0001");
+    expect(completion.status).toBe("completed");
+    expect(completion.exitCode).toBeNull();
   });
 
   test("calls wakeAgentForOpportunity on proxy error result", async () => {
@@ -398,6 +404,11 @@ describe("host_bash background mode — direct execution path", () => {
     expect((wakeCall.untrustedOutput as { content: string }).content).toContain(
       "hello world",
     );
+    const completion =
+      wakeCall.backgroundToolCompletion as CompletedBackgroundTool;
+    expect(completion.id).toBe("bg-test-0001");
+    expect(completion.status).toBe("completed");
+    expect(completion.exitCode).toBe(0);
   });
 
   test("calls wakeAgentForOpportunity with error hint on non-zero exit", async () => {

package/src/__tests__/list-messages-background-tool-completion.test.ts

@@ -0,0 +1,141 @@
+/**
+ * Tests for handleListMessages background-tool completion projection.
+ *
+ * A backgrounded bash/host_bash run posts a `<background_event
+ * source="background-tool">` wake on completion, stamped with
+ * `metadata.backgroundToolCompletion`. The history projection must surface
+ * that structured record (and the `backgroundToolNotification` flag) so the
+ * web can rebuild a terminal inline card after a daemon restart.
+ */
+
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+mock.module("../util/logger.js", () => ({
+  getLogger: () =>
+    new Proxy({} as Record<string, unknown>, {
+      get: () => () => {},
+    }),
+}));
+
+mock.module("../config/loader.js", () => ({
+  getConfig: () => ({
+    ui: {},
+    model: "test",
+    provider: "test",
+    memory: { enabled: false },
+    rateLimit: { maxRequestsPerMinute: 0 },
+  }),
+}));
+
+import { ConversationMessageSchema } from "../api/responses/conversation-message.js";
+import {
+  addMessage,
+  createConversation,
+} from "../persistence/conversation-crud.js";
+import { getDb } from "../persistence/db-connection.js";
+import { initializeDb } from "../persistence/db-init.js";
+import { handleListMessages } from "../runtime/routes/conversation-routes.js";
+
+await initializeDb();
+
+function resetTables() {
+  const db = getDb();
+  db.run("DELETE FROM message_attachments");
+  db.run("DELETE FROM attachments");
+  db.run("DELETE FROM messages");
+  db.run("DELETE FROM conversations");
+}
+
+interface ProjectedMessage {
+  role: string;
+  backgroundToolNotification?: boolean;
+  backgroundToolCompletion?: Record<string, unknown>;
+}
+
+describe("handleListMessages background-tool completion projection", () => {
+  beforeEach(resetTables);
+
+  test("projects backgroundToolCompletion from the wake row metadata", async () => {
+    const conv = createConversation();
+    await addMessage(
+      conv.id,
+      "user",
+      JSON.stringify([{ type: "text", text: "run a long command" }]),
+    );
+
+    const completion = {
+      id: "bg-1",
+      toolName: "bash",
+      conversationId: conv.id,
+      command: "sleep 5 && echo done",
+      startedAt: 1000,
+      status: "completed" as const,
+      exitCode: 0,
+      output: "done\n",
+      completedAt: 2000,
+    };
+    // Mirror persistWakeTriggerMessage: a user-role
+    // `<background_event source="background-tool">` row carrying the structured
+    // completion. Not flagged `hidden`; the client suppresses it from the
+    // transcript via `backgroundToolNotification`.
+    await addMessage(
+      conv.id,
+      "user",
+      JSON.stringify([
+        {
+          type: "text",
+          text: '<background_event source="background-tool">Background command completed (id=bg-1, exit=0):</background_event>',
+        },
+      ]),
+      {
+        metadata: {
+          kind: "background-event",
+          backgroundEventSource: "background-tool",
+          automated: true,
+          backgroundToolCompletion: completion,
+        },
+      },
+    );
+
+    const response = handleListMessages({
+      queryParams: { conversationId: conv.id },
+    }) as { messages: ProjectedMessage[] };
+
+    // Every projected message validates against the wire schema.
+    for (const message of response.messages) {
+      expect(() => ConversationMessageSchema.parse(message)).not.toThrow();
+    }
+
+    const wakeRow = response.messages.find(
+      (m) => m.backgroundToolCompletion !== undefined,
+    );
+    expect(wakeRow).toBeDefined();
+    expect(wakeRow?.backgroundToolNotification).toBe(true);
+    expect(wakeRow?.backgroundToolCompletion).toEqual(completion);
+  });
+
+  test("omits backgroundToolCompletion when the row carries no completion metadata", async () => {
+    const conv = createConversation();
+    await addMessage(
+      conv.id,
+      "user",
+      JSON.stringify([{ type: "text", text: "hello" }]),
+    );
+    await addMessage(
+      conv.id,
+      "assistant",
+      JSON.stringify([{ type: "text", text: "hi there" }]),
+    );
+
+    const response = handleListMessages({
+      queryParams: { conversationId: conv.id },
+    }) as { messages: ProjectedMessage[] };
+
+    expect(response.messages).toHaveLength(2);
+    for (const message of response.messages) {
+      expect(message.backgroundToolCompletion).toBeUndefined();
+      expect(message.backgroundToolNotification).toBeUndefined();
+      expect(() => ConversationMessageSchema.parse(message)).not.toThrow();
+    }
+  });
+});

package/src/api/index.ts

@@ -404,6 +404,7 @@ export {
   DictationRequestSchema,
 } from "./requests/dictation.js";
 export {
+  type BackgroundToolCompletion,
   type ConversationAttachmentBlock,
   ConversationAttachmentBlockSchema,
   type ConversationContentBlock,

package/src/api/responses/conversation-message.ts

@@ -296,6 +296,29 @@ export type ConversationAcpNotification = z.infer<
   typeof ConversationAcpNotificationSchema
 >;
 
+// ---------------------------------------------------------------------------
+// Background-tool completion
+// ---------------------------------------------------------------------------
+
+/** Structured terminal record of a backgrounded bash/host_bash run, carrying
+ *  everything a web `BackgroundTaskEntry` needs to rebuild a completed inline
+ *  card from history. Mirrors the `background_tool_completed` SSE event plus
+ *  the registry fields (`toolName`, `command`, `startedAt`). */
+export const BackgroundToolCompletionSchema = z.object({
+  id: z.string(),
+  toolName: z.string(),
+  conversationId: z.string(),
+  command: z.string(),
+  startedAt: z.number(),
+  status: z.enum(["completed", "failed", "cancelled"]),
+  exitCode: z.number().nullable(),
+  output: z.string(),
+  completedAt: z.number(),
+});
+export type BackgroundToolCompletion = z.infer<
+  typeof BackgroundToolCompletionSchema
+>;
+
 // ---------------------------------------------------------------------------
 // Slack message envelope
 // ---------------------------------------------------------------------------
@@ -549,6 +572,12 @@ export const ConversationMessageSchema = z.object({
    *  notifications, the row stays in state (the LLM reads it) but is filtered
    *  from the rendered transcript — the inline card carries the status. */
   backgroundToolNotification: z.boolean().optional(),
+  /** Structured completion of a backgrounded bash/host_bash run, stamped on the
+   *  same persisted background-event wake row as `backgroundToolNotification`.
+   *  Lets the web reconstruct a terminal inline card after a daemon restart
+   *  (the in-memory completed ring does not survive restarts). `id` equals the
+   *  spawning tool call's `{backgrounded,id}` id. */
+  backgroundToolCompletion: BackgroundToolCompletionSchema.optional(),
   slackMessage: ConversationSlackMessageSchema.optional(),
   /**
    * Queue state for a user message that is still waiting in the daemon's

package/src/daemon/__tests__/abort-null-controller.test.ts

@@ -0,0 +1,167 @@
+/**
+ * Abort contract when there is no live controller to signal.
+ *
+ * `abortConversation` signals `ctx.abortController?.abort()` and otherwise
+ * defers clearing the `processing` flag to the in-flight turn's `finally`.
+ * That deferral is only safe while a turn is actually live to reach its
+ * `finally`. The agent-loop `finally` nulls `abortController` *before* it
+ * clears the flag, and some paths set `processing` without ever installing a
+ * controller — so a conversation can be `isProcessing() === true` with a null
+ * `abortController`. In that state the old `?.abort()` was a silent no-op and
+ * nothing ever cleared the flag: every later submit was rejected with
+ * "already processing" and Stop did nothing.
+ *
+ * This pins the fix: when asked to abort while processing with no live
+ * controller, `abortConversation` force-clears the flag itself; when a
+ * controller IS live, it signals it and leaves the flag to the turn.
+ */
+import { describe, expect, mock, test } from "bun:test";
+
+// `conversation-lifecycle` transitively imports the messaging markdown
+// renderers, which pull in `hast`/`mdast`/`remark`/`unified`. Those packages
+// are declared in `assistant/package.json` but absent from this sandbox's
+// partial node_modules install (CI has the full set). `abortConversation`
+// never touches message rendering, so stub these leaf modules — the only ones
+// importing the missing packages — with no-op named exports so the import
+// graph resolves. Bun validates named imports statically, hence the explicit
+// keys rather than a Proxy.
+mock.module("../../messaging/content/parse.js", () => ({
+  parseMarkdown: () => ({}),
+}));
+mock.module("../../messaging/providers/slack/render.js", () => ({
+  renderSlackBlocks: () => undefined,
+  renderSlack: () => [],
+}));
+mock.module("../../messaging/providers/telegram-bot/render.js", () => ({
+  renderTelegramHtml: () => undefined,
+}));
+
+const { abortConversation } = await import("../conversation-lifecycle.js");
+import type { AbortContext } from "../conversation-lifecycle.js";
+
+interface Harness {
+  ctx: AbortContext;
+  setProcessingCalls: boolean[];
+  prompterDisposed: () => boolean;
+  secretPrompterDisposed: () => boolean;
+  queueClearedCount: () => number;
+}
+
+function makeContext(opts: {
+  processing: boolean;
+  controller: AbortController | null;
+}): Harness {
+  let processing = opts.processing;
+  const setProcessingCalls: boolean[] = [];
+  let prompterDisposed = false;
+  let secretPrompterDisposed = false;
+  let queueCleared = 0;
+
+  const ctx = {
+    conversationId: "abort-null-controller-test",
+    isProcessing: () => processing,
+    setProcessing: (value: boolean) => {
+      setProcessingCalls.push(value);
+      processing = value;
+    },
+    abortController: opts.controller,
+    prompter: {
+      dispose: () => {
+        prompterDisposed = true;
+      },
+    },
+    secretPrompter: {
+      dispose: () => {
+        secretPrompterDisposed = true;
+      },
+    },
+    pendingSurfaceActions: new Map(),
+    surfaceActionRequestIds: new Set(),
+    surfaceState: new Map(),
+    accumulatedSurfaceState: new Map(),
+    queue: {
+      clear: () => {
+        queueCleared += 1;
+      },
+      [Symbol.iterator]: function* () {
+        // no queued messages
+      },
+    },
+  } as unknown as AbortContext;
+
+  return {
+    ctx,
+    setProcessingCalls,
+    prompterDisposed: () => prompterDisposed,
+    secretPrompterDisposed: () => secretPrompterDisposed,
+    queueClearedCount: () => queueCleared,
+  };
+}
+
+describe("abortConversation", () => {
+  test("force-clears the flag when processing with no live controller", () => {
+    // GIVEN a conversation flagged processing but with no controller to signal
+    const h = makeContext({ processing: true, controller: null });
+
+    // WHEN an abort is requested
+    abortConversation(h.ctx);
+
+    // THEN the flag is force-cleared so the conversation is no longer wedged
+    expect(h.setProcessingCalls).toContain(false);
+    expect(h.ctx.isProcessing()).toBe(false);
+    // AND the rest of the teardown still ran
+    expect(h.prompterDisposed()).toBe(true);
+    expect(h.secretPrompterDisposed()).toBe(true);
+    expect(h.queueClearedCount()).toBe(1);
+  });
+
+  test("signals a live controller and defers the flag to the turn's finally", () => {
+    // GIVEN a conversation with a live, un-aborted controller
+    const controller = new AbortController();
+    const h = makeContext({ processing: true, controller });
+
+    // WHEN an abort is requested
+    abortConversation(h.ctx);
+
+    // THEN the controller is signalled
+    expect(controller.signal.aborted).toBe(true);
+    // AND the flag is NOT force-cleared here — the turn's `finally` owns that
+    expect(h.setProcessingCalls).not.toContain(false);
+    expect(h.ctx.isProcessing()).toBe(true);
+    // AND the shared teardown still ran
+    expect(h.prompterDisposed()).toBe(true);
+    expect(h.queueClearedCount()).toBe(1);
+  });
+
+  test("propagates the abort reason to the live controller", () => {
+    // GIVEN a live controller and an explicit abort reason
+    const controller = new AbortController();
+    const h = makeContext({ processing: true, controller });
+    let observedReason: unknown;
+    controller.signal.addEventListener("abort", () => {
+      observedReason = controller.signal.reason;
+    });
+
+    // WHEN aborting with no explicit reason (a default reason is synthesized)
+    abortConversation(h.ctx);
+
+    // THEN the controller's reason carries the tagged AbortReason
+    expect(observedReason).toBeDefined();
+    expect((observedReason as { kind?: string }).kind).toBe(
+      "preempted_by_new_message",
+    );
+  });
+
+  test("is a no-op when the conversation is not processing", () => {
+    // GIVEN a conversation that is not processing
+    const h = makeContext({ processing: false, controller: null });
+
+    // WHEN an abort is requested
+    abortConversation(h.ctx);
+
+    // THEN nothing is torn down and the flag is never touched
+    expect(h.setProcessingCalls).toEqual([]);
+    expect(h.prompterDisposed()).toBe(false);
+    expect(h.queueClearedCount()).toBe(0);
+  });
+});

package/src/daemon/__tests__/wake-conversation-ops-completion.test.ts

@@ -0,0 +1,107 @@
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+import { makeMockLogger } from "../../__tests__/helpers/mock-logger.js";
+
+mock.module("../../util/logger.js", () => ({
+  getLogger: () => makeMockLogger(),
+}));
+
+// persistWakeTriggerMessage syncs each row to the disk view and publishes a
+// sync invalidation; stub both so this unit test stays a pure DB round-trip
+// without touching the filesystem or the event hub.
+mock.module("../../persistence/conversation-disk-view.js", () => ({
+  syncMessageToDisk: () => {},
+}));
+mock.module("../../runtime/sync/resource-sync-events.js", () => ({
+  publishConversationMessagesChanged: () => {},
+}));
+
+import {
+  createConversation,
+  getMessages,
+} from "../../persistence/conversation-crud.js";
+import { initializeDb } from "../../persistence/db-init.js";
+import type { Message } from "../../providers/types.js";
+import type { CompletedBackgroundTool } from "../../tools/background-tool-registry.js";
+import type { Conversation } from "../conversation.js";
+import { persistWakeTriggerMessage } from "../wake-conversation-ops.js";
+
+await initializeDb();
+
+/** Minimal Conversation stub exercising only the fields the function reads. */
+function makeConversationStub(conversationId: string): Conversation {
+  return {
+    conversationId,
+    trustContext: undefined,
+    getTurnChannelContext: () => null,
+    getTurnInterfaceContext: () => null,
+  } as unknown as Conversation;
+}
+
+function triggerMessage(): Message {
+  return {
+    role: "user",
+    content: [
+      {
+        type: "text",
+        text: '<background_event source="background-tool">Background command completed (id=bg-1, exit=0):</background_event>',
+      },
+    ],
+  };
+}
+
+function readMetadata(conversationId: string): Record<string, unknown> {
+  const rows = getMessages(conversationId);
+  expect(rows.length).toBe(1);
+  const raw = rows[0]?.metadata;
+  expect(raw).toBeTruthy();
+  return JSON.parse(raw as string) as Record<string, unknown>;
+}
+
+describe("persistWakeTriggerMessage backgroundToolCompletion", () => {
+  let conversationId: string;
+
+  beforeEach(() => {
+    conversationId = createConversation("wake-completion-test").id;
+  });
+
+  test("round-trips a completion onto the persisted metadata", async () => {
+    const completion: CompletedBackgroundTool = {
+      id: "bg-1",
+      toolName: "bash",
+      conversationId,
+      command: "sleep 1 && echo done",
+      startedAt: 1_700_000_000_000,
+      status: "completed",
+      exitCode: 0,
+      output: "done\n",
+      completedAt: 1_700_000_001_000,
+    };
+
+    await persistWakeTriggerMessage(
+      makeConversationStub(conversationId),
+      triggerMessage(),
+      "background-tool",
+      completion,
+    );
+
+    const metadata = readMetadata(conversationId);
+    expect(metadata.backgroundToolCompletion).toEqual(completion);
+    // Existing wake-trigger metadata is unaffected.
+    expect(metadata.kind).toBe("background-event");
+    expect(metadata.backgroundEventSource).toBe("background-tool");
+    expect(metadata.automated).toBe(true);
+  });
+
+  test("omits the key entirely when no completion is passed", async () => {
+    await persistWakeTriggerMessage(
+      makeConversationStub(conversationId),
+      triggerMessage(),
+      "background-tool",
+    );
+
+    const metadata = readMetadata(conversationId);
+    expect("backgroundToolCompletion" in metadata).toBe(false);
+    expect(metadata.kind).toBe("background-event");
+  });
+});

package/src/daemon/conversation-lifecycle.ts

@@ -69,6 +69,7 @@ export function reinjectImageSourcePaths(
 export interface AbortContext {
   readonly conversationId: string;
   isProcessing(): boolean;
+  setProcessing(value: boolean): void;
   abortController: AbortController | null;
   prompter: PermissionPrompter;
   secretPrompter: SecretPrompter;
@@ -125,7 +126,30 @@ export function abortConversation(
       { conversationId: ctx.conversationId, abortReason: effectiveReason },
       "Aborting in-flight processing",
     );
-    ctx.abortController?.abort(effectiveReason);
+    if (ctx.abortController) {
+      // A live turn owns this controller. Signal it and let the agent loop's
+      // own `finally` observe the abort, unwind, and clear the processing flag
+      // — that path clears it with the correct sync-invalidation ordering
+      // (after the awaited turn-boundary commit), so we deliberately do NOT
+      // clear it here and risk clobbering a client's optimistic state.
+      ctx.abortController.abort(effectiveReason);
+    } else {
+      // The flag is set but there is no live controller to signal: the turn
+      // that owned it already tore its controller down (the agent-loop
+      // `finally` nulls `abortController` before clearing the flag) or died
+      // without ever installing one. Either way no agent-loop `finally` is
+      // going to run to clear the flag. Without this branch the abort is a
+      // silent no-op — `?.abort()` does nothing — and the conversation stays
+      // wedged: every later submit is rejected with "already processing" and
+      // Stop appears dead. Force-clear the flag directly so the conversation
+      // frees up. `setProcessing(false)` also nulls the persisted column and
+      // emits the metadata invalidation that drives clients to idle.
+      log.warn(
+        { conversationId: ctx.conversationId },
+        "Abort requested while processing but no live abort controller — force-clearing stale processing flag",
+      );
+      ctx.setProcessing(false);
+    }
     ctx.prompter.dispose();
     ctx.secretPrompter.dispose();
     ctx.pendingSurfaceActions.clear();

package/src/daemon/wake-conversation-ops.ts

@@ -23,6 +23,7 @@ import { backfillMessageIdOnLogs } from "../persistence/llm-request-log-store.js
 import type { Message } from "../providers/types.js";
 import { broadcastMessage } from "../runtime/assistant-event-hub.js";
 import { publishConversationMessagesChanged } from "../runtime/sync/resource-sync-events.js";
+import type { CompletedBackgroundTool } from "../tools/background-tool-registry.js";
 import { getLogger } from "../util/logger.js";
 import type { Conversation } from "./conversation.js";
 import type { ServerMessage } from "./message-protocol.js";
@@ -273,6 +274,7 @@ export async function persistWakeTriggerMessage(
   conversation: Conversation,
   message: Message,
   source: string,
+  completion?: CompletedBackgroundTool,
 ): Promise<void> {
   const turnChannelCtx = conversation.getTurnChannelContext();
   const turnInterfaceCtx = conversation.getTurnInterfaceContext();
@@ -287,6 +289,7 @@ export async function persistWakeTriggerMessage(
     kind: "background-event",
     backgroundEventSource: source,
     automated: true,
+    ...(completion ? { backgroundToolCompletion: completion } : {}),
   };
   const persisted = await addMessage(
     conversation.conversationId,

package/src/persistence/conversation-crud.ts

@@ -133,6 +133,18 @@ const acpNotificationSchema = z.object({
   agent: z.string().optional(),
 });
 
+const backgroundToolCompletionMetadataSchema = z.object({
+  id: z.string(),
+  toolName: z.string(),
+  conversationId: z.string(),
+  command: z.string(),
+  startedAt: z.number(),
+  status: z.enum(["completed", "failed", "cancelled"]),
+  exitCode: z.number().nullable(),
+  output: z.string(),
+  completedAt: z.number(),
+});
+
 export const messageMetadataSchema = z
   .object({
     userMessageChannel: channelIdSchema.optional(),
@@ -164,6 +176,12 @@ export const messageMetadataSchema = z
     provenanceGuardianExternalUserId: z.string().optional(),
     provenanceRequesterIdentifier: z.string().optional(),
     automated: z.boolean().optional(),
+    /**
+     * Structured terminal record stamped onto a `<background_event
+     * source="background-tool">` wake so the web can rebuild the inline
+     * bash/host_bash card from history after a daemon restart.
+     */
+    backgroundToolCompletion: backgroundToolCompletionMetadataSchema.optional(),
     forkSourceMessageId: z.string().optional(),
     /** Image source paths from desktop attachments, keyed by filename. */
     imageSourcePaths: z.record(z.string(), z.string()).optional(),

package/src/runtime/agent-wake.ts

@@ -108,6 +108,7 @@ import {
   type UntrustedContentSource,
   wrapUntrustedContent,
 } from "../security/untrusted-content.js";
+import type { CompletedBackgroundTool } from "../tools/background-tool-registry.js";
 import { getLogger } from "../util/logger.js";
 
 const log = getLogger("agent-wake");
@@ -323,6 +324,12 @@ export interface WakeOptions {
    * framing outside the fence.
    */
   untrustedOutput?: WakeUntrustedOutput;
+  /**
+   * Structured terminal record for a backgrounded bash/host_bash run, stamped
+   * onto the persisted background-event wake so the web can rebuild the inline
+   * card from history after a daemon restart.
+   */
+  backgroundToolCompletion?: CompletedBackgroundTool;
   /**
    * Schedule-run id to stamp on the usage rows this wake records. Set when the
    * wake is triggered by a script-mode schedule (the firing's run id), so the
@@ -784,7 +791,12 @@ export async function wakeAgentForOpportunity(
       };
       conversation.messages.push(triggerMessage);
       try {
-        await persistWakeTriggerMessage(conversation, triggerMessage, source);
+        await persistWakeTriggerMessage(
+          conversation,
+          triggerMessage,
+          source,
+          opts.backgroundToolCompletion,
+        );
       } catch (err) {
         log.warn(
           { conversationId, source, err },

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

@@ -11,7 +11,9 @@ import {
   createUserMessage,
 } from "../../agent/message-types.js";
 import {
+  BackgroundToolCompletionSchema,
   type ConversationContentBlock,
+  type ConversationMessage,
   ConversationMessageSchema,
 } from "../../api/responses/conversation-message.js";
 import {
@@ -840,6 +842,7 @@ export function handleListMessages({
       | undefined;
     let acpNotification: { acpSessionId: string; agent?: string } | undefined;
     let backgroundToolNotification: boolean | undefined;
+    let backgroundToolCompletion: ConversationMessage["backgroundToolCompletion"];
     if (msg.metadata) {
       try {
         const meta = JSON.parse(msg.metadata);
@@ -852,6 +855,15 @@ export function handleListMessages({
         if (meta.backgroundEventSource === "background-tool") {
           backgroundToolNotification = true;
         }
+        // `persistWakeTriggerMessage` stamps the structured completion onto the
+        // same wake row, letting the web rebuild a terminal inline card from
+        // history after a restart (the in-memory completed ring does not survive).
+        const completionParse = BackgroundToolCompletionSchema.safeParse(
+          meta.backgroundToolCompletion,
+        );
+        if (completionParse.success) {
+          backgroundToolCompletion = completionParse.data;
+        }
         if (meta.subagentNotification) {
           const n = meta.subagentNotification;
           if (typeof n.subagentId === "string" && typeof n.label === "string") {
@@ -905,6 +917,7 @@ export function handleListMessages({
       subagentNotification,
       acpNotification,
       backgroundToolNotification,
+      backgroundToolCompletion,
       slackMessage,
       clientMessageId: msg.clientMessageId ?? undefined,
     };
@@ -1092,6 +1105,9 @@ export function handleListMessages({
       ...(m.backgroundToolNotification
         ? { backgroundToolNotification: true }
         : {}),
+      ...(m.backgroundToolCompletion
+        ? { backgroundToolCompletion: m.backgroundToolCompletion }
+        : {}),
       ...(m.slackMessage ? { slackMessage: m.slackMessage } : {}),
     };
   });

package/src/tools/host-terminal/host-shell.ts

@@ -31,6 +31,7 @@ import {
 import { isUntrustedShellLockdownActive } from "../../runtime/effective-capabilities.js";
 import { redactSecrets } from "../../security/secret-scanner.js";
 import { getLogger } from "../../util/logger.js";
+import type { CompletedBackgroundTool } from "../background-tool-registry.js";
 import {
   generateBackgroundToolId,
   isBackgroundToolLimitReached,
@@ -318,7 +319,7 @@ export const hostShellTool = {
                 ? `Background host command cancelled (id=${bgId}).`
                 : result.content;
             const completedAt = Date.now();
-            recordCompletedBackgroundTool({
+            const completion: CompletedBackgroundTool = {
               id: bgId,
               toolName: "host_bash",
               conversationId: context.conversationId,
@@ -328,7 +329,8 @@ export const hostShellTool = {
               exitCode: null,
               output,
               completedAt,
-            });
+            };
+            recordCompletedBackgroundTool(completion);
             broadcastMessage(
               {
                 type: "background_tool_completed",
@@ -351,6 +353,7 @@ export const hostShellTool = {
               hint: framing,
               source: "background-tool",
               persistTriggerAsEvent: true,
+              backgroundToolCompletion: completion,
               untrustedOutput: {
                 content: output || "(no output)",
                 source: "tool_result",
@@ -370,7 +373,7 @@ export const hostShellTool = {
                   ? err.message
                   : String(err);
             const completedAt = Date.now();
-            recordCompletedBackgroundTool({
+            const completion: CompletedBackgroundTool = {
               id: bgId,
               toolName: "host_bash",
               conversationId: context.conversationId,
@@ -380,7 +383,8 @@ export const hostShellTool = {
               exitCode: null,
               output,
               completedAt,
-            });
+            };
+            recordCompletedBackgroundTool(completion);
             broadcastMessage(
               {
                 type: "background_tool_completed",
@@ -400,6 +404,7 @@ export const hostShellTool = {
                   : `Background host command failed (id=${bgId}): ${err instanceof Error ? err.message : String(err)}`,
               source: "background-tool",
               persistTriggerAsEvent: true,
+              backgroundToolCompletion: completion,
             });
           })
           .finally(() => removeBackgroundTool(bgId));
@@ -559,7 +564,7 @@ export const hostShellTool = {
             ? `Background host command cancelled (id=${bgId}).`
             : result.content;
         const completedAt = Date.now();
-        recordCompletedBackgroundTool({
+        const completion: CompletedBackgroundTool = {
           id: bgId,
           toolName: "host_bash",
           conversationId: context.conversationId,
@@ -569,7 +574,8 @@ export const hostShellTool = {
           exitCode: code ?? null,
           output,
           completedAt,
-        });
+        };
+        recordCompletedBackgroundTool(completion);
         broadcastMessage(
           {
             type: "background_tool_completed",
@@ -593,6 +599,7 @@ export const hostShellTool = {
           hint: framing,
           source: "background-tool",
           persistTriggerAsEvent: true,
+          backgroundToolCompletion: completion,
           untrustedOutput: {
             content: output || "(no output)",
             source: "tool_result",
@@ -613,7 +620,7 @@ export const hostShellTool = {
             ? `Background host command cancelled (id=${bgId}).`
             : err.message;
         const completedAt = Date.now();
-        recordCompletedBackgroundTool({
+        const completion: CompletedBackgroundTool = {
           id: bgId,
           toolName: "host_bash",
           conversationId: context.conversationId,
@@ -623,7 +630,8 @@ export const hostShellTool = {
           exitCode: null,
           output,
           completedAt,
-        });
+        };
+        recordCompletedBackgroundTool(completion);
         broadcastMessage(
           {
             type: "background_tool_completed",
@@ -643,6 +651,7 @@ export const hostShellTool = {
               : `Background host command failed (id=${bgId}): ${err.message}`,
           source: "background-tool",
           persistTriggerAsEvent: true,
+          backgroundToolCompletion: completion,
         });
         removeBackgroundTool(bgId);
       });

package/src/tools/terminal/shell.ts

@@ -11,6 +11,7 @@ import { isUntrustedShellLockdownActive } from "../../runtime/effective-capabili
 import { redactSecrets } from "../../security/secret-scanner.js";
 import { getLogger } from "../../util/logger.js";
 import { getDataDir } from "../../util/platform.js";
+import type { CompletedBackgroundTool } from "../background-tool-registry.js";
 import {
   generateBackgroundToolId,
   isBackgroundToolLimitReached,
@@ -427,6 +428,17 @@ export const shellTool = {
             ? `Background command cancelled (id=${bgId}).`
             : fmtResult.content;
         const completedAt = Date.now();
+        const completion: CompletedBackgroundTool = {
+          id: bgId,
+          toolName: "bash",
+          conversationId: context.conversationId,
+          command,
+          startedAt,
+          status,
+          exitCode: code ?? null,
+          output,
+          completedAt,
+        };
 
         // Wake AFTER the terminal status is known so a user-cancelled run wakes
         // the assistant with the cancellation — not the SIGKILL-framed "completed"
@@ -440,6 +452,7 @@ export const shellTool = {
           hint: framing,
           source: "background-tool",
           persistTriggerAsEvent: true,
+          backgroundToolCompletion: completion,
           untrustedOutput: {
             content: output,
             source: "tool_result",
@@ -448,17 +461,7 @@ export const shellTool = {
             maxChars: MAX_OUTPUT_LENGTH * 2,
           },
         });
-        recordCompletedBackgroundTool({
-          id: bgId,
-          toolName: "bash",
-          conversationId: context.conversationId,
-          command,
-          startedAt,
-          status,
-          exitCode: code ?? null,
-          output,
-          completedAt,
-        });
+        recordCompletedBackgroundTool(completion);
         broadcastMessage(
           {
             type: "background_tool_completed",
@@ -493,15 +496,8 @@ export const shellTool = {
         });
 
         const framing = `Background command failed (id=${bgId}): ${err.message}`;
-        void wakeAgentForOpportunity({
-          conversationId: context.conversationId,
-          hint: framing,
-          source: "background-tool",
-          persistTriggerAsEvent: true,
-        });
-
         const completedAt = Date.now();
-        recordCompletedBackgroundTool({
+        const completion: CompletedBackgroundTool = {
           id: bgId,
           toolName: "bash",
           conversationId: context.conversationId,
@@ -511,7 +507,16 @@ export const shellTool = {
           exitCode: null,
           output: framing,
           completedAt,
+        };
+        void wakeAgentForOpportunity({
+          conversationId: context.conversationId,
+          hint: framing,
+          source: "background-tool",
+          persistTriggerAsEvent: true,
+          backgroundToolCompletion: completion,
         });
+
+        recordCompletedBackgroundTool(completion);
         broadcastMessage(
           {
             type: "background_tool_completed",