@vellumai/assistant 0.11.2 → 0.11.3-dev.202608080427.92f668a

package/src/runtime/routes/sse-actor-principal-heal.ts

@@ -0,0 +1,113 @@
+/**
+ * Retrying self-heal for an SSE client subscription that registered without an
+ * actor principal.
+ *
+ * In `DISABLE_HTTP_AUTH` deployments the SSE subscribe path cannot await, so it
+ * resolves the dev-bypass actor principal from an IO-free peek at the
+ * guardian-delivery cache. A cold cache registers the subscription with
+ * `actorPrincipalId: undefined`, and every host-proxy result that client
+ * submits then fails the same-actor gate with `missing_target`: a 403 that only
+ * a fresh registration clears.
+ *
+ * The heal resolves the guardian asynchronously and patches the live hub
+ * record. Each attempt can come back empty, since the lookup goes over the
+ * gateway IPC and yields nothing both when the transport fails (unreachable
+ * gateway, its 2s timeout, a pod still starting) and when no guardian binding
+ * exists yet, so attempts repeat on a bounded backoff. The loop stops on the
+ * first success, when the connection is gone or already carries a principal, or
+ * when the schedule is exhausted.
+ *
+ * Callers must pass a cache-bypassing lookup: the guardian-delivery reader
+ * caches a successful empty result for minutes, which outlives the whole
+ * schedule, so a cached read would spend every attempt on the same stale
+ * answer.
+ */
+import { getLogger } from "../../util/logger.js";
+
+const log = getLogger("sse-actor-heal");
+
+/**
+ * The hub surface this module needs: a liveness check and the fill. Narrow by
+ * design so tests can drive the loop without a real hub.
+ */
+export interface ActorPrincipalHealHub {
+  needsActorPrincipalHeal(connectionId: string): boolean;
+  fillClientActorPrincipalId(
+    connectionId: string,
+    actorPrincipalId: string,
+  ): void;
+}
+
+/**
+ * Delay before each attempt, in milliseconds. The leading zero dispatches the
+ * first attempt inline with the subscribe; the rest back off to cover a gateway
+ * that is slow to come up, without holding a timer for the life of a long-lived
+ * stream. Total span is about 44s.
+ */
+export const ACTOR_PRINCIPAL_HEAL_DELAYS_MS: readonly number[] = [
+  0, 1_000, 3_000, 10_000, 30_000,
+];
+
+/**
+ * Start the retrying heal for `connectionId`. Fire-and-forget: never awaited by
+ * the route, never delays the stream.
+ *
+ * `resolve` performs the daemon's own server-side guardian lookup, bypassing
+ * the guardian-delivery cache. The value must never come from client input. It
+ * may resolve `undefined` (no binding yet, or the gateway is unreachable) or
+ * reject; both count as a failed attempt.
+ */
+export function startActorPrincipalHeal(args: {
+  hub: ActorPrincipalHealHub;
+  connectionId: string;
+  resolve: () => Promise<string | undefined>;
+  /** Override the backoff schedule. Tests pass all-zero delays. */
+  delaysMs?: readonly number[];
+}): void {
+  const { hub, connectionId, resolve } = args;
+  const delays = args.delaysMs ?? ACTOR_PRINCIPAL_HEAL_DELAYS_MS;
+
+  void (async () => {
+    for (let attempt = 0; attempt < delays.length; attempt++) {
+      const delayMs = delays[attempt] ?? 0;
+      if (delayMs > 0) {
+        await sleep(delayMs);
+      }
+
+      // Re-check every pass: the connection may have closed, been replaced by a
+      // reconnect, or been healed by another path since the last one.
+      if (!hub.needsActorPrincipalHeal(connectionId)) {
+        return;
+      }
+
+      let resolved: string | undefined;
+      try {
+        resolved = await resolve();
+      } catch {
+        resolved = undefined;
+      }
+      if (resolved) {
+        hub.fillClientActorPrincipalId(connectionId, resolved);
+        return;
+      }
+    }
+
+    // Log the give-up so a principal-less subscription is greppable next to the
+    // same-actor rejections it causes, rather than surfacing only as opaque
+    // 403s on the client.
+    if (hub.needsActorPrincipalHeal(connectionId)) {
+      log.warn(
+        { connectionId, attempts: delays.length },
+        "gave up healing missing actorPrincipalId for client subscription; host-proxy results from this connection are rejected until it reconnects",
+      );
+    }
+  })();
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    // Never hold the process (or a test runner) open on a pending backoff.
+    (timer as { unref?: () => void }).unref?.();
+  });
+}

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

