@vellumai/assistant 0.12.2-staging.5 → 0.12.2-staging.7

package/src/plugin-api/plugin-channel-turn-trust.test.ts

@@ -0,0 +1,133 @@
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+type InboundTrustReadResult =
+  | {
+      ok: true;
+      verdict: {
+        trustClass: string;
+        canonicalSenderId: string | null;
+        contactId?: string;
+        status?: string;
+        resolutionFailed?: boolean;
+      };
+      admissionPolicy: string | null;
+    }
+  | { ok: false };
+
+let nextRead: InboundTrustReadResult = { ok: false };
+
+mock.module("../calls/inbound-trust-reader.js", () => ({
+  readInboundTrust: async () => nextRead,
+}));
+
+import {
+  PluginTurnNotAdmittedError,
+  resolvePluginChannelTurnTrust,
+} from "./plugin-channel-turn-trust.js";
+
+const CHANNEL = {
+  sourceChannel: "plugin" as const,
+  externalChatId: "imessage:+12025550142",
+  externalUserId: "imessage:+12025550142",
+  displayName: "Ada",
+};
+
+beforeEach(() => {
+  nextRead = { ok: false };
+});
+
+describe("resolvePluginChannelTurnTrust", () => {
+  test("returns the gateway verdict as the turn trust context", async () => {
+    nextRead = {
+      ok: true,
+      verdict: {
+        trustClass: "trusted_contact",
+        canonicalSenderId: "imessage:+12025550142",
+        contactId: "c-ada",
+        status: "active",
+      },
+      admissionPolicy: "trusted_contacts",
+    };
+
+    const trust = await resolvePluginChannelTurnTrust(CHANNEL);
+    expect(trust.trustClass).toBe("trusted_contact");
+    expect(trust.sourceChannel).toBe("plugin");
+    expect(trust.requesterChatId).toBe(CHANNEL.externalChatId);
+  });
+
+  test("fails closed when the gateway could not vouch for the sender", async () => {
+    nextRead = {
+      ok: true,
+      verdict: {
+        trustClass: "unknown",
+        canonicalSenderId: null,
+        resolutionFailed: true,
+      },
+      admissionPolicy: "strangers",
+    };
+
+    await expect(resolvePluginChannelTurnTrust(CHANNEL)).rejects.toMatchObject({
+      name: "PluginTurnNotAdmittedError",
+      reason: "trust_resolution_failed",
+    });
+  });
+
+  test("fails closed when the gateway trust read fails", async () => {
+    nextRead = { ok: false };
+    await expect(resolvePluginChannelTurnTrust(CHANNEL)).rejects.toMatchObject({
+      name: "PluginTurnNotAdmittedError",
+      reason: "trust_resolution_failed",
+    });
+  });
+
+  test("rejects a sender below the channel admission floor", async () => {
+    nextRead = {
+      ok: true,
+      verdict: { trustClass: "unknown", canonicalSenderId: null },
+      admissionPolicy: "guardian_only",
+    };
+
+    await expect(resolvePluginChannelTurnTrust(CHANNEL)).rejects.toEqual(
+      expect.objectContaining({
+        name: "PluginTurnNotAdmittedError",
+        reason: "admission_policy_guardian_only",
+      }),
+    );
+  });
+
+  test("rejects a blocked member regardless of floor", async () => {
+    nextRead = {
+      ok: true,
+      verdict: {
+        trustClass: "trusted_contact",
+        canonicalSenderId: "imessage:+12025550142",
+        contactId: "c-ada",
+        status: "blocked",
+      },
+      admissionPolicy: "strangers",
+    };
+
+    await expect(resolvePluginChannelTurnTrust(CHANNEL)).rejects.toMatchObject({
+      name: "PluginTurnNotAdmittedError",
+      reason: "member_blocked",
+    });
+  });
+
+  test("admits when the gateway reports no admission policy", async () => {
+    nextRead = {
+      ok: true,
+      verdict: { trustClass: "unknown", canonicalSenderId: null },
+      admissionPolicy: null,
+    };
+
+    const trust = await resolvePluginChannelTurnTrust(CHANNEL);
+    expect(trust.trustClass).toBe("unknown");
+  });
+
+  test("PluginTurnNotAdmittedError names the deny reason", () => {
+    const err = new PluginTurnNotAdmittedError("admission_policy_no_one");
+    expect(err).toBeInstanceOf(Error);
+    expect(err.reason).toBe("admission_policy_no_one");
+    expect(err.message).toContain("admission_policy_no_one");
+  });
+});

