@vellumai/assistant 0.8.10 → 0.8.11-staging.1

package/src/plugins/defaults/memory-v3-shadow/injector.ts

@@ -1,38 +1,229 @@
 /**
- * The memory-v3 {@link Injector}. Reads both v3 flags:
- *   - `memory-v3-live` on → orchestrate, log, render the working-set selection
- *     into a `<memory>` block, and return it at v2's dynamic-memory placement.
- *   - `memory-v3-shadow` on (live off) → orchestrate + log only, return `null`.
- *   - both off → return `null` (no orchestration).
+ * The memory-v3 {@link Injector}s: frozen net-new cards + ephemeral spotlight.
  *
- * Empty selection and any failure return `null` (no v3 injection). v2
- * suppression keys off BOTH the flag AND this return value, so a `null` here
- * (failure or empty selection) falls back to v2 memory rather than dropping all
- * memory.
+ * Two injectors share one orchestration result per turn (memoized via
+ * {@link observeTurnOnce} so re-entry assemblies — overflow convergence,
+ * post-compaction re-injection — reuse the turn's selections instead of
+ * re-running the selector):
  *
- * Orchestration and telemetry live in {@link observeTurn}; this module is the
- * thin injector wrapper that renders the result for live injection.
+ *  - {@link memoryV3Injector} (id `memory-v3`, `after-memory-prefix`): the
+ *    PERSISTENT layer. Renders only this turn's NET-NEW selections — selections
+ *    not already in the everInjected store — as compact cards inside one
+ *    `<memory>` block and returns the block. The everInjected store write
+ *    (`recordInjected`) and the prune-valve schedule are DEFERRED to a commit
+ *    callback the block carries (`meta[MEMORY_V3_COMMIT_META_KEY]`): runtime
+ *    assembly invokes it only when the turn's tail is a user message — the
+ *    same gate as metadata capture — so a turn whose block silently fails to
+ *    attach never claims its cards in the store (which would suppress them
+ *    until compaction). Runtime assembly splices the block onto the current
+ *    user message and the user-prompt-submit hook persists the unwrapped inner
+ *    text under `metadata.memoryV3InjectedBlock`; `conversation.ts` rehydrates
+ *    it on load. The block is FROZEN thereafter: prior turns' card blocks stay
+ *    byte-identical in history, so they ride the provider's cached prefix and
+ *    survive restarts — mirroring v2's `memoryInjectedBlock` mechanism. An
+ *    all-repeat turn returns an EMPTY-TEXT block: assembly attaches nothing,
+ *    but the block's presence still keys v2 suppression (v3 ran and owns the
+ *    `<memory>` layer this turn). A `null` return (failure / empty selection /
+ *    every net-new card rendered empty) leaves v2's block intact — fallback to
+ *    v2 rather than a memory-less turn.
+ *
+ *  - {@link memoryV3SpotlightInjector} (id `memory-v3-spotlight`,
+ *    `append-user-tail`): the EPHEMERAL layer. Renders the top `spotlight.n`
+ *    selected finder hits' matched sections, plus the previous
+ *    `spotlight.windowTurns` turns' entries from an in-memory per-conversation
+ *    ring (a daemon restart simply re-warms it), as a `<memory_spotlight>`
+ *    block at the current-message tail. Assembly strip-and-replaces this block
+ *    every turn (scoped to this block id only); it is never persisted to
+ *    metadata.
+ *
+ * Flag gating is unchanged: `memory-v3-live` attaches blocks; `memory-v3-shadow`
+ * (live off) logs what WOULD inject (net-new slugs + bytes + spotlight refs)
+ * and attaches nothing; both off → no orchestration.
+ *
+ * Both injectors apply the same personal-memory trust gate as v2
+ * ({@link isPersonalMemoryAllowed}): an untrusted remote actor's turn
+ * produces nothing — no orchestration, no cards, no spotlight, and nothing
+ * recorded or persisted. Memory pages, skill/CLI capability cards, and
+ * matched-section spotlights all surface private user content — and because
+ * v3 cards are persisted to message metadata and rehydrated forever, the gate
+ * must also keep an untrusted turn from recording or persisting anything.
+ *
+ * Known mirror-of-v2 limitation: cards attached by mid-turn re-entry
+ * assemblies (post-compaction re-injection) live only in memory — metadata is
+ * persisted at the first-call site only — so a restart drops them while the
+ * store still claims them, exactly as v2's `lastInjectedBlock` reinject does.
+ * The next compaction clears the store and resets both layers.
  */
 
 import { isAssistantFeatureFlagEnabled } from "../../../config/assistant-feature-flags.js";
 import { getConfig } from "../../../config/loader.js";
