@vellumai/assistant 0.10.10-dev.202607170508.cf52585 → 0.10.10-dev.202607170744.fa2b150

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.10.10-dev.202607170508.cf52585",
+  "version": "0.10.10-dev.202607170744.fa2b150",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/conversation-runtime-assembly.test.ts

@@ -6211,6 +6211,84 @@ describe("assembleSlackChronologicalMessages", () => {
     expect(serialized).toContain("hi assistant");
     expect(serialized).toContain("back to normal");
   });
+
+  test("quarantines the refused exchange across an interleaved sibling thread", () => {
+    // Multi-party channel: @alice's flagged prompt roots a thread, the
+    // assistant's refusal fallback replies inside it (`threadTs` = the prompt's
+    // ts), and @bob posts in a different thread in between. Chronological
+    // adjacency would pair the fallback with @bob's unrelated post — dropping
+    // it and stranding the actual refused prompt, which then re-trips the
+    // classifier every turn. Thread provenance pairs the fallback with @alice's
+    // prompt instead and leaves @bob's post in place.
+    const CHANNEL_ID = "C0MULTI01";
+    const SLACK_CAPS_CHANNEL: ChannelCapabilities = {
+      channel: "slack",
+      dashboardCapable: false,
+      supportsDynamicUi: false,
+      supportsVoiceInput: false,
+      chatType: "channel",
+    };
+    const T_HI = "1699971900.000100";
+    const T_PROMPT = "1699972000.000200"; // roots @alice's thread
+    const T_BOB = "1699972030.000300"; // sibling-thread post, interleaved
+    const T_FALLBACK = "1699972060.000400"; // assistant refusal, in @alice's thread
+    const T_LATER = "1699972200.000500";
+    const meta = (
+      channelTs: string,
+      displayName: string,
+      threadTs?: string,
+    ): SlackMessageMetadata => ({
+      source: "slack",
+      channelId: CHANNEL_ID,
+      channelTs,
+      ...(threadTs ? { threadTs } : {}),
+      eventKind: "message",
+      displayName,
+    });
+    const rows: SlackTranscriptInputRow[] = [
+      row(
+        "user",
+        "hi assistant",
+        1699971900_000,
+        metadataEnvelope(meta(T_HI, "@alice")),
+      ),
+      row(
+        "user",
+        "disallowed question",
+        1699972000_000,
+        metadataEnvelope(meta(T_PROMPT, "@alice")),
+      ),
+      row(
+        "user",
+        "what's for lunch",
+        1699972030_000,
+        metadataEnvelope(meta(T_BOB, "@bob")),
+      ),
+      row(
+        "assistant",
+        REFUSAL_FALLBACK_TEXT,
+        1699972060_000,
+        metadataEnvelope(meta(T_FALLBACK, "@assistant", T_PROMPT)),
+      ),
+      row(
+        "user",
+        "back to normal",
+        1699972200_000,
+        metadataEnvelope(meta(T_LATER, "@alice")),
+      ),
+    ];
+
+    const result = assembleSlackChronologicalMessages(rows, SLACK_CAPS_CHANNEL);
+    const serialized = JSON.stringify(result);
+    // The refusal and the prompt that tripped it are both gone …
+    expect(serialized).not.toContain(REFUSAL_FALLBACK_TEXT);
+    expect(serialized).not.toContain("disallowed question");
+    // … the interleaved sibling-thread post from another user is untouched …
+    expect(serialized).toContain("what's for lunch");
+    // … as are the benign turns on either side.
+    expect(serialized).toContain("hi assistant");
+    expect(serialized).toContain("back to normal");
+  });
 });
 
 // ---------------------------------------------------------------------------

package/src/__tests__/conversation-tool-setup-app-refresh.test.ts

@@ -2,9 +2,10 @@
  * Regression tests for app surface refresh and eventing side effects in
  * createToolExecutor (conversation-tool-setup.ts).
  *
- * Tests verify that app_refresh, app_update, app_create, and app_delete hooks
- * fire correctly, and that non-hooked tools (app_file_edit, app_file_write) do
- * not trigger side effects.
+ * Tests verify that app_refresh, app_update, app_create, app_delete, and
+ * app_generate_icon hooks fire correctly — including recovering an omitted
+ * app_id from the executor's echoed result — and that non-hooked tools
+ * (app_file_edit, app_file_write) do not trigger side effects.
  *
  * File-change detection for file_write/file_edit is handled by
  * AppSourceWatcher (see app-source-watcher.test.ts).
