Enhance logging and documentation across utility tools and TUI overlays

- Added tracing instrumentation and improved logging messages in the Pong, Todofinish, and Todowrite tools for better debugging and monitoring.
- Enhanced documentation comments for clarity on tool functionalities and workflows.
- Implemented tracing in WorkflowRun, NoteFinding, ReadFindings, and HiveMind tools to track execution phases and findings.
- Updated TUI overlays (e.g., Bash, Clear Confirm, Editor, Effort Level, Help, Key Input, Learning, Loading, MCP, Model Selector, Plan, Quit Confirm, Rewind, Settings, Todo, Usage) with debug logging to capture rendering details.
- Improved the status bar and workflow panel rendering with additional debug information.
- Added tracing to various utility functions to facilitate better performance monitoring and error tracking.

apps/infrastructure/src/tools/mod.rs

@@ -12,6 +12,7 @@ use sha2::Digest;
 use std::path::PathBuf;
 use std::sync::atomic::AtomicBool;
 use std::sync::{Arc, Mutex};
+use tracing::{debug, info, instrument, warn};
 
 pub mod bash_tools;
 pub mod fs;
@@ -220,12 +221,18 @@ pub fn arg_str(args: &Value, name: &str) -> Result<String> {
 }
 
 /// Execute a `std::process::Command` and return its combined stdout/stderr.
+///
+/// Flow: spawn → collect stdout + stderr → check exit code → return combined output
+/// or bail with the error message.
+#[instrument(skip(cmd))]
 pub fn execute_cmd(cmd: &mut std::process::Command) -> Result<String> {
     let output = cmd
         .output()
         .map_err(|e| anyhow::anyhow!("command execution failed: {e}"))?;
     let stdout = String::from_utf8_lossy(&output.stdout).trim().to_string();
     let stderr = String::from_utf8_lossy(&output.stderr).trim().to_string();
+    let stdout_len = stdout.len();
+    let stderr_len = stderr.len();
     let combined = if stderr.is_empty() {
         stdout
     } else {
@@ -233,16 +240,22 @@ pub fn execute_cmd(cmd: &mut std::process::Command) -> Result<String> {
             .trim()
             .to_string()
     };
+    let code = output.status.code().unwrap_or(-1);
     if output.status.success() {
+        info!(exit_code = code, stdout_len, "command succeeded");
         Ok(combined)
     } else {
-        let code = output.status.code().unwrap_or(-1);
+        warn!(exit_code = code, stderr_len, "command failed");
         anyhow::bail!("command failed with exit code {code}:\n{combined}")
     }
 }
 
 /// Resolve a tool-supplied relative path to an absolute path within a workspace
 /// root, rejecting escapes.
+///
+/// Flow: parse optional `[idx]` prefix → join with workspace root → canonicalize
+/// → verify result is inside one of the workspace roots.
+#[instrument(skip(workspaces))]
 pub fn resolve_path(workspaces: &[PathBuf], rel: &str) -> Result<PathBuf> {
     let (ws_idx, path) = if rel.starts_with('[') {
         let close = rel
@@ -284,15 +297,21 @@ pub fn resolve_path(workspaces: &[PathBuf], rel: &str) -> Result<PathBuf> {
         }
         resolved
     };
+    debug!(resolved = %canon.display(), "path resolved within workspace");
     if workspaces.iter().any(|w| canon.starts_with(w)) {
         Ok(canon)
     } else {
+        warn!(path = %canon.display(), rel = rel, "path is outside all workspace roots");
         anyhow::bail!("path '{rel}' is outside all workspace roots")
     }
 }
 
 /// After a successful write/edit tool run, compute content hash and byte
 /// delta, then persist an `EditLogEntry` to the session's edit log.
+///
+/// Flow: extract path/content/reason from args → compute SHA-256 of content
+/// → compute byte delta → build `EditLogEntry` → open repo → append entry.
+#[instrument(skip(args, session_dir))]
 pub fn log_write_edit_tool(
     args: &serde_json::Value,
     tool_name: &str,
@@ -334,6 +353,9 @@ pub fn log_write_edit_tool(
     let repo = crate::persistence::cms::edit_log_repo::JsonlEditLogRepository::new();
     if let Ok(mut el) = repo.open(session_dir) {
         let _ = repo.append(session_dir, &mut el, entry);
+        debug!(tool = tool_name, path = path, "edit-log entry persisted");
+    } else {
+        warn!(tool = tool_name, path = path, "failed to open edit-log repository");
     }
 }