+import { isPersonalMemoryAllowed } from "../../../daemon/trust-context.js";
+import {
+  wrapMemoryBlock,
+  wrapMemorySpotlightBlock,
+} from "../../../memory/memory-marker.js";
 import { getLogger } from "../../../util/logger.js";
 import {
   type InjectionBlock,
   type Injector,
   type TurnContext,
 } from "../../types.js";
-import { renderV3SectionContent } from "./page-content.js";
-import { renderMemoryBlock } from "./render-injection.js";
+import { isCapabilitySlug } from "./capabilities.js";
+import { cardBytes } from "./card.js";
+import { getActiveSlugs, recordInjected } from "./ever-injected-store.js";
+import type { OrchestrateResult } from "./orchestrate.js";
+import { renderV3CardContent } from "./page-content.js";
+import { schedulePruneValve } from "./prune.js";
+import {
+  renderCardsBlockInner,
+  renderSpotlightInner,
+  type SpotlightEntry,
+} from "./render-injection.js";
 import {
   MEMORY_V3_LIVE,
   MEMORY_V3_SHADOW,
   observeTurn,
 } from "./shadow-plugin.js";
-import { MEMORY_V3_BLOCK_ID } from "./types.js";
+import {
+  MEMORY_V3_BLOCK_ID,
+  MEMORY_V3_COMMIT_META_KEY,
+  MEMORY_V3_SPOTLIGHT_BLOCK_ID,
+  type Slug,
+} from "./types.js";
 
 const log = getLogger("memory-v3-shadow");
 
