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

@@ -1,8 +1,13 @@
 //! Workflow tools — orchestrate multi-step agent workflows and hive-mind convergence.
+//!
+//! `WorkflowRun` executes a YAML-defined multi-step workflow. `NoteFinding` and
+//! `ReadFindings` record and retrieve findings during execution. `HiveMind`
+//! orchestrates a convergence — multiple parallel agent cycles followed by
+//! consensus synthesis.
 
 use anyhow::Result;
 use serde_json::{json, Value};
-use tracing::info;
+use tracing::{debug, info, instrument, warn};
 
 use crate::llm::provider::LlmClient;
 use crate::tools::{arg_str, Tool, ToolCtx};
@@ -41,6 +46,7 @@ impl Tool for WorkflowRun {
         })
     }
 
+    #[instrument(skip(self, ctx, args))]
     fn run(&self, ctx: &ToolCtx, args: &Value) -> Result<String> {
         let yaml = arg_str(args, "workflow_yaml")?;
         let script = WorkflowScript::parse(&yaml)?;
@@ -66,6 +72,7 @@ impl Tool for WorkflowRun {
         let result: Vec<String> =
             rt.block_on(async { execute_workflow(&script, ctx, &llm_client).await })?;
 
+        info!(phase_count = result.len(), "Workflow completed");
         Ok(format!(
             "Workflow '{}' completed.\n\n{}",
             script.name,
@@ -74,6 +81,10 @@ impl Tool for WorkflowRun {
     }
 }
 
+/// Record a finding during workflow or hive-mind execution.
+///
+/// Flow: extract finding text and optional category → prepend `[category]` tag
+/// → push onto `ctx.workflow_findings` shared list.
 pub struct NoteFinding;
 
 impl Tool for NoteFinding {
@@ -102,6 +113,7 @@ impl Tool for NoteFinding {
         })
     }
 
+    #[instrument(skip(self, ctx, args))]
     fn run(&self, ctx: &ToolCtx, args: &Value) -> Result<String> {
         let finding = crate::tools::arg_str(args, "finding")?;
         let category = args
@@ -114,13 +126,19 @@ impl Tool for NoteFinding {
         if let Some(ref findings) = ctx.workflow_findings {
             if let Ok(mut guard) = findings.lock() {
                 guard.push(tagged);
+                info!(finding_count = guard.len(), category = %category, "finding recorded");
             }
+        } else {
+            debug!("no workflow_findings channel available — finding not persisted");
         }
 
         Ok(format!("Finding recorded: {finding}"))
     }
 }
 
+/// Read all findings recorded so far in the current workflow.
+///
+/// Flow: lock `ctx.workflow_findings` → clone the list → format as numbered output.
 pub struct ReadFindings;
 
 impl Tool for ReadFindings {
@@ -139,12 +157,16 @@ impl Tool for ReadFindings {
         })
     }
 
+    #[instrument(skip(self, ctx, _args))]
     fn run(&self, ctx: &ToolCtx, _args: &Value) -> Result<String> {
         let findings = ctx
             .workflow_findings
             .as_ref()
             .and_then(|f| f.lock().ok())
-            .map(|guard| guard.clone())
+            .map(|guard| {
+                debug!(finding_count = guard.len(), "reading findings");
+                guard.clone()
+            })
             .unwrap_or_default();
 
         if findings.is_empty() {
@@ -202,6 +224,7 @@ impl Tool for HiveMind {
         })
     }
 
+    #[instrument(skip(self, ctx, args))]
     fn run(&self, ctx: &ToolCtx, args: &Value) -> Result<String> {
         let cycles_val = args
             .get("cycles")
@@ -235,6 +258,7 @@ impl Tool for HiveMind {
                 })
                 .unwrap_or_default();
 
+            info!(cycle_index = cycle_idx, node_count = directives.len(), "executing hive-mind cycle");
             let cycle = CognitiveCycle {
                 index: cycle_idx as u32,
                 directives,
@@ -246,6 +270,7 @@ impl Tool for HiveMind {
         }
 
         let node_count = all_node_outputs.len();
+        info!(node_count, "all cycles completed, synthesizing consensus");
         let consensus =
             rt.block_on(async { synthesize_consensus(&all_node_outputs, ctx).await })?;