uploads: centralise via ChatHubApi::save_upload, refactor handlers

Extract shared upload seam in skald-core, move Telegram and web
handlers to use it. Simplify media attachment routing. Clean up
unused deps and dead code.

crates/core-api/src/chat_hub.rs

@@ -5,7 +5,7 @@ use tokio::sync::broadcast;
 
 use crate::events::GlobalEvent;
 use crate::interface_tool::InterfaceTool;
-use crate::message_meta::MessageMetadata;
+use crate::message_meta::{Attachment, MessageMetadata};
 
 // ── SendMessageOptions ────────────────────────────────────────────────────────
 
@@ -59,6 +59,20 @@ pub trait ChatHubApi: Send + Sync {
         opts: SendMessageOptions,
     ) -> anyhow::Result<()>;
 
+    /// Persist an uploaded file for `source_id` into the owner's
+    /// `~/uploads/{session}/` and return its [`Attachment`] (home-relative agent
+    /// path). Channel adapters (e.g. the Telegram plugin) call this instead of
+    /// writing files themselves, so the core owns *where* uploads land and every
+    /// surface produces a path the agent can actually reach. The recognized
+    /// magic-byte MIME wins over the caller-claimed `client_mime`.
+    async fn save_upload(
+        &self,
+        source_id: &str,
+        file_name: &str,
+        client_mime: Option<String>,
+        bytes: &[u8],
+    ) -> anyhow::Result<Attachment>;
+
     /// Create a new session for the source, discarding the previous one.
     async fn clear(&self, source_id: &str) -> anyhow::Result<i64>;
 

crates/core-api/src/message_meta.rs

@@ -12,9 +12,10 @@
 
 use serde::{Deserialize, Serialize};
 
