@vellumai/assistant 0.8.9-staging.2 → 0.8.9-staging.4

package/src/memory/v2/consolidation-job.ts

@@ -63,19 +63,6 @@ import { dirname, join } from "node:path";
 
 import { isAssistantFeatureFlagEnabled } from "../../config/assistant-feature-flags.js";
 import type { AssistantConfig } from "../../config/types.js";
-import { loadCore } from "../../plugins/defaults/memory-v3-shadow/core.js";
-import {
-  computeV3Health,
-  renderV3Health,
-} from "../../plugins/defaults/memory-v3-shadow/health.js";
-import {
-  loadLeafTree,
-  resolveDataDir,
-} from "../../plugins/defaults/memory-v3-shadow/tree.js";
-import type {
-  LeafPath,
-  Slug,
-} from "../../plugins/defaults/memory-v3-shadow/types.js";
 import { runBackgroundJob } from "../../runtime/background-job-runner.js";
 import { getLogger } from "../../util/logger.js";
 import { getWorkspaceDir } from "../../util/platform.js";
@@ -86,7 +73,6 @@ import {
   type MemoryJob,
   type MemoryJobType,
 } from "../jobs-store.js";
-import { getPageIndex } from "../v2/page-index.js";
 import { MEMORY_V2_CONSOLIDATION_SOURCE } from "./constants.js";
 import { resolveConsolidationPrompt } from "./prompts/consolidation.js";
 
@@ -96,8 +82,7 @@ const log = getLogger("memory-v2-consolidate");
 const JOB_NAME = "memory.consolidate";
 
 /**
- * v3 plugin flags. Either being on (a) prepends a v3 health block to the
- * consolidation prompt and (b) enqueues `memory_v3_maintain` as a
+ * v3 plugin flags. Either being on enqueues `memory_v3_maintain` as a
  * post-consolidation follow-up. These gate the v3 plugin itself.
  */
 const MEMORY_V3_SHADOW = "memory-v3-shadow" as const;
