chore: tweak quickstart

micro-fix: quickstart build failing

.github/workflows/ci.yml

@@ -62,8 +62,11 @@ jobs:
           uv run pytest tests/ -v
 
   test-tools:
-    name: Test Tools
-    runs-on: ubuntu-latest
+    name: Test Tools (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
     steps:
       - uses: actions/checkout@v4
 

.gitignore

@@ -79,3 +79,4 @@ core/tests/*dumps/*
 
 screenshots/*
 
+.gemini/*

AGENTS.md

@@ -2,6 +2,10 @@
 
 Shared agent instructions for this workspace.
 
+## Deprecations
+
+- **TUI is deprecated.** The terminal UI (`hive tui`) is no longer maintained. Use the browser-based interface (`hive open`) instead.
+
 ## Coding Agent Notes
 
 - 

Makefile

@@ -20,8 +20,20 @@ check: ## Run all checks without modifying files (CI-safe)
 	cd core && ruff format --check .
 	cd tools && ruff format --check .
 
-test: ## Run all tests
+test: ## Run all tests (core + tools, excludes live)
 	cd core && uv run python -m pytest tests/ -v
+	cd tools && uv run python -m pytest -v
+
+test-tools: ## Run tool tests only (mocked, no credentials needed)
+	cd tools && uv run python -m pytest -v
+
+test-live: ## Run live integration tests (requires real API credentials)
+	cd tools && uv run python -m pytest -m live -s -o "addopts=" --log-cli-level=INFO
+
+test-all: ## Run everything including live tests
+	cd core && uv run python -m pytest tests/ -v
+	cd tools && uv run python -m pytest -v
+	cd tools && uv run python -m pytest -m live -s -o "addopts=" --log-cli-level=INFO
 
 install-hooks: ## Install pre-commit hooks
 	uv pip install pre-commit

README.md

@@ -82,6 +82,7 @@ Use Hive when you need:
 
 - Python 3.11+ for agent development
 - An LLM provider that powers the agents
+- **ripgrep (optional, recommended on Windows):** The `search_files` tool uses ripgrep for faster file search. If not installed, a Python fallback is used. On Windows: `winget install BurntSushi.ripgrep` or `scoop install ripgrep`
 
 > **Note for Windows Users:** It is strongly recommended to use **WSL (Windows Subsystem for Linux)** or **Git Bash** to run this framework. Some core automation scripts may not execute correctly in standard Command Prompt or PowerShell.
 
@@ -112,6 +113,8 @@ This sets up:
 
 - At last, it will initiate the open hive interface in your browser
 
+> **Tip:** To reopen the dashboard later, run `hive open` from the project directory.
+
 <img width="2500" height="1214" alt="home-screen" src="https://github.com/user-attachments/assets/134d897f-5e75-4874-b00b-e0505f6b45c4" />
 
 ### Build Your First Agent

commit_message.txt

@@ -0,0 +1,31 @@
+perf: reduce subprocess spawning in quickstart scripts (#4427)
+
+## Problem
+Windows process creation (CreateProcess) is 10-100x slower than Linux fork/exec.
+The quickstart scripts were spawning 4+ separate `uv run python -c "import X"` 
+processes to verify imports, adding ~600ms overhead on Windows.
+
+## Solution
+Consolidated all import checks into a single batch script that checks multiple 
+modules in one subprocess call, reducing spawn overhead by ~75%.
+
+## Changes
+- **New**: `scripts/check_requirements.py` - Batched import checker
+- **New**: `scripts/test_check_requirements.py` - Test suite  
+- **New**: `scripts/benchmark_quickstart.ps1` - Performance benchmark tool
+- **Modified**: `quickstart.ps1` - Updated import verification (2 sections)
+- **Modified**: `quickstart.sh` - Updated import verification
+
+## Performance Impact
+**Benchmark results on Windows:**
+- Before: ~19.8 seconds for import checks
+- After: ~4.9 seconds for import checks
+- **Improvement: 14.9 seconds saved (75.2% faster)**
+
+## Testing
+- ✅ All functional tests pass (`scripts/test_check_requirements.py`)
+- ✅ Quickstart scripts work correctly on Windows
+- ✅ Error handling verified (invalid imports reported correctly)
+- ✅ Performance benchmark confirms 75%+ improvement
+
+Fixes #4427

core/framework/agents/hive_coder/config.py

@@ -10,7 +10,7 @@ def _load_preferred_model() -> str:
     config_path = Path.home() / ".hive" / "configuration.json"
     if config_path.exists():
         try:
-            with open(config_path) as f:
+            with open(config_path, encoding="utf-8") as f:
                 config = json.load(f)
             llm = config.get("llm", {})
             if llm.get("provider") and llm.get("model"):
@@ -24,7 +24,7 @@ def _load_preferred_model() -> str:
 class RuntimeConfig:
     model: str = field(default_factory=_load_preferred_model)
     temperature: float = 0.7
-    max_tokens: int = 40000
+    max_tokens: int = 8000
     api_key: str | None = None
     api_base: str | None = None
 

core/framework/agents/hive_coder/nodes/__init__.py

@@ -7,11 +7,11 @@ from framework.graph import NodeSpec
 # Load reference docs at import time so they're always in the system prompt.
 # No voluntary read_file() calls needed — the LLM gets everything upfront.
 _ref_dir = Path(__file__).parent.parent / "reference"
-_framework_guide = (_ref_dir / "framework_guide.md").read_text()
-_file_templates = (_ref_dir / "file_templates.md").read_text()
-_anti_patterns = (_ref_dir / "anti_patterns.md").read_text()
+_framework_guide = (_ref_dir / "framework_guide.md").read_text(encoding="utf-8")
+_file_templates = (_ref_dir / "file_templates.md").read_text(encoding="utf-8")
+_anti_patterns = (_ref_dir / "anti_patterns.md").read_text(encoding="utf-8")
 _gcu_guide_path = _ref_dir / "gcu_guide.md"
-_gcu_guide = _gcu_guide_path.read_text() if _gcu_guide_path.exists() else ""
+_gcu_guide = _gcu_guide_path.read_text(encoding="utf-8") if _gcu_guide_path.exists() else ""
 
 
 def _is_gcu_enabled() -> bool:
@@ -46,6 +46,7 @@ _SHARED_TOOLS = [
     "read_file",
     "write_file",
     "edit_file",
+    "hashline_edit",
     "list_directory",
     "search_files",
     "run_command",
@@ -55,8 +56,6 @@ _SHARED_TOOLS = [
     "validate_agent_tools",
     "list_agents",
     "list_agent_sessions",
-    "get_agent_session_state",
-    "get_agent_session_memory",
     "list_agent_checkpoints",
     "get_agent_checkpoint",
     "run_agent_tests",
@@ -131,12 +130,23 @@ errors yourself. Don't declare success until validation passes.
 
 # Tools
 
+## Paths (MANDATORY)
+**Always use RELATIVE paths**
+(e.g. `exports/agent_name/config.py`, `exports/agent_name/nodes/__init__.py`).
+**Never use absolute paths** like `/mnt/data/...` or `/workspace/...` — they fail.
+The project root is implicit.
+
 ## File I/O
-- read_file(path, offset?, limit?) — read with line numbers
+- read_file(path, offset?, limit?, hashline?) — read with line numbers; \
+hashline=True for N:hhhh|content anchors (use with hashline_edit)
 - write_file(path, content) — create/overwrite, auto-mkdir
 - edit_file(path, old_text, new_text, replace_all?) — fuzzy-match edit
+- hashline_edit(path, edits, auto_cleanup?, encoding?) — anchor-based \
+editing using N:hhhh refs from read_file(hashline=True). Ops: set_line, \
+replace_lines, insert_after, insert_before, replace, append
 - list_directory(path, recursive?) — list contents
-- search_files(pattern, path?, include?) — regex search
+- search_files(pattern, path?, include?, hashline?) — regex search; \
+hashline=True for anchors in results
 - run_command(command, cwd?, timeout?) — shell execution
 - undo_changes(path?) — restore from git snapshot
 
@@ -149,8 +159,6 @@ available tools grouped by category. output_schema: "simple" (default) or \
 in an agent's nodes actually exist. Call after building.
 - list_agents() — list all agent packages in exports/ with session counts
 - list_agent_sessions(agent_name, status?, limit?) — list sessions
-- get_agent_session_state(agent_name, session_id) — full session state
-- get_agent_session_memory(agent_name, session_id, key?) — memory data
 - list_agent_checkpoints(agent_name, session_id) — list checkpoints
 - get_agent_checkpoint(agent_name, session_id, checkpoint_id?) — load checkpoint
 - run_agent_tests(agent_name, test_types?, fail_fast?) — run pytest with parsing
@@ -185,8 +193,7 @@ After writing agent code, validate structurally AND run tests:
 ## Debugging Built Agents
 When a user says "my agent is failing" or "debug this agent":
 1. list_agent_sessions("{agent_name}") — find the session
-2. get_agent_session_state("{agent_name}", "{session_id}") — see status
-3. get_agent_session_memory("{agent_name}", "{session_id}") — inspect data
+2. get_worker_status
 4. list_agent_checkpoints / get_agent_checkpoint — trace execution
 
 # Agent Building Workflow
@@ -608,7 +615,7 @@ You have full coding tools for building and modifying agents:
 - File I/O: read_file, write_file, edit_file, list_directory, search_files, \
 run_command, undo_changes
 - Meta-agent: list_agent_tools, validate_agent_tools, \
-list_agents, list_agent_sessions, get_agent_session_state, get_agent_session_memory, \
+list_agents, list_agent_sessions, \
 list_agent_checkpoints, get_agent_checkpoint, run_agent_tests
 - load_built_agent(agent_path) — Load the agent and switch to STAGING mode
 - list_credentials(credential_id?) — List authorized credentials

core/framework/builder/workflow.py

@@ -660,7 +660,7 @@ class GraphBuilder:
         # Generate Python code
         code = self._generate_code(graph)
 
-        Path(path).write_text(code)
+        Path(path).write_text(code, encoding="utf-8")
         self.session.phase = BuildPhase.EXPORTED
         self._save_session()
 
@@ -754,7 +754,7 @@ class GraphBuilder:
         """Save session to disk."""
         self.session.updated_at = datetime.now()
         path = self.storage_path / f"{self.session.id}.json"
-        path.write_text(self.session.model_dump_json(indent=2))
+        path.write_text(self.session.model_dump_json(indent=2), encoding="utf-8")
 
     def _load_session(self, session_id: str) -> BuildSession:
         """Load session from disk."""

core/framework/config.py

@@ -92,7 +92,7 @@ def get_api_key() -> str | None:
 
 def get_gcu_enabled() -> bool:
     """Return whether GCU (browser automation) is enabled in user config."""
-    return get_hive_config().get("gcu_enabled", False)
+    return get_hive_config().get("gcu_enabled", True)
 
 
 def get_api_base() -> str | None:

core/framework/credentials/key_storage.py

@@ -69,7 +69,7 @@ def save_credential_key(key: str) -> Path:
     # Restrict the secrets directory itself
     path.parent.chmod(stat.S_IRWXU)  # 0o700
 
-    path.write_text(key)
+    path.write_text(key, encoding="utf-8")
     path.chmod(stat.S_IRUSR | stat.S_IWUSR)  # 0o600
 
     os.environ[CREDENTIAL_KEY_ENV_VAR] = key

core/framework/credentials/oauth2/__init__.py

@@ -73,6 +73,7 @@ from .provider import (
     TokenExpiredError,
     TokenPlacement,
 )
+from .zoho_provider import ZohoOAuth2Provider
 
 __all__ = [
     # Types
@@ -82,6 +83,7 @@ __all__ = [
     # Providers
     "BaseOAuth2Provider",
     "HubSpotOAuth2Provider",
+    "ZohoOAuth2Provider",
     # Lifecycle
     "TokenLifecycleManager",
     "TokenRefreshResult",

core/framework/credentials/oauth2/zoho_provider.py

@@ -0,0 +1,198 @@
+"""
+Zoho CRM-specific OAuth2 provider.
+
+Pre-configured for Zoho's OAuth2 endpoints and CRM scopes.
+Extends BaseOAuth2Provider for Zoho-specific behavior.
+
+Usage:
+    provider = ZohoOAuth2Provider(
+        client_id="your-client-id",
+        client_secret="your-client-secret",
+        accounts_domain="https://accounts.zoho.com",  # or .in, .eu, etc.
+    )
+
+    # Use with credential store
+    store = CredentialStore(
+        storage=EncryptedFileStorage(),
+        providers=[provider],
+    )
+
+See: https://www.zoho.com/crm/developer/docs/api/v2/access-refresh.html
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Any
+
+from ..models import CredentialObject, CredentialRefreshError, CredentialType
+from .base_provider import BaseOAuth2Provider
+from .provider import OAuth2Config, OAuth2Token, TokenPlacement
+
+logger = logging.getLogger(__name__)
+
+# Default CRM scopes for Phase 1 (Leads, Contacts, Accounts, Deals, Notes)
+ZOHO_DEFAULT_SCOPES = [
+    "ZohoCRM.modules.leads.ALL",
+    "ZohoCRM.modules.contacts.ALL",
+    "ZohoCRM.modules.accounts.ALL",
+    "ZohoCRM.modules.deals.ALL",
+    "ZohoCRM.modules.notes.CREATE",
+]
+
+
+class ZohoOAuth2Provider(BaseOAuth2Provider):
+    """
+    Zoho CRM OAuth2 provider with pre-configured endpoints.
+
+    Handles Zoho-specific OAuth2 behavior:
+    - Pre-configured token and authorization URLs (region-aware)
+    - Default CRM scopes for Leads, Contacts, Accounts, Deals, Notes
+    - Token validation via Zoho CRM API
+    - Authorization header format: "Authorization: Zoho-oauthtoken {token}"
+
+    Example:
+        provider = ZohoOAuth2Provider(
+            client_id="your-zoho-client-id",
+            client_secret="your-zoho-client-secret",
+            accounts_domain="https://accounts.zoho.com",  # US
+            # or "https://accounts.zoho.in" for India
+            # or "https://accounts.zoho.eu" for EU
+        )
+    """
+
+    def __init__(
+        self,
+        client_id: str,
+        client_secret: str,
+        accounts_domain: str = "https://accounts.zoho.com",
+        api_domain: str | None = None,
+        scopes: list[str] | None = None,
+    ):
+        """
+        Initialize Zoho OAuth2 provider.
+
+        Args:
+            client_id: Zoho OAuth2 client ID
+            client_secret: Zoho OAuth2 client secret
+            accounts_domain: Zoho accounts domain (region-specific)
+                - US: https://accounts.zoho.com
+                - India: https://accounts.zoho.in
+                - EU: https://accounts.zoho.eu
+                - etc.
+            api_domain: Zoho API domain for CRM calls (used in validate).
+                Defaults to ZOHO_API_DOMAIN env or https://www.zohoapis.com
+            scopes: Override default scopes if needed
+        """
+        base = accounts_domain.rstrip("/")
+        token_url = f"{base}/oauth/v2/token"
+        auth_url = f"{base}/oauth/v2/auth"
+
+        config = OAuth2Config(
+            token_url=token_url,
+            authorization_url=auth_url,
+            client_id=client_id,
+            client_secret=client_secret,
+            default_scopes=scopes or ZOHO_DEFAULT_SCOPES,
+            token_placement=TokenPlacement.HEADER_CUSTOM,
+            custom_header_name="Authorization",
+        )
+        super().__init__(config, provider_id="zoho_crm_oauth2")
+        self._accounts_domain = base
+        self._api_domain = (
+            api_domain or os.getenv("ZOHO_API_DOMAIN", "https://www.zohoapis.com")
+        ).rstrip("/")
+
+    @property
+    def supported_types(self) -> list[CredentialType]:
+        return [CredentialType.OAUTH2]
+
+    def format_for_request(self, token: OAuth2Token) -> dict[str, Any]:
+        """
+        Format token for Zoho CRM API requests.
+
+        Zoho uses Authorization header: "Zoho-oauthtoken {access_token}"
+        (not Bearer).
+        """
+        return {
+            "headers": {
+                "Authorization": f"Zoho-oauthtoken {token.access_token}",
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+            }
+        }
+
+    def validate(self, credential: CredentialObject) -> bool:
+        """
+        Validate Zoho credential by making a lightweight API call.
+
+        Uses GET /crm/v2/users?type=CurrentUser (doesn't require module access).
+        Treats 429 as valid-but-rate-limited.
+        """
+        access_token = credential.get_key("access_token")
+        if not access_token:
+            return False
+
+        try:
+            client = self._get_client()
+            response = client.get(
+                f"{self._api_domain}/crm/v2/users?type=CurrentUser",
+                headers={
+                    "Authorization": f"Zoho-oauthtoken {access_token}",
+                    "Accept": "application/json",
+                },
+                timeout=self.config.request_timeout,
+            )
+            return response.status_code in (200, 429)
+        except Exception as e:
+            logger.debug("Zoho credential validation failed: %s", e)
+            return False
+
+    def _parse_token_response(self, response_data: dict[str, Any]) -> OAuth2Token:
+        """
+        Parse Zoho token response.
+
+        Zoho returns:
+        {
+            "access_token": "...",
+            "refresh_token": "...",
+            "expires_in": 3600,
+            "api_domain": "https://www.zohoapis.com",
+            "token_type": "Bearer"
+        }
+        """
+        token = OAuth2Token.from_token_response(response_data)
+        if "api_domain" in response_data:
+            token.raw_response["api_domain"] = response_data["api_domain"]
+        return token
+
+    def refresh(self, credential: CredentialObject) -> CredentialObject:
+        """Refresh Zoho OAuth2 credential and persist DC metadata."""
+        refresh_tok = credential.get_key("refresh_token")
+        if not refresh_tok:
+            raise CredentialRefreshError(f"Credential '{credential.id}' has no refresh_token")
+
+        try:
+            new_token = self.refresh_access_token(refresh_tok)
+        except Exception as e:
+            raise CredentialRefreshError(f"Failed to refresh '{credential.id}': {e}") from e
+
+        credential.set_key("access_token", new_token.access_token, expires_at=new_token.expires_at)
+
+        if new_token.refresh_token and new_token.refresh_token != refresh_tok:
+            credential.set_key("refresh_token", new_token.refresh_token)
+
+        api_domain = new_token.raw_response.get("api_domain")
+        if isinstance(api_domain, str) and api_domain:
+            credential.set_key("api_domain", api_domain.rstrip("/"))
+
+        accounts_server = new_token.raw_response.get("accounts-server")
+        if isinstance(accounts_server, str) and accounts_server:
+            credential.set_key("accounts_domain", accounts_server.rstrip("/"))
+
+        location = new_token.raw_response.get("location")
+        if isinstance(location, str) and location:
+            credential.set_key("location", location.strip().lower())
+
+        return credential

core/framework/credentials/setup.py

@@ -568,7 +568,7 @@ def _load_nodes_from_python_agent(agent_path: Path) -> list:
 def _load_nodes_from_json_agent(agent_json: Path) -> list:
     """Load nodes from a JSON-based agent."""
     try:
-        with open(agent_json) as f:
+        with open(agent_json, encoding="utf-8") as f:
             data = json.load(f)
 
         from framework.graph import NodeSpec

core/framework/credentials/storage.py

@@ -227,7 +227,7 @@ class EncryptedFileStorage(CredentialStorage):
         index_path = self.base_path / "metadata" / "index.json"
         if not index_path.exists():
             return []
-        with open(index_path) as f:
+        with open(index_path, encoding="utf-8") as f:
             index = json.load(f)
         return list(index.get("credentials", {}).keys())
 
@@ -268,7 +268,7 @@ class EncryptedFileStorage(CredentialStorage):
         index_path = self.base_path / "metadata" / "index.json"
 
         if index_path.exists():
-            with open(index_path) as f:
+            with open(index_path, encoding="utf-8") as f:
                 index = json.load(f)
         else:
             index = {"credentials": {}, "version": "1.0"}
@@ -283,7 +283,7 @@ class EncryptedFileStorage(CredentialStorage):
 
         index["last_modified"] = datetime.now(UTC).isoformat()
 
-        with open(index_path, "w") as f:
+        with open(index_path, "w", encoding="utf-8") as f:
             json.dump(index, f, indent=2)
 
 

core/framework/graph/edge.py

@@ -431,8 +431,7 @@ class GraphSpec(BaseModel):
     max_tokens: int = Field(default=None)  # resolved by _resolve_max_tokens validator
 
     # Cleanup LLM for JSON extraction fallback (fast/cheap model preferred)
-    # If not set, uses CEREBRAS_API_KEY -> cerebras/llama-3.3-70b or
-    # ANTHROPIC_API_KEY -> claude-haiku-4-5 as fallback
+    # If not set, uses CEREBRAS_API_KEY -> cerebras/llama-3.3-70b
     cleanup_llm_model: str | None = None
 
     # Execution limits

core/framework/graph/event_loop_node.py

@@ -4058,329 +4058,3 @@ class EventLoopNode(NodeProtocol):
                 content=json.dumps(result_json, indent=2),
                 is_error=True,
             )
-
-    # -------------------------------------------------------------------
-    # Subagent Execution
-    # -------------------------------------------------------------------
-
-    async def _execute_subagent(
-        self,
-        ctx: NodeContext,
-        agent_id: str,
-        task: str,
-        *,
-        accumulator: OutputAccumulator | None = None,
-    ) -> ToolResult:
-        """Execute a subagent and return the result as a ToolResult.
-
-        The subagent:
-        - Gets a fresh conversation with just the task
-        - Has read-only access to the parent's readable memory
-        - Cannot delegate to its own subagents (prevents recursion)
-        - Returns its output in structured JSON format
-
-        Args:
-            ctx: Parent node's context (for memory, tools, LLM access).
-            agent_id: The node ID of the subagent to invoke.
-            task: The task description to give the subagent.
-            accumulator: Parent's OutputAccumulator — provides outputs that
-                have been set via ``set_output`` but not yet written to
-                shared memory (which only happens after the node completes).
-
-        Returns:
-            ToolResult with structured JSON output containing:
-            - message: Human-readable summary
-            - data: Subagent's output (free-form JSON)
-            - metadata: Execution metadata (success, tokens, latency)
-        """
-        from framework.graph.node import NodeContext, SharedMemory
-
-        # Log subagent invocation start
-        logger.info(
-            "\n" + "=" * 60 + "\n"
-            "🤖 SUBAGENT INVOCATION\n"
-            "=" * 60 + "\n"
-            "Parent Node: %s\n"
-            "Subagent ID: %s\n"
-            "Task: %s\n" + "=" * 60,
-            ctx.node_id,
-            agent_id,
-            task[:500] + "..." if len(task) > 500 else task,
-        )
-
-        # 1. Validate agent exists in registry
-        if agent_id not in ctx.node_registry:
-            return ToolResult(
-                tool_use_id="",
-                content=json.dumps(
-                    {
-                        "message": f"Sub-agent '{agent_id}' not found in registry",
-                        "data": None,
-                        "metadata": {"agent_id": agent_id, "success": False, "error": "not_found"},
-                    }
-                ),
-                is_error=True,
-            )
-
-        subagent_spec = ctx.node_registry[agent_id]
-
-        # 2. Create read-only memory snapshot
-        # Start with everything the parent can read from shared memory.
-        parent_data = ctx.memory.read_all()
-
-        # Merge in-flight outputs from the parent's accumulator.
-        # set_output() writes to the accumulator but shared memory is only
-        # updated after the parent node completes — so the subagent would
-        # otherwise miss any keys the parent set before delegating.
-        if accumulator:
-            for key, value in accumulator.to_dict().items():
-                if key not in parent_data:
-                    parent_data[key] = value
-
-        subagent_memory = SharedMemory()
-        for key, value in parent_data.items():
-            subagent_memory.write(key, value, validate=False)
-
-        # Allow reads for parent data AND the subagent's declared input_keys
-        # (input_keys may reference keys that exist but weren't in read_all,
-        # or keys that were just written by the accumulator).
-        read_keys = set(parent_data.keys()) | set(subagent_spec.input_keys or [])
-        scoped_memory = subagent_memory.with_permissions(
-            read_keys=list(read_keys),
-            write_keys=[],  # Read-only!
-        )
-
-        # 2b. Set up report callback (one-way channel to parent / event bus)
-        subagent_reports: list[dict] = []
-
-        async def _report_callback(
-            message: str,
-            data: dict | None = None,
-            *,
-            wait_for_response: bool = False,
-        ) -> str | None:
-            subagent_reports.append({"message": message, "data": data, "timestamp": time.time()})
-            if self._event_bus:
-                await self._event_bus.emit_subagent_report(
-                    stream_id=ctx.node_id,
-                    node_id=f"{ctx.node_id}:subagent:{agent_id}",
-                    subagent_id=agent_id,
-                    message=message,
-                    data=data,
-                    execution_id=ctx.execution_id,
-                )
-
-            if not wait_for_response:
-                return None
-
-            if not self._event_bus:
-                logger.warning(
-                    "Subagent '%s' requested user response but no event_bus available",
-                    agent_id,
-                )
-                return None
-
-            # Create isolated receiver and register for input routing
-            import uuid
-
-            escalation_id = f"{ctx.node_id}:escalation:{uuid.uuid4().hex[:8]}"
-            receiver = _EscalationReceiver()
-            registry = ctx.shared_node_registry
-
-            registry[escalation_id] = receiver
-            try:
-                # Stream message to user (parent's node_id so TUI shows parent talking)
-                await self._event_bus.emit_client_output_delta(
-                    stream_id=ctx.node_id,
-                    node_id=ctx.node_id,
-                    content=message,
-                    snapshot=message,
-                    execution_id=ctx.execution_id,
-                )
-                # Request input (escalation_id for routing response back)
-                await self._event_bus.emit_client_input_requested(
-                    stream_id=ctx.node_id,
-                    node_id=escalation_id,
-                    prompt=message,
-                    execution_id=ctx.execution_id,
-                )
-                # Block until user responds
-                return await receiver.wait()
-            finally:
-                registry.pop(escalation_id, None)
-
-        # 3. Filter tools for subagent
-        # Use the full tool catalog (ctx.all_tools) so subagents can access tools
-        # that aren't in the parent node's filtered set (e.g. browser tools for a
-        # GCU subagent when the parent only has web_scrape/save_data).
-        # Falls back to ctx.available_tools if all_tools is empty (e.g. in tests).
-        subagent_tool_names = set(subagent_spec.tools or [])
-        tool_source = ctx.all_tools if ctx.all_tools else ctx.available_tools
-
-        subagent_tools = [
-            t
-            for t in tool_source
-            if t.name in subagent_tool_names and t.name != "delegate_to_sub_agent"
-        ]
-
-        missing = subagent_tool_names - {t.name for t in subagent_tools}
-        if missing:
-            logger.warning(
-                "Subagent '%s' requested tools not found in catalog: %s",
-                agent_id,
-                sorted(missing),
-            )
-
-        logger.info(
-            "📦 Subagent '%s' configuration:\n"
-            "   - System prompt: %s\n"
-            "   - Tools available (%d): %s\n"
-            "   - Memory keys inherited: %s",
-            agent_id,
-            (subagent_spec.system_prompt[:200] + "...")
-            if subagent_spec.system_prompt and len(subagent_spec.system_prompt) > 200
-            else subagent_spec.system_prompt,
-            len(subagent_tools),
-            [t.name for t in subagent_tools],
-            list(parent_data.keys()),
-        )
-
-        # 4. Build subagent context
-        max_iter = min(self._config.max_iterations, 10)
-        subagent_ctx = NodeContext(
-            runtime=ctx.runtime,
-            node_id=f"{ctx.node_id}:subagent:{agent_id}",
-            node_spec=subagent_spec,
-            memory=scoped_memory,
-            input_data={"task": task, **parent_data},
-            llm=ctx.llm,
-            available_tools=subagent_tools,
-            goal_context=(
-                f"Your specific task: {task}\n\n"
-                f"COMPLETION REQUIREMENTS:\n"
-                f"When your task is done, you MUST call set_output() "
-                f"for each required key: {subagent_spec.output_keys}\n"
-                f"Alternatively, call report_to_parent(mark_complete=true) "
-                f"with your findings in message/data.\n"
-                f"You have a maximum of {max_iter} turns to complete this task."
-            ),
-            goal=ctx.goal,
-            max_tokens=ctx.max_tokens,
-            runtime_logger=ctx.runtime_logger,
-            is_subagent_mode=True,  # Prevents nested delegation
-            report_callback=_report_callback,
-            node_registry={},  # Empty - no nested subagents
-            shared_node_registry=ctx.shared_node_registry,  # For escalation routing
-        )
-
-        # 5. Create and execute subagent EventLoopNode
-        # Derive a conversation store for the subagent from the parent's store.
-        # Each invocation gets a unique path so that repeated delegate calls
-        # (e.g. one per profile) don't restore a stale completed conversation.
-        self._subagent_instance_counter.setdefault(agent_id, 0)
-        self._subagent_instance_counter[agent_id] += 1
-        subagent_instance = str(self._subagent_instance_counter[agent_id])
-
-        subagent_conv_store = None
-        if self._conversation_store is not None:
-            from framework.storage.conversation_store import FileConversationStore
-
-            parent_base = getattr(self._conversation_store, "_base", None)
-            if parent_base is not None:
-                # Store subagent conversations parallel to the parent node,
-                # not nested inside it.  e.g. conversations/{node}:subagent:{agent_id}:{instance}/
-                conversations_dir = parent_base.parent  # e.g. conversations/
-                subagent_dir_name = f"{agent_id}-{subagent_instance}"
-                subagent_store_path = conversations_dir / subagent_dir_name
-                subagent_conv_store = FileConversationStore(base_path=subagent_store_path)
-
-        # Derive a subagent-scoped spillover dir so large tool results
-        # (e.g. browser_snapshot) get written to disk instead of being
-        # silently truncated.  Each instance gets its own directory to
-        # avoid file collisions between concurrent subagents.
-        subagent_spillover = None
-        if self._config.spillover_dir:
-            subagent_spillover = str(
-                Path(self._config.spillover_dir) / agent_id / subagent_instance
-            )
-
-        subagent_node = EventLoopNode(
-            event_bus=None,  # Subagents don't emit events to parent's bus
-            judge=SubagentJudge(task=task, max_iterations=max_iter),
-            config=LoopConfig(
-                max_iterations=max_iter,  # Tighter budget
-                max_tool_calls_per_turn=self._config.max_tool_calls_per_turn,
-                tool_call_overflow_margin=self._config.tool_call_overflow_margin,
-                max_history_tokens=self._config.max_history_tokens,
-                stall_detection_threshold=self._config.stall_detection_threshold,
-                max_tool_result_chars=self._config.max_tool_result_chars,
-                spillover_dir=subagent_spillover,
-            ),
-            tool_executor=self._tool_executor,
-            conversation_store=subagent_conv_store,
-        )
-
-        try:
-            logger.info("🚀 Starting subagent '%s' execution...", agent_id)
-            start_time = time.time()
-            result = await subagent_node.execute(subagent_ctx)
-            latency_ms = int((time.time() - start_time) * 1000)
-
-            logger.info(
-                "\n" + "-" * 60 + "\n"
-                "✅ SUBAGENT '%s' COMPLETED\n"
-                "-" * 60 + "\n"
-                "Success: %s\n"
-                "Latency: %dms\n"
-                "Tokens used: %s\n"
-                "Output keys: %s\n" + "-" * 60,
-                agent_id,
-                result.success,
-                latency_ms,
-                result.tokens_used,
-                list(result.output.keys()) if result.output else [],
-            )
-
-            result_json = {
-                "message": (
-                    f"Sub-agent '{agent_id}' completed successfully"
-                    if result.success
-                    else f"Sub-agent '{agent_id}' failed: {result.error}"
-                ),
-                "data": result.output,
-                "reports": subagent_reports if subagent_reports else None,
-                "metadata": {
-                    "agent_id": agent_id,
-                    "success": result.success,
-                    "tokens_used": result.tokens_used,
-                    "latency_ms": latency_ms,
-                    "report_count": len(subagent_reports),
-                },
-            }
-
-            return ToolResult(
-                tool_use_id="",
-                content=json.dumps(result_json, indent=2, default=str),
-                is_error=not result.success,
-            )
-
-        except Exception as e:
-            logger.exception(
-                "\n" + "!" * 60 + "\n❌ SUBAGENT '%s' FAILED\nError: %s\n" + "!" * 60,
-                agent_id,
-                str(e),
-            )
-            result_json = {
-                "message": f"Sub-agent '{agent_id}' raised exception: {e}",
-                "data": None,
-                "metadata": {
-                    "agent_id": agent_id,
-                    "success": False,
-                    "error": str(e),
-                },
-            }
-            return ToolResult(
-                tool_use_id="",
-                content=json.dumps(result_json, indent=2),
-                is_error=True,
-            )

core/framework/graph/executor.py

@@ -183,11 +183,12 @@ class GraphExecutor:
         self.tool_provider_map = tool_provider_map
         self.dynamic_tools_provider = dynamic_tools_provider
 
-        # Initialize output cleaner
+        # Initialize output cleaner — uses its own dedicated fast model (CEREBRAS_API_KEY),
+        # never the main agent LLM. Passing the main LLM here would cause expensive
+        # Anthropic calls for output cleaning whenever ANTHROPIC_API_KEY is set.
         self.cleansing_config = cleansing_config or CleansingConfig()
         self.output_cleaner = OutputCleaner(
             config=self.cleansing_config,
-            llm_provider=llm,
         )
 
         # Parallel execution settings
@@ -620,11 +621,14 @@ class GraphExecutor:
         # node doesn't restore a filled OutputAccumulator from the previous
         # webhook run (which would cause the judge to accept immediately).
         # The conversation history is preserved (continuous memory).
+        # Exclude cold restores — those need to continue the conversation
+        # naturally without a "start fresh" marker.
         _is_fresh_shared = bool(
             session_state
             and session_state.get("resume_session_id")
             and not session_state.get("paused_at")
             and not session_state.get("resume_from_checkpoint")
+            and not session_state.get("cold_restore")
         )
         if _is_fresh_shared and is_continuous and self._storage_path:
             try:

core/framework/graph/hitl.py

@@ -154,71 +154,19 @@ class HITLProtocol:
         """
         Parse human's raw input into structured response.
 
-        Uses Haiku to intelligently extract answers for each question.
+        Maps the raw input to the first question. For multi-question HITL,
+        the caller should present one question at a time.
         """
-        import os
-
         response = HITLResponse(request_id=request.request_id, raw_input=raw_input)
 
         # If no questions, just return raw input
         if not request.questions:
             return response
 
-        # Try to use Haiku for intelligent parsing
-        api_key = os.environ.get("ANTHROPIC_API_KEY")
-        if not use_haiku or not api_key:
-            # Simple fallback: treat as answer to first question
-            if request.questions:
+        # Map raw input to first question
         response.answers[request.questions[0].id] = raw_input
         return response
 
-        # Use Haiku to extract answers
-        try:
-            import json
-
-            import anthropic
-
-            questions_str = "\n".join(
-                [f"{i + 1}. {q.question} (id: {q.id})" for i, q in enumerate(request.questions)]
-            )
-
-            prompt = f"""Parse the user's response and extract answers for each question.
-
-Questions asked:
-{questions_str}
-
-User's response:
-{raw_input}
-
-Extract the answer for each question. Output JSON with question IDs as keys.
-
-Example format:
-{{"question-1": "answer here", "question-2": "answer here"}}"""
-
-            client = anthropic.Anthropic(api_key=api_key)
-            message = client.messages.create(
-                model="claude-haiku-4-5-20251001",
-                max_tokens=500,
-                messages=[{"role": "user", "content": prompt}],
-            )
-
-            # Parse Haiku's response
-            import re
-
-            response_text = message.content[0].text.strip()
-            json_match = re.search(r"\{[^{}]*\}", response_text, re.DOTALL)
-
-            if json_match:
-                parsed = json.loads(json_match.group())
-                response.answers = parsed
-
-        except Exception:
-            # Fallback: use raw input for first question
-            if request.questions:
-                response.answers[request.questions[0].id] = raw_input
-
-        return response
-
     @staticmethod
     def format_for_display(request: HITLRequest) -> str:
         """Format HITL request for user-friendly display."""

core/framework/graph/node.py

@@ -585,7 +585,6 @@ class NodeResult:
         Generate a human-readable summary of this node's execution and output.
 
         This is like toString() - it describes what the node produced in its current state.
-        Uses Haiku to intelligently summarize complex outputs.
         """
         if not self.success:
             return f"❌ Failed: {self.error}"
@@ -593,13 +592,6 @@ class NodeResult:
         if not self.output:
             return "✓ Completed (no output)"
 
-        # Use Haiku to generate intelligent summary
-        import os
-
-        api_key = os.environ.get("ANTHROPIC_API_KEY")
-
-        if not api_key:
-            # Fallback: simple key-value listing
         parts = [f"✓ Completed with {len(self.output)} outputs:"]
         for key, value in list(self.output.items())[:5]:  # Limit to 5 keys
             value_str = str(value)[:100]
@@ -608,45 +600,6 @@ class NodeResult:
             parts.append(f"  • {key}: {value_str}")
         return "\n".join(parts)
 
-        # Use Haiku to generate intelligent summary
-        try:
-            import json
-
-            import anthropic
-
-            node_context = ""
-            if node_spec:
-                node_context = f"\nNode: {node_spec.name}\nPurpose: {node_spec.description}"
-
-            output_json = json.dumps(self.output, indent=2, default=str)[:2000]
-            prompt = (
-                f"Generate a 1-2 sentence human-readable summary of "
-                f"what this node produced.{node_context}\n\n"
-                f"Node output:\n{output_json}\n\n"
-                "Provide a concise, clear summary that a human can quickly "
-                "understand. Focus on the key information produced."
-            )
-
-            client = anthropic.Anthropic(api_key=api_key)
-            message = client.messages.create(
-                model="claude-haiku-4-5-20251001",
-                max_tokens=200,
-                messages=[{"role": "user", "content": prompt}],
-            )
-
-            summary = message.content[0].text.strip()
-            return f"✓ {summary}"
-
-        except Exception:
-            # Fallback on error
-            parts = [f"✓ Completed with {len(self.output)} outputs:"]
-            for key, value in list(self.output.items())[:3]:
-                value_str = str(value)[:80]
-                if len(str(value)) > 80:
-                    value_str += "..."
-                parts.append(f"  • {key}: {value_str}")
-            return "\n".join(parts)
-
 
 class NodeProtocol(ABC):
     """

core/framework/llm/litellm.py

@@ -170,7 +170,7 @@ def _dump_failed_request(
         "temperature": kwargs.get("temperature"),
     }
 
-    with open(filepath, "w") as f:
+    with open(filepath, "w", encoding="utf-8") as f:
         json.dump(dump_data, f, indent=2, default=str)
 
     return str(filepath)

core/framework/mcp/agent_builder_server.py

@@ -162,7 +162,7 @@ def _load_session(session_id: str) -> BuildSession:
     if not session_file.exists():
         raise ValueError(f"Session '{session_id}' not found")
 
-    with open(session_file) as f:
+    with open(session_file, encoding="utf-8") as f:
         data = json.load(f)
 
     return BuildSession.from_dict(data)
@@ -174,7 +174,7 @@ def _load_active_session() -> BuildSession | None:
         return None
 
     try:
-        with open(ACTIVE_SESSION_FILE) as f:
+        with open(ACTIVE_SESSION_FILE, encoding="utf-8") as f:
             session_id = f.read().strip()
 
         if session_id:
@@ -228,7 +228,7 @@ def list_sessions() -> str:
     if SESSIONS_DIR.exists():
         for session_file in SESSIONS_DIR.glob("*.json"):
             try:
-                with open(session_file) as f:
+                with open(session_file, encoding="utf-8") as f:
                     data = json.load(f)
                     sessions.append(
                         {
@@ -248,7 +248,7 @@ def list_sessions() -> str:
     active_id = None
     if ACTIVE_SESSION_FILE.exists():
         try:
-            with open(ACTIVE_SESSION_FILE) as f:
+            with open(ACTIVE_SESSION_FILE, encoding="utf-8") as f:
                 active_id = f.read().strip()
         except Exception:
             pass
@@ -310,7 +310,7 @@ def delete_session(session_id: Annotated[str, "ID of the session to delete"]) ->
             _session = None
 
         if ACTIVE_SESSION_FILE.exists():
-            with open(ACTIVE_SESSION_FILE) as f:
+            with open(ACTIVE_SESSION_FILE, encoding="utf-8") as f:
                 active_id = f.read().strip()
                 if active_id == session_id:
                     ACTIVE_SESSION_FILE.unlink()
@@ -2894,10 +2894,12 @@ def run_tests(
     try:
         result = subprocess.run(
             cmd,
+            encoding="utf-8",
             capture_output=True,
             text=True,
             timeout=600,  # 10 minute timeout
             env=env,
+            stdin=subprocess.DEVNULL,
         )
     except subprocess.TimeoutExpired:
         return json.dumps(
@@ -3085,10 +3087,12 @@ def debug_test(
     try:
         result = subprocess.run(
             cmd,
+            encoding="utf-8",
             capture_output=True,
             text=True,
             timeout=120,  # 2 minute timeout for single test
             env=env,
+            stdin=subprocess.DEVNULL,
         )
     except subprocess.TimeoutExpired:
         return json.dumps(
@@ -3712,82 +3716,6 @@ def list_agent_sessions(
     )
 
 
-@mcp.tool()
-def get_agent_session_state(
-    agent_work_dir: Annotated[str, "Path to the agent's working directory"],
-    session_id: Annotated[str, "The session ID (e.g., 'session_20260208_143022_abc12345')"],
-) -> str:
-    """
-    Load full session state for a specific session.
-
-    Returns complete session data including status, progress, result,
-    metrics, and checkpoint info. Memory values are excluded to prevent
-    context bloat -- use get_agent_session_memory to retrieve memory contents.
-    """
-    state_path = Path(agent_work_dir) / "sessions" / session_id / "state.json"
-    data = _read_session_json(state_path)
-    if data is None:
-        return json.dumps({"error": f"Session not found: {session_id}"})
-
-    memory = data.get("memory", {})
-    data["memory_keys"] = list(memory.keys()) if isinstance(memory, dict) else []
-    data["memory_size"] = len(memory) if isinstance(memory, dict) else 0
-    data.pop("memory", None)
-
-    return json.dumps(data, indent=2, default=str)
-
-
-@mcp.tool()
-def get_agent_session_memory(
-    agent_work_dir: Annotated[str, "Path to the agent's working directory"],
-    session_id: Annotated[str, "The session ID"],
-    key: Annotated[str, "Specific memory key to retrieve. Empty for all."] = "",
-) -> str:
-    """
-    Get memory contents from a session.
-
-    Memory stores intermediate results passed between nodes. Use this
-    to inspect what data was produced during execution.
-
-    If key is provided, returns only that memory key's value.
-    If key is empty, returns all memory keys and their values.
-    """
-    state_path = Path(agent_work_dir) / "sessions" / session_id / "state.json"
-    data = _read_session_json(state_path)
-    if data is None:
-        return json.dumps({"error": f"Session not found: {session_id}"})
-
-    memory = data.get("memory", {})
-    if not isinstance(memory, dict):
-        memory = {}
-
-    if key:
-        if key not in memory:
-            return json.dumps(
-                {
-                    "error": f"Memory key not found: '{key}'",
-                    "available_keys": list(memory.keys()),
-                }
-            )
-        value = memory[key]
-        return json.dumps(
-            {
-                "session_id": session_id,
-                "key": key,
-                "value": value,
-                "value_type": type(value).__name__,
-            },
-            indent=2,
-            default=str,
-        )
-
-    return json.dumps(
-        {"session_id": session_id, "memory": memory, "total_keys": len(memory)},
-        indent=2,
-        default=str,
-    )
-
-
 @mcp.tool()
 def list_agent_checkpoints(
     agent_work_dir: Annotated[str, "Path to the agent's working directory"],

core/framework/runner/cli.py

@@ -401,6 +401,43 @@ def register_commands(subparsers: argparse._SubParsersAction) -> None:
     )
     serve_parser.set_defaults(func=cmd_serve)
 
+    # open command (serve + auto-open browser)
+    open_parser = subparsers.add_parser(
+        "open",
+        help="Start HTTP server and open dashboard in browser",
+        description="Shortcut for 'hive serve --open'. "
+        "Starts the HTTP server and opens the dashboard.",
+    )
+    open_parser.add_argument(
+        "--host",
+        type=str,
+        default="127.0.0.1",
+        help="Host to bind (default: 127.0.0.1)",
+    )
+    open_parser.add_argument(
+        "--port",
+        "-p",
+        type=int,
+        default=8787,
+        help="Port to listen on (default: 8787)",
+    )
+    open_parser.add_argument(
+        "--agent",
+        "-a",
+        type=str,
+        action="append",
+        default=[],
+        help="Agent path to preload (repeatable)",
+    )
+    open_parser.add_argument(
+        "--model",
+        "-m",
+        type=str,
+        default=None,
+        help="LLM model for preloaded agents",
+    )
+    open_parser.set_defaults(func=cmd_open)
+
 
 def _load_resume_state(
     agent_path: str, session_id: str, checkpoint_id: str | None = None
@@ -517,7 +554,7 @@ def cmd_run(args: argparse.Namespace) -> int:
             return 1
     elif args.input_file:
         try:
-            with open(args.input_file) as f:
+            with open(args.input_file, encoding="utf-8") as f:
                 context = json.load(f)
         except (FileNotFoundError, json.JSONDecodeError) as e:
             print(f"Error reading input file: {e}", file=sys.stderr)
@@ -659,7 +696,7 @@ def cmd_run(args: argparse.Namespace) -> int:
 
     # Output results
     if args.output:
-        with open(args.output, "w") as f:
+        with open(args.output, "w", encoding="utf-8") as f:
             json.dump(output, f, indent=2, default=str)
         if not args.quiet:
             print(f"Results written to {args.output}")
@@ -1053,62 +1090,19 @@ def _interactive_approval(request):
 def _format_natural_language_to_json(
     user_input: str, input_keys: list[str], agent_description: str, session_context: dict = None
 ) -> dict:
-    """Use Haiku to convert natural language input to JSON based on agent's input schema."""
-    import os
+    """Convert natural language input to JSON based on agent's input schema.
 
-    import anthropic
-
-    client = anthropic.Anthropic(api_key=os.environ.get("ANTHROPIC_API_KEY"))
-
-    # Build prompt for Haiku
-    session_info = ""
-    if session_context:
-        # Extract the main field (usually 'objective') that we'll append to
+    Maps user input to the primary input field. For follow-up inputs,
+    appends to the existing value.
+    """
     main_field = input_keys[0] if input_keys else "objective"
+
+    if session_context:
         existing_value = session_context.get(main_field, "")
+        if existing_value:
+            return {main_field: f"{existing_value}\n\n{user_input}"}
 
-        session_info = (
-            f'\n\nExisting {main_field}: "{existing_value}"\n\n'
-            f"The user is providing ADDITIONAL information. Append this new "
-            f"information to the existing {main_field} to create an enriched, "
-            "more detailed version."
-        )
-
-    prompt = f"""You are formatting user input for an agent that requires specific input fields.
-
-Agent: {agent_description}
-
-Required input fields: {", ".join(input_keys)}{session_info}
-
-User input: {user_input}
-
-{"If this is a follow-up, APPEND new info to the existing field value." if session_context else ""}
-
-Output ONLY valid JSON, no explanation:"""
-
-    try:
-        message = client.messages.create(
-            model="claude-haiku-4-5-20251001",  # Fast and cheap
-            max_tokens=500,
-            messages=[{"role": "user", "content": prompt}],
-        )
-
-        json_str = message.content[0].text.strip()
-        # Remove markdown code blocks if present
-        if json_str.startswith("```"):
-            json_str = json_str.split("```")[1]
-            if json_str.startswith("json"):
-                json_str = json_str[4:]
-        json_str = json_str.strip()
-
-        return json.loads(json_str)
-    except Exception:
-        # Fallback: try to infer the main field
-        if len(input_keys) == 1:
-            return {input_keys[0]: user_input}
-        else:
-            # Put it in the first field as fallback
-            return {input_keys[0]: user_input}
+    return {main_field: user_input}
 
 
 def cmd_shell(args: argparse.Namespace) -> int:
@@ -1517,7 +1511,7 @@ def _extract_python_agent_metadata(agent_path: Path) -> tuple[str, str]:
         return fallback_name, fallback_desc
 
     try:
-        with open(config_path) as f:
+        with open(config_path, encoding="utf-8") as f:
             tree = ast.parse(f.read())
 
         # Find AgentMetadata class definition
@@ -1928,14 +1922,27 @@ def cmd_setup_credentials(args: argparse.Namespace) -> int:
 def _open_browser(url: str) -> None:
     """Open URL in the default browser (best-effort, non-blocking)."""
     import subprocess
-    import sys
 
     try:
         if sys.platform == "darwin":
-            subprocess.Popen(["open", url], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+            subprocess.Popen(
+                ["open", url],
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+                encoding="utf-8",
+            )
+        elif sys.platform == "win32":
+            subprocess.Popen(
+                ["cmd", "/c", "start", "", url],
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+            )
         elif sys.platform == "linux":
             subprocess.Popen(
-                ["xdg-open", url], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL
+                ["xdg-open", url],
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+                encoding="utf-8",
             )
     except Exception:
         pass  # Best-effort — don't crash if browser can't open
@@ -1980,12 +1987,14 @@ def _build_frontend() -> bool:
         # Ensure deps are installed
         subprocess.run(
             ["npm", "install", "--no-fund", "--no-audit"],
+            encoding="utf-8",
             cwd=frontend_dir,
             check=True,
             capture_output=True,
         )
         subprocess.run(
             ["npm", "run", "build"],
+            encoding="utf-8",
             cwd=frontend_dir,
             check=True,
             capture_output=True,
@@ -2074,3 +2083,9 @@ def cmd_serve(args: argparse.Namespace) -> int:
         print("\nServer stopped.")
 
     return 0
+
+
+def cmd_open(args: argparse.Namespace) -> int:
+    """Start the HTTP API server and open the dashboard in the browser."""
+    args.open = True
+    return cmd_serve(args)

core/framework/runner/mcp_client.py

@@ -7,6 +7,8 @@ Supports both STDIO and HTTP transports using the official MCP Python SDK.
 import asyncio
 import logging
 import os
+import sys
+import threading
 from dataclasses import dataclass, field
 from typing import Any, Literal
 
@@ -73,6 +75,8 @@ class MCPClient:
         # Background event loop for persistent STDIO connection
         self._loop = None
         self._loop_thread = None
+        # Serialize STDIO tool calls (avoids races, helps on Windows)
+        self._stdio_call_lock = threading.Lock()
 
     def _run_async(self, coro):
         """
@@ -156,11 +160,19 @@ class MCPClient:
             # Create server parameters
             # Always inherit parent environment and merge with any custom env vars
             merged_env = {**os.environ, **(self.config.env or {})}
+            # On Windows, passing cwd can cause WinError 267 ("invalid directory name").
+            # tool_registry passes cwd=None and uses absolute script paths when applicable.
+            cwd = self.config.cwd
+            if os.name == "nt" and cwd is not None:
+                # Avoid passing cwd on Windows; tool_registry should have set cwd=None
+                # and absolute script paths for tools-dir servers. If cwd is still set,
+                # pass None to prevent WinError 267 (caller should use absolute paths).
+                cwd = None
             server_params = StdioServerParameters(
                 command=self.config.command,
                 args=self.config.args,
                 env=merged_env,
-                cwd=self.config.cwd,
+                cwd=cwd,
             )
 
             # Store for later use
@@ -184,10 +196,12 @@ class MCPClient:
                         from mcp.client.stdio import stdio_client
 
                         # Create persistent stdio client context.
-                        # Redirect server stderr to devnull to prevent raw
-                        # output from leaking behind the TUI.
-                        devnull = open(os.devnull, "w")  # noqa: SIM115
-                        self._stdio_context = stdio_client(server_params, errlog=devnull)
+                        # On Windows, use stderr so subprocess startup errors are visible.
+                        if os.name == "nt":
+                            errlog = sys.stderr
+                        else:
+                            errlog = open(os.devnull, "w")  # noqa: SIM115
+                        self._stdio_context = stdio_client(server_params, errlog=errlog)
                         (
                             self._read_stream,
                             self._write_stream,
@@ -353,6 +367,7 @@ class MCPClient:
             raise ValueError(f"Unknown tool: {tool_name}")
 
         if self.config.transport == "stdio":
+            with self._stdio_call_lock:
                 return self._run_async(self._call_tool_stdio_async(tool_name, arguments))
         else:
             return self._call_tool_http(tool_name, arguments)
@@ -448,10 +463,14 @@ class MCPClient:
             if self._stdio_context:
                 await self._stdio_context.__aexit__(None, None, None)
         except asyncio.CancelledError:
-            logger.warning(
+            logger.debug(
                 "STDIO context cleanup was cancelled; proceeding with best-effort shutdown"
             )
         except Exception as e:
+            msg = str(e).lower()
+            if "cancel scope" in msg or "different task" in msg:
+                logger.debug("STDIO context teardown (known anyio quirk): %s", e)
+            else:
                 logger.warning(f"Error closing STDIO context: {e}")
         finally:
             self._stdio_context = None

core/framework/runner/runner.py

@@ -39,6 +39,7 @@ logger = logging.getLogger(__name__)
 CLAUDE_CREDENTIALS_FILE = Path.home() / ".claude" / ".credentials.json"
 CLAUDE_OAUTH_TOKEN_URL = "https://console.anthropic.com/v1/oauth/token"
 CLAUDE_OAUTH_CLIENT_ID = "9d1c250a-e61b-44d9-88ed-5944d1962f5e"
+CLAUDE_KEYCHAIN_SERVICE = "Claude Code-credentials"
 
 # Buffer in seconds before token expiry to trigger a proactive refresh
 _TOKEN_REFRESH_BUFFER_SECS = 300  # 5 minutes
@@ -51,6 +52,96 @@ CODEX_KEYCHAIN_SERVICE = "Codex Auth"
 _CODEX_TOKEN_LIFETIME_SECS = 3600  # 1 hour (no explicit expiry field)
 
 
+def _read_claude_keychain() -> dict | None:
+    """Read Claude Code credentials from macOS Keychain.
+
+    Returns the parsed JSON dict, or None if not on macOS or entry missing.
+    """
+    import getpass
+    import platform
+    import subprocess
+
+    if platform.system() != "Darwin":
+        return None
+
+    try:
+        account = getpass.getuser()
+        result = subprocess.run(
+            [
+                "security",
+                "find-generic-password",
+                "-s",
+                CLAUDE_KEYCHAIN_SERVICE,
+                "-a",
+                account,
+                "-w",
+            ],
+            capture_output=True,
+            encoding="utf-8",
+            timeout=5,
+        )
+        if result.returncode != 0:
+            return None
+        raw = result.stdout.strip()
+        if not raw:
+            return None
+        return json.loads(raw)
+    except (subprocess.TimeoutExpired, json.JSONDecodeError, OSError) as exc:
+        logger.debug("Claude keychain read failed: %s", exc)
+        return None
+
+
+def _save_claude_keychain(creds: dict) -> bool:
+    """Write Claude Code credentials to macOS Keychain. Returns True on success."""
+    import getpass
+    import platform
+    import subprocess
+
+    if platform.system() != "Darwin":
+        return False
+
+    try:
+        account = getpass.getuser()
+        data = json.dumps(creds)
+        result = subprocess.run(
+            [
+                "security",
+                "add-generic-password",
+                "-U",
+                "-s",
+                CLAUDE_KEYCHAIN_SERVICE,
+                "-a",
+                account,
+                "-w",
+                data,
+            ],
+            capture_output=True,
+            timeout=5,
+        )
+        return result.returncode == 0
+    except (subprocess.TimeoutExpired, OSError) as exc:
+        logger.debug("Claude keychain write failed: %s", exc)
+        return False
+
+
+def _read_claude_credentials() -> dict | None:
+    """Read Claude Code credentials from Keychain (macOS) or file (Linux/Windows)."""
+    # Try macOS Keychain first
+    creds = _read_claude_keychain()
+    if creds:
+        return creds
+
+    # Fall back to file
+    if not CLAUDE_CREDENTIALS_FILE.exists():
+        return None
+
+    try:
+        with open(CLAUDE_CREDENTIALS_FILE, encoding="utf-8") as f:
+            return json.load(f)
+    except (json.JSONDecodeError, OSError):
+        return None
+
+
 def _refresh_claude_code_token(refresh_token: str) -> dict | None:
     """Refresh the Claude Code OAuth token using the refresh token.
 
@@ -89,16 +180,14 @@ def _refresh_claude_code_token(refresh_token: str) -> dict | None:
 
 
 def _save_refreshed_credentials(token_data: dict) -> None:
-    """Write refreshed token data back to ~/.claude/.credentials.json."""
+    """Write refreshed token data back to Keychain (macOS) or credentials file."""
     import time
 
-    if not CLAUDE_CREDENTIALS_FILE.exists():
+    creds = _read_claude_credentials()
+    if not creds:
         return
 
     try:
-        with open(CLAUDE_CREDENTIALS_FILE) as f:
-            creds = json.load(f)
-
         oauth = creds.get("claudeAiOauth", {})
         oauth["accessToken"] = token_data["access_token"]
         if "refresh_token" in token_data:
@@ -107,9 +196,15 @@ def _save_refreshed_credentials(token_data: dict) -> None:
             oauth["expiresAt"] = int((time.time() + token_data["expires_in"]) * 1000)
         creds["claudeAiOauth"] = oauth
 
-        with open(CLAUDE_CREDENTIALS_FILE, "w") as f:
+        # Try Keychain first (macOS), fall back to file
+        if _save_claude_keychain(creds):
+            logger.debug("Claude Code credentials refreshed in Keychain")
+            return
+
+        if CLAUDE_CREDENTIALS_FILE.exists():
+            with open(CLAUDE_CREDENTIALS_FILE, "w", encoding="utf-8") as f:
                 json.dump(creds, f, indent=2)
-        logger.debug("Claude Code credentials refreshed successfully")
+            logger.debug("Claude Code credentials refreshed in file")
     except (json.JSONDecodeError, OSError, KeyError) as exc:
         logger.debug("Failed to save refreshed credentials: %s", exc)
 
@@ -117,8 +212,8 @@ def _save_refreshed_credentials(token_data: dict) -> None:
 def get_claude_code_token() -> str | None:
     """Get the OAuth token from Claude Code subscription with auto-refresh.
 
-    Reads from ~/.claude/.credentials.json which is created by the
-    Claude Code CLI when users authenticate with their subscription.
+    Reads from macOS Keychain (on Darwin) or ~/.claude/.credentials.json
+    (on Linux/Windows), as created by the Claude Code CLI.
 
     If the token is expired or close to expiry, attempts an automatic
     refresh using the stored refresh token.
@@ -128,13 +223,8 @@ def get_claude_code_token() -> str | None:
     """
     import time
 
-    if not CLAUDE_CREDENTIALS_FILE.exists():
-        return None
-
-    try:
-        with open(CLAUDE_CREDENTIALS_FILE) as f:
-            creds = json.load(f)
-    except (json.JSONDecodeError, OSError):
+    creds = _read_claude_credentials()
+    if not creds:
         return None
 
     oauth = creds.get("claudeAiOauth", {})
@@ -212,7 +302,7 @@ def _read_codex_keychain() -> dict | None:
                 "-w",
             ],
             capture_output=True,
-            text=True,
+            encoding="utf-8",
             timeout=5,
         )
         if result.returncode != 0:
@@ -231,7 +321,7 @@ def _read_codex_auth_file() -> dict | None:
     if not CODEX_AUTH_FILE.exists():
         return None
     try:
-        with open(CODEX_AUTH_FILE) as f:
+        with open(CODEX_AUTH_FILE, encoding="utf-8") as f:
             return json.load(f)
     except (json.JSONDecodeError, OSError):
         return None
@@ -324,7 +414,7 @@ def _save_refreshed_codex_credentials(auth_data: dict, token_data: dict) -> None
 
         CODEX_AUTH_FILE.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
         fd = os.open(CODEX_AUTH_FILE, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
-        with os.fdopen(fd, "w") as f:
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
             json.dump(auth_data, f, indent=2)
         logger.debug("Codex credentials refreshed successfully")
     except (OSError, KeyError) as exc:
@@ -869,7 +959,7 @@ class AgentRunner:
         if not agent_json_path.exists():
             raise FileNotFoundError(f"No agent.py or agent.json found in {agent_path}")
 
-        with open(agent_json_path) as f:
+        with open(agent_json_path, encoding="utf-8") as f:
             graph, goal = load_agent_export(f.read())
 
         return cls(

core/framework/runner/tool_registry.py

@@ -326,6 +326,103 @@ class ToolRegistry:
         """Restore execution context to its previous state."""
         _execution_context.reset(token)
 
+    @staticmethod
+    def resolve_mcp_stdio_config(server_config: dict[str, Any], base_dir: Path) -> dict[str, Any]:
+        """Resolve cwd and script paths for MCP stdio config (Windows compatibility).
+
+        Use this when building MCPServerConfig from a config file (e.g. in
+        list_agent_tools, discover_mcp_tools) so hive-tools and other servers
+        work on Windows. Call with base_dir = directory containing the config.
+        """
+        registry = ToolRegistry()
+        return registry._resolve_mcp_server_config(server_config, base_dir)
+
+    def _resolve_mcp_server_config(
+        self, server_config: dict[str, Any], base_dir: Path
+    ) -> dict[str, Any]:
+        """Resolve cwd and script paths for MCP stdio servers (Windows compatibility).
+
+        On Windows, passing cwd to subprocess can cause WinError 267. We use cwd=None
+        and absolute script paths when the server runs a .py script from the tools dir.
+        If the resolved cwd doesn't exist (e.g. config from ~/.hive/agents/), fall back
+        to Path.cwd() / "tools".
+        """
+        config = dict(server_config)
+        if config.get("transport") != "stdio":
+            return config
+
+        cwd = config.get("cwd")
+        args = list(config.get("args", []))
+        if not cwd and not args:
+            return config
+
+        # Resolve cwd relative to base_dir
+        resolved_cwd: Path | None = None
+        if cwd:
+            if Path(cwd).is_absolute():
+                resolved_cwd = Path(cwd)
+            else:
+                resolved_cwd = (base_dir / cwd).resolve()
+
+        # Find .py script in args (e.g. coder_tools_server.py, files_server.py)
+        script_name = None
+        for i, arg in enumerate(args):
+            if isinstance(arg, str) and arg.endswith(".py"):
+                script_name = arg
+                script_idx = i
+                break
+
+        if resolved_cwd is None:
+            return config
+
+        # If resolved cwd doesn't exist or (when we have a script) doesn't contain it,
+        # try fallback
+        tools_fallback = Path.cwd() / "tools"
+        need_fallback = not resolved_cwd.is_dir()
+        if script_name and not need_fallback:
+            need_fallback = not (resolved_cwd / script_name).exists()
+        if need_fallback:
+            fallback_ok = tools_fallback.is_dir()
+            if script_name:
+                fallback_ok = fallback_ok and (tools_fallback / script_name).exists()
+            else:
+                # No script (e.g. GCU); just need tools dir to exist
+                pass
+            if fallback_ok:
+                resolved_cwd = tools_fallback
+                logger.debug(
+                    "MCP server '%s': using fallback tools dir %s",
+                    config.get("name", "?"),
+                    resolved_cwd,
+                )
+            else:
+                config["cwd"] = str(resolved_cwd)
+                return config
+
+        if not script_name:
+            # No .py script (e.g. GCU uses -m gcu.server); just set cwd
+            config["cwd"] = str(resolved_cwd)
+            return config
+
+        # For coder_tools_server, inject --project-root so writes go to the expected workspace
+        if script_name and "coder_tools" in script_name:
+            project_root = str(resolved_cwd.parent.resolve())
+            args = list(args)
+            if "--project-root" not in args:
+                args.extend(["--project-root", project_root])
+            config["args"] = args
+
+        if os.name == "nt":
+            # Windows: cwd=None avoids WinError 267; use absolute script path
+            config["cwd"] = None
+            abs_script = str((resolved_cwd / script_name).resolve())
+            args = list(config["args"])
+            args[script_idx] = abs_script
+            config["args"] = args
+        else:
+            config["cwd"] = str(resolved_cwd)
+        return config
+
     def load_mcp_config(self, config_path: Path) -> None:
         """
         Load and register MCP servers from a config file.
@@ -340,7 +437,7 @@ class ToolRegistry:
         self._mcp_config_path = Path(config_path)
 
         try:
-            with open(config_path) as f:
+            with open(config_path, encoding="utf-8") as f:
                 config = json.load(f)
         except Exception as e:
             logger.warning(f"Failed to load MCP config from {config_path}: {e}")
@@ -357,9 +454,7 @@ class ToolRegistry:
             server_list = [{"name": name, **cfg} for name, cfg in config.items()]
 
         for server_config in server_list:
-            cwd = server_config.get("cwd")
-            if cwd and not Path(cwd).is_absolute():
-                server_config["cwd"] = str((base_dir / cwd).resolve())
+            server_config = self._resolve_mcp_server_config(server_config, base_dir)
             try:
                 self.register_mcp_server(server_config)
             except Exception as e:
@@ -480,6 +575,11 @@ class ToolRegistry:
 
         except Exception as e:
             logger.error(f"Failed to register MCP server: {e}")
+            if "Connection closed" in str(e) and os.name == "nt":
+                logger.debug(
+                    "On Windows, check that the MCP subprocess starts (e.g. uv in PATH, "
+                    "script path correct). Worker config uses base_dir = mcp_servers.json parent."
+                )
             return 0
 
     def _convert_mcp_tool_to_framework_tool(self, mcp_tool: Any) -> Tool:

core/framework/server/routes_events.py

@@ -4,6 +4,7 @@ import asyncio
 import logging
 
 from aiohttp import web
+from aiohttp.client_exceptions import ClientConnectionResetError as _AiohttpConnReset
 
 from framework.runtime.event_bus import EventType
 from framework.server.app import resolve_session
@@ -168,8 +169,15 @@ async def handle_events(request: web.Request) -> web.StreamResponse:
                         "SSE first event: session='%s', type='%s'", session.id, data.get("type")
                     )
             except TimeoutError:
+                try:
                     await sse.send_keepalive()
-            except (ConnectionResetError, ConnectionError):
+                except (ConnectionResetError, ConnectionError, _AiohttpConnReset):
+                    close_reason = "client_disconnected"
+                    break
+                except Exception as exc:
+                    close_reason = f"keepalive_error: {exc}"
+                    break
+            except (ConnectionResetError, ConnectionError, _AiohttpConnReset):
                 close_reason = "client_disconnected"
                 break
             except Exception as exc:

core/framework/server/routes_execution.py

@@ -288,6 +288,60 @@ async def handle_resume(request: web.Request) -> web.Response:
     )
 
 
+async def handle_pause(request: web.Request) -> web.Response:
+    """POST /api/sessions/{session_id}/pause — pause the worker (queen stays alive).
+
+    Mirrors the queen's stop_worker() tool: cancels all active worker
+    executions, pauses timers so nothing auto-restarts, but does NOT
+    touch the queen so she can observe and react to the pause.
+    """
+    session, err = resolve_session(request)
+    if err:
+        return err
+
+    if not session.worker_runtime:
+        return web.json_response({"error": "No worker loaded in this session"}, status=503)
+
+    runtime = session.worker_runtime
+    cancelled = []
+
+    for graph_id in runtime.list_graphs():
+        reg = runtime.get_graph_registration(graph_id)
+        if reg is None:
+            continue
+        for _ep_id, stream in reg.streams.items():
+            # Signal shutdown on active nodes to abort in-flight LLM streams
+            for executor in stream._active_executors.values():
+                for node in executor.node_registry.values():
+                    if hasattr(node, "signal_shutdown"):
+                        node.signal_shutdown()
+                    if hasattr(node, "cancel_current_turn"):
+                        node.cancel_current_turn()
+
+            for exec_id in list(stream.active_execution_ids):
+                try:
+                    ok = await stream.cancel_execution(exec_id)
+                    if ok:
+                        cancelled.append(exec_id)
+                except Exception:
+                    pass
+
+    # Pause timers so the next tick doesn't restart execution
+    runtime.pause_timers()
+
+    # Switch to staging (agent still loaded, ready to re-run)
+    if session.mode_state is not None:
+        await session.mode_state.switch_to_staging(source="frontend")
+
+    return web.json_response(
+        {
+            "stopped": bool(cancelled),
+            "cancelled": cancelled,
+            "timers_paused": True,
+        }
+    )
+
+
 async def handle_stop(request: web.Request) -> web.Response:
     """POST /api/sessions/{session_id}/stop — cancel a running execution.
 
@@ -416,7 +470,7 @@ def register_routes(app: web.Application) -> None:
     app.router.add_post("/api/sessions/{session_id}/chat", handle_chat)
     app.router.add_post("/api/sessions/{session_id}/queen-context", handle_queen_context)
     app.router.add_post("/api/sessions/{session_id}/worker-input", handle_worker_input)
-    app.router.add_post("/api/sessions/{session_id}/pause", handle_stop)
+    app.router.add_post("/api/sessions/{session_id}/pause", handle_pause)
     app.router.add_post("/api/sessions/{session_id}/resume", handle_resume)
     app.router.add_post("/api/sessions/{session_id}/stop", handle_stop)
     app.router.add_post("/api/sessions/{session_id}/cancel-queen", handle_cancel_queen)

core/framework/server/routes_sessions.py

@@ -124,6 +124,9 @@ async def handle_create_session(request: web.Request) -> web.Response:
     session_id = body.get("session_id")
     model = body.get("model")
     initial_prompt = body.get("initial_prompt")
+    # When set, the queen writes conversations to this existing session's directory
+    # so the full history accumulates in one place across server restarts.
+    queen_resume_from = body.get("queen_resume_from")
 
     if agent_path:
         try:
@@ -139,6 +142,7 @@ async def handle_create_session(request: web.Request) -> web.Response:
                 agent_id=agent_id,
                 model=model,
                 initial_prompt=initial_prompt,
+                queen_resume_from=queen_resume_from,
             )
         else:
             # Queen-only session
@@ -146,6 +150,7 @@ async def handle_create_session(request: web.Request) -> web.Response:
                 session_id=session_id,
                 model=model,
                 initial_prompt=initial_prompt,
+                queen_resume_from=queen_resume_from,
             )
     except ValueError as e:
         msg = str(e)
@@ -179,7 +184,12 @@ async def handle_list_live_sessions(request: web.Request) -> web.Response:
 
 
 async def handle_get_live_session(request: web.Request) -> web.Response:
-    """GET /api/sessions/{session_id} — get session detail."""
+    """GET /api/sessions/{session_id} — get session detail.
+
+    Falls back to cold session metadata (HTTP 200 with ``cold: true``) when the
+    session is not alive in memory but queen conversation files exist on disk.
+    This lets the frontend detect a server restart and restore message history.
+    """
     manager = _get_manager(request)
     session_id = request.match_info["session_id"]
     session = manager.get_session(session_id)
@@ -190,6 +200,10 @@ async def handle_get_live_session(request: web.Request) -> web.Response:
                 {"session_id": session_id, "loading": True},
                 status=202,
             )
+        # Check if conversation files survived on disk (post-restart scenario)
+        cold_info = SessionManager.get_cold_session_info(session_id)
+        if cold_info is not None:
+            return web.json_response(cold_info)
         return web.json_response(
             {"error": f"Session '{session_id}' not found"},
             status=404,
@@ -613,15 +627,17 @@ async def handle_messages(request: web.Request) -> web.Response:
 
 
 async def handle_queen_messages(request: web.Request) -> web.Response:
-    """GET /api/sessions/{session_id}/queen-messages — get queen conversation."""
-    session, err = resolve_session(request)
-    if err:
-        return err
+    """GET /api/sessions/{session_id}/queen-messages — get queen conversation.
 
-    queen_dir = Path.home() / ".hive" / "queen" / "session" / session.id
+    Reads directly from disk so it works for both live sessions and cold
+    (post-server-restart) sessions — no live session required.
+    """
+    session_id = request.match_info["session_id"]
+
+    queen_dir = Path.home() / ".hive" / "queen" / "session" / session_id
     convs_dir = queen_dir / "conversations"
     if not convs_dir.exists():
-        return web.json_response({"messages": []})
+        return web.json_response({"messages": [], "session_id": session_id})
 
     all_messages: list[dict] = []
     for node_dir in convs_dir.iterdir():
@@ -654,7 +670,58 @@ async def handle_queen_messages(request: web.Request) -> web.Response:
         and not (m["role"] == "assistant" and m.get("tool_calls"))
     ]
 
-    return web.json_response({"messages": all_messages})
+    return web.json_response({"messages": all_messages, "session_id": session_id})
+
+
+async def handle_session_history(request: web.Request) -> web.Response:
+    """GET /api/sessions/history — all queen sessions on disk (live + cold).
+
+    Returns every session directory under ~/.hive/queen/session/, newest first.
+    Live sessions have ``live: true, cold: false``; sessions that survived a
+    server restart have ``live: false, cold: true``.
+    """
+    manager = _get_manager(request)
+    live_sessions = {s.id: s for s in manager.list_sessions()}
+
+    disk_sessions = SessionManager.list_cold_sessions()
+    for s in disk_sessions:
+        if s["session_id"] in live_sessions:
+            live = live_sessions[s["session_id"]]
+            s["cold"] = False
+            s["live"] = True
+            # Fill in agent_name from live memory if meta.json wasn't written yet
+            if not s.get("agent_name") and live.worker_info:
+                s["agent_name"] = live.worker_info.name
+            if not s.get("agent_path") and live.worker_path:
+                s["agent_path"] = str(live.worker_path)
+
+    return web.json_response({"sessions": disk_sessions})
+
+
+async def handle_delete_history_session(request: web.Request) -> web.Response:
+    """DELETE /api/sessions/history/{session_id} — permanently remove a session.
+
+    Stops the live session (if still running) and deletes the queen session
+    directory from disk at ~/.hive/queen/session/{session_id}/.
+    This is the frontend 'delete from history' action.
+    """
+    manager = _get_manager(request)
+    session_id = request.match_info["session_id"]
+
+    # Stop the live session if it exists (best-effort)
+    if manager.get_session(session_id):
+        await manager.stop_session(session_id)
+
+    # Delete the queen session directory from disk
+    queen_session_dir = Path.home() / ".hive" / "queen" / "session" / session_id
+    if queen_session_dir.exists() and queen_session_dir.is_dir():
+        try:
+            shutil.rmtree(queen_session_dir)
+        except OSError as e:
+            logger.warning("Failed to delete session directory %s: %s", queen_session_dir, e)
+            return web.json_response({"error": f"Failed to delete session: {e}"}, status=500)
+
+    return web.json_response({"deleted": session_id})
 
 
 # ------------------------------------------------------------------
@@ -703,6 +770,9 @@ def register_routes(app: web.Application) -> None:
     # Session lifecycle
     app.router.add_post("/api/sessions", handle_create_session)
     app.router.add_get("/api/sessions", handle_list_live_sessions)
+    # history must be registered before {session_id} so it takes priority
+    app.router.add_get("/api/sessions/history", handle_session_history)
+    app.router.add_delete("/api/sessions/history/{session_id}", handle_delete_history_session)
     app.router.add_get("/api/sessions/{session_id}", handle_get_live_session)
     app.router.add_delete("/api/sessions/{session_id}", handle_stop_session)
 

core/framework/server/session_manager.py

@@ -45,6 +45,11 @@ class Session:
     # Judge (active when worker is loaded)
     judge_task: asyncio.Task | None = None
     escalation_sub: str | None = None
+    # Session directory resumption:
+    # When set, _start_queen writes queen conversations to this existing session's
+    # directory instead of creating a new one.  This lets cold-restores accumulate
+    # all messages in the original session folder so history is never fragmented.
+    queen_resume_from: str | None = None
 
 
 class SessionManager:
@@ -114,18 +119,25 @@ class SessionManager:
         session_id: str | None = None,
         model: str | None = None,
         initial_prompt: str | None = None,
+        queen_resume_from: str | None = None,
     ) -> Session:
         """Create a new session with a queen but no worker.
 
-        The queen starts immediately with MCP coding tools.
-        A worker can be loaded later via load_worker().
+        When ``queen_resume_from`` is set the queen writes conversation messages
+        to that existing session's directory instead of creating a new one.
+        This preserves full conversation history across server restarts.
         """
         session = await self._create_session_core(session_id=session_id, model=model)
+        session.queen_resume_from = queen_resume_from
 
         # Start queen immediately (queen-only, no worker tools yet)
         await self._start_queen(session, worker_identity=None, initial_prompt=initial_prompt)
 
-        logger.info("Session '%s' created (queen-only)", session.id)
+        logger.info(
+            "Session '%s' created (queen-only, resume_from=%s)",
+            session.id,
+            queen_resume_from,
+        )
         return session
 
     async def create_session_with_worker(
@@ -134,15 +146,12 @@ class SessionManager:
         agent_id: str | None = None,
         model: str | None = None,
         initial_prompt: str | None = None,
+        queen_resume_from: str | None = None,
     ) -> Session:
         """Create a session and load a worker in one step.
 
-        Backward-compatible with the old POST /api/agents flow.
-        Loads the worker FIRST so the queen starts with full lifecycle
-        and monitoring tools available.
-
-        The session gets an auto-generated unique ID. The agent name
-        becomes the worker_id (used by the frontend as backendAgentId).
+        When ``queen_resume_from`` is set the queen writes conversation messages
+        to that existing session's directory instead of creating a new one.
         """
         from framework.tools.queen_lifecycle_tools import build_worker_profile
 
@@ -151,6 +160,7 @@ class SessionManager:
 
         # Auto-generate session ID (not the agent name)
         session = await self._create_session_core(model=model)
+        session.queen_resume_from = queen_resume_from
         try:
             # Load worker FIRST (before queen) so queen gets full tools
             await self._load_worker_core(
@@ -170,10 +180,6 @@ class SessionManager:
                 session, worker_identity=worker_identity, initial_prompt=initial_prompt
             )
 
-            # Health judge disabled for simplicity.
-            # if agent_path.name != "hive_coder" and session.worker_runtime:
-            #     await self._start_judge(session, session.runner._storage_path)
-
         except Exception:
             # If anything fails, tear down the session
             await self.stop_session(session.id)
@@ -401,7 +407,12 @@ class SessionManager:
         worker_identity: str | None,
         initial_prompt: str | None = None,
     ) -> None:
-        """Start the queen executor for a session."""
+        """Start the queen executor for a session.
+
+        When ``session.queen_resume_from`` is set, queen conversation messages
+        are written to the ORIGINAL session's directory so the full conversation
+        history accumulates in one place across server restarts.
+        """
         from framework.agents.hive_coder.agent import (
             queen_goal,
             queen_graph as _queen_graph,
@@ -411,9 +422,41 @@ class SessionManager:
         from framework.runtime.core import Runtime
 
         hive_home = Path.home() / ".hive"
-        queen_dir = hive_home / "queen" / "session" / session.id
+
+        # Determine which session directory to use for queen storage.
+        # When queen_resume_from is set we write to the ORIGINAL session's
+        # directory so that all messages accumulate in one place.
+        storage_session_id = session.queen_resume_from or session.id
+        queen_dir = hive_home / "queen" / "session" / storage_session_id
         queen_dir.mkdir(parents=True, exist_ok=True)
 
+        # Always write/update session metadata so history sidebar has correct
+        # agent name, path, and last-active timestamp (important so the original
+        # session directory sorts as "most recent" after a cold-restore resume).
+        _meta_path = queen_dir / "meta.json"
+        try:
+            _agent_name = (
+                session.worker_info.name
+                if session.worker_info
+                else (
+                    str(session.worker_path.name).replace("_", " ").title()
+                    if session.worker_path
+                    else None
+                )
+            )
+            _meta_path.write_text(
+                json.dumps(
+                    {
+                        "agent_name": _agent_name,
+                        "agent_path": str(session.worker_path) if session.worker_path else None,
+                        "created_at": time.time(),
+                    }
+                ),
+                encoding="utf-8",
+            )
+        except OSError:
+            pass
+
         # Register MCP coding tools
         queen_registry = ToolRegistry()
         import framework.agents.hive_coder as _hive_coder_pkg
@@ -774,6 +817,166 @@ class SessionManager:
     def list_sessions(self) -> list[Session]:
         return list(self._sessions.values())
 
+    # ------------------------------------------------------------------
+    # Cold session helpers (disk-only, no live runtime required)
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def get_cold_session_info(session_id: str) -> dict | None:
+        """Return disk metadata for a session that is no longer live in memory.
+
+        Checks whether queen conversation files exist at
+        ~/.hive/queen/session/{session_id}/conversations/.  Returns None when
+        no data is found so callers can fall through to a 404.
+        """
+        queen_dir = Path.home() / ".hive" / "queen" / "session" / session_id
+        convs_dir = queen_dir / "conversations"
+        if not convs_dir.exists():
+            return None
+
+        # Check whether any message part files are actually present
+        has_messages = False
+        try:
+            for node_dir in convs_dir.iterdir():
+                if not node_dir.is_dir():
+                    continue
+                parts_dir = node_dir / "parts"
+                if parts_dir.exists() and any(f.suffix == ".json" for f in parts_dir.iterdir()):
+                    has_messages = True
+                    break
+        except OSError:
+            pass
+
+        try:
+            created_at = queen_dir.stat().st_ctime
+        except OSError:
+            created_at = 0.0
+
+        # Read extra metadata written at session start
+        agent_name: str | None = None
+        agent_path: str | None = None
+        meta_path = queen_dir / "meta.json"
+        if meta_path.exists():
+            try:
+                meta = json.loads(meta_path.read_text(encoding="utf-8"))
+                agent_name = meta.get("agent_name")
+                agent_path = meta.get("agent_path")
+                created_at = meta.get("created_at") or created_at
+            except (json.JSONDecodeError, OSError):
+                pass
+
+        return {
+            "session_id": session_id,
+            "cold": True,
+            "live": False,
+            "has_messages": has_messages,
+            "created_at": created_at,
+            "agent_name": agent_name,
+            "agent_path": agent_path,
+        }
+
+    @staticmethod
+    def list_cold_sessions() -> list[dict]:
+        """Return metadata for every queen session directory on disk, newest first."""
+        queen_sessions_dir = Path.home() / ".hive" / "queen" / "session"
+        if not queen_sessions_dir.exists():
+            return []
+
+        results: list[dict] = []
+        try:
+            entries = sorted(
+                queen_sessions_dir.iterdir(),
+                key=lambda p: p.stat().st_mtime,
+                reverse=True,
+            )
+        except OSError:
+            return []
+
+        for d in entries:
+            if not d.is_dir():
+                continue
+            try:
+                created_at = d.stat().st_ctime
+            except OSError:
+                created_at = 0.0
+            agent_name: str | None = None
+            agent_path: str | None = None
+            meta_path = d / "meta.json"
+            if meta_path.exists():
+                try:
+                    meta = json.loads(meta_path.read_text(encoding="utf-8"))
+                    agent_name = meta.get("agent_name")
+                    agent_path = meta.get("agent_path")
+                    created_at = meta.get("created_at") or created_at
+                except (json.JSONDecodeError, OSError):
+                    pass
+
+            # Build a quick preview of the last human/assistant exchange.
+            # We read all conversation parts, filter to client-facing messages,
+            # and return the last assistant message content as a snippet.
+            last_message: str | None = None
+            message_count: int = 0
+            convs_dir = d / "conversations"
+            if convs_dir.exists():
+                try:
+                    all_parts: list[dict] = []
+                    for node_dir in convs_dir.iterdir():
+                        if not node_dir.is_dir():
+                            continue
+                        parts_dir = node_dir / "parts"
+                        if not parts_dir.exists():
+                            continue
+                        for part_file in sorted(parts_dir.iterdir()):
+                            if part_file.suffix != ".json":
+                                continue
+                            try:
+                                part = json.loads(part_file.read_text(encoding="utf-8"))
+                                part.setdefault("created_at", part_file.stat().st_mtime)
+                                all_parts.append(part)
+                            except (json.JSONDecodeError, OSError):
+                                continue
+                    # Filter to client-facing messages only
+                    client_msgs = [
+                        p
+                        for p in all_parts
+                        if not p.get("is_transition_marker")
+                        and p.get("role") != "tool"
+                        and not (p.get("role") == "assistant" and p.get("tool_calls"))
+                    ]
+                    client_msgs.sort(key=lambda m: m.get("created_at", m.get("seq", 0)))
+                    message_count = len(client_msgs)
+                    # Last assistant message as preview snippet
+                    for msg in reversed(client_msgs):
+                        content = msg.get("content") or ""
+                        if isinstance(content, list):
+                            # Anthropic-style content blocks
+                            content = " ".join(
+                                b.get("text", "")
+                                for b in content
+                                if isinstance(b, dict) and b.get("type") == "text"
+                            )
+                        if content and msg.get("role") == "assistant":
+                            last_message = content[:120].strip()
+                            break
+                except OSError:
+                    pass
+
+            results.append(
+                {
+                    "session_id": d.name,
+                    "cold": True,  # caller overrides for live sessions
+                    "live": False,
+                    "has_messages": convs_dir.exists() and message_count > 0,
+                    "created_at": created_at,
+                    "agent_name": agent_name,
+                    "agent_path": agent_path,
+                    "last_message": last_message,
+                    "message_count": message_count,
+                }
+            )
+
+        return results
+
     async def shutdown_all(self) -> None:
         """Gracefully stop all sessions. Called on server shutdown."""
         session_ids = list(self._sessions.keys())

core/framework/server/tests/test_api.py

@@ -74,6 +74,7 @@ class MockStream:
     is_awaiting_input: bool = False
     _execution_tasks: dict = field(default_factory=dict)
     _active_executors: dict = field(default_factory=dict)
+    active_execution_ids: set = field(default_factory=set)
 
     async def cancel_execution(self, execution_id: str) -> bool:
         return execution_id in self._execution_tasks
@@ -117,6 +118,9 @@ class MockRuntime:
     async def inject_input(self, node_id, content, graph_id=None, *, is_client_input=False):
         return True
 
+    def pause_timers(self):
+        pass
+
     async def get_goal_progress(self):
         return {"progress": 0.5, "criteria": []}
 
@@ -537,18 +541,8 @@ class TestExecution:
             assert resp.status == 400
 
     @pytest.mark.asyncio
-    async def test_pause_not_found(self):
-        session = _make_session()
-        app = _make_app_with_session(session)
-        async with TestClient(TestServer(app)) as client:
-            resp = await client.post(
-                "/api/sessions/test_agent/pause",
-                json={"execution_id": "nonexistent"},
-            )
-            assert resp.status == 404
-
-    @pytest.mark.asyncio
-    async def test_pause_missing_execution_id(self):
+    async def test_pause_no_active_executions(self):
+        """Pause with no active executions returns stopped=False."""
         session = _make_session()
         app = _make_app_with_session(session)
         async with TestClient(TestServer(app)) as client:
@@ -556,7 +550,26 @@ class TestExecution:
                 "/api/sessions/test_agent/pause",
                 json={},
             )
-            assert resp.status == 400
+            assert resp.status == 200
+            data = await resp.json()
+            assert data["stopped"] is False
+            assert data["cancelled"] == []
+            assert data["timers_paused"] is True
+
+    @pytest.mark.asyncio
+    async def test_pause_does_not_cancel_queen(self):
+        """Pause should stop the worker but leave the queen running."""
+        session = _make_session()
+        app = _make_app_with_session(session)
+        async with TestClient(TestServer(app)) as client:
+            resp = await client.post(
+                "/api/sessions/test_agent/pause",
+                json={},
+            )
+            assert resp.status == 200
+            # Queen's cancel_current_turn should NOT have been called
+            queen_node = session.queen_executor.node_registry["queen"]
+            queen_node.cancel_current_turn.assert_not_called()
 
     @pytest.mark.asyncio
     async def test_goal_progress(self):

core/framework/testing/approval_cli.py

@@ -270,10 +270,10 @@ def _edit_test_code(code: str) -> str:
 
     try:
         # Open editor
-        subprocess.run([editor, temp_path], check=True)
+        subprocess.run([editor, temp_path], check=True, encoding="utf-8")
 
         # Read edited code
-        with open(temp_path) as f:
+        with open(temp_path, encoding="utf-8") as f:
             return f.read()
     except subprocess.CalledProcessError:
         print("Editor failed, keeping original code")

core/framework/testing/cli.py

@@ -190,6 +190,7 @@ def cmd_test_run(args: argparse.Namespace) -> int:
     try:
         result = subprocess.run(
             cmd,
+            encoding="utf-8",
             env=env,
             timeout=600,  # 10 minute timeout
         )
@@ -248,6 +249,7 @@ def cmd_test_debug(args: argparse.Namespace) -> int:
     try:
         result = subprocess.run(
             cmd,
+            encoding="utf-8",
             env=env,
             timeout=120,  # 2 minute timeout for single test
         )

core/framework/tui/app.py

@@ -256,7 +256,7 @@ class AdenTUI(App):
         """Override to use native `open` for file:// URLs on macOS."""
         if url.startswith("file://") and platform.system() == "Darwin":
             path = url.removeprefix("file://")
-            subprocess.Popen(["open", path])
+            subprocess.Popen(["open", path], encoding="utf-8")
         else:
             super().open_url(url, new_tab=new_tab)
 

core/framework/tui/widgets/chat_repl.py

@@ -488,7 +488,7 @@ class ChatRepl(Vertical):
                 if not state_file.exists():
                     continue
 
-                with open(state_file) as f:
+                with open(state_file, encoding="utf-8") as f:
                     state = json.load(f)
 
                 status = state.get("status", "").lower()
@@ -547,7 +547,7 @@ class ChatRepl(Vertical):
 
             # Read session state
             try:
-                with open(state_file) as f:
+                with open(state_file, encoding="utf-8") as f:
                     state = json.load(f)
 
                 # Track this session for /resume <number> lookup
@@ -599,7 +599,7 @@ class ChatRepl(Vertical):
         try:
             import json
 
-            with open(state_file) as f:
+            with open(state_file, encoding="utf-8") as f:
                 state = json.load(f)
 
             # Basic info
@@ -640,7 +640,7 @@ class ChatRepl(Vertical):
                     # Load and show checkpoints
                     for i, cp_file in enumerate(checkpoint_files[-5:], 1):  # Last 5
                         try:
-                            with open(cp_file) as f:
+                            with open(cp_file, encoding="utf-8") as f:
                                 cp_data = json.load(f)
 
                             cp_id = cp_data.get("checkpoint_id", cp_file.stem)
@@ -687,7 +687,7 @@ class ChatRepl(Vertical):
 
             import json
 
-            with open(state_file) as f:
+            with open(state_file, encoding="utf-8") as f:
                 state = json.load(f)
 
             # Resume from session state (not checkpoint)
@@ -1102,7 +1102,7 @@ class ChatRepl(Vertical):
                     continue
 
                 try:
-                    with open(state_file) as f:
+                    with open(state_file, encoding="utf-8") as f:
                         state = json.load(f)
 
                     status = state.get("status", "").lower()

core/framework/tui/widgets/file_browser.py

@@ -38,6 +38,7 @@ def _linux_file_dialog() -> subprocess.CompletedProcess | None:
                 "--title=Select a PDF file",
                 "--file-filter=PDF files (*.pdf)|*.pdf",
             ],
+            encoding="utf-8",
             capture_output=True,
             text=True,
             timeout=300,
@@ -54,6 +55,7 @@ def _linux_file_dialog() -> subprocess.CompletedProcess | None:
                 ".",
                 "PDF files (*.pdf)",
             ],
+            encoding="utf-8",
             capture_output=True,
             text=True,
             timeout=300,
@@ -79,6 +81,7 @@ def _pick_pdf_subprocess() -> Path | None:
                     'POSIX path of (choose file of type {"com.adobe.pdf"} '
                     'with prompt "Select a PDF file")',
                 ],
+                encoding="utf-8",
                 capture_output=True,
                 text=True,
                 timeout=300,
@@ -93,6 +96,7 @@ def _pick_pdf_subprocess() -> Path | None:
             )
             result = subprocess.run(
                 ["powershell", "-NoProfile", "-Command", ps_script],
+                encoding="utf-8",
                 capture_output=True,
                 text=True,
                 timeout=300,

core/framework/tui/widgets/selectable_rich_log.py

@@ -199,10 +199,11 @@ def _copy_to_clipboard(text: str) -> None:
     """Copy text to system clipboard using platform-native tools."""
     try:
         if sys.platform == "darwin":
-            subprocess.run(["pbcopy"], input=text.encode(), check=True, timeout=5)
+            subprocess.run(["pbcopy"], encoding="utf-8", input=text.encode(), check=True, timeout=5)
         elif sys.platform == "win32":
             subprocess.run(
                 ["clip.exe"],
+                encoding="utf-8",
                 input=text.encode("utf-16le"),
                 check=True,
                 timeout=5,
@@ -211,6 +212,7 @@ def _copy_to_clipboard(text: str) -> None:
             try:
                 subprocess.run(
                     ["xclip", "-selection", "clipboard"],
+                    encoding="utf-8",
                     input=text.encode(),
                     check=True,
                     timeout=5,
@@ -218,6 +220,7 @@ def _copy_to_clipboard(text: str) -> None:
             except (subprocess.SubprocessError, FileNotFoundError):
                 subprocess.run(
                     ["xsel", "--clipboard", "--input"],
+                    encoding="utf-8",
                     input=text.encode(),
                     check=True,
                     timeout=5,

core/frontend/src/api/sessions.ts

@@ -13,12 +13,13 @@ export const sessionsApi = {
   // --- Session lifecycle ---
 
   /** Create a session. If agentPath is provided, loads worker in one step. */
-  create: (agentPath?: string, agentId?: string, model?: string, initialPrompt?: string) =>
+  create: (agentPath?: string, agentId?: string, model?: string, initialPrompt?: string, queenResumeFrom?: string) =>
     api.post<LiveSession>("/sessions", {
       agent_path: agentPath,
       agent_id: agentId,
       model,
       initial_prompt: initialPrompt,
+      queen_resume_from: queenResumeFrom || undefined,
     }),
 
   /** List all active sessions. */
@@ -66,9 +67,17 @@ export const sessionsApi = {
   graphs: (sessionId: string) =>
     api.get<{ graphs: string[] }>(`/sessions/${sessionId}/graphs`),
 
-  /** Get queen conversation history for a session. */
+  /** Get queen conversation history for a session (works for cold/post-restart sessions too). */
   queenMessages: (sessionId: string) =>
-    api.get<{ messages: Message[] }>(`/sessions/${sessionId}/queen-messages`),
+    api.get<{ messages: Message[]; session_id: string }>(`/sessions/${sessionId}/queen-messages`),
+
+  /** List all queen sessions on disk — live + cold (post-restart). */
+  history: () =>
+    api.get<{ sessions: Array<{ session_id: string; cold: boolean; live: boolean; has_messages: boolean; created_at: number; agent_name?: string | null; agent_path?: string | null }> }>("/sessions/history"),
+
+  /** Permanently delete a history session (stops live session + removes disk files). */
+  deleteHistory: (sessionId: string) =>
+    api.delete<{ deleted: string }>(`/sessions/history/${sessionId}`),
 
   // --- Worker session browsing (persisted execution runs) ---
 

core/frontend/src/api/types.ts

@@ -21,6 +21,8 @@ export interface LiveSession {
 export interface LiveSessionDetail extends LiveSession {
   entry_points?: EntryPoint[];
   graphs?: string[];
+  /** True when the session exists on disk but is not live (server restarted). */
+  cold?: boolean;
 }
 
 export interface EntryPoint {

core/frontend/src/components/HistorySidebar.tsx

@@ -0,0 +1,431 @@
+/**
+ * HistorySidebar — persistent ChatGPT-style session history sidebar.
+ *
+ * Shown on both the Home page and the Workspace.  Clicking a session fires
+ * `onOpen(sessionId, agentPath)` so the caller decides what to do (navigate
+ * to workspace on Home, open/switch tab on Workspace).
+ *
+ * Labels (user-visible names) are stored purely in localStorage — backend
+ * session IDs are never touched.
+ *
+ * Session deduplication: the backend may have multiple session directories
+ * for the same agent (cold restarts create new directories). We deduplicate
+ * by agent_path and show only the most-recent session per agent so the
+ * history list stays clean.
+ */
+
+import { useState, useEffect, useRef, useCallback } from "react";
+import { ChevronLeft, ChevronRight, Clock, Bot, Loader2, MoreHorizontal, Pencil, Trash2, Check, X } from "lucide-react";
+import { sessionsApi } from "@/api/sessions";
+
+// ── Types ─────────────────────────────────────────────────────────────────────
+
+export type HistorySession = {
+  session_id: string;
+  cold: boolean;
+  live: boolean;
+  has_messages: boolean;
+  created_at: number;
+  agent_name?: string | null;
+  agent_path?: string | null;
+  /** Snippet of the last assistant message — for sidebar preview. */
+  last_message?: string | null;
+  /** Total number of client-facing messages in this session. */
+  message_count?: number;
+};
+
+const LABEL_STORE_KEY = "hive:history-labels";
+
+function loadLabelStore(): Record<string, string> {
+  try {
+    const raw = localStorage.getItem(LABEL_STORE_KEY);
+    return raw ? (JSON.parse(raw) as Record<string, string>) : {};
+  } catch {
+    return {};
+  }
+}
+
+function saveLabelStore(store: Record<string, string>) {
+  try {
+    localStorage.setItem(LABEL_STORE_KEY, JSON.stringify(store));
+  } catch { }
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function defaultLabel(s: HistorySession, index: number): string {
+  if (s.agent_name) return s.agent_name;
+  if (s.agent_path) {
+    const base = s.agent_path.replace(/\/$/, "").split("/").pop() || s.agent_path;
+    return base
+      .split("_")
+      .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+      .join(" ");
+  }
+  return `New Agent${index > 0 ? ` #${index + 1}` : ""}`;
+}
+
+function formatDateTime(createdAt: number, sessionId: string): string {
+  // Prefer timestamp embedded in session_id: session_YYYYMMDD_HHMMSS_xxx
+  const match = sessionId.match(/^session_(\d{4})(\d{2})(\d{2})_(\d{2})(\d{2})(\d{2})/);
+  const d = match
+    ? new Date(+match[1], +match[2] - 1, +match[3], +match[4], +match[5], +match[6])
+    : new Date(createdAt * 1000);
+  return d.toLocaleString(undefined, {
+    month: "short",
+    day: "numeric",
+    hour: "2-digit",
+    minute: "2-digit",
+  });
+}
+
+/**
+ * Deduplicate sessions by agent_path — keep only the most recent session
+ * per agent. Sessions are already sorted newest-first by the backend.
+ * Sessions without an agent_path (new-agent / queen-only) are kept individually.
+ */
+function deduplicateByAgent(sessions: HistorySession[]): HistorySession[] {
+  const seen = new Set<string>();
+  const result: HistorySession[] = [];
+  for (const s of sessions) {
+    // Group key: use agent_path when present, otherwise use session_id (unique)
+    const key = s.agent_path ? s.agent_path.replace(/\/$/, "") : `__no_agent__${s.session_id}`;
+    if (!seen.has(key)) {
+      seen.add(key);
+      result.push(s);
+    }
+    // Additional sessions for the same agent are silently skipped
+  }
+  return result;
+}
+
+function groupByDate(sessions: HistorySession[]): { label: string; items: HistorySession[] }[] {
+  const now = new Date();
+  const today = new Date(now.getFullYear(), now.getMonth(), now.getDate()).getTime();
+  const yesterday = today - 86_400_000;
+  const weekAgo = today - 7 * 86_400_000;
+  const groups: { label: string; items: HistorySession[] }[] = [
+    { label: "Today", items: [] },
+    { label: "Yesterday", items: [] },
+    { label: "Last 7 days", items: [] },
+    { label: "Older", items: [] },
+  ];
+  for (const s of sessions) {
+    const d = new Date(s.created_at * 1000);
+    const dayTs = new Date(d.getFullYear(), d.getMonth(), d.getDate()).getTime();
+    if (dayTs >= today) groups[0].items.push(s);
+    else if (dayTs >= yesterday) groups[1].items.push(s);
+    else if (dayTs >= weekAgo) groups[2].items.push(s);
+    else groups[3].items.push(s);
+  }
+  return groups.filter((g) => g.items.length > 0);
+}
+
+// ── Row component ─────────────────────────────────────────────────────────────
+
+interface RowProps {
+  session: HistorySession;
+  label: string;
+  index: number;
+  isActive: boolean;
+  isLive: boolean;
+  onOpen: () => void;
+  onRename: (newLabel: string) => void;
+  onDelete: () => void;
+}
+
+function HistoryRow({ session: s, label, isActive, isLive, onOpen, onRename, onDelete }: RowProps) {
+  const [menuOpen, setMenuOpen] = useState(false);
+  const [renaming, setRenaming] = useState(false);
+  const [draftLabel, setDraftLabel] = useState(label);
+  const menuRef = useRef<HTMLDivElement>(null);
+  const inputRef = useRef<HTMLInputElement>(null);
+
+  useEffect(() => {
+    if (!menuOpen) return;
+    const handler = (e: MouseEvent) => {
+      if (menuRef.current && !menuRef.current.contains(e.target as Node)) setMenuOpen(false);
+    };
+    document.addEventListener("mousedown", handler);
+    return () => document.removeEventListener("mousedown", handler);
+  }, [menuOpen]);
+
+  useEffect(() => {
+    if (renaming) {
+      setDraftLabel(label);
+      requestAnimationFrame(() => inputRef.current?.select());
+    }
+  }, [renaming, label]);
+
+  const commitRename = () => {
+    const trimmed = draftLabel.trim();
+    if (trimmed) onRename(trimmed);
+    setRenaming(false);
+  };
+
+  const dateStr = formatDateTime(s.created_at, s.session_id);
+
+  return (
+    <div
+      className={`group relative flex items-start gap-2 px-3 py-2 cursor-pointer transition-colors ${isActive
+        ? "bg-primary/10 border-l-2 border-primary"
+        : "border-l-2 border-transparent hover:bg-muted/40"
+        }`}
+      onClick={() => { if (!renaming) onOpen(); }}
+    >
+      <Bot className="w-3.5 h-3.5 flex-shrink-0 mt-[3px] text-muted-foreground/40 group-hover:text-muted-foreground/70 transition-colors" />
+
+      <div className="min-w-0 flex-1">
+        {renaming ? (
+          <div className="flex items-center gap-1" onClick={(e) => e.stopPropagation()}>
+            <input
+              ref={inputRef}
+              value={draftLabel}
+              onChange={(e) => setDraftLabel(e.target.value)}
+              onKeyDown={(e) => {
+                if (e.key === "Enter") commitRename();
+                if (e.key === "Escape") setRenaming(false);
+              }}
+              className="flex-1 min-w-0 text-[11px] bg-muted/60 border border-border/50 rounded px-1.5 py-0.5 text-foreground focus:outline-none focus:ring-1 focus:ring-primary/40"
+            />
+            <button onClick={commitRename} className="p-0.5 text-primary hover:text-primary/80">
+              <Check className="w-3 h-3" />
+            </button>
+            <button onClick={() => setRenaming(false)} className="p-0.5 text-muted-foreground hover:text-foreground">
+              <X className="w-3 h-3" />
+            </button>
+          </div>
+        ) : (
+          <>
+            <div className={`text-[11px] font-medium truncate leading-tight ${isActive ? "text-foreground" : "text-foreground/80"}`}>
+              {label}
+            </div>
+            {/* Message preview — most recent assistant message */}
+            {s.last_message && (
+              <div className="text-[10px] text-muted-foreground/50 mt-0.5 leading-tight line-clamp-2 break-words">
+                {s.last_message}
+              </div>
+            )}
+            <div className="flex items-center gap-1.5 mt-0.5">
+              <div className="text-[10px] text-muted-foreground/40">{dateStr}</div>
+              {(s.message_count ?? 0) > 0 && (
+                <span className="text-[9px] text-muted-foreground/30">· {s.message_count} msgs</span>
+              )}
+            </div>
+            {isLive && (
+              <span className="text-[9px] text-emerald-500/80 font-semibold uppercase tracking-wide">live</span>
+            )}
+          </>
+        )}
+      </div>
+
+      {/* 3-dot button — visible on row hover */}
+      {!renaming && (
+        <div className="relative flex-shrink-0" ref={menuRef} onClick={(e) => e.stopPropagation()}>
+          <button
+            onClick={() => setMenuOpen((o) => !o)}
+            className={`p-0.5 rounded transition-colors text-muted-foreground/40 hover:text-foreground hover:bg-muted/60 ${menuOpen ? "opacity-100" : "opacity-0 group-hover:opacity-100"
+              }`}
+            title="More options"
+          >
+            <MoreHorizontal className="w-3.5 h-3.5" />
+          </button>
+
+          {menuOpen && (
+            <div className="absolute right-0 top-5 z-50 w-36 rounded-lg border border-border/60 bg-card shadow-xl shadow-black/30 overflow-hidden py-1">
+              <button
+                onClick={() => { setMenuOpen(false); setRenaming(true); }}
+                className="flex items-center gap-2 w-full px-3 py-1.5 text-xs text-foreground hover:bg-muted/60 transition-colors"
+              >
+                <Pencil className="w-3 h-3 text-muted-foreground" />
+                Rename
+              </button>
+              <button
+                onClick={() => { setMenuOpen(false); onDelete(); }}
+                className="flex items-center gap-2 w-full px-3 py-1.5 text-xs text-destructive hover:bg-destructive/10 transition-colors"
+              >
+                <Trash2 className="w-3 h-3" />
+                Delete
+              </button>
+            </div>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}
+
+// ── Main sidebar component ────────────────────────────────────────────────────
+
+interface HistorySidebarProps {
+  /** Called when a history session is clicked. */
+  onOpen: (sessionId: string, agentPath?: string | null, agentName?: string | null) => void;
+  /** session_ids of tabs already open (for highlighting). */
+  openSessionIds?: string[];
+  /** session_id of the currently active/viewed session (live backend ID). */
+  activeSessionId?: string | null;
+  /** historySourceId of the active session — the original cold session ID before revive,
+   * stays stable even after the backend creates a new live session on cold-restore. */
+  activeHistorySourceId?: string | null;
+  /** Increment this to force a refresh of the session list. */
+  refreshKey?: number;
+}
+
+export default function HistorySidebar({ onOpen, openSessionIds = [], activeSessionId, activeHistorySourceId, refreshKey }: HistorySidebarProps) {
+  const [collapsed, setCollapsed] = useState(false);
+  // Raw sessions from the backend (may contain duplicates per agent)
+  const [rawSessions, setRawSessions] = useState<HistorySession[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [labels, setLabels] = useState<Record<string, string>>(loadLabelStore);
+
+  const refresh = useCallback(() => {
+    setLoading(true);
+    sessionsApi
+      .history()
+      .then((r) => setRawSessions(r.sessions))
+      .catch(() => { })
+      .finally(() => setLoading(false));
+  }, []);
+
+  // Refresh on mount and whenever the parent forces a refresh
+  useEffect(() => {
+    refresh();
+  }, [refresh, refreshKey]);
+
+  // Refresh when the browser tab regains visibility
+  useEffect(() => {
+    const handleVisibility = () => {
+      if (document.visibilityState === "visible") refresh();
+    };
+    document.addEventListener("visibilitychange", handleVisibility);
+    return () => document.removeEventListener("visibilitychange", handleVisibility);
+  }, [refresh]);
+
+  const handleRename = (sessionId: string, newLabel: string) => {
+    const next = { ...labels, [sessionId]: newLabel };
+    setLabels(next);
+    saveLabelStore(next);
+  };
+
+  const handleDelete = (sessionId: string) => {
+    // Optimistically remove from in-memory list immediately
+    setRawSessions((prev) => prev.filter((s) => s.session_id !== sessionId));
+    const next = { ...labels };
+    delete next[sessionId];
+    setLabels(next);
+    saveLabelStore(next);
+
+    // Permanently delete session files from disk (fire-and-forget)
+    sessionsApi.deleteHistory(sessionId).catch(() => {
+      // Soft failure — the entry is already removed from the UI.
+      // The file may linger on disk, but won't appear in the next refresh
+      // because it's been removed from rawSessions.
+    });
+  };
+
+  // ── Deduplicate & render ────────────────────────────────────────────────────
+
+  // Deduplicate: show only the most-recent session per agent_path.
+  // rawSessions is already sorted newest-first by the backend.
+  const sessions = deduplicateByAgent(rawSessions);
+  const groups = groupByDate(sessions);
+
+  return (
+    <div
+      className={`flex-shrink-0 flex flex-col bg-card/20 border-r border-border/30 transition-[width] duration-200 overflow-hidden ${collapsed ? "w-[44px]" : "w-[220px]"
+        }`}
+    >
+      {/* Header */}
+      <div
+        className={`flex items-center border-b border-border/20 flex-shrink-0 h-10 ${collapsed ? "justify-center" : "px-3 gap-2"
+          }`}
+      >
+        {!collapsed && (
+          <span className="text-[11px] font-semibold text-muted-foreground/60 uppercase tracking-wider flex-1">
+            History
+          </span>
+        )}
+        <button
+          onClick={() => setCollapsed((o) => !o)}
+          className="p-1 rounded-md text-muted-foreground hover:text-foreground hover:bg-muted/50 transition-colors flex-shrink-0"
+          title={collapsed ? "Expand history" : "Collapse history"}
+        >
+          {collapsed ? (
+            <ChevronRight className="w-3.5 h-3.5" />
+          ) : (
+            <ChevronLeft className="w-3.5 h-3.5" />
+          )}
+        </button>
+      </div>
+
+      {/* Expanded list */}
+      {!collapsed && (
+        <div className="flex-1 overflow-y-auto min-h-0">
+          {loading ? (
+            <div className="flex items-center justify-center py-8">
+              <Loader2 className="w-4 h-4 animate-spin text-muted-foreground/40" />
+            </div>
+          ) : sessions.length === 0 ? (
+            <div className="px-4 py-12 text-center text-[11px] text-muted-foreground/40 leading-relaxed">
+              No previous
+              <br />
+              sessions yet
+            </div>
+          ) : (
+            groups.map(({ label: groupLabel, items }) => (
+              <div key={groupLabel}>
+                <p className="px-3 pt-4 pb-1 text-[10px] font-semibold text-muted-foreground/35 uppercase tracking-wider">
+                  {groupLabel}
+                </p>
+                {items.map((s, idx) => {
+                  const customLabel = labels[s.session_id];
+                  const computedLabel = customLabel || defaultLabel(s, idx);
+                  const isActive =
+                    s.session_id === activeSessionId ||
+                    s.session_id === activeHistorySourceId;
+                  // Mark as live if the backend flagged it OR if it's currently open in a tab
+                  const isLive = s.live || openSessionIds.includes(s.session_id);
+                  return (
+                    <HistoryRow
+                      key={s.session_id}
+                      session={s}
+                      label={computedLabel}
+                      index={idx}
+                      isActive={isActive}
+                      isLive={isLive}
+                      onOpen={() => onOpen(s.session_id, s.agent_path, s.agent_name)}
+                      onRename={(nl) => handleRename(s.session_id, nl)}
+                      onDelete={() => handleDelete(s.session_id)}
+                    />
+                  );
+                })}
+              </div>
+            ))
+          )}
+        </div>
+      )}
+
+      {/* Collapsed icon strip */}
+      {collapsed && (
+        <div className="flex-1 overflow-y-auto min-h-0 flex flex-col items-center py-2 gap-0.5">
+          {sessions.slice(0, 30).map((s) => {
+            const isLive = s.live || openSessionIds.includes(s.session_id);
+            return (
+              <button
+                key={s.session_id}
+                onClick={() => { setCollapsed(false); onOpen(s.session_id, s.agent_path, s.agent_name); }}
+                className="w-7 h-7 rounded-md flex items-center justify-center text-muted-foreground/40 hover:text-foreground hover:bg-muted/50 transition-colors relative"
+                title={labels[s.session_id] || defaultLabel(s, 0)}
+              >
+                <Clock className="w-3 h-3" />
+                {isLive && (
+                  <span className="absolute top-0.5 right-0.5 w-1.5 h-1.5 rounded-full bg-emerald-500" />
+                )}
+              </button>
+            );
+          })}
+        </div>
+      )}
+    </div>
+  );
+}

core/frontend/src/lib/tab-persistence.ts

@@ -9,7 +9,7 @@ import type { GraphNode } from "@/components/AgentGraph";
 export const TAB_STORAGE_KEY = "hive:workspace-tabs";
 
 export interface PersistedTabState {
-  tabs: Array<{ id: string; agentType: string; label: string; backendSessionId?: string }>;
+  tabs: Array<{ id: string; agentType: string; tabKey?: string; label: string; backendSessionId?: string; historySourceId?: string }>;
   activeSessionByAgent: Record<string, string>;
   activeWorker: string;
   sessions?: Record<string, { messages: ChatMessage[]; graphNodes: GraphNode[] }>;

core/frontend/src/pages/home.tsx

@@ -1,6 +1,6 @@
 import { useState, useEffect, useRef } from "react";
 import { useNavigate } from "react-router-dom";
-import { Crown, Mail, Briefcase, Shield, Search, Newspaper, ArrowRight, Hexagon, Send, Bot } from "lucide-react";
+import { Crown, Mail, Briefcase, Shield, Search, Newspaper, ArrowRight, Hexagon, Send, Bot, Radar, Reply, DollarSign, MapPin, Calendar, UserPlus, Twitter } from "lucide-react";
 import TopBar from "@/components/TopBar";
 import type { LucideIcon } from "lucide-react";
 import { agentsApi } from "@/api/agents";
@@ -14,6 +14,13 @@ const AGENT_ICONS: Record<string, LucideIcon> = {
   vulnerability_assessment: Shield,
   deep_research_agent: Search,
   tech_news_reporter: Newspaper,
+  competitive_intel_agent: Radar,
+  email_reply_agent: Reply,
+  hubspot_revenue_leak_detector: DollarSign,
+  local_business_extractor: MapPin,
+  meeting_scheduler: Calendar,
+  sdr_agent: UserPlus,
+  twitter_news_agent: Twitter,
 };
 
 const AGENT_COLORS: Record<string, string> = {
@@ -22,6 +29,13 @@ const AGENT_COLORS: Record<string, string> = {
   vulnerability_assessment: "hsl(15,70%,52%)",
   deep_research_agent: "hsl(210,70%,55%)",
   tech_news_reporter: "hsl(270,60%,55%)",
+  competitive_intel_agent: "hsl(190,70%,45%)",
+  email_reply_agent: "hsl(45,80%,55%)",
+  hubspot_revenue_leak_detector: "hsl(145,60%,42%)",
+  local_business_extractor: "hsl(350,65%,55%)",
+  meeting_scheduler: "hsl(220,65%,55%)",
+  sdr_agent: "hsl(165,55%,45%)",
+  twitter_news_agent: "hsl(200,85%,55%)",
 };
 
 function agentSlug(path: string): string {

core/frontend/src/pages/my-agents.tsx

@@ -41,11 +41,11 @@ export default function MyAgents() {
   const idleCount = agents.length - activeCount;
 
   return (
-    <div className="min-h-screen bg-background flex flex-col">
+    <div className="h-screen bg-background flex flex-col overflow-hidden">
       <TopBar />
 
       {/* Content */}
-      <div className="flex-1 p-6 md:p-10 max-w-5xl mx-auto w-full">
+      <div className="flex-1 p-6 md:p-10 max-w-5xl mx-auto w-full overflow-y-auto">
         <div className="flex items-center justify-between mb-8">
           <div>
             <h1 className="text-xl font-semibold text-foreground">My Agents</h1>

core/frontend/src/pages/workspace.tsx

@@ -8,7 +8,6 @@ import TopBar from "@/components/TopBar";
 import { TAB_STORAGE_KEY, loadPersistedTabs, savePersistedTabs, type PersistedTabState } from "@/lib/tab-persistence";
 import NodeDetailPanel from "@/components/NodeDetailPanel";
 import CredentialsModal, { type Credential, createFreshCredentials, cloneCredentials, allRequiredCredentialsMet, clearCredentialCache } from "@/components/CredentialsModal";
-
 import { agentsApi } from "@/api/agents";
 import { executionApi } from "@/api/execution";
 import { graphsApi } from "@/api/graphs";
@@ -21,6 +20,13 @@ import { ApiError } from "@/api/client";
 
 const makeId = () => Math.random().toString(36).slice(2, 9);
 
+/**
+ * Strip the instance suffix added when multiple tabs share the same agentType.
+ * e.g. "exports/deep_research::abc123" → "exports/deep_research"
+ * First-instance keys (no "::") are returned unchanged.
+ */
+const baseAgentType = (key: string): string => key.split("::")[0];
+
 /** Format seconds into a compact countdown string. */
 function formatCountdown(totalSecs: number): string {
   const h = Math.floor(totalSecs / 3600);
@@ -56,11 +62,19 @@ function TimerCountdown({ initialSeconds }: { initialSeconds: number }) {
 interface Session {
   id: string;
   agentType: string;
+  /** The key used in sessionsByAgent / agentStates for this specific tab instance.
+   * Equals agentType for the first tab; equals "agentType::frontendSessionId" for
+   * additional tabs opened for the same agent so each gets its own isolated slot. */
+  tabKey?: string;
   label: string;
   messages: ChatMessage[];
   graphNodes: GraphNode[];
   credentials: Credential[];
   backendSessionId?: string;
+  /** The cold history session ID this tab was originally opened from (if any).
+   * Used to detect "already open" even after backendSessionId is updated to a
+   * new live session ID when the cold session is revived. */
+  historySourceId?: string;
 }
 
 function createSession(agentType: string, label: string, existingCredentials?: Credential[]): Session {
@@ -301,6 +315,9 @@ export default function Workspace() {
   const rawAgent = searchParams.get("agent") || "new-agent";
   const hasExplicitAgent = searchParams.has("agent");
   const initialPrompt = searchParams.get("prompt") || "";
+  // ?session= param: when navigating from the home history sidebar, this
+  // carries the backendSessionId to open as a tab on mount.
+  const initialSessionId = searchParams.get("session") || "";
 
   // When submitting a new prompt from home for "new-agent", use a unique key
   // so each prompt gets its own tab instead of overwriting the previous one.
@@ -317,10 +334,15 @@ export default function Workspace() {
 
     if (persisted) {
       for (const tab of persisted.tabs) {
-        if (!initial[tab.agentType]) initial[tab.agentType] = [];
+        // tabKey is the actual key used in sessionsByAgent (may contain "::" suffix).
+        // Fall back to agentType for tabs persisted before this field was added.
+        const tabKey = tab.tabKey || tab.agentType;
+        if (!initial[tabKey]) initial[tabKey] = [];
         const session = createSession(tab.agentType, tab.label);
         session.id = tab.id;
         session.backendSessionId = tab.backendSessionId;
+        session.tabKey = tab.tabKey; // restore so future persistence uses correct key
+        session.historySourceId = tab.historySourceId;
         // Restore messages and graph from localStorage (up to 50 messages).
         // If the backend session is still alive, loadAgentForType may
         // append additional messages fetched from the server.
@@ -329,7 +351,7 @@ export default function Workspace() {
           session.messages = cached.messages || [];
           session.graphNodes = cached.graphNodes || [];
         }
-        initial[tab.agentType].push(session);
+        initial[tabKey].push(session);
       }
     }
 
@@ -339,6 +361,13 @@ export default function Workspace() {
       return initial;
     }
 
+    // If there are already persisted tabs for this agent type, don't create
+    // a new one — the post-mount effect will call handleHistoryOpen if needed
+    // (for ?session= params coming from the home page sidebar).
+    if (initial[initialAgent]?.length) {
+      return initial;
+    }
+
     // If the user submitted a new prompt from the home page, always create
     // a fresh session so the prompt isn't lost into an existing session.
     // initialAgent is already a unique key (e.g. "new-agent-abc123") when
@@ -352,15 +381,16 @@ export default function Workspace() {
       return initial;
     }
 
-    if (initial[initialAgent]?.length) {
-      return initial;
-    }
-
+    // Only create a fresh default tab when there are no persisted tabs at all.
+    // If ?session= was passed we intentionally do NOT create a tab here —
+    // handleHistoryOpen is called post-mount and does proper dedup.
     if (initialAgent === "new-agent") {
-      initial["new-agent"] = [...(initial["new-agent"] || []), createSession("new-agent", "New Agent")];
-    } else {
-      initial[initialAgent] = [...(initial[initialAgent] || []),
-        createSession(initialAgent, formatAgentDisplayName(initialAgent))];
+      const s = createSession("new-agent", "New Agent");
+      initial["new-agent"] = [...(initial["new-agent"] || []), s];
+    } else if (!initialSessionId) {
+      // Only auto-create an agent tab if there's no session to restore
+      const s = createSession(initialAgent, formatAgentDisplayName(initialAgent));
+      initial[initialAgent] = [...(initial[initialAgent] || []), s];
     }
 
     return initial;
@@ -368,6 +398,17 @@ export default function Workspace() {
 
   const [activeSessionByAgent, setActiveSessionByAgent] = useState<Record<string, string>>(() => {
     const persisted = loadPersistedTabs();
+    // If initialSessionId maps to an already-restored tab, activate that tab
+    if (initialSessionId) {
+      for (const [tabKey, sessions] of Object.entries(sessionsByAgent)) {
+        const match = sessions.find(
+          s => s.backendSessionId === initialSessionId || s.historySourceId === initialSessionId,
+        );
+        if (match) {
+          return { ...(persisted?.activeSessionByAgent ?? {}), [tabKey]: match.id };
+        }
+      }
+    }
     if (persisted) {
       const restored = { ...persisted.activeSessionByAgent };
       const urlSessions = sessionsByAgent[initialAgent];
@@ -387,6 +428,14 @@ export default function Workspace() {
   });
 
   const [activeWorker, setActiveWorker] = useState(() => {
+    // If initialSessionId maps to an already-restored tab, activate that key
+    if (initialSessionId) {
+      for (const [tabKey, sessions] of Object.entries(sessionsByAgent)) {
+        if (sessions.some(
+          s => s.backendSessionId === initialSessionId || s.historySourceId === initialSessionId,
+        )) return tabKey;
+      }
+    }
     if (!hasExplicitAgent) {
       const persisted = loadPersistedTabs();
       if (persisted?.activeWorker) return persisted.activeWorker;
@@ -400,6 +449,16 @@ export default function Workspace() {
     navigate("/workspace", { replace: true });
   }, []);
 
+  // Post-mount: if the URL carried a ?session= param (from the home page history
+  // sidebar), open it via handleHistoryOpen instead of creating a tab in init state.
+  // This is the single canonical path — it has robust dedup (checks backendSessionId
+  // AND historySourceId across all in-memory tabs) and is safe to call after persisted
+  // state has been hydrated.
+  // We capture initialSessionId and related URL params in stable refs so the effect
+  // only fires once on mount, regardless of re-renders.
+  const initialSessionIdRef = useRef(initialSessionId);
+  const initialAgentRef = useRef(initialAgent);
+  const mountedRef = useRef(false);
   const [credentialsOpen, setCredentialsOpen] = useState(false);
   // Explicit agent path for the credentials modal — set from 424 responses
   // when activeWorker doesn't match the actual agent (e.g. "new-agent" tab).
@@ -425,6 +484,12 @@ export default function Workspace() {
   // arrive in the same React batch.
   const turnCounterRef = useRef<Record<string, number>>({});
 
+  // Synchronous ref to suppress the queen's auto-intro SSE messages
+  // after a cold-restore (where we already restored the conversation from disk).
+  // Using a ref avoids the race condition where sessionId is set in agentState
+  // (opening SSE) before the suppressQueenIntro flag can be committed.
+  const suppressIntroRef = useRef(new Set<string>());
+
   // --- Consolidated per-agent backend state ---
   const [agentStates, setAgentStates] = useState<Record<string, AgentBackendState>>({});
 
@@ -448,11 +513,15 @@ export default function Workspace() {
     const sessions: Record<string, { messages: ChatMessage[]; graphNodes: GraphNode[] }> = {};
     for (const agentSessions of Object.values(sessionsByAgent)) {
       for (const s of agentSessions) {
+        const tKey = s.tabKey || s.agentType;
         tabs.push({
           id: s.id,
           agentType: s.agentType,
+          tabKey: s.tabKey,
           label: s.label,
-          backendSessionId: s.backendSessionId || agentStates[s.agentType]?.sessionId || undefined,
+          // agentStates is keyed by tabKey (unique per tab), not by base agentType
+          backendSessionId: s.backendSessionId || agentStates[tKey]?.sessionId || undefined,
+          ...(s.historySourceId ? { historySourceId: s.historySourceId } : {}),
         });
         sessions[s.id] = { messages: s.messages, graphNodes: s.graphNodes };
       }
@@ -518,7 +587,10 @@ export default function Workspace() {
   // --- Agent loading: loadAgentForType ---
   const loadingRef = useRef(new Set<string>());
   const loadAgentForType = useCallback(async (agentType: string) => {
-    if (agentType === "new-agent" || agentType.startsWith("new-agent-")) {
+    // agentType may be a unique composite key ("exports/foo::sessionId") for additional
+    // tabs — extract the real agent path for selector checks and API calls.
+    const agentPath = baseAgentType(agentType);
+    if (agentPath === "new-agent" || agentType.startsWith("new-agent-")) {
       // Create a queen-only session (no worker) for agent building
       updateAgentState(agentType, { loading: true, error: null, ready: false, sessionId: null });
       try {
@@ -532,17 +604,68 @@ export default function Workspace() {
 
         // Try to reconnect to stored backend session (e.g., after browser refresh)
         const storedId = activeSess?.backendSessionId;
+        // When the server restarts the session is "cold" — conversation files
+        // survive on disk but there is no live runtime.  Track the old ID so
+        // we can restore message history after creating a new session.
+        let coldRestoreId: string | undefined;
+
         if (storedId) {
           try {
-            liveSession = await sessionsApi.get(storedId);
+            const sessionData = await sessionsApi.get(storedId);
+            if (sessionData.cold) {
+              // Server restarted — files on disk, no live runtime
+              coldRestoreId = storedId;
+            } else {
+              liveSession = sessionData;
+            }
           } catch {
-            // Session gone — fall through to create new
+            // Session gone entirely (no disk files either)
           }
         }
 
+        let restoredMessageCount = 0;
+
         if (!liveSession) {
-          // Reconnect failed — clear stale cached messages from localStorage restore
-          if (storedId && activeId) {
+          // Fetch conversation history from disk BEFORE creating the new session.
+          // SKIP if messages were already pre-populated by handleHistoryOpen.
+          const restoreFrom = coldRestoreId ?? storedId;
+          const preRestoredMsgs: ChatMessage[] = [];
+          const alreadyHasMessages = (activeSess?.messages?.length ?? 0) > 0;
+          if (restoreFrom && !alreadyHasMessages) {
+            try {
+              const { messages: queenMsgs } = await sessionsApi.queenMessages(restoreFrom);
+              for (const m of queenMsgs as Message[]) {
+                const msg = backendMessageToChatMessage(m, agentType, "Queen Bee");
+                msg.role = "queen";
+                preRestoredMsgs.push(msg);
+              }
+            } catch {
+              // Not available — will start fresh
+            }
+          }
+
+          // Suppress the queen's intro cycle whenever we are about to restore a
+          // previous conversation, or whenever we have a stored session ID.
+          const willRestore = !!(restoreFrom);
+          if (willRestore || preRestoredMsgs.length > 0) suppressIntroRef.current.add(agentType);
+
+          // Pass coldRestoreId as queenResumeFrom so the backend writes queen
+          // messages into the ORIGINAL session's directory.
+          liveSession = await sessionsApi.create(undefined, undefined, undefined, prompt, coldRestoreId ?? undefined);
+
+          if (preRestoredMsgs.length > 0) {
+            preRestoredMsgs.sort((a, b) => (a.createdAt ?? 0) - (b.createdAt ?? 0));
+            if (activeId) {
+              setSessionsByAgent(prev => ({
+                ...prev,
+                [agentType]: (prev[agentType] || []).map(s =>
+                  s.id === activeId ? { ...s, messages: preRestoredMsgs, graphNodes: [] } : s,
+                ),
+              }));
+            }
+            restoredMessageCount = preRestoredMsgs.length;
+          } else if (restoreFrom && activeId) {
+            // We had a stored session but no messages on disk — wipe stale localStorage cache
             setSessionsByAgent(prev => ({
               ...prev,
               [agentType]: (prev[agentType] || []).map(s =>
@@ -551,10 +674,8 @@ export default function Workspace() {
             }));
           }
 
-          liveSession = await sessionsApi.create(undefined, undefined, undefined, prompt);
-
-          // Show the initial prompt as a user message in chat (only on fresh create)
-          if (prompt && activeId) {
+          // Show the initial prompt as a user message only on a truly fresh session
+          if (prompt && restoredMessageCount === 0 && activeId) {
             const userMsg: ChatMessage = {
               id: makeId(), agent: "You", agentColor: "",
               content: prompt, timestamp: "", type: "user", thread: agentType, createdAt: Date.now(),
@@ -568,16 +689,25 @@ export default function Workspace() {
           }
         }
 
-        // Store backendSessionId on the active Session object for persistence
+        // Store backendSessionId on the Session object for persistence.
+        // Also set historySourceId so the sidebar "already-open" check works
+        // even after cold-revive changes backendSessionId to a new live session ID.
         if (activeId) {
           setSessionsByAgent(prev => ({
             ...prev,
             [agentType]: (prev[agentType] || []).map(s =>
-              s.id === activeId ? { ...s, backendSessionId: liveSession!.session_id } : s,
+              s.id === activeId ? {
+                ...s,
+                backendSessionId: liveSession!.session_id,
+                historySourceId: s.historySourceId || coldRestoreId || undefined,
+              } : s,
             ),
           }));
         }
 
+        // If no messages were actually restored, lift the intro suppression
+        if (restoredMessageCount === 0) suppressIntroRef.current.delete(agentType);
+
         updateAgentState(agentType, {
           sessionId: liveSession.session_id,
           displayName: "Queen Bee",
@@ -601,22 +731,42 @@ export default function Workspace() {
     try {
       let liveSession: LiveSession | undefined;
       let isResumedSession = false;
+      // Set when the stored session is cold (server restarted) so we can restore
+      // messages from the old session files after creating a new live session.
+      let coldRestoreId: string | undefined;
 
       // Try to reconnect to an existing backend session (e.g., after browser refresh).
       // The backendSessionId is persisted in localStorage per tab.
-      const storedSessionId = sessionsRef.current[agentType]?.[0]?.backendSessionId;
+      // Also check historySourceId — handleHistoryOpen populates this with the
+      // original session ID from the sidebar. Use it as a fallback for stored ID.
+      const historySourceId = sessionsRef.current[agentType]?.[0]?.historySourceId;
+      const storedSessionId = sessionsRef.current[agentType]?.[0]?.backendSessionId
+        || historySourceId;
       if (storedSessionId) {
         try {
-          liveSession = await sessionsApi.get(storedSessionId);
+          const sessionData = await sessionsApi.get(storedSessionId);
+          if (sessionData.cold) {
+            // Server restarted — conversation files survive on disk, no live runtime.
+            coldRestoreId = storedSessionId;
+          } else {
+            liveSession = sessionData;
             isResumedSession = true;
+          }
         } catch {
-          // Session gone (server restarted, etc.) — fall through to create new
+          // 404: session was explicitly stopped (via closeAgentTab) but conversation
+          // files likely still exist on disk. Treat it as cold so we can restore.
+          // Verify files exist before assuming cold — if queenMessages succeeds with
+          // content, files are there.
+          coldRestoreId = historySourceId || storedSessionId;
         }
       }
 
       if (!liveSession) {
-        // Reconnect failed — clear stale cached messages from localStorage restore
-        if (storedSessionId) {
+        // Reconnect failed — clear stale cached messages from localStorage restore.
+        // NEVER wipe when: (a) doing a cold restore (we'll restore from disk) or
+        // (b) handleHistoryOpen already pre-populated messages (alreadyHasMessages).
+        const alreadyHasMessages = (sessionsRef.current[agentType] || [])[0]?.messages?.length > 0;
+        if (storedSessionId && !coldRestoreId && !alreadyHasMessages) {
           setSessionsByAgent(prev => ({
             ...prev,
             [agentType]: (prev[agentType] || []).map((s, i) =>
@@ -625,8 +775,48 @@ export default function Workspace() {
           }));
         }
 
+        // CRITICAL: Pre-fetch queen messages from the old session directory BEFORE
+        // creating the new session. When queen_resume_from is set the new session writes
+        // to the SAME directory, so if we fetch after creation we risk capturing the
+        // new queen's greeting in the restored history.
+        // SKIP if messages were already pre-populated by handleHistoryOpen (avoids
+        // double-fetch and greeting leakage).
+        let preQueenMsgs: ChatMessage[] = [];
+        if (coldRestoreId && !alreadyHasMessages) {
           try {
-          liveSession = await sessionsApi.create(agentType);
+            const { messages: queenMsgs } = await sessionsApi.queenMessages(coldRestoreId);
+            // Also pre-fetch worker messages from the old session if a resumable worker exists
+            const displayNameTemp = formatAgentDisplayName(agentPath);
+            for (const m of queenMsgs as Message[]) {
+              const msg = backendMessageToChatMessage(m, agentType, "Queen Bee");
+              msg.role = "queen";
+              preQueenMsgs.push(msg);
+            }
+            // Also try to grab worker messages while we're here
+            try {
+              const { sessions: workerSessions } = await sessionsApi.workerSessions(coldRestoreId);
+              const resumable = workerSessions.find(s => s.status === "active" || s.status === "paused");
+              if (resumable) {
+                const { messages: wMsgs } = await sessionsApi.messages(coldRestoreId, resumable.session_id);
+                for (const m of wMsgs as Message[]) {
+                  preQueenMsgs.push(backendMessageToChatMessage(m, agentType, displayNameTemp));
+                }
+              }
+            } catch { /* not critical */ }
+          } catch {
+            // Not available — will start fresh
+          }
+        }
+
+        // Suppress intro whenever we are about to restore a previous conversation.
+        // The user never expects a greeting when reopening a session.
+        if (coldRestoreId) suppressIntroRef.current.add(agentType);
+
+        try {
+          // Pass coldRestoreId as queenResumeFrom so the backend writes queen
+          // messages into the ORIGINAL session's directory — all conversation
+          // history accumulates in one place across server restarts.
+          liveSession = await sessionsApi.create(agentPath, undefined, undefined, undefined, coldRestoreId ?? undefined);
         } catch (loadErr: unknown) {
           // 424 = credentials required — open the credentials modal
           if (loadErr instanceof ApiError && loadErr.status === 424) {
@@ -671,6 +861,18 @@ export default function Workspace() {
             liveSession = body as unknown as LiveSession;
           }
         }
+
+        // If we pre-fetched messages for a cold restore, populate the UI immediately.
+        // This happens before the SSE connection opens so no greeting can slip through.
+        if (preQueenMsgs.length > 0) {
+          preQueenMsgs.sort((a, b) => (a.createdAt ?? 0) - (b.createdAt ?? 0));
+          setSessionsByAgent(prev => ({
+            ...prev,
+            [agentType]: (prev[agentType] || []).map((s, i) =>
+              i === 0 ? { ...s, messages: preQueenMsgs, graphNodes: [] } : s,
+            ),
+          }));
+        }
       }
 
       // At this point liveSession is guaranteed set — if both reconnect and create
@@ -685,31 +887,48 @@ export default function Workspace() {
         queenBuilding: initialMode === "building",
       });
 
-      // Update the session label
+      // Update the session label + backendSessionId.  Also set historySourceId
+      // so the sidebar "already-open" check works even after cold-revive changes
+      // backendSessionId to a new live session ID.
       setSessionsByAgent((prev) => {
         const sessions = prev[agentType] || [];
         if (!sessions.length) return prev;
         return {
           ...prev,
           [agentType]: sessions.map((s, i) =>
-            i === 0 ? { ...s, label: sessions.length === 1 ? displayName : `${displayName} #${i + 1}`, backendSessionId: session.session_id } : s,
+            i === 0 ? {
+              ...s,
+              // Preserve existing label if it was already set with a #N suffix by
+              // addAgentSession/handleHistoryOpen. Only overwrite with the bare
+              // displayName when the label doesn't match the resolved display name.
+              label: s.label.startsWith(displayName) ? s.label : displayName,
+              backendSessionId: session.session_id,
+              // Preserve existing historySourceId; set it from coldRestoreId if missing
+              historySourceId: s.historySourceId || coldRestoreId || undefined,
+            } : s,
           ),
         };
       });
 
-      // Check worker session status (detects running worker).
-      // Only restore messages when rejoining an existing backend session.
+      // Restore messages when rejoining an existing session OR cold-restoring from disk.
       let isWorkerRunning = false;
       const restoredMsgs: ChatMessage[] = [];
+      // For cold-restore, use the old session ID. For live resume, use current session.
+      const historyId = coldRestoreId ?? (isResumedSession ? session.session_id : undefined);
+
+      // For LIVE resume (not cold restore), fetch worker + queen messages now.
+      // For cold restore they were already pre-fetched above (before create) so we skip to avoid
+      // double-restoring and to avoid capturing the new greeting.
+      if (historyId && !coldRestoreId) {
         try {
-        const { sessions: workerSessions } = await sessionsApi.workerSessions(session.session_id);
+          const { sessions: workerSessions } = await sessionsApi.workerSessions(historyId);
           const resumable = workerSessions.find(
             (s) => s.status === "active" || s.status === "paused",
           );
           isWorkerRunning = resumable?.status === "active";
 
-        if (isResumedSession && resumable) {
-          const { messages } = await sessionsApi.messages(session.session_id, resumable.session_id);
+          if (resumable) {
+            const { messages } = await sessionsApi.messages(historyId, resumable.session_id);
             for (const m of messages as Message[]) {
               restoredMsgs.push(backendMessageToChatMessage(m, agentType, displayName));
             }
@@ -718,10 +937,8 @@ export default function Workspace() {
           // Worker session listing failed — not critical
         }
 
-      // Restore queen conversation when rejoining an existing session
-      if (isResumedSession) {
         try {
-          const { messages: queenMsgs } = await sessionsApi.queenMessages(session.session_id);
+          const { messages: queenMsgs } = await sessionsApi.queenMessages(historyId);
           for (const m of queenMsgs as Message[]) {
             const msg = backendMessageToChatMessage(m, agentType, "Queen Bee");
             msg.role = "queen";
@@ -732,7 +949,8 @@ export default function Workspace() {
         }
       }
 
-      // Merge queen + worker messages in chronological order
+      // Merge messages in chronological order (only for live resume; cold restore
+      // was already applied above before create).
       if (restoredMsgs.length > 0) {
         restoredMsgs.sort((a, b) => (a.createdAt ?? 0) - (b.createdAt ?? 0));
         setSessionsByAgent((prev) => ({
@@ -743,7 +961,12 @@ export default function Workspace() {
         }));
       }
 
+      // If no messages were actually restored, lift the intro suppression gate
+      if (restoredMsgs.length === 0 && !coldRestoreId) suppressIntroRef.current.delete(agentType);
+
       updateAgentState(agentType, {
+        sessionId: session.session_id,
+        displayName,
         ready: true,
         loading: false,
         queenReady: true,
@@ -1017,6 +1240,9 @@ export default function Workspace() {
 
       const isQueen = streamId === "queen";
       if (isQueen) console.log('[QUEEN] handleSSEEvent:', event.type, 'agentType:', agentType);
+      // Drop queen message content while suppressing the auto-intro after a cold-restore.
+      // Uses a synchronous ref to avoid race conditions with React state batching.
+      const suppressQueenMessages = isQueen && suppressIntroRef.current.has(agentType);
       const agentDisplayName = agentStates[agentType]?.displayName;
       const displayName = isQueen ? "Queen Bee" : (agentDisplayName || undefined);
       const role = isQueen ? "queen" as const : "worker" as const;
@@ -1068,6 +1294,7 @@ export default function Workspace() {
 
         case "execution_completed":
           if (isQueen) {
+            suppressIntroRef.current.delete(agentType);
             updateAgentState(agentType, { isTyping: false, queenIsTyping: false });
           } else {
             // Flush any remaining LLM snapshots before clearing state
@@ -1106,7 +1333,7 @@ export default function Workspace() {
         case "llm_text_delta": {
           const chatMsg = sseEventToChatMessage(event, agentType, displayName, currentTurn);
           if (isQueen) console.log('[QUEEN] chatMsg:', chatMsg?.id, chatMsg?.content?.slice(0, 50), 'turn:', currentTurn);
-          if (chatMsg) {
+          if (chatMsg && !suppressQueenMessages) {
             if (isQueen) chatMsg.role = role;
             upsertChatMessage(agentType, chatMsg);
           }
@@ -1149,16 +1376,19 @@ export default function Workspace() {
                 const cur = prev[agentType] || defaultAgentState();
                 const workerQuestionActive = cur.pendingQuestionSource === "worker";
                 if (isAutoBlock && workerQuestionActive) {
-                  return { ...prev, [agentType]: {
+                  return {
+                    ...prev, [agentType]: {
                       ...cur,
                       awaitingInput: true,
                       isTyping: false,
                       isStreaming: false,
                       queenIsTyping: false,
                       queenBuilding: false,
-                  }};
                     }
-                return { ...prev, [agentType]: {
+                  };
+                }
+                return {
+                  ...prev, [agentType]: {
                     ...cur,
                     awaitingInput: true,
                     isTyping: false,
@@ -1168,7 +1398,8 @@ export default function Workspace() {
                     pendingQuestion: prompt || null,
                     pendingOptions: options,
                     pendingQuestionSource: "queen",
-                }};
+                  }
+                };
               });
             } else {
               // Worker input request.
@@ -1200,7 +1431,7 @@ export default function Workspace() {
                 queenIsTyping: false,
                 pendingQuestion: prompt || null,
                 pendingOptions: options,
-                pendingQuestionSource: options ? "worker" : null,
+                pendingQuestionSource: "worker",
               });
             }
           }
@@ -1547,13 +1778,13 @@ export default function Workspace() {
         case "worker_loaded": {
           const workerName = event.data?.worker_name as string | undefined;
           const agentPathFromEvent = event.data?.agent_path as string | undefined;
-          const displayName = formatAgentDisplayName(workerName || agentType);
+          const displayName = formatAgentDisplayName(workerName || baseAgentType(agentType));
 
           // Invalidate cached credential requirements so the modal fetches
           // fresh data the next time it opens (the new agent may have
           // different credential needs than the previous one).
           clearCredentialCache(agentPathFromEvent);
-          clearCredentialCache(agentType);
+          clearCredentialCache(baseAgentType(agentType));
 
           // Update agent state: new display name, reset graph so topology refetch triggers
           updateAgentState(agentType, {
@@ -1564,15 +1795,17 @@ export default function Workspace() {
             nodeSpecs: [],
           });
 
-          // Update session label (tab name) and clear graph nodes for fresh fetch
+          // Update ONLY the active session's label + graph nodes — never touch
+          // sessions belonging to a different tab sharing the same agentType key.
+          // Also clear worker messages so the fresh worker starts with a clean slate.
+          const activeId = activeSessionRef.current[agentType];
           setSessionsByAgent(prev => ({
             ...prev,
-            [agentType]: (prev[agentType] || []).map(s => ({
-              ...s,
-              label: displayName,
-              graphNodes: [],
-              messages: s.messages.filter(m => m.role !== "worker"),
-            })),
+            [agentType]: (prev[agentType] || []).map(s =>
+              s.id === activeId || (!activeId && prev[agentType]?.[0]?.id === s.id)
+                ? { ...s, label: displayName, graphNodes: [], messages: s.messages.filter(m => m.role !== "worker") }
+                : s
+            ),
           }));
 
           // Explicitly fetch graph topology for the newly loaded worker
@@ -1610,7 +1843,7 @@ export default function Workspace() {
   const activeSession = currentSessions.find(s => s.id === activeSessionId) || currentSessions[0];
 
   const currentGraph = activeSession
-    ? { nodes: activeSession.graphNodes, title: activeAgentState?.displayName || formatAgentDisplayName(activeWorker) }
+    ? { nodes: activeSession.graphNodes, title: activeAgentState?.displayName || formatAgentDisplayName(baseAgentType(activeWorker)) }
     : { nodes: [] as GraphNode[], title: "" };
 
   // Build a flat list of all agent-type tabs for the tab bar
@@ -1652,6 +1885,41 @@ export default function Workspace() {
       return;
     }
 
+    // If worker is awaiting free-text input (no options / no QuestionWidget),
+    // route the message directly to the worker instead of the queen.
+    if (agentStates[activeWorker]?.awaitingInput && agentStates[activeWorker]?.pendingQuestionSource === "worker" && !agentStates[activeWorker]?.pendingOptions) {
+      const state = agentStates[activeWorker];
+      if (state?.sessionId && state?.ready) {
+        const userMsg: ChatMessage = {
+          id: makeId(), agent: "You", agentColor: "",
+          content: text, timestamp: "", type: "user", thread, createdAt: Date.now(),
+        };
+        setSessionsByAgent(prev => ({
+          ...prev,
+          [activeWorker]: prev[activeWorker].map(s =>
+            s.id === activeSession.id ? { ...s, messages: [...s.messages, userMsg] } : s
+          ),
+        }));
+        updateAgentState(activeWorker, { awaitingInput: false, workerInputMessageId: null, isTyping: true, pendingQuestion: null, pendingOptions: null, pendingQuestionSource: null });
+        executionApi.workerInput(state.sessionId, text).catch((err: unknown) => {
+          const errMsg = err instanceof Error ? err.message : String(err);
+          const errorChatMsg: ChatMessage = {
+            id: makeId(), agent: "System", agentColor: "",
+            content: `Failed to send to worker: ${errMsg}`,
+            timestamp: "", type: "system", thread, createdAt: Date.now(),
+          };
+          setSessionsByAgent(prev => ({
+            ...prev,
+            [activeWorker]: prev[activeWorker].map(s =>
+              s.id === activeSession.id ? { ...s, messages: [...s.messages, errorChatMsg] } : s
+            ),
+          }));
+          updateAgentState(activeWorker, { isTyping: false, isStreaming: false });
+        });
+      }
+      return;
+    }
+
     // If queen has a pending question widget, dismiss it when user types directly
     if (agentStates[activeWorker]?.pendingQuestionSource === "queen") {
       updateAgentState(activeWorker, { pendingQuestion: null, pendingOptions: null, pendingQuestionSource: null });
@@ -1667,6 +1935,7 @@ export default function Workspace() {
         s.id === activeSession.id ? { ...s, messages: [...s.messages, userMsg] } : s
       ),
     }));
+    suppressIntroRef.current.delete(activeWorker);
     updateAgentState(activeWorker, { isTyping: true, queenIsTyping: true });
 
     if (state?.sessionId && state?.ready) {
@@ -1901,22 +2170,128 @@ export default function Workspace() {
 
   // Create a new session for any agent type (used by NewTabPopover)
   const addAgentSession = useCallback((agentType: string, agentLabel?: string) => {
-    const sessions = sessionsByAgent[agentType] || [];
-    const newIndex = sessions.length + 1;
-    const existingCreds = sessions.length > 0 ? sessions[0].credentials : undefined;
+    // Count all existing open tabs for this base agent type (first tab uses agentType
+    // as key; subsequent tabs use "agentType::frontendSessionId" as unique keys).
+    const existingTabCount = Object.keys(sessionsByAgent).filter(
+      k => baseAgentType(k) === agentType && (sessionsByAgent[k] || []).length > 0,
+    ).length;
+
+    const newIndex = existingTabCount + 1;
+    const existingCreds = sessionsByAgent[agentType]?.[0]?.credentials;
     const displayLabel = agentLabel || formatAgentDisplayName(agentType);
     const label = newIndex === 1 ? displayLabel : `${displayLabel} #${newIndex}`;
     const newSession = createSession(agentType, label, existingCreds);
 
+    // First tab keeps agentType as its key (backward-compatible with all existing
+    // logic).  Additional tabs get a unique key so each has its own isolated
+    // agentStates slot, its own backend session, and its own tab-bar entry.
+    const tabKey = existingTabCount === 0 ? agentType : `${agentType}::${newSession.id}`;
+    if (tabKey !== agentType) {
+      newSession.tabKey = tabKey;
+    }
+
     setSessionsByAgent(prev => ({
       ...prev,
-      [agentType]: [...(prev[agentType] || []), newSession],
+      [tabKey]: [newSession],
     }));
-    setActiveSessionByAgent(prev => ({ ...prev, [agentType]: newSession.id }));
-    setActiveWorker(agentType);
+    setActiveSessionByAgent(prev => ({ ...prev, [tabKey]: newSession.id }));
+    setActiveWorker(tabKey);
   }, [sessionsByAgent]);
 
-  const activeWorkerLabel = activeAgentState?.displayName || formatAgentDisplayName(activeWorker);
+  // Open a history session: switch to its existing tab, or open a new tab.
+  // Async so we can pre-fetch messages before creating the tab — this gives
+  // instant visual feedback without waiting for loadAgentForType.
+  const handleHistoryOpen = useCallback(async (sessionId: string, agentPath?: string | null, agentName?: string | null) => {
+    // Already open as a tab — just switch to it.
+    for (const [type, sessions] of Object.entries(sessionsByAgent)) {
+      for (const s of sessions) {
+        if (s.backendSessionId === sessionId || s.historySourceId === sessionId) {
+          setActiveWorker(type);
+          setActiveSessionByAgent(prev => ({ ...prev, [type]: s.id }));
+          if (s.messages.length > 0) {
+            suppressIntroRef.current.add(type);
+          }
+          return;
+        }
+      }
+    }
+
+    // Pre-fetch messages from disk so the tab opens with conversation already shown.
+    // This happens BEFORE creating the tab so no "new session" empty state is visible.
+    let prefetchedMessages: ChatMessage[] = [];
+    try {
+      const { messages: queenMsgs } = await sessionsApi.queenMessages(sessionId);
+      for (const m of queenMsgs as Message[]) {
+        const resolvedType = agentPath || "new-agent";
+        const msg = backendMessageToChatMessage(m, resolvedType, "Queen Bee");
+        msg.role = "queen";
+        prefetchedMessages.push(msg);
+      }
+      if (prefetchedMessages.length > 0) {
+        prefetchedMessages.sort((a, b) => (a.createdAt ?? 0) - (b.createdAt ?? 0));
+      }
+    } catch {
+      // Not available — session will open empty and loadAgentForType will try again
+    }
+
+    const resolvedAgentType = agentPath || "new-agent";
+    const existingTabCount = Object.keys(sessionsByAgent).filter(
+      k => baseAgentType(k) === resolvedAgentType && (sessionsByAgent[k] || []).length > 0
+    ).length;
+    const rawLabel = agentName ||
+      (agentPath ? agentPath.replace(/\/$/, "").split("/").pop()?.replace(/_/g, " ").replace(/\b\w/g, c => c.toUpperCase()) || agentPath : null) ||
+      "New Agent";
+    const label = existingTabCount === 0 ? rawLabel : `${rawLabel} #${existingTabCount + 1}`;
+    const newSession = createSession(resolvedAgentType, label);
+    newSession.backendSessionId = sessionId;
+    newSession.historySourceId = sessionId;
+    // Pre-populate messages so the chat panel immediately shows the conversation
+    if (prefetchedMessages.length > 0) {
+      newSession.messages = prefetchedMessages;
+    }
+    const tabKey = existingTabCount === 0 ? resolvedAgentType : `${resolvedAgentType}::${newSession.id}`;
+    if (tabKey !== resolvedAgentType) newSession.tabKey = tabKey;
+
+    // Suppress queen intro BEFORE the tab is created so loadAgentForType
+    // never sees an unsuppressed window — the user never expects a greeting on reopen.
+    if (prefetchedMessages.length > 0 || sessionId) {
+      suppressIntroRef.current.add(tabKey);
+    }
+
+    setSessionsByAgent(prev => ({ ...prev, [tabKey]: [newSession] }));
+    setActiveSessionByAgent(prev => ({ ...prev, [tabKey]: newSession.id }));
+    setActiveWorker(tabKey);
+  }, [sessionsByAgent]);
+
+  // Post-mount: open the session from the URL ?session= param via handleHistoryOpen.
+  // This runs AFTER persisted tabs are hydrated, so dedup works correctly.
+  // Use a ref guard so it fires exactly once even in React StrictMode.
+  useEffect(() => {
+    if (mountedRef.current) return;
+    mountedRef.current = true;
+    const sid = initialSessionIdRef.current;
+    if (!sid) return;
+    // Fetch agent metadata from the backend so handleHistoryOpen gets the right
+    // agentPath and agentName (needed to label the tab correctly).
+    sessionsApi.history().then(r => {
+      const match = r.sessions.find((s: { session_id: string }) => s.session_id === sid);
+      handleHistoryOpen(
+        sid,
+        match?.agent_path ?? initialAgentRef.current !== "new-agent" ? initialAgentRef.current : null,
+        match?.agent_name ?? null,
+      );
+    }).catch(() => {
+      // History fetch failed — still open the session with what we know.
+      handleHistoryOpen(
+        sid,
+        initialAgentRef.current !== "new-agent" ? initialAgentRef.current : null,
+        null,
+      );
+    });
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  const activeWorkerLabel = activeAgentState?.displayName || formatAgentDisplayName(baseAgentType(activeWorker));
 
 
   return (
@@ -1965,7 +2340,9 @@ export default function Workspace() {
 
       {/* Main content area */}
       <div className="flex flex-1 min-h-0">
-        <div className="w-[340px] min-w-[280px] bg-card/30 flex flex-col border-r border-border/30">
+
+        {/* ── Pipeline graph + chat ──────────────────────────────────── */}
+        <div className="w-[300px] min-w-[240px] bg-card/30 flex flex-col border-r border-border/30">
           <div className="flex-1 min-h-0">
             <AgentGraph
               nodes={currentGraph.nodes}

core/setup_mcp.py

@@ -53,7 +53,13 @@ def log_error(message: str):
 def run_command(cmd: list, error_msg: str) -> bool:
     """Run a command and return success status."""
     try:
-        subprocess.run(cmd, check=True, capture_output=True, text=True)
+        subprocess.run(
+            cmd,
+            check=True,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+        )
         return True
     except subprocess.CalledProcessError as e:
         log_error(error_msg)
@@ -97,7 +103,7 @@ def main():
     if mcp_config_path.exists():
         log_success("MCP configuration found at .mcp.json")
         logger.info("Configuration:")
-        with open(mcp_config_path) as f:
+        with open(mcp_config_path, encoding="utf-8") as f:
             config = json.load(f)
             logger.info(json.dumps(config, indent=2))
     else:
@@ -114,7 +120,7 @@ def main():
             }
         }
 
-        with open(mcp_config_path, "w") as f:
+        with open(mcp_config_path, "w", encoding="utf-8") as f:
             json.dump(config, f, indent=2)
 
         log_success("Created .mcp.json")
@@ -129,6 +135,7 @@ def main():
             check=True,
             capture_output=True,
             text=True,
+            encoding="utf-8",
         )
         log_success("MCP server module verified")
     except subprocess.CalledProcessError as e:

core/tests/test_cli_entry_point.py

@@ -68,6 +68,7 @@ class TestFrameworkModule:
             [sys.executable, "-m", "framework", "--help"],
             capture_output=True,
             text=True,
+            encoding="utf-8",
             cwd=str(project_root / "core"),
         )
         assert result.returncode == 0
@@ -79,6 +80,7 @@ class TestFrameworkModule:
             [sys.executable, "-m", "framework", "list", "--help"],
             capture_output=True,
             text=True,
+            encoding="utf-8",
             cwd=str(project_root / "core"),
         )
         assert result.returncode == 0
@@ -104,6 +106,7 @@ class TestHiveEntryPoint:
             ["hive", "--help"],
             capture_output=True,
             text=True,
+            encoding="utf-8",
         )
         assert result.returncode == 0
         assert "run" in result.stdout.lower()
@@ -115,6 +118,7 @@ class TestHiveEntryPoint:
             ["hive", "list", "--help"],
             capture_output=True,
             text=True,
+            encoding="utf-8",
         )
         assert result.returncode == 0
 
@@ -124,5 +128,6 @@ class TestHiveEntryPoint:
             ["hive", "run", "nonexistent_agent_xyz"],
             capture_output=True,
             text=True,
+            encoding="utf-8",
         )
         assert result.returncode != 0

core/tests/test_execution_stream.py

@@ -232,7 +232,7 @@ async def test_shared_session_reuses_directory_and_memory(tmp_path):
     # Verify primary session's state.json exists and has the primary entry_point
     primary_state_path = tmp_path / "sessions" / primary_exec_id / "state.json"
     assert primary_state_path.exists()
-    primary_state = json.loads(primary_state_path.read_text())
+    primary_state = json.loads(primary_state_path.read_text(encoding="utf-8"))
     assert primary_state["entry_point"] == "primary"
 
     # Async stream — simulates a webhook entry point sharing the session
@@ -275,7 +275,7 @@ async def test_shared_session_reuses_directory_and_memory(tmp_path):
 
     # State.json should NOT have been overwritten by the async execution
     # (it should still show the primary entry point)
-    final_state = json.loads(primary_state_path.read_text())
+    final_state = json.loads(primary_state_path.read_text(encoding="utf-8"))
     assert final_state["entry_point"] == "primary"
 
     # Verify only ONE session directory exists (not two)

core/tests/test_path_traversal_fix.py

@@ -184,7 +184,7 @@ class TestPathTraversalWithActualFiles:
 
             # Create a secret file outside storage
             secret_file = tmpdir_path / "secret.txt"
-            secret_file.write_text("SENSITIVE_DATA")
+            secret_file.write_text("SENSITIVE_DATA", encoding="utf-8")
 
             storage = FileStorage(storage_dir)
 
@@ -193,7 +193,7 @@ class TestPathTraversalWithActualFiles:
                 storage.get_runs_by_goal("../secret")
 
             # Verify the secret file was not accessed (still contains original data)
-            assert secret_file.read_text() == "SENSITIVE_DATA"
+            assert secret_file.read_text(encoding="utf-8") == "SENSITIVE_DATA"
 
     def test_cannot_write_outside_storage(self):
         """Verify that we can't write files outside storage directory."""

core/tests/test_runtime_logger.py

@@ -353,7 +353,9 @@ class TestRuntimeLogger:
         # Verify the file exists and has one line
         jsonl_path = tmp_path / "logs" / "sessions" / run_id / "logs" / "tool_logs.jsonl"
         assert jsonl_path.exists()
-        lines = [line for line in jsonl_path.read_text().strip().split("\n") if line]
+        lines = [
+            line for line in jsonl_path.read_text(encoding="utf-8").strip().split("\n") if line
+        ]
         assert len(lines) == 1
 
         data = json.loads(lines[0])
@@ -376,7 +378,8 @@ class TestRuntimeLogger:
 
         jsonl_path = tmp_path / "logs" / "sessions" / run_id / "logs" / "details.jsonl"
         assert jsonl_path.exists()
-        lines = [line for line in jsonl_path.read_text().strip().split("\n") if line]
+        content = jsonl_path.read_text(encoding="utf-8").strip()
+        lines = [line for line in content.split("\n") if line]
         assert len(lines) == 1
 
         data = json.loads(lines[0])

core/tests/test_storage.py

@@ -98,7 +98,7 @@ class TestFileStorageRunOperations:
         assert run_file.exists()
 
         # Verify it's valid JSON
-        with open(run_file) as f:
+        with open(run_file, encoding="utf-8") as f:
             data = json.load(f)
         assert data["id"] == "my_run"
 

core/verify_mcp.py

@@ -71,6 +71,7 @@ def main():
             capture_output=True,
             text=True,
             check=True,
+            encoding="utf-8",
         )
         framework_path = result.stdout.strip()
         success(f"installed at {framework_path}")
@@ -84,7 +85,12 @@ def main():
     missing_deps = []
     for dep in ["mcp", "fastmcp"]:
         try:
-            subprocess.run([sys.executable, "-c", f"import {dep}"], capture_output=True, check=True)
+            subprocess.run(
+                [sys.executable, "-c", f"import {dep}"],
+                capture_output=True,
+                check=True,
+                encoding="utf-8",
+            )
         except subprocess.CalledProcessError:
             missing_deps.append(dep)
 
@@ -103,6 +109,7 @@ def main():
             capture_output=True,
             text=True,
             check=True,
+            encoding="utf-8",
         )
         success("loads successfully")
     except subprocess.CalledProcessError as e:
@@ -115,7 +122,7 @@ def main():
     mcp_config = script_dir / ".mcp.json"
     if mcp_config.exists():
         try:
-            with open(mcp_config) as f:
+            with open(mcp_config, encoding="utf-8") as f:
                 config = json.load(f)
 
             if "mcpServers" in config and "agent-builder" in config["mcpServers"]:
@@ -149,7 +156,10 @@ def main():
     for module in modules_to_check:
         try:
             subprocess.run(
-                [sys.executable, "-c", f"import {module}"], capture_output=True, check=True
+                [sys.executable, "-c", f"import {module}"],
+                capture_output=True,
+                check=True,
+                encoding="utf-8",
             )
         except subprocess.CalledProcessError:
             failed_modules.append(module)
@@ -174,6 +184,7 @@ def main():
             text=True,
             check=True,
             timeout=5,
+            encoding="utf-8",
         )
         if "OK" in result.stdout:
             success("server can start")

docs/getting-started.md

@@ -27,8 +27,22 @@ uv run python -c "import framework; import aden_tools; print('✓ Setup complete
 
 ## Building Your First Agent
 
+Agents are not included by default in a fresh clone.
+
+Agents are created using Claude Code or by manual creation in the
+exports/ directory. Until an agent exists, agent validation and run
+commands will fail.
+
 ### Option 1: Using Claude Code Skills (Recommended)
 
+This is the recommended way to create your first agent.
+
+**Requirements**
+
+- Anthropic (Claude) API access
+- Claude Code CLI installed
+- Unix-based shell (macOS, Linux, or Windows via WSL)
+
 ```bash
 # Setup already done via quickstart.sh above
 
@@ -120,7 +134,10 @@ hive/
 ## Running an Agent
 
 ```bash
-# Browse and run agents interactively (Recommended)
+# Launch the web dashboard in your browser
+hive open
+
+# Browse and run agents in terminal
 hive tui
 
 # Run a specific agent
@@ -164,7 +181,7 @@ PYTHONPATH=exports uv run python -m my_agent test --type success
 
 ## Next Steps
 
-1. **TUI Dashboard**: Run `hive tui` to explore agents interactively
+1. **Dashboard**: Run `hive open` to launch the web dashboard, or `hive tui` for the terminal UI
 2. **Detailed Setup**: See [environment-setup.md](./environment-setup.md)
 3. **Developer Guide**: See [developer-guide.md](./developer-guide.md)
 4. **Build Agents**: Use `/hive` skill in Claude Code

docs/hive-coder-meta-agent-plan.md

@@ -37,8 +37,6 @@ Ported from `agent_builder_server.py` lines 3484-3856. Pure filesystem reads —
 | Tool | Purpose |
 |------|---------|
 | `list_agent_sessions(agent_name, status?, limit?)` | List sessions, filterable by status |
-| `get_agent_session_state(agent_name, session_id)` | Full session state (memory excluded to prevent context bloat) |
-| `get_agent_session_memory(agent_name, session_id, key?)` | Read memory contents from a session |
 | `list_agent_checkpoints(agent_name, session_id)` | List checkpoints for debugging |
 | `get_agent_checkpoint(agent_name, session_id, checkpoint_id?)` | Load a checkpoint's full state |
 
@@ -67,7 +65,7 @@ Add all 8 tools after the existing `undo_changes` tool:
 
 # ── Meta-agent: Session & checkpoint inspection ───────────────
 # _resolve_hive_agent_path(), _read_session_json(), _scan_agent_sessions(), _truncate_value()
-# list_agent_sessions(), get_agent_session_state(), get_agent_session_memory()
+# list_agent_sessions(), list_agent_checkpoints(), get_agent_checkpoint()
 # list_agent_checkpoints(), get_agent_checkpoint()
 
 # ── Meta-agent: Test execution ────────────────────────────────

docs/issue-queen-bee.md

@@ -43,7 +43,7 @@ Dedicated tool server providing:
 - **File I/O**: `read_file` (with line numbers, offset/limit), `write_file` (auto-mkdir), `edit_file` (9-strategy fuzzy matching ported from opencode), `list_directory`, `search_files` (regex)
 - **Shell**: `run_command` (timeout, cwd, output truncation)
 - **Git**: `undo_changes` (snapshot-based rollback)
-- **Meta-agent**: `discover_mcp_tools`, `list_agents`, `list_agent_sessions`, `get_agent_session_state`, `get_agent_session_memory`, `list_agent_checkpoints`, `get_agent_checkpoint`, `run_agent_tests`
+- **Meta-agent**: `discover_mcp_tools`, `list_agents`, `list_agent_sessions`, `list_agent_checkpoints`, `get_agent_checkpoint`, `run_agent_tests`
 
 All file operations sandboxed to a configurable project root.
 

docs/pr-queen-bee.md

@@ -16,7 +16,7 @@ The agent is deeply integrated with the framework: it can discover available MCP
 - **`reference/`** — Framework guide, file templates, and anti-patterns docs embedded as agent reference material
 
 ### New: Coder Tools MCP Server (`tools/coder_tools_server.py`)
-- 1500-line MCP server providing 15 tools: `read_file`, `write_file`, `edit_file` (with opencode-style 9-strategy fuzzy matching), `list_directory`, `search_files`, `run_command`, `undo_changes`, `discover_mcp_tools`, `list_agents`, `list_agent_sessions`, `get_agent_session_state`, `get_agent_session_memory`, `list_agent_checkpoints`, `get_agent_checkpoint`, `run_agent_tests`
+- 1500-line MCP server providing 13 tools: `read_file`, `write_file`, `edit_file` (with opencode-style 9-strategy fuzzy matching), `list_directory`, `search_files`, `run_command`, `undo_changes`, `discover_mcp_tools`, `list_agents`, `list_agent_sessions`, `list_agent_checkpoints`, `get_agent_checkpoint`, `run_agent_tests`
 - Path-scoped security: all file operations sandboxed to project root
 - Git-based undo: automatic snapshots before writes with `undo_changes` rollback
 

docs/roadmap.md

@@ -145,7 +145,7 @@ Implement the core execution engine where every Agent operates as an isolated, a
     - [x] SharedState manager (runtime/shared_state.py)
     - [x] Session-based storage (storage/session_store.py)
     - [x] Isolation levels: ISOLATED, SHARED, SYNCHRONIZED
-- [ ] **Default Monitoring Hooks**
+- [x] **Default Monitoring Hooks**
     - [ ] Performance metrics collection
     - [ ] Resource usage tracking
     - [ ] Health check endpoints
@@ -590,7 +590,7 @@ Write the Quick Start guide, detailed tool usage documentation, and set up the M
     - [x] README with examples
     - [x] Contributing guidelines
     - [x] GitHub Page setup
-- [ ] **Tool Usage Documentation**
+- [x] **Tool Usage Documentation**
     - [ ] Comprehensive tool documentation
     - [ ] Tool integration examples
     - [ ] Best practices guide
@@ -643,7 +643,7 @@ Expose basic REST/WebSocket endpoints for external control (Start, Stop, Pause,
     - [x] Load/unload/start/restart in AgentRuntime
     - [x] State persistence
     - [x] Recovery mechanisms
-- [ ] **REST API Endpoints**
+- [x] **REST API Endpoints**
     - [ ] Start endpoint for agent execution
     - [ ] Stop endpoint for graceful shutdown
     - [ ] Pause endpoint for execution suspension
@@ -661,7 +661,7 @@ Implement automated test execution, agent version control, and mandatory test-pa
     - [x] Test framework with pytest integration (testing/)
     - [x] Test result reporting
     - [x] Test CLI commands (test-run, test-debug, etc.)
-- [ ] **Automated Testing Pipeline**
+- [x] **Automated Testing Pipeline**
     - [ ] CI integration (GitHub Actions, etc.)
     - [ ] Mandatory test-passing gates
     - [ ] Coverage reporting
@@ -873,7 +873,7 @@ Build native frontend configurations to easily connect Open Hive's backend to lo
     - [ ] Node.js runtime support
     - [ ] Browser runtime support
 - [ ] **Platform Compatibility**
-    - [ ] Windows support improvements
+    - [x] Windows support improvements
     - [ ] macOS optimization
     - [ ] Linux distribution support
 

docs/tools.md

@@ -0,0 +1,78 @@
+# Tools
+
+Hive agents interact with external services through **tools** — functions exposed via MCP (Model Context Protocol) servers. The main tool server lives at `tools/mcp_server.py` and registers integrations from the `aden_tools` package.
+
+## Verified vs Unverified
+
+Tools are split into two tiers:
+
+| Tier | Description | Default |
+|------|-------------|---------|
+| **Verified** | Stable integrations tested on main. Always loaded. | On |
+| **Unverified** | New or community integrations pending full review. | Off |
+
+Verified tools include core capabilities like web search, GitHub, email, file system operations, and security scanners. Unverified tools cover newer integrations like Jira, Notion, Salesforce, Snowflake, and others that are functional but haven't completed the full review process.
+
+## Enabling Unverified Tools
+
+Set the `INCLUDE_UNVERIFIED_TOOLS` environment variable to opt in:
+
+```bash
+# Shell
+INCLUDE_UNVERIFIED_TOOLS=true uv run python tools/mcp_server.py --stdio
+```
+
+### In `mcp_servers.json`
+
+When configuring an agent's MCP server, pass the env var in the server config:
+
+```json
+{
+  "servers": [
+    {
+      "name": "tools",
+      "transport": "stdio",
+      "command": "uv",
+      "args": ["run", "python", "tools/mcp_server.py", "--stdio"],
+      "env": {
+        "INCLUDE_UNVERIFIED_TOOLS": "true"
+      }
+    }
+  ]
+}
+```
+
+### In Docker
+
+```bash
+docker run -e INCLUDE_UNVERIFIED_TOOLS=true ...
+```
+
+### In Python
+
+If calling `register_all_tools` directly (e.g., in a custom server):
+
+```python
+from aden_tools.tools import register_all_tools
+
+register_all_tools(mcp, credentials=credentials, include_unverified=True)
+```
+
+Accepted values: `true`, `1`, `yes` (case-insensitive). Any other value or unset means off.
+
+## Listing Available Tools
+
+The MCP server logs registered tools at startup (HTTP mode):
+
+```bash
+uv run python tools/mcp_server.py
+# [MCP] Registered 47 tools: [...]
+```
+
+In STDIO mode, logs go to stderr to keep stdout clean for JSON-RPC.
+
+## Adding a New Tool
+
+New tool integrations are added to `tools/src/aden_tools/tools/` and registered in `_register_unverified()` in `tools/src/aden_tools/tools/__init__.py`. Once reviewed and stabilized, they graduate to `_register_verified()`.
+
+See the [developer guide](developer-guide.md) for the full contribution workflow.

docs/tui-selection-guide.md

@@ -1,59 +0,0 @@
-# TUI Dashboard Guide
-
-## Launching the TUI
-
-There are two ways to launch the TUI dashboard:
-
-```bash
-# Browse and select an agent interactively
-hive tui
-
-# Launch the TUI for a specific agent
-hive run exports/my_agent --tui
-```
-
-`hive tui` scans both `exports/` and `examples/templates/` for available agents, then presents a selection menu.
-
-## Dashboard Panels
-
-The TUI dashboard is divided into four areas:
-
-- **Status Bar** - Shows the current agent name, execution state, and model in use
-- **Graph Overview** - Live visualization of the agent's node graph with highlighted active node
-- **Log Pane** - Scrollable event log streaming node transitions, LLM calls, and tool outputs
-- **Chat REPL** - Input area for interacting with client-facing nodes (`ask_user()` prompts appear here)
-
-## Keybindings
-
-| Key           | Action                |
-|---------------|-----------------------|
-| `Tab`         | Next panel            |
-| `Shift+Tab`   | Previous panel        |
-| `Ctrl+S`      | Save SVG screenshot   |
-| `Ctrl+O`      | Command palette       |
-| `Q`           | Quit                  |
-
-## Panel Cycle Order
-
-`Tab` cycles: **Log Pane → Graph View → Chat Input**
-
-## Text Selection
-
-Textual apps capture the mouse, so normal click-drag selection won't work by default. To select and copy text from any pane:
-
-1. **Hold `Shift`** while clicking and dragging — this bypasses Textual's mouse capture and lets your terminal handle selection natively.
-2. Copy with your terminal's shortcut (`Cmd+C` on macOS, `Ctrl+Shift+C` on most Linux terminals).
-
-## Log Pane Scrolling
-
-The log pane uses `auto_scroll=False`. New output only scrolls to the bottom when you are already at the bottom of the log. If you've scrolled up to read earlier output, it stays in place.
-
-## Screenshots
-
-`Ctrl+S` saves an SVG screenshot to the `screenshots/` directory with a timestamped filename. Open the SVG in any browser to view it.
-
-## Tips
-
-- Use `--mock` mode to explore agent execution without spending API credits: `hive run exports/my_agent --tui --mock`
-- Override the default model with `--model`: `hive run exports/my_agent --model gpt-4o`
-- Screenshots are saved as SVG files to `screenshots/` and can be opened in any browser

docs/worker-health-monitoring.md

@@ -191,7 +191,7 @@ Both events are handled in the cross-graph filter (events from non-active graphs
 
 ## Known Gaps
 
-**Gap 1 — Resolved.** The queen is now the full `HiveCoderAgent` graph (not a minimal hand-assembled subset). `_load_judge_and_queen` calls `HiveCoderAgent._setup(mock_mode=True)` to load hive-tools MCP, then merges those tools into the worker runtime alongside monitoring tools. When the operator connects via Ctrl+Q, they get `coder_node` with `read_file`, `write_file`, `run_command`, `restart_agent`, `get_agent_session_state`, and all other hive-tools. The `ticket_triage_node` still handles auto-triage on ticket events. `self._queen_agent` is held on the TUI instance to keep the MCP process alive.
+**Gap 1 — Resolved.** The queen is now the full `HiveCoderAgent` graph (not a minimal hand-assembled subset). `_load_judge_and_queen` calls `HiveCoderAgent._setup(mock_mode=True)` to load hive-tools MCP, then merges those tools into the worker runtime alongside monitoring tools. When the operator connects via Ctrl+Q, they get `coder_node` with `read_file`, `write_file`, `run_command`, `restart_agent`, and all other hive-tools. The `ticket_triage_node` still handles auto-triage on ticket events. `self._queen_agent` is held on the TUI instance to keep the MCP process alive.
 
 **Gap 2 — LLM-hang detection latency.**
 If the worker's LLM call hangs (API never returns), no new log entries are written. The judge detects this on its next timer tick (≤2 min). Bounded latency, not zero.

examples/templates/README.md

@@ -43,4 +43,5 @@ uv run python -m exports.my_research_agent --input '{"topic": "..."}'
 | Template | Description |
 |----------|-------------|
 | [deep_research_agent](deep_research_agent/) | Interactive research agent that searches diverse sources, evaluates findings with user checkpoints, and produces a cited HTML report |
+| [local_business_extractor](local_business_extractor/) | Finds local businesses on Google Maps, scrapes contact details, and syncs to Google Sheets |
 | [tech_news_reporter](tech_news_reporter/) | Researches the latest technology and AI news from the web and produces a well-organized report |

examples/templates/local_business_extractor/README.md

@@ -0,0 +1,31 @@
+# Local Business Extractor
+
+Finds local businesses on Google Maps, scrapes their websites for contact details, and syncs everything to a Google Sheets spreadsheet.
+
+## Nodes
+
+| Node | Type | Description |
+|------|------|-------------|
+| `map-search-worker` | `gcu` (browser) | Searches Google Maps and extracts business names + website URLs |
+| `extract-contacts` | `event_loop` | Scrapes business websites for emails, phone, hours, reviews, address |
+| `sheets-sync` | `event_loop` | Appends extracted data to a Google Sheets spreadsheet |
+
+## Flow
+
+```
+extract-contacts → sheets-sync → (loop back to extract-contacts)
+       ↓
+  map-search-worker (sub-agent)
+```
+
+## Tools used
+
+- **Exa** — `exa_search`, `exa_get_contents` for web scraping
+- **Google Sheets** — `google_sheets_create_spreadsheet`, `google_sheets_update_values`, `google_sheets_append_values`, `google_sheets_get_values`
+- **Browser (GCU)** — automated Google Maps browsing
+
+## Running
+
+```bash
+uv run python -m examples.templates.local_business_extractor run --query "bakeries in San Francisco"
+```

examples/templates/local_business_extractor/__init__.py

@@ -0,0 +1,34 @@
+"""Local Business Extractor package."""
+
+from .agent import (
+    LocalBusinessExtractor,
+    default_agent,
+    goal,
+    nodes,
+    edges,
+    entry_node,
+    entry_points,
+    pause_nodes,
+    terminal_nodes,
+    conversation_mode,
+    identity_prompt,
+    loop_config,
+)
+from .config import default_config, metadata
+
+__all__ = [
+    "LocalBusinessExtractor",
+    "default_agent",
+    "goal",
+    "nodes",
+    "edges",
+    "entry_node",
+    "entry_points",
+    "pause_nodes",
+    "terminal_nodes",
+    "conversation_mode",
+    "identity_prompt",
+    "loop_config",
+    "default_config",
+    "metadata",
+]

examples/templates/local_business_extractor/__main__.py

@@ -0,0 +1,146 @@
+"""
+CLI entry point for Local Business Extractor.
+"""
+
+import asyncio
+import json
+import logging
+import sys
+import click
+
+from .agent import default_agent, LocalBusinessExtractor
+
+
+def setup_logging(verbose=False, debug=False):
+    """Configure logging for execution visibility."""
+    if debug:
+        level, fmt = logging.DEBUG, "%(asctime)s %(name)s: %(message)s"
+    elif verbose:
+        level, fmt = logging.INFO, "%(message)s"
+    else:
+        level, fmt = logging.WARNING, "%(levelname)s: %(message)s"
+    logging.basicConfig(level=level, format=fmt, stream=sys.stderr)
+    logging.getLogger("framework").setLevel(level)
+
+
+@click.group()
+@click.version_option(version="1.0.0")
+def cli():
+    """Local Business Extractor - Find businesses, extract contacts, sync to Sheets."""
+    pass
+
+
+@cli.command()
+@click.option(
+    "--query",
+    "-q",
+    type=str,
+    required=True,
+    help="Search query (e.g. 'bakeries in San Francisco')",
+)
+@click.option("--quiet", is_flag=True, help="Only output result JSON")
+@click.option("--verbose", "-v", is_flag=True, help="Show execution details")
+@click.option("--debug", is_flag=True, help="Show debug logging")
+def run(query, quiet, verbose, debug):
+    """Extract businesses matching a search query."""
+    if not quiet:
+        setup_logging(verbose=verbose, debug=debug)
+
+    context = {"user_request": query}
+
+    result = asyncio.run(default_agent.run(context))
+
+    output_data = {
+        "success": result.success,
+        "steps_executed": result.steps_executed,
+        "output": result.output,
+    }
+    if result.error:
+        output_data["error"] = result.error
+
+    click.echo(json.dumps(output_data, indent=2, default=str))
+    sys.exit(0 if result.success else 1)
+
+
+@cli.command()
+@click.option("--json", "output_json", is_flag=True)
+def info(output_json):
+    """Show agent information."""
+    info_data = default_agent.info()
+    if output_json:
+        click.echo(json.dumps(info_data, indent=2))
+    else:
+        click.echo(f"Agent: {info_data['name']}")
+        click.echo(f"Version: {info_data['version']}")
+        click.echo(f"Description: {info_data['description']}")
+        click.echo(f"\nNodes: {', '.join(info_data['nodes'])}")
+        click.echo(f"Entry: {info_data['entry_node']}")
+        click.echo(f"Terminal: {', '.join(info_data['terminal_nodes'])}")
+
+
+@cli.command()
+def validate():
+    """Validate agent structure."""
+    validation = default_agent.validate()
+    if validation["valid"]:
+        click.echo("Agent is valid")
+        if validation["warnings"]:
+            for warning in validation["warnings"]:
+                click.echo(f"  WARNING: {warning}")
+    else:
+        click.echo("Agent has errors:")
+        for error in validation["errors"]:
+            click.echo(f"  ERROR: {error}")
+    sys.exit(0 if validation["valid"] else 1)
+
+
+@cli.command()
+@click.option("--verbose", "-v", is_flag=True)
+def shell(verbose):
+    """Interactive session (CLI)."""
+    asyncio.run(_interactive_shell(verbose))
+
+
+async def _interactive_shell(verbose=False):
+    """Async interactive shell."""
+    setup_logging(verbose=verbose)
+
+    click.echo("=== Local Business Extractor ===")
+    click.echo("Enter a search query (or 'quit' to exit):\n")
+
+    agent = LocalBusinessExtractor()
+    await agent.start()
+
+    try:
+        while True:
+            try:
+                query = await asyncio.get_event_loop().run_in_executor(
+                    None, input, "Query> "
+                )
+                if query.lower() in ["quit", "exit", "q"]:
+                    click.echo("Goodbye!")
+                    break
+
+                if not query.strip():
+                    continue
+
+                click.echo("\nExtracting...\n")
+
+                result = await agent.run({"user_request": query})
+
+                if result.success:
+                    click.echo("\nExtraction complete\n")
+                else:
+                    click.echo(f"\nExtraction failed: {result.error}\n")
+
+            except KeyboardInterrupt:
+                click.echo("\nGoodbye!")
+                break
+            except Exception as e:
+                click.echo(f"Error: {e}", err=True)
+    finally:
+        await agent.stop()
+
+
+if __name__ == "__main__":
+    cli()

examples/templates/local_business_extractor/agent.py

@@ -0,0 +1,205 @@
+"""Agent graph construction for Local Business Extractor."""
+
+from pathlib import Path
+from framework.graph import EdgeSpec, EdgeCondition, Goal, SuccessCriterion, Constraint
+from framework.graph.edge import GraphSpec
+from framework.graph.executor import ExecutionResult
+from framework.graph.checkpoint_config import CheckpointConfig
+from framework.llm import LiteLLMProvider
+from framework.runner.tool_registry import ToolRegistry
+from framework.runtime.agent_runtime import create_agent_runtime
+from framework.runtime.execution_stream import EntryPointSpec
+
+from .config import default_config, metadata
+from .nodes import map_search_gcu, extract_contacts_node, sheets_sync_node
+
+goal = Goal(
+    id="local-business-extraction",
+    name="Local Business Extraction",
+    description="Find local businesses on Maps, extract contacts, and sync to Google Sheets.",
+    success_criteria=[
+        SuccessCriterion(
+            id="sc-1",
+            description="Extract business details from Maps",
+            metric="count",
+            target="5",
+            weight=0.5,
+        ),
+        SuccessCriterion(
+            id="sc-2",
+            description="Sync data to Google Sheets",
+            metric="success_rate",
+            target="1.0",
+            weight=0.5,
+        ),
+    ],
+    constraints=[
+        Constraint(
+            id="c-1",
+            description="Must verify website presence before scraping",
+            constraint_type="hard",
+            category="quality",
+        ),
+    ],
+)
+
+nodes = [map_search_gcu, extract_contacts_node, sheets_sync_node]
+
+edges = [
+    EdgeSpec(
+        id="extract-to-sheets",
+        source="extract-contacts",
+        target="sheets-sync",
+        condition=EdgeCondition.ON_SUCCESS,
+        priority=1,
+    ),
+    # Loop back for new tasks
+    EdgeSpec(
+        id="sheets-to-extract",
+        source="sheets-sync",
+        target="extract-contacts",
+        condition=EdgeCondition.ALWAYS,
+        priority=1,
+    ),
+]
+
+entry_node = "extract-contacts"
+entry_points = {"start": "extract-contacts"}
+pause_nodes = []
+terminal_nodes = []
+
+conversation_mode = "continuous"
+identity_prompt = "You are a lead generation specialist focused on local businesses."
+loop_config = {
+    "max_iterations": 100,
+    "max_tool_calls_per_turn": 30,
+    "max_history_tokens": 32000,
+}
+
+
+class LocalBusinessExtractor:
+    def __init__(self, config=None):
+        self.config = config or default_config
+        self.goal = goal
+        self.nodes = nodes
+        self.edges = edges
+        self.entry_node = entry_node
+        self.entry_points = entry_points
+        self.pause_nodes = pause_nodes
+        self.terminal_nodes = terminal_nodes
+        self._graph = None
+        self._agent_runtime = None
+        self._tool_registry = None
+        self._storage_path = None
+
+    def _build_graph(self):
+        return GraphSpec(
+            id="local-business-extractor-graph",
+            goal_id=self.goal.id,
+            version="1.0.0",
+            entry_node=self.entry_node,
+            entry_points=self.entry_points,
+            terminal_nodes=self.terminal_nodes,
+            pause_nodes=self.pause_nodes,
+            nodes=self.nodes,
+            edges=self.edges,
+            default_model=self.config.model,
+            max_tokens=self.config.max_tokens,
+            loop_config=loop_config,
+            conversation_mode=conversation_mode,
+            identity_prompt=identity_prompt,
+        )
+
+    def _setup(self):
+        self._storage_path = (
+            Path.home() / ".hive" / "agents" / "local_business_extractor"
+        )
+        self._storage_path.mkdir(parents=True, exist_ok=True)
+        self._tool_registry = ToolRegistry()
+        mcp_config = Path(__file__).parent / "mcp_servers.json"
+        if mcp_config.exists():
+            self._tool_registry.load_mcp_config(mcp_config)
+        llm = LiteLLMProvider(
+            model=self.config.model,
+            api_key=self.config.api_key,
+            api_base=self.config.api_base,
+        )
+        tools = list(self._tool_registry.get_tools().values())
+        tool_executor = self._tool_registry.get_executor()
+        self._graph = self._build_graph()
+        self._agent_runtime = create_agent_runtime(
+            graph=self._graph,
+            goal=self.goal,
+            storage_path=self._storage_path,
+            entry_points=[
+                EntryPointSpec(
+                    id="default",
+                    name="Default",
+                    entry_node=self.entry_node,
+                    trigger_type="manual",
+                    isolation_level="shared",
+                )
+            ],
+            llm=llm,
+            tools=tools,
+            tool_executor=tool_executor,
+            checkpoint_config=CheckpointConfig(
+                enabled=True, checkpoint_on_node_complete=True
+            ),
+        )
+
+    async def start(self):
+        if self._agent_runtime is None:
+            self._setup()
+        if not self._agent_runtime.is_running:
+            await self._agent_runtime.start()
+
+    async def stop(self):
+        if self._agent_runtime and self._agent_runtime.is_running:
+            await self._agent_runtime.stop()
+        self._agent_runtime = None
+
+    async def run(self, context, session_state=None):
+        await self.start()
+        try:
+            result = await self._agent_runtime.trigger_and_wait(
+                "default", context, session_state=session_state
+            )
+            return result or ExecutionResult(success=False, error="Execution timeout")
+        finally:
+            await self.stop()
+
+    def info(self):
+        """Get agent information."""
+        return {
+            "name": metadata.name,
+            "version": metadata.version,
+            "description": metadata.description,
+            "goal": {
+                "name": self.goal.name,
+                "description": self.goal.description,
+            },
+            "nodes": [n.id for n in self.nodes],
+            "edges": [e.id for e in self.edges],
+            "entry_node": self.entry_node,
+            "entry_points": self.entry_points,
+            "pause_nodes": self.pause_nodes,
+            "terminal_nodes": self.terminal_nodes,
+        }
+
+    def validate(self):
+        """Validate agent structure."""
+        errors = []
+        warnings = []
+        node_ids = {n.id for n in self.nodes}
+        for edge in self.edges:
+            if edge.source not in node_ids:
+                errors.append(f"Edge {edge.id}: source '{edge.source}' not found")
+            if edge.target not in node_ids:
+                errors.append(f"Edge {edge.id}: target '{edge.target}' not found")
+        if self.entry_node not in node_ids:
+            errors.append(f"Entry node '{self.entry_node}' not found")
+        return {"valid": len(errors) == 0, "errors": errors, "warnings": warnings}
+
+
+default_agent = LocalBusinessExtractor()

examples/templates/local_business_extractor/config.py

@@ -0,0 +1,21 @@
+"""Runtime configuration."""
+
+from dataclasses import dataclass
+
+from framework.config import RuntimeConfig
+
+default_config = RuntimeConfig()
+
+
+@dataclass
+class AgentMetadata:
+    name: str = "Local Business Extractor"
+    version: str = "1.0.0"
+    description: str = (
+        "Extracts local businesses from Google Maps, scrapes contact details, "
+        "and syncs the results to Google Sheets."
+    )
+    intro_message: str = "I'm ready to extract business data. What should I search for?"
+
+
+metadata = AgentMetadata()

examples/templates/local_business_extractor/mcp_servers.json

@@ -0,0 +1,14 @@
+{
+  "hive-tools": {
+    "transport": "stdio",
+    "command": "uv",
+    "args": ["run", "python", "mcp_server.py", "--stdio"],
+    "cwd": "../../../tools"
+  },
+  "gcu-tools": {
+    "transport": "stdio",
+    "command": "uv",
+    "args": ["run", "python", "-m", "gcu.server", "--stdio"],
+    "cwd": "../../../tools"
+  }
+}

examples/templates/local_business_extractor/nodes/__init__.py

@@ -0,0 +1,86 @@
+"""Node definitions for Local Business Extractor."""
+
+from framework.graph import NodeSpec
+
+# GCU Subagent for Google Maps
+map_search_gcu = NodeSpec(
+    id="map-search-worker",
+    name="Maps Browser Worker",
+    description="Browser subagent that searches Google Maps and extracts business links.",
+    node_type="gcu",
+    client_facing=False,
+    max_node_visits=1,
+    input_keys=["query"],
+    output_keys=["business_list"],
+    tools=[],  # Auto-populated with browser tools
+    system_prompt="""\
+You are a browser agent. Your job: Search Google Maps for the provided query and extract business names and website URLs.
+
+## Workflow
+1. browser_start
+2. browser_open(url="https://www.google.com/maps")
+3. Use browser_type or browser_click to search for the "query" in memory.
+4. browser_wait(seconds=3)
+5. browser_snapshot to find the list of results.
+6. For each relevant result, extract:
+   - Name of the business
+   - Website URL (look for the website icon/link)
+7. set_output("business_list", [{"name": "...", "website": "..."}, ...])
+
+## Constraints
+- Extract at least 5-10 businesses if possible.
+- If you see a "Website" button, extract that URL specifically.
+""",
+)
+
+# Processing Node: Scrape & Prepare
+extract_contacts_node = NodeSpec(
+    id="extract-contacts",
+    name="Extract Business Details",
+    description="Scrapes business websites and Maps for comprehensive business details.",
+    node_type="event_loop",
+    sub_agents=["map-search-worker"],
+    input_keys=["user_request"],
+    output_keys=["business_data"],
+    success_criteria="Comprehensive business details (reviews, hours, contacts) extracted.",
+    system_prompt="""\
+1. Call delegate_to_sub_agent(agent_id="map-search-worker", task=user_request)
+2. Receive "business_list" from memory.
+3. For each business in the list:
+   - Use exa_get_contents or exa_search to find:
+     - Contact emails and phone numbers.
+     - Business hours.
+     - Customer reviews or ratings summary.
+     - Physical address.
+4. Format the data into a comprehensive report for each business.
+5. set_output("business_data", enriched_business_list)
+""",
+    tools=["exa_get_contents", "exa_search"],
+)
+
+# Google Sheets Sync Node
+sheets_sync_node = NodeSpec(
+    id="sheets-sync",
+    name="Google Sheets Sync",
+    description="Appends the extracted business data to a Google Sheets spreadsheet.",
+    node_type="event_loop",
+    input_keys=["business_data"],
+    output_keys=["spreadsheet_id"],
+    success_criteria="Data successfully synced to Google Sheets.",
+    system_prompt="""\
+1. Check memory for "spreadsheet_id". If not set, create a new spreadsheet:
+   - Use google_sheets_create_spreadsheet(title="Comprehensive Business Leads")
+   - Save the spreadsheet ID with set_output("spreadsheet_id", id)
+2. If the spreadsheet is new, write header row:
+   - Use google_sheets_update_values(spreadsheet_id=id, range_name="Sheet1!A1:G1", values=[["Name", "Website", "Email", "Phone", "Address", "Hours", "Reviews"]])
+3. For each business in "business_data", append a row:
+   - Use google_sheets_append_values(spreadsheet_id=id, range_name="Sheet1!A:G", values=[[name, website, email, phone, address, hours, reviews]])
+4. set_output("spreadsheet_id", id)
+""",
+    tools=[
+        "google_sheets_create_spreadsheet",
+        "google_sheets_update_values",
+        "google_sheets_append_values",
+        "google_sheets_get_values",
+    ],
+)

examples/templates/meeting_scheduler/__init__.py

@@ -0,0 +1,34 @@
+"""Meeting Scheduler — Find available times on your calendar and book meetings."""
+
+from .agent import (
+    MeetingScheduler,
+    default_agent,
+    goal,
+    nodes,
+    edges,
+    entry_node,
+    entry_points,
+    pause_nodes,
+    terminal_nodes,
+    conversation_mode,
+    identity_prompt,
+    loop_config,
+)
+from .config import default_config, metadata
+
+__all__ = [
+    "MeetingScheduler",
+    "default_agent",
+    "goal",
+    "nodes",
+    "edges",
+    "entry_node",
+    "entry_points",
+    "pause_nodes",
+    "terminal_nodes",
+    "conversation_mode",
+    "identity_prompt",
+    "loop_config",
+    "default_config",
+    "metadata",
+]

examples/templates/meeting_scheduler/__main__.py

@@ -0,0 +1,131 @@
+"""CLI entry point for Meeting Scheduler."""
+
+import asyncio
+import json
+import logging
+import sys
+import click
+from .agent import default_agent, MeetingScheduler
+
+
+def setup_logging(verbose=False, debug=False):
+    if debug:
+        level, fmt = logging.DEBUG, "%(asctime)s %(name)s: %(message)s"
+    elif verbose:
+        level, fmt = logging.INFO, "%(message)s"
+    else:
+        level, fmt = logging.WARNING, "%(levelname)s: %(message)s"
+    logging.basicConfig(level=level, format=fmt, stream=sys.stderr)
+
+
+@click.group()
+@click.version_option(version="1.0.0")
+def cli():
+    """Meeting Scheduler — Find available times on your calendar and book meetings."""
+    pass
+
+
+@cli.command()
+@click.option("--attendee", "-a", required=True, help="Attendee email address")
+@click.option(
+    "--duration", "-d", type=int, required=True, help="Meeting duration in minutes"
+)
+@click.option("--title", "-t", required=True, help="Meeting title")
+@click.option("--verbose", "-v", is_flag=True)
+def run(attendee, duration, title, verbose):
+    """Execute the scheduler."""
+    setup_logging(verbose=verbose)
+    result = asyncio.run(
+        default_agent.run(
+            {
+                "attendee_email": attendee,
+                "meeting_duration_minutes": str(duration),
+                "meeting_title": title,
+            }
+        )
+    )
+    click.echo(
+        json.dumps(
+            {"success": result.success, "output": result.output}, indent=2, default=str
+        )
+    )
+    sys.exit(0 if result.success else 1)
+
+
+@cli.command()
+def tui():
+    """Launch TUI dashboard."""
+    from pathlib import Path
+    from framework.tui.app import AdenTUI
+    from framework.llm import LiteLLMProvider
+    from framework.runner.tool_registry import ToolRegistry
+    from framework.runtime.agent_runtime import create_agent_runtime
+    from framework.runtime.execution_stream import EntryPointSpec
+
+    async def run_tui():
+        agent = MeetingScheduler()
+        agent._tool_registry = ToolRegistry()
+        storage = Path.home() / ".hive" / "agents" / "meeting_scheduler"
+        storage.mkdir(parents=True, exist_ok=True)
+        mcp_cfg = Path(__file__).parent / "mcp_servers.json"
+        if mcp_cfg.exists():
+            agent._tool_registry.load_mcp_config(mcp_cfg)
+        llm = LiteLLMProvider(
+            model=agent.config.model,
+            api_key=agent.config.api_key,
+            api_base=agent.config.api_base,
+        )
+        runtime = create_agent_runtime(
+            graph=agent._build_graph(),
+            goal=agent.goal,
+            storage_path=storage,
+            entry_points=[
+                EntryPointSpec(
+                    id="start",
+                    name="Start",
+                    entry_node="intake",
+                    trigger_type="manual",
+                    isolation_level="isolated",
+                )
+            ],
+            llm=llm,
+            tools=list(agent._tool_registry.get_tools().values()),
+            tool_executor=agent._tool_registry.get_executor(),
+        )
+        await runtime.start()
+        try:
+            app = AdenTUI(runtime)
+            await app.run_async()
+        finally:
+            await runtime.stop()
+
+    asyncio.run(run_tui())
+
+
+@cli.command()
+def info():
+    """Show agent info."""
+    data = default_agent.info()
+    click.echo(
+        f"Agent: {data['name']}\nVersion: {data['version']}\nDescription: {data['description']}"
+    )
+    click.echo(
+        f"Nodes: {', '.join(data['nodes'])}\nClient-facing: {', '.join(data['client_facing_nodes'])}"
+    )
+
+
+@cli.command()
+def validate():
+    """Validate agent structure."""
+    v = default_agent.validate()
+    if v["valid"]:
+        click.echo("Agent is valid")
+    else:
+        click.echo("Errors:")
+        for e in v["errors"]:
+            click.echo(f"  {e}")
+    sys.exit(0 if v["valid"] else 1)
+
+
+if __name__ == "__main__":
+    cli()

examples/templates/meeting_scheduler/agent.py

@@ -0,0 +1,257 @@
+"""Agent graph construction for Meeting Scheduler."""
+
+from pathlib import Path
+
+from framework.graph import EdgeSpec, EdgeCondition, Goal, SuccessCriterion, Constraint
+from framework.graph.edge import GraphSpec
+from framework.graph.executor import ExecutionResult
+from framework.graph.checkpoint_config import CheckpointConfig
+from framework.llm import LiteLLMProvider
+from framework.runner.tool_registry import ToolRegistry
+from framework.runtime.agent_runtime import create_agent_runtime
+from framework.runtime.execution_stream import EntryPointSpec
+
+from .config import default_config, metadata
+from .nodes import intake_node, schedule_node, confirm_node
+
+# Goal definition
+goal = Goal(
+    id="meeting-scheduler-goal",
+    name="Schedule Meetings",
+    description="Check calendar availability, find optimal meeting times, record meetings, and send reminders.",
+    success_criteria=[
+        SuccessCriterion(
+            id="sc-1",
+            description="Meeting time found within requested duration",
+            metric="calendar_availability",
+            target="success",
+            weight=0.35,
+        ),
+        SuccessCriterion(
+            id="sc-2",
+            description="Meeting recorded in spreadsheet accurately",
+            metric="data_persistence",
+            target="recorded",
+            weight=0.30,
+        ),
+        SuccessCriterion(
+            id="sc-3",
+            description="Attendee email reminder sent",
+            metric="communication",
+            target="sent",
+            weight=0.25,
+        ),
+        SuccessCriterion(
+            id="sc-4",
+            description="User confirms meeting details",
+            metric="user_acknowledgment",
+            target="confirmed",
+            weight=0.10,
+        ),
+    ],
+    constraints=[
+        Constraint(
+            id="c-1",
+            description="Must use Google Calendar API for availability check",
+            constraint_type="hard",
+            category="functional",
+        ),
+        Constraint(
+            id="c-2",
+            description="Meeting duration must match requested time",
+            constraint_type="hard",
+            category="accuracy",
+        ),
+        Constraint(
+            id="c-3",
+            description="Spreadsheet record must include date, time, attendee, title",
+            constraint_type="hard",
+            category="quality",
+        ),
+    ],
+)
+
+# Node list
+nodes = [intake_node, schedule_node, confirm_node]
+
+# Edge definitions
+edges = [
+    EdgeSpec(
+        id="intake-to-schedule",
+        source="intake",
+        target="schedule",
+        condition=EdgeCondition.ON_SUCCESS,
+        priority=1,
+    ),
+    EdgeSpec(
+        id="schedule-to-confirm",
+        source="schedule",
+        target="confirm",
+        condition=EdgeCondition.ON_SUCCESS,
+        priority=1,
+    ),
+    # Loop back for another booking
+    EdgeSpec(
+        id="confirm-to-intake",
+        source="confirm",
+        target="intake",
+        condition=EdgeCondition.CONDITIONAL,
+        condition_expr="str(next_action).lower() == 'another'",
+        priority=1,
+    ),
+]
+
+# Graph configuration
+entry_node = "intake"
+entry_points = {"start": "intake"}
+pause_nodes = []
+terminal_nodes = []  # Forever-alive
+
+# Module-level vars read by AgentRunner.load()
+conversation_mode = "continuous"
+identity_prompt = "You are a helpful meeting scheduler assistant that manages calendar availability and sends confirmations."
+loop_config = {
+    "max_iterations": 100,
+    "max_tool_calls_per_turn": 20,
+    "max_history_tokens": 32000,
+}
+
+
+class MeetingScheduler:
+    def __init__(self, config=None):
+        self.config = config or default_config
+        self.goal = goal
+        self.nodes = nodes
+        self.edges = edges
+        self.entry_node = entry_node
+        self.entry_points = entry_points
+        self.pause_nodes = pause_nodes
+        self.terminal_nodes = terminal_nodes
+        self._graph = None
+        self._agent_runtime = None
+        self._tool_registry = None
+        self._storage_path = None
+
+    def _build_graph(self):
+        return GraphSpec(
+            id="meeting-scheduler-graph",
+            goal_id=self.goal.id,
+            version="1.0.0",
+            entry_node=self.entry_node,
+            entry_points=self.entry_points,
+            terminal_nodes=self.terminal_nodes,
+            pause_nodes=self.pause_nodes,
+            nodes=self.nodes,
+            edges=self.edges,
+            default_model=self.config.model,
+            max_tokens=self.config.max_tokens,
+            loop_config=loop_config,
+            conversation_mode=conversation_mode,
+            identity_prompt=identity_prompt,
+        )
+
+    def _setup(self):
+        self._storage_path = Path.home() / ".hive" / "agents" / "meeting_scheduler"
+        self._storage_path.mkdir(parents=True, exist_ok=True)
+        self._tool_registry = ToolRegistry()
+        mcp_config = Path(__file__).parent / "mcp_servers.json"
+        if mcp_config.exists():
+            self._tool_registry.load_mcp_config(mcp_config)
+        llm = LiteLLMProvider(
+            model=self.config.model,
+            api_key=self.config.api_key,
+            api_base=self.config.api_base,
+        )
+        tools = list(self._tool_registry.get_tools().values())
+        tool_executor = self._tool_registry.get_executor()
+        self._graph = self._build_graph()
+        self._agent_runtime = create_agent_runtime(
+            graph=self._graph,
+            goal=self.goal,
+            storage_path=self._storage_path,
+            entry_points=[
+                EntryPointSpec(
+                    id="default",
+                    name="Default",
+                    entry_node=self.entry_node,
+                    trigger_type="manual",
+                    isolation_level="shared",
+                )
+            ],
+            llm=llm,
+            tools=tools,
+            tool_executor=tool_executor,
+            checkpoint_config=CheckpointConfig(
+                enabled=True,
+                checkpoint_on_node_complete=True,
+                checkpoint_max_age_days=7,
+                async_checkpoint=True,
+            ),
+        )
+
+    async def start(self):
+        if self._agent_runtime is None:
+            self._setup()
+        if not self._agent_runtime.is_running:
+            await self._agent_runtime.start()
+
+    async def stop(self):
+        if self._agent_runtime and self._agent_runtime.is_running:
+            await self._agent_runtime.stop()
+        self._agent_runtime = None
+
+    async def trigger_and_wait(
+        self, entry_point="default", input_data=None, timeout=None, session_state=None
+    ):
+        if self._agent_runtime is None:
+            raise RuntimeError("Agent not started. Call start() first.")
+        return await self._agent_runtime.trigger_and_wait(
+            entry_point_id=entry_point,
+            input_data=input_data or {},
+            session_state=session_state,
+        )
+
+    async def run(self, context, session_state=None):
+        await self.start()
+        try:
+            result = await self.trigger_and_wait(
+                "default", context, session_state=session_state
+            )
+            return result or ExecutionResult(success=False, error="Execution timeout")
+        finally:
+            await self.stop()
+
+    def info(self):
+        return {
+            "name": metadata.name,
+            "version": metadata.version,
+            "description": metadata.description,
+            "goal": {"name": self.goal.name, "description": self.goal.description},
+            "nodes": [n.id for n in self.nodes],
+            "edges": [e.id for e in self.edges],
+            "entry_node": self.entry_node,
+            "entry_points": self.entry_points,
+            "terminal_nodes": self.terminal_nodes,
+            "client_facing_nodes": [n.id for n in self.nodes if n.client_facing],
+        }
+
+    def validate(self):
+        errors, warnings = [], []
+        node_ids = {n.id for n in self.nodes}
+        for e in self.edges:
+            if e.source not in node_ids:
+                errors.append(f"Edge {e.id}: source '{e.source}' not found")
+            if e.target not in node_ids:
+                errors.append(f"Edge {e.id}: target '{e.target}' not found")
+        if self.entry_node not in node_ids:
+            errors.append(f"Entry node '{self.entry_node}' not found")
+        for t in self.terminal_nodes:
+            if t not in node_ids:
+                errors.append(f"Terminal node '{t}' not found")
+        for ep_id, nid in self.entry_points.items():
+            if nid not in node_ids:
+                errors.append(f"Entry point '{ep_id}' references unknown node '{nid}'")
+        return {"valid": len(errors) == 0, "errors": errors, "warnings": warnings}
+
+
+default_agent = MeetingScheduler()

examples/templates/meeting_scheduler/config.py

@@ -0,0 +1,28 @@
+"""Runtime configuration."""
+
+from dataclasses import dataclass
+
+from framework.config import RuntimeConfig
+
+default_config = RuntimeConfig()
+
+
+@dataclass
+class AgentMetadata:
+    name: str = "Meeting Scheduler"
+    version: str = "1.0.0"
+    description: str = (
+        "Schedule meetings by checking Google Calendar availability, booking "
+        "optimal time slots, recording details in Google Sheets, and sending "
+        "email confirmations with Google Meet links to attendees."
+    )
+    intro_message: str = (
+        "Hi! I'm your meeting scheduler. Tell me who you'd like to meet with, "
+        "how long the meeting should be, and what it's about — I'll check "
+        "calendar availability, book a time slot, log it to your spreadsheet, "
+        "and send a confirmation email with a Google Meet link. "
+        "Who would you like to schedule a meeting with?"
+    )
+
+
+metadata = AgentMetadata()

examples/templates/meeting_scheduler/mcp_servers.json

@@ -0,0 +1,9 @@
+{
+  "hive-tools": {
+    "transport": "stdio",
+    "command": "uv",
+    "args": ["run", "python", "mcp_server.py", "--stdio"],
+    "cwd": "../../../tools",
+    "description": "Hive tools MCP server"
+  }
+}

examples/templates/meeting_scheduler/nodes/__init__.py

@@ -0,0 +1,140 @@
+"""Node definitions for Meeting Scheduler."""
+
+from framework.graph import NodeSpec
+
+# Node 1: Intake (client-facing)
+intake_node = NodeSpec(
+    id="intake",
+    name="Intake",
+    description="Gather meeting details from the user",
+    node_type="event_loop",
+    client_facing=True,
+    max_node_visits=0,
+    input_keys=["attendee_email", "meeting_duration_minutes"],
+    output_keys=["attendee_email", "meeting_duration_minutes", "meeting_title"],
+    nullable_output_keys=[
+        "attendee_email",
+        "meeting_duration_minutes",
+        "meeting_title",
+    ],
+    success_criteria="User has provided attendee email, meeting duration, and title.",
+    system_prompt="""\
+You are a meeting scheduler assistant.
+
+**STEP 1 — Use ask_user to collect meeting details:**
+1. Call ask_user to ask for: attendee email, meeting duration (minutes), and meeting title
+2. Wait for the user's response before proceeding
+
+**STEP 2 — After user provides all details, call set_output:**
+- set_output("attendee_email", "user's email address")
+- set_output("meeting_duration_minutes", meeting duration as string)
+- set_output("meeting_title", "title of the meeting")
+""",
+    tools=[],
+)
+
+# Node 2: Schedule (autonomous)
+schedule_node = NodeSpec(
+    id="schedule",
+    name="Schedule",
+    description="Find available time on calendar, book meeting with Google Meet, and log to Google Sheet",
+    node_type="event_loop",
+    max_node_visits=0,
+    input_keys=["attendee_email", "meeting_duration_minutes", "meeting_title"],
+    output_keys=[
+        "meeting_time",
+        "booking_confirmed",
+        "spreadsheet_recorded",
+        "email_sent",
+        "meet_link",
+    ],
+    nullable_output_keys=[],
+    success_criteria="Meeting time found, Google Meet created, Google Sheet 'Meeting Scheduler' updated with date/time/attendee/title/meet_link, and confirmation email sent.",
+    system_prompt="""\
+You are a meeting booking agent that creates Google Calendar events with Google Meet and logs to Google Sheets.
+
+## STEP 1 — Calendar Operations (tool calls in this turn):
+
+1. **Find availability and verify conflicts:**
+   - Use calendar_check_availability to find potential time slots.
+   - **CRITICAL:** Always search a broad window (at least 8 hours) for the target day to see the full context of the user's schedule.
+   - **SECONDARY CHECK:** Before finalizing a slot, use calendar_list_events for that specific day. This ensures you catch "soft" conflicts or events not marked as 'busy' that might still be important.
+
+2. **Create the event WITH GOOGLE MEET (AUTOMATIC):**
+   - Use calendar_create_event with these parameters:
+     - summary: the meeting title
+     - start_time: the start datetime in ISO format (e.g., "2024-01-15T09:00:00")
+     - end_time: the end datetime in ISO format
+     - attendees: list with the attendee email address (e.g., ["user@example.com"])
+     - timezone: user's timezone (e.g., "America/Los_Angeles")
+   - IMPORTANT: The tool automatically generates a Google Meet link when attendees are provided.
+     You do NOT need to pass conferenceData - it is handled automatically.
+   - The response will include conferenceData.entryPoints with the Google Meet link
+   - Extract the meet_link from conferenceData.entryPoints[0].uri in the response
+
+3. **Log to Google Sheets:**
+   - First, use google_sheets_get_spreadsheet with spreadsheet_id="Meeting Scheduler" to check if it exists
+   - If it doesn't exist, use google_sheets_create_spreadsheet with title="Meeting Scheduler"
+   - Then use google_sheets_append_values to add a row with:
+     - Date, Time, Attendee Email, Meeting Title, Google Meet Link
+   - The spreadsheet_id should be "Meeting Scheduler" (by name) or the ID returned from create
+
+4. **Send confirmation email:**
+   - Use send_email to send the attendee a confirmation with:
+     - to: attendee email address
+     - subject: "Meeting Confirmation: {meeting_title}"
+     - body: Include meeting title, date/time, and Google Meet link
+
+## STEP 2 — set_output (SEPARATE turn, no other tool calls):
+
+After all tools complete successfully, call set_output:
+- set_output("meeting_time", "YYYY-MM-DD HH:MM")
+- set_output("meet_link", "https://meet.google.com/xxx/yyy")
+- set_output("booking_confirmed", "true")
+- set_output("spreadsheet_recorded", "true")
+- set_output("email_sent", "true")
+
+## CRITICAL: Google Meet creation
+Google Meet links are AUTOMATICALLY created by calendar_create_event when attendees are provided.
+Simply pass the attendees list and the tool will generate the Meet link.
+""",
+    tools=[
+        "calendar_check_availability",
+        "calendar_create_event",
+        "calendar_list_events",
+        "google_sheets_create_spreadsheet",
+        "google_sheets_get_spreadsheet",
+        "google_sheets_append_values",
+        "send_email",
+    ],
+)
+
+# Node 3: Confirm (client-facing)
+confirm_node = NodeSpec(
+    id="confirm",
+    name="Confirm",
+    description="Present booking confirmation to user with Google Meet link",
+    node_type="event_loop",
+    client_facing=True,
+    max_node_visits=0,
+    input_keys=["meeting_time", "booking_confirmed", "meet_link"],
+    output_keys=["next_action"],
+    nullable_output_keys=["next_action"],
+    success_criteria="User has acknowledged the booking and received the Google Meet link.",
+    system_prompt="""\
+You are a confirmation assistant.
+
+**STEP 1 — Present confirmation and ask user:**
+1. Show the meeting details (date, time, attendee, title)
+2. Display the Google Meet link prominently
+3. Confirm the booking is complete and logged to Google Sheets
+4. Call ask_user to ask if they want to schedule another meeting or finish
+
+**STEP 2 — After user responds, call set_output:**
+- set_output("next_action", "another") — if booking another meeting
+- set_output("next_action", "done")  — if finished
+""",
+    tools=[],
+)
+
+__all__ = ["intake_node", "schedule_node", "confirm_node"]

examples/templates/meeting_scheduler/tests/conftest.py

@@ -0,0 +1,34 @@
+"""Test fixtures."""
+
+import sys
+from pathlib import Path
+
+import pytest
+
+_repo_root = Path(__file__).resolve().parents[4]
+for _p in ["examples/templates", "core"]:
+    _path = str(_repo_root / _p)
+    if _path not in sys.path:
+        sys.path.insert(0, _path)
+
+AGENT_PATH = str(Path(__file__).resolve().parents[1])
+
+
+@pytest.fixture(scope="session")
+def agent_module():
+    """Import the agent package for structural validation."""
+    import importlib
+
+    return importlib.import_module(Path(AGENT_PATH).name)
+
+
+@pytest.fixture(scope="session")
+def runner_loaded():
+    """Load the agent through AgentRunner (structural only, no LLM needed)."""
+    from framework.runner.runner import AgentRunner
+    from framework.credentials.models import CredentialError
+
+    try:
+        return AgentRunner.load(AGENT_PATH)
+    except CredentialError:
+        pytest.skip("Google OAuth credentials not configured")

examples/templates/meeting_scheduler/tests/test_structure.py

@@ -0,0 +1,103 @@
+"""Structural tests for Meeting Scheduler."""
+
+from meeting_scheduler import (
+    default_agent,
+    goal,
+    nodes,
+    edges,
+    entry_node,
+    entry_points,
+    terminal_nodes,
+    conversation_mode,
+    loop_config,
+)
+
+
+class TestGoalDefinition:
+    def test_goal_exists(self):
+        assert goal is not None
+        assert goal.id == "meeting-scheduler-goal"
+        assert len(goal.success_criteria) == 4
+        assert len(goal.constraints) == 3
+
+    def test_success_criteria_weights_sum_to_one(self):
+        total = sum(sc.weight for sc in goal.success_criteria)
+        assert abs(total - 1.0) < 0.01
+
+
+class TestNodeStructure:
+    def test_three_nodes(self):
+        assert len(nodes) == 3
+        assert nodes[0].id == "intake"
+        assert nodes[1].id == "schedule"
+        assert nodes[2].id == "confirm"
+
+    def test_intake_is_client_facing(self):
+        assert nodes[0].client_facing is True
+
+    def test_schedule_has_required_tools(self):
+        required = {
+            "calendar_check_availability",
+            "calendar_create_event",
+            "google_sheets_append_values",
+            "send_email",
+        }
+        actual = set(nodes[1].tools)
+        assert required.issubset(actual)
+
+    def test_confirm_is_client_facing(self):
+        assert nodes[2].client_facing is True
+
+
+class TestEdgeStructure:
+    def test_three_edges(self):
+        assert len(edges) == 3
+
+    def test_linear_path(self):
+        assert edges[0].source == "intake"
+        assert edges[0].target == "schedule"
+        assert edges[1].source == "schedule"
+        assert edges[1].target == "confirm"
+
+    def test_loop_back(self):
+        assert edges[2].source == "confirm"
+        assert edges[2].target == "intake"
+
+
+class TestGraphConfiguration:
+    def test_entry_node(self):
+        assert entry_node == "intake"
+
+    def test_entry_points(self):
+        assert entry_points == {"start": "intake"}
+
+    def test_forever_alive(self):
+        assert terminal_nodes == []
+
+    def test_conversation_mode(self):
+        assert conversation_mode == "continuous"
+
+    def test_loop_config_valid(self):
+        assert "max_iterations" in loop_config
+        assert "max_tool_calls_per_turn" in loop_config
+        assert "max_history_tokens" in loop_config
+
+
+class TestAgentClass:
+    def test_default_agent_created(self):
+        assert default_agent is not None
+
+    def test_validate_passes(self):
+        result = default_agent.validate()
+        assert result["valid"] is True
+        assert len(result["errors"]) == 0
+
+    def test_agent_info(self):
+        info = default_agent.info()
+        assert info["name"] == "Meeting Scheduler"
+        assert "schedule" in [n for n in info["nodes"]]
+
+
+class TestRunnerLoad:
+    def test_agent_runner_load_succeeds(self, runner_loaded):
+        assert runner_loaded is not None

examples/templates/twitter_news_agent/README.md

@@ -0,0 +1,32 @@
+# Twitter News Digest
+
+Monitors tech Twitter profiles, extracts the latest tweets, and compiles a daily tech news digest with user review.
+
+## Nodes
+
+| Node | Type | Description |
+|------|------|-------------|
+| `fetch-tweets` | `gcu` (browser) | Navigates to Twitter profiles and extracts latest tweets |
+| `process-news` | `event_loop` | Analyzes and summarizes tweets into a tech digest |
+| `review-digest` | `event_loop` (client-facing) | Presents digest for user review and feedback |
+
+## Flow
+
+```
+process-news → review-digest → (loop back to process-news)
+      ↓                ↑
+ fetch-tweets      feedback loop (if revisions needed)
+ (sub-agent)
+```
+
+## Tools used
+
+- **save_data / load_data** — persist daily reports
+- **Browser (GCU)** — automated Twitter browsing and tweet extraction
+
+## Running
+
+```bash
+uv run python -m examples.templates.twitter_news_agent run
+uv run python -m examples.templates.twitter_news_agent run --handles "@TechCrunch,@verge,@WIRED"
+```

examples/templates/twitter_news_agent/__init__.py

@@ -0,0 +1,34 @@
+"""Twitter News Digest — monitors Twitter for news."""
+
+from .agent import (
+    TwitterNewsAgent,
+    default_agent,
+    goal,
+    nodes,
+    edges,
+    entry_node,
+    entry_points,
+    pause_nodes,
+    terminal_nodes,
+    conversation_mode,
+    identity_prompt,
+    loop_config,
+)
+from .config import default_config, metadata
+
+__all__ = [
+    "TwitterNewsAgent",
+    "default_agent",
+    "goal",
+    "nodes",
+    "edges",
+    "entry_node",
+    "entry_points",
+    "pause_nodes",
+    "terminal_nodes",
+    "conversation_mode",
+    "identity_prompt",
+    "loop_config",
+    "default_config",
+    "metadata",
+]

examples/templates/twitter_news_agent/__main__.py

@@ -0,0 +1,148 @@
+"""
+CLI entry point for Twitter News Digest.
+"""
+
+import asyncio
+import json
+import logging
+import sys
+import click
+
+from .agent import default_agent, TwitterNewsAgent
+
+
+def setup_logging(verbose=False, debug=False):
+    """Configure logging for execution visibility."""
+    if debug:
+        level, fmt = logging.DEBUG, "%(asctime)s %(name)s: %(message)s"
+    elif verbose:
+        level, fmt = logging.INFO, "%(message)s"
+    else:
+        level, fmt = logging.WARNING, "%(levelname)s: %(message)s"
+    logging.basicConfig(level=level, format=fmt, stream=sys.stderr)
+    logging.getLogger("framework").setLevel(level)
+
+
+@click.group()
+@click.version_option(version="1.1.0")
+def cli():
+    """Twitter News Digest - Monitor Twitter feeds for tech news."""
+    pass
+
+
+@cli.command()
+@click.option(
+    "--handles",
+    "-h",
+    type=str,
+    default=None,
+    help="Comma-separated Twitter handles to monitor",
+)
+@click.option("--quiet", is_flag=True, help="Only output result JSON")
+@click.option("--verbose", "-v", is_flag=True, help="Show execution details")
+@click.option("--debug", is_flag=True, help="Show debug logging")
+def run(handles, quiet, verbose, debug):
+    """Fetch and summarize tech news from Twitter."""
+    if not quiet:
+        setup_logging(verbose=verbose, debug=debug)
+
+    context = {"user_request": "Fetch the latest tech news digest from Twitter"}
+    if handles:
+        context["twitter_handles"] = [h.strip() for h in handles.split(",")]
+
+    result = asyncio.run(default_agent.run(context))
+
+    output_data = {
+        "success": result.success,
+        "steps_executed": result.steps_executed,
+        "output": result.output,
+    }
+    if result.error:
+        output_data["error"] = result.error
+
+    click.echo(json.dumps(output_data, indent=2, default=str))
+    sys.exit(0 if result.success else 1)
+
+
+@cli.command()
+@click.option("--json", "output_json", is_flag=True)
+def info(output_json):
+    """Show agent information."""
+    info_data = default_agent.info()
+    if output_json:
+        click.echo(json.dumps(info_data, indent=2))
+    else:
+        click.echo(f"Agent: {info_data['name']}")
+        click.echo(f"Version: {info_data['version']}")
+        click.echo(f"Description: {info_data['description']}")
+        click.echo(f"\nNodes: {', '.join(info_data['nodes'])}")
+        click.echo(f"Entry: {info_data['entry_node']}")
+        click.echo(f"Terminal: {', '.join(info_data['terminal_nodes'])}")
+
+
+@cli.command()
+def validate():
+    """Validate agent structure."""
+    validation = default_agent.validate()
+    if validation["valid"]:
+        click.echo("Agent is valid")
+        if validation["warnings"]:
+            for warning in validation["warnings"]:
+                click.echo(f"  WARNING: {warning}")
+    else:
+        click.echo("Agent has errors:")
+        for error in validation["errors"]:
+            click.echo(f"  ERROR: {error}")
+    sys.exit(0 if validation["valid"] else 1)
+
+
+@cli.command()
+@click.option("--verbose", "-v", is_flag=True)
+def shell(verbose):
+    """Interactive session (CLI)."""
+    asyncio.run(_interactive_shell(verbose))
+
+
+async def _interactive_shell(verbose=False):
+    """Async interactive shell."""
+    setup_logging(verbose=verbose)
+
+    click.echo("=== Twitter News Digest ===")
+    click.echo("Enter a request (or 'quit' to exit):\n")
+
+    agent = TwitterNewsAgent()
+    await agent.start()
+
+    try:
+        while True:
+            try:
+                query = await asyncio.get_event_loop().run_in_executor(
+                    None, input, "News> "
+                )
+                if query.lower() in ["quit", "exit", "q"]:
+                    click.echo("Goodbye!")
+                    break
+
+                if not query.strip():
+                    continue
+
+                click.echo("\nFetching news...\n")
+
+                result = await agent.run({"user_request": query})
+
+                if result.success:
+                    click.echo("\nDigest complete\n")
+                else:
+                    click.echo(f"\nDigest failed: {result.error}\n")
+
+            except KeyboardInterrupt:
+                click.echo("\nGoodbye!")
+                break
+            except Exception as e:
+                click.echo(f"Error: {e}", err=True)
+    finally:
+        await agent.stop()
+
+
+if __name__ == "__main__":
+    cli()

examples/templates/twitter_news_agent/agent.py

@@ -0,0 +1,241 @@
+"""Agent graph construction for Twitter News Digest."""
+
+from pathlib import Path
+
+from framework.graph import EdgeSpec, EdgeCondition, Goal, SuccessCriterion, Constraint
+from framework.graph.edge import GraphSpec
+from framework.graph.executor import ExecutionResult
+from framework.graph.checkpoint_config import CheckpointConfig
+from framework.llm import LiteLLMProvider
+from framework.runner.tool_registry import ToolRegistry
+from framework.runtime.agent_runtime import create_agent_runtime
+from framework.runtime.execution_stream import EntryPointSpec
+
+from .config import default_config, metadata
+from .nodes import fetch_node, process_node, review_node
+
+# Goal definition
+goal = Goal(
+    id="twitter-news-goal",
+    name="Twitter News Digest",
+    description="Achieve an accurate and concise daily news digest based on Twitter feed monitoring.",
+    success_criteria=[
+        SuccessCriterion(
+            id="sc-1",
+            description="Navigate and extract tweets from at least 3 handles.",
+            metric="handle_count",
+            target=">=3",
+            weight=0.4,
+        ),
+        SuccessCriterion(
+            id="sc-2",
+            description="Provide a summary of the most important stories.",
+            metric="summary_quality",
+            target="high",
+            weight=0.4,
+        ),
+        SuccessCriterion(
+            id="sc-3",
+            description="Maintain a persistent log of daily digests.",
+            metric="file_exists",
+            target="true",
+            weight=0.2,
+        ),
+    ],
+    constraints=[
+        Constraint(
+            id="c-1",
+            description="Respect rate limits and ethical web usage.",
+            constraint_type="hard",
+            category="functional",
+        ),
+    ],
+)
+
+# Node list
+nodes = [fetch_node, process_node, review_node]
+
+# Edge definitions
+edges = [
+    # Process tweets then review
+    EdgeSpec(
+        id="process-to-review",
+        source="process-news",
+        target="review-digest",
+        condition=EdgeCondition.ON_SUCCESS,
+        priority=1,
+    ),
+    # Feedback loop if revisions needed
+    EdgeSpec(
+        id="review-to-process",
+        source="review-digest",
+        target="process-news",
+        condition=EdgeCondition.CONDITIONAL,
+        condition_expr="str(status).lower() == 'revise'",
+        priority=2,
+    ),
+    # Loop back for next run (forever-alive)
+    EdgeSpec(
+        id="review-done",
+        source="review-digest",
+        target="process-news",
+        condition=EdgeCondition.CONDITIONAL,
+        condition_expr="str(status).lower() == 'approved'",
+        priority=1,
+    ),
+]
+
+# Entry point is the autonomous processing node (queen handles intake)
+entry_node = "process-news"
+entry_points = {"start": "process-news"}
+pause_nodes = []
+terminal_nodes = []  # Forever-alive
+
+# Module-level vars read by AgentRunner.load()
+conversation_mode = "continuous"
+identity_prompt = "You are a professional news analyst and researcher."
+loop_config = {
+    "max_iterations": 100,
+    "max_tool_calls_per_turn": 20,
+    "max_history_tokens": 32000,
+}
+
+
+class TwitterNewsAgent:
+    def __init__(self, config=None):
+        self.config = config or default_config
+        self.goal = goal
+        self.nodes = nodes
+        self.edges = edges
+        self.entry_node = entry_node
+        self.entry_points = entry_points
+        self.pause_nodes = pause_nodes
+        self.terminal_nodes = terminal_nodes
+        self._graph = None
+        self._agent_runtime = None
+        self._tool_registry = None
+        self._storage_path = None
+
+    def _build_graph(self):
+        return GraphSpec(
+            id="twitter-news-graph",
+            goal_id=self.goal.id,
+            version="1.0.0",
+            entry_node=self.entry_node,
+            entry_points=self.entry_points,
+            terminal_nodes=self.terminal_nodes,
+            pause_nodes=self.pause_nodes,
+            nodes=self.nodes,
+            edges=self.edges,
+            default_model=self.config.model,
+            max_tokens=self.config.max_tokens,
+            loop_config=loop_config,
+            conversation_mode=conversation_mode,
+            identity_prompt=identity_prompt,
+        )
+
+    def _setup(self):
+        self._storage_path = Path.home() / ".hive" / "agents" / "twitter_news_agent"
+        self._storage_path.mkdir(parents=True, exist_ok=True)
+        self._tool_registry = ToolRegistry()
+        mcp_config = Path(__file__).parent / "mcp_servers.json"
+        if mcp_config.exists():
+            self._tool_registry.load_mcp_config(mcp_config)
+        llm = LiteLLMProvider(
+            model=self.config.model,
+            api_key=self.config.api_key,
+            api_base=self.config.api_base,
+        )
+        tools = list(self._tool_registry.get_tools().values())
+        tool_executor = self._tool_registry.get_executor()
+        self._graph = self._build_graph()
+        self._agent_runtime = create_agent_runtime(
+            graph=self._graph,
+            goal=self.goal,
+            storage_path=self._storage_path,
+            entry_points=[
+                EntryPointSpec(
+                    id="default",
+                    name="Default",
+                    entry_node=self.entry_node,
+                    trigger_type="manual",
+                    isolation_level="shared",
+                )
+            ],
+            llm=llm,
+            tools=tools,
+            tool_executor=tool_executor,
+            checkpoint_config=CheckpointConfig(
+                enabled=True,
+                checkpoint_on_node_complete=True,
+                checkpoint_max_age_days=7,
+                async_checkpoint=True,
+            ),
+        )
+
+    async def start(self):
+        if self._agent_runtime is None:
+            self._setup()
+        if not self._agent_runtime.is_running:
+            await self._agent_runtime.start()
+
+    async def stop(self):
+        if self._agent_runtime and self._agent_runtime.is_running:
+            await self._agent_runtime.stop()
+        self._agent_runtime = None
+
+    async def trigger_and_wait(
+        self, entry_point="default", input_data=None, timeout=None, session_state=None
+    ):
+        if self._agent_runtime is None:
+            raise RuntimeError("Agent not started. Call start() first.")
+        return await self._agent_runtime.trigger_and_wait(
+            entry_point_id=entry_point,
+            input_data=input_data or {},
+            session_state=session_state,
+        )
+
+    async def run(self, context, session_state=None):
+        await self.start()
+        try:
+            result = await self.trigger_and_wait(
+                "default", context, session_state=session_state
+            )
+            return result or ExecutionResult(success=False, error="Execution timeout")
+        finally:
+            await self.stop()
+
+    def info(self):
+        return {
+            "name": metadata.name,
+            "version": metadata.version,
+            "description": metadata.description,
+            "goal": {"name": self.goal.name, "description": self.goal.description},
+            "nodes": [n.id for n in self.nodes],
+            "edges": [e.id for e in self.edges],
+            "entry_node": self.entry_node,
+            "entry_points": self.entry_points,
+            "terminal_nodes": self.terminal_nodes,
+            "client_facing_nodes": [n.id for n in self.nodes if n.client_facing],
+        }
+
+    def validate(self):
+        errors, warnings = [], []
+        node_ids = {n.id for n in self.nodes}
+        for e in self.edges:
+            if e.source not in node_ids:
+                errors.append(f"Edge {e.id}: source '{e.source}' not found")
+            if e.target not in node_ids:
+                errors.append(f"Edge {e.id}: target '{e.target}' not found")
+        if self.entry_node not in node_ids:
+            errors.append(f"Entry node '{self.entry_node}' not found")
+        for t in self.terminal_nodes:
+            if t not in node_ids:
+                errors.append(f"Terminal node '{t}' not found")
+        for ep_id, nid in self.entry_points.items():
+            if nid not in node_ids:
+                errors.append(f"Entry point '{ep_id}' references unknown node '{nid}'")
+        return {"valid": len(errors) == 0, "errors": errors, "warnings": warnings}
+
+
+default_agent = TwitterNewsAgent()

examples/templates/twitter_news_agent/config.py

@@ -0,0 +1,20 @@
+"""Runtime configuration."""
+
+from dataclasses import dataclass
+
+from framework.config import RuntimeConfig
+
+default_config = RuntimeConfig()
+
+
+@dataclass
+class AgentMetadata:
+    name: str = "Twitter News Digest"
+    version: str = "1.1.0"
+    description: str = (
+        "Monitors Twitter feeds and provides a daily news digest, focused on tech news."
+    )
+    intro_message: str = "I'm ready to fetch the latest tech news from Twitter. Which tech handles should I check?"
+
+
+metadata = AgentMetadata()

examples/templates/twitter_news_agent/mcp_servers.json

@@ -0,0 +1,16 @@
+{
+  "hive-tools": {
+    "transport": "stdio",
+    "command": "uv",
+    "args": ["run", "python", "mcp_server.py", "--stdio"],
+    "cwd": "../../../tools",
+    "description": "Hive tools MCP server"
+  },
+  "gcu-tools": {
+    "transport": "stdio",
+    "command": "uv",
+    "args": ["run", "python", "-m", "gcu.server", "--stdio"],
+    "cwd": "../../../tools",
+    "description": "GCU tools for browser automation"
+  }
+}

examples/templates/twitter_news_agent/nodes/__init__.py

@@ -0,0 +1,86 @@
+"""Node definitions for Twitter News Digest."""
+
+from framework.graph import NodeSpec
+
+# Node 1: Browser subagent (GCU) to fetch tweets
+fetch_node = NodeSpec(
+    id="fetch-tweets",
+    name="Fetch Tech Tweets",
+    description="Browser subagent to navigate to tech news Twitter profiles and extract latest tweets.",
+    node_type="gcu",
+    client_facing=False,
+    max_node_visits=1,
+    input_keys=["twitter_handles"],
+    output_keys=["raw_tweets"],
+    tools=[],  # Auto-populated with browser tools
+    system_prompt="""\
+You are a specialized tech news researcher.
+Your task is to navigate to the provided tech Twitter profiles and extract the latest 10 tweets from each.
+
+## Target Content
+Focus on:
+- Major software/AI releases
+- Tech company earnings/acquisitions
+- Hardware/Silicon breakthroughs
+
+## Instructions
+1. browser_start
+2. For each handle:
+   a. browser_open(url=f"https://x.com/{handle}")
+   b. browser_wait(seconds=5)
+   c. browser_snapshot
+   d. Parse relevant tech news text
+3. set_output("raw_tweets", consolidated_json)
+""",
+)
+
+# Node 2: Process and summarize (autonomous)
+process_node = NodeSpec(
+    id="process-news",
+    name="Process Tech News",
+    description="Analyze and summarize the raw tweets into a daily tech digest.",
+    node_type="event_loop",
+    sub_agents=["fetch-tweets"],
+    input_keys=["user_request", "feedback", "raw_tweets"],
+    output_keys=["daily_digest"],
+    nullable_output_keys=["feedback", "raw_tweets"],
+    success_criteria="A high-quality, tech-focused news summary.",
+    system_prompt="""\
+You are a senior technology editor.
+If "raw_tweets" is missing, call delegate_to_sub_agent(agent_id="fetch-tweets", task="Fetch tech news from @TechCrunch, @verge, @WIRED, @CNET, @engadget, @Gizmodo, @TheRegister, @ArsTechnica, @ZDNet, @venturebeat, @AndrewYNg, @ylecun, @geoffreyhinton, @goodfellow_ian, @drfeifei, @hardmaru, @tegmark, @GaryMarcus, @schmidhuberAI, @fastdotai").
+
+Once tech tweets are available:
+1. Synthesize a "Daily Tech Report" highlighting major breakthroughs.
+2. Save the report using save_data(filename="daily_tech_report.txt", data=summary).
+3. set_output("daily_digest", summary)
+""",
+    tools=["save_data", "load_data"],
+)
+
+# Node 3: Review (client-facing)
+review_node = NodeSpec(
+    id="review-digest",
+    name="Review Digest",
+    description="Present the news digest for user review and approval.",
+    node_type="event_loop",
+    client_facing=True,
+    input_keys=["daily_digest"],
+    output_keys=["status", "feedback"],
+    nullable_output_keys=["feedback"],
+    success_criteria="User has reviewed the digest and provided feedback or approval.",
+    system_prompt="""\
+Present the daily news digest to the user.
+
+**STEP 1 — Present (text only, NO tool calls):**
+Display the summary and ask:
+1. Is this summary helpful?
+2. Are there specific handles or topics you'd like to focus on for tomorrow?
+
+**STEP 2 — After user responds, call set_output:**
+- set_output("status", "approved") if satisfied.
+- set_output("status", "revise") and set_output("feedback", "...") if changes are needed.
+""",
+    tools=[],
+)
+
+__all__ = ["fetch_node", "process_node", "review_node"]

hive.ps1

@@ -78,5 +78,6 @@ if (-not $env:HIVE_CREDENTIAL_KEY) {
 }
 
 # ── Run the Hive CLI ────────────────────────────────────────────────
-
+# PYTHONUTF8=1: use UTF-8 for default encoding (fixes charmap decode errors on Windows)
+$env:PYTHONUTF8 = "1"
 & uv run hive @args

quickstart.ps1

@@ -130,8 +130,8 @@ function Test-DefenderExclusions {
     
     # Normalize and filter null/empty values
     $safePrefixes = $safePrefixes | Where-Object { $_ } | ForEach-Object {
-        [System.IO.Path]::GetFullPath($_)
-    }
+        try { [System.IO.Path]::GetFullPath($_) } catch { $null }
+    } | Where-Object { $_ }
     
     try {
         # Check if Defender cmdlets are available (may not exist on older Windows)
@@ -157,15 +157,20 @@ function Test-DefenderExclusions {
         $existing = $prefs.ExclusionPath
         if (-not $existing) { $existing = @() }
         
-        # Normalize existing paths for comparison
+        # Normalize existing paths for comparison (some may contain wildcards
+        # or env vars that GetFullPath rejects — skip those gracefully)
         $existing = $existing | Where-Object { $_ } | ForEach-Object {
-            [System.IO.Path]::GetFullPath($_)
+            try { [System.IO.Path]::GetFullPath($_) } catch { $_ }
         }
         
         # Normalize paths and find missing exclusions
         $missing = @()
         foreach ($path in $Paths) {
+            try {
                 $normalized = [System.IO.Path]::GetFullPath($path)
+            } catch {
+                continue  # Skip paths with unsupported format
+            }
             
             # Security: Ensure path is within safe boundaries
             $isSafe = $false
@@ -249,8 +254,12 @@ function Add-DefenderExclusions {
     $failed = @()
     
     foreach ($path in $Paths) {
+        try {
             try {
                 $normalized = [System.IO.Path]::GetFullPath($path)
+            } catch {
+                $normalized = $path  # Use raw path if normalization fails
+            }
             Add-MpPreference -ExclusionPath $normalized -ErrorAction Stop
             $added += $normalized
         } catch {
@@ -408,6 +417,58 @@ Write-Ok "uv detected: $uvVersion"
 Write-Host ""
 
 # Check for Node.js (needed for frontend dashboard)
+function Install-NodeViaFnm {
+    <#
+    .SYNOPSIS
+        Install Node.js 20 via fnm (Fast Node Manager) - mirrors nvm approach in quickstart.sh
+    #>
+    $fnmCmd = Get-Command fnm -ErrorAction SilentlyContinue
+    if (-not $fnmCmd) {
+        $fnmDir = Join-Path $env:LOCALAPPDATA "fnm"
+        $fnmExe = Join-Path $fnmDir "fnm.exe"
+        if (-not (Test-Path $fnmExe)) {
+            try {
+                Write-Host "    Downloading fnm (Fast Node Manager)..." -ForegroundColor DarkGray
+                $zipUrl = "https://github.com/Schniz/fnm/releases/latest/download/fnm-windows.zip"
+                $zipPath = Join-Path $env:TEMP "fnm-install.zip"
+                Invoke-WebRequest -Uri $zipUrl -OutFile $zipPath -UseBasicParsing -ErrorAction Stop
+                if (-not (Test-Path $fnmDir)) { New-Item -ItemType Directory -Path $fnmDir -Force | Out-Null }
+                Expand-Archive -Path $zipPath -DestinationPath $fnmDir -Force
+                Remove-Item $zipPath -Force -ErrorAction SilentlyContinue
+            } catch {
+                Write-Fail "fnm download failed"
+                Write-Host "    Install Node.js 20+ manually from https://nodejs.org" -ForegroundColor DarkGray
+                return $false
+            }
+        }
+        if (Test-Path (Join-Path $fnmDir "fnm.exe")) {
+            $env:PATH = "$fnmDir;$env:PATH"
+        } else {
+            Write-Fail "fnm binary not found after download"
+            Write-Host "    Install Node.js 20+ manually from https://nodejs.org" -ForegroundColor DarkGray
+            return $false
+        }
+    }
+
+    try {
+        $null = & fnm install 20 2>&1
+        if ($LASTEXITCODE -ne 0) { throw "fnm install 20 exited with code $LASTEXITCODE" }
+        & fnm env --use-on-cd --shell powershell | Out-String | Invoke-Expression
+        $null = & fnm use 20 2>&1
+        $testNode = Get-Command node -ErrorAction SilentlyContinue
+        if ($testNode) {
+            $ver = & node --version 2>$null
+            Write-Ok "Node.js $ver installed via fnm"
+            return $true
+        }
+        throw "node not found after fnm install"
+    } catch {
+        Write-Fail "Node.js installation failed"
+        Write-Host "    Install manually from https://nodejs.org" -ForegroundColor DarkGray
+        return $false
+    }
+}
+
 $NodeAvailable = $false
 $nodeCmd = Get-Command node -ErrorAction SilentlyContinue
 if ($nodeCmd) {
@@ -419,12 +480,13 @@ if ($nodeCmd) {
             $NodeAvailable = $true
         } else {
             Write-Warn "Node.js $nodeVersion found (20+ required for frontend dashboard)"
-            Write-Host "    Install from https://nodejs.org" -ForegroundColor DarkGray
+            Write-Host "    Installing Node.js 20 via fnm..." -ForegroundColor Yellow
+            $NodeAvailable = Install-NodeViaFnm
         }
     }
 } else {
-    Write-Warn "Node.js not found (optional, needed for web dashboard)"
-    Write-Host "    Install from https://nodejs.org" -ForegroundColor DarkGray
+    Write-Warn "Node.js not found. Installing via fnm..."
+    $NodeAvailable = Install-NodeViaFnm
 }
 Write-Host ""
 
@@ -736,8 +798,8 @@ $ProviderMap = [ordered]@{
 }
 
 $DefaultModels = @{
-    anthropic   = "claude-opus-4-6"
-    openai      = "gpt-5.2"
+    anthropic   = "claude-haiku-4-5-20251001"
+    openai      = "gpt-5-mini"
     gemini      = "gemini-3-flash-preview"
     groq        = "moonshotai/kimi-k2-instruct-0905"
     cerebras    = "zai-glm-4.7"
@@ -749,14 +811,14 @@ $DefaultModels = @{
 # Model choices: array of hashtables per provider
 $ModelChoices = @{
     anthropic = @(
-        @{ Id = "claude-opus-4-6";            Label = "Opus 4.6 - Most capable (recommended)"; MaxTokens = 32768 },
-        @{ Id = "claude-sonnet-4-5-20250929"; Label = "Sonnet 4.5 - Best balance";             MaxTokens = 16384 },
+        @{ Id = "claude-haiku-4-5-20251001";  Label = "Haiku 4.5 - Fast + cheap (recommended)"; MaxTokens = 8192 },
         @{ Id = "claude-sonnet-4-20250514";   Label = "Sonnet 4 - Fast + capable";              MaxTokens = 8192 },
-        @{ Id = "claude-haiku-4-5-20251001";  Label = "Haiku 4.5 - Fast + cheap";              MaxTokens = 8192 }
+        @{ Id = "claude-sonnet-4-5-20250929"; Label = "Sonnet 4.5 - Best balance";              MaxTokens = 16384 },
+        @{ Id = "claude-opus-4-6";            Label = "Opus 4.6 - Most capable";                MaxTokens = 32768 }
     )
     openai = @(
-        @{ Id = "gpt-5.2";   Label = "GPT-5.2 - Most capable (recommended)"; MaxTokens = 16384 },
-        @{ Id = "gpt-5-mini"; Label = "GPT-5 Mini - Fast + cheap";            MaxTokens = 16384 }
+        @{ Id = "gpt-5-mini"; Label = "GPT-5 Mini - Fast + cheap (recommended)"; MaxTokens = 16384 },
+        @{ Id = "gpt-5.2";   Label = "GPT-5.2 - Most capable";                   MaxTokens = 16384 }
     )
     gemini = @(
         @{ Id = "gemini-3-flash-preview"; Label = "Gemini 3 Flash - Fast (recommended)"; MaxTokens = 8192 },
@@ -783,6 +845,17 @@ function Get-ModelSelection {
         return @{ Model = $choices[0].Id; MaxTokens = $choices[0].MaxTokens }
     }
 
+    # Find default index from previous model (if same provider)
+    $defaultIdx = "1"
+    if ($PrevModel -and $PrevProvider -eq $ProviderId) {
+        for ($j = 0; $j -lt $choices.Count; $j++) {
+            if ($choices[$j].Id -eq $PrevModel) {
+                $defaultIdx = [string]($j + 1)
+                break
+            }
+        }
+    }
+
     Write-Host ""
     Write-Color -Text "Select a model:" -Color White
     Write-Host ""
@@ -794,8 +867,8 @@ function Get-ModelSelection {
     Write-Host ""
 
     while ($true) {
-        $raw = Read-Host "Enter choice [1]"
-        if ([string]::IsNullOrWhiteSpace($raw)) { $raw = "1" }
+        $raw = Read-Host "Enter choice [$defaultIdx]"
+        if ([string]::IsNullOrWhiteSpace($raw)) { $raw = $defaultIdx }
         if ($raw -match '^\d+$') {
             $num = [int]$raw
             if ($num -ge 1 -and $num -le $choices.Count) {
@@ -851,6 +924,60 @@ $ProviderMenuUrls     = @(
     "https://cloud.cerebras.ai/"
 )
 
+# ── Read previous configuration (if any) ──────────────────────
+$PrevProvider = ""
+$PrevModel = ""
+$PrevEnvVar = ""
+$PrevSubMode = ""
+if (Test-Path $HiveConfigFile) {
+    try {
+        $prevConfig = Get-Content -Path $HiveConfigFile -Raw | ConvertFrom-Json
+        $prevLlm = $prevConfig.llm
+        if ($prevLlm) {
+            $PrevProvider = if ($prevLlm.provider) { $prevLlm.provider } else { "" }
+            $PrevModel = if ($prevLlm.model) { $prevLlm.model } else { "" }
+            $PrevEnvVar = if ($prevLlm.api_key_env_var) { $prevLlm.api_key_env_var } else { "" }
+            if ($prevLlm.use_claude_code_subscription) { $PrevSubMode = "claude_code" }
+            elseif ($prevLlm.use_codex_subscription) { $PrevSubMode = "codex" }
+            elseif ($prevLlm.api_base -and $prevLlm.api_base -like "*api.z.ai*") { $PrevSubMode = "zai_code" }
+        }
+    } catch { }
+}
+
+# Compute default menu number (only if credential is still valid)
+$DefaultChoice = ""
+if ($PrevSubMode -or $PrevProvider) {
+    $prevCredValid = $false
+    switch ($PrevSubMode) {
+        "claude_code" { if ($ClaudeCredDetected) { $prevCredValid = $true } }
+        "zai_code"    { if ($ZaiCredDetected)    { $prevCredValid = $true } }
+        "codex"       { if ($CodexCredDetected)  { $prevCredValid = $true } }
+        default {
+            if ($PrevEnvVar) {
+                $envVal = [System.Environment]::GetEnvironmentVariable($PrevEnvVar, "Process")
+                if (-not $envVal) { $envVal = [System.Environment]::GetEnvironmentVariable($PrevEnvVar, "User") }
+                if ($envVal) { $prevCredValid = $true }
+            }
+        }
+    }
+    if ($prevCredValid) {
+        switch ($PrevSubMode) {
+            "claude_code" { $DefaultChoice = "1" }
+            "zai_code"    { $DefaultChoice = "2" }
+            "codex"       { $DefaultChoice = "3" }
+        }
+        if (-not $DefaultChoice) {
+            switch ($PrevProvider) {
+                "anthropic" { $DefaultChoice = "4" }
+                "openai"    { $DefaultChoice = "5" }
+                "gemini"    { $DefaultChoice = "6" }
+                "groq"      { $DefaultChoice = "7" }
+                "cerebras"  { $DefaultChoice = "8" }
+            }
+        }
+    }
+}
+
 # ── Show unified provider selection menu ─────────────────────
 Write-Color -Text "Select your default LLM provider:" -Color White
 Write-Host ""
@@ -896,8 +1023,18 @@ Write-Color -Text "9" -Color Cyan -NoNewline
 Write-Host ") Skip for now"
 Write-Host ""
 
+if ($DefaultChoice) {
+    Write-Color -Text "  Previously configured: $PrevProvider/$PrevModel. Press Enter to keep." -Color DarkGray
+    Write-Host ""
+}
+
 while ($true) {
+    if ($DefaultChoice) {
+        $raw = Read-Host "Enter choice (1-9) [$DefaultChoice]"
+        if ([string]::IsNullOrWhiteSpace($raw)) { $raw = $DefaultChoice }
+    } else {
         $raw = Read-Host "Enter choice (1-9)"
+    }
     if ($raw -match '^\d+$') {
         $num = [int]$raw
         if ($num -ge 1 -and $num -le 9) { break }
@@ -974,28 +1111,68 @@ switch ($num) {
         $providerName       = $ProviderMenuNames[$provIdx] -replace ' - .*', ''  # strip description
         $signupUrl          = $ProviderMenuUrls[$provIdx]
 
-        # Check if key is already set
+        # Prompt for key (allow replacement if already set) with verification + retry
+        while ($true) {
             $existingKey = [System.Environment]::GetEnvironmentVariable($SelectedEnvVar, "User")
             if (-not $existingKey) { $existingKey = [System.Environment]::GetEnvironmentVariable($SelectedEnvVar, "Process") }
-        if (-not $existingKey) {
+
+            if ($existingKey) {
+                $masked = $existingKey.Substring(0, [Math]::Min(4, $existingKey.Length)) + "..." + $existingKey.Substring([Math]::Max(0, $existingKey.Length - 4))
+                Write-Host ""
+                Write-Color -Text "  $([char]0x2B22) Current key: $masked" -Color Green
+                $apiKey = Read-Host "  Press Enter to keep, or paste a new key to replace"
+            } else {
                 Write-Host ""
                 Write-Host "Get your API key from: " -NoNewline
                 Write-Color -Text $signupUrl -Color Cyan
                 Write-Host ""
                 $apiKey = Read-Host "Paste your $providerName API key (or press Enter to skip)"
+            }
 
             if ($apiKey) {
                 [System.Environment]::SetEnvironmentVariable($SelectedEnvVar, $apiKey, "User")
                 Set-Item -Path "Env:\$SelectedEnvVar" -Value $apiKey
                 Write-Host ""
                 Write-Ok "API key saved as User environment variable: $SelectedEnvVar"
-                Write-Color -Text "  (Persisted for all future sessions)" -Color DarkGray
+
+                # Health check the new key
+                Write-Host "  Verifying API key... " -NoNewline
+                try {
+                    $hcResult = & uv run python (Join-Path $ScriptDir "scripts/check_llm_key.py") $SelectedProviderId $apiKey 2>$null
+                    $hcJson = $hcResult | ConvertFrom-Json
+                    if ($hcJson.valid -eq $true) {
+                        Write-Color -Text "ok" -Color Green
+                        break
+                    } elseif ($hcJson.valid -eq $false) {
+                        Write-Color -Text "failed" -Color Red
+                        Write-Warn $hcJson.message
+                        # Undo the save so user can retry cleanly
+                        [System.Environment]::SetEnvironmentVariable($SelectedEnvVar, $null, "User")
+                        Remove-Item -Path "Env:\$SelectedEnvVar" -ErrorAction SilentlyContinue
+                        Write-Host ""
+                        Read-Host "  Press Enter to try again"
+                        # loop back to key prompt
                     } else {
+                        Write-Color -Text "--" -Color Yellow
+                        Write-Color -Text "  Could not verify key (network issue). The key has been saved." -Color DarkGray
+                        break
+                    }
+                } catch {
+                    Write-Color -Text "--" -Color Yellow
+                    Write-Color -Text "  Could not verify key (network issue). The key has been saved." -Color DarkGray
+                    break
+                }
+            } elseif (-not $existingKey) {
+                # No existing key and user skipped
                 Write-Host ""
                 Write-Warn "Skipped. Set the environment variable manually when ready:"
                 Write-Host "  [System.Environment]::SetEnvironmentVariable('$SelectedEnvVar', 'your-key', 'User')"
                 $SelectedEnvVar     = ""
                 $SelectedProviderId = ""
+                break
+            } else {
+                # User pressed Enter with existing key — keep it
+                break
             }
         }
     }
@@ -1011,26 +1188,67 @@ switch ($num) {
     }
 }
 
-# For ZAI subscription: prompt for API key if not already set
+# For ZAI subscription: prompt for API key (allow replacement if already set) with verification + retry
 if ($SubscriptionMode -eq "zai_code") {
+    while ($true) {
         $existingZai = [System.Environment]::GetEnvironmentVariable("ZAI_API_KEY", "User")
         if (-not $existingZai) { $existingZai = $env:ZAI_API_KEY }
-    if (-not $existingZai) {
+
+        if ($existingZai) {
+            $masked = $existingZai.Substring(0, [Math]::Min(4, $existingZai.Length)) + "..." + $existingZai.Substring([Math]::Max(0, $existingZai.Length - 4))
+            Write-Host ""
+            Write-Color -Text "  $([char]0x2B22) Current ZAI key: $masked" -Color Green
+            $apiKey = Read-Host "  Press Enter to keep, or paste a new key to replace"
+        } else {
             Write-Host ""
             $apiKey = Read-Host "Paste your ZAI API key (or press Enter to skip)"
+        }
 
         if ($apiKey) {
             [System.Environment]::SetEnvironmentVariable("ZAI_API_KEY", $apiKey, "User")
             $env:ZAI_API_KEY = $apiKey
             Write-Host ""
             Write-Ok "ZAI API key saved as User environment variable"
+
+            # Health check the new key
+            Write-Host "  Verifying ZAI API key... " -NoNewline
+            try {
+                $hcResult = & uv run python (Join-Path $ScriptDir "scripts/check_llm_key.py") "zai" $apiKey "https://api.z.ai/api/coding/paas/v4" 2>$null
+                $hcJson = $hcResult | ConvertFrom-Json
+                if ($hcJson.valid -eq $true) {
+                    Write-Color -Text "ok" -Color Green
+                    break
+                } elseif ($hcJson.valid -eq $false) {
+                    Write-Color -Text "failed" -Color Red
+                    Write-Warn $hcJson.message
+                    # Undo the save so user can retry cleanly
+                    [System.Environment]::SetEnvironmentVariable("ZAI_API_KEY", $null, "User")
+                    Remove-Item -Path "Env:\ZAI_API_KEY" -ErrorAction SilentlyContinue
+                    Write-Host ""
+                    Read-Host "  Press Enter to try again"
+                    # loop back to key prompt
                 } else {
+                    Write-Color -Text "--" -Color Yellow
+                    Write-Color -Text "  Could not verify key (network issue). The key has been saved." -Color DarkGray
+                    break
+                }
+            } catch {
+                Write-Color -Text "--" -Color Yellow
+                Write-Color -Text "  Could not verify key (network issue). The key has been saved." -Color DarkGray
+                break
+            }
+        } elseif (-not $existingZai) {
+            # No existing key and user skipped
             Write-Host ""
             Write-Warn "Skipped. Add your ZAI API key later:"
             Write-Color -Text "  [System.Environment]::SetEnvironmentVariable('ZAI_API_KEY', 'your-key', 'User')" -Color Cyan
             $SelectedEnvVar     = ""
             $SelectedProviderId = ""
             $SubscriptionMode   = ""
+            break
+        } else {
+            # User pressed Enter with existing key — keep it
+            break
         }
     }
 }
@@ -1081,37 +1299,18 @@ if ($SelectedProviderId) {
 Write-Host ""
 
 # ============================================================
-# Step 5b: Browser Automation (GCU)
+# Step 5b: Browser Automation (GCU) — always enabled
 # ============================================================
 
 Write-Host ""
-Write-Color -Text "Enable browser automation?" -Color White
-Write-Color -Text "This lets your agents control a real browser - navigate websites, fill forms," -Color DarkGray
-Write-Color -Text "scrape dynamic pages, and interact with web UIs." -Color DarkGray
-Write-Host ""
-Write-Host "  " -NoNewline; Write-Color -Text "1)" -Color Cyan -NoNewline; Write-Host " Yes"
-Write-Host "  " -NoNewline; Write-Color -Text "2)" -Color Cyan -NoNewline; Write-Host " No"
-Write-Host ""
-
-do {
-    $gcuChoice = Read-Host "Enter choice (1-2)"
-} while ($gcuChoice -ne "1" -and $gcuChoice -ne "2")
-
-$GcuEnabled = $false
-if ($gcuChoice -eq "1") {
-    $GcuEnabled = $true
 Write-Ok "Browser automation enabled"
-} else {
-    Write-Color -Text "  Browser automation skipped" -Color DarkGray
-}
 
 # Patch gcu_enabled into configuration.json
 if (Test-Path $HiveConfigFile) {
     $existingConfig = Get-Content -Path $HiveConfigFile -Raw | ConvertFrom-Json
-    $existingConfig | Add-Member -NotePropertyName "gcu_enabled" -NotePropertyValue $GcuEnabled -Force
+    $existingConfig | Add-Member -NotePropertyName "gcu_enabled" -NotePropertyValue $true -Force
     $existingConfig | ConvertTo-Json -Depth 4 | Set-Content -Path $HiveConfigFile -Encoding UTF8
-} elseif ($GcuEnabled) {
-    # No config file yet (user skipped LLM provider) - create minimal one
+} else {
     if (-not (Test-Path $HiveConfigDir)) {
         New-Item -ItemType Directory -Path $HiveConfigDir -Force | Out-Null
     }
@@ -1425,7 +1624,7 @@ if ($FrontendBuilt) {
     Write-Color -Text "  Starting server on http://localhost:8787" -Color DarkGray
     Write-Color -Text "  Press Ctrl+C to stop" -Color DarkGray
     Write-Host ""
-    & (Join-Path $ScriptDir "hive.ps1") serve --open
+    & (Join-Path $ScriptDir "hive.ps1") open
 } else {
     Write-Color -Text "═══════════════════════════════════════════════════════" -Color Yellow
     Write-Host ""

quickstart.sh

@@ -407,7 +407,7 @@ if [ "$USE_ASSOC_ARRAYS" = true ]; then
     )
 
     declare -A DEFAULT_MODELS=(
-        ["anthropic"]="claude-haiku-4-5"
+        ["anthropic"]="claude-haiku-4-5-20251001"
         ["openai"]="gpt-5-mini"
         ["gemini"]="gemini-3-flash-preview"
         ["groq"]="moonshotai/kimi-k2-instruct-0905"
@@ -420,12 +420,12 @@ if [ "$USE_ASSOC_ARRAYS" = true ]; then
     # Model choices per provider: composite-key associative arrays
     # Keys: "provider:index" -> value
     declare -A MODEL_CHOICES_ID=(
-        ["anthropic:0"]="claude-opus-4-6"
-        ["anthropic:1"]="claude-sonnet-4-5-20250929"
-        ["anthropic:2"]="claude-sonnet-4-20250514"
-        ["anthropic:3"]="claude-haiku-4-5-20251001"
-        ["openai:0"]="gpt-5.2"
-        ["openai:1"]="gpt-5-mini"
+        ["anthropic:0"]="claude-haiku-4-5-20251001"
+        ["anthropic:1"]="claude-sonnet-4-20250514"
+        ["anthropic:2"]="claude-sonnet-4-5-20250929"
+        ["anthropic:3"]="claude-opus-4-6"
+        ["openai:0"]="gpt-5-mini"
+        ["openai:1"]="gpt-5.2"
         ["gemini:0"]="gemini-3-flash-preview"
         ["gemini:1"]="gemini-3.1-pro-preview"
         ["groq:0"]="moonshotai/kimi-k2-instruct-0905"
@@ -435,12 +435,12 @@ if [ "$USE_ASSOC_ARRAYS" = true ]; then
     )
 
     declare -A MODEL_CHOICES_LABEL=(
-        ["anthropic:0"]="Opus 4.6 - Most capable (recommended)"
-        ["anthropic:1"]="Sonnet 4.5 - Best balance"
-        ["anthropic:2"]="Sonnet 4 - Fast + capable"
-        ["anthropic:3"]="Haiku 4.5 - Fast + cheap"
-        ["openai:0"]="GPT-5.2 - Most capable (recommended)"
-        ["openai:1"]="GPT-5 Mini - Fast + cheap"
+        ["anthropic:0"]="Haiku 4.5 - Fast + cheap (recommended)"
+        ["anthropic:1"]="Sonnet 4 - Fast + capable"
+        ["anthropic:2"]="Sonnet 4.5 - Best balance"
+        ["anthropic:3"]="Opus 4.6 - Most capable"
+        ["openai:0"]="GPT-5 Mini - Fast + cheap (recommended)"
+        ["openai:1"]="GPT-5.2 - Most capable"
         ["gemini:0"]="Gemini 3 Flash - Fast (recommended)"
         ["gemini:1"]="Gemini 3.1 Pro - Best quality"
         ["groq:0"]="Kimi K2 - Best quality (recommended)"
@@ -450,10 +450,10 @@ if [ "$USE_ASSOC_ARRAYS" = true ]; then
     )
 
     declare -A MODEL_CHOICES_MAXTOKENS=(
-        ["anthropic:0"]=32768
-        ["anthropic:1"]=16384
-        ["anthropic:2"]=8192
-        ["anthropic:3"]=8192
+        ["anthropic:0"]=8192
+        ["anthropic:1"]=8192
+        ["anthropic:2"]=16384
+        ["anthropic:3"]=32768
         ["openai:0"]=16384
         ["openai:1"]=16384
         ["gemini:0"]=8192
@@ -508,7 +508,7 @@ else
 
     # Default models by provider id (parallel arrays)
     MODEL_PROVIDER_IDS=(anthropic openai gemini groq cerebras mistral together_ai deepseek)
-    MODEL_DEFAULTS=("claude-opus-4-6" "gpt-5.2" "gemini-3-flash-preview" "moonshotai/kimi-k2-instruct-0905" "zai-glm-4.7" "mistral-large-latest" "meta-llama/Llama-3.3-70B-Instruct-Turbo" "deepseek-chat")
+    MODEL_DEFAULTS=("claude-haiku-4-5-20251001" "gpt-5-mini" "gemini-3-flash-preview" "moonshotai/kimi-k2-instruct-0905" "zai-glm-4.7" "mistral-large-latest" "meta-llama/Llama-3.3-70B-Instruct-Turbo" "deepseek-chat")
 
     # Helper: get provider display name for an env var
     get_provider_name() {
@@ -552,9 +552,9 @@ else
     # Model choices per provider - flat parallel arrays with provider offsets
     # Provider order: anthropic(4), openai(2), gemini(2), groq(2), cerebras(2)
     MC_PROVIDERS=(anthropic anthropic anthropic anthropic openai openai gemini gemini groq groq cerebras cerebras)
-    MC_IDS=("claude-opus-4-6" "claude-sonnet-4-5-20250929" "claude-sonnet-4-20250514" "claude-haiku-4-5-20251001" "gpt-5.2" "gpt-5-mini" "gemini-3-flash-preview" "gemini-3.1-pro-preview" "moonshotai/kimi-k2-instruct-0905" "openai/gpt-oss-120b" "zai-glm-4.7" "qwen3-235b-a22b-instruct-2507")
-    MC_LABELS=("Opus 4.6 - Most capable (recommended)" "Sonnet 4.5 - Best balance" "Sonnet 4 - Fast + capable" "Haiku 4.5 - Fast + cheap" "GPT-5.2 - Most capable (recommended)" "GPT-5 Mini - Fast + cheap" "Gemini 3 Flash - Fast (recommended)" "Gemini 3.1 Pro - Best quality" "Kimi K2 - Best quality (recommended)" "GPT-OSS 120B - Fast reasoning" "ZAI-GLM 4.7 - Best quality (recommended)" "Qwen3 235B - Frontier reasoning")
-    MC_MAXTOKENS=(32768 16384 8192 8192 16384 16384 8192 8192 8192 8192 8192 8192)
+    MC_IDS=("claude-haiku-4-5-20251001" "claude-sonnet-4-20250514" "claude-sonnet-4-5-20250929" "claude-opus-4-6" "gpt-5-mini" "gpt-5.2" "gemini-3-flash-preview" "gemini-3.1-pro-preview" "moonshotai/kimi-k2-instruct-0905" "openai/gpt-oss-120b" "zai-glm-4.7" "qwen3-235b-a22b-instruct-2507")
+    MC_LABELS=("Haiku 4.5 - Fast + cheap (recommended)" "Sonnet 4 - Fast + capable" "Sonnet 4.5 - Best balance" "Opus 4.6 - Most capable" "GPT-5 Mini - Fast + cheap (recommended)" "GPT-5.2 - Most capable" "Gemini 3 Flash - Fast (recommended)" "Gemini 3.1 Pro - Best quality" "Kimi K2 - Best quality (recommended)" "GPT-OSS 120B - Fast reasoning" "ZAI-GLM 4.7 - Best quality (recommended)" "Qwen3 235B - Frontier reasoning")
+    MC_MAXTOKENS=(8192 8192 16384 32768 16384 16384 8192 8192 8192 8192 8192 8192)
 
     # Helper: get number of model choices for a provider
     get_model_choice_count() {
@@ -687,6 +687,19 @@ prompt_model_selection() {
     echo -e "${BOLD}Select a model:${NC}"
     echo ""
 
+    # Find default index from previous model (if same provider)
+    local default_idx=""
+    if [ -n "$PREV_MODEL" ] && [ "$provider_id" = "$PREV_PROVIDER" ]; then
+        local j=0
+        while [ $j -lt "$count" ]; do
+            if [ "$(get_model_choice_id "$provider_id" "$j")" = "$PREV_MODEL" ]; then
+                default_idx=$((j + 1))
+                break
+            fi
+            j=$((j + 1))
+        done
+    fi
+
     local i=0
     while [ $i -lt "$count" ]; do
         local label
@@ -701,7 +714,12 @@ prompt_model_selection() {
 
     local choice
     while true; do
+        if [ -n "$default_idx" ]; then
+            read -r -p "Enter choice (1-$count) [$default_idx]: " choice || true
+            choice="${choice:-$default_idx}"
+        else
             read -r -p "Enter choice (1-$count): " choice || true
+        fi
         if [[ "$choice" =~ ^[0-9]+$ ]] && [ "$choice" -ge 1 ] && [ "$choice" -le "$count" ]; then
             local idx=$((choice - 1))
             SELECTED_MODEL="$(get_model_choice_id "$provider_id" "$idx")"
@@ -781,7 +799,9 @@ SUBSCRIPTION_MODE=""    # "claude_code" | "codex" | "zai_code" | ""
 
 # ── Credential detection (silent — just set flags) ───────────
 CLAUDE_CRED_DETECTED=false
-if [ -f "$HOME/.claude/.credentials.json" ]; then
+if command -v security &>/dev/null && security find-generic-password -s "Claude Code-credentials" &>/dev/null 2>&1; then
+    CLAUDE_CRED_DETECTED=true
+elif [ -f "$HOME/.claude/.credentials.json" ]; then
     CLAUDE_CRED_DETECTED=true
 fi
 
@@ -814,6 +834,65 @@ else
     done
 fi
 
+# ── Read previous configuration (if any) ──────────────────────
+PREV_PROVIDER=""
+PREV_MODEL=""
+PREV_ENV_VAR=""
+PREV_SUB_MODE=""
+if [ -f "$HIVE_CONFIG_FILE" ]; then
+    eval "$($PYTHON_CMD -c "
+import json, sys
+try:
+    with open('$HIVE_CONFIG_FILE') as f:
+        c = json.load(f)
+    llm = c.get('llm', {})
+    print(f'PREV_PROVIDER={llm.get(\"provider\", \"\")}')
+    print(f'PREV_MODEL={llm.get(\"model\", \"\")}')
+    print(f'PREV_ENV_VAR={llm.get(\"api_key_env_var\", \"\")}')
+    sub = ''
+    if llm.get('use_claude_code_subscription'): sub = 'claude_code'
+    elif llm.get('use_codex_subscription'): sub = 'codex'
+    elif 'api.z.ai' in llm.get('api_base', ''): sub = 'zai_code'
+    print(f'PREV_SUB_MODE={sub}')
+except Exception:
+    pass
+" 2>/dev/null)" || true
+fi
+
+# Compute default menu number from previous config (only if credential is still valid)
+DEFAULT_CHOICE=""
+if [ -n "$PREV_SUB_MODE" ] || [ -n "$PREV_PROVIDER" ]; then
+    PREV_CRED_VALID=false
+    case "$PREV_SUB_MODE" in
+        claude_code) [ "$CLAUDE_CRED_DETECTED" = true ] && PREV_CRED_VALID=true ;;
+        zai_code)    [ "$ZAI_CRED_DETECTED" = true ] && PREV_CRED_VALID=true ;;
+        codex)       [ "$CODEX_CRED_DETECTED" = true ] && PREV_CRED_VALID=true ;;
+        *)
+            # API key provider — check if the env var is set
+            if [ -n "$PREV_ENV_VAR" ] && [ -n "${!PREV_ENV_VAR}" ]; then
+                PREV_CRED_VALID=true
+            fi
+            ;;
+    esac
+
+    if [ "$PREV_CRED_VALID" = true ]; then
+        case "$PREV_SUB_MODE" in
+            claude_code) DEFAULT_CHOICE=1 ;;
+            zai_code)    DEFAULT_CHOICE=2 ;;
+            codex)       DEFAULT_CHOICE=3 ;;
+        esac
+        if [ -z "$DEFAULT_CHOICE" ]; then
+            case "$PREV_PROVIDER" in
+                anthropic) DEFAULT_CHOICE=4 ;;
+                openai)    DEFAULT_CHOICE=5 ;;
+                gemini)    DEFAULT_CHOICE=6 ;;
+                groq)      DEFAULT_CHOICE=7 ;;
+                cerebras)  DEFAULT_CHOICE=8 ;;
+            esac
+        fi
+    fi
+fi
+
 # ── Show unified provider selection menu ─────────────────────
 echo -e "${BOLD}Select your default LLM provider:${NC}"
 echo ""
@@ -858,8 +937,18 @@ done
 echo -e "  ${CYAN}9)${NC} Skip for now"
 echo ""
 
+if [ -n "$DEFAULT_CHOICE" ]; then
+    echo -e "  ${DIM}Previously configured: ${PREV_PROVIDER}/${PREV_MODEL}. Press Enter to keep.${NC}"
+    echo ""
+fi
+
 while true; do
+    if [ -n "$DEFAULT_CHOICE" ]; then
+        read -r -p "Enter choice (1-9) [$DEFAULT_CHOICE]: " choice || true
+        choice="${choice:-$DEFAULT_CHOICE}"
+    else
         read -r -p "Enter choice (1-9): " choice || true
+    fi
     if [[ "$choice" =~ ^[0-9]+$ ]] && [ "$choice" -ge 1 ] && [ "$choice" -le 9 ]; then
         break
     fi
@@ -968,48 +1057,132 @@ case $choice in
         ;;
 esac
 
-# For API-key providers: prompt for key if not already set
-if [ -z "$SUBSCRIPTION_MODE" ] && [ -n "$SELECTED_ENV_VAR" ] && [ -z "${!SELECTED_ENV_VAR}" ]; then
+# For API-key providers: prompt for key (allow replacement if already set)
+if [ -z "$SUBSCRIPTION_MODE" ] && [ -n "$SELECTED_ENV_VAR" ]; then
+    while true; do
+        CURRENT_KEY="${!SELECTED_ENV_VAR}"
+        if [ -n "$CURRENT_KEY" ]; then
+            # Key exists — offer to keep or replace
+            MASKED_KEY="${CURRENT_KEY:0:4}...${CURRENT_KEY: -4}"
+            echo ""
+            echo -e "  ${GREEN}⬢${NC} Current key: ${DIM}$MASKED_KEY${NC}"
+            read -r -p "  Press Enter to keep, or paste a new key to replace: " API_KEY
+        else
+            # No key — prompt for one
             echo ""
             echo -e "Get your API key from: ${CYAN}$SIGNUP_URL${NC}"
             echo ""
             read -r -p "Paste your $PROVIDER_NAME API key (or press Enter to skip): " API_KEY
+        fi
 
         if [ -n "$API_KEY" ]; then
+            # Remove old export line(s) for this env var from shell rc, then append new
+            sed -i.bak "/^export ${SELECTED_ENV_VAR}=/d" "$SHELL_RC_FILE" && rm -f "${SHELL_RC_FILE}.bak"
             echo "" >> "$SHELL_RC_FILE"
             echo "# Hive Agent Framework - $PROVIDER_NAME API key" >> "$SHELL_RC_FILE"
             echo "export $SELECTED_ENV_VAR=\"$API_KEY\"" >> "$SHELL_RC_FILE"
             export "$SELECTED_ENV_VAR=$API_KEY"
             echo ""
             echo -e "${GREEN}⬢${NC} API key saved to $SHELL_RC_FILE"
+            # Health check the new key
+            echo -n "  Verifying API key... "
+            HC_RESULT=$(uv run python "$SCRIPT_DIR/scripts/check_llm_key.py" "$SELECTED_PROVIDER_ID" "$API_KEY" 2>/dev/null) || true
+            HC_VALID=$(echo "$HC_RESULT" | $PYTHON_CMD -c "import json,sys; print(json.loads(sys.stdin.read()).get('valid',''))" 2>/dev/null) || true
+            HC_MSG=$(echo "$HC_RESULT" | $PYTHON_CMD -c "import json,sys; print(json.loads(sys.stdin.read()).get('message',''))" 2>/dev/null) || true
+            if [ "$HC_VALID" = "True" ]; then
+                echo -e "${GREEN}ok${NC}"
+                break
+            elif [ "$HC_VALID" = "False" ]; then
+                echo -e "${RED}failed${NC}"
+                echo -e "  ${YELLOW}⚠ $HC_MSG${NC}"
+                # Undo the save so the user can retry cleanly
+                sed -i.bak "/^export ${SELECTED_ENV_VAR}=/d" "$SHELL_RC_FILE" && rm -f "${SHELL_RC_FILE}.bak"
+                # Remove the comment line we just added
+                sed -i.bak "/^# Hive Agent Framework - $PROVIDER_NAME API key$/d" "$SHELL_RC_FILE" && rm -f "${SHELL_RC_FILE}.bak"
+                unset "$SELECTED_ENV_VAR"
+                echo ""
+                read -r -p "  Press Enter to try again: " _
+                # Loop back to key prompt
             else
+                echo -e "${YELLOW}--${NC}"
+                echo -e "  ${DIM}Could not verify key (network issue). The key has been saved.${NC}"
+                break
+            fi
+        elif [ -z "$CURRENT_KEY" ]; then
+            # No existing key and user skipped — abort provider
             echo ""
             echo -e "${YELLOW}Skipped.${NC} Add your API key to $SHELL_RC_FILE when ready."
             SELECTED_ENV_VAR=""
             SELECTED_PROVIDER_ID=""
+            break
+        else
+            # User pressed Enter with existing key — keep it, proceed normally
+            break
         fi
+    done
 fi
 
-# For ZAI subscription: always prompt for API key
+# For ZAI subscription: prompt for API key (allow replacement if already set)
 if [ "$SUBSCRIPTION_MODE" = "zai_code" ]; then
+    while true; do
+        if [ "$ZAI_CRED_DETECTED" = true ] && [ -n "$ZAI_API_KEY" ]; then
+            # Key exists — offer to keep or replace
+            MASKED_KEY="${ZAI_API_KEY:0:4}...${ZAI_API_KEY: -4}"
+            echo ""
+            echo -e "  ${GREEN}⬢${NC} Current ZAI key: ${DIM}$MASKED_KEY${NC}"
+            read -r -p "  Press Enter to keep, or paste a new key to replace: " API_KEY
+        else
+            # No key — prompt for one
             echo ""
             read -r -p "Paste your ZAI API key (or press Enter to skip): " API_KEY
+        fi
 
         if [ -n "$API_KEY" ]; then
+            sed -i.bak "/^export ZAI_API_KEY=/d" "$SHELL_RC_FILE" && rm -f "${SHELL_RC_FILE}.bak"
             echo "" >> "$SHELL_RC_FILE"
             echo "# Hive Agent Framework - ZAI Code subscription API key" >> "$SHELL_RC_FILE"
             echo "export ZAI_API_KEY=\"$API_KEY\"" >> "$SHELL_RC_FILE"
             export ZAI_API_KEY="$API_KEY"
             echo ""
             echo -e "${GREEN}⬢${NC} ZAI API key saved to $SHELL_RC_FILE"
+            # Health check the new key
+            echo -n "  Verifying ZAI API key... "
+            HC_RESULT=$(uv run python "$SCRIPT_DIR/scripts/check_llm_key.py" "zai" "$API_KEY" "https://api.z.ai/api/coding/paas/v4" 2>/dev/null) || true
+            HC_VALID=$(echo "$HC_RESULT" | $PYTHON_CMD -c "import json,sys; print(json.loads(sys.stdin.read()).get('valid',''))" 2>/dev/null) || true
+            HC_MSG=$(echo "$HC_RESULT" | $PYTHON_CMD -c "import json,sys; print(json.loads(sys.stdin.read()).get('message',''))" 2>/dev/null) || true
+            if [ "$HC_VALID" = "True" ]; then
+                echo -e "${GREEN}ok${NC}"
+                break
+            elif [ "$HC_VALID" = "False" ]; then
+                echo -e "${RED}failed${NC}"
+                echo -e "  ${YELLOW}⚠ $HC_MSG${NC}"
+                # Undo the save so the user can retry cleanly
+                sed -i.bak "/^export ZAI_API_KEY=/d" "$SHELL_RC_FILE" && rm -f "${SHELL_RC_FILE}.bak"
+                sed -i.bak "/^# Hive Agent Framework - ZAI Code subscription API key$/d" "$SHELL_RC_FILE" && rm -f "${SHELL_RC_FILE}.bak"
+                unset ZAI_API_KEY
+                ZAI_CRED_DETECTED=false
+                echo ""
+                read -r -p "  Press Enter to try again: " _
+                # Loop back to key prompt
             else
+                echo -e "${YELLOW}--${NC}"
+                echo -e "  ${DIM}Could not verify key (network issue). The key has been saved.${NC}"
+                break
+            fi
+        elif [ "$ZAI_CRED_DETECTED" = false ] || [ -z "$ZAI_API_KEY" ]; then
+            # No existing key and user skipped — abort provider
             echo ""
             echo -e "${YELLOW}Skipped.${NC} Add your ZAI API key to $SHELL_RC_FILE when ready:"
             echo -e "  ${CYAN}echo 'export ZAI_API_KEY=\"your-key\"' >> $SHELL_RC_FILE${NC}"
             SELECTED_ENV_VAR=""
             SELECTED_PROVIDER_ID=""
             SUBSCRIPTION_MODE=""
+            break
+        else
+            # User pressed Enter with existing key — keep it, proceed normally
+            break
         fi
+    done
 fi
 
 # Prompt for model if not already selected (manual provider path)
@@ -1037,52 +1210,22 @@ fi
 echo ""
 
 # ============================================================
-# Step 4b: Browser Automation (GCU)
+# Step 4b: Browser Automation (GCU) — always enabled
 # ============================================================
 
-echo -e "${BOLD}Enable browser automation?${NC}"
-echo -e "${DIM}This lets your agents control a real browser — navigate websites, fill forms,${NC}"
-echo -e "${DIM}scrape dynamic pages, and interact with web UIs.${NC}"
-echo ""
-echo -e "  ${CYAN}${BOLD}1)${NC} ${BOLD}Yes${NC}"
-echo -e "  ${CYAN}2)${NC} No"
-echo ""
-
-while true; do
-    read -r -p "Enter choice (1-2, default 1): " gcu_choice || true
-    gcu_choice="${gcu_choice:-1}"
-    if [ "$gcu_choice" = "1" ] || [ "$gcu_choice" = "2" ]; then
-        break
-    fi
-    echo -e "${RED}Invalid choice. Please enter 1 or 2${NC}"
-done
-
-if [ "$gcu_choice" = "1" ]; then
-    GCU_ENABLED=true
 echo -e "${GREEN}⬢${NC} Browser automation enabled"
-else
-    GCU_ENABLED=false
-    echo -e "${DIM}⬡ Browser automation skipped${NC}"
-fi
 
 # Patch gcu_enabled into configuration.json
-if [ "$GCU_ENABLED" = "true" ]; then
-    GCU_PY_VAL="True"
-else
-    GCU_PY_VAL="False"
-fi
-
 if [ -f "$HIVE_CONFIG_FILE" ]; then
     uv run python -c "
 import json
 with open('$HIVE_CONFIG_FILE') as f:
     config = json.load(f)
-config['gcu_enabled'] = $GCU_PY_VAL
+config['gcu_enabled'] = True
 with open('$HIVE_CONFIG_FILE', 'w') as f:
     json.dump(config, f, indent=2)
 "
-elif [ "$GCU_ENABLED" = "true" ]; then
-    # No config file yet (user skipped LLM provider) — create minimal one
+else
     mkdir -p "$HIVE_CONFIG_DIR"
     uv run python -c "
 import json
@@ -1334,6 +1477,26 @@ if [ -n "$HIVE_CREDENTIAL_KEY" ]; then
     echo ""
 fi
 
+# Show tool summary
+TOOL_COUNTS=$(uv run python -c "
+from fastmcp import FastMCP
+from aden_tools.tools import register_all_tools
+mv = FastMCP('v')
+v = register_all_tools(mv, include_unverified=False)
+ma = FastMCP('a')
+a = register_all_tools(ma, include_unverified=True)
+print(f'{len(v)}|{len(a) - len(v)}')
+" 2>/dev/null)
+if [ -n "$TOOL_COUNTS" ]; then
+    VERIFIED=$(echo "$TOOL_COUNTS" | cut -d'|' -f1)
+    UNVERIFIED=$(echo "$TOOL_COUNTS" | cut -d'|' -f2)
+    echo -e "${BOLD}Tools:${NC}"
+    echo -e "  ${GREEN}⬢${NC} ${VERIFIED} verified    ${DIM}${UNVERIFIED} unverified available${NC}"
+    echo -e "  ${DIM}Enable unverified: INCLUDE_UNVERIFIED_TOOLS=true${NC}"
+    echo -e "  ${DIM}Learn more: docs/tools.md${NC}"
+    echo ""
+fi
+
 # Show Codex instructions if available
 if [ "$CODEX_AVAILABLE" = true ]; then
     echo -e "${BOLD}Build a New Agent (Codex):${NC}"
@@ -1352,9 +1515,10 @@ if [ "$FRONTEND_BUILT" = true ]; then
     echo -e "  ${DIM}Starting server on http://localhost:8787${NC}"
     echo -e "  ${DIM}Press Ctrl+C to stop${NC}"
     echo ""
-    # exec replaces the quickstart process with hive serve
-    # --open tells it to auto-open the browser once the server is ready
-    exec "$SCRIPT_DIR/hive" serve --open
+    echo -e "  ${DIM}Tip: You can restart the dashboard anytime with:${NC} ${CYAN}hive open${NC}"
+    echo ""
+    # exec replaces the quickstart process with hive open
+    exec "$SCRIPT_DIR/hive" open
 else
     # No frontend — show manual instructions
     echo -e "${YELLOW}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
@@ -1376,7 +1540,7 @@ else
     echo ""
     echo -e "  Launch the interactive dashboard to browse and run agents:"
     echo -e "  You can start an example agent or an agent built by yourself:"
-    echo -e "     ${CYAN}hive tui${NC}"
+    echo -e "     ${CYAN}hive open${NC}"
     echo ""
     echo -e "${DIM}Run ./quickstart.sh again to reconfigure.${NC}"
     echo ""

scripts/check_llm_key.py

@@ -0,0 +1,132 @@
+"""Validate an LLM API key without consuming tokens.
+
+Usage:
+    python scripts/check_llm_key.py <provider_id> <api_key> [api_base]
+
+Exit codes:
+    0 = valid key
+    1 = invalid key
+    2 = inconclusive (timeout, network error)
+
+Output: single JSON line {"valid": bool, "message": str}
+"""
+
+import json
+import sys
+
+import httpx
+
+TIMEOUT = 10.0
+
+
+def check_anthropic(api_key: str, **_: str) -> dict:
+    """Send empty messages to trigger 400 without consuming tokens."""
+    with httpx.Client(timeout=TIMEOUT) as client:
+        r = client.post(
+            "https://api.anthropic.com/v1/messages",
+            headers={
+                "x-api-key": api_key,
+                "anthropic-version": "2023-06-01",
+                "Content-Type": "application/json",
+            },
+            json={"model": "claude-sonnet-4-20250514", "max_tokens": 1, "messages": []},
+        )
+    if r.status_code in (200, 400, 429):
+        return {"valid": True, "message": "API key valid"}
+    if r.status_code == 401:
+        return {"valid": False, "message": "Invalid API key"}
+    if r.status_code == 403:
+        return {"valid": False, "message": "API key lacks permissions"}
+    return {"valid": False, "message": f"Unexpected status {r.status_code}"}
+
+
+def check_openai_compatible(api_key: str, endpoint: str, name: str) -> dict:
+    """GET /models on any OpenAI-compatible API."""
+    with httpx.Client(timeout=TIMEOUT) as client:
+        r = client.get(
+            endpoint,
+            headers={"Authorization": f"Bearer {api_key}"},
+        )
+    if r.status_code in (200, 429):
+        return {"valid": True, "message": f"{name} API key valid"}
+    if r.status_code == 401:
+        return {"valid": False, "message": f"Invalid {name} API key"}
+    if r.status_code == 403:
+        return {"valid": False, "message": f"{name} API key lacks permissions"}
+    return {"valid": False, "message": f"{name} API returned status {r.status_code}"}
+
+
+def check_gemini(api_key: str, **_: str) -> dict:
+    """List models with query param auth."""
+    with httpx.Client(timeout=TIMEOUT) as client:
+        r = client.get(
+            "https://generativelanguage.googleapis.com/v1beta/models",
+            params={"key": api_key},
+        )
+    if r.status_code in (200, 429):
+        return {"valid": True, "message": "Gemini API key valid"}
+    if r.status_code in (400, 401, 403):
+        return {"valid": False, "message": "Invalid Gemini API key"}
+    return {"valid": False, "message": f"Gemini API returned status {r.status_code}"}
+
+
+PROVIDERS = {
+    "anthropic": lambda key, **kw: check_anthropic(key),
+    "openai": lambda key, **kw: check_openai_compatible(
+        key, "https://api.openai.com/v1/models", "OpenAI"
+    ),
+    "gemini": lambda key, **kw: check_gemini(key),
+    "groq": lambda key, **kw: check_openai_compatible(
+        key, "https://api.groq.com/openai/v1/models", "Groq"
+    ),
+    "cerebras": lambda key, **kw: check_openai_compatible(
+        key, "https://api.cerebras.ai/v1/models", "Cerebras"
+    ),
+}
+
+
+def main() -> None:
+    if len(sys.argv) < 3:
+        print(
+            json.dumps(
+                {
+                    "valid": False,
+                    "message": "Usage: check_llm_key.py <provider> <key> [api_base]",
+                }
+            )
+        )
+        sys.exit(2)
+
+    provider_id = sys.argv[1]
+    api_key = sys.argv[2]
+    api_base = sys.argv[3] if len(sys.argv) > 3 else ""
+
+    try:
+        if api_base:
+            # Custom API base (ZAI or other OpenAI-compatible)
+            endpoint = api_base.rstrip("/") + "/models"
+            result = check_openai_compatible(api_key, endpoint, "ZAI")
+        elif provider_id in PROVIDERS:
+            result = PROVIDERS[provider_id](api_key)
+        else:
+            result = {"valid": True, "message": f"No health check for {provider_id}"}
+            print(json.dumps(result))
+            sys.exit(0)
+
+        print(json.dumps(result))
+        sys.exit(0 if result["valid"] else 1)
+
+    except httpx.TimeoutException:
+        print(json.dumps({"valid": None, "message": "Request timed out"}))
+        sys.exit(2)
+    except httpx.RequestError as e:
+        msg = str(e)
+        # Redact key from error messages
+        if api_key in msg:
+            msg = msg.replace(api_key, "***")
+        print(json.dumps({"valid": None, "message": f"Connection failed: {msg}"}))
+        sys.exit(2)
+
+
+if __name__ == "__main__":
+    main()

scripts/test_check_requirements.py

@@ -20,6 +20,7 @@ def test_check_requirements():
         [sys.executable, "scripts/check_requirements.py", "json", "sys", "os"],
         capture_output=True,
         text=True,
+        encoding="utf-8",
     )
     print(f"Exit code: {result.returncode}")
     print(f"Output:\n{result.stdout}")
@@ -39,6 +40,7 @@ def test_check_requirements():
         [sys.executable, "scripts/check_requirements.py", "json", "nonexistent_module"],
         capture_output=True,
         text=True,
+        encoding="utf-8",
     )
     print(f"Exit code: {result.returncode}")
     print(f"Output:\n{result.stdout}")

tools/.env.example

@@ -0,0 +1,66 @@
+# MSSQL Connection Configuration Template
+#
+# Copy this file to .env and fill in your actual values
+# DO NOT commit the .env file to version control!
+
+# ============================================================================
+# SQL Server Connection - Choose ONE format below:
+# ============================================================================
+
+# OPTION 1: Local named instance
+MSSQL_SERVER=localhost\SQLEXPRESS
+
+# OPTION 2: Local default instance
+# MSSQL_SERVER=localhost
+
+# OPTION 3: Remote server with default port (1433)
+# MSSQL_SERVER=192.168.1.100
+
+# OPTION 4: Remote server with custom port (comma-separated)
+# MSSQL_SERVER=192.168.1.100,1433
+
+# OPTION 5: Remote named instance
+# MSSQL_SERVER=PRODUCTION-SERVER\INSTANCE01
+
+# OPTION 6: Domain server name
+# MSSQL_SERVER=sql-prod.company.com
+
+# OPTION 7: Domain server with port
+# MSSQL_SERVER=sql-prod.company.com,1433
+
+# ============================================================================
+# Database Configuration
+# ============================================================================
+MSSQL_DATABASE=AdenTestDB
+
+# ============================================================================
+# Authentication - Choose ONE method:
+# ============================================================================
+
+# METHOD 1: SQL Server Authentication (username/password)
+# Use this for: remote servers, Linux servers, specific SQL logins
+MSSQL_USERNAME=sa
+MSSQL_PASSWORD=your_password_here
+
+# METHOD 2: Windows Authentication (leave both empty)
+# Use this for: local Windows servers, domain-joined environments
+# MSSQL_USERNAME=
+# MSSQL_PASSWORD=
+
+# ============================================================================
+# Important Notes:
+# ============================================================================
+# - Port format: Use comma (,) not colon - Example: server,1433
+# - Named instances: Use backslash (\) - Example: SERVER\INSTANCE
+# - Default port: 1433 (can be omitted if using default)
+# - ODBC Driver: Requires "ODBC Driver 17 for SQL Server" or newer
+# - Security: Never commit this file with real credentials!
+# - Escaping: In some shells, escape backslashes (\\) when setting env vars
+# ============================================================================
+
+# Example Production Configurations:
+# -----------------------------------
+# Azure SQL: MSSQL_SERVER=yourserver.database.windows.net
+# AWS RDS: MSSQL_SERVER=yourinstance.region.rds.amazonaws.com,1433
+# Docker: MSSQL_SERVER=localhost,1401
+# Kubernetes: MSSQL_SERVER=mssql-service.namespace.svc.cluster.local,1433

tools/README.md

@@ -72,6 +72,7 @@ python mcp_server.py
 | `apply_diff` | Apply diff patches to files |
 | `apply_patch` | Apply unified patches to files |
 | `grep_search` | Search file contents with regex |
+| `hashline_edit` | Anchor-based file editing with hash-validated line references |
 | `execute_command_tool` | Execute shell commands |
 | `save_data` / `load_data` | Persist and retrieve structured data across steps |
 | `serve_file_to_user` | Serve a file for the user to download |
@@ -175,14 +176,17 @@ tools/
 │   └── tools/               # Tool implementations
 │       ├── example_tool/
 │       ├── file_system_toolkits/  # File operation tools
-│       │   ├── view_file.py
-│       │   ├── write_to_file.py
-│       │   ├── list_dir.py
-│       │   ├── replace_file_content.py
-│       │   ├── apply_diff.py
-│       │   ├── apply_patch.py
-│       │   ├── grep_search.py
-│       │   └── execute_command_tool.py
+│       │   ├── security.py
+│       │   ├── hashline.py
+│       │   ├── view_file/
+│       │   ├── write_to_file/
+│       │   ├── list_dir/
+│       │   ├── replace_file_content/
+│       │   ├── apply_diff/
+│       │   ├── apply_patch/
+│       │   ├── grep_search/
+│       │   ├── hashline_edit/
+│       │   └── execute_command_tool/
 │       ├── web_search_tool/
 │       ├── web_scrape_tool/
 │       ├── pdf_read_tool/

tools/coder_tools_server.py

@@ -71,8 +71,49 @@ def _find_project_root() -> str:
 
 def _resolve_path(path: str) -> str:
     """Resolve path relative to PROJECT_ROOT. Raises ValueError if outside."""
+    # Normalize slashes for cross-platform (e.g. exports/hi_agent from LLM)
+    path = path.replace("/", os.sep)
     if os.path.isabs(path):
         resolved = os.path.abspath(path)
+        try:
+            common = os.path.commonpath([resolved, PROJECT_ROOT])
+        except ValueError:
+            common = ""
+        if common != PROJECT_ROOT:
+            # LLM may emit wrong-root paths (/mnt/data, /workspace, etc.).
+            # Strip known prefixes and treat the remainder as relative to PROJECT_ROOT.
+            path_norm = path.replace("\\", "/")
+            for prefix in (
+                "/mnt/data/",
+                "/mnt/data",
+                "/workspace/",
+                "/workspace",
+                "/repo/",
+                "/repo",
+            ):
+                p = prefix.rstrip("/") + "/"
+                prefix_stripped = prefix.rstrip("/")
+                if path_norm.startswith(p) or (
+                    path_norm.startswith(prefix_stripped) and len(path_norm) > len(prefix)
+                ):
+                    suffix = path_norm[len(prefix_stripped) :].lstrip("/")
+                    if suffix:
+                        path = suffix.replace("/", os.sep)
+                        resolved = os.path.abspath(os.path.join(PROJECT_ROOT, path))
+                        break
+            else:
+                # Try extracting exports/ or core/ subpath from the absolute path
+                parts = path.split(os.sep)
+                if "exports" in parts:
+                    idx = parts.index("exports")
+                    path = os.sep.join(parts[idx:])
+                    resolved = os.path.abspath(os.path.join(PROJECT_ROOT, path))
+                elif "core" in parts:
+                    idx = parts.index("core")
+                    path = os.sep.join(parts[idx:])
+                    resolved = os.path.abspath(os.path.join(PROJECT_ROOT, path))
+                else:
+                    raise ValueError(f"Access denied: '{path}' is outside the project root.")
     else:
         resolved = os.path.abspath(os.path.join(PROJECT_ROOT, path))
     try:
@@ -90,7 +131,9 @@ def _resolve_path(path: str) -> str:
 def _snapshot_git(*args: str) -> str:
     """Run a git command with the snapshot GIT_DIR and PROJECT_ROOT worktree."""
     cmd = ["git", "--git-dir", SNAPSHOT_DIR, "--work-tree", PROJECT_ROOT, *args]
-    result = subprocess.run(cmd, capture_output=True, text=True, timeout=30)
+    result = subprocess.run(
+        cmd, capture_output=True, text=True, timeout=30, encoding="utf-8", stdin=subprocess.DEVNULL
+    )
     return result.stdout.strip()
 
 
@@ -104,6 +147,8 @@ def _ensure_snapshot_repo():
             ["git", "init", "--bare", SNAPSHOT_DIR],
             capture_output=True,
             timeout=10,
+            stdin=subprocess.DEVNULL,
+            encoding="utf-8",
         )
         _snapshot_git("config", "core.autocrlf", "false")
 
@@ -125,6 +170,37 @@ def _take_snapshot() -> str:
 MAX_COMMAND_OUTPUT = 30_000  # chars before truncation
 
 
+def _translate_command_for_windows(command: str) -> str:
+    """Translate common Unix commands to Windows equivalents."""
+    if os.name != "nt":
+        return command
+    cmd = command.strip()
+
+    # mkdir -p: Unix creates parents; Windows mkdir already does; -p becomes a dir name
+    if cmd.startswith("mkdir -p ") or cmd.startswith("mkdir -p\t"):
+        rest = cmd[9:].lstrip().replace("/", os.sep)
+        return "mkdir " + rest
+
+    # ls / pwd: cmd.exe uses dir and cd
+    # Order matters: replace longer patterns first
+    for unix, win in [
+        ("ls -la", "dir /a"),
+        ("ls -al", "dir /a"),
+        ("ls -l", "dir"),
+        ("ls -a", "dir /a"),
+        ("ls ", "dir "),
+        ("pwd", "cd"),
+    ]:
+        cmd = cmd.replace(unix, win)
+    # Standalone "ls" at end (e.g. "cd x && ls")
+    if cmd.endswith(" ls"):
+        cmd = cmd[:-3] + " dir"
+    elif cmd == "ls":
+        cmd = "dir"
+
+    return cmd
+
+
 @mcp.tool()
 def run_command(command: str, cwd: str = "", timeout: int = 120) -> str:
     """Execute a shell command in the project context.
@@ -144,6 +220,7 @@ def run_command(command: str, cwd: str = "", timeout: int = 120) -> str:
     work_dir = _resolve_path(cwd) if cwd else PROJECT_ROOT
 
     try:
+        command = _translate_command_for_windows(command)
         start = time.monotonic()
         result = subprocess.run(
             command,
@@ -152,11 +229,16 @@ def run_command(command: str, cwd: str = "", timeout: int = 120) -> str:
             capture_output=True,
             text=True,
             timeout=timeout,
+            stdin=subprocess.DEVNULL,
+            encoding="utf-8",
             env={
                 **os.environ,
-                "PYTHONPATH": (
-                    f"{PROJECT_ROOT}/core:{PROJECT_ROOT}/exports"
-                    f":{PROJECT_ROOT}/core/framework/agents"
+                "PYTHONPATH": os.pathsep.join(
+                    [
+                        os.path.join(PROJECT_ROOT, "core"),
+                        os.path.join(PROJECT_ROOT, "exports"),
+                        os.path.join(PROJECT_ROOT, "core", "framework", "agents"),
+                    ]
                 ),
             },
         )
@@ -228,6 +310,8 @@ def undo_changes(path: str = "") -> str:
                 capture_output=True,
                 text=True,
                 timeout=10,
+                stdin=subprocess.DEVNULL,
+                encoding="utf-8",
             )
             return f"Restored: {path}"
         else:
@@ -300,28 +384,31 @@ def list_agent_tools(
         return json.dumps({"error": f"Failed to read config: {e}"})
 
     try:
+        from pathlib import Path
+
         from framework.runner.mcp_client import MCPClient, MCPServerConfig
+        from framework.runner.tool_registry import ToolRegistry
     except ImportError:
         return json.dumps({"error": "Cannot import MCPClient"})
 
     all_tools: list[dict] = []
     errors = []
-    config_dir = os.path.dirname(config_path)
+    config_dir = Path(config_path).parent
 
     for server_name, server_conf in servers_config.items():
-        cwd = server_conf.get("cwd", "")
-        if cwd and not os.path.isabs(cwd):
-            cwd = os.path.abspath(os.path.join(config_dir, cwd))
+        resolved = ToolRegistry.resolve_mcp_stdio_config(
+            {"name": server_name, **server_conf}, config_dir
+        )
         try:
             config = MCPServerConfig(
                 name=server_name,
-                transport=server_conf.get("transport", "stdio"),
-                command=server_conf.get("command"),
-                args=server_conf.get("args", []),
-                env=server_conf.get("env", {}),
-                cwd=cwd or None,
-                url=server_conf.get("url"),
-                headers=server_conf.get("headers", {}),
+                transport=resolved.get("transport", "stdio"),
+                command=resolved.get("command"),
+                args=resolved.get("args", []),
+                env=resolved.get("env", {}),
+                cwd=resolved.get("cwd"),
+                url=resolved.get("url"),
+                headers=resolved.get("headers", {}),
             )
             client = MCPClient(config)
             client.connect()
@@ -410,19 +497,24 @@ def validate_agent_tools(agent_path: str) -> str:
     if not os.path.isdir(resolved):
         return json.dumps({"error": f"Agent directory not found: {agent_path}"})
 
+    agent_dir = resolved  # Keep path; 'resolved' is reused for MCP config in loop
+
     # --- Discover available tools from agent's MCP servers ---
-    mcp_config_path = os.path.join(resolved, "mcp_servers.json")
+    mcp_config_path = os.path.join(agent_dir, "mcp_servers.json")
     if not os.path.isfile(mcp_config_path):
         return json.dumps({"error": f"No mcp_servers.json found in {agent_path}"})
 
     try:
+        from pathlib import Path
+
         from framework.runner.mcp_client import MCPClient, MCPServerConfig
+        from framework.runner.tool_registry import ToolRegistry
     except ImportError:
         return json.dumps({"error": "Cannot import MCPClient"})
 
     available_tools: set[str] = set()
     discovery_errors = []
-    config_dir = os.path.dirname(mcp_config_path)
+    config_dir = Path(mcp_config_path).parent
 
     try:
         with open(mcp_config_path, encoding="utf-8") as f:
@@ -431,19 +523,19 @@ def validate_agent_tools(agent_path: str) -> str:
         return json.dumps({"error": f"Failed to read mcp_servers.json: {e}"})
 
     for server_name, server_conf in servers_config.items():
-        cwd = server_conf.get("cwd", "")
-        if cwd and not os.path.isabs(cwd):
-            cwd = os.path.abspath(os.path.join(config_dir, cwd))
+        resolved = ToolRegistry.resolve_mcp_stdio_config(
+            {"name": server_name, **server_conf}, config_dir
+        )
         try:
             config = MCPServerConfig(
                 name=server_name,
-                transport=server_conf.get("transport", "stdio"),
-                command=server_conf.get("command"),
-                args=server_conf.get("args", []),
-                env=server_conf.get("env", {}),
-                cwd=cwd or None,
-                url=server_conf.get("url"),
-                headers=server_conf.get("headers", {}),
+                transport=resolved.get("transport", "stdio"),
+                command=resolved.get("command"),
+                args=resolved.get("args", []),
+                env=resolved.get("env", {}),
+                cwd=resolved.get("cwd"),
+                url=resolved.get("url"),
+                headers=resolved.get("headers", {}),
             )
             client = MCPClient(config)
             client.connect()
@@ -454,7 +546,7 @@ def validate_agent_tools(agent_path: str) -> str:
             discovery_errors.append({"server": server_name, "error": str(e)})
 
     # --- Load agent nodes and extract declared tools ---
-    agent_py = os.path.join(resolved, "agent.py")
+    agent_py = os.path.join(agent_dir, "agent.py")
     if not os.path.isfile(agent_py):
         return json.dumps({"error": f"No agent.py found in {agent_path}"})
 
@@ -462,8 +554,8 @@ def validate_agent_tools(agent_path: str) -> str:
     import importlib.util
     import sys
 
-    package_name = os.path.basename(resolved)
-    parent_dir = os.path.dirname(os.path.abspath(resolved))
+    package_name = os.path.basename(agent_dir)
+    parent_dir = os.path.dirname(os.path.abspath(agent_dir))
     if parent_dir not in sys.path:
         sys.path.insert(0, parent_dir)
 
@@ -717,94 +809,6 @@ def list_agent_sessions(
     )
 
 
-@mcp.tool()
-def get_agent_session_state(agent_name: str, session_id: str) -> str:
-    """Load full session state (excluding memory to prevent context bloat).
-
-    Returns status, progress, result, metrics, and checkpoint info.
-    Use get_agent_session_memory to read memory contents separately.
-
-    Args:
-        agent_name: Agent package name (e.g. 'deep_research_agent')
-        session_id: Session ID (e.g. 'session_20260208_143022_abc12345')
-
-    Returns:
-        JSON with full session state
-    """
-    agent_dir = _resolve_hive_agent_path(agent_name)
-    state_path = agent_dir / "sessions" / session_id / "state.json"
-    data = _read_session_json(state_path)
-    if data is None:
-        return json.dumps({"error": f"Session not found: {session_id}"})
-
-    # Exclude memory values but show keys
-    memory = data.get("memory", {})
-    data["memory_keys"] = list(memory.keys()) if isinstance(memory, dict) else []
-    data["memory_size"] = len(memory) if isinstance(memory, dict) else 0
-    data.pop("memory", None)
-
-    return json.dumps(data, indent=2, default=str)
-
-
-@mcp.tool()
-def get_agent_session_memory(
-    agent_name: str,
-    session_id: str,
-    key: str = "",
-) -> str:
-    """Read memory contents from a session.
-
-    Memory stores intermediate results passed between nodes. Use this
-    to inspect what data was produced during execution.
-
-    Args:
-        agent_name: Agent package name
-        session_id: Session ID
-        key: Specific memory key to retrieve. Empty for all keys.
-
-    Returns:
-        JSON with memory contents
-    """
-    agent_dir = _resolve_hive_agent_path(agent_name)
-    state_path = agent_dir / "sessions" / session_id / "state.json"
-    data = _read_session_json(state_path)
-    if data is None:
-        return json.dumps({"error": f"Session not found: {session_id}"})
-
-    memory = data.get("memory", {})
-    if not isinstance(memory, dict):
-        memory = {}
-
-    if key:
-        if key not in memory:
-            return json.dumps(
-                {
-                    "error": f"Memory key not found: '{key}'",
-                    "available_keys": list(memory.keys()),
-                }
-            )
-        return json.dumps(
-            {
-                "session_id": session_id,
-                "key": key,
-                "value": memory[key],
-                "value_type": type(memory[key]).__name__,
-            },
-            indent=2,
-            default=str,
-        )
-
-    return json.dumps(
-        {
-            "session_id": session_id,
-            "memory": memory,
-            "total_keys": len(memory),
-        },
-        indent=2,
-        default=str,
-    )
-
-
 @mcp.tool()
 def list_agent_checkpoints(
     agent_name: str,
@@ -1006,13 +1010,16 @@ def run_agent_tests(
         cmd.append("-x")
     cmd.append("--tb=short")
 
-    # Set PYTHONPATH
+    # Set PYTHONPATH (use pathsep for Windows)
     env = os.environ.copy()
     pythonpath = env.get("PYTHONPATH", "")
     core_path = os.path.join(PROJECT_ROOT, "core")
     exports_path = os.path.join(PROJECT_ROOT, "exports")
     fw_agents_path = os.path.join(PROJECT_ROOT, "core", "framework", "agents")
-    env["PYTHONPATH"] = f"{core_path}:{exports_path}:{fw_agents_path}:{PROJECT_ROOT}:{pythonpath}"
+    path_parts = [core_path, exports_path, fw_agents_path, PROJECT_ROOT]
+    if pythonpath:
+        path_parts.append(pythonpath)
+    env["PYTHONPATH"] = os.pathsep.join(path_parts)
 
     try:
         result = subprocess.run(
@@ -1021,6 +1028,8 @@ def run_agent_tests(
             text=True,
             timeout=120,
             env=env,
+            stdin=subprocess.DEVNULL,
+            encoding="utf-8",
         )
     except subprocess.TimeoutExpired:
         return json.dumps(
@@ -1144,7 +1153,7 @@ def main() -> None:
     register_file_tools(
         mcp,
         resolve_path=_resolve_path,
-        before_write=_take_snapshot,
+        before_write=None,  # Git snapshot causes stdio deadlock on Windows; undo_changes limited
         project_root=PROJECT_ROOT,
     )
 

tools/create_aden_testdb.py

@@ -0,0 +1,120 @@
+"""
+Database Initialization Script Runner for AdenTestDB
+
+This script executes the SQL initialization file to create the AdenTestDB database.
+Make sure your SQL Server is running before executing this script.
+"""
+
+import os
+
+import pyodbc
+from dotenv import load_dotenv
+
+# Load environment variables from .env
+load_dotenv()
+
+# Database connection settings (from environment variables)
+SERVER = os.getenv("MSSQL_SERVER", r"MONSTER\MSSQLSERVERR")
+USERNAME = os.getenv("MSSQL_USERNAME")
+PASSWORD = os.getenv("MSSQL_PASSWORD")
+
+# SQL file path
+SQL_FILE = os.path.join(os.path.dirname(__file__), "init_aden_testdb.sql")
+
+
+def execute_sql_file():
+    """Execute the SQL initialization file."""
+    connection = None
+
+    try:
+        # Read SQL file
+        if not os.path.exists(SQL_FILE):
+            print(f"[ERROR] SQL file not found: {SQL_FILE}")
+            return False
+
+        with open(SQL_FILE, encoding="utf-8") as f:
+            sql_script = f.read()
+
+        print("=" * 70)
+        print("AdenTestDB Database Initialization")
+        print("=" * 70)
+        print(f"Server: {SERVER}")
+        print(f"SQL Script: {SQL_FILE}")
+        print()
+
+        # Connect to master database (to create new database)
+        connection_string = (
+            f"DRIVER={{ODBC Driver 17 for SQL Server}};"
+            f"SERVER={SERVER};"
+            f"DATABASE=master;"
+            f"UID={USERNAME};"
+            f"PWD={PASSWORD};"
+        )
+
+        print("Connecting to SQL Server...")
+        connection = pyodbc.connect(connection_string)
+        connection.autocommit = True  # Required for CREATE DATABASE
+        cursor = connection.cursor()
+
+        print("[OK] Connected successfully!")
+        print()
+        print("Executing SQL script...")
+        print("-" * 70)
+
+        # Split by GO statements and execute each batch
+        batches = sql_script.split("\nGO\n")
+
+        for i, batch in enumerate(batches, 1):
+            batch = batch.strip()
+            if batch and not batch.startswith("--"):
+                try:
+                    cursor.execute(batch)
+                    # Print any messages from the server
+                    while cursor.nextset():
+                        pass
+                except pyodbc.Error as e:
+                    # Some statements might not return results, that's OK
+                    if "No results" not in str(e):
+                        print(f"Warning in batch {i}: {str(e)}")
+
+        print("-" * 70)
+        print()
+        print("=" * 70)
+        print("[SUCCESS] Database initialization completed successfully!")
+        print("=" * 70)
+        print()
+        print("Next steps:")
+        print("1. Run: python test_mssql_connection.py")
+        print("2. Verify the relational schema and sample data")
+        print()
+
+        return True
+
+    except pyodbc.Error as e:
+        print()
+        print("=" * 70)
+        print("[ERROR] Database initialization failed!")
+        print("=" * 70)
+        print(f"Error detail: {str(e)}")
+        print()
+        print("Possible solutions:")
+        print("1. Ensure SQL Server is running")
+        print("2. Check server name, username, and password")
+        print("3. Ensure you have permission to create databases")
+        print("4. Verify ODBC Driver 17 for SQL Server is installed")
+        print()
+        return False
+
+    except Exception as e:
+        print(f"\n[ERROR] Unexpected error: {str(e)}")
+        return False
+
+    finally:
+        if connection:
+            connection.close()
+            print("Connection closed.")
+
+
+if __name__ == "__main__":
+    success = execute_sql_file()
+    exit(0 if success else 1)

tools/grant_permissions.py

@@ -0,0 +1,134 @@
+"""
+Grant Permissions to AdenTestDB
+
+This script grants the necessary permissions to the 'sa' user to access AdenTE testDB.
+"""
+
+import pyodbc
+
+SERVER = r"MONSTER\MSSQLSERVERR"
+USERNAME = "sa"
+PASSWORD = "622622aA."
+
+
+def grant_permissions():
+    """Grant permissions to the database."""
+    connection = None
+
+    try:
+        # Connect to AdenTestDB
+        connection_string = (
+            f"DRIVER={{ODBC Driver 17 for SQL Server}};"
+            f"SERVER={SERVER};"
+            f"DATABASE=AdenTestDB;"
+            f"UID={USERNAME};"
+            f"PWD={PASSWORD};"
+            f"TrustServerCertificate=yes;"
+        )
+
+        print("=" * 70)
+        print("Granting Permissions to AdenTestDB")
+        print("=" * 70)
+        print(f"Server: {SERVER}")
+        print()
+
+        print("Connecting to database...")
+        connection = pyodbc.connect(connection_string)
+        cursor = connection.cursor()
+
+        print("[OK] Connected successfully!")
+        print()
+
+        # Grant permissions
+        print("Granting permissions...")
+
+        try:
+            cursor.execute("GRANT SELECT, INSERT, UPDATE, DELETE ON SCHEMA::dbo TO sa")
+            print("[OK] Granted schema permissions to sa")
+        except pyodbc.Error as e:
+            print(f"Note: {str(e)}")
+
+        connection.commit()
+
+        print()
+        print("=" * 70)
+        print("[SUCCESS] Permissions granted!")
+        print("=" * 70)
+        print()
+        print("You can now run: python test_mssql_connection.py")
+
+        return True
+
+    except pyodbc.Error:
+        # If we can't connect, try connecting to master and creating user
+        try:
+            connection_string = (
+                f"DRIVER={{ODBC Driver 17 for SQL Server}};"
+                f"SERVER={SERVER};"
+                f"DATABASE=master;"
+                f"UID={USERNAME};"
+                f"PWD={PASSWORD};"
+                f"TrustServerCertificate=yes;"
+            )
+
+            print("Attempting to grant permissions via master database...")
+            connection = pyodbc.connect(connection_string)
+            cursor = connection.cursor()
+
+            # Create login if not exists
+            try:
+                cursor.execute(f"""
+                IF NOT EXISTS (SELECT * FROM sys.server_principals WHERE name = 'sa')
+                BEGIN
+                    CREATE LOGIN sa WITH PASSWORD = '{PASSWORD}'
+                END
+                """)
+            except Exception:
+                pass
+
+            # Switch to AdenTestDB and grant permissions
+            cursor.execute("USE AdenTestDB")
+
+            # Create user if not exists
+            try:
+                cursor.execute("""
+                IF NOT EXISTS (SELECT * FROM sys.database_principals WHERE name = 'sa')
+                BEGIN
+                    CREATE USER sa FOR LOGIN sa
+                END
+                """)
+                print("[OK] Created database user")
+            except Exception:
+                pass
+
+            # Grant permissions
+            cursor.execute("ALTER ROLE db_datareader ADD MEMBER sa")
+            cursor.execute("ALTER ROLE db_datawriter ADD MEMBER sa")
+
+            connection.commit()
+
+            print("[OK] Permissions granted successfully!")
+            return True
+
+        except Exception as inner_e:
+            print("\n[ERROR] Could not grant permissions!")
+            print(f"Error: {str(inner_e)}")
+            print()
+            print("The database was created successfully, but there's a permission issue.")
+            print("Please run this SQL command in SQL Server Management Studio:")
+            print()
+            print("USE AdenTestDB;")
+            print("GO")
+            print("ALTER ROLE db_datareader ADD MEMBER sa;")
+            print("ALTER ROLE db_datawriter ADD MEMBER sa;")
+            print("GO")
+            return False
+
+    finally:
+        if connection:
+            connection.close()
+            print("\nConnection closed.")
+
+
+if __name__ == "__main__":
+    grant_permissions()

tools/init_aden_testdb.sql

@@ -0,0 +1,183 @@
+-- ============================================================================
+-- AdenTestDB Database Initialization Script
+-- ============================================================================
+-- Purpose: Create a professional testing database for Aden Hive MSSQL tool
+-- Author: Database Architect
+-- Date: 2026-02-08
+-- ============================================================================
+
+USE master;
+GO
+
+-- Drop database if exists (for clean recreation)
+IF EXISTS (SELECT name FROM sys.databases WHERE name = N'AdenTestDB')
+BEGIN
+    ALTER DATABASE AdenTestDB SET SINGLE_USER WITH ROLLBACK IMMEDIATE;
+    DROP DATABASE AdenTestDB;
+    PRINT 'Existing AdenTestDB dropped successfully.';
+END
+GO
+
+-- Create new database
+CREATE DATABASE AdenTestDB;
+GO
+
+PRINT 'AdenTestDB created successfully.';
+GO
+
+USE AdenTestDB;
+GO
+
+-- ============================================================================
+-- TABLE: Departments
+-- ============================================================================
+-- Purpose: Store department information with budget tracking
+-- ============================================================================
+
+CREATE TABLE Departments (
+    department_id   INT IDENTITY(1,1) NOT NULL,
+    name            NVARCHAR(100) NOT NULL,
+    budget          DECIMAL(15,2) NOT NULL,
+    created_date    DATETIME NOT NULL DEFAULT GETDATE(),
+
+    CONSTRAINT PK_Departments PRIMARY KEY (department_id),
+    CONSTRAINT UK_Departments_Name UNIQUE (name),
+    CONSTRAINT CK_Departments_Budget CHECK (budget >= 0)
+);
+GO
+
+-- Create index for performance optimization
+CREATE INDEX IX_Departments_Name ON Departments(name);
+GO
+
+PRINT 'Departments table created successfully.';
+GO
+
+-- ============================================================================
+-- TABLE: Employees
+-- ============================================================================
+-- Purpose: Store employee information with department association
+-- ============================================================================
+
+CREATE TABLE Employees (
+    employee_id     INT IDENTITY(1000,1) NOT NULL,
+    first_name      NVARCHAR(50) NOT NULL,
+    last_name       NVARCHAR(50) NOT NULL,
+    email           NVARCHAR(100) NOT NULL,
+    salary          DECIMAL(12,2) NOT NULL,
+    hire_date       DATETIME NOT NULL,
+    department_id   INT NOT NULL,
+
+    CONSTRAINT PK_Employees PRIMARY KEY (employee_id),
+    CONSTRAINT UK_Employees_Email UNIQUE (email),
+    CONSTRAINT CK_Employees_Salary CHECK (salary >= 0),
+    CONSTRAINT FK_Employees_Departments
+        FOREIGN KEY (department_id) REFERENCES Departments(department_id)
+        ON DELETE CASCADE
+        ON UPDATE CASCADE
+);
+GO
+
+-- Create indexes for performance optimization
+CREATE INDEX IX_Employees_DepartmentId ON Employees(department_id);
+CREATE INDEX IX_Employees_LastName ON Employees(last_name);
+CREATE INDEX IX_Employees_Email ON Employees(email);
+GO
+
+PRINT 'Employees table created successfully.';
+GO
+
+-- ============================================================================
+-- SAMPLE DATA: Departments
+-- ============================================================================
+
+INSERT INTO Departments (name, budget, created_date) VALUES
+    ('Engineering', 2500000.00, '2023-01-15'),
+    ('Human Resources', 800000.00, '2023-01-15'),
+    ('Sales', 1500000.00, '2023-01-20'),
+    ('Marketing', 1200000.00, '2023-02-01'),
+    ('Finance', 1000000.00, '2023-02-10');
+GO
+
+PRINT 'Sample departments inserted successfully.';
+GO
+
+-- ============================================================================
+-- SAMPLE DATA: Employees
+-- ============================================================================
+
+INSERT INTO Employees (first_name, last_name, email, salary, hire_date, department_id) VALUES
+    -- Engineering Department (ID: 1)
+    ('John', 'Smith', 'john.smith@adenhive.com', 120000.00, '2023-03-01', 1),
+    ('Sarah', 'Johnson', 'sarah.johnson@adenhive.com', 115000.00, '2023-03-15', 1),
+    ('Michael', 'Chen', 'michael.chen@adenhive.com', 125000.00, '2023-04-01', 1),
+    ('Emily', 'Rodriguez', 'emily.rodriguez@adenhive.com', 110000.00, '2023-05-10', 1),
+    ('David', 'Kim', 'david.kim@adenhive.com', 105000.00, '2024-01-15', 1),
+
+    -- Human Resources Department (ID: 2)
+    ('Lisa', 'Anderson', 'lisa.anderson@adenhive.com', 85000.00, '2023-02-20', 2),
+    ('James', 'Wilson', 'james.wilson@adenhive.com', 80000.00, '2023-06-01', 2),
+
+    -- Sales Department (ID: 3)
+    ('Jennifer', 'Taylor', 'jennifer.taylor@adenhive.com', 95000.00, '2023-04-15', 3),
+    ('Robert', 'Martinez', 'robert.martinez@adenhive.com', 90000.00, '2023-05-01', 3),
+    ('Amanda', 'Garcia', 'amanda.garcia@adenhive.com', 92000.00, '2023-07-20', 3),
+
+    -- Marketing Department (ID: 4)
+    ('Christopher', 'Lee', 'christopher.lee@adenhive.com', 88000.00, '2023-03-10', 4),
+    ('Michelle', 'White', 'michelle.white@adenhive.com', 86000.00, '2023-08-01', 4),
+    ('Kevin', 'Brown', 'kevin.brown@adenhive.com', 84000.00, '2024-02-01', 4),
+
+    -- Finance Department (ID: 5)
+    ('Jessica', 'Davis', 'jessica.davis@adenhive.com', 98000.00, '2023-02-15', 5),
+    ('Daniel', 'Miller', 'daniel.miller@adenhive.com', 95000.00, '2023-09-01', 5);
+GO
+
+PRINT 'Sample employees inserted successfully.';
+GO
+
+-- ============================================================================
+-- VERIFICATION QUERIES
+-- ============================================================================
+
+PRINT '';
+PRINT '============================================================';
+PRINT 'Database Setup Summary';
+PRINT '============================================================';
+
+-- Count departments
+DECLARE @DeptCount INT;
+SELECT @DeptCount = COUNT(*) FROM Departments;
+PRINT 'Total Departments: ' + CAST(@DeptCount AS NVARCHAR(10));
+
+-- Count employees
+DECLARE @EmpCount INT;
+SELECT @EmpCount = COUNT(*) FROM Employees;
+PRINT 'Total Employees: ' + CAST(@EmpCount AS NVARCHAR(10));
+
+-- Show department summary
+PRINT '';
+PRINT 'Department Summary:';
+PRINT '------------------------------------------------------------';
+SELECT
+    d.name AS Department,
+    COUNT(e.employee_id) AS Employees,
+    d.budget AS Budget,
+    FORMAT(d.budget / NULLIF(COUNT(e.employee_id), 0), 'C', 'en-US') AS BudgetPerEmployee
+FROM Departments d
+LEFT JOIN Employees e ON d.department_id = e.department_id
+GROUP BY d.name, d.budget
+ORDER BY d.name;
+GO
+
+PRINT '';
+PRINT '============================================================';
+PRINT 'AdenTestDB initialization completed successfully!';
+PRINT '============================================================';
+PRINT '';
+PRINT 'Next Steps:';
+PRINT '1. Run: python test_mssql_connection.py';
+PRINT '2. Verify JOIN queries work correctly';
+PRINT '3. Test relational integrity';
+PRINT '============================================================';
+GO

tools/mcp_server.py

@@ -16,6 +16,8 @@ Usage:
 
 Environment Variables:
     MCP_PORT                  - Server port (default: 4001)
+    INCLUDE_UNVERIFIED_TOOLS  - Set to "true", "1", or "yes" to also load
+                                unverified/community tool integrations (default: off)
     ANTHROPIC_API_KEY         - Required at startup for testing/LLM nodes
     BRAVE_SEARCH_API_KEY      - Required for web_search tool (validated at agent load time)
 
@@ -81,7 +83,8 @@ except CredentialError as e:
 mcp = FastMCP("tools")
 
 # Register all tools with the MCP server, passing credential store
-tools = register_all_tools(mcp, credentials=credentials)
+include_unverified = os.getenv("INCLUDE_UNVERIFIED_TOOLS", "").lower() in ("true", "1", "yes")
+tools = register_all_tools(mcp, credentials=credentials, include_unverified=include_unverified)
 # Only print to stdout in HTTP mode (STDIO mode requires clean stdout for JSON-RPC)
 if "--stdio" not in sys.argv:
     logger.info(f"Registered {len(tools)} tools: {tools}")

tools/payroll_analysis.py

@@ -0,0 +1,208 @@
+"""
+Payroll Analysis Tool
+Analyzes total payroll costs by department and identifies highest-paid employee
+"""
+
+import io
+import os
+import sys
+
+import pyodbc
+from dotenv import load_dotenv
+
+# Force UTF-8 encoding for console output
+sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding="utf-8")
+
+# Load environment variables from .env file
+load_dotenv()
+
+# Database connection settings (from environment variables)
+SERVER = os.getenv("MSSQL_SERVER", r"MONSTER\MSSQLSERVERR")
+DATABASE = os.getenv("MSSQL_DATABASE", "AdenTestDB")
+USERNAME = os.getenv("MSSQL_USERNAME")
+PASSWORD = os.getenv("MSSQL_PASSWORD")
+
+
+def main():
+    """Main analysis function."""
+    connection = None
+
+    try:
+        print("=" * 80)
+        print("  COMPANY PAYROLL ANALYSIS")
+        print("=" * 80)
+        print(f"Server: {SERVER}")
+        print(f"Database: {DATABASE}")
+        print()
+
+        # Connect to database
+        if USERNAME and PASSWORD:
+            # SQL Server Authentication
+            connection_string = (
+                f"DRIVER={{ODBC Driver 17 for SQL Server}};"
+                f"SERVER={SERVER};"
+                f"DATABASE={DATABASE};"
+                f"UID={USERNAME};"
+                f"PWD={PASSWORD};"
+            )
+        else:
+            # Windows Authentication
+            connection_string = (
+                f"DRIVER={{ODBC Driver 17 for SQL Server}};"
+                f"SERVER={SERVER};"
+                f"DATABASE={DATABASE};"
+                f"Trusted_Connection=yes;"
+            )
+
+        print("Connecting to database...")
+        connection = pyodbc.connect(connection_string)
+        cursor = connection.cursor()
+        print("✓ Connection successful!")
+        print()
+
+        # Analysis 1: Total Payroll by Department
+        print("=" * 80)
+        print("  TOTAL SALARY COSTS BY DEPARTMENT")
+        print("=" * 80)
+
+        payroll_query = """
+        SELECT
+            d.name AS department_name,
+            COUNT(e.employee_id) AS employee_count,
+            SUM(e.salary) AS total_salary_cost,
+            AVG(e.salary) AS avg_salary
+        FROM Departments d
+        LEFT JOIN Employees e ON d.department_id = e.department_id
+        GROUP BY d.name
+        ORDER BY total_salary_cost DESC
+        """
+
+        cursor.execute(payroll_query)
+
+        print(
+            f"\n{'Department':<25} {'Employees':<12} {'Total Salary Cost':<20} {'Avg Salary':<15}"
+        )
+        print("-" * 80)
+
+        total_company_payroll = 0
+        total_employees = 0
+
+        for row in cursor:
+            dept_name = row[0]
+            emp_count = row[1]
+            total_salary = row[2] if row[2] else 0
+            avg_salary = row[3] if row[3] else 0
+
+            total_company_payroll += total_salary
+            total_employees += emp_count
+
+            total_salary_str = f"${total_salary:,.2f}"
+            avg_salary_str = f"${avg_salary:,.2f}" if avg_salary > 0 else "N/A"
+
+            print(f"{dept_name:<25} {emp_count:<12} {total_salary_str:<20} {avg_salary_str:<15}")
+
+        print("-" * 80)
+        print(f"{'TOTAL COMPANY':<25} {total_employees:<12} ${total_company_payroll:,.2f}")
+        print("-" * 80)
+        print()
+
+        # Analysis 2: Highest Paid Employee
+        print("=" * 80)
+        print("  HIGHEST PAID EMPLOYEE")
+        print("=" * 80)
+
+        highest_paid_query = """
+        SELECT TOP 1
+            e.employee_id,
+            e.first_name + ' ' + e.last_name AS full_name,
+            e.email,
+            e.salary,
+            d.name AS department_name
+        FROM Employees e
+        INNER JOIN Departments d ON e.department_id = d.department_id
+        ORDER BY e.salary DESC
+        """
+
+        cursor.execute(highest_paid_query)
+        top_employee = cursor.fetchone()
+
+        if top_employee:
+            print(f"\n{'Field':<20} {'Value':<50}")
+            print("-" * 80)
+            print(f"{'Employee ID':<20} {top_employee[0]}")
+            print(f"{'Name':<20} {top_employee[1]}")
+            print(f"{'Email':<20} {top_employee[2]}")
+            print(f"{'Department':<20} {top_employee[4]}")
+            print(f"{'Salary':<20} ${top_employee[3]:,.2f}")
+            print("-" * 80)
+        else:
+            print("\nNo employees found in the database.")
+
+        print()
+
+        # Additional Analysis: Top 5 Highest Paid Employees
+        print("=" * 80)
+        print("  TOP 5 HIGHEST PAID EMPLOYEES")
+        print("=" * 80)
+
+        top_5_query = """
+        SELECT TOP 5
+            e.first_name + ' ' + e.last_name AS full_name,
+            d.name AS department_name,
+            e.salary
+        FROM Employees e
+        INNER JOIN Departments d ON e.department_id = d.department_id
+        ORDER BY e.salary DESC
+        """
+
+        cursor.execute(top_5_query)
+
+        print(f"\n{'Rank':<6} {'Name':<30} {'Department':<25} {'Salary':<15}")
+        print("-" * 80)
+
+        rank = 1
+        for row in cursor:
+            full_name = row[0]
+            dept_name = row[1]
+            salary = row[2]
+
+            print(f"{rank:<6} {full_name:<30} {dept_name:<25} ${salary:,.2f}")
+            rank += 1
+
+        print("-" * 80)
+        print()
+
+        # Summary
+        print("=" * 80)
+        print("  ANALYSIS SUMMARY")
+        print("=" * 80)
+        print(f"✓ Total Employees: {total_employees}")
+        print(f"✓ Total Company Payroll: ${total_company_payroll:,.2f}")
+        print(
+            f"✓ Average Employee Salary: ${total_company_payroll / total_employees:,.2f}"
+            if total_employees > 0
+            else "N/A"
+        )
+        print("=" * 80)
+        print("\nPayroll analysis completed successfully!")
+
+    except pyodbc.Error as e:
+        print("\n[ERROR] Database operation failed!")
+        print(f"Error detail: {str(e)}")
+        print()
+        print("Possible solutions:")
+        print("1. Ensure SQL Server is running")
+        print("2. Verify database access permissions")
+        print("3. Check connection string configuration")
+
+    except Exception as e:
+        print(f"\n[ERROR] Unexpected error: {str(e)}")
+
+    finally:
+        if connection:
+            connection.close()
+            print("\nConnection closed.")
+
+
+if __name__ == "__main__":
+    main()

tools/pyproject.toml

@@ -31,6 +31,7 @@ dependencies = [
     "litellm>=1.81.0",
     "dnspython>=2.4.0",
     "resend>=2.0.0",
+    "asana>=3.2.0",
     "google-analytics-data>=0.18.0",
     "framework",
     "stripe>=14.3.0",
@@ -60,6 +61,10 @@ sql = [
 bigquery = [
     "google-cloud-bigquery>=3.0.0",
 ]
+databricks = [
+    "databricks-sdk>=0.30.0",
+    "databricks-mcp>=0.1.0",
+]
 all = [
     "RestrictedPython>=7.0",
     "pytesseract>=0.3.10",
@@ -67,6 +72,8 @@ all = [
     "duckdb>=1.0.0",
     "openpyxl>=3.1.0",
     "google-cloud-bigquery>=3.0.0",
+    "databricks-sdk>=0.30.0",
+    "databricks-mcp>=0.1.0",
 ]
 
 [tool.uv.sources]
@@ -107,6 +114,10 @@ lint.isort.section-order = [
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 asyncio_mode = "auto"
+addopts = "-m 'not live'"
+markers = [
+    "live: Tests that call real external APIs (require credentials, never run in CI)",
+]
 
 [dependency-groups]
 dev = [

tools/query_avg_salary.py

@@ -0,0 +1,117 @@
+"""
+Query Average Salary by Department
+"""
+
+import io
+import os
+import sys
+
+import pyodbc
+from dotenv import load_dotenv
+
+# Force UTF-8 encoding for console output
+sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding="utf-8")
+
+# Load environment variables from .env file
+load_dotenv()
+
+# Database connection settings (from environment variables)
+SERVER = os.getenv("MSSQL_SERVER", r"MONSTER\\MSSQLSERVERR")
+DATABASE = os.getenv("MSSQL_DATABASE", "AdenTestDB")
+USERNAME = os.getenv("MSSQL_USERNAME")
+PASSWORD = os.getenv("MSSQL_PASSWORD")
+
+
+def main():
+    """Query and display average salary by department."""
+    connection = None
+
+    try:
+        # Connect to database
+        if USERNAME and PASSWORD:
+            # SQL Server Authentication
+            connection_string = (
+                f"DRIVER={{ODBC Driver 17 for SQL Server}};"
+                f"SERVER={SERVER};"
+                f"DATABASE={DATABASE};"
+                f"UID={USERNAME};"
+                f"PWD={PASSWORD};"
+            )
+        else:
+            # Windows Authentication
+            connection_string = (
+                f"DRIVER={{ODBC Driver 17 for SQL Server}};"
+                f"SERVER={SERVER};"
+                f"DATABASE={DATABASE};"
+                f"Trusted_Connection=yes;"
+            )
+
+        connection = pyodbc.connect(connection_string)
+        cursor = connection.cursor()
+
+        # Query to get average salary by department, sorted by average salary descending
+        query = """
+        SELECT
+            d.name AS department,
+            AVG(e.salary) AS avg_salary,
+            COUNT(e.employee_id) AS emp_count
+        FROM Departments d
+        LEFT JOIN Employees e ON d.department_id = e.department_id
+        WHERE e.salary IS NOT NULL
+        GROUP BY d.name
+        ORDER BY avg_salary DESC
+        """
+
+        cursor.execute(query)
+        results = cursor.fetchall()
+
+        if not results:
+            print("No salary data found.")
+            return
+
+        # Get the highest average salary for highlighting
+        highest_avg = results[0][1] if results else 0
+
+        print("=" * 80)
+        print("  AVERAGE SALARY BY DEPARTMENT (Sorted Highest to Lowest)")
+        print("=" * 80)
+        print()
+        print(f"{'Rank':<6} {'Department':<25} {'Avg Salary':<20} {'Employees':<12}")
+        print("-" * 80)
+
+        for idx, row in enumerate(results, 1):
+            department = row[0]
+            avg_salary = row[1]
+            emp_count = row[2]
+
+            avg_salary_str = f"${avg_salary:,.2f}"
+
+            # Highlight the department with the highest average
+            if avg_salary == highest_avg:
+                # Use special formatting for the highest
+                prefix = f"{'>>> ' + str(idx):<6}"
+                print(f"{prefix} {department:<25} {avg_salary_str:<20} {emp_count:<12} ⭐ HIGHEST")
+            else:
+                print(f"{idx:<6} {department:<25} {avg_salary_str:<20} {emp_count:<12}")
+
+        print("-" * 80)
+        print()
+        print("📊 Summary:")
+        print(f"   • Total departments with employees: {len(results)}")
+        print(f"   • Highest average salary: ${highest_avg:,.2f} ({results[0][0]})")
+        print(f"   • Lowest average salary: ${results[-1][1]:,.2f} ({results[-1][0]})")
+        print("=" * 80)
+
+    except pyodbc.Error as e:
+        print(f"\n[ERROR] Database operation failed: {str(e)}")
+
+    except Exception as e:
+        print(f"\n[ERROR] Unexpected error: {str(e)}")
+
+    finally:
+        if connection:
+            connection.close()
+
+
+if __name__ == "__main__":
+    main()

tools/src/aden_tools/credentials/__init__.py

@@ -33,17 +33,20 @@ Usage:
     })
 
 Credential categories:
-- llm.py: LLM provider credentials (anthropic, openai, etc.)
 - search.py: Search tool credentials (brave_search, google_search, etc.)
 - email.py: Email provider credentials (resend, google/gmail)
 - apollo.py: Apollo.io API credentials
+- brevo.py: Brevo (Sendinblue) transactional email/SMS credentials
 - discord.py: Discord bot credentials
 - github.py: GitHub API credentials
+- google_analytics.py: Google Analytics 4 Data API credentials
+- google_docs.py: Google Docs API credentials
+- google_maps.py: Google Maps Platform credentials
 - hubspot.py: HubSpot CRM credentials
 - intercom.py: Intercom customer messaging credentials
+- postgres.py: PostgreSQL database credentials
 - slack.py: Slack workspace credentials
-- google_analytics.py: Google Analytics credentials
-- google_maps.py: Google Maps Platform credentials
+- stripe.py: Stripe payments API credentials
 - calcom.py: Cal.com scheduling API credentials
 
 Note: Tools that don't need credentials simply omit the 'credentials' parameter
@@ -55,32 +58,65 @@ To add a new credential:
 3. If new category, import and merge it in this __init__.py
 """
 
+from .airtable import AIRTABLE_CREDENTIALS
+from .apify import APIFY_CREDENTIALS
 from .apollo import APOLLO_CREDENTIALS
+from .asana import ASANA_CREDENTIALS
+from .attio import ATTIO_CREDENTIALS
+from .aws_s3 import AWS_S3_CREDENTIALS
+from .azure_sql import AZURE_SQL_CREDENTIALS
 from .base import CredentialError, CredentialSpec
 from .bigquery import BIGQUERY_CREDENTIALS
 from .brevo import BREVO_CREDENTIALS
 from .browser import get_aden_auth_url, get_aden_setup_url, open_browser
 from .calcom import CALCOM_CREDENTIALS
+from .calendly import CALENDLY_CREDENTIALS
+from .cloudinary import CLOUDINARY_CREDENTIALS
+from .confluence import CONFLUENCE_CREDENTIALS
+from .databricks import DATABRICKS_CREDENTIALS
 from .discord import DISCORD_CREDENTIALS
+from .docker_hub import DOCKER_HUB_CREDENTIALS
 from .email import EMAIL_CREDENTIALS
 from .gcp_vision import GCP_VISION_CREDENTIALS
 from .github import GITHUB_CREDENTIALS
+from .gitlab import GITLAB_CREDENTIALS
 from .google_analytics import GOOGLE_ANALYTICS_CREDENTIALS
-from .google_calendar import GOOGLE_CALENDAR_CREDENTIALS
 from .google_docs import GOOGLE_DOCS_CREDENTIALS
 from .google_maps import GOOGLE_MAPS_CREDENTIALS
+from .google_search_console import GOOGLE_SEARCH_CONSOLE_CREDENTIALS
+from .greenhouse import GREENHOUSE_CREDENTIALS
 from .health_check import (
-    BaseHttpHealthChecker,
     HealthCheckResult,
     check_credential_health,
-    validate_integration_wiring,
 )
 from .hubspot import HUBSPOT_CREDENTIALS
+from .huggingface import HUGGINGFACE_CREDENTIALS
 from .intercom import INTERCOM_CREDENTIALS
-from .llm import LLM_CREDENTIALS
+from .jira import JIRA_CREDENTIALS
+from .kafka import KAFKA_CREDENTIALS
+from .langfuse import LANGFUSE_CREDENTIALS
+from .linear import LINEAR_CREDENTIALS
+from .lusha import LUSHA_CREDENTIALS
+from .microsoft_graph import MICROSOFT_GRAPH_CREDENTIALS
+from .mongodb import MONGODB_CREDENTIALS
+from .n8n import N8N_CREDENTIALS
 from .news import NEWS_CREDENTIALS
+from .notion import NOTION_CREDENTIALS
+from .obsidian import OBSIDIAN_CREDENTIALS
+from .pagerduty import PAGERDUTY_CREDENTIALS
+from .pinecone import PINECONE_CREDENTIALS
+from .pipedrive import PIPEDRIVE_CREDENTIALS
+from .plaid import PLAID_CREDENTIALS
 from .postgres import POSTGRES_CREDENTIALS
+from .powerbi import POWERBI_CREDENTIALS
+from .pushover import PUSHOVER_CREDENTIALS
+from .quickbooks import QUICKBOOKS_CREDENTIALS
 from .razorpay import RAZORPAY_CREDENTIALS
+from .reddit import REDDIT_CREDENTIALS
+from .redis import REDIS_CREDENTIALS
+from .redshift import REDSHIFT_CREDENTIALS
+from .salesforce import SALESFORCE_CREDENTIALS
+from .sap import SAP_CREDENTIALS
 from .search import SEARCH_CREDENTIALS
 from .serpapi import SERPAPI_CREDENTIALS
 from .shell_config import (
@@ -89,36 +125,101 @@ from .shell_config import (
     get_shell_config_path,
     get_shell_source_command,
 )
+from .shopify import SHOPIFY_CREDENTIALS
 from .slack import SLACK_CREDENTIALS
+from .snowflake import SNOWFLAKE_CREDENTIALS
 from .store_adapter import CredentialStoreAdapter
 from .stripe import STRIPE_CREDENTIALS
+from .supabase import SUPABASE_CREDENTIALS
 from .telegram import TELEGRAM_CREDENTIALS
+from .terraform import TERRAFORM_CREDENTIALS
+from .tines import TINES_CREDENTIALS
+from .trello import TRELLO_CREDENTIALS
+from .twilio import TWILIO_CREDENTIALS
+from .twitter import TWITTER_CREDENTIALS
+from .vercel import VERCEL_CREDENTIALS
+from .youtube import YOUTUBE_CREDENTIALS
+from .zendesk import ZENDESK_CREDENTIALS
+from .zoho_crm import ZOHO_CRM_CREDENTIALS
+from .zoom import ZOOM_CREDENTIALS
 
 # Merged registry of all credentials
 CREDENTIAL_SPECS = {
-    **LLM_CREDENTIALS,
+    **AIRTABLE_CREDENTIALS,
     **NEWS_CREDENTIALS,
     **SEARCH_CREDENTIALS,
     **EMAIL_CREDENTIALS,
     **GCP_VISION_CREDENTIALS,
+    **APIFY_CREDENTIALS,
     **APOLLO_CREDENTIALS,
+    **ASANA_CREDENTIALS,
+    **ATTIO_CREDENTIALS,
+    **AWS_S3_CREDENTIALS,
+    **AZURE_SQL_CREDENTIALS,
+    **BIGQUERY_CREDENTIALS,
+    **BREVO_CREDENTIALS,
+    **CALCOM_CREDENTIALS,
+    **CALENDLY_CREDENTIALS,
+    **CLOUDINARY_CREDENTIALS,
+    **CONFLUENCE_CREDENTIALS,
+    **DATABRICKS_CREDENTIALS,
     **DISCORD_CREDENTIALS,
+    **DOCKER_HUB_CREDENTIALS,
+    **EMAIL_CREDENTIALS,
+    **GCP_VISION_CREDENTIALS,
     **GITHUB_CREDENTIALS,
+    **GREENHOUSE_CREDENTIALS,
+    **GITLAB_CREDENTIALS,
     **GOOGLE_ANALYTICS_CREDENTIALS,
     **GOOGLE_DOCS_CREDENTIALS,
     **GOOGLE_MAPS_CREDENTIALS,
+    **GOOGLE_SEARCH_CONSOLE_CREDENTIALS,
     **HUBSPOT_CREDENTIALS,
+    **HUGGINGFACE_CREDENTIALS,
     **INTERCOM_CREDENTIALS,
-    **GOOGLE_CALENDAR_CREDENTIALS,
-    **SLACK_CREDENTIALS,
-    **SERPAPI_CREDENTIALS,
-    **RAZORPAY_CREDENTIALS,
-    **TELEGRAM_CREDENTIALS,
-    **BIGQUERY_CREDENTIALS,
-    **CALCOM_CREDENTIALS,
-    **STRIPE_CREDENTIALS,
-    **BREVO_CREDENTIALS,
+    **JIRA_CREDENTIALS,
+    **KAFKA_CREDENTIALS,
+    **LANGFUSE_CREDENTIALS,
+    **LINEAR_CREDENTIALS,
+    **LUSHA_CREDENTIALS,
+    **MICROSOFT_GRAPH_CREDENTIALS,
+    **MONGODB_CREDENTIALS,
+    **N8N_CREDENTIALS,
+    **NEWS_CREDENTIALS,
+    **NOTION_CREDENTIALS,
+    **OBSIDIAN_CREDENTIALS,
+    **PAGERDUTY_CREDENTIALS,
+    **PINECONE_CREDENTIALS,
+    **PIPEDRIVE_CREDENTIALS,
+    **PLAID_CREDENTIALS,
     **POSTGRES_CREDENTIALS,
+    **POWERBI_CREDENTIALS,
+    **PUSHOVER_CREDENTIALS,
+    **QUICKBOOKS_CREDENTIALS,
+    **RAZORPAY_CREDENTIALS,
+    **REDDIT_CREDENTIALS,
+    **REDIS_CREDENTIALS,
+    **REDSHIFT_CREDENTIALS,
+    **SALESFORCE_CREDENTIALS,
+    **SAP_CREDENTIALS,
+    **SEARCH_CREDENTIALS,
+    **SERPAPI_CREDENTIALS,
+    **SHOPIFY_CREDENTIALS,
+    **SLACK_CREDENTIALS,
+    **SNOWFLAKE_CREDENTIALS,
+    **STRIPE_CREDENTIALS,
+    **SUPABASE_CREDENTIALS,
+    **TELEGRAM_CREDENTIALS,
+    **TERRAFORM_CREDENTIALS,
+    **TINES_CREDENTIALS,
+    **TRELLO_CREDENTIALS,
+    **TWILIO_CREDENTIALS,
+    **TWITTER_CREDENTIALS,
+    **VERCEL_CREDENTIALS,
+    **YOUTUBE_CREDENTIALS,
+    **ZENDESK_CREDENTIALS,
+    **ZOHO_CRM_CREDENTIALS,
+    **ZOOM_CREDENTIALS,
 }
 
 __all__ = [
@@ -126,13 +227,9 @@ __all__ = [
     "CredentialSpec",
     "CredentialStoreAdapter",
     "CredentialError",
-    # Credential store adapter (replaces deprecated CredentialManager)
-    "CredentialStoreAdapter",
     # Health check utilities
-    "BaseHttpHealthChecker",
     "HealthCheckResult",
     "check_credential_health",
-    "validate_integration_wiring",
     # Browser utilities for OAuth2 flows
     "open_browser",
     "get_aden_auth_url",
@@ -144,28 +241,76 @@ __all__ = [
     "add_env_var_to_shell_config",
     # Merged registry
     "CREDENTIAL_SPECS",
-    # Category registries (for direct access if needed)
-    "LLM_CREDENTIALS",
-    "NEWS_CREDENTIALS",
-    "SEARCH_CREDENTIALS",
+    # Category registries
+    "AIRTABLE_CREDENTIALS",
+    "APIFY_CREDENTIALS",
+    "APOLLO_CREDENTIALS",
+    "ASANA_CREDENTIALS",
+    "ATTIO_CREDENTIALS",
+    "AWS_S3_CREDENTIALS",
+    "AZURE_SQL_CREDENTIALS",
+    "BIGQUERY_CREDENTIALS",
+    "BREVO_CREDENTIALS",
+    "CALCOM_CREDENTIALS",
+    "CALENDLY_CREDENTIALS",
+    "CLOUDINARY_CREDENTIALS",
+    "CONFLUENCE_CREDENTIALS",
+    "DATABRICKS_CREDENTIALS",
+    "DISCORD_CREDENTIALS",
+    "DOCKER_HUB_CREDENTIALS",
     "EMAIL_CREDENTIALS",
     "GCP_VISION_CREDENTIALS",
     "GITHUB_CREDENTIALS",
+    "GREENHOUSE_CREDENTIALS",
+    "GITLAB_CREDENTIALS",
     "GOOGLE_ANALYTICS_CREDENTIALS",
     "GOOGLE_DOCS_CREDENTIALS",
     "GOOGLE_MAPS_CREDENTIALS",
+    "GOOGLE_SEARCH_CONSOLE_CREDENTIALS",
     "HUBSPOT_CREDENTIALS",
+    "HUGGINGFACE_CREDENTIALS",
     "INTERCOM_CREDENTIALS",
-    "GOOGLE_CALENDAR_CREDENTIALS",
-    "SLACK_CREDENTIALS",
-    "APOLLO_CREDENTIALS",
-    "SERPAPI_CREDENTIALS",
-    "RAZORPAY_CREDENTIALS",
-    "TELEGRAM_CREDENTIALS",
-    "BIGQUERY_CREDENTIALS",
-    "CALCOM_CREDENTIALS",
-    "DISCORD_CREDENTIALS",
-    "STRIPE_CREDENTIALS",
-    "BREVO_CREDENTIALS",
+    "JIRA_CREDENTIALS",
+    "KAFKA_CREDENTIALS",
+    "LANGFUSE_CREDENTIALS",
+    "LINEAR_CREDENTIALS",
+    "LUSHA_CREDENTIALS",
+    "MICROSOFT_GRAPH_CREDENTIALS",
+    "MONGODB_CREDENTIALS",
+    "N8N_CREDENTIALS",
+    "NEWS_CREDENTIALS",
+    "NOTION_CREDENTIALS",
+    "OBSIDIAN_CREDENTIALS",
+    "PAGERDUTY_CREDENTIALS",
+    "PINECONE_CREDENTIALS",
+    "PIPEDRIVE_CREDENTIALS",
+    "PLAID_CREDENTIALS",
     "POSTGRES_CREDENTIALS",
+    "POWERBI_CREDENTIALS",
+    "PUSHOVER_CREDENTIALS",
+    "QUICKBOOKS_CREDENTIALS",
+    "RAZORPAY_CREDENTIALS",
+    "REDDIT_CREDENTIALS",
+    "REDIS_CREDENTIALS",
+    "REDSHIFT_CREDENTIALS",
+    "SALESFORCE_CREDENTIALS",
+    "SAP_CREDENTIALS",
+    "SEARCH_CREDENTIALS",
+    "SERPAPI_CREDENTIALS",
+    "SHOPIFY_CREDENTIALS",
+    "SLACK_CREDENTIALS",
+    "SNOWFLAKE_CREDENTIALS",
+    "STRIPE_CREDENTIALS",
+    "SUPABASE_CREDENTIALS",
+    "TELEGRAM_CREDENTIALS",
+    "TERRAFORM_CREDENTIALS",
+    "TINES_CREDENTIALS",
+    "TRELLO_CREDENTIALS",
+    "TWILIO_CREDENTIALS",
+    "TWITTER_CREDENTIALS",
+    "VERCEL_CREDENTIALS",
+    "YOUTUBE_CREDENTIALS",
+    "ZENDESK_CREDENTIALS",
+    "ZOHO_CRM_CREDENTIALS",
+    "ZOOM_CREDENTIALS",
 ]

tools/src/aden_tools/credentials/airtable.py

@@ -0,0 +1,37 @@
+"""
+Airtable credentials.
+
+Contains credentials for the Airtable Web API.
+Requires AIRTABLE_PAT (Personal Access Token).
+"""
+
+from .base import CredentialSpec
+
+AIRTABLE_CREDENTIALS = {
+    "airtable_pat": CredentialSpec(
+        env_var="AIRTABLE_PAT",
+        tools=[
+            "airtable_list_records",
+            "airtable_get_record",
+            "airtable_create_records",
+            "airtable_update_records",
+            "airtable_list_bases",
+            "airtable_get_base_schema",
+        ],
+        required=True,
+        startup_required=False,
+        help_url="https://airtable.com/create/tokens",
+        description="Airtable Personal Access Token",
+        direct_api_key_supported=True,
+        api_key_instructions="""To set up Airtable API access:
+1. Go to https://airtable.com/create/tokens
+2. Create a new Personal Access Token
+3. Grant scopes: data.records:read, data.records:write, schema.bases:read
+4. Select the bases to grant access to
+5. Set environment variable:
+   export AIRTABLE_PAT=your-personal-access-token""",
+        health_check_endpoint="",
+        credential_id="airtable_pat",
+        credential_key="api_key",
+    ),
+}

tools/src/aden_tools/credentials/apify.py

@@ -0,0 +1,34 @@
+"""
+Apify credentials.
+
+Contains credentials for Apify web scraping and automation platform.
+"""
+
+from .base import CredentialSpec
+
+APIFY_CREDENTIALS = {
+    "apify": CredentialSpec(
+        env_var="APIFY_API_TOKEN",
+        tools=[
+            "apify_run_actor",
+            "apify_get_run",
+            "apify_get_dataset_items",
+            "apify_list_actors",
+            "apify_list_runs",
+            "apify_get_kv_store_record",
+        ],
+        required=True,
+        startup_required=False,
+        help_url="https://docs.apify.com/api/v2",
+        description="Apify API token for running web scraping actors and retrieving datasets",
+        direct_api_key_supported=True,
+        api_key_instructions="""To get an Apify API token:
+1. Go to https://console.apify.com/account/integrations
+2. Copy your personal API token
+3. Set the environment variable:
+   export APIFY_API_TOKEN=your-api-token""",
+        health_check_endpoint="https://api.apify.com/v2/users/me",
+        credential_id="apify",
+        credential_key="api_key",
+    ),
+}