package/src/plugin-api/plugin-channel-turn-trust.ts

@@ -0,0 +1,71 @@
+/**
+ * Gateway admission and trust for plugin turns addressed by a channel chat.
+ *
+ * A channel address means an inbound sender, not an internal plugin job.
+ * Trust comes from the gateway verdict (`resolve_inbound_trust`); the turn
+ * runs only when that sender clears the channel admission floor.
+ */
+
+import { meetsAdmissionFloor } from "@vellumai/gateway-client";
+
+import { readInboundTrust } from "../calls/inbound-trust-reader.js";
+import type { ChannelId } from "../channels/types.js";
+import type { TrustContext } from "../daemon/trust-context-types.js";
+import { trustContextFromVerdict } from "../runtime/trust-verdict-consumer.js";
+
+interface PluginChannelTurnAddress {
+  sourceChannel: ChannelId;
+  externalChatId: string;
+  externalUserId?: string | null;
+  displayName?: string | null;
+  username?: string | null;
+}
+
+export class PluginTurnNotAdmittedError extends Error {
+  readonly reason: string;
+
+  constructor(reason: string) {
+    super(`This inbound plugin turn was not admitted (${reason}).`);
+    this.name = "PluginTurnNotAdmittedError";
+    this.reason = reason;
+  }
+}
+
+export async function resolvePluginChannelTurnTrust(
+  channel: PluginChannelTurnAddress,
+): Promise<TrustContext> {
+  const actorExternalId = channel.externalUserId?.trim() || undefined;
+  const read = await readInboundTrust({
+    channelType: channel.sourceChannel,
+    actorExternalId,
+  });
+  if (!read.ok) {
+    throw new PluginTurnNotAdmittedError("trust_resolution_failed");
+  }
+
+  if (read.verdict.resolutionFailed) {
+    throw new PluginTurnNotAdmittedError("trust_resolution_failed");
+  }
+
+  const memberStatus = read.verdict.status;
+  if (memberStatus === "blocked" || memberStatus === "revoked") {
+    throw new PluginTurnNotAdmittedError(`member_${memberStatus}`);
+  }
+
+  const trustClass = read.verdict.trustClass;
+  if (
+    read.admissionPolicy != null &&
+    !meetsAdmissionFloor(read.admissionPolicy, trustClass)
+  ) {
+    throw new PluginTurnNotAdmittedError(
+      `admission_policy_${read.admissionPolicy}`,
+    );
+  }
+
+  return trustContextFromVerdict(read.verdict, {
+    sourceChannel: channel.sourceChannel,
+    conversationExternalId: channel.externalChatId,
+    actorDisplayName: channel.displayName ?? undefined,
+    actorUsername: channel.username ?? undefined,
+  });
+}

package/src/plugins/defaults/memory/AGENTS.md

@@ -68,6 +68,13 @@ Everything else under the plugin root is **spine**:
   the writer plus the one matcher every reader uses. It lives at the root
   precisely so `substrate/`, `graph/`, and `graph-topology/` can all reach it
   without a tier importing spine. Do not add a second matcher anywhere),
+  `buffer-file` (the two writers of `memory/buffer.md`: the append every
+  `remember()`-shaped path uses and the consume the consolidation job runs
+  after a pass. Do not write the buffer from anywhere else, and never
+  rewrite it from a read that is not inside `consumeBufferEntries`'s
+  synchronous critical section), `memory-run-evidence` (readers of what a
+  background memory run durably produced from its persisted messages; every
+  job that gates a state transition on a verified write uses them),
   `segmenter`, `message-media`, `worker`, `worker-control`,
   `memory-recall-log-store`, `activation-session-store` (the onboarding
   activation rail — **not** a memory tier despite the name),