@@ -191,15 +176,10 @@ export async function memoryV2ConsolidateJob(
     // it to a regular file under 1 MiB before substitution so a stray path
     // (or a `/dev/zero`-style pseudo-file) cannot exfiltrate megabytes of
     // bytes through the wake hint.
-    //
-    // That resolved prompt is the base; `maybePrependV3Health` prepends a
-    // freshly computed v3 health block when a v3 flag is on and the tree has
-    // actionable drift, leaving it untouched otherwise.
-    const basePrompt = resolveConsolidationPrompt(
+    const prompt = resolveConsolidationPrompt(
       config.memory.v2.consolidation_prompt_path,
       cutoff,
     );
-    const prompt = await maybePrependV3Health(basePrompt, config);
 
     const runResult = await runBackgroundJob({
       jobName: JOB_NAME,
@@ -270,56 +250,6 @@ export async function memoryV2ConsolidateJob(
   }
 }
 
-/**
- * When a v3 flag is enabled and the v3 tree has actionable structural drift,
- * prepend a rendered health block to `basePrompt` so the consolidation run can
- * fold tree maintenance into its pass. Returns `basePrompt` UNCHANGED when:
- *   - neither `memory-v3-shadow` nor `memory-v3-live` is enabled,
- *   - the health report is all-green (`renderV3Health` returns ""), or
- *   - computing the report throws for any reason.
- *
- * The block is computed here (not baked into the prompt template) so an
- * operator's custom consolidation prompt stays untouched and the block reflects
- * the tree state at run time. Health computation is wrapped so a load/compute
- * failure can never break consolidation — the run proceeds on the base prompt.
- */
-async function maybePrependV3Health(
-  basePrompt: string,
-  config: AssistantConfig,
-): Promise<string> {
-  const v3Enabled =
-    isAssistantFeatureFlagEnabled(MEMORY_V3_SHADOW, config) ||
-    isAssistantFeatureFlagEnabled(MEMORY_V3_LIVE, config);
-  if (!v3Enabled) return basePrompt;
-
-  try {
-    const pageIndex = await getPageIndex(getWorkspaceDir());
-    const pageLeaves = new Map<Slug, LeafPath[]>();
-    const allSlugs: Slug[] = [];
-    for (const entry of pageIndex.entries) {
-      pageLeaves.set(entry.slug, entry.leaves);
-      allSlugs.push(entry.slug);
-    }
-
-    const dataDir = resolveDataDir();
-    const [tree, core] = await Promise.all([
-      loadLeafTree(dataDir, pageLeaves),
-      loadCore(dataDir),
-    ]);
-
-    const report = computeV3Health({ tree, allSlugs, core });
-    const healthBlock = renderV3Health(report);
-    if (healthBlock.length === 0) return basePrompt;
-    return `${healthBlock}\n\n${basePrompt}`;
-  } catch (err) {
-    log.warn(
-      { err: err instanceof Error ? err.message : String(err) },
-      "consolidation: v3 health computation failed; using base prompt",
-    );
-    return basePrompt;
-  }
-}
-
 /**
  * Read `memory/buffer.md`. Missing file → empty string so the skip-on-empty
  * branch doesn't have to distinguish "no file" from "blank file".

package/src/memory/v2/types.ts

@@ -41,6 +41,11 @@ export const ConceptPageFrontmatterSchema = z
     ref_urls: z.array(z.string().url()).default([]),
     summary: z.string().optional(),
     leaves: z.array(z.string()).optional(),
+    // Optional authored `"<target-slug> — <why>"` cross-links. Curated, first-class
+    // edges for the memory-v3 edge lane. Declared here so `.strict()` does not
+    // reject a page that uses `links:`, and so `renderPageContent` round-trips the
+    // field (the edge graph reads it back from the rendered frontmatter).
+    links: z.array(z.string()).optional(),
   })
   .strict();
 

package/src/messaging/providers/telegram-bot/api.ts

@@ -8,7 +8,8 @@
  */
 
 import { credentialKey } from "../../../security/credential-key.js";
-import { getSecureKeyAsync } from "../../../security/secure-keys.js";
+import { getSecureKeyResultAsync } from "../../../security/secure-keys.js";
+import { BackendUnavailableError, ConfigError } from "../../../util/errors.js";
 import { getLogger } from "../../../util/logger.js";
 
 const log = getLogger("telegram-api");
@@ -197,13 +198,21 @@ async function retryableFetch<T>(
 // ---------------------------------------------------------------------------
 
 async function resolveBotToken(): Promise<string> {
-  const botToken = await getSecureKeyAsync(
+  const result = await getSecureKeyResultAsync(
     credentialKey("telegram", "bot_token"),
   );
-  if (!botToken) {
-    throw new Error("Telegram bot token not configured");
+  if (result.value) {
+    return result.value;
   }
-  return botToken;
+  // Distinguish a transient credential-store outage from a token that was
+  // genuinely never set. Both surface as an absent value, but only the
+  // latter is an operator misconfiguration; the former is retryable
+  // infrastructure unavailability that callers should not treat as
+  // "not configured".
+  if (result.unreachable) {
+    throw new BackendUnavailableError("Telegram credential store unreachable");
+  }
+  throw new ConfigError("Telegram bot token not configured");
 }
 
 // ---------------------------------------------------------------------------

package/src/notifications/adapters/telegram.ts

@@ -10,6 +10,7 @@
 
 import { sendTelegramReply } from "../../messaging/providers/telegram-bot/send.js";
 import type { ApprovalUIMetadata } from "../../runtime/channel-approval-types.js";
+import { ConfigError } from "../../util/errors.js";
 import { getLogger } from "../../util/logger.js";
 import { isConversationSeedSane } from "../conversation-seed-composer.js";
 import { buildAccessRequestContractText, nonEmpty } from "../copy-composer.js";
@@ -136,7 +137,12 @@ export class TelegramAdapter implements ChannelAdapter {
       return { success: true };
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
-      log.error(
+      // A missing bot token means the operator simply hasn't configured
+      // Telegram; it is not a code fault, so log it at warn to keep it out
+      // of Sentry. Genuine and transient failures (e.g. an unreachable
+      // credential store) stay at error so they remain visible.
+      const logFn = err instanceof ConfigError ? log.warn : log.error;
+      logFn(
         { err, sourceEventName: payload.sourceEventName, chatId },
         "Failed to deliver Telegram notification",
       );

package/src/plugin-api/constants.ts

@@ -26,8 +26,8 @@ export const HOOKS = {
   POST_TOOL_USE: "post-tool-use",
   /** Fires when the model yields a response with no tool calls — the run's stop boundary. Decides whether to stop or continue with a follow-up turn. */
   STOP: "stop",
-  /** Fires for each finalized assistant message, before it is persisted/streamed-final. A hook may transform the message content. */
-  ASSISTANT_MESSAGE: "assistant-message",
+  /** Fires for each finalized assistant message, once per model call, before it is persisted/streamed-final. A hook may transform the message content. */
+  POST_MODEL_CALL: "post-model-call",
 } as const;
 
 /** Union of every hook name declared in {@link HOOKS}. */

package/src/plugin-api/index.ts

@@ -30,7 +30,7 @@
  *   per tool result before it joins the provider-bound history
  * - {@link StopContext} — passed to `stop` hook, fired when the model yields
  *   a response with no tool calls
- * - {@link AssistantMessageContext} — passed to `assistant-message` hook,
+ * - {@link PostModelCallContext} — passed to `post-model-call` hook,
  *   fired for each finalized assistant message to transform its content
  * - {@link PluginHookFn} — signature every lifecycle hook implements
  * - {@link PluginLogger} — pino-compatible logger shape on the contexts
@@ -43,11 +43,11 @@
 export type { HookName } from "./constants.js";
 export { HOOKS } from "./constants.js";
 export type {
-  AssistantMessageContext,
   PluginHookFn,
   PluginInitContext,
   PluginLogger,
   PluginShutdownContext,
+  PostModelCallContext,
   PostToolUseContext,
   PreModelCallContext,
   StopContext,

package/src/plugin-api/types.ts

@@ -55,7 +55,7 @@ export interface PluginLogger {
  *   - `pre-model-call` — {@link PreModelCallContext}
  *   - `post-tool-use` — {@link PostToolUseContext}
  *   - `stop` — {@link StopContext}
- *   - `assistant-message` — {@link AssistantMessageContext}
+ *   - `post-model-call` — {@link PostModelCallContext}
  */
 export type PluginHookFn<TCtx = unknown> = (ctx: TCtx) => Promise<TCtx | void>;
 
@@ -130,6 +130,20 @@ export interface PluginShutdownContext {
 export interface UserPromptSubmitContext {
   /** Conversation ID the user prompt was submitted on. */
   readonly conversationId: string;
+  /**
+   * Persisted ID of the user message that triggered this turn. Hooks that
+   * attach turn-scoped metadata to the originating message (e.g. recording an
+   * injected memory block so it survives a conversation reload) key off this
+   * row id rather than the in-memory message arrays, whose entries carry no id.
+   */
+  readonly userMessageId: string;
+  /**
+   * Stable ID for the request that drives this turn. Hooks that perform
+   * runtime injection forward it onto the injector turn context so the
+   * assembled blocks are attributed to the originating request; it is fixed
+   * for the turn and cannot be recovered from the message arrays.
+   */
+  readonly requestId: string;
   /**
    * The text of the user prompt that triggered this turn — the resolved
    * user message (after slash-command expansion), independent of any
@@ -321,7 +335,7 @@ export interface PreModelCallContext {
   systemPrompt: string | undefined;
   /**
    * Seeded `false`. When a hook sets it `true`, the loop suppresses this turn's
-   * live assistant `text_delta` stream; an `assistant-message` hook is then
+   * live assistant `text_delta` stream; a `post-model-call` hook is then
    * expected to produce the text the client sees (emitted once, after the reply
    * is finalized). Lets a plugin replace streamed output wholesale — e.g.
    * redaction that needs the full message — instead of leaking the raw stream.
@@ -331,10 +345,10 @@ export interface PreModelCallContext {
   readonly logger: PluginLogger;
 }
 
-// ─── Assistant-message hook context ──────────────────────────────────────────
+// ─── Post-model-call hook context ────────────────────────────────────────────
 
 /**
- * Context passed to the `assistant-message` hook. Fires for each finalized
+ * Context passed to the `post-model-call` hook. Fires for each finalized
  * assistant message — once per model call, at the message-complete boundary —
  * before the message is persisted and (if deferred) streamed-final. Unlike
  * {@link StopContext}'s read-only `responseContent` (which exists for the stop
@@ -348,7 +362,7 @@ export interface PreModelCallContext {
  * place or return a new context; throwing is contained by the loop (the original
  * content is kept).
  */
-export interface AssistantMessageContext {
+export interface PostModelCallContext {
   /** Conversation ID the message belongs to. */
   readonly conversationId: string;
   /** The call site this message serves — `"mainAgent"` for the user-facing reply. */

package/src/plugins/defaults/compaction/compact.ts

@@ -2,19 +2,19 @@
  * Default compaction implementation.
  *
  * Summarizes conversation history when the context window fills up by
- * delegating to a {@link ContextWindowManager}. The agent loop calls
- * {@link defaultCompact} directly with a {@link CompactionContext}; the request
- * carries the conversational inputs while the manager performs the work.
+ * delegating to the conversation's {@link ContextWindowManager}. The agent loop
+ * calls {@link defaultCompact} directly with a {@link CompactionContext}; the
+ * request carries the conversational inputs while the compaction module resolves
+ * (and, if needed, builds) the manager from its per-conversation store.
  *
  * This module is side-effect free: importing it does not register any plugin.
  */
 
-import type {
-  ContextWindowManager,
-  ContextWindowResult,
-} from "../../../context/window-manager.js";
 import type { Message } from "../../../providers/types.js";
 import type { TrustClass } from "../../../runtime/actor-trust-resolver.js";
+import { PluginExecutionError } from "../../types.js";
+import { getContextWindowManager } from "./manager-store.js";
+import type { ContextWindowResult } from "./window-manager.js";
 
 /**
  * Name under which the default compaction plugin registers. Exposed so call
@@ -24,13 +24,14 @@ export const DEFAULT_COMPACTION_PLUGIN_NAME = "default-compaction";
 
 /**
  * Self-describing compaction request handed to {@link defaultCompact}. Carries
- * the conversational inputs plus the {@link ContextWindowManager} that runs the
- * summary, so the request is the part that can grow toward a model-facing
- * compaction-method shape without coupling callers to the manager's option bag.
+ * the conversational inputs plus the `conversationId` the compaction module
+ * resolves its manager from, so callers never hold or pass a manager handle and
+ * the request can grow toward a model-facing compaction-method shape without
+ * coupling callers to the manager's option bag.
  */
 export interface CompactionContext {
-  /** Context window manager that performs the compaction. */
-  manager: ContextWindowManager;
+  /** Conversation whose manager performs the compaction. */
+  conversationId: string;
   /** Message history to consider for compaction. */
   messages: Message[];
   /** Abort signal forwarded to the compaction summary call. */
@@ -48,12 +49,20 @@ export interface CompactionContext {
 }
 
 /**
- * Run compaction for the turn: delegates to the request's context window
- * manager and returns the (possibly summarized) message history.
+ * Run compaction for the turn: resolves the conversation's context window
+ * manager from the compaction store (building it on first access) and returns
+ * the (possibly summarized) message history.
  */
 export async function defaultCompact(
   context: CompactionContext,
 ): Promise<ContextWindowResult> {
-  const { manager, messages, signal, ...options } = context;
+  const { conversationId, messages, signal, ...options } = context;
+  const manager = getContextWindowManager(conversationId);
+  if (manager == null) {
+    throw new PluginExecutionError(
+      `default-compaction: no ContextWindowManager registered for conversation ${conversationId} — the conversation must register one before compaction runs`,
+      DEFAULT_COMPACTION_PLUGIN_NAME,
+    );
+  }
   return manager.maybeCompact(messages, signal, options);
 }

package/src/plugins/defaults/compaction/context-overflow-reducer.ts

@@ -22,10 +22,6 @@ import {
   estimatePromptTokens,
 } from "../../../context/token-estimator.js";
 import { truncateToolResultsAcrossHistory } from "../../../context/tool-result-truncation.js";
-import type {
-  ContextWindowCompactOptions,
-  ContextWindowResult,
-} from "../../../context/window-manager.js";
 import {
   countMediaBlocks,
   estimateUnconditionalStubTokens,
@@ -33,6 +29,10 @@ import {
 } from "../../../daemon/conversation-media-retry.js";
 import type { InjectionMode } from "../../../daemon/conversation-runtime-assembly.js";
 import type { Message } from "../../../providers/types.js";
+import type {
+  ContextWindowCompactOptions,
+  ContextWindowResult,
+} from "./window-manager.js";
 
 /**
  * Identifies which reduction tier was applied in a given step.

package/src/plugins/defaults/compaction/manager-store.ts

@@ -15,7 +15,7 @@
 import {
   ContextWindowManager,
   type ContextWindowManagerOptions,
-} from "../../../context/window-manager.js";
+} from "./window-manager.js";
 
 /** Live managers keyed by conversation id. */
 const managersByConversation = new Map<string, ContextWindowManager>();

package/src/{context → plugins/defaults/compaction}/window-manager.ts

@@ -14,23 +14,25 @@
  * marker is wrapped around the assistant-role memory message we emit on
  * successful compaction so those code paths keep working unchanged.
  */
-import { getConfig } from "../config/loader.js";
-import type { CompactionConfig } from "../config/schemas/compaction.js";
-import type { LLMCallSite } from "../config/schemas/llm.js";
-import type { ContextWindowConfig } from "../config/types.js";
+import { getConfig } from "../../../config/loader.js";
+import type { CompactionConfig } from "../../../config/schemas/compaction.js";
+import type { LLMCallSite } from "../../../config/schemas/llm.js";
+import type { ContextWindowConfig } from "../../../config/types.js";
+import {
+  type CompactionRunArgs,
+  type CompactionRunResult,
+  runAssistantDrivenCompaction,
+  runEmergencyCompaction,
+} from "../../../context/compactor.js";
+import { estimatePromptTokens } from "../../../context/token-estimator.js";
 import type {
   ContentBlock,
   Message,
   Provider,
   ToolDefinition,
-} from "../providers/types.js";
-import type { TrustClass } from "../runtime/actor-trust-resolver.js";
-import { getLogger } from "../util/logger.js";
-import {
-  type CompactionRunArgs,
-  runAssistantDrivenCompaction,
-} from "./compactor.js";
-import { estimatePromptTokens } from "./token-estimator.js";
+} from "../../../providers/types.js";
+import type { TrustClass } from "../../../runtime/actor-trust-resolver.js";
+import { getLogger } from "../../../util/logger.js";
 
 const log = getLogger("context-window");
 
@@ -118,6 +120,21 @@ export interface ContextWindowCompactOptions {
   actorTrustClass?: TrustClass;
 }
 
+export interface EmergencyCompactOptions {
+  /**
+   * The provider-reported estimate at the overflow that triggered recovery.
+   * Sizing the emergency summary needs the actual rejected token count, not
+   * the manager's pre-send estimate (which under-counted, hence the
+   * rejection).
+   */
+  previousEstimatedInputTokens: number;
+  /**
+   * Per-conversation inference-profile override forwarded to the summary
+   * call.
+   */
+  overrideProfile?: string | null;
+}
+
 export interface ContextWindowManagerOptions {
   provider: Provider;
   systemPrompt: string | (() => string);
@@ -428,6 +445,45 @@ export class ContextWindowManager {
     return { ...result, estimatedInputTokens, exhausted: true };
   }
 
+  /**
+   * Emergency mid-turn compaction — summarize everything before the last
+   * tool_use/tool_result pair and let the agent continue with
+   * `[summary, last_tool_call, last_tool_result]`. Used as a recovery rung
+   * after the provider rejects a turn for context overflow. The manager
+   * supplies the provider, system prompt, token budget, conversation id, and
+   * non-persisted prefix count it already owns; the caller provides only the
+   * overflow-specific inputs.
+   */
+  async emergencyCompact(
+    messages: Message[],
+    options: EmergencyCompactOptions,
+    signal?: AbortSignal,
+  ): Promise<CompactionRunResult> {
+    if (this.conversationId == null) {
+      throw new Error(
+        "ContextWindowManager has no conversationId — cannot run emergency compaction",
+      );
+    }
+    try {
+      return await runEmergencyCompaction({
+        conversationId: this.conversationId,
+        messages,
+        provider: this.provider,
+        systemPrompt: this.systemPrompt,
+        tools: undefined,
+        compaction: this.resolveCompactionConfig(),
+        maxInputTokens: this.config.maxInputTokens,
+        previousEstimatedInputTokens: options.previousEstimatedInputTokens,
+        force: true,
+        signal,
+        overrideProfile: options.overrideProfile ?? null,
+        nonPersistedPrefixCount: this._nonPersistedPrefixCount,
+      });
+    } finally {
+      this.clearSystemPromptCache();
+    }
+  }
+
   /**
    * Recompute the prompt-token estimate against the post-compaction
    * message array. The compactor returns a conservative placeholder; the

package/src/plugins/defaults/memory-retrieval/hooks/user-prompt-submit-temp.ts

@@ -37,8 +37,7 @@ import { getConfig } from "../../../../config/loader.js";
 import { findConversationOrSubagent } from "../../../../daemon/conversation-registry.js";
 import {
   applyRuntimeInjections,
-  type InboundActorContext,
-  type InjectionMode,
+  resolveTurnInboundActorContext,
   type RuntimeInjectionResult,
 } from "../../../../daemon/conversation-runtime-assembly.js";
 import type { ServerMessage } from "../../../../daemon/message-protocol.js";
@@ -78,12 +77,6 @@ export interface MemoryRetrievalHookContext {
    * context. The one turn-identity field the live conversation can't recover.
    */
   readonly requestId: string | undefined;
-  /**
-   * Injection volume for the assembled blocks. `"full"` on the first call;
-   * overflow reduction downgrades subsequent re-injection, but the first-call
-   * assembly this hook performs runs at the loop's committed mode.
-   */
-  readonly mode: InjectionMode;
   /**
    * Whether the in-flight turn has no human present to answer clarification
    * questions. Resolved once at turn start and threaded in so injection uses
@@ -96,12 +89,6 @@ export interface MemoryRetrievalHookContext {
    * at turn start, so it is threaded in rather than re-derived.
    */
   readonly modelProfile: string | null;
-  /**
-   * Inbound actor identity and trust fields for the unified `<turn_context>`
-   * block, or `null` on guardian turns (which suppress the actor section).
-   * Resolved once at turn start from the actor-trust resolver and threaded in.
-   */
-  readonly actorContext: InboundActorContext | null;
 }
 
 /**
@@ -266,6 +253,10 @@ const userPromptSubmitMemoryRetrieval: PluginHookFn<
   const abortSignal = conversation?.abortController?.signal;
   const isTrustedActor =
     resolveTrustClass(conversation?.trustContext) === "guardian";
+  const actorContext = resolveTurnInboundActorContext(
+    conversation?.trustContext,
+    conversation?.assistantId,
+  );
 
   if (conversation && isTrustedActor && abortSignal) {
     const graphResult = await conversation.graphMemory.prepareMemory(
@@ -309,13 +300,16 @@ const userPromptSubmitMemoryRetrieval: PluginHookFn<
   // input — the Slack chronological transcript, the unified `<turn_context>`
   // block, channel/voice/transport hints, and the turn's trust/index/call-site
   // — from the live conversation, so we hand in only the request id and
-  // conversation id plus the fields resolved once at turn start (`mode`,
-  // `isNonInteractive`, `modelProfile`, `actorContext`).
+  // conversation id plus the fields resolved once at turn start
+  // (`isNonInteractive`, `modelProfile`). The unified `<turn_context>` actor
+  // input is self-resolved from the live conversation's trust context. This
+  // first-call assembly always runs at `"full"` volume; overflow reduction only
+  // downgrades the mode on later re-injection.
   const injection = await applyRuntimeInjections(ctx.latestMessages, {
     isNonInteractive: ctx.isNonInteractive,
     modelProfile: ctx.modelProfile,
-    actorContext: ctx.actorContext,
-    mode: ctx.mode,
+    actorContext,
+    mode: "full",
     requestId: ctx.requestId,
     conversationId: ctx.conversationId,
   });

package/src/plugins/defaults/memory-v3-shadow/__tests__/capabilities.test.ts

@@ -1,18 +1,11 @@
 import { describe, expect, test } from "bun:test";
 
 import {
-  CAPABILITIES_LEAF_PATH,
+  capabilityOrDiskBody,
   type CapabilityResolvers,
-  injectCapabilitiesLeaf,
   isCapabilitySlug,
   renderCapabilityContent,
 } from "../capabilities.js";
-import { buildNeedleIndex } from "../needle.js";
-import type { LeafPath, LeafTree, Slug } from "../types.js";
-
-function emptyTree(): LeafTree {
-  return { leaves: new Map(), byPage: new Map<Slug, LeafPath[]>() };
-}
 
 describe("isCapabilitySlug", () => {
   test("true for skill and CLI-command slugs, false otherwise", () => {
@@ -23,52 +16,6 @@ describe("isCapabilitySlug", () => {
   });
 });
 
-describe("injectCapabilitiesLeaf", () => {
-  test("registers an always-on leaf with the synthetic slugs as members", () => {
-    const tree = emptyTree();
-    const core = new Set<LeafPath>();
-    injectCapabilitiesLeaf(tree, core, ["skills/foo", "cli-commands/bar"]);
-
-    const leaf = tree.leaves.get(CAPABILITIES_LEAF_PATH);
-    expect(leaf?.frontmatter.in_core).toBe(true);
-    expect(leaf?.members).toEqual(["skills/foo", "cli-commands/bar"]);
-    expect(core.has(CAPABILITIES_LEAF_PATH)).toBe(true);
-  });
-
-  test("unions the leaf into each member's byPage entry without dropping existing leaves", () => {
-    const tree = emptyTree();
-    tree.byPage.set("skills/foo", ["other/leaf"]);
-    injectCapabilitiesLeaf(tree, new Set<LeafPath>(), [
-      "skills/foo",
-      "cli-commands/bar",
-    ]);
-
-    expect(tree.byPage.get("skills/foo")).toEqual([
-      "other/leaf",
-      CAPABILITIES_LEAF_PATH,
-    ]);
-    expect(tree.byPage.get("cli-commands/bar")).toEqual([
-      CAPABILITIES_LEAF_PATH,
-    ]);
-  });
-
-  test("is idempotent — re-injecting does not duplicate the byPage entry", () => {
-    const tree = emptyTree();
-    const core = new Set<LeafPath>();
-    injectCapabilitiesLeaf(tree, core, ["skills/foo"]);
-    injectCapabilitiesLeaf(tree, core, ["skills/foo"]);
-    expect(tree.byPage.get("skills/foo")).toEqual([CAPABILITIES_LEAF_PATH]);
-  });
-
-  test("stays always-on even with no installed skills/commands", () => {
-    const tree = emptyTree();
-    const core = new Set<LeafPath>();
-    injectCapabilitiesLeaf(tree, core, []);
-    expect(tree.leaves.get(CAPABILITIES_LEAF_PATH)?.members).toEqual([]);
-    expect(core.has(CAPABILITIES_LEAF_PATH)).toBe(true);
-  });
-});
-
 describe("renderCapabilityContent", () => {
   const resolvers: CapabilityResolvers = {
     skill: (slug) =>
@@ -100,19 +47,25 @@ describe("renderCapabilityContent", () => {
   });
 });
 
-describe("needle indexes injected capability members", () => {
-  test("a skill slug is lexically retrievable by its title and summary", async () => {
-    const tree = emptyTree();
-    injectCapabilitiesLeaf(tree, new Set<LeafPath>(), ["skills/meet-join"]);
+describe("capabilityOrDiskBody", () => {
+  test("a capability slug routes through renderCapabilityContent and never reads disk", async () => {
+    let diskReads = 0;
+    const readDiskBody = async (): Promise<string> => {
+      diskReads += 1;
+      return "disk body — should not be read";
+    };
+    // A capability slug whose production cache has no entry degrades to "" (the
+    // `renderCapabilityContent` contract) rather than falling through to the
+    // injected disk reader, which must stay untouched.
+    expect(await capabilityOrDiskBody("skills/example", readDiskBody)).toBe("");
+    expect(diskReads).toBe(0);
+  });
 
-    const needle = await buildNeedleIndex(
-      tree,
-      async () => "Join and transcribe a video meeting",
+  test("a non-capability slug returns the injected disk reader's result", async () => {
+    const readDiskBody = async (slug: string): Promise<string> =>
+      `disk body for ${slug}`;
+    expect(await capabilityOrDiskBody("relationship/vows", readDiskBody)).toBe(
+      "disk body for relationship/vows",
     );
-
-    // By slug-derived title token.
-    expect(needle.query("meet", 5)).toContain("skills/meet-join");
-    // By summary token.
-    expect(needle.query("transcribe", 5)).toContain("skills/meet-join");
   });
 });