@vellumai/assistant 0.11.4 → 0.11.5-staging.1

package/src/plugins/defaults/image-fallback/hooks/user-prompt-submit.ts

@@ -17,6 +17,14 @@
  *    {@link captionImagesInMessages} (which also persists the original and
  *    caches captions across turns), sweeping top-level blocks and images
  *    nested in `tool_result` blocks alike.
+ * 4. Posts a transcript system card when an image the user attached to this
+ *    turn reached step 3 with no vision profile configured, since that image
+ *    is information the model never receives in any form.
+ *
+ * The card covers only images attached to the message this turn submitted.
+ * The sweep also walks earlier turns (persisted rows keep their raw images, so
+ * every turn re-encounters them) and tool-returned media, and describing those
+ * again would post a card per turn for images the user already heard about.
  *
  * The companion `post-tool-use` hook applies the same substitution to images a
  * tool returns (e.g. a browser screenshot), and `post-compact` re-sweeps the
@@ -25,6 +33,7 @@
 
 import {
   type HookFunction,
+  persistSystemCard,
   type UserPromptSubmitContext,
 } from "@vellumai/plugin-api";
 
@@ -34,6 +43,29 @@ import {
 } from "../src/caption-blocks.js";
 import { findVisionProfile } from "../src/vision-caption.js";
 
