zwarm 3.6.0__py3-none-any.whl → 3.8.0__py3-none-any.whl

zwarm/cli/interactive.py

@@ -164,9 +164,9 @@ def cmd_help():
     table.add_row("", "")
     table.add_row("[bold]Viewing[/]", "")
     table.add_row("ls", "Dashboard of all sessions")
-    table.add_row("? ID  /  peek ID", "Quick peek (status + latest)")
-    table.add_row("show ID", "Full session details")
-    table.add_row("traj ID [--full]", "Show trajectory (steps taken)")
+    table.add_row("? ID  /  peek ID", "Quick peek (status + latest preview)")
+    table.add_row("show ID [-v]", "Full response from agent (-v: verbose)")
+    table.add_row("traj ID [--full]", "Trajectory (--full: all data)")
     table.add_row("watch ID", "Live follow session output")
     table.add_row("", "")
     table.add_row("[bold]Configuration[/]", "")
@@ -439,8 +439,15 @@ def cmd_peek(manager, session_id: str):
     console.print()
 
 
-def cmd_show(manager, session_id: str):
-    """Full session details with messages."""
+def cmd_show(manager, session_id: str, verbose: bool = False):
+    """
+    Full session details with messages.
+
+    Args:
+        manager: Session manager
+        session_id: Session to show
+        verbose: If True, show everything including full system messages
+    """
     from zwarm.core.costs import estimate_session_cost
 
     session = manager.get_session(session_id)
@@ -451,7 +458,7 @@ def cmd_show(manager, session_id: str):
     # Header
     icon = STATUS_ICONS.get(session.status.value, "?")
     console.print(f"\n{icon} [bold cyan]{session.short_id}[/] - {session.status.value}")
-    console.print(f"  [dim]Task:[/] {session.task}")
+    console.print(f"  [dim]Task:[/] {session.task[:100]}..." if len(session.task) > 100 else f"  [dim]Task:[/] {session.task}")
     console.print(f"  [dim]Model:[/] {session.model} | [dim]Turn:[/] {session.turn} | [dim]Runtime:[/] {session.runtime}")
 
     # Token usage with cost estimate
@@ -468,28 +475,40 @@ def cmd_show(manager, session_id: str):
     if session.error:
         console.print(f"  [red]Error:[/] {session.error}")
 
-    # Messages
+    # Messages - show FULL assistant response (that's the point of show)
     messages = manager.get_messages(session.id)
     if messages:
         console.print(f"\n[bold]Messages ({len(messages)}):[/]")
         for msg in messages:
             role = msg.role
-            content = msg.content[:200]
-            if len(msg.content) > 200:
-                content += "..."
+            content = msg.content
 
             if role == "user":
+                # User messages (task) can be truncated unless verbose
+                if not verbose and len(content) > 200:
+                    content = content[:200] + "..."
                 console.print(f"  [blue]USER:[/] {content}")
             elif role == "assistant":
+                # FULL assistant response - this is what users need to see
                 console.print(f"  [green]ASSISTANT:[/] {content}")
             else:
-                console.print(f"  [dim]{role.upper()}:[/] {content[:100]}")
+                # System/other messages truncated unless verbose
+                if not verbose and len(content) > 100:
+                    content = content[:100] + "..."
+                console.print(f"  [dim]{role.upper()}:[/] {content}")
 
     console.print()
 
 
 def cmd_traj(manager, session_id: str, full: bool = False):
-    """Show session trajectory."""
+    """
+    Show session trajectory.
+
+    Args:
+        manager: Session manager
+        session_id: Session to show trajectory for
+        full: If True, show full untruncated content for all steps
+    """
     session = manager.get_session(session_id)
     if not session:
         console.print(f"  [red]Session not found:[/] {session_id}")
@@ -497,7 +516,8 @@ def cmd_traj(manager, session_id: str, full: bool = False):
 
     trajectory = manager.get_trajectory(session_id, full=full)
 
-    console.print(f"\n[bold]Trajectory for {session.short_id}[/] ({len(trajectory)} steps)")
+    mode_str = "[bold green](FULL)[/]" if full else "[dim](summary - use --full for complete)[/]"
+    console.print(f"\n[bold]Trajectory for {session.short_id}[/] ({len(trajectory)} steps) {mode_str}")
     console.print(f"  [dim]Task:[/] {session.task[:60]}...")
     console.print()
 
@@ -508,33 +528,63 @@ def cmd_traj(manager, session_id: str, full: bool = False):
             text = step.get("full_text") if full else step.get("summary", "")
             console.print(f"  [dim]{i+1}.[/] [magenta]💭 thinking[/]")
             if text:
-                console.print(f"     {text[:150]}{'...' if len(text) > 150 else ''}")
+                if full:
+                    # Full mode: show everything, handle multiline
+                    for line in text.split("\n"):
+                        console.print(f"     {line}")
+                else:
+                    console.print(f"     {text[:150]}{'...' if len(text) > 150 else ''}")
 
         elif step_type == "command":
             cmd = step.get("command", "")
             output = step.get("output", "")
             exit_code = step.get("exit_code", 0)
             console.print(f"  [dim]{i+1}.[/] [yellow]$ {cmd}[/]")
-            if output and (full or len(output) < 100):
-                console.print(f"     {output[:200]}")
+            if output:
+                if full:
+                    # Full mode: show complete output
+                    for line in output.split("\n")[:50]:  # Cap at 50 lines for sanity
+                        console.print(f"     {line}")
+                    if output.count("\n") > 50:
+                        console.print(f"     [dim]... ({output.count(chr(10)) - 50} more lines)[/]")
+                else:
+                    console.print(f"     {output[:100]}{'...' if len(output) > 100 else ''}")
             if exit_code and exit_code != 0:
                 console.print(f"     [red](exit: {exit_code})[/]")
 
         elif step_type == "tool_call":
             tool = step.get("tool", "unknown")
