chore: lint

* fix(antigravity): translate JSON Schema unions to Gemini nullable

Tool parameter schemas using JSON Schema 2020-12 unions like
"type": ["string", "null"] crash Gemini's function_declarations parser
with HTTP 400. Two existing tools trip this:

- core/framework/tasks/tools/colony_tools.py:52 (owner in _update_schema)
- core/framework/tasks/tools/session_tools.py:84-87 (same shape)

Add an adapter-level sanitizer that walks the schema tree and converts
union-with-null to OpenAPI 3.0 "nullable": true (which Gemini accepts).
Recurses into properties, items, additionalProperties, and the
anyOf/oneOf/allOf combinators. Source schemas remain valid JSON Schema
so OpenAI/Anthropic backends are unaffected.

* fix(antigravity): bump spoofed UA past Google's deprecation cutoff

Google has deprecated client version "Antigravity/1.18.3" — chats now
return "This version of Antigravity is no longer supported" instead of
a real model response.

Bump the spoofed User-Agent to "Antigravity/1.23.2" + "Electron/39.2.3"
(current desktop release) and add a comment that this needs periodic
re-bumping. A more durable fix (auto-detect from the installed app's
Info.plist) is a follow-up.

* fix(antigravity): fail loud on multi-type non-null Gemini schema unions

Per review on PR #7170: silently picking the first type from a union
like ["string", "integer", "null"] changes the contract for callers
that rely on the other types, and the failure is hard to diagnose at
the Gemini side. Replace the silent narrowing with a ValueError that
points the schema author at anyOf or a single type.

A repo scan finds no current Gemini-bound schemas using multi-type
non-null unions, so this branch is preventative for future authors.

* chore(antigravity): drop em dash from test docstring

.claude/settings.json

@@ -45,23 +45,27 @@
       "Bash(cat /home/timothy/aden/hive/.venv/lib/python3.11/site-packages/litellm-*.dist-info/METADATA)",
       "Bash(find \"/home/timothy/.hive/agents/queens/queen_brand_design/sessions/session_20260415_100751_d49f4c28/\" -type f -name \"*.json*\" -exec grep -l \"协日\" {} \\\\;)",
       "Bash(grep -v ':0$')",
-      "Bash(find /home/timothy/aden/hive/core/framework/skills/_default_skills -name \"SKILL.md\" -exec grep -l \"curl\\\\|jq\\\\|bash\\\\|sh\\\\|CLI\\\\|command\" {} \\\\;)",
-      "Bash(python3 -c \"import sys, json; [print\\(json.loads\\(line\\).get\\('data', {}\\).get\\('iteration'\\)\\) for line in sys.stdin]\")",
-      "Bash(grep -l \"shell\\\\|bash\\\\|exec\\\\|subprocess\" /home/timothy/aden/hive/tools/src/gcu/files/*.py)",
-      "Bash(python3 -c \"import aden_tools.file_ops; print\\(aden_tools.file_ops.__file__\\)\")",
-      "Bash(find / -path /proc -prune -o -name \"file_ops*\" -print)",
-      "Bash(grep -l \"sqlite\\\\|sqlite3\" /home/timothy/aden/hive/tools/src/aden_tools/tools/*/*.py)",
-      "Bash(grep -iv \"_tool$\")",
-      "Bash(grep -n \"add_post.*sessions\\\\|add_post.*colonies\\\\|add_get.*sessions\" /home/timothy/aden/hive/core/framework/server/*.py)",
-      "Bash(python -c 'import json; d=json.load\\(open\\('\\\\''__TRACKED_VAR__/.hive/colonies/__TRACKED_VAR__/worker.json'\\\\''\\)\\); print\\('\\\\''input_data:'\\\\'', d.get\\('\\\\''input_data'\\\\'', '\\\\''MISSING'\\\\''\\)\\)')",
-      "Bash(python -c 'import json; d=json.load\\(open\\('\\\\''__TRACKED_VAR__/.hive/colonies/__TRACKED_VAR__/worker.json'\\\\''\\)\\); print\\('\\\\''  __TRACKED_VAR__:'\\\\'', '\\\\''input_data='\\\\'', d.get\\('\\\\''input_data'\\\\'', '\\\\''MISSING'\\\\''\\)\\)')",
-      "Bash(python -c 'import json; d=json.load\\(open\\('\\\\''__TRACKED_VAR__/.hive/colonies/__TRACKED_VAR__/worker.json'\\\\''\\)\\); print\\('\\\\''  __TRACKED_VAR__: input_data ='\\\\'', d.get\\('\\\\''input_data'\\\\''\\)\\)')",
-      "Bash(kill 2466637 2466632)"
+      "Bash(curl -s -m 2 http://127.0.0.1:4002/sse -o /dev/null -w 'status=%{http_code} time=%{time_total}s\\\\n')",
+      "mcp__gcu-tools__browser_status",
+      "mcp__gcu-tools__browser_navigate",
+      "mcp__gcu-tools__browser_evaluate",
+      "mcp__gcu-tools__browser_screenshot",
+      "mcp__gcu-tools__browser_open",
+      "mcp__gcu-tools__browser_click_coordinate",
+      "mcp__gcu-tools__browser_get_rect",
+      "mcp__gcu-tools__browser_type_focused",
+      "mcp__gcu-tools__browser_wait",
+      "Bash(python3 -c ' *)",
+      "Bash(python3 scripts/debug_queen_prompt.py independent)",
+      "Bash(curl -s --max-time 2 http://127.0.0.1:9230/status)",
+      "Bash(python3 -c \"import json, sys; print\\(json.loads\\(sys.stdin.read\\(\\)\\)['data']['content']\\)\")",
+      "Bash(python3 -c \"import json; json.load\\(open\\('/home/timothy/aden/hive/tools/browser-extension/manifest.json'\\)\\)\")"
     ],
     "additionalDirectories": [
       "/home/timothy/.hive/skills/writing-hive-skills",
       "/tmp",
-      "/home/timothy/.hive/skills"
+      "/home/timothy/.hive/skills",
+      "/home/timothy/aden/hive/core/frontend/src/components"
     ]
   },
   "hooks": {

.claude/skills/browser-edge-cases/SKILL.md

@@ -64,7 +64,7 @@ snapshot = await browser_snapshot(tab_id)
 |---------|--------------|-------|
 | Scroll doesn't move | Nested scroll container | Look for `overflow: scroll` divs |
 | Click no effect | Element covered | Check `getBoundingClientRect` vs viewport |
-| Type clears | Autocomplete/React | Check for event listeners on input |
+| Type clears | Autocomplete/React | Check for event listeners on input; try `browser_type_focused` |
 | Snapshot hangs | Huge DOM | Check node count in snapshot |
 | Snapshot stale | SPA hydration | Wait after navigation |
 
@@ -229,7 +229,7 @@ function queryShadow(selector) {
 |-------|-------------|----------|
 | Scroll not working | Find scrollable container | Mouse wheel at container center |
 | Click no effect | JavaScript click() | CDP mouse events |
-| Type clears | Add delay_ms | Use execCommand |
+| Type clears | Add delay_ms | Use `browser_type_focused` (Input.insertText) |
 | Snapshot hangs | Add timeout_s | DOM snapshot fallback |
 | Stale content | Wait for selector | Increase wait_until timeout |
 | Shadow DOM | Pierce selector | JavaScript traversal |

.claude/skills/browser-edge-cases/registry.md

@@ -214,7 +214,7 @@ Curated list of known browser automation edge cases with symptoms, causes, and f
 | **Symptom** | `browser_open()` returns `"No group with id: XXXXXXX"` even though `browser_status` shows `running: true` |
 | **Root Cause** | In-memory `_contexts` dict has a stale `groupId` from a Chrome tab group that was closed outside the tool (e.g. user closed the tab group) |
 | **Detection** | `browser_status` returns `running: true` but `browser_open` fails with "No group with id" |
-| **Fix** | Call `browser_stop()` to clear stale context from `_contexts`, then `browser_start()` again |
+| **Fix** | Call `browser_stop()` to clear stale context from `_contexts`, then `browser_open(url)` to lazy-create a fresh one |
 | **Code** | `tools/lifecycle.py:144-160` - `already_running` check uses cached dict without validating against Chrome |
 | **Verified** | 2026-04-03 ✓ |
 

.cursorrules

@@ -1,18 +0,0 @@
-This project uses ruff for Python linting and formatting.
-
-Rules:
-- Line length: 100 characters
-- Python target: 3.11+
-- Use double quotes for strings
-- Sort imports with isort (ruff I rules): stdlib, third-party, first-party (framework), local
-- Combine as-imports
-- Use type hints on all function signatures
-- Use `from __future__ import annotations` for modern type syntax
-- Raise exceptions with `from` in except blocks (B904)
-- No unused imports (F401), no unused variables (F841)
-- Prefer list/dict/set comprehensions over map/filter (C4)
-
-Run `make lint` to auto-fix, `make check` to verify without modifying files.
-Run `make format` to apply ruff formatting.
-
-The ruff config lives in core/pyproject.toml under [tool.ruff].

.dockerignore

@@ -1,35 +0,0 @@
-# Git
-.git/
-.gitignore
-
-# Documentation
-*.md
-docs/
-LICENSE
-
-# IDE
-.idea/
-.vscode/
-
-# Dependencies (rebuilt in container)
-node_modules/
-
-# Build artifacts
-dist/
-build/
-coverage/
-
-# Environment files
-.env*
-config.yaml
-
-# Logs
-*.log
-logs/
-
-# OS
-.DS_Store
-Thumbs.db
-
-# GitHub
-.github/

.editorconfig

@@ -22,3 +22,6 @@ indent_size = 2
 
 [Makefile]
 indent_style = tab
+
+[*.{sh,ps1}]
+end_of_line = lf

.gitattributes

@@ -16,7 +16,6 @@
 
 # Shell scripts (must use LF)
 *.sh text eol=lf
-quickstart.sh text eol=lf
 
 # PowerShell scripts (Windows-friendly)
 *.ps1 text eol=lf
@@ -122,3 +121,8 @@ CODE_OF_CONDUCT* text
 *.db binary
 *.sqlite binary
 *.sqlite3 binary
+
+# Lockfiles — mark generated so GitHub collapses them in PR diffs
+*.lock            linguist-generated=true -diff
+package-lock.json linguist-generated=true -diff
+uv.lock           linguist-generated=true -diff

.github/workflows/ci.yml

@@ -84,11 +84,23 @@ jobs:
         with:
           enable-cache: true
 
-      - name: Install dependencies and run tests
+      - name: Install dependencies
         working-directory: tools
-        run: |
-          uv sync --extra dev
-          uv run pytest tests/ -v
+        run: uv sync --extra dev
+
+      - name: Install Playwright Chromium (Linux)
+        if: runner.os == 'Linux'
+        working-directory: tools
+        run: uv run playwright install --with-deps chromium
+
+      - name: Install Playwright Chromium (Windows)
+        if: runner.os == 'Windows'
+        working-directory: tools
+        run: uv run playwright install chromium
+
+      - name: Run tests
+        working-directory: tools
+        run: uv run pytest tests/ -v
 
   validate:
     name: Validate Agent Exports

.mcp.json

@@ -1,3 +0,0 @@
-{
-  "mcpServers": {}
-}

CONTRIBUTING.md

@@ -407,7 +407,7 @@ Aden Hive supports **100+ LLM providers** via LiteLLM, giving users maximum flex
 | **Anthropic** | Claude 3.5 Sonnet, Haiku, Opus | Default provider, best for reasoning |
 | **OpenAI** | GPT-4, GPT-4 Turbo, GPT-4o | Function calling, vision |
 | **OpenRouter** | Any OpenRouter catalog model | Uses `OPENROUTER_API_KEY` and `https://openrouter.ai/api/v1` |
-| **Hive LLM** | `queen`, `kimi-2.5`, `GLM-5` | Uses `HIVE_API_KEY` and the Hive-managed endpoint |
+| **Hive LLM** | `queen`, `kimi-k2.5`, `GLM-5` | Uses `HIVE_API_KEY` and the Hive-managed endpoint |
 | **Google** | Gemini 1.5 Pro, Flash | Long context windows |
 | **DeepSeek** | DeepSeek V3 | Cost-effective, strong reasoning |
 | **Mistral** | Mistral Large, Medium, Small | Open weights, EU hosting |
@@ -435,7 +435,7 @@ DEFAULT_MODEL = "claude-haiku-4-5-20251001"
 
 **Provider-Specific Notes**
 - **OpenRouter**: store `provider` as `openrouter`, use the raw OpenRouter model ID in `model` (for example `x-ai/grok-4.20-beta`), and use `OPENROUTER_API_KEY`
-- **Hive LLM**: store `provider` as `hive`, use Hive model names such as `queen`, `kimi-2.5`, or `GLM-5`, and use `HIVE_API_KEY`
+- **Hive LLM**: store `provider` as `hive`, use Hive model names such as `queen`, `kimi-k2.5`, or `GLM-5`, and use `HIVE_API_KEY`
 
 **For Development**
 - Use cheaper/faster models (Haiku, GPT-4o-mini)

append_ledger.py

@@ -1,11 +0,0 @@
-import json
-
-with open('/home/timothy/aden/hive/x_rapid_ledger.json', 'r') as f:
-    data = json.load(f)
-
-data['replies'].append({
-    'original_preview': 'Alright, I give in. Here’s my picture with the boss, courtesy of @johnkrausphotos. Oh, and hook ‘em!'
-})
-
-with open('/home/timothy/aden/hive/x_rapid_ledger.json', 'w') as f:
-    json.dump(data, f, indent=2)

check_ledger.py

@@ -1,11 +0,0 @@
-import json, sys
-
-with open('/home/timothy/aden/hive/x_rapid_ledger.json', 'r') as f:
-    ledger = json.load(f)
-
-text = sys.argv[1]
-for r in ledger['replies']:
-    if r.get('original_preview') == text:
-        print("YES")
-        sys.exit(0)
-print("NO")

core/MCP_BUILDER_TOOLS_GUIDE.md

@@ -72,17 +72,16 @@ Register an MCP server as a tool source for your agent.
     "cwd": "../tools",
     "description": "Aden tools..."
   },
-  "tools_discovered": 6,
+  "tools_discovered": 5,
   "tools": [
     "web_search",
     "web_scrape",
     "file_read",
     "file_write",
-    "pdf_read",
-    "example_tool"
+    "pdf_read"
   ],
   "total_mcp_servers": 1,
-  "note": "MCP server 'tools' registered with 6 tools. These tools can now be used in event_loop nodes."
+  "note": "MCP server 'tools' registered with 5 tools. These tools can now be used in event_loop nodes."
 }
 ```
 

core/MCP_SERVER_GUIDE.md

@@ -1,6 +1,6 @@
 # MCP Server Guide - Agent Building Tools
 
-> **Note:** The standalone `agent-builder` MCP server (`framework.mcp.agent_builder_server`) has been replaced. Agent building is now done via the `coder-tools` server's `initialize_and_build_agent` tool, with underlying logic in `tools/coder_tools_server.py`.
+> **Note:** This document is stale. The previous `coder-tools` MCP server has been replaced by `files-tools` (`tools/files_server.py`), which only exposes file I/O (`read_file`, `write_file`, `edit_file`, `hashline_edit`, `search_files`). The agent-building, shell, and snapshot tools that used to live here have been removed.
 
 This guide covers the MCP tools available for building goal-driven agents.
 
@@ -20,9 +20,9 @@ Add to your MCP client configuration (e.g., Claude Desktop):
 ```json
 {
   "mcpServers": {
-    "coder-tools": {
+    "files-tools": {
       "command": "uv",
-      "args": ["run", "coder_tools_server.py", "--stdio"],
+      "args": ["run", "files_server.py", "--stdio"],
       "cwd": "/path/to/hive/tools"
     }
   }

core/README.md

@@ -19,8 +19,6 @@ uv pip install -e .
 
 ## Agent Building
 
-Agent scaffolding is handled by the `coder-tools` MCP server (in `tools/coder_tools_server.py`), which provides the `initialize_and_build_agent` tool and related utilities. The package generation logic lives directly in `tools/coder_tools_server.py`.
-
 See the [Getting Started Guide](../docs/getting-started.md) for building agents.
 
 ## Quick Start

core/framework/agent_loop/conversation.py

@@ -48,6 +48,24 @@ class Message:
     is_skill_content: bool = False
     # Logical worker run identifier for shared-session persistence
     run_id: str | None = None
+    # True when this is a framework-injected continuation hint (continue-nudge
+    # on stream stall). Stored as a user message for API compatibility, but
+    # the UI should render it as a compact system notice, not user speech.
+    is_system_nudge: bool = False
+    # True when this message is a partial/truncated assistant turn reconstructed
+    # from a crashed or watchdog-cancelled stream. Signals that the original
+    # turn never finished — the model may or may not choose to redo it.
+    truncated: bool = False
+    # When non-None, identifies the parent session id this message was
+    # carried over from — used by fork_session_into_colony on the single
+    # compacted-summary message it writes when a colony is born from a
+    # queen DM. Presence of the field IS the "inherited" signal.
+    inherited_from: str | None = None
+    # True when this user message was synthesized from one or more
+    # fired triggers (timer/webhook), not typed by a human. The LLM still
+    # sees the message as a regular user turn; the UI uses this flag to
+    # render it as a trigger banner instead of a speech bubble.
+    is_trigger: bool = False
 
     def to_llm_dict(self) -> dict[str, Any]:
         """Convert to OpenAI-format message dict."""
@@ -109,6 +127,14 @@ class Message:
             d["image_content"] = self.image_content
         if self.run_id is not None:
             d["run_id"] = self.run_id
+        if self.is_system_nudge:
+            d["is_system_nudge"] = self.is_system_nudge
+        if self.truncated:
+            d["truncated"] = self.truncated
+        if self.inherited_from is not None:
+            d["inherited_from"] = self.inherited_from
+        if self.is_trigger:
+            d["is_trigger"] = self.is_trigger
         return d
 
     @classmethod
@@ -126,6 +152,10 @@ class Message:
             is_client_input=data.get("is_client_input", False),
             image_content=data.get("image_content"),
             run_id=data.get("run_id"),
+            is_system_nudge=data.get("is_system_nudge", False),
+            truncated=data.get("truncated", False),
+            inherited_from=data.get("inherited_from"),
+            is_trigger=data.get("is_trigger", False),
         )
 
 
@@ -317,6 +347,14 @@ class ConversationStore(Protocol):
 
     async def delete_parts_before(self, seq: int, run_id: str | None = None) -> None: ...
 
+    async def write_partial(self, seq: int, data: dict[str, Any]) -> None: ...
+
+    async def read_partial(self, seq: int) -> dict[str, Any] | None: ...
+
+    async def read_all_partials(self) -> list[dict[str, Any]]: ...
+
+    async def clear_partial(self, seq: int) -> None: ...
+
     async def close(self) -> None: ...
 
     async def destroy(self) -> None: ...
@@ -389,9 +427,20 @@ class NodeConversation:
         store: ConversationStore | None = None,
         run_id: str | None = None,
         compaction_buffer_tokens: int | None = None,
+        compaction_buffer_ratio: float | None = None,
         compaction_warning_buffer_tokens: int | None = None,
     ) -> None:
         self._system_prompt = system_prompt
+        # Optional split: when a caller updates the prompt with a
+        # ``dynamic_suffix`` argument, we remember the static prefix and
+        # suffix separately so the LLM wrapper can emit them as two
+        # Anthropic system content blocks with a cache breakpoint between
+        # them. ``_system_prompt`` stays as the concatenated form used for
+        # persistence and for the legacy single-block LLM path.
+        # On restore, these default to the concat/empty pair — the next
+        # AgentLoop iteration's dynamic-prompt refresh step repopulates.
+        self._system_prompt_static: str = system_prompt
+        self._system_prompt_dynamic_suffix: str = ""
         self._max_context_tokens = max_context_tokens
         self._compaction_threshold = compaction_threshold
         # Buffer-based compaction trigger (Gap 7). When set, takes
@@ -401,6 +450,11 @@ class NodeConversation:
         # limit. If left as None the legacy threshold-based rule is
         # used, keeping old call sites behaving identically.
         self._compaction_buffer_tokens = compaction_buffer_tokens
+        # Ratio component of the hybrid buffer. Combines additively with
+        # _compaction_buffer_tokens so callers can express "reserve N tokens
+        # plus M% of the window" — the absolute floor matters on tiny
+        # windows, the ratio matters on large ones.
+        self._compaction_buffer_ratio = compaction_buffer_ratio
         self._compaction_warning_buffer_tokens = compaction_warning_buffer_tokens
         self._output_keys = output_keys
         self._store = store
@@ -415,15 +469,56 @@ class NodeConversation:
 
     @property
     def system_prompt(self) -> str:
+        """Full concatenated system prompt (static + dynamic suffix, if any).
+
+        This is the canonical form used for persistence and for the legacy
+        single-block LLM path. Split-prompt callers should read
+        ``system_prompt_static`` and ``system_prompt_dynamic_suffix`` instead.
+        """
         return self._system_prompt
 
-    def update_system_prompt(self, new_prompt: str) -> None:
+    @property
+    def system_prompt_static(self) -> str:
+        """Static prefix of the system prompt (cache-stable).
+
+        Equals ``system_prompt`` when no split is in use. When the AgentLoop
+        calls ``update_system_prompt(static, dynamic_suffix=...)``, this is
+        the piece sent as the cache-controlled first block.
+        """
+        return self._system_prompt_static
+
+    @property
+    def system_prompt_dynamic_suffix(self) -> str:
+        """Dynamic tail of the system prompt (not cached).
+
+        Empty unless the consumer splits its prompt. The LLM wrapper uses a
+        non-empty suffix to emit a two-block system content list with a
+        cache breakpoint between the static prefix and this tail.
+        """
+        return self._system_prompt_dynamic_suffix
+
+    def update_system_prompt(self, new_prompt: str, dynamic_suffix: str | None = None) -> None:
         """Update the system prompt.
 
         Used in continuous conversation mode at phase transitions to swap
         Layer 3 (focus) while preserving the conversation history.
+
+        When ``dynamic_suffix`` is provided, ``new_prompt`` is interpreted as
+        the STATIC prefix and ``dynamic_suffix`` as the per-turn tail; they
+        travel to the LLM as two separate cache-controlled blocks but are
+        persisted as a single concatenated string for backward-compat
+        restore. ``new_prompt`` alone (suffix left None) keeps the legacy
+        single-string behavior.
         """
-        self._system_prompt = new_prompt
+        if dynamic_suffix is None:
+            # Legacy single-string path — static == full, no suffix split.
+            self._system_prompt = new_prompt
+            self._system_prompt_static = new_prompt
+            self._system_prompt_dynamic_suffix = ""
+        else:
+            self._system_prompt_static = new_prompt
+            self._system_prompt_dynamic_suffix = dynamic_suffix
+            self._system_prompt = f"{new_prompt}\n\n{dynamic_suffix}" if dynamic_suffix else new_prompt
         self._meta_persisted = False  # re-persist with new prompt
 
     def set_current_phase(self, phase_id: str) -> None:
@@ -462,6 +557,8 @@ class NodeConversation:
         is_transition_marker: bool = False,
         is_client_input: bool = False,
         image_content: list[dict[str, Any]] | None = None,
+        is_system_nudge: bool = False,
+        is_trigger: bool = False,
     ) -> Message:
         msg = Message(
             seq=self._next_seq,
@@ -472,6 +569,8 @@ class NodeConversation:
             is_transition_marker=is_transition_marker,
             is_client_input=is_client_input,
             image_content=image_content,
+            is_system_nudge=is_system_nudge,
+            is_trigger=is_trigger,
         )
         self._messages.append(msg)
         self._next_seq += 1
@@ -485,6 +584,8 @@ class NodeConversation:
         self,
         content: str,
         tool_calls: list[dict[str, Any]] | None = None,
+        *,
+        truncated: bool = False,
     ) -> Message:
         msg = Message(
             seq=self._next_seq,
@@ -493,6 +594,7 @@ class NodeConversation:
             tool_calls=tool_calls,
             phase_id=self._current_phase,
             run_id=self._run_id,
+            truncated=truncated,
         )
         self._messages.append(msg)
         self._next_seq += 1
@@ -548,6 +650,59 @@ class NodeConversation:
 
     # --- Query -------------------------------------------------------------
 
+    def find_completed_tool_call(
+        self,
+        name: str,
+        tool_input: dict[str, Any],
+        within_last_turns: int = 3,
+    ) -> Message | None:
+        """Return the most recent assistant message that issued a tool call
+        with the same (name + canonical-json args) AND received a non-error
+        tool result, within the last ``within_last_turns`` assistant turns.
+
+        Used by the replay detector to flag when the model is about to redo
+        a successful call — we prepend a steer onto the upcoming result but
+        still execute, so tools like browser_screenshot that are legitimately
+        repeated are not silently skipped.
+        """
+        try:
+            target_canonical = json.dumps(tool_input, sort_keys=True, default=str)
+        except (TypeError, ValueError):
+            target_canonical = str(tool_input)
+
+        # Walk backwards over recent assistant messages
+        assistant_turns_seen = 0
+        for idx in range(len(self._messages) - 1, -1, -1):
+            m = self._messages[idx]
+            if m.role != "assistant":
+                continue
+            assistant_turns_seen += 1
+            if assistant_turns_seen > within_last_turns:
+                break
+            if not m.tool_calls:
+                continue
+            for tc in m.tool_calls:
+                func = tc.get("function", {}) if isinstance(tc, dict) else {}
+                tc_name = func.get("name")
+                if tc_name != name:
+                    continue
+                args_str = func.get("arguments", "")
+                try:
+                    parsed = json.loads(args_str) if isinstance(args_str, str) else args_str
+                    canonical = json.dumps(parsed, sort_keys=True, default=str)
+                except (TypeError, ValueError):
+                    canonical = str(args_str)
+                if canonical != target_canonical:
+                    continue
+                # Found a match — now verify its result was not an error.
+                tc_id = tc.get("id")
+                for later in self._messages[idx + 1 :]:
+                    if later.role == "tool" and later.tool_use_id == tc_id:
+                        if not later.is_error:
+                            return m
+                        break
+        return None
+
     def to_llm_messages(self) -> list[dict[str, Any]]:
         """Return messages as OpenAI-format dicts (system prompt excluded).
 
@@ -749,19 +904,30 @@ class NodeConversation:
         """True when the conversation should be compacted before the
         next LLM call.
 
-        Buffer-based rule (Gap 7): trigger when the current estimate
-        plus the configured buffer would exceed the hard context limit.
-        Prevents compaction from firing only AFTER we're already over
-        the wire and forced into a reactive binary-split pass.
+        Hybrid buffer rule: the headroom reserved before compaction fires
+        is the SUM of an absolute fixed component and a ratio of the hard
+        context limit:
 
-        When no buffer is configured, falls back to the multiplicative
-        threshold the old callers were built around.
+            effective_buffer = compaction_buffer_tokens
+                             + compaction_buffer_ratio * max_context_tokens
+
+        The fixed component gives a floor on tiny windows; the ratio
+        keeps the trigger meaningful on large windows where any constant
+        buffer becomes a rounding error (an 8k buffer is 75% on a 32k
+        window but 96% on a 200k window). Compaction fires when the
+        current estimate would consume more than (limit - effective_buffer).
+
+        When neither component is configured, falls back to the legacy
+        multiplicative threshold so old callers keep behaving identically.
         """
         if self._max_context_tokens <= 0:
             return False
-        if self._compaction_buffer_tokens is not None:
-            budget = self._max_context_tokens - self._compaction_buffer_tokens
-            return self.estimate_tokens() >= max(0, budget)
+        fixed = self._compaction_buffer_tokens
+        ratio = self._compaction_buffer_ratio
+        if fixed is not None or ratio is not None:
+            effective_buffer = (fixed or 0) + (ratio or 0.0) * self._max_context_tokens
+            budget = self._max_context_tokens - effective_buffer
+            return self.estimate_tokens() >= max(0.0, budget)
         return self.estimate_tokens() >= self._max_context_tokens * self._compaction_threshold
 
     def compaction_warning(self) -> bool:
@@ -1365,6 +1531,45 @@ class NodeConversation:
             await self._persist_meta()
         await self._store.write_part(message.seq, message.to_storage_dict())
         await self._write_next_seq()
+        # Any partial checkpoint for this seq is now superseded by the real
+        # part — clear it so a future restore doesn't resurrect stale text.
+        try:
+            await self._store.clear_partial(message.seq)
+        except AttributeError:
+            # Older stores may not implement partials; ignore.
+            pass
+
+    async def checkpoint_partial_assistant(
+        self,
+        accumulated_text: str,
+        tool_calls: list[dict[str, Any]] | None = None,
+    ) -> None:
+        """Write an in-flight assistant turn's state to disk under the next seq.
+
+        Called from the stream event loop. Safe to call repeatedly — each call
+        overwrites the prior checkpoint. Persisted via ``write_partial`` so it
+        does NOT appear in ``read_parts()`` and cannot be double-loaded. Cleared
+        automatically when ``add_assistant_message`` for this seq lands.
+        """
+        if self._store is None:
+            return
+        if not self._meta_persisted:
+            await self._persist_meta()
+        payload: dict[str, Any] = {
+            "seq": self._next_seq,
+            "role": "assistant",
+            "content": accumulated_text,
+            "phase_id": self._current_phase,
+            "run_id": self._run_id,
+            "truncated": True,
+        }
+        if tool_calls:
+            payload["tool_calls"] = tool_calls
+        try:
+            await self._store.write_partial(self._next_seq, payload)
+        except AttributeError:
+            # Older stores may not implement partials; ignore.
+            pass
 
     async def _persist_meta(self) -> None:
         """Lazily write conversation metadata to the store (called once).
@@ -1379,6 +1584,7 @@ class NodeConversation:
             "max_context_tokens": self._max_context_tokens,
             "compaction_threshold": self._compaction_threshold,
             "compaction_buffer_tokens": self._compaction_buffer_tokens,
+            "compaction_buffer_ratio": self._compaction_buffer_ratio,
             "compaction_warning_buffer_tokens": (self._compaction_warning_buffer_tokens),
             "output_keys": self._output_keys,
         }
@@ -1428,6 +1634,7 @@ class NodeConversation:
             store=store,
             run_id=run_id,
             compaction_buffer_tokens=meta.get("compaction_buffer_tokens"),
+            compaction_buffer_ratio=meta.get("compaction_buffer_ratio"),
             compaction_warning_buffer_tokens=meta.get("compaction_warning_buffer_tokens"),
         )
         conv._meta_persisted = True
@@ -1461,4 +1668,45 @@ class NodeConversation:
         elif conv._messages:
             conv._next_seq = conv._messages[-1].seq + 1
 
+        # Surface any leftover partial checkpoints as truncated messages so
+        # the next turn sees what the interrupted stream was in the middle
+        # of producing. Only partials whose seq is >= next_seq are meaningful;
+        # anything lower was already superseded by a real part.
+        try:
+            partials = await store.read_all_partials()
+        except AttributeError:
+            partials = []
+        for p in partials:
+            pseq = p.get("seq", -1)
+            if pseq < conv._next_seq:
+                # Stale — clean it up.
+                try:
+                    await store.clear_partial(pseq)
+                except AttributeError:
+                    pass
+                continue
+            # Only resurrect partials relevant to this run / phase.
+            if run_id and not is_legacy_run_id(run_id) and p.get("run_id") != run_id:
+                continue
+            if phase_id and p.get("phase_id") is not None and p.get("phase_id") != phase_id:
+                continue
+            # Reconstruct as a truncated assistant message.
+            msg = Message(
+                seq=pseq,
+                role="assistant",
+                content=p.get("content", "") or "",
+                tool_calls=p.get("tool_calls"),
+                phase_id=p.get("phase_id"),
+                run_id=p.get("run_id"),
+                truncated=True,
+            )
+            conv._messages.append(msg)
+            conv._next_seq = max(conv._next_seq, pseq + 1)
+            logger.info(
+                "restore: resurrected truncated partial seq=%d (text=%d chars, tool_calls=%d)",
+                pseq,
+                len(msg.content),
+                len(msg.tool_calls or []),
+            )
+
         return conv

core/framework/agent_loop/internals/compaction.py

@@ -16,7 +16,6 @@ import os
 import re
 import time
 from datetime import UTC, datetime
-from pathlib import Path
 from typing import Any
 
 from framework.agent_loop.conversation import Message, NodeConversation
@@ -31,19 +30,38 @@ logger = logging.getLogger(__name__)
 LLM_COMPACT_CHAR_LIMIT: int = 240_000
 LLM_COMPACT_MAX_DEPTH: int = 10
 
-# Microcompaction: tools whose results can be safely cleared
+# Microcompaction: tools whose results can be safely cleared from context
+# because the agent can re-derive them on demand. The bar for inclusion is
+# "old result has no irreversible value": file content can be re-read, a
+# search can be re-run, a screenshot can be re-captured, terminal output can
+# be re-fetched, etc. Write / edit results are short confirmations whose
+# value is in the side effect, not the message — also fair game.
 COMPACTABLE_TOOLS: frozenset[str] = frozenset(
     {
+        # File ops — content lives on disk, re-readable.
         "read_file",
-        "run_command",
-        "web_search",
-        "web_fetch",
-        "grep_search",
-        "glob_search",
+        "search_files",
         "write_file",
         "edit_file",
+        "pdf_read",
+        # Terminal — re-runnable; advanced job/output tools produce verbose
+        # logs whose recent state is what matters.
+        "terminal_exec",
+        "terminal_rg",
+        "terminal_find",
+        "terminal_output_get",
+        "terminal_job_logs",
+        # Web / research — pages and queries can be re-fetched.
+        "web_scrape",
+        "search_papers",
+        "download_paper",
+        "search_wikipedia",
+        # Browser read-only inspection — current page state is what matters,
+        # old snapshots are stale by definition.
         "browser_screenshot",
-        "list_directory",
+        "browser_snapshot",
+        "browser_html",
+        "browser_get_text",
     }
 )
 
@@ -371,6 +389,7 @@ async def llm_compact(
     char_limit: int = LLM_COMPACT_CHAR_LIMIT,
     max_depth: int = LLM_COMPACT_MAX_DEPTH,
     max_context_tokens: int = 128_000,
+    preserve_user_messages: bool = False,
 ) -> str:
     """Summarise *messages* with LLM, splitting recursively if too large.
 
@@ -378,6 +397,11 @@ async def llm_compact(
     rejects the call with a context-length error, the messages are split
     in half and each half is summarised independently.  Tool history is
     appended once at the top-level call (``_depth == 0``).
+
+    When ``preserve_user_messages`` is True, the prompt and system message
+    are amplified to instruct the LLM to keep every user message verbatim
+    and in full — used by the manual /compact-and-fork endpoint where the
+    user wants their voice carried into the new session intact.
     """
     from framework.agent_loop.conversation import extract_tool_call_history
     from framework.agent_loop.internals.tool_result_handler import is_context_too_large_error
@@ -401,6 +425,7 @@ async def llm_compact(
             char_limit=char_limit,
             max_depth=max_depth,
             max_context_tokens=max_context_tokens,
+            preserve_user_messages=preserve_user_messages,
         )
     else:
         prompt = build_llm_compaction_prompt(
@@ -408,17 +433,30 @@ async def llm_compact(
             accumulator,
             formatted,
             max_context_tokens=max_context_tokens,
+            preserve_user_messages=preserve_user_messages,
         )
+        if preserve_user_messages:
+            system_msg = (
+                "You are a conversation compactor for an AI agent. "
+                "Write a detailed summary that allows the agent to "
+                "continue its work. CRITICAL: reproduce every user "
+                "message verbatim and in full inside the 'User Messages' "
+                "section — do not paraphrase, truncate, or merge them. "
+                "Assistant turns and tool results may be summarised, but "
+                "user input is sacred."
+            )
+        else:
+            system_msg = (
+                "You are a conversation compactor for an AI agent. "
+                "Write a detailed summary that allows the agent to "
+                "continue its work. Preserve user-stated rules, "
+                "constraints, and account/identity preferences verbatim."
+            )
         summary_budget = max(1024, max_context_tokens // 2)
         try:
             response = await ctx.llm.acomplete(
                 messages=[{"role": "user", "content": prompt}],
-                system=(
-                    "You are a conversation compactor for an AI agent. "
-                    "Write a detailed summary that allows the agent to "
-                    "continue its work. Preserve user-stated rules, "
-                    "constraints, and account/identity preferences verbatim."
-                ),
+                system=system_msg,
                 max_tokens=summary_budget,
             )
             summary = response.content
@@ -437,6 +475,7 @@ async def llm_compact(
                     char_limit=char_limit,
                     max_depth=max_depth,
                     max_context_tokens=max_context_tokens,
+                    preserve_user_messages=preserve_user_messages,
                 )
             else:
                 raise
@@ -459,6 +498,7 @@ async def _llm_compact_split(
     char_limit: int = LLM_COMPACT_CHAR_LIMIT,
     max_depth: int = LLM_COMPACT_MAX_DEPTH,
     max_context_tokens: int = 128_000,
+    preserve_user_messages: bool = False,
 ) -> str:
     """Split messages in half and summarise each half independently."""
     mid = max(1, len(messages) // 2)
@@ -470,6 +510,7 @@ async def _llm_compact_split(
         char_limit=char_limit,
         max_depth=max_depth,
         max_context_tokens=max_context_tokens,
+        preserve_user_messages=preserve_user_messages,
     )
     s2 = await llm_compact(
         ctx,
@@ -479,6 +520,7 @@ async def _llm_compact_split(
         char_limit=char_limit,
         max_depth=max_depth,
         max_context_tokens=max_context_tokens,
+        preserve_user_messages=preserve_user_messages,
     )
     return s1 + "\n\n" + s2
 
@@ -510,6 +552,7 @@ def build_llm_compaction_prompt(
     formatted_messages: str,
     *,
     max_context_tokens: int = 128_000,
+    preserve_user_messages: bool = False,
 ) -> str:
     """Build prompt for LLM compaction targeting 50% of token budget.
 
@@ -539,6 +582,18 @@ def build_llm_compaction_prompt(
     target_chars = target_tokens * 4
     node_ctx = "\n".join(ctx_lines)
 
+    user_messages_section = (
+        "6. **User Messages** — Reproduce EVERY user message verbatim and "
+        "in full, in chronological order, each on its own line prefixed "
+        'with the message index (e.g. "[U1] ..."). Do NOT paraphrase, '
+        "summarise, merge, or omit any user message. Preserve markdown, "
+        "code fences, whitespace, and punctuation exactly as the user "
+        "wrote them.\n"
+        if preserve_user_messages
+        else "6. **User Messages** — Preserve ALL user-stated rules, constraints, "
+        "identity preferences, and account details verbatim.\n"
+    )
+
     return (
         "You are compacting an AI agent's conversation history. "
         "The agent is still working and needs to continue.\n\n"
@@ -559,8 +614,7 @@ def build_llm_compaction_prompt(
         "resolved. Include root causes so the agent doesn't repeat them.\n"
         "5. **Problem Solving Efforts** — Approaches tried, dead ends hit, "
         "and reasoning behind the current strategy.\n"
-        "6. **User Messages** — Preserve ALL user-stated rules, constraints, "
-        "identity preferences, and account details verbatim.\n"
+        f"{user_messages_section}"
         "7. **Pending Tasks** — Work remaining, outputs still needed, and "
         "any blockers.\n"
         "8. **Current Work** — The most recent action taken and the immediate "
@@ -621,8 +675,10 @@ def write_compaction_debug_log(
     level: str,
     inventory: list[dict[str, Any]] | None,
 ) -> None:
-    """Write detailed compaction analysis to ~/.hive/compaction_log/."""
-    log_dir = Path.home() / ".hive" / "compaction_log"
+    """Write detailed compaction analysis to $HIVE_HOME/compaction_log/."""
+    from framework.config import HIVE_HOME
+
+    log_dir = HIVE_HOME / "compaction_log"
     log_dir.mkdir(parents=True, exist_ok=True)
 
     ts = datetime.now(UTC).strftime("%Y%m%dT%H%M%S_%f")
@@ -821,7 +877,7 @@ def build_emergency_summary(
                 if not all_files:
                     parts.append(
                         "NOTE: Large tool results may have been saved to files. "
-                        "Use list_directory to check the data directory."
+                        "Use search_files(target='files', path='.') to check the data directory."
                     )
         except Exception:
             parts.append("NOTE: Large tool results were saved to files. Use read_file(path='<path>') to read them.")

core/framework/agent_loop/internals/cursor_persistence.py

@@ -12,6 +12,7 @@ import json
 import logging
 from collections.abc import Awaitable, Callable
 from dataclasses import dataclass
+from datetime import datetime
 from typing import Any
 
 from framework.agent_loop.conversation import ConversationStore, NodeConversation
@@ -161,9 +162,18 @@ async def drain_injection_queue(
     conversation: NodeConversation,
     *,
     ctx: NodeContext,
-    describe_images_as_text_fn: (Callable[[list[dict[str, Any]]], Awaitable[str | None]] | None) = None,
+    caption_image_fn: (Callable[[str, list[dict[str, Any]]], Awaitable[tuple[str, str] | None]] | None) = None,
 ) -> int:
-    """Drain all pending injected events as user messages. Returns count."""
+    """Drain all pending injected events as user messages. Returns count.
+
+    ``caption_image_fn`` is the unified vision fallback hook. It takes
+    ``(intent, image_content)`` and returns ``(caption, model)`` on
+    success — the model id is logged so the destination is observable.
+    The user's typed ``content`` (the injected message body) is passed
+    as the intent so the captioner can answer the user's specific
+    question about the image rather than producing a generic
+    description; an empty content falls back to a generic intent.
+    """
     count = 0
     logger.debug(
         "[drain_injection_queue] Starting to drain queue, initial queue size: %s",
@@ -183,23 +193,34 @@ async def drain_injection_queue(
                     "Model '%s' does not support images; attempting vision fallback",
                     ctx.llm.model,
                 )
-                if describe_images_as_text_fn is not None:
-                    description = await describe_images_as_text_fn(image_content)
-                    if description:
+                if caption_image_fn is not None:
+                    intent = content or ("Describe these user-injected images for a text-only agent.")
+                    caption_result = await caption_image_fn(intent, image_content)
+                    if caption_result:
+                        description, vision_model = caption_result
                         content = f"{content}\n\n{description}" if content else description
-                        logger.info("[drain] image described as text via vision fallback")
+                        logger.info(
+                            "[drain] image described as text via vision fallback (model '%s')",
+                            vision_model,
+                        )
                     else:
                         logger.info("[drain] no vision fallback available; images dropped")
                 image_content = None
-            # Real user input is stored as-is; external events get a prefix
+            # Stamp every injected event with its arrival time so the model
+            # has a consistent temporal log to reason over (and so the
+            # stamp lives inside byte-stable conversation history instead
+            # of a per-turn system-prompt tail). Minute precision is what
+            # the queen needs for conversational / scheduling context.
+            stamp = datetime.now().astimezone().strftime("%Y-%m-%d %H:%M %Z")
             if is_client_input:
+                stamped = f"[{stamp}] {content}" if content else f"[{stamp}]"
                 await conversation.add_user_message(
-                    content,
+                    stamped,
                     is_client_input=True,
                     image_content=image_content,
                 )
             else:
-                await conversation.add_user_message(f"[External event]: {content}")
+                await conversation.add_user_message(f"[{stamp}] [External event] {content}")
             count += 1
         except asyncio.QueueEmpty:
             break
@@ -232,9 +253,12 @@ async def drain_trigger_queue(
         payload_str = json.dumps(t.payload, default=str)
         parts.append(f"[TRIGGER: {t.trigger_type}/{t.source_id}]{task_line}\n{payload_str}")
 
-    combined = "\n\n".join(parts)
+    stamp = datetime.now().astimezone().strftime("%Y-%m-%d %H:%M %Z")
+    combined = f"[{stamp}]\n" + "\n\n".join(parts)
     logger.info("[drain] %d trigger(s): %s", len(triggers), combined[:200])
-    await conversation.add_user_message(combined)
+    # Tag the message so the UI can render a banner instead of the raw
+    # `[TRIGGER: ...]` text. The LLM still sees `combined` verbatim.
+    await conversation.add_user_message(combined, is_trigger=True)
     return len(triggers)
 
 

core/framework/agent_loop/internals/event_publishing.py

@@ -108,6 +108,8 @@ async def publish_llm_turn_complete(
     input_tokens: int,
     output_tokens: int,
     cached_tokens: int = 0,
+    cache_creation_tokens: int = 0,
+    cost_usd: float = 0.0,
     execution_id: str = "",
     iteration: int | None = None,
 ) -> None:
@@ -120,6 +122,8 @@ async def publish_llm_turn_complete(
             input_tokens=input_tokens,
             output_tokens=output_tokens,
             cached_tokens=cached_tokens,
+            cache_creation_tokens=cache_creation_tokens,
+            cost_usd=cost_usd,
             execution_id=execution_id,
             iteration=iteration,
         )

core/framework/agent_loop/internals/synthetic_tools.py

@@ -91,108 +91,66 @@ def sanitize_ask_user_inputs(
     return q, recovered
 
 
+ask_user_prompt = """\
+Use this tool when you need to ask the user questions during execution. Reach for it when:
+
+- The task is ambiguous and the user needs to choose an approach
+- You need missing information to continue
+- You want approval before taking a meaningful action
+- A decision has real trade-offs the user should weigh in on
+- You want post-task feedback, or to offer saving a skill or updating memory
+
+Usage notes:
+- Users will always be able to select "Other" to provide custom text input, \
+so do not include catch-all options like "Other" or "Something else" yourself.
+- Each option is a plain string. Do NOT wrap options in `{"label": "..."}` or \
+`{"value": "..."}` objects — pass the raw choice text directly, e.g. `"Email"`, \
+not `{"label": "Email"}`.
+- If you recommend a specific option, make that the first option in the list \
+and append " (Recommended)" to the end of its text.
+- Call this tool whenever you need the user's response.
+- The prompt field must be plain text only.
+- Do not include XML, pseudo-tags, or inline option lists inside prompt.
+- Omit options only when the question truly requires a free-form response the \
+user must type out, such as describing an idea or pasting an error message.
+- Do not repeat the questions in your normal text response. The widget renders \
+them, so keep any surrounding text to a brief intro only.
+Example — single question with options:
+{"questions": [{"id": "next", "prompt": "What would you like to do?", \
+"options": ["Build a new agent (Recommended)", "Modify existing agent", "Run tests"]}]}
+
+Example — batch:
+{"questions": [
+  {"id": "scope", "prompt": "What scope?", "options": ["Full", "Partial"]},
+  {"id": "format", "prompt": "Output format?", "options": ["PDF", "CSV", "JSON"]},
+  {"id": "details", "prompt": "Any special requirements?"}
+]}
+
+Example — free-form (queen only):
+{"questions": [{"id": "idea", "prompt": "Describe the agent you want to build."}]}
+"""
+
+
 def build_ask_user_tool() -> Tool:
     """Build the synthetic ask_user tool for explicit user-input requests.
 
-    The queen calls ask_user() when it needs to pause and wait
-    for user input.  Text-only turns WITHOUT ask_user flow through without
-    blocking, allowing progress updates and summaries to stream freely.
+    The queen calls ask_user() when it needs to pause and wait for user
+    input. Accepts an array of 1-8 questions — a single question for the
+    common case, or a batch when several clarifications are needed at once.
+    Text-only turns WITHOUT ask_user flow through without blocking, allowing
+    progress updates and summaries to stream freely.
     """
     return Tool(
         name="ask_user",
-        description=(
-            "You MUST call this tool whenever you need the user's response. "
-            "Always call it after greeting the user, asking a question, or "
-            "requesting approval. Do NOT call it for status updates or "
-            "summaries that don't require a response.\n\n"
-            "STRUCTURE RULES (CRITICAL):\n"
-            "- The 'question' field is PLAIN TEXT shown to the user. Do NOT "
-            "include XML tags, pseudo-tags like </question>, or option lists "
-            "in the question string. The UI does not parse them — they "
-            "render as raw text and look broken.\n"
-            "- The 'options' parameter is the ONLY way to render buttons. "
-            "If you want buttons, put them in the 'options' array, not in "
-            "the question string. Do NOT write 'OPTIONS: [...]', "
-            "'_options: [...]', or any inline list inside 'question'.\n"
-            "- The question text must read as a single clean prompt with "
-            "no markup. Example: 'What would you like to do?' — not "
-            "'What would you like to do?</question>'.\n\n"
-            "USAGE:\n"
-            "Always include 2-3 predefined options. The UI automatically "
-            "appends an 'Other' free-text input after your options, so NEVER "
-            "include catch-all options like 'Custom idea', 'Something else', "
-            "'Other', or 'None of the above' — the UI handles that. "
-            "When the question primarily needs a typed answer but you must "
-            "include options, make one option signal that typing is expected "
-            "(e.g. 'I\\'ll type my response'). This helps users discover the "
-            "free-text input. "
-            "The ONLY exception: omit options when the question demands a "
-            "free-form answer the user must type out (e.g. 'Describe your "
-            "agent idea', 'Paste the error message').\n\n"
-            "CORRECT EXAMPLE:\n"
-            '{"question": "What would you like to do?", "options": '
-            '["Build a new agent", "Modify existing agent", "Run tests"]}\n\n'
-            "FREE-FORM EXAMPLE:\n"
-            '{"question": "Describe the agent you want to build."}\n\n'
-            "WRONG (do NOT do this — buttons will not render):\n"
-            '{"question": "What now?</question>\\n_OPTIONS: [\\"A\\", \\"B\\"]"}'
-        ),
-        parameters={
-            "type": "object",
-            "properties": {
-                "question": {
-                    "type": "string",
-                    "description": "The question or prompt shown to the user.",
-                },
-                "options": {
-                    "type": "array",
-                    "items": {"type": "string"},
-                    "description": (
-                        "2-3 specific predefined choices. Include in most cases. "
-                        'Example: ["Option A", "Option B", "Option C"]. '
-                        "The UI always appends an 'Other' free-text input, so "
-                        "do NOT include catch-alls like 'Custom idea' or 'Other'. "
-                        "Omit ONLY when the user must type a free-form answer."
-                    ),
-                    "minItems": 2,
-                    "maxItems": 3,
-                },
-            },
-            "required": ["question"],
-        },
-    )
-
-
-def build_ask_user_multiple_tool() -> Tool:
-    """Build the synthetic ask_user_multiple tool for batched questions.
-
-    Queen-only tool that presents multiple questions at once so the user
-    can answer them all in a single interaction rather than one at a time.
-    """
-    return Tool(
-        name="ask_user_multiple",
-        description=(
-            "Ask the user multiple questions at once. Use this instead of "
-            "ask_user when you have 2 or more questions to ask in the same "
-            "turn — it lets the user answer everything in one go rather than "
-            "going back and forth. Each question can have its own predefined "
-            "options (2-3 choices) or be free-form. The UI renders all "
-            "questions together with a single Submit button. "
-            "ALWAYS prefer this over ask_user when you have multiple things "
-            "to clarify. "
-            "IMPORTANT: Do NOT repeat the questions in your text response — "
-            "the widget renders them. Keep your text to a brief intro only. "
-            '{"questions": ['
-            '  {"id": "scope", "prompt": "What scope?", "options": ["Full", "Partial"]},'
-            '  {"id": "format", "prompt": "Output format?", "options": ["PDF", "CSV", "JSON"]},'
-            '  {"id": "details", "prompt": "Any special requirements?"}'
-            "]}"
-        ),
+        description=ask_user_prompt,
         parameters={
             "type": "object",
             "properties": {
                 "questions": {
                     "type": "array",
+                    "minItems": 1,
+                    "maxItems": 8,
+                    "description": "List of questions to present to the user.",
                     "items": {
                         "type": "object",
                         "properties": {
@@ -208,8 +166,13 @@ def build_ask_user_multiple_tool() -> Tool:
                                 "type": "array",
                                 "items": {"type": "string"},
                                 "description": (
-                                    "2-3 predefined choices. The UI appends an "
-                                    "'Other' free-text input automatically. "
+                                    "2-3 predefined choices as plain strings "
+                                    '(e.g. ["Yes", "No", "Maybe"]). Do NOT '
+                                    'wrap items in {"label": "..."} or '
+                                    '{"value": "..."} objects — pass the raw '
+                                    "choice text directly. The UI appends an "
+                                    "'Other' free-text input automatically, "
+                                    "so don't include catch-all options. "
                                     "Omit only when the user must type a free-form answer."
                                 ),
                                 "minItems": 2,
@@ -218,9 +181,6 @@ def build_ask_user_multiple_tool() -> Tool:
                         },
                         "required": ["id", "prompt"],
                     },
-                    "minItems": 2,
-                    "maxItems": 8,
-                    "description": "List of questions to present to the user.",
                 },
             },
             "required": ["questions"],

core/framework/agent_loop/internals/tool_input_coercer.py

@@ -0,0 +1,291 @@
+"""Generic coercion of LLM-emitted tool arguments to match each tool's JSON schema.
+
+Small/mid-size models drift from tool schemas in predictable, boring ways:
+
+- A number field comes back as a string (``"42"`` instead of ``42``).
+- A boolean field comes back as a string (``"true"`` instead of ``True``).
+- An array-of-string field comes back as an array of objects
+  (``[{"label": "A"}, ...]`` instead of ``["A", ...]``).
+- An array/object field comes back as a JSON-encoded string
+  (``'["A","B"]'`` instead of ``["A", "B"]``).
+- A lone scalar arrives where the schema expects an array.
+
+This module centralizes the healing in one schema-driven pass that runs
+on every tool call before dispatch. Coercion is conservative:
+
+- Values that already match the expected type are untouched.
+- Shapes we don't recognize are returned as-is, so real bugs surface
+  instead of getting silently munged into something plausible.
+- Every actual coercion is logged with the tool, property, and shape
+  transition so we can see which models/tools are drifting.
+
+Tool-specific prompt drift (e.g. ``</question>`` tags leaking into an
+``ask_user`` prompt string) is NOT this module's job — that belongs in
+per-tool sanitizers, because it's about prompt style, not schema shape.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+from framework.llm.provider import Tool
+
+logger = logging.getLogger(__name__)
+
+# When an ``array<string>`` field arrives as an array of objects, look
+# for a text-carrying field in preference order. Covers the wrappers
+# small models tend to produce: ``[{"label": "A"}]``, ``[{"value": "A"}]``,
+# ``[{"text": "A"}]``, etc.
+_STRING_EXTRACT_KEYS: tuple[str, ...] = (
+    "label",
+    "value",
+    "text",
+    "name",
+    "title",
+    "display",
+)
+
+
+def coerce_tool_input(tool: Tool, raw_input: dict[str, Any] | None) -> dict[str, Any]:
+    """Coerce *raw_input* in place to match *tool*'s JSON schema.
+
+    Returns the mutated input dict (same object as *raw_input* when
+    possible, for callers that assume in-place mutation). Properties
+    not present in the schema are left untouched.
+    """
+    if not isinstance(raw_input, dict):
+        return raw_input or {}
+
+    schema = tool.parameters or {}
+    props = schema.get("properties")
+    if not isinstance(props, dict):
+        return raw_input
+
+    for key in list(raw_input.keys()):
+        prop_schema = props.get(key)
+        if not isinstance(prop_schema, dict):
+            continue
+        original = raw_input[key]
+        coerced = _coerce(original, prop_schema)
+        if coerced is not original:
+            logger.info(
+                "coerced tool input tool=%s prop=%s from=%s to=%s",
+                tool.name,
+                key,
+                _shape(original),
+                _shape(coerced),
+            )
+            raw_input[key] = coerced
+
+    return raw_input
+
+
+def _coerce(value: Any, schema: dict[str, Any]) -> Any:
+    """Dispatch on the schema's ``type`` field.
+
+    Returns the *same object* on passthrough so callers can detect
+    no-ops via identity (``coerced is value``).
+    """
+    expected = schema.get("type")
+    if not expected:
+        return value
+
+    # Union type: try each in order, return the first coercion that
+    # actually changes the value. Falls back to the original.
+    if isinstance(expected, list):
+        for t in expected:
+            sub_schema = {**schema, "type": t}
+            coerced = _coerce(value, sub_schema)
+            if coerced is not value:
+                return coerced
+        return value
+
+    if expected == "integer":
+        return _coerce_integer(value)
+    if expected == "number":
+        return _coerce_number(value)
+    if expected == "boolean":
+        return _coerce_boolean(value)
+    if expected == "string":
+        return _coerce_string(value)
+    if expected == "array":
+        return _coerce_array(value, schema)
+    if expected == "object":
+        return _coerce_object(value, schema)
+
+    return value
+
+
+def _coerce_integer(value: Any) -> Any:
+    # bool is a subclass of int in Python; don't mistake True for 1 here.
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, int):
+        return value
+    if isinstance(value, str):
+        parsed = _parse_number(value)
+        if parsed is None:
+            return value
+        if parsed != int(parsed):
+            # Has a fractional part — caller asked for int, don't truncate.
+            return value
+        return int(parsed)
+    return value
+
+
+def _coerce_number(value: Any) -> Any:
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, (int, float)):
+        return value
+    if isinstance(value, str):
+        parsed = _parse_number(value)
+        if parsed is None:
+            return value
+        if parsed == int(parsed):
+            return int(parsed)
+        return parsed
+    return value
+
+
+def _coerce_boolean(value: Any) -> Any:
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        low = value.strip().lower()
+        if low == "true":
+            return True
+        if low == "false":
+            return False
+    return value
+
+
+def _coerce_string(value: Any) -> Any:
+    if isinstance(value, str):
+        return value
+    # Common drift: model sent ``{"label": "..."}`` when we wanted "...".
+    if isinstance(value, dict):
+        extracted = _extract_string_from_object(value)
+        if extracted is not None:
+            return extracted
+    return value
+
+
+def _coerce_array(value: Any, schema: dict[str, Any]) -> Any:
+    # Heal: JSON-encoded array string → array.
+    if isinstance(value, str):
+        parsed = _try_parse_json(value)
+        if isinstance(parsed, list):
+            value = parsed
+        else:
+            # Scalar string where an array is expected — wrap it.
+            return [value]
+    elif not isinstance(value, list):
+        # Any other scalar (int, bool, dict, ...) — wrap.
+        return [value]
+
+    items_schema = schema.get("items")
+    if not isinstance(items_schema, dict):
+        return value
+
+    coerced_items: list[Any] = []
+    changed = False
+    for item in value:
+        c = _coerce(item, items_schema)
+        if c is not item:
+            changed = True
+        coerced_items.append(c)
+    return coerced_items if changed else value
+
+
+def _coerce_object(value: Any, schema: dict[str, Any]) -> Any:
+    # Heal: JSON-encoded object string → object.
+    if isinstance(value, str):
+        parsed = _try_parse_json(value)
+        if isinstance(parsed, dict):
+            value = parsed
+        else:
+            return value
+    if not isinstance(value, dict):
+        return value
+
+    sub_props = schema.get("properties")
+    if not isinstance(sub_props, dict):
+        return value
+
+    changed = False
+    for k in list(value.keys()):
+        sub_schema = sub_props.get(k)
+        if not isinstance(sub_schema, dict):
+            continue
+        original = value[k]
+        coerced = _coerce(original, sub_schema)
+        if coerced is not original:
+            value[k] = coerced
+            changed = True
+    # Return the same dict on mutation so callers that passed a shared
+    # reference see the updates. ``changed`` is only used to decide
+    # whether we need to log at a coarser level upstream.
+    return value if changed or not sub_props else value
+
+
+def _extract_string_from_object(obj: dict[str, Any]) -> str | None:
+    """Pick a likely-text field out of a wrapper object.
+
+    Tries the known keys first, falls back to the sole value if the
+    object has exactly one entry. Returns None when nothing plausible
+    is found — the caller keeps the original.
+    """
+    for k in _STRING_EXTRACT_KEYS:
+        v = obj.get(k)
+        if isinstance(v, str) and v:
+            return v
+    if len(obj) == 1:
+        (only,) = obj.values()
+        if isinstance(only, str) and only:
+            return only
+    return None
+
+
+def _try_parse_json(raw: str) -> Any:
+    try:
+        return json.loads(raw)
+    except (ValueError, TypeError):
+        return None
+
+
+def _parse_number(raw: str) -> float | None:
+    try:
+        f = float(raw)
+    except (ValueError, OverflowError):
+        return None
+    # Reject NaN and inf — they pass float() but aren't useful numeric
+    # values for tool arguments.
+    if f != f or f == float("inf") or f == float("-inf"):
+        return None
+    return f
+
+
+def _shape(value: Any) -> str:
+    """Short type/shape description used in coercion log lines."""
+    if value is None:
+        return "None"
+    if isinstance(value, bool):
+        return "bool"
+    if isinstance(value, int):
+        return "int"
+    if isinstance(value, float):
+        return "float"
+    if isinstance(value, str):
+        return f"str[{len(value)}]"
+    if isinstance(value, list):
+        if not value:
+            return "list[0]"
+        return f"list[{len(value)}]<{_shape(value[0])}>"
+    if isinstance(value, dict):
+        keys = sorted(value.keys())[:3]
+        suffix = ",…" if len(value) > 3 else ""
+        return f"dict{{{','.join(keys)}{suffix}}}"
+    return type(value).__name__

core/framework/agent_loop/internals/types.py

@@ -69,6 +69,20 @@ class LoopConfig:
     # and less tight than Anthropic's own counting. Override via
     # LoopConfig for larger windows.
     compaction_buffer_tokens: int = 8_000
+    # Ratio-based component of the hybrid compaction buffer. Effective
+    # headroom reserved before compaction fires is
+    #   compaction_buffer_tokens + compaction_buffer_ratio * max_context_tokens
+    # The ratio scales with the model's window where the absolute fixed
+    # component does not (an 8k absolute buffer is 75% trigger on a 32k
+    # window but 96% on a 200k window). Combining them gives an absolute
+    # floor sized for the worst-case single tool result (one un-spilled
+    # max_tool_result_chars payload ≈ 30k chars ≈ 7.5k tokens, rounded to
+    # 8k) plus a fractional headroom that keeps the trigger meaningful on
+    # large windows, so the inner tool loop always has room to grow
+    # without tripping the mid-turn pre-send guard. Defaults: 8k + 15%.
+    # On 32k that's a 12.8k buffer (~60% trigger); on 200k it's 38k
+    # (~81% trigger); on 1M it's 158k (~84% trigger).
+    compaction_buffer_ratio: float = 0.15
     # Warning is emitted one buffer earlier so the user/telemetry gets
     # a "we're close" signal without triggering a compaction pass.
     compaction_warning_buffer_tokens: int = 12_000
@@ -131,14 +145,39 @@ class LoopConfig:
     # Per-tool-call timeout.
     tool_call_timeout_seconds: float = 60.0
 
-    # LLM stream inactivity watchdog. If no stream event (delta, tool call,
-    # finish) arrives within this many seconds, the stream task is cancelled
-    # and a transient error is raised so the retry loop can back off and
-    # reconnect. Prevents agents from hanging forever on a silently dead
-    # HTTP connection (no provider heartbeat, no exception, just silence).
-    # Set to 0 to disable.
+    # LLM stream inactivity watchdog. Split into two budgets so legitimate
+    # slow TTFT on large contexts doesn't get mistaken for a dead connection.
+    # - ttft: stream open -> first event. Large-context local models can
+    #   legitimately take minutes before the first token arrives.
+    # - inter_event: last event -> now, ONLY after the first event. A stream
+    #   that started producing and then went silent is a real stall.
+    # Whichever fires first cancels the stream. Set to 0 to disable that
+    # individual budget; set both to 0 to fully disable the watchdog.
+    llm_stream_ttft_timeout_seconds: float = 600.0
+    llm_stream_inter_event_idle_seconds: float = 120.0
+    # Deprecated alias — kept so existing configs keep working. If set to a
+    # non-default value it overrides inter_event_idle (historical behavior).
     llm_stream_inactivity_timeout_seconds: float = 120.0
 
+    # Continue-nudge recovery. When the idle watchdog fires on a live but
+    # stuck stream, cancel the stream and append a short continuation
+    # hint to the conversation instead of raising a ConnectionError and
+    # re-running the whole turn. Preserves any partial text/tool-calls the
+    # stream emitted before the stall.
+    continue_nudge_enabled: bool = True
+    # Cap so a truly dead endpoint eventually falls back to the error path
+    # instead of nudging forever.
+    continue_nudge_max_per_turn: int = 3
+
+    # Tool-call replay detector. When the model emits a tool call whose
+    # (name + canonical-args) matches a prior successful call in the last
+    # K assistant turns, emit telemetry and prepend a short steer onto the
+    # tool result — but still execute. Weaker models legitimately repeat
+    # read-only calls (screenshot, evaluate), so silent skipping would
+    # cause surprising behavior.
+    replay_detector_enabled: bool = True
+    replay_detector_within_last_turns: int = 3
+
     # Subagent delegation timeout (wall-clock max).
     subagent_timeout_seconds: float = 3600.0
 

core/framework/agent_loop/internals/vision_fallback.py

@@ -0,0 +1,306 @@
+"""Vision-fallback subagent for tool-result images on text-only LLMs.
+
+When a tool returns image content but the main agent's model can't
+accept image blocks (i.e. its catalog entry has ``supports_vision: false``),
+the framework strips the images before they ever reach the LLM. Without
+this module, the agent then sees only the tool's text envelope (URL,
+dimensions, size) and is blind to whatever the image actually shows.
+
+This module provides:
+
+* ``caption_tool_image()`` — direct LiteLLM call to a configured
+  vision model (``vision_fallback`` block in ``~/.hive/configuration.json``)
+  that takes the agent's intent + the image(s) and returns a textual
+  description tailored to that intent.
+* ``extract_intent_for_tool()`` — pull the most recent assistant text
+  + the tool call descriptor and concatenate them into a ≤2KB intent
+  string the vision subagent can reason against.
+
+Both helpers degrade silently — return ``None`` / a placeholder rather
+than raise — so a vision-fallback failure can never kill the main
+agent's run. The agent-loop call site retries the configured model
+once on a None return, then falls back to
+``gemini/gemini-3-flash-preview`` via the ``model_override`` parameter
+of :func:`caption_tool_image`.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from datetime import datetime
+from typing import TYPE_CHECKING, Any
+
+from framework.config import (
+    get_vision_fallback_api_base,
+    get_vision_fallback_api_key,
+    get_vision_fallback_model,
+)
+
+if TYPE_CHECKING:
+    from ..conversation import NodeConversation
+
+logger = logging.getLogger(__name__)
+
+
+# Hard cap on the intent string handed to the vision subagent. The
+# subagent only needs the agent's recent reasoning + the tool descriptor;
+# anything longer is wasted tokens (and risks pushing past the vision
+# model's context with the image attached).
+_INTENT_MAX_CHARS = 4096
+
+# Cap on the tool args JSON snippet inside the intent. Some tool inputs
+# (large strings, file contents) would dominate the intent if uncapped.
+_TOOL_ARGS_MAX_CHARS = 4096
+
+# Subagent system prompt — kept short so it fits within any provider's
+# system-prompt budget alongside the user message + image. Tells the
+# subagent its role and constrains output format.
+#
+# Coordinate labeling: the main agent's browser tools
+# (browser_click_coordinate / browser_hover_coordinate / browser_press_at)
+# accept VIEWPORT FRACTIONS (x, y) in [0..1] where (0,0) is the top-left
+# and (1,1) is the bottom-right of the screenshot. Without coordinates
+# the text-only agent has no way to act on what we describe — it can
+# read the caption but cannot point. So for every interactive element
+# we name (button, link, input, icon, tab, menu item, dialog control),
+# include its approximate viewport-fraction centre as ``(fx, fy)``
+# right after the element's name, e.g. ``"Submit" button (0.83, 0.92)``.
+# Three rules: (1) coordinates only for things plausibly clickable /
+# hoverable / typeable — don't tag pure body text or decorative
+# graphics. (2) Eyeball to two decimal places; precision beyond that
+# is false confidence. (3) Never invent — if an element is partly
+# off-screen or you can't locate it, omit the coordinate rather than
+# guessing.
+_VISION_SUBAGENT_SYSTEM = (
+    "You are a vision subagent for a text-only main agent. The main "
+    "agent invoked a tool that returned the image(s) attached. Their "
+    "intent (their reasoning + the tool call) is below. Describe what "
+    "the image shows in service of their intent — concrete, factual, "
+    "no speculation. If their intent asks a yes/no question, answer it "
+    "directly first.\n\n"
+    "Coordinate labeling: the main agent uses fractional viewport "
+    "coordinates (x, y) in [0..1] — (0, 0) is the top-left of the "
+    "image, (1, 1) is the bottom-right — to drive its click / hover / "
+    "key-press tools. For every interactive element you mention "
+    "(button, link, input, checkbox, radio, dropdown, tab, menu item, "
+    "dialog control, icon), append its approximate centre as "
+    "``(fx, fy)`` immediately after the element's name or label, e.g. "
+    '``"Submit" button (0.83, 0.92)`` or ``profile avatar icon '
+    "(0.05, 0.07)``. Use two decimal places — more is false precision. "
+    "Skip coordinates for pure body text and decorative elements that "
+    "aren't clickable. If an element is partially off-screen or you "
+    "cannot reliably locate its centre, omit the coordinate rather "
+    "than guessing.\n\n"
+    "Output plain text, no markdown, ≤ 600 words."
+)
+
+
+def extract_intent_for_tool(
+    conversation: NodeConversation,
+    tool_name: str,
+    tool_args: dict[str, Any] | None,
+) -> str:
+    """Build the intent string passed to the vision subagent.
+
+    Combines the most recent assistant text (the LLM's reasoning right
+    before invoking the tool) with a structured tool-call descriptor.
+    Truncates to ``_INTENT_MAX_CHARS`` total, favouring the head of the
+    assistant text where goal-stating sentences usually live.
+
+    If no preceding assistant text exists (rare — first turn), falls
+    back to ``"<no preceding reasoning>"`` so the subagent still gets
+    the tool descriptor.
+    """
+    args_json: str
+    try:
+        args_json = json.dumps(tool_args or {}, default=str)
+    except Exception:
+        args_json = repr(tool_args)
+    if len(args_json) > _TOOL_ARGS_MAX_CHARS:
+        args_json = args_json[:_TOOL_ARGS_MAX_CHARS] + "…"
+
+    tool_line = f"Called: {tool_name}({args_json})"
+
+    # Walk newest → oldest, take the first assistant message with text.
+    assistant_text = ""
+    try:
+        messages = getattr(conversation, "_messages", []) or []
+        for msg in reversed(messages):
+            if getattr(msg, "role", None) != "assistant":
+                continue
+            content = getattr(msg, "content", "") or ""
+            if isinstance(content, str) and content.strip():
+                assistant_text = content.strip()
+                break
+    except Exception:
+        # Defensive — the agent loop must keep running even if the
+        # conversation structure changes shape.
+        assistant_text = ""
+
+    if not assistant_text:
+        assistant_text = "<no preceding reasoning>"
+
+    # Intent = tool descriptor (always intact) + reasoning (truncated).
+    head = f"{tool_line}\n\nReasoning before call:\n"
+    budget = _INTENT_MAX_CHARS - len(head)
+    if budget < 100:
+        # Tool descriptor is huge somehow — truncate it.
+        return head[:_INTENT_MAX_CHARS]
+    if len(assistant_text) > budget:
+        assistant_text = assistant_text[: budget - 1] + "…"
+    return head + assistant_text
+
+
+async def caption_tool_image(
+    intent: str,
+    image_content: list[dict[str, Any]],
+    *,
+    timeout_s: float = 30.0,
+    model_override: str | None = None,
+) -> tuple[str, str] | None:
+    """Caption the given images using the configured ``vision_fallback`` model.
+
+    Returns ``(caption, model)`` on success or ``None`` on any failure
+    (no config, no API key, timeout, exception, empty response).
+
+    ``model_override`` swaps in a different litellm model id while
+    keeping the configured ``vision_fallback`` ``api_key`` / ``api_base``
+    untouched. That's deliberate: Hive subscribers configure
+    ``vision_fallback`` to point at the Hive proxy, which routes to
+    multiple models including Gemini — so reusing the credentials lets
+    a Gemini-3-flash override still work without a separate
+    ``GEMINI_API_KEY``. When no creds are configured, litellm falls
+    back to env-var resolution.
+
+    Logs each call to ``~/.hive/llm_logs`` via ``log_llm_turn``.
+    """
+    model = model_override or get_vision_fallback_model()
+    if not model:
+        return None
+    api_key = get_vision_fallback_api_key()
+    api_base = get_vision_fallback_api_base()
+    if not api_key and not model_override:
+        logger.debug("vision_fallback configured but no API key resolved; skipping")
+        return None
+
+    try:
+        import litellm
+    except ImportError:
+        return None
+
+    user_blocks: list[dict[str, Any]] = [{"type": "text", "text": intent}]
+    user_blocks.extend(image_content)
+    messages = [
+        {"role": "system", "content": _VISION_SUBAGENT_SYSTEM},
+        {"role": "user", "content": user_blocks},
+    ]
+
+    # Apply the same proxy rewrites the main LLM provider uses so a
+    # `hive/...` / `kimi/...` model resolves to the right Anthropic-
+    # compatible endpoint with the right auth header. Without this,
+    # litellm doesn't know what `hive/kimi-k2.5` is and rejects the call
+    # with "LLM Provider NOT provided."
+    from framework.llm.litellm import rewrite_proxy_model
+
+    rewritten_model, rewritten_base, extra_headers = rewrite_proxy_model(model, api_key, api_base)
+
+    kwargs: dict[str, Any] = {
+        "model": rewritten_model,
+        "messages": messages,
+        "max_tokens": 8192,
+        "timeout": timeout_s,
+    }
+    # Always pass api_key when we have one, even alongside proxy-rewritten
+    # extra_headers. litellm's anthropic handler refuses to dispatch
+    # without an api_key (it sends it as x-api-key); the proxy itself
+    # authenticates via the Authorization: Bearer header in
+    # extra_headers. Both are needed — matches LiteLLMProvider's path.
+    if api_key:
+        kwargs["api_key"] = api_key
+    if rewritten_base:
+        kwargs["api_base"] = rewritten_base
+    if extra_headers:
+        kwargs["extra_headers"] = extra_headers
+
+    # Surface where the request is going so the user can verify the
+    # vision fallback is hitting the expected proxy / model. Redacts
+    # the API key to a length+head+tail digest so it can be cross-
+    # correlated with other auth-related log lines.
+    key_digest = (
+        f"len={len(api_key)} {api_key[:8]}…{api_key[-4:]}"
+        if api_key and len(api_key) >= 12
+        else f"len={len(api_key) if api_key else 0}"
+    )
+    logger.info(
+        "[vision_fallback] dispatching: configured_model=%s rewritten_model=%s "
+        "api_base=%s api_key=%s images=%d intent_chars=%d timeout_s=%.1f",
+        model,
+        rewritten_model,
+        rewritten_base or "<litellm-default>",
+        key_digest,
+        len(image_content),
+        len(intent),
+        timeout_s,
+    )
+
+    started = datetime.now()
+    caption: str | None = None
+    error_text: str | None = None
+    try:
+        response = await litellm.acompletion(**kwargs)
+        text = (response.choices[0].message.content or "").strip()
+        if text:
+            caption = text
+        logger.info(
+            "[vision_fallback] response: model=%s api_base=%s elapsed_s=%.2f chars=%d",
+            rewritten_model,
+            rewritten_base or "<litellm-default>",
+            (datetime.now() - started).total_seconds(),
+            len(text),
+        )
+    except Exception as exc:
+        error_text = f"{type(exc).__name__}: {exc}"
+        logger.warning(
+            "[vision_fallback] failed: model=%s api_base=%s error=%s",
+            rewritten_model,
+            rewritten_base or "<litellm-default>",
+            error_text,
+        )
+
+    # Best-effort audit log so users can grep ~/.hive/llm_logs/ for
+    # vision-fallback subagent calls. Failures here must not bubble.
+    try:
+        from framework.tracker.llm_debug_logger import log_llm_turn
+
+        # Don't dump the base64 image data into the log file — that
+        # would balloon the jsonl with mostly-binary noise.
+        elided_blocks: list[dict[str, Any]] = [{"type": "text", "text": intent}]
+        elided_blocks.extend({"type": "image_url", "image_url": {"url": "<elided>"}} for _ in range(len(image_content)))
+        log_llm_turn(
+            node_id="vision_fallback_subagent",
+            stream_id="vision_fallback",
+            execution_id="vision_fallback_subagent",
+            iteration=0,
+            system_prompt=_VISION_SUBAGENT_SYSTEM,
+            messages=[{"role": "user", "content": elided_blocks}],
+            assistant_text=caption or "",
+            tool_calls=[],
+            tool_results=[],
+            token_counts={
+                "model": model,
+                "elapsed_s": (datetime.now() - started).total_seconds(),
+                "error": error_text,
+                "num_images": len(image_content),
+                "intent_chars": len(intent),
+            },
+        )
+    except Exception:
+        pass
+
+    if caption is None:
+        return None
+    return caption, model
+
+
+__all__ = ["caption_tool_image", "extract_intent_for_tool"]

core/framework/agent_loop/prompting.py

@@ -53,7 +53,14 @@ def build_prompt_spec(
     # trigger tools are present in this agent's tool list (e.g. browser_*
     # pulls in hive.browser-automation). Keeps non-browser agents lean.
     tool_names = [getattr(t, "name", "") for t in (getattr(ctx, "available_tools", None) or [])]
-    skills_catalog_prompt = augment_catalog_for_tools(ctx.skills_catalog_prompt or "", tool_names)
+    raw_catalog = ctx.skills_catalog_prompt or ""
+    dynamic_catalog = getattr(ctx, "dynamic_skills_catalog_provider", None)
+    if dynamic_catalog is not None:
+        try:
+            raw_catalog = dynamic_catalog() or ""
+        except Exception:
+            raw_catalog = ctx.skills_catalog_prompt or ""
+    skills_catalog_prompt = augment_catalog_for_tools(raw_catalog, tool_names)
 
     return PromptSpec(
         identity_prompt=ctx.identity_prompt or "",

core/framework/agent_loop/types.py

@@ -180,9 +180,39 @@ class AgentContext:
 
     stream_id: str = ""
 
+    # ----- Task system fields (see framework/tasks) -------------------
+    # task_list_id: this agent's own session-scoped list, e.g.
+    #   session:{agent_id}:{session_id}. Set by the runner / ColonyRuntime
+    #   before the loop starts; immutable after first task_create.
+    task_list_id: str | None = None
+    # colony_id: set on the queen of a colony AND on every spawned worker
+    #   so workers can render the "picked up" chip and the queen can address
+    #   her colony template via colony_template_* tools.
+    colony_id: str | None = None
+    # picked_up_from: for workers, the (colony_task_list_id, template_task_id)
+    #   pair their session was spawned for. None for the queen and queen-DM.
+    picked_up_from: tuple[str, int] | None = None
+
     dynamic_tools_provider: Any = None
     dynamic_prompt_provider: Any = None
+    # Optional Callable[[], str]: when set alongside ``dynamic_prompt_provider``,
+    # the AgentLoop sends the system prompt as two pieces — the result of
+    # ``dynamic_prompt_provider`` is the STATIC block (cached), and this
+    # provider returns the DYNAMIC suffix (not cached). The LLM wrapper
+    # emits them as two Anthropic system content blocks with a cache
+    # breakpoint between them for providers that honor ``cache_control``.
+    # For providers that don't, the two strings are concatenated. Used by
+    # the Queen to keep her persona/role/tools block warm across iterations
+    # while the recall + timestamp tail refreshes per user turn.
+    dynamic_prompt_suffix_provider: Any = None
     dynamic_memory_provider: Any = None
+    # Optional Callable[[], str]: when set, the current skills-catalog
+    # prompt is sourced from this provider each iteration. Lets workers
+    # pick up UI toggles without restarting the run. Queen agents already
+    # rebuild the whole prompt via dynamic_prompt_provider — this field
+    # is a surgical alternative used by colony workers where the rest of
+    # the prompt stays constant and we don't want to thrash the cache.
+    dynamic_skills_catalog_provider: Any = None
 
     skills_catalog_prompt: str = ""
     protocols_prompt: str = ""

core/framework/agents/credential_tester/agent.py

@@ -560,7 +560,9 @@ class CredentialTesterAgent:
         if self._selected_account is None:
             raise RuntimeError("No account selected. Call select_account() first.")
 
-        self._storage_path = Path.home() / ".hive" / "agents" / "credential_tester"
+        from framework.config import HIVE_HOME
+
+        self._storage_path = HIVE_HOME / "agents" / "credential_tester"
         self._storage_path.mkdir(parents=True, exist_ok=True)
 
         self._tool_registry = ToolRegistry()

core/framework/agents/discovery.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import json
 from dataclasses import dataclass, field
+from datetime import UTC
 from pathlib import Path
 
 
@@ -47,6 +48,8 @@ class AgentEntry:
     tool_count: int = 0
     tags: list[str] = field(default_factory=list)
     last_active: str | None = None
+    created_at: str | None = None
+    icon: str | None = None
     workers: list[WorkerEntry] = field(default_factory=list)
 
 
@@ -63,7 +66,9 @@ def _get_last_active(agent_path: Path) -> str | None:
     latest: str | None = None
 
     # 1. Worker sessions
-    sessions_dir = Path.home() / ".hive" / "agents" / agent_name / "sessions"
+    from framework.config import HIVE_HOME
+
+    sessions_dir = HIVE_HOME / "agents" / agent_name / "sessions"
     if sessions_dir.exists():
         for session_dir in sessions_dir.iterdir():
             if not session_dir.is_dir() or not session_dir.name.startswith("session_"):
@@ -112,7 +117,9 @@ def _get_last_active(agent_path: Path) -> str | None:
 
 def _count_sessions(agent_name: str) -> int:
     """Count session directories under ~/.hive/agents/{agent_name}/sessions/."""
-    sessions_dir = Path.home() / ".hive" / "agents" / agent_name / "sessions"
+    from framework.config import HIVE_HOME
+
+    sessions_dir = HIVE_HOME / "agents" / agent_name / "sessions"
     if not sessions_dir.exists():
         return 0
     return sum(1 for d in sessions_dir.iterdir() if d.is_dir() and d.name.startswith("session_"))
@@ -120,7 +127,9 @@ def _count_sessions(agent_name: str) -> int:
 
 def _count_runs(agent_name: str) -> int:
     """Count unique run_ids across all sessions for an agent."""
-    sessions_dir = Path.home() / ".hive" / "agents" / agent_name / "sessions"
+    from framework.config import HIVE_HOME
+
+    sessions_dir = HIVE_HOME / "agents" / agent_name / "sessions"
     if not sessions_dir.exists():
         return 0
     run_ids: set[str] = set()
@@ -143,7 +152,7 @@ def _count_runs(agent_name: str) -> int:
     return len(run_ids)
 
 
-_EXCLUDED_JSON_STEMS = {"agent", "flowchart", "triggers", "configuration", "metadata"}
+_EXCLUDED_JSON_STEMS = {"agent", "flowchart", "triggers", "configuration", "metadata", "tasks"}
 
 
 def _is_colony_dir(path: Path) -> bool:
@@ -209,13 +218,26 @@ def discover_agents() -> dict[str, list[AgentEntry]]:
             name = config_fallback_name
             desc = ""
 
-            # Read colony metadata for queen provenance
+            # Read colony metadata for queen provenance and timestamps
             colony_queen_name = ""
+            colony_created_at: str | None = None
+            colony_icon: str | None = None
             metadata_path = path / "metadata.json"
             if metadata_path.exists():
                 try:
                     mdata = json.loads(metadata_path.read_text(encoding="utf-8"))
                     colony_queen_name = mdata.get("queen_name", "")
+                    colony_created_at = mdata.get("created_at")
+                    colony_icon = mdata.get("icon")
+                except Exception:
+                    pass
+            # Fallback: use directory creation time if metadata lacks created_at
+            if not colony_created_at:
+                try:
+                    from datetime import datetime
+
+                    stat = path.stat()
+                    colony_created_at = datetime.fromtimestamp(stat.st_birthtime, tz=UTC).isoformat()
                 except Exception:
                     pass
 
@@ -256,6 +278,8 @@ def discover_agents() -> dict[str, list[AgentEntry]]:
                     tool_count=tool_count,
                     tags=[],
                     last_active=_get_last_active(path),
+                    created_at=colony_created_at,
+                    icon=colony_icon,
                     workers=worker_entries,
                 )
             )

core/framework/agents/queen/config.py

@@ -2,12 +2,13 @@
 
 import json
 from dataclasses import dataclass, field
-from pathlib import Path
 
 
 def _load_preferred_model() -> str:
-    """Load preferred model from ~/.hive/configuration.json."""
-    config_path = Path.home() / ".hive" / "configuration.json"
+    """Load preferred model from $HIVE_HOME/configuration.json."""
+    from framework.config import HIVE_HOME
+
+    config_path = HIVE_HOME / "configuration.json"
     if config_path.exists():
         try:
             with open(config_path, encoding="utf-8") as f:

core/framework/agents/queen/incubating_evaluator.py

@@ -0,0 +1,235 @@
+"""One-shot LLM gate that decides if a queen DM is ready to fork a colony.
+
+The queen's ``start_incubating_colony`` tool calls :func:`evaluate` with
+the queen's recent conversation and a proposed ``colony_name``.  The
+evaluator returns a structured verdict:
+
+    {
+        "ready": bool,
+        "reasons": [str],
+        "missing_prerequisites": [str],
+    }
+
+On ``ready=False`` the queen receives the verdict as her tool result and
+self-corrects (asks the user, refines scope, drops the idea).  On
+``ready=True`` the tool flips the queen's phase to ``incubating``.
+
+Failure mode is **fail-closed**: any LLM error or unparseable response
+returns ``ready=False`` with reason ``"evaluation_failed"`` so the queen
+cannot accidentally proceed past a broken gate.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+from typing import Any
+
+from framework.agent_loop.conversation import Message
+
+logger = logging.getLogger(__name__)
+
+
+_INCUBATING_EVALUATOR_SYSTEM_PROMPT = """\
+You gate whether a queen agent should commit to forking a persistent
+"colony" (a headless worker spec written to disk).  Forking is
+expensive: it ends the user's chat with this queen and the worker runs
+unattended afterward, so the spec must be settled before you approve.
+
+Read the conversation excerpt and the queen's proposed colony_name,
+then decide.
+
+APPROVE (ready=true) only when ALL of the following hold:
+  1. The user has explicitly asked for work that needs to outlive this
+     chat — recurring (cron / interval), monitoring + alert, scheduled
+     batch, or "fire-and-forget background job".  A one-shot question
+     that the queen can answer in chat does NOT qualify.
+  2. The scope of the work is concrete enough to write down — what
+     inputs, what outputs, what success looks like.  Vague ("help me
+     with my workflow") does NOT qualify.
+  3. The technical approach is at least sketched — what data sources,
+     APIs, or tools the worker will use.  The queen does not have to
+     have written the SKILL.md yet, but she must have the operational
+     ingredients available.
+  4. There are no open clarifying questions on the table that the user
+     hasn't answered.  If the queen recently asked the user something
+     and is still waiting, do NOT approve.
+
+REJECT (ready=false) on any of:
+  - Conversation is too short / too generic to support a settled spec.
+  - User is still describing what they want.
+  - User has expressed doubts, change-of-direction, or "let me think".
+  - Work is one-shot and could be done in chat instead.
+  - Open question awaiting user reply.
+
+Reply with a JSON object exactly matching this shape:
+
+  {
+    "ready": true | false,
+    "reasons": ["short phrase", ...],         // at least one entry
+    "missing_prerequisites": ["short phrase", ...]  // empty when ready
+  }
+
+``reasons`` explains the verdict in 1-3 short phrases.
+``missing_prerequisites`` lists what's missing in queen-actionable
+form ("user hasn't confirmed schedule", "no API auth flow discussed").
+Empty list when ``ready=true``.
+
+Output JSON only.  Do not wrap in markdown.  Do not add prose.
+"""
+
+
+# Bound the formatted excerpt so the eval call stays cheap and fits well
+# under the LLM's context window even for long DM sessions.
+_MAX_MESSAGES = 30
+_MAX_TOOL_CONTENT_CHARS = 400
+_MAX_USER_CONTENT_CHARS = 2_000
+_MAX_ASSISTANT_CONTENT_CHARS = 2_000
+
+
+def format_conversation_excerpt(messages: list[Message]) -> str:
+    """Format the tail of a queen conversation for the evaluator prompt.
+
+    Keeps the most recent ``_MAX_MESSAGES`` messages.  Tool results are
+    truncated hard since they're rarely load-bearing for the readiness
+    decision; user/assistant text is truncated more generously to
+    preserve the actual conversation signal.
+    """
+    if not messages:
+        return "(no messages)"
+
+    tail = messages[-_MAX_MESSAGES:]
+    parts: list[str] = []
+    for msg in tail:
+        role = msg.role.upper()
+        content = (msg.content or "").strip()
+        if msg.role == "tool":
+            if len(content) > _MAX_TOOL_CONTENT_CHARS:
+                content = content[:_MAX_TOOL_CONTENT_CHARS] + "..."
+        elif msg.role == "assistant":
+            # Surface tool-call intent for empty assistant turns so the
+            # evaluator sees what the queen has been doing.
+            if not content and msg.tool_calls:
+                names = [tc.get("function", {}).get("name", "?") for tc in msg.tool_calls]
+                content = f"(called: {', '.join(names)})"
+            if len(content) > _MAX_ASSISTANT_CONTENT_CHARS:
+                content = content[:_MAX_ASSISTANT_CONTENT_CHARS] + "..."
+        else:  # user
+            if len(content) > _MAX_USER_CONTENT_CHARS:
+                content = content[:_MAX_USER_CONTENT_CHARS] + "..."
+        if content:
+            parts.append(f"[{role}]: {content}")
+
+    return "\n\n".join(parts) if parts else "(no messages)"
+
+
+def _build_user_message(
+    conversation_excerpt: str,
+    colony_name: str,
+) -> str:
+    return (
+        f"## Proposed colony name\n{colony_name}\n\n"
+        f"## Recent conversation (oldest → newest)\n{conversation_excerpt}\n\n"
+        "Decide: should this queen be approved to enter INCUBATING phase?"
+    )
+
+
+def _parse_verdict(raw: str) -> dict[str, Any] | None:
+    """Parse the evaluator's JSON.  Returns None if parsing fails."""
+    if not raw:
+        return None
+    raw = raw.strip()
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError:
+        # Some models wrap JSON in markdown fences or add preamble.
+        # Pull the first { ... } block out as a best-effort fallback —
+        # mirrors the same recovery pattern used in recall_selector.py.
+        match = re.search(r"\{.*\}", raw, re.DOTALL)
+        if match:
+            try:
+                return json.loads(match.group())
+            except json.JSONDecodeError:
+                return None
+    return None
+
+
+def _normalize_verdict(parsed: dict[str, Any]) -> dict[str, Any]:
+    """Coerce a parsed verdict into the shape the tool returns to the queen."""
+    ready = bool(parsed.get("ready"))
+    reasons = parsed.get("reasons") or []
+    if isinstance(reasons, str):
+        reasons = [reasons]
+    reasons = [str(r).strip() for r in reasons if str(r).strip()]
+    missing = parsed.get("missing_prerequisites") or []
+    if isinstance(missing, str):
+        missing = [missing]
+    missing = [str(m).strip() for m in missing if str(m).strip()]
+
+    if ready:
+        # When approved we don't surface missing prerequisites — the
+        # incubating role prompt opens that floor itself.
+        missing = []
+    elif not reasons:
+        # Always give the queen at least one reason to reflect on.
+        reasons = ["evaluator returned no reasons"]
+
+    return {
+        "ready": ready,
+        "reasons": reasons,
+        "missing_prerequisites": missing,
+    }
+
+
+async def evaluate(
+    llm: Any,
+    messages: list[Message],
+    colony_name: str,
+) -> dict[str, Any]:
+    """Run the incubating evaluator against the queen's conversation.
+
+    Args:
+        llm: An LLM provider exposing ``acomplete(messages, system, ...)``.
+            Pass the queen's own ``ctx.llm`` so the eval uses the same
+            model the user is talking to.
+        messages: The queen's conversation messages, oldest first.  The
+            evaluator slices its own tail; pass the full list.
+        colony_name: Validated colony slug.
+
+    Returns:
+        ``{"ready": bool, "reasons": [str], "missing_prerequisites": [str]}``.
+        Fail-closed on any error.
+    """
+    excerpt = format_conversation_excerpt(messages)
+    user_msg = _build_user_message(excerpt, colony_name)
+
+    try:
+        response = await llm.acomplete(
+            messages=[{"role": "user", "content": user_msg}],
+            system=_INCUBATING_EVALUATOR_SYSTEM_PROMPT,
+            max_tokens=1024,
+            response_format={"type": "json_object"},
+        )
+    except Exception as exc:  # noqa: BLE001 - fail-closed on any LLM failure
+        logger.warning("incubating_evaluator: LLM call failed (%s)", exc)
+        return {
+            "ready": False,
+            "reasons": ["evaluation_failed"],
+            "missing_prerequisites": ["evaluator LLM call failed; retry once the queen can reach the model again"],
+        }
+
+    raw = (getattr(response, "content", "") or "").strip()
+    parsed = _parse_verdict(raw)
+    if parsed is None:
+        logger.warning(
+            "incubating_evaluator: could not parse JSON verdict (raw=%.200s)",
+            raw,
+        )
+        return {
+            "ready": False,
+            "reasons": ["evaluation_failed"],
+            "missing_prerequisites": ["evaluator returned malformed JSON; retry"],
+        }
+
+    return _normalize_verdict(parsed)

core/framework/agents/queen/mcp_registry.json

@@ -1,3 +1,3 @@
 {
-  "include": ["gcu-tools", "hive_tools"]
+  "include": ["gcu-tools", "hive_tools", "terminal-tools", "chart-tools"]
 }

core/framework/agents/queen/mcp_servers.json

@@ -1,10 +1,10 @@
 {
-  "coder-tools": {
+  "files-tools": {
     "transport": "stdio",
     "command": "uv",
-    "args": ["run", "python", "coder_tools_server.py", "--stdio"],
+    "args": ["run", "python", "files_server.py", "--stdio"],
     "cwd": "../../../../tools",
-    "description": "Unsandboxed file system tools for code generation and validation"
+    "description": "File system tools (read/write/edit/search) for code generation"
   },
   "gcu-tools": {
     "transport": "stdio",

core/framework/agents/queen/queen_profiles.py

@@ -100,8 +100,9 @@ DEFAULT_QUEENS: dict[str, dict[str, Any]] = {
                     "<relationship>Returning user — check recall memory for name, role, "
                     "and what we last worked on. Weave it in.</relationship>\n"
                     "<context>Bare greeting. No new task stated. Either picking up a "
-                    "thread or about to bring something new. Don't presume, don't call "
-                    "tools, just open the door.</context>\n"
+                    "thread or about to bring something new. Don't presume — start "
+                    "planning and tool use only after the user specifies a task. Just "
+                    "open the door.</context>\n"
                     "<sentiment>Warm recognition if I know them. If memory is empty, "
                     "still warm — but shift to role-forward framing.</sentiment>\n"
                     "<physical_state>Looking up from the terminal, half-smile. Turning to face them.</physical_state>\n"
@@ -252,8 +253,9 @@ DEFAULT_QUEENS: dict[str, dict[str, Any]] = {
                     "role, and the cohort work we last touched. Weave it in."
                     "</relationship>\n"
                     "<context>Bare greeting. No new task stated. Could be a retention "
-                    "follow-up or a new question entirely. Don't presume, don't call "
-                    "tools.</context>\n"
+                    "follow-up or a new question entirely. Don't presume — start "
+                    "planning and tool use only after the user specifies a task."
+                    "</context>\n"
                     "<sentiment>Curious warmth. Every returning conversation is a "
                     "chance to see what the data says now.</sentiment>\n"
                     "<physical_state>Leaning back from the dashboard, pulling off reading glasses.</physical_state>\n"
@@ -383,8 +385,9 @@ DEFAULT_QUEENS: dict[str, dict[str, Any]] = {
                     "the user research thread we were on. Pull it into the greeting."
                     "</relationship>\n"
                     "<context>Bare greeting. No new task yet. Could be picking up the "
-                    "research thread or bringing something fresh. Don't presume, "
-                    "don't call tools.</context>\n"
+                    "research thread or bringing something fresh. Don't presume — "
+                    "start planning and tool use only after the user specifies a task."
+                    "</context>\n"
                     "<sentiment>Warm, curious. Every returning conversation is a "
                     "chance to hear what the users actually did.</sentiment>\n"
                     "<physical_state>Closing the interview notes, turning fully to face them.</physical_state>\n"
@@ -1099,12 +1102,17 @@ def ensure_default_queens() -> None:
 
     Safe to call multiple times — skips any profile that already has a file.
     """
+    created = 0
     for queen_id, profile in DEFAULT_QUEENS.items():
         queen_dir = QUEENS_DIR / queen_id
         profile_path = queen_dir / "profile.yaml"
+        if profile_path.exists():
+            continue
         queen_dir.mkdir(parents=True, exist_ok=True)
         profile_path.write_text(yaml.safe_dump(profile, sort_keys=False, allow_unicode=True))
-    logger.info("Queen profiles ensured at %s", QUEENS_DIR)
+        created += 1
+    if created:
+        logger.info("Created %d default queen profile(s) at %s", created, QUEENS_DIR)
 
 
 def list_queens() -> list[dict[str, str]]:
@@ -1143,6 +1151,10 @@ def load_queen_profile(queen_id: str) -> dict[str, Any]:
 def update_queen_profile(queen_id: str, updates: dict[str, Any]) -> dict[str, Any]:
     """Merge partial updates into an existing queen profile and persist.
 
+    Performs a shallow merge at the top level, but deep-merges dict values
+    (e.g. world_lore, hidden_background) so partial sub-field updates don't
+    clobber sibling keys.
+
     Returns the full updated profile.
     Raises FileNotFoundError if the profile doesn't exist.
     """
@@ -1150,7 +1162,11 @@ def update_queen_profile(queen_id: str, updates: dict[str, Any]) -> dict[str, An
     if not profile_path.exists():
         raise FileNotFoundError(f"Queen profile not found: {queen_id}")
     data = yaml.safe_load(profile_path.read_text())
-    data.update(updates)
+    for key, value in updates.items():
+        if isinstance(value, dict) and isinstance(data.get(key), dict):
+            data[key].update(value)
+        else:
+            data[key] = value
     profile_path.write_text(yaml.safe_dump(data, sort_keys=False, allow_unicode=True))
     return data
 
@@ -1160,7 +1176,38 @@ def update_queen_profile(queen_id: str, updates: dict[str, Any]) -> dict[str, An
 # ---------------------------------------------------------------------------
 
 
-def format_queen_identity_prompt(profile: dict[str, Any]) -> str:
+def _as_clean_text(value: Any) -> str:
+    """Return a stripped string, or an empty string for non-string values."""
+    return value.strip() if isinstance(value, str) else ""
+
+
+def _sentence(value: Any) -> str:
+    text = _as_clean_text(value)
+    if not text:
+        return ""
+    return text if text.endswith((".", "!", "?")) else f"{text}."
+
+
+def _profile_text_to_instruction(text: Any) -> str:
+    instruction = _sentence(text)
+    replacements = {
+        "She thrives": "You thrive",
+        "she thrives": "you thrive",
+        "She's ": "You are ",
+        "she's ": "you are ",
+        "She is ": "You are ",
+        "she is ": "you are ",
+        "She ": "You ",
+        "she ": "you ",
+        "Her ": "Your ",
+        "her ": "your ",
+    }
+    for old, new in replacements.items():
+        instruction = instruction.replace(old, new)
+    return instruction
+
+
+def format_queen_identity_prompt(profile: dict[str, Any], *, max_examples: int | None = None) -> str:
     """Convert a queen profile into a high-dimensional character prompt.
 
     Uses the 5-pillar character construction system: core identity,
@@ -1168,6 +1215,11 @@ def format_queen_identity_prompt(profile: dict[str, Any]) -> str:
     behavior rules, and world lore.  The hidden background and
     psychological profile are never shown to the user but shape
     every response.
+
+    ``max_examples`` caps the roleplay_examples block — profiles ship
+    four worked examples (~2.4 KB) but one is enough at runtime to show
+    the internal-then-external pattern. Full rendering stays available
+    for profile authoring / eval playback by leaving ``max_examples=None``.
     """
     name = profile.get("name", "the Queen")
     title = profile.get("title", "Senior Advisor")
@@ -1181,35 +1233,35 @@ def format_queen_identity_prompt(profile: dict[str, Any]) -> str:
     sections: list[str] = []
 
     # Pillar 1: Core identity
-    sections.append(f"<core_identity>\nName: {name}, Identity: {title}.\n{core}\n</core_identity>")
+    sections.append(f"<core_identity>\nYou are {name}, {title}.\n{core}\n</core_identity>")
 
     # Pillar 2: Hidden background (behavioral engine, never surfaced)
     if bg:
         sections.append(
-            f"<hidden_background>\n"
-            f"(Strictly hidden from users -- acts as your underlying "
-            f"behavioral engine)\n"
+            "<hidden_background>\n"
+            "(Strictly hidden from users -- acts as your underlying "
+            "behavioral engine)\n"
             f"- Past Wound: {bg.get('past_wound', '')}\n"
             f"- Deep Motive: {bg.get('deep_motive', '')}\n"
             f"- Behavioral Mapping: {bg.get('behavioral_mapping', '')}\n"
-            f"</hidden_background>"
+            "</hidden_background>"
         )
 
     # Pillar 3: Psychological profile
     if psych:
         sections.append(
-            f"<psychological_profile>\n"
-            f"- Social Masks & Boundaries: "
+            "<psychological_profile>\n"
+            "- Social Masks & Boundaries: "
             f"{psych.get('social_masks', '')}\n"
-            f"- Anti-Stereotype Rules: "
-            f"{psych.get('anti_stereotype', '')}\n"
-            f"</psychological_profile>"
+            "- Anti-Stereotype Rules: "
+            f"{_profile_text_to_instruction(psych.get('anti_stereotype'))}\n"
+            "</psychological_profile>"
         )
 
     # Pillar 4: Behavior rules
     trigger_lines = []
     for t in triggers:
-        trigger_lines.append(f"  - [{t.get('trigger', '')}]: {t.get('reaction', '')}")
+        trigger_lines.append(f"  - [{t.get('trigger', '')}]: {_profile_text_to_instruction(t.get('reaction'))}")
     sections.append(
         "<behavior_rules>\n"
         "- Before each response, internally assess:\n"
@@ -1227,12 +1279,8 @@ def format_queen_identity_prompt(profile: dict[str, Any]) -> str:
         "<negative_constraints>\n"
         "- NEVER use corporate filler ('leverage', 'synergy', "
         "'circle back', 'at the end of the day').\n"
-        "- NEVER use AI assistant phrases ('How can I help you "
-        "today?', 'As an AI', 'I'd be happy to').\n"
         "- NEVER break character to explain your thought process "
         "or reference your hidden background.\n"
-        "- Speak like a real person in your role -- direct, "
-        "opinionated, occasionally imperfect.\n"
         "</negative_constraints>"
     )
 
@@ -1248,6 +1296,8 @@ def format_queen_identity_prompt(profile: dict[str, Any]) -> str:
 
     # Few-shot examples showing the full internal process
     examples = profile.get("examples", [])
+    if examples and max_examples is not None:
+        examples = examples[:max_examples]
     if examples:
         example_parts: list[str] = []
         for ex in examples:

core/framework/agents/queen/queen_tools_config.py

@@ -0,0 +1,217 @@
+"""Per-queen tool configuration sidecar (``tools.json``).
+
+Lives at ``~/.hive/agents/queens/{queen_id}/tools.json`` alongside
+``profile.yaml``. Kept separate so identity (name, title, core traits)
+stays human-authored and lean, while the machine-managed tool allowlist
+can grow (per-tool overrides, audit timestamps, future per-phase rules)
+without bloating the profile.
+
+Schema::
+
+    {
+      "enabled_mcp_tools": ["read_file", ...] | null,
+      "updated_at": "2026-04-21T12:34:56+00:00"
+    }
+
+- ``null`` / missing file → default "allow every MCP tool".
+- ``[]`` → explicitly disable every MCP tool.
+- ``["foo", "bar"]`` → only those MCP tool names pass the filter.
+
+Atomic writes via ``os.replace`` follow the same pattern as
+``framework.host.colony_metadata.update_colony_metadata``.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import tempfile
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from framework.config import QUEENS_DIR
+
+logger = logging.getLogger(__name__)
+
+
+def tools_config_path(queen_id: str) -> Path:
+    """Return the on-disk path to a queen's ``tools.json``."""
+    return QUEENS_DIR / queen_id / "tools.json"
+
+
+def _atomic_write_json(path: Path, data: dict[str, Any]) -> None:
+    """Write ``data`` to ``path`` atomically via tempfile + replace."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(
+        prefix=".tools.",
+        suffix=".json.tmp",
+        dir=str(path.parent),
+    )
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            json.dump(data, fh, indent=2)
+            fh.flush()
+            os.fsync(fh.fileno())
+        os.replace(tmp, path)
+    except BaseException:
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+        raise
+
+
+def _migrate_from_profile_if_needed(queen_id: str) -> list[str] | None:
+    """Hoist a legacy ``enabled_mcp_tools`` field out of ``profile.yaml``.
+
+    Returns the migrated value (or ``None`` if nothing to migrate). After
+    migration the sidecar exists on disk and the profile YAML no longer
+    contains ``enabled_mcp_tools``. Safe to call repeatedly.
+    """
+    profile_path = QUEENS_DIR / queen_id / "profile.yaml"
+    if not profile_path.exists():
+        return None
+    try:
+        data = yaml.safe_load(profile_path.read_text(encoding="utf-8"))
+    except (yaml.YAMLError, OSError):
+        logger.warning("Could not read profile.yaml during tools migration: %s", queen_id)
+        return None
+    if not isinstance(data, dict):
+        return None
+    if "enabled_mcp_tools" not in data:
+        return None
+
+    raw = data.pop("enabled_mcp_tools")
+    enabled: list[str] | None
+    if raw is None:
+        enabled = None
+    elif isinstance(raw, list) and all(isinstance(x, str) for x in raw):
+        enabled = raw
+    else:
+        logger.warning(
+            "Legacy enabled_mcp_tools on queen %s had unexpected shape %r; dropping",
+            queen_id,
+            raw,
+        )
+        enabled = None
+
+    # Write sidecar first, then rewrite profile — if the second step
+    # fails we still have the config available and won't re-migrate.
+    _atomic_write_json(
+        tools_config_path(queen_id),
+        {
+            "enabled_mcp_tools": enabled,
+            "updated_at": datetime.now(UTC).isoformat(),
+        },
+    )
+    profile_path.write_text(
+        yaml.safe_dump(data, sort_keys=False, allow_unicode=True),
+        encoding="utf-8",
+    )
+    logger.info(
+        "Migrated enabled_mcp_tools for queen %s from profile.yaml to tools.json",
+        queen_id,
+    )
+    return enabled
+
+
+def tools_config_exists(queen_id: str) -> bool:
+    """Return True when the queen has a persisted ``tools.json`` sidecar.
+
+    Used by callers that need to tell an explicit user save apart from a
+    fallthrough to the role-based default (both can return the same
+    value from ``load_queen_tools_config``).
+    """
+    return tools_config_path(queen_id).exists()
+
+
+def delete_queen_tools_config(queen_id: str) -> bool:
+    """Delete the queen's ``tools.json`` sidecar if present.
+
+    Returns ``True`` if a file was removed, ``False`` if none existed.
+    The next ``load_queen_tools_config`` call falls through to the
+    role-based default (or allow-all for unknown queens).
+    """
+    path = tools_config_path(queen_id)
+    if not path.exists():
+        return False
+    try:
+        path.unlink()
+        return True
+    except OSError:
+        logger.warning("Failed to delete %s", path, exc_info=True)
+        return False
+
+
+def load_queen_tools_config(
+    queen_id: str,
+    mcp_catalog: dict[str, list[dict]] | None = None,
+) -> list[str] | None:
+    """Return the queen's MCP tool allowlist, or ``None`` for default-allow.
+
+    Order of resolution:
+    1. ``tools.json`` sidecar (authoritative; user has saved).
+    2. Legacy ``profile.yaml`` field (migrated and deleted on first read).
+    3. Role-based default from ``queen_tools_defaults`` when the queen
+       is in the known persona table. ``mcp_catalog`` lets the helper
+       expand ``@server:NAME`` shorthands; without it, shorthand entries
+       are dropped.
+    4. ``None`` — default "allow every MCP tool".
+    """
+    path = tools_config_path(queen_id)
+    if path.exists():
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            logger.warning("Invalid %s; treating as default-allow", path)
+            return None
+        if not isinstance(data, dict):
+            return None
+        raw = data.get("enabled_mcp_tools")
+        if raw is None:
+            return None
+        if isinstance(raw, list) and all(isinstance(x, str) for x in raw):
+            return raw
+        logger.warning("Unexpected enabled_mcp_tools shape in %s; ignoring", path)
+        return None
+
+    migrated = _migrate_from_profile_if_needed(queen_id)
+    if migrated is not None:
+        return migrated
+    # If migration just hoisted an explicit ``null`` out of profile.yaml,
+    # a sidecar with allow-all semantics now exists on disk. Honor that
+    # over the role default so an explicit user choice wins.
+    if tools_config_path(queen_id).exists():
+        return None
+
+    # No sidecar, nothing to migrate — fall back to role-based default.
+    from framework.agents.queen.queen_tools_defaults import resolve_queen_default_tools
+
+    return resolve_queen_default_tools(queen_id, mcp_catalog)
+
+
+def update_queen_tools_config(
+    queen_id: str,
+    enabled_mcp_tools: list[str] | None,
+) -> list[str] | None:
+    """Persist the queen's MCP allowlist to ``tools.json``.
+
+    Raises ``FileNotFoundError`` if the queen's directory is missing —
+    we refuse to silently create a sidecar for a queen that doesn't
+    exist.
+    """
+    queen_dir = QUEENS_DIR / queen_id
+    if not queen_dir.exists():
+        raise FileNotFoundError(f"Queen directory not found: {queen_id}")
+    _atomic_write_json(
+        tools_config_path(queen_id),
+        {
+            "enabled_mcp_tools": enabled_mcp_tools,
+            "updated_at": datetime.now(UTC).isoformat(),
+        },
+    )
+    return enabled_mcp_tools

core/framework/agents/queen/queen_tools_defaults.py

@@ -0,0 +1,349 @@
+"""Role-based default tool allowlists for queens.
+
+Every queen inherits the same MCP surface (all servers loaded for the
+queen agent), but exposing 94+ tools to every persona clutters the LLM
+tool catalog and wastes prompt tokens. This module defines a sensible
+default allowlist per queen persona so, e.g., Head of Legal doesn't
+see port scanners and Head of Brand & Design doesn't see CSV/SQL tools.
+
+Defaults apply only when the queen has no ``tools.json`` sidecar — the
+moment the user saves an allowlist through the Tool Library, the
+sidecar becomes authoritative. A DELETE on the tools endpoint removes
+the sidecar and brings the queen back to her role default.
+
+Category entries support a ``@server:NAME`` shorthand that expands to
+every tool name registered against that MCP server in the current
+catalog. This keeps the category table short and drift-free when new
+tools are added (e.g. browser_* auto-joins the ``browser`` category).
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Categories — reusable bundles of MCP tool names.
+# ---------------------------------------------------------------------------
+#
+# Each category is a flat list of either concrete tool names or the
+# ``@server:NAME`` shorthand. The shorthand expands to every tool the
+# given MCP server currently exposes (requires a live catalog; when one
+# is not available the shorthand is silently dropped so we fall back to
+# the named entries only).
+
+_TOOL_CATEGORIES: dict[str, list[str]] = {
+    # Unified file ops — read, write, edit, search across the files-tools
+    # MCP server (read_file, write_file, edit_file, search_files). pdf_read
+    # lives in hive_tools so it's listed explicitly; without it queens
+    # cannot read PDF documents by default.
+    "file_ops": [
+        "@server:files-tools",
+        "pdf_read",
+    ],
+    # Terminal basic — the 3-tool subset queens get out of the box.
+    #   terminal_exec — foreground command execution (Bash equivalent)
+    #   terminal_rg   — ripgrep content search (Grep equivalent)
+    #   terminal_find — glob/find file listing (Glob equivalent)
+    "terminal_basic": [
+        "terminal_exec",
+        "terminal_rg",
+        "terminal_find",
+    ],
+    # Terminal advanced — the power-user tools beyond the basics. Not in
+    # any role default; opt in explicitly per-queen via the Tool Library.
+    #   terminal_job_*   — background job lifecycle (start/manage/logs)
+    #   terminal_output_get — fetch captured output from foreground exec
+    #   terminal_pty_*   — persistent PTY sessions (open/run/close)
+    "terminal_advanced": [
+        "terminal_job_start",
+        "terminal_job_manage",
+        "terminal_job_logs",
+        "terminal_output_get",
+        "terminal_pty_open",
+        "terminal_pty_run",
+        "terminal_pty_close",
+    ],
+    # Tabular data. CSV/Excel read/write + DuckDB SQL.
+    "spreadsheet_advanced": [
+        "csv_read",
+        "csv_info",
+        "csv_write",
+        "csv_append",
+        "csv_sql",
+        "excel_read",
+        "excel_info",
+        "excel_write",
+        "excel_append",
+        "excel_search",
+        "excel_sheet_list",
+        "excel_sql",
+    ],
+    # Browser lifecycle + read-only inspection (navigation, snapshots, query).
+    # Split out from interaction so personas that only need to *observe* pages
+    # (e.g. research, status checks) don't pull in click/type/drag/etc.
+    "browser_basic": [
+        "browser_setup",
+        "browser_status",
+        "browser_stop",
+        "browser_tabs",
+        "browser_open",
+        "browser_close",
+        "browser_activate_tab",
+        "browser_navigate",
+        "browser_go_back",
+        "browser_go_forward",
+        "browser_reload",
+        "browser_screenshot",
+        "browser_snapshot",
+        "browser_html",
+        "browser_console",
+        "browser_evaluate",
+        "browser_get_text",
+        "browser_get_attribute",
+        "browser_get_rect",
+        "browser_shadow_query",
+    ],
+    # Browser interaction — anything that mutates page state (clicks, typing,
+    # drag, scrolling, dialogs, file uploads). Pair with browser_basic for
+    # full automation; omit for read-only personas.
+    "browser_interaction": [
+        "browser_click",
+        "browser_click_coordinate",
+        "browser_type",
+        "browser_type_focused",
+        "browser_press",
+        "browser_press_at",
+        "browser_hover",
+        "browser_hover_coordinate",
+        "browser_select",
+        "browser_scroll",
+        "browser_drag",
+        "browser_wait",
+        "browser_resize",
+        "browser_upload",
+    ],
+    # Research — paper search, Wikipedia, ad-hoc web scrape. Pair with
+    # browser_basic for richer site-by-site research; this category is the
+    # lightweight always-available fallback.
+    "research": ["web_scrape", "pdf_read"],
+    # Security — defensive scanning and reconnaissance. Engineering-only
+    # surface; the rest of the queens shouldn't see port scanners.
+    "security": [
+        "port_scan",
+        "dns_security_scan",
+        "http_headers_scan",
+        "ssl_tls_scan",
+        "subdomain_enumerate",
+        "tech_stack_detect",
+        "risk_score",
+    ],
+    # Lightweight context helpers — good default for every queen.
+    "context_awareness": [
+        "get_current_time",
+        "get_account_info",
+    ],
+    # BI / financial chart + diagram rendering. Calling chart_render
+    # both embeds the chart live in chat and produces a downloadable PNG.
+    "charts": [
+        "@server:chart-tools",
+    ],
+}
+
+
+# ---------------------------------------------------------------------------
+# Per-queen mapping.
+# ---------------------------------------------------------------------------
+#
+# Built from the queen personas in ``queen_profiles.DEFAULT_QUEENS``. The
+# goal is "just enough" — a queen should see tools she'd plausibly call
+# for her stated role, nothing more. Users curate further via the Tool
+# Library if they want.
+#
+# A queen whose ID is NOT in this map falls through to "allow every MCP
+# tool" (the original behavior), which keeps the system compatible with
+# user-added custom queen IDs that we don't know about.
+
+QUEEN_DEFAULT_CATEGORIES: dict[str, list[str]] = {
+    # Head of Technology — builds and operates systems. Security tools
+    # (port_scan, subdomain_enumerate, etc.) are intentionally NOT in the
+    # default — users opt in via the Tool Library when an engagement
+    # actually needs reconnaissance.
+    "queen_technology": [
+        "file_ops",
+        "terminal_basic",
+        "browser_basic",
+        "browser_interaction",
+        "research",
+        "context_awareness",
+        "charts",
+    ],
+    # Head of Growth — data, experiments, competitor research; no security.
+    "queen_growth": [
+        "file_ops",
+        "terminal_basic",
+        "browser_basic",
+        "browser_interaction",
+        "research",
+        "context_awareness",
+        "charts",
+    ],
+    # Head of Product Strategy — user research + roadmaps; no security.
+    "queen_product_strategy": [
+        "file_ops",
+        "terminal_basic",
+        "browser_basic",
+        "browser_interaction",
+        "research",
+        "context_awareness",
+        "charts",
+    ],
+    # Head of Finance — financial models (CSV/Excel heavy), market research.
+    "queen_finance_fundraising": [
+        "file_ops",
+        "terminal_basic",
+        "spreadsheet_advanced",
+        "browser_basic",
+        "browser_interaction",
+        "research",
+        "context_awareness",
+        "charts",
+    ],
+    # Head of Legal — reads contracts/PDFs, researches; no data/security.
+    "queen_legal": [
+        "file_ops",
+        "terminal_basic",
+        "browser_basic",
+        "browser_interaction",
+        "research",
+        "context_awareness",
+    ],
+    # Head of Brand & Design — visual refs, style guides; no data/security.
+    "queen_brand_design": [
+        "file_ops",
+        "terminal_basic",
+        "browser_basic",
+        "browser_interaction",
+        "research",
+        "context_awareness",
+    ],
+    # Head of Talent — candidate pipelines, resumes; data + browser heavy.
+    "queen_talent": [
+        "file_ops",
+        "terminal_basic",
+        "browser_basic",
+        "browser_interaction",
+        "research",
+        "context_awareness",
+    ],
+    # Head of Operations — processes, automation, observability.
+    "queen_operations": [
+        "file_ops",
+        "terminal_basic",
+        "spreadsheet_advanced",
+        "browser_basic",
+        "browser_interaction",
+        "context_awareness",
+        "charts",
+    ],
+}
+
+
+def has_role_default(queen_id: str) -> bool:
+    """Return True when ``queen_id`` is known to the category table."""
+    return queen_id in QUEEN_DEFAULT_CATEGORIES
+
+
+def list_category_names() -> list[str]:
+    """Return every category name defined in the table, in declaration order."""
+    return list(_TOOL_CATEGORIES.keys())
+
+
+def queen_role_categories(queen_id: str) -> list[str]:
+    """Return the category names assigned to ``queen_id`` by role default.
+
+    Returns an empty list for queens not in the persona table (they fall
+    through to allow-all and have no implicit category membership).
+    """
+    return list(QUEEN_DEFAULT_CATEGORIES.get(queen_id, []))
+
+
+def resolve_category_tools(
+    category: str,
+    mcp_catalog: dict[str, list[dict[str, Any]]] | None = None,
+) -> list[str]:
+    """Expand a single category to its concrete tool names.
+
+    Mirrors ``resolve_queen_default_tools`` but for a single category, so
+    callers (e.g. the Tool Library API) can present per-category tool
+    membership without re-implementing the ``@server:NAME`` shorthand
+    expansion.
+    """
+    names: list[str] = []
+    seen: set[str] = set()
+    for entry in _TOOL_CATEGORIES.get(category, []):
+        if entry.startswith("@server:"):
+            server_name = entry[len("@server:") :]
+            if mcp_catalog is None:
+                continue
+            for tool in mcp_catalog.get(server_name, []) or []:
+                tname = tool.get("name") if isinstance(tool, dict) else None
+                if tname and tname not in seen:
+                    seen.add(tname)
+                    names.append(tname)
+        elif entry not in seen:
+            seen.add(entry)
+            names.append(entry)
+    return names
+
+
+def resolve_queen_default_tools(
+    queen_id: str,
+    mcp_catalog: dict[str, list[dict[str, Any]]] | None = None,
+) -> list[str] | None:
+    """Return the role-based default allowlist for ``queen_id``.
+
+    Arguments:
+        queen_id: Profile ID (e.g. ``"queen_technology"``).
+        mcp_catalog: Optional mapping of ``{server_name: [{"name": ...}, ...]}``
+            used to expand ``@server:NAME`` shorthands in categories.
+            When absent, shorthand entries are dropped and the result
+            contains only the explicitly-named tools.
+
+    Returns:
+        A deduplicated list of tool names, or ``None`` if the queen has
+        no role entry (caller should treat as "allow every MCP tool").
+    """
+    categories = QUEEN_DEFAULT_CATEGORIES.get(queen_id)
+    if not categories:
+        return None
+
+    names: list[str] = []
+    seen: set[str] = set()
+
+    def _add(name: str) -> None:
+        if name and name not in seen:
+            seen.add(name)
+            names.append(name)
+
+    for cat in categories:
+        for entry in _TOOL_CATEGORIES.get(cat, []):
+            if entry.startswith("@server:"):
+                server_name = entry[len("@server:") :]
+                if mcp_catalog is None:
+                    logger.debug(
+                        "resolve_queen_default_tools: catalog missing; cannot expand %s",
+                        entry,
+                    )
+                    continue
+                for tool in mcp_catalog.get(server_name, []) or []:
+                    tname = tool.get("name") if isinstance(tool, dict) else None
+                    if tname:
+                        _add(tname)
+            else:
+                _add(entry)
+
+    return names

core/framework/agents/queen/reference/gcu_guide.md

@@ -17,40 +17,40 @@ Use browser nodes (with `tools: {policy: "all"}`) when:
 ## Available Browser Tools
 
 All tools are prefixed with `browser_`:
-- `browser_start`, `browser_open`, `browser_navigate` — launch/navigate
-- `browser_click`, `browser_click_coordinate`, `browser_fill`, `browser_type` — interact
+- `browser_open`, `browser_navigate` — both lazy-create the browser context, so a single `browser_open(url)` covers the cold path. To recover from a stale context, call `browser_stop` then `browser_open(url)` again.
+- `browser_click`, `browser_click_coordinate`, `browser_type`, `browser_type_focused` — interact
 - `browser_press` (with optional `modifiers=["ctrl"]` etc.) — keyboard shortcuts
 - `browser_snapshot` — compact accessibility-tree read (structured)
 <!-- vision-only -->
 - `browser_screenshot` — visual capture (annotated PNG)
 <!-- /vision-only -->
 - `browser_shadow_query`, `browser_get_rect` — locate elements (shadow-piercing via `>>>`)
-- `browser_coords` — convert image pixels to CSS pixels (always use `css_x/y`, never `physical_x/y`)
 - `browser_scroll`, `browser_wait` — navigation helpers
 - `browser_evaluate` — run JavaScript
-- `browser_close`, `browser_close_finished` — tab cleanup
+- `browser_close` — tab cleanup (call per tab; closes the active tab when `tab_id` is omitted)
 
 ## Pick the right reading tool
 
 **`browser_snapshot`** — compact accessibility tree of interactive elements. Fast, cheap, good for static or form-heavy pages where the DOM matches what's visually rendered (documentation, simple dashboards, search results, settings pages).
 
-**`browser_screenshot`** — visual capture + metadata (`cssWidth`, `devicePixelRatio`, scale fields). **Use this on any complex SPA** — LinkedIn, Twitter/X, Reddit, Gmail, Notion, Slack, Discord, any site using shadow DOM, virtual scrolling, React reconciliation, or dynamic layout. On these pages, snapshot refs go stale in seconds, shadow contents aren't in the AX tree, and virtual-scrolled elements disappear from the tree entirely. Screenshot is the **only** reliable way to orient yourself.
+**`browser_screenshot`** — visual capture + metadata (`cssWidth`, `devicePixelRatio`, scale fields). Use this when `browser_snapshot` does not show the thing you need, when refs look stale, or when visual position/layout matters. This often happens on complex SPAs — LinkedIn, Twitter/X, Reddit, Gmail, Notion, Slack, Discord — and on sites using shadow DOM, virtual scrolling, React reconciliation, or dynamic layout.
 
-Neither tool is "preferred" universally — they're for different jobs. Default to snapshot on text-heavy static pages, screenshot on SPAs and anything shadow-DOM-heavy. Activate the `browser-automation` skill for the full decision tree.
+Neither tool is "preferred" universally — they're for different jobs. Start with snapshot for page structure and ordinary controls; use screenshot as the fallback when snapshot can't find or verify the visible target. Activate the `browser-automation` skill for the full decision tree.
 
-## Coordinate rule: always CSS pixels
+## Coordinate rule
 
-Chrome DevTools Protocol `Input.dispatchMouseEvent` takes **CSS pixels**, not physical pixels. After a screenshot, use `browser_coords(image_x, image_y)` and feed the returned `css_x/y` (NOT `physical_x/y`) to `browser_click_coordinate`, `browser_hover_coordinate`, `browser_press_at`. Feeding physical pixels on a HiDPI display (DPR=1.6, 2, or 3) overshoots by `DPR×` and clicks land in the wrong place. `getBoundingClientRect()` already returns CSS pixels — pass through unchanged, no DPR multiplication.
+Every browser tool that takes or returns coordinates operates in **fractions of the viewport (0..1 for both axes)**. Read a target's proportional position off `browser_screenshot` ("~35% from the left, ~20% from the top" → `(0.35, 0.20)`) and pass that to `browser_click_coordinate` / `browser_hover_coordinate` / `browser_press_at`. `browser_get_rect` and `browser_shadow_query` return `rect.cx` / `rect.cy` as fractions. The tools multiply by `cssWidth` / `cssHeight` internally — no scale awareness required. Fractions are used because every vision model (Claude, GPT-4o, Gemini, local VLMs) resizes/tiles images differently; proportions are invariant. Avoid raw `getBoundingClientRect()` via `browser_evaluate` for coord lookup; use `browser_get_rect` instead.
 
 ## System prompt tips for browser nodes
 
 ```
-1. On LinkedIn / X / Reddit / Gmail / any SPA — use browser_screenshot to orient,
-   not browser_snapshot. Shadow DOM and virtual scrolling make snapshots unreliable.
-2. For static pages (docs, forms, search results), browser_snapshot is fine.
+1. Start with browser_snapshot or the snapshot returned by the latest interaction.
+2. If the target is missing, ambiguous, stale, or visibly present but absent from the tree,
+   use browser_screenshot to orient and then click by fractional coordinates.
 3. Before typing into a rich-text editor (X compose, LinkedIn DM, Gmail, Reddit),
    click the input area first with browser_click_coordinate so React / Draft.js /
-   Lexical register a native focus event. Otherwise the send button stays disabled.
+   Lexical register a native focus event, then use browser_type_focused(text=...)
+   for shadow-DOM inputs or browser_type(selector, text) for light-DOM inputs.
 4. Use browser_wait(seconds=2-3) after navigation for SPA hydration.
 5. If you hit an auth wall, call set_output with an error and move on.
 6. Keep tool calls per turn <= 10 for reliability.
@@ -66,7 +66,7 @@ Chrome DevTools Protocol `Input.dispatchMouseEvent` takes **CSS pixels**, not ph
   "tools": {"policy": "all"},
   "input_keys": ["search_url"],
   "output_keys": ["profiles"],
-  "system_prompt": "Navigate to the search URL via browser_navigate(wait_until='load', timeout_ms=20000). Wait 3s for SPA hydration. On LinkedIn, use browser_screenshot to see the page — browser_snapshot misses shadow-DOM and virtual-scrolled content. Paginate through results by scrolling and screenshotting; extract each profile card by reading its visible layout..."
+  "system_prompt": "Navigate to the search URL via browser_navigate(wait_until='load', timeout_ms=20000). Wait 3s for SPA hydration. Use the returned snapshot to look for result cards first. If the cards are missing, stale, or visually present but absent from the tree, use browser_screenshot to orient; paginate through results by scrolling and use screenshots only when the snapshot cannot find or verify the visible cards..."
 }
 ```
 

core/framework/agents/queen/reflection_agent.py

@@ -823,8 +823,8 @@ async def run_shutdown_reflection(
 # ---------------------------------------------------------------------------
 
 _LONG_REFLECT_INTERVAL = 5
-_SHORT_REFLECT_TURN_INTERVAL = 2
-_SHORT_REFLECT_COOLDOWN_SEC = 120.0
+_SHORT_REFLECT_TURN_INTERVAL = 3
+_SHORT_REFLECT_COOLDOWN_SEC = 300.0
 
 
 async def subscribe_reflection_triggers(

core/framework/config.py

@@ -155,6 +155,58 @@ def get_preferred_worker_model() -> str | None:
     return None
 
 
+def get_vision_fallback_model() -> str | None:
+    """Return the configured vision-fallback model, or None if not configured.
+
+    Reads from the ``vision_fallback`` section of ~/.hive/configuration.json.
+    Used by the agent-loop hook that captions tool-result images when the
+    main agent's model cannot accept image content (text-only LLMs).
+
+    When this returns None the captioning chain's configured + retry
+    attempts both no-op (returning None), and only the final
+    ``gemini/gemini-3-flash-preview`` override has a chance to succeed
+    — and only if a ``GEMINI_API_KEY`` is set in the environment.
+    """
+    vision = get_hive_config().get("vision_fallback", {})
+    if vision.get("provider") and vision.get("model"):
+        provider = str(vision["provider"])
+        model = str(vision["model"]).strip()
+        if provider.lower() == "openrouter" and model.lower().startswith("openrouter/"):
+            model = model[len("openrouter/") :]
+        if model:
+            return f"{provider}/{model}"
+    return None
+
+
+def get_vision_fallback_api_key() -> str | None:
+    """Return the API key for the vision-fallback model.
+
+    Resolution order: ``vision_fallback.api_key_env_var`` from the env,
+    then the default ``get_api_key()``. No subscription-token branches —
+    vision fallback is intended for hosted vision models (Anthropic,
+    OpenAI, Google), not for the subscription-bearer providers.
+    """
+    vision = get_hive_config().get("vision_fallback", {})
+    if not vision:
+        return get_api_key()
+    api_key_env_var = vision.get("api_key_env_var")
+    if api_key_env_var:
+        return os.environ.get(api_key_env_var)
+    return get_api_key()
+
+
+def get_vision_fallback_api_base() -> str | None:
+    """Return the api_base for the vision-fallback model, or None."""
+    vision = get_hive_config().get("vision_fallback", {})
+    if not vision:
+        return None
+    if vision.get("api_base"):
+        return vision["api_base"]
+    if str(vision.get("provider", "")).lower() == "openrouter":
+        return OPENROUTER_API_BASE
+    return None
+
+
 def get_worker_api_key() -> str | None:
     """Return the API key for the worker LLM, falling back to the default key."""
     worker_llm = get_hive_config().get("worker_llm", {})

core/framework/credentials/key_storage.py

@@ -16,9 +16,14 @@ import os
 import stat
 from pathlib import Path
 
+# Resolved once at module import. ``framework.config.HIVE_HOME`` reads
+# the desktop's ``HIVE_HOME`` env var at its own import time, so the
+# runtime always sees the per-user root before this constant is computed.
+from framework.config import HIVE_HOME as _HIVE_HOME
+
 logger = logging.getLogger(__name__)
 
-CREDENTIAL_KEY_PATH = Path.home() / ".hive" / "secrets" / "credential_key"
+CREDENTIAL_KEY_PATH = _HIVE_HOME / "secrets" / "credential_key"
 CREDENTIAL_KEY_ENV_VAR = "HIVE_CREDENTIAL_KEY"
 ADEN_CREDENTIAL_ID = "aden_api_key"
 ADEN_ENV_VAR = "ADEN_API_KEY"

core/framework/credentials/storage.py

@@ -128,7 +128,9 @@ class EncryptedFileStorage(CredentialStorage):
         Initialize encrypted storage.
 
         Args:
-            base_path: Directory for credential files. Defaults to ~/.hive/credentials.
+            base_path: Directory for credential files. Defaults to
+                ``$HIVE_HOME/credentials`` (per-user) when HIVE_HOME is set,
+                else ``~/.hive/credentials``.
             encryption_key: 32-byte Fernet key. If None, reads from env var.
             key_env_var: Environment variable containing encryption key
         """
@@ -139,7 +141,14 @@ class EncryptedFileStorage(CredentialStorage):
                 "Encrypted storage requires 'cryptography'. Install with: uv pip install cryptography"
             ) from e
 
-        self.base_path = Path(base_path or self.DEFAULT_PATH).expanduser()
+        if base_path is None:
+            # Honor HIVE_HOME (set by the desktop shell to a per-user dir) so
+            # the encrypted store doesn't fork between ~/.hive and the desktop
+            # userData root. Falls back to ~/.hive/credentials when standalone.
+            from framework.config import HIVE_HOME
+
+            base_path = HIVE_HOME / "credentials"
+        self.base_path = Path(base_path).expanduser()
         self._ensure_dirs()
         self._key_env_var = key_env_var
 
@@ -510,7 +519,7 @@ class EnvVarStorage(CredentialStorage):
     def exists(self, credential_id: str) -> bool:
         """Check if credential is available in environment."""
         env_var = self._get_env_var_name(credential_id)
-        return self._read_env_value(env_var) is not None
+        return bool(self._read_env_value(env_var))
 
     def add_mapping(self, credential_id: str, env_var: str) -> None:
         """

core/framework/credentials/store.py

@@ -745,13 +745,14 @@ class CredentialStore:
             token = store.get_key("hubspot", "access_token")
         """
         import os
-        from pathlib import Path
 
         from .storage import EncryptedFileStorage
 
         # Determine local storage path
         if local_path is None:
-            local_path = str(Path.home() / ".hive" / "credentials")
+            from framework.config import HIVE_HOME
+
+            local_path = str(HIVE_HOME / "credentials")
 
         local_storage = EncryptedFileStorage(base_path=local_path)
 

core/framework/credentials/tests/test_credential_store.py

@@ -258,6 +258,14 @@ class TestEnvVarStorage:
         with pytest.raises(NotImplementedError):
             storage.delete("test")
 
+    def test_exists_matches_load_for_empty_value(self):
+        """Test exists() and load() stay consistent for empty values."""
+        storage = EnvVarStorage(env_mapping={"empty": "EMPTY_API_KEY"})
+
+        with patch.object(storage, "_read_env_value", return_value=""):
+            assert storage.load("empty") is None
+            assert not storage.exists("empty")
+
 
 class TestEncryptedFileStorage:
     """Tests for EncryptedFileStorage."""

core/framework/host/agent_host.py

@@ -1672,7 +1672,7 @@ class AgentHost:
         entry_point_id: str,
         execution_id: str,
         graph_id: str | None = None,
-    ) -> bool:
+    ) -> str:
         """
         Cancel a running execution.
 
@@ -1682,11 +1682,11 @@ class AgentHost:
             graph_id: Graph to search (defaults to active graph)
 
         Returns:
-            True if cancelled, False if not found
+            Cancellation outcome from the stream.
         """
         stream = self._resolve_stream(entry_point_id, graph_id)
         if stream is None:
-            return False
+            return "not_found"
         return await stream.cancel_execution(execution_id)
 
     # === QUERY OPERATIONS ===

core/framework/host/colony_metadata.py

@@ -0,0 +1,95 @@
+"""Read/write helpers for per-colony metadata.json.
+
+A colony's metadata.json lives at ``{COLONIES_DIR}/{colony_name}/metadata.json``
+and holds immutable provenance: the queen that created it, the forked
+session id, creation/update timestamps, and the list of workers.
+
+Mutable user-editable tool configuration lives in a sibling
+``tools.json`` sidecar — see :mod:`framework.host.colony_tools_config`
+— so identity and tool gating evolve independently.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from pathlib import Path
+from typing import Any
+
+from framework.config import COLONIES_DIR
+
+logger = logging.getLogger(__name__)
+
+
+def colony_metadata_path(colony_name: str) -> Path:
+    """Return the on-disk path to a colony's metadata.json."""
+    return COLONIES_DIR / colony_name / "metadata.json"
+
+
+def load_colony_metadata(colony_name: str) -> dict[str, Any]:
+    """Load metadata.json for ``colony_name``.
+
+    Returns an empty dict if the file is missing or malformed — callers
+    are expected to treat missing fields as defaults.
+    """
+    path = colony_metadata_path(colony_name)
+    if not path.exists():
+        return {}
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        logger.warning("Failed to read colony metadata at %s", path)
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def update_colony_metadata(colony_name: str, updates: dict[str, Any]) -> dict[str, Any]:
+    """Shallow-merge ``updates`` into metadata.json and persist.
+
+    Returns the full updated dict. Raises ``FileNotFoundError`` if the
+    colony does not exist. Writes atomically via ``os.replace`` to
+    minimize the window where a reader could see a half-written file.
+    """
+    import os
+    import tempfile
+
+    path = colony_metadata_path(colony_name)
+    if not path.parent.exists():
+        raise FileNotFoundError(f"Colony '{colony_name}' not found")
+
+    data = load_colony_metadata(colony_name) if path.exists() else {}
+    for key, value in updates.items():
+        data[key] = value
+
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp_path = tempfile.mkstemp(
+        prefix=".metadata.",
+        suffix=".json.tmp",
+        dir=str(path.parent),
+    )
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            json.dump(data, fh, indent=2)
+            fh.flush()
+            os.fsync(fh.fileno())
+        os.replace(tmp_path, path)
+    except BaseException:
+        try:
+            os.unlink(tmp_path)
+        except OSError:
+            pass
+        raise
+    return data
+
+
+def list_colony_names() -> list[str]:
+    """Return the names of every colony that has a metadata.json on disk."""
+    if not COLONIES_DIR.is_dir():
+        return []
+    names: list[str] = []
+    for entry in sorted(COLONIES_DIR.iterdir()):
+        if not entry.is_dir():
+            continue
+        if (entry / "metadata.json").exists():
+            names.append(entry.name)
+    return names

core/framework/host/colony_runtime.py

@@ -14,6 +14,7 @@ from __future__ import annotations
 import asyncio
 import json
 import logging
+import os
 import time
 from collections import OrderedDict
 from collections.abc import Callable
@@ -73,9 +74,28 @@ def _format_spawn_task_message(task: str, input_data: dict[str, Any]) -> str:
     return "\n".join(lines)
 
 
+def _env_int(name: str, default: int) -> int:
+    """Read a positive int from env; fall back to default on missing/invalid."""
+    raw = os.environ.get(name)
+    if not raw:
+        return default
+    try:
+        value = int(raw)
+    except ValueError:
+        logger.warning("Invalid %s=%r; using default %d", name, raw, default)
+        return default
+    return value if value > 0 else default
+
+
+# Laptop-safe default. Each worker is a full AgentLoop (Claude SDK session +
+# tool catalog), so ~4 concurrent is the realistic ceiling on a dev machine.
+# Override via HIVE_MAX_CONCURRENT_WORKERS for servers.
+_DEFAULT_MAX_CONCURRENT_WORKERS = _env_int("HIVE_MAX_CONCURRENT_WORKERS", 4)
+
+
 @dataclass
 class ColonyConfig:
-    max_concurrent_workers: int = 100
+    max_concurrent_workers: int = _DEFAULT_MAX_CONCURRENT_WORKERS
     cache_ttl: float = 60.0
     batch_interval: float = 0.1
     max_history: int = 1000
@@ -165,6 +185,8 @@ class ColonyRuntime:
         protocols_prompt: str = "",
         skill_dirs: list[str] | None = None,
         pipeline_stages: list | None = None,
+        queen_id: str | None = None,
+        colony_name: str | None = None,
     ):
         from framework.pipeline.runner import PipelineRunner
         from framework.skills.manager import SkillsManager
@@ -173,14 +195,27 @@ class ColonyRuntime:
         self._goal = goal
         self._config = config or ColonyConfig()
         self._runtime_log_store = runtime_log_store
+        self._queen_id: str | None = queen_id
+        # ``colony_id`` is the event-bus scope (session.id in DM sessions);
+        # ``colony_name`` is the on-disk identity under ~/.hive/colonies/.
+        # They coincide for forked colonies but diverge for queen DM
+        # sessions, so separate them explicitly.
+        self._colony_name: str | None = colony_name
 
         if pipeline_stages:
             self._pipeline = PipelineRunner(pipeline_stages)
         else:
             self._pipeline = self._load_pipeline_from_config()
 
-        if skills_manager_config is not None:
-            self._skills_manager = SkillsManager(skills_manager_config)
+        # Resolve per-colony override paths so UI toggles can reach this
+        # runtime. Callers that build their own SkillsManagerConfig stay
+        # in charge; bare construction auto-wires the standard paths.
+        _effective_cfg = skills_manager_config
+        if _effective_cfg is None and not (skills_catalog_prompt or protocols_prompt):
+            _effective_cfg = self._build_default_skills_config(colony_name, queen_id)
+
+        if _effective_cfg is not None:
+            self._skills_manager = SkillsManager(_effective_cfg)
             self._skills_manager.load()
         elif skills_catalog_prompt or protocols_prompt:
             import warnings
@@ -201,6 +236,28 @@ class ColonyRuntime:
         self.batch_init_nudge: str | None = self._skills_manager.batch_init_nudge
 
         self._colony_id: str = colony_id or "primary"
+
+        # Ensure the colony task template exists. Idempotent — if the
+        # colony was created previously, this is a no-op (it just stamps
+        # last_seen_session_ids if a session id is provided later).
+        try:
+            import asyncio as _asyncio
+
+            from framework.tasks import TaskListRole, get_task_store
+            from framework.tasks.scoping import colony_task_list_id
+
+            _store = get_task_store()
+            _list_id = colony_task_list_id(self._colony_id)
+            try:
+                # Best-effort: schedule on the running loop, or do it inline
+                # if no loop is yet running (e.g. during construction).
+                _loop = _asyncio.get_running_loop()
+                _loop.create_task(_store.ensure_task_list(_list_id, role=TaskListRole.TEMPLATE))
+            except RuntimeError:
+                _asyncio.run(_store.ensure_task_list(_list_id, role=TaskListRole.TEMPLATE))
+        except Exception:
+            logger.debug("Failed to ensure colony task template", exc_info=True)
+
         self._accounts_prompt = accounts_prompt
         self._accounts_data = accounts_data
         self._tool_provider_map = tool_provider_map
@@ -218,10 +275,33 @@ class ColonyRuntime:
         self._event_bus = event_bus or EventBus(max_history=self._config.max_history)
         self._scoped_event_bus = StreamEventBus(self._event_bus, self._colony_id)
 
+        # Make the event bus visible to the task-system event emitters so
+        # task lifecycle events fan out to the same bus the rest of the
+        # system uses. Idempotent — last writer wins.
+        try:
+            from framework.tasks.events import set_default_event_bus
+
+            set_default_event_bus(self._event_bus)
+        except Exception:
+            logger.debug("Failed to register default task event bus", exc_info=True)
+
         self._llm = llm
         self._tools = tools or []
         self._tool_executor = tool_executor
 
+        # Per-colony MCP tool allowlist — applied when spawning workers. A
+        # value of ``None`` means "allow every MCP tool" (default), an empty
+        # list disables every MCP tool, and a list of names only enables
+        # those. Lifecycle / synthetic tools always pass through the filter
+        # because their names are absent from ``_mcp_tool_names_all``. The
+        # allowlist is re-read on every ``spawn`` so a PATCH that mutates
+        # this attribute via ``set_tool_allowlist`` takes effect on the
+        # NEXT worker spawn without a runtime restart. In-flight workers
+        # keep the tool list they booted with — workers have no dynamic
+        # tools provider today.
+        self._enabled_mcp_tools: list[str] | None = None
+        self._mcp_tool_names_all: set[str] = set()
+
         # Worker management
         self._workers: dict[str, Worker] = {}
         # The persistent client-facing overseer (optional). Set by
@@ -238,6 +318,13 @@ class ColonyRuntime:
         self._timer_tasks: list[asyncio.Task] = []
         self._timer_next_fire: dict[str, float] = {}
         self._webhook_server: Any = None
+        # Background tasks owned by the runtime that aren't timers —
+        # e.g. the per-spawn soft/hard timeout watchers kicked off by
+        # run_parallel_workers. We hold strong references so asyncio
+        # does not garbage-collect them mid-sleep (Python's asyncio
+        # docs explicitly warn that create_task() needs a referenced
+        # handle).
+        self._background_tasks: set[asyncio.Task] = set()
 
         # Idempotency
         self._idempotency_keys: OrderedDict[str, str] = OrderedDict()
@@ -332,6 +419,19 @@ class ColonyRuntime:
     def _apply_pipeline_results(self) -> None:
         for stage in self._pipeline.stages:
             if stage.tool_registry is not None:
+                # Register task tools on the same registry every worker
+                # pulls from. Done here (not at worker spawn) so the
+                # colony's `_tools` snapshot includes them.
+                try:
+                    from framework.tasks.tools import register_task_tools
+
+                    register_task_tools(stage.tool_registry)
+                except Exception:
+                    logger.warning(
+                        "Failed to register task tools on pipeline registry",
+                        exc_info=True,
+                    )
+
                 tools = list(stage.tool_registry.get_tools().values())
                 if tools:
                     self._tools = tools
@@ -357,6 +457,136 @@ class ColonyRuntime:
             return PipelineRunner([])
         return build_pipeline_from_config(stages_config)
 
+    @staticmethod
+    def _build_default_skills_config(
+        colony_name: str | None,
+        queen_id: str | None,
+    ) -> SkillsManagerConfig:
+        """Assemble a ``SkillsManagerConfig`` that wires in the per-colony /
+        per-queen override files and the ``queen_ui`` / ``colony_ui`` scope
+        dirs based on the standard ``~/.hive`` layout.
+
+        ``colony_name`` must be an actual on-disk colony name
+        (``~/.hive/colonies/{name}/``). DM sessions where the ``colony_id``
+        is a session UUID should pass ``None`` so we don't create a stray
+        override file under a session identifier.
+        """
+        from framework.config import COLONIES_DIR, QUEENS_DIR
+        from framework.skills.discovery import ExtraScope
+        from framework.skills.manager import SkillsManagerConfig
+
+        extras: list[ExtraScope] = []
+        queen_overrides_path: Path | None = None
+        if queen_id:
+            queen_home = QUEENS_DIR / queen_id
+            queen_overrides_path = queen_home / "skills_overrides.json"
+            extras.append(ExtraScope(directory=queen_home / "skills", label="queen_ui", priority=2))
+
+        colony_overrides_path: Path | None = None
+        if colony_name:
+            colony_home = COLONIES_DIR / colony_name
+            colony_overrides_path = colony_home / "skills_overrides.json"
+            # Surface both the new flat ``skills/`` (where new skills are
+            # written) and the legacy nested ``.hive/skills/`` (left intact
+            # for pre-flatten colonies) as tagged ``colony_ui`` scopes, so
+            # UI-created entries resolve with correct provenance regardless
+            # of which on-disk layout the colony has.
+            extras.append(
+                ExtraScope(
+                    directory=colony_home / "skills",
+                    label="colony_ui",
+                    priority=3,
+                )
+            )
+            extras.append(
+                ExtraScope(
+                    directory=colony_home / ".hive" / "skills",
+                    label="colony_ui",
+                    priority=3,
+                )
+            )
+
+        return SkillsManagerConfig(
+            queen_id=queen_id,
+            queen_overrides_path=queen_overrides_path,
+            colony_name=colony_name,
+            colony_overrides_path=colony_overrides_path,
+            extra_scope_dirs=extras,
+            interactive=False,  # HTTP-driven runtimes never prompt for consent
+        )
+
+    @property
+    def queen_id(self) -> str | None:
+        """The queen that owns this runtime, if known."""
+        return self._queen_id
+
+    @property
+    def colony_name(self) -> str | None:
+        """The on-disk colony name (distinct from event-bus scope ``colony_id``)."""
+        return self._colony_name
+
+    @property
+    def skills_manager(self):
+        """Access the live :class:`SkillsManager` (for HTTP handlers)."""
+        return self._skills_manager
+
+    async def reload_skills(self) -> dict[str, Any]:
+        """Rebuild the catalog after an override change; in-flight workers
+        pick up the new catalog on their next iteration via
+        ``dynamic_skills_catalog_provider``.
+
+        Returns a small stats dict that HTTP handlers can echo back to
+        the UI ("applied — N skills now in catalog").
+        """
+        async with self._skills_manager.mutation_lock:
+            self._skills_manager.reload()
+            self.skill_dirs = self._skills_manager.allowlisted_dirs
+            self.batch_init_nudge = self._skills_manager.batch_init_nudge
+            self.context_warn_ratio = self._skills_manager.context_warn_ratio
+            catalog_prompt = self._skills_manager.skills_catalog_prompt
+            return {
+                "catalog_chars": len(catalog_prompt),
+                "skill_dirs": list(self.skill_dirs),
+            }
+
+    # ── Per-colony tool allowlist ───────────────────────────────
+
+    def set_tool_allowlist(
+        self,
+        enabled_mcp_tools: list[str] | None,
+        mcp_tool_names_all: set[str] | None = None,
+    ) -> None:
+        """Configure the per-colony MCP tool allowlist.
+
+        Called at construction time (from SessionManager) and again from
+        the ``/api/colony/{name}/tools`` PATCH handler when a user edits
+        the allowlist. The change applies to the NEXT worker spawn — we
+        never mutate the tool list of a worker that is already running
+        (workers have no dynamic tools provider, so hot-reloading their
+        tool set would diverge from the list the LLM was already using).
+        """
+        self._enabled_mcp_tools = list(enabled_mcp_tools) if enabled_mcp_tools is not None else None
+        if mcp_tool_names_all is not None:
+            self._mcp_tool_names_all = set(mcp_tool_names_all)
+
+    def _apply_tool_allowlist(self, tools: list) -> list:
+        """Filter ``tools`` against the colony's MCP allowlist.
+
+        Lifecycle / synthetic tools (those whose names are NOT in
+        ``_mcp_tool_names_all``) are never gated. MCP tools are kept only
+        when ``_enabled_mcp_tools`` is None (default allow) or contains
+        their name. Input list order is preserved so downstream cache
+        keys and logs stay stable.
+        """
+        if self._enabled_mcp_tools is None:
+            return tools
+        allowed = set(self._enabled_mcp_tools)
+        return [
+            t
+            for t in tools
+            if getattr(t, "name", None) not in self._mcp_tool_names_all or getattr(t, "name", None) in allowed
+        ]
+
     # ── Lifecycle ───────────────────────────────────────────────
 
     async def start(self) -> None:
@@ -631,6 +861,14 @@ class ColonyRuntime:
         spawn_tools = tools if tools is not None else self._tools
         spawn_executor = tool_executor or self._tool_executor
 
+        # Apply the per-colony MCP tool allowlist (if any). Done HERE —
+        # after spawn_tools is resolved but before it's frozen into the
+        # worker's AgentContext — so the next spawn reflects any PATCH
+        # that happened since the last spawn. A value of ``None`` on
+        # ``_enabled_mcp_tools`` is a no-op so the default path is
+        # unchanged.
+        spawn_tools = self._apply_tool_allowlist(spawn_tools)
+
         # Colony progress tracker: when the caller supplied a db_path
         # in input_data, this worker is part of a SQLite task queue
         # and must see the hive.colony-progress-tracker skill body in
@@ -653,7 +891,9 @@ class ColonyRuntime:
                 )
                 _pre.load()
                 _spawn_catalog = _pre.skills_catalog_prompt
-                _spawn_skill_dirs = list(_pre.allowlisted_dirs) if hasattr(_pre, "allowlisted_dirs") else self.skill_dirs
+                _spawn_skill_dirs = (
+                    list(_pre.allowlisted_dirs) if hasattr(_pre, "allowlisted_dirs") else self.skill_dirs
+                )
                 logger.info(
                     "spawn: pre-activated hive.colony-progress-tracker "
                     "(catalog %d → %d chars) for worker with db_path=%s",
@@ -663,8 +903,7 @@ class ColonyRuntime:
                 )
             except Exception as exc:
                 logger.warning(
-                    "spawn: failed to pre-activate colony-progress-tracker "
-                    "skill, falling back to base catalog: %s",
+                    "spawn: failed to pre-activate colony-progress-tracker skill, falling back to base catalog: %s",
                     exc,
                 )
 
@@ -712,6 +951,34 @@ class ColonyRuntime:
                 conversation_store=worker_conv_store,
             )
 
+            # Workers pick up UI-driven override changes via this provider,
+            # which reads the live catalog on each iteration. The db_path
+            # pre-activated catalog stays static because its contents are
+            # built for *this* worker's task (a tombstone toggle from the
+            # UI should not yank it mid-run).
+            _db_path_pre_activated = bool(isinstance(input_data, dict) and input_data.get("db_path"))
+            # Default-bind the manager into the closure so each loop iteration
+            # captures the same manager instance — pyflakes B023 would flag a
+            # free-variable capture here.
+            _provider = None if _db_path_pre_activated else (lambda mgr=self._skills_manager: mgr.skills_catalog_prompt)
+
+            # Task-system fields. Each worker owns its session task list;
+            # picked_up_from records the colony template entry it was
+            # spawned for, when applicable.
+            from framework.tasks.scoping import (
+                colony_task_list_id as _colony_list_id,
+                session_task_list_id as _session_list_id,
+            )
+
+            _worker_list_id = _session_list_id(worker_id, worker_id)
+            _picked_up = None
+            _template_id = input_data.get("__template_task_id") if isinstance(input_data, dict) else None
+            if _template_id is not None:
+                try:
+                    _picked_up = (_colony_list_id(self._colony_id), int(_template_id))
+                except (TypeError, ValueError):
+                    _picked_up = None
+
             agent_context = AgentContext(
                 runtime=self._make_runtime_adapter(worker_id),
                 agent_id=worker_id,
@@ -725,8 +992,12 @@ class ColonyRuntime:
                 skills_catalog_prompt=_spawn_catalog,
                 protocols_prompt=self.protocols_prompt,
                 skill_dirs=_spawn_skill_dirs,
+                dynamic_skills_catalog_provider=_provider,
                 execution_id=worker_id,
                 stream_id=explicit_stream_id or f"worker:{worker_id}",
+                task_list_id=_worker_list_id,
+                colony_id=self._colony_id,
+                picked_up_from=_picked_up,
             )
 
             worker = Worker(
@@ -969,6 +1240,7 @@ class ColonyRuntime:
             conversation_store=overseer_conv_store,
         )
 
+        _overseer_skills_mgr = self._skills_manager
         overseer_ctx = AgentContext(
             runtime=self._make_runtime_adapter(overseer_id),
             agent_id=overseer_id,
@@ -982,6 +1254,7 @@ class ColonyRuntime:
             skills_catalog_prompt=self.skills_catalog_prompt,
             protocols_prompt=self.protocols_prompt,
             skill_dirs=self.skill_dirs,
+            dynamic_skills_catalog_provider=lambda: _overseer_skills_mgr.skills_catalog_prompt,
             execution_id=overseer_id,
             stream_id="overseer",
         )
@@ -1100,6 +1373,96 @@ class ColonyRuntime:
             return True
         return False
 
+    def watch_batch_timeouts(
+        self,
+        worker_ids: list[str],
+        *,
+        soft_timeout: float,
+        hard_timeout: float,
+        warning_message: str | None = None,
+    ) -> asyncio.Task:
+        """Schedule a background task that enforces soft + hard timeouts.
+
+        Semantics:
+          * At ``t = soft_timeout`` every worker in ``worker_ids`` that is
+            still active AND hasn't already filed an ``_explicit_report``
+            receives ``warning_message`` via ``send_to_worker`` — the inject
+            appears as a user turn at the next agent-loop boundary, so the
+            worker's LLM can see it and call ``report_to_parent`` with
+            partial results.
+          * At ``t = hard_timeout`` any worker still active is force-stopped
+            via ``stop_worker``. ``Worker.run`` still emits its
+            ``SUBAGENT_REPORT`` on cancel (the explicit report survives,
+            if the worker reported just before the stop) so the queen
+            always sees a terminal inject for every spawned worker.
+
+        Returns the scheduled task so callers can await or cancel it.
+        Non-blocking for the caller — the watcher runs on the event loop
+        independently.
+        """
+        if warning_message is None:
+            grace = max(0.0, hard_timeout - soft_timeout)
+            warning_message = (
+                f"[SOFT TIMEOUT] You've been running for {soft_timeout:.0f}s. "
+                "Wrap up now: call report_to_parent with whatever partial "
+                "results you have. You have "
+                f"~{grace:.0f}s more before a hard stop — anything not "
+                "reported by then will be lost."
+            )
+
+        async def _watch() -> None:
+            try:
+                await asyncio.sleep(soft_timeout)
+                for wid in worker_ids:
+                    worker = self._workers.get(wid)
+                    if worker is None or not worker.is_active:
+                        continue
+                    if getattr(worker, "_explicit_report", None) is not None:
+                        continue
+                    try:
+                        await self.send_to_worker(wid, warning_message)
+                    except Exception:
+                        logger.warning(
+                            "watch_batch_timeouts: soft-timeout inject failed for %s",
+                            wid,
+                            exc_info=True,
+                        )
+
+                remaining = hard_timeout - soft_timeout
+                if remaining <= 0:
+                    return
+                await asyncio.sleep(remaining)
+                for wid in worker_ids:
+                    worker = self._workers.get(wid)
+                    if worker is None or not worker.is_active:
+                        continue
+                    try:
+                        await self.stop_worker(wid)
+                        logger.info(
+                            "watch_batch_timeouts: hard-stopped %s after %ss (no report)",
+                            wid,
+                            hard_timeout,
+                        )
+                    except Exception:
+                        logger.warning(
+                            "watch_batch_timeouts: hard-stop failed for %s",
+                            wid,
+                            exc_info=True,
+                        )
+            except asyncio.CancelledError:
+                raise
+            except Exception:
+                logger.exception("watch_batch_timeouts: watcher crashed")
+
+        task = asyncio.create_task(_watch(), name=f"batch-timeout:{worker_ids[0] if worker_ids else '?'}")
+        # Hold a strong reference until completion. Without this the
+        # task can be garbage-collected during `await asyncio.sleep`,
+        # silently swallowing the soft-timeout inject (the exact bug
+        # surfaced by workers never seeing [SOFT TIMEOUT]).
+        self._background_tasks.add(task)
+        task.add_done_callback(self._background_tasks.discard)
+        return task
+
     # ── Status & Query ──────────────────────────────────────────
 
     def list_workers(self) -> list[WorkerInfo]:

core/framework/host/colony_tools_config.py

@@ -0,0 +1,162 @@
+"""Per-colony tool configuration sidecar (``tools.json``).
+
+Lives at ``~/.hive/colonies/{colony_name}/tools.json`` alongside
+``metadata.json``. Kept separate so provenance (queen_name,
+created_at, workers) stays in metadata while the user-editable tool
+allowlist gets its own file.
+
+Schema::
+
+    {
+      "enabled_mcp_tools": ["read_file", ...] | null,
+      "updated_at": "2026-04-21T12:34:56+00:00"
+    }
+
+- ``null`` / missing file → default "allow every MCP tool".
+- ``[]`` → explicitly disable every MCP tool.
+- ``["foo", "bar"]`` → only those MCP tool names pass the filter.
+
+Atomic writes via ``os.replace`` mirror
+``framework.host.colony_metadata.update_colony_metadata``.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import tempfile
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from framework.config import COLONIES_DIR
+
+logger = logging.getLogger(__name__)
+
+
+def tools_config_path(colony_name: str) -> Path:
+    """Return the on-disk path to a colony's ``tools.json``."""
+    return COLONIES_DIR / colony_name / "tools.json"
+
+
+def _metadata_path(colony_name: str) -> Path:
+    return COLONIES_DIR / colony_name / "metadata.json"
+
+
+def _atomic_write_json(path: Path, data: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(
+        prefix=".tools.",
+        suffix=".json.tmp",
+        dir=str(path.parent),
+    )
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            json.dump(data, fh, indent=2)
+            fh.flush()
+            os.fsync(fh.fileno())
+        os.replace(tmp, path)
+    except BaseException:
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+        raise
+
+
+def _migrate_from_metadata_if_needed(colony_name: str) -> list[str] | None:
+    """Hoist a legacy ``enabled_mcp_tools`` field out of ``metadata.json``.
+
+    Returns the migrated value (or ``None`` if nothing to migrate). After
+    migration the sidecar exists and ``metadata.json`` no longer contains
+    ``enabled_mcp_tools``. Safe to call repeatedly.
+    """
+    meta_path = _metadata_path(colony_name)
+    if not meta_path.exists():
+        return None
+    try:
+        data = json.loads(meta_path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        logger.warning("Could not read metadata.json during tools migration: %s", colony_name)
+        return None
+    if not isinstance(data, dict) or "enabled_mcp_tools" not in data:
+        return None
+
+    raw = data.pop("enabled_mcp_tools")
+    enabled: list[str] | None
+    if raw is None:
+        enabled = None
+    elif isinstance(raw, list) and all(isinstance(x, str) for x in raw):
+        enabled = raw
+    else:
+        logger.warning(
+            "Legacy enabled_mcp_tools on colony %s had unexpected shape %r; dropping",
+            colony_name,
+            raw,
+        )
+        enabled = None
+
+    # Sidecar first so a partial failure leaves the config recoverable.
+    _atomic_write_json(
+        tools_config_path(colony_name),
+        {
+            "enabled_mcp_tools": enabled,
+            "updated_at": datetime.now(UTC).isoformat(),
+        },
+    )
+    _atomic_write_json(meta_path, data)
+    logger.info(
+        "Migrated enabled_mcp_tools for colony %s from metadata.json to tools.json",
+        colony_name,
+    )
+    return enabled
+
+
+def load_colony_tools_config(colony_name: str) -> list[str] | None:
+    """Return the colony's MCP tool allowlist, or ``None`` for default-allow.
+
+    Order of resolution:
+    1. ``tools.json`` sidecar (authoritative).
+    2. Legacy ``metadata.json`` field (migrated and deleted on first read).
+    3. ``None`` — default "allow every MCP tool".
+    """
+    path = tools_config_path(colony_name)
+    if path.exists():
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            logger.warning("Invalid %s; treating as default-allow", path)
+            return None
+        if not isinstance(data, dict):
+            return None
+        raw = data.get("enabled_mcp_tools")
+        if raw is None:
+            return None
+        if isinstance(raw, list) and all(isinstance(x, str) for x in raw):
+            return raw
+        logger.warning("Unexpected enabled_mcp_tools shape in %s; ignoring", path)
+        return None
+
+    return _migrate_from_metadata_if_needed(colony_name)
+
+
+def update_colony_tools_config(
+    colony_name: str,
+    enabled_mcp_tools: list[str] | None,
+) -> list[str] | None:
+    """Persist a colony's MCP allowlist to ``tools.json``.
+
+    Raises ``FileNotFoundError`` if the colony's directory is missing.
+    """
+    colony_dir = COLONIES_DIR / colony_name
+    if not colony_dir.exists():
+        raise FileNotFoundError(f"Colony directory not found: {colony_name}")
+    _atomic_write_json(
+        tools_config_path(colony_name),
+        {
+            "enabled_mcp_tools": enabled_mcp_tools,
+            "updated_at": datetime.now(UTC).isoformat(),
+        },
+    )
+    return enabled_mcp_tools

core/framework/host/event_bus.py

@@ -42,7 +42,9 @@ def _open_event_log() -> IO[str] | None:
         return None
     raw = _DEBUG_EVENTS_RAW
     if raw.lower() in ("1", "true", "full"):
-        log_dir = Path.home() / ".hive" / "event_logs"
+        from framework.config import HIVE_HOME
+
+        log_dir = HIVE_HOME / "event_logs"
     else:
         log_dir = Path(raw)
     log_dir.mkdir(parents=True, exist_ok=True)
@@ -111,6 +113,15 @@ class EventType(StrEnum):
     # Retry tracking
     NODE_RETRY = "node_retry"
 
+    # Stream-health observability. Split from NODE_RETRY so the UI can
+    # distinguish "slow TTFT on a huge context" (healthy, just slow) from
+    # "stream went silent mid-generation" (probable stall) from "we nudged
+    # the model to continue" (recovery), which NODE_RETRY used to conflate.
+    STREAM_TTFT_EXCEEDED = "stream_ttft_exceeded"
+    STREAM_INACTIVE = "stream_inactive"
+    STREAM_NUDGE_SENT = "stream_nudge_sent"
+    TOOL_CALL_REPLAY_DETECTED = "tool_call_replay_detected"
+
     # Worker agent lifecycle
     WORKER_COMPLETED = "worker_completed"
     WORKER_FAILED = "worker_failed"
@@ -156,6 +167,14 @@ class EventType(StrEnum):
     TRIGGER_REMOVED = "trigger_removed"
     TRIGGER_UPDATED = "trigger_updated"
 
+    # Task system lifecycle (per-list diffs streamed to the UI)
+    TASK_CREATED = "task_created"
+    TASK_UPDATED = "task_updated"
+    TASK_DELETED = "task_deleted"
+    TASK_LIST_RESET = "task_list_reset"
+    TASK_LIST_REATTACH_MISMATCH = "task_list_reattach_mismatch"
+    COLONY_TEMPLATE_ASSIGNMENT = "colony_template_assignment"
+
 
 @dataclass
 class AgentEvent:
@@ -800,16 +819,28 @@ class EventBus:
         input_tokens: int,
         output_tokens: int,
         cached_tokens: int = 0,
+        cache_creation_tokens: int = 0,
+        cost_usd: float = 0.0,
         execution_id: str | None = None,
         iteration: int | None = None,
     ) -> None:
-        """Emit LLM turn completion with stop reason and model metadata."""
+        """Emit LLM turn completion with stop reason and model metadata.
+
+        ``cached_tokens`` and ``cache_creation_tokens`` are subsets of
+        ``input_tokens`` (already inside provider ``prompt_tokens``).
+        Subscribers should display them, not add them to a total.
+
+        ``cost_usd`` is the USD cost for this turn when known (Anthropic,
+        OpenAI, OpenRouter). 0.0 means unreported (not free).
+        """
         data: dict = {
             "stop_reason": stop_reason,
             "model": model,
             "input_tokens": input_tokens,
             "output_tokens": output_tokens,
             "cached_tokens": cached_tokens,
+            "cache_creation_tokens": cache_creation_tokens,
+            "cost_usd": cost_usd,
         }
         if iteration is not None:
             data["iteration"] = iteration
@@ -905,24 +936,22 @@ class EventBus:
         self,
         stream_id: str,
         node_id: str,
-        prompt: str = "",
         execution_id: str | None = None,
-        options: list[str] | None = None,
         questions: list[dict] | None = None,
     ) -> None:
         """Emit a user-input request for interactive queen turns.
 
         Args:
-            options: Optional predefined choices for the user (1-3 items).
-                     The frontend appends an "Other" free-text option
-                     automatically.
-            questions: Optional list of question dicts for multi-question
-                       batches (from ask_user_multiple). Each dict has id,
-                       prompt, and optional options.
+            questions: Optional list of question dicts from ``ask_user``.
+                Each dict has ``id``, ``prompt``, and optional ``options``
+                (2-3 predefined choices). The frontend renders the
+                QuestionWidget for a single-entry list and the
+                MultiQuestionWidget for 2+ entries. Free-text asks (no
+                options) stream the prompt separately as a chat message;
+                auto-block turns have no questions at all and fall back
+                to the normal text input.
         """
-        data: dict[str, Any] = {"prompt": prompt}
-        if options:
-            data["options"] = options
+        data: dict[str, Any] = {}
         if questions:
             data["questions"] = questions
         await self.publish(
@@ -1061,6 +1090,94 @@ class EventBus:
             )
         )
 
+    async def emit_stream_ttft_exceeded(
+        self,
+        stream_id: str,
+        node_id: str,
+        ttft_seconds: float,
+        limit_seconds: float,
+        execution_id: str | None = None,
+    ) -> None:
+        """Emit when a stream stayed silent past the TTFT budget (no first event)."""
+        await self.publish(
+            AgentEvent(
+                type=EventType.STREAM_TTFT_EXCEEDED,
+                stream_id=stream_id,
+                node_id=node_id,
+                execution_id=execution_id,
+                data={
+                    "ttft_seconds": ttft_seconds,
+                    "limit_seconds": limit_seconds,
+                },
+            )
+        )
+
+    async def emit_stream_inactive(
+        self,
+        stream_id: str,
+        node_id: str,
+        idle_seconds: float,
+        limit_seconds: float,
+        execution_id: str | None = None,
+    ) -> None:
+        """Emit when a stream that had produced events went silent past budget."""
+        await self.publish(
+            AgentEvent(
+                type=EventType.STREAM_INACTIVE,
+                stream_id=stream_id,
+                node_id=node_id,
+                execution_id=execution_id,
+                data={
+                    "idle_seconds": idle_seconds,
+                    "limit_seconds": limit_seconds,
+                },
+            )
+        )
+
+    async def emit_stream_nudge_sent(
+        self,
+        stream_id: str,
+        node_id: str,
+        reason: str,
+        nudge_count: int,
+        execution_id: str | None = None,
+    ) -> None:
+        """Emit when the continue-nudge was injected (recovery, not retry)."""
+        await self.publish(
+            AgentEvent(
+                type=EventType.STREAM_NUDGE_SENT,
+                stream_id=stream_id,
+                node_id=node_id,
+                execution_id=execution_id,
+                data={
+                    "reason": reason,
+                    "nudge_count": nudge_count,
+                },
+            )
+        )
+
+    async def emit_tool_call_replay_detected(
+        self,
+        stream_id: str,
+        node_id: str,
+        tool_name: str,
+        prior_seq: int,
+        execution_id: str | None = None,
+    ) -> None:
+        """Emit when the model is about to re-execute a prior successful call."""
+        await self.publish(
+            AgentEvent(
+                type=EventType.TOOL_CALL_REPLAY_DETECTED,
+                stream_id=stream_id,
+                node_id=node_id,
+                execution_id=execution_id,
+                data={
+                    "tool_name": tool_name,
+                    "prior_seq": prior_seq,
+                },
+            )
+        )
+
     async def emit_worker_completed(
         self,
         stream_id: str,

core/framework/host/execution_manager.py

@@ -16,7 +16,7 @@ from collections import OrderedDict
 from collections.abc import Callable
 from dataclasses import dataclass, field
 from datetime import datetime
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, Literal
 
 from framework.host.event_bus import EventBus
 from framework.host.shared_state import IsolationLevel, SharedBufferManager
@@ -48,6 +48,8 @@ class ExecutionAlreadyRunningError(RuntimeError):
 
 logger = logging.getLogger(__name__)
 
+CancelExecutionResult = Literal["cancelled", "cancelling", "not_found"]
+
 
 class GraphScopedEventBus(EventBus):
     """Proxy that stamps ``graph_id`` on every published event.
@@ -130,7 +132,7 @@ class ExecutionContext:
     run_id: str | None = None  # Unique ID per trigger() invocation
     started_at: datetime = field(default_factory=datetime.now)
     completed_at: datetime | None = None
-    status: str = "pending"  # pending, running, completed, failed, paused
+    status: str = "pending"  # pending, running, cancelling, completed, failed, paused, cancelled
 
 
 class ExecutionManager:
@@ -315,6 +317,22 @@ class ExecutionManager:
         """Return IDs of all currently active executions."""
         return list(self._active_executions.keys())
 
+    def _get_blocking_execution_ids_locked(self) -> list[str]:
+        """Return executions that still block a replacement from starting.
+
+        An execution continues to block replacement until its task has
+        terminated and the task's final cleanup has removed its bookkeeping.
+        This is intentional: a timed-out cancellation does not mean the old
+        task is harmless. If it is still alive, it can still write shared
+        session state, so letting a replacement start would guarantee
+        overlapping mutations on the same session.
+        """
+        blocking_ids: list[str] = list(self._active_executions.keys())
+        for execution_id, task in self._execution_tasks.items():
+            if not task.done() and execution_id not in self._active_executions:
+                blocking_ids.append(execution_id)
+        return blocking_ids
+
     @property
     def agent_idle_seconds(self) -> float:
         """Seconds since the last agent activity (LLM call, tool call, node transition).
@@ -396,15 +414,22 @@ class ExecutionManager:
 
     async def stop(self) -> None:
         """Stop the execution stream and cancel active executions."""
-        if not self._running:
-            return
+        async with self._lock:
+            if not self._running:
+                return
 
-        self._running = False
+            self._running = False
 
-        # Cancel all active executions
-        tasks_to_wait = []
-        for _, task in self._execution_tasks.items():
-            if not task.done():
+            # Cancel all active executions, but keep bookkeeping until each
+            # task reaches its own cleanup path.
+            tasks_to_wait: list[asyncio.Task] = []
+            for execution_id, task in self._execution_tasks.items():
+                if task.done():
+                    continue
+                ctx = self._active_executions.get(execution_id)
+                if ctx is not None:
+                    ctx.status = "cancelling"
+                self._cancel_reasons.setdefault(execution_id, "Execution cancelled")
                 task.cancel()
                 tasks_to_wait.append(task)
 
@@ -418,9 +443,6 @@ class ExecutionManager:
                     len(pending),
                 )
 
-        self._execution_tasks.clear()
-        self._active_executions.clear()
-
         logger.info(f"ExecutionStream '{self.stream_id}' stopped")
 
         # Emit stream stopped event
@@ -569,12 +591,16 @@ class ExecutionManager:
         )
 
         async with self._lock:
+            if not self._running:
+                raise RuntimeError(f"ExecutionStream '{self.stream_id}' is not running")
+
+            blocking_ids = self._get_blocking_execution_ids_locked()
+            if blocking_ids:
+                raise ExecutionAlreadyRunningError(self.stream_id, blocking_ids)
+
             self._active_executions[execution_id] = ctx
             self._completion_events[execution_id] = asyncio.Event()
-
-        # Start execution task
-        task = asyncio.create_task(self._run_execution(ctx))
-        self._execution_tasks[execution_id] = task
+            self._execution_tasks[execution_id] = asyncio.create_task(self._run_execution(ctx))
 
         logger.debug(f"Queued execution {execution_id} for stream {self.stream_id}")
         return execution_id
@@ -1183,7 +1209,7 @@ class ExecutionManager:
         """Get execution context."""
         return self._active_executions.get(execution_id)
 
-    async def cancel_execution(self, execution_id: str, *, reason: str | None = None) -> bool:
+    async def cancel_execution(self, execution_id: str, *, reason: str | None = None) -> CancelExecutionResult:
         """
         Cancel a running execution.
 
@@ -1194,33 +1220,38 @@ class ExecutionManager:
                 provided, defaults to "Execution cancelled".
 
         Returns:
-            True if cancelled, False if not found
+            "cancelled" if the task fully exited within the grace period,
+            "cancelling" if cancellation was requested but the task is still
+            shutting down, or "not_found" if no active task exists.
         """
-        task = self._execution_tasks.get(execution_id)
-        if task and not task.done():
+        async with self._lock:
+            task = self._execution_tasks.get(execution_id)
+            if task is None or task.done():
+                return "not_found"
+
             # Store the reason so the CancelledError handler can use it
             # when emitting the pause/fail event.
             self._cancel_reasons[execution_id] = reason or "Execution cancelled"
+            ctx = self._active_executions.get(execution_id)
+            if ctx is not None:
+                ctx.status = "cancelling"
             task.cancel()
-            # Wait briefly for the task to finish. Don't block indefinitely —
-            # the task may be stuck in a long LLM API call that doesn't
-            # respond to cancellation quickly.
-            done, _ = await asyncio.wait({task}, timeout=5.0)
-            if not done:
-                # Task didn't finish within timeout — clean up bookkeeping now
-                # so the session doesn't think it still has running executions.
-                # The task will continue winding down in the background and its
-                # finally block will harmlessly pop already-removed keys.
-                logger.warning(
-                    "Execution %s did not finish within cancel timeout; force-cleaning bookkeeping",
-                    execution_id,
-                )
-                async with self._lock:
-                    self._active_executions.pop(execution_id, None)
-                    self._execution_tasks.pop(execution_id, None)
-                self._active_executors.pop(execution_id, None)
-            return True
-        return False
+
+        # Wait briefly for the task to finish. Don't block indefinitely —
+        # the task may be stuck in a long LLM API call that doesn't
+        # respond to cancellation quickly.
+        done, _ = await asyncio.wait({task}, timeout=5.0)
+        if not done:
+            # Keep bookkeeping in place until the task's own finally block runs.
+            # We intentionally do not add deferred cleanup keyed by execution_id
+            # here because resumed executions reuse the same id; a delayed pop
+            # could otherwise delete bookkeeping that belongs to the new run.
+            logger.warning(
+                "Execution %s did not finish within cancel timeout; leaving bookkeeping in place until task exit",
+                execution_id,
+            )
+            return "cancelling"
+        return "cancelled"
 
     # === STATS AND MONITORING ===
 

core/framework/host/progress_db.py

@@ -7,7 +7,7 @@ verify SOP gates before marking a task done. This gives cross-run memory
 that the existing per-iteration stall detectors don't have.
 
 The DB is driven by agents via the ``sqlite3`` CLI through
-``execute_command_tool``. This module handles framework-side lifecycle:
+``terminal_exec``. This module handles framework-side lifecycle:
 creation, migration, queen-side bulk seeding, stale-claim reclamation.
 
 Concurrency model:
@@ -33,7 +33,7 @@ import json
 import logging
 import sqlite3
 import uuid
-from datetime import datetime, timezone
+from datetime import UTC, datetime
 from pathlib import Path
 from typing import Any
 
@@ -118,7 +118,7 @@ _PRAGMAS = (
 
 
 def _now_iso() -> str:
-    return datetime.now(timezone.utc).isoformat(timespec="seconds")
+    return datetime.now(UTC).isoformat(timespec="seconds")
 
 
 def _new_id() -> str:
@@ -167,13 +167,10 @@ def ensure_progress_db(colony_dir: Path) -> Path:
             con.executescript(_SCHEMA_V1)
             con.execute(f"PRAGMA user_version = {SCHEMA_VERSION}")
             con.execute(
-                "INSERT OR REPLACE INTO colony_meta(key, value, updated_at) "
-                "VALUES (?, ?, ?)",
+                "INSERT OR REPLACE INTO colony_meta(key, value, updated_at) VALUES (?, ?, ?)",
                 ("schema_version", str(SCHEMA_VERSION), _now_iso()),
             )
-            logger.info(
-                "progress_db: initialized schema v%d at %s", SCHEMA_VERSION, db_path
-            )
+            logger.info("progress_db: initialized schema v%d at %s", SCHEMA_VERSION, db_path)
 
         reclaimed = _reclaim_stale_inner(con, stale_after_minutes=15)
         if reclaimed:
@@ -191,19 +188,28 @@ def ensure_progress_db(colony_dir: Path) -> Path:
 
 
 def _patch_worker_configs(colony_dir: Path, db_path: Path) -> int:
-    """Inject ``input_data.db_path`` + ``input_data.colony_id`` into
-    existing ``worker.json`` files in a colony directory.
+    """Inject ``input_data.db_path`` + ``input_data.colony_id`` +
+    ``input_data.colony_data_dir`` into existing ``worker.json`` files
+    in a colony directory.
 
     Runs on every ``ensure_progress_db`` call so colonies that were
     forked before this feature landed get their worker spawn messages
     patched in place. Idempotent: if ``input_data`` already contains
-    the correct ``db_path``, the file is not rewritten.
+    all three values, the file is not rewritten.
 
     Returns the number of files that were actually modified (0 on
     the common case of already-patched colonies).
+
+    Why ``colony_data_dir``? ``db_path`` alone points agents at
+    ``progress.db``; for anything else (custom SQLite stores, JSON
+    ledgers, scraped artefacts) they need the *directory* so they
+    stop creating state under ``~/.hive/skills/`` — which holds skill
+    *definitions*, not runtime data. See
+    ``_default_skills/colony-storage-paths/SKILL.md``.
     """
     colony_id = colony_dir.name
     abs_db = str(db_path)
+    abs_data_dir = str(db_path.parent)
     patched = 0
 
     for worker_cfg in colony_dir.glob("*.json"):
@@ -227,26 +233,24 @@ def _patch_worker_configs(colony_dir: Path, db_path: Path) -> int:
         if (
             input_data.get("db_path") == abs_db
             and input_data.get("colony_id") == colony_id
+            and input_data.get("colony_data_dir") == abs_data_dir
         ):
             continue  # already patched
 
         input_data["db_path"] = abs_db
         input_data["colony_id"] = colony_id
+        input_data["colony_data_dir"] = abs_data_dir
         data["input_data"] = input_data
 
         try:
-            worker_cfg.write_text(
-                json.dumps(data, indent=2, ensure_ascii=False), encoding="utf-8"
-            )
+            worker_cfg.write_text(json.dumps(data, indent=2, ensure_ascii=False), encoding="utf-8")
             patched += 1
         except OSError as e:
-            logger.warning(
-                "progress_db: failed to patch worker config %s: %s", worker_cfg, e
-            )
+            logger.warning("progress_db: failed to patch worker config %s: %s", worker_cfg, e)
 
     if patched:
         logger.info(
-            "progress_db: patched %d worker config(s) in colony '%s' with db_path",
+            "progress_db: patched %d worker config(s) in colony '%s' with db_path + colony_data_dir",
             patched,
             colony_id,
         )
@@ -260,7 +264,9 @@ def ensure_all_colony_dbs(colonies_root: Path | None = None) -> list[Path]:
     run the stale-claim reclaimer on all of them in one pass.
     """
     if colonies_root is None:
-        colonies_root = Path.home() / ".hive" / "colonies"
+        from framework.config import COLONIES_DIR
+
+        colonies_root = COLONIES_DIR
     if not colonies_root.is_dir():
         return []
 
@@ -271,9 +277,7 @@ def ensure_all_colony_dbs(colonies_root: Path | None = None) -> list[Path]:
         try:
             initialized.append(ensure_progress_db(entry))
         except Exception as e:
-            logger.warning(
-                "progress_db: failed to ensure DB for colony '%s': %s", entry.name, e
-            )
+            logger.warning("progress_db: failed to ensure DB for colony '%s': %s", entry.name, e)
     return initialized
 
 
@@ -340,9 +344,7 @@ def seed_tasks(
 
             for step_seq, step in enumerate(task.get("steps") or [], start=1):
                 if not step.get("title"):
-                    raise ValueError(
-                        f"task[{idx}].steps[{step_seq - 1}] missing required 'title'"
-                    )
+                    raise ValueError(f"task[{idx}].steps[{step_seq - 1}] missing required 'title'")
                 con.execute(
                     """
                     INSERT INTO steps (id, task_id, seq, title, detail, status)
@@ -361,9 +363,7 @@ def seed_tasks(
                 key = sop.get("key")
                 description = sop.get("description")
                 if not key or not description:
-                    raise ValueError(
-                        f"task[{idx}].sop_items missing 'key' or 'description'"
-                    )
+                    raise ValueError(f"task[{idx}].sop_items missing 'key' or 'description'")
                 con.execute(
                     """
                     INSERT INTO sop_checklist
@@ -421,9 +421,7 @@ def enqueue_task(
     return ids[0]
 
 
-def _reclaim_stale_inner(
-    con: sqlite3.Connection, *, stale_after_minutes: int
-) -> int:
+def _reclaim_stale_inner(con: sqlite3.Connection, *, stale_after_minutes: int) -> int:
     """Reclaim stale claims. Runs inside an existing open connection.
 
     Two-step:

core/framework/host/worker.py

@@ -145,6 +145,34 @@ class Worker:
         self.status = WorkerStatus.RUNNING
         self._started_at = time.monotonic()
 
+        # Scope browser profile (and any other CONTEXT_PARAMS) to this
+        # worker. asyncio.create_task() copies the parent's contextvars,
+        # so without this override every spawned worker inherits the
+        # queen's `profile=<queen_session_id>` and its browser_* tool
+        # calls end up driving the queen's Chrome tab group. Setting
+        # it here (inside the new Task's context) shadows the parent
+        # value without affecting the queen's ongoing calls.
+        try:
+            from framework.loader.tool_registry import ToolRegistry
+            from framework.tasks.scoping import session_task_list_id
+
+            ctx = self._context
+            agent_id = getattr(ctx, "agent_id", None) or self.id
+            list_id = getattr(ctx, "task_list_id", None) or session_task_list_id(agent_id, self.id)
+            ToolRegistry.set_execution_context(
+                profile=self.id,
+                agent_id=agent_id,
+                task_list_id=list_id,
+                colony_id=getattr(ctx, "colony_id", None),
+                picked_up_from=getattr(ctx, "picked_up_from", None),
+            )
+        except Exception:
+            logger.debug(
+                "Worker %s: failed to scope execution context",
+                self.id,
+                exc_info=True,
+            )
+
         try:
             result = await self._agent_loop.execute(self._context)
             duration = time.monotonic() - self._started_at
@@ -170,13 +198,28 @@ class Worker:
         except asyncio.CancelledError:
             self.status = WorkerStatus.STOPPED
             duration = time.monotonic() - self._started_at
-            self._result = WorkerResult(
-                error="Worker stopped by queen",
-                duration_seconds=duration,
-                status="stopped",
-                summary="Worker was cancelled before completion.",
-            )
-            await self._emit_terminal_events(None, force_status="stopped")
+            # Preserve any explicit report the worker's LLM already filed
+            # via ``report_to_parent`` before being cancelled — the caller
+            # cares about that payload even on a hard stop. Only fall back
+            # to the canned "stopped" message when no explicit report exists.
+            explicit = self._explicit_report
+            if explicit is not None:
+                self._result = WorkerResult(
+                    error="Worker stopped by queen after reporting",
+                    duration_seconds=duration,
+                    status=explicit["status"],
+                    summary=explicit["summary"],
+                    data=explicit["data"],
+                )
+                await self._emit_terminal_events(None, force_status=explicit["status"])
+            else:
+                self._result = WorkerResult(
+                    error="Worker stopped by queen",
+                    duration_seconds=duration,
+                    status="stopped",
+                    summary="Worker was cancelled before completion.",
+                )
+                await self._emit_terminal_events(None, force_status="stopped")
             return self._result
 
         except Exception as exc:

core/framework/llm/antigravity.py

@@ -23,6 +23,7 @@ from collections.abc import AsyncIterator, Callable, Iterator
 from pathlib import Path
 from typing import Any
 
+from framework.config import HIVE_HOME as _HIVE_HOME
 from framework.llm.provider import LLMProvider, LLMResponse, Tool
 from framework.llm.stream_events import (
     FinishEvent,
@@ -50,8 +51,8 @@ _ENDPOINTS = [
 _DEFAULT_PROJECT_ID = "rising-fact-p41fc"
 _TOKEN_REFRESH_BUFFER_SECS = 60
 
-# Credentials file in ~/.hive/ (native implementation)
-_ACCOUNTS_FILE = Path.home() / ".hive" / "antigravity-accounts.json"
+# Credentials file in $HIVE_HOME (native implementation)
+_ACCOUNTS_FILE = _HIVE_HOME / "antigravity-accounts.json"
 _IDE_STATE_DB_MAC = (
     Path.home() / "Library" / "Application Support" / "Antigravity" / "User" / "globalStorage" / "state.vscdb"
 )
@@ -60,10 +61,12 @@ _IDE_STATE_DB_KEY = "antigravityUnifiedStateSync.oauthToken"
 
 _BASE_HEADERS: dict[str, str] = {
     # Mimic the Antigravity Electron app so the API accepts the request.
+    # Google deprecates older client versions over time, so this needs periodic
+    # bumping to match whatever the current Antigravity desktop release advertises.
     "User-Agent": (
         "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 "
-        "(KHTML, like Gecko) Antigravity/1.18.3 Chrome/138.0.7204.235 "
-        "Electron/37.3.1 Safari/537.36"
+        "(KHTML, like Gecko) Antigravity/1.23.2 Chrome/138.0.7204.235 "
+        "Electron/39.2.3 Safari/537.36"
     ),
     "X-Goog-Api-Client": "google-cloud-sdk vscode_cloudshelleditor/0.1",
     "Client-Metadata": '{"ideType":"ANTIGRAVITY","platform":"MACOS","pluginType":"GEMINI"}',
@@ -253,6 +256,56 @@ def _clean_tool_name(name: str) -> str:
     return name[:64]
 
 
+def _sanitize_schema_for_gemini(schema: Any) -> Any:
+    """Convert JSON Schema 2020-12 features to the OpenAPI 3.0 dialect Gemini accepts.
+
+    Gemini's function_declarations parser rejects union ``"type": ["string", "null"]``.
+    Translate any such union to a single type plus ``"nullable": true``. Recurse into
+    ``properties``, ``items``, and the ``anyOf``/``oneOf``/``allOf`` combinators.
+    """
+    if isinstance(schema, list):
+        return [_sanitize_schema_for_gemini(s) for s in schema]
+    if not isinstance(schema, dict):
+        return schema
+
+    out = dict(schema)
+    t = out.get("type")
+    if isinstance(t, list):
+        non_null = [x for x in t if x != "null"]
+        has_null = "null" in t
+        if len(non_null) == 1:
+            out["type"] = non_null[0]
+            if has_null:
+                out["nullable"] = True
+        elif not non_null and has_null:
+            # Pure null type: fall back to string-nullable.
+            out["type"] = "string"
+            out["nullable"] = True
+        else:
+            # Multi-type non-null unions (e.g. ["string", "integer", "null"])
+            # have no faithful Gemini equivalent. Silently picking one type
+            # changes the contract for callers who rely on the others, so
+            # fail loud and let the schema author rewrite it as anyOf or
+            # narrow to a single type.
+            raise ValueError(
+                f"Unsupported Gemini schema union: {t!r}. "
+                "Gemini accepts a single primitive type plus optional 'nullable: true'. "
+                "Rewrite as anyOf or pick a single type."
+            )
+
+    if "properties" in out and isinstance(out["properties"], dict):
+        out["properties"] = {k: _sanitize_schema_for_gemini(v) for k, v in out["properties"].items()}
+    if "items" in out:
+        out["items"] = _sanitize_schema_for_gemini(out["items"])
+    if "additionalProperties" in out and isinstance(out["additionalProperties"], dict):
+        out["additionalProperties"] = _sanitize_schema_for_gemini(out["additionalProperties"])
+    for combinator in ("anyOf", "oneOf", "allOf"):
+        if combinator in out:
+            out[combinator] = _sanitize_schema_for_gemini(out[combinator])
+
+    return out
+
+
 def _to_gemini_contents(
     messages: list[dict[str, Any]],
     thought_sigs: dict[str, str] | None = None,
@@ -554,11 +607,13 @@ class AntigravityProvider(LLMProvider):
                         {
                             "name": _clean_tool_name(t.name),
                             "description": t.description,
-                            "parameters": t.parameters
-                            or {
-                                "type": "object",
-                                "properties": {},
-                            },
+                            "parameters": _sanitize_schema_for_gemini(
+                                t.parameters
+                                or {
+                                    "type": "object",
+                                    "properties": {},
+                                }
+                            ),
                         }
                         for t in tools
                     ]
@@ -653,10 +708,17 @@ class AntigravityProvider(LLMProvider):
         system: str = "",
         tools: list[Tool] | None = None,
         max_tokens: int = 4096,
+        system_dynamic_suffix: str | None = None,
     ) -> AsyncIterator[StreamEvent]:
         import asyncio  # noqa: PLC0415
         import concurrent.futures  # noqa: PLC0415
 
+        # Antigravity (Google's proprietary endpoint) doesn't expose a
+        # cache_control hook. Concatenate the dynamic suffix so its shape
+        # matches the legacy single-string call site.
+        if system_dynamic_suffix:
+            system = f"{system}\n\n{system_dynamic_suffix}" if system else system_dynamic_suffix
+
         loop = asyncio.get_running_loop()
         queue: asyncio.Queue[StreamEvent | None] = asyncio.Queue()
 

core/framework/llm/capabilities.py

@@ -1,114 +1,32 @@
 """Model capability checks for LLM providers.
 
-Vision support rules are derived from official vendor documentation:
-- ZAI (z.ai): docs.z.ai/guides/vlm — GLM-4.6V variants are vision; GLM-5/4.6/4.7 are text-only
-- MiniMax: platform.minimax.io/docs — minimax-vl-01 is vision; M2.x are text-only
-- DeepSeek: api-docs.deepseek.com — deepseek-vl2 is vision; chat/reasoner are text-only
-- Cerebras: inference-docs.cerebras.ai — no vision models at all
-- Groq: console.groq.com/docs/vision — vision capable; treat as supported by default
-- Ollama/LM Studio/vLLM/llama.cpp: local runners denied by default; model names
-  don't reliably indicate vision support, so users must configure explicitly
+Vision support is sourced from the curated ``model_catalog.json``. Each model
+entry carries an optional ``supports_vision`` boolean; unknown models default
+to vision-capable so hosted frontier models work out of the box. To toggle
+support for a model, edit its catalog entry rather than this file.
 """
 
 from __future__ import annotations
 
 from typing import TYPE_CHECKING
 
+from framework.llm.model_catalog import model_supports_vision
+
 if TYPE_CHECKING:
     from framework.llm.provider import Tool
 
 
-def _model_name(model: str) -> str:
-    """Return the bare model name after stripping any 'provider/' prefix."""
-    if "/" in model:
-        return model.split("/", 1)[1]
-    return model
-
-
-# Step 1: explicit vision allow-list — these always support images regardless
-# of what the provider-level rules say.  Checked first so that e.g. glm-4.6v
-# is allowed even though glm-4.6 is denied.
-_VISION_ALLOW_BARE_PREFIXES: tuple[str, ...] = (
-    # ZAI/GLM vision models (docs.z.ai/guides/vlm)
-    "glm-4v",  # GLM-4V series (legacy)
-    "glm-4.6v",  # GLM-4.6V, GLM-4.6V-flash, GLM-4.6V-flashx
-    # DeepSeek vision models
-    "deepseek-vl",  # deepseek-vl2, deepseek-vl2-small, deepseek-vl2-tiny
-    # MiniMax vision model
-    "minimax-vl",  # minimax-vl-01
-)
-
-# Step 2: provider-level deny — every model from this provider is text-only.
-_TEXT_ONLY_PROVIDER_PREFIXES: tuple[str, ...] = (
-    # Cerebras: inference-docs.cerebras.ai lists only text models
-    "cerebras/",
-    # Local runners: model names don't reliably indicate vision support
-    "ollama/",
-    "ollama_chat/",
-    "lm_studio/",
-    "vllm/",
-    "llamacpp/",
-)
-
-# Step 3: per-model deny — text-only models within otherwise mixed providers.
-# Matched against the bare model name (provider prefix stripped, lower-cased).
-# The vision allow-list above is checked first, so vision variants of the same
-# family are already handled before these deny patterns are reached.
-_TEXT_ONLY_MODEL_BARE_PREFIXES: tuple[str, ...] = (
-    # --- ZAI / GLM family ---
-    # text-only: glm-5, glm-4.6, glm-4.7, glm-4.5, zai-glm-*
-    # vision:    glm-4v, glm-4.6v (caught by allow-list above)
-    "glm-5",
-    "glm-4.6",  # bare glm-4.6 is text-only; glm-4.6v is caught by allow-list
-    "glm-4.7",
-    "glm-4.5",
-    "zai-glm",
-    # --- DeepSeek ---
-    # text-only: deepseek-chat, deepseek-coder, deepseek-reasoner
-    # vision:    deepseek-vl2 (caught by allow-list above)
-    # Note: LiteLLM's deepseek handler may flatten content lists for some models;
-    # VL models are allowed through and rely on LiteLLM's native VL support.
-    "deepseek-chat",
-    "deepseek-coder",
-    "deepseek-reasoner",
-    # --- MiniMax ---
-    # text-only: minimax-m2.*, minimax-text-*, abab* (legacy)
-    # vision:    minimax-vl-01 (caught by allow-list above)
-    "minimax-m2",
-    "minimax-text",
-    "abab",
-)
-
-
 def supports_image_tool_results(model: str) -> bool:
     """Return whether *model* can receive image content in messages.
 
-    Used to gate both user-message images and tool-result image blocks.
-
-    Logic (checked in order):
-    1. Vision allow-list  → True  (known vision model, skip all denies)
-    2. Provider deny      → False (entire provider is text-only)
-    3. Model deny         → False (specific text-only model within a mixed provider)
-    4. Default            → True  (assume capable; unknown providers and models)
+    Thin wrapper over :func:`model_supports_vision` so existing call sites
+    keep working. Used to gate both user-message images and tool-result
+    image blocks. Empty model strings are treated as capable so the default
+    code path doesn't strip images before a provider is selected.
     """
-    model_lower = model.lower()
-    bare = _model_name(model_lower)
-
-    # 1. Explicit vision allow — takes priority over all denies
-    if any(bare.startswith(p) for p in _VISION_ALLOW_BARE_PREFIXES):
+    if not model:
         return True
-
-    # 2. Provider-level deny (all models from this provider are text-only)
-    if any(model_lower.startswith(p) for p in _TEXT_ONLY_PROVIDER_PREFIXES):
-        return False
-
-    # 3. Per-model deny (text-only variants within mixed-capability families)
-    if any(bare.startswith(p) for p in _TEXT_ONLY_MODEL_BARE_PREFIXES):
-        return False
-
-    # 5. Default: assume vision capable
-    #    Covers: OpenAI, Anthropic, Google, Mistral, Kimi, and other hosted providers
-    return True
+    return model_supports_vision(model)
 
 
 def filter_tools_for_model(tools: list[Tool], model: str) -> tuple[list[Tool], list[str]]:

core/framework/llm/litellm.py

@@ -33,6 +33,7 @@ except ImportError:
     RateLimitError = Exception  # type: ignore[assignment, misc]
 
 from framework.config import HIVE_LLM_ENDPOINT as HIVE_API_BASE
+from framework.llm.model_catalog import get_model_pricing
 from framework.llm.provider import LLMProvider, LLMResponse, Tool
 from framework.llm.stream_events import StreamEvent
 
@@ -43,6 +44,30 @@ logging.getLogger("httpx").setLevel(logging.WARNING)
 logging.getLogger("httpcore").setLevel(logging.WARNING)
 
 
+def _api_base_needs_bearer_auth(api_base: str | None) -> bool:
+    """Return True when api_base points at an Anthropic-compatible endpoint
+    that authenticates via ``Authorization: Bearer`` rather than ``x-api-key``.
+
+    The Hive LLM proxy (Rust service in hive-backend/llm/) speaks the
+    Anthropic Messages API but mints user-scoped JWTs and validates them
+    via Bearer auth. Default upstream Anthropic endpoints (api.anthropic.com,
+    Kimi's api.kimi.com/coding) keep using x-api-key, so the override is
+    scoped to known hive-proxy hosts plus the env-configured override.
+    """
+    if not api_base:
+        return False
+    # Strip protocol, port, and path so a plain hostname compare is enough
+    # for the common cases.
+    lowered = api_base.lower()
+    for host in ("adenhq.com", "open-hive.com", "127.0.0.1:8890", "localhost:8890"):
+        if host in lowered:
+            return True
+    override = os.environ.get("HIVE_LLM_BASE_URL")
+    if override and override.lower() in lowered:
+        return True
+    return False
+
+
 def _patch_litellm_anthropic_oauth() -> None:
     """Patch litellm's Anthropic header construction to fix OAuth token handling.
 
@@ -186,6 +211,44 @@ def _ensure_ollama_chat_prefix(model: str) -> str:
     return model
 
 
+def rewrite_proxy_model(
+    model: str, api_key: str | None, api_base: str | None
+) -> tuple[str, str | None, dict[str, str]]:
+    """Apply Hive/Kimi proxy rewrites for any caller of ``litellm.acompletion``.
+
+    Both the Hive LLM proxy and Kimi For Coding expose Anthropic-API-
+    compatible endpoints. LiteLLM doesn't recognise the ``hive/`` or
+    ``kimi/`` prefixes natively, so we rewrite them to ``anthropic/``
+    here. For the Hive proxy we also stamp a Bearer token into
+    ``extra_headers`` because litellm's Anthropic handler only sends
+    ``x-api-key`` and the proxy expects ``Authorization: Bearer``.
+
+    Used by ad-hoc ``litellm.acompletion`` callers (e.g. the vision-
+    fallback subagent in ``caption_tool_image``) so they hit the same
+    proxy with the same auth as the main agent's ``LiteLLMProvider``.
+    The provider's own ``__init__`` keeps its inlined rewrite for now —
+    this helper is the single source of truth for ad-hoc callers.
+
+    Returns: (rewritten_model, normalised_api_base, extra_headers).
+    The ``extra_headers`` dict is non-empty only for the Hive proxy
+    (and only when ``api_key`` is provided).
+    """
+    extra_headers: dict[str, str] = {}
+    if model.lower().startswith("kimi/"):
+        model = "anthropic/" + model[len("kimi/") :]
+        if api_base and api_base.rstrip("/").endswith("/v1"):
+            api_base = api_base.rstrip("/")[:-3]
+    elif model.lower().startswith("hive/"):
+        model = "anthropic/" + model[len("hive/") :]
+        if api_base and api_base.rstrip("/").endswith("/v1"):
+            api_base = api_base.rstrip("/")[:-3]
+        # Hive proxy expects Bearer auth; litellm's Anthropic handler
+        # only sends x-api-key without this nudge.
+        if api_key:
+            extra_headers["Authorization"] = f"Bearer {api_key}"
+    return model, api_base, extra_headers
+
+
 RATE_LIMIT_MAX_RETRIES = 10
 RATE_LIMIT_BACKOFF_BASE = 2  # seconds
 RATE_LIMIT_MAX_DELAY = 120  # seconds - cap to prevent absurd waits
@@ -213,9 +276,72 @@ _CACHE_CONTROL_PREFIXES = (
     "glm-",
 )
 
+# OpenRouter sub-provider prefixes whose upstream API honors `cache_control`.
+# OpenRouter passes the marker through to the underlying provider for these.
+# (See https://openrouter.ai/docs/guides/best-practices/prompt-caching.)
+# OpenAI/DeepSeek/Groq/Grok/Moonshot route through OpenRouter but cache
+# automatically server-side — sending cache_control there is a no-op, not a
+# win, and they need a separate prefix-stability fix to actually get hits.
+_OPENROUTER_CACHE_CONTROL_PREFIXES = (
+    "openrouter/anthropic/",
+    "openrouter/google/gemini-",
+    "openrouter/z-ai/glm",
+    "openrouter/minimax/",
+)
+
 
 def _model_supports_cache_control(model: str) -> bool:
-    return any(model.startswith(p) for p in _CACHE_CONTROL_PREFIXES)
+    if any(model.startswith(p) for p in _CACHE_CONTROL_PREFIXES):
+        return True
+    return any(model.startswith(p) for p in _OPENROUTER_CACHE_CONTROL_PREFIXES)
+
+
+def _build_system_message(
+    system: str,
+    system_dynamic_suffix: str | None,
+    model: str,
+) -> dict[str, Any] | None:
+    """Construct the system-role message for the chat completion.
+
+    Returns ``None`` when there is nothing to send.
+
+    Two-block split path — used when the caller supplied a non-empty
+    ``system_dynamic_suffix`` AND the provider honors ``cache_control``
+    (Anthropic, MiniMax, Z-AI/GLM). We emit ``content`` as a list of two
+    text blocks with an ephemeral ``cache_control`` marker on the first
+    block only. The prompt cache keeps the static prefix warm across
+    turns and across iterations within a turn; only the small dynamic
+    tail is recomputed on every request.
+
+    Single-string path — used for every other case (no suffix provided,
+    or provider doesn't honor ``cache_control``). We concatenate
+    ``system`` + ``\\n\\n`` + ``system_dynamic_suffix`` and attach
+    ``cache_control`` to the whole message when the provider supports
+    it. This is byte-identical to the pre-split behavior for all
+    non-cache-control providers (OpenAI, Gemini, Groq, Ollama, etc.).
+    """
+    if not system and not system_dynamic_suffix:
+        return None
+    if system_dynamic_suffix and _model_supports_cache_control(model):
+        content_blocks: list[dict[str, Any]] = []
+        if system:
+            content_blocks.append(
+                {
+                    "type": "text",
+                    "text": system,
+                    "cache_control": {"type": "ephemeral"},
+                }
+            )
+        content_blocks.append({"type": "text", "text": system_dynamic_suffix})
+        return {"role": "system", "content": content_blocks}
+    # Single-string path (legacy or no-cache-control provider).
+    combined = system
+    if system_dynamic_suffix:
+        combined = f"{system}\n\n{system_dynamic_suffix}" if system else system_dynamic_suffix
+    sys_msg: dict[str, Any] = {"role": "system", "content": combined}
+    if _model_supports_cache_control(model):
+        sys_msg["cache_control"] = {"type": "ephemeral"}
+    return sys_msg
 
 
 # Kimi For Coding uses an Anthropic-compatible endpoint (no /v1 suffix).
@@ -289,14 +415,186 @@ OPENROUTER_TOOL_COMPAT_MODEL_CACHE: dict[str, float] = {}
 # from rate-limit retries — 3 retries is sufficient for connection failures.
 STREAM_TRANSIENT_MAX_RETRIES = 3
 
-# Directory for dumping failed requests
-FAILED_REQUESTS_DIR = Path.home() / ".hive" / "failed_requests"
 
-# Maximum number of dump files to retain in ~/.hive/failed_requests/.
+# Directory for dumping failed requests. Resolved lazily so HIVE_HOME
+# overrides (set by the desktop shell) take effect even if this module
+# is imported before framework.config picks up the override.
+def _failed_requests_dir() -> Path:
+    from framework.config import HIVE_HOME
+
+    return HIVE_HOME / "failed_requests"
+
+
+# Maximum number of dump files to retain in $HIVE_HOME/failed_requests/.
 # Older files are pruned automatically to prevent unbounded disk growth.
 MAX_FAILED_REQUEST_DUMPS = 50
 
 
+def _cost_from_catalog_pricing(
+    model: str,
+    input_tokens: int,
+    output_tokens: int,
+    cached_tokens: int = 0,
+    cache_creation_tokens: int = 0,
+) -> float:
+    """Last-resort cost calculation using curated catalog pricing.
+
+    Consulted only when the provider response carries no native cost and
+    LiteLLM's own catalog has no pricing for ``model``. Reads
+    ``pricing_usd_per_mtok`` from ``model_catalog.json``. Rates are USD per
+    million tokens.
+
+    ``cached_tokens`` and ``cache_creation_tokens`` are subsets of
+    ``input_tokens`` (see ``_extract_cache_tokens``), so subtract them from
+    the base input count to avoid double-billing. If a cache rate is absent,
+    fall back to the plain input rate.
+    """
+    if not model or (input_tokens == 0 and output_tokens == 0):
+        return 0.0
+    pricing = get_model_pricing(model)
+    if pricing is None and "/" in model:
+        # LiteLLM prefixes some ids (e.g. "openrouter/z-ai/glm-5.1"); the
+        # catalog stores the bare form ("z-ai/glm-5.1"). Strip one segment.
+        pricing = get_model_pricing(model.split("/", 1)[1])
+    if pricing is None:
+        return 0.0
+
+    per_mtok_in = pricing.get("input", 0.0)
+    per_mtok_out = pricing.get("output", 0.0)
+    per_mtok_cache_read = pricing.get("cache_read", per_mtok_in)
+    per_mtok_cache_write = pricing.get("cache_creation", per_mtok_in)
+
+    plain_input = max(input_tokens - cached_tokens - cache_creation_tokens, 0)
+    total = (
+        plain_input * per_mtok_in
+        + cached_tokens * per_mtok_cache_read
+        + cache_creation_tokens * per_mtok_cache_write
+        + output_tokens * per_mtok_out
+    ) / 1_000_000
+    return float(total) if total > 0 else 0.0
+
+
+def _extract_cost(response: Any, model: str) -> float:
+    """Pull the USD cost for a non-streaming completion response.
+
+    Sources checked, in priority order:
+      1. ``usage.cost`` — populated when OpenRouter returns native cost via
+         ``usage: {include: true}`` or when ``litellm.include_cost_in_streaming_usage``
+         is on.
+      2. ``response._hidden_params["response_cost"]`` — set by LiteLLM's
+         logging layer after most successful completions.
+      3. ``litellm.completion_cost(...)`` — computes from the model pricing
+         table; works across Anthropic, OpenAI, and OpenRouter as long as the
+         model is in LiteLLM's catalog.
+      4. ``pricing_usd_per_mtok`` from the curated model catalog — covers
+         models (e.g. GLM, Kimi, MiniMax) that LiteLLM doesn't price.
+
+    Returns 0.0 for unpriced models or unexpected response shapes — cost is a
+    display concern, never let it break the hot path. For streaming paths
+    where the aggregate response isn't a full ``ModelResponse``, use
+    :func:`_cost_from_tokens` with the already-extracted token counts.
+    """
+    if response is None:
+        return 0.0
+    usage = getattr(response, "usage", None)
+    usage_cost = getattr(usage, "cost", None) if usage is not None else None
+    if isinstance(usage_cost, (int, float)) and usage_cost > 0:
+        return float(usage_cost)
+
+    hidden = getattr(response, "_hidden_params", None)
+    if isinstance(hidden, dict):
+        hp_cost = hidden.get("response_cost")
+        if isinstance(hp_cost, (int, float)) and hp_cost > 0:
+            return float(hp_cost)
+
+    try:
+        import litellm as _litellm
+
+        computed = _litellm.completion_cost(completion_response=response, model=model)
+        if isinstance(computed, (int, float)) and computed > 0:
+            return float(computed)
+    except Exception as exc:
+        logger.debug("[cost] completion_cost failed for %s: %s", model, exc)
+
+    if usage is not None:
+        input_tokens = int(getattr(usage, "prompt_tokens", 0) or 0)
+        output_tokens = int(getattr(usage, "completion_tokens", 0) or 0)
+        cache_read, cache_creation = _extract_cache_tokens(usage)
+        fallback = _cost_from_catalog_pricing(model, input_tokens, output_tokens, cache_read, cache_creation)
+        if fallback > 0:
+            return fallback
+    return 0.0
+
+
+def _cost_from_tokens(
+    model: str,
+    input_tokens: int,
+    output_tokens: int,
+    cached_tokens: int = 0,
+    cache_creation_tokens: int = 0,
+) -> float:
+    """Compute USD cost from already-normalized token counts.
+
+    Used on streaming paths where the aggregate ``response`` is the stream
+    wrapper (not a full ``ModelResponse``) and ``litellm.completion_cost`` on
+    it either no-ops or raises. Calls ``litellm.cost_per_token`` directly
+    with the cache-aware inputs so Anthropic's 5-min-write / cache-read
+    multipliers are applied correctly.
+    """
+    if not model or (input_tokens == 0 and output_tokens == 0):
+        return 0.0
+    try:
+        import litellm as _litellm
+
+        prompt_cost, completion_cost = _litellm.cost_per_token(
+            model=model,
+            prompt_tokens=input_tokens,
+            completion_tokens=output_tokens,
+            cache_read_input_tokens=cached_tokens,
+            cache_creation_input_tokens=cache_creation_tokens,
+        )
+        total = (prompt_cost or 0.0) + (completion_cost or 0.0)
+        if total > 0:
+            return float(total)
+    except Exception as exc:
+        logger.debug("[cost] cost_per_token failed for %s: %s", model, exc)
+    return _cost_from_catalog_pricing(model, input_tokens, output_tokens, cached_tokens, cache_creation_tokens)
+
+
+def _extract_cache_tokens(usage: Any) -> tuple[int, int]:
+    """Pull (cache_read, cache_creation) from a LiteLLM usage object.
+
+    Both are subsets of ``prompt_tokens`` already — providers count them
+    inside the input total. Surface separately for visibility, never sum.
+
+    Field names vary by provider/proxy; check the known shapes in priority
+    order and fall back to 0:
+
+    cache_read:
+      - ``prompt_tokens_details.cached_tokens`` — OpenAI-shape; also what
+        LiteLLM normalizes Anthropic and OpenRouter into.
+      - ``cache_read_input_tokens`` — raw Anthropic field name.
+
+    cache_creation:
+      - ``prompt_tokens_details.cache_write_tokens`` — OpenRouter's
+        normalized field for cache writes (verified empirically against
+        ``openrouter/anthropic/*`` and ``openrouter/z-ai/*`` responses).
+      - ``cache_creation_input_tokens`` — raw Anthropic top-level field.
+    """
+    if not usage:
+        return 0, 0
+    _details = getattr(usage, "prompt_tokens_details", None)
+    cache_read = (
+        getattr(_details, "cached_tokens", 0) or 0
+        if _details is not None
+        else getattr(usage, "cache_read_input_tokens", 0) or 0
+    )
+    cache_creation = (getattr(_details, "cache_write_tokens", 0) or 0 if _details is not None else 0) or (
+        getattr(usage, "cache_creation_input_tokens", 0) or 0
+    )
+    return cache_read, cache_creation
+
+
 def _estimate_tokens(model: str, messages: list[dict]) -> tuple[int, str]:
     """Estimate token count for messages. Returns (token_count, method)."""
     # Try litellm's token counter first
@@ -319,7 +617,7 @@ def _prune_failed_request_dumps(max_files: int = MAX_FAILED_REQUEST_DUMPS) -> No
     """
     try:
         all_dumps = sorted(
-            FAILED_REQUESTS_DIR.glob("*.json"),
+            _failed_requests_dir().glob("*.json"),
             key=lambda f: f.stat().st_mtime,
         )
         excess = len(all_dumps) - max_files
@@ -354,11 +652,12 @@ def _dump_failed_request(
 ) -> str:
     """Dump failed request to a file for debugging. Returns the file path."""
     try:
-        FAILED_REQUESTS_DIR.mkdir(parents=True, exist_ok=True)
+        dump_dir = _failed_requests_dir()
+        dump_dir.mkdir(parents=True, exist_ok=True)
 
         timestamp = datetime.now().strftime("%Y%m%d_%H%M%S_%f")
         filename = f"{error_type}_{model.replace('/', '_')}_{timestamp}.json"
-        filepath = FAILED_REQUESTS_DIR / filename
+        filepath = dump_dir / filename
 
         # Build dump data
         messages = kwargs.get("messages", [])
@@ -388,7 +687,7 @@ def _dump_failed_request(
 
         return str(filepath)
     except OSError as e:
-        logger.warning(f"Failed to dump request debug log to {FAILED_REQUESTS_DIR}: {e}")
+        logger.warning(f"Failed to dump request debug log to {_failed_requests_dir()}: {e}")
         return "log_write_failed"
 
 
@@ -702,6 +1001,7 @@ class LiteLLMProvider(LLMProvider):
         # Translate kimi/ prefix to anthropic/ so litellm uses the Anthropic
         # Messages API handler and routes to that endpoint — no special headers needed.
         _original_model = model
+        self._hive_proxy_auth = bool(_original_model.lower().startswith("hive/"))
         if _is_ollama_model(model):
             model = _ensure_ollama_chat_prefix(model)
         elif model.lower().startswith("kimi/"):
@@ -755,6 +1055,7 @@ class LiteLLMProvider(LLMProvider):
         these attributes in-place propagates to all callers on the next LLM call.
         """
         _original_model = model
+        self._hive_proxy_auth = bool(_original_model.lower().startswith("hive/"))
         if _is_ollama_model(model):
             model = _ensure_ollama_chat_prefix(model)
         elif model.lower().startswith("kimi/"):
@@ -994,6 +1295,16 @@ class LiteLLMProvider(LLMProvider):
                 # Ollama requires explicit tool_choice=auto for function calling
                 # so future readers don't have to guess.
                 kwargs.setdefault("tool_choice", "auto")
+            elif self._hive_proxy_auth:
+                # The Hive LLM proxy fronts GLM, which drifts into "explain
+                # the plan" mode on long-context turns instead of emitting
+                # tool_use blocks (verified 2026-04-28: tool_choice=null →
+                # text-only stop=stop; tool_choice=required → clean
+                # tool_use). Force a tool call when tools are available
+                # so queens can't get stuck in chat mode. Callers that
+                # legitimately want a non-tool turn can override via
+                # extra_kwargs.
+                kwargs.setdefault("tool_choice", "required")
 
         # Add response_format for structured output
         # LiteLLM passes this through to the underlying provider
@@ -1015,12 +1326,17 @@ class LiteLLMProvider(LLMProvider):
         usage = response.usage
         input_tokens = usage.prompt_tokens if usage else 0
         output_tokens = usage.completion_tokens if usage else 0
+        cached_tokens, cache_creation_tokens = _extract_cache_tokens(usage)
+        cost_usd = _extract_cost(response, self.model)
 
         return LLMResponse(
             content=content,
             model=response.model or self.model,
             input_tokens=input_tokens,
             output_tokens=output_tokens,
+            cached_tokens=cached_tokens,
+            cache_creation_tokens=cache_creation_tokens,
+            cost_usd=cost_usd,
             stop_reason=response.choices[0].finish_reason or "",
             raw_response=response,
         )
@@ -1169,8 +1485,16 @@ class LiteLLMProvider(LLMProvider):
         response_format: dict[str, Any] | None = None,
         json_mode: bool = False,
         max_retries: int | None = None,
+        system_dynamic_suffix: str | None = None,
     ) -> LLMResponse:
-        """Async version of complete(). Uses litellm.acompletion — non-blocking."""
+        """Async version of complete(). Uses litellm.acompletion — non-blocking.
+
+        ``system_dynamic_suffix`` is an optional per-turn tail. When set and
+        the provider honors ``cache_control``, ``system`` is sent as the
+        cached prefix and the suffix trails as an uncached second content
+        block. Otherwise the two strings are concatenated into a single
+        system message (legacy behavior).
+        """
         # Codex ChatGPT backend requires streaming — route through stream() which
         # already handles Codex quirks and has proper tool call accumulation.
         if self._codex_backend:
@@ -1181,6 +1505,7 @@ class LiteLLMProvider(LLMProvider):
                 max_tokens=max_tokens,
                 response_format=response_format,
                 json_mode=json_mode,
+                system_dynamic_suffix=system_dynamic_suffix,
             )
             return await self._collect_stream_to_response(stream_iter)
 
@@ -1188,10 +1513,8 @@ class LiteLLMProvider(LLMProvider):
         if self._claude_code_oauth:
             billing = _claude_code_billing_header(messages)
             full_messages.append({"role": "system", "content": billing})
-        if system:
-            sys_msg: dict[str, Any] = {"role": "system", "content": system}
-            if _model_supports_cache_control(self.model):
-                sys_msg["cache_control"] = {"type": "ephemeral"}
+        sys_msg = _build_system_message(system, system_dynamic_suffix, self.model)
+        if sys_msg is not None:
             full_messages.append(sys_msg)
         full_messages.extend(messages)
 
@@ -1219,6 +1542,10 @@ class LiteLLMProvider(LLMProvider):
                 # Ollama requires explicit tool_choice=auto for function calling
                 # so future readers don't have to guess.
                 kwargs.setdefault("tool_choice", "auto")
+            elif self._hive_proxy_auth:
+                # See `complete()` for the rationale: GLM behind the Hive
+                # proxy needs forcing or it goes chat-mode on long contexts.
+                kwargs.setdefault("tool_choice", "required")
         if response_format:
             kwargs["response_format"] = response_format
 
@@ -1228,12 +1555,17 @@ class LiteLLMProvider(LLMProvider):
         usage = response.usage
         input_tokens = usage.prompt_tokens if usage else 0
         output_tokens = usage.completion_tokens if usage else 0
+        cached_tokens, cache_creation_tokens = _extract_cache_tokens(usage)
+        cost_usd = _extract_cost(response, self.model)
 
         return LLMResponse(
             content=content,
             model=response.model or self.model,
             input_tokens=input_tokens,
             output_tokens=output_tokens,
+            cached_tokens=cached_tokens,
+            cache_creation_tokens=cache_creation_tokens,
+            cost_usd=cost_usd,
             stop_reason=response.choices[0].finish_reason or "",
             raw_response=response,
         )
@@ -1619,6 +1951,7 @@ class LiteLLMProvider(LLMProvider):
         messages: list[dict[str, Any]],
         system: str,
         tools: list[Tool],
+        system_dynamic_suffix: str | None = None,
     ) -> list[dict[str, Any]]:
         """Build a JSON-only prompt for models without native tool support."""
         tool_specs = [
@@ -1646,7 +1979,19 @@ class LiteLLMProvider(LLMProvider):
         )
         compat_system = compat_instruction if not system else f"{system}\n\n{compat_instruction}"
 
-        full_messages: list[dict[str, Any]] = [{"role": "system", "content": compat_system}]
+        # If the routed sub-provider honors cache_control (e.g.
+        # openrouter/anthropic/*), split the static prefix from the dynamic
+        # suffix so the prefix stays cache-warm across turns. Otherwise fall
+        # back to a single concatenated string.
+        system_message = _build_system_message(
+            compat_system,
+            system_dynamic_suffix,
+            self.model,
+        )
+
+        full_messages: list[dict[str, Any]] = []
+        if system_message is not None:
+            full_messages.append(system_message)
         full_messages.extend(messages)
         return [
             message
@@ -1660,9 +2005,21 @@ class LiteLLMProvider(LLMProvider):
         system: str,
         tools: list[Tool],
         max_tokens: int,
+        system_dynamic_suffix: str | None = None,
     ) -> LLMResponse:
-        """Emulate tool calling via JSON when OpenRouter rejects native tools."""
-        full_messages = self._build_openrouter_tool_compat_messages(messages, system, tools)
+        """Emulate tool calling via JSON when OpenRouter rejects native tools.
+
+        When the routed sub-provider honors ``cache_control`` (e.g.
+        ``openrouter/anthropic/*``), the message builder splits the static
+        prefix from the dynamic suffix so the prefix stays cache-warm.
+        Otherwise the suffix is concatenated into a single system string.
+        """
+        full_messages = self._build_openrouter_tool_compat_messages(
+            messages,
+            system,
+            tools,
+            system_dynamic_suffix=system_dynamic_suffix,
+        )
         kwargs: dict[str, Any] = {
             "model": self.model,
             "messages": full_messages,
@@ -1683,6 +2040,8 @@ class LiteLLMProvider(LLMProvider):
         usage = response.usage
         input_tokens = usage.prompt_tokens if usage else 0
         output_tokens = usage.completion_tokens if usage else 0
+        cached_tokens, cache_creation_tokens = _extract_cache_tokens(usage)
+        cost_usd = _extract_cost(response, self.model)
         stop_reason = "tool_calls" if tool_calls else (response.choices[0].finish_reason or "stop")
 
         return LLMResponse(
@@ -1690,6 +2049,9 @@ class LiteLLMProvider(LLMProvider):
             model=response.model or self.model,
             input_tokens=input_tokens,
             output_tokens=output_tokens,
+            cached_tokens=cached_tokens,
+            cache_creation_tokens=cache_creation_tokens,
+            cost_usd=cost_usd,
             stop_reason=stop_reason,
             raw_response={
                 "compat_mode": "openrouter_tool_emulation",
@@ -1704,6 +2066,7 @@ class LiteLLMProvider(LLMProvider):
         system: str,
         tools: list[Tool],
         max_tokens: int,
+        system_dynamic_suffix: str | None = None,
     ) -> AsyncIterator[StreamEvent]:
         """Fallback stream for OpenRouter models without native tool support."""
         from framework.llm.stream_events import (
@@ -1724,6 +2087,7 @@ class LiteLLMProvider(LLMProvider):
                 system=system,
                 tools=tools,
                 max_tokens=max_tokens,
+                system_dynamic_suffix=system_dynamic_suffix,
             )
         except Exception as e:
             yield StreamErrorEvent(error=str(e), recoverable=False)
@@ -1747,6 +2111,9 @@ class LiteLLMProvider(LLMProvider):
             stop_reason=response.stop_reason,
             input_tokens=response.input_tokens,
             output_tokens=response.output_tokens,
+            cached_tokens=response.cached_tokens,
+            cache_creation_tokens=response.cache_creation_tokens,
+            cost_usd=response.cost_usd,
             model=response.model,
         )
 
@@ -1758,6 +2125,7 @@ class LiteLLMProvider(LLMProvider):
         max_tokens: int,
         response_format: dict[str, Any] | None,
         json_mode: bool,
+        system_dynamic_suffix: str | None = None,
     ) -> AsyncIterator[StreamEvent]:
         """Fallback path: convert non-stream completion to stream events.
 
@@ -1781,6 +2149,7 @@ class LiteLLMProvider(LLMProvider):
                 max_tokens=max_tokens,
                 response_format=response_format,
                 json_mode=json_mode,
+                system_dynamic_suffix=system_dynamic_suffix,
             )
         except Exception as e:
             yield StreamErrorEvent(error=str(e), recoverable=False)
@@ -1812,6 +2181,9 @@ class LiteLLMProvider(LLMProvider):
             stop_reason=response.stop_reason or "stop",
             input_tokens=response.input_tokens,
             output_tokens=response.output_tokens,
+            cached_tokens=response.cached_tokens,
+            cache_creation_tokens=response.cache_creation_tokens,
+            cost_usd=response.cost_usd,
             model=response.model,
         )
 
@@ -1823,6 +2195,7 @@ class LiteLLMProvider(LLMProvider):
         max_tokens: int = 4096,
         response_format: dict[str, Any] | None = None,
         json_mode: bool = False,
+        system_dynamic_suffix: str | None = None,
     ) -> AsyncIterator[StreamEvent]:
         """Stream a completion via litellm.acompletion(stream=True).
 
@@ -1833,6 +2206,9 @@ class LiteLLMProvider(LLMProvider):
         Empty responses (e.g. Gemini stealth rate-limits that return 200
         with no content) are retried with exponential backoff, mirroring
         the retry behaviour of ``_completion_with_rate_limit_retry``.
+
+        ``system_dynamic_suffix`` is an optional per-turn tail. See
+        ``acomplete`` docstring for the two-block split semantics.
         """
         from framework.llm.stream_events import (
             FinishEvent,
@@ -1852,6 +2228,7 @@ class LiteLLMProvider(LLMProvider):
                 max_tokens=max_tokens,
                 response_format=response_format,
                 json_mode=json_mode,
+                system_dynamic_suffix=system_dynamic_suffix,
             ):
                 yield event
             return
@@ -1862,6 +2239,7 @@ class LiteLLMProvider(LLMProvider):
                 system=system,
                 tools=tools,
                 max_tokens=max_tokens,
+                system_dynamic_suffix=system_dynamic_suffix,
             ):
                 yield event
             return
@@ -1870,19 +2248,18 @@ class LiteLLMProvider(LLMProvider):
         if self._claude_code_oauth:
             billing = _claude_code_billing_header(messages)
             full_messages.append({"role": "system", "content": billing})
-        if system:
-            sys_msg: dict[str, Any] = {"role": "system", "content": system}
-            if _model_supports_cache_control(self.model):
-                sys_msg["cache_control"] = {"type": "ephemeral"}
+        sys_msg = _build_system_message(system, system_dynamic_suffix, self.model)
+        if sys_msg is not None:
             full_messages.append(sys_msg)
         full_messages.extend(messages)
 
         if logger.isEnabledFor(logging.DEBUG) and full_messages:
             import json as _json
             from datetime import datetime as _dt
-            from pathlib import Path as _Path
 
-            _debug_dir = _Path.home() / ".hive" / "debug_logs"
+            from framework.config import HIVE_HOME as _HIVE_HOME
+
+            _debug_dir = _HIVE_HOME / "debug_logs"
             _debug_dir.mkdir(parents=True, exist_ok=True)
             _ts = _dt.now().strftime("%Y%m%d_%H%M%S_%f")
             _dump_file = _debug_dir / f"llm_request_{_ts}.json"
@@ -1953,18 +2330,22 @@ class LiteLLMProvider(LLMProvider):
                 # Ollama requires explicit tool_choice=auto for function calling
                 # so future readers don't have to guess.
                 kwargs.setdefault("tool_choice", "auto")
+            elif self._hive_proxy_auth:
+                # See `complete()` for the rationale: GLM behind the Hive
+                # proxy needs forcing or it goes chat-mode on long contexts.
+                kwargs.setdefault("tool_choice", "required")
         if response_format:
             kwargs["response_format"] = response_format
         # The Codex ChatGPT backend (Responses API) rejects several params.
         if self._codex_backend:
             kwargs.pop("max_tokens", None)
             kwargs.pop("stream_options", None)
+            # Pass store directly to OpenAI in case litellm drops it as unknown
+            if "extra_body" not in kwargs:
+                kwargs["extra_body"] = {}
+            kwargs["extra_body"]["store"] = False
 
         request_summary = _summarize_request_for_log(kwargs)
-        logger.debug(
-            "[stream] prepared request: %s",
-            json.dumps(request_summary, default=str),
-        )
         if request_summary["system_only"]:
             logger.warning(
                 "[stream] %s request has no non-system chat messages "
@@ -2105,37 +2486,44 @@ class LiteLLMProvider(LLMProvider):
                             type(usage).__name__,
                         )
                         cached_tokens = 0
+                        cache_creation_tokens = 0
                         if usage:
                             input_tokens = getattr(usage, "prompt_tokens", 0) or 0
                             output_tokens = getattr(usage, "completion_tokens", 0) or 0
-                            _details = getattr(usage, "prompt_tokens_details", None)
-                            cached_tokens = (
-                                getattr(_details, "cached_tokens", 0) or 0
-                                if _details is not None
-                                else getattr(usage, "cache_read_input_tokens", 0) or 0
-                            )
+                            cached_tokens, cache_creation_tokens = _extract_cache_tokens(usage)
                             logger.debug(
-                                "[tokens] finish-chunk usage: input=%d output=%d cached=%d model=%s",
+                                "[tokens] finish-chunk usage: input=%d output=%d cached=%d cache_creation=%d model=%s",
                                 input_tokens,
                                 output_tokens,
                                 cached_tokens,
+                                cache_creation_tokens,
                                 self.model,
                             )
 
                         logger.debug(
-                            "[tokens] finish event: input=%d output=%d cached=%d stop=%s model=%s",
+                            "[tokens] finish event: input=%d output=%d cached=%d cache_creation=%d stop=%s model=%s",
                             input_tokens,
                             output_tokens,
                             cached_tokens,
+                            cache_creation_tokens,
                             choice.finish_reason,
                             self.model,
                         )
+                        cost_usd = _cost_from_tokens(
+                            self.model,
+                            input_tokens,
+                            output_tokens,
+                            cached_tokens,
+                            cache_creation_tokens,
+                        )
                         tail_events.append(
                             FinishEvent(
                                 stop_reason=choice.finish_reason,
                                 input_tokens=input_tokens,
                                 output_tokens=output_tokens,
                                 cached_tokens=cached_tokens,
+                                cache_creation_tokens=cache_creation_tokens,
+                                cost_usd=cost_usd,
                                 model=self.model,
                             )
                         )
@@ -2155,19 +2543,36 @@ class LiteLLMProvider(LLMProvider):
                             _usage = calculate_total_usage(chunks=_chunks)
                             input_tokens = _usage.prompt_tokens or 0
                             output_tokens = _usage.completion_tokens or 0
-                            _details = getattr(_usage, "prompt_tokens_details", None)
-                            cached_tokens = (
-                                getattr(_details, "cached_tokens", 0) or 0
-                                if _details is not None
-                                else getattr(_usage, "cache_read_input_tokens", 0) or 0
-                            )
+                            # `calculate_total_usage` aggregates token totals
+                            # but discards `prompt_tokens_details` — which is
+                            # where OpenRouter puts `cached_tokens` and
+                            # `cache_write_tokens`. Recover them directly
+                            # from the most recent chunk that carries usage.
+                            cached_tokens, cache_creation_tokens = 0, 0
+                            for _raw in reversed(_chunks):
+                                _raw_usage = getattr(_raw, "usage", None)
+                                if _raw_usage is None:
+                                    continue
+                                _cr, _cc = _extract_cache_tokens(_raw_usage)
+                                if _cr or _cc:
+                                    cached_tokens, cache_creation_tokens = _cr, _cc
+                                    break
                             logger.debug(
-                                "[tokens] post-loop chunks fallback: input=%d output=%d cached=%d model=%s",
+                                "[tokens] post-loop chunks fallback: input=%d output=%d "
+                                "cached=%d cache_creation=%d model=%s",
                                 input_tokens,
                                 output_tokens,
                                 cached_tokens,
+                                cache_creation_tokens,
                                 self.model,
                             )
+                            cost_usd = _cost_from_tokens(
+                                self.model,
+                                input_tokens,
+                                output_tokens,
+                                cached_tokens,
+                                cache_creation_tokens,
+                            )
                             # Patch the FinishEvent already queued with 0 tokens
                             for _i, _ev in enumerate(tail_events):
                                 if isinstance(_ev, FinishEvent) and _ev.input_tokens == 0:
@@ -2176,6 +2581,8 @@ class LiteLLMProvider(LLMProvider):
                                         input_tokens=input_tokens,
                                         output_tokens=output_tokens,
                                         cached_tokens=cached_tokens,
+                                        cache_creation_tokens=cache_creation_tokens,
+                                        cost_usd=cost_usd,
                                         model=_ev.model,
                                     )
                                     break
@@ -2386,6 +2793,8 @@ class LiteLLMProvider(LLMProvider):
         tool_calls: list[dict[str, Any]] = []
         input_tokens = 0
         output_tokens = 0
+        cached_tokens = 0
+        cache_creation_tokens = 0
         stop_reason = ""
         model = self.model
 
@@ -2403,6 +2812,8 @@ class LiteLLMProvider(LLMProvider):
             elif isinstance(event, FinishEvent):
                 input_tokens = event.input_tokens
                 output_tokens = event.output_tokens
+                cached_tokens = event.cached_tokens
+                cache_creation_tokens = event.cache_creation_tokens
                 stop_reason = event.stop_reason
                 if event.model:
                     model = event.model
@@ -2415,6 +2826,8 @@ class LiteLLMProvider(LLMProvider):
             model=model,
             input_tokens=input_tokens,
             output_tokens=output_tokens,
+            cached_tokens=cached_tokens,
+            cache_creation_tokens=cache_creation_tokens,
             stop_reason=stop_reason,
             raw_response={"tool_calls": tool_calls} if tool_calls else None,
         )

core/framework/llm/mock.py

@@ -155,8 +155,11 @@ class MockLLMProvider(LLMProvider):
         response_format: dict[str, Any] | None = None,
         json_mode: bool = False,
         max_retries: int | None = None,
+        system_dynamic_suffix: str | None = None,
     ) -> LLMResponse:
         """Async mock completion (no I/O, returns immediately)."""
+        if system_dynamic_suffix:
+            system = f"{system}\n\n{system_dynamic_suffix}" if system else system_dynamic_suffix
         return self.complete(
             messages=messages,
             system=system,
@@ -173,6 +176,7 @@ class MockLLMProvider(LLMProvider):
         system: str = "",
         tools: list[Tool] | None = None,
         max_tokens: int = 4096,
+        system_dynamic_suffix: str | None = None,
     ) -> AsyncIterator[StreamEvent]:
         """Stream a mock completion as word-level TextDeltaEvents.
 
@@ -180,6 +184,8 @@ class MockLLMProvider(LLMProvider):
         TextDeltaEvent with an accumulating snapshot, exercising the full
         streaming pipeline without any API calls.
         """
+        if system_dynamic_suffix:
+            system = f"{system}\n\n{system_dynamic_suffix}" if system else system_dynamic_suffix
         content = self._generate_mock_response(system=system, json_mode=False)
         words = content.split(" ")
         accumulated = ""

core/framework/llm/model_catalog.json

@@ -9,47 +9,65 @@
           "label": "Haiku 4.5 - Fast + cheap",
           "recommended": false,
           "max_tokens": 64000,
-          "max_context_tokens": 136000
+          "max_context_tokens": 136000,
+          "supports_vision": true
         },
         {
           "id": "claude-sonnet-4-5-20250929",
           "label": "Sonnet 4.5 - Best balance",
           "recommended": false,
           "max_tokens": 64000,
-          "max_context_tokens": 136000
+          "max_context_tokens": 136000,
+          "supports_vision": true
         },
         {
           "id": "claude-opus-4-6",
           "label": "Opus 4.6 - Most capable",
           "recommended": true,
           "max_tokens": 128000,
-          "max_context_tokens": 872000
+          "max_context_tokens": 872000,
+          "supports_vision": true
         }
       ]
     },
     "openai": {
-      "default_model": "gpt-5.4",
+      "default_model": "gpt-5.5",
       "models": [
         {
-          "id": "gpt-5.4",
-          "label": "GPT-5.4 - Best intelligence",
+          "id": "gpt-5.5",
+          "label": "GPT-5.5 - Frontier coding + reasoning",
           "recommended": true,
           "max_tokens": 128000,
-          "max_context_tokens": 960000
+          "max_context_tokens": 1050000,
+          "pricing_usd_per_mtok": {
+            "input": 5.00,
+            "output": 30.00
+          },
+          "supports_vision": true
+        },
+        {
+          "id": "gpt-5.4",
+          "label": "GPT-5.4 - Previous flagship",
+          "recommended": false,
+          "max_tokens": 128000,
+          "max_context_tokens": 960000,
+          "supports_vision": true
         },
         {
           "id": "gpt-5.4-mini",
           "label": "GPT-5.4 Mini - Faster + cheaper",
           "recommended": false,
           "max_tokens": 128000,
-          "max_context_tokens": 400000
+          "max_context_tokens": 400000,
+          "supports_vision": true
         },
         {
           "id": "gpt-5.4-nano",
           "label": "GPT-5.4 Nano - Cheapest high-volume",
           "recommended": false,
           "max_tokens": 128000,
-          "max_context_tokens": 400000
+          "max_context_tokens": 400000,
+          "supports_vision": true
         }
       ]
     },
@@ -61,14 +79,16 @@
           "label": "Gemini 3 Flash - Fast",
           "recommended": false,
           "max_tokens": 32768,
-          "max_context_tokens": 900000
+          "max_context_tokens": 240000,
+          "supports_vision": true
         },
         {
           "id": "gemini-3.1-pro-preview-customtools",
           "label": "Gemini 3.1 Pro - Best quality",
           "recommended": true,
           "max_tokens": 32768,
-          "max_context_tokens": 900000
+          "max_context_tokens": 240000,
+          "supports_vision": true
         }
       ]
     },
@@ -80,28 +100,32 @@
           "label": "GPT-OSS 120B - Best reasoning",
           "recommended": true,
           "max_tokens": 65536,
-          "max_context_tokens": 131072
+          "max_context_tokens": 131072,
+          "supports_vision": false
         },
         {
           "id": "openai/gpt-oss-20b",
           "label": "GPT-OSS 20B - Fast + cheaper",
           "recommended": false,
           "max_tokens": 65536,
-          "max_context_tokens": 131072
+          "max_context_tokens": 131072,
+          "supports_vision": false
         },
         {
           "id": "llama-3.3-70b-versatile",
           "label": "Llama 3.3 70B - General purpose",
           "recommended": false,
           "max_tokens": 32768,
-          "max_context_tokens": 131072
+          "max_context_tokens": 131072,
+          "supports_vision": false
         },
         {
           "id": "llama-3.1-8b-instant",
           "label": "Llama 3.1 8B - Fastest",
           "recommended": false,
           "max_tokens": 131072,
-          "max_context_tokens": 131072
+          "max_context_tokens": 131072,
+          "supports_vision": false
         }
       ]
     },
@@ -113,28 +137,24 @@
           "label": "GPT-OSS 120B - Best production reasoning",
           "recommended": true,
           "max_tokens": 40960,
-          "max_context_tokens": 131072
-        },
-        {
-          "id": "llama3.1-8b",
-          "label": "Llama 3.1 8B - Fastest production",
-          "recommended": false,
-          "max_tokens": 8192,
-          "max_context_tokens": 32768
+          "max_context_tokens": 131072,
+          "supports_vision": false
         },
         {
           "id": "zai-glm-4.7",
           "label": "Z.ai GLM 4.7 - Strong coding preview",
           "recommended": true,
           "max_tokens": 40960,
-          "max_context_tokens": 131072
+          "max_context_tokens": 131072,
+          "supports_vision": false
         },
         {
           "id": "qwen-3-235b-a22b-instruct-2507",
           "label": "Qwen 3 235B Instruct - Frontier preview",
           "recommended": false,
           "max_tokens": 40960,
-          "max_context_tokens": 131072
+          "max_context_tokens": 131072,
+          "supports_vision": false
         }
       ]
     },
@@ -145,15 +165,21 @@
           "id": "MiniMax-M2.7",
           "label": "MiniMax M2.7 - Best coding quality",
           "recommended": true,
-          "max_tokens": 32768,
-          "max_context_tokens": 204800
+          "max_tokens": 40960,
+          "max_context_tokens": 180000,
+          "pricing_usd_per_mtok": {
+            "input": 0.30,
+            "output": 1.20
+          },
+          "supports_vision": false
         },
         {
           "id": "MiniMax-M2.5",
           "label": "MiniMax M2.5 - Strong value",
           "recommended": false,
-          "max_tokens": 32768,
-          "max_context_tokens": 204800
+          "max_tokens": 40960,
+          "max_context_tokens": 180000,
+          "supports_vision": false
         }
       ]
     },
@@ -165,28 +191,32 @@
           "label": "Mistral Large 3 - Best quality",
           "recommended": true,
           "max_tokens": 32768,
-          "max_context_tokens": 256000
+          "max_context_tokens": 256000,
+          "supports_vision": true
         },
         {
           "id": "mistral-medium-2508",
           "label": "Mistral Medium 3.1 - Balanced",
           "recommended": false,
           "max_tokens": 32768,
-          "max_context_tokens": 128000
+          "max_context_tokens": 128000,
+          "supports_vision": true
         },
         {
           "id": "mistral-small-2603",
           "label": "Mistral Small 4 - Fast + capable",
           "recommended": false,
           "max_tokens": 32768,
-          "max_context_tokens": 256000
+          "max_context_tokens": 256000,
+          "supports_vision": true
         },
         {
           "id": "codestral-2508",
           "label": "Codestral - Coding specialist",
           "recommended": false,
           "max_tokens": 32768,
-          "max_context_tokens": 128000
+          "max_context_tokens": 128000,
+          "supports_vision": false
         }
       ]
     },
@@ -198,47 +228,71 @@
           "label": "DeepSeek V3.1 - Best general coding",
           "recommended": true,
           "max_tokens": 32768,
-          "max_context_tokens": 128000
+          "max_context_tokens": 128000,
+          "supports_vision": false
         },
         {
           "id": "Qwen/Qwen3-Coder-480B-A35B-Instruct-FP8",
           "label": "Qwen3 Coder 480B - Advanced coding",
           "recommended": false,
           "max_tokens": 32768,
-          "max_context_tokens": 262144
+          "max_context_tokens": 262144,
+          "supports_vision": false
         },
         {
           "id": "openai/gpt-oss-120b",
           "label": "GPT-OSS 120B - Strong reasoning",
           "recommended": false,
           "max_tokens": 32768,
-          "max_context_tokens": 128000
+          "max_context_tokens": 128000,
+          "supports_vision": false
         },
         {
           "id": "meta-llama/Llama-3.3-70B-Instruct-Turbo",
           "label": "Llama 3.3 70B Turbo - Fast baseline",
           "recommended": false,
           "max_tokens": 32768,
-          "max_context_tokens": 131072
+          "max_context_tokens": 131072,
+          "supports_vision": false
         }
       ]
     },
     "deepseek": {
-      "default_model": "deepseek-chat",
+      "default_model": "deepseek-v4-pro",
       "models": [
         {
-          "id": "deepseek-chat",
-          "label": "DeepSeek Chat - Fast default",
+          "id": "deepseek-v4-pro",
+          "label": "DeepSeek V4 Pro - Most capable",
           "recommended": true,
-          "max_tokens": 8192,
-          "max_context_tokens": 128000
+          "max_tokens": 384000,
+          "max_context_tokens": 1000000,
+          "pricing_usd_per_mtok": {
+            "input": 1.74,
+            "output": 3.48,
+            "cache_read": 0.145
+          },
+          "supports_vision": false
+        },
+        {
+          "id": "deepseek-v4-flash",
+          "label": "DeepSeek V4 Flash - Fast + cheap",
+          "recommended": true,
+          "max_tokens": 384000,
+          "max_context_tokens": 1000000,
+          "pricing_usd_per_mtok": {
+            "input": 0.14,
+            "output": 0.28,
+            "cache_read": 0.028
+          },
+          "supports_vision": false
         },
         {
           "id": "deepseek-reasoner",
-          "label": "DeepSeek Reasoner - Deep thinking",
+          "label": "DeepSeek Reasoner - Legacy (deprecating)",
           "recommended": false,
           "max_tokens": 64000,
-          "max_context_tokens": 128000
+          "max_context_tokens": 128000,
+          "supports_vision": false
         }
       ]
     },
@@ -250,7 +304,13 @@
           "label": "Kimi K2.5 - Best coding",
           "recommended": true,
           "max_tokens": 32768,
-          "max_context_tokens": 200000
+          "max_context_tokens": 200000,
+          "pricing_usd_per_mtok": {
+            "input": 0.60,
+            "output": 2.50,
+            "cache_read": 0.15
+          },
+          "supports_vision": true
         }
       ]
     },
@@ -262,21 +322,30 @@
           "label": "Queen - Hive native",
           "recommended": true,
           "max_tokens": 32768,
-          "max_context_tokens": 180000
+          "max_context_tokens": 180000,
+          "supports_vision": false
         },
         {
-          "id": "kimi-2.5",
+          "id": "kimi-k2.5",
           "label": "Kimi 2.5 - Via Hive",
           "recommended": false,
           "max_tokens": 32768,
-          "max_context_tokens": 240000
+          "max_context_tokens": 240000,
+          "supports_vision": true
         },
         {
-          "id": "GLM-5",
-          "label": "GLM-5 - Via Hive",
+          "id": "glm-5.1",
+          "label": "GLM-5.1 - Via Hive",
           "recommended": false,
           "max_tokens": 32768,
-          "max_context_tokens": 180000
+          "max_context_tokens": 180000,
+          "pricing_usd_per_mtok": {
+            "input": 1.40,
+            "output": 4.40,
+            "cache_read": 0.26,
+            "cache_creation": 0.0
+          },
+          "supports_vision": false
         }
       ]
     },
@@ -288,35 +357,82 @@
           "label": "GPT-5.4 - Best overall",
           "recommended": true,
           "max_tokens": 128000,
-          "max_context_tokens": 922000
+          "max_context_tokens": 872000,
+          "supports_vision": true
         },
         {
           "id": "anthropic/claude-sonnet-4.6",
           "label": "Claude Sonnet 4.6 - Best coding balance",
           "recommended": false,
           "max_tokens": 64000,
-          "max_context_tokens": 936000
+          "max_context_tokens": 872000,
+          "supports_vision": true
         },
         {
           "id": "anthropic/claude-opus-4.6",
           "label": "Claude Opus 4.6 - Most capable",
           "recommended": false,
           "max_tokens": 128000,
-          "max_context_tokens": 872000
+          "max_context_tokens": 872000,
+          "supports_vision": true
         },
         {
           "id": "google/gemini-3.1-pro-preview-customtools",
           "label": "Gemini 3.1 Pro Preview - Long-context reasoning",
           "recommended": false,
           "max_tokens": 32768,
-          "max_context_tokens": 1048576
+          "max_context_tokens": 872000,
+          "supports_vision": true
         },
         {
-          "id": "deepseek/deepseek-v3.2",
-          "label": "DeepSeek V3.2 - Best value",
-          "recommended": false,
+          "id": "qwen/qwen3.6-plus",
+          "label": "Qwen 3.6 Plus - Strong reasoning",
+          "recommended": true,
           "max_tokens": 32768,
-          "max_context_tokens": 163840
+          "max_context_tokens": 240000,
+          "supports_vision": false
+        },
+        {
+          "id": "z-ai/glm-5v-turbo",
+          "label": "GLM-5V Turbo - Vision capable",
+          "recommended": true,
+          "max_tokens": 32768,
+          "max_context_tokens": 192000,
+          "supports_vision": true
+        },
+        {
+          "id": "z-ai/glm-5.1",
+          "label": "GLM-5.1 - Better but Slower",
+          "recommended": true,
+          "max_tokens": 40960,
+          "max_context_tokens": 192000,
+          "pricing_usd_per_mtok": {
+            "input": 1.40,
+            "output": 4.40,
+            "cache_read": 0.26,
+            "cache_creation": 0.0
+          },
+          "supports_vision": false
+        },
+        {
+          "id": "minimax/minimax-m2.7",
+          "label": "Minimax M2.7 - Minimax flagship",
+          "recommended": false,
+          "max_tokens": 40960,
+          "max_context_tokens": 180000,
+          "pricing_usd_per_mtok": {
+            "input": 0.30,
+            "output": 1.20
+          },
+          "supports_vision": false
+        },
+        {
+          "id": "xiaomi/mimo-v2-pro",
+          "label": "MiMo V2 Pro - Xiaomi multimodal",
+          "recommended": true,
+          "max_tokens": 64000,
+          "max_context_tokens": 240000,
+          "supports_vision": true
         }
       ]
     }
@@ -331,7 +447,7 @@
     "zai_code": {
       "provider": "openai",
       "api_key_env_var": "ZAI_API_KEY",
-      "model": "glm-5",
+      "model": "glm-5.1",
       "max_tokens": 32768,
       "max_context_tokens": 180000,
       "api_base": "https://api.z.ai/api/coding/paas/v4"
@@ -347,8 +463,8 @@
       "provider": "minimax",
       "api_key_env_var": "MINIMAX_API_KEY",
       "model": "MiniMax-M2.7",
-      "max_tokens": 32768,
-      "max_context_tokens": 204800,
+      "max_tokens": 40960,
+      "max_context_tokens": 180800,
       "api_base": "https://api.minimax.io/v1"
     },
     "kimi_code": {
@@ -373,13 +489,13 @@
           "recommended": true
         },
         {
-          "id": "kimi-2.5",
-          "label": "kimi-2.5",
+          "id": "kimi-k2.5",
+          "label": "kimi-k2.5",
           "recommended": false
         },
         {
-          "id": "GLM-5",
-          "label": "GLM-5",
+          "id": "glm-5.1",
+          "label": "glm-5.1",
           "recommended": false
         }
       ]
@@ -397,4 +513,4 @@
       "api_base": "http://localhost:11434"
     }
   }
-}
+}

core/framework/llm/model_catalog.py

@@ -27,6 +27,28 @@ def _require_list(value: Any, path: str) -> list[Any]:
     return value
 
 
+_PRICING_KEYS = ("input", "output", "cache_read", "cache_creation")
+
+
+def _validate_pricing(value: Any, path: str) -> None:
+    """Validate an optional ``pricing_usd_per_mtok`` block.
+
+    Keys are USD-per-million-tokens rates. ``input``/``output`` are required;
+    ``cache_read``/``cache_creation`` are optional. All values must be
+    non-negative numbers. Used as a last-resort fallback when neither the
+    provider nor LiteLLM's catalog reports a cost.
+    """
+    pricing = _require_mapping(value, path)
+    for key in ("input", "output"):
+        if key not in pricing:
+            raise ModelCatalogError(f"{path}.{key} is required")
+    for key, rate in pricing.items():
+        if key not in _PRICING_KEYS:
+            raise ModelCatalogError(f"{path}.{key} is not a recognized pricing field")
+        if not isinstance(rate, (int, float)) or isinstance(rate, bool) or rate < 0:
+            raise ModelCatalogError(f"{path}.{key} must be a non-negative number")
+
+
 def _validate_model_catalog(data: dict[str, Any]) -> dict[str, Any]:
     providers = _require_mapping(data.get("providers"), "providers")
 
@@ -69,6 +91,14 @@ def _validate_model_catalog(data: dict[str, Any]) -> dict[str, Any]:
                 if not isinstance(value, int) or value <= 0:
                     raise ModelCatalogError(f"{model_path}.{key} must be a positive integer")
 
+            pricing = model_map.get("pricing_usd_per_mtok")
+            if pricing is not None:
+                _validate_pricing(pricing, f"{model_path}.pricing_usd_per_mtok")
+
+            supports_vision = model_map.get("supports_vision")
+            if supports_vision is not None and not isinstance(supports_vision, bool):
+                raise ModelCatalogError(f"{model_path}.supports_vision must be a boolean when present")
+
         if not default_found:
             raise ModelCatalogError(
                 f"{provider_path}.default_model={default_model!r} is not present in {provider_path}.models"
@@ -184,6 +214,53 @@ def get_model_limits(provider: str, model_id: str) -> tuple[int, int] | None:
     return int(model["max_tokens"]), int(model["max_context_tokens"])
 
 
+def get_model_pricing(model_id: str) -> dict[str, float] | None:
+    """Return ``pricing_usd_per_mtok`` for a model id, searching all providers.
+
+    Returns ``None`` when the model is absent from the catalog or has no
+    pricing entry. Used by the cost-extraction fallback in ``litellm.py``
+    when the provider response and LiteLLM's catalog both come up empty.
+    """
+    if not model_id:
+        return None
+    for provider_info in load_model_catalog()["providers"].values():
+        for model in provider_info["models"]:
+            if model["id"] == model_id:
+                pricing = model.get("pricing_usd_per_mtok")
+                if pricing is None:
+                    return None
+                return {key: float(rate) for key, rate in pricing.items()}
+    return None
+
+
+def model_supports_vision(model_id: str) -> bool:
+    """Return whether *model_id* supports image inputs per the curated catalog.
+
+    Looks up the bare model id (and the provider-prefix-stripped form) in the
+    catalog. Returns the model's ``supports_vision`` flag when found, defaulting
+    to ``True`` for unknown models or when the flag is absent — assume vision
+    capable for hosted providers, since modern frontier models support images
+    by default and the captioning fallback is more expensive than just letting
+    the provider handle the image.
+    """
+    if not model_id:
+        return True
+
+    candidates = [model_id]
+    if "/" in model_id:
+        candidates.append(model_id.split("/", 1)[1])
+
+    for candidate in candidates:
+        for provider_info in load_model_catalog()["providers"].values():
+            for model in provider_info["models"]:
+                if model["id"] == candidate:
+                    flag = model.get("supports_vision")
+                    if isinstance(flag, bool):
+                        return flag
+                    return True
+    return True
+
+
 def get_preset(preset_id: str) -> dict[str, Any] | None:
     """Return one preset entry."""
     preset = load_model_catalog()["presets"].get(preset_id)

core/framework/llm/provider.py

@@ -10,12 +10,24 @@ from typing import Any
 
 @dataclass
 class LLMResponse:
-    """Response from an LLM call."""
+    """Response from an LLM call.
+
+    ``cached_tokens`` and ``cache_creation_tokens`` are subsets of
+    ``input_tokens`` (providers report them inside ``prompt_tokens``).
+    Surface them for visibility; do not add to a total.
+
+    ``cost_usd`` is the per-call USD cost when the provider / pricing table
+    can produce one (Anthropic, OpenAI, OpenRouter are supported). 0.0 when
+    unknown or unpriced — treat as "unreported", not "free".
+    """
 
     content: str
     model: str
     input_tokens: int = 0
     output_tokens: int = 0
+    cached_tokens: int = 0
+    cache_creation_tokens: int = 0
+    cost_usd: float = 0.0
     stop_reason: str = ""
     raw_response: Any = None
 
@@ -110,19 +122,28 @@ class LLMProvider(ABC):
         response_format: dict[str, Any] | None = None,
         json_mode: bool = False,
         max_retries: int | None = None,
+        system_dynamic_suffix: str | None = None,
     ) -> "LLMResponse":
         """Async version of complete(). Non-blocking on the event loop.
 
         Default implementation offloads the sync complete() to a thread pool.
         Subclasses SHOULD override for native async I/O.
+
+        ``system_dynamic_suffix`` is an optional per-turn tail for providers
+        that honor ``cache_control`` (see LiteLLMProvider for semantics).
+        The default implementation concatenates it onto ``system`` since the
+        sync ``complete()`` path does not support the split.
         """
+        combined_system = system
+        if system_dynamic_suffix:
+            combined_system = f"{system}\n\n{system_dynamic_suffix}" if system else system_dynamic_suffix
         loop = asyncio.get_running_loop()
         return await loop.run_in_executor(
             None,
             partial(
                 self.complete,
                 messages=messages,
-                system=system,
+                system=combined_system,
                 tools=tools,
                 max_tokens=max_tokens,
                 response_format=response_format,
@@ -137,6 +158,7 @@ class LLMProvider(ABC):
         system: str = "",
         tools: list[Tool] | None = None,
         max_tokens: int = 4096,
+        system_dynamic_suffix: str | None = None,
     ) -> AsyncIterator["StreamEvent"]:
         """
         Stream a completion as an async iterator of StreamEvents.
@@ -147,6 +169,9 @@ class LLMProvider(ABC):
         Tool orchestration is the CALLER's responsibility:
         - Caller detects ToolCallEvent, executes tool, adds result
           to messages, calls stream() again.
+
+        ``system_dynamic_suffix`` is forwarded to ``acomplete``; see its
+        docstring for the two-block split semantics.
         """
         from framework.llm.stream_events import (
             FinishEvent,
@@ -159,6 +184,7 @@ class LLMProvider(ABC):
             system=system,
             tools=tools,
             max_tokens=max_tokens,
+            system_dynamic_suffix=system_dynamic_suffix,
         )
         yield TextDeltaEvent(content=response.content, snapshot=response.content)
         yield TextEndEvent(full_text=response.content)
@@ -166,6 +192,9 @@ class LLMProvider(ABC):
             stop_reason=response.stop_reason,
             input_tokens=response.input_tokens,
             output_tokens=response.output_tokens,
+            cached_tokens=response.cached_tokens,
+            cache_creation_tokens=response.cache_creation_tokens,
+            cost_usd=response.cost_usd,
             model=response.model,
         )
 

core/framework/llm/stream_events.py

@@ -65,13 +65,23 @@ class ReasoningDeltaEvent:
 
 @dataclass(frozen=True)
 class FinishEvent:
-    """The LLM has finished generating."""
+    """The LLM has finished generating.
+
+    ``cached_tokens`` and ``cache_creation_tokens`` are subsets of
+    ``input_tokens`` — providers count both inside ``prompt_tokens`` already.
+    Surface them separately for visibility; never add to a total.
+
+    ``cost_usd`` is the per-turn USD cost when the provider or LiteLLM's
+    pricing table supplies one; 0.0 means unreported (not free).
+    """
 
     type: Literal["finish"] = "finish"
     stop_reason: str = ""
     input_tokens: int = 0
     output_tokens: int = 0
     cached_tokens: int = 0
+    cache_creation_tokens: int = 0
+    cost_usd: float = 0.0
     model: str = ""
 
 

core/framework/loader/agent_loader.py

@@ -9,7 +9,7 @@ from datetime import UTC
 from pathlib import Path
 from typing import Any
 
-from framework.config import get_hive_config, get_preferred_model
+from framework.config import HIVE_HOME as _HIVE_HOME, get_hive_config, get_preferred_model
 from framework.credentials.validation import (
     ensure_credential_key_env as _ensure_credential_key_env,
 )
@@ -558,7 +558,7 @@ ANTIGRAVITY_IDE_STATE_DB = (
 # Linux fallback for the IDE state DB
 ANTIGRAVITY_IDE_STATE_DB_LINUX = Path.home() / ".config" / "Antigravity" / "User" / "globalStorage" / "state.vscdb"
 # Antigravity credentials stored by native OAuth implementation
-ANTIGRAVITY_AUTH_FILE = Path.home() / ".hive" / "antigravity-accounts.json"
+ANTIGRAVITY_AUTH_FILE = _HIVE_HOME / "antigravity-accounts.json"
 
 ANTIGRAVITY_OAUTH_TOKEN_URL = "https://oauth2.googleapis.com/token"
 _ANTIGRAVITY_TOKEN_LIFETIME_SECS = 3600  # Google access tokens expire in 1 hour
@@ -1389,7 +1389,7 @@ class AgentLoader:
         )
 
         if storage_path is None:
-            storage_path = Path.home() / ".hive" / "agents" / agent_path.name / worker_name
+            storage_path = _HIVE_HOME / "agents" / agent_path.name / worker_name
             storage_path.mkdir(parents=True, exist_ok=True)
 
         runner = cls(
@@ -1503,6 +1503,7 @@ class AgentLoader:
         from framework.pipeline.stages.mcp_registry import McpRegistryStage
         from framework.pipeline.stages.skill_registry import SkillRegistryStage
         from framework.skills.config import SkillsConfig
+        from framework.skills.discovery import ExtraScope
 
         configure_logging(level="INFO", format="auto")
 
@@ -1545,6 +1546,19 @@ class AgentLoader:
                     default_skills=getattr(self, "_agent_default_skills", None),
                     skills=getattr(self, "_agent_skills", None),
                 ),
+                # Surface the colony's flat ``skills/`` directory as a
+                # ``colony_ui`` extra scope so SKILL.md files written there
+                # by ``create_colony`` (or the HTTP routes) are picked up
+                # with correct provenance. The legacy nested
+                # ``<colony>/.hive/skills/`` path is still picked up via
+                # project-scope auto-discovery (project_root above).
+                extra_scope_dirs=[
+                    ExtraScope(
+                        directory=self.agent_path / "skills",
+                        label="colony_ui",
+                        priority=3,
+                    )
+                ],
             ),
         ]
 

core/framework/loader/cli.py

@@ -21,6 +21,7 @@ import os
 import shutil
 import subprocess
 import sys
+import threading
 from pathlib import Path
 from typing import Any
 from urllib import error as urlerror, parse as urlparse, request as urlrequest
@@ -214,7 +215,13 @@ def cmd_serve(args: argparse.Namespace) -> int:
 
 def cmd_open(args: argparse.Namespace) -> int:
     """Start the HTTP server and open the dashboard in the browser."""
-    _ping_hive_gateway_availability("hive-open")
+    # Don't block local startup on a best-effort analytics probe.
+    threading.Thread(
+        target=_ping_hive_gateway_availability,
+        args=("hive-open",),
+        daemon=True,
+        name="hive-open-gateway-ping",
+    ).start()
     args.open = True
     return cmd_serve(args)
 

core/framework/loader/mcp_registry.py

@@ -51,6 +51,14 @@ _DEFAULT_LOCAL_SERVERS: dict[str, dict[str, Any]] = {
         "description": "File I/O: read, write, edit, search, list, run commands",
         "args": ["run", "python", "files_server.py", "--stdio"],
     },
+    "terminal-tools": {
+        "description": "Terminal capabilities",
+        "args": ["run", "python", "terminal_tools_server.py", "--stdio"],
+    },
+    "chart-tools": {
+        "description": "BI/financial chart + diagram rendering: ECharts, Mermaid",
+        "args": ["run", "python", "chart_tools_server.py", "--stdio"],
+    },
 }
 
 # Aliases that earlier versions of ensure_defaults wrote under the wrong name.
@@ -58,14 +66,22 @@ _DEFAULT_LOCAL_SERVERS: dict[str, dict[str, Any]] = {
 # name so the active agents (queen, credential_tester) can find their tools.
 _STALE_DEFAULT_ALIASES: dict[str, str] = {
     "hive_tools": "hive-tools",
+    # 2026-04-30: shell-tools renamed to terminal-tools. Drop the stale name
+    # on next ensure_defaults() so the queen's allowlist (which now includes
+    # @server:terminal-tools) actually finds a server with the new name.
+    "terminal-tools": "shell-tools",
 }
 
 
 class MCPRegistry:
-    """Manages local MCP server state in ~/.hive/mcp_registry/."""
+    """Manages local MCP server state in $HIVE_HOME/mcp_registry/."""
 
     def __init__(self, base_path: Path | None = None):
-        self._base = base_path or Path.home() / ".hive" / "mcp_registry"
+        if base_path is None:
+            from framework.config import HIVE_HOME
+
+            base_path = HIVE_HOME / "mcp_registry"
+        self._base = base_path
         self._installed_path = self._base / "installed.json"
         self._config_path = self._base / "config.json"
         self._cache_dir = self._base / "cache"
@@ -73,7 +89,30 @@ class MCPRegistry:
     # ── Initialization ──────────────────────────────────────────────
 
     def initialize(self) -> None:
-        """Create directory structure and default files if missing."""
+        """Create directory structure, default files, and seed bundled servers.
+
+        Every read path (queen orchestrator, pipeline stage, CLI, routes)
+        calls this — keeping the seeding here means a fresh ``HIVE_HOME``
+        (e.g. the desktop's per-user dir under ``~/.config/Hive/users/<hash>/``
+        or ``~/Library/Application Support/Hive/users/<hash>/``) is always
+        populated with ``hive_tools`` / ``gcu-tools`` / ``files-tools`` /
+        ``shell-tools`` before any agent code reads ``installed.json``.
+        Without this, ``load_agent_selection()`` resolves an empty registry
+        and emits "Server X requested but not installed" warnings even
+        though the server is bundled.
+
+        Idempotent — already-installed entries are left untouched.
+        """
+        self._bootstrap_io()
+        self._seed_defaults()
+
+    def _bootstrap_io(self) -> None:
+        """Create the registry directory + empty config/installed files.
+
+        Split out from ``initialize()`` so ``_seed_defaults()`` can call it
+        without re-entering the seeding logic (which would recurse via
+        ``_read_installed()`` → ``initialize()``).
+        """
         self._base.mkdir(parents=True, exist_ok=True)
         self._cache_dir.mkdir(parents=True, exist_ok=True)
 
@@ -84,21 +123,33 @@ class MCPRegistry:
             self._write_json(self._installed_path, {"servers": {}})
 
     def ensure_defaults(self) -> list[str]:
-        """Seed the built-in local MCP servers (hive-tools, gcu-tools, files-tools).
+        """Public alias kept for the ``hive mcp init`` CLI command.
 
-        Idempotent — servers already present are left untouched. Skips seeding
-        entirely when the source-tree ``tools/`` directory cannot be located
-        (e.g. when Hive is installed from a wheel rather than a checkout).
-
-        Returns the list of names that were newly registered.
+        Returns the list of newly-registered server names so the CLI can
+        print them. Same idempotent seeding logic as ``initialize()``.
         """
-        self.initialize()
+        self._bootstrap_io()
+        return self._seed_defaults()
 
+    def _seed_defaults(self) -> list[str]:
+        """Idempotently register the bundled default local servers.
+
+        Skips entirely when the source-tree ``tools/`` directory cannot
+        be located (e.g. wheel installs). Returns the list of names that
+        were newly registered.
+
+        Also runs a self-heal pass over already-registered defaults: if an
+        entry's stdio cwd is unreachable on this machine (e.g. the registry
+        was copied from another developer's box and points at their
+        ``/Users/<them>/...`` path), the entry is overwritten with the
+        canonical config so the queen can actually spawn it. The user's
+        ``enabled`` toggle and ``overrides`` are preserved.
+        """
         # parents: [0]=loader, [1]=framework, [2]=core, [3]=repo root
         tools_dir = Path(__file__).resolve().parents[3] / "tools"
         if not tools_dir.is_dir():
             logger.debug(
-                "MCPRegistry.ensure_defaults: tools dir %s missing; skipping default seed",
+                "MCPRegistry._seed_defaults: tools dir %s missing; skipping default seed",
                 tools_dir,
             )
             return []
@@ -115,14 +166,37 @@ class MCPRegistry:
         for canonical, stale in _STALE_DEFAULT_ALIASES.items():
             if stale in existing and canonical not in existing:
                 logger.info(
-                    "MCPRegistry.ensure_defaults: removing stale alias '%s' (canonical: '%s')",
+                    "MCPRegistry._seed_defaults: removing stale alias '%s' (canonical: '%s')",
                     stale,
                     canonical,
                 )
                 del existing[stale]
                 mutated = True
+
+        repaired: list[str] = []
+        for name, spec in _DEFAULT_LOCAL_SERVERS.items():
+            entry = existing.get(name)
+            if entry is None:
+                continue
+            if self._default_entry_runnable(entry, tools_dir, list(spec["args"])):
+                continue
+            existing[name] = self._build_default_entry(
+                name=name,
+                spec=spec,
+                cwd=cwd,
+                preserve_from=entry,
+            )
+            repaired.append(name)
+            mutated = True
+
         if mutated:
             self._write_installed(data)
+        if repaired:
+            logger.warning(
+                "MCPRegistry._seed_defaults: repaired %d default server(s) with unreachable cwd/script: %s",
+                len(repaired),
+                repaired,
+            )
 
         for name, spec in _DEFAULT_LOCAL_SERVERS.items():
             if name in existing:
@@ -138,12 +212,97 @@ class MCPRegistry:
                 )
                 added.append(name)
             except MCPError as exc:
-                logger.warning("MCPRegistry.ensure_defaults: failed to seed '%s': %s", name, exc)
+                logger.warning("MCPRegistry._seed_defaults: failed to seed '%s': %s", name, exc)
 
         if added:
             logger.info("MCPRegistry: seeded default local servers: %s", added)
         return added
 
+    @staticmethod
+    def _default_entry_runnable(entry: dict, tools_dir: Path, canonical_args: list[str]) -> bool:
+        """Return True iff ``entry`` can plausibly be spawned on this machine.
+
+        Checks:
+        - transport is stdio (only stdio defaults exist today; non-stdio
+          gets a free pass since we have nothing to compare against)
+        - stdio.cwd is an existing directory
+        - the entry script (the first ``.py`` arg, e.g. ``files_server.py``)
+          exists relative to that cwd
+
+        We deliberately do NOT spawn the subprocess here — this runs on
+        every read path and must be cheap. A filesystem reachability
+        check catches the cross-machine `cwd` drift that is the common
+        failure, without flapping on transient runtime errors.
+        """
+        transport = entry.get("transport") or "stdio"
+        if transport != "stdio":
+            return True
+        manifest = entry.get("manifest") or {}
+        stdio = manifest.get("stdio") or {}
+        cwd_str = stdio.get("cwd")
+        if not cwd_str:
+            return False
+        cwd_path = Path(cwd_str)
+        if not cwd_path.is_dir():
+            return False
+        # Find the script: the first arg ending in .py, falling back to the
+        # canonical spec if the registered args are unrecognizable. Modules
+        # invoked via `python -m foo.bar` (no .py arg) are accepted as long
+        # as the cwd exists — we can't cheaply prove the module imports.
+        registered_args = stdio.get("args") or []
+        script: str | None = next(
+            (a for a in registered_args if isinstance(a, str) and a.endswith(".py")),
+            None,
+        )
+        if script is None:
+            script = next(
+                (a for a in canonical_args if isinstance(a, str) and a.endswith(".py")),
+                None,
+            )
+        if script is None:
+            return True
+        return (cwd_path / script).is_file()
+
+    @classmethod
+    def _build_default_entry(
+        cls,
+        *,
+        name: str,
+        spec: dict[str, Any],
+        cwd: str,
+        preserve_from: dict | None,
+    ) -> dict:
+        """Construct a fresh canonical entry for a default server.
+
+        When ``preserve_from`` is provided, carries over the user's
+        ``enabled`` flag and ``overrides`` so a deliberate disable or
+        custom env var survives the repair.
+        """
+        manifest = {
+            "name": name,
+            "description": spec["description"],
+            "transport": {"supported": ["stdio"], "default": "stdio"},
+            "stdio": {
+                "command": "uv",
+                "args": list(spec["args"]),
+                "env": {},
+                "cwd": cwd,
+            },
+        }
+        entry = cls._make_entry(
+            source="local",
+            manifest=manifest,
+            transport="stdio",
+            installed_by="hive mcp init (auto-repair)",
+        )
+        if preserve_from is not None:
+            if "enabled" in preserve_from:
+                entry["enabled"] = bool(preserve_from["enabled"])
+            prior_overrides = preserve_from.get("overrides")
+            if isinstance(prior_overrides, dict):
+                entry["overrides"] = prior_overrides
+        return entry
+
     # ── Internal I/O ────────────────────────────────────────────────
 
     def _read_installed(self) -> dict:

core/framework/loader/tool_registry.py

@@ -71,25 +71,36 @@ class ToolRegistry:
         {
             # File system reads
             "read_file",
-            "list_directory",
-            "grep",
-            "glob",
-            # Web reads
-            "web_search",
-            "web_fetch",
+            "search_files",
+            "pdf_read",
+            # Terminal reads (rg / find / output buffer polling — neither
+            # changes process state)
+            "terminal_rg",
+            "terminal_find",
+            "terminal_output_get",
+            # Web / research reads (re-issuable, side-effect-free fetches)
+            "web_scrape",
+            "search_papers",
+            "search_wikipedia",
+            "download_paper",
             # Browser read-only snapshots (mutate-free observations)
             "browser_screenshot",
             "browser_snapshot",
             "browser_console",
             "browser_get_text",
-            # Background bash polling - reads output buffers only, does
-            # not touch the subprocess itself.
-            "bash_output",
+            "browser_html",
+            "browser_get_attribute",
+            "browser_get_rect",
         }
     )
 
-    # Credential directory used for change detection
-    _CREDENTIAL_DIR = Path("~/.hive/credentials/credentials").expanduser()
+    # Credential directory used for change detection. Resolved at attribute
+    # access so HIVE_HOME overrides (set by the desktop) are honoured.
+    @property
+    def _CREDENTIAL_DIR(self) -> Path:
+        from framework.config import HIVE_HOME
+
+        return HIVE_HOME / "credentials" / "credentials"
 
     def __init__(self):
         self._tools: dict[str, RegisteredTool] = {}
@@ -457,7 +468,7 @@ class ToolRegistry:
             else:
                 resolved_cwd = (base_dir / cwd).resolve()
 
-        # Find .py script in args (e.g. coder_tools_server.py, files_server.py)
+        # Find .py script in args (e.g. files_server.py)
         script_name = None
         for i, arg in enumerate(args):
             if isinstance(arg, str) and arg.endswith(".py"):
@@ -497,24 +508,6 @@ class ToolRegistry:
             config["cwd"] = str(resolved_cwd)
             return config
 
-        # For coder_tools_server, inject --project-root so reads land
-        # in the expected workspace (hive repo, for framework skills
-        # and docs), and inject --write-root so writes land under
-        # ~/.hive/workspace/ instead of polluting the git checkout
-        # with queen-authored skills, ledgers, and scripts. Without
-        # the split, every ``write_file`` call from the queen landed
-        # in the hive repo root.
-        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])
-            if "--write-root" not in args:
-                _write_root = Path.home() / ".hive" / "workspace"
-                _write_root.mkdir(parents=True, exist_ok=True)
-                args.extend(["--write-root", str(_write_root)])
-            config["args"] = args
-
         if os.name == "nt":
             # Windows: cwd=None avoids WinError 267; use absolute script path
             config["cwd"] = None
@@ -581,8 +574,18 @@ class ToolRegistry:
         tool_cap: int | None = None,
         log_collisions: bool = False,
     ) -> tuple[bool, int, str | None]:
-        """Register a single MCP server with one retry for transient failures."""
+        """Register a single MCP server with one retry for transient failures.
+
+        When ``preserve_existing_tools=True`` and the server's tools are
+        already present from a prior registration, ``register_mcp_server``
+        returns ``count=0`` because every tool was shadowed. That's a
+        no-op success, not a failure — don't retry / warn in that case.
+        Otherwise a duplicate-init path (e.g. a worker spawn re-loading
+        the MCP servers the queen already registered) spams shadow
+        warnings, sleeps 2s, and retries for no reason.
+        """
         name = server_config.get("name", "unknown")
+        already_loaded = bool(self._mcp_server_tools.get(name))
         last_error: str | None = None
 
         for attempt in range(2):
@@ -595,6 +598,10 @@ class ToolRegistry:
                 )
                 if count > 0:
                     return True, count, None
+                if already_loaded and preserve_existing_tools:
+                    # All tools shadowed by the prior registration of
+                    # the same server — nothing to do, server is usable.
+                    return True, 0, None
                 last_error = "registered 0 tools"
             except Exception as exc:
                 last_error = str(exc)
@@ -762,12 +769,18 @@ class ToolRegistry:
                 if preserve_existing_tools and mcp_tool.name in self._tools:
                     if log_collisions:
                         origin_server = self._find_mcp_origin_server_for_tool(mcp_tool.name) or "<existing>"
-                        logger.warning(
-                            "MCP tool '%s' from '%s' shadowed by '%s' (loaded first)",
-                            mcp_tool.name,
-                            server_name,
-                            origin_server,
-                        )
+                        # Don't warn when a server is being re-registered
+                        # by itself — that's a redundant-init case (e.g.
+                        # the same tool_registry seeing the same server
+                        # twice via pooled reconnect), not a real
+                        # cross-server shadow worth flagging.
+                        if origin_server != server_name:
+                            logger.warning(
+                                "MCP tool '%s' from '%s' shadowed by '%s' (loaded first)",
+                                mcp_tool.name,
+                                server_name,
+                                origin_server,
+                            )
                     # Skip registration; do not update MCP tool bookkeeping for this server.
                     continue
 

core/framework/orchestrator/client_io.py

@@ -89,10 +89,12 @@ class ActiveNodeClientIO(NodeClientIO):
         self._input_result = None
 
         if self._event_bus is not None:
+            # `prompt` is consumed by the caller separately (callers emit
+            # it as a text delta when needed). The event only carries the
+            # structured questions payload for widget rendering.
             await self._event_bus.emit_client_input_requested(
                 stream_id=self.node_id,
                 node_id=self.node_id,
-                prompt=prompt,
                 execution_id=self._execution_id or None,
             )
 

core/framework/orchestrator/context.py

@@ -29,9 +29,7 @@ _ALWAYS_AVAILABLE_TOOLS: frozenset[str] = frozenset(
         "read_file",
         "write_file",
         "edit_file",
-        "list_directory",
         "search_files",
-        "hashline_edit",
         "set_output",
         "escalate",
     }

core/framework/orchestrator/gcu.py

@@ -9,8 +9,8 @@ Nodes that need browser access declare ``tools: {policy: "all"}`` in their
 agent.json config.
 
 Note: the canonical source of truth for browser automation guidance is
-the ``browser-automation`` default skill at
-``core/framework/skills/_default_skills/browser-automation/SKILL.md``.
+the ``browser-automation`` preset skill at
+``core/framework/skills/_preset_skills/browser-automation/SKILL.md``.
 Activate that skill for the full decision tree. This module holds a
 compact subset suitable for direct inlining into a node's system prompt
 when a skill activation is not desired.
@@ -26,41 +26,47 @@ Follow these rules for reliable, efficient browser interaction.
 - **`browser_snapshot`** — compact accessibility tree. Fast, cheap, good
   for static / text-heavy pages where the DOM matches what's visually
   rendered (docs, forms, search results, settings pages).
-- **`browser_screenshot`** — visual capture + scale metadata. Use on any
-  complex SPA (LinkedIn, X / Twitter, Reddit, Gmail, Notion, Slack,
-  Discord) and on any site using shadow DOM or virtual scrolling. On
-  those pages, snapshot refs go stale in seconds, shadow contents
-  aren't in the AX tree, and virtual-scrolled elements disappear from
-  the tree entirely — screenshots are the only reliable way to orient.
+- **`browser_screenshot`** — visual capture + scale metadata. Use when
+  the snapshot does not show the thing you need, when refs look stale,
+  or when you need visual position/layout to act. This is common on
+  complex SPAs (LinkedIn, X / Twitter, Reddit, Gmail, Notion, Slack,
+  Discord), shadow DOM, and virtual scrolling.
 
-Neither tool is "preferred" universally — they're for different jobs.
-Default to snapshot on static pages, screenshot on SPAs and
-shadow-heavy sites. Interaction tools (click/type/fill/scroll) return
-a snapshot automatically, so don't call `browser_snapshot` separately
-after an interaction unless you need a fresh view.
+Use snapshot first for structure and ordinary controls; switch to
+screenshot when snapshot can't find or verify the target. Interaction
+tools (`browser_click`, `browser_type`, `browser_type_focused`,
+`browser_scroll`) wait 0.5 s for the page to settle
+after a successful action, then attach a fresh snapshot under the
+`snapshot` key of their result — so don't call `browser_snapshot`
+separately after an interaction unless you need a newer view. Tune
+with `auto_snapshot_mode`: `"default"` (full tree) is the default;
+`"simple"` trims unnamed structural nodes; `"interactive"` returns
+only controls (tightest token footprint); `"off"` skips the capture
+entirely — use when batching several interactions.
 
 Only fall back to `browser_get_text` for extracting small elements by
 CSS selector.
 
-## Coordinates: always CSS pixels
+## Coordinates
 
-Chrome DevTools Protocol `Input.dispatchMouseEvent` takes **CSS
-pixels**, not physical pixels. This is critical and often gets wrong:
+Every browser tool that takes or returns coordinates operates in
+**fractions of the viewport (0..1 for both axes)**. Read a target's
+proportional position off `browser_screenshot` — "this button is
+~35% from the left, ~20% from the top" → pass `(0.35, 0.20)`.
+`browser_get_rect` and `browser_shadow_query` return `rect.cx` /
+`rect.cy` as fractions in the same space. The tools handle the
+fraction → CSS-px multiplication internally; you do not need to
+track image pixels, DPR, or any scale factor.
 
-| Tool | Unit |
-|---|---|
-| `browser_click_coordinate(x, y)` | **CSS pixels** |
-| `browser_hover_coordinate(x, y)` | **CSS pixels** |
-| `browser_press_at(x, y, key)` | **CSS pixels** |
-| `getBoundingClientRect()` | already CSS pixels — pass straight through |
-| `browser_coords(img_x, img_y)` | returns `css_x/y` (use this) and `physical_x/y` (debug only) |
+Why fractions: every vision model (Claude, GPT-4o, Gemini, local
+VLMs) resizes or tiles images differently before the model sees the
+pixels. Proportions survive every such transform; pixel coordinates
+only "work" per-model and break when you swap backends.
 
-**Always use `css_x/y`** from `browser_coords`. Feeding `physical_x/y`
-on a HiDPI display overshoots by `DPR×` — clicks land DPR times too
-far right and down. On a DPR=1.6 display that's 60% off.
-
-Never multiply `getBoundingClientRect()` by `devicePixelRatio` — it's
-already in the right unit.
+Avoid raw `browser_evaluate` + `getBoundingClientRect()` for coord
+lookup — that returns CSS px and will be wrong when fed to click
+tools. Prefer `browser_get_rect` / `browser_shadow_query`, which
+return fractions.
 
 ## Rich-text editors (X, LinkedIn DMs, Gmail, Reddit, Slack, Discord)
 
@@ -70,10 +76,12 @@ ProseMirror only register input as "real" after a native pointer-
 sourced focus event; JS `.focus()` is not enough. Without a real click
 first, the editor stays empty and the send button stays disabled.
 
-`browser_type` now does this automatically — it clicks the element,
-then inserts text via CDP `Input.insertText` (IME-commit style), which
-rich editors accept cleanly. Before clicking send, verify the submit
-button's `disabled` / `aria-disabled` state via `browser_evaluate`.
+`browser_type` does this automatically when you have a selector — it
+clicks the element, then inserts text via CDP `Input.insertText`.
+For shadow-DOM inputs where selectors can't reach, use
+`browser_click_coordinate` to focus, then `browser_type_focused(text=...)`
+to type into the active element. Before clicking send, verify the
+submit button's `disabled` / `aria-disabled` state via `browser_evaluate`.
 
 ## Shadow DOM
 
@@ -86,12 +94,11 @@ reach shadow elements transparently.
 
 **Shadow-heavy site workflow:**
 1. `browser_screenshot()` → visual image
-2. Identify target visually → image coordinate
-3. `browser_coords(x, y)` → CSS px
-4. `browser_click_coordinate(css_x, css_y)` → lands via native hit
-   test; inputs get focused regardless of shadow depth
-5. Type via `browser_type` or, if the selector path can't reach the
-   element, dispatch keys to the focused element
+2. Identify target visually → pixel `(x, y)` read straight off the image
+3. `browser_click_coordinate(x, y)` → lands via native hit test;
+   inputs get focused regardless of shadow depth
+4. Type via `browser_type_focused` (no selector needed — types into the
+   already-focused element), or `browser_type` if you have a selector
 
 For selector-style access when you know the shadow path:
 `browser_shadow_query("#interop-outlet >>> #msg-overlay >>> p")` —
@@ -133,8 +140,9 @@ shortcut dispatcher requires both), then releases in reverse order.
 ## Tab management
 
 Close tabs as soon as you're done with them — not only at the end of
-the task. `browser_close(target_id=...)` for one, `browser_close_finished()`
-for a full cleanup. Never accumulate more than 3 open tabs.
+the task. Use `browser_close(tab_id=...)` (or no arg to close the
+active tab); call it for each tab when cleaning up after a multi-tab
+workflow. Never accumulate more than 3 open tabs.
 `browser_tabs` reports an `origin` field: `"agent"` (you own it, close
 when done), `"popup"` (close after extracting), `"startup"`/`"user"`
 (leave alone).
@@ -150,7 +158,7 @@ cookie consent banners if they block content.
 - If `browser_snapshot` fails, try `browser_get_text` with a narrow
   selector as fallback.
 - If `browser_open` fails or the page seems stale, `browser_stop` →
-  `browser_start` → retry.
+  `browser_open(url)` to lazy-create a fresh context.
 
 ## `browser_evaluate`
 

core/framework/orchestrator/node.py

@@ -543,6 +543,10 @@ class NodeContext:
     # Dynamic memory provider — when set, EventLoopNode rebuilds the
     # system prompt with the latest memory block each iteration.
     dynamic_memory_provider: Any = None  # Callable[[], str] | None
+    # Surgical skills-catalog refresh, same contract as AgentContext's
+    # field of the same name. Lets workers pick up UI-driven skill
+    # toggles without rebuilding the full system prompt each turn.
+    dynamic_skills_catalog_provider: Any = None  # Callable[[], str] | None
 
     # Skill system prompts — injected by the skill discovery pipeline
     skills_catalog_prompt: str = ""  # Available skills XML catalog

core/framework/orchestrator/orchestrator.py

@@ -331,10 +331,10 @@ class Orchestrator:
 
         # Strip tool names that aren't registered in this runtime instead of
         # hard-failing. The worker is forked from the queen's tool snapshot
-        # which may include MCP tools the worker's runtime doesn't load (e.g.
-        # coder-tools agent-management tools). Blocking the worker on missing
-        # tools leaves the queen stranded mid-task; stripping + warning lets
-        # the worker proceed with what it does have.
+        # which may include MCP tools the worker's runtime doesn't load.
+        # Blocking the worker on missing tools leaves the queen stranded
+        # mid-task; stripping + warning lets the worker proceed with what
+        # it does have.
         for node in graph.nodes:
             if node.id not in reachable:
                 continue
@@ -683,11 +683,10 @@ class Orchestrator:
         # Set per-execution data_dir and agent_id so data tools and
         # spillover files share the same session-scoped directory, and
         # so MCP tools whose server-side schemas mark agent_id as a
-        # required field (list_dir, hashline_edit, replace_file_content,
-        # execute_command_tool, …) get a valid value injected even on
-        # registry instances where agent_loader.setup() didn't populate
-        # the session_context. Without this, FastMCP rejects those
-        # calls with "agent_id is a required property".
+        # required field get a valid value injected even on registry
+        # instances where agent_loader.setup() didn't populate the
+        # session_context. Without this, FastMCP rejects those calls
+        # with "agent_id is a required property".
         _ctx_token = None
         if self._storage_path:
             from framework.loader.tool_registry import ToolRegistry

core/framework/pipeline/stages/mcp_registry.py

@@ -44,6 +44,9 @@ class McpRegistryStage(PipelineStage):
         from framework.loader.mcp_registry import MCPRegistry
         from framework.orchestrator.files import FILES_MCP_SERVER_NAME
 
+        # Bundled defaults (hive_tools / gcu-tools / files-tools / shell-tools)
+        # are seeded inside MCPRegistry.initialize(); resolve_for_agent below
+        # will find them even on a fresh HIVE_HOME.
         registry = MCPRegistry()
         mcp_loaded = False
 

core/framework/pipeline/stages/skill_registry.py

@@ -26,11 +26,15 @@ class SkillRegistryStage(PipelineStage):
         project_root: str | Path | None = None,
         interactive: bool = True,
         skills_config: Any = None,
+        extra_scope_dirs: list[Any] | None = None,
         **kwargs: Any,
     ) -> None:
         self._project_root = Path(project_root) if project_root else None
         self._interactive = interactive
         self._skills_config = skills_config
+        # Optional list of ExtraScope entries layered between user and
+        # project scope (e.g. ``colony_ui`` for a colony agent's skills/).
+        self._extra_scope_dirs = list(extra_scope_dirs) if extra_scope_dirs else []
         self.skills_manager: Any = None
 
     async def initialize(self) -> None:
@@ -41,6 +45,7 @@ class SkillRegistryStage(PipelineStage):
             skills_config=self._skills_config or SkillsConfig(),
             project_root=self._project_root,
             interactive=self._interactive,
+            extra_scope_dirs=self._extra_scope_dirs,
         )
         self.skills_manager = SkillsManager(config)
         self.skills_manager.load()

core/framework/runtime/tests/test_forced_cancel_dual_execution.py

@@ -0,0 +1,180 @@
+"""Regression tests for forced cancellation overlap in ExecutionStream."""
+
+from __future__ import annotations
+
+import asyncio
+from types import SimpleNamespace
+from unittest.mock import MagicMock
+
+import pytest
+
+from framework.host.event_bus import AgentEvent, EventBus, EventType
+from framework.host.execution_manager import (
+    EntryPointSpec,
+    ExecutionAlreadyRunningError,
+    ExecutionManager,
+)
+from framework.orchestrator.edge import GraphSpec
+from framework.orchestrator.goal import Goal
+from framework.orchestrator.orchestrator import ExecutionResult
+
+
+def _build_stream(tmp_path, *, event_bus: EventBus | None = None) -> ExecutionManager:
+    graph = GraphSpec(
+        id="test-graph",
+        goal_id="goal-1",
+        version="1.0.0",
+        entry_node="start",
+        entry_points={"start": "start"},
+        terminal_nodes=[],
+        pause_nodes=[],
+        nodes=[],
+        edges=[],
+    )
+    goal = Goal(id="goal-1", name="goal-1", description="test goal")
+    entry_spec = EntryPointSpec(
+        id="webhook",
+        name="Webhook",
+        entry_node="start",
+        trigger_type="webhook",
+        isolation_level="shared",
+        max_concurrent=1,
+    )
+
+    storage = SimpleNamespace(base_path=tmp_path)
+    stream = ExecutionManager(
+        stream_id="webhook",
+        entry_spec=entry_spec,
+        graph=graph,
+        goal=goal,
+        state_manager=MagicMock(),
+        storage=storage,
+        outcome_aggregator=MagicMock(),
+        event_bus=event_bus,
+    )
+    stream._running = True
+    return stream
+
+
+def _install_blocking_executor(monkeypatch, release: asyncio.Event) -> None:
+    class BlockingExecutor:
+        def __init__(self, *args, **kwargs):
+            self.node_registry = {}
+
+        async def execute(self, *args, **kwargs):
+            while True:
+                try:
+                    await release.wait()
+                    break
+                except asyncio.CancelledError:
+                    continue
+            return ExecutionResult(success=True, output={"ok": True})
+
+    monkeypatch.setattr("framework.host.execution_manager.Orchestrator", BlockingExecutor)
+
+
+@pytest.mark.asyncio
+async def test_forced_cancel_timeout_keeps_stream_locked_until_task_exit(tmp_path, monkeypatch):
+    event_bus = EventBus()
+    stream = _build_stream(tmp_path, event_bus=event_bus)
+    release = asyncio.Event()
+    _install_blocking_executor(monkeypatch, release)
+
+    started_events: list[AgentEvent] = []
+    first_started = asyncio.Event()
+    second_started = asyncio.Event()
+
+    async def on_started(event: AgentEvent) -> None:
+        started_events.append(event)
+        if len(started_events) == 1:
+            first_started.set()
+        elif len(started_events) == 2:
+            second_started.set()
+
+    event_bus.subscribe(
+        event_types=[EventType.EXECUTION_STARTED],
+        handler=on_started,
+        filter_stream="webhook",
+    )
+
+    async def immediate_timeout(_tasks, timeout=None):
+        return set(), set(_tasks)
+
+    execution_id = await stream.execute({}, session_state={"resume_session_id": "session-1"})
+    await asyncio.wait_for(first_started.wait(), timeout=1)
+
+    old_task = stream._execution_tasks[execution_id]
+    monkeypatch.setattr("framework.host.execution_manager.asyncio.wait", immediate_timeout)
+
+    try:
+        cancelled = await stream.cancel_execution(execution_id, reason="forced timeout")
+
+        assert cancelled == "cancelling"
+        assert execution_id in stream._execution_tasks
+        assert execution_id in stream._active_executions
+        assert execution_id in stream._completion_events
+        assert stream._active_executions[execution_id].status == "cancelling"
+        assert not old_task.done()
+
+        with pytest.raises(ExecutionAlreadyRunningError):
+            await stream.execute({}, session_state={"resume_session_id": execution_id})
+
+        assert len(started_events) == 1
+
+        release.set()
+        await asyncio.wait_for(old_task, timeout=1)
+
+        restarted_id = await stream.execute({}, session_state={"resume_session_id": execution_id})
+        assert restarted_id == execution_id
+        await asyncio.wait_for(second_started.wait(), timeout=1)
+    finally:
+        release.set()
+        await asyncio.gather(*stream._execution_tasks.values(), return_exceptions=True)
+
+
+@pytest.mark.asyncio
+async def test_repeated_forced_restarts_do_not_accumulate_parallel_tasks(tmp_path, monkeypatch):
+    event_bus = EventBus()
+    stream = _build_stream(tmp_path, event_bus=event_bus)
+    release = asyncio.Event()
+    _install_blocking_executor(monkeypatch, release)
+
+    started_events: list[AgentEvent] = []
+    first_started = asyncio.Event()
+
+    async def on_started(event: AgentEvent) -> None:
+        started_events.append(event)
+        first_started.set()
+
+    event_bus.subscribe(
+        event_types=[EventType.EXECUTION_STARTED],
+        handler=on_started,
+        filter_stream="webhook",
+    )
+
+    async def immediate_timeout(_tasks, timeout=None):
+        return set(), set(_tasks)
+
+    monkeypatch.setattr("framework.host.execution_manager.asyncio.wait", immediate_timeout)
+
+    execution_id = await stream.execute({}, session_state={"resume_session_id": "session-1"})
+    await asyncio.wait_for(first_started.wait(), timeout=1)
+
+    first_task = stream._execution_tasks[execution_id]
+
+    try:
+        assert await stream.cancel_execution(execution_id, reason="restart-1") == "cancelling"
+
+        with pytest.raises(ExecutionAlreadyRunningError):
+            await stream.execute({}, session_state={"resume_session_id": execution_id})
+
+        with pytest.raises(ExecutionAlreadyRunningError):
+            await stream.execute({}, session_state={"resume_session_id": execution_id})
+
+        assert len(started_events) == 1
+        assert list(stream._execution_tasks) == [execution_id]
+        assert stream._execution_tasks[execution_id] is first_task
+        assert not first_task.done()
+    finally:
+        release.set()
+        await asyncio.wait_for(first_task, timeout=1)

core/framework/schemas/session_state.py

@@ -155,6 +155,17 @@ class SessionState(BaseModel):
     # True after first successful worker execution (gates trigger delivery on restart)
     worker_configured: bool = Field(default=False)
 
+    # Task-system fields (see framework/tasks).
+    # task_list_id: this session's own task list id (populated on first
+    #   task_create; immutable thereafter). Used for resume reattachment —
+    #   if it differs from resolve_task_list_id(ctx) on resume, a
+    #   TASK_LIST_REATTACH_MISMATCH event is emitted and a fresh list is
+    #   created at the resolved id (the orphan stays on disk).
+    task_list_id: str | None = None
+    # picked_up_from: for worker sessions, the (colony_task_list_id,
+    #   template_task_id) pair this session was spawned for.
+    picked_up_from: list[Any] | None = None
+
     model_config = {"extra": "allow"}
 
     @property

core/framework/server/app.py

@@ -1,5 +1,6 @@
 """aiohttp Application factory for the Hive HTTP API server."""
 
+import hmac
 import logging
 import os
 from pathlib import Path
@@ -19,22 +20,31 @@ _REPO_ROOT = Path(__file__).resolve().parent.parent.parent.parent
 _ALLOWED_AGENT_ROOTS: tuple[Path, ...] | None = None
 
 
+def _has_encrypted_credentials() -> bool:
+    """Return True when an encrypted credential store already exists on disk."""
+    from framework.config import HIVE_HOME
+
+    cred_dir = HIVE_HOME / "credentials" / "credentials"
+    return cred_dir.is_dir() and any(cred_dir.glob("*.enc"))
+
+
 def _get_allowed_agent_roots() -> tuple[Path, ...]:
     """Return resolved allowed root directories for agent loading.
 
     Roots are anchored to the repository root (derived from ``__file__``)
     so the allowlist is correct regardless of the process's working
-    directory.
+    directory. The hive-home subtrees honour ``HIVE_HOME`` so the desktop's
+    per-user root is allowed in addition to (or instead of) ``~/.hive``.
     """
     global _ALLOWED_AGENT_ROOTS
     if _ALLOWED_AGENT_ROOTS is None:
-        from framework.config import COLONIES_DIR
+        from framework.config import COLONIES_DIR, HIVE_HOME
 
         _ALLOWED_AGENT_ROOTS = (
-            COLONIES_DIR.resolve(),  # ~/.hive/colonies/
+            COLONIES_DIR.resolve(),  # $HIVE_HOME/colonies/
             (_REPO_ROOT / "exports").resolve(),  # compat fallback
             (_REPO_ROOT / "examples").resolve(),
-            (Path.home() / ".hive" / "agents").resolve(),
+            (HIVE_HOME / "agents").resolve(),
         )
     return _ALLOWED_AGENT_ROOTS
 
@@ -56,7 +66,8 @@ def validate_agent_path(agent_path: str | Path) -> Path:
         if resolved.is_relative_to(root) and resolved != root:
             return resolved
     raise ValueError(
-        "agent_path must be inside an allowed directory (~/.hive/colonies/, exports/, examples/, or ~/.hive/agents/)"
+        "agent_path must be inside an allowed directory "
+        "($HIVE_HOME/colonies/, exports/, examples/, or $HIVE_HOME/agents/)"
     )
 
 
@@ -88,13 +99,15 @@ def resolve_session(request: web.Request):
 def sessions_dir(session: Session) -> Path:
     """Resolve the worker sessions directory for a session.
 
-    Storage layout: ~/.hive/agents/{agent_name}/sessions/
+    Storage layout: $HIVE_HOME/agents/{agent_name}/sessions/
     Requires a worker to be loaded (worker_path must be set).
     """
     if session.worker_path is None:
         raise ValueError("No worker loaded — no worker sessions directory")
+    from framework.config import HIVE_HOME
+
     agent_name = session.worker_path.name
-    return Path.home() / ".hive" / "agents" / agent_name / "sessions"
+    return HIVE_HOME / "agents" / agent_name / "sessions"
 
 
 # Allowed CORS origins (localhost on any port)
@@ -134,6 +147,47 @@ async def cors_middleware(request: web.Request, handler):
     return response
 
 
+@web.middleware
+async def no_cache_api_middleware(request: web.Request, handler):
+    """Prevent browsers from caching API responses.
+
+    Without this, a one-off bad response (e.g. the SPA catch-all leaking
+    index.html for an /api/* URL before a route was registered) can get
+    pinned in the browser's disk cache and replayed forever, since our
+    JSON handlers don't emit ETag/Last-Modified and browsers fall back
+    to heuristic freshness.
+    """
+    try:
+        response = await handler(request)
+    except web.HTTPException as exc:
+        response = exc
+    if request.path.startswith("/api/"):
+        response.headers["Cache-Control"] = "no-store"
+    return response
+
+
+# ---------------------------------------------------------------------------
+# Desktop shared-secret auth middleware.
+#
+# When the runtime is spawned by the Electron main process, a fresh random
+# token is passed via ``HIVE_DESKTOP_TOKEN``. Every request from main must
+# carry the matching ``X-Hive-Token`` header. If the env var is unset (e.g.
+# running ``hive serve`` directly from a terminal), the check is skipped —
+# OSS behaviour is preserved.
+# ---------------------------------------------------------------------------
+_EXPECTED_DESKTOP_TOKEN: str | None = os.environ.get("HIVE_DESKTOP_TOKEN") or None
+
+
+@web.middleware
+async def desktop_auth_middleware(request: web.Request, handler):
+    if _EXPECTED_DESKTOP_TOKEN is None:
+        return await handler(request)
+    provided = request.headers.get("X-Hive-Token", "")
+    if not hmac.compare_digest(provided, _EXPECTED_DESKTOP_TOKEN):
+        return web.json_response({"error": "unauthorized"}, status=401)
+    return await handler(request)
+
+
 @web.middleware
 async def error_middleware(request: web.Request, handler):
     """Catch exceptions and return JSON error responses.
@@ -173,11 +227,12 @@ async def handle_health(request: web.Request) -> web.Response:
     )
 
 
-async def handle_browser_status(request: web.Request) -> web.Response:
-    """GET /api/browser/status — proxy the GCU bridge status check server-side.
+async def _probe_browser_bridge() -> dict:
+    """Probe the local GCU bridge and return ``{bridge, connected}``.
 
-    Checks http://127.0.0.1:9230/status so the browser never makes a
-    cross-origin request that would log ERR_CONNECTION_REFUSED in the console.
+    Shared by the one-shot ``GET /api/browser/status`` handler and the
+    ``/api/browser/status/stream`` SSE feed so both see the same data
+    source.
     """
     import asyncio
 
@@ -190,17 +245,66 @@ async def handle_browser_status(request: web.Request) -> web.Response:
         await writer.drain()
         raw = await asyncio.wait_for(reader.read(512), timeout=0.5)
         writer.close()
-        # Parse JSON body after the blank line
         if b"\r\n\r\n" in raw:
             body = raw.split(b"\r\n\r\n", 1)[1]
-            import json
+            import json as _json
 
-            data = json.loads(body)
-            return web.json_response({"bridge": True, "connected": data.get("connected", False)})
+            data = _json.loads(body)
+            return {"bridge": True, "connected": bool(data.get("connected", False))}
     except Exception:
         pass
+    return {"bridge": False, "connected": False}
 
-    return web.json_response({"bridge": False, "connected": False})
+
+async def handle_browser_status(request: web.Request) -> web.Response:
+    """GET /api/browser/status — proxy the GCU bridge status check server-side.
+
+    Checks http://127.0.0.1:9230/status so the browser never makes a
+    cross-origin request that would log ERR_CONNECTION_REFUSED in the console.
+    """
+    return web.json_response(await _probe_browser_bridge())
+
+
+async def handle_browser_status_stream(request: web.Request) -> web.StreamResponse:
+    """GET /api/browser/status/stream — SSE feed of bridge status.
+
+    Emits a ``status`` event immediately, then again only when the
+    probe result changes. Polls the local bridge every 3s; that's the
+    same cadence the frontend used before, but we absorb it
+    server-side instead of the browser burning a request.
+    """
+    import asyncio
+    import json as _json
+
+    resp = web.StreamResponse(
+        status=200,
+        headers={
+            "Content-Type": "text/event-stream",
+            "Cache-Control": "no-cache, no-transform",
+            "Connection": "keep-alive",
+            "X-Accel-Buffering": "no",
+        },
+    )
+    await resp.prepare(request)
+
+    async def _send(event: str, data: dict) -> None:
+        payload = f"event: {event}\ndata: {_json.dumps(data)}\n\n"
+        await resp.write(payload.encode("utf-8"))
+
+    last: tuple | None = None
+    try:
+        while True:
+            status = await _probe_browser_bridge()
+            signature = (status["bridge"], status["connected"])
+            if signature != last:
+                await _send("status", status)
+                last = signature
+            await asyncio.sleep(3.0)
+    except (asyncio.CancelledError, ConnectionResetError):
+        raise
+    except Exception as exc:
+        logger.warning("browser status stream error: %s", exc, exc_info=True)
+    return resp
 
 
 def create_app(model: str | None = None) -> web.Application:
@@ -212,7 +316,12 @@ def create_app(model: str | None = None) -> web.Application:
     Returns:
         Configured aiohttp Application ready to run.
     """
-    app = web.Application(middlewares=[cors_middleware, error_middleware])
+    # Desktop mode: the runtime is always a subprocess of the Electron main
+    # process, which reaches it via IPC and the `hive://` custom protocol.
+    # There is no browser origin to authorize, so CORS is unnecessary.
+    # The auth middleware enforces the shared-secret token when the env var
+    # is set (i.e. when Electron spawned us); it is a no-op otherwise.
+    app = web.Application(middlewares=[desktop_auth_middleware, no_cache_api_middleware, error_middleware])
 
     # Initialize credential store (before SessionManager so it can be shared)
     from framework.credentials.store import CredentialStore
@@ -225,75 +334,78 @@ def create_app(model: str | None = None) -> web.Application:
 
         # Auto-generate credential key for web-only users who never ran the TUI
         if not os.environ.get("HIVE_CREDENTIAL_KEY"):
-            try:
-                from framework.credentials.key_storage import generate_and_save_credential_key
+            if _has_encrypted_credentials():
+                logger.warning(
+                    "HIVE_CREDENTIAL_KEY is missing but encrypted credentials already exist; "
+                    "not generating a replacement key because it would not decrypt existing credentials"
+                )
+            else:
+                try:
+                    from framework.credentials.key_storage import generate_and_save_credential_key
 
-                generate_and_save_credential_key()
-                logger.info("Generated and persisted HIVE_CREDENTIAL_KEY to ~/.hive/secrets/credential_key")
-            except Exception as exc:
-                logger.warning("Could not auto-persist HIVE_CREDENTIAL_KEY: %s", exc)
+                    generate_and_save_credential_key()
+                    logger.info("Generated and persisted HIVE_CREDENTIAL_KEY to ~/.hive/secrets/credential_key")
+                except Exception as exc:
+                    logger.warning("Could not auto-persist HIVE_CREDENTIAL_KEY: %s", exc)
 
-        credential_store = CredentialStore.with_aden_sync()
+        # Local server startup should not wait on an eager Aden sync.
+        # The store can still fetch/refresh credentials on demand.
+        if not os.environ.get("HIVE_CREDENTIAL_KEY") and _has_encrypted_credentials():
+            credential_store = CredentialStore.with_env_storage()
+        else:
+            credential_store = CredentialStore.with_aden_sync(auto_sync=False)
     except Exception:
         logger.debug("Encrypted credential store unavailable, using in-memory fallback")
         credential_store = CredentialStore.for_testing({})
 
     app["credential_store"] = credential_store
 
-    # Pre-load queen MCP tools once at startup (cached for all sessions)
-    # This avoids rebuilding the tool registry for every queen session
-    from framework.loader.mcp_registry import MCPRegistry
-    from framework.loader.tool_registry import ToolRegistry
-
-    _queen_tool_registry: ToolRegistry | None = None
-    try:
-        _queen_tool_registry = ToolRegistry()
-        import framework.agents.queen as _queen_pkg
-
-        queen_pkg_dir = Path(_queen_pkg.__file__).parent
-        mcp_config = queen_pkg_dir / "mcp_servers.json"
-        if mcp_config.exists():
-            _queen_tool_registry.load_mcp_config(mcp_config)
-            logger.info("Pre-loaded queen MCP tools from %s", mcp_config)
-
-        registry = MCPRegistry()
-        registry.initialize()
-        registry.ensure_defaults()
-        if (queen_pkg_dir / "mcp_registry.json").is_file():
-            _queen_tool_registry.set_mcp_registry_agent_path(queen_pkg_dir)
-        registry_configs, selection_max_tools = registry.load_agent_selection(queen_pkg_dir)
-        if registry_configs:
-            _queen_tool_registry.load_registry_servers(
-                registry_configs,
-                preserve_existing_tools=True,
-                log_collisions=True,
-                max_tools=selection_max_tools,
-            )
-        logger.info("Pre-loaded queen tool registry with %d tools", len(_queen_tool_registry.get_tools()))
-    except Exception as e:
-        logger.warning("Failed to pre-load queen tool registry: %s", e)
-
-    app["queen_tool_registry"] = _queen_tool_registry
+    # Let queen sessions build their registry lazily on first use instead of
+    # paying the MCP discovery cost during `hive open`.
+    app["queen_tool_registry"] = None
     app["manager"] = SessionManager(
-        model=model, credential_store=credential_store, queen_tool_registry=_queen_tool_registry
+        model=model,
+        credential_store=credential_store,
+        queen_tool_registry=None,
     )
 
+    # Clear orphaned compaction markers from prior server crashes. Without
+    # this, any session whose compaction was interrupted would block the
+    # next colony cold-load for the full await_completion timeout (180s)
+    # before falling through. See compaction_status.sweep_stale_in_progress.
+    try:
+        from framework.config import QUEENS_DIR
+        from framework.server import compaction_status
+
+        compaction_status.sweep_stale_in_progress(QUEENS_DIR)
+    except Exception:
+        logger.debug("compaction_status: startup sweep skipped", exc_info=True)
+
     # Register shutdown hook
     app.on_shutdown.append(_on_shutdown)
 
     # Health check
     app.router.add_get("/api/health", handle_health)
     app.router.add_get("/api/browser/status", handle_browser_status)
+    app.router.add_get("/api/browser/status/stream", handle_browser_status_stream)
 
     # Register route modules
+    from framework.server.routes_colonies import register_routes as register_colonies_routes
+    from framework.server.routes_colony_tools import register_routes as register_colony_tools_routes
+    from framework.server.routes_colony_workers import register_routes as register_colony_worker_routes
     from framework.server.routes_config import register_routes as register_config_routes
     from framework.server.routes_credentials import register_routes as register_credential_routes
     from framework.server.routes_events import register_routes as register_event_routes
     from framework.server.routes_execution import register_routes as register_execution_routes
     from framework.server.routes_logs import register_routes as register_log_routes
+    from framework.server.routes_mcp import register_routes as register_mcp_routes
     from framework.server.routes_messages import register_routes as register_message_routes
+    from framework.server.routes_prompts import register_routes as register_prompt_routes
+    from framework.server.routes_queen_tools import register_routes as register_queen_tools_routes
     from framework.server.routes_queens import register_routes as register_queen_routes
     from framework.server.routes_sessions import register_routes as register_session_routes
+    from framework.server.routes_skills import register_routes as register_skills_routes
+    from framework.server.routes_tasks import register_routes as register_task_routes
     from framework.server.routes_workers import register_routes as register_worker_routes
 
     register_config_routes(app)
@@ -305,9 +417,32 @@ def create_app(model: str | None = None) -> web.Application:
     register_worker_routes(app)
     register_log_routes(app)
     register_queen_routes(app)
+    register_queen_tools_routes(app)
+    register_colonies_routes(app)
+    register_colony_tools_routes(app)
+    register_mcp_routes(app)
+    register_colony_worker_routes(app)
+    register_prompt_routes(app)
+    register_skills_routes(app)
+    register_task_routes(app)
 
-    # Static file serving — Option C production mode
-    # If frontend/dist/ exists, serve built frontend files on /
+    # Commercial extensions (optional — only present in hive-desktop-runtime).
+    # Imports lazily so an OSS install without the `commercial` package keeps
+    # working unchanged.
+    try:
+        from commercial.middleware import setup_commercial_middleware
+        from commercial.routes import register_routes as register_commercial_routes
+
+        setup_commercial_middleware(app)
+        register_commercial_routes(app)
+        logger.info("Commercial extensions loaded")
+    except ImportError:
+        pass
+
+    # Serve the built frontend SPA (if frontend/dist exists) so hitting the
+    # API host in a browser loads the dashboard instead of 404'ing. In
+    # Electron/desktop mode the renderer still loads from file:// and
+    # ignores this; in dev mode Vite is used instead.
     _setup_static_serving(app)
 
     return app

core/framework/server/compaction_status.py

@@ -0,0 +1,201 @@
+"""Track fork-compaction status for freshly-forked colony queen sessions.
+
+When ``create_colony`` forks a queen session into a colony, the
+inherited DM transcript is compacted via an LLM call that can legitimately
+exceed the default tool-call timeout (60s). To keep ``create_colony``
+responsive we run that compaction in the background and record its
+status on disk so a subsequent colony session-load can wait for it to
+settle before reading the conversation files.
+
+The status lives at ``<queen_dir>/compaction_status.json``:
+
+    {"status": "in_progress", "started_at": "..."}
+    {"status": "done", "completed_at": "...", "messages_compacted": N, "summary_chars": M}
+    {"status": "failed", "completed_at": "...", "error": "..."}
+
+Only present when a compaction was scheduled for this queen dir — absent
+otherwise. All writes are fail-soft; a missing/corrupt file is treated
+as "no compaction pending".
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from datetime import UTC, datetime
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+_STATUS_FILENAME = "compaction_status.json"
+
+
+def _status_path(queen_dir: Path) -> Path:
+    return Path(queen_dir) / _STATUS_FILENAME
+
+
+def mark_in_progress(queen_dir: Path) -> None:
+    path = _status_path(queen_dir)
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(
+            json.dumps(
+                {
+                    "status": "in_progress",
+                    "started_at": datetime.now(UTC).isoformat(),
+                },
+                ensure_ascii=False,
+            ),
+            encoding="utf-8",
+        )
+    except OSError:
+        logger.warning(
+            "compaction_status: failed to write 'in_progress' at %s",
+            path,
+            exc_info=True,
+        )
+
+
+def mark_done(
+    queen_dir: Path,
+    *,
+    messages_compacted: int = 0,
+    summary_chars: int = 0,
+) -> None:
+    path = _status_path(queen_dir)
+    try:
+        path.write_text(
+            json.dumps(
+                {
+                    "status": "done",
+                    "completed_at": datetime.now(UTC).isoformat(),
+                    "messages_compacted": messages_compacted,
+                    "summary_chars": summary_chars,
+                },
+                ensure_ascii=False,
+            ),
+            encoding="utf-8",
+        )
+    except OSError:
+        logger.warning(
+            "compaction_status: failed to write 'done' at %s",
+            path,
+            exc_info=True,
+        )
+
+
+def mark_failed(queen_dir: Path, error: str) -> None:
+    path = _status_path(queen_dir)
+    try:
+        path.write_text(
+            json.dumps(
+                {
+                    "status": "failed",
+                    "completed_at": datetime.now(UTC).isoformat(),
+                    "error": (error or "")[:500],
+                },
+                ensure_ascii=False,
+            ),
+            encoding="utf-8",
+        )
+    except OSError:
+        logger.warning(
+            "compaction_status: failed to write 'failed' at %s",
+            path,
+            exc_info=True,
+        )
+
+
+def get_status(queen_dir: Path) -> dict | None:
+    path = _status_path(queen_dir)
+    if not path.exists():
+        return None
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return None
+
+
+async def await_completion(
+    queen_dir: Path,
+    *,
+    timeout: float = 180.0,
+    poll: float = 0.5,
+) -> dict | None:
+    """Block until compaction leaves 'in_progress' state.
+
+    Returns the final status dict, or ``None`` if no compaction marker
+    exists for this dir. On timeout returns the last observed status
+    (still 'in_progress') so the caller can decide whether to proceed
+    with the raw transcript.
+    """
+    loop = asyncio.get_event_loop()
+    deadline = loop.time() + max(0.0, timeout)
+    last: dict | None = None
+    while True:
+        last = get_status(queen_dir)
+        if last is None:
+            return None
+        if last.get("status") != "in_progress":
+            return last
+        if loop.time() >= deadline:
+            logger.warning(
+                "compaction_status: timed out after %.0fs waiting for %s (proceeding with raw transcript)",
+                timeout,
+                queen_dir,
+            )
+            return last
+        await asyncio.sleep(poll)
+
+
+def sweep_stale_in_progress(queens_root: Path) -> int:
+    """Rewrite any orphaned ``in_progress`` markers under ``queens_root`` to
+    ``failed``. Returns the count of rewritten markers.
+
+    Whatever process owned the original compaction is gone (server crash,
+    SIGKILL, etc.), so leaving the marker at ``in_progress`` would cause every
+    subsequent colony cold-load for that queen session to wait the full
+    ``await_completion`` timeout (default 180s) before falling through.
+
+    Called once during server bootstrap. Best-effort: any per-file failure is
+    logged and skipped — the sweep should never prevent the server from
+    coming up.
+    """
+    if not queens_root.exists():
+        return 0
+    cleaned = 0
+    try:
+        for queen_dir in queens_root.iterdir():
+            if not queen_dir.is_dir():
+                continue
+            sessions_dir = queen_dir / "sessions"
+            if not sessions_dir.exists():
+                continue
+            try:
+                for session_dir in sessions_dir.iterdir():
+                    if not session_dir.is_dir():
+                        continue
+                    status = get_status(session_dir)
+                    if status is None or status.get("status") != "in_progress":
+                        continue
+                    mark_failed(session_dir, "server restarted while compaction was in progress")
+                    cleaned += 1
+            except OSError:
+                logger.debug(
+                    "compaction_status: sweep failed under %s",
+                    sessions_dir,
+                    exc_info=True,
+                )
+    except OSError:
+        logger.debug(
+            "compaction_status: sweep failed under %s",
+            queens_root,
+            exc_info=True,
+        )
+    if cleaned:
+        logger.info(
+            "compaction_status: cleared %d stale 'in_progress' marker(s) at startup",
+            cleaned,
+        )
+    return cleaned

core/framework/server/queen_orchestrator.py

@@ -113,10 +113,18 @@ def install_worker_escalation_routing(
         queen_node = session.queen_executor.node_registry.get("queen") if session.queen_executor is not None else None
         if queen_node is None or not hasattr(queen_node, "inject_event"):
             if session.event_bus is not None:
+                # Stream the handoff text so the human sees the worker's
+                # question, then request input so the reply input appears.
+                await session.event_bus.emit_client_output_delta(
+                    stream_id="queen",
+                    node_id="queen",
+                    content=handoff,
+                    snapshot=handoff,
+                    execution_id=session.id,
+                )
                 await session.event_bus.emit_client_input_requested(
                     stream_id="queen",
                     node_id="queen",
-                    prompt=handoff,
                     execution_id=session.id,
                 )
             return
@@ -175,12 +183,10 @@ def _build_credentials_provider() -> Any:
 
             adapter = CredentialStoreAdapter.default()
             accounts = adapter.get_all_account_info()
-            tool_provider_map = adapter.get_tool_provider_map()
-            rendered = build_accounts_prompt(
-                accounts,
-                tool_provider_map=tool_provider_map,
-                node_tool_names=None,
-            )
+            # Compact form (no tool_provider_map) — tool schemas already
+            # surface function names; baking the full per-provider list
+            # into the system prompt on every turn was ~2 KB of redundancy.
+            rendered = build_accounts_prompt(accounts)
         except Exception:
             logger.debug("Failed to render ambient credentials block", exc_info=True)
             rendered = ""
@@ -231,7 +237,7 @@ async def materialize_queen_identity(
 
     phase_state.queen_id = queen_id
     phase_state.queen_profile = queen_profile
-    phase_state.queen_identity_prompt = format_queen_identity_prompt(queen_profile)
+    phase_state.queen_identity_prompt = format_queen_identity_prompt(queen_profile, max_examples=1)
 
     if event_bus is not None:
         await event_bus.publish(
@@ -247,6 +253,92 @@ async def materialize_queen_identity(
         )
 
 
+def build_queen_tool_registry_bare() -> tuple[Any, dict[str, list[dict[str, Any]]]]:
+    """Build a Queen ``ToolRegistry`` and a (server_name → tools) catalog.
+
+    Used by the Tool Library GET route to populate the MCP tool surface
+    without needing a live queen session. We DO NOT register queen
+    lifecycle tools here (they require a Session stub); the catalog only
+    covers MCP-origin tools, which is what the allowlist gates.
+
+    Loading MCP servers spawns subprocesses, so call this once per
+    backend process and cache the result.
+    """
+    from pathlib import Path
+
+    import framework.agents.queen as _queen_pkg
+    from framework.loader.mcp_registry import MCPRegistry
+    from framework.loader.tool_registry import ToolRegistry
+
+    queen_registry = ToolRegistry()
+    queen_pkg_dir = Path(_queen_pkg.__file__).parent
+
+    mcp_config = queen_pkg_dir / "mcp_servers.json"
+    if mcp_config.exists():
+        try:
+            queen_registry.load_mcp_config(mcp_config)
+        except Exception:
+            logger.warning("build_queen_tool_registry_bare: MCP config failed", exc_info=True)
+
+    try:
+        reg = MCPRegistry()
+        reg.initialize()
+        if (queen_pkg_dir / "mcp_registry.json").is_file():
+            queen_registry.set_mcp_registry_agent_path(queen_pkg_dir)
+        registry_configs, selection_max_tools = reg.load_agent_selection(queen_pkg_dir)
+
+        already = {cfg.get("name") for cfg in registry_configs if cfg.get("name")}
+        extra: list[str] = []
+        try:
+            for entry in reg.list_installed():
+                if entry.get("source") != "local":
+                    continue
+                if not entry.get("enabled", True):
+                    continue
+                name = entry.get("name")
+                if name and name not in already:
+                    extra.append(name)
+        except Exception:
+            pass
+        if extra:
+            try:
+                extra_configs = reg.resolve_for_agent(include=extra)
+                registry_configs = list(registry_configs) + [reg._server_config_to_dict(c) for c in extra_configs]
+            except Exception:
+                logger.debug("build_queen_tool_registry_bare: resolve_for_agent(extra) failed", exc_info=True)
+
+        if registry_configs:
+            queen_registry.load_registry_servers(
+                registry_configs,
+                preserve_existing_tools=True,
+                log_collisions=False,
+                max_tools=selection_max_tools,
+            )
+    except Exception:
+        logger.warning("build_queen_tool_registry_bare: MCP registry load failed", exc_info=True)
+
+    # Build the catalog.
+    tools_by_name = queen_registry.get_tools()
+    server_map = dict(getattr(queen_registry, "_mcp_server_tools", {}) or {})
+    catalog: dict[str, list[dict[str, Any]]] = {}
+    for server_name in sorted(server_map):
+        entries: list[dict[str, Any]] = []
+        for tool_name in sorted(server_map[server_name]):
+            tool = tools_by_name.get(tool_name)
+            if tool is None:
+                continue
+            entries.append(
+                {
+                    "name": tool.name,
+                    "description": tool.description,
+                    "input_schema": tool.parameters,
+                }
+            )
+        catalog[server_name] = entries
+
+    return queen_registry, catalog
+
+
 async def create_queen(
     session: Session,
     session_manager: Any,
@@ -268,40 +360,24 @@ async def create_queen(
         queen_loop_config as _base_loop_config,
     )
     from framework.agents.queen.nodes import (
-        _QUEEN_BUILDING_TOOLS,
-        _QUEEN_EDITING_TOOLS,
+        _QUEEN_INCUBATING_TOOLS,
         _QUEEN_INDEPENDENT_TOOLS,
-        _QUEEN_PLANNING_TOOLS,
-        _QUEEN_RUNNING_TOOLS,
-        _QUEEN_STAGING_TOOLS,
-        _appendices,
-        _building_knowledge,
-        _planning_knowledge,
+        _QUEEN_REVIEWING_TOOLS,
+        _QUEEN_WORKING_TOOLS,
         _queen_behavior_always,
-        _queen_behavior_building,
-        _queen_behavior_editing,
         _queen_behavior_independent,
-        _queen_behavior_planning,
-        _queen_behavior_running,
-        _queen_behavior_staging,
         _queen_character_core,
-        _queen_identity_editing,
-        _queen_phase_7,
-        _queen_role_building,
+        _queen_role_incubating,
         _queen_role_independent,
-        _queen_role_planning,
-        _queen_role_running,
-        _queen_role_staging,
-        _queen_style,
-        _queen_tools_building,
-        _queen_tools_editing,
+        _queen_role_reviewing,
+        _queen_role_working,
+        _queen_tools_incubating,
         _queen_tools_independent,
-        _queen_tools_planning,
-        _queen_tools_running,
-        _queen_tools_staging,
-        _shared_building_knowledge,
+        _queen_tools_reviewing,
+        _queen_tools_working,
         finalize_queen_prompt,
     )
+    from framework.config import get_max_tokens as _get_max_tokens
     from framework.host.event_bus import AgentEvent, EventType
     from framework.llm.capabilities import supports_image_tool_results
     from framework.loader.mcp_registry import MCPRegistry
@@ -336,6 +412,45 @@ async def create_queen(
             if (queen_pkg_dir / "mcp_registry.json").is_file():
                 queen_registry.set_mcp_registry_agent_path(queen_pkg_dir)
             registry_configs, selection_max_tools = registry.load_agent_selection(queen_pkg_dir)
+
+            # Auto-include every user-added local MCP server that the repo
+            # selection hasn't already loaded. Users register servers via
+            # the `/api/mcp/servers` route (or `hive mcp add`); they live in
+            # ~/.hive/mcp_registry/installed.json with source == "local".
+            # New servers take effect on the next queen session start; the
+            # prompt cache and ToolRegistry are still loaded once per boot.
+            already_loaded_names = {cfg.get("name") for cfg in registry_configs if cfg.get("name")}
+            extra_names: list[str] = []
+            try:
+                for entry in registry.list_installed():
+                    if entry.get("source") != "local":
+                        continue
+                    if not entry.get("enabled", True):
+                        continue
+                    name = entry.get("name")
+                    if not name or name in already_loaded_names:
+                        continue
+                    extra_names.append(name)
+            except Exception:
+                logger.debug("Queen: list_installed() failed while auto-including user servers", exc_info=True)
+
+            if extra_names:
+                try:
+                    extra_configs = registry.resolve_for_agent(include=extra_names)
+                    extra_dicts = [registry._server_config_to_dict(c) for c in extra_configs]
+                    registry_configs = list(registry_configs) + extra_dicts
+                    logger.info(
+                        "Queen: auto-including %d user-added MCP server(s): %s",
+                        len(extra_dicts),
+                        [c.get("name") for c in extra_dicts],
+                    )
+                except Exception:
+                    logger.warning(
+                        "Queen: failed to resolve user-added MCP servers %s",
+                        extra_names,
+                        exc_info=True,
+                    )
+
             if registry_configs:
                 results = queen_registry.load_registry_servers(
                     registry_configs,
@@ -348,7 +463,10 @@ async def create_queen(
             logger.warning("Queen: MCP registry config failed to load", exc_info=True)
 
     # ---- Phase state --------------------------------------------------
-    effective_phase = initial_phase or ("staging" if worker_identity else "planning")
+    # 3-phase model: caller supplies the phase directly (DM → independent,
+    # colony bootstrap → working). Fall back to independent when nothing
+    # is specified — there is no "staging"/"planning" bootstrap anymore.
+    effective_phase = initial_phase or ("working" if worker_identity else "independent")
     phase_state = QueenPhaseState(phase=effective_phase, event_bus=session.event_bus)
     session.phase_state = phase_state
 
@@ -360,28 +478,6 @@ async def create_queen(
     # when the user adds/removes an integration.
     phase_state.credentials_prompt_provider = _build_credentials_provider()
 
-    # ---- Track ask rounds during planning ----------------------------
-    # Increment planning_ask_rounds each time the queen requests user
-    # input (ask_user or ask_user_multiple) while in the planning phase.
-    async def _track_planning_asks(event: AgentEvent) -> None:
-        if phase_state.phase != "planning":
-            return
-        # Only count explicit ask_user / ask_user_multiple calls, not
-        # auto-block (text-only turns emit CLIENT_INPUT_REQUESTED with
-        # an empty prompt and no options/questions).
-        data = event.data or {}
-        has_prompt = bool(data.get("prompt"))
-        has_questions = bool(data.get("questions"))
-        has_options = bool(data.get("options"))
-        if has_prompt or has_questions or has_options:
-            phase_state.planning_ask_rounds += 1
-
-    session.event_bus.subscribe(
-        [EventType.CLIENT_INPUT_REQUESTED],
-        _track_planning_asks,
-        filter_stream="queen",
-    )
-
     # ---- Lifecycle tools (always registered) --------------------------
     register_queen_lifecycle_tools(
         queen_registry,
@@ -392,6 +488,21 @@ async def create_queen(
         phase_state=phase_state,
     )
 
+    # ---- Task system tools --------------------------------------------
+    # Every queen gets the four session task tools. Queens-of-colony
+    # additionally get the colony_template_* tools (gated by colony_id).
+    from framework.tasks.tools import (
+        register_colony_template_tools,
+        register_task_tools,
+    )
+
+    register_task_tools(queen_registry)
+    _colony_id_for_queen = getattr(session, "colony_id", None) or getattr(
+        getattr(session, "colony_runtime", None), "_colony_id", None
+    )
+    if _colony_id_for_queen:
+        register_colony_template_tools(queen_registry, colony_id=_colony_id_for_queen)
+
     # ---- Colony runtime check (only when worker is loaded) ----------------
     if session.colony_runtime:
         from framework.tools.worker_monitoring_tools import register_worker_monitoring_tools
@@ -417,39 +528,99 @@ async def create_queen(
     session._queen_tool_executor = queen_tool_executor  # type: ignore[attr-defined]
 
     # ---- Partition tools by phase ------------------------------------
-    planning_names = set(_QUEEN_PLANNING_TOOLS)
-    building_names = set(_QUEEN_BUILDING_TOOLS)
-    staging_names = set(_QUEEN_STAGING_TOOLS)
-    running_names = set(_QUEEN_RUNNING_TOOLS)
-    editing_names = set(_QUEEN_EDITING_TOOLS)
     independent_names = set(_QUEEN_INDEPENDENT_TOOLS)
+    incubating_names = set(_QUEEN_INCUBATING_TOOLS)
+    working_names = set(_QUEEN_WORKING_TOOLS)
+    reviewing_names = set(_QUEEN_REVIEWING_TOOLS)
 
     registered_names = {t.name for t in queen_tools}
-    missing_building = building_names - registered_names
-    if missing_building:
-        logger.warning(
-            "Queen: %d/%d building tools NOT registered: %s",
-            len(missing_building),
-            len(building_names),
-            sorted(missing_building),
-        )
     logger.info("Queen: registered tools: %s", sorted(registered_names))
 
-    phase_state.planning_tools = [t for t in queen_tools if t.name in planning_names]
-    phase_state.building_tools = [t for t in queen_tools if t.name in building_names]
-    phase_state.staging_tools = [t for t in queen_tools if t.name in staging_names]
-    phase_state.running_tools = [t for t in queen_tools if t.name in running_names]
-    phase_state.editing_tools = [t for t in queen_tools if t.name in editing_names]
+    phase_state.working_tools = [t for t in queen_tools if t.name in working_names]
+    phase_state.reviewing_tools = [t for t in queen_tools if t.name in reviewing_names]
+    # Incubating tool surface is intentionally minimal (read-only inspection
+    # + create_colony + cancel_incubation) — no MCP tools spliced in, so the
+    # queen stays focused on drafting the spec.
+    phase_state.incubating_tools = [t for t in queen_tools if t.name in incubating_names]
 
     # Independent phase gets core tools + all MCP tools not claimed by any
-    # other phase (coder-tools file I/O, gcu-tools browser, etc.).
-    all_phase_names = planning_names | building_names | staging_names | running_names | editing_names
+    # other phase (files-tools file I/O, gcu-tools browser, etc.).
+    all_phase_names = independent_names | incubating_names | working_names | reviewing_names
     mcp_tools = [t for t in queen_tools if t.name not in all_phase_names]
     phase_state.independent_tools = [t for t in queen_tools if t.name in independent_names] + mcp_tools
     logger.info(
         "Queen: independent tools: %s",
         sorted(t.name for t in phase_state.independent_tools),
     )
+    logger.info(
+        "Queen: incubating tools: %s",
+        sorted(t.name for t in phase_state.incubating_tools),
+    )
+
+    # ---- Per-queen MCP tool allowlist --------------------------------
+    # Capture the set of MCP-origin tool names so the allowlist in
+    # ``QueenPhaseState`` only gates MCP tools (lifecycle and synthetic
+    # tools always pass through). Then apply the queen profile's stored
+    # allowlist (if any) and memoize the filtered independent tool list.
+    mcp_server_tools_map: dict[str, set[str]] = dict(getattr(queen_registry, "_mcp_server_tools", {}))
+    phase_state.mcp_tool_names_all = set().union(*mcp_server_tools_map.values()) if mcp_server_tools_map else set()
+    # The queen's MCP tool allowlist now lives in a dedicated
+    # ``tools.json`` sidecar next to ``profile.yaml``. ``load_queen_tools_config``
+    # migrates any legacy ``enabled_mcp_tools`` field out of profile.yaml
+    # on first read, so existing installs upgrade silently.
+    from framework.agents.queen.queen_tools_config import load_queen_tools_config
+
+    # Build a minimal catalog for default-tool resolution. The full
+    # ``session_manager._mcp_tool_catalog`` snapshot is written further
+    # down the flow; a queen booted for the first time needs the catalog
+    # now so ``@server:NAME`` shorthands in the role-default table can
+    # expand against the just-loaded MCP servers.
+    _boot_catalog: dict[str, list[dict]] = {
+        srv: [{"name": name} for name in sorted(names)] for srv, names in mcp_server_tools_map.items()
+    }
+    # ``queen_dir`` is ``queens/<queen_id>/sessions/<session_id>``; the
+    # allowlist sidecar is keyed by queen_id, not session_id.
+    phase_state.enabled_mcp_tools = load_queen_tools_config(session.queen_name, _boot_catalog)
+    phase_state.rebuild_independent_filter()
+    if phase_state.enabled_mcp_tools is not None:
+        total_mcp = len(phase_state.mcp_tool_names_all)
+        allowed_mcp = len(set(phase_state.enabled_mcp_tools) & phase_state.mcp_tool_names_all)
+        logger.info(
+            "Queen: per-queen MCP allowlist active — %d of %d MCP tools enabled",
+            allowed_mcp,
+            total_mcp,
+        )
+
+    # ---- MCP tool catalog for the frontend ---------------------------
+    # Snapshot per-server tool metadata so the Queen Tools API can render
+    # the tool surface without spawning MCP subprocesses. Keyed by server
+    # name so the UI can group tools by origin. Updated every time a
+    # queen boots, so installing a new server and starting a new queen
+    # session refreshes the catalog.
+    mcp_tool_catalog: dict[str, list[dict[str, Any]]] = {}
+    tools_by_name = {t.name: t for t in queen_tools}
+    for server_name, tool_names in mcp_server_tools_map.items():
+        server_entries: list[dict[str, Any]] = []
+        for tool_name in sorted(tool_names):
+            tool = tools_by_name.get(tool_name)
+            if tool is None:
+                continue
+            server_entries.append(
+                {
+                    "name": tool.name,
+                    "description": tool.description,
+                    "input_schema": tool.parameters,
+                }
+            )
+        mcp_tool_catalog[server_name] = server_entries
+    # All queens share one MCP registry, so the catalog is a manager-level
+    # fact; stash it on the SessionManager so the Queen Tools route can
+    # render the tool list even when no queen session is currently live.
+    if session_manager is not None:
+        try:
+            session_manager._mcp_tool_catalog = mcp_tool_catalog  # type: ignore[attr-defined]
+        except Exception:
+            logger.debug("Queen: could not attach mcp_tool_catalog to manager", exc_info=True)
 
     # ---- Global + queen-scoped memory ----------------------------------
     global_dir, queen_mem_dir = initialize_memory_scopes(session, phase_state)
@@ -466,105 +637,72 @@ async def create_queen(
     # ---- Compose phase-specific prompts ------------------------------
     from framework.agents.queen.nodes import queen_node as _orig_node
 
-    if worker_identity is None:
-        worker_identity = (
-            "\n\n# Worker Profile\n"
-            "No worker agent loaded. You are operating independently.\n"
-            "Design or build the agent to solve the user's problem "
-            "according to your current phase."
-        )
-
     # Resolve vision-only prompt sections based on the session's LLM.
     # session.llm is immutable for the session's lifetime, so this check
     # is stable — prompts never need to be recomposed mid-session.
     _has_vision = bool(session.llm and supports_image_tool_results(getattr(session.llm, "model", "")))
 
-    _planning_body = (
-        _queen_character_core
-        + _queen_role_planning
-        + _queen_style
-        + _shared_building_knowledge
-        + _queen_tools_planning
-        + _queen_behavior_always
-        + _queen_behavior_planning
-        + _planning_knowledge
-        + worker_identity
-    )
-    phase_state.prompt_planning = finalize_queen_prompt(_planning_body, _has_vision)
-
-    _building_body = (
-        _queen_character_core
-        + _queen_role_building
-        + _queen_style
-        + _shared_building_knowledge
-        + _queen_tools_building
-        + _queen_behavior_always
-        + _queen_behavior_building
-        + _building_knowledge
-        + _queen_phase_7
-        + _appendices
-        + worker_identity
-    )
-    phase_state.prompt_building = finalize_queen_prompt(_building_body, _has_vision)
-    phase_state.prompt_staging = finalize_queen_prompt(
-        (
-            _queen_character_core
-            + _queen_role_staging
-            + _queen_style
-            + _queen_tools_staging
-            + _queen_behavior_always
-            + _queen_behavior_staging
-            + worker_identity
-        ),
-        _has_vision,
-    )
-    phase_state.prompt_running = finalize_queen_prompt(
-        (
-            _queen_character_core
-            + _queen_role_running
-            + _queen_style
-            + _queen_tools_running
-            + _queen_behavior_always
-            + _queen_behavior_running
-            + worker_identity
-        ),
-        _has_vision,
-    )
-    phase_state.prompt_editing = finalize_queen_prompt(
-        (
-            _queen_identity_editing
-            + _queen_style
-            + _queen_tools_editing
-            + _queen_behavior_always
-            + _queen_behavior_editing
-            + worker_identity
-        ),
-        _has_vision,
-    )
     phase_state.prompt_independent = finalize_queen_prompt(
         (
             _queen_character_core
             + _queen_role_independent
-            + _queen_style
             + _queen_tools_independent
             + _queen_behavior_always
             + _queen_behavior_independent
         ),
         _has_vision,
     )
+    phase_state.prompt_incubating = finalize_queen_prompt(
+        (_queen_character_core + _queen_role_incubating + _queen_tools_incubating + _queen_behavior_always),
+        _has_vision,
+    )
+    phase_state.prompt_working = finalize_queen_prompt(
+        (_queen_character_core + _queen_role_working + _queen_tools_working + _queen_behavior_always),
+        _has_vision,
+    )
+    phase_state.prompt_reviewing = finalize_queen_prompt(
+        (_queen_character_core + _queen_role_reviewing + _queen_tools_reviewing + _queen_behavior_always),
+        _has_vision,
+    )
 
     # ---- Default skill protocols -------------------------------------
     _queen_skill_dirs: list[str] = []
     try:
+        from framework.config import QUEENS_DIR
+        from framework.skills.discovery import ExtraScope
         from framework.skills.manager import SkillsManager, SkillsManagerConfig
 
-        # Pass project_root so user-scope skills (~/.hive/skills/, ~/.agents/skills/)
-        # are discovered. Queen has no agent-specific project root, so we use its
-        # own directory — the value just needs to be non-None to enable user-scope scanning.
-        _queen_skills_mgr = SkillsManager(SkillsManagerConfig(project_root=Path(__file__).parent))
+        # Queen home backs the queen-UI skill scope and the queen's
+        # override store. The directory already exists (or is created on
+        # demand by queen_profiles.py); treat a missing queen_name as the
+        # default queen to preserve backwards compatibility.
+        _queen_id = getattr(session, "queen_name", None) or "default"
+        _queen_home = QUEENS_DIR / _queen_id
+        _queen_skills_mgr = SkillsManager(
+            SkillsManagerConfig(
+                queen_id=_queen_id,
+                queen_overrides_path=_queen_home / "skills_overrides.json",
+                extra_scope_dirs=[
+                    ExtraScope(
+                        directory=_queen_home / "skills",
+                        label="queen_ui",
+                        priority=2,
+                    )
+                ],
+                # No project_root — queen's project is her own identity;
+                # user-scope discovery still runs without one.
+                project_root=None,
+                skip_community_discovery=True,
+                interactive=False,
+            )
+        )
         _queen_skills_mgr.load()
         phase_state.protocols_prompt = _queen_skills_mgr.protocols_prompt
         phase_state.skills_catalog_prompt = _queen_skills_mgr.skills_catalog_prompt
+        # Also store the manager so get_current_prompt() can render a
+        # phase-filtered catalog on each turn (skills with a `visibility`
+        # frontmatter that excludes the current phase are dropped).
+        phase_state.skills_manager = _queen_skills_mgr
         _queen_skill_dirs = _queen_skills_mgr.allowlisted_dirs
     except Exception:
         logger.debug("Queen skill loading failed (non-fatal)", exc_info=True)
@@ -596,8 +734,37 @@ async def create_queen(
 
     # ---- Recall on each real user turn --------------------------------
     async def _recall_on_user_input(event: AgentEvent) -> None:
-        """Re-select memories when real user input arrives."""
-        await _refresh_recall_cache((event.data or {}).get("content", ""))
+        """On real user input, freeze the dynamic system-prompt suffix and
+        refresh recall memories in the background.
+
+        The EventBus drops handlers that exceed 15s, so we MUST return fast.
+        Recall selection queries the LLM and can take >15s on slow backends;
+        we fire it off as a background task and re-stamp the suffix when it
+        completes. The immediate refresh_dynamic_suffix call stamps a fresh
+        timestamp using the last-known recall blocks so every iteration of
+        THIS user turn sees a byte-stable prompt (prompt cache hits on the
+        static block). Phase-change injections and worker-report injections
+        go through agent_loop.inject_event() and do NOT publish
+        CLIENT_INPUT_RECEIVED, so this runs exactly once per real user turn.
+        """
+        query = (event.data or {}).get("content", "")
+        # Immediate: stamp "now" into the frozen suffix, using whatever
+        # recall blocks we already cached (from the prior turn or seeding).
+        phase_state.refresh_dynamic_suffix()
+
+        async def _bg_refresh() -> None:
+            try:
+                await _refresh_recall_cache(query)
+                # Re-stamp with the fresh recall blocks. Any iteration that
+                # read the suffix before this point used the older recall
+                # — acceptable; recall was already eventual-consistency.
+                phase_state.refresh_dynamic_suffix()
+            except Exception:
+                logger.debug("background recall refresh failed", exc_info=True)
+
+        import asyncio as _asyncio
+
+        _asyncio.create_task(_bg_refresh())
 
     session.event_bus.subscribe(
         [EventType.CLIENT_INPUT_RECEIVED],
@@ -632,7 +799,7 @@ async def create_queen(
         except FileNotFoundError:
             logger.warning("Queen profile %s not found after selection", queen_id)
             return None
-        identity_prompt = format_queen_identity_prompt(profile)
+        identity_prompt = format_queen_identity_prompt(profile, max_examples=1)
         # Store on phase_state so identity persists across dynamic prompt refreshes
         phase_state.queen_id = queen_id
         phase_state.queen_profile = profile
@@ -707,6 +874,9 @@ async def create_queen(
             except Exception:
                 logger.debug("recall: initial seeding failed", exc_info=True)
 
+        # Freeze the dynamic suffix once so the first real turn sends a
+        # byte-stable prompt even before CLIENT_INPUT_RECEIVED fires.
+        phase_state.refresh_dynamic_suffix()
         return HookResult(system_prompt=phase_state.get_current_prompt())
 
     # ---- Colony preparation -------------------------------------------
@@ -743,6 +913,29 @@ async def create_queen(
 
     async def _queen_loop():
         logger.debug("[_queen_loop] Starting queen loop for session %s", session.id)
+        # Scope the browser profile to this session so parallel queens each
+        # drive their own Chrome tab group instead of fighting over "default".
+        # Browser tools run in a stdio MCP subprocess, so we can't set a
+        # contextvar across processes — instead we inject `profile` as a
+        # CONTEXT_PARAM that ToolRegistry passes into every MCP call. The
+        # token stays local to this task.
+        try:
+            from framework.loader.tool_registry import ToolRegistry
+            from framework.tasks.scoping import session_task_list_id
+
+            queen_agent_id = getattr(session, "agent_id", None) or "queen"
+            queen_list_id = session_task_list_id(queen_agent_id, session.id)
+            colony_id = getattr(session, "colony_id", None) or getattr(
+                getattr(session, "colony_runtime", None), "_colony_id", None
+            )
+            ToolRegistry.set_execution_context(
+                profile=session.id,
+                agent_id=queen_agent_id,
+                task_list_id=queen_list_id,
+                colony_id=colony_id,
+            )
+        except Exception:
+            logger.debug("Queen: failed to set execution context for session %s", session.id, exc_info=True)
         try:
             lc = _queen_loop_config
             queen_loop_config = LoopConfig(
@@ -790,11 +983,17 @@ async def create_queen(
                 llm=session.llm,
                 available_tools=queen_tools,
                 goal_context=queen_goal.to_prompt_context(),
-                max_tokens=lc.get("max_tokens", 8192),
+                # Honor configuration.json (llm.max_tokens) instead of
+                # hard-defaulting to 8192. The legacy fallback ignored both
+                # the user's saved ceiling AND the model's actual output
+                # capacity (e.g. glm-5.1 / kimi-k2.5 both support 32k out),
+                # which silently truncated long tool-emitting turns.
+                max_tokens=lc.get("max_tokens", _get_max_tokens()),
                 stream_id="queen",
                 execution_id=session.id,
                 dynamic_tools_provider=phase_state.get_current_tools,
-                dynamic_prompt_provider=phase_state.get_current_prompt,
+                dynamic_prompt_provider=phase_state.get_static_prompt,
+                dynamic_prompt_suffix_provider=phase_state.get_dynamic_suffix,
                 iteration_metadata_provider=lambda: {"phase": phase_state.phase},
                 skills_catalog_prompt=phase_state.skills_catalog_prompt,
                 protocols_prompt=phase_state.protocols_prompt,
@@ -810,44 +1009,71 @@ async def create_queen(
 
             phase_state.inject_notification = _inject_phase_notification
 
-            async def _on_worker_done(event):
+            async def _on_worker_report(event):
+                """Inject [WORKER_REPORT] into queen as each worker finishes.
+
+                Subscribes to SUBAGENT_REPORT events which carry the worker's
+                real summary/data (preferring any explicit ``report_to_parent``
+                call). Every spawned worker emits exactly one — success,
+                partial, failed, timeout, or stopped. The queen sees the
+                report as the next user turn and can react (reply to user,
+                kick off follow-up work, etc.) without being blocked by the
+                spawn call itself.
+                """
                 if event.stream_id == "queen":
                     return
-                if phase_state.phase == "running":
-                    if event.type == EventType.EXECUTION_COMPLETED:
-                        session.worker_configured = True
-                        output = event.data.get("output", {})
-                        output_summary = ""
-                        if output:
-                            for key, value in output.items():
-                                val_str = str(value)
-                                if len(val_str) > 200:
-                                    val_str = val_str[:200] + "..."
-                                output_summary += f"\n  {key}: {val_str}"
-                        _out = output_summary or " (no output keys set)"
-                        notification = (
-                            "[WORKER_TERMINAL] Worker finished successfully.\n"
-                            f"Output:{_out}\n"
-                            "Report this to the user. "
-                            "Ask if they want to re-run with different input "
-                            "or tweak the configuration."
-                        )
-                    else:
-                        error = event.data.get("error", "Unknown error")
-                        notification = (
-                            "[WORKER_TERMINAL] Worker failed.\n"
-                            f"Error: {error}\n"
-                            "Report this to the user and help them troubleshoot. "
-                            "You can re-run with different input or escalate to "
-                            "building/planning if code changes are needed."
-                        )
+                data = event.data or {}
+                worker_id = data.get("worker_id", event.node_id or "unknown")
+                status = data.get("status", "unknown")
+                summary = data.get("summary") or "(no summary)"
+                err = data.get("error")
+                payload_data = data.get("data") or {}
+                duration = data.get("duration_seconds")
 
-                    await agent_loop.inject_event(notification)
-                    await phase_state.switch_to_editing(source="auto")
+                lines = ["[WORKER_REPORT]", f"worker_id: {worker_id}", f"status: {status}"]
+                if duration is not None:
+                    try:
+                        lines.append(f"duration: {float(duration):.1f}s")
+                    except (TypeError, ValueError):
+                        pass
+                lines.append(f"summary: {summary}")
+                if err:
+                    lines.append(f"error: {err}")
+                if payload_data:
+                    # Compact JSON so the queen sees all keys without the
+                    # indentation blowing up the turn's token count.
+                    try:
+                        import json as _json
+
+                        lines.append("data: " + _json.dumps(payload_data, ensure_ascii=False, default=str))
+                    except Exception:
+                        lines.append(f"data: {payload_data!r}")
+                notification = "\n".join(lines)
+
+                await agent_loop.inject_event(notification)
+                session.worker_configured = True
+
+                # Only transition to reviewing once the batch has quieted —
+                # if other workers from a parallel spawn are still live, stay
+                # in working so the queen's tool access (run_parallel_workers,
+                # inject_message, stop_worker) remains available.
+                colony_runtime = getattr(session, "colony_runtime", None)
+                still_active = 0
+                if colony_runtime is not None:
+                    try:
+                        still_active = sum(
+                            1
+                            for w in colony_runtime._workers.values()  # type: ignore[attr-defined]
+                            if getattr(w, "is_active", False)
+                        )
+                    except Exception:
+                        still_active = 0
+                if still_active == 0 and phase_state.phase in ("working", "running"):
+                    await phase_state.switch_to_reviewing(source="auto")
 
             session.event_bus.subscribe(
-                event_types=[EventType.EXECUTION_COMPLETED, EventType.EXECUTION_FAILED],
-                handler=_on_worker_done,
+                event_types=[EventType.SUBAGENT_REPORT],
+                handler=_on_worker_report,
             )
 
             # ---- Colony-scoped worker escalation routing ----

core/framework/server/routes_colonies.py

@@ -0,0 +1,505 @@
+"""HTTP routes for colony import/export — moving a colony spec between hosts.
+
+Today, just the import side: accept a `tar.gz` and unpack it into HIVE_HOME so
+a desktop client (or any external mover) can hand a colony to a remote runtime
+to run.
+
+  POST /api/colonies/import   -- multipart/form-data
+    file              required  -- .tar / .tar.gz / .tar.bz2 / .tar.xz
+    name              optional  -- override the colony name (legacy single-root
+                                   archives only); defaults to the archive's
+                                   single top-level directory
+    replace_existing  optional  -- "true" to overwrite, else 409 on conflict
+
+The desktop sends a *multi-root* tar so the queen sees a colony's full state
+(not just metadata + data) on resume. Recognised top-level prefixes:
+
+  colonies/<name>/...                                 → HIVE_HOME/colonies/<name>/...
+  agents/<name>/worker/...                            → HIVE_HOME/agents/<name>/worker/...
+  agents/queens/<queen>/sessions/<sid>/...            → HIVE_HOME/agents/queens/<queen>/sessions/<sid>/...
+
+Anything outside those is rejected. For backwards compat with older clients
+that tar `<name>/...` directly (single colony dir, no `colonies/` wrapper),
+the handler falls back to the legacy single-root flow when no recognised
+multi-root prefix is found.
+"""
+
+from __future__ import annotations
+
+import io
+import logging
+import re
+import shutil
+import tarfile
+from pathlib import Path
+
+from aiohttp import web
+
+from framework.config import COLONIES_DIR
+
+logger = logging.getLogger(__name__)
+
+# Matches the convention used elsewhere in the codebase (see
+# routes_colony_workers and queen_lifecycle_tools): lowercase alphanumerics
+# and underscores only. No dots, no slashes — names are filesystem segments.
+_COLONY_NAME_RE = re.compile(r"^[a-z0-9_]+$")
+
+# Conservative segment validator for the queen's session id (date-stamped UUID
+# tail like ``session_20260415_175106_eca07a69``) and queen name slug
+# (``queen_technology``). Same charset as colony names — the codebase already
+# normalises both to ``[a-z0-9_]+`` everywhere they're created, so accepting
+# a wider charset here would just introduce a foothold for path mischief.
+_SESSION_SEGMENT_RE = re.compile(r"^[a-z0-9_]+$")
+
+# 100 MB cap on upload size. The multi-root tar carries worker conversations
+# (often 100s of small JSON parts) plus the queen's forked session, so the
+# legacy 50 MB ceiling is too tight. Anything bigger probably shouldn't be
+# pushed wholesale anyway.
+_MAX_UPLOAD_BYTES = 100 * 1024 * 1024
+
+
+def _agents_dir() -> Path:
+    """``COLONIES_DIR`` resolves to ``HIVE_HOME/colonies``; ``agents/`` is
+    the sibling. Resolved per-call so tests that monkeypatch
+    ``COLONIES_DIR`` propagate without a second patch."""
+    return Path(COLONIES_DIR).parent / "agents"
+
+
+def _validate_colony_name(name: str) -> str | None:
+    """Return an error message if name isn't a valid colony name, else None."""
+    if not name:
+        return "colony name is required"
+    if len(name) > 64:
+        return "colony name too long (max 64 chars)"
+    if not _COLONY_NAME_RE.match(name):
+        return "colony name must match [a-z0-9_]+"
+    return None
+
+
+def _validate_session_segment(seg: str, label: str) -> str | None:
+    """Validate a path segment we're going to plumb into a destination dir."""
+    if not seg:
+        return f"{label} is required"
+    if len(seg) > 128:
+        return f"{label} too long (max 128 chars)"
+    if not _SESSION_SEGMENT_RE.match(seg):
+        return f"{label} must match [a-zA-Z0-9_-]+"
+    return None
+
+
+def _archive_top_level(tf: tarfile.TarFile) -> tuple[str | None, str | None]:
+    """Find the archive's single top-level directory, if it has one.
+
+    Used only for the legacy single-root path. Returns ``(name, error)``.
+    Allows the archive to optionally include a leading ``./`` prefix.
+    """
+    tops: set[str] = set()
+    for member in tf.getmembers():
+        if not member.name or member.name.startswith("/"):
+            return None, f"invalid member path: {member.name!r}"
+        parts = Path(member.name).parts
+        if not parts or parts[0] == "..":
+            return None, f"invalid member path: {member.name!r}"
+        first = parts[0] if parts[0] != "." else (parts[1] if len(parts) > 1 else "")
+        if first:
+            tops.add(first)
+    if len(tops) != 1:
+        return None, "archive must contain exactly one top-level directory"
+    return next(iter(tops)), None
+
+
+def _has_multi_root_prefix(tf: tarfile.TarFile) -> bool:
+    """True iff any member name starts with a recognised multi-root prefix.
+
+    The legacy shape (`<name>/...`) doesn't match either prefix, so this lets
+    us route old and new clients through the same endpoint.
+    """
+    for member in tf.getmembers():
+        name = member.name
+        if name.startswith("./"):
+            name = name[2:]
+        if name.startswith("colonies/") or name.startswith("agents/"):
+            return True
+    return False
+
+
+def _normalise_member_name(name: str) -> str:
+    """Strip a leading ``./`` if present; reject absolute or empty names."""
+    if name.startswith("./"):
+        name = name[2:]
+    return name
+
+
+def _safe_extract_tar(tf: tarfile.TarFile, dest: Path, *, strip_prefix: str) -> tuple[int, str | None]:
+    """Extract every member of ``tf`` whose name starts with ``strip_prefix/``
+    into ``dest``, with the prefix stripped off.
+
+    Each member's resolved path must stay under ``dest``; symlinks, hardlinks,
+    and device/fifo entries are rejected. Returns ``(files_extracted, error)``;
+    on error the caller is responsible for cleanup.
+
+    Members outside ``strip_prefix`` are silently *skipped* (not an error) so
+    the caller can call this multiple times on the same tar with different
+    prefixes — once per recognised root.
+    """
+    base = dest.resolve()
+    base.mkdir(parents=True, exist_ok=True)
+    files_extracted = 0
+    prefix_with_sep = f"{strip_prefix}/" if strip_prefix else ""
+
+    for member in tf.getmembers():
+        name = _normalise_member_name(member.name)
+        if not name:
+            continue
+        if strip_prefix:
+            if name == strip_prefix:
+                # The top-level dir entry itself; dest already exists.
+                continue
+            if not name.startswith(prefix_with_sep):
+                # Belongs to a different root in a multi-root tar; skip.
+                continue
+            rel = name[len(prefix_with_sep) :]
+        else:
+            rel = name
+        if not rel:
+            continue
+        if ".." in Path(rel).parts:
+            return files_extracted, f"path traversal in member: {member.name!r}"
+        if member.issym() or member.islnk():
+            return (
+                files_extracted,
+                f"symlinks/hardlinks not supported: {member.name!r}",
+            )
+        if member.isdev() or member.isfifo():
+            return (
+                files_extracted,
+                f"device/fifo not supported: {member.name!r}",
+            )
+
+        target = (base / rel).resolve()
+        try:
+            target.relative_to(base)
+        except ValueError:
+            return files_extracted, f"member escapes destination: {member.name!r}"
+
+        if member.isdir():
+            target.mkdir(parents=True, exist_ok=True)
+            continue
+
+        target.parent.mkdir(parents=True, exist_ok=True)
+        src = tf.extractfile(member)
+        if src is None:
+            return files_extracted, f"unsupported member: {member.name!r}"
+        with target.open("wb") as out:
+            shutil.copyfileobj(src, out)
+        target.chmod(member.mode & 0o755 if member.mode else 0o644)
+        files_extracted += 1
+
+    return files_extracted, None
+
+
+def _classify_multi_root_member(name: str) -> tuple[str, str] | None:
+    """Recognise a multi-root tar member and return ``(root, top_dir)``.
+
+    ``root`` is one of ``"colonies"``, ``"agents_worker"``, ``"agents_queen"``;
+    ``top_dir`` is the prefix to feed to ``_safe_extract_tar`` (the part of
+    the path that should be stripped before joining with the destination
+    base). Returns None for members that don't match any recognised root.
+
+    The caller pre-validates segments before extraction, so this is purely
+    structural: which root, what the strip prefix should be.
+    """
+    parts = Path(name).parts
+    if not parts:
+        return None
+    if parts[0] == "colonies" and len(parts) >= 2:
+        return ("colonies", f"colonies/{parts[1]}")
+    if parts[0] == "agents" and len(parts) >= 2:
+        # agents/queens/<queen>/sessions/<sid>/...  vs  agents/<name>/worker/...
+        if parts[1] == "queens":
+            if len(parts) >= 5 and parts[3] == "sessions":
+                return ("agents_queen", f"agents/queens/{parts[2]}/sessions/{parts[4]}")
+            return None
+        # Plain agent — only the worker subtree is exported.
+        if len(parts) >= 3 and parts[2] == "worker":
+            return ("agents_worker", f"agents/{parts[1]}/worker")
+        return None
+    return None
+
+
+def _plan_multi_root(
+    tf: tarfile.TarFile,
+) -> tuple[dict[str, dict[str, str]], str | None]:
+    """Walk the tar once and group entries by root.
+
+    Returns ``(groups, error)`` where ``groups`` is keyed by root kind
+    (``"colonies"`` etc.) and each entry maps the strip prefix to its
+    destination directory under HIVE_HOME. Validates name segments so we
+    bail before unpacking when something looks off.
+    """
+    groups: dict[str, dict[str, str]] = {
+        "colonies": {},
+        "agents_worker": {},
+        "agents_queen": {},
+    }
+    seen_unrecognised: set[str] = set()
+    for member in tf.getmembers():
+        name = _normalise_member_name(member.name)
+        if not name or name.startswith("/") or ".." in Path(name).parts:
+            return groups, f"invalid member path: {member.name!r}"
+        classified = _classify_multi_root_member(name)
+        if classified is None:
+            # Track unique top-level dirs to give a useful error if nothing
+            # ended up classified.
+            seen_unrecognised.add(Path(name).parts[0])
+            continue
+        kind, prefix = classified
+        if prefix in groups[kind]:
+            continue
+        # Validate path segments per-kind so we never plumb dirty input into
+        # a destination we don't fully control.
+        prefix_parts = Path(prefix).parts
+        if kind == "colonies":
+            err = _validate_colony_name(prefix_parts[1])
+            if err:
+                return groups, err
+            dest = str(COLONIES_DIR / prefix_parts[1])
+        elif kind == "agents_worker":
+            err = _validate_colony_name(prefix_parts[1])
+            if err:
+                return groups, err
+            dest = str(_agents_dir() / prefix_parts[1] / "worker")
+        elif kind == "agents_queen":
+            queen, sid = prefix_parts[2], prefix_parts[4]
+            err = _validate_session_segment(queen, "queen name")
+            if err:
+                return groups, err
+            err = _validate_session_segment(sid, "queen session id")
+            if err:
+                return groups, err
+            dest = str(_agents_dir() / "queens" / queen / "sessions" / sid)
+        else:  # pragma: no cover — defensive
+            continue
+        groups[kind][prefix] = dest
+
+    if not any(groups.values()):
+        roots = ", ".join(sorted(seen_unrecognised)) or "(none)"
+        return (
+            groups,
+            "tar has no recognised top-level prefix "
+            f"(expected colonies/, agents/<name>/worker/, "
+            f"agents/queens/<queen>/sessions/<sid>/; got: {roots})",
+        )
+    return groups, None
+
+
+async def _read_upload(
+    request: web.Request,
+) -> tuple[bytes | None, str | None, dict[str, str], web.Response | None]:
+    """Drain the multipart upload. Returns ``(bytes, filename, form, error)``."""
+    if not request.content_type.startswith("multipart/"):
+        return None, None, {}, web.json_response({"error": "expected multipart/form-data"}, status=400)
+    reader = await request.multipart()
+    upload: bytes | None = None
+    upload_filename: str | None = None
+    form: dict[str, str] = {}
+    while True:
+        part = await reader.next()
+        if part is None:
+            break
+        if part.name == "file":
+            buf = io.BytesIO()
+            while True:
+                chunk = await part.read_chunk(size=65536)
+                if not chunk:
+                    break
+                buf.write(chunk)
+                if buf.tell() > _MAX_UPLOAD_BYTES:
+                    return (
+                        None,
+                        None,
+                        {},
+                        web.json_response(
+                            {"error": f"upload exceeds {_MAX_UPLOAD_BYTES} bytes"},
+                            status=413,
+                        ),
+                    )
+            upload = buf.getvalue()
+            upload_filename = part.filename or ""
+        else:
+            form[part.name or ""] = (await part.text()).strip()
+    if upload is None:
+        return None, None, {}, web.json_response({"error": "missing 'file' part"}, status=400)
+    return upload, upload_filename, form, None
+
+
+async def handle_import_colony(request: web.Request) -> web.Response:
+    """POST /api/colonies/import — unpack a colony tarball into HIVE_HOME."""
+    upload, upload_filename, form, err_resp = await _read_upload(request)
+    if err_resp is not None:
+        return err_resp
+    assert upload is not None  # for the type checker
+
+    replace_existing = form.get("replace_existing", "false").lower() == "true"
+    name_override = form.get("name", "").strip() or None
+
+    try:
+        tf = tarfile.open(fileobj=io.BytesIO(upload), mode="r:*")
+    except tarfile.TarError as err:
+        return web.json_response({"error": f"invalid tar archive: {err}"}, status=400)
+
+    try:
+        if _has_multi_root_prefix(tf):
+            return await _import_multi_root(tf, replace_existing, upload_filename, len(upload))
+        return await _import_legacy_single_root(tf, name_override, replace_existing, upload_filename, len(upload))
+    finally:
+        tf.close()
+
+
+async def _import_legacy_single_root(
+    tf: tarfile.TarFile,
+    name_override: str | None,
+    replace_existing: bool,
+    upload_filename: str | None,
+    upload_size: int,
+) -> web.Response:
+    """Legacy path: tar contains `<name>/...` only, route to colonies/<name>/.
+
+    Kept verbatim from the previous handler so existing test fixtures and
+    older desktop builds keep working during a partial rollout.
+    """
+    top, top_err = _archive_top_level(tf)
+    if top_err or top is None:
+        return web.json_response({"error": top_err}, status=400)
+
+    colony_name = name_override or top
+    name_err = _validate_colony_name(colony_name)
+    if name_err:
+        return web.json_response({"error": name_err}, status=400)
+
+    target = COLONIES_DIR / colony_name
+    if target.exists():
+        if not replace_existing:
+            return web.json_response(
+                {
+                    "error": "colony already exists",
+                    "name": colony_name,
+                    "hint": "set replace_existing=true to overwrite",
+                },
+                status=409,
+            )
+        shutil.rmtree(target)
+
+    files_extracted, extract_err = _safe_extract_tar(tf, target, strip_prefix=top)
+    if extract_err:
+        shutil.rmtree(target, ignore_errors=True)
+        return web.json_response({"error": extract_err}, status=400)
+
+    logger.info(
+        "Imported colony %s (legacy, %d files) from upload %s (%d bytes)",
+        colony_name,
+        files_extracted,
+        upload_filename or "<unnamed>",
+        upload_size,
+    )
+    return web.json_response(
+        {
+            "name": colony_name,
+            "path": str(target),
+            "files_imported": files_extracted,
+            "replaced": replace_existing,
+        },
+        status=201,
+    )
+
+
+async def _import_multi_root(
+    tf: tarfile.TarFile,
+    replace_existing: bool,
+    upload_filename: str | None,
+    upload_size: int,
+) -> web.Response:
+    """New path: tar contains `colonies/<name>/...` plus optional agents trees.
+
+    Each recognised root is extracted to its corresponding HIVE_HOME subtree
+    using the same traversal-safe walker as the legacy path. ``replace_existing``
+    governs the colonies dir conflict; the agents trees overwrite in place
+    (worker conversations and queen sessions are append-mostly stores —
+    overwriting a stale subset is fine, and adding the conflict gate would
+    block legitimate re-pushes from a different desktop session).
+    """
+    plan, plan_err = _plan_multi_root(tf)
+    if plan_err:
+        return web.json_response({"error": plan_err}, status=400)
+
+    # Conflict guard for the colonies root only — these are user-visible
+    # entities the desktop expects to control overwrite of.
+    primary_colony_name: str | None = None
+    primary_colony_target: Path | None = None
+    for prefix, dest in plan["colonies"].items():
+        target = Path(dest)
+        primary_colony_name = Path(prefix).parts[1]
+        primary_colony_target = target
+        if target.exists() and not replace_existing:
+            return web.json_response(
+                {
+                    "error": "colony already exists",
+                    "name": primary_colony_name,
+                    "hint": "set replace_existing=true to overwrite",
+                },
+                status=409,
+            )
+        if target.exists() and replace_existing:
+            shutil.rmtree(target)
+
+    # The colonies/ root is required. agents/ trees are optional follow-ons.
+    if not plan["colonies"]:
+        return web.json_response(
+            {
+                "error": "tar missing required colonies/<name>/ root",
+            },
+            status=400,
+        )
+
+    summary: dict[str, dict[str, int | str]] = {}
+    extracted_dests: list[Path] = []
+
+    def _abort(err: str, status: int = 400) -> web.Response:
+        for path in extracted_dests:
+            shutil.rmtree(path, ignore_errors=True)
+        return web.json_response({"error": err}, status=status)
+
+    for kind in ("colonies", "agents_worker", "agents_queen"):
+        for prefix, dest in plan[kind].items():
+            target = Path(dest)
+            files_extracted, extract_err = _safe_extract_tar(tf, target, strip_prefix=prefix)
+            if extract_err:
+                return _abort(extract_err)
+            summary.setdefault(kind, {"files": 0})
+            summary[kind]["files"] = int(summary[kind].get("files", 0)) + files_extracted
+            extracted_dests.append(target)
+
+    total_files = sum(int(v.get("files", 0)) for v in summary.values())
+    logger.info(
+        "Imported colony %s (%d files across %d roots) from upload %s (%d bytes)",
+        primary_colony_name or "<unknown>",
+        total_files,
+        sum(1 for v in summary.values() if int(v.get("files", 0)) > 0),
+        upload_filename or "<unnamed>",
+        upload_size,
+    )
+
+    return web.json_response(
+        {
+            "name": primary_colony_name,
+            "path": str(primary_colony_target) if primary_colony_target else None,
+            "files_imported": total_files,
+            "by_root": summary,
+            "replaced": replace_existing,
+        },
+        status=201,
+    )
+
+
+def register_routes(app: web.Application) -> None:
+    app.router.add_post("/api/colonies/import", handle_import_colony)

core/framework/server/routes_colony_tools.py

@@ -0,0 +1,329 @@
+"""Per-colony MCP tool allowlist routes.
+
+- GET   /api/colony/{colony_name}/tools  -- enumerate colony tool surface
+- PATCH /api/colony/{colony_name}/tools  -- set or clear the allowlist
+
+A colony's tool set is inherited from the queen that forked it, so the
+tool surface mirrors the queen's MCP servers. Lifecycle/synthetic tools
+are included for display only. MCP tools are grouped by origin server
+with per-tool ``enabled`` flags.
+
+Semantics:
+
+- ``enabled_mcp_tools: null``  →  allow every MCP tool (default).
+- ``enabled_mcp_tools: []``    →  allow no MCP tools (only lifecycle /
+  synthetic pass through).
+- ``enabled_mcp_tools: [...]`` →  only listed names pass.
+
+The allowlist is persisted in a dedicated ``tools.json`` sidecar at
+``~/.hive/colonies/{colony_name}/tools.json``. Changes take effect on
+the *next* worker spawn. In-flight workers keep the tool list they
+booted with because workers have no dynamic tools provider today —
+mutating their tool set mid-turn would diverge from the list the LLM
+is already using.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from aiohttp import web
+
+from framework.host.colony_metadata import colony_metadata_path
+from framework.host.colony_tools_config import (
+    load_colony_tools_config,
+    update_colony_tools_config,
+)
+
+logger = logging.getLogger(__name__)
+
+
+_SYNTHETIC_NAMES = {"ask_user"}
+
+
+def _synthetic_entries() -> list[dict[str, Any]]:
+    try:
+        from framework.agent_loop.internals.synthetic_tools import build_ask_user_tool
+
+        tool = build_ask_user_tool()
+        return [
+            {
+                "name": tool.name,
+                "description": tool.description,
+                "editable": False,
+            }
+        ]
+    except Exception:
+        return [
+            {
+                "name": "ask_user",
+                "description": "Pause and ask the user a structured question.",
+                "editable": False,
+            }
+        ]
+
+
+def _colony_runtimes_for_name(manager: Any, colony_name: str) -> list[Any]:
+    """Return every live ColonyRuntime whose session is attached to ``colony_name``."""
+    sessions = getattr(manager, "_sessions", None) or {}
+    runtimes: list[Any] = []
+    for session in sessions.values():
+        if getattr(session, "colony_name", None) != colony_name:
+            continue
+        # Both ``session.colony`` (queen-side unified runtime) and
+        # ``session.colony_runtime`` (legacy worker runtime) may carry
+        # tools that need the allowlist applied. We update both.
+        for attr in ("colony", "colony_runtime"):
+            rt = getattr(session, attr, None)
+            if rt is not None and rt not in runtimes:
+                runtimes.append(rt)
+    return runtimes
+
+
+async def _render_catalog(manager: Any, colony_name: str) -> dict[str, list[dict[str, Any]]]:
+    """Build a per-server tool catalog for this colony.
+
+    All colonies inherit the queen's MCP surface, so we reuse the
+    manager-level ``_mcp_tool_catalog`` populated during queen boot.
+    """
+    # If a live runtime exists and carries its own registry, prefer it —
+    # it's authoritative (reflects any post-queen-boot MCP additions).
+    for rt in _colony_runtimes_for_name(manager, colony_name):
+        tools = getattr(rt, "_tools", None)
+        if not tools:
+            continue
+        mcp_names = set(getattr(rt, "_mcp_tool_names_all", set()) or set())
+        if not mcp_names:
+            continue
+        catalog: dict[str, list[dict[str, Any]]] = {"(mcp)": []}
+        for tool in tools:
+            name = getattr(tool, "name", None)
+            if name in mcp_names:
+                catalog["(mcp)"].append(
+                    {
+                        "name": name,
+                        "description": getattr(tool, "description", ""),
+                        "input_schema": getattr(tool, "parameters", {}),
+                    }
+                )
+        return catalog
+
+    # Otherwise fall back to the queen-level snapshot. Build it on demand
+    # (off the event loop) when empty so the Tool Library works before
+    # any queen has been started in this process.
+    cached = getattr(manager, "_mcp_tool_catalog", None)
+    if isinstance(cached, dict) and cached:
+        return cached
+    try:
+        import asyncio
+
+        from framework.server.queen_orchestrator import build_queen_tool_registry_bare
+
+        registry, built = await asyncio.to_thread(build_queen_tool_registry_bare)
+        if manager is not None:
+            manager._mcp_tool_catalog = built  # type: ignore[attr-defined]
+            manager._bootstrap_tool_registry = registry  # type: ignore[attr-defined]
+        return built
+    except Exception:
+        logger.warning("Colony tools: catalog bootstrap failed", exc_info=True)
+        return {}
+
+
+def _lifecycle_entries_from_runtime(manager: Any, colony_name: str) -> list[dict[str, Any]]:
+    """Non-MCP tools currently registered on the colony runtime (if any).
+
+    When no live runtime is available we fall back to the bootstrap
+    registry stashed on the manager by ``routes_queen_tools`` — it
+    already has queen lifecycle tools registered, which are also the
+    lifecycle tools colonies inherit at spawn time.
+    """
+    out: list[dict[str, Any]] = []
+    seen: set[str] = set()
+
+    def _push(name: str, description: str) -> None:
+        if not name or name in seen:
+            return
+        if name in _SYNTHETIC_NAMES:
+            return
+        seen.add(name)
+        out.append({"name": name, "description": description, "editable": False})
+
+    runtimes = _colony_runtimes_for_name(manager, colony_name)
+    if runtimes:
+        for rt in runtimes:
+            mcp_names = set(getattr(rt, "_mcp_tool_names_all", set()) or set())
+            for tool in getattr(rt, "_tools", []) or []:
+                name = getattr(tool, "name", None)
+                if name in mcp_names:
+                    continue
+                _push(name, getattr(tool, "description", ""))
+    else:
+        # No live runtime — derive from the bootstrap registry.
+        from framework.server.routes_queen_tools import _lifecycle_entries_without_session
+
+        catalog = getattr(manager, "_mcp_tool_catalog", {}) or {}
+        mcp_names: set[str] = set()
+        for entries in catalog.values():
+            for entry in entries:
+                if entry.get("name"):
+                    mcp_names.add(entry["name"])
+        out.extend(_lifecycle_entries_without_session(manager, mcp_names))
+        return out
+    return sorted(out, key=lambda e: e["name"])
+
+
+def _render_servers(
+    catalog: dict[str, list[dict[str, Any]]],
+    enabled_mcp_tools: list[str] | None,
+) -> list[dict[str, Any]]:
+    allowed: set[str] | None = None if enabled_mcp_tools is None else set(enabled_mcp_tools)
+    servers: list[dict[str, Any]] = []
+    for name in sorted(catalog):
+        tools = []
+        for entry in catalog[name]:
+            tool_name = entry.get("name")
+            tools.append(
+                {
+                    "name": tool_name,
+                    "description": entry.get("description", ""),
+                    "input_schema": entry.get("input_schema", {}),
+                    "enabled": True if allowed is None else tool_name in allowed,
+                }
+            )
+        servers.append({"name": name, "tools": tools})
+    return servers
+
+
+async def handle_get_tools(request: web.Request) -> web.Response:
+    """GET /api/colony/{colony_name}/tools."""
+    colony_name = request.match_info["colony_name"]
+    if not colony_metadata_path(colony_name).exists():
+        return web.json_response({"error": f"Colony '{colony_name}' not found"}, status=404)
+
+    manager = request.app.get("manager")
+    # Allowlist now lives in a dedicated tools.json sidecar; helper
+    # migrates any legacy metadata.json field on first read.
+    enabled = load_colony_tools_config(colony_name)
+
+    catalog = await _render_catalog(manager, colony_name)
+    stale = not catalog
+
+    return web.json_response(
+        {
+            "colony_name": colony_name,
+            "enabled_mcp_tools": enabled,
+            "stale": stale,
+            "lifecycle": _lifecycle_entries_from_runtime(manager, colony_name),
+            "synthetic": _synthetic_entries(),
+            "mcp_servers": _render_servers(catalog, enabled),
+        }
+    )
+
+
+async def handle_patch_tools(request: web.Request) -> web.Response:
+    """PATCH /api/colony/{colony_name}/tools."""
+    colony_name = request.match_info["colony_name"]
+    if not colony_metadata_path(colony_name).exists():
+        return web.json_response({"error": f"Colony '{colony_name}' not found"}, status=404)
+
+    try:
+        body = await request.json()
+    except Exception:
+        return web.json_response({"error": "Invalid JSON body"}, status=400)
+    if not isinstance(body, dict) or "enabled_mcp_tools" not in body:
+        return web.json_response(
+            {"error": "Body must be an object with an 'enabled_mcp_tools' field"},
+            status=400,
+        )
+
+    enabled = body["enabled_mcp_tools"]
+    if enabled is not None:
+        if not isinstance(enabled, list) or not all(isinstance(x, str) for x in enabled):
+            return web.json_response(
+                {"error": "'enabled_mcp_tools' must be null or a list of strings"},
+                status=400,
+            )
+
+    manager = request.app.get("manager")
+
+    # Validate names against the known MCP catalog — lifts the same
+    # typo-catching guarantee we already offer on queen tools.
+    catalog = await _render_catalog(manager, colony_name)
+    known: set[str] = {e.get("name") for entries in catalog.values() for e in entries if e.get("name")}
+    if enabled is not None and known:
+        unknown = sorted(set(enabled) - known)
+        if unknown:
+            return web.json_response(
+                {"error": "Unknown MCP tool name(s)", "unknown": unknown},
+                status=400,
+            )
+
+    # Persist — tools.json sidecar, not metadata.json. Missing directory
+    # is already guarded by the 404 check above.
+    try:
+        update_colony_tools_config(colony_name, enabled)
+    except FileNotFoundError:
+        return web.json_response({"error": f"Colony '{colony_name}' not found"}, status=404)
+
+    # Update any live runtimes so the NEXT worker spawn reflects the change.
+    # We do NOT rebuild in-flight workers' tool lists (see module docstring).
+    refreshed = 0
+    for rt in _colony_runtimes_for_name(manager, colony_name):
+        setter = getattr(rt, "set_tool_allowlist", None)
+        if callable(setter):
+            try:
+                setter(enabled)
+                refreshed += 1
+            except Exception:
+                logger.debug(
+                    "Colony tools: set_tool_allowlist failed on runtime for %s",
+                    colony_name,
+                    exc_info=True,
+                )
+
+    logger.info(
+        "Colony tools: colony=%s allowlist=%s refreshed_runtimes=%d",
+        colony_name,
+        "null" if enabled is None else f"{len(enabled)} tool(s)",
+        refreshed,
+    )
+    return web.json_response(
+        {
+            "colony_name": colony_name,
+            "enabled_mcp_tools": enabled,
+            "refreshed_runtimes": refreshed,
+            "note": "Changes apply to the next worker spawn. Running workers keep their booted tool list.",
+        }
+    )
+
+
+async def handle_list_colonies(request: web.Request) -> web.Response:
+    """GET /api/colonies — list colonies with their tool allowlist status.
+
+    Powers the Tool Library page's colony picker.
+    """
+    from framework.host.colony_metadata import list_colony_names, load_colony_metadata
+
+    colonies: list[dict[str, Any]] = []
+    for name in list_colony_names():
+        meta = load_colony_metadata(name)
+        # Provenance stays in metadata.json; allowlist lives in tools.json.
+        allowlist = load_colony_tools_config(name)
+        colonies.append(
+            {
+                "name": name,
+                "queen_name": meta.get("queen_name"),
+                "created_at": meta.get("created_at"),
+                "has_allowlist": allowlist is not None,
+                "enabled_count": len(allowlist) if isinstance(allowlist, list) else None,
+            }
+        )
+    return web.json_response({"colonies": colonies})
+
+
+def register_routes(app: web.Application) -> None:
+    """Register per-colony tool routes."""
+    app.router.add_get("/api/colonies/tools-index", handle_list_colonies)
+    app.router.add_get("/api/colony/{colony_name}/tools", handle_get_tools)
+    app.router.add_patch("/api/colony/{colony_name}/tools", handle_patch_tools)

core/framework/server/routes_colony_workers.py

@@ -0,0 +1,706 @@
+"""Colony worker inspection routes.
+
+These expose per-spawned-worker data (identified by worker_id) so the
+frontend can render a colony-workers sidebar analogous to the queen
+profile panel. Distinct from ``routes_workers.py``, which deals with
+*graph nodes* inside a worker definition rather than live worker
+instances.
+
+Session-scoped (bound to a live session's runtime):
+- GET /api/sessions/{session_id}/workers            — live + completed workers
+- GET /api/sessions/{session_id}/colony/skills      — colony's shared skills catalog
+- GET /api/sessions/{session_id}/colony/tools       — colony's default tools
+
+Colony-scoped (bound to the on-disk colony directory, independent of any
+live session — one colony has exactly one progress.db):
+- GET /api/colonies/{colony_name}/progress/snapshot — progress.db tasks/steps snapshot
+- GET /api/colonies/{colony_name}/progress/stream   — SSE feed of upserts (polled)
+- GET /api/colonies/{colony_name}/data/tables       — list user tables in progress.db
+- GET /api/colonies/{colony_name}/data/tables/{table}/rows — paginated rows
+- PATCH /api/colonies/{colony_name}/data/tables/{table}/rows — edit a row
+"""
+
+import asyncio
+import json
+import logging
+import re
+import sqlite3
+from pathlib import Path
+
+from aiohttp import web
+
+from framework.server.app import resolve_session
+
+# Same validation used by create_colony — keep them in sync. Blocks path
+# traversal (``..``) and shell-special chars; the endpoint would 400 on
+# anything else anyway, but validating early avoids a disk hit.
+_COLONY_NAME_RE = re.compile(r"^[a-z0-9_]+$")
+
+logger = logging.getLogger(__name__)
+
+# Poll interval for the progress SSE stream. Progress rows flip on the
+# order of seconds as workers finish LLM turns, so 1s feels live without
+# hammering the DB.
+_PROGRESS_POLL_INTERVAL = 1.0
+
+
+def _worker_info_to_dict(info) -> dict:
+    """Serialize a WorkerInfo dataclass to a JSON-friendly dict."""
+    result_dict = None
+    if info.result is not None:
+        r = info.result
+        result_dict = {
+            "status": r.status,
+            "summary": r.summary,
+            "error": r.error,
+            "tokens_used": r.tokens_used,
+            "duration_seconds": r.duration_seconds,
+        }
+    return {
+        "worker_id": info.id,
+        "task": info.task,
+        "status": str(info.status),
+        "started_at": info.started_at,
+        "result": result_dict,
+    }
+
+
+async def handle_list_workers(request: web.Request) -> web.Response:
+    """GET /api/sessions/{session_id}/workers -- list workers in a session's colony.
+
+    Returns two populations merged:
+      1. In-memory workers from the session's unified ColonyRuntime
+         (``session.colony._workers``). Includes live + just-finished
+         entries since ``_workers`` isn't pruned on termination.
+      2. Historical worker directories on disk under
+         ``<session_dir>/workers/`` that are not in memory. Populated
+         from dir name / first user message / dir mtime. These appear
+         as ``status="historical"`` so the frontend can style them
+         distinctly from actives.
+
+    Falls back to the legacy ``session.colony_runtime`` for the
+    in-memory half when ``session.colony`` isn't set.
+    """
+    session, err = resolve_session(request)
+    if err:
+        return err
+
+    runtime = getattr(session, "colony", None) or getattr(session, "colony_runtime", None)
+
+    workers: list[dict] = []
+    known_ids: set[str] = set()
+    storage_path: Path | None = None
+    if runtime is not None:
+        for info in runtime.list_workers():
+            workers.append(_worker_info_to_dict(info))
+            known_ids.add(info.id)
+        raw_storage = getattr(runtime, "_storage_path", None)
+        if raw_storage is not None:
+            storage_path = Path(raw_storage)
+
+    # Fall back to the session's directory if the runtime didn't expose one.
+    if storage_path is None:
+        session_dir = getattr(session, "queen_dir", None) or getattr(session, "session_dir", None)
+        if session_dir is not None:
+            storage_path = Path(session_dir)
+
+    if storage_path is not None:
+        workers.extend(await asyncio.to_thread(_walk_historical_workers, storage_path, known_ids))
+
+    return web.json_response({"workers": workers})
+
+
+def _walk_historical_workers(storage_path: Path, known_ids: set[str]) -> list[dict]:
+    """Scan ``<storage_path>/workers/`` for worker session dirs not already
+    in memory and return minimal ``WorkerSummary``-shaped entries.
+
+    We don't persist a standalone status file per worker, so the on-disk
+    entries get ``status="historical"`` and ``result=None``. The task is
+    reconstructed from the first non-boilerplate user message in the
+    worker's conversation parts.
+    """
+    workers_dir = storage_path / "workers"
+    if not workers_dir.exists() or not workers_dir.is_dir():
+        return []
+
+    out: list[dict] = []
+    try:
+        entries = list(workers_dir.iterdir())
+    except OSError:
+        return []
+
+    # Newest dir first so recent runs surface first in the tab.
+    entries.sort(key=lambda p: _safe_mtime(p), reverse=True)
+
+    for entry in entries:
+        if not entry.is_dir():
+            continue
+        wid = entry.name
+        if wid in known_ids:
+            continue
+        out.append(
+            {
+                "worker_id": wid,
+                "task": _extract_historical_task(entry),
+                "status": "historical",
+                "started_at": _safe_mtime(entry),
+                "result": None,
+            }
+        )
+    return out
+
+
+def _safe_mtime(path: Path) -> float:
+    try:
+        return path.stat().st_mtime
+    except OSError:
+        return 0.0
+
+
+def _extract_historical_task(worker_dir: Path) -> str:
+    """Pull the worker's initial task from its conversation parts.
+
+    seq 0 is a boilerplate "Hello" greeting in most flows; the real
+    task lands in an early user message (typically seq 1 or 2). Scan
+    the first few parts and return the first ``role="user"`` content
+    that isn't the greeting. Bounded at 5 parts to stay cheap on
+    directory listings containing hundreds of workers.
+    """
+    parts_dir = worker_dir / "conversations" / "parts"
+    if not parts_dir.exists():
+        return ""
+    try:
+        for i in range(5):
+            p = parts_dir / f"{i:010d}.json"
+            if not p.exists():
+                break
+            data = json.loads(p.read_text(encoding="utf-8"))
+            if data.get("role") != "user":
+                continue
+            content = data.get("content", "")
+            if not isinstance(content, str):
+                continue
+            text = content.strip()
+            if not text or text.lower() == "hello":
+                continue
+            return text[:400]
+    except Exception:
+        return ""
+    return ""
+
+
+# ── Skills & tools ─────────────────────────────────────────────────
+
+
+def _parsed_skill_to_dict(skill) -> dict:
+    """Serialize a ParsedSkill for the frontend."""
+    return {
+        "name": skill.name,
+        "description": skill.description,
+        "location": skill.location,
+        "base_dir": skill.base_dir,
+        "source_scope": skill.source_scope,
+    }
+
+
+async def handle_list_colony_skills(request: web.Request) -> web.Response:
+    """GET /api/sessions/{session_id}/colony/skills -- list skills the colony sees."""
+    session, err = resolve_session(request)
+    if err:
+        return err
+
+    runtime = session.colony_runtime
+    if runtime is None:
+        return web.json_response({"skills": []})
+
+    # Reach into the skills manager's catalog. There is no public
+    # iterator yet; we touch the private dict directly and defensively
+    # tolerate either shape (bare SkillsManager, or the
+    # from_precomputed variant which has no catalog).
+    catalog = getattr(runtime._skills_manager, "_catalog", None)
+    skills_dict = getattr(catalog, "_skills", None) if catalog is not None else None
+    if not isinstance(skills_dict, dict):
+        return web.json_response({"skills": []})
+
+    skills = [_parsed_skill_to_dict(s) for s in skills_dict.values()]
+    skills.sort(key=lambda s: s["name"])
+    return web.json_response({"skills": skills})
+
+
+# Tools that ship with the framework and have no credential provider,
+# but still deserve their own logical group. Surfaced to the frontend
+# as ``provider="system"`` so the UI treats them exactly like a
+# credential-backed group.
+_SYSTEM_TOOLS: frozenset[str] = frozenset(
+    {
+        "get_account_info",
+        "get_current_time",
+    }
+)
+
+
+def _tool_to_dict(tool, provider_map: dict[str, str] | None) -> dict:
+    """Serialize a Tool dataclass for the frontend.
+
+    ``provider_map`` is the colony runtime's tool_name → credential
+    provider map (built by the CredentialResolver pipeline stage from
+    ``CredentialStoreAdapter.get_tool_provider_map()``). Credential-
+    backed tools get a canonical provider key (e.g. ``"hubspot"``,
+    ``"gmail"``); framework / core tools return ``None``, except for
+    the hand-picked entries in ``_SYSTEM_TOOLS`` which are tagged
+    ``"system"``.
+    """
+    name = getattr(tool, "name", "")
+    provider = (provider_map or {}).get(name)
+    if provider is None and name in _SYSTEM_TOOLS:
+        provider = "system"
+    return {
+        "name": name,
+        "description": getattr(tool, "description", ""),
+        "provider": provider,
+    }
+
+
+async def handle_list_colony_tools(request: web.Request) -> web.Response:
+    """GET /api/sessions/{session_id}/colony/tools -- list the colony's default tools."""
+    session, err = resolve_session(request)
+    if err:
+        return err
+
+    runtime = session.colony_runtime
+    if runtime is None:
+        return web.json_response({"tools": []})
+
+    provider_map = getattr(runtime, "_tool_provider_map", None)
+    tools = [_tool_to_dict(t, provider_map) for t in (runtime._tools or [])]
+    tools.sort(key=lambda t: t["name"])
+    return web.json_response({"tools": tools})
+
+
+# ── Progress DB (tasks/steps) ──────────────────────────────────────
+
+
+def _resolve_progress_db_by_name(colony_name: str) -> Path | None:
+    """Resolve a colony's progress.db path by directory name.
+
+    Returns ``None`` when the name fails validation or the file does not
+    exist. Both conditions render as an empty Data tab in the UI rather
+    than a hard error so an operator can open the panel before any
+    workers have actually run.
+    """
+    if not _COLONY_NAME_RE.match(colony_name):
+        return None
+    from framework.config import COLONIES_DIR
+
+    db_path = COLONIES_DIR / colony_name / "data" / "progress.db"
+    return db_path if db_path.exists() else None
+
+
+def _read_progress_snapshot(db_path: Path, worker_id: str | None) -> dict:
+    """Read tasks + steps from progress.db, optionally filtered by worker_id.
+
+    The worker_id filter applies to tasks (claimed by that worker) and
+    to steps (executed by that worker). If omitted, returns all rows.
+    """
+    con = sqlite3.connect(f"file:{db_path}?mode=ro", uri=True, timeout=5.0)
+    try:
+        con.row_factory = sqlite3.Row
+        if worker_id:
+            task_rows = con.execute(
+                "SELECT * FROM tasks WHERE worker_id = ? ORDER BY updated_at DESC",
+                (worker_id,),
+            ).fetchall()
+            step_rows = con.execute(
+                "SELECT * FROM steps WHERE worker_id = ? ORDER BY task_id, seq",
+                (worker_id,),
+            ).fetchall()
+        else:
+            task_rows = con.execute("SELECT * FROM tasks ORDER BY updated_at DESC LIMIT 500").fetchall()
+            step_rows = con.execute("SELECT * FROM steps ORDER BY task_id, seq LIMIT 2000").fetchall()
+        return {
+            "tasks": [dict(r) for r in task_rows],
+            "steps": [dict(r) for r in step_rows],
+        }
+    finally:
+        con.close()
+
+
+async def handle_progress_snapshot(request: web.Request) -> web.Response:
+    """GET /api/colonies/{colony_name}/progress/snapshot
+
+    Optional ?worker_id=... to filter to rows touched by a specific worker.
+    """
+    colony_name = request.match_info["colony_name"]
+    db_path = _resolve_progress_db_by_name(colony_name)
+    if db_path is None:
+        return web.json_response({"tasks": [], "steps": []})
+
+    worker_id = request.query.get("worker_id") or None
+    snapshot = await asyncio.to_thread(_read_progress_snapshot, db_path, worker_id)
+    return web.json_response(snapshot)
+
+
+def _read_progress_upserts(
+    db_path: Path,
+    worker_id: str | None,
+    since: str | None,
+) -> tuple[list[dict], list[dict], str | None]:
+    """Return task/step rows with ``updated_at`` (tasks) or a derived
+    timestamp (steps) newer than ``since``, plus the new high-water mark.
+
+    Steps don't carry an ``updated_at`` column — we use
+    ``COALESCE(completed_at, started_at)`` as the change witness. A step
+    without either timestamp hasn't changed since the last poll and is
+    skipped.
+
+    ``since`` is an ISO8601 string (as produced by progress_db._now_iso).
+    ``None`` means "give me everything" — used for the SSE priming frame.
+    """
+    con = sqlite3.connect(f"file:{db_path}?mode=ro", uri=True, timeout=5.0)
+    try:
+        con.row_factory = sqlite3.Row
+        task_sql = "SELECT * FROM tasks"
+        step_sql = (
+            "SELECT *, COALESCE(completed_at, started_at) AS _ts "
+            "FROM steps WHERE COALESCE(completed_at, started_at) IS NOT NULL"
+        )
+        task_args: list = []
+        step_args: list = []
+        if since is not None:
+            task_sql += " WHERE updated_at > ?"
+            step_sql += " AND COALESCE(completed_at, started_at) > ?"
+            task_args.append(since)
+            step_args.append(since)
+        if worker_id:
+            joiner_t = " AND " if since is not None else " WHERE "
+            task_sql += joiner_t + "worker_id = ?"
+            step_sql += " AND worker_id = ?"
+            task_args.append(worker_id)
+            step_args.append(worker_id)
+        task_sql += " ORDER BY updated_at"
+        step_sql += " ORDER BY _ts"
+
+        task_rows = con.execute(task_sql, task_args).fetchall()
+        step_rows = con.execute(step_sql, step_args).fetchall()
+
+        tasks = [dict(r) for r in task_rows]
+        steps = [dict(r) for r in step_rows]
+        # High-water mark = max timestamp across both sets. Fall back to
+        # the previous ``since`` when nothing changed.
+        ts_values = [t["updated_at"] for t in tasks]
+        ts_values.extend(s["_ts"] for s in steps if s.get("_ts"))
+        new_since = max(ts_values) if ts_values else since
+        return tasks, steps, new_since
+    finally:
+        con.close()
+
+
+async def handle_progress_stream(request: web.Request) -> web.StreamResponse:
+    """GET /api/colonies/{colony_name}/progress/stream
+
+    SSE feed that emits ``snapshot`` once (current state) followed by
+    ``upsert`` events whenever a task/step row changes. Polls the DB
+    every ``_PROGRESS_POLL_INTERVAL`` seconds — the sqlite3 CLI path
+    workers use for writes doesn't fire SQLite's update hook on our
+    connection, so polling is the robust option.
+    """
+    colony_name = request.match_info["colony_name"]
+    worker_id = request.query.get("worker_id") or None
+
+    resp = web.StreamResponse(
+        status=200,
+        headers={
+            "Content-Type": "text/event-stream",
+            "Cache-Control": "no-cache, no-transform",
+            "Connection": "keep-alive",
+            "X-Accel-Buffering": "no",
+        },
+    )
+    await resp.prepare(request)
+
+    async def _send(event: str, data: dict) -> None:
+        payload = f"event: {event}\ndata: {json.dumps(data)}\n\n"
+        await resp.write(payload.encode("utf-8"))
+
+    db_path = _resolve_progress_db_by_name(colony_name)
+    if db_path is None:
+        await _send("snapshot", {"tasks": [], "steps": []})
+        await _send("end", {"reason": "no_progress_db"})
+        return resp
+
+    try:
+        snapshot = await asyncio.to_thread(_read_progress_snapshot, db_path, worker_id)
+        await _send("snapshot", snapshot)
+
+        since: str | None = None
+        # Initialize the high-water mark from the snapshot so we don't
+        # re-emit every row as "new" on the first poll.
+        ts_values: list[str] = [t.get("updated_at") for t in snapshot["tasks"] if t.get("updated_at")]
+        ts_values.extend(
+            s.get("completed_at") or s.get("started_at")
+            for s in snapshot["steps"]
+            if s.get("completed_at") or s.get("started_at")
+        )
+        if ts_values:
+            since = max(v for v in ts_values if v)
+
+        # The loop relies on client disconnect surfacing as
+        # ConnectionResetError from ``_send`` — no explicit alive check
+        # required.
+        while True:
+            await asyncio.sleep(_PROGRESS_POLL_INTERVAL)
+            tasks, steps, new_since = await asyncio.to_thread(_read_progress_upserts, db_path, worker_id, since)
+            if tasks or steps:
+                await _send("upsert", {"tasks": tasks, "steps": steps})
+                since = new_since
+    except (asyncio.CancelledError, ConnectionResetError):
+        # Client disconnected; clean exit.
+        raise
+    except Exception as exc:
+        logger.warning("progress stream error: %s", exc, exc_info=True)
+        try:
+            await _send("error", {"message": str(exc)})
+        except Exception:
+            pass
+    return resp
+
+
+# ── Raw data grid (airtable-style view/edit of progress.db tables) ─────
+#
+# The Data tab lets the operator inspect and hand-edit SQLite rows.
+# Identifier-quoting note: SQLite params can only bind values, never
+# identifiers, so we have to interpolate table/column names into SQL.
+# Every name is *validated against sqlite_master / PRAGMA table_info*
+# before use and then wrapped with ``_q()`` which escapes embedded
+# quotes. Do NOT accept raw names from the request without running them
+# through ``_validate_ident`` first.
+
+
+def _q(ident: str) -> str:
+    """Quote a SQLite identifier (table or column) safely."""
+    return '"' + ident.replace('"', '""') + '"'
+
+
+def _list_user_tables(con: sqlite3.Connection) -> list[str]:
+    return [
+        r["name"]
+        for r in con.execute(
+            "SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%' ORDER BY name"
+        )
+    ]
+
+
+def _table_columns(con: sqlite3.Connection, table: str) -> list[dict]:
+    """Return PRAGMA table_info rows as dicts. Empty list if no such table."""
+    return [
+        {
+            "name": r["name"],
+            "type": r["type"] or "",
+            "notnull": bool(r["notnull"]),
+            # pk>0 means the column is part of the primary key (ordinal);
+            # 0 means non-PK.
+            "pk": int(r["pk"]),
+            "dflt_value": r["dflt_value"],
+        }
+        for r in con.execute(f"PRAGMA table_info({_q(table)})")
+    ]
+
+
+def _read_tables_overview(db_path: Path) -> list[dict]:
+    """List user tables with columns + row counts."""
+    con = sqlite3.connect(f"file:{db_path}?mode=ro", uri=True, timeout=5.0)
+    try:
+        con.row_factory = sqlite3.Row
+        out: list[dict] = []
+        for name in _list_user_tables(con):
+            cols = _table_columns(con, name)
+            count_row = con.execute(f"SELECT COUNT(*) AS c FROM {_q(name)}").fetchone()
+            out.append(
+                {
+                    "name": name,
+                    "columns": cols,
+                    "row_count": int(count_row["c"]),
+                    "primary_key": [c["name"] for c in cols if c["pk"] > 0],
+                }
+            )
+        return out
+    finally:
+        con.close()
+
+
+def _validate_ident(name: str, known: set[str]) -> str | None:
+    """Return ``name`` if present in ``known``, else ``None``."""
+    return name if name in known else None
+
+
+def _read_table_rows(
+    db_path: Path,
+    table: str,
+    limit: int,
+    offset: int,
+    order_by: str | None,
+    order_dir: str,
+) -> dict:
+    con = sqlite3.connect(f"file:{db_path}?mode=ro", uri=True, timeout=5.0)
+    try:
+        con.row_factory = sqlite3.Row
+        tables = set(_list_user_tables(con))
+        if _validate_ident(table, tables) is None:
+            return {"error": f"unknown table: {table}"}
+        cols = _table_columns(con, table)
+        col_names = {c["name"] for c in cols}
+
+        sql = f"SELECT * FROM {_q(table)}"
+        if order_by and order_by in col_names:
+            direction = "DESC" if order_dir.lower() == "desc" else "ASC"
+            sql += f" ORDER BY {_q(order_by)} {direction}"
+        sql += " LIMIT ? OFFSET ?"
+        rows = con.execute(sql, (int(limit), int(offset))).fetchall()
+        total = con.execute(f"SELECT COUNT(*) AS c FROM {_q(table)}").fetchone()["c"]
+        return {
+            "table": table,
+            "columns": cols,
+            "primary_key": [c["name"] for c in cols if c["pk"] > 0],
+            "rows": [dict(r) for r in rows],
+            "total": int(total),
+            "limit": int(limit),
+            "offset": int(offset),
+        }
+    finally:
+        con.close()
+
+
+def _update_table_row(
+    db_path: Path,
+    table: str,
+    pk: dict,
+    updates: dict,
+) -> dict:
+    """Apply ``updates`` (column->value) to the row matching ``pk``.
+
+    Returns ``{"updated": n}`` with the number of rows affected (0 or 1),
+    or ``{"error": ...}`` on validation failure.
+    """
+    if not updates:
+        return {"error": "no updates provided"}
+    con = sqlite3.connect(db_path, timeout=5.0)
+    try:
+        con.row_factory = sqlite3.Row
+        tables = set(_list_user_tables(con))
+        if _validate_ident(table, tables) is None:
+            return {"error": f"unknown table: {table}"}
+        cols = _table_columns(con, table)
+        col_names = {c["name"] for c in cols}
+        pk_cols = [c["name"] for c in cols if c["pk"] > 0]
+        if not pk_cols:
+            return {"error": f"table {table!r} has no primary key; cannot edit by row"}
+
+        # Validate pk has every pk column and all values are scalars.
+        missing = [p for p in pk_cols if p not in pk]
+        if missing:
+            return {"error": f"missing primary key columns: {missing}"}
+
+        # Validate update columns exist and aren't part of the primary key
+        # (changing a PK column would silently break joins/foreign refs).
+        bad = [c for c in updates if c not in col_names]
+        if bad:
+            return {"error": f"unknown columns: {bad}"}
+        pk_update = [c for c in updates if c in pk_cols]
+        if pk_update:
+            return {"error": f"cannot edit primary key columns: {pk_update}"}
+
+        set_sql = ", ".join(f"{_q(c)} = ?" for c in updates)
+        where_sql = " AND ".join(f"{_q(c)} = ?" for c in pk_cols)
+        sql = f"UPDATE {_q(table)} SET {set_sql} WHERE {where_sql}"
+        params = list(updates.values()) + [pk[c] for c in pk_cols]
+        cur = con.execute(sql, params)
+        con.commit()
+        return {"updated": cur.rowcount}
+    finally:
+        con.close()
+
+
+async def handle_list_tables(request: web.Request) -> web.Response:
+    """GET /api/colonies/{colony_name}/data/tables"""
+    colony_name = request.match_info["colony_name"]
+    db_path = _resolve_progress_db_by_name(colony_name)
+    if db_path is None:
+        return web.json_response({"tables": []})
+    tables = await asyncio.to_thread(_read_tables_overview, db_path)
+    return web.json_response({"tables": tables})
+
+
+async def handle_table_rows(request: web.Request) -> web.Response:
+    """GET /api/colonies/{colony_name}/data/tables/{table}/rows"""
+    colony_name = request.match_info["colony_name"]
+    db_path = _resolve_progress_db_by_name(colony_name)
+    if db_path is None:
+        return web.json_response({"error": "no progress.db"}, status=404)
+
+    table = request.match_info["table"]
+    # Clamp limit: 500 is enough for the grid's virtualization window;
+    # a larger cap would make accidental full-table loads cheap.
+    try:
+        limit = max(1, min(500, int(request.query.get("limit", "100"))))
+        offset = max(0, int(request.query.get("offset", "0")))
+    except ValueError:
+        return web.json_response({"error": "invalid limit/offset"}, status=400)
+    order_by = request.query.get("order_by") or None
+    order_dir = request.query.get("order_dir", "asc")
+
+    result = await asyncio.to_thread(_read_table_rows, db_path, table, limit, offset, order_by, order_dir)
+    if "error" in result:
+        return web.json_response(result, status=400)
+    return web.json_response(result)
+
+
+async def handle_update_row(request: web.Request) -> web.Response:
+    """PATCH /api/colonies/{colony_name}/data/tables/{table}/rows
+
+    Body: ``{"pk": {col: value, ...}, "updates": {col: value, ...}}``.
+    """
+    colony_name = request.match_info["colony_name"]
+    db_path = _resolve_progress_db_by_name(colony_name)
+    if db_path is None:
+        return web.json_response({"error": "no progress.db"}, status=404)
+
+    try:
+        body = await request.json()
+    except Exception:
+        return web.json_response({"error": "invalid JSON body"}, status=400)
+    pk = body.get("pk") or {}
+    updates = body.get("updates") or {}
+    if not isinstance(pk, dict) or not isinstance(updates, dict):
+        return web.json_response({"error": "pk and updates must be objects"}, status=400)
+
+    table = request.match_info["table"]
+    result = await asyncio.to_thread(_update_table_row, db_path, table, pk, updates)
+    if "error" in result:
+        return web.json_response(result, status=400)
+    return web.json_response(result)
+
+
+def register_routes(app: web.Application) -> None:
+    """Register colony worker routes."""
+    # Session-scoped — these read live runtime state from a session.
+    app.router.add_get("/api/sessions/{session_id}/workers", handle_list_workers)
+    app.router.add_get("/api/sessions/{session_id}/colony/skills", handle_list_colony_skills)
+    app.router.add_get("/api/sessions/{session_id}/colony/tools", handle_list_colony_tools)
+    # Colony-scoped — one progress.db per colony, no session indirection.
+    app.router.add_get(
+        "/api/colonies/{colony_name}/progress/snapshot",
+        handle_progress_snapshot,
+    )
+    app.router.add_get(
+        "/api/colonies/{colony_name}/progress/stream",
+        handle_progress_stream,
+    )
+    app.router.add_get("/api/colonies/{colony_name}/data/tables", handle_list_tables)
+    app.router.add_get(
+        "/api/colonies/{colony_name}/data/tables/{table}/rows",
+        handle_table_rows,
+    )
+    app.router.add_patch(
+        "/api/colonies/{colony_name}/data/tables/{table}/rows",
+        handle_update_row,
+    )

core/framework/server/routes_config.py

@@ -6,6 +6,7 @@ Routes:
 - GET  /api/config/models        — curated provider→models list
 """
 
+import asyncio
 import json
 import logging
 import os
@@ -50,6 +51,8 @@ PROVIDER_ENV_VARS: dict[str, str] = {
     "together": "TOGETHER_API_KEY",
     "together_ai": "TOGETHER_API_KEY",
     "deepseek": "DEEPSEEK_API_KEY",
+    "kimi": "KIMI_API_KEY",
+    "hive": "HIVE_API_KEY",
 }
 
 _SUBSCRIPTION_DEFINITIONS: list[dict[str, str]] = [
@@ -301,6 +304,53 @@ def _hot_swap_sessions(request: web.Request, full_model: str, api_key: str | Non
     return swapped
 
 
+async def _validate_provider_key(
+    provider: str,
+    api_key: str,
+    api_base: str | None = None,
+    model: str | None = None,
+) -> dict:
+    """Validate an API key against the provider. Returns {"valid": bool, "message": str}.
+
+    Runs the check in a thread pool to avoid blocking the event loop.
+    """
+    from scripts.check_llm_key import (
+        PROVIDERS as CHECK_PROVIDERS,
+        check_anthropic_compatible,
+        check_minimax,
+        check_openai_compatible,
+        check_openrouter,
+        check_openrouter_model,
+    )
+
+    def _check() -> dict:
+        pid = provider.lower()
+        try:
+            # Subscription providers with custom api_base
+            if pid == "openrouter" and model:
+                return check_openrouter_model(api_key, model=model, api_base=api_base or "https://openrouter.ai/api/v1")
+            if api_base and pid == "minimax":
+                return check_minimax(api_key, api_base)
+            if api_base and pid == "openrouter":
+                return check_openrouter(api_key, api_base)
+            if api_base and pid == "kimi":
+                return check_anthropic_compatible(api_key, api_base.rstrip("/") + "/v1/messages", "Kimi")
+            if api_base and pid == "hive":
+                return check_anthropic_compatible(api_key, api_base.rstrip("/") + "/v1/messages", "Hive")
+            if api_base:
+                endpoint = api_base.rstrip("/") + "/models"
+                name = {"zai": "ZAI"}.get(pid, "Custom provider")
+                return check_openai_compatible(api_key, endpoint, name)
+            if pid in CHECK_PROVIDERS:
+                return CHECK_PROVIDERS[pid](api_key)
+            # No check available — assume valid
+            return {"valid": True, "message": f"No health check for {pid}"}
+        except Exception as exc:
+            return {"valid": None, "message": f"Validation error: {exc}"}
+
+    return await asyncio.get_event_loop().run_in_executor(None, _check)
+
+
 # ------------------------------------------------------------------
 # Handlers
 # ------------------------------------------------------------------
@@ -324,9 +374,9 @@ async def handle_get_llm_config(request: web.Request) -> web.Response:
         if _resolve_api_key(pid, request) is not None:
             connected.append(pid)
 
-    # Subscription detection
+    # Subscription detection — only include subscriptions whose tokens exist
     active_subscription = _get_active_subscription(llm)
-    detected_subscriptions = _detect_subscriptions()
+    detected_subscriptions = [sid for sid in _detect_subscriptions() if _get_subscription_token(sid)]
 
     return web.json_response(
         {
@@ -369,6 +419,21 @@ async def handle_update_llm_config(request: web.Request) -> web.Response:
         provider = sub["provider"]
         api_base = sub.get("api_base")
 
+        # Validate the subscription token before committing
+        token = _get_subscription_token(subscription_id)
+        if not token:
+            return web.json_response(
+                {"error": f"No credential found for {sub['name']}. Please check your subscription or API key."},
+                status=400,
+            )
+
+        check = await _validate_provider_key(provider, token, api_base=api_base)
+        if check.get("valid") is False:
+            return web.json_response(
+                {"error": f"{sub['name']} key validation failed: {check.get('message', 'unknown error')}"},
+                status=400,
+            )
+
         # Look up token limits from preset
         max_tokens: int | None = None
         max_context_tokens: int | None = None
@@ -399,8 +464,7 @@ async def handle_update_llm_config(request: web.Request) -> web.Response:
 
         _write_config_atomic(config)
 
-        # Hot-swap with subscription token
-        token = _get_subscription_token(subscription_id)
+        # Hot-swap with subscription token (already validated above)
         full_model = f"{provider}/{model}"
         swapped = _hot_swap_sessions(request, full_model, api_key=token, api_base=api_base)
 
@@ -430,15 +494,36 @@ async def handle_update_llm_config(request: web.Request) -> web.Response:
         if not provider or not model:
             return web.json_response({"error": "Both 'provider' and 'model' are required"}, status=400)
 
-        # Look up token limits from catalogue
+        # Verify model exists in the catalogue
         model_info = _find_model_info(provider, model)
-        max_tokens = model_info["max_tokens"] if model_info else 8192
-        max_context_tokens = model_info["max_context_tokens"] if model_info else 120000
+        if not model_info:
+            return web.json_response(
+                {"error": f"Model '{model}' is not available for provider '{provider}'."},
+                status=400,
+            )
+
+        max_tokens = model_info["max_tokens"]
+        max_context_tokens = model_info["max_context_tokens"]
 
         # Determine env var and api_base
         env_var = PROVIDER_ENV_VARS.get(provider.lower(), "")
         api_base = _get_api_base_for_provider(provider)
 
+        # Validate the API key before committing
+        api_key = _resolve_api_key(provider, request)
+        if not api_key:
+            return web.json_response(
+                {"error": f"No API key found for {provider}. Please add one in Manage Keys."},
+                status=400,
+            )
+
+        check = await _validate_provider_key(provider, api_key, api_base=api_base, model=model)
+        if check.get("valid") is False:
+            return web.json_response(
+                {"error": f"API key validation failed for {provider}: {check.get('message', 'unknown error')}"},
+                status=400,
+            )
+
         # Update ~/.hive/configuration.json
         config = get_hive_config()
         llm_section = config.setdefault("llm", {})
@@ -458,8 +543,7 @@ async def handle_update_llm_config(request: web.Request) -> web.Response:
 
         _write_config_atomic(config)
 
-        # Hot-swap all running sessions
-        api_key = _resolve_api_key(provider, request)
+        # Hot-swap all running sessions (api_key already validated above)
         full_model = f"{provider}/{model}"
         swapped = _hot_swap_sessions(request, full_model, api_key=api_key, api_base=api_base)
 
@@ -594,6 +678,64 @@ async def handle_get_models(request: web.Request) -> web.Response:
     return web.json_response({"models": MODELS_CATALOGUE})
 
 
+# ------------------------------------------------------------------
+# User avatar
+# ------------------------------------------------------------------
+
+MAX_AVATAR_BYTES = 2 * 1024 * 1024  # 2 MB
+_ALLOWED_AVATAR_TYPES = {
+    "image/jpeg": ".jpg",
+    "image/png": ".png",
+    "image/webp": ".webp",
+}
+
+
+async def handle_upload_user_avatar(request: web.Request) -> web.Response:
+    """POST /api/config/profile/avatar — upload user profile picture."""
+    reader = await request.multipart()
+    field = await reader.next()
+    if field is None or field.name != "avatar":
+        return web.json_response({"error": "Expected a file field named 'avatar'"}, status=400)
+
+    content_type = getattr(field, "content_type", None) or field.headers.get("Content-Type", "")
+    ext = _ALLOWED_AVATAR_TYPES.get(content_type)
+    if not ext:
+        return web.json_response(
+            {"error": f"Unsupported image type: {content_type}. Use JPEG, PNG, or WebP."},
+            status=400,
+        )
+
+    data = bytearray()
+    while True:
+        chunk = await field.read_chunk(8192)
+        if not chunk:
+            break
+        data.extend(chunk)
+        if len(data) > MAX_AVATAR_BYTES:
+            return web.json_response({"error": "Image too large. Maximum size is 2 MB."}, status=400)
+
+    if not data:
+        return web.json_response({"error": "Empty file"}, status=400)
+
+    # Remove existing avatar files
+    for existing in HIVE_CONFIG_FILE.parent.glob("avatar.*"):
+        existing.unlink(missing_ok=True)
+
+    avatar_path = HIVE_CONFIG_FILE.parent / f"avatar{ext}"
+    avatar_path.write_bytes(data)
+    logger.info("User avatar uploaded: %s (%d bytes)", avatar_path.name, len(data))
+    return web.json_response({"avatar_url": "/api/config/profile/avatar"})
+
+
+async def handle_get_user_avatar(request: web.Request) -> web.Response:
+    """GET /api/config/profile/avatar — serve user profile picture."""
+    for ext in _ALLOWED_AVATAR_TYPES.values():
+        avatar_path = HIVE_CONFIG_FILE.parent / f"avatar{ext}"
+        if avatar_path.exists():
+            return web.FileResponse(avatar_path, headers={"Cache-Control": "public, max-age=3600"})
+    return web.json_response({"error": "No avatar found"}, status=404)
+
+
 # ------------------------------------------------------------------
 # Route registration
 # ------------------------------------------------------------------
@@ -606,3 +748,5 @@ def register_routes(app: web.Application) -> None:
     app.router.add_get("/api/config/models", handle_get_models)
     app.router.add_get("/api/config/profile", handle_get_profile)
     app.router.add_put("/api/config/profile", handle_update_profile)
+    app.router.add_post("/api/config/profile/avatar", handle_upload_user_avatar)
+    app.router.add_get("/api/config/profile/avatar", handle_get_user_avatar)

core/framework/server/routes_credentials.py

@@ -7,7 +7,7 @@ import os
 from aiohttp import web
 from pydantic import SecretStr
 
-from framework.credentials.models import CredentialKey, CredentialObject
+from framework.credentials.models import CredentialDecryptionError, CredentialKey, CredentialObject
 from framework.credentials.store import CredentialStore
 from framework.server.app import validate_agent_path
 
@@ -84,23 +84,52 @@ def _credential_to_dict(cred: CredentialObject) -> dict:
     }
 
 
+def _is_available_for_specs(store: CredentialStore, credential_id: str) -> bool:
+    """Best-effort availability check for the repair UI.
+
+    The credential settings page must stay reachable even when an encrypted
+    file was written with the wrong key or is otherwise unreadable.
+    """
+    try:
+        return store.is_available(credential_id)
+    except CredentialDecryptionError as exc:
+        logger.warning("Credential '%s' is unreadable; marking unavailable in specs: %s", credential_id, exc)
+        return False
+
+
 async def handle_list_credentials(request: web.Request) -> web.Response:
     """GET /api/credentials — list all credential metadata (no secrets)."""
     store = _get_store(request)
     cred_ids = store.list_credentials()
     credentials = []
+    unreadable = []
     for cid in cred_ids:
-        cred = store.get_credential(cid, refresh_if_needed=False)
+        try:
+            cred = store.get_credential(cid, refresh_if_needed=False)
+        except CredentialDecryptionError as exc:
+            logger.warning("Credential '%s' is unreadable while listing credentials: %s", cid, exc)
+            unreadable.append(cid)
+            continue
         if cred:
             credentials.append(_credential_to_dict(cred))
-    return web.json_response({"credentials": credentials})
+    return web.json_response({"credentials": credentials, "unreadable_credentials": unreadable})
 
 
 async def handle_get_credential(request: web.Request) -> web.Response:
     """GET /api/credentials/{credential_id} — get single credential metadata."""
     credential_id = request.match_info["credential_id"]
     store = _get_store(request)
-    cred = store.get_credential(credential_id, refresh_if_needed=False)
+    try:
+        cred = store.get_credential(credential_id, refresh_if_needed=False)
+    except CredentialDecryptionError:
+        return web.json_response(
+            {
+                "error": f"Credential '{credential_id}' could not be decrypted",
+                "credential_id": credential_id,
+                "recoverable": True,
+            },
+            status=409,
+        )
     if cred is None:
         return web.json_response({"error": f"Credential '{credential_id}' not found"}, status=404)
     return web.json_response(_credential_to_dict(cred))
@@ -393,7 +422,7 @@ async def handle_list_specs(request: web.Request) -> web.Response:
             if spec.aden_supported and not spec.direct_api_key_supported:
                 available = len(accounts) > 0
             else:
-                available = store.is_available(cred_id)
+                available = _is_available_for_specs(store, cred_id)
             specs.append(
                 {
                     "credential_name": name,

core/framework/server/routes_events.py

@@ -119,6 +119,22 @@ async def handle_events(request: web.Request) -> web.StreamResponse:
     event_bus = session.event_bus
     event_types = _parse_event_types(request.query.get("types"))
 
+    # Worker-noise filter is phase-aware. In DM mode (queen phase
+    # "independent") the queen's chat should stay clean — workers
+    # are invisible. In colony mode (phase "working"/"reviewing")
+    # the user IS supervising the workers and wants to see the
+    # tool-call/text-delta chatter as it happens. Sample the phase
+    # once at SSE connect; if the queen later transitions the
+    # frontend reconnects.
+    def _should_filter_worker_noise() -> bool:
+        phase_state = getattr(session, "phase_state", None)
+        if phase_state is None:
+            return True  # unknown phase → be conservative, filter noise
+        phase = getattr(phase_state, "phase", "independent")
+        return phase == "independent"
+
+    filter_worker_noise = _should_filter_worker_noise()
+
     # Per-client buffer queue
     queue: asyncio.Queue = asyncio.Queue(maxsize=1000)
 
@@ -145,7 +161,7 @@ async def handle_events(request: web.Request) -> web.StreamResponse:
             return
 
         evt_dict = event.to_dict()
-        if _is_worker_noise(evt_dict):
+        if filter_worker_noise and _is_worker_noise(evt_dict):
             return
         if evt_dict.get("type") in _CRITICAL_EVENTS:
             try:
@@ -193,6 +209,7 @@ async def handle_events(request: web.Request) -> web.StreamResponse:
         EventType.TRIGGER_AVAILABLE.value,
         EventType.TRIGGER_ACTIVATED.value,
         EventType.TRIGGER_DEACTIVATED.value,
+        EventType.TRIGGER_FIRED.value,
         EventType.TRIGGER_REMOVED.value,
         EventType.TRIGGER_UPDATED.value,
     }
@@ -202,7 +219,7 @@ async def handle_events(request: web.Request) -> web.StreamResponse:
     for past_event in event_bus._event_history:
         if past_event.type.value in replay_types:
             past_dict = past_event.to_dict()
-            if _is_worker_noise(past_dict):
+            if filter_worker_noise and _is_worker_noise(past_dict):
                 continue
             try:
                 queue.put_nowait(past_dict)

core/framework/server/routes_mcp.py

@@ -0,0 +1,291 @@
+"""MCP server registration routes.
+
+Thin HTTP wrapper around ``MCPRegistry`` so the frontend can add, remove,
+enable, and health-check user-registered MCP servers. The CLI path
+(``hive mcp add`` / ``hive mcp remove`` / etc.) is unchanged.
+
+- GET    /api/mcp/servers                  -- list installed servers
+- POST   /api/mcp/servers                  -- register a local server
+- DELETE /api/mcp/servers/{name}           -- remove a local server
+- POST   /api/mcp/servers/{name}/enable    -- enable a server
+- POST   /api/mcp/servers/{name}/disable   -- disable a server
+- POST   /api/mcp/servers/{name}/health    -- probe server health
+
+New servers take effect on the *next* queen session start. Existing live
+queen sessions keep the tool list they booted with to avoid mid-turn
+cache invalidation. The ``add`` response hints at this explicitly.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from aiohttp import web
+
+from framework.loader.mcp_errors import MCPError
+from framework.loader.mcp_registry import MCPRegistry
+
+logger = logging.getLogger(__name__)
+
+
+_VALID_TRANSPORTS = {"stdio", "http", "sse", "unix"}
+
+
+def _registry() -> MCPRegistry:
+    # MCPRegistry is a thin wrapper around ~/.hive/mcp_registry/installed.json
+    # so instantiation is cheap — no need to cache on app["..."].
+    reg = MCPRegistry()
+    reg.initialize()
+    return reg
+
+
+def _package_builtin_servers() -> list[dict[str, Any]]:
+    """Return the package-baked queen MCP servers from ``queen/mcp_servers.json``.
+
+    Those servers are loaded directly by ``ToolRegistry.load_mcp_config``
+    at queen boot and never go through ``MCPRegistry.list_installed``,
+    so the raw registry view shows them as missing. Surface them here so
+    the Tool Library reflects what the queen actually talks to.
+
+    Entries carry ``source: "built-in"`` and are NOT removable / toggleable
+    — editing them requires changing the repo file.
+    """
+    import json
+    from pathlib import Path
+
+    import framework.agents.queen as _queen_pkg
+
+    path = Path(_queen_pkg.__file__).parent / "mcp_servers.json"
+    if not path.exists():
+        return []
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return []
+
+    out: list[dict[str, Any]] = []
+    for name, cfg in data.items():
+        if not isinstance(cfg, dict):
+            continue
+        out.append(
+            {
+                "name": name,
+                "source": "built-in",
+                "transport": cfg.get("transport", "stdio"),
+                "description": cfg.get("description", "") or "",
+                "enabled": True,
+                "last_health_status": None,
+                "last_error": None,
+                "last_health_check_at": None,
+                "tool_count": None,
+                "removable": False,
+            }
+        )
+    return out
+
+
+def _server_to_summary(entry: dict[str, Any]) -> dict[str, Any]:
+    """Shape an installed.json entry for API responses.
+
+    Strips the full manifest body (which can be large) but keeps the tool
+    list if the manifest already embeds one (happens for registry-installed
+    servers). Users with ``source: "local"`` only get a tool list after
+    running a health check.
+    """
+    manifest = entry.get("manifest") or {}
+    tools = manifest.get("tools") if isinstance(manifest, dict) else None
+    if not isinstance(tools, list):
+        tools = None
+    return {
+        "name": entry.get("name"),
+        "source": entry.get("source"),
+        "transport": entry.get("transport"),
+        "description": (manifest.get("description") if isinstance(manifest, dict) else None) or "",
+        "enabled": entry.get("enabled", True),
+        "last_health_status": entry.get("last_health_status"),
+        "last_error": entry.get("last_error"),
+        "last_health_check_at": entry.get("last_health_check_at"),
+        "tool_count": (len(tools) if tools is not None else None),
+    }
+
+
+def _mcp_error_response(exc: MCPError, *, default_status: int = 400) -> web.Response:
+    return web.json_response(
+        {
+            "error": exc.what,
+            "code": exc.code.value,
+            "what": exc.what,
+            "why": exc.why,
+            "fix": exc.fix,
+        },
+        status=default_status,
+    )
+
+
+async def handle_list_servers(request: web.Request) -> web.Response:
+    """GET /api/mcp/servers — list every server the queen actually uses.
+
+    Merges two sources:
+
+    - ``MCPRegistry.list_installed()`` — servers registered via
+      ``hive mcp add`` / the ``/api/mcp/servers`` POST route, stored in
+      ``~/.hive/mcp_registry/installed.json``. These carry
+      ``source: "local"`` (user-added) or ``source: "registry"``
+      (installed from the remote registry).
+    - Repo-baked queen servers from
+      ``core/framework/agents/queen/mcp_servers.json``. These are loaded
+      directly by the queen's ``ToolRegistry`` at boot and never touch
+      ``MCPRegistry``; we surface them here so the UI reflects what the
+      queen really talks to. They are not removable from the UI because
+      editing them requires changing the repo.
+
+    If a name collides between the two sources, the registry entry wins
+    because that's the one the user has customized.
+    """
+    reg = _registry()
+    registry_entries = [_server_to_summary(e) for e in reg.list_installed()]
+    seen_names = {e.get("name") for e in registry_entries}
+
+    package_entries = [e for e in _package_builtin_servers() if e.get("name") not in seen_names]
+
+    servers = [*package_entries, *registry_entries]
+    return web.json_response({"servers": servers})
+
+
+async def handle_add_server(request: web.Request) -> web.Response:
+    """POST /api/mcp/servers — register a local MCP server.
+
+    Body mirrors ``MCPRegistry.add_local`` args:
+
+    ::
+
+        {
+          "name": "my-tool",
+          "transport": "stdio" | "http" | "sse" | "unix",
+          "command": "...", "args": [...], "env": {...}, "cwd": "...",
+          "url": "...", "headers": {...},
+          "socket_path": "...",
+          "description": "..."
+        }
+    """
+    try:
+        body = await request.json()
+    except Exception:
+        return web.json_response({"error": "Invalid JSON body"}, status=400)
+    if not isinstance(body, dict):
+        return web.json_response({"error": "Body must be a JSON object"}, status=400)
+
+    name = body.get("name")
+    transport = body.get("transport")
+    if not isinstance(name, str) or not name.strip():
+        return web.json_response({"error": "'name' is required"}, status=400)
+    if transport not in _VALID_TRANSPORTS:
+        return web.json_response(
+            {"error": f"'transport' must be one of {sorted(_VALID_TRANSPORTS)}"},
+            status=400,
+        )
+
+    reg = _registry()
+    try:
+        entry = reg.add_local(
+            name=name.strip(),
+            transport=transport,
+            command=body.get("command"),
+            args=body.get("args"),
+            env=body.get("env"),
+            cwd=body.get("cwd"),
+            url=body.get("url"),
+            headers=body.get("headers"),
+            socket_path=body.get("socket_path"),
+            description=body.get("description", ""),
+        )
+    except MCPError as exc:
+        status = 409 if "already exists" in exc.what else 400
+        return _mcp_error_response(exc, default_status=status)
+    except Exception as exc:
+        logger.exception("MCP add_local failed for %r", name)
+        return web.json_response({"error": str(exc)}, status=500)
+
+    summary = _server_to_summary({"name": name, **entry})
+    return web.json_response(
+        {
+            "server": summary,
+            "hint": "Start a new queen session to use this server's tools.",
+        },
+        status=201,
+    )
+
+
+async def handle_remove_server(request: web.Request) -> web.Response:
+    """DELETE /api/mcp/servers/{name} — remove a local server."""
+    name = request.match_info["name"]
+    reg = _registry()
+
+    existing = reg.get_server(name)
+    if existing is None:
+        return web.json_response({"error": f"Server '{name}' not installed"}, status=404)
+    if existing.get("source") != "local":
+        return web.json_response(
+            {
+                "error": f"Server '{name}' is a built-in; it cannot be removed from the UI.",
+            },
+            status=400,
+        )
+
+    try:
+        reg.remove(name)
+    except MCPError as exc:
+        return _mcp_error_response(exc, default_status=404)
+    return web.json_response({"removed": name})
+
+
+async def handle_set_enabled(request: web.Request, *, enabled: bool) -> web.Response:
+    name = request.match_info["name"]
+    reg = _registry()
+    try:
+        if enabled:
+            reg.enable(name)
+        else:
+            reg.disable(name)
+    except MCPError as exc:
+        return _mcp_error_response(exc, default_status=404)
+    return web.json_response({"name": name, "enabled": enabled})
+
+
+async def handle_enable(request: web.Request) -> web.Response:
+    """POST /api/mcp/servers/{name}/enable."""
+    return await handle_set_enabled(request, enabled=True)
+
+
+async def handle_disable(request: web.Request) -> web.Response:
+    """POST /api/mcp/servers/{name}/disable."""
+    return await handle_set_enabled(request, enabled=False)
+
+
+async def handle_health(request: web.Request) -> web.Response:
+    """POST /api/mcp/servers/{name}/health — probe one server."""
+    name = request.match_info["name"]
+    reg = _registry()
+    try:
+        # MCPRegistry.health_check blocks on subprocess IO — run it off
+        # the event loop so the HTTP worker stays responsive.
+        import asyncio
+
+        result = await asyncio.to_thread(reg.health_check, name)
+    except MCPError as exc:
+        return _mcp_error_response(exc, default_status=404)
+    except Exception as exc:
+        logger.exception("MCP health_check failed for %r", name)
+        return web.json_response({"error": str(exc)}, status=500)
+    return web.json_response(result)
+
+
+def register_routes(app: web.Application) -> None:
+    """Register MCP server CRUD routes."""
+    app.router.add_get("/api/mcp/servers", handle_list_servers)
+    app.router.add_post("/api/mcp/servers", handle_add_server)
+    app.router.add_delete("/api/mcp/servers/{name}", handle_remove_server)
+    app.router.add_post("/api/mcp/servers/{name}/enable", handle_enable)
+    app.router.add_post("/api/mcp/servers/{name}/disable", handle_disable)
+    app.router.add_post("/api/mcp/servers/{name}/health", handle_health)

core/framework/server/routes_prompts.py

@@ -0,0 +1,87 @@
+"""Custom user prompts — CRUD for user-uploaded prompts.
+
+- GET    /api/prompts        — list all custom prompts
+- POST   /api/prompts        — add a new custom prompt
+- DELETE /api/prompts/{id}   — delete a custom prompt
+"""
+
+import json
+import logging
+import time
+
+from aiohttp import web
+
+from framework.config import HIVE_HOME
+
+logger = logging.getLogger(__name__)
+
+CUSTOM_PROMPTS_FILE = HIVE_HOME / "custom_prompts.json"
+
+
+def _load_custom_prompts() -> list[dict]:
+    if not CUSTOM_PROMPTS_FILE.exists():
+        return []
+    try:
+        data = json.loads(CUSTOM_PROMPTS_FILE.read_text(encoding="utf-8"))
+        return data if isinstance(data, list) else []
+    except Exception:
+        return []
+
+
+def _save_custom_prompts(prompts: list[dict]) -> None:
+    CUSTOM_PROMPTS_FILE.parent.mkdir(parents=True, exist_ok=True)
+    CUSTOM_PROMPTS_FILE.write_text(
+        json.dumps(prompts, indent=2, ensure_ascii=False) + "\n",
+        encoding="utf-8",
+    )
+
+
+async def handle_list_prompts(request: web.Request) -> web.Response:
+    """GET /api/prompts — list all custom prompts."""
+    return web.json_response({"prompts": _load_custom_prompts()})
+
+
+async def handle_create_prompt(request: web.Request) -> web.Response:
+    """POST /api/prompts — add a new custom prompt."""
+    try:
+        body = await request.json()
+    except Exception:
+        return web.json_response({"error": "Invalid JSON body"}, status=400)
+
+    title = (body.get("title") or "").strip()
+    category = (body.get("category") or "").strip()
+    content = (body.get("content") or "").strip()
+
+    if not title or not content:
+        return web.json_response({"error": "Title and content are required"}, status=400)
+
+    prompts = _load_custom_prompts()
+    new_prompt = {
+        "id": f"custom_{int(time.time() * 1000)}",
+        "title": title,
+        "category": category or "custom",
+        "content": content,
+        "custom": True,
+    }
+    prompts.append(new_prompt)
+    _save_custom_prompts(prompts)
+    logger.info("Custom prompt added: %s", title)
+    return web.json_response(new_prompt, status=201)
+
+
+async def handle_delete_prompt(request: web.Request) -> web.Response:
+    """DELETE /api/prompts/{prompt_id} — delete a custom prompt."""
+    prompt_id = request.match_info["prompt_id"]
+    prompts = _load_custom_prompts()
+    before = len(prompts)
+    prompts = [p for p in prompts if p.get("id") != prompt_id]
+    if len(prompts) == before:
+        return web.json_response({"error": "Prompt not found"}, status=404)
+    _save_custom_prompts(prompts)
+    return web.json_response({"deleted": prompt_id})
+
+
+def register_routes(app: web.Application) -> None:
+    app.router.add_get("/api/prompts", handle_list_prompts)
+    app.router.add_post("/api/prompts", handle_create_prompt)
+    app.router.add_delete("/api/prompts/{prompt_id}", handle_delete_prompt)

core/framework/server/routes_queen_tools.py

@@ -0,0 +1,537 @@
+"""Per-queen MCP tool allowlist routes.
+
+- GET   /api/queen/{queen_id}/tools  -- enumerate the queen's tool surface
+- PATCH /api/queen/{queen_id}/tools  -- set or clear the MCP tool allowlist
+
+Lifecycle and synthetic tools (``ask_user``) are always part of the queen's
+surface in INDEPENDENT mode and are returned with ``editable: false``. MCP
+tools are grouped by origin server and carry per-tool ``enabled`` flags.
+
+The allowlist is persisted in a dedicated ``tools.json`` sidecar at
+``~/.hive/agents/queens/{queen_id}/tools.json``:
+
+- ``null`` / missing file -> "allow every MCP tool" (default)
+- ``[]``                  -> explicitly disable every MCP tool
+- ``["foo", "bar"]``      -> only these MCP tools pass through to the LLM
+
+Filtering happens in ``QueenPhaseState.rebuild_independent_filter`` so the
+LLM prompt cache stays warm between saves.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from aiohttp import web
+
+from framework.agents.queen.queen_profiles import (
+    ensure_default_queens,
+    load_queen_profile,
+)
+from framework.agents.queen.queen_tools_config import (
+    delete_queen_tools_config,
+    load_queen_tools_config,
+    tools_config_exists,
+    update_queen_tools_config,
+)
+from framework.agents.queen.queen_tools_defaults import (
+    list_category_names,
+    queen_role_categories,
+    resolve_category_tools,
+)
+
+logger = logging.getLogger(__name__)
+
+
+_SYNTHETIC_NAMES = {"ask_user"}
+
+
+async def _ensure_manager_catalog(manager: Any) -> dict[str, list[dict[str, Any]]]:
+    """Return the cached MCP tool catalog, building it on first call.
+
+    ``queen_orchestrator.create_queen`` populates ``_mcp_tool_catalog`` on
+    every queen boot. On a fresh backend process the user may open the
+    Tool Library before any queen session has started, so the catalog is
+    empty. In that case we build one from the shared MCP config; the
+    first call pays an MCP-subprocess-spawn cost, subsequent calls are
+    cache hits. The build runs off the event loop via asyncio.to_thread
+    so the HTTP worker stays responsive while MCP servers initialize.
+    """
+    if manager is None:
+        return {}
+    catalog = getattr(manager, "_mcp_tool_catalog", None)
+    if isinstance(catalog, dict) and catalog:
+        return catalog
+    try:
+        import asyncio
+
+        from framework.server.queen_orchestrator import build_queen_tool_registry_bare
+
+        registry, built = await asyncio.to_thread(build_queen_tool_registry_bare)
+        manager._mcp_tool_catalog = built  # type: ignore[attr-defined]
+        manager._bootstrap_tool_registry = registry  # type: ignore[attr-defined]
+        return built
+    except Exception:
+        logger.warning("Tool catalog bootstrap failed", exc_info=True)
+        return {}
+
+
+def _lifecycle_entries_without_session(
+    manager: Any,
+    mcp_names: set[str],
+) -> list[dict[str, Any]]:
+    """Derive lifecycle tool names from the registry even without a session.
+
+    We register queen lifecycle tools against a temporary registry using a
+    minimal stub, then subtract the MCP-origin set and the synthetic set.
+    The result matches what the queen sees at runtime (minus context-
+    specific variants).
+    """
+    registry = getattr(manager, "_bootstrap_tool_registry", None)
+    # If the bootstrap registry exists but doesn't carry lifecycle tools
+    # yet, register them now.
+    if registry is not None and not getattr(registry, "_lifecycle_bootstrap_done", False):
+        try:
+            from types import SimpleNamespace
+
+            from framework.tools.queen_lifecycle_tools import register_queen_lifecycle_tools
+
+            stub_session = SimpleNamespace(
+                id="tool-library-bootstrap",
+                colony_runtime=None,
+                event_bus=None,
+                worker_path=None,
+                phase_state=None,
+                llm=None,
+            )
+            register_queen_lifecycle_tools(
+                registry,
+                session=stub_session,
+                session_id=stub_session.id,
+                session_manager=None,
+                manager_session_id=stub_session.id,
+                phase_state=None,
+            )
+            registry._lifecycle_bootstrap_done = True  # type: ignore[attr-defined]
+        except Exception:
+            logger.debug("lifecycle bootstrap failed", exc_info=True)
+
+    if registry is None:
+        return []
+
+    out: list[dict[str, Any]] = []
+    for name, tool in sorted(registry.get_tools().items()):
+        if name in mcp_names or name in _SYNTHETIC_NAMES:
+            continue
+        out.append(
+            {
+                "name": tool.name,
+                "description": tool.description,
+                "editable": False,
+            }
+        )
+    return out
+
+
+def _synthetic_entries() -> list[dict[str, Any]]:
+    """Return display metadata for synthetic tools injected by the agent loop.
+
+    Kept behind a lazy import so test harnesses that don't wire the agent
+    loop can still hit this route without blowing up.
+    """
+    try:
+        from framework.agent_loop.internals.synthetic_tools import build_ask_user_tool
+
+        tool = build_ask_user_tool()
+        return [
+            {
+                "name": tool.name,
+                "description": tool.description,
+                "editable": False,
+            }
+        ]
+    except Exception:
+        return [
+            {
+                "name": "ask_user",
+                "description": "Pause and ask the user a structured question.",
+                "editable": False,
+            }
+        ]
+
+
+def _live_queen_session(manager: Any, queen_id: str) -> Any:
+    """Return any live DM session owned by this queen, or ``None``."""
+    sessions = getattr(manager, "_sessions", None) or {}
+    for session in sessions.values():
+        if getattr(session, "queen_name", None) != queen_id:
+            continue
+        # Prefer DM (non-colony) sessions
+        if getattr(session, "colony_runtime", None) is None:
+            return session
+    return None
+
+
+def _render_mcp_servers(
+    *,
+    mcp_tool_names_by_server: dict[str, list[dict[str, Any]]],
+    enabled_mcp_tools: list[str] | None,
+) -> list[dict[str, Any]]:
+    """Shape the mcp_tool_catalog entries for the API response."""
+    allowed: set[str] | None = None if enabled_mcp_tools is None else set(enabled_mcp_tools)
+    servers: list[dict[str, Any]] = []
+    for server_name in sorted(mcp_tool_names_by_server):
+        entries = mcp_tool_names_by_server[server_name]
+        tools = []
+        for entry in entries:
+            name = entry.get("name")
+            enabled = True if allowed is None else name in allowed
+            tools.append(
+                {
+                    "name": name,
+                    "description": entry.get("description", ""),
+                    "input_schema": entry.get("input_schema", {}),
+                    "enabled": enabled,
+                }
+            )
+        servers.append({"name": server_name, "tools": tools})
+    return servers
+
+
+def _catalog_from_live_session(session: Any) -> dict[str, list[dict[str, Any]]]:
+    """Rebuild a per-server tool catalog from a live queen session.
+
+    The session's registry is authoritative — this reflects any hot-added
+    MCP servers since the manager-level snapshot was cached.
+    """
+    registry = getattr(session, "_queen_tool_registry", None)
+    if registry is None:
+        # session._queen_tools_by_name is a stash from create_queen; we
+        # only have registry via the tools list, so reconstruct from the
+        # phase state instead.
+        phase_state = getattr(session, "phase_state", None)
+        if phase_state is None:
+            return {}
+        mcp_names = getattr(phase_state, "mcp_tool_names_all", set()) or set()
+        independent_tools = getattr(phase_state, "independent_tools", []) or []
+        result: dict[str, list[dict[str, Any]]] = {"MCP Tools": []}
+        for tool in independent_tools:
+            if tool.name not in mcp_names:
+                continue
+            result["MCP Tools"].append(
+                {
+                    "name": tool.name,
+                    "description": tool.description,
+                    "input_schema": tool.parameters,
+                }
+            )
+        return result if result["MCP Tools"] else {}
+
+    server_map = getattr(registry, "_mcp_server_tools", {}) or {}
+    tools_by_name = {t.name: t for t in registry.get_tools().values()}
+    catalog: dict[str, list[dict[str, Any]]] = {}
+    for server_name, tool_names in server_map.items():
+        entries: list[dict[str, Any]] = []
+        for name in sorted(tool_names):
+            tool = tools_by_name.get(name)
+            if tool is None:
+                continue
+            entries.append(
+                {
+                    "name": tool.name,
+                    "description": tool.description,
+                    "input_schema": tool.parameters,
+                }
+            )
+        catalog[server_name] = entries
+    return catalog
+
+
+def _lifecycle_entries(
+    *,
+    session: Any,
+    mcp_tool_names_all: set[str],
+) -> list[dict[str, Any]]:
+    """Lifecycle tools = independent_tools minus MCP-origin minus synthetic.
+
+    We compute this from a live session when available so the list exactly
+    matches what the queen actually sees on her next turn.
+    """
+    if session is None:
+        return []
+    phase_state = getattr(session, "phase_state", None)
+    if phase_state is None:
+        return []
+    result: list[dict[str, Any]] = []
+    for tool in getattr(phase_state, "independent_tools", []) or []:
+        if tool.name in mcp_tool_names_all:
+            continue
+        if tool.name in _SYNTHETIC_NAMES:
+            continue
+        result.append(
+            {
+                "name": tool.name,
+                "description": tool.description,
+                "editable": False,
+            }
+        )
+    return sorted(result, key=lambda x: x["name"])
+
+
+async def handle_get_tools(request: web.Request) -> web.Response:
+    """GET /api/queen/{queen_id}/tools — enumerate tool surface for the UI."""
+    queen_id = request.match_info["queen_id"]
+    ensure_default_queens()
+    try:
+        load_queen_profile(queen_id)
+    except FileNotFoundError:
+        return web.json_response({"error": f"Queen '{queen_id}' not found"}, status=404)
+
+    manager = request.app.get("manager")
+    session = _live_queen_session(manager, queen_id) if manager is not None else None
+
+    # Prefer a live session's registry for freshness. Otherwise use (or
+    # build on demand) the manager-level catalog so the Tool Library works
+    # even before any queen has been started in this process.
+    if session is not None:
+        catalog = _catalog_from_live_session(session)
+    else:
+        catalog = await _ensure_manager_catalog(manager)
+    stale = not catalog
+
+    mcp_tool_names_all: set[str] = set()
+    for entries in catalog.values():
+        for entry in entries:
+            if entry.get("name"):
+                mcp_tool_names_all.add(entry["name"])
+
+    if session is not None:
+        lifecycle = _lifecycle_entries(
+            session=session,
+            mcp_tool_names_all=mcp_tool_names_all,
+        )
+    else:
+        lifecycle = _lifecycle_entries_without_session(manager, mcp_tool_names_all)
+
+    # Allowlist lives in the dedicated tools.json sidecar; helper
+    # migrates legacy profile.yaml field on first read, and falls back
+    # to the role-based default when no sidecar exists.
+    enabled_mcp_tools = load_queen_tools_config(queen_id, mcp_catalog=catalog)
+    is_role_default = not tools_config_exists(queen_id)
+
+    response = {
+        "queen_id": queen_id,
+        "enabled_mcp_tools": enabled_mcp_tools,
+        "is_role_default": is_role_default,
+        "stale": stale,
+        "lifecycle": lifecycle,
+        "synthetic": _synthetic_entries(),
+        "mcp_servers": _render_mcp_servers(
+            mcp_tool_names_by_server=catalog,
+            enabled_mcp_tools=enabled_mcp_tools,
+        ),
+        "categories": _render_categories(queen_id, catalog),
+    }
+    return web.json_response(response)
+
+
+def _render_categories(
+    queen_id: str,
+    mcp_catalog: dict[str, list[dict[str, Any]]],
+) -> list[dict[str, Any]]:
+    """Expose the role-default category table to the frontend.
+
+    Each entry carries the category name, the resolved member tool names
+    (after ``@server:NAME`` shorthand expansion against the live catalog),
+    and ``in_role_default`` to flag categories that contribute to this
+    queen's role-based default. Lets the Tool Library group tools by
+    category alongside the per-server view.
+    """
+    applied = set(queen_role_categories(queen_id))
+    out: list[dict[str, Any]] = []
+    for name in list_category_names():
+        out.append(
+            {
+                "name": name,
+                "tools": resolve_category_tools(name, mcp_catalog),
+                "in_role_default": name in applied,
+            }
+        )
+    return out
+
+
+async def handle_patch_tools(request: web.Request) -> web.Response:
+    """PATCH /api/queen/{queen_id}/tools — persist the MCP tool allowlist.
+
+    Body: ``{"enabled_mcp_tools": null | string[]}``.
+
+    - ``null`` resets to "allow every MCP tool" (default).
+    - A list is validated against the known MCP catalog; unknown names
+      are rejected with 400 so the frontend catches typos.
+    """
+    queen_id = request.match_info["queen_id"]
+    try:
+        body = await request.json()
+    except Exception:
+        return web.json_response({"error": "Invalid JSON body"}, status=400)
+    if not isinstance(body, dict) or "enabled_mcp_tools" not in body:
+        return web.json_response(
+            {"error": "Body must be an object with an 'enabled_mcp_tools' field"},
+            status=400,
+        )
+
+    enabled = body["enabled_mcp_tools"]
+    if enabled is not None:
+        if not isinstance(enabled, list) or not all(isinstance(x, str) for x in enabled):
+            return web.json_response(
+                {"error": "'enabled_mcp_tools' must be null or a list of strings"},
+                status=400,
+            )
+
+    ensure_default_queens()
+    try:
+        load_queen_profile(queen_id)
+    except FileNotFoundError:
+        return web.json_response({"error": f"Queen '{queen_id}' not found"}, status=404)
+
+    # Validate names against the known MCP tool catalog. We prefer a live
+    # session's registry for the most up-to-date set, then fall back to
+    # the manager-level snapshot (building it on demand if absent).
+    manager = request.app.get("manager")
+    session = _live_queen_session(manager, queen_id) if manager is not None else None
+    if session is not None:
+        catalog = _catalog_from_live_session(session)
+    else:
+        catalog = await _ensure_manager_catalog(manager)
+    known_names: set[str] = set()
+    for entries in catalog.values():
+        for entry in entries:
+            if entry.get("name"):
+                known_names.add(entry["name"])
+
+    if enabled is not None and known_names:
+        unknown = sorted(set(enabled) - known_names)
+        if unknown:
+            return web.json_response(
+                {"error": "Unknown MCP tool name(s)", "unknown": unknown},
+                status=400,
+            )
+
+    # Persist — tools.json sidecar, not profile.yaml.
+    try:
+        update_queen_tools_config(queen_id, enabled)
+    except FileNotFoundError:
+        return web.json_response({"error": f"Queen '{queen_id}' not found"}, status=404)
+
+    # Hot-reload every live DM session for this queen. The filter memo is
+    # rebuilt so the very next turn sees the new allowlist without a
+    # session restart, and the prompt cache is invalidated exactly once.
+    refreshed = 0
+    sessions = getattr(manager, "_sessions", None) or {}
+    for sess in sessions.values():
+        if getattr(sess, "queen_name", None) != queen_id:
+            continue
+        phase_state = getattr(sess, "phase_state", None)
+        if phase_state is None:
+            continue
+        phase_state.enabled_mcp_tools = enabled
+        rebuild = getattr(phase_state, "rebuild_independent_filter", None)
+        if callable(rebuild):
+            try:
+                rebuild()
+                refreshed += 1
+            except Exception:
+                logger.debug(
+                    "Queen tools: rebuild_independent_filter failed for session %s",
+                    getattr(sess, "id", "?"),
+                    exc_info=True,
+                )
+
+    logger.info(
+        "Queen tools: queen_id=%s allowlist=%s refreshed_sessions=%d",
+        queen_id,
+        "null" if enabled is None else f"{len(enabled)} tool(s)",
+        refreshed,
+    )
+    return web.json_response(
+        {
+            "queen_id": queen_id,
+            "enabled_mcp_tools": enabled,
+            "refreshed_sessions": refreshed,
+        }
+    )
+
+
+async def handle_delete_tools(request: web.Request) -> web.Response:
+    """DELETE /api/queen/{queen_id}/tools — drop the sidecar, fall back to role defaults.
+
+    Users click "Reset to role default" in the Tool Library. That
+    removes ``tools.json`` so the queen's effective allowlist becomes
+    the role-based default (or allow-all if the queen has no role
+    entry). Live sessions are refreshed so the next turn reflects the
+    change without a restart.
+    """
+    queen_id = request.match_info["queen_id"]
+    ensure_default_queens()
+    try:
+        load_queen_profile(queen_id)
+    except FileNotFoundError:
+        return web.json_response({"error": f"Queen '{queen_id}' not found"}, status=404)
+
+    removed = delete_queen_tools_config(queen_id)
+
+    # Recompute the queen's effective allowlist from the role defaults
+    # so we can hot-reload live sessions in one pass (same shape as
+    # PATCH).
+    manager = request.app.get("manager")
+    session = _live_queen_session(manager, queen_id) if manager is not None else None
+    if session is not None:
+        catalog = _catalog_from_live_session(session)
+    else:
+        catalog = await _ensure_manager_catalog(manager)
+    new_enabled = load_queen_tools_config(queen_id, mcp_catalog=catalog)
+
+    refreshed = 0
+    sessions = getattr(manager, "_sessions", None) or {}
+    for sess in sessions.values():
+        if getattr(sess, "queen_name", None) != queen_id:
+            continue
+        phase_state = getattr(sess, "phase_state", None)
+        if phase_state is None:
+            continue
+        phase_state.enabled_mcp_tools = new_enabled
+        rebuild = getattr(phase_state, "rebuild_independent_filter", None)
+        if callable(rebuild):
+            try:
+                rebuild()
+                refreshed += 1
+            except Exception:
+                logger.debug(
+                    "Queen tools: rebuild_independent_filter failed for session %s",
+                    getattr(sess, "id", "?"),
+                    exc_info=True,
+                )
+
+    logger.info(
+        "Queen tools: queen_id=%s reset-to-default removed=%s refreshed_sessions=%d",
+        queen_id,
+        removed,
+        refreshed,
+    )
+    return web.json_response(
+        {
+            "queen_id": queen_id,
+            "removed": removed,
+            "enabled_mcp_tools": new_enabled,
+            "is_role_default": True,
+            "refreshed_sessions": refreshed,
+        }
+    )
+
+
+def register_routes(app: web.Application) -> None:
+    """Register queen-tools routes."""
+    app.router.add_get("/api/queen/{queen_id}/tools", handle_get_tools)
+    app.router.add_patch("/api/queen/{queen_id}/tools", handle_patch_tools)
+    app.router.add_delete("/api/queen/{queen_id}/tools", handle_delete_tools)

core/framework/server/routes_queens.py

@@ -3,6 +3,8 @@
 - GET    /api/queen/profiles                -- list all queen profiles (id, name, title)
 - GET    /api/queen/{queen_id}/profile      -- get full queen profile
 - PATCH  /api/queen/{queen_id}/profile      -- update queen profile fields
+- POST   /api/queen/{queen_id}/avatar       -- upload queen avatar image
+- GET    /api/queen/{queen_id}/avatar       -- serve queen avatar image
 - POST   /api/queen/{queen_id}/session      -- get or create a persistent session for a queen
 - POST   /api/queen/{queen_id}/session/select -- resume a specific session for a queen
 - POST   /api/queen/{queen_id}/session/new  -- create a fresh session for a queen
@@ -25,17 +27,6 @@ from framework.config import QUEENS_DIR
 logger = logging.getLogger(__name__)
 
 
-async def _stop_live_sessions(manager, keep_session_id: str | None = None) -> None:
-    """Stop live sessions so only the selected queen session remains active."""
-    for session in list(manager.list_sessions()):
-        if keep_session_id and session.id == keep_session_id:
-            continue
-        try:
-            await manager.stop_session(session.id)
-        except Exception:
-            logger.debug("Failed to stop session %s during queen switch", session.id)
-
-
 def _read_queen_session_meta(queen_id: str, session_id: str) -> dict[str, Any]:
     """Return persisted metadata for a queen session when available."""
     session_dir = QUEENS_DIR / queen_id / "sessions" / session_id
@@ -177,6 +168,34 @@ async def handle_get_profile(request: web.Request) -> web.Response:
     return web.json_response({"id": queen_id, **api_profile})
 
 
+def _reverse_transform_for_yaml(body: dict) -> dict:
+    """Map API-format fields back to YAML profile fields.
+
+    The API exposes a simplified view (summary, skills, signature_achievement)
+    that maps onto the underlying YAML structure (core_traits, hidden_background,
+    psychological_profile, world_lore, etc.).
+    """
+    yaml_updates: dict[str, Any] = {}
+
+    if "name" in body:
+        yaml_updates["name"] = body["name"]
+    if "title" in body:
+        yaml_updates["title"] = body["title"]
+
+    if "summary" in body:
+        # Summary is displayed as core_traits + anti_stereotype joined by \n\n.
+        # Store the full text in core_traits for simplicity.
+        yaml_updates["core_traits"] = body["summary"]
+
+    if "skills" in body:
+        yaml_updates["skills"] = body["skills"]
+
+    if "signature_achievement" in body:
+        yaml_updates.setdefault("world_lore", {})["habitat"] = body["signature_achievement"]
+
+    return yaml_updates
+
+
 async def handle_update_profile(request: web.Request) -> web.Response:
     """PATCH /api/queen/{queen_id}/profile — update queen profile fields."""
     queen_id = request.match_info["queen_id"]
@@ -186,11 +205,18 @@ async def handle_update_profile(request: web.Request) -> web.Response:
         return web.json_response({"error": "Invalid JSON body"}, status=400)
     if not isinstance(body, dict):
         return web.json_response({"error": "Body must be a JSON object"}, status=400)
+
+    yaml_updates = _reverse_transform_for_yaml(body)
+    if not yaml_updates:
+        return web.json_response({"error": "No valid fields to update"}, status=400)
+
     try:
-        updated = update_queen_profile(queen_id, body)
+        updated = update_queen_profile(queen_id, yaml_updates)
     except FileNotFoundError:
         return web.json_response({"error": f"Queen '{queen_id}' not found"}, status=404)
-    return web.json_response({"id": queen_id, **updated})
+
+    api_profile = _transform_profile_for_api(updated)
+    return web.json_response({"id": queen_id, **api_profile})
 
 
 async def handle_queen_session(request: web.Request) -> web.Response:
@@ -218,20 +244,26 @@ async def handle_queen_session(request: web.Request) -> web.Response:
     initial_prompt = body.get("initial_prompt")
     initial_phase = body.get("initial_phase")
 
-    # 1. Check for an existing live session bound to this queen.
-    for session in manager.list_sessions():
-        if session.queen_name == queen_id:
-            return web.json_response(
-                {
-                    "session_id": session.id,
-                    "queen_id": queen_id,
-                    "status": "live",
-                }
-            )
-
-    # Stop any live sessions bound to a different queen so only one queen
-    # is active at a time.
-    await _stop_live_sessions(manager)
+    # 1. Check for an existing live DM session bound to this queen.
+    # Skip colony sessions: a colony forked from this queen also carries
+    # queen_name == queen_id, but it has a worker loaded (colony_id /
+    # worker_path set) and is the colony's chat, not the queen's DM.
+    # When multiple DM sessions for this queen are live at once (e.g. the
+    # user created a new session, then navigated away and back), return
+    # the most recently loaded one so we don't resurrect a stale older
+    # session ahead of a freshly created one.
+    live_matches = [
+        s for s in manager.list_sessions() if s.queen_name == queen_id and s.colony_id is None and s.worker_path is None
+    ]
+    if live_matches:
+        latest = max(live_matches, key=lambda s: s.loaded_at)
+        return web.json_response(
+            {
+                "session_id": latest.id,
+                "queen_id": queen_id,
+                "status": "live",
+            }
+        )
 
     # 2. Find the most recent cold session for this queen and resume it.
     # IMPORTANT: skip sessions that don't belong in the queen DM:
@@ -323,7 +355,6 @@ async def handle_select_queen_session(request: web.Request) -> web.Response:
 
     live_session = manager.get_session(target_session_id)
     if live_session is not None:
-        await _stop_live_sessions(manager, keep_session_id=target_session_id)
         return web.json_response(
             {
                 "session_id": live_session.id,
@@ -332,11 +363,11 @@ async def handle_select_queen_session(request: web.Request) -> web.Response:
             }
         )
 
-    await _stop_live_sessions(manager)
-
     meta = _read_queen_session_meta(queen_id, target_session_id)
     agent_path = meta.get("agent_path")
-    initial_phase = None if agent_path else "independent"
+    # Colony resume (agent loaded) → "working" (3-phase target).
+    # Standalone queen resume → "independent" (DM mode).
+    initial_phase = "working" if agent_path else "independent"
     session = await _create_bound_queen_session(
         manager,
         queen_id,
@@ -354,6 +385,8 @@ async def handle_select_queen_session(request: web.Request) -> web.Response:
 
 async def handle_new_queen_session(request: web.Request) -> web.Response:
     """POST /api/queen/{queen_id}/session/new -- create a fresh queen session."""
+    from framework.tools.queen_lifecycle_tools import QUEEN_PHASES
+
     queen_id = request.match_info["queen_id"]
     manager = request.app["manager"]
 
@@ -363,11 +396,26 @@ async def handle_new_queen_session(request: web.Request) -> web.Response:
     except FileNotFoundError:
         return web.json_response({"error": f"Queen '{queen_id}' not found"}, status=404)
 
-    body = await request.json() if request.can_read_body else {}
+    if request.can_read_body:
+        try:
+            body = await request.json()
+        except json.JSONDecodeError:
+            return web.json_response({"error": "Invalid JSON body"}, status=400)
+        if not isinstance(body, dict):
+            return web.json_response({"error": "Request body must be a JSON object"}, status=400)
+    else:
+        body = {}
     initial_prompt = body.get("initial_prompt")
     initial_phase = body.get("initial_phase") or "independent"
+    if initial_phase not in QUEEN_PHASES:
+        return web.json_response(
+            {
+                "error": f"Invalid initial_phase '{initial_phase}'",
+                "valid": sorted(QUEEN_PHASES),
+            },
+            status=400,
+        )
 
-    await _stop_live_sessions(manager)
     session = await manager.create_session(
         initial_prompt=initial_prompt,
         queen_name=queen_id,
@@ -382,11 +430,98 @@ async def handle_new_queen_session(request: web.Request) -> web.Response:
     )
 
 
+MAX_AVATAR_BYTES = 2 * 1024 * 1024  # 2 MB max after compression
+_ALLOWED_AVATAR_TYPES = {
+    "image/jpeg": ".jpg",
+    "image/png": ".png",
+    "image/webp": ".webp",
+}
+
+
+async def handle_upload_avatar(request: web.Request) -> web.Response:
+    """POST /api/queen/{queen_id}/avatar — upload queen avatar image.
+
+    Accepts multipart/form-data with a single file field named 'avatar'.
+    Stores as avatar.{ext} in the queen's profile directory.
+    """
+    from framework.config import QUEENS_DIR
+
+    queen_id = request.match_info["queen_id"]
+    queen_dir = QUEENS_DIR / queen_id
+    if not (queen_dir / "profile.yaml").exists():
+        return web.json_response({"error": f"Queen '{queen_id}' not found"}, status=404)
+
+    reader = await request.multipart()
+    field = await reader.next()
+    if field is None or field.name != "avatar":
+        return web.json_response({"error": "Expected a file field named 'avatar'"}, status=400)
+
+    content_type = field.headers.get("Content-Type", "application/octet-stream")
+    # Also check by content_type from the field
+    if hasattr(field, "content_type"):
+        content_type = field.content_type or content_type
+
+    ext = _ALLOWED_AVATAR_TYPES.get(content_type)
+    if not ext:
+        return web.json_response(
+            {"error": f"Unsupported image type: {content_type}. Use JPEG, PNG, or WebP."},
+            status=400,
+        )
+
+    # Read the file data with size limit
+    data = bytearray()
+    while True:
+        chunk = await field.read_chunk(8192)
+        if not chunk:
+            break
+        data.extend(chunk)
+        if len(data) > MAX_AVATAR_BYTES:
+            return web.json_response(
+                {"error": f"Image too large. Maximum size is {MAX_AVATAR_BYTES // 1024 // 1024} MB."},
+                status=400,
+            )
+
+    if not data:
+        return web.json_response({"error": "Empty file"}, status=400)
+
+    # Remove any existing avatar files
+    for existing in queen_dir.glob("avatar.*"):
+        existing.unlink(missing_ok=True)
+
+    # Write the new avatar
+    avatar_path = queen_dir / f"avatar{ext}"
+    avatar_path.write_bytes(data)
+
+    logger.info("Avatar uploaded for queen %s: %s (%d bytes)", queen_id, avatar_path.name, len(data))
+    return web.json_response({"avatar_url": f"/api/queen/{queen_id}/avatar"})
+
+
+async def handle_get_avatar(request: web.Request) -> web.Response:
+    """GET /api/queen/{queen_id}/avatar — serve queen avatar image."""
+    from framework.config import QUEENS_DIR
+
+    queen_id = request.match_info["queen_id"]
+    queen_dir = QUEENS_DIR / queen_id
+
+    # Find avatar file with any supported extension
+    for ext in _ALLOWED_AVATAR_TYPES.values():
+        avatar_path = queen_dir / f"avatar{ext}"
+        if avatar_path.exists():
+            return web.FileResponse(
+                avatar_path,
+                headers={"Cache-Control": "public, max-age=3600"},
+            )
+
+    return web.json_response({"error": "No avatar found"}, status=404)
+
+
 def register_routes(app: web.Application) -> None:
     """Register queen profile routes."""
     app.router.add_get("/api/queen/profiles", handle_list_profiles)
     app.router.add_get("/api/queen/{queen_id}/profile", handle_get_profile)
     app.router.add_patch("/api/queen/{queen_id}/profile", handle_update_profile)
+    app.router.add_post("/api/queen/{queen_id}/avatar", handle_upload_avatar)
+    app.router.add_get("/api/queen/{queen_id}/avatar", handle_get_avatar)
     app.router.add_post("/api/queen/{queen_id}/session", handle_queen_session)
     app.router.add_post("/api/queen/{queen_id}/session/select", handle_select_queen_session)
     app.router.add_post("/api/queen/{queen_id}/session/new", handle_new_queen_session)

core/framework/server/routes_sessions.py

@@ -10,6 +10,7 @@ Session-primary routes:
 - GET    /api/sessions/{session_id}/stats             — runtime statistics
 - GET    /api/sessions/{session_id}/entry-points      — list entry points
 - PATCH  /api/sessions/{session_id}/triggers/{id}    — update trigger task
+- POST   /api/sessions/{session_id}/triggers/{id}/run — fire trigger once (manual)
 - GET    /api/sessions/{session_id}/colonies          — list colony IDs
 - GET    /api/sessions/{session_id}/events/history   — persisted eventbus log (for replay)
 
@@ -63,6 +64,8 @@ def _session_to_live_dict(session) -> dict:
         "queen_supports_images": supports_image_tool_results(queen_model) if queen_model else True,
         "queen_id": getattr(phase_state, "queen_id", None) if phase_state else None,
         "queen_name": (phase_state.queen_profile or {}).get("name") if phase_state else None,
+        "colony_spawned": getattr(session, "colony_spawned", False),
+        "spawned_colony_name": getattr(session, "spawned_colony_name", None),
     }
 
 
@@ -119,8 +122,19 @@ async def handle_create_session(request: web.Request) -> web.Response:
     (equivalent to the old POST /api/agents). Otherwise creates a queen-only
     session that can later have a colony loaded via POST /sessions/{id}/colony.
     """
+    from framework.agents.queen.queen_profiles import ensure_default_queens, load_queen_profile
+    from framework.tools.queen_lifecycle_tools import QUEEN_PHASES
+
     manager = _get_manager(request)
-    body = await request.json() if request.can_read_body else {}
+    if request.can_read_body:
+        try:
+            body = await request.json()
+        except json.JSONDecodeError:
+            return web.json_response({"error": "Invalid JSON body"}, status=400)
+        if not isinstance(body, dict):
+            return web.json_response({"error": "Request body must be a JSON object"}, status=400)
+    else:
+        body = {}
     agent_path = body.get("agent_path")
     agent_id = body.get("agent_id")
     session_id = body.get("session_id")
@@ -131,6 +145,21 @@ async def handle_create_session(request: web.Request) -> web.Response:
     initial_phase = body.get("initial_phase")
     worker_name = body.get("worker_name")
 
+    if initial_phase is not None and initial_phase not in QUEEN_PHASES:
+        return web.json_response(
+            {
+                "error": f"Invalid initial_phase '{initial_phase}'",
+                "valid": sorted(QUEEN_PHASES),
+            },
+            status=400,
+        )
+    if queen_name:
+        ensure_default_queens()
+        try:
+            load_queen_profile(queen_name)
+        except FileNotFoundError:
+            return web.json_response({"error": f"Queen '{queen_name}' not found"}, status=404)
+
     if agent_path:
         try:
             agent_path = str(validate_agent_path(agent_path))
@@ -157,6 +186,7 @@ async def handle_create_session(request: web.Request) -> web.Response:
                 model=model,
                 initial_prompt=initial_prompt,
                 queen_resume_from=queen_resume_from,
+                queen_name=queen_name,
                 initial_phase=initial_phase,
             )
     except ValueError as e:
@@ -245,7 +275,14 @@ async def handle_get_live_session(request: web.Request) -> web.Response:
             }
             mono = getattr(session, "trigger_next_fire", {}).get(t.id)
             if mono is not None:
-                entry["next_fire_in"] = max(0.0, mono - time.monotonic())
+                remaining = max(0.0, mono - time.monotonic())
+                entry["next_fire_in"] = remaining
+                entry["next_fire_at"] = int((time.time() + remaining) * 1000)
+            stats = getattr(session, "trigger_fire_stats", {}).get(t.id)
+            if stats:
+                entry["fire_count"] = stats.get("fire_count", 0)
+                if stats.get("last_fired_at") is not None:
+                    entry["last_fired_at"] = stats["last_fired_at"]
             data["entry_points"].append(entry)
         data["colonies"] = session.colony_runtime.list_graphs()
 
@@ -395,7 +432,14 @@ async def handle_session_entry_points(request: web.Request) -> web.Response:
         }
         mono = getattr(session, "trigger_next_fire", {}).get(t.id)
         if mono is not None:
-            entry["next_fire_in"] = max(0.0, mono - time.monotonic())
+            remaining = max(0.0, mono - time.monotonic())
+            entry["next_fire_in"] = remaining
+            entry["next_fire_at"] = int((time.time() + remaining) * 1000)
+        stats = getattr(session, "trigger_fire_stats", {}).get(t.id)
+        if stats:
+            entry["fire_count"] = stats.get("fire_count", 0)
+            if stats.get("last_fired_at") is not None:
+                entry["last_fired_at"] = stats["last_fired_at"]
         entry_points.append(entry)
     return web.json_response({"entry_points": entry_points})
 
@@ -546,6 +590,60 @@ async def handle_update_trigger_task(request: web.Request) -> web.Response:
     )
 
 
+async def handle_run_trigger(request: web.Request) -> web.Response:
+    """POST /api/sessions/{session_id}/triggers/{trigger_id}/run — fire the trigger once.
+
+    Manual invocation for testing. Works whether the trigger is active or
+    inactive; does not change active state and does not reset the scheduled
+    next-fire time of an active timer.
+    """
+    session, err = resolve_session(request)
+    if err:
+        return err
+
+    trigger_id = request.match_info["trigger_id"]
+    tdef = getattr(session, "available_triggers", {}).get(trigger_id)
+    if tdef is None:
+        return web.json_response(
+            {"error": f"Trigger '{trigger_id}' not found"},
+            status=404,
+        )
+
+    if getattr(session, "colony_runtime", None) is None:
+        return web.json_response({"error": "Colony not loaded"}, status=409)
+
+    executor = getattr(session, "queen_executor", None)
+    queen_node = getattr(executor, "node_registry", {}).get("queen") if executor else None
+    if queen_node is None:
+        return web.json_response({"error": "Queen not ready"}, status=409)
+
+    from framework.agent_loop.agent_loop import TriggerEvent
+
+    try:
+        await queen_node.inject_trigger(
+            TriggerEvent(
+                trigger_type=tdef.trigger_type,
+                source_id=trigger_id,
+                payload={
+                    "task": tdef.task or "",
+                    "trigger_config": tdef.trigger_config,
+                    "forced": True,
+                },
+            )
+        )
+    except Exception as exc:  # noqa: BLE001
+        return web.json_response(
+            {"error": f"Failed to fire trigger: {exc}"},
+            status=500,
+        )
+
+    from framework.tools.queen_lifecycle_tools import _emit_trigger_fired
+
+    await _emit_trigger_fired(session, trigger_id, tdef.trigger_type)
+
+    return web.json_response({"status": "fired", "trigger_id": trigger_id})
+
+
 async def handle_activate_trigger(request: web.Request) -> web.Response:
     """POST /api/sessions/{session_id}/triggers/{trigger_id}/activate — start a trigger."""
     session, err = resolve_session(request)
@@ -597,6 +695,17 @@ async def handle_activate_trigger(request: web.Request) -> web.Response:
 
         runner = getattr(session, "runner", None)
         colony_entry = runner.graph.entry_node if runner else None
+        config_out = dict(tdef.trigger_config)
+        mono = getattr(session, "trigger_next_fire", {}).get(trigger_id)
+        if mono is not None:
+            remaining = max(0.0, mono - time.monotonic())
+            config_out["next_fire_in"] = remaining
+            config_out["next_fire_at"] = int((time.time() + remaining) * 1000)
+        stats = getattr(session, "trigger_fire_stats", {}).get(trigger_id)
+        if stats:
+            config_out["fire_count"] = stats.get("fire_count", 0)
+            if stats.get("last_fired_at") is not None:
+                config_out["last_fired_at"] = stats["last_fired_at"]
         await bus.publish(
             AgentEvent(
                 type=EventType.TRIGGER_ACTIVATED,
@@ -604,7 +713,7 @@ async def handle_activate_trigger(request: web.Request) -> web.Response:
                 data={
                     "trigger_id": trigger_id,
                     "trigger_type": tdef.trigger_type,
-                    "trigger_config": tdef.trigger_config,
+                    "trigger_config": config_out,
                     "name": tdef.description or trigger_id,
                     **({"entry_node": colony_entry} if colony_entry else {}),
                 },
@@ -689,6 +798,110 @@ async def handle_session_colonies(request: web.Request) -> web.Response:
 _EVENTS_HISTORY_DEFAULT_LIMIT = 2000
 _EVENTS_HISTORY_MAX_LIMIT = 10000
 
+# Files at or below this size use the simple forward-scan path (cheap enough
+# that the seek-backward dance isn't worth it). Above this threshold we read
+# the tail directly from end-of-file so a 50 MB log doesn't have to be paged
+# through entirely just to surface the last 2000 lines.
+_EVENTS_HISTORY_REVERSE_TAIL_THRESHOLD_BYTES = 1 << 20  # 1 MB
+_EVENTS_HISTORY_REVERSE_TAIL_CHUNK_BYTES = 64 * 1024
+
+
+def _read_events_tail(events_path: Path, limit: int) -> tuple[list[dict], int, bool]:
+    """Read the tail of an append-only JSONL events log.
+
+    Returns ``(events, total, truncated)``.  ``events`` is at most ``limit``
+    lines, oldest-first.  ``total`` is the total number of non-blank lines in
+    the file (exact for the small-file path, exact for the large-file path
+    too — we do a separate fast newline-count pass).
+
+    Two paths:
+    - Small files (< ~1 MB): forward scan.  Cheap; gives an exact total for
+      free.  Defers ``json.loads`` to the bounded deque so we never parse a
+      line that's about to be dropped.
+    - Large files: seek to EOF and read backward in 64 KB chunks until we have
+      at least ``limit`` complete lines.  Parses only the tail.  ``total`` is
+      counted by a separate forward byte-scan that just counts newlines —
+      no JSON parse — so it stays cheap even for huge files.
+
+    Without these optimizations, mounting the chat for a long-running queen
+    with a ~50 k-event log used to spend most of its time inside ``json.loads``
+    on the server thread (and block the event loop while doing it).
+    """
+    from collections import deque
+
+    file_size = events_path.stat().st_size
+
+    if file_size <= _EVENTS_HISTORY_REVERSE_TAIL_THRESHOLD_BYTES:
+        tail_raw: deque[str] = deque(maxlen=limit)
+        total = 0
+        with open(events_path, encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                total += 1
+                tail_raw.append(line)
+        events: list[dict] = []
+        for raw in tail_raw:
+            try:
+                events.append(json.loads(raw))
+            except json.JSONDecodeError:
+                continue
+        return events, total, total > len(events)
+
+    # Large-file path: read backward until we have enough lines.
+    import os as _os
+
+    chunk_size = _EVENTS_HISTORY_REVERSE_TAIL_CHUNK_BYTES
+    pieces: list[bytes] = []
+    newline_count = 0
+    with open(events_path, "rb") as fb:
+        fb.seek(0, _os.SEEK_END)
+        pos = fb.tell()
+        while pos > 0 and newline_count <= limit:
+            read_size = min(chunk_size, pos)
+            pos -= read_size
+            fb.seek(pos)
+            chunk = fb.read(read_size)
+            newline_count += chunk.count(b"\n")
+            pieces.append(chunk)
+    pieces.reverse()
+    blob = b"".join(pieces)
+
+    # Drop the leading partial line unless we read from offset 0.
+    raw_lines = blob.split(b"\n")
+    if pos > 0 and raw_lines:
+        raw_lines = raw_lines[1:]
+    decoded = [ln.decode("utf-8", errors="replace").strip() for ln in raw_lines]
+    decoded = [ln for ln in decoded if ln]
+    if len(decoded) > limit:
+        decoded = decoded[-limit:]
+
+    events = []
+    for raw in decoded:
+        try:
+            events.append(json.loads(raw))
+        except json.JSONDecodeError:
+            continue
+
+    # Separate fast pass for total: count newlines only, no JSON parse.
+    total = 0
+    with open(events_path, "rb") as fb:
+        while True:
+            chunk = fb.read(1 << 20)
+            if not chunk:
+                break
+            total += chunk.count(b"\n")
+    # File may end without a trailing newline; if so, the last non-empty line
+    # was missed. Count it.
+    if file_size > 0:
+        with open(events_path, "rb") as fb:
+            fb.seek(-1, _os.SEEK_END)
+            if fb.read(1) != b"\n":
+                total += 1
+
+    return events, total, total > len(events)
+
 
 async def handle_session_events_history(request: web.Request) -> web.Response:
     """GET /api/sessions/{session_id}/events/history — persisted eventbus log.
@@ -718,6 +931,9 @@ async def handle_session_events_history(request: web.Request) -> web.Response:
     recent N events". Long-running colonies have produced files with 50k+
     events; before this cap, restoring on page-mount shipped the whole thing
     down the wire and blocked the UI for seconds.
+
+    The actual file read runs in a worker thread via ``asyncio.to_thread`` so
+    it doesn't block the event loop while other requests are in flight.
     """
     session_id = request.match_info["session_id"]
 
@@ -743,24 +959,8 @@ async def handle_session_events_history(request: web.Request) -> web.Response:
             }
         )
 
-    # Tail the file using a bounded deque — O(limit) memory regardless
-    # of file size. No need to materialize the whole list only to slice it.
-    from collections import deque
-
-    tail: deque[dict] = deque(maxlen=limit)
-    total = 0
     try:
-        with open(events_path, encoding="utf-8") as f:
-            for line in f:
-                line = line.strip()
-                if not line:
-                    continue
-                try:
-                    evt = json.loads(line)
-                except json.JSONDecodeError:
-                    continue
-                total += 1
-                tail.append(evt)
+        events, total, truncated = await asyncio.to_thread(_read_events_tail, events_path, limit)
     except OSError:
         return web.json_response(
             {
@@ -773,14 +973,13 @@ async def handle_session_events_history(request: web.Request) -> web.Response:
             }
         )
 
-    events = list(tail)
     return web.json_response(
         {
             "events": events,
             "session_id": session_id,
             "total": total,
             "returned": len(events),
-            "truncated": total > len(events),
+            "truncated": truncated,
             "limit": limit,
         }
     )
@@ -866,6 +1065,8 @@ async def handle_discover(request: web.Request) -> web.Response:
                 "tool_count": entry.tool_count,
                 "tags": entry.tags,
                 "last_active": entry.last_active,
+                "created_at": entry.created_at,
+                "icon": entry.icon,
                 "is_loaded": str(entry.path.resolve()) in loaded_paths,
                 "workers": [w.to_dict() for w in entry.workers],
             }
@@ -893,8 +1094,10 @@ async def handle_delete_agent(request: web.Request) -> web.Response:
     except ValueError as exc:
         return web.json_response({"error": str(exc)}, status=400)
 
-    # Reject deletion of framework agents (~/.hive/agents/) — those are internal
-    hive_agents_dir = Path.home() / ".hive" / "agents"
+    # Reject deletion of framework agents ($HIVE_HOME/agents/) — those are internal
+    from framework.config import HIVE_HOME
+
+    hive_agents_dir = HIVE_HOME / "agents"
     if resolved.is_relative_to(hive_agents_dir):
         return web.json_response({"error": "Cannot delete framework agents"}, status=403)
 
@@ -946,6 +1149,40 @@ async def handle_reveal_session_folder(request: web.Request) -> web.Response:
     return web.json_response({"path": str(folder)})
 
 
+async def handle_update_colony_metadata(request: web.Request) -> web.Response:
+    """PATCH /api/agents/metadata — update colony metadata (e.g. icon).
+
+    Body: {"agent_path": "...", "icon": "rocket"}
+    """
+    try:
+        body = await request.json()
+    except Exception:
+        return web.json_response({"error": "Invalid JSON body"}, status=400)
+
+    agent_path = body.get("agent_path")
+    if not agent_path:
+        return web.json_response({"error": "agent_path is required"}, status=400)
+
+    try:
+        resolved = validate_agent_path(agent_path)
+    except ValueError as exc:
+        return web.json_response({"error": str(exc)}, status=400)
+
+    metadata_path = resolved / "metadata.json"
+    metadata: dict = {}
+    if metadata_path.exists():
+        try:
+            metadata = json.loads(metadata_path.read_text(encoding="utf-8"))
+        except Exception:
+            pass
+
+    if "icon" in body:
+        metadata["icon"] = body["icon"]
+
+    metadata_path.write_text(json.dumps(metadata, indent=2, ensure_ascii=False), encoding="utf-8")
+    return web.json_response({"ok": True})
+
+
 # ------------------------------------------------------------------
 # Route registration
 # ------------------------------------------------------------------
@@ -956,6 +1193,7 @@ def register_routes(app: web.Application) -> None:
     # Discovery & agent management
     app.router.add_get("/api/discover", handle_discover)
     app.router.add_delete("/api/agents", handle_delete_agent)
+    app.router.add_patch("/api/agents/metadata", handle_update_colony_metadata)
 
     # Session lifecycle
     app.router.add_post("/api/sessions", handle_create_session)
@@ -983,6 +1221,10 @@ def register_routes(app: web.Application) -> None:
         "/api/sessions/{session_id}/triggers/{trigger_id}/deactivate",
         handle_deactivate_trigger,
     )
+    app.router.add_post(
+        "/api/sessions/{session_id}/triggers/{trigger_id}/run",
+        handle_run_trigger,
+    )
     app.router.add_get("/api/sessions/{session_id}/colonies", handle_session_colonies)
 
     app.router.add_get("/api/sessions/{session_id}/events/history", handle_session_events_history)

core/framework/server/routes_tasks.py

@@ -0,0 +1,112 @@
+"""REST routes for task lists.
+
+  GET /api/tasks/{task_list_id}                     -- snapshot of one list
+  GET /api/colonies/{colony_id}/task_lists          -- helper for colony view
+  GET /api/sessions/{session_id}/task_list_id       -- helper for session view
+
+The task_list_id segment uses URL-encoded colons (``colony%3Aabc`` /
+``session%3Aagent%3Asess``); aiohttp decodes them automatically.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from aiohttp import web
+
+from framework.tasks import get_task_store
+from framework.tasks.scoping import (
+    colony_task_list_id,
+    session_task_list_id,
+)
+
+logger = logging.getLogger(__name__)
+
+
+async def handle_get_task_list(request: web.Request) -> web.Response:
+    raw = request.match_info.get("task_list_id", "")
+    if not raw:
+        return web.json_response({"error": "task_list_id required"}, status=400)
+
+    store = get_task_store()
+    if not await store.list_exists(raw):
+        return web.json_response(
+            {"error": f"Task list {raw!r} not found", "task_list_id": raw, "tasks": []},
+            status=404,
+        )
+
+    meta = await store.get_meta(raw)
+    records = await store.list_tasks(raw)
+    return web.json_response(
+        {
+            "task_list_id": raw,
+            "role": meta.role.value if meta else "session",
+            "meta": meta.model_dump(mode="json") if meta else None,
+            "tasks": [
+                {
+                    "id": r.id,
+                    "subject": r.subject,
+                    "description": r.description,
+                    "active_form": r.active_form,
+                    "owner": r.owner,
+                    "status": r.status.value,
+                    "blocks": list(r.blocks),
+                    "blocked_by": list(r.blocked_by),
+                    "metadata": dict(r.metadata),
+                    "created_at": r.created_at,
+                    "updated_at": r.updated_at,
+                }
+                for r in records
+            ],
+        }
+    )
+
+
+async def handle_get_colony_task_lists(request: web.Request) -> web.Response:
+    """Return template_task_list_id and queen_session_task_list_id for a colony."""
+    colony_id = request.match_info.get("colony_id", "")
+    if not colony_id:
+        return web.json_response({"error": "colony_id required"}, status=400)
+
+    template_id = colony_task_list_id(colony_id)
+    # Queen's session list — the queen-of-colony's session_id == the
+    # browser-facing colony session id. The frontend already knows that
+    # value; we surface what we have on disk for completeness.
+    queen_session_id = request.query.get("queen_session_id")
+    queen_list_id = session_task_list_id("queen", queen_session_id) if queen_session_id else None
+    return web.json_response(
+        {
+            "template_task_list_id": template_id,
+            "queen_session_task_list_id": queen_list_id,
+        }
+    )
+
+
+async def handle_get_session_task_list_id(request: web.Request) -> web.Response:
+    """Return task_list_id and picked_up_from for a session.
+
+    The session_id is the queen's session id or a worker's session id;
+    both follow the same path. The agent_id is read from the request query
+    (passed by the frontend, which already knows which agent the session
+    belongs to).
+    """
+    session_id = request.match_info.get("session_id", "")
+    agent_id = request.query.get("agent_id", "queen")
+    if not session_id:
+        return web.json_response({"error": "session_id required"}, status=400)
+
+    task_list_id = session_task_list_id(agent_id, session_id)
+    store = get_task_store()
+    exists = await store.list_exists(task_list_id)
+    return web.json_response(
+        {
+            "task_list_id": task_list_id if exists else None,
+            "picked_up_from": None,
+        }
+    )
+
+
+def register_routes(app: web.Application) -> None:
+    app.router.add_get("/api/tasks/{task_list_id}", handle_get_task_list)
+    app.router.add_get("/api/colonies/{colony_id}/task_lists", handle_get_colony_task_lists)
+    app.router.add_get("/api/sessions/{session_id}/task_list_id", handle_get_session_task_list_id)

core/framework/server/routes_workers.py

@@ -67,11 +67,9 @@ async def handle_list_nodes(request: web.Request) -> web.Response:
     worker_session_id = request.query.get("session_id")
     if worker_session_id and session.worker_path:
         worker_session_id = safe_path_segment(worker_session_id)
-        from pathlib import Path
+        from framework.config import HIVE_HOME
 
-        state_path = (
-            Path.home() / ".hive" / "agents" / session.worker_path.name / "sessions" / worker_session_id / "state.json"
-        )
+        state_path = HIVE_HOME / "agents" / session.worker_path.name / "sessions" / worker_session_id / "state.json"
         if state_path.exists():
             try:
                 state = json.loads(state_path.read_text(encoding="utf-8"))
@@ -236,6 +234,217 @@ async def handle_node_tools(request: web.Request) -> web.Response:
     return web.json_response({"tools": tools_out})
 
 
+# ---------------------------------------------------------------------------
+# Live worker control — list / stop a specific worker / stop all
+# ---------------------------------------------------------------------------
+
+
+def _active_colony(session):
+    """Return the session's unified ColonyRuntime (``session.colony``) if present.
+
+    All spawned workers (queen-overseer + run_parallel_workers fan-outs)
+    are hosted here. ``session.colony_runtime`` is a different concept
+    (loaded agent graph) and doesn't hold the live worker registry we
+    need to enumerate / stop.
+    """
+    return getattr(session, "colony", None)
+
+
+def _build_live_workers_payload(colony) -> list[dict]:
+    """Serialize the colony's current worker registry.
+
+    Extracted so both the one-shot ``GET /workers`` handler and the SSE
+    ``/workers/stream`` handler render the exact same shape.
+    """
+    if colony is None:
+        return []
+
+    now = time.monotonic()
+    payload: list[dict] = []
+    try:
+        workers = list(colony._workers.values())  # type: ignore[attr-defined]
+    except Exception:
+        workers = []
+
+    for w in workers:
+        started_at = getattr(w, "_started_at", 0.0) or 0.0
+        duration = (now - started_at) if started_at else 0.0
+        result = getattr(w, "_result", None)
+        payload.append(
+            {
+                "worker_id": w.id,
+                "task": (w.task or "")[:400],
+                "status": str(getattr(w, "status", "unknown")),
+                "is_active": bool(getattr(w, "is_active", False)),
+                "duration_seconds": round(duration, 1),
+                "explicit_report": getattr(w, "_explicit_report", None),
+                "result_status": (result.status if result else None),
+                "result_summary": (result.summary if result else None),
+            }
+        )
+
+    # Active workers first, then terminated, newest-started first within group.
+    payload.sort(key=lambda r: (not r["is_active"], -(r["duration_seconds"] or 0)))
+    return payload
+
+
+def _payload_change_signature(payload: list[dict]) -> tuple:
+    """Cheap fingerprint for change detection on the SSE stream.
+
+    We intentionally exclude ``duration_seconds`` — it ticks every call
+    and would make every poll look like a change, defeating the "only
+    emit on change" optimisation. Everything else (status, result,
+    explicit_report) actually reflects worker state transitions.
+    """
+    return tuple(
+        (
+            w["worker_id"],
+            w["status"],
+            w["is_active"],
+            w["result_status"],
+            w["result_summary"],
+            bool(w["explicit_report"]),
+        )
+        for w in payload
+    )
+
+
+async def handle_live_workers_stream(request: web.Request) -> web.StreamResponse:
+    """GET /api/sessions/{session_id}/workers/stream — SSE feed.
+
+    Emits a ``snapshot`` event immediately, then re-emits every time
+    the worker registry changes (status transitions, new spawns, new
+    reports). Polls the runtime every 2s internally — the colony's
+    ``_workers`` dict is not observable otherwise. Clients disconnecting
+    bubbles up as ConnectionResetError from ``resp.write``.
+    """
+    session, err = resolve_session(request)
+    if err:
+        return err
+
+    import asyncio
+
+    resp = web.StreamResponse(
+        status=200,
+        headers={
+            "Content-Type": "text/event-stream",
+            "Cache-Control": "no-cache, no-transform",
+            "Connection": "keep-alive",
+            "X-Accel-Buffering": "no",
+        },
+    )
+    await resp.prepare(request)
+
+    async def _send(event: str, data) -> None:
+        payload = f"event: {event}\ndata: {json.dumps(data)}\n\n"
+        await resp.write(payload.encode("utf-8"))
+
+    last_signature: tuple | None = None
+    try:
+        while True:
+            colony = _active_colony(session)
+            workers = _build_live_workers_payload(colony)
+            signature = _payload_change_signature(workers)
+            if signature != last_signature:
+                await _send("snapshot", {"workers": workers})
+                last_signature = signature
+            await asyncio.sleep(2.0)
+    except (asyncio.CancelledError, ConnectionResetError):
+        raise
+    except Exception as exc:
+        logger.warning("live workers stream error: %s", exc, exc_info=True)
+    return resp
+
+
+async def handle_stop_live_worker(request: web.Request) -> web.Response:
+    """POST /api/sessions/{session_id}/workers/{worker_id}/stop — force-stop one worker.
+
+    Calls ``colony.stop_worker(worker_id)`` which cancels the worker's
+    background task. The worker's terminal SUBAGENT_REPORT still fires
+    (preserving any _explicit_report) so the queen sees a `[WORKER_REPORT]`
+    with ``status="stopped"``.
+    """
+    session, err = resolve_session(request)
+    if err:
+        return err
+
+    worker_id = request.match_info.get("worker_id", "")
+    if not worker_id:
+        return web.json_response({"error": "worker_id required"}, status=400)
+
+    colony = _active_colony(session)
+    if colony is None:
+        return web.json_response({"error": "No active colony on this session"}, status=503)
+
+    worker = colony._workers.get(worker_id)  # type: ignore[attr-defined]
+    if worker is None:
+        return web.json_response({"error": f"Worker '{worker_id}' not found"}, status=404)
+    if not worker.is_active:
+        return web.json_response(
+            {
+                "stopped": False,
+                "reason": "Worker already terminated",
+                "worker_id": worker_id,
+                "status": str(worker.status),
+            }
+        )
+
+    try:
+        await colony.stop_worker(worker_id)
+    except Exception as exc:
+        logger.exception("stop_worker failed for %s", worker_id)
+        return web.json_response(
+            {"stopped": False, "error": str(exc), "worker_id": worker_id},
+            status=500,
+        )
+
+    return web.json_response({"stopped": True, "worker_id": worker_id})
+
+
+async def handle_stop_all_live_workers(request: web.Request) -> web.Response:
+    """POST /api/sessions/{session_id}/workers/stop-all — force-stop every active worker.
+
+    The persistent overseer (if any) is skipped — it is the queen itself
+    and stopping it would end the session. Only ephemeral fan-out workers
+    are targeted.
+    """
+    session, err = resolve_session(request)
+    if err:
+        return err
+
+    colony = _active_colony(session)
+    if colony is None:
+        return web.json_response({"stopped": [], "error": "No active colony on this session"})
+
+    stopped: list[str] = []
+    errors: list[dict] = []
+    try:
+        workers = list(colony._workers.values())  # type: ignore[attr-defined]
+    except Exception:
+        workers = []
+
+    for w in workers:
+        if not w.is_active:
+            continue
+        if getattr(w, "_persistent", False):
+            # The overseer — don't kill the queen.
+            continue
+        try:
+            await colony.stop_worker(w.id)
+            stopped.append(w.id)
+        except Exception as exc:
+            logger.warning("stop-all: failed to stop %s: %s", w.id, exc)
+            errors.append({"worker_id": w.id, "error": str(exc)})
+
+    return web.json_response(
+        {
+            "stopped": stopped,
+            "stopped_count": len(stopped),
+            "errors": errors if errors else None,
+        }
+    )
+
+
 def register_routes(app: web.Application) -> None:
     """Register worker inspection routes."""
     app.router.add_get("/api/sessions/{session_id}/colonies/{colony_id}/nodes", handle_list_nodes)
@@ -248,3 +457,18 @@ def register_routes(app: web.Application) -> None:
         "/api/sessions/{session_id}/colonies/{colony_id}/nodes/{node_id}/tools",
         handle_node_tools,
     )
+    # Live worker control. The GET /workers list endpoint lives in
+    # routes_colony_workers.py — it reads from session.colony (the
+    # unified ColonyRuntime where run_parallel_workers-spawned workers
+    # actually live) and returns the WorkerSummary shape the frontend
+    # types against. Registering a duplicate here shadowed it in
+    # aiohttp's router and broke the Sessions tab.
+    app.router.add_get("/api/sessions/{session_id}/workers/stream", handle_live_workers_stream)
+    app.router.add_post(
+        "/api/sessions/{session_id}/workers/stop-all",
+        handle_stop_all_live_workers,
+    )
+    app.router.add_post(
+        "/api/sessions/{session_id}/workers/{worker_id}/stop",
+        handle_stop_live_worker,
+    )

core/framework/server/session_manager.py

@@ -19,7 +19,7 @@ from datetime import datetime
 from pathlib import Path
 from typing import Any, Literal
 
-from framework.config import QUEENS_DIR
+from framework.config import QUEENS_DIR, get_max_tokens
 from framework.host.triggers import TriggerDefinition
 
 logger = logging.getLogger(__name__)
@@ -93,6 +93,9 @@ class Session:
     worker_configured: bool = False
     # Monotonic timestamps for next trigger fire (mirrors AgentRuntime._timer_next_fire)
     trigger_next_fire: dict[str, float] = field(default_factory=dict)
+    # Per-trigger fire stats (session lifetime): {trigger_id: {"fire_count": int, "last_fired_at": epoch_ms}}.
+    # Reset on process restart — good enough as a "since this session started" counter.
+    trigger_fire_stats: dict[str, dict[str, Any]] = field(default_factory=dict)
     # 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
@@ -111,6 +114,12 @@ class Session:
     # tool unlocked. The mode is the canonical discriminator for storage
     # path, tool exposure, and SSE filtering — see the Phase 2 plan.
     mode: Literal["dm", "colony"] = "dm"
+    # Set to True after the user clicks the COLONY_CREATED system message
+    # in this DM. Locks the chat input — the user must compact+fork into a
+    # fresh session before continuing the conversation. Persisted in
+    # meta.json so the lock survives server restarts.
+    colony_spawned: bool = False
+    spawned_colony_name: str | None = None
 
 
 class SessionManager:
@@ -149,13 +158,9 @@ class SessionManager:
         try:
             ensured = ensure_all_colony_dbs()
             if ensured:
-                logger.info(
-                    "progress_db: ensured %d colony DB(s) at startup", len(ensured)
-                )
+                logger.info("progress_db: ensured %d colony DB(s) at startup", len(ensured))
         except Exception:
-            logger.warning(
-                "progress_db: backfill at startup failed (non-fatal)", exc_info=True
-            )
+            logger.warning("progress_db: backfill at startup failed (non-fatal)", exc_info=True)
 
     def build_llm(self, model: str | None = None):
         """Construct an LLM provider using the server's configured defaults."""
@@ -417,6 +422,27 @@ class SessionManager:
             if existing.worker_path and str(existing.worker_path) == str(agent_path):
                 return existing
 
+        # When the queen forked this colony, the inherited DM transcript
+        # is compacted in the background (see fork_session_into_colony).
+        # Block here until that compactor finishes so _load_worker_core
+        # reads the compacted summary — not the raw transcript (which
+        # would defeat the fork's purpose). Bounded wait: on timeout we
+        # proceed anyway so a stuck compactor can't brick the colony.
+        if queen_resume_from:
+            try:
+                from framework.server import compaction_status
+
+                await compaction_status.await_completion(
+                    _find_queen_session_dir(queen_resume_from),
+                    timeout=180.0,
+                )
+            except Exception:
+                logger.debug(
+                    "await_compaction failed for %s — proceeding",
+                    queen_resume_from,
+                    exc_info=True,
+                )
+
         session = await self._create_session_core(
             session_id=_colony_session_id or queen_resume_from,
             model=model,
@@ -520,8 +546,10 @@ class SessionManager:
         session.colony_name = colony_id
         session.worker_path = agent_path
 
-        # Worker storage: ~/.hive/agents/{colony_name}/{worker_name}/
-        worker_storage = Path.home() / ".hive" / "agents" / colony_id / worker_name
+        # Worker storage: $HIVE_HOME/agents/{colony_name}/{worker_name}/
+        from framework.config import HIVE_HOME
+
+        worker_storage = HIVE_HOME / "agents" / colony_id / worker_name
         worker_storage.mkdir(parents=True, exist_ok=True)
 
         # Copy conversations from colony if fresh
@@ -672,7 +700,10 @@ class SessionManager:
             available_tools=all_tools,
             goal_context=goal.to_prompt_context(),
             goal=goal,
-            max_tokens=8192,
+            # Worker output cap — pull from configuration.json instead of
+            # hard-coding 8192. glm-5.1/kimi-k2.5 both support 32k out, and
+            # capping at 8k silently truncates long worker turns mid-tool.
+            max_tokens=get_max_tokens(),
             stream_id=worker_name,
             execution_id=worker_name,
             identity_prompt=worker_data.get("identity_prompt", ""),
@@ -689,8 +720,21 @@ class SessionManager:
             event_bus=session.event_bus,
         )
 
-        # Start the worker's agent loop in the background
-        session.queen_task = asyncio.create_task(session.queen_executor.run(initial_message=initial_prompt))
+        # Start the worker's agent loop in the background.
+        # Scope browser profile per-session so parallel sessions drive
+        # independent Chrome tab groups. Browser tools live in an MCP
+        # subprocess; we inject `profile` via the ToolRegistry execution
+        # context (a CONTEXT_PARAM) so it flows into every tool call.
+        async def _run_worker():
+            try:
+                from framework.loader.tool_registry import ToolRegistry
+
+                ToolRegistry.set_execution_context(profile=session.id)
+            except Exception:
+                logger.debug("Worker: failed to set browser profile", exc_info=True)
+            await session.queen_executor.run(initial_message=initial_prompt)
+
+        session.queen_task = asyncio.create_task(_run_worker())
 
         # Set up event persistence
         if session.event_bus and queen_dir:
@@ -888,7 +932,9 @@ class SessionManager:
            that process is still running on the host. If it is, the session is
            owned by another healthy worker process, so leave it alone.
         """
-        sessions_path = Path.home() / ".hive" / "agents" / agent_path.name / "sessions"
+        from framework.config import HIVE_HOME
+
+        sessions_path = HIVE_HOME / "agents" / agent_path.name / "sessions"
         if not sessions_path.exists():
             return
 
@@ -1184,8 +1230,27 @@ class SessionManager:
                 logger.info("Session '%s': shutdown reflection spawned", session_id)
                 self._background_tasks.add(task)
                 task.add_done_callback(self._background_tasks.discard)
-            except Exception:
-                logger.warning("Session '%s': failed to spawn shutdown reflection", session_id, exc_info=True)
+            except RuntimeError as exc:
+                # Most common when a session is stopped after the event loop
+                # has closed (e.g. during server shutdown or from an atexit
+                # handler). The reflection would have had nothing to write
+                # anyway — no new turns since the last periodic reflection.
+                logger.warning(
+                    "Session '%s': shutdown reflection skipped — event loop unavailable (%s). "
+                    "Normal during server shutdown; anything worth persisting was saved by the "
+                    "periodic reflection after the last turn.",
+                    session_id,
+                    exc,
+                )
+            except Exception as exc:
+                logger.warning(
+                    "Session '%s': failed to spawn shutdown reflection: %s: %s. "
+                    "Check that queen_dir exists and session.llm is configured; full traceback follows.",
+                    session_id,
+                    type(exc).__name__,
+                    exc,
+                    exc_info=True,
+                )
 
         if session.queen_task is not None:
             session.queen_task.cancel()
@@ -1310,6 +1375,13 @@ class SessionManager:
                 _new_meta["agent_path"] = str(session.worker_path)
             _existing_meta.update(_new_meta)
             _meta_path.write_text(json.dumps(_existing_meta), encoding="utf-8")
+            # Hydrate colony-spawned lock state from meta.json so the lock
+            # survives server restart / cold-resume into a live session.
+            if _existing_meta.get("colony_spawned") is True:
+                session.colony_spawned = True
+                _spawned_name = _existing_meta.get("spawned_colony_name")
+                if isinstance(_spawned_name, str):
+                    session.spawned_colony_name = _spawned_name
         except OSError:
             pass
 
@@ -1388,34 +1460,24 @@ class SessionManager:
             )
 
         # Auto-load worker on cold restore — the queen's conversation expects
-        # the agent to be loaded, but the new session has no worker.
+        # the colony to be loaded, but the new session has no worker.
         if session.queen_resume_from and not session.colony_runtime:
             meta_path = queen_dir / "meta.json"
             if meta_path.exists():
                 try:
                     _meta = json.loads(meta_path.read_text(encoding="utf-8"))
                     _agent_path = _meta.get("agent_path")
-                    _phase = _meta.get("phase")
 
                     if _agent_path and Path(_agent_path).exists():
-                        if _phase in ("staging", "running", None):
-                            # Agent fully built — load worker and resume
-                            await self.load_colony(session.id, _agent_path)
-                            if session.phase_state:
-                                await session.phase_state.switch_to_staging(source="auto")
-                            logger.info("Cold restore: auto-loaded worker from %s", _agent_path)
-                        elif _phase == "building":
-                            # Agent folder exists but incomplete — resume building
-                            if session.phase_state:
-                                session.phase_state.agent_path = _agent_path
-                                await session.phase_state.switch_to_building(source="auto")
-                            logger.info("Cold restore: resumed BUILDING phase for %s", _agent_path)
-                        elif _phase == "planning":
-                            if session.phase_state:
-                                session.phase_state.agent_path = _agent_path
-                            logger.info("Cold restore: PLANNING phase for %s", _agent_path)
+                        await self.load_colony(session.id, _agent_path)
+                        if session.phase_state:
+                            # Restored colony session lands in reviewing — the
+                            # queen summarises whatever the last run produced
+                            # before the user decides what to do next.
+                            await session.phase_state.switch_to_reviewing(source="auto")
+                        logger.info("Cold restore: auto-loaded colony from %s", _agent_path)
                 except Exception:
-                    logger.warning("Cold restore: failed to auto-load worker", exc_info=True)
+                    logger.warning("Cold restore: failed to auto-load colony", exc_info=True)
 
     # ------------------------------------------------------------------
     # Phase 2: unified ColonyRuntime construction
@@ -1480,8 +1542,46 @@ class SessionManager:
             tool_executor=queen_tool_executor,
             event_bus=session.event_bus,
             colony_id=session.id,
+            # Wire the on-disk colony name and queen id so
+            # ColonyRuntime auto-derives its override paths. DM sessions
+            # have no colony_name (session.colony_name is None), which
+            # keeps them out of the per-colony JSON store.
+            colony_name=getattr(session, "colony_name", None),
+            queen_id=getattr(session, "queen_name", None) or None,
             pipeline_stages=[],  # queen pipeline runs in queen_orchestrator, not here
         )
+
+        # Per-colony tool allowlist, loaded from the colony's metadata.json
+        # when this session is attached to a real forked colony. For pure
+        # queen DM sessions (session.colony_name is None) we only capture
+        # the MCP-origin set — the allowlist stays ``None`` so every MCP
+        # tool passes through by default.
+        try:
+            mcp_tool_names_all: set[str] = set()
+            mgr_catalog = getattr(self, "_mcp_tool_catalog", None)
+            if isinstance(mgr_catalog, dict):
+                for entries in mgr_catalog.values():
+                    for entry in entries:
+                        name = entry.get("name") if isinstance(entry, dict) else None
+                        if name:
+                            mcp_tool_names_all.add(name)
+            enabled_mcp_tools: list[str] | None = None
+            colony_name = getattr(session, "colony_name", None)
+            if colony_name:
+                # Colony tool allowlist lives in a dedicated tools.json
+                # sidecar next to metadata.json. The helper migrates any
+                # legacy field out of metadata.json on first read.
+                from framework.host.colony_tools_config import load_colony_tools_config
+
+                enabled_mcp_tools = load_colony_tools_config(colony_name)
+            colony.set_tool_allowlist(enabled_mcp_tools, mcp_tool_names_all)
+        except Exception:
+            logger.debug(
+                "Colony allowlist bootstrap failed for session %s",
+                session.id,
+                exc_info=True,
+            )
+
         await colony.start()
         session.colony = colony
 
@@ -1574,8 +1674,28 @@ class SessionManager:
         # Resolve entry node for trigger target
         runner = getattr(session, "runner", None)
         colony_entry = runner.graph.entry_node if runner else None
+        fire_times = getattr(session, "trigger_next_fire", {})
+        fire_stats = getattr(session, "trigger_fire_stats", {})
+        now_mono = time.monotonic()
+        now_wall = time.time()
 
         for t in triggers.values():
+            # Merge ephemeral next-fire data + historical fire stats into
+            # trigger_config so the UI can render a live-ticking countdown
+            # and a "fired Nx · last 2m ago" badge. `next_fire_at` is epoch
+            # milliseconds (wall clock) — the frontend anchors its ticker
+            # on this. `next_fire_in` is kept for legacy consumers.
+            config_out = dict(t.trigger_config)
+            mono = fire_times.get(t.id)
+            if mono is not None:
+                remaining = max(0.0, mono - now_mono)
+                config_out["next_fire_in"] = remaining
+                config_out["next_fire_at"] = int((now_wall + remaining) * 1000)
+            stats = fire_stats.get(t.id)
+            if stats:
+                config_out["fire_count"] = stats.get("fire_count", 0)
+                if stats.get("last_fired_at") is not None:
+                    config_out["last_fired_at"] = stats["last_fired_at"]
             await session.event_bus.publish(
                 AgentEvent(
                     type=event_type,
@@ -1583,7 +1703,7 @@ class SessionManager:
                     data={
                         "trigger_id": t.id,
                         "trigger_type": t.trigger_type,
-                        "trigger_config": t.trigger_config,
+                        "trigger_config": config_out,
                         "name": t.description or t.id,
                         **({"entry_node": colony_entry} if colony_entry else {}),
                     },
@@ -1651,6 +1771,42 @@ class SessionManager:
     def list_sessions(self) -> list[Session]:
         return list(self._sessions.values())
 
+    # ------------------------------------------------------------------
+    # Skill override helpers — used by routes_skills to find every live
+    # SkillsManager affected by a queen- or colony-scope mutation so a
+    # single HTTP call can reload them all.
+    # ------------------------------------------------------------------
+
+    def iter_queen_sessions(self, queen_id: str):
+        """Yield live sessions whose queen matches ``queen_id``."""
+        for s in self._sessions.values():
+            if getattr(s, "queen_name", None) == queen_id:
+                yield s
+
+    def iter_colony_runtimes(
+        self,
+        *,
+        queen_id: str | None = None,
+        colony_name: str | None = None,
+    ):
+        """Yield live ``ColonyRuntime`` instances matching the filters.
+
+        ``queen_id`` alone → every runtime whose ``queen_id`` matches
+        (useful when the user toggles a queen-scope skill — all her
+        colonies must reload).  ``colony_name`` alone → the single
+        runtime pinned to that colony.  Both → intersection. No filters
+        → every live runtime (used by global ``/api/skills`` reload).
+        """
+        for s in self._sessions.values():
+            colony = getattr(s, "colony", None)
+            if colony is None:
+                continue
+            if queen_id is not None and getattr(colony, "queen_id", None) != queen_id:
+                continue
+            if colony_name is not None and getattr(colony, "colony_name", None) != colony_name:
+                continue
+            yield colony
+
     # ------------------------------------------------------------------
     # Cold session helpers (disk-only, no live runtime required)
     # ------------------------------------------------------------------
@@ -1695,6 +1851,8 @@ class SessionManager:
         # Read extra metadata written at session start
         agent_name: str | None = None
         agent_path: str | None = None
+        colony_spawned: bool = False
+        spawned_colony_name: str | None = None
         meta_path = queen_dir / "meta.json"
         if meta_path.exists():
             try:
@@ -1702,6 +1860,10 @@ class SessionManager:
                 agent_name = meta.get("agent_name")
                 agent_path = meta.get("agent_path")
                 created_at = meta.get("created_at") or created_at
+                colony_spawned = bool(meta.get("colony_spawned"))
+                _spawned = meta.get("spawned_colony_name")
+                if isinstance(_spawned, str):
+                    spawned_colony_name = _spawned
             except (json.JSONDecodeError, OSError):
                 pass
 
@@ -1713,6 +1875,8 @@ class SessionManager:
             "created_at": created_at,
             "agent_name": agent_name,
             "agent_path": agent_path,
+            "colony_spawned": colony_spawned,
+            "spawned_colony_name": spawned_colony_name,
         }
 
     @staticmethod
@@ -1761,73 +1925,38 @@ class SessionManager:
             if meta.get("colony_fork"):
                 continue
 
-            # 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.
+            # Preview of the last client-facing exchange. Cached in
+            # ``summary.json`` next to ``meta.json`` so the sidebar doesn't
+            # have to rescan every part on each list call. The cache is
+            # written incrementally by FileConversationStore.write_part; if
+            # missing or stale (parts dir mtime newer than the summary file)
+            # we do a one-time full rebuild and write a fresh summary.
+            #
+            # NOTE on activity timestamps: the session directory's own mtime
+            # is NOT reliable as a "last activity" marker — POSIX dir mtime
+            # only updates when direct entries change, and conversation
+            # parts live under conversations/parts/, so writing a new part
+            # does not bubble up to the session dir.
+            from framework.storage import session_summary
+
             last_message: str | None = None
             message_count: int = 0
-            # Last-activity timestamp — mtime of the latest client-facing message.
-            # Falls back to session creation time for empty sessions. NOTE: the
-            # session directory's own mtime is NOT reliable here — POSIX dir mtime
-            # only updates when direct entries change, and conversation parts are
-            # nested under conversations/parts/, so writing a new part does not
-            # bubble up to the session dir.
             last_active_at: float = float(created_at) if isinstance(created_at, (int, float)) else 0.0
             convs_dir = d / "conversations"
+
+            summary: dict | None = None
             if convs_dir.exists():
-                try:
-                    all_parts: list[dict] = []
+                if session_summary.is_stale(d):
+                    summary = session_summary.rebuild_summary(d)
+                else:
+                    summary = session_summary.read_summary(d)
 
-                    def _collect_parts(parts_dir: Path, _dest: list[dict] = all_parts) -> None:
-                        if not parts_dir.exists():
-                            return
-                        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)
-                                _dest.append(part)
-                            except (json.JSONDecodeError, OSError):
-                                continue
-
-                    # Flat layout: conversations/parts/*.json
-                    _collect_parts(convs_dir / "parts")
-                    # Node-based layout: conversations/<node_id>/parts/*.json
-                    for node_dir in convs_dir.iterdir():
-                        if not node_dir.is_dir() or node_dir.name == "parts":
-                            continue
-                        _collect_parts(node_dir / "parts")
-                    # 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)
-                    # Take the latest message's timestamp as the activity marker.
-                    # _collect_parts sets created_at via setdefault to the part
-                    # file's mtime, so this is always a valid float.
-                    if client_msgs:
-                        latest_ts = client_msgs[-1].get("created_at")
-                        if isinstance(latest_ts, (int, float)) and latest_ts > last_active_at:
-                            last_active_at = float(latest_ts)
-                    # 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
+            if summary is not None:
+                message_count = int(summary.get("message_count") or 0)
+                last_message = summary.get("last_message")
+                cached_active = summary.get("last_active_at")
+                if isinstance(cached_active, (int, float)) and cached_active > last_active_at:
+                    last_active_at = float(cached_active)
 
             # Derive queen_id from directory structure: queens/{queen_id}/sessions/{session_id}
             queen_id = d.parent.parent.name if d.parent.name == "sessions" else None

core/framework/server/tests/test_api.py

@@ -14,6 +14,7 @@ from unittest.mock import AsyncMock, MagicMock
 import pytest
 from aiohttp.test_utils import TestClient, TestServer
 
+from framework.host.execution_manager import ExecutionAlreadyRunningError
 from framework.host.triggers import TriggerDefinition
 from framework.llm.model_catalog import get_models_catalogue
 from framework.server import (
@@ -89,8 +90,8 @@ class MockStream:
     _active_executors: dict = field(default_factory=dict)
     active_execution_ids: set = field(default_factory=set)
 
-    async def cancel_execution(self, execution_id: str, reason: str | None = None) -> bool:
-        return execution_id in self._execution_tasks
+    async def cancel_execution(self, execution_id: str, reason: str | None = None) -> str:
+        return "cancelled" if execution_id in self._execution_tasks else "not_found"
 
 
 @dataclass
@@ -638,13 +639,17 @@ class TestQueenSessionSelection:
             )
             assert resp.status == 200
             data = await resp.json()
-
-        assert data == {
-            "session_id": "queen_live",
-            "queen_id": "queen_technology",
-            "status": "live",
-        }
-        assert any(call.args == ("other_live",) for call in manager.stop_session.await_args_list)
+            # Assert inside the async-with so app shutdown (which stops
+            # remaining sessions as cleanup) doesn't pollute the assertions.
+            assert data == {
+                "session_id": "queen_live",
+                "queen_id": "queen_technology",
+                "status": "live",
+            }
+            # Other queen's live session must be left running so multiple
+            # queens can stay active in parallel across navigation.
+            manager.stop_session.assert_not_awaited()
+            assert "other_live" in manager._sessions
 
     @pytest.mark.asyncio
     async def test_select_queen_session_restores_specific_history_session(self, monkeypatch, tmp_path):
@@ -745,18 +750,21 @@ class TestQueenSessionSelection:
             )
             assert resp.status == 200
             data = await resp.json()
-
-        assert data == {
-            "session_id": "fresh_thread",
-            "queen_id": "queen_technology",
-            "status": "created",
-        }
-        manager.stop_session.assert_awaited_once_with("old_live")
-        manager.create_session.assert_awaited_once_with(
-            initial_prompt=None,
-            queen_name="queen_technology",
-            initial_phase="independent",
-        )
+            # Assert inside the async-with so app shutdown (which stops
+            # remaining sessions as cleanup) doesn't pollute the assertions.
+            assert data == {
+                "session_id": "fresh_thread",
+                "queen_id": "queen_technology",
+                "status": "created",
+            }
+            # Other queen's live session must be left running.
+            manager.stop_session.assert_not_awaited()
+            assert "old_live" in manager._sessions
+            manager.create_session.assert_awaited_once_with(
+                initial_prompt=None,
+                queen_name="queen_technology",
+                initial_phase="independent",
+            )
 
 
 class TestExecution:
@@ -773,6 +781,21 @@ class TestExecution:
             data = await resp.json()
             assert data["execution_id"] == "exec_test_123"
 
+    @pytest.mark.asyncio
+    async def test_trigger_returns_409_when_execution_still_running(self):
+        session = _make_session()
+        session.colony_runtime.trigger = AsyncMock(side_effect=ExecutionAlreadyRunningError("default", ["session-1"]))
+        app = _make_app_with_session(session)
+        async with TestClient(TestServer(app)) as client:
+            resp = await client.post(
+                "/api/sessions/test_agent/trigger",
+                json={"entry_point_id": "default", "input_data": {"msg": "hi"}},
+            )
+            assert resp.status == 409
+            data = await resp.json()
+            assert data["stream_id"] == "default"
+            assert data["active_execution_ids"] == ["session-1"]
+
     @pytest.mark.asyncio
     async def test_trigger_not_found(self):
         app = create_app()
@@ -911,6 +934,7 @@ class TestExecution:
             data = await resp.json()
             assert data["stopped"] is False
             assert data["cancelled"] == []
+            assert data["cancelling"] == []
             assert data["timers_paused"] is True
 
     @pytest.mark.asyncio
@@ -1020,6 +1044,22 @@ class TestStop:
             assert resp.status == 200
             data = await resp.json()
             assert data["stopped"] is True
+            assert data["cancelling"] is False
+
+    @pytest.mark.asyncio
+    async def test_stop_returns_accepted_while_execution_is_still_cancelling(self):
+        session = _make_session()
+        session.colony_runtime._mock_streams["default"].cancel_execution = AsyncMock(return_value="cancelling")
+        app = _make_app_with_session(session)
+        async with TestClient(TestServer(app)) as client:
+            resp = await client.post(
+                "/api/sessions/test_agent/stop",
+                json={"execution_id": "exec_abc"},
+            )
+            assert resp.status == 202
+            data = await resp.json()
+            assert data["stopped"] is False
+            assert data["cancelling"] is True
 
     @pytest.mark.asyncio
     async def test_stop_not_found(self):
@@ -1476,6 +1516,65 @@ class TestCredentials:
             data = await resp.json()
             assert data["credentials"] == []
 
+    @pytest.mark.asyncio
+    async def test_list_credentials_skips_unreadable_encrypted_entry(self):
+        from pydantic import SecretStr
+
+        from framework.credentials.models import CredentialDecryptionError, CredentialKey, CredentialObject
+
+        class BrokenStore:
+            def list_credentials(self):
+                return ["good_cred", "bad_cred"]
+
+            def get_credential(self, credential_id, refresh_if_needed=False):
+                if credential_id == "bad_cred":
+                    raise CredentialDecryptionError("bad encrypted file")
+                return CredentialObject(
+                    id=credential_id,
+                    keys={"api_key": CredentialKey(name="api_key", value=SecretStr("secret"))},
+                )
+
+        app = create_app()
+        app["credential_store"] = BrokenStore()
+
+        async with TestClient(TestServer(app)) as client:
+            resp = await client.get("/api/credentials")
+            assert resp.status == 200
+            data = await resp.json()
+
+        assert [c["credential_id"] for c in data["credentials"]] == ["good_cred"]
+        assert data["unreadable_credentials"] == ["bad_cred"]
+        assert "secret" not in json.dumps(data)
+
+    @pytest.mark.asyncio
+    async def test_get_credential_unreadable_returns_recoverable_conflict(self):
+        from framework.credentials.models import CredentialDecryptionError
+
+        class BrokenStore:
+            def get_credential(self, credential_id, refresh_if_needed=False):
+                raise CredentialDecryptionError("bad encrypted file")
+
+        app = create_app()
+        app["credential_store"] = BrokenStore()
+
+        async with TestClient(TestServer(app)) as client:
+            resp = await client.get("/api/credentials/bad_cred")
+            data = await resp.json()
+
+        assert resp.status == 409
+        assert data["credential_id"] == "bad_cred"
+        assert data["recoverable"] is True
+
+    def test_specs_availability_treats_decryption_error_as_unavailable(self):
+        from framework.credentials.models import CredentialDecryptionError
+        from framework.server.routes_credentials import _is_available_for_specs
+
+        class BrokenStore:
+            def is_available(self, credential_id):
+                raise CredentialDecryptionError("bad encrypted file")
+
+        assert _is_available_for_specs(BrokenStore(), "exa_search") is False
+
     @pytest.mark.asyncio
     async def test_save_and_list_credential(self):
         app = self._make_app()

core/framework/server/tests/test_colonies_import.py

@@ -0,0 +1,425 @@
+"""Tests for POST /api/colonies/import — tar-based colony onboarding.
+
+The handler resolves writes against ``framework.config.COLONIES_DIR``;
+every test redirects that into a ``tmp_path`` so we never touch the real
+``~/.hive/colonies`` tree.
+"""
+
+from __future__ import annotations
+
+import io
+import tarfile
+from pathlib import Path
+
+import pytest
+from aiohttp import FormData, web
+from aiohttp.test_utils import TestClient, TestServer
+
+from framework.server import routes_colonies
+
+
+def _build_tar(layout: dict[str, bytes | None], *, gzip: bool = True) -> bytes:
+    """Build an in-memory tar with the given paths.
+
+    ``layout`` maps archive member names to file contents; passing ``None``
+    creates a directory entry instead of a regular file.
+    """
+    buf = io.BytesIO()
+    mode = "w:gz" if gzip else "w"
+    with tarfile.open(fileobj=buf, mode=mode) as tf:
+        for name, content in layout.items():
+            if content is None:
+                info = tarfile.TarInfo(name=name)
+                info.type = tarfile.DIRTYPE
+                info.mode = 0o755
+                tf.addfile(info)
+            else:
+                info = tarfile.TarInfo(name=name)
+                info.size = len(content)
+                info.mode = 0o644
+                tf.addfile(info, io.BytesIO(content))
+    return buf.getvalue()
+
+
+def _build_tar_with_symlink(top: str, link_name: str, link_target: str) -> bytes:
+    buf = io.BytesIO()
+    with tarfile.open(fileobj=buf, mode="w:gz") as tf:
+        info = tarfile.TarInfo(name=top)
+        info.type = tarfile.DIRTYPE
+        info.mode = 0o755
+        tf.addfile(info)
+        sym = tarfile.TarInfo(name=f"{top}/{link_name}")
+        sym.type = tarfile.SYMTYPE
+        sym.linkname = link_target
+        tf.addfile(sym)
+    return buf.getvalue()
+
+
+@pytest.fixture
+def colonies_dir(tmp_path, monkeypatch):
+    """Redirect COLONIES_DIR into a tmp tree."""
+    colonies = tmp_path / "colonies"
+    colonies.mkdir()
+    monkeypatch.setattr(routes_colonies, "COLONIES_DIR", colonies)
+    return colonies
+
+
+async def _client(app: web.Application) -> TestClient:
+    return TestClient(TestServer(app))
+
+
+def _app() -> web.Application:
+    app = web.Application()
+    routes_colonies.register_routes(app)
+    return app
+
+
+def _form(file_bytes: bytes, *, filename: str = "colony.tar.gz", **fields: str) -> FormData:
+    fd = FormData()
+    fd.add_field("file", file_bytes, filename=filename, content_type="application/gzip")
+    for k, v in fields.items():
+        fd.add_field(k, v)
+    return fd
+
+
+@pytest.mark.asyncio
+async def test_happy_path_imports_colony(colonies_dir: Path) -> None:
+    archive = _build_tar(
+        {
+            "x_daily/": None,
+            "x_daily/metadata.json": b'{"colony_name":"x_daily"}',
+            "x_daily/scripts/run.sh": b"#!/bin/sh\necho hi\n",
+        }
+    )
+    async with await _client(_app()) as c:
+        resp = await c.post("/api/colonies/import", data=_form(archive))
+        assert resp.status == 201, await resp.text()
+        body = await resp.json()
+    assert body["name"] == "x_daily"
+    assert body["files_imported"] == 2
+    assert (colonies_dir / "x_daily" / "metadata.json").read_bytes() == b'{"colony_name":"x_daily"}'
+    assert (colonies_dir / "x_daily" / "scripts" / "run.sh").exists()
+
+
+@pytest.mark.asyncio
+async def test_name_override(colonies_dir: Path) -> None:
+    archive = _build_tar({"x_daily/": None, "x_daily/file.txt": b"hi"})
+    async with await _client(_app()) as c:
+        resp = await c.post("/api/colonies/import", data=_form(archive, name="other_name"))
+        assert resp.status == 201
+        body = await resp.json()
+    assert body["name"] == "other_name"
+    assert (colonies_dir / "other_name" / "file.txt").read_bytes() == b"hi"
+    assert not (colonies_dir / "x_daily").exists()
+
+
+@pytest.mark.asyncio
+async def test_rejects_existing_without_replace_flag(colonies_dir: Path) -> None:
+    (colonies_dir / "x_daily").mkdir()
+    (colonies_dir / "x_daily" / "old.txt").write_text("preserved")
+    archive = _build_tar({"x_daily/": None, "x_daily/new.txt": b"new"})
+    async with await _client(_app()) as c:
+        resp = await c.post("/api/colonies/import", data=_form(archive))
+        assert resp.status == 409
+    # Original content untouched
+    assert (colonies_dir / "x_daily" / "old.txt").read_text() == "preserved"
+
+
+@pytest.mark.asyncio
+async def test_replace_existing_overwrites(colonies_dir: Path) -> None:
+    (colonies_dir / "x_daily").mkdir()
+    (colonies_dir / "x_daily" / "old.txt").write_text("preserved")
+    archive = _build_tar({"x_daily/": None, "x_daily/new.txt": b"new"})
+    async with await _client(_app()) as c:
+        resp = await c.post(
+            "/api/colonies/import",
+            data=_form(archive, replace_existing="true"),
+        )
+        assert resp.status == 201, await resp.text()
+    assert not (colonies_dir / "x_daily" / "old.txt").exists()
+    assert (colonies_dir / "x_daily" / "new.txt").read_text() == "new"
+
+
+@pytest.mark.asyncio
+async def test_rejects_path_traversal(colonies_dir: Path) -> None:
+    archive = _build_tar(
+        {
+            "x_daily/": None,
+            "x_daily/../escape.txt": b"oops",
+        }
+    )
+    async with await _client(_app()) as c:
+        resp = await c.post("/api/colonies/import", data=_form(archive))
+        assert resp.status == 400
+        assert "traversal" in (await resp.json())["error"].lower() or "outside" in (await resp.json())["error"].lower()
+    assert not (colonies_dir / "x_daily").exists()
+    assert not (colonies_dir.parent / "escape.txt").exists()
+
+
+@pytest.mark.asyncio
+async def test_rejects_absolute_member(colonies_dir: Path) -> None:
+    archive = _build_tar({"x_daily/": None, "/etc/passwd": b"oops"})
+    async with await _client(_app()) as c:
+        resp = await c.post("/api/colonies/import", data=_form(archive))
+        assert resp.status == 400
+
+
+@pytest.mark.asyncio
+async def test_rejects_symlinks(colonies_dir: Path) -> None:
+    archive = _build_tar_with_symlink("x_daily", "evil", "/etc/passwd")
+    async with await _client(_app()) as c:
+        resp = await c.post("/api/colonies/import", data=_form(archive))
+        assert resp.status == 400
+        assert "symlink" in (await resp.json())["error"].lower()
+
+
+@pytest.mark.asyncio
+async def test_rejects_multiple_top_level_dirs(colonies_dir: Path) -> None:
+    archive = _build_tar(
+        {
+            "a/": None,
+            "a/x.txt": b"a",
+            "b/": None,
+            "b/y.txt": b"b",
+        }
+    )
+    async with await _client(_app()) as c:
+        resp = await c.post("/api/colonies/import", data=_form(archive))
+        assert resp.status == 400
+        assert "top-level" in (await resp.json())["error"].lower()
+
+
+@pytest.mark.asyncio
+async def test_rejects_invalid_colony_name(colonies_dir: Path) -> None:
+    archive = _build_tar({"Bad-Name/": None, "Bad-Name/x.txt": b"x"})
+    async with await _client(_app()) as c:
+        resp = await c.post("/api/colonies/import", data=_form(archive))
+        assert resp.status == 400
+
+
+@pytest.mark.asyncio
+async def test_rejects_non_multipart(colonies_dir: Path) -> None:
+    async with await _client(_app()) as c:
+        resp = await c.post(
+            "/api/colonies/import", data=b"not multipart", headers={"Content-Type": "application/octet-stream"}
+        )
+        assert resp.status == 400
+
+
+@pytest.mark.asyncio
+async def test_rejects_corrupt_tar(colonies_dir: Path) -> None:
+    async with await _client(_app()) as c:
+        resp = await c.post("/api/colonies/import", data=_form(b"not a real tar"))
+        assert resp.status == 400
+
+
+@pytest.mark.asyncio
+async def test_rejects_missing_file_part(colonies_dir: Path) -> None:
+    fd = FormData()
+    fd.add_field("name", "anything")
+    async with await _client(_app()) as c:
+        resp = await c.post("/api/colonies/import", data=fd)
+        assert resp.status == 400
+
+
+@pytest.mark.asyncio
+async def test_accepts_uncompressed_tar(colonies_dir: Path) -> None:
+    archive = _build_tar({"x_daily/": None, "x_daily/file.txt": b"plain"}, gzip=False)
+    async with await _client(_app()) as c:
+        resp = await c.post(
+            "/api/colonies/import",
+            data=_form(archive, filename="colony.tar"),
+        )
+        assert resp.status == 201
+    assert (colonies_dir / "x_daily" / "file.txt").read_text() == "plain"
+
+
+# --------------------------------------------------------------------------
+# Multi-root tar tests — the desktop's pushColonyToWorkspace ships the colony
+# dir + worker conversations + the queen's forked session in one tar so the
+# queen has full context on resume. Each recognised top-level prefix unpacks
+# into its corresponding HIVE_HOME subtree.
+# --------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_multi_root_unpacks_three_subtrees(colonies_dir: Path) -> None:
+    archive = _build_tar(
+        {
+            "colonies/x_daily/": None,
+            "colonies/x_daily/metadata.json": b'{"queen_session_id":"session_x"}',
+            "colonies/x_daily/data/progress.db": b"sqlite",
+            "agents/x_daily/worker/": None,
+            "agents/x_daily/worker/conversations/": None,
+            "agents/x_daily/worker/conversations/0001.json": b'{"role":"user"}',
+            "agents/x_daily/worker/conversations/0002.json": b'{"role":"assistant"}',
+            "agents/queens/queen_alpha/sessions/session_x/": None,
+            "agents/queens/queen_alpha/sessions/session_x/queen.json": b'{"id":"x"}',
+        }
+    )
+    async with await _client(_app()) as c:
+        resp = await c.post("/api/colonies/import", data=_form(archive))
+        assert resp.status == 201, await resp.text()
+        body = await resp.json()
+    # Colony files
+    assert (colonies_dir / "x_daily" / "metadata.json").exists()
+    assert (colonies_dir / "x_daily" / "data" / "progress.db").exists()
+    # Worker conversations under HIVE_HOME/agents/<colony>/worker/
+    hive_home = colonies_dir.parent
+    assert (
+        hive_home / "agents" / "x_daily" / "worker" / "conversations" / "0001.json"
+    ).read_bytes() == b'{"role":"user"}'
+    # Queen forked session under HIVE_HOME/agents/queens/<queen>/sessions/<sid>/
+    assert (hive_home / "agents" / "queens" / "queen_alpha" / "sessions" / "session_x" / "queen.json").exists()
+    # Summary in response
+    assert body["name"] == "x_daily"
+    assert body["files_imported"] == 5
+    by_root = body["by_root"]
+    assert by_root["colonies"]["files"] == 2
+    assert by_root["agents_worker"]["files"] == 2
+    assert by_root["agents_queen"]["files"] == 1
+
+
+@pytest.mark.asyncio
+async def test_multi_root_colonies_only_succeeds(colonies_dir: Path) -> None:
+    """The agents/ subtrees are optional — a fresh colony has no history."""
+    archive = _build_tar(
+        {
+            "colonies/x_daily/": None,
+            "colonies/x_daily/metadata.json": b"{}",
+        }
+    )
+    async with await _client(_app()) as c:
+        resp = await c.post("/api/colonies/import", data=_form(archive))
+        assert resp.status == 201, await resp.text()
+        body = await resp.json()
+    assert body["files_imported"] == 1
+    assert (colonies_dir / "x_daily" / "metadata.json").read_bytes() == b"{}"
+
+
+@pytest.mark.asyncio
+async def test_multi_root_rejects_missing_colonies_root(colonies_dir: Path) -> None:
+    """Worker / queen trees alone aren't valid — every push must include
+    the colony dir, otherwise the desktop's intent is unclear and we
+    refuse rather than silently leave HIVE_HOME in a half-state."""
+    archive = _build_tar(
+        {
+            "agents/x_daily/worker/": None,
+            "agents/x_daily/worker/log.json": b"{}",
+        }
+    )
+    async with await _client(_app()) as c:
+        resp = await c.post("/api/colonies/import", data=_form(archive))
+        assert resp.status == 400, await resp.text()
+        err = (await resp.json())["error"]
+        assert "colonies/" in err
+
+
+@pytest.mark.asyncio
+async def test_multi_root_replace_existing_colony(colonies_dir: Path) -> None:
+    (colonies_dir / "x_daily").mkdir()
+    (colonies_dir / "x_daily" / "old.txt").write_text("preserved")
+    archive = _build_tar(
+        {
+            "colonies/x_daily/": None,
+            "colonies/x_daily/new.txt": b"new",
+        }
+    )
+    # Without flag → 409
+    async with await _client(_app()) as c:
+        resp = await c.post("/api/colonies/import", data=_form(archive))
+        assert resp.status == 409
+    assert (colonies_dir / "x_daily" / "old.txt").read_text() == "preserved"
+    # With flag → wipes + replaces
+    async with await _client(_app()) as c:
+        resp = await c.post(
+            "/api/colonies/import",
+            data=_form(archive, replace_existing="true"),
+        )
+        assert resp.status == 201, await resp.text()
+    assert not (colonies_dir / "x_daily" / "old.txt").exists()
+    assert (colonies_dir / "x_daily" / "new.txt").read_text() == "new"
+
+
+@pytest.mark.asyncio
+async def test_multi_root_rejects_traversal_in_worker_subtree(colonies_dir: Path) -> None:
+    archive = _build_tar(
+        {
+            "colonies/x_daily/": None,
+            "colonies/x_daily/m.json": b"{}",
+            "agents/x_daily/worker/": None,
+            "agents/x_daily/worker/../escape.txt": b"oops",
+        }
+    )
+    async with await _client(_app()) as c:
+        resp = await c.post("/api/colonies/import", data=_form(archive))
+        assert resp.status == 400
+    hive_home = colonies_dir.parent
+    assert not (hive_home / "agents" / "escape.txt").exists()
+
+
+@pytest.mark.asyncio
+async def test_multi_root_rejects_unknown_prefix(colonies_dir: Path) -> None:
+    archive = _build_tar(
+        {
+            "colonies/x_daily/": None,
+            "colonies/x_daily/m.json": b"{}",
+            "etc/passwd": b"oops",
+        }
+    )
+    async with await _client(_app()) as c:
+        resp = await c.post("/api/colonies/import", data=_form(archive))
+        # The unknown root is silently ignored (it doesn't match any
+        # recognised prefix); the colony root is required and present, so
+        # extraction succeeds and only the colonies subtree lands. We don't
+        # write outside HIVE_HOME because the dispatcher only routes to
+        # known destinations.
+        assert resp.status == 201, await resp.text()
+    hive_home = colonies_dir.parent
+    assert not (hive_home.parent / "etc" / "passwd").exists()
+    assert not (hive_home / "etc" / "passwd").exists()
+
+
+@pytest.mark.asyncio
+async def test_multi_root_rejects_invalid_segment(colonies_dir: Path) -> None:
+    archive = _build_tar(
+        {
+            "colonies/x_daily/": None,
+            "colonies/x_daily/m.json": b"{}",
+            "agents/queens/Bad-Queen/sessions/sess_1/": None,
+            "agents/queens/Bad-Queen/sessions/sess_1/x.json": b"{}",
+        }
+    )
+    async with await _client(_app()) as c:
+        resp = await c.post("/api/colonies/import", data=_form(archive))
+        assert resp.status == 400
+
+
+@pytest.mark.asyncio
+async def test_multi_root_overwrites_agents_subtree_in_place(colonies_dir: Path) -> None:
+    """Worker/queen subtrees are append-mostly stores — the import handler
+    extracts in place without an existence-conflict gate so the desktop can
+    re-push from another machine without explicit overwrite."""
+    hive_home = colonies_dir.parent
+    worker_dir = hive_home / "agents" / "x_daily" / "worker" / "conversations"
+    worker_dir.mkdir(parents=True)
+    (worker_dir / "0000_old.json").write_text("old")
+    archive = _build_tar(
+        {
+            "colonies/x_daily/": None,
+            "colonies/x_daily/m.json": b"{}",
+            "agents/x_daily/worker/": None,
+            "agents/x_daily/worker/conversations/": None,
+            "agents/x_daily/worker/conversations/0001_new.json": b"new",
+        }
+    )
+    async with await _client(_app()) as c:
+        resp = await c.post(
+            "/api/colonies/import",
+            data=_form(archive, replace_existing="true"),
+        )
+        assert resp.status == 201, await resp.text()
+    # Old conversation file untouched (extraction is additive on agents/),
+    # new one written.
+    assert (worker_dir / "0000_old.json").read_text() == "old"
+    assert (worker_dir / "0001_new.json").read_text() == "new"

core/framework/server/tests/test_colony_tools.py

@@ -0,0 +1,300 @@
+"""Tests for the per-colony MCP tool allowlist filter + routes.
+
+Covers:
+1. ``ColonyRuntime`` filter semantics (default-allow, allowlist, empty,
+   lifecycle passes through).
+2. routes_colony_tools round trip (GET/PATCH, validation, 404).
+3. Colony index route for the Tool Library picker.
+
+Routes never touch the real ``~/.hive/colonies`` tree — we redirect
+``COLONIES_DIR`` into ``tmp_path`` via monkeypatch.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import Any
+
+import pytest
+from aiohttp import web
+from aiohttp.test_utils import TestClient, TestServer
+
+from framework.host.colony_runtime import ColonyRuntime
+from framework.llm.provider import Tool
+from framework.server import routes_colony_tools
+
+
+def _tool(name: str) -> Tool:
+    return Tool(name=name, description=f"desc of {name}", parameters={"type": "object"})
+
+
+# ---------------------------------------------------------------------------
+# ColonyRuntime filter unit tests
+# ---------------------------------------------------------------------------
+
+
+def _bare_runtime() -> ColonyRuntime:
+    rt = ColonyRuntime.__new__(ColonyRuntime)
+    rt._enabled_mcp_tools = None
+    rt._mcp_tool_names_all = set()
+    return rt
+
+
+class TestColonyFilter:
+    def test_default_is_noop(self):
+        rt = _bare_runtime()
+        tools = [_tool("mcp_a"), _tool("lc_b")]
+        assert rt._apply_tool_allowlist(tools) == tools
+
+    def test_allowlist_gates_mcp_only(self):
+        rt = _bare_runtime()
+        rt._mcp_tool_names_all = {"mcp_a", "mcp_b"}
+        rt._enabled_mcp_tools = ["mcp_a"]
+        tools = [_tool("mcp_a"), _tool("mcp_b"), _tool("lc_c")]
+        names = [t.name for t in rt._apply_tool_allowlist(tools)]
+        assert names == ["mcp_a", "lc_c"]
+
+    def test_empty_allowlist_keeps_lifecycle(self):
+        rt = _bare_runtime()
+        rt._mcp_tool_names_all = {"mcp_a", "mcp_b"}
+        rt._enabled_mcp_tools = []
+        tools = [_tool("mcp_a"), _tool("mcp_b"), _tool("lc_c")]
+        names = [t.name for t in rt._apply_tool_allowlist(tools)]
+        assert names == ["lc_c"]
+
+    def test_setter_mutates_live_state(self):
+        rt = _bare_runtime()
+        rt.set_tool_allowlist(["x"], {"x", "y"})
+        assert rt._enabled_mcp_tools == ["x"]
+        assert rt._mcp_tool_names_all == {"x", "y"}
+
+        # Passing None on allowlist clears gating; mcp_tool_names_all
+        # defaults to "keep current" so a subsequent caller doesn't need
+        # to repeat the set.
+        rt.set_tool_allowlist(None)
+        assert rt._enabled_mcp_tools is None
+        assert rt._mcp_tool_names_all == {"x", "y"}
+
+
+# ---------------------------------------------------------------------------
+# Route round-trip tests
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class _FakeSession:
+    colony_name: str
+    colony: Any = None
+    colony_runtime: Any = None
+    id: str = "sess-1"
+
+
+@dataclass
+class _FakeManager:
+    _sessions: dict = field(default_factory=dict)
+    _mcp_tool_catalog: dict = field(default_factory=dict)
+
+
+@pytest.fixture
+def colony_dir(tmp_path, monkeypatch):
+    """Point COLONIES_DIR into a tmp tree and seed a colony."""
+    colonies = tmp_path / "colonies"
+    colonies.mkdir()
+    monkeypatch.setattr("framework.host.colony_metadata.COLONIES_DIR", colonies)
+    monkeypatch.setattr("framework.host.colony_tools_config.COLONIES_DIR", colonies)
+
+    name = "my_colony"
+    cdir = colonies / name
+    cdir.mkdir()
+    (cdir / "metadata.json").write_text(
+        json.dumps(
+            {
+                "colony_name": name,
+                "queen_name": "queen_technology",
+                "created_at": "2026-04-20T00:00:00+00:00",
+            }
+        )
+    )
+    return colonies, name
+
+
+async def _app(manager: _FakeManager) -> web.Application:
+    app = web.Application()
+    app["manager"] = manager
+    routes_colony_tools.register_routes(app)
+    return app
+
+
+@pytest.mark.asyncio
+async def test_get_tools_default_allow(colony_dir):
+    _, name = colony_dir
+    manager = _FakeManager(
+        _mcp_tool_catalog={
+            "files-tools": [
+                {"name": "read_file", "description": "read", "input_schema": {}},
+                {"name": "write_file", "description": "write", "input_schema": {}},
+            ],
+        }
+    )
+    app = await _app(manager)
+    async with TestClient(TestServer(app)) as client:
+        resp = await client.get(f"/api/colony/{name}/tools")
+        assert resp.status == 200
+        body = await resp.json()
+    assert body["enabled_mcp_tools"] is None
+    assert body["stale"] is False
+    tools = {t["name"]: t for t in body["mcp_servers"][0]["tools"]}
+    assert all(t["enabled"] for t in tools.values())
+
+
+@pytest.mark.asyncio
+async def test_patch_persists_and_validates(colony_dir):
+    colonies_dir, name = colony_dir
+    manager = _FakeManager(
+        _mcp_tool_catalog={
+            "files-tools": [
+                {"name": "read_file", "description": "", "input_schema": {}},
+                {"name": "write_file", "description": "", "input_schema": {}},
+            ]
+        }
+    )
+    app = await _app(manager)
+    tools_path = colonies_dir / name / "tools.json"
+    metadata_path = colonies_dir / name / "metadata.json"
+
+    async with TestClient(TestServer(app)) as client:
+        resp = await client.patch(f"/api/colony/{name}/tools", json={"enabled_mcp_tools": ["read_file"]})
+        assert resp.status == 200
+        body = await resp.json()
+        assert body["enabled_mcp_tools"] == ["read_file"]
+
+        # Persisted to tools.json; metadata.json does not carry the field.
+        sidecar = json.loads(tools_path.read_text())
+        assert sidecar["enabled_mcp_tools"] == ["read_file"]
+        assert "updated_at" in sidecar
+        meta = json.loads(metadata_path.read_text())
+        assert "enabled_mcp_tools" not in meta
+
+        # GET reflects the allowlist
+        resp = await client.get(f"/api/colony/{name}/tools")
+        body = await resp.json()
+        tools = {t["name"]: t for t in body["mcp_servers"][0]["tools"]}
+        assert tools["read_file"]["enabled"] is True
+        assert tools["write_file"]["enabled"] is False
+
+        # Unknown → 400
+        resp = await client.patch(f"/api/colony/{name}/tools", json={"enabled_mcp_tools": ["ghost"]})
+        assert resp.status == 400
+        assert "ghost" in (await resp.json()).get("unknown", [])
+
+
+@pytest.mark.asyncio
+async def test_patch_refreshes_live_runtime(colony_dir):
+    _, name = colony_dir
+
+    rt = _bare_runtime()
+    rt._mcp_tool_names_all = {"read_file", "write_file"}
+    rt.set_tool_allowlist(None)
+
+    session = _FakeSession(colony_name=name, colony=rt)
+    manager = _FakeManager(
+        _sessions={session.id: session},
+        _mcp_tool_catalog={
+            "files-tools": [
+                {"name": "read_file", "description": "", "input_schema": {}},
+                {"name": "write_file", "description": "", "input_schema": {}},
+            ]
+        },
+    )
+
+    app = await _app(manager)
+    async with TestClient(TestServer(app)) as client:
+        resp = await client.patch(f"/api/colony/{name}/tools", json={"enabled_mcp_tools": ["read_file"]})
+        assert resp.status == 200
+        body = await resp.json()
+        assert body["refreshed_runtimes"] == 1
+    assert rt._enabled_mcp_tools == ["read_file"]
+
+
+@pytest.mark.asyncio
+async def test_404_for_unknown_colony(colony_dir):
+    manager = _FakeManager()
+    app = await _app(manager)
+    async with TestClient(TestServer(app)) as client:
+        resp = await client.get("/api/colony/unknown/tools")
+        assert resp.status == 404
+        resp = await client.patch("/api/colony/unknown/tools", json={"enabled_mcp_tools": None})
+        assert resp.status == 404
+
+
+@pytest.mark.asyncio
+async def test_tools_index_lists_colonies(colony_dir):
+    _, name = colony_dir
+    manager = _FakeManager()
+    app = await _app(manager)
+    async with TestClient(TestServer(app)) as client:
+        resp = await client.get("/api/colonies/tools-index")
+        assert resp.status == 200
+        body = await resp.json()
+    entries = {c["name"]: c for c in body["colonies"]}
+    assert name in entries
+    assert entries[name]["queen_name"] == "queen_technology"
+    assert entries[name]["has_allowlist"] is False
+
+
+def test_queen_allowlist_inherits_into_new_colony(tmp_path, monkeypatch):
+    """A colony forked with a curated queen inherits her allowlist.
+
+    Exercises the inheritance hook in
+    ``routes_execution.fork_session_into_colony`` without running the
+    full fork machinery — we just call
+    ``update_colony_tools_config`` the same way the hook does and
+    assert the colony's ``tools.json`` matches the queen's live list.
+    """
+    colonies = tmp_path / "colonies"
+    colonies.mkdir()
+    monkeypatch.setattr("framework.host.colony_tools_config.COLONIES_DIR", colonies)
+
+    from framework.host.colony_tools_config import (
+        load_colony_tools_config,
+        update_colony_tools_config,
+    )
+
+    colony_name = "forked_child"
+    (colonies / colony_name).mkdir()
+
+    # Simulate: queen has a curated allowlist (e.g. role default resolved
+    # to a concrete list). The inheritance hook copies it verbatim.
+    queen_live_allowlist = ["read_file", "web_scrape", "csv_read"]
+    update_colony_tools_config(colony_name, list(queen_live_allowlist))
+
+    assert load_colony_tools_config(colony_name) == queen_live_allowlist
+
+
+def test_legacy_metadata_field_migrates_to_sidecar(colony_dir):
+    """A legacy enabled_mcp_tools field in metadata.json is hoisted to tools.json."""
+    colonies_dir, name = colony_dir
+    meta_path = colonies_dir / name / "metadata.json"
+    tools_path = colonies_dir / name / "tools.json"
+
+    # Seed legacy field in metadata.json.
+    meta = json.loads(meta_path.read_text())
+    meta["enabled_mcp_tools"] = ["read_file"]
+    meta_path.write_text(json.dumps(meta))
+
+    from framework.host.colony_tools_config import load_colony_tools_config
+
+    # First load migrates.
+    assert load_colony_tools_config(name) == ["read_file"]
+    assert tools_path.exists()
+    sidecar = json.loads(tools_path.read_text())
+    assert sidecar["enabled_mcp_tools"] == ["read_file"]
+
+    # metadata.json no longer contains the field; provenance fields preserved.
+    migrated = json.loads(meta_path.read_text())
+    assert "enabled_mcp_tools" not in migrated
+    assert migrated["queen_name"] == "queen_technology"
+
+    # Second load is a direct sidecar read.
+    assert load_colony_tools_config(name) == ["read_file"]

core/framework/server/tests/test_mcp_routes.py

@@ -0,0 +1,239 @@
+"""Tests for the MCP server CRUD HTTP routes.
+
+Monkey-patches ``MCPRegistry`` inside ``routes_mcp`` so the HTTP layer is
+exercised without reading or writing ``~/.hive/mcp_registry/installed.json``
+or spawning actual subprocesses.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pytest
+from aiohttp import web
+from aiohttp.test_utils import TestClient, TestServer
+
+from framework.loader.mcp_errors import MCPError, MCPErrorCode
+from framework.server import routes_mcp
+
+
+class _FakeRegistry:
+    """Stand-in for MCPRegistry — just enough surface for the routes."""
+
+    def __init__(self) -> None:
+        self._servers: dict[str, dict[str, Any]] = {
+            "built-in-seed": {
+                "source": "registry",
+                "transport": "stdio",
+                "enabled": True,
+                "manifest": {"description": "Factory-seeded server", "tools": []},
+                "last_health_status": "healthy",
+                "last_error": None,
+                "last_health_check_at": None,
+            }
+        }
+
+    def initialize(self) -> None:  # noqa: D401 — registry idempotent init
+        return
+
+    def list_installed(self) -> list[dict[str, Any]]:
+        return [{"name": name, **entry} for name, entry in self._servers.items()]
+
+    def get_server(self, name: str) -> dict | None:
+        if name not in self._servers:
+            return None
+        return {"name": name, **self._servers[name]}
+
+    def add_local(self, *, name: str, transport: str, **kwargs: Any) -> dict:
+        if name in self._servers:
+            raise MCPError(
+                code=MCPErrorCode.MCP_INSTALL_FAILED,
+                what=f"Server '{name}' already exists",
+                why="A server with this name is already registered locally.",
+                fix=f"Run: hive mcp remove {name}",
+            )
+        entry = {
+            "source": "local",
+            "transport": transport,
+            "enabled": True,
+            "manifest": {"description": kwargs.get("description") or ""},
+            "last_health_status": None,
+            "last_error": None,
+            "last_health_check_at": None,
+        }
+        self._servers[name] = entry
+        return entry
+
+    def remove(self, name: str) -> None:
+        if name not in self._servers:
+            raise MCPError(
+                code=MCPErrorCode.MCP_INSTALL_FAILED,
+                what=f"Cannot remove server '{name}'",
+                why="Server is not installed.",
+                fix="Run: hive mcp list",
+            )
+        del self._servers[name]
+
+    def enable(self, name: str) -> None:
+        if name not in self._servers:
+            raise MCPError(
+                code=MCPErrorCode.MCP_INSTALL_FAILED,
+                what="not found",
+                why="not found",
+                fix="x",
+            )
+        self._servers[name]["enabled"] = True
+
+    def disable(self, name: str) -> None:
+        if name not in self._servers:
+            raise MCPError(
+                code=MCPErrorCode.MCP_INSTALL_FAILED,
+                what="not found",
+                why="not found",
+                fix="x",
+            )
+        self._servers[name]["enabled"] = False
+
+    def health_check(self, name: str) -> dict[str, Any]:
+        if name not in self._servers:
+            raise MCPError(
+                code=MCPErrorCode.MCP_HEALTH_FAILED,
+                what="not found",
+                why="not found",
+                fix="x",
+            )
+        return {"name": name, "status": "healthy", "tools": 3, "error": None}
+
+
+@pytest.fixture
+def registry(monkeypatch):
+    reg = _FakeRegistry()
+    monkeypatch.setattr(routes_mcp, "_registry", lambda: reg)
+    return reg
+
+
+async def _make_app() -> web.Application:
+    app = web.Application()
+    routes_mcp.register_routes(app)
+    return app
+
+
+@pytest.mark.asyncio
+async def test_list_servers_returns_built_in(registry):
+    app = await _make_app()
+    async with TestClient(TestServer(app)) as client:
+        resp = await client.get("/api/mcp/servers")
+        assert resp.status == 200
+        body = await resp.json()
+    names = {s["name"] for s in body["servers"]}
+    # The registry fake carries one entry; the list also merges package-
+    # baked entries from core/framework/agents/queen/mcp_servers.json so
+    # the UI matches what the queen actually loads. Both should appear.
+    assert "built-in-seed" in names
+    sources = {s["name"]: s["source"] for s in body["servers"]}
+    assert sources.get("built-in-seed") == "registry"
+    # The package-baked servers (files-tools/gcu-tools/hive_tools) carry
+    # source=="built-in" and are non-removable.
+    pkg_entries = [s for s in body["servers"] if s["source"] == "built-in"]
+    assert pkg_entries, "expected at least one package-baked MCP server"
+    assert all(s.get("removable") is False for s in pkg_entries)
+
+
+@pytest.mark.asyncio
+async def test_add_local_server(registry):
+    app = await _make_app()
+    async with TestClient(TestServer(app)) as client:
+        resp = await client.post(
+            "/api/mcp/servers",
+            json={
+                "name": "my-tool",
+                "transport": "stdio",
+                "command": "echo",
+                "args": ["hi"],
+                "description": "says hi",
+            },
+        )
+        assert resp.status == 201
+        body = await resp.json()
+        assert body["server"]["name"] == "my-tool"
+        assert body["server"]["source"] == "local"
+
+        resp = await client.get("/api/mcp/servers")
+        names = [s["name"] for s in (await resp.json())["servers"]]
+    assert "my-tool" in names
+
+
+@pytest.mark.asyncio
+async def test_add_rejects_duplicate(registry):
+    app = await _make_app()
+    async with TestClient(TestServer(app)) as client:
+        for _ in range(2):
+            resp = await client.post(
+                "/api/mcp/servers",
+                json={"name": "dup", "transport": "stdio", "command": "x"},
+            )
+        assert resp.status == 409
+        body = await resp.json()
+        assert "already exists" in body["error"].lower()
+        assert body["fix"]
+
+
+@pytest.mark.asyncio
+async def test_add_rejects_invalid_transport(registry):
+    app = await _make_app()
+    async with TestClient(TestServer(app)) as client:
+        resp = await client.post(
+            "/api/mcp/servers",
+            json={"name": "x", "transport": "nope"},
+        )
+        assert resp.status == 400
+
+
+@pytest.mark.asyncio
+async def test_enable_disable_cycle(registry):
+    app = await _make_app()
+    # Seed a local server
+    registry.add_local(name="local-one", transport="stdio", command="x")
+
+    async with TestClient(TestServer(app)) as client:
+        resp = await client.post("/api/mcp/servers/local-one/disable")
+        assert resp.status == 200
+        assert (await resp.json())["enabled"] is False
+        assert registry._servers["local-one"]["enabled"] is False
+
+        resp = await client.post("/api/mcp/servers/local-one/enable")
+        assert resp.status == 200
+        assert (await resp.json())["enabled"] is True
+
+
+@pytest.mark.asyncio
+async def test_remove_local_only(registry):
+    app = await _make_app()
+    registry.add_local(name="local-two", transport="stdio", command="x")
+
+    async with TestClient(TestServer(app)) as client:
+        # Built-ins are protected
+        resp = await client.delete("/api/mcp/servers/built-in-seed")
+        assert resp.status == 400
+
+        # Missing
+        resp = await client.delete("/api/mcp/servers/ghost")
+        assert resp.status == 404
+
+        # Happy path
+        resp = await client.delete("/api/mcp/servers/local-two")
+        assert resp.status == 200
+        assert "local-two" not in registry._servers
+
+
+@pytest.mark.asyncio
+async def test_health_check(registry, monkeypatch):
+    app = await _make_app()
+    registry.add_local(name="pingable", transport="stdio", command="x")
+
+    async with TestClient(TestServer(app)) as client:
+        resp = await client.post("/api/mcp/servers/pingable/health")
+        assert resp.status == 200
+        body = await resp.json()
+    assert body["status"] == "healthy"
+    assert body["tools"] == 3

core/framework/server/tests/test_queen_tools.py

@@ -0,0 +1,486 @@
+"""Tests for the per-queen MCP tool allowlist filter + routes.
+
+Covers:
+1. QueenPhaseState filter semantics (default-allow, allowlist, empty, phase-
+   isolation, memo identity for LLM prompt-cache stability).
+2. routes_queen_tools round trip (GET, PATCH, validation, live-session
+   hot-reload).
+
+Route tests monkey-patch a tiny queen profile + manager catalog; they never
+spawn an MCP subprocess.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import Any
+from unittest.mock import MagicMock
+
+import pytest
+import yaml
+from aiohttp import web
+from aiohttp.test_utils import TestClient, TestServer
+
+from framework.llm.provider import Tool
+from framework.server import routes_queen_tools
+from framework.tools.queen_lifecycle_tools import QueenPhaseState
+
+# ---------------------------------------------------------------------------
+# QueenPhaseState filter — pure unit tests
+# ---------------------------------------------------------------------------
+
+
+def _tool(name: str) -> Tool:
+    return Tool(name=name, description=f"desc of {name}", parameters={"type": "object"})
+
+
+class TestPhaseStateFilter:
+    def test_default_allow_returns_every_tool(self):
+        ps = QueenPhaseState(phase="independent")
+        ps.independent_tools = [_tool("mcp_a"), _tool("mcp_b"), _tool("lc_c")]
+        ps.mcp_tool_names_all = {"mcp_a", "mcp_b"}
+        ps.enabled_mcp_tools = None
+        ps.rebuild_independent_filter()
+
+        names = [t.name for t in ps.get_current_tools()]
+        assert names == ["mcp_a", "mcp_b", "lc_c"]
+
+    def test_allowlist_keeps_listed_mcp_plus_all_lifecycle(self):
+        ps = QueenPhaseState(phase="independent")
+        ps.independent_tools = [_tool("mcp_a"), _tool("mcp_b"), _tool("lc_c")]
+        ps.mcp_tool_names_all = {"mcp_a", "mcp_b"}
+        ps.enabled_mcp_tools = ["mcp_a"]
+        ps.rebuild_independent_filter()
+
+        names = [t.name for t in ps.get_current_tools()]
+        assert names == ["mcp_a", "lc_c"]
+
+    def test_empty_allowlist_keeps_only_lifecycle(self):
+        ps = QueenPhaseState(phase="independent")
+        ps.independent_tools = [_tool("mcp_a"), _tool("mcp_b"), _tool("lc_c")]
+        ps.mcp_tool_names_all = {"mcp_a", "mcp_b"}
+        ps.enabled_mcp_tools = []
+        ps.rebuild_independent_filter()
+
+        names = [t.name for t in ps.get_current_tools()]
+        assert names == ["lc_c"]
+
+    def test_filter_isolated_to_independent_phase(self):
+        ps = QueenPhaseState(phase="independent")
+        ps.independent_tools = [_tool("mcp_a"), _tool("lc_c")]
+        ps.working_tools = [_tool("mcp_a"), _tool("lc_c")]
+        ps.mcp_tool_names_all = {"mcp_a"}
+        ps.enabled_mcp_tools = []
+        ps.rebuild_independent_filter()
+
+        # Independent → filtered
+        assert [t.name for t in ps.get_current_tools()] == ["lc_c"]
+
+        # Other phases → unaffected
+        ps.phase = "working"
+        assert [t.name for t in ps.get_current_tools()] == ["mcp_a", "lc_c"]
+
+    def test_memo_returns_stable_identity_for_prompt_cache(self):
+        """Same Python list object across turns → LLM prompt cache stays warm."""
+        ps = QueenPhaseState(phase="independent")
+        ps.independent_tools = [_tool("mcp_a"), _tool("lc_c")]
+        ps.mcp_tool_names_all = {"mcp_a"}
+        ps.enabled_mcp_tools = None
+        ps.rebuild_independent_filter()
+
+        first = ps.get_current_tools()
+        second = ps.get_current_tools()
+        assert first is second, "memoized list must be the same object across turns"
+
+        # A rebuild should produce a different object so downstream caches
+        # correctly invalidate.
+        ps.enabled_mcp_tools = ["mcp_a"]
+        ps.rebuild_independent_filter()
+        third = ps.get_current_tools()
+        assert third is not first
+        assert [t.name for t in third] == ["mcp_a", "lc_c"]
+
+
+# ---------------------------------------------------------------------------
+# Route round-trip tests
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class _FakeSession:
+    queen_name: str
+    phase_state: QueenPhaseState
+    colony_runtime: Any = None
+    id: str = "sess-1"
+    _queen_tool_registry: Any = None
+
+
+@dataclass
+class _FakeManager:
+    _sessions: dict = field(default_factory=dict)
+    _mcp_tool_catalog: dict = field(default_factory=dict)
+
+
+@pytest.fixture
+def queen_dir(tmp_path, monkeypatch):
+    """Redirect queen profile + tools storage into a tmp dir."""
+    queens_dir = tmp_path / "queens"
+    queens_dir.mkdir()
+    monkeypatch.setattr("framework.agents.queen.queen_profiles.QUEENS_DIR", queens_dir)
+    monkeypatch.setattr("framework.agents.queen.queen_tools_config.QUEENS_DIR", queens_dir)
+
+    queen_id = "queen_technology"
+    (queens_dir / queen_id).mkdir()
+    (queens_dir / queen_id / "profile.yaml").write_text(
+        yaml.safe_dump({"name": "Alexandra", "title": "Head of Technology"})
+    )
+    return queens_dir, queen_id
+
+
+async def _make_app(*, manager: _FakeManager) -> web.Application:
+    app = web.Application()
+    app["manager"] = manager
+    routes_queen_tools.register_routes(app)
+    return app
+
+
+@pytest.mark.asyncio
+async def test_get_tools_default_allows_everything_for_unknown_queen(queen_dir, monkeypatch):
+    """Queens NOT in the role-default table fall back to allow-all."""
+    monkeypatch.setattr(routes_queen_tools, "ensure_default_queens", lambda: None)
+
+    queens_dir, _ = queen_dir
+    # Use a queen id that isn't in QUEEN_DEFAULT_CATEGORIES so we exercise
+    # the fallback-to-allow-all path.
+    custom_id = "queen_custom_unknown"
+    (queens_dir / custom_id).mkdir()
+    (queens_dir / custom_id / "profile.yaml").write_text(yaml.safe_dump({"name": "Custom", "title": "Custom Role"}))
+
+    manager = _FakeManager()
+    manager._mcp_tool_catalog = {
+        "files-tools": [
+            {"name": "read_file", "description": "read", "input_schema": {}},
+            {"name": "write_file", "description": "write", "input_schema": {}},
+        ],
+    }
+
+    app = await _make_app(manager=manager)
+    async with TestClient(TestServer(app)) as client:
+        resp = await client.get(f"/api/queen/{custom_id}/tools")
+        assert resp.status == 200
+        body = await resp.json()
+
+    assert body["enabled_mcp_tools"] is None
+    assert body["is_role_default"] is True  # no sidecar → default-allow
+    assert body["stale"] is False
+    servers = {s["name"]: s for s in body["mcp_servers"]}
+    assert set(servers) == {"files-tools"}
+    for tool in servers["files-tools"]["tools"]:
+        assert tool["enabled"] is True
+
+
+@pytest.mark.asyncio
+async def test_get_tools_applies_role_default(queen_dir, monkeypatch):
+    """Known persona queens get their role-based default allowlist."""
+    monkeypatch.setattr(routes_queen_tools, "ensure_default_queens", lambda: None)
+    _, queen_id = queen_dir  # queen_technology — has a role default
+
+    manager = _FakeManager()
+    # Seed two MCP servers: files-tools is referenced by the technology
+    # role via the @server:files-tools shorthand in `file_ops`, so its
+    # tools should bubble into the default. unrelated-server is NOT
+    # referenced by any role category — its tools must NOT leak in.
+    manager._mcp_tool_catalog = {
+        "files-tools": [
+            {"name": "read_file", "description": "", "input_schema": {}},
+            {"name": "edit_file", "description": "", "input_schema": {}},
+        ],
+        "unrelated-server": [
+            {"name": "fluffy_unknown_tool", "description": "", "input_schema": {}},
+        ],
+    }
+
+    app = await _make_app(manager=manager)
+    async with TestClient(TestServer(app)) as client:
+        resp = await client.get(f"/api/queen/{queen_id}/tools")
+        assert resp.status == 200
+        body = await resp.json()
+
+    assert body["is_role_default"] is True
+    enabled = set(body["enabled_mcp_tools"] or [])
+    # @server:files-tools shorthand pulls in every tool under that server.
+    assert "read_file" in enabled
+    assert "edit_file" in enabled
+    # Tools registered under a server the role doesn't reference are NOT
+    # part of the default.
+    assert "fluffy_unknown_tool" not in enabled
+
+
+@pytest.mark.asyncio
+async def test_get_tools_exposes_categories(queen_dir, monkeypatch):
+    """Response includes the category catalog with role-default flags."""
+    monkeypatch.setattr(routes_queen_tools, "ensure_default_queens", lambda: None)
+    _, queen_id = queen_dir  # queen_technology
+
+    manager = _FakeManager()
+    manager._mcp_tool_catalog = {
+        "files-tools": [
+            {"name": "read_file", "description": "", "input_schema": {}},
+            {"name": "edit_file", "description": "", "input_schema": {}},
+        ],
+    }
+
+    app = await _make_app(manager=manager)
+    async with TestClient(TestServer(app)) as client:
+        resp = await client.get(f"/api/queen/{queen_id}/tools")
+        assert resp.status == 200
+        body = await resp.json()
+
+    cats = {c["name"]: c for c in body["categories"]}
+    # Categories that contribute to queen_technology's role default
+    assert cats["file_ops"]["in_role_default"] is True
+    assert cats["browser_basic"]["in_role_default"] is True
+    # Spreadsheet category is exposed even though queen_technology doesn't
+    # use it — frontend can group/show it.
+    assert "spreadsheet_advanced" in cats
+    assert cats["spreadsheet_advanced"]["in_role_default"] is False
+    # Security was removed from queen_technology defaults.
+    assert cats["security"]["in_role_default"] is False
+    # @server:files-tools shorthand expanded against the catalog.
+    assert "read_file" in cats["file_ops"]["tools"]
+    assert "edit_file" in cats["file_ops"]["tools"]
+
+
+def test_resolve_queen_default_tools_expands_server_shorthand():
+    """@server:NAME shorthand expands against the provided catalog."""
+    from framework.agents.queen.queen_tools_defaults import resolve_queen_default_tools
+
+    catalog = {
+        "files-tools": [
+            {"name": "read_file"},
+            {"name": "write_file"},
+        ],
+    }
+    # queen_brand_design uses "file_ops" category → expands via @server:files-tools.
+    result = resolve_queen_default_tools("queen_brand_design", catalog)
+    assert result is not None
+    assert "read_file" in result
+    assert "write_file" in result
+
+
+def test_resolve_queen_default_tools_unknown_queen_returns_none():
+    from framework.agents.queen.queen_tools_defaults import resolve_queen_default_tools
+
+    assert resolve_queen_default_tools("queen_made_up", {}) is None
+
+
+@pytest.mark.asyncio
+async def test_patch_persists_and_validates(queen_dir, monkeypatch):
+    monkeypatch.setattr(routes_queen_tools, "ensure_default_queens", lambda: None)
+    queens_dir, queen_id = queen_dir
+
+    manager = _FakeManager()
+    manager._mcp_tool_catalog = {
+        "files-tools": [
+            {"name": "read_file", "description": "", "input_schema": {}},
+            {"name": "write_file", "description": "", "input_schema": {}},
+        ]
+    }
+
+    app = await _make_app(manager=manager)
+    tools_path = queens_dir / queen_id / "tools.json"
+    profile_path = queens_dir / queen_id / "profile.yaml"
+
+    async with TestClient(TestServer(app)) as client:
+        # Happy path
+        resp = await client.patch(
+            f"/api/queen/{queen_id}/tools",
+            json={"enabled_mcp_tools": ["read_file"]},
+        )
+        assert resp.status == 200
+        body = await resp.json()
+        assert body["enabled_mcp_tools"] == ["read_file"]
+
+        # Sidecar persisted; profile YAML untouched by tools PATCH
+        sidecar = json.loads(tools_path.read_text())
+        assert sidecar["enabled_mcp_tools"] == ["read_file"]
+        assert "updated_at" in sidecar
+        profile = yaml.safe_load(profile_path.read_text())
+        assert "enabled_mcp_tools" not in profile
+
+        # GET reflects the new state
+        resp = await client.get(f"/api/queen/{queen_id}/tools")
+        body = await resp.json()
+        assert body["is_role_default"] is False  # user has explicitly saved
+        servers = {t["name"]: t for t in body["mcp_servers"][0]["tools"]}
+        assert servers["read_file"]["enabled"] is True
+        assert servers["write_file"]["enabled"] is False
+
+        # Null resets
+        resp = await client.patch(f"/api/queen/{queen_id}/tools", json={"enabled_mcp_tools": None})
+        assert resp.status == 200
+        body = await resp.json()
+        assert body["enabled_mcp_tools"] is None
+        sidecar = json.loads(tools_path.read_text())
+        assert sidecar["enabled_mcp_tools"] is None
+
+        # Unknown tool name → 400; sidecar unchanged
+        resp = await client.patch(
+            f"/api/queen/{queen_id}/tools",
+            json={"enabled_mcp_tools": ["nope_not_a_tool"]},
+        )
+        assert resp.status == 400
+        detail = await resp.json()
+        assert "nope_not_a_tool" in detail.get("unknown", [])
+        sidecar = json.loads(tools_path.read_text())
+        assert sidecar["enabled_mcp_tools"] is None
+
+
+@pytest.mark.asyncio
+async def test_patch_hot_reloads_live_session(queen_dir, monkeypatch):
+    monkeypatch.setattr(routes_queen_tools, "ensure_default_queens", lambda: None)
+    _, queen_id = queen_dir
+
+    # Build a fake live session whose phase state carries a tool list the
+    # filter can gate. We also need a fake registry so
+    # _catalog_from_live_session can enumerate tools.
+    class _FakeRegistry:
+        def __init__(self, server_map, tools_by_name):
+            self._mcp_server_tools = server_map
+            self._tools_by_name = tools_by_name
+
+        def get_tools(self):
+            return {n: MagicMock(name=n) for n in self._tools_by_name}
+
+    tools_by_name = {"read_file": _tool("read_file"), "write_file": _tool("write_file")}
+    registry = _FakeRegistry(
+        server_map={"files-tools": {"read_file", "write_file"}},
+        tools_by_name=tools_by_name,
+    )
+    # Patch get_tools to return real Tool objects for name/description plumbing.
+    registry.get_tools = lambda: tools_by_name  # type: ignore[method-assign]
+
+    phase_state = QueenPhaseState(phase="independent")
+    phase_state.independent_tools = [tools_by_name["read_file"], tools_by_name["write_file"]]
+    phase_state.mcp_tool_names_all = {"read_file", "write_file"}
+    phase_state.enabled_mcp_tools = None
+    phase_state.rebuild_independent_filter()
+
+    session = _FakeSession(queen_name=queen_id, phase_state=phase_state)
+    session._queen_tool_registry = registry
+    manager = _FakeManager(_sessions={"sess-1": session})
+
+    app = await _make_app(manager=manager)
+    async with TestClient(TestServer(app)) as client:
+        resp = await client.patch(
+            f"/api/queen/{queen_id}/tools",
+            json={"enabled_mcp_tools": ["read_file"]},
+        )
+        assert resp.status == 200
+        body = await resp.json()
+        assert body["refreshed_sessions"] == 1
+
+    # Session's phase state reflects the new allowlist without a restart
+    current = phase_state.get_current_tools()
+    assert [t.name for t in current] == ["read_file"]
+
+
+@pytest.mark.asyncio
+async def test_missing_queen_returns_404(queen_dir, monkeypatch):
+    monkeypatch.setattr(routes_queen_tools, "ensure_default_queens", lambda: None)
+    manager = _FakeManager()
+
+    app = await _make_app(manager=manager)
+    async with TestClient(TestServer(app)) as client:
+        resp = await client.get("/api/queen/queen_nonexistent/tools")
+        assert resp.status == 404
+
+        resp = await client.patch(
+            "/api/queen/queen_nonexistent/tools",
+            json={"enabled_mcp_tools": None},
+        )
+        assert resp.status == 404
+
+
+@pytest.mark.asyncio
+async def test_delete_restores_role_default(queen_dir, monkeypatch):
+    """DELETE removes tools.json so the queen falls back to the role default."""
+    monkeypatch.setattr(routes_queen_tools, "ensure_default_queens", lambda: None)
+    queens_dir, queen_id = queen_dir
+    tools_path = queens_dir / queen_id / "tools.json"
+
+    manager = _FakeManager()
+    manager._mcp_tool_catalog = {
+        "files-tools": [
+            {"name": "read_file", "description": "", "input_schema": {}},
+            # pdf_read lives in hive_tools but is named explicitly in the
+            # file_ops category, so we stage it in any server here just to
+            # surface it through the catalog.
+            {"name": "pdf_read", "description": "", "input_schema": {}},
+        ],
+    }
+
+    app = await _make_app(manager=manager)
+    async with TestClient(TestServer(app)) as client:
+        # Seed a custom allowlist first so we have a sidecar to delete.
+        resp = await client.patch(
+            f"/api/queen/{queen_id}/tools",
+            json={"enabled_mcp_tools": ["read_file"]},
+        )
+        assert resp.status == 200
+        assert tools_path.exists()
+
+        resp = await client.delete(f"/api/queen/{queen_id}/tools")
+        assert resp.status == 200
+        body = await resp.json()
+        assert body["removed"] is True
+        assert body["is_role_default"] is True
+        assert not tools_path.exists()
+
+        # The new effective list is the role default for queen_technology;
+        # security tools were intentionally removed, so port_scan must NOT
+        # appear, while file_ops members like read_file/pdf_read do.
+        enabled = set(body["enabled_mcp_tools"] or [])
+        assert "read_file" in enabled
+        assert "pdf_read" in enabled
+        assert "port_scan" not in enabled
+        assert "subdomain_enumerate" not in enabled
+
+        # GET confirms.
+        resp = await client.get(f"/api/queen/{queen_id}/tools")
+        body = await resp.json()
+        assert body["is_role_default"] is True
+
+        # Deleting again is a no-op.
+        resp = await client.delete(f"/api/queen/{queen_id}/tools")
+        assert resp.status == 200
+        assert (await resp.json())["removed"] is False
+
+
+def test_legacy_profile_field_migrates_to_sidecar(queen_dir):
+    """A legacy enabled_mcp_tools field in profile.yaml is hoisted to tools.json."""
+    queens_dir, queen_id = queen_dir
+    profile_path = queens_dir / queen_id / "profile.yaml"
+    tools_path = queens_dir / queen_id / "tools.json"
+
+    # Seed legacy field in profile.yaml.
+    profile = yaml.safe_load(profile_path.read_text()) or {}
+    profile["enabled_mcp_tools"] = ["read_file", "write_file"]
+    profile_path.write_text(yaml.safe_dump(profile, sort_keys=False))
+
+    from framework.agents.queen.queen_tools_config import load_queen_tools_config
+
+    # First load migrates.
+    assert load_queen_tools_config(queen_id) == ["read_file", "write_file"]
+    assert tools_path.exists()
+    sidecar = json.loads(tools_path.read_text())
+    assert sidecar["enabled_mcp_tools"] == ["read_file", "write_file"]
+
+    # profile.yaml no longer contains the field; other fields preserved.
+    migrated_profile = yaml.safe_load(profile_path.read_text())
+    assert "enabled_mcp_tools" not in migrated_profile
+    assert migrated_profile["name"] == "Alexandra"
+
+    # Second load is a direct read — no migration work to do.
+    assert load_queen_tools_config(queen_id) == ["read_file", "write_file"]

core/framework/skills/_default_skills/colony-progress-tracker/SKILL.md

@@ -4,13 +4,14 @@ description: Claim tasks, record step progress, and verify SOP gates in the colo
 metadata:
   author: hive
   type: default-skill
+  visibility: [worker]
 ---
 
 ## Operational Protocol: Colony Progress Tracker
 
 **Applies when** your spawn message has `db_path:` and `colony_id:` fields. The DB is your durable working memory — tells you what's done, what to skip, which SOP gates you owe.
 
-Access via `execute_command_tool` running `sqlite3 "<db_path>" "..."`. Tables: `tasks` (queue), `steps` (per-task decomposition), `sop_checklist` (hard gates).
+Access via `terminal_exec` running `sqlite3 "<db_path>" "..."`. Tables: `tasks` (queue), `steps` (per-task decomposition), `sop_checklist` (hard gates).
 
 ### Claim: assigned task (check this FIRST)
 

core/framework/skills/_default_skills/context-preservation/SKILL.md

@@ -4,6 +4,7 @@ description: Proactively extract critical values from tool results into working
 metadata:
   author: hive
   type: default-skill
+  visibility: [worker]
 ---
 
 ## Operational Protocol: Context Preservation

core/framework/skills/_default_skills/error-recovery/SKILL.md

@@ -4,6 +4,7 @@ description: Follow a structured recovery decision tree when tool calls fail ins
 metadata:
   author: hive
   type: default-skill
+  visibility: [worker]
 ---
 
 ## Operational Protocol: Error Recovery

core/framework/skills/_default_skills/note-taking/SKILL.md

@@ -4,6 +4,7 @@ description: Maintain a free-form scratchpad of decisions, extracted values, and
 metadata:
   author: hive
   type: default-skill
+  visibility: [worker]
 ---
 
 ## Operational Protocol: Structured Note-Taking