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/plan.rs

@@ -1,10 +1,18 @@
 //! Plan management tools — enter and mark ready.
+//!
+//! These tools implement a two-phase planning workflow: `PlanEnter` presents a
+//! structured plan to the user for approval, and `PlanReady` signals that the
+//! plan is finalised and execution may begin.
 
 use crate::tools::{Tool, ToolCtx};
 use anyhow::Result;
 use serde_json::{json, Value};
-use tracing::info;
+use tracing::{info, instrument, warn};
 
+/// Enter a planning phase — persist a structured plan and notify the user.
+///
+/// Flow: extract plan text → write to `{session_dir}/PLAN.md` → push a
+/// `PlanUpdate` turn event → return plan length summary.
 pub struct PlanEnter;
 
 impl Tool for PlanEnter {
@@ -29,9 +37,11 @@ impl Tool for PlanEnter {
         })
     }
 
+    #[instrument(skip(self, ctx, args))]
     fn run(&self, ctx: &ToolCtx, args: &Value) -> Result<String> {
         let plan_text = crate::tools::arg_str(args, "plan")?;
-        
+        info!(plan_len = plan_text.len(), "plan_enter called");
+
         let plan_path = ctx.session_dir.join("PLAN.md");
         let _ = std::fs::write(&plan_path, &plan_text);
         if let Some(events) = &ctx.turn_events {
@@ -46,6 +56,10 @@ impl Tool for PlanEnter {
     }
 }
 
+/// Signal that the plan is ready and execution can begin.
+///
+/// Flow: extract plan content → persist to a timestamped file in
+/// `{session_dir}/plans/` → overwrite `PLAN.md` → push `PlanUpdate` event.
 pub struct PlanReady;
 
 impl Tool for PlanReady {
@@ -70,9 +84,11 @@ impl Tool for PlanReady {
         })
     }
 
+    #[instrument(skip(self, ctx, args))]
     fn run(&self, ctx: &ToolCtx, args: &Value) -> Result<String> {
         let plan_content = crate::tools::arg_str(args, "plan")?;
-        info!("plan ready: {} chars", plan_content.len());
+        info!(plan_len = plan_content.len(), "plan_ready called");
+
         // Persist the plan to session directory for reference
         let plan_dir = ctx.session_dir.join("plans");
         if std::fs::create_dir_all(&plan_dir).is_ok() {
@@ -80,7 +96,9 @@ impl Tool for PlanReady {
             let path = plan_dir.join(&filename);
             std::fs::write(&path, &plan_content)
                 .map_err(|e| anyhow::anyhow!("failed to save plan: {e}"))?;
-            
+
+            info!(filename = %filename, "plan persisted to disk");
+
             // Also save the latest plan
             let plan_path = ctx.session_dir.join("PLAN.md");
             let _ = std::fs::write(&plan_path, &plan_content);
@@ -91,6 +109,7 @@ impl Tool for PlanReady {
 
             Ok(format!("Plan saved to {filename}. Starting execution."))
         } else {
+            warn!("failed to create plans directory");
             Ok("Plan is ready. Starting execution.".to_string())
         }
     }