feat(tools): add max_snapshot_bytes limit to transactional ShellExecutor

Add `max_snapshot_bytes: u64` to `ShellConfig` (default 0 = unlimited).
`TransactionSnapshot::capture()` now tracks cumulative bytes and aborts
with `ToolError::SnapshotFailed` if the configured limit is exceeded,
preventing disk exhaustion from unbounded snapshot copies.

Closes #2474

Author: bug-ops

CHANGELOG.md

@@ -8,6 +8,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### Added
 
+- feat(tools): `[tools.shell] max_snapshot_bytes` config option to limit transaction snapshot size — returns `SnapshotFailed` when cumulative copied bytes exceed the limit; `0` means unlimited (default)
 - feat(tools): transactional `ShellExecutor` — opt-in snapshot+rollback for shell commands; file-level snapshot is captured before write commands (detected via `WRITE_INDICATORS` heuristic + redirection target extraction); rollback restores originals on configurable exit codes; new `ShellConfig` fields: `transactional`, `transaction_scope` (glob-filtered paths), `auto_rollback`, `auto_rollback_exit_codes`, `snapshot_required`; new `ToolError::SnapshotFailed`, `AuditResult::Rollback`, `ToolEvent::Rollback` variants; backed by `tempfile::TempDir` for automatic cleanup on success (closes #2414)
 - feat(core): `/new` slash command — resets conversation context (messages, compaction state, tool caches, focus/sidequest, pending plans) while preserving memory, MCP connections, providers, and skills; creates a new `ConversationId` in SQLite for audit trail; generates a session digest for the outgoing conversation fire-and-forget unless `--no-digest` is passed; active sub-agents and background compression tasks are cancelled; `--keep-plan` preserves a pending plan graph; available in all channels (CLI, TUI, Telegram) via the unified `handle_builtin_command` path (closes #2451)
 - feat(memory): Kumiho AGM-inspired belief revision for graph edges — new `BeliefRevisionConfig` with `similarity_threshold`; `find_superseded_edges()` uses contradiction heuristic (same relation domain + high cosine similarity = supersession); `superseded_by` column added to `graph_edges` for audit trail; `invalidate_edge_with_supersession()` in `GraphStore`; `resolve_edge_typed` accepts optional `BeliefRevisionConfig`; controlled by `[memory.graph.belief_revision] enabled = false` (migration 056, closes #2441)

crates/zeph-tools/src/config.rs

@@ -520,6 +520,9 @@ pub struct ShellConfig {
     /// When false (default), snapshot failure emits a warning and execution proceeds.
     #[serde(default)]
     pub snapshot_required: bool,
+    /// Maximum cumulative bytes for transaction snapshots. 0 = unlimited.
+    #[serde(default)]
+    pub max_snapshot_bytes: u64,
 }
 
 impl ShellConfig {
@@ -588,6 +591,7 @@ impl Default for ShellConfig {
             auto_rollback: false,
             auto_rollback_exit_codes: Vec::new(),
             snapshot_required: false,
+            max_snapshot_bytes: 0,
         }
     }
 }

crates/zeph-tools/src/shell/mod.rs

@@ -112,6 +112,7 @@ pub struct ShellExecutor {
     auto_rollback: bool,
     auto_rollback_exit_codes: Vec<i32>,
     snapshot_required: bool,
+    max_snapshot_bytes: u64,
     transaction_scope_matchers: Vec<globset::GlobMatcher>,
 }
 
@@ -165,6 +166,7 @@ impl ShellExecutor {
             auto_rollback: config.auto_rollback,
             auto_rollback_exit_codes: config.auto_rollback_exit_codes.clone(),
             snapshot_required: config.snapshot_required,
+            max_snapshot_bytes: config.max_snapshot_bytes,
             transaction_scope_matchers: build_scope_matchers(&config.transaction_scope),
         }
     }
@@ -285,7 +287,7 @@ impl ShellExecutor {
             if paths.is_empty() {
                 None
             } else {
-                match TransactionSnapshot::capture(&paths) {
+                match TransactionSnapshot::capture(&paths, self.max_snapshot_bytes) {
                     Ok(snap) => {
                         tracing::debug!(
                             files = snap.file_count(),

crates/zeph-tools/src/shell/tests.rs

@@ -17,6 +17,7 @@ fn default_config() -> ShellConfig {
         auto_rollback: false,
         auto_rollback_exit_codes: Vec::new(),
         snapshot_required: false,
+        max_snapshot_bytes: 0,
     }
 }
 
@@ -1710,7 +1711,7 @@ fn transaction_snapshot_capture_and_rollback() {
     std::fs::write(&file, b"original").unwrap();
 
     let snap =
-        super::transaction::TransactionSnapshot::capture(std::slice::from_ref(&file)).unwrap();
+        super::transaction::TransactionSnapshot::capture(std::slice::from_ref(&file), 0).unwrap();
     assert_eq!(snap.file_count(), 1);
 
     std::fs::write(&file, b"modified").unwrap();
@@ -1726,7 +1727,7 @@ fn transaction_snapshot_new_file_rollback() {
     let file = dir.path().join("new.txt");
 
     let snap =
-        super::transaction::TransactionSnapshot::capture(std::slice::from_ref(&file)).unwrap();
+        super::transaction::TransactionSnapshot::capture(std::slice::from_ref(&file), 0).unwrap();
     assert_eq!(snap.file_count(), 1);
 
     std::fs::write(&file, b"created").unwrap();
@@ -1738,7 +1739,7 @@ fn transaction_snapshot_new_file_rollback() {
 
 #[test]
 fn transaction_snapshot_empty_paths() {
-    let snap = super::transaction::TransactionSnapshot::capture(&[]).unwrap();
+    let snap = super::transaction::TransactionSnapshot::capture(&[], 0).unwrap();
     assert_eq!(snap.file_count(), 0);
     assert_eq!(snap.total_bytes(), 0);
     let report = snap.rollback().unwrap();
@@ -2187,3 +2188,42 @@ async fn custom_rollback_exit_codes() {
     let content2 = std::fs::read(&file).unwrap();
     assert_eq!(content2, b"original", "exit 42 should trigger rollback");
 }
+
+// --- snapshot size limit tests ---
+
+#[test]
+fn transaction_snapshot_size_limit_exceeded() {
+    use crate::shell::transaction::TransactionSnapshot;
+    let dir = tempfile::TempDir::new().unwrap();
+    let file = dir.path().join("big.txt");
+    // Write 100 bytes
+    std::fs::write(&file, vec![b'x'; 100]).unwrap();
+
+    let result = TransactionSnapshot::capture(&[file], 50);
+    assert!(result.is_err());
+    let msg = result.unwrap_err().to_string();
+    assert!(msg.contains("exceeds limit"), "unexpected error: {msg}");
+}
+
+#[test]
+fn transaction_snapshot_size_limit_zero_unlimited() {
+    use crate::shell::transaction::TransactionSnapshot;
+    let dir = tempfile::TempDir::new().unwrap();
+    let file = dir.path().join("big.txt");
+    std::fs::write(&file, vec![b'x'; 1_000_000]).unwrap();
+
+    // max_bytes = 0 means unlimited — must succeed
+    let result = TransactionSnapshot::capture(&[file], 0);
+    assert!(result.is_ok());
+}
+
+#[test]
+fn transaction_snapshot_size_limit_within_budget() {
+    use crate::shell::transaction::TransactionSnapshot;
+    let dir = tempfile::TempDir::new().unwrap();
+    let file = dir.path().join("small.txt");
+    std::fs::write(&file, b"hello").unwrap();
+
+    let result = TransactionSnapshot::capture(&[file], 1024);
+    assert!(result.is_ok());
+}

crates/zeph-tools/src/shell/transaction.rs

@@ -51,13 +51,17 @@ impl TransactionSnapshot {
     /// Capture files at `paths`.
     ///
     /// Non-existent paths are recorded as "new" (rollback will delete them if created).
+    /// If `max_bytes > 0` and the cumulative size of copied files exceeds `max_bytes`,
+    /// an error is returned immediately.
     ///
     /// # Errors
     ///
-    /// Returns `std::io::Error` if the temp directory or any file copy fails.
-    pub(crate) fn capture(paths: &[PathBuf]) -> Result<Self, std::io::Error> {
+    /// Returns `std::io::Error` if the temp directory, any file copy fails, or the
+    /// snapshot size limit is exceeded.
+    pub(crate) fn capture(paths: &[PathBuf], max_bytes: u64) -> Result<Self, std::io::Error> {
         let backup_dir = tempfile::TempDir::new()?;
         let mut entries = Vec::with_capacity(paths.len());
+        let mut cumulative_bytes: u64 = 0;
 
         for (i, original) in paths.iter().enumerate() {
             // Use symlink_metadata to avoid following symlinks — snapshot only regular files.
@@ -91,6 +95,13 @@ impl TransactionSnapshot {
             let meta = std::fs::metadata(original)?;
             std::fs::set_permissions(&backup_path, meta.permissions())?;
 
+            cumulative_bytes += meta.len();
+            if max_bytes > 0 && cumulative_bytes > max_bytes {
+                return Err(std::io::Error::other(format!(
+                    "snapshot size {cumulative_bytes} exceeds limit {max_bytes}"
+                )));
+            }
+
             entries.push(SnapshotEntry {
                 original: original.clone(),
                 kind: EntryKind::Existing { backup_path },