+/**
+ * Cap on the per-conversation maps below. Least-recently-touched entries are
+ * evicted first; an evicted conversation simply re-warms (spotlight) or
+ * re-runs orchestration (memo) on its next turn.
+ */
+const MAX_TRACKED_CONVERSATIONS = 256;
+
+/**
+ * LRU-set `key` on `map`: delete-then-set so a re-touched key moves to the
+ * back of the Map's insertion order (a plain `set` on an existing key keeps
+ * its original position, which would evict the most long-lived ACTIVE
+ * conversation first). Eviction only fires when inserting a genuinely new
+ * key at the cap.
+ */
+function lruSet<V>(map: Map<string, V>, key: string, value: V): void {
+  if (map.has(key)) {
+    map.delete(key);
+  } else if (map.size >= MAX_TRACKED_CONVERSATIONS) {
+    const oldest = map.keys().next().value;
+    if (oldest !== undefined) map.delete(oldest);
+  }
+  map.set(key, value);
+}
+
+// ─── shared per-turn orchestration memo ─────────────────────────────────────
+
+interface ObservedTurn {
+  turnIndex: number;
+  result: Promise<OrchestrateResult | null>;
+}
+
+/** Latest observed turn per conversation (both injectors + re-entry sites
+ *  share one orchestration per turn). */
+const observedTurns = new Map<string, ObservedTurn>();
+
+/**
+ * Run {@link observeTurn} once per (conversation, turn) and memoize the
+ * promise. The cards and spotlight injectors both consume the result, and
+ * re-entry assemblies within the same turn (overflow convergence,
+ * post-compaction re-injection) reuse the turn's selections rather than
+ * paying a second selector call. A new `turnIndex` replaces the entry, so the
+ * memo never holds more than one turn per conversation.
+ */
+function observeTurnOnce(
+  conversationId: string,
+  turnIndex: number,
+): Promise<OrchestrateResult | null> {
+  const cached = observedTurns.get(conversationId);
+  if (cached && cached.turnIndex === turnIndex) return cached.result;
+  const result = observeTurn(conversationId, turnIndex);
+  lruSet(observedTurns, conversationId, { turnIndex, result });
+  return result;
+}
+
+// ─── ephemeral spotlight ring ────────────────────────────────────────────────
+
+interface SpotlightTurn {
+  turnIndex: number;
+  entries: SpotlightEntry[];
+}
+
+/** Recent turns' spotlight entries per conversation, oldest → newest. */
+const spotlightRings = new Map<string, SpotlightTurn[]>();
+
+/**
+ * Compute this turn's spotlight entries: the top `n` SELECTED finder hits'
+ * matched sections, in finder surfacing order (needle → dense → edge
+ * precedence). A finder hit on a stable-prefix page keeps its matched-section
+ * ref in the orchestrate result, so core/hot pages with current relevance
+ * spotlight too.
+ */
+function computeSpotlightEntries(
+  result: OrchestrateResult,
+  n: number,
+): SpotlightEntry[] {
+  const selected = new Set<Slug>(result.selections.map((s) => s.slug));
+  const entries: SpotlightEntry[] = [];
+  for (const candidate of result.lanes.finder) {
+    if (entries.length >= n) break;
+    if (!selected.has(candidate.slug)) continue;
+    const section = result.matchedSections.get(candidate.slug);
+    if (!section) continue;
+    entries.push({
+      slug: candidate.slug,
+      title: section.title,
+      text: section.text,
+    });
+  }
+  return entries;
+}
+
+/**
+ * Fold this turn's entries into the conversation's ring and return the
+ * rendered window: current turn first, then previous turns newest-first,
+ * deduped by slug § heading, bounded by `n × (windowTurns + 1)` entries by
+ * construction. Re-observing the SAME turn (re-entry assembly) replaces that
+ * turn's entry rather than accumulating.
+ */
+function updateSpotlightWindow(
+  conversationId: string,
+  turnIndex: number,
+  entries: SpotlightEntry[],
+  windowTurns: number,
+): SpotlightEntry[] {
+  const prior = (spotlightRings.get(conversationId) ?? []).filter(
+    (t) => t.turnIndex < turnIndex && t.turnIndex >= turnIndex - windowTurns,
+  );
+  lruSet(spotlightRings, conversationId, [...prior, { turnIndex, entries }]);
+
+  const window: SpotlightEntry[] = [];
+  const seen = new Set<string>();
+  // Newest first: this turn's entries, then prior turns newest → oldest.
+  for (const turn of [{ turnIndex, entries }, ...prior.reverse()]) {
+    for (const entry of turn.entries) {
+      const key = `${entry.slug}§${entry.title}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      window.push(entry);
+    }
+  }
+  return window;
+}
+
+/** Test-only reset for the per-turn memo and the spotlight rings. */
+export function resetMemoryV3InjectorStateForTests(): void {
+  observedTurns.clear();
+  spotlightRings.clear();
+}
+
+// ─── injectors ───────────────────────────────────────────────────────────────
+
 export const memoryV3Injector: Injector = {
   name: "memory-v3-shadow",
   // High order so it sorts last; the live `<memory>` block uses the
@@ -41,26 +232,97 @@ export const memoryV3Injector: Injector = {
   order: 1000,
   async produce(ctx: TurnContext): Promise<InjectionBlock | null> {
     const config = getConfig();
+    if (config.memory.enabled === false) return null;
     const live = isAssistantFeatureFlagEnabled(MEMORY_V3_LIVE, config);
     const shadow = isAssistantFeatureFlagEnabled(MEMORY_V3_SHADOW, config);
     if (!live && !shadow) return null;
+    if (!isPersonalMemoryAllowed(ctx.trust)) return null;
 
-    const result = await observeTurn(ctx.conversationId, ctx.turnIndex);
-    if (!live || !result) return null;
+    const result = await observeTurnOnce(ctx.conversationId, ctx.turnIndex);
+    // Empty selection falls back to v2 (return null): v2 suppression keys off
+    // BOTH the flag AND a produced block, so a selector failure or a turn with
+    // nothing selected ships v2 memory rather than no memory.
+    if (!result || result.selections.length === 0) return null;
 
     try {
-      // `renderMemoryBlock` returns "" for an empty selection; inject nothing.
-      const text = await renderMemoryBlock(
-        result.finalInjection,
-        result.sectionBySlug,
-        renderV3SectionContent,
-      );
-      if (text.length === 0) return null;
+      const active = getActiveSlugs(ctx.conversationId);
+      const netNew = result.selections
+        .map((s) => s.slug)
+        .filter((slug) => !active.has(slug));
+
+      // Render net-new cards, skipping slugs that resolve to no content
+      // (deleted pages, unresolvable capabilities) — nothing is attached for
+      // them, so nothing is recorded either.
+      const cards: Array<{ slug: Slug; card: string }> = [];
+      for (const slug of netNew) {
+        const card = await renderV3CardContent(slug);
+        if (card.trim().length > 0) cards.push({ slug, card });
+      }
+      // Every net-new card rendered empty: return null (fall back to v2)
+      // rather than an empty-text block — suppressing v2 with nothing to show
+      // would ship a memory-less turn. Distinct from the all-repeat case
+      // (empty `netNew`), where the empty block correctly keeps v2 suppressed
+      // because the cards already ride history.
+      if (netNew.length > 0 && cards.length === 0) return null;
+      const entries = cards.map(({ slug, card }) => ({
+        slug,
+        // Capability cards (skills / CLI commands) render with their own
+        // `# Skill:` / `# CLI command:` headers, which the prune valve's
+        // `# memory/concepts/<slug>.md` section grammar can never locate to
+        // free. Record them at zero bytes so they never inflate the freeable
+        // resident accounting (the valve would otherwise loop-fire on bytes
+        // it cannot free).
+        bytes: isCapabilitySlug(slug) ? 0 : cardBytes(card),
+      }));
+
+      if (!live) {
+        // Shadow mode: log what WOULD inject, attach and record nothing.
+        const spotlightRefs = computeSpotlightEntries(
+          result,
+          config.memory.v3.spotlight.n,
+        ).map((e) => `${e.slug}§${e.title}`);
+        log.info(
+          {
+            conversationId: ctx.conversationId,
+            turnIndex: ctx.turnIndex,
+            netNew: entries,
+            netNewBytes: entries.reduce((sum, e) => sum + e.bytes, 0),
+            spotlightRefs,
+          },
+          "memory-v3 shadow: would inject net-new cards + spotlight",
+        );
+        return null;
+      }
+
+      // The everInjected store write and the prune-valve schedule are
+      // DEFERRED to this commit callback, invoked by runtime assembly at the
+      // point where attachment is guaranteed (the turn's tail is a user
+      // message — the same gate as metadata capture). Recording here in
+      // `produce()` would let a never-attached turn (non-user tail) claim
+      // cards in the store, suppressing them until compaction. The valve is
+      // scheduled after `recordInjected` so the resident accounting includes
+      // this turn's cards; core/hot lane members are exempt — the selector's
+      // stable prefix must never be pruned out from under it.
+      const commit = (): void => {
+        recordInjected(ctx.conversationId, entries);
+        schedulePruneValve(ctx.conversationId, {
+          exemptSlugs: new Set<Slug>([
+            ...result.lanes.core,
+            ...result.lanes.hot,
+          ]),
+        });
+      };
+
+      // Empty net-new → empty-text block: assembly attaches no content
+      // (`applyInjectionBlock` no-ops empty text) but the block's presence
+      // still marks v3 as this turn's `<memory>` source for v2 suppression.
+      const inner = renderCardsBlockInner(cards.map((c) => c.card));
       return {
         id: MEMORY_V3_BLOCK_ID,
-        text,
+        text: inner.length === 0 ? "" : wrapMemoryBlock(inner),
         // Mirror v2's dynamic `<memory>` block placement.
         placement: "after-memory-prefix",
+        meta: { [MEMORY_V3_COMMIT_META_KEY]: commit },
       };
     } catch (err) {
       log.warn(
@@ -74,3 +336,48 @@ export const memoryV3Injector: Injector = {
     }
   },
 };
