@vellumai/assistant 0.11.8 → 0.11.9-staging.1

package/src/live-voice/live-voice-photo.ts

@@ -1,12 +1,13 @@
 /**
- * Persisting an image that arrives during a live-voice call, on its own.
+ * Persisting a camera image on its own, outside any turn.
  *
  * Two kinds arrive this way and both take the same route: a photo the user
- * snapped with the shutter, and an ambient camera frame the client's gate kept.
+ * snapped with the shutter on a call, and an ambient camera frame the client's
+ * gate kept, which arrives from a call and from the text-chat composer alike.
  * Each lands in the conversation as its own user message, the moment it
  * arrives, and **runs no turn**. That single choice is what makes the order of
- * image and speech irrelevant: whatever the user says next, before or after,
- * is answered by a model whose history already contains the picture.
+ * image and message irrelevant: whatever the user says or types next, before
+ * or after, is answered by a model whose history already contains the picture.
  *
  * A kept frame carries the sight tag as well, which is what lets retention age
  * it out of the model's context while the transcript keeps it. A shutter photo
@@ -75,13 +76,19 @@ import {
   persistQueuedMessageBody,
 } from "../daemon/conversation-messaging.js";
 import { findConversation } from "../daemon/conversation-registry.js";
-import { getOrCreateConversation } from "../daemon/conversation-store.js";
+import {
+  getConversationIfExists,
+  isSameIncarnation,
+} from "../daemon/conversation-store.js";
+import type { TrustContext } from "../daemon/trust-context-types.js";
 import {
   deleteOrphanAttachments,
   resolveAttachmentsForPersist,
 } from "../persistence/attachments-store.js";
 import {
+  getConversation,
   getMessageById,
+  MessageInsertPreconditionError,
   recordConversationPersistedSeq,
 } from "../persistence/conversation-crud.js";
 import { broadcastMessage } from "../runtime/assistant-event-hub.js";
@@ -140,7 +147,11 @@ export interface LiveVoicePhotoResult {
  */
 interface StandaloneImageQueue {
   tail: Promise<void>;
-  queuedSightFrame: { superseded: boolean; attachmentId: string } | null;
+  queuedSightFrame: {
+    superseded: boolean;
+    attachmentId: string;
+    content: string;
+  } | null;
   outstanding: number;
 }
 
