Phase 3: pausable command lifecycle (pause / resume / cancel)

crates/tui/src/commands/user_commands.rs

@@ -6,7 +6,7 @@
 //! `/name`, the file contents are sent as a user message.
 //!
 //! Files may include optional YAML-like frontmatter between `---` markers.
-//! Supported fields are `description`, `argument-hint`, and `allowed-tools`.
+//! Supported fields are `description`, `argument-hint`, `allowed-tools`, and `pausable`.
 //! Frontmatter is stripped before the command body is sent to the model.
 //!
 //! ## Precedence
@@ -206,6 +206,25 @@ pub fn try_dispatch_user_command(app: &mut App, input: &str) -> Option<CommandRe
             app.hunt.verdict = HuntVerdict::Hunting;
             app.hunt.token_budget = None;
             app.active_allowed_tools = None;
+            // Clear todos and plan state from the previous command.
+            match app.todos.try_lock() {
+                Ok(mut todos) => todos.clear(),
+                Err(_) => {
+                    tracing::warn!(target: "pausable", "todos lock contended or poisoned — state not cleared");
+                }
+            }
+            match app.plan_state.try_lock() {
+                Ok(mut plan) => *plan = crate::tools::plan::PlanState::default(),
+                Err(_) => {
+                    tracing::warn!(target: "pausable", "plan_state lock contended or poisoned — state not cleared");
+                }
+            }
+            // Clear any previous pause state — new command, fresh start.
+            app.paused = false;
+            app.pausable = false;
+            app.paused_cancelled = false;
+            app.paused_at = None;
+            app.active_snapshot = None;
             for (key, value) in &metadata {
                 match key.as_str() {
                     "description" => {
@@ -215,6 +234,45 @@ pub fn try_dispatch_user_command(app: &mut App, input: &str) -> Option<CommandRe
                     "allowed-tools" => {
                         app.active_allowed_tools = Some(parse_allowed_tools(value));
                     }
+                    "pausable" if value.trim().eq_ignore_ascii_case("true") => {
+                        // Snapshot workspace for potential rollback via git stash
+                        if let Some(snap_id) = app.active_snapshot.take()
+                            && let Ok(repo) =
+                                crate::snapshot::repo::SnapshotRepo::open_or_init(&app.workspace)
+                        {
+                            let _ = repo.restore(&crate::snapshot::repo::SnapshotId(snap_id));
+                        }
+                        let git_stash_cmd = std::process::Command::new("git")
+                            .args([
+                                "-C",
+                                &app.workspace.to_string_lossy(),
+                                "stash",
+                                "push",
+                                "--include-untracked",
+                                "-m",
+                                "codewhale-pausable",
+                            ])
+                            .output();
+                        if let Ok(output) = git_stash_cmd {
+                            if output.status.success() {
+                                tracing::debug!(target: "pausable", "created git stash snapshot");
+                            } else {
+                                let stderr = String::from_utf8_lossy(&output.stderr);
+                                tracing::warn!(target: "pausable", "git stash failed: {stderr}");
+                            }
+                        }
+                        app.pausable = true;
+                        app.paused = false;
+                        app.paused_cancelled = false;
+                    }
+                    "pausable" => {
+                        // Explicitly set pausable: false
+                        app.pausable = false;
+                        app.paused = false;
+                        app.paused_cancelled = false;
+                        app.active_snapshot = None;
+                        tracing::debug!(target: "pausable", "pausable explicitly set to false");
+                    }
                     _ => {}
                 }
             }

crates/tui/src/core/engine.rs

@@ -439,6 +439,9 @@ pub struct EngineHandle {
     tx_user_input: mpsc::Sender<UserInputDecision>,
     /// Send steer input for an in-flight turn.
     tx_steer: mpsc::Sender<String>,
+    /// Shared paused flag — set by the UI, read by the turn loop.
+    /// Uses the same pattern as `cancel_token` to bypass the Op channel.
+    pub shared_paused: Arc<StdMutex<bool>>,
 }
 
 // `impl EngineHandle { ... }` moved to `engine/handle.rs` so the
@@ -505,6 +508,9 @@ pub struct Engine {
     slop_ledger_gate_cache: Option<(Option<SystemTime>, Option<String>)>,
     /// Current operating mode. Updated on `ChangeMode` and `SendMessage`.
     current_mode: AppMode,
+    /// Shared paused flag — set by the UI (via EngineHandle::set_paused),
+    /// read by the turn-loop pause gate.
+    shared_paused: Arc<StdMutex<bool>>,
 }
 
 // === Internal tool helpers ===
@@ -591,6 +597,7 @@ impl Engine {
         let cancel_token = CancellationToken::new();
         let shared_cancel_token = Arc::new(StdMutex::new(cancel_token.clone()));
         let cancel_reason: Arc<StdMutex<Option<CancelReason>>> = Arc::new(StdMutex::new(None));
+        let shared_paused = Arc::new(StdMutex::new(false));
         let tool_exec_lock = Arc::new(RwLock::new(()));
 
         // Create clients for both providers
@@ -752,6 +759,7 @@ impl Engine {
             workshop_vars,
             sandbox_backend,
             current_mode: AppMode::Agent,
+            shared_paused: shared_paused.clone(),
         };
         engine.rehydrate_latest_canonical_state();
 
@@ -760,6 +768,7 @@ impl Engine {
             rx_event: Arc::new(RwLock::new(rx_event)),
             cancel_token: shared_cancel_token,
             cancel_reason,
+            shared_paused,
             tx_approval,
             tx_user_input,
             tx_steer,
@@ -2606,11 +2615,13 @@ pub(crate) fn mock_engine_handle() -> MockEngineHandle {
     let cancel_token = CancellationToken::new();
     let shared_cancel_token = Arc::new(StdMutex::new(cancel_token.clone()));
     let cancel_reason: Arc<StdMutex<Option<CancelReason>>> = Arc::new(StdMutex::new(None));
+    let shared_paused = Arc::new(StdMutex::new(false));
     let handle = EngineHandle {
         tx_op,
         rx_event: Arc::new(RwLock::new(rx_event)),
         cancel_token: shared_cancel_token,
         cancel_reason,
+        shared_paused,
         tx_approval,
         tx_user_input,
         tx_steer,

crates/tui/src/core/engine/handle.rs

@@ -110,4 +110,21 @@ impl EngineHandle {
         self.tx_steer.send(content.into()).await?;
         Ok(())
     }
+
+    /// Pause or resume the current command (for pausable commands).
+    /// Sets a shared flag that the turn loop reads before every tool call.
+    /// Uses the same side-channel pattern as `cancel()` — bypasses the Op
+    /// channel so it takes effect immediately, even during a running turn.
+    pub fn set_paused(&self, paused: bool) {
+        match self.shared_paused.lock() {
+            Ok(mut slot) => {
+                *slot = paused;
+                tracing::debug!(target: "pausable", paused, "EngineHandle::set_paused");
+            }
+            Err(poisoned) => *poisoned.into_inner() = paused,
+        }
+        // Note: Op::SetPaused was removed — the shared flag is the single
+        // source of truth. Sending an Op would make the engine fire a status
+        // event that races with cancel/continue status from the UI.
+    }
 }

crates/tui/src/core/engine/turn_loop.rs

@@ -1357,6 +1357,16 @@ impl Engine {
                     )));
                 }
 
+                // Pause gate: when the command is paused, cancel the turn
+                // instead of returning a tool error. Returning a tool error
+                // causes the model to try alternative approaches; cancelling
+                // the turn cleanly stops all execution.
+                let is_paused = self.shared_paused.lock().is_ok_and(|g| *g);
+                tracing::debug!(target: "pausable", is_paused, tool_name, "pause gate check");
+                if blocked_error.is_none() && is_paused {
+                    self.cancel_token.cancel();
+                }
+
                 if blocked_error.is_none()
                     && let Some(hook_executor) = self.config.hook_executor.as_ref()
                     && hook_executor.has_hooks_for_event(crate::hooks::HookEvent::ToolCallBefore)

crates/tui/src/tools/shell.rs

@@ -269,6 +269,7 @@ impl WindowsJob {
             )
             .map_err(windows_io_error)?;
 
+            #[allow(clippy::unnecessary_cast)]
             let process_handle = HANDLE(child.as_raw_handle() as *mut core::ffi::c_void);
             AssignProcessToJobObject(job.handle, process_handle).map_err(windows_io_error)?;
         }

