zwarm 1.2.1__tar.gz → 1.3.3__tar.gz

{zwarm-1.2.1 → zwarm-1.3.3}/.gitignore

@@ -19,3 +19,5 @@ dist-ssr/
 *.local
 
 jobs/
+
+.zwarm/

{zwarm-1.2.1 → zwarm-1.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zwarm
-Version: 1.2.1
+Version: 1.3.3
 Summary: Multi-Agent CLI Orchestration Research Platform
 Requires-Python: <3.14,>=3.13
 Requires-Dist: python-dotenv>=1.0.0
@@ -136,12 +136,17 @@ state_dir: .zwarm             # State directory for sessions/events
 
 watchers:
   enabled: true
+  message_role: user            # Role for nudge messages: user | assistant | system
   watchers:
     - name: progress
     - name: budget
       config:
         max_steps: 50
         max_sessions: 10
+    - name: delegation_reminder
+      config:
+        threshold: 10           # Nudge after N consecutive non-delegation calls
+        lookback: 30            # How many messages to check
     - name: scope
       config:
         keywords: []
@@ -217,28 +222,38 @@ Watchers are composable guardrails that monitor agent behavior and can intervene
 | `pattern` | Custom regex pattern matching |
 | `quality` | Code quality checks |
 | `delegation` | Ensures orchestrator delegates instead of writing code directly |
+| `delegation_reminder` | Nudges after many consecutive non-delegation tool calls (default: 10) |
 
 ### Enabling Watchers
 
 ```yaml
 # config.yaml
 watchers:
-  enabled:
-    - progress
-    - budget
-    - scope
-  config:
-    progress:
-      stuck_threshold: 5      # Flag after 5 similar steps
-    budget:
-      max_steps: 50
-      max_sessions: 10
-    scope:
-      keywords:
-        - "refactor"
-        - "rewrite"
+  enabled: true
+  message_role: user              # How nudges appear: user | assistant | system
+  watchers:
+    - name: progress
+      config:
+        max_same_calls: 3         # Flag after 3 identical tool calls
+    - name: budget
+      config:
+        max_steps: 50
+        max_sessions: 10
+    - name: delegation_reminder
+      config:
+        threshold: 10             # Nudge after 10 non-delegation calls
+    - name: scope
+      config:
+        avoid_keywords:
+          - "refactor everything"
+          - "rewrite"
 ```
 
+The `message_role` setting controls how watcher nudges are injected:
+- `user` (default): Appears as a user message - strong nudge, agent must respond
+- `assistant`: Appears as a previous assistant thought - softer, agent can continue
+- `system`: Appears as system instruction - authoritative guidance
+
 ### Watcher Actions
 
 Watchers can return different actions:

{zwarm-1.2.1 → zwarm-1.3.3}/README.md

@@ -124,12 +124,17 @@ state_dir: .zwarm             # State directory for sessions/events
 
 watchers:
   enabled: true
+  message_role: user            # Role for nudge messages: user | assistant | system
   watchers:
     - name: progress
     - name: budget
       config:
         max_steps: 50
         max_sessions: 10
+    - name: delegation_reminder
+      config:
+        threshold: 10           # Nudge after N consecutive non-delegation calls
+        lookback: 30            # How many messages to check
     - name: scope
       config:
         keywords: []
@@ -205,28 +210,38 @@ Watchers are composable guardrails that monitor agent behavior and can intervene
 | `pattern` | Custom regex pattern matching |
 | `quality` | Code quality checks |
 | `delegation` | Ensures orchestrator delegates instead of writing code directly |
+| `delegation_reminder` | Nudges after many consecutive non-delegation tool calls (default: 10) |
 
 ### Enabling Watchers
 
 ```yaml
 # config.yaml
 watchers:
-  enabled:
-    - progress
-    - budget
-    - scope
-  config:
-    progress:
-      stuck_threshold: 5      # Flag after 5 similar steps
-    budget:
-      max_steps: 50
-      max_sessions: 10
-    scope:
-      keywords:
-        - "refactor"
-        - "rewrite"
+  enabled: true
+  message_role: user              # How nudges appear: user | assistant | system
+  watchers:
+    - name: progress
+      config:
+        max_same_calls: 3         # Flag after 3 identical tool calls
+    - name: budget
+      config:
+        max_steps: 50
+        max_sessions: 10
+    - name: delegation_reminder
+      config:
+        threshold: 10             # Nudge after 10 non-delegation calls
+    - name: scope
+      config:
+        avoid_keywords:
+          - "refactor everything"
+          - "rewrite"
 ```
 
+The `message_role` setting controls how watcher nudges are injected:
+- `user` (default): Appears as a user message - strong nudge, agent must respond
+- `assistant`: Appears as a previous assistant thought - softer, agent can continue
+- `system`: Appears as system instruction - authoritative guidance
+
 ### Watcher Actions
 
 Watchers can return different actions:

{zwarm-1.2.1 → zwarm-1.3.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "zwarm"
-version = "1.2.1"
+version = "1.3.3"
 description = "Multi-Agent CLI Orchestration Research Platform"
 readme = "README.md"
 requires-python = ">=3.13,<3.14"

{zwarm-1.2.1 → zwarm-1.3.3}/src/zwarm/adapters/codex_mcp.py

@@ -549,20 +549,33 @@ class CodexMCPAdapter(ExecutorAdapter):
         """
         client = self._ensure_client()
 
+        logger.debug(f"Calling codex-reply with conversation_id={conversation_id}")
+
         result = client.call_tool("codex-reply", {
             "conversationId": conversation_id,
             "prompt": message,
         })
 
+        # Check for conversation loss - MCP returns empty result when session not found
+        if not result.get("messages") and not result.get("output"):
+            logger.error(
+                f"codex-reply returned empty result for conversation_id={conversation_id}. "
+                f"The MCP server may have lost the conversation state. Result: {result}"
+            )
+
         # Track usage
         usage = result.get("usage", {})
         self._accumulate_usage(usage)
 
+        response = self._extract_response(result)
+        logger.debug(f"codex-reply response length: {len(response)} chars")
+
         return {
-            "response": self._extract_response(result),
+            "response": response,
             "raw_messages": result.get("messages", []),
             "usage": usage,
             "total_usage": self.total_usage,
+            "conversation_lost": not result.get("messages") and not result.get("output"),
         }
 
     @weave.op()
@@ -598,6 +611,13 @@ class CodexMCPAdapter(ExecutorAdapter):
             session.conversation_id = result["conversation_id"]
             if session.conversation_id:
                 self._sessions[session.id] = session.conversation_id
+                logger.debug(f"Session {session.id[:8]} mapped to conversation {session.conversation_id}")
+            else:
+                # This is bad - we won't be able to continue this conversation
+                logger.warning(
+                    f"Session {session.id[:8]} started but MCP didn't return a conversation ID. "
+                    "Further converse() calls will fail."
+                )
 
             session.add_message("user", task)
             session.add_message("assistant", result["response"])
@@ -652,6 +672,16 @@ class CodexMCPAdapter(ExecutorAdapter):
         )
 
         response_text = result["response"]
+
+        # Check if conversation was lost
+        if result.get("conversation_lost"):
+            logger.warning(
+                f"Conversation {session.conversation_id} was lost. "
+                f"Session {session.id} will be marked as needing re-delegation."
+            )
+            # Mark the session as having a lost conversation so orchestrator can handle it
+            session.conversation_id = None  # Clear the stale ID
+
         session.add_message("user", message)
         session.add_message("assistant", response_text)
 
@@ -797,6 +827,15 @@ class CodexMCPAdapter(ExecutorAdapter):
 
     def _extract_response(self, result: dict) -> str:
         """Extract response text from MCP result."""
+        # Check for error indicators - empty result suggests lost conversation
+        if (
+            result.get("conversationId") is None
+            and not result.get("messages")
+            and not result.get("output")
+        ):
+            logger.warning(f"MCP returned empty result - conversation may be lost: {result}")
+            return "[ERROR] Conversation lost - the MCP server no longer has this session. Please re-delegate the task."
+
         # First check for our collected output
         if result.get("output"):
             return result["output"]
@@ -823,5 +862,6 @@ class CodexMCPAdapter(ExecutorAdapter):
         if "text" in result:
             return result["text"]
 
-        # Fallback: stringify the result
+        # Fallback: stringify the result (but log it as unexpected)
+        logger.warning(f"Unexpected MCP result format, returning raw: {list(result.keys())}")
         return json.dumps(result, indent=2)

{zwarm-1.2.1 → zwarm-1.3.3}/src/zwarm/cli/main.py

@@ -141,6 +141,8 @@ def orchestrate(
     resume: Annotated[bool, typer.Option("--resume", help="Resume from previous state")] = False,
     max_steps: Annotated[Optional[int], typer.Option("--max-steps", help="Maximum orchestrator steps")] = None,
     verbose: Annotated[bool, typer.Option("--verbose", "-v", help="Show detailed output")] = False,
+    instance: Annotated[Optional[str], typer.Option("--instance", "-i", help="Instance ID (for isolation/resume)")] = None,
+    instance_name: Annotated[Optional[str], typer.Option("--name", "-n", help="Human-readable instance name")] = None,
 ):
     """
     Start an orchestrator session.
@@ -149,6 +151,9 @@ def orchestrate(
     (Codex, Claude Code). It can have sync conversations or fire-and-forget
     async delegations.
 
+    Each run creates an isolated instance to prevent conflicts when running
+    multiple orchestrators in the same directory.
+
     [bold]Examples:[/]
         [dim]# Simple task[/]
         $ zwarm orchestrate --task "Add a logout button to the navbar"
@@ -166,8 +171,14 @@ def orchestrate(
         [dim]# Override settings[/]
         $ zwarm orchestrate --task "Fix bug" --set executor.adapter=claude_code
 
-        [dim]# Resume interrupted session[/]
-        $ zwarm orchestrate --task "Continue work" --resume
+        [dim]# Named instance (easier to track)[/]
+        $ zwarm orchestrate --task "Add tests" --name test-work
+
+        [dim]# Resume a specific instance[/]
+        $ zwarm orchestrate --resume --instance abc123
+
+        [dim]# List all instances[/]
+        $ zwarm instances
     """
     from zwarm.orchestrator import build_orchestrator
 
@@ -187,6 +198,8 @@ def orchestrate(
     console.print(f"[bold]Starting orchestrator...[/]")
     console.print(f"  Task: {task}")
     console.print(f"  Working dir: {working_dir.absolute()}")
+    if instance:
+        console.print(f"  Instance: {instance}" + (f" ({instance_name})" if instance_name else ""))
     console.print()
 
     # Output handler to show orchestrator messages
@@ -203,11 +216,17 @@ def orchestrate(
             overrides=override_list,
             resume=resume,
             output_handler=output_handler,
+            instance_id=instance,
+            instance_name=instance_name,
         )
 
         if resume:
             console.print("  [dim]Resuming from previous state...[/]")
 
+        # Show instance ID if auto-generated
+        if orchestrator.instance_id and not instance:
+            console.print(f"  [dim]Instance: {orchestrator.instance_id[:8]}[/]")
+
         # Run the orchestrator loop
         console.print("[bold]--- Orchestrator running ---[/]\n")
         result = orchestrator.run(task=task)
@@ -223,16 +242,35 @@ def orchestrate(
         # Save state for potential resume
         orchestrator.save_state()
 
+        # Update instance status
+        if orchestrator.instance_id:
+            from zwarm.core.state import update_instance_status
+            update_instance_status(
+                orchestrator.instance_id,
+                "completed",
+                working_dir / ".zwarm",
+            )
+            console.print(f"  [dim]Instance {orchestrator.instance_id[:8]} marked completed[/]")
+
     except KeyboardInterrupt:
         console.print("\n\n[yellow]Interrupted.[/]")
         if orchestrator:
             orchestrator.save_state()
             console.print("[dim]State saved. Use --resume to continue.[/]")
+            # Keep instance as "active" so it can be resumed
         sys.exit(1)
     except Exception as e:
         console.print(f"\n[red]Error:[/] {e}")
         if verbose:
             console.print_exception()
+        # Update instance status to failed
+        if orchestrator and orchestrator.instance_id:
+            from zwarm.core.state import update_instance_status
+            update_instance_status(
+                orchestrator.instance_id,
+                "failed",
+                working_dir / ".zwarm",
+            )
         sys.exit(1)
 
 
@@ -384,6 +422,63 @@ def status(
         console.print("  [dim](none)[/]")
 
 
+@app.command()
+def instances(
+    working_dir: Annotated[Path, typer.Option("--working-dir", "-w", help="Working directory")] = Path("."),
+    all_instances: Annotated[bool, typer.Option("--all", "-a", help="Show all instances (including completed)")] = False,
+):
+    """
+    List all orchestrator instances.
+
+    Shows instances that have been run in this directory. Use --all to include
+    completed instances.
+
+    [bold]Examples:[/]
+        [dim]# List active instances[/]
+        $ zwarm instances
+
+        [dim]# List all instances[/]
+        $ zwarm instances --all
+    """
+    from zwarm.core.state import list_instances as get_instances
+
+    state_dir = working_dir / ".zwarm"
+    all_inst = get_instances(state_dir)
+
+    if not all_inst:
+        console.print("[dim]No instances found.[/]")
+        console.print("[dim]Run 'zwarm orchestrate' to start a new instance.[/]")
+        return
+
+    # Filter if not showing all
+    if not all_instances:
+        all_inst = [i for i in all_inst if i.get("status") == "active"]
+
+    if not all_inst:
+        console.print("[dim]No active instances. Use --all to see completed ones.[/]")
+        return
+
+    console.print(f"[bold]Instances[/] ({len(all_inst)} total)\n")
+
+    for inst in all_inst:
+        status = inst.get("status", "unknown")
+        status_icon = {"active": "[green]●[/]", "completed": "[dim]✓[/]", "failed": "[red]✗[/]"}.get(status, "[dim]?[/]")
+
+        inst_id = inst.get("id", "unknown")[:8]
+        name = inst.get("name", "")
+        task = (inst.get("task") or "")[:60]
+        updated = inst.get("updated_at", "")[:19] if inst.get("updated_at") else ""
+
+        console.print(f"  {status_icon} [bold]{inst_id}[/]" + (f" ({name})" if name and name != inst_id else ""))
+        if task:
+            console.print(f"      [dim]{task}[/]")
+        if updated:
+            console.print(f"      [dim]Updated: {updated}[/]")
+        console.print()
+
+    console.print("[dim]Use --instance <id> with 'orchestrate --resume' to resume an instance.[/]")
+
+
 @app.command()
 def history(
     working_dir: Annotated[Path, typer.Option("--working-dir", "-w", help="Working directory")] = Path("."),
@@ -577,7 +672,7 @@ def init(
     # Gather settings
     weave_project = ""
     adapter = "codex_mcp"
-    watchers_enabled = ["progress", "budget", "delegation"]
+    watchers_enabled = ["progress", "budget", "delegation", "delegation_reminder"]
     create_project_config = with_project
     project_description = ""
     project_context = ""
@@ -601,10 +696,10 @@ def init(
 
         # Watchers
         console.print("\n  [bold]Watchers[/] (trajectory aligners)")
-        available_watchers = ["progress", "budget", "delegation", "scope", "pattern", "quality"]
+        available_watchers = ["progress", "budget", "delegation", "delegation_reminder", "scope", "pattern", "quality"]
         watchers_enabled = []
         for w in available_watchers:
-            default = w in ["progress", "budget", "delegation"]
+            default = w in ["progress", "budget", "delegation", "delegation_reminder"]
             if typer.confirm(f"    Enable {w}?", default=default):
                 watchers_enabled.append(w)
 

{zwarm-1.2.1 → zwarm-1.3.3}/src/zwarm/core/config.py

@@ -86,7 +86,13 @@ class WatchersConfig:
     watchers: list[WatcherConfigItem] = field(default_factory=lambda: [
         WatcherConfigItem(name="progress"),
         WatcherConfigItem(name="budget"),
+        WatcherConfigItem(name="delegation_reminder"),
     ])
+    # Role for watcher nudge messages: "user" | "assistant" | "system"
+    # "user" (default) - Appears as if user sent the message, strong nudge
+    # "assistant" - Appears as previous assistant thought, softer nudge
+    # "system" - Appears as system instruction, authoritative
+    message_role: str = "user"
 
 
 @dataclass
@@ -122,13 +128,14 @@ class ZwarmConfig:
                 ],
             )
         else:
-            # Full format: watchers: {enabled: true, watchers: [...]}
+            # Full format: watchers: {enabled: true, watchers: [...], message_role: "user"}
             watchers_config = WatchersConfig(
                 enabled=watchers_data.get("enabled", True),
                 watchers=[
                     WatcherConfigItem(name=w) if isinstance(w, str) else WatcherConfigItem(**w)
                     for w in watchers_data.get("watchers", [])
                 ] or WatchersConfig().watchers,
+                message_role=watchers_data.get("message_role", "user"),
             )
 
         # Build orchestrator config with nested compaction
@@ -180,6 +187,7 @@ class ZwarmConfig:
                     {"name": w.name, "enabled": w.enabled, "config": w.config}
                     for w in self.watchers.watchers
                 ],
+                "message_role": self.watchers.message_role,
             },
             "state_dir": self.state_dir,
         }

{zwarm-1.2.1 → zwarm-1.3.3}/src/zwarm/core/state.py

@@ -1,16 +1,25 @@
 """
 Flat-file state management for zwarm.
 
-State structure:
+State structure (with instance isolation):
 .zwarm/
-├── state.json              # Current state (sessions, tasks)
-├── events.jsonl            # Append-only event log
-├── sessions/
-│   └── <session-id>/
-│       ├── messages.json   # Full conversation history
-│       └── output.log      # Agent stdout/stderr
-└── orchestrator/
-    └── messages.json       # Orchestrator's message history (for resume)
+├── instances.json              # Registry of all instances
+└── instances/
+    └── <instance-id>/
+        ├── state.json          # Current state (sessions, tasks)
+        ├── events.jsonl        # Append-only event log
+        ├── sessions/
+        │   └── <session-id>/
+        │       ├── messages.json
+        │       └── output.log
+        └── orchestrator/
+            └── messages.json   # Orchestrator's message history (for resume)
+
+Legacy structure (single instance, for backwards compat):
+.zwarm/
+├── state.json
+├── events.jsonl
+└── ...
 """
 
 from __future__ import annotations
@@ -19,10 +28,116 @@ import json
 from datetime import datetime
 from pathlib import Path
 from typing import Any
+from uuid import uuid4
 
 from .models import ConversationSession, Event, Task
 
 
+# --- Instance Registry ---
+
+def get_instances_registry_path(base_dir: Path | str = ".zwarm") -> Path:
+    """Get path to the instances registry file."""
+    return Path(base_dir) / "instances.json"
+
+
+def list_instances(base_dir: Path | str = ".zwarm") -> list[dict[str, Any]]:
+    """List all registered instances."""
+    registry_path = get_instances_registry_path(base_dir)
+    if not registry_path.exists():
+        return []
+    try:
+        return json.loads(registry_path.read_text()).get("instances", [])
+    except (json.JSONDecodeError, KeyError):
+        return []
+
+
+def register_instance(
+    instance_id: str,
+    name: str | None = None,
+    task: str | None = None,
+    base_dir: Path | str = ".zwarm",
+) -> None:
+    """Register an instance in the global registry."""
+    base = Path(base_dir)
+    base.mkdir(parents=True, exist_ok=True)
+
+    registry_path = get_instances_registry_path(base_dir)
+
+    # Load existing registry
+    if registry_path.exists():
+        try:
+            registry = json.loads(registry_path.read_text())
+        except json.JSONDecodeError:
+            registry = {"instances": []}
+    else:
+        registry = {"instances": []}
+
+    # Check if instance already registered
+    existing_ids = {inst["id"] for inst in registry["instances"]}
+    if instance_id in existing_ids:
+        # Update existing entry
+        for inst in registry["instances"]:
+            if inst["id"] == instance_id:
+                inst["updated_at"] = datetime.now().isoformat()
+                inst["status"] = "active"
+                if name:
+                    inst["name"] = name
+                if task:
+                    inst["task"] = task[:100]  # Truncate
+                break
+    else:
+        # Add new entry
+        registry["instances"].append({
+            "id": instance_id,
+            "name": name or instance_id[:8],
+            "task": (task[:100] if task else None),
+            "created_at": datetime.now().isoformat(),
+            "updated_at": datetime.now().isoformat(),
+            "status": "active",
+        })
+
+    registry_path.write_text(json.dumps(registry, indent=2))
+
+
+def update_instance_status(
+    instance_id: str,
+    status: str,
+    base_dir: Path | str = ".zwarm",
+) -> None:
+    """Update an instance's status in the registry."""
+    registry_path = get_instances_registry_path(base_dir)
+    if not registry_path.exists():
+        return
+
+    try:
+        registry = json.loads(registry_path.read_text())
+    except json.JSONDecodeError:
+        return
+
+    for inst in registry.get("instances", []):
+        if inst["id"] == instance_id:
+            inst["status"] = status
+            inst["updated_at"] = datetime.now().isoformat()
+            break
+
+    registry_path.write_text(json.dumps(registry, indent=2))
+
+
+def get_instance_state_dir(
+    instance_id: str | None = None,
+    base_dir: Path | str = ".zwarm",
+) -> Path:
+    """
+    Get the state directory for an instance.
+
+    If instance_id is None, returns the legacy path for backwards compat.
+    """
+    base = Path(base_dir)
+    if instance_id is None:
+        return base  # Legacy: .zwarm/
+    return base / "instances" / instance_id
+
+
 def _json_serializer(obj: Any) -> Any:
     """Custom JSON serializer for non-standard types."""
     # Handle pydantic models
@@ -42,15 +157,31 @@ class StateManager:
     """
     Manages flat-file state for zwarm.
 
-    All state is stored as JSON files in a directory (default: .zwarm/).
+    All state is stored as JSON files in a directory.
+    With instance isolation: .zwarm/instances/<instance-id>/
+    Legacy (no instance): .zwarm/
+
     This enables:
     - Git-backed history
     - Easy debugging (just read the files)
     - Resume from previous state
+    - Multiple concurrent orchestrators (with instance isolation)
     """
 
-    def __init__(self, state_dir: Path | str = ".zwarm"):
-        self.state_dir = Path(state_dir)
+    def __init__(
+        self,
+        state_dir: Path | str = ".zwarm",
+        instance_id: str | None = None,
+    ):
+        self.base_dir = Path(state_dir)
+        self.instance_id = instance_id
+
+        # Resolve actual state directory
+        if instance_id:
+            self.state_dir = get_instance_state_dir(instance_id, self.base_dir)
+        else:
+            self.state_dir = self.base_dir
+
         self._sessions: dict[str, ConversationSession] = {}
         self._tasks: dict[str, Task] = {}
         self._orchestrator_messages: list[dict[str, Any]] = []

{zwarm-1.2.1 → zwarm-1.3.3}/src/zwarm/orchestrator.py

@@ -52,6 +52,10 @@ class Orchestrator(YamlAgent):
     config: ZwarmConfig = Field(default_factory=ZwarmConfig)
     working_dir: Path = Field(default_factory=Path.cwd)
 
+    # Instance identification (for multi-orchestrator isolation)
+    instance_id: str | None = Field(default=None)
+    instance_name: str | None = Field(default=None)
+
     # Load tools from modules (delegation + bash for verification)
     agent_tool_modules: list[str] = Field(
         default=[
@@ -77,11 +81,25 @@ class Orchestrator(YamlAgent):
         """Initialize state and adapters after model creation."""
         super().model_post_init(__context)
 
-        # Initialize state manager
-        self._state = StateManager(self.working_dir / self.config.state_dir)
+        # Initialize state manager with instance isolation
+        base_state_dir = self.working_dir / self.config.state_dir
+        self._state = StateManager(
+            state_dir=base_state_dir,
+            instance_id=self.instance_id,
+        )
         self._state.init()
         self._state.load()
 
+        # Register instance if using instance isolation
+        if self.instance_id:
+            from zwarm.core.state import register_instance
+            register_instance(
+                instance_id=self.instance_id,
+                name=self.instance_name,
+                task=None,  # Will be updated when task is set
+                base_dir=base_state_dir,
+            )
+
         # Load existing sessions
         for session in self._state.list_sessions():
             self._sessions[session.id] = session
@@ -215,12 +233,18 @@ class Orchestrator(YamlAgent):
         if not self._resumed:
             return
 
-        # Build list of old sessions
+        # Build list of old sessions and INVALIDATE their conversation IDs
+        # The MCP server was restarted, so all conversation IDs are now stale
         old_sessions = []
+        invalidated_count = 0
         for sid, session in self._sessions.items():
             old_sessions.append(
                 f"  - {sid[:8]}... ({session.adapter}, {session.status.value})"
             )
+            # Clear stale conversation_id to prevent converse() from trying to use it
+            if session.conversation_id:
+                session.conversation_id = None
+                invalidated_count += 1
 
         session_info = "\n".join(old_sessions) if old_sessions else "  (none)"
 
@@ -228,14 +252,14 @@ class Orchestrator(YamlAgent):
             "role": "user",
             "content": f"""[SYSTEM NOTICE] You have been resumed from a previous session.
 
-IMPORTANT: Your previous executor sessions are NO LONGER ACTIVE. The MCP connections and subprocess handles were lost when the previous session ended.
+CRITICAL: Your previous executor sessions are NO LONGER USABLE. The MCP server was restarted, so all conversation state was lost. {invalidated_count} conversation ID(s) have been invalidated.
 
-Previous sessions (now stale):
+Previous sessions (conversation IDs cleared):
 {session_info}
 
-You must start NEW sessions with delegate() if you need to continue work. Do NOT try to use converse() or check_session() with the old session IDs - they will fail.
+You MUST start NEW sessions with delegate() to continue any work. The converse() tool will fail on these old sessions because they have no active conversation.
 
-Continue with your task from where you left off.""",
+Review what was accomplished in the previous session and delegate new tasks as needed.""",
         }
 
         self.messages.append(resume_msg)
@@ -328,10 +352,15 @@ Continue with your task from where you left off.""",
 
         # Handle watcher result
         if result.action == WatcherAction.NUDGE and result.guidance:
-            # Inject guidance as a system message
+            # Inject guidance as a message with configurable role
+            message_role = self.config.watchers.message_role
+            # Validate role (default to user if invalid)
+            if message_role not in ("user", "assistant", "system"):
+                message_role = "user"
+
             self.messages.append(
                 {
-                    "role": "user",
+                    "role": message_role,
                     "content": f"[WATCHER: {result.metadata.get('triggered_by', 'unknown')}] {result.guidance}",
                 }
             )
@@ -521,6 +550,8 @@ def build_orchestrator(
     overrides: list[str] | None = None,
     resume: bool = False,
     output_handler: Callable[[str], None] | None = None,
+    instance_id: str | None = None,
+    instance_name: str | None = None,
 ) -> Orchestrator:
     """
     Build an orchestrator from configuration.
@@ -532,10 +563,14 @@ def build_orchestrator(
         overrides: CLI overrides (--set key=value)
         resume: Whether to resume from previous state
         output_handler: Function to handle orchestrator output
+        instance_id: Unique ID for this instance (enables multi-orchestrator isolation)
+        instance_name: Human-readable name for this instance
 
     Returns:
         Configured Orchestrator instance
     """
+    from uuid import uuid4
+
     # Load configuration
     config = load_config(
         config_path=config_path,
@@ -545,6 +580,11 @@ def build_orchestrator(
     # Resolve working directory
     working_dir = working_dir or Path.cwd()
 
+    # Generate instance ID if not provided (enables isolation by default for new runs)
+    # For resume, instance_id should be provided explicitly
+    if instance_id is None and not resume:
+        instance_id = str(uuid4())
+
     # Build system prompt
     system_prompt = _build_system_prompt(config, working_dir)
 
@@ -565,6 +605,8 @@ def build_orchestrator(
         system_prompt=system_prompt,
         maxSteps=config.orchestrator.max_steps,
         env=env,
+        instance_id=instance_id,
+        instance_name=instance_name,
     )
 
     # Resume if requested

{zwarm-1.2.1 → zwarm-1.3.3}/src/zwarm/prompts/orchestrator.py

@@ -43,6 +43,24 @@ Your primary tools are for delegation and verification:
 
 ---
 
+# Watchers
+
+Your execution is monitored by "watchers" - automated systems that observe your trajectory and provide guidance when you may be going off course. Watchers are designed to help you stay aligned with best practices and catch common pitfalls.
+
+When you see a message prefixed with `[WATCHER: ...]`, pay attention. These are interventions from the watcher system indicating that your current approach may need adjustment. Watchers might notice:
+
+- You're doing direct work (bash commands) when you should be delegating to executors
+- You're spinning or repeating the same actions without making progress
+- You're approaching resource limits (steps, sessions)
+- You're drifting from the original task scope
+- You're making changes without corresponding tests
+
+Watcher guidance is not optional advice - treat it as an important course correction. If a watcher tells you to delegate instead of doing work directly, delegate. If a watcher says you're stuck, step back and try a different approach. If a watcher warns about budget limits, prioritize and wrap up.
+
+The watchers are on your side. They exist to help you succeed, not to criticize. Heed their guidance promptly.
+
+---
+
 # Sync vs Async: Choosing the Right Mode
 
 The mode you choose for delegation significantly affects how work proceeds.

{zwarm-1.2.1 → zwarm-1.3.3}/src/zwarm/tools/delegation.py

@@ -194,7 +194,7 @@ def delegate(
     header = _format_session_header(session.id, adapter_name, mode)
 
     if mode == "sync":
-        return {
+        result = {
             "success": True,
             "session": header,
             "session_id": session.id,
@@ -204,6 +204,14 @@ def delegate(
             "tokens": session.token_usage.get("total_tokens", 0),
             "hint": "Use converse(session_id, message) to continue this conversation",
         }
+        # Warn if no conversation ID - converse() won't work
+        if not session.conversation_id:
+            result["warning"] = "no_conversation_id"
+            result["hint"] = (
+                "WARNING: MCP didn't return a conversation ID. "
+                "You cannot use converse() - send all instructions upfront or use async mode."
+            )
+        return result
     else:
         return {
             "success": True,
@@ -263,6 +271,18 @@ def converse(
             "hint": "Start a new session with delegate()",
         }
 
+    # Check for stale/missing conversation_id (common after resume)
+    if not session.conversation_id:
+        return {
+            "success": False,
+            "error": "Session has no conversation ID (likely stale after resume)",
+            "hint": (
+                "This session's conversation was lost (MCP server restarted). "
+                "Use end_session() to close it, then delegate() a new task."
+            ),
+            "session_id": session_id,
+        }
+
     # Get adapter and send message
     executor = self._get_adapter(session.adapter)
     try:
@@ -288,7 +308,13 @@ def converse(
     turn = len([m for m in session.messages if m.role == "user"])
     header = _format_session_header(session.id, session.adapter, session.mode.value)
 
-    return {
+    # Check for conversation loss (indicated by error in response)
+    conversation_lost = (
+        "[ERROR] Conversation lost" in response
+        or session.conversation_id is None
+    )
+
+    result = {
         "success": True,
         "session": header,
         "session_id": session_id,
@@ -298,6 +324,15 @@ def converse(
         "tokens": session.token_usage.get("total_tokens", 0),
     }
 
+    if conversation_lost:
+        result["warning"] = "conversation_lost"
+        result["hint"] = (
+            "The MCP server lost this conversation. You should end_session() "
+            "and delegate() a new task with the full context."
+        )
+
+    return result
+
 
 @weaveTool
 def check_session(

{zwarm-1.2.1 → zwarm-1.3.3}/src/zwarm/watchers/builtin.py

@@ -340,3 +340,85 @@ class QualityWatcher(Watcher):
                 )
 
         return WatcherResult.ok()
+
+
+@register_watcher("delegation_reminder")
+class DelegationReminderWatcher(Watcher):
+    """
+    Reminds the orchestrator to delegate work instead of doing it directly.
+
+    Counts consecutive non-delegation tool calls (bash commands that aren't
+    delegation-related). When the count exceeds a threshold, nudges the
+    orchestrator to consider delegating to executors instead.
+
+    This is a softer reminder than the DelegationWatcher - it doesn't detect
+    specific code-writing patterns, just notices when the orchestrator seems
+    to be doing a lot of direct work that could potentially be delegated.
+    """
+
+    name = "delegation_reminder"
+    description = "Reminds orchestrator to delegate after many direct tool calls"
+
+    # Tools that count as delegation-related (don't count against threshold)
+    DELEGATION_TOOLS = {
+        "delegate",
+        "converse",
+        "check_session",
+        "end_session",
+        "list_sessions",
+        "chat",  # Talking to user is not direct work
+    }
+
+    async def observe(self, ctx: WatcherContext) -> WatcherResult:
+        config = self.config
+        threshold = config.get("threshold", 10)  # Max consecutive non-delegation calls
+        lookback = config.get("lookback", 30)  # How many messages to check
+
+        # Count consecutive non-delegation tool calls from the end
+        consecutive_non_delegation = 0
+
+        # Look through recent messages in reverse order
+        for msg in reversed(ctx.messages[-lookback:]):
+            if msg.get("role") != "assistant":
+                continue
+
+            tool_calls = msg.get("tool_calls", [])
+            if not tool_calls:
+                # Text-only response doesn't reset counter, but doesn't add to it
+                continue
+
+            # Check each tool call in this message
+            has_delegation = False
+            has_non_delegation = False
+
+            for tc in tool_calls:
+                func = tc.get("function", {})
+                name = func.get("name", "")
+
+                if name in self.DELEGATION_TOOLS:
+                    has_delegation = True
+                elif name:  # Any other tool call
+                    has_non_delegation = True
+
+            if has_delegation:
+                # Found a delegation tool - stop counting
+                break
+            elif has_non_delegation:
+                # Add to consecutive count (one per message, not per tool call)
+                consecutive_non_delegation += 1
+
+        # Check if threshold exceeded
+        if consecutive_non_delegation >= threshold:
+            return WatcherResult.nudge(
+                guidance=(
+                    f"You've made {consecutive_non_delegation} consecutive direct tool calls "
+                    "without delegating to an executor. Remember: as the orchestrator, your role "
+                    "is to delegate coding work to executors, not do it yourself via bash. "
+                    "Consider whether the work you're doing could be delegated to an executor "
+                    "using delegate(). Executors can write code, run tests, and handle complex "
+                    "file operations more effectively than direct bash commands."
+                ),
+                reason=f"Consecutive non-delegation calls: {consecutive_non_delegation}",
+            )
+
+        return WatcherResult.ok()