diff --git a/.changeset/clean-staged-media.md b/.changeset/clean-staged-media.md
new file mode 100644
index 0000000000..d6857e0d65
--- /dev/null
+++ b/.changeset/clean-staged-media.md
@@ -0,0 +1,6 @@
+---
+"@moonshot-ai/kimi-code": patch
+"@moonshot-ai/kimi-code-sdk": patch
+---
+
+Clean up staged image and video uploads across prompt submission, cancellation, and queue cleanup paths, with daemon-side expiry and deletion support.
diff --git a/.changeset/sdk-prompt-id.md b/.changeset/sdk-prompt-id.md
new file mode 100644
index 0000000000..701129802c
--- /dev/null
+++ b/.changeset/sdk-prompt-id.md
@@ -0,0 +1,5 @@
+---
+"@moonshot-ai/kimi-code-sdk": patch
+---
+
+Add an optional `promptId` to session prompt submissions, echoed back on the turn-started event so callers can correlate a submission with the turn it opens. Requires the v2 harness.
diff --git a/.changeset/sdk-upload-file.md b/.changeset/sdk-upload-file.md
new file mode 100644
index 0000000000..aa81bf54f4
--- /dev/null
+++ b/.changeset/sdk-upload-file.md
@@ -0,0 +1,5 @@
+---
+"@moonshot-ai/kimi-code-sdk": minor
+---
+
+Add `uploadFile` to the harness plus daemon file-reference helpers, so SDK consumers can upload media to the engine's file store and reference it by path in prompts. Requires 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 51958dbe96..9c7b8f6002 100644
--- a/apps/kimi-code/src/tui/components/editor/custom-editor.ts
+++ b/apps/kimi-code/src/tui/components/editor/custom-editor.ts
@@ -154,13 +154,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();
 
   setArgumentHints(hints: ReadonlyMap<string, string>): void {
@@ -325,6 +328,15 @@ 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
+    // (placeholder insert + compression + daemon upload), so Enter cannot
+    // submit a half-built draft.
+    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)) {
@@ -368,17 +380,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;
       }
     }
@@ -503,6 +519,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/controllers/cache-hint-controller.ts b/apps/kimi-code/src/tui/controllers/cache-hint-controller.ts
index 4a1aa4626c..d8104febe8 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 } 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;
 }
 
 export interface CacheHintHost {
@@ -253,7 +258,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 };
+    const stash: StashedSubmit = { text, extraction, sessionId: host.session.id };
     const cached = peekCacheHintConfig();
     if (cached !== undefined) {
       const decision = evaluateCacheHint({
@@ -342,7 +347,11 @@ export class CacheHintController {
   private async releaseStashed(stash: StashedSubmit): Promise<void> {
     this.releasingStashed = true;
     try {
-      await this.host.sendNormalUserInput(stash.text, stash.extraction);
+      const extraction =
+        stash.extraction !== undefined && this.host.state.appState.sessionId !== stash.sessionId
+          ? makeExtractionResendable(stash.extraction)
+          : stash.extraction;
+      await this.host.sendNormalUserInput(stash.text, extraction);
     } finally {
       this.releasingStashed = false;
     }
@@ -470,7 +479,7 @@ export class CacheHintController {
         break;
     }
     this.lastDialogRestored = false;
-    if (stashed !== undefined) await host.sendNormalUserInput(stashed.text, stashed.extraction);
+    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 55df80609b..9eebe4348f 100644
--- a/apps/kimi-code/src/tui/controllers/editor-keyboard.ts
+++ b/apps/kimi-code/src/tui/controllers/editor-keyboard.ts
@@ -1,3 +1,5 @@
+import { unlink } from 'node:fs/promises';
+
 import type { KimiHarness, Session } from '@moonshot-ai/kimi-code-sdk';
 import { compressImageForModel, persistOriginalImage, sessionMediaOriginalsDir } from '@moonshot-ai/kimi-code-sdk';
 
@@ -14,8 +16,8 @@ import {
   NO_ACTIVE_SESSION_MESSAGE,
 } from '../constant/kimi-tui';
 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 type { PendingExit, QueuedMessage, SteerInputItem } from '../types';
 import type { TUIState } from '../tui-state';
 import type { BtwPanelController } from './btw-panel';
@@ -23,6 +25,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;
   /**
@@ -40,6 +47,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;
@@ -280,7 +288,12 @@ export class EditorKeyboardController {
         if (trimmed.length > 0) {
           // Queued items carry the parts extracted when they were submitted
           // (and were already capability-validated then).
-          items.push({ text: trimmed, parts: m.parts, imageAttachmentIds: m.imageAttachmentIds });
+          items.push({
+            text: trimmed,
+            parts: m.parts,
+            imageAttachmentIds: m.imageAttachmentIds,
+            stagingPaths: m.stagingPaths,
+          });
         }
       }
       let editorExtraction: ReturnType<typeof extractMediaAttachments> | undefined;
@@ -300,6 +313,7 @@ export class EditorKeyboardController {
             editorExtraction.imageAttachmentIds.length > 0
               ? editorExtraction.imageAttachmentIds
               : undefined,
+          stagingPaths: editorExtraction.stagingPaths,
         });
       }
 
@@ -311,16 +325,24 @@ export class EditorKeyboardController {
           editorExtraction !== undefined &&
           !host.validateMediaCapabilities(editorExtraction)
         ) {
+          host.releaseStagingMedia(
+            editorExtraction.imageAttachmentIds,
+            editorExtraction.stagingPaths,
+          );
           return;
         }
-        host.state.queuedMessages = queued.filter((m) => m.mode === 'bash');
-        if (!editorIsBash) editor.setText('');
         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);
-        } else {
-          host.steerMessage(session, items);
+          return;
         }
+        host.state.queuedMessages = queued.filter((m) => m.mode === 'bash');
+        if (!editorIsBash) editor.setText('');
+        host.steerMessage(session, items);
       }
       host.updateQueueDisplay();
       host.state.ui.requestRender();
@@ -459,6 +481,44 @@ export class EditorKeyboardController {
 
     const meta = parseImageMeta(media.bytes);
     if (meta === null) return false;
+
+    // Register the attachment and put its placeholder in the editor before
+    // doing any of the asynchronous ingestion work below. CustomEditor holds
+    // subsequent keystrokes while this handler is in flight, so Enter cannot
+    // submit a draft that is still missing the pasted image.
+    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' });
+
+    try {
+      await this.finishClipboardImagePaste(
+        attachment,
+        media.bytes,
+        meta.mime,
+        meta.width,
+        meta.height,
+      );
+    } catch (error) {
+      // 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
@@ -470,7 +530,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: {
@@ -485,34 +545,68 @@ 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 fileId = 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,
+    });
+    if (completed === undefined && fileId !== undefined) {
+      await this.host.harness?.deleteFile(fileId).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). Best effort: any failure returns undefined,
+   * so the attachment keeps no `fileId` and submit-time expansion falls back
+   * to the inline base64 form — the paste never blocks on the upload.
+   */
+  private async uploadImageToDaemonFileStore(
+    bytes: Uint8Array,
+    mime: string,
+  ): Promise<string | undefined> {
+    if (this.host.engineV2 !== true) 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: 60 * 60,
+      });
+      return meta.id;
+    } catch {
+      return undefined;
+    }
   }
 
   private async openExternalEditor(): Promise<void> {
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 0eff25feb1..3286bcab6d 100644
--- a/apps/kimi-code/src/tui/controllers/session-event-handler.ts
+++ b/apps/kimi-code/src/tui/controllers/session-event-handler.ts
@@ -118,6 +118,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;
 }
@@ -316,6 +318,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);
@@ -353,6 +356,7 @@ export class SessionEventHandler {
   }
 
   private handleTurnEnd(event: TurnEndedEvent, sendQueued: (item: QueuedMessage) => void): void {
+    this.host.handleTurnEnded?.(event);
     this.host.streamingUI.flushNow();
     if (event.reason === 'cancelled') {
       this.markActiveAgentSwarmsCancelled();
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 0000000000..8fceadbc81
--- /dev/null
+++ b/apps/kimi-code/src/tui/controllers/staging-leases.ts
@@ -0,0 +1,262 @@
+/**
+ * `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.
+ *
+ * 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[];
+  /** 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 {
+    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);
+  }
+
+  /** 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[] {
+    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 7c118e57a3..6a18f5815d 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';
@@ -115,6 +119,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 } from './controllers/staging-leases';
 import { StreamingUIController } from './controllers/streaming-ui';
 import { TasksBrowserController } from './controllers/tasks-browser';
 import { installRainbowDance } from './easter-eggs/dance';
@@ -148,6 +153,7 @@ import { ImageAttachmentStore, type ImageAttachment } from './utils/image-attach
 import { extractMediaAttachments, rewriteMediaPlaceholders } 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_TURN_LIMIT } from './utils/message-replay';
 import { hasPatchChanges } from './utils/object-patch';
@@ -261,53 +267,10 @@ 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 });
-}
-
 /** How long the one-shot "moved to background" footer hint stays visible. */
 const DETACH_HINT_DISPLAY_MS = 4_000;
 
@@ -318,6 +281,8 @@ export class KimiTUI {
   state: TUIState;
   /** In-flight lazy session creation (v2 engine), shared by concurrent first-use triggers. */
   private ensureSessionPromise: Promise<Session | undefined> | null = null;
+  /** Staged prompt media lifecycle (daemon uploads + cache copies) — see StagingLeaseTracker. */
+  private readonly staging: StagingLeaseTracker;
   private readonly cacheHint = new CacheHintController(this);
   private readonly approvalController = new ApprovalController();
   private readonly questionController = new QuestionController();
@@ -342,7 +307,7 @@ export class KimiTUI {
   private backgroundRefreshPromise: Promise<void> | undefined;
   private readonly migrationPlan: MigrationPlan | null;
   private readonly migrateOnly: boolean;
-  /** Whether the harness runs on the agent-core-v2 engine (lazy session creation). */
+  /** agent-core-v2 engine flag (startup-selected); read by controllers via host interfaces. */
   readonly engineV2: boolean;
   private startupNotice: string | undefined;
   private lastActivityMode: string | undefined;
@@ -400,6 +365,18 @@ export class KimiTUI {
 
   constructor(harness: KimiHarness, startupInput: KimiTUIStartupInput) {
     this.harness = harness;
+    this.staging = new StagingLeaseTracker({
+      takeFileIds: (ids) => this.imageStore.takeFileIds(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: {
@@ -958,6 +935,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();
@@ -1236,11 +1217,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);
@@ -1270,7 +1252,10 @@ export class KimiTUI {
       this.showError(`Failed to prepare media attachment: ${formatErrorMessage(error)}`);
       return;
     }
-    if (!this.validateMediaCapabilities(extraction)) return;
+    if (!this.validateMediaCapabilities(extraction)) {
+      this.releaseStagingMedia(extraction.imageAttachmentIds, extraction.stagingPaths);
+      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.
@@ -1279,16 +1264,21 @@ export class KimiTUI {
     if (session === undefined) {
       if (!this.engineV2) {
         this.showError(LLM_NOT_SET_MESSAGE);
+        this.releaseStagingMedia(extraction.imageAttachmentIds, extraction.stagingPaths);
         return;
       }
       session = await this.ensureSession();
-      if (session === undefined) return;
+      if (session === undefined) {
+        this.releaseStagingMedia(extraction.imageAttachmentIds, extraction.stagingPaths);
+        return;
+      }
     }
     if (extraction.hasMedia) {
       this.sendMessage(session, text, {
         hasMedia: true,
         parts: extraction.parts,
         imageAttachmentIds: extraction.imageAttachmentIds,
+        stagingPaths: extraction.stagingPaths,
       });
     } else {
       this.sendMessage(session, text);
@@ -1301,10 +1291,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.');
@@ -1358,6 +1349,7 @@ 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);
+    this.staging.releaseQueued([last]);
     return last;
   }
 
@@ -1378,6 +1370,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,
     });
     this.track('input_queue');
@@ -1409,6 +1405,7 @@ export class KimiTUI {
 
   sendQueuedMessage(session: Session, item: QueuedMessage): void {
     if (item.mode === 'bash') {
+      this.staging.releaseQueued([item]);
       void this.runShellCommandFromInput(item.text);
       return;
     }
@@ -1416,10 +1413,23 @@ export class KimiTUI {
       this.sendMessageInternal(session, item.text, {
         parts: item.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();
   }
@@ -1437,29 +1447,53 @@ 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';
+    // A plain prompt submission carrying staged media gets a client-chosen
+    // prompt id: 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 submissionId =
+      !goalActive && (imageAttachmentIds !== undefined || (options?.stagingPaths?.length ?? 0) > 0)
+        ? randomUUID()
+        : undefined;
+    const stagingLease = this.staging.create(
+      imageAttachmentIds ?? [],
+      options?.stagingPaths ?? [],
+      'user',
+      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)}`);
     });
   }
 
@@ -1477,12 +1511,23 @@ export class KimiTUI {
       this.showError(`Failed to prepare media attachment: ${formatErrorMessage(error)}`);
       return;
     }
-    if (!this.validateMediaCapabilities(rewrite)) return;
+    if (!this.validateMediaCapabilities(rewrite)) {
+      this.releaseStagingMedia(rewrite.imageAttachmentIds, rewrite.stagingPaths);
+      return;
+    }
     this.beginSessionRequest();
-    void session.activateSkill(skillName, rewrite.text).catch((error: unknown) => {
-      const message = formatErrorMessage(error);
-      this.failSessionRequest(`Skill "${skillName}" failed: ${message}`);
-    });
+    const stagingLease = this.staging.create(
+      rewrite.imageAttachmentIds,
+      rewrite.stagingPaths,
+      'skill_activation',
+    );
+    this.staging.trackDispatch(
+      stagingLease,
+      session.activateSkill(skillName, rewrite.text),
+      (error) => {
+        this.failSessionRequest(`Skill "${skillName}" failed: ${formatErrorMessage(error)}`);
+      },
+    );
   }
 
   activatePluginCommand(
@@ -1501,14 +1546,25 @@ export class KimiTUI {
       this.showError(`Failed to prepare media attachment: ${formatErrorMessage(error)}`);
       return;
     }
-    if (!this.validateMediaCapabilities(rewrite)) return;
+    if (!this.validateMediaCapabilities(rewrite)) {
+      this.releaseStagingMedia(rewrite.imageAttachmentIds, rewrite.stagingPaths);
+      return;
+    }
     this.beginSessionRequest();
-    void session
-      .activatePluginCommand(pluginId, commandName, rewrite.text)
-      .catch((error: unknown) => {
-        const message = formatErrorMessage(error);
-        this.failSessionRequest(`Command "${pluginId}:${commandName}" failed: ${message}`);
-      });
+    const stagingLease = this.staging.create(
+      rewrite.imageAttachmentIds,
+      rewrite.stagingPaths,
+      'plugin_command',
+    );
+    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 {
@@ -1551,9 +1607,13 @@ export class KimiTUI {
       });
     }
 
-    void session.steer(combineSteerInput(input)).catch((error: unknown) => {
-      const message = formatErrorMessage(error);
-      this.showError(`Failed to steer: ${message}`);
+    const imageAttachmentIds = input.flatMap((item) => 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)}`);
     });
   }
 
@@ -1566,7 +1626,9 @@ export class KimiTUI {
   }
 
   clearQueuedMessages(): void {
+    const queued = this.state.queuedMessages;
     this.state.queuedMessages = [];
+    this.staging.releaseQueued(queued);
   }
 
   shiftQueuedMessage(): QueuedMessage | undefined {
@@ -1851,6 +1913,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);
@@ -1919,6 +1985,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 {
@@ -1986,7 +2053,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();
@@ -2337,7 +2404,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
@@ -2388,7 +2456,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 d423aec705..59e0a732f6 100644
--- a/apps/kimi-code/src/tui/types.ts
+++ b/apps/kimi-code/src/tui/types.ts
@@ -235,6 +235,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;
    *  undefined (=`prompt`) for a normal message. */
   readonly mode?: 'prompt' | 'bash';
@@ -250,6 +251,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 9531efa104..221ac731fd 100644
--- a/apps/kimi-code/src/tui/utils/export-markdown.ts
+++ b/apps/kimi-code/src/tui/utils/export-markdown.ts
@@ -1,3 +1,4 @@
+import { foldMediaPathTagRefs } from '@moonshot-ai/kimi-code-sdk';
 import type { ContentPart, ContextMessage, PromptOrigin, ToolCall } from '@moonshot-ai/kimi-code-sdk';
 
 const HINT_KEYS = ['path', 'file_path', 'command', 'query', 'url', 'name', 'pattern'] as const;
@@ -139,7 +140,11 @@ function formatTurnMd(messages: readonly ContextMessage[], turnNumber: number):
 
     if (msg.role === 'user') {
       lines.push('### User', '');
-      for (const part of msg.content) {
+      // Fold the upload pair (`<media path>` tag + daemon-ref media part): a
+      // claimed tag is machine markup carrying the materialization path and
+      // must not leak into the exported document; the media part itself
+      // renders as `[image]`/`[video]` below.
+      for (const part of foldMediaPathTagRefs(msg.content).parts) {
         const text = formatContentPartMd(part);
         if (text.trim()) {
           lines.push(text, '');
@@ -188,8 +193,8 @@ function buildOverview(
   let topic = '';
   for (const msg of history) {
     if (msg.role === 'user' && !isInternalMessage(msg)) {
-      const textParts = msg.content
-        .filter((p): p is { type: 'text'; text: string } => p.type === 'text')
+      const textParts = foldMediaPathTagRefs(msg.content)
+        .parts.filter((p): p is { type: 'text'; text: string } => p.type === 'text')
         .map((p) => p.text);
       topic = shorten(textParts.join(' '), 80);
       break;
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 8d653159a2..b998d8fbc9 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,13 @@ 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;
   /** Rendered placeholder string, e.g. `[image #1 (640×480)]`. */
   readonly placeholder: string;
 }
@@ -59,9 +66,14 @@ export interface VideoAttachment {
 
 export type MediaAttachment = ImageAttachment | VideoAttachment;
 
+type MutableImageAttachment = {
+  -readonly [Property in keyof ImageAttachment]: ImageAttachment[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 +81,7 @@ export class ImageAttachmentStore {
     width: number,
     height: number,
     original?: ImageAttachmentOriginal,
+    fileId?: string,
   ): ImageAttachment {
     const id = this.nextId;
     this.nextId += 1;
@@ -80,6 +93,7 @@ export class ImageAttachmentStore {
       width,
       height,
       original,
+      fileId,
       placeholder: formatPlaceholder(id, width, height),
     };
     this.byId.set(id, attachment);
@@ -106,26 +120,104 @@ 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;
+    },
+  ): 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.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;
+    }
+    return fileIds;
+  }
+
+  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 87d53eabc2..947961806f 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 authors the paired
+ *     `<image path>` tag, then resolves the reference at request time;
+ *     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,12 +35,16 @@
  */
 
 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';
 
@@ -58,6 +68,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 +95,108 @@ export function extractMediaAttachments(
   const parts: PromptPart[] = [];
   const imageAttachmentIds: number[] = [];
   const videoAttachmentIds: number[] = [];
+  const imageSnapshots: ImageResendSnapshot[] = [];
+  const stagingPaths: string[] = [];
   let cursor = 0;
   let hasMedia = false;
 
-  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);
-      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));
+  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 authors the
+          // paired `<image path>` tag, 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);
       }
-      parts.push(imagePartForAttachment(attachment));
-      imageAttachmentIds.push(id);
+      hasMedia = true;
+      cursor = match.index + literal.length;
     }
-    hasMedia = true;
-    cursor = match.index + literal.length;
+    const tail = text.slice(cursor);
+    pushText(parts, tail);
+
+    store.retainFileIds(imageAttachmentIds);
+    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,
+      imageSnapshots,
+      stagingPaths,
+    };
+  } catch (error) {
+    cleanupStagingPaths(stagingPaths);
+    throw error;
   }
-  const tail = text.slice(cursor);
-  pushText(parts, tail);
+}
+
+/**
+ * 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 +206,7 @@ export interface MediaTagRewriteResult {
   hasMedia: boolean;
   imageAttachmentIds: number[];
   videoAttachmentIds: number[];
+  stagingPaths: string[];
 }
 
 /**
@@ -152,39 +238,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 +354,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 +393,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 +402,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 f04edeb292..14bc4eba8e 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 c068ac1068..aa5248dc1e 100644
--- a/apps/kimi-code/src/tui/utils/message-replay.ts
+++ b/apps/kimi-code/src/tui/utils/message-replay.ts
@@ -8,7 +8,10 @@ import type {
   ResumedAgentState,
   ToolCall,
 } from '@moonshot-ai/kimi-code-sdk';
-import { limitAgentReplayByTurns } from '@moonshot-ai/kimi-code-sdk';
+import {
+  foldMediaPathTagRefs,
+  limitAgentReplayByTurns,
+} from '@moonshot-ai/kimi-code-sdk';
 
 import type {
   AppState,
@@ -218,7 +221,11 @@ export function toolResultOutput(content: readonly ContentPart[]): string {
 }
 
 export function contentPartsToText(content: readonly ContentPart[]): string {
-  return content.map(contentPartToText).join('');
+  // Fold the upload pair (`<media path>` tag + daemon-ref media part): a
+  // claimed tag is machine markup carrying the materialization path, and the
+  // ref renders as a bare `[image]`/`[video]` placeholder downstream — neither
+  // the path nor the internal `kimi-file://` url may surface as user text.
+  return foldMediaPathTagRefs(content).parts.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 0000000000..9e14df8bae
--- /dev/null
+++ b/apps/kimi-code/src/tui/utils/steer-input.ts
@@ -0,0 +1,69 @@
+/**
+ * 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). Standalone `<media path>` tags (machine markup paired with the
+ * adjacent daemon-ref media part) keep their own parts so the engine-side
+ * pairing survives the merge.
+ */
+
+import { matchSingleMediaPathTag } from '@moonshot-ai/kimi-code-sdk';
+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). An item whose
+ * FIRST part is a standalone `<media path>` tag counts as media for this:
+ * the tag stays atomic (never merges with the separator), so a separator
+ * inserted before it would strand exactly that illegal whitespace-only
+ * text part between the previous media part and the tag.
+ */
+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' || matchSingleMediaPathTag(first.text) !== undefined);
+    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;
+        }
+        // A standalone `<media path>` tag is machine markup paired with the
+        // adjacent daemon-ref media part; merging it into neighboring text
+        // would break the pairing (the engine fold only claims standalone
+        // tags), so it keeps its own part.
+        if (matchSingleMediaPathTag(part.text) !== undefined) parts.push(part);
+        else 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 f66c92e7d6..be29c77ced 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 99834d9d9a..ffb811e291 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);
@@ -80,6 +81,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);
@@ -361,6 +380,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 b87b2d4d59..1481af9a0f 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
+ *     and the attachment carries the returned `fileId`; an upload failure
+ *     leaves the paste on the inline base64 fallback
  */
 
 import { mkdtemp, readFile, rm, unlink } from 'node:fs/promises';
@@ -42,7 +45,17 @@ interface PasteHarness {
   pasteImage(): Promise<void>;
 }
 
-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,14 +74,16 @@ 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;
   }
 
@@ -98,6 +113,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 }));
+}
+
 /**
  * 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 +319,82 @@ describe('clipboard image paste compression', () => {
     expect(props['source']).toBe('tui_paste');
     expect(props['outcome']).toBe('compressed');
   });
+
+  it('uploads the final bytes to the daemon file store on the v2 engine', 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(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();
+  });
 });
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 0000000000..e1125210b0
--- /dev/null
+++ b/apps/kimi-code/test/tui/controllers/staging-leases.test.ts
@@ -0,0 +1,299 @@
+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[]>>;
+  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 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, deleteFiles, warn }, takeFileIds, 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();
+    });
+  });
+
+  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('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 05a6eb8adc..b1b04236be 100644
--- a/apps/kimi-code/test/tui/export-markdown.test.ts
+++ b/apps/kimi-code/test/tui/export-markdown.test.ts
@@ -316,6 +316,56 @@ describe('buildExportMarkdown', () => {
     expect(md).toContain('deep thought');
   });
 
+  it('folds an upload tag+ref pair out of the exported user message', () => {
+    // An uploaded image persists as `<image path>` tag text + a `kimi-file://`
+    // image part; the claimed tag is machine markup carrying the
+    // materialization path — the export keeps the real text and `[image]`,
+    // never the path or the internal url.
+    const msgs: ContextMessage[] = [
+      {
+        role: 'user',
+        content: [
+          { 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' },
+          },
+        ],
+        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 6add1e428e..96736c933a 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,27 @@ 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();
+  });
 });
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 85755641c6..edd053cd87 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,17 @@
-import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+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,
   rewriteMediaPlaceholders,
 } from '#/tui/utils/image-placeholder';
 import { getCacheDir } from '#/utils/paths';
@@ -229,6 +232,126 @@ 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 authors the paired tag.
+      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('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', () => {
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 dc2a4deb29..7d22edf9c5 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';
@@ -118,6 +119,9 @@ interface MessageDriver {
   handleUserInput(text: string): void;
   persistInputHistory(text: string): Promise<void>;
   sendQueuedMessage(session: unknown, item: QueuedMessage): void;
+  clearQueuedMessages(): void;
+  closeSession(reason: string): Promise<void>;
+  setSession(session: unknown): Promise<void>;
   getCurrentSessionId(): string;
 }
 
@@ -285,6 +289,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(),
@@ -427,6 +432,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);
@@ -498,7 +535,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({
@@ -661,7 +698,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);
@@ -713,7 +750,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();
@@ -796,7 +833,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();
@@ -822,7 +859,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' }),
@@ -857,7 +894,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 }),
@@ -876,7 +913,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 }),
@@ -900,7 +937,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();
@@ -957,7 +994,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.
@@ -1247,7 +1284,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.
@@ -1296,7 +1333,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' }),
@@ -2084,7 +2121,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');
@@ -2478,42 +2515,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';
 
@@ -2526,12 +2593,12 @@ 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);
+    });
   });
 
 
@@ -2542,10 +2609,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',
@@ -2555,6 +2627,132 @@ 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('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';
@@ -2648,7 +2846,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();
   });
@@ -2831,10 +3029,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 () => {
@@ -2884,6 +3087,33 @@ 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('steers consecutive image-only messages without a whitespace-only separator part', async () => {
     const session = makeSession();
     const { driver } = await makeDriver(session);
@@ -4190,7 +4420,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 79c73b9f9a..c13ae01031 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 be5446a08e..37951fa394 100644
--- a/apps/kimi-code/test/tui/message-replay.test.ts
+++ b/apps/kimi-code/test/tui/message-replay.test.ts
@@ -320,6 +320,34 @@ describe('KimiTUI resume message replay', () => {
     expect(transcript).not.toContain('Goal complete');
   });
 
+  it('folds an upload tag+ref pair out of the replayed user message', async () => {
+    // An uploaded image persists as `<image path>` tag text + a `kimi-file://`
+    // image part; on replay the claimed tag is machine markup (carrying the
+    // materialization path) and the ref renders as a bare `[image]`
+    // placeholder — neither the path nor the internal url may surface.
+    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).not.toContain('/Users/alice');
+    expect(transcript).not.toContain('kimi-file');
+    expect(transcript).not.toContain('<image path=');
+  });
+
   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 0000000000..96cc79e17b
--- /dev/null
+++ b/apps/kimi-code/test/tui/utils/steer-input.test.ts
@@ -0,0 +1,98 @@
+import { describe, expect, it } from 'vitest';
+
+import { foldMediaPathTagRefs } from '@moonshot-ai/kimi-code-sdk';
+
+import { combineSteerInput } from '#/tui/utils/steer-input';
+
+describe('combineSteerInput', () => {
+  const tag = '<image path="/cache/f_1.png"></image>';
+  const refPart = {
+    type: 'image_url',
+    imageUrl: { url: 'kimi-file://f_1?path=%2Fcache%2Ff_1.png' },
+  } as const;
+
+  it('keeps a standalone <media path> tag as its own part so the engine pairing survives', () => {
+    const result = combineSteerInput([
+      {
+        text: 'what is this?',
+        parts: [{ type: 'text', text: 'what is this? ' }, { type: 'text', text: tag }, refPart],
+      },
+    ]);
+    expect(result).toEqual([
+      { type: 'text', text: 'what is this? ' },
+      { type: 'text', text: tag },
+      refPart,
+    ]);
+    // The pair still folds: one claimed tag, one media ref.
+    const folded = foldMediaPathTagRefs(result as never);
+    expect(folded.media).toHaveLength(1);
+    expect(folded.parts).toHaveLength(2);
+  });
+
+  it('merges plain text across items without absorbing adjacent media tags', () => {
+    const result = combineSteerInput([
+      {
+        text: 'a',
+        parts: [
+          { type: 'text', text: 'a ' },
+          { type: 'text', text: '<image path="/cache/f_1.png"></image>' },
+          refPart,
+        ],
+      },
+      {
+        text: 'b',
+        parts: [
+          { type: 'text', text: 'b ' },
+          { type: 'text', text: '<image path="/cache/f_1.png"></image>' },
+          refPart,
+        ],
+      },
+    ]);
+    expect(result).toEqual([
+      { type: 'text', text: 'a ' },
+      { type: 'text', text: '<image path="/cache/f_1.png"></image>' },
+      refPart,
+      { type: 'text', text: '\n\nb ' },
+      { type: 'text', text: '<image path="/cache/f_1.png"></image>' },
+      refPart,
+    ]);
+  });
+
+  it('drops the separator between a trailing media part and a leading standalone tag', () => {
+    // Two queued pure-image messages: each item's parts open with the tag.
+    // Inserting '\n\n' there would strand a whitespace-only text part between
+    // the media part and the atomic tag, which `normalizePromptInput` rejects.
+    const tag2 = '<image path="/cache/f_2.png"></image>';
+    const refPart2 = {
+      type: 'image_url',
+      imageUrl: { url: 'kimi-file://f_2?path=%2Fcache%2Ff_2.png' },
+    } as const;
+    const result = combineSteerInput([
+      { text: '', parts: [{ type: 'text', text: tag }, refPart] },
+      { text: '', parts: [{ type: 'text', text: tag2 }, refPart2] },
+    ]);
+    expect(result).toEqual([{ type: 'text', text: tag }, refPart, { type: 'text', text: tag2 }, refPart2]);
+    // Both pairs still fold: two claimed tags, two media refs, no cross-claim.
+    const folded = foldMediaPathTagRefs(result as never);
+    expect(folded.media).toHaveLength(2);
+    expect(folded.parts).toHaveLength(2);
+  });
+
+  it('drops the separator when a media-ending item is followed by a tag-first item', () => {
+    const result = combineSteerInput([
+      { text: 'a', parts: [{ type: 'text', text: 'a ' }, { type: 'text', text: tag }, refPart] },
+      { text: '', parts: [{ type: 'text', text: tag }, refPart] },
+    ]);
+    expect(result).toEqual([
+      { type: 'text', text: 'a ' },
+      { type: 'text', text: tag },
+      refPart,
+      { type: 'text', text: tag },
+      refPart,
+    ]);
+  });
+
+  it('joins text-only items with the historical separator', () => {
+    expect(combineSteerInput([{ text: 'one' }, { text: 'two' }])).toBe('one\n\ntwo');
+  });
+});
diff --git a/packages/agent-core-v2/docs/state-manifest.d.ts b/packages/agent-core-v2/docs/state-manifest.d.ts
index 0dcbe84665..e50d12dc29 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
@@ -1093,9 +1093,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;
@@ -1122,6 +1120,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/profile/profileService.ts
diff --git a/packages/agent-core-v2/scripts/gen-contract-types.mjs b/packages/agent-core-v2/scripts/gen-contract-types.mjs
index 2cd8307b04..e215d7aa48 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 a6313013a1..7e1bb3e16d 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 92339a83df..f09a0ed78f 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.
@@ -43,7 +44,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';
@@ -171,7 +172,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,
@@ -356,7 +357,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 a6940a27b7..47034833bb 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';
@@ -453,11 +453,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)
+      : undefined;
     this.eventBus.publish({
       type: 'turn.started',
       turnId: job.turn.id,
       origin,
-      prompt: isDisplayablePromptOrigin(origin) ? turnPromptText(job.seed.input) : 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 f66490a5ee..fb7c438f6e 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 fed477dd99..fc0c957409 100644
--- a/packages/agent-core-v2/src/agent/loop/turnEvents.ts
+++ b/packages/agent-core-v2/src/agent/loop/turnEvents.ts
@@ -9,13 +9,22 @@
  * 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.
+ * which must never surface in transcripts. An upload's `<media path>` tag
+ * text part is machine markup paired with its daemon-ref media part
+ * (`foldMediaPathTagRefs`): the tag never reaches the prompt text, and the
+ * referenced media rides as {@link TurnStartedEvent.promptAttachments}.
+ * `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 { foldMediaPathTagRefs } from '#/agent/media/mediaRef';
 import type { TokenUsage } from '#/kosong/contract/usage';
 
 export type TurnEndReason = 'completed' | 'cancelled' | 'failed' | 'blocked';
@@ -28,19 +37,59 @@ export type TurnInterruptReason =
   | 'filtered'
   | 'blocked';
 
+/**
+ * One daemon-referenced upload carried by the turn-opening input. `name` is
+ * a display label (the paired tag path's basename) — never an absolute path,
+ * so the payload stays safe to forward onto client-facing event streams.
+ */
+export interface TurnPromptAttachment {
+  readonly kind: 'image' | 'video';
+  readonly fileId: string;
+  readonly name?: string;
+}
+
 export interface TurnStartedEvent {
   readonly type: 'turn.started';
   readonly turnId: number;
   readonly origin: PromptOrigin;
   readonly prompt?: string;
+  readonly promptAttachments?: readonly TurnPromptAttachment[];
+  readonly promptId?: string;
 }
 
