[Cleanup] Compact 17 multi-line comment blocks added by recent PRs (#1961)

Recent bug-fix PRs left behind block comments that narrate the defect
they fixed -- four to seven lines of "it used to do X, which caused Y"
sitting above a one-line change. That history belongs in the PR
description and the commit, not in the source, where it has to be read
past on every future visit.

Each block is reduced to a single line that keeps the operative reason
and drops the archaeology:

    -            # Add completion percentage if loops are running.
    -            #
    -            # current_loop is 1-based and set at the *top* of each
    -            # iteration (hiearchical_swarm.py calls
    -            # update_loop(current_loop + 1)), so dividing by max_loops
    -            # reported 100% before the final loop's agents had run.
    -            # Count loops finished instead: the loop in progress is
    -            # current_loop, so current_loop - 1 are done.
    +            # current_loop is 1-based, so count current_loop - 1 as finished.

17 blocks across 6 files, -72/+17 lines. Scope was picked by blaming
every run of three or more consecutive comment lines under swarms/ and
keeping only those authored by the last 25 commits on master.

Comments only -- no code, control flow, or behaviour is touched.
black and ruff clean; test_conversation.py and test_cron_job.py pass
(89 passed).

Author: kyegomez

swarms/structs/agent.py

@@ -2156,10 +2156,7 @@ def run_concurrent_tasks(self, tasks: List[str], *args, **kwargs):
         """
         try:
             logger.info(f"Running concurrent tasks: {tasks}")
-            # Pool is scoped to the call, matching how the rest of the codebase
-            # runs concurrent work (heavy_swarm, majority_voting,
-            # multi_agent_router). An Agent-level pool would keep idle threads
-            # alive for the process lifetime of every agent a swarm builds.
+            # Call-scoped pool, as in heavy_swarm: no idle threads per agent.
             with ContextThreadPoolExecutor(
                 max_workers=os.cpu_count()
             ) as executor:
@@ -2497,10 +2494,7 @@ def _reinitialize_after_load(self) -> None:
                     rules=self.rules,
                 )
 
-            # No executor to reinitialize: concurrent work creates its own
-            # call-scoped pool. The assignment that used to live here stored an
-            # executor the enclosing `with` had already shut down, so anything
-            # reading it back would have submitted to a dead pool.
+            # Nothing to restore: concurrent work builds its own call-scoped pool.
 
         except Exception as e:
             logger.error(f"Error reinitializing components: {e}")
@@ -3362,9 +3356,7 @@ def run_batched(
         Returns:
             List[Any]: List of results from each task execution.
         """
-        # `for task, imgs in zip(...)` rebound the parameter to one image per
-        # iteration, so a List[str] field received a bare str -- and with the
-        # documented default of imgs=None the zip raised before any task ran.
+        # Index imgs rather than zip: zip rebound imgs and raised when it was None.
         if imgs is None:
             return [
                 self.run(task=task, *args, **kwargs) for task in tasks
@@ -4127,10 +4119,7 @@ def tool_execution_retry(self, response: any, loop_count: int):
             )
             return
 
-        # execute_tools re-raises whatever the tool raised, and nothing in the
-        # framework raises AgentToolExecutionError, so catching only that type
-        # caught nothing. Catch broadly here, which is also what the docstring
-        # promises ("Other exceptions: Logs error and retries").
+        # Catch broadly: nothing raises AgentToolExecutionError, so that caught nothing.
         attempts = max(1, int(self.tool_retry_attempts or 1))
         last_error: Optional[Exception] = None
 
@@ -4149,10 +4138,7 @@ def tool_execution_retry(self, response: any, loop_count: int):
                     f"Full traceback: {traceback.format_exc()}"
                 )
 
