@vellumai/assistant 0.8.1 → 0.8.2

package/src/memory/v2/__tests__/skill-store.test.ts

@@ -15,10 +15,13 @@
  *   - It swallows errors from the embedding backend — the function resolves
  *     and the cache is unchanged from prior state.
  *
- * Hermetic by design: the catalog loader, state resolver, embedding backend,
- * Qdrant module, and feature-flag resolver are all module-mocked so the suite
- * never reaches a real backend or filesystem.
+ * Hermetic by design: the embedding backend, Qdrant module, and feature-flag
+ * resolver are module-mocked so the suite never reaches a real backend. One
+ * regression case uses a temp workspace to exercise disk-discovered skills.
  */
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
 
 import { makeMockLogger } from "../../../__tests__/helpers/mock-logger.js";
@@ -48,9 +51,15 @@ interface PruneCall {
   options?: { kind?: string };
 }
 
+interface BackfillCall {
+  prefix: string;
+  kind: string;
+  allowedSuffixes: ReadonlySet<string>;
+}
+
 interface TestState {
-  catalog: SkillSummary[];
-  resolved: ResolvedSkill[];
+  catalog: SkillSummary[] | null;
+  resolved: ResolvedSkill[] | null;
   fullCatalog: CatalogSkill[];
   fullCatalogThrows: Error | null;
   flagsEnabled: Record<string, boolean>;
@@ -60,6 +69,10 @@ interface TestState {
   upsertCalls: UpsertCall[];
   pruneCalls: PruneCall[];
   upsertThrows: Error | null;
+  backfillCalls: BackfillCall[];
+  backfillReturn: number;
+  backfillThrows: Error | null;
+  callSequence: Array<"upsert" | "prune" | "backfill">;
 }
 
 const state: TestState = {
@@ -74,6 +87,10 @@ const state: TestState = {
   upsertCalls: [],
   pruneCalls: [],
   upsertThrows: null,
+  backfillCalls: [],
+  backfillReturn: 0,
+  backfillThrows: null,
+  callSequence: [],
 };
 
 // Stub config so resolveSkillStates / mcp augmentation have something to read.
@@ -83,16 +100,39 @@ mock.module("../../../config/loader.js", () => ({
       qdrant: { url: "http://127.0.0.1:6333", vectorSize: 3, onDisk: false },
     },
     mcp: { servers: {} },
-    skills: { entries: {}, allowBundled: null },
+    skills: { entries: {}, allowBundled: [] },
   }),
 }));
 
 mock.module("../../../config/skills.js", () => ({
-  loadSkillCatalog: () => state.catalog,
+  loadSkillCatalog: () => state.catalog ?? [],
 }));
 
 mock.module("../../../config/skill-state.js", () => ({
-  resolveSkillStates: () => state.resolved,
+  resolveSkillStates: (
+    catalog: SkillSummary[],
+    config: { skills?: { allowBundled?: string[] | null } },
+  ) => {
+    if (state.resolved) return state.resolved;
+    return catalog
+      .filter((summary) => {
+        const allowBundled = config.skills?.allowBundled;
+        return !(
+          summary.source === "bundled" &&
+          allowBundled != null &&
+          !allowBundled.includes(summary.id)
+        );
+      })
+      .map((summary) => ({
+        summary,
+        state:
+          summary.source === "managed" ||
+          summary.source === "bundled" ||
+          summary.source === "plugin"
+            ? "enabled"
+            : "disabled",
+      }));
+  },
 }));
 
 mock.module("../../../config/assistant-feature-flags.js", () => ({
@@ -115,6 +155,7 @@ mock.module("../../embedding-backend.js", () => ({
 mock.module("../qdrant.js", () => ({
   upsertConceptPageEmbedding: async (params: UpsertCall) => {
     if (state.upsertThrows) throw state.upsertThrows;
+    state.callSequence.push("upsert");
     state.upsertCalls.push(params);
   },
   pruneSlugsWithPrefixExcept: async (
@@ -122,8 +163,19 @@ mock.module("../qdrant.js", () => ({
     activeSuffixes: readonly string[],
     options?: { kind?: string },
   ) => {
+    state.callSequence.push("prune");
     state.pruneCalls.push({ prefix, activeSuffixes, options });
   },
+  backfillKindOnPointsWithPrefix: async (
+    prefix: string,
+    kind: string,
+    allowedSuffixes: ReadonlySet<string>,
+  ) => {
+    if (state.backfillThrows) throw state.backfillThrows;
+    state.callSequence.push("backfill");
+    state.backfillCalls.push({ prefix, kind, allowedSuffixes });
+    return state.backfillReturn;
+  },
 }));
 
 mock.module("../../../skills/catalog-cache.js", () => ({
@@ -170,6 +222,10 @@ function resetState(): void {
   state.upsertCalls.length = 0;
   state.pruneCalls.length = 0;
   state.upsertThrows = null;
+  state.backfillCalls.length = 0;
+  state.backfillReturn = 0;
+  state.backfillThrows = null;
+  state.callSequence.length = 0;
   _resetSkillStoreForTests();
 }
 
@@ -390,6 +446,154 @@ describe("seedV2SkillEntries", () => {
     expect(getSkillCapability("skills/unknown-skill")).toBeNull();
   });
 
+  test("skips stale in-flight seed results when a newer refresh is requested", async () => {
+    const skillA = makeSummary({
+      id: "example-skill-a",
+      displayName: "Skill A",
+    });
+    const skillB = makeSummary({
+      id: "example-skill-b",
+      displayName: "Skill B",
+    });
+    state.catalog = [skillA];
+    state.resolved = [{ summary: skillA, state: "enabled" }];
+    state.embedReturn = [[0.1, 0.2, 0.3]];
+
+    const firstSeed = seedV2SkillEntries();
+    state.catalog = [skillB];
+    state.resolved = [{ summary: skillB, state: "enabled" }];
+    const secondSeed = seedV2SkillEntries();
+
+    await Promise.all([firstSeed, secondSeed]);
+
+    expect(state.upsertCalls.map((call) => call.slug)).toEqual([
+      "skills/example-skill-b",
+    ]);
+    expect(getSkillCapability("example-skill-a")).toBeNull();
+    expect(getSkillCapability("example-skill-b")?.content).toContain("Skill B");
+  });
+
+  test("continues draining when waiter continuations enqueue additional generations", async () => {
+    const skillA = makeSummary({
+      id: "example-skill-a",
+      displayName: "Skill A",
+    });
+    const skillB = makeSummary({
+      id: "example-skill-b",
+      displayName: "Skill B",
+    });
+    const skillC = makeSummary({
+      id: "example-skill-c",
+      displayName: "Skill C",
+    });
+
+    function useSkill(skill: SkillSummary, dense: number[]): void {
+      state.catalog = [skill];
+      state.resolved = [{ summary: skill, state: "enabled" }];
+      state.embedReturn = [dense];
+    }
+
+    useSkill(skillA, [0.1, 0.2, 0.3]);
+    const firstSeed = seedV2SkillEntries();
+    const secondSeed = firstSeed.then(() => {
+      useSkill(skillB, [0.4, 0.5, 0.6]);
+      return seedV2SkillEntries();
+    });
+    const thirdSeed = secondSeed.then(() => {
+      useSkill(skillC, [0.7, 0.8, 0.9]);
+      return seedV2SkillEntries();
+    });
+
+    let timeout: ReturnType<typeof setTimeout> | undefined;
+    try {
+      await expect(
+        Promise.race([
+          Promise.all([firstSeed, secondSeed, thirdSeed]),
+          new Promise<never>((_, reject) => {
+            timeout = setTimeout(
+              () => reject(new Error("seed queue stalled")),
+              500,
+            );
+          }),
+        ]),
+      ).resolves.toBeDefined();
+    } finally {
+      if (timeout) clearTimeout(timeout);
+    }
+
+    expect(state.upsertCalls.map((call) => call.slug)).toEqual([
+      "skills/example-skill-a",
+      "skills/example-skill-b",
+      "skills/example-skill-c",
+    ]);
+    expect(getSkillCapability("example-skill-a")).toBeNull();
+    expect(getSkillCapability("example-skill-b")).toBeNull();
+    expect(getSkillCapability("example-skill-c")?.content).toContain("Skill C");
+  });
+
+  test("seeds disk-discovered managed skills omitted from a stale SKILLS.md index", async () => {
+    const workspaceDir = mkdtempSync(join(tmpdir(), "skill-store-index-"));
+    state.resolved = null;
+    state.embedReturn = [[0.7, 0.8, 0.9]];
+
+    try {
+      const skillsDir = join(workspaceDir, "skills");
+      const skillDir = join(skillsDir, "geo-article-writer");
+      mkdirSync(skillDir, { recursive: true });
+      writeFileSync(join(skillsDir, "SKILLS.md"), "- stale-only\n", "utf-8");
+      writeFileSync(
+        join(skillDir, "SKILL.md"),
+        `---
+name: "Geo Article Writer"
+description: "Writes local geo articles"
+metadata:
+  vellum:
+    activation-hints:
+      - user asks for local article drafts
+    avoid-when:
+      - user only wants citation extraction
+---
+
+Write a local article draft.
+`,
+        "utf-8",
+      );
+
+      state.catalog = [
+        {
+          id: "geo-article-writer",
+          name: "Geo Article Writer",
+          displayName: "Geo Article Writer",
+          description: "Writes local geo articles",
+          directoryPath: skillDir,
+          skillFilePath: join(skillDir, "SKILL.md"),
+          source: "managed",
+          activationHints: ["user asks for local article drafts"],
+          avoidWhen: ["user only wants citation extraction"],
+        },
+      ];
+
+      await seedV2SkillEntries();
+    } finally {
+      rmSync(workspaceDir, { recursive: true, force: true });
+    }
+
+    expect(state.upsertCalls).toHaveLength(1);
+    expect(state.upsertCalls[0].slug).toBe("skills/geo-article-writer");
+
+    const entry = getSkillCapability("geo-article-writer");
+    expect(entry).not.toBeNull();
+    expect(entry?.id).toBe("geo-article-writer");
+    expect(entry?.content).toContain('The "Geo Article Writer" skill');
+    expect(entry?.content).toContain("Writes local geo articles");
+    expect(entry?.content).toContain(
+      "Use when: user asks for local article drafts.",
+    );
+    expect(entry?.content).toContain(
+      "Avoid when: user only wants citation extraction.",
+    );
+  });
+
   test("swallows errors from embedWithBackend and leaves prior cache intact", async () => {
     const skillA = makeSummary({ id: "example-skill-a" });
     state.catalog = [skillA];
@@ -444,6 +648,118 @@ describe("seedV2SkillEntries", () => {
     expect([...state.pruneCalls[0].activeSuffixes]).toEqual(["remote-only"]);
   });
 
+  test("passes kind: 'skill' to upsert and prune so legacy skill rows stay scoped to the skill kind", async () => {
+    const skillA = makeSummary({ id: "example-skill-a" });
+    state.catalog = [skillA];
+    state.resolved = [{ summary: skillA, state: "enabled" }];
+    state.fullCatalog = [
+      { id: "example-skill-a", name: "example-skill-a", description: "A" },
+    ];
+    state.embedReturn = [[0.1, 0.2, 0.3]];
+
+    await seedV2SkillEntries();
+
+    expect(state.upsertCalls).toHaveLength(1);
+    expect(state.upsertCalls[0].kind).toBe("skill");
+    expect(state.pruneCalls).toHaveLength(1);
+    expect(state.pruneCalls[0].options).toEqual({ kind: "skill" });
+  });
+
+  test("runs the legacy kind backfill before pruning so kindless skill points become prunable", async () => {
+    // Simulates an install carrying legacy skill points written before the
+    // kind discriminator existed: the backfill must run before prune so the
+    // kind-scoped prune can see and delete the orphans.
+    const skillA = makeSummary({ id: "example-skill-a" });
+    state.catalog = [skillA];
+    state.resolved = [{ summary: skillA, state: "enabled" }];
+    state.fullCatalog = [
+      { id: "example-skill-a", name: "example-skill-a", description: "A" },
+    ];
+    state.embedReturn = [[0.1, 0.2, 0.3]];
+    state.backfillReturn = 3;
+
+    await seedV2SkillEntries();
+
+    expect(state.backfillCalls).toHaveLength(1);
+    expect(state.backfillCalls[0].prefix).toBe("skills/");
+    expect(state.backfillCalls[0].kind).toBe("skill");
+    expect([...state.backfillCalls[0].allowedSuffixes].sort()).toEqual([
+      "example-skill-a",
+    ]);
+    expect(state.pruneCalls).toHaveLength(1);
+    expect(state.pruneCalls[0].options).toEqual({ kind: "skill" });
+    expect(state.callSequence.filter((s) => s !== "upsert")).toEqual([
+      "backfill",
+      "prune",
+    ]);
+  });
+
+  test("backfill only runs once per process across repeated seed runs", async () => {
+    const skillA = makeSummary({ id: "example-skill-a" });
+    state.catalog = [skillA];
+    state.resolved = [{ summary: skillA, state: "enabled" }];
+    state.fullCatalog = [
+      { id: "example-skill-a", name: "example-skill-a", description: "A" },
+    ];
+    state.embedReturn = [[0.1, 0.2, 0.3]];
+
+    await seedV2SkillEntries();
+    expect(state.backfillCalls).toHaveLength(1);
+
+    // A second seed should not re-scan: new upserts already carry kind, so
+    // there's nothing for the backfill to do.
+    state.embedReturn = [[0.1, 0.2, 0.3]];
+    await seedV2SkillEntries();
+    expect(state.backfillCalls).toHaveLength(1);
+    expect(state.pruneCalls).toHaveLength(2);
+  });
+
+  test("backfill failure is non-fatal — prune still runs and lastSeedError stays clean", async () => {
+    const skillA = makeSummary({ id: "example-skill-a" });
+    state.catalog = [skillA];
+    state.resolved = [{ summary: skillA, state: "enabled" }];
+    state.fullCatalog = [
+      { id: "example-skill-a", name: "example-skill-a", description: "A" },
+    ];
+    state.embedReturn = [[0.1, 0.2, 0.3]];
+    state.backfillThrows = new Error("qdrant scroll exploded");
+
+    await expect(
+      seedV2SkillEntries({ throwOnError: true }),
+    ).resolves.toBeUndefined();
+
+    // Prune still ran despite the backfill failure — we don't want to block
+    // the steady-state prune when the legacy scan trips.
+    expect(state.pruneCalls).toHaveLength(1);
+  });
+
+  test("backfill allowlist spans installed + remote catalog ids so user-authored skills/* pages stay untagged", async () => {
+    // Regression: backfilling kind on every `skills/*` point would also tag
+    // user-authored concept pages slugged like `skills/my-notes` — those
+    // would then be pruned as stale skills. The allowlist must contain
+    // every legitimate skill id we know about (installed + remote catalog)
+    // and nothing else.
+    const installed = makeSummary({ id: "installed-skill" });
+    state.catalog = [installed];
+    state.resolved = [{ summary: installed, state: "enabled" }];
+    state.fullCatalog = [
+      { id: "installed-skill", name: "installed-skill", description: "X" },
+      { id: "remote-only-skill", name: "remote-only-skill", description: "Y" },
+    ];
+    state.embedReturn = [
+      [0.1, 0.2, 0.3],
+      [0.4, 0.5, 0.6],
+    ];
+
+    await seedV2SkillEntries();
+
+    expect(state.backfillCalls).toHaveLength(1);
+    expect([...state.backfillCalls[0].allowedSuffixes].sort()).toEqual([
+      "installed-skill",
+      "remote-only-skill",
+    ]);
+  });
+
   test("skips pruning when catalog fetch returns empty (network failure guard)", async () => {
     const skillA = makeSummary({ id: "example-skill-a" });
     state.catalog = [skillA];
@@ -473,6 +789,38 @@ describe("getSkillCapability", () => {
 
     expect(getSkillCapability("does-not-exist")).toBeNull();
   });
+
+  test("mutating the returned entry does not corrupt the cache", async () => {
+    const skillA = makeSummary({ id: "example-skill-a" });
+    state.catalog = [skillA];
+    state.resolved = [{ summary: skillA, state: "enabled" }];
+    state.embedReturn = [[0.1, 0.2, 0.3]];
+
+    await seedV2SkillEntries();
+
+    const first = getSkillCapability("example-skill-a");
+    expect(first).not.toBeNull();
+    const originalContent = first!.content;
+
+    // Frozen entries throw in strict mode when mutated; suppress so we can
+    // prove cache invariance even if a future refactor swaps freeze for a
+    // plain clone.
+    try {
+      (first as unknown as { id: string }).id = "tampered";
+      (first as unknown as { content: string }).content = "tampered";
+    } catch {
+      // expected under Object.freeze
+    }
+
+    const second = getSkillCapability("example-skill-a");
+    expect(second?.id).toBe("example-skill-a");
+    expect(second?.content).toBe(originalContent);
+
+    // listSkillEntries path also unaffected.
+    const viaList = listSkillEntries();
+    expect(viaList[0].id).toBe("example-skill-a");
+    expect(viaList[0].content).toBe(originalContent);
+  });
 });
 
 describe("listSkillEntries", () => {
@@ -521,4 +869,35 @@ describe("listSkillEntries", () => {
     expect(second).toHaveLength(1);
     expect(second[0].id).toBe("example-skill-a");
   });
+
+  test("mutating a returned entry does not corrupt the cache", async () => {
+    const skillA = makeSummary({ id: "example-skill-a" });
+    state.catalog = [skillA];
+    state.resolved = [{ summary: skillA, state: "enabled" }];
+    state.embedReturn = [[0.1, 0.2, 0.3]];
+
+    await seedV2SkillEntries();
+
+    const first = listSkillEntries();
+    expect(first).toHaveLength(1);
+    const originalContent = first[0].content;
+
+    // Frozen entries throw in strict mode (ESM tests are strict) when
+    // mutated; suppress so we can prove cache invariance even if a future
+    // refactor swaps freeze for a plain clone.
+    try {
+      (first[0] as { id: string }).id = "tampered";
+      (first[0] as { content: string }).content = "tampered";
+    } catch {
+      // expected under Object.freeze
+    }
+
+    const second = listSkillEntries();
+    expect(second[0].id).toBe("example-skill-a");
+    expect(second[0].content).toBe(originalContent);
+
+    // Lookup-by-id path also unaffected.
+    const viaLookup = getSkillCapability("example-skill-a");
+    expect(viaLookup?.content).toBe(originalContent);
+  });
 });

package/src/memory/v2/injection.ts

@@ -144,6 +144,7 @@ export async function injectMemoryV2Block(
   } = params;
 
   const workspaceDir = getWorkspaceDir();
+  const mode: InjectMemoryV2Mode = params.mode ?? "per-turn";
 
   // (1) Hydrate. Missing rows are normal at conversation start — proceed
   // with an effective empty prior state so the first turn can still inject.
@@ -151,10 +152,17 @@ export async function injectMemoryV2Block(
   const priorState = await hydrate(database, conversationId);
 
   // Flag-gated router dispatch: when the LLM router is enabled, route the
-  // per-turn page selection through `runRouter` and reuse `finalizeInjection`
-  // for persistence, render, and telemetry. The activation pipeline below
+  // page selection through `runRouter` and reuse `finalizeInjection` for
+  // persistence, render, and telemetry. The activation pipeline below
   // remains the default (flag-off) behavior — every code path past this
   // branch only runs when the router is disabled.
+  //
+  // Runs on both `per-turn` and `context-load`. The `everInjected` dedupe
+  // concern from earlier doesn't apply post-compaction because
+  // `evictCompactedTurnsV2` in `ConversationGraphMemory.onCompacted`
+  // empties the list before this code runs. Router abstention on
+  // context-load means no v2 pages restored that turn, which is preferable
+  // to letting the activation graph pick something arbitrary.
   if (config.memory.v2.router.enabled) {
     return injectViaRouter({
       workspaceDir,
@@ -214,7 +222,6 @@ export async function injectMemoryV2Block(
   // prior cached attachments don't exist or have been thrown away. The user
   // message gets a complete top-K dump alongside the static
   // essentials/threads/recent block, then per-turn turns just add deltas.
-  const mode: InjectMemoryV2Mode = params.mode ?? "per-turn";
   const priorEverInjected: readonly EverInjectedEntry[] =
     priorState?.everInjected ?? [];
   const { topNow, toInject } = selectInjections({
@@ -310,6 +317,14 @@ async function finalizeInjection(args: {
   telemetryRows: MemoryV2ConceptRowRecord[];
   config: AssistantConfig;
   nextStateMap: Record<string, number>;
+  /**
+   * When true, errors thrown inside the helper (save / render / status
+   * finalization) are logged and swallowed instead of re-thrown. Used by
+   * the router-failure path, which is already a best-effort cleanup: a
+   * transient SQLite write here must not abort the turn on top of the
+   * router failure that already happened. Defaults to throwing.
+   */
+  bestEffort?: boolean;
 }): Promise<InjectMemoryV2BlockResult> {
   const {
     workspaceDir,
@@ -449,9 +464,16 @@ async function finalizeInjection(args: {
   } catch (err) {
     // Stash the error and let `finally` flush a best-effort telemetry row
     // before we re-throw to the caller. `mode = "errored"` flags the row
-    // for observability dashboards / inspector queries.
+    // for observability dashboards / inspector queries. On the best-effort
+    // path the error is logged and swallowed so the trailing return stands.
     caughtErr = err;
     mode = "errored";
+    if (args.bestEffort) {
+      log.warn(
+        { err, conversationId, turn: currentTurn },
+        "Memory v2 finalizeInjection error on best-effort path — swallowing",
+      );
+    }
   } finally {
     try {
       recordMemoryV2ActivationLog({
@@ -469,7 +491,7 @@ async function finalizeInjection(args: {
     }
   }
 
-  if (caughtErr !== undefined) throw caughtErr;
+  if (caughtErr !== undefined && !args.bestEffort) throw caughtErr;
   return { block, toInject: newlyInjected };
 }
 
@@ -537,7 +559,10 @@ async function injectViaRouter(args: {
     // (preserving `priorEverInjected` so future turns still subtract
     // previously-attached slugs) and writes the telemetry row through the
     // same code path as the success branch — no inline duplication of
-    // `save` + `recordMemoryV2ActivationLog`.
+    // `save` + `recordMemoryV2ActivationLog`. `bestEffort: true` matches
+    // the pre-refactor inline behavior of logging and continuing if the
+    // stub-state `save()` throws — we don't want a transient SQLite write
+    // to abort the turn on top of the router failure that already happened.
     return finalizeInjection({
       workspaceDir,
       database,
@@ -550,6 +575,7 @@ async function injectViaRouter(args: {
       telemetryRows: [],
       config,
       nextStateMap: {},
+      bestEffort: true,
     });
   }
 

package/src/memory/v2/migration.ts

@@ -643,12 +643,15 @@ export async function runMemoryV2Migration(
 }
 
 /**
- * HTML marker embedded in each appended block so a crash-recovery rerun can
- * detect already-applied promotions and skip the append. `appendLines` is a
- * read-modify-write — without this, a crash between `appendPromotions` and
- * `writeSentinel` would let the next boot duplicate every promotion line.
+ * Paired HTML markers wrapped around each appended block. The opening marker
+ * also serves as the idempotency guard: `appendLines` is a read-modify-write,
+ * and without it a crash between `appendPromotions` and `writeSentinel` would
+ * let the next boot duplicate every promotion line. The closing marker
+ * delimits the migration-inserted region so a force-rerun strip can remove
+ * exactly that block without touching user/assistant edits appended below.
  */
-const PROMOTION_MARKER = "<!-- migration:v1-to-v2 -->";
+const PROMOTION_MARKER_OPEN = "<!-- migration:v1-to-v2 -->";
+const PROMOTION_MARKER_CLOSE = "<!-- /migration:v1-to-v2 -->";
 
 /**
  * Append each promotion bucket to its target file. Files are created if
@@ -680,8 +683,8 @@ async function appendPromotions(
 
 /**
  * Append `lines` to `path`, creating it (with a trailing newline) if absent.
- * If the file already contains `PROMOTION_MARKER`, the append is skipped — a
- * prior partially-completed migration already wrote this block.
+ * If the file already contains `PROMOTION_MARKER_OPEN`, the append is skipped
+ * — a prior partially-completed migration already wrote this block.
  */
 async function appendLines(path: string, lines: string[]): Promise<void> {
   let existing = "";
@@ -690,16 +693,17 @@ async function appendLines(path: string, lines: string[]): Promise<void> {
   } catch (err) {
     if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
   }
-  if (existing.includes(PROMOTION_MARKER)) return;
+  if (existing.includes(PROMOTION_MARKER_OPEN)) return;
   const trailing = existing.length === 0 || existing.endsWith("\n") ? "" : "\n";
-  const next = `${existing}${trailing}${PROMOTION_MARKER}\n${lines.join("\n")}\n`;
+  const block = `${PROMOTION_MARKER_OPEN}\n${lines.join("\n")}\n${PROMOTION_MARKER_CLOSE}\n`;
+  const next = `${existing}${trailing}${block}`;
   await writeFile(path, next, "utf-8");
 }
 
 /**
- * Strip any prior migration-block (everything from the marker line through
- * end of file) from each promotion target. Called on force-reruns so the
- * marker guard in `appendLines` doesn't skip the new promotions.
+ * Strip any prior migration-block from each promotion target. Called on
+ * force-reruns so the marker guard in `appendLines` doesn't skip the new
+ * promotions.
  */
 async function stripPromotionMarkerBlocks(workspaceDir: string): Promise<void> {
   const memoryDir = join(workspaceDir, "memory");
@@ -718,6 +722,16 @@ async function stripPromotionMarkerBlocks(workspaceDir: string): Promise<void> {
   await Promise.all(candidates.map(stripMarkerBlock));
 }
 
+/**
+ * Remove the migration-inserted block from `path` while preserving content
+ * outside it. The block is identified by the
+ * `PROMOTION_MARKER_OPEN ... PROMOTION_MARKER_CLOSE` envelope.
+ *
+ * If an opening marker is present without a matching close, strip from the
+ * opening marker to the next blank line, or to EOF if none is found. Content
+ * appended after such an unclosed block without a blank-line separator can
+ * be dropped on that fallback path.
+ */
 async function stripMarkerBlock(path: string): Promise<void> {
   let existing: string;
   try {
@@ -726,13 +740,29 @@ async function stripMarkerBlock(path: string): Promise<void> {
     if ((err as NodeJS.ErrnoException).code === "ENOENT") return;
     throw err;
   }
-  const idx = existing.indexOf(PROMOTION_MARKER);
-  if (idx === -1) return;
-  // Cut from the start of the marker line. `idx` already points at the marker,
-  // which `appendLines` always wrote at the start of its own line, so a plain
-  // slice here also drops the leading newline that preceded it (if any).
-  const trimmed = existing.slice(0, idx).replace(/\n+$/, "");
-  const next = trimmed.length === 0 ? "" : `${trimmed}\n`;
+  const openIdx = existing.indexOf(PROMOTION_MARKER_OPEN);
+  if (openIdx === -1) return;
+
+  let endIdx: number;
+  const closeIdx = existing.indexOf(PROMOTION_MARKER_CLOSE, openIdx);
+  if (closeIdx !== -1) {
+    endIdx = closeIdx + PROMOTION_MARKER_CLOSE.length;
+    if (existing[endIdx] === "\n") endIdx += 1;
+  } else {
+    const blankIdx = existing.indexOf("\n\n", openIdx);
+    endIdx = blankIdx === -1 ? existing.length : blankIdx + 2;
+  }
+
+  const head = existing.slice(0, openIdx).replace(/\n+$/, "");
+  const tail = existing.slice(endIdx);
+  let next: string;
+  if (head.length === 0) {
+    next = tail;
+  } else if (tail.length === 0) {
+    next = `${head}\n`;
+  } else {
+    next = `${head}\n${tail}`;
+  }
   await writeFile(path, next, "utf-8");
 }