@@ -222,7 +223,35 @@ describe("session-tool-setup app refresh side effects", () => {
       expect(updatePublishedSpy).not.toHaveBeenCalled();
     });
 
-    test("skips side effects when app_id is missing", async () => {
+    test("recovers appId from the result when input omits app_id", async () => {
+      // app_id is optional: the skill script resolves the active app and the
+      // executor echoes it back as `appId`. The hook must act on that resolved
+      // id so an omitted-id refresh still refreshes surfaces and re-deploys.
+      const ctx = makeCtx();
+      const executor = makeFakeExecutor({
+        content: '{"refreshed":true,"appId":"app-resolved"}',
+        isError: false,
+      });
+
+      const toolFn = createToolExecutor(
+        executor as unknown as ToolExecutor,
+        noopPrompter,
+        noopSecretPrompter,
+        ctx,
+      );
+
+      await toolFn("app_refresh", {});
+
+      expect(refreshSpy).toHaveBeenCalledTimes(1);
+      expect((refreshSpy.mock.calls as unknown[][])[0][1]).toBe("app-resolved");
+      expectAppChangeBroadcast("app-resolved");
+      expect(updatePublishedSpy).toHaveBeenCalledTimes(1);
+      expect((updatePublishedSpy.mock.calls as unknown[][])[0][0]).toBe(
+        "app-resolved",
+      );
+    });
+
+    test("skips side effects when app_id is absent from input and result", async () => {
       const ctx = makeCtx();
       const executor = makeFakeExecutor({ content: "{}", isError: false });
 
@@ -289,7 +318,34 @@ describe("session-tool-setup app refresh side effects", () => {
       expect(updatePublishedSpy).not.toHaveBeenCalled();
     });
 
-    test("skips side effects when app_id is missing", async () => {
+    test("recovers appId from the result when input omits app_id", async () => {
+      const ctx = makeCtx();
+      const executor = makeFakeExecutor({
+        content: '{"updated":true,"appId":"app-resolved-u"}',
+        isError: false,
+      });
+
+      const toolFn = createToolExecutor(
+        executor as unknown as ToolExecutor,
+        noopPrompter,
+        noopSecretPrompter,
+        ctx,
+      );
+
+      await toolFn("app_update", {});
+
+      expect(refreshSpy).toHaveBeenCalledTimes(1);
+      expect((refreshSpy.mock.calls as unknown[][])[0][1]).toBe(
+        "app-resolved-u",
+      );
+      expectAppChangeBroadcast("app-resolved-u");
+      expect(updatePublishedSpy).toHaveBeenCalledTimes(1);
+      expect((updatePublishedSpy.mock.calls as unknown[][])[0][0]).toBe(
+        "app-resolved-u",
+      );
+    });
+
+    test("skips side effects when app_id is absent from input and result", async () => {
       const ctx = makeCtx();
       const executor = makeFakeExecutor({ content: "{}", isError: false });
 
@@ -511,6 +567,70 @@ describe("session-tool-setup app refresh side effects", () => {
     });
   });
 
+  // ── app_generate_icon side effects ──────────────────────────────────
+
+  describe("app_generate_icon side effects", () => {
+    test("broadcasts app_files_changed with explicit app_id", async () => {
+      const ctx = makeCtx();
+      const executor = makeFakeExecutor({
+        content: '{"generated":true,"appId":"icon-app"}',
+        isError: false,
+      });
+
+      const toolFn = createToolExecutor(
+        executor as unknown as ToolExecutor,
+        noopPrompter,
+        noopSecretPrompter,
+        ctx,
+      );
+
+      await toolFn("app_generate_icon", { app_id: "icon-app" });
+
+      expect(broadcastSpy).toHaveBeenCalledTimes(2);
+      expectAppChangeBroadcast("icon-app");
+      // Icon regen only rebroadcasts the app list — it neither refreshes open
+      // surfaces nor re-deploys the published app.
+      expect(refreshSpy).not.toHaveBeenCalled();
+      expect(updatePublishedSpy).not.toHaveBeenCalled();
+    });
+
+    test("recovers appId from the result when input omits app_id", async () => {
+      const ctx = makeCtx();
+      const executor = makeFakeExecutor({
+        content: '{"generated":true,"appId":"icon-resolved"}',
+        isError: false,
+      });
+
+      const toolFn = createToolExecutor(
+        executor as unknown as ToolExecutor,
+        noopPrompter,
+        noopSecretPrompter,
+        ctx,
+      );
+
+      await toolFn("app_generate_icon", {});
+
+      expect(broadcastSpy).toHaveBeenCalledTimes(2);
+      expectAppChangeBroadcast("icon-resolved");
+    });
+
+    test("skips broadcast when app_id is absent from input and result", async () => {
+      const ctx = makeCtx();
+      const executor = makeFakeExecutor({ content: "{}", isError: false });
+
+      const toolFn = createToolExecutor(
+        executor as unknown as ToolExecutor,
+        noopPrompter,
+        noopSecretPrompter,
+        ctx,
+      );
+
+      await toolFn("app_generate_icon", {});
+
+      expect(broadcastSpy).not.toHaveBeenCalled();
+    });
+  });
+
   // ── Name-based hook targeting (skill-origin tools) ──────────────────
 
   describe("name-based hooks fire for skill-origin tools", () => {

package/src/__tests__/interrupted-turn-reconciler.test.ts

@@ -19,6 +19,9 @@ import { initializeDb } from "../persistence/db-init.js";
 
 await initializeDb();
 
+const actualConversationCrud =
+  await import("../persistence/conversation-crud.js");
+
 function readRow(id: string): {
   processing_started_at: number | null;
   processing_resume_attempts: number;
@@ -254,4 +257,47 @@ describe("resumeInterruptedConversations", () => {
     expect(readRow("conv-bad").processing_resume_attempts).toBe(1);
     expect(readRow("conv-good").processing_resume_attempts).toBe(1);
   });
+
+  test("a failing counter write is isolated to its conversation and does not abort the rest", async () => {
+    createConversation({ id: "conv-bad" });
+    createConversation({ id: "conv-good" });
+
+    // A transient counter-write failure (e.g. a locked SQLite db during
+    // startup) must be logged and skipped for that conversation, exactly like a
+    // failing wake — never rejected out of the loop, which would strand every
+    // conversation queued behind it.
+    // Captured before mock.module: the namespace binding is live post-mock, so
+    // delegating through it would recurse into this override.
+    const realIncrement =
+      actualConversationCrud.incrementProcessingResumeAttempts;
+    mock.module("../persistence/conversation-crud.js", () => ({
+      ...actualConversationCrud,
+      incrementProcessingResumeAttempts: (id: string) => {
+        if (id === "conv-bad") {
+          throw new Error("counter write failed");
+        }
+        return realIncrement(id);
+      },
+    }));
+
+    const wakeCalls: string[] = [];
+    const wakeMock = mock(async (opts: Record<string, unknown>) => {
+      wakeCalls.push(opts.conversationId as string);
+      return { invoked: true, producedToolCalls: false };
+    });
+    mock.module("../runtime/agent-wake.js", () => ({
+      wakeAgentForOpportunity: wakeMock,
+    }));
+
+    await resumeInterruptedConversations([
+      guardianTarget("conv-bad"),
+      guardianTarget("conv-good"),
+    ]);
+
+    // conv-bad's counter threw before its wake ran, so it was skipped and never
+    // charged; conv-good still resumed and charged its own attempt.
+    expect(wakeCalls).toEqual(["conv-good"]);
+    expect(readRow("conv-bad").processing_resume_attempts).toBe(0);
+    expect(readRow("conv-good").processing_resume_attempts).toBe(1);
+  });
 });

package/src/__tests__/job-handler-registration-guard.test.ts

@@ -13,6 +13,7 @@ const MEMORY_JOB_TYPES = [
   "backfill",
   "rebuild_index",
   "delete_qdrant_vectors",
+  "sweep_orphaned_graph_node_points",
   "embed_media",
   "embed_attachment",
   "embed_graph_node",

package/src/context/refusal-quarantine.ts

@@ -66,18 +66,56 @@ export function isRefusalFallbackMessage(message: Message): boolean {
 /**
  * Indices of every message belonging to a previously-refused exchange: for each
  * assistant message that is exactly the refusal fallback, its own index plus the
- * contiguous run back to (and including) the nearest genuine user prompt — the
+ * run back to (and including) the genuine user prompt that tripped it — the
  * flagged prompt and any tool exchange in that run.
  *
+ * Pairing the fallback with its true prompt:
+ *
+ * - By default (no `threadKeys`) the walk-back is pure array adjacency: the
+ *   nearest preceding genuine user prompt. Correct for a single-party history
+ *   (the in-memory working set, a Slack DM) where turns strictly alternate.
+ * - In a multi-party Slack channel, another party's post can land between the
+ *   refused prompt and the fallback in chronological order, so adjacency would
+ *   pair the fallback with that unrelated post and leave the actual refused
+ *   prompt behind. `threadKeys` (a per-message Slack thread identity aligned
+ *   1:1 with `messages`, `threadTs ?? channelTs`) fixes this: when the
+ *   fallback's thread is shared by another message — i.e. it is a real thread,
+ *   not a lone top-level/DM row whose key is just its own `channelTs` — the
+ *   walk-back skips over messages from other threads and pairs the fallback
+ *   with the nearest genuine prompt in its own thread. A `null` key (non-Slack
+ *   / legacy rows with no provenance) always uses adjacency.
+ *
  * Exposed as a set of indices (rather than only the filtered messages) so a
  * caller holding an array rendered in lockstep with `messages` — e.g. the Slack
  * chronological transcript, whose per-message compaction provenance rides in a
  * sibling array — can drop the same exchanges from both and keep them aligned.
  */
-export function computeRefusedExchangeDrops(messages: Message[]): {
+export function computeRefusedExchangeDrops(
+  messages: Message[],
+  opts: { threadKeys?: ReadonlyArray<string | null> } = {},
+): {
   dropIndices: Set<number>;
   droppedExchanges: number;
 } {
+  const { threadKeys } = opts;
+  // A thread key only carries pairing signal when it is shared: a lone
+  // top-level or DM row has its own `channelTs` as its key, so treating it as a
+  // one-message "thread" would strand the prompt. Count keys once so each
+  // fallback can tell whether it sits in a real (multi-row) thread.
+  const sharedThreadKeys = new Set<string>();
+  if (threadKeys) {
+    const seen = new Set<string>();
+    for (const key of threadKeys) {
+      if (key === null) {
+        continue;
+      }
+      if (seen.has(key)) {
+        sharedThreadKeys.add(key);
+      } else {
+        seen.add(key);
+      }
+    }
+  }
   const dropIndices = new Set<number>();
   let droppedExchanges = 0;
   for (let r = 0; r < messages.length; r++) {
@@ -85,17 +123,24 @@ export function computeRefusedExchangeDrops(messages: Message[]): {
       continue;
     }
     dropIndices.add(r);
-    // Walk back over tool-result / assistant tool churn to the genuine prompt.
-    let s = r - 1;
-    while (
-      s >= 0 &&
-      !(messages[s].role === "user" && !isToolResultMessage(messages[s]))
-    ) {
+    const fallbackThreadKey = threadKeys?.[r] ?? null;
+    // Scope the walk-back to the fallback's own thread only when that thread is
+    // real — shared by another row. A lone top-level/DM row (keyed by its own
+    // channelTs) or a provenance-less null key falls through to adjacency.
+    const threadScope =
+      fallbackThreadKey !== null && sharedThreadKeys.has(fallbackThreadKey)
+        ? threadKeys
+        : undefined;
+    // Walk back to the genuine prompt over tool-result / assistant tool churn,
+    // skipping (leaving in place) any interleaved message from another thread.
+    for (let s = r - 1; s >= 0; s--) {
+      if (threadScope && (threadScope[s] ?? null) !== fallbackThreadKey) {
+        continue;
+      }
       dropIndices.add(s);
-      s--;
-    }
-    if (s >= 0) {
-      dropIndices.add(s); // the genuine user prompt that was refused
+      if (messages[s].role === "user" && !isToolResultMessage(messages[s])) {
+        break; // the genuine user prompt that was refused
+      }
     }
     droppedExchanges++;
   }

package/src/daemon/conversation-runtime-assembly.ts

@@ -1304,6 +1304,30 @@ export function getSlackWatermarkAdvanceForRowPrefix(
   return ts;
 }
 
+/**
+ * Map each row's Slack `channelTs` to its thread key (`threadTs ?? channelTs`).
+ *
+ * A rendered transcript message carries its source row's `channelTs` in
+ * `sourceChannelTs`, so this map lets the refusal-exchange sweep resolve each
+ * rendered message's thread and pair a persisted refusal fallback with the
+ * prompt in its own thread — rather than the nearest chronological neighbour,
+ * which in a multi-party channel can be an unrelated sibling-thread post.
+ */
+function buildSlackThreadKeyByChannelTs(
+  rows: SlackTranscriptInputRow[],
+): Map<string, string> {
+  const byChannelTs = new Map<string, string>();
+  for (const row of rows) {
+    const meta = readSlackMetadataFromMessageMetadata(row.metadata, {
+      allowFlatLegacy: true,
+    });
+    if (meta?.channelTs) {
+      byChannelTs.set(meta.channelTs, meta.threadTs ?? meta.channelTs);
+    }
+  }
+  return byChannelTs;
+}
+
 function assembleSlackChronologicalContext(
   rows: SlackTranscriptInputRow[],
   capabilities: ChannelCapabilities,
@@ -1319,9 +1343,20 @@ function assembleSlackChronologicalContext(
   // Drop previously-refused exchanges — a persisted safety-classifier refusal
   // and the prompt that tripped it — so the model isn't re-fed a refusal it
   // will just repeat (the dead-end `empty-response` sweeps off Slack turns).
-  // `renderedMessages` is filtered by the same indices to stay aligned with the
-  // `messages` projection compaction slices.
-  const { dropIndices } = computeRefusedExchangeDrops(rendered.messages);
+  // Pairing is thread-aware: each rendered message's Slack thread is resolved
+  // from its `sourceChannelTs`, so an interleaved sibling-thread post that
+  // landed between the refused prompt and the fallback is neither dropped nor
+  // mistaken for the prompt. `renderedMessages` is filtered by the same indices
+  // to stay aligned with the `messages` projection compaction slices.
+  const threadKeyByChannelTs = buildSlackThreadKeyByChannelTs(rows);
+  const threadKeys = rendered.renderedMessages.map((entry) =>
+    entry.sourceChannelTs !== null
+      ? (threadKeyByChannelTs.get(entry.sourceChannelTs) ?? null)
+      : null,
+  );
+  const { dropIndices } = computeRefusedExchangeDrops(rendered.messages, {
+    threadKeys,
+  });
   const renderedMessages =
     dropIndices.size > 0
       ? rendered.renderedMessages.filter((_, i) => !dropIndices.has(i))

package/src/daemon/interrupted-turn-reconciler.ts

@@ -168,13 +168,16 @@ export async function resumeInterruptedConversations(
 ): Promise<void> {
   const { wakeAgentForOpportunity } = await import("../runtime/agent-wake.js");
   for (const { conversationId, trustContext } of targets) {
-    // Charge the attempt as the wake begins, before the turn runs. The cap
-    // exists to stop a resumed turn that keeps killing the process, so the
-    // counter must be durably incremented before that turn can crash the
-    // daemon; a sequential increment here also means a crash mid-resume never
-    // charges the conversations still queued behind it.
-    incrementProcessingResumeAttempts(conversationId);
     try {
+      // Charge the attempt before the wake runs. The cap exists to stop a
+      // resumed turn that keeps killing the process, so the counter must be
+      // durably incremented before that turn can crash the daemon; charging it
+      // per-conversation (never up-front for the batch) also means a crash
+      // mid-resume never burns the budget of conversations still queued behind
+      // it. Doing it inside this guarded block keeps a transient counter-write
+      // failure scoped to its own conversation instead of aborting every
+      // resume still queued.
+      incrementProcessingResumeAttempts(conversationId);
       const result = await wakeAgentForOpportunity({
         conversationId,
         hint: INTERRUPTED_TURN_RESUME_HINT,

package/src/daemon/process-message.ts

@@ -409,6 +409,13 @@ export async function processMessage(
 ): Promise<{
   messageId: string;
   assistantMessageId?: string;
+  /**
+   * True when this ingress deduplicated against a prior turn (same idempotency
+   * key) and the agent loop was skipped. Channel finalization must skip reply
+   * delivery on this signal so an at-least-once redelivery does not re-emit the
+   * original turn's reply.
+   */
+  deduplicated?: boolean;
   /**
    * The agent turn's failure outcome, or `null` when it replied normally. Set
    * when the turn failed (e.g. its LLM call failed with an invalid provider) —
@@ -676,12 +683,18 @@ export async function processMessage(
 
   if (deduplicated) {
     // This exact ingress (same idempotency key) already ran a turn; skip the
-    // loop so an at-least-once redelivery does not emit a second reply.
+    // loop so an at-least-once redelivery does not emit a second reply. The
+    // `deduplicated` signal also stops channel finalization from re-delivering
+    // the original reply.
     log.info(
       { conversationId, messageId },
       "Skipping agent loop for deduplicated ingress message",
     );
-    return { messageId, turnFailure: readTurnFailure(messageId) };
+    return {
+      messageId,
+      deduplicated: true,
+      turnFailure: readTurnFailure(messageId),
+    };
   }
 
   if (options?.isInteractive === true) {

package/src/daemon/tool-side-effects.ts

@@ -70,6 +70,35 @@ function broadcastAppFilesChanged(appId: string): void {
   publishAppsChanged();
 }
 
+/**
+ * Resolve the app id a post-execution hook should act on.
+ *
+ * `app_id` is optional for the app-builder fallback tools (`app_update`,
+ * `app_refresh`, `app_generate_icon`): when the model omits it, the skill
+ * script resolves the conversation's active app and the executor echoes that
+ * id back as `appId` in its result. Prefer the explicit tool input; fall back
+ * to the resolved id the result carries so an omitted-id call still refreshes
+ * surfaces, rebroadcasts, and re-deploys instead of silently no-op'ing.
+ */
+function resolveHookAppId(
+  input: Record<string, unknown>,
+  result: ToolExecutionResult,
+): string | undefined {
+  const explicit = input.app_id;
+  if (typeof explicit === "string" && explicit.trim().length > 0) {
+    return explicit;
+  }
+  try {
+    const parsed = JSON.parse(result.content) as { appId?: unknown };
+    if (typeof parsed.appId === "string" && parsed.appId.length > 0) {
+      return parsed.appId;
+    }
+  } catch {
+    // Result wasn't valid JSON — no resolved id to recover.
+  }
+  return undefined;
+}
+
 // ── Registry ─────────────────────────────────────────────────────────
 
 /**
@@ -130,8 +159,8 @@ registerHook("app_create", (_name, _input, result, { ctx }) => {
   }
 });
 
-registerHook("app_generate_icon", (_name, input) => {
-  const appId = input.app_id as string | undefined;
+registerHook("app_generate_icon", (_name, input, result) => {
+  const appId = resolveHookAppId(input, result);
   if (appId) {
     broadcastAppFilesChanged(appId);
   }
@@ -144,31 +173,26 @@ registerHook("app_delete", (_name, input) => {
   }
 });
 
-registerHook("app_refresh", (_name, input, _result, { ctx }) => {
-  const appId = input.app_id as string | undefined;
-  if (!appId) return;
-  try {
-    addAppConversationId(appId, ctx.conversationId);
-  } catch (err) {
-    log.warn({ err, appId }, "Failed to track conversation ID on app_refresh");
-  }
-  notifyAppChanged(ctx, appId, { fileChange: true });
-});
-
-// app_update compiles internally (like app_refresh) but emits no events of its
-// own, so without this hook an updated app leaves open surfaces rendering the
-// stale dist and never re-deploys or invalidates the Library. The executor owns
-// the compile; notifyAppChanged only refreshes surfaces and broadcasts.
-registerHook("app_update", (_name, input, _result, { ctx }) => {
-  const appId = input.app_id as string | undefined;
-  if (!appId) return;
-  try {
-    addAppConversationId(appId, ctx.conversationId);
-  } catch (err) {
-    log.warn({ err, appId }, "Failed to track conversation ID on app_update");
-  }
-  notifyAppChanged(ctx, appId, { fileChange: true });
-});
+// app_refresh and app_update mutate an app's source but emit no events of their
+// own, so without a hook an updated app leaves open surfaces rendering the stale
+// dist and never re-deploys or invalidates the Library. The executor owns the
+// compile; notifyAppChanged only refreshes surfaces and broadcasts.
+function registerAppSurfaceRefreshHook(toolName: string): void {
+  registerHook(toolName, (name, input, result, { ctx }) => {
+    const appId = resolveHookAppId(input, result);
+    if (!appId) {
+      return;
+    }
+    try {
+      addAppConversationId(appId, ctx.conversationId);
+    } catch (err) {
+      log.warn({ err, appId }, `Failed to track conversation ID on ${name}`);
+    }
+    notifyAppChanged(ctx, appId, { fileChange: true });
+  });
+}
+registerAppSurfaceRefreshHook("app_refresh");
+registerAppSurfaceRefreshHook("app_update");
 
 registerHook("voice_config_update", (_name, input) => {
   const setting = input.setting as string | undefined;