diff --git a/.changeset/clean-staged-media.md b/.changeset/clean-staged-media.md
new file mode 100644
index 00000000000..375c6eff13a
--- /dev/null
+++ b/.changeset/clean-staged-media.md
@@ -0,0 +1,5 @@
+---
+"@moonshot-ai/kimi-code": patch
+---
+
+Keep pasted image and video attachments available in session history, and clean up temporary uploads automatically.
diff --git a/.changeset/daemon-file-ref-drop-path.md b/.changeset/daemon-file-ref-drop-path.md
new file mode 100644
index 00000000000..6f23742ef9c
--- /dev/null
+++ b/.changeset/daemon-file-ref-drop-path.md
@@ -0,0 +1,5 @@
+---
+"@moonshot-ai/kimi-code-sdk": minor
+---
+
+Daemon file references no longer persist a materialization path: the daemon-file URL builder takes only a file id, and the parsed reference no longer carries a `path` field. The display path is derived from the session media store at read time, so a session fork or home relocation can no longer stale a persisted reference. Urls with a legacy `?path=` query still parse.
diff --git a/.changeset/sdk-upload-file.md b/.changeset/sdk-upload-file.md
new file mode 100644
index 00000000000..c00f4dd97ca
--- /dev/null
+++ b/.changeset/sdk-upload-file.md
@@ -0,0 +1,5 @@
+---
+"@moonshot-ai/kimi-code-sdk": minor
+---
+
+Add `uploadFile` for uploading media to the engine's file store and referencing it from prompts, plus an optional `promptId` on prompt submissions for correlating them with turn-started events. Both require the v2 harness.
diff --git a/apps/kimi-code/src/tui/components/editor/custom-editor.ts b/apps/kimi-code/src/tui/components/editor/custom-editor.ts
index 21a272ef426..2a280209325 100644
--- a/apps/kimi-code/src/tui/components/editor/custom-editor.ts
+++ b/apps/kimi-code/src/tui/components/editor/custom-editor.ts
@@ -155,13 +155,16 @@ export class CustomEditor extends Editor {
    * Alt-V on Windows — Ctrl-V is terminal-reserved there). Return
    * `true` to consume the key (image was read and handled); return
    * `false` to let the key fall through to the normal paste path.
-   * The callback may be async; pi-tui awaits it before dispatching
-   * the next keystroke.
+   * The callback may be async; CustomEditor queues subsequent keystrokes until
+   * it settles before dispatching them.
    */
   public onPasteImage?: () => Promise<boolean>;
 
   private consumingPaste = false;
   private consumeBuffer = '';
+  /** Serialize paste callbacks so Enter/typing cannot overtake an image paste. */
+  private pasteInFlight = false;
+  private readonly pasteInputQueue: string[] = [];
   private argumentHints: ReadonlyMap<string, string> = new Map();
   private skillCommandNames: ReadonlySet<string> = new Set();
 
@@ -363,6 +366,16 @@ export class CustomEditor extends Editor {
       return;
     }
 
+    // Clipboard reads are asynchronous. Queue every key received while a
+    // paste callback is in flight and replay it once the callback settles
+    // (clipboard read + placeholder insert — compression and the daemon
+    // upload continue in the background off this path), so Enter cannot
+    // submit a draft that is still missing the pasted image.
+    if (this.pasteInFlight) {
+      this.pasteInputQueue.push(normalized);
+      return;
+    }
+
     // Any input other than a lone Escape breaks a pending double-Esc sequence,
     // so the shortcut only fires for two consecutive Escape presses.
     if (!matchesKey(normalized, Key.escape)) {
@@ -406,17 +419,21 @@ export class CustomEditor extends Editor {
           this.onTextPaste?.();
           super.handleInput.call(this, normalized);
         };
-        void handler().then(
-          (handled) => {
+        this.pasteInFlight = true;
+        void handler()
+          .then((handled) => {
             if (!handled) pasteAsText();
-          },
-          () => {
+          })
+          .catch(() => {
             // A rejecting image-paste handler must not leak an unhandled
             // rejection (the CLI turns those into a silent exit) — treat it
             // the same as "no image available" and fall back to text paste.
             pasteAsText();
-          },
-        );
+          })
+          .finally(() => {
+            this.pasteInFlight = false;
+            this.flushPasteInputQueue();
+          });
         return;
       }
     }
@@ -541,6 +558,14 @@ export class CustomEditor extends Editor {
     this.reopenAutocompleteAfterInput();
   }
 
+  private flushPasteInputQueue(): void {
+    if (this.pasteInFlight) return;
+    const next = this.pasteInputQueue.shift();
+    if (next === undefined) return;
+    this.handleInput(next);
+    if (!this.pasteInFlight) this.flushPasteInputQueue();
+  }
+
   private reopenAutocompleteAfterInput(): void {
     if (this.isShowingAutocomplete()) return;
     const { line, col } = this.getCursor();
diff --git a/apps/kimi-code/src/tui/constant/media.ts b/apps/kimi-code/src/tui/constant/media.ts
new file mode 100644
index 00000000000..d125258a913
--- /dev/null
+++ b/apps/kimi-code/src/tui/constant/media.ts
@@ -0,0 +1,6 @@
+/** TUI-only daemon staging lifetimes for pasted media. */
+
+export const IMAGE_STAGING_TTL_SECONDS = 60 * 60;
+export const IMAGE_FILE_REF_MIN_REMAINING_MS = 60_000;
+/** How long submit waits for a just-pasted image's background ingestion before falling back to the inline form. */
+export const IMAGE_INGESTION_SUBMIT_WAIT_MS = 2_000;
diff --git a/apps/kimi-code/src/tui/controllers/cache-hint-controller.ts b/apps/kimi-code/src/tui/controllers/cache-hint-controller.ts
index 6926baa7551..532f291a56c 100644
--- a/apps/kimi-code/src/tui/controllers/cache-hint-controller.ts
+++ b/apps/kimi-code/src/tui/controllers/cache-hint-controller.ts
@@ -21,13 +21,18 @@ import type { AppState, InlineSkillActivation } from '../types';
 import type { TUIState } from '../tui-state';
 import { evaluateCacheHint } from '../utils/cache-hint';
 import { formatErrorMessage } from '../utils/event-payload';
-import type { ExtractionResult } from '../utils/image-placeholder';
+import {
+  makeExtractionResendable,
+  type ExtractionResult,
+} from '../utils/image-placeholder';
 
 /** A swallowed submit: the raw text plus its media extraction (done before
  *  the dialog so pasted attachments survive a later store clear). */
 interface StashedSubmit {
   readonly text: string;
   readonly extraction?: ExtractionResult;
+  /** Session that owned any daemon refs inside {@link extraction}. */
+  readonly sessionId: string;
   readonly inlineSkillActivations?: readonly InlineSkillActivation[];
 }
 
@@ -41,6 +46,12 @@ export interface CacheHintHost {
   mountEditorReplacement(panel: Component & Focusable): void;
   restoreEditor(): void;
   restoreInputText(text: string): void;
+  /**
+   * A stashed submission going back to the editor releases its extraction's
+   * staged media with queue-recall semantics (consume retains, retire staged
+   * copies, rebase videos) — without this the retains/copies would leak.
+   */
+  recallStashedMedia(text: string, extraction: ExtractionResult | undefined): void;
   showError(message: string): void;
   createNewSession(): Promise<void>;
   sendNormalUserInput(text: string, preExtracted?: ExtractionResult): Promise<void>;
@@ -263,7 +274,7 @@ export class CacheHintController {
     // Coarse floor: configured cache durations are 10min+, so anything
     // fresher than a minute can never hint.
     if (Date.now() - this.lastActivityAt < 60_000) return false;
-    const stash: StashedSubmit = { text, extraction, inlineSkillActivations };
+    const stash: StashedSubmit = { text, extraction, sessionId: host.session.id, inlineSkillActivations };
     const cached = peekCacheHintConfig();
     if (cached !== undefined) {
       const decision = evaluateCacheHint({
@@ -305,7 +316,7 @@ export class CacheHintController {
     // would reorder the conversation.
     if (this.idlePrompted) {
       if (this.lastDialogRestored) {
-        this.restoreStashedInput(stash.text);
+        this.restoreStashedInput(stash);
       } else {
         await this.releaseStashed(stash);
       }
@@ -316,7 +327,7 @@ export class CacheHintController {
     // meanwhile, never send the stashed text into the wrong session — hand it
     // back to the editor instead.
     if (host.session?.id !== sessionId) {
-      this.restoreStashedInput(stash.text);
+      this.restoreStashedInput(stash);
       return;
     }
     // If a foreground operation (turn, /compact, …) started meanwhile, don't
@@ -359,23 +370,27 @@ export class CacheHintController {
   }
 
   private async releaseToSendPath(stash: StashedSubmit): Promise<void> {
+    const extraction =
+      stash.extraction !== undefined && this.host.state.appState.sessionId !== stash.sessionId
+        ? makeExtractionResendable(stash.extraction)
+        : stash.extraction;
     if (stash.inlineSkillActivations !== undefined && stash.inlineSkillActivations.length > 0) {
-      await this.host.sendInlineSkillUserInput(
-        stash.text,
-        stash.inlineSkillActivations,
-        stash.extraction,
-      );
+      await this.host.sendInlineSkillUserInput(stash.text, stash.inlineSkillActivations, extraction);
       return;
     }
-    await this.host.sendNormalUserInput(stash.text, stash.extraction);
+    await this.host.sendNormalUserInput(stash.text, extraction);
   }
 
   /** Restore a stashed input to the editor, appending to anything already
-   *  restored this cycle so earlier text is not overwritten. */
-  private restoreStashedInput(text: string | undefined): void {
-    if (text === undefined) return;
-    this.restoredTexts.push(text);
+   *  restored this cycle so earlier text is not overwritten, and release the
+   *  stash's staged media with recall semantics — the restored draft still
+   *  references its attachments, so retains are consumed (the next submit
+   *  re-retains) and staged copies retire instead of leaking. */
+  private restoreStashedInput(stash: StashedSubmit | undefined): void {
+    if (stash === undefined) return;
+    this.restoredTexts.push(stash.text);
     this.host.restoreInputText(this.restoredTexts.join('\n'));
+    this.host.recallStashedMedia(stash.text, stash.extraction);
   }
 
   private upstreamModelId(): string | undefined {
@@ -441,7 +456,7 @@ export class CacheHintController {
     const { host } = this;
     const restoreInput = () => {
       this.lastDialogRestored = true;
-      this.restoreStashedInput(stashed?.text);
+      this.restoreStashedInput(stashed);
     };
     switch (action) {
       case 'dismiss':
@@ -492,7 +507,7 @@ export class CacheHintController {
         break;
     }
     this.lastDialogRestored = false;
-    if (stashed !== undefined) await this.releaseToSendPath(stashed);
+    if (stashed !== undefined) await this.releaseStashed(stashed);
   }
 
   /** Bounded wait for the engine to flip `isCompacting` after a compact RPC. */
diff --git a/apps/kimi-code/src/tui/controllers/editor-keyboard.ts b/apps/kimi-code/src/tui/controllers/editor-keyboard.ts
index 962065ca99e..0e071e3d9fe 100644
--- a/apps/kimi-code/src/tui/controllers/editor-keyboard.ts
+++ b/apps/kimi-code/src/tui/controllers/editor-keyboard.ts
@@ -1,4 +1,6 @@
-import type { KimiHarness, Session } from '@moonshot-ai/kimi-code-sdk';
+import { unlink } from 'node:fs/promises';
+
+import type { FileMeta, KimiHarness, Session } from '@moonshot-ai/kimi-code-sdk';
 import { compressImageForModel, persistOriginalImage, sessionMediaOriginalsDir } from '@moonshot-ai/kimi-code-sdk';
 
 import { ClipboardMediaError, readClipboardMedia } from '#/utils/clipboard/clipboard-image';
@@ -13,9 +15,10 @@ import {
   LLM_NOT_SET_MESSAGE,
   NO_ACTIVE_SESSION_MESSAGE,
 } from '../constant/kimi-tui';
+import { IMAGE_STAGING_TTL_SECONDS } from '../constant/media';
 import { formatErrorMessage } from '../utils/event-payload';
-import type { ImageAttachmentStore } from '../utils/image-attachment-store';
-import { extractMediaAttachments } from '../utils/image-placeholder';
+import type { ImageAttachment, ImageAttachmentStore } from '../utils/image-attachment-store';
+import { extractMediaAttachments, imageExtensionForMime } from '../utils/image-placeholder';
 import { extractInlineSkillActivations } from '../utils/inline-skill-tokens';
 import type { PendingExit, QueuedMessage, SteerInputItem } from '../types';
 import type { TUIState } from '../tui-state';
@@ -24,6 +27,11 @@ import type { BtwPanelController } from './btw-panel';
 export interface EditorKeyboardHost {
   state: TUIState;
   session: Session | undefined;
+  /**
+   * True when the TUI runs on the agent-core-v2 engine (startup-selected).
+   * Gates the paste-time upload to the daemon file store; the v1 engine has
+   * no file store and keeps the submit-time inline base64 form.
+   */
   readonly engineV2: boolean;
   cancelInFlight: (() => void) | undefined;
   /**
@@ -43,6 +51,7 @@ export interface EditorKeyboardHost {
     imageAttachmentIds: readonly number[];
     videoAttachmentIds: readonly number[];
   }): boolean;
+  releaseStagingMedia(imageAttachmentIds: readonly number[], paths: readonly string[]): void;
   recallLastQueued(): QueuedMessage | undefined;
   showError(msg: string): void;
   track(event: string, props?: Record<string, unknown>): void;
@@ -334,12 +343,21 @@ export class EditorKeyboardController {
         if (trimmed.length > 0) {
           // Queued items carry the parts extracted when they were submitted
           // (and were already capability-validated then).
-          textRun.push({ text: trimmed, parts: m.parts, imageAttachmentIds: m.imageAttachmentIds });
+          textRun.push({
+            text: trimmed,
+            parts: m.parts,
+            imageAttachmentIds: m.imageAttachmentIds,
+            stagingPaths: m.stagingPaths,
+          });
         }
       }
       let editorExtraction: ReturnType<typeof extractMediaAttachments> | undefined;
       if (!editorIsBash && text.length > 0 && !editorHasInlineSkills && firstBundle === -1) {
         try {
+          // Synchronous path: an image still ingesting in the background
+          // extracts to its inline fallback here (no bounded wait like
+          // `sendNormalUserInput` — this handler cannot await without
+          // interleaving queue/draft edits).
           editorExtraction = extractMediaAttachments(text, this.imageStore);
         } catch (error) {
           // Cache copy failed (e.g. the pasted video's source vanished) —
@@ -354,6 +372,7 @@ export class EditorKeyboardController {
             editorExtraction.imageAttachmentIds.length > 0
               ? editorExtraction.imageAttachmentIds
               : undefined,
+          stagingPaths: editorExtraction.stagingPaths,
         });
       }
       flushTextRun();
@@ -366,22 +385,30 @@ export class EditorKeyboardController {
           editorExtraction !== undefined &&
           !host.validateMediaCapabilities(editorExtraction)
         ) {
+          host.releaseStagingMedia(
+            editorExtraction.imageAttachmentIds,
+            editorExtraction.stagingPaths,
+          );
+          return;
+        }
+        const session = host.session;
+        if (host.state.appState.model.trim().length === 0 || session === undefined) {
+          host.releaseStagingMedia(
+            editorExtraction?.imageAttachmentIds ?? [],
+            editorExtraction?.stagingPaths ?? [],
+          );
+          host.showError(LLM_NOT_SET_MESSAGE);
           return;
         }
         host.state.queuedMessages = queued.filter(
           (m, index) => m.mode === 'bash' || (firstBundle !== -1 && index >= firstBundle),
         );
         if (!editorIsBash && !editorHasInlineSkills && firstBundle === -1) editor.setText('');
-        const session = host.session;
-        if (host.state.appState.model.trim().length === 0 || session === undefined) {
-          host.showError(LLM_NOT_SET_MESSAGE);
-        } else {
-          for (const run of runs) {
-            if (run.kind === 'text') {
-              host.steerMessage(session, run.items);
-            } else {
-              host.steerSkillActivation(session, run.skillName, run.skillArgs);
-            }
+        for (const run of runs) {
+          if (run.kind === 'text') {
+            host.steerMessage(session, run.items);
+          } else {
+            host.steerSkillActivation(session, run.skillName, run.skillArgs);
           }
         }
       }
@@ -524,6 +551,45 @@ export class EditorKeyboardController {
 
     const meta = parseImageMeta(media.bytes);
     if (meta === null) return false;
+
+    // Register the attachment and put its placeholder in the editor before
+    // any of the asynchronous ingestion work below. CustomEditor only holds
+    // keystrokes until this handler settles, so the callback returns right
+    // after the placeholder lands and ingestion continues in the background —
+    // typing never waits on compression or the daemon upload. Submit gives a
+    // pending ingestion a bounded wait (`pendingImageIngestions`) and falls
+    // back to the inline form when it has not finished.
+    const attachment = this.imageStore.addImage(
+      media.bytes,
+      meta.mime,
+      meta.width,
+      meta.height,
+    );
+    this.host.state.editor.insertTextAtCursor?.(`${attachment.placeholder} `);
+    this.host.state.ui.requestRender();
+    this.host.track('shortcut_paste', { kind: 'image' });
+
+    attachment.pending = this.finishClipboardImagePaste(
+      attachment,
+      media.bytes,
+      meta.mime,
+      meta.width,
+      meta.height,
+    ).catch((error: unknown) => {
+      // The raw attachment and its already-visible placeholder are still a
+      // valid inline fallback when optional ingestion work fails.
+      this.host.showError(`Failed to process pasted image: ${formatErrorMessage(error)}`);
+    });
+    return true;
+  }
+
+  private async finishClipboardImagePaste(
+    attachment: ImageAttachment,
+    originalBytes: Uint8Array,
+    originalMime: string,
+    originalWidth: number,
+    originalHeight: number,
+  ): Promise<void> {
     // Compress at ingestion — a pure data step while building the attachment, so
     // the stored bytes, the inline thumbnail, the `[image #N (W×H)]` placeholder,
     // and the submitted image all agree, and the agent core only ever sees an
@@ -535,7 +601,7 @@ export class EditorKeyboardController {
     // The edge cap comes from the host harness's [image] config (resolved per
     // paste so a config reload applies immediately); hosts without a harness
     // use the env/built-in default.
-    const compressed = await compressImageForModel(media.bytes, meta.mime, {
+    const compressed = await compressImageForModel(originalBytes, originalMime, {
       maxEdge: this.host.harness?.imageLimits?.maxEdgePx(),
       telemetry: {
         client: {
@@ -550,34 +616,71 @@ export class EditorKeyboardController {
     // compressor reports display space (EXIF orientation applied) — the space
     // the sent image, the caption, and ReadMediaFile region readback share —
     // while parseImageMeta reads the raw pre-rotation header.
-    const attachment = compressed.changed
-      ? this.imageStore.addImage(
-          compressed.data,
-          compressed.mimeType,
-          compressed.width,
-          compressed.height,
-          {
-            path: await persistOriginalImage(
-              media.bytes,
-              meta.mime,
-              sessionDir === undefined ? {} : { dir: sessionMediaOriginalsDir(sessionDir) },
-            ),
-            width: compressed.originalWidth,
-            height: compressed.originalHeight,
-            byteLength: media.bytes.length,
-            mime: meta.mime,
-          },
-        )
-      : this.imageStore.addImage(
-          media.bytes,
-          meta.mime,
-          compressed.width || meta.width,
-          compressed.height || meta.height,
-        );
-    this.host.state.editor.insertTextAtCursor?.(`${attachment.placeholder} `);
+    // Persist the original BEFORE minting a daemon upload: when persistence
+    // fails the whole ingestion is abandoned, and an upload minted earlier
+    // would be orphaned (never attached, never deleted).
+    const original = compressed.changed
+      ? {
+          path: await persistOriginalImage(
+            originalBytes,
+            originalMime,
+            sessionDir === undefined ? {} : { dir: sessionMediaOriginalsDir(sessionDir) },
+          ),
+          width: compressed.originalWidth,
+          height: compressed.originalHeight,
+          byteLength: originalBytes.length,
+          mime: originalMime,
+        }
+      : undefined;
+    // v2 only: upload the final bytes to the daemon file store so submit-time
+    // expansion emits a `kimi-file://` reference instead of inline base64.
+    const uploaded = await this.uploadImageToDaemonFileStore(
+      compressed.changed ? compressed.data : originalBytes,
+      compressed.changed ? compressed.mimeType : originalMime,
+    );
+    const completed = this.imageStore.completeImage(attachment, {
+      bytes: compressed.changed ? compressed.data : originalBytes,
+      mime: compressed.changed ? compressed.mimeType : originalMime,
+      width: compressed.width || originalWidth,
+      height: compressed.height || originalHeight,
+      original,
+      fileId: uploaded?.id,
+      fileExpiresAt: parseExpiry(uploaded),
+    });
+    if (completed === undefined && uploaded !== undefined) {
+      await this.host.harness?.deleteFile(uploaded.id).catch(() => undefined);
+    }
+    if (completed === undefined && original !== undefined && original.path !== null) {
+      await unlink(original.path).catch(() => undefined);
+    }
     this.host.state.ui.requestRender();
-    this.host.track('shortcut_paste', { kind: 'image' });
-    return true;
+  }
+
+  /**
+   * Paste-time upload of the final image bytes to the engine's daemon file
+   * store (agent-core-v2 only), run as part of the background ingestion —
+   * typing never waits on it, and submit only gives it the bounded
+   * `pendingImageIngestions` wait. Best effort: any failure returns undefined,
+   * so the attachment keeps no `fileId` and submit-time expansion falls back
+   * to the inline base64 form.
+   */
+  private async uploadImageToDaemonFileStore(
+    bytes: Uint8Array,
+    mime: string,
+  ): Promise<FileMeta | undefined> {
+    if (!this.host.engineV2) return undefined;
+    const harness = this.host.harness;
+    if (harness === undefined) return undefined;
+    try {
+      const meta = await harness.uploadFile(bytes, {
+        name: `pasted-image.${imageExtensionForMime(mime)}`,
+        mimeType: mime,
+        expiresInSec: IMAGE_STAGING_TTL_SECONDS,
+      });
+      return meta;
+    } catch {
+      return undefined;
+    }
   }
 
   private async openExternalEditor(): Promise<void> {
@@ -621,3 +724,9 @@ export class EditorKeyboardController {
     }
   }
 }
+
+function parseExpiry(meta: FileMeta | undefined): number | undefined {
+  if (meta?.expires_at === undefined) return undefined;
+  const value = Date.parse(meta.expires_at);
+  return Number.isFinite(value) ? value : undefined;
+}
diff --git a/apps/kimi-code/src/tui/controllers/session-event-handler.ts b/apps/kimi-code/src/tui/controllers/session-event-handler.ts
index 9e73c92f207..e0fa8cf107d 100644
--- a/apps/kimi-code/src/tui/controllers/session-event-handler.ts
+++ b/apps/kimi-code/src/tui/controllers/session-event-handler.ts
@@ -119,6 +119,8 @@ export interface SessionEventHost {
   updateTerminalTitle(): void;
   sendQueuedMessage(session: Session, item: QueuedMessage): void;
   shiftQueuedMessage(): QueuedMessage | undefined;
+  handleTurnStarted?(event: TurnStartedEvent): void;
+  handleTurnEnded?(event: TurnEndedEvent): void;
   readonly btwPanelController: BtwPanelController;
   readonly tasksBrowserController: TasksBrowserController;
 }
@@ -319,6 +321,7 @@ export class SessionEventHandler {
   // ---------------------------------------------------------------------------
 
   private handleTurnBegin(event: TurnStartedEvent): void {
+    this.host.handleTurnStarted?.(event);
     this.currentTurnHasAssistantText = false;
     if (event.origin?.kind === 'plugin_command') {
       this.pluginCommandTurns.set(String(event.turnId), event.origin.pluginId);
@@ -356,6 +359,7 @@ export class SessionEventHandler {
   }
 
   private handleTurnEnd(event: TurnEndedEvent, sendQueued: (item: QueuedMessage) => void): void {
+    this.host.handleTurnEnded?.(event);
     this.host.streamingUI.flushNow();
     this.clearStepRetry();
     if (event.reason === 'cancelled') {
diff --git a/apps/kimi-code/src/tui/controllers/staging-leases.ts b/apps/kimi-code/src/tui/controllers/staging-leases.ts
new file mode 100644
index 00000000000..4d935aa5f9b
--- /dev/null
+++ b/apps/kimi-code/src/tui/controllers/staging-leases.ts
@@ -0,0 +1,303 @@
+/**
+ * `StagingLeaseTracker` — owns the lifecycle of staged prompt media (daemon
+ * uploads + local cache copies) between submission and the session that
+ * consumes it.
+ *
+ * A paste/upload edge stages media before the prompt exists. The two staged
+ * forms age differently once the consuming turn ends:
+ *
+ * - Daemon uploads become garbage — the engine materialized its own session
+ *   copy at intake — so the turn-end release deletes them.
+ * - Local cache copies may still be referenced by persisted history: a v1
+ *   video degrade writes its `<video path="…">` tag with the cache path, and
+ *   skill/plugin args carry the path as plain text; neither form is rewritten
+ *   to the session media dir. Turn-end release therefore retires cache copies
+ *   to a session-lifetime bucket, deleted at session close / shutdown.
+ *
+ * Media that never gets consumed (validation/render failure, queue discard,
+ * a dispatch RPC that failed before any turn claimed the lease) is deleted
+ * immediately, whatever form it takes.
+ *
+ * A submission diverted before dispatch hands its lease back via `defer`:
+ * the media stays staged under raw (ids, paths) ownership — a queued message
+ * re-leases at dequeue dispatch, and the cache-hint stash's restore/resend
+ * exits release it through `releaseRecalled` / a fresh lease.
+ *
+ * The tracker holds one lease per submission, binds it to the consuming turn
+ * (explicitly at dispatch, by exact submission id when the turn echoes the
+ * client-chosen prompt id, or heuristically when a matching-origin turn
+ * starts), and releases it when that turn ends. The heuristic claims the
+ * earliest unclaimed lease of the same origin; that is only sound because the
+ * TUI serializes same-origin dispatches (one in-flight submission at a time,
+ * see `beginSessionRequest`) and `turn.started` arrives in dispatch order.
+ *
+ * Exact binding: a lease created with a `submissionId` is registered in
+ * `leasesBySubmissionId`, and the submission sends that id as the prompt id;
+ * the consuming turn's `turn.started` echoes it as `promptId`, so
+ * `handleTurnStarted` binds the exact lease instead of guessing. The
+ * heuristic below remains the fallback for submissions without an id echo.
+ *
+ * INVARIANT: at most one unclaimed lease per origin at any moment — with two
+ * or more, the heuristic cannot tell which submission the turn belongs to.
+ * `handleTurnStarted` reports a violation through the `warn` effect and still
+ * claims the earliest (a mis-claim only mis-times deletions, so it is not
+ * worth failing the turn over). An exact `promptId` hit bypasses the
+ * heuristic entirely, so it neither trips nor needs the invariant.
+ *
+ * Unclaimed leases are released at session close / shutdown, and every
+ * in-flight cleanup is drainable via {@link drain}.
+ *
+ * Self-contained state machine extracted from `KimiTUI`: the two side effects
+ * (resolving attachment ids to daemon file ids, deleting the staged files)
+ * are injected, so the tracker is unit-testable without a TUI.
+ */
+
+import type { TurnEndedEvent, TurnStartedEvent } from '@moonshot-ai/kimi-code-sdk';
+
+import type { QueuedMessage } from '../types';
+
+export type StagingLeaseOrigin = 'user' | 'skill_activation' | 'plugin_command';
+
+export interface StagingLease {
+  readonly imageAttachmentIds: readonly number[];
+  readonly paths: readonly string[];
+  readonly origin: StagingLeaseOrigin;
+  readonly submissionId?: string;
+  turnId: string | undefined;
+  released: boolean;
+}
+
+export interface StagingLeaseEffects {
+  /** Resolve attachment ids to the staged daemon file ids, consuming the mapping. */
+  readonly takeFileIds: (imageAttachmentIds: readonly number[]) => readonly string[];
+  /** Consume retains without taking the staged files (queue recall keeps them). */
+  readonly releaseRetains: (imageAttachmentIds: readonly number[]) => void;
+  /** Delete staged files (daemon uploads + local cache copies); never rejects. */
+  readonly deleteFiles: (fileIds: readonly string[], paths: readonly string[]) => Promise<void>;
+  /**
+   * Optional sink for invariant violations (see the INVARIANT note above).
+   * The tracker keeps operating; the warning exists to make a broken
+   * same-origin ordering assumption visible instead of mis-binding silently.
+   */
+  readonly warn?: (message: string) => void;
+}
+
+export class StagingLeaseTracker {
+  private readonly cleanups = new Set<Promise<void>>();
+  /** Staged media is owned by the turn that consumes it, not by the RPC call. */
+  private readonly leases = new Set<StagingLease>();
+  private readonly leasesByTurn = new Map<string, Set<StagingLease>>();
+  /** Leases carrying a client-chosen submission id, for exact `promptId` binding. */
+  private readonly leasesBySubmissionId = new Map<string, StagingLease>();
+  /**
+   * Cache copies whose consuming turn already ended. Persisted history may
+   * still reference their paths (v1 video degrade tags, skill/plugin text
+   * references), so they survive until the session closes.
+   */
+  private readonly retiredPaths = new Set<string>();
+
+  constructor(private readonly effects: StagingLeaseEffects) {}
+
+  create(
+    imageAttachmentIds: readonly number[],
+    paths: readonly string[],
+    origin: StagingLeaseOrigin,
+    submissionId?: string,
+  ): StagingLease | undefined {
+    // `imageAttachmentIds` multiplicity is the retain count this lease must
+    // release: each extraction/rewrite retains once per unique id, so callers
+    // dedupe repeated placeholder occurrences per contribution before handing
+    // the ids over (one message referencing an image twice contributes it
+    // once; two batched messages sharing an image contribute it twice).
+    if (imageAttachmentIds.length === 0 && paths.length === 0) return undefined;
+    const lease: StagingLease = {
+      imageAttachmentIds: [...imageAttachmentIds],
+      paths: [...paths],
+      origin,
+      submissionId,
+      turnId: undefined,
+      released: false,
+    };
+    this.leases.add(lease);
+    if (submissionId !== undefined) this.leasesBySubmissionId.set(submissionId, lease);
+    return lease;
+  }
+
+  bindToTurn(lease: StagingLease | undefined, turnId: string): void {
+    if (lease === undefined || lease.released || lease.turnId !== undefined) return;
+    lease.turnId = turnId;
+    let leases = this.leasesByTurn.get(turnId);
+    if (leases === undefined) {
+      leases = new Set<StagingLease>();
+      this.leasesByTurn.set(turnId, leases);
+    }
+    leases.add(lease);
+  }
+
+  handleTurnStarted(event: TurnStartedEvent): void {
+    const kind = event.origin?.kind;
+    if (kind !== 'user' && kind !== 'skill_activation' && kind !== 'plugin_command') return;
+    if (event.promptId !== undefined) {
+      // Exact binding: the turn echoes the submission's client-chosen prompt
+      // id — bind that lease directly and skip the origin heuristic (and its
+      // ambiguity warning) entirely.
+      const exact = this.leasesBySubmissionId.get(event.promptId);
+      if (exact !== undefined && exact.turnId === undefined) {
+        this.bindToTurn(exact, String(event.turnId));
+        return;
+      }
+    }
+    const candidates = [...this.leases].filter(
+      (candidate) =>
+        !candidate.released && candidate.turnId === undefined && candidate.origin === kind,
+    );
+    if (candidates.length > 1) {
+      // INVARIANT violation: the earliest-unclaimed pick cannot tell
+      // same-origin leases apart — same-origin dispatch serialization or the
+      // turn.started ordering assumption may be broken.
+      this.effects.warn?.(
+        `staging lease: ${candidates.length} unclaimed '${kind}' leases when turn ` +
+          `${String(event.turnId)} started; claiming the earliest`,
+      );
+    }
+    this.bindToTurn(candidates[0], String(event.turnId));
+  }
+
+  handleTurnEnded(event: TurnEndedEvent): void {
+    const turnId = String(event.turnId);
+    const leases = this.leasesByTurn.get(turnId);
+    if (leases === undefined) return;
+    for (const lease of leases) this.releaseConsumed(lease);
+    this.leasesByTurn.delete(turnId);
+  }
+
+  /**
+   * Track a dispatch RPC carrying staged media. When it rejects, run
+   * `onError` and release the lease — but only while no turn has claimed it:
+   * a bound lease is owned by the turn and released at turn end, whatever the
+   * RPC's later outcome.
+   */
+  trackDispatch(
+    lease: StagingLease | undefined,
+    request: Promise<unknown>,
+    onError: (error: unknown) => void,
+  ): void {
+    this.track(
+      request
+        .catch((error: unknown) => {
+          onError(error);
+          if (lease?.turnId === undefined) this.release(lease);
+        })
+        .then(() => undefined),
+    );
+  }
+
+  /**
+   * Release staged media that will never be consumed (dispatch failed before
+   * a turn claimed the lease): delete daemon uploads and cache copies now.
+   */
+  release(lease: StagingLease | undefined): void {
+    if (lease === undefined || lease.released) return;
+    this.unbind(lease);
+    this.deleteStaged(this.takeFileIds(lease), lease.paths);
+  }
+
+  /** Release every unclaimed lease and the retired cache copies (session close / shutdown). */
+  releaseAll(): void {
+    for (const lease of this.leases) this.release(lease);
+    const retired = [...this.retiredPaths];
+    this.retiredPaths.clear();
+    this.deleteStaged([], retired);
+  }
+
+  /** Release staged media that never got a lease (validation/render failures). */
+  releaseMedia(imageAttachmentIds: readonly number[], paths: readonly string[]): void {
+    const fileIds = this.effects.takeFileIds(imageAttachmentIds);
+    this.deleteStaged(fileIds, paths);
+  }
+
+  releaseQueued(items: readonly QueuedMessage[]): void {
+    const fileIds = items.flatMap((item) =>
+      this.effects.takeFileIds(item.imageAttachmentIds ?? []),
+    );
+    const paths = items.flatMap((item) => item.stagingPaths ?? []);
+    this.deleteStaged(fileIds, paths);
+  }
+
+  /**
+   * Release a queued item (or a cache-hint stash's extraction) recalled into
+   * the editor: the restored draft still references its attachments, so this
+   * is not a discard — daemon uploads stay staged (only the retain is
+   * consumed; the next submit re-retains them) and cache copies retire to
+   * session lifetime instead of being deleted.
+   */
+  releaseRecalled(item: {
+    imageAttachmentIds?: readonly number[];
+    stagingPaths?: readonly string[];
+  }): void {
+    this.effects.releaseRetains(item.imageAttachmentIds ?? []);
+    for (const path of item.stagingPaths ?? []) this.retiredPaths.add(path);
+  }
+
+  /**
+   * Hand a lease's staged media back to raw (ids, paths) ownership without
+   * consuming retains or deleting files: the lease is simply unbound. Used
+   * when a submission is diverted before dispatch — queued behind a running
+   * turn or swallowed by the cache-hint stash; see the header note.
+   */
+  defer(lease: StagingLease | undefined): void {
+    if (lease === undefined || lease.released) return;
+    this.unbind(lease);
+  }
+
+  /** Track an in-flight staging-related promise so {@link drain} can await it. */
+  track(cleanup: Promise<void>): void {
+    let tracked!: Promise<void>;
+    tracked = cleanup.catch(() => undefined).finally(() => {
+      this.cleanups.delete(tracked);
+    });
+    this.cleanups.add(tracked);
+  }
+
+  async drain(): Promise<void> {
+    while (this.cleanups.size > 0) {
+      await Promise.allSettled(this.cleanups);
+    }
+  }
+
+  /** Schedule deletion of already-resolved staged files (e.g. a store clear). */
+  deleteStaged(fileIds: readonly string[], paths: readonly string[] = []): void {
+    if (fileIds.length === 0 && paths.length === 0) return;
+    this.track(this.effects.deleteFiles(fileIds, paths));
+  }
+
+  /**
+   * Turn-end release: the daemon uploads are safe to delete — the engine
+   * materialized its own session copies at intake — while the cache copies
+   * retire to session lifetime (see {@link retiredPaths}).
+   */
+  private releaseConsumed(lease: StagingLease): void {
+    if (lease.released) return;
+    this.unbind(lease);
+    for (const path of lease.paths) this.retiredPaths.add(path);
+    this.deleteStaged(this.takeFileIds(lease));
+  }
+
+  private unbind(lease: StagingLease): void {
+    lease.released = true;
+    this.leases.delete(lease);
+    if (lease.submissionId !== undefined) this.leasesBySubmissionId.delete(lease.submissionId);
+    if (lease.turnId !== undefined) {
+      const leases = this.leasesByTurn.get(lease.turnId);
+      leases?.delete(lease);
+      if (leases?.size === 0) this.leasesByTurn.delete(lease.turnId);
+    }
+  }
+
+  private takeFileIds(lease: StagingLease): readonly string[] {
+    // Multiplicity in the lease's id list is the retain count (creation sites
+    // dedupe per extraction before contributing ids): consume one retain per
+    // occurrence.
+    return lease.imageAttachmentIds.flatMap((id) => this.effects.takeFileIds([id]));
+  }
+}
diff --git a/apps/kimi-code/src/tui/kimi-tui.ts b/apps/kimi-code/src/tui/kimi-tui.ts
index 0b40460f432..21db15b5b57 100644
--- a/apps/kimi-code/src/tui/kimi-tui.ts
+++ b/apps/kimi-code/src/tui/kimi-tui.ts
@@ -1,4 +1,6 @@
+import { randomUUID } from 'node:crypto';
 import { writeFileSync } from 'node:fs';
+import { unlink } from 'node:fs/promises';
 import { join } from 'node:path';
 
 import type { DeviceAuthorization } from '@moonshot-ai/kimi-code-oauth';
@@ -15,6 +17,8 @@ import type {
   Session,
   SkillSummary,
   TokenUsage,
+  TurnEndedEvent,
+  TurnStartedEvent,
   WorkspaceTrustInfo,
 } from '@moonshot-ai/kimi-code-sdk';
 import type { MigrationPlan } from '@moonshot-ai/migration-legacy';
@@ -111,6 +115,7 @@ import {
   SESSION_LIST_PAGE_SIZE,
   SESSIONLESS_STARTUP_NOTICE,
 } from './constant/kimi-tui';
+import { IMAGE_INGESTION_SUBMIT_WAIT_MS } from './constant/media';
 import { CHROME_GUTTER } from './constant/rendering';
 import { MAX_TERMINAL_TITLE_LENGTH } from './constant/terminal';
 import { AuthFlowController } from './controllers/auth-flow';
@@ -119,6 +124,7 @@ import { ClipboardImageHintController } from './controllers/clipboard-image-hint
 import { EditorKeyboardController } from './controllers/editor-keyboard';
 import { SessionEventHandler } from './controllers/session-event-handler';
 import { SessionReplayRenderer } from './controllers/session-replay';
+import { StagingLeaseTracker, type StagingLease } from './controllers/staging-leases';
 import { StreamingUIController } from './controllers/streaming-ui';
 import { TasksBrowserController } from './controllers/tasks-browser';
 import { installRainbowDance } from './easter-eggs/dance';
@@ -151,9 +157,16 @@ import { isDeadTerminalError } from './utils/dead-terminal';
 import { formatErrorMessage } from './utils/event-payload';
 import { pickForegroundTasks } from './utils/foreground-task';
 import { ImageAttachmentStore, type ImageAttachment } from './utils/image-attachment-store';
-import { extractMediaAttachments, rewriteMediaPlaceholders } from './utils/image-placeholder';
+import {
+  extractMediaAttachments,
+  pendingImageIngestions,
+  refreshExpiringImageFileRefs,
+  rewriteMediaPlaceholders,
+  videoAttachmentIdsInText,
+} from './utils/image-placeholder';
 import type { ExtractionResult } from './utils/image-placeholder';
 import { installInputLatencyProbe } from './utils/input-latency';
+import { combineSteerInput } from './utils/steer-input';
 import { startupTrace } from '#/utils/startup-trace';
 import { REPLAY_FETCH_TURN_LIMIT } from './utils/message-replay';
 import { hasPatchChanges } from './utils/object-patch';
@@ -275,51 +288,14 @@ function createInitialAppState(input: KimiTUIStartupInput): AppState {
 interface SendMessageOptions {
   readonly parts?: readonly PromptPart[];
   readonly imageAttachmentIds?: readonly number[];
+  readonly stagingPaths?: readonly string[];
   readonly hasMedia?: boolean;
-}
-
-/**
- * Flatten steer items into the payload `session.steer` expects: the
- * historical `'\n\n'`-joined string when nothing carries media, or a
- * merged part list when any item has extracted media parts (queued image
- * messages, or the editor draft after placeholder extraction).
- *
- * Items are separated by the historical `'\n\n'`, which merges into the
- * adjacent text part. The one exception is two touching media parts: a
- * standalone `{type:'text',text:'\n\n'}` between them would be rejected
- * by `normalizePromptInput` as an empty text part, so the separator is
- * dropped there (media parts are self-delimiting anyway).
- */
-function combineSteerInput(items: readonly SteerInputItem[]): string | PromptPart[] {
-  const hasMedia = items.some((item) => item.parts !== undefined && item.parts.length > 0);
-  if (!hasMedia) return items.map((item) => item.text).join('\n\n');
-  const parts: PromptPart[] = [];
-  for (const item of items) {
-    const startsWithMedia =
-      item.parts !== undefined && item.parts.length > 0 && item.parts[0]?.type !== 'text';
-    const lastIsMedia = parts.length > 0 && parts.at(-1)?.type !== 'text';
-    if (parts.length > 0 && !(lastIsMedia && startsWithMedia)) {
-      appendSteerText(parts, '\n\n');
-    }
-    if (item.parts !== undefined && item.parts.length > 0) {
-      for (const part of item.parts) {
-        if (part.type === 'text') appendSteerText(parts, part.text);
-        else parts.push(part);
-      }
-    } else {
-      appendSteerText(parts, item.text);
-    }
-  }
-  return parts;
-}
-
-function appendSteerText(parts: PromptPart[], text: string): void {
-  const last = parts.at(-1);
-  if (last?.type === 'text') {
-    parts[parts.length - 1] = { type: 'text', text: last.text + text };
-    return;
-  }
-  parts.push({ type: 'text', text });
+  /**
+   * Lease pre-created at extraction time by `sendNormalUserInput`. Dispatch
+   * reuses it (carrying its exact-binding submission id); enqueueing defers
+   * it — the queue item owns the raw ids/paths and re-leases at dequeue.
+   */
+  readonly lease?: StagingLease;
 }
 
 /** How long the one-shot "moved to background" footer hint stays visible. */
@@ -333,6 +309,8 @@ export class KimiTUI {
   /** In-flight lazy session creation (v2 engine), shared by concurrent first-use triggers. */
   private ensureSessionPromise: Promise<Session | undefined> | null = null;
   private readonly cacheHint = new CacheHintController(this);
+  /** Staged prompt media lifecycle (daemon uploads + cache copies) — see StagingLeaseTracker. */
+  private readonly staging: StagingLeaseTracker;
   private readonly approvalController = new ApprovalController();
   private readonly questionController = new QuestionController();
   private readonly reverseRpcDisposers: Array<() => void> = [];
@@ -418,6 +396,21 @@ export class KimiTUI {
 
   constructor(harness: KimiHarness, startupInput: KimiTUIStartupInput) {
     this.harness = harness;
+    this.staging = new StagingLeaseTracker({
+      takeFileIds: (ids) => this.imageStore.takeFileIds(ids),
+      releaseRetains: (ids) => {
+        this.imageStore.releaseRetains(ids);
+      },
+      deleteFiles: async (fileIds, paths) => {
+        await Promise.all([
+          ...fileIds.map((fileId) => this.harness.deleteFile(fileId).catch(() => undefined)),
+          ...paths.map((path) => unlink(path).catch(() => undefined)),
+        ]);
+      },
+      warn: (message) => {
+        this.track('staging_lease_invariant', { message });
+      },
+    });
     const tuiOptions: KimiTUIOptions = {
       initialAppState: createInitialAppState(startupInput),
       startup: {
@@ -994,6 +987,10 @@ export class KimiTUI {
     // raw mode with a hidden cursor.
     try {
       await this.closeSession('shutting down');
+      this.clearQueuedMessages();
+      this.staging.releaseAll();
+      this.staging.deleteStaged(this.imageStore.clear());
+      await this.staging.drain();
       await this.harness.close();
     } finally {
       this.sessionEventHandler.stopAllMcpServerStatusSpinners();
@@ -1310,11 +1307,12 @@ export class KimiTUI {
   }
 
   private drainOneQueuedMessage(): void {
-    const item = this.shiftQueuedMessage();
-    if (item === undefined) return;
     const session = this.session;
     if (session === undefined) return;
+    const item = this.shiftQueuedMessage();
+    if (item === undefined) return;
     if (item.mode === 'bash') {
+      this.staging.releaseQueued([item]);
       void this.runShellCommandFromInput(item.text);
     } else {
       this.sendQueuedMessage(session, item);
@@ -1329,6 +1327,19 @@ export class KimiTUI {
       return;
     }
     let extraction: ReturnType<typeof extractMediaAttachments>;
+    if (preExtracted === undefined) {
+      // A just-pasted image may still be finishing its background ingestion
+      // (compression/daemon upload): give it a bounded moment so the submit
+      // can use the compressed/daemon-ref form — a slower ingestion extracts
+      // to the inline fallback instead. Undefined when nothing is pending,
+      // keeping the media-free send path synchronous.
+      const ingestionWait = pendingImageIngestions(
+        text,
+        this.imageStore,
+        IMAGE_INGESTION_SUBMIT_WAIT_MS,
+      );
+      if (ingestionWait !== undefined) await ingestionWait;
+    }
     try {
       // Pasted videos are copied into the cache and expand to a `file://`
       // `video_url` part; the engine resolves (uploads or degrades) them
@@ -1338,31 +1349,71 @@ export class KimiTUI {
       // in: the image store may already be cleared (e.g. after "Start a new
       // session"), so re-extracting from the text would lose the media.
       extraction = preExtracted ?? extractMediaAttachments(text, this.imageStore);
+      if (preExtracted !== undefined) {
+        const parts = refreshExpiringImageFileRefs(
+          extraction.parts,
+          extraction.imageAttachmentIds,
+          this.imageStore,
+        );
+        if (parts !== extraction.parts) extraction = { ...extraction, parts };
+      }
     } catch (error) {
       // A video cache copy failed (unwritable cache dir, vanished source…);
       // nothing was dispatched.
       this.showError(`Failed to prepare media attachment: ${formatErrorMessage(error)}`);
       return;
     }
-    if (!this.validateMediaCapabilities(extraction)) return;
+    // Create the staging lease right after extraction, so every exit below
+    // releases through the tracker instead of open-coding ids/paths — a
+    // forgotten exit degrades to an unclaimed lease (swept by `releaseAll`)
+    // instead of a permanently retained upload. The lease carries the
+    // exact-binding submission id: the consuming turn's `turn.started` echoes
+    // it as `promptId`. A goal-active submission is steered and binds its
+    // lease explicitly in sendMessageInternal, so it gets no id.
+    const stagingLease = this.staging.create(
+      // One retain per unique id per extraction: dedupe repeated placeholder
+      // occurrences so the lease's id multiplicity matches the retain count.
+      [...new Set(extraction.imageAttachmentIds)],
+      extraction.stagingPaths,
+      'user',
+      extraction.hasMedia && this.state.appState.goal?.status !== 'active'
+        ? randomUUID()
+        : undefined,
+    );
+    if (!this.validateMediaCapabilities(extraction)) {
+      this.staging.release(stagingLease);
+      return;
+    }
     // Idle cache-hint interception sits before session creation; it is
-    // synchronous unless a hint actually fires, keeping the send path
-    // await-free up to sendMessage.
-    if (this.cacheHint.maybeInterceptOnSubmit(text, extraction)) return;
+    // synchronous unless a hint actually fires. Aside from the bounded
+    // ingestion wait above, the send path stays await-free up to sendMessage.
+    if (this.cacheHint.maybeInterceptOnSubmit(text, extraction)) {
+      // The stash owns the extraction from here: its resend re-leases inside
+      // the re-entered send path, its restore goes through releaseRecalled
+      // (see CacheHintController). Detach so the stash is not double-owned.
+      this.staging.defer(stagingLease);
+      return;
+    }
     let session = this.session;
     if (session === undefined) {
       if (!this.engineV2) {
         this.showError(LLM_NOT_SET_MESSAGE);
+        this.staging.release(stagingLease);
         return;
       }
       session = await this.ensureSession();
-      if (session === undefined) return;
+      if (session === undefined) {
+        this.staging.release(stagingLease);
+        return;
+      }
     }
     if (extraction.hasMedia) {
       this.sendMessage(session, text, {
         hasMedia: true,
         parts: extraction.parts,
         imageAttachmentIds: extraction.imageAttachmentIds,
+        stagingPaths: extraction.stagingPaths,
+        lease: stagingLease,
       });
     } else {
       this.sendMessage(session, text);
@@ -1410,6 +1461,7 @@ export class KimiTUI {
               hasMedia: true,
               parts: extraction.parts,
               imageAttachmentIds: extraction.imageAttachmentIds,
+              stagingPaths: extraction.stagingPaths,
               inlineSkillActivations: activations,
             }
           : { inlineSkillActivations: activations },
@@ -1467,10 +1519,11 @@ export class KimiTUI {
     hasMedia: boolean;
     imageAttachmentIds: readonly number[];
     videoAttachmentIds: readonly number[];
+    imageSnapshots?: readonly unknown[];
   }): boolean {
     if (!extraction.hasMedia) return true;
     if (
-      extraction.imageAttachmentIds.length > 0 &&
+      (extraction.imageAttachmentIds.length > 0 || (extraction.imageSnapshots?.length ?? 0) > 0) &&
       !this.supportsCurrentModelCapability('image_in')
     ) {
       this.showError('Current model does not support image input.');
@@ -1524,9 +1577,41 @@ export class KimiTUI {
     if (this.state.queuedMessages.length === 0) return undefined;
     const last = this.state.queuedMessages.at(-1)!;
     this.state.queuedMessages = this.state.queuedMessages.slice(0, -1);
+    // A recall restores the draft into the editor — it is not a discard:
+    // consumes the retains only, keeping staged files alive (see
+    // `releaseRecalled`), and rebases recalled videos onto their staged cache
+    // copies so a vanished original source cannot lose the media.
+    this.staging.releaseRecalled(last);
+    this.rebaseRecalledVideoSources(last.text, last.stagingPaths);
     return last;
   }
 
+  /**
+   * Cache-hint restore: a dismissed/hand-back interception returns its draft
+   * to the editor — same semantics as a queue recall (consume the stash
+   * extraction's retains, retire its staged copies, rebase videos onto them).
+   */
+  recallStashedMedia(text: string, extraction: ExtractionResult | undefined): void {
+    if (extraction === undefined) return;
+    this.staging.releaseRecalled({
+      imageAttachmentIds: extraction.imageAttachmentIds,
+      stagingPaths: extraction.stagingPaths,
+    });
+    this.rebaseRecalledVideoSources(text, extraction.stagingPaths);
+  }
+
+  private rebaseRecalledVideoSources(
+    text: string,
+    stagingPaths: readonly string[] | undefined,
+  ): void {
+    if (stagingPaths === undefined || stagingPaths.length === 0) return;
+    const videoIds = videoAttachmentIdsInText(text, this.imageStore);
+    stagingPaths.forEach((path, index) => {
+      const id = videoIds[index];
+      if (id !== undefined) this.imageStore.rebaseVideoSource(id, path);
+    });
+  }
+
   // =========================================================================
   // Session Requests / Queues
   // =========================================================================
@@ -1546,6 +1631,10 @@ export class KimiTUI {
         options?.imageAttachmentIds !== undefined && options.imageAttachmentIds.length > 0
           ? options.imageAttachmentIds
           : undefined,
+      stagingPaths:
+        options?.stagingPaths !== undefined && options.stagingPaths.length > 0
+          ? options.stagingPaths
+          : undefined,
       mode,
       inlineSkillActivations: options?.inlineSkillActivations,
     });
@@ -1578,6 +1667,7 @@ export class KimiTUI {
 
   sendQueuedMessage(session: Session, item: QueuedMessage): void {
     if (item.mode === 'bash') {
+      this.staging.releaseQueued([item]);
       void this.runShellCommandFromInput(item.text);
       return;
     }
@@ -1590,30 +1680,64 @@ export class KimiTUI {
     if (item.inlineSkillActivations !== undefined && item.inlineSkillActivations.length > 0) {
       // Media was extracted and validated at enqueue time; reuse the queued
       // parts rather than re-extracting from a possibly-cleared image store.
+      // Expiring daemon refs refresh at dispatch, same as the plain tail below.
+      const refreshed =
+        item.parts === undefined
+          ? []
+          : [
+              ...refreshExpiringImageFileRefs(
+                item.parts,
+                item.imageAttachmentIds ?? [],
+                this.imageStore,
+              ),
+            ];
       this.beginSessionRequest();
       void this.runInlineSkillActivations(
         session,
         item.text,
         item.inlineSkillActivations,
         {
-          parts: item.parts !== undefined ? [...item.parts] : [],
-          hasMedia: item.parts !== undefined && item.parts.length > 0,
+          parts: refreshed,
+          hasMedia: refreshed.length > 0,
           imageAttachmentIds: item.imageAttachmentIds !== undefined ? [...item.imageAttachmentIds] : [],
           videoAttachmentIds: [],
+          imageSnapshots: [],
+          stagingPaths: item.stagingPaths !== undefined ? [...item.stagingPaths] : [],
         },
       ).catch((error: unknown) => {
         this.failSessionRequest(`Skill activation failed: ${formatErrorMessage(error)}`);
       });
       return;
     }
+    const parts =
+      item.parts === undefined
+        ? undefined
+        : refreshExpiringImageFileRefs(
+            item.parts,
+            item.imageAttachmentIds ?? [],
+            this.imageStore,
+          );
     this.harness.withInteractiveAgent(item.agentId ?? MAIN_AGENT_ID, () => {
       this.sendMessageInternal(session, item.text, {
-        parts: item.parts,
+        parts,
         imageAttachmentIds: item.imageAttachmentIds,
+        stagingPaths: item.stagingPaths,
       });
     });
   }
 
+  handleTurnStarted(event: TurnStartedEvent): void {
+    this.staging.handleTurnStarted(event);
+  }
+
+  handleTurnEnded(event: TurnEndedEvent): void {
+    this.staging.handleTurnEnded(event);
+  }
+
+  releaseStagingMedia(imageAttachmentIds: readonly number[], paths: readonly string[]): void {
+    this.staging.releaseMedia(imageAttachmentIds, paths);
+  }
+
   requestQueuedGoalPromotion(): void {
     this.sessionEventHandler.requestQueuedGoalPromotion();
   }
@@ -1631,29 +1755,58 @@ export class KimiTUI {
       content: input,
       imageAttachmentIds,
     });
-
+    // A goal-active steer is buffered into the running goal turn — no new
+    // turn.started will fire for handleTurnStarted to claim the lease — so
+    // bind it to that turn here. The turn context must be read BEFORE
+    // beginSessionRequest resets it, and only while a turn is actually live
+    // (finalizeTurn clears the id at turn end; a queued dispatch can land
+    // while the goal driver's next continuation turn is already streaming).
+    const runningTurnId =
+      this.state.appState.streamingPhase === 'idle' || this.state.appState.streamingPhase === 'shell'
+        ? undefined
+        : this.streamingUI.getTurnContext().turnId;
     this.beginSessionRequest();
 
     const sdkInput = options?.parts ?? input;
+    const goalActive = this.state.appState.goal?.status === 'active';
+    // The lease normally arrives pre-created by sendNormalUserInput (carrying
+    // its exact-binding submission id). Queued dispatches and steer batches
+    // arrive with raw ids/paths instead: a prompt submission carrying staged
+    // media gets a client-chosen prompt id minted here — the engine echoes it
+    // on the consuming turn's `turn.started` (`promptId`), so the lease binds
+    // exactly instead of through the origin heuristic. The goal-steer path
+    // binds its lease explicitly below, so it gets no id.
+    const stagingLease =
+      options?.lease ??
+      this.staging.create(
+        // One retain per unique id per extraction: dedupe repeated placeholder
+        // occurrences so the lease's id multiplicity matches the retain count.
+        imageAttachmentIds === undefined ? [] : [...new Set(imageAttachmentIds)],
+        options?.stagingPaths ?? [],
+        'user',
+        !goalActive && (imageAttachmentIds !== undefined || (options?.stagingPaths?.length ?? 0) > 0)
+          ? randomUUID()
+          : undefined,
+      );
+    const submissionId = stagingLease?.submissionId;
     // While a goal is being pursued the engine holds its active turn across the
     // whole continuation loop, so a fresh prompt races the goal driver at every
     // continuation boundary and is rejected with `turn.agent_busy`, dropping
     // the message. Steer instead: the engine buffers it into the running goal
     // turn, or launches a turn of its own if the loop just ended.
-    if (this.state.appState.goal?.status === 'active') {
-      void session.steer(sdkInput).catch((error: unknown) => {
-        const message = formatErrorMessage(error);
+    if (goalActive) {
+      if (runningTurnId !== undefined) this.staging.bindToTurn(stagingLease, runningTurnId);
+      this.staging.trackDispatch(stagingLease, session.steer(sdkInput), (error) => {
         // Same reset as the prompt path: beginSessionRequest already moved the
         // TUI to the waiting phase, and no turn events may follow a failed
         // steer (e.g. the session is gone), which would leave the UI stuck
         // queueing input behind a request that never completes.
-        this.failSessionRequest(`Failed to steer: ${message}`);
+        this.failSessionRequest(`Failed to steer: ${formatErrorMessage(error)}`);
       });
       return;
     }
-    void session.prompt(sdkInput).catch((error: unknown) => {
-      const message = formatErrorMessage(error);
-      this.failSessionRequest(`Failed to send: ${message}`);
+    this.staging.trackDispatch(stagingLease, session.prompt(sdkInput, { promptId: submissionId }), (error) => {
+      this.failSessionRequest(`Failed to send: ${formatErrorMessage(error)}`);
     });
   }
 
@@ -1671,7 +1824,10 @@ export class KimiTUI {
       this.showError(`Failed to prepare media attachment: ${formatErrorMessage(error)}`);
       return;
     }
-    if (!this.validateMediaCapabilities(rewrite)) return;
+    if (!this.validateMediaCapabilities(rewrite)) {
+      this.staging.releaseMedia(rewrite.imageAttachmentIds, rewrite.stagingPaths);
+      return;
+    }
     // Compacting (or deferred input): queue behind it — visible and recallable.
     // Slash-skill items steer like any queued input on Ctrl-S (the activation
     // fires into the running turn instead of the literal text) — see
@@ -1680,6 +1836,10 @@ export class KimiTUI {
     // plain input — queued by default, steered on demand — because the engine
     // steers activations into a running turn exactly like a steered user
     // message (v2 `prompt.inject`, v1 `SkillManager.recordActivation`).
+    // The rewritten args reference the staging cache copies by plain path,
+    // never the daemon uploads, so queueing takes recall semantics: the
+    // retains are consumed and the copies retire to session lifetime — they
+    // must stay readable until the item drains.
     const turnRunning = this.state.appState.streamingPhase !== 'idle';
     if (this.deferUserMessages || this.state.appState.isCompacting || turnRunning) {
       const args = rewrite.text.trim();
@@ -1690,16 +1850,28 @@ export class KimiTUI {
         skillName,
         skillArgs: rewrite.text,
       });
+      this.staging.releaseRecalled({
+        imageAttachmentIds: rewrite.imageAttachmentIds,
+        stagingPaths: rewrite.stagingPaths,
+      });
       this.track('input_queue');
       this.updateQueueDisplay();
       this.state.ui.requestRender();
       return;
     }
+    const stagingLease = this.staging.create(
+      [...new Set(rewrite.imageAttachmentIds)],
+      rewrite.stagingPaths,
+      'skill_activation',
+    );
     this.beginSessionRequest();
-    void session.activateSkill(skillName, rewrite.text).catch((error: unknown) => {
-      const message = formatErrorMessage(error);
-      this.failSessionRequest(`Skill "${skillName}" failed: ${message}`);
-    });
+    this.staging.trackDispatch(
+      stagingLease,
+      session.activateSkill(skillName, rewrite.text),
+      (error) => {
+        this.failSessionRequest(`Skill "${skillName}" failed: ${formatErrorMessage(error)}`);
+      },
+    );
   }
 
   activatePluginCommand(
@@ -1718,14 +1890,25 @@ export class KimiTUI {
       this.showError(`Failed to prepare media attachment: ${formatErrorMessage(error)}`);
       return;
     }
-    if (!this.validateMediaCapabilities(rewrite)) return;
+    const stagingLease = this.staging.create(
+      [...new Set(rewrite.imageAttachmentIds)],
+      rewrite.stagingPaths,
+      'plugin_command',
+    );
+    if (!this.validateMediaCapabilities(rewrite)) {
+      this.staging.release(stagingLease);
+      return;
+    }
     this.beginSessionRequest();
-    void session
-      .activatePluginCommand(pluginId, commandName, rewrite.text)
-      .catch((error: unknown) => {
-        const message = formatErrorMessage(error);
-        this.failSessionRequest(`Command "${pluginId}:${commandName}" failed: ${message}`);
-      });
+    this.staging.trackDispatch(
+      stagingLease,
+      session.activatePluginCommand(pluginId, commandName, rewrite.text),
+      (error) => {
+        this.failSessionRequest(
+          `Command "${pluginId}:${commandName}" failed: ${formatErrorMessage(error)}`,
+        );
+      },
+    );
   }
 
   private sendMessage(session: Session, input: string, options?: SendMessageOptions): void {
@@ -1734,6 +1917,9 @@ export class KimiTUI {
       this.state.appState.streamingPhase !== 'idle' ||
       this.state.appState.isCompacting
     ) {
+      // A queued message re-leases its staged media at dequeue dispatch; the
+      // pre-dispatch lease defers to the queue item's raw ids/paths.
+      this.staging.defer(options?.lease);
       this.enqueueMessage(input, options);
       return;
     }
@@ -1768,9 +1954,17 @@ export class KimiTUI {
       });
     }
 
-    void session.steer(combineSteerInput(input)).catch((error: unknown) => {
-      const message = formatErrorMessage(error);
-      this.showError(`Failed to steer: ${message}`);
+    // Dedupe per item, not across the batch: each queued message retained a
+    // shared image once, so the batch's id multiplicity is the retain count.
+    const imageAttachmentIds = input.flatMap((item) => [
+      ...new Set(item.imageAttachmentIds ?? []),
+    ]);
+    const stagingPaths = input.flatMap((item) => item.stagingPaths ?? []);
+    const stagingLease = this.staging.create(imageAttachmentIds, stagingPaths, 'user');
+    const currentTurnId = this.streamingUI.getTurnContext().turnId;
+    if (currentTurnId !== undefined) this.staging.bindToTurn(stagingLease, currentTurnId);
+    this.staging.trackDispatch(stagingLease, session.steer(combineSteerInput(input)), (error) => {
+      this.showError(`Failed to steer: ${formatErrorMessage(error)}`);
     });
   }
 
@@ -1792,7 +1986,9 @@ export class KimiTUI {
   }
 
   clearQueuedMessages(): void {
+    const queued = this.state.queuedMessages;
     this.state.queuedMessages = [];
+    this.staging.releaseQueued(queued);
   }
 
   shiftQueuedMessage(): QueuedMessage | undefined {
@@ -2077,6 +2273,10 @@ export class KimiTUI {
   async setSession(session: Session): Promise<void> {
     const previous = this.unloadCurrentSession('switching session');
     await previous?.close();
+    // A session switch abandons the previous session's in-flight staging
+    // leases and retires its history-owned cache copies. Do this at the
+    // boundary so retired paths cannot accumulate until process shutdown.
+    this.staging.releaseAll();
     this.session = session;
     this.harness.setTelemetryContext({ sessionId: session.id });
     this.registerSessionHandlers(session);
@@ -2145,6 +2345,7 @@ export class KimiTUI {
   async closeSession(reason: string): Promise<void> {
     const previous = this.unloadCurrentSession(reason);
     await previous?.close();
+    this.staging.releaseAll();
   }
 
   private unloadCurrentSession(reason: string): Session | undefined {
@@ -2290,7 +2491,7 @@ export class KimiTUI {
     this.aborted = false;
     this.cacheHint.resetRuntime();
     this.streamingUI.discardPending();
-    this.state.queuedMessages = [];
+    this.clearQueuedMessages();
     this.state.swarmModeEntry = undefined;
     this.streamingUI.resetToolCallState();
     this.streamingUI.resetToolUi();
@@ -2641,7 +2842,8 @@ export class KimiTUI {
     this.clearTerminalInlineImages();
     this.state.todoPanel.clear();
     this.state.todoPanelContainer.clear();
-    this.imageStore.clear();
+    const stagingFileIds = this.imageStore.clear();
+    this.staging.deleteStaged(stagingFileIds);
     this.renderWelcome();
     // No forced full render on session reset: let the differential renderer
     // converge on its own (a mass change above the viewport still makes the
@@ -2692,7 +2894,8 @@ export class KimiTUI {
     // only be dropped once its owning user message leaves the transcript.
     for (const entry of toRemove) {
       if (entry.kind === 'user' && entry.imageAttachmentIds !== undefined) {
-        this.imageStore.removeMany(entry.imageAttachmentIds);
+        const stagingFileIds = this.imageStore.removeMany(entry.imageAttachmentIds);
+        this.staging.deleteStaged(stagingFileIds);
       }
     }
 
diff --git a/apps/kimi-code/src/tui/types.ts b/apps/kimi-code/src/tui/types.ts
index 3edcda053cc..29700f18fd0 100644
--- a/apps/kimi-code/src/tui/types.ts
+++ b/apps/kimi-code/src/tui/types.ts
@@ -270,6 +270,7 @@ export interface QueuedMessage {
   readonly agentId?: string;
   readonly parts?: readonly PromptPart[];
   readonly imageAttachmentIds?: readonly number[];
+  readonly stagingPaths?: readonly string[];
   /** `bash` for a `!` shell command queued while another command is running;
    *  `skill` for a slash-skill activation queued while the session is busy;
    *  undefined (=`prompt`) for a normal message. */
@@ -293,6 +294,7 @@ export interface SteerInputItem {
   readonly text: string;
   readonly parts?: readonly PromptPart[];
   readonly imageAttachmentIds?: readonly number[];
+  readonly stagingPaths?: readonly string[];
 }
 
 export const INITIAL_LIVE_PANE: LivePaneState = {
diff --git a/apps/kimi-code/src/tui/utils/export-markdown.ts b/apps/kimi-code/src/tui/utils/export-markdown.ts
index 9531efa1046..594a411c411 100644
--- a/apps/kimi-code/src/tui/utils/export-markdown.ts
+++ b/apps/kimi-code/src/tui/utils/export-markdown.ts
@@ -139,6 +139,9 @@ function formatTurnMd(messages: readonly ContextMessage[], turnNumber: number):
 
     if (msg.role === 'user') {
       lines.push('### User', '');
+      // A daemon-ref media part is self-contained and renders as
+      // `[image]`/`[video]` below; a standalone `<media path>` tag is user
+      // text and exports verbatim.
       for (const part of msg.content) {
         const text = formatContentPartMd(part);
         if (text.trim()) {
diff --git a/apps/kimi-code/src/tui/utils/image-attachment-store.ts b/apps/kimi-code/src/tui/utils/image-attachment-store.ts
index 8d653159a20..ed2a5af4a5a 100644
--- a/apps/kimi-code/src/tui/utils/image-attachment-store.ts
+++ b/apps/kimi-code/src/tui/utils/image-attachment-store.ts
@@ -42,6 +42,24 @@ export interface ImageAttachment {
    * knows it received a downsampled copy. Absent for untouched pastes.
    */
   readonly original?: ImageAttachmentOriginal | undefined;
+  /**
+   * Daemon file-store id, set when the bytes were uploaded at paste time
+   * (v2 engine only). Submit-time expansion then emits a `kimi-file://`
+   * reference plus an `<image path>` tag instead of inline base64; absent
+   * means the inline form is used.
+   */
+  fileId?: string;
+  /** Epoch milliseconds when the daemon staging upload expires. */
+  fileExpiresAt?: number;
+  /**
+   * Background ingestion (compression/original persistence/daemon upload)
+   * still in flight. The paste callback settles once the placeholder is in
+   * the editor — typing never waits on this — but submit holds it briefly
+   * (`pendingImageIngestions`) so a fast paste-then-Enter still gets the
+   * compressed/ref form; a slow ingestion submits the inline form instead.
+   * Cleared when ingestion completes.
+   */
+  pending?: Promise<void>;
   /** Rendered placeholder string, e.g. `[image #1 (640×480)]`. */
   readonly placeholder: string;
 }
@@ -59,9 +77,18 @@ export interface VideoAttachment {
 
 export type MediaAttachment = ImageAttachment | VideoAttachment;
 
+type MutableImageAttachment = {
+  -readonly [Property in keyof ImageAttachment]: ImageAttachment[Property];
+};
+
+type MutableVideoAttachment = {
+  -readonly [Property in keyof VideoAttachment]: VideoAttachment[Property];
+};
+
 export class ImageAttachmentStore {
   private nextId = 1;
   private readonly byId = new Map<number, MediaAttachment>();
+  private readonly stagingUses = new Map<number, number>();
 
   addImage(
     bytes: Uint8Array,
@@ -69,6 +96,8 @@ export class ImageAttachmentStore {
     width: number,
     height: number,
     original?: ImageAttachmentOriginal,
+    fileId?: string,
+    fileExpiresAt?: number,
   ): ImageAttachment {
     const id = this.nextId;
     this.nextId += 1;
@@ -80,6 +109,8 @@ export class ImageAttachmentStore {
       width,
       height,
       original,
+      fileId,
+      fileExpiresAt,
       placeholder: formatPlaceholder(id, width, height),
     };
     this.byId.set(id, attachment);
@@ -106,26 +137,136 @@ export class ImageAttachmentStore {
     return attachment;
   }
 
+  /**
+   * Complete an image that was inserted into the editor before its ingestion
+   * work (compression/original persistence/upload) finished. Returns undefined
+   * when the attachment was cleared while that work was in flight.
+   */
+  completeImage(
+    attachment: ImageAttachment,
+    input: {
+      bytes: Uint8Array;
+      mime: string;
+      width: number;
+      height: number;
+      original?: ImageAttachmentOriginal;
+      fileId?: string;
+      fileExpiresAt?: number;
+    },
+  ): ImageAttachment | undefined {
+    const current = this.byId.get(attachment.id);
+    if (current !== attachment || attachment.kind !== 'image') return undefined;
+    const mutable = attachment as MutableImageAttachment;
+    mutable.bytes = input.bytes;
+    mutable.mime = input.mime;
+    mutable.width = input.width;
+    mutable.height = input.height;
+    mutable.original = input.original;
+    mutable.fileId = input.fileId;
+    mutable.fileExpiresAt = input.fileExpiresAt;
+    mutable.pending = undefined;
+    mutable.placeholder = formatPlaceholder(attachment.id, input.width, input.height);
+    return attachment;
+  }
+
   get(id: number): MediaAttachment | undefined {
     return this.byId.get(id);
   }
 
-  clear(): void {
+  clear(): readonly string[] {
+    const fileIds = this.fileIds();
     this.byId.clear();
+    this.stagingUses.clear();
     this.nextId = 1;
+    return fileIds;
   }
 
   /**
    * Drop a single attachment, releasing its bytes. Used to reclaim image
    * memory once the transcript entry that references it is trimmed.
    */
-  remove(id: number): void {
+  remove(id: number): string | undefined {
+    const attachment = this.byId.get(id);
+    const fileId = attachment?.kind === 'image' ? attachment.fileId : undefined;
     this.byId.delete(id);
+    this.stagingUses.delete(id);
+    return fileId;
   }
 
   /** Drop many attachments at once. See {@link remove}. */
-  removeMany(ids: Iterable<number>): void {
-    for (const id of ids) this.byId.delete(id);
+  removeMany(ids: Iterable<number>): readonly string[] {
+    const fileIds: string[] = [];
+    for (const id of ids) {
+      const fileId = this.remove(id);
+      if (fileId !== undefined) fileIds.push(fileId);
+    }
+    return fileIds;
+  }
+
+  retainFileIds(ids: Iterable<number>): void {
+    const retained = new Set<number>();
+    for (const id of ids) {
+      if (retained.has(id)) continue;
+      retained.add(id);
+      const attachment = this.byId.get(id);
+      if (attachment?.kind !== 'image' || attachment.fileId === undefined) continue;
+      this.stagingUses.set(id, (this.stagingUses.get(id) ?? 0) + 1);
+    }
+  }
+
+  takeFileIds(ids: Iterable<number>): readonly string[] {
+    const fileIds: string[] = [];
+    const taken = new Set<number>();
+    for (const id of ids) {
+      if (taken.has(id)) continue;
+      taken.add(id);
+      const attachment = this.byId.get(id);
+      if (attachment?.kind !== 'image' || attachment.fileId === undefined) continue;
+      const uses = this.stagingUses.get(id) ?? 0;
+      if (uses > 1) {
+        this.stagingUses.set(id, uses - 1);
+        continue;
+      }
+      this.stagingUses.delete(id);
+      fileIds.push(attachment.fileId);
+      attachment.fileId = undefined;
+      attachment.fileExpiresAt = undefined;
+    }
+    return fileIds;
+  }
+
+  /**
+   * Consume the retains a recalled submission held WITHOUT taking the staged
+   * files: the recalled draft still references the attachments, so their
+   * daemon uploads stay alive and the next submit re-retains them. Used by
+   * queue recall; every other release path goes through {@link takeFileIds}.
+   */
+  releaseRetains(ids: Iterable<number>): void {
+    const released = new Set<number>();
+    for (const id of ids) {
+      if (released.has(id)) continue;
+      released.add(id);
+      const uses = this.stagingUses.get(id) ?? 0;
+      if (uses > 1) this.stagingUses.set(id, uses - 1);
+      else this.stagingUses.delete(id);
+    }
+  }
+
+  /**
+   * Repoint a recalled video at its staged cache copy: the original source
+   * (e.g. a clipboard temp file) may be gone by the time the restored draft
+   * is resubmitted, and re-extraction re-materializes from `sourcePath`.
+   */
+  rebaseVideoSource(id: number, sourcePath: string): void {
+    const attachment = this.byId.get(id);
+    if (attachment?.kind !== 'video') return;
+    (attachment as MutableVideoAttachment).sourcePath = sourcePath;
+  }
+
+  private fileIds(): readonly string[] {
+    return [...this.byId.values()]
+      .filter((attachment): attachment is ImageAttachment => attachment.kind === 'image')
+      .flatMap((attachment) => attachment.fileId ?? []);
   }
 
   size(): number {
diff --git a/apps/kimi-code/src/tui/utils/image-placeholder.ts b/apps/kimi-code/src/tui/utils/image-placeholder.ts
index 87d53eabc29..ab5bef2cd9c 100644
--- a/apps/kimi-code/src/tui/utils/image-placeholder.ts
+++ b/apps/kimi-code/src/tui/utils/image-placeholder.ts
@@ -5,7 +5,13 @@
  * `extractMediaAttachments` (sync) is the single expansion path for prompts:
  *   - image placeholders expand to inline image content parts (preceded by a
  *     compression caption when paste-time compression shrank the bytes — see
- *     `ImageAttachment.original`);
+ *     `ImageAttachment.original`). When the paste was uploaded to the daemon
+ *     file store (`ImageAttachment.fileId`, v2 engine only), the placeholder
+ *     instead expands to a bare `kimi-file://<id>` image part — the engine's
+ *     prompt intake materializes the session copy and rewrites the reference
+ *     with its `?path=`, making the part self-contained (no paired tag is
+ *     authored); without a `fileId` the inline base64 form is emitted
+ *     unchanged (the only form the v1 engine accepts);
  *   - video placeholders are copied into the shared cache (`getCacheDir()`)
  *     and expand to a `video_url` part pointing at the cache copy with a
  *     `file://` url. The v1 engine resolves that local reference inside the
@@ -29,15 +35,20 @@
  */
 
 import { randomUUID } from 'node:crypto';
-import { copyFileSync, mkdirSync, writeFileSync } from 'node:fs';
+import { copyFileSync, mkdirSync, unlinkSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { pathToFileURL } from 'node:url';
 
 import type { PromptPart } from '@moonshot-ai/kimi-code-sdk';
-import { buildImageCompressionCaption } from '@moonshot-ai/kimi-code-sdk';
+import {
+  buildDaemonFileUrl,
+  buildImageCompressionCaption,
+  buildMediaPathTag,
+} from '@moonshot-ai/kimi-code-sdk';
 
 import { getCacheDir } from '#/utils/paths';
 
+import { IMAGE_FILE_REF_MIN_REMAINING_MS } from '../constant/media';
 import type {
   ImageAttachment,
   ImageAttachmentStore,
@@ -58,6 +69,24 @@ export interface ExtractionResult {
   imageAttachmentIds: number[];
   /** Video attachment ids matched, in the order they appeared. */
   videoAttachmentIds: number[];
+  /**
+   * Image bytes captured while extracting the prompt. A cache-hint resend can
+   * outlive the attachment store and daemon file ids, so it uses these
+   * snapshots to rebuild the image parts as inline data URLs.
+   */
+  imageSnapshots: ImageResendSnapshot[];
+  /**
+   * Cache copies staged by this submission. Lifecycle is owned by the
+   * StagingLeaseTracker: deleted immediately when the submission is
+   * abandoned, retired to session lifetime once a turn consumes them
+   * (persisted history may still reference their paths).
+   */
+  stagingPaths: string[];
+}
+
+export interface ImageResendSnapshot {
+  readonly bytes: Uint8Array;
+  readonly mime: string;
 }
 
 export function extractMediaAttachments(
@@ -67,51 +96,205 @@ export function extractMediaAttachments(
   const parts: PromptPart[] = [];
   const imageAttachmentIds: number[] = [];
   const videoAttachmentIds: number[] = [];
+  const imageSnapshots: ImageResendSnapshot[] = [];
+  const stagingPaths: string[] = [];
   let cursor = 0;
   let hasMedia = false;
 
+  try {
+    PLACEHOLDER_REGEX.lastIndex = 0;
+    let match: RegExpExecArray | null;
+    while ((match = PLACEHOLDER_REGEX.exec(text)) !== null) {
+      const [literal, kind, idStr] = match;
+      if (kind !== 'image' && kind !== 'video') continue;
+      if (idStr === undefined) continue;
+      const id = Number.parseInt(idStr, 10);
+      const attachment = store.get(id);
+      if (attachment === undefined) continue; // stale / user-typed — leave as text
+      if (attachment.kind !== kind) continue;
+      const before = text.slice(cursor, match.index);
+      pushText(parts, before);
+      if (attachment.kind === 'video') {
+        // Copy the paste into the shared cache and reference it by a `file://`
+        // url; the engine resolves (uploads or degrades) it inside the turn.
+        const cachePath = materializeVideoToCache(attachment);
+        stagingPaths.push(cachePath);
+        parts.push(videoPartForCachePath(cachePath));
+        videoAttachmentIds.push(id);
+      } else {
+        imageSnapshots.push({ bytes: attachment.bytes, mime: attachment.mime });
+        // Paste-time compression is announced next to the image so the model
+        // knows it received a downsampled copy and where the original lives.
+        if (attachment.original !== undefined) {
+          pushText(parts, captionForCompressedImage(attachment));
+        }
+        if (attachment.fileId !== undefined) {
+          // The bytes were uploaded to the daemon file store at paste time
+          // (v2): reference them by a bare `kimi-file://` url — the engine's
+          // prompt intake materializes the session copy and rewrites the
+          // reference with its `?path=`, so the edge stages no local copy.
+          parts.push({
+            type: 'image_url',
+            imageUrl: { url: buildDaemonFileUrl(attachment.fileId) },
+          });
+        } else {
+          parts.push(imagePartForAttachment(attachment));
+        }
+        imageAttachmentIds.push(id);
+      }
+      hasMedia = true;
+      cursor = match.index + literal.length;
+    }
+    const tail = text.slice(cursor);
+    pushText(parts, tail);
+
+    store.retainFileIds(imageAttachmentIds);
+    const freshParts = refreshExpiringImageFileRefs(parts, imageAttachmentIds, store);
+    return {
+      // Text-only submissions drop the synthesised parts array — the
+      // caller's contract is "parts is meaningful iff hasMedia", and
+      // emitting a stray TextPart confuses consumers that branch on
+      // `parts.length > 0`.
+      parts: hasMedia ? freshParts : [],
+      hasMedia,
+      imageAttachmentIds,
+      videoAttachmentIds,
+      imageSnapshots,
+      stagingPaths,
+    };
+  } catch (error) {
+    cleanupStagingPaths(stagingPaths);
+    throw error;
+  }
+}
+
+/**
+ * The video attachment ids referenced by `text`, in placeholder order — the
+ * same order extraction staged their cache copies in, so callers can zip the
+ * result with a submission's `stagingPaths`.
+ */
+export function videoAttachmentIdsInText(text: string, store: ImageAttachmentStore): number[] {
+  const ids: number[] = [];
   PLACEHOLDER_REGEX.lastIndex = 0;
   let match: RegExpExecArray | null;
   while ((match = PLACEHOLDER_REGEX.exec(text)) !== null) {
-    const [literal, kind, idStr] = match;
-    if (kind !== 'image' && kind !== 'video') continue;
-    if (idStr === undefined) continue;
+    const [, kind, idStr] = match;
+    if (kind !== 'video' || idStr === undefined) continue;
     const id = Number.parseInt(idStr, 10);
-    const attachment = store.get(id);
-    if (attachment === undefined) continue; // stale / user-typed — leave as text
-    if (attachment.kind !== kind) continue;
-    const before = text.slice(cursor, match.index);
-    pushText(parts, before);
-    if (attachment.kind === 'video') {
-      // Copy the paste into the shared cache and reference it by a `file://`
-      // url; the engine resolves (uploads or degrades) it inside the turn.
-      const cachePath = materializeVideoToCache(attachment);
-      parts.push(videoPartForCachePath(cachePath));
-      videoAttachmentIds.push(id);
-    } else {
-      // Paste-time compression is announced next to the image so the model
-      // knows it received a downsampled copy and where the original lives.
-      if (attachment.original !== undefined) {
-        pushText(parts, captionForCompressedImage(attachment));
-      }
-      parts.push(imagePartForAttachment(attachment));
-      imageAttachmentIds.push(id);
+    if (store.get(id)?.kind === 'video') ids.push(id);
+  }
+  return ids;
+}
+
+/**
+ * Give images referenced by `text` a bounded moment to finish their
+ * background paste ingestion (compression/upload — see `ImageAttachment.pending`)
+ * before extraction, so a paste-then-immediately-submit still expands to the
+ * compressed/daemon-ref form. The returned promise resolves after `timeoutMs`
+ * at the latest; whatever has not landed by then simply extracts to the
+ * inline fallback form. Returns undefined when nothing is pending, so the
+ * submit path stays synchronous for media-free prompts.
+ */
+export function pendingImageIngestions(
+  text: string,
+  store: ImageAttachmentStore,
+  timeoutMs: number,
+): Promise<void> | undefined {
+  const pendings: Promise<void>[] = [];
+  PLACEHOLDER_REGEX.lastIndex = 0;
+  let match: RegExpExecArray | null;
+  while ((match = PLACEHOLDER_REGEX.exec(text)) !== null) {
+    const [, kind, idStr] = match;
+    if (kind !== 'image' || idStr === undefined) continue;
+    const attachment = store.get(Number.parseInt(idStr, 10));
+    if (attachment?.kind === 'image' && attachment.pending !== undefined) {
+      pendings.push(attachment.pending);
     }
-    hasMedia = true;
-    cursor = match.index + literal.length;
   }
-  const tail = text.slice(cursor);
-  pushText(parts, tail);
+  if (pendings.length === 0) return undefined;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  return Promise.race([
+    Promise.allSettled(pendings).then(() => undefined),
+    new Promise<void>((resolve) => {
+      timer = setTimeout(resolve, timeoutMs);
+    }),
+  ]).finally(() => {
+    clearTimeout(timer);
+  });
+}
+
+/**
+ * Replace daemon refs that may expire before validation reaches the server
+ * with the attachment's retained bytes. Called both at extraction time and
+ * again when a queued/cache-hint submission is actually dispatched.
+ */
+export function refreshExpiringImageFileRefs(
+  parts: readonly PromptPart[],
+  imageAttachmentIds: readonly number[],
+  store: ImageAttachmentStore,
+  now = Date.now(),
+): PromptPart[] {
+  if (imageAttachmentIds.length === 0) return [...parts];
+  let imageIndex = 0;
+  let changed = false;
+  const next = parts.map((part) => {
+    if (part.type !== 'image_url') return part;
+    const attachmentId = imageAttachmentIds[imageIndex++];
+    if (attachmentId === undefined || !part.imageUrl.url.startsWith('kimi-file://')) return part;
+    const attachment = store.get(attachmentId);
+    if (attachment?.kind !== 'image') return part;
+
+    const fileId = attachment.fileId;
+    const expiresAt = attachment.fileExpiresAt;
+    const usable =
+      fileId !== undefined &&
+      (expiresAt === undefined || expiresAt - now > IMAGE_FILE_REF_MIN_REMAINING_MS);
+    if (usable) {
+      const url = buildDaemonFileUrl(fileId);
+      if (url === part.imageUrl.url) return part;
+      changed = true;
+      return { ...part, imageUrl: { ...part.imageUrl, url } };
+    }
+
+    attachment.fileId = undefined;
+    attachment.fileExpiresAt = undefined;
+    changed = true;
+    return imagePartForAttachment(attachment);
+  });
+  return changed ? next : [...parts];
+}
+
+/**
+ * Make an extraction safe to resend after a session reset. The reset clears
+ * the image store and deletes daemon file ids, so uploaded image refs must be
+ * replaced with the bytes captured during the original extraction. Cache
+ * paths are intentionally preserved: they are carried by the resend's new
+ * staging lease and remain available to any path tag in the prompt.
+ */
+export function makeExtractionResendable(extraction: ExtractionResult): ExtractionResult {
+  if (extraction.imageSnapshots.length === 0) return extraction;
+
+  let imageIndex = 0;
+  const parts = extraction.parts.map((part) => {
+    if (part.type !== 'image_url') return part;
+    const snapshot = extraction.imageSnapshots[imageIndex++];
+    if (snapshot === undefined || !part.imageUrl.url.startsWith('kimi-file://')) return part;
+    return {
+      ...part,
+      imageUrl: {
+        ...part.imageUrl,
+        url: `data:${snapshot.mime};base64,${Buffer.from(snapshot.bytes).toString('base64')}`,
+      },
+    };
+  });
 
   return {
-    // Text-only submissions drop the synthesised parts array — the
-    // caller's contract is "parts is meaningful iff hasMedia", and
-    // emitting a stray TextPart confuses consumers that branch on
-    // `parts.length > 0`.
-    parts: hasMedia ? parts : [],
-    hasMedia,
-    imageAttachmentIds,
-    videoAttachmentIds,
+    ...extraction,
+    parts,
+    // The new session's store no longer contains these ids. The rebuilt parts
+    // carry their own bytes, so keeping stale ids would break thumbnail and
+    // later cleanup lookups.
+    imageAttachmentIds: [],
   };
 }
 
@@ -121,6 +304,7 @@ export interface MediaTagRewriteResult {
   hasMedia: boolean;
   imageAttachmentIds: number[];
   videoAttachmentIds: number[];
+  stagingPaths: string[];
 }
 
 /**
@@ -152,39 +336,65 @@ export function rewriteMediaPlaceholders(
 ): MediaTagRewriteResult {
   const imageAttachmentIds: number[] = [];
   const videoAttachmentIds: number[] = [];
+  const stagingPaths: string[] = [];
   let cursor = 0;
   let out = '';
 
-  PLACEHOLDER_REGEX.lastIndex = 0;
-  let match: RegExpExecArray | null;
-  while ((match = PLACEHOLDER_REGEX.exec(text)) !== null) {
-    const [literal, kind, idStr] = match;
-    if (kind !== 'image' && kind !== 'video') continue;
-    if (idStr === undefined) continue;
-    const id = Number.parseInt(idStr, 10);
-    const attachment = store.get(id);
-    if (attachment === undefined) continue; // stale / user-typed — leave as text
-    if (attachment.kind !== kind) continue;
-    out += text.slice(cursor, match.index);
-    if (attachment.kind === 'video') {
-      const path = materializeVideoToCache(attachment, style === 'plain');
-      out += style === 'plain' ? formatMediaReference('video', path) : formatMediaTag('video', path);
-      videoAttachmentIds.push(id);
-    } else {
-      const path = materializeImageToCache(attachment);
-      out += style === 'plain' ? formatMediaReference('image', path) : formatMediaTag('image', path);
-      imageAttachmentIds.push(id);
+  try {
+    PLACEHOLDER_REGEX.lastIndex = 0;
+    let match: RegExpExecArray | null;
+    while ((match = PLACEHOLDER_REGEX.exec(text)) !== null) {
+      const [literal, kind, idStr] = match;
+      if (kind !== 'image' && kind !== 'video') continue;
+      if (idStr === undefined) continue;
+      const id = Number.parseInt(idStr, 10);
+      const attachment = store.get(id);
+      if (attachment === undefined) continue; // stale / user-typed — leave as text
+      if (attachment.kind !== kind) continue;
+      out += text.slice(cursor, match.index);
+      if (attachment.kind === 'video') {
+        const path = materializeVideoToCache(attachment, style === 'plain');
+        stagingPaths.push(path);
+        out +=
+          style === 'plain'
+            ? formatMediaReference('video', path)
+            : buildMediaPathTag('video', path);
+        videoAttachmentIds.push(id);
+      } else {
+        const path = materializeImageToCache(attachment);
+        stagingPaths.push(path);
+        out +=
+          style === 'plain'
+            ? formatMediaReference('image', path)
+            : buildMediaPathTag('image', path);
+        imageAttachmentIds.push(id);
+      }
+      cursor = match.index + literal.length;
     }
-    cursor = match.index + literal.length;
+
+    const hasMedia = imageAttachmentIds.length + videoAttachmentIds.length > 0;
+    store.retainFileIds(imageAttachmentIds);
+    return {
+      text: hasMedia ? out + text.slice(cursor) : text,
+      hasMedia,
+      imageAttachmentIds,
+      videoAttachmentIds,
+      stagingPaths,
+    };
+  } catch (error) {
+    cleanupStagingPaths(stagingPaths);
+    throw error;
   }
+}
 
-  const hasMedia = imageAttachmentIds.length + videoAttachmentIds.length > 0;
-  return {
-    text: hasMedia ? out + text.slice(cursor) : text,
-    hasMedia,
-    imageAttachmentIds,
-    videoAttachmentIds,
-  };
+function cleanupStagingPaths(paths: readonly string[]): void {
+  for (const path of paths) {
+    try {
+      unlinkSync(path);
+    } catch {
+      // Best effort: a failed copy may not have created the target.
+    }
+  }
 }
 
 function pushText(parts: PromptPart[], segment: string): void {
@@ -242,13 +452,21 @@ const IMAGE_MIME_EXTENSION: Readonly<Record<string, string>> = {
   'image/tiff': 'tif',
 };
 
+/**
+ * File-extension hint for an image MIME (`image/png` → `png`). The real
+ * format is always sniffed from the bytes, so this only names files (cache
+ * copies, daemon upload labels).
+ */
+export function imageExtensionForMime(mime: string): string {
+  return IMAGE_MIME_EXTENSION[mime.trim().toLowerCase()] ?? 'img';
+}
+
 function materializeImageToCache(att: ImageAttachment): string {
   const cacheDir = getCacheDir();
   mkdirSync(cacheDir, { recursive: true });
   // ReadMediaFile sniffs the real format from the bytes, so the extension
   // only needs to be a reasonable hint.
-  const ext = IMAGE_MIME_EXTENSION[att.mime.trim().toLowerCase()] ?? 'img';
-  const target = join(cacheDir, `${randomUUID()}.${ext}`);
+  const target = join(cacheDir, `${randomUUID()}.${imageExtensionForMime(att.mime)}`);
   writeFileSync(target, att.bytes);
   return target;
 }
@@ -273,10 +491,6 @@ function captionForCompressedImage(att: ImageAttachment): string {
   });
 }
 
-function formatMediaTag(tag: 'image' | 'video', path: string): string {
-  return `<${tag} path="${escapeAttribute(path)}"></${tag}>`;
-}
-
 /**
  * Plain-text media reference for channels that XML-escape args (`/skill`).
  * Free of `& < > "` (UUID image names; boundary chars stripped from video
@@ -286,11 +500,3 @@ function formatMediaTag(tag: 'image' | 'video', path: string): string {
 function formatMediaReference(kind: 'image' | 'video', path: string): string {
   return `Attached ${kind} file: ${path} (open it with ReadMediaFile)`;
 }
-
-function escapeAttribute(value: string): string {
-  return value
-    .replaceAll('&', '&amp;')
-    .replaceAll('"', '&quot;')
-    .replaceAll('<', '&lt;')
-    .replaceAll('>', '&gt;');
-}
diff --git a/apps/kimi-code/src/tui/utils/media-url.ts b/apps/kimi-code/src/tui/utils/media-url.ts
index f04edeb2929..14bc4eba8e4 100644
--- a/apps/kimi-code/src/tui/utils/media-url.ts
+++ b/apps/kimi-code/src/tui/utils/media-url.ts
@@ -1,3 +1,5 @@
+import { isDaemonFileUrl } from '@moonshot-ai/kimi-code-sdk';
+
 export type MediaUrlKind = 'audio' | 'image' | 'video';
 
 export function mediaUrlPartToText(kind: MediaUrlKind, url: string): string {
@@ -6,6 +8,10 @@ export function mediaUrlPartToText(kind: MediaUrlKind, url: string): string {
     const size = summary.bytes !== undefined ? `, ${formatByteSize(summary.bytes)}` : '';
     return `[${kind} ${summary.mime}${size}]`;
   }
+  // An internal daemon file reference (`kimi-file://…?path=…`) never renders
+  // its wire form: the scheme resolves nowhere for the user and the query
+  // carries the materialization path. Render the bare placeholder instead.
+  if (isDaemonFileUrl(url)) return `[${kind}]`;
   return `<${kind} url="${escapeAttribute(url)}">`;
 }
 
diff --git a/apps/kimi-code/src/tui/utils/message-replay.ts b/apps/kimi-code/src/tui/utils/message-replay.ts
index 83ec5e375cd..1ef5c544c41 100644
--- a/apps/kimi-code/src/tui/utils/message-replay.ts
+++ b/apps/kimi-code/src/tui/utils/message-replay.ts
@@ -230,6 +230,10 @@ export function toolResultOutput(content: readonly ContentPart[]): string {
 }
 
 export function contentPartsToText(content: readonly ContentPart[]): string {
+  // A daemon-ref media part is self-contained and renders as a bare
+  // `[image]`/`[video]` placeholder downstream — neither the materialization
+  // path nor the internal `kimi-file://` url may surface as user text. A
+  // standalone `<media path>` tag is user text and stays verbatim.
   return content.map(contentPartToText).join('');
 }
 
diff --git a/apps/kimi-code/src/tui/utils/steer-input.ts b/apps/kimi-code/src/tui/utils/steer-input.ts
new file mode 100644
index 00000000000..d69c999d8de
--- /dev/null
+++ b/apps/kimi-code/src/tui/utils/steer-input.ts
@@ -0,0 +1,56 @@
+/**
+ * Steer-input composition for `session.steer`: flattens queued items (and the
+ * editor draft) into one payload — the historical `'\n\n'`-joined string when
+ * nothing carries media, or a merged part list when any item has extracted
+ * media parts (queued image messages, or the editor draft after placeholder
+ * extraction). Media parts are self-contained daemon references; no machine
+ * `<media path>` tag is authored, so text parts always merge freely.
+ */
+
+import type { PromptPart } from '@moonshot-ai/kimi-code-sdk';
+
+import type { SteerInputItem } from '../types';
+
+/**
+ * Flatten steer items into the payload `session.steer` expects.
+ *
+ * Items are separated by the historical `'\n\n'`, which merges into the
+ * adjacent text part. The one exception is two touching media parts: a
+ * standalone `{type:'text',text:'\n\n'}` between them would be rejected
+ * by `normalizePromptInput` as an empty text part, so the separator is
+ * dropped there (media parts are self-delimiting anyway).
+ */
+export function combineSteerInput(items: readonly SteerInputItem[]): string | PromptPart[] {
+  const hasMedia = items.some((item) => item.parts !== undefined && item.parts.length > 0);
+  if (!hasMedia) return items.map((item) => item.text).join('\n\n');
+  const parts: PromptPart[] = [];
+  for (const item of items) {
+    const first = item.parts?.[0];
+    const startsWithMedia = first !== undefined && first.type !== 'text';
+    const lastIsMedia = parts.length > 0 && parts.at(-1)?.type !== 'text';
+    if (parts.length > 0 && !(lastIsMedia && startsWithMedia)) {
+      appendSteerText(parts, '\n\n');
+    }
+    if (item.parts !== undefined && item.parts.length > 0) {
+      for (const part of item.parts) {
+        if (part.type !== 'text') {
+          parts.push(part);
+          continue;
+        }
+        appendSteerText(parts, part.text);
+      }
+    } else {
+      appendSteerText(parts, item.text);
+    }
+  }
+  return parts;
+}
+
+function appendSteerText(parts: PromptPart[], text: string): void {
+  const last = parts.at(-1);
+  if (last?.type === 'text') {
+    parts[parts.length - 1] = { type: 'text', text: last.text + text };
+    return;
+  }
+  parts.push({ type: 'text', text });
+}
diff --git a/apps/kimi-code/test/tui/components/editor/custom-editor.test.ts b/apps/kimi-code/test/tui/components/editor/custom-editor.test.ts
index a2755d2ea0e..6b68d83e197 100644
--- a/apps/kimi-code/test/tui/components/editor/custom-editor.test.ts
+++ b/apps/kimi-code/test/tui/components/editor/custom-editor.test.ts
@@ -615,6 +615,33 @@ describe('CustomEditor paste marker expansion', () => {
       process.off('unhandledRejection', onRejection);
     }
   });
+
+  it('queues Enter and typing until an asynchronous image paste inserts its placeholder', async () => {
+    const editor = makeEditor();
+    const submit = vi.fn();
+    editor.onSubmit = submit;
+    let resolvePaste!: (handled: boolean) => void;
+    editor.onPasteImage = () =>
+      new Promise<boolean>((resolve) => {
+        resolvePaste = (handled) => {
+          editor.insertTextAtCursor?.('[image #1 (1×1)] ');
+          resolve(handled);
+        };
+      });
+
+    const pasteKey = process.platform === 'win32' ? '\u001Bv' : '\u0016';
+    editor.handleInput(pasteKey);
+    editor.handleInput('hello');
+    editor.handleInput('\r');
+
+    expect(editor.getText()).toBe('');
+    expect(submit).not.toHaveBeenCalled();
+
+    resolvePaste(true);
+    await new Promise((resolve) => setImmediate(resolve));
+
+    expect(submit).toHaveBeenCalledWith('[image #1 (1×1)] hello');
+  });
 });
 
 describe('CustomEditor shortcut telemetry hooks', () => {
diff --git a/apps/kimi-code/test/tui/controllers/cache-hint-controller.test.ts b/apps/kimi-code/test/tui/controllers/cache-hint-controller.test.ts
index 7e71860629d..2dd5871ba40 100644
--- a/apps/kimi-code/test/tui/controllers/cache-hint-controller.test.ts
+++ b/apps/kimi-code/test/tui/controllers/cache-hint-controller.test.ts
@@ -5,6 +5,7 @@ import {
   type CacheHintHost,
 } from '#/tui/controllers/cache-hint-controller';
 import type { CacheHintConfig } from '#/utils/cache-hint-config';
+import type { ExtractionResult } from '#/tui/utils/image-placeholder';
 
 const peekMock = vi.fn<() => CacheHintConfig | undefined>(() => undefined);
 const getMock = vi.fn(async (): Promise<CacheHintConfig | undefined> => undefined);
@@ -52,6 +53,7 @@ function makeHost(
     mountEditorReplacement: vi.fn(),
     restoreEditor: vi.fn(),
     restoreInputText: vi.fn(),
+    recallStashedMedia: vi.fn(),
     showError: vi.fn(),
     createNewSession: vi.fn(async () => {
       if (overrides.createNewSessionFails !== true) state.appState.sessionId = 's2';
@@ -81,6 +83,24 @@ async function flush(times = 20): Promise<void> {
   for (let i = 0; i < times; i++) await new Promise((r) => setImmediate(r));
 }
 
+function uploadedExtraction(fileId: string, byte: number): ExtractionResult {
+  const path = `/tmp/${fileId}.png`;
+  return {
+    parts: [
+      { type: 'text', text: `<image path="${path}"></image>` },
+      {
+        type: 'image_url',
+        imageUrl: { url: `kimi-file://${fileId}?path=${encodeURIComponent(path)}` },
+      },
+    ],
+    hasMedia: true,
+    imageAttachmentIds: [1],
+    videoAttachmentIds: [],
+    imageSnapshots: [{ bytes: new Uint8Array([byte]), mime: 'image/png' }],
+    stagingPaths: [path],
+  };
+}
+
 beforeEach(() => {
   peekMock.mockReset().mockReturnValue(undefined);
   getMock.mockReset().mockResolvedValue(undefined);
@@ -228,6 +248,34 @@ describe('CacheHintController scenario 2 (idle submit)', () => {
     expect(host.restoreInputText).toHaveBeenLastCalledWith('hello\nworld');
   });
 
+  it('releases stashed media with recall semantics when the dialog is dismissed', async () => {
+    getMock.mockResolvedValue(CONFIG);
+    const { host } = makeHost();
+    const controller = new CacheHintController(host);
+    controller.recordActivity();
+    vi.spyOn(Date, 'now').mockReturnValue(Date.now() + 1200_000);
+    const extraction = uploadedExtraction('file-1', 1);
+
+    expect(controller.maybeInterceptOnSubmit('describe [image #1 (1×1)]', extraction)).toBe(true);
+    await vi.waitFor(() => {
+      expect(host.mountEditorReplacement).toHaveBeenCalled();
+    });
+    vi.restoreAllMocks();
+
+    const dialog = (host.mountEditorReplacement as ReturnType<typeof vi.fn>).mock.calls[0]![0] as {
+      handleInput: (data: string) => void;
+    };
+    dialog.handleInput('\u001B'); // dismiss
+    await flush();
+
+    // Nothing was sent; the draft is back in the editor and the stash's
+    // retains/staged copies go through recall — without this the retain count
+    // never returns to zero and the upload can never be lease-deleted.
+    expect(host.sendNormalUserInput).not.toHaveBeenCalled();
+    expect(host.restoreInputText).toHaveBeenCalledWith('describe [image #1 (1×1)]');
+    expect(host.recallStashedMedia).toHaveBeenCalledWith('describe [image #1 (1×1)]', extraction);
+  });
+
   it('hands the stashed input back when the session switched during the fetch', async () => {
     const { host } = makeHost();
     const controller = new CacheHintController(host);
@@ -382,6 +430,68 @@ describe('CacheHintController scenario 2 (idle submit)', () => {
     expect(host.sendNormalUserInput).toHaveBeenCalledWith('hello', undefined);
   });
 
+  it('resends an uploaded image inline after starting a new session', async () => {
+    peekMock.mockReturnValue(CONFIG);
+    const { host } = makeHost();
+    const controller = new CacheHintController(host);
+    controller.recordActivity();
+    vi.spyOn(Date, 'now').mockReturnValue(Date.now() + 1200_000);
+    const extraction = uploadedExtraction('file-1', 1);
+
+    controller.maybeInterceptOnSubmit('describe [image #1 (1×1)]', extraction);
+    vi.restoreAllMocks();
+
+    const dialog = (host.mountEditorReplacement as ReturnType<typeof vi.fn>).mock.calls[0]![0] as {
+      handleInput: (data: string) => void;
+    };
+    dialog.handleInput('\u001B[B');
+    dialog.handleInput('\r');
+    await flush();
+
+    const resend = vi.mocked(host.sendNormalUserInput).mock.calls[0]?.[1];
+    expect(resend?.imageAttachmentIds).toEqual([]);
+    expect(resend?.parts).toContainEqual({
+      type: 'image_url',
+      imageUrl: { url: 'data:image/png;base64,AQ==' },
+    });
+  });
+
+  it('resends every chained uploaded image inline after starting a new session', async () => {
+    getMock.mockResolvedValue(CONFIG);
+    const { host } = makeHost();
+    const controller = new CacheHintController(host);
+    controller.recordActivity();
+    vi.spyOn(Date, 'now').mockReturnValue(Date.now() + 1200_000);
+
+    expect(controller.maybeInterceptOnSubmit('first', uploadedExtraction('file-1', 1))).toBe(true);
+    expect(controller.maybeInterceptOnSubmit('second', uploadedExtraction('file-2', 2))).toBe(true);
+    await vi.waitFor(() => {
+      expect(host.mountEditorReplacement).toHaveBeenCalled();
+    });
+    vi.restoreAllMocks();
+
+    const dialog = (host.mountEditorReplacement as ReturnType<typeof vi.fn>).mock.calls[0]![0] as {
+      handleInput: (data: string) => void;
+    };
+    dialog.handleInput('\u001B[B');
+    dialog.handleInput('\r');
+    await flush();
+
+    const sendCalls = (
+      host.sendNormalUserInput as unknown as {
+        mock: { calls: Array<[string, ExtractionResult | undefined]> };
+      }
+    ).mock.calls;
+    const imageUrls = sendCalls.map(([, extraction]) => {
+      const imagePart = extraction?.parts.find((part) => part.type === 'image_url');
+      return imagePart?.type === 'image_url' ? imagePart.imageUrl.url : undefined;
+    });
+    expect(imageUrls).toEqual([
+      'data:image/png;base64,AQ==',
+      'data:image/png;base64,Ag==',
+    ]);
+  });
+
   it('keeps the input when new-session creation fails', async () => {
     peekMock.mockReturnValue(CONFIG);
     const { host, state } = makeHost({ createNewSessionFails: true });
diff --git a/apps/kimi-code/test/tui/controllers/editor-keyboard-image-paste.test.ts b/apps/kimi-code/test/tui/controllers/editor-keyboard-image-paste.test.ts
index b87b2d4d599..17e363e3e0e 100644
--- a/apps/kimi-code/test/tui/controllers/editor-keyboard-image-paste.test.ts
+++ b/apps/kimi-code/test/tui/controllers/editor-keyboard-image-paste.test.ts
@@ -10,6 +10,9 @@
  *     point the model at the full-fidelity bytes
  *   - a within-budget paste is stored byte-for-byte (fast path), with no
  *     original recorded
+ *   - on the v2 engine the final bytes are uploaded to the daemon file store
+ *     with a crash-recovery TTL, and the attachment carries the returned id
+ *     and expiry; an upload failure leaves the paste on the inline fallback
  */
 
 import { mkdtemp, readFile, rm, unlink } from 'node:fs/promises';
@@ -39,10 +42,23 @@ vi.mock('#/utils/clipboard/clipboard-image', async (importActual) => {
 interface PasteHarness {
   readonly store: ImageAttachmentStore;
   readonly track: ReturnType<typeof vi.fn>;
+  /** Invoke the paste handler, then wait for the background ingestion to settle. */
   pasteImage(): Promise<void>;
+  /** Invoke the paste handler only — background ingestion may still be pending. */
+  pasteImageRaw(): Promise<boolean>;
 }
 
-function createPasteHarness(options: { sessionDir?: string; imageLimits?: ImageLimits } = {}): PasteHarness {
+function createPasteHarness(
+  options: {
+    sessionDir?: string;
+    imageLimits?: ImageLimits;
+    engineV2?: boolean;
+    uploadFile?: (
+      data: Uint8Array,
+      opts: { name: string; mimeType?: string; expiresInSec?: number },
+    ) => Promise<{ id: string }>;
+  } = {},
+): PasteHarness {
   const editor: Record<string, ((...args: never[]) => unknown) | undefined> = {
     setHistoryFilter: vi.fn() as unknown as (...args: never[]) => unknown,
   };
@@ -61,28 +77,39 @@ function createPasteHarness(options: { sessionDir?: string; imageLimits?: ImageL
         ? undefined
         : { summary: { sessionDir: options.sessionDir } },
     btwPanelController: { closeOrCancel: vi.fn(() => false) },
+    engineV2: options.engineV2,
     track,
     showError: vi.fn(),
     openUndoSelector: vi.fn(),
     cancelRunningShellCommand: vi.fn(),
   } as unknown as EditorKeyboardHost;
-  if (options.imageLimits !== undefined) {
+  if (options.imageLimits !== undefined || options.uploadFile !== undefined) {
     (host as unknown as { harness: KimiHarness }).harness = {
       imageLimits: options.imageLimits,
+      uploadFile: options.uploadFile,
     } as unknown as KimiHarness;
   }
 
   const controller = new EditorKeyboardController(host, store);
   controller.install();
 
+  const pasteImageRaw = (): Promise<boolean> => {
+    const handler = editor['onPasteImage'];
+    if (handler === undefined) throw new Error('onPasteImage handler not installed');
+    return (handler as () => Promise<boolean>)();
+  };
+
   return {
     store,
     track,
     async pasteImage() {
-      const handler = editor['onPasteImage'];
-      if (handler === undefined) throw new Error('onPasteImage handler not installed');
-      await (handler as () => Promise<boolean>)();
+      await pasteImageRaw();
+      for (let id = 1; id <= store.size(); id++) {
+        const attachment = store.get(id);
+        if (attachment?.kind === 'image') await attachment.pending;
+      }
     },
+    pasteImageRaw,
   };
 }
 
@@ -98,6 +125,14 @@ async function solidJpeg(width: number, height: number): Promise<Uint8Array> {
   );
 }
 
+/** Typed `uploadFile` stub so `mock.calls` keeps the (data, options) tuple. */
+function uploadFileMock(id: string) {
+  return vi.fn(async (
+    _data: Uint8Array,
+    _opts: { name: string; mimeType?: string; expiresInSec?: number },
+  ) => ({ id, expires_at: '2030-01-02T03:04:05.000Z' }));
+}
+
 /**
  * Insert a minimal EXIF APP1 segment carrying only an Orientation tag right
  * after the JPEG SOI marker (jimp itself never writes EXIF). Mirrors the
@@ -296,4 +331,115 @@ describe('clipboard image paste compression', () => {
     expect(props['source']).toBe('tui_paste');
     expect(props['outcome']).toBe('compressed');
   });
+
+  it('uploads final bytes with a crash-recovery TTL while the staging lease owns normal cleanup', async () => {
+    const small = await solidPng(80, 80);
+    readClipboardMedia.mockResolvedValue({ kind: 'image', bytes: small, mimeType: 'image/png' });
+    const uploadFile = uploadFileMock('file-1');
+
+    const { store, pasteImage } = createPasteHarness({ engineV2: true, uploadFile });
+    await pasteImage();
+
+    const att = store.get(1);
+    if (att?.kind !== 'image') throw new Error('expected image attachment');
+    expect(att.fileId).toBe('file-1');
+    expect(att.fileExpiresAt).toBe(Date.parse('2030-01-02T03:04:05.000Z'));
+    expect(uploadFile).toHaveBeenCalledTimes(1);
+    const [data, opts] = uploadFile.mock.calls[0]!;
+    expect(new Uint8Array(data)).toEqual(small);
+    expect(opts).toEqual({
+      name: 'pasted-image.png',
+      mimeType: 'image/png',
+      expiresInSec: 60 * 60,
+    });
+    // The bytes stay on the attachment for the inline fallback / cache copy.
+    expect(att.bytes).toBe(small);
+  });
+
+  it('uploads the compressed bytes when paste-time compression changed them (v2)', async () => {
+    const big = await solidPng(3600, 1800);
+    readClipboardMedia.mockResolvedValue({ kind: 'image', bytes: big, mimeType: 'image/png' });
+    const uploadFile = uploadFileMock('file-9');
+
+    const { store, pasteImage } = createPasteHarness({ engineV2: true, uploadFile });
+    await pasteImage();
+
+    const att = store.get(1);
+    if (att?.kind !== 'image') throw new Error('expected image attachment');
+    expect(att.fileId).toBe('file-9');
+    // The upload carries exactly what the attachment stores — the compressed
+    // bytes, not the clipboard original.
+    const [data] = uploadFile.mock.calls[0]!;
+    expect(data).toBe(att.bytes);
+    expect(att.bytes).not.toBe(big);
+    await unlink(att.original!.path!).catch(() => undefined);
+  });
+
+  it('keeps the paste on the inline fallback when the daemon upload fails (v2)', async () => {
+    const small = await solidPng(80, 80);
+    readClipboardMedia.mockResolvedValue({ kind: 'image', bytes: small, mimeType: 'image/png' });
+    const uploadFile = vi.fn(
+      async (
+        _data: Uint8Array,
+        _opts: { name: string; mimeType?: string; expiresInSec?: number },
+      ): Promise<{ id: string }> => {
+        throw new Error('daemon down');
+      },
+    );
+
+    const { store, pasteImage } = createPasteHarness({ engineV2: true, uploadFile });
+    await pasteImage(); // must not throw
+
+    const att = store.get(1);
+    if (att?.kind !== 'image') throw new Error('expected image attachment');
+    expect(att.fileId).toBeUndefined();
+    expect(att.bytes).toBe(small);
+  });
+
+  it('never uploads on the v1 engine', async () => {
+    const small = await solidPng(80, 80);
+    readClipboardMedia.mockResolvedValue({ kind: 'image', bytes: small, mimeType: 'image/png' });
+    const uploadFile = uploadFileMock('file-1');
+
+    // engineV2 unset — the v1 host shape.
+    const { store, pasteImage } = createPasteHarness({ uploadFile });
+    await pasteImage();
+
+    expect(uploadFile).not.toHaveBeenCalled();
+    const att = store.get(1);
+    if (att?.kind !== 'image') throw new Error('expected image attachment');
+    expect(att.fileId).toBeUndefined();
+  });
+
+  it('settles the paste callback before the background daemon upload completes (v2)', async () => {
+    const small = await solidPng(80, 80);
+    readClipboardMedia.mockResolvedValue({ kind: 'image', bytes: small, mimeType: 'image/png' });
+    let resolveUpload!: (meta: { id: string }) => void;
+    const uploadFile = vi.fn(
+      (
+        _data: Uint8Array,
+        _opts: { name: string; mimeType?: string; expiresInSec?: number },
+      ): Promise<{ id: string }> =>
+        new Promise<{ id: string }>((resolve) => {
+          resolveUpload = resolve;
+        }),
+    );
+
+    const { store, pasteImageRaw } = createPasteHarness({ engineV2: true, uploadFile });
+    // The handler returns once the placeholder is in the editor; the upload
+    // is still unresolved here — typing is never held behind it.
+    await pasteImageRaw();
+
+    const att = store.get(1);
+    if (att?.kind !== 'image') throw new Error('expected image attachment');
+    expect(att.placeholder).toBe('[image #1 (80×80)]');
+    expect(att.fileId).toBeUndefined();
+    expect(att.pending).toBeDefined();
+
+    resolveUpload({ id: 'file-late' });
+    await att.pending;
+
+    expect(att.fileId).toBe('file-late');
+    expect(att.pending).toBeUndefined();
+  });
 });
diff --git a/apps/kimi-code/test/tui/controllers/staging-leases.test.ts b/apps/kimi-code/test/tui/controllers/staging-leases.test.ts
new file mode 100644
index 00000000000..43a599d4ae5
--- /dev/null
+++ b/apps/kimi-code/test/tui/controllers/staging-leases.test.ts
@@ -0,0 +1,364 @@
+import type { TurnEndedEvent, TurnStartedEvent } from '@moonshot-ai/kimi-code-sdk';
+import { describe, expect, it, vi } from 'vitest';
+
+import {
+  StagingLeaseTracker,
+  type StagingLeaseEffects,
+  type StagingLeaseOrigin,
+} from '#/tui/controllers/staging-leases';
+
+function turnStarted(turnId: number | string, kind: string, promptId?: string): TurnStartedEvent {
+  return { type: 'turn.started', agentId: 'main', turnId, origin: { kind }, promptId } as TurnStartedEvent;
+}
+
+function turnEnded(turnId: number | string): TurnEndedEvent {
+  return { type: 'turn.ended', agentId: 'main', turnId, reason: 'completed' } as TurnEndedEvent;
+}
+
+function makeEffects(): {
+  effects: StagingLeaseEffects;
+  takeFileIds: ReturnType<typeof vi.fn<(ids: readonly number[]) => readonly string[]>>;
+  releaseRetains: ReturnType<typeof vi.fn<(ids: readonly number[]) => void>>;
+  deleteFiles: ReturnType<
+    typeof vi.fn<(fileIds: readonly string[], paths: readonly string[]) => Promise<void>>
+  >;
+  warn: ReturnType<typeof vi.fn<(message: string) => void>>;
+  deleted: { fileIds: string[]; paths: string[] };
+} {
+  const deleted = { fileIds: [] as string[], paths: [] as string[] };
+  const takeFileIds = vi.fn((ids: readonly number[]) => ids.map((id) => `file-${id}`));
+  const releaseRetains = vi.fn((ids: readonly number[]) => void ids);
+  const deleteFiles = vi.fn((fileIds: readonly string[], paths: readonly string[]) => {
+    deleted.fileIds.push(...fileIds);
+    deleted.paths.push(...paths);
+    return Promise.resolve();
+  });
+  const warn = vi.fn((message: string) => void message);
+  return {
+    effects: { takeFileIds, releaseRetains, deleteFiles, warn },
+    takeFileIds,
+    releaseRetains,
+    deleteFiles,
+    warn,
+    deleted,
+  };
+}
+
+function makeTracker(): ReturnType<typeof makeEffects> & { tracker: StagingLeaseTracker } {
+  const mocks = makeEffects();
+  return { ...mocks, tracker: new StagingLeaseTracker(mocks.effects) };
+}
+
+describe('StagingLeaseTracker', () => {
+  describe('create', () => {
+    it('returns undefined when nothing is staged', () => {
+      const { tracker } = makeTracker();
+      expect(tracker.create([], [], 'user')).toBeUndefined();
+    });
+  });
+
+  describe('turn claiming', () => {
+    it('claims the earliest unbound lease of the matching origin', () => {
+      const { tracker } = makeTracker();
+      const first = tracker.create([], ['/cache/a'], 'user');
+      const second = tracker.create([], ['/cache/b'], 'user');
+
+      tracker.handleTurnStarted(turnStarted(1, 'user'));
+      expect(first?.turnId).toBe('1');
+      expect(second?.turnId).toBeUndefined();
+
+      tracker.handleTurnStarted(turnStarted(2, 'user'));
+      expect(second?.turnId).toBe('2');
+    });
+
+    it('warns when several unclaimed same-origin leases make the heuristic claim ambiguous', () => {
+      const { tracker, warn } = makeTracker();
+      tracker.create([], ['/cache/a'], 'user');
+      tracker.create([], ['/cache/b'], 'user');
+
+      tracker.handleTurnStarted(turnStarted(1, 'user'));
+
+      expect(warn).toHaveBeenCalledOnce();
+      expect(warn.mock.calls[0]![0]).toContain("'user'");
+      expect(warn.mock.calls[0]![0]).toContain('1');
+    });
+
+    it('stays silent while at most one same-origin lease is unclaimed', () => {
+      const { tracker, warn } = makeTracker();
+      tracker.create([], ['/cache/a'], 'user');
+
+      tracker.handleTurnStarted(turnStarted(1, 'user'));
+      tracker.handleTurnStarted(turnStarted(2, 'user'));
+
+      expect(warn).not.toHaveBeenCalled();
+    });
+
+    it('binds the exact lease when turn.started echoes its submission id', () => {
+      const { tracker, warn } = makeTracker();
+      const earlier = tracker.create([], ['/cache/a'], 'user');
+      const exact = tracker.create([], ['/cache/b'], 'user', 'sub-2');
+
+      // The exact id wins over the earlier unclaimed same-origin lease, and
+      // the ambiguity warning stays silent.
+      tracker.handleTurnStarted(turnStarted(1, 'user', 'sub-2'));
+
+      expect(exact?.turnId).toBe('1');
+      expect(earlier?.turnId).toBeUndefined();
+      expect(warn).not.toHaveBeenCalled();
+    });
+
+    it('falls back to the origin heuristic when the promptId is unknown', () => {
+      const { tracker, warn } = makeTracker();
+      const first = tracker.create([], ['/cache/a'], 'user', 'sub-1');
+      const second = tracker.create([], ['/cache/b'], 'user');
+
+      tracker.handleTurnStarted(turnStarted(1, 'user', 'sub-unknown'));
+
+      expect(first?.turnId).toBe('1');
+      expect(second?.turnId).toBeUndefined();
+      expect(warn).toHaveBeenCalledOnce();
+    });
+
+    it('does not exact-bind a released lease whose submission id is echoed again', () => {
+      const { tracker } = makeTracker();
+      const released = tracker.create([], ['/cache/a'], 'user', 'sub-1');
+      tracker.release(released);
+      const fallback = tracker.create([], ['/cache/b'], 'user');
+
+      tracker.handleTurnStarted(turnStarted(1, 'user', 'sub-1'));
+
+      expect(released?.turnId).toBeUndefined();
+      expect(fallback?.turnId).toBe('1');
+    });
+
+    it('ignores turns of other or unknown origins', () => {
+      const { tracker } = makeTracker();
+      const lease = tracker.create([], ['/cache/a'], 'skill_activation');
+
+      tracker.handleTurnStarted(turnStarted(1, 'user'));
+      tracker.handleTurnStarted(turnStarted(2, 'plugin_command'));
+      tracker.handleTurnStarted(turnStarted(3, 'system_trigger'));
+      expect(lease?.turnId).toBeUndefined();
+
+      tracker.handleTurnStarted(turnStarted(4, 'skill_activation'));
+      expect(lease?.turnId).toBe('4');
+    });
+
+    it('does not rebind a bound or released lease', () => {
+      const { tracker } = makeTracker();
+      const lease = tracker.create([], ['/cache/a'], 'user');
+      tracker.bindToTurn(lease, '1');
+      tracker.bindToTurn(lease, '2');
+      expect(lease?.turnId).toBe('1');
+
+      tracker.release(lease);
+      tracker.bindToTurn(lease, '3');
+      expect(lease?.turnId).toBe('1');
+    });
+  });
+
+  describe('turn-end release', () => {
+    it('deletes daemon uploads but retires cache copies to session lifetime', () => {
+      const { tracker, deleted } = makeTracker();
+      const lease = tracker.create([1], ['/cache/a'], 'user');
+      tracker.bindToTurn(lease, '1');
+
+      tracker.handleTurnEnded(turnEnded(1));
+
+      expect(deleted.fileIds).toEqual(['file-1']);
+      expect(deleted.paths).toEqual([]);
+    });
+
+    it('deletes retired cache copies at session close', () => {
+      const { tracker, deleted } = makeTracker();
+      const lease = tracker.create([1], ['/cache/a'], 'user');
+      tracker.bindToTurn(lease, '1');
+      tracker.handleTurnEnded(turnEnded(1));
+      expect(deleted.paths).toEqual([]);
+
+      tracker.releaseAll();
+      expect(deleted.paths).toEqual(['/cache/a']);
+    });
+
+    it('releases a bound lease exactly once across repeated turn.ended events', () => {
+      const { tracker, deleteFiles } = makeTracker();
+      const lease = tracker.create([1], ['/cache/a'], 'user');
+      tracker.bindToTurn(lease, '1');
+
+      tracker.handleTurnEnded(turnEnded(1));
+      tracker.handleTurnEnded(turnEnded(1));
+      tracker.release(lease);
+
+      expect(deleteFiles).toHaveBeenCalledTimes(1);
+    });
+
+    it('ignores turn.ended for unknown turns', () => {
+      const { tracker, deleteFiles } = makeTracker();
+      tracker.create([1], ['/cache/a'], 'user');
+      tracker.handleTurnEnded(turnEnded(99));
+      expect(deleteFiles).not.toHaveBeenCalled();
+    });
+
+    it('consumes one retain per id occurrence at turn end', () => {
+      const { tracker, takeFileIds } = makeTracker();
+      // Multiplicity in the lease's id list is the retain count (creation
+      // sites dedupe per extraction): [7, 7] means two retains, e.g. a
+      // batched steer of two queued messages sharing the image.
+      tracker.create([7, 7], [], 'user', 'sub-dup');
+      tracker.handleTurnStarted(turnStarted(1, 'user', 'sub-dup'));
+
+      tracker.handleTurnEnded(turnEnded(1));
+
+      expect(takeFileIds.mock.calls).toEqual([[[7]], [[7]]]);
+    });
+  });
+
+  describe('abandonment', () => {
+    // Every abandonment entry point deletes daemon uploads and cache copies
+    // immediately, whether or not a turn ever consumed the lease.
+    it.each([
+      [
+        'release',
+        (tracker: StagingLeaseTracker) => {
+          tracker.release(tracker.create([1], ['/cache/a'], 'user'));
+          tracker.release(tracker.create([2], ['/cache/b'], 'user'));
+        },
+      ],
+      [
+        'releaseMedia and releaseQueued',
+        (tracker: StagingLeaseTracker) => {
+          tracker.releaseMedia([1], ['/cache/a']);
+          tracker.releaseQueued([
+            { text: 'q', agentId: 'main', imageAttachmentIds: [2], stagingPaths: ['/cache/b'] },
+          ]);
+        },
+      ],
+      [
+        'releaseAll',
+        (tracker: StagingLeaseTracker) => {
+          tracker.create([1], ['/cache/a'], 'user');
+          tracker.bindToTurn(tracker.create([2], ['/cache/b'], 'user'), '1');
+          tracker.releaseAll();
+        },
+      ],
+    ] as const)('%s deletes daemon uploads and cache copies immediately', (_name, abandon) => {
+      const { tracker, deleted } = makeTracker();
+
+      abandon(tracker);
+
+      expect(deleted.fileIds).toEqual(['file-1', 'file-2']);
+      expect(deleted.paths).toEqual(['/cache/a', '/cache/b']);
+    });
+  });
+
+  describe('queue recall', () => {
+    it('consumes only the retain and retires cache copies instead of deleting', () => {
+      const { tracker, releaseRetains, deleted } = makeTracker();
+
+      // A recall restores the draft into the editor — not a discard: the
+      // daemon upload stays staged (only the retain is consumed) and the
+      // cache copy retires to session lifetime.
+      tracker.releaseRecalled({
+        imageAttachmentIds: [2],
+        stagingPaths: ['/cache/b'],
+      });
+
+      expect(releaseRetains).toHaveBeenCalledWith([2]);
+      expect(deleted.fileIds).toEqual([]);
+      expect(deleted.paths).toEqual([]);
+
+      tracker.releaseAll();
+      expect(deleted.fileIds).toEqual([]);
+      expect(deleted.paths).toEqual(['/cache/b']);
+    });
+  });
+
+  describe('defer', () => {
+    it('unbinds the lease without consuming retains or deleting files', () => {
+      const { tracker, takeFileIds, releaseRetains, deleted } = makeTracker();
+      const lease = tracker.create([1], ['/cache/a'], 'user', 'sub-1');
+
+      tracker.defer(lease);
+
+      expect(lease?.released).toBe(true);
+      expect(takeFileIds).not.toHaveBeenCalled();
+      expect(releaseRetains).not.toHaveBeenCalled();
+      expect(deleted).toEqual({ fileIds: [], paths: [] });
+
+      // A deferred lease is gone for good: turn events cannot claim it and
+      // releaseAll does not sweep its media.
+      tracker.handleTurnStarted(turnStarted(1, 'user', 'sub-1'));
+      expect(lease?.turnId).toBeUndefined();
+      tracker.releaseAll();
+      expect(deleted).toEqual({ fileIds: [], paths: [] });
+    });
+  });
+
+  describe('trackDispatch', () => {
+    const origin: StagingLeaseOrigin = 'user';
+
+    it('keeps the lease when the dispatch resolves', async () => {
+      const { tracker, deleteFiles } = makeTracker();
+      const lease = tracker.create([1], ['/cache/a'], origin);
+      const onError = vi.fn();
+
+      tracker.trackDispatch(lease, Promise.resolve(), onError);
+      await tracker.drain();
+
+      expect(onError).not.toHaveBeenCalled();
+      expect(deleteFiles).not.toHaveBeenCalled();
+      expect(lease?.released).toBe(false);
+    });
+
+    it('releases an unclaimed lease exactly once when the dispatch rejects', async () => {
+      const { tracker, deleted } = makeTracker();
+      const lease = tracker.create([1], ['/cache/a'], origin);
+      const onError = vi.fn();
+
+      tracker.trackDispatch(lease, Promise.reject(new Error('boom')), onError);
+      await tracker.drain();
+
+      expect(onError).toHaveBeenCalledOnce();
+      expect(deleted.fileIds).toEqual(['file-1']);
+      expect(deleted.paths).toEqual(['/cache/a']);
+      // A later turn end must not delete again.
+      tracker.handleTurnEnded(turnEnded(1));
+      tracker.releaseAll();
+      expect(deleted.fileIds).toEqual(['file-1']);
+    });
+
+    it('does not release a lease a turn already claimed when the dispatch rejects', async () => {
+      const { tracker, deleted } = makeTracker();
+      const lease = tracker.create([1], ['/cache/a'], origin);
+      tracker.bindToTurn(lease, '7');
+
+      tracker.trackDispatch(lease, Promise.reject(new Error('boom')), vi.fn());
+      await tracker.drain();
+      expect(deleted.fileIds).toEqual([]);
+
+      // The owning turn still releases it at turn end (uploads deleted, copies retired).
+      tracker.handleTurnEnded(turnEnded(7));
+      expect(deleted.fileIds).toEqual(['file-1']);
+      expect(deleted.paths).toEqual([]);
+    });
+  });
+
+  describe('track/drain', () => {
+    it('drain awaits in-flight cleanups and track swallows rejections', async () => {
+      const { tracker } = makeTracker();
+      let settled = false;
+      tracker.track(
+        new Promise<void>((resolve) => {
+          setTimeout(() => {
+            settled = true;
+            resolve();
+          }, 10);
+        }),
+      );
+      tracker.track(Promise.reject(new Error('ignored')));
+
+      await tracker.drain();
+      expect(settled).toBe(true);
+    });
+  });
+});
diff --git a/apps/kimi-code/test/tui/export-markdown.test.ts b/apps/kimi-code/test/tui/export-markdown.test.ts
index 05a6eb8adc6..7e65577332b 100644
--- a/apps/kimi-code/test/tui/export-markdown.test.ts
+++ b/apps/kimi-code/test/tui/export-markdown.test.ts
@@ -316,6 +316,54 @@ describe('buildExportMarkdown', () => {
     expect(md).toContain('deep thought');
   });
 
+  it('renders an uploaded image daemon ref as [image] in the exported user message', () => {
+    // An uploaded image persists as a self-contained `kimi-file://` part —
+    // the export keeps the real text and `[image]`, never the materialization
+    // path or the internal url.
+    const msgs: ContextMessage[] = [
+      {
+        role: 'user',
+        content: [
+          { type: 'text', text: 'what is this? ' },
+          {
+            type: 'image_url',
+            imageUrl: { url: 'kimi-file://f_1?path=%2FUsers%2Falice%2Fmedia%2Ff_1.png' },
+          },
+        ],
+        toolCalls: [],
+        origin: { kind: 'user' },
+      },
+      assistantMsg('a screenshot'),
+    ];
+    const md = buildExportMarkdown({
+      sessionId: 'ses_test',
+      workDir: '/tmp',
+      history: msgs,
+      tokenCount: 0,
+      now,
+    });
+    expect(md).toContain('what is this?');
+    expect(md).toContain('[image]');
+    expect(md).not.toContain('/Users/alice');
+    expect(md).not.toContain('kimi-file');
+    expect(md).not.toContain('<image path=');
+  });
+
+  it('keeps an unpaired standalone <media path> tag as user text in the export', () => {
+    const msgs: ContextMessage[] = [
+      userMsg('<image path="/tmp/shot.png">', { kind: 'user' }),
+      assistantMsg('ok'),
+    ];
+    const md = buildExportMarkdown({
+      sessionId: 'ses_test',
+      workDir: '/tmp',
+      history: msgs,
+      tokenCount: 0,
+      now,
+    });
+    expect(md).toContain('<image path="/tmp/shot.png">');
+  });
+
   it('renders tool calls and results', () => {
     const tc = makeToolCall('c1', 'Read', { file_path: '/foo.ts' });
     const msgs: ContextMessage[] = [
diff --git a/apps/kimi-code/test/tui/input/image-attachment-store.test.ts b/apps/kimi-code/test/tui/input/image-attachment-store.test.ts
index 6add1e428ed..27038b7c46c 100644
--- a/apps/kimi-code/test/tui/input/image-attachment-store.test.ts
+++ b/apps/kimi-code/test/tui/input/image-attachment-store.test.ts
@@ -49,12 +49,53 @@ describe('ImageAttachmentStore', () => {
     expect(att.mime).toBe('image/jpeg');
   });
 
+  it('completes a pending image without changing its attachment id', () => {
+    const s = new ImageAttachmentStore();
+    const att = s.addImage(new Uint8Array([1]), 'image/png', 10, 20);
+
+    const completed = s.completeImage(att, {
+      bytes: new Uint8Array([2, 3]),
+      mime: 'image/jpeg',
+      width: 30,
+      height: 40,
+      fileId: 'file-2',
+    });
+
+    expect(completed).toBe(att);
+    expect(att.id).toBe(1);
+    expect(att.bytes).toEqual(new Uint8Array([2, 3]));
+    expect(att.mime).toBe('image/jpeg');
+    expect(att.placeholder).toBe('[image #1 (30×40)]');
+    const stale = att;
+    s.clear();
+    const fresh = s.addImage(new Uint8Array([9]), 'image/png', 2, 2);
+    expect(s.completeImage(stale, {
+      bytes: new Uint8Array([8]),
+      mime: 'image/png',
+      width: 3,
+      height: 3,
+    })).toBeUndefined();
+    expect(fresh.bytes).toEqual(new Uint8Array([9]));
+  });
+
+  it('records the daemon file-store id when the paste was uploaded (v2)', () => {
+    const s = new ImageAttachmentStore();
+    const att = s.addImage(new Uint8Array([1]), 'image/png', 10, 20, undefined, 'file-abc');
+    expect(att.fileId).toBe('file-abc');
+  });
+
+  it('leaves fileId undefined for attachments that were not uploaded', () => {
+    const s = new ImageAttachmentStore();
+    const att = s.addImage(new Uint8Array([1]), 'image/png', 10, 20);
+    expect(att.fileId).toBeUndefined();
+  });
+
   it('clear() resets ids and empties storage', () => {
     const s = new ImageAttachmentStore();
-    s.addImage(new Uint8Array(), 'image/png', 10, 10);
+    s.addImage(new Uint8Array(), 'image/png', 10, 10, undefined, 'file-1');
     s.addImage(new Uint8Array(), 'image/png', 10, 10);
     expect(s.size()).toBe(2);
-    s.clear();
+    expect(s.clear()).toEqual(['file-1']);
     expect(s.size()).toBe(0);
     const next = s.addImage(new Uint8Array(), 'image/png', 10, 10);
     expect(next.id).toBe(1);
@@ -85,4 +126,69 @@ describe('ImageAttachmentStore', () => {
     expect(s.get(a.id)).toBeUndefined();
     expect(s.get(c.id)).toBeUndefined();
   });
+
+  it('transfers staging file ownership without dropping thumbnail bytes', () => {
+    const s = new ImageAttachmentStore();
+    const bytes = new Uint8Array([1, 2, 3]);
+    const att = s.addImage(bytes, 'image/png', 10, 10, undefined, 'file-1');
+
+    expect(s.takeFileIds([att.id])).toEqual(['file-1']);
+    expect(att.fileId).toBeUndefined();
+    expect(att.bytes).toBe(bytes);
+    expect(s.takeFileIds([att.id])).toEqual([]);
+  });
+
+  it('keeps a daemon upload until every extracted message releases it', () => {
+    const s = new ImageAttachmentStore();
+    const att = s.addImage(new Uint8Array([1]), 'image/png', 10, 10, undefined, 'file-1');
+
+    s.retainFileIds([att.id]);
+    s.retainFileIds([att.id]);
+    expect(s.takeFileIds([att.id])).toEqual([]);
+    expect(att.fileId).toBe('file-1');
+    expect(s.takeFileIds([att.id])).toEqual(['file-1']);
+    expect(att.fileId).toBeUndefined();
+  });
+
+  it('releaseRetains consumes the retain but keeps the staged upload on the attachment', () => {
+    const s = new ImageAttachmentStore();
+    const att = s.addImage(new Uint8Array([1]), 'image/png', 10, 10, undefined, 'file-1');
+
+    s.retainFileIds([att.id]);
+    s.releaseRetains([att.id]);
+    expect(att.fileId).toBe('file-1');
+    // The retain is gone: a later take consumes the upload immediately.
+    expect(s.takeFileIds([att.id])).toEqual(['file-1']);
+    expect(att.fileId).toBeUndefined();
+  });
+
+  it('releaseRetains leaves retains held by other submissions untouched', () => {
+    const s = new ImageAttachmentStore();
+    const att = s.addImage(new Uint8Array([1]), 'image/png', 10, 10, undefined, 'file-1');
+
+    s.retainFileIds([att.id]); // submission A queues
+    s.retainFileIds([att.id]); // submission B queues
+    s.releaseRetains([att.id]); // A is recalled into the editor
+    s.retainFileIds([att.id]); // A's restored draft resubmits
+    // A's consuming turn ends: one retain (B's) is still outstanding, so the
+    // upload survives.
+    expect(s.takeFileIds([att.id])).toEqual([]);
+    expect(att.fileId).toBe('file-1');
+    // B's turn ends: the last retain is gone, the upload is taken.
+    expect(s.takeFileIds([att.id])).toEqual(['file-1']);
+    expect(att.fileId).toBeUndefined();
+  });
+
+  it('rebaseVideoSource repoints a recalled video at its staged cache copy', () => {
+    const s = new ImageAttachmentStore();
+    const att = s.addVideo('video/mp4', '/tmp/original.mp4');
+
+    s.rebaseVideoSource(att.id, '/cache/original.mp4');
+    expect(att.sourcePath).toBe('/cache/original.mp4');
+
+    // Images and unknown ids are ignored.
+    const image = s.addImage(new Uint8Array([1]), 'image/png', 10, 10);
+    s.rebaseVideoSource(image.id, '/cache/nope');
+    expect(s.get(image.id)).toBe(image);
+  });
 });
diff --git a/apps/kimi-code/test/tui/input/image-placeholder.test.ts b/apps/kimi-code/test/tui/input/image-placeholder.test.ts
index 85755641c6a..8a52dedaae9 100644
--- a/apps/kimi-code/test/tui/input/image-placeholder.test.ts
+++ b/apps/kimi-code/test/tui/input/image-placeholder.test.ts
@@ -1,14 +1,24 @@
-import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+/**
+ * Media placeholder expansion and rewrite contracts, including dispatch-time
+ * fallback from expiring daemon uploads to bytes retained by the TUI.
+ */
+
+import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { describe, it, expect } from 'vitest';
 
+import { parseDaemonFileUrl } from '@moonshot-ai/kimi-code-sdk';
+
 import { KIMI_CODE_HOME_ENV } from '#/constant/app';
 import { ImageAttachmentStore } from '#/tui/utils/image-attachment-store';
 import {
   extractMediaAttachments,
+  makeExtractionResendable,
+  pendingImageIngestions,
+  refreshExpiringImageFileRefs,
   rewriteMediaPlaceholders,
 } from '#/tui/utils/image-placeholder';
 import { getCacheDir } from '#/utils/paths';
@@ -229,6 +239,153 @@ describe('extractMediaAttachments', () => {
     expect(r.parts).toHaveLength(1);
     expect(r.parts[0]?.type).toBe('image_url');
   });
+
+  it('expands an uploaded (fileId) image into a bare kimi-file reference', () => {
+    const { cleanup } = setupTempCache();
+    try {
+      const store = new ImageAttachmentStore();
+      const att = store.addImage(new Uint8Array([0x89, 0x50, 0x4e, 0x47]), 'image/png', 640, 480, undefined, 'file-1');
+      const r = extractMediaAttachments(`describe ${att.placeholder} please`, store);
+      expect(r.hasMedia).toBe(true);
+      expect(r.imageAttachmentIds).toEqual([1]);
+      // No tag text part and no `?path=`: the engine's prompt intake
+      // materializes the session copy and rewrites the reference with its
+      // path — the part is self-contained, no paired tag is authored.
+      expect(r.parts).toEqual([
+        { type: 'text', text: 'describe ' },
+        { type: 'image_url', imageUrl: { url: 'kimi-file://file-1' } },
+        { type: 'text', text: ' please' },
+      ]);
+      expect(parseDaemonFileUrl('kimi-file://file-1')).toEqual({ fileId: 'file-1' });
+      // The edge stages no local copy for an uploaded image — the cache dir
+      // is never even created.
+      expect(r.stagingPaths).toEqual([]);
+      expect(existsSync(getCacheDir())).toBe(false);
+    } finally {
+      cleanup();
+    }
+  });
+
+  it('falls back to retained bytes when an uploaded image is too close to expiry', () => {
+    const store = new ImageAttachmentStore();
+    const att = store.addImage(
+      new Uint8Array([0x89, 0x50, 0x4e, 0x47]),
+      'image/png',
+      640,
+      480,
+      undefined,
+      'file-1',
+      1_060_000,
+    );
+
+    const parts = refreshExpiringImageFileRefs(
+      [{ type: 'image_url', imageUrl: { url: 'kimi-file://file-1' } }],
+      [att.id],
+      store,
+      1_000_000,
+    );
+
+    expect(parts).toEqual([
+      { type: 'image_url', imageUrl: { url: 'data:image/png;base64,iVBORw==' } },
+    ]);
+    expect(att.fileId).toBeUndefined();
+    expect(att.fileExpiresAt).toBeUndefined();
+  });
+
+  it('rebuilds an uploaded image as inline bytes for a new-session resend', () => {
+    const { cleanup } = setupTempCache();
+    try {
+      const bytes = new Uint8Array([0x89, 0x50, 0x4e, 0x47]);
+      const store = new ImageAttachmentStore();
+      const att = store.addImage(bytes, 'image/png', 640, 480, undefined, 'file-1');
+      const extraction = extractMediaAttachments(att.placeholder, store);
+
+      const resend = makeExtractionResendable(extraction);
+
+      expect(resend.imageAttachmentIds).toEqual([]);
+      expect(resend.parts).toContainEqual({
+        type: 'image_url',
+        imageUrl: { url: 'data:image/png;base64,iVBORw==' },
+      });
+      expect(resend.stagingPaths).toHaveLength(0);
+    } finally {
+      cleanup();
+    }
+  });
+
+  it('emits the compression caption before the bare kimi-file reference', () => {
+    const { cleanup } = setupTempCache();
+    try {
+      const store = new ImageAttachmentStore();
+      const att = store.addImage(
+        new Uint8Array([1, 2, 3]),
+        'image/png',
+        2000,
+        2000,
+        {
+          path: '/tmp/kimi-code-original-images/abc.png',
+          width: 2600,
+          height: 2600,
+          byteLength: 123456,
+          mime: 'image/png',
+        },
+        'file-2',
+      );
+      const r = extractMediaAttachments(att.placeholder, store);
+      expect(r.parts).toHaveLength(2);
+      const caption = r.parts[0];
+      if (caption?.type !== 'text') throw new Error('expected leading text part');
+      expect(caption.text).toContain('Image compressed');
+      expect(r.parts[1]).toEqual({
+        type: 'image_url',
+        imageUrl: { url: 'kimi-file://file-2' },
+      });
+    } finally {
+      cleanup();
+    }
+  });
+
+  it('keeps expanding an uploaded image as a bare reference when the cache dir is broken', () => {
+    const { cleanup } = setupTempCache();
+    try {
+      // A file at the cache dir path breaks local cache copies, but neither
+      // form stages one: an uploaded image expands to a bare reference and
+      // the inline (no fileId) form embeds its bytes.
+      writeFileSync(getCacheDir(), 'occupied');
+      const store = new ImageAttachmentStore();
+      const uploaded = store.addImage(new Uint8Array([1]), 'image/png', 10, 10, undefined, 'file-1');
+      const plain = store.addImage(new Uint8Array([2]), 'image/png', 20, 20);
+      const r = extractMediaAttachments(`${uploaded.placeholder} and ${plain.placeholder}`, store);
+      expect(r.imageAttachmentIds).toEqual([1, 2]);
+      expect(r.parts).toEqual([
+        { type: 'image_url', imageUrl: { url: 'kimi-file://file-1' } },
+        { type: 'text', text: ' and ' },
+        { type: 'image_url', imageUrl: { url: 'data:image/png;base64,Ag==' } },
+      ]);
+    } finally {
+      cleanup();
+    }
+  });
+
+  it('rolls back cache copies when a later attachment cannot be materialized', () => {
+    const { cleanup } = setupTempCache();
+    const srcDir = makeTempDir();
+    try {
+      const firstPath = join(srcDir, 'first.mp4');
+      writeFileSync(firstPath, 'video-bytes');
+      const store = new ImageAttachmentStore();
+      const first = store.addVideo('video/mp4', firstPath);
+      const missing = store.addVideo('video/mp4', join(srcDir, 'missing.mp4'));
+
+      expect(() =>
+        extractMediaAttachments(`${first.placeholder} ${missing.placeholder}`, store),
+      ).toThrow();
+      expect(readdirSync(getCacheDir())).toEqual([]);
+    } finally {
+      cleanup();
+      rmSync(srcDir, { recursive: true, force: true });
+    }
+  });
 });
 
 describe('rewriteMediaPlaceholders', () => {
@@ -375,3 +532,69 @@ describe('rewriteMediaPlaceholders', () => {
     }
   });
 });
+
+describe('pendingImageIngestions', () => {
+  it('returns undefined for text without image placeholders', () => {
+    const store = new ImageAttachmentStore();
+    expect(pendingImageIngestions('hello world', store, 5)).toBeUndefined();
+  });
+
+  it('returns undefined when no referenced image has a pending ingestion', () => {
+    const { store, placeholder } = storeWith(new Uint8Array([0xaa, 0xbb]));
+    expect(pendingImageIngestions(`describe ${placeholder}`, store, 5)).toBeUndefined();
+  });
+
+  it('waits for a pending ingestion so extraction can use the daemon-ref form', async () => {
+    const { store, placeholder } = storeWith(new Uint8Array([0xaa, 0xbb]));
+    const att = store.get(1);
+    if (att?.kind !== 'image') throw new Error('expected image attachment');
+    let finish!: () => void;
+    att.pending = new Promise<void>((resolve) => {
+      finish = () => {
+        // Complete like the background ingestion would: land the upload id,
+        // then resolve and clear the pending marker.
+        att.fileId = 'file-1';
+        att.fileExpiresAt = Date.now() + 60 * 60 * 1000;
+        att.pending = undefined;
+        resolve();
+      };
+    });
+
+    const waited = pendingImageIngestions(`describe ${placeholder}`, store, 1_000);
+    if (waited === undefined) throw new Error('expected a pending wait');
+    let settled = false;
+    void waited.then(() => {
+      settled = true;
+    });
+    await new Promise((resolve) => setTimeout(resolve, 10));
+    expect(settled).toBe(false);
+
+    finish();
+    await waited;
+    expect(settled).toBe(true);
+
+    const r = extractMediaAttachments(`describe ${placeholder}`, store);
+    const part = r.parts.find((p) => p.type === 'image_url');
+    expect(part?.type).toBe('image_url');
+    if (part?.type !== 'image_url') throw new Error('expected an image part');
+    expect(parseDaemonFileUrl(part.imageUrl.url)?.fileId).toBe('file-1');
+  });
+
+  it('bounds the wait by the timeout so a slow ingestion extracts to the inline form', async () => {
+    const { store, placeholder } = storeWith(new Uint8Array([0xaa, 0xbb]));
+    const att = store.get(1);
+    if (att?.kind !== 'image') throw new Error('expected image attachment');
+    att.pending = new Promise<void>(() => undefined); // never settles
+
+    const start = Date.now();
+    const waited = pendingImageIngestions(`describe ${placeholder}`, store, 20);
+    if (waited === undefined) throw new Error('expected a pending wait');
+    await waited;
+    expect(Date.now() - start).toBeLessThan(1_000);
+
+    const r = extractMediaAttachments(`describe ${placeholder}`, store);
+    const part = r.parts.find((p) => p.type === 'image_url');
+    if (part?.type !== 'image_url') throw new Error('expected an image part');
+    expect(part.imageUrl.url.startsWith('data:image/png;base64,')).toBe(true);
+  });
+});
diff --git a/apps/kimi-code/test/tui/kimi-tui-message-flow.test.ts b/apps/kimi-code/test/tui/kimi-tui-message-flow.test.ts
index eb6328e4f09..ccbc2fc9cdb 100644
--- a/apps/kimi-code/test/tui/kimi-tui-message-flow.test.ts
+++ b/apps/kimi-code/test/tui/kimi-tui-message-flow.test.ts
@@ -1,4 +1,5 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
+import { existsSync } from 'node:fs';
 import { mkdtemp, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join, resolve } from 'node:path';
@@ -63,6 +64,10 @@ import {
 } from '#/tui/commands/prompts';
 import type { QueuedMessage } from '#/tui/types';
 import type { ImageAttachmentStore } from '#/tui/utils/image-attachment-store';
+import {
+  extractMediaAttachments,
+  type ExtractionResult,
+} from '#/tui/utils/image-placeholder';
 
 vi.mock('#/tui/commands/prompts', async (importOriginal) => {
   const actual = await importOriginal<typeof import('#/tui/commands/prompts')>();
@@ -129,6 +134,11 @@ interface MessageDriver {
   handleUserInput(text: string): void;
   persistInputHistory(text: string): Promise<void>;
   sendQueuedMessage(session: unknown, item: QueuedMessage): void;
+  recallLastQueued(): QueuedMessage | undefined;
+  recallStashedMedia(text: string, extraction: ExtractionResult | undefined): void;
+  clearQueuedMessages(): void;
+  closeSession(reason: string): Promise<void>;
+  setSession(session: unknown): Promise<void>;
   getCurrentSessionId(): string;
 }
 
@@ -297,6 +307,7 @@ function makeHarness(session = makeSession(), overrides: Record<string, unknown>
       sessionDir: '/tmp/session-a',
       manifest: {},
     })),
+    deleteFile: vi.fn(async () => {}),
     close: vi.fn(async () => {}),
     track: vi.fn(),
     setTelemetryContext: vi.fn(),
@@ -456,6 +467,38 @@ async function makeTempHome(): Promise<string> {
   return dir;
 }
 
+/** Runs `run` with a temp clip.mp4 source, removing the temp dir afterwards. */
+async function withTempVideo(run: (srcVideo: string) => Promise<void>): Promise<void> {
+  const dir = await mkdtemp(join(tmpdir(), 'tui-video-'));
+  try {
+    const srcVideo = join(dir, 'clip.mp4');
+    await writeFile(srcVideo, 'video-bytes');
+    await run(srcVideo);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+}
+
+function stagedImage(imageStore: ImageAttachmentStore, fileId: string) {
+  return imageStore.addImage(new Uint8Array([0xaa, 0xbb]), 'image/png', 1, 1, undefined, fileId);
+}
+
+/**
+ * Emits the turn.started/turn.ended pair that claims and then releases a
+ * staged-media lease; `between` runs assertions after the claim.
+ */
+function emitTurn(driver: MessageDriver, turnId: number, between?: () => void): void {
+  driver.sessionEventHandler.handleEvent(
+    { type: 'turn.started', agentId: 'main', turnId, origin: { kind: 'user' } } as Event,
+    () => {},
+  );
+  between?.();
+  driver.sessionEventHandler.handleEvent(
+    { type: 'turn.ended', agentId: 'main', turnId, reason: 'completed' } as Event,
+    () => {},
+  );
+}
+
 async function makeExportedSessionZip(content = 'session zip'): Promise<string> {
   const dir = await mkdtemp(join(tmpdir(), 'kimi-code-feedback-export-'));
   tempDirs.push(dir);
@@ -526,7 +569,7 @@ describe('KimiTUI message flow', () => {
     driver.handleUserInput('hello');
 
     await vi.waitFor(() => {
-      expect(session.prompt).toHaveBeenCalledWith('hello');
+      expect(session.prompt).toHaveBeenCalledWith('hello', { promptId: undefined });
     });
     expect(harness.createSession).toHaveBeenCalledTimes(1);
     expect(harness.createSession).toHaveBeenCalledWith({
@@ -813,7 +856,7 @@ describe('KimiTUI message flow', () => {
     driver.handleUserInput('please /skill:review this');
 
     await vi.waitFor(() => {
-      expect(session.prompt).toHaveBeenCalledWith('please /skill:review this');
+      expect(session.prompt).toHaveBeenCalledWith('please /skill:review this', { promptId: undefined });
     });
     expect(session.promptWithSkills).not.toHaveBeenCalled();
   });
@@ -1307,7 +1350,7 @@ describe('KimiTUI message flow', () => {
     // The prompt continuation starts its turn first; /new (idle-only) must
     // then be blocked instead of switching away from the active session.
     await vi.waitFor(() => {
-      expect(lazySession.prompt).toHaveBeenCalledWith('hello');
+      expect(lazySession.prompt).toHaveBeenCalledWith('hello', { promptId: undefined });
       expect(stripSgr(renderTranscript(driver))).toContain('Cannot /new while streaming');
     });
     expect(harness.createSession).toHaveBeenCalledTimes(1);
@@ -1359,7 +1402,7 @@ describe('KimiTUI message flow', () => {
     // The prompt starts its turn first; the switch must then be rejected
     // instead of being silently overwritten by the session assembly.
     await vi.waitFor(() => {
-      expect(lazySession.prompt).toHaveBeenCalledWith('hello');
+      expect(lazySession.prompt).toHaveBeenCalledWith('hello', { promptId: undefined });
       expect(stripSgr(renderTranscript(driver))).toContain('Cannot switch models while streaming');
     });
     expect(lazySession.setThinking).not.toHaveBeenCalled();
@@ -1442,7 +1485,7 @@ describe('KimiTUI message flow', () => {
     // The prompt starts its turn first; the switch must then be rejected
     // instead of being overwritten when the lazy creation completes.
     await vi.waitFor(() => {
-      expect(lazySession.prompt).toHaveBeenCalledWith('hello');
+      expect(lazySession.prompt).toHaveBeenCalledWith('hello', { promptId: undefined });
       expect(stripSgr(renderTranscript(driver))).toContain('Cannot switch sessions while streaming');
     });
     expect(harness.resumeSession).not.toHaveBeenCalled();
@@ -1468,7 +1511,7 @@ describe('KimiTUI message flow', () => {
     driver.handleUserInput('hello');
 
     await vi.waitFor(() => {
-      expect(session.prompt).toHaveBeenCalledWith('hello');
+      expect(session.prompt).toHaveBeenCalledWith('hello', { promptId: undefined });
     });
     expect(harness.createSession).toHaveBeenCalledWith(
       expect.objectContaining({ model: 'k2', thinking: 'high' }),
@@ -1503,7 +1546,7 @@ describe('KimiTUI message flow', () => {
     driver.handleUserInput('hello');
 
     await vi.waitFor(() => {
-      expect(session.prompt).toHaveBeenCalledWith('hello');
+      expect(session.prompt).toHaveBeenCalledWith('hello', { promptId: undefined });
     });
     expect(harness.createSession).toHaveBeenCalledWith(
       expect.objectContaining({ planMode: undefined }),
@@ -1522,7 +1565,7 @@ describe('KimiTUI message flow', () => {
     driver.handleUserInput('hello');
 
     await vi.waitFor(() => {
-      expect(session.prompt).toHaveBeenCalledWith('hello');
+      expect(session.prompt).toHaveBeenCalledWith('hello', { promptId: undefined });
     });
     expect(harness.createSession).toHaveBeenCalledWith(
       expect.objectContaining({ planMode: true }),
@@ -1546,7 +1589,7 @@ describe('KimiTUI message flow', () => {
     driver.handleUserInput('ls');
 
     await vi.waitFor(() => {
-      expect(session.prompt).toHaveBeenCalledWith('hello');
+      expect(session.prompt).toHaveBeenCalledWith('hello', { promptId: undefined });
     });
     // The shell command must be queued, not run concurrently with the prompt.
     expect(runShellCommand).not.toHaveBeenCalled();
@@ -1603,7 +1646,7 @@ describe('KimiTUI message flow', () => {
     driver.handleUserInput('/skill:my-skill');
 
     await vi.waitFor(() => {
-      expect(session.prompt).toHaveBeenCalledWith('hello');
+      expect(session.prompt).toHaveBeenCalledWith('hello', { promptId: undefined });
     });
     // The skill activation must be blocked, not run concurrently with the
     // prompt's turn.
@@ -1893,7 +1936,7 @@ describe('KimiTUI message flow', () => {
     driver.handleUserInput('hello');
 
     await vi.waitFor(() => {
-      expect(session.prompt).toHaveBeenCalledWith('hello');
+      expect(session.prompt).toHaveBeenCalledWith('hello', { promptId: undefined });
     });
     // The engine applies the config default at create; repeating --plan would
     // re-enter plan mode and throw, so it must not be passed again.
@@ -1942,7 +1985,7 @@ describe('KimiTUI message flow', () => {
     driver.handleUserInput('hello');
 
     await vi.waitFor(() => {
-      expect(session.prompt).toHaveBeenCalledWith('hello');
+      expect(session.prompt).toHaveBeenCalledWith('hello', { promptId: undefined });
     });
     expect(harness.createSession).toHaveBeenCalledWith(
       expect.objectContaining({ permission: 'yolo' }),
@@ -2730,7 +2773,7 @@ command = "vim"
 
     driver.handleUserInput('hello');
 
-    expect(session.prompt).toHaveBeenCalledWith('hello');
+    expect(session.prompt).toHaveBeenCalledWith('hello', { promptId: undefined });
     expect(driver.state.appState.streamingPhase).not.toBe('idle');
     expect(driver.state.appState.streamingPhase).toBe('waiting');
     expect(driver.state.livePane.mode).toBe('waiting');
@@ -3124,42 +3167,72 @@ command = "vim"
     expect(transcript).not.toContain('review');
   });
 
-  it('sends a pasted video as a file:// video_url part', async () => {
-    const { driver, session } = await makeDriver();
+  it('keeps a pasted video cache copy for history until the session closes', async () => {
+    process.env['KIMI_CODE_HOME'] = await makeTempHome();
+    let finishPrompt!: () => void;
+    const promptSettled = new Promise<void>((resolve) => {
+      finishPrompt = resolve;
+    });
+    const session = makeSession({ prompt: vi.fn(() => promptSettled) });
+    const { driver } = await makeDriver(session);
     const imageStore = (driver as unknown as { imageStore: ImageAttachmentStore }).imageStore;
-    const dir = await mkdtemp(join(tmpdir(), 'tui-video-'));
     try {
-      const srcVideo = join(dir, 'clip.mp4');
-      await writeFile(srcVideo, 'video-bytes');
-      const attachment = imageStore.addVideo('video/mp4', srcVideo);
+      await withTempVideo(async (srcVideo) => {
+        const attachment = imageStore.addVideo('video/mp4', srcVideo);
+
+        // Submission is fully synchronous: the paste is copied to the cache and
+        // referenced by a `file://` video_url the engine resolves in-turn.
+        driver.handleUserInput(`watch ${attachment.placeholder}`);
+
+        const parts = vi.mocked(session.prompt).mock.calls[0]?.[0] as
+          | Array<{
+              type: string;
+              text?: string;
+              videoUrl?: { url: string };
+            }>
+          | undefined;
+        expect(parts?.[0]).toEqual({ type: 'text', text: 'watch ' });
+        expect(parts?.[1]?.type).toBe('video_url');
+        expect(parts?.[1]?.videoUrl?.url).toMatch(/^file:\/\/.*clip\.mp4$/);
+        const stagingPath = driver.state.queuedMessages[0]?.stagingPaths?.[0]
+          ?? new URL(parts![1]!.videoUrl!.url).pathname;
+        expect(existsSync(stagingPath)).toBe(true);
+
+        driver.sessionEventHandler.handleEvent(
+          { type: 'turn.started', agentId: 'main', turnId: 1, origin: { kind: 'user' } } as Event,
+          () => {},
+        );
+        finishPrompt();
+        expect(existsSync(stagingPath)).toBe(true);
+        driver.sessionEventHandler.handleEvent(
+          { type: 'turn.ended', agentId: 'main', turnId: 1, reason: 'completed' } as Event,
+          () => {},
+        );
+        // The cache copy survives the consuming turn: a v1 degrade persists a
+        // `<video path>` tag carrying this exact path into history, and later
+        // turns re-open it with ReadMediaFile.
+        await new Promise((resolve) => {
+          setTimeout(resolve, 20);
+        });
+        expect(existsSync(stagingPath)).toBe(true);
 
-      // Submission is fully synchronous: the paste is copied to the cache and
-      // referenced by a `file://` video_url the engine resolves in-turn.
-      driver.handleUserInput(`watch ${attachment.placeholder}`);
-
-      const parts = vi.mocked(session.prompt).mock.calls[0]?.[0] as
-        | Array<{
-            type: string;
-            text?: string;
-            videoUrl?: { url: string };
-          }>
-        | undefined;
-      expect(parts?.[0]).toEqual({ type: 'text', text: 'watch ' });
-      expect(parts?.[1]?.type).toBe('video_url');
-      expect(parts?.[1]?.videoUrl?.url).toMatch(/^file:\/\/.*clip\.mp4$/);
+        // Session close retires it.
+        await driver.closeSession('test');
+        await vi.waitFor(() => {
+          expect(existsSync(stagingPath)).toBe(false);
+        });
+      });
     } finally {
-      await rm(dir, { recursive: true, force: true });
+      finishPrompt();
     }
   });
 
   it('queues a pasted video (file:// part) while a turn is streaming', async () => {
+    process.env['KIMI_CODE_HOME'] = await makeTempHome();
     const session = makeSession();
     const { driver } = await makeDriver(session);
     const imageStore = (driver as unknown as { imageStore: ImageAttachmentStore }).imageStore;
-    const dir = await mkdtemp(join(tmpdir(), 'tui-video-'));
-    try {
-      const srcVideo = join(dir, 'clip.mp4');
-      await writeFile(srcVideo, 'video-bytes');
+    await withTempVideo(async (srcVideo) => {
       const attachment = imageStore.addVideo('video/mp4', srcVideo);
       driver.state.appState.streamingPhase = 'waiting';
 
@@ -3172,14 +3245,41 @@ command = "vim"
       expect(parts?.[0]).toEqual({ type: 'text', text: 'describe ' });
       expect(parts?.[1]?.type).toBe('video_url');
       expect(parts?.[1]?.videoUrl?.url).toMatch(/^file:\/\/.*clip\.mp4$/);
+      expect(queued?.stagingPaths).toHaveLength(1);
+      expect(existsSync(queued!.stagingPaths![0]!)).toBe(true);
 
       driver.sendQueuedMessage(session, queued!);
-      expect(session.prompt).toHaveBeenCalledWith(parts);
-    } finally {
-      await rm(dir, { recursive: true, force: true });
-    }
+      expect(vi.mocked(session.prompt).mock.calls[0]?.[0]).toEqual(parts);
+    });
   });
 
+  it('falls back to retained bytes when a queued image upload expires before dispatch', async () => {
+    const session = makeSession();
+    const { driver } = await makeDriver(session);
+    const imageStore = (driver as unknown as { imageStore: ImageAttachmentStore }).imageStore;
+    const attachment = imageStore.addImage(
+      new Uint8Array([0xaa, 0xbb]),
+      'image/png',
+      1,
+      1,
+      undefined,
+      'file-expired',
+      1,
+    );
+
+    driver.sendQueuedMessage(session, {
+      text: `describe ${attachment.placeholder}`,
+      parts: [
+        { type: 'image_url', imageUrl: { url: 'kimi-file://file-expired' } },
+      ],
+      imageAttachmentIds: [attachment.id],
+    });
+
+    expect(session.prompt).toHaveBeenCalledWith(
+      [{ type: 'image_url', imageUrl: { url: 'data:image/png;base64,qrs=' } }],
+      { promptId: expect.any(String) },
+    );
+  });
 
   it('sends pasted image placeholders as image content parts', async () => {
     const { driver, session } = await makeDriver();
@@ -3188,10 +3288,15 @@ command = "vim"
 
     driver.handleUserInput(`describe ${attachment.placeholder}`);
 
-    expect(session.prompt).toHaveBeenCalledWith([
-      { type: 'text', text: 'describe ' },
-      { type: 'image_url', imageUrl: { url: 'data:image/png;base64,qrs=' } },
-    ]);
+    expect(session.prompt).toHaveBeenCalledWith(
+      [
+        { type: 'text', text: 'describe ' },
+        { type: 'image_url', imageUrl: { url: 'data:image/png;base64,qrs=' } },
+      ],
+      // Staged media rides with a client-chosen prompt id so the consuming
+      // turn's `turn.started` can bind the lease exactly.
+      { promptId: expect.any(String) },
+    );
     expect(driver.state.transcriptEntries).toEqual([
       expect.objectContaining({
         kind: 'user',
@@ -3201,6 +3306,191 @@ command = "vim"
     ]);
   });
 
+  it('keeps an image staging upload until the consuming turn ends', async () => {
+    const { driver, session, harness } = await makeDriver();
+    const imageStore = (driver as unknown as { imageStore: ImageAttachmentStore }).imageStore;
+    const attachment = stagedImage(imageStore, 'file-1');
+
+    driver.handleUserInput(attachment.placeholder);
+
+    expect(session.prompt).toHaveBeenCalledOnce();
+    emitTurn(driver, 1, () => {
+      expect(harness.deleteFile).not.toHaveBeenCalled();
+    });
+    await vi.waitFor(() => {
+      expect(harness.deleteFile).toHaveBeenCalledWith('file-1');
+    });
+    expect(attachment.fileId).toBeUndefined();
+    expect(attachment.bytes).toEqual(new Uint8Array([0xaa, 0xbb]));
+  });
+
+  it('still deletes the staging upload when a cache-hint dismissal precedes the resend', async () => {
+    const { driver, session, harness } = await makeDriver();
+    const imageStore = (driver as unknown as { imageStore: ImageAttachmentStore }).imageStore;
+    const attachment = stagedImage(imageStore, 'file-dismissed');
+    const text = `describe ${attachment.placeholder}`;
+
+    // Simulate a cache-hint interception dismissed back into the editor: the
+    // submit's extraction is stashed, then restored with recall semantics
+    // (retain consumed, staged files kept for the restored draft).
+    const extraction = extractMediaAttachments(text, imageStore);
+    driver.recallStashedMedia(text, extraction);
+
+    // The restored draft resubmits and re-retains; the consuming turn must
+    // still delete the daemon upload — a retain leaked by the dismissal would
+    // keep the count above zero and pin the upload until its TTL.
+    driver.handleUserInput(text);
+
+    expect(session.prompt).toHaveBeenCalledOnce();
+    emitTurn(driver, 1, () => {
+      expect(harness.deleteFile).not.toHaveBeenCalled();
+    });
+    await vi.waitFor(() => {
+      expect(harness.deleteFile).toHaveBeenCalledWith('file-dismissed');
+    });
+    expect(harness.deleteFile).toHaveBeenCalledTimes(1);
+  });
+
+  it('waits briefly for a pending paste ingestion so the submit uses the daemon-ref form', async () => {
+    const { driver, session } = await makeDriver();
+    const imageStore = (driver as unknown as { imageStore: ImageAttachmentStore }).imageStore;
+    const attachment = imageStore.addImage(new Uint8Array([0xaa, 0xbb]), 'image/png', 1, 1);
+    // Simulate a paste whose background ingestion is still uploading when the
+    // user hits Enter: the send path waits for it instead of dispatching the
+    // inline fallback.
+    let finishIngestion!: () => void;
+    attachment.pending = new Promise<void>((resolve) => {
+      finishIngestion = () => {
+        attachment.fileId = 'file-late';
+        attachment.fileExpiresAt = Date.now() + 60 * 60 * 1000;
+        attachment.pending = undefined;
+        resolve();
+      };
+    });
+
+    driver.handleUserInput(`describe ${attachment.placeholder}`);
+    expect(session.prompt).not.toHaveBeenCalled();
+
+    finishIngestion();
+    await vi.waitFor(() => {
+      expect(session.prompt).toHaveBeenCalledWith(
+        [
+          { type: 'text', text: 'describe ' },
+          { type: 'image_url', imageUrl: { url: 'kimi-file://file-late' } },
+        ],
+        { promptId: expect.any(String) },
+      );
+    });
+  });
+
+  it('releases staged media exactly once when the prompt dispatch rejects', async () => {
+    const session = makeSession({
+      prompt: vi.fn(async () => {
+        throw new Error('session closed');
+      }),
+    });
+    const { driver, harness } = await makeDriver(session);
+    const imageStore = (driver as unknown as { imageStore: ImageAttachmentStore }).imageStore;
+    const attachment = stagedImage(imageStore, 'file-reject');
+
+    driver.handleUserInput(attachment.placeholder);
+
+    await vi.waitFor(() => {
+      expect(driver.state.appState.streamingPhase).toBe('idle');
+    });
+    expect(stripSgr(renderTranscript(driver))).toContain('Failed to send: session closed');
+    expect(harness.deleteFile).toHaveBeenCalledWith('file-reject');
+
+    // The released lease must not be claimed or deleted again by later turn
+    // events or by session close.
+    emitTurn(driver, 1);
+    await driver.closeSession('test');
+    expect(harness.deleteFile).toHaveBeenCalledTimes(1);
+  });
+
+  it('releases goal-steered staging media when the running goal turn ends', async () => {
+    const { driver, session, harness } = await makeDriver();
+    const imageStore = (driver as unknown as { imageStore: ImageAttachmentStore }).imageStore;
+    const attachment = stagedImage(imageStore, 'file-goal');
+    // The goal driver's continuation turn (origin system_trigger — it never
+    // claims leases through handleTurnStarted) is streaming when the queued
+    // steer dispatch lands.
+    driver.state.appState.goal = makeActiveGoalSnapshot();
+    driver.state.appState.streamingPhase = 'waiting';
+    driver.streamingUI.setTurnId('7');
+
+    driver.sendQueuedMessage(session, {
+      text: attachment.placeholder,
+      agentId: 'main',
+      parts: [{ type: 'image_url', imageUrl: { url: 'data:image/png;base64,qrs=' } }],
+      imageAttachmentIds: [attachment.id],
+    });
+
+    expect(session.steer).toHaveBeenCalledOnce();
+    expect(harness.deleteFile).not.toHaveBeenCalled();
+    driver.sessionEventHandler.handleEvent(
+      { type: 'turn.ended', agentId: 'main', turnId: 7, reason: 'completed' } as Event,
+      () => {},
+    );
+    await vi.waitFor(() => {
+      expect(harness.deleteFile).toHaveBeenCalledWith('file-goal');
+    });
+    expect(attachment.fileId).toBeUndefined();
+  });
+
+  it('releases every queued use of shared media when the queue is discarded', async () => {
+    process.env['KIMI_CODE_HOME'] = await makeTempHome();
+    const { driver, harness } = await makeDriver();
+    const imageStore = (driver as unknown as { imageStore: ImageAttachmentStore }).imageStore;
+    const attachment = stagedImage(imageStore, 'file-queued');
+    driver.state.appState.streamingPhase = 'waiting';
+
+    driver.handleUserInput(`first ${attachment.placeholder}`);
+    driver.handleUserInput(`second ${attachment.placeholder}`);
+    const stagingPaths = driver.state.queuedMessages.flatMap((item) => item.stagingPaths ?? []);
+    expect(driver.state.queuedMessages).toHaveLength(2);
+    // An uploaded image stages no local cache copy — the engine's intake
+    // materializes the session copy — so only the daemon upload lease rides
+    // with each queued message.
+    expect(stagingPaths).toHaveLength(0);
+
+    driver.clearQueuedMessages();
+
+    await vi.waitFor(() => {
+      expect(harness.deleteFile).toHaveBeenCalledWith('file-queued');
+    });
+    expect(harness.deleteFile).toHaveBeenCalledTimes(1);
+    expect(attachment.fileId).toBeUndefined();
+  });
+
+  it('does not delete shared daemon media while another turn still uses it', async () => {
+    const session = makeSession();
+    const { driver, harness } = await makeDriver(session);
+    driver.state.appState.model = 'k2';
+    const imageStore = (driver as unknown as { imageStore: ImageAttachmentStore }).imageStore;
+    const attachment = stagedImage(imageStore, 'file-shared-turn');
+
+    driver.handleUserInput(`first ${attachment.placeholder}`);
+    driver.sessionEventHandler.handleEvent(
+      { type: 'turn.started', agentId: 'main', turnId: 1, origin: { kind: 'user' } } as Event,
+      () => {},
+    );
+    driver.state.appState.streamingPhase = 'waiting';
+    driver.handleUserInput(`second ${attachment.placeholder}`);
+    driver.clearQueuedMessages();
+
+    await Promise.resolve();
+    expect(harness.deleteFile).not.toHaveBeenCalled();
+
+    driver.sessionEventHandler.handleEvent(
+      { type: 'turn.ended', agentId: 'main', turnId: 1, reason: 'completed' } as Event,
+      () => {},
+    );
+    await vi.waitFor(() => {
+      expect(harness.deleteFile).toHaveBeenCalledWith('file-shared-turn');
+    });
+  });
+
   it('queues editor input instead of prompting while a turn is already streaming', async () => {
     const { driver, session, harness } = await makeDriver();
     driver.state.appState.streamingPhase = 'waiting';
@@ -3378,7 +3668,7 @@ command = "vim"
     );
 
     await vi.waitFor(() => {
-      expect(session.prompt).toHaveBeenCalledWith('after the turn');
+      expect(session.prompt).toHaveBeenCalledWith('after the turn', { promptId: undefined });
     });
     expect(session.steer).not.toHaveBeenCalled();
   });
@@ -3561,10 +3851,15 @@ command = "vim"
 
     driver.sendQueuedMessage(session, queued!);
 
-    expect(session.prompt).toHaveBeenCalledWith([
-      { type: 'text', text: 'describe ' },
-      { type: 'image_url', imageUrl: { url: 'data:image/png;base64,qrs=' } },
-    ]);
+    expect(session.prompt).toHaveBeenCalledWith(
+      [
+        { type: 'text', text: 'describe ' },
+        { type: 'image_url', imageUrl: { url: 'data:image/png;base64,qrs=' } },
+      ],
+      // Staged media rides with a client-chosen prompt id so the consuming
+      // turn's `turn.started` can bind the lease exactly.
+      { promptId: expect.any(String) },
+    );
   });
 
   it('steers editor image input as media parts', async () => {
@@ -3614,6 +3909,122 @@ command = "vim"
     expect(driver.state.queuedMessages).toEqual([]);
   });
 
+  it('releases every queued use of shared media after a batched steer', async () => {
+    const session = makeSession();
+    const { driver, harness } = await makeDriver(session);
+    driver.state.appState.model = 'k2';
+    driver.state.appState.streamingPhase = 'waiting';
+    driver.streamingUI.setTurnId('1');
+    const imageStore = (driver as unknown as { imageStore: ImageAttachmentStore }).imageStore;
+    const attachment = stagedImage(imageStore, 'file-batched');
+    driver.handleUserInput(`first ${attachment.placeholder}`);
+    driver.handleUserInput(`second ${attachment.placeholder}`);
+    expect(driver.state.queuedMessages).toHaveLength(2);
+
+    driver.state.editor.onCtrlS?.();
+
+    expect(session.steer).toHaveBeenCalledOnce();
+    driver.sessionEventHandler.handleEvent(
+      { type: 'turn.ended', agentId: 'main', turnId: 1, reason: 'completed' } as Event,
+      () => {},
+    );
+    await vi.waitFor(() => {
+      expect(harness.deleteFile).toHaveBeenCalledWith('file-batched');
+    });
+    expect(harness.deleteFile).toHaveBeenCalledTimes(1);
+    expect(attachment.fileId).toBeUndefined();
+    expect(driver.state.queuedMessages).toEqual([]);
+  });
+
+  it('keeps a shared staged upload alive while another submission still holds it', async () => {
+    const session = makeSession();
+    const { driver, harness } = await makeDriver(session);
+    driver.state.appState.model = 'k2';
+    driver.state.appState.streamingPhase = 'waiting';
+    const imageStore = (driver as unknown as { imageStore: ImageAttachmentStore }).imageStore;
+    const attachment = stagedImage(imageStore, 'file-shared');
+
+    // One message referencing the same image twice retains it once; a second
+    // queued message retains it again — two retains total.
+    driver.handleUserInput(`compare ${attachment.placeholder} with ${attachment.placeholder}`);
+    driver.handleUserInput(`and ${attachment.placeholder}`);
+    const [first, second] = driver.state.queuedMessages;
+
+    driver.sendQueuedMessage(session, first!);
+    emitTurn(driver, 1);
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    // The first turn consumed the only retain its submission held; the second
+    // queued message's retain keeps the upload alive.
+    expect(harness.deleteFile).not.toHaveBeenCalled();
+
+    driver.sendQueuedMessage(session, second!);
+    emitTurn(driver, 2);
+    await vi.waitFor(() => {
+      expect(harness.deleteFile).toHaveBeenCalledWith('file-shared');
+    });
+    expect(harness.deleteFile).toHaveBeenCalledTimes(1);
+  });
+
+  it('keeps staged media when a queued message is recalled into the editor', async () => {
+    const session = makeSession();
+    const { driver, harness } = await makeDriver(session);
+    driver.state.appState.model = 'k2';
+    driver.state.appState.streamingPhase = 'waiting';
+    const imageStore = (driver as unknown as { imageStore: ImageAttachmentStore }).imageStore;
+    const attachment = stagedImage(imageStore, 'file-recall');
+
+    driver.handleUserInput(`look ${attachment.placeholder}`);
+    expect(driver.state.queuedMessages).toHaveLength(1);
+
+    const recalled = driver.recallLastQueued();
+    expect(recalled?.text).toContain(attachment.placeholder);
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    // Recalled, not discarded: the daemon upload stays staged for the
+    // restored draft.
+    expect(harness.deleteFile).not.toHaveBeenCalled();
+    expect(attachment.fileId).toBe('file-recall');
+
+    // Re-queueing the restored draft reuses the daemon-ref form, and the
+    // consuming turn's end releases the upload exactly once.
+    driver.handleUserInput(recalled!.text);
+    const requeued = driver.state.queuedMessages[0]!;
+    expect(requeued.parts).toContainEqual({
+      type: 'image_url',
+      imageUrl: { url: 'kimi-file://file-recall' },
+    });
+
+    driver.sendQueuedMessage(session, requeued);
+    emitTurn(driver, 1);
+    await vi.waitFor(() => {
+      expect(harness.deleteFile).toHaveBeenCalledWith('file-recall');
+    });
+    expect(harness.deleteFile).toHaveBeenCalledTimes(1);
+  });
+
+  it('rebases a recalled video onto its staged cache copy', async () => {
+    process.env['KIMI_CODE_HOME'] = await makeTempHome();
+    const session = makeSession();
+    const { driver } = await makeDriver(session);
+    const imageStore = (driver as unknown as { imageStore: ImageAttachmentStore }).imageStore;
+    await withTempVideo(async (srcVideo) => {
+      const attachment = imageStore.addVideo('video/mp4', srcVideo);
+      driver.state.appState.streamingPhase = 'waiting';
+
+      driver.handleUserInput(`describe ${attachment.placeholder}`);
+      const queued = driver.state.queuedMessages[0]!;
+      const cachePath = queued.stagingPaths![0]!;
+      expect(existsSync(cachePath)).toBe(true);
+
+      const recalled = driver.recallLastQueued();
+      expect(recalled?.text).toContain(attachment.placeholder);
+      await new Promise((resolve) => setTimeout(resolve, 20));
+      // The cache copy survives the recall and becomes the video's source, so
+      // a vanished original cannot lose the media on resubmit.
+      expect(existsSync(cachePath)).toBe(true);
+      expect(attachment.sourcePath).toBe(cachePath);
+    });
+  });
+
   it('steers consecutive image-only messages without a whitespace-only separator part', async () => {
     const session = makeSession();
     const { driver } = await makeDriver(session);
@@ -5076,7 +5487,7 @@ command = "vim"
     resolveInit?.();
 
     await vi.waitFor(() => {
-      expect(session.prompt).toHaveBeenCalledWith('apply after init');
+      expect(session.prompt).toHaveBeenCalledWith('apply after init', { promptId: undefined });
     });
     expect(driver.state.queuedMessages).toEqual([]);
   });
diff --git a/apps/kimi-code/test/tui/media-url.test.ts b/apps/kimi-code/test/tui/media-url.test.ts
index 79c73b9f9a7..c13ae01031e 100644
--- a/apps/kimi-code/test/tui/media-url.test.ts
+++ b/apps/kimi-code/test/tui/media-url.test.ts
@@ -9,6 +9,15 @@ describe('mediaUrlPartToText', () => {
     );
   });
 
+  it('renders an internal daemon file reference as a bare placeholder', () => {
+    // `kimi-file://…?path=…` resolves nowhere for the user and carries the
+    // materialization path — never render the wire form.
+    expect(
+      mediaUrlPartToText('image', 'kimi-file://f_1?path=%2FUsers%2Falice%2Fmedia%2Ff_1.png'),
+    ).toBe('[image]');
+    expect(mediaUrlPartToText('video', 'kimi-file://f_2')).toBe('[video]');
+  });
+
   it('summarizes base64 data URLs without returning the payload', () => {
     expect(mediaUrlPartToText('image', 'data:image/png;base64,qrs=')).toBe(
       '[image image/png, 2 B]',
diff --git a/apps/kimi-code/test/tui/message-replay.test.ts b/apps/kimi-code/test/tui/message-replay.test.ts
index be5446a08e5..9f9c0b430c2 100644
--- a/apps/kimi-code/test/tui/message-replay.test.ts
+++ b/apps/kimi-code/test/tui/message-replay.test.ts
@@ -320,6 +320,57 @@ describe('KimiTUI resume message replay', () => {
     expect(transcript).not.toContain('Goal complete');
   });
 
+  it('renders an uploaded image daemon ref as a bare placeholder on replay', async () => {
+    // An uploaded image persists as a self-contained `kimi-file://` part; on
+    // replay it renders as a bare `[image]` placeholder — neither the
+    // materialization path nor the internal url may surface.
+    const driver = await replayIntoDriver([
+      message(
+        'user',
+        [
+          { type: 'text', text: 'what is this? ' },
+          {
+            type: 'image_url',
+            imageUrl: { url: 'kimi-file://f_1?path=%2FUsers%2Falice%2Fmedia%2Ff_1.png' },
+          },
+        ],
+        { origin: { kind: 'user' } },
+      ),
+    ]);
+
+    const transcript = stripAnsi(driver.state.transcriptContainer.render(140).join('\n'));
+    expect(transcript).toContain('what is this?');
+    expect(transcript).toContain('[image]');
+    expect(transcript).not.toContain('/Users/alice');
+    expect(transcript).not.toContain('kimi-file');
+  });
+
+  it('keeps the tag of a legacy upload pair as user text on replay', async () => {
+    // Legacy history paired the daemon ref with an `<image path>` tag. The
+    // pairing is gone: the tag is plain user text and replays verbatim while
+    // the ref still renders as `[image]`.
+    const driver = await replayIntoDriver([
+      message(
+        'user',
+        [
+          { type: 'text', text: 'what is this? ' },
+          { type: 'text', text: '<image path="/Users/alice/media/f_1.png"></image>' },
+          {
+            type: 'image_url',
+            imageUrl: { url: 'kimi-file://f_1?path=%2FUsers%2Falice%2Fmedia%2Ff_1.png' },
+          },
+        ],
+        { origin: { kind: 'user' } },
+      ),
+    ]);
+
+    const transcript = stripAnsi(driver.state.transcriptContainer.render(140).join('\n'));
+    expect(transcript).toContain('what is this?');
+    expect(transcript).toContain('[image]');
+    expect(transcript).toContain('<image path="/Users/alice/media/f_1.png"></image>');
+    expect(transcript).not.toContain('kimi-file');
+  });
+
   it('unescapes bash tag delimiters when replaying shell output', async () => {
     const driver = await replayIntoDriver([
       message(
diff --git a/apps/kimi-code/test/tui/utils/steer-input.test.ts b/apps/kimi-code/test/tui/utils/steer-input.test.ts
new file mode 100644
index 00000000000..8cadccfd183
--- /dev/null
+++ b/apps/kimi-code/test/tui/utils/steer-input.test.ts
@@ -0,0 +1,78 @@
+import { describe, expect, it } from 'vitest';
+
+import type { PromptPart } from '@moonshot-ai/kimi-code-sdk';
+
+import type { SteerInputItem } from '#/tui/types';
+import { combineSteerInput } from '#/tui/utils/steer-input';
+
+describe('combineSteerInput', () => {
+  const refPart = {
+    type: 'image_url',
+    imageUrl: { url: 'kimi-file://f_1?path=%2Fcache%2Ff_1.png' },
+  } as const;
+
+  it('keeps a bare daemon-ref part intact while merging the surrounding text', () => {
+    const result = combineSteerInput([
+      {
+        text: 'what is this?',
+        parts: [{ type: 'text', text: 'what is this? ' }, refPart],
+      },
+    ]);
+    expect(result).toEqual([{ type: 'text', text: 'what is this? ' }, refPart]);
+  });
+
+  it('merges plain text across items around the media parts', () => {
+    const result = combineSteerInput([
+      { text: 'a', parts: [{ type: 'text', text: 'a ' }, refPart] },
+      { text: 'b', parts: [{ type: 'text', text: 'b ' }, refPart] },
+    ]);
+    expect(result).toEqual([
+      { type: 'text', text: 'a ' },
+      refPart,
+      { type: 'text', text: '\n\nb ' },
+      refPart,
+    ]);
+  });
+
+  it.each([
+    {
+      name: 'between two touching media parts',
+      first: { text: '', parts: [refPart] } as SteerInputItem,
+      head: [] as PromptPart[],
+    },
+    {
+      name: 'when a media-ending item is followed by a media-first item',
+      first: {
+        text: 'a',
+        parts: [{ type: 'text', text: 'a ' }, refPart],
+      } as SteerInputItem,
+      head: [{ type: 'text', text: 'a ' }] as PromptPart[],
+    },
+  ])('drops the separator $name', ({ first, head }) => {
+    // Inserting '\n\n' there would strand a whitespace-only text part between
+    // the two media parts, which `normalizePromptInput` rejects.
+    const refPart2 = {
+      type: 'image_url',
+      imageUrl: { url: 'kimi-file://f_2?path=%2Fcache%2Ff_2.png' },
+    } as const;
+    const result = combineSteerInput([first, { text: '', parts: [refPart2] }]);
+    expect(result).toEqual([...head, refPart, refPart2]);
+  });
+
+  it('treats a standalone <media path> tag as plain user text', () => {
+    // Extraction no longer authors machine tags, so a tag in the input is
+    // user text: it merges with adjacent text instead of staying atomic.
+    const tag = '<image path="/cache/f_1.png"></image>';
+    const result = combineSteerInput([
+      {
+        text: `look ${tag}`,
+        parts: [{ type: 'text', text: 'look ' }, { type: 'text', text: tag }, refPart],
+      },
+    ]);
+    expect(result).toEqual([{ type: 'text', text: `look ${tag}` }, refPart]);
+  });
+
+  it('joins text-only items with the historical separator', () => {
+    expect(combineSteerInput([{ text: 'one' }, { text: 'two' }])).toBe('one\n\ntwo');
+  });
+});
diff --git a/apps/kimi-inspect/src/components/ChatView.tsx b/apps/kimi-inspect/src/components/ChatView.tsx
index 25d50369b11..9d9933f1212 100644
--- a/apps/kimi-inspect/src/components/ChatView.tsx
+++ b/apps/kimi-inspect/src/components/ChatView.tsx
@@ -61,7 +61,12 @@ import {
 import { AuditTrail } from '../audit/trail';
 import { useConnection } from '../connection';
 import type { SearchHit } from '../search/api';
-import { fetchTranscriptOps, fetchTranscriptPage, TRANSCRIPT_PAGE_SIZE } from '../transcript/api';
+import {
+  fetchTranscriptAttachment,
+  fetchTranscriptOps,
+  fetchTranscriptPage,
+  TRANSCRIPT_PAGE_SIZE,
+} from '../transcript/api';
 import {
   createCoalescedRunner,
   hasTurnId,
@@ -945,7 +950,6 @@ function AttachmentChips({
       {ids.map((id) => {
         const attachment = attachments.get(id);
         const label = attachment?.name ?? attachment?.mediaType ?? id;
-        const href = attachment?.source?.kind === 'url' ? attachment.source.url : undefined;
         return (
           <span
             key={id}
@@ -953,13 +957,7 @@ function AttachmentChips({
             title={attachment?.mediaType}
           >
             📎{' '}
-            {href !== undefined ? (
-              <a href={href} className="underline">
-                {label}
-              </a>
-            ) : (
-              label
-            )}
+            <AttachmentLink attachment={attachment} label={label} />
           </span>
         );
       })}
@@ -967,6 +965,63 @@ function AttachmentChips({
   );
 }
 
+function AttachmentLink({
+  attachment,
+  label,
+}: {
+  attachment: TranscriptAttachment | undefined;
+  label: string;
+}) {
+  const sessionId = useContext(SessionContext);
+  const { baseUrl, config } = useConnection();
+  const [downloading, setDownloading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const source = attachment?.source;
+  if (source === undefined) return label;
+  if (source.kind === 'url') {
+    return (
+      <a href={source.url} target="_blank" rel="noreferrer" className="underline">
+        {label}
+      </a>
+    );
+  }
+  const download = async (): Promise<void> => {
+    setDownloading(true);
+    setError(null);
+    try {
+      const blob = await fetchTranscriptAttachment({
+        baseUrl,
+        token: config.token.trim() || undefined,
+        sessionId,
+        source,
+      });
+      const href = URL.createObjectURL(blob);
+      const link = document.createElement('a');
+      link.href = href;
+      link.download = attachment?.name ?? source.fileId;
+      link.click();
+      setTimeout(() => {
+        URL.revokeObjectURL(href);
+      }, 0);
+    } catch (error) {
+      setError(error instanceof Error ? error.message : String(error));
+    } finally {
+      setDownloading(false);
+    }
+  };
+  return (
+    <button
+      type="button"
+      className="underline disabled:cursor-wait disabled:opacity-60"
+      disabled={downloading}
+      title={error ?? undefined}
+      onClick={() => void download()}
+    >
+      {downloading ? 'Downloading…' : label}
+    </button>
+  );
+}
+
 function FrameView({
   frame,
   tasks,
diff --git a/apps/kimi-inspect/src/transcript/api.ts b/apps/kimi-inspect/src/transcript/api.ts
index bca4ed4fcb2..7aa54cee855 100644
--- a/apps/kimi-inspect/src/transcript/api.ts
+++ b/apps/kimi-inspect/src/transcript/api.ts
@@ -17,6 +17,7 @@ import {
   transcriptOpsCatchupResponseSchema,
   transcriptPlanResponseSchema,
   transcriptResponseSchema,
+  type AttachmentSource,
   type TranscriptAttachment,
   type TranscriptInteraction,
   type TranscriptItem,
@@ -26,6 +27,44 @@ import {
   type TranscriptTodo,
 } from '@moonshot-ai/transcript';
 
+type StoredAttachmentSource = Extract<AttachmentSource, { kind: 'file' | 'session_media' }>;
+
+export interface FetchTranscriptAttachmentOptions {
+  readonly baseUrl: string;
+  readonly token?: string;
+  readonly sessionId: string;
+  readonly source: StoredAttachmentSource;
+  readonly fetchImpl?: typeof fetch;
+}
+
+export function transcriptAttachmentUrl(
+  baseUrl: string,
+  sessionId: string,
+  source: AttachmentSource,
+): string {
+  if (source.kind === 'url') return source.url;
+  if (source.kind === 'file') {
+    return `${baseUrl}/api/v1/files/${encodeURIComponent(source.fileId)}`;
+  }
+  return `${baseUrl}/api/v1/sessions/${encodeURIComponent(sessionId)}/media/${encodeURIComponent(source.fileId)}`;
+}
+
+export async function fetchTranscriptAttachment(
+  opts: FetchTranscriptAttachmentOptions,
+): Promise<Blob> {
+  const headers: Record<string, string> = {};
+  if (opts.token !== undefined && opts.token !== '') {
+    headers['authorization'] = `Bearer ${opts.token}`;
+  }
+  const doFetch = opts.fetchImpl ?? fetch;
+  const res = await doFetch(
+    transcriptAttachmentUrl(opts.baseUrl, opts.sessionId, opts.source),
+    { headers },
+  );
+  if (!res.ok) throw new Error(`attachment download failed (${res.status})`);
+  return res.blob();
+}
+
 /** One transcript page as merged by the chat store. */
 export interface TranscriptPage {
   readonly items: readonly TranscriptItem[];
diff --git a/apps/kimi-inspect/src/transcript/transcript.test.ts b/apps/kimi-inspect/src/transcript/transcript.test.ts
index 8a7bab27bd3..507d5c15e94 100644
--- a/apps/kimi-inspect/src/transcript/transcript.test.ts
+++ b/apps/kimi-inspect/src/transcript/transcript.test.ts
@@ -16,9 +16,11 @@ import { describe, expect, it, vi } from 'vitest';
 
 import type { WsLike } from '../channel/wsLike';
 import {
+  fetchTranscriptAttachment,
   fetchTranscriptOps,
   fetchTranscriptPage,
   fetchTranscriptPlan,
+  transcriptAttachmentUrl,
   type TranscriptPage,
 } from './api';
 import {
@@ -44,6 +46,44 @@ function stepHeader(stepId: string, ordinal: number): StepHeader {
   return { kind: 'step', stepId, turnId: stepId.split('.')[0] ?? 't1', ordinal, state: 'running' };
 }
 
+describe('transcript attachments', () => {
+  it('maps each attachment locator to its transport route', () => {
+    expect(
+      transcriptAttachmentUrl('http://h:1', 's 1', { kind: 'file', fileId: 'f 1' }),
+    ).toBe('http://h:1/api/v1/files/f%201');
+    expect(
+      transcriptAttachmentUrl('http://h:1', 's 1', {
+        kind: 'session_media',
+        fileId: 'f 1',
+      }),
+    ).toBe('http://h:1/api/v1/sessions/s%201/media/f%201');
+    expect(
+      transcriptAttachmentUrl('http://h:1', 's1', {
+        kind: 'url',
+        url: 'https://example.com/a.png',
+      }),
+    ).toBe('https://example.com/a.png');
+  });
+
+  it('fetches stored attachment bytes with bearer auth', async () => {
+    const fetchImpl = vi.fn(async () => new Response('media-bytes', { status: 200 }));
+
+    const blob = await fetchTranscriptAttachment({
+      baseUrl: 'http://h:1',
+      token: 'tok',
+      sessionId: 's1',
+      source: { kind: 'session_media', fileId: 'f_1' },
+      fetchImpl: fetchImpl as typeof fetch,
+    });
+
+    expect(fetchImpl).toHaveBeenCalledWith(
+      'http://h:1/api/v1/sessions/s1/media/f_1',
+      { headers: { authorization: 'Bearer tok' } },
+    );
+    await expect(blob.text()).resolves.toBe('media-bytes');
+  });
+});
+
 const textFrameUpsert = (turnId: string, stepId: string, frameId: string, text: string) => ({
   op: 'frame.upsert' as const,
   turnId,
diff --git a/packages/agent-core-v2/docs/state-manifest.d.ts b/packages/agent-core-v2/docs/state-manifest.d.ts
index defdae1a212..b369b8b8128 100644
--- a/packages/agent-core-v2/docs/state-manifest.d.ts
+++ b/packages/agent-core-v2/docs/state-manifest.d.ts
@@ -92,7 +92,7 @@
 //     mcp.discoveryWritesReady                        src/agent/mcp/mcpService.ts
 //     mcp.mcpToolsByServer                            src/agent/mcp/mcpService.ts
 //     media.registeredKey                             src/agent/media/mediaToolsRegistrar.ts
-//     media.resolved                                  src/agent/media/videoResolverService.ts
+//     media.resolved                                  src/agent/media/mediaResolverService.ts
 //     permissionMode.lastMode                         src/agent/permissionMode/injection/permissionModeInjection.ts
 //     plan.wasActive                                  src/features/plan/injection/planModeInjection.ts
 //     profile.activeToolNamesOverlay                  src/agent/profile/profileService.ts
@@ -1096,9 +1096,7 @@ export interface AgentStateSnapshot {
   // src/agent/mcp/mcpService.ts
   'mcp.discoveryWritesReady': boolean;
   'mcp.mcpToolsByServer': Map<string, string[]>;
-  // src/agent/media/mediaToolsRegistrar.ts
-  'media.registeredKey': string | undefined;
-  // src/agent/media/videoResolverService.ts
+  // src/agent/media/mediaResolverService.ts
   'media.resolved': Map<string, /* ContentPart — packages/agent-core-v2/src/kosong/contract/message.ts */ /* TextPart — packages/agent-core-v2/src/kosong/contract/message.ts */ {
     type: 'text';
     text: string;
@@ -1125,6 +1123,8 @@ export interface AgentStateSnapshot {
       id?: string;
     };
   }>;
+  // src/agent/media/mediaToolsRegistrar.ts
+  'media.registeredKey': string | undefined;
   // src/agent/permissionMode/injection/permissionModeInjection.ts
   'permissionMode.lastMode': 'manual' | 'yolo' | 'auto' | undefined;
   // src/agent/plugin/agentPluginService.ts
diff --git a/packages/agent-core-v2/docs/wire-manifest.d.ts b/packages/agent-core-v2/docs/wire-manifest.d.ts
index 718fd74b441..4181aad5436 100644
--- a/packages/agent-core-v2/docs/wire-manifest.d.ts
+++ b/packages/agent-core-v2/docs/wire-manifest.d.ts
@@ -21,7 +21,7 @@
 // owning model offloads inline media to blob storage), cross-reducers
 // (foreign models that also reduce this record on dispatch and replay).
 
-// Index (52 record types)
+// Index (53 record types)
 //   config.update                      profile                     persisted  src/agent/profile/profileOps.ts
 //   context.append_loop_event          contextMemory               persisted  src/agent/contextMemory/contextOps.ts
 //   context.append_message             contextMemory               persisted  src/agent/contextMemory/contextOps.ts
@@ -53,6 +53,7 @@
 //   plan.revision                      plan                        persisted  src/features/plan/planOps.ts
 //   plugin.session_start               pluginSessionStartSnapshot  persisted  src/agent/plugin/agentPluginOps.ts
 //   profile.bind                       profile                     persisted  src/agent/profile/profileOps.ts
+//   prompt.accepted                    promptAdmission             persisted  src/agent/prompt/promptOps.ts
 //   runtime.set_binding                runtimeBinding              persisted  src/agent/runtimeBinding/runtimeBindingOps.ts
 //   skill.activate                     skill                       transient  src/agent/skill/skillOps.ts
 //   swarm_mode.enter                   swarm                       persisted  src/features/swarm/swarmOps.ts
@@ -484,6 +485,15 @@ interface ProfileBindPayload {
   subagents?: string[];
 }
 
+/**
+ * model: promptAdmission · persisted
+ * owner: src/agent/prompt/promptOps.ts
+ */
+interface PromptAcceptedPayload {
+  _name: 'prompt.accepted';
+  promptId: string;
+}
+
 /**
  * model: runtimeBinding · persisted
  * owner: src/agent/runtimeBinding/runtimeBindingOps.ts
@@ -787,6 +797,7 @@ interface WirePayloadMap {
   "plan.revision": PlanRevisionPayload;
   "plugin.session_start": PluginSessionStartPayload;
   "profile.bind": ProfileBindPayload;
+  "prompt.accepted": PromptAcceptedPayload;
   "runtime.set_binding": RuntimeSetBindingPayload;
   "skill.activate": SkillActivatePayload;
   "swarm_mode.enter": SwarmModeEnterPayload;
diff --git a/packages/agent-core-v2/scripts/gen-contract-types.mjs b/packages/agent-core-v2/scripts/gen-contract-types.mjs
index 2cd8307b043..e215d7aa482 100644
--- a/packages/agent-core-v2/scripts/gen-contract-types.mjs
+++ b/packages/agent-core-v2/scripts/gen-contract-types.mjs
@@ -13,7 +13,9 @@
  *   2. Detect impl files = source files containing a top-level
  *      `registerScopedService(...)` call; the 3rd argument is the impl class.
  *   3. In each impl file's emitted `.d.ts`, drop the registered class
- *      declaration(s) and keep everything else.
+ *      declaration(s) and keep everything else, then drop re-export
+ *      specifiers elsewhere in the tree that name a dropped class
+ *      (deprecated alias modules) — they would otherwise dangle.
  *   4. Copy the scrubbed tree to the output directory.
  */
 
@@ -134,6 +136,48 @@ for (const [dtsPath, names] of dropByDts) {
 }
 log(`scrubbed ${scrubbedClasses} impl class(es) across ${scrubbedFiles} file(s)`);
 
+// 3b. Scrub re-exports of scrubbed classes. A deprecated alias module (e.g.
+// `export { Impl as OldName } from './implService'`) would otherwise keep
+// naming a class its declaring file no longer exports — a dangling reference
+// for consumers and an impl-name leak. `export *` needs nothing: it only
+// re-exports what survives.
+function resolveReexportTarget(dtsPath, spec) {
+  const clean = spec.endsWith('.js') ? spec.slice(0, -'.js'.length) : spec;
+  if (clean.startsWith('.')) return join(dirname(dtsPath), `${clean}.d.ts`);
+  if (clean.startsWith('#/')) return join(TMP, `${clean.slice(2)}.d.ts`);
+  return undefined;
+}
+
+let scrubbedReexports = 0;
+const emittedDts = [];
+walk(TMP, emittedDts);
+const reexportProject = new Project();
+for (const dtsPath of emittedDts) {
+  if (!dtsPath.endsWith('.d.ts')) continue;
+  const dts = reexportProject.addSourceFileAtPath(dtsPath);
+  let changed = false;
+  for (const exp of dts.getExportDeclarations()) {
+    const spec = exp.getModuleSpecifierValue();
+    if (spec === undefined) continue;
+    const target = resolveReexportTarget(dtsPath, spec);
+    const names = target === undefined ? undefined : dropByDts.get(target);
+    if (names === undefined) continue;
+    let removedHere = false;
+    for (const specifier of exp.getNamedExports()) {
+      const name = specifier.getNameNode().getText();
+      if (names.has('*') || names.has(name)) {
+        specifier.remove();
+        removedHere = true;
+        scrubbedReexports++;
+      }
+    }
+    if (removedHere && exp.getNamedExports().length === 0) exp.remove();
+    changed = changed || removedHere;
+  }
+  if (changed) dts.saveSync();
+}
+log(`scrubbed ${scrubbedReexports} re-export(s) of impl classes from alias modules`);
+
 // 4. Copy the scrubbed tree to the output directory.
 rmSync(OUT, { recursive: true, force: true });
 mkdirSync(dirname(OUT), { recursive: true });
diff --git a/packages/agent-core-v2/src/_base/utils/fs.ts b/packages/agent-core-v2/src/_base/utils/fs.ts
index a6313013a18..7e1bb3e16d8 100644
--- a/packages/agent-core-v2/src/_base/utils/fs.ts
+++ b/packages/agent-core-v2/src/_base/utils/fs.ts
@@ -81,14 +81,18 @@ export async function atomicWrite(
   content: string | Uint8Array,
   _syncOverride?: (fd: number) => Promise<void>,
   mode?: number,
+  signal?: AbortSignal,
 ): Promise<void> {
+  signal?.throwIfAborted();
   const hex = randomBytes(4).toString('hex');
   const tmpPath = `${filePath}.tmp.${process.pid}.${hex}`;
   let renamed = false;
   try {
     const fh = await open(tmpPath, 'w', mode);
     try {
+      signal?.throwIfAborted();
       await fh.writeFile(content);
+      signal?.throwIfAborted();
       await (_syncOverride ?? syncFd)(fh.fd);
     } finally {
       await fh.close();
@@ -101,6 +105,7 @@ export async function atomicWrite(
         if (code !== 'ENOENT') throw error;
       }
     }
+    signal?.throwIfAborted();
     await rename(tmpPath, filePath);
     renamed = true;
   } finally {
@@ -117,18 +122,30 @@ export async function atomicWriteStream(
   filePath: string,
   source: AsyncIterable<Uint8Array>,
   mode?: number,
+  signal?: AbortSignal,
 ): Promise<void> {
+  signal?.throwIfAborted();
   const hex = randomBytes(4).toString('hex');
   const tmpPath = `${filePath}.tmp.${process.pid}.${hex}`;
   let renamed = false;
+  const destroyable = source as AsyncIterable<Uint8Array> & {
+    destroy?(error?: Error): void;
+  };
+  const onAbort = (): void => {
+    const reason = signal?.reason instanceof Error ? signal.reason : undefined;
+    destroyable.destroy?.(reason);
+  };
+  signal?.addEventListener('abort', onAbort, { once: true });
   try {
     const fh = await open(tmpPath, 'w', mode);
     try {
       for await (const chunk of source) {
+        signal?.throwIfAborted();
         if (chunk.byteLength > 0) {
           await fh.writeFile(chunk);
         }
       }
+      signal?.throwIfAborted();
       await fh.sync();
     } finally {
       await fh.close();
@@ -141,9 +158,11 @@ export async function atomicWriteStream(
         if (code !== 'ENOENT') throw error;
       }
     }
+    signal?.throwIfAborted();
     await rename(tmpPath, filePath);
     renamed = true;
   } finally {
+    signal?.removeEventListener('abort', onAbort);
     if (!renamed) {
       try {
         await unlink(tmpPath);
diff --git a/packages/agent-core-v2/src/agent/llmRequester/llmRequesterService.ts b/packages/agent-core-v2/src/agent/llmRequester/llmRequesterService.ts
index ae27064fb67..665dca6850e 100644
--- a/packages/agent-core-v2/src/agent/llmRequester/llmRequesterService.ts
+++ b/packages/agent-core-v2/src/agent/llmRequester/llmRequesterService.ts
@@ -9,9 +9,10 @@
  * resolved from `IModelCatalog`: one primary `requester.request(input, signal,
  * params)` attempt plus projection rebuilds for request structure or media
  * compatibility. Before each request the projected messages pass through `media`'s
- * video resolver, which rewrites every `kimi-file://` prompt-video reference
- * to a provider-acceptable part (uploaded `ms://`, inline base64, or a
- * `<video path>` tag) so the internal reference never reaches the wire. When a
+ * media resolver, which rewrites every `kimi-file://` prompt-media reference
+ * to a provider-acceptable part (an uploaded `ms://` video, an inline base64
+ * `data:` part, or a degradation tag/drop) so the internal reference never
+ * reaches the wire. When a
  * model is configured, `prepareTurnConfig` snapshots the
  * model, effective thinking effort, and system prompt at the turn boundary
  * so loop telemetry and every request in that turn share one configuration.
@@ -46,7 +47,7 @@ import { IAgentProfileService, type ProfileModelContext } from '#/agent/profile/
 import { IAgentStateService } from '#/agent/state/agentState';
 import { IAgentToolRegistryService } from '#/agent/toolRegistry/toolRegistry';
 import { IAgentToolSelectService } from '#/agent/toolSelect/toolSelect';
-import { IAgentVideoResolverService } from '#/agent/media/videoResolver';
+import { IAgentMediaResolverService } from '#/agent/media/mediaResolver';
 import { IAgentUsageService } from '#/agent/usage/usage';
 import { IConfigService } from '#/app/config/config';
 import { IEventBus } from '#/app/event/eventBus';
@@ -180,7 +181,7 @@ export class AgentLLMRequesterService implements IAgentLLMRequesterService {
     @IAgentTokenCountingService private readonly tokenCounting: IAgentTokenCountingService,
     @IAgentToolRegistryService private readonly tools: IAgentToolRegistryService,
     @IAgentToolSelectService private readonly toolSelect: IAgentToolSelectService,
-    @IAgentVideoResolverService private readonly videoResolver: IAgentVideoResolverService,
+    @IAgentMediaResolverService private readonly mediaResolver: IAgentMediaResolverService,
     @IAgentProfileService private readonly profile: IAgentProfileService,
     @IAgentUsageService private readonly usage: IAgentUsageService,
     @IConfigService private readonly config: IConfigService,
@@ -366,7 +367,7 @@ export class AgentLLMRequesterService implements IAgentLLMRequesterService {
       const projected = requestInput(projection);
       const input = {
         ...projected,
-        messages: await this.videoResolver.resolve(
+        messages: await this.mediaResolver.resolve(
           projected.messages,
           request.requester,
           signal,
diff --git a/packages/agent-core-v2/src/agent/loop/loopService.ts b/packages/agent-core-v2/src/agent/loop/loopService.ts
index ea9ca88e0f8..cea09f583c4 100644
--- a/packages/agent-core-v2/src/agent/loop/loopService.ts
+++ b/packages/agent-core-v2/src/agent/loop/loopService.ts
@@ -85,7 +85,7 @@ import {
   type TurnSeed,
 } from './stepRequest';
 import { StepRequestQueue, type StepRequestBatch } from './stepRequestQueue';
-import { isDisplayablePromptOrigin, turnPromptText, type TurnInterruptReason } from './turnEvents';
+import { isDisplayablePromptOrigin, projectTurnPrompt, type TurnInterruptReason } from './turnEvents';
 import { cancelTurn, endTurn, promptTurn, TurnModel } from './turnOps';
 
 export type LoopInterruptReason = 'aborted' | 'max_steps' | 'error';
@@ -470,11 +470,16 @@ export class AgentLoopService extends Disposable implements IAgentLoopService {
     this.wire.dispatch(promptTurn({ input: job.seed.input, origin }));
     job.turn.state = 'running';
     this.activeTurnJob = job;
+    const projection = isDisplayablePromptOrigin(origin)
+      ? projectTurnPrompt(job.seed.input, origin)
+      : undefined;
     this.eventBus.publish({
       type: 'turn.started',
       turnId: job.turn.id,
       origin,
-      prompt: isDisplayablePromptOrigin(origin) ? turnPromptText(job.seed.input, origin) : undefined,
+      prompt: projection?.text,
+      promptAttachments: projection?.attachments,
+      promptId: job.seed.promptId,
     });
     void this.runTurn(job.turn, job.ready).then(job.result.resolve, job.result.reject);
   }
diff --git a/packages/agent-core-v2/src/agent/loop/stepRequest.ts b/packages/agent-core-v2/src/agent/loop/stepRequest.ts
index f66490a5eed..fb7c438f6e4 100644
--- a/packages/agent-core-v2/src/agent/loop/stepRequest.ts
+++ b/packages/agent-core-v2/src/agent/loop/stepRequest.ts
@@ -29,6 +29,7 @@ export type StepRequestAdmission =
 export interface TurnSeed {
   readonly input: readonly ContentPart[];
   readonly origin: PromptOrigin;
+  readonly promptId?: string;
 }
 
 export interface StepRequestOptions {
diff --git a/packages/agent-core-v2/src/agent/loop/turnEvents.ts b/packages/agent-core-v2/src/agent/loop/turnEvents.ts
index 50a1d7d15a5..73243d1b927 100644
--- a/packages/agent-core-v2/src/agent/loop/turnEvents.ts
+++ b/packages/agent-core-v2/src/agent/loop/turnEvents.ts
@@ -9,15 +9,25 @@
  * prompt rides the event only for displayable user origins
  * ({@link isDisplayablePromptOrigin}) — a system-triggered turn (goal
  * continuation, subagent run, cron…) has internal steering text as its input,
- * which must never surface in transcripts. When the turn's prompt bundles
+ * which must never surface in transcripts. An upload's daemon-ref media part
+ * is self-contained (`daemonFileRefFromPart`): its kind comes from the part
+ * type and its file id from the reference, so the projection needs no
+ * tag+ref pairing — the referenced media rides as
+ * {@link TurnStartedEvent.promptAttachments}. When the turn's prompt bundles
  * skill activations, their rendered blocks (prepended to the content, one
  * text part per skill) are excluded from the extracted text.
+ * `turn.started` also echoes the prompt record id as
+ * {@link TurnStartedEvent.promptId} when the turn was opened by a prompt
+ * submission, so submitters can bind their own bookkeeping (e.g. staged
+ * uploads) to the exact turn that consumed them; turns opened any other way
+ * (retry, goal continuation, …) leave it absent.
  */
 
 import type { KimiErrorPayload } from '#/_base/errors/serialize';
 import type { PromptOrigin } from '#/agent/contextMemory/types';
 import type { FinishReason } from '#/kosong/contract/provider';
 import type { ContentPart, TextPart } from '#/kosong/contract/message';
+import { daemonFileRefFromPart } from '#/agent/media/mediaRef';
 import type { TokenUsage } from '#/kosong/contract/usage';
 
 export type TurnEndReason = 'completed' | 'cancelled' | 'failed' | 'blocked';
@@ -30,24 +40,56 @@ export type TurnInterruptReason =
   | 'filtered'
   | 'blocked';
 
+/**
+ * One daemon-referenced upload carried by the turn-opening input.
+ */
+export interface TurnPromptAttachment {
+  readonly kind: 'image' | 'video';
+  readonly fileId: string;
+}
+
 export interface TurnStartedEvent {
   readonly type: 'turn.started';
   readonly turnId: number;
   readonly origin: PromptOrigin;
   readonly prompt?: string;
+  readonly promptAttachments?: readonly TurnPromptAttachment[];
+  readonly promptId?: string;
+}
+
+/**
+ * The displayable projection of the turn-opening input: the prompt text,
+ * plus one entry per daemon-referenced upload.
+ */
+export interface TurnPromptProjection {
+  readonly text?: string;
+  readonly attachments?: readonly TurnPromptAttachment[];
 }
 
-export function turnPromptText(
+export function projectTurnPrompt(
   input: readonly ContentPart[],
   origin?: PromptOrigin,
-): string | undefined {
+): TurnPromptProjection {
   const bundledBlocks = origin?.kind === 'user' ? (origin.skillActivations?.length ?? 0) : 0;
   const text = input
     .filter((part): part is TextPart => part.type === 'text')
     .slice(bundledBlocks)
     .map((part) => part.text)
     .join('');
-  return text.length > 0 ? text : undefined;
+  const media = input.flatMap((part) => {
+    const daemonPart = daemonFileRefFromPart(part);
+    return daemonPart === undefined ? [] : [daemonPart];
+  });
+  return {
+    text: text.length > 0 ? text : undefined,
+    attachments:
+      media.length === 0
+        ? undefined
+        : media.map((entry) => ({
+            kind: entry.kind,
+            fileId: entry.ref.fileId,
+          })),
+  };
 }
 
 export function isDisplayablePromptOrigin(origin: PromptOrigin): boolean {
diff --git a/packages/agent-core-v2/src/agent/media/file-type.ts b/packages/agent-core-v2/src/agent/media/file-type.ts
index 809462aed63..7d2e93302e9 100644
--- a/packages/agent-core-v2/src/agent/media/file-type.ts
+++ b/packages/agent-core-v2/src/agent/media/file-type.ts
@@ -6,6 +6,14 @@
  * no scoped service.
  */
 
+import {
+  AUDIO_MIME_BY_SUFFIX,
+  IMAGE_MIME_BY_SUFFIX,
+  VIDEO_MIME_BY_SUFFIX,
+} from './mediaRef';
+
+export { AUDIO_MIME_BY_SUFFIX, IMAGE_MIME_BY_SUFFIX, VIDEO_MIME_BY_SUFFIX };
+
 export const MEDIA_SNIFF_BYTES = 512;
 
 export interface FileType {
@@ -15,38 +23,6 @@ export interface FileType {
 
 export type DetectFileTypeMode = 'text' | 'media';
 
-export const IMAGE_MIME_BY_SUFFIX: Readonly<Record<string, string>> = Object.freeze({
-  '.png': 'image/png',
-  '.jpg': 'image/jpeg',
-  '.jpeg': 'image/jpeg',
-  '.gif': 'image/gif',
-  '.bmp': 'image/bmp',
-  '.tif': 'image/tiff',
-  '.tiff': 'image/tiff',
-  '.webp': 'image/webp',
-  '.ico': 'image/x-icon',
-  '.heic': 'image/heic',
-  '.heif': 'image/heif',
-  '.avif': 'image/avif',
-  '.svgz': 'image/svg+xml',
-});
-
-export const VIDEO_MIME_BY_SUFFIX: Readonly<Record<string, string>> = Object.freeze({
-  '.mp4': 'video/mp4',
-  '.mpg': 'video/mpeg',
-  '.mpeg': 'video/mpeg',
-  '.mkv': 'video/x-matroska',
-  '.avi': 'video/x-msvideo',
-  '.mov': 'video/quicktime',
-  '.ogv': 'video/ogg',
-  '.wmv': 'video/x-ms-wmv',
-  '.webm': 'video/webm',
-  '.m4v': 'video/x-m4v',
-  '.flv': 'video/x-flv',
-  '.3gp': 'video/3gpp',
-  '.3g2': 'video/3gpp2',
-});
-
 const TEXT_MIME_BY_SUFFIX: Readonly<Record<string, string>> = Object.freeze({
   '.svg': 'image/svg+xml',
 });
diff --git a/packages/agent-core-v2/src/agent/media/kimiFileUrl.ts b/packages/agent-core-v2/src/agent/media/kimiFileUrl.ts
index 7615648aa5b..d7a26ef915c 100644
--- a/packages/agent-core-v2/src/agent/media/kimiFileUrl.ts
+++ b/packages/agent-core-v2/src/agent/media/kimiFileUrl.ts
@@ -1,50 +1,15 @@
 /**
- * `media` domain — the `kimi-file://` internal video reference.
+ * `media` domain — the `kimi-file://` internal media reference.
  *
- * A prompt video uploaded to `/files` enters context memory as a `video_url`
- * part carrying `kimi-file://<fileId>?path=<encoded absolute path>`: `fileId`
- * addresses the daemon upload the request-time resolver reads bytes from, and
- * the optional `?path=` names the edge-materialized copy the model opens with
- * `ReadMediaFile` when the video cannot be uploaded or inlined. The reference
- * never reaches the provider wire — the resolver rewrites it first. Pure
- * helpers; no scoped service.
+ * Aliases of the sibling daemon file reference helpers (`./mediaRef`), kept
+ * under the historical names so existing call sites read unchanged. New code
+ * should prefer the canonical `*DaemonFile*` names.
+ * Pure helpers; no scoped service.
  */
 
-const KIMI_FILE_SCHEME = 'kimi-file://';
-const PATH_QUERY = '?path=';
-
-export interface KimiFileRef {
-  readonly fileId: string;
-  readonly path?: string;
-}
-
-export function isKimiFileUrl(url: string): boolean {
-  return url.startsWith(KIMI_FILE_SCHEME);
-}
-
-export function buildKimiFileUrl(fileId: string, path?: string): string {
-  const base = `${KIMI_FILE_SCHEME}${fileId}`;
-  return path === undefined || path.length === 0
-    ? base
-    : `${base}${PATH_QUERY}${encodeURIComponent(path)}`;
-}
-
-export function parseKimiFileUrl(url: string): KimiFileRef | undefined {
-  if (!url.startsWith(KIMI_FILE_SCHEME)) return undefined;
-  const rest = url.slice(KIMI_FILE_SCHEME.length);
-  const queryAt = rest.indexOf(PATH_QUERY);
-  if (queryAt === -1) {
-    return rest.length > 0 ? { fileId: rest } : undefined;
-  }
-  const fileId = rest.slice(0, queryAt);
-  if (fileId.length === 0) return undefined;
-  const encoded = rest.slice(queryAt + PATH_QUERY.length);
-  if (encoded.length === 0) return { fileId };
-  let path: string;
-  try {
-    path = decodeURIComponent(encoded);
-  } catch {
-    return { fileId };
-  }
-  return { fileId, path };
-}
+export {
+  buildDaemonFileUrl as buildKimiFileUrl,
+  isDaemonFileUrl as isKimiFileUrl,
+  parseDaemonFileUrl as parseKimiFileUrl,
+  type DaemonFileRef as KimiFileRef,
+} from './mediaRef';
diff --git a/packages/agent-core-v2/src/agent/media/mediaRef.ts b/packages/agent-core-v2/src/agent/media/mediaRef.ts
new file mode 100644
index 00000000000..e76d0ce847b
--- /dev/null
+++ b/packages/agent-core-v2/src/agent/media/mediaRef.ts
@@ -0,0 +1,242 @@
+/**
+ * `media` domain — media classification and daemon file references.
+ *
+ * "Media kind" is the classification every upload edge, resolver, and
+ * projection agrees on: `image`, `video`, and `audio` (the media content-part
+ * kinds a model can consume) plus `file` (anything else, which always
+ * degrades to a path reference). The helpers derive the kind from a content
+ * part, a MIME type, or a path suffix, and the suffix tables are the single
+ * source of truth for suffix ↔ MIME mapping — `agent/media/file-type`
+ * re-exports them for its magic-byte detection. `mediaExtensionForMime`
+ * inverts the tables (first suffix wins) so every materialization path
+ * derives the same file extension for an extensionless upload.
+ *
+ * A daemon file reference is the internal `kimi-file://<fileId>` URL:
+ * `fileId` addresses the daemon upload the request-time media resolver reads
+ * bytes from. The reference lives in context memory and never reaches the
+ * provider wire — the resolver rewrites it first. The kind of a referenced
+ * file is carried by the enclosing content part (`image_url` / `video_url`),
+ * never by the URL itself, so existing references stay valid.
+ *
+ * The materialized copy lives at the session-canonical location
+ * (`sessionMediaFilePath`: `<sessionDir>/media/<fileId><ext>`), written by
+ * the session media store at prompt intake. The reference deliberately
+ * carries no path: a persisted absolute path would bind the durable record
+ * to one machine and one home directory (a fork or a home relocation would
+ * stale it), so the display path is derived from the session media store by
+ * file id at read time instead. A legacy `?path=` query (the retired
+ * write-time snapshot) is tolerated at parse time and ignored.
+ *
+ * The `<image|video|audio|file path="…">` tag is the model-facing
+ * degradation form: the resolver swaps a media part for the tag when the
+ * bytes cannot reach the provider, and plain-text edges (skill/plugin args)
+ * write it directly; clients parse it back to render or re-open the file.
+ * Emission escapes the path as an XML attribute; parsing unescapes it and
+ * tolerates extra attributes and a missing closing tag.
+ * `matchSingleMediaPathTag` matches only when the whole (trimmed) text is
+ * exactly one tag; tags embedded in larger user text are never matched,
+ * because treating them as markup would eat user content.
+ *
+ * A daemon-ref media part is self-contained: read models derive the
+ * attachment (kind from the part type, file id from the reference) straight
+ * from the part via `daemonFileRefFromPart` — there is no tag+ref pairing
+ * to compute. A standalone tag in history is user-visible text or a legacy
+ * degrade form and always stays a text part.
+ *
+ * Pure types and pure functions only — no I/O, no SDKs; depends only on the
+ * `ContentPart` envelope type from `kosong/contract`.
+ */
+
+import { join } from 'node:path';
+
+import type { ContentPart } from '#/kosong/contract/message';
+
+export type MediaKind = 'image' | 'video' | 'audio' | 'file';
+
+export const IMAGE_MIME_BY_SUFFIX: Readonly<Record<string, string>> = Object.freeze({
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.bmp': 'image/bmp',
+  '.tif': 'image/tiff',
+  '.tiff': 'image/tiff',
+  '.webp': 'image/webp',
+  '.ico': 'image/x-icon',
+  '.heic': 'image/heic',
+  '.heif': 'image/heif',
+  '.avif': 'image/avif',
+  '.svgz': 'image/svg+xml',
+});
+
+export const VIDEO_MIME_BY_SUFFIX: Readonly<Record<string, string>> = Object.freeze({
+  '.mp4': 'video/mp4',
+  '.mpg': 'video/mpeg',
+  '.mpeg': 'video/mpeg',
+  '.mkv': 'video/x-matroska',
+  '.avi': 'video/x-msvideo',
+  '.mov': 'video/quicktime',
+  '.ogv': 'video/ogg',
+  '.wmv': 'video/x-ms-wmv',
+  '.webm': 'video/webm',
+  '.m4v': 'video/x-m4v',
+  '.flv': 'video/x-flv',
+  '.3gp': 'video/3gpp',
+  '.3g2': 'video/3gpp2',
+});
+
+export const AUDIO_MIME_BY_SUFFIX: Readonly<Record<string, string>> = Object.freeze({
+  '.mp3': 'audio/mpeg',
+  '.wav': 'audio/wav',
+  '.m4a': 'audio/mp4',
+  '.ogg': 'audio/ogg',
+  '.oga': 'audio/ogg',
+  '.flac': 'audio/flac',
+  '.aac': 'audio/aac',
+  '.opus': 'audio/opus',
+  '.weba': 'audio/webm',
+  '.wma': 'audio/x-ms-wma',
+});
+
+const IMAGE_EXT_BY_MIME = invertMimeBySuffix(IMAGE_MIME_BY_SUFFIX);
+const VIDEO_EXT_BY_MIME = invertMimeBySuffix(VIDEO_MIME_BY_SUFFIX);
+const AUDIO_EXT_BY_MIME = invertMimeBySuffix(AUDIO_MIME_BY_SUFFIX);
+
+function invertMimeBySuffix(table: Readonly<Record<string, string>>): Readonly<Record<string, string>> {
+  const out: Record<string, string> = {};
+  for (const [suffix, mime] of Object.entries(table)) {
+    out[mime] ??= suffix;
+  }
+  return Object.freeze(out);
+}
+
+export function mediaExtensionForMime(mimeType: string): string | undefined {
+  const semi = mimeType.indexOf(';');
+  const base = (semi === -1 ? mimeType : mimeType.slice(0, semi)).trim().toLowerCase();
+  return VIDEO_EXT_BY_MIME[base] ?? IMAGE_EXT_BY_MIME[base] ?? AUDIO_EXT_BY_MIME[base];
+}
+
+function mediaSuffix(path: string): string {
+  const idx = path.lastIndexOf('.');
+  if (idx === -1) return '';
+  const lastSep = Math.max(path.lastIndexOf('/'), path.lastIndexOf('\\'));
+  if (idx <= lastSep + 1) return '';
+  return path.slice(idx).toLowerCase();
+}
+
+export function mediaKindForPath(path: string): 'image' | 'video' | 'audio' | undefined {
+  const suffix = mediaSuffix(path);
+  if (suffix in IMAGE_MIME_BY_SUFFIX) return 'image';
+  if (suffix in VIDEO_MIME_BY_SUFFIX) return 'video';
+  if (suffix in AUDIO_MIME_BY_SUFFIX) return 'audio';
+  return undefined;
+}
+
+export function mediaKindForMime(mimeType: string): 'image' | 'video' | 'audio' | undefined {
+  const semi = mimeType.indexOf(';');
+  const base = (semi === -1 ? mimeType : mimeType.slice(0, semi)).trim().toLowerCase();
+  if (base.startsWith('image/')) return 'image';
+  if (base.startsWith('video/')) return 'video';
+  if (base.startsWith('audio/')) return 'audio';
+  return undefined;
+}
+
+export function mediaKindOfPart(part: ContentPart): 'image' | 'video' | 'audio' | undefined {
+  if (part.type === 'image_url') return 'image';
+  if (part.type === 'video_url') return 'video';
+  if (part.type === 'audio_url') return 'audio';
+  return undefined;
+}
+
+const KIMI_FILE_SCHEME = 'kimi-file://';
+
+export interface DaemonFileRef {
+  readonly fileId: string;
+}
+
+export function isDaemonFileUrl(url: string): boolean {
+  return url.startsWith(KIMI_FILE_SCHEME);
+}
+
+export function buildDaemonFileUrl(fileId: string): string {
+  return `${KIMI_FILE_SCHEME}${fileId}`;
+}
+
+export function parseDaemonFileUrl(url: string): DaemonFileRef | undefined {
+  if (!url.startsWith(KIMI_FILE_SCHEME)) return undefined;
+  const rest = url.slice(KIMI_FILE_SCHEME.length);
+  const queryAt = rest.indexOf('?');
+  const fileId = queryAt === -1 ? rest : rest.slice(0, queryAt);
+  return fileId.length > 0 ? { fileId } : undefined;
+}
+
+export function daemonFileRefFromPart(
+  part: ContentPart,
+): { readonly kind: 'image' | 'video'; readonly ref: DaemonFileRef } | undefined {
+  if (part.type === 'image_url') {
+    const ref = parseDaemonFileUrl(part.imageUrl.url);
+    return ref === undefined ? undefined : { kind: 'image', ref };
+  }
+  if (part.type === 'video_url') {
+    const ref = parseDaemonFileUrl(part.videoUrl.url);
+    return ref === undefined ? undefined : { kind: 'video', ref };
+  }
+  return undefined;
+}
+
+export const SESSION_MEDIA_DIR = 'media';
+
+export function sessionMediaFilePath(sessionDir: string, fileId: string, ext: string): string {
+  return join(sessionDir, SESSION_MEDIA_DIR, `${fileId}${ext}`);
+}
+
+const MEDIA_PATH_TAG_RE = /<(image|video|audio|file)\b[^>]*?\bpath="([^"]*)"[^>]*>(?:<\/\1>)?/g;
+
+export interface MediaPathTag {
+  readonly kind: MediaKind;
+  readonly path: string;
+  readonly index: number;
+  readonly text: string;
+}
+
+export function escapeMediaAttribute(value: string): string {
+  return value
+    .replaceAll('&', '&amp;')
+    .replaceAll('"', '&quot;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;');
+}
+
+export function unescapeMediaAttribute(value: string): string {
+  return value
+    .replaceAll('&quot;', '"')
+    .replaceAll('&lt;', '<')
+    .replaceAll('&gt;', '>')
+    .replaceAll('&amp;', '&');
+}
+
+export function buildMediaPathTag(kind: MediaKind, path: string): string {
+  return `<${kind} path="${escapeMediaAttribute(path)}"></${kind}>`;
+}
+
+export function matchMediaPathTags(text: string): MediaPathTag[] {
+  const tags: MediaPathTag[] = [];
+  for (const match of text.matchAll(MEDIA_PATH_TAG_RE)) {
+    tags.push({
+      kind: match[1] as MediaKind,
+      path: unescapeMediaAttribute(match[2]!),
+      index: match.index,
+      text: match[0],
+    });
+  }
+  return tags;
+}
+
+export function matchSingleMediaPathTag(text: string): MediaPathTag | undefined {
+  const trimmed = text.trim();
+  if (trimmed.length === 0) return undefined;
+  const tags = matchMediaPathTags(trimmed);
+  if (tags.length !== 1) return undefined;
+  const tag = tags[0]!;
+  return tag.index === 0 && tag.text.length === trimmed.length ? tag : undefined;
+}
diff --git a/packages/agent-core-v2/src/agent/media/mediaResolver.ts b/packages/agent-core-v2/src/agent/media/mediaResolver.ts
new file mode 100644
index 00000000000..5ef82ff9713
--- /dev/null
+++ b/packages/agent-core-v2/src/agent/media/mediaResolver.ts
@@ -0,0 +1,32 @@
+/**
+ * `media` domain — request-time media reference resolver contract.
+ *
+ * Rewrites the `kimi-file://` daemon references a prompt carries in the
+ * projected wire messages into provider-acceptable parts (an uploaded
+ * `ms://` video reference, an inline base64 `data:` part, a `<video path>`
+ * or `<image path>` text tag, or an unavailable-placeholder text part)
+ * right before the messages reach the provider — so a `kimi-file://` url
+ * never touches the wire. Bound at Agent scope.
+ *
+ * The decorator keeps the historical `agentVideoResolverService` name so the
+ * DI identity (and the debug-RPC channel surface built from decorator names)
+ * stays stable across the video-only → media rename.
+ */
+
+import { createDecorator } from '#/_base/di/instantiation';
+import type { Message } from '#/kosong/contract/message';
+import type { ModelRequester } from '#/kosong/model/modelRequester';
+
+export interface IAgentMediaResolverService {
+  readonly _serviceBrand: undefined;
+
+  resolve(
+    messages: readonly Message[],
+    requester: ModelRequester,
+    signal?: AbortSignal,
+  ): Promise<readonly Message[]>;
+}
+
+export const IAgentMediaResolverService = createDecorator<IAgentMediaResolverService>(
+  'agentVideoResolverService',
+);
diff --git a/packages/agent-core-v2/src/agent/media/mediaResolverService.ts b/packages/agent-core-v2/src/agent/media/mediaResolverService.ts
new file mode 100644
index 00000000000..a1267082d9d
--- /dev/null
+++ b/packages/agent-core-v2/src/agent/media/mediaResolverService.ts
@@ -0,0 +1,438 @@
+/**
+ * `media` domain — `IAgentMediaResolverService` implementation.
+ *
+ * Resolves each `kimi-file://` daemon reference in the projected wire
+ * messages to a provider-acceptable part right before the request leaves for
+ * the wire, so the internal reference never reaches the provider. The
+ * referenced bytes are read through the `file` domain (`IFileService`) and
+ * the referenced kind is carried by the enclosing content part
+ * (`image_url` / `video_url`), so the two kinds resolve through different
+ * strategies:
+ *
+ * Video: uploads the bytes through the bound model's
+ * `ModelRequester.uploadVideo` (wrapped for `video_upload` telemetry through
+ * `createVideoUploader`) and persists the `(file, provider) → llmFileId`
+ * mapping through the `blobStore` access-pattern store so the upload happens
+ * once across a turn's steps, retries, and media-recovery reprojections.
+ * Falls back to an inline base64 `video_url` (protocols that carry it) or a
+ * `<video path>` text tag (the model then opens the session-materialized copy
+ * with `ReadMediaFile`); auth failures surface so they drive credential
+ * refresh instead of masking a bad token, and an upload interrupted by the
+ * step's aborted signal re-throws — shape-agnostic, since abort rejections
+ * vary by provider — so cancellation ends the request instead of memoizing a
+ * degraded fallback for the rest of the agent's lifetime. Resolution
+ * outcomes are memoized per (file, provider) for step/retry stability —
+ * except a transient upload failure, which degrades only the current request
+ * to the tag form so a later step retries the upload instead of freezing the
+ * fallback. The `video_in` capability gate runs before the memo lookup
+ * (mirroring the image strategy), so a switch to a video-incapable model
+ * degrades to the tag instead of replaying a memoized upload reference.
+ *
+ * Image: inlines the bytes as a base64 `data:` `image_url` part — kosong has
+ * no image upload channel, so there is no provider reference to persist. The
+ * inline part depends only on the immutable upload bytes, not on the
+ * requester, so a successful inline is memoized per file id in a private
+ * byte-budgeted LRU (per-entry cap plus a total budget; the least-recently
+ * hit entries are evicted, and a miss simply re-reads the bytes) and reused
+ * across steps, retries, and media-recovery reprojections instead of
+ * re-reading and re-encoding the same bytes on every request; the degrade
+ * forms are never memoized, so the display path is re-derived through the
+ * session media store on every request. The bytes are sniffed
+ * (`detectFileType`) and gated against the provider-accepted image formats
+ * (`isModelAcceptedImageMime`) as defense in depth —
+ * the ingest edges already refuse unaccepted formats. A reference that
+ * cannot be inlined (model without `image_in`, unreadable bytes, non-image
+ * or unaccepted sniff) degrades to the `<image path>` tag SYNTHESIZED from
+ * the store-derived display path so the model keeps a path to re-open; when
+ * no canonical copy exists it swaps in an unavailable placeholder text. A
+ * message left with no parts at all keeps one placeholder so its content
+ * never goes empty.
+ *
+ * The path offered to the model in any degrade form is derived at request
+ * time from the session media store (`ISessionMediaStore`): the canonical
+ * copy is located by file id, so a fork or a home relocation never hands the
+ * model a dead path. A memoized video tag has its path refreshed on every
+ * hit for the same reason.
+ *
+ * The plain-data state (`resolved`, the video memo) is registered into
+ * `agentState` (`IAgentStateService`) and read/written through it. The image
+ * memo stays a private field instead: a memoized inline part is a multi-MB
+ * base64 string, and the state registry's snapshot/inspect path serializes
+ * every registered state in full. Bound at Agent scope.
+ */
+
+import { createHash } from 'node:crypto';
+
+import { ScopeActivation, registerScopedService } from '#/_base/di/scope';
+import { defineState } from '#/_base/state/stateRegistry';
+import { IAgentStateService } from '#/agent/state/agentState';
+import { IFileService } from '#/app/file/fileService';
+import { LifecycleScope } from '#/app/scopes';
+import { ITelemetryService } from '#/app/telemetry/telemetry';
+import type { ContentPart, Message } from '#/kosong/contract/message';
+import type { ModelRequester } from '#/kosong/model/modelRequester';
+import { IBlobStore } from '#/persistence/interface/blobStore';
+
+import { detectFileType, MEDIA_SNIFF_BYTES } from './file-type';
+import { isModelAcceptedImageMime, normalizeImageMime } from './image-format-policy';
+import {
+  buildMediaPathTag,
+  type DaemonFileRef,
+  daemonFileRefFromPart,
+  matchSingleMediaPathTag,
+} from './mediaRef';
+import { ISessionMediaStore } from './sessionMediaStore';
+import { IAgentMediaResolverService } from './mediaResolver';
+import { createVideoUploader } from './registerMediaTools';
+import {
+  inlineVideoPart,
+  inlineVideoSupportedForProtocol,
+  isVideoUploadAuthError,
+  isVideoUploadUnsupportedError,
+} from './videoUpload';
+
+const CACHE_SCOPE = 'video-upload-cache';
+const PROVIDER_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const VIDEO_UNAVAILABLE_TEXT =
+  '[video omitted: the uploaded file is no longer available]';
+const IMAGE_UNAVAILABLE_TEXT =
+  '[image omitted: the uploaded file is no longer available]';
+/**
+ * A memoized inline image pins its base64 form in the resolver's memory;
+ * skip the memo for outsized uploads so a rare huge paste is re-read from
+ * disk per request instead of pinning memory. The total budget caps the
+ * whole memo — at least eight full-size entries — and once it is exceeded
+ * the least-recently hit entries are evicted.
+ */
+const IMAGE_MEMO_MAX_BYTES = 8 * 1024 * 1024;
+const IMAGE_MEMO_MAX_TOTAL_BYTES = 64 * 1024 * 1024;
+
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder();
+
+export const mediaResolvedKey = defineState<Map<string, ContentPart>>(
+  'media.resolved',
+  () => new Map(),
+);
+
+export class AgentMediaResolverService implements IAgentMediaResolverService {
+  declare readonly _serviceBrand: undefined;
+
+  constructor(
+    @IFileService private readonly files: IFileService,
+    @IBlobStore private readonly blobs: IBlobStore,
+    @ITelemetryService private readonly telemetry: ITelemetryService,
+    @IAgentStateService private readonly states: IAgentStateService,
+    @ISessionMediaStore private readonly mediaStore: ISessionMediaStore,
+  ) {
+    this.states.register(mediaResolvedKey);
+  }
+
+  private get resolved(): Map<string, ContentPart> {
+    return this.states.get(mediaResolvedKey);
+  }
+
+  private readonly imageMemo = new Map<string, { part: ContentPart; bytes: number }>();
+  private imageMemoBytes = 0;
+
+  async resolve(
+    messages: readonly Message[],
+    requester: ModelRequester,
+    signal?: AbortSignal,
+  ): Promise<readonly Message[]> {
+    if (!messages.some(hasDaemonFileMediaPart)) return messages;
+
+    let changed = false;
+    const out: Message[] = [];
+    for (const message of messages) {
+      if (!hasDaemonFileMediaPart(message)) {
+        out.push(message);
+        continue;
+      }
+      const content: ContentPart[] = [];
+      let sawVideoRef = false;
+      for (const part of message.content) {
+        const daemonPart = daemonFileRefFromPart(part);
+        if (daemonPart === undefined) {
+          content.push(part);
+          continue;
+        }
+        sawVideoRef ||= daemonPart.kind === 'video';
+        const resolved =
+          daemonPart.kind === 'video'
+            ? await this.resolveVideoPart(daemonPart.ref, requester, signal)
+            : await this.resolveImagePart(daemonPart.ref, requester, signal);
+        content.push(resolved);
+      }
+      // A message whose parts were all dropped keeps one kind-matching
+      // placeholder so its content never goes empty.
+      out.push({
+        ...message,
+        content:
+          content.length > 0
+            ? content
+            : [unavailableMediaText(sawVideoRef ? 'video' : 'image')],
+      });
+      changed = true;
+    }
+    return changed ? out : messages;
+  }
+
+  private displayPath(ref: DaemonFileRef): Promise<string | undefined> {
+    return this.mediaStore.resolveDisplayPath(ref.fileId);
+  }
+
+  // -------------------------------------------------------------------------
+  // Image strategy — inline-only; no provider upload; the inline part itself
+  // is memoized per file id, degrade forms are not.
+  // -------------------------------------------------------------------------
+
+  private async resolveImagePart(
+    ref: DaemonFileRef,
+    requester: ModelRequester,
+    signal: AbortSignal | undefined,
+  ): Promise<ContentPart> {
+    if (!requester.model.capabilities.image_in) {
+      return degradedImage(await this.displayPath(ref));
+    }
+    // Memo hit: the inline part is requester-independent, so a previous
+    // successful resolve is reused without touching the bytes again.
+    const cacheKey = `image\0${ref.fileId}`;
+    const memoed = this.memoedImage(cacheKey);
+    if (memoed !== undefined) return memoed;
+    const path = await this.displayPath(ref);
+
+    let source: { readonly bytes: Buffer; readonly filename: string };
+    try {
+      source = await this.readMedia(ref, signal);
+    } catch {
+      signal?.throwIfAborted();
+      return degradedImage(path);
+    }
+
+    const fileType = detectFileType(
+      source.filename,
+      source.bytes.subarray(0, MEDIA_SNIFF_BYTES),
+      'media',
+    );
+    if (fileType.kind !== 'image') return degradedImage(path);
+    if (!isModelAcceptedImageMime(fileType.mimeType)) return degradedImage(path);
+
+    const part: ContentPart = {
+      type: 'image_url',
+      imageUrl: {
+        url: `data:${normalizeImageMime(fileType.mimeType)};base64,${source.bytes.toString('base64')}`,
+      },
+    };
+    if (source.bytes.length <= IMAGE_MEMO_MAX_BYTES) {
+      this.memoizeImage(cacheKey, part, source.bytes.length);
+    }
+    return part;
+  }
+
+  private memoedImage(cacheKey: string): ContentPart | undefined {
+    const entry = this.imageMemo.get(cacheKey);
+    if (entry === undefined) return undefined;
+    // A hit refreshes recency (a Map iterates in insertion order).
+    this.imageMemo.delete(cacheKey);
+    this.imageMemo.set(cacheKey, entry);
+    return entry.part;
+  }
+
+  private memoizeImage(cacheKey: string, part: ContentPart, bytes: number): void {
+    this.imageMemo.set(cacheKey, { part, bytes });
+    this.imageMemoBytes += bytes;
+    // Evict least-recently hit entries until the total budget holds again.
+    for (const [key, entry] of this.imageMemo) {
+      if (this.imageMemoBytes <= IMAGE_MEMO_MAX_TOTAL_BYTES) return;
+      this.imageMemo.delete(key);
+      this.imageMemoBytes -= entry.bytes;
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Video strategy — upload once, memoize, degrade to inline or tag.
+  // -------------------------------------------------------------------------
+
+  private async resolveVideoPart(
+    ref: DaemonFileRef,
+    requester: ModelRequester,
+    signal: AbortSignal | undefined,
+  ): Promise<ContentPart> {
+    const model = requester.model;
+    // The capability gate runs before the memo lookup (mirroring the image
+    // strategy): an `ms://` part memoized under a video-capable model must
+    // not leak to a same-provider model that cannot accept video.
+    if (!model.capabilities.video_in) return videoTag(await this.displayPath(ref));
+    const providerKey = model.providerType ?? model.protocol;
+    const cacheKey = `${ref.fileId}\0${providerKey}`;
+
+    const memoed = this.resolved.get(cacheKey);
+    if (memoed !== undefined) return this.memoedOutcome(ref, memoed);
+
+    const { part, memoize } = await this.resolveVideoUncached(ref, requester, cacheKey, signal);
+    if (memoize) this.resolved.set(cacheKey, part);
+    return part;
+  }
+
+  private async memoedOutcome(ref: DaemonFileRef, memoed: ContentPart): Promise<ContentPart> {
+    if (memoed.type !== 'text') return memoed;
+    const tag = matchSingleMediaPathTag(memoed.text);
+    if (tag === undefined) return memoed;
+    const path = await this.displayPath(ref);
+    if (path === undefined || path === tag.path) return memoed;
+    return { type: 'text', text: buildMediaPathTag(tag.kind, path) };
+  }
+
+  private async resolveVideoUncached(
+    ref: DaemonFileRef,
+    requester: ModelRequester,
+    cacheKey: string,
+    signal: AbortSignal | undefined,
+  ): Promise<{ part: ContentPart; memoize: boolean }> {
+    const cachedLlmFileId = await this.readCachedUpload(cacheKey);
+    if (cachedLlmFileId !== undefined) {
+      return {
+        part: { type: 'video_url', videoUrl: { url: `ms://${cachedLlmFileId}`, id: cachedLlmFileId } },
+        memoize: true,
+      };
+    }
+    const tagPath = await this.displayPath(ref);
+
+    let source: { readonly bytes: Buffer; readonly filename: string };
+    try {
+      source = await this.readMedia(ref, signal);
+    } catch {
+      signal?.throwIfAborted();
+      return { part: videoTag(tagPath), memoize: true };
+    }
+
+    const { bytes, filename } = source;
+    const fileType = detectFileType(filename, bytes.subarray(0, MEDIA_SNIFF_BYTES), 'media');
+    if (fileType.kind !== 'video') return { part: videoTag(tagPath), memoize: true };
+    const mimeType = fileType.mimeType;
+
+    const model = requester.model;
+    const inlineSupported = inlineVideoSupportedForProtocol(model.protocol);
+
+    const uploader = createVideoUploader(requester, {
+      client: this.telemetry,
+      props: {
+        model: model.name,
+        provider_type: model.providerType ?? model.protocol,
+        protocol: model.protocol,
+      },
+    });
+    if (uploader === undefined) {
+      return {
+        part: inlineSupported ? inlineVideoPart(bytes, mimeType) : videoTag(tagPath),
+        memoize: true,
+      };
+    }
+
+    try {
+      const uploaded = await uploader({ data: bytes, mimeType, filename }, { signal });
+      const llmFileId = uploaded.videoUrl.id ?? msFileIdFromUrl(uploaded.videoUrl.url);
+      if (llmFileId !== undefined) await this.writeCachedUpload(cacheKey, llmFileId);
+      return { part: uploaded, memoize: true };
+    } catch (error) {
+      if (signal?.aborted) throw error;
+      if (isVideoUploadAuthError(error)) throw error;
+      if (isVideoUploadUnsupportedError(error)) {
+        return {
+          part: inlineSupported ? inlineVideoPart(bytes, mimeType) : videoTag(tagPath),
+          memoize: true,
+        };
+      }
+      return { part: videoTag(tagPath), memoize: false };
+    }
+  }
+
+  private async readMedia(
+    ref: DaemonFileRef,
+    signal: AbortSignal | undefined,
+  ): Promise<{ readonly bytes: Buffer; readonly filename: string }> {
+    try {
+      signal?.throwIfAborted();
+      const file = await this.files.get(ref.fileId);
+      const bytes = await readStream(file.stream(), signal);
+      return { bytes, filename: file.meta.name };
+    } catch {
+      signal?.throwIfAborted();
+      const canonical = await this.mediaStore.read(ref.fileId);
+      if (canonical === undefined) throw new Error(`media ${ref.fileId} is unavailable`);
+      return { bytes: Buffer.from(canonical.data), filename: canonical.name };
+    }
+  }
+
+  private async readCachedUpload(cacheKey: string): Promise<string | undefined> {
+    const data = await this.blobs.get(CACHE_SCOPE, blobKey(cacheKey)).catch(() => undefined);
+    if (data === undefined) return undefined;
+    const llmFileId = textDecoder.decode(data);
+    return PROVIDER_ID_RE.test(llmFileId) ? llmFileId : undefined;
+  }
+
+  private async writeCachedUpload(cacheKey: string, llmFileId: string): Promise<void> {
+    if (!PROVIDER_ID_RE.test(llmFileId)) return;
+    await this.blobs.put(CACHE_SCOPE, blobKey(cacheKey), textEncoder.encode(llmFileId)).catch(
+      () => undefined,
+    );
+  }
+}
+
+function hasDaemonFileMediaPart(message: Message): boolean {
+  return message.content.some((part) => daemonFileRefFromPart(part) !== undefined);
+}
+
+function degradedImage(path: string | undefined): ContentPart {
+  if (path === undefined) return unavailableMediaText('image');
+  return { type: 'text', text: buildMediaPathTag('image', path) };
+}
+
+function unavailableMediaText(kind: 'image' | 'video'): ContentPart {
+  return { type: 'text', text: kind === 'video' ? VIDEO_UNAVAILABLE_TEXT : IMAGE_UNAVAILABLE_TEXT };
+}
+
+function videoTag(path: string | undefined): ContentPart {
+  if (path === undefined) {
+    return { type: 'text', text: VIDEO_UNAVAILABLE_TEXT };
+  }
+  return { type: 'text', text: buildMediaPathTag('video', path) };
+}
+
+function msFileIdFromUrl(url: string): string | undefined {
+  if (!url.startsWith('ms://')) return undefined;
+  const id = url.slice('ms://'.length);
+  return id.length > 0 ? id : undefined;
+}
+
+function blobKey(cacheKey: string): string {
+  return createHash('sha256').update(cacheKey).digest('hex');
+}
+
+async function readStream(stream: NodeJS.ReadableStream, signal?: AbortSignal): Promise<Buffer> {
+  const onAbort = (): void => {
+    const reason = signal?.reason instanceof Error ? signal.reason : undefined;
+    (stream as NodeJS.ReadableStream & { destroy?(error?: Error): void }).destroy?.(reason);
+  };
+  signal?.addEventListener('abort', onAbort, { once: true });
+  const chunks: Buffer[] = [];
+  try {
+    signal?.throwIfAborted();
+    for await (const chunk of stream) {
+      signal?.throwIfAborted();
+      chunks.push(Buffer.from(chunk as string | Uint8Array));
+    }
+    return Buffer.concat(chunks);
+  } finally {
+    signal?.removeEventListener('abort', onAbort);
+  }
+}
+
+registerScopedService(
+  LifecycleScope.Agent,
+  IAgentMediaResolverService,
+  AgentMediaResolverService,
+  ScopeActivation.OnScopeCreated,
+  'media',
+);
diff --git a/packages/agent-core-v2/src/agent/media/promptMediaIntake.ts b/packages/agent-core-v2/src/agent/media/promptMediaIntake.ts
new file mode 100644
index 00000000000..b7dcad20352
--- /dev/null
+++ b/packages/agent-core-v2/src/agent/media/promptMediaIntake.ts
@@ -0,0 +1,66 @@
+/**
+ * `media` domain — prompt-intake materialization of daemon file references.
+ *
+ * Every daemon reference entering a session's context gets its bytes
+ * materialized at the session-canonical location through the session media
+ * store (`ISessionMediaStore`), whichever edge (REST prompt route, SDK
+ * prompt, steer, …) the message arrived through. The copy's extension is
+ * derived from the upload name, then MIME. The reference itself is never
+ * rewritten: it stays the bare `kimi-file://<fileId>` form, and the display
+ * path is derived from the store by file id at read time, so nothing
+ * machine-bound is persisted.
+ *
+ * Materialization is idempotent (an already-materialized copy whose size
+ * matches is kept) and best effort (an unreadable upload or a failed
+ * canonical write is skipped; the request-time resolver serves the reference
+ * from the daemon upload while it lives and degrades it afterwards). Reads
+ * the referenced bytes through the `file` domain (`IFileService`). Pure
+ * orchestration; no scoped service of its own.
+ */
+
+import type { IFileService } from '#/app/file/fileService';
+import { abortable } from '#/_base/utils/abort';
+import type { ContentPart } from '#/kosong/contract/message';
+
+import { daemonFileRefFromPart } from './mediaRef';
+import { ISessionMediaStore } from './sessionMediaStore';
+
+export interface PromptMediaIntakeDeps {
+  readonly files: IFileService;
+  readonly mediaStore: ISessionMediaStore;
+  readonly signal?: AbortSignal;
+}
+
+export async function materializePromptDaemonRefs(
+  content: readonly ContentPart[],
+  deps: PromptMediaIntakeDeps,
+): Promise<void> {
+  for (const part of content) {
+    deps.signal?.throwIfAborted();
+    const daemonPart = daemonFileRefFromPart(part);
+    if (daemonPart === undefined) continue;
+    await materializeRef(deps, daemonPart.ref.fileId).catch((_error: unknown) => {
+      deps.signal?.throwIfAborted();
+      return undefined;
+    });
+  }
+}
+
+async function materializeRef(deps: PromptMediaIntakeDeps, fileId: string): Promise<void> {
+  const file =
+    deps.signal === undefined
+      ? await deps.files.get(fileId)
+      : await abortable(deps.files.get(fileId), deps.signal);
+  try {
+    await deps.mediaStore.materialize({
+      fileId,
+      size: file.meta.size,
+      name: file.meta.name,
+      mimeType: file.meta.media_type,
+      stream: () => file.stream(),
+      signal: deps.signal,
+    });
+  } catch {
+    deps.signal?.throwIfAborted();
+  }
+}
diff --git a/packages/agent-core-v2/src/agent/media/sessionMediaStore.ts b/packages/agent-core-v2/src/agent/media/sessionMediaStore.ts
new file mode 100644
index 00000000000..9b03991af61
--- /dev/null
+++ b/packages/agent-core-v2/src/agent/media/sessionMediaStore.ts
@@ -0,0 +1,49 @@
+/**
+ * `media` domain — `ISessionMediaStore` contract.
+ *
+ * Owns the per-session canonical media blobs through the persistence byte
+ * store. It materializes daemon uploads, exposes a host path only when the
+ * selected backend has one, and opens canonical bytes with download metadata
+ * after a transient daemon upload has been released. Bound at Session scope.
+ */
+
+import { createDecorator, type ServiceIdentifier } from '#/_base/di/instantiation';
+
+export interface SessionMediaMaterializeInput {
+  readonly fileId: string;
+  readonly size: number;
+  readonly name: string;
+  readonly mimeType: string;
+  readonly stream: () => NodeJS.ReadableStream;
+  readonly signal?: AbortSignal;
+}
+
+export interface SessionMediaReadRange {
+  readonly start: number;
+  readonly end: number;
+}
+
+export interface SessionMediaFile {
+  readonly path?: string;
+  readonly name: string;
+  readonly mediaType: string;
+  readonly size: number;
+  readonly stream: (range?: SessionMediaReadRange) => AsyncIterable<Uint8Array>;
+}
+
+export interface ISessionMediaStore {
+  readonly _serviceBrand: undefined;
+
+  pathFor(fileId: string, ext: string): string | undefined;
+
+  resolveDisplayPath(fileId: string): Promise<string | undefined>;
+
+  read(fileId: string): Promise<{ readonly data: Uint8Array; readonly name: string } | undefined>;
+
+  open(fileId: string): Promise<SessionMediaFile | undefined>;
+
+  materialize(input: SessionMediaMaterializeInput): Promise<string | undefined>;
+}
+
+export const ISessionMediaStore: ServiceIdentifier<ISessionMediaStore> =
+  createDecorator<ISessionMediaStore>('sessionMediaStore');
diff --git a/packages/agent-core-v2/src/agent/media/sessionMediaStoreService.ts b/packages/agent-core-v2/src/agent/media/sessionMediaStoreService.ts
new file mode 100644
index 00000000000..0c5ee4c25de
--- /dev/null
+++ b/packages/agent-core-v2/src/agent/media/sessionMediaStoreService.ts
@@ -0,0 +1,168 @@
+/**
+ * `media` domain — `ISessionMediaStore` implementation.
+ *
+ * Materializes and reads session-canonical media through the `storage` byte
+ * backend, persists download metadata through the atomic-document store, and
+ * addresses both through `sessionContext`. Filesystem deployments expose an
+ * absolute host path for model readback; non-filesystem deployments retain
+ * canonical bytes without inventing one. Every entry point rejects ids that
+ * are not minted upload ids (`isFileId`) before using them as storage keys.
+ * By-id resolution lists the scope prefix and skips the backend's
+ * in-progress atomic-write temp siblings (`*.tmp.*`), so a lookup racing an
+ * unfinished materialize never returns the partial copy. Bound at Session
+ * scope.
+ */
+
+import { extname } from 'node:path';
+
+import { ScopeActivation, registerScopedService } from '#/_base/di/scope';
+import { LifecycleScope } from '#/app/scopes';
+import { isFileId } from '#/app/file/fileService';
+import { IAtomicDocumentStore } from '#/persistence/interface/atomicDocumentStore';
+import { IFileSystemStorageService } from '#/persistence/interface/storage';
+import { ISessionContext } from '#/session/sessionContext/sessionContext';
+
+import {
+  AUDIO_MIME_BY_SUFFIX,
+  IMAGE_MIME_BY_SUFFIX,
+  mediaExtensionForMime,
+  VIDEO_MIME_BY_SUFFIX,
+} from './mediaRef';
+import {
+  ISessionMediaStore,
+  type SessionMediaFile,
+  type SessionMediaMaterializeInput,
+} from './sessionMediaStore';
+
+interface SessionMediaMetadata {
+  readonly version: 1;
+  readonly key: string;
+  readonly name: string;
+  readonly mediaType: string;
+}
+
+export class SessionMediaStoreService implements ISessionMediaStore {
+  declare readonly _serviceBrand: undefined;
+  private readonly scope: string;
+
+  constructor(
+    @ISessionContext sessionContext: ISessionContext,
+    @IFileSystemStorageService private readonly storage: IFileSystemStorageService,
+    @IAtomicDocumentStore private readonly documents: IAtomicDocumentStore,
+  ) {
+    this.scope = sessionContext.scope('media');
+  }
+
+  pathFor(fileId: string, ext: string): string | undefined {
+    if (!isFileId(fileId)) return undefined;
+    return this.storage.pathFor(this.scope, this.keyFor(fileId, ext));
+  }
+
+  async resolveDisplayPath(fileId: string): Promise<string | undefined> {
+    if (!isFileId(fileId)) return undefined;
+    const key = await this.findKey(fileId);
+    if (key === undefined) return undefined;
+    return this.storage.pathFor(this.scope, key);
+  }
+
+  async read(
+    fileId: string,
+  ): Promise<{ readonly data: Uint8Array; readonly name: string } | undefined> {
+    if (!isFileId(fileId)) return undefined;
+    const key = await this.findKey(fileId);
+    if (key === undefined) return undefined;
+    const data = await this.storage.read(this.scope, key);
+    return data === undefined ? undefined : { data, name: key };
+  }
+
+  async open(fileId: string): Promise<SessionMediaFile | undefined> {
+    if (!isFileId(fileId)) return undefined;
+    const storedMetadata = await this.documents.get<unknown>(this.scope, this.metadataKey(fileId));
+    const metadata = this.isMetadataFor(storedMetadata, fileId) ? storedMetadata : undefined;
+    const key =
+      metadata !== undefined && (await this.storage.size(this.scope, metadata.key)) !== undefined
+        ? metadata.key
+        : await this.findKey(fileId);
+    if (key === undefined) return undefined;
+    const size = await this.storage.size(this.scope, key);
+    if (size === undefined) return undefined;
+    return {
+      path: this.storage.pathFor(this.scope, key),
+      name: metadata?.name ?? key,
+      mediaType: metadata?.mediaType ?? this.mediaTypeForKey(key),
+      size,
+      stream: (range) => this.storage.readStream(this.scope, key, range),
+    };
+  }
+
+  async materialize(input: SessionMediaMaterializeInput): Promise<string | undefined> {
+    if (!isFileId(input.fileId)) return undefined;
+    const ext = extname(input.name) || (mediaExtensionForMime(input.mimeType) ?? '.bin');
+    const key = this.keyFor(input.fileId, ext);
+    const existingSize = await this.storage.size(this.scope, key);
+    if (existingSize !== input.size) {
+      const source = input.stream() as NodeJS.ReadableStream & AsyncIterable<Uint8Array>;
+      await this.storage.writeStream(this.scope, key, source, {
+        atomic: true,
+        signal: input.signal,
+      });
+    }
+    await this.documents.set(this.scope, this.metadataKey(input.fileId), {
+      version: 1,
+      key,
+      name: input.name,
+      mediaType: input.mimeType,
+    });
+    return this.storage.pathFor(this.scope, key);
+  }
+
+  private keyFor(fileId: string, ext: string): string {
+    return `${fileId}${ext}`;
+  }
+
+  private metadataKey(fileId: string): string {
+    return `meta/${fileId}.json`;
+  }
+
+  private isMetadataFor(value: unknown, fileId: string): value is SessionMediaMetadata {
+    if (typeof value !== 'object' || value === null) return false;
+    const candidate = value as Partial<SessionMediaMetadata>;
+    return (
+      candidate.version === 1 &&
+      typeof candidate.key === 'string' &&
+      (candidate.key === fileId || candidate.key.startsWith(`${fileId}.`)) &&
+      !candidate.key.includes('/') &&
+      !candidate.key.includes('\\') &&
+      typeof candidate.name === 'string' &&
+      candidate.name.length > 0 &&
+      typeof candidate.mediaType === 'string' &&
+      candidate.mediaType.length > 0
+    );
+  }
+
+  private mediaTypeForKey(key: string): string {
+    const ext = extname(key).toLowerCase();
+    return (
+      IMAGE_MIME_BY_SUFFIX[ext] ??
+      VIDEO_MIME_BY_SUFFIX[ext] ??
+      AUDIO_MIME_BY_SUFFIX[ext] ??
+      'application/octet-stream'
+    );
+  }
+
+  private async findKey(fileId: string): Promise<string | undefined> {
+    const keys = await this.storage.list(this.scope, fileId);
+    return keys.find(
+      (key) =>
+        key === fileId || (key.startsWith(`${fileId}.`) && !key.includes('.tmp.')),
+    );
+  }
+}
+
+registerScopedService(
+  LifecycleScope.Session,
+  ISessionMediaStore,
+  SessionMediaStoreService,
+  ScopeActivation.OnScopeCreated,
+  'media',
+);
diff --git a/packages/agent-core-v2/src/agent/media/videoResolver.ts b/packages/agent-core-v2/src/agent/media/videoResolver.ts
index efbdefb8e83..f140f98bde4 100644
--- a/packages/agent-core-v2/src/agent/media/videoResolver.ts
+++ b/packages/agent-core-v2/src/agent/media/videoResolver.ts
@@ -1,27 +1,10 @@
 /**
- * `media` domain — request-time video reference resolver contract.
+ * `media` domain — deprecated alias of the request-time media resolver
+ * contract (`mediaResolver`).
  *
- * Rewrites the `kimi-file://` video references a prompt carries in the
- * projected wire messages into a provider-acceptable form (an uploaded
- * `ms://` reference, an inline base64 `data:` part, or a `<video path>` text
- * tag) right before the messages reach the provider — so a `kimi-file://` url
- * never touches the wire. Bound at Agent scope.
+ * Kept under the historical name so existing call sites read unchanged. New
+ * code should import `IAgentMediaResolverService` from `mediaResolver`
+ * directly.
  */
 
-import { createDecorator } from '#/_base/di/instantiation';
-import type { Message } from '#/kosong/contract/message';
-import type { ModelRequester } from '#/kosong/model/modelRequester';
-
-export interface IAgentVideoResolverService {
-  readonly _serviceBrand: undefined;
-
-  resolve(
-    messages: readonly Message[],
-    requester: ModelRequester,
-    signal?: AbortSignal,
-  ): Promise<readonly Message[]>;
-}
-
-export const IAgentVideoResolverService = createDecorator<IAgentVideoResolverService>(
-  'agentVideoResolverService',
-);
+export { IAgentMediaResolverService as IAgentVideoResolverService } from './mediaResolver';
diff --git a/packages/agent-core-v2/src/agent/media/videoResolverService.ts b/packages/agent-core-v2/src/agent/media/videoResolverService.ts
index 1aafe624d5f..dc63a96ba18 100644
--- a/packages/agent-core-v2/src/agent/media/videoResolverService.ts
+++ b/packages/agent-core-v2/src/agent/media/videoResolverService.ts
@@ -1,245 +1,12 @@
 /**
- * `media` domain — `IAgentVideoResolverService` implementation.
+ * `media` domain — deprecated alias of the request-time media resolver
+ * implementation (`mediaResolverService`).
  *
- * Resolves each `kimi-file://` video reference in the projected wire messages
- * to a provider-acceptable part right before the request leaves for the wire.
- * Reads the uploaded bytes through the `file` domain (`IFileService`), uploads
- * them through the bound model's `ModelRequester.uploadVideo` (wrapped for
- * `video_upload` telemetry through `createVideoUploader`), and persists the
- * `(file, provider) → llmFileId` mapping through the `blobStore`
- * access-pattern store so the upload happens once across a turn's steps,
- * retries, and media-recovery reprojections. Falls back to an inline base64
- * `video_url` (protocols that carry it) or a `<video path>` text tag (the
- * model then opens the edge-materialized copy with `ReadMediaFile`); auth
- * failures surface so they drive credential refresh instead of masking a bad
- * token, and an upload interrupted by the step's aborted signal re-throws —
- * shape-agnostic, since abort rejections vary by provider — so cancellation
- * ends the request instead of memoizing a degraded fallback for the rest of
- * the agent's lifetime. Resolution outcomes are memoized per (file, provider)
- * for step/retry stability — except a transient upload failure, which
- * degrades only the current request to the tag form so a later step retries
- * the upload instead of freezing the fallback. The plain-data state
- * (`resolved`) is registered into `agentState` (`IAgentStateService`) and
- * read/written through it. Bound at Agent scope.
+ * Kept under the historical names so existing call sites read unchanged. New
+ * code should import `AgentMediaResolverService` / `mediaResolvedKey` from
+ * `mediaResolverService` directly. Only the class is re-exported here:
+ * re-exporting `mediaResolvedKey` too would make the package root's
+ * `export *` of both modules ambiguous and silently drop the name.
  */
 
-import { createHash } from 'node:crypto';
-import { LifecycleScope } from '#/app/scopes';
-import { ScopeActivation, registerScopedService } from '#/_base/di/scope';
-import { defineState } from '#/_base/state/stateRegistry';
-import { IAgentStateService } from '#/agent/state/agentState';
-import { IFileService } from '#/app/file/fileService';
-import { ITelemetryService } from '#/app/telemetry/telemetry';
-import type { ContentPart, Message } from '#/kosong/contract/message';
-import type { ModelRequester } from '#/kosong/model/modelRequester';
-import { IBlobStore } from '#/persistence/interface/blobStore';
-
-import { detectFileType, MEDIA_SNIFF_BYTES } from './file-type';
-import { type KimiFileRef, isKimiFileUrl, parseKimiFileUrl } from './kimiFileUrl';
-import { createVideoUploader } from './registerMediaTools';
-import {
-  inlineVideoPart,
-  inlineVideoSupportedForProtocol,
-  isVideoUploadAuthError,
-  isVideoUploadUnsupportedError,
-} from './videoUpload';
-import { IAgentVideoResolverService } from './videoResolver';
-
-const CACHE_SCOPE = 'video-upload-cache';
-const PROVIDER_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
-const VIDEO_UNAVAILABLE_TEXT =
-  '[video omitted: the uploaded file is no longer available]';
-
-const textEncoder = new TextEncoder();
-const textDecoder = new TextDecoder();
-
-export const mediaResolvedKey = defineState<Map<string, ContentPart>>(
-  'media.resolved',
-  () => new Map(),
-);
-
-export class AgentVideoResolverService implements IAgentVideoResolverService {
-  declare readonly _serviceBrand: undefined;
-
-  constructor(
-    @IFileService private readonly files: IFileService,
-    @IBlobStore private readonly blobs: IBlobStore,
-    @ITelemetryService private readonly telemetry: ITelemetryService,
-    @IAgentStateService private readonly states: IAgentStateService,
-  ) {
-    this.states.register(mediaResolvedKey);
-  }
-
-  private get resolved(): Map<string, ContentPart> {
-    return this.states.get(mediaResolvedKey);
-  }
-
-  async resolve(
-    messages: readonly Message[],
-    requester: ModelRequester,
-    signal?: AbortSignal,
-  ): Promise<readonly Message[]> {
-    if (!messages.some(hasKimiFileVideoPart)) return messages;
-
-    let changed = false;
-    const out: Message[] = [];
-    for (const message of messages) {
-      if (!hasKimiFileVideoPart(message)) {
-        out.push(message);
-        continue;
-      }
-      const content: ContentPart[] = [];
-      for (const part of message.content) {
-        const ref =
-          part.type === 'video_url' ? parseKimiFileUrl(part.videoUrl.url) : undefined;
-        content.push(ref === undefined ? part : await this.resolvePart(ref, requester, signal));
-      }
-      out.push({ ...message, content });
-      changed = true;
-    }
-    return changed ? out : messages;
-  }
-
-  private async resolvePart(
-    ref: KimiFileRef,
-    requester: ModelRequester,
-    signal: AbortSignal | undefined,
-  ): Promise<ContentPart> {
-    const model = requester.model;
-    const providerKey = model.providerType ?? model.protocol;
-    const cacheKey = `${ref.fileId}\0${providerKey}`;
-
-    const memoed = this.resolved.get(cacheKey);
-    if (memoed !== undefined) return memoed;
-
-    const { part, memoize } = await this.resolveUncached(ref, requester, cacheKey, signal);
-    if (memoize) this.resolved.set(cacheKey, part);
-    return part;
-  }
-
-  private async resolveUncached(
-    ref: KimiFileRef,
-    requester: ModelRequester,
-    cacheKey: string,
-    signal: AbortSignal | undefined,
-  ): Promise<{ part: ContentPart; memoize: boolean }> {
-    const cachedLlmFileId = await this.readCachedUpload(cacheKey);
-    if (cachedLlmFileId !== undefined) {
-      return {
-        part: { type: 'video_url', videoUrl: { url: `ms://${cachedLlmFileId}`, id: cachedLlmFileId } },
-        memoize: true,
-      };
-    }
-
-    let bytes: Buffer;
-    let filename: string;
-    try {
-      const file = await this.files.get(ref.fileId);
-      bytes = await readStream(file.stream());
-      filename = file.meta.name;
-    } catch {
-      return { part: tag(ref), memoize: true };
-    }
-
-    const fileType = detectFileType(filename, bytes.subarray(0, MEDIA_SNIFF_BYTES), 'media');
-    if (fileType.kind !== 'video') return { part: tag(ref), memoize: true };
-    const mimeType = fileType.mimeType;
-
-    const model = requester.model;
-    if (!model.capabilities.video_in) return { part: tag(ref), memoize: true };
-    const inlineSupported = inlineVideoSupportedForProtocol(model.protocol);
-
-    const uploader = createVideoUploader(requester, {
-      client: this.telemetry,
-      props: {
-        model: model.name,
-        provider_type: model.providerType ?? model.protocol,
-        protocol: model.protocol,
-      },
-    });
-    if (uploader === undefined) {
-      return {
-        part: inlineSupported ? inlineVideoPart(bytes, mimeType) : tag(ref),
-        memoize: true,
-      };
-    }
-
-    try {
-      const uploaded = await uploader({ data: bytes, mimeType, filename }, { signal });
-      const llmFileId = uploaded.videoUrl.id ?? msFileIdFromUrl(uploaded.videoUrl.url);
-      if (llmFileId !== undefined) await this.writeCachedUpload(cacheKey, llmFileId);
-      return { part: uploaded, memoize: true };
-    } catch (error) {
-      if (signal?.aborted) throw error;
-      if (isVideoUploadAuthError(error)) throw error;
-      if (isVideoUploadUnsupportedError(error)) {
-        return {
-          part: inlineSupported ? inlineVideoPart(bytes, mimeType) : tag(ref),
-          memoize: true,
-        };
-      }
-      return { part: tag(ref), memoize: false };
-    }
-  }
-
-  private async readCachedUpload(cacheKey: string): Promise<string | undefined> {
-    const data = await this.blobs.get(CACHE_SCOPE, blobKey(cacheKey)).catch(() => undefined);
-    if (data === undefined) return undefined;
-    const llmFileId = textDecoder.decode(data);
-    return PROVIDER_ID_RE.test(llmFileId) ? llmFileId : undefined;
-  }
-
-  private async writeCachedUpload(cacheKey: string, llmFileId: string): Promise<void> {
-    if (!PROVIDER_ID_RE.test(llmFileId)) return;
-    await this.blobs.put(CACHE_SCOPE, blobKey(cacheKey), textEncoder.encode(llmFileId)).catch(
-      () => undefined,
-    );
-  }
-}
-
-function hasKimiFileVideoPart(message: Message): boolean {
-  return message.content.some(
-    (part) => part.type === 'video_url' && isKimiFileUrl(part.videoUrl.url),
-  );
-}
-
-function tag(ref: KimiFileRef): ContentPart {
-  if (ref.path === undefined || ref.path.length === 0) {
-    return { type: 'text', text: VIDEO_UNAVAILABLE_TEXT };
-  }
-  return { type: 'text', text: `<video path="${escapeAttribute(ref.path)}"></video>` };
-}
-
-function msFileIdFromUrl(url: string): string | undefined {
-  if (!url.startsWith('ms://')) return undefined;
-  const id = url.slice('ms://'.length);
-  return id.length > 0 ? id : undefined;
-}
-
-function blobKey(cacheKey: string): string {
-  return createHash('sha256').update(cacheKey).digest('hex');
-}
-
-async function readStream(stream: NodeJS.ReadableStream): Promise<Buffer> {
-  const chunks: Buffer[] = [];
-  for await (const chunk of stream) {
-    chunks.push(Buffer.from(chunk as string | Uint8Array));
-  }
-  return Buffer.concat(chunks);
-}
-
-function escapeAttribute(value: string): string {
-  return value
-    .replaceAll('&', '&amp;')
-    .replaceAll('"', '&quot;')
-    .replaceAll('<', '&lt;')
-    .replaceAll('>', '&gt;');
-}
-
-registerScopedService(
-  LifecycleScope.Agent,
-  IAgentVideoResolverService,
-  AgentVideoResolverService,
-  ScopeActivation.OnScopeCreated,
-  'media',
-);
+export { AgentMediaResolverService as AgentVideoResolverService } from './mediaResolverService';
diff --git a/packages/agent-core-v2/src/agent/prompt/errors.ts b/packages/agent-core-v2/src/agent/prompt/errors.ts
index a3e6b14360f..9565cef52cc 100644
--- a/packages/agent-core-v2/src/agent/prompt/errors.ts
+++ b/packages/agent-core-v2/src/agent/prompt/errors.ts
@@ -9,6 +9,7 @@ export const PromptErrors = {
     REQUEST_INVALID: 'request.invalid',
     REQUEST_WORK_DIR_REQUIRED: 'request.work_dir_required',
     REQUEST_PROMPT_INPUT_EMPTY: 'request.prompt_input_empty',
+    PROMPT_ID_CONFLICT: 'prompt.id_conflict',
     PROMPT_NOT_FOUND: 'prompt.not_found',
     PROMPT_ALREADY_COMPLETED: 'prompt.already_completed',
     SESSION_BUSY: 'session.busy',
diff --git a/packages/agent-core-v2/src/agent/prompt/prompt.ts b/packages/agent-core-v2/src/agent/prompt/prompt.ts
index 73f1b49e4dc..b82d0964282 100644
--- a/packages/agent-core-v2/src/agent/prompt/prompt.ts
+++ b/packages/agent-core-v2/src/agent/prompt/prompt.ts
@@ -1,4 +1,5 @@
 import { createDecorator } from '#/_base/di/instantiation';
+import type { IDisposable } from '#/_base/di/lifecycle';
 import type { ContextMessage } from '#/agent/contextMemory/types';
 import type { Turn, TurnResult } from '#/agent/loop/loop';
 import type { ContentPart } from '#/kosong/contract/message';
@@ -50,6 +51,18 @@ export interface PromptQueueSnapshot {
 
 export interface PromptPayload {
   readonly input: readonly ContentPart[];
+  /**
+   * Client-managed session tool denylist (full-replace semantics), applied
+   * before the prompt is enqueued. Omit to keep the current value; `[]`
+   * clears the client portion.
+   */
+  readonly disabledTools?: readonly string[];
+  /**
+   * Client-chosen prompt record id, echoed on the consuming turn's
+   * `turn.started` (`promptId`). A duplicate id rejects the submission before
+   * any session state is touched.
+   */
+  readonly promptId?: string;
 }
 
 export interface SteerPayload {
@@ -60,6 +73,21 @@ export interface PromptLaunchResult {
   readonly turn_id: number;
 }
 
+export interface PromptReservation extends IDisposable {
+  readonly id: string;
+  submit(message: ContextMessage): Promise<PromptHandle>;
+}
+
+export const promptAdmission = Symbol('promptAdmission');
+
+type PromptAdmissionHook = (promptId?: string) => PromptReservation;
+
+export function reservePrompt(service: IAgentPromptService, promptId?: string): PromptReservation {
+  return (service as IAgentPromptService & { [promptAdmission]: PromptAdmissionHook })[
+    promptAdmission
+  ](promptId);
+}
+
 export interface IAgentPromptService {
   readonly _serviceBrand: undefined;
   enqueue(input: PromptInput): Promise<PromptHandle>;
@@ -68,6 +96,7 @@ export interface IAgentPromptService {
   list(): PromptQueueSnapshot;
   steer(promptIds: readonly string[]): Promise<readonly PromptHandle[]>;
   abort(promptId: string, reason?: Error): boolean;
+  drain(reason?: Error): Promise<void>;
   inject(message: ContextMessage): Promise<Turn | undefined>;
   retry(): Promise<Turn | undefined>;
   clear(): void;
diff --git a/packages/agent-core-v2/src/agent/prompt/promptMetadataText.ts b/packages/agent-core-v2/src/agent/prompt/promptMetadataText.ts
index 631c7c5d340..cd3c21bc7c4 100644
--- a/packages/agent-core-v2/src/agent/prompt/promptMetadataText.ts
+++ b/packages/agent-core-v2/src/agent/prompt/promptMetadataText.ts
@@ -3,10 +3,13 @@
  *
  * Shared by prompt submission and undo projection so `lastPrompt` uses one
  * normalization, redaction, and length limit, with image captions supplied by
- * the `media` domain.
+ * the `media` domain. A standalone `<media path="…">` tag is machine markup
+ * (the model-facing degrade form) and never reaches titles / lastPrompt, so
+ * a materialization path cannot leak into them.
  */
 
 import type { ContentPart } from '#/kosong/contract/message';
+import { matchSingleMediaPathTag } from '#/agent/media/mediaRef';
 import { extractImageCompressionCaptions } from '#/agent/media/image-compress';
 
 const MAX_TITLE_LENGTH = 200;
@@ -51,6 +54,7 @@ export function promptMetadataTextFromText(text: string): string | undefined {
 function promptPartText(part: ContentPart): string | undefined {
   switch (part.type) {
     case 'text': {
+      if (matchSingleMediaPathTag(part.text) !== undefined) return undefined;
       const { text } = extractImageCompressionCaptions(part.text);
       return text.trim().length === 0 ? undefined : text;
     }
diff --git a/packages/agent-core-v2/src/agent/prompt/promptOps.ts b/packages/agent-core-v2/src/agent/prompt/promptOps.ts
new file mode 100644
index 00000000000..025e62ac46a
--- /dev/null
+++ b/packages/agent-core-v2/src/agent/prompt/promptOps.ts
@@ -0,0 +1,29 @@
+/**
+ * `prompt` domain — persists the accepted prompt identities used for
+ * same-agent uniqueness checks.
+ */
+
+import { z } from 'zod';
+
+import { defineModel } from '#/wire/model';
+
+export type PromptAdmissionModelState = Map<string, true>;
+
+export const PromptAdmissionModel = defineModel<PromptAdmissionModelState>(
+  'promptAdmission',
+  () => new Map(),
+);
+
+declare module '#/wire/types' {
+  interface PersistedOpMap {
+    'prompt.accepted': typeof promptAccepted;
+  }
+}
+
+export const promptAccepted = PromptAdmissionModel.defineOp('prompt.accepted', {
+  schema: z.object({ promptId: z.string().min(1) }),
+  apply: (state, { promptId }) => {
+    if (state.has(promptId)) return state;
+    return new Map([...state, [promptId, true] as const]);
+  },
+});
diff --git a/packages/agent-core-v2/src/agent/prompt/promptService.ts b/packages/agent-core-v2/src/agent/prompt/promptService.ts
index f41ded27c77..30ee8413454 100644
--- a/packages/agent-core-v2/src/agent/prompt/promptService.ts
+++ b/packages/agent-core-v2/src/agent/prompt/promptService.ts
@@ -4,13 +4,19 @@
  * Assigns prompt and message identities, serializes user prompts through an
  * active slot and FIFO, converts selected pending prompts into active-turn
  * steers, settles lifecycle handles, and keeps system input outside the prompt
- * resource model. `submit` / `submitSteer` are the wire-facing user entry
+ * resource model. Daemon file references in submissions are materialized
+ * through the `media` domain's intake (`materializePromptDaemonRefs` — copy
+ * the bytes into the session media store; the reference stays the bare
+ * `kimi-file://<fileId>` form); the media store owns the canonical
+ * persistence. `submit` /
+ * `submitSteer` are the wire-facing user entry
  * points: they track `input_steer` through `telemetry`, persist the derived
  * title/lastPrompt through `sessionMetadata` for the main agent only
  * (publishing the live update through `event`), enqueue, and settle
- * `{turn_id}` from the launch handle. Session tool gating is an edge
- * concern: callers apply `IAgentToolPolicyService.setSessionDisabledTools`
- * before submitting, the way kap-server's prompt route composes it.
+ * `{turn_id}` from the launch handle. A `submit` payload may carry a
+ * client-chosen `promptId` (admitted through the reservation so a duplicate
+ * rejects before any session state changes) and a client-managed session
+ * tool denylist, applied through `toolPolicy` before the enqueue.
  * The pure-data `launching` flag is registered into
  * `agentState` (`IAgentStateService`) and read/written through it; the
  * `active` / `pending` / `steered` records stay plain fields because their
@@ -20,10 +26,14 @@
  */
 
 import { IInstantiationService } from '#/_base/di/instantiation';
+import { Disposable } from '#/_base/di/lifecycle';
 import { LifecycleScope } from '#/app/scopes';
 import { ScopeActivation, registerScopedService } from '#/_base/di/scope';
 import { defineState } from '#/_base/state/stateRegistry';
 import { extractImageCompressionCaptions } from '#/agent/media/image-compress';
+import { daemonFileRefFromPart } from '#/agent/media/mediaRef';
+import { materializePromptDaemonRefs } from '#/agent/media/promptMediaIntake';
+import { ISessionMediaStore } from '#/agent/media/sessionMediaStore';
 import { userCancellationReason } from '#/_base/utils/abort';
 import { IAgentContextMemoryService } from '#/agent/contextMemory/contextMemory';
 import { newMessageId } from '#/agent/contextMemory/messageId';
@@ -36,7 +46,10 @@ import { IAgentSystemReminderService } from '#/agent/systemReminder/systemRemind
 import type { ExecutableToolResult } from '#/tool/toolContract';
 import type { ToolDidExecuteContext } from '#/agent/toolExecutor/toolHooks';
 import { IAgentToolExecutorService } from '#/agent/toolExecutor/toolExecutor';
+import { IAgentToolPolicyService } from '#/agent/toolPolicy/toolPolicy';
+import { ProfileError } from '#/agent/profile/profile';
 import type { ContentPart } from '#/kosong/contract/message';
+import { IFileService } from '#/app/file/fileService';
 import { IEventBus } from '#/app/event/eventBus';
 import { IEventService } from '#/app/event/event';
 import { ErrorCodes, Error2, isError2 } from '#/errors';
@@ -51,11 +64,13 @@ import { applyPromptMetadataUpdate } from '#/session/sessionMetadata/promptMetad
 
 import {
   IAgentPromptService,
+  promptAdmission,
   type PromptCompletion,
   type PromptHandle,
   type PromptInput,
   type PromptLaunchResult,
   type PromptPayload,
+  type PromptReservation,
   type PromptQueueSnapshot,
   type PromptSnapshot,
   type PromptState,
@@ -63,6 +78,7 @@ import {
   type SteerPayload,
 } from './prompt';
 import { promptMetadataTextFromContentParts } from './promptMetadataText';
+import { promptAccepted, PromptAdmissionModel } from './promptOps';
 import { PromptStepRequest, RetryStepRequest, SteerStepRequest } from './promptStepRequests';
 
 declare module '#/app/event/eventBus' {
@@ -77,18 +93,31 @@ declare module '#/app/event/eventBus' {
 interface Deferred<T> { readonly promise: Promise<T>; resolve(value: T): void; reject(reason: unknown): void }
 interface Record extends PromptSnapshot {
   state: PromptState;
+  message: ContextMessage;
   readonly launchedDeferred: Deferred<Turn | undefined>;
   readonly completionDeferred: Deferred<PromptCompletion>;
+  readonly intakeController: AbortController;
+  intake: Promise<void>;
   handle: PromptHandle;
 }
 
+interface SteeringReservation {
+  readonly item: Record;
+  readonly active: Record & { turn: Turn };
+}
+
 export const promptLaunchingKey = defineState<boolean>('prompt.launching', () => false);
 
-export class AgentPromptService implements IAgentPromptService {
+export class AgentPromptService extends Disposable implements IAgentPromptService {
   declare readonly _serviceBrand: undefined;
   private active: (Record & { turn: Turn }) | undefined;
   private readonly pending: Record[] = [];
+  private launchingItem: Record | undefined;
   private readonly steered = new Map<string, Record[]>();
+  private readonly steering = new Map<string, SteeringReservation>();
+  private readonly reservedPromptIds = new Set<string>();
+  private readonly intakes = new Set<Promise<void>>();
+  private readonly intakeControllers = new Set<AbortController>();
   private fullCompactionService: IAgentFullCompactionService | undefined;
   readonly hooks = { onBeforeSubmitPrompt: new OrderedHookSlot<PromptSubmitContext>() };
 
@@ -101,17 +130,23 @@ export class AgentPromptService implements IAgentPromptService {
     @IWireService private readonly wire: IWireService,
     @IEventBus private readonly eventBus: IEventBus,
     @IAgentStateService private readonly states: IAgentStateService,
+    @IFileService private readonly files: IFileService,
+    @ISessionMediaStore private readonly mediaStore: ISessionMediaStore,
     @ITelemetryService private readonly telemetry: ITelemetryService,
     @ISessionMetadata private readonly metadata: ISessionMetadata,
     @IEventService private readonly eventService: IEventService,
     @ISessionContext private readonly sessionContext: ISessionContext,
     @IAgentScopeContext private readonly scopeContext: IAgentScopeContext,
+    @IAgentToolPolicyService private readonly toolPolicy: IAgentToolPolicyService,
   ) {
+    super();
     this.states.register(promptLaunchingKey);
-    toolExecutor.hooks.onDidExecuteTool.register('prompt-service-delivery', async (ctx, next) => {
-      await this.deliverToolResult(ctx);
-      await next();
-    });
+    this._register(
+      toolExecutor.hooks.onDidExecuteTool.register('prompt-service-delivery', async (ctx, next) => {
+        await this.deliverToolResult(ctx);
+        await next();
+      }),
+    );
   }
 
   private get launching(): boolean {
@@ -122,16 +157,74 @@ export class AgentPromptService implements IAgentPromptService {
     this.states.set(promptLaunchingKey, value);
   }
 
+  private mediaIntakeOf(record: Record): Promise<void> {
+    const intake = materializePromptDaemonRefs(record.message.content, {
+      files: this.files,
+      mediaStore: this.mediaStore,
+      signal: record.intakeController.signal,
+    });
+    let tracked!: Promise<void>;
+    tracked = intake
+      .catch(() => undefined)
+      .then(() => {
+        this.intakes.delete(tracked);
+        this.intakeControllers.delete(record.intakeController);
+      });
+    this.intakes.add(tracked);
+    this.intakeControllers.add(record.intakeController);
+    return tracked;
+  }
+
+  [promptAdmission](promptId?: string): PromptReservation {
+    if (promptId !== undefined && promptId.length === 0) {
+      throw new Error2(ErrorCodes.REQUEST_INVALID, 'prompt_id must not be empty');
+    }
+    let id = promptId ?? newMessageId();
+    const accepted = this.wire.getModel(PromptAdmissionModel);
+    while (accepted.has(id) || this.reservedPromptIds.has(id)) {
+      if (promptId !== undefined) throw promptIdConflict(id);
+      id = newMessageId();
+    }
+    this.reservedPromptIds.add(id);
+    let submitted = false;
+    return {
+      id,
+      submit: (message) => {
+        if (submitted || !this.reservedPromptIds.has(id)) {
+          throw new Error2(ErrorCodes.REQUEST_INVALID, 'prompt reservation is no longer available');
+        }
+        submitted = true;
+        this.reservedPromptIds.delete(id);
+        this.wire.dispatch(promptAccepted({ promptId: id }));
+        return this.enqueueAccepted(id, message);
+      },
+      dispose: () => {
+        if (submitted) return;
+        submitted = true;
+        this.reservedPromptIds.delete(id);
+      },
+    };
+  }
+
   async enqueue(input: PromptInput): Promise<PromptHandle> {
-    const id = input.id ?? input.message.id ?? newMessageId();
-    const message = { ...input.message, id };
+    const reservation = this[promptAdmission](input.id ?? input.message.id);
+    try {
+      return await reservation.submit(input.message);
+    } finally {
+      reservation.dispose();
+    }
+  }
+
+  private async enqueueAccepted(id: string, inputMessage: ContextMessage): Promise<PromptHandle> {
+    const message = { ...inputMessage, id };
     const launchedDeferred = deferred<Turn | undefined>();
     const completionDeferred = deferred<PromptCompletion>();
-    const record = {} as Record;
-    Object.assign(record, {
+    const record = {
       id, userMessageId: id, createdAt: new Date().toISOString(), state: 'pending', message,
-      launchedDeferred, completionDeferred,
-    });
+      launchedDeferred, completionDeferred, intakeController: new AbortController(),
+    } as Record;
+    const requiresMediaIntake = message.content.some((part) => daemonFileRefFromPart(part) !== undefined);
+    record.intake = this.mediaIntakeOf(record);
     record.handle = {
       get id() { return record.id; }, get userMessageId() { return record.userMessageId; },
       get createdAt() { return record.createdAt; }, get state() { return record.state; },
@@ -145,6 +238,10 @@ export class AgentPromptService implements IAgentPromptService {
         return record.handle;
       }
       void this.startNext();
+      if (requiresMediaIntake) {
+        this.publishQueued(record);
+        return record.handle;
+      }
       await Promise.race([record.launchedDeferred.promise, record.completionDeferred.promise]);
     } else {
       this.publishQueued(record);
@@ -153,16 +250,33 @@ export class AgentPromptService implements IAgentPromptService {
   }
 
   async submit(payload: PromptPayload): Promise<PromptLaunchResult | undefined> {
-    await this.updatePromptMetadata(promptMetadataTextFromContentParts(payload.input));
-    const handle = await this.enqueue({ message: {
-      role: 'user',
-      content: [...payload.input],
-      toolCalls: [],
-      origin: { kind: 'user' },
-    } });
-    if (handle.state === 'pending') return undefined;
-    const turn = await handle.launched;
-    return turn === undefined ? undefined : { turn_id: turn.id };
+    // Reserve the (possibly client-chosen) id first: a duplicate promptId must
+    // reject before the denylist or the session metadata changes.
+    const reservation = this[promptAdmission](payload.promptId);
+    try {
+      if (payload.disabledTools !== undefined) {
+        try {
+          await this.toolPolicy.setSessionDisabledTools(payload.disabledTools);
+        } catch (error) {
+          if (error instanceof ProfileError) {
+            throw new Error2(ErrorCodes.REQUEST_INVALID, error.message);
+          }
+          throw error;
+        }
+      }
+      await this.updatePromptMetadata(promptMetadataTextFromContentParts(payload.input));
+      const handle = await reservation.submit({
+        role: 'user',
+        content: [...payload.input],
+        toolCalls: [],
+        origin: { kind: 'user' },
+      });
+      if (handle.state === 'pending') return undefined;
+      const turn = await handle.launched;
+      return turn === undefined ? undefined : { turn_id: turn.id };
+    } finally {
+      reservation.dispose();
+    }
   }
 
   async submitSteer(payload: SteerPayload): Promise<PromptLaunchResult | undefined> {
@@ -211,44 +325,102 @@ export class AgentPromptService implements IAgentPromptService {
   }
 
   list(): PromptQueueSnapshot {
-    return { active: this.active === undefined ? undefined : snapshot(this.active), pending: this.pending.map(snapshot) };
+    // startNext shifts the launching record out of `pending` before its media
+    // intake settles; keep reporting it as queued during that window so the
+    // snapshot never loses an accepted (and abortable) submission between the
+    // `prompt.queued` event and `turn.started`.
+    const pending = this.pending.map(snapshot);
+    if (this.launchingItem !== undefined) pending.unshift(snapshot(this.launchingItem));
+    return { active: this.active === undefined ? undefined : snapshot(this.active), pending };
   }
 
   async steer(promptIds: readonly string[]): Promise<readonly PromptHandle[]> {
     if (promptIds.length === 0) throw new Error2(ErrorCodes.REQUEST_INVALID, 'prompt_ids must not be empty');
-    if (this.active === undefined) throw new Error2(ErrorCodes.PROMPT_NOT_FOUND, 'no active prompt to steer into');
+    const active = this.active;
+    if (active === undefined) throw new Error2(ErrorCodes.PROMPT_NOT_FOUND, 'no active prompt to steer into');
     const ids = new Set(promptIds);
     if (ids.size !== promptIds.length || this.pending.filter((item) => ids.has(item.id)).length !== ids.size) {
       throw new Error2(ErrorCodes.PROMPT_NOT_FOUND, 'one or more prompts are not pending');
     }
     const selected = this.pending.filter((item) => ids.has(item.id));
-    for (const item of selected) this.pending.splice(this.pending.indexOf(item), 1);
-    const message: ContextMessage = {
-      role: 'user', content: selected.flatMap((item) => item.message.content), toolCalls: [], origin: USER_PROMPT_ORIGIN,
-    };
-    const { message: rerouted, captions } = this.extractCompressionCaptions(message);
-    const request = new SteerStepRequest(rerouted, captions, this.reminders, (materialized) => {
-      this.wire.dispatch(steerTurn({ input: materialized.content, origin: materialized.origin ?? USER_PROMPT_ORIGIN }));
-    }, () => {});
-    const turn = (await this.loop.enqueue(request).assigned).turn;
-    if (turn === undefined) throw new Error2(ErrorCodes.PROMPT_NOT_FOUND, 'no active turn to steer into');
-    for (const item of selected) { item.state = 'steered'; item.launchedDeferred.resolve(turn); }
-    this.steered.set(this.active.id, [...(this.steered.get(this.active.id) ?? []), ...selected]);
-    this.eventBus.publish({ type: 'prompt.steered', activePromptId: this.active.id, promptIds: selected.map((x) => x.id), content: rerouted.content as ContentPart[], steeredAt: new Date().toISOString() });
-    return selected.map((item) => item.handle);
+    for (const item of selected) {
+      this.pending.splice(this.pending.indexOf(item), 1);
+      this.steering.set(item.id, { item, active });
+    }
+    try {
+      await Promise.all(selected.map((item) => item.intake));
+      if (!this.reservationsMatch(selected, active)) {
+        throw new Error2(ErrorCodes.PROMPT_NOT_FOUND, 'prompt steer was cancelled');
+      }
+      if (this.active !== active) {
+        this.cancelSteering(selected);
+        throw new Error2(ErrorCodes.PROMPT_NOT_FOUND, 'active prompt finished before steer');
+      }
+      const message: ContextMessage = {
+        role: 'user', content: selected.flatMap((item) => item.message.content), toolCalls: [], origin: USER_PROMPT_ORIGIN,
+      };
+      const { message: rerouted, captions } = this.extractCompressionCaptions(message);
+      const request = new SteerStepRequest(rerouted, captions, this.reminders, (materialized) => {
+        this.wire.dispatch(steerTurn({ input: materialized.content, origin: materialized.origin ?? USER_PROMPT_ORIGIN }));
+      }, () => {});
+      const receipt = this.loop.enqueue(request);
+      const turn = (await receipt.assigned).turn;
+      const cancelledMidFlight = !this.reservationsMatch(selected, active);
+      if (turn === undefined || this.active !== active || turn.id !== active.turn.id || cancelledMidFlight) {
+        // The steer request is turn-agnostic (`turnScoped: false`), so without
+        // an explicit abort it could still materialize its content into
+        // whichever turn pops it next. An abort that landed inside the
+        // `assigned` window has already settled the record as cancelled —
+        // keep that terminal state instead of flipping it to 'steered'.
+        receipt.abort(userCancellationReason());
+        this.cancelSteering(selected);
+        throw new Error2(
+          ErrorCodes.PROMPT_NOT_FOUND,
+          cancelledMidFlight ? 'prompt steer was cancelled' : 'no active turn to steer into',
+        );
+      }
+      for (const item of selected) {
+        this.steering.delete(item.id);
+        item.state = 'steered';
+        item.launchedDeferred.resolve(turn);
+      }
+      this.steered.set(active.id, [...(this.steered.get(active.id) ?? []), ...selected]);
+      this.eventBus.publish({ type: 'prompt.steered', activePromptId: active.id, promptIds: selected.map((x) => x.id), content: rerouted.content, steeredAt: new Date().toISOString() });
+      return selected.map((item) => item.handle);
+    } catch (error) {
+      this.cancelSteering(selected);
+      throw error;
+    }
   }
 
   abort(promptId: string, reason: Error = userCancellationReason()): boolean {
     if (this.active?.id === promptId) { this.loop.cancel(this.active.turn.id, reason); return true; }
+    if (this.launchingItem?.id === promptId) {
+      const item = this.launchingItem;
+      this.cancelRecord(item, reason);
+      return true;
+    }
+    const reservation = this.steering.get(promptId);
+    if (reservation !== undefined) {
+      this.steering.delete(promptId);
+      this.cancelRecord(reservation.item, reason);
+      return true;
+    }
     const index = this.pending.findIndex((item) => item.id === promptId);
     if (index < 0) throw new Error2(ErrorCodes.PROMPT_NOT_FOUND, `prompt ${promptId} not found`);
     const [item] = this.pending.splice(index, 1) as [Record];
-    item.state = 'cancelled'; item.launchedDeferred.resolve(undefined);
-    item.completionDeferred.resolve({ promptId, result: undefined, state: 'cancelled' });
-    this.publishAborted(promptId);
+    this.cancelRecord(item, reason);
     return true;
   }
 
+  async drain(reason: Error = userCancellationReason()): Promise<void> {
+    for (const item of this.pending.slice()) this.abort(item.id, reason);
+    for (const item of this.steering.values()) this.abort(item.item.id, reason);
+    if (this.launchingItem !== undefined) this.abort(this.launchingItem.id, reason);
+    for (const controller of this.intakeControllers) controller.abort(reason);
+    await Promise.allSettled(this.intakes);
+  }
+
   async inject(message: ContextMessage): Promise<Turn | undefined> {
     const { message: rerouted, captions } = this.extractCompressionCaptions(message);
     const request = new SteerStepRequest(rerouted, captions, this.reminders, (materialized) => {
@@ -261,40 +433,95 @@ export class AgentPromptService implements IAgentPromptService {
 
   clear(): void {
     for (const item of this.pending.slice()) this.abort(item.id);
+    for (const item of this.steering.values()) this.abort(item.item.id);
+    if (this.launchingItem !== undefined) this.abort(this.launchingItem.id);
     if (this.active !== undefined) this.abort(this.active.id);
     this.context.clear();
   }
 
+  override dispose(): void {
+    for (const controller of this.intakeControllers) controller.abort(userCancellationReason());
+    super.dispose();
+  }
+
+  private reservationsMatch(
+    selected: readonly Record[],
+    active: Record & { turn: Turn },
+  ): boolean {
+    return selected.every((item) => {
+      const reservation = this.steering.get(item.id);
+      return reservation?.item === item && reservation.active === active;
+    });
+  }
+
+  private cancelSteering(selected: readonly Record[], reason = userCancellationReason()): void {
+    for (const item of selected) {
+      const reservation = this.steering.get(item.id);
+      if (reservation?.item !== item) continue;
+      this.steering.delete(item.id);
+      this.cancelRecord(item, reason);
+    }
+  }
+
+  private cancelRecord(item: Record, reason: Error): void {
+    if (cancelled(item)) return;
+    item.intakeController.abort(reason);
+    item.state = 'cancelled';
+    item.launchedDeferred.resolve(undefined);
+    item.completionDeferred.resolve({ promptId: item.id, result: undefined, state: 'cancelled' });
+    this.publishAborted(item.id);
+  }
+
   private async startNext(): Promise<void> {
     if (this.active !== undefined || this.launching) return;
     const item = this.pending.shift(); if (item === undefined) return;
     this.launching = true;
+    this.launchingItem = item;
+    let requeued = false;
     try {
-      if (this.fullCompaction.compacting !== null && this.loop.status().state !== 'running') { this.pending.unshift(item); return; }
+      await Promise.race([item.intake, item.launchedDeferred.promise]);
+      if (cancelled(item)) return;
+      if (this.fullCompaction.compacting !== null && this.loop.status().state !== 'running') {
+        this.pending.unshift(item);
+        requeued = true;
+        return;
+      }
       const { message, captions } = this.extractCompressionCaptions(item.message);
-      if (await this.blockedByHook(message, false)) {
+      const blocked = await this.blockedByHook(message, false);
+      if (cancelled(item)) return;
+      if (blocked) {
         this.appendPrompt(message, captions); item.state = 'blocked'; item.launchedDeferred.resolve(undefined);
         item.completionDeferred.resolve({ promptId: item.id, result: undefined, state: 'blocked' });
         this.publishCompleted(item.id, 'blocked'); return;
       }
       const turn = (await this.loop.enqueue(new PromptStepRequest(message, captions, this.reminders)).assigned).turn;
-      if (turn === undefined) { this.pending.unshift(item); return; }
+      if (turn === undefined) { if (!cancelled(item)) this.pending.unshift(item); return; }
+      if (cancelled(item)) { this.loop.cancel(turn.id); return; }
       item.state = 'running'; item.launchedDeferred.resolve(turn); this.active = Object.assign(item, { turn });
-      void turn.result.then((result) => this.settle(item, result));
+      void turn.result.then((result) => {
+        this.settle(item, result);
+      });
     } catch {
+      if (cancelled(item)) return;
       item.state = 'failed';
       item.launchedDeferred.resolve(undefined);
       item.completionDeferred.resolve({ promptId: item.id, result: undefined, state: 'failed' });
       this.publishCompleted(item.id, 'failed');
     } finally {
+      this.launchingItem = undefined;
       this.launching = false;
-      if (this.active === undefined) void this.startNext();
+      if (!requeued && this.active === undefined) void this.startNext();
     }
   }
 
   private settle(item: Record, result: TurnResult): void {
     if (this.active?.id !== item.id) return;
     this.active = undefined;
+    this.cancelSteering(
+      [...this.steering.values()]
+        .filter((reservation) => reservation.active === item)
+        .map((reservation) => reservation.item),
+    );
     const state = result.type === 'cancelled' ? 'cancelled' : result.type === 'failed' ? 'failed' : 'completed';
     item.state = state; item.completionDeferred.resolve({ promptId: item.id, result, state });
     for (const child of this.steered.get(item.id) ?? []) { child.state = state; child.completionDeferred.resolve({ promptId: child.id, result, state }); }
@@ -342,12 +569,23 @@ export class AgentPromptService implements IAgentPromptService {
   private publishCompleted(promptId: string, reason: 'completed' | 'failed' | 'blocked'): void { this.eventBus.publish({ type: 'prompt.completed', promptId, finishedAt: new Date().toISOString(), reason }); }
   private publishQueued(record: Record): void {
     if ((record.message.origin ?? USER_PROMPT_ORIGIN).kind !== 'user') return;
-    this.eventBus.publish({ type: 'prompt.queued', promptId: record.id, content: record.message.content, queueLength: this.pending.length });
+    // Count from the same snapshot `list()` exposes: a record startNext
+    // already shifted into `launchingItem` (media intake still running) is
+    // still queued.
+    const queueLength = this.pending.length + (this.launchingItem === undefined ? 0 : 1);
+    this.eventBus.publish({ type: 'prompt.queued', promptId: record.id, content: record.message.content, queueLength });
   }
   private publishAborted(promptId: string): void { this.eventBus.publish({ type: 'prompt.aborted', promptId, abortedAt: new Date().toISOString() }); }
 }
 
+function promptIdConflict(promptId: string): Error2 {
+  return new Error2(ErrorCodes.PROMPT_ID_CONFLICT, `prompt id "${promptId}" is already in use`, {
+    details: { promptId },
+  });
+}
+
 function snapshot(item: Record): PromptSnapshot { return { id: item.id, userMessageId: item.userMessageId, createdAt: item.createdAt, state: item.state, message: item.message }; }
+function cancelled(item: Record): boolean { return item.state === 'cancelled'; }
 function deferred<T>(): Deferred<T> { let resolve!: (value: T) => void; let reject!: (reason: unknown) => void; const promise = new Promise<T>((res, rej) => { resolve = res; reject = rej; }); return { promise, resolve, reject }; }
 
 registerScopedService(
diff --git a/packages/agent-core-v2/src/agent/prompt/promptStepRequests.ts b/packages/agent-core-v2/src/agent/prompt/promptStepRequests.ts
index c67687180fd..3272a4d4d0c 100644
--- a/packages/agent-core-v2/src/agent/prompt/promptStepRequests.ts
+++ b/packages/agent-core-v2/src/agent/prompt/promptStepRequests.ts
@@ -73,7 +73,11 @@ export class PromptStepRequest extends UserMessageStepRequest {
   }
 
   override get turnSeed(): TurnSeed {
-    return { input: this.message.content, origin: this.message.origin ?? USER_PROMPT_ORIGIN };
+    return {
+      input: this.message.content,
+      origin: this.message.origin ?? USER_PROMPT_ORIGIN,
+      promptId: this.message.id,
+    };
   }
 }
 
diff --git a/packages/agent-core-v2/src/app/file/fileService.ts b/packages/agent-core-v2/src/app/file/fileService.ts
index 2dbab364381..57fc1a0fb9b 100644
--- a/packages/agent-core-v2/src/app/file/fileService.ts
+++ b/packages/agent-core-v2/src/app/file/fileService.ts
@@ -51,6 +51,18 @@ export interface IFileService {
 
 export const IFileService: ServiceIdentifier<IFileService> = createDecorator<IFileService>('fileService');
 
+/**
+ * The upload id shape every `fileId`-addressed store may rely on. Ids are
+ * minted by `IFileService.save` (`f_<uuid>`); anything else is not an upload
+ * and must never reach a storage key — the character whitelist is what keeps
+ * a caller-supplied id from escaping its storage scope (`..`, separators).
+ */
+export const FILE_ID_REGEX = /^f_[A-Za-z0-9][A-Za-z0-9_-]*$/;
+
+export function isFileId(value: string): boolean {
+  return FILE_ID_REGEX.test(value);
+}
+
 
 export const FileErrors = {
   codes: {
diff --git a/packages/agent-core-v2/src/app/file/fileServiceImpl.ts b/packages/agent-core-v2/src/app/file/fileServiceImpl.ts
index d3de270f0ed..5f8bb672974 100644
--- a/packages/agent-core-v2/src/app/file/fileServiceImpl.ts
+++ b/packages/agent-core-v2/src/app/file/fileServiceImpl.ts
@@ -13,13 +13,14 @@
 import { randomUUID } from 'node:crypto';
 import { Readable } from 'node:stream';
 
-import type { FileMeta } from './fileService';
 import { LifecycleScope } from '#/app/scopes';
 import { ScopeActivation, registerScopedService } from '#/_base/di/scope';
 import { IBlobStore } from '#/persistence/interface/blobStore';
 import {
   IFileService,
   fileNotFoundError,
+  isFileId,
+  type FileMeta,
   type FileReadRange,
   type GetResult,
   type SaveOptions,
@@ -28,7 +29,6 @@ import {
 const BLOB_SCOPE = 'files';
 const INDEX_SCOPE = 'file';
 const INDEX_KEY = 'index.json';
-const FILE_ID_REGEX = /^f_[A-Za-z0-9][A-Za-z0-9_-]*$/;
 
 const textEncoder = new TextEncoder();
 const textDecoder = new TextDecoder();
@@ -38,10 +38,6 @@ interface IndexFile {
   readonly files: FileMeta[];
 }
 
-function isFileId(value: string): boolean {
-  return FILE_ID_REGEX.test(value);
-}
-
 function isFileMeta(value: unknown): value is FileMeta {
   if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;
   const meta = value as Record<string, unknown>;
@@ -63,11 +59,13 @@ export class FileServiceImpl implements IFileService {
 
   private indexCache: Map<string, FileMeta> | undefined;
   private indexLoadPromise: Promise<void> | undefined;
+  private indexWritePromise: Promise<void> = Promise.resolve();
 
   constructor(@IBlobStore private readonly blobs: IBlobStore) {}
 
   async save(source: Readable, filename: string, options: SaveOptions = {}): Promise<FileMeta> {
     await this.ensureIndex();
+    await this.pruneExpired();
 
     const id = `f_${randomUUID()}`;
     let size = 0;
@@ -92,9 +90,10 @@ export class FileServiceImpl implements IFileService {
       media_type: options.mimeType ?? 'application/octet-stream',
       size,
       created_at: new Date(now).toISOString(),
-      ...(options.expiresInSec !== undefined
-        ? { expires_at: new Date(now + options.expiresInSec * 1000).toISOString() }
-        : {}),
+      expires_at:
+        options.expiresInSec === undefined
+          ? undefined
+          : new Date(now + options.expiresInSec * 1000).toISOString(),
     };
 
     this.indexCache!.set(id, meta);
@@ -107,6 +106,7 @@ export class FileServiceImpl implements IFileService {
       throw fileNotFoundError(fileId);
     }
     await this.ensureIndex();
+    await this.pruneExpired();
     const meta = this.indexCache!.get(fileId);
     if (meta === undefined) {
       throw fileNotFoundError(fileId);
@@ -165,16 +165,36 @@ export class FileServiceImpl implements IFileService {
         }
       }
       this.indexCache = map;
+      await this.pruneExpired();
     } catch {
       this.indexCache = new Map();
     }
   }
 
-  private async writeIndex(): Promise<void> {
+  private async pruneExpired(): Promise<void> {
     const cache = this.indexCache;
     if (cache === undefined) return;
-    const payload: IndexFile = { version: 1, files: Array.from(cache.values()) };
-    await this.blobs.put(INDEX_SCOPE, INDEX_KEY, textEncoder.encode(JSON.stringify(payload)));
+    const now = Date.now();
+    const expired = [...cache.values()].filter(
+      (meta) => meta.expires_at !== undefined && Date.parse(meta.expires_at) <= now,
+    );
+    if (expired.length === 0) return;
+    for (const meta of expired) {
+      cache.delete(meta.id);
+      await this.blobs.delete(BLOB_SCOPE, meta.id).catch(() => undefined);
+    }
+    await this.writeIndex().catch(() => undefined);
+  }
+
+  private async writeIndex(): Promise<void> {
+    const write = this.indexWritePromise.catch(() => undefined).then(async () => {
+      const cache = this.indexCache;
+      if (cache === undefined) return;
+      const payload: IndexFile = { version: 1, files: Array.from(cache.values()) };
+      await this.blobs.put(INDEX_SCOPE, INDEX_KEY, textEncoder.encode(JSON.stringify(payload)));
+    });
+    this.indexWritePromise = write;
+    await write;
   }
 }
 
diff --git a/packages/agent-core-v2/src/index.ts b/packages/agent-core-v2/src/index.ts
index 79c5518807b..28ade125583 100644
--- a/packages/agent-core-v2/src/index.ts
+++ b/packages/agent-core-v2/src/index.ts
@@ -631,8 +631,25 @@ export * from '#/mcpCore/config-schema';
 export * from '#/agent/media/mediaTools';
 export * from '#/agent/media/mediaToolsRegistrar';
 export * from '#/agent/media/registerMediaTools';
+// mediaRef keeps a named export list: the module's remaining helpers (suffix
+// tables, tag escaping, session fs layout) are domain-internal, and external
+// consumers only need the reference/tag grammar below.
+export {
+  buildDaemonFileUrl,
+  buildMediaPathTag,
+  daemonFileRefFromPart,
+  mediaExtensionForMime,
+  matchSingleMediaPathTag,
+  parseDaemonFileUrl,
+} from '#/agent/media/mediaRef';
+export type { DaemonFileRef, MediaKind } from '#/agent/media/mediaRef';
+export * from '#/agent/media/sessionMediaStore';
+import '#/agent/media/sessionMediaStoreService';
 export * from '#/agent/media/kimiFileUrl';
 export * from '#/agent/media/videoUpload';
+export * from '#/agent/media/mediaResolver';
+export * from '#/agent/media/mediaResolverService';
+// Deprecated aliases kept so existing consumers compile unchanged.
 export * from '#/agent/media/videoResolver';
 export * from '#/agent/media/videoResolverService';
 import '#/agent/media/configSection';
@@ -653,6 +670,7 @@ export * from '#/agent/profile/profile';
 export * from '#/agent/profile/profileService';
 export * from '#/agent/profile/context';
 export * from '#/agent/prompt/prompt';
+export * from '#/agent/prompt/promptOps';
 export * from '#/agent/prompt/promptService';
 export * from '#/agent/prompt/promptMetadataText';
 export * from '#/agent/replayBuilder/types';
diff --git a/packages/agent-core-v2/src/persistence/backends/memory/inMemoryStorageService.ts b/packages/agent-core-v2/src/persistence/backends/memory/inMemoryStorageService.ts
index b32ec029f22..77f29c7b4e6 100644
--- a/packages/agent-core-v2/src/persistence/backends/memory/inMemoryStorageService.ts
+++ b/packages/agent-core-v2/src/persistence/backends/memory/inMemoryStorageService.ts
@@ -61,8 +61,9 @@ export class InMemoryStorageService implements IFileSystemStorageService {
     scope: string,
     key: string,
     data: Uint8Array,
-    _options: StorageWriteOptions = {},
+    options: StorageWriteOptions = {},
   ): Promise<void> {
+    options.signal?.throwIfAborted();
     this.bucket(scope).set(key, data);
     this.notifyWatchers(scope, key);
   }
@@ -71,14 +72,16 @@ export class InMemoryStorageService implements IFileSystemStorageService {
     scope: string,
     key: string,
     source: AsyncIterable<Uint8Array>,
-    _options: StorageWriteOptions = {},
+    options: StorageWriteOptions = {},
   ): Promise<void> {
     const chunks: Uint8Array[] = [];
     let total = 0;
     for await (const chunk of source) {
+      options.signal?.throwIfAborted();
       chunks.push(chunk);
       total += chunk.byteLength;
     }
+    options.signal?.throwIfAborted();
     const merged = new Uint8Array(total);
     let offset = 0;
     for (const chunk of chunks) {
@@ -121,6 +124,14 @@ export class InMemoryStorageService implements IFileSystemStorageService {
     this.notifyWatchers(scope, key);
   }
 
+  async size(scope: string, key: string): Promise<number | undefined> {
+    return this.scopes.get(scope)?.get(key)?.byteLength;
+  }
+
+  pathFor(_scope: string, _key: string): undefined {
+    return undefined;
+  }
+
   watch(scope: string, key: string): Event<void> {
     const id = this.watchKey(scope, key);
     return (listener, thisArg, disposables) => {
diff --git a/packages/agent-core-v2/src/persistence/backends/node-fs/fileStorageService.ts b/packages/agent-core-v2/src/persistence/backends/node-fs/fileStorageService.ts
index e7ce6d995fd..b76fb1f35f8 100644
--- a/packages/agent-core-v2/src/persistence/backends/node-fs/fileStorageService.ts
+++ b/packages/agent-core-v2/src/persistence/backends/node-fs/fileStorageService.ts
@@ -22,7 +22,7 @@
  */
 
 import { createReadStream, mkdirSync } from 'node:fs';
-import { mkdir, open, readFile, readdir, unlink } from 'node:fs/promises';
+import { mkdir, open, readFile, readdir, stat, unlink } from 'node:fs/promises';
 import { FSWatcher } from 'chokidar';
 import { dirname, join, normalize } from 'pathe';
 
@@ -57,7 +57,7 @@ export class FileStorageService implements IFileSystemStorageService {
   ) {}
 
   async read(scope: string, key: string): Promise<Uint8Array | undefined> {
-    const filePath = this.path(scope, key);
+    const filePath = this.pathFor(scope, key);
     try {
       return await readFile(filePath);
     } catch (error) {
@@ -71,7 +71,7 @@ export class FileStorageService implements IFileSystemStorageService {
     key: string,
     range?: StorageReadRange,
   ): AsyncIterable<Uint8Array> {
-    const filePath = this.path(scope, key);
+    const filePath = this.pathFor(scope, key);
     const stream = createReadStream(
       filePath,
       range === undefined ? undefined : { start: range.start, end: range.end },
@@ -90,14 +90,15 @@ export class FileStorageService implements IFileSystemStorageService {
     scope: string,
     key: string,
     data: Uint8Array,
-    _options: StorageWriteOptions = {},
+    options: StorageWriteOptions = {},
   ): Promise<void> {
-    const filePath = this.path(scope, key);
+    const filePath = this.pathFor(scope, key);
     try {
       await mkdir(dirname(filePath), { recursive: true, mode: this.dirMode });
-      await atomicWrite(filePath, data, undefined, this.fileMode);
+      await atomicWrite(filePath, data, undefined, this.fileMode, options.signal);
       await this.syncDirOnce(dirname(filePath));
     } catch (error) {
+      options.signal?.throwIfAborted();
       throw toStorageIoError(error, { path: filePath, op: 'write' });
     }
   }
@@ -106,14 +107,15 @@ export class FileStorageService implements IFileSystemStorageService {
     scope: string,
     key: string,
     source: AsyncIterable<Uint8Array>,
-    _options: StorageWriteOptions = {},
+    options: StorageWriteOptions = {},
   ): Promise<void> {
-    const filePath = this.path(scope, key);
+    const filePath = this.pathFor(scope, key);
     try {
       await mkdir(dirname(filePath), { recursive: true, mode: this.dirMode });
-      await atomicWriteStream(filePath, source, this.fileMode);
+      await atomicWriteStream(filePath, source, this.fileMode, options.signal);
       await this.syncDirOnce(dirname(filePath));
     } catch (error) {
+      options.signal?.throwIfAborted();
       throw toStorageIoError(error, { path: filePath, op: 'write' });
     }
   }
@@ -124,7 +126,7 @@ export class FileStorageService implements IFileSystemStorageService {
     data: Uint8Array,
     options: StorageAppendOptions = {},
   ): Promise<void> {
-    const filePath = this.path(scope, key);
+    const filePath = this.pathFor(scope, key);
     const dir = dirname(filePath);
     try {
       await mkdir(dir, { recursive: true, mode: this.dirMode });
@@ -158,7 +160,7 @@ export class FileStorageService implements IFileSystemStorageService {
   }
 
   async delete(scope: string, key: string): Promise<void> {
-    const filePath = this.path(scope, key);
+    const filePath = this.pathFor(scope, key);
     try {
       await unlink(filePath);
     } catch (error) {
@@ -167,8 +169,18 @@ export class FileStorageService implements IFileSystemStorageService {
     }
   }
 
+  async size(scope: string, key: string): Promise<number | undefined> {
+    const filePath = this.pathFor(scope, key);
+    try {
+      return (await stat(filePath)).size;
+    } catch (error) {
+      if (isEnoent(error)) return undefined;
+      throw toStorageIoError(error, { path: filePath, op: 'stat' });
+    }
+  }
+
   watch(scope: string, key: string): Event<void> {
-    const target = this.path(scope, key);
+    const target = this.pathFor(scope, key);
     const dir = dirname(target);
     const normalizedTarget = normalize(target);
     const emitter = new Emitter<void>();
@@ -236,7 +248,7 @@ export class FileStorageService implements IFileSystemStorageService {
 
   async close(): Promise<void> {}
 
-  private path(scope: string, key: string): string {
+  pathFor(scope: string, key: string): string {
     return join(this.baseDir, scope, key);
   }
 
diff --git a/packages/agent-core-v2/src/persistence/interface/storage.ts b/packages/agent-core-v2/src/persistence/interface/storage.ts
index 1d55183cb12..1323ffb8d18 100644
--- a/packages/agent-core-v2/src/persistence/interface/storage.ts
+++ b/packages/agent-core-v2/src/persistence/interface/storage.ts
@@ -149,6 +149,7 @@ export function toStorageIoError(error: unknown, ctx: { path: string; op: string
 
 export interface StorageWriteOptions {
   readonly atomic?: boolean;
+  readonly signal?: AbortSignal;
 }
 
 export interface StorageAppendOptions {
@@ -175,6 +176,8 @@ export interface IFileSystemStorageService {
   append(scope: string, key: string, data: Uint8Array, options?: StorageAppendOptions): Promise<void>;
   list(scope: string, prefix?: string): Promise<readonly string[]>;
   delete(scope: string, key: string): Promise<void>;
+  size(scope: string, key: string): Promise<number | undefined>;
+  pathFor(scope: string, key: string): string | undefined;
   watch?(scope: string, key: string): Event<void>;
   flush(): Promise<void>;
   close(): Promise<void>;
diff --git a/packages/agent-core-v2/src/session/agentLifecycle/agentLifecycleService.ts b/packages/agent-core-v2/src/session/agentLifecycle/agentLifecycleService.ts
index 9b119e288e4..51e323f5f48 100644
--- a/packages/agent-core-v2/src/session/agentLifecycle/agentLifecycleService.ts
+++ b/packages/agent-core-v2/src/session/agentLifecycle/agentLifecycleService.ts
@@ -55,6 +55,7 @@ import { IAgentRuntimeBindingSeed, IAgentRuntimeBindingService } from '#/agent/r
 import '#/agent/runtimeBinding/runtimeBindingService';
 import { IAgentFullCompactionService } from '#/agent/fullCompaction/fullCompaction';
 import { IAgentToolActivationService } from '#/agent/toolActivation/toolActivation';
+import { IAgentPromptService } from '#/agent/prompt/prompt';
 import { ISessionInteractionService } from '#/session/interaction/interaction';
 import { IWireService } from '#/wire/wire';
 import { ITelemetryService } from '#/app/telemetry/telemetry';
@@ -284,6 +285,7 @@ export class AgentLifecycleService extends Disposable implements IAgentLifecycle
     const compaction = handle.accessor.get(IAgentFullCompactionService).compacting;
     const compactionSettled = compaction?.promise.catch(() => undefined) ?? Promise.resolve();
     const reason = abortError('Agent removed');
+    const prompt = handle.accessor.get(IAgentPromptService);
     for (const turnId of loop.status().pendingTurnIds) {
       loop.cancel(turnId, reason);
     }
@@ -291,7 +293,7 @@ export class AgentLifecycleService extends Disposable implements IAgentLifecycle
     if (compaction !== null && !compaction.abortController.signal.aborted) {
       compaction.abortController.abort(reason);
     }
-    await Promise.all([loop.settled(), compactionSettled]);
+    await Promise.all([loop.settled(), compactionSettled, prompt.drain(reason)]);
     handle.dispose();
     this.onDidDisposeEmitter.fire(agentId);
   }
diff --git a/packages/agent-core-v2/test/agent/llmRequester/llmRequesterService.test.ts b/packages/agent-core-v2/test/agent/llmRequester/llmRequesterService.test.ts
index 3f3bb9fd2aa..34b4be82dcb 100644
--- a/packages/agent-core-v2/test/agent/llmRequester/llmRequesterService.test.ts
+++ b/packages/agent-core-v2/test/agent/llmRequester/llmRequesterService.test.ts
@@ -12,7 +12,7 @@
  */
 
 import { createControlledPromise } from '@antfu/utils';
-import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { SyncDescriptor } from '#/_base/di/descriptors';
 import { DisposableStore, toDisposable } from '#/_base/di/lifecycle';
@@ -32,7 +32,7 @@ import { IAgentStateService } from '#/agent/state/agentState';
 import { AgentStateService } from '#/agent/state/agentStateService';
 import { IAgentToolRegistryService } from '#/agent/toolRegistry/toolRegistry';
 import { IAgentToolSelectService } from '#/agent/toolSelect/toolSelect';
-import { IAgentVideoResolverService } from '#/agent/media/videoResolver';
+import { IAgentMediaResolverService } from '#/agent/media/mediaResolver';
 import { IAgentUsageService } from '#/agent/usage/usage';
 import { IConfigService } from '#/app/config/config';
 import { type DomainEvent, IEventBus } from '#/app/event/eventBus';
@@ -146,6 +146,7 @@ function createService(
     | undefined,
   options: {
     readonly thinkingLevel?: ThinkingEffort;
+    readonly mediaResolver?: Partial<IAgentMediaResolverService>;
     readonly contextMessages?: Message[];
   } = {},
 ) {
@@ -202,7 +203,7 @@ function createService(
 
   ix.stub(IAgentContextMemoryService, context);
   ix.stub(IAgentToolSelectService, toolSelect);
-  ix.stub(IAgentVideoResolverService, { resolve: async (messages) => messages });
+  ix.stub(IAgentMediaResolverService, options.mediaResolver ?? { resolve: async (messages) => messages });
   if (projector === undefined) {
     ix.set(
       IAgentContextProjectorService,
@@ -808,6 +809,21 @@ describe('AgentLLMRequesterService trace id', () => {
   });
 });
 
+describe('AgentLLMRequesterService media resolver wiring', () => {
+  it('resolves the projected messages through the DI-injected media resolver', async () => {
+    const requester = createRequester({ value: 0 }, null);
+    const resolve = vi.fn(async (messages: readonly Message[], _requester: ModelRequester) => messages);
+    const { service } = createService(requester, undefined, {
+      mediaResolver: { resolve },
+    });
+
+    await service.request();
+
+    expect(resolve).toHaveBeenCalledTimes(1);
+    expect(resolve.mock.calls[0]?.[1]).toBe(requester);
+  });
+});
+
 describe('AgentLLMRequesterService tool call id normalization', () => {
   function createScriptedRequester(
     script: { ids: string[]; error?: Error }[],
diff --git a/packages/agent-core-v2/test/agent/loop/loop.test.ts b/packages/agent-core-v2/test/agent/loop/loop.test.ts
index ae9390b389b..deb7c2932ee 100644
--- a/packages/agent-core-v2/test/agent/loop/loop.test.ts
+++ b/packages/agent-core-v2/test/agent/loop/loop.test.ts
@@ -59,8 +59,9 @@ describe('Agent loop', () => {
 
     expect(await ctx.untilTurnEnd()).toMatchInlineSnapshot(`
       [wire] tools.set_active_tools      { "names": [], "time": "<time>" }
+      [wire] prompt.accepted             { "promptId": "<msg-1>", "time": "<time>" }
       [wire] turn.prompt                 { "input": [ { "type": "text", "text": "Hello" } ], "origin": { "kind": "user" }, "time": "<time>" }
-      [emit] turn.started                { "turnId": 0, "origin": { "kind": "user" }, "prompt": "Hello" }
+      [emit] turn.started                { "turnId": 0, "origin": { "kind": "user" }, "prompt": "Hello", "promptId": "<msg-1>" }
       [emit] agent.activity.updated      { "lifecycle": "ready", "turn": { "turnId": 0, "origin": { "kind": "user" }, "phase": "running", "step": 0, "ending": false, "pendingApprovals": [], "activeToolCalls": [], "since": "<time>" }, "background": [] }
       [emit] context.spliced             { "start": 0, "deleteCount": 0, "messages": [ { "role": "user", "content": [ { "type": "text", "text": "Hello" } ], "toolCalls": [], "origin": { "kind": "user" }, "id": "<msg-1>" } ] }
       [wire] context.append_message      { "message": { "role": "user", "content": [ { "type": "text", "text": "Hello" } ], "toolCalls": [], "origin": { "kind": "user" }, "id": "<msg-1>" }, "time": "<time>" }
@@ -115,8 +116,9 @@ describe('Agent loop', () => {
     await ctx.rpc.prompt({ input: [{ type: 'text', text: 'Hello' }] });
 
     expect(await ctx.untilTurnEnd()).toMatchInlineSnapshot(`
+      [wire] prompt.accepted             { "promptId": "<msg-1>", "time": "<time>" }
       [wire] turn.prompt                 { "input": [ { "type": "text", "text": "Hello" } ], "origin": { "kind": "user" }, "time": "<time>" }
-      [emit] turn.started                { "turnId": 0, "origin": { "kind": "user" }, "prompt": "Hello" }
+      [emit] turn.started                { "turnId": 0, "origin": { "kind": "user" }, "prompt": "Hello", "promptId": "<msg-1>" }
       [emit] agent.activity.updated      { "lifecycle": "ready", "turn": { "turnId": 0, "origin": { "kind": "user" }, "phase": "running", "step": 0, "ending": false, "pendingApprovals": [], "activeToolCalls": [], "since": "<time>" }, "background": [] }
       [emit] context.spliced             { "start": 0, "deleteCount": 0, "messages": [ { "role": "user", "content": [ { "type": "text", "text": "Hello" } ], "toolCalls": [], "origin": { "kind": "user" }, "id": "<msg-1>" } ] }
       [wire] context.append_message      { "message": { "role": "user", "content": [ { "type": "text", "text": "Hello" } ], "toolCalls": [], "origin": { "kind": "user" }, "id": "<msg-1>" }, "time": "<time>" }
@@ -336,8 +338,9 @@ describe('Agent loop', () => {
     ctx.mockNextResponse({ type: 'text', text: 'The lookup result is lookup-result.' });
     expect(await ctx.untilApproval(true)).toMatchInlineSnapshot(`
       [wire] tools.set_active_tools          { "names": [ "Lookup" ], "time": "<time>" }
+      [wire] prompt.accepted                 { "promptId": "<msg-1>", "time": "<time>" }
       [wire] turn.prompt                     { "input": [ { "type": "text", "text": "Look up moon" } ], "origin": { "kind": "user" }, "time": "<time>" }
-      [emit] turn.started                    { "turnId": 0, "origin": { "kind": "user" }, "prompt": "Look up moon" }
+      [emit] turn.started                    { "turnId": 0, "origin": { "kind": "user" }, "prompt": "Look up moon", "promptId": "<msg-1>" }
       [emit] agent.activity.updated          { "lifecycle": "ready", "turn": { "turnId": 0, "origin": { "kind": "user" }, "phase": "running", "step": 0, "ending": false, "pendingApprovals": [], "activeToolCalls": [], "since": "<time>" }, "background": [] }
       [emit] context.spliced                 { "start": 0, "deleteCount": 0, "messages": [ { "role": "user", "content": [ { "type": "text", "text": "Look up moon" } ], "toolCalls": [], "origin": { "kind": "user" }, "id": "<msg-1>" } ] }
       [wire] context.append_message          { "message": { "role": "user", "content": [ { "type": "text", "text": "Look up moon" } ], "toolCalls": [], "origin": { "kind": "user" }, "id": "<msg-1>" }, "time": "<time>" }
@@ -711,8 +714,10 @@ describe('Agent loop', () => {
 
   it('omits the turn.started prompt for system-triggered turns', async () => {
     const prompts: Array<string | undefined> = [];
+    const promptIds: Array<string | undefined> = [];
     const subscription = ctx.get(IEventBus).subscribe('turn.started', (event) => {
       prompts.push(event.prompt);
+      promptIds.push(event.promptId);
     });
     ctx.mockNextResponse({ type: 'text', text: 'continued' });
     ctx.mockNextResponse({ type: 'text', text: 'hi there' });
@@ -736,6 +741,60 @@ describe('Agent loop', () => {
     subscription.dispose();
 
     expect(prompts).toEqual([undefined, 'hi']);
+    expect(promptIds).toEqual([undefined, undefined]);
+  });
+
+  it('echoes the prompt record id in turn.started for prompt-opened turns', async () => {
+    profile.update({ activeToolNames: [] });
+    const started: Array<{ promptId?: string }> = [];
+    const subscription = ctx.get(IEventBus).subscribe('turn.started', (event) => {
+      started.push({ promptId: event.promptId });
+    });
+    ctx.mockNextResponse({ type: 'text', text: 'hi there' });
+
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'Hello' }], promptId: 'sub-1' });
+    await ctx.untilTurnEnd();
+    subscription.dispose();
+
+    expect(ctx.contextData().history[0]?.id).toBe('sub-1');
+    expect(started).toEqual([{ promptId: 'sub-1' }]);
+  });
+
+  it('projects daemon-ref upload parts into turn.started prompt and promptAttachments', async () => {
+    const started: Array<{ prompt?: string; promptAttachments?: unknown }> = [];
+    const subscription = ctx.get(IEventBus).subscribe('turn.started', (event) => {
+      started.push({ prompt: event.prompt, promptAttachments: event.promptAttachments });
+    });
+    ctx.mockNextResponse({ type: 'text', text: 'a screenshot' });
+
+    const turn = (
+      await loop.enqueue(
+        new MessageStepRequest(
+          {
+            role: 'user',
+            content: [
+              { type: 'text', text: 'what is this?' },
+              {
+                type: 'image_url',
+                imageUrl: { url: 'kimi-file://f_123' },
+              },
+            ],
+            toolCalls: [],
+            origin: { kind: 'user' },
+          },
+          { admission: 'newTurn' },
+        ),
+      ).assigned
+    ).turn;
+    await turn.result;
+    subscription.dispose();
+
+    expect(started).toEqual([
+      {
+        prompt: 'what is this?',
+        promptAttachments: [{ kind: 'image', fileId: 'f_123' }],
+      },
+    ]);
   });
 });
 
diff --git a/packages/agent-core-v2/test/agent/loop/stubs.ts b/packages/agent-core-v2/test/agent/loop/stubs.ts
index 59f3b59839b..a70659ec3f3 100644
--- a/packages/agent-core-v2/test/agent/loop/stubs.ts
+++ b/packages/agent-core-v2/test/agent/loop/stubs.ts
@@ -3,16 +3,16 @@
  */
 import { toDisposable } from '#/_base/di/lifecycle';
 import { Event } from '#/_base/event';
-import type { IAgentLoopService, LoopErrorHandler, LoopErrorHandlerRegistrationOptions, Step, Turn } from '#/agent/loop/loop';
+import type { IAgentLoopService, LoopErrorHandler, LoopErrorHandlerRegistrationOptions, Step, Turn, TurnResult } from '#/agent/loop/loop';
 import type { StepRequest } from '#/agent/loop/stepRequest';
 import { StepRequestQueue, type StepRequestBatch } from '#/agent/loop/stepRequestQueue';
 import type { IAgentToolExecutorService } from '#/agent/toolExecutor/toolExecutor';
 import type { BeforeToolExecuteEvent, ToolDidExecuteContext, WillExecuteToolEvent } from '#/agent/toolExecutor/toolHooks';
-import { OrderedHookSlot } from '#/hooks';
+import { OrderedHookSlot, createHooks } from '#/hooks';
 import type { ContentPart } from '#/kosong/contract/message';
 import type { ContextMessage, PromptOrigin } from '#/agent/contextMemory/types';
-import { createHooks } from '#/hooks';
 import type { Op } from '#/wire/op';
+import type { ModelDef } from '#/wire/model';
 import type { IWireService } from '#/wire/wire';
 
 export interface StubLoopOptions { readonly hasActiveTurn?: boolean; readonly currentId?: string | number; readonly pendingTurnResult?: boolean }
@@ -21,6 +21,7 @@ export type StubLoop = IAgentLoopService & {
   readonly launches: readonly number[];
   readonly cancels: readonly { readonly turnId?: number; readonly reason?: unknown }[];
   startTurn(): Turn;
+  finishActive(result?: TurnResult): void;
   drainNextBatch(context: { append(...messages: ContextMessage[]): void }): StepRequestBatch | undefined;
 };
 const turnControllers = new WeakMap<Turn, AbortController>();
@@ -44,19 +45,27 @@ function registry(): { handlers: LoopErrorHandler[]; register: IAgentLoopService
   };
   return { handlers, register };
 }
-function materialize(request: StepRequest, context: { append(...messages: ContextMessage[]): void }): void { if (request.state !== 'pending') return; request.onWillMaterialize(); const messages = request.resolveContextMessages(); if (messages.length) context.append(...messages); request.markMaterialized(); }
+function materialize(request: StepRequest, context: { append(...messages: ContextMessage[]): void }): void { if (request.state !== 'pending') return; request.onWillMaterialize(); const messages = request.resolveContextMessages(); if (messages.length > 0) context.append(...messages); request.markMaterialized(); }
 export function stubLoopWithHooks(options: StubLoopOptions = {}): StubLoop {
   const hooks = createHooks(['onWillBeginStep', 'onDidFinishStep']) as IAgentLoopService['hooks'];
   const queue = new StepRequestQueue(); const errorHandlers = registry(); const launches: number[] = []; const cancels: { turnId?: number; reason?: unknown }[] = [];
   let active: Turn | undefined; let nextId = typeof options.currentId === 'number' ? options.currentId : 0;
+  let finishTurn: ((result: TurnResult) => void) | undefined;
   const startTurn = () => {
     const turn = makeTurn(nextId++);
-    const result = options.pendingTurnResult === true ? new Promise<never>(() => {}) : turn.result;
+    const result = options.pendingTurnResult === true
+      ? new Promise<TurnResult>((resolve) => { finishTurn = resolve; })
+      : turn.result;
     const configured = { ...turn, result };
     launches.push(configured.id); active = configured; return configured;
   };
   const stub: StubLoop = {
     _serviceBrand: undefined, hooks, queue, launches, cancels, startTurn,
+    finishActive(result?: TurnResult) {
+      finishTurn?.(result ?? { type: 'completed', steps: 0, truncated: false });
+      finishTurn = undefined;
+      active = undefined;
+    },
     enqueue(request, enqueueOptions) {
       let turn = active;
       if (request.admission === 'newTurn' || (request.admission === 'activeOrNewTurn' && turn === undefined)) turn = startTurn();
@@ -92,5 +101,37 @@ export async function runWillBeginStepHooks(
   });
 }
 export type StubWire = IWireService & { readonly ops: readonly Op[]; readonly steered: readonly { readonly input: readonly ContentPart[]; readonly origin?: PromptOrigin }[] };
-export function stubWire(): StubWire { const ops: Op[] = []; const steered: { input: readonly ContentPart[]; origin?: PromptOrigin }[] = []; return { _serviceBrand: undefined, hooks: createHooks(['onDidRestore']), ops, steered, dispatch: (...incoming: Op[]) => { for (const op of incoming) { ops.push(op); if (op.type === 'turn.steer') steered.push(op.payload as never); } }, replay: async () => {}, signal: () => {}, flush: async () => {}, getModel: () => ({}), subscribe: () => toDisposable(() => {}), onEmission: () => toDisposable(() => {}) } as unknown as StubWire; }
+export function stubWire(): StubWire {
+  const ops: Op[] = [];
+  const steered: { input: readonly ContentPart[]; origin?: PromptOrigin }[] = [];
+  const models = new Map<object, unknown>();
+  const getModel = <S>(model: ModelDef<S>): S => {
+    let state = models.get(model);
+    if (state === undefined) {
+      state = model.initial();
+      models.set(model, state);
+    }
+    return state as S;
+  };
+  return {
+    _serviceBrand: undefined,
+    hooks: createHooks(['onDidRestore']),
+    ops,
+    steered,
+    dispatch: (...incoming: Op[]) => {
+      for (const op of incoming) {
+        ops.push(op);
+        const state = getModel(op.descriptor.model);
+        models.set(op.descriptor.model, op.descriptor.apply(state, op.payload));
+        if (op.type === 'turn.steer') steered.push(op.payload as never);
+      }
+    },
+    replay: async () => {},
+    signal: () => {},
+    flush: async () => {},
+    getModel,
+    subscribe: () => toDisposable(() => {}),
+    onEmission: () => toDisposable(() => {}),
+  } as unknown as StubWire;
+}
 export function stubToolExecutor(): IAgentToolExecutorService { return { _serviceBrand: undefined, execute: async function* () {}, onBeforeExecuteTool: Event.None as Event<BeforeToolExecuteEvent>, onWillExecuteTool: Event.None as Event<WillExecuteToolEvent>, hooks: { onDidExecuteTool: new OrderedHookSlot<ToolDidExecuteContext>() }, recordDupType: () => {}, registerToolCallGuard: () => ({ dispose() {} }), registerUnavailableToolDescriber: () => ({ dispose() {} }), registerMissingToolDescriber: () => ({ dispose() {} }) }; }
diff --git a/packages/agent-core-v2/test/agent/media/image-compress.test.ts b/packages/agent-core-v2/test/agent/media/image-compress.test.ts
index eec30746360..8c2a28c0352 100644
--- a/packages/agent-core-v2/test/agent/media/image-compress.test.ts
+++ b/packages/agent-core-v2/test/agent/media/image-compress.test.ts
@@ -59,6 +59,7 @@ import {
   normalizeImageMime,
   unsupportedImageMimeFromUrl,
 } from '#/agent/media/image-format-policy';
+import { buildDaemonFileUrl } from '#/agent/media/mediaRef';
 
 
 async function solidPng(width: number, height: number, color = 0x3366ccff): Promise<Uint8Array> {
@@ -767,6 +768,21 @@ describe('gateImageFormatParts', () => {
     }
   });
 
+  it('passes daemon file references (kimi-file://) through untouched', () => {
+    const fileId = 'f_9b2f7c1e4a2d4f3a8c1e0b6d5a493827';
+    // A daemon reference carries no extension for the gate to reject — the
+    // resolver sniffs the real bytes downstream, so the reference survives
+    // as-is, including a legacy `?path=` query whose suffix (`.heic`) a remote
+    // URL would be rejected for.
+    for (const url of [
+      buildDaemonFileUrl(fileId),
+      `kimi-file://${fileId}?path=${encodeURIComponent('/tmp/upload/photo.heic')}`,
+    ]) {
+      const part = { type: 'image_url' as const, imageUrl: { url } };
+      expect(gateImageFormatParts([part])).toEqual([part]);
+    }
+  });
+
   it('drops a malformed data URL instead of letting it poison the session', () => {
     const cases = [
       'data:image/avif',
diff --git a/packages/agent-core-v2/test/agent/media/mediaRef.test.ts b/packages/agent-core-v2/test/agent/media/mediaRef.test.ts
new file mode 100644
index 00000000000..88cab60e511
--- /dev/null
+++ b/packages/agent-core-v2/test/agent/media/mediaRef.test.ts
@@ -0,0 +1,190 @@
+/**
+ * `agent/media` mediaRef — media classification, daemon file references,
+ * and media path tags.
+ *
+ *   - suffix / MIME / content-part classification (`mediaKindFor*` /
+ *     `mediaKindOfPart`)
+ *   - `kimi-file://` daemon file URL build/parse round-trips
+ *   - `<image|video|audio|file path="…">` tag emission and matching,
+ *     including the legacy no-closing-tag and extra-attribute shapes
+ */
+
+import { describe, expect, it } from 'vitest';
+
+import type { ContentPart } from '#/kosong/contract/message';
+import {
+  AUDIO_MIME_BY_SUFFIX,
+  IMAGE_MIME_BY_SUFFIX,
+  VIDEO_MIME_BY_SUFFIX,
+  buildDaemonFileUrl,
+  buildMediaPathTag,
+  daemonFileRefFromPart,
+  isDaemonFileUrl,
+  matchMediaPathTags,
+  matchSingleMediaPathTag,
+  mediaKindForMime,
+  mediaKindForPath,
+  mediaKindOfPart,
+  parseDaemonFileUrl,
+} from '#/agent/media/mediaRef';
+
+describe('media kind classification', () => {
+  it('classifies paths by suffix, case-insensitively', () => {
+    expect(mediaKindForPath('/a/b/shot.PNG')).toBe('image');
+    expect(mediaKindForPath('clip.mp4')).toBe('video');
+    expect(mediaKindForPath('song.MP3')).toBe('audio');
+    expect(mediaKindForPath('/a/b/track.weba')).toBe('audio');
+    expect(mediaKindForPath('/a.b/clip')).toBeUndefined();
+    expect(mediaKindForPath('/a/shot.')).toBeUndefined();
+    expect(mediaKindForPath('notes.txt')).toBeUndefined();
+  });
+
+  it('classifies MIME types, ignoring case and parameters', () => {
+    expect(mediaKindForMime('image/png')).toBe('image');
+    expect(mediaKindForMime(' Image/JPEG ')).toBe('image');
+    expect(mediaKindForMime('video/mp4; codecs=avc1')).toBe('video');
+    expect(mediaKindForMime('audio/mpeg')).toBe('audio');
+    expect(mediaKindForMime(' Audio/OGG; codecs=opus ')).toBe('audio');
+    expect(mediaKindForMime('application/pdf')).toBeUndefined();
+    expect(mediaKindForMime('text/plain')).toBeUndefined();
+  });
+
+  it('classifies content parts by their type', () => {
+    const image: ContentPart = { type: 'image_url', imageUrl: { url: 'https://x/y.png' } };
+    const video: ContentPart = { type: 'video_url', videoUrl: { url: 'https://x/y.mp4' } };
+    const audio: ContentPart = { type: 'audio_url', audioUrl: { url: 'https://x/y.mp3' } };
+    const text: ContentPart = { type: 'text', text: 'hi' };
+    expect(mediaKindOfPart(image)).toBe('image');
+    expect(mediaKindOfPart(video)).toBe('video');
+    expect(mediaKindOfPart(audio)).toBe('audio');
+    expect(mediaKindOfPart(text)).toBeUndefined();
+  });
+
+  it('keeps the suffix tables mapping to the expected MIME families', () => {
+    expect(IMAGE_MIME_BY_SUFFIX['.png']).toBe('image/png');
+    expect(VIDEO_MIME_BY_SUFFIX['.mkv']).toBe('video/x-matroska');
+    expect(AUDIO_MIME_BY_SUFFIX['.mp3']).toBe('audio/mpeg');
+    expect(AUDIO_MIME_BY_SUFFIX['.weba']).toBe('audio/webm');
+  });
+});
+
+describe('daemon file URL', () => {
+  it('builds and parses a bare reference', () => {
+    expect(buildDaemonFileUrl('file_1')).toBe('kimi-file://file_1');
+    expect(parseDaemonFileUrl('kimi-file://file_1')).toEqual({ fileId: 'file_1' });
+  });
+
+  it('strips a legacy `?path=` query at parse time', () => {
+    expect(parseDaemonFileUrl('kimi-file://file_1?path=%2Fa%20b%2Fclip.mp4')).toEqual({
+      fileId: 'file_1',
+    });
+    expect(parseDaemonFileUrl('kimi-file://file_1?path=')).toEqual({ fileId: 'file_1' });
+    expect(parseDaemonFileUrl('kimi-file://file_1?path=%E0%A4%A')).toEqual({ fileId: 'file_1' });
+  });
+
+  it('rejects non-daemon URLs and empty file ids', () => {
+    expect(isDaemonFileUrl('kimi-file://file_1')).toBe(true);
+    expect(isDaemonFileUrl('ms://file_1')).toBe(false);
+    expect(parseDaemonFileUrl('ms://prov-1')).toBeUndefined();
+    expect(parseDaemonFileUrl('data:video/mp4;base64,AAAA')).toBeUndefined();
+    expect(parseDaemonFileUrl('https://example.com/clip.mp4')).toBeUndefined();
+    expect(parseDaemonFileUrl('kimi-file://')).toBeUndefined();
+    expect(parseDaemonFileUrl('kimi-file://?path=%2Fa')).toBeUndefined();
+  });
+
+  it('extracts references from media parts with the part-implied kind', () => {
+    const url = buildDaemonFileUrl('file_1');
+    expect(
+      daemonFileRefFromPart({ type: 'image_url', imageUrl: { url } }),
+    ).toEqual({ kind: 'image', ref: { fileId: 'file_1' } });
+    expect(
+      daemonFileRefFromPart({ type: 'video_url', videoUrl: { url } }),
+    ).toEqual({ kind: 'video', ref: { fileId: 'file_1' } });
+    expect(
+      daemonFileRefFromPart({ type: 'image_url', imageUrl: { url: 'data:image/png;base64,AA' } }),
+    ).toBeUndefined();
+    expect(daemonFileRefFromPart({ type: 'text', text: url })).toBeUndefined();
+  });
+});
+
+describe('media path tags', () => {
+  it('round-trips through build and match', () => {
+    const text = `before ${buildMediaPathTag('image', '/cache/a b.png')} after`;
+    expect(text).toBe('before <image path="/cache/a b.png"></image> after');
+    expect(matchMediaPathTags(text)).toEqual([
+      {
+        kind: 'image',
+        path: '/cache/a b.png',
+        index: 7,
+        text: '<image path="/cache/a b.png"></image>',
+      },
+    ]);
+  });
+
+  it('escapes and unescapes attribute entities', () => {
+    const tag = buildMediaPathTag('video', '/a & "b"/<c>.mp4');
+    expect(tag).toBe('<video path="/a &amp; &quot;b&quot;/&lt;c&gt;.mp4"></video>');
+    expect(matchMediaPathTags(tag)[0]?.path).toBe('/a & "b"/<c>.mp4');
+  });
+
+  it('tolerates extra attributes and a missing closing tag', () => {
+    expect(matchMediaPathTags('<image path="/a.png" content_type="image/png">')).toEqual([
+      {
+        kind: 'image',
+        path: '/a.png',
+        index: 0,
+        text: '<image path="/a.png" content_type="image/png">',
+      },
+    ]);
+    expect(matchMediaPathTags('<video path="/b.mp4">')[0]?.path).toBe('/b.mp4');
+  });
+
+  it('matches every tag in order across kinds', () => {
+    const tags = matchMediaPathTags(
+      '<image path="/a.png"></image> text <video path="/b.mp4"></video> <audio path="/c.mp3"></audio> <file path="/d.pdf"></file>',
+    );
+    expect(tags.map((t) => t.kind)).toEqual(['image', 'video', 'audio', 'file']);
+    expect(tags.map((t) => t.path)).toEqual(['/a.png', '/b.mp4', '/c.mp3', '/d.pdf']);
+  });
+
+  it('round-trips an audio tag through build and match', () => {
+    const tag = buildMediaPathTag('audio', '/cache/a b.mp3');
+    expect(tag).toBe('<audio path="/cache/a b.mp3"></audio>');
+    expect(matchMediaPathTags(tag)).toEqual([
+      { kind: 'audio', path: '/cache/a b.mp3', index: 0, text: tag },
+    ]);
+  });
+
+  it('ignores lookalikes without a path attribute', () => {
+    expect(matchMediaPathTags('<image src="/a.png">')).toEqual([]);
+    expect(matchMediaPathTags('path="/a.png"')).toEqual([]);
+  });
+});
+
+describe('matchSingleMediaPathTag', () => {
+  it('matches a text that is exactly one tag', () => {
+    expect(matchSingleMediaPathTag('<image path="/a.png"></image>')).toEqual({
+      kind: 'image',
+      path: '/a.png',
+      index: 0,
+      text: '<image path="/a.png"></image>',
+    });
+    expect(matchSingleMediaPathTag('  <video path="/b.mp4">\n')).toMatchObject({
+      kind: 'video',
+      path: '/b.mp4',
+    });
+    expect(matchSingleMediaPathTag('<image path="/a.png" content_type="image/png">')).toMatchObject(
+      { kind: 'image', path: '/a.png' },
+    );
+  });
+
+  it('rejects tags embedded in user text and multi-tag text', () => {
+    expect(matchSingleMediaPathTag('look <image path="/a.png"></image>')).toBeUndefined();
+    expect(matchSingleMediaPathTag('<image path="/a.png"></image> please')).toBeUndefined();
+    expect(
+      matchSingleMediaPathTag('<image path="/a.png"></image><image path="/b.png"></image>'),
+    ).toBeUndefined();
+    expect(matchSingleMediaPathTag('plain text')).toBeUndefined();
+  });
+});
+
diff --git a/packages/agent-core-v2/test/agent/media/mediaResolver.test.ts b/packages/agent-core-v2/test/agent/media/mediaResolver.test.ts
new file mode 100644
index 00000000000..bb208876932
--- /dev/null
+++ b/packages/agent-core-v2/test/agent/media/mediaResolver.test.ts
@@ -0,0 +1,828 @@
+import { mkdtemp, mkdir, readdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { Readable } from 'node:stream';
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { DisposableStore } from '#/_base/di/lifecycle';
+import {
+  ScopeActivation,
+  _clearScopedRegistryForTests,
+  registerScopedService,
+} from '#/_base/di/scope';
+import { LifecycleScope } from '#/app/scopes';
+import { createScopedTestHost, createServices, stubPair } from '#/_base/di/test';
+import { buildKimiFileUrl } from '#/agent/media/kimiFileUrl';
+import { IAgentMediaResolverService } from '#/agent/media/mediaResolver';
+import { AgentMediaResolverService } from '#/agent/media/mediaResolverService';
+import { ISessionMediaStore } from '#/agent/media/sessionMediaStore';
+import { IAgentVideoResolverService } from '#/agent/media/videoResolver';
+import { IAgentStateService } from '#/agent/state/agentState';
+import { AgentStateService } from '#/agent/state/agentStateService';
+import { type GetResult, IFileService } from '#/app/file/fileService';
+import { ITelemetryService } from '#/app/telemetry/telemetry';
+import type { ModelCapability } from '#/kosong/contract/capability';
+import type { ContentPart, Message, VideoURLPart } from '#/kosong/contract/message';
+import type { ModelRequester } from '#/kosong/model/modelRequester';
+import type { Protocol } from '#/kosong/protocol/protocol';
+import { IBlobStore } from '#/persistence/interface/blobStore';
+
+import { registerStateServices } from '../../state/stubs';
+
+const FILE_ID = 'file_abc';
+const VIDEO_BYTES = Buffer.from('tiny fake mp4 bytes');
+const PNG_BYTES = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0x00]);
+const BMP_BYTES = Buffer.from([0x42, 0x4d, 0x46, 0x00, 0x00, 0x00, 0x00, 0x00]);
+const MP4_MAGIC_BYTES = Buffer.from([
+  0x00, 0x00, 0x00, 0x18, 0x66, 0x74, 0x79, 0x70, 0x69, 0x73, 0x6f, 0x6d, 0x00, 0x00, 0x00, 0x00,
+]);
+const IMAGE_UNAVAILABLE_TEXT = '[image omitted: the uploaded file is no longer available]';
+const VIDEO_UNAVAILABLE_TEXT = '[video omitted: the uploaded file is no longer available]';
+const VIDEO_TAG = '<video path="/cache/file_abc.mp4"></video>';
+const IMAGE_TAG = '<image path="/cache/file_abc.png"></image>';
+const PNG_DATA_URL = `data:image/png;base64,${PNG_BYTES.toString('base64')}`;
+
+function videoMessage(url: string): Message {
+  return { role: 'user', content: [{ type: 'video_url', videoUrl: { url } }], toolCalls: [] };
+}
+
+function imageMessage(url: string, ...before: ContentPart[]): Message {
+  return {
+    role: 'user',
+    content: [...before, { type: 'image_url', imageUrl: { url } }],
+    toolCalls: [],
+  };
+}
+
+function firstPart(messages: readonly Message[]) {
+  return messages[0]!.content[0]!;
+}
+
+function fileService(files: Map<string, { name: string; bytes: Buffer }>): IFileService {
+  return {
+    _serviceBrand: undefined,
+    save: async () => {
+      throw new Error('unused');
+    },
+    delete: async () => {},
+    get: async (fileId): Promise<GetResult> => {
+      const file = files.get(fileId);
+      if (file === undefined) throw new Error(`file not found: ${fileId}`);
+      return {
+        meta: {
+          id: fileId,
+          name: file.name,
+          media_type: 'video/mp4',
+          size: file.bytes.length,
+          created_at: new Date(0).toISOString(),
+        },
+        stream: () => Readable.from([file.bytes]),
+      };
+    },
+  };
+}
+
+function countingFileService(files: Map<string, { name: string; bytes: Buffer }>): {
+  service: IFileService;
+  readonly gets: number;
+} {
+  const base = fileService(files);
+  let gets = 0;
+  return {
+    service: {
+      ...base,
+      get: async (fileId) => {
+        gets++;
+        return base.get(fileId);
+      },
+    },
+    get gets() {
+      return gets;
+    },
+  };
+}
+
+function blobStore(): IBlobStore {
+  const data = new Map<string, Uint8Array>();
+  return {
+    _serviceBrand: undefined,
+    put: async (scope, key, bytes) => {
+      data.set(`${scope}/${key}`, bytes);
+    },
+    putStream: async (scope, key, source) => {
+      const chunks: Uint8Array[] = [];
+      for await (const chunk of source) chunks.push(chunk);
+      data.set(`${scope}/${key}`, Buffer.concat(chunks));
+    },
+    get: async (scope, key) => data.get(`${scope}/${key}`),
+    getStream: async function* () {},
+    has: async (scope, key) => data.has(`${scope}/${key}`),
+    delete: async (scope, key) => {
+      data.delete(`${scope}/${key}`);
+    },
+    list: async () => [],
+  };
+}
+
+const telemetry = { track2: () => {} } as unknown as ITelemetryService;
+
+/**
+ * Store stub over a plain dir: the canonical copy exists only when a test
+ * plants it (mirrors the real store's by-id listing without materialization).
+ */
+function stubMediaStore(sessionDir = '/nonexistent-session'): ISessionMediaStore {
+  return {
+    _serviceBrand: undefined,
+    pathFor: (fileId, ext) => join(sessionDir, 'media', `${fileId}${ext}`),
+    resolveDisplayPath: async (fileId) => {
+      const dir = join(sessionDir, 'media');
+      const keys: string[] = await readdir(dir).catch(() => []);
+      const key = keys.find((name) => name === fileId || name.startsWith(`${fileId}.`));
+      return key === undefined ? undefined : join(dir, key);
+    },
+    read: async () => undefined,
+    open: async () => undefined,
+    materialize: async () => {
+      throw new Error('unused');
+    },
+  };
+}
+
+let sessionDir: string;
+
+async function plantCanonical(fileId: string, ext: string, bytes: Buffer): Promise<string> {
+  const canonical = join(sessionDir, 'media', `${fileId}${ext}`);
+  await mkdir(join(sessionDir, 'media'), { recursive: true });
+  await writeFile(canonical, bytes);
+  return canonical;
+}
+
+function requester(opts: {
+  videoIn?: boolean;
+  imageIn?: boolean;
+  protocol?: Protocol;
+  providerType?: string;
+  uploadVideo?: ModelRequester['uploadVideo'];
+}): ModelRequester {
+  return {
+    model: {
+      id: 'm',
+      name: 'stub',
+      aliases: [],
+      protocol: opts.protocol ?? 'openai',
+      headers: {},
+      capabilities: {
+        video_in: opts.videoIn ?? true,
+        image_in: opts.imageIn ?? true,
+      } as unknown as ModelCapability,
+      maxContextSize: 1000,
+      alwaysThinking: false,
+      providerName: 'p',
+      providerType: opts.providerType ?? 'kimi',
+      authProvider: {} as never,
+    },
+    request: () => {
+      throw new Error('unused');
+    },
+    uploadVideo: opts.uploadVideo,
+  };
+}
+
+function msPart(id: string): VideoURLPart {
+  return { type: 'video_url', videoUrl: { url: `ms://${id}`, id } };
+}
+
+let disposables: DisposableStore;
+
+beforeEach(async () => {
+  disposables = new DisposableStore();
+  sessionDir = await mkdtemp(join(tmpdir(), 'media-resolver-'));
+});
+
+afterEach(async () => {
+  disposables.dispose();
+  await rm(sessionDir, { recursive: true, force: true });
+});
+
+function resolver(
+  files: Map<string, { name: string; bytes: Buffer }>,
+  sessionDir?: string,
+  mediaStore: ISessionMediaStore = stubMediaStore(sessionDir),
+): IAgentMediaResolverService {
+  const ix = createServices(disposables, {
+    base: [registerStateServices],
+    additionalServices: (reg) => {
+      reg.defineInstance(IFileService, fileService(files));
+      reg.defineInstance(IBlobStore, blobStore());
+      reg.defineInstance(ITelemetryService, telemetry);
+      reg.defineInstance(ISessionMediaStore, mediaStore);
+      reg.define(IAgentMediaResolverService, AgentMediaResolverService);
+    },
+  });
+  return ix.get(IAgentMediaResolverService);
+}
+
+describe('AgentMediaResolverService video strategy', () => {
+  it('uploads a kimi-file video once and reuses the cached reference on later steps', async () => {
+    const upload = vi.fn(async (): Promise<VideoURLPart> => msPart('prov-1'));
+    const res = resolver(new Map([[FILE_ID, { name: 'clip.mp4', bytes: VIDEO_BYTES }]]));
+    const req = requester({ uploadVideo: upload });
+    const message = videoMessage(buildKimiFileUrl(FILE_ID));
+
+    const first = await res.resolve([message], req);
+    const second = await res.resolve([message], req);
+
+    expect(firstPart(first)).toEqual(msPart('prov-1'));
+    expect(firstPart(second)).toEqual(msPart('prov-1'));
+    expect(upload).toHaveBeenCalledTimes(1);
+
+    // A message without a kimi-file reference passes through untouched.
+    const plain = [videoMessage('ms://already-uploaded')];
+    expect(await res.resolve(plain, req)).toBe(plain);
+  });
+
+  it('degrades to the path tag when the current model cannot accept video, ignoring a memoized upload', async () => {
+    const upload = vi.fn(async (): Promise<VideoURLPart> => msPart('prov-1'));
+    const canonical = await plantCanonical(FILE_ID, '.mp4', VIDEO_BYTES);
+    const res = resolver(new Map([[FILE_ID, { name: 'clip.mp4', bytes: VIDEO_BYTES }]]), sessionDir);
+    const message = videoMessage(buildKimiFileUrl(FILE_ID));
+
+    const capable = await res.resolve([message], requester({ uploadVideo: upload }));
+    expect(firstPart(capable)).toEqual(msPart('prov-1'));
+
+    // Same provider, video_in:false: the memoized ms:// part must not leak to
+    // a model that cannot accept video.
+    const incapable = await res.resolve(
+      [message],
+      requester({ videoIn: false, uploadVideo: upload }),
+    );
+    expect(firstPart(incapable)).toEqual({
+      type: 'text',
+      text: `<video path="${canonical}"></video>`,
+    });
+    expect(upload).toHaveBeenCalledTimes(1);
+  });
+
+  it('reuses a persisted upload across resolver instances without re-uploading', async () => {
+    const files = new Map([[FILE_ID, { name: 'clip.mp4', bytes: VIDEO_BYTES }]]);
+    const blobs = blobStore();
+    const message = videoMessage(buildKimiFileUrl(FILE_ID));
+
+    // Two independent instances over one shared blob store: the container
+    // hands out a singleton per token and would share the state service (and
+    // with it the in-memory upload memo), so the persisted-cache path would
+    // never run — direct construction is di-testing.md's two-instance
+    // exception.
+    const upload1 = vi.fn(async (): Promise<VideoURLPart> => msPart('prov-1'));
+    await new AgentMediaResolverService(fileService(files), blobs, telemetry, new AgentStateService(), stubMediaStore()).resolve(
+      [message],
+      requester({ uploadVideo: upload1 }),
+    );
+
+    const upload2 = vi.fn(async (): Promise<VideoURLPart> => msPart('prov-2'));
+    const out = await new AgentMediaResolverService(fileService(files), blobs, telemetry, new AgentStateService(), stubMediaStore()).resolve(
+      [message],
+      requester({ uploadVideo: upload2 }),
+    );
+
+    expect(firstPart(out)).toEqual(msPart('prov-1'));
+    expect(upload1).toHaveBeenCalledTimes(1);
+    expect(upload2).not.toHaveBeenCalled();
+  });
+
+  type TagCase = {
+    name: string;
+    files: Map<string, { name: string; bytes: Buffer }>;
+    fileId: string;
+    req: (upload: ModelRequester['uploadVideo']) => ModelRequester;
+  };
+
+  it.each<TagCase>([
+    {
+      name: 'the model cannot ingest video',
+      files: new Map([[FILE_ID, { name: 'clip.mp4', bytes: VIDEO_BYTES }]]),
+      fileId: FILE_ID,
+      req: (upload) => requester({ videoIn: false, uploadVideo: upload }),
+    },
+    {
+      name: 'a no-upload provider whose wire drops inline video (openai family)',
+      files: new Map([[FILE_ID, { name: 'clip.mp4', bytes: VIDEO_BYTES }]]),
+      fileId: FILE_ID,
+      req: () => requester({ protocol: 'openai', uploadVideo: undefined }),
+    },
+    {
+      name: 'the bytes do not sniff as a video',
+      files: new Map([[FILE_ID, { name: 'clip.mp4', bytes: PNG_BYTES }]]),
+      fileId: FILE_ID,
+      req: (upload) => requester({ uploadVideo: upload }),
+    },
+    {
+      name: 'the reference is stale',
+      files: new Map(),
+      fileId: 'missing',
+      req: (upload) => requester({ uploadVideo: upload }),
+    },
+  ])('degrades when $name', async ({ files, fileId, req }) => {
+    const upload = vi.fn();
+    const canonical =
+      fileId === FILE_ID ? await plantCanonical(FILE_ID, '.mp4', VIDEO_BYTES) : undefined;
+    const out = await resolver(files, sessionDir).resolve(
+      [videoMessage(buildKimiFileUrl(fileId))],
+      req(upload),
+    );
+
+    expect(firstPart(out)).toEqual({
+      type: 'text',
+      text: canonical === undefined ? VIDEO_UNAVAILABLE_TEXT : `<video path="${canonical}"></video>`,
+    });
+    expect(upload).not.toHaveBeenCalled();
+  });
+
+  it('rethrows an auth failure so it can drive credential refresh', async () => {
+    const upload = vi.fn(async () => {
+      throw Object.assign(new Error('unauthorized'), { statusCode: 401 });
+    });
+    const res = resolver(new Map([[FILE_ID, { name: 'clip.mp4', bytes: VIDEO_BYTES }]]));
+
+    await expect(
+      res.resolve([videoMessage(buildKimiFileUrl(FILE_ID))], requester({ uploadVideo: upload })),
+    ).rejects.toThrow('unauthorized');
+  });
+
+  it('rethrows a cancelled upload without memoizing the fallback', async () => {
+    const controller = new AbortController();
+    const interrupted = vi.fn(async () => {
+      controller.abort();
+      throw new Error('socket closed');
+    });
+    const res = resolver(new Map([[FILE_ID, { name: 'clip.mp4', bytes: VIDEO_BYTES }]]));
+    const message = videoMessage(buildKimiFileUrl(FILE_ID));
+
+    await expect(
+      res.resolve([message], requester({ uploadVideo: interrupted }), controller.signal),
+    ).rejects.toThrow('socket closed');
+
+    const retry = vi.fn(async (): Promise<VideoURLPart> => msPart('prov-1'));
+    const out = await res.resolve([message], requester({ uploadVideo: retry }));
+    expect(firstPart(out)).toEqual(msPart('prov-1'));
+    expect(retry).toHaveBeenCalledTimes(1);
+  });
+
+  it('retries the upload on a later step after a transient failure instead of freezing the tag', async () => {
+    let uploadCalls = 0;
+    const upload = vi.fn(async (): Promise<VideoURLPart> => {
+      uploadCalls += 1;
+      if (uploadCalls === 1) throw new Error('files endpoint unavailable');
+      return msPart('prov-1');
+    });
+    const canonical = await plantCanonical(FILE_ID, '.mp4', VIDEO_BYTES);
+    const res = resolver(new Map([[FILE_ID, { name: 'clip.mp4', bytes: VIDEO_BYTES }]]), sessionDir);
+    const message = videoMessage(buildKimiFileUrl(FILE_ID));
+    const req = requester({ uploadVideo: upload });
+
+    const failed = await res.resolve([message], req);
+    expect(firstPart(failed)).toEqual({
+      type: 'text',
+      text: `<video path="${canonical}"></video>`,
+    });
+
+    const retried = await res.resolve([message], req);
+    expect(firstPart(retried)).toEqual(msPart('prov-1'));
+    expect(upload).toHaveBeenCalledTimes(2);
+  });
+
+  it('emits an unavailable placeholder when a stale reference has no canonical copy', async () => {
+    const out = await resolver(new Map()).resolve(
+      [videoMessage(buildKimiFileUrl('missing'))],
+      requester({ uploadVideo: vi.fn() }),
+    );
+
+    expect(firstPart(out)).toEqual({
+      type: 'text',
+      text: VIDEO_UNAVAILABLE_TEXT,
+    });
+  });
+});
+
+describe('AgentMediaResolverService canonical session bytes', () => {
+  it.each([
+    {
+      kind: 'video',
+      bytes: VIDEO_BYTES,
+      fileName: `${FILE_ID}.mp4`,
+      message: videoMessage(buildKimiFileUrl(FILE_ID)),
+      expected: msPart('prov-1'),
+      uploads: 1,
+    },
+    {
+      kind: 'image',
+      bytes: PNG_BYTES,
+      fileName: `${FILE_ID}.png`,
+      message: imageMessage(buildKimiFileUrl(FILE_ID)),
+      expected: { type: 'image_url', imageUrl: { url: PNG_DATA_URL } },
+      uploads: 0,
+    },
+  ])(
+    'reads canonical session bytes for a $kind after the transient upload is released',
+    async ({ bytes, fileName, message, expected, uploads }) => {
+      const mediaStore = stubMediaStore();
+      mediaStore.read = async () => ({ data: bytes, name: fileName });
+      const res = resolver(new Map(), undefined, mediaStore);
+      const upload = vi.fn(async (): Promise<VideoURLPart> => msPart('prov-1'));
+
+      const out = await res.resolve([message], requester({ uploadVideo: upload }));
+
+      expect(upload).toHaveBeenCalledTimes(uploads);
+      expect(firstPart(out)).toEqual(expected);
+    },
+  );
+});
+
+describe('AgentMediaResolverService image strategy', () => {
+  it('inlines a daemon-ref image as a canonical base64 data url, leaving other parts untouched', async () => {
+    const res = resolver(new Map([[FILE_ID, { name: 'pic.png', bytes: PNG_BYTES }]]));
+    const tagPart: ContentPart = { type: 'text', text: IMAGE_TAG };
+    const remotePart: ContentPart = {
+      type: 'image_url',
+      imageUrl: { url: 'https://example.com/pic.png' },
+    };
+    const message = imageMessage(buildKimiFileUrl(FILE_ID), tagPart, remotePart);
+
+    const out = await res.resolve([message], requester({}));
+
+    expect(out[0]!.content).toEqual([
+      tagPart,
+      remotePart,
+      { type: 'image_url', imageUrl: { url: PNG_DATA_URL } },
+    ]);
+  });
+
+  it('rethrows a cancelled image read instead of degrading to a tag', async () => {
+    const controller = new AbortController();
+    // The stream failure is deliberately NOT abort-shaped: the aborted signal
+    // alone must decide cancellation, mirroring the video upload rule.
+    const files: IFileService = {
+      _serviceBrand: undefined,
+      save: async () => {
+        throw new Error('unused');
+      },
+      delete: async () => {},
+      get: async (fileId): Promise<GetResult> => ({
+        meta: {
+          id: fileId,
+          name: 'pic.png',
+          media_type: 'image/png',
+          size: PNG_BYTES.length,
+          created_at: new Date(0).toISOString(),
+        },
+        stream: () =>
+          Readable.from(
+            (async function* () {
+              yield PNG_BYTES;
+              controller.abort();
+              throw new Error('socket closed');
+            })(),
+          ),
+      }),
+    };
+    const res = new AgentMediaResolverService(
+      files,
+      blobStore(),
+      telemetry,
+      new AgentStateService(),
+      stubMediaStore(),
+    );
+
+    await expect(
+      res.resolve(
+        [imageMessage(buildKimiFileUrl(FILE_ID))],
+        requester({}),
+        controller.signal,
+      ),
+    ).rejects.toMatchObject({ name: 'AbortError' });
+  });
+
+  it.each([
+    {
+      name: 'the model cannot ingest images',
+      files: new Map([[FILE_ID, { name: 'pic.png', bytes: PNG_BYTES }]]),
+      fileId: FILE_ID,
+      imageIn: false,
+    },
+    {
+      name: 'the reference is stale',
+      files: new Map<string, { name: string; bytes: Buffer }>(),
+      fileId: 'missing',
+      imageIn: true,
+    },
+    {
+      name: 'the bytes sniff as a non-image media type',
+      files: new Map([[FILE_ID, { name: 'pic.png', bytes: MP4_MAGIC_BYTES }]]),
+      fileId: FILE_ID,
+      imageIn: true,
+    },
+    {
+      name: 'the bytes sniff as an unaccepted image mime',
+      files: new Map([[FILE_ID, { name: 'pic.bmp', bytes: BMP_BYTES }]]),
+      fileId: FILE_ID,
+      imageIn: true,
+    },
+  ])('degrades when $name', async ({ files, fileId, imageIn }) => {
+    const canonical =
+      fileId === FILE_ID ? await plantCanonical(FILE_ID, '.png', PNG_BYTES) : undefined;
+    const message = imageMessage(buildKimiFileUrl(fileId));
+
+    const out = await resolver(files, sessionDir).resolve([message], requester({ imageIn }));
+
+    expect(out[0]!.content).toEqual([
+      {
+        type: 'text',
+        text:
+          canonical === undefined ? IMAGE_UNAVAILABLE_TEXT : `<image path="${canonical}"></image>`,
+      },
+    ]);
+  });
+
+  it.each([
+    {
+      name: 'the model cannot ingest images and there is no canonical copy',
+      files: new Map([[FILE_ID, { name: 'pic.png', bytes: PNG_BYTES }]]),
+      url: buildKimiFileUrl(FILE_ID),
+      imageIn: false,
+      expected: IMAGE_UNAVAILABLE_TEXT,
+    },
+    {
+      name: 'a bare stale reference has no canonical copy',
+      files: new Map<string, { name: string; bytes: Buffer }>(),
+      url: buildKimiFileUrl('missing'),
+      imageIn: true,
+      expected: IMAGE_UNAVAILABLE_TEXT,
+    },
+  ])('emits the fallback text part when $name', async ({ files, url, imageIn, expected }) => {
+    const out = await resolver(files).resolve([imageMessage(url)], requester({ imageIn }));
+
+    expect(out[0]!.content).toEqual([{ type: 'text', text: expected }]);
+  });
+
+  it('memoizes an inlined image across resolves without re-reading the bytes', async () => {
+    const files = new Map([[FILE_ID, { name: 'pic.png', bytes: PNG_BYTES }]]);
+    const counting = countingFileService(files);
+    const res = new AgentMediaResolverService(
+      counting.service,
+      blobStore(),
+      telemetry,
+      new AgentStateService(),
+      stubMediaStore(),
+    );
+    const message = imageMessage(buildKimiFileUrl(FILE_ID));
+    const expected = { type: 'image_url', imageUrl: { url: PNG_DATA_URL } };
+
+    const first = await res.resolve([message], requester({}));
+    // The memo survives the transient upload's release and is
+    // requester-independent: a later step on another provider / protocol
+    // reuses the same inline part.
+    files.delete(FILE_ID);
+    const second = await res.resolve(
+      [message],
+      requester({ providerType: 'other', protocol: 'anthropic' }),
+    );
+
+    expect(firstPart(first)).toEqual(expected);
+    expect(firstPart(second)).toEqual(expected);
+    expect(counting.gets).toBe(1);
+  });
+
+  it('re-reads an oversized image instead of memoizing its base64', async () => {
+    const bigBytes = Buffer.concat([PNG_BYTES, Buffer.alloc(8 * 1024 * 1024)]);
+    const files = new Map([[FILE_ID, { name: 'pic.png', bytes: bigBytes }]]);
+    const counting = countingFileService(files);
+    const res = new AgentMediaResolverService(
+      counting.service,
+      blobStore(),
+      telemetry,
+      new AgentStateService(),
+      stubMediaStore(),
+    );
+    const message = imageMessage(buildKimiFileUrl(FILE_ID));
+
+    const first = await res.resolve([message], requester({}));
+    const second = await res.resolve([message], requester({}));
+
+    expect(firstPart(first)).toEqual(firstPart(second));
+    expect(counting.gets).toBe(2);
+  });
+
+  it('evicts the least-recently-hit memo entry once the total byte budget is exceeded', async () => {
+    // Nine 8MB images overfill the 64MB total budget; each one is under the
+    // per-image cap, so every resolve memoizes.
+    const bigPng = (): Buffer =>
+      Buffer.concat([PNG_BYTES, Buffer.alloc(8 * 1024 * 1024 - PNG_BYTES.length)]);
+    const ids = Array.from({ length: 9 }, (_, i) => `file_${i}`);
+    const files = new Map(ids.map((id) => [id, { name: 'pic.png', bytes: bigPng() }]));
+    const counting = countingFileService(files);
+    const res = new AgentMediaResolverService(
+      counting.service,
+      blobStore(),
+      telemetry,
+      new AgentStateService(),
+      stubMediaStore(),
+    );
+    const req = requester({});
+
+    // Eight entries fill the budget exactly; a hit on file_0 makes it the
+    // most-recently-hit, so the ninth insert evicts file_1 instead.
+    for (const id of ids.slice(0, 8)) {
+      await res.resolve([imageMessage(buildKimiFileUrl(id))], req);
+    }
+    await res.resolve([imageMessage(buildKimiFileUrl('file_0'))], req);
+    await res.resolve([imageMessage(buildKimiFileUrl('file_8'))], req);
+    expect(counting.gets).toBe(9);
+
+    // file_0 survives as a memo hit; the evicted file_1 is re-read.
+    await res.resolve([imageMessage(buildKimiFileUrl('file_0'))], req);
+    expect(counting.gets).toBe(9);
+    await res.resolve([imageMessage(buildKimiFileUrl('file_1'))], req);
+    expect(counting.gets).toBe(10);
+  });
+
+  it.each([
+    {
+      name: 'the model cannot ingest images',
+      present: true,
+      imageIn: false,
+      reads: 1,
+    },
+    {
+      name: 'the bytes are initially unreadable',
+      present: false,
+      imageIn: true,
+      reads: 2,
+    },
+  ])(
+    'does not memoize a degrade when $name, resolving inline once it can',
+    async ({ present, imageIn, reads }) => {
+      const files = new Map<string, { name: string; bytes: Buffer }>();
+      if (present) files.set(FILE_ID, { name: 'pic.png', bytes: PNG_BYTES });
+      const counting = countingFileService(files);
+      const canonical = await plantCanonical(FILE_ID, '.png', PNG_BYTES);
+      const res = new AgentMediaResolverService(
+        counting.service,
+        blobStore(),
+        telemetry,
+        new AgentStateService(),
+        stubMediaStore(sessionDir),
+      );
+      const message = imageMessage(buildKimiFileUrl(FILE_ID));
+
+      const degraded = await res.resolve([message], requester({ imageIn }));
+      if (!present) files.set(FILE_ID, { name: 'pic.png', bytes: PNG_BYTES });
+      const out = await res.resolve([message], requester({}));
+
+      expect(firstPart(degraded)).toEqual({
+        type: 'text',
+        text: `<image path="${canonical}"></image>`,
+      });
+      expect(firstPart(out)).toEqual({ type: 'image_url', imageUrl: { url: PNG_DATA_URL } });
+      expect(counting.gets).toBe(reads);
+    },
+  );
+});
+
+describe('AgentMediaResolverService session-canonical display path', () => {
+  it.each([
+    {
+      name: 'synthesizes the degrade tag from the canonical path when it exists',
+      canonical: true,
+    },
+    {
+      name: 'emits the unavailable placeholder when no canonical copy exists',
+      canonical: false,
+    },
+  ])('$name', async ({ canonical: plant }) => {
+    const canonical = plant ? await plantCanonical(FILE_ID, '.png', PNG_BYTES) : undefined;
+    const message = imageMessage(buildKimiFileUrl(FILE_ID));
+
+    const out = await resolver(new Map(), sessionDir).resolve([message], requester({ imageIn: false }));
+
+    expect(out[0]!.content).toEqual([
+      {
+        type: 'text',
+        text:
+          canonical === undefined ? IMAGE_UNAVAILABLE_TEXT : `<image path="${canonical}"></image>`,
+      },
+    ]);
+  });
+
+  it('refreshes the degrade form when the canonical copy appears', async () => {
+    const res = resolver(new Map(), sessionDir);
+    const message = videoMessage(buildKimiFileUrl(FILE_ID));
+    const req = requester({ videoIn: false });
+
+    const first = await res.resolve([message], req);
+    expect(firstPart(first)).toEqual({ type: 'text', text: VIDEO_UNAVAILABLE_TEXT });
+
+    const canonical = await plantCanonical(FILE_ID, '.mp4', VIDEO_BYTES);
+    const second = await res.resolve([message], req);
+    expect(firstPart(second)).toEqual({ type: 'text', text: `<video path="${canonical}"></video>` });
+  });
+
+  it('keeps a legacy persisted tag as text and degrades the reference with a synthesized tag', async () => {
+    const canonical = await plantCanonical(FILE_ID, '.mp4', VIDEO_BYTES);
+    const message: Message = {
+      role: 'user',
+      toolCalls: [],
+      content: [
+        { type: 'text', text: VIDEO_TAG },
+        { type: 'video_url', videoUrl: { url: buildKimiFileUrl(FILE_ID) } },
+      ],
+    };
+    const out = await resolver(new Map(), sessionDir).resolve(
+      [message],
+      requester({ videoIn: false }),
+    );
+    expect(out[0]!.content).toEqual([
+      { type: 'text', text: VIDEO_TAG },
+      { type: 'text', text: `<video path="${canonical}"></video>` },
+    ]);
+  });
+
+  it('keeps a legacy persisted tag as text when the reference degrades to the placeholder', async () => {
+    const res = resolver(new Map(), sessionDir);
+    const req = requester({ videoIn: false });
+    const bare: Message = {
+      role: 'user',
+      toolCalls: [],
+      content: [
+        { type: 'video_url', videoUrl: { url: buildKimiFileUrl(FILE_ID) } },
+      ],
+    };
+    const first = await res.resolve([bare], req);
+    expect(firstPart(first)).toEqual({ type: 'text', text: VIDEO_UNAVAILABLE_TEXT });
+
+    const withLegacyTag: Message = {
+      role: 'user',
+      toolCalls: [],
+      content: [
+        { type: 'text', text: VIDEO_TAG },
+        { type: 'video_url', videoUrl: { url: buildKimiFileUrl(FILE_ID) } },
+      ],
+    };
+    const second = await res.resolve([withLegacyTag], req);
+    expect(second[0]!.content).toEqual([
+      { type: 'text', text: VIDEO_TAG },
+      { type: 'text', text: VIDEO_UNAVAILABLE_TEXT },
+    ]);
+  });
+});
+
+describe('AgentMediaResolverService scoped registration', () => {
+  let host: ReturnType<typeof createScopedTestHost>;
+
+  beforeEach(() => {
+    _clearScopedRegistryForTests();
+    registerScopedService(
+      LifecycleScope.Agent,
+      IAgentMediaResolverService,
+      AgentMediaResolverService,
+      ScopeActivation.OnScopeCreated,
+      'media',
+    );
+  });
+
+  afterEach(() => {
+    host.dispose();
+  });
+
+  function agentScope(files: Map<string, { name: string; bytes: Buffer }>) {
+    host = createScopedTestHost([
+      stubPair(IFileService, fileService(files)),
+      stubPair(IBlobStore, blobStore()),
+      stubPair(ITelemetryService, telemetry),
+    ]);
+    return host.child(LifecycleScope.Agent, 'main', [
+      stubPair(IAgentStateService, new AgentStateService()),
+      stubPair(ISessionMediaStore, stubMediaStore()),
+    ]);
+  }
+
+  it('resolves the media resolver token to a working instance through the scope tree', async () => {
+    const agent = agentScope(new Map([[FILE_ID, { name: 'pic.png', bytes: PNG_BYTES }]]));
+
+    const svc = agent.accessor.get(IAgentMediaResolverService);
+    const out = await svc.resolve(
+      [imageMessage(buildKimiFileUrl(FILE_ID))],
+      requester({}),
+    );
+
+    expect(firstPart(out)).toEqual({ type: 'image_url', imageUrl: { url: PNG_DATA_URL } });
+  });
+
+  it('resolves the legacy video-resolver alias to the same instance', () => {
+    const agent = agentScope(new Map());
+
+    expect(agent.accessor.get(IAgentVideoResolverService)).toBe(
+      agent.accessor.get(IAgentMediaResolverService),
+    );
+  });
+});
diff --git a/packages/agent-core-v2/test/agent/media/sessionMediaStore.test.ts b/packages/agent-core-v2/test/agent/media/sessionMediaStore.test.ts
new file mode 100644
index 00000000000..ba9b1b02b7b
--- /dev/null
+++ b/packages/agent-core-v2/test/agent/media/sessionMediaStore.test.ts
@@ -0,0 +1,252 @@
+/**
+ * Scenario: session-canonical media persists through the byte-storage boundary.
+ */
+
+import { mkdir, mkdtemp, readdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { Readable } from 'node:stream';
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { DisposableStore } from '#/_base/di/lifecycle';
+import { createServices, type TestInstantiationService } from '#/_base/di/test';
+import { ISessionMediaStore } from '#/agent/media/sessionMediaStore';
+import { SessionMediaStoreService } from '#/agent/media/sessionMediaStoreService';
+import { JsonAtomicDocumentStore } from '#/persistence/backends/node-fs/atomicDocumentStore';
+import { FileStorageService } from '#/persistence/backends/node-fs/fileStorageService';
+import { InMemoryStorageService } from '#/persistence/backends/memory/inMemoryStorageService';
+import { IAtomicDocumentStore } from '#/persistence/interface/atomicDocumentStore';
+import { IFileSystemStorageService } from '#/persistence/interface/storage';
+import { ISessionContext, makeSessionContext } from '#/session/sessionContext/sessionContext';
+
+const BYTES = Buffer.from('media bytes');
+
+function streamOf(bytes: Buffer): () => NodeJS.ReadableStream {
+  return () => Readable.from([bytes]);
+}
+
+describe('SessionMediaStoreService', () => {
+  let disposables: DisposableStore;
+  let ix: TestInstantiationService;
+  let homeDir: string;
+  let sessionDir: string;
+  let store: ISessionMediaStore;
+
+  beforeEach(async () => {
+    disposables = new DisposableStore();
+    homeDir = await mkdtemp(join(tmpdir(), 'session-media-store-home-'));
+    sessionDir = join(homeDir, 'sessions', 's1');
+    await mkdir(sessionDir, { recursive: true });
+    ix = createServices(disposables, {
+      strict: true,
+      additionalServices: (reg) => {
+        reg.defineInstance(ISessionContext, makeSessionContext({
+          sessionId: 's1',
+          workspaceId: 'w1',
+          sessionDir,
+          sessionScope: join('sessions', 's1'),
+          cwd: '/tmp',
+        }));
+        reg.defineInstance(IFileSystemStorageService, new FileStorageService(homeDir));
+        reg.define(IAtomicDocumentStore, JsonAtomicDocumentStore);
+        reg.define(ISessionMediaStore, SessionMediaStoreService);
+      },
+    });
+    store = ix.get(ISessionMediaStore);
+  });
+
+  afterEach(async () => {
+    disposables.dispose();
+    await rm(homeDir, { recursive: true, force: true });
+  });
+
+  function input(overrides: Partial<Parameters<ISessionMediaStore['materialize']>[0]> = {}) {
+    return {
+      fileId: 'f_1',
+      size: BYTES.length,
+      name: 'clip.mp4',
+      mimeType: 'video/mp4',
+      stream: streamOf(BYTES),
+      ...overrides,
+    };
+  }
+
+  function pathFor(fileId: string, ext: string): string {
+    const path = store.pathFor(fileId, ext);
+    expect(path).toBeDefined();
+    return path!;
+  }
+
+  it('materializes at the storage-backed canonical path', async () => {
+    const target = await store.materialize(input());
+    expect(target).toBe(pathFor('f_1', '.mp4'));
+    expect(target).toBe(join(sessionDir, 'media', 'f_1.mp4'));
+    expect(await readFile(target!)).toEqual(BYTES);
+  });
+
+  it('keeps a same-size copy without re-reading the stream', async () => {
+    await store.materialize(input());
+    const again = await store.materialize(
+      input({
+        stream: () => {
+          throw new Error('must not be read');
+        },
+      }),
+    );
+    expect(again).toBe(pathFor('f_1', '.mp4'));
+    expect(await readFile(again!)).toEqual(BYTES);
+  });
+
+  it('overwrites a wrong-size copy', async () => {
+    const target = await store.materialize(input());
+    await writeFile(target!, 'xx');
+    await store.materialize(input());
+    expect(await readFile(target!)).toEqual(BYTES);
+  });
+
+  it('leaves no temporary storage entry when the stream fails', async () => {
+    await expect(
+      store.materialize(
+        input({
+          stream: () =>
+            Readable.from(
+              (async function* () {
+                yield Buffer.from('partial');
+                throw new Error('stream broke');
+              })(),
+            ),
+        }),
+      ),
+    ).rejects.toMatchObject({ code: 'storage.io_failed' });
+    const entries = await readdir(join(sessionDir, 'media')).catch(() => [] as string[]);
+    expect(entries.filter((name) => name.includes('.tmp.'))).toEqual([]);
+    expect(entries).not.toContain('f_1.mp4');
+  });
+
+  it('derives the extension from the name, then the MIME fallback', async () => {
+    expect(await store.materialize(input())).toBe(pathFor('f_1', '.mp4'));
+    expect(await store.materialize(input({ fileId: 'f_2', name: 'noext' }))).toBe(
+      pathFor('f_2', '.mp4'),
+    );
+    expect(await store.materialize(input({ fileId: 'f_3', name: 'noext', mimeType: 'odd/type' }))).toBe(
+      pathFor('f_3', '.bin'),
+    );
+  });
+
+  it('reads canonical bytes independently from the daemon file store', async () => {
+    await store.materialize(input());
+    await expect(store.read('f_1')).resolves.toEqual({
+      data: BYTES,
+      name: 'f_1.mp4',
+    });
+  });
+
+  it('opens canonical media with its persisted download metadata', async () => {
+    await store.materialize(input({ name: 'original clip.mp4', mimeType: 'video/mp4' }));
+
+    const file = await store.open('f_1');
+
+    expect(file).toMatchObject({
+      path: join(sessionDir, 'media', 'f_1.mp4'),
+      name: 'original clip.mp4',
+      mediaType: 'video/mp4',
+      size: BYTES.length,
+    });
+    expect(file === undefined ? undefined : Buffer.from(await collect(file.stream()))).toEqual(BYTES);
+  });
+
+  it('streams only the requested canonical byte range', async () => {
+    await store.materialize(input());
+
+    const file = await store.open('f_1');
+
+    expect(
+      file === undefined
+        ? undefined
+        : Buffer.from(await collect(file.stream({ start: 2, end: 6 }))),
+    ).toEqual(BYTES.subarray(2, 7));
+  });
+
+  it('resolves the display path from the canonical copy by file id alone', async () => {
+    const target = await store.materialize(input());
+    await expect(store.resolveDisplayPath('f_1')).resolves.toBe(target);
+    await expect(store.resolveDisplayPath('f_missing')).resolves.toBeUndefined();
+  });
+
+  it('finds an extensionless canonical copy by listing', async () => {
+    const target = await store.materialize(input({ name: 'noext', mimeType: 'odd/type' }));
+    expect(target).toBe(pathFor('f_1', '.bin'));
+    const extless = pathFor('f_1', '');
+    await rm(target!);
+    await writeFile(extless, BYTES);
+    await expect(store.resolveDisplayPath('f_1')).resolves.toBe(extless);
+  });
+
+  it('skips in-progress atomic temp siblings when resolving by id', async () => {
+    // The fs backend's atomic write stages bytes at `<key>.tmp.<pid>.<hex>`
+    // next to the target key; a lookup racing the write must not mistake the
+    // partial copy for the canonical one.
+    await mkdir(join(sessionDir, 'media'), { recursive: true });
+    await writeFile(join(sessionDir, 'media', 'f_1.mp4.tmp.1234.deadbeef'), 'partial');
+    await expect(store.resolveDisplayPath('f_1')).resolves.toBeUndefined();
+    await expect(store.read('f_1')).resolves.toBeUndefined();
+    await expect(store.open('f_1')).resolves.toBeUndefined();
+
+    const target = await store.materialize(input());
+    await expect(store.resolveDisplayPath('f_1')).resolves.toBe(target);
+    await expect(store.read('f_1')).resolves.toEqual({ data: BYTES, name: 'f_1.mp4' });
+  });
+
+  it('never turns a non-upload id into a storage key (path traversal guard)', async () => {
+    // A crafted daemon reference (`kimi-file://../../…`) reaches the
+    // store through the request-time resolver's canonical-read fallback; the
+    // id must be rejected before it can become a filesystem key.
+    const evil = '../../../../etc/passwd';
+    expect(store.pathFor(evil, '')).toBeUndefined();
+    expect(store.pathFor(evil, '.png')).toBeUndefined();
+    await expect(store.read(evil)).resolves.toBeUndefined();
+    await expect(store.materialize(input({ fileId: evil }))).resolves.toBeUndefined();
+    await expect(store.resolveDisplayPath(evil)).resolves.toBeUndefined();
+    // Legit ids still work after the guard.
+    expect(store.pathFor('f_1', '.mp4')).toBe(join(sessionDir, 'media', 'f_1.mp4'));
+  });
+});
+
+it('retains canonical bytes without inventing a path for a non-filesystem backend', async () => {
+  const disposables = new DisposableStore();
+  const ix = createServices(disposables, {
+    strict: true,
+    additionalServices: (reg) => {
+      reg.defineInstance(ISessionContext, makeSessionContext({
+        sessionId: 's1',
+        workspaceId: 'w1',
+        sessionDir: '/unused',
+        sessionScope: 'sessions/w1/s1',
+        cwd: '/tmp',
+      }));
+      reg.defineInstance(IFileSystemStorageService, new InMemoryStorageService());
+      reg.define(IAtomicDocumentStore, JsonAtomicDocumentStore);
+      reg.define(ISessionMediaStore, SessionMediaStoreService);
+    },
+  });
+  const store = ix.get(ISessionMediaStore);
+  await expect(store.materialize({
+    fileId: 'f_1',
+    size: BYTES.length,
+    name: 'clip.mp4',
+    mimeType: 'video/mp4',
+    stream: streamOf(BYTES),
+  })).resolves.toBeUndefined();
+  const canonical = await store.read('f_1');
+  expect(canonical?.name).toBe('f_1.mp4');
+  expect(canonical === undefined ? undefined : Buffer.from(canonical.data)).toEqual(BYTES);
+  expect((await store.open('f_1'))?.path).toBeUndefined();
+  disposables.dispose();
+});
+
+async function collect(source: AsyncIterable<Uint8Array>): Promise<Uint8Array> {
+  const chunks: Uint8Array[] = [];
+  for await (const chunk of source) chunks.push(chunk);
+  return Buffer.concat(chunks);
+}
diff --git a/packages/agent-core-v2/test/agent/media/videoResolver.test.ts b/packages/agent-core-v2/test/agent/media/videoResolver.test.ts
deleted file mode 100644
index ded03736de7..00000000000
--- a/packages/agent-core-v2/test/agent/media/videoResolver.test.ts
+++ /dev/null
@@ -1,321 +0,0 @@
-import { Readable } from 'node:stream';
-
-import { describe, expect, it, vi } from 'vitest';
-
-import { buildKimiFileUrl, parseKimiFileUrl } from '#/agent/media/kimiFileUrl';
-import { AgentVideoResolverService } from '#/agent/media/videoResolverService';
-import { AgentStateService } from '#/agent/state/agentStateService';
-import type { GetResult, IFileService } from '#/app/file/fileService';
-import type { ITelemetryService } from '#/app/telemetry/telemetry';
-import type { ModelCapability } from '#/kosong/contract/capability';
-import type { Message, VideoURLPart } from '#/kosong/contract/message';
-import type { ModelRequester } from '#/kosong/model/modelRequester';
-import type { Protocol } from '#/kosong/protocol/protocol';
-import type { IBlobStore } from '#/persistence/interface/blobStore';
-
-const FILE_ID = 'file_abc';
-const FALLBACK_PATH = '/cache/file_abc.mp4';
-const VIDEO_BYTES = Buffer.from('tiny fake mp4 bytes');
-const PNG_BYTES = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0x00]);
-
-function videoMessage(url: string): Message {
-  return { role: 'user', content: [{ type: 'video_url', videoUrl: { url } }], toolCalls: [] };
-}
-
-function firstPart(messages: readonly Message[]) {
-  return messages[0]!.content[0]!;
-}
-
-function fileService(files: Map<string, { name: string; bytes: Buffer }>): IFileService {
-  return {
-    _serviceBrand: undefined,
-    save: async () => {
-      throw new Error('unused');
-    },
-    delete: async () => {},
-    get: async (fileId): Promise<GetResult> => {
-      const file = files.get(fileId);
-      if (file === undefined) throw new Error(`file not found: ${fileId}`);
-      return {
-        meta: {
-          id: fileId,
-          name: file.name,
-          media_type: 'video/mp4',
-          size: file.bytes.length,
-          created_at: new Date(0).toISOString(),
-        },
-        stream: () => Readable.from([file.bytes]),
-      };
-    },
-  };
-}
-
-function blobStore(): IBlobStore {
-  const data = new Map<string, Uint8Array>();
-  return {
-    _serviceBrand: undefined,
-    put: async (scope, key, bytes) => {
-      data.set(`${scope}/${key}`, bytes);
-    },
-    putStream: async (scope, key, source) => {
-      const chunks: Uint8Array[] = [];
-      for await (const chunk of source) chunks.push(chunk);
-      data.set(`${scope}/${key}`, Buffer.concat(chunks));
-    },
-    get: async (scope, key) => data.get(`${scope}/${key}`),
-    getStream: async function* () {},
-    has: async (scope, key) => data.has(`${scope}/${key}`),
-    delete: async (scope, key) => {
-      data.delete(`${scope}/${key}`);
-    },
-    list: async () => [],
-  };
-}
-
-const telemetry = { track2: () => {} } as unknown as ITelemetryService;
-
-function requester(opts: {
-  videoIn?: boolean;
-  protocol?: Protocol;
-  providerType?: string;
-  uploadVideo?: ModelRequester['uploadVideo'];
-}): ModelRequester {
-  return {
-    model: {
-      id: 'm',
-      name: 'stub',
-      aliases: [],
-      protocol: opts.protocol ?? 'openai',
-      headers: {},
-      capabilities: { video_in: opts.videoIn ?? true } as unknown as ModelCapability,
-      maxContextSize: 1000,
-      alwaysThinking: false,
-      providerName: 'p',
-      providerType: opts.providerType ?? 'kimi',
-      authProvider: {} as never,
-    },
-    request: () => {
-      throw new Error('unused');
-    },
-    uploadVideo: opts.uploadVideo,
-  };
-}
-
-function msPart(id: string): VideoURLPart {
-  return { type: 'video_url', videoUrl: { url: `ms://${id}`, id } };
-}
-
-describe('kimiFileUrl', () => {
-  it('round-trips a file id and an escaped materialization path', () => {
-    const url = buildKimiFileUrl('file_1', '/a b/clip.mp4');
-    expect(url).toBe(`kimi-file://file_1?path=${encodeURIComponent('/a b/clip.mp4')}`);
-    expect(parseKimiFileUrl(url)).toEqual({ fileId: 'file_1', path: '/a b/clip.mp4' });
-  });
-
-  it('omits the query when no path is given', () => {
-    expect(buildKimiFileUrl('file_1')).toBe('kimi-file://file_1');
-    expect(parseKimiFileUrl('kimi-file://file_1')).toEqual({ fileId: 'file_1' });
-  });
-
-  it('returns undefined for any non-kimi-file url', () => {
-    expect(parseKimiFileUrl('ms://prov-1')).toBeUndefined();
-    expect(parseKimiFileUrl('data:video/mp4;base64,AAAA')).toBeUndefined();
-    expect(parseKimiFileUrl('https://example.com/clip.mp4')).toBeUndefined();
-  });
-});
-
-describe('AgentVideoResolverService', () => {
-  it('uploads a kimi-file video once and reuses the cached reference on later steps', async () => {
-    const upload = vi.fn(async (): Promise<VideoURLPart> => msPart('prov-1'));
-    const resolver = new AgentVideoResolverService(
-      fileService(new Map([[FILE_ID, { name: 'clip.mp4', bytes: VIDEO_BYTES }]])),
-      blobStore(),
-      telemetry,
-      new AgentStateService(),
-    );
-    const req = requester({ uploadVideo: upload });
-    const message = videoMessage(buildKimiFileUrl(FILE_ID, FALLBACK_PATH));
-
-    const first = await resolver.resolve([message], req);
-    const second = await resolver.resolve([message], req);
-
-    expect(firstPart(first)).toEqual(msPart('prov-1'));
-    expect(firstPart(second)).toEqual(msPart('prov-1'));
-    expect(upload).toHaveBeenCalledTimes(1);
-  });
-
-  it('reuses a persisted upload across resolver instances without re-uploading', async () => {
-    const files = new Map([[FILE_ID, { name: 'clip.mp4', bytes: VIDEO_BYTES }]]);
-    const blobs = blobStore();
-    const message = videoMessage(buildKimiFileUrl(FILE_ID, FALLBACK_PATH));
-
-    const upload1 = vi.fn(async (): Promise<VideoURLPart> => msPart('prov-1'));
-    await new AgentVideoResolverService(fileService(files), blobs, telemetry, new AgentStateService()).resolve(
-      [message],
-      requester({ uploadVideo: upload1 }),
-    );
-
-    const upload2 = vi.fn(async (): Promise<VideoURLPart> => msPart('prov-2'));
-    const out = await new AgentVideoResolverService(fileService(files), blobs, telemetry, new AgentStateService()).resolve(
-      [message],
-      requester({ uploadVideo: upload2 }),
-    );
-
-    expect(firstPart(out)).toEqual(msPart('prov-1'));
-    expect(upload1).toHaveBeenCalledTimes(1);
-    expect(upload2).not.toHaveBeenCalled();
-  });
-
-  it('falls back to a path tag when the model cannot ingest video', async () => {
-    const upload = vi.fn();
-    const out = await new AgentVideoResolverService(
-      fileService(new Map([[FILE_ID, { name: 'clip.mp4', bytes: VIDEO_BYTES }]])),
-      blobStore(),
-      telemetry,
-      new AgentStateService(),
-    ).resolve([videoMessage(buildKimiFileUrl(FILE_ID, FALLBACK_PATH))], requester({ videoIn: false, uploadVideo: upload }));
-
-    expect(firstPart(out)).toEqual({ type: 'text', text: `<video path="${FALLBACK_PATH}"></video>` });
-    expect(upload).not.toHaveBeenCalled();
-  });
-
-  it('inlines base64 for a no-upload provider whose wire carries video', async () => {
-    const out = await new AgentVideoResolverService(
-      fileService(new Map([[FILE_ID, { name: 'clip.mp4', bytes: VIDEO_BYTES }]])),
-      blobStore(),
-      telemetry,
-      new AgentStateService(),
-    ).resolve([videoMessage(buildKimiFileUrl(FILE_ID, FALLBACK_PATH))], requester({ protocol: 'anthropic', uploadVideo: undefined }));
-
-    expect(firstPart(out)).toEqual({
-      type: 'video_url',
-      videoUrl: { url: `data:video/mp4;base64,${VIDEO_BYTES.toString('base64')}` },
-    });
-  });
-
-  it('tags for a no-upload provider whose wire drops inline video (openai family)', async () => {
-    const out = await new AgentVideoResolverService(
-      fileService(new Map([[FILE_ID, { name: 'clip.mp4', bytes: VIDEO_BYTES }]])),
-      blobStore(),
-      telemetry,
-      new AgentStateService(),
-    ).resolve([videoMessage(buildKimiFileUrl(FILE_ID, FALLBACK_PATH))], requester({ protocol: 'openai', uploadVideo: undefined }));
-
-    expect(firstPart(out)).toEqual({ type: 'text', text: `<video path="${FALLBACK_PATH}"></video>` });
-  });
-
-  it('rethrows an auth failure so it can drive credential refresh', async () => {
-    const upload = vi.fn(async () => {
-      throw Object.assign(new Error('unauthorized'), { statusCode: 401 });
-    });
-    const resolver = new AgentVideoResolverService(
-      fileService(new Map([[FILE_ID, { name: 'clip.mp4', bytes: VIDEO_BYTES }]])),
-      blobStore(),
-      telemetry,
-      new AgentStateService(),
-    );
-
-    await expect(
-      resolver.resolve([videoMessage(buildKimiFileUrl(FILE_ID, FALLBACK_PATH))], requester({ uploadVideo: upload })),
-    ).rejects.toThrow('unauthorized');
-  });
-
-  it('rethrows a cancelled upload without memoizing the fallback', async () => {
-    const controller = new AbortController();
-    const interrupted = vi.fn(async () => {
-      controller.abort();
-      throw new Error('socket closed');
-    });
-    const resolver = new AgentVideoResolverService(
-      fileService(new Map([[FILE_ID, { name: 'clip.mp4', bytes: VIDEO_BYTES }]])),
-      blobStore(),
-      telemetry,
-      new AgentStateService(),
-    );
-    const message = videoMessage(buildKimiFileUrl(FILE_ID, FALLBACK_PATH));
-
-    await expect(
-      resolver.resolve([message], requester({ uploadVideo: interrupted }), controller.signal),
-    ).rejects.toThrow('socket closed');
-
-    const retry = vi.fn(async (): Promise<VideoURLPart> => msPart('prov-1'));
-    const out = await resolver.resolve([message], requester({ uploadVideo: retry }));
-    expect(firstPart(out)).toEqual(msPart('prov-1'));
-    expect(retry).toHaveBeenCalledTimes(1);
-  });
-
-  it('retries the upload on a later step after a transient failure instead of freezing the tag', async () => {
-    let uploadCalls = 0;
-    const upload = vi.fn(async (): Promise<VideoURLPart> => {
-      uploadCalls += 1;
-      if (uploadCalls === 1) throw new Error('files endpoint unavailable');
-      return msPart('prov-1');
-    });
-    const resolver = new AgentVideoResolverService(
-      fileService(new Map([[FILE_ID, { name: 'clip.mp4', bytes: VIDEO_BYTES }]])),
-      blobStore(),
-      telemetry,
-      new AgentStateService(),
-    );
-    const message = videoMessage(buildKimiFileUrl(FILE_ID, FALLBACK_PATH));
-    const req = requester({ uploadVideo: upload });
-
-    const failed = await resolver.resolve([message], req);
-    expect(firstPart(failed)).toEqual({ type: 'text', text: `<video path="${FALLBACK_PATH}"></video>` });
-
-    const retried = await resolver.resolve([message], req);
-    expect(firstPart(retried)).toEqual(msPart('prov-1'));
-
-    const memoed = await resolver.resolve([message], req);
-    expect(firstPart(memoed)).toEqual(msPart('prov-1'));
-    expect(upload).toHaveBeenCalledTimes(2);
-  });
-
-  it('tags when the bytes do not sniff as a video', async () => {
-    const upload = vi.fn();
-    const out = await new AgentVideoResolverService(
-      fileService(new Map([[FILE_ID, { name: 'clip.mp4', bytes: PNG_BYTES }]])),
-      blobStore(),
-      telemetry,
-      new AgentStateService(),
-    ).resolve([videoMessage(buildKimiFileUrl(FILE_ID, FALLBACK_PATH))], requester({ uploadVideo: upload }));
-
-    expect(firstPart(out)).toEqual({ type: 'text', text: `<video path="${FALLBACK_PATH}"></video>` });
-    expect(upload).not.toHaveBeenCalled();
-  });
-
-  it('tags a stale reference by its materialization path', async () => {
-    const out = await new AgentVideoResolverService(fileService(new Map()), blobStore(), telemetry, new AgentStateService()).resolve(
-      [videoMessage(buildKimiFileUrl('missing', FALLBACK_PATH))],
-      requester({ uploadVideo: vi.fn() }),
-    );
-
-    expect(firstPart(out)).toEqual({ type: 'text', text: `<video path="${FALLBACK_PATH}"></video>` });
-  });
-
-  it('emits an unavailable placeholder when a stale reference has no fallback path', async () => {
-    const out = await new AgentVideoResolverService(fileService(new Map()), blobStore(), telemetry, new AgentStateService()).resolve(
-      [videoMessage(buildKimiFileUrl('missing'))],
-      requester({ uploadVideo: vi.fn() }),
-    );
-
-    expect(firstPart(out)).toEqual({
-      type: 'text',
-      text: '[video omitted: the uploaded file is no longer available]',
-    });
-  });
-
-  it('leaves messages without a kimi-file video untouched', async () => {
-    const resolver = new AgentVideoResolverService(
-      fileService(new Map([[FILE_ID, { name: 'clip.mp4', bytes: VIDEO_BYTES }]])),
-      blobStore(),
-      telemetry,
-      new AgentStateService(),
-    );
-    const messages = [videoMessage('ms://already-uploaded')];
-
-    const out = await resolver.resolve(messages, requester({ uploadVideo: vi.fn() }));
-
-    expect(out).toBe(messages);
-  });
-});
diff --git a/packages/agent-core-v2/test/agent/prompt/promptMetadataText.test.ts b/packages/agent-core-v2/test/agent/prompt/promptMetadataText.test.ts
index e93d59ff9ba..feed9ec9619 100644
--- a/packages/agent-core-v2/test/agent/prompt/promptMetadataText.test.ts
+++ b/packages/agent-core-v2/test/agent/prompt/promptMetadataText.test.ts
@@ -7,6 +7,8 @@
  *   - an inline image-compression caption (harness metadata placed next to
  *     the image by prompt ingestion) never leaks into titles/lastPrompt,
  *     whether it is a standalone text part or merged into the user's text
+ *   - a standalone `<media path>` tag (machine markup) never leaks a
+ *     materialization path into titles/lastPrompt
  *   - prompt metadata updates retain the latest sanitized prompt and derive
  *     the easy title
  */
@@ -58,6 +60,28 @@ describe('promptMetadataTextFromContentParts', () => {
     expect(text).not.toContain('<system>');
     expect(text).not.toContain('Image compressed');
   });
+
+  it('keeps an upload <image path> tag out of the metadata text', () => {
+    // A standalone media path tag is machine markup: the materialization path
+    // must never leak into titles / lastPrompt, whether or not a daemon-ref
+    // part rides next to it.
+    const text = promptMetadataTextFromContentParts([
+      { type: 'text', text: 'what is this?' },
+      { type: 'text', text: '<image path="/Users/alice/cache/f_123.png"></image>' },
+      { type: 'image_url', imageUrl: { url: 'kimi-file://f_123?path=%2FUsers%2Falice%2Fcache%2Ff_123.png' } },
+    ]);
+    expect(text).toBe('what is this? [image]');
+    expect(text).not.toContain('/Users/alice');
+  });
+
+  it('keeps a bare <image path> tag out of the metadata text', () => {
+    const text = promptMetadataTextFromContentParts([
+      { type: 'text', text: '<image path="/cache/f_123.png">' },
+      { type: 'text', text: 'describe it' },
+    ]);
+    expect(text).toBe('describe it');
+    expect(text).not.toContain('/cache');
+  });
 });
 
 describe('applyPromptMetadataUpdate', () => {
diff --git a/packages/agent-core-v2/test/agent/prompt/promptService.test.ts b/packages/agent-core-v2/test/agent/prompt/promptService.test.ts
index 30e17a60232..3fdf5d74be5 100644
--- a/packages/agent-core-v2/test/agent/prompt/promptService.test.ts
+++ b/packages/agent-core-v2/test/agent/prompt/promptService.test.ts
@@ -6,61 +6,144 @@
  * Run: `pnpm exec vitest run packages/agent-core-v2/test/agent/prompt/promptService.test.ts`.
  */
 
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, dirname, join, relative } from 'node:path';
+import { Readable } from 'node:stream';
+
 import { describe, expect, it, onTestFinished, vi } from 'vitest';
 
 import { DisposableStore } from '#/_base/di/lifecycle';
-import { createServices } from '#/_base/di/test';
+import { createServices, TestInstantiationService } from '#/_base/di/test';
 import { Event } from '#/_base/event';
 import { IAgentContextMemoryService } from '#/agent/contextMemory/contextMemory';
 import type { ContextMessage } from '#/agent/contextMemory/types';
 import { IAgentFullCompactionService } from '#/agent/fullCompaction/fullCompaction';
-import { IAgentLoopService } from '#/agent/loop/loop';
-import { IAgentPromptService } from '#/agent/prompt/prompt';
+import { IAgentLoopService, type Step, type StepAssignment } from '#/agent/loop/loop';
+import type { StepRequest } from '#/agent/loop/stepRequest';
+import { buildDaemonFileUrl } from '#/agent/media/mediaRef';
+import { ISessionMediaStore } from '#/agent/media/sessionMediaStore';
+import { SessionMediaStoreService } from '#/agent/media/sessionMediaStoreService';
+import { IAgentPromptService, reservePrompt } from '#/agent/prompt/prompt';
+import { promptAccepted, PromptAdmissionModel } from '#/agent/prompt/promptOps';
 import { AgentPromptService } from '#/agent/prompt/promptService';
 import { IAgentScopeContext, makeAgentScopeContext } from '#/agent/scopeContext/scopeContext';
 import { IAgentSystemReminderService } from '#/agent/systemReminder/systemReminder';
 import { AgentSystemReminderService } from '#/agent/systemReminder/systemReminderService';
 import { IAgentToolExecutorService } from '#/agent/toolExecutor/toolExecutor';
+import { IAgentToolPolicyService } from '#/agent/toolPolicy/toolPolicy';
+import { IBootstrapService } from '#/app/bootstrap/bootstrap';
 import { IEventBus } from '#/app/event/eventBus';
 import { IEventService } from '#/app/event/event';
 import { EventBusService } from '#/app/event/eventBusService';
+import { type GetResult, IFileService } from '#/app/file/fileService';
 import { ITelemetryService } from '#/app/telemetry/telemetry';
 import { ErrorCodes, Error2 } from '#/errors';
 import { createHooks } from '#/hooks';
-import { ISessionContext } from '#/session/sessionContext/sessionContext';
 import { ISessionMetadata } from '#/session/sessionMetadata/sessionMetadata';
+import type { ContentPart } from '#/kosong/contract/message';
+import { JsonAtomicDocumentStore } from '#/persistence/backends/node-fs/atomicDocumentStore';
 import { IWireService } from '#/wire/wire';
+import { FileStorageService } from '#/persistence/backends/node-fs/fileStorageService';
+import { IAtomicDocumentStore } from '#/persistence/interface/atomicDocumentStore';
+import { IFileSystemStorageService } from '#/persistence/interface/storage';
+import { ISessionContext, makeSessionContext } from '#/session/sessionContext/sessionContext';
 
 import { stubContextMemory } from '../contextMemory/stubs';
 import { stubLoopWithHooks, stubToolExecutor, stubWire } from '../loop/stubs';
 import { registerStateServices } from '../../state/stubs';
+import { stubBootstrap } from '../../app/bootstrap/stubs';
+import {
+  recordingWireLog,
+  registerTestAgentWire,
+  restoreTestAgentWire,
+  testWireScope,
+} from '../../wire/stubs';
 
 function message(text: string): ContextMessage {
   return { role: 'user', content: [{ type: 'text', text }], toolCalls: [], origin: { kind: 'user' } };
 }
 
-function harness() {
+function stubFileService(
+  files: Map<string, { name: string; bytes: Buffer; mime?: string; stream?: () => Readable }>,
+  onGet?: (fileId: string) => void,
+): IFileService {
+  return {
+    _serviceBrand: undefined,
+    save: async () => {
+      throw new Error('unused');
+    },
+    delete: async () => {},
+    get: async (fileId): Promise<GetResult> => {
+      onGet?.(fileId);
+      const file = files.get(fileId);
+      if (file === undefined) throw new Error(`file not found: ${fileId}`);
+      return {
+        meta: {
+          id: fileId,
+          name: file.name,
+          media_type: file.mime ?? 'image/png',
+          size: file.bytes.length,
+          created_at: new Date(0).toISOString(),
+        },
+        stream: file.stream ?? (() => Readable.from([file.bytes])),
+      };
+    },
+  };
+}
+
+function harness(
+  opts: {
+    sessionDir?: string;
+    homeDir?: string;
+    files?: Map<string, { name: string; bytes: Buffer; mime?: string; stream?: () => Readable }>;
+    fileGets?: string[];
+    fullCompaction?: IAgentFullCompactionService;
+    wire?: IWireService;
+  } = {},
+) {
   const disposables = new DisposableStore();
   onTestFinished(() => disposables.dispose());
   const context = stubContextMemory();
   const loop = stubLoopWithHooks({ pendingTurnResult: true });
-  const fullCompaction = {
+  const fullCompaction = opts.fullCompaction ?? ({
     _serviceBrand: undefined,
     compacting: null,
     begin: () => false,
     hooks: createHooks(['onWillCompact']),
     onDidFinishCompaction: Event.None,
-  } as unknown as IAgentFullCompactionService;
+  } as unknown as IAgentFullCompactionService);
+  const sessionDir = opts.sessionDir ?? '/nonexistent-session';
+  const homeDir = opts.homeDir ?? dirname(sessionDir);
+  const sessionScope = opts.homeDir === undefined ? basename(sessionDir) : relative(homeDir, sessionDir);
   const ix = createServices(disposables, {
     strict: true, additionalServices: (reg) => {
       registerStateServices(reg);
       reg.defineInstance(IAgentContextMemoryService, context);
       reg.defineInstance(IAgentLoopService, loop);
-      reg.defineInstance(IWireService, stubWire());
+      reg.defineInstance(IWireService, opts.wire ?? stubWire());
       reg.defineInstance(IAgentToolExecutorService, stubToolExecutor());
+      reg.definePartialInstance(IAgentToolPolicyService, {
+        setSessionDisabledTools: async () => {},
+      });
       reg.defineInstance(IAgentFullCompactionService, fullCompaction);
       reg.define(IEventBus, EventBusService);
       reg.define(IAgentSystemReminderService, AgentSystemReminderService);
+      reg.defineInstance(
+        IFileService,
+        stubFileService(opts.files ?? new Map(), (fileId) => opts.fileGets?.push(fileId)),
+      );
+      reg.defineInstance(IBootstrapService, stubBootstrap(homeDir));
+      reg.defineInstance(ISessionContext, makeSessionContext({
+        sessionId: 's1',
+        workspaceId: 'w1',
+        sessionDir,
+        sessionScope,
+        cwd: '/tmp',
+      }));
+      reg.defineInstance(IFileSystemStorageService, new FileStorageService(homeDir));
+      reg.define(IAtomicDocumentStore, JsonAtomicDocumentStore);
+      reg.define(ISessionMediaStore, SessionMediaStoreService);
       reg.define(IAgentPromptService, AgentPromptService);
       reg.definePartialInstance(ITelemetryService, { track: () => {}, track2: () => {} });
       reg.definePartialInstance(ISessionMetadata, {
@@ -68,7 +151,6 @@ function harness() {
         update: async () => {},
       });
       reg.definePartialInstance(IEventService, { publish: () => {} });
-      reg.definePartialInstance(ISessionContext, { sessionId: 'test-session' });
       reg.defineInstance(IAgentScopeContext, makeAgentScopeContext({ agentId: 'main', agentScope: '' }));
     }
   });
@@ -76,6 +158,62 @@ function harness() {
 }
 
 describe('AgentPromptService', () => {
+  it('rejects an empty caller-chosen id before queue admission', async () => {
+    const { prompt } = harness();
+
+    await expect(prompt.enqueue({ id: '', message: message('hello') })).rejects.toMatchObject({
+      code: 'request.invalid',
+    });
+    expect(prompt.list()).toEqual({ active: undefined, pending: [] });
+  });
+
+  it('atomically rejects a second live reservation for the same id', () => {
+    const { prompt } = harness();
+    const first = reservePrompt(prompt, 'submission-1');
+
+    expect(() => reservePrompt(prompt, 'submission-1')).toThrowError(
+      expect.objectContaining({ code: 'prompt.id_conflict' }),
+    );
+
+    first.dispose();
+    expect(reservePrompt(prompt, 'submission-1').id).toBe('submission-1');
+  });
+
+  it('rejects a duplicate id before daemon media intake or queue events', async () => {
+    const fileGets: string[] = [];
+    const files = new Map([['f_duplicate', { name: 'duplicate.png', bytes: Buffer.from('png') }]]);
+    const { prompt, eventBus } = harness({ files, fileGets });
+    const queued: string[] = [];
+    eventBus.subscribe('prompt.queued', (event) => queued.push(event.promptId));
+    await prompt.enqueue({ id: 'submission-1', message: message('first') });
+
+    await expect(
+      prompt.enqueue({
+        id: 'submission-1',
+        message: {
+          role: 'user',
+          content: [{ type: 'image_url', imageUrl: { url: buildDaemonFileUrl('f_duplicate') } }],
+          toolCalls: [],
+          origin: { kind: 'user' },
+        },
+      }),
+    ).rejects.toMatchObject({ code: 'prompt.id_conflict' });
+
+    expect(fileGets).toEqual([]);
+    expect(queued).toEqual([]);
+  });
+
+  it('rejects reuse after the original prompt reaches a terminal state', async () => {
+    const { prompt, loop } = harness();
+    const first = await prompt.enqueue({ id: 'submission-1', message: message('first') });
+    loop.finishActive();
+    await first.completion;
+
+    await expect(
+      prompt.enqueue({ id: 'submission-1', message: message('retry') }),
+    ).rejects.toMatchObject({ code: 'prompt.id_conflict' });
+  });
+
   it('assigns stable identity and launches an idle prompt', async () => {
     const { prompt } = harness();
     const handle = await prompt.enqueue({ id: 'prompt-1', message: message('hello') });
@@ -84,6 +222,14 @@ describe('AgentPromptService', () => {
     expect((await handle.launched)?.id).toBe(0);
   });
 
+  it('seeds the launched turn with the prompt record id', async () => {
+    const { prompt, loop, context } = harness();
+    const handle = await prompt.enqueue({ id: 'prompt-1', message: message('hello') });
+    await handle.launched;
+    const batch = loop.drainNextBatch(context);
+    expect(batch?.driver.turnSeed?.promptId).toBe('prompt-1');
+  });
+
   it('keeps later prompts in FIFO order while active', async () => {
     const { prompt } = harness();
     await prompt.enqueue({ message: message('active') });
@@ -134,6 +280,17 @@ describe('AgentPromptService', () => {
     expect(prompt.list().pending).toEqual([]);
   });
 
+  it('drains queued prompts before an agent scope is disposed', async () => {
+    const { prompt } = harness();
+    await prompt.enqueue({ message: message('active') });
+    const queued = await prompt.enqueue({ message: message('queued') });
+
+    await prompt.drain(new Error('agent removed'));
+
+    await expect(queued.completion).resolves.toMatchObject({ state: 'cancelled' });
+    expect(prompt.list().pending).toEqual([]);
+  });
+
   it('keeps injections outside the prompt queue', async () => {
     const { prompt } = harness();
     await prompt.inject({ ...message('system'), origin: { kind: 'injection', variant: 'test' } });
@@ -234,3 +391,422 @@ describe('AgentPromptService', () => {
     ).toBe(true);
   });
 });
+
+describe('prompt admission wire model', () => {
+  it('restores accepted ids from the persisted journal', async () => {
+    const disposables = new DisposableStore();
+    onTestFinished(() => {
+      disposables.dispose();
+    });
+    const records: Array<{ type: string; [key: string]: unknown }> = [];
+    const sourceIx = disposables.add(new TestInstantiationService());
+    const source = registerTestAgentWire(sourceIx, testWireScope('prompt', 'source'), {
+      log: recordingWireLog(records),
+    });
+    source.dispatch(promptAccepted({ promptId: 'persisted-submission' }));
+
+    const replayRecords = records.map((record) => ({ ...record }));
+    const replayLog = recordingWireLog([]);
+    const replayIx = disposables.add(new TestInstantiationService());
+    const replay = registerTestAgentWire(replayIx, testWireScope('prompt', 'replay'), {
+      log: replayLog,
+    });
+    await restoreTestAgentWire(
+      replay,
+      replayLog,
+      testWireScope('prompt', 'replay'),
+      replayRecords,
+    );
+
+    expect(replay.getModel(PromptAdmissionModel).has('persisted-submission')).toBe(true);
+  });
+});
+
+describe('AgentPromptService daemon media intake', () => {
+  const PNG_BYTES = Buffer.from('fake png bytes');
+
+  async function tmpSessionDir(): Promise<string> {
+    const dir = await mkdtemp(join(tmpdir(), 'prompt-intake-'));
+    onTestFinished(() => rm(dir, { recursive: true, force: true }));
+    return dir;
+  }
+
+  function mediaMessage(...content: ContentPart[]): ContextMessage {
+    return { role: 'user', content, toolCalls: [], origin: { kind: 'user' } };
+  }
+
+  function enqueueMedia(
+    prompt: IAgentPromptService,
+    opts: { id?: string; fileId: string; kind?: 'image' | 'video'; path?: string; withTag?: boolean },
+  ) {
+    const kind = opts.kind ?? 'image';
+    const url = buildDaemonFileUrl(opts.fileId);
+    const ref: ContentPart =
+      kind === 'video'
+        ? { type: 'video_url', videoUrl: { url } }
+        : { type: 'image_url', imageUrl: { url } };
+    const content: ContentPart[] =
+      opts.withTag === true && opts.path !== undefined
+        ? [{ type: 'text', text: `<${kind} path="${opts.path}"></${kind}>` }, ref]
+        : [ref];
+    return prompt.enqueue({ id: opts.id, message: mediaMessage(...content) });
+  }
+
+  function gatedImage(fileId = 'f_slow') {
+    let open!: () => void;
+    const gate = new Promise<void>((resolve) => {
+      open = resolve;
+    });
+    const files = new Map([
+      [
+        fileId,
+        {
+          name: `${fileId}.png`,
+          bytes: PNG_BYTES,
+          stream: () =>
+            Readable.from(
+              (async function* () {
+                await gate;
+                yield PNG_BYTES;
+              })(),
+            ),
+        },
+      ],
+    ]);
+    return { files, open };
+  }
+
+  function expectMediaRef(
+    content: readonly ContentPart[],
+    fileId: string,
+    kind: 'image' | 'video' = 'image',
+  ): void {
+    expect(content).toEqual([
+      kind === 'video'
+        ? { type: 'video_url', videoUrl: { url: buildDaemonFileUrl(fileId) } }
+        : { type: 'image_url', imageUrl: { url: buildDaemonFileUrl(fileId) } },
+    ]);
+  }
+
+  it('materializes a bare daemon reference into the session media dir', async () => {
+    const sessionDir = await tmpSessionDir();
+    const files = new Map([['f_1', { name: 'pic.png', bytes: PNG_BYTES }]]);
+    const { prompt } = harness({ sessionDir, files });
+
+    const handle = await enqueueMedia(prompt, { id: 'prompt-media', fileId: 'f_1' });
+    await handle.launched;
+
+    const target = join(sessionDir, 'media', 'f_1.png');
+    expect(await readFile(target)).toEqual(PNG_BYTES);
+    expectMediaRef(handle.message.content, 'f_1');
+  });
+
+  it('materializes a bare video daemon reference into the session media dir', async () => {
+    const sessionDir = await tmpSessionDir();
+    const files = new Map([['f_v', { name: 'clip.mp4', bytes: PNG_BYTES, mime: 'video/mp4' }]]);
+    const { prompt } = harness({ sessionDir, files });
+
+    const handle = await enqueueMedia(prompt, { id: 'prompt-video', fileId: 'f_v', kind: 'video' });
+    await handle.launched;
+
+    const target = join(sessionDir, 'media', 'f_v.mp4');
+    expect(await readFile(target)).toEqual(PNG_BYTES);
+    expectMediaRef(handle.message.content, 'f_v', 'video');
+  });
+
+  it('keeps the upload-backed reference when the session media store cannot write', async () => {
+    const homeDir = await mkdtemp(join(tmpdir(), 'prompt-intake-home-'));
+    onTestFinished(() => rm(homeDir, { recursive: true, force: true }));
+    const sessionDir = join(homeDir, 'sessions', 's1');
+    await mkdir(sessionDir, { recursive: true });
+    // A regular file squatting on the media dir name fails the canonical write.
+    await writeFile(join(sessionDir, 'media'), 'occupied');
+    const files = new Map([['f_1', { name: 'pic.png', bytes: PNG_BYTES }]]);
+    const { prompt } = harness({ sessionDir, homeDir, files });
+
+    const handle = await enqueueMedia(prompt, { id: 'prompt-unwritable', fileId: 'f_1' });
+    await handle.launched;
+
+    // No fallback copy: the reference stays bare, so the request-time
+    // resolver keeps serving the bytes from the daemon upload while it lives.
+    expect(handle.message.content).toEqual([
+      { type: 'image_url', imageUrl: { url: buildDaemonFileUrl('f_1') } },
+    ]);
+    await expect(readFile(join(homeDir, 'cache', 'f_1.png'))).rejects.toThrow();
+  });
+
+  it('returns the first idle media prompt before intake resolves', async () => {
+    const sessionDir = await tmpSessionDir();
+    const { files, open } = gatedImage();
+    const { prompt } = harness({ sessionDir, files });
+
+    const handle = await enqueueMedia(prompt, { id: 'media-idle-first', fileId: 'f_slow' });
+
+    expect(handle.state).toBe('pending');
+    // Launching but not yet active: the record stays listed as queued during
+    // the intake window so `list()` never loses an accepted submission.
+    expect(prompt.list().active).toBeUndefined();
+    expect(prompt.list().pending.map((item) => item.id)).toEqual(['media-idle-first']);
+    open();
+    await expect(handle.launched).resolves.toBeDefined();
+  });
+
+  it('counts a launching media prompt as queued in the prompt.queued event', async () => {
+    const sessionDir = await tmpSessionDir();
+    const { files, open } = gatedImage();
+    const { prompt, eventBus } = harness({ sessionDir, files });
+    const queued: Array<{ promptId: string; queueLength: number }> = [];
+    eventBus.subscribe('prompt.queued', (e) => {
+      queued.push({ promptId: e.promptId, queueLength: e.queueLength });
+    });
+
+    // startNext shifts the record into `launchingItem` before the event is
+    // published — the count must still include it.
+    const handlePromise = enqueueMedia(prompt, { id: 'media-launching', fileId: 'f_slow' });
+    expect(queued).toEqual([{ promptId: 'media-launching', queueLength: 1 }]);
+
+    open();
+    await (await handlePromise).launched;
+  });
+
+  it('keeps a client-submitted tag+ref pair as-is while materializing the bytes', async () => {
+    const sessionDir = await tmpSessionDir();
+    const files = new Map([['f_1', { name: 'pic.png', bytes: PNG_BYTES }]]);
+    const { prompt } = harness({ sessionDir, files });
+    const clientPath = '/client-cache/f_1.png';
+
+    const handle = await enqueueMedia(prompt, {
+      id: 'prompt-pair',
+      fileId: 'f_1',
+      path: clientPath,
+      withTag: true,
+    });
+    await handle.launched;
+
+    const target = join(sessionDir, 'media', 'f_1.png');
+    expect(await readFile(target)).toEqual(PNG_BYTES);
+    expect(handle.message.content).toEqual([
+      { type: 'text', text: `<image path="${clientPath}"></image>` },
+      { type: 'image_url', imageUrl: { url: buildDaemonFileUrl('f_1') } },
+    ]);
+  });
+
+  it('keeps an already-materialized reference untouched when intake runs over it again', async () => {
+    const sessionDir = await tmpSessionDir();
+    const files = new Map([['f_1', { name: 'pic.png', bytes: PNG_BYTES }]]);
+    const { prompt } = harness({ sessionDir, files });
+    const target = join(sessionDir, 'media', 'f_1.png');
+
+    const first = await enqueueMedia(prompt, { fileId: 'f_1' });
+    await first.launched;
+    const second = await prompt.enqueue({ message: mediaMessage(...first.message.content) });
+
+    expectMediaRef(first.message.content, 'f_1');
+    expectMediaRef(second.message.content, 'f_1');
+    expect((await readFile(target)).length).toBe(PNG_BYTES.length);
+  });
+
+  it('keeps the original reference when the upload cannot be read', async () => {
+    const sessionDir = await tmpSessionDir();
+    const { prompt } = harness({ sessionDir, files: new Map() });
+
+    const handle = await enqueueMedia(prompt, { fileId: 'f_missing' });
+
+    expect(handle.message.content).toEqual([
+      { type: 'image_url', imageUrl: { url: buildDaemonFileUrl('f_missing') } },
+    ]);
+  });
+
+  it('keeps arrival order without making a queued text prompt wait for a slow media intake', async () => {
+    const sessionDir = await tmpSessionDir();
+    const { files, open } = gatedImage();
+    const { prompt } = harness({ sessionDir, files });
+
+    const mediaHandle = enqueueMedia(prompt, { id: 'media-first', fileId: 'f_slow' });
+    const textHandle = prompt.enqueue({ id: 'text-second', message: message('plain') });
+    const textRecord = await textHandle;
+    expect(textRecord.state).toBe('pending');
+    // The media record is launching through its slow intake: still queued in
+    // the snapshot, ahead of the text prompt.
+    expect(prompt.list().pending.map((item) => item.id)).toEqual(['media-first', 'text-second']);
+    open();
+
+    const mediaRecord = await mediaHandle;
+    await mediaRecord.launched;
+    expect(prompt.list().active?.id).toBe('media-first');
+    expect(prompt.list().pending.map((item) => item.id)).toEqual(['text-second']);
+  });
+
+  it('settles an abort that lands during a hung intake, freeing the launch slot', async () => {
+    const sessionDir = await tmpSessionDir();
+    const { files, open } = gatedImage();
+    const { prompt } = harness({ sessionDir, files });
+
+    const handlePromise = enqueueMedia(prompt, { id: 'media-abort', fileId: 'f_slow' });
+    expect(prompt.abort('media-abort')).toBe(true);
+    const handle = await handlePromise;
+    expect(handle.state).toBe('cancelled');
+    await expect(handle.launched).resolves.toBeUndefined();
+    await expect(handle.completion).resolves.toMatchObject({ state: 'cancelled' });
+
+    const textHandle = await prompt.enqueue({ id: 'text-after', message: message('plain') });
+    await textHandle.launched;
+    expect(textHandle.state).toBe('running');
+    expect(prompt.list().active?.id).toBe('text-after');
+
+    open();
+    await prompt.drain();
+    await expect(readFile(join(sessionDir, 'media', 'f_slow.png'))).rejects.toMatchObject({
+      code: 'ENOENT',
+    });
+    expect(prompt.list().pending).toEqual([]);
+  });
+
+  it('materializes a queued daemon reference before a steer consumes it', async () => {
+    const sessionDir = await tmpSessionDir();
+    const files = new Map([['f_1', { name: 'pic.png', bytes: PNG_BYTES }]]);
+    const { prompt, context, loop } = harness({ sessionDir, files });
+
+    const active = await prompt.enqueue({ message: message('active') });
+    await active.launched;
+    const queued = await enqueueMedia(prompt, { id: 'prompt-steer-media', fileId: 'f_1' });
+    await prompt.steer([queued.id]);
+    loop.drainNextBatch(context);
+
+    const target = join(sessionDir, 'media', 'f_1.png');
+    expect(await readFile(target)).toEqual(PNG_BYTES);
+    const parts = context.get().flatMap((entry) => entry.content);
+    const images = parts.filter((part) => part.type === 'image_url');
+    expect(images).toEqual([
+      { type: 'image_url', imageUrl: { url: buildDaemonFileUrl('f_1') } },
+    ]);
+  });
+
+  it('does not write context or launch when an abort lands during the before-submit hook', async () => {
+    const { prompt, context, loop, eventBus } = harness();
+    let hookEntered!: () => void;
+    let releaseHook!: () => void;
+    const hookRunning = new Promise<void>((resolve) => { hookEntered = resolve; });
+    const hookGate = new Promise<void>((resolve) => { releaseHook = resolve; });
+    prompt.hooks.onBeforeSubmitPrompt.register('gate', async (_ctx, next) => {
+      hookEntered();
+      await hookGate;
+      await next();
+    });
+    const events: string[] = [];
+    eventBus.subscribe('prompt.completed', () => events.push('completed'));
+    eventBus.subscribe('prompt.aborted', () => events.push('aborted'));
+
+    const handlePromise = prompt.enqueue({ id: 'hooked', message: message('hi') });
+    await hookRunning;
+    expect(prompt.abort('hooked')).toBe(true);
+    releaseHook();
+
+    const handle = await handlePromise;
+    expect(handle.state).toBe('cancelled');
+    await expect(handle.completion).resolves.toMatchObject({ state: 'cancelled' });
+    expect(loop.launches).toEqual([]);
+    expect(context.get()).toEqual([]);
+    expect(events).toEqual(['aborted']);
+    expect(prompt.list()).toEqual({ active: undefined, pending: [] });
+  });
+
+  it('requeues once while compaction runs and launches when compaction finishes', async () => {
+    const sessionDir = await tmpSessionDir();
+    const { files, open } = gatedImage();
+    const finishListeners: Array<() => void> = [];
+    const compactionState: { current: unknown } = { current: null };
+    const compaction = {
+      _serviceBrand: undefined,
+      get compacting() { return compactionState.current; },
+      begin: () => false,
+      hooks: createHooks(['onWillCompact']),
+      onDidFinishCompaction: (listener: () => void) => {
+        finishListeners.push(listener);
+        return { dispose: () => undefined };
+      },
+    } as unknown as IAgentFullCompactionService;
+    const { prompt, loop } = harness({ sessionDir, files, fullCompaction: compaction });
+
+    const handlePromise = enqueueMedia(prompt, { id: 'media-compacted', fileId: 'f_slow' });
+    compactionState.current = { pass: 'manual' };
+    open();
+    await vi.waitFor(() => {
+      expect(prompt.list().pending.map((item) => item.id)).toEqual(['media-compacted']);
+    });
+    expect(loop.launches).toEqual([]);
+
+    compactionState.current = null;
+    for (const listener of finishListeners) listener();
+    const handle = await handlePromise;
+    await handle.launched;
+    expect(handle.state).toBe('running');
+    expect(prompt.list().active?.id).toBe('media-compacted');
+  });
+
+  it('rejects a steer whose prompt was cleared while its intake was still running', async () => {
+    const sessionDir = await tmpSessionDir();
+    const { files, open } = gatedImage();
+    const { prompt } = harness({ sessionDir, files });
+
+    const active = await prompt.enqueue({ message: message('active') });
+    await active.launched;
+    const queued = await enqueueMedia(prompt, { id: 'steered-away', fileId: 'f_slow' });
+    const steerPromise = prompt.steer([queued.id]);
+    void steerPromise.catch(() => undefined);
+    prompt.clear();
+    open();
+
+    await expect(steerPromise).rejects.toThrow(/cancelled/);
+    expect(queued.state).toBe('cancelled');
+    await expect(queued.completion).resolves.toMatchObject({ state: 'cancelled' });
+  });
+
+  it('keeps an abort that lands while a steer awaits its step assignment', async () => {
+    const { prompt, loop, eventBus } = harness();
+    const active = await prompt.enqueue({ id: 'active', message: message('active') });
+    const activeTurn = await active.launched;
+    const queued = await prompt.enqueue({ id: 'steer-me', message: message('steer me') });
+
+    // Hold the steer request's step assignment so the abort lands mid-flight.
+    let assign!: (assignment: StepAssignment) => void;
+    let steerRequest!: StepRequest;
+    const originalEnqueue = loop.enqueue.bind(loop);
+    vi.spyOn(loop, 'enqueue').mockImplementation((request, options) => {
+      if (request.kind !== 'steer') return originalEnqueue(request, options);
+      steerRequest = request;
+      const assigned = new Promise<StepAssignment>((resolve) => { assign = resolve; });
+      void assigned.catch(() => undefined);
+      return { assigned, abort: () => request.abort() };
+    });
+    const events: string[] = [];
+    eventBus.subscribe('prompt.steered', () => events.push('steered'));
+    eventBus.subscribe('prompt.aborted', () => events.push('aborted'));
+
+    const steerPromise = prompt.steer([queued.id]);
+    void steerPromise.catch(() => undefined);
+    await vi.waitFor(() => {
+      expect(steerRequest).toBeDefined();
+    });
+
+    // The abort settles the prompt as cancelled inside the assignment window;
+    // the steer must not flip it back to 'steered', and the undispatched
+    // request must be discarded so its content never reaches the context.
+    expect(prompt.abort(queued.id)).toBe(true);
+    const step: Step = {
+      id: steerRequest.id,
+      turnId: activeTurn!.id,
+      state: 'queued',
+      signal: new AbortController().signal,
+      result: Promise.resolve({ type: 'completed' }),
+      cancel: () => steerRequest.abort(),
+    };
+    assign({ turn: activeTurn!, step });
+
+    await expect(steerPromise).rejects.toThrow(/steer was cancelled/);
+    expect(queued.state).toBe('cancelled');
+    await expect(queued.completion).resolves.toMatchObject({ state: 'cancelled' });
+    expect(steerRequest.aborted).toBe(true);
+    expect(events).toEqual(['aborted']);
+  });
+});
diff --git a/packages/agent-core-v2/test/app/config/config.test.ts b/packages/agent-core-v2/test/app/config/config.test.ts
index 5a5cacf18ef..2e6a16c4c46 100644
--- a/packages/agent-core-v2/test/app/config/config.test.ts
+++ b/packages/agent-core-v2/test/app/config/config.test.ts
@@ -318,8 +318,9 @@ describe('Agent config', () => {
       input: [{ type: 'text', text: 'Look up before config changes' }],
     });
     expect(await ctx.untilApproval(true)).toMatchInlineSnapshot(`
+      [wire] prompt.accepted                 { "promptId": "<msg-1>", "time": "<time>" }
       [wire] turn.prompt                     { "input": [ { "type": "text", "text": "Look up before config changes" } ], "origin": { "kind": "user" }, "time": "<time>" }
-      [emit] turn.started                    { "turnId": 0, "origin": { "kind": "user" }, "prompt": "Look up before config changes" }
+      [emit] turn.started                    { "turnId": 0, "origin": { "kind": "user" }, "prompt": "Look up before config changes", "promptId": "<msg-1>" }
       [emit] agent.activity.updated          { "lifecycle": "ready", "turn": { "turnId": 0, "origin": { "kind": "user" }, "phase": "running", "step": 0, "ending": false, "pendingApprovals": [], "activeToolCalls": [], "since": "<time>" }, "background": [] }
       [emit] context.spliced                 { "start": 0, "deleteCount": 0, "messages": [ { "role": "user", "content": [ { "type": "text", "text": "Look up before config changes" } ], "toolCalls": [], "origin": { "kind": "user" }, "id": "<msg-1>" } ] }
       [wire] context.append_message          { "message": { "role": "user", "content": [ { "type": "text", "text": "Look up before config changes" } ], "toolCalls": [], "origin": { "kind": "user" }, "id": "<msg-1>" }, "time": "<time>" }
@@ -403,8 +404,9 @@ describe('Agent config', () => {
     expect(await ctx.untilTurnEnd()).toMatchInlineSnapshot(`
       [emit] agent.activity.updated      { "lifecycle": "ready", "lastTurn": { "turnId": 0, "reason": "completed", "at": "<time>" }, "background": [] }
       [emit] prompt.completed            { "promptId": "<msg-1>", "finishedAt": "<time>", "reason": "completed" }
+      [wire] prompt.accepted             { "promptId": "<msg-2>", "time": "<time>" }
       [wire] turn.prompt                 { "input": [ { "type": "text", "text": "Start a fresh turn" } ], "origin": { "kind": "user" }, "time": "<time>" }
-      [emit] turn.started                { "turnId": 1, "origin": { "kind": "user" }, "prompt": "Start a fresh turn" }
+      [emit] turn.started                { "turnId": 1, "origin": { "kind": "user" }, "prompt": "Start a fresh turn", "promptId": "<msg-2>" }
       [emit] agent.activity.updated      { "lifecycle": "ready", "turn": { "turnId": 1, "origin": { "kind": "user" }, "phase": "running", "step": 0, "ending": false, "pendingApprovals": [], "activeToolCalls": [], "since": "<time>" }, "background": [] }
       [emit] context.spliced             { "start": 4, "deleteCount": 0, "messages": [ { "role": "user", "content": [ { "type": "text", "text": "Start a fresh turn" } ], "toolCalls": [], "origin": { "kind": "user" }, "id": "<msg-2>" } ] }
       [wire] context.append_message      { "message": { "role": "user", "content": [ { "type": "text", "text": "Start a fresh turn" } ], "toolCalls": [], "origin": { "kind": "user" }, "id": "<msg-2>" }, "time": "<time>" }
diff --git a/packages/agent-core-v2/test/app/file/fileService.test.ts b/packages/agent-core-v2/test/app/file/fileService.test.ts
index b112e09b743..a2801499027 100644
--- a/packages/agent-core-v2/test/app/file/fileService.test.ts
+++ b/packages/agent-core-v2/test/app/file/fileService.test.ts
@@ -85,6 +85,43 @@ describe('FileServiceImpl', () => {
     expect(Date.parse(meta.expires_at!)).toBeGreaterThan(Date.parse(meta.created_at));
   });
 
+  it('removes an expired staging upload on access', async () => {
+    const meta = await store().save(readable('temporary'), 'temporary.bin', {
+      expiresInSec: -1,
+    });
+
+    await expect(store().get(meta.id)).rejects.toMatchObject({
+      code: FileErrors.codes.FILE_NOT_FOUND,
+    });
+    expect(await backend.list('files')).not.toContain(meta.id);
+  });
+
+  it('prunes expired uploads while loading a persisted index', async () => {
+    const expired = await store().save(readable('old'), 'old.bin', { expiresInSec: 60 });
+    const fresh = await store().save(readable('new'), 'new.bin');
+    const rawIndex = await backend.read('file', 'index.json');
+    const index = JSON.parse(new TextDecoder().decode(rawIndex)) as {
+      files: Array<{ id: string; expires_at?: string }>;
+    };
+    index.files.find((file) => file.id === expired.id)!.expires_at = new Date(0).toISOString();
+    await backend.write('file', 'index.json', textEncoder.encode(JSON.stringify(index)));
+
+    const ix2 = createServices(disposables, {
+      additionalServices: (reg) => {
+        reg.defineInstance(IFileSystemStorageService, backend);
+        reg.define(IBlobStore, BlobStoreService);
+        reg.define(IFileService, FileServiceImpl);
+      },
+    });
+    const reloaded = ix2.get(IFileService);
+
+    await expect(reloaded.get(expired.id)).rejects.toMatchObject({
+      code: FileErrors.codes.FILE_NOT_FOUND,
+    });
+    await expect(reloaded.get(fresh.id)).resolves.toMatchObject({ meta: { id: fresh.id } });
+    expect(await backend.list('files')).not.toContain(expired.id);
+  });
+
   it('throws file.not_found for an unknown id on get', async () => {
     await expect(store().get('f_does_not_exist')).rejects.toMatchObject({
       code: FileErrors.codes.FILE_NOT_FOUND,
@@ -124,6 +161,25 @@ describe('FileServiceImpl', () => {
     expect((await readAll(stream())).toString()).toBe('aaabbbbcc');
   });
 
+  it('keeps concurrent uploads visible in the persisted index', async () => {
+    const metas = await Promise.all([
+      store().save(readable('first'), 'first.txt'),
+      store().save(readable('second'), 'second.txt'),
+    ]);
+
+    const ix2 = createServices(disposables, {
+      additionalServices: (reg) => {
+        reg.defineInstance(IFileSystemStorageService, backend);
+        reg.define(IBlobStore, BlobStoreService);
+        reg.define(IFileService, FileServiceImpl);
+      },
+    });
+    const reloaded = ix2.get(IFileService);
+    for (const meta of metas) {
+      await expect(reloaded.get(meta.id)).resolves.toMatchObject({ meta: { id: meta.id } });
+    }
+  });
+
   it('cleans up the blob when the source stream fails mid-upload', async () => {
     const failing = Readable.from((async function* () {
       yield Buffer.from('partial');
diff --git a/packages/agent-core-v2/test/app/gateway/gateway.test.ts b/packages/agent-core-v2/test/app/gateway/gateway.test.ts
index d942033d841..fb04d1e3412 100644
--- a/packages/agent-core-v2/test/app/gateway/gateway.test.ts
+++ b/packages/agent-core-v2/test/app/gateway/gateway.test.ts
@@ -58,6 +58,7 @@ describe('RestGateway', () => {
       steer: () => Promise.resolve([]),
       list: () => ({ active: undefined, pending: [] }),
       abort: () => true,
+      drain: () => Promise.resolve(),
       inject: () => Promise.resolve(undefined),
       retry: () => Promise.resolve(undefined),
       clear: () => {},
diff --git a/packages/agent-core-v2/test/features/plan/plan.test.ts b/packages/agent-core-v2/test/features/plan/plan.test.ts
index 5fc1a3f764b..108f42bc773 100644
--- a/packages/agent-core-v2/test/features/plan/plan.test.ts
+++ b/packages/agent-core-v2/test/features/plan/plan.test.ts
@@ -714,8 +714,9 @@ describe('Plan service', () => {
         [wire] permission.set_mode         { "mode": "yolo", "time": "<time>" }
         [wire] plan_mode.enter             { "id": "test-plan", "time": "<time>" }
         [emit] agent.status.updated        { "planMode": true }
+        [wire] prompt.accepted             { "promptId": "<msg-1>", "time": "<time>" }
         [wire] turn.prompt                 { "input": [ { "type": "text", "text": "Inspect without mutating files" } ], "origin": { "kind": "user" }, "time": "<time>" }
-        [emit] turn.started                { "turnId": 0, "origin": { "kind": "user" }, "prompt": "Inspect without mutating files" }
+        [emit] turn.started                { "turnId": 0, "origin": { "kind": "user" }, "prompt": "Inspect without mutating files", "promptId": "<msg-1>" }
         [emit] agent.activity.updated      { "lifecycle": "ready", "turn": { "turnId": 0, "origin": { "kind": "user" }, "phase": "running", "step": 0, "ending": false, "pendingApprovals": [], "activeToolCalls": [], "since": "<time>" }, "background": [] }
         [emit] context.spliced             { "start": 0, "deleteCount": 0, "messages": [ { "role": "user", "content": [ { "type": "text", "text": "Inspect without mutating files" } ], "toolCalls": [], "origin": { "kind": "user" }, "id": "<msg-1>" } ] }
         [wire] context.append_message      { "message": { "role": "user", "content": [ { "type": "text", "text": "Inspect without mutating files" } ], "toolCalls": [], "origin": { "kind": "user" }, "id": "<msg-1>" }, "time": "<time>" }
@@ -793,8 +794,9 @@ describe('Plan service', () => {
         [wire] permission.set_mode         { "mode": "yolo", "time": "<time>" }
         [wire] plan_mode.enter             { "id": "test-plan", "time": "<time>" }
         [emit] agent.status.updated        { "planMode": true }
+        [wire] prompt.accepted             { "promptId": "<msg-1>", "time": "<time>" }
         [wire] turn.prompt                 { "input": [ { "type": "text", "text": "Remove forbidden.txt" } ], "origin": { "kind": "user" }, "time": "<time>" }
-        [emit] turn.started                { "turnId": 0, "origin": { "kind": "user" }, "prompt": "Remove forbidden.txt" }
+        [emit] turn.started                { "turnId": 0, "origin": { "kind": "user" }, "prompt": "Remove forbidden.txt", "promptId": "<msg-1>" }
         [emit] agent.activity.updated      { "lifecycle": "ready", "turn": { "turnId": 0, "origin": { "kind": "user" }, "phase": "running", "step": 0, "ending": false, "pendingApprovals": [], "activeToolCalls": [], "since": "<time>" }, "background": [] }
         [emit] context.spliced             { "start": 0, "deleteCount": 0, "messages": [ { "role": "user", "content": [ { "type": "text", "text": "Remove forbidden.txt" } ], "toolCalls": [], "origin": { "kind": "user" }, "id": "<msg-1>" } ] }
         [wire] context.append_message      { "message": { "role": "user", "content": [ { "type": "text", "text": "Remove forbidden.txt" } ], "toolCalls": [], "origin": { "kind": "user" }, "id": "<msg-1>" }, "time": "<time>" }
diff --git a/packages/agent-core-v2/test/index.test.ts b/packages/agent-core-v2/test/index.test.ts
index 3456e441fa6..0c7c9665a8e 100644
--- a/packages/agent-core-v2/test/index.test.ts
+++ b/packages/agent-core-v2/test/index.test.ts
@@ -81,6 +81,7 @@ const V2_RECORD_TYPES: ReadonlySet<string> = new Set([
   'plugin.session_start',
   'runtime.set_binding',
   'turn.ended',
+  'prompt.accepted',
   'token_counting.measured',
   'token_counting.truncated',
   'token_counting.rebased',
diff --git a/packages/agent-core-v2/test/persistence/backends/node-fs/appendLogStore.test.ts b/packages/agent-core-v2/test/persistence/backends/node-fs/appendLogStore.test.ts
index 52d7eaadaa8..390241b5d32 100644
--- a/packages/agent-core-v2/test/persistence/backends/node-fs/appendLogStore.test.ts
+++ b/packages/agent-core-v2/test/persistence/backends/node-fs/appendLogStore.test.ts
@@ -38,6 +38,8 @@ function chunkedStorage(chunks: Uint8Array[]): IFileSystemStorageService {
     append: async () => {},
     list: async () => [],
     delete: async () => {},
+    size: async () => undefined,
+    pathFor: () => undefined,
     flush: async () => {},
     close: async () => {},
   };
diff --git a/packages/agent-core-v2/test/session/agentLifecycle/agentLifecycle.test.ts b/packages/agent-core-v2/test/session/agentLifecycle/agentLifecycle.test.ts
index e231ccc0520..3c126b3eb96 100644
--- a/packages/agent-core-v2/test/session/agentLifecycle/agentLifecycle.test.ts
+++ b/packages/agent-core-v2/test/session/agentLifecycle/agentLifecycle.test.ts
@@ -59,6 +59,7 @@ import { ISessionMetadata } from '#/session/sessionMetadata/sessionMetadata';
 import { createWireMetadataRecord, type WireRecord } from '#/wire/record';
 import { IAgentToolExecutorService } from '#/agent/toolExecutor/toolExecutor';
 import { IAgentLoopService } from '#/agent/loop/loop';
+import { IAgentPromptService } from '#/agent/prompt/prompt';
 import { IAgentFullCompactionService } from '#/agent/fullCompaction/fullCompaction';
 import { ITelemetryService } from '#/app/telemetry/telemetry';
 import { IAgentTelemetryContextService } from '#/app/telemetry/agentTelemetryContext';
@@ -173,6 +174,7 @@ describe('AgentLifecycleService', () => {
   let loopPendingTurnIds: number[];
   let loopCancel: ReturnType<typeof vi.fn<IAgentLoopService['cancel']>>;
   let loopSettled: ReturnType<typeof vi.fn<IAgentLoopService['settled']>>;
+  let promptDrain: ReturnType<typeof vi.fn<IAgentPromptService['drain']>>;
   let beforeExecuteListeners: number;
   let didExecuteHookIds: string[];
 
@@ -318,6 +320,11 @@ describe('AgentLifecycleService', () => {
       cancel: loopCancel,
       settled: loopSettled,
     } as unknown as IAgentLoopService);
+    promptDrain = vi.fn<IAgentPromptService['drain']>(async () => {});
+    ix.stub(IAgentPromptService, {
+      _serviceBrand: undefined,
+      drain: promptDrain,
+    } as unknown as IAgentPromptService);
     ix.stub(ITelemetryService, {
       _serviceBrand: undefined,
       track2: () => {},
@@ -426,6 +433,35 @@ describe('AgentLifecycleService', () => {
     await svc.remove('main');
 
     expect(stopAllOnExit).toHaveBeenCalledWith('Session closed');
+    expect(promptDrain).toHaveBeenCalledOnce();
+  });
+
+  it('remove waits for prompt intake to drain before disposing the agent scope', async () => {
+    let releaseDrain!: () => void;
+    let markDrainStarted!: () => void;
+    const drainStarted = new Promise<void>((resolve) => {
+      markDrainStarted = resolve;
+    });
+    promptDrain.mockImplementationOnce(() => {
+      markDrainStarted();
+      return new Promise<void>((resolve) => {
+        releaseDrain = resolve;
+      });
+    });
+    const svc = ix.get(IAgentLifecycleService);
+    await svc.create({ agentId: 'main' });
+    const disposed: string[] = [];
+    disposables.add(svc.onDidDispose((agentId) => disposed.push(agentId)));
+
+    const removal = svc.remove('main');
+    await drainStarted;
+    await Promise.resolve();
+
+    expect(disposed).toEqual([]);
+
+    releaseDrain();
+    await removal;
+    expect(disposed).toEqual(['main']);
   });
 
   it('remove cancels queued turns before waiting for the active turn to settle', async () => {
diff --git a/packages/agent-core-v2/test/tool/tool.test.ts b/packages/agent-core-v2/test/tool/tool.test.ts
index f8c82c09bf8..25dd7d37353 100644
--- a/packages/agent-core-v2/test/tool/tool.test.ts
+++ b/packages/agent-core-v2/test/tool/tool.test.ts
@@ -3399,8 +3399,9 @@ describe('Agent tools', () => {
       ).toMatchInlineSnapshot(`
         [wire] permission.set_mode         { "mode": "auto", "time": "<time>" }
         [wire] tools.register_user_tool    { "name": "Lookup", "description": "Look up a short test value.", "parameters": { "type": "object", "properties": { "query": { "type": "string" } }, "required": [ "query" ], "additionalProperties": false }, "time": "<time>" }
+        [wire] prompt.accepted             { "promptId": "<msg-1>", "time": "<time>" }
         [wire] turn.prompt                 { "input": [ { "type": "text", "text": "Look up moon" } ], "origin": { "kind": "user" }, "time": "<time>" }
-        [emit] turn.started                { "turnId": 0, "origin": { "kind": "user" }, "prompt": "Look up moon" }
+        [emit] turn.started                { "turnId": 0, "origin": { "kind": "user" }, "prompt": "Look up moon", "promptId": "<msg-1>" }
         [emit] agent.activity.updated      { "lifecycle": "ready", "turn": { "turnId": 0, "origin": { "kind": "user" }, "phase": "running", "step": 0, "ending": false, "pendingApprovals": [], "activeToolCalls": [], "since": "<time>" }, "background": [] }
         [emit] context.spliced             { "start": 0, "deleteCount": 0, "messages": [ { "role": "user", "content": [ { "type": "text", "text": "Look up moon" } ], "toolCalls": [], "origin": { "kind": "user" }, "id": "<msg-1>" } ] }
         [emit] context.spliced             { "start": 1, "deleteCount": 0, "messages": [ { "role": "user", "content": [ { "type": "text", "text": "<auto-mode-enter-reminder>" } ], "toolCalls": [], "origin": { "kind": "injection", "variant": "permission_mode" } } ] }
@@ -3472,8 +3473,9 @@ describe('Agent tools', () => {
         [emit] agent.activity.updated       { "lifecycle": "ready", "lastTurn": { "turnId": 0, "reason": "completed", "at": "<time>" }, "background": [] }
         [wire] tools.unregister_user_tool   { "name": "Lookup", "time": "<time>" }
         [emit] prompt.completed             { "promptId": "<msg-1>", "finishedAt": "<time>", "reason": "completed" }
+        [wire] prompt.accepted              { "promptId": "<msg-2>", "time": "<time>" }
         [wire] turn.prompt                  { "input": [ { "type": "text", "text": "Can you still use Lookup?" } ], "origin": { "kind": "user" }, "time": "<time>" }
-        [emit] turn.started                 { "turnId": 1, "origin": { "kind": "user" }, "prompt": "Can you still use Lookup?" }
+        [emit] turn.started                 { "turnId": 1, "origin": { "kind": "user" }, "prompt": "Can you still use Lookup?", "promptId": "<msg-2>" }
         [emit] agent.activity.updated       { "lifecycle": "ready", "turn": { "turnId": 1, "origin": { "kind": "user" }, "phase": "running", "step": 0, "ending": false, "pendingApprovals": [], "activeToolCalls": [], "since": "<time>" }, "background": [] }
         [emit] context.spliced              { "start": 5, "deleteCount": 0, "messages": [ { "role": "user", "content": [ { "type": "text", "text": "Can you still use Lookup?" } ], "toolCalls": [], "origin": { "kind": "user" }, "id": "<msg-2>" } ] }
         [wire] context.append_message       { "message": { "role": "user", "content": [ { "type": "text", "text": "Can you still use Lookup?" } ], "toolCalls": [], "origin": { "kind": "user" }, "id": "<msg-2>" }, "time": "<time>" }
diff --git a/packages/kap-server/src/lib/contentDisposition.ts b/packages/kap-server/src/lib/contentDisposition.ts
new file mode 100644
index 00000000000..4f18c7d16d3
--- /dev/null
+++ b/packages/kap-server/src/lib/contentDisposition.ts
@@ -0,0 +1,11 @@
+/**
+ * Raw-content HTTP helpers — safe inline/attachment content disposition.
+ */
+
+export function buildContentDisposition(name: string, mediaType?: string): string {
+  const disposition = /^(image|video|audio)\//.test(mediaType ?? '') ? 'inline' : 'attachment';
+  if (/^[\w. ()+[\]-]+$/.test(name)) {
+    return `${disposition}; filename="${name}"`;
+  }
+  return disposition;
+}
diff --git a/packages/kap-server/src/lib/promptMedia.ts b/packages/kap-server/src/lib/promptMedia.ts
index 2895cecaf3c..ddce09f1ff4 100644
--- a/packages/kap-server/src/lib/promptMedia.ts
+++ b/packages/kap-server/src/lib/promptMedia.ts
@@ -2,14 +2,17 @@
  * Prompt media/attachment pipeline shared by the prompt-submission and
  * skill-activation edges.
  *
- * Three stages, in the order both routes apply them:
+ * Four stages, in the order both routes apply them:
  *   1. `assertPromptFileRefs` — fail fast on stale or mis-kinded `file_id`
  *      references before anything session-scoped is resolved or mutated.
- *   2. `resolvePromptMediaFiles` — materialize uploads into session-local
- *      copies: arbitrary files become path-referenced attachments (a text
- *      notice the model opens with the Read tool), images are format-gated
- *      and compressed, videos become internal `kimi-file://` references.
- *   3. `contentToCoreParts` — project the resolved wire content onto engine
+ *   2. `assertPromptSessionMediaRefs` — validate canonical session media
+ *      references before anything session-scoped is resolved or mutated.
+ *   3. `resolvePromptMediaFiles` — resolve uploads into their context form:
+ *      arbitrary files become path-referenced attachments (a text notice the
+ *      model opens with the Read tool), images are format-gated and
+ *      compressed, and image/video uploads enter context as bare internal
+ *      `kimi-file://` references the engine's prompt intake materializes.
+ *   4. `contentToCoreParts` — project the resolved wire content onto engine
  *      `ContentPart`s.
  *
  * Extracted from `routes/prompts.ts` so `routes/skills.ts` can run the exact
@@ -19,17 +22,19 @@
 import { createHash } from 'node:crypto';
 import { createWriteStream } from 'node:fs';
 import { mkdir, stat, writeFile } from 'node:fs/promises';
-import { extname, join } from 'node:path';
+import { join } from 'node:path';
+import { Readable } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
 
 import {
-  buildKimiFileUrl,
+  buildDaemonFileUrl,
   buildImageCompressionCaption,
   buildUnsupportedImageNotice,
   compressBase64ForModel,
   compressImageForModel,
   decodeBase64Prefix,
   Error2,
+  fileNotFoundError,
   isModelAcceptedImageMime,
   normalizeImageMime,
   persistOriginalImage,
@@ -38,6 +43,7 @@ import {
   type ContentPart,
   type GetResult,
   type IFileService,
+  type ISessionMediaStore,
   type ImageCompressionTelemetry,
   type ITelemetryService,
 } from '@moonshot-ai/agent-core-v2';
@@ -51,15 +57,6 @@ import type { PromptSubmission } from '../protocol/rest-prompt';
  */
 type WireContent = PromptSubmission['content'];
 
-const VIDEO_EXT_BY_MIME: Record<string, string> = {
-  'video/mp4': '.mp4',
-  'video/quicktime': '.mov',
-  'video/webm': '.webm',
-  'video/x-msvideo': '.avi',
-  'video/x-matroska': '.mkv',
-  'video/mpeg': '.mpeg',
-};
-
 /**
  * Fail fast on stale or mis-kinded file references before anything
  * session-scoped happens: a bad `file_id` (unknown, or a real file used with
@@ -78,14 +75,35 @@ export async function assertPromptFileRefs(content: WireContent, store: IFileSer
   }
 }
 
+/**
+ * Fail fast on stale `session_media` references: a file id with no canonical
+ * copy in this session must reject the request before anything is resolved
+ * or mutated.
+ */
+export async function assertPromptSessionMediaRefs(
+  content: WireContent,
+  store: ISessionMediaStore,
+): Promise<void> {
+  for (const part of content) {
+    if (
+      (part.type !== 'image' && part.type !== 'video') ||
+      part.source.kind !== 'session_media'
+    ) continue;
+    const file = await store.open(part.source.file_id);
+    if (file === undefined) throw fileNotFoundError(part.source.file_id);
+  }
+}
+
 export function contentToCoreParts(content: WireContent): ContentPart[] {
   const parts: ContentPart[] = [];
   for (const part of content) {
     if (part.type === 'text') parts.push({ type: 'text', text: part.text });
     else if (part.type === 'image' && part.source.kind === 'url') parts.push({ type: 'image_url', imageUrl: { url: part.source.url, id: part.source.id } });
     else if (part.type === 'image' && part.source.kind === 'base64') parts.push({ type: 'image_url', imageUrl: { url: `data:${part.source.media_type};base64,${part.source.data}` } });
+    else if (part.type === 'image' && part.source.kind === 'session_media') parts.push({ type: 'image_url', imageUrl: { url: buildDaemonFileUrl(part.source.file_id) } });
     else if (part.type === 'video' && part.source.kind === 'url') parts.push({ type: 'video_url', videoUrl: { url: part.source.url, id: part.source.id } });
     else if (part.type === 'video' && part.source.kind === 'base64') parts.push({ type: 'video_url', videoUrl: { url: `data:${part.source.media_type};base64,${part.source.data}` } });
+    else if (part.type === 'video' && part.source.kind === 'session_media') parts.push({ type: 'video_url', videoUrl: { url: buildDaemonFileUrl(part.source.file_id) } });
   }
   return parts;
 }
@@ -109,18 +127,39 @@ export interface ResolvePromptMediaOptions {
   readonly telemetry?: ITelemetryService;
 }
 
+export interface PromptMediaPreparation {
+  readonly content: WireContent;
+  /**
+   * Delete the transient daemon uploads this preparation created (the
+   * compressed re-save). Call on failure, or after the engine has either
+   * materialized the Session-owned copy or terminally rejected the prompt.
+   */
+  readonly discard: () => Promise<void>;
+}
+
 /**
  * Resolve a wire content list's media/file references into their final wire
  * form: uploaded files materialize to a session-local path notice, images are
- * format-gated and compressed, videos materialize to a `kimi-file://`
- * reference. Returns the input array unchanged when nothing needed resolving.
+ * format-gated and compressed, and image/video uploads enter context as bare
+ * internal `kimi-file://` references. The preparation's `content` is the
+ * input array unchanged when nothing needed resolving; `discard` rolls back
+ * or releases the daemon uploads the preparation created after intake.
  */
 export async function resolvePromptMediaFiles(
   input: WireContent,
   store: IFileService,
   cacheDir: string,
   options: ResolvePromptMediaOptions = {},
-): Promise<WireContent> {
+): Promise<PromptMediaPreparation> {
+  const ownedFileIds = new Set<string>();
+  let discarded = false;
+  const discard = async (): Promise<void> => {
+    if (discarded) return;
+    discarded = true;
+    await Promise.all(
+      [...ownedFileIds].map((fileId) => store.delete(fileId).catch(() => undefined)),
+    );
+  };
   let changed = false;
   let originalsDir: string | undefined;
   let originalsDirResolved = false;
@@ -143,209 +182,227 @@ export async function resolvePromptMediaFiles(
   const telemetryFor = (source: string): ImageCompressionTelemetry | undefined =>
     options.telemetry === undefined ? undefined : { client: options.telemetry, source };
   const content: WireContent = [];
-  for (const part of input) {
-    // Inline base64 image: compress the payload in place. This mirrors the v1
-    // server path for REST clients that submit an image without uploading it.
-    if (part.type === 'image' && part.source.kind === 'base64') {
-      // Formats the provider cannot accept must never enter the session
-      // history — one unsupported image_url makes every later request fail.
-      // The bytes are authoritative: an image labeled image/png that is
-      // actually AVIF is gated on the sniffed format, not the label. The
-      // bytes are still the user's content, though: persist them as a
-      // path-referenced attachment so the model can read and convert them
-      // itself (best effort — the plain notice stands in when persisting
-      // fails). Inline base64 has no original name, so the file is addressed
-      // by content hash with a name derived from the sniffed format.
-      const effectiveMime = resolveEffectiveImageMime(
-        part.source.media_type,
-        decodeBase64Prefix(part.source.data),
-      );
-      if (!isModelAcceptedImageMime(effectiveMime)) {
-        const bytes = Buffer.from(part.source.data, 'base64');
-        const name = `image.${imageExtensionForMime(effectiveMime)}`;
-        const persisted = await persistAttachmentBytes(
-          bytes,
-          `${createHash('sha256').update(bytes).digest('hex').slice(0, 32)}-${name}`,
-          await resolveAttachmentsDir(),
+  try {
+    for (const part of input) {
+      // Inline base64 image: compress the payload in place. This mirrors the v1
+      // server path for REST clients that submit an image without uploading it.
+      if (part.type === 'image' && part.source.kind === 'base64') {
+        // Formats the provider cannot accept must never enter the session
+        // history — one unsupported image_url makes every later request fail.
+        // The bytes are authoritative: an image labeled image/png that is
+        // actually AVIF is gated on the sniffed format, not the label. The
+        // bytes are still the user's content, though: persist them as a
+        // path-referenced attachment so the model can read and convert them
+        // itself (best effort — the plain notice stands in when persisting
+        // fails). Inline base64 has no original name, so the file is addressed
+        // by content hash with a name derived from the sniffed format.
+        const effectiveMime = resolveEffectiveImageMime(
+          part.source.media_type,
+          decodeBase64Prefix(part.source.data),
         );
-        content.push({
-          type: 'text',
-          text: persisted === null
-            ? buildUnsupportedImageNotice(effectiveMime)
-            : buildAttachedFileNotice(name, effectiveMime, bytes.length, persisted),
+        if (!isModelAcceptedImageMime(effectiveMime)) {
+          const bytes = Buffer.from(part.source.data, 'base64');
+          const name = `image.${imageExtensionForMime(effectiveMime)}`;
+          const persisted = await persistAttachmentBytes(
+            bytes,
+            `${createHash('sha256').update(bytes).digest('hex').slice(0, 32)}-${name}`,
+            await resolveAttachmentsDir(),
+          );
+          content.push({
+            type: 'text',
+            text: persisted === null
+              ? buildUnsupportedImageNotice(effectiveMime)
+              : buildAttachedFileNotice(name, effectiveMime, bytes.length, persisted),
+          });
+          changed = true;
+          continue;
+        }
+        const canonicalMime = normalizeImageMime(effectiveMime);
+        const compressed = await compressBase64ForModel(part.source.data, canonicalMime, {
+          telemetry: telemetryFor('prompt_inline'),
         });
-        changed = true;
+        if (compressed.changed) {
+          const dir = await resolveOriginalsDir();
+          const originalPath = await persistOriginalImage(
+            Buffer.from(part.source.data, 'base64'),
+            part.source.media_type,
+            { dir },
+          );
+          content.push({
+            type: 'text',
+            text: buildImageCompressionCaption({
+              original: {
+                width: compressed.originalWidth,
+                height: compressed.originalHeight,
+                byteLength: compressed.originalByteLength,
+                mimeType: part.source.media_type,
+              },
+              final: {
+                width: compressed.width,
+                height: compressed.height,
+                byteLength: compressed.finalByteLength,
+                mimeType: compressed.mimeType,
+              },
+              originalPath,
+            }),
+          });
+          content.push({
+            type: 'image',
+            source: { kind: 'base64', media_type: compressed.mimeType, data: compressed.base64 },
+          });
+          changed = true;
+        } else {
+          content.push(part);
+        }
         continue;
       }
-      const canonicalMime = normalizeImageMime(effectiveMime);
-      const compressed = await compressBase64ForModel(part.source.data, canonicalMime, {
-        telemetry: telemetryFor('prompt_inline'),
-      });
-      if (compressed.changed) {
-        const dir = await resolveOriginalsDir();
-        const originalPath = await persistOriginalImage(
-          Buffer.from(part.source.data, 'base64'),
-          part.source.media_type,
-          { dir },
-        );
+
+      // Remote image URL: no bytes to sniff, so reject when its path extension
+      // names a format providers reject (e.g. a link ending in `.avif`) — the
+      // notice keeps the URL so the model can still fetch and convert the
+      // image. Extensionless / unknown URLs pass through to the provider and
+      // the 400 recovery. Image+URL parts that pass are re-emitted unchanged.
+      if (part.type === 'image' && part.source.kind === 'url') {
+        const extMime = unsupportedImageMimeFromUrl(part.source.url);
+        if (extMime !== null) {
+          content.push({ type: 'text', text: buildUnsupportedImageNotice(extMime, part.source.url) });
+          changed = true;
+          continue;
+        }
+        content.push(part);
+        continue;
+      }
+
+      // Arbitrary file attachment: materialize the uploaded bytes next to the
+      // session and replace the part with a path reference — the model opens it
+      // with the Read tool instead of receiving it as a media part.
+      if (part.type === 'file') {
+        const file = await store.get(part.file_id);
+        const attachedPath = await materializeAttachmentToDir(file, await resolveAttachmentsDir());
         content.push({
           type: 'text',
-          text: buildImageCompressionCaption({
-            original: {
-              width: compressed.originalWidth,
-              height: compressed.originalHeight,
-              byteLength: compressed.originalByteLength,
-              mimeType: part.source.media_type,
-            },
-            final: {
-              width: compressed.width,
-              height: compressed.height,
-              byteLength: compressed.finalByteLength,
-              mimeType: compressed.mimeType,
-            },
-            originalPath,
-          }),
-        });
-        content.push({
-          type: 'image',
-          source: { kind: 'base64', media_type: compressed.mimeType, data: compressed.base64 },
+          text: buildAttachedFileNotice(file.meta.name, file.meta.media_type, file.meta.size, attachedPath),
         });
         changed = true;
-      } else {
-        content.push(part);
+        continue;
       }
-      continue;
-    }
 
-    // Remote image URL: no bytes to sniff, so reject when its path extension
-    // names a format providers reject (e.g. a link ending in `.avif`) — the
-    // notice keeps the URL so the model can still fetch and convert the
-    // image. Extensionless / unknown URLs pass through to the provider and
-    // the 400 recovery. Image+URL parts that pass are re-emitted unchanged.
-    if (part.type === 'image' && part.source.kind === 'url') {
-      const extMime = unsupportedImageMimeFromUrl(part.source.url);
-      if (extMime !== null) {
-        content.push({ type: 'text', text: buildUnsupportedImageNotice(extMime, part.source.url) });
-        changed = true;
+      if ((part.type !== 'image' && part.type !== 'video') || part.source.kind !== 'file') {
+        content.push(part);
         continue;
       }
-      content.push(part);
-      continue;
-    }
-
-    // Arbitrary file attachment: materialize the uploaded bytes next to the
-    // session and replace the part with a path reference — the model opens it
-    // with the Read tool instead of receiving it as a media part.
-    if (part.type === 'file') {
-      const file = await store.get(part.file_id);
-      const attachedPath = await materializeAttachmentToDir(file, await resolveAttachmentsDir());
-      content.push({
-        type: 'text',
-        text: buildAttachedFileNotice(file.meta.name, file.meta.media_type, file.meta.size, attachedPath),
-      });
-      changed = true;
-      continue;
-    }
-
-    if ((part.type !== 'image' && part.type !== 'video') || part.source.kind !== 'file') {
-      content.push(part);
-      continue;
-    }
 
-    const file = await store.get(part.source.file_id);
-    assertMediaFile(file, part.type);
-    if (part.type === 'image') {
-      const data = await readFileOrStream(file);
-      let mediaType = file.meta.media_type;
-      let bytes: Uint8Array = data;
-      // Same format gate as the inline path above, and again the bytes are
-      // authoritative: an upload whose Content-Type lies (AVIF bytes sent
-      // as image/png) is gated on the sniffed format. Like the inline path,
-      // keep the bytes as a path-referenced attachment instead of dropping
-      // them (best effort — the plain notice stands in when persisting
-      // fails).
-      mediaType = resolveEffectiveImageMime(mediaType, data);
-      if (!isModelAcceptedImageMime(mediaType)) {
-        const persisted = await persistAttachmentBytes(
-          data,
-          `${file.meta.id}-${sanitizeAttachmentName(file.meta.name)}`,
-          await resolveAttachmentsDir(),
-        );
+      const file = await store.get(part.source.file_id);
+      assertMediaFile(file, part.type);
+      if (part.type === 'image') {
+        const data = await readFileOrStream(file);
+        let mediaType = file.meta.media_type;
+        // Same format gate as the inline path above, and again the bytes are
+        // authoritative: an upload whose Content-Type lies (AVIF bytes sent
+        // as image/png) is gated on the sniffed format. Like the inline path,
+        // keep the bytes as a path-referenced attachment instead of dropping
+        // them (best effort — the plain notice stands in when persisting
+        // fails).
+        mediaType = resolveEffectiveImageMime(mediaType, data);
+        if (!isModelAcceptedImageMime(mediaType)) {
+          const persisted = await persistAttachmentBytes(
+            data,
+            `${file.meta.id}-${sanitizeAttachmentName(file.meta.name)}`,
+            await resolveAttachmentsDir(),
+          );
+          content.push({
+            type: 'text',
+            text: persisted === null
+              ? buildUnsupportedImageNotice(mediaType, file.meta.name)
+              : buildAttachedFileNotice(file.meta.name, mediaType, file.meta.size, persisted),
+          });
+          changed = true;
+          continue;
+        }
+        // Forward the canonical MIME (image/jpg → image/jpeg, case/whitespace)
+        // — strict provider whitelists reject the raw alias.
+        mediaType = normalizeImageMime(mediaType);
+        const compressed = await compressImageForModel(data, mediaType, {
+          telemetry: telemetryFor('prompt_file'),
+        });
+        if (compressed.changed) {
+          const dir = await resolveOriginalsDir();
+          const originalPath = await persistOriginalImage(data, mediaType, { dir });
+          content.push({
+            type: 'text',
+            text: buildImageCompressionCaption({
+              original: {
+                width: compressed.originalWidth,
+                height: compressed.originalHeight,
+                byteLength: compressed.originalByteLength,
+                mimeType: mediaType,
+              },
+              final: {
+                width: compressed.width,
+                height: compressed.height,
+                byteLength: compressed.finalByteLength,
+                mimeType: compressed.mimeType,
+              },
+              originalPath,
+            }),
+          });
+        }
+        // Like an uploaded video, the image enters context as a bare internal
+        // `kimi-file://<id>` reference: the engine's prompt intake
+        // materializes the session-canonical copy and resolves the reference
+        // at request time.
+        // When compression changed the bytes, the reference addresses a NEW
+        // daemon upload holding the final bytes — the client's original
+        // upload stays untouched. The re-save is staging only: read models
+        // project the Session-owned copy, and the route releases this upload
+        // after intake or terminal rejection.
+        let finalFile = file;
+        if (compressed.changed) {
+          const saved = await store.save(
+            Readable.from(Buffer.from(compressed.data)),
+            compressedUploadName(file.meta.name, compressed.mimeType),
+            { mimeType: compressed.mimeType },
+          );
+          // Owned until the content reaches the engine: a preparation failure
+          // rolls the re-save back; successful submission releases it once
+          // intake has materialized the Session-owned copy.
+          ownedFileIds.add(saved.id);
+          finalFile = await store.get(saved.id);
+        }
         content.push({
-          type: 'text',
-          text: persisted === null
-            ? buildUnsupportedImageNotice(mediaType, file.meta.name)
-            : buildAttachedFileNotice(file.meta.name, mediaType, file.meta.size, persisted),
+          type: 'image',
+          source: { kind: 'url', url: buildDaemonFileUrl(finalFile.meta.id) },
         });
         changed = true;
         continue;
       }
-      // Forward the canonical MIME (image/jpg → image/jpeg, case/whitespace)
-      // — strict provider whitelists reject the raw alias.
-      mediaType = normalizeImageMime(mediaType);
-      const compressed = await compressImageForModel(data, mediaType, {
-        telemetry: telemetryFor('prompt_file'),
-      });
-      if (compressed.changed) {
-        const dir = await resolveOriginalsDir();
-        const originalPath = await persistOriginalImage(data, mediaType, { dir });
-        content.push({
-          type: 'text',
-          text: buildImageCompressionCaption({
-            original: {
-              width: compressed.originalWidth,
-              height: compressed.originalHeight,
-              byteLength: compressed.originalByteLength,
-              mimeType: mediaType,
-            },
-            final: {
-              width: compressed.width,
-              height: compressed.height,
-              byteLength: compressed.finalByteLength,
-              mimeType: compressed.mimeType,
-            },
-            originalPath,
-          }),
-        });
-      }
-      bytes = compressed.data;
-      mediaType = compressed.mimeType;
+
+      // Uploaded video: carried into context as a bare internal
+      // `kimi-file://<id>` reference. The engine's prompt intake materializes
+      // the session copy, then resolves the reference to a provider form
+      // (upload / inline / tag) at request time, so the edge never uploads
+      // and never blocks on the provider.
       content.push({
-        type: 'image',
-        source: {
-          kind: 'base64',
-          media_type: mediaType,
-          data: Buffer.from(bytes).toString('base64'),
-        },
+        type: 'video',
+        source: { kind: 'url', url: buildDaemonFileUrl(file.meta.id) },
       });
       changed = true;
-      continue;
     }
-
-    // Uploaded video: materialize a local copy the model can open as a
-    // fallback, and carry the upload into context as an internal
-    // `kimi-file://<id>?path=<materialized path>` reference. The engine
-    // resolves it to a provider form (upload / inline / `<video path>` tag) at
-    // request time, so the edge never uploads and never blocks on the provider.
-    const cachePath = await materializeVideoToCache(file, cacheDir);
-    content.push({
-      type: 'video',
-      source: { kind: 'url', url: buildKimiFileUrl(file.meta.id, cachePath) },
-    });
-    changed = true;
+    return { content: changed ? content : input, discard };
+  } catch (error) {
+    await discard();
+    throw error;
   }
-  return changed ? content : input;
 }
 
-async function materializeVideoToCache(file: GetResult, cacheDir: string): Promise<string> {
-  await mkdir(cacheDir, { recursive: true });
-  const ext = extname(file.meta.name) || (VIDEO_EXT_BY_MIME[file.meta.media_type.toLowerCase()] ?? '.bin');
-  const target = join(cacheDir, `${file.meta.id}${ext}`);
-  const info = await stat(target).catch(() => undefined);
-  if (info?.size === file.meta.size) return target;
-
-  await pipeline(file.stream(), createWriteStream(target));
-  return target;
+/**
+ * Name for the daemon upload holding compressed image bytes: keep the
+ * original base name but take the extension from the final MIME, since the
+ * encoder may have switched formats (png ↔ jpeg).
+ */
+function compressedUploadName(originalName: string, mimeType: string): string {
+  const base = originalName.replace(/\.[^./\\]*$/, '');
+  return `${base.length > 0 ? base : 'image'}.${imageExtensionForMime(mimeType)}`;
 }
 
 const ATTACHMENT_NAME_MAX = 100;
diff --git a/packages/kap-server/src/protocol/error-codes.ts b/packages/kap-server/src/protocol/error-codes.ts
index 770e4841997..26ceb7c152b 100644
--- a/packages/kap-server/src/protocol/error-codes.ts
+++ b/packages/kap-server/src/protocol/error-codes.ts
@@ -130,6 +130,8 @@ export const ErrorCode = {
   /** 当前平台/架构不支持该 capability */
   CAPABILITY_UNSUPPORTED: 40925,
   RUNTIME_UNAVAILABLE: 40926,
+  /** prompt_id 已在该 agent 的历史中使用 */
+  PROMPT_ID_CONFLICT: 40927,
 
   /** approval 60s 超时 */
   APPROVAL_EXPIRED: 41001,
diff --git a/packages/kap-server/src/protocol/events-zod.ts b/packages/kap-server/src/protocol/events-zod.ts
index c7aa95d7660..9927ea93591 100644
--- a/packages/kap-server/src/protocol/events-zod.ts
+++ b/packages/kap-server/src/protocol/events-zod.ts
@@ -379,6 +379,7 @@ export const kimiErrorCodeSchema = z.enum([
   'request.invalid',
   'request.work_dir_required',
   'request.prompt_input_empty',
+  'prompt.id_conflict',
   'prompt.not_found',
   'prompt.already_completed',
   'session.busy',
@@ -703,6 +704,7 @@ export const turnStartedEventSchema = z.object({
   turnId: z.number(),
   origin: promptOriginSchema,
   prompt: z.string().optional(),
+  promptId: z.string().optional(),
 });
 
 export const turnEndedEventSchema = z.object({
diff --git a/packages/kap-server/src/protocol/message.ts b/packages/kap-server/src/protocol/message.ts
index bf1faa14a39..4f1990e8835 100644
--- a/packages/kap-server/src/protocol/message.ts
+++ b/packages/kap-server/src/protocol/message.ts
@@ -5,10 +5,12 @@
  * only the native `ContextMessage`, and `services/messages/messageProjection`
  * projects it into this shape at the edge.
  *
- * Media sources come in three kinds: `url`, `base64`, and `file` (a daemon
- * upload id). The `url` kind optionally pairs an `id` — the provider-issued
- * file id behind a reference such as `ms://…` — forwarded on the wire when
- * the provider keys media by id.
+ * Media sources come in four kinds: `url`, `base64`, `file` (a transient
+ * daemon upload id accepted on input), and `session_media` (the canonical
+ * Session-owned copy returned by stored prompt/message projections). The
+ * `url` kind optionally pairs an `id` — the provider-issued file id behind a
+ * reference such as `ms://…` — forwarded on the wire when the provider keys
+ * media by id.
  */
 
 import { z } from 'zod';
@@ -52,6 +54,7 @@ export const imageSourceSchema = z.discriminatedUnion('kind', [
     data: z.string().min(1),
   }),
   z.object({ kind: z.literal('file'), file_id: z.string().min(1) }),
+  z.object({ kind: z.literal('session_media'), file_id: z.string().min(1) }),
 ]);
 export type ImageSource = z.infer<typeof imageSourceSchema>;
 
diff --git a/packages/kap-server/src/protocol/rest-prompt.ts b/packages/kap-server/src/protocol/rest-prompt.ts
index b04a2fe78af..b1110520aea 100644
--- a/packages/kap-server/src/protocol/rest-prompt.ts
+++ b/packages/kap-server/src/protocol/rest-prompt.ts
@@ -2,7 +2,7 @@
  *   POST /v1/sessions/{sid}/prompts
  *     Body:  PromptSubmission { content, metadata?, agent_id?, profile?, model?, thinking?,
  *              permission_mode?, plan_mode?, swarm_mode?, goal_objective?, goal_control?,
- *              disabled_tools? }
+ *              disabled_tools?, prompt_id? }
  *     Reply: PromptSubmitResult { prompt_id, user_message_id, status, content, created_at }
  *
  *   GET /v1/sessions/{sid}/prompts
@@ -47,6 +47,10 @@ export const promptSubmissionSchema = z.object({
   // bound profile's own deny always survives. Omit to keep the persisted
   // value, send `[]` to clear the client portion.
   disabled_tools: z.array(z.string()).optional(),
+  // Client-chosen prompt record id; the engine echoes it on the consuming
+  // turn's `turn.started` (`promptId`) so the submitter can bind its own
+  // bookkeeping to that turn exactly. Omit to let the engine assign one.
+  prompt_id: z.string().min(1).optional(),
 });
 export type PromptSubmission = z.infer<typeof promptSubmissionSchema>;
 
diff --git a/packages/kap-server/src/routes/files.ts b/packages/kap-server/src/routes/files.ts
index 6d5e8af7323..7b28905a675 100644
--- a/packages/kap-server/src/routes/files.ts
+++ b/packages/kap-server/src/routes/files.ts
@@ -23,6 +23,7 @@ import {
 import { z } from 'zod';
 
 import { requestLog } from '../lib/requestLog';
+import { buildContentDisposition } from '../lib/contentDisposition';
 import { defineRoute } from '../middleware/defineRoute';
 import { ErrorCode } from '../protocol/error-codes';
 import { errEnvelope, okEnvelope } from '../protocol/envelope';
@@ -263,14 +264,6 @@ function readRangeHeader(value: string | string[] | undefined): string | undefin
   return Array.isArray(value) ? value[0] : value;
 }
 
-function buildContentDisposition(name: string, mediaType?: string): string {
-  const disposition = /^(image|video|audio)\//.test(mediaType ?? '') ? 'inline' : 'attachment';
-  if (/^[\w. ()+[\]-]+$/.test(name)) {
-    return `${disposition}; filename="${name}"`;
-  }
-  return disposition;
-}
-
 interface ByteRange {
   start: number;
   end: number;
diff --git a/packages/kap-server/src/routes/prompts.ts b/packages/kap-server/src/routes/prompts.ts
index 4f26880f5d7..b2f5ee49334 100644
--- a/packages/kap-server/src/routes/prompts.ts
+++ b/packages/kap-server/src/routes/prompts.ts
@@ -17,13 +17,14 @@ import {
   IAuthSummaryService,
   IEventService,
   IFileService,
+  ISessionMediaStore,
   ISessionMetadata,
-  parseKimiFileUrl,
   promptMetadataTextFromContentParts,
   ProfileError,
-  type ContentPart,
   type PromptHandle,
   type PromptQueueSnapshot,
+  type PromptReservation,
+  reservePrompt,
   ISessionContext,
   resumeSessionById,
   ITelemetryService,
@@ -36,6 +37,7 @@ import {
   type Scope,
 } from '@moonshot-ai/agent-core-v2';
 import { ErrorCode } from '../protocol/error-codes';
+import { projectPromptContentParts } from '../services/messages/messageProjection';
 import {
   promptAbortResponseSchema,
   promptListResponseSchema,
@@ -43,15 +45,16 @@ import {
   promptSteerResultSchema,
   promptSubmissionSchema,
   promptSubmitResultSchema,
-  type PromptSubmission,
 } from '../protocol/rest-prompt';
 import { z } from 'zod';
 
 import { errEnvelope, okEnvelope } from '../envelope';
 import {
   assertPromptFileRefs,
+  assertPromptSessionMediaRefs,
   contentToCoreParts,
   resolvePromptMediaFiles,
+  type PromptMediaPreparation,
 } from '../lib/promptMedia';
 import { requestLog } from '../lib/requestLog';
 import { defineRoute } from '../middleware/defineRoute';
@@ -200,6 +203,7 @@ export function registerPromptsRoutes(app: PromptRouteHost, core: Scope): void {
         [ErrorCode.AUTH_TOKEN_UNAUTHORIZED]: { detailsSchema: authProviderDetailsSchema },
         [ErrorCode.AUTH_MODEL_NOT_RESOLVED]: { detailsSchema: authModelDetailsSchema },
         [ErrorCode.SESSION_NOT_FOUND]: {},
+        [ErrorCode.PROMPT_ID_CONFLICT]: {},
         [ErrorCode.PROMPT_ALREADY_COMPLETED]: { dataSchema: z.object({ aborted: z.literal(false) }) },
       },
       description: 'Submit a prompt to a session',
@@ -208,22 +212,32 @@ export function registerPromptsRoutes(app: PromptRouteHost, core: Scope): void {
     },
     async (req, reply) => {
       const { session_id } = req.params;
+      let preparedMedia: PromptMediaPreparation | undefined;
+      let reservation: PromptReservation | undefined;
+      let enqueued = false;
       try {
         // Fail fast on stale file references before anything is resolved or
         // mutated: a bad `file_id` must not create the agent, register `main`
         // in session metadata, or touch the session's controls.
         await assertPromptFileRefs(req.body.content, core.accessor.get(IFileService));
-        const resolved = await resolvePrompt(core, session_id, req.body.agent_id);
+        const session = await resolveSession(core, session_id);
+        await assertPromptSessionMediaRefs(
+          req.body.content,
+          session.accessor.get(ISessionMediaStore),
+        );
+        const resolved = await resolvePromptFromSession(session, req.body.agent_id);
+        reservation = reservePrompt(resolved.prompt, req.body.prompt_id);
         await resolved.auth.ensureReady();
 
         // Media resolution runs BEFORE any control mutation, so a failed
         // submission leaves the session's controls untouched. Prompt videos
-        // are materialized to a local copy and carried into context as an
-        // internal `kimi-file://` reference; the engine resolves them to a
-        // provider form (upload / inline / `<video path>` tag) at request
-        // time, so the edge no longer uploads.
+        // and uploaded images are carried into context as bare internal
+        // `kimi-file://` references; the engine's prompt intake materializes
+        // the session copy and resolves them to a provider form
+        // (upload / inline / path tag) at request time, so the edge no longer
+        // uploads.
         const telemetry = core.accessor.get(ITelemetryService).withContext({ sessionId: session_id });
-        const resolvedContent = await resolvePromptMediaFiles(
+        preparedMedia = await resolvePromptMediaFiles(
           req.body.content,
           core.accessor.get(IFileService),
           core.accessor.get(IBootstrapService).cacheDir,
@@ -241,6 +255,7 @@ export function registerPromptsRoutes(app: PromptRouteHost, core: Scope): void {
             },
           },
         );
+        const resolvedContent = preparedMedia.content;
 
         // Media prepared successfully — only now do the overrides bind.
         let thinkingConsumed = false;
@@ -270,21 +285,33 @@ export function registerPromptsRoutes(app: PromptRouteHost, core: Scope): void {
           }
         }
         const parts = contentToCoreParts(resolvedContent);
-        const session = await resolveSession(core, session_id);
         await applyPromptMetadataUpdate({
           metadata: session.accessor.get(ISessionMetadata),
           eventService: core.accessor.get(IEventService),
           sessionId: session_id,
         }, promptMetadataTextFromContentParts(parts));
-        const handle = await resolved.prompt.enqueue({ message: {
+        const handle = await reservation.submit({
           role: 'user',
           content: parts,
           toolCalls: [],
           origin: { kind: 'user' },
-        } });
+        });
+        enqueued = true;
+        const staging = preparedMedia;
+        void Promise.race([handle.launched, handle.completion]).then(
+          () => staging?.discard(),
+          () => staging?.discard(),
+        );
         reply.send(okEnvelope(projectPromptHandle(handle), req.id));
       } catch (error) {
+        // A submission that failed before the engine took the prompt projected
+        // no Session media to the client — roll back the uploads the
+        // preparation created. A successful enqueue releases them when the
+        // prompt launches (intake complete) or settles without launching.
+        if (!enqueued) await preparedMedia?.discard();
         sendMappedError(reply, req, error);
+      } finally {
+        reservation?.dispose();
       }
     },
   );
@@ -379,41 +406,19 @@ function projectPromptSnapshot(prompt: PromptQueueSnapshot['pending'][number]) {
   const status = prompt.state === 'running' || prompt.state === 'steered'
     ? 'running'
     : prompt.state === 'blocked' ? 'blocked' : 'queued';
+  // The prompt queue holds user prompts only; the shared projection maps each
+  // self-contained daemon-ref media part to its `{kind:'session_media'}` wire
+  // shape, mirroring the message projection: the internal URL never reaches
+  // REST callers.
   return {
     prompt_id: prompt.id,
     user_message_id: prompt.userMessageId,
     status,
-    content: corePartsToProtocol(prompt.message.content),
+    content: projectPromptContentParts(prompt.message.content),
     created_at: prompt.createdAt,
   };
 }
 
-function corePartsToProtocol(content: readonly ContentPart[]): PromptSubmission['content'] {
-  const parts: PromptSubmission['content'] = [];
-  for (const part of content) {
-    if (part.type === 'text') parts.push({ type: 'text', text: part.text });
-    else if (part.type === 'image_url') {
-      const match = /^data:([^;]+);base64,(.*)$/.exec(part.imageUrl.url);
-      parts.push(match === null
-        ? { type: 'image', source: { kind: 'url', url: part.imageUrl.url, id: part.imageUrl.id } }
-        : { type: 'image', source: { kind: 'base64', media_type: match[1]!, data: match[2]! } });
-    } else if (part.type === 'video_url') {
-      // An internal `kimi-file://<id>?path=…` reference projects back to the
-      // daemon upload it came from — the materialization path never leaks to
-      // the client.
-      const kimiFile = parseKimiFileUrl(part.videoUrl.url);
-      if (kimiFile !== undefined) {
-        parts.push({ type: 'video', source: { kind: 'file', file_id: kimiFile.fileId } });
-        continue;
-      }
-      const match = /^data:([^;]+);base64,(.*)$/.exec(part.videoUrl.url);
-      parts.push(match === null
-        ? { type: 'video', source: { kind: 'url', url: part.videoUrl.url, id: part.videoUrl.id } }
-        : { type: 'video', source: { kind: 'base64', media_type: match[1]!, data: match[2]! } });
-    }
-  }
-  return parts;
-}
 
 
 function sendMappedError(
@@ -435,6 +440,9 @@ function sendMappedError(
       case 'prompt.not_found':
         reply.send(errEnvelope(ErrorCode.PROMPT_NOT_FOUND, err.message, requestId, err.stack));
         return;
+      case 'prompt.id_conflict':
+        reply.send(errEnvelope(ErrorCode.PROMPT_ID_CONFLICT, err.message, requestId, err.stack));
+        return;
       case 'session.busy':
         reply.send(errEnvelope(ErrorCode.SESSION_BUSY, err.message, requestId, err.stack));
         return;
diff --git a/packages/kap-server/src/routes/registerApiV1Routes.ts b/packages/kap-server/src/routes/registerApiV1Routes.ts
index 008396dd443..1cd286b30fc 100644
--- a/packages/kap-server/src/routes/registerApiV1Routes.ts
+++ b/packages/kap-server/src/routes/registerApiV1Routes.ts
@@ -37,6 +37,7 @@ import { registerPromptsRoutes } from './prompts';
 import { registerQuestionsRoutes } from './questions';
 import { registerRuntimeRoutes } from './runtime';
 import { registerSearchRoutes } from './search';
+import { registerSessionMediaRoutes } from './sessionMedia';
 import { registerSessionExportRoute } from './sessionExport';
 import { registerSessionsRoutes } from './sessions';
 import { registerShutdownRoutes } from './shutdown';
@@ -175,6 +176,10 @@ export async function registerApiV1Routes(
         core,
       );
       registerFilesRoutes(apiV1 as unknown as Parameters<typeof registerFilesRoutes>[0], core);
+      registerSessionMediaRoutes(
+        apiV1 as unknown as Parameters<typeof registerSessionMediaRoutes>[0],
+        core,
+      );
       registerFsRoutes(apiV1 as unknown as Parameters<typeof registerFsRoutes>[0], core);
       registerGuiStoreRoutes(apiV1 as unknown as Parameters<typeof registerGuiStoreRoutes>[0], opts.guiStore);
       registerToolsRoutes(apiV1 as unknown as Parameters<typeof registerToolsRoutes>[0], core);
diff --git a/packages/kap-server/src/routes/sessionMedia.ts b/packages/kap-server/src/routes/sessionMedia.ts
new file mode 100644
index 00000000000..5d42008d7d4
--- /dev/null
+++ b/packages/kap-server/src/routes/sessionMedia.ts
@@ -0,0 +1,158 @@
+/**
+ * Session-canonical media download route.
+ *
+ * Resolves the Session-scoped `ISessionMediaStore` through the workspace /
+ * session lifecycle chain and streams canonical prompt media with browser
+ * byte-range semantics. The session store is canonical, so it is read first;
+ * on a miss the route falls back to the App-scope `IFileService` staged
+ * upload — the engine's prompt intake materializes bytes into the session
+ * store asynchronously and best-effort, so a `session_media` ref is
+ * downloadable during the intake window (and after an intake failure) as
+ * long as the transient daemon upload is still staged. Only a double miss
+ * is a 404.
+ *
+ * NOTE: resolving the session store through `resumeSessionById` fully
+ * RESUMES a cold session — materializing the session scope, creating the
+ * main agent, and firing `session_started` telemetry. Browsing historical
+ * attachments therefore starts the session, unlike the deliberately
+ * cold-reading transcript/messages surface. This asymmetry is an accepted
+ * short-term semantic.
+ * TODO: add a cold-read channel that resolves the sessionDir through
+ * `ISessionIndex` and reads the media storage directly, without resuming.
+ */
+
+import { Readable } from 'node:stream';
+
+import {
+  ISessionMediaStore,
+  type SessionMediaFile,
+} from '@moonshot-ai/agent-core-v2/agent/media/sessionMediaStore';
+import {
+  FileErrors,
+  IFileService,
+  isFileError,
+} from '@moonshot-ai/agent-core-v2/app/file/fileService';
+import { resumeSessionById } from '@moonshot-ai/agent-core-v2/app/sessionManager/sessionLookup';
+import type { Scope } from '@moonshot-ai/agent-core-v2/_base/di/scope';
+import { z } from 'zod';
+
+import { buildContentDisposition } from '../lib/contentDisposition';
+import { parseRangeHeader, pickHeader } from '../lib/httpRange';
+import { defineRoute } from '../middleware/defineRoute';
+import { ErrorCode } from '../protocol/error-codes';
+import { errEnvelope } from '../protocol/envelope';
+
+interface SessionMediaRouteHost {
+  get(
+    path: string,
+    options: { preHandler: unknown[]; schema?: Record<string, unknown> },
+    handler: (req: SessionMediaRequest, reply: SessionMediaReply) => unknown,
+  ): unknown;
+}
+
+interface SessionMediaRequest {
+  readonly id: string;
+  readonly params: { readonly session_id: string; readonly file_id: string };
+  readonly headers: Record<string, unknown>;
+}
+
+interface SessionMediaReply {
+  type(mime: string): SessionMediaReply;
+  header(name: string, value: string | number): SessionMediaReply;
+  code(status: number): SessionMediaReply;
+  send(payload: unknown): unknown;
+}
+
+const sessionMediaParamSchema = z.object({
+  session_id: z.string().min(1),
+  file_id: z.string().min(1),
+});
+
+export function registerSessionMediaRoutes(app: SessionMediaRouteHost, core: Scope): void {
+  const route = defineRoute(
+    {
+      method: 'GET',
+      path: '/sessions/{session_id}/media/{file_id}',
+      params: sessionMediaParamSchema,
+      rawResponse: { 200: { type: 'string', format: 'binary' } },
+      errors: {
+        [ErrorCode.SESSION_NOT_FOUND]: {},
+        [ErrorCode.FILE_NOT_FOUND]: {},
+      },
+      description: 'Download session-canonical prompt media by file ID',
+      tags: ['files'],
+    },
+    async (req, reply) => {
+      const r = reply as unknown as SessionMediaReply;
+      const { session_id, file_id } = req.params;
+      const session = await resumeSessionById(core.accessor, session_id);
+      if (session === undefined) {
+        return r
+          .code(404)
+          .send(
+            errEnvelope(ErrorCode.SESSION_NOT_FOUND, 'session not found', req.id),
+          ) as unknown as void;
+      }
+      let file = await session.accessor.get(ISessionMediaStore).open(file_id);
+      file ??= await openStagedUpload(core, file_id);
+      if (file === undefined) {
+        return r
+          .code(404)
+          .send(
+            errEnvelope(ErrorCode.FILE_NOT_FOUND, 'file not found', req.id),
+          ) as unknown as void;
+      }
+
+      r
+        .type(file.mediaType)
+        .header('content-disposition', buildContentDisposition(file.name, file.mediaType))
+        .header('accept-ranges', 'bytes')
+        .header('etag', `"${session_id}-${file_id}-${file.size}"`);
+
+      const range = parseRangeHeader(pickHeader(req.headers, 'range'), file.size);
+      if (range !== null) {
+        return r
+          .header('content-range', `bytes ${range.start}-${range.end}/${file.size}`)
+          .header('content-length', range.length)
+          .code(206)
+          .send(
+            Readable.from(file.stream({ start: range.start, end: range.end })),
+          ) as unknown as void;
+      }
+      return r
+        .header('content-length', file.size)
+        .code(200)
+        .send(Readable.from(file.stream())) as unknown as void;
+    },
+  );
+  app.get(
+    route.path,
+    route.options,
+    route.handler as unknown as Parameters<SessionMediaRouteHost['get']>[2],
+  );
+}
+
+/**
+ * Staged-upload fallback for the download route: serves the bytes from the
+ * App-scope `IFileService` while the transient daemon upload still exists,
+ * adapting its `GetResult` to the `SessionMediaFile` shape the route serves.
+ * A missing upload (already discarded) reads as `undefined`, so the caller
+ * can fall through to the canonical 404.
+ */
+async function openStagedUpload(
+  core: Scope,
+  fileId: string,
+): Promise<SessionMediaFile | undefined> {
+  try {
+    const uploaded = await core.accessor.get(IFileService).get(fileId);
+    return {
+      name: uploaded.meta.name,
+      mediaType: uploaded.meta.media_type,
+      size: uploaded.meta.size,
+      stream: (range) => uploaded.stream(range),
+    };
+  } catch (error) {
+    if (isFileError(error, FileErrors.codes.FILE_NOT_FOUND)) return undefined;
+    throw error;
+  }
+}
diff --git a/packages/kap-server/src/routes/skills.ts b/packages/kap-server/src/routes/skills.ts
index 987125ccde4..06e20d38a41 100644
--- a/packages/kap-server/src/routes/skills.ts
+++ b/packages/kap-server/src/routes/skills.ts
@@ -88,6 +88,7 @@ import {
   IPluginService,
   ISessionContext,
   ISessionIndex,
+  ISessionMediaStore,
   ISessionSkillCatalog,
   ISkillDiscovery,
   ITelemetryService,
@@ -115,8 +116,10 @@ import { z } from 'zod';
 import { errEnvelope, okEnvelope } from '../envelope';
 import {
   assertPromptFileRefs,
+  assertPromptSessionMediaRefs,
   contentToCoreParts,
   resolvePromptMediaFiles,
+  type PromptMediaPreparation,
 } from '../lib/promptMedia';
 import { requestLog } from '../lib/requestLog';
 import { defineRoute } from '../middleware/defineRoute';
@@ -303,6 +306,7 @@ export function registerSkillsRoutes(app: SkillsRouteHost, core: Scope): void {
         return;
       }
 
+      let preparedMedia: PromptMediaPreparation | undefined;
       try {
         // Attachments run through the same edge pipeline as prompt uploads
         // (validate → materialize → convert) BEFORE the activation starts, so
@@ -328,9 +332,13 @@ export function registerSkillsRoutes(app: SkillsRouteHost, core: Scope): void {
             );
           }
           await assertPromptFileRefs(attachments, core.accessor.get(IFileService));
+          await assertPromptSessionMediaRefs(
+            attachments,
+            resolved.handle.accessor.get(ISessionMediaStore),
+          );
           const telemetry = core.accessor.get(ITelemetryService).withContext({ sessionId: session_id });
           const sessionDir = resolved.handle.accessor.get(ISessionContext).sessionDir;
-          const resolvedContent = await resolvePromptMediaFiles(
+          preparedMedia = await resolvePromptMediaFiles(
             attachments,
             core.accessor.get(IFileService),
             core.accessor.get(IBootstrapService).cacheDir,
@@ -340,7 +348,7 @@ export function registerSkillsRoutes(app: SkillsRouteHost, core: Scope): void {
               resolveAttachmentsDir: async () => join(sessionDir, 'attachments'),
             },
           );
-          attachmentParts.push(...contentToCoreParts(resolvedContent));
+          attachmentParts.push(...contentToCoreParts(preparedMedia.content));
         }
         const agent = await ensureMainAgent(resolved.handle);
         // The engine applies the prompt-metadata update itself (main agent
@@ -349,9 +357,14 @@ export function registerSkillsRoutes(app: SkillsRouteHost, core: Scope): void {
         await agent.accessor
           .get(IAgentSkillService)
           .activate({ name: parsed.id, args: req.body.args, content: attachmentParts });
+        // Intake materialized the session-owned copies — release the
+        // preparation's uploads, and keep them released on the success path.
+        await preparedMedia?.discard();
+        preparedMedia = undefined;
         requestLog(req)?.info({ session_id, skill_name: parsed.id }, 'skill activated');
         reply.send(okEnvelope({ activated: true, skill_name: parsed.id }, req.id));
       } catch (err) {
+        await preparedMedia?.discard();
         sendMappedError(reply, req.id, err);
       }
     },
diff --git a/packages/kap-server/src/routes/transcript.ts b/packages/kap-server/src/routes/transcript.ts
index 6734f393c31..95b95d9bf27 100644
--- a/packages/kap-server/src/routes/transcript.ts
+++ b/packages/kap-server/src/routes/transcript.ts
@@ -25,7 +25,8 @@
  * that holds watermark N converge without a full refresh.
  *
  * `GET /sessions/{session_id}/transcript/user-messages` projects every
- * turn-opening input (turns with a defined `prompt`) out of the transcript,
+ * turn-opening input (turns with a defined `prompt`, plus attachment-only
+ * prompts normalized to `""`) out of the transcript,
  * grouped per agent — agents are separate transcripts, so user messages are
  * per-agent by construction. It reads the same live-store / cold-rebuild
  * paths as the paged route, but unpaginated (user messages are few compared
@@ -347,7 +348,7 @@ export function registerTranscriptRoutes(app: TranscriptRouteHost, deps: Transcr
         [ErrorCode.SESSION_NOT_FOUND]: {},
       },
       description:
-        'All turn-opening inputs ("user messages") of a session, grouped per agent: every turn with a defined prompt (real user text, user-slash skill/plugin commands, cron prompts — distinguish via origin). agent_id optional: present reads one agent, absent reads every rostered agent. Live sessions answer from the in-memory store (history backfill awaited per agent), cold sessions rebuild from the persisted wire records. Unpaginated; attachment entities referenced by the messages ride along (metadata only)',
+        'All turn-opening inputs ("user messages") of a session, grouped per agent: every turn with a defined prompt (real user text, user-slash skill/plugin commands, cron prompts — distinguish via origin), plus attachment-only prompts projected with an empty prompt string. agent_id optional: present reads one agent, absent reads every rostered agent. Live sessions answer from the in-memory store (history backfill awaited per agent), cold sessions rebuild from the persisted wire records. Unpaginated; attachment entities referenced by the messages ride along (metadata only)',
       tags: ['transcript'],
     },
     async (req, reply) => {
@@ -484,9 +485,13 @@ interface UserMessageEntry {
 
 /**
  * Project the user messages out of one agent's full timeline: every turn with
- * a defined prompt, in timeline order. `resolveAttachment` looks up the
- * referenced entities (live: the store's attachment map; cold: the snapshot's
- * array) so the response carries their metadata alongside the ids.
+ * a defined prompt, in timeline order. An attachment-only prompt folds to no
+ * text — live turns then carry `prompt: undefined` while the cold rebuild
+ * yields `""`; both normalize to `""` here so the two paths list the same
+ * messages. A genuinely promptless turn (no text, no attachments) stays
+ * projected out. `resolveAttachment` looks up the referenced entities (live:
+ * the store's attachment map; cold: the snapshot's array) so the response
+ * carries their metadata alongside the ids.
  */
 function projectUserMessages(
   items: readonly TranscriptItem[],
@@ -495,13 +500,15 @@ function projectUserMessages(
   const messages: UserMessageEntry[] = [];
   const attachments = new Map<string, TranscriptAttachment>();
   for (const item of items) {
-    if (item.kind !== 'turn' || item.prompt === undefined) continue;
+    if (item.kind !== 'turn') continue;
+    const hasAttachments = item.attachmentIds !== undefined && item.attachmentIds.length > 0;
+    if (item.prompt === undefined && !hasAttachments) continue;
     messages.push({
       turn_id: item.turnId,
       ordinal: item.ordinal,
       state: item.state,
       origin: item.origin,
-      prompt: item.prompt,
+      prompt: item.prompt ?? '',
       attachment_ids: item.attachmentIds,
       started_at: item.startedAt,
     });
diff --git a/packages/kap-server/src/search/wireExtract.ts b/packages/kap-server/src/search/wireExtract.ts
index d3c7598d267..a71d4720e81 100644
--- a/packages/kap-server/src/search/wireExtract.ts
+++ b/packages/kap-server/src/search/wireExtract.ts
@@ -25,6 +25,8 @@
  * Kept free of any service / filesystem dependency so it is unit-testable.
  */
 
+import { matchSingleMediaPathTag } from '@moonshot-ai/agent-core-v2/agent/media/mediaRef';
+
 export interface ExtractedWireMessage {
   readonly role: 'user' | 'assistant';
   readonly text: string;
@@ -153,18 +155,24 @@ interface ContentPartLike {
   readonly text?: unknown;
 }
 
+/**
+ * The user-visible text of a persisted message: text parts concatenated,
+ * skipping standalone `<media path>` tag parts. A standalone tag is machine
+ * markup (the upload residue of legacy sessions, or the model-facing degrade
+ * form) and carries the materialization path, so it must never reach the
+ * index — matching the other read models, which never treat it as searchable
+ * prose either. A tag embedded in larger user text is indexed with that text:
+ * stripping there would eat user content.
+ */
 function textOfContent(content: unknown): string {
   if (!Array.isArray(content)) return '';
   let text = '';
-  for (const part of content as readonly ContentPartLike[]) {
-    if (
-      part !== null &&
-      typeof part === 'object' &&
-      part.type === 'text' &&
-      typeof part.text === 'string'
-    ) {
-      text += part.text;
-    }
+  for (const raw of content as readonly unknown[]) {
+    if (raw === null || typeof raw !== 'object') continue;
+    const part = raw as ContentPartLike;
+    if (part.type !== 'text' || typeof part.text !== 'string') continue;
+    if (matchSingleMediaPathTag(part.text) !== undefined) continue;
+    text += part.text;
   }
   return text;
 }
diff --git a/packages/kap-server/src/services/messages/messageProjection.ts b/packages/kap-server/src/services/messages/messageProjection.ts
index ad846f01ee9..a78acc239f3 100644
--- a/packages/kap-server/src/services/messages/messageProjection.ts
+++ b/packages/kap-server/src/services/messages/messageProjection.ts
@@ -12,15 +12,22 @@
  * array through, the same shape the live `tool.result` event stream carries,
  * so REST consumers can still render the media after reload/resume.
  *
- * A user `video_url` part projects to a structured `video` content part so
- * REST consumers can render it: an internal `kimi-file://<id>?path=…`
- * reference becomes `{ kind: 'file', file_id }` (the materialization path is
- * stripped, never leaked to clients); any other url becomes `{ kind: 'url' }`
- * carrying the provider id. An `audio_url` part still flattens to a text
- * marker.
+ * A user `image_url` / `video_url` part projects to a structured `image` /
+ * `video` content part so REST consumers can render it: an internal
+ * `kimi-file://<id>` reference becomes
+ * `{ kind: 'session_media', file_id }` (the internal URL never reaches
+ * clients); any other url becomes `{ kind: 'url' }` carrying
+ * the provider id. An `audio_url` part still flattens to a text marker.
+ *
+ * A daemon-ref media part is self-contained (`daemonFileRefFromPart`): the
+ * part type carries the kind and the reference the file id, so the
+ * projection walks the raw parts directly — there is no tag+ref pairing to
+ * fold. A standalone `<media path>` tag text part is user text or the legacy
+ * degrade form and passes through verbatim. Assistant output passes through
+ * verbatim.
  */
 
-import { parseKimiFileUrl, type ContextMessage } from '@moonshot-ai/agent-core-v2';
+import { daemonFileRefFromPart, parseDaemonFileUrl, type ContentPart, type ContextMessage } from '@moonshot-ai/agent-core-v2';
 
 import type { Message, MessageContent, MessageRole, ToolUseContent } from '../../protocol/message';
 
@@ -43,17 +50,20 @@ function mapContentPart(part: ContextMessage['content'][number]): MessageContent
         ? { type: 'thinking', thinking: part.think, signature: sig }
         : { type: 'thinking', thinking: part.think };
     }
-    case 'image_url':
-      return {
-        type: 'image',
-        source: { kind: 'url', url: part.imageUrl.url, id: part.imageUrl.id },
-      };
+    case 'image_url': {
+      // Same daemon-reference rule as `video_url`: an internal reference
+      // projects to the Session-owned copy created during prompt intake.
+      const ref = parseDaemonFileUrl(part.imageUrl.url);
+      return ref !== undefined
+        ? { type: 'image', source: { kind: 'session_media', file_id: ref.fileId } }
+        : { type: 'image', source: { kind: 'url', url: part.imageUrl.url, id: part.imageUrl.id } };
+    }
     case 'audio_url':
       return { type: 'text', text: `[audio:${part.audioUrl.url}]` };
     case 'video_url': {
-      const ref = parseKimiFileUrl(part.videoUrl.url);
+      const ref = parseDaemonFileUrl(part.videoUrl.url);
       return ref !== undefined
-        ? { type: 'video', source: { kind: 'file', file_id: ref.fileId } }
+        ? { type: 'video', source: { kind: 'session_media', file_id: ref.fileId } }
         : { type: 'video', source: { kind: 'url', url: part.videoUrl.url, id: part.videoUrl.id } };
     }
   }
@@ -86,6 +96,9 @@ function buildProtocolContent(msg: ContextMessage): MessageContent[] {
     return [part];
   }
 
+  // User and assistant content both map part-by-part: daemon-ref media parts
+  // are self-contained and project to `session_media` sources inside
+  // `mapContentPart`; standalone `<media path>` tags stay text.
   const base = msg.content.map((p) => mapContentPart(p));
 
   if (msg.role === 'assistant' && msg.toolCalls.length > 0) {
@@ -111,6 +124,41 @@ function buildProtocolContent(msg: ContextMessage): MessageContent[] {
   return base;
 }
 
+/**
+ * Prompt content (engine kosong parts) → the v1 wire `messageContentSchema`
+ * shape. Shared by every prompt-queue surface — the REST prompt list, the
+ * `prompt.steered` session event, and the transcript prompt entity — so a
+ * self-contained daemon-ref media part projects back to
+ * `{ kind: 'session_media', file_id }`: neither the transient App upload nor
+ * the internal `kimi-file://` URL becomes the stored read-model contract.
+ */
+export function projectPromptContentParts(content: readonly ContentPart[]): MessageContent[] {
+  const parts: MessageContent[] = [];
+  for (const part of content) {
+    const daemonRef = daemonFileRefFromPart(part);
+    if (daemonRef !== undefined) {
+      parts.push({
+        type: daemonRef.kind,
+        source: { kind: 'session_media', file_id: daemonRef.ref.fileId },
+      });
+      continue;
+    }
+    if (part.type === 'text') parts.push({ type: 'text', text: part.text });
+    else if (part.type === 'image_url') {
+      const match = /^data:([^;]+);base64,(.*)$/.exec(part.imageUrl.url);
+      parts.push(match === null
+        ? { type: 'image', source: { kind: 'url', url: part.imageUrl.url, id: part.imageUrl.id } }
+        : { type: 'image', source: { kind: 'base64', media_type: match[1]!, data: match[2]! } });
+    } else if (part.type === 'video_url') {
+      const match = /^data:([^;]+);base64,(.*)$/.exec(part.videoUrl.url);
+      parts.push(match === null
+        ? { type: 'video', source: { kind: 'url', url: part.videoUrl.url, id: part.videoUrl.id } }
+        : { type: 'video', source: { kind: 'base64', media_type: match[1]!, data: match[2]! } });
+    }
+  }
+  return parts;
+}
+
 export function toProtocolMessage(
   sessionId: string,
   index: number,
diff --git a/packages/kap-server/src/services/transcript/coreBinding.ts b/packages/kap-server/src/services/transcript/coreBinding.ts
index e32e6b7b042..9cb01e2555e 100644
--- a/packages/kap-server/src/services/transcript/coreBinding.ts
+++ b/packages/kap-server/src/services/transcript/coreBinding.ts
@@ -147,6 +147,11 @@ export function bindSessionTranscript(
           const turn = view?.state().turn;
           return turn === undefined || `t${turn.turnId}` !== turnId ? undefined : turn.step;
         },
+        // A projector that attached mid-turn never saw `turn.started`: let its
+        // terminal upsert inherit the header the backfill seeded into the
+        // store (origin / prompt / attachmentIds) instead of clobbering them
+        // — `turn.upsert` is a whole-header replace downstream.
+        turn: (turnId) => store.getAgent(agentId)?.getTurn(turnId),
       });
       projectors.set(agentId, projector);
     }
diff --git a/packages/kap-server/src/services/transcript/coreEventMap.ts b/packages/kap-server/src/services/transcript/coreEventMap.ts
index e2c2ae71c90..eed4ca9a6db 100644
--- a/packages/kap-server/src/services/transcript/coreEventMap.ts
+++ b/packages/kap-server/src/services/transcript/coreEventMap.ts
@@ -7,7 +7,11 @@
  *     on `frame.upsert` (whole frame state) and `append` (deltas).
  *   - The turn prompt arrives on `turn.started` itself
  *     (`TurnStartedEvent.prompt`) — the context append carrying the same text
- *     is not a bus event and lands after the turn header.
+ *     is not a bus event and lands after the turn header. Upload media
+ *     referenced by the prompt ride the same event (`promptAttachments`),
+ *     projected as `attachment.upsert` entities plus `turn.attachmentIds` —
+ *     one attachment per daemon-referenced upload — the daemon-ref part is
+ *     self-contained, no `<media path>` tag is authored engine-side.
  *   - Flush: at step/turn completion boundaries every open text/thinking frame
  *     of that step is re-emitted as a full-text `frame.upsert` — this is how
  *     'block'-grade subscribers (who never see `append`) reconverge.
@@ -74,6 +78,7 @@ import type {
   TextFrame,
   ToolCallFrame,
   ToolFrameProgress,
+  TranscriptAttachment,
   TranscriptFrame,
   TranscriptInteraction,
   TranscriptMarker,
@@ -88,6 +93,7 @@ import type {
 } from '@moonshot-ai/transcript';
 
 import { toLegacyPhase } from '../legacyStatus/legacyStatus';
+import { projectPromptContentParts } from '../messages/messageProjection';
 
 // ---------------------------------------------------------------------------
 // Interaction view (structural — the kernel's `Interaction` narrowed to the
@@ -111,6 +117,8 @@ export interface ProjectorInteraction {
  */
 type PlanRevisionEvent = Extract<DomainEvent, { type: 'plan.revision' }>;
 
+type TurnStartedBusEvent = Extract<DomainEvent, { type: 'turn.started' }>;
+
 type AgentActivityUpdatedEvent = Extract<DomainEvent, { type: 'agent.activity.updated' }>;
 type PromptCompletedEvent = Extract<DomainEvent, { type: 'prompt.completed' }>;
 type PromptAbortedEvent = Extract<DomainEvent, { type: 'prompt.aborted' }>;
@@ -155,11 +163,19 @@ export type ProjectorToolFrameLookup = (toolCallId: string) => ToolFrameRecord |
  */
 export type ProjectorStepOrdinalLookup = (turnId: string) => number | undefined;
 
+/**
+ * Read access to one turn's current header (the producer store). Used when
+ * the projector attached mid-turn and never saw `turn.started` — see
+ * `onTurnEnded`.
+ */
+export type ProjectorTurnLookup = (turnId: string) => TurnHeader | undefined;
+
 /** Optional producer-store lookups that let the projector adopt seeded state. */
 export interface ProjectorLookups {
   readonly stepFrames?: ProjectorFrameLookup;
   readonly toolFrame?: ProjectorToolFrameLookup;
   readonly stepOrdinal?: ProjectorStepOrdinalLookup;
+  readonly turn?: ProjectorTurnLookup;
 }
 
 interface OpenTextFrame {
@@ -296,13 +312,25 @@ export class AgentTranscriptProjector {
 
   // ---------------------------------------------------------------- turn / step
 
-  private onTurnStarted(event: {
-    turnId: number;
-    origin: unknown;
-    prompt?: string;
-  }): TranscriptOperation[] {
+  private onTurnStarted(event: TurnStartedBusEvent): TranscriptOperation[] {
     const n = event.turnId;
     const turnId = `t${n}`;
+    const ops: TranscriptOperation[] = [];
+    let attachmentIds: string[] | undefined;
+    if (event.promptAttachments !== undefined && event.promptAttachments.length > 0) {
+      attachmentIds = [];
+      for (const input of event.promptAttachments) {
+        // Turn-scoped id namespace: cold-rebuild attachments use `att_<n>`,
+        // so a live id can never collide with a backfilled one.
+        const attachment: TranscriptAttachment = {
+          attachmentId: `${turnId}.att${attachmentIds.length + 1}`,
+          mediaType: `${input.kind}/*`,
+          source: { kind: 'session_media', fileId: input.fileId },
+        };
+        ops.push({ op: 'attachment.upsert', attachment });
+        attachmentIds.push(attachment.attachmentId);
+      }
+    }
     this.currentTurn = {
       kind: 'turn',
       turnId,
@@ -310,12 +338,14 @@ export class AgentTranscriptProjector {
       state: 'running',
       origin: mapTurnOrigin(event.origin),
       prompt: event.prompt,
+      attachmentIds,
       startedAt: nowIso(),
     };
     this.currentStep = undefined;
     this.openText = undefined;
     this.openThinking = undefined;
-    return [{ op: 'turn.upsert', turn: this.currentTurn }];
+    ops.push({ op: 'turn.upsert', turn: this.currentTurn });
+    return ops;
   }
 
   private onTurnEnded(event: {
@@ -335,7 +365,13 @@ export class AgentTranscriptProjector {
       this.currentStep = step;
       ops.push({ op: 'step.upsert', turnId: step.turnId, step });
     }
-    const prev = this.currentTurn?.turnId === turnId ? this.currentTurn : undefined;
+    // Mid-turn attach: when this projector never saw `turn.started`, inherit
+    // the header the history backfill already seeded into the store —
+    // otherwise this terminal upsert (a whole-header replace downstream)
+    // would wipe the backfilled origin / prompt / attachmentIds until the
+    // next heal, and for good if the session closes before it runs.
+    const prev =
+      this.currentTurn?.turnId === turnId ? this.currentTurn : this.lookups?.turn?.(turnId);
     const state = mapTurnEndState(event.reason);
     this.currentTurn = {
       kind: 'turn',
@@ -344,6 +380,7 @@ export class AgentTranscriptProjector {
       state,
       origin: prev?.origin ?? { kind: 'other' },
       prompt: prev?.prompt,
+      attachmentIds: prev?.attachmentIds,
       startedAt: prev?.startedAt,
       endedAt: nowIso(),
       durationMs: event.durationMs,
@@ -1307,11 +1344,14 @@ export class AgentTranscriptProjector {
    */
   private onPromptSteered(event: PromptSteeredEvent): TranscriptOperation[] {
     const ops: TranscriptOperation[] = [];
+    // The event carries raw engine content parts (internal `kimi-file://<id>`
+    // daemon refs); the entity stores the Session-media wire projection, so
+    // the transient App upload and internal URL never reach consumers.
     const active = this.upsertPrompt(event.activePromptId, (prev) => ({
       promptId: event.activePromptId,
       status: prev?.status ?? 'running',
       userMessageId: prev?.userMessageId,
-      content: event.content,
+      content: projectPromptContentParts(event.content),
       createdAt: prev?.createdAt ?? event.steeredAt,
       finishedAt: prev?.finishedAt,
       steeredAt: event.steeredAt,
diff --git a/packages/kap-server/src/services/transcript/transcriptService.ts b/packages/kap-server/src/services/transcript/transcriptService.ts
index b3da0ebda83..3a8a3be9632 100644
--- a/packages/kap-server/src/services/transcript/transcriptService.ts
+++ b/packages/kap-server/src/services/transcript/transcriptService.ts
@@ -278,8 +278,14 @@ export class TranscriptService {
       // while the records were being read (a tool frame's display/approvalId,
       // a longer text frame) must not be replaced by the staler persisted
       // version.
+      const superseded = supersededColdAttachmentIds(snapshot, transcript);
       const ops = snapshotToOps(snapshot, (turn) =>
         healTurnOps(turn, transcript.getTurn(turn.turnId)),
+      ).filter(
+        // The merge keeps a live-opened turn's own attachment ids, so the
+        // snapshot's cold `att_<n>` counterparts would land unreferenced —
+        // drop them instead of orphaning duplicate entities.
+        (op) => op.op !== 'attachment.upsert' || !superseded.has(op.attachment.attachmentId),
       );
       const overlay = this.liveTurnOverlay(sessionId, agentId, transcript, snapshot);
       if (overlay !== undefined) ops.push(overlay);
@@ -472,6 +478,10 @@ export class TranscriptService {
         state: 'running',
         origin: existing?.origin ?? snapshotTurn?.origin ?? { kind: 'other' },
         prompt: existing?.prompt ?? snapshotTurn?.prompt,
+        // `turn.upsert` replaces the whole header, so the live attachment ids
+        // must ride along — omitting them would clear the references and
+        // orphan the live `{turnId}.att<N>` entities.
+        attachmentIds: existing?.attachmentIds ?? snapshotTurn?.attachmentIds,
         startedAt: existing?.startedAt ?? snapshotTurn?.startedAt,
       },
     };
@@ -506,12 +516,27 @@ export class TranscriptService {
     if (snapshot === undefined || this.live.get(sessionId)?.store !== entry.store) return;
     const transcript = entry.store.getAgent(agentId);
     if (transcript === undefined) return;
-    const ops: TranscriptOperation[] = [];
+    const turnOps: TranscriptOperation[] = [];
     for (const item of snapshot.items) {
       if (item.kind !== 'turn' || !ordinals.has(item.ordinal)) continue;
-      ops.push(...healTurnOps(item, transcript.getTurn(item.turnId)));
+      turnOps.push(...healTurnOps(item, transcript.getTurn(item.turnId)));
     }
-    if (ops.length === 0) return;
+    if (turnOps.length === 0) return;
+    // Attachment entities are global (not turn-scoped): upsert the snapshot's
+    // set alongside the healed turns so their `attachmentIds` never dangle.
+    // Cold counterparts of turns the live projector already opened with its
+    // own attachment ids are skipped — the heal keeps the live ids, so those
+    // `att_<n>` entities would be orphaned duplicates.
+    const superseded = supersededColdAttachmentIds(snapshot, transcript);
+    const ops: TranscriptOperation[] = [
+      ...snapshot.attachments
+        .filter((attachment) => !superseded.has(attachment.attachmentId))
+        .map((attachment) => ({
+          op: 'attachment.upsert' as const,
+          attachment,
+        })),
+      ...turnOps,
+    ];
     transcript.apply(ops);
     // Fan the heal out like any mapped-op batch so attached subscribers
     // converge; all ops are state-style upserts.
@@ -605,7 +630,8 @@ export class TranscriptService {
  * Flatten a snapshot into idempotent upsert ops (turn/step/frame upserts,
  * standalone items, tasks, meta). Deliberately never a `reset`: upserts merge
  * by id and keep ordinal order, so the backfill cannot clobber live ops that
- * landed while the records were being read.
+ * landed while the records were being read. Global attachment entities flatten
+ * too — without them a backfilled turn's `attachmentIds` would dangle.
  *
  * Standalone items (markers / taskrefs) carry a `beforeTurn` placement anchor:
  * the reducer's standalone path is append-only, so without an anchor a
@@ -649,6 +675,9 @@ export function snapshotToOps(
   // precede the engine's next live turn (`lastTurnOrdinal + 1`, matched
   // robustly by the reducer's `>=` placement when ordinals drift).
   flushPending(lastTurnOrdinal === undefined ? undefined : lastTurnOrdinal + 1);
+  for (const attachment of snapshot.attachments) {
+    ops.push({ op: 'attachment.upsert', attachment });
+  }
   for (const task of snapshot.tasks) {
     ops.push({ op: 'task.upsert', task });
   }
@@ -679,13 +708,39 @@ const TERMINAL_TURN_STATES: ReadonlySet<TranscriptTurn['state']> = new Set([
   'cancelled',
 ]);
 
+/**
+ * Cold attachment ids superseded by live ones. A turn the live projector
+ * already opened carries its own `{turnId}.att<N>` attachment ids, and the
+ * live-first merges (heal / overlay) keep them; the snapshot's cold `att_<n>`
+ * counterparts of THAT turn must not be upserted alongside — nothing would
+ * reference them (orphan duplicate entities). Cold ids are unique per
+ * snapshot (`att_${attachments.length + 1}` counts across the whole rebuild),
+ * so each id belongs to exactly one turn.
+ */
+function supersededColdAttachmentIds(
+  snapshot: AgentTranscriptSnapshot,
+  transcript: AgentTranscript,
+): ReadonlySet<string> {
+  const superseded = new Set<string>();
+  for (const item of snapshot.items) {
+    if (item.kind !== 'turn' || item.attachmentIds === undefined) continue;
+    const live = transcript.getTurn(item.turnId);
+    if (live?.attachmentIds === undefined || live.attachmentIds.length === 0) continue;
+    for (const id of item.attachmentIds) superseded.add(id);
+  }
+  return superseded;
+}
+
 /**
  * Merge one persisted (snapshot) turn back into the live store after the turn
  * ended — the post-turn heal for mid-turn attaches:
  *   - turn the live store never saw: taken wholesale;
  *   - header: the snapshot is authoritative for origin/prompt (it reads the
  *     persisted user message, which a mid-turn-attached projector missed);
- *     the live header wins on state and timestamps;
+ *     the live header wins on state, timestamps, and attachment ids (its
+ *     `{turnId}.att<N>` entities are already projected — swapping in the
+ *     snapshot's cold `att_<n>` ids would churn the references and orphan
+ *     the live entities);
  *   - steps the live turn never saw: taken wholesale from the snapshot;
  *   - existing steps: text/thinking frames are re-emitted only when the
  *     persisted text is longer and the kind matches (a fresh live frame may
@@ -721,6 +776,7 @@ export function healTurnOps(
       ...header,
       state: liveTurn.state,
       prompt: liveTurn.prompt ?? header.prompt,
+      attachmentIds: liveTurn.attachmentIds ?? header.attachmentIds,
       startedAt: liveTurn.startedAt ?? header.startedAt,
       endedAt: liveTurn.endedAt ?? header.endedAt,
     },
diff --git a/packages/kap-server/src/transport/errors.ts b/packages/kap-server/src/transport/errors.ts
index 5994cee19e2..3d0981f977a 100644
--- a/packages/kap-server/src/transport/errors.ts
+++ b/packages/kap-server/src/transport/errors.ts
@@ -41,6 +41,7 @@ const KIMI_TO_PROTOCOL: Record<string, ErrorCode> = {
   [ErrorCodes.FS_PATH_NOT_FOUND]: ErrorCode.FS_PATH_NOT_FOUND,
   [ErrorCodes.SESSION_BUSY]: ErrorCode.SESSION_BUSY,
   [ErrorCodes.PROMPT_ALREADY_COMPLETED]: ErrorCode.PROMPT_ALREADY_COMPLETED,
+  [ErrorCodes.PROMPT_ID_CONFLICT]: ErrorCode.PROMPT_ID_CONFLICT,
   [ErrorCodes.GOAL_ALREADY_EXISTS]: ErrorCode.GOAL_ALREADY_EXISTS,
   [ErrorCodes.GOAL_NOT_FOUND]: ErrorCode.GOAL_NOT_FOUND,
   [ErrorCodes.GOAL_STATUS_INVALID]: ErrorCode.GOAL_STATUS_INVALID,
diff --git a/packages/kap-server/src/transport/ws/v1/sessionEventBroadcaster.ts b/packages/kap-server/src/transport/ws/v1/sessionEventBroadcaster.ts
index bdadd1b408b..66571fe6c4e 100644
--- a/packages/kap-server/src/transport/ws/v1/sessionEventBroadcaster.ts
+++ b/packages/kap-server/src/transport/ws/v1/sessionEventBroadcaster.ts
@@ -102,6 +102,7 @@ import {
 
 import { toWireApproval } from '../../../routes/approvals';
 import { toWireQuestion } from '../../../routes/questions';
+import { projectPromptContentParts } from '../../../services/messages/messageProjection';
 import { readLegacyStatus, toLegacyPhase } from '../../../services/legacyStatus/legacyStatus';
 import type { TranscriptService } from '../../../services/transcript/transcriptService';
 import { InFlightTurnTracker } from './inFlightTurnTracker';
@@ -1154,7 +1155,35 @@ export class SessionEventBroadcaster {
     // ported from the former `record.signal(agentEvent)` call sites); the declared
     // `DomainEventMap` payload types are deliberately wider than the protocol
     // contract, hence the assertion via `unknown`.
-    const wireEvent = { ...event, agentId, sessionId } as unknown as Event;
+    let wireEvent: Event;
+    if (event.type === 'turn.started') {
+      // `promptAttachments` is an internal transcript-projection input, not part
+      // of the v1 wire contract (`turnStartedEventSchema` stops at
+      // {type, turnId, origin, prompt?, promptId?}). Strip it at the edge so the
+      // payload — video-prompt turns included — keeps exactly the
+      // pre-attachment field set (plus the optional `promptId` echo). The
+      // journal records this same stripped envelope, so the one strip covers
+      // live fan-out and every replay path (memory tail + cursor read).
+      const { promptAttachments: _internal, ...wireFields } = event;
+      wireEvent = { ...wireFields, agentId, sessionId } as unknown as Event;
+    } else if (event.type === 'prompt.steered' || event.type === 'prompt.queued') {
+      // `content` arrives as raw engine content parts carrying internal
+      // `kimi-file://<id>` daemon references. Each self-contained ref
+      // projects to one `{kind:'session_media'}` part, so neither the
+      // transient upload nor the internal URL leaves the process (for
+      // steered, the declared `promptSteeredEventSchema` content is
+      // `messageContentSchema`).
+      // Projecting before the journal write covers live fan-out and every
+      // replay path with one mapping.
+      wireEvent = {
+        ...event,
+        content: projectPromptContentParts(event.content),
+        agentId,
+        sessionId,
+      } as unknown as Event;
+    } else {
+      wireEvent = { ...event, agentId, sessionId } as unknown as Event;
+    }
     const volatile = isVolatileSignal(event.type);
     state.queue = state.queue
       .then(() => this.dispatch(state, wireEvent, volatile))
diff --git a/packages/kap-server/test/__snapshots__/apiSurface.snapshot.test.ts.snap b/packages/kap-server/test/__snapshots__/apiSurface.snapshot.test.ts.snap
index 8f9cb3cad04..b2316ba2c0e 100644
--- a/packages/kap-server/test/__snapshots__/apiSurface.snapshot.test.ts.snap
+++ b/packages/kap-server/test/__snapshots__/apiSurface.snapshot.test.ts.snap
@@ -188,6 +188,10 @@ exports[`API surface snapshot > matches the documented v2 route table and meta e
       "GET",
       "/api/v1/sessions/{session_id}/goal",
     ],
+    [
+      "GET",
+      "/api/v1/sessions/{session_id}/media/{file_id}",
+    ],
     [
       "GET",
       "/api/v1/sessions/{session_id}/messages",
diff --git a/packages/kap-server/test/files.test.ts b/packages/kap-server/test/files.test.ts
index f83999a31cc..f682f417ccb 100644
--- a/packages/kap-server/test/files.test.ts
+++ b/packages/kap-server/test/files.test.ts
@@ -1,5 +1,5 @@
 /**
- * `/api/v1/files` end-to-end for the v2 server.
+ * `/api/v1/files` and session-canonical media downloads end-to-end for the v2 server.
  *
  * Mirrors the v1 server's files e2e (upload → download → delete → 404,
  * large uploads with no size cap, unknown ids, index persistence across
@@ -12,6 +12,12 @@ import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 
+import {
+  getLiveSessionById,
+  IFileService,
+  ISessionManager,
+  ISessionMediaStore,
+} from '@moonshot-ai/agent-core-v2';
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 
 import { type RunningServer, startServer } from '../src/start';
@@ -112,6 +118,64 @@ function buildMultipart(parts: {
   };
 }
 
+async function createSession(r: RunningServer): Promise<string> {
+  const res = await appOf(r).inject({
+    method: 'POST',
+    url: '/api/v1/sessions',
+    payload: { metadata: { cwd: home } },
+    headers: { 'content-type': 'application/json' },
+  });
+  const envelope = res.json() as Envelope<{ id: string }>;
+  if (envelope.code !== 0 || envelope.data === null) {
+    throw new Error(`failed to create session: ${res.body}`);
+  }
+  return envelope.data.id;
+}
+
+async function uploadFile(
+  r: RunningServer,
+  data: Buffer,
+  name: string,
+  mediaType: string,
+): Promise<{ id: string; name: string; media_type: string; size: number }> {
+  const multipart = buildMultipart({
+    file: { fieldName: 'file', filename: name, contentType: mediaType, data },
+  });
+  const res = await appOf(r).inject({
+    method: 'POST',
+    url: '/api/v1/files',
+    payload: multipart.body,
+    headers: { 'content-type': multipart.contentType },
+  });
+  const envelope = res.json() as Envelope<{
+    id: string;
+    name: string;
+    media_type: string;
+    size: number;
+  }>;
+  if (envelope.code !== 0 || envelope.data === null) {
+    throw new Error(`failed to upload file: ${res.body}`);
+  }
+  return envelope.data;
+}
+
+async function materializeUploadedFile(
+  r: RunningServer,
+  sessionId: string,
+  meta: { id: string; name: string; media_type: string; size: number },
+): Promise<void> {
+  const session = getLiveSessionById(r.core.accessor, sessionId);
+  if (session === undefined) throw new Error(`session ${sessionId} is not live`);
+  const uploaded = await r.core.accessor.get(IFileService).get(meta.id);
+  await session.accessor.get(ISessionMediaStore).materialize({
+    fileId: meta.id,
+    name: meta.name,
+    mimeType: meta.media_type,
+    size: meta.size,
+    stream: () => uploaded.stream(),
+  });
+}
+
 describe('POST /api/v1/files (server-v2)', () => {
   it('upload → GET stream → DELETE → re-GET 40407', async () => {
     const r = await boot();
@@ -333,3 +397,136 @@ describe('POST /api/v1/files (server-v2)', () => {
     expect((res.json() as Envelope).code).toBe(40001);
   });
 });
+
+describe('GET /api/v1/sessions/{session_id}/media/{file_id} (server-v2)', () => {
+  it('serves the session copy after the transient upload is deleted', async () => {
+    const r = await boot();
+    const data = Buffer.from('canonical image bytes');
+    const sessionId = await createSession(r);
+    const meta = await uploadFile(r, data, 'pasted image.png', 'image/png');
+    await materializeUploadedFile(r, sessionId, meta);
+
+    await appOf(r).inject({ method: 'DELETE', url: `/api/v1/files/${meta.id}` });
+    const res = await appOf(r).inject({
+      method: 'GET',
+      url: `/api/v1/sessions/${sessionId}/media/${meta.id}`,
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.headers['content-type']).toBe('image/png');
+    expect(res.headers['content-length']).toBe(String(data.length));
+    expect(String(res.headers['content-disposition'])).toMatch(
+      /inline; filename="pasted image\.png"/,
+    );
+    expect(res.rawPayload).toEqual(data);
+  });
+
+  it('serves the staged upload before intake materializes the session copy', async () => {
+    const r = await boot();
+    const data = Buffer.from('staged upload bytes');
+    const sessionId = await createSession(r);
+    const meta = await uploadFile(r, data, 'staged.png', 'image/png');
+
+    const res = await appOf(r).inject({
+      method: 'GET',
+      url: `/api/v1/sessions/${sessionId}/media/${meta.id}`,
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.headers['content-type']).toBe('image/png');
+    expect(res.headers['content-length']).toBe(String(data.length));
+    expect(res.rawPayload).toEqual(data);
+  });
+
+  it('returns file-not-found when neither the session store nor the staged upload holds it', async () => {
+    const r = await boot();
+    const sessionId = await createSession(r);
+
+    const res = await appOf(r).inject({
+      method: 'GET',
+      url: `/api/v1/sessions/${sessionId}/media/f_does_not_exist`,
+    });
+
+    expect(res.statusCode).toBe(404);
+    expect((res.json() as Envelope).code).toBe(40407);
+  });
+
+  it('serves a requested byte range from the session copy', async () => {
+    const r = await boot();
+    const data = Buffer.from('0123456789abcdefghijklmnopqrstuvwxyz');
+    const sessionId = await createSession(r);
+    const meta = await uploadFile(r, data, 'clip.mp4', 'video/mp4');
+    await materializeUploadedFile(r, sessionId, meta);
+
+    const res = await appOf(r).inject({
+      method: 'GET',
+      url: `/api/v1/sessions/${sessionId}/media/${meta.id}`,
+      headers: { range: 'bytes=4-9' },
+    });
+
+    expect(res.statusCode).toBe(206);
+    expect(res.headers['content-type']).toBe('video/mp4');
+    expect(res.headers['content-range']).toBe(`bytes 4-9/${data.length}`);
+    expect(res.headers['content-length']).toBe('6');
+    expect(res.rawPayload).toEqual(data.subarray(4, 10));
+  });
+
+  it('serves the session copy after a server restart', async () => {
+    let r = await boot();
+    const data = Buffer.from('restart-safe media');
+    const sessionId = await createSession(r);
+    const meta = await uploadFile(r, data, 'restart.png', 'image/png');
+    await materializeUploadedFile(r, sessionId, meta);
+    await appOf(r).inject({ method: 'DELETE', url: `/api/v1/files/${meta.id}` });
+
+    await r.close();
+    server = undefined;
+    r = await boot();
+    const res = await appOf(r).inject({
+      method: 'GET',
+      url: `/api/v1/sessions/${sessionId}/media/${meta.id}`,
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.headers['content-type']).toBe('image/png');
+    expect(res.rawPayload).toEqual(data);
+  });
+
+  it('serves the copied media from a forked session', async () => {
+    const r = await boot();
+    const data = Buffer.from('forked media');
+    const sessionId = await createSession(r);
+    const meta = await uploadFile(r, data, 'fork.png', 'image/png');
+    await materializeUploadedFile(r, sessionId, meta);
+    const fork = await r.core.accessor.get(ISessionManager).fork({
+      sourceSessionId: sessionId,
+    });
+
+    const res = await appOf(r).inject({
+      method: 'GET',
+      url: `/api/v1/sessions/${fork.id}/media/${meta.id}`,
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.headers['content-type']).toBe('image/png');
+    expect(String(res.headers['content-disposition'])).toMatch(/filename="fork\.png"/);
+    expect(res.rawPayload).toEqual(data);
+  });
+
+  it('returns session-not-found after the owning session is deleted', async () => {
+    const r = await boot();
+    const data = Buffer.from('delete-owned media');
+    const sessionId = await createSession(r);
+    const meta = await uploadFile(r, data, 'delete.png', 'image/png');
+    await materializeUploadedFile(r, sessionId, meta);
+    await r.core.accessor.get(ISessionManager).delete(sessionId);
+
+    const res = await appOf(r).inject({
+      method: 'GET',
+      url: `/api/v1/sessions/${sessionId}/media/${meta.id}`,
+    });
+
+    expect(res.statusCode).toBe(404);
+    expect((res.json() as Envelope).code).toBe(40401);
+  });
+});
diff --git a/packages/kap-server/test/mediaRefParity.test.ts b/packages/kap-server/test/mediaRefParity.test.ts
new file mode 100644
index 00000000000..54c6da32178
--- /dev/null
+++ b/packages/kap-server/test/mediaRefParity.test.ts
@@ -0,0 +1,100 @@
+/**
+ * Parity pin for the daemon-ref / media-tag grammar, which lives in TWO
+ * packages that may not import each other: the engine
+ * (`agent-core-v2/agent/media/mediaRef.ts`, drives the request-time
+ * resolver's drop/synthesize decisions) and the transcript read-model mirror
+ * (`transcript/contract/mediaRef.ts`, drives the cold-rebuild projection).
+ * The two header comments say "keep the two in sync" — this test is what
+ * actually enforces it: both implementations must answer identically for
+ * every fixture below, so a grammar change landed on only one side fails
+ * here instead of drifting the live projection apart from the cold rebuild.
+ *
+ * The shared surface is threefold: `kimi-file://` url parsing, the
+ * standalone `<media path>` tag matcher, and the single-part daemon-ref
+ * extraction (`daemonFileRefFromPart` vs `daemonFileRefFromPairingPart`).
+ */
+
+import { describe, expect, it } from 'vitest';
+
+import {
+  daemonFileRefFromPart as engineRefFromPart,
+  matchSingleMediaPathTag as engineMatchTag,
+  parseDaemonFileUrl as engineParse,
+} from '@moonshot-ai/agent-core-v2';
+import {
+  daemonFileRefFromPairingPart as mirrorRefFromPart,
+  matchMediaPathTagText as mirrorMatchTag,
+  parseDaemonFileRef as mirrorParse,
+  type MediaRefPart,
+} from '@moonshot-ai/transcript';
+import type { ContentPart } from '@moonshot-ai/agent-core-v2/kosong/contract/message';
+
+const URLS = [
+  'kimi-file://f_1?path=%2Fcache%2Fshot.png',
+  'kimi-file://f_1',
+  'kimi-file://f_1?path=',
+  'kimi-file://?path=%2Fcache%2Fshot.png',
+  // A legacy `?path=` query is stripped, however it was encoded.
+  'kimi-file://f_1?path=%2Fcache%2Fa%20%26%20%22b%22%20%3Cc%3E.png',
+  'kimi-file://f_1?path=%zz',
+  'kimi-file://',
+  'https://example.com/shot.png',
+  '',
+];
+
+describe('daemon file url parsing parity (engine vs transcript mirror)', () => {
+  for (const url of URLS) {
+    it(JSON.stringify(url), () => {
+      expect(mirrorParse(url)).toEqual(engineParse(url));
+    });
+  }
+});
+
+const TAG_TEXTS = [
+  '<image path="/cache/shot.png"></image>',
+  // A missing closing tag is tolerated.
+  '<image path="/cache/shot.png">',
+  // Extra attributes are tolerated.
+  '<image content_type="image/png" path="/cache/shot.png">',
+  // Surrounding whitespace is tolerated.
+  '  <image path="/cache/shot.png"></image>\n',
+  // Escaped path characters round-trip.
+  '<image path="/cache/a &amp; &quot;b&quot; &lt;c&gt;.png"></image>',
+  // A tag embedded in user text is never matched.
+  'open <image path="/cache/shot.png"></image> please',
+  // Two tags are not a standalone tag.
+  '<image path="/cache/shot.png"></image><image path="/cache/other.png"></image>',
+  'plain text',
+  '',
+];
+
+describe('standalone media path tag matching parity', () => {
+  for (const text of TAG_TEXTS) {
+    it(JSON.stringify(text), () => {
+      const engine = engineMatchTag(text);
+      const mirror = mirrorMatchTag(text);
+      expect(mirror === undefined ? undefined : { kind: mirror.kind, path: mirror.path }).toEqual(
+        engine === undefined ? undefined : { kind: engine.kind, path: engine.path },
+      );
+    });
+  }
+});
+
+const PARTS: ReadonlyArray<MediaRefPart> = [
+  { type: 'image_url', imageUrl: { url: 'kimi-file://f_1?path=%2Fcache%2Fshot.png' } },
+  { type: 'video_url', videoUrl: { url: 'kimi-file://f_3?path=%2Fcache%2Fclip.mp4' } },
+  { type: 'image_url', imageUrl: { url: 'kimi-file://f_1' } },
+  { type: 'image_url', imageUrl: { url: 'https://example.com/shot.png' } },
+  { type: 'text', text: '<image path="/cache/shot.png"></image>' },
+  { type: 'text', text: 'hello' },
+];
+
+describe('daemon ref extraction parity', () => {
+  for (const [index, part] of PARTS.entries()) {
+    it(`part ${index}: ${part.type}`, () => {
+      expect(mirrorRefFromPart(part)).toEqual(
+        engineRefFromPart(part as unknown as ContentPart),
+      );
+    });
+  }
+});
diff --git a/packages/kap-server/test/prompts.test.ts b/packages/kap-server/test/prompts.test.ts
index 10ceb752a39..060bcc7680b 100644
--- a/packages/kap-server/test/prompts.test.ts
+++ b/packages/kap-server/test/prompts.test.ts
@@ -1,4 +1,4 @@
-import { mkdir, mkdtemp, readFile, realpath, rm, writeFile } from 'node:fs/promises';
+import { chmod, mkdir, mkdtemp, readFile, realpath, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { deflateSync } from 'node:zlib';
@@ -9,10 +9,14 @@ import {
   IAgentLifecycleService,
   IAgentProfileService,
   IAgentToolPolicyService,
+  IBootstrapService,
+  IFileService,
+  ISessionContext,
+  ISessionMetadata,
   closeSessionById,
   getLiveSessionById,
 } from '@moonshot-ai/agent-core-v2';
-import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { type RunningServer, startServer } from '../src/start';
 import { TEST_HOST_IDENTITY } from './helpers/hostIdentity';
@@ -129,6 +133,31 @@ function pngDimensions(bytes: Buffer): { width: number; height: number } {
   };
 }
 
+async function readFileEventually(path: string): Promise<Buffer> {
+  return vi.waitFor(() => readFile(path));
+}
+
+/** The session's own media dir, where prompt media materializes now. */
+function sessionMediaDir(server: RunningServer, sessionId: string): string {
+  const session = getLiveSessionById(server.core.accessor, sessionId);
+  return join(session!.accessor.get(ISessionContext).sessionDir, 'media');
+}
+
+/**
+ * Asserts the session-media copy of an uploaded prompt file lands with the
+ * original bytes; returns its path for follow-up leak assertions.
+ */
+async function expectSessionMedia(
+  server: RunningServer,
+  sessionId: string,
+  name: string,
+  bytes: Buffer,
+): Promise<string> {
+  const path = join(sessionMediaDir(server, sessionId), name);
+  expect(await readFileEventually(path)).toEqual(bytes);
+  return path;
+}
+
 describe('server-v2 /api/v1 prompts', () => {
   let server: RunningServer | undefined;
   let home: string | undefined;
@@ -216,6 +245,50 @@ describe('server-v2 /api/v1 prompts', () => {
     expect(Array.isArray(list.body.data.queued)).toBe(true);
   });
 
+  it('honors a client-chosen prompt_id on submit', async () => {
+    const id = await createSession(home as string);
+    await createMainAgent(id);
+
+    const submitted = await call<PromptItemWire>('POST', `/api/v1/sessions/${id}/prompts`, {
+      content: [{ type: 'text', text: 'hello' }],
+      prompt_id: 'submission-1',
+    });
+    expect(submitted.body.code).toBe(0);
+    expect(submitted.body.data.prompt_id).toBe('submission-1');
+    expect(submitted.body.data.user_message_id).toBe('submission-1');
+  });
+
+  it('rejects a reused prompt_id live and after cold resume without changing metadata', async () => {
+    const id = await createSession(home as string);
+    await createMainAgent(id);
+
+    const first = await call<PromptItemWire>('POST', `/api/v1/sessions/${id}/prompts`, {
+      content: [{ type: 'text', text: 'first prompt' }],
+      prompt_id: 'submission-1',
+    });
+    expect(first.body.code).toBe(0);
+
+    const duplicate = await call<null>('POST', `/api/v1/sessions/${id}/prompts`, {
+      content: [{ type: 'text', text: 'must not become metadata' }],
+      prompt_id: 'submission-1',
+    });
+    expect(duplicate.body.code).toBe(40927);
+
+    const session = getLiveSessionById(server!.core.accessor, id);
+    expect((await session!.accessor.get(ISessionMetadata).read()).lastPrompt).toBe('first prompt');
+
+    await closeSessionById(server!.core.accessor, id);
+    expect(getLiveSessionById(server!.core.accessor, id)).toBeUndefined();
+
+    const afterResume = await call<null>('POST', `/api/v1/sessions/${id}/prompts`, {
+      content: [{ type: 'text', text: 'must not survive a cold resume' }],
+      prompt_id: 'submission-1',
+    });
+    expect(afterResume.body.code).toBe(40927);
+    const resumed = getLiveSessionById(server!.core.accessor, id);
+    expect((await resumed!.accessor.get(ISessionMetadata).read()).lastPrompt).toBe('first prompt');
+  });
+
   it('makes the first three REST prompts available to title generation', async () => {
     const id = await createSession(home as string);
     await createMainAgent(id);
@@ -303,47 +376,40 @@ describe('server-v2 /api/v1 prompts', () => {
     // The edge no longer uploads to the provider. The queued prompt reprojects
     // the video as the file reference it came from — a `{ kind: 'file' }` source
     // is only ever produced from an internal `kimi-file://` url, so this proves
-    // the enqueued message carries the reference (its materialization path is
-    // never leaked back to the client).
+    // the enqueued message carries the reference (the internal URL is never
+    // leaked back to the client).
     const content = submitted.body.data.content as Array<Record<string, unknown>>;
     expect(content).toHaveLength(2);
     expect(content[0]).toEqual({ type: 'text', text: 'what happens in this video?' });
     expect(content[1]).toEqual({
       type: 'video',
-      source: { kind: 'file', file_id: uploaded.data.id },
+      source: { kind: 'session_media', file_id: uploaded.data.id },
     });
 
-    // The `?path=` of that reference points at a materialized copy of the bytes
-    // (written during the submit), which the engine resolver falls back to when
-    // it cannot upload or inline the video.
-    const materialized = join(home as string, 'cache', `${uploaded.data.id}.mp4`);
-    expect(await readFile(materialized)).toEqual(videoBytes);
+    // Intake materializes a copy of the bytes in the session's own media dir,
+    // written asynchronously by the engine's prompt intake — the engine
+    // resolver falls back to it when it cannot upload or inline the video.
+    await expectSessionMedia(server!, id, `${uploaded.data.id}.mp4`, videoBytes);
   });
 
-  it('compresses uploaded image prompts into base64 image parts with a readback caption', async () => {
+  it('carries a compressed uploaded image into the prompt as an internal kimi-file reference', async () => {
     const id = await createSession(home as string);
     await createMainAgent(id);
     const bigPng = solidPng(3600, 1800);
-    const form = new FormData();
-    form.set('file', new Blob([bigPng], { type: 'image/png' }), 'big.png');
-    const uploadRes = await fetch(`${base}/api/v1/files`, {
-      method: 'POST',
-      headers: authHeaders(server as RunningServer),
-      body: form,
-    } as never);
-    const uploaded = (await uploadRes.json()) as Envelope<{ id: string; size: number }>;
-    expect(uploaded.code).toBe(0);
-    expect(uploaded.data.size).toBe(bigPng.length);
+    const uploaded = await uploadFile(bigPng, 'image/png', 'big.png');
+    expect(uploaded.size).toBe(bigPng.length);
 
     const submitted = await call<PromptItemWire>('POST', `/api/v1/sessions/${id}/prompts`, {
-      content: [{ type: 'image', source: { kind: 'file', file_id: uploaded.data.id } }],
+      content: [{ type: 'image', source: { kind: 'file', file_id: uploaded.id } }],
     });
     expect(submitted.body.code).toBe(0);
 
-    const content = submitted.body.data.content as PromptContentPart[];
+    // [compression caption, projected file reference]: the daemon ref
+    // projects to `session_media`, the internal URL never leaked.
+    const content = submitted.body.data.content as Array<Record<string, unknown>>;
     expect(content).toHaveLength(2);
-    const caption = content[0];
-    if (caption?.type !== 'text') throw new Error('expected compression caption');
+    const caption = content[0] as { type: string; text: string };
+    expect(caption.type).toBe('text');
     expect(caption.text).toContain('Image compressed');
     expect(caption.text).toContain('3600x1800');
     const pathMatch = /saved at "([^"]+)"/.exec(caption.text);
@@ -351,17 +417,210 @@ describe('server-v2 /api/v1 prompts', () => {
     expect(pathMatch![1]!).toContain('/media-originals/');
     expect(await readFile(pathMatch![1]!)).toEqual(bigPng);
 
-    const image = content[1];
-    if (image?.type !== 'image' || image.source.kind !== 'base64') {
-      throw new Error('expected resolved base64 image');
+    // Compression swapped the referenced upload: the reference addresses a NEW
+    // daemon upload holding the final bytes, so its id differs from the
+    // client's original upload id.
+    const image = content[1] as { type: string; source: { kind: string; file_id: string } };
+    expect(image.type).toBe('image');
+    expect(image.source.kind).toBe('session_media');
+    const finalFileId = image.source.file_id;
+    expect(finalFileId).not.toBe(uploaded.id);
+
+    // Intake materializes the session-media copy of the FINAL (compressed)
+    // bytes, named by the final upload id — the copy still lands on disk for
+    // the engine, but its path never reaches the wire.
+    const mediaPath = join(sessionMediaDir(server!, id), `${finalFileId}.png`);
+    expect(pngDimensions(await readFileEventually(mediaPath))).toEqual({ width: 2000, height: 1000 });
+    expect(JSON.stringify(content)).not.toContain(mediaPath);
+
+    // The original client upload stays untouched.
+    const original = await server!.core.accessor.get(IFileService).get(uploaded.id);
+    expect(original.meta.size).toBe(bigPng.length);
+
+    // The compressed re-save is only staging. Once prompt intake has created
+    // the Session-owned copy, the App upload is released; stored projections
+    // address the canonical copy through `session_media` instead.
+    const files = server!.core.accessor.get(IFileService);
+    await vi.waitFor(async () => {
+      const result = await files.get(finalFileId).catch((error: unknown) => error);
+      expect(result).toMatchObject({ code: 'file.not_found' });
+    });
+
+    // The internal reference never leaks to the wire.
+    expect(JSON.stringify(content)).not.toContain('kimi-file://');
+
+    // The prompt service extracts the compression caption into its own
+    // system-reminder message on enqueue.
+    const session = getLiveSessionById(server!.core.accessor, id);
+    const main = session!.accessor.get(IAgentLifecycleService).get('main')!;
+    const memory = main.accessor.get(IAgentContextMemoryService).get();
+    const reminder = memory.find((m) => m.origin?.kind === 'injection');
+    const reminderText = reminder?.content[0];
+    expect(reminderText?.type).toBe('text');
+    expect((reminderText as { type: 'text'; text: string }).text).toContain('<system-reminder>');
+    expect((reminderText as { type: 'text'; text: string }).text).toContain('Image compressed');
+  });
+
+  it('rolls back a compressed upload when a later prompt part fails to resolve', async () => {
+    const id = await createSession(home as string);
+    await createMainAgent(id);
+    const first = await uploadFile(solidPng(3600, 1800), 'image/png', 'big.png');
+    const second = await uploadFile(solidPng(10, 10), 'image/png', 'small.png');
+    const files = server!.core.accessor.get(IFileService);
+    const originalGet = files.get.bind(files);
+    const originalSave = files.save.bind(files);
+    let secondGets = 0;
+    let compressedFileId: string | undefined;
+    const getSpy = vi.spyOn(files, 'get').mockImplementation(async (fileId) => {
+      if (fileId === second.id && ++secondGets === 2) {
+        throw new Error('injected second-part failure');
+      }
+      return originalGet(fileId);
+    });
+    const saveSpy = vi.spyOn(files, 'save').mockImplementation(async (...args) => {
+      const saved = await originalSave(...args);
+      compressedFileId = saved.id;
+      return saved;
+    });
+
+    try {
+      const submitted = await call<PromptItemWire>('POST', `/api/v1/sessions/${id}/prompts`, {
+        content: [
+          { type: 'image', source: { kind: 'file', file_id: first.id } },
+          { type: 'image', source: { kind: 'file', file_id: second.id } },
+        ],
+      });
+
+      expect(submitted.body.code).not.toBe(0);
+      expect(compressedFileId).toBeDefined();
+      if (compressedFileId === undefined) throw new Error('expected a compressed upload');
+      await expect(originalGet(compressedFileId)).rejects.toMatchObject({
+        code: 'file.not_found',
+      });
+    } finally {
+      getSpy.mockRestore();
+      saveSpy.mockRestore();
     }
-    expect(image.source.media_type).toBe('image/png');
-    expect(pngDimensions(Buffer.from(image.source.data, 'base64'))).toEqual({
-      width: 2000,
-      height: 1000,
+  });
+
+  it('carries an uncompressed uploaded image into the prompt as an internal kimi-file reference', async () => {
+    const id = await createSession(home as string);
+    await createMainAgent(id);
+    const smallPng = solidPng(10, 10);
+    const uploaded = await uploadFile(smallPng, 'image/png', 'small.png');
+
+    const submitted = await call<PromptItemWire>('POST', `/api/v1/sessions/${id}/prompts`, {
+      content: [{ type: 'image', source: { kind: 'file', file_id: uploaded.id } }],
+    });
+    expect(submitted.body.code).toBe(0);
+
+    // No compression caption when the bytes pass through unchanged, and the
+    // reference addresses the client's original upload — no new upload. The
+    // daemon ref projects to `session_media`, so the media path never leaks
+    // to the client.
+    const content = submitted.body.data.content as Array<Record<string, unknown>>;
+    expect(content).toEqual([
+      { type: 'image', source: { kind: 'session_media', file_id: uploaded.id } },
+    ]);
+
+    // The session-media copy holds the original bytes, named by the original upload id.
+    const mediaPath = await expectSessionMedia(server!, id, `${uploaded.id}.png`, smallPng);
+    expect(JSON.stringify(content)).not.toContain(mediaPath);
+
+    // The internal reference never leaks to the wire.
+    expect(JSON.stringify(content)).not.toContain('kimi-file://');
+  });
+
+  it('accepts a stored session-media reference after the transient upload is deleted', async () => {
+    const id = await createSession(home as string);
+    await createMainAgent(id);
+    const smallPng = solidPng(10, 10);
+    const uploaded = await uploadFile(smallPng, 'image/png', 'small.png');
+
+    const first = await call<PromptItemWire>('POST', `/api/v1/sessions/${id}/prompts`, {
+      content: [{ type: 'image', source: { kind: 'file', file_id: uploaded.id } }],
+    });
+    expect(first.body.code).toBe(0);
+    await expectSessionMedia(server!, id, `${uploaded.id}.png`, smallPng);
+    await server!.core.accessor.get(IFileService).delete(uploaded.id);
+
+    const replayed = await call<PromptItemWire>('POST', `/api/v1/sessions/${id}/prompts`, {
+      content: [
+        { type: 'text', text: 'replay the stored image' },
+        { type: 'image', source: { kind: 'session_media', file_id: uploaded.id } },
+      ],
+    });
+
+    expect(replayed.body.code).toBe(0);
+    expect(replayed.body.data.content).toEqual([
+      { type: 'text', text: 'replay the stored image' },
+      { type: 'image', source: { kind: 'session_media', file_id: uploaded.id } },
+    ]);
+
+    const session = getLiveSessionById(server!.core.accessor, id);
+    const main = session!.accessor.get(IAgentLifecycleService).get('main')!;
+    await vi.waitFor(() => {
+      const replayedMessage = main.accessor
+        .get(IAgentContextMemoryService)
+        .get()
+        .find(
+          (message) =>
+            message.role === 'user' &&
+            message.content.some(
+              (part) => part.type === 'text' && part.text === 'replay the stored image',
+            ),
+        );
+      expect(replayedMessage).toBeDefined();
+      expect(replayedMessage!.content).toContainEqual({
+        type: 'image_url',
+        imageUrl: {
+          url: `kimi-file://${uploaded.id}`,
+        },
+      });
     });
   });
 
+  it('keeps the upload-backed reference when the session media dir is not writable', async () => {
+    // Root bypasses permission checks, so the read-only dir never triggers.
+    if (process.getuid?.() === 0) return;
+    const id = await createSession(home as string);
+    await createMainAgent(id);
+    const smallPng = solidPng(10, 10);
+    const uploaded = await uploadFile(smallPng, 'image/png', 'small.png');
+
+    // A read-only session media dir must not reject an otherwise-submittable
+    // prompt: the reference stays upload-backed, without a materialized copy.
+    const mediaDir = sessionMediaDir(server!, id);
+    await mkdir(mediaDir, { recursive: true });
+    await chmod(mediaDir, 0o555);
+    try {
+      const submitted = await call<PromptItemWire>('POST', `/api/v1/sessions/${id}/prompts`, {
+        content: [{ type: 'image', source: { kind: 'file', file_id: uploaded.id } }],
+      });
+      expect(submitted.body.code).toBe(0);
+
+      const session = getLiveSessionById(server!.core.accessor, id);
+      const main = session!.accessor.get(IAgentLifecycleService).get('main')!;
+      await vi.waitFor(() => {
+        const message = main.accessor
+          .get(IAgentContextMemoryService)
+          .get()
+          .find((m) => m.role === 'user' && m.content.some((part) => part.type === 'image_url'));
+        expect(message).toBeDefined();
+        expect(message!.content).toContainEqual({
+          type: 'image_url',
+          imageUrl: { url: `kimi-file://${uploaded.id}` },
+        });
+      });
+
+      // No fallback copy lands outside the session media dir.
+      const cacheDir = server!.core.accessor.get(IBootstrapService).cacheDir;
+      await expect(readFile(join(cacheDir, `${uploaded.id}.png`))).rejects.toThrow();
+    } finally {
+      await chmod(mediaDir, 0o755);
+    }
+  });
+
   it('compresses inline base64 image prompts into session media-originals', async () => {
     const id = await createSession(home as string);
     await createMainAgent(id);
diff --git a/packages/kap-server/test/rpc.test.ts b/packages/kap-server/test/rpc.test.ts
index 46a745dc542..8d8021078f6 100644
--- a/packages/kap-server/test/rpc.test.ts
+++ b/packages/kap-server/test/rpc.test.ts
@@ -12,6 +12,7 @@ import {
   IAgentShellCommandService,
   IAppendLogStore,
   IDebugEventsService,
+  IEventService,
   IInstantiationService,
   IPluginService,
   ISessionIndex,
@@ -193,6 +194,10 @@ describe('server-v2 /api/v1/debug RPC', () => {
     });
     // Framework plumbing stays out of the listing.
     expect(meta?.methods.map((m) => m.name)).not.toContain('dispose');
+
+    const prompts = byName.get('agentPromptService');
+    expect(prompts?.methods.map((m) => m.name)).toContain('enqueue');
+    expect(prompts?.methods.map((m) => m.name)).not.toContain('reserve');
   });
 
   it('reaches a runtime-contributed Service absent from /channels (decorator-name fallback)', async () => {
@@ -454,6 +459,116 @@ describe('server-v2 /api/v1/debug RPC', () => {
 
   // --- Agent scope ----------------------------------------------------------
 
+  it('submits a prompt and returns the turn id', async () => {
+    const id = await createSession(home as string);
+    await createMainAgent(id);
+
+    const { body } = await call<{ turn_id: number }>(
+      'POST',
+      rpc('agent', IAgentPromptService, 'submit', { sid: id, aid: 'main' }),
+      { input: [{ type: 'text', text: 'hello' }] },
+    );
+    expect(body.code).toBe(0);
+    expect(body.data.turn_id).toBe(0);
+  });
+
+  it('maps a duplicate promptId to 40927 before metadata changes', async () => {
+    const id = await createSession(home as string);
+    await createMainAgent(id);
+    const path = rpc('agent', IAgentPromptService, 'submit', { sid: id, aid: 'main' });
+
+    const first = await call<{ turn_id: number }>('POST', path, {
+      input: [{ type: 'text', text: 'first prompt' }],
+      promptId: 'submission-1',
+    });
+    expect(first.body.code).toBe(0);
+
+    const duplicate = await call<null>('POST', path, {
+      input: [{ type: 'text', text: 'must not become metadata' }],
+      promptId: 'submission-1',
+    });
+    expect(duplicate.body.code).toBe(40927);
+
+    const metadata = await call<SessionMetaWire>(
+      'POST',
+      rpc('session', ISessionMetadata, 'read', { sid: id }),
+    );
+    expect(metadata.body.data.lastPrompt).toBe('first prompt');
+  });
+
+  it('rejects disabledTools before bind without mutating prompt metadata', async () => {
+    const id = await createSession(home as string);
+    await createMainAgent(id);
+
+    const { body } = await call<null>(
+      'POST',
+      rpc('agent', IAgentPromptService, 'submit', { sid: id, aid: 'main' }),
+      {
+        input: [{ type: 'text', text: 'must not become metadata' }],
+        disabledTools: ['Bash'],
+      },
+    );
+    expect(body.code).toBe(40001);
+
+    const metadata = await call<SessionMetaWire>(
+      'POST',
+      rpc('session', ISessionMetadata, 'read', { sid: id }),
+    );
+    expect(metadata.body.data.title).toBeUndefined();
+    expect(metadata.body.data.lastPrompt).toBeUndefined();
+  });
+
+  it('derives the session title and lastPrompt from the first prompt', async () => {
+    const id = await createSession(home as string);
+    await createMainAgent(id);
+
+    const events: { type: string; payload: unknown }[] = [];
+    const sub = (server as RunningServer).core.accessor
+      .get(IEventService)
+      .subscribe((event) => events.push(event));
+
+    const { body } = await call<{ turn_id: number }>(
+      'POST',
+      rpc('agent', IAgentPromptService, 'submit', { sid: id, aid: 'main' }),
+      { input: [{ type: 'text', text: 'hello title' }] },
+    );
+    expect(body.code).toBe(0);
+    sub.dispose();
+
+    const meta = await call<SessionMetaWire>('POST', rpc('session', ISessionMetadata, 'read', { sid: id }));
+    expect(meta.body.code).toBe(0);
+    expect(meta.body.data.title).toBe('hello title');
+    expect(meta.body.data.lastPrompt).toBe('hello title');
+
+    const updated = events.find((e) => e.type === 'session.meta.updated');
+    expect(updated).toBeDefined();
+    const payload = updated?.payload as
+      | { title?: string; patch?: { lastPrompt?: string } }
+      | undefined;
+    expect(payload?.title).toBe('hello title');
+    expect(payload?.patch?.lastPrompt).toBe('hello title');
+  });
+
+  it('keeps a custom title and only refreshes lastPrompt on a later prompt', async () => {
+    const id = await createSession(home as string);
+    await createMainAgent(id);
+
+    const renamed = await call<null>('POST', rpc('session', ISessionMetadata, 'setTitle', { sid: id }), 'keep-me');
+    expect(renamed.body.code).toBe(0);
+
+    const { body } = await call<{ turn_id: number }>(
+      'POST',
+      rpc('agent', IAgentPromptService, 'submit', { sid: id, aid: 'main' }),
+      { input: [{ type: 'text', text: 'should not become the title' }] },
+    );
+    expect(body.code).toBe(0);
+
+    const meta = await call<SessionMetaWire>('POST', rpc('session', ISessionMetadata, 'read', { sid: id }));
+    expect(meta.body.code).toBe(0);
+    expect(meta.body.data.title).toBe('keep-me');
+    expect(meta.body.data.lastPrompt).toBe('should not become the title');
+  });
+
   it('runs a shell command through the shell command service', async () => {
     const id = await createSession(home as string);
     await createMainAgent(id);
diff --git a/packages/kap-server/test/search/wireExtract.test.ts b/packages/kap-server/test/search/wireExtract.test.ts
index 088dfff1d3e..07e3d9a24bd 100644
--- a/packages/kap-server/test/search/wireExtract.test.ts
+++ b/packages/kap-server/test/search/wireExtract.test.ts
@@ -92,6 +92,62 @@ describe('extractFromWireLine', () => {
     expect(out).toEqual([]);
   });
 
+  it('indexes only the real text of an upload-carrying user message', () => {
+    // An uploaded image persists as a self-contained `kimi-file://` image
+    // part — no text at all — so an upload-only message drops out of the
+    // index, and a real text beside the ref is indexed on its own.
+    const uploadRef = {
+      type: 'image_url',
+      imageUrl: { url: 'kimi-file://f_1?path=%2FUsers%2Falice%2Fmedia%2Ff_1.png' },
+    };
+    const record = (content: unknown[]): string =>
+      line({
+        type: 'context.append_message',
+        time: 1_700_000_000_000,
+        message: { role: 'user', content, origin: { kind: 'user' } },
+      });
+
+    // Upload-only: nothing indexable (the materialization path included).
+    expect(extractFromWireLine(record([uploadRef]))).toEqual([]);
+    // With a real text part alongside, exactly that text is indexed.
+    expect(
+      extractFromWireLine(record([{ type: 'text', text: 'what is this? ' }, uploadRef])),
+    ).toEqual([{ role: 'user', text: 'what is this?', time: 1_700_000_000_000 }]);
+  });
+
+  it('never indexes a standalone <media path> tag, paired or not', () => {
+    // A standalone tag is machine markup (the upload residue of legacy
+    // sessions, or the model-facing degrade form) and leaks the
+    // materialization path — it stays out of the index whether or not a
+    // daemon ref rides alongside. A tag embedded in real user text is
+    // indexed with that text.
+    const legacyPair = [
+      { type: 'text', text: '<image path="/Users/alice/media/f_1.png"></image>' },
+      {
+        type: 'image_url',
+        imageUrl: { url: 'kimi-file://f_1?path=%2FUsers%2Falice%2Fmedia%2Ff_1.png' },
+      },
+    ];
+    const record = (content: unknown[]): string =>
+      line({
+        type: 'context.append_message',
+        time: 1_700_000_000_000,
+        message: { role: 'user', content, origin: { kind: 'user' } },
+      });
+
+    expect(extractFromWireLine(record(legacyPair))).toEqual([]);
+    expect(
+      extractFromWireLine(userRecord('<image path="/tmp/shot.png">', 1_700_000_000_000, { kind: 'user' })),
+    ).toEqual([]);
+    expect(
+      extractFromWireLine(
+        userRecord('open <image path="/tmp/shot.png"> please', 1_700_000_000_000, { kind: 'user' }),
+      ),
+    ).toEqual([
+      { role: 'user', text: 'open <image path="/tmp/shot.png"> please', time: 1_700_000_000_000 },
+    ]);
+  });
+
   it('extracts assistant text content parts from loop events', () => {
     const out = extractFromWireLine(
       line({
diff --git a/packages/kap-server/test/services/messages/messageProjection.test.ts b/packages/kap-server/test/services/messages/messageProjection.test.ts
index 948f0b5b817..1045c1b271b 100644
--- a/packages/kap-server/test/services/messages/messageProjection.test.ts
+++ b/packages/kap-server/test/services/messages/messageProjection.test.ts
@@ -40,6 +40,75 @@ describe('toProtocolMessage', () => {
     ]);
   });
 
+  it('projects a daemon-ref image part to a session_media source', () => {
+    // The persisted upload shape is a single self-contained daemon-ref part:
+    // the reference projects to the Session-owned copy; a legacy `?path=`
+    // query is ignored, never leaked.
+    const msg: ContextMessage = {
+      role: 'user',
+      content: [
+        { type: 'text', text: 'what is this?' },
+        { type: 'image_url', imageUrl: { url: 'kimi-file://file_9?path=%2Fcache%2Fpic.png' } },
+      ],
+      toolCalls: [],
+    };
+
+    expect(toProtocolMessage(SESSION_ID, 0, msg, CREATED_AT).content).toEqual([
+      { type: 'text', text: 'what is this?' },
+      { type: 'image', source: { kind: 'session_media', file_id: 'file_9' } },
+    ]);
+  });
+
+  it('keeps a legacy tag+ref pair as text plus the ref projection', () => {
+    // Legacy sessions persist an upload as the pair `<image path>` tag text
+    // part + daemon-ref media part. Tolerated, not folded: the tag passes
+    // through as text and the self-contained ref projects on its own.
+    const msg: ContextMessage = {
+      role: 'user',
+      content: [
+        { type: 'text', text: '<image path="/cache/pic.png"></image>' },
+        { type: 'image_url', imageUrl: { url: 'kimi-file://file_9?path=%2Fcache%2Fpic.png' } },
+      ],
+      toolCalls: [],
+    };
+
+    expect(toProtocolMessage(SESSION_ID, 0, msg, CREATED_AT).content).toEqual([
+      { type: 'text', text: '<image path="/cache/pic.png"></image>' },
+      { type: 'image', source: { kind: 'session_media', file_id: 'file_9' } },
+    ]);
+  });
+
+  it('keeps a bare <media path> tag as text in user messages', () => {
+    // A standalone tag without a daemon ref is user-visible text (or the
+    // legacy degrade form): it passes through as a text part.
+    const msg: ContextMessage = {
+      role: 'user',
+      content: [
+        { type: 'text', text: '<video path="/cache/clip.mp4">' },
+        { type: 'text', text: 'watch this' },
+      ],
+      toolCalls: [],
+    };
+
+    expect(toProtocolMessage(SESSION_ID, 0, msg, CREATED_AT).content).toEqual([
+      { type: 'text', text: '<video path="/cache/clip.mp4">' },
+      { type: 'text', text: 'watch this' },
+    ]);
+  });
+
+  it('passes assistant tag-shaped text through verbatim', () => {
+    // The fold applies to user uploads only — model output is never eaten.
+    const msg: ContextMessage = {
+      role: 'assistant',
+      content: [{ type: 'text', text: '<image path="/cache/out.png"></image>' }],
+      toolCalls: [],
+    };
+
+    expect(toProtocolMessage(SESSION_ID, 0, msg, CREATED_AT).content).toEqual([
+      { type: 'text', text: '<image path="/cache/out.png"></image>' },
+    ]);
+  });
+
   it('projects a kimi-file video reference to a structured file source without leaking the path', () => {
     const msg: ContextMessage = {
       role: 'user',
@@ -50,7 +119,7 @@ describe('toProtocolMessage', () => {
     };
 
     expect(toProtocolMessage(SESSION_ID, 0, msg, CREATED_AT).content).toEqual([
-      { type: 'video', source: { kind: 'file', file_id: 'file_9' } },
+      { type: 'video', source: { kind: 'session_media', file_id: 'file_9' } },
     ]);
   });
 
diff --git a/packages/kap-server/test/services/transcript.test.ts b/packages/kap-server/test/services/transcript.test.ts
index b0d08e22279..a9b775fe198 100644
--- a/packages/kap-server/test/services/transcript.test.ts
+++ b/packages/kap-server/test/services/transcript.test.ts
@@ -147,6 +147,50 @@ describe('AgentTranscriptProjector', () => {
     expect(turn.state).toBe('completed');
   });
 
+  it('projects turn.started promptAttachments into attachment entities and turn.attachmentIds', () => {
+    const projector = new AgentTranscriptProjector('main');
+    const tx = new AgentTranscript('main');
+    const ops: TranscriptOperation[] = [];
+    const feed = (event: DomainEvent): void => {
+      const mapped = projector.map(event);
+      ops.push(...mapped);
+      tx.apply(mapped);
+    };
+
+    feed(
+      ev({
+        type: 'turn.started',
+        turnId: 0,
+        origin: { kind: 'user' },
+        prompt: 'what is this?',
+        promptAttachments: [{ kind: 'image', fileId: 'file_1' }],
+      }),
+    );
+    feed(ev({ type: 'turn.ended', turnId: 0, reason: 'completed' }));
+
+    // Op-level: one attachment entity per referenced upload.
+    expect(ops.filter((op) => op.op === 'attachment.upsert')).toEqual([
+      {
+        op: 'attachment.upsert',
+        attachment: {
+          attachmentId: 't0.att1',
+          mediaType: 'image/*',
+          source: { kind: 'session_media', fileId: 'file_1' },
+        },
+      },
+    ]);
+
+    // Converged store: the id list survives the turn.ended header rebuild.
+    const turn = turnOps('t0', tx.getItems());
+    expect(turn.prompt).toBe('what is this?');
+    expect(turn.attachmentIds).toEqual(['t0.att1']);
+    expect(tx.getAttachment('t0.att1')).toEqual({
+      attachmentId: 't0.att1',
+      mediaType: 'image/*',
+      source: { kind: 'session_media', fileId: 'file_1' },
+    });
+  });
+
   it('places late-attach deltas into the engine-reported active step', () => {
     const tx = new AgentTranscript('main');
     // The projector missed turn.started AND turn.step.started for step 2 —
@@ -396,6 +440,46 @@ describe('AgentTranscriptProjector', () => {
     ).toEqual(['t0', 'm1', 't1', 'r1', 't2']);
   });
 
+  it('snapshotToOps flattens attachment entities so backfilled attachmentIds never dangle', () => {
+    const snapshot: AgentTranscriptSnapshot = {
+      interactions: [],
+      attachments: [
+        {
+          attachmentId: 'att_1',
+          mediaType: 'image/*',
+          name: 'shot.png',
+          source: { kind: 'file', fileId: 'file_1' },
+        },
+      ],
+      todos: [],
+      prompts: [],
+      items: [
+        {
+          kind: 'turn',
+          turnId: 't0',
+          ordinal: 0,
+          state: 'completed',
+          origin: { kind: 'user' },
+          prompt: 'what is this?',
+          attachmentIds: ['att_1'],
+          steps: [],
+        },
+      ],
+      tasks: [],
+      meta: {},
+    };
+
+    const ops = snapshotToOps(snapshot);
+    expect(ops.filter((op) => op.op === 'attachment.upsert')).toEqual([
+      { op: 'attachment.upsert', attachment: snapshot.attachments[0] },
+    ]);
+
+    const tx = new AgentTranscript('main');
+    tx.apply(ops);
+    expect(tx.getAttachment('att_1')).toEqual(snapshot.attachments[0]);
+    expect(turnOps('t0', tx.getItems()).attachmentIds).toEqual(['att_1']);
+  });
+
   it('flushes open frames on turn.ended even without step completion', () => {
     const projector = new AgentTranscriptProjector('main');
     const tx = new AgentTranscript('main');
@@ -1492,6 +1576,34 @@ describe('AgentTranscriptProjector', () => {
     });
   });
 
+  it('projects prompt.steered media content to the wire shape (no daemon ref or path leak)', () => {
+    const projector = new AgentTranscriptProjector('main');
+    const tx = new AgentTranscript('main');
+    const feed = (event: DomainEvent): void => void tx.apply(projector.map(event));
+
+    feed(
+      ev({
+        type: 'prompt.steered',
+        activePromptId: 'p1',
+        promptIds: ['p2'],
+        content: [
+          { type: 'text', text: 'look at this' },
+          {
+            type: 'image_url',
+            imageUrl: { url: 'kimi-file://f_img1?path=%2Fabs%2Fsession%2Fmedia%2Ff_img1.png' },
+          },
+        ],
+        steeredAt: '2026-01-01T00:00:02.000Z',
+      }),
+    );
+
+    const prompt = tx.getPrompt('p1');
+    expect(prompt?.content).toEqual([
+      { type: 'text', text: 'look at this' },
+      { type: 'image', source: { kind: 'session_media', file_id: 'f_img1' } },
+    ]);
+  });
+
   it('readColdSnapshot answers empty for path-hostile agent ids without touching disk', async () => {
     const service = new TranscriptService({
       homeDir: '/nonexistent-home',
@@ -1885,23 +1997,50 @@ describe('bindSessionTranscript', () => {
     binding.dispose();
   });
 
-  async function seedWireHome(): Promise<string> {
+  /** The upload carried by an attachment seed: its cold fold yields the `att_1` entity. */
+  const SHOT_PNG_UPLOAD = {
+    type: 'file',
+    file_id: 'file_1',
+    media_type: 'image/png',
+    name: 'shot.png',
+  };
+
+  /**
+   * Wire seed: a lone `hi` user message — or, with `attachment`, an
+   * upload-carrying user message (its cold fold yields the `att_1` entity)
+   * trailed by an assistant reply.
+   */
+  async function seedWireHome(attachment?: Record<string, unknown>): Promise<string> {
     const home = await mkdtemp(join(tmpdir(), 'transcript-overlay-'));
     const wireDir = join(home, 'sessions', 'ws', 's1', 'agents', 'main');
     await mkdir(wireDir, { recursive: true });
-    await writeFile(
-      join(wireDir, 'wire.jsonl'),
-      `${JSON.stringify({
+    const records: Record<string, unknown>[] = [
+      {
         type: 'context.append_message',
         message: {
           role: 'user',
-          content: [{ type: 'text', text: 'hi' }],
+          content:
+            attachment === undefined
+              ? [{ type: 'text', text: 'hi' }]
+              : [{ type: 'text', text: 'what is this?' }, attachment],
           toolCalls: [],
           origin: { kind: 'user' },
         },
         time: new Date().toISOString(),
-      })}\n`,
-    );
+      },
+    ];
+    if (attachment !== undefined) {
+      records.push({
+        type: 'context.append_message',
+        message: {
+          role: 'assistant',
+          content: [{ type: 'text', text: 'a screenshot' }],
+          toolCalls: [],
+        },
+        time: new Date().toISOString(),
+      });
+    }
+    await writeFile(join(wireDir, 'wire.jsonl'), `${records.map((r) => JSON.stringify(r)).join('\n')}\n`);
     return home;
   }
 
@@ -2046,6 +2185,96 @@ describe('bindSessionTranscript', () => {
     expect(frames).toContainEqual(expect.objectContaining({ frameId: 't0.1.call_3', output: 'y' }));
   });
 
+  it('heal keeps the live attachment ids over the snapshot cold ids', () => {
+    const makeTurn = (attachmentIds: string[] | undefined): TranscriptTurn => ({
+      kind: 'turn',
+      turnId: 't0',
+      ordinal: 0,
+      state: 'completed',
+      origin: { kind: 'user' },
+      attachmentIds,
+      steps: [],
+    });
+    // Live turn opened by the projector with its own `{turnId}.att<N>` ids:
+    // the merged header must keep them, not churn to the cold `att_<n>` form.
+    const header = healTurnOps(makeTurn(['att_1']), makeTurn(['t0.att1'])).find(
+      (op) => op.op === 'turn.upsert',
+    );
+    expect(header).toMatchObject({ turn: { attachmentIds: ['t0.att1'] } });
+    // A mid-turn-attached projector never saw turn.started: the live header
+    // has no ids and the heal falls back to the persisted cold ones.
+    const fallback = healTurnOps(makeTurn(['att_1']), makeTurn(undefined)).find(
+      (op) => op.op === 'turn.upsert',
+    );
+    expect(fallback).toMatchObject({ turn: { attachmentIds: ['att_1'] } });
+  });
+
+  it('terminal turn.upsert inherits the backfilled header when the projector missed turn.started', () => {
+    const agents = new FakeAgents();
+    const store = new TranscriptStore('s1');
+    const ops: TranscriptOperation[] = [];
+    const binding = bindSessionTranscript(
+      store,
+      fakeSession(new SessionInteractionService(new TestSessionStateService()), agents),
+      undefined,
+      (event) => ops.push(...event.ops),
+    );
+    const main = agents.add('main');
+
+    // The history backfill landed first: the store already holds the running
+    // turn with its cold attachment ids…
+    store.ensureAgent('main').apply([
+      {
+        op: 'attachment.upsert',
+        attachment: {
+          attachmentId: 'att_1',
+          mediaType: 'image/*',
+          name: 'shot.png',
+          source: { kind: 'file', fileId: 'f_1' },
+        },
+      },
+      {
+        op: 'turn.upsert',
+        turn: {
+          kind: 'turn',
+          turnId: 't0',
+          ordinal: 0,
+          state: 'running',
+          origin: { kind: 'user' },
+          prompt: 'hi',
+          attachmentIds: ['att_1'],
+          startedAt: '2026-08-04T00:00:00.000Z',
+        },
+      },
+    ]);
+
+    // …but the projector attached mid-turn: the only live event it ever sees
+    // for this turn is the terminal one. The terminal batch itself must carry
+    // the inherited header — waiting for the debounced heal is too late (the
+    // whole-header replace has already wiped the ids, and the session may
+    // close before the heal runs).
+    main.bus.emit(ev({ type: 'turn.ended', turnId: 0, reason: 'completed' }));
+
+    const terminal = ops.filter((op) => op.op === 'turn.upsert');
+    expect(terminal).toHaveLength(1);
+    expect(terminal[0]).toMatchObject({
+      turn: {
+        turnId: 't0',
+        state: 'completed',
+        origin: { kind: 'user' },
+        prompt: 'hi',
+        attachmentIds: ['att_1'],
+        startedAt: '2026-08-04T00:00:00.000Z',
+      },
+    });
+    expect(store.getAgent('main')?.getTurn('t0')).toMatchObject({
+      state: 'completed',
+      prompt: 'hi',
+      attachmentIds: ['att_1'],
+    });
+    binding.dispose();
+  });
+
   it('seeds pending interactions per agent, not before that agent is backfilled', () => {
     const interactions = new SessionInteractionService(new TestSessionStateService());
     interactions.enqueue({ id: 'q-main', kind: 'question', payload: { toolCallId: 'call_main' }, origin: { agentId: 'main', turnId: 0 } });
@@ -2144,6 +2373,14 @@ describe('bindSessionTranscript', () => {
     return home;
   }
 
+  async function waitFor(condition: () => boolean, timeoutMs = 2000): Promise<void> {
+    const deadline = Date.now() + timeoutMs;
+    while (!condition()) {
+      if (Date.now() > deadline) throw new Error('waitFor timed out');
+      await new Promise((resolve) => setTimeout(resolve, 20));
+    }
+  }
+
   it('subscribes the bus for an agent whose projector was seeded before its handle existed', () => {
     const agents = new FakeAgents();
     const interactions = new SessionInteractionService(new TestSessionStateService());
@@ -2261,6 +2498,106 @@ describe('bindSessionTranscript', () => {
     }
   });
 
+  it('backfill + overlay keep the live attachment ids and drop the cold counterpart entity', async () => {
+    const home = await seedWireHome(SHOT_PNG_UPLOAD);
+    try {
+      const agents = new FakeAgents();
+      agents.add('main', { loopStatus: { state: 'running', activeTurnId: 0 } });
+      const service = new TranscriptService({
+        homeDir: home,
+        core: fakeCoreWithAgents(new SessionInteractionService(new TestSessionStateService()), agents),
+      });
+      const store = service.forSessionLive('s1');
+      // The live turn.started (with its own `t0.att1` attachment) lands while
+      // the backfill is still reading the persisted `att_1` form from disk.
+      agents.get('main')!.bus.emit(
+        ev({
+          type: 'turn.started',
+          turnId: 0,
+          origin: { kind: 'user' },
+          prompt: 'live prompt',
+          promptAttachments: [{ kind: 'image', fileId: 'file_1' }],
+        }),
+      );
+      await service.whenReady('s1');
+
+      const agent = store?.getAgent('main');
+      // Neither the live-first merge nor the running-overlay may churn or
+      // clear the live ids.
+      expect(agent?.getTurn('t0')).toMatchObject({
+        state: 'running',
+        prompt: 'live prompt',
+        attachmentIds: ['t0.att1'],
+      });
+      // The snapshot's cold counterpart must not land as an orphan entity.
+      expect(agent?.getAttachment('t0.att1')).toBeDefined();
+      expect(agent?.getAttachment('att_1')).toBeUndefined();
+      service.dropSession('s1');
+    } finally {
+      await rm(home, { recursive: true, force: true });
+    }
+  });
+
+  it('post-turn heal keeps the live attachment ids and never upserts the cold counterparts', async () => {
+    const home = await seedWireHome(SHOT_PNG_UPLOAD);
+    try {
+      const agents = new FakeAgents();
+      agents.add('main', { loopStatus: { state: 'idle' } });
+      const service = new TranscriptService({
+        homeDir: home,
+        core: fakeCoreWithAgents(new SessionInteractionService(new TestSessionStateService()), agents),
+      });
+      const store = service.forSessionLive('s1');
+      const batches: TranscriptOperation[][] = [];
+      service.onSessionOps('s1', (event) => {
+        if (event.agentId === 'main') batches.push([...event.ops]);
+      });
+      const bus = agents.get('main')!.bus;
+      bus.emit(
+        ev({
+          type: 'turn.started',
+          turnId: 0,
+          origin: { kind: 'user' },
+          prompt: 'live prompt',
+          promptAttachments: [{ kind: 'image', fileId: 'file_1' }],
+        }),
+      );
+      await service.whenReady('s1');
+
+      bus.emit(ev({ type: 'turn.ended', turnId: 0, reason: 'completed' }));
+      // The debounced heal re-reads the persisted snapshot and merges it back;
+      // its batch is the one carrying the (live-missed) wholesale step.
+      await waitFor(() =>
+        batches.some((batch) => batch.some((op) => op.op === 'step.upsert' && op.turnId === 't0')),
+      );
+      const healBatch = batches.find((batch) =>
+        batch.some((op) => op.op === 'step.upsert' && op.turnId === 't0'),
+      )!;
+      // No id churn on the wire: the healed header keeps the live ids, and no
+      // batch ever upserts the cold `att_1` entity.
+      expect(healBatch.find((op) => op.op === 'turn.upsert')).toMatchObject({
+        turn: { attachmentIds: ['t0.att1'] },
+      });
+      const attachmentUpserts = batches.flatMap((batch) =>
+        batch.filter((op) => op.op === 'attachment.upsert'),
+      );
+      expect(attachmentUpserts).toEqual([
+        { op: 'attachment.upsert', attachment: expect.objectContaining({ attachmentId: 't0.att1' }) },
+      ]);
+
+      const agent = store?.getAgent('main');
+      expect(agent?.getTurn('t0')).toMatchObject({
+        state: 'completed',
+        attachmentIds: ['t0.att1'],
+      });
+      expect(agent?.getAttachment('t0.att1')).toBeDefined();
+      expect(agent?.getAttachment('att_1')).toBeUndefined();
+      service.dropSession('s1');
+    } finally {
+      await rm(home, { recursive: true, force: true });
+    }
+  });
+
   describe('op journal', () => {
     it('assigns consecutive per-agent seqs and serves catch-up from the journal', async () => {
       const agents = new FakeAgents();
diff --git a/packages/kap-server/test/sessionEventBroadcaster.test.ts b/packages/kap-server/test/sessionEventBroadcaster.test.ts
index 84f86df16a2..fc7b6bbb1c1 100644
--- a/packages/kap-server/test/sessionEventBroadcaster.test.ts
+++ b/packages/kap-server/test/sessionEventBroadcaster.test.ts
@@ -786,6 +786,133 @@ describe('SessionEventBroadcaster', () => {
     expect(result.currentSeq).toBe(6);
   });
 
+  // The v1 wire contract for `turn.started` is exactly
+  // {type, turnId, origin, prompt?, promptId?, agentId, sessionId} — the
+  // engine-internal `promptAttachments` projection input must never reach the
+  // payload, and a video prompt's frame stays field-identical to the
+  // pre-attachment shape. Events without a `promptId` keep the six-key set.
+  const TURN_STARTED_WIRE_KEYS = ['agentId', 'origin', 'prompt', 'sessionId', 'turnId', 'type'];
+
+  it('forwards the promptId echo on a prompt-opened turn.started (live)', async () => {
+    const lc = new FakeLifecycle();
+    const main = lc.addAgent('main');
+    sessions.set('s1', lc);
+    const { target, envelopes } = collectingTarget();
+    await bc.subscribe('s1', target);
+
+    main.bus.emit(
+      agentEvent('turn.started', {
+        turnId: 1,
+        origin: { kind: 'user' },
+        prompt: 'with an exact id',
+        promptId: 'submission-1',
+      }),
+    );
+    await bc.getCursor('s1'); // drain
+
+    const live = envelopes.find((e) => e.type === 'turn.started');
+    expect(live).toBeDefined();
+    expect(live!.payload).toHaveProperty('promptId', 'submission-1');
+    expect(Object.keys(live!.payload as Record<string, unknown>).toSorted()).toEqual(
+      [...TURN_STARTED_WIRE_KEYS, 'promptId'].toSorted(),
+    );
+  });
+
+  it('keeps a video-prompt turn.started wire payload at the pre-attachment field set (live + disk-journal replay)', async () => {
+    const lc = new FakeLifecycle();
+    const main = lc.addAgent('main');
+    sessions.set('s1', lc);
+    const { target, envelopes } = collectingTarget();
+    await bc.subscribe('s1', target);
+
+    main.bus.emit(
+      agentEvent('turn.started', {
+        turnId: 1,
+        origin: { kind: 'user' },
+        prompt: 'summarize this clip',
+        promptAttachments: [{ kind: 'video', fileId: 'file_vid_1' }],
+      }),
+    );
+    await bc.getCursor('s1'); // drain between the turn boundaries (see note above)
+
+    const live = envelopes.find(
+      (e) => e.type === 'turn.started' && (e.payload as { turnId?: number }).turnId === 1,
+    );
+    expect(live).toBeDefined();
+    expect(live!.payload).not.toHaveProperty('promptAttachments');
+    expect(Object.keys(live!.payload as Record<string, unknown>).toSorted()).toEqual(
+      TURN_STARTED_WIRE_KEYS,
+    );
+
+    // The journal persists the same stripped envelope: reopen the session
+    // against the same eventsDir (a fresh instance has an empty in-memory
+    // tail, so the cursor replay is served by the on-disk journal) and the
+    // video turn.started still carries exactly the pre-attachment field set.
+    await bc.close(); // flushes the journal write-behind buffer
+    bc = new SessionEventBroadcaster({
+      eventsDir: dir,
+      core: makeCore(sessions, eventBus),
+      maxBufferSize: 20,
+    });
+    const replay = await bc.getBufferedSince('s1', { seq: 0 });
+    expect(replay.resyncRequired).toBe(false);
+    const replayed = replay.events.find(
+      (e) =>
+        e.envelope.type === 'turn.started' &&
+        (e.envelope.payload as { turnId?: number }).turnId === 1,
+    );
+    expect(replayed).toBeDefined();
+    expect(replayed!.envelope.payload).not.toHaveProperty('promptAttachments');
+    expect(Object.keys(replayed!.envelope.payload as Record<string, unknown>).toSorted()).toEqual(
+      TURN_STARTED_WIRE_KEYS,
+    );
+  });
+
+  it.each(['prompt.steered', 'prompt.queued'])(
+    'projects %s content without leaking daemon refs (live + tail replay)',
+    async (type) => {
+      const lc = new FakeLifecycle();
+      const main = lc.addAgent('main');
+      sessions.set('s1', lc);
+      const { target, envelopes } = collectingTarget();
+      await bc.subscribe('s1', target);
+
+      const ids =
+        type === 'prompt.steered'
+          ? { activePromptId: 'p1', promptIds: ['p2'], steeredAt: '2026-01-01T00:00:02.000Z' }
+          : { promptId: 'p2', queueLength: 1 };
+      main.bus.emit(
+        agentEvent(type, {
+          ...ids,
+          content: [
+            { type: 'text', text: 'look at this' },
+            {
+              type: 'image_url',
+              imageUrl: { url: 'kimi-file://f_img1?path=%2Fabs%2Fsession%2Fmedia%2Ff_img1.png' },
+            },
+          ],
+        }),
+      );
+      await bc.getCursor('s1'); // drain
+
+      const expected = [
+        { type: 'text', text: 'look at this' },
+        { type: 'image', source: { kind: 'session_media', file_id: 'f_img1' } },
+      ];
+      const live = envelopes.find((e) => e.type === type);
+      expect(live).toBeDefined();
+      expect((live!.payload as { content: unknown }).content).toEqual(expected);
+      expect(JSON.stringify(live!.payload)).not.toContain('kimi-file://');
+      expect(JSON.stringify(live!.payload)).not.toContain('/abs/session');
+
+      // Cursor replay within the in-memory tail serves the same projected envelope.
+      const replay = await bc.getBufferedSince('s1', { seq: 0 });
+      const replayed = replay.events.find((e) => e.envelope.type === type);
+      expect(replayed).toBeDefined();
+      expect((replayed!.envelope.payload as { content: unknown }).content).toEqual(expected);
+    },
+  );
+
   it('returns epoch_changed for a mismatched epoch', async () => {
     const lc = new FakeLifecycle();
     lc.addAgent('main');
diff --git a/packages/kap-server/test/transcript.test.ts b/packages/kap-server/test/transcript.test.ts
index 5f49b162156..37efd93e55e 100644
--- a/packages/kap-server/test/transcript.test.ts
+++ b/packages/kap-server/test/transcript.test.ts
@@ -1088,6 +1088,80 @@ describe('server-v2 /api/v1/sessions/{sid}/transcript', () => {
     expect(single.body.data.agents.map((a) => a.agent_id)).toEqual(['main']);
   });
 
+  it('lists an attachment-only prompt as an empty-string user message (live)', async () => {
+    const id = await createSession();
+    await ensureMainAgent(id);
+    // Bind the transcript before publishing live turns.
+    await getJson<TranscriptContract>(`/api/v1/sessions/${id}/transcript?agent_id=main`);
+
+    // An upload-only prompt folds to no text: the live turn carries no
+    // `prompt`, only its attachments. The route normalizes the prompt to ""
+    // (the cold rebuild's shape) instead of dropping the message.
+    const bus = mainAgentBus(id);
+    bus.publish(
+      serverEvent({
+        type: 'turn.started',
+        turnId: 1,
+        origin: { kind: 'user' },
+        promptAttachments: [{ kind: 'image', fileId: 'f_upload' }],
+      }),
+    );
+    bus.publish(serverEvent({ type: 'turn.ended', turnId: 1, reason: 'completed' }));
+
+    const { body } = await getJson<UserMessagesContract>(
+      `/api/v1/sessions/${id}/transcript/user-messages?agent_id=main`,
+    );
+    expect(body.code).toBe(0);
+    const main = body.data.agents[0]!;
+    expect(main.messages.map((m) => [m.turn_id, m.prompt])).toEqual([['t1', '']]);
+    expect(main.messages[0]!.attachment_ids).toEqual(['t1.att1']);
+    expect(main.attachments).toEqual([
+      expect.objectContaining({
+        attachmentId: 't1.att1',
+        mediaType: 'image/*',
+        source: { kind: 'session_media', fileId: 'f_upload' },
+      }),
+    ]);
+  });
+
+  it('lists an attachment-only prompt as an empty-string user message (cold)', async () => {
+    const id = await createSession();
+    await ensureMainAgent(id);
+    // The persisted shape of an upload-only prompt: a single self-contained
+    // daemon-ref media part. The cold projection maps it to one attachment
+    // and an empty prompt text.
+    await seedMainAgentMessages(id, [
+      {
+        role: 'user',
+        content: [
+          { type: 'image_url', imageUrl: { url: 'kimi-file://f_upload?path=%2Ftmp%2Fcache%2Ff_upload.png' } },
+        ],
+        toolCalls: [],
+      } as ContextMessage,
+      { role: 'assistant', content: [{ type: 'text', text: 'done' }], toolCalls: [] },
+    ]);
+
+    // Reboot on the same home — the session drops out of memory (cold path).
+    await server!.close();
+    server = undefined;
+    await boot();
+
+    const { body } = await getJson<UserMessagesContract>(
+      `/api/v1/sessions/${id}/transcript/user-messages?agent_id=main`,
+    );
+    expect(body.code).toBe(0);
+    const main = body.data.agents[0]!;
+    expect(main.messages.map((m) => [m.turn_id, m.prompt])).toEqual([['t0', '']]);
+    expect(main.messages[0]!.attachment_ids).toEqual(['att_1']);
+    expect(main.attachments).toEqual([
+      expect.objectContaining({
+        attachmentId: 'att_1',
+        mediaType: 'image/*',
+        source: { kind: 'session_media', fileId: 'f_upload' },
+      }),
+    ]);
+  });
+
   it('answers 40401 for an unknown session and 40001 for a hostile agent id on the user-messages route', async () => {
     const missing = await getJson<null>('/api/v1/sessions/nope/transcript/user-messages');
     expect(missing.body.code).toBe(40401);
diff --git a/packages/kap-server/test/transport-errors.test.ts b/packages/kap-server/test/transport-errors.test.ts
index 9eb6747c203..8e592e254d4 100644
--- a/packages/kap-server/test/transport-errors.test.ts
+++ b/packages/kap-server/test/transport-errors.test.ts
@@ -22,6 +22,7 @@ describe('/api/v1/debug transport mapError', () => {
     [ErrorCodes.STORAGE_LOCKED, ErrorCode.PERSISTENCE_FAILURE],
     [ErrorCodes.CONFIG_INVALID, ErrorCode.VALIDATION_FAILED],
     [ErrorCodes.GOAL_UNSUPPORTED_AGENT, ErrorCode.GOAL_UNSUPPORTED_AGENT],
+    [ErrorCodes.PROMPT_ID_CONFLICT, ErrorCode.PROMPT_ID_CONFLICT],
   ])('maps domain code %s to its wire equivalent', (code, wire) => {
     const env = mapError(new Error2(code, 'boom'), 'req-1');
     expect(env.code).toBe(wire);
diff --git a/packages/klient/AGENTS.md b/packages/klient/AGENTS.md
index d4724f483bb..127bd662e87 100644
--- a/packages/klient/AGENTS.md
+++ b/packages/klient/AGENTS.md
@@ -28,8 +28,10 @@ The facade only covers services that behave identically on both transports
 (the in-process dispatcher mirrors the server's scope resolution, including
 `main`-agent materialization via `ensureMainAgent`). onWill/hook-style
 interception is not wire-exposable
-(engine hooks are in-process `OrderedHookSlot`s); file upload and the
-terminal surface are v1-only and live in the legacy suites.
+(engine hooks are in-process `OrderedHookSlot`s); the terminal surface is
+v1-only and lives in the legacy suites. File upload IS on the facade
+(`global.files`): bytes cross the wire base64-encoded and the dispatcher
+adapts the engine's `IFileService` streams in both directions.
 
 ## Testing
 
diff --git a/packages/klient/src/contract/agent/events.ts b/packages/klient/src/contract/agent/events.ts
index 53e650c9377..bbf95bc1ac6 100644
--- a/packages/klient/src/contract/agent/events.ts
+++ b/packages/klient/src/contract/agent/events.ts
@@ -34,6 +34,8 @@ export const turnStartedEventSchema = z.object({
   origin: z.unknown(),
   /** The turn's extracted prompt text (present when the turn opened with a text part). */
   prompt: z.string().optional(),
+  /** The prompt record id when the turn was opened by a prompt submission. */
+  promptId: z.string().optional(),
 });
 
 export const turnEndedEventSchema = z.object({
diff --git a/packages/klient/src/contract/agent/schemas.ts b/packages/klient/src/contract/agent/schemas.ts
index fabcfcd5c82..c5301d868f7 100644
--- a/packages/klient/src/contract/agent/schemas.ts
+++ b/packages/klient/src/contract/agent/schemas.ts
@@ -39,6 +39,12 @@ export const emptyPayloadSchema = z.object({});
 
 export const promptPayloadSchema = z.object({
   input: z.array(promptPartSchema),
+  // Mirrors `PromptPayload.disabledTools` in the engine (client-managed
+  // session denylist, full-replace).
+  disabledTools: z.array(z.string()).optional(),
+  // Mirrors `PromptPayload.promptId` in the engine (client-chosen prompt
+  // record id, echoed on the consuming turn's `turn.started`).
+  promptId: z.string().min(1).optional(),
 });
 
 /** Same shape as `PromptSkillActivation` in the engine. */
diff --git a/packages/klient/src/contract/global/files.ts b/packages/klient/src/contract/global/files.ts
new file mode 100644
index 00000000000..74644dbe87f
--- /dev/null
+++ b/packages/klient/src/contract/global/files.ts
@@ -0,0 +1,46 @@
+/**
+ * `fileService` — process-global upload store. Mirrors
+ * `agent-core-v2/app/file/fileService.ts`.
+ *
+ * The wire cannot carry the engine's streams (every value JSON round-trips),
+ * so bytes cross base64-encoded: `save`'s `Readable` source becomes a base64
+ * string as the first argument, and `get`'s result stream is buffered
+ * server-side and returned as `{ meta, data }` with `data` base64-encoded.
+ * The dispatcher performs the stream ⇄ base64 adaptation; the facade encodes
+ * and decodes the caller's `Uint8Array`s.
+ */
+
+import { z } from 'zod';
+
+import { noResult } from '../helpers.js';
+import type { ServiceContract } from '../types.js';
+
+export const fileMetaSchema = z.object({
+  id: z.string().min(1),
+  name: z.string().min(1),
+  media_type: z.string().min(1),
+  size: z.number().int().nonnegative(),
+  created_at: z.string(),
+  expires_at: z.string().optional(),
+});
+
+export const fileSaveOptionsSchema = z.object({
+  name: z.string().optional(),
+  mimeType: z.string().optional(),
+  expiresInSec: z.number().optional(),
+});
+
+/** Wire result of `get` — the engine's `GetResult.stream` buffered to base64. */
+export const fileGetResultSchema = z.object({
+  meta: fileMetaSchema,
+  data: z.string(),
+});
+
+export const filesContract = {
+  save: {
+    input: z.tuple([z.string(), z.string().min(1), fileSaveOptionsSchema]),
+    output: fileMetaSchema,
+  },
+  get: { input: z.tuple([z.string().min(1)]), output: fileGetResultSchema },
+  delete: { input: z.tuple([z.string().min(1)]), output: noResult },
+} satisfies ServiceContract;
diff --git a/packages/klient/src/contract/index.ts b/packages/klient/src/contract/index.ts
index 1950f6d789a..4155f4b48a9 100644
--- a/packages/klient/src/contract/index.ts
+++ b/packages/klient/src/contract/index.ts
@@ -31,6 +31,7 @@ import { catalogContract } from './global/catalog.js';
 import { providerDiscoveryContract } from './global/providerDiscovery.js';
 import { configContract } from './global/config.js';
 import { envContract } from './global/env.js';
+import { filesContract } from './global/files.js';
 import { flagsContract } from './global/flags.js';
 import { hostFsContract } from './global/hostFs.js';
 import { modelsContract } from './global/models.js';
@@ -62,6 +63,7 @@ export const globalContract: KlientContract = {
   capabilityService: capabilitiesContract,
   hostFolderBrowser: hostFsContract,
   bootstrapService: envContract,
+  fileService: filesContract,
   sessionManager: sessionManagerContract,
   // session scope
   sessionMetadata: sessionMetadataContract,
diff --git a/packages/klient/src/core/facade/agent.ts b/packages/klient/src/core/facade/agent.ts
index 3fdb529b69a..14305c8b7d6 100644
--- a/packages/klient/src/core/facade/agent.ts
+++ b/packages/klient/src/core/facade/agent.ts
@@ -45,7 +45,11 @@ export type AgentTaskInfo = Awaited<ReturnType<IAgentTaskService['list']>>[numbe
 export type McpServerEntry = ReturnType<IAgentMcpService['list']>[number];
 
 export interface AgentFacade {
-  prompt(input: { input: readonly ContentPart[] }): Promise<PromptLaunchResult>;
+  prompt(input: {
+    input: readonly ContentPart[];
+    disabledTools?: readonly string[];
+    promptId?: string;
+  }): Promise<PromptLaunchResult>;
   /**
    * Submit one prompt with one or more skill activations bundled into the
    * same user message: the skills are validated up front (an unknown name or
diff --git a/packages/klient/src/core/facade/global.ts b/packages/klient/src/core/facade/global.ts
index 1415c6c5891..c185812f248 100644
--- a/packages/klient/src/core/facade/global.ts
+++ b/packages/klient/src/core/facade/global.ts
@@ -31,6 +31,7 @@ import type {
   FsBrowseResponse,
   FsHomeResponse,
 } from '@moonshot-ai/agent-core-v2/app/hostFolderBrowser/hostFolderBrowser';
+import type { FileMeta } from '@moonshot-ai/agent-core-v2/app/file/fileService';
 import type { ModelRecord } from '@moonshot-ai/agent-core-v2/kosong/model/model';
 import type { IModelCatalog } from '@moonshot-ai/agent-core-v2/kosong/model/catalog';
 import type { IProviderDiscoveryService } from '@moonshot-ai/agent-core-v2/app/kosongConfig/discovery';
@@ -221,6 +222,30 @@ export interface GlobalHostFsFacade {
   home(): Promise<FsHomeResponse>;
 }
 
+/** One downloaded upload: its metadata plus the buffered bytes. */
+export interface FileDownload {
+  readonly meta: FileMeta;
+  readonly data: Uint8Array;
+}
+
+export interface GlobalFilesFacade {
+  /**
+   * Upload buffered bytes to the daemon's file store. Bytes cross the wire
+   * base64-encoded (JSON cannot carry them), so very large uploads pay one
+   * encode here and one decode in the dispatcher.
+   */
+  save(input: {
+    data: Uint8Array;
+    filename: string;
+    name?: string;
+    mimeType?: string;
+    expiresInSec?: number;
+  }): Promise<FileMeta>;
+  /** Download one upload back into memory. */
+  get(fileId: string): Promise<FileDownload>;
+  delete(fileId: string): Promise<void>;
+}
+
 /** Aggregated host/environment snapshot (`bootstrapService` properties). */
 export interface KlientEnvInfo {
   readonly platform: string;
@@ -247,6 +272,7 @@ export interface GlobalFacade {
   readonly plugins: GlobalPluginsFacade;
   readonly capabilities: GlobalCapabilitiesFacade;
   readonly hostFs: GlobalHostFsFacade;
+  readonly files: GlobalFilesFacade;
   env(): Promise<KlientEnvInfo>;
 }
 
@@ -465,6 +491,23 @@ export function createGlobalFacade(scoped: ScopedCaller, scopedStream: ScopedStr
       home: () => call('hostFolderBrowser', 'home', []) as Promise<FsHomeResponse>,
     },
 
+    files: {
+      save: ({ data, filename, name, mimeType, expiresInSec }) =>
+        call('fileService', 'save', [
+          Buffer.from(data).toString('base64'),
+          filename,
+          { name, mimeType, expiresInSec },
+        ]) as Promise<FileMeta>,
+      get: async (fileId) => {
+        const wire = (await call('fileService', 'get', [fileId])) as {
+          meta: FileMeta;
+          data: string;
+        };
+        return { meta: wire.meta, data: Buffer.from(wire.data, 'base64') };
+      },
+      delete: (fileId) => call('fileService', 'delete', [fileId]) as Promise<void>,
+    },
+
     env,
   };
 }
diff --git a/packages/klient/src/index.ts b/packages/klient/src/index.ts
index 40eb1745e93..6ea629ac619 100644
--- a/packages/klient/src/index.ts
+++ b/packages/klient/src/index.ts
@@ -26,9 +26,11 @@ export type { Caller, ScopedCaller, ScopedStreamCaller } from './core/facade/glo
 
 export type {
   ConfigTargetLiteral,
+  FileDownload,
   GlobalAuthFacade,
   GlobalConfigFacade,
   GlobalFacade,
+  GlobalFilesFacade,
   GlobalFlagsFacade,
   GlobalHostFsFacade,
   GlobalKosongFacade,
@@ -112,6 +114,7 @@ export type {
   FsBrowseResponse,
   FsHomeResponse,
 } from '@moonshot-ai/agent-core-v2/app/hostFolderBrowser/hostFolderBrowser';
+export type { FileMeta } from '@moonshot-ai/agent-core-v2/app/file/fileService';
 export type {
   PluginCommandDef,
   PluginInfo,
diff --git a/packages/klient/src/transports/memory/dispatcher.ts b/packages/klient/src/transports/memory/dispatcher.ts
index 0eeee6dbaf5..a967ffa9130 100644
--- a/packages/klient/src/transports/memory/dispatcher.ts
+++ b/packages/klient/src/transports/memory/dispatcher.ts
@@ -22,6 +22,15 @@ import { IAgentLifecycleService } from '@moonshot-ai/agent-core-v2/session/agent
 import { ensureMainAgent } from '@moonshot-ai/agent-core-v2/session/agentLifecycle/mainAgent';
 import { ISessionInteractionService } from '@moonshot-ai/agent-core-v2/session/interaction/interaction';
 import { IEventBus } from '@moonshot-ai/agent-core-v2/app/event/eventBus';
+import type {
+  FileMeta,
+  GetResult,
+  SaveOptions,
+} from '@moonshot-ai/agent-core-v2/app/file/fileService';
+import { FileErrors } from '@moonshot-ai/agent-core-v2/app/file/fileService';
+import { Error2, ErrorCodes } from '@moonshot-ai/agent-core-v2/errors';
+
+import { Readable } from 'node:stream';
 
 import type { EventSourceRef, IDisposable, ScopeRef } from '../../core/channel.js';
 import { RPCError } from '../../core/errors.js';
@@ -53,6 +62,20 @@ export interface MemoryDispatcher {
 
 const REQUEST_INVALID = 40001;
 const NOT_FOUND = 40404;
+const PROMPT_ID_CONFLICT = 40927;
+
+/**
+ * Engine file errors cross the facade as public `RPCError`s, never as the
+ * engine's raw `Error2`. The dispatcher is shared by both transports, so
+ * memory and ipc then surface the identical `NOT_FOUND` code for a stale or
+ * expired upload id.
+ */
+function rethrowFileErrorAsRpc(error: unknown): never {
+  if (error instanceof Error2 && error.code === FileErrors.codes.FILE_NOT_FOUND) {
+    throw new RPCError(NOT_FOUND, error.message, error.details);
+  }
+  throw error;
+}
 
 type ScopeKind = 'core' | 'workspace' | 'session' | 'agent';
 
@@ -61,6 +84,12 @@ interface ResolvedScope {
   readonly like: ScopeLike;
 }
 
+/** Structural view of the engine's `IFileService` used by the wire adaptation. */
+type FileServiceWireTarget = {
+  save(source: Readable, filename: string, options?: SaveOptions): Promise<FileMeta>;
+  get(fileId: string): Promise<GetResult>;
+};
+
 export function createMemoryDispatcher(root: ScopeLike): MemoryDispatcher {
   /** Mirrors kap-server's `resolveScope`, incl. main-agent materialization. */
   async function resolveScope(scope: ScopeRef): Promise<ResolvedScope> {
@@ -156,6 +185,38 @@ export function createMemoryDispatcher(root: ScopeLike): MemoryDispatcher {
     async call(scope, service, method, args) {
       const resolved = await resolveScope(scope);
       const instance = resolveService(resolved, service);
+      // `fileService` adapts bytes ⇄ streams: the JSON wire cannot carry
+      // `save`'s Readable source or `get`'s result stream, so both cross as
+      // base64 strings (the same kind of wire adaptation as
+      // `modelResolver.generate` in `stream`).
+      if (service === 'fileService' && method === 'save') {
+        const [data, filename, options] = args as [string, string, SaveOptions | undefined];
+        const files = instance as FileServiceWireTarget;
+        try {
+          const meta = await files.save(
+            Readable.from(Buffer.from(data, 'base64')),
+            filename,
+            options,
+          );
+          return wireClone(meta);
+        } catch (error) {
+          rethrowFileErrorAsRpc(error);
+        }
+      }
+      if (service === 'fileService' && method === 'get') {
+        const [fileId] = args as [string];
+        const files = instance as FileServiceWireTarget;
+        try {
+          const { meta, stream } = await files.get(fileId);
+          const chunks: Buffer[] = [];
+          for await (const chunk of stream()) {
+            chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk as Uint8Array));
+          }
+          return { meta: wireClone(meta), data: Buffer.concat(chunks).toString('base64') };
+        } catch (error) {
+          rethrowFileErrorAsRpc(error);
+        }
+      }
       const member = instance[method];
       if (member === undefined) {
         throw new RPCError(REQUEST_INVALID, `method not found: ${service}.${method}`);
@@ -164,8 +225,15 @@ export function createMemoryDispatcher(root: ScopeLike): MemoryDispatcher {
         return wireClone(member);
       }
       const clonedArgs = args.map(wireClone);
-      const result = await (member as (...a: unknown[]) => unknown).apply(instance, clonedArgs);
-      return wireClone(result);
+      try {
+        const result = await (member as (...a: unknown[]) => unknown).apply(instance, clonedArgs);
+        return wireClone(result);
+      } catch (error) {
+        if (error instanceof Error2 && error.code === ErrorCodes.PROMPT_ID_CONFLICT) {
+          throw new RPCError(PROMPT_ID_CONFLICT, error.message, error.details);
+        }
+        throw error;
+      }
     },
 
     stream(scope, service, method, args): AsyncIterable<unknown> {
diff --git a/packages/klient/src/transports/memory/serviceRegistry.ts b/packages/klient/src/transports/memory/serviceRegistry.ts
index 4d98dc2bf0c..920aa8ca7ba 100644
--- a/packages/klient/src/transports/memory/serviceRegistry.ts
+++ b/packages/klient/src/transports/memory/serviceRegistry.ts
@@ -22,6 +22,7 @@ import { IPluginService } from '@moonshot-ai/agent-core-v2/app/plugin/plugin';
 import { ICapabilityService } from '@moonshot-ai/agent-core-v2/app/capability/capability';
 import { IBootstrapService } from '@moonshot-ai/agent-core-v2/app/bootstrap/bootstrap';
 import { IEventService } from '@moonshot-ai/agent-core-v2/app/event/event';
+import { IFileService } from '@moonshot-ai/agent-core-v2/app/file/fileService';
 import { IHostFolderBrowser } from '@moonshot-ai/agent-core-v2/app/hostFolderBrowser/hostFolderBrowser';
 import { IWorkspaceInstanceManager } from '@moonshot-ai/agent-core-v2/workspace/workspaceInstance/workspaceInstanceManager';
 import { ISessionManager } from '@moonshot-ai/agent-core-v2/app/sessionManager/sessionManager';
@@ -64,6 +65,7 @@ export const serviceTokens: Readonly<Record<string, ServiceIdentifier<unknown>>>
   capabilityService: ICapabilityService,
   hostFolderBrowser: IHostFolderBrowser,
   bootstrapService: IBootstrapService,
+  fileService: IFileService,
   workspaceInstanceManager: IWorkspaceInstanceManager,
   sessionManager: ISessionManager,
   sessionMetadata: ISessionMetadata,
diff --git a/packages/klient/test/contract-parity.ts b/packages/klient/test/contract-parity.ts
index 1738515e1a4..21ebb30eee7 100644
--- a/packages/klient/test/contract-parity.ts
+++ b/packages/klient/test/contract-parity.ts
@@ -82,6 +82,10 @@ import type {
   CapabilityStep,
 } from '@moonshot-ai/agent-core-v2/app/capability/types';
 import type { ExperimentalFeatureState } from '@moonshot-ai/agent-core-v2/app/flag/flag';
+import type {
+  FileMeta,
+  SaveOptions,
+} from '@moonshot-ai/agent-core-v2/app/file/fileService';
 import type {
   FsBrowseResponse,
   FsHomeResponse,
@@ -259,6 +263,10 @@ import {
   refreshProviderModelsResponseSchema,
 } from '../src/contract/global/providerDiscovery.js';
 import { experimentalFeatureStateSchema } from '../src/contract/global/flags.js';
+import {
+  fileMetaSchema,
+  fileSaveOptionsSchema,
+} from '../src/contract/global/files.js';
 import {
   fsBrowseResponseSchema,
   fsHomeResponseSchema,
@@ -373,6 +381,11 @@ const _experimentalFeatureState: AssertWire<
 const _fsBrowseResponse: AssertWire<typeof fsBrowseResponseSchema, FsBrowseResponse> = true;
 const _fsHomeResponse: AssertWire<typeof fsHomeResponseSchema, FsHomeResponse> = true;
 
+// files.ts (`fileGetResultSchema` has no engine counterpart — the wire
+// adaptation replaces `GetResult.stream` with base64 `data`).
+const _fileMeta: AssertWire<typeof fileMetaSchema, FileMeta> = true;
+const _fileSaveOptions: AssertWire<typeof fileSaveOptionsSchema, SaveOptions> = true;
+
 // catalog.ts / providerDiscovery.ts — protocol wire shapes derived through the
 // catalog and discovery service interfaces.
 type ModelCatalogItem = Awaited<ReturnType<IModelCatalog['listModels']>>[number];
diff --git a/packages/klient/test/contract.test.ts b/packages/klient/test/contract.test.ts
index 5f3103b692e..0d3b1ae6ba5 100644
--- a/packages/klient/test/contract.test.ts
+++ b/packages/klient/test/contract.test.ts
@@ -10,6 +10,7 @@ import { describe, expect, it } from 'vitest';
 
 import { pluginManifestSchema } from '../src/contract/global/plugins.js';
 import { createSessionOptionsSchema } from '../src/contract/session/lifecycle.js';
+import { promptPayloadSchema } from '../src/contract/agent/schemas.js';
 
 type McpTimeoutField = 'startupTimeoutMs' | 'toolTimeoutMs';
 
@@ -65,3 +66,13 @@ describe('MCP timeout contract validation', () => {
     expect(parsed.success).toBe(false);
   });
 });
+
+describe('prompt contract validation', () => {
+  it('rejects an empty caller-chosen promptId', () => {
+    expect(promptPayloadSchema.safeParse({ input: [], promptId: '' }).success).toBe(false);
+  });
+
+  it('accepts a non-empty caller-chosen promptId', () => {
+    expect(promptPayloadSchema.safeParse({ input: [], promptId: 'submission-1' }).success).toBe(true);
+  });
+});
diff --git a/packages/klient/test/facade.test.ts b/packages/klient/test/facade.test.ts
index 21b0b21fd8c..5a7e7ff915a 100644
--- a/packages/klient/test/facade.test.ts
+++ b/packages/klient/test/facade.test.ts
@@ -629,3 +629,61 @@ describe('event hub', () => {
     expect(errors[0]).toBeInstanceOf(KlientValidationError);
   });
 });
+
+describe('files routing', () => {
+  const META = {
+    id: 'f_1',
+    name: 'a.png',
+    media_type: 'image/png',
+    size: 4,
+    created_at: '2026-01-01T00:00:00.000Z',
+  };
+
+  it('routes the files save/get/delete lifecycle through fileService', async () => {
+    const channel = new FakeChannel();
+    const klient = createKlientFromChannel(channel);
+
+    channel.result = META;
+    const meta = await klient.global.files.save({
+      data: new Uint8Array([1, 2, 3, 4]),
+      filename: 'a.png',
+      mimeType: 'image/png',
+    });
+    expect(meta).toEqual(META);
+    expect(channel.calls[0]).toMatchObject({
+      scope: {},
+      service: 'fileService',
+      method: 'save',
+      args: ['AQIDBA==', 'a.png', { mimeType: 'image/png' }],
+    });
+
+    channel.result = { meta: META, data: 'AQIDBA==' };
+    const got = await klient.global.files.get('f_1');
+    expect(got.meta).toEqual(META);
+    expect([...got.data]).toEqual([1, 2, 3, 4]);
+    expect(channel.calls[1]).toMatchObject({
+      scope: {},
+      service: 'fileService',
+      method: 'get',
+      args: ['f_1'],
+    });
+
+    channel.result = undefined;
+    await expect(klient.global.files.delete('f_1')).resolves.toBeUndefined();
+    expect(channel.calls[2]).toMatchObject({
+      scope: {},
+      service: 'fileService',
+      method: 'delete',
+      args: ['f_1'],
+    });
+  });
+
+  it('files.save rejects invalid input before it hits the wire', async () => {
+    const channel = new FakeChannel();
+    const klient = createKlientFromChannel(channel);
+    await expect(
+      klient.global.files.save({ data: new Uint8Array(0), filename: '' }),
+    ).rejects.toBeInstanceOf(KlientValidationError);
+    expect(channel.calls).toHaveLength(0);
+  });
+});
diff --git a/packages/klient/test/helpers/conformance.ts b/packages/klient/test/helpers/conformance.ts
index ec5b0600fb6..531e1136dfe 100644
--- a/packages/klient/test/helpers/conformance.ts
+++ b/packages/klient/test/helpers/conformance.ts
@@ -14,6 +14,9 @@ import { join } from 'node:path';
 import { Service } from '@moonshot-ai/agent-core-v2/_base/di/service';
 import { CommandContribution } from '@moonshot-ai/agent-core-v2/agent/command/commandContribution';
 import { IFeatureManager } from '@moonshot-ai/agent-core-v2/app/feature/featureManager';
+import { getLiveSessionById } from '@moonshot-ai/agent-core-v2/app/sessionManager/sessionLookup';
+import { IAgentLifecycleService } from '@moonshot-ai/agent-core-v2/session/agentLifecycle/agentLifecycle';
+import { IAgentPromptService, reservePrompt } from '@moonshot-ai/agent-core-v2/agent/prompt/prompt';
 
 import type { Klient } from '../../src/index.js';
 import type { TestEngine } from './engine.js';
@@ -247,6 +250,31 @@ export function defineKlientConformance(
       expect(Array.isArray(browse.entries)).toBe(true);
     });
 
+    it('files save/get/delete round-trips bytes through the file store', async () => {
+      const files = target.klient.global.files;
+      const bytes = new Uint8Array([0, 1, 127, 128, 254, 255]);
+      const meta = await files.save({
+        data: bytes,
+        filename: 'conformance.bin',
+        mimeType: 'application/octet-stream',
+        expiresInSec: 3600,
+      });
+      expect(meta.id.startsWith('f_')).toBe(true);
+      expect(meta.name).toBe('conformance.bin');
+      expect(meta.media_type).toBe('application/octet-stream');
+      expect(meta.size).toBe(bytes.length);
+      expect(typeof meta.expires_at).toBe('string');
+
+      const downloaded = await files.get(meta.id);
+      expect(downloaded.meta).toEqual(meta);
+      expect([...downloaded.data]).toEqual([...bytes]);
+
+      await files.delete(meta.id);
+      // Both transports surface a deleted/expired upload as the same public
+      // RPCError code, never the engine's raw error type.
+      await expect(files.get(meta.id)).rejects.toMatchObject({ name: 'RPCError', code: 40404 });
+    });
+
     it('kosong lists models/providers and anonymous provider round-trips', async () => {
       const kosong = target.klient.global.kosong;
       expect(Array.isArray(await kosong.listModels())).toBe(true);
@@ -366,5 +394,27 @@ export function defineKlientConformance(
         await target.klient.session(created.id).close();
       }
     });
+
+    it('propagates prompt id conflicts with the same 40927 error', async () => {
+      const created = await target.klient.global.sessions.create({
+        workDir: process.cwd(),
+        title: 'conformance prompt conflict',
+      });
+      const session = getLiveSessionById(target.app.accessor, created.id);
+      if (session === undefined) throw new Error('conformance session was not materialized');
+      const main = await session.accessor.get(IAgentLifecycleService).create({ agentId: 'main' });
+      const reservation = reservePrompt(main.accessor.get(IAgentPromptService), 'submission-1');
+      try {
+        await expect(
+          target.klient.session(created.id).agent('main').prompt({
+            input: [{ type: 'text', text: 'duplicate' }],
+            promptId: 'submission-1',
+          }),
+        ).rejects.toMatchObject({ name: 'RPCError', code: 40927 });
+      } finally {
+        reservation.dispose();
+        await target.klient.session(created.id).close();
+      }
+    });
   });
 }
diff --git a/packages/node-sdk/src/index.ts b/packages/node-sdk/src/index.ts
index a2e10b94174..cc1823c6cb5 100644
--- a/packages/node-sdk/src/index.ts
+++ b/packages/node-sdk/src/index.ts
@@ -132,6 +132,24 @@ export type {
   FlagSurface,
 } from '@moonshot-ai/agent-core';
 
+// Daemon file references (agent-core-v2) — pure helpers for the internal
+// `kimi-file://` media URLs and the model-facing `<image|video|file>` path
+// tags. A daemon-ref media part is self-contained (kind from the part type,
+// file id from the url) — there is no tag+ref pairing to fold.
+// Hosts must not import agent-core-v2 directly; `FileMeta` and
+// `UploadFileOptions` ride the `export type * from '#/types'` below.
+export {
+  buildDaemonFileUrl,
+  buildMediaPathTag,
+  isDaemonFileUrl,
+  matchSingleMediaPathTag,
+  parseDaemonFileUrl,
+} from '@moonshot-ai/agent-core-v2/agent/media/mediaRef';
+export type {
+  DaemonFileRef,
+  MediaKind,
+} from '@moonshot-ai/agent-core-v2/agent/media/mediaRef';
+
 export type {
   KimiAuthCompleteFeedbackUploadInput,
   KimiAuthCompleteFeedbackUploadPart,
diff --git a/packages/node-sdk/src/kimi-harness.ts b/packages/node-sdk/src/kimi-harness.ts
index 15f755ab9b6..ccfa065892f 100644
--- a/packages/node-sdk/src/kimi-harness.ts
+++ b/packages/node-sdk/src/kimi-harness.ts
@@ -17,6 +17,7 @@ import type {
   CreateSessionOptions,
   ExportSessionInput,
   ExportSessionResult,
+  FileMeta,
   ForkSessionInput,
   GenerateSessionTitleInput,
   GetConfigOptions,
@@ -42,6 +43,7 @@ import type {
   TelemetryContextPatch,
   TelemetryProperties,
   TestMcpServerOptions,
+  UploadFileOptions,
   WorkspaceTrustInfo,
 } from '#/types';
 
@@ -418,6 +420,20 @@ export class KimiHarness {
     return this.rpc.getExperimentalFeatures();
   }
 
+  /**
+   * Upload media bytes to the engine's file store; pair the returned meta
+   * with `buildDaemonFileUrl` to reference the file from a prompt.
+   * agent-core-v2 only — the v1 engine throws `not_implemented`.
+   */
+  async uploadFile(data: Uint8Array, options: UploadFileOptions): Promise<FileMeta> {
+    return this.rpc.uploadFile(data, options);
+  }
+
+  /** Delete a daemon upload owned by a client-side staging operation. */
+  async deleteFile(fileId: string): Promise<void> {
+    return this.rpc.deleteFile(fileId);
+  }
+
   async ensureConfigFile(): Promise<void> {
     await this.ensureConfigFileImpl();
   }
diff --git a/packages/node-sdk/src/rpc.ts b/packages/node-sdk/src/rpc.ts
index 8f122317a80..4f2c67f3d56 100644
--- a/packages/node-sdk/src/rpc.ts
+++ b/packages/node-sdk/src/rpc.ts
@@ -34,6 +34,7 @@ import type {
   ExportSessionInput,
   ExportSessionResult,
   CreateGoalInput,
+  FileMeta,
   ForkSessionInput,
   GenerateSessionTitleInput,
   GetConfigOptions,
@@ -66,6 +67,7 @@ import type {
   SkillSummary,
   PluginCommandDef,
   Unsubscribe,
+  UploadFileOptions,
   WorkspaceTrustInfo,
 } from '#/types';
 
@@ -74,6 +76,18 @@ const MAIN_AGENT_ID = 'main';
 export interface SessionPromptRpcInput {
   readonly sessionId: string;
   readonly input: PromptInput;
+  /**
+   * Client-managed session tool denylist (full-replace semantics), forwarded
+   * to engines with profile tool gating. Omit to keep the persisted value;
+   * `[]` clears the client portion.
+   */
+  readonly disabledTools?: readonly string[];
+  /**
+   * Client-chosen prompt record id, unique for the Agent's persisted history
+   * and echoed on the consuming turn's `turn.started` (`promptId`). Honored by
+   * the v2 RPC client only.
+   */
+  readonly promptId?: string;
 }
 
 export interface SessionPromptWithSkillsRpcInput extends SessionPromptRpcInput {
@@ -340,6 +354,26 @@ export abstract class SDKRpcClientBase {
     );
   }
 
+  /**
+   * Upload media bytes to the engine's daemon file store; pair the returned
+   * meta with `buildDaemonFileUrl` to reference the file from a prompt. Only
+   * the v2 client wires this (through the klient files facade) — the v1
+   * client has no file service and throws `not_implemented`.
+   */
+  uploadFile(_data: Uint8Array, _options: UploadFileOptions): Promise<FileMeta> {
+    throw new KimiError(
+      ErrorCodes.NOT_IMPLEMENTED,
+      'This SDK client does not support file upload.',
+    );
+  }
+
+  deleteFile(_fileId: string): Promise<void> {
+    throw new KimiError(
+      ErrorCodes.NOT_IMPLEMENTED,
+      'This SDK client does not support file deletion.',
+    );
+  }
+
   async listGlobalMcpServers(): Promise<readonly McpServerConfig[]> {
     const rpc = await this.getRpc();
     return rpc.listGlobalMcpServers({});
diff --git a/packages/node-sdk/src/sdk-rpc-client-v2.ts b/packages/node-sdk/src/sdk-rpc-client-v2.ts
index 7a1539d31b0..d9dbbb75e91 100644
--- a/packages/node-sdk/src/sdk-rpc-client-v2.ts
+++ b/packages/node-sdk/src/sdk-rpc-client-v2.ts
@@ -263,6 +263,7 @@ import type {
   CreateSessionOptions,
   ExportSessionInput,
   ExportSessionResult,
+  FileMeta,
   ForkSessionInput,
   GenerateSessionTitleInput,
   GetConfigOptions,
@@ -297,6 +298,7 @@ import type {
   SessionUsage,
   SkillSummary,
   TelemetryClient,
+  UploadFileOptions,
   WorkspaceTrustInfo,
 } from '#/types';
 import {
@@ -564,6 +566,24 @@ export class SDKRpcClientV2 extends SDKRpcClientBase {
     return this.klient.global.flags.list();
   }
 
+  /**
+   * `uploadFile` → `klient.global.files.save` (the app-scope `IFileService`).
+   * The SDK's single `name` doubles as the engine's `filename`; the engine's
+   * `SaveOptions.name` (display name) defaults to it.
+   */
+  override async uploadFile(data: Uint8Array, options: UploadFileOptions): Promise<FileMeta> {
+    return this.klient.global.files.save({
+      data,
+      filename: options.name,
+      mimeType: options.mimeType,
+      expiresInSec: options.expiresInSec,
+    });
+  }
+
+  override async deleteFile(fileId: string): Promise<void> {
+    return this.klient.global.files.delete(fileId);
+  }
+
   /**
    * Through the workspace handler's `IWorkspaceSkillCatalog` — the engine's
    * own merged view (builtin / user / explicit / extra / workspace-root /
@@ -1817,7 +1837,11 @@ export class SDKRpcClientV2 extends SDKRpcClientBase {
    */
   override async prompt(input: SessionPromptRpcInput): Promise<void> {
     const agent = await this.agentFacade(input.sessionId);
-    await agent.prompt({ input: input.input });
+    await agent.prompt({
+      input: input.input,
+      disabledTools: input.disabledTools,
+      promptId: input.promptId,
+    });
   }
 
   /**
diff --git a/packages/node-sdk/src/session.ts b/packages/node-sdk/src/session.ts
index 765809265a7..4834dfcac35 100644
--- a/packages/node-sdk/src/session.ts
+++ b/packages/node-sdk/src/session.ts
@@ -136,11 +136,15 @@ export class Session {
     this.rpc.setQuestionHandler(this.id, handler);
   }
 
-  async prompt(input: string | PromptInput): Promise<void> {
+  async prompt(input: string | PromptInput, options?: { promptId?: string }): Promise<void> {
     this.ensureOpen();
+    if (options?.promptId !== undefined && options.promptId.length === 0) {
+      throw new TypeError('promptId must not be empty');
+    }
     await this.rpc.prompt({
       sessionId: this.id,
       input: normalizePromptInput(input),
+      promptId: options?.promptId,
     });
   }
 
diff --git a/packages/node-sdk/src/types.ts b/packages/node-sdk/src/types.ts
index 510b6e93d48..d5be5ac1612 100644
--- a/packages/node-sdk/src/types.ts
+++ b/packages/node-sdk/src/types.ts
@@ -106,6 +106,17 @@ export interface WorkspaceTrustInfo {
   readonly gatedMcpServers: readonly WorkspaceTrustMcpServerInfo[];
 }
 
+/** Metadata of one upload in the engine's daemon file store. */
+export type { FileMeta } from '@moonshot-ai/agent-core-v2/app/file/fileService';
+
+/** Input for `uploadFile`: the upload's display name and MIME type. */
+export interface UploadFileOptions {
+  readonly name: string;
+  readonly mimeType?: string;
+  /** Optional daemon-side TTL for staging uploads. */
+  readonly expiresInSec?: number;
+}
+
 export interface CreateGoalInput {
   readonly objective: string;
   readonly replace?: boolean;
diff --git a/packages/node-sdk/src/v2/event-mapper.ts b/packages/node-sdk/src/v2/event-mapper.ts
index e004e396c11..1aa63f11ee0 100644
--- a/packages/node-sdk/src/v2/event-mapper.ts
+++ b/packages/node-sdk/src/v2/event-mapper.ts
@@ -67,6 +67,14 @@ export function translateDomainEvent(
 ): Event | undefined {
   if (DROPPED_DOMAIN_EVENT_TYPES.has(event.type)) return undefined;
   const type = RENAMED_DOMAIN_EVENT_TYPES[event.type] ?? event.type;
+  if (event.type === 'turn.started') {
+    // `promptAttachments` is an internal transcript-projection input, not part
+    // of the public event contract — kap-server strips it from the WS wire
+    // event, so the in-process SDK drops it too, keeping both consumers on the
+    // same `turn.started` field set.
+    const { promptAttachments: _internal, ...publicFields } = event;
+    return { ...publicFields, type, sessionId, agentId } as unknown as Event;
+  }
   return { ...event, type, sessionId, agentId } as unknown as Event;
 }
 
diff --git a/packages/node-sdk/test/kimi-harness.test.ts b/packages/node-sdk/test/kimi-harness.test.ts
index 4f7c82ca40a..3068b14b5a8 100644
--- a/packages/node-sdk/test/kimi-harness.test.ts
+++ b/packages/node-sdk/test/kimi-harness.test.ts
@@ -138,3 +138,22 @@ read_byte_budget = 65536
     expect(harness.imageLimits?.maxEdgePx()).toBe(900);
   });
 });
+
+describe('KimiHarness v1 file ops', () => {
+  it('rejects file upload and deletion as not implemented on the v1 harness', async () => {
+    const homeDir = await mkdtemp(join(tmpdir(), 'kimi-sdk-harness-'));
+    tempDirs.push(homeDir);
+
+    const harness = createKimiHarness({ identity: TEST_IDENTITY, homeDir });
+    try {
+      await expect(
+        harness.uploadFile(new Uint8Array([137, 80, 78, 71]), { name: 'pixel.png' }),
+      ).rejects.toThrow(/does not support file upload/);
+      await expect(harness.deleteFile('f_example')).rejects.toThrow(
+        /does not support file deletion/,
+      );
+    } finally {
+      await harness.close();
+    }
+  });
+});
diff --git a/packages/node-sdk/test/sdk-rpc-client-v2.test.ts b/packages/node-sdk/test/sdk-rpc-client-v2.test.ts
index d7d55ab384a..547ff32e88d 100644
--- a/packages/node-sdk/test/sdk-rpc-client-v2.test.ts
+++ b/packages/node-sdk/test/sdk-rpc-client-v2.test.ts
@@ -20,8 +20,10 @@ import {
 import { afterEach, describe, expect, it, vi } from 'vitest';
 
 import {
+  buildDaemonFileUrl,
   createKimiHarnessV2,
   ErrorCodes,
+  isDaemonFileUrl,
   KimiHarness,
   removeProviderFromConfig,
   SDKRpcClientV2,
@@ -277,6 +279,32 @@ describe('SDKRpcClientV2 (agent-core-v2 wiring)', () => {
     }
   });
 
+  it('uploadFile stores bytes through the klient files facade', async () => {
+    const { harness } = await makeHarness();
+    try {
+      const bytes = new Uint8Array([137, 80, 78, 71]);
+      const meta = await harness.uploadFile(bytes, {
+        name: 'pixel.png',
+        mimeType: 'image/png',
+        expiresInSec: 60,
+      });
+      expect(meta.id.startsWith('f_')).toBe(true);
+      expect(meta.name).toBe('pixel.png');
+      expect(meta.media_type).toBe('image/png');
+      expect(meta.size).toBe(bytes.length);
+      expect(typeof meta.created_at).toBe('string');
+      expect(typeof meta.expires_at).toBe('string');
+
+      // Re-export smoke only — helper behavior is pinned by agent-core-v2's
+      // mediaRef tests.
+      expect(isDaemonFileUrl(buildDaemonFileUrl(meta.id))).toBe(true);
+      await harness.deleteFile(meta.id);
+      await expect(harness.deleteFile(meta.id)).rejects.toThrow(/file not found/);
+    } finally {
+      await harness.close();
+    }
+  });
+
   it('emits one complete metadata event when a generated title is applied', async () => {
     const homeDir = await mkdtemp(join(tmpdir(), 'kimi-sdk-v2-'));
     tempDirs.push(homeDir);
diff --git a/packages/node-sdk/test/session-event-wiring.test.ts b/packages/node-sdk/test/session-event-wiring.test.ts
index 6f0fe206ae3..ef36331dd14 100644
--- a/packages/node-sdk/test/session-event-wiring.test.ts
+++ b/packages/node-sdk/test/session-event-wiring.test.ts
@@ -159,4 +159,34 @@ describe('SessionEventWiring status snapshot fold', () => {
     expect(events[0]).toMatchObject({ type: 'agent.status.updated', usage: USAGE });
     expect(events[0]).not.toHaveProperty('model');
   });
+
+  it('strips the internal promptAttachments field from turn.started', () => {
+    const sub = new FakeAgentHandle('agent-1');
+    const { sink, events } = collectingSink();
+    const wiring = new SessionEventWiring(makeSession([sub]), sink);
+    try {
+      // `promptAttachments` is transcript-projection metadata: kap-server
+      // strips it from the WS wire event, so SDK consumers must not see it
+      // either.
+      sub.bus.emit({
+        type: 'turn.started',
+        turnId: 1,
+        origin: { kind: 'user' },
+        prompt: 'describe this',
+        promptAttachments: [{ kind: 'image', fileId: 'f_1' }],
+      });
+    } finally {
+      wiring.dispose();
+    }
+
+    expect(events).toHaveLength(1);
+    expect(events[0]).toMatchObject({
+      type: 'turn.started',
+      turnId: 1,
+      sessionId: 's1',
+      agentId: 'agent-1',
+      prompt: 'describe this',
+    });
+    expect(events[0]).not.toHaveProperty('promptAttachments');
+  });
 });
diff --git a/packages/node-sdk/test/session-prompt-input.test.ts b/packages/node-sdk/test/session-prompt-input.test.ts
index f88c710009c..9ec42eb886b 100644
--- a/packages/node-sdk/test/session-prompt-input.test.ts
+++ b/packages/node-sdk/test/session-prompt-input.test.ts
@@ -82,6 +82,37 @@ describe('Session.prompt input normalization', () => {
     });
   });
 
+  it('forwards a caller-chosen promptId to the core RPC client', async () => {
+    const prompt = vi.fn(async () => {});
+    const session = new Session({
+      id: 'ses_prompt_id',
+      workDir: '/tmp/work',
+      rpc: { prompt } as unknown as SDKRpcClientBase,
+    });
+
+    await session.prompt('hello', { promptId: 'sub-1' });
+
+    expect(prompt).toHaveBeenCalledWith({
+      sessionId: 'ses_prompt_id',
+      input: [{ type: 'text', text: 'hello' }],
+      promptId: 'sub-1',
+    });
+  });
+
+  it('rejects an empty caller-chosen promptId before calling RPC', async () => {
+    const prompt = vi.fn(async () => {});
+    const session = new Session({
+      id: 'ses_prompt_id',
+      workDir: '/tmp/work',
+      rpc: { prompt } as unknown as SDKRpcClientBase,
+    });
+
+    await expect(session.prompt('hello', { promptId: '' })).rejects.toThrow(
+      'promptId must not be empty',
+    );
+    expect(prompt).not.toHaveBeenCalled();
+  });
+
   it('starts btw and returns the forked agent id', async () => {
     const startBtw = vi.fn(async () => 'agent-btw');
     const session = new Session({
diff --git a/packages/protocol/src/__tests__/events.test.ts b/packages/protocol/src/__tests__/events.test.ts
index 3b7638944ba..6b97ab7751d 100644
--- a/packages/protocol/src/__tests__/events.test.ts
+++ b/packages/protocol/src/__tests__/events.test.ts
@@ -114,10 +114,12 @@ describe('events / display re-exports', () => {
       sessionId: 'sess_1',
       turnId: 1,
       origin: { kind: 'user' },
+      promptId: 'prompt_1',
     });
 
     expect(parsed.agentId).toBe('agent_1');
     expect(parsed.sessionId).toBe('sess_1');
+    expect((parsed as { promptId?: string }).promptId).toBe('prompt_1');
   });
 
   it('validates prompt.submitted events', () => {
diff --git a/packages/protocol/src/__tests__/message.test.ts b/packages/protocol/src/__tests__/message.test.ts
index 75f516aa7b0..4939430b9f3 100644
--- a/packages/protocol/src/__tests__/message.test.ts
+++ b/packages/protocol/src/__tests__/message.test.ts
@@ -89,6 +89,14 @@ describe('messageContentSchema variants', () => {
     expect(parsed.source.kind).toBe('file');
   });
 
+  it('parses session-owned media source from stored history', () => {
+    const parsed = imageContentSchema.parse({
+      type: 'image',
+      source: { kind: 'session_media', file_id: 'file_image_01' },
+    });
+    expect(parsed.source.kind).toBe('session_media');
+  });
+
   it('parses file content', () => {
     const parsed = fileContentSchema.parse({
       type: 'file',
diff --git a/packages/protocol/src/__tests__/rest-prompt.test.ts b/packages/protocol/src/__tests__/rest-prompt.test.ts
index a8f95f230a8..2128d562338 100644
--- a/packages/protocol/src/__tests__/rest-prompt.test.ts
+++ b/packages/protocol/src/__tests__/rest-prompt.test.ts
@@ -91,6 +91,23 @@ describe('promptSubmissionSchema', () => {
     expect(parsed.plan_mode).toBe(false);
   });
 
+  it('preserves a client-chosen prompt_id through parsing', () => {
+    const parsed = promptSubmissionSchema.parse({
+      content: [{ type: 'text', text: 'hi' }],
+      prompt_id: 'client-prompt-1',
+    });
+    expect(parsed.prompt_id).toBe('client-prompt-1');
+  });
+
+  it('rejects an empty prompt_id', () => {
+    expect(
+      promptSubmissionSchema.safeParse({
+        content: [{ type: 'text', text: 'hi' }],
+        prompt_id: '',
+      }).success,
+    ).toBe(false);
+  });
+
   it('rejects empty content array', () => {
     expect(
       promptSubmissionSchema.safeParse({
diff --git a/packages/protocol/src/error-codes.ts b/packages/protocol/src/error-codes.ts
index ee1ebc344fc..13a14777c5b 100644
--- a/packages/protocol/src/error-codes.ts
+++ b/packages/protocol/src/error-codes.ts
@@ -101,6 +101,8 @@ export const ErrorCode = {
   FS_ALREADY_EXISTS: 40919,
   /** goal 只允许主 agent 使用 */
   GOAL_UNSUPPORTED_AGENT: 40920,
+  /** prompt_id 已在该 agent 的历史中使用 */
+  PROMPT_ID_CONFLICT: 40927,
 
   /** approval 60s 超时 */
   APPROVAL_EXPIRED: 41001,
@@ -197,6 +199,7 @@ export const ErrorCodeReason: Readonly<Record<ErrorCode, string>> = {
   [ErrorCode.GOAL_OBJECTIVE_TOO_LONG]: 'goal.objective_too_long',
   [ErrorCode.FS_ALREADY_EXISTS]: 'fs.already_exists',
   [ErrorCode.GOAL_UNSUPPORTED_AGENT]: 'goal.unsupported_agent',
+  [ErrorCode.PROMPT_ID_CONFLICT]: 'prompt.id_conflict',
 
   [ErrorCode.APPROVAL_EXPIRED]: 'approval.expired',
   [ErrorCode.QUESTION_EXPIRED]: 'question.expired',
diff --git a/packages/protocol/src/events.ts b/packages/protocol/src/events.ts
index 76caa3ef9ab..0ab7d8e5da8 100644
--- a/packages/protocol/src/events.ts
+++ b/packages/protocol/src/events.ts
@@ -310,6 +310,7 @@ export type KimiErrorCode =
   | 'request.invalid'
   | 'request.work_dir_required'
   | 'request.prompt_input_empty'
+  | 'prompt.id_conflict'
   | 'prompt.not_found'
   | 'prompt.already_completed'
   | 'session.busy'
@@ -671,6 +672,8 @@ export interface TurnStartedEvent {
   readonly turnId: number;
   readonly origin: PromptOrigin;
   readonly prompt?: string;
+  /** The prompt record id when the turn was opened by a prompt submission. */
+  readonly promptId?: string;
 }
 
 export interface TurnEndedEvent {
@@ -1314,6 +1317,7 @@ export const kimiErrorCodeSchema = z.enum([
   'request.invalid',
   'request.work_dir_required',
   'request.prompt_input_empty',
+  'prompt.id_conflict',
   'prompt.not_found',
   'prompt.already_completed',
   'session.busy',
@@ -1630,6 +1634,7 @@ export const turnStartedEventSchema = z.object({
   turnId: z.number(),
   origin: promptOriginSchema,
   prompt: z.string().optional(),
+  promptId: z.string().optional(),
 }) satisfies z.ZodType<TurnStartedEvent>;
 
 export const turnEndedEventSchema = z.object({
diff --git a/packages/protocol/src/message.ts b/packages/protocol/src/message.ts
index 29f1f62d3ed..f33905e6780 100644
--- a/packages/protocol/src/message.ts
+++ b/packages/protocol/src/message.ts
@@ -41,6 +41,9 @@ export const imageSourceSchema = z.discriminatedUnion('kind', [
     data: z.string().min(1),
   }),
   z.object({ kind: z.literal('file'), file_id: z.string().min(1) }),
+  // Stored prompt/message projections address the Session-owned canonical
+  // copy; `file` remains the transient upload form accepted on submission.
+  z.object({ kind: z.literal('session_media'), file_id: z.string().min(1) }),
 ]);
 export type ImageSource = z.infer<typeof imageSourceSchema>;
 
@@ -50,7 +53,7 @@ export const imageContentSchema = z.object({
 });
 export type ImageContent = z.infer<typeof imageContentSchema>;
 
-// Video uses the same source shape as image (url / base64 / uploaded file id).
+// Video uses the same source shape as image (url / base64 / uploaded or Session media id).
 export const videoContentSchema = z.object({
   type: z.literal('video'),
   source: imageSourceSchema,
diff --git a/packages/protocol/src/rest/prompt.ts b/packages/protocol/src/rest/prompt.ts
index 8bb1fca9b0f..9ecd4d67480 100644
--- a/packages/protocol/src/rest/prompt.ts
+++ b/packages/protocol/src/rest/prompt.ts
@@ -61,6 +61,10 @@ export const promptSubmissionSchema = z.object({
   // bound profile's own deny always survives. Omit to keep the persisted
   // value, send `[]` to clear the client portion.
   disabled_tools: z.array(z.string()).optional(),
+  // Client-chosen prompt record id; the engine echoes it on the consuming
+  // turn's `turn.started` (`promptId`) so the submitter can bind its own
+  // bookkeeping to that turn exactly. Omit to let the engine assign one.
+  prompt_id: z.string().min(1).optional(),
 });
 export type PromptSubmission = z.infer<typeof promptSubmissionSchema>;
 
diff --git a/packages/transcript/src/contract/mediaRef.ts b/packages/transcript/src/contract/mediaRef.ts
new file mode 100644
index 00000000000..cefe20b04da
--- /dev/null
+++ b/packages/transcript/src/contract/mediaRef.ts
@@ -0,0 +1,98 @@
+/**
+ * `contract` — media path tag + kimi-file ref recognition for read models.
+ *
+ * Browser-pure mirror of the engine grammar
+ * (`packages/agent-core-v2/src/agent/media/mediaRef.ts`), duplicated
+ * because this package must not import the engine — keep the two in sync.
+ *
+ * A daemon-ref media part is self-contained: the part type carries the kind
+ * and the reference the daemon file id, so read models derive the attachment
+ * straight from the part via `daemonFileRefFromPairingPart` — there is no
+ * tag+ref pairing to compute. A standalone `<media path>` tag in history is
+ * user-visible text or the legacy degrade form and always stays a text part.
+ */
+
+export type MediaPathTagKind = 'image' | 'video' | 'audio' | 'file';
+
+export interface MediaPathTagMatch {
+  readonly kind: MediaPathTagKind;
+  readonly path: string;
+}
+
+const SINGLE_MEDIA_PATH_TAG_RE =
+  /^\s*<(image|video|audio|file)\b[^>]*?\bpath="([^"]*)"[^>]*>(?:<\/\1>)?\s*$/;
+
+/**
+ * The whole text is exactly one media path tag (surrounding whitespace
+ * tolerated) — the mirror of the engine's `matchSingleMediaPathTag`.
+ * Tolerates extra attributes and a missing closing tag, like the engine
+ * grammar. Tags embedded in larger user text are NOT matched: stripping
+ * there would eat user content.
+ */
+export function matchMediaPathTagText(text: string): MediaPathTagMatch | undefined {
+  const match = SINGLE_MEDIA_PATH_TAG_RE.exec(text);
+  if (match === null) return undefined;
+  return { kind: match[1] as MediaPathTagKind, path: unescapeMediaAttribute(match[2]!) };
+}
+
+function unescapeMediaAttribute(value: string): string {
+  return value
+    .replaceAll('&quot;', '"')
+    .replaceAll('&lt;', '<')
+    .replaceAll('&gt;', '>')
+    .replaceAll('&amp;', '&');
+}
+
+const KIMI_FILE_SCHEME = 'kimi-file://';
+
+/** The daemon upload reference behind a `kimi-file://<fileId>` url. */
+export interface DaemonFileRef {
+  readonly fileId: string;
+}
+
+/**
+ * Parse a `kimi-file://<fileId>` url — the mirror of the engine's
+ * `parseDaemonFileUrl`. A legacy `?path=` query (the retired persisted
+ * materialization path) is stripped and ignored.
+ */
+export function parseDaemonFileRef(url: string): DaemonFileRef | undefined {
+  if (!url.startsWith(KIMI_FILE_SCHEME)) return undefined;
+  const rest = url.slice(KIMI_FILE_SCHEME.length);
+  const queryAt = rest.indexOf('?');
+  const fileId = queryAt === -1 ? rest : rest.slice(0, queryAt);
+  return fileId.length > 0 ? { fileId } : undefined;
+}
+
+/** The daemon upload id behind a `kimi-file://<fileId>` url. */
+export function parseDaemonFileRefFileId(url: string): string | undefined {
+  return parseDaemonFileRef(url)?.fileId;
+}
+
+/**
+ * The structural minimum the daemon-ref extraction needs from a content
+ * part — the kosong `text` / `image_url` / `video_url` shapes plus anything
+ * else.
+ */
+export interface MediaRefPart {
+  readonly type: string;
+  readonly text?: string;
+  readonly imageUrl?: { readonly url?: string };
+  readonly videoUrl?: { readonly url?: string };
+}
+
+/**
+ * The daemon reference behind a content part, if any — the mirror of the
+ * engine's `daemonFileRefFromPart` (keep the two in sync): the kind comes
+ * from the part type, the file id from the `kimi-file://` url. This is the
+ * single part → ref extraction read models share.
+ */
+export function daemonFileRefFromPairingPart(
+  part: MediaRefPart,
+): { readonly kind: 'image' | 'video'; readonly ref: DaemonFileRef } | undefined {
+  if (part.type !== 'image_url' && part.type !== 'video_url') return undefined;
+  const url = part.type === 'image_url' ? part.imageUrl?.url : part.videoUrl?.url;
+  if (typeof url !== 'string') return undefined;
+  const ref = parseDaemonFileRef(url);
+  if (ref === undefined) return undefined;
+  return { kind: part.type === 'image_url' ? 'image' : 'video', ref };
+}
diff --git a/packages/transcript/src/contract/schema.ts b/packages/transcript/src/contract/schema.ts
index ce55f347a35..84afbaf70fd 100644
--- a/packages/transcript/src/contract/schema.ts
+++ b/packages/transcript/src/contract/schema.ts
@@ -354,6 +354,7 @@ export const attachmentSchema = z.object({
     .discriminatedUnion('kind', [
       z.object({ kind: z.literal('url'), url: z.string() }),
       z.object({ kind: z.literal('file'), fileId: z.string() }),
+      z.object({ kind: z.literal('session_media'), fileId: z.string() }),
     ])
     .optional(),
   placeholder: z.string().optional(),
diff --git a/packages/transcript/src/history/groupTurns.ts b/packages/transcript/src/history/groupTurns.ts
index c675186f246..e6f8b79d909 100644
--- a/packages/transcript/src/history/groupTurns.ts
+++ b/packages/transcript/src/history/groupTurns.ts
@@ -11,7 +11,10 @@
  *    context messages do not carry them (turn end facts DO persist as
  *    `turn.ended` records and are folded in by `foldWireRecordFacts`);
  *  - media content parts become attachment entities (metadata only — base64
- *    bytes are dropped, never shipped); mid-turn media is not anchored;
+ *    bytes are dropped, never shipped); mid-turn media is not anchored. A
+ *    daemon-ref media part (`kimi-file://<fileId>`) is self-contained
+ *    and projects to a single attachment; a standalone `<media path>` tag is
+ *    user text or the legacy degrade form and stays prompt text;
  *  - streamed-vs-persisted duplication is assumed already resolved upstream;
  *  - only the turn tree is built here: tasks / interactions / todos / meta
  *    (goal, plan, swarm) are NOT context messages — the companion fold
@@ -33,6 +36,7 @@ import type { TranscriptAttachment } from '../model/attachment';
 import type { TranscriptFrame } from '../model/frame';
 import type { TranscriptItem, TranscriptMarker } from '../model/item';
 import type { TurnOrigin } from '../model/turn';
+import { daemonFileRefFromPairingPart } from '../contract/mediaRef';
 
 export type HistoryMediaSource =
   | { readonly kind: 'url'; readonly url: string }
@@ -114,10 +118,24 @@ export function groupMessagesIntoSnapshot(
   let nextOrdinal = 0;
   let markerCount = 0;
 
-  /** Media parts of a turn-opening user message → attachment entities (+ ids). */
-  const collectAttachments = (message: HistoryMessage): string[] | undefined => {
+  /**
+   * Turn-opening user message → prompt text + attachment ids. A daemon-ref
+   * media part (`kimi-file://<fileId>`) is self-contained: it yields one
+   * attachment. Text parts pass through verbatim — a standalone
+   * `<media path>` tag is user text or the legacy degrade form, never markup
+   * the read model may eat.
+   */
+  const foldTurnOpeningInput = (
+    message: HistoryMessage,
+  ): { text: string; attachmentIds?: string[] } => {
+    const parts = message.content ?? [];
     const ids: string[] = [];
-    for (const part of message.content ?? []) {
+    const texts: string[] = [];
+    for (const part of parts) {
+      if (part.type === 'text' && 'text' in part && typeof part.text === 'string') {
+        texts.push(part.text);
+        continue;
+      }
       if (part.type === 'image' || part.type === 'video' || part.type === 'audio') {
         if (!('source' in part) || part.source === undefined) continue;
         const source = part.source as HistoryMediaSource;
@@ -135,7 +153,9 @@ export function groupMessagesIntoSnapshot(
         };
         attachments.push(entity);
         ids.push(entity.attachmentId);
-      } else if (part.type === 'file' && 'file_id' in part) {
+        continue;
+      }
+      if (part.type === 'file' && 'file_id' in part) {
         const entity: TranscriptAttachment = {
           attachmentId: `att_${attachments.length + 1}`,
           mediaType: part.media_type as string,
@@ -145,9 +165,20 @@ export function groupMessagesIntoSnapshot(
         };
         attachments.push(entity);
         ids.push(entity.attachmentId);
+        continue;
+      }
+      const ref = daemonFileRefFromPairingPart(part);
+      if (ref !== undefined) {
+        const entity: TranscriptAttachment = {
+          attachmentId: `att_${attachments.length + 1}`,
+          mediaType: `${ref.kind}/*`,
+          source: { kind: 'session_media', fileId: ref.ref.fileId },
+        };
+        attachments.push(entity);
+        ids.push(entity.attachmentId);
       }
     }
-    return ids.length > 0 ? ids : undefined;
+    return { text: texts.join(''), attachmentIds: ids.length > 0 ? ids : undefined };
   };
 
   const ensureTurn = (origin: TurnOrigin = FALLBACK_ORIGIN): TurnDraft => {
@@ -190,13 +221,17 @@ export function groupMessagesIntoSnapshot(
       }
       const markerKey = originKind !== undefined ? MARKER_USER_ORIGINS[originKind] : undefined;
       if (markerKey !== undefined) {
-        pushMarker(markerKey, { text: textOf(message), origin: message.origin });
         // A user-slash skill/plugin command is a real user prompt (mirrors
         // the engine's `isRealUserPrompt`): it opened its own turn, so
         // advance the grouping instead of folding the response into the
         // previous turn. Other triggers are mid-turn context — marker only.
-        if (isUserSlashPrompt(message)) {
-          startTurn(mapOrigin(message), textOf(message));
+        // A slash turn-opening input projects like any other user's (each
+        // daemon-ref media part → one attachment), mirroring the live
+        // `projectTurnPrompt` projection.
+        const opening = isUserSlashPrompt(message) ? foldTurnOpeningInput(message) : undefined;
+        pushMarker(markerKey, { text: opening?.text ?? textOf(message), origin: message.origin });
+        if (opening !== undefined) {
+          startTurn(mapOrigin(message), opening.text, opening.attachmentIds);
         }
         continue;
       }
@@ -216,10 +251,12 @@ export function groupMessagesIntoSnapshot(
           });
         });
         const callerMessage = { ...message, content: parts.slice(bundled.length) };
-        startTurn(mapOrigin(message), textOf(callerMessage), collectAttachments(callerMessage));
+        const opening = foldTurnOpeningInput(callerMessage);
+        startTurn(mapOrigin(message), opening.text, opening.attachmentIds);
         continue;
       }
-      startTurn(mapOrigin(message), textOf(message), collectAttachments(message));
+      const opening = foldTurnOpeningInput(message);
+      startTurn(mapOrigin(message), opening.text, opening.attachmentIds);
       continue;
     }
 
diff --git a/packages/transcript/src/index.ts b/packages/transcript/src/index.ts
index 70f8bc7abed..1ae1ae01164 100644
--- a/packages/transcript/src/index.ts
+++ b/packages/transcript/src/index.ts
@@ -21,3 +21,4 @@ export * from './history/groupTurns';
 export * from './history/foldFacts';
 export * from './contract/schema';
 export * from './contract/events';
+export * from './contract/mediaRef';
diff --git a/packages/transcript/src/model/attachment.ts b/packages/transcript/src/model/attachment.ts
index 4cfbfdd480d..d0a05e773a9 100644
--- a/packages/transcript/src/model/attachment.ts
+++ b/packages/transcript/src/model/attachment.ts
@@ -14,13 +14,15 @@
 import type { AttachmentId } from './ids';
 
 /**
- * Where the frontend fetches the bytes. Mirrors the engine's media source
- * kinds minus `base64` — inline data is deliberately dropped rather than
- * shipped over the transcript API.
+ * Where the frontend fetches the bytes. `file` addresses the process-global
+ * upload store; `session_media` addresses canonical media owned by the
+ * transcript's session. Inline base64 data is deliberately dropped rather
+ * than shipped over the transcript API.
  */
 export type AttachmentSource =
   | { readonly kind: 'url'; readonly url: string }
-  | { readonly kind: 'file'; readonly fileId: string };
+  | { readonly kind: 'file'; readonly fileId: string }
+  | { readonly kind: 'session_media'; readonly fileId: string };
 
 export interface TranscriptAttachment {
   readonly attachmentId: AttachmentId;
diff --git a/packages/transcript/test/layers.test.ts b/packages/transcript/test/layers.test.ts
index 5726401c4a5..84ed47fdb73 100644
--- a/packages/transcript/test/layers.test.ts
+++ b/packages/transcript/test/layers.test.ts
@@ -4,7 +4,7 @@ import { filterOpsForGrade, isAppendOnly, redactSnapshotForGrade } from '#/granu
 import { detachGrades, gradeFor, needsResetOnTransition } from '#/granularity/grade';
 import { paginateTurns } from '#/pagination/paginate';
 import { ViewRegistry } from '#/view/registry';
-import { groupMessagesIntoSnapshot } from '#/history/groupTurns';
+import { groupMessagesIntoSnapshot, type HistoryContentPart } from '#/history/groupTurns';
 import { foldWireRecordFacts, type HistoryWireRecord } from '#/history/foldFacts';
 import {
   transcriptOperationSchema,
@@ -410,6 +410,12 @@ describe('contract schemas', () => {
 });
 
 describe('groupMessagesIntoSnapshot (cold path)', () => {
+  // Single-user-message shell shared by the media ref projection tests below.
+  const snapshotOf = (...parts: HistoryContentPart[]): AgentTranscriptSnapshot =>
+    groupMessagesIntoSnapshot([
+      { role: 'user', content: parts, toolCalls: [], origin: { kind: 'user' } },
+    ]);
+
   it('groups flat messages into turns with folded tool results', () => {
     const snapshot = groupMessagesIntoSnapshot([
       { role: 'system', content: [{ type: 'text', text: 'sys' }] },
@@ -524,6 +530,167 @@ describe('groupMessagesIntoSnapshot (cold path)', () => {
     expect(firstTurn.attachmentIds).toEqual(['att_1', 'att_2', 'att_3']);
   });
 
+  it('maps persisted kimi-file media refs to attachments', () => {
+    // The engine persists an uploaded medium as a self-contained kosong
+    // `image_url` / `video_url` part carrying a `kimi-file://<fileId>` ref:
+    // the part type gives the kind and the ref the file id. A legacy `?path=`
+    // query is tolerated and ignored.
+    const snapshot = groupMessagesIntoSnapshot([
+      {
+        role: 'user',
+        content: [
+          {
+            type: 'video_url',
+            videoUrl: { url: 'kimi-file://file_1' },
+          } as HistoryContentPart,
+        ],
+        toolCalls: [],
+        origin: { kind: 'user' },
+      },
+      {
+        role: 'user',
+        content: [
+          { type: 'text', text: 'what is this?' },
+          {
+            type: 'image_url',
+            imageUrl: { url: 'kimi-file://file_2?path=%2Fcache%2Fshot.png' },
+          } as HistoryContentPart,
+        ],
+        toolCalls: [],
+        origin: { kind: 'user' },
+      },
+    ]);
+
+    expect(snapshot.attachments).toEqual([
+      {
+        attachmentId: 'att_1',
+        mediaType: 'video/*',
+        source: { kind: 'session_media', fileId: 'file_1' },
+      },
+      {
+        attachmentId: 'att_2',
+        mediaType: 'image/*',
+        source: { kind: 'session_media', fileId: 'file_2' },
+      },
+    ]);
+    const videoTurn = snapshot.items[0];
+    const imageTurn = snapshot.items[1];
+    if (videoTurn?.kind !== 'turn' || imageTurn?.kind !== 'turn') {
+      throw new Error('expected turns');
+    }
+    expect(videoTurn.attachmentIds).toEqual(['att_1']);
+    expect(imageTurn.attachmentIds).toEqual(['att_2']);
+    expect(videoTurn.prompt).toBe('');
+    expect(imageTurn.prompt).toBe('what is this?');
+  });
+
+  it('projects a daemon ref in a user-slash turn-opening input like a plain user turn', () => {
+    // A user-slash skill command carrying an uploaded image persists the same
+    // self-contained daemon-ref part; the cold rebuild projects it exactly
+    // like a plain user turn (one attachment on the turn), mirroring the live
+    // `projectTurnPrompt` projection.
+    const snapshot = groupMessagesIntoSnapshot([
+      {
+        role: 'user',
+        content: [
+          { type: 'text', text: '/gen-docs ' },
+          {
+            type: 'image_url',
+            imageUrl: { url: 'kimi-file://file_4?path=%2Fcache%2Fshot.png' },
+          } as HistoryContentPart,
+        ],
+        toolCalls: [],
+        origin: { kind: 'skill_activation', trigger: 'user-slash', skillName: 'gen-docs' } as {
+          kind: string;
+        },
+      },
+    ]);
+
+    expect(snapshot.attachments).toEqual([
+      {
+        attachmentId: 'att_1',
+        mediaType: 'image/*',
+        source: { kind: 'session_media', fileId: 'file_4' },
+      },
+    ]);
+    expect(snapshot.items.map((item) => item.kind)).toEqual(['marker', 'turn']);
+    const marker = snapshot.items[0];
+    if (marker?.kind !== 'marker') throw new Error('expected marker');
+    expect((marker.payload as { text: string }).text).toBe('/gen-docs ');
+    const turn = snapshot.items[1];
+    if (turn?.kind !== 'turn') throw new Error('expected turn');
+    expect(turn.prompt).toBe('/gen-docs ');
+    expect(turn.attachmentIds).toEqual(['att_1']);
+  });
+
+  it('keeps a kimi-file ref as a nameless attachment and inline tags as user text', () => {
+    const snapshot = snapshotOf(
+      { type: 'text', text: 'open <image path="/tmp/other.png"></image> please' },
+      {
+        type: 'image_url',
+        imageUrl: { url: 'kimi-file://file_3' },
+      } as HistoryContentPart,
+    );
+
+    // The ref carries no display name; the inline tag inside real user text
+    // stays verbatim (never stripped).
+    expect(snapshot.attachments).toEqual([
+      {
+        attachmentId: 'att_1',
+        mediaType: 'image/*',
+        source: { kind: 'session_media', fileId: 'file_3' },
+      },
+    ]);
+    const turn = snapshot.items[0];
+    if (turn?.kind !== 'turn') throw new Error('expected turn');
+    expect(turn.attachmentIds).toEqual(['att_1']);
+    expect(turn.prompt).toBe('open <image path="/tmp/other.png"></image> please');
+  });
+
+  it('keeps a legacy tag+ref pair as prompt text plus the ref-derived attachment', () => {
+    // Legacy sessions persist an upload as the pair `<media path>` tag text
+    // part + daemon-ref media part. Tolerated, not folded: the tag stays
+    // user-visible text and the self-contained ref projects on its own.
+    const snapshot = snapshotOf(
+      { type: 'text', text: '<image path="/cache/shot.png"></image>' },
+      {
+        type: 'image_url',
+        imageUrl: { url: 'kimi-file://file_5?path=%2Fcache%2Fshot.png' },
+      } as HistoryContentPart,
+    );
+
+    expect(snapshot.attachments).toEqual([
+      {
+        attachmentId: 'att_1',
+        mediaType: 'image/*',
+        source: { kind: 'session_media', fileId: 'file_5' },
+      },
+    ]);
+    const turn = snapshot.items[0];
+    if (turn?.kind !== 'turn') throw new Error('expected turn');
+    expect(turn.prompt).toBe('<image path="/cache/shot.png"></image>');
+    expect(turn.attachmentIds).toEqual(['att_1']);
+  });
+
+  it('keeps standalone <media path> tags as prompt text', () => {
+    // The no-closing-tag and extra-attribute forms both exist in persisted
+    // sessions. A standalone tag is user-visible text (or the legacy degrade
+    // form), not markup the read model may eat.
+    const snapshot = snapshotOf(
+      { type: 'text', text: '<image path="/cache/shot.png">' },
+      { type: 'text', text: '<image path="/cache/shot.png" content_type="image/png"></image>' },
+      { type: 'text', text: '<video path="/cache/clip.mp4">' },
+    );
+
+    const turn = snapshot.items[0];
+    if (turn?.kind !== 'turn') throw new Error('expected turn');
+    expect(turn.prompt).toBe(
+      '<image path="/cache/shot.png"><image path="/cache/shot.png" content_type="image/png"></image><video path="/cache/clip.mp4">',
+    );
+    expect(turn.attachmentIds).toBeUndefined();
+    expect(snapshot.attachments).toEqual([]);
+  });
+
   it('keeps cold tool calls running until a result is persisted', () => {
     const pending = groupMessagesIntoSnapshot([
       { role: 'user', content: [{ type: 'text', text: 'run it' }], toolCalls: [], origin: { kind: 'user' } },