-export function turnPromptText(input: readonly ContentPart[]): string | undefined {
-  const text = input
+/**
+ * The displayable projection of the turn-opening input: the prompt text with
+ * machine markup folded out, plus one entry per referenced upload. Both
+ * halves come from a single `foldMediaPathTagRefs` pass, so callers take the
+ * pair rather than re-running the pairing per field.
+ */
+export interface TurnPromptProjection {
+  readonly text?: string;
+  readonly attachments?: readonly TurnPromptAttachment[];
+}
+
+export function projectTurnPrompt(input: readonly ContentPart[]): TurnPromptProjection {
+  const { parts, media } = foldMediaPathTagRefs(input);
+  const text = parts
     .filter((part): part is TextPart => part.type === 'text')
     .map((part) => part.text)
     .join('');
-  return text.length > 0 ? text : undefined;
+  return {
+    text: text.length > 0 ? text : undefined,
+    attachments:
+      media.length === 0
+        ? undefined
+        : media.map((entry) => ({
+            kind: entry.kind,
+            fileId: entry.ref.fileId,
+            name: entry.path === undefined ? undefined : pathBaseName(entry.path),
+          })),
+  };
+}
+
+function pathBaseName(path: string): string {
+  const sep = Math.max(path.lastIndexOf('/'), path.lastIndexOf('\\'));
+  return sep === -1 ? path : path.slice(sep + 1);
 }
 
 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 809462aed6..7d2e93302e 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 7615648aa5..d7a26ef915 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 0000000000..8448e06b51
--- /dev/null
+++ b/packages/agent-core-v2/src/agent/media/mediaRef.ts
@@ -0,0 +1,344 @@
+/**
+ * `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>?path=<encoded
+ * absolute path>` URL: `fileId` addresses the daemon upload the request-time
+ * media resolver reads bytes from, and the optional `?path=` names the
+ * materialized copy the model opens with `ReadMediaFile` when the media
+ * cannot be uploaded or inlined. 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 — prompt intake persists that absolute path. The
+ * persisted path is a write-time snapshot: after a session fork or a home
+ * relocation it goes stale, so readers prefer the canonical location when it
+ * exists and treat the carried path as a fallback hint (see the request-time
+ * media resolver).
+ *
+ * The `<image|video|audio|file path="…">` tag is the model-facing
+ * degradation form: the resolver (or an edge) swaps a media part for the tag
+ * when the bytes cannot reach the provider, and 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 — the shape upload edges emit as a standalone text part
+ * next to the daemon-ref media part; tags embedded in larger user text are
+ * never matched, because stripping there would eat user content.
+ *
+ * The tag + daemon-ref fold is the read-model normalization of the upload
+ * pair: a CLAIMED tag text part disappears (it is machine markup), and each
+ * daemon-ref media part yields one `FoldedMediaRef` — carrying the paired
+ * tag's path, or none for a bare ref. An unpaired standalone tag stays as a
+ * text part: without a pairing ref it is user-visible text, not markup the
+ * read model may eat. `pairMediaPathTagRefs` is the single pairing algorithm
+ * the fold and the request-time media resolver share, so the two can never
+ * drift apart. Pairing rules: only a standalone tag participates; a tag
+ * pairs with a daemon-ref media part immediately before or after it (edges
+ * emit tag-before-ref; persisted history also has ref-before-tag) when the
+ * kinds are compatible — a `file` tag matches either ref kind — AND the
+ * tag's path equals the path the reference carries (a reference without a
+ * path can never pair); each tag claims at most one reference and each
+ * reference is claimed by at most one tag, references claiming in input
+ * order, checking the part before them first. `claimingRefIndex` recovers
+ * which reference claimed a given tag.
+ *
+ * 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)) {
+    if (out[mime] === undefined) 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://';
+const PATH_QUERY = '?path=';
+
+export interface DaemonFileRef {
+  readonly fileId: string;
+  readonly path?: string;
+}
+
+export function isDaemonFileUrl(url: string): boolean {
+  return url.startsWith(KIMI_FILE_SCHEME);
+}
+
+export function buildDaemonFileUrl(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 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(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 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;
+}
+
+export interface FoldedMediaRef {
+  readonly kind: 'image' | 'video';
+  readonly ref: DaemonFileRef;
+  readonly path?: string;
+}
+
+export interface MediaPathTagFold {
+  readonly parts: ContentPart[];
+  readonly media: FoldedMediaRef[];
+}
+
+export interface MediaPathTagPairing {
+  readonly claimedTagIndices: ReadonlySet<number>;
+  readonly claimedPathByRefIndex: ReadonlyMap<number, string>;
+  readonly claimingRefByTagIndex: ReadonlyMap<number, number>;
+}
+
+export function pairMediaPathTagRefs(parts: readonly ContentPart[]): MediaPathTagPairing {
+  const tagByIndex = new Map<number, MediaPathTag>();
+  const refByIndex = new Map<number, { kind: 'image' | 'video'; path?: string }>();
+  parts.forEach((part, index) => {
+    if (part.type === 'text') {
+      const tag = matchSingleMediaPathTag(part.text);
+      if (tag !== undefined) tagByIndex.set(index, tag);
+      return;
+    }
+    const ref = daemonFileRefFromPart(part);
+    if (ref !== undefined) refByIndex.set(index, { kind: ref.kind, path: ref.ref.path });
+  });
+  const claimedTagIndices = new Set<number>();
+  const claimedPathByRefIndex = new Map<number, string>();
+  const claimingRefByTagIndex = new Map<number, number>();
+  for (const [refIndex, ref] of refByIndex) {
+    if (ref.path === undefined) continue;
+    for (const neighbor of [refIndex - 1, refIndex + 1]) {
+      const tag = tagByIndex.get(neighbor);
+      if (tag === undefined || claimedTagIndices.has(neighbor)) continue;
+      if (tag.kind !== 'file' && tag.kind !== ref.kind) continue;
+      if (tag.path !== ref.path) continue;
+      claimedTagIndices.add(neighbor);
+      claimedPathByRefIndex.set(refIndex, tag.path);
+      claimingRefByTagIndex.set(neighbor, refIndex);
+      break;
+    }
+  }
+  return { claimedTagIndices, claimedPathByRefIndex, claimingRefByTagIndex };
+}
+
+export function foldMediaPathTagRefs(parts: readonly ContentPart[]): MediaPathTagFold {
+  const pairing = pairMediaPathTagRefs(parts);
+  const kept: ContentPart[] = [];
+  const media: FoldedMediaRef[] = [];
+  parts.forEach((part, index) => {
+    if (pairing.claimedTagIndices.has(index)) return;
+    kept.push(part);
+    const ref = daemonFileRefFromPart(part);
+    if (ref === undefined) return;
+    media.push({
+      kind: ref.kind,
+      ref: ref.ref,
+      path: pairing.claimedPathByRefIndex.get(index),
+    });
+  });
+  return { parts: kept, media };
+}
+
+export function claimingRefIndex(
+  pairing: MediaPathTagPairing,
+  tagIndex: number,
+): number | undefined {
+  return pairing.claimingRefByTagIndex.get(tagIndex);
+}
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 0000000000..289c6301ca
--- /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 a dropped image 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 0000000000..069428ca22
--- /dev/null
+++ b/packages/agent-core-v2/src/agent/media/mediaResolverService.ts
@@ -0,0 +1,447 @@
+/**
+ * `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.
+ *
+ * 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 (size-bounded)
+ * 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 because they depend on the message's tag pairing.
+ * 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 through the reference's materialization
+ * path: DROPPED silently only when the tag+ref pairing
+ * (`pairMediaPathTagRefs`, shared with the read-model fold) claims this exact
+ * reference — an adjacent standalone `<image path>` tag carrying the same
+ * path already conveys it — otherwise the `<image path>` tag is SYNTHESIZED
+ * from the reference path so a bare SDK-supplied reference still leaves the
+ * model the path to re-open; a reference without a path 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 — a persisted claimed
+ * tag refreshed in place, or a synthesized tag — is resolved through the
+ * session media store (`ISessionMediaStore`): the session-canonical copy
+ * wins when it exists, the reference's persisted snapshot path is the
+ * fallback, so a fork or a home relocation never hands the model a dead
+ * path. A reference claimed by a persisted tag leaves only that refreshed
+ * tag behind (video degrades included — a claimed reference never produces
+ * a second tag), and 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. Bound at
+ * Agent scope.
+ */
+
+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 { isModelAcceptedImageMime, normalizeImageMime } from './image-format-policy';
+import {
+  buildMediaPathTag,
+  claimingRefIndex,
+  type DaemonFileRef,
+  daemonFileRefFromPart,
+  type MediaPathTagPairing,
+  matchSingleMediaPathTag,
+  pairMediaPathTagRefs,
+} 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 keeps its base64 form alive in agent state for the
+ * agent's lifetime; skip the memo for outsized uploads so a rare huge paste
+ * is re-read from disk per request instead of pinning memory.
+ */
+const IMAGE_MEMO_MAX_BYTES = 8 * 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);
+  }
+
+  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[] = [];
+      // The fold's own pairing decides which references a tag claims: an
+      // image degrade may drop the part only when the pairing actually
+      // claims THIS reference (an adjacent standalone `<image path>` tag
+      // carrying the same path); a bare or unclaimed reference gets the tag
+      // synthesized from its path.
+      const pairing = pairMediaPathTagRefs(message.content);
+      let sawVideoRef = false;
+      for (const [index, part] of message.content.entries()) {
+        if (part.type === 'text' && pairing.claimedTagIndices.has(index)) {
+          content.push(await this.refreshClaimedTag(message.content, pairing, index));
+          continue;
+        }
+        const daemonPart = daemonFileRefFromPart(part);
+        if (daemonPart === undefined) {
+          content.push(part);
+          continue;
+        }
+        sawVideoRef ||= daemonPart.kind === 'video';
+        const claimed = pairing.claimedPathByRefIndex.has(index);
+        const resolved =
+          daemonPart.kind === 'video'
+            ? await this.resolveVideoPart(daemonPart.ref, requester, signal, claimed)
+            : await this.resolveImagePart(daemonPart.ref, requester, signal, claimed);
+        if (resolved !== undefined) 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, ref.path);
+  }
+
+  private async refreshClaimedTag(
+    parts: readonly ContentPart[],
+    pairing: MediaPathTagPairing,
+    tagIndex: number,
+  ): Promise<ContentPart> {
+    const part = parts[tagIndex]!;
+    if (part.type !== 'text') return part;
+    const tag = matchSingleMediaPathTag(part.text);
+    const refIndex = tag === undefined ? undefined : claimingRefIndex(pairing, tagIndex);
+    const daemonPart = refIndex === undefined ? undefined : daemonFileRefFromPart(parts[refIndex]!);
+    if (tag === undefined || daemonPart === undefined) return part;
+    const path = await this.displayPath(daemonPart.ref);
+    if (path === undefined || path === tag.path) return part;
+    return { type: 'text', text: buildMediaPathTag(tag.kind, path) };
+  }
+
+  // -------------------------------------------------------------------------
+  // 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,
+    hasAdjacentPathTag: boolean,
+  ): Promise<ContentPart | undefined> {
+    if (!requester.model.capabilities.image_in) {
+      return degradedImage(hasAdjacentPathTag, 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.resolved.get(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(hasAdjacentPathTag, path);
+    }
+
+    const fileType = detectFileType(
+      source.filename,
+      source.bytes.subarray(0, MEDIA_SNIFF_BYTES),
+      'media',
+    );
+    if (fileType.kind !== 'image') return degradedImage(hasAdjacentPathTag, path);
+    if (!isModelAcceptedImageMime(fileType.mimeType)) return degradedImage(hasAdjacentPathTag, 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.resolved.set(cacheKey, part);
+    return part;
+  }
+
+  // -------------------------------------------------------------------------
+  // Video strategy — upload once, memoize, degrade to inline or tag.
+  // -------------------------------------------------------------------------
+
+  private async resolveVideoPart(
+    ref: DaemonFileRef,
+    requester: ModelRequester,
+    signal: AbortSignal | undefined,
+    claimed: boolean,
+  ): Promise<ContentPart | undefined> {
+    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 this.memoedOutcome(ref, memoed, claimed);
+
+    const { part, memoize } = await this.resolveVideoUncached(ref, requester, cacheKey, signal);
+    if (part.type === 'text' && claimed) return undefined;
+    if (memoize) this.resolved.set(cacheKey, part);
+    return part;
+  }
+
+  private async memoedOutcome(
+    ref: DaemonFileRef,
+    memoed: ContentPart,
+    claimed: boolean,
+  ): Promise<ContentPart | undefined> {
+    if (memoed.type !== 'text') return memoed;
+    if (claimed) return undefined;
+    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;
+    if (!model.capabilities.video_in) return { part: videoTag(tagPath), 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) : 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, ref.path);
+      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(hasAdjacentPathTag: boolean, path: string | undefined): ContentPart | undefined {
+  if (path === undefined) return unavailableMediaText('image');
+  if (hasAdjacentPathTag) return undefined;
+  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 0000000000..f924391806
--- /dev/null
+++ b/packages/agent-core-v2/src/agent/media/promptMediaIntake.ts
@@ -0,0 +1,150 @@
+/**
+ * `media` domain — prompt-intake normalization 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`) and carries that absolute path, so the
+ * persisted reference always points into the session's own `media/` dir —
+ * whichever edge (REST prompt route, SDK prompt, steer, …) the message
+ * arrived through. When the canonical write fails, the session media store
+ * places the bytes in its shared-cache fallback — a read-only session dir must
+ * not reject a submittable prompt — with the extension derived like the
+ * canonical copy's: hint path, then upload name, then MIME.
+ *
+ * Intake also authors the paired `<image|video path="…">` tag: edges submit
+ * the bare daemon reference, and a successfully materialized reference that
+ * no standalone tag claims — pairing is re-evaluated on the rewritten
+ * content, so a tag whose path already matches the rewritten reference
+ * counts — gets its tag synthesized immediately before it. Normalization is
+ * idempotent (a reference already carrying the canonical path with its
+ * paired tag passes through untouched) and best effort (an unreadable
+ * upload keeps its original reference and gains no tag; the request-time
+ * resolver degrades it instead). 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 {
+  buildDaemonFileUrl,
+  buildMediaPathTag,
+  claimingRefIndex,
+  daemonFileRefFromPart,
+  matchSingleMediaPathTag,
+  pairMediaPathTagRefs,
+} 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<readonly ContentPart[]> {
+  if (!content.some((part) => daemonFileRefFromPart(part) !== undefined)) return content;
+
+  const pairing = pairMediaPathTagRefs(content);
+  const out: ContentPart[] = [];
+  let changed = false;
+  const pathByRefIndex = new Map<number, string>();
+
+  for (const [index, part] of content.entries()) {
+    deps.signal?.throwIfAborted();
+    const daemonPart = daemonFileRefFromPart(part);
+    if (daemonPart === undefined) {
+      out.push(part);
+      continue;
+    }
+    const path = await materializeRef(deps, daemonPart.ref.fileId, daemonPart.ref.path).catch(
+      (_error: unknown) => {
+        deps.signal?.throwIfAborted();
+        return undefined;
+      },
+    );
+    if (path === undefined || path === daemonPart.ref.path) {
+      if (path !== undefined) pathByRefIndex.set(index, path);
+      out.push(part);
+      continue;
+    }
+    pathByRefIndex.set(index, path);
+    out.push(rewriteRefPath(part, daemonPart.ref.fileId, path));
+    changed = true;
+  }
+
+  for (const tagIndex of pairing.claimedTagIndices) {
+    const refIndex = claimingRefIndex(pairing, tagIndex);
+    if (refIndex === undefined) continue;
+    const path = pathByRefIndex.get(refIndex);
+    const tagPart = content[tagIndex];
+    if (path === undefined || tagPart?.type !== 'text') continue;
+    const tag = matchSingleMediaPathTag(tagPart.text);
+    if (tag === undefined || tag.path === path) continue;
+    out[tagIndex] = { type: 'text', text: buildMediaPathTag(tag.kind, path) };
+    changed = true;
+  }
+
+  const finalPairing = pairMediaPathTagRefs(out);
+  const authored: ContentPart[] = [];
+  let inserted = false;
+  for (const [index, part] of out.entries()) {
+    const path = pathByRefIndex.get(index);
+    if (path !== undefined && !finalPairing.claimedPathByRefIndex.has(index)) {
+      const daemonPart = daemonFileRefFromPart(part);
+      if (daemonPart !== undefined) {
+        authored.push({ type: 'text', text: buildMediaPathTag(daemonPart.kind, path) });
+        inserted = true;
+      }
+    }
+    authored.push(part);
+  }
+  if (inserted) return authored;
+
+  return changed ? out : content;
+}
+
+async function materializeRef(
+  deps: PromptMediaIntakeDeps,
+  fileId: string,
+  hintPath: string | undefined,
+): Promise<string | undefined> {
+  const file =
+    deps.signal === undefined
+      ? await deps.files.get(fileId)
+      : await abortable(deps.files.get(fileId), deps.signal);
+  const input = {
+    fileId,
+    size: file.meta.size,
+    name: file.meta.name,
+    mimeType: file.meta.media_type,
+    hintPath,
+  };
+  try {
+    const path = await deps.mediaStore.materialize({
+      ...input,
+      stream: () => file.stream(),
+      signal: deps.signal,
+    });
+    if (path !== undefined) return path;
+  } catch {
+    deps.signal?.throwIfAborted();
+  }
+  return deps.mediaStore.materializeFallback({
+    ...input,
+    stream: () => file.stream(),
+    signal: deps.signal,
+  });
+}
+
+function rewriteRefPath(part: ContentPart, fileId: string, path: string): ContentPart {
+  const url = buildDaemonFileUrl(fileId, path);
+  if (part.type === 'image_url') return { ...part, imageUrl: { ...part.imageUrl, url } };
+  if (part.type === 'video_url') return { ...part, videoUrl: { ...part.videoUrl, url } };
+  return part;
+}
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 0000000000..c25380bd90
--- /dev/null
+++ b/packages/agent-core-v2/src/agent/media/sessionMediaStore.ts
@@ -0,0 +1,40 @@
+/**
+ * `media` domain — `ISessionMediaStore` contract.
+ *
+ * Owns the per-session canonical media blobs and shared-cache fallback through
+ * the persistence byte store. It materializes daemon uploads, exposes a host
+ * path only when the selected backend has one, and reads canonical bytes 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 hintPath?: string;
+  readonly stream: () => NodeJS.ReadableStream;
+  readonly signal?: AbortSignal;
+}
+
+export interface ISessionMediaStore {
+  readonly _serviceBrand: undefined;
+
+  pathFor(fileId: string, ext: string): string | undefined;
+
+  resolveDisplayPath(fileId: string, hint: string | undefined): Promise<string | undefined>;
+
+  read(
+    fileId: string,
+    hintPath?: string,
+  ): Promise<{ readonly data: Uint8Array; readonly name: string } | undefined>;
+
+  materialize(input: SessionMediaMaterializeInput): Promise<string | undefined>;
+
+  materializeFallback(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 0000000000..7ee60dd3f6
--- /dev/null
+++ b/packages/agent-core-v2/src/agent/media/sessionMediaStoreService.ts
@@ -0,0 +1,119 @@
+/**
+ * `media` domain — `ISessionMediaStore` implementation.
+ *
+ * Materializes and reads session-canonical media through the `storage` byte
+ * backend, addressed by `sessionContext`, with the shared cache as a fallback
+ * when the session media directory is unavailable. Filesystem deployments
+ * expose an absolute host path for model readback; non-filesystem deployments
+ * retain the canonical bytes without inventing one. Every entry point rejects
+ * ids that are not minted upload ids (`isFileId`) — the id becomes a storage
+ * key here, so an unvalidated id would be a path-traversal vector. Bound at
+ * Session scope.
+ */
+
+import { extname } from 'node:path';
+
+import { LifecycleScope } from '#/app/scopes';
+import { ScopeActivation, registerScopedService } from '#/_base/di/scope';
+import { IBootstrapService } from '#/app/bootstrap/bootstrap';
+import { isFileId } from '#/app/file/fileService';
+import { IFileSystemStorageService } from '#/persistence/interface/storage';
+import { ISessionContext } from '#/session/sessionContext/sessionContext';
+
+import { mediaExtensionForMime } from './mediaRef';
+import { ISessionMediaStore, type SessionMediaMaterializeInput } from './sessionMediaStore';
+
+export class SessionMediaStoreService implements ISessionMediaStore {
+  declare readonly _serviceBrand: undefined;
+  private readonly scope: string;
+  private readonly fallbackScope: string;
+
+  constructor(
+    @ISessionContext sessionContext: ISessionContext,
+    @IFileSystemStorageService private readonly storage: IFileSystemStorageService,
+    @IBootstrapService bootstrap: IBootstrapService,
+  ) {
+    this.scope = sessionContext.scope('media');
+    this.fallbackScope = bootstrap.scope('cache');
+  }
+
+  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, hint: string | undefined): Promise<string | undefined> {
+    if (hint === undefined || hint.length === 0) return undefined;
+    // An id that is not a minted upload id can never have a canonical copy —
+    // and must never become a storage key (path traversal guard). Treat it
+    // like a missing copy: the caller's own hint stands.
+    if (!isFileId(fileId)) return hint;
+    const ext = extname(hint);
+    const canonical = this.pathFor(fileId, ext);
+    if (canonical === undefined || canonical === hint) return hint;
+    const size = await this.storage.size(this.scope, this.keyFor(fileId, ext));
+    return size === undefined ? hint : canonical;
+  }
+
+  async read(
+    fileId: string,
+    hintPath?: string,
+  ): Promise<{ readonly data: Uint8Array; readonly name: string } | undefined> {
+    if (!isFileId(fileId)) return undefined;
+    const key = await this.findKey(fileId, hintPath);
+    if (key === undefined) return undefined;
+    const data = await this.storage.read(this.scope, key);
+    return data === undefined ? undefined : { data, name: key };
+  }
+
+  async materialize(input: SessionMediaMaterializeInput): Promise<string | undefined> {
+    return this.materializeAt(this.scope, input);
+  }
+
+  async materializeFallback(input: SessionMediaMaterializeInput): Promise<string | undefined> {
+    return this.materializeAt(this.fallbackScope, input);
+  }
+
+  private async materializeAt(
+    scope: string,
+    input: SessionMediaMaterializeInput,
+  ): Promise<string | undefined> {
+    if (!isFileId(input.fileId)) return undefined;
+    const ext =
+      (input.hintPath === undefined ? '' : extname(input.hintPath)) ||
+      extname(input.name) ||
+      mediaExtensionForMime(input.mimeType) ||
+      '.bin';
+    const key = this.keyFor(input.fileId, ext);
+    const existingSize = await this.storage.size(scope, key);
+    if (existingSize !== input.size) {
+      const source = input.stream() as NodeJS.ReadableStream & AsyncIterable<Uint8Array>;
+      await this.storage.writeStream(scope, key, source, {
+        atomic: true,
+        signal: input.signal,
+      });
+    }
+    return this.storage.pathFor(scope, key);
+  }
+
+  private keyFor(fileId: string, ext: string): string {
+    return `${fileId}${ext}`;
+  }
+
+  private async findKey(fileId: string, hintPath: string | undefined): Promise<string | undefined> {
+    if (hintPath !== undefined) {
+      const hinted = this.keyFor(fileId, extname(hintPath));
+      if ((await this.storage.size(this.scope, hinted)) !== undefined) return hinted;
+    }
+    const keys = await this.storage.list(this.scope, fileId);
+    return keys.find((key) => key === fileId || key.startsWith(`${fileId}.`));
+  }
+}
+
+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 efbdefb8e8..f140f98bde 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 1aafe624d5..dc63a96ba1 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/prompt.ts b/packages/agent-core-v2/src/agent/prompt/prompt.ts
index d5045dd025..77288bcc51 100644
--- a/packages/agent-core-v2/src/agent/prompt/prompt.ts
+++ b/packages/agent-core-v2/src/agent/prompt/prompt.ts
@@ -53,6 +53,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 631c7c5d34..df409e9236 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. An upload's `<media path>` tag text part is machine
+ * markup paired with its daemon-ref media part (`foldMediaPathTagRefs`) —
+ * stripping it keeps the materialization path out of titles / lastPrompt.
  */
 
 import type { ContentPart } from '#/kosong/contract/message';
+import { foldMediaPathTagRefs } from '#/agent/media/mediaRef';
 import { extractImageCompressionCaptions } from '#/agent/media/image-compress';
 
 const MAX_TITLE_LENGTH = 200;
@@ -20,7 +23,7 @@ export function promptMetadataTextFromContentParts(
   parts: readonly ContentPart[],
 ): string | undefined {
   const texts: string[] = [];
-  for (const part of parts) {
+  for (const part of foldMediaPathTagRefs(parts).parts) {
     const text = promptPartText(part);
     if (text !== undefined) texts.push(text);
   }
diff --git a/packages/agent-core-v2/src/agent/prompt/promptService.ts b/packages/agent-core-v2/src/agent/prompt/promptService.ts
index efd40bac1c..1e56d1207b 100644
--- a/packages/agent-core-v2/src/agent/prompt/promptService.ts
+++ b/packages/agent-core-v2/src/agent/prompt/promptService.ts
@@ -4,7 +4,11 @@
  * 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. The pure-data `launching` flag is registered into
+ * resource model. Daemon file references in submissions are normalized through
+ * the `media` domain's intake (`materializePromptDaemonRefs` — materialize
+ * into the session media store and author the paired media-path tag); the media
+ * store owns canonical and shared-cache persistence. 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
  * `Record` values carry Deferred promise handles (the container only holds
@@ -13,10 +17,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';
@@ -30,6 +38,7 @@ import type { ExecutableToolResult } from '#/tool/toolContract';
 import type { ToolDidExecuteContext } from '#/agent/toolExecutor/toolHooks';
 import { IAgentToolExecutorService } from '#/agent/toolExecutor/toolExecutor';
 import type { ContentPart } from '#/kosong/contract/message';
+import { IFileService } from '#/app/file/fileService';
 import { IEventBus } from '#/app/event/eventBus';
 import { ErrorCodes, Error2 } from '#/errors';
 import { OrderedHookSlot } from '#/hooks';
@@ -59,18 +68,30 @@ 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 intakes = new Set<Promise<void>>();
+  private readonly intakeControllers = new Set<AbortController>();
   private fullCompactionService: IAgentFullCompactionService | undefined;
   readonly hooks = { onBeforeSubmitPrompt: new OrderedHookSlot<PromptSubmitContext>() };
 
@@ -83,12 +104,17 @@ 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,
   ) {
+    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 {
@@ -99,16 +125,38 @@ 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,
+    }).then((content) => {
+      if (record.intakeController.signal.aborted) return;
+      record.message = { ...record.message, content: [...content] };
+    });
+    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;
+  }
+
   async enqueue(input: PromptInput): Promise<PromptHandle> {
     const id = input.id ?? input.message.id ?? newMessageId();
     const message = { ...input.message, 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; },
@@ -122,6 +170,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);
@@ -135,39 +187,91 @@ export class AgentPromptService implements IAgentPromptService {
 
   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) => {
@@ -180,40 +284,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 }); }
@@ -267,6 +426,7 @@ export class AgentPromptService implements IAgentPromptService {
 }
 
 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 f84ede987e..e374341ec4 100644
--- a/packages/agent-core-v2/src/agent/prompt/promptStepRequests.ts
+++ b/packages/agent-core-v2/src/agent/prompt/promptStepRequests.ts
@@ -72,7 +72,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/agent/rpc/core-api.ts b/packages/agent-core-v2/src/agent/rpc/core-api.ts
index f1c68603cc..8d8b7cf6a3 100644
--- a/packages/agent-core-v2/src/agent/rpc/core-api.ts
+++ b/packages/agent-core-v2/src/agent/rpc/core-api.ts
@@ -119,6 +119,11 @@ export interface SessionSummary {
 export interface PromptPayload {
   readonly input: readonly ContentPart[];
   readonly disabledTools?: readonly string[];
+  /**
+   * Client-chosen prompt record id; echoed back on the consuming turn's
+   * `turn.started` (`promptId`). Omit to let the engine assign one.
+   */
+  readonly promptId?: string;
 }
 export interface RunShellCommandPayload {
   readonly command: string;
diff --git a/packages/agent-core-v2/src/agent/rpc/rpcService.ts b/packages/agent-core-v2/src/agent/rpc/rpcService.ts
index f3d089ab76..c74c84e0e8 100644
--- a/packages/agent-core-v2/src/agent/rpc/rpcService.ts
+++ b/packages/agent-core-v2/src/agent/rpc/rpcService.ts
@@ -99,7 +99,7 @@ export class AgentRPCService implements IAgentRPCService {
       }
     }
     await this.updatePromptMetadata(promptMetadataTextFromPayload(payload));
-    const handle = await this.promptService.enqueue({ message: {
+    const handle = await this.promptService.enqueue({ id: payload.promptId, message: {
       role: 'user',
       content: [...payload.input],
       toolCalls: [],
diff --git a/packages/agent-core-v2/src/app/file/fileService.ts b/packages/agent-core-v2/src/app/file/fileService.ts
index 2dbab36438..57fc1a0fb9 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 d3de270f0e..5f8bb67297 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 9994bbf630..f2979a0fbc 100644
--- a/packages/agent-core-v2/src/index.ts
+++ b/packages/agent-core-v2/src/index.ts
@@ -591,8 +591,31 @@ 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,
+  foldMediaPathTagRefs,
+  mediaExtensionForMime,
+  pairMediaPathTagRefs,
+  parseDaemonFileUrl,
+} from '#/agent/media/mediaRef';
+export type {
+  DaemonFileRef,
+  FoldedMediaRef,
+  MediaKind,
+  MediaPathTagFold,
+  MediaPathTagPairing,
+} 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';
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 b32ec029f2..77f29c7b4e 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 e7ce6d995f..b76fb1f35f 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 1d55183cb1..1323ffb8d1 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 6c7a0d6efe..9d4504ba02 100644
--- a/packages/agent-core-v2/src/session/agentLifecycle/agentLifecycleService.ts
+++ b/packages/agent-core-v2/src/session/agentLifecycle/agentLifecycleService.ts
@@ -48,6 +48,7 @@ import { IAgentPermissionModeService } from '#/agent/permissionMode/permissionMo
 import { IAgentContextMemoryService } from '#/agent/contextMemory/contextMemory';
 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';
@@ -260,6 +261,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);
     }
@@ -267,7 +269,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 a58079cc87..3c06178651 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';
@@ -141,6 +141,7 @@ function createService(
     | undefined,
   options: {
     readonly thinkingLevel?: ThinkingEffort;
+    readonly mediaResolver?: Partial<IAgentMediaResolverService>;
   } = {},
 ) {
   const ix = disposables.add(new TestInstantiationService());
@@ -196,7 +197,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,
@@ -801,3 +802,18 @@ describe('AgentLLMRequesterService trace id', () => {
     ).toBeUndefined();
   });
 });
+
+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);
+  });
+});
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 6ed1e1c4f6..c71597addb 100644
--- a/packages/agent-core-v2/test/agent/loop/loop.test.ts
+++ b/packages/agent-core-v2/test/agent/loop/loop.test.ts
@@ -60,7 +60,7 @@ describe('Agent loop', () => {
     expect(await ctx.untilTurnEnd()).toMatchInlineSnapshot(`
       [wire] tools.set_active_tools      { "names": [], "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>" }
@@ -114,7 +114,7 @@ describe('Agent loop', () => {
 
     expect(await ctx.untilTurnEnd()).toMatchInlineSnapshot(`
       [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>" }
@@ -333,7 +333,7 @@ describe('Agent loop', () => {
     expect(await ctx.untilApproval(true)).toMatchInlineSnapshot(`
       [wire] tools.set_active_tools          { "names": [ "Lookup" ], "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>" }
@@ -703,8 +703,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' });
@@ -728,6 +730,61 @@ 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('folds an upload tag+ref pair 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: 'text', text: '<image path="/cache/f_123.png"></image>' },
+              {
+                type: 'image_url',
+                imageUrl: { url: 'kimi-file://f_123?path=%2Fcache%2Ff_123.png' },
+              },
+            ],
+            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', name: 'f_123.png' }],
+      },
+    ]);
   });
 });
 
diff --git a/packages/agent-core-v2/test/agent/loop/stubs.ts b/packages/agent-core-v2/test/agent/loop/stubs.ts
index 227bf84b3c..f2ed41d251 100644
--- a/packages/agent-core-v2/test/agent/loop/stubs.ts
+++ b/packages/agent-core-v2/test/agent/loop/stubs.ts
@@ -3,15 +3,14 @@
  */
 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 { IWireService } from '#/wire/wire';
 
@@ -21,6 +20,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 +44,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();
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 eec3074636..56d0782c1a 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,18 @@ describe('gateImageFormatParts', () => {
     }
   });
 
+  it('passes daemon file references (kimi-file://) through untouched', () => {
+    const fileId = 'f_9b2f7c1e4a2d4f3a8c1e0b6d5a493827';
+    // The gate's unsupported-extension check strips the `?path=` query before
+    // looking for an extension, so a daemon reference survives as-is — even
+    // one whose path suffix (`.heic`) a remote URL would be rejected for,
+    // because the resolver sniffs the real bytes downstream.
+    for (const path of ['/tmp/upload/photo.png', '/tmp/upload/photo.heic']) {
+      const part = { type: 'image_url' as const, imageUrl: { url: buildDaemonFileUrl(fileId, path) } };
+      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 0000000000..3d6b2954fc
--- /dev/null
+++ b/packages/agent-core-v2/test/agent/media/mediaRef.test.ts
@@ -0,0 +1,332 @@
+/**
+ * `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,
+  foldMediaPathTagRefs,
+  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('round-trips fileId and path', () => {
+    const url = buildDaemonFileUrl('file_1', '/a b/clip.mp4');
+    expect(url).toBe('kimi-file://file_1?path=%2Fa%20b%2Fclip.mp4');
+    expect(parseDaemonFileUrl(url)).toEqual({ fileId: 'file_1', path: '/a b/clip.mp4' });
+  });
+
+  it('builds and parses a bare reference without path', () => {
+    expect(buildDaemonFileUrl('file_1')).toBe('kimi-file://file_1');
+    expect(parseDaemonFileUrl('kimi-file://file_1')).toEqual({ fileId: 'file_1' });
+    expect(buildDaemonFileUrl('file_1', '')).toBe('kimi-file://file_1');
+    expect(parseDaemonFileUrl('kimi-file://file_1?path=')).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('drops an undecodable path but keeps the file id', () => {
+    expect(parseDaemonFileUrl('kimi-file://file_1?path=%E0%A4%A')).toEqual({ fileId: 'file_1' });
+  });
+
+  it('extracts references from media parts with the part-implied kind', () => {
+    const url = buildDaemonFileUrl('file_1', '/cache/a.png');
+    expect(
+      daemonFileRefFromPart({ type: 'image_url', imageUrl: { url } }),
+    ).toEqual({ kind: 'image', ref: { fileId: 'file_1', path: '/cache/a.png' } });
+    expect(
+      daemonFileRefFromPart({ type: 'video_url', videoUrl: { url } }),
+    ).toEqual({ kind: 'video', ref: { fileId: 'file_1', path: '/cache/a.png' } });
+    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();
+  });
+});
+
+describe('foldMediaPathTagRefs', () => {
+  const daemonImage = (fileId: string, path?: string): ContentPart => ({
+    type: 'image_url',
+    imageUrl: { url: buildDaemonFileUrl(fileId, path) },
+  });
+
+  it('folds a tag-before-ref pair into one media entry carrying the tag path', () => {
+    const ref = daemonImage('file_1', '/cache/shot.png');
+    const fold = foldMediaPathTagRefs([
+      { type: 'text', text: 'what is this?' },
+      { type: 'text', text: '<image path="/cache/shot.png"></image>' },
+      ref,
+    ]);
+    expect(fold.parts).toEqual([{ type: 'text', text: 'what is this?' }, ref]);
+    expect(fold.media).toEqual([
+      { kind: 'image', ref: { fileId: 'file_1', path: '/cache/shot.png' }, path: '/cache/shot.png' },
+    ]);
+  });
+
+  it('folds a ref-before-tag pair the same way', () => {
+    const ref = daemonImage('file_1', '/cache/shot.png');
+    const fold = foldMediaPathTagRefs([
+      ref,
+      { type: 'text', text: '<image path="/cache/shot.png"></image>' },
+    ]);
+    expect(fold.parts).toEqual([ref]);
+    expect(fold.media).toEqual([
+      { kind: 'image', ref: { fileId: 'file_1', path: '/cache/shot.png' }, path: '/cache/shot.png' },
+    ]);
+  });
+
+  it('keeps an unpaired standalone tag as text', () => {
+    const tag: ContentPart = { type: 'text', text: '<image path="/cache/shot.png">' };
+    const fold = foldMediaPathTagRefs([tag, { type: 'text', text: 'kept' }]);
+    expect(fold.parts).toEqual([tag, { type: 'text', text: 'kept' }]);
+    expect(fold.media).toEqual([]);
+  });
+
+  it('keeps a bare ref as pathless media', () => {
+    const ref = daemonImage('file_1');
+    const fold = foldMediaPathTagRefs([ref]);
+    expect(fold.parts).toEqual([ref]);
+    expect(fold.media).toEqual([{ kind: 'image', ref: { fileId: 'file_1' }, path: undefined }]);
+  });
+
+  it('leaves non-daemon media parts untouched and out of the media list', () => {
+    const remote: ContentPart = { type: 'image_url', imageUrl: { url: 'https://example.com/a.png' } };
+    const fold = foldMediaPathTagRefs([remote]);
+    expect(fold.parts).toEqual([remote]);
+    expect(fold.media).toEqual([]);
+  });
+
+  it('neither pairs nor drops a kind-mismatched adjacent tag', () => {
+    const tag: ContentPart = { type: 'text', text: '<image path="/cache/clip.mp4"></image>' };
+    const ref: ContentPart = {
+      type: 'video_url',
+      videoUrl: { url: buildDaemonFileUrl('file_1', '/cache/clip.mp4') },
+    };
+    const fold = foldMediaPathTagRefs([tag, ref]);
+    expect(fold.parts).toEqual([tag, ref]);
+    expect(fold.media).toEqual([
+      { kind: 'video', ref: { fileId: 'file_1', path: '/cache/clip.mp4' }, path: undefined },
+    ]);
+  });
+
+  it('pairs a file-kind tag with either ref kind when the path matches', () => {
+    const ref = daemonImage('file_1', '/cache/shot.png');
+    const fold = foldMediaPathTagRefs([{ type: 'text', text: '<file path="/cache/shot.png">' }, ref]);
+    expect(fold.parts).toEqual([ref]);
+    expect(fold.media[0]?.path).toBe('/cache/shot.png');
+  });
+
+  it('does not pair an adjacent tag whose path differs from the reference path', () => {
+    const tag: ContentPart = { type: 'text', text: '<image path="/cache/other.png"></image>' };
+    const ref = daemonImage('file_1', '/cache/shot.png');
+    const fold = foldMediaPathTagRefs([tag, ref]);
+    expect(fold.parts).toEqual([tag, ref]);
+    expect(fold.media).toEqual([
+      { kind: 'image', ref: { fileId: 'file_1', path: '/cache/shot.png' }, path: undefined },
+    ]);
+  });
+
+  it('never pairs a reference that carries no path — both sides stay', () => {
+    const tag: ContentPart = { type: 'text', text: '<image path="/cache/shot.png"></image>' };
+    const ref = daemonImage('file_1');
+    const fold = foldMediaPathTagRefs([tag, ref]);
+    expect(fold.parts).toEqual([tag, ref]);
+    expect(fold.media).toEqual([{ kind: 'image', ref: { fileId: 'file_1' }, path: undefined }]);
+  });
+
+  it('claims the tag for the path-matching ref, not the adjacent bare one', () => {
+    // [bareRefA, tagB, refB]: adjacency alone would misassign tagB to refA.
+    const bareRefA = daemonImage('file_1', '/cache/a.png');
+    const refB = daemonImage('file_2', '/cache/b.png');
+    const fold = foldMediaPathTagRefs([
+      bareRefA,
+      { type: 'text', text: '<image path="/cache/b.png"></image>' },
+      refB,
+    ]);
+    expect(fold.parts).toEqual([bareRefA, refB]);
+    expect(fold.media).toEqual([
+      { kind: 'image', ref: { fileId: 'file_1', path: '/cache/a.png' }, path: undefined },
+      { kind: 'image', ref: { fileId: 'file_2', path: '/cache/b.png' }, path: '/cache/b.png' },
+    ]);
+  });
+
+  it('claims a tag for at most one ref', () => {
+    const first = daemonImage('file_1', '/cache/a.png');
+    const second = daemonImage('file_2', '/cache/a.png');
+    const fold = foldMediaPathTagRefs([
+      first,
+      { type: 'text', text: '<image path="/cache/a.png"></image>' },
+      second,
+    ]);
+    expect(fold.parts).toEqual([first, second]);
+    expect(fold.media.map((m) => m.path)).toEqual(['/cache/a.png', undefined]);
+  });
+
+  it('claims at most one tag per ref, keeping the unclaimed tag as text', () => {
+    const ref = daemonImage('file_1', '/cache/shot.png');
+    const secondTag: ContentPart = { type: 'text', text: '<image path="/cache/shot.png"></image>' };
+    const fold = foldMediaPathTagRefs([
+      { type: 'text', text: '<image path="/cache/shot.png"></image>' },
+      ref,
+      secondTag,
+    ]);
+    expect(fold.parts).toEqual([ref, secondTag]);
+    expect(fold.media.map((m) => m.path)).toEqual(['/cache/shot.png']);
+  });
+
+  it('keeps user text with an inline tag verbatim', () => {
+    const text: ContentPart = { type: 'text', text: 'open <image path="/a.png"></image> please' };
+    const fold = foldMediaPathTagRefs([text]);
+    expect(fold.parts).toEqual([text]);
+    expect(fold.media).toEqual([]);
+  });
+});
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 0000000000..bee6d16df7
--- /dev/null
+++ b/packages/agent-core-v2/test/agent/media/mediaResolver.test.ts
@@ -0,0 +1,786 @@
+import { mkdtemp, mkdir, rm, stat, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { extname, 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 { LifecycleScope } from '#/app/scopes';
+import {
+  ScopeActivation,
+  _clearScopedRegistryForTests,
+  registerScopedService,
+} from '#/_base/di/scope';
+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 FALLBACK_PATH = '/cache/file_abc.mp4';
+const IMAGE_FALLBACK_PATH = '/cache/file_abc.png';
+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_TAG = `<video path="${FALLBACK_PATH}"></video>`;
+const IMAGE_TAG = `<image path="${IMAGE_FALLBACK_PATH}"></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 imagePathTagPart(path: string): ContentPart {
+  return { type: 'text', text: `<image path="${path}"></image>` };
+}
+
+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;
+
+/**
+ * Store stub over a plain dir: the canonical copy exists only when a test
+ * plants it (mirrors the real store's canonical-vs-hint rule without
+ * materialization).
+ */
+function stubMediaStore(sessionDir = '/nonexistent-session'): ISessionMediaStore {
+  return {
+    _serviceBrand: undefined,
+    pathFor: (fileId, ext) => join(sessionDir, 'media', `${fileId}${ext}`),
+    resolveDisplayPath: async (fileId, hint) => {
+      if (hint === undefined || hint.length === 0) return undefined;
+      const canonical = join(sessionDir, 'media', `${fileId}${extname(hint)}`);
+      if (canonical === hint) return hint;
+      const own = await stat(canonical).catch(() => undefined);
+      return own === undefined ? hint : canonical;
+    },
+    read: async () => undefined,
+    materialize: async () => {
+      throw new Error('unused');
+    },
+    materializeFallback: async () => {
+      throw new Error('unused');
+    },
+  };
+}
+
+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(() => {
+  disposables = new DisposableStore();
+});
+
+afterEach(() => disposables.dispose());
+
+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, FALLBACK_PATH));
+
+    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('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));
+
+    // 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 }),
+    },
+  ])('tags with the materialization path when $name', async ({ files, fileId, req }) => {
+    const upload = vi.fn();
+    const out = await resolver(files).resolve(
+      [videoMessage(buildKimiFileUrl(fileId, FALLBACK_PATH))],
+      req(upload),
+    );
+
+    expect(firstPart(out)).toEqual({ type: 'text', text: VIDEO_TAG });
+    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, FALLBACK_PATH))], requester({ uploadVideo: upload })),
+    ).rejects.toThrow('unauthorized');
+  });
+
+  it('rethrows a cancelled upload without memoizing the fallback', async () => {
+    const controller = new AbortController();
+    // The rejection is deliberately NOT abort-shaped: the aborted signal alone
+    // must decide cancellation, since abort error shapes vary by provider.
+    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, FALLBACK_PATH));
+
+    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 res = resolver(new Map([[FILE_ID, { name: 'clip.mp4', bytes: VIDEO_BYTES }]]));
+    const message = videoMessage(buildKimiFileUrl(FILE_ID, FALLBACK_PATH));
+    const req = requester({ uploadVideo: upload });
+
+    const failed = await res.resolve([message], req);
+    expect(firstPart(failed)).toEqual({ type: 'text', text: VIDEO_TAG });
+
+    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 fallback path', async () => {
+    const out = await resolver(new Map()).resolve(
+      [videoMessage(buildKimiFileUrl('missing'))],
+      requester({ uploadVideo: vi.fn() }),
+    );
+
+    expect(firstPart(out)).toEqual({
+      type: 'text',
+      text: '[video omitted: the uploaded file is no longer available]',
+    });
+  });
+});
+
+describe('AgentMediaResolverService canonical session bytes', () => {
+  it.each([
+    {
+      kind: 'video',
+      bytes: VIDEO_BYTES,
+      fileName: `${FILE_ID}.mp4`,
+      message: videoMessage(buildKimiFileUrl(FILE_ID, FALLBACK_PATH)),
+      expected: msPart('prov-1'),
+      uploads: 1,
+    },
+    {
+      kind: 'image',
+      bytes: PNG_BYTES,
+      fileName: `${FILE_ID}.png`,
+      message: imageMessage(buildKimiFileUrl(FILE_ID, IMAGE_FALLBACK_PATH)),
+      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 = imagePathTagPart(IMAGE_FALLBACK_PATH);
+    const remotePart: ContentPart = {
+      type: 'image_url',
+      imageUrl: { url: 'https://example.com/pic.png' },
+    };
+    const message = imageMessage(buildKimiFileUrl(FILE_ID, IMAGE_FALLBACK_PATH), 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, IMAGE_FALLBACK_PATH))],
+        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,
+    },
+  ])('drops the part, keeping the adjacent path tag, when $name', async ({ files, fileId, imageIn }) => {
+    const tagPart = imagePathTagPart(IMAGE_FALLBACK_PATH);
+    const message = imageMessage(buildKimiFileUrl(fileId, IMAGE_FALLBACK_PATH), tagPart);
+
+    const out = await resolver(files).resolve([message], requester({ imageIn }));
+
+    expect(out[0]!.content).toEqual([tagPart]);
+  });
+
+  it.each([
+    {
+      name: 'a bare stale reference has no adjacent tag',
+      files: new Map<string, { name: string; bytes: Buffer }>(),
+      url: buildKimiFileUrl('missing', IMAGE_FALLBACK_PATH),
+      imageIn: true,
+      expected: IMAGE_TAG,
+    },
+    {
+      name: 'the model cannot ingest images and no adjacent tag exists',
+      files: new Map([[FILE_ID, { name: 'pic.png', bytes: PNG_BYTES }]]),
+      url: buildKimiFileUrl(FILE_ID, IMAGE_FALLBACK_PATH),
+      imageIn: false,
+      expected: IMAGE_TAG,
+    },
+    {
+      name: 'the bytes sniff as an unaccepted image mime and no adjacent tag exists',
+      files: new Map([[FILE_ID, { name: 'pic.bmp', bytes: BMP_BYTES }]]),
+      url: buildKimiFileUrl(FILE_ID, IMAGE_FALLBACK_PATH),
+      imageIn: true,
+      expected: IMAGE_TAG,
+    },
+    {
+      name: 'the model cannot ingest images and there is no path',
+      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 path',
+      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 base = fileService(files);
+    let gets = 0;
+    const counting: IFileService = {
+      ...base,
+      get: async (fileId) => {
+        gets++;
+        return base.get(fileId);
+      },
+    };
+    const res = new AgentMediaResolverService(
+      counting,
+      blobStore(),
+      telemetry,
+      new AgentStateService(),
+      stubMediaStore(),
+    );
+    const message = imageMessage(buildKimiFileUrl(FILE_ID, IMAGE_FALLBACK_PATH));
+    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(gets).toBe(1);
+  });
+
+  it('re-reads an oversized image instead of pinning its base64 in agent state', async () => {
+    const bigBytes = Buffer.concat([PNG_BYTES, Buffer.alloc(8 * 1024 * 1024)]);
+    const files = new Map([[FILE_ID, { name: 'pic.png', bytes: bigBytes }]]);
+    const base = fileService(files);
+    let gets = 0;
+    const counting: IFileService = {
+      ...base,
+      get: async (fileId) => {
+        gets++;
+        return base.get(fileId);
+      },
+    };
+    const res = new AgentMediaResolverService(
+      counting,
+      blobStore(),
+      telemetry,
+      new AgentStateService(),
+      stubMediaStore(),
+    );
+    const message = imageMessage(buildKimiFileUrl(FILE_ID, IMAGE_FALLBACK_PATH));
+
+    const first = await res.resolve([message], requester({}));
+    const second = await res.resolve([message], requester({}));
+
+    expect(firstPart(first)).toEqual(firstPart(second));
+    expect(gets).toBe(2);
+  });
+
+  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 base = fileService(files);
+      let gets = 0;
+      const counting: IFileService = {
+        ...base,
+        get: async (fileId) => {
+          gets++;
+          return base.get(fileId);
+        },
+      };
+      const res = new AgentMediaResolverService(
+        counting,
+        blobStore(),
+        telemetry,
+        new AgentStateService(),
+        stubMediaStore(),
+      );
+      const message = imageMessage(buildKimiFileUrl(FILE_ID, IMAGE_FALLBACK_PATH));
+
+      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_TAG });
+      expect(firstPart(out)).toEqual({ type: 'image_url', imageUrl: { url: PNG_DATA_URL } });
+      expect(gets).toBe(reads);
+    },
+  );
+});
+
+describe('AgentMediaResolverService session-canonical display path', () => {
+  let sessionDir: string;
+
+  beforeEach(async () => {
+    sessionDir = await mkdtemp(join(tmpdir(), 'media-resolver-'));
+  });
+
+  afterEach(async () => {
+    await rm(sessionDir, { recursive: true, force: true });
+  });
+
+  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;
+  }
+
+  it.each([
+    {
+      name: 'refreshes a claimed persisted tag to the canonical path and drops the reference',
+      canonical: true,
+    },
+    {
+      name: 'leaves a claimed persisted tag untouched when no canonical file exists',
+      canonical: false,
+    },
+  ])('$name', async ({ canonical: plant }) => {
+    const canonical = plant ? await plantCanonical(FILE_ID, '.png', PNG_BYTES) : undefined;
+    const message = imageMessage(
+      buildKimiFileUrl(FILE_ID, IMAGE_FALLBACK_PATH),
+      imagePathTagPart(IMAGE_FALLBACK_PATH),
+    );
+
+    const out = await resolver(new Map(), sessionDir).resolve([message], requester({ imageIn: false }));
+
+    expect(out[0]!.content).toEqual([
+      { type: 'text', text: `<image path="${canonical ?? IMAGE_FALLBACK_PATH}"></image>` },
+    ]);
+  });
+
+  it('refreshes a memoized video tag path when the canonical copy appears', async () => {
+    const res = resolver(new Map(), sessionDir);
+    const message = videoMessage(buildKimiFileUrl(FILE_ID, FALLBACK_PATH));
+    const req = requester({ videoIn: false });
+
+    const first = await res.resolve([message], req);
+    expect(firstPart(first)).toEqual({ type: 'text', text: VIDEO_TAG });
+
+    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('drops a claimed video reference, refreshing its tag instead of emitting a second one', 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, FALLBACK_PATH) } },
+      ],
+    };
+    const out = await resolver(new Map(), sessionDir).resolve(
+      [message],
+      requester({ videoIn: false }),
+    );
+    expect(out[0]!.content).toEqual([
+      { type: 'text', text: `<video path="${canonical}"></video>` },
+    ]);
+  });
+
+  it('drops a claimed video reference whose degrade was memoized from an earlier bare resolve', 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, FALLBACK_PATH) } },
+      ],
+    };
+    const first = await res.resolve([bare], req);
+    expect(firstPart(first)).toEqual({ type: 'text', text: VIDEO_TAG });
+
+    const paired: Message = {
+      role: 'user',
+      toolCalls: [],
+      content: [
+        { type: 'text', text: VIDEO_TAG },
+        { type: 'video_url', videoUrl: { url: buildKimiFileUrl(FILE_ID, FALLBACK_PATH) } },
+      ],
+    };
+    const second = await res.resolve([paired], req);
+    expect(second[0]!.content).toEqual([{ type: 'text', text: VIDEO_TAG }]);
+  });
+});
+
+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, IMAGE_FALLBACK_PATH))],
+      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 0000000000..982dbbb2b2
--- /dev/null
+++ b/packages/agent-core-v2/test/agent/media/sessionMediaStore.test.ts
@@ -0,0 +1,223 @@
+/**
+ * Scenario: session-canonical media persists through the byte-storage boundary.
+ */
+
+import { mkdir, mkdtemp, readdir, readFile, rm, stat, 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 { IBootstrapService } from '#/app/bootstrap/bootstrap';
+import { FileStorageService } from '#/persistence/backends/node-fs/fileStorageService';
+import { InMemoryStorageService } from '#/persistence/backends/memory/inMemoryStorageService';
+import { IFileSystemStorageService } from '#/persistence/interface/storage';
+import { ISessionContext, makeSessionContext } from '#/session/sessionContext/sessionContext';
+
+import { stubBootstrap } from '../../app/bootstrap/stubs';
+
+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(IBootstrapService, stubBootstrap(homeDir));
+        reg.defineInstance(IFileSystemStorageService, new FileStorageService(homeDir));
+        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('materializes at the shared cache fallback through the storage boundary', async () => {
+    const target = await store.materializeFallback(input());
+    expect(target).toBe(join(homeDir, 'cache', '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 hint, then the name, then the MIME fallback', async () => {
+    expect(await store.materialize(input({ hintPath: '/elsewhere/x.mov' }))).toBe(
+      pathFor('f_1', '.mov'),
+    );
+    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 () => {
+    const target = await store.materialize(input());
+    await expect(store.read('f_1', target)).resolves.toEqual({
+      data: BYTES,
+      name: 'f_1.mp4',
+    });
+  });
+
+  it('resolves the display path to the canonical copy, else the hint, else undefined', async () => {
+    const target = await store.materialize(input());
+    await expect(store.resolveDisplayPath('f_1', '/stale/elsewhere.mp4')).resolves.toBe(target);
+    await expect(store.resolveDisplayPath('f_missing', '/hint/x.mp4')).resolves.toBe('/hint/x.mp4');
+    await expect(store.resolveDisplayPath('f_missing', undefined)).resolves.toBeUndefined();
+    await expect(store.resolveDisplayPath('f_missing', '')).resolves.toBeUndefined();
+  });
+
+  it('probes the extensionless canonical location for an extensionless hint', 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', '/stale/noext')).resolves.toBe(extless);
+  });
+
+  it('treats a hint already equal to the canonical path as-is', async () => {
+    const canonical = pathFor('f_1', '.mp4');
+    await expect(store.resolveDisplayPath('f_1', canonical)).resolves.toBe(canonical);
+    await expect(stat(canonical)).rejects.toThrow();
+  });
+
+  it('never turns a non-upload id into a storage key (path traversal guard)', async () => {
+    // A crafted daemon reference (`kimi-file://../../…?path=…`) 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, 'a.png')).resolves.toBeUndefined();
+    await expect(store.read(evil)).resolves.toBeUndefined();
+    await expect(store.materialize(input({ fileId: evil }))).resolves.toBeUndefined();
+    // The display path falls back to the caller's own hint, like a missing copy.
+    await expect(store.resolveDisplayPath(evil, '/hint/x.png')).resolves.toBe('/hint/x.png');
+    // 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(IBootstrapService, stubBootstrap('/unused-home'));
+      reg.defineInstance(IFileSystemStorageService, new InMemoryStorageService());
+      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);
+  disposables.dispose();
+});
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 ded03736de..0000000000
--- 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/promptService.test.ts b/packages/agent-core-v2/test/agent/prompt/promptService.test.ts
index 7336d31c91..adad5eba62 100644
--- a/packages/agent-core-v2/test/agent/prompt/promptService.test.ts
+++ b/packages/agent-core-v2/test/agent/prompt/promptService.test.ts
@@ -6,6 +6,11 @@
  * 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';
@@ -14,38 +19,85 @@ 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 { IAgentLoopService, type Step, type StepAssignment } from '#/agent/loop/loop';
+import type { StepRequest } from '#/agent/loop/stepRequest';
+import { buildDaemonFileUrl, foldMediaPathTagRefs } from '#/agent/media/mediaRef';
+import { ISessionMediaStore } from '#/agent/media/sessionMediaStore';
+import { SessionMediaStoreService } from '#/agent/media/sessionMediaStoreService';
 import { IAgentPromptService } from '#/agent/prompt/prompt';
 import { AgentPromptService } from '#/agent/prompt/promptService';
 import { IAgentSystemReminderService } from '#/agent/systemReminder/systemReminder';
 import { AgentSystemReminderService } from '#/agent/systemReminder/systemReminderService';
 import { IAgentToolExecutorService } from '#/agent/toolExecutor/toolExecutor';
+import { IBootstrapService } from '#/app/bootstrap/bootstrap';
 import { IEventBus } from '#/app/event/eventBus';
 import { EventBusService } from '#/app/event/eventBusService';
+import { type GetResult, IFileService } from '#/app/file/fileService';
 import { ErrorCodes, Error2 } from '#/errors';
 import { createHooks } from '#/hooks';
+import type { ContentPart } from '#/kosong/contract/message';
 import { IWireService } from '#/wire/wire';
+import { FileStorageService } from '#/persistence/backends/node-fs/fileStorageService';
+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';
 
 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 }>,
+): 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: 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 }>;
+    fullCompaction?: IAgentFullCompactionService;
+  } = {},
+) {
   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);
@@ -56,6 +108,17 @@ function harness() {
       reg.defineInstance(IAgentFullCompactionService, fullCompaction);
       reg.define(IEventBus, EventBusService);
       reg.define(IAgentSystemReminderService, AgentSystemReminderService);
+      reg.defineInstance(IFileService, stubFileService(opts.files ?? new Map()));
+      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(ISessionMediaStore, SessionMediaStoreService);
       reg.define(IAgentPromptService, AgentPromptService);
     }
   });
