@vellumai/assistant 0.9.0 → 0.10.0-staging.2

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

@@ -41,9 +41,9 @@
  *    block id only); it is never persisted to metadata, so the frozen card
  *    prefix it follows stays byte-stable and cached regardless.
  *
- * 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.
+ * Gating: `memory.v3.live` (config) attaches blocks; the `memory-v3-shadow`
+ * flag (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
@@ -62,6 +62,7 @@
 
 import { isAssistantFeatureFlagEnabled } from "../../../config/assistant-feature-flags.js";
 import { getConfig } from "../../../config/loader.js";
+import { isMemoryV3Live } from "../../../config/memory-v3-gate.js";
 import { isPersonalMemoryAllowed } from "../../../daemon/trust-context.js";
 import {
   wrapMemoryBlock,
@@ -85,11 +86,7 @@ import {
   renderSpotlightInner,
   type SpotlightEntry,
 } from "./render-injection.js";
-import {
-  MEMORY_V3_LIVE,
-  MEMORY_V3_SHADOW,
-  observeTurn,
-} from "./shadow-plugin.js";
+import { MEMORY_V3_SHADOW, observeTurn } from "./shadow-plugin.js";
 import {
   MEMORY_V3_BLOCK_ID,
   MEMORY_V3_COMMIT_META_KEY,
@@ -239,7 +236,7 @@ export const memoryV3Injector: Injector = {
   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 live = isMemoryV3Live(config);
     const shadow = isAssistantFeatureFlagEnabled(MEMORY_V3_SHADOW, config);
     if (!live && !shadow) return null;
     if (!isPersonalMemoryAllowed(ctx.trust)) return null;
@@ -378,7 +375,7 @@ export const memoryV3SpotlightInjector: Injector = {
     // 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 (!isMemoryV3Live(config)) return null;
     if (!isPersonalMemoryAllowed(ctx.trust)) return null;
 
     try {

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 four independent stages, in order:
+ * store and the in-memory lanes. It runs five 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
@@ -15,19 +15,26 @@
  *      captured before any potential mtime bumps) so a page is not re-embedded
  *      forever, yet a page whose embed failed (and whose sections were therefore
  *      left deleted) stays above the mark and is retried next pass.
- *   2. **Deleted-page prune** — diff the dense store's stored articles
+ *   2. **Capability reconcile** — embed capability rows (synthetic skill/CLI
+ *      slugs) present in the page index but missing from the section store. The
+ *      re-embed delta above EXCLUDES capability rows (they have `modifiedAt` 0,
+ *      no mtime to diff), so the only other embedder is the one-time
+ *      `backfillAllSections`. Without this stage a skill enabled AFTER that
+ *      backfill (e.g. a flag-gated skill flipped on at runtime) lands in the
+ *      index but never reaches the dense lane. See {@link reconcileCapabilityRows}.
+ *   3. **Deleted-page prune** — diff the dense store's stored articles
  *      (`listSectionArticles`) against the live page-index slugs and
  *      `deleteSectionsForArticle` for any article that is no longer in the
  *      index. A deleted page's slug never reaches the re-embed delta selector
  *      (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. **Core-set validation** — load the maintainer-curated core set
+ *   4. **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
+ *   5. **Lane invalidation** — `invalidateLanes()` so the next turn rebuilds the
  *      in-memory section index, needle, and edge graph from the freshly-updated
  *      pages.
  *
@@ -35,8 +42,8 @@
  * logged and recorded in the outcome but does NOT abort the others. A single
  * page whose embed fails does not abort the rest of the re-embed stage, and a
  * single prune delete that throws does not abort the rest of the prune stage.
- * The job is a no-op (returns a disabled outcome) unless `memory-v3-shadow` OR
- * `memory-v3-live` is enabled — the same flags that gate the v3 plugin.
+ * The job is a no-op (returns a disabled outcome) unless the `memory-v3-shadow`
+ * flag OR `memory.v3.live` (config) is enabled — the same gates as the v3 plugin.
  *
  * Dependency-injectable: `deps` lets tests substitute the page-index reader,
  * section builder, dense-store ops (including the prune-stage
@@ -45,11 +52,17 @@
  */
 
 import { isAssistantFeatureFlagEnabled } from "../../../config/assistant-feature-flags.js";
+import { isMemoryV3Live } from "../../../config/memory-v3-gate.js";
 import type { AssistantConfig } from "../../../config/types.js";
 import {
   getMemoryCheckpoint,
   setMemoryCheckpoint,
 } from "../../../memory/checkpoints.js";
+import {
+  EmbeddingBackendUnavailableError,
+  embedWithBackend,
+} from "../../../memory/embedding-backend.js";
+import { EmbeddingBillingBlockError } from "../../../memory/embedding-billing-breaker.js";
 import type { MemoryJob } from "../../../memory/jobs-store.js";
 import { getPageIndex } from "../../../memory/v2/page-index.js";
 import { readPage } from "../../../memory/v2/page-store.js";
@@ -68,7 +81,6 @@ import { invalidateLanes as realInvalidateLanes } from "./shadow-plugin.js";
 import type { Slug } from "./types.js";
 
 const MEMORY_V3_SHADOW = "memory-v3-shadow" as const;
-const MEMORY_V3_LIVE = "memory-v3-live" as const;
 
 /**
  * Durable checkpoint holding the epoch-ms high-water mark of the last successful
@@ -110,6 +122,13 @@ export interface MaintainJobDeps {
   buildSectionIndex: typeof realBuildSectionIndex;
   /** Read a page's frontmatter-stripped body for `buildSectionIndex`. */
   readPageBody: (slug: Slug) => Promise<string>;
+  /**
+   * Capability-aware body reader for the reconcile stage: synthetic skill/CLI
+   * slugs resolve their rendered capability content; real pages read from disk.
+   * The re-embed stage uses `readPageBody` (disk-only) since it only processes
+   * real pages — the reconcile stage needs capability bodies.
+   */
+  readCapabilityBody: (slug: Slug) => Promise<string>;
   /** Clear an article's stale section points before re-upserting. */
   deleteSectionsForArticle: typeof realDeleteSectionsForArticle;
   /** Embed + upsert an article's current sections into the dense store. */
@@ -178,6 +197,13 @@ export interface BackfillJobDeps {
   nowMs: () => number;
   /** Active assistant config (for the dense-store/embedding calls). */
   config: AssistantConfig;
+  /**
+   * Smoke-test the embedding backend before any destructive write. Throws when
+   * the backend is unavailable, so the backfill aborts BEFORE deleting any
+   * article's points (each article is processed delete-then-upsert). Injectable
+   * for tests.
+   */
+  embedProbe: () => Promise<void>;
 }
 
 /** Counts surfaced by {@link backfillAllSections}. */
@@ -198,6 +224,15 @@ export interface MaintainOutcome {
   reembedded: number;
   /** Pages whose re-embed threw (and was contained). */
   reembedFailures: number;
+  /**
+   * Capability rows (skills/CLI) present in the index but missing from the
+   * section store that were embedded this pass — how a skill enabled after the
+   * one-time backfill reaches the dense lane (the re-embed delta excludes
+   * capability rows).
+   */
+  capabilitiesReconciled: number;
+  /** Capability reconcile embeds that threw (and were contained). */
+  reconcileFailures: number;
   /**
    * Deleted-page articles whose lingering section points were pruned this pass
    * (present in the dense store but absent from the page index).
@@ -302,6 +337,8 @@ function defaultDeps(config: AssistantConfig): MaintainJobDeps {
     selectChangedPages: () => selectChangedPagesFromWorkspace(workspaceDir),
     buildSectionIndex: realBuildSectionIndex,
     readPageBody: (slug) => readPageBodyFromWorkspace(workspaceDir, slug),
+    readCapabilityBody: (slug) =>
+      backfillPageBodyFromWorkspace(workspaceDir, slug),
     deleteSectionsForArticle: realDeleteSectionsForArticle,
     upsertSections: realUpsertSections,
     commitEmbedHighWater,
@@ -325,6 +362,9 @@ function defaultBackfillDeps(config: AssistantConfig): BackfillJobDeps {
     commitEmbedHighWater,
     nowMs: () => Date.now(),
     config,
+    embedProbe: async () => {
+      await embedWithBackend(config, ["memory-v3 backfill preflight"]);
+    },
   };
 }
 
@@ -357,6 +397,58 @@ async function reembedChangedPages(
   return { reembedded, reembedFailures };
 }
 
+/**
+ * Embed capability rows (synthetic skill/CLI slugs) present in the page index
+ * but missing from the section dense store. The incremental re-embed selector
+ * ({@link computeChangedPages}) excludes capability rows — they have no on-disk
+ * mtime to delta against — so the ONLY other embedder is the one-time
+ * {@link backfillAllSections}. Without this, a skill enabled AFTER that backfill
+ * (e.g. a flag-gated skill flipped on at runtime) lands in the page index but
+ * never reaches the dense lane. This stage makes the periodic maintain pass
+ * self-heal: diff the live capability slugs against the stored section articles
+ * and embed the missing ones.
+ *
+ * Each row is independent: a single build/upsert throw is logged and counted in
+ * `reconcileFailures` without aborting the rest. A capability row whose body
+ * resolves empty (its store has not seeded yet) is skipped WITHOUT deleting any
+ * points — never replace good points with a blank — and is retried next pass.
+ */
+async function reconcileCapabilityRows(
+  deps: MaintainJobDeps,
+): Promise<{ capabilitiesReconciled: number; reconcileFailures: number }> {
+  const [indexedSlugs, storedArticles] = await Promise.all([
+    deps.listIndexedSlugs(),
+    deps.listSectionArticles(),
+  ]);
+  const stored = new Set(storedArticles);
+  const missing = indexedSlugs.filter(
+    (slug) => isCapabilitySlug(slug) && !stored.has(slug),
+  );
+
+  let capabilitiesReconciled = 0;
+  let reconcileFailures = 0;
+  for (const slug of missing) {
+    try {
+      const body = await deps.readCapabilityBody(slug);
+      if (body.trim().length === 0) continue; // store cold — retry next pass
+      const index = await deps.buildSectionIndex(
+        [slug],
+        deps.readCapabilityBody,
+      );
+      await deps.deleteSectionsForArticle(deps.config, slug);
+      await deps.upsertSections(deps.config, index.sections);
+      capabilitiesReconciled += 1;
+    } catch (err) {
+      reconcileFailures += 1;
+      log.warn(
+        { slug, err: err instanceof Error ? err.message : String(err) },
+        "memory-v3 maintain: capability reconcile embed failed (non-fatal)",
+      );
+    }
+  }
+  return { capabilitiesReconciled, reconcileFailures };
+}
+
 /**
  * Prune section points for articles that no longer exist in the page index. A
  * deleted concept page leaves `getPageIndex` (so the needle and edge lanes both
@@ -444,6 +536,13 @@ export async function backfillAllSections(
   const slugs = await deps.selectAllPages();
   await deps.ensureSectionCollection(deps.config);
 
+  // Pre-flight: smoke-test the embedding backend BEFORE any delete. Each article
+  // is processed delete-then-upsert, so starting a full backfill against a down
+  // backend would delete every article's points and re-embed none of them. A
+  // throw here aborts with nothing deleted; the high-water mark stays put, so a
+  // later run retries once the backend is healthy.
+  await deps.embedProbe();
+
   let articles = 0;
   let sections = 0;
   let failures = 0;
@@ -466,6 +565,17 @@ export async function backfillAllSections(
       sections += index.sections.length;
       return "embedded";
     } catch (err) {
+      // A down embedding backend (unconfigured, or billing breaker open) fails
+      // EVERY article — the condition is process-wide — and each article is
+      // delete-then-upsert, so continuing would delete the rest of the corpus
+      // and re-embed none of it. Abort the run; the high-water mark is never
+      // advanced, so the next pass retries from here once the backend recovers.
+      if (
+        err instanceof EmbeddingBackendUnavailableError ||
+        err instanceof EmbeddingBillingBlockError
+      ) {
+        throw err;
+      }
       failures += 1;
       log.warn(
         { slug, err: err instanceof Error ? err.message : String(err) },
@@ -537,6 +647,8 @@ export async function maintainJob(
     disabled: false,
     reembedded: 0,
     reembedFailures: 0,
+    capabilitiesReconciled: 0,
+    reconcileFailures: 0,
     pruned: 0,
     pruneFailures: 0,
     danglingCoreSlugs: [],
@@ -546,7 +658,7 @@ export async function maintainJob(
 
   const enabled =
     isAssistantFeatureFlagEnabled(MEMORY_V3_SHADOW, config) ||
-    isAssistantFeatureFlagEnabled(MEMORY_V3_LIVE, config);
+    isMemoryV3Live(config);
   if (!enabled) {
     outcome.disabled = true;
     return outcome;
@@ -587,7 +699,26 @@ export async function maintainJob(
     );
   }
 
-  // Stage 2: prune section points for pages deleted from the index. A deleted
+  // Stage 2: embed capability rows (skills/CLI) present in the index but missing
+  // from the section store. They have modifiedAt 0, so computeChangedPages never
+  // selects them; the one-time backfill is otherwise their only embedder, so a
+  // skill enabled after that backfill stays invisible to the dense lane until
+  // this self-heals it. Contained: a failure is logged + recorded without
+  // aborting later stages.
+  try {
+    const { capabilitiesReconciled, reconcileFailures } =
+      await reconcileCapabilityRows(deps);
+    outcome.capabilitiesReconciled = capabilitiesReconciled;
+    outcome.reconcileFailures = reconcileFailures;
+  } catch (err) {
+    outcome.failures.push("capability-reconcile");
+    log.warn(
+      { err: err instanceof Error ? err.message : String(err) },
+      "memory-v3 maintain: capability reconcile failed (non-fatal)",
+    );
+  }
+
+  // Stage 3: prune section points for pages deleted from the index. A deleted
   // page's slug never appears in `selectChangedPages` (the delta selector only
   // names live pages), so its lingering points are cleared by diffing the dense
   // store's stored articles against the live page-index slugs. Contained: a
@@ -604,7 +735,7 @@ export async function maintainJob(
     );
   }
 
-  // Stage 3: validate the maintainer-curated core set. Diff `core-pages.md`
+  // Stage 4: 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
@@ -632,7 +763,7 @@ export async function maintainJob(
     );
   }
 
-  // Stage 4: rebuild section index + needle + edge graph on the next turn.
+  // Stage 5: rebuild section index + needle + edge graph on the next turn.
   try {
     deps.invalidateLanes();
     outcome.invalidated = true;
@@ -648,6 +779,8 @@ export async function maintainJob(
     {
       reembedded: outcome.reembedded,
       reembedFailures: outcome.reembedFailures,
+      capabilitiesReconciled: outcome.capabilitiesReconciled,
+      reconcileFailures: outcome.reconcileFailures,
       pruned: outcome.pruned,
       pruneFailures: outcome.pruneFailures,
       danglingCoreSlugs: outcome.danglingCoreSlugs,

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

@@ -18,9 +18,10 @@
  *      Each lane only ever ADDS candidates, so the pool is recall-safe by
  *      construction.
  *   2. Build the candidate pool in CACHE ORDER: the stable prefix —
- *      `[...core (file order), ...hot (score order), ...fresh (recency
- *      order)]`, all computed at lane init — followed by the finder
- *      candidates (needle → dense → edge surfacing order). The stable prefix
+ *      `[...core (file order), ...hot (score order), ...fresh (recency order),
+ *      ...always-candidate (skills pinned every turn)]`, all computed at lane
+ *      init — followed by the finder candidates (needle → dense → edge
+ *      surfacing order). The stable prefix
  *      is identical across consecutive turns while the lanes are unchanged
  *      (lane invalidation at consolidation is the recompute cadence), so the
  *      selector input's leading segment rides the provider KV cache (the
@@ -82,6 +83,10 @@ export interface OrchestrateDeps {
   /** The modification-recency fresh set in recency order (computed at lane
    *  init with core and hot excluded). Follows hot in the stable prefix. */
   freshSlugs: Slug[];
+  /** Skills pinned into the candidate pool every turn regardless of retrieval
+   *  (existence-filtered and core/hot/fresh-excluded at lane init). Follow fresh
+   *  in the stable prefix so the selector always sees them. */
+  alwaysCandidateSlugs?: Slug[];
   /** Pre-rendered FULL cards for the stable-prefix slugs, keyed by slug.
    *  Rendered ONCE at lane init so the selector's stable prefix is
    *  byte-identical across turns (the cache contract). Every core/hot/fresh
@@ -172,14 +177,19 @@ export async function orchestrate(
   const { sections } = deps.sectionIndex;
 
   // The stable prefix: core (file order), hot (score order), fresh (recency
-  // order). Hot is computed with core excluded at lane init, fresh with both
-  // excluded; the filters here are a cheap defensive dedup so a misbehaving
-  // lane can never double-list a slug.
+  // order), then always-candidate skills. Hot is computed with core excluded at
+  // lane init, fresh with both excluded, always-candidate with all three
+  // excluded; the filters here are a cheap defensive dedup so a misbehaving lane
+  // can never double-list a slug.
   const core = deps.coreSlugs;
   const hot = deps.hotSlugs.filter((slug) => !core.includes(slug));
   const coreHot = new Set<Slug>([...core, ...hot]);
   const fresh = deps.freshSlugs.filter((slug) => !coreHot.has(slug));
-  const stablePrefix = new Set<Slug>([...coreHot, ...fresh]);
+  const coreHotFresh = new Set<Slug>([...coreHot, ...fresh]);
+  const always = (deps.alwaysCandidateSlugs ?? []).filter(
+    (slug) => !coreHotFresh.has(slug),
+  );
+  const stablePrefix = new Set<Slug>([...coreHotFresh, ...always]);
 
   // Step 1: needle (sync BM25) and dense (async embed + Qdrant) lanes run in
   // parallel. Both return distinct articles each tagged with their best-scoring
@@ -342,19 +352,21 @@ export async function orchestrate(
   // its own snippet line so its CURRENT relevance stays visible; `selectPool`
   // dedupes selections by slug. Finder candidates with no match text fall
   // back to the page's lead-section snippet.
-  const stable: StableCandidate[] = [...core, ...hot, ...fresh].map((slug) => {
-    const card = deps.prefixCards.get(slug);
-    if (card === undefined) {
-      // Lane init renders a card for every core/hot slug; a hole here means
-      // the lanes and the card map are out of sync. Throw rather than render
-      // a degraded card — the caller (observeTurn) logs and skips the turn,
-      // which is better than silently breaking the byte-stable prefix.
-      throw new Error(
-        `memory-v3: no pre-rendered card for stable-prefix slug "${slug}"`,
-      );
-    }
-    return { slug, card };
-  });
+  const stable: StableCandidate[] = [...core, ...hot, ...fresh, ...always].map(
+    (slug) => {
+      const card = deps.prefixCards.get(slug);
+      if (card === undefined) {
+        // Lane init renders a card for every core/hot slug; a hole here means
+        // the lanes and the card map are out of sync. Throw rather than render
+        // a degraded card — the caller (observeTurn) logs and skips the turn,
+        // which is better than silently breaking the byte-stable prefix.
+        throw new Error(
+          `memory-v3: no pre-rendered card for stable-prefix slug "${slug}"`,
+        );
+      }
+      return { slug, card };
+    },
+  );
   const finderTail: PoolCandidate[] = finder.map((c) => ({
     slug: c.slug,
     lane: c.lane,

package/src/plugins/defaults/memory-v3-shadow/selection-log-store.ts

@@ -19,6 +19,7 @@
 import type { MemoryV3SelectionLog } from "../../../api/responses/memory-v3-selection-log.js";
 import { isAssistantFeatureFlagEnabled } from "../../../config/assistant-feature-flags.js";
 import { getConfig } from "../../../config/loader.js";
+import { isMemoryV3Live } from "../../../config/memory-v3-gate.js";
 import { getDb, getSqliteFrom } from "../../../memory/db-connection.js";
 import { readPage } from "../../../memory/v2/page-store.js";
 import { getWorkspaceDir } from "../../../util/platform.js";
@@ -35,7 +36,6 @@ import {
 } from "./types.js";
 
 const MEMORY_V3_SHADOW = "memory-v3-shadow" as const;
-const MEMORY_V3_LIVE = "memory-v3-live" as const;
 
 interface SelectionRow {
   turn: number;
@@ -74,6 +74,52 @@ function rowsForMessageIds(messageIds: string[]): SelectionRow[] {
     .all(...messageIds) as SelectionRow[];
 }
 
+const MAX_FORK_HOPS = 64;
+
+/**
+ * Read the `forkSourceMessageId` back-pointer that `cloneForkMessageMetadata`
+ * stamps onto every message a fork copies, for the given message ids.
+ */
+function forkSourceIdsOf(messageIds: string[]): string[] {
+  if (messageIds.length === 0) return [];
+  const placeholders = messageIds.map(() => "?").join(", ");
+  const rows = getSqliteFrom(getDb())
+    .query(
+      /*sql*/ `
+      SELECT json_extract(metadata, '$.forkSourceMessageId') AS src
+      FROM messages
+      WHERE id IN (${placeholders})
+    `,
+    )
+    .all(...messageIds) as Array<{ src: string | null }>;
+  return rows
+    .map((r) => r.src)
+    .filter((src): src is string => typeof src === "string" && src.length > 0);
+}
+
+/**
+ * A fork copies the parent's messages under fresh ids but does not copy their
+ * `memory_v3_selections` rows, so an inherited turn has no rows under its own
+ * message ids. Each copied message preserves a `forkSourceMessageId` pointer to
+ * the message it was cloned from; walk that chain (a fork of a fork chains it
+ * again) to the nearest ancestor generation that logged selections and return
+ * those rows. Returns `[]` when no ancestor has v3 rows (or the ids aren't fork
+ * copies).
+ */
+function rowsViaForkSource(messageIds: string[]): SelectionRow[] {
+  let frontier = messageIds;
+  const visited = new Set(messageIds);
+  for (let hop = 0; hop < MAX_FORK_HOPS; hop++) {
+    const sources = forkSourceIdsOf(frontier).filter((id) => !visited.has(id));
+    if (sources.length === 0) return [];
+    for (const id of sources) visited.add(id);
+    const rows = rowsForMessageIds(sources);
+    if (rows.length > 0) return rows;
+    frontier = sources;
+  }
+  return [];
+}
+
 /**
  * Resolve each selection's persisted matched section `(slug, ordinal)` to the
  * concrete `Section` in the CURRENT page, so the injected block renders the
@@ -133,7 +179,7 @@ async function buildSelectionLog(
 
   return {
     turn: rows[0]!.turn,
-    live: isAssistantFeatureFlagEnabled(MEMORY_V3_LIVE, config),
+    live: isMemoryV3Live(config),
     shadow: isAssistantFeatureFlagEnabled(MEMORY_V3_SHADOW, config),
     selections,
     injectedText,
@@ -150,13 +196,20 @@ async function buildSelectionLog(
  * conversation with no v3 data). Message ids are globally unique, so no
  * conversation scope is needed.
  *
+ * For turns inherited from a fork, the copied messages carry fresh ids with no
+ * selection rows of their own, so the lookup falls back to the parent's rows by
+ * following each message's `forkSourceMessageId` back-pointer.
+ *
  * Selection rows are stored in selection order, so rendering them in row order
  * reproduces the block v3 would inject.
  */
 export async function getMemoryV3SelectionForInspectorByMessageIds(
   messageIds: string[],
 ): Promise<MemoryV3SelectionLog | null> {
-  return buildSelectionLog(rowsForMessageIds(messageIds));
+  const rows = rowsForMessageIds(messageIds);
+  return buildSelectionLog(
+    rows.length > 0 ? rows : rowsViaForkSource(messageIds),
+  );
 }
 
 /**

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

@@ -34,6 +34,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { isAssistantFeatureFlagEnabled } from "../../../config/assistant-feature-flags.js";
 import { getConfig } from "../../../config/loader.js";
 import type { AssistantConfig } from "../../../config/schema.js";
+import { loadSkillCatalog } from "../../../config/skills.js";
 import { getMessages } from "../../../memory/conversation-crud.js";
 import { getDb, getSqliteFrom } from "../../../memory/db-connection.js";
 import { stringifyMessageContent } from "../../../memory/message-content.js";
@@ -68,7 +69,6 @@ import {
 } from "./types.js";
 
 export const MEMORY_V3_SHADOW = "memory-v3-shadow" as const;
-export const MEMORY_V3_LIVE = "memory-v3-live" as const;
 
 const log = getLogger("memory-v3-shadow");
 
@@ -107,6 +107,9 @@ export interface ShadowLanes {
   /** Modification-recency fresh set in recency order: core and hot excluded,
    *  filtered to pages in the section index. */
   freshSlugs: string[];
+  /** Skills pinned into the stable prefix every turn (`always-candidate: true`
+   *  in SKILL.md), existence-filtered and core/hot/fresh-excluded. */
+  alwaysCandidateSlugs: string[];
   /** Learned-edge graph: co-selection NPMI associations over the selection
    *  log, rebuilt with the lanes (the consolidation cadence). */
   learnedGraph: EdgeGraph;
@@ -216,6 +219,18 @@ async function initLanes(config: AssistantConfig): Promise<ShadowLanes> {
     excludeSlugs: new Set([...coreSlugs, ...hotSlugs]),
   }).filter((slug) => sectionIndex.byArticle.has(slug));
 
+  // Always-candidate skills are pinned into the stable prefix every turn so the
+  // selector can choose a cross-cutting capability (e.g. workflows) even when no
+  // retrieval lane surfaces it — its relevance is a judgment the model makes,
+  // not something embedding similarity finds. Filtered to skills present in the
+  // section index and excluded from core/hot/fresh so the prefix never
+  // double-lists a slug.
+  const prefixSet = new Set([...coreSlugs, ...hotSlugs, ...freshSlugs]);
+  const alwaysCandidateSlugs = loadSkillCatalog()
+    .filter((summary) => summary.alwaysCandidate === true)
+    .map((summary) => `skills/${summary.id}`)
+    .filter((slug) => sectionIndex.byArticle.has(slug) && !prefixSet.has(slug));
+
   // Pre-render the stable-prefix cards ONCE per lane build: the selector's
   // stable prefix must be byte-identical across turns to ride the provider KV
   // cache, so the cards are frozen here (lane invalidation at consolidation is
@@ -228,7 +243,10 @@ async function initLanes(config: AssistantConfig): Promise<ShadowLanes> {
   const modifiedAtBySlug = new Map(
     pageIndex.entries.map((entry) => [entry.slug, entry.modifiedAt]),
   );
-  const laneAnnotation = (slug: Slug, lane: "core" | "hot" | "fresh") => {
+  const laneAnnotation = (
+    slug: Slug,
+    lane: "core" | "hot" | "fresh" | "always",
+  ) => {
     if (lane !== "fresh") return `[lane: ${lane}]`;
     const modifiedAt = modifiedAtBySlug.get(slug);
     if (
@@ -249,6 +267,7 @@ async function initLanes(config: AssistantConfig): Promise<ShadowLanes> {
     ["core", coreSlugs],
     ["hot", hotSlugs],
     ["fresh", freshSlugs],
+    ["always", alwaysCandidateSlugs],
   ] as const) {
     for (const slug of slugs) {
       const raw = await capabilityOrDiskBody(
@@ -303,6 +322,7 @@ async function initLanes(config: AssistantConfig): Promise<ShadowLanes> {
     coreSlugs,
     hotSlugs,
     freshSlugs,
+    alwaysCandidateSlugs,
     prefixCards,
   };
 }
@@ -545,6 +565,7 @@ export async function observeTurn(
       coreSlugs: lanes.coreSlugs,
       hotSlugs: lanes.hotSlugs,
       freshSlugs: lanes.freshSlugs,
+      alwaysCandidateSlugs: lanes.alwaysCandidateSlugs,
       prefixCards: lanes.prefixCards,
       needleK: v3.needleK,
       denseK: v3.denseK,