-        # Attempts exhausted. Raising is what the docstring specifies, and it is
-        # the only way the caller learns the tools did not run — returning here
-        # left `short_memory` with no Tool Executor entry, so the model saw the
-        # call as having produced nothing and carried on as if it had succeeded.
+        # Attempts exhausted: raise, or the model reads a silent no-op as success.
         raise AgentToolExecutionError(
             f"Agent '{self.agent_name}' failed to execute tools in loop "
             f"{loop_count} after {attempts} attempt(s): {last_error}"

swarms/structs/agent_rearrange.py

@@ -565,10 +565,7 @@ def _run_concurrent_workflow(
                 f"Agent(s) {missing} not registered in this AgentRearrange instance."
             )
 
-        # Run agents concurrently
-        # `img` was accepted and dropped, so a flow step written with a comma
-        # ("A, B") silently ran without the image while the sequential path
-        # ("A -> B") forwarded it. The async twin below forwards it too.
+        # Run agents concurrently, forwarding img; this path used to drop it.
         results = run_agents_concurrently(
             agents=agents_to_run,
             task=self.conversation.get_str(),

swarms/structs/concurrent_workflow.py

@@ -410,11 +410,7 @@ def agent_streaming_callback(chunk: str):
                         output = future.result()
                         results.append((agent.agent_name, output))
                     except Exception as e:
-                        # Same failure policy as `_run`. This path used to
-                        # convert every failure into an "Error: ..." string
-                        # regardless, so `on_error="raise"` was silently
-                        # revoked by turning the dashboard on, and the
-                        # failure never reached telemetry either.
+                        # Same failure policy as _run: the dashboard must not revoke on_error.
                         if self.on_error == "raise":
                             raise
                         capture_error(

swarms/structs/conversation.py

@@ -163,11 +163,7 @@ def setup_file_path(self):
             extension = (
                 ".json" if self.export_method == "json" else ".yaml"
             )
-            # Under conversations_dir, not the process's working directory:
-            # a bare relative name dropped conversation_<name>.json wherever
-            # the program happened to run from, and two conversations sharing
-            # a name in different directories silently loaded each other's
-            # history.
+            # Under conversations_dir, not CWD: same-named conversations must not collide.
             self.save_filepath = os.path.join(
                 self.conversations_dir or get_conversation_dir(),
                 f"conversation_{self.name}{extension}",

swarms/structs/cron_job.py

@@ -118,11 +118,7 @@ def __init__(
         self.execution_count = 0
         self.start_time = None
 
-        # Failure accounting. A task that raises must not take the schedule
-        # down with it, but the failures still have to be visible: the loop
-        # used to set is_running=False and re-raise, which killed the
-        # scheduler thread on the first error while run() returned normally,
-        # so a dead job was indistinguishable from a healthy one.
+        # Failures stay visible without taking the schedule down.
         self.error_count = 0
         self.consecutive_errors = 0
         self.last_error = None
@@ -139,10 +135,7 @@ def reliability_check(self):
                 "Agent must be provided during initialization"
             )
 
-        # An empty string is not "no interval given", it is a bad interval.
-        # It used to fall through this guard and only surface much later, from
-        # _run(), as "Interval must be provided during initialization" -- which
-        # is confusing, because it was provided.
+        # An empty string is a bad interval, not a missing one: fail here, not in _run().
         if (
             self.interval is not None
             and not str(self.interval).strip()
@@ -395,10 +388,7 @@ def _run_job(self, task: str, **kwargs) -> Any:
         try:
             logger.debug(f"Executing task for job {self.job_id}")
 
-            # Execute the agent. Discriminate on having a run() method, not
-            # on isinstance(Callable): a plain function is Callable too, so
-            # that test sent every function down the .run() path and left the
-            # branch below unreachable.
+            # Dispatch on having run(), not on Callable: a plain function is Callable too.
             runner = getattr(self.agent, "run", None)
             if callable(runner):
                 original_output = runner(task=task, **kwargs)
@@ -548,12 +538,7 @@ def _run_schedule(self):
                 self.schedule.run_pending()
                 self.consecutive_errors = 0
             except Exception as e:
-                # Log and keep going. Setting is_running=False and re-raising
-                # here killed the scheduler thread on the first failed
-                # execution, so a single transient error (a rate limit, a
-                # dropped connection) permanently stopped the job -- and
-                # because _block_forever also loops on is_running, run()
-                # returned normally and the caller was never told.
+                # Log and keep going: one failed execution must not kill the scheduler.
                 self.error_count += 1
                 self.consecutive_errors += 1
                 self.last_error = e
@@ -710,9 +695,7 @@ def run_many(
             return jobs
 
         try:
-            # Hold here while the per-job threads do the work. Exit as soon as
-            # every job has stopped, so a fleet that has given up does not
-            # leave the caller parked forever.
+            # Wait while the per-job threads work; exit once every job has stopped.
             while any(job.is_running for job in jobs):
                 time.sleep(1)
         except KeyboardInterrupt:

swarms/utils/hierarchical_swarm_dashboard.py

@@ -199,17 +199,9 @@ def _create_status_panel(self) -> Panel:
             status_text.append("RUNTIME: ", style="bold white")
             status_text.append(f"{runtime:.2f}s", style="bold green")
 
-            # Add completion percentage if loops are running.
-            #
-            # current_loop is 1-based and set at the *top* of each iteration
-            # (hiearchical_swarm.py calls update_loop(current_loop + 1)), so
-            # dividing by max_loops reported 100% before the final loop's
-            # agents had run. Count loops finished instead: the loop in
-            # progress is current_loop, so current_loop - 1 are done.
+            # current_loop is 1-based, so count current_loop - 1 as finished.
             if self.max_loops > 0:
-                # Once the swarm reports COMPLETED every loop has finished,
-                # including the last one — otherwise the run would end at
-                # (max_loops - 1) / max_loops and never show 100%.
+                # COMPLETED means the final loop finished, so show 100%.
                 completed_loops = (
                     self.max_loops
                     if self.director_status == "COMPLETED"
@@ -246,10 +238,7 @@ def _create_agents_table(self) -> Table:
         table.add_column("LOOP", style="bold white", width=8)
         table.add_column("STATUS", style="bold white", width=15)
         table.add_column("TASK", style="white", width=40)
-        # OUTPUT takes whatever is left rather than a hardcoded 150, which
-        # made the table ~250 chars and overflowed almost every terminal.
-        # ratio=1 lets Rich shrink it to the console; the minimum keeps it
-        # readable on a narrow one.
+        # OUTPUT takes the remaining width (ratio=1); a fixed 150 overflowed the terminal.
         table.add_column(
             "OUTPUT",
             style="white",
@@ -357,9 +346,7 @@ def _create_director_panel(self) -> Panel:
         # Orders section
         director_text.append("CURRENT ORDERS:\n", style="bold white")
         if self.director_orders:
-            # Actually show only the first 5. Without the slice every order
-            # was rendered and the "... and N more" line below contradicted
-            # what the panel had just printed.
+            # Show only the first 5, so the "... and N more" line below is accurate.
             for i, order in enumerate(self.director_orders[:5]):
                 director_text.append(f"{i + 1}. ", style="bold cyan")
                 director_text.append(