@@ -71,6 +134,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') });
@@ -121,6 +192,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' } });
@@ -194,3 +276,365 @@ describe('AgentPromptService', () => {
     ).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, opts.path);
+    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 expectMediaPair(
+    content: readonly ContentPart[],
+    fileId: string,
+    target: string,
+    kind: 'image' | 'video' = 'image',
+  ): void {
+    expect(content).toEqual([
+      { type: 'text', text: `<${kind} path="${target}"></${kind}>` },
+      kind === 'video'
+        ? { type: 'video_url', videoUrl: { url: buildDaemonFileUrl(fileId, target) } }
+        : { type: 'image_url', imageUrl: { url: buildDaemonFileUrl(fileId, target) } },
+    ]);
+  }
+
+  it('materializes a bare daemon reference into the session media dir and authors its paired tag', 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);
+    expectMediaPair(handle.message.content, 'f_1', target);
+    const fold = foldMediaPathTagRefs(handle.message.content);
+    expect(fold.parts).toEqual([
+      { type: 'image_url', imageUrl: { url: buildDaemonFileUrl('f_1', target) } },
+    ]);
+    expect(fold.media).toEqual([{ kind: 'image', ref: { fileId: 'f_1', path: target }, path: target }]);
+  });
+
+  it('authors a paired video tag for a bare video daemon reference', 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);
+    expectMediaPair(handle.message.content, 'f_v', target, 'video');
+  });
+
+  it('falls back to the shared cache dir 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-fallback', fileId: 'f_1' });
+    await handle.launched;
+
+    const target = join(homeDir, 'cache', 'f_1.png');
+    expect(await readFile(target)).toEqual(PNG_BYTES);
+    expectMediaPair(handle.message.content, 'f_1', target);
+  });
+
+  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');
+    expect(prompt.list()).toEqual({ active: undefined, pending: [] });
+    open();
+    await expect(handle.launched).resolves.toBeDefined();
+  });
+
+  it('rewrites a client-cache tag+reference pair to 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 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');
+    expectMediaPair(handle.message.content, 'f_1', target);
+  });
+
+  it('keeps an already-normalized pair 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) });
+
+    expectMediaPair(first.message.content, 'f_1', target);
+    expectMediaPair(second.message.content, 'f_1', target);
+    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 url = buildDaemonFileUrl('f_missing', '/client-cache/x.png');
+
+    const handle = await enqueueMedia(prompt, { fileId: 'f_missing', path: '/client-cache/x.png' });
+
+    expect(handle.message.content).toEqual([{ type: 'image_url', imageUrl: { url } }]);
+  });
+
+  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');
+    expect(prompt.list().pending.map((item) => item.id)).toEqual(['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('normalizes 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');
+    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', target) } },
+    ]);
+  });
+
+  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/agent/rpc/prompt-metadata.test.ts b/packages/agent-core-v2/test/agent/rpc/prompt-metadata.test.ts
index 7e1527c443..2828eba023 100644
--- a/packages/agent-core-v2/test/agent/rpc/prompt-metadata.test.ts
+++ b/packages/agent-core-v2/test/agent/rpc/prompt-metadata.test.ts
@@ -52,4 +52,31 @@ describe('promptMetadataTextFromPayload', () => {
     expect(text).not.toContain('<system>');
     expect(text).not.toContain('Image compressed');
   });