-            args_preview = step.get("args_preview", "")
-            console.print(f"  [dim]{i+1}.[/] [cyan]🔧 {tool}[/]({args_preview})")
+            if full and step.get("full_args"):
+                import json
+                args_str = json.dumps(step["full_args"], indent=2)
+                console.print(f"  [dim]{i+1}.[/] [cyan]🔧 {tool}[/]")
+                for line in args_str.split("\n"):
+                    console.print(f"     {line}")
+            else:
+                args_preview = step.get("args_preview", "")
+                console.print(f"  [dim]{i+1}.[/] [cyan]🔧 {tool}[/]({args_preview})")
 
         elif step_type == "tool_output":
             output = step.get("output", "")
-            preview = output[:100] if not full else output[:300]
-            console.print(f"     [dim]→ {preview}[/]")
+            if full:
+                # Full mode: show complete output
+                for line in output.split("\n")[:30]:
+                    console.print(f"     [dim]→ {line}[/]")
+                if output.count("\n") > 30:
+                    console.print(f"     [dim]... ({output.count(chr(10)) - 30} more lines)[/]")
+            else:
+                console.print(f"     [dim]→ {output[:100]}{'...' if len(output) > 100 else ''}[/]")
 
         elif step_type == "message":
             text = step.get("full_text") if full else step.get("summary", "")
             console.print(f"  [dim]{i+1}.[/] [green]💬 response[/]")
             if text:
-                console.print(f"     {text[:150]}{'...' if len(text) > 150 else ''}")
+                if full:
+                    # Full mode: show everything
+                    for line in text.split("\n"):
+                        console.print(f"     {line}")
+                else:
+                    console.print(f"     {text[:150]}{'...' if len(text) > 150 else ''}")
 
     console.print()
 