@@ -163,6 +174,7 @@ async function enqueueStandaloneImagePersist(
   conversationId: string,
   attachmentId: string,
   kind: "photo" | "sight_frame",
+  content: string,
   job: () => Promise<LiveVoicePhotoResult>,
 ): Promise<LiveVoicePhotoResult> {
   let queue = standaloneImageQueues.get(conversationId);
@@ -176,7 +188,7 @@ async function enqueueStandaloneImagePersist(
   }
   const chained = queue;
 
-  const ticket = { superseded: false, attachmentId };
+  const ticket = { superseded: false, attachmentId, content };
   if (kind === "sight_frame") {
     if (chained.queuedSightFrame) {
       chained.queuedSightFrame.superseded = true;
@@ -195,7 +207,12 @@ async function enqueueStandaloneImagePersist(
         { conversationId, attachmentId: ticket.attachmentId },
         "A newer camera frame replaced one still waiting to persist",
       );
-      reclaimDroppedFrame(ticket.attachmentId);
+      reclaimOrDefer(
+        conversationId,
+        [ticket.attachmentId],
+        ticket.content,
+        uuidv7(),
+      );
       return { ok: false };
     }
     return job();
@@ -232,10 +249,12 @@ async function enqueueStandaloneImagePersist(
  * Each caller owes the invariant in the first line. The supersede and timeout
  * paths have it by construction, neither having reached the persist; the
  * thrown path establishes it by checking that no row was inserted
- * ({@link messageMayExist}), because a persist can fail after `addMessage`
- * succeeded. {@link deleteOrphanAttachments} being link-aware is the second
- * backstop rather than the only one: a failure between the insert and the link
- * leaves a row that references the attachment with no link to protect it.
+ * ({@link insertedMessageState}), because a persist can fail after `addMessage`
+ * succeeded, and a path that cannot read that answer waits for it through
+ * {@link deferFrameReclaimDecision} rather than guessing.
+ * {@link deleteOrphanAttachments} being link-aware is the second backstop
+ * rather than the only one: a failure between the insert and the link leaves a
+ * row that references the attachment with no link to protect it.
  *
  * The reclaim names the id the caller handed in, which is not always the id
  * the row ended up referencing: conversation scoping clones an attachment
@@ -247,17 +266,41 @@ async function enqueueStandaloneImagePersist(
  * and one that failed to persist is theirs to retry, not the daemon's to
  * delete.
  *
- * Best effort. Losing a row's bytes is not worth failing a call over.
+ * Never throws, and reports whether the store answered. A delete can fail on
+ * the same contention the rest of this module waits out, and the caller owes
+ * the upload an outcome rather than a log line.
  */
-function reclaimDroppedFrame(attachmentId: string): void {
+function reclaimDroppedFrame(attachmentIds: readonly string[]): boolean {
   try {
-    deleteOrphanAttachments([attachmentId]);
+    deleteOrphanAttachments([...attachmentIds]);
+    return true;
   } catch (err) {
     log.warn(
-      { err, attachmentId },
-      "Could not reclaim a dropped live-voice camera frame",
+      { err, attachmentIds },
+      "Could not reclaim a dropped camera frame",
     );
+    return false;
+  }
+}
+
+/**
+ * Give the upload up, and hand it to the recheck when the store refuses.
+ *
+ * `messageId` is the id the row would carry, so a later pass asks the right
+ * question: a caller that attempted an insert passes the id it used, and one
+ * that never reached an insert passes a fresh id, which reads absent as soon as
+ * the store is readable and so retries exactly this delete.
+ */
+function reclaimOrDefer(
+  conversationId: string,
+  attachmentIds: readonly string[],
+  content: string,
+  messageId: string,
+): void {
+  if (reclaimDroppedFrame(attachmentIds)) {
+    return;
   }
+  deferFrameReclaimDecision(conversationId, messageId, attachmentIds, content);
 }
 
 /** Conversations with a standalone-image persist still in flight. */
@@ -265,6 +308,200 @@ export function _standaloneImageQueueSizeForTests(): number {
   return standaloneImageQueues.size;
 }
 
+/**
+ * How long to wait before asking the store again about a frame whose fate it
+ * could not report.
+ *
+ * The quick cadence covers the ordinary outage, a migration or a writer holding
+ * the database, which clears in seconds. One that outlasts those passes steps
+ * down to a cadence that can wait all day without filling the log. There is no
+ * final pass: giving the record up is the one outcome that loses the bytes for
+ * good, nothing else in the daemon collecting an attachment no caller names.
+ */
+const RECLAIM_RECHECK_MS = 30_000;
+const RECLAIM_RECHECK_SLOW_MS = 300_000;
+/** Passes at the quick cadence before a record steps down to the slow one. */
+const RECLAIM_RECHECK_QUICK_PASSES = 10;
+
+interface PendingFrameReclaim {
+  conversationId: string;
+  messageId: string;
+  /**
+   * Every id this attempt is answerable for: the one the caller handed in, and
+   * any the persist materialized for itself. A pre-uploaded frame already
+   * linked to another conversation is cloned into this one under a fresh id,
+   * and the caller's id reclaims nothing for it, that row still being linked
+   * where it came from.
+   */
+  attachmentIds: readonly string[];
+  /** Row text, so a frame found to have landed can still be announced. */
+  content: string;
+  attempts: number;
+}
+
+/**
+ * Frames waiting on an answer, held for as long as this process lives.
+ *
+ * In memory on purpose: the record exists because the store could not be read,
+ * so writing it to that store is circular. A process that dies inside the
+ * outage therefore loses it, which leaves the upload in the same position as
+ * every other attachment nothing links, since the daemon has no orphan sweep.
+ */
+const pendingFrameReclaims: PendingFrameReclaim[] = [];
+let reclaimRecheckTimer: ReturnType<typeof setTimeout> | null = null;
+
+/**
+ * Hold a frame whose outcome the store would not report, and settle it once
+ * the store answers.
+ *
+ * Both the refusal a caller sees and the upload behind it are this module's to
+ * settle: a refused frame is reported as handled, and nothing else in the
+ * daemon collects an attachment no caller names, collection being
+ * candidate-driven with no sweep. Reclaiming on the spot is the other wrong
+ * answer, because "could not read" is not "no row", and a row that landed can
+ * reference the bytes through content whose link write failed. So the question
+ * is asked again later and only an answer decides it.
+ *
+ * `messageId` is the id the row would carry. A path that never reached an
+ * insert passes the id it would have used, which reads absent the moment the
+ * store is readable, and readable is the whole of what that path is waiting
+ * for.
+ */
+function deferFrameReclaimDecision(
+  conversationId: string,
+  messageId: string,
+  attachmentIds: readonly string[],
+  content: string,
+): void {
+  pendingFrameReclaims.push({
+    conversationId,
+    messageId,
+    attachmentIds,
+    content,
+    attempts: 0,
+  });
+  scheduleFrameReclaimRecheck();
+}
+
+/**
+ * The wait before the next pass: quick while any record is still in its early
+ * passes, slow once every one of them has outlasted those.
+ */
+function nextFrameReclaimRecheckDelay(): number {
+  return pendingFrameReclaims.some(
+    (pending) => pending.attempts < RECLAIM_RECHECK_QUICK_PASSES,
+  )
+    ? RECLAIM_RECHECK_MS
+    : RECLAIM_RECHECK_SLOW_MS;
+}
+
+function scheduleFrameReclaimRecheck(): void {
+  if (reclaimRecheckTimer || pendingFrameReclaims.length === 0) {
+    return;
+  }
+  reclaimRecheckTimer = setTimeout(() => {
+    reclaimRecheckTimer = null;
+    drainFrameReclaimRechecks();
+  }, nextFrameReclaimRecheckDelay());
+  // A pending reclaim is never a reason to keep the process alive.
+  reclaimRecheckTimer.unref?.();
+}
+
+/**
+ * Deliver a row the client was told had not landed.
+ *
+ * The refusal it got is not destructive: it retracts a frame the client was
+ * showing as pending and does nothing else, so this arrives as an ordinary
+ * event for a message the client has never seen and the transcript converges
+ * without a reload. A row that reads as existing is proof its conversation is
+ * there too, the message being a foreign key into it, so what the announce
+ * writes has somewhere to go.
+ *
+ * The persist unwound its own history push before it threw, so the resident
+ * history no longer matches the rows and the next turn reloads rather than
+ * reusing what it holds.
+ */
+function announceDeferredImage(pending: PendingFrameReclaim): void {
+  findConversation(pending.conversationId)?.markHistoryStale();
+  try {
+    announcePersistedImage(
+      pending.conversationId,
+      pending.content,
+      pending.messageId,
+    );
+  } catch (err) {
+    log.warn(
+      {
+        err,
+        conversationId: pending.conversationId,
+        messageId: pending.messageId,
+      },
+      "Persisted a standalone image but could not announce it",
+    );
+  }
+}
+
+/**
+ * Ask the store again about every frame waiting on it.
+ *
+ * A row that exists means the frame reached the transcript, so its bytes are
+ * spoken for and the client is told about the row it was never given. Absent
+ * means the write never landed and the upload is this module's to give up. A
+ * store that still will not answer, and a delete that answers by failing, are
+ * the same situation here: ask again, for as long as that takes.
+ */
+function drainFrameReclaimRechecks(): void {
+  for (const pending of pendingFrameReclaims.splice(0)) {
+    const inserted = insertedMessageState(
+      pending.conversationId,
+      pending.messageId,
+    );
+    if (inserted === "exists") {
+      announceDeferredImage(pending);
+      continue;
+    }
+    if (inserted === "absent" && reclaimDroppedFrame(pending.attachmentIds)) {
+      continue;
+    }
+    keepWaitingForStore(pending);
+  }
+  scheduleFrameReclaimRecheck();
+}
+
+/**
+ * Put a record back for another pass, counting the attempt so the cadence can
+ * step down. The record is never dropped: it is the only handle on an upload
+ * nothing else in the daemon would collect.
+ */
+function keepWaitingForStore(pending: PendingFrameReclaim): void {
+  pending.attempts += 1;
+  if (pending.attempts === RECLAIM_RECHECK_QUICK_PASSES) {
+    log.warn(
+      {
+        conversationId: pending.conversationId,
+        attachmentIds: pending.attachmentIds,
+      },
+      "Still cannot settle a camera frame; asking less often until the store answers",
+    );
+  }
+  pendingFrameReclaims.push(pending);
+}
+
+/** Frames whose outcome the store has not reported yet. */
+export function _pendingFrameReclaimCountForTests(): number {
+  return pendingFrameReclaims.length;
+}
+
+/** The wait the next recheck pass would use. */
+export function _nextFrameReclaimRecheckDelayForTests(): number {
+  return nextFrameReclaimRecheckDelay();
+}
+
+/** Ask the store now rather than on the recheck timer. */
+export function _drainFrameReclaimRechecksForTests(): void {
+  drainFrameReclaimRechecks();
+}
+
 /**
  * Take the conversation's processing flag once it is free, or return false on
  * timeout having taken nothing.
@@ -280,17 +517,28 @@ export function _standaloneImageQueueSizeForTests(): number {
  * means nothing was taken and nothing needs releasing.
  */
 async function acquireProcessingFlag(conversation: {
-  isProcessing: () => boolean;
-  setProcessing: (value: boolean) => void;
-}): Promise<boolean> {
+  acquireProcessingFenced: () => Promise<number | null>;
+}): Promise<number | null> {
   const deadline = Date.now() + processingWaitMs;
   for (;;) {
-    if (!conversation.isProcessing()) {
-      conversation.setProcessing(true);
-      return true;
+    // Fenced, so a frame never writes into a turn no reader can see. A marker
+    // that refuses to persist gives the hold back and drops the frame; a
+    // conversation that belongs to someone else is waited out below.
+    let owner: number | null;
+    try {
+      owner = await conversation.acquireProcessingFenced();
+    } catch (err) {
+      log.warn(
+        { err },
+        "Standalone image gave up its hold: the processing marker would not persist",
+      );
+      return null;
+    }
+    if (owner !== null) {
+      return owner;
     }
     if (Date.now() >= deadline) {
-      return false;
+      return null;
     }
     await new Promise((resolve) => setTimeout(resolve, PROCESSING_POLL_MS));
   }
@@ -309,76 +557,260 @@ async function acquireProcessingFlag(conversation: {
  * them ever holds the flag. Never throws. An image that cannot be stored must
  * not take the call down with it, and the caller reports the failure to the
  * user instead.
+ *
+ * Every later check answers for the one incarnation the image was accepted
+ * for, which is read before anything is queued. Reading it inside the job
+ * instead would read whatever holds the id by the time the job runs: the chain
+ * can hold a frame behind another image for as long as a turn runs, and a
+ * conversation deleted and recreated in that time would be captured as the
+ * incarnation the frame was taken in, leaving every check comparing the
+ * replacement against itself.
+ *
+ * `acceptedIncarnation` is that value read by the caller, for one whose own
+ * acceptance is earlier than this call: the HTTP door answers 404 from a row
+ * it reads before resolving the request's actor, so the row it accepted is the
+ * one it read there rather than whatever survives that resolution. A caller
+ * with nothing between its acceptance and this call omits it, and the read
+ * below is that same moment.
  */
 function persistStandaloneImage(
   conversationId: string,
   attachmentId: string,
   kind: "photo" | "sight_frame",
-  persistOptions: Omit<PersistMessageOptions, "attachments" | "requestId">,
+  persistOptions: Omit<
+    PersistMessageOptions,
+    | "attachments"
+    | "requestId"
+    | "insertPrecondition"
+    | "onUndiscardedAttachments"
+  >,
+  acceptedIncarnation?: number,
 ): Promise<LiveVoicePhotoResult> {
-  return enqueueStandaloneImagePersist(conversationId, attachmentId, kind, () =>
-    writeStandaloneImage(conversationId, attachmentId, kind, persistOptions),
+  let incarnation: number | null;
+  try {
+    incarnation =
+      acceptedIncarnation ?? getConversation(conversationId)?.createdAt ?? null;
+  } catch (err) {
+    // This read is the one thing here that runs outside the job's own catch,
+    // and the contract above is that an image never takes its caller down: the
+    // socket attaches no handler for a rejection. Reported as the refusal it
+    // is, and the upload is held rather than deleted, because a store that
+    // cannot be read is not evidence the conversation is gone. Nothing was
+    // inserted, so the recheck reclaims as soon as the store answers at all.
+    log.warn(
+      { err, conversationId, attachmentId, kind },
+      "Could not read the conversation a standalone image names",
+    );
+    if (kind === "sight_frame") {
+      deferFrameReclaimDecision(
+        conversationId,
+        uuidv7(),
+        [attachmentId],
+        persistOptions.content,
+      );
+    }
+    return Promise.resolve({ ok: false });
+  }
+  if (incarnation === null) {
+    log.warn(
+      { conversationId, attachmentId, kind },
+      "Standalone image dropped: it names no conversation",
+    );
+    if (kind === "sight_frame") {
+      reclaimOrDefer(
+        conversationId,
+        [attachmentId],
+        persistOptions.content,
+        uuidv7(),
+      );
+    }
+    return Promise.resolve({ ok: false });
+  }
+  return enqueueStandaloneImagePersist(
+    conversationId,
+    attachmentId,
+    kind,
+    persistOptions.content,
+    () =>
+      writeStandaloneImage(
+        conversationId,
+        attachmentId,
+        kind,
+        incarnation,
+        persistOptions,
+      ),
   );
 }
 
+/**
+ * Report and give up on an image whose conversation is no longer the
+ * incarnation it was accepted for.
+ *
+ * Keeps only, per {@link reclaimDroppedFrame}: a photo that failed to land is
+ * the user's to retry rather than the daemon's to delete.
+ */
+function dropReplacedImage(
+  conversationId: string,
+  attachmentId: string,
+  kind: "photo" | "sight_frame",
+  content: string,
+): LiveVoicePhotoResult {
+  log.warn(
+    { conversationId, attachmentId, kind },
+    "Standalone image dropped: its conversation was replaced before the write",
+  );
+  if (kind === "sight_frame") {
+    reclaimOrDefer(conversationId, [attachmentId], content, uuidv7());
+  }
+  return { ok: false };
+}
+
 async function writeStandaloneImage(
   conversationId: string,
   attachmentId: string,
   kind: "photo" | "sight_frame",
-  persistOptions: Omit<PersistMessageOptions, "attachments" | "requestId">,
+  incarnation: number,
+  persistOptions: Omit<
+    PersistMessageOptions,
+    | "attachments"
+    | "requestId"
+    | "insertPrecondition"
+    | "onUndiscardedAttachments"
+  >,
 ): Promise<LiveVoicePhotoResult> {
   const { content } = persistOptions;
   // The id the row is inserted under, so a failure can ask whether the insert
   // landed before deciding the frame is safe to reclaim.
   const requestId = uuidv7();
+  // Ids the persist materialized for this attempt and then could not delete.
+  // A frame already linked elsewhere is cloned into this conversation under a
+  // fresh id, and nothing but the persist knows it: reclaiming under the id
+  // this module holds would leave the clone behind for good.
+  const strandedClones: string[] = [];
   try {
     const attachments = resolveAttachmentsForPersist([attachmentId]);
     if (attachments.length === 0) {
       log.warn(
         { attachmentId, kind },
-        "Live-voice image attachment did not resolve",
+        "Standalone image attachment did not resolve",
       );
       return { ok: false };
     }
 
-    const conversation = await getOrCreateConversation(conversationId);
+    // A queued job starts long after its caller checked, so the conversation
+    // can be gone by now. The acquire creates nothing, which is what keeps a
+    // delete final for everything already queued: the creating acquire would
+    // write the row back and bring the conversation home carrying nothing but
+    // camera frames. A delete that lands after the acquire is fenced by the
+    // messages foreign key instead, and the failure path below reclaims the
+    // upload once it reads that no row was inserted.
+    const conversation = await getConversationIfExists(conversationId);
+    if (!conversation) {
+      log.warn(
+        { conversationId, attachmentId, kind },
+        "Standalone image dropped: its conversation was deleted while it waited",
+      );
+      if (kind === "sight_frame") {
+        reclaimOrDefer(conversationId, [attachmentId], content, uuidv7());
+      }
+      return { ok: false };
+    }
+
+    // The acquire answers for the row it found, which for a job the chain held
+    // behind another image can be a conversation created under this id since.
+    // Asked before the idle wait so a replacement is answered now rather than
+    // after holding a stranger's lock for the length of a turn.
+    if (!isSameIncarnation(conversationId, incarnation)) {
+      return dropReplacedImage(conversationId, attachmentId, kind, content);
+    }
 
     // A turn holds the lock for its whole run. Waiting rather than queueing:
     // the conversation's queue drains into a turn, which is the one thing this
     // must not cause.
-    if (!(await acquireProcessingFlag(conversation))) {
+    const owner = await acquireProcessingFlag(conversation);
+    if (owner === null) {
       log.warn(
         { conversationId, attachmentId, kind },
-        "Live-voice image timed out waiting for the conversation to go idle",
+        "Standalone image timed out waiting for the conversation to go idle",
       );
       if (kind === "sight_frame") {
-        reclaimDroppedFrame(attachmentId);
+        reclaimOrDefer(conversationId, [attachmentId], content, uuidv7());
       }
       return { ok: false };
     }
 
     try {
+      // The wait can outlast the conversation, and this job holds an instance
+      // rather than re-reading, so a delete alone would be caught only by the
+      // messages foreign key. A delete followed by a recreate under the same
+      // id restores that foreign key's target, and the row would land in a
+      // conversation created after the deletion. Both kinds check: a photo
+      // persisted into a stranger that inherited the name is the same wrong.
+      // The same question rides the persist below as its insert precondition,
+      // which is what covers a replacement landing while the write runs.
+      if (!isSameIncarnation(conversationId, incarnation)) {
+        return dropReplacedImage(conversationId, attachmentId, kind, content);
+      }
+
       const persisted = await persistQueuedMessageBody(conversation, {
         ...persistOptions,
         attachments,
         requestId,
+        // Asked again in the insert's own tick, about both things that can
+        // stop being true across the awaits the persist takes to materialize
+        // the attachment and build its content.
+        //
+        // A delete and recreate under the same id leaves a valid foreign-key
+        // target, so without the first term the frame joins a conversation it
+        // was never taken in. A Stop on this hold force-clears the flag, since
+        // no turn owns it, and the next request acquires, so without the
+        // second the frame writes under a dead claim alongside that turn. The
+        // release afterwards is refused either way, but a refused release
+        // cannot undo a row.
+        //
+        // Refusing is also the right reading of the Stop: the user asked the
+        // conversation to stop, and this frame is the camera's, not theirs.
+        insertPrecondition: () =>
+          isSameIncarnation(conversationId, incarnation) &&
+          conversation.holdsProcessingClaim(owner),
+        onUndiscardedAttachments: (ids) => {
+          strandedClones.push(...ids);
+        },
       });
 
+      // The row just joined the resident history, and this write ran outside
+      // any turn, so nothing scoped that history for the actor it names. A
+      // frame posted by one actor into a conversation resident under another
+      // would otherwise reach the model inside a scope a reload filters it out
+      // of.
+      conversation.markHistoryStaleForForeignScope(persistOptions.trustContext);
+
       announcePersistedImage(conversationId, content, persisted.id);
 
       return { ok: true, messageId: persisted.id };
     } finally {
-      conversation.setProcessing(false);
-      // Anything queued behind the lock we just held still has to run. Without
-      // this a message queued during the image's write sits until the next
-      // turn ends.
-      void conversation.kickDrainQueue("loop_complete", `live_voice_${kind}`);
+      // Only this job's own hold is released. A turn that claimed the flag
+      // away mid-write owns it now, and clearing there would free a turn that
+      // is still running.
+      if (conversation.releaseProcessing(owner)) {
+        // Anything queued behind the lock we just held still has to run.
+        // Without this a message queued during the image's write sits until
+        // the next turn ends.
+        void conversation.kickDrainQueue("loop_complete", `standalone_${kind}`);
+      }
     }
   } catch (err) {
-    log.warn(
-      { err, conversationId, attachmentId, kind },
-      "Failed to persist a live-voice image",
-    );
+    if (err instanceof MessageInsertPreconditionError) {
+      log.warn(
+        { conversationId, attachmentId, kind },
+        "Standalone image dropped: its conversation was replaced during the write",
+      );
+    } else {
+      log.warn(
+        { err, conversationId, attachmentId, kind },
+        "Failed to persist a standalone image",
+      );
+    }
     const inserted = insertedMessageState(conversationId, requestId);
     if (inserted === "exists") {
       // The row is in the transcript, so the result has to say so whatever
@@ -397,13 +829,31 @@ async function writeStandaloneImage(
       } catch (announceErr) {
         log.warn(
           { err: announceErr, conversationId, messageId: requestId },
-          "Persisted a live-voice image but could not announce it",
+          "Persisted a standalone image but could not announce it",
         );
       }
       return { ok: true, messageId: requestId };
     }
-    if (kind === "sight_frame" && inserted === "absent") {
-      reclaimDroppedFrame(attachmentId);
+    if (kind === "sight_frame") {
+      if (inserted === "absent") {
+        reclaimOrDefer(
+          conversationId,
+          [attachmentId, ...strandedClones],
+          content,
+          requestId,
+        );
+      } else {
+        // The store would not say whether the row landed. The refusal below
+        // reports the frame as handled, so the upload cannot simply be left,
+        // and a row that turns out to have landed was never announced. Both
+        // wait on the same answer.
+        deferFrameReclaimDecision(
+          conversationId,
+          requestId,
+          [attachmentId, ...strandedClones],
+          content,
+        );
+      }
     }
     return { ok: false };
   }
@@ -461,7 +911,7 @@ function insertedMessageState(
   } catch (err) {
     log.warn(
       { err, conversationId, messageId },
-      "Could not tell whether a live-voice image persisted; keeping its attachment and reporting failure",
+      "Could not tell whether a standalone image persisted; keeping its attachment and reporting failure",
     );
     return "unknown";
   }
@@ -489,6 +939,9 @@ export async function persistLiveVoicePhoto(
   });
 }
 
+/** Which client surface the camera's gate was running on. */
+export type SightFrameSurface = "voice" | "chat";
+
 /**
  * Persist an ambient camera frame the client's gate kept.
  *
@@ -501,23 +954,53 @@ export async function persistLiveVoicePhoto(
  *
  * `scripted` because the camera's gate sent this, not the user: a keep every
  * few seconds would otherwise read downstream as that many turns the user
- * took, and activation counts turns that claim they were typed.
+ * took, and activation counts turns that claim they were typed. The pair of
+ * `scripted` and the tag is also the signature the memory-privacy guard
+ * (`messageMetadataIsAmbientSightKeep`) reads, so both surfaces stamp both.
+ *
+ * The surface decides one key and nothing else. `voiceSessionTurn` says a
+ * reply to this row is spoken back over a session that is still open, which is
+ * true of a keep taken on a call and false of one taken beside the composer,
+ * so only the voice caller stamps it.
+ *
+ * `trustContext` is the requester's own trust, for a caller that resolved one
+ * from the actor it verified. The row's provenance is stamped from it, so a
+ * conversation whose resting trust names an earlier actor cannot claim this
+ * frame. A caller that holds no per-request actor omits it and the persist
+ * attributes the row to the conversation, which is the right answer for a
+ * session that owns the conversation's trust for its whole life.
+ *
+ * `acceptedIncarnation` is the `created_at` of the conversation the caller
+ * accepted the frame for, for one that resolved that trust between reading the
+ * row and calling here: the frame belongs to the row the caller answered on,
+ * not to whatever holds the id once the resolution returns. A caller with no
+ * such gap omits it. See {@link persistStandaloneImage}.
  */
-export async function persistLiveVoiceSightFrame(
+export async function persistAmbientSightFrame(
   conversationId: string,
   attachmentId: string,
+  surface: SightFrameSurface,
+  trustContext?: TrustContext,
+  acceptedIncarnation?: number,
 ): Promise<LiveVoicePhotoResult> {
-  return persistStandaloneImage(conversationId, attachmentId, "sight_frame", {
-    content: SIGHT_FRAME_MESSAGE_CONTENT,
-    metadata: { voiceSessionTurn: true },
-    scripted: true,
-    // The camera sampled this, nobody sent it. Indexing it would feed
-    // extraction a frame every few seconds of whatever the room happens to
-    // contain, and commit those visuals to long-term memory with no consent
-    // surface: the design puts keeps in the TRANSCRIPT, which the user can see
-    // and delete, and says nothing about memory. The text half is worthless to
-    // search anyway, every row reading "(camera frame)".
-    skipIndexing: true,
-    sightFrameAttachmentIds: [attachmentId],
-  });
+  return persistStandaloneImage(
+    conversationId,
+    attachmentId,
+    "sight_frame",
+    {
+      content: SIGHT_FRAME_MESSAGE_CONTENT,
+      metadata: surface === "voice" ? { voiceSessionTurn: true } : {},
+      ...(trustContext ? { trustContext } : {}),
+      scripted: true,
+      // The camera sampled this, nobody sent it. Indexing it would feed
+      // extraction a frame every few seconds of whatever the room happens to
+      // contain, and commit those visuals to long-term memory with no consent
+      // surface: the design puts keeps in the TRANSCRIPT, which the user can
+      // see and delete, and says nothing about memory. The text half is
+      // worthless to search anyway, every row reading "(camera frame)".
+      skipIndexing: true,
+      sightFrameAttachmentIds: [attachmentId],
+    },
+    acceptedIncarnation,
+  );
 }