@@ -407,8 +414,13 @@ per distinct matched section, at most `memory.v3.finderSectionsPerPage` in
 surfacing order (needle, dense, reply, span) plus its entity and rare-term
 lines, and selecting a line selects that section; the selection log keeps
 one row per slug, so the pool row is where the per-section verdicts live. A
-turn whose selector never judged a pool (the injection gate hard-skipped it,
-or nothing was pooled) persists an empty pool with `selector_ran = 0`, and a
+turn whose selector never judged a pool persists it with `selector_ran = 0`:
+an empty pool when the injection gate hard-skipped it or nothing was pooled,
+and the pool as the selector was given it, stable-prefix cards chosen and
+finder lines not, when the selector's provider failed and the orchestrator
+kept that prefix unjudged. That turn writes no `memory_v3_selections` rows:
+the hot set's frecency and the learned-edge graph read that table as
+judgments, and an unjudged page is not one. A
 turn that logged no selections is still reachable by its stamped
 `message_id`, so the inspector shows negative verdicts too. The pool row and
 the turn's `memory_v3_selections` rows are

package/src/plugins/defaults/memory/__tests__/buffer-file.test.ts

@@ -0,0 +1,320 @@
+/**
+ * Tests for `buffer-file.ts`: the two writers of `memory/buffer.md`.
+ *
+ * The consume cases pin the invariant the module exists for: an entry saved
+ * at any point while a consolidation run is in flight is either the run's
+ * own material or still in the buffer afterwards, never destroyed. The
+ * cross-process case is the reason to believe it: a child process appends
+ * as fast as it can while this process consumes in a loop, and every tagged
+ * entry must end up consumed or present. The same harness run against a
+ * naive read-modify-write consume loses entries, which is what the
+ * mechanism is measured against.
+ */
+
+import {
+  appendFileSync,
+  chmodSync,
+  closeSync,
+  existsSync,
+  mkdtempSync,
+  openSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  afterAll,
+  beforeAll,
+  beforeEach,
+  describe,
+  expect,
+  test,
+} from "bun:test";
+
+import {
+  appendBufferAndArchive,
+  consumeBufferEntries,
+} from "../buffer-file.js";
+import {
+  type BufferEntryLines,
+  bufferEntryText,
+  formatRememberEntry,
+  joinBufferEntries,
+  splitBufferContent,
+} from "../buffer-format.js";
+
+let tmp: string;
+beforeAll(() => {
+  tmp = mkdtempSync(join(tmpdir(), "memory-buffer-file-test-"));
+});
+afterAll(() => {
+  rmSync(tmp, { recursive: true, force: true });
+});
+
+let memoryDir: string;
+let bufferPath: string;
+beforeEach(() => {
+  memoryDir = mkdtempSync(join(tmp, "memory-"));
+  bufferPath = join(memoryDir, "buffer.md");
+});
+
+const A = "- [Apr 27, 9:00 AM] Alice prefers VS Code.";
+const B = "- [Apr 27, 9:01 AM] Bob shared a snippet:\n  line two\n  line three";
+const C = "- [Apr 27, 9:02 AM] Carol loves jazz.";
+const D = "- [Apr 27, 9:03 AM] Dave runs marathons.";
+
+function file(...entries: string[]): string {
+  return entries.map((e) => `${e}\n`).join("");
+}
+function entries(content: string): BufferEntryLines[] {
+  return splitBufferContent(content);
+}
+function texts(): string[] {
+  return entries(readFileSync(bufferPath, "utf-8")).map(bufferEntryText);
+}
+
+describe("appendBufferAndArchive", () => {
+  test("appends to the buffer and the dated archive, seeding the archive header once", () => {
+    const now = new Date(2026, 3, 27, 9, 0);
+    const entry = formatRememberEntry("Alice prefers VS Code.", now);
+    const first = appendBufferAndArchive({ rootDir: memoryDir, entry, now });
+    appendBufferAndArchive({ rootDir: memoryDir, entry, now });
+
+    expect(first.bufferPath).toBe(bufferPath);
+    expect(readFileSync(bufferPath, "utf-8")).toBe(entry + entry);
+    expect(first.archivePath).toBe(join(memoryDir, "archive", "2026-04-27.md"));
+    expect(readFileSync(first.archivePath, "utf-8")).toBe(
+      `# Apr 27, 2026\n\n${entry}${entry}`,
+    );
+  });
+});
+
+describe("consumeBufferEntries", () => {
+  test("removes exactly the consumed entries and keeps the rest verbatim and in order", async () => {
+    writeFileSync(bufferPath, file(A, B, C, D));
+    const pass = entries(file(A, B));
+
+    const result = await consumeBufferEntries(bufferPath, pass, {
+      lateAppendGraceMs: 0,
+    });
+
+    expect(result).toEqual({
+      removed: 2,
+      alreadyAbsent: 0,
+      lateAppendBytesRecovered: 0,
+      unrecoveredLateAppendBytes: 0,
+      lateAppendDrainFailed: false,
+    });
+    expect(readFileSync(bufferPath, "utf-8")).toBe(file(C, D));
+  });
+
+  test("entries appended after the snapshot survive, including one that duplicates a consumed entry", async () => {
+    // The snapshot held one copy of A; the same fact was remembered again
+    // during the run. Multiset semantics: one copy goes, one stays.
+    writeFileSync(bufferPath, file(A, B));
+    const pass = entries(file(A, B));
+    appendFileSync(bufferPath, file(C, A));
+
+    const result = await consumeBufferEntries(bufferPath, pass, {
+      lateAppendGraceMs: 0,
+    });
+
+    expect(result.removed).toBe(2);
+    expect(texts()).toEqual([C, A]);
+  });
+
+  test("a consumed entry missing from the live file is counted, not searched for", async () => {
+    writeFileSync(bufferPath, file(B, C));
+    const pass = entries(file(A, B));
+
+    const result = await consumeBufferEntries(bufferPath, pass, {
+      lateAppendGraceMs: 0,
+    });
+
+    expect(result).toMatchObject({ removed: 1, alreadyAbsent: 1 });
+    expect(texts()).toEqual([C]);
+  });
+
+  test("a missing buffer file consumes nothing and creates nothing", async () => {
+    const result = await consumeBufferEntries(bufferPath, entries(file(A)), {
+      lateAppendGraceMs: 0,
+    });
+
+    expect(result).toEqual({
+      removed: 0,
+      alreadyAbsent: 1,
+      lateAppendBytesRecovered: 0,
+      unrecoveredLateAppendBytes: 0,
+      lateAppendDrainFailed: false,
+    });
+    expect(existsSync(bufferPath)).toBe(false);
+  });
+
+  test("consuming everything leaves an empty file and no temp file behind", async () => {
+    writeFileSync(bufferPath, file(A, B));
+
+    await consumeBufferEntries(bufferPath, entries(file(A, B)), {
+      lateAppendGraceMs: 0,
+    });
+
+    expect(readFileSync(bufferPath, "utf-8")).toBe("");
+    expect(readdirSync(memoryDir)).toEqual(["buffer.md"]);
+  });
+
+  test("an append that landed on the replaced inode is drained back into the buffer", async () => {
+    // An appender that opened the file before the rename writes to the old
+    // inode. The consumer holds that inode open and copies the late bytes
+    // over. The test plays the appender: open before, write after the
+    // synchronous phase, before the grace-window drain.
+    writeFileSync(bufferPath, file(A, B));
+    const lateFd = openSync(bufferPath, "a");
+    const consuming = consumeBufferEntries(bufferPath, entries(file(A)), {
+      lateAppendGraceMs: 50,
+    });
+    // The synchronous phase (read, rewrite, rename) ran before the first
+    // await inside consume, so this write lands on the orphaned inode.
+    appendFileSync(lateFd, file(C));
+    closeSync(lateFd);
+
+    const result = await consuming;
+
+    expect(result.removed).toBe(1);
+    expect(result.lateAppendBytesRecovered).toBe(file(C).length);
+    expect(result.unrecoveredLateAppendBytes).toBe(0);
+    expect(texts()).toEqual([B, C]);
+  });
+
+  test("a late append the drain cannot copy back is reported, not thrown, and the pass stays consumed", async () => {
+    // The rename has committed when the drain runs, so a failing copy must
+    // not surface as "nothing happened". The test makes the rewritten
+    // buffer read-only before the late bytes land, so every copy attempt
+    // fails.
+    writeFileSync(bufferPath, file(A, B));
+    const lateFd = openSync(bufferPath, "a");
+    const consuming = consumeBufferEntries(bufferPath, entries(file(A)), {
+      lateAppendGraceMs: 50,
+    });
+    chmodSync(bufferPath, 0o444);
+    appendFileSync(lateFd, file(C));
+    closeSync(lateFd);
+
+    try {
+      const result = await consuming;
+      expect(result.removed).toBe(1);
+      expect(result.lateAppendBytesRecovered).toBe(0);
+      expect(result.unrecoveredLateAppendBytes).toBe(file(C).length);
+      expect(result.lateAppendDrainFailed).toBe(false);
+      expect(texts()).toEqual([B]);
+    } finally {
+      chmodSync(bufferPath, 0o644);
+    }
+  });
+});
+
+/**
+ * The cross-process invariant. A child appends `count` tagged entries as
+ * fast as it can through `appendFileSync`; this process consumes the leading
+ * entries (up to `passSize` at a time) in a loop through `consume`. Returns
+ * the tags that were neither consumed by a pass nor left in the buffer: the
+ * entries the consume destroyed.
+ */
+async function lostUnder(
+  consume: (path: string, pass: BufferEntryLines[]) => Promise<unknown>,
+  count: number,
+  passSize: number,
+): Promise<{ lost: string[]; duplicated: string[]; passes: number }> {
+  const tag = `t${Math.random().toString(36).slice(2, 8)}`;
+  writeFileSync(bufferPath, "");
+  const child = Bun.spawn(
+    [
+      process.execPath,
+      join(import.meta.dir, "fixtures", "buffer-appender.ts"),
+      bufferPath,
+      String(count),
+      tag,
+    ],
+    { stdout: "ignore", stderr: "inherit" },
+  );
+  const consumed: string[] = [];
+  let passes = 0;
+  let childDone = false;
+  void child.exited.then(() => {
+    childDone = true;
+  });
+  while (!childDone) {
+    const snapshot = entries(readFileSync(bufferPath, "utf-8"));
+    const pass = snapshot.slice(0, passSize);
+    if (pass.length === 0) {
+      await Bun.sleep(1);
+      continue;
+    }
+    await consume(bufferPath, pass);
+    consumed.push(...pass.map(bufferEntryText));
+    passes += 1;
+  }
+  await child.exited;
+  const seen = new Map<string, number>();
+  for (const text of [...consumed, ...texts()]) {
+    seen.set(text, (seen.get(text) ?? 0) + 1);
+  }
+  const lost: string[] = [];
+  const duplicated: string[] = [];
+  for (let i = 0; i < count; i++) {
+    const text = `- [Apr 27, 9:00 AM] ${tag}-${i}`;
+    const n = seen.get(text) ?? 0;
+    if (n === 0) {
+      lost.push(text);
+    } else if (n > 1) {
+      duplicated.push(text);
+    }
+  }
+  return { lost, duplicated, passes };
+}
+
+/** The read-modify-write the production consume replaces. */
+async function naiveConsume(
+  path: string,
+  pass: BufferEntryLines[],
+): Promise<void> {
+  const pending = pass.map(bufferEntryText);
+  const remaining = entries(readFileSync(path, "utf-8")).filter((entry) => {
+    const index = pending.indexOf(bufferEntryText(entry));
+    if (index === -1) {
+      return true;
+    }
+    pending.splice(index, 1);
+    return false;
+  });
+  writeFileSync(path, joinBufferEntries(remaining), "utf-8");
+}
+
+describe("consumeBufferEntries under a concurrent appender in another process", () => {
+  const APPENDS = 4000;
+
+  test("no entry appended during consumption is lost or duplicated", async () => {
+    // Runs the consume exactly as production does, grace window included:
+    // the window is what makes the invariant hold, and a loaded machine
+    // can deschedule the appender between its open and its write for
+    // longer than a token grace would cover. Larger passes keep the run
+    // short with the full grace paid per pass.
+    const outcome = await lostUnder(
+      (path, pass) => consumeBufferEntries(path, pass),
+      APPENDS,
+      500,
+    );
+    expect(outcome.passes).toBeGreaterThan(0);
+    expect(outcome.lost).toEqual([]);
+    expect(outcome.duplicated).toEqual([]);
+  }, 60_000);
+
+  test("the naive read-modify-write consume loses entries under the same load", async () => {
+    // Sensitivity check for the harness: the mechanism above is only
+    // evidence if this shape, run identically, fails.
+    const outcome = await lostUnder(naiveConsume, APPENDS, 500);
+    expect(outcome.passes).toBeGreaterThan(0);
+    expect(outcome.lost.length).toBeGreaterThan(0);
+  }, 60_000);
+});

