@vellumai/assistant 0.11.4 → 0.11.5-staging.1

package/src/notifications/assistant-reply-producer.ts

@@ -29,6 +29,7 @@ import {
 } from "../persistence/conversation-types.js";
 import { stringifyMessageContent } from "../persistence/message-content.js";
 import { isDesktopAttended } from "../runtime/desktop-presence.js";
+import { isWebConversationFocused } from "../runtime/web-presence.js";
 import { safeParseRecord } from "../util/json.js";
 import { emitNotificationSignal } from "./emit-signal.js";
 import {
@@ -45,6 +46,9 @@ const ASSISTANT_REPLY_PUSH_FLAG = "assistant-reply-push" as const;
 /** Gates the desktop-attended suppression below, on by default. */
 const DESKTOP_PRESENCE_FLAG = "desktop-presence-suppression" as const;
 
+/** Gates the web-focused suppression below, on by default. */
+const WEB_PRESENCE_FLAG = "web-presence-suppression" as const;
+
 /**
  * Collapse whitespace runs ahead of the sanitizers' truncation: blank lines and
  * list indentation would otherwise eat into the copy's length budget.
@@ -129,6 +133,27 @@ function readDesktopAttended(rlog: pino.Logger): boolean {
   }
 }
 
+/**
+ * Web presence, kept fail-open here for the same reason as
+ * {@link readDesktopAttended}: a presence read that fails has to send the
+ * push, not reach the producer's catch and silence it.
+ *
+ * No `actorPrincipalId`: the platform delivers this push to the assistant
+ * owner's device tokens, and a pod has exactly one owner, so any focused web
+ * tab is that owner's.
+ */
+function readWebConversationFocused(
+  conversationId: string,
+  rlog: pino.Logger,
+): boolean {
+  try {
+    return isWebConversationFocused(conversationId);
+  } catch (err) {
+    rlog.warn({ err }, "Web presence read failed; treating as unfocused");
+    return false;
+  }
+}
+
 export async function emitAssistantReplyNotification(params: {
   conversationId: string;
   assistantMessageId: string;
@@ -229,6 +254,14 @@ export async function emitAssistantReplyNotification(params: {
       isMacOriginatedUserMessage(initiatingMetadata) &&
       readDesktopAttended(rlog);
 
+    // Conversation-scoped web presence applies regardless of which device
+    // initiated the turn: a visible matching tab proves where this reply is
+    // currently being displayed, while the conversation id prevents an
+    // unrelated tab from suppressing the push.
+    const webFocused =
+      isAssistantFeatureFlagEnabled(WEB_PRESENCE_FLAG) &&
+      readWebConversationFocused(conversationId, rlog);
+
     await emitNotificationSignal({
       sourceEventName: "chat.assistant_reply",
       sourceChannel: "vellum",
@@ -243,10 +276,10 @@ export async function emitAssistantReplyNotification(params: {
         // opting into v2.
         urgency: "medium",
         isAsyncBackground: false,
-        // Read weakly, as "at the machine this landed on": the attended Mac
-        // that opened the turn renders the reply in-app, and its Dock unread
-        // badge carries it while the window is hidden.
-        visibleInSourceNow: desktopAttended,
+        // Read weakly, as "at the surface this landed on": the attended Mac
+        // or focused web tab that opened the turn renders the reply in-app,
+        // so a redundant push would only duplicate what's already on screen.
+        visibleInSourceNow: desktopAttended || webFocused,
       },
       contextPayload: {
         ...(requestedTitle ? { requestedTitle } : {}),

package/src/notifications/conversation-pairing.ts

@@ -30,6 +30,7 @@ import {
   getBindingByChannelChat,
   upsertOutboundBinding,
 } from "../persistence/external-conversation-store.js";
+import { publishConversationMessagesChanged } from "../runtime/sync/resource-sync-events.js";
 import { getLogger } from "../util/logger.js";
 import { withSqliteRetry } from "../util/sqlite-retry.js";
 import {
@@ -92,6 +93,13 @@ export interface PairingOptions {
  *
  * Invalid/stale targets at any level fall through to the next.
  *
+ * Passive vellum notifications (those without `requiresConversation`) never
+ * reach that order. They create nothing, and instead append their body to the
+ * producing conversation named by `sourceContextId` when it resolves, since
+ * that is the row the home feed's "Go to Conversation" button already targets.
+ * The returned `conversationId` is that producing conversation, with
+ * `createdNewConversation` false.
+ *
  * Errors are caught and logged — this function never throws so the
  * notification pipeline is not disrupted by pairing failures.
  */
@@ -117,20 +125,47 @@ export async function pairDeliveryWithConversation(
     const conversationAction = options?.conversationAction;
     const bindingContext = options?.bindingContext;
 
-    // Passive vellum notifications surface via the home feed alone and link
-    // back to the originating conversation via `signal.sourceContextId`.
-    // Materializing a fresh per-notification conversation just to host the
-    // seed message leaves a graveyard entry in the sidebar; skip it
-    // unconditionally when the producer did not opt in via
-    // `requiresConversation`. The decision engine's `reuse_existing` hint is
-    // also ignored here: even a successful reuse would append a seed message
-    // to a conversation that the user didn't ask for, and a failed reuse
-    // (stale target / source mismatch) falls through to `createConversation`
-    // — producing exactly the graveyard entry we want to avoid.
+    // Structured content blocks take precedence. They enable Surface-based
+    // rendering in the web/macOS/iOS apps (e.g. a card widget instead of
+    // plain text). Falls back to model-provided seed or runtime composer.
+    const messageContent = copy.seedContentBlocks
+      ? JSON.stringify(copy.seedContentBlocks)
+      : isConversationSeedSane(copy.conversationSeedMessage)
+        ? copy.conversationSeedMessage
+        : composeConversationSeed(signal, channel, copy);
+
+    // Passive vellum notifications link back to the originating conversation
+    // via `signal.sourceContextId` rather than materializing one of their own.
+    // A fresh per-notification conversation just to host the seed message
+    // leaves a graveyard entry in the sidebar, so nothing is created here when
+    // the producer did not opt in via `requiresConversation`. The decision
+    // engine's `reuse_existing` hint is ignored for the same reason: a failed
+    // reuse (stale target / source mismatch) falls through to
+    // `createConversation`, producing exactly the graveyard entry we want to
+    // avoid.
+    //
+    // The body is still appended to the producing conversation when
+    // `sourceContextId` resolves, because every route the user has into this
+    // notification ends at that conversation. Tapping the banner deep-links
+    // there, and resolves there with or without this append, since the
+    // broadcaster falls back to `sourceContextId` for the vellum deep link.
+    // The client suppresses the banner outright when that conversation is
+    // already on screen, leaving the transcript as the only place the
+    // notification can appear. The home feed aims its "Go to Conversation"
+    // button at the same row whenever it mirrors the signal.
+    //
+    // So this is deliberately not gated on home-feed eligibility: a signal the
+    // feed declines to mirror still reaches the user through the banner, and
+    // this row is what makes that landing honest.
     if (strategy === "start_new_conversation" && !signal.requiresConversation) {
+      const appended = await appendBodyToSourceConversation(
+        signal,
+        channel,
+        messageContent,
+      );
       return {
-        conversationId: null,
-        messageId: null,
+        conversationId: appended?.conversationId ?? null,
+        messageId: appended?.messageId ?? null,
         strategy,
         createdNewConversation: false,
         conversationFallbackUsed: false,
@@ -147,15 +182,6 @@ export async function pairDeliveryWithConversation(
       signal.conversationMetadata?.conversationType ??
       (strategy === "start_new_conversation" ? "standard" : "background");
 
-    // Structured content blocks take precedence — they enable Surface-based
-    // rendering in the web/macOS/iOS apps (e.g. a card widget instead of
-    // plain text). Falls back to model-provided seed or runtime composer.
-    const messageContent = copy.seedContentBlocks
-      ? JSON.stringify(copy.seedContentBlocks)
-      : isConversationSeedSane(copy.conversationSeedMessage)
-        ? copy.conversationSeedMessage
-        : composeConversationSeed(signal, channel, copy);
-
     // Attempt to reuse an existing conversation when the model requests it
     if (conversationAction?.action === "reuse_existing") {
       const targetId = conversationAction.conversationId;
@@ -456,3 +482,67 @@ export async function pairDeliveryWithConversation(
     };
   }
 }
+
+/**
+ * Append a delivered notification body to the conversation that produced it.
+ *
+ * Passive notifications never materialize a conversation of their own, so the
+ * home feed points "Go to Conversation" at the producing conversation
+ * (`resolveHomeFeedMirror` prefers `sourceContextId`). Writing the body there
+ * makes that button truthful: whenever it renders, the conversation it opens
+ * contains the notification the user tapped.
+ *
+ * Reuse only. Producers may pass sentinels (job ids, call session ids,
+ * `access-req-*` strings) as `sourceContextId`; those resolve to nothing and
+ * append nothing, which matches the button staying hidden for them.
+ *
+ * This covers vellum deliveries only, since no other channel takes the
+ * passive branch. A signal routed away from vellum still gets a card, so
+ * `writeHomeFeedItemForSignal` writes the body itself when no vellum
+ * conversation was paired. Between them the button holds whatever the
+ * routing was, and only one of the two ever writes.
+ *
+ * Indexing is skipped for parity with the other notification write paths:
+ * notification copy is delivery audit, not conversational memory.
+ */
+async function appendBodyToSourceConversation(
+  signal: NotificationSignal,
+  channel: NotificationChannel,
+  messageContent: string,
+): Promise<{ conversationId: string; messageId: string } | null> {
+  const sourceContextId = signal.sourceContextId;
+  if (!sourceContextId) {
+    return null;
+  }
+
+  let existing: ReturnType<typeof getConversation>;
+  try {
+    existing = getConversation(sourceContextId);
+  } catch {
+    return null;
+  }
+  if (!existing) {
+    return null;
+  }
+
+  const message = await addMessage(existing.id, "assistant", messageContent, {
+    skipIndexing: true,
+  });
+  // `addMessage` projects attention metadata alone, so a client with this
+  // conversation open needs the messages tag to refetch the transcript. A
+  // notification the user taps through to has every chance of landing on an
+  // already-open conversation.
+  publishConversationMessagesChanged(existing.id);
+
+  log.info(
+    {
+      signalId: signal.signalId,
+      channel,
+      conversationId: existing.id,
+      messageId: message.id,
+    },
+    "Appended notification body to producing conversation",
+  );
+
+  return { conversationId: existing.id, messageId: message.id };
+}

package/src/notifications/edit-notification.ts

@@ -22,6 +22,7 @@ import {
   updateDeliveryRenderedCopy,
 } from "./deliveries-store.js";
 import { getBroadcaster } from "./emit-signal.js";
+import { updateFeedItemConversationMessage } from "./home-feed-side-effect.js";
 import { nonEmpty } from "./notification-utils.js";
 import type { NotificationChannel } from "./types.js";
 
@@ -119,24 +120,49 @@ export async function editNotification(
       { feedItemId, signalId },
       "Feed item has no persisted decision — skipping channel updates",
     );
-    return { feedItem, channels: [] };
   }
 
-  const deliveries = findDeliveriesByDecisionId(decision.id);
-  const channels = await updateChannelDeliveries(deliveries, {
-    title,
-    body: params.body,
-  });
+  const deliveries = decision ? findDeliveriesByDecisionId(decision.id) : [];
+  const { channels, rewrittenMessageIds } = await updateChannelDeliveries(
+    deliveries,
+    { title, body: params.body },
+  );
+
+  // The delivery walk covers a conversation row only while its delivery reads
+  // sent, so the card carries the id of the row behind it and this closes
+  // whatever the walk missed. Runs after it, and skips a row the walk just
+  // rewrote, so the two never both write. Body edits only: a title-only patch
+  // leaves the feed summary alone, and the row holds the body.
+  if (params.body !== undefined) {
+    updateFeedItemConversationMessage(
+      feedItem,
+      params.body,
+      rewrittenMessageIds,
+    );
+  }
 
   return { feedItem, channels };
 }
 
+/**
+ * Walk the recorded deliveries and let each channel adapter apply the patch.
+ *
+ * Alongside the per-channel outcomes this reports the message ids the
+ * adapters rewrote, which is what tells the caller whether the row behind the
+ * card still needs writing. Only body patches contribute: an adapter reports
+ * its message id on a title-only patch too, without having touched the
+ * conversation row.
+ */
 async function updateChannelDeliveries(
   deliveries: NotificationDeliveryRow[],
   patch: { title?: string; body?: string },
-): Promise<ChannelEditResult[]> {
+): Promise<{
+  channels: ChannelEditResult[];
+  rewrittenMessageIds: ReadonlySet<string>;
+}> {
   const broadcaster = getBroadcaster();
   const results: ChannelEditResult[] = [];
+  const rewrittenMessageIds = new Set<string>();
 
   for (const delivery of deliveries) {
     const channel = delivery.channel as NotificationChannel;
@@ -167,6 +193,7 @@ async function updateChannelDeliveries(
           deliveryId: delivery.id,
           destination: delivery.destination,
           messageId: delivery.messageId,
+          conversationId: delivery.conversationId,
         },
         patch,
       );
@@ -183,6 +210,9 @@ async function updateChannelDeliveries(
         renderedTitle: patch.title,
         renderedBody: patch.body,
       });
+      if (patch.body !== undefined && result.messageId) {
+        rewrittenMessageIds.add(result.messageId);
+      }
       results.push({
         channel,
         deliveryId: delivery.id,
@@ -203,5 +233,5 @@ async function updateChannelDeliveries(
     }
   }
 
-  return results;
+  return { channels: results, rewrittenMessageIds };
 }

package/src/notifications/emit-signal.ts

@@ -525,21 +525,19 @@ export async function emitNotificationSignal<TEventName extends string>(
     // Step 5: Mirror background-origin signals into the home activity feed.
     // The helper itself decides whether to write (background filter); we
     // catch and log so a feed-write failure cannot poison the dispatch result.
-    // Pass the paired vellum delivery conversation as a fallback so producers
-    // whose `sourceContextId` is a sentinel string (e.g. heartbeat startup,
-    // credential health, watcher emits, scheduler retries-exhausted) still
-    // get a "Go to Convo" button — pointing at the conversation the
-    // broadcaster paired the notification with.
-    const pairedVellumConversationId = dispatchResult.deliveryResults.find(
+    // Pass the vellum delivery outcome so producers whose `sourceContextId` is
+    // a sentinel string (e.g. heartbeat startup, credential health, watcher
+    // emits, scheduler retries-exhausted) still get a "Go to Convo" button
+    // pointing at the conversation the broadcaster paired, and so the feed can
+    // tell whether that delivery left a conversation row an edit can reach.
+    const vellumDelivery = dispatchResult.deliveryResults.find(
       (r) => r.channel === "vellum",
-    )?.conversationId;
-    await writeHomeFeedItemForSignal(
-      signal,
-      decision,
-      pairedVellumConversationId,
-    ).catch((err) => {
-      log.warn({ err, signalId }, "writeHomeFeedItemForSignal threw");
-    });
+    );
+    await writeHomeFeedItemForSignal(signal, decision, vellumDelivery).catch(
+      (err) => {
+        log.warn({ err, signalId }, "writeHomeFeedItemForSignal threw");
+      },
+    );
 
     log.info(
       {

package/src/notifications/home-feed-side-effect.ts

@@ -17,31 +17,59 @@ import {
   feedItemSchema,
 } from "../home/feed-types.js";
 import { appendFeedItem } from "../home/feed-writer.js";
-import { getConversation } from "../persistence/conversation-crud.js";
+import {
+  addMessage,
+  getConversation,
+  getMessageById,
+  updateMessageContent,
+} from "../persistence/conversation-crud.js";
 import { isBackgroundConversationType } from "../persistence/conversation-types.js";
+import { publishConversationMessagesChanged } from "../runtime/sync/resource-sync-events.js";
 import { getLogger } from "../util/logger.js";
 import { normalizeTitle, stripMarkdown } from "../util/short-title.js";
 import { isConversationSeedSane } from "./conversation-seed-composer.js";
 import { deriveTitle } from "./copy-composer.js";
 import { readPayloadString } from "./notification-utils.js";
 import type { NotificationSignal } from "./signal.js";
-import type { NotificationDecision, RenderedChannelCopy } from "./types.js";
+import type {
+  NotificationDecision,
+  NotificationDeliveryResult,
+  RenderedChannelCopy,
+} from "./types.js";
 
 const log = getLogger("home-feed-side-effect");
 
+/**
+ * Metadata key holding the id of the conversation message this module wrote
+ * for a card.
+ *
+ * Only cards holding a row no delivery adapter will rewrite carry it, and it
+ * is the handle `updateFeedItemConversationMessage` rewrites on an edit.
+ * `metadata` is a free-form record on the wire, so this stays a daemon-side
+ * convention and needs no schema field, the same way `scheduleId` rides along
+ * below.
+ *
+ * Reserved: producer `contextPayload` also lands in `metadata`, so the key is
+ * stripped from it before this module writes its own. A producer able to set
+ * it would otherwise hand an edit an arbitrary message id to overwrite.
+ */
+const CONVERSATION_MESSAGE_ID_KEY = "notificationConversationMessageId";
+
 /**
  * Append a `FeedItem` for the given notification signal when the
  * filter criteria pass.
  *
- * `fallbackConversationId` is used as the feed item's "Go to Convo"
- * navigation target when `signal.sourceContextId` doesn't resolve to a
- * real conversation row. The notification broadcaster pairs the vellum
- * delivery with a conversation (newly created or reused) before this
- * function runs, so callers can thread that paired id through here for
- * producers whose `sourceContextId` is a sentinel (heartbeat startup,
- * credential health, watcher emits, scheduler retries-exhausted) — the
- * feed item will then carry the paired delivery conversation and the
- * "Go to Convo" button can render.
+ * `vellumDelivery` is this signal's vellum delivery outcome, and it settles
+ * two questions here.
+ *
+ * Its conversation is a navigation target standing in for a
+ * `signal.sourceContextId` that doesn't resolve to a real conversation row,
+ * so producers passing a sentinel (heartbeat startup, credential health,
+ * watcher emits, scheduler retries-exhausted) still render a "Go to Convo"
+ * button.
+ *
+ * It also settles which row backs the card and who rewrites it on an edit,
+ * which `resolveOwnedConversationMessageId` works through below.
  *
  * Returns the persisted `FeedItem`, or `null` if the signal does not
  * qualify for home-feed mirroring (non-background origin AND no
@@ -50,10 +78,10 @@ const log = getLogger("home-feed-side-effect");
 export async function writeHomeFeedItemForSignal(
   signal: NotificationSignal,
   decision: NotificationDecision,
-  fallbackConversationId?: string,
+  vellumDelivery?: NotificationDeliveryResult,
 ): Promise<FeedItem | null> {
   const { mirror, sourceConversationId, sourceScheduleJobId } =
-    resolveHomeFeedMirror(signal, fallbackConversationId);
+    resolveHomeFeedMirror(signal, vellumDelivery?.conversationId);
   if (!mirror) {
     return null;
   }
@@ -109,6 +137,9 @@ export async function writeHomeFeedItemForSignal(
     !Array.isArray(signal.contextPayload)
       ? { ...signal.contextPayload }
       : undefined;
+  // Producer payloads reach the card verbatim, and this key addresses a
+  // message row for rewriting, so only this module may set it.
+  delete baseMetadata?.[CONVERSATION_MESSAGE_ID_KEY];
 
   // Link scheduled-run notifications back to their schedule. `notify`-mode
   // jobs put `scheduleId` directly in the context payload; `execute`-mode (and
@@ -152,8 +183,180 @@ export async function writeHomeFeedItemForSignal(
     return null;
   }
 
-  await appendFeedItem(item);
-  return item;
+  // Resolved once the card is known to be writable, since the only reason to
+  // put a notification body in a conversation is that a card sends the user
+  // there. Validating first keeps the one rejection this function controls
+  // from leaving a message behind with no card to explain it. The id joins
+  // free-form metadata, which no schema rule can turn away.
+  const conversationMessageId = await resolveOwnedConversationMessageId(
+    signal,
+    vellumDelivery,
+    sourceConversationId,
+    resolvedSummary,
+  );
+  const card: FeedItem = conversationMessageId
+    ? {
+        ...item,
+        metadata: {
+          ...(item.metadata ?? {}),
+          [CONVERSATION_MESSAGE_ID_KEY]: conversationMessageId,
+        },
+      }
+    : item;
+
+  await appendFeedItem(card);
+  return card;
+}
+
+/**
+ * Resolve the conversation row backing this card, writing one if the card
+ * would otherwise have no body in the conversation it opens.
+ *
+ * The card records the row whoever wrote it, rather than only the rows it
+ * expects an edit to miss. Whether a delivery adapter will actually rewrite a
+ * row is a property of the durable delivery state at edit time, which a
+ * dispatch result cannot predict: a send can succeed and lose its status
+ * write, leaving a row that reads pending. `editNotification` settles that
+ * question by rewriting through the card only when the delivery walk did not.
+ *
+ * A vellum delivery that paired a conversation already wrote the body there,
+ * so its row is the one to record. Guardian producers pair a fresh
+ * conversation instead of the one the card opens, and their row is left
+ * unrecorded: a handle has to address the conversation behind the button, and
+ * `updateFeedItemConversationMessage` refuses anything else.
+ */
+async function resolveOwnedConversationMessageId(
+  signal: NotificationSignal,
+  vellumDelivery: NotificationDeliveryResult | undefined,
+  sourceConversationId: string | undefined,
+  summary: string,
+): Promise<string | undefined> {
+  if (vellumDelivery?.conversationId) {
+    return vellumDelivery.conversationId === sourceConversationId
+      ? vellumDelivery.messageId
+      : undefined;
+  }
+  if (!sourceConversationId) {
+    return undefined;
+  }
+  return appendSummaryToFeedTarget(signal, sourceConversationId, summary);
+}
+
+/**
+ * Write the card's own summary into the conversation its "Go to Convo"
+ * button opens, returning the id of the row written.
+ *
+ * That button targets the producing conversation whatever the routing, but
+ * only the vellum delivery writes a notification body into a conversation
+ * (`pairDeliveryWithConversation` appends there for passive signals). A
+ * signal the decision engine routes to Slack or Telegram alone pairs no
+ * vellum conversation, so without this the button opens a conversation that
+ * never received what the card shows. A paired vellum id means that write
+ * already happened, and this is skipped.
+ *
+ * The caller has already read `sourceConversationId` back from the store to
+ * gate the mirror, so the row is known to exist and needs no second lookup:
+ * with no paired id to fall back on, a resolved target can only be the
+ * producing conversation itself.
+ *
+ * Indexing is skipped for parity with the other notification write paths:
+ * notification copy is delivery audit, not conversational memory. Failures
+ * are logged rather than thrown, so a conversation write cannot cost the
+ * user a card; the card just goes out without a rewritable row.
+ */
+async function appendSummaryToFeedTarget(
+  signal: NotificationSignal,
+  conversationId: string,
+  summary: string,
+): Promise<string | undefined> {
+  try {
+    const message = await addMessage(conversationId, "assistant", summary, {
+      skipIndexing: true,
+    });
+    publishConversationMessagesChanged(conversationId);
+    log.info(
+      {
+        signalId: signal.signalId,
+        conversationId,
+        messageId: message.id,
+      },
+      "Appended notification body to the feed item's conversation",
+    );
+    return message.id;
+  } catch (err) {
+    log.warn(
+      { err, signalId: signal.signalId, conversationId },
+      "Failed to append notification body to the feed item's conversation",
+    );
+    return undefined;
+  }
+}
+
+/**
+ * Rewrite the conversation message behind a card, keeping an edited card and
+ * the conversation it opens in step.
+ *
+ * Notification edits reach conversation content through the delivery rows the
+ * broadcaster recorded, which is how the vellum adapter rewrites the row its
+ * pairing wrote. That walk covers a row only while its delivery reads sent, so
+ * this is the backstop for every way it can miss one: a delivery that failed,
+ * a row that was never recorded, a signal with no deliveries at all, and a
+ * send whose status write was lost after the message went out.
+ *
+ * `alreadyRewritten` carries the message ids the delivery walk reported
+ * rewriting, so the common case where the adapter got there first costs
+ * nothing and no row is written twice.
+ *
+ * The row holds the body, and the feed rewrites its summary only when the
+ * patch carries one, so the caller applies this for body edits alone.
+ *
+ * Never throws. It runs last, after the feed patch and the channel updates
+ * have landed, so anything it cannot do is reported as "no rewrite" rather
+ * than failing an edit that has already partly applied. Returns whether a row
+ * was rewritten.
+ */
+export function updateFeedItemConversationMessage(
+  item: FeedItem,
+  body: string,
+  alreadyRewritten?: ReadonlySet<string>,
+): boolean {
+  const messageId = item.metadata?.[CONVERSATION_MESSAGE_ID_KEY];
+  if (typeof messageId !== "string" || messageId.length === 0) {
+    return false;
+  }
+  if (alreadyRewritten?.has(messageId)) {
+    return false;
+  }
+  try {
+    // Scoped to the card's own conversation so the handle can only ever
+    // address a row inside what the card opens, whatever put it in the
+    // metadata. Guarded with the write: a store that cannot answer the
+    // question is not grounds for failing an edit already applied to the feed
+    // and the channels.
+    if (
+      !item.conversationId ||
+      !getMessageById(messageId, item.conversationId)
+    ) {
+      log.warn(
+        { feedItemId: item.id, messageId },
+        "Feed item message handle does not address a row in its conversation, leaving it alone",
+      );
+      return false;
+    }
+    updateMessageContent(messageId, body);
+    publishConversationMessagesChanged(item.conversationId);
+    log.info(
+      { feedItemId: item.id, messageId },
+      "Rewrote the conversation message behind an edited feed item",
+    );
+    return true;
+  } catch (err) {
+    log.error(
+      { err, feedItemId: item.id, messageId },
+      "Failed to rewrite the conversation message behind an edited feed item",
+    );
+    return false;
+  }
 }
 
 /**

package/src/notifications/types.ts

@@ -150,6 +150,11 @@ export interface ChannelUpdateContext {
   deliveryId: string;
   destination: string;
   messageId: string | null;
+  /**
+   * Conversation the delivery paired, for adapters whose message lives in one.
+   * Channel-native adapters patch a channel message and leave this unread.
+   */
+  conversationId?: string | null;
 }
 
 // -- Conversation action types ------------------------------------------------

package/src/permissions/AGENTS.md

@@ -0,0 +1,16 @@
+# Permissions: Agent Instructions
+
+This directory is the assistant's **client** of gateway-owned risk classification and trust rules, plus the assistant-owned decision that follows. Keep the split:
+
+- **Gateway owns:** risk classification (`gateway/src/risk/*`, entered through the `classify_risk` IPC method), the trust rules that lower or raise a classified risk (applied inside the gateway classifiers and surfaced only as the classified level plus `matchType: "user_rule"`), the auto-approve thresholds and channel-permission cells, and the per-actor `TrustClass` verdict.
+- **Assistant owns:** the turn's actor and its capabilities (`runtime/capabilities.ts`), the sensitive-tool capability floor (`tools/tool-approval-handler.ts`), the allow / prompt / deny decision over risk × threshold × capabilities (`check()` here, `DefaultApprovalPolicy`), the prompt UX (`prompter.ts`), execution, and the `tool_invocations` audit row.
+
+Rules that follow from the split:
+
+- **Do not add a risk classifier, risk table, or trust-rule matcher under `assistant/src`.** If a tool's risk is wrong or a rule cannot cover it, the fix is in `gateway/src/risk/` (or the tool's `defaultRiskLevel`, which the gateway uses for tools without a dedicated classifier).
+- **Classify once per tool invocation.** `classifyRisk()` is the only call into the gateway; the executor takes it before the pre-execution gates and hands the result to `checkPermission` and `check()`. Do not re-classify downstream, and do not memoise the result in the daemon: the inputs (rules, config, skill content) change out from under it, and the gateway already memoises the expensive part.
+- **Read the classification, do not re-derive it.** The allowlist ladder is `classification.allowlistOptions`; there are no per-tool option builders here. Elevations, `matchType` checks, and option ladders come from the `RiskClassificationWithMeta` the gateway returned. A daemon-side "defense in depth" copy of a gateway rule is a second source of truth, not a defense.
+- **Types cross the boundary from the wire contract.** The `classify_risk` request and response are `ClassifyRiskIpcParamsSchema` / `ClassifyRiskIpcResponseSchema` in `@vellumai/gateway-client`; fields the daemon carries from the response are typed off `ClassifyRiskIpcResponse`, never re-declared. `src/__tests__/risk-classification-boundary-guard.test.ts` pins the single call site and the absence of local classifiers.
+- The one daemon-side adjustment to a classification is the bash sandbox symlink-escape re-check (`applyBashSymlinkEscapeCheck`), because it needs the assistant's filesystem; it only ever revokes auto-approve.
+
+The architecture doc for this area is [`docs/architecture/security.md`](../../docs/architecture/security.md).