+
+export const memoryV3SpotlightInjector: Injector = {
+  name: "memory-v3-spotlight",
+  // After the cards injector so the shared memo is (usually) already primed.
+  order: 1001,
+  async produce(ctx: TurnContext): Promise<InjectionBlock | null> {
+    const config = getConfig();
+    if (config.memory.enabled === false) return null;
+    // Live-only: shadow mode logs spotlight refs from the cards injector and
+    // must keep the turn untouched (no ring state either, so a later
+    // live-flag flip starts from a clean window).
+    if (!isAssistantFeatureFlagEnabled(MEMORY_V3_LIVE, config)) return null;
+    if (!isPersonalMemoryAllowed(ctx.trust)) return null;
+
+    try {
+      const result = await observeTurnOnce(ctx.conversationId, ctx.turnIndex);
+      if (!result || result.selections.length === 0) return null;
+
+      const { n, windowTurns } = config.memory.v3.spotlight;
+      const current = computeSpotlightEntries(result, n);
+      const window = updateSpotlightWindow(
+        ctx.conversationId,
+        ctx.turnIndex,
+        current,
+        windowTurns,
+      );
+      if (window.length === 0) return null;
+
+      return {
+        id: MEMORY_V3_SPOTLIGHT_BLOCK_ID,
+        text: wrapMemorySpotlightBlock(renderSpotlightInner(window)),
+        placement: "append-user-tail",
+      };
+    } catch (err) {
+      log.warn(
+        {
+          err: err instanceof Error ? err.message : String(err),
+          conversationId: ctx.conversationId,
+        },
+        "memory-v3 spotlight render failed (non-fatal) — skipping spotlight",
+      );
+      return null;
+    }
+  },
+};