package/src/plugins/defaults/memory/__tests__/buffer-format.test.ts

@@ -10,10 +10,13 @@
 import { describe, expect, test } from "bun:test";
 
 import {
+  bufferEntryText,
   formatBufferTimestamp,
   formatRememberEntry,
   isBufferEntryStart,
+  joinBufferEntries,
   matchBufferEntryStart,
+  splitBufferContent,
   splitBufferEntries,
 } from "../buffer-format.js";
 
@@ -202,3 +205,43 @@ describe("splitBufferEntries", () => {
     expect(splitBufferEntries([])).toEqual([]);
   });
 });
+
+describe("splitBufferContent / joinBufferEntries", () => {
+  const content =
+    formatRememberEntry("Alice prefers dark mode", new Date(2026, 0, 1, 9, 0)) +
+    formatRememberEntry(
+      "Bob's plan:\n- [ ] step one\n\nend",
+      new Date(2026, 0, 1, 9, 1),
+    );
+
+  test("round-trips newline-terminated content byte for byte", () => {
+    expect(joinBufferEntries(splitBufferContent(content))).toBe(content);
+  });
+
+  test("an entry's text is the same whether or not it is last in the file", () => {
+    const [first] = splitBufferContent(content);
+    const [alone] = splitBufferContent(
+      formatRememberEntry(
+        "Alice prefers dark mode",
+        new Date(2026, 0, 1, 9, 0),
+      ),
+    );
+    expect(bufferEntryText(alone!)).toBe(bufferEntryText(first!));
+    expect(bufferEntryText(alone!)).toBe(
+      "- [Jan 1, 9:00 AM] Alice prefers dark mode",
+    );
+  });
+
+  test("empty content has no entries and joins back to empty", () => {
+    expect(splitBufferContent("")).toEqual([]);
+    expect(joinBufferEntries([])).toBe("");
+  });
+
+  test("content without a terminating newline keeps its last line intact", () => {
+    const entries = splitBufferContent("- [Jan 1, 9:00 AM] partial appe");
+    expect(entries).toHaveLength(1);
+    expect(bufferEntryText(entries[0]!)).toBe(
+      "- [Jan 1, 9:00 AM] partial appe",
+    );
+  });
+});

