@vellumai/assistant 0.8.12 → 0.9.0-staging.2

package/src/config/schema.ts

@@ -56,6 +56,7 @@ import {
   TimeoutConfigSchema,
 } from "./schemas/timeouts.js";
 import { ToolsConfigSchema } from "./schemas/tools.js";
+import { WorkflowsConfigSchema } from "./schemas/workflows.js";
 import { WorkspaceGitConfigSchema } from "./schemas/workspace-git.js";
 
 export const AssistantConfigSchema = z
@@ -121,6 +122,7 @@ export const AssistantConfigSchema = z
     ),
     ui: UiConfigSchema.default(UiConfigSchema.parse({})),
     tools: ToolsConfigSchema.default(ToolsConfigSchema.parse({})),
+    workflows: WorkflowsConfigSchema.default(WorkflowsConfigSchema.parse({})),
     // Per-plugin config blocks keyed by plugin name. The schema is intentionally
     // permissive — each plugin's manifest supplies its own validator which the
     // plugin bootstrap (`external-plugins-bootstrap.ts`) runs against the raw

package/src/config/schemas/call-site-catalog.ts

@@ -82,6 +82,13 @@ const CATALOG_RECORD: CatalogRecord = {
     description: "Handles voice call conversations.",
     domain: "agentLoop",
   },
+  workflowLeaf: {
+    id: "workflowLeaf",
+    displayName: "Workflow Leaf",
+    description:
+      "Runs an ephemeral leaf agent fanned out by the workflow orchestration engine.",
+    domain: "agentLoop",
+  },
 
   // memory
   memoryExtraction: {

package/src/config/schemas/heartbeat.ts

@@ -5,7 +5,10 @@ export const HeartbeatConfigSchema = z
   .object({
     enabled: z
       .boolean({ error: "heartbeat.enabled must be a boolean" })
-      .default(true)
+      // Heartbeats are opt-in for new workspaces. Workspaces created while
+      // the default was true keep their behavior via workspace migration
+      // 102-preserve-heartbeat-enabled-for-existing-workspaces.
+      .default(false)
       .describe("Whether periodic heartbeat checks are enabled"),
     intervalMs: z
       .number({ error: "heartbeat.intervalMs must be a number" })

package/src/config/schemas/llm.ts

@@ -13,16 +13,18 @@ import { z } from "zod";
 // Provider enum
 // ---------------------------------------------------------------------------
 
-const LLMProvider = z.enum([
-  "anthropic",
-  "openai",
-  "gemini",
-  "ollama",
-  "fireworks",
-  "openrouter",
-  "openai-compatible",
-  "minimax",
-]);
+export const LLMProvider = z
+  .enum([
+    "anthropic",
+    "openai",
+    "gemini",
+    "ollama",
+    "fireworks",
+    "openrouter",
+    "openai-compatible",
+    "minimax",
+  ])
+  .meta({ id: "LLMProvider" });
 type LLMProvider = z.infer<typeof LLMProvider>;
 
 // ---------------------------------------------------------------------------
@@ -78,6 +80,7 @@ export const LLMCallSiteEnum = z.enum([
   "trustRuleSuggestion",
   "homeGreeting",
   "homeSuggestedPrompts",
+  "workflowLeaf",
 ]);
 export type LLMCallSite = z.infer<typeof LLMCallSiteEnum>;
 
@@ -349,23 +352,27 @@ export type LLMConfigBase = z.infer<typeof LLMConfigBase>;
  * objects so callers can override individual leaves (e.g. `{ thinking:
  * { enabled: false } }`).
  */
-const LLMConfigFragment = z.object({
-  provider: LLMProvider.optional(),
-  model: ModelSchema.optional(),
-  maxTokens: MaxTokensSchema.optional(),
-  effort: EffortEnum.optional(),
-  speed: SpeedEnum.optional(),
-  verbosity: VerbosityEnum.optional(),
-  temperature: TemperatureSchema.optional(),
-  thinking: ThinkingFragmentSchema.optional(),
-  contextWindow: ContextWindowDeepPartialSchema.optional(),
-  openrouter: OpenRouterDeepPartialSchema.optional(),
-  logitBias: LogitBiasPresetSchema.optional(),
-  disableCache: z.boolean().optional(),
-});
-type LLMConfigFragment = z.infer<typeof LLMConfigFragment>;
+export const LLMConfigFragment = z
+  .object({
+    provider: LLMProvider.optional(),
+    model: ModelSchema.optional(),
+    maxTokens: MaxTokensSchema.optional(),
+    effort: EffortEnum.optional(),
+    speed: SpeedEnum.optional(),
+    verbosity: VerbosityEnum.optional(),
+    temperature: TemperatureSchema.optional(),
+    thinking: ThinkingFragmentSchema.optional(),
+    contextWindow: ContextWindowDeepPartialSchema.optional(),
+    openrouter: OpenRouterDeepPartialSchema.optional(),
+    logitBias: LogitBiasPresetSchema.optional(),
+    disableCache: z.boolean().optional(),
+  })
+  .meta({ id: "LLMConfigFragment" });
+export type LLMConfigFragment = z.infer<typeof LLMConfigFragment>;
 
-export const ProfileStatusSchema = z.enum(["active", "disabled"]);
+export const ProfileStatusSchema = z
+  .enum(["active", "disabled"])
+  .meta({ id: "ProfileStatus" });
 export type ProfileStatus = z.infer<typeof ProfileStatusSchema>;
 
 // ---------------------------------------------------------------------------

package/src/config/schemas/memory-retrospective.ts

@@ -38,6 +38,25 @@ export const MemoryRetrospectiveConfigSchema = z
       .describe(
         "Minimum milliseconds between attempts (success or failure). Prevents tight retry loops across trigger types. Pre-compaction bypasses this gate.",
       ),
+
+    keepSupersededRuns: z
+      .boolean({
+        error: "memory.retrospective.keepSupersededRuns must be a boolean",
+      })
+      .default(false)
+      .describe(
+        "When false (default), superseded retrospective conversations are deleted once a newer run succeeds — the persisted remembered_log on memory_retrospective_state is the dedup baseline (the most recent run is scanned only as a fallback for state rows that predate the log column), so older runs are dead weight (fork-based runs each carry a full copy of the source conversation's messages). Operators who want to retain the full run history set this to true; retained runs also skip the startup orphan sweep so they survive restarts.",
+      ),
+
+    matchConversationProfile: z
+      .boolean({
+        error:
+          "memory.retrospective.matchConversationProfile must be a boolean",
+      })
+      .default(false)
+      .describe(
+        "When true, fork-based retrospectives run under the source conversation's inference profile (which forkConversation copies onto the fork) instead of the call site's default. Provider prompt caches are byte-exact prefix matches scoped per model, and a thinking enable/disable mismatch invalidates the messages cache tier — so reusing the source's cached prefix requires the retrospective to resolve the SAME model/thinking/effort as the conversation's own turns. Falls back to the call site's default when the conversation has no profile or the referenced profile no longer exists.",
+      ),
   })
   .describe(
     "Controls the memory-retrospective background pass. Model selection lives under llm.callSites.memoryRetrospective.",

package/src/config/schemas/platform.ts

@@ -110,6 +110,14 @@ export const UiConfigSchema = z
       .describe(
         "IANA timezone identifier detected from the client environment for assistant temporal grounding when no manual override is configured (e.g. 'America/New_York'). Use an empty string to clear the setting.",
       ),
+    emptyStateGreetingCacheTtlMs: z
+      .number({ error: "ui.emptyStateGreetingCacheTtlMs must be a number" })
+      .int("ui.emptyStateGreetingCacheTtlMs must be an integer")
+      .min(0, "ui.emptyStateGreetingCacheTtlMs must be >= 0")
+      .default(4 * 60 * 60 * 1000)
+      .describe(
+        "Server-side cache TTL (ms) for the generated empty-state (new-chat) greeting. 0 disables caching, so a fresh greeting is generated on every request.",
+      ),
   })
   .describe(
     "User interface display settings. Empty-state greeting model selection lives under llm.callSites.emptyStateGreeting.",

package/src/config/schemas/services.ts

@@ -1,10 +1,13 @@
 import { z } from "zod";
 
+import { DEFAULT_IMAGE_MODEL } from "../../media/image-models.js";
 import { SEARCH_PROVIDER_IDS } from "../../providers/search-provider-catalog.js";
 import { SttServiceSchema } from "./stt.js";
 import { TtsServiceSchema } from "./tts.js";
 
-const ServiceModeSchema = z.enum(["managed", "your-own"]);
+export const ServiceModeSchema = z
+  .enum(["managed", "your-own"])
+  .meta({ id: "ServiceMode" });
 type ServiceMode = z.infer<typeof ServiceModeSchema>;
 
 export const VALID_INFERENCE_PROVIDERS = [
@@ -42,7 +45,7 @@ const InferenceServiceSchema = z.object({});
 
 const ImageGenerationServiceSchema = BaseServiceSchema.extend({
   provider: z.enum(VALID_IMAGE_GEN_PROVIDERS).default("gemini"),
-  model: z.string().default("gemini-3.1-flash-image-preview"),
+  model: z.string().default(DEFAULT_IMAGE_MODEL),
 });
 
 const WebSearchServiceSchema = BaseServiceSchema.extend({

package/src/config/schemas/workflows.ts

@@ -0,0 +1,42 @@
+import { z } from "zod";
+
+export const WorkflowsConfigSchema = z
+  .object({
+    maxAgentsPerRun: z
+      .number({ error: "workflows.maxAgentsPerRun must be a number" })
+      .int()
+      .positive()
+      .default(500)
+      .describe(
+        "Maximum total leaf agents a single workflow run may spawn across all steps",
+      ),
+    maxConcurrentLeaves: z
+      .number({ error: "workflows.maxConcurrentLeaves must be a number" })
+      .int()
+      .positive()
+      .default(6)
+      .describe(
+        "Maximum number of leaf agents that may run concurrently within a single workflow run",
+      ),
+    maxConcurrentRuns: z
+      .number({ error: "workflows.maxConcurrentRuns must be a number" })
+      .int()
+      .positive()
+      .default(3)
+      .describe(
+        "Maximum number of workflow runs that may execute concurrently",
+      ),
+    journalRetentionDays: z
+      .number({ error: "workflows.journalRetentionDays must be a number" })
+      .int()
+      .positive()
+      .default(30)
+      .describe(
+        "Number of days to retain workflow run journals before pruning",
+      ),
+  })
+  .describe(
+    "Workflow orchestration engine configuration — caps and concurrency knobs",
+  );
+
+export type WorkflowsConfig = z.infer<typeof WorkflowsConfigSchema>;

package/src/config/skills.ts

@@ -62,7 +62,7 @@ const SkillMetadataSchema = z
  * Origin of a skill in the merged catalog.
  *
  * - `bundled`: ships inside the assistant binary under `bundled-skills/`.
- * - `managed`: installed into `~/.vellum/workspace/skills/` from our catalog.
+ * - `managed`: installed into `$VELLUM_WORKSPACE_DIR/skills/` from our catalog.
  * - `workspace`: user-authored skill living in a conversation's working dir.
  * - `extra`: third-party directory roots passed via `loadSkillCatalog`'s
  *   `extraDirs` argument (primarily for tests).
@@ -479,7 +479,7 @@ function readSkillFromDirectory(
     if (isOutsideSkillsRoot(skillsDir, directoryPath)) {
       log.warn(
         { directoryPath },
-        "Skipping skill directory that resolves outside ~/.vellum/workspace/skills",
+        "Skipping skill directory that resolves outside $VELLUM_WORKSPACE_DIR/skills",
       );
       return null;
     }
@@ -496,7 +496,7 @@ function readSkillFromDirectory(
     if (isOutsideSkillsRoot(skillsDir, skillFilePath)) {
       log.warn(
         { skillFilePath },
-        "Skipping SKILL.md that resolves outside ~/.vellum/workspace/skills",
+        "Skipping SKILL.md that resolves outside $VELLUM_WORKSPACE_DIR/skills",
       );
       return null;
     }

package/src/context/compactor.ts

@@ -43,7 +43,10 @@ import {
 } from "../runtime/actor-trust-resolver.js";
 import { getLogger } from "../util/logger.js";
 import { stripInjectionsForCompaction } from "./strip-injections.js";
-import { estimatePromptTokens } from "./token-estimator.js";
+import {
+  estimatePromptTokens,
+  estimateToolsTokens,
+} from "./token-estimator.js";
 
 const log = getLogger("compactor");
 
@@ -134,7 +137,8 @@ Compress aggressively:
 For picking where to cut between summary and preserved tail:
 - Find the last major topic shift or energy change
 - Keep the active thread of conversation fully intact
-- When in doubt, preserve more rather than less
+- Keep the verbatim tail within roughly {tail_budget} tokens so the
+  compacted conversation has room to breathe before the next pass
 - Never cut in the middle of an ongoing discussion
 
 IMAGE MANIFEST (images in this conversation):
@@ -181,6 +185,14 @@ export interface CompactionRunArgs {
   compaction: CompactionConfig;
   /** Effective context window for the conversation (in tokens). */
   maxInputTokens: number;
+  /**
+   * Low-watermark token budget the rebuilt history (summary + verbatim tail)
+   * should land at or below after a successful pass. Drives the deterministic
+   * forward-cut that advances the model's tail choice until the estimate fits,
+   * so one pass buys a long quiet period instead of landing a hair under the
+   * trigger. When omitted the forward-cut is skipped (legacy/emergency paths).
+   */
+  targetTokens?: number;
   /** Pre-computed estimated input tokens for the live history. */
   previousEstimatedInputTokens: number;
   /** Skip the autoThreshold check — fire compaction unconditionally. */
@@ -232,6 +244,19 @@ export interface CompactionRunResult {
   reason?: string;
   /** True when the provider call threw and no compaction was applied. */
   summaryFailed?: boolean;
+  /**
+   * Set on a successful pass when the deterministic forward-cut advanced to the
+   * tail floor (the start of the most recent complete exchange) but the rebuilt
+   * history still exceeds `targetTokens`. The verbatim tail alone — the
+   * in-flight turn during a tool-heavy round — is over budget, and no boundary
+   * the cut can reach fits it. The window-manager's retry loop reads this to
+   * stop retrying immediately: a second full-context pass would land on the same
+   * floor and free nothing, just paying another full cache write. Omitted (and
+   * treated as `false`) on no-op / skipped / legacy (`targetTokens` absent)
+   * results. Internal-result-only — not persisted or emitted on any external
+   * wire payload.
+   */
+  tailFloorReached?: boolean;
 }
 
 export interface ParsedCompactionResult {
@@ -551,6 +576,113 @@ export function adjustTailIndexForToolPairing(
   return 0;
 }
 
+/**
+ * Whether keeping `messages[index..]` as the verbatim tail lands on a clean
+ * boundary: the tail must open on a user turn that does not lead with a
+ * client-side `tool_result` (which would orphan its matching `tool_use` in the
+ * summarized prefix). This is the forward-walk dual of
+ * {@link adjustTailIndexForToolPairing}'s backward walk — the deterministic
+ * budget enforcement only advances the cut to indices that satisfy it.
+ */
+function isForwardCutBoundary(messages: Message[], index: number): boolean {
+  const m = messages[index];
+  if (m == null || m.role !== "user") return false;
+  // guard:allow-tool-result-only — server-side web_search_tool_result is
+  // self-paired inside its assistant message and never spans user turns.
+  return !m.content.some((block) => block.type === "tool_result");
+}
+
+/** Outcome of the deterministic forward-cut budget enforcement. */
+interface ForwardCutOutcome {
+  /** The chosen tail index (≥ `startIndex`, ≤ `floorIndex`). */
+  index: number;
+  /**
+   * True when the cut ran out of forward boundaries — it advanced to (or could
+   * not advance past) the tail floor — yet the rebuilt-history estimate still
+   * exceeds `targetTokens`. Signals to the retry loop that a second pass cannot
+   * do better: the floor is the same and another full-context LLM pass would
+   * land on the same over-budget tail. See {@link CompactionRunResult.tailFloorReached}.
+   */
+  tailFloorReached: boolean;
+}
+
+/**
+ * Deterministic low-watermark enforcement. Given the model's tail choice
+ * (already resolved + back-walked for tool pairing), advance the cut FORWARD —
+ * dropping more leading messages into the summarized region, keeping a smaller
+ * verbatim tail — until the rebuilt-history estimate fits `targetTokens` or a
+ * minimum-tail floor is hit.
+ *
+ * The floor preserves conversational integrity: it never advances past
+ * `floorIndex`, which the caller anchors to the start of the most recent
+ * complete user→assistant exchange so the current in-flight turn is never cut.
+ * Every candidate cut must pass {@link isForwardCutBoundary} so tool pairs are
+ * never orphaned. Returns the original `startIndex` unchanged when the model's
+ * own tail already fits the budget (the cut is enforcement, not optimization)
+ * or when no forward boundary improves on it.
+ *
+ * Reports `tailFloorReached` when the cut exhausts its forward boundaries (the
+ * loop never broke early on a fit) while the best tail it found is still over
+ * `targetTokens` — the floor-dominated case where the verbatim tail (the
+ * in-flight turn during a tool-heavy round) alone exceeds the budget. The
+ * window-manager reads this to skip a futile second pass.
+ */
+function advanceTailForBudget(args: {
+  messages: Message[];
+  startIndex: number;
+  floorIndex: number;
+  targetTokens: number;
+  estimateTail: (tail: Message[]) => number;
+}): ForwardCutOutcome {
+  const { messages, startIndex, floorIndex, targetTokens, estimateTail } = args;
+  // The model's own tail choice already fits — keep it untouched. Without this
+  // early return the loop below would advance to the first forward boundary
+  // regardless (smaller tails also fit), needlessly dropping verbatim messages
+  // the budget never required us to drop.
+  if (estimateTail(messages.slice(startIndex)) <= targetTokens) {
+    return { index: startIndex, tailFloorReached: false };
+  }
+  let chosen = startIndex;
+  let fits = false;
+  for (let i = startIndex + 1; i <= floorIndex; i++) {
+    if (!isForwardCutBoundary(messages, i)) continue;
+    chosen = i;
+    const estimate = estimateTail(messages.slice(i));
+    if (estimate <= targetTokens) {
+      fits = true;
+      break;
+    }
+  }
+  return { index: chosen, tailFloorReached: !fits };
+}
+
+/**
+ * Anchor index for the forward-cut floor: the start of the most recent
+ * complete user→assistant exchange. The deterministic budget enforcement never
+ * advances the cut past this point, so a single pass always preserves at least
+ * the latest finished exchange and never bites into the current in-flight turn.
+ *
+ * Walks back from the end to the last assistant message, then back to the user
+ * message that opens its exchange (the nearest preceding clean user boundary).
+ * Falls back to the model's chosen `tailIndex` when no such exchange exists
+ * (e.g. the tail is a single in-flight turn), which makes the enforcement a
+ * no-op rather than cutting too aggressively.
+ */
+function resolveTailFloorIndex(messages: Message[], tailIndex: number): number {
+  let lastAssistant = -1;
+  for (let i = messages.length - 1; i > tailIndex; i--) {
+    if (messages[i].role === "assistant") {
+      lastAssistant = i;
+      break;
+    }
+  }
+  if (lastAssistant < 0) return tailIndex;
+  for (let i = lastAssistant - 1; i > tailIndex; i--) {
+    if (isForwardCutBoundary(messages, i)) return i;
+  }
+  return tailIndex;
+}
+
 // ---------------------------------------------------------------------------
 // Retained-image hydration
 // ---------------------------------------------------------------------------
@@ -618,12 +750,22 @@ function guessMimeFromFilename(filename: string): string {
 export function buildInstructionMessage(
   customPrompt: string | null | undefined,
   imageManifest: string,
+  tailBudgetTokens?: number,
 ): Message {
   const template =
     customPrompt && customPrompt.trim().length > 0
       ? customPrompt
       : DEFAULT_COMPACTION_PROMPT;
-  const text = template.replace("{image_manifest}", imageManifest);
+  // `{tail_budget}` is a soft nudge — the deterministic forward-cut downstream
+  // is what actually enforces the budget. Custom prompts without the
+  // placeholder render unchanged; the default prompt always carries it.
+  const tailBudgetText =
+    tailBudgetTokens != null && tailBudgetTokens > 0
+      ? String(tailBudgetTokens)
+      : "as few as needed";
+  const text = template
+    .replace("{image_manifest}", imageManifest)
+    .replace("{tail_budget}", tailBudgetText);
   return {
     role: "user",
     content: [{ type: "text", text }],
@@ -736,6 +878,7 @@ export async function runAssistantDrivenCompaction(
   const instruction = buildInstructionMessage(
     args.compaction.prompt ?? null,
     manifestText,
+    args.targetTokens,
   );
 
   const requestMessages = buildCompactionRequest(args.messages, instruction);
@@ -826,22 +969,141 @@ export async function runAssistantDrivenCompaction(
     };
   }
 
-  const tailIndex = adjustTailIndexForToolPairing(
+  const pairedTailIndex = adjustTailIndexForToolPairing(
     args.messages,
     resolvedTailIndex,
   );
-  if (tailIndex !== resolvedTailIndex) {
+  if (pairedTailIndex !== resolvedTailIndex) {
     log.info(
       {
         conversationId: args.conversationId,
         originalTailIndex: resolvedTailIndex,
-        tailIndex,
-        walkedBy: resolvedTailIndex - tailIndex,
+        tailIndex: pairedTailIndex,
+        walkedBy: resolvedTailIndex - pairedTailIndex,
       },
       "Adjusted compaction tail backward to preserve tool_use/tool_result pairing",
     );
   }
 
+  const summaryText = buildSummaryMemoryText(parsed.summary, parsed.keyState);
+  // The durable summary. When the forward-cut below advances the tail, a
+  // truncation notice is appended HERE — not just on the in-memory message —
+  // because `applyCompactionResult` persists and rehydrates the summary from
+  // the result's `summaryText`: a notice only on the message would vanish on
+  // reload/fork, silently hiding that the dropped span was never summarized.
+  let finalSummaryText = summaryText;
+  let summaryMessage: Message = {
+    role: "assistant",
+    content: [{ type: "text", text: finalSummaryText }],
+  };
+
+  const {
+    blocks: retainedImageBlocks,
+    resolved,
+    missing,
+  } = buildRetainedImageBlocks(parsed.retainedImageFilenames, manifest);
+  if (missing.length > 0) {
+    log.warn(
+      { missing },
+      "Compaction referenced images that could not be resolved against attachments — dropping",
+    );
+  }
+
+  const retainedImageMessage: Message | null =
+    retainedImageBlocks.length > 0
+      ? {
+          role: "user",
+          content: [
+            {
+              type: "text" as const,
+              text: "Images retained from the compacted portion of the conversation:",
+            },
+            ...retainedImageBlocks,
+          ],
+        }
+      : null;
+
+  // Deterministic low-watermark enforcement. The model was asked to keep the
+  // tail within the budget, but it routinely keeps a fat tail in repetitive
+  // conversations, so each pass would otherwise free almost nothing and the
+  // history bounces back over the trigger within a tick or two. When the
+  // rebuilt history (summary + retained images + verbatim tail) still exceeds
+  // `targetTokens`, advance the cut forward — onto clean user-turn boundaries
+  // only — until it fits or the most-recent-complete-exchange floor is hit.
+  // No second LLM call: the summary stays as written, and the span dropped
+  // between the model's cut and the enforced cut is acknowledged with an
+  // explicit truncation notice appended to the summary message (see below),
+  // so the loss is visible in-context rather than silent.
+  let tailIndex = pairedTailIndex;
+  // Whether the deterministic forward-cut hit the tail floor while still over
+  // `targetTokens` — propagated onto the success result so the window-manager's
+  // retry loop can skip a futile second full-context pass (the floor is the same
+  // next time, so it cannot do better). Only meaningful when a `targetTokens`
+  // budget drove the forward-cut.
+  let tailFloorReached = false;
+  if (args.targetTokens != null && pairedTailIndex > 0) {
+    const providerName =
+      args.provider.tokenEstimationProvider ?? args.provider.name;
+    // Mirror the window-manager's post-compaction estimate (system prompt +
+    // tools + messages) so the forward-cut targets the same number the manager
+    // recomputes on return — otherwise the cut would under-count by the tool
+    // budget and land short of the real low-watermark.
+    const toolTokenBudget = args.tools ? estimateToolsTokens(args.tools) : 0;
+    const fixedPrefix: Message[] = [summaryMessage];
+    if (retainedImageMessage) fixedPrefix.push(retainedImageMessage);
+    const estimateRebuilt = (tail: Message[]): number =>
+      estimatePromptTokens(
+        [...fixedPrefix, ...stripInjectionsForCompaction(tail)],
+        args.systemPrompt,
+        { providerName, toolTokenBudget },
+      );
+    const floorIndex = resolveTailFloorIndex(args.messages, pairedTailIndex);
+    const advanced = advanceTailForBudget({
+      messages: args.messages,
+      startIndex: pairedTailIndex,
+      floorIndex,
+      targetTokens: args.targetTokens,
+      estimateTail: estimateRebuilt,
+    });
+    tailFloorReached = advanced.tailFloorReached;
+    if (advanced.index !== pairedTailIndex) {
+      tailIndex = advanced.index;
+      // The LLM wrote its summary believing the verbatim tail would start at
+      // `pairedTailIndex`, so the messages in [pairedTailIndex, tailIndex) are
+      // covered by neither the summary's detail nor the retained tail. Append
+      // a deterministic truncation notice so the loss is visible in-context
+      // instead of silent — the conversation can recompute or recall what it
+      // needs rather than acting on a gap it doesn't know exists. The notice
+      // is a few dozen tokens against a multi-thousand-token target, so the
+      // budget estimate above remains effectively accurate.
+      const dropped = args.messages.slice(pairedTailIndex, tailIndex);
+      const droppedUser = dropped.filter((m) => m.role === "user").length;
+      const droppedAssistant = dropped.length - droppedUser;
+      const truncationNote =
+        `\n\n[Context budget enforcement: ${dropped.length} message(s) ` +
+        `(${droppedUser} user, ${droppedAssistant} assistant) between this ` +
+        `summary and the retained tail were truncated to fit the context ` +
+        `budget and are not covered in detail above.]`;
+      finalSummaryText = summaryText + truncationNote;
+      summaryMessage = {
+        role: "assistant",
+        content: [{ type: "text", text: finalSummaryText }],
+      };
+      log.info(
+        {
+          conversationId: args.conversationId,
+          modelTailIndex: pairedTailIndex,
+          tailIndex,
+          floorIndex,
+          droppedFromTail: dropped.length,
+          targetTokens: args.targetTokens,
+          tailFloorReached,
+        },
+        "Advanced compaction tail forward to meet low-watermark token budget",
+      );
+    }
+  }
+
   if (tailIndex === 0) {
     return {
       ...emptyResult(
@@ -876,37 +1138,8 @@ export async function runAssistantDrivenCompaction(
     args.messages.slice(tailIndex),
   );
 
-  const summaryText = buildSummaryMemoryText(parsed.summary, parsed.keyState);
-  const summaryMessage: Message = {
-    role: "assistant",
-    content: [{ type: "text", text: summaryText }],
-  };
-
-  const {
-    blocks: retainedImageBlocks,
-    resolved,
-    missing,
-  } = buildRetainedImageBlocks(parsed.retainedImageFilenames, manifest);
-  if (missing.length > 0) {
-    log.warn(
-      { missing },
-      "Compaction referenced images that could not be resolved against attachments — dropping",
-    );
-  }
-
   const compactedMessages: Message[] = [summaryMessage];
-  if (retainedImageBlocks.length > 0) {
-    compactedMessages.push({
-      role: "user",
-      content: [
-        {
-          type: "text" as const,
-          text: "Images retained from the compacted portion of the conversation:",
-        },
-        ...retainedImageBlocks,
-      ],
-    });
-  }
+  if (retainedImageMessage) compactedMessages.push(retainedImageMessage);
   compactedMessages.push(...tailMessages);
 
   const nonPersistedCompactedAway = Math.min(
@@ -928,7 +1161,7 @@ export async function runAssistantDrivenCompaction(
         ? { originalTailIndex: resolvedTailIndex }
         : {}),
       retainedImages: resolved.length,
-      summaryChars: summaryText.length,
+      summaryChars: finalSummaryText.length,
     },
     "Applied assistant-driven compaction",
   );
@@ -956,9 +1189,10 @@ export async function runAssistantDrivenCompaction(
       response.usage.cacheCreationInputTokens ?? 0,
     summaryCacheReadInputTokens: response.usage.cacheReadInputTokens ?? 0,
     summaryRawResponses: response.rawResponse ? [response.rawResponse] : [],
-    summaryText,
+    summaryText: finalSummaryText,
     keyState: parsed.keyState,
     summaryFailed: false,
+    tailFloorReached,
   };
 }