+
+  it('keeps an upload <image path> tag out of the metadata text', () => {
+    // The upload pair (`<image path>` tag + daemon-ref image part) folds to
+    // the `[image]` placeholder — the materialization path must never leak
+    // into titles / lastPrompt.
+    const text = promptMetadataTextFromPayload({
+      input: [
+        { 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 as text when no ref pairs with it', () => {
+    // Without a paired daemon ref the tag is not machine markup the fold may
+    // claim: it stays user-visible text.
+    const text = promptMetadataTextFromPayload({
+      input: [
+        { type: 'text', text: '<image path="/cache/f_123.png">' },
+        { type: 'text', text: 'describe it' },
+      ],
+    });
+    expect(text).toBe('<image path="/cache/f_123.png"> describe it');
+  });
 });
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 f56dbe6541..e7c430cdf9 100644
--- a/packages/agent-core-v2/test/app/config/config.test.ts
+++ b/packages/agent-core-v2/test/app/config/config.test.ts
@@ -322,7 +322,7 @@ describe('Agent config', () => {
     });
     expect(await ctx.untilApproval(true)).toMatchInlineSnapshot(`
       [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>" }
@@ -404,7 +404,7 @@ describe('Agent config', () => {
       [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] 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 b112e09b74..a280149902 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 2a3926cbca..5205a19462 100644
--- a/packages/agent-core-v2/test/app/gateway/gateway.test.ts
+++ b/packages/agent-core-v2/test/app/gateway/gateway.test.ts
@@ -56,6 +56,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 909ec4c82b..8dc9c072ab 100644
--- a/packages/agent-core-v2/test/features/plan/plan.test.ts
+++ b/packages/agent-core-v2/test/features/plan/plan.test.ts
@@ -715,7 +715,7 @@ describe('Plan service', () => {
         [wire] plan_mode.enter             { "id": "test-plan", "time": "<time>" }
         [emit] agent.status.updated        { "planMode": true }
         [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>" }
@@ -791,7 +791,7 @@ describe('Plan service', () => {
         [wire] plan_mode.enter             { "id": "test-plan", "time": "<time>" }
         [emit] agent.status.updated        { "planMode": true }
         [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/persistence/backends/node-fs/appendLogStore.test.ts b/packages/agent-core-v2/test/persistence/backends/node-fs/appendLogStore.test.ts
index 52d7eaadaa..390241b5d3 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 e566431514..dbe8156bd7 100644
--- a/packages/agent-core-v2/test/session/agentLifecycle/agentLifecycle.test.ts
+++ b/packages/agent-core-v2/test/session/agentLifecycle/agentLifecycle.test.ts
@@ -54,6 +54,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';
@@ -163,6 +164,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[];
 
@@ -293,6 +295,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: () => {},
@@ -400,6 +407,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 2bd1f4e9e3..605f092ec7 100644
--- a/packages/agent-core-v2/test/tool/tool.test.ts
+++ b/packages/agent-core-v2/test/tool/tool.test.ts
@@ -3167,7 +3167,7 @@ describe('Agent tools', () => {
         [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] 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>" }
@@ -3237,7 +3237,7 @@ describe('Agent tools', () => {
         [wire] tools.unregister_user_tool   { "name": "Lookup", "time": "<time>" }
         [emit] prompt.completed             { "promptId": "<msg-1>", "finishedAt": "<time>", "reason": "completed" }
         [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/agent-core-v2/test/workspace/sessionLifecycle/sessionLifecycle.test.ts b/packages/agent-core-v2/test/workspace/sessionLifecycle/sessionLifecycle.test.ts
index 12ff392942..6a2f5db13b 100644
--- a/packages/agent-core-v2/test/workspace/sessionLifecycle/sessionLifecycle.test.ts
+++ b/packages/agent-core-v2/test/workspace/sessionLifecycle/sessionLifecycle.test.ts
@@ -1489,7 +1489,7 @@ describe('SessionLifecycleService', () => {
   });
 
   describe('fork session state', () => {
-    it('copies blobs, plans, background tasks, and media originals into the fork', async () => {
+    it('copies blobs, plans, background tasks, media originals, and session media into the fork', async () => {
       const root = await makeTmpRoot();
       const svc = await build([
         stubPair(IBootstrapService, tmpBootstrapStub(root)),
@@ -1506,6 +1506,8 @@ describe('SessionLifecycleService', () => {
       await writeFile(join(srcDir, 'agents', 'main', 'tasks', 'bash-1', 'output.log'), 'out');
       await mkdir(join(srcDir, 'media-originals'), { recursive: true });
       await writeFile(join(srcDir, 'media-originals', 'x.png'), 'png');
+      await mkdir(join(srcDir, 'media'), { recursive: true });
+      await writeFile(join(srcDir, 'media', 'f_1.mp4'), 'mp4');
       await writeFile(join(srcDir, 'state.json'), '{"source":true}');
       await writeFile(join(srcDir, 'agents', 'main', 'wire.jsonl'), '{"type":"metadata"}\n');
       await mkdir(join(srcDir, 'logs'), { recursive: true });
@@ -1529,6 +1531,7 @@ describe('SessionLifecycleService', () => {
       await expect(readFile(join(dstDir, 'media-originals', 'x.png'), 'utf8')).resolves.toBe(
         'png',
       );
+      await expect(readFile(join(dstDir, 'media', 'f_1.mp4'), 'utf8')).resolves.toBe('mp4');
       await expect(stat(join(dstDir, 'state.json'))).rejects.toThrow();
       await expect(stat(join(dstDir, 'agents', 'main', 'wire.jsonl'))).rejects.toThrow();
       await expect(stat(join(dstDir, 'logs'))).rejects.toThrow();
diff --git a/packages/kap-server/src/lib/promptMedia.ts b/packages/kap-server/src/lib/promptMedia.ts
index 2895cecaf3..3241c89b35 100644
--- a/packages/kap-server/src/lib/promptMedia.ts
+++ b/packages/kap-server/src/lib/promptMedia.ts
@@ -5,10 +5,11 @@
  * Three 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.
+ *   2. `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.
  *   3. `contentToCoreParts` — project the resolved wire content onto engine
  *      `ContentPart`s.
  *
@@ -19,11 +20,12 @@
 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,
@@ -51,15 +53,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
@@ -109,18 +102,40 @@ export interface ResolvePromptMediaOptions {
   readonly telemetry?: ITelemetryService;
 }
 
+export interface PromptMediaPreparation {
+  readonly content: WireContent;
+  /**
+   * Delete the daemon uploads this preparation created (the compressed
+   * re-save). Failure rollback only: once a submission reaches the engine,
+   * client read models project these upload ids, so they must stay
+   * retrievable like any client upload.
+   */
+  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
+ * the daemon uploads the preparation created (the failure path only).
  */
 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 +158,228 @@ 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 authors the paired
+        // `<image path>` tag, then 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 an ordinary upload (no
+        // expiry): read models project its id, so it must keep serving bytes
+        // for the session's history.
+        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 (the outer catch), a successful submission
+          // keeps it alive.
+          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 and authors the paired `<video path>` tag, 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/events-zod.ts b/packages/kap-server/src/protocol/events-zod.ts
index a99558cfb7..09645d37dc 100644
--- a/packages/kap-server/src/protocol/events-zod.ts
+++ b/packages/kap-server/src/protocol/events-zod.ts
@@ -676,6 +676,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/rest-prompt.ts b/packages/kap-server/src/protocol/rest-prompt.ts
index b04a2fe78a..b1110520ae 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/prompts.ts b/packages/kap-server/src/routes/prompts.ts
index 4f26880f5d..bc8a8459d0 100644
--- a/packages/kap-server/src/routes/prompts.ts
+++ b/packages/kap-server/src/routes/prompts.ts
@@ -18,10 +18,8 @@ import {
   IEventService,
   IFileService,
   ISessionMetadata,
-  parseKimiFileUrl,
   promptMetadataTextFromContentParts,
   ProfileError,
-  type ContentPart,
   type PromptHandle,
   type PromptQueueSnapshot,
   ISessionContext,
@@ -36,6 +34,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,7 +42,6 @@ import {
   promptSteerResultSchema,
   promptSubmissionSchema,
   promptSubmitResultSchema,
-  type PromptSubmission,
 } from '../protocol/rest-prompt';
 import { z } from 'zod';
 
@@ -52,6 +50,7 @@ import {
   assertPromptFileRefs,
   contentToCoreParts,
   resolvePromptMediaFiles,
+  type PromptMediaPreparation,
 } from '../lib/promptMedia';
 import { requestLog } from '../lib/requestLog';
 import { defineRoute } from '../middleware/defineRoute';
@@ -208,6 +207,8 @@ export function registerPromptsRoutes(app: PromptRouteHost, core: Scope): void {
     },
     async (req, reply) => {
       const { session_id } = req.params;
+      let preparedMedia: PromptMediaPreparation | 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`
@@ -218,12 +219,13 @@ export function registerPromptsRoutes(app: PromptRouteHost, core: Scope): void {
 
         // 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
+        // and uploaded images are carried into context as bare internal
+        // `kimi-file://` references; the engine's prompt intake materializes
+        // the session copy, authors the paired media-path tag, 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 +243,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;
@@ -276,14 +279,23 @@ export function registerPromptsRoutes(app: PromptRouteHost, core: Scope): void {
           eventService: core.accessor.get(IEventService),
           sessionId: session_id,
         }, promptMetadataTextFromContentParts(parts));
-        const handle = await resolved.prompt.enqueue({ message: {
-          role: 'user',
-          content: parts,
-          toolCalls: [],
-          origin: { kind: 'user' },
-        } });
+        const handle = await resolved.prompt.enqueue({
+          id: req.body.prompt_id,
+          message: {
+            role: 'user',
+            content: parts,
+            toolCalls: [],
+            origin: { kind: 'user' },
+          },
+        });
+        enqueued = true;
         reply.send(okEnvelope(projectPromptHandle(handle), req.id));
       } catch (error) {
+        // A submission that failed before the engine took the prompt projected
+        // no upload ids to the client — roll back the uploads the preparation
+        // created. After a successful enqueue the compressed re-save must stay
+        // retrievable: read models project its id.
+        if (!enqueued) await preparedMedia?.discard();
         sendMappedError(reply, req, error);
       }
     },
@@ -379,43 +391,20 @@ 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 folds the
+  // upload pair (`<media path>` tag + daemon-ref media part) into the single
+  // media part, mirroring the message projection: the tag is machine markup
+  // and would otherwise leak the materialization path to REST callers while
+  // rendering the same upload twice.
   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(
   reply: { send(payload: unknown): unknown },
   req: { id: string },
diff --git a/packages/kap-server/src/routes/skills.ts b/packages/kap-server/src/routes/skills.ts
index f2f56de965..77bbbef330 100644
--- a/packages/kap-server/src/routes/skills.ts
+++ b/packages/kap-server/src/routes/skills.ts
@@ -121,6 +121,7 @@ import {
   assertPromptFileRefs,
   contentToCoreParts,
   resolvePromptMediaFiles,
+  type PromptMediaPreparation,
 } from '../lib/promptMedia';
 import { requestLog } from '../lib/requestLog';
 import { defineRoute } from '../middleware/defineRoute';
@@ -307,6 +308,8 @@ export function registerSkillsRoutes(app: SkillsRouteHost, core: Scope): void {
         return;
       }
 
+      let preparedMedia: PromptMediaPreparation | undefined;
+      let activated = false;
       try {
         // Attachments run through the same edge pipeline as prompt uploads
         // (validate → materialize → convert) BEFORE the activation starts, so
@@ -334,7 +337,7 @@ export function registerSkillsRoutes(app: SkillsRouteHost, core: Scope): void {
           await assertPromptFileRefs(attachments, core.accessor.get(IFileService));
           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,
@@ -344,12 +347,13 @@ 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);
         await agent.accessor
           .get(IAgentSkillService)
           .activate({ name: parsed.id, args: req.body.args, content: attachmentParts });
+        activated = true;
         // Keep the easy-title behavior of the native RPC / TUI path: a first
         // `/<skill>` message titles the session (same as routes/prompts.ts).
         await applyPromptMetadataUpdate(
@@ -363,6 +367,9 @@ export function registerSkillsRoutes(app: SkillsRouteHost, core: Scope): void {
         requestLog(req)?.info({ session_id, skill_name: parsed.id }, 'skill activated');
         reply.send(okEnvelope({ activated: true, skill_name: parsed.id }, req.id));
       } catch (err) {
+        // Same rollback contract as the prompt route: before the engine took
+        // the activation, no upload id was projected — discard the re-saves.
+        if (!activated) 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 6734f393c3..95b95d9bf2 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 d3c7598d26..baa93145bf 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 { foldMediaPathTagRefs, type ContentPart } from '@moonshot-ai/agent-core-v2';
+
 export interface ExtractedWireMessage {
   readonly role: 'user' | 'assistant';
   readonly text: string;
@@ -153,18 +155,46 @@ interface ContentPartLike {
   readonly text?: unknown;
 }
 
+/**
+ * Coerce one raw JSON part into a fold-safe `ContentPart`: well-formed parts
+ * pass through, anything malformed becomes an inert empty text part (indices
+ * — and therefore pairing adjacency — are preserved). The engine's fold is
+ * not defensive against malformed holders, and wire lines are tolerated to be
+ * corrupt.
+ */
+function foldSafePart(part: unknown): ContentPart {
+  if (part === null || typeof part !== 'object') return { type: 'text', text: '' };
+  const p = part as ContentPartLike & {
+    readonly imageUrl?: unknown;
+    readonly videoUrl?: unknown;
+  };
+  if (p.type === 'text') {
+    return { type: 'text', text: typeof p.text === 'string' ? p.text : '' };
+  }
+  if (p.type === 'image_url' || p.type === 'video_url') {
+    const holder = p.type === 'image_url' ? p.imageUrl : p.videoUrl;
+    const url =
+      holder !== null && typeof holder === 'object'
+        ? (holder as { readonly url?: unknown }).url
+        : undefined;
+    if (typeof url !== 'string') return { type: 'text', text: '' };
+  }
+  return part as ContentPart;
+}
+
+/**
+ * The user-visible text of a persisted message: text parts concatenated, with
+ * the upload pair (`<media path>` tag + daemon-ref media part) folded the same
+ * way as every other read model — a claimed tag is machine markup (and carries
+ * the materialization path), so it must never reach the index. An unpaired
+ * standalone tag stays as text.
+ */
 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;
-    }
+  const parts = (content as readonly unknown[]).map(foldSafePart);
+  for (const part of foldMediaPathTagRefs(parts).parts) {
+    if (part.type === 'text') 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 ad846f01ee..56a8adbd6c 100644
--- a/packages/kap-server/src/services/messages/messageProjection.ts
+++ b/packages/kap-server/src/services/messages/messageProjection.ts
@@ -12,15 +12,21 @@
  * 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>?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 upload persists as the pair `<media path>` tag text part +
+ * `kimi-file://` media part (`foldMediaPathTagRefs`): the pair folds into the
+ * single media part — the tag is machine markup and must not reach the wire
+ * as a text part (clients would render one upload twice). Assistant output
+ * passes through verbatim.
  */
 
-import { parseKimiFileUrl, type ContextMessage } from '@moonshot-ai/agent-core-v2';
+import { foldMediaPathTagRefs, parseDaemonFileUrl, type ContentPart, type ContextMessage } from '@moonshot-ai/agent-core-v2';
 
 import type { Message, MessageContent, MessageRole, ToolUseContent } from '../../protocol/message';
 
@@ -43,15 +49,18 @@ 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
+      // `kimi-file://<id>?path=…` reference becomes the upload it came from.
+      const ref = parseDaemonFileUrl(part.imageUrl.url);
+      return ref !== undefined
+        ? { type: 'image', source: { kind: 'file', 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: 'url', url: part.videoUrl.url, id: part.videoUrl.id } };
@@ -86,7 +95,10 @@ function buildProtocolContent(msg: ContextMessage): MessageContent[] {
     return [part];
   }
 
-  const base = msg.content.map((p) => mapContentPart(p));
+  // User messages fold the upload pair (`<media path>` tag + daemon-ref media
+  // part) into the single media part; assistant output passes through verbatim.
+  const content = msg.role === 'user' ? foldMediaPathTagRefs(msg.content).parts : msg.content;
+  const base = content.map((p) => mapContentPart(p));
 
   if (msg.role === 'assistant' && msg.toolCalls.length > 0) {
     for (const call of msg.toolCalls) {
@@ -111,6 +123,44 @@ 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 the
+ * upload pair (`<media path>` tag + daemon-ref media part) folds into the
+ * single media part and a daemon reference projects back to
+ * `{ kind: 'file', file_id }`: neither the internal `kimi-file://` URL nor
+ * the materialization path ever reaches a client.
+ */
+export function projectPromptContentParts(content: readonly ContentPart[]): MessageContent[] {
+  const parts: MessageContent[] = [];
+  for (const part of foldMediaPathTagRefs(content).parts) {
+    if (part.type === 'text') parts.push({ type: 'text', text: part.text });
+    else if (part.type === 'image_url') {
+      const ref = parseDaemonFileUrl(part.imageUrl.url);
+      if (ref !== undefined) {
+        parts.push({ type: 'image', source: { kind: 'file', file_id: ref.fileId } });
+        continue;
+      }
+      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 ref = parseDaemonFileUrl(part.videoUrl.url);
+      if (ref !== undefined) {
+        parts.push({ type: 'video', source: { kind: 'file', file_id: ref.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;
+}
+
 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 e32e6b7b04..9cb01e2555 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 a54b21b158..74b3eeb074 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 paired `<media path>`
+ *     tag already folded away 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,26 @@ 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}/*`,
+          name: input.name,
+          source: { kind: 'file', fileId: input.fileId },
+        };
+        ops.push({ op: 'attachment.upsert', attachment });
+        attachmentIds.push(attachment.attachmentId);
+      }
+    }
     this.currentTurn = {
       kind: 'turn',
       turnId,
@@ -310,12 +339,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 +366,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 +381,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 +1345,15 @@ export class AgentTranscriptProjector {
    */
   private onPromptSteered(event: PromptSteeredEvent): TranscriptOperation[] {
     const ops: TranscriptOperation[] = [];
+    // The event carries raw engine content parts (daemon refs with
+    // `kimi-file://…?path=<abs>` plus the paired `<media path>` tag); the
+    // entity stores the wire-projected form, so the internal URL and the
+    // materialization path never reach transcript 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 581821f230..9e8eeb3d9a 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/ws/v1/sessionEventBroadcaster.ts b/packages/kap-server/src/transport/ws/v1/sessionEventBroadcaster.ts
index 38f151e7d9..aaccb33fce 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';
@@ -1128,7 +1129,34 @@ 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: daemon references carry
+      // `kimi-file://…?path=<abs>` and a paired `<media path>` tag text part.
+      // The pair folds into one `{kind:'file'}` part, so neither the internal
+      // URL nor the materialization path 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/mediaRefParity.test.ts b/packages/kap-server/test/mediaRefParity.test.ts
new file mode 100644
index 0000000000..a795b56966
--- /dev/null
+++ b/packages/kap-server/test/mediaRefParity.test.ts
@@ -0,0 +1,147 @@
+/**
+ * Parity pin for the media tag+ref pairing algorithm, 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 fold). The two
+ * header comments say "keep the two in sync" — this test is what actually
+ * enforces it: both implementations must produce the identical pairing for
+ * every fixture below, so a rule change landed on only one side fails here
+ * instead of drifting the live projection apart from the cold rebuild.
+ */
+
+import { describe, expect, it } from 'vitest';
+
+import { pairMediaPathTagRefs as enginePair } from '@moonshot-ai/agent-core-v2';
+import {
+  pairMediaPathTagRefs as mirrorPair,
+  type MediaRefPairingPart,
+} from '@moonshot-ai/transcript';
+import type { ContentPart } from '@moonshot-ai/agent-core-v2/kosong/contract/message';
+
+interface PairingLike {
+  readonly claimedTagIndices: ReadonlySet<number>;
+  readonly claimedPathByRefIndex: ReadonlyMap<number, string>;
+  readonly claimingRefByTagIndex: ReadonlyMap<number, number>;
+}
+
+function normalize(pairing: PairingLike): { tags: number[]; paths: [number, string][]; refs: [number, number][] } {
+  return {
+    tags: [...pairing.claimedTagIndices].toSorted((a, b) => a - b),
+    paths: [...pairing.claimedPathByRefIndex.entries()].toSorted((a, b) => a[0] - b[0]),
+    refs: [...pairing.claimingRefByTagIndex.entries()].toSorted((a, b) => a[0] - b[0]),
+  };
+}
+
+const text = (value: string): MediaRefPairingPart => ({ type: 'text', text: value });
+const imageRef = (url: string): MediaRefPairingPart => ({ type: 'image_url', imageUrl: { url } });
+const videoRef = (url: string): MediaRefPairingPart => ({ type: 'video_url', videoUrl: { url } });
+const REF_IMAGE = 'kimi-file://f_1?path=%2Fcache%2Fshot.png';
+const REF_IMAGE_2 = 'kimi-file://f_2?path=%2Fcache%2Fshot.png';
+const REF_VIDEO = 'kimi-file://f_3?path=%2Fcache%2Fclip.mp4';
+
+const FIXTURES: ReadonlyArray<{ readonly name: string; readonly parts: readonly MediaRefPairingPart[] }> = [
+  // The edge-emitted pair, tag before ref.
+  { name: 'tag before ref pairs', parts: [text('<image path="/cache/shot.png"></image>'), imageRef(REF_IMAGE)] },
+  // Persisted history also has ref before tag.
+  { name: 'ref before tag pairs', parts: [imageRef(REF_IMAGE), text('<image path="/cache/shot.png"></image>')] },
+  // Kind mismatch never pairs.
+  { name: 'kind mismatch does not pair', parts: [text('<video path="/cache/shot.png"></video>'), imageRef(REF_IMAGE)] },
+  // A `file` tag matches either ref kind.
+  { name: 'file tag matches a video ref', parts: [text('<file path="/cache/clip.mp4"></file>'), videoRef(REF_VIDEO)] },
+  // Path mismatch never pairs.
+  { name: 'path mismatch does not pair', parts: [text('<image path="/cache/other.png"></image>'), imageRef(REF_IMAGE)] },
+  // A reference without a path can never pair.
+  { name: 'pathless ref does not pair', parts: [text('<image path="/cache/shot.png"></image>'), imageRef('kimi-file://f_1')] },
+  // A tag embedded in user text is not a standalone tag.
+  { name: 'embedded tag does not pair', parts: [text('open <image path="/cache/shot.png"></image> please'), imageRef(REF_IMAGE)] },
+  // Single claim, references check the part before them first.
+  {
+    name: 'two tags one ref: the leading tag is claimed',
+    parts: [
+      text('<image path="/cache/shot.png"></image>'),
+      imageRef(REF_IMAGE),
+      text('<image path="/cache/shot.png"></image>'),
+    ],
+  },
+  {
+    name: 'two refs one tag: the earlier ref claims it',
+    parts: [imageRef(REF_IMAGE), text('<image path="/cache/shot.png"></image>'), imageRef(REF_IMAGE_2)],
+  },
+  // Extra attributes and a missing closing tag are tolerated.
+  { name: 'extra attributes and missing closing tag', parts: [text('<image content_type="image/png" path="/cache/shot.png">'), imageRef(REF_IMAGE)] },
+  // Escaped path characters round-trip.
+  {
+    name: 'escaped path characters round-trip',
+    parts: [
+      text('<image path="/cache/a &amp; &quot;b&quot; &lt;c&gt;.png"></image>'),
+      imageRef('kimi-file://f_1?path=%2Fcache%2Fa%20%26%20%22b%22%20%3Cc%3E.png'),
+    ],
+  },
+  // A non-daemon url is not a reference.
+  { name: 'non-daemon url does not pair', parts: [text('<image path="/cache/shot.png"></image>'), imageRef('https://example.com/shot.png')] },
+  // An audio tag does not pair with an image ref.
+  { name: 'audio tag does not pair with an image ref', parts: [text('<audio path="/cache/shot.png"></audio>'), imageRef(REF_IMAGE)] },
+  // Surrounding whitespace is tolerated for the standalone tag.
+  { name: 'whitespace around a standalone tag', parts: [text('  <image path="/cache/shot.png"></image>\n'), imageRef(REF_IMAGE)] },
+  // An unrelated part between tag and ref breaks adjacency.
+  {
+    name: 'an intervening part breaks adjacency',
+    parts: [text('<image path="/cache/shot.png"></image>'), text('caption'), imageRef(REF_IMAGE)],
+  },
+  // Same path on different fileIds, interleaved: each tag claims its own ref
+  // (the claim mapping must not be recovered by path equality).
+  {
+    name: 'same-path interleaved pairs claim their own ref',
+    parts: [
+      text('<image path="/cache/shot.png"></image>'),
+      imageRef(REF_IMAGE),
+      text('<image path="/cache/shot.png"></image>'),
+      imageRef(REF_IMAGE_2),
+    ],
+  },
+];
+
+describe('media tag+ref pairing parity (engine vs transcript mirror)', () => {
+  FIXTURES.forEach(({ name, parts }) => {
+    it(name, () => {
+      const engine = normalize(enginePair(parts as unknown as ContentPart[]));
+      const mirror = normalize(mirrorPair(parts));
+      expect(mirror).toEqual(engine);
+    });
+  });
+
+  it('pins the expected claims, not just cross-implementation equality', () => {
+    const byName = (name: string): readonly MediaRefPairingPart[] => {
+      const fixture = FIXTURES.find((f) => f.name === name);
+      if (fixture === undefined) throw new Error(`fixture not found: ${name}`);
+      return fixture.parts;
+    };
+    expect(normalize(enginePair(byName('tag before ref pairs') as unknown as ContentPart[]))).toEqual({
+      tags: [0],
+      paths: [[1, '/cache/shot.png']],
+      refs: [[0, 1]],
+    });
+    expect(normalize(enginePair(byName('two refs one tag: the earlier ref claims it') as unknown as ContentPart[]))).toEqual({
+      tags: [1],
+      paths: [[0, '/cache/shot.png']],
+      refs: [[1, 0]],
+    });
+    expect(normalize(enginePair(byName('escaped path characters round-trip') as unknown as ContentPart[]))).toEqual({
+      tags: [0],
+      paths: [[1, '/cache/a & "b" <c>.png']],
+      refs: [[0, 1]],
+    });
+    expect(normalize(enginePair(byName('same-path interleaved pairs claim their own ref') as unknown as ContentPart[]))).toEqual({
+      tags: [0, 2],
+      paths: [
+        [1, '/cache/shot.png'],
+        [3, '/cache/shot.png'],
+      ],
+      refs: [
+        [0, 1],
+        [2, 3],
+      ],
+    });
+  });
+});
diff --git a/packages/kap-server/test/prompts.test.ts b/packages/kap-server/test/prompts.test.ts
index 859c66148c..2f2ef37df7 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';
@@ -8,10 +8,13 @@ import {
   IAgentLifecycleService,
   IAgentProfileService,
   IAgentToolPolicyService,
+  IBootstrapService,
+  IFileService,
+  ISessionContext,
   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';
@@ -128,6 +131,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;
@@ -215,6 +243,19 @@ 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 stale file reference without creating the agent or mutating the model', async () => {
     const id = await createSession(home as string);
     const session = getLiveSessionById(server!.core.accessor, id);
@@ -294,36 +335,30 @@ describe('server-v2 /api/v1 prompts', () => {
     });
 
     // 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);
+    // 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 `<image path>` tag
+    // folded into the media part instead of reaching the wire.
+    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);
@@ -331,15 +366,144 @@ 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('file');
+    const finalFileId = image.source.file_id;
+    expect(finalFileId).not.toBe(uploaded.id);
+
+    // The folded-away <image path> tag named the materialized 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 stays retrievable: read models project this id
+    // (submit response, prompt list, transcript), so it must keep serving the
+    // final bytes like any client upload — deleting it after intake would
+    // leave every projected `{kind:'file'}` reference dangling.
+    const final = await server!.core.accessor.get(IFileService).get(finalFileId);
+    expect(final.meta.size).toBe((await readFileEventually(mediaPath)).length);
+
+    // 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
+    // `<image path>` tag folded into the media part instead of reaching the
+    // wire, 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: 'file', 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('falls back to the shared cache dir 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 materialized copy falls back to the shared cache dir.
+    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 cacheDir = server!.core.accessor.get(IBootstrapService).cacheDir;
+      const mediaPath = join(cacheDir, `${uploaded.id}.png`);
+      expect(await readFileEventually(mediaPath)).toEqual(smallPng);
+    } finally {
+      await chmod(mediaDir, 0o755);
+    }
   });
 
   it('compresses inline base64 image prompts into session media-originals', async () => {
diff --git a/packages/kap-server/test/search/wireExtract.test.ts b/packages/kap-server/test/search/wireExtract.test.ts
index 088dfff1d3..6c649a9f19 100644
--- a/packages/kap-server/test/search/wireExtract.test.ts
+++ b/packages/kap-server/test/search/wireExtract.test.ts
@@ -92,6 +92,44 @@ describe('extractFromWireLine', () => {
     expect(out).toEqual([]);
   });
 
+  it('indexes only the real text of an upload-carrying user message', () => {
+    // An uploaded image persists as `<image path>` tag text + a `kimi-file://`
+    // image part; the tag is machine markup paired with the ref, so it never
+    // becomes searchable — an upload-only message drops out of the index, and
+    // a real text beside the pair is indexed on its own.
+    const uploadPair = [
+      { 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' } },
+      });
+
+    // Upload-only: nothing indexable (the materialization path included).
+    expect(extractFromWireLine(record(uploadPair))).toEqual([]);
+    // With a real text part alongside, exactly that text is indexed.
+    expect(
+      extractFromWireLine(record([{ type: 'text', text: 'what is this? ' }, ...uploadPair])),
+    ).toEqual([{ role: 'user', text: 'what is this?', time: 1_700_000_000_000 }]);
+  });
+
+  it('keeps an unpaired standalone <media path> tag as user text', () => {
+    // Without an adjacent path-matching daemon ref the tag is user content,
+    // not markup the index may eat.
+    const out = extractFromWireLine(
+      userRecord('<image path="/tmp/shot.png">', 1_700_000_000_000, { kind: 'user' }),
+    );
+    expect(out).toEqual([
+      { role: 'user', text: '<image path="/tmp/shot.png">', 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 948f0b5b81..1980231615 100644
--- a/packages/kap-server/test/services/messages/messageProjection.test.ts
+++ b/packages/kap-server/test/services/messages/messageProjection.test.ts
@@ -40,6 +40,57 @@ describe('toProtocolMessage', () => {
     ]);
   });
 
+  it('folds the upload tag+ref pair into a single image part', () => {
+    // The persisted dual shape (`<image path>` tag text part + daemon-ref
+    // image part) is ONE upload: the tag is machine markup and must not
+    // reach the wire as a text part (clients would render the image twice).
+    const msg: ContextMessage = {
+      role: 'user',
+      content: [
+        { type: 'text', text: 'what is this?' },
+        { 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: 'what is this?' },
+      { type: 'image', source: { kind: 'file', file_id: 'file_9' } },
+    ]);
+  });
+
+  it('keeps a bare <media path> tag as text in user messages', () => {
+    // Without a paired daemon ref the tag is not machine markup the fold may
+    // claim: 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',
diff --git a/packages/kap-server/test/services/transcript.test.ts b/packages/kap-server/test/services/transcript.test.ts
index 26432624eb..b72e5cb169 100644
--- a/packages/kap-server/test/services/transcript.test.ts
+++ b/packages/kap-server/test/services/transcript.test.ts
@@ -146,6 +146,52 @@ 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', name: 'shot.png' }],
+      }),
+    );
+    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/*',
+          name: 'shot.png',
+          source: { kind: 'file', 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/*',
+      name: 'shot.png',
+      source: { kind: 'file', 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 —
@@ -395,6 +441,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');
@@ -1491,6 +1577,35 @@ 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: 'text', text: '<image path="/abs/session/media/f_img1.png"></image>' },
+          {
+            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: 'file', file_id: 'f_img1' } },
+    ]);
+  });
+
   it('readColdSnapshot answers empty for path-hostile agent ids without touching disk', async () => {
     const service = new TranscriptService({
       homeDir: '/nonexistent-home',
@@ -1888,23 +2003,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;
   }
 
@@ -2047,6 +2189,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 } });
@@ -2145,6 +2377,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());
@@ -2262,6 +2502,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', name: 'shot.png' }],
+        }),
+      );
+      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', name: 'shot.png' }],
+        }),
+      );
+      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 9d5fd631d3..ff5c56ce9b 100644
--- a/packages/kap-server/test/sessionEventBroadcaster.test.ts
+++ b/packages/kap-server/test/sessionEventBroadcaster.test.ts
@@ -824,6 +824,130 @@ 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>).sort()).toEqual(
+      [...TURN_STARTED_WIRE_KEYS, 'promptId'].sort(),
+    );
+  });
+
+  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', name: 'clip.mp4' }],
+      }),
+    );
+    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>).sort()).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>).sort()).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: '<image path="/abs/session/media/f_img1.png"></image>' },
+            {
+              type: 'image_url',
+              imageUrl: { url: 'kimi-file://f_img1?path=%2Fabs%2Fsession%2Fmedia%2Ff_img1.png' },
+            },
+          ],
+        }),
+      );
+      await bc.getCursor('s1'); // drain
+
+      const expected = [{ type: 'image', source: { kind: 'file', 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 2cec22368d..d0b5d98dc7 100644
--- a/packages/kap-server/test/transcript.test.ts
+++ b/packages/kap-server/test/transcript.test.ts
@@ -1082,6 +1082,82 @@ 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', name: 'upload.png' }],
+      }),
+    );
+    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: 'file', 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: the `<image path>` tag
+    // text part paired with its daemon-ref media part. The cold fold collapses
+    // the pair into one attachment and an empty prompt text.
+    await seedMainAgentMessages(id, [
+      {
+        role: 'user',
+        content: [
+          { type: 'text', text: '<image path="/tmp/cache/f_upload.png"></image>' },
+          { 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/*',
+        name: 'f_upload.png',
+        source: { kind: 'file', 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/klient/AGENTS.md b/packages/klient/AGENTS.md
index d4724f483b..127bd662e8 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 53e650c937..bbf95bc1ac 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/rpc.ts b/packages/klient/src/contract/agent/rpc.ts
index 1186c694a4..6fb38efa13 100644
--- a/packages/klient/src/contract/agent/rpc.ts
+++ b/packages/klient/src/contract/agent/rpc.ts
@@ -48,6 +48,9 @@ export const promptPayloadSchema = z.object({
   // 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().optional(),
 });
 
 /** Same shape as `SteerPayload` 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 0000000000..74644dbe87
--- /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 6f9ef48efa..511c43d147 100644
--- a/packages/klient/src/contract/index.ts
+++ b/packages/klient/src/contract/index.ts
@@ -24,6 +24,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';
@@ -57,6 +58,7 @@ export const globalContract: KlientContract = {
   capabilityService: capabilitiesContract,
   hostFolderBrowser: hostFsContract,
   bootstrapService: envContract,
+  fileService: filesContract,
   // workspace scope (+ the app-registered handler registry)
   workspaceLifecycleService: workspaceLifecycleContract,
   sessionLifecycleService: sessionLifecycleContract,
diff --git a/packages/klient/src/core/facade/agent.ts b/packages/klient/src/core/facade/agent.ts
index 145e5fbaf9..811a1a0f6c 100644
--- a/packages/klient/src/core/facade/agent.ts
+++ b/packages/klient/src/core/facade/agent.ts
@@ -38,6 +38,7 @@ export interface AgentFacade {
   prompt(input: {
     input: readonly ContentPart[];
     disabledTools?: readonly string[];
+    promptId?: string;
   }): Promise<PromptLaunchResult>;
   steer(input: { input: readonly ContentPart[] }): Promise<PromptLaunchResult>;
   /**
diff --git a/packages/klient/src/core/facade/global.ts b/packages/klient/src/core/facade/global.ts
index 088ab9a470..7c62308066 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>;
 }
 
@@ -470,6 +496,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 bd02deee32..7b633d2a81 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,
@@ -111,6 +113,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 11c2c3fb59..806bf917bb 100644
--- a/packages/klient/src/transports/memory/dispatcher.ts
+++ b/packages/klient/src/transports/memory/dispatcher.ts
@@ -20,6 +20,13 @@ 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 { Readable } from 'node:stream';
 
 import type { EventSourceRef, IDisposable, ScopeRef } from '../../core/channel.js';
 import { RPCError } from '../../core/errors.js';
@@ -59,6 +66,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> {
@@ -153,6 +166,30 @@ 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;
+        const meta = await files.save(
+          Readable.from(Buffer.from(data, 'base64')),
+          filename,
+          options,
+        );
+        return wireClone(meta);
+      }
+      if (service === 'fileService' && method === 'get') {
+        const [fileId] = args as [string];
+        const files = instance as FileServiceWireTarget;
+        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') };
+      }
       const member = instance[method];
       if (member === undefined) {
         throw new RPCError(REQUEST_INVALID, `method not found: ${service}.${method}`);
diff --git a/packages/klient/src/transports/memory/serviceRegistry.ts b/packages/klient/src/transports/memory/serviceRegistry.ts
index 00f31551e2..c3e445f504 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 { IWorkspaceLifecycleService } from '@moonshot-ai/agent-core-v2/app/workspaceLifecycle/workspaceLifecycle';
 import { ISessionLifecycleService } from '@moonshot-ai/agent-core-v2/workspace/sessionLifecycle/sessionLifecycle';
@@ -56,6 +57,7 @@ export const serviceTokens: Readonly<Record<string, ServiceIdentifier<unknown>>>
   capabilityService: ICapabilityService,
   hostFolderBrowser: IHostFolderBrowser,
   bootstrapService: IBootstrapService,
+  fileService: IFileService,
   workspaceLifecycleService: IWorkspaceLifecycleService,
   sessionLifecycleService: ISessionLifecycleService,
   sessionMetadata: ISessionMetadata,
diff --git a/packages/klient/test/contract-parity.ts b/packages/klient/test/contract-parity.ts
index fb6bdf032d..d5fdc42d96 100644
--- a/packages/klient/test/contract-parity.ts
+++ b/packages/klient/test/contract-parity.ts
@@ -88,6 +88,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,
@@ -261,6 +265,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,
@@ -374,6 +382,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/facade.test.ts b/packages/klient/test/facade.test.ts
index 8c76e8cf9a..180c7c27d3 100644
--- a/packages/klient/test/facade.test.ts
+++ b/packages/klient/test/facade.test.ts
@@ -533,3 +533,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 226dce0b1a..a80c302a48 100644
--- a/packages/klient/test/helpers/conformance.ts
+++ b/packages/klient/test/helpers/conformance.ts
@@ -221,6 +221,29 @@ 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);
+      await expect(files.get(meta.id)).rejects.toThrow();
+    });
+
     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);
diff --git a/packages/node-sdk/src/index.ts b/packages/node-sdk/src/index.ts
index 19b0f08a57..d467fb4fa8 100644
--- a/packages/node-sdk/src/index.ts
+++ b/packages/node-sdk/src/index.ts
@@ -124,6 +124,23 @@ 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. Hosts must not import agent-core-v2 directly; `FileMeta` and
+// `UploadFileOptions` ride the `export type * from '#/types'` below.
+export {
+  buildDaemonFileUrl,
+  buildMediaPathTag,
+  foldMediaPathTagRefs,
+  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 3aa1843deb..f42a3af378 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,
   GetConfigOptions,
   KimiConfig,
@@ -39,6 +40,7 @@ import type {
   TelemetryContextPatch,
   TelemetryProperties,
   TestMcpServerOptions,
+  UploadFileOptions,
   WorkspaceTrustInfo,
 } from '#/types';
 
@@ -358,6 +360,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 e33199d2a5..5f0c4f02ab 100644
--- a/packages/node-sdk/src/rpc.ts
+++ b/packages/node-sdk/src/rpc.ts
@@ -33,6 +33,7 @@ import type {
   ExportSessionInput,
   ExportSessionResult,
   CreateGoalInput,
+  FileMeta,
   ForkSessionInput,
   GetConfigOptions,
   McpServerConfig,
@@ -61,6 +62,7 @@ import type {
   SkillSummary,
   PluginCommandDef,
   Unsubscribe,
+  UploadFileOptions,
   WorkspaceTrustInfo,
 } from '#/types';
 
@@ -75,6 +77,11 @@ export interface SessionPromptRpcInput {
    * `[]` clears the client portion.
    */
   readonly disabledTools?: readonly string[];
+  /**
+   * Client-chosen prompt record id, echoed on the consuming turn's
+   * `turn.started` (`promptId`). Honored by the v2 RPC client only.
+   */
+  readonly promptId?: string;
 }
 
 export interface SessionIdRpcInput {
@@ -310,6 +317,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 d42ddfcd36..e876eb4412 100644
--- a/packages/node-sdk/src/sdk-rpc-client-v2.ts
+++ b/packages/node-sdk/src/sdk-rpc-client-v2.ts
@@ -265,6 +265,7 @@ import type {
   CreateSessionOptions,
   ExportSessionInput,
   ExportSessionResult,
+  FileMeta,
   ForkSessionInput,
   GetConfigOptions,
   GetCronTasksResult,
@@ -295,6 +296,7 @@ import type {
   SessionUsage,
   SkillSummary,
   TelemetryClient,
+  UploadFileOptions,
   WorkspaceTrustInfo,
 } from '#/types';
 import {
@@ -536,6 +538,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 /
@@ -1586,7 +1606,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, disabledTools: input.disabledTools });
+    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 4a3325fdcc..e3e2100ba4 100644
--- a/packages/node-sdk/src/session.ts
+++ b/packages/node-sdk/src/session.ts
@@ -129,11 +129,12 @@ 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();
     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 04d94c702a..7ed780acd7 100644
--- a/packages/node-sdk/src/types.ts
+++ b/packages/node-sdk/src/types.ts
@@ -90,6 +90,17 @@ export interface WorkspaceTrustInfo {
   readonly gatedMcpServers: readonly string[];
 }
 
+/** 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/test/kimi-harness.test.ts b/packages/node-sdk/test/kimi-harness.test.ts
index 4f7c82ca40..3068b14b5a 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 aa2a3b2e5b..74726f54a5 100644
--- a/packages/node-sdk/test/sdk-rpc-client-v2.test.ts
+++ b/packages/node-sdk/test/sdk-rpc-client-v2.test.ts
@@ -14,8 +14,10 @@ import { join } from 'node:path';
 import { afterEach, describe, expect, it } from 'vitest';
 
 import {
+  buildDaemonFileUrl,
   createKimiHarnessV2,
   ErrorCodes,
+  isDaemonFileUrl,
   KimiError,
   KimiHarness,
   removeProviderFromConfig,
@@ -78,6 +80,32 @@ describe('SDKRpcClientV2 (agent-core-v2 wiring MVP)', () => {
     }
   });
 
+  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, '/tmp/pixel.png'))).toBe(true);
+      await harness.deleteFile(meta.id);
+      await expect(harness.deleteFile(meta.id)).rejects.toThrow(/file not found/);
+    } finally {
+      await harness.close();
+    }
+  });
+
   it('serves listWorkspaceSkills through the engineAccessor escape hatch', async () => {
     const { harness, homeDir } = await makeHarness();
     const workDir = await mkdtemp(join(tmpdir(), 'kimi-sdk-v2-work-'));
diff --git a/packages/node-sdk/test/session-prompt-input.test.ts b/packages/node-sdk/test/session-prompt-input.test.ts
index f88c710009..52e7cee643 100644
--- a/packages/node-sdk/test/session-prompt-input.test.ts
+++ b/packages/node-sdk/test/session-prompt-input.test.ts
@@ -82,6 +82,23 @@ 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('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/events.ts b/packages/protocol/src/events.ts
index bea2fbe265..e79b108a05 100644
--- a/packages/protocol/src/events.ts
+++ b/packages/protocol/src/events.ts
@@ -631,6 +631,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 {
diff --git a/packages/transcript/src/contract/mediaRef.ts b/packages/transcript/src/contract/mediaRef.ts
new file mode 100644
index 0000000000..6e02a9c6b9
--- /dev/null
+++ b/packages/transcript/src/contract/mediaRef.ts
@@ -0,0 +1,171 @@
+/**
+ * `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.
+ * An upload edge persists a medium as the pair `<media path> tag text part +
+ * `kimi-file://` media part; read models fold the pair into a single
+ * attachment and never render the tag as text. `pairMediaPathTagRefs` decides
+ * which tag claims which ref (standalone tag only, adjacent, kind-compatible,
+ * path-equal, single-claim); an unpaired standalone tag stays as text.
+ */
+
+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 shape upload edges emit as a standalone text part next to
+ * the daemon-ref media part. 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://';
+const PATH_QUERY = '?path=';
+
+/** The daemon upload reference behind a `kimi-file://<fileId>[?path=…]` url. */
+export interface DaemonFileRef {
+  readonly fileId: string;
+  readonly path?: string;
+}
+
+/**
+ * Parse a `kimi-file://<fileId>[?path=<encoded absolute path>]` url — the
+ * mirror of the engine's `parseDaemonFileUrl`. An undecodable path is dropped
+ * but the file id keeps parsing.
+ */
+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(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 };
+}
+
+/** The daemon upload id behind a `kimi-file://<fileId>[?path=…]` url. */
+export function parseDaemonFileRefFileId(url: string): string | undefined {
+  return parseDaemonFileRef(url)?.fileId;
+}
+
+// ---------------------------------------------------------------------------
+// Tag + daemon-ref pairing — the mirror of the engine's `pairMediaPathTagRefs`.
+// ---------------------------------------------------------------------------
+
+/**
+ * The structural minimum the pairing algorithm needs from a content part —
+ * the kosong `text` / `image_url` / `video_url` shapes plus anything else.
+ */
+export interface MediaRefPairingPart {
+  readonly type: string;
+  readonly text?: string;
+  readonly imageUrl?: { readonly url?: string };
+  readonly videoUrl?: { readonly url?: string };
+}
+
+/**
+ * The daemon reference behind a pairing part, if any — the mirror of the
+ * engine's `daemonFileRefFromPart` (keep the two in sync), and the single
+ * part → ref extraction the pairing and read models share.
+ */
+export function daemonFileRefFromPairingPart(
+  part: MediaRefPairingPart,
+): { readonly kind: 'image' | 'video'; readonly fileId: string; readonly path?: string } | 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', fileId: ref.fileId, path: ref.path };
+}
+
+/**
+ * The claim analysis behind the tag + daemon-ref fold — the mirror of the
+ * engine's algorithm (keep the two in sync).
+ *
+ * Pairing rules:
+ *   - only a STANDALONE tag (the whole text part is exactly one media path
+ *     tag) participates; a tag embedded in other text never does;
+ *   - a tag pairs with a daemon-ref media part immediately before or after it
+ *     (edges emit tag-before-ref; persisted history also has ref-before-tag)
+ *     when the kinds are compatible — a `file` tag matches either ref kind —
+ *     AND the tag's path equals the path the reference carries. A reference
+ *     without a path can never pair: both sides stay, conservatively;
+ *   - each tag claims at most one reference and each reference is claimed by
+ *     at most one tag; references claim in input order, checking the part
+ *     before them first.
+ */
+export interface MediaPathTagPairing {
+  /** Standalone media-tag text part indices claimed by an adjacent daemon ref. */
+  readonly claimedTagIndices: ReadonlySet<number>;
+  /** The claiming tag's path per daemon-ref part index; absent for an unpaired ref. */
+  readonly claimedPathByRefIndex: ReadonlyMap<number, string>;
+  /** The claiming reference per claimed tag index. */
+  readonly claimingRefByTagIndex: ReadonlyMap<number, number>;
+}
+
+export function pairMediaPathTagRefs(
+  parts: readonly MediaRefPairingPart[],
+): MediaPathTagPairing {
+  const tagByIndex = new Map<number, MediaPathTagMatch>();
+  const refByIndex = new Map<number, { kind: 'image' | 'video'; path?: string }>();
+  parts.forEach((part, index) => {
+    if (part.type === 'text') {
+      const tag = typeof part.text === 'string' ? matchMediaPathTagText(part.text) : undefined;
+      if (tag !== undefined) tagByIndex.set(index, tag);
+      return;
+    }
+    const ref = daemonFileRefFromPairingPart(part);
+    if (ref !== undefined) refByIndex.set(index, { kind: ref.kind, path: ref.path });
+  });
+  const claimedTagIndices = new Set<number>();
+  const claimedPathByRefIndex = new Map<number, string>();
+  const claimingRefByTagIndex = new Map<number, number>();
+  for (const [refIndex, ref] of refByIndex) {
+    if (ref.path === undefined) continue;
+    for (const neighbor of [refIndex - 1, refIndex + 1]) {
+      const tag = tagByIndex.get(neighbor);
+      if (tag === undefined || claimedTagIndices.has(neighbor)) continue;
+      if (tag.kind !== 'file' && tag.kind !== ref.kind) continue;
+      if (tag.path !== ref.path) continue;
+      claimedTagIndices.add(neighbor);
+      claimedPathByRefIndex.set(refIndex, tag.path);
+      claimingRefByTagIndex.set(neighbor, refIndex);
+      break;
+    }
+  }
+  return { claimedTagIndices, claimedPathByRefIndex, claimingRefByTagIndex };
+}
diff --git a/packages/transcript/src/history/groupTurns.ts b/packages/transcript/src/history/groupTurns.ts
index bc9c6afd8a..e16dfc3ecb 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. An
+ *    upload persists as the pair `<media path>` tag text part + `kimi-file://`
+ *    media part: the pair folds into a single attachment, and the tag —
+ *    machine markup — never surfaces as 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,10 @@ 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,
+  pairMediaPathTagRefs,
+} from '../contract/mediaRef';
 
 export type HistoryMediaSource =
   | { readonly kind: 'url'; readonly url: string }
@@ -114,12 +121,29 @@ 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. The upload pair
+   * (`<media path>` tag text part + `kimi-file://` media part) folds into a
+   * single attachment per the shared pairing (`pairMediaPathTagRefs`): a
+   * CLAIMED tag is machine markup and never surfaces as prompt text, while an
+   * unpaired standalone tag stays as text; a bare ref still yields an
+   * attachment, without a path-derived name.
+   */
+  const foldTurnOpeningInput = (
+    message: HistoryMessage,
+  ): { text: string; attachmentIds?: string[] } => {
+    const parts = message.content ?? [];
+    const pairing = pairMediaPathTagRefs(parts);
     const ids: string[] = [];
-    for (const part of message.content ?? []) {
+    const texts: string[] = [];
+    parts.forEach((part, index) => {
+      if (pairing.claimedTagIndices.has(index)) return;
+      if (part.type === 'text' && 'text' in part && typeof part.text === 'string') {
+        texts.push(part.text);
+        return;
+      }
       if (part.type === 'image' || part.type === 'video' || part.type === 'audio') {
-        if (!('source' in part) || part.source === undefined) continue;
+        if (!('source' in part) || part.source === undefined) return;
         const source = part.source as HistoryMediaSource;
         const entity: TranscriptAttachment = {
           attachmentId: `att_${attachments.length + 1}`,
@@ -135,7 +159,9 @@ export function groupMessagesIntoSnapshot(
         };
         attachments.push(entity);
         ids.push(entity.attachmentId);
-      } else if (part.type === 'file' && 'file_id' in part) {
+        return;
+      }
+      if (part.type === 'file' && 'file_id' in part) {
         const entity: TranscriptAttachment = {
           attachmentId: `att_${attachments.length + 1}`,
           mediaType: part.media_type as string,
@@ -145,9 +171,22 @@ export function groupMessagesIntoSnapshot(
         };
         attachments.push(entity);
         ids.push(entity.attachmentId);
+        return;
       }
-    }
-    return ids.length > 0 ? ids : undefined;
+      const ref = daemonFileRefFromPairingPart(part);
+      if (ref !== undefined) {
+        const path = pairing.claimedPathByRefIndex.get(index);
+        const entity: TranscriptAttachment = {
+          attachmentId: `att_${attachments.length + 1}`,
+          mediaType: `${ref.kind}/*`,
+          name: path === undefined ? undefined : pathBaseName(path),
+          source: { kind: 'file', fileId: ref.fileId },
+        };
+        attachments.push(entity);
+        ids.push(entity.attachmentId);
+      }
+    });
+    return { text: texts.join(''), attachmentIds: ids.length > 0 ? ids : undefined };
   };
 
   const ensureTurn = (origin: TurnOrigin = FALLBACK_ORIGIN): TurnDraft => {
@@ -190,17 +229,22 @@ 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 folds like any other user's (upload
+        // tag+ref pair → attachment, claimed tag out of the text), 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;
       }
-      startTurn(mapOrigin(message), textOf(message), collectAttachments(message));
+      const opening = foldTurnOpeningInput(message);
+      startTurn(mapOrigin(message), opening.text, opening.attachmentIds);
       continue;
     }
 
@@ -329,6 +373,14 @@ function textOf(message: HistoryMessage): string {
     .join('');
 }
 
+/**
+ * Basename of a materialization path for an attachment's display name.
+ */
+function pathBaseName(path: string): string {
+  const sep = Math.max(path.lastIndexOf('/'), path.lastIndexOf('\\'));
+  return sep === -1 ? path : path.slice(sep + 1);
+}
+
 function parseArguments(raw: string | null): unknown {
   if (!raw) return undefined;
   try {
diff --git a/packages/transcript/src/index.ts b/packages/transcript/src/index.ts
index 70f8bc7abe..1ae1ae0116 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/test/layers.test.ts b/packages/transcript/test/layers.test.ts
index d6108f5239..fafe92913e 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 tag+ref fold 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' }] },
@@ -485,6 +491,173 @@ describe('groupMessagesIntoSnapshot (cold path)', () => {
     expect(firstTurn.attachmentIds).toEqual(['att_1', 'att_2', 'att_3']);
   });
 
+  it('folds persisted kimi-file media refs and their <media path> tags into single attachments', () => {
+    // The engine persists an uploaded medium as a kosong `image_url` /
+    // `video_url` part carrying a `kimi-file://<fileId>?path=…` ref, plus an
+    // adjacent `<image|video path=…>` text tag. The pair folds into ONE
+    // attachment (source = the daemon upload, name = the tag path's
+    // basename); the tag is machine markup and never surfaces as prompt text.
+    const snapshot = groupMessagesIntoSnapshot([
+      {
+        role: 'user',
+        content: [
+          {
+            type: 'video_url',
+            videoUrl: { url: 'kimi-file://file_1?path=%2Fcache%2Fclip.mp4' },
+          } as HistoryContentPart,
+          { type: 'text', text: '<video path="/cache/clip.mp4"></video>' },
+        ],
+        toolCalls: [],
+        origin: { kind: 'user' },
+      },
+      {
+        role: 'user',
+        content: [
+          { type: 'text', text: 'what is this?' },
+          { type: 'text', text: '<image path="/cache/shot.png"></image>' },
+          {
+            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/*',
+        name: 'clip.mp4',
+        source: { kind: 'file', fileId: 'file_1' },
+      },
+      {
+        attachmentId: 'att_2',
+        mediaType: 'image/*',
+        name: 'shot.png',
+        source: { kind: 'file', 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('folds the upload pair in a user-slash turn-opening input like a plain user turn', () => {
+    // A user-slash skill command carrying an uploaded image persists the same
+    // tag+ref pair; the cold rebuild folds it exactly like a plain user turn
+    // (claimed tag out of the prompt text, one attachment on the turn),
+    // mirroring the live `projectTurnPrompt` fold.
+    const snapshot = groupMessagesIntoSnapshot([
+      {
+        role: 'user',
+        content: [
+          { type: 'text', text: '/gen-docs ' },
+          { type: 'text', text: '<image path="/cache/shot.png"></image>' },
+          {
+            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/*',
+        name: 'shot.png',
+        source: { kind: 'file', 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 bare kimi-file ref as a pathless 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?path=%2Fcache%2Fplain.png' },
+      } as HistoryContentPart,
+    );
+
+    // No adjacent tag: the attachment carries no path-derived name; the
+    // inline tag inside real user text stays verbatim (never stripped).
+    expect(snapshot.attachments).toEqual([
+      {
+        attachmentId: 'att_1',
+        mediaType: 'image/*',
+        name: undefined,
+        source: { kind: 'file', 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 standalone <media path> tags as prompt text when no daemon ref pairs with them', () => {
+    // The no-closing-tag and extra-attribute forms both exist in persisted
+    // sessions. Without an adjacent path-matching ref there is no pair: the
+    // tag is user-visible text, 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 a standalone tag as prompt text when the adjacent ref carries a different path', () => {
+    const snapshot = snapshotOf(
+      { type: 'text', text: '<image path="/cache/other.png"></image>' },
+      {
+        type: 'image_url',
+        imageUrl: { url: 'kimi-file://file_1?path=%2Fcache%2Fshot.png' },
+      } as HistoryContentPart,
+    );
+
+    expect(snapshot.attachments).toEqual([
+      {
+        attachmentId: 'att_1',
+        mediaType: 'image/*',
+        name: undefined,
+        source: { kind: 'file', fileId: 'file_1' },
+      },
+    ]);
+    const turn = snapshot.items[0];
+    if (turn?.kind !== 'turn') throw new Error('expected turn');
+    expect(turn.prompt).toBe('<image path="/cache/other.png"></image>');
+    expect(turn.attachmentIds).toEqual(['att_1']);
+  });
+
   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' } },