package/src/plugins/defaults/memory/__tests__/fixtures/buffer-appender.ts

@@ -0,0 +1,17 @@
+// Child process for the buffer-file cross-process test: appends `count`
+// uniquely tagged entries to `bufferPath` as fast as it can, through the same
+// `appendFileSync` call the production appender uses. Hand-formats the entry
+// line so the fixture imports nothing from `src/`.
+//
+// usage: bun buffer-appender.ts <bufferPath> <count> <tag>
+
+import { appendFileSync } from "node:fs";
+
+const [bufferPath, countArg, tag] = process.argv.slice(2);
+if (!bufferPath || !countArg || !tag) {
+  throw new Error("usage: buffer-appender <bufferPath> <count> <tag>");
+}
+const count = Number.parseInt(countArg, 10);
+for (let i = 0; i < count; i++) {
+  appendFileSync(bufferPath, `- [Apr 27, 9:00 AM] ${tag}-${i}\n`, "utf-8");
+}

package/src/plugins/defaults/memory/__tests__/memory-retrospective-job.test.ts

@@ -117,6 +117,17 @@ let loadedConversations: Record<string, { processing: boolean }> = {};
 // the stale-flag override's age check. Absent ids read as null (stampless).
 let processingStartedAtById: Record<string, number | null> = {};
 