@@ -223,6 +223,35 @@ const STT_ERROR_MAP: Record<SttErrorCategory, () => RouteError> = {
   "provider-error": () => new BadGatewayError("STT provider error"),
 };
 
+/**
+ * Resolve the configured batch transcriber, or fail the request with a 503
+ * naming which kind of unavailability this is.
+ *
+ * A typed {@link SttError} already names the situation and its fix (a
+ * configured provider that cannot batch transcribe), so its message is
+ * surfaced verbatim. `null` means nothing is configured at all, and any other
+ * throw is an unexpected resolver failure.
+ */
+async function resolveBatchTranscriberOrUnavailable(): Promise<BatchTranscriber> {
+  let transcriber: BatchTranscriber | null;
+  try {
+    transcriber = await resolveBatchTranscriber();
+  } catch (err) {
+    if (err instanceof SttError) {
+      throw new ServiceUnavailableError(err.message);
+    }
+    log.error({ err }, "Failed to resolve STT transcriber");
+    throw new ServiceUnavailableError("STT provider is not available");
+  }
+
+  if (!transcriber) {
+    throw new ServiceUnavailableError(
+      "No speech-to-text provider is configured",
+    );
+  }
+  return transcriber;
+}
+
 // ---------------------------------------------------------------------------
 // Handlers
 // ---------------------------------------------------------------------------
@@ -288,19 +317,7 @@ async function handleTranscribe({ body }: RouteHandlerArgs) {
   }
 
   // -- Resolve transcriber --------------------------------------------------
-  let transcriber;
-  try {
-    transcriber = await resolveBatchTranscriber();
-  } catch (err) {
-    log.error({ err }, "Failed to resolve STT transcriber");
-    throw new ServiceUnavailableError("STT provider is not available");
-  }
-
-  if (!transcriber) {
-    throw new ServiceUnavailableError(
-      "No speech-to-text provider is configured",
-    );
-  }
+  const transcriber = await resolveBatchTranscriberOrUnavailable();
 
   // -- Transcribe with timeout ----------------------------------------------
   const abortController = new AbortController();
@@ -358,18 +375,7 @@ async function handleTranscribeFile({ body }: RouteHandlerArgs) {
     );
   }
 
-  let transcriber;
-  try {
-    transcriber = await resolveBatchTranscriber();
-  } catch (err) {
-    log.error({ err }, "Failed to resolve STT transcriber");
-    throw new ServiceUnavailableError("STT provider is not available");
-  }
-  if (!transcriber) {
-    throw new ServiceUnavailableError(
-      "No speech-to-text provider is configured",
-    );
-  }
+  const transcriber = await resolveBatchTranscriberOrUnavailable();
 
   const startTime = Date.now();
   let wavPath: string | null = null;

package/src/runtime/routes/ui-snapshot-routes.ts

@@ -206,6 +206,7 @@ async function handleHostUiSnapshotResult({ body, headers }: RouteHandlerArgs) {
       targetActorPrincipalId: peeked.targetActorPrincipalId,
       targetClientId: peeked.targetClientId,
       op: "host_ui_snapshot",
+      hubForMissingTarget: assistantEventHub,
     });
   }
 

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

@@ -8,6 +8,7 @@ import { z } from "zod";
 
 import { INTERNAL_GUARDIAN_TRUST_CONTEXT } from "../../daemon/trust-context.js";
 import { getConversation } from "../../persistence/conversation-crud.js";
+import { getSchedule } from "../../schedule/schedule-store.js";
 import { wakeAgentForOpportunity } from "../agent-wake.js";
 import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
 import { NotFoundError } from "./errors.js";
