fix: bom safe json loading

feat(tools): expand Telegram tool with message management, media, and chat info operations

.github/ISSUE_TEMPLATE/integration-bounty.yml

@@ -0,0 +1,89 @@
+name: Integration Bounty
+description: A bounty task for the integration contribution program
+title: "[Bounty]: "
+labels: []
+body:
+  - type: markdown
+    attributes:
+      value: |
+        ## Integration Bounty
+
+        This issue is part of the [Integration Bounty Program](../../docs/bounty-program/README.md).
+        **Claim this bounty** by commenting below — a maintainer will assign you within 24 hours.
+
+  - type: dropdown
+    id: bounty-type
+    attributes:
+      label: Bounty Type
+      options:
+        - "Test a Tool (20 pts)"
+        - "Write Docs (20 pts)"
+        - "Code Contribution (30 pts)"
+        - "New Integration (75 pts)"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: difficulty
+    attributes:
+      label: Difficulty
+      options:
+        - Easy
+        - Medium
+        - Hard
+    validations:
+      required: true
+
+  - type: input
+    id: tool-name
+    attributes:
+      label: Tool Name
+      description: The integration this bounty targets (e.g., `airtable`, `salesforce`)
+      placeholder: e.g., airtable
+    validations:
+      required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: What needs to be done to complete this bounty.
+      placeholder: |
+        Describe the specific task, including:
+        - What the contributor needs to do
+        - Links to relevant files in the repo
+        - Any setup requirements (API keys, accounts, etc.)
+    validations:
+      required: true
+
+  - type: textarea
+    id: acceptance-criteria
+    attributes:
+      label: Acceptance Criteria
+      description: What "done" looks like. The PR or report must meet all criteria.
+      placeholder: |
+        - [ ] Criterion 1
+        - [ ] Criterion 2
+        - [ ] CI passes
+    validations:
+      required: true
+
+  - type: textarea
+    id: relevant-files
+    attributes:
+      label: Relevant Files
+      description: Links to tool directory, credential spec, health check file, etc.
+      placeholder: |
+        - Tool: `tools/src/aden_tools/tools/{tool_name}/`
+        - Credential spec: `tools/src/aden_tools/credentials/{category}.py`
+        - Health checks: `tools/src/aden_tools/credentials/health_check.py`
+
+  - type: textarea
+    id: resources
+    attributes:
+      label: Resources
+      description: Links to API docs, examples, or guides that will help the contributor.
+      placeholder: |
+        - [Building Tools Guide](../../tools/BUILDING_TOOLS.md)
+        - [Tool README Template](../../docs/bounty-program/templates/tool-readme-template.md)
+        - API docs: https://...

.github/ISSUE_TEMPLATE/link-discord.yml