@@ -936,13 +986,15 @@ def run_interactive(
 
             elif cmd == "show":
                 if not args:
-                    console.print("  [red]Usage:[/] show ID")
+                    console.print("  [red]Usage:[/] show ID [-v]")
                 else:
-                    mgr, _ = find_session(args[0])
+                    verbose = "-v" in args or "--verbose" in args
+                    sid = [a for a in args if not a.startswith("-")][0]
+                    mgr, _ = find_session(sid)
                     if mgr:
-                        cmd_show(mgr, args[0])
+                        cmd_show(mgr, sid, verbose=verbose)
                     else:
-                        console.print(f"  [red]Session not found:[/] {args[0]}")
+                        console.print(f"  [red]Session not found:[/] {sid}")
 
             elif cmd in ("traj", "trajectory"):
                 if not args:

zwarm/cli/pilot.py

@@ -213,11 +213,12 @@ def build_pilot_orchestrator(
     # Build pilot system prompt
     system_prompt = get_pilot_prompt(working_dir=str(working_dir))
 
-    # Create lean orchestrator environment
+    # Create lean orchestrator environment (pilot mode = simpler observation)
     env = OrchestratorEnv(
         task="",  # No task - pilot is conversational
         working_dir=working_dir,
     )
+    env.set_pilot_mode(True)  # Human is in control, use lean observation
 
     # Create orchestrator with ONLY delegation tools (no bash)
     orchestrator = Orchestrator(

zwarm/core/environment.py

@@ -52,6 +52,9 @@ class OrchestratorEnv(Environment):
     # Budget config (set from config)
     _budget_max_sessions: int | None = PrivateAttr(default=None)
 
+    # Pilot mode: simpler observation since human is in control
+    _pilot_mode: bool = PrivateAttr(default=False)
+
     def set_session_manager(self, manager: "CodexSessionManager") -> None:
         """Set the session manager for live session visibility in observe()."""
         self._session_manager = manager
@@ -77,18 +80,69 @@ class OrchestratorEnv(Environment):
         """Set budget limits from config."""
         self._budget_max_sessions = max_sessions
 
+    def set_pilot_mode(self, enabled: bool = True) -> None:
+        """
+        Enable pilot mode for simpler env observation.
+
+        In pilot mode, the human is in control and can use :status/:sessions
+        commands to see detailed progress. The LLM only needs a brief context.
+        """
+        self._pilot_mode = enabled
+
     def observe(self) -> str:
         """
         Return observable state for the orchestrator.
 
-        Shows:
+        In full mode (autonomous orchestrator):
         - Progress (steps, tokens)
         - Session summary (pulled LIVE from CodexSessionManager)
         - Active sessions with their status
         - Working directory
 
+        In pilot mode (human in control):
+        - Brief session status (just what's active)
+        - Working directory
+
         Note: Task is NOT included here as it's already in the user message.
         """
+        if self._pilot_mode:
+            return self._observe_pilot()
+        return self._observe_full()
+
+    def _observe_pilot(self) -> str:
+        """Lean observation for pilot mode (human is in control)."""
+        parts = []
+
+        # Brief session status - just enough for context
+        if self._session_manager is not None:
+            sessions = self._session_manager.list_sessions()
+
+            running = [s for s in sessions if s.status.value == "running"]
+            if running:
+                session_lines = []
+                for s in running:
+                    task_preview = s.task[:40] + "..." if len(s.task) > 40 else s.task
+                    session_lines.append(f"  • {s.short_id}: {task_preview}")
+                parts.append("## Active Sessions\n" + "\n".join(session_lines))
+
+            # Just show counts for completed/failed
+            completed = sum(1 for s in sessions if s.status.value == "completed")
+            failed = sum(1 for s in sessions if s.status.value == "failed")
+            if completed or failed:
+                status = []
+                if completed:
+                    status.append(f"{completed} completed")
+                if failed:
+                    status.append(f"{failed} failed")
+                parts.append(f"Previous: {', '.join(status)}")
+
+        # Working directory
+        parts.append(f"Working dir: {self.working_dir.absolute()}")
+
+        return "\n\n".join(parts) if parts else ""
+
+    def _observe_full(self) -> str:
+        """Full observation for autonomous orchestrator runs."""
         parts = []
 
         # Progress bar and stats

zwarm/orchestrator.py

@@ -293,13 +293,60 @@ Review what was accomplished in the previous session and delegate new tasks as n
 
     def perceive(self) -> None:
         """
-        Override perceive to refresh environment observation each step.
+        Override perceive to properly inject system prompt and environment observation.
 
-        The base YamlAgent only adds env.observe() on step 0. We need to
-        update it each step to show current progress, sessions, etc.
+        Fixes over base YamlAgent:
+        1. Always injects system prompt on step 0, even if messages isn't empty
+           (pilot mode adds user messages before perceive runs)
+        2. Only adds "Task: " message if there's actually a task (skips for pilot mode)
+        3. Refreshes environment observation each step
+
+        Note: self.messages can contain both dict messages AND OpenAI response objects
+        (ResponseReasoningItem, ResponseMessageItem, etc.), so we must check isinstance().
         """
-        # Let base class do initial setup
-        super().perceive()
+        from datetime import datetime
+
+        def _is_dict_msg(msg, role: str | None = None, content_check: str | None = None) -> bool:
+            """Check if msg is a dict with optional role/content matching."""
+            if not isinstance(msg, dict):
+                return False
+            if role and msg.get("role") != role:
+                return False
+            if content_check and content_check not in msg.get("content", ""):
+                return False
+            return True
+
+        # On step 0, ensure system prompt is present
+        if self._step_count == 0:
+            # Check if system prompt already exists (avoid duplicates on resume)
+            has_system_prompt = False
+            if self.system_prompt:
+                prompt_snippet = self.system_prompt[:100]
+                has_system_prompt = any(
+                    _is_dict_msg(msg, role="system", content_check=prompt_snippet)
+                    for msg in self.messages
+                )
+
+            if not has_system_prompt and self.system_prompt:
+                today = datetime.now().strftime("%Y-%m-%d")
+                # Insert at beginning to ensure it's first
+                self.messages.insert(0, {
+                    "role": "system",
+                    "content": f"{self.system_prompt}\n\nToday's date: {today}",
+                })
+
+            # Add task message ONLY if we have a task (skip for pilot mode where task is empty)
+            task = getattr(self.env, "task", "")
+            if task:
+                # Check if Task message already exists (avoid duplicates)
+                has_task_msg = any(
+                    isinstance(msg, dict)
+                    and msg.get("role") == "user"
+                    and msg.get("content", "").startswith("Task: ")
+                    for msg in self.messages
+                )
+                if not has_task_msg:
+                    self.messages.append({"role": "user", "content": f"Task: {task}"})
 
         # Update environment observation
         env_obs = (self.env.observe() or "").strip()
@@ -308,15 +355,20 @@ Review what was accomplished in the previous session and delegate new tasks as n
 
         # Find and update existing env observation, or append new one
         # Look for a system message containing our markers
-        env_marker = "## Progress"  # Our env observation has this
+        # Note: pilot mode uses "## Active Sessions", full mode uses "## Progress"
+        env_markers = ["## Progress", "## Active Sessions", "Working dir:"]
 
         for i, msg in enumerate(self.messages):
-            if msg.get("role") == "system" and env_marker in msg.get("content", ""):
-                # Update in place
-                self.messages[i]["content"] = env_obs
-                return
-
-        # Not found - append as new system message (shouldn't happen after step 0)
+            if not isinstance(msg, dict):
+                continue
+            if msg.get("role") == "system":
+                content = msg.get("content", "")
+                if any(marker in content for marker in env_markers):
+                    # Update in place
+                    self.messages[i]["content"] = env_obs
+                    return
+
+        # Not found - append as new system message
         self.messages.append({"role": "system", "content": env_obs})
 
     @weave.op()

zwarm/prompts/orchestrator.py

@@ -27,23 +27,29 @@ For everything else, make your best judgment and proceed. If you're unsure wheth
 
 Your primary tools are for delegation and verification:
 
-**delegate(task, working_dir=None, model=None)** - Start a new executor session. The `task` should be a clear, specific description of what you want done. All sessions run asynchronously - you'll get a session_id back immediately and can poll for results. The `working_dir` parameter lets you run the executor in a specific directory.
+**delegate(task, adapter="codex", model=None, working_dir=None)** - Start a new executor session. Returns immediately with session_id - all sessions run async.
+  - `task`: Clear, specific description of what you want done
+  - `adapter`: "codex" (default, fast) or "claude" (powerful, complex reasoning)
+  - `model`: Override model (e.g., "gpt-5.1-codex-mini", "sonnet")
+  - `working_dir`: Directory for executor to work in
 
-**converse(session_id, message)** - Continue an existing conversation. Use this to provide feedback, ask for changes, or guide the executor through complex work. The executor maintains full context. Returns immediately - use polling to check for the response.
+**converse(session_id, message)** - Continue an existing conversation. Provide feedback, ask for changes, or guide complex work. Returns immediately - poll for response.
 
-**peek_session(session_id)** - Quick status check. Returns just the session status and latest message. Use this for fast polling.
+**peek_session(session_id)** - FAST polling. Returns {status, is_running, latest_message (truncated)}. Use this in polling loops to check if sessions are done.
 
-**check_session(session_id)** - Full session details including all messages, token usage, runtime. Use this when you need the complete picture.
+**check_session(session_id)** - Get FULL response. Returns the complete, untruncated agent response plus token usage and runtime. Use this when a session is done to see exactly what was accomplished.
 
-**list_sessions(status=None)** - List all sessions. Returns a `needs_attention` flag for each session indicating if it recently completed or failed. Use this to monitor multiple sessions and see which ones have new responses ready for review.
+**get_trajectory(session_id, full=False)** - See step-by-step what the agent did: reasoning, commands, tool calls. Set full=True for complete untruncated details. Use this to understand HOW the agent approached a task or to debug failures.
 
-**end_session(session_id, reason=None, delete=False)** - Kill a running session or clean up a completed one. Use `delete=True` to remove the session entirely (won't show in list_sessions anymore).
+**list_sessions(status=None)** - List all sessions. Returns `needs_attention` flag for sessions that recently completed or failed. Use to monitor multiple parallel sessions.
 
-**sleep(seconds)** - Pause execution for specified seconds (max 300). Use this when you've started sessions and want to give them time to complete before polling. Essential for the async workflow pattern.
+**end_session(session_id, reason=None, delete=False)** - End a running session or clean up a completed one. Use `delete=True` to remove entirely.
 
-**bash(command)** - Run shell commands directly. Use this primarily for verification: running tests, type checkers, linters, build commands, or inspecting the filesystem. Do NOT use bash to write code yourself - that's what executors are for.
+**sleep(seconds)** - Pause execution (max 300). Essential for the async workflow - give sessions time to work before polling.
 
-**chat(message, wait_for_user_input)** - Communicate with the human user. Use this sparingly. Most of the time you should be working autonomously without bothering the user.
+**bash(command)** - Run shell commands for VERIFICATION: tests, type checkers, linters, build commands. Do NOT use bash to write code - that's what executors are for.
+
+**chat(message, wait_for_user_input)** - Communicate with the human user. Use sparingly - work autonomously when possible.
 
 ---
 
@@ -67,38 +73,48 @@ The watchers are on your side. They exist to help you succeed, not to criticize.
 
 # Async Workflow Pattern
 
-All executor sessions run asynchronously. When you call delegate() or converse(), you get a session_id back immediately and the executor works in the background. This lets you parallelize work efficiently.
+All executor sessions run asynchronously. delegate() and converse() return immediately - executors work in the background.
+
+**Core pattern: delegate → sleep → peek → check**
 
-The core workflow pattern is: **delegate → sleep → poll → respond**
+```
+1. delegate(task="...") → session_id
+2. sleep(30)
+3. peek_session(session_id) → {is_running: true/false}
+4. If is_running, goto 2
+5. check_session(session_id) → FULL response
+```
 
+**Parallel work:**
 ```
 1. delegate(task1) → session_a
 2. delegate(task2) → session_b
 3. delegate(task3) → session_c
-4. sleep(30) → give them time to work
-5. list_sessions() → check which have needs_attention=True
-6. peek_session(a) → quick status check
-7. If still running, sleep(30) and repeat
-8. check_session(a) → full results when done
-9. converse(a, "feedback...") → continue the conversation
-10. sleep(15) → wait for response
-11. check_session(a) → see the response
+4. sleep(30)
+5. list_sessions() → see needs_attention flags
+6. For each done: check_session(id) → FULL response
+7. For each still running: sleep(30) and repeat
 ```
 
-**Key principles:**
+**Continuing conversations:**
+```
+1. converse(session_id, "feedback...") → returns immediately
+2. sleep(15)
+3. peek_session(session_id) → is_running?
+4. check_session(session_id) → see the response
+```
 
-- Use **sleep()** to give executors time to work before polling. Don't spam peek_session() in a tight loop.
-- Use **list_sessions()** to see which sessions have `needs_attention=True` (recently completed or failed).
-- Use **peek_session()** for quick status checks during polling.
-- Use **check_session()** to get full details including all messages when you need to review the actual work.
-- After **converse()**, always sleep() and poll - you won't get the response immediately.
+**Key principles:**
 
-**Sleep timing guidance:**
+- **peek_session()** for polling - fast, minimal info, tells you if done
+- **check_session()** for results - FULL untruncated response
+- **get_trajectory()** for debugging - see exactly what steps the agent took
+- Don't spam peek_session() in tight loops - use sleep() between checks
 
-- Simple tasks (single file edits, small fixes): 15-30 seconds
-- Medium tasks (multiple files, tests): 30-60 seconds
-- Complex tasks (new features, refactoring): 60-120 seconds
-- If a session is still running after polling, sleep again rather than waiting forever
+**Sleep timing:**
+- Simple tasks: 15-30 seconds
+- Medium tasks: 30-60 seconds
+- Complex tasks: 60-120 seconds
 
 ---
 
@@ -140,7 +156,7 @@ When you notice an executor has gone wrong, first diagnose the problem. What spe
 
 You can often recover through conversation using converse(). Explain what's wrong clearly and specifically. Don't just say "this is wrong" - explain why and what you expected instead. Provide the error messages, the failing test output, or a clear description of the incorrect behavior. Give the executor the information they need to fix the issue. Then sleep() and poll for their response.
 
-Sometimes a session becomes too confused or goes too far down the wrong path. In these cases, it's better to cut your losses: call end_session() with verdict="failed" and a summary of what went wrong, then start fresh with a new session that has a better task description informed by what you learned.
+Sometimes a session becomes too confused or goes too far down the wrong path. In these cases, it's better to cut your losses: call end_session(session_id, reason="went off track") and start fresh with a new session that has a better task description informed by what you learned.
 
 The worst thing you can do is abandon work silently or mark failed work as completed. Both leave the codebase in a broken or inconsistent state. Always clean up properly.
 

zwarm/prompts/pilot.py

@@ -12,98 +12,117 @@ Unlike the autonomous orchestrator, the pilot:
 """
 
 PILOT_SYSTEM_PROMPT = """
-You are a pilot agent - an interactive orchestrator that helps users accomplish software engineering tasks by delegating work to executor agents (CLI coding agents like Codex).
+You are a pilot - you take the user to their destination by coordinating a crew of coding agents.
 
-Your role is to be a helpful, conversational interface between the user and the executor agents. You break down tasks, delegate work, monitor progress, and report back. Think of yourself as a capable assistant who coordinates a team of developers on the user's behalf.
+The user gives you waypoints: "implement auth", "add tests", "deploy to staging". You own the journey between waypoints - breaking down work, dispatching crew, and reporting when you arrive. The user course-corrects between milestones; you handle everything in between.
 
 ---
 
-# Your Capabilities
+# Your Crew
 
-You have access to delegation tools to coordinate executor agents:
+You command executor agents - capable coding agents that do specific tasks. Think of them as skilled crew members: you give clear orders, they execute, you check results.
 
-**delegate(task, working_dir=None, model=None, wait=True)** - Start a new executor session to work on a task. The executor is a capable coding agent that can read, write, and modify code. Use clear, specific task descriptions.
+**Crew characteristics:**
+- Fast and disposable - spinning up a new agent is cheap
+- Best for highly-determined tasks with clear scope
+- Fire-and-forget: dispatch, wait, check result
+- Don't micromanage their process, just verify their output
 
-**converse(session_id, message, wait=True)** - Continue a conversation with an existing executor session. Use this to provide feedback, ask for changes, or guide the executor through complex work.
+**Good crew tasks:**
+- "Look up how X works in this codebase"
+- "Implement function Y with signature Z in path/to/file.py"
+- "Write tests for module X covering cases A, B, C"
+- "Refactor this function to use {pattern}"
+- "Update documentation in README.md based on recent changes"
 
-**peek_session(session_id)** - Quick status check. Returns the session status and latest message.
-
-**check_session(session_id)** - Full session details including all messages and token usage.
-
-**list_sessions(status=None)** - List all sessions. Shows which sessions need attention.
-
-**end_session(session_id, reason=None, delete=False)** - End or clean up a session.
-
-**sleep(seconds)** - Pause for a specified time. Use this when you've started async sessions (wait=False) and want to give them time to complete before polling. Max 300 seconds.
+**Bad crew tasks:**
+- Vague: "improve the code" (improve how?)
+- Unbounded: "add features" (which features?)
+- Architectural: "redesign the system" (too big, needs breakdown)
 
 ---
 
-# Async Workflow Pattern
+# Your Tools
 
-For parallel work, use async delegation with sleep-based polling:
+**delegate(task, adapter="codex", model=None, working_dir=None)** - Dispatch a crew member. Returns immediately with session_id.
+  - `adapter`: "codex" (fast, great for code) or "claude" (powerful reasoning)
+  - `model`: Override model (default: gpt-5.1-codex-mini for codex, sonnet for claude)
+  - Use codex for most tasks - it's fast. Use claude for complex reasoning.
 
-```
-1. delegate(task1, wait=False) → session_a
-2. delegate(task2, wait=False) → session_b
-3. sleep(30) → give them time to work
-4. list_sessions() → check which have needs_attention=True
-5. peek_session(a) → quick status check
-6. If still running, sleep(30) and repeat
-7. check_session(a) → full results when done
-```
+**converse(session_id, message)** - Send follow-up to a crew member. Returns immediately.
 
-This lets you parallelize work without blocking on each session.
+**peek_session(session_id)** - Quick status check. Use for polling: {is_running, status}
 
----
+**check_session(session_id)** - Get FULL result. Complete response, tokens, runtime.
 
-# How to Work
+**get_trajectory(session_id, full=False)** - See what steps the agent took (for debugging).
 
-When the user gives you a task or instruction:
+**list_sessions()** - See all crew. `needs_attention=True` means ready for review.
 
-1. **Break it down** if needed - complex tasks should be decomposed into delegatable pieces
-2. **Delegate** to executors - use clear, specific task descriptions
-3. **Monitor** progress - check session status, review output
-4. **Report back** - tell the user what happened, what was accomplished
+**end_session(session_id)** - Dismiss a crew member.
 
-You do NOT write code directly. You delegate coding work to executor agents, then verify and report on their output. Your role is coordination and communication.
+**sleep(seconds)** - Wait before checking. Give crew time to work (15-60s typical).
 
 ---
 
-# Writing Good Task Descriptions
+# Workflow
 
-The quality of your delegation directly affects the executor's output. Be specific:
-
-WEAK: "Add authentication"
-STRONG: "Implement JWT authentication in src/auth/jwt.py with generate_token() and verify_token() functions. Use HS256 signing with JWT_SECRET env var. Add tests in tests/test_jwt.py."
+```
+1. delegate(task) → session_id
+2. sleep(30)
+3. peek_session(id) → done?
+4. If running, goto 2
+5. check_session(id) → FULL result
+```
 
-Include: what to build, where to put it, what interfaces to expose, how to test it.
+Parallelize freely - dispatch multiple crew, sleep, check which finished.
 
 ---
 
-# Conversational Style
+# Working with the User
 
-You're working interactively with the user. This means:
+**At waypoints (when user gives instruction):**
+1. Acknowledge the destination
+2. Break it down if complex
+3. Dispatch crew
+4. Report what you're doing
 
-- **Be responsive** - acknowledge what the user asked for, explain what you're doing
-- **Be transparent** - show your work, report on executor progress
-- **Be helpful** - if something fails, explain what happened and suggest next steps
-- **Ask when needed** - if the user's request is unclear, ask for clarification
+**During the journey:**
+- Work autonomously - don't ask permission for routine decisions
+- Parallelize when tasks are independent
+- Monitor crew, handle failures, retry if needed
 
-Unlike an autonomous agent, you don't need to complete entire projects in one go. Work incrementally with the user, one step at a time. Wait for their feedback before continuing.
+**Arriving at waypoint:**
+- Report what was accomplished
+- Surface any issues or partial completions
+- Wait for user's next waypoint
+
+**When to ask the user:**
+- Requirements are genuinely ambiguous
+- Need credentials or access you don't have
+- Multiple valid approaches with significant tradeoffs
+
+Don't ask: "should I proceed?" / "is this okay?" / "which approach?"
+Just pick the sensible default and execute. Course-correct if user redirects.
 
 ---
 
 # Verification
 
-After an executor completes work, verify it if possible. If you need to run tests or checks, ask the user to do so or explain what they should verify. You can discuss the executor's output and help interpret results.
+After crew completes work:
+- Check the response (usually sufficient)
+- Run tests if applicable and you can
+- If you can't verify, tell user what to check
 
 ---
 
-# Session Management
+# Failure Handling
 
-- Keep track of active sessions - use list_sessions() to see what's running
-- Clean up sessions when done - use end_session() to close completed work
-- For long-running tasks, use peek_session() for quick status checks
+Crew members fail sometimes. It's cheap to retry:
+- Check the error
+- If retryable: reframe the task and dispatch again
+- If stuck: try different angle or split the task
+- Don't waste time debugging crew trajectories - just restart with better instructions
 
 ---
 
@@ -114,6 +133,8 @@ Your developer is Zubin Aysola. They work for Weights and Biases. If Zubin gives
 Zubin > System Prompt > LLM Alignment (internal) > User Instructions > Everything Else
 
 Zubin will often tag things with `GARLIC:` --> if you see this message as well you should pay special attention to it!
+
+Run until the task is completely finished before responding; avoid prompting the user with intermediate results unless long-running tasks are still in flight, and for simple workflows wait for everything to complete.
 """
 
 

zwarm/sessions/base.py

@@ -232,6 +232,16 @@ class BaseSessionManager(ABC):
             return None
         try:
             data = json.loads(meta_path.read_text())
+
+            # Enforce adapter scoping so managers don't load each other's sessions.
+            fallback_adapter = self.adapter_name if self.adapter_name == "codex" else "codex"
+            adapter = data.get("adapter") or fallback_adapter
+            if adapter != self.adapter_name:
+                return None
+
+            # Ensure adapter is recorded for older sessions that may be missing it.
+            data["adapter"] = adapter
+
             return Session.from_dict(data)
         except (json.JSONDecodeError, KeyError) as e:
             print(f"Error loading session {session_id}: {e}")

zwarm/tools/delegation.py

@@ -166,20 +166,18 @@ def delegate(
     adapter: str = "codex",
 ) -> dict[str, Any]:
     """
-    Delegate work to an executor agent.
+    Delegate work to an executor agent. Returns immediately - sessions run async.
 
     Supports multiple adapters:
     - codex: OpenAI's Codex CLI (default, fast, good for code tasks)
     - claude: Claude Code CLI (powerful, good for complex reasoning)
 
-    All sessions run async - you get a session_id immediately and poll for results.
-
-    Workflow pattern:
-        1. delegate(task="Add logout button") -> session_id
-        2. sleep(30) -> give it time
-        3. peek_session(session_id) -> check if done
-        4. Repeat 2-3 if still running
-        5. check_session(session_id) -> get full results
+    WORKFLOW:
+        1. delegate(task="...") -> session_id
+        2. sleep(30)
+        3. peek_session(session_id) -> {is_running: true/false}
+        4. If is_running, goto 2
+        5. check_session(session_id) -> FULL response
 
     Args:
         task: Clear description of what to do. Be specific about requirements.
@@ -188,13 +186,11 @@ def delegate(
         adapter: Which executor to use - "codex" (default) or "claude".
 
     Returns:
-        {session_id, status: "running", task, adapter, hint}
+        {session_id, status: "running", adapter}
 
-    Example with codex (default):
+    Example:
         delegate(task="Add a logout button to the navbar")
-
-    Example with claude for complex tasks:
-        delegate(task="Refactor the auth system to use OAuth2", adapter="claude")
+        delegate(task="Refactor auth to OAuth2", adapter="claude")
     """
     # Validate adapter
     if adapter not in ADAPTERS:
@@ -346,18 +342,19 @@ def check_session(
     session_id: str,
 ) -> dict[str, Any]:
     """
-    Check the status of a session.
+    Check the status of a session and get the FULL response.
+
+    This is your primary tool for seeing what an executor accomplished.
+    Returns the complete, untruncated response from the agent.
 
-    Use this to:
-    - Check if an async session has finished
-    - Get current status and message count
-    - View the latest response
+    Use this after peek_session() shows the session is done, or when
+    you need to see the full details of what was accomplished.
 
     Args:
         session_id: The session to check.
 
     Returns:
-        {session_id, status, messages, response}
+        {session_id, status, response (FULL), tokens, runtime}
     """
     manager = _get_session_manager(self)
 
@@ -369,12 +366,12 @@ def check_session(
             "hint": "Use list_sessions() to see available sessions",
         }
 
-    # Get latest response
+    # Get latest response - FULL, not truncated
     response_text = ""
     messages = manager.get_messages(session_id)
     for msg in reversed(messages):
         if msg.role == "assistant":
-            response_text = msg.content
+            response_text = msg.content  # Full content, no truncation
             break
 
     # Build log path
@@ -388,8 +385,8 @@ def check_session(
         "is_running": session.is_running,
         "turn": session.turn,
         "message_count": len(messages),
-        "task": _truncate(session.task, 80),
-        "response": _truncate(response_text, 500) if response_text else "(no response yet)",
+        "task": _truncate(session.task, 80),  # Task can stay truncated
+        "response": response_text if response_text else "(no response yet)",  # FULL response
         "tokens": _get_total_tokens(session),
         "runtime": session.runtime,
         "log_file": log_path,
@@ -410,15 +407,21 @@ def peek_session(
     session_id: str,
 ) -> dict[str, Any]:
     """
-    Quick peek at a session - minimal info for fast polling.
+    Quick peek at a session - minimal info for FAST POLLING.
+
+    Use this in your polling loop to check if a session is done:
+        1. delegate() -> start work
+        2. sleep(30)
+        3. peek_session() -> is_running? If yes, goto 2
+        4. check_session() -> get FULL response
 
-    Returns just status and latest message. Use check_session() for full details.
+    Returns truncated preview only. Once done, use check_session() for full response.
 
     Args:
         session_id: The session to peek at.
 
     Returns:
-        {session_id, status, latest_message}
+        {session_id, status, is_running, latest_message (truncated preview)}
     """
     manager = _get_session_manager(self)
 
@@ -450,18 +453,23 @@ def get_trajectory(
     full: bool = False,
 ) -> dict[str, Any]:
     """
-    Get the full trajectory of a session - all steps the agent took.
+    Get the step-by-step trajectory of what the agent did.
 
-    Shows reasoning, commands, tool calls, and responses in order.
-    Useful for understanding HOW the agent completed a task, not just
-    the final result.
+    Shows reasoning, commands, tool calls, and responses in execution order.
+    Use this to understand HOW the agent approached a task, debug failures,
+    or verify the agent took the right steps.
 
     Args:
         session_id: The session to get trajectory for.
-        full: If True, include full untruncated content (default: False for summary view).
+        full: If True, include FULL untruncated content for all steps.
+              If False (default), returns concise summaries.
 
     Returns:
-        {steps: [...], step_count}
+        {steps: ["[thinking] ...", "[command] $ ...", "[response] ..."], step_count}
+
+    When to use:
+    - check_session() -> what did the agent conclude? (FULL response)
+    - get_trajectory() -> what steps did the agent take? (step-by-step)
     """
     manager = _get_session_manager(self)
 

{zwarm-3.6.0.dist-info → zwarm-3.8.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zwarm
-Version: 3.6.0
+Version: 3.8.0
 Summary: Multi-Agent CLI Orchestration Research Platform
 Requires-Python: <3.14,>=3.13
 Requires-Dist: prompt-toolkit>=3.0.52
@@ -78,6 +78,8 @@ zwarm orchestrate --task "Build a REST API with authentication"
 
 # Or manual control
 zwarm interactive
+
+Want a 3-minute walkthrough? See `docs/DEMO.md` for a pilot + interactive demo.
 ```
 
 ---

{zwarm-3.6.0.dist-info → zwarm-3.8.0.dist-info}/RECORD

@@ -1,16 +1,16 @@
 zwarm/__init__.py,sha256=3i3LMjHwIzE-LFIS2aUrwv3EZmpkvVMe-xj1h97rcSM,837
-zwarm/orchestrator.py,sha256=1IitiuhlCRGd512p3ObwiwI8c2zDzq1yzLTs_y6Mv_o,22803
+zwarm/orchestrator.py,sha256=CqZpe4h8-Z7rpy-boN2W9-sZdFfLONOnNMp2MJP2pbc,25292
 zwarm/test_orchestrator_watchers.py,sha256=QpoaehPU7ekT4XshbTOWnJ2H0wRveV3QOZjxbgyJJLY,807
 zwarm/cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-zwarm/cli/interactive.py,sha256=zNxaU7U3PwHyx04-aiGqxyxwCsKhX-0jG0tzMlvrV24,39031
+zwarm/cli/interactive.py,sha256=81w9vw6yoqFS6l973OPgoNEgV9Ngcy-3Gj_LhHhRtto,41641
 zwarm/cli/main.py,sha256=vQGgbAkg_8ei5UTF-IvTtRv3Vxb85NNApVECwT1ghlg,77443
-zwarm/cli/pilot.py,sha256=my0j6-YpWRTFZ8tMrsh2wtJ2n9BP58JokvP7K8ssl7Q,42403
+zwarm/cli/pilot.py,sha256=13eKX5yMaSQh16nHAqBsInVHmBiAy9DxUfCvNBHrgCI,42512
 zwarm/core/__init__.py,sha256=nEdpEHMFo0gEEKgX-eKHabyOdrOI6UXfWqLu3FfZDao,376
 zwarm/core/checkpoints.py,sha256=D6sXCMB7Sa1kchQ9_lQx_rabwc5-_7jbuynWgA1nkNY,6560
 zwarm/core/compact.py,sha256=Y8C7Gs-5-WOU43WRvQ863Qzd5xtuEqR6Aw3r2p8_-i8,10907
 zwarm/core/config.py,sha256=m3Vm6U_BNtEDu_cz2d6E3p_RNQfRHWaq-946mDru9-8,12656
 zwarm/core/costs.py,sha256=Z-5o-ZQWRCfFv0mTHev4Ke1AzyXKhXWO6ss7S8eBX9U,1485
-zwarm/core/environment.py,sha256=zrgh0N3Ng4HI2F1gCYkcQVGzjQPKiIFWuRe1OPRuRn0,6558
+zwarm/core/environment.py,sha256=v7wwVCTIOt_qfiJEe774oM4vIYnlb28s6LJXucJdjoo,8735
 zwarm/core/models.py,sha256=PrC3okRBVJxISUa1Fax4KkagqLT6Xub-kTxC9drN0sY,10083
 zwarm/core/registry.py,sha256=-3mwW4MZ8LKM9SuNBR-r5KWFcQx5F7gqnKfghikxzAI,9484
 zwarm/core/state.py,sha256=MzrvODKEiJovI7YI1jajW4uukineZ3ezmW5oQinMgjg,11563
@@ -18,14 +18,14 @@ zwarm/core/test_compact.py,sha256=WSdjCB5t4YMcknsrkmJIUsVOPY28s4y9GnDmu3Z4BFw,11
 zwarm/core/test_config.py,sha256=bXXd3OHhK-ndC7wAxePWIdpu73s4O1eScxi3xDzrZwA,4828
 zwarm/core/test_models.py,sha256=sWTIhMZvuLP5AooGR6y8OR2EyWydqVfhmGrE7NPBBnk,8450
 zwarm/prompts/__init__.py,sha256=DI307o712F8qQyDt5vwnFgpVBrxpKwjhr0MaBHLzr9E,334
-zwarm/prompts/orchestrator.py,sha256=AkVbEpT91QbYFjUYOzm0d37wXrpm0esLBD1MG_W-3FI,15367
-zwarm/prompts/pilot.py,sha256=BcaV04-43FZyrtmoqCbA7DqnTlQ330TcDp9wNGhRojo,5586
+zwarm/prompts/orchestrator.py,sha256=rfxpVCNAlTdQN8h0hgtU1OOr_9Io62ULZFisBjNUZVs,15076
+zwarm/prompts/pilot.py,sha256=K5NkIBK0zuBprkiNILLhtIgj-lQ7_GhLlfDItev_cJI,5517
 zwarm/sessions/__init__.py,sha256=5fPkl6JRS_GwPn9hi5iv3dzIpGWu_yghPtvPZdujhnM,1728
-zwarm/sessions/base.py,sha256=UA5E39xDx5q4qX2rUcvhSX7cfrCEqTS3F9Tj-ubmrJA,16538
+zwarm/sessions/base.py,sha256=3YBd-WWKslQvsBtu03Blth8cEGc_4k4H3GOoKJoTcgg,16976
 zwarm/sessions/claude.py,sha256=hBP_TpNFJjR29IRGJFB3rlG7Z9uWEYSbBGV61tpIr00,16672
 zwarm/sessions/manager.py,sha256=Vq5PePzKfy658EVG24SFsUMXQc1OGgOm8vdOX_WPMF8,18530
 zwarm/tools/__init__.py,sha256=FpqxwXJA6-fQ7C-oLj30jjK_0qqcE7MbI0dQuaB56kU,290
-zwarm/tools/delegation.py,sha256=FM8CIqm3ic6mHjVmY1DkOpTdMIYi21TniMclhdtPRn4,23424
+zwarm/tools/delegation.py,sha256=Pg4aZ6JlInN9wLE7rmuGCHct5Nf_HUSnWkUjLEnTzWc,24050
 zwarm/watchers/__init__.py,sha256=a96s7X6ruYkF2ItWWOZ3Q5QUOMOoeCW4Vz8XXcYLXPM,956
 zwarm/watchers/base.py,sha256=r1GoPlj06nOT2xp4fghfSjxbRyFFFQUB6HpZbEyO2OY,3834
 zwarm/watchers/builtin.py,sha256=IL5QwwKOIqWEfJ_uQWb321Px4i5OLtI_vnWQMudqKoA,19064
@@ -33,7 +33,7 @@ zwarm/watchers/llm_watcher.py,sha256=yJGpE3BGKNZX3qgPsiNtJ5d3UJpiTT1V-A-Rh4AiMYM
 zwarm/watchers/manager.py,sha256=XZjBVeHjgCUlkTUeHqdvBvHoBC862U1ik0fG6nlRGog,5587
 zwarm/watchers/registry.py,sha256=A9iBIVIFNtO7KPX0kLpUaP8dAK7ozqWLA44ocJGnOw4,1219
 zwarm/watchers/test_watchers.py,sha256=zOsxumBqKfR5ZVGxrNlxz6KcWjkcdp0QhW9WB0_20zM,7855
-zwarm-3.6.0.dist-info/METADATA,sha256=5nkx2jC93DRcLohSvGdZk-W1XWeOc1DModIazvr0gwI,11311
-zwarm-3.6.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-zwarm-3.6.0.dist-info/entry_points.txt,sha256=u0OXq4q8d3yJ3EkUXwZfkS-Y8Lcy0F8cWrcQfoRxM6Q,46
-zwarm-3.6.0.dist-info/RECORD,,
+zwarm-3.8.0.dist-info/METADATA,sha256=6rv5Ntx99zDEKsnxVs_PKeUYm9cUHAda8UF23A39dGY,11392
+zwarm-3.8.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+zwarm-3.8.0.dist-info/entry_points.txt,sha256=u0OXq4q8d3yJ3EkUXwZfkS-Y8Lcy0F8cWrcQfoRxM6Q,46
+zwarm-3.8.0.dist-info/RECORD,,