@vellumai/assistant 0.8.12 → 0.9.0-staging.1

package/src/plugin-api/types.ts

@@ -493,8 +493,11 @@ export type PostModelCallDecision = "continue" | "stop";
  *   the hook's result as the persisted and streamed message), and
  *   {@link stopReason} carries the provider's stop reason. Fires once per model
  *   call, including tool-bearing turns (a reply can carry both text and
- *   `tool_use`), so a hook should transform only the blocks it owns and leave
- *   others — notably `tool_use` — intact.
+ *   `tool_use`). A hook should leave blocks it does not own untouched, but it
+ *   may **append a `tool_use` block** to invoke a tool as if the model had
+ *   called it — the loop executes whatever the finalized content carries (see
+ *   {@link content}). This is the supported way for a plugin to drive a tool
+ *   (e.g. render a surface via `ui_show`) deterministically after a turn.
  * - **Provider rejection.** The call threw before any reply existed.
  *   {@link error} holds the rejection, {@link content} is empty, and
  *   {@link stopReason} is `null`. A hook that recognizes the rejection may
@@ -518,8 +521,17 @@ export interface PostModelCallContext {
   /** The call site this message serves — `"mainAgent"` for the user-facing reply; `null` when untagged. */
   readonly callSite: LLMCallSite | null;
   /**
-   * The finalized message content. Mutable — transform the text blocks and leave
-   * `tool_use` (and other non-text blocks) intact. Empty on a provider rejection.
+   * The finalized message content. Mutable, and the source of truth for both
+   * persistence and execution: the loop derives the turn's executable tool
+   * calls from this array *after* the hook chain runs. A hook may transform the
+   * text blocks, **append a `tool_use` block** to invoke a tool as if the model
+   * had called it (executed through the normal tool path — trust rules apply,
+   * and its result/surface is appended after any already-streamed text without
+   * discarding it), or drop a `tool_use` block to suppress a call. The host
+   * assigns an id to any appended `tool_use` block whose `id` is empty or
+   * collides. Empty on a provider rejection. Appended `tool_use` blocks are
+   * dropped on a truncated (max-tokens) turn, which short-circuits before the
+   * executor runs and so cannot pair a tool call with a result.
    */
   content: ContentBlock[];
   /**

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

@@ -115,6 +115,13 @@ export interface ContextWindowResult {
    * `context_too_large`. Omitted on the ordinary compaction path.
    */
   autoCompressApplied?: boolean;
+  /**
+   * Propagated from the compactor: the deterministic forward-cut hit the tail
+   * floor while still over the low-watermark budget. {@link _maybeCompact} reads
+   * it to stop retrying — a second pass lands on the same floor and frees
+   * nothing. See {@link CompactionRunResult.tailFloorReached}.
+   */
+  tailFloorReached?: boolean;
 }
 
 export interface ShouldCompactResult {
@@ -627,6 +634,28 @@ export class ContextWindowManager {
     return Math.floor(this.config.maxInputTokens * (1 - safetyMargin));
   }
 
+  /**
+   * Low-watermark token budget a compaction pass aims to land the rebuilt
+   * history at or below. Derived from `contextWindow.targetBudgetRatio` (the
+   * fraction of the window to retain after compaction) minus the summary's own
+   * reserve (`summaryBudgetRatio`), so the post-compaction total — summary plus
+   * verbatim tail — fits the target. Clamped meaningfully below the
+   * auto-threshold success gate: a target at or above the gate would defeat the
+   * purpose (a pass could "succeed" while landing a hair under the trigger and
+   * thrash on the next tick), so it is pulled down to at most 80% of the gate.
+   */
+  private resolveCompactionTargetTokens(thresholdTokens: number): number {
+    const { maxInputTokens, targetBudgetRatio, summaryBudgetRatio } =
+      this.config;
+    const verbatimRatio = Math.max(
+      0,
+      targetBudgetRatio - (summaryBudgetRatio ?? 0),
+    );
+    const raw = Math.floor(maxInputTokens * verbatimRatio);
+    const ceiling = Math.floor(thresholdTokens * 0.8);
+    return Math.max(1, Math.min(raw, ceiling));
+  }
+
   private async _maybeCompact(
     messages: Message[],
     signal?: AbortSignal,
@@ -642,6 +671,7 @@ export class ContextWindowManager {
     const thresholdTokens = Math.floor(
       this.config.maxInputTokens * compaction.autoThreshold,
     );
+    const targetTokens = this.resolveCompactionTargetTokens(thresholdTokens);
 
     if (!compaction.enabled) {
       return noopResult(messages, previousEstimatedInputTokens, {
@@ -681,6 +711,7 @@ export class ContextWindowManager {
       tools: this.resolveTools?.(),
       compaction,
       maxInputTokens: this.config.maxInputTokens,
+      targetTokens,
       previousEstimatedInputTokens,
       force: options?.force,
       signal,
@@ -713,6 +744,16 @@ export class ContextWindowManager {
       return { ...result, estimatedInputTokens };
     }
 
+    // The deterministic forward-cut already advanced to the tail floor (the
+    // most recent complete exchange) and still couldn't fit the budget — the
+    // verbatim tail alone is over budget (a tool-heavy in-flight turn). A
+    // second full-context pass would re-derive the same floor and free
+    // nothing, just paying another full cache write. Stop now and surface
+    // `exhausted` so reducers escalate instead of thrashing the compactor.
+    if (result.tailFloorReached) {
+      return { ...result, estimatedInputTokens, exhausted: true };
+    }
+
     // Still above the threshold after one pass — retry on the compacted
     // history, up to the remaining budget. Each retry runs against the
     // PREVIOUS attempt's output, building a tighter summary each time.
@@ -737,6 +778,9 @@ export class ContextWindowManager {
       if (estimatedInputTokens < thresholdTokens) {
         return { ...result, estimatedInputTokens };
       }
+      // Forward-cut hit the floor and still over budget — same stop condition
+      // as the first pass: another retry lands on the same floor.
+      if (nextResult.tailFloorReached) break;
       // Non-productive (compacted but didn't shrink) — stuck compactor.
       if (estimatedInputTokens >= previousEstimate) break;
       previousEstimate = estimatedInputTokens;

package/src/plugins/defaults/index.ts

@@ -44,12 +44,20 @@ import imageRecoveryPostModelCall from "./image-recovery/hooks/post-model-call.j
 import imageRecoveryStop from "./image-recovery/hooks/stop.js";
 import { resetImageRecoveryStoreForTests } from "./image-recovery/image-recovery-state-store.js";
 import imageRecoveryPkg from "./image-recovery/package.json" with { type: "json" };
+import { resetMaxTokensContinueStoreForTests } from "./max-tokens-continue/continue-state-store.js";
+import maxTokensContinuePostModelCall from "./max-tokens-continue/hooks/post-model-call.js";
+import maxTokensContinueStop from "./max-tokens-continue/hooks/stop.js";
+import maxTokensContinuePkg from "./max-tokens-continue/package.json" with { type: "json" };
 import memoryRetrievalPostCompact from "./memory-retrieval/hooks/post-compact.js";
 import memoryRetrievalUserPromptSubmit from "./memory-retrieval/hooks/user-prompt-submit.js";
 import memoryRetrievalPkg from "./memory-retrieval/package.json" with { type: "json" };
 import memoryV3PostCompact from "./memory-v3-shadow/hooks/post-compact.js";
 import memoryV3UserPromptSubmit from "./memory-v3-shadow/hooks/user-prompt-submit.js";
 import memoryV3Pkg from "./memory-v3-shadow/package.json" with { type: "json" };
+import taskProgressNudgePostToolUse, {
+  resetTaskProgressNudgeStateForTests,
+} from "./task-progress-nudge/hooks/post-tool-use.js";
+import taskProgressNudgePkg from "./task-progress-nudge/package.json" with { type: "json" };
 import titleGenerateStop from "./title-generate/hooks/stop.js";
 import titleGenerateUserPromptSubmit from "./title-generate/hooks/user-prompt-submit.js";
 import titleGeneratePkg from "./title-generate/package.json" with { type: "json" };
@@ -150,6 +158,24 @@ export const defaultImageRecoveryPlugin: Plugin = {
   },
 };
 
+/**
+ * `max-tokens-continue` — a `post-model-call` hook that auto-resumes a
+ * user-facing turn the provider truncated at its output token limit, keeping
+ * the partial output and re-querying with a continuation nudge so long
+ * generations can finish without the user clicking the continuation card.
+ * Bounded per run; the `stop` hook clears the budget on a terminal stop.
+ */
+export const defaultMaxTokensContinuePlugin: Plugin = {
+  manifest: {
+    name: maxTokensContinuePkg.name,
+    version: maxTokensContinuePkg.version,
+  },
+  hooks: {
+    "post-model-call": maxTokensContinuePostModelCall,
+    stop: maxTokensContinueStop,
+  },
+};
+
 /**
  * `memory-v3-shadow` — houses the memory-v3 shadow/live orchestration engine
  * (`memory-v3-shadow/`) and its injector. The `user-prompt-submit` /
@@ -217,6 +243,22 @@ export const defaultExplorationDriftPlugin: Plugin = {
   },
 };
 
+/**
+ * `task-progress-nudge` — a `post-tool-use` hook that nudges the model to show
+ * a `task_progress` card once an interactive turn has accumulated several
+ * tool-call rounds without one. Best-effort and once-per-turn; capable models
+ * that already show a card are never nudged.
+ */
+export const defaultTaskProgressNudgePlugin: Plugin = {
+  manifest: {
+    name: taskProgressNudgePkg.name,
+    version: taskProgressNudgePkg.version,
+  },
+  hooks: {
+    "post-tool-use": taskProgressNudgePostToolUse,
+  },
+};
+
 /**
  * `tool-result-truncate` — a `post-tool-use` hook that tail-drops an oversized
  * tool result down to a character budget derived from the model's context
@@ -243,8 +285,10 @@ function getAllDefaultPlugins(): readonly Plugin[] {
     defaultMemoryRetrievalPlugin,
     defaultToolResultTruncatePlugin,
     defaultEmptyResponsePlugin,
+    defaultMaxTokensContinuePlugin,
     defaultToolErrorPlugin,
     defaultExplorationDriftPlugin,
+    defaultTaskProgressNudgePlugin,
     defaultHistoryRepairPlugin,
     defaultImageRecoveryPlugin,
     defaultCompactionPlugin,
@@ -290,8 +334,10 @@ export function registerDefaultPlugins(): void {
 export function resetPluginRegistryAndRegisterDefaults(): void {
   resetPluginRegistryForTests();
   resetEmptyResponseNudgeStoreForTests();
+  resetMaxTokensContinueStoreForTests();
   resetRepairStateStoreForTests();
   resetImageRecoveryStoreForTests();
   resetExplorationDriftStateForTests();
+  resetTaskProgressNudgeStateForTests();
   registerDefaultPlugins();
 }

package/src/plugins/defaults/max-tokens-continue/continue-state-store.ts

@@ -0,0 +1,53 @@
+/**
+ * Per-conversation auto-continue budget for the default max-tokens-continue
+ * module.
+ *
+ * The `post-model-call` hook resumes a turn the provider truncated at its
+ * output token limit by appending a continuation nudge and asking the loop to
+ * re-query. The recovery is bounded per run: a long output legitimately spans
+ * a few continuations (each model call gets a fresh output budget), but a turn
+ * that keeps hitting the limit after several resumes is burning tokens without
+ * converging, so the hook lets it end and the continuation card surfaces for
+ * the user to drive.
+ *
+ * The two hooks split this state's lifecycle: `post-model-call` consumes a
+ * unit of budget each time it issues a continue, and the sibling `stop` hook
+ * clears the counter when the turn terminates. A conversation therefore only
+ * holds an entry while a run is in flight, and the next run starts with a
+ * full budget.
+ */
+
+/** Maximum automatic continuations per run before the turn ends terminally. */
+export const MAX_TOKENS_AUTO_CONTINUES = 3;
+
+/** Continues consumed this run, keyed by conversation. */
+const continuesUsed = new Map<string, number>();
+
+/** Whether the conversation still has auto-continue budget this run. */
+export function hasMaxTokensContinueBudget(conversationId: string): boolean {
+  return (continuesUsed.get(conversationId) ?? 0) < MAX_TOKENS_AUTO_CONTINUES;
+}
+
+/** Consume one unit of the conversation's auto-continue budget. */
+export function consumeMaxTokensContinueBudget(conversationId: string): void {
+  continuesUsed.set(
+    conversationId,
+    (continuesUsed.get(conversationId) ?? 0) + 1,
+  );
+}
+
+/**
+ * Clear the conversation's budget counter so the next run starts afresh. The
+ * sibling `stop` hook calls this when the turn terminates.
+ */
+export function clearMaxTokensContinueBudget(conversationId: string): void {
+  continuesUsed.delete(conversationId);
+}
+
+/**
+ * Test-only: drop every conversation's budget state so a suite that drives
+ * the hook directly starts each case from an empty store.
+ */
+export function resetMaxTokensContinueStoreForTests(): void {
+  continuesUsed.clear();
+}

package/src/plugins/defaults/max-tokens-continue/hooks/post-model-call.ts

@@ -0,0 +1,80 @@
+/**
+ * Default `post-model-call` hook: when the provider truncates a user-facing
+ * turn at its output token limit, resume it automatically instead of ending
+ * the turn.
+ *
+ * A `max_tokens` stop means the model had more to say — the reply (often a
+ * long generation such as a skill building an entire app) simply exceeded the
+ * profile's output budget. Without intervention the loop ends the turn and
+ * surfaces a continuation card the user must click, and a single click often
+ * just truncates again — the turn can never finish. This hook keeps the
+ * truncated turn in history, appends a continuation nudge, and sets
+ * `decision: "continue"` so the next model call resumes with a fresh output
+ * budget.
+ *
+ * Scope and bounds:
+ *
+ * - **Main-agent turns only.** Background, subagent, and compaction calls
+ *   self-manage their budgets; per the post-model-call contract the hook
+ *   gates on {@link PostModelCallContext.callSite}.
+ * - **Bounded per run.** A long output legitimately spans a few
+ *   continuations, but a turn that keeps truncating after
+ *   `MAX_TOKENS_AUTO_CONTINUES` resumes is not converging; the hook lets it
+ *   end so the continuation card surfaces for the user to drive. The sibling
+ *   `stop` hook (see `./stop.ts`) clears the budget when the turn
+ *   terminates.
+ * - **Truncation-safe content only.** The agent loop strips unsafe blocks
+ *   (truncated `tool_use` and friends) before running this hook; an entirely
+ *   empty remainder leaves nothing to resume from, so the hook lets the turn
+ *   end rather than pushing an empty assistant message the provider would
+ *   reject.
+ */
+
+import type { PluginHookFn, PostModelCallContext } from "@vellumai/plugin-api";
+
+import { isMaxTokensStopReason } from "../../../../agent/loop.js";
+import {
+  consumeMaxTokensContinueBudget,
+  hasMaxTokensContinueBudget,
+} from "../continue-state-store.js";
+
+/**
+ * Continuation nudge appended after the truncated assistant turn. Shown to
+ * the LLM, not the user — edits here affect model behavior, not end-user UX.
+ */
+export const MAX_TOKENS_CONTINUE_NUDGE_TEXT =
+  "<system_notice>Your previous response was cut off because it reached the maximum output length. Continue exactly where you stopped — do not repeat content you already sent and do not start over.</system_notice>";
+
+const postModelCall: PluginHookFn<PostModelCallContext> = async (ctx) => {
+  if (ctx.error) return;
+  if (!isMaxTokensStopReason(ctx.stopReason)) return;
+  if (ctx.callSite !== "mainAgent") return;
+  // Nothing survived truncation-block stripping — there is no partial output
+  // to resume from, so let the turn end terminally.
+  if (ctx.content.length === 0) return;
+
+  if (!hasMaxTokensContinueBudget(ctx.conversationId)) {
+    ctx.logger.warn(
+      { plugin: "max-tokens-continue", conversationId: ctx.conversationId },
+      "Turn kept hitting the output token limit — auto-continue budget exhausted, ending the turn",
+    );
+    return;
+  }
+
+  consumeMaxTokensContinueBudget(ctx.conversationId);
+  ctx.messages.push({
+    role: "assistant",
+    content: structuredClone(ctx.content),
+  });
+  ctx.messages.push({
+    role: "user",
+    content: [{ type: "text", text: MAX_TOKENS_CONTINUE_NUDGE_TEXT }],
+  });
+  ctx.decision = "continue";
+  ctx.logger.warn(
+    { plugin: "max-tokens-continue", conversationId: ctx.conversationId },
+    "Turn truncated at the output token limit — auto-continuing",
+  );
+};
+
+export default postModelCall;

package/src/plugins/defaults/max-tokens-continue/hooks/stop.ts

@@ -0,0 +1,20 @@
+/**
+ * Default `stop` hook: clears the per-conversation max-tokens auto-continue
+ * budget when a turn terminates.
+ *
+ * The `post-model-call` hook (see `./post-model-call.ts`) consumes budget each
+ * time it resumes a truncated turn. `stop` is the definitive terminal hook —
+ * it fires exactly once when the turn is truly ending — so clearing the
+ * counter here unconditionally guarantees the next run starts with a full
+ * budget, no matter how the turn ended.
+ */
+
+import type { PluginHookFn, StopContext } from "@vellumai/plugin-api";
+
+import { clearMaxTokensContinueBudget } from "../continue-state-store.js";
+
+const stop: PluginHookFn<StopContext> = async (ctx) => {
+  clearMaxTokensContinueBudget(ctx.conversationId);
+};
+
+export default stop;

package/src/plugins/defaults/max-tokens-continue/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "default-max-tokens-continue",
+  "version": "1.0.0",
+  "description": "First-party default plugin that auto-resumes a user-facing turn truncated by the provider's output token limit.",
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=20.12.0"
+  },
+  "peerDependencies": {
+    "@vellumai/plugin-api": ">=0.8.0"
+  }
+}

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

@@ -0,0 +1,37 @@
+import { describe, expect, test } from "bun:test";
+
+import { shouldRunV2Retrieval } from "../user-prompt-submit.js";
+
+/**
+ * v2 graph-memory retrieval is the deprecated path. It is gated off under
+ * `memory-v3-live` — v3 owns the injected-memory layer and runtime assembly
+ * strips any v2 `<memory>` block, so running v2's per-turn retrieval (embedding
+ * + hybrid search + the `memoryRetrieval` LLM router) would only have its
+ * result discarded. It is also skipped for untrusted actors. The
+ * conversation/abort-signal presence checks stay inline at the call site (for
+ * type narrowing) and are deliberately NOT part of this policy decision.
+ */
+describe("shouldRunV2Retrieval", () => {
+  test("runs for a trusted actor when memory-v3-live is off (v2/shadow path)", () => {
+    expect(
+      shouldRunV2Retrieval({ isTrustedActor: true, memoryV3Live: false }),
+    ).toBe(true);
+  });
+
+  test("is skipped under memory-v3-live even for a trusted actor", () => {
+    // The cutover: v3 owns memory, so v2 retrieval (and its LLM router) must
+    // not fire — this is the per-turn cost the gate removes.
+    expect(
+      shouldRunV2Retrieval({ isTrustedActor: true, memoryV3Live: true }),
+    ).toBe(false);
+  });
+
+  test("is skipped for an untrusted actor regardless of the flag", () => {
+    expect(
+      shouldRunV2Retrieval({ isTrustedActor: false, memoryV3Live: false }),
+    ).toBe(false);
+    expect(
+      shouldRunV2Retrieval({ isTrustedActor: false, memoryV3Live: true }),
+    ).toBe(false);
+  });
+});

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

@@ -32,6 +32,7 @@ import type {
   UserPromptSubmitContext,
 } from "@vellumai/plugin-api";
 
+import { isAssistantFeatureFlagEnabled } from "../../../../config/assistant-feature-flags.js";
 import { getConfig } from "../../../../config/loader.js";
 import { findConversationOrSubagent } from "../../../../daemon/conversation-registry.js";
 import {
@@ -48,6 +49,22 @@ import { broadcastMessage } from "../../../../runtime/assistant-event-hub.js";
 import type { GraphMemoryResult } from "../../../types.js";
 import { MEMORY_V3_INJECTED_BLOCK_METADATA_KEY } from "../../memory-v3-shadow/ever-injected-store.js";
 
+/**
+ * Whether to run v2 graph-memory retrieval this turn. v2 retrieval is the
+ * deprecated path: under `memory-v3-live`, v3 is the injected-memory source and
+ * runtime assembly strips any v2 `<memory>` block, so running v2's retrieval
+ * (embedding + hybrid search + the `memoryRetrieval` LLM router) only to
+ * discard the result is pure per-turn waste. Untrusted actors never run it
+ * either. The caller additionally requires the live conversation and its abort
+ * signal to be present (kept inline at the call site for type narrowing).
+ */
+export function shouldRunV2Retrieval(params: {
+  isTrustedActor: boolean;
+  memoryV3Live: boolean;
+}): boolean {
+  return params.isTrustedActor && !params.memoryV3Live;
+}
+
 /**
  * Persist and broadcast the retrieval's side effects: the injected block on
  * the user message's metadata (so it survives reloads), a recall-log row, and
@@ -250,8 +267,19 @@ const userPromptSubmitMemoryRetrieval: PluginHookFn<
     conversation?.assistantId,
   );
 
+  // v2 graph retrieval is the deprecated path: `shouldRunV2Retrieval` skips it
+  // under memory-v3-live (v3 owns the `<memory>` layer and assembly strips any
+  // v2 block) and for untrusted actors. The `conversation && abortSignal`
+  // presence checks stay inline so the block below narrows. NOTE: this removes
+  // the v2 fallback — under v3-live, a v3 empty/failed selection yields no NEW
+  // injected memory that turn (prior turns' frozen v3 cards still ride history).
+  const memoryV3Live = isAssistantFeatureFlagEnabled("memory-v3-live", config);
   let v2BlockPersisted = false;
-  if (conversation && isTrustedActor && abortSignal) {
+  if (
+    shouldRunV2Retrieval({ isTrustedActor, memoryV3Live }) &&
+    conversation &&
+    abortSignal
+  ) {
     // Retrieval progress (`memory_status`) and the `memory_recalled` summary
     // publish to the shared `broadcastMessage` hub — the sink every turn
     // publisher converges to — rather than a threaded event callback. This

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

@@ -57,6 +57,7 @@ import {
 } from "../../../../memory/memory-marker.js";
 import { migrateAddMemoryV3Selections } from "../../../../memory/migrations/268-add-memory-v3-selections.js";
 import { migrateAddMemoryV3EverInjected } from "../../../../memory/migrations/277-add-memory-v3-ever-injected.js";
+import { migrateMemoryV3SelectionsMessageIdAndSections } from "../../../../memory/migrations/283-memory-v3-selections-message-id-and-sections.js";
 import * as schema from "../../../../memory/schema.js";
 import type { PageIndexEntry } from "../../../../memory/v2/page-index.js";
 import type {
@@ -131,6 +132,7 @@ function makeDb() {
   const db = drizzle(testSqlite, { schema });
   migrateAddMemoryV3EverInjected(db);
   migrateAddMemoryV3Selections(db);
+  migrateMemoryV3SelectionsMessageIdAndSections(db);
   // Minimal `messages` shape — metadata persistence, the prune valve's
   // v3-ownership scan, and the restart rehydration read only these columns.
   testSqlite.run(/*sql*/ `
@@ -631,7 +633,10 @@ async function runTurn(
   }
 
   // Spotlight: scoped strip of the stale block (real assembly helper), then
-  // append the fresh one at the current-message tail.
+  // re-attach the fresh one. Real assembly splices it after the memory cards
+  // (after-memory-prefix); this sim appends to the tail because only the
+  // block's presence, content, placement value, and strip-and-replace are
+  // asserted here — not its exact position within the message.
   const spotlight = await memoryV3SpotlightInjector.produce(ctx);
   const stripped = stripSpotlightInjections(history);
   history.splice(0, history.length, ...stripped);
@@ -976,13 +981,13 @@ describe("memory-v3 carry integration — cache contract", () => {
 });
 
 describe("memory-v3 carry integration — spotlight contract", () => {
-  test("spotlight is present every turn, at the user tail, bounded by n × (window + 1)", () => {
+  test("spotlight is present every turn, after the memory cards, bounded by n × (window + 1)", () => {
     for (const record of records) {
       expect(record.spotlightText.startsWith("<memory_spotlight>\n")).toBe(
         true,
       );
       expect(record.spotlightText.endsWith("\n</memory_spotlight>")).toBe(true);
-      expect(record.spotlightPlacement).toBe("append-user-tail");
+      expect(record.spotlightPlacement).toBe("after-memory-prefix");
       expect(record.spotlightEntries).toBeGreaterThanOrEqual(1);
       expect(record.spotlightEntries).toBeLessThanOrEqual(
         SPOTLIGHT_N * (SPOTLIGHT_WINDOW_TURNS + 1),

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

@@ -33,6 +33,7 @@ import { drizzle } from "drizzle-orm/bun-sqlite";
 import { unwrapMemoryBlock } from "../../../../memory/memory-marker.js";
 import { migrateAddMemoryV3Selections } from "../../../../memory/migrations/268-add-memory-v3-selections.js";
 import { migrateAddMemoryV3EverInjected } from "../../../../memory/migrations/277-add-memory-v3-ever-injected.js";
+import { migrateMemoryV3SelectionsMessageIdAndSections } from "../../../../memory/migrations/283-memory-v3-selections-message-id-and-sections.js";
 import * as schema from "../../../../memory/schema.js";
 import type { InjectionBlock } from "../../../types.js";
 import type { OrchestrateResult } from "../orchestrate.js";
@@ -93,6 +94,7 @@ function makeDb() {
   migrateAddMemoryV3EverInjected(db);
   // The prune valve's recency ranking reads `memory_v3_selections`.
   migrateAddMemoryV3Selections(db);
+  migrateMemoryV3SelectionsMessageIdAndSections(db);
   // The prune valve plans only against slugs whose card sections are
   // locatable in persisted `memoryV3InjectedBlock` rows
   // (`collectPersistedV3Cards`) — minimal `messages` shape it reads.
@@ -573,13 +575,13 @@ describe("memoryV3SpotlightInjector — ephemeral section spotlight", () => {
   const sectionB = section("page-b", "Beta", "beta section text");
   const sectionC = section("page-c", "Gamma", "gamma section text");
 
-  test("renders selected finder hits' matched sections at the user tail", async () => {
+  test("renders selected finder hits' matched sections right after the memory cards", async () => {
     liveEnabled = true;
     turnResults.set(0, result(["page-a", "page-b"], [["page-a", sectionA]]));
 
     const block = await produceSpotlight("conv-1", 0);
     expect(block).not.toBeNull();
-    expect(block!.placement).toBe("append-user-tail");
+    expect(block!.placement).toBe("after-memory-prefix");
     expect(block!.text.startsWith("<memory_spotlight>\n")).toBe(true);
     expect(block!.text.endsWith("\n</memory_spotlight>")).toBe(true);
     expect(block!.text).toContain(

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

@@ -13,10 +13,12 @@
  *     by `pinned_ids`; out-of-range IDs dropped; selections deduped by slug
  *     (a page can appear as both a card and a finder line; pinned flags OR).
  *   - Omitted `ids` → keep ALL candidates (recall-safe, slug-deduped).
- *   - Explicit `ids: []` → keep none (deliberate abstention).
+ *   - Explicit `ids: []` → keep none (deliberate abstention) — a normal result.
+ *   - Empty candidate pool → keep none (nothing to select).
  *   - Finder snippets are whitespace-collapsed and truncated (~300 chars).
- *   - No provider / missing tool_use / schema mismatch / throw → keep none
- *     (degrade to deterministic lanes), the last three after a re-prompt retry.
+ *   - No provider / missing tool_use / schema mismatch / provider throw → throw
+ *     MemoryV3RetrievalUnavailableError (an INFRA failure, deliberately DISTINCT
+ *     from a deliberate empty selection), the last three after a re-prompt retry.
  *   - One forced-tool `select_pages` call on the v3 L2 call site with
  *     `disableTurnStartCache` (the tail varies per turn — the provider's
  *     auto-anchor would never hit).
@@ -61,7 +63,8 @@ mock.module("../../../../util/logger.js", () => ({
     }),
 }));
 
-const { selectPool } = await import("../pool-select.js");
+const { selectPool, MemoryV3RetrievalUnavailableError } =
+  await import("../pool-select.js");
 type SelectorPool = Parameters<typeof selectPool>[0];
 
 // ---------------------------------------------------------------------------
@@ -226,35 +229,42 @@ describe("selectPool — id mapping", () => {
 });
 
 // ---------------------------------------------------------------------------
-// selectPool — recall-safe fallbacks.
+// selectPool — infrastructure failures THROW (no silent degradation). A
+// deliberate empty selection and an empty pool (covered above) still return
+// normally; only a genuine infra failure throws so the LIVE injector can
+// hard-fail the turn instead of shipping it with no memory.
 // ---------------------------------------------------------------------------
 
-describe("selectPool — degradation on failure", () => {
-  test("no provider → no pages, without calling the provider", async () => {
+describe("selectPool — infrastructure failures throw", () => {
+  test("no provider → throws without calling the provider", async () => {
     providerStub = null;
-    const result = await selectPool(makePool(), makeTurn("x"));
-    expect(result).toEqual([]);
+    await expect(selectPool(makePool(), makeTurn("x"))).rejects.toThrow(
+      MemoryV3RetrievalUnavailableError,
+    );
     expect(providerCalls).toHaveLength(0);
   });
 
-  test("missing tool_use → no pages after retrying", async () => {
+  test("missing tool_use → throws after retrying", async () => {
     providerStub = makeProvider(noToolResponse());
-    const result = await selectPool(makePool(), makeTurn("x"));
-    expect(result).toEqual([]);
+    await expect(selectPool(makePool(), makeTurn("x"))).rejects.toThrow(
+      MemoryV3RetrievalUnavailableError,
+    );
     expect(providerCalls).toHaveLength(3);
   });
 
-  test("schema mismatch → no pages after retrying", async () => {
+  test("schema mismatch → throws after retrying", async () => {
     providerStub = makeProvider(toolUseResponse({ ids: "not-an-array" }));
-    const result = await selectPool(makePool(), makeTurn("x"));
-    expect(result).toEqual([]);
+    await expect(selectPool(makePool(), makeTurn("x"))).rejects.toThrow(
+      MemoryV3RetrievalUnavailableError,
+    );
     expect(providerCalls).toHaveLength(3);
   });
 
-  test("provider throw → no pages after retrying", async () => {
+  test("provider throw → throws after retrying", async () => {
     providerStub = makeThrowingProvider();
-    const result = await selectPool(makePool(), makeTurn("x"));
-    expect(result).toEqual([]);
+    await expect(selectPool(makePool(), makeTurn("x"))).rejects.toThrow(
+      MemoryV3RetrievalUnavailableError,
+    );
     expect(providerCalls).toHaveLength(3);
   });