package/src/plugins/defaults/memory-v3-shadow/maintain-job.ts

@@ -2,7 +2,7 @@
  * Memory v3 — `memory_v3_maintain` job handler.
  *
  * A flag-gated, best-effort self-maintenance pass over the v3 section dense
- * store and the in-memory lanes. It runs three independent stages, in order:
+ * store and the in-memory lanes. It runs four independent stages, in order:
  *
  *   1. **Section re-embed** — diff the page index by `modifiedAt` against the
  *      last successful pass (the high-water mark below), and for every page that
@@ -22,7 +22,12 @@
  *      (it only names live pages), so without this its section points would
  *      linger in Qdrant and the dense lane could still surface the deleted page.
  *      Synthetic capability rows are in the page index, so they are never pruned.
- *   3. **Lane invalidation** — `invalidateLanes()` so the next turn rebuilds the
+ *   3. **Core-set validation** — load the maintainer-curated core set
+ *      (`memory/core-pages.md`) and report entries whose page no longer exists
+ *      in the page index (dangling slugs) via the log + outcome. The file is
+ *      maintainer-owned, so this stage NEVER edits it — the maintainer fixes
+ *      dangling entries at the next consolidation pass.
+ *   4. **Lane invalidation** — `invalidateLanes()` so the next turn rebuilds the
  *      in-memory section index, needle, and edge graph from the freshly-updated
  *      pages.
  *
@@ -35,8 +40,8 @@
  *
  * Dependency-injectable: `deps` lets tests substitute the page-index reader,
  * section builder, dense-store ops (including the prune-stage
- * `listSectionArticles`/`listIndexedSlugs` collaborators), and `invalidateLanes`
- * without process-global module mocks.
+ * `listSectionArticles`/`listIndexedSlugs` collaborators), the core-set loader,
+ * and `invalidateLanes` without process-global module mocks.
  */
 
 import { isAssistantFeatureFlagEnabled } from "../../../config/assistant-feature-flags.js";
@@ -50,7 +55,8 @@ import { getPageIndex } from "../../../memory/v2/page-index.js";
 import { readPage } from "../../../memory/v2/page-store.js";
 import { getLogger } from "../../../util/logger.js";
 import { getWorkspaceDir } from "../../../util/platform.js";