@@ -20,6 +21,10 @@ const WakeConversationBody = z.object({
   // Honored only for a `local` caller (see handler) — a remote `actor` could
   // otherwise attribute its wake's cost to an arbitrary firing.
   cronRunId: z.string().min(1).optional(),
+  // Runs the turn on this schedule's pinned inference profile. Honored only for
+  // a `local` caller (see handler): a remote `actor` could otherwise run turns
+  // under an arbitrary schedule's profile and spend the owner's money.
+  scheduleId: z.string().min(1).optional(),
   // Persist the trigger as a background event rather than an ephemeral hint, so
   // repeated wakes stay prompt-cache-friendly.
   persist: z.boolean().optional(),
@@ -53,6 +58,7 @@ export const ROUTES: RouteDefinition[] = [
         hint,
         source,
         cronRunId,
+        scheduleId,
         persist,
         externalContent,
       } = WakeConversationBody.parse(body);
@@ -72,6 +78,22 @@ export const ROUTES: RouteDefinition[] = [
       // local caller.
       const isLocal = headers?.["x-vellum-principal-type"] === "local";
 
+      // A script-mode schedule hands off to the agent loop through this route,
+      // so the schedule's pinned profile has to be applied here for the woken
+      // turn to run on the model the schedule was created under.
+      //
+      // The pin applies per turn rather than as a durable conversation pin,
+      // and it wins over the target conversation's own pin for turns the
+      // schedule triggers. That matters because a script may wake any
+      // conversation it names, not only the `scheduled` one it created:
+      // waking an interactive chat runs that one turn on the schedule's
+      // profile, while the user's own replies keep using their selection.
+      // A schedule with no pin resolves as any other turn does.
+      const scheduleProfile =
+        isLocal && scheduleId
+          ? (getSchedule(scheduleId)?.inferenceProfile ?? null)
+          : null;
+
       return wakeAgentForOpportunity({
         conversationId,
         hint,
@@ -80,6 +102,7 @@ export const ROUTES: RouteDefinition[] = [
           ? { trustContext: INTERNAL_GUARDIAN_TRUST_CONTEXT, clientless: true }
           : {}),
         ...(isLocal && cronRunId ? { cronRunId } : {}),
+        ...(scheduleProfile ? { forceOverrideProfile: scheduleProfile } : {}),
         ...(persist ? { persistTriggerAsEvent: true } : {}),
         ...(externalContent !== undefined
           ? { untrustedOutput: { content: externalContent, source: "webhook" } }

package/src/runtime/services/__tests__/conversation-serializer.test.ts

@@ -38,6 +38,7 @@ function makeConversationRow(
     originInterface: null,
     forkParentConversationId: null,
     forkParentMessageId: null,
+    forkStrategy: null,
     isAutoTitle: 0,
     scheduleJobId: null,
     lastMessageAt: 3000,

package/src/runtime/services/conversation-serializer.ts

@@ -22,6 +22,7 @@ import {
   getDisplayMetaForConversations,
   isConversationProcessing,
 } from "../../persistence/conversation-crud.js";
+import { isReferentialFork } from "../../persistence/conversation-lineage.js";
 import type { ExternalConversationBinding } from "../../persistence/external-conversation-store.js";
 import { getBindingsForConversations } from "../../persistence/external-conversation-store.js";
 
@@ -64,14 +65,24 @@ function buildAssistantAttention(attentionState: AttentionState | undefined):
   };
 }
 
-function buildForkParent(
+interface ForkLineage {
+  forkParent?: { conversationId: string; messageId: string; title: string };
+  /**
+   * The fork reads its history from a parent that is gone. Only meaningful for
+   * referential forks: a cloning fork holds its own copy, so a deleted parent
+   * costs it nothing and is not worth telling the user about.
+   */
+  historyOrphaned?: true;
+}
+
+function buildForkLineage(
   conversation: ConversationRow,
   parentCache: Map<string, ConversationRow | null>,
-): { conversationId: string; messageId: string; title: string } | undefined {
+): ForkLineage {
   const parentConversationId = conversation.forkParentConversationId;
   const parentMessageId = conversation.forkParentMessageId;
   if (!parentConversationId || !parentMessageId) {
-    return undefined;
+    return {};
   }
 
   let parentConversation: ConversationRow | null | undefined =
@@ -81,13 +92,17 @@ function buildForkParent(
     parentCache.set(parentConversationId, parentConversation);
   }
   if (!parentConversation) {
-    return undefined;
+    // The parent lookup already happened, so reporting the orphan costs
+    // nothing beyond the branch.
+    return isReferentialFork(conversation) ? { historyOrphaned: true } : {};
   }
 
   return {
-    conversationId: parentConversationId,
-    messageId: parentMessageId,
-    title: parentConversation.title ?? "Untitled",
+    forkParent: {
+      conversationId: parentConversationId,
+      messageId: parentMessageId,
+      title: parentConversation.title ?? "Untitled",
+    },
   };
 }
 
@@ -174,7 +189,7 @@ export function serializeConversationSummary(params: {
   } = params;
   const originChannel = parseChannelId(conversation.originChannel);
   const assistantAttention = buildAssistantAttention(attentionState);
-  const forkParent = buildForkParent(conversation, parentCache);
+  const forkLineage = buildForkLineage(conversation, parentCache);
 
   return {
     id: conversation.id,
@@ -208,7 +223,7 @@ export function serializeConversationSummary(params: {
       conversation,
       displayMeta?.groupId ?? null,
     ),
-    ...(forkParent ? { forkParent } : {}),
+    ...forkLineage,
     ...(conversation.archivedAt != null
       ? { archivedAt: conversation.archivedAt }
       : {}),

package/src/runtime/sync/documents-sidecar-publish.test.ts

@@ -0,0 +1,101 @@
+/**
+ * A scheduled, heartbeat, or background turn runs its document tools in a
+ * sidecar worker, whose local hub has no SSE subscriber. The documents-changed
+ * broadcast has to be handed to the daemon there, or the document edited while
+ * the user was not looking stays invisible on every client.
+ */
+
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+let notifyCount = 0;
+
+mock.module("./worker-daemon-notify.js", () => ({
+  NOTIFY_CONVERSATION_PERSISTED_IPC_METHOD:
+    "notify_conversation_persisted_externally",
+  NOTIFY_DOCUMENTS_CHANGED_IPC_METHOD: "notify_documents_changed_externally",
+  notifyDaemonConversationPersisted: async () => {},
+  notifyDaemonDocumentsChanged: async () => {
+    notifyCount++;
+  },
+}));
+
+import type { AssistantEventEnvelope } from "../../api/index.js";
+import { assistantEventHub } from "../assistant-event-hub.js";
+import {
+  _resetStreamStateForTesting,
+  disableStreamSeqStamping,
+} from "../assistant-stream-state.js";
+import {
+  DOCUMENTS_CHANGED_COALESCE_MS,
+  publishDocumentsChanged,
+} from "./resource-sync-events.js";
+
+async function settle(): Promise<void> {
+  await new Promise((resolve) =>
+    setTimeout(resolve, DOCUMENTS_CHANGED_COALESCE_MS + 50),
+  );
+}
+
+/** Run `publish`, then return the `sync_changed` events it put on the hub. */
+async function captureLocalPublishes(
+  publish: () => void,
+): Promise<AssistantEventEnvelope[]> {
+  await settle();
+  const received: AssistantEventEnvelope[] = [];
+  const subscription = assistantEventHub.subscribe({
+    type: "process",
+    callback: (event) => {
+      if (event.message.type === "sync_changed") {
+        received.push(event);
+      }
+    },
+  });
+  try {
+    publish();
+    await settle();
+    return received;
+  } finally {
+    subscription.dispose();
+  }
+}
+
+describe("publishDocumentsChanged in a sidecar worker", () => {
+  beforeEach(async () => {
+    await settle();
+    notifyCount = 0;
+    _resetStreamStateForTesting();
+  });
+
+  test("hands the broadcast to the daemon instead of publishing into a void", async () => {
+    disableStreamSeqStamping();
+
+    const events = await captureLocalPublishes(() => {
+      publishDocumentsChanged();
+    });
+
+    expect(notifyCount).toBe(1);
+    expect(events).toEqual([]);
+  });
+
+  test("coalesces a burst of worker writes into one hand-off", async () => {
+    disableStreamSeqStamping();
+
+    await captureLocalPublishes(() => {
+      for (let i = 0; i < 10; i++) {
+        publishDocumentsChanged();
+      }
+    });
+
+    expect(notifyCount).toBe(1);
+  });
+
+  test("publishes on the local hub in the daemon, where subscribers live", async () => {
+    const events = await captureLocalPublishes(() => {
+      publishDocumentsChanged();
+    });
+
+    expect(notifyCount).toBe(0);
+    expect(events).toHaveLength(1);
+    expect(events[0].message).toMatchObject({ type: "sync_changed" });
+  });
+});

package/src/runtime/sync/resource-sync-events.ts

@@ -9,7 +9,10 @@ import { getAvatarImagePath } from "../../util/platform.js";
 import { broadcastMessage } from "../assistant-event-hub.js";
 import { isStreamSeqStampingDisabled } from "../assistant-stream-state.js";
 import { publishSyncInvalidation } from "./sync-publisher.js";
-import { notifyDaemonConversationPersisted } from "./worker-daemon-notify.js";
+import {
+  notifyDaemonConversationPersisted,
+  notifyDaemonDocumentsChanged,
+} from "./worker-daemon-notify.js";
 
 /**
  * Derive the initiating client's id from request headers so a sync publish can
@@ -67,6 +70,81 @@ export function publishAppsChanged(originClientId?: string): void {
   void publishSyncInvalidation([SYNC_TAGS.appsList], originClientId);
 }
 
+/**
+ * How long a documents-list invalidation waits for the writes around it to
+ * settle before it is broadcast.
+ *
+ * Document writes arrive in bursts: the document-editor skill is instructed to
+ * stream a document as many small `document_update` calls, and the web editor
+ * autosaves as the user types. Every burst member publishes, and every publish
+ * makes each client drain its `documentsGet` queries (the per-conversation
+ * assets pill, the Library, the intelligence stats), during an SSE stream that
+ * is already saturated. Open editors track each individual write through
+ * `document_editor_update`, so the list-level invalidation only has to land
+ * once the burst settles.
+ */
+export const DOCUMENTS_CHANGED_COALESCE_MS = 150;
+
+/**
+ * Ceiling on how long an unbroken run of writes can defer the invalidation, so
+ * a document streamed in sub-window chunks still refreshes the list while it is
+ * being written instead of only when the turn ends.
+ */
+export const DOCUMENTS_CHANGED_MAX_DEFER_MS = 1_000;
+
+let documentsPublishTimer: ReturnType<typeof setTimeout> | undefined;
+let documentsPublishDeadline = 0;
+let documentsPublishOrigin: string | undefined;
+let documentsPublishOriginSeen = false;
+
+function flushDocumentsChanged(): void {
+  documentsPublishTimer = undefined;
+  documentsPublishDeadline = 0;
+  const originClientId = documentsPublishOrigin;
+  documentsPublishOrigin = undefined;
+  documentsPublishOriginSeen = false;
+
+  // In a sidecar worker (seq stamping disabled) the local hub has no SSE
+  // subscribers, so a local publish reaches no client and a document edited by
+  // a scheduled or background turn stays invisible. Hand off to the daemon,
+  // which republishes the invalidation where subscribers observe it. Such a
+  // turn has no originating client, so no `originClientId` is forwarded.
+  if (isStreamSeqStampingDisabled()) {
+    void notifyDaemonDocumentsChanged();
+    return;
+  }
+  void publishSyncInvalidation([SYNC_TAGS.documentsList], originClientId);
+}
+
+/**
+ * Invalidate the document list on every client, coalescing a burst of writes
+ * into a single broadcast (see {@link DOCUMENTS_CHANGED_COALESCE_MS}).
+ */
+export function publishDocumentsChanged(originClientId?: string): void {
+  if (!documentsPublishOriginSeen) {
+    documentsPublishOrigin = originClientId;
+    documentsPublishOriginSeen = true;
+  } else if (documentsPublishOrigin !== originClientId) {
+    // Writes from more than one client merged into this broadcast, so no single
+    // client may suppress it as its own echo.
+    documentsPublishOrigin = undefined;
+  }
+
+  const now = Date.now();
+  if (documentsPublishTimer) {
+    clearTimeout(documentsPublishTimer);
+  } else {
+    documentsPublishDeadline = now + DOCUMENTS_CHANGED_MAX_DEFER_MS;
+  }
+  documentsPublishTimer = setTimeout(
+    flushDocumentsChanged,
+    Math.max(
+      0,
+      Math.min(DOCUMENTS_CHANGED_COALESCE_MS, documentsPublishDeadline - now),
+    ),
+  );
+}
+
 export function publishPluginsChanged(originClientId?: string): void {
   void publishSyncInvalidation([SYNC_TAGS.pluginsList], originClientId);
 }

package/src/runtime/sync/worker-daemon-notify.test.ts

@@ -33,7 +33,9 @@ mock.module("../../ipc/cli-client.js", () => ({
 
 import {
   NOTIFY_CONVERSATION_PERSISTED_IPC_METHOD,
+  NOTIFY_DOCUMENTS_CHANGED_IPC_METHOD,
   notifyDaemonConversationPersisted,
+  notifyDaemonDocumentsChanged,
 } from "./worker-daemon-notify.js";
 
 describe("notifyDaemonConversationPersisted", () => {
@@ -67,3 +69,35 @@ describe("notifyDaemonConversationPersisted", () => {
     expect(calls).toHaveLength(1);
   });
 });
+
+describe("notifyDaemonDocumentsChanged", () => {
+  beforeEach(() => {
+    calls.length = 0;
+    nextResult = { ok: true };
+    shouldThrow = false;
+  });
+
+  test("asks the daemon to republish over the shared IPC method", async () => {
+    await notifyDaemonDocumentsChanged();
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0]!.method).toBe(NOTIFY_DOCUMENTS_CHANGED_IPC_METHOD);
+    expect(calls[0]!.params).toEqual({ body: {} });
+  });
+
+  test("swallows a failed IPC result (best-effort, no throw)", async () => {
+    nextResult = { ok: false, error: "daemon unreachable" };
+
+    const result = await notifyDaemonDocumentsChanged();
+    expect(result).toBeUndefined();
+    expect(calls).toHaveLength(1);
+  });
+
+  test("swallows a thrown IPC error (best-effort, no throw)", async () => {
+    shouldThrow = true;
+
+    const result = await notifyDaemonDocumentsChanged();
+    expect(result).toBeUndefined();
+    expect(calls).toHaveLength(1);
+  });
+});

package/src/runtime/sync/worker-daemon-notify.ts

@@ -1,13 +1,13 @@
 /**
- * Worker → daemon hand-off for conversation message-persist notifications.
+ * Worker → daemon hand-off for sync notifications a sidecar cannot deliver.
  *
  * Sidecar worker processes (schedule, memory) disable SSE seq stamping — the
  * daemon is the sole seq authority — so a worker's own `getCurrentSeq()`
- * reports `0` and its `publishConversationMessagesChanged` broadcast reaches no
- * SSE subscriber (those live in the daemon). After a worker persists a turn's
- * rows it hands the notification here; the daemon records an honest snapshot
- * anchor at its own seq and republishes the invalidation to real subscribers
- * (see `ipc/routes/conversation-sync-ipc-routes.ts`).
+ * reports `0` and its `sync_changed` broadcasts reach no SSE subscriber (those
+ * live in the daemon). A worker hands the notification here instead and the
+ * daemon republishes it to real subscribers (see
+ * `ipc/routes/conversation-sync-ipc-routes.ts`,
+ * `ipc/routes/documents-sync-ipc-routes.ts`).
  */
 
 import { cliIpcCall } from "../../ipc/cli-client.js";
@@ -22,6 +22,14 @@ const log = getLogger("worker-daemon-notify");
 export const NOTIFY_CONVERSATION_PERSISTED_IPC_METHOD =
   "notify_conversation_persisted_externally";
 
+/**
+ * IPC method the daemon exposes for the documents-changed hand-off. Shared by
+ * the worker caller and the daemon route registration so the wire name cannot
+ * drift.
+ */
+export const NOTIFY_DOCUMENTS_CHANGED_IPC_METHOD =
+  "notify_documents_changed_externally";
+
 /**
  * Short timeout: this is a fire-and-forget invalidation, not a request whose
  * result the worker consumes. A busy or unreachable daemon simply leaves the
@@ -61,3 +69,33 @@ export async function notifyDaemonConversationPersisted(
     );
   }
 }
+
+/**
+ * Ask the daemon to republish the documents-list invalidation.
+ *
+ * A scheduled or background turn runs its document tools in a sidecar worker,
+ * so the edit is real but the worker's own broadcast reaches nobody. This is
+ * the path that lets the user learn a document changed while they were not
+ * looking.
+ *
+ * Best-effort by design, like the conversation hand-off: an unreachable daemon
+ * is logged at debug and swallowed, and the client picks the change up on its
+ * next document-list fetch.
+ */
+export async function notifyDaemonDocumentsChanged(): Promise<void> {
+  try {
+    const result = await cliIpcCall(
+      NOTIFY_DOCUMENTS_CHANGED_IPC_METHOD,
+      { body: {} },
+      { timeoutMs: NOTIFY_TIMEOUT_MS },
+    );
+    if (!result.ok) {
+      log.debug(
+        { error: result.error },
+        "daemon documents-changed notify was not acknowledged",
+      );
+    }
+  } catch (err) {
+    log.debug({ err }, "daemon documents-changed notify failed");
+  }
+}