+// The source conversation's recorded wire tool surface (what its last live
+// turn sent to the provider). `null` = no live turn has recorded one yet.
+let mockSourceToolSurface: Array<Record<string, unknown>> | null = null;
+let toolSurfaceReads: string[] = [];
+mock.module("../../../../persistence/conversation-tool-surface.js", () => ({
+  getConversationToolSurface: (conversationId: string) => {
+    toolSurfaceReads.push(conversationId);
+    return mockSourceToolSurface;
+  },
+}));
+
 const watchdogEvents: Array<{
   checkName: string;
   value?: number | null;
@@ -509,6 +520,8 @@ describe("memoryRetrospectiveJob", () => {
     resolveUserSlugCalls = [];
     mockV3TierActive = true;
     mockSkillImprovementActive = false;
+    mockSourceToolSurface = null;
+    toolSurfaceReads = [];
   });
 
   test("first-run happy path: no state row, no prior retrospective, both pointer fields set on success", async () => {
@@ -1842,6 +1855,39 @@ describe("memoryRetrospectiveJob", () => {
     });
   });
 
+  test("replays the source's recorded wire tool surface verbatim on the fork wake", async () => {
+    mockSourceToolSurface = [
+      { name: "bash", description: "Run", input_schema: {} },
+      { name: "remember", description: "Save", input_schema: {} },
+      { name: "bell_jingle", description: "Ring", input_schema: {} },
+      { type: "web_search_20250305", name: "web_search", max_uses: 5 },
+    ];
+
+    await memoryRetrospectiveJob(makeJob(), stubConfig);
+
+    expect(toolSurfaceReads).toEqual(["src-conv-1"]);
+    expect(wakeCalls).toHaveLength(1);
+    // The exact recorded array rides to the wake; the fork sends it in place
+    // of the surface it would resolve for itself.
+    expect(wakeCalls[0]!.opts.wireToolDefinitions).toEqual(
+      mockSourceToolSurface,
+    );
+    // The execution-side pin still rides alongside it.
+    expect(wakeCalls[0]!.opts.toolGateMode).toBe("execution");
+    expect(wakeCalls[0]!.opts.toolContextPin).toBeDefined();
+  });
+
+  test("no recorded source surface → no wireToolDefinitions; the pin alone shapes the wire", async () => {
+    mockSourceToolSurface = null;
+
+    await memoryRetrospectiveJob(makeJob(), stubConfig);
+
+    expect(toolSurfaceReads).toEqual(["src-conv-1"]);
+    expect(wakeCalls).toHaveLength(1);
+    expect("wireToolDefinitions" in wakeCalls[0]!.opts).toBe(false);
+    expect(wakeCalls[0]!.opts.toolContextPin).toBeDefined();
+  });
+
   test("execution mode is unconditional → toolContextPin rides even without a resolved profile", async () => {
     await memoryRetrospectiveJob(
       makeJob(),