@@ -0,0 +1,31 @@
+name: Link Discord Account
+description: Connect your GitHub and Discord for the bounty program
+title: "link: @{{ github.actor }}"
+labels: ["link-discord"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Link your Discord account to receive XP and role rewards when your bounty PRs are merged.
+
+        **How to find your Discord ID:**
+        1. Open Discord Settings > Advanced > Enable **Developer Mode**
+        2. Right-click your username > **Copy User ID**
+
+  - type: input
+    id: discord_id
+    attributes:
+      label: Discord User ID
+      description: "Your numeric Discord ID (not your username). Example: 123456789012345678"
+      placeholder: "123456789012345678"
+    validations:
+      required: true
+
+  - type: input
+    id: display_name
+    attributes:
+      label: Display Name (optional)
+      description: How you'd like to be credited
+      placeholder: "Jane Doe"
+    validations:
+      required: false

.github/workflows/bounty-completed.yml

@@ -0,0 +1,37 @@
+name: Bounty completed
+description: Awards points and notifies Discord when a bounty PR is merged
+
+on:
+  pull_request:
+    types: [closed]
+
+jobs:
+  bounty-notify:
+    if: >
+      github.event.pull_request.merged == true &&
+      contains(join(github.event.pull_request.labels.*.name, ','), 'bounty:')
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: read
+      pull-requests: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Award XP and notify Discord
+        run: bun run scripts/bounty-tracker.ts notify
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_REPOSITORY_OWNER: ${{ github.repository_owner }}
+          GITHUB_REPOSITORY_NAME: ${{ github.event.repository.name }}
+          DISCORD_WEBHOOK_URL: ${{ secrets.DISCORD_BOUNTY_WEBHOOK_URL }}
+          LURKR_API_KEY: ${{ secrets.LURKR_API_KEY }}
+          LURKR_GUILD_ID: ${{ secrets.LURKR_GUILD_ID }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}

.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
 

.github/workflows/link-discord.yml

@@ -0,0 +1,126 @@
+name: Link Discord account
+description: Auto-creates a PR to add contributor to contributors.yml when a link-discord issue is opened
+
+on:
+  issues:
+    types: [opened]
+
+jobs:
+  link-discord:
+    if: contains(github.event.issue.labels.*.name, 'link-discord')
+    runs-on: ubuntu-latest
+    timeout-minutes: 2
+    permissions:
+      contents: write
+      issues: write
+      pull-requests: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Parse issue and update contributors.yml
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('fs');
+
+            const issue = context.payload.issue;
+            const githubUsername = issue.user.login;
+
+            // Parse the issue body for form fields
+            const body = issue.body || '';
+
+            // Extract Discord ID — look for the numeric value after the "Discord User ID" heading
+            const discordMatch = body.match(/### Discord User ID\s*\n\s*(\d{17,20})/);
+            if (!discordMatch) {
+              await github.rest.issues.createComment({
+                ...context.repo,
+                issue_number: issue.number,
+                body: `Could not find a valid Discord ID in the issue body. Please make sure you entered a numeric ID (17-20 digits), not a username.\n\nExample: \`123456789012345678\``
+              });
+              await github.rest.issues.update({
+                ...context.repo,
+                issue_number: issue.number,
+                state: 'closed',
+                state_reason: 'not_planned'
+              });
+              return;
+            }
+            const discordId = discordMatch[1];
+
+            // Extract display name (optional)
+            const nameMatch = body.match(/### Display Name \(optional\)\s*\n\s*(.+)/);
+            const displayName = nameMatch ? nameMatch[1].trim() : '';
+
+            // Check if user already exists
+            const yml = fs.readFileSync('contributors.yml', 'utf-8');
+            if (yml.includes(`github: ${githubUsername}`)) {
+              await github.rest.issues.createComment({
+                ...context.repo,
+                issue_number: issue.number,
+                body: `@${githubUsername} is already in \`contributors.yml\`. If you need to update your Discord ID, please edit the file directly via PR.`
+              });
+              await github.rest.issues.update({
+                ...context.repo,
+                issue_number: issue.number,
+                state: 'closed',
+                state_reason: 'completed'
+              });
+              return;
+            }
+
+            // Append entry to contributors.yml
+            let entry = `  - github: ${githubUsername}\n    discord: "${discordId}"`;
+            if (displayName && displayName !== '_No response_') {
+              entry += `\n    name: ${displayName}`;
+            }
+            entry += '\n';
+
+            const updated = yml.trimEnd() + '\n' + entry;
+            fs.writeFileSync('contributors.yml', updated);
+
+            // Set outputs for commit step
+            core.exportVariable('GITHUB_USERNAME', githubUsername);
+            core.exportVariable('DISCORD_ID', discordId);
+            core.exportVariable('ISSUE_NUMBER', issue.number.toString());
+
+      - name: Create PR
+        run: |
+          # Check if there are changes
+          if git diff --quiet contributors.yml; then
+            echo "No changes to contributors.yml"
+            exit 0
+          fi
+
+          BRANCH="docs/link-discord-${GITHUB_USERNAME}"
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git checkout -b "$BRANCH"
+          git add contributors.yml
+          git commit -m "docs: link @${GITHUB_USERNAME} to Discord"
+          git push origin "$BRANCH"
+
+          gh pr create \
+            --title "docs: link @${GITHUB_USERNAME} to Discord" \
+            --body "Adds @${GITHUB_USERNAME} (Discord \`${DISCORD_ID}\`) to \`contributors.yml\` for bounty XP tracking.
+
+          Closes #${ISSUE_NUMBER}" \
+            --base main \
+            --head "$BRANCH" \
+            --label "link-discord"
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Notify on issue
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const username = process.env.GITHUB_USERNAME;
+            const issueNumber = parseInt(process.env.ISSUE_NUMBER);
+
+            await github.rest.issues.createComment({
+              ...context.repo,
+              issue_number: issueNumber,
+              body: `A PR has been created to link your account. A maintainer will merge it shortly — once merged, you'll receive XP and Discord pings when your bounty PRs are merged.`
+            });

.github/workflows/weekly-leaderboard.yml

@@ -0,0 +1,40 @@
+name: Weekly bounty leaderboard
+description: Posts the integration bounty leaderboard to Discord every Monday
+
+on:
+  schedule:
+    # Every Monday at 9:00 UTC
+    - cron: "0 9 * * 1"
+  workflow_dispatch:
+    inputs:
+      since_date:
+        description: "Only count PRs merged after this date (YYYY-MM-DD). Leave empty for all-time."
+        required: false
+
+jobs:
+  leaderboard:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: read
+      pull-requests: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Post leaderboard to Discord
+        run: bun run scripts/bounty-tracker.ts leaderboard
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_REPOSITORY_OWNER: ${{ github.repository_owner }}
+          GITHUB_REPOSITORY_NAME: ${{ github.event.repository.name }}
+          DISCORD_WEBHOOK_URL: ${{ secrets.DISCORD_BOUNTY_WEBHOOK_URL }}
+          LURKR_API_KEY: ${{ secrets.LURKR_API_KEY }}
+          LURKR_GUILD_ID: ${{ secrets.LURKR_GUILD_ID }}
+          SINCE_DATE: ${{ github.event.inputs.since_date || '' }}

.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

contributors.yml

@@ -0,0 +1,27 @@
+# Identity mapping: GitHub username -> Discord ID
+#
+# This file links GitHub accounts to Discord accounts for the
+# Integration Bounty Program. When a bounty PR is merged, the
+# GitHub Action uses this file to ping the contributor on Discord.
+#
+# HOW TO ADD YOURSELF:
+# Open a "Link Discord Account" issue:
+# https://github.com/aden-hive/hive/issues/new?template=link-discord.yml
+# A GitHub Action will automatically add your entry here.
+#
+# To find your Discord ID:
+# 1. Open Discord Settings > Advanced > Enable Developer Mode
+# 2. Right-click your name > Copy User ID
+#
+# Format:
+#   - github: your-github-username
+#     discord: "your-discord-id"  # quotes required (it's a number)
+#     name: Your Display Name      # optional
+
+contributors:
+  # - github: example-user
+  #   discord: "123456789012345678"
+  #   name: Example User
+  - github: TimothyZhang7
+    discord: "408460790061072384"
+    name: Timothy@Aden

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

@@ -6,6 +6,7 @@ helper functions.
 """
 
 import json
+import logging
 import os
 from dataclasses import dataclass, field
 from pathlib import Path
@@ -18,6 +19,7 @@ from framework.graph.edge import DEFAULT_MAX_TOKENS
 # ---------------------------------------------------------------------------
 
 HIVE_CONFIG_FILE = Path.home() / ".hive" / "configuration.json"
+logger = logging.getLogger(__name__)
 
 
 def get_hive_config() -> dict[str, Any]:
@@ -27,7 +29,12 @@ def get_hive_config() -> dict[str, Any]:
     try:
         with open(HIVE_CONFIG_FILE, encoding="utf-8-sig") as f:
             return json.load(f)
-    except (json.JSONDecodeError, OSError):
+    except (json.JSONDecodeError, OSError) as e:
+        logger.warning(
+            "Failed to load Hive config %s: %s",
+            HIVE_CONFIG_FILE,
+            e,
+        )
         return {}
 
 
@@ -92,7 +99,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/aden/client.py

@@ -37,6 +37,8 @@ from dataclasses import dataclass, field
 from datetime import datetime
 from typing import Any
 
+import json as _json
+
 import httpx
 
 logger = logging.getLogger(__name__)
@@ -260,6 +262,11 @@ class AdenCredentialClient:
         self.config = config
         self._client: httpx.Client | None = None
 
+    @staticmethod
+    def _parse_json(response: httpx.Response) -> Any:
+        """Parse JSON from response, tolerating UTF-8 BOM."""
+        return _json.loads(response.content.decode("utf-8-sig"))
+
     def _get_client(self) -> httpx.Client:
         if self._client is None:
             headers = {
@@ -295,7 +302,7 @@ class AdenCredentialClient:
                     raise AdenAuthenticationError("Agent API key is invalid or revoked")
 
                 if response.status_code == 403:
-                    data = response.json()
+                    data = self._parse_json(response)
                     raise AdenClientError(data.get("message", "Forbidden"))
 
                 if response.status_code == 404:
@@ -309,7 +316,7 @@ class AdenCredentialClient:
                     )
 
                 if response.status_code == 400:
-                    data = response.json()
+                    data = self._parse_json(response)
                     msg = data.get("message", "Bad request")
                     if data.get("error") == "refresh_failed" or "refresh" in msg.lower():
                         raise AdenRefreshError(
@@ -356,7 +363,7 @@ class AdenCredentialClient:
             alias, status, email, expires_at.
         """
         response = self._request_with_retry("GET", "/v1/credentials")
-        data = response.json()
+        data = self._parse_json(response)
         return [AdenIntegrationInfo.from_dict(item) for item in data.get("integrations", [])]
 
     # Alias
@@ -376,7 +383,7 @@ class AdenCredentialClient:
         """
         try:
             response = self._request_with_retry("GET", f"/v1/credentials/{integration_id}")
-            data = response.json()
+            data = self._parse_json(response)
             return AdenCredentialResponse.from_dict(data, integration_id=integration_id)
         except AdenNotFoundError:
             return None
@@ -394,7 +401,7 @@ class AdenCredentialClient:
             AdenCredentialResponse with new access_token.
         """
         response = self._request_with_retry("POST", f"/v1/credentials/{integration_id}/refresh")
-        data = response.json()
+        data = self._parse_json(response)
         return AdenCredentialResponse.from_dict(data, integration_id=integration_id)
 
     def validate_token(self, integration_id: str) -> dict[str, Any]:
@@ -407,7 +414,7 @@ class AdenCredentialClient:
             {"valid": bool, "status": str, "expires_at": str, "error": str|null}
         """
         response = self._request_with_retry("GET", f"/v1/credentials/{integration_id}/validate")
-        return response.json()
+        return self._parse_json(response)
 
     def health_check(self) -> dict[str, Any]:
         """Check Aden server health."""
@@ -415,7 +422,7 @@ class AdenCredentialClient:
             client = self._get_client()
             response = client.get("/health")
             if response.status_code == 200:
-                data = response.json()
+                data = self._parse_json(response)
                 data["latency_ms"] = response.elapsed.total_seconds() * 1000
                 return data
             return {"status": "degraded", "error": f"HTTP {response.status_code}"}

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-sig") as f:
             data = json.load(f)
 
         from framework.graph import NodeSpec

core/framework/credentials/storage.py

@@ -203,7 +203,7 @@ class EncryptedFileStorage(CredentialStorage):
         # Decrypt
         try:
             json_bytes = self._fernet.decrypt(encrypted)
-            data = json.loads(json_bytes.decode())
+            data = json.loads(json_bytes.decode("utf-8-sig"))
         except Exception as e:
             raise CredentialDecryptionError(
                 f"Failed to decrypt credential '{credential_id}': {e}"
@@ -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-sig") 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-sig") 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,69 +154,17 @@ 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:
-                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
-
+        # Map raw input to first question
+        response.answers[request.questions[0].id] = raw_input
         return response
 
     @staticmethod

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,59 +592,13 @@ 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]
-                if len(str(value)) > 100:
-                    value_str += "..."
-                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)
+        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]
+            if len(str(value)) > 100:
+                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,11 +554,28 @@ 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)
             return 1
+    # Validate --output path before execution begins (fail fast, before agent loads)
+    if args.output:
+        import os
+
+        output_parent = Path(args.output).parent
+        if not output_parent.exists():
+            print(
+                f"Error: output directory does not exist: {output_parent}/",
+                file=sys.stderr,
+            )
+            return 1
+        if not os.access(output_parent, os.W_OK):
+            print(
+                f"Error: output directory is not writable: {output_parent}/",
+                file=sys.stderr,
+            )
+            return 1
 
     # Run the agent (with TUI or standard)
     if getattr(args, "tui", False):
@@ -659,7 +713,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 +1107,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
+    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"
 
-    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
-        main_field = input_keys[0] if input_keys else "objective"
         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 +1528,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 +1939,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 +2004,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 +2100,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,7 +367,8 @@ class MCPClient:
             raise ValueError(f"Unknown tool: {tool_name}")
 
         if self.config.transport == "stdio":
-            return self._run_async(self._call_tool_stdio_async(tool_name, arguments))
+            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,11 +463,15 @@ 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:
-            logger.warning(f"Error closing STDIO context: {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:
-            json.dump(creds, f, indent=2)
-        logger.debug("Claude Code credentials refreshed successfully")
+        # 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 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:
@@ -621,6 +711,7 @@ class AgentRunner:
         requires_account_selection: bool = False,
         configure_for_account: Callable | None = None,
         list_accounts: Callable | None = None,
+        credential_store: Any | None = None,
     ):
         """
         Initialize the runner (use AgentRunner.load() instead).
@@ -640,6 +731,7 @@ class AgentRunner:
             requires_account_selection: If True, TUI shows account picker before starting.
             configure_for_account: Callback(runner, account_dict) to scope tools after selection.
             list_accounts: Callback() -> list[dict] to fetch available accounts.
+            credential_store: Optional shared CredentialStore (avoids creating redundant stores).
         """
         self.agent_path = agent_path
         self.graph = graph
@@ -653,6 +745,7 @@ class AgentRunner:
         self.requires_account_selection = requires_account_selection
         self._configure_for_account = configure_for_account
         self._list_accounts = list_accounts
+        self._credential_store = credential_store
 
         # Set up storage
         if storage_path:
@@ -750,6 +843,7 @@ class AgentRunner:
         model: str | None = None,
         interactive: bool = True,
         skip_credential_validation: bool | None = None,
+        credential_store: Any | None = None,
     ) -> "AgentRunner":
         """
         Load an agent from an export folder.
@@ -767,6 +861,7 @@ class AgentRunner:
                 Set to False from TUI callers that handle setup via their own UI.
             skip_credential_validation: If True, skip credential checks at load time.
                 When None (default), uses the agent module's setting.
+            credential_store: Optional shared CredentialStore (avoids creating redundant stores).
 
         Returns:
             AgentRunner instance ready to run
@@ -856,15 +951,19 @@ class AgentRunner:
                 requires_account_selection=needs_acct,
                 configure_for_account=configure_fn,
                 list_accounts=list_accts_fn,
+                credential_store=credential_store,
             )
 
         # Fallback: load from agent.json (legacy JSON-based agents)
         agent_json_path = agent_path / "agent.json"
-        if not agent_json_path.exists():
+        if not agent_json_path.is_file():
             raise FileNotFoundError(f"No agent.py or agent.json found in {agent_path}")
 
-        with open(agent_json_path) as f:
-            graph, goal = load_agent_export(f.read())
+        content = agent_json_path.read_text(encoding="utf-8").strip()
+        if not content:
+            raise FileNotFoundError(f"agent.json is empty: {agent_json_path}")
+
+        graph, goal = load_agent_export(content)
 
         return cls(
             agent_path=agent_path,
@@ -875,6 +974,7 @@ class AgentRunner:
             model=model,
             interactive=interactive,
             skip_credential_validation=skip_credential_validation or False,
+            credential_store=credential_store,
         )
 
     def register_tool(
@@ -1108,11 +1208,10 @@ class AgentRunner:
             # Auto-register GCU MCP server if tools aren't loaded yet
             gcu_tool_names = self._tool_registry.get_server_tool_names(GCU_SERVER_NAME)
             if not gcu_tool_names:
-                # Resolve relative cwd against agent path
+                # Resolve cwd to repo-level tools/ (not relative to agent_path)
                 gcu_config = dict(GCU_MCP_SERVER_CONFIG)
-                cwd = gcu_config.get("cwd")
-                if cwd and not Path(cwd).is_absolute():
-                    gcu_config["cwd"] = str((self.agent_path / cwd).resolve())
+                _repo_root = Path(__file__).resolve().parent.parent.parent.parent
+                gcu_config["cwd"] = str(_repo_root / "tools")
                 self._tool_registry.register_mcp_server(gcu_config)
                 gcu_tool_names = self._tool_registry.get_server_tool_names(GCU_SERVER_NAME)
 
@@ -1132,10 +1231,10 @@ class AgentRunner:
 
             files_tool_names = self._tool_registry.get_server_tool_names(FILES_MCP_SERVER_NAME)
             if not files_tool_names:
+                # Resolve cwd to repo-level tools/ (not relative to agent_path)
                 files_config = dict(FILES_MCP_SERVER_CONFIG)
-                cwd = files_config.get("cwd")
-                if cwd and not Path(cwd).is_absolute():
-                    files_config["cwd"] = str((self.agent_path / cwd).resolve())
+                _repo_root = Path(__file__).resolve().parent.parent.parent.parent
+                files_config["cwd"] = str(_repo_root / "tools")
                 self._tool_registry.register_mcp_server(files_config)
                 files_tool_names = self._tool_registry.get_server_tool_names(FILES_MCP_SERVER_NAME)
 
@@ -1158,7 +1257,10 @@ class AgentRunner:
         try:
             from aden_tools.credentials.store_adapter import CredentialStoreAdapter
 
-            adapter = CredentialStoreAdapter.default()
+            if self._credential_store is not None:
+                adapter = CredentialStoreAdapter(store=self._credential_store)
+            else:
+                adapter = CredentialStoreAdapter.default()
             accounts_data = adapter.get_all_account_info()
             tool_provider_map = adapter.get_tool_provider_map()
             if accounts_data:
@@ -1229,9 +1331,11 @@ class AgentRunner:
             return None
 
         try:
-            from framework.credentials import CredentialStore
+            store = self._credential_store
+            if store is None:
+                from framework.credentials import CredentialStore
 
-            store = CredentialStore.with_encrypted_storage()
+                store = CredentialStore.with_encrypted_storage()
             return store.get(cred_id)
         except Exception:
             return None

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/runtime/agent_runtime.py

@@ -1270,6 +1270,42 @@ class AgentRuntime:
         """Get the registration for a specific graph (or None)."""
         return self._graphs.get(graph_id)
 
+    def cancel_all_tasks(self, loop: asyncio.AbstractEventLoop) -> bool:
+        """Cancel all running execution tasks across all graphs.
+
+        Schedules the cancellation on *loop* (the agent event loop) so
+        that ``_execution_tasks`` is only read from the thread that owns
+        it, avoiding cross-thread dict access.  Safe to call from any
+        thread (e.g. the Textual UI thread).
+
+        Blocks the caller for up to 5 seconds waiting for the result.
+        For async callers, use :meth:`cancel_all_tasks_async` instead.
+        """
+        future = asyncio.run_coroutine_threadsafe(self.cancel_all_tasks_async(), loop)
+        try:
+            return future.result(timeout=5)
+        except Exception:
+            logger.warning("cancel_all_tasks: timed out or failed")
+            return False
+
+    async def cancel_all_tasks_async(self) -> bool:
+        """Cancel all running execution tasks (runs on the agent loop).
+
+        Iterates ``_execution_tasks`` and calls ``task.cancel()`` directly.
+        Must be awaited on the agent event loop so dict access is
+        thread-safe.  Returns True if at least one task was cancelled.
+        """
+        cancelled = False
+        for gid in self.list_graphs():
+            reg = self.get_graph_registration(gid)
+            if reg:
+                for stream in reg.streams.values():
+                    for task in list(stream._execution_tasks.values()):
+                        if task and not task.done():
+                            task.cancel()
+                            cancelled = True
+        return cancelled
+
     def _get_primary_session_state(
         self,
         exclude_entry_point: str,

core/framework/runtime/tests/test_agent_runtime.py

@@ -821,5 +821,148 @@ class TestTimerEntryPoints:
             await runtime.stop()
 
 
+# === Cancel All Tasks Tests ===
+
+
+class TestCancelAllTasks:
+    """Tests for cancel_all_tasks and cancel_all_tasks_async."""
+
+    @pytest.mark.asyncio
+    async def test_cancel_all_tasks_async_returns_false_when_no_tasks(
+        self, sample_graph, sample_goal, temp_storage
+    ):
+        """Test that cancel_all_tasks_async returns False with no running tasks."""
+        runtime = AgentRuntime(
+            graph=sample_graph,
+            goal=sample_goal,
+            storage_path=temp_storage,
+        )
+
+        entry_spec = EntryPointSpec(
+            id="webhook",
+            name="Webhook",
+            entry_node="process-webhook",
+            trigger_type="webhook",
+        )
+        runtime.register_entry_point(entry_spec)
+        await runtime.start()
+
+        try:
+            result = await runtime.cancel_all_tasks_async()
+            assert result is False
+        finally:
+            await runtime.stop()
+
+    @pytest.mark.asyncio
+    async def test_cancel_all_tasks_async_cancels_running_task(
+        self, sample_graph, sample_goal, temp_storage
+    ):
+        """Test that cancel_all_tasks_async cancels a running task and returns True."""
+        runtime = AgentRuntime(
+            graph=sample_graph,
+            goal=sample_goal,
+            storage_path=temp_storage,
+        )
+
+        entry_spec = EntryPointSpec(
+            id="webhook",
+            name="Webhook",
+            entry_node="process-webhook",
+            trigger_type="webhook",
+        )
+        runtime.register_entry_point(entry_spec)
+        await runtime.start()
+
+        try:
+            # Inject a fake running task into the stream
+            stream = runtime._streams["webhook"]
+
+            async def hang_forever():
+                await asyncio.get_event_loop().create_future()
+
+            fake_task = asyncio.ensure_future(hang_forever())
+            stream._execution_tasks["fake-exec"] = fake_task
+
+            result = await runtime.cancel_all_tasks_async()
+            assert result is True
+
+            # Let the CancelledError propagate
+            try:
+                await fake_task
+            except asyncio.CancelledError:
+                pass
+            assert fake_task.cancelled()
+
+            # Clean up
+            del stream._execution_tasks["fake-exec"]
+        finally:
+            await runtime.stop()
+
+    @pytest.mark.asyncio
+    async def test_cancel_all_tasks_async_cancels_multiple_tasks_across_streams(
+        self, sample_graph, sample_goal, temp_storage
+    ):
+        """Test that cancel_all_tasks_async cancels tasks across multiple streams."""
+        runtime = AgentRuntime(
+            graph=sample_graph,
+            goal=sample_goal,
+            storage_path=temp_storage,
+        )
+
+        # Register two entry points so we get two streams
+        runtime.register_entry_point(
+            EntryPointSpec(
+                id="stream-a",
+                name="Stream A",
+                entry_node="process-webhook",
+                trigger_type="webhook",
+            )
+        )
+        runtime.register_entry_point(
+            EntryPointSpec(
+                id="stream-b",
+                name="Stream B",
+                entry_node="process-webhook",
+                trigger_type="webhook",
+            )
+        )
+        await runtime.start()
+
+        try:
+
+            async def hang_forever():
+                await asyncio.get_event_loop().create_future()
+
+            stream_a = runtime._streams["stream-a"]
+            stream_b = runtime._streams["stream-b"]
+
+            # Two tasks in stream A, one task in stream B
+            task_a1 = asyncio.ensure_future(hang_forever())
+            task_a2 = asyncio.ensure_future(hang_forever())
+            task_b1 = asyncio.ensure_future(hang_forever())
+
+            stream_a._execution_tasks["exec-a1"] = task_a1
+            stream_a._execution_tasks["exec-a2"] = task_a2
+            stream_b._execution_tasks["exec-b1"] = task_b1
+
+            result = await runtime.cancel_all_tasks_async()
+            assert result is True
+
+            # Let CancelledErrors propagate
+            for task in [task_a1, task_a2, task_b1]:
+                try:
+                    await task
+                except asyncio.CancelledError:
+                    pass
+                assert task.cancelled()
+
+            # Clean up
+            del stream_a._execution_tasks["exec-a1"]
+            del stream_a._execution_tasks["exec-a2"]
+            del stream_b._execution_tasks["exec-b1"]
+        finally:
+            await runtime.stop()
+
+
 if __name__ == "__main__":
     pytest.main([__file__, "-v"])

core/framework/server/app.py

@@ -176,10 +176,7 @@ def create_app(model: str | None = None) -> web.Application:
     """
     app = web.Application(middlewares=[cors_middleware, error_middleware])
 
-    # Store manager on app for handlers
-    app["manager"] = SessionManager(model=model)
-
-    # Initialize credential store
+    # Initialize credential store (before SessionManager so it can be shared)
     from framework.credentials.store import CredentialStore
 
     try:
@@ -200,10 +197,13 @@ def create_app(model: str | None = None) -> web.Application:
             except Exception as exc:
                 logger.warning("Could not auto-persist HIVE_CREDENTIAL_KEY: %s", exc)
 
-        app["credential_store"] = CredentialStore.with_aden_sync()
+        credential_store = CredentialStore.with_aden_sync()
     except Exception:
         logger.debug("Encrypted credential store unavailable, using in-memory fallback")
-        app["credential_store"] = CredentialStore.for_testing({})
+        credential_store = CredentialStore.for_testing({})
+
+    app["credential_store"] = credential_store
+    app["manager"] = SessionManager(model=model, credential_store=credential_store)
 
     # Register shutdown hook
     app.on_shutdown.append(_on_shutdown)

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:
-                await sse.send_keepalive()
-            except (ConnectionResetError, ConnectionError):
+                try:
+                    await sse.send_keepalive()
+                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:
@@ -54,10 +59,11 @@ class SessionManager:
     (blocking I/O) then started on the event loop.
     """
 
-    def __init__(self, model: str | None = None) -> None:
+    def __init__(self, model: str | None = None, credential_store=None) -> None:
         self._sessions: dict[str, Session] = {}
         self._loading: set[str] = set()
         self._model = model
+        self._credential_store = credential_store
         self._lock = asyncio.Lock()
 
     # ------------------------------------------------------------------
@@ -113,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(
@@ -133,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
 
@@ -150,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(
@@ -169,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)
@@ -219,6 +226,7 @@ class SessionManager:
                     model=resolved_model,
                     interactive=False,
                     skip_credential_validation=True,
+                    credential_store=self._credential_store,
                 ),
             )
 
@@ -399,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,
@@ -409,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
@@ -772,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)
 
@@ -1643,46 +1643,20 @@ class AdenTUI(App):
         self.notify(f"Logs {mode}", severity="information", timeout=2)
 
     def action_pause_execution(self) -> None:
-        """Immediately pause execution by cancelling task (bound to Ctrl+Z)."""
+        """Immediately pause execution by cancelling all running tasks (bound to Ctrl+Z)."""
         if self.chat_repl is None or self.runtime is None:
             return
         try:
-            if not self.chat_repl._current_exec_id:
+            if self.runtime.cancel_all_tasks(self.chat_repl._agent_loop):
+                self.chat_repl._current_exec_id = None
                 self.notify(
-                    "No active execution to pause",
+                    "All executions stopped",
                     severity="information",
                     timeout=3,
                 )
-                return
-
-            task_cancelled = False
-            all_streams = []
-            active_reg = self.runtime.get_graph_registration(self.runtime.active_graph_id)
-            if active_reg:
-                all_streams.extend(active_reg.streams.values())
-            for gid in self.runtime.list_graphs():
-                if gid == self.runtime.active_graph_id:
-                    continue
-                reg = self.runtime.get_graph_registration(gid)
-                if reg:
-                    all_streams.extend(reg.streams.values())
-
-            for stream in all_streams:
-                exec_id = self.chat_repl._current_exec_id
-                task = stream._execution_tasks.get(exec_id)
-                if task and not task.done():
-                    task.cancel()
-                    task_cancelled = True
-                    self.notify(
-                        "Execution paused - state saved",
-                        severity="information",
-                        timeout=3,
-                    )
-                    break
-
-            if not task_cancelled:
+            else:
                 self.notify(
-                    "Execution already completed",
+                    "No active executions",
                     severity="information",
                     timeout=2,
                 )

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)
@@ -868,27 +868,17 @@ class ChatRepl(Vertical):
             self._write_history(f"[dim]{traceback.format_exc()}[/dim]")
 
     async def _cmd_pause(self) -> None:
-        """Immediately pause execution by cancelling task (same as Ctrl+Z)."""
-        # Check if there's a current execution
-        if not self._current_exec_id:
-            self._write_history("[bold yellow]No active execution to pause[/bold yellow]")
-            self._write_history("  Start an execution first, then use /pause during execution")
-            return
-
-        # Find and cancel the execution task - executor will catch and save state
-        task_cancelled = False
-        for stream in self.runtime._streams.values():
-            exec_id = self._current_exec_id
-            task = stream._execution_tasks.get(exec_id)
-            if task and not task.done():
-                task.cancel()
-                task_cancelled = True
-                self._write_history("[bold green]⏸ Execution paused - state saved[/bold green]")
-                self._write_history("  Resume later with: [bold]/resume[/bold]")
-                break
-
-        if not task_cancelled:
-            self._write_history("[bold yellow]Execution already completed[/bold yellow]")
+        """Immediately pause execution by cancelling all running tasks (same as Ctrl+Z)."""
+        future = asyncio.run_coroutine_threadsafe(
+            self.runtime.cancel_all_tasks_async(), self._agent_loop
+        )
+        result = await asyncio.wrap_future(future)
+        if result:
+            self._current_exec_id = None
+            self._write_history("[bold green]⏸ All executions stopped[/bold green]")
+            self._write_history("  Resume later with: [bold]/resume[/bold]")
+        else:
+            self._write_history("[bold yellow]No active executions[/bold yellow]")
 
     async def _cmd_coder(self, reason: str = "") -> None:
         """User-initiated escalation to Hive Coder."""
@@ -1112,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/CredentialsModal.tsx

@@ -400,17 +400,19 @@ export default function CredentialsModal({
                             <Pencil className="w-3 h-3" />
                           </button>
                         )}
-                        <button
-                          onClick={() => {
-                            setDeletingId(deletingId === row.id ? null : row.id);
-                            if (editingId) { setEditingId(null); setInputValue(""); }
-                          }}
-                          disabled={saving}
-                          className="p-1.5 rounded-md text-muted-foreground hover:text-destructive hover:bg-destructive/10 transition-colors"
-                          title="Delete credential"
-                        >
-                          <Trash2 className="w-3 h-3" />
-                        </button>
+                        {!(row.adenSupported && row.id !== "aden_api_key") && (
+                          <button
+                            onClick={() => {
+                              setDeletingId(deletingId === row.id ? null : row.id);
+                              if (editingId) { setEditingId(null); setInputValue(""); }
+                            }}
+                            disabled={saving}
+                            className="p-1.5 rounded-md text-muted-foreground hover:text-destructive hover:bg-destructive/10 transition-colors"
+                            title="Delete credential"
+                          >
+                            <Trash2 className="w-3 h-3" />
+                          </button>
+                        )}
                       </div>
                     ) : row.adenSupported && !adenPlatformConnected && row.id !== "aden_api_key" ? (
                       <span className="text-[11px] text-muted-foreground italic flex-shrink-0">

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 };
       }
