Skip to content

feat(tools): transactional ShellExecutor with snapshot+rollback (#2414)#2473

Merged
bug-ops merged 2 commits intomainfrom
transactional-shell-executor
Mar 30, 2026
Merged

feat(tools): transactional ShellExecutor with snapshot+rollback (#2414)#2473
bug-ops merged 2 commits intomainfrom
transactional-shell-executor

Conversation

@bug-ops
Copy link
Copy Markdown
Owner

@bug-ops bug-ops commented Mar 30, 2026

Summary

  • Add opt-in snapshot+rollback to ShellExecutor for atomic file operations (closes research(tools): transactional ShellExecutor — snapshot+rollback for atomic file operations (arXiv:2512.12806) #2414)
  • New transaction.rs module: TransactionSnapshot captures filesystem state before write commands and restores on failure
  • Shell redirection targets (>, >>, 2>, 2>>, &>, &>>) are parsed and included in snapshot scope
  • Symlinks are detected and skipped during snapshot to prevent traversal outside sandbox
  • rollback() attempts all file restores before returning error (no early-exit on partial failure)

New config fields ([tools.shell])

transactional = false              # opt-in snapshot+rollback
transaction_scope = []             # glob patterns; empty = all affected paths
auto_rollback = false              # restore snapshot on exit code >= 2
auto_rollback_exit_codes = []      # explicit exit codes that trigger rollback
snapshot_required = false          # abort execution if snapshot creation fails

Integration points

  • --init wizard: prompts for transactional and auto_rollback
  • --migrate-config: Step 6 handles new optional fields
  • TUI: ToolEvent::Rollback surfaced as status indicator via tui_bridge
  • Audit: new AuditResult::Rollback variant logged to audit trail

Test plan

  • 903 tests pass (18 new covering: snapshot/rollback, redirection parsing, scope filtering, exit code semantics, snapshot failure modes, symlink skipping, partial rollback error collection)
  • cargo +nightly fmt --check clean
  • cargo clippy -- -D warnings clean

Follow-up issues to file after merge

  • Snapshot size limit (max_snapshot_bytes config field) — security audit MEDIUM
  • Symlink rollback write risk — security audit MEDIUM (symlinks currently skipped at capture; rollback is safe)

@bug-ops bug-ops added the tools Tool execution and MCP integration label Mar 30, 2026
@github-actions github-actions bot added documentation Improvements or additions to documentation rust Rust code changes dependencies Dependency updates enhancement New feature or request labels Mar 30, 2026
@bug-ops bug-ops enabled auto-merge (squash) March 30, 2026 21:19
@github-actions github-actions bot added the size/XL Extra large PR (500+ lines) label Mar 30, 2026
bug-ops added 2 commits March 30, 2026 23:34
Add opt-in snapshot+rollback to ShellExecutor for atomic file operations.
Before executing write commands, capture filesystem snapshots of affected
paths; restore on failure if auto_rollback is enabled.

New config fields on ShellConfig:
- transactional: bool (default false)
- transaction_scope: Vec<String> glob patterns (empty = all paths)
- auto_rollback: bool (default false, triggers on exit code >= 2)
- auto_rollback_exit_codes: Vec<i32> explicit exit code list
- snapshot_required: bool (default false, abort execution on snapshot failure)

New module: zeph-tools/src/shell/transaction.rs
- TransactionSnapshot using tempfile::TempDir for automatic cleanup
- extract_redirection_targets() parses >, >>, 2>, 2>>, &>, &>> operators
- affected_paths() combines path extraction + glob scope filtering
- capture() detects and skips symlinks to prevent traversal
- rollback() restores all files, collecting errors without early return

Integration:
- execute_block() snapshots before execution, rollbacks on condition
- AuditResult::Rollback and ToolEvent::Rollback variants for audit/TUI
- TUI bridge handles Rollback as AgentEvent::Status
- --init wizard prompts for transactional/auto_rollback settings
- --migrate-config Step 6 acknowledges new optional shell fields

903 tests pass (18 new).
@bug-ops bug-ops force-pushed the transactional-shell-executor branch from 5f6ed20 to 0bbe099 Compare March 30, 2026 21:34
@bug-ops bug-ops merged commit 41cbd7d into main Mar 30, 2026
27 checks passed
@bug-ops bug-ops deleted the transactional-shell-executor branch March 30, 2026 21:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

dependencies Dependency updates documentation Improvements or additions to documentation enhancement New feature or request rust Rust code changes size/XL Extra large PR (500+ lines) tools Tool execution and MCP integration

Projects

None yet

Development

Successfully merging this pull request may close these issues.

research(tools): transactional ShellExecutor — snapshot+rollback for atomic file operations (arXiv:2512.12806)

1 participant