@vellumai/assistant 0.10.8 → 0.10.9-dev.202607152225.ec6fdbf

package/src/monitoring/recovery/__tests__/inflight-content.test.ts

@@ -0,0 +1,166 @@
+/**
+ * Tests for the monitor-process in-flight content recovery step: folding
+ * `finalized = 0` rows a crashed daemon left behind, skipping rows a live turn
+ * still owns (conversation mid-turn / fresh delta file), and GC of orphan
+ * delta files.
+ */
+import { existsSync, utimesSync } from "node:fs";
+import { describe, expect, mock, test } from "bun:test";
+
+import pino from "pino";
+
+mock.module("../../../util/logger.js", () => ({
+  getLogger: () =>
+    new Proxy({} as Record<string, unknown>, {
+      get: () => () => {},
+    }),
+}));
+
+import {
+  appendInflightSnapshot,
+  createInflightContentWriter,
+  type InflightContentWriter,
+} from "../../../daemon/inflight-message-content.js";
+import {
+  createConversation,
+  finalizeMessageContent,
+  getMessageById,
+  reserveMessage,
+} from "../../../persistence/conversation-crud.js";
+import { getDb, getSqliteFrom } from "../../../persistence/db-connection.js";
+import { initializeDb } from "../../../persistence/db-init.js";
+import type { ContentBlock } from "../../../providers/types.js";
+import { recoverInflightContent } from "../inflight-content.js";
+
+await initializeDb();
+
+const rlog = pino({ level: "silent" });
+
+function db() {
+  return getSqliteFrom(getDb());
+}
+
+function textBlock(text: string): ContentBlock {
+  return { type: "text", text };
+}
+
+/**
+ * Push a delta file's mtime firmly into the past so an age-floored fold/GC
+ * treats it as unambiguously old. The recovery age guard is `now - mtime <
+ * minAgeMs`; with `minAgeMs: 0` a file whose recorded mtime lands even a hair
+ * ahead of the captured `now` (filesystem-clock vs `Date.now()` skew on CI)
+ * yields a negative age and is wrongly preserved. Backdating removes that
+ * boundary race without weakening what the test asserts.
+ */
+function backdateDeltaFile(absPath: string): void {
+  const past = new Date(Date.now() - 60_000);
+  utimesSync(absPath, past, past);
+}
+
+function rawRow(messageId: string): { content: string; finalized: number } {
+  return db()
+    .query("SELECT content, finalized FROM messages WHERE id = ?")
+    .get(messageId) as { content: string; finalized: number };
+}
+
+function setProcessing(conversationId: string): void {
+  db()
+    .query("UPDATE conversations SET processing_started_at = ? WHERE id = ?")
+    .run(Date.now(), conversationId);
+}
+
+/** Mirror the reserve seam: writer first, row born with its ref. */
+async function reserveInflight(): Promise<{
+  conversationId: string;
+  messageId: string;
+  writer: InflightContentWriter;
+}> {
+  const conv = createConversation("recovery test");
+  const writer = createInflightContentWriter(conv.id);
+  if (!writer) {
+    throw new Error("writer creation failed");
+  }
+  const reserved = await reserveMessage(
+    conv.id,
+    "assistant",
+    undefined,
+    writer.ref,
+  );
+  writer.messageId = reserved.id;
+  return { conversationId: conv.id, messageId: reserved.id, writer };
+}
+
+describe("recoverInflightContent — folding stranded rows", () => {
+  test("folds a stranded row inline, sets finalized = 1, deletes its file", async () => {
+    const { conversationId, messageId, writer } = await reserveInflight();
+    appendInflightSnapshot(writer, [textBlock("streamed")], 1, rlog);
+    expect(existsSync(writer.absPath)).toBe(true);
+    backdateDeltaFile(writer.absPath);
+
+    const result = recoverInflightContent({ minAgeMs: 0 });
+
+    expect(result.finalized).toBeGreaterThanOrEqual(1);
+    const row = rawRow(messageId);
+    expect(row.finalized).toBe(1);
+    expect(JSON.parse(row.content)).toEqual([textBlock("streamed")]);
+    expect(existsSync(writer.absPath)).toBe(false);
+    expect(getMessageById(messageId, conversationId)?.content).toEqual([
+      textBlock("streamed"),
+    ]);
+  });
+
+  test("folds a never-flushed in-flight row to empty content", async () => {
+    const { conversationId, messageId, writer } = await reserveInflight();
+    expect(existsSync(writer.absPath)).toBe(false);
+
+    recoverInflightContent({ minAgeMs: 0 });
+
+    expect(rawRow(messageId).finalized).toBe(1);
+    expect(getMessageById(messageId, conversationId)?.content).toEqual([]);
+  });
+});
+
+describe("recoverInflightContent — ownership guards", () => {
+  test("skips a row whose conversation is mid-turn, preserving its file", async () => {
+    const { conversationId, messageId, writer } = await reserveInflight();
+    appendInflightSnapshot(writer, [textBlock("live")], 1, rlog);
+    setProcessing(conversationId);
+
+    const result = recoverInflightContent({ minAgeMs: 0 });
+
+    expect(result.skippedProcessing).toBeGreaterThanOrEqual(1);
+    expect(rawRow(messageId).finalized).toBe(0);
+    expect(existsSync(writer.absPath)).toBe(true);
+  });
+
+  test("the age floor preserves a freshly written delta file", async () => {
+    const { messageId, writer } = await reserveInflight();
+    appendInflightSnapshot(writer, [textBlock("fresh")], 1, rlog);
+    // Row already finalized, but its file lingers (interrupted unlink).
+    finalizeMessageContent(messageId, JSON.stringify([textBlock("fresh")]));
+    expect(existsSync(writer.absPath)).toBe(true);
+
+    // Default age floor treats the just-written file as possibly live.
+    const result = recoverInflightContent();
+
+    expect(result.filesDeleted).toBe(0);
+    expect(existsSync(writer.absPath)).toBe(true);
+  });
+});
+
+describe("recoverInflightContent — orphan file GC", () => {
+  test("deletes a delta file whose row is already finalized", async () => {
+    const { messageId, writer } = await reserveInflight();
+    appendInflightSnapshot(writer, [textBlock("orphaned")], 1, rlog);
+    // finalize the row without deleting its file (interrupted unlink).
+    finalizeMessageContent(messageId, JSON.stringify([textBlock("orphaned")]));
+    expect(rawRow(messageId).finalized).toBe(1);
+    expect(existsSync(writer.absPath)).toBe(true);
+    backdateDeltaFile(writer.absPath);
+
+    const result = recoverInflightContent({ minAgeMs: 0 });
+
+    expect(result.filesDeleted).toBeGreaterThanOrEqual(1);
+    expect(existsSync(writer.absPath)).toBe(false);
+  });
+});