@@ -512,13 +581,16 @@ export default function Workspace() {
       const { Framework: _fw, ...userFacing } = result;
       const all = Object.values(userFacing).flat();
       setDiscoverAgents(all);
-    }).catch(() => {});
+    }).catch(() => { });
   }, []);
 
   // --- 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);
-          isResumedSession = true;
+          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 {
+            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 {
-          liveSession = await sessionsApi.create(agentType);
+          // 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,43 +887,58 @@ 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[] = [];
-      try {
-        const { sessions: workerSessions } = await sessionsApi.workerSessions(session.session_id);
-        const resumable = workerSessions.find(
-          (s) => s.status === "active" || s.status === "paused",
-        );
-        isWorkerRunning = resumable?.status === "active";
+      // For cold-restore, use the old session ID. For live resume, use current session.
+      const historyId = coldRestoreId ?? (isResumedSession ? session.session_id : undefined);
 
-        if (isResumedSession && resumable) {
-          const { messages } = await sessionsApi.messages(session.session_id, resumable.session_id);
-          for (const m of messages as Message[]) {
-            restoredMsgs.push(backendMessageToChatMessage(m, agentType, displayName));
-          }
-        }
-      } catch {
-        // Worker session listing failed — not critical
-      }
-
-      // Restore queen conversation when rejoining an existing session
-      if (isResumedSession) {
+      // 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 { messages: queenMsgs } = await sessionsApi.queenMessages(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 (resumable) {
+            const { messages } = await sessionsApi.messages(historyId, resumable.session_id);
+            for (const m of messages as Message[]) {
+              restoredMsgs.push(backendMessageToChatMessage(m, agentType, displayName));
+            }
+          }
+        } catch {
+          // Worker session listing failed — not critical
+        }
+
+        try {
+          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,26 +1376,30 @@ 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]: {
                     ...cur,
                     awaitingInput: true,
                     isTyping: false,
                     isStreaming: false,
                     queenIsTyping: false,
                     queenBuilding: false,
-                  }};
-                }
-                return { ...prev, [agentType]: {
-                  ...cur,
-                  awaitingInput: true,
-                  isTyping: false,
-                  isStreaming: false,
-                  queenIsTyping: false,
-                  queenBuilding: false,
-                  pendingQuestion: prompt || null,
-                  pendingOptions: options,
-                  pendingQuestionSource: "queen",
-                }};
+                    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) {
@@ -1786,7 +2055,7 @@ export default function Workspace() {
       // Queue context for queen (fire-and-forget, no LLM response triggered)
       if (question && state?.sessionId && state?.ready) {
         const notification = `[Worker asked: "${question}" | User selected: "${answer}"]`;
-        executionApi.queenContext(state.sessionId, notification).catch(() => {});
+        executionApi.queenContext(state.sessionId, notification).catch(() => { });
       }
     }
   }, [activeWorker, activeSession, agentStates, handleWorkerReply, handleSend, updateAgentState, setSessionsByAgent]);