+/**
+ * How many images the user attached to the message this turn submitted, read
+ * off the pre-hook history snapshot: its tail is the submitted row as the user
+ * sent it, before any earlier hook's injected blocks (memory context, runtime
+ * context) reach the working history. Counting there keeps the tally to the
+ * user's own attachments and needs no object identity, which injection breaks
+ * by rebuilding the tail message around its added blocks.
+ */
+function submittedImageCount(ctx: UserPromptSubmitContext): number {
+  const submitted = ctx.originalMessages[ctx.originalMessages.length - 1];
+  if (submitted == null || submitted.role !== "user") {
+    return 0;
+  }
+  return submitted.content.filter((block) => block.type === "image").length;
+}
+
+/** Transcript copy for images this turn could not send to the model. */
+function droppedImageCardText(count: number): string {
+  return count === 1
+    ? "The image you attached was not sent to the model: no vision-capable model is configured to describe it. Configure one to use images in this conversation."
+    : `The ${count} images you attached were not sent to the model: no vision-capable model is configured to describe them. Configure one to use images in this conversation.`;
+}
+
 const userPromptSubmit: HookFunction<UserPromptSubmitContext> = async (ctx) => {
   // If the turn's model already supports vision, nothing to do.
   if (!needsImageFallback(ctx.modelProfileKey)) {
@@ -43,6 +75,12 @@ const userPromptSubmit: HookFunction<UserPromptSubmitContext> = async (ctx) => {
   // Find a vision-capable profile for captioning.
   const visionProfileKey = findVisionProfile();
 
+  // Images the user attached to this turn, tallied before the sweep replaces
+  // them: with no vision profile every one of them is dropped, so this is the
+  // count the card reports.
+  const droppedFromSubmission =
+    visionProfileKey == null ? submittedImageCount(ctx) : 0;
+
   // Scan all messages for image blocks and replace them with captions.
   const imageCount = await captionImagesInMessages(
     ctx.latestMessages,
@@ -57,6 +95,26 @@ const userPromptSubmit: HookFunction<UserPromptSubmitContext> = async (ctx) => {
       "Replaced image blocks with text captions for text-only model",
     );
   }
+
+  if (droppedFromSubmission > 0) {
+    try {
+      await persistSystemCard({
+        conversationId: ctx.conversationId,
+        text: droppedImageCardText(droppedFromSubmission),
+        metadata: {
+          plugin: "image-fallback",
+          droppedImageCount: droppedFromSubmission,
+        },
+      });
+    } catch (err) {
+      // The turn proceeds with the placeholder text either way; the notice is
+      // the only thing lost.
+      ctx.logger.warn(
+        { plugin: "image-fallback", err },
+        "Failed to post dropped-image notice",
+      );
+    }
+  }
 };
 
 export default userPromptSubmit;

package/src/plugins/defaults/image-fallback/src/caption-blocks.ts

@@ -11,7 +11,10 @@
  * original image to a known location, caption it via a vision-capable
  * profile, and swap in a `[Image …]` text block — and the message-level deep
  * sweep ({@link captionImagesInMessages}) that reaches images nested inside
- * `tool_result` blocks as well as top-level ones.
+ * `tool_result` blocks as well as top-level ones. The message-level sweeps
+ * close by merging text-only user content into a single text block
+ * ({@link flattenTextOnlyBlocks}), the shape providers serialize as a plain
+ * string.
  *
  * The substitution mutates the blocks in place, but the hook pipeline hands
  * each hook a deep clone of its context, so the caption reaches only the
@@ -62,8 +65,7 @@ export function needsImageFallback(modelProfileKey: string): boolean {
 
 /**
  * Replace every `image` block in `blocks` (in place) with a text caption so a
- * text-only model can still reason about the image's content. Returns the
- * number of image blocks replaced.
+ * text-only model can still reason about the image's content.
  *
  * @param blocks            Content-block array to scan and mutate in place.
  * @param conversationId    Conversation the blocks belong to, recorded on the
@@ -80,7 +82,7 @@ export async function captionImageBlocks(
   visionProfileKey: string | null,
   logger: PluginLogger,
 ): Promise<number> {
-  let imageCount = 0;
+  let replaced = 0;
 
   for (let i = 0; i < blocks.length; i++) {
     const block = blocks[i];
@@ -88,7 +90,7 @@ export async function captionImageBlocks(
       continue;
     }
 
-    imageCount++;
+    replaced++;
     const image = block as ImageContent;
 
     // Persist the original to a known, content-hash-deduped location so it
@@ -114,7 +116,7 @@ export async function captionImageBlocks(
             : `[Image: auto-description failed (text-only model)]`,
       };
     } else {
-      // No vision profile configured at all — fail-open placeholder.
+      // No vision profile configured at all: fail-open placeholder.
       blocks[i] = {
         type: "text",
         text: `[Image: no vision-capable model configured to describe it]`,
@@ -122,12 +124,12 @@ export async function captionImageBlocks(
     }
   }
 
-  return imageCount;
+  return replaced;
 }
 
 /**
  * Replace image blocks nested in a message's `tool_result` blocks' rich
- * `contentBlocks` (in place) with text captions. Returns the number replaced.
+ * `contentBlocks` (in place) with text captions.
  */
 async function captionToolResultMedia(
   message: Message,
@@ -135,10 +137,10 @@ async function captionToolResultMedia(
   visionProfileKey: string | null,
   logger: PluginLogger,
 ): Promise<number> {
-  let imageCount = 0;
+  let replaced = 0;
   for (const block of message.content) {
     if (block.type === "tool_result" && block.contentBlocks != null) {
-      imageCount += await captionImageBlocks(
+      replaced += await captionImageBlocks(
         block.contentBlocks,
         conversationId,
         visionProfileKey,
@@ -146,7 +148,42 @@ async function captionToolResultMedia(
       );
     }
   }
-  return imageCount;
+  return replaced;
+}
+
+/**
+ * Merge a user message's text blocks (in place) into a single text block,
+ * joined by a blank line, for every message whose content is more than one
+ * block and entirely text. Returns how many messages were merged.
+ *
+ * A text-only turn's user content is text after image substitution, and a
+ * single text block is the shape providers serialize as a plain string:
+ * OpenAI-compatible endpoints that accept only `messages[].content` as a
+ * string (rejecting an array of content parts with
+ * `body/messages/N/content must be string`) can then take the turn, and the
+ * request costs fewer tokens than the equivalent array of parts. The blank
+ * line keeps the boundaries between the blocks a user message carries (the
+ * turn's runtime-injected context blocks plus the user's own text) legible.
+ *
+ * Content holding any non-text block (audio, tool results, an image no
+ * fallback replaced) keeps its array shape, since merging would drop it.
+ */
+export function flattenTextOnlyBlocks(messages: Message[]): number {
+  let flattened = 0;
+  for (const message of messages) {
+    if (message.role !== "user" || message.content.length <= 1) {
+      continue;
+    }
+    if (!message.content.every((block) => block.type === "text")) {
+      continue;
+    }
+    const text = message.content
+      .map((block) => (block.type === "text" ? block.text : ""))
+      .join("\n\n");
+    message.content = [{ type: "text", text }];
+    flattened++;
+  }
+  return flattened;
 }
 
 /**
@@ -154,8 +191,9 @@ async function captionToolResultMedia(
  * a text caption via {@link captionImageBlocks}. Covers both top-level image
  * blocks (user-attached images, the compactor's retained-image message) and
  * images nested in a `tool_result` block's rich `contentBlocks` (tool results
- * restored from persistence carry their raw images there). Returns the number
- * of image blocks replaced.
+ * restored from persistence carry their raw images there).
+ *
+ * Text-only user content is then merged via {@link flattenTextOnlyBlocks}.
  */
 export async function captionImagesInMessages(
   messages: Message[],
@@ -163,22 +201,23 @@ export async function captionImagesInMessages(
   visionProfileKey: string | null,
   logger: PluginLogger,
 ): Promise<number> {
-  let imageCount = 0;
+  let replaced = 0;
   for (const message of messages) {
-    imageCount += await captionImageBlocks(
+    replaced += await captionImageBlocks(
       message.content,
       conversationId,
       visionProfileKey,
       logger,
     );
-    imageCount += await captionToolResultMedia(
+    replaced += await captionToolResultMedia(
       message,
       conversationId,
       visionProfileKey,
       logger,
     );
   }
-  return imageCount;
+  flattenTextOnlyBlocks(messages);
+  return replaced;
 }
 
 /**
@@ -188,8 +227,9 @@ export async function captionImagesInMessages(
  * message ({@link lastToolResultUserMessageIndex}, the one the sanitizer keeps
  * intact). Older tool_result media is left raw so the sanitizer replaces it
  * with its compact removed-media marker on the retry rather than a full
- * caption — captioning it would waste vision calls and balloon context.
- * Returns the number of image blocks replaced.
+ * caption: captioning it would waste vision calls and balloon context.
+ *
+ * Text-only user content is then merged via {@link flattenTextOnlyBlocks}.
  */
 export async function captionOutboundImagesInMessages(
   messages: Message[],
@@ -198,16 +238,16 @@ export async function captionOutboundImagesInMessages(
   logger: PluginLogger,
 ): Promise<number> {
   const currentTurnIdx = lastToolResultUserMessageIndex(messages);
-  let imageCount = 0;
+  let replaced = 0;
   for (let i = 0; i < messages.length; i++) {
-    imageCount += await captionImageBlocks(
+    replaced += await captionImageBlocks(
       messages[i].content,
       conversationId,
       visionProfileKey,
       logger,
     );
     if (i === currentTurnIdx) {
-      imageCount += await captionToolResultMedia(
+      replaced += await captionToolResultMedia(
         messages[i],
         conversationId,
         visionProfileKey,
@@ -215,5 +255,6 @@ export async function captionOutboundImagesInMessages(
       );
     }
   }
-  return imageCount;
+  flattenTextOnlyBlocks(messages);
+  return replaced;
 }

package/src/plugins/defaults/image-recovery/detect.ts

@@ -13,6 +13,14 @@
  * classification matters because retrying with the same image is futile — the
  * recovery path must resize, relabel, or note it instead.
  *
+ * OpenAI-compatible providers reject the same class of input in their own
+ * wording ("The image data you provided does not represent a valid image.
+ * Please check your input and try again with one of the supported image
+ * formats: [image/jpeg, image/png, image/gif, image/webp]"), so the
+ * unsupported-format patterns carry that shape. Without them an OpenAI-family
+ * 400 falls through to the generic provider-error copy and takes the whole
+ * turn down with no hint that an attachment is what broke it.
+ *
  * Exported as the single source of truth: the image-recovery hook reads these
  * to recognize the rejections it can recover, and `daemon/conversation-error`
  * imports them so the user-facing classification stays in lockstep with what
@@ -32,6 +40,11 @@ export const IMAGE_MEDIA_TYPE_MISMATCH_PATTERNS: readonly RegExp[] = [
   /image does not match the provided media type/i,
 ];
 
+export const IMAGE_UNSUPPORTED_FORMAT_PATTERNS: readonly RegExp[] = [
+  /does not represent a valid image/i,
+  /supported image formats?:/i,
+];
+
 /** Whether an error message indicates an image-input dimension/payload failure. */
 export function isImageDimensionsTooLargeError(message: string): boolean {
   return IMAGE_DIMENSIONS_TOO_LARGE_PATTERNS.some((p) => p.test(message));
@@ -53,11 +66,21 @@ export function isImageMediaTypeMismatchError(message: string): boolean {
   return IMAGE_MEDIA_TYPE_MISMATCH_PATTERNS.some((p) => p.test(message));
 }
 
+/**
+ * Whether an error message indicates the image's bytes are not in a format the
+ * provider accepts at all, rather than merely mislabeled: an unsupported
+ * codec (HEIC, AVIF, BMP), or a truncated or corrupt payload.
+ */
+export function isImageUnsupportedFormatError(message: string): boolean {
+  return IMAGE_UNSUPPORTED_FORMAT_PATTERNS.some((p) => p.test(message));
+}
+
 /** Any image-input rejection the recovery hook knows how to act on. */
 export function isRecoverableImageError(message: string): boolean {
   return (
     isImageDimensionsTooLargeError(message) ||
     isImageUnprocessableError(message) ||
-    isImageMediaTypeMismatchError(message)
+    isImageMediaTypeMismatchError(message) ||
+    isImageUnsupportedFormatError(message)
   );
 }

package/src/plugins/defaults/main.ts

@@ -29,6 +29,7 @@ const DEFAULTS_DIR = resolveBundledDir(import.meta.dir, ".", "default-plugins");
 const DEFAULT_PLUGIN_NAMESPACE_PREFIX = "default-";
 
 let cachedNames: readonly string[] | null = null;
+let cachedNameSet: ReadonlySet<string> | null = null;
 let cachedDirToManifest: ReadonlyMap<string, string> | null = null;
 
 /**
@@ -58,10 +59,24 @@ export function getAllDefaultPluginNames(): readonly string[] {
       }
     }
     cachedNames = names.sort();
+    cachedNameSet = new Set(cachedNames);
   }
   return cachedNames;
 }
 
+/**
+ * Whether `name` is one of the first-party default plugins that ship in
+ * `plugins/defaults/` (e.g. `default-memory`). Used by hook collection so
+ * those plugins' hooks are not dropped by a per-chat allowlist that only
+ * names user-installed plugins.
+ */
+export function isFirstPartyDefaultPlugin(name: string): boolean {
+  if (cachedNameSet === null) {
+    getAllDefaultPluginNames();
+  }
+  return cachedNameSet !== null && cachedNameSet.has(name);
+}
+
 /**
  * Manifest name (e.g. `default-platform-hosted`) for a default plugin's
  * *directory* name (e.g. `platform-hosted`), or `null` when `<dirName>` is not

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

@@ -38,11 +38,16 @@ them. Everything not listed as a tier directory is spine.
 
 | Directory         | What lives there                                                                                                                                                                                                                                                                                                                                                                                                                  | Gate predicate                |
 | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
-| `substrate/`      | The shared concept-page substrate (v2 + v3): `page-store`, `page-index`, `edge-index`, `qdrant`, `sim`, `sparse-bm25`, `spread`, `skill-store`, `cli-command-store`, `skill-content`, `cli-command-content`, `injected-block-slugs`, `static-context`, `boot-maintenance`, `frontmatter-sweep`, `consolidation-lock`, `consolidation-job`, `ingest`, `sweep-job`, `reembed-job`, `tuning`, `types`, `constants`, `prompts/`.      | `usesConceptPageMemory()`     |
+| `substrate/`      | The shared concept-page substrate (v2 + v3): `page-store`, `page-index`, `edge-index`, `qdrant`, `sim`, `sparse-bm25`, `spread`, `skill-store`, `cli-command-store`, `skill-content`, `cli-command-content`, `injected-block-slugs`, `static-context`, `boot-maintenance`, `frontmatter-sweep`, `consolidation-lock`, `consolidation-job`, `ingest`, `sweep-job`, `reembed-job`, `tuning`, `types`, `page-links`, `prompts/`.     | `usesConceptPageMemory()`     |
 | `v1/`             | The legacy PKB/graph engine: `pkb/`, `graph/` (retriever, triggers, scoring, serendipity, extraction, extraction-job, decay, consolidation, pattern-scan, narrative, bootstrap, injection, and the hybrid node-search half of `graph-search`), `jobs/embed-pkb-file.ts`, `job-handlers/{backfill,embedding,index-maintenance}.ts`, `pkb-schedule.ts`, `filing-jobs.ts`, `semantic-search.ts`, `identity-context.ts`, `README.md`. | `isMemoryV1Active()`          |
 | `v2/`             | The v2 activation/router injection engine: `activation`, `activation-store`, `activation-log-store`, `concept-frequency`, `injection`, `injection-events`, `router`, `reranker`, `rerank-local`, `migration`, `now-text`, `backfill-jobs` (migrate + activation-recompute), `harness/`, `prompts/router`.                                                                                                                         | `isV2InjectionEngineActive()` |
 | `v3/`, `v3-eval/` | The v3 lanes, orchestrator, injectors, maintain job, and the eval siblings.                                                                                                                                                                                                                                                                                                                                                       | `isMemoryV3Live()`            |
 
+`substrate/page-links` is the one owner of `links:`-entry and `[[wikilink]]`
+parsing; every reader in any tier imports it (the same single-matcher rule
+`buffer-format` follows for buffer entries, below). Do not add a second
+wikilink matcher or `links:` splitter anywhere.
+
 Everything else under the plugin root is **spine**:
 
 - `graph/` — the **all-tier** legacy-graph store plus the tier dispatcher:
@@ -708,8 +713,11 @@ not deleted**. Today the test-only hits are:
      client-coordinated change.
    - `cli/commands/memory/memory-v2.ts` — follows its routes rather than being
      deleted outright. `memory v2 reembed` (which posts the surviving `reembed`
-     backfill op), `memory v2 reembed-skills`, and `memory v2 validate` keep
-     working and move with the substrate routes; `memory v2 activation` (the
+     backfill op) and `memory v2 reembed-skills` keep working and move with
+     the substrate routes; `memory v2 validate` and the top-level
+     `memory validate` (`cli/commands/memory/memory-validate.ts`) share
+     `runMemoryValidate`, which lives in `memory-v2.ts` and moves with the
+     survivors; `memory v2 activation` (the
      `activation-recompute` op), `memory v2 ema`, `memory v2 simulate`, and
      `memory v2 compare` go with the engine. There is no `migrate` subcommand —
      the route is that job's only enqueue path.

package/src/plugins/defaults/memory/__tests__/memory-tier-boundary-guard.test.ts

@@ -151,7 +151,6 @@ const HOST_TIER_IMPORT_ALLOWLIST: readonly HostTierImportExemption[] = [
   { path: "src/daemon/embedding-reconcile.ts", tiers: ["substrate", "v3"] },
   { path: "src/daemon/skill-memory-refresh.ts", tiers: ["substrate"] },
   { path: "src/daemon/tool-side-effects.ts", tiers: ["substrate"] },
-  { path: "src/daemon/trust-context.ts", tiers: ["substrate"] },
   { path: "src/persistence/steps.ts", tiers: ["v1"] },
   { path: "src/runtime/routes/consolidation-routes.ts", tiers: ["substrate"] },
   {

package/src/plugins/defaults/memory/graph-topology/pending-buffer.ts

@@ -22,6 +22,11 @@ import {
   formatRememberEntry,
   matchBufferEntryStart,
 } from "../buffer-format.js";
+import {
+  extractWikilinkTargets,
+  WIKILINK_REGEX,
+  wikilinkTarget,
+} from "../substrate/page-links.js";
 import type { MemoryGraphEdge, MemoryGraphNode } from "./types.js";
 
 /** Node id prefix marking a pending buffer entry (id = prefix + text hash). */
@@ -43,9 +48,6 @@ const PENDING_LABEL_MAX_CHARS = 60;
  * timestamped entry seen yet still counts as an entry of its own. */
 const PLAIN_BULLET_REGEX = /^-\s+(.+)$/;
 
-/** Matches `[[slug]]` / `[[slug|label]]` wikilinks inside an entry. */
-const WIKILINK_REGEX = /\[\[([^[\]|]+)(?:\|[^\]]*)?\]\]/g;
-
 export interface PendingBufferEntry {
   /** Stable node id (`buffer:` + content hash, deduped within one parse). */
   id: string;
@@ -116,13 +118,7 @@ export function parseBufferEntries(content: string): PendingBufferEntry[] {
   flush();
 
   for (const text of texts) {
-    const slugs: string[] = [];
-    for (const link of text.matchAll(WIKILINK_REGEX)) {
-      const slug = link[1]!.trim();
-      if (slug && !slugs.includes(slug)) {
-        slugs.push(slug);
-      }
-    }
+    const slugs = [...new Set(extractWikilinkTargets(text))];
 
     const hash = hashText(text);
     const count = (seen.get(hash) ?? 0) + 1;
@@ -144,8 +140,9 @@ export function parseBufferEntries(content: string): PendingBufferEntry[] {
 function pendingLabel(text: string): string {
   const firstLine = text.split("\n", 1)[0] ?? text;
   const plain = firstLine
-    .replace(WIKILINK_REGEX, (_match, slug: string) => {
-      return slug.trim().split("/").pop() ?? slug;
+    .replace(WIKILINK_REGEX, (_match, inner: string) => {
+      const slug = wikilinkTarget(inner);
+      return slug.split("/").pop() || slug;
     })
     .trim();
   if (plain.length <= PENDING_LABEL_MAX_CHARS) {

package/src/plugins/defaults/memory/memory-retrospective-prompt.ts

@@ -223,7 +223,7 @@ If your review window contains a PROCEDURE you actually carried out — a sequen
 
 When you do capture a procedure:
 
-1. Deduplicate against existing skills first. Call \`find_similar_skills\` with a short description of the procedure's goal. Each hit carries a \`source\` (bundled, managed, plugin, workspace, or extra), and a managed hit also carries \`author\` (\`"assistant"\` if you authored it, \`"user"\` if a person did, omitted if untagged). You may only overwrite or refine a skill YOU authored — a hit with \`source: "managed"\` AND \`author: "assistant"\`. ANY other hit means the procedure is ALREADY COVERED: a non-managed source (bundled, plugin, workspace, or extra), OR a managed skill that is NOT \`author: "assistant"\` (a person wrote it, or it is untagged). For an ALREADY COVERED hit do not \`overwrite\` it, do not shadow it by creating a skill with its \`skill_id\`, and do not create a near-duplicate — skip it. Only when a returned skill is one of your own (\`source: "managed"\`, \`author: "assistant"\`) and is the SAME procedure, UPDATE it: call \`scaffold_managed_skill\` with that \`skill_id\` and \`overwrite: true\`, rewriting the body from what you actually observed in the trace. Only CREATE a new skill (fresh \`skill_id\`) when no existing skill of any source covers the procedure. Bias strongly toward reusing or refining your own skills over spawning near-duplicates.
+1. Deduplicate against existing skills first. Call \`find_similar_skills\` with the procedure's goal as its \`goal\` argument. Each hit carries a \`source\` (bundled, managed, plugin, workspace, or extra), and a managed hit also carries \`author\` (\`"assistant"\` if you authored it, \`"user"\` if a person did, omitted if untagged). You may only overwrite or refine a skill YOU authored — a hit with \`source: "managed"\` AND \`author: "assistant"\`. ANY other hit means the procedure is ALREADY COVERED: a non-managed source (bundled, plugin, workspace, or extra), OR a managed skill that is NOT \`author: "assistant"\` (a person wrote it, or it is untagged). For an ALREADY COVERED hit do not \`overwrite\` it, do not shadow it by creating a skill with its \`skill_id\`, and do not create a near-duplicate — skip it. Only when a returned skill is one of your own (\`source: "managed"\`, \`author: "assistant"\`) and is the SAME procedure, UPDATE it: call \`scaffold_managed_skill\` with that \`skill_id\` and \`overwrite: true\`, rewriting \`body_markdown\` from what you actually observed in the trace. Only CREATE a new skill (fresh \`skill_id\`) when no existing skill of any source covers the procedure. Bias strongly toward reusing or refining your own skills over spawning near-duplicates.
 
 2. Capture procedure-scoped knowledge alongside the body. Failure modes, gotchas, and cached values you observed in the trace (error signatures and how you recovered, preconditions, IDs/paths/endpoints that held steady) belong in companion files passed via \`scaffold_managed_skill\`'s \`files\` input (for example \`references/failure-modes.md\`), and the SKILL.md body should reference them so a future load surfaces them.
 

package/src/plugins/defaults/memory/src/memory-v2-routes.ts

@@ -22,12 +22,9 @@ import type { RouteDefinition } from "../../../../runtime/routes/types.js";
 import type { RouteHandlerArgs } from "../../../../runtime/routes/types.js";
 import { getLogger } from "../logging.js";
 import { getWorkspaceDir } from "../paths.js";
-import {
-  getEdgeIndex,
-  totalEdgeCount,
-  validateEdgeTargets,
-} from "../substrate/edge-index.js";
+import { getEdgeIndex, totalEdgeCount } from "../substrate/edge-index.js";
 import { getPageIndex } from "../substrate/page-index.js";
+import type { DanglingLink } from "../substrate/page-links.js";
 import {
   getConceptsDir,
   listPages,
@@ -111,14 +108,17 @@ async function handleBackfill({
 
 const MemoryV2ValidateParams = z.object({}).strict();
 
-type MissingEdgeEndpoint = { from: string; to: string };
 type OversizedPage = { slug: string; chars: number };
 type ParseFailure = { slug: string; error: string };
 
 export type MemoryV2ValidateResult = {
   pageCount: number;
   edgeCount: number;
-  missingEdgeEndpoints: MissingEdgeEndpoint[];
+  /**
+   * `links:`, `[[wikilink]]`, and `edges:` references whose target has no
+   * page (`PageIndex.danglingLinks`).
+   */
+  danglingLinks: DanglingLink[];
   oversizedPages: OversizedPage[];
   parseFailures: ParseFailure[];
 };
@@ -162,13 +162,15 @@ async function handleValidate({
     }
   }
 
-  const edgeIndex = await getEdgeIndex(workspaceDir);
-  const { missing } = validateEdgeTargets(edgeIndex, knownSlugs);
+  const [edgeIndex, pageIndex] = await Promise.all([
+    getEdgeIndex(workspaceDir),
+    getPageIndex(workspaceDir),
+  ]);
 
   return {
     pageCount: knownSlugs.size,
     edgeCount: totalEdgeCount(edgeIndex),
-    missingEdgeEndpoints: missing,
+    danglingLinks: pageIndex.danglingLinks,
     oversizedPages,
     parseFailures,
   };

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

@@ -615,6 +615,32 @@ describe("memoryV2ConsolidateJob — non-empty buffer", () => {
     }
   });
 
+  test("threads page-index dangling links into the prompt's repair step", async () => {
+    const conceptsDir = join(tmpWorkspace, "memory", "concepts");
+    const sourcePath = join(conceptsDir, "atl-1290.md");
+    // A `links:` entry naming a page that does not exist (the LUM-3316 shape).
+    writeFileSync(
+      sourcePath,
+      "---\nlinks:\n  - atl-1291\n---\n# ATL-1290\n\nSee [[atl-1291]].\n",
+    );
+    invalidatePageIndex();
+    try {
+      const result = await memoryV2ConsolidateJob(makeJob(), CONFIG);
+      expect(result.kind).toBe("invoked");
+      const prompt = runnerLastArgs?.prompt as string;
+      expect(prompt).toContain("resolve dangling links");
+      expect(prompt).toContain(
+        "- `memory/concepts/atl-1290.md` → `atl-1291` (frontmatter `links:` entry)",
+      );
+      expect(prompt).toContain(
+        "- `memory/concepts/atl-1290.md` → `atl-1291` (inline `[[wikilink]]` in the body)",
+      );
+    } finally {
+      rmSync(sourcePath, { force: true });
+      invalidatePageIndex();
+    }
+  });
+
   test("dispatches with skipPromptIndexing so the kickoff prompt is not indexed", async () => {
     // The prompt is a static instruction manual — indexing it would write
     // near-identical memory segments, embeddings, and a lexical entry on
@@ -880,6 +906,94 @@ describe("memoryV2ConsolidateJob — progress check and follow-up coalescing", (
     expect(enqueuedJobs).toHaveLength(0);
   });
 
+  test("a run that leaves dangling links reports the count and still enqueues follow-ups", async () => {
+    const conceptsDir = join(tmpWorkspace, "memory", "concepts");
+    runnerImpl = async () => {
+      // The agent files the buffer into a page whose links: names a page it
+      // never spawned. Writing through the file tools would invalidate the
+      // index via the tool hook; the stub does so by hand.
+      writeFileSync(
+        join(conceptsDir, "atl-1290.md"),
+        "---\nlinks:\n  - atl-1291\n---\n# ATL-1290\n",
+      );
+      writeFileSync(bufferPath(), "");
+      invalidatePageIndex();
+      return { conversationId: "conv-1", ok: true };
+    };
+    try {
+      const result = await memoryV2ConsolidateJob(makeJob(), CONFIG);
+
+      expect(result.kind).toBe("invoked");
+      if (result.kind !== "invoked") {
+        throw new Error("unreachable");
+      }
+      expect(result.noProgress).toBe(false);
+      expect(result.danglingLinks).toBe(1);
+      // Surfaced, not gating: the page that was written still gets indexed.
+      expect(result.followUpJobIds).toEqual(["job-1"]);
+      expect(enqueuedJobs.map((j) => j.type)).toEqual(["memory_v2_reembed"]);
+    } finally {
+      rmSync(join(conceptsDir, "atl-1290.md"), { force: true });
+      invalidatePageIndex();
+    }
+  });
+
+  test("a run that spawns the missing target clears the pre-run dangling link", async () => {
+    const conceptsDir = join(tmpWorkspace, "memory", "concepts");
+    writeFileSync(
+      join(conceptsDir, "atl-1290.md"),
+      "---\nlinks:\n  - atl-1291\n---\n# ATL-1290\n",
+    );
+    invalidatePageIndex();
+    runnerImpl = async () => {
+      writeFileSync(join(conceptsDir, "atl-1291.md"), "# ATL-1291\n");
+      writeFileSync(bufferPath(), "");
+      invalidatePageIndex();
+      return { conversationId: "conv-1", ok: true };
+    };
+    try {
+      const result = await memoryV2ConsolidateJob(makeJob(), CONFIG);
+
+      expect(result.kind).toBe("invoked");
+      if (result.kind !== "invoked") {
+        throw new Error("unreachable");
+      }
+      // The pre-run index fed the repair step...
+      expect(runnerLastArgs?.prompt as string).toContain(
+        "resolve dangling links",
+      );
+      // ...and the post-run count reflects the repair.
+      expect(result.danglingLinks).toBe(0);
+    } finally {
+      rmSync(join(conceptsDir, "atl-1290.md"), { force: true });
+      rmSync(join(conceptsDir, "atl-1291.md"), { force: true });
+      invalidatePageIndex();
+    }
+  });
+
+  test("a no-progress run still reports its dangling-link count", async () => {
+    const conceptsDir = join(tmpWorkspace, "memory", "concepts");
+    writeFileSync(
+      join(conceptsDir, "atl-1290.md"),
+      "---\nlinks:\n  - atl-1291\n---\n# ATL-1290\n",
+    );
+    invalidatePageIndex();
+    runnerImpl = async () => ({ conversationId: "conv-1", ok: true });
+    try {
+      const result = await memoryV2ConsolidateJob(makeJob(), CONFIG);
+
+      expect(result.kind).toBe("invoked");
+      if (result.kind !== "invoked") {
+        throw new Error("unreachable");
+      }
+      expect(result.noProgress).toBe(true);
+      expect(result.danglingLinks).toBe(1);
+    } finally {
+      rmSync(join(conceptsDir, "atl-1290.md"), { force: true });
+      invalidatePageIndex();
+    }
+  });
+
   test("a pending reembed suppresses its duplicate; v3 maintain still enqueues", async () => {
     v3FlagOn = true;
     pendingJobTypes.add("memory_v2_reembed");