package/src/monitoring/recovery/inflight-content.ts

@@ -0,0 +1,260 @@
+/**
+ * Recovery step: fold in-flight message content a crashed daemon left behind.
+ *
+ * A message row born in-flight carries `finalized = 0` and a `{ ref }` pointer
+ * to an append-only JSONL delta file until its turn reaches the finalize seam
+ * (see `daemon/inflight-message-content.ts`). A daemon that dies mid-turn
+ * leaves the row `finalized = 0` with its delta file on disk. The live daemon
+ * folds stranded writers from its in-memory map at the turn tail, but a crash
+ * loses that map — so this step, run once from the monitor process at startup,
+ * reconciles the residue.
+ *
+ * It runs OUT OF PROCESS from the daemon, so it cannot see live in-memory
+ * writers. Two DB-observable signals stand in for that ownership knowledge:
+ *
+ *   - `conversations.processing_started_at` — the daemon persists this at every
+ *     turn boundary precisely so out-of-process callers can detect a live turn
+ *     (the same signal the resource sampler reads). A `finalized = 0` row whose
+ *     conversation is mid-turn is a LIVE stream, not crash residue: skip it.
+ *   - delta-file mtime — a file touched within the age floor may belong to a
+ *     writer whose conversation flag we observed a beat after it cleared.
+ *
+ * With both guards the fold only ever touches rows no live turn owns. Genuine
+ * crash residue is folded on this one pass (the daemon's startup reconciler
+ * clears stale `processing_started_at` before this runs). The rare row a
+ * reconnecting client re-activated within the startup window is left as-is and
+ * reconciled by the next daemon restart's run.
+ *
+ * Two phases:
+ *   1. Fold each eligible `finalized = 0` row's resolved content inline and set
+ *      `finalized = 1`, deleting its delta file.
+ *   2. GC orphan delta files no `finalized = 0` row references — e.g. a file
+ *      whose finalize landed but whose unlink was interrupted, which phase 1
+ *      never revisits and which would otherwise leak on disk.
+ */
+
+import { existsSync, readdirSync, rmSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { Database } from "bun:sqlite";
+
+import {
+  parseContentRef,
+  resolveContentRefPath,
+  resolveMessageContentBlocks,
+} from "../../persistence/message-content-file.js";
+import { getLogger } from "../../util/logger.js";
+import { getConversationsDir, getDbPath } from "../../util/platform.js";
+
+const log = getLogger("recovery-inflight-content");
+
+/** Max time a recovery write waits on the daemon's writer lock before erroring. */
+const BUSY_TIMEOUT_MS = 5_000;
+
+/**
+ * Delta files touched within this window may belong to a live writer, so the
+ * fold and the orphan GC both leave them alone. Startup residue from a crashed
+ * process is always older than this, so recovery is not delayed in practice.
+ */
+export const DEFAULT_INFLIGHT_MIN_AGE_MS = 60_000;
+
+export interface InflightRecoveryResult {
+  /** `finalized = 0` rows folded inline and flipped to `finalized = 1`. */
+  finalized: number;
+  /** Orphan delta files unlinked from disk. */
+  filesDeleted: number;
+  /** Rows left for a later run because their conversation is mid-turn. */
+  skippedProcessing: number;
+}
+
+interface UnfinalizedRow {
+  id: string;
+  conversationId: string;
+  content: string;
+  processingStartedAt: number | null;
+}
+
+/**
+ * Open a read/write handle on the daemon's SQLite database. Returns null when
+ * the database file does not exist yet (the daemon has not booted) — never
+ * creating it. Recovery owns this handle for the lifetime of one run and
+ * closes it before returning.
+ */
+function openDaemonDb(): Database | null {
+  if (!existsSync(getDbPath())) {
+    return null; // daemon has not created the database yet
+  }
+  try {
+    const db = new Database(getDbPath(), { readwrite: true, create: false });
+    db.exec(`PRAGMA busy_timeout=${BUSY_TIMEOUT_MS}`);
+    return db;
+  } catch (err) {
+    log.debug({ err }, "recovery: could not open database");
+    return null;
+  }
+}
+
+/** Delta-file absolute path a row's `{ ref }` content points at, or null. */
+function refAbsPath(content: string): string | null {
+  const ref = parseContentRef(content);
+  return ref ? resolveContentRefPath(ref.ref) : null;
+}
+
+function fileMtimeMs(absPath: string): number | null {
+  try {
+    return statSync(absPath).mtimeMs;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Fold `finalized = 0` rows a crashed daemon left behind and GC orphan delta
+ * files. Opens (and closes) its own handle on the daemon database — different
+ * recovery steps may target different databases — and logs its own result.
+ * Throws only if the schema is not yet migrated; the orchestrator treats that
+ * as a failed step and retries on the next monitor start.
+ */
+export function recoverInflightContent(
+  options: {
+    minAgeMs?: number;
+  } = {},
+): InflightRecoveryResult {
+  const db = openDaemonDb();
+  if (db == null) {
+    return { finalized: 0, filesDeleted: 0, skippedProcessing: 0 };
+  }
+  try {
+    const minAgeMs = options.minAgeMs ?? DEFAULT_INFLIGHT_MIN_AGE_MS;
+    const now = Date.now();
+
+    // Throws here (missing `finalized`/`processing_started_at` column) propagate
+    // to the caller as "schema not ready yet".
+    const rows = db
+      .query(
+        `SELECT m.id AS id,
+                m.conversation_id AS conversationId,
+                m.content AS content,
+                c.processing_started_at AS processingStartedAt
+           FROM messages m
+           LEFT JOIN conversations c ON c.id = m.conversation_id
+          WHERE m.finalized = 0`,
+      )
+      .all() as UnfinalizedRow[];
+
+    // `AND finalized = 0` makes the write a no-op if the daemon finalized the
+    // row between our read and this write; `changes` then reports 0 and we
+    // leave its file to the daemon.
+    const finalizeStmt = db.query(
+      `UPDATE messages SET content = ?, finalized = 1
+        WHERE id = ? AND finalized = 0`,
+    );
+
+    let finalized = 0;
+    let skippedProcessing = 0;
+    for (const row of rows) {
+      // Ownership guard: a live turn on this conversation still owns the row.
+      if (row.processingStartedAt != null) {
+        skippedProcessing++;
+        continue;
+      }
+      const absPath = refAbsPath(row.content);
+      // Age guard: a freshly-written file may be a live writer whose
+      // conversation flag we observed just after it cleared.
+      if (absPath != null) {
+        const mtime = fileMtimeMs(absPath);
+        if (mtime != null && now - mtime < minAgeMs) {
+          continue;
+        }
+      }
+      try {
+        const blocks = resolveMessageContentBlocks(row.content);
+        const info = finalizeStmt.run(JSON.stringify(blocks), row.id);
+        if (info.changes > 0) {
+          finalized++;
+          if (absPath != null) {
+            rmSync(absPath, { force: true });
+          }
+        }
+      } catch (err) {
+        log.warn(
+          { err, messageId: row.id },
+          "in-flight recovery: failed to fold a row — continuing",
+        );
+      }
+    }
+
+    const filesDeleted = sweepOrphanDeltaFiles(db, minAgeMs, now);
+    const result = { finalized, filesDeleted, skippedProcessing };
+    if (finalized > 0 || filesDeleted > 0) {
+      log.info(result, "Recovered in-flight message content");
+    }
+    return result;
+  } finally {
+    db.close();
+  }
+}
+
+/**
+ * Delete delta files no `finalized = 0` row references. Re-reads the
+ * unfinalized set so a row whose fold we skipped (busy conversation, fresh
+ * file) keeps its file, and honours the same age floor so a live writer's file
+ * is never unlinked mid-stream.
+ */
+function sweepOrphanDeltaFiles(
+  db: Database,
+  minAgeMs: number,
+  now: number,
+): number {
+  const referenced = new Set<string>();
+  const rows = db
+    .query(`SELECT content FROM messages WHERE finalized = 0`)
+    .all() as Array<{ content: string }>;
+  for (const row of rows) {
+    const absPath = refAbsPath(row.content);
+    if (absPath != null) {
+      referenced.add(absPath);
+    }
+  }
+
+  const conversationsDir = getConversationsDir();
+  let convDirNames: string[];
+  try {
+    convDirNames = readdirSync(conversationsDir);
+  } catch {
+    return 0; // no conversations directory yet
+  }
+
+  let deleted = 0;
+  for (const name of convDirNames) {
+    const inflightDir = join(conversationsDir, name, "inflight");
+    let files: string[];
+    try {
+      files = readdirSync(inflightDir);
+    } catch {
+      continue; // not a directory, or has no inflight subdirectory
+    }
+    for (const file of files) {
+      if (!file.endsWith(".jsonl")) {
+        continue;
+      }
+      const absPath = resolve(inflightDir, file);
+      if (referenced.has(absPath)) {
+        continue;
+      }
+      const mtime = fileMtimeMs(absPath);
+      if (mtime != null && now - mtime < minAgeMs) {
+        continue; // too fresh — may belong to a live turn
+      }
+      try {
+        rmSync(absPath, { force: true });
+        deleted++;
+      } catch (err) {
+        log.warn(
+          { err, absPath },
+          "in-flight recovery: failed to GC orphan delta file — continuing",
+        );
+      }
+    }
+  }
+  return deleted;
+}

package/src/monitoring/recovery/run-recovery.ts

@@ -0,0 +1,72 @@
+/**
+ * `runRecovery` — the monitor process's recovery orchestrator.
+ *
+ * Startup reconciliation that would otherwise weigh down the daemon's boot
+ * path runs here instead, in the resource-monitor process, off the daemon's
+ * event loop. It lists a set of recovery steps and runs each ONCE, shortly
+ * after the monitor starts — this is crash recovery, not a periodic sweep.
+ * Each step owns the database file it needs and its own logging; the
+ * orchestrator only sequences them and isolates one step's failure from the
+ * next.
+ *
+ * Today the only step is in-flight message content. New reconciliations plug
+ * in by adding a {@link RecoveryStep} to `RECOVERY_STEPS`.
+ */
+
+import { getLogger } from "../../util/logger.js";
+import { recoverInflightContent } from "./inflight-content.js";
+
+const log = getLogger("recovery");
+
+/**
+ * Delay before the one-shot recovery run, giving the daemon time to finish
+ * migrations and clear stale processing flags before recovery reads them.
+ */
+const RECOVERY_DELAY_MS = 15_000;
+
+export interface RecoveryStep {
+  readonly name: string;
+  /** Reconcile once. Owns its own DB handle and logging; may throw. */
+  run(): void;
+}
+
+const RECOVERY_STEPS: RecoveryStep[] = [
+  { name: "inflight-content", run: recoverInflightContent },
+];
+
+/**
+ * Run every recovery step once, in order. Never throws — a step that fails
+ * (most often because the schema is still migrating) is logged and skipped so
+ * one bad step cannot block the rest.
+ */
+export function runRecovery(): void {
+  for (const step of RECOVERY_STEPS) {
+    log.info({ step: step.name }, "Running recovery step");
+    try {
+      step.run();
+    } catch (err) {
+      log.warn({ err, step: step.name }, "Recovery step failed");
+    }
+  }
+}
+
+export interface RecoveryHandle {
+  stop(): void;
+}
+
+/**
+ * Schedule the one-shot recovery run shortly after the monitor starts. Runs
+ * once per monitor lifetime — the next reconciliation happens on the next
+ * daemon (and monitor) restart. The timer is unref'd so recovery never keeps
+ * the process alive; the returned handle cancels it if the monitor shuts down
+ * before it fires.
+ */
+export function startRecovery(): RecoveryHandle {
+  const timer = setTimeout(runRecovery, RECOVERY_DELAY_MS);
+  timer.unref?.();
+  return {
+    stop() {
+      clearTimeout(timer);
+    },
+  };
+}

package/src/monitoring/worker.ts

@@ -2,17 +2,29 @@
  * Standalone entry point for the resource monitor as its own OS process.
  *
  * Spawned at every daemon startup (and on demand by `assistant monitoring
- * start`). Loads config, starts the sampling loop, writes a PID file, and
- * stays alive until SIGTERM/SIGINT.
+ * start`). Loads config, starts the sampling loop and the non-turn telemetry
+ * reporter, writes a PID file, and stays alive until SIGTERM/SIGINT.
  *
  * Running as a separate process — off the assistant's main event loop — is the
- * whole point: the sampler keeps recording during a main-thread freeze, and its
- * on-disk ring buffer survives the OOM SIGKILL that resets all in-VM state.
+ * whole point: the sampler keeps recording during a main-thread freeze, its
+ * on-disk ring buffer survives the OOM SIGKILL that resets all in-VM state,
+ * and telemetry keeps flushing while the daemon is busy or stalled.
  */
 
 import { existsSync, mkdirSync, unlinkSync, writeFileSync } from "node:fs";
 
 import { getConfig } from "../config/loader.js";
+import { rehydratePlatformCredentials } from "../config/platform-rehydration.js";
+import { resetDb } from "../persistence/db-connection.js";
+import { startConsentRefresh } from "../platform/consent-cache.js";
+import {
+  startConfigSnapshotReporter,
+  stopConfigSnapshotReporter,
+} from "../telemetry/config-setting-snapshot.js";
+import {
+  startMonitorUsageTelemetryReporter,
+  stopUsageTelemetryReporter,
+} from "../telemetry/usage-telemetry-reporter.js";
 import { getLogger } from "../util/logger.js";
 import {
   getMonitoringDataDir,
@@ -22,6 +34,7 @@ import {
   type PluginSourceWatchHandle,
   startPluginSourceWatch,
 } from "./plugin-source-watch.js";
+import { type RecoveryHandle, startRecovery } from "./recovery/run-recovery.js";
 import {
   type ResourceSamplerHandle,
   startResourceSampler,
@@ -59,26 +72,72 @@ async function main(): Promise<void> {
     "Resource monitor process started",
   );
 
+  // Rehydrate the platform base URL and IDs from the credential store before
+  // the telemetry reporter starts. The daemon does this in
+  // initializeProvidersAndTools(); this standalone process must do it itself so
+  // the non-turn telemetry it flushes carries the platform organization and
+  // user context instead of shipping with those fields empty.
+  await rehydratePlatformCredentials();
+
   const sampler: ResourceSamplerHandle = startResourceSampler(
     config.monitoring,
   );
   const sourceWatch: PluginSourceWatchHandle = startPluginSourceWatch(
     config.monitoring.pluginSourceScanIntervalMs,
   );
+  // Crash recovery runs here, off the daemon's boot path and event loop.
+  const recovery: RecoveryHandle = startRecovery();
+
+  // Flush the non-turn telemetry sources from this process, off the daemon's
+  // event loop. The reporter's share_analytics gate reads the consent cache,
+  // so this process runs its own refresh loop.
+  startConsentRefresh();
+  startMonitorUsageTelemetryReporter();
+
+  // Emit the tracked config settings into the config_setting pipeline this
+  // process flushes.
+  startConfigSnapshotReporter();
 
-  const shutdown = (signal: string) => {
+  let shuttingDown = false;
+  const shutdown = async (signal: string) => {
+    if (shuttingDown) {
+      return;
+    }
+    shuttingDown = true;
     log.info({ signal }, "Resource monitor process shutting down");
+    recovery.stop();
+    stopConfigSnapshotReporter();
     sourceWatch.stop();
     sampler.stop();
+    // Bounded final telemetry flush, mirroring the daemon's shutdown. This
+    // is load-bearing for the opt-out contract: when share_analytics is
+    // off, flush() is what advances this process's watermarks past rows
+    // recorded during the opt-out window — without it, rows since the last
+    // 5-minute cycle would ship after a later opt-in. When opted in, it
+    // ships the tail instead of leaving it for the next boot.
+    try {
+      const timeout = new Promise<void>((_, reject) =>
+        setTimeout(() => reject(new Error("Telemetry flush timed out")), 3_000),
+      );
+      await Promise.race([stopUsageTelemetryReporter(), timeout]);
+    } catch (err) {
+      log.warn({ err }, "Telemetry reporter shutdown failed (non-fatal)");
+    }
     cleanupPidFile();
     process.exit(0);
   };
 
-  process.on("SIGTERM", () => shutdown("SIGTERM"));
-  process.on("SIGINT", () => shutdown("SIGINT"));
+  process.on("SIGTERM", () => void shutdown("SIGTERM"));
+  process.on("SIGINT", () => void shutdown("SIGINT"));
+
+  process.on("SIGUSR1", () => {
+    log.info("Received SIGUSR1 — refreshing database connections");
+    resetDb();
+  });
 
   process.on("uncaughtException", (err) => {
     log.error({ err }, "Uncaught exception in resource monitor process");
+    recovery.stop();
     sourceWatch.stop();
     sampler.stop();
     cleanupPidFile();
@@ -87,6 +146,7 @@ async function main(): Promise<void> {
 
   process.on("unhandledRejection", (reason) => {
     log.error({ reason }, "Unhandled rejection in resource monitor process");
+    recovery.stop();
     sourceWatch.stop();
     sampler.stop();
     cleanupPidFile();
@@ -94,6 +154,7 @@ async function main(): Promise<void> {
   });
 
   process.on("exit", () => {
+    recovery.stop();
     sourceWatch.stop();
     sampler.stop();
     cleanupPidFile();

package/src/notifications/AGENTS.md

@@ -4,4 +4,4 @@ All notification producers **MUST** go through `emitNotificationSignal()` in `no
 
 When a notification flow creates a server-side conversation (e.g. guardian question conversations, task run conversations), the conversation and initial message **MUST** be persisted before the conversation-created event is emitted. This ensures the macOS/iOS client can immediately fetch the conversation contents when it receives the event.
 
-Guardian-request producers (access requests, tool approvals, tool-grant escalations, voice questions, trusted-contact confirmations) **MUST** record approval-card deliveries through `recordApprovalCardDelivery` / `recordGuardianRequestDeliveries` in `canonical-delivery-recorder.ts` -- never by calling `createCanonicalGuardianDelivery` 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 call the store helper directly for fixtures.)
+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.)

package/src/notifications/README.md

@@ -314,13 +314,13 @@ Connected channels are resolved at signal emission time by `getConnectedChannels
 
 ## Conversation Materialization
 
-The system uses a single conversation materialization path for **all** notifications -- there are no legacy bypass paths or dual-broadcast mechanisms. Every notification, including guardian questions and ingress escalation alerts, flows through `emitNotificationSignal()`:
+The system uses a single conversation materialization path for **all** notifications -- there are no legacy bypass paths or dual-broadcast mechanisms. Every notification, including guardian questions and access-request alerts, flows through `emitNotificationSignal()`:
 
 1. `emitNotificationSignal()` evaluates the signal and dispatches to channels.
 2. `NotificationBroadcaster` pairs each delivery with a conversation via `pairDeliveryWithConversation()`, executing the per-channel conversation action (start_new or reuse_existing).
 3. For vellum deliveries, the broadcaster merges `conversationId` into `deepLinkMetadata` and emits `notification_conversation_created` only when a new conversation was created (not on reuse).
 
-Guardian dispatch follows this same path and uses the optional `onConversationCreated` callback to attach guardian-delivery bookkeeping to the canonical vellum conversation.
+Guardian dispatch follows this same path and uses the optional `onConversationCreated` callback to attach guardian-delivery bookkeeping to the paired vellum conversation.
 
 ### Conversation Pairing Invariant
 
@@ -377,7 +377,7 @@ When the decision engine routes multiple guardian questions to the **same** conv
 
 ### How Request Codes Work
 
-Each `guardian_action_request` is assigned a unique 6-character hex code (e.g. `A1B2C3`) at creation time by `generateRequestCode()` in `guardian-action-store.ts`. The code is included in the notification copy delivered to the guardian.
+Each guardian request is assigned a unique 6-character hex code (e.g. `A1B2C3`) at creation time, generated gateway-side during `guardian_requests_create` (`generateRequestCode()` in `gateway/src/db/guardian-request-store.ts`). The code is included in the notification copy delivered to the guardian.
 
 ### Disambiguation Flow
 
@@ -550,6 +550,6 @@ from the unified `llm` block. Override defaults by setting either of:
 | `llm.callSites.notificationDecision` | object | _(unset)_ | Provider/model/effort/etc. override for the decision engine call site      |
 | `llm.callSites.preferenceExtraction` | object | _(unset)_ | Provider/model/effort/etc. override for the preference extractor call site |
 
-When a call site override is unset, the resolver falls back to `llm.default`.
+When a call site override is unset, the resolver falls back to the shipped call-site default profile.
 
 The notification pipeline is always active -- signals are processed and dispatched as soon as the daemon is running. The audit trail (events, decisions, deliveries) is written for every signal.