@@ -1817,9 +2086,9 @@ export default function Workspace() {
     // Unblock the waiting node with a dismiss signal
     const dismissMsg = `[User dismissed the question: "${question}"]`;
     if (source === "worker") {
-      executionApi.workerInput(state.sessionId, dismissMsg).catch(() => {});
+      executionApi.workerInput(state.sessionId, dismissMsg).catch(() => { });
     } else {
-      executionApi.chat(state.sessionId, dismissMsg).catch(() => {});
+      executionApi.chat(state.sessionId, dismissMsg).catch(() => { });
     }
   }, [agentStates, activeWorker, updateAgentState]);
 
@@ -1867,9 +2136,9 @@ export default function Workspace() {
         : Promise.resolve();
 
       pausePromise
-        .catch(() => {})                          // pause failure shouldn't block kill
+        .catch(() => { })                          // pause failure shouldn't block kill
         .then(() => sessionsApi.stop(state.sessionId!))
-        .catch(() => {});                         // fire-and-forget
+        .catch(() => { });                         // fire-and-forget
     }
 
     const allTypes = Object.keys(sessionsByAgent).filter(k => (sessionsByAgent[k] || []).length > 0);
@@ -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,9 +2340,11 @@ 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
+            <AgentGraph
               nodes={currentGraph.nodes}
               title={currentGraph.title}
               onNodeClick={(node) => setSelectedNode(prev => prev?.id === node.id ? null : node)}