-import { capabilityOrDiskBody } from "./capabilities.js";
+import { capabilityOrDiskBody, isCapabilitySlug } from "./capabilities.js";
+import { loadCoreSet as realLoadCoreSet } from "./core-set.js";
 import {
   deleteSectionsForArticle as realDeleteSectionsForArticle,
   ensureSectionCollection as realEnsureSectionCollection,
@@ -126,6 +132,12 @@ export interface MaintainJobDeps {
    * from this set. Includes synthetic capability rows so they are never pruned.
    */
   listIndexedSlugs: () => Promise<Slug[]>;
+  /**
+   * The maintainer-curated core set from `memory/core-pages.md`. The validation
+   * stage diffs it against the live page-index slugs and REPORTS dangling
+   * entries only — the file is maintainer-owned and is never edited here.
+   */
+  loadCoreSet: () => Slug[];
   /** Drop the memoized v3 lanes so the next turn rebuilds them. */
   invalidateLanes: () => void;
   /** Active assistant config (for the dense-store/embedding calls). */
@@ -140,7 +152,12 @@ export interface MaintainJobDeps {
  * collection-ensure step rather than the change-delta machinery.
  */
 export interface BackfillJobDeps {
-  /** All page-index slugs, including synthetic skill/CLI capability rows. */
+  /**
+   * All page-index slugs, including synthetic skill/CLI capability rows.
+   * Called once at the start and once after the main loop — the second call
+   * catches capability rows whose startup seed had not yet listed them in the
+   * index when the first snapshot was taken.
+   */
   selectAllPages: () => Promise<Slug[]>;
   /** Create the section collection if absent before the first upsert. */
   ensureSectionCollection: typeof realEnsureSectionCollection;
@@ -188,6 +205,12 @@ export interface MaintainOutcome {
   pruned: number;
   /** Prune deletes that threw (and were contained). */
   pruneFailures: number;
+  /**
+   * Core-set entries (`memory/core-pages.md`) whose page no longer exists in
+   * the page index. Reported for the maintainer to fix at the next
+   * consolidation pass — the file itself is never mutated.
+   */
+  danglingCoreSlugs: Slug[];
   /** Whether the in-memory lanes were invalidated. */
   invalidated: boolean;
   /** Stages that threw (and were contained). */
@@ -284,6 +307,7 @@ function defaultDeps(config: AssistantConfig): MaintainJobDeps {
     commitEmbedHighWater,
     listSectionArticles: () => realListSectionArticles(config),
     listIndexedSlugs: () => selectAllPagesFromWorkspace(workspaceDir),
+    loadCoreSet: () => realLoadCoreSet(workspaceDir),
     invalidateLanes: realInvalidateLanes,
     config,
   };
@@ -393,6 +417,22 @@ async function pruneDeletedPages(
  * checkpoint is held (not advanced): a failed page was delete-then-upsert'd and
  * so has no sections, and advancing past its mtime would hide it from the
  * incremental selector forever — holding the mark lets the next pass re-embed it.
+ *
+ * Capability rows get an extra guard. Their stores (skill/CLI caches) are
+ * seeded fire-and-forget at daemon startup, so a backfill fired shortly after a
+ * restart can race the seed in two ways: (a) the rows are missing from the page
+ * index entirely when `selectAllPages` snapshots it, so they are silently
+ * absent from the work list; (b) the rows are listed but their content cache is
+ * still cold, so they render `""` — and the section chunker synthesizes a junk
+ * one-line head section from the bare slug, which would be embedded as if it
+ * were real content. Both end with capabilities effectively missing from the
+ * dense lane while the pass reports zero failures. So: a capability row whose
+ * body resolves empty is skipped without deleting its existing points (never
+ * replace good points with a blank), the page index is re-enumerated after the
+ * main loop (which spans long enough for the startup seed to finish) to pick up
+ * late-appearing capability rows, cold rows are retried, and any capability row
+ * that still resolves empty counts as a failure — holding the checkpoint and
+ * surfacing in the outcome instead of silently succeeding.
  */
 export async function backfillAllSections(
   config: AssistantConfig,
@@ -407,29 +447,65 @@ export async function backfillAllSections(
   let articles = 0;
   let sections = 0;
   let failures = 0;
-  for (const slug of slugs) {
+
+  // "cold" is only reported for capability rows whose body resolves empty —
+  // their store has not seeded yet. Real pages never report cold: an empty
+  // on-disk body legitimately replaces the page's sections.
+  const embedOne = async (
+    slug: Slug,
+  ): Promise<"embedded" | "cold" | "failed"> => {
     try {
+      if (isCapabilitySlug(slug)) {
+        const body = await deps.readPageBody(slug);
+        if (body.trim().length === 0) return "cold";
+      }
       const index = await deps.buildSectionIndex([slug], deps.readPageBody);
       await deps.deleteSectionsForArticle(deps.config, slug);
       await deps.upsertSections(deps.config, index.sections);
       articles += 1;
       sections += index.sections.length;
+      return "embedded";
     } catch (err) {
       failures += 1;
       log.warn(
         { slug, err: err instanceof Error ? err.message : String(err) },
         "memory-v3 backfill: page embed failed (non-fatal)",
       );
+      return "failed";
+    }
+  };
+
+  const coldCapabilities: Slug[] = [];
+  for (const slug of slugs) {
+    if ((await embedOne(slug)) === "cold") coldCapabilities.push(slug);
+  }
+
+  // Late-capability sweep + cold retry. The main loop spans minutes on a real
+  // corpus, so the startup-seeded capability stores have typically warmed by
+  // now: re-enumerate the index to catch capability rows that were not listed
+  // yet at snapshot time, and retry the ones that rendered cold. A row that
+  // still resolves empty is a real failure.
+  const processed = new Set(slugs);
+  const lateCapabilities = (await deps.selectAllPages()).filter(
+    (slug) => isCapabilitySlug(slug) && !processed.has(slug),
+  );
+  for (const slug of [...coldCapabilities, ...lateCapabilities]) {
+    if ((await embedOne(slug)) === "cold") {
+      failures += 1;
+      log.warn(
+        { slug },
+        "memory-v3 backfill: capability row still empty after retry (capability store not seeded?) — re-run backfill-sections once the store seeds",
+      );
     }
   }
 
   // Advance the maintain high-water mark only when every page embedded cleanly,
   // so the next incremental pass deltas from here rather than re-embedding
-  // everything. A failed page was delete-then-upsert'd, so it now has no
-  // sections; advancing past its mtime would hide it from `computeChangedPages`
-  // forever. Holding the checkpoint keeps failed pages above the mark so the
-  // next pass re-embeds them — re-embedding the succeeded pages too is
-  // idempotent and cheap.
+  // everything. A thrown failure was delete-then-upsert'd (it now has no
+  // sections) and an empty capability row was never embedded at all; advancing
+  // past them would hide them from `computeChangedPages` forever. Holding the
+  // checkpoint keeps failed pages above the mark so the next pass re-embeds
+  // them — re-embedding the succeeded pages too is idempotent and cheap.
   if (failures === 0) {
     deps.commitEmbedHighWater(startedAtMs);
   } else {
@@ -463,6 +539,7 @@ export async function maintainJob(
     reembedFailures: 0,
     pruned: 0,
     pruneFailures: 0,
+    danglingCoreSlugs: [],
     invalidated: false,
     failures: [],
   };
@@ -527,7 +604,35 @@ export async function maintainJob(
     );
   }
 
-  // Stage 3: rebuild section index + needle + edge graph on the next turn.
+  // Stage 3: validate the maintainer-curated core set. Diff `core-pages.md`
+  // entries against the live page-index slugs and REPORT dangling entries
+  // (pages that were renamed or deleted) through the log + outcome — the file
+  // is maintainer-owned, so it is never auto-edited; the maintainer fixes it at
+  // the next consolidation pass. No hot/core recompute is needed in this job:
+  // the lanes (including the core and hot prefixes) are computed at lane init,
+  // and the invalidateLanes() stage below already forces a next-turn rebuild —
+  // that rebuild IS the consolidation-cadence refresh.
+  try {
+    const coreSlugs = deps.loadCoreSet();
+    if (coreSlugs.length > 0) {
+      const live = new Set(await deps.listIndexedSlugs());
+      outcome.danglingCoreSlugs = coreSlugs.filter((slug) => !live.has(slug));
+      if (outcome.danglingCoreSlugs.length > 0) {
+        log.warn(
+          { dangling: outcome.danglingCoreSlugs },
+          "memory-v3 maintain: core-pages.md lists pages missing from the index — review the file at the next consolidation",
+        );
+      }
+    }
+  } catch (err) {
+    outcome.failures.push("core-validate");
+    log.warn(
+      { err: err instanceof Error ? err.message : String(err) },
+      "memory-v3 maintain: core-set validation failed (non-fatal)",
+    );
+  }
+
+  // Stage 4: rebuild section index + needle + edge graph on the next turn.
   try {
     deps.invalidateLanes();
     outcome.invalidated = true;
@@ -545,6 +650,7 @@ export async function maintainJob(
       reembedFailures: outcome.reembedFailures,
       pruned: outcome.pruned,
       pruneFailures: outcome.pruneFailures,
+      danglingCoreSlugs: outcome.danglingCoreSlugs,
       invalidated: outcome.invalidated,
       failures: outcome.failures,
     },