-/// One file attached by the user to a message. `path` is relative to the project
-/// root (e.g. `data/uploads/123/file.pdf`) so it is both servable under `/data/…`
-/// and resolvable by the filesystem tools.
+/// One file attached by the user to a message. `path` is a home-relative agent
+/// path (e.g. `uploads/123/file.pdf`) — the caller's container home is its root,
+/// so the fs-tools, `execute_cmd`, the file viewer (`/api/file`) and the media
+/// inliner all resolve it to the same physical file.
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
 pub struct Attachment {
     pub path:     String,

crates/core-api/src/user_fs.rs

@@ -22,6 +22,12 @@
 use std::path::{Component, Path, PathBuf};
 use std::sync::{Arc, RwLock};
 
+/// The subdirectory of a user's home where chat uploads are saved
+/// (`{home}/uploads/{session_id}/…`, reachable by the agent as `uploads/…`).
+/// Shared by the upload handler (write path) and the media inliner (containment
+/// root) so the two anchors can never drift.
+pub const UPLOADS_SUBDIR: &str = "uploads";
+
 /// One shared folder mounted into a user's container.
 #[derive(Debug, Clone)]
 pub struct SharedMount {

crates/plugin-telegram-bot/src/attachments.rs

@@ -1,7 +1,6 @@
 use std::path::Path;
 
 use anyhow::Result;
-use core_api::message_meta::Attachment;
 use teloxide::net::Download;
 use teloxide::prelude::*;
 
@@ -10,9 +9,9 @@ use teloxide::prelude::*;
 /// # Extending
 /// Add a new variant here, then handle it in:
 ///   1. `handlers::classify_message`  — detect the message type and build the variant
-///   2. `TelegramAttachment::download_and_save` — fetch bytes and persist to disk,
-///                                                 returning an [`Attachment`]
-///                                                 (return `Ok(None)` if no file is involved)
+///   2. `TelegramAttachment::download` — fetch the bytes (return `Ok(None)` if no
+///                                       file is involved); the caller persists them
+///                                       via the shared `ChatHubApi::save_upload` seam
 ///   3. `TelegramAttachment::system_info_message` — describe a file-less variant
 ///                                                   (Location) for the LLM
 pub(crate) enum TelegramAttachment {
@@ -36,20 +35,16 @@ pub(crate) enum TelegramAttachment {
 }
 
 impl TelegramAttachment {
-    /// Downloads the attachment from Telegram, writes it to `base_dir/<chat_id>/<name>`,
-    /// and returns the saved [`Attachment`] (shared with the web/mobile path so the
-    /// copilot UI renders it identically). Returns `None` for attachment types that
-    /// carry no binary content (e.g. Location).
-    ///
-    /// The returned `path` is made relative to the process working directory (the
-    /// project root) when possible, so it is both servable under `/data/…` and
-    /// resolvable by the filesystem tools — matching web uploads.
-    pub(crate) async fn download_and_save(
+    /// Downloads the attachment's bytes from Telegram, returning
+    /// `(file_name, mimetype, bytes)`. Persistence is **not** done here: the caller
+    /// hands the bytes to the shared upload seam (`ChatHubApi::save_upload`), which
+    /// saves them into the user's home under `uploads/{session}/…` and produces the
+    /// [`Attachment`] — the same path every surface uses, so the agent can reach it.
+    /// Returns `None` for attachment types that carry no binary content (e.g. Location).
+    pub(crate) async fn download(
         &self,
-        bot:      &Bot,
-        base_dir: &Path,
-        chat_id:  i64,
-    ) -> Result<Option<Attachment>> {
+        bot: &Bot,
+    ) -> Result<Option<(String, Option<String>, Vec<u8>)>> {
         let (file_id, file_name, mimetype): (&str, String, Option<String>) = match self {
             Self::Document { file_id, file_name, mime_type, .. } =>
                 (file_id, file_name.clone(), mime_type.clone()),
@@ -58,28 +53,11 @@ impl TelegramAttachment {
             Self::Location { .. } => return Ok(None),
         };
 
-        let dir = base_dir.join(chat_id.to_string());
-        tokio::fs::create_dir_all(&dir).await?;
-
         let tg_file = bot.get_file(teloxide::types::FileId(file_id.to_string())).await?;
         let mut bytes = Vec::new();
         bot.download_file(&tg_file.path, &mut bytes).await?;
 
-        let path = dir.join(&file_name);
-        tokio::fs::write(&path, &bytes).await?;
-
-        // Prefer a project-root-relative path so `/data/…` serving works.
-        let rel = std::env::current_dir()
-            .ok()
-            .and_then(|cwd| path.strip_prefix(&cwd).ok().map(Path::to_path_buf))
-            .unwrap_or_else(|| path.clone());
-
-        Ok(Some(Attachment {
-            path:     rel.to_string_lossy().to_string(),
-            name:     file_name,
-            mimetype,
-            filesize: Some(bytes.len() as u64),
-        }))
+        Ok(Some((file_name, mimetype, bytes)))
     }
 
     /// Builds the `[TELEGRAM SYSTEM INFO]` message injected into the conversation history.

crates/plugin-telegram-bot/src/handlers.rs

@@ -512,17 +512,32 @@ async fn handle_attachment(
 
     bot.send_chat_action(chat_id, ChatAction::UploadDocument).await.ok();
 
-    let saved = match attachment.download_and_save(&bot, &shared.uploads_dir, chat_id.0).await {
-        Ok(s)  => s,
+    let downloaded = match attachment.download(&bot).await {
+        Ok(d)  => d,
         Err(e) => {
-            error!(error = %e, "telegram: failed to save attachment");
-            bot.send_message(chat_id, "⚠️ Could not save the attachment.").await.ok();
+            error!(error = %e, "telegram: failed to download attachment");
+            bot.send_message(chat_id, "⚠️ Could not download the attachment.").await.ok();
             return;
         }
     };
 
-    match saved {
-        Some(att) => {
+    match downloaded {
+        Some((file_name, mimetype, bytes)) => {
+            // Persist through the shared upload seam so the file lands in the user's
+            // home (`uploads/{session}/…`) with an agent-reachable path — identical
+            // to a web upload.
+            let att = match handle
+                .chat_hub()
+                .save_upload("telegram", &file_name, mimetype, &bytes)
+                .await
+            {
+                Ok(a)  => a,
+                Err(e) => {
+                    error!(error = %e, "telegram: failed to save attachment");
+                    bot.send_message(chat_id, "⚠️ Could not save the attachment.").await.ok();
+                    return;
+                }
+            };
             info!(chat_id = chat_id.0, path = %att.path, "telegram: attachment saved, forwarding to LLM");
             let caption = match &attachment {
                 TelegramAttachment::Document { caption, .. } => caption.clone(),

crates/plugin-telegram-bot/src/lib.rs

@@ -26,7 +26,6 @@
 /// `ApprovalApi`.
 
 use std::collections::{HashMap, HashSet};
-use std::path::PathBuf;
 use std::sync::Arc;
 use std::sync::atomic::{AtomicBool, Ordering};
 
@@ -106,7 +105,6 @@ pub(crate) struct TgShared {
     pub(crate) transcribe:   Arc<dyn TranscribeProvider>,
     pub(crate) tts:          Arc<dyn TtsProvider>,
     pub(crate) location:     Arc<dyn LocationUpdater>,
-    pub(crate) uploads_dir:  PathBuf,
 
     // ── Pairing / bindings (config-table-backed, cached in memory) ──
     pub(crate) bindings:     RwLock<auth::TelegramConfig>,
@@ -272,11 +270,6 @@ impl Plugin for TelegramPlugin {
             anyhow::bail!("telegram: token is empty — set it via the plugins API");
         }
 
-        let uploads_dir = std::env::current_dir()
-            .unwrap_or_default()
-            .join("uploads")
-            .join("telegram");
-
         // Load bindings from the config table (or default if absent).
         let telegram_config = auth::load_config(&*ctx.config).await
             .unwrap_or_default();
@@ -293,7 +286,6 @@ impl Plugin for TelegramPlugin {
             transcribe:        Arc::clone(&ctx.transcribe),
             tts:               Arc::clone(&ctx.tts_provider),
             location:          Arc::clone(&ctx.location),
-            uploads_dir,
             bindings:          RwLock::new(telegram_config),
             pending_approvals: Mutex::new(HashMap::new()),
             pending_questions: Mutex::new(HashMap::new()),

crates/skald-core/src/chat_hub/mod.rs

@@ -4,6 +4,7 @@ use std::sync::{Arc, OnceLock, Weak};
 use std::time::Duration;
 
 use async_trait::async_trait;
+use core_api::message_meta::Attachment;
 use sqlx::SqlitePool;
 use tokio::sync::{Mutex, broadcast, mpsc};
 use tokio_util::sync::CancellationToken;
@@ -234,6 +235,32 @@ impl ChatHub {
         self.session_mgr.get_or_create_handler(session_id).await
     }
 
+    /// Persist an uploaded file for `source_id` into the owner's home
+    /// (`~/uploads/{session}/`) and return its [`Attachment`]. The single entry
+    /// point every surface (web handler, channel plugins) routes through, so
+    /// uploads can't drift on placement or on the recorded agent path — see
+    /// [`crate::uploads::save_to_home`]. Resolves the source's active session (so
+    /// the upload shares the directory the following message references).
+    pub async fn save_upload(
+        &self,
+        source_id: &str,
+        file_name: &str,
+        client_mime: Option<String>,
+        bytes: &[u8],
+    ) -> anyhow::Result<Attachment> {
+        let handler = self.session_handler(source_id).await?;
+        let fs = handler.user_fs();
+        let att = crate::uploads::save_to_home(
+            &fs,
+            handler.session_id,
+            file_name,
+            client_mime,
+            bytes,
+        )
+        .await?;
+        Ok(att)
+    }
+
     /// Returns the handler for a specific `session_id`, creating one lazily if needed.
     /// Used to resolve a pending tool against the session that actually owns it,
     /// independent of any source's "active" session.
@@ -781,6 +808,16 @@ impl ChatHubApi for ChatHub {
         self.send_message(source_id, prompt, opts).await
     }
 
+    async fn save_upload(
+        &self,
+        source_id: &str,
+        file_name: &str,
+        client_mime: Option<String>,
+        bytes: &[u8],
+    ) -> anyhow::Result<Attachment> {
+        self.save_upload(source_id, file_name, client_mime, bytes).await
+    }
+
     async fn clear(&self, source_id: &str) -> anyhow::Result<i64> {
         self.clear(source_id).await
     }

crates/skald-core/src/lib.rs

@@ -48,4 +48,5 @@ pub mod tool_discovery;
 pub mod tools;
 pub mod transcribe;
 pub mod tts;
+pub mod uploads;
 pub mod users;

crates/skald-core/src/session/handler/media.rs

@@ -10,8 +10,9 @@
 //! Promotion is deliberately strict: an attachment is inlined only when ALL of
 //! these hold —
 //! - the model has the modality's capability;
-//! - the file lives under `data/uploads/`, canonicalized (attachments saved
-//!   anywhere else, e.g. by the Telegram plugin, stay textual);
+//! - the file lives under the caller's `~/uploads/` (where the upload handler
+//!   saves it), resolved through their per-user filesystem — attachments stored
+//!   anywhere else stay textual;
 //! - the sniffed magic bytes match an allowed MIME — the client-supplied
 //!   `mimetype` is never trusted;
 //! - the per-file and per-turn byte/count budgets are not exhausted.
@@ -26,7 +27,7 @@ use tracing::debug;
 
 use core_api::message_meta::Attachment;
 use core_api::tool::MediaRef;
-use core_api::user_fs::UserFs;
+use core_api::user_fs::{UserFs, UPLOADS_SUBDIR};
 
 /// Max media parts inlined per turn.
 const MAX_MEDIA_PER_TURN: usize = 4;
@@ -108,22 +109,21 @@ pub struct MediaPartition {
 }
 
 /// Splits a message's attachments into inline media parts and leftovers.
-/// Files are resolved against the process working directory.
-pub async fn partition(attachments: &[Attachment], capabilities: &[String]) -> MediaPartition {
-    let base = std::env::current_dir().unwrap_or_default();
-    partition_under(attachments, capabilities, &base).await
-}
-
-/// [`partition`] with an explicit base directory (tests).
-pub async fn partition_under(
+///
+/// Each attachment path is resolved through the caller's per-user [`UserFs`] —
+/// the same resolver the fs-tools use, fail-closed on traversal / workspace
+/// escape — and inlined only when it lands under their `~/uploads/` directory,
+/// where the upload handler saves them. Attachments stored anywhere else (a
+/// path outside the home, or another surface's directory) stay textual.
+pub async fn partition(
     attachments: &[Attachment],
     capabilities: &[String],
-    base: &Path,
+    fs: &UserFs,
 ) -> MediaPartition {
     let capable = MODALITIES
         .iter()
         .any(|m| capabilities.iter().any(|c| c == m.capability));
-    let root = std::fs::canonicalize(base.join("data").join("uploads")).ok();
+    let root = std::fs::canonicalize(fs.home_host.join(UPLOADS_SUBDIR)).ok();
     if !capable || root.is_none() {
         return MediaPartition { parts: Vec::new(), rest: attachments.to_vec() };
     }
@@ -138,7 +138,7 @@ pub async fn partition_under(
             rest.push(a.clone());
             continue;
         }
-        match try_inline(a, capabilities, base, &root, total).await {
+        match try_inline(a, capabilities, fs, &root, total).await {
             Some((part, bytes)) => {
                 total += bytes;
                 parts.push(part);
@@ -150,16 +150,17 @@ pub async fn partition_under(
 }
 
 /// Promotes one uploaded attachment to a content part, or `None` when any check
-/// fails (logged at debug level; the caller keeps it on the textual path).
-/// Containment is against the uploads `root`; the rest is [`promote`].
+/// fails (logged at debug level; the caller keeps it on the textual path). The
+/// agent path is resolved through the per-user filesystem (fail-closed) and then
+/// re-checked to land under the uploads `root`; the rest is [`promote`].
 async fn try_inline(
     a: &Attachment,
     capabilities: &[String],
-    base: &Path,
+    fs: &UserFs,
     root: &Path,
     used_total: u64,
 ) -> Option<(Value, u64)> {
-    let abs = tokio::fs::canonicalize(base.join(&a.path)).await.ok()?;
+    let abs = crate::tools::fs::resolve_host_path(fs, &a.path).ok()?;
     if !abs.starts_with(root) {
         debug!(path = %a.path, "media not inlined: outside the uploads root");
         return None;
@@ -205,7 +206,7 @@ async fn promote(
 }
 
 /// Inline media a tool produced (e.g. `read_file` on an image) as content parts,
-/// for the current turn only. Mirrors [`partition_under`] but contains against the
+/// for the current turn only. Mirrors [`partition`] but contains against the
 /// caller's **workspace roots** (home + shared + projects + docs) rather than the
 /// uploads dir — the tool already resolved + contained the path, so this is a
 /// fail-closed re-check against a symlink swap since the read (§6). Same per-file,
@@ -395,11 +396,13 @@ mod tests {
     #[tokio::test]
     async fn partition_inlines_png_for_vision_model() {
         let tmp = std::env::temp_dir().join(format!("skald-media-{}", uuid::Uuid::new_v4()));
-        let dir = tmp.join("data/uploads/u/1");
+        let home = tmp.join("homes/u1");
+        let dir = home.join("uploads/1");
         tokio::fs::create_dir_all(&dir).await.unwrap();
         tokio::fs::write(dir.join("a.png"), png_bytes()).await.unwrap();
+        let fs = fs_home(&home);
 
-        let p = partition_under(&[att("data/uploads/u/1/a.png")], &caps(&["vision"]), &tmp).await;
+        let p = partition(&[att("uploads/1/a.png")], &caps(&["vision"]), &fs).await;
         assert!(p.rest.is_empty());
         assert_eq!(p.parts.len(), 1);
         let url = p.parts[0]["image_url"]["url"].as_str().unwrap();
@@ -411,27 +414,30 @@ mod tests {
     #[tokio::test]
     async fn partition_gates_on_capability_and_containment() {
         let tmp = std::env::temp_dir().join(format!("skald-media-{}", uuid::Uuid::new_v4()));
-        let dir = tmp.join("data/uploads/u/1");
+        let home = tmp.join("homes/u1");
+        let dir = home.join("uploads/1");
         tokio::fs::create_dir_all(&dir).await.unwrap();
         tokio::fs::write(dir.join("a.png"), png_bytes()).await.unwrap();
-        tokio::fs::write(tmp.join("secret.png"), png_bytes()).await.unwrap();
+        // A real image inside the home but OUTSIDE the uploads dir.
+        tokio::fs::write(home.join("secret.png"), png_bytes()).await.unwrap();
+        let fs = fs_home(&home);
 
         // No capability → everything stays textual.
-        let p = partition_under(&[att("data/uploads/u/1/a.png")], &caps(&[]), &tmp).await;
+        let p = partition(&[att("uploads/1/a.png")], &caps(&[]), &fs).await;
         assert_eq!(p.rest.len(), 1);
         assert!(p.parts.is_empty());
 
         // vision capability does not unlock video parts.
-        let p = partition_under(&[att("data/uploads/u/1/a.png")], &caps(&["video"]), &tmp).await;
+        let p = partition(&[att("uploads/1/a.png")], &caps(&["video"]), &fs).await;
         assert_eq!(p.rest.len(), 1);
 
-        // A real image outside the uploads root is never read inline.
-        let p = partition_under(&[att("secret.png")], &caps(&["vision"]), &tmp).await;
+        // A real image in the home but outside the uploads dir is never inlined.
+        let p = partition(&[att("secret.png")], &caps(&["vision"]), &fs).await;
         assert_eq!(p.rest.len(), 1);
         assert!(p.parts.is_empty());
 
-        // Traversal out of the root is rejected.
-        let p = partition_under(&[att("data/uploads/../../secret.png")], &caps(&["vision"]), &tmp).await;
+        // Traversal out of the workspace is rejected fail-closed.
+        let p = partition(&[att("uploads/../../secret.png")], &caps(&["vision"]), &fs).await;
         assert_eq!(p.rest.len(), 1);
         assert!(p.parts.is_empty());
 
@@ -441,15 +447,16 @@ mod tests {
     #[tokio::test]
     async fn partition_enforces_count_budget() {
         let tmp = std::env::temp_dir().join(format!("skald-media-{}", uuid::Uuid::new_v4()));
-        let dir = tmp.join("data/uploads/u/1");
+        let home = tmp.join("homes/u1");
+        let dir = home.join("uploads/1");
         tokio::fs::create_dir_all(&dir).await.unwrap();
         let mut atts = Vec::new();
         for i in 0..(MAX_MEDIA_PER_TURN + 2) {
-            let rel = format!("data/uploads/u/1/{i}.png");
             tokio::fs::write(dir.join(format!("{i}.png")), png_bytes()).await.unwrap();
-            atts.push(att(&rel));
+            atts.push(att(&format!("uploads/1/{i}.png")));
         }
-        let p = partition_under(&atts, &caps(&["vision"]), &tmp).await;
+        let fs = fs_home(&home);
+        let p = partition(&atts, &caps(&["vision"]), &fs).await;
         assert_eq!(p.parts.len(), MAX_MEDIA_PER_TURN);
         assert_eq!(p.rest.len(), 2);
 
@@ -465,12 +472,14 @@ mod tests {
     #[tokio::test]
     async fn partition_inlines_pdf_as_file_part_for_document_model() {
         let tmp = std::env::temp_dir().join(format!("skald-media-{}", uuid::Uuid::new_v4()));
-        let dir = tmp.join("data/uploads/u/1");
+        let home = tmp.join("homes/u1");
+        let dir = home.join("uploads/1");
         tokio::fs::create_dir_all(&dir).await.unwrap();
         tokio::fs::write(dir.join("a.pdf"), pdf_bytes()).await.unwrap();
+        let fs = fs_home(&home);
 
         // A document-capable model inlines the PDF as the OpenAI `file` part shape.
-        let p = partition_under(&[att("data/uploads/u/1/a.pdf")], &caps(&["document"]), &tmp).await;
+        let p = partition(&[att("uploads/1/a.pdf")], &caps(&["document"]), &fs).await;
         assert!(p.rest.is_empty());
         assert_eq!(p.parts.len(), 1);
         assert_eq!(p.parts[0]["type"], "file");
@@ -479,7 +488,7 @@ mod tests {
         assert!(fd.starts_with("data:application/pdf;base64,"), "{fd}");
 
         // vision alone does not unlock PDFs.
-        let p = partition_under(&[att("data/uploads/u/1/a.pdf")], &caps(&["vision"]), &tmp).await;
+        let p = partition(&[att("uploads/1/a.pdf")], &caps(&["vision"]), &fs).await;
         assert_eq!(p.rest.len(), 1);
         assert!(p.parts.is_empty());
 

crates/skald-core/src/session/handler/message_builder.rs

@@ -258,8 +258,14 @@ impl MessageBuilder {
                     // textual path block, generated on the fly and never
                     // persisted as content.
                     let (text, media) = match &entry.metadata {
-                        Some(meta) if !meta.attachments.is_empty() && idx >= media_turn_start => {
-                            let partition = super::media::partition(&meta.attachments, capabilities).await;
+                        Some(meta)
+                            if !meta.attachments.is_empty()
+                                && idx >= media_turn_start
+                                && self.fs.is_some() =>
+                        {
+                            let fs = self.fs.as_deref().expect("guarded by is_some()");
+                            let partition =
+                                super::media::partition(&meta.attachments, capabilities, fs).await;
                             (
                                 format!(
                                     "{}{}",

crates/skald-core/src/session/handler/mod.rs

@@ -20,7 +20,7 @@ use crate::config::DatetimeConfig;
 use crate::db::{chat_history, chat_sessions_stack};
 use crate::events::ServerEvent;
 use core_api::message_meta::MessageMetadata;
-use core_api::user_fs::SharedFs;
+use core_api::user_fs::{SharedFs, UserFs};
 use crate::llm::LlmManager;
 use crate::mcp::McpProvider;
 use crate::image_generate::ImageGeneratorManager;
@@ -414,6 +414,13 @@ impl ChatSessionHandler {
         }
     }
 
+    /// The caller's current filesystem snapshot (home + shared folders + projects
+    /// + docs). Cheap — clones an `Arc`. Used by upload persistence to place files
+    /// in the owner's home.
+    pub fn user_fs(&self) -> Arc<UserFs> {
+        self.fs.load()
+    }
+
     /// Override the session used for scratchpad reads/writes.
     /// Called by the cron runner for async tasks so they share the parent's scratchpad.
     pub fn set_scratchpad_session_id(&self, id: i64) {

crates/skald-core/src/uploads.rs

@@ -0,0 +1,154 @@
+//! Centralized upload persistence.
+//!
+//! The single place any surface — the web `POST /uploads` handler, a channel
+//! plugin like Telegram, or a future one — turns received file bytes into a
+//! saved [`Attachment`]. Keeping placement + naming + metadata here means no two
+//! callers can drift on *where* an upload lands or *what* path is recorded (the
+//! bug this fixes: uploads that the agent then couldn't reach).
+//!
+//! Files are written into the user's private container home under
+//! `uploads/{session_id}/…`. That single agent path is resolved identically by
+//! every consumer — the fs-tools, `execute_cmd` (the home is bind-mounted at
+//! `/root`), the file viewer (`/api/file`) and the media inliner — through the
+//! same per-user [`UserFs`].
+
+use std::path::{Path, PathBuf};
+
+use core_api::message_meta::Attachment;
+use core_api::user_fs::{UserFs, UPLOADS_SUBDIR};
+
+use crate::session::handler::media::sniff_mime;
+
+/// Persist `bytes` as a file named `file_name` into the user's
+/// `~/uploads/{session_id}/`, returning the resulting [`Attachment`] whose `path`
+/// is the home-relative agent path. The recognized magic-byte MIME wins over the
+/// caller-claimed `client_mime`.
+///
+/// The caller owns byte transport (streaming a multipart body, downloading from
+/// an API) and any size cap; this owns placement, collision-safe naming, MIME
+/// sniffing and the metadata shape.
+pub async fn save_to_home(
+    fs: &UserFs,
+    session_id: i64,
+    file_name: &str,
+    client_mime: Option<String>,
+    bytes: &[u8],
+) -> std::io::Result<Attachment> {
+    let dir_host = fs
+        .home_host
+        .join(UPLOADS_SUBDIR)
+        .join(session_id.to_string());
+    tokio::fs::create_dir_all(&dir_host).await?;
+
+    let (abs_path, final_name) = unique_target(&dir_host, &sanitize_filename(file_name));
+    tokio::fs::write(&abs_path, bytes).await?;
+
+    // The sniffed type wins over the client claim when we recognize the bytes.
+    let mimetype = sniff_mime(&bytes[..bytes.len().min(16)])
+        .map(str::to_string)
+        .or(client_mime);
+
+    Ok(Attachment {
+        path:     format!("{UPLOADS_SUBDIR}/{session_id}/{final_name}"),
+        name:     final_name,
+        mimetype,
+        filesize: Some(bytes.len() as u64),
+    })
+}
+
+/// Reduces an arbitrary client filename to a safe basename: directory components
+/// are dropped and an empty/`.`/`..` result falls back to `"file"`.
+fn sanitize_filename(raw: &str) -> String {
+    let base = Path::new(raw)
+        .file_name()
+        .and_then(|n| n.to_str())
+        .unwrap_or("")
+        .trim();
+    if base.is_empty() || base == "." || base == ".." {
+        "file".to_string()
+    } else {
+        base.to_string()
+    }
+}
+
+/// Returns a non-colliding `(absolute_path, final_name)` inside `dir`. If `name`
+/// already exists, inserts `_1`, `_2`, … before the extension.
+fn unique_target(dir: &Path, name: &str) -> (PathBuf, String) {
+    let candidate = dir.join(name);
+    if !candidate.exists() {
+        return (candidate, name.to_string());
+    }
+    let path = Path::new(name);
+    let stem = path.file_stem().and_then(|s| s.to_str()).unwrap_or(name);
+    let ext = path.extension().and_then(|s| s.to_str());
+    for n in 1.. {
+        let next = match ext {
+            Some(ext) => format!("{stem}_{n}.{ext}"),
+            None => format!("{stem}_{n}"),
+        };
+        let candidate = dir.join(&next);
+        if !candidate.exists() {
+            return (candidate, next);
+        }
+    }
+    unreachable!("unique_target loop always returns")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// A throwaway [`UserFs`] whose private home is `home`.
+    fn fs_home(home: &Path) -> UserFs {
+        UserFs::new(
+            "u1",
+            home.to_path_buf(),
+            "skald-u1",
+            PathBuf::from("/root"),
+            vec![],
+            vec![],
+            None,
+        )
+    }
+
+    fn pdf_bytes() -> Vec<u8> {
+        let mut v = b"%PDF-1.7\n".to_vec();
+        v.extend_from_slice(&[0x00; 32]);
+        v
+    }
+
+    #[tokio::test]
+    async fn saves_into_home_uploads_with_agent_path_and_sniffs_mime() {
+        let tmp = std::env::temp_dir().join(format!("skald-upload-{}", uuid::Uuid::new_v4()));
+        let home = tmp.join("homes/u1");
+        tokio::fs::create_dir_all(&home).await.unwrap();
+        let fs = fs_home(&home);
+
+        // A wrong client MIME is overridden by the sniffed PDF signature.
+        let att = save_to_home(&fs, 7, "cv.pdf", Some("application/octet-stream".into()), &pdf_bytes())
+            .await
+            .unwrap();
+
+        assert_eq!(att.path, "uploads/7/cv.pdf");
+        assert_eq!(att.name, "cv.pdf");
+        assert_eq!(att.mimetype.as_deref(), Some("application/pdf"));
+        assert_eq!(att.filesize, Some(pdf_bytes().len() as u64));
+        // Physically lands under the home's uploads dir (reachable by the agent).
+        assert!(home.join("uploads/7/cv.pdf").exists());
+
+        // A second upload of the same name never overwrites — it is de-duped.
+        let att2 = save_to_home(&fs, 7, "cv.pdf", None, &pdf_bytes()).await.unwrap();
+        assert_eq!(att2.path, "uploads/7/cv_1.pdf");
+        assert!(home.join("uploads/7/cv_1.pdf").exists());
+
+        let _ = tokio::fs::remove_dir_all(&tmp).await;
+    }
+
+    #[test]
+    fn sanitize_strips_directory_components() {
+        assert_eq!(sanitize_filename("../../etc/passwd"), "passwd");
+        assert_eq!(sanitize_filename("a/b/c.txt"), "c.txt");
+        assert_eq!(sanitize_filename(".."), "file");
+        assert_eq!(sanitize_filename(""), "file");
+    }
+}