@@ -2065,7 +2442,7 @@ export default function Workspace() {
                     <div className="flex items-start gap-3 min-w-0">
                       <div className="w-8 h-8 rounded-lg flex items-center justify-center flex-shrink-0 mt-0.5 bg-[hsl(210,40%,55%)]/15 border border-[hsl(210,40%,55%)]/25">
                         <span className="text-sm" style={{ color: "hsl(210,40%,55%)" }}>
-                          {{"webhook": "\u26A1", "timer": "\u23F1", "api": "\u2192", "event": "\u223F"}[selectedNode.triggerType || ""] || "\u26A1"}
+                          {{ "webhook": "\u26A1", "timer": "\u23F1", "api": "\u2192", "event": "\u223F" }[selectedNode.triggerType || ""] || "\u26A1"}
                         </span>
                       </div>
                       <div className="min-w-0">

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_config.py

@@ -0,0 +1,23 @@
+"""Tests for framework/config.py - Hive configuration loading."""
+
+import logging
+
+from framework.config import get_hive_config
+
+
+class TestGetHiveConfig:
+    """Test get_hive_config() logs warnings on parse errors."""
+
+    def test_logs_warning_on_malformed_json(self, tmp_path, monkeypatch, caplog):
+        """Test that malformed JSON logs warning and returns empty dict."""
+        config_file = tmp_path / "configuration.json"
+        config_file.write_text('{"broken": }')
+
+        monkeypatch.setattr("framework.config.HIVE_CONFIG_FILE", config_file)
+
+        with caplog.at_level(logging.WARNING):
+            result = get_hive_config()
+
+        assert result == {}
+        assert "Failed to load Hive config" in caplog.text
+        assert str(config_file) in caplog.text

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/bounty-program/README.md

@@ -0,0 +1,145 @@
+# Integration Bounty Program
+
+Earn XP, Discord roles, and money by testing, documenting, and building integrations for the Aden agent framework.
+
+## Why Contribute?
+
+**Your name in the product.** When you promote a tool to verified, your GitHub handle goes in the tool's README under `Contributed by`. Every agent that uses that integration carries your name — permanent credit in a production codebase.
+
+**Visible status.** Your Discord tier role is earned, not bought. When you answer a question in `#integrations-help` with a Core Contributor badge, people listen.
+
+**Weekly races.** Every Monday the bot posts the leaderboard. Top 3 get medal emojis. The best work gets highlighted in announcements.
+
+**The path to paid.** Core Contributor unlocks real money. It takes sustained quality work across testing, docs, and code — the scarcity makes it matter.
+
+## How It Works
+
+1. Pick a bounty from the [GitHub issues board](https://github.com/adenhq/hive/issues?q=is%3Aissue+is%3Aopen+label%3A%22bounty%3A*%22)
+2. Claim it by commenting on the issue
+3. Do the work and submit a PR (or test report)
+4. A maintainer reviews and merges
+5. You automatically get XP in Discord via Lurkr
+6. At certain levels, you unlock roles. At the top tier, you unlock paid bounties.
+
+## Tiers
+
+| Tier                        | How to Reach               | Rewards                                                       |
+| --------------------------- | -------------------------- | ------------------------------------------------------------- |
+| **Agent Builder**           | ~500 XP (Lurkr level 5)    | Discord role, bounty board access                             |
+| **Open Source Contributor** | ~2,000 XP (Lurkr level 15) | Discord role, name in CONTRIBUTORS.md and tool READMEs        |
+| **Core Contributor**        | Maintainer-approved        | Monetary payout per bounty, private `#bounty-payouts` channel |
+
+Lurkr auto-assigns the first two roles. Core Contributor requires sustained, quality contributions across multiple bounty types and a maintainer vouching for you.
+
+## Bounty Types
+
+| Type                  | Label             | Points | What You Do                                                                |
+| --------------------- | ----------------- | ------ | -------------------------------------------------------------------------- |
+| **Test a tool**       | `bounty:test`     | 20     | Test with a real API key, submit a report with logs                        |
+| **Write docs**        | `bounty:docs`     | 20     | Write a README following the [template](templates/tool-readme-template.md) |
+| **Code contribution** | `bounty:code`     | 30     | Add health checker, fix a bug, or improve an integration                   |
+| **New integration**   | `bounty:new-tool` | 75     | Build a complete integration from scratch                                  |
+
+Promoting a tool from unverified to verified is the final step — submit a PR moving it from `_register_unverified()` to `_register_verified()` after the [promotion checklist](promotion-checklist.md) is complete.
+
+## Quality Gates
+
+- **PRs** must be merged by a maintainer (not self-merged)
+- **Test reports** must follow the [test report template](templates/agent-test-report-template.md) with logs or session ID
+- **READMEs** must follow the [tool README template](templates/tool-readme-template.md)
+- **Claim before you start** — comment on the issue, wait for assignment
+- No self-review, no splitting one change across multiple PRs, no AI-only submissions without verification
+
+## Labels
+
+| Label               | Color              | Meaning                                 |
+| ------------------- | ------------------ | --------------------------------------- |
+| `bounty:test`       | `#1D76DB` (blue)   | Test a tool with a real API key         |
+| `bounty:docs`       | `#FBCA04` (yellow) | Write or improve documentation          |
+| `bounty:code`       | `#D93F0B` (orange) | Health checker, bug fix, or improvement |
+| `bounty:new-tool`   | `#6F42C1` (purple) | Build a new integration from scratch    |
+| `difficulty:easy`   | `#BFD4F2`          | Good first contribution                 |
+| `difficulty:medium` | `#D4C5F9`          | Requires some familiarity               |
+| `difficulty:hard`   | `#F9D0C4`          | Significant effort or expertise needed  |
+
+## Discord
+
+```
+#integrations-announcements  — Bounties, leaderboard, tool promotions (bot + admin only)
+#integrations-help           — Questions, testing coordination, showcases
+#bounty-payouts              — Dollar values and payout tracking (Core Contributors only)
+```
+
+## Leaderboard
+
+Weekly leaderboard auto-posts to `#integrations-announcements` every Monday. Top 3 get medal emojis. Check your rank anytime with `/rank` in Discord.
+
+XP comes from two sources: GitHub bounties (auto-pushed on PR merge) and Discord activity in `#integrations-help`.
+
+## Launch Plan: The 55-Tool Blitz
+
+A 2-week sprint to get all 55 unverified tools tested, documented, and health-checked.
+
+### Day 1: Post Everything
+
+- **41 `bounty:docs` issues** — tools missing READMEs, `difficulty:easy`, 20 pts each
+- **40 `bounty:code` issues** — tools missing health checkers, `difficulty:medium`, 30 pts each
+- **55 `bounty:test` issues** — one per unverified tool, `difficulty:medium`, 20 pts each
+
+### Week 1-2
+
+All bounty types open in parallel. Contributors self-select. Daily progress updates in `#integrations-announcements`. Day 14 wrap-up with final leaderboard and shoutouts.
+
+## Automation
+
+```
+PR merged with bounty:* label
+  → GitHub Action runs bounty-tracker.ts
+  → Calculates points from label
+  → Resolves GitHub → Discord ID via contributors.yml
+  → Pushes XP to Lurkr API
+  → Posts notification to #integrations-announcements
+```
+
+See the [Setup Guide](setup-guide.md) for full configuration (Lurkr, webhooks, secrets, labels).
+
+### Identity Linking
+
+Contributors link GitHub ↔ Discord by opening a [Link Discord Account](https://github.com/aden-hive/hive/issues/new?template=link-discord.yml) issue. A GitHub Action auto-adds them to `contributors.yml` and closes the issue.
+
+Without this link, bounties are still tracked but Lurkr can't push XP to your Discord account.
+
+### What Handles What
+
+| Concern                  | Handled By                 | How                                             |
+| ------------------------ | -------------------------- | ----------------------------------------------- |
+| Bounty point calculation | GitHub Actions             | `bounty-completed.yml` reads PR labels          |
+| XP push to Discord       | GitHub Actions → Lurkr API | `PATCH /levels/{guild}/users/{user}`            |
+| Discord engagement XP    | Lurkr bot                  | Native message XP (configurable per-channel)    |
+| Leaderboard              | Lurkr bot + GitHub Actions | `/leaderboard` in Discord + weekly webhook post |
+| Agent Builder role       | Lurkr bot                  | Auto-assigned at level 5                        |
+| OSS Contributor role     | Lurkr bot                  | Auto-assigned at level 15                       |
+| Core Contributor role    | Maintainer                 | Manual (involves money)                         |
+| Identity linking         | contributors.yml           | PR-based, reviewed by maintainers               |
+
+## Guides
+
+- **[Setup Guide](setup-guide.md)** — Admin setup from zero to running
+- **[Game Master Manual](game-master-manual.md)** — Maintainer operations
+- **[Contributor Guide](contributor-guide.md)** — Everything a contributor needs to start
+
+## Reference
+
+- [Promotion Checklist](promotion-checklist.md) — Criteria for unverified → verified
+- [Tool README Template](templates/tool-readme-template.md)
+- [Agent Test Report Template](templates/agent-test-report-template.md)
+- [Building Tools Guide](../tools/BUILDING_TOOLS.md)
+- [Lurkr API Docs](https://lurkr.gg/docs/api)
+
+### Automation Files
+
+- `.github/workflows/bounty-completed.yml` — PR merge → XP push + Discord notification
+- `.github/workflows/weekly-leaderboard.yml` — Monday leaderboard post
+- `scripts/bounty-tracker.ts` — Point calculation, Lurkr API, Discord formatting
+- `scripts/setup-bounty-labels.sh` — One-time label setup
+- `contributors.yml` — GitHub ↔ Discord identity mapping

docs/bounty-program/contributor-guide.md

@@ -0,0 +1,109 @@
+# Contributor Guide — Integration Bounty Program
+
+Earn XP, Discord roles, and eventually real money by testing and building integrations for the Aden agent framework.
+
+## Getting Started
+
+### 1. Link your GitHub and Discord
+
+Open a [Link Discord Account](https://github.com/aden-hive/hive/issues/new?template=link-discord.yml) issue — just paste your Discord ID and submit. A GitHub Action will automatically add you to `contributors.yml` and close the issue.
+
+To find your Discord ID: Discord Settings > Advanced > Enable **Developer Mode**, then right-click your name > **Copy User ID**.
+
+Without this link, Lurkr can't push XP to your Discord account.
+
+### 2. Pick your first bounty
+
+Browse [GitHub Issues with bounty labels](https://github.com/adenhq/hive/issues?q=is%3Aissue+is%3Aopen+label%3A%22bounty%3A*%22). Start with `bounty:docs` or `difficulty:easy`.
+
+Comment "I'd like to work on this" and wait for a maintainer to assign you.
+
+## Tiers
+
+| Tier | How to Reach | What You Get |
+|------|-------------|--------------|
+| **Agent Builder** | ~500 XP (Lurkr level 5) | Discord role, bounty board access |
+| **Open Source Contributor** | ~2,000 XP (Lurkr level 15) | Discord role, name in CONTRIBUTORS.md and tool READMEs |
+| **Core Contributor** | Maintainer nomination | Dollar values on bounties, paid per completion |
+
+XP comes from GitHub bounties (auto-pushed on PR merge) and Discord activity in `#integrations-help`.
+
+## Bounty Types
+
+### Test a Tool (20 pts)
+
+Test an unverified tool with a real API key and report what happens.
+
+1. Get an API key for the service (the bounty issue links to where)
+2. Run the tool functions with real data
+3. Fill out the [test report template](templates/agent-test-report-template.md)
+4. Submit as a comment on the issue or a file in a PR
+
+Report both successes and failures. Finding bugs is valuable.
+
+### Write Docs (20 pts)
+
+Write a README for a tool that's missing one.
+
+1. Read the tool's source code in `tools/src/aden_tools/tools/{tool_name}/`
+2. Read the credential spec in `tools/src/aden_tools/credentials/`
+3. Fill in the [tool README template](templates/tool-readme-template.md)
+4. Submit a PR adding `README.md` to the tool directory
+
+Function names and API URLs must match reality — no AI hallucinations.
+
+### Code Contribution (30 pts)
+
+Add a health checker, fix a bug, or improve an integration.
+
+**Health checker:**
+1. Find a lightweight API endpoint that validates the credential (GET, no writes)
+2. Add `health_check_endpoint` to the tool's CredentialSpec
+3. Implement a HealthChecker class in `tools/src/aden_tools/credentials/health_check.py`
+4. Register in `HEALTH_CHECKERS`, run `uv run pytest tools/tests/test_credential_registry.py`
+
+**Bug fix:**
+1. Find a bug during testing, file an issue
+2. Fix it in a PR with a test covering the bug
+
+### New Integration (75 pts)
+
+Build a complete integration from scratch.
+
+1. Follow the [BUILDING_TOOLS.md](../tools/BUILDING_TOOLS.md) guide
+2. Create: tool + credential spec + health checker + tests + README
+3. Register in `_register_unverified()` in `tools/__init__.py`
+4. Run `make check && make test`
+
+Expect multiple review rounds.
+
+## Rules
+
+1. **Claim before you start** — comment on the issue, wait for assignment
+2. **7-day window** — no PR within 7 days = bounty gets re-opened
+3. **Max 3 active claims** — don't hoard bounties
+4. **Quality matters** — PRs must pass CI and follow templates
+5. **No self-review** and no AI-only submissions without verification
+
+## FAQ
+
+**Q: Do I need an API key for every tool I test?**
+A: Yes. Most services have free tiers. The bounty issue links to where you get the key.
+
+**Q: How do I become a Core Contributor?**
+A: Contribute consistently across different bounty types for 4+ weeks. Maintainers will nominate you.
+
+**Q: What if I haven't linked my Discord yet?**
+A: You'll still get credit in GitHub, but no Lurkr XP or Discord roles. Add yourself to `contributors.yml`.
+
+## Quick Reference
+
+| What | Where |
+|------|-------|
+| Bounty board | [GitHub Issues](https://github.com/adenhq/hive/issues?q=is%3Aissue+is%3Aopen+label%3A%22bounty%3A*%22) |
+| README template | [templates/tool-readme-template.md](templates/tool-readme-template.md) |
+| Test report template | [templates/agent-test-report-template.md](templates/agent-test-report-template.md) |
+| Promotion checklist | [promotion-checklist.md](promotion-checklist.md) |
+| Building tools | [BUILDING_TOOLS.md](../tools/BUILDING_TOOLS.md) |
+| Discord | [Join](https://discord.com/invite/MXE49hrKDk) |
+| Your rank | `/rank` in Discord |

docs/bounty-program/game-master-manual.md

@@ -0,0 +1,107 @@
+# Game Master Manual
+
+Operations guide for maintainers running the Integration Bounty Program.
+
+## Your Role
+
+- Post bounty issues and set dollar values for Core Contributors
+- Assign claimed bounties to contributors
+- Review and merge bounty PRs (auto-triggers XP awards)
+- Manage the Core Contributor role
+- Monitor for gaming and low-quality submissions
+
+## Handling Bounty Claims
+
+When someone comments "I'd like to work on this":
+
+1. For `difficulty:easy`, assign immediately
+2. For `difficulty:medium`/`difficulty:hard`, check if they've done easier bounties first
+3. Assign via GitHub. If no PR within 7 days, unassign and re-open
+
+## Reviewing Bounty PRs
+
+1. Verify the PR matches the bounty issue
+2. Check quality gates (below)
+3. A **different maintainer** must approve than the one who created the bounty
+4. Apply the correct `bounty:*` label to the PR before merging
+5. Merge — the GitHub Action auto-awards XP and posts to Discord
+6. Close the linked bounty issue
+
+### Quality Gates
+
+**`bounty:docs`:**
+- [ ] Follows the [tool README template](templates/tool-readme-template.md)
+- [ ] Setup instructions are accurate (API key URL works)
+- [ ] Function names match the actual code
+- [ ] Not AI-generated without verification
+
+**`bounty:test`:**
+- [ ] Test report follows the [template](templates/agent-test-report-template.md)
+- [ ] Includes logs, session ID, or screenshots
+- [ ] Done with a real API key, not mocked
+- [ ] Reports failures honestly
+
+**`bounty:code`:**
+- [ ] CI passes (`uv run pytest tools/tests/test_credential_registry.py` for health checks)
+- [ ] Fix addresses root cause, not symptom
+- [ ] New test added for bug fixes
+
+**`bounty:new-tool`:**
+- [ ] Full implementation: tool + credential spec + tests + README
+- [ ] `make check && make test` passes
+- [ ] Registered in `_register_unverified()` (not verified)
+
+### Rejecting Submissions
+
+1. Leave specific, constructive feedback
+2. Request changes (don't close the PR)
+3. 7 days to address. No response → close PR, unassign bounty
+
+Never merge low-quality work just to be nice.
+
+## Core Contributor Promotion
+
+Core Contributor unlocks monetary rewards. The bar must be high.
+
+**Promote when:**
+- Active for **4+ weeks** with contributions across **3+ bounty types**
+- PRs are consistently clean
+- At least one maintainer vouches for them
+
+**How:** Discuss with maintainers → assign role in Discord → announce in `#integrations-announcements` → add to `#bounty-payouts`
+
+**Don't promote** if they only do easy bounties, have been active < 4 weeks, or show signs of gaming.
+
+If a Core Contributor is inactive 8+ weeks, reach out privately first, then remove the role if no response.
+
+## Dollar Values
+
+Post dollar values in `#bounty-payouts` (Core Contributors only):
+
+| Bounty Type | Dollar Range |
+|-------------|-------------|
+| `bounty:test` | $10–30 |
+| `bounty:docs` | $10–20 |
+| `bounty:code` | $20–50 |
+| `bounty:new-tool` | $50–150 |
+
+**Payout:** PR merged → verify quality → record in `#bounty-payouts` → process payment.
+
+XP is always awarded regardless of budget. Money is a bonus layer.
+
+## Anti-Gaming
+
+| Pattern | Response |
+|---------|----------|
+| Splitting one change across multiple PRs | Reject extras, warn |
+| AI-generated without verification | Reject, explain why |
+| Claiming many bounties, completing few | Unassign after 7 days |
+
+**First offense:** warning. **Second:** 2-week cooldown. **Third:** permanent removal.
+
+## Keeping It Fresh
+
+- Aim for 10+ unclaimed bounties at all times
+- Unassign stale claims (>7 days)
+- Shoutout exceptional contributions in announcements
+- Post milestones ("10th tool promoted to verified!")

docs/bounty-program/promotion-checklist.md

@@ -0,0 +1,99 @@
+# Integration Promotion Checklist
+
+Formal criteria for promoting a tool from **unverified** to **verified**. A tool must satisfy every required item before a maintainer moves it from `_register_unverified()` to `_register_verified()` in [tools/__init__.py](../tools/src/aden_tools/tools/__init__.py).
+
+## Checklist
+
+### Code Quality (Required)
+
+- [ ] **`register_tools` function** follows the standard signature pattern from [BUILDING_TOOLS.md](../tools/BUILDING_TOOLS.md)
+- [ ] **Error handling** — all tools return `{"error": ...}` dicts instead of raising exceptions
+- [ ] **Credential handling** — graceful fallback when credentials are missing, with actionable `"help"` message
+- [ ] **Input validation** — parameters are validated before making API calls
+- [ ] **No hardcoded secrets** — API keys come from credentials adapter or environment variables only
+
+### Credential Spec (Required)
+
+- [ ] **CredentialSpec exists** in `tools/src/aden_tools/credentials/{category}.py`
+- [ ] **`env_var`** is set and unique (no collisions with other specs)
+- [ ] **`tools`** list includes every tool function name registered by this module
+- [ ] **`help_url`** points to the page where users get their API key
+- [ ] **`description`** is a clear one-liner
+- [ ] **`credential_id`** and **`credential_key`** are set for credential store mapping
+- [ ] **Spec is merged** into `CREDENTIAL_SPECS` in `credentials/__init__.py`
+
+### Health Check (Required)
+
+- [ ] **`health_check_endpoint`** is set in the CredentialSpec
+- [ ] **HealthChecker class** is implemented in `tools/src/aden_tools/credentials/health_check.py`
+- [ ] **Checker is registered** in the `HEALTH_CHECKERS` dict
+- [ ] **Handles 200** (valid), **401** (invalid/expired), and **429** (rate limited but valid) responses
+- [ ] **Registry tests pass** — `uv run pytest tools/tests/test_credential_registry.py -v`
+
+### Documentation (Required)
+
+- [ ] **README.md** exists in the tool directory, following the [tool README template](templates/tool-readme-template.md)
+- [ ] **Setup instructions** — how to get and configure the API key
+- [ ] **Tool table** — lists all tool functions with descriptions
+- [ ] **Usage examples** — at least one example per tool function
+- [ ] **API reference link** — link to the service's API docs
+
+### Testing (Required)
+
+- [ ] **Unit tests exist** in `tools/tests/tools/test_{tool_name}.py`
+- [ ] **Tests mock external APIs** — no live API calls in unit tests
+- [ ] **Tests cover happy path** for each tool function
+- [ ] **Tests cover error cases** — missing credentials, invalid input, API errors
+- [ ] **CI passes** — `make check && make test`
+
+### Community Testing (Required)
+
+- [ ] **At least 1 community member** has tested with a real API key
+- [ ] **Agent test report submitted** following the [test report template](templates/agent-test-report-template.md)
+- [ ] **Tool works in a real agent workflow** (not just isolated function calls)
+- [ ] **No blocking issues** reported in the test report
+
+### Optional (Bonus)
+
+- [ ] Multiple community test reports from different testers
+- [ ] Rate limit documentation
+- [ ] Integration tests with sandboxed API accounts
+- [ ] Pagination support for list endpoints
+- [ ] Webhook support (if applicable to the service)
+
+## Promotion Process
+
+1. **Contributor opens a PR** that checks off all required items above
+2. **PR description** includes links to: the tool README, the health checker, the test report(s)
+3. **Maintainer reviews** the checklist — every required item must be verified
+4. **Maintainer moves** the tool registration from `_register_unverified()` to `_register_verified()` in `tools/__init__.py`
+5. **Maintainer adds the `bounty:code` label** to the PR — this triggers the GitHub Action to award XP via Lurkr and post a Discord notification
+6. **Announcement** auto-posted in `#integrations-announcements` on Discord
+
+## Current Status
+
+### Tools Ready for Promotion Testing
+
+The following 55 unverified tools have implementations, credential specs, and unit tests. They need documentation, health checks, and community testing to be promoted:
+
+<details>
+<summary>Full list of unverified tools</summary>
+
+airtable, apify, asana, attio, aws_s3, azure_sql, calendly, cloudinary, confluence,
+databricks, docker_hub, duckduckgo, gitlab, google_analytics, google_search_console,
+google_sheets, greenhouse, huggingface, jira, kafka, langfuse, linear, lusha,
+microsoft_graph, mongodb, n8n, notion, obsidian, pagerduty, pinecone, pipedrive,
+plaid, powerbi, pushover, quickbooks, reddit, redis, redshift, salesforce, sap,
+shopify, snowflake, supabase, terraform, tines, trello, twilio, twitter, vercel,
+yahoo_finance, youtube, youtube_transcript, zendesk, zoho_crm, zoom
+
+</details>
+
+### Gap Summary
+
+| Gap | Count | Bounty Type |
+|-----|-------|-------------|
+| Missing README | ~41 | `bounty:docs` |
+| Missing health_check_endpoint | ~40 | `bounty:code` |
+| Missing HealthChecker class | ~40 | `bounty:code` |
+| No community test report | 55 | `bounty:test` |

docs/bounty-program/setup-guide.md

@@ -0,0 +1,157 @@
+# Integration Bounty Program — Setup Guide
+
+Complete setup from zero to running. Estimated time: 30 minutes.
+
+## Prerequisites
+
+- Admin access to the GitHub repo
+- Admin access to the Discord server
+- `gh` CLI installed and authenticated
+
+## Step 1: Create GitHub Labels (2 min)
+
+```bash
+./scripts/setup-bounty-labels.sh
+```
+
+This creates 7 labels: 4 bounty types (`bounty:test`, `bounty:docs`, `bounty:code`, `bounty:new-tool`) and 3 difficulty levels (`difficulty:easy`, `difficulty:medium`, `difficulty:hard`).
+
+## Step 2: Create Discord Channels (3 min)
+
+```
+Category: Integrations
+  #integrations-announcements  (read-only for non-admins)
+  #integrations-help
+
+Category: Private
+  #bounty-payouts  (visible only to Core Contributor role)
+```
+
+**Permissions:**
+
+- `#integrations-announcements`: Everyone reads, only bots + admins post
+- `#bounty-payouts`: Core Contributor role only
+
+## Step 3: Create Discord Roles (2 min)
+
+Order matters — higher = more prestigious:
+
+| Role                    | Color            | Hoisted | Mentionable |
+| ----------------------- | ---------------- | ------- | ----------- |
+| Core Contributor        | Gold `#F1C40F`   | Yes     | Yes         |
+| Open Source Contributor | Purple `#9B59B6` | Yes     | No          |
+| Agent Builder           | Green `#2ECC71`  | Yes     | No          |
+
+## Step 4: Install and Configure Lurkr (10 min)
+
+### 4a. Invite Lurkr
+
+Go to https://lurkr.gg/ and invite the bot. Grant requested permissions.
+
+### 4b. Enable Leveling
+
+In Discord, run:
+
+```
+/config toggle option:Leveling System
+```
+
+### 4c. Configure XP and Cooldown (Dashboard)
+
+Lurkr configures XP range and cooldown through the web dashboard, not slash commands.
+
+1. Go to https://lurkr.gg/dashboard and select your server
+2. Open the **Leveling** category
+3. Set **XP range** to min 15, max 25
+4. Set **Cooldown** to 60 seconds
+
+### 4d. Configure Channel Settings
+
+Set `#integrations-help` as a leveling channel with a 2x multiplier, and exclude announcement/payout channels:
+
+1. In the Lurkr dashboard **Leveling** settings, add `#integrations-help` as a leveling channel
+2. Set a **channel multiplier** of 2x for `#integrations-help` using `/config set` (channel multiplier option)
+3. Do NOT add `#integrations-announcements` or `#bounty-payouts` as leveling channels
+
+### 4e. Configure Role Rewards
+
+Use `/config set` to add role rewards:
+
+1. Set `@Agent Builder` as a role reward at **level 5**
+2. Set `@Open Source Contributor` as a role reward at **level 15**
+
+Do NOT auto-assign Core Contributor — that's maintainer-only.
+
+### 4f. Generate Lurkr API Key
+
+1. Go to https://lurkr.gg/ and log in
+2. Profile > API settings > Create API Key
+3. Select **Read/Write** (not read-only)
+4. Copy the key
+
+## Step 5: Create Discord Webhook (2 min)
+
+1. Server Settings > Integrations > Webhooks > New Webhook
+2. Name: `Bounty Tracker`, channel: `#integrations-announcements`
+3. Copy the webhook URL
+
+## Step 6: Add GitHub Secrets (3 min)
+
+Repo Settings > Secrets and variables > Actions:
+
+| Secret                       | Value                      |
+| ---------------------------- | -------------------------- |
+| `DISCORD_BOUNTY_WEBHOOK_URL` | Webhook URL from Step 5    |
+| `LURKR_API_KEY`              | Lurkr API key from Step 4f |
+| `LURKR_GUILD_ID`             | Your Discord server ID\*   |
+
+\*Enable Developer Mode in Discord, right-click server name > Copy Server ID.
+
+## Step 7: Test the Pipeline (5 min)
+
+```bash
+GITHUB_TOKEN=$(gh auth token) \
+GITHUB_REPOSITORY_OWNER=aden-hive \
+GITHUB_REPOSITORY_NAME=hive \
+bun run scripts/bounty-tracker.ts leaderboard
+```
+
+Then create a test PR with `bounty:docs` label, merge it, verify the Discord notification appears.
+
+## Step 8: Seed the 55-Tool Blitz
+
+Post all bounties at once on launch day:
+
+**Documentation (41 issues):** `bounty:docs`, `difficulty:easy`, 20 pts
+**Health checks (40 issues):** `bounty:code`, `difficulty:medium`, 30 pts
+**Testing (55 issues):** `bounty:test`, `difficulty:medium`, 20 pts
+
+### Tools missing READMEs
+
+```
+azure_sql, cloudinary, confluence, databricks, docker_hub, duckduckgo,
+google_search_console, google_sheets, greenhouse, jira, kafka, lusha,
+mongodb, notion, obsidian, pagerduty, pinecone, pipedrive, plaid,
+pushover, quickbooks, redshift, sap, salesforce, shopify, snowflake,
+supabase, terraform, tines, trello, twilio, twitter, vercel,
+yahoo_finance, zoom, huggingface, langfuse, microsoft_graph, n8n,
+powerbi, redis
+```
+
+## Verification Checklist
+
+- [ ] Labels exist (`bounty:*` and `difficulty:*`)
+- [ ] Discord channels and roles created
+- [ ] Lurkr installed, leveling enabled, XP/cooldown configured in dashboard, role rewards set
+- [ ] All 3 GitHub secrets added
+- [ ] Both workflows enabled (`bounty-completed.yml`, `weekly-leaderboard.yml`)
+- [ ] Test PR + merge triggers Discord notification
+- [ ] `contributors.yml` exists at repo root
+
+## Troubleshooting
+
+**No Discord message:** Check `DISCORD_BOUNTY_WEBHOOK_URL` secret and Action logs.
+
+**Lurkr XP not awarded:** Confirm API key is Read/Write, contributor is in `contributors.yml`, check Action logs for `Lurkr XP push failed`.
+
+**Role not assigned:** Verify role rewards in the Lurkr dashboard or via `/config set`. Lurkr's role must be above the roles it assigns in server hierarchy.

docs/bounty-program/templates/agent-test-report-template.md

@@ -0,0 +1,90 @@
+# Agent Test Report: {tool_name}
+
+<!-- Submit this report as a comment on the bounty issue, or as a file in a PR. -->
+
+## Summary
+
+- **Tool tested:** `{tool_name}`
+- **Tester:** @{github_handle}
+- **Date:** {YYYY-MM-DD}
+- **Verdict:** Pass / Partial / Fail
+
+## Environment
+
+- **OS:** {e.g., macOS 15.2, Ubuntu 24.04}
+- **Python:** {e.g., 3.12.1}
+- **Hive version:** {commit hash or version}
+- **API tier:** {e.g., Free, Pro — relevant for rate limits}
+
+## Credential Setup
+
+- **Auth method:** {API key / OAuth / Bearer token}
+- **Health check result:** {Pass / Fail / No health checker available}
+- **Setup difficulty:** {Easy / Medium / Hard}
+- **Setup notes:** {Any friction, confusing docs, extra steps not documented}
+
+## Agent Configuration
+
+<!-- Describe the agent you built or used to test this tool. -->
+
+```
+Agent name: {name}
+Tools used: {tool_name}, {any other tools}
+Goal: {What the agent was supposed to accomplish}
+```
+
+## Test Results
+
+### Tool Functions Tested
+
+| Function | Input | Expected | Actual | Status |
+|----------|-------|----------|--------|--------|
+| `{function_name}` | {brief input description} | {expected behavior} | {what happened} | Pass/Fail |
+| `{function_name}` | {brief input description} | {expected behavior} | {what happened} | Pass/Fail |
+
+### Agent Workflow Test
+
+<!-- Did the agent successfully use this tool to accomplish a task? -->
+
+**Goal:** {What you asked the agent to do}
+
+**Result:** {What actually happened}
+
+**Session ID:** `{session_id if available}`
+
+### Edge Cases Found
+
+<!-- Document any unexpected behavior, errors, or limitations. -->
+
+| Edge Case | Behavior | Severity |
+|-----------|----------|----------|
+| {e.g., empty query} | {what happened} | Low/Medium/High |
+| {e.g., rate limit hit} | {what happened} | Low/Medium/High |
+
+## Issues Found
+
+<!-- List any bugs or problems. Link to new issues if you filed them. -->
+
+- [ ] {Issue description} — {filed as #XXXX / not yet filed}
+- [ ] {Issue description}
+
+## Recommendations
+
+<!-- Suggestions for the tool maintainer. -->
+
+- {e.g., "Error message for missing API key should include the help URL"}
+- {e.g., "Rate limit handling should retry with backoff"}
+- {e.g., "Ready for promotion after health checker is added"}
+
+## Evidence
+
+<!-- Attach or link to logs, screenshots, or recordings. At minimum, include the session ID or key log output. -->
+
+<details>
+<summary>Logs</summary>
+
+```
+{Paste relevant log output here}
+```
+
+</details>

docs/bounty-program/templates/tool-readme-template.md

@@ -0,0 +1,71 @@
+# {Tool Name} Tool
+
+<!-- One-liner: what this tool does and what it enables agents to do. -->
+
+{Brief description of what the tool does and its primary use case.}
+
+## Setup
+
+```bash
+# Required
+export {ENV_VAR}=your-api-key
+```
+
+**Get your key:**
+1. Go to {help_url}
+2. {Step to create/generate a key}
+3. {Step to copy the key}
+4. Set `{ENV_VAR}` environment variable
+
+Alternatively, configure via the credential store (`CredentialStoreAdapter`).
+
+<!-- If OAuth is supported, add: -->
+<!-- **OAuth:** This integration also supports OAuth2 via Aden. -->
+
+## Tools ({count})
+
+| Tool | Description |
+|------|-------------|
+| `{tool_function_name}` | {What it does} |
+| `{tool_function_name}` | {What it does} |
+
+## Usage
+
+### {Action name}
+
+```python
+result = {tool_function_name}(
+    param="value",
+)
+# Returns: {brief description of return value}
+```
+
+### {Action name}
+
+```python
+result = {tool_function_name}(
+    param="value",
+)
+# Returns: {brief description of return value}
+```
+
+## Scope
+
+<!-- What this integration covers in its current form. -->
+
+- {Capability 1}
+- {Capability 2}
+- {Capability 3}
+
+## Rate Limits
+
+<!-- Document known rate limits if applicable. Remove this section if not relevant. -->
+
+| Tier | Limit |
+|------|-------|
+| Free | {X requests/minute} |
+| Paid | {Y requests/minute} |
+
+## API Reference
+
+- [{Service} API Docs]({url})

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"
+  }
+}