crates/tui/src/tui/app.rs

@@ -1174,6 +1174,18 @@ pub struct App {
     /// Active tool restriction from custom slash command frontmatter.
     /// `None` means the current turn may use the normal tool set.
     pub active_allowed_tools: Option<Vec<String>>,
+    /// Whether the current pausable command is paused (ESC once).
+    pub paused: bool,
+    /// Timestamp of the last pause (for ESC debounce).
+    pub paused_at: Option<std::time::Instant>,
+    /// Whether the active command has `pausable: true` in frontmatter.
+    pub pausable: bool,
+    /// Whether the last pausable command was cancelled.
+    pub paused_cancelled: bool,
+    /// Snapshot ID for rollback of a pausable command.
+    pub active_snapshot: Option<String>,
+    /// Saved hunt.quarry from before pause — restored on "continue".
+    pub paused_quarry: Option<String>,
     pub history: Vec<HistoryCell>,
     pub history_version: u64,
     /// Per-cell revision counter, kept in lockstep with `history`.
@@ -1985,6 +1997,12 @@ impl App {
             hunt: HuntState::default(),
             session: SessionState::default(),
             active_allowed_tools: None,
+            paused: false,
+            paused_at: None,
+            pausable: false,
+            paused_cancelled: false,
+            active_snapshot: None,
+            paused_quarry: None,
             history: Vec::new(),
             history_version: 0,
             history_revisions: Vec::new(),

crates/tui/src/tui/composer_ui.rs

@@ -8,6 +8,7 @@ const COMPOSER_ARROW_SCROLL_LINES: usize = 3;
 pub(crate) enum EscapeAction {
     CloseSlashMenu,
     CancelRequest,
+    PauseCommand,
     DiscardQueuedDraft,
     ClearInput,
     Noop,
@@ -16,8 +17,16 @@ pub(crate) enum EscapeAction {
 pub(crate) fn next_escape_action(app: &App, slash_menu_open: bool) -> EscapeAction {
     if slash_menu_open {
         EscapeAction::CloseSlashMenu
-    } else if app.is_loading || matches!(app.runtime_turn_status.as_deref(), Some("in_progress")) {
-        EscapeAction::CancelRequest
+    } else if app.is_loading
+        || matches!(app.runtime_turn_status.as_deref(), Some("in_progress"))
+        || app.pausable
+        || app.paused
+    {
+        if app.pausable && !app.paused {
+            EscapeAction::PauseCommand
+        } else {
+            EscapeAction::CancelRequest
+        }
     } else if app.queued_draft.is_some() && app.input.is_empty() {
         EscapeAction::DiscardQueuedDraft
     } else if !app.input.is_empty() {