@vellumai/assistant 0.11.4 → 0.11.5-staging.1

package/src/cli/lib/__tests__/merge-plugin-tree.test.ts

@@ -440,4 +440,38 @@ describe("mergePluginTree", () => {
     expect(result.conflicts).toEqual(["f.txt"]);
     expect(result.binaryConflicts).toEqual([]);
   });
+
+  test("copies live config.json, data/, and .disabled from ours, ignoring the pin", async () => {
+    // GIVEN user-owned state on the live install and different defaults at the pin
+    writeTree(baseDir, { "package.json": '{"name":"p"}\n' });
+    writeTree(oursDir, {
+      "package.json": '{"name":"p"}\n',
+      "config.json": '{"provider":"photon","ingressMode":"live"}\n',
+      "data/cursor.json": '{"n":1}\n',
+      ".disabled": "",
+    });
+    writeTree(theirsDir, {
+      "package.json": '{"name":"p"}\n',
+      "config.json": '{"provider":"comms","ingressMode":"webhook"}\n',
+      "data/cursor.json": '{"n":0}\n',
+    });
+
+    // WHEN merged with theirs (the strategy that would otherwise take the pin)
+    const result = await mergePluginTree({
+      baseDir,
+      oursDir,
+      theirsDir,
+      destDir,
+      strategy: "theirs",
+    });
+
+    // THEN user-owned state is the live copy, not the pin, and is not counted
+    // as a merged source file
+    expect(read("config.json")).toBe(
+      '{"provider":"photon","ingressMode":"live"}\n',
+    );
+    expect(read("data/cursor.json")).toBe('{"n":1}\n');
+    expect(read(".disabled")).toBe("");
+    expect(result.fileCount).toBe(1);
+  });
 });

package/src/cli/lib/__tests__/plugin-surfaces.test.ts

@@ -17,7 +17,11 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 
-import { detectPluginSurfaces } from "../plugin-surfaces.js";
+import {
+  detectPluginSurfaces,
+  findPluginSetupSkill,
+  formatPluginSetupHint,
+} from "../plugin-surfaces.js";
 
 let pluginDir: string;
 
@@ -188,3 +192,30 @@ describe("detectPluginSurfaces", () => {
     expect(detectPluginSurfaces(pluginDir).schedules).toEqual([]);
   });
 });
+
+describe("findPluginSetupSkill", () => {
+  test("prefers the generic setup id when both conventions are present", () => {
+    expect(
+      findPluginSetupSkill("imessage", ["setup", "imessage-setup", "other"]),
+    ).toBe("setup");
+  });
+
+  test("falls back to <plugin-name>-setup", () => {
+    expect(findPluginSetupSkill("imessage", ["imessage-setup"])).toBe(
+      "imessage-setup",
+    );
+  });
+
+  test("returns undefined when the plugin ships no setup skill", () => {
+    expect(findPluginSetupSkill("imessage", ["imessage-send"])).toBeUndefined();
+    expect(findPluginSetupSkill("imessage", [])).toBeUndefined();
+  });
+});
+
+describe("formatPluginSetupHint", () => {
+  test("names the skill in the install-command copy", () => {
+    expect(formatPluginSetupHint("imessage-setup")).toBe(
+      "Load the imessage-setup skill to help set up this plugin",
+    );
+  });
+});

package/src/cli/lib/__tests__/toggle-plugin.test.ts

@@ -5,6 +5,7 @@ import {
   rmSync,
   writeFileSync,
 } from "node:fs";
+import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, beforeEach, describe, expect, it } from "bun:test";
 
@@ -18,7 +19,7 @@ import {
 
 // VELLUM_WORKSPACE_DIR is set to this; getWorkspacePluginsDir() returns
 // <workspace>/plugins, so the actual plugins directory is TMP_WS_DIR/plugins.
-const TMP_WS_DIR = join(import.meta.dir, "__tmp__toggle-plugin-test");
+const TMP_WS_DIR = join(tmpdir(), `toggle-plugin-test-${process.pid}`);
 const TMP_PLUGINS_DIR = join(TMP_WS_DIR, "plugins");
 
 beforeEach(() => {

package/src/cli/lib/__tests__/upgrade-plugin.test.ts

@@ -920,6 +920,70 @@ describe("upgradePlugin --strategy", () => {
     expect(installedFile("level-up", "local-only.txt")).toBeNull();
   });
 
+  test("keeps live config.json, data/, and .disabled under overwrite, theirs, and ours", async () => {
+    // GIVEN user-owned state on the live install, and a pin that ships defaults
+    const userConfig = '{"provider":"photon","ingressMode":"live"}\n';
+    const pinConfig = '{"provider":"comms","ingressMode":"webhook"}\n';
+    const liveOurs: Tree = {
+      ...OURS,
+      "config.json": userConfig,
+      "data/cursor.json": '{"n":1}\n',
+      ".disabled": "",
+    };
+    const pinTheirs: Tree = {
+      ...THEIRS,
+      "config.json": pinConfig,
+      "data/cursor.json": '{"n":0}\n',
+    };
+
+    for (const strategy of ["overwrite", "theirs", "ours"] as const) {
+      rmSync(join(pluginsDir, "level-up"), { recursive: true, force: true });
+      installMergeCopy("level-up", liveOurs, SHA_A, BASE);
+      const fetch = makeFetch({ manifest: manifestWith("level-up", SHA_B) });
+      const runGit = treeGitRunner({
+        [SHA_A]: BASE,
+        [SHA_B]: pinTheirs,
+      });
+
+      // WHEN the plugin is upgraded
+      const result = await upgradePlugin(
+        { name: "level-up", strategy },
+        { fetch, runGit, workspacePluginsDir: pluginsDir },
+      );
+
+      // THEN user-owned state is unchanged, including under `theirs` and
+      // overwrite, which would otherwise take the pin wholesale
+      expect(result.outcome).toBe("upgraded");
+      expect(installedFile("level-up", "config.json")).toBe(userConfig);
+      expect(installedFile("level-up", "data/cursor.json")).toBe('{"n":1}\n');
+      expect(existsSync(join(pluginsDir, "level-up", ".disabled"))).toBe(true);
+    }
+  });
+
+  test("does not seed config.json from the pin when the live install has none", async () => {
+    // GIVEN an install with no config.json, and a pin that ships defaults
+    installMergeCopy("level-up", OURS, SHA_A, BASE);
+    const fetch = makeFetch({ manifest: manifestWith("level-up", SHA_B) });
+    const runGit = treeGitRunner({
+      [SHA_A]: BASE,
+      [SHA_B]: {
+        ...THEIRS,
+        "config.json": '{"provider":"comms","ingressMode":"webhook"}\n',
+      },
+    });
+
+    // WHEN upgraded (overwrite materializes the pin tree directly)
+    const result = await upgradePlugin(
+      { name: "level-up", strategy: "overwrite" },
+      { fetch, runGit, workspacePluginsDir: pluginsDir },
+    );
+
+    // THEN the pin's config.json does not land: host-owned config is created
+    // by the plugin at runtime, not by the installer
+    expect(result.outcome).toBe("upgraded");
+    expect(installedFile("level-up", "config.json")).toBeNull();
+  });
+
   test("defaults to overwrite when no strategy is given", async () => {
     // GIVEN an install with a local-only file and an advanced pin
     installMergeCopy("level-up", OURS, SHA_A, BASE);

package/src/cli/lib/bundled-marketplace.json

@@ -292,6 +292,19 @@
       "license": "MIT",
       "icon": "🎬"
     },
+    {
+      "name": "natural",
+      "source": {
+        "source": "github",
+        "repo": "vellum-ai/natural",
+        "ref": "3cfc8c97c14df311fc64992ab8b172c1b2d64eb0"
+      },
+      "description": "Hosted MCP access to Natural payment operations for Vellum assistants.",
+      "category": "finance",
+      "homepage": "https://www.natural.com",
+      "license": "MIT",
+      "icon": "💳"
+    },
     {
       "name": "originkit",
       "source": {

package/src/cli/lib/daemon-credential-client.ts

@@ -31,6 +31,8 @@ export interface DeleteSecureKeyResult {
   result: DeleteResult;
   /** Human-readable error reason when result="error". */
   error?: string;
+  /** Daemon error code when result="error" (e.g. `CREDENTIAL_IN_USE`). */
+  code?: string;
 }
 
 // ---------------------------------------------------------------------------
@@ -104,13 +106,18 @@ export async function setSecureKeyViaDaemon(
 /**
  * Delete a secret via the daemon IPC socket. Falls back to direct
  * `deleteSecureKeyAsync()` when the daemon is not running.
+ *
+ * `force` carries the caller's confirmation past the daemon's in-use guard,
+ * which refuses a delete while an LLM provider connection resolves its auth
+ * through the credential.
  */
 export async function deleteSecureKeyViaDaemon(
   type: string,
   name: string,
+  force = false,
 ): Promise<DeleteSecureKeyResult> {
   const ipc = await cliIpcCall<{ success: boolean }>("secrets_delete", {
-    body: { type, name },
+    body: force ? { type, name, force } : { type, name },
   });
 
   if (ipc.ok && ipc.result?.success) {
@@ -122,7 +129,9 @@ export async function deleteSecureKeyViaDaemon(
     if (ipc.error.includes("not found") || ipc.error.includes("404")) {
       return { result: "not-found" };
     }
-    return { result: "error", error: ipc.error };
+    return ipc.errorCode !== undefined
+      ? { result: "error", error: ipc.error, code: ipc.errorCode }
+      : { result: "error", error: ipc.error };
   }
 
   // Daemon returned success=false
@@ -133,7 +142,20 @@ export async function deleteSecureKeyViaDaemon(
     };
   }
 
-  // Daemon unreachable — fall back to direct delete.
+  // Daemon unreachable. The in-use guard runs daemon-side, next to the
+  // provider connection records it reads, so a direct delete here would
+  // remove a credential an LLM connection depends on with no check at all.
+  // The delete is refused until the caller either starts the assistant or
+  // states the intent explicitly.
+  if (!force) {
+    return {
+      result: "error",
+      code: "IN_USE_CHECK_UNAVAILABLE",
+      error:
+        "Cannot check whether LLM provider connections depend on this credential while the assistant is not running. Start the assistant, or re-run with --force to delete without the check.",
+    };
+  }
+
   if (type === "api_key") {
     // Delete from both locations; during migration overlap both may exist.
     const credResult = await deleteSecureKeyAsync(

package/src/cli/lib/install-from-github.ts

@@ -26,7 +26,6 @@
 import { execFile } from "node:child_process";
 import {
   copyFileSync,
-  cpSync,
   existsSync,
   mkdirSync,
   readdirSync,
@@ -40,7 +39,12 @@ import { tmpdir } from "node:os";
 import { dirname, join, resolve, sep } from "node:path";
 import { promisify } from "node:util";
 
-import { PRESERVED_ENTRIES } from "../../plugins/plugin-tree-walk.js";
+import {
+  copyPreservedUserState,
+  isPluginUserStateEntry,
+  PRESERVED_ENTRIES,
+  stripPreservedUserState,
+} from "../../plugins/plugin-tree-walk.js";
 import { ensureBun } from "../../util/bun-runtime.js";
 import { getWorkspacePluginsDir } from "../../util/platform.js";
 import type { FetchLike } from "./fetch-like.js";
@@ -687,27 +691,13 @@ export async function finalizeStagedInstall(
     }
   }
 
-  // Copy preserved entries (config.json, data/, .disabled) from the existing
-  // install into the staging dir before the swap so user-owned state survives
-  // upgrades and reinstalls. Without this, the rm+rename below would destroy
-  // user config and runtime data.
+  // User-owned state (config.json, data/, .disabled) is not plugin source.
+  // Drop any copy the pin materialized into staging, then copy the live
+  // install's bytes over so an upgrade cannot reset user config to pin
+  // defaults. Without the live copy, the rm+rename below would destroy it.
+  stripPreservedUserState(stagingDir);
   if (existsSync(target)) {
-    for (const entry of PRESERVED_ENTRIES) {
-      if (entry === INSTALL_META_FILENAME) {
-        continue;
-      } // sidecar is rewritten above
-      const src = join(target, entry);
-      if (!existsSync(src)) {
-        continue;
-      }
-      const dest = join(stagingDir, entry);
-      const stat = statSync(src);
-      if (stat.isDirectory()) {
-        cpSync(src, dest, { recursive: true });
-      } else {
-        copyFileSync(src, dest);
-      }
-    }
+    copyPreservedUserState(target, stagingDir);
     rmSync(target, { recursive: true, force: true });
   }
   renameSync(stagingDir, target);
@@ -1287,7 +1277,8 @@ function pluginPostinstallEnv(bun: string): NodeJS.ProcessEnv {
 
 /**
  * Recursively copy regular files from `srcRoot` into `destDir`, skipping the
- * top-level `.git` directory, a top-level `bunfig.toml` (see below), and any
+ * top-level `.git` directory, a top-level `bunfig.toml` (see below), top-level
+ * user-state entries (`config.json`, `data/`, `.disabled`), and any
  * symlinks. Returns the file count.
  */
 function copyTreeSkippingGit(srcRoot: string, destDir: string): number {
@@ -1300,6 +1291,12 @@ function copyTreeSkippingGit(srcRoot: string, destDir: string): number {
       if (relDir === "" && entry.name === ".git") {
         continue;
       }
+      // Runtime-owned state is not plugin source. A pin that ships
+      // `config.json` or `data/` must not land in the staged tree, or an
+      // upgrade would reset user config to whatever the revision committed.
+      if (relDir === "" && isPluginUserStateEntry(entry.name)) {
+        continue;
+      }
       // Drop a top-level `bunfig.toml`. The adapter postinstall runs `bun` with
       // its cwd at the staged root, and Bun auto-loads `$cwd/bunfig.toml` as
       // project config — including a `preload` list it executes before the
@@ -1712,6 +1709,7 @@ async function copyDir(
   ref: string,
   destDir: string,
   fetchFn: FetchLike,
+  atPluginRoot = true,
 ): Promise<number> {
   const entries = await listDir(owner, repo, apiPath, ref, fetchFn);
   if (entries === null) {
@@ -1725,11 +1723,24 @@ async function copyDir(
       continue;
     }
     assertSafeFilename("entry name", entry.name);
+    // Adapter stubs overlay the plugin root. User-state names at that root
+    // are host-owned, not adapter input.
+    if (atPluginRoot && isPluginUserStateEntry(entry.name)) {
+      continue;
+    }
 
     if (entry.type === "dir") {
       const subDest = join(destDir, entry.name);
       mkdirSync(subDest, { recursive: true });
-      count += await copyDir(owner, repo, entry.path, ref, subDest, fetchFn);
+      count += await copyDir(
+        owner,
+        repo,
+        entry.path,
+        ref,
+        subDest,
+        fetchFn,
+        false,
+      );
       continue;
     }
 

package/src/cli/lib/merge-plugin-tree.ts

@@ -23,6 +23,13 @@
  * one side) is resolved here before any line merge, since `git merge-file`
  * operates on three existing blobs.
  *
+ * Runtime-owned user state (`config.json`, `data/`, `.disabled`) is never
+ * merged. Those paths are excluded from the fingerprints and copied from the
+ * live install (`ours`) into the destination after the source merge, so a
+ * pin that ships default config cannot reset user settings. The provenance
+ * sidecar is excluded on every side and rewritten by the caller after the swap.
+ *
+ *
  * Binary files cannot be line-merged, so a binary file that diverged on both
  * sides is resolved whole-file by the strategy (`ours`/`theirs`); under
  * `assistant` the local copy is kept and the path is reported as a binary
@@ -44,7 +51,10 @@ import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { promisify } from "node:util";
 
-import { PRESERVED_ENTRIES } from "../../plugins/plugin-tree-walk.js";
+import {
+  copyPreservedUserState,
+  PRESERVED_ENTRIES,
+} from "../../plugins/plugin-tree-walk.js";
 import { computeFingerprint } from "./plugin-fingerprint.js";
 
 const execFileAsync = promisify(execFile);
@@ -230,9 +240,11 @@ async function threeWayMergeFile(
 
 /**
  * Three-way merge `oursDir`/`theirsDir` against `baseDir` into `destDir` per
- * `strategy`. The provenance sidecar is excluded on every side — it is
- * rewritten by the caller after the swap and must not be carried through the
- * merge.
+ * `strategy`. User-owned state (`config.json`, `data/`, `.disabled`) is
+ * excluded from the line merge and copied from `oursDir` afterward, so the
+ * pin cannot reset it. The provenance sidecar is excluded on every side — it
+ * is rewritten by the caller after the swap and must not be carried through
+ * the merge.
  *
  * Returns the file count plus, for the `assistant` strategy, the paths left for
  * the assistant to resolve (text files with conflict markers and modify/delete
@@ -332,5 +344,11 @@ export async function mergePluginTree({
     // Present only in the base: removed on both sides, so it stays removed.
   }
 
+  // User-owned state is not plugin source, so it is never a merge input.
+  // Copy it from the live install so `--strategy theirs` cannot take a
+  // pin-shipped `config.json` (or drop an untracked one the fingerprint
+  // walk never saw).
+  copyPreservedUserState(oursDir, destDir);
+
   return { fileCount, conflicts, binaryConflicts };
 }

package/src/cli/lib/plugin-surfaces.ts

@@ -216,6 +216,33 @@ function listSchedules(schedulesDir: string): PluginScheduleSurface[] {
   );
 }
 
+/**
+ * Skill id a plugin ships for first-run setup, if any.
+ *
+ * Convention: `skills/setup/SKILL.md` or `skills/<plugin-name>-setup/SKILL.md`.
+ * The directory name is the id `skill_load` uses. `setup` wins when both exist
+ * so the generic name is the standard; `<plugin-name>-setup` covers plugins
+ * that already ship that form.
+ */
+export function findPluginSetupSkill(
+  pluginName: string,
+  skillIds: readonly string[],
+): string | undefined {
+  if (skillIds.includes("setup")) {
+    return "setup";
+  }
+  const named = `${pluginName}-setup`;
+  if (skillIds.includes(named)) {
+    return named;
+  }
+  return undefined;
+}
+
+/** Install-command copy pointing at a plugin's setup skill. */
+export function formatPluginSetupHint(skillId: string): string {
+  return `Load the ${skillId} skill to help set up this plugin`;
+}
+
 /**
  * Detect the {@link PluginSurfaces} an installed plugin contributes by walking
  * its install tree at `pluginDir`. Surface types with no contributions come

package/src/config/feature-flag-registry.json

@@ -92,14 +92,6 @@
       "description": "Enable the Quick Input popover on right-click of the menu bar icon",
       "defaultEnabled": false
     },
-    {
-      "id": "companion-surface",
-      "scope": "client",
-      "key": "companion-surface",
-      "label": "Companion Surface",
-      "description": "Show the macOS companion surface: the floating avatar that carries Talk, Type and the running call, and its tray item. Read in the Electron main process, which decides whether the window opens at all",
-      "defaultEnabled": false
-    },
     {
       "id": "expand-completed-steps",
       "scope": "client",
@@ -108,14 +100,6 @@
       "description": "Auto-expand completed tool call step groups instead of showing them collapsed",
       "defaultEnabled": false
     },
-    {
-      "id": "collapse-assistant-intermediates",
-      "scope": "client",
-      "key": "collapse-assistant-intermediates",
-      "label": "Collapse Assistant Intermediates",
-      "description": "Collapse completed intermediary assistant activity behind Earlier activity while keeping the final response visible",
-      "defaultEnabled": false
-    },
     {
       "id": "backward-releases",
       "scope": "assistant",
@@ -152,8 +136,16 @@
       "id": "fork-from-message",
       "scope": "client",
       "key": "fork-from-message",
-      "label": "Fork from Message",
-      "description": "Show the 'Fork from here' option in message overflow menus",
+      "label": "Internal Thread Actions (legacy key)",
+      "description": "Legacy key for `internal-thread-actions`. The client grants the internal thread affordances when either key is enabled, so the platform may serve the gate under either name. Declared here so the flag mapper keeps the value instead of dropping it as undeclared.",
+      "defaultEnabled": false
+    },
+    {
+      "id": "internal-thread-actions",
+      "scope": "client",
+      "key": "internal-thread-actions",
+      "label": "Internal Thread Actions",
+      "description": "Show the internal thread affordances: 'Fork from here' on messages, 'Fork Conversation', 'Analyze Conversation', and 'Copy conversation ID' in the thread menu, plus the LLM inspector surfaces. The flag is the sole gate: any session that enables it gets the affordances, including local sessions with no platform identity.",
       "defaultEnabled": false
     },
     {
@@ -244,6 +236,14 @@
       "description": "Show the pair-a-device card in web settings. Visibility only; pairing itself is always available.",
       "defaultEnabled": false
     },
+    {
+      "id": "paired-devices-ui",
+      "scope": "client",
+      "key": "paired-devices-ui",
+      "label": "Paired Devices UI",
+      "description": "Show the paired-devices list and revoke controls inside the pair-a-device settings card. Visibility only; `vellum devices` on the host stays available.",
+      "defaultEnabled": false
+    },
     {
       "id": "settings-sleep-policy",
       "scope": "assistant",
@@ -356,13 +356,21 @@
       "description": "Gates whether a `chat.assistant_reply` push is suppressed while a Mac desktop client reports itself attended. On by default; turn it off to restore unconditional reply pushes.",
       "defaultEnabled": true
     },
+    {
+      "id": "web-presence-suppression",
+      "scope": "assistant",
+      "key": "web-presence-suppression",
+      "label": "Web Presence Suppression",
+      "description": "Gates whether a `chat.assistant_reply` push is suppressed while a browser tab reports itself visible on that conversation. On by default; turn it off to restore unconditional reply pushes for web-visible conversations.",
+      "defaultEnabled": true
+    },
     {
       "id": "plugin-schedules",
       "scope": "assistant",
       "key": "plugin-schedules",
       "label": "Plugin Schedules",
       "description": "Plugins declare recurring schedules as files that register and run automatically",
-      "defaultEnabled": false
+      "defaultEnabled": true
     },
     {
       "id": "experiment-balanced-model-2026-08-06",
@@ -372,6 +380,14 @@
       "description": "Multivariate experiment on the model the managed Balanced inference profile resolves to. control = gpt-5.6-luna (the shipped pin); terra = gpt-5.6-terra; glm-5p2 = accounts/fireworks/models/glm-5p2. Only the managed (vellum) implementation moves: ChatGPT-subscription and BYOK installs run the provider the user chose and are outside the experiment. Rollout and targeting are managed in the LaunchDarkly dashboard; any value that is not an arm name resolves to control.",
       "defaultEnabled": "control",
       "values": ["control", "terra", "glm-5p2"]
+    },
+    {
+      "id": "obscure-credits",
+      "scope": "client",
+      "key": "obscure-credits",
+      "label": "Obscure Credits",
+      "description": "Replaces the dollar amounts on the billing Plan section with a usage-relative view: the current-plan tile trades its price footer for a Usage Balance bar (managed spend this billing cycle against the package's included credits) and the credits spec chip reads \"<Package> usage, reset monthly\" instead of naming a dollar bundle. Spec chips wrap horizontally to fit the shorter labels. Off leaves the Plan section exactly as it ships today.",
+      "defaultEnabled": false
     }
   ]
 }

package/src/config/webhook-routing.ts

@@ -83,6 +83,14 @@ function isIngressExplicitlyDisabled(): boolean {
  *
  * `allowManagedCallbacks` gates both platform tiers: channels that can only be
  * served by a self-hosted ingress pass `false` and never see them.
+ *
+ * The gateway's Telegram webhook reconciler implements this same resolution
+ * order when deciding what URL to hand Telegram's setWebhook
+ * (`resolveExpectedTelegramWebhookUrl` in
+ * `gateway/src/telegram/webhook-manager.ts`). The two must stay in agreement:
+ * a tier this derivation reports as configured but the reconciler declines
+ * leaves Telegram setup reporting success while no webhook is ever
+ * registered. Change the tiers in both places or not at all.
  */
 export async function hasWebhookRoutingConfigured(
   allowManagedCallbacks = false,

package/src/context/compactor.ts

@@ -39,6 +39,10 @@ import type {
 } from "../providers/types.js";
 import { type TrustClass } from "../runtime/actor-trust-resolver.js";
 import { resolveCapabilities } from "../runtime/capabilities.js";
+import {
+  hasValidJpegStructure,
+  sniffImageMimeType,
+} from "../util/image-conversion.js";
 import { getLogger } from "../util/logger.js";
 import { preModelCallSanitize } from "./outbound-sanitize.js";
 import { stripInjectionsForCompaction } from "./strip-injections.js";
@@ -865,7 +869,8 @@ function resolveTailFloorIndex(messages: Message[], tailIndex: number): number {
 // Retained-image hydration
 // ---------------------------------------------------------------------------
 
-async function buildRetainedImageBlocks(
+/** Exported for unit testing (the corrupt-bytes drop gate). */
+export async function buildRetainedImageBlocks(
   filenames: string[],
   manifest: ManifestEntry[],
 ): Promise<{ blocks: ImageContent[]; resolved: string[]; missing: string[] }> {
@@ -883,7 +888,11 @@ async function buildRetainedImageBlocks(
       missing.push(name);
       continue;
     }
-    const sourceMime = guessMimeFromFilename(name);
+    // Sniff the declared MIME from the stored bytes rather than the filename:
+    // clients derive extensions from user input, and providers reject an image
+    // whose bytes disagree with the declared media type.
+    const sourceMime =
+      sniffImageMimeType(content) ?? guessMimeFromFilename(name);
     // Run the same downscale pass the agent uses when first sending an
     // image. Without this, attachments that exceed the provider's per-image
     // byte limit (Anthropic: 5 MB) crash the next turn after compaction.
@@ -891,6 +900,26 @@ async function buildRetainedImageBlocks(
       content.toString("base64"),
       sourceMime,
     );
+    // Last-line gate before the bytes are baked into the rebuilt history: a
+    // corrupt payload would be rejected by the provider with a 400 on EVERY
+    // subsequent turn, wedging the conversation. Dropping the image loses a
+    // retained picture; shipping it loses the conversation. Format sniffing
+    // alone is not enough for JPEG: a truncated JPEG (e.g. persisted from a
+    // torn conversion-cache read) keeps its SOI header, so JPEG payloads must
+    // also walk to a terminal EOI marker.
+    const optimizedBytes = Buffer.from(optimized.data, "base64");
+    const optimizedFormat = sniffImageMimeType(optimizedBytes);
+    const bytesAreValidImage =
+      optimizedFormat != null &&
+      (optimizedFormat !== "image/jpeg" ||
+        hasValidJpegStructure(optimizedBytes));
+    if (!bytesAreValidImage) {
+      log.warn(
+        { filename: name, attachmentId: entry.attachmentId },
+        "Retained image bytes are not a valid image after transport optimization; dropping",
+      );
+      continue;
+    }
     blocks.push({
       type: "image",
       source: {