@vellumai/assistant 0.11.4-staging.3 → 0.11.4-staging.4

package/src/__tests__/file-ops-service.test.ts

@@ -10,10 +10,11 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, describe, expect, test } from "bun:test";
 
+import { THRESHOLD_CHARS } from "../context/post-turn-tool-result-truncation.js";
 import {
-  DEFAULT_READ_LINE_LIMIT,
   FileSystemOps,
   type PathPolicy,
+  READ_CHAR_BUDGET,
 } from "../tools/shared/filesystem/file-ops-service.js";
 import { sandboxPolicy } from "../tools/shared/filesystem/path-policy.js";
 
@@ -111,34 +112,28 @@ describe("FileSystemOps.readFileSafe", () => {
     expect(result.error.code).toBe("PATH_OUT_OF_BOUNDS");
   });
 
-  test("respects offset and limit", async () => {
+  test("respects startIndex and maxChars", async () => {
     const dir = makeTempDir();
     writeFileSync(join(dir, "lines.txt"), "a\nb\nc\nd\ne\n");
     const ops = new FileSystemOps(sandboxPolicyFor(dir));
 
     const result = await ops.readFileSafe({
       path: "lines.txt",
-      offset: 2,
-      limit: 2,
+      startIndex: 2,
+      maxChars: 3,
     });
     expect(result.ok).toBe(true);
     if (!result.ok) {
       return;
     }
-    // Assert on the numbered lines rather than bare letters: the truncation
-    // notice is prose, so a bare `toContain("d")` matches its wording.
     const [body] = result.value.content.split("\n\n[Truncated:");
-    expect(body).toContain("     2  b");
-    expect(body).toContain("     3  c");
-    expect(body).not.toContain("     1  a");
-    expect(body).not.toContain("     4  d");
+    expect(body).toBe("b\nc");
   });
 
-  test("caps an unbounded read at the default line limit and says so", async () => {
+  test("caps an unbounded read at the character budget and says so", async () => {
     const dir = makeTempDir();
-    const total = DEFAULT_READ_LINE_LIMIT + 500;
-    const lines = Array.from({ length: total }, (_, i) => `line${i + 1}`);
-    writeFileSync(join(dir, "big.txt"), lines.join("\n"));
+    const total = READ_CHAR_BUDGET + 500;
+    writeFileSync(join(dir, "big.txt"), "x".repeat(total));
     const ops = new FileSystemOps(sandboxPolicyFor(dir));
 
     const result = await ops.readFileSafe({ path: "big.txt" });
@@ -146,36 +141,74 @@ describe("FileSystemOps.readFileSafe", () => {
     if (!result.ok) {
       return;
     }
-    const content = result.value.content;
-    expect(content).toContain(`  ${DEFAULT_READ_LINE_LIMIT}  line2000`);
-    expect(content).not.toContain("line2001");
-    expect(content).toContain(
-      `[Truncated: showing through line ${DEFAULT_READ_LINE_LIMIT} of ${total}. Read on with offset=${DEFAULT_READ_LINE_LIMIT + 1}`,
+    const [body] = result.value.content.split("\n\n[Truncated:");
+    expect(body).toHaveLength(READ_CHAR_BUDGET);
+    expect(result.value.content).toContain(
+      `[Truncated: characters 0-${READ_CHAR_BUDGET} of ${total}. Read on with start_index=${READ_CHAR_BUDGET}.]`,
     );
   });
 
-  test("an explicit limit is honored rather than replaced by the default", async () => {
+  test("a maxChars above the budget is clamped to it", async () => {
     const dir = makeTempDir();
-    const lines = Array.from(
-      { length: DEFAULT_READ_LINE_LIMIT + 500 },
-      (_, i) => `line${i + 1}`,
-    );
-    writeFileSync(join(dir, "big.txt"), lines.join("\n"));
+    const total = READ_CHAR_BUDGET + 500;
+    writeFileSync(join(dir, "big.txt"), "x".repeat(total));
     const ops = new FileSystemOps(sandboxPolicyFor(dir));
 
     const result = await ops.readFileSafe({
       path: "big.txt",
-      limit: DEFAULT_READ_LINE_LIMIT + 500,
+      maxChars: total,
     });
     expect(result.ok).toBe(true);
     if (!result.ok) {
       return;
     }
-    expect(result.value.content).toContain("line2500");
-    expect(result.value.content).not.toContain("[Truncated:");
+    const [body] = result.value.content.split("\n\n[Truncated:");
+    expect(body).toHaveLength(READ_CHAR_BUDGET);
+  });
+
+  test("a maxChars below the budget is honored as given", async () => {
+    const dir = makeTempDir();
+    writeFileSync(join(dir, "big.txt"), "x".repeat(500));
+    const ops = new FileSystemOps(sandboxPolicyFor(dir));
+
+    const result = await ops.readFileSafe({ path: "big.txt", maxChars: 10 });
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    const [body] = result.value.content.split("\n\n[Truncated:");
+    expect(body).toHaveLength(10);
+    expect(result.value.content).toContain(
+      "[Truncated: characters 0-10 of 500. Read on with start_index=10.]",
+    );
+  });
+
+  test("paging with the offset from a notice returns the next window", async () => {
+    const dir = makeTempDir();
+    writeFileSync(join(dir, "big.txt"), "abcdefghij");
+    const ops = new FileSystemOps(sandboxPolicyFor(dir));
+
+    const first = await ops.readFileSafe({ path: "big.txt", maxChars: 4 });
+    expect(first.ok).toBe(true);
+    if (!first.ok) {
+      return;
+    }
+    expect(first.value.content).toContain("start_index=4");
+
+    const second = await ops.readFileSafe({
+      path: "big.txt",
+      startIndex: 4,
+      maxChars: 4,
+    });
+    expect(second.ok).toBe(true);
+    if (!second.ok) {
+      return;
+    }
+    const [body] = second.value.content.split("\n\n[Truncated:");
+    expect(body).toBe("efgh");
   });
 
-  test("a read that reaches the last line carries no truncation notice", async () => {
+  test("a read that reaches the end carries no truncation notice", async () => {
     const dir = makeTempDir();
     writeFileSync(join(dir, "small.txt"), "a\nb\nc");
     const ops = new FileSystemOps(sandboxPolicyFor(dir));
@@ -193,13 +226,113 @@ describe("FileSystemOps.readFileSafe", () => {
     writeFileSync(join(dir, "small.txt"), "a\nb\nc");
     const ops = new FileSystemOps(sandboxPolicyFor(dir));
 
-    const result = await ops.readFileSafe({ path: "small.txt", offset: 100 });
+    const result = await ops.readFileSafe({
+      path: "small.txt",
+      startIndex: 100,
+    });
     expect(result.ok).toBe(true);
     if (!result.ok) {
       return;
     }
     expect(result.value.content).not.toContain("[Truncated:");
   });
+
+  test("a window boundary inside a surrogate pair does not corrupt it", async () => {
+    const dir = makeTempDir();
+    // "ab" + a 2-unit emoji + "cd": a maxChars of 3 would split the pair.
+    writeFileSync(join(dir, "emoji.txt"), `ab\u{1F600}cd`);
+    const ops = new FileSystemOps(sandboxPolicyFor(dir));
+
+    const result = await ops.readFileSafe({ path: "emoji.txt", maxChars: 3 });
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    const [body] = result.value.content.split("\n\n[Truncated:");
+    expect(body).toBe("ab");
+    expect(body).not.toContain("\uFFFD");
+  });
+
+  test("paging across a surrogate pair reassembles the whole file", async () => {
+    const dir = makeTempDir();
+    const original = `ab\u{1F600}cd`;
+    writeFileSync(join(dir, "emoji.txt"), original);
+    const ops = new FileSystemOps(sandboxPolicyFor(dir));
+
+    let assembled = "";
+    let startIndex = 0;
+    for (let i = 0; i < 10; i++) {
+      const result = await ops.readFileSafe({
+        path: "emoji.txt",
+        startIndex,
+        maxChars: 3,
+      });
+      expect(result.ok).toBe(true);
+      if (!result.ok) {
+        return;
+      }
+      const [body] = result.value.content.split("\n\n[Truncated:");
+      assembled += body;
+      const match = /start_index=(\d+)/.exec(result.value.content);
+      if (match?.[1] === undefined) {
+        break;
+      }
+      startIndex = Number(match[1]);
+    }
+    expect(assembled).toBe(original);
+  });
+
+  test("a lone-low-surrogate startIndex backs up onto the whole pair", async () => {
+    const dir = makeTempDir();
+    writeFileSync(join(dir, "emoji.txt"), `ab\u{1F600}cd`);
+    const ops = new FileSystemOps(sandboxPolicyFor(dir));
+
+    // Index 3 (0-indexed) is the low half of the emoji.
+    const result = await ops.readFileSafe({
+      path: "emoji.txt",
+      startIndex: 3,
+      maxChars: 2,
+    });
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    const [body] = result.value.content.split("\n\n[Truncated:");
+    expect(body).toBe(`\u{1F600}`);
+    expect(body).not.toContain("\uFFFD");
+  });
+
+  test("legacy offset/limit are rejected rather than silently ignored", async () => {
+    const { fileReadTool } = await import("../tools/filesystem/read.js");
+    const dir = makeTempDir();
+    writeFileSync(join(dir, "big.txt"), "x".repeat(500));
+
+    const result = await fileReadTool.execute(
+      { path: join(dir, "big.txt"), offset: 2001, limit: 2000 },
+      { workingDir: dir } as never,
+    );
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain("no longer takes");
+    expect(result.content).toContain("start_index");
+  });
+
+  test("legacy fields alongside current ones do not trigger the guard", async () => {
+    const { fileReadTool } = await import("../tools/filesystem/read.js");
+    const dir = makeTempDir();
+    writeFileSync(join(dir, "big.txt"), "abcdefghij");
+
+    const result = await fileReadTool.execute(
+      { path: join(dir, "big.txt"), offset: 1, max_chars: 4 },
+      { workingDir: dir } as never,
+    );
+    expect(result.isError).toBe(false);
+    const [body] = result.content.split("\n\n[Truncated:");
+    expect(body).toBe("abcd");
+  });
+
+  test("the read budget stays under the tool-result spool threshold", () => {
+    expect(READ_CHAR_BUDGET).toBeLessThan(THRESHOLD_CHARS);
+  });
 });
 
 // ---------------------------------------------------------------------------

package/src/__tests__/filesystem-tools.test.ts

@@ -125,16 +125,19 @@ describe("FileSystemOps symlink handling", () => {
 });
 
 // ===========================================================================
-// FileSystemOps: read offset/limit edge cases
+// FileSystemOps: read character-window edge cases
 // ===========================================================================
 
-describe("FileSystemOps read offset/limit edge cases", () => {
-  test("offset beyond file length returns empty content", async () => {
+describe("FileSystemOps read character-window edge cases", () => {
+  test("startIndex beyond file length returns empty content", async () => {
     const dir = makeTempDir();
     writeFileSync(join(dir, "short.txt"), "a\nb\nc");
     const ops = new FileSystemOps(sandboxPolicyFor(dir));
 
-    const result = await ops.readFileSafe({ path: "short.txt", offset: 100 });
+    const result = await ops.readFileSafe({
+      path: "short.txt",
+      startIndex: 100,
+    });
     expect(result.ok).toBe(true);
     if (!result.ok) {
       return;
@@ -142,12 +145,12 @@ describe("FileSystemOps read offset/limit edge cases", () => {
     expect(result.value.content).toBe("");
   });
 
-  test("limit of zero returns empty content", async () => {
+  test("maxChars of zero returns empty content", async () => {
     const dir = makeTempDir();
     writeFileSync(join(dir, "file.txt"), "a\nb\nc");
     const ops = new FileSystemOps(sandboxPolicyFor(dir));
 
-    const result = await ops.readFileSafe({ path: "file.txt", limit: 0 });
+    const result = await ops.readFileSafe({ path: "file.txt", maxChars: 0 });
     expect(result.ok).toBe(true);
     if (!result.ok) {
       return;
@@ -155,61 +158,57 @@ describe("FileSystemOps read offset/limit edge cases", () => {
     expect(result.value.content).toBe("");
   });
 
-  test("offset=1 reads from first line (1-indexed)", async () => {
+  test("startIndex=0 reads from the first character (0-indexed)", async () => {
     const dir = makeTempDir();
     writeFileSync(join(dir, "file.txt"), "first\nsecond\nthird");
     const ops = new FileSystemOps(sandboxPolicyFor(dir));
 
     const result = await ops.readFileSafe({
       path: "file.txt",
-      offset: 1,
-      limit: 1,
+      startIndex: 0,
+      maxChars: 5,
     });
     expect(result.ok).toBe(true);
     if (!result.ok) {
       return;
     }
-    expect(result.value.content).toContain("first");
-    expect(result.value.content).not.toContain("second");
+    const [body] = result.value.content.split("\n\n[Truncated:");
+    expect(body).toBe("first");
   });
 
-  test("limit exceeding file length returns all remaining lines", async () => {
+  test("maxChars exceeding file length returns the rest of the file", async () => {
     const dir = makeTempDir();
     writeFileSync(join(dir, "file.txt"), "a\nb");
     const ops = new FileSystemOps(sandboxPolicyFor(dir));
 
     const result = await ops.readFileSafe({
       path: "file.txt",
-      offset: 1,
-      limit: 1000,
+      startIndex: 0,
+      maxChars: 1000,
     });
     expect(result.ok).toBe(true);
     if (!result.ok) {
       return;
     }
-    expect(result.value.content).toContain("a");
-    expect(result.value.content).toContain("b");
+    expect(result.value.content).toBe("a\nb");
   });
 
-  test("read adds line numbers starting from offset", async () => {
+  test("the window starts at startIndex and carries no line numbers", async () => {
     const dir = makeTempDir();
     writeFileSync(join(dir, "file.txt"), "a\nb\nc\nd\ne");
     const ops = new FileSystemOps(sandboxPolicyFor(dir));
 
     const result = await ops.readFileSafe({
       path: "file.txt",
-      offset: 3,
-      limit: 2,
+      startIndex: 4,
+      maxChars: 3,
     });
     expect(result.ok).toBe(true);
     if (!result.ok) {
       return;
     }
-    // Lines should be numbered 3 and 4
-    expect(result.value.content).toContain("3");
-    expect(result.value.content).toContain("4");
-    expect(result.value.content).toContain("c");
-    expect(result.value.content).toContain("d");
+    const [body] = result.value.content.split("\n\n[Truncated:");
+    expect(body).toBe("c\nd");
   });
 });
 

package/src/__tests__/host-file-read-tool.test.ts

@@ -27,7 +27,7 @@ mock.module("../daemon/host-file-proxy.js", () => ({
 }));
 
 import { hostFileReadTool } from "../tools/host-filesystem/read.js";
-import { DEFAULT_READ_LINE_LIMIT } from "../tools/shared/filesystem/file-ops-service.js";
+import { READ_CHAR_BUDGET } from "../tools/shared/filesystem/file-ops-service.js";
 import type { ToolContext } from "../tools/types.js";
 
 const testDirs: string[] = [];
@@ -77,19 +77,19 @@ describe("host_file_read tool", () => {
     expect(result.content).toContain("must be absolute");
   });
 
-  test("reads file with line numbers", async () => {
+  test("reads a character window", async () => {
     const dir = mkdtempSync(join(tmpdir(), "host-file-read-test-"));
     testDirs.push(dir);
     const filePath = join(dir, "sample.txt");
     writeFileSync(filePath, "first\nsecond\nthird\n");
 
     const result = await hostFileReadTool.execute(
-      { path: filePath, offset: 2, limit: 2 },
+      { path: filePath, start_index: 6, max_chars: 6 },
       makeContext(),
     );
     expect(result.isError).toBe(false);
-    expect(result.content).toContain("2  second");
-    expect(result.content).toContain("3  third");
+    expect(result.content).toContain("second");
+    expect(result.content).not.toContain("first");
   });
 
   test("returns error when file does not exist", async () => {
@@ -128,7 +128,7 @@ describe("host_file_read tool", () => {
     expect(result.content).toContain('Invalid input for tool "host_file_read"');
   });
 
-  test("reads entire file when no offset or limit specified", async () => {
+  test("reads the whole file when no window is specified", async () => {
     const dir = mkdtempSync(join(tmpdir(), "host-file-read-test-"));
     testDirs.push(dir);
     const filePath = join(dir, "full.txt");
@@ -139,9 +139,7 @@ describe("host_file_read tool", () => {
       makeContext(),
     );
     expect(result.isError).toBe(false);
-    expect(result.content).toContain("1  line1");
-    expect(result.content).toContain("2  line2");
-    expect(result.content).toContain("3  line3");
+    expect(result.content).toBe("line1\nline2\nline3\n");
   });
 
   test("handles empty file", async () => {
@@ -157,20 +155,19 @@ describe("host_file_read tool", () => {
     expect(result.isError).toBe(false);
   });
 
-  test("offset starts from the correct line (1-indexed)", async () => {
+  test("start_index is 0-indexed", async () => {
     const dir = mkdtempSync(join(tmpdir(), "host-file-read-test-"));
     testDirs.push(dir);
     const filePath = join(dir, "lines.txt");
     writeFileSync(filePath, "a\nb\nc\nd\ne\n");
 
     const result = await hostFileReadTool.execute(
-      { path: filePath, offset: 3, limit: 1 },
+      { path: filePath, start_index: 4, max_chars: 1 },
       makeContext(),
     );
     expect(result.isError).toBe(false);
-    expect(result.content).toContain("3  c");
-    expect(result.content).not.toContain("2  b");
-    expect(result.content).not.toContain("4  d");
+    const [body] = result.content.split("\n\n[Truncated:");
+    expect(body).toBe("c");
   });
 
   test("reads a file with symlinks resolved", async () => {
@@ -228,15 +225,15 @@ describe("host_file_read image support", () => {
     expect(result.isError).toBe(false);
     expect(result.contentBlocks).toHaveLength(1);
     // The proxied request carries the resolved default window, so a host read
-    // is bounded by the same limit as a local one rather than streaming a
+    // is bounded by the same budget as a local one rather than streaming a
     // whole file across the bridge.
     expect(requests).toEqual([
       {
         input: {
           operation: "read",
           path: "/host/screenshot.png",
-          offset: undefined,
-          limit: DEFAULT_READ_LINE_LIMIT,
+          startIndex: undefined,
+          maxChars: READ_CHAR_BUDGET,
         },
         conversationId: "test-conversation",
         signal: undefined,
@@ -306,8 +303,8 @@ describe("host_file_read image support", () => {
     );
 
     expect(result.isError).toBe(false);
-    expect(result.content).toContain("1  hello world");
-    expect(result.content).toContain("2  second line");
+    expect(result.content).toContain("hello world");
+    expect(result.content).toContain("second line");
     expect((result as any).contentBlocks).toBeUndefined();
   });
 

package/src/__tests__/tool-executor.test.ts

@@ -1457,7 +1457,11 @@ describe("ToolExecutor input-schema validation gate", () => {
     const executor = new ToolExecutor(makePrompter());
     const result = await executor.execute(
       "file_read",
-      { path: "a.txt", offset: "not-a-number", activity: "Reading a file" },
+      {
+        path: "a.txt",
+        start_index: "not-a-number",
+        activity: "Reading a file",
+      },
       makeContext(),
     );
 

package/src/api/events/host-file.ts

@@ -21,8 +21,8 @@ const HostFileReadRequestSchema = z.object({
   targetClientId: z.string().optional(),
   operation: z.literal("read"),
   path: z.string(),
-  offset: z.number().optional(),
-  limit: z.number().optional(),
+  startIndex: z.number().optional(),
+  maxChars: z.number().optional(),
 });
 
 const HostFileWriteRequestSchema = z.object({

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

@@ -44,6 +44,7 @@ import {
   type RenderedSlackTranscriptMessage,
   renderSlackTranscriptWithProvenance,
 } from "../messaging/providers/slack/render-transcript.js";
+import { isGuardianCardRow } from "../notifications/approval-card-data.js";
 import {
   getMessages as defaultGetMessages,
   type MessageRow,
@@ -520,7 +521,7 @@ function injectActiveSurfaceContext(
       "RULES FOR WORKSPACE MODIFICATION:",
       `1. Use \`file_edit\` to make surgical changes to app files. The file path is \`${getAppDirPath(ctx.appId)}/<path>\`.`,
       "2. Use `file_write` to create new files or rewrite files.",
-      "3. Use `file_read` to read any file with line numbers before editing.",
+      "3. Use `file_read` to read any file before editing, and `code_search` when you need a line reference.",
       "4. Use `bash ls` to see all files in the app directory.",
       `5. Call \`app_refresh\` with app_id "${ctx.appId}" ONCE after all changes are complete.`,
       "6. NEVER respond with only text — the user expects a visual update.",
@@ -1513,10 +1514,16 @@ export function loadSlackChronologicalContext(
     allRows,
     options.trustClass,
   );
+  // Applied after the compaction boundary, never before it: that filter
+  // indexes into the row list when no watermark is set, so dropping rows
+  // earlier would shift what it cuts. Same rule and same ordering constraint
+  // as `Conversation.loadFromDb` -- Slack builds the provider history from
+  // rows rather than `this.messages`, so a rule applied only there would
+  // exempt this channel entirely.
   const rows = filterRowsAfterSlackCompactionBoundary(
     messageRowsToSlackTranscriptRows(scopedRows),
     options,
-  );
+  ).filter((row) => !isGuardianCardRow(row.content));
   return assembleSlackChronologicalContext(rows, capabilities, {
     contextSummary: resolveCapabilities(options.trustClass).canAccessMemory
       ? options.contextSummary

package/src/daemon/conversation.ts

@@ -41,6 +41,7 @@ import {
   derefToolResultReReads,
   postTurnTruncateToolResults,
 } from "../context/post-turn-tool-result-truncation.js";
+import { isGuardianCardRow } from "../notifications/approval-card-data.js";
 import { PermissionPrompter } from "../permissions/prompter.js";
 import { SecretPrompter } from "../permissions/secret-prompter.js";
 import type { UserDecision } from "../permissions/types.js";
@@ -1341,6 +1342,16 @@ export class Conversation {
       parsedMessages.length,
     );
     for (const [index, message] of parsedMessages.entries()) {
+      // Applied after the compaction slice, never before it: the slice and
+      // `rowToHistoryIndex` are both computed against the full row list, so
+      // dropping earlier would shift them. A dropped row maps to a null
+      // history index exactly like a fully-injected user row that strips to
+      // nothing. `index` is shared with `slicedDbMessages`, which
+      // `parsedMessages` maps 1:1.
+      if (isGuardianCardRow(slicedDbMessages[index]?.content)) {
+        preRepairIndexBySlicedRow[index] = null;
+        continue;
+      }
       const stripped =
         index < preStrippedCount
           ? stripInjectionsForCompaction([message])
@@ -1443,7 +1454,7 @@ export class Conversation {
       messageCount: this.messages.length,
     });
 
-    this.restoreSurfaceStateFromHistory();
+    this.restoreSurfaceStateFromHistory(parsedMessages);
     this.graphMemory.restoreState();
 
     // Row→history correspondence for this load: slice offset, then the
@@ -1475,14 +1486,19 @@ export class Conversation {
    * populate surfaceState so that findConversationBySurfaceId works for
    * surfaces restored from history (e.g. after daemon restart).
    *
-   * Only scans live (non-compacted) messages in this.messages — not all DB
-   * rows — because surface IDs are not globally unique and restoring stale
-   * compacted surfaces would let findConversationBySurfaceId route actions
-   * to the wrong conversation.
+   * Scans the live (non-compacted) window only, never all DB rows, because
+   * surface IDs are not globally unique and restoring stale compacted
+   * surfaces would let findConversationBySurfaceId route actions to the wrong
+   * conversation.
+   *
+   * Takes that window as rows rather than reading `this.messages`, because a
+   * surface's lifecycle and the model's context are different questions. A
+   * guardian card is absent from `this.messages`, but it is exactly the card
+   * whose Approve/Reject buttons must still route after a restart.
    */
-  private restoreSurfaceStateFromHistory(): void {
+  private restoreSurfaceStateFromHistory(liveWindow: Message[]): void {
     this.surfaceState.clear();
-    for (const msg of this.messages) {
+    for (const msg of liveWindow) {
       if (!Array.isArray(msg.content)) {
         continue;
       }

package/src/notifications/AGENTS.md

@@ -9,3 +9,5 @@ When a notification flow creates a server-side conversation (e.g. guardian quest
 Guardian-request producers (access requests, tool approvals, tool-grant escalations, voice questions, trusted-contact confirmations) **MUST** record approval-card deliveries through `recordApprovalCardDelivery` / `recordGuardianRequestDeliveries` in `guardian-delivery-recorder.ts` -- never by calling the gateway client's `createGuardianRequestDelivery` directly. That sink is the single place the card-to-request addressing convention lives (conversation id for the in-app card; chat + channel-native `ts` for channel cards), so the path that writes a delivery row cannot drift from the paths that read it back to withdraw a card or resolve an emoji reaction -- the drift that previously fanned this logic into four divergent copies. (Tests may seed delivery rows directly for fixtures.)
 
 Approval-card **source references** (the link back to the channel message that triggered a request) resolve only through `resolveApprovalSourceReference()` in `runtime/approval-source-link.ts` -- producers spread the result into the `guardian.question` context payload and never hand-build links. Channel-format knowledge (id shapes, permalinks, mrkdwn) lives only in `messaging/providers/<channel>/` and `notifications/adapters/<channel>`; the four-layer ownership map is documented at the top of `approval-source-link.ts`. Exception: access-request cards predate the registry and still derive their Slack permalink from payload `messageTs` in `access-request-copy.ts` -- converge them onto the registry rather than adding a third resolution path.
+
+Guardian-request card rows are **not conversation history**. `pairDeliveryWithConversation` persists a message row per delivery, and for a guardian card that row is addressed to a conversation the request is _about_ (the vellum card is pinned to the originating conversation; a channel card lands in whatever conversation the guardian's chat binds to). `isGuardianCardRow` in `approval-card-data.ts` is the single definition of which rows those are, derived from the card's own `ui_surface` id rather than a stored marker so old rows need no backfill. **Both** history assemblers must consult it -- `Conversation.loadFromDb` and `loadSlackChronologicalContext`, which re-reads rows rather than using `this.messages` -- or the unfiltered one replays the card between a parked turn's `tool_use` and its `tool_result` and history repair destroys the real result. Surface state is exempt on purpose: the card's buttons must still route after a restart. Full rationale in [docs/guardian-request-flow.md](../../docs/guardian-request-flow.md).

package/src/notifications/approval-card-data.ts

@@ -75,6 +75,39 @@ export function approvalCardSurfaceId(
   }
 }
 
+/**
+ * Whether a persisted message row is a guardian card rather than the
+ * conversation's own speech.
+ *
+ * Read off the card's own `ui_surface` id, using the prefixes above. The card
+ * builder writes that block on every path (`ensureSeedContentBlocks`), and the
+ * withdrawal path already recomputes the same id from the same constants, so
+ * the identity is structural rather than sniffed. Deriving it means rows
+ * written before this rule existed are recognized on the same terms as new
+ * ones, with no marker to backfill.
+ *
+ * Only a row that LEADS with an approval-card surface counts. A real assistant
+ * turn can carry a `ui_surface` block too (a wake card is unshifted onto the
+ * turn's own content), and those surfaces do not use these prefixes; requiring
+ * the lead position keeps the rule from ever swallowing a turn that has speech
+ * in it.
+ */
+export function isGuardianCardRow(
+  content: readonly unknown[] | string | null | undefined,
+): boolean {
+  if (!Array.isArray(content) || content.length === 0) {
+    return false;
+  }
+  const lead = content[0] as { type?: unknown; surfaceId?: unknown };
+  if (lead?.type !== "ui_surface" || typeof lead.surfaceId !== "string") {
+    return false;
+  }
+  return (
+    lead.surfaceId.startsWith(`${ACCESS_REQUEST_SURFACE_PREFIX}-`) ||
+    lead.surfaceId.startsWith(`${TOOL_APPROVAL_SURFACE_PREFIX}-`)
+  );
+}
+
 // ── Typed card data ─────────────────────────────────────────────────────────
 
 /** Resolved card data for an access-request notification. */