Merge branch 'feature/colonized-memory' into refactor/automated-testing

feat: incubating phase
fix: scope conversation restore to current run_id
2026-04-03 14:43:41 -07:00 · 2026-04-03 14:43:05 -07:00 · 2026-04-03 13:42:13 -07:00 · 2026-04-03 13:03:47 -07:00 · 2026-04-03 13:00:49 -07:00 · 2026-04-03 12:38:05 -07:00
615 changed files with 90298 additions and 42281 deletions
@@ -0,0 +1,225 @@
+# Integration Test Reporting Skill
+
+Run the Level 2 dummy agent integration test suite and produce a detailed HTML report with per-test input → outcome analysis.
+
+## Trigger
+
+User wants to run integration tests and see results:
+- `/test-reporting`
+- `/test-reporting test_component_queen_live.py`
+- `/test-reporting --all`
+
+## SOP: Running Tests
+
+### Step 1: Select Scope
+
+If the user provides a specific test file or pattern, use it. Otherwise run the full suite.
+
+```bash
+# Full suite
+cd core && echo "1" | uv run python tests/dummy_agents/run_all.py --interactive 2>&1
+
+# Specific file (requires manual provider setup)
+cd core && uv run python -c "
+import sys
+sys.path.insert(0, '.')
+from tests.dummy_agents.run_all import detect_available
+from tests.dummy_agents.conftest import set_llm_selection
+
+avail = detect_available()
+claude = [p for p in avail if 'Claude Code' in p['name']]
+if not claude:
+    avail_names = [p['name'] for p in avail]
+    raise RuntimeError(f'No Claude Code subscription. Available: {avail_names}')
+provider = claude[0]
+set_llm_selection(
+    model=provider['model'],
+    api_key=provider['api_key'],
+    extra_headers=provider.get('extra_headers'),
+    api_base=provider.get('api_base'),
+)
+
+import pytest
+sys.exit(pytest.main([
+    'tests/dummy_agents/TEST_FILE_HERE',
+    '-v', '--override-ini=asyncio_mode=auto', '--no-header', '--tb=long',
+    '--log-cli-level=WARNING', '--junitxml=/tmp/hive_test_results.xml',
+]))
+"
+```
+
+### Step 2: Collect Results
+
+After the test run completes, collect:
+1. **JUnit XML** from `--junitxml` output (if available)
+2. **stdout/stderr** from the run
+3. **Summary table** from `run_all.py` output (the Unicode table)
+
+### Step 3: Generate HTML Report
+
+Write the report to `/tmp/hive_integration_test_report.html`.
+
+The report MUST include these sections:
+
+#### Header
+- Run timestamp (ISO 8601)
+- Provider used (model name, source)
+- Total tests / passed / failed / skipped
+- Total wall-clock time
+- Overall verdict: PASS (all green) or FAIL (with count)
+
+#### Per-Test Table
+
+For EVERY test (not just failures), include a row with:
+
+| Column | Description |
+|--------|-------------|
+| Component | Test file grouping (e.g., `component_queen_live`) |
+| Test Name | Function name (e.g., `test_queen_starts_in_planning_without_worker`) |
+| Status | PASS / FAIL / SKIP / ERROR with color badge |
+| Duration | Wall-clock seconds |
+| What | One-line description of what the test verifies |
+| How | How it works (setup → action → assertion) |
+| Why | Why this test matters (what bug/behavior it catches) |
+| Input | The input data or configuration (graph spec, initial prompt, phase, etc.) |
+| Expected Outcome | What the test asserts |
+| Actual Outcome | What actually happened (PASS: matches expected / FAIL: actual vs expected) |
+| Failure Detail | For failures only: full traceback + diagnosis |
+
+#### What / How / Why Descriptions
+
+These MUST be derived from the test function's docstring and code. Read each test file to extract:
+- **What**: From the docstring first line
+- **How**: From the test body (what fixtures, what graph, what assertions)
+- **Why**: From the docstring body or "Why this matters" section in the test module
+
+Use these mappings for the component test files:
+
+```
+test_component_llm.py          → "LLM Provider" — streaming, tool calling, tokens
+test_component_tools.py        → "Tool Registry + MCP" — connection, execution
+test_component_event_loop.py   → "EventLoopNode" — iteration, output, stall
+test_component_edges.py        → "Edge Evaluation" — conditional, priority
+test_component_conversation.py → "Conversation Persistence" — storage, cursor
+test_component_escalation.py   → "Escalation Flow" — worker→queen signaling
+test_component_continuous.py   → "Continuous Mode" — conversation threading
+test_component_queen.py        → "Queen Phase (Unit)" — phase state, tools, events
+test_component_queen_live.py   → "Queen Phase (Live)" — real queen, real LLM
+test_component_queen_state_machine.py → "Queen State Machine" — edge cases, races
+test_component_worker_comms.py → "Worker Communication" — events, data flow
+test_component_strict_outcomes.py → "Strict Outcomes" — exact path, output, quality
+```
+
+#### HTML Template
+
+Use this structure:
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Hive Integration Test Report — {timestamp}</title>
+<style>
+  :root { --pass: #22c55e; --fail: #ef4444; --skip: #f59e0b; --bg: #0f172a; --surface: #1e293b; --text: #e2e8f0; --muted: #94a3b8; --border: #334155; }
+  * { box-sizing: border-box; margin: 0; padding: 0; }
+  body { font-family: 'SF Mono', 'Fira Code', monospace; background: var(--bg); color: var(--text); padding: 2rem; line-height: 1.6; }
+  h1, h2, h3 { font-weight: 600; }
+  h1 { font-size: 1.5rem; margin-bottom: 1rem; }
+  h2 { font-size: 1.2rem; margin: 2rem 0 1rem; border-bottom: 1px solid var(--border); padding-bottom: 0.5rem; }
+  .summary { display: grid; grid-template-columns: repeat(auto-fit, minmax(150px, 1fr)); gap: 1rem; margin-bottom: 2rem; }
+  .card { background: var(--surface); padding: 1rem; border-radius: 8px; border: 1px solid var(--border); }
+  .card .label { color: var(--muted); font-size: 0.75rem; text-transform: uppercase; }
+  .card .value { font-size: 1.5rem; font-weight: 700; margin-top: 0.25rem; }
+  .card .value.pass { color: var(--pass); }
+  .card .value.fail { color: var(--fail); }
+  table { width: 100%; border-collapse: collapse; font-size: 0.8rem; }
+  th { background: var(--surface); position: sticky; top: 0; text-align: left; padding: 0.5rem; border-bottom: 2px solid var(--border); color: var(--muted); text-transform: uppercase; font-size: 0.7rem; }
+  td { padding: 0.5rem; border-bottom: 1px solid var(--border); vertical-align: top; }
+  tr:hover { background: rgba(255,255,255,0.03); }
+  .badge { display: inline-block; padding: 2px 8px; border-radius: 4px; font-size: 0.7rem; font-weight: 700; }
+  .badge.pass { background: rgba(34,197,94,0.2); color: var(--pass); }
+  .badge.fail { background: rgba(239,68,68,0.2); color: var(--fail); }
+  .badge.skip { background: rgba(245,158,11,0.2); color: var(--skip); }
+  .detail { background: #1a1a2e; padding: 0.75rem; border-radius: 4px; margin-top: 0.5rem; font-size: 0.75rem; white-space: pre-wrap; overflow-x: auto; max-height: 200px; overflow-y: auto; }
+  .component-header { background: var(--surface); padding: 0.75rem 0.5rem; font-weight: 600; font-size: 0.85rem; }
+  .meta { color: var(--muted); font-size: 0.75rem; }
+</style>
+</head>
+<body>
+<h1>Hive Integration Test Report</h1>
+<p class="meta">Generated: {timestamp} | Provider: {provider} | Duration: {duration}s</p>
+
+<div class="summary">
+  <div class="card"><div class="label">Total</div><div class="value">{total}</div></div>
+  <div class="card"><div class="label">Passed</div><div class="value pass">{passed}</div></div>
+  <div class="card"><div class="label">Failed</div><div class="value fail">{failed}</div></div>
+  <div class="card"><div class="label">Verdict</div><div class="value {verdict_class}">{verdict}</div></div>
+</div>
+
+<h2>Test Results</h2>
+<table>
+<thead>
+<tr>
+  <th>Component</th>
+  <th>Test</th>
+  <th>Status</th>
+  <th>Time</th>
+  <th>What</th>
+  <th>Input → Expected → Actual</th>
+</tr>
+</thead>
+<tbody>
+<!-- For each test: -->
+<tr>
+  <td>{component}</td>
+  <td>{test_name}</td>
+  <td><span class="badge {status_class}">{status}</span></td>
+  <td>{duration}s</td>
+  <td>{what_description}</td>
+  <td>
+    <strong>Input:</strong> {input_description}<br>
+    <strong>Expected:</strong> {expected_outcome}<br>
+    <strong>Actual:</strong> {actual_outcome}
+    <!-- If failed: -->
+    <div class="detail">{failure_traceback}</div>
+  </td>
+</tr>
+</tbody>
+</table>
+
+<h2>Failure Analysis</h2>
+<!-- Only if there are failures -->
+<p>For each failure, provide:</p>
+<ul>
+  <li><strong>Root cause:</strong> Why it failed</li>
+  <li><strong>Impact:</strong> What this means for the system</li>
+  <li><strong>Suggested fix:</strong> How to address it</li>
+</ul>
+
+</body>
+</html>
+```
+
+### Step 4: Output
+
+1. Write the HTML file to `/tmp/hive_integration_test_report.html`
+2. Print the file path so the user can open it
+3. Print a concise summary to the terminal:
+   ```
+   Test Report: /tmp/hive_integration_test_report.html
+   Result: 74/76 PASSED (2 failures)
+   Failures:
+     - parallel_merge::test_parallel_disjoint_output_keys
+     - worker::test_worker_timestamped_note_artifact
+   ```
+
+## Key Rules
+
+1. ALWAYS use `--junitxml` when running pytest to get structured results
+2. ALWAYS read the test source files to populate What/How/Why columns — do not guess
+3. For Input/Expected/Actual, extract from the test's graph spec, assertions, and result
+4. Color-code everything: green for pass, red for fail, amber for skip
+5. Include the full traceback for failures in a scrollable `<div class="detail">`
+6. Group tests by component (file name) with a visual separator
+7. The report must be self-contained HTML (no external CSS/JS dependencies)
@@ -1,31 +0,0 @@
-name: Link Discord Account
-description: Connect your GitHub and Discord for the bounty program
-title: "link: @{{ github.actor }}"
-labels: ["link-discord"]
-body:
-  - type: markdown
-    attributes:
-      value: |
-        Link your Discord account to receive XP and role rewards when your bounty PRs are merged.
-
-        **How to find your Discord ID:**
-        1. Open Discord Settings > Advanced > Enable **Developer Mode**
-        2. Right-click your username > **Copy User ID**
-
-  - type: input
-    id: discord_id
-    attributes:
-      label: Discord User ID
-      description: "Your numeric Discord ID (not your username). Example: 123456789012345678"
-      placeholder: "123456789012345678"
-    validations:
-      required: true
-
-  - type: input
-    id: display_name
-    attributes:
-      label: Display Name (optional)
-      description: How you'd like to be credited
-      placeholder: "Jane Doe"
-    validations:
-      required: false
@@ -0,0 +1,78 @@
+name: Standard Bounty
+description: A bounty task for general framework contributions (not integration-specific)
+title: "[Bounty]: "
+labels: []
+body:
+  - type: markdown
+    attributes:
+      value: |
+        ## Standard Bounty
+
+        This issue is part of the [Bounty Program](../../docs/bounty-program/README.md).
+        **Claim this bounty** by commenting below — a maintainer will assign you within 24 hours.
+
+  - type: dropdown
+    id: bounty-size
+    attributes:
+      label: Bounty Size
+      options:
+        - "Small (10 pts)"
+        - "Medium (30 pts)"
+        - "Large (75 pts)"
+        - "Extreme (150 pts)"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: difficulty
+    attributes:
+      label: Difficulty
+      options:
+        - Easy
+        - Medium
+        - Hard
+    validations:
+      required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: What needs to be done to complete this bounty.
+      placeholder: |
+        Describe the specific task, including:
+        - What the contributor needs to do
+        - Links to relevant files in the repo
+        - Any context or motivation for the change
+    validations:
+      required: true
+
+  - type: textarea
+    id: acceptance-criteria
+    attributes:
+      label: Acceptance Criteria
+      description: What "done" looks like. The PR must meet all criteria.
+      placeholder: |
+        - [ ] Criterion 1
+        - [ ] Criterion 2
+        - [ ] CI passes
+    validations:
+      required: true
+
+  - type: textarea
+    id: relevant-files
+    attributes:
+      label: Relevant Files
+      description: Links to files or directories related to this bounty.
+      placeholder: |
+        - `path/to/file.py`
+        - `path/to/directory/`
+
+  - type: textarea
+    id: resources
+    attributes:
+      label: Resources
+      description: Links to docs, issues, or external references that will help.
+      placeholder: |
+        - Related issue: #XXXX
+        - Docs: https://...
@@ -2,14 +2,22 @@ name: Bounty completed
 description: Awards points and notifies Discord when a bounty PR is merged

 on:
-  pull_request:
+  pull_request_target:
    types: [closed]

+  workflow_dispatch:
+    inputs:
+      pr_number:
+        description: "PR number to process (for missed bounties)"
+        required: true
+        type: number
+
 jobs:
  bounty-notify:
    if: >
-      github.event.pull_request.merged == true &&
-      contains(join(github.event.pull_request.labels.*.name, ','), 'bounty:')
+      github.event_name == 'workflow_dispatch' ||
+      (github.event.pull_request.merged == true &&
+       contains(join(github.event.pull_request.labels.*.name, ','), 'bounty:'))
    runs-on: ubuntu-latest
    timeout-minutes: 5
    permissions:
@@ -32,6 +40,8 @@ jobs:
          GITHUB_REPOSITORY_OWNER: ${{ github.repository_owner }}
          GITHUB_REPOSITORY_NAME: ${{ github.event.repository.name }}
          DISCORD_WEBHOOK_URL: ${{ secrets.DISCORD_BOUNTY_WEBHOOK_URL }}
+          BOT_API_URL: ${{ secrets.BOT_API_URL }}
+          BOT_API_KEY: ${{ secrets.BOT_API_KEY }}
          LURKR_API_KEY: ${{ secrets.LURKR_API_KEY }}
          LURKR_GUILD_ID: ${{ secrets.LURKR_GUILD_ID }}
-          PR_NUMBER: ${{ github.event.pull_request.number }}
+          PR_NUMBER: ${{ inputs.pr_number || github.event.pull_request.number }}
@@ -5,7 +5,7 @@ on:
    branches: [main]
  pull_request:
    branches: [main]
-
+    
 concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true
@@ -24,6 +24,8 @@ jobs:

      - name: Install uv
        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true

      - name: Install dependencies
        run: uv sync --project core --group dev
@@ -54,10 +56,12 @@ jobs:

      - name: Install uv
        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true

      - name: Install dependencies and run tests
+        working-directory: core
        run: |
-          cd core
          uv sync
          uv run pytest tests/ -v

@@ -77,10 +81,12 @@ jobs:

      - name: Install uv
        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true

      - name: Install dependencies and run tests
+        working-directory: tools
        run: |
-          cd tools
          uv sync --extra dev
          uv run pytest tests/ -v

@@ -98,10 +104,12 @@ jobs:

      - name: Install uv
        uses: astral-sh/setup-uv@v4
-
+        with:
+          enable-cache: true
+            
      - name: Install dependencies
+        working-directory: core
        run: |
-          cd core
          uv sync

      - name: Validate exported agents
@@ -1,126 +0,0 @@
-name: Link Discord account
-description: Auto-creates a PR to add contributor to contributors.yml when a link-discord issue is opened
-
-on:
-  issues:
-    types: [opened]
-
-jobs:
-  link-discord:
-    if: contains(github.event.issue.labels.*.name, 'link-discord')
-    runs-on: ubuntu-latest
-    timeout-minutes: 2
-    permissions:
-      contents: write
-      issues: write
-      pull-requests: write
-
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-
-      - name: Parse issue and update contributors.yml
-        uses: actions/github-script@v7
-        with:
-          script: |
-            const fs = require('fs');
-
-            const issue = context.payload.issue;
-            const githubUsername = issue.user.login;
-
-            // Parse the issue body for form fields
-            const body = issue.body || '';
-
-            // Extract Discord ID — look for the numeric value after the "Discord User ID" heading
-            const discordMatch = body.match(/### Discord User ID\s*\n\s*(\d{17,20})/);
-            if (!discordMatch) {
-              await github.rest.issues.createComment({
-                ...context.repo,
-                issue_number: issue.number,
-                body: `Could not find a valid Discord ID in the issue body. Please make sure you entered a numeric ID (17-20 digits), not a username.\n\nExample: \`123456789012345678\``
-              });
-              await github.rest.issues.update({
-                ...context.repo,
-                issue_number: issue.number,
-                state: 'closed',
-                state_reason: 'not_planned'
-              });
-              return;
-            }
-            const discordId = discordMatch[1];
-
-            // Extract display name (optional)
-            const nameMatch = body.match(/### Display Name \(optional\)\s*\n\s*(.+)/);
-            const displayName = nameMatch ? nameMatch[1].trim() : '';
-
-            // Check if user already exists
-            const yml = fs.readFileSync('contributors.yml', 'utf-8');
-            if (yml.includes(`github: ${githubUsername}`)) {
-              await github.rest.issues.createComment({
-                ...context.repo,
-                issue_number: issue.number,
-                body: `@${githubUsername} is already in \`contributors.yml\`. If you need to update your Discord ID, please edit the file directly via PR.`
-              });
-              await github.rest.issues.update({
-                ...context.repo,
-                issue_number: issue.number,
-                state: 'closed',
-                state_reason: 'completed'
-              });
-              return;
-            }
-
-            // Append entry to contributors.yml
-            let entry = `  - github: ${githubUsername}\n    discord: "${discordId}"`;
-            if (displayName && displayName !== '_No response_') {
-              entry += `\n    name: ${displayName}`;
-            }
-            entry += '\n';
-
-            const updated = yml.trimEnd() + '\n' + entry;
-            fs.writeFileSync('contributors.yml', updated);
-
-            // Set outputs for commit step
-            core.exportVariable('GITHUB_USERNAME', githubUsername);
-            core.exportVariable('DISCORD_ID', discordId);
-            core.exportVariable('ISSUE_NUMBER', issue.number.toString());
-
-      - name: Create PR
-        run: |
-          # Check if there are changes
-          if git diff --quiet contributors.yml; then
-            echo "No changes to contributors.yml"
-            exit 0
-          fi
-
-          BRANCH="docs/link-discord-${GITHUB_USERNAME}"
-          git config user.name "github-actions[bot]"
-          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
-          git checkout -b "$BRANCH"
-          git add contributors.yml
-          git commit -m "docs: link @${GITHUB_USERNAME} to Discord"
-          git push origin "$BRANCH"
-
-          gh pr create \
-            --title "docs: link @${GITHUB_USERNAME} to Discord" \
-            --body "Adds @${GITHUB_USERNAME} (Discord \`${DISCORD_ID}\`) to \`contributors.yml\` for bounty XP tracking.
-
-          Closes #${ISSUE_NUMBER}" \
-            --base main \
-            --head "$BRANCH" \
-            --label "link-discord"
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Notify on issue
-        uses: actions/github-script@v7
-        with:
-          script: |
-            const username = process.env.GITHUB_USERNAME;
-            const issueNumber = parseInt(process.env.ISSUE_NUMBER);
-
-            await github.rest.issues.createComment({
-              ...context.repo,
-              issue_number: issueNumber,
-              body: `A PR has been created to link your account. A maintainer will merge it shortly — once merged, you'll receive XP and Discord pings when your bounty PRs are merged.`
-            });
@@ -0,0 +1,54 @@
+# Closes PRs that still have the `pr-requirements-warning` label
+# after contributors were warned in pr-requirements.yml.
+name: PR Requirements Enforcement
+on:
+  schedule:
+    - cron: "0 0 * * *"   # runs every day once at midnight 
+jobs:
+  enforce:
+    name: Close PRs still failing contribution requirements
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+      issues: write
+    steps:
+      - name: Close PRs still failing requirements
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const { owner, repo } = context.repo;
+            const prs = await github.paginate(github.rest.pulls.list, {
+              owner,
+              repo,
+              state: "open",
+              per_page: 100
+            });
+            for (const pr of prs) {
+              // Skip draft PRs — author may still be actively working toward compliance
+              if (pr.draft) continue;
+              const labels = pr.labels.map(l => l.name);
+              if (!labels.includes("pr-requirements-warning")) continue;
+              const gracePeriod = 24 * 60 * 60 * 1000;
+              const lastUpdated = new Date(pr.created_at);
+              const now = new Date();
+              if (now - lastUpdated < gracePeriod) {
+                console.log(`Skipping PR #${pr.number} — still within grace period`);
+                continue;
+              }
+              const prNumber = pr.number;
+              const prAuthor = pr.user.login;
+              await github.rest.issues.createComment({
+                owner,
+                repo,
+                issue_number: prNumber,
+                body: `Closing PR because the contribution requirements were not resolved within the 24-hour grace period.
+                If this was closed in error, feel free to reopen the PR after fixing the requirements.`
+              });
+              await github.rest.pulls.update({
+                owner,
+                repo,
+                pull_number: prNumber,
+                state: "closed"
+              });
+              console.log(`Closed PR #${prNumber} by ${prAuthor} (PR requirements were not met)`);
+            }
@@ -43,9 +43,10 @@ jobs:
            console.log(`  Found issue references: ${issueNumbers.length > 0 ? issueNumbers.join(', ') : 'none'}`);

            if (issueNumbers.length === 0) {
-              const message = `## PR Closed - Requirements Not Met
+              const message = `## PR Requirements Warning

-            This PR has been automatically closed because it doesn't meet the requirements.
+            This PR does not meet the contribution requirements.
+            If the issue is not fixed within ~24 hours, it may be automatically closed.

            **Missing:** No linked issue found.

@@ -67,14 +68,15 @@ jobs:

            **Why is this required?** See #472 for details.`;

-              const comments = await github.rest.issues.listComments({
+              const comments = await github.paginate(github.rest.issues.listComments, {
                owner: context.repo.owner,
                repo: context.repo.repo,
                issue_number: prNumber,
+                per_page: 100,
              });

-              const botComment = comments.data.find(
-                (c) => c.user.type === 'Bot' && c.body.includes('PR Closed - Requirements Not Met')
+              const botComment = comments.find(
+                (c) => c.user.type === 'Bot' && c.body.includes('PR Requirements Warning')
              );

              if (!botComment) {
@@ -86,11 +88,11 @@ jobs:
                });
              }

-              await github.rest.pulls.update({
+              await github.rest.issues.addLabels({
                owner: context.repo.owner,
                repo: context.repo.repo,
-                pull_number: prNumber,
-                state: 'closed',
+                issue_number: prNumber,
+                labels: ['pr-requirements-warning'],
              });

              core.setFailed('PR must reference an issue');
@@ -132,9 +134,10 @@ jobs:
                `#${i.number} (assignees: ${i.assignees.length > 0 ? i.assignees.join(', ') : 'none'})`
              ).join(', ');

-              const message = `## PR Closed - Requirements Not Met
+              const message = `## PR Requirements Warning

-            This PR has been automatically closed because it doesn't meet the requirements.
+            This PR does not meet the contribution requirements.
+            If the issue is not fixed within ~24 hours, it may be automatically closed.

            **PR Author:** @${prAuthor}
            **Found issues:** ${issueList}
@@ -157,14 +160,15 @@ jobs:

            **Why is this required?** See #472 for details.`;

-              const comments = await github.rest.issues.listComments({
+              const comments = await github.paginate(github.rest.issues.listComments, {
                owner: context.repo.owner,
                repo: context.repo.repo,
                issue_number: prNumber,
+                per_page: 100,
              });

-              const botComment = comments.data.find(
-                (c) => c.user.type === 'Bot' && c.body.includes('PR Closed - Requirements Not Met')
+              const botComment = comments.find(
+                (c) => c.user.type === 'Bot' && c.body.includes('PR Requirements Warning')
              );

              if (!botComment) {
@@ -176,14 +180,24 @@ jobs:
                });
              }

-              await github.rest.pulls.update({
+              await github.rest.issues.addLabels({
                owner: context.repo.owner,
                repo: context.repo.repo,
-                pull_number: prNumber,
-                state: 'closed',
+                issue_number: prNumber,
+                labels: ['pr-requirements-warning'],
              });

              core.setFailed('PR author must be assigned to the linked issue');
            } else {
              console.log(`PR requirements met! Issue #${issueWithAuthorAssigned} has ${prAuthor} as assignee.`);
-            }
+              try {
+                await github.rest.issues.removeLabel({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  issue_number: prNumber,
+                  name: "pr-requirements-warning"
+                });
+              }catch (error){
+                //ignore if label doesn't exist
+              }
+            }
@@ -35,6 +35,8 @@ jobs:
          GITHUB_REPOSITORY_OWNER: ${{ github.repository_owner }}
          GITHUB_REPOSITORY_NAME: ${{ github.event.repository.name }}
          DISCORD_WEBHOOK_URL: ${{ secrets.DISCORD_BOUNTY_WEBHOOK_URL }}
+          BOT_API_URL: ${{ secrets.BOT_API_URL }}
+          BOT_API_KEY: ${{ secrets.BOT_API_KEY }}
          LURKR_API_KEY: ${{ secrets.LURKR_API_KEY }}
          LURKR_GUILD_ID: ${{ secrets.LURKR_GUILD_ID }}
          SINCE_DATE: ${{ github.event.inputs.since_date || '' }}
@@ -13,6 +13,10 @@ out/
 .env
 .env.local
 .env.*.local
+.venv
+/venv
+tools/src/uv.lock
+

 # User configuration (copied from .example)
 config.yaml
@@ -68,9 +72,6 @@ temp/
 exports/*

 .claude/settings.local.json
-.claude/skills/ship-it/
-
-.venv

 docs/github-issues/*
 core/tests/*dumps/*
@@ -2,10 +2,6 @@

 Shared agent instructions for this workspace.

-## Deprecations
-
- **TUI is deprecated.** The terminal UI (`hive tui`) is no longer maintained. Use the browser-based interface (`hive open`) instead.
-
 ## Coding Agent Notes

 - 
@@ -1,17 +1,149 @@
 # Release Notes

+## v0.7.1
+
+**Release Date:** March 13, 2026
+**Tag:** v0.7.1
+
+### Chrome-Native Browser Control
+
+v0.7.1 replaces Playwright with direct Chrome DevTools Protocol (CDP) integration. The GCU now launches the user's system Chrome via `open -n` on macOS, connects over CDP, and manages browser lifecycle end-to-end -- no extra browser binary required.
+
+---
+
+### Highlights
+
+#### System Chrome via CDP
+
+The entire GCU browser stack has been rewritten:
+
+- **Chrome finder & launcher** -- New `chrome_finder.py` discovers installed Chrome and `chrome_launcher.py` manages process lifecycle with `--remote-debugging-port`
+- **Coexist with user's browser** -- `open -n` on macOS launches a separate Chrome instance so the user's tabs stay untouched
+- **Dynamic viewport sizing** -- Viewport auto-sizes to the available display area, suppressing Chrome warning bars
+- **Orphan cleanup** -- Chrome processes are killed on GCU server shutdown to prevent leaks
+- **`--no-startup-window`** -- Chrome launches headlessly by default until a page is needed
+
+#### Per-Subagent Browser Isolation
+
+Each GCU subagent gets its own Chrome user-data directory, preventing cookie/session cross-contamination:
+
+- Unique browser profiles injected per subagent
+- Profiles cleaned up after top-level GCU node execution
+- Tab origin and age metadata tracked per subagent
+
+#### Dummy Agent Testing Framework
+
+A comprehensive test suite for validating agent graph patterns without LLM calls:
+
+- 8 test modules covering echo, pipeline, branch, parallel merge, retry, feedback loop, worker, and GCU subagent patterns
+- Shared fixtures and a `run_all.py` runner for CI integration
+- Subagent lifecycle tests
+
+---
+
+### What's New
+
+#### GCU Browser
+
+- **Switch from Playwright to system Chrome via CDP** -- Direct CDP connection replaces Playwright dependency. (@bryanadenhq)
+- **Chrome finder and launcher modules** -- `chrome_finder.py` and `chrome_launcher.py` for cross-platform Chrome discovery and process management. (@bryanadenhq)
+- **Dynamic viewport sizing** -- Auto-size viewport and suppress Chrome warning bar. (@bryanadenhq)
+- **Per-subagent browser profile isolation** -- Unique user-data directories per subagent with cleanup. (@bryanadenhq)
+- **Tab origin/age metadata** -- Track which subagent opened each tab and when. (@bryanadenhq)
+- **`browser_close_all` tool** -- Bulk tab cleanup for agents managing many pages. (@bryanadenhq)
+- **Auto-track popup pages** -- Popups are automatically captured and tracked. (@bryanadenhq)
+- **Auto-snapshot from browser interactions** -- Browser interaction tools return screenshots automatically. (@bryanadenhq)
+- **Kill orphaned Chrome processes** -- GCU server shutdown cleans up lingering Chrome instances. (@bryanadenhq)
+- **`--no-startup-window` Chrome flag** -- Prevent empty window on launch. (@bryanadenhq)
+- **Launch Chrome via `open -n` on macOS** -- Coexist with the user's running browser. (@bryanadenhq)
+
+#### Framework & Runtime
+
+- **Session resume fix for new agents** -- Correctly resume sessions when a new agent is loaded. (@bryanadenhq)
+- **Queen upsert fix** -- Prevent duplicate queen entries on session restore. (@bryanadenhq)
+- **Anchor worker monitoring to queen's session ID on cold-restore** -- Worker monitors reconnect to the correct queen after restart. (@bryanadenhq)
+- **Update meta.json when loading workers** -- Worker metadata stays in sync with runtime state. (@RichardTang-Aden)
+- **Generate worker MCP file correctly** -- Fix MCP config generation for spawned workers. (@RichardTang-Aden)
+- **Share event bus so tool events are visible to parent** -- Tool execution events propagate up to parent graphs. (@bryanadenhq)
+- **Subagent activity tracking in queen status** -- Queen instructions include live subagent status. (@bryanadenhq)
+- **GCU system prompt updates** -- Auto-snapshots, batching, popup tracking, and close_all guidance. (@bryanadenhq)
+
+#### Frontend
+
+- **Loading spinner in draft panel** -- Shows spinner during planning phase instead of blank panel. (@bryanadenhq)
+- **Fix credential modal errors** -- Modal no longer eats errors; banner stays visible. (@bryanadenhq)
+- **Fix credentials_required loop** -- Stop clearing the flag on modal close to prevent infinite re-prompting. (@bryanadenhq)
+- **Fix "Add tab" dropdown overflow** -- Dropdown no longer hidden when many agents are open. (@prasoonmhwr)
+
+#### Testing
+
+- **Dummy agent test framework** -- 8 test modules (echo, pipeline, branch, parallel merge, retry, feedback loop, worker, GCU subagent) with shared fixtures and CI runner. (@bryanadenhq)
+- **Subagent lifecycle tests** -- Validate subagent spawn and completion flows. (@bryanadenhq)
+
+#### Documentation & Infrastructure
+
+- **MCP integration PRD** -- Product requirements for MCP server registry. (@TimothyZhang7)
+- **Skills registry PRD** -- Product requirements for skill registry system. (@bryanadenhq)
+- **Bounty program updates** -- Standard bounty issue template and updated contributor guide. (@bryanadenhq)
+- **Windows quickstart** -- Add default context limit for PowerShell setup. (@bryanadenhq)
+- **Remove deprecated files** -- Clean up `setup_mcp.py`, `verify_mcp.py`, `antigravity-setup.md`, and `setup-antigravity-mcp.sh`. (@bryanadenhq)
+
+---
+
+### Bug Fixes
+
+- Fix credential modal eating errors and banner staying open
+- Stop clearing `credentials_required` on modal close to prevent infinite loop
+- Share event bus so tool events are visible to parent graph
+- Use lazy %-formatting in subagent completion log to avoid f-string in logger
+- Anchor worker monitoring to queen's session ID on cold-restore
+- Update meta.json when loading workers
+- Generate worker MCP file correctly
+- Fix "Add tab" dropdown partially hidden when creating multiple agents
+
+---
+
+### Community Contributors
+
+- **Prasoon Mahawar** (@prasoonmhwr) -- Fix UI overflow on agent tab dropdown
+- **Richard Tang** (@RichardTang-Aden) -- Worker MCP generation and meta.json fixes
+
+---
+
+### Upgrading
+
+```bash
+git pull origin main
+uv sync
+```
+
+The Playwright dependency is no longer required for GCU browser operations. Chrome must be installed on the host system.
+
+---
+
+## v0.7.0
+
+**Release Date:** March 5, 2026
+**Tag:** v0.7.0
+
+Session management refactor release.
+
+---
+
+## v0.5.1
+
 **Release Date:** February 18, 2026
 **Tag:** v0.5.1

-## The Hive Gets a Brain
+### The Hive Gets a Brain

 v0.5.1 is our most ambitious release yet. Hive agents can now **build other agents** -- the new Hive Coder meta-agent writes, tests, and fixes agent packages from natural language. The runtime grows multi-graph support so one session can orchestrate multiple agents simultaneously. The TUI gets a complete overhaul with an in-app agent picker, live streaming, and seamless escalation to the Coder. And we're now provider-agnostic: Claude Code subscriptions, OpenAI-compatible endpoints, and any LiteLLM-supported model work out of the box.

 ---

-## Highlights
+### Highlights

-### Hive Coder -- The Agent That Builds Agents
+#### Hive Coder -- The Agent That Builds Agents

 A native meta-agent that lives inside the framework at `core/framework/agents/hive_coder/`. Give it a natural-language specification and it produces a complete agent package -- goal definition, node prompts, edge routing, MCP tool wiring, tests, and all boilerplate files.

@@ -30,7 +162,7 @@ The Coder ships with:
 - **Coder Tools MCP server** -- file I/O, fuzzy-match editing, git snapshots, and sandboxed shell execution (`tools/coder_tools_server.py`)
 - **Test generation** -- structural tests for forever-alive agents that don't hang on `runner.run()`

-### Multi-Graph Agent Runtime
+#### Multi-Graph Agent Runtime

 `AgentRuntime` now supports loading, managing, and switching between multiple agent graphs within a single session. Six new lifecycle tools give agents (and the TUI) full control:

@@ -44,7 +176,7 @@ await runtime.add_graph("exports/deep_research_agent")

 The Hive Coder uses multi-graph internally -- when you escalate from a worker agent, the Coder loads as a separate graph while the worker stays alive in the background.

-### TUI Revamp
+#### TUI Revamp

 The Terminal UI gets a ground-up rebuild with five major additions:

@@ -54,7 +186,7 @@ The Terminal UI gets a ground-up rebuild with five major additions:
 - **PDF attachments** -- `/attach` and `/detach` commands with native OS file dialog (macOS, Linux, Windows)
 - **Multi-graph commands** -- `/graphs`, `/graph <id>`, `/load <path>`, `/unload <id>` for managing agent graphs in-session

-### Provider-Agnostic LLM Support
+#### Provider-Agnostic LLM Support

 Hive is no longer Anthropic-only. v0.5.1 adds first-class support for:

@@ -66,9 +198,9 @@ The quickstart script auto-detects Claude Code subscriptions and ZAI Code instal

 ---

-## What's New
+### What's New

-### Architecture & Runtime
+#### Architecture & Runtime

 - **Hive Coder meta-agent** -- Natural-language agent builder with reference docs, guardian watchdog, and `hive code` CLI command. (@TimothyZhang7)
 - **Multi-graph agent sessions** -- `add_graph`/`remove_graph` on AgentRuntime with 6 lifecycle tools (`load_agent`, `unload_agent`, `start_agent`, `restart_agent`, `list_agents`, `get_user_presence`). (@TimothyZhang7)
@@ -79,7 +211,7 @@ The quickstart script auto-detects Claude Code subscriptions and ZAI Code instal
 - **Pre-start confirmation prompt** -- Interactive prompt before agent execution allowing credential updates or abort. (@RichardTang-Aden)
 - **Event bus multi-graph support** -- `graph_id` on events, `filter_graph` on subscriptions, `ESCALATION_REQUESTED` event type, `exclude_own_graph` filter. (@TimothyZhang7)

-### TUI Improvements
+#### TUI Improvements

 - **In-app agent picker** (Ctrl+A) -- Tabbed modal for browsing agents with metadata badges (nodes, tools, sessions, tags). (@TimothyZhang7)
 - **Runtime-optional TUI startup** -- Launches without a pre-loaded agent, shows agent picker on startup. (@TimothyZhang7)
@@ -89,7 +221,7 @@ The quickstart script auto-detects Claude Code subscriptions and ZAI Code instal
 - **Multi-graph TUI commands** -- `/graphs`, `/graph <id>`, `/load <path>`, `/unload <id>`. (@TimothyZhang7)
 - **Agent Guardian watchdog** -- Event-driven monitor that catches secondary agent failures and triggers automatic remediation, with `--no-guardian` CLI flag. (@TimothyZhang7)

-### New Tool Integrations
+#### New Tool Integrations

 | Tool                   | Description                                                                                                                                                            | Contributor        |
 | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
@@ -99,7 +231,7 @@ The quickstart script auto-detects Claude Code subscriptions and ZAI Code instal
 | **Google Docs**        | Document creation, reading, and editing with OAuth credential support                                                                                                  | @haliaeetusvocifer |
 | **Gmail enhancements** | Expanded mail operations for inbox management                                                                                                                          | @bryanadenhq       |

-### Infrastructure
+#### Infrastructure

 - **Default node type → `event_loop`** -- `NodeSpec.node_type` defaults to `"event_loop"` instead of `"llm_tool_use"`. (@TimothyZhang7)
 - **Default `max_node_visits` → 0 (unlimited)** -- Nodes default to unlimited visits, reducing friction for feedback loops and forever-alive agents. (@TimothyZhang7)
@@ -112,7 +244,7 @@ The quickstart script auto-detects Claude Code subscriptions and ZAI Code instal

 ---

-## Bug Fixes
+### Bug Fixes

 - Flush WIP accumulator outputs on cancel/failure so edge conditions see correct values on resume
 - Stall detection state preserved across resume (no more resets on checkpoint restore)
@@ -125,13 +257,13 @@ The quickstart script auto-detects Claude Code subscriptions and ZAI Code instal
 - Fix email agent version conflicts (@RichardTang-Aden)
 - Fix coder tool timeouts (120s for tests, 300s cap for commands)

-## Documentation
+### Documentation

 - Clarify installation and prevent root pip install misuse (@paarths-collab)

 ---

-## Agent Updates
+### Agent Updates

 - **Email Inbox Management** -- Consolidate `gmail_inbox_guardian` and `inbox_management` into a single unified agent with updated prompts and config. (@RichardTang-Aden, @bryanadenhq)
 - **Job Hunter** -- Updated node prompts, config, and agent metadata; added PDF resume selection. (@bryanadenhq)
@@ -141,7 +273,7 @@ The quickstart script auto-detects Claude Code subscriptions and ZAI Code instal

 ---

-## Breaking Changes
+### Breaking Changes

 - **Deprecated node types raise `RuntimeError`** -- `llm_tool_use`, `llm_generate`, `function`, `router`, `human_input` now fail instead of warning. Migrate to `event_loop`.
 - **`NodeSpec.node_type` defaults to `"event_loop"`** (was `"llm_tool_use"`)
@@ -150,7 +282,7 @@ The quickstart script auto-detects Claude Code subscriptions and ZAI Code instal

 ---

-## Community Contributors
+### Community Contributors

 A huge thank you to everyone who contributed to this release:

@@ -165,14 +297,14 @@ A huge thank you to everyone who contributed to this release:

 ---

-## Upgrading
+### Upgrading

 ```bash
 git pull origin main
 uv sync
 ```

-### Migration Guide
+#### Migration Guide

 If your agents use deprecated node types, update them:

@@ -196,12 +328,3 @@ hive code
 # Or from TUI -- press Ctrl+E to escalate
 hive tui
 ```
-
---
-
-## What's Next
-
- **Agent-to-agent communication** -- one agent's output triggers another agent's entry point
- **Cost visibility** -- detailed runtime log of LLM costs per node and per session
- **Persistent webhook subscriptions** -- survive agent restarts without re-registering
- **Remote agent deployment** -- run agents as long-lived services with HTTP APIs
@@ -1,24 +1,31 @@
-.PHONY: lint format check test install-hooks help frontend-install frontend-dev frontend-build
+.PHONY: lint format check test test-tools test-live test-all install-hooks help frontend-install frontend-dev frontend-build
+
+# ── Ensure uv is findable in Git Bash on Windows ──────────────────────────────
+# uv installs to ~/.local/bin on Windows/Linux/macOS. Git Bash may not include
+# this in PATH by default, so we prepend it here.
+export PATH := $(HOME)/.local/bin:$(PATH)
+
+# ── Targets ───────────────────────────────────────────────────────────────────

 help: ## Show this help
 	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | \
 		awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-15s\033[0m %s\n", $$1, $$2}'

 lint: ## Run ruff linter and formatter (with auto-fix)
-	cd core && ruff check --fix .
-	cd tools && ruff check --fix .
-	cd core && ruff format .
-	cd tools && ruff format .
+	cd core && uv run ruff check --fix .
+	cd tools && uv run ruff check --fix .
+	cd core && uv run ruff format .
+	cd tools && uv run ruff format .

 format: ## Run ruff formatter
-	cd core && ruff format .
-	cd tools && ruff format .
+	cd core && uv run ruff format .
+	cd tools && uv run ruff format .

 check: ## Run all checks without modifying files (CI-safe)
-	cd core && ruff check .
-	cd tools && ruff check .
-	cd core && ruff format --check .
-	cd tools && ruff format --check .
+	cd core && uv run ruff check .
+	cd tools && uv run ruff check .
+	cd core && uv run ruff format --check .
+	cd tools && uv run ruff format --check .

 test: ## Run all tests (core + tools, excludes live)
 	cd core && uv run python -m pytest tests/ -v
@@ -46,4 +53,4 @@ frontend-dev: ## Start frontend dev server
 	cd core/frontend && npm run dev

 frontend-build: ## Build frontend for production
-	cd core/frontend && npm run build
+	cd core/frontend && npm run build
@@ -23,11 +23,12 @@
 </p>

 <p align="center">
+  <img src="https://img.shields.io/badge/Agent_Harness-Runtime_Layer-ff6600?style=flat-square" alt="Agent Harness" />
  <img src="https://img.shields.io/badge/AI_Agents-Self--Improving-brightgreen?style=flat-square" alt="AI Agents" />
  <img src="https://img.shields.io/badge/Multi--Agent-Systems-blue?style=flat-square" alt="Multi-Agent" />
  <img src="https://img.shields.io/badge/Headless-Development-purple?style=flat-square" alt="Headless" />
  <img src="https://img.shields.io/badge/Human--in--the--Loop-orange?style=flat-square" alt="HITL" />
-  <img src="https://img.shields.io/badge/Production--Ready-red?style=flat-square" alt="Production" />
+  <img src="https://img.shields.io/badge/Browser-Use-red?style=flat-square" alt="Browser Use" />
 </p>
 <p align="center">
  <img src="https://img.shields.io/badge/OpenAI-supported-412991?style=flat-square&logo=openai" alt="OpenAI" />
@@ -35,37 +36,42 @@
  <img src="https://img.shields.io/badge/Google_Gemini-supported-4285F4?style=flat-square&logo=google" alt="Gemini" />
 </p>

+<p align="center"><em>The agent harness for production workloads — state management, failure recovery, observability, and human oversight so your agents actually run.</em></p>
+
 ## Overview

-Build autonomous, reliable, self-improving AI agents without hardcoding workflows. Define your goal through conversation with hive coding agent(queen), and the framework generates a node graph with dynamically created connection code. When things break, the framework captures failure data, evolves the agent through the coding agent, and redeploys. Built-in human-in-the-loop nodes, credential management, and real-time monitoring give you control without sacrificing adaptability.
+Hive is a runtime harness for AI agents in production. You describe your goal in natural language; a coding agent (the queen) generates the agent graph and connection code to achieve it. During execution, the harness manages state isolation, checkpoint-based crash recovery, cost enforcement, and real-time observability. When agents fail, the framework captures failure data, evolves the graph through the coding agent, and redeploys automatically. Built-in human-in-the-loop nodes, browser control, credential management, and parallel execution give you production reliability without sacrificing adaptability.

 Visit [adenhq.com](https://adenhq.com) for complete documentation, examples, and guides.

-[![Hive Demo](https://img.youtube.com/vi/XDOG9fOaLjU/maxresdefault.jpg)](https://www.youtube.com/watch?v=XDOG9fOaLjU)
+Visit [HoneyComb](http://honeycomb.open-hive.com/) to see what jobs are being automated by AI. It’s a stock market for jobs, driven by our community’s AI agent progress. You can long and short jobs (with no real money but compute token)based on how much you think a job is going to be replaced by AI.
+
+https://github.com/user-attachments/assets/bf10edc3-06ba-48b6-98ba-d069b15fb69d
+

 ## Who Is Hive For?

-Hive is designed for developers and teams who want to build **production-grade AI agents** without manually wiring complex workflows.
+Hive is the harness layer for teams moving AI agents from prototype to production. Models are getting better on their own — the bottleneck is the infrastructure around them: state management, failure recovery, cost control, and observability.

 Hive is a good fit if you:

 - Want AI agents that **execute real business processes**, not demos
- Need **fast or high volume agent execution** over open workflow
+- Need a **runtime that handles state, recovery, and parallel execution** at scale
 - Need **self-healing and adaptive agents** that improve over time
 - Require **human-in-the-loop control**, observability, and cost limits
- Plan to run agents in **production environments**
+- Plan to run agents in **production** where uptime, cost, and auditability matter

 Hive may not be the best fit if you’re only experimenting with simple agent chains or one-off scripts.

 ## When Should You Use Hive?

-Use Hive when you need:
+Use Hive when the bottleneck is no longer the model but the harness around it:

- Long-running, autonomous agents
- Strong guardrails, process, and controls
- Continuous improvement based on failures
- Multi-agent coordination
- A framework that evolves with your goals
+- Long-running agents that need **state persistence and crash recovery**
+- Production workloads requiring **cost enforcement, observability, and audit trails**
+- Agents that **self-heal** through failure capture and graph evolution
+- Multi-agent coordination with **session isolation and shared buffers**
+- A framework that **scales with model improvements** rather than fighting them

 ## Quick Links

@@ -73,7 +79,7 @@ Use Hive when you need:
 - **[Self-Hosting Guide](https://docs.adenhq.com/getting-started/quickstart)** - Deploy Hive on your infrastructure
 - **[Changelog](https://github.com/aden-hive/hive/releases)** - Latest updates and releases
 - **[Roadmap](docs/roadmap.md)** - Upcoming features and plans
- **[Report Issues](https://github.com/adenhq/hive/issues)** - Bug reports and feature requests
+- **[Report Issues](https://github.com/aden-hive/hive/issues)** - Bug reports and feature requests
 - **[Contributing](CONTRIBUTING.md)** - How to contribute and submit PRs

 ## Quick Start
@@ -84,7 +90,7 @@ Use Hive when you need:
 - An LLM provider that powers the agents
 - **ripgrep (optional, recommended on Windows):** The `search_files` tool uses ripgrep for faster file search. If not installed, a Python fallback is used. On Windows: `winget install BurntSushi.ripgrep` or `scoop install ripgrep`

-> **Note for Windows Users:** It is strongly recommended to use **WSL (Windows Subsystem for Linux)** or **Git Bash** to run this framework. Some core automation scripts may not execute correctly in standard Command Prompt or PowerShell.
+> **Windows Users:** Native Windows is supported via `quickstart.ps1` and `hive.ps1`. Run these in PowerShell 5.1+. WSL is also an option but not required.

 ### Installation

@@ -98,9 +104,11 @@ Use Hive when you need:
 git clone https://github.com/aden-hive/hive.git
 cd hive

-
-# Run quickstart setup
+# Run quickstart setup (macOS/Linux)
 ./quickstart.sh
+
+# Windows (PowerShell)
+.\quickstart.ps1
 ```

 This sets up:
@@ -108,54 +116,51 @@ This sets up:
 - **framework** - Core agent runtime and graph executor (in `core/.venv`)
 - **aden_tools** - MCP tools for agent capabilities (in `tools/.venv`)
 - **credential store** - Encrypted API key storage (`~/.hive/credentials`)
- **LLM provider** - Interactive default model configuration
+- **LLM provider** - Interactive default model configuration, including Hive LLM and OpenRouter
 - All required Python dependencies with `uv`

- At last, it will initiate the open hive interface in your browser
+- Finally, it will open the Hive interface in your browser

 > **Tip:** To reopen the dashboard later, run `hive open` from the project directory.

-<img width="2500" height="1214" alt="home-screen" src="https://github.com/user-attachments/assets/134d897f-5e75-4874-b00b-e0505f6b45c4" />
-
 ### Build Your First Agent

-Type the agent you want to build in the home input box
+Type the agent you want to build in the home input box. The queen is going to ask you questions and work out a solution with you.

 <img width="2500" height="1214" alt="Image" src="https://github.com/user-attachments/assets/1ce19141-a78b-46f5-8d64-dbf987e048f4" />

 ### Use Template Agents

-Click "Try a sample agent" and check the templates. You can run a templates directly or choose to build your version on top of the existing template.
+Click "Try a sample agent" and check the templates. You can run a template directly or choose to build your version on top of the existing template.

 ### Run Agents

-Now you can run an agent by selectiing the agent (either an existing agent or example agent). You can click the Run button on the top left, or talk to the queen agent and it can run the agent for you.
+Now you can run an agent by selecting the agent (either an existing agent or example agent). You can click the Run button on the top left, or talk to the queen agent and it can run the agent for you.

-<img width="2500" height="1214" alt="Image" src="https://github.com/user-attachments/assets/71c38206-2ad5-49aa-bde8-6698d0bc55f5" />
+<img width="2549" height="1174" alt="Screenshot 2026-03-12 at 9 27 36 PM" src="https://github.com/user-attachments/assets/7c7d30fa-9ceb-4c23-95af-b1caa405547d" />

 ## Features

 - **Browser-Use** - Control the browser on your computer to achieve hard tasks
- **Parallel Execution** - Execute the generated graph in parallel. This way you can have multiple agent compelteing the jobs for you
+- **Parallel Execution** - Execute the generated graph in parallel. This way you can have multiple agents completing the jobs for you
 - **[Goal-Driven Generation](docs/key_concepts/goals_outcome.md)** - Define objectives in natural language; the coding agent generates the agent graph and connection code to achieve them
 - **[Adaptiveness](docs/key_concepts/evolution.md)** - Framework captures failures, calibrates according to the objectives, and evolves the agent graph
 - **[Dynamic Node Connections](docs/key_concepts/graph.md)** - No predefined edges; connection code is generated by any capable LLM based on your goals
- **SDK-Wrapped Nodes** - Every node gets shared memory, local RLM memory, monitoring, tools, and LLM access out of the box
+- **SDK-Wrapped Nodes** - Every node gets a shared data buffer, local RLM memory, monitoring, tools, and LLM access out of the box
 - **[Human-in-the-Loop](docs/key_concepts/graph.md#human-in-the-loop)** - Intervention nodes that pause execution for human input with configurable timeouts and escalation
 - **Real-time Observability** - WebSocket streaming for live monitoring of agent execution, decisions, and node-to-node communication
- **Production-Ready** - Self-hostable, built for scale and reliability

 ## Integration

 <a href="https://github.com/aden-hive/hive/tree/main/tools/src/aden_tools/tools"><img width="100%" alt="Integration" src="https://github.com/user-attachments/assets/a1573f93-cf02-4bb8-b3d5-b305b05b1e51" /></a>
 Hive is built to be model-agnostic and system-agnostic.

- **LLM flexibility** - Hive Framework is designed to support various types of LLMs, including hosted and local models through LiteLLM-compatible providers.
+- **LLM flexibility** - Hive Framework supports Anthropic, OpenAI, OpenRouter, Hive LLM, and other hosted or local models through LiteLLM-compatible providers.
 - **Business system connectivity** - Hive Framework is designed to connect to all kinds of business systems as tools, such as CRM, support, messaging, data, file, and internal APIs via MCP.

-## Why Aden
+## Why Hive

-Hive focuses on generating agents that run real business processes rather than generic agents. Instead of requiring you to manually design workflows, define agent interactions, and handle failures reactively, Hive flips the paradigm: **you describe outcomes, and the system builds itself**—delivering an outcome-driven, adaptive experience with an easy-to-use set of tools and integrations.
+As models improve, the upper bound of what agents can do rises — but their reliability and production value are determined by the harness. Hive focuses on generating agents that run real business processes rather than generic agents. Instead of requiring you to manually design workflows, define agent interactions, and handle failures reactively, Hive flips the paradigm: **you describe outcomes, and the system builds itself**—delivering an outcome-driven, adaptive experience with an easy-to-use set of tools and integrations.

 ```mermaid
 flowchart LR
@@ -191,8 +196,9 @@ flowchart LR

 ### The Hive Advantage

-| Traditional Frameworks     | Hive                                   |
+| Typical Agent Frameworks   | Hive                                   |
 | -------------------------- | -------------------------------------- |
+| Focus on model orchestration | **Production harness**: state, recovery, observability |
 | Hardcode agent workflows   | Describe goals in natural language     |
 | Manual graph definition    | Auto-generated agent graphs            |
 | Reactive error handling    | Outcome-evaluation and adaptiveness    |
@@ -378,7 +384,7 @@ This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENS

 **Q: What LLM providers does Hive support?**

-Hive supports 100+ LLM providers through LiteLLM integration, including OpenAI (GPT-4, GPT-4o), Anthropic (Claude models), Google Gemini, DeepSeek, Mistral, Groq, and many more. Simply set the appropriate API key environment variable and specify the model name. We recommend using Claude, GLM and Gemini as they have the best performance.
+Hive supports 100+ LLM providers through LiteLLM integration, including OpenAI (GPT-4, GPT-4o), Anthropic (Claude models), Google Gemini, DeepSeek, Mistral, Groq, OpenRouter, and Hive LLM. Simply set the appropriate API key environment variable and specify the model name. See [docs/configuration.md](docs/configuration.md) for provider-specific configuration examples.

 **Q: Can I use Hive with local AI models like Ollama?**

@@ -386,16 +392,12 @@ Yes! Hive supports local models through LiteLLM. Simply use the model name forma

 **Q: What makes Hive different from other agent frameworks?**

-Hive generates your entire agent system from natural language goals using a coding agent—you don't hardcode workflows or manually define graphs. When agents fail, the framework automatically captures failure data, [evolves the agent graph](docs/key_concepts/evolution.md), and redeploys. This self-improving loop is unique to Aden.
+Hive is an agent harness, not just an orchestration framework. It provides the production runtime layer — session isolation, checkpoint-based crash recovery, cost enforcement, real-time observability, and human-in-the-loop controls — that makes agents reliable enough to run real workloads. On top of that, Hive generates your entire agent system from natural language goals and automatically [evolves the graph](docs/key_concepts/evolution.md) when agents fail. The combination of a robust harness with self-improving generation is what sets Hive apart.

 **Q: Is Hive open-source?**

 Yes, Hive is fully open-source under the Apache License 2.0. We actively encourage community contributions and collaboration.

-**Q: Can Hive handle complex, production-scale use cases?**
-
-Yes. Hive is explicitly designed for production environments with features like automatic failure recovery, real-time observability, cost controls, and horizontal scaling support. The framework handles both simple automations and complex multi-agent workflows.
-
 **Q: Does Hive support human-in-the-loop workflows?**

 Yes, Hive fully supports [human-in-the-loop](docs/key_concepts/graph.md#human-in-the-loop) workflows through intervention nodes that pause execution for human input. These include configurable timeouts and escalation policies, allowing seamless collaboration between human experts and AI agents.
@@ -420,6 +422,16 @@ Visit [docs.adenhq.com](https://docs.adenhq.com/) for complete guides, API refer

 Contributions are welcome! Fork the repository, create your feature branch, implement your changes, and submit a pull request. See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.

+## Star History
+
+<a href="https://star-history.com/#aden-hive/hive&Date">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=aden-hive/hive&type=Date&theme=dark" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=aden-hive/hive&type=Date" />
+   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=aden-hive/hive&type=Date" />
+ </picture>
+</a>
+
 ---

 <p align="center">
@@ -39,8 +39,8 @@ We consider security research conducted in accordance with this policy to be:
 ## Security Best Practices for Users

 1. **Keep Updated**: Always run the latest version
-2. **Secure Configuration**: Review `config.yaml` settings, especially in production
-3. **Environment Variables**: Never commit `.env` files or `config.yaml` with secrets
+2. **Secure Configuration**: Review your `~/.hive/configuration.json`, `.mcp.json`, and environment variable settings, especially in production
+3. **Environment Variables**: Never commit `.env` files or any configuration files that contain secrets
 4. **Network Security**: Use HTTPS in production, configure firewalls appropriately
 5. **Database Security**: Use strong passwords, limit network access

@@ -1,31 +0,0 @@
-perf: reduce subprocess spawning in quickstart scripts (#4427)
-
-## Problem
-Windows process creation (CreateProcess) is 10-100x slower than Linux fork/exec.
-The quickstart scripts were spawning 4+ separate `uv run python -c "import X"` 
-processes to verify imports, adding ~600ms overhead on Windows.
-
-## Solution
-Consolidated all import checks into a single batch script that checks multiple 
-modules in one subprocess call, reducing spawn overhead by ~75%.
-
-## Changes
- **New**: `scripts/check_requirements.py` - Batched import checker
- **New**: `scripts/test_check_requirements.py` - Test suite  
- **New**: `scripts/benchmark_quickstart.ps1` - Performance benchmark tool
- **Modified**: `quickstart.ps1` - Updated import verification (2 sections)
- **Modified**: `quickstart.sh` - Updated import verification
-
-## Performance Impact
-**Benchmark results on Windows:**
- Before: ~19.8 seconds for import checks
- After: ~4.9 seconds for import checks
- **Improvement: 14.9 seconds saved (75.2% faster)**
-
-## Testing
- ✅ All functional tests pass (`scripts/test_check_requirements.py`)
- ✅ Quickstart scripts work correctly on Windows
- ✅ Error handling verified (invalid imports reported correctly)
- ✅ Performance benchmark confirms 75%+ improvement
-
-Fixes #4427
@@ -1,27 +0,0 @@
-# Identity mapping: GitHub username -> Discord ID
-#
-# This file links GitHub accounts to Discord accounts for the
-# Integration Bounty Program. When a bounty PR is merged, the
-# GitHub Action uses this file to ping the contributor on Discord.
-#
-# HOW TO ADD YOURSELF:
-# Open a "Link Discord Account" issue:
-# https://github.com/aden-hive/hive/issues/new?template=link-discord.yml
-# A GitHub Action will automatically add your entry here.
-#
-# To find your Discord ID:
-# 1. Open Discord Settings > Advanced > Enable Developer Mode
-# 2. Right-click your name > Copy User ID
-#
-# Format:
-#   - github: your-github-username
-#     discord: "your-discord-id"  # quotes required (it's a number)
-#     name: Your Display Name      # optional
-
-contributors:
-  # - github: example-user
-  #   discord: "123456789012345678"
-  #   name: Example User
-  - github: TimothyZhang7
-    discord: "408460790061072384"
-    name: Timothy@Aden
@@ -6,7 +6,7 @@ This guide explains how to integrate Model Context Protocol (MCP) servers with t

 The framework provides built-in support for MCP servers, allowing you to:

- **Register MCP servers** via STDIO or HTTP transport
+- **Register MCP servers** via STDIO, HTTP, Unix socket, or SSE transport
 - **Auto-discover tools** from registered servers
 - **Use MCP tools** seamlessly in your agents
 - **Manage multiple MCP servers** simultaneously
@@ -104,6 +104,48 @@ runner.register_mcp_server(
 - `url`: Base URL of the MCP server
 - `headers`: HTTP headers to include (optional)

+### Unix Socket Transport
+
+Best for same-host inter-process communication with lower overhead than TCP:
+
+```python
+runner.register_mcp_server(
+    name="local-ipc-tools",
+    transport="unix",
+    url="http://localhost",
+    socket_path="/tmp/mcp_server.sock",
+    headers={
+        "Authorization": "Bearer token"
+    }
+)
+```
+
+**Configuration:**
+
+- `url`: Base URL for HTTP requests over the socket (required, e.g., `"http://localhost"`)
+- `socket_path`: Absolute path to the Unix socket file (required, e.g., `"/tmp/mcp_server.sock"`)
+- `headers`: HTTP headers to include (optional)
+
+### SSE Transport
+
+Best for real-time, event-driven connections using the MCP SDK's SSE client:
+
+```python
+runner.register_mcp_server(
+    name="streaming-tools",
+    transport="sse",
+    url="http://localhost:8000/sse",
+    headers={
+        "Authorization": "Bearer token"
+    }
+)
+```
+
+**Configuration:**
+
+- `url`: SSE endpoint URL (required, e.g., `"http://localhost:8000/sse"`)
+- `headers`: HTTP headers for the SSE connection (optional)
+
 ## Using MCP Tools in Agents

 Once registered, MCP tools are available just like any other tool:
@@ -258,7 +300,32 @@ runner.register_mcp_server(
 )
 ```

-### 3. Handle Cleanup
+### 3. Use Unix Socket for Same-Host IPC
+
+When both the agent and MCP server run on the same machine, Unix sockets avoid TCP overhead:
+
+```python
+runner.register_mcp_server(
+    name="fast-local-tools",
+    transport="unix",
+    url="http://localhost",
+    socket_path="/tmp/mcp_server.sock"
+)
+```
+
+### 4. Use SSE for Streaming and Real-Time Tools
+
+SSE transport maintains a persistent connection, ideal for event-driven servers:
+
+```python
+runner.register_mcp_server(
+    name="realtime-tools",
+    transport="sse",
+    url="http://realtime-server:8000/sse"
+)
+```
+
+### 5. Handle Cleanup

 Always clean up MCP connections when done:

@@ -280,7 +347,7 @@ async with AgentRunner.load("exports/my-agent") as runner:
    # Automatic cleanup
 ```

-### 4. Tool Name Conflicts
+### 6. Tool Name Conflicts

 If multiple MCP servers provide tools with the same name, the last registered server wins. To avoid conflicts:

@@ -315,6 +382,24 @@ If HTTP transport fails:
 2. Check firewall settings
 3. Verify the URL and port are correct

+### Unix Socket Not Connecting
+
+If Unix socket transport fails:
+
+1. Verify the socket file exists: `ls -la /tmp/mcp_server.sock`
+2. Check file permissions on the socket
+3. Ensure no other process has locked the socket
+4. Verify the `url` field is set (e.g., `"http://localhost"`)
+
+### SSE Connection Issues
+
+If SSE transport fails:
+
+1. Verify the server supports SSE at the given URL
+2. Check that the `mcp` Python package is installed (`pip install mcp`)
+3. Ensure the SSE endpoint is accessible: `curl http://localhost:8000/sse`
+4. Check for firewall or proxy issues blocking long-lived connections
+
 ## Example: Full Agent with MCP Tools

 Here's a complete example of an agent that uses MCP tools:
@@ -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_agent_package` tool, with underlying logic in `framework.builder.package_generator`.
+> **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`.

 This guide covers the MCP tools available for building goal-driven agents.

@@ -19,7 +19,7 @@ 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_agent_package` tool and related utilities. The underlying package generation logic lives in `framework.builder.package_generator`.
+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.

@@ -0,0 +1,583 @@
+#!/usr/bin/env python3
+"""Antigravity authentication CLI.
+
+Implements OAuth2 flow for Google's Antigravity Code Assist gateway.
+Credentials are stored in ~/.hive/antigravity-accounts.json.
+
+Usage:
+    python -m antigravity_auth auth account add
+    python -m antigravity_auth auth account list
+    python -m antigravity_auth auth account remove <email>
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import os
+import secrets
+import socket
+import sys
+import time
+import urllib.parse
+import urllib.request
+import webbrowser
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from pathlib import Path
+from typing import Any
+
+logging.basicConfig(level=logging.INFO, format="%(message)s")
+logger = logging.getLogger(__name__)
+
+# OAuth endpoints
+_OAUTH_AUTH_URL = "https://accounts.google.com/o/oauth2/v2/auth"
+_OAUTH_TOKEN_URL = "https://oauth2.googleapis.com/token"
+
+# Scopes for Antigravity/Cloud Code Assist
+_OAUTH_SCOPES = [
+    "https://www.googleapis.com/auth/cloud-platform",
+    "https://www.googleapis.com/auth/userinfo.email",
+    "https://www.googleapis.com/auth/userinfo.profile",
+]
+
+# Credentials file path in ~/.hive/
+_ACCOUNTS_FILE = Path.home() / ".hive" / "antigravity-accounts.json"
+
+# Default project ID
+_DEFAULT_PROJECT_ID = "rising-fact-p41fc"
+_DEFAULT_REDIRECT_PORT = 51121
+
+# OAuth credentials fetched from the opencode-antigravity-auth project.
+# This project reverse-engineered and published the public OAuth credentials
+# for Google's Antigravity/Cloud Code Assist API.
+# Source: https://github.com/NoeFabris/opencode-antigravity-auth
+_CREDENTIALS_URL = (
+    "https://raw.githubusercontent.com/NoeFabris/opencode-antigravity-auth/dev/src/constants.ts"
+)
+
+# Cached credentials fetched from public source
+_cached_client_id: str | None = None
+_cached_client_secret: str | None = None
+
+
+def _fetch_credentials_from_public_source() -> tuple[str | None, str | None]:
+    """Fetch OAuth client ID and secret from the public npm package source on GitHub."""
+    global _cached_client_id, _cached_client_secret
+    if _cached_client_id and _cached_client_secret:
+        return _cached_client_id, _cached_client_secret
+
+    try:
+        req = urllib.request.Request(
+            _CREDENTIALS_URL, headers={"User-Agent": "Hive-Antigravity-Auth/1.0"}
+        )
+        with urllib.request.urlopen(req, timeout=10) as resp:
+            content = resp.read().decode("utf-8")
+            import re
+
+            id_match = re.search(r'ANTIGRAVITY_CLIENT_ID\s*=\s*"([^"]+)"', content)
+            secret_match = re.search(r'ANTIGRAVITY_CLIENT_SECRET\s*=\s*"([^"]+)"', content)
+            if id_match:
+                _cached_client_id = id_match.group(1)
+            if secret_match:
+                _cached_client_secret = secret_match.group(1)
+            return _cached_client_id, _cached_client_secret
+    except Exception as e:
+        logger.debug(f"Failed to fetch credentials from public source: {e}")
+    return None, None
+
+
+def get_client_id() -> str:
+    """Get OAuth client ID from env, config, or public source."""
+    env_id = os.environ.get("ANTIGRAVITY_CLIENT_ID")
+    if env_id:
+        return env_id
+
+    # Try hive config
+    hive_cfg = Path.home() / ".hive" / "configuration.json"
+    if hive_cfg.exists():
+        try:
+            with open(hive_cfg) as f:
+                cfg = json.load(f)
+                cfg_id = cfg.get("llm", {}).get("antigravity_client_id")
+                if cfg_id:
+                    return cfg_id
+        except Exception:
+            pass
+
+    # Fetch from public source
+    client_id, _ = _fetch_credentials_from_public_source()
+    if client_id:
+        return client_id
+
+    raise RuntimeError("Could not obtain Antigravity OAuth client ID")
+
+
+def get_client_secret() -> str | None:
+    """Get OAuth client secret from env, config, or public source."""
+    secret = os.environ.get("ANTIGRAVITY_CLIENT_SECRET")
+    if secret:
+        return secret
+
+    # Try to read from hive config
+    hive_cfg = Path.home() / ".hive" / "configuration.json"
+    if hive_cfg.exists():
+        try:
+            with open(hive_cfg) as f:
+                cfg = json.load(f)
+                secret = cfg.get("llm", {}).get("antigravity_client_secret")
+                if secret:
+                    return secret
+        except Exception:
+            pass
+
+    # Fetch from public source (npm package on GitHub)
+    _, secret = _fetch_credentials_from_public_source()
+    return secret
+
+
+def find_free_port() -> int:
+    """Find an available local port."""
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.bind(("", 0))
+        s.listen(1)
+        return s.getsockname()[1]
+
+
+class OAuthCallbackHandler(BaseHTTPRequestHandler):
+    """Handle OAuth callback from browser."""
+
+    auth_code: str | None = None
+    state: str | None = None
+    error: str | None = None
+
+    def log_message(self, format: str, *args: Any) -> None:
+        pass  # Suppress default logging
+
+    def do_GET(self) -> None:
+        parsed = urllib.parse.urlparse(self.path)
+
+        if parsed.path == "/oauth-callback":
+            query = urllib.parse.parse_qs(parsed.query)
+
+            if "error" in query:
+                self.error = query["error"][0]
+                self._send_response("Authentication failed. You can close this window.")
+                return
+
+            if "code" in query and "state" in query:
+                OAuthCallbackHandler.auth_code = query["code"][0]
+                OAuthCallbackHandler.state = query["state"][0]
+                self._send_response(
+                    "Authentication successful! You can close this window "
+                    "and return to the terminal."
+                )
+                return
+
+        self._send_response("Waiting for authentication...")
+
+    def _send_response(self, message: str) -> None:
+        self.send_response(200)
+        self.send_header("Content-Type", "text/html")
+        self.end_headers()
+        html = f"""<!DOCTYPE html>
+<html>
+<head><title>Antigravity Auth</title></head>
+<body style="font-family: system-ui; display: flex; align-items: center;
+      justify-content: center; height: 100vh; margin: 0; background: #1a1a2e;
+      color: #eee;">
+    <div style="text-align: center;">
+        <h2>{message}</h2>
+    </div>
+</body>
+</html>"""
+        self.wfile.write(html.encode())
+
+
+def wait_for_callback(port: int, timeout: int = 300) -> tuple[str | None, str | None, str | None]:
+    """Start local server and wait for OAuth callback."""
+    server = HTTPServer(("localhost", port), OAuthCallbackHandler)
+    server.timeout = 1
+
+    start = time.time()
+    while time.time() - start < timeout:
+        if OAuthCallbackHandler.auth_code:
+            return (
+                OAuthCallbackHandler.auth_code,
+                OAuthCallbackHandler.state,
+                OAuthCallbackHandler.error,
+            )
+        server.handle_request()
+
+    return None, None, "timeout"
+
+
+def exchange_code_for_tokens(
+    code: str, redirect_uri: str, client_id: str, client_secret: str | None
+) -> dict[str, Any] | None:
+    """Exchange authorization code for tokens."""
+    data = {
+        "code": code,
+        "client_id": client_id,
+        "redirect_uri": redirect_uri,
+        "grant_type": "authorization_code",
+    }
+    if client_secret:
+        data["client_secret"] = client_secret
+
+    body = urllib.parse.urlencode(data).encode()
+
+    req = urllib.request.Request(
+        _OAUTH_TOKEN_URL,
+        data=body,
+        headers={"Content-Type": "application/x-www-form-urlencoded"},
+        method="POST",
+    )
+
+    try:
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            return json.loads(resp.read())
+    except Exception as e:
+        logger.error(f"Token exchange failed: {e}")
+        return None
+
+
+def get_user_email(access_token: str) -> str | None:
+    """Get user email from Google API."""
+    req = urllib.request.Request(
+        "https://www.googleapis.com/oauth2/v2/userinfo",
+        headers={"Authorization": f"Bearer {access_token}"},
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=10) as resp:
+            data = json.loads(resp.read())
+            return data.get("email")
+    except Exception:
+        return None
+
+
+def load_accounts() -> dict[str, Any]:
+    """Load existing accounts from file."""
+    if not _ACCOUNTS_FILE.exists():
+        return {"schemaVersion": 4, "accounts": []}
+    try:
+        with open(_ACCOUNTS_FILE) as f:
+            return json.load(f)
+    except Exception:
+        return {"schemaVersion": 4, "accounts": []}
+
+
+def save_accounts(data: dict[str, Any]) -> None:
+    """Save accounts to file."""
+    _ACCOUNTS_FILE.parent.mkdir(parents=True, exist_ok=True)
+    with open(_ACCOUNTS_FILE, "w") as f:
+        json.dump(data, f, indent=2)
+    logger.info(f"Saved credentials to {_ACCOUNTS_FILE}")
+
+
+def validate_credentials(access_token: str, project_id: str = _DEFAULT_PROJECT_ID) -> bool:
+    """Test if credentials work by making a simple API call to Antigravity.
+
+    Returns True if credentials are valid, False otherwise.
+    """
+    endpoint = "https://daily-cloudcode-pa.sandbox.googleapis.com"
+    body = {
+        "project": project_id,
+        "model": "gemini-3-flash",
+        "request": {
+            "contents": [{"role": "user", "parts": [{"text": "hi"}]}],
+            "generationConfig": {"maxOutputTokens": 10},
+        },
+        "requestType": "agent",
+        "userAgent": "antigravity",
+        "requestId": "validation-test",
+    }
+    headers = {
+        "Authorization": f"Bearer {access_token}",
+        "Content-Type": "application/json",
+        "User-Agent": (
+            "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) "
+            "AppleWebKit/537.36 (KHTML, like Gecko) Antigravity/1.18.3"
+        ),
+        "X-Goog-Api-Client": "google-cloud-sdk vscode_cloudshelleditor/0.1",
+    }
+
+    try:
+        req = urllib.request.Request(
+            f"{endpoint}/v1internal:generateContent",
+            data=json.dumps(body).encode("utf-8"),
+            headers=headers,
+            method="POST",
+        )
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            json.loads(resp.read())
+            return True
+    except Exception:
+        return False
+
+
+def refresh_access_token(
+    refresh_token: str, client_id: str, client_secret: str | None
+) -> dict | None:
+    """Refresh the access token using the refresh token."""
+    data = {
+        "grant_type": "refresh_token",
+        "refresh_token": refresh_token,
+        "client_id": client_id,
+    }
+    if client_secret:
+        data["client_secret"] = client_secret
+
+    body = urllib.parse.urlencode(data).encode()
+    req = urllib.request.Request(
+        _OAUTH_TOKEN_URL,
+        data=body,
+        headers={"Content-Type": "application/x-www-form-urlencoded"},
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            return json.loads(resp.read())
+    except Exception as e:
+        logger.debug(f"Token refresh failed: {e}")
+        return None
+
+
+def cmd_account_add(args: argparse.Namespace) -> int:
+    """Add a new Antigravity account via OAuth2.
+
+    First checks if valid credentials already exist. If so, validates them
+    and skips OAuth if they work. Otherwise, proceeds with OAuth flow.
+    """
+    client_id = get_client_id()
+    client_secret = get_client_secret()
+
+    # Check if credentials already exist
+    accounts_data = load_accounts()
+    accounts = accounts_data.get("accounts", [])
+
+    if accounts:
+        account = next((a for a in accounts if a.get("enabled", True) is not False), accounts[0])
+        access_token = account.get("access")
+        refresh_token_str = account.get("refresh", "")
+        refresh_token = refresh_token_str.split("|")[0] if refresh_token_str else None
+        project_id = (
+            refresh_token_str.split("|")[1] if "|" in refresh_token_str else _DEFAULT_PROJECT_ID
+        )
+        email = account.get("email", "unknown")
+        expires_ms = account.get("expires", 0)
+        expires_at = expires_ms / 1000.0 if expires_ms else 0.0
+
+        # Check if token is expired or near expiry
+        if access_token and expires_at and time.time() < expires_at - 60:
+            # Token still valid, test it
+            logger.info(f"Found existing credentials for: {email}")
+            logger.info("Validating existing credentials...")
+            if validate_credentials(access_token, project_id):
+                logger.info("✓ Credentials valid! Skipping OAuth.")
+                return 0
+            else:
+                logger.info("Credentials failed validation, refreshing...")
+        elif refresh_token:
+            logger.info(f"Found expired credentials for: {email}")
+            logger.info("Attempting token refresh...")
+
+            tokens = refresh_access_token(refresh_token, client_id, client_secret)
+            if tokens:
+                new_access = tokens.get("access_token")
+                expires_in = tokens.get("expires_in", 3600)
+                if new_access:
+                    # Update the account
+                    account["access"] = new_access
+                    account["expires"] = int((time.time() + expires_in) * 1000)
+                    accounts_data["last_refresh"] = time.strftime(
+                        "%Y-%m-%dT%H:%M:%SZ", time.gmtime()
+                    )
+                    save_accounts(accounts_data)
+
+                    # Validate the refreshed token
+                    logger.info("Validating refreshed credentials...")
+                    if validate_credentials(new_access, project_id):
+                        logger.info("✓ Credentials refreshed and validated!")
+                        return 0
+                    else:
+                        logger.info("Refreshed token failed validation, proceeding with OAuth...")
+            else:
+                logger.info("Token refresh failed, proceeding with OAuth...")
+
+    # No valid credentials, proceed with OAuth
+    if not client_secret:
+        logger.warning(
+            "No client secret configured. Token refresh may fail.\n"
+            "Set ANTIGRAVITY_CLIENT_SECRET env var or add "
+            "'antigravity_client_secret' to ~/.hive/configuration.json"
+        )
+
+    # Use fixed port and path matching Google's expected OAuth redirect URI
+    port = _DEFAULT_REDIRECT_PORT
+    redirect_uri = f"http://localhost:{port}/oauth-callback"
+
+    # Generate state for CSRF protection
+    state = secrets.token_urlsafe(16)
+
+    # Build authorization URL
+    params = {
+        "client_id": client_id,
+        "redirect_uri": redirect_uri,
+        "response_type": "code",
+        "scope": " ".join(_OAUTH_SCOPES),
+        "state": state,
+        "access_type": "offline",
+        "prompt": "consent",
+    }
+    auth_url = f"{_OAUTH_AUTH_URL}?{urllib.parse.urlencode(params)}"
+
+    logger.info("Opening browser for authentication...")
+    logger.info(f"If the browser doesn't open, visit: {auth_url}\n")
+
+    # Open browser
+    webbrowser.open(auth_url)
+
+    # Wait for callback
+    logger.info(f"Listening for callback on port {port}...")
+    code, received_state, error = wait_for_callback(port)
+
+    if error:
+        logger.error(f"Authentication failed: {error}")
+        return 1
+
+    if not code:
+        logger.error("No authorization code received")
+        return 1
+
+    if received_state != state:
+        logger.error("State mismatch - possible CSRF attack")
+        return 1
+
+    # Exchange code for tokens
+    logger.info("Exchanging authorization code for tokens...")
+    tokens = exchange_code_for_tokens(code, redirect_uri, client_id, client_secret)
+
+    if not tokens:
+        return 1
+
+    access_token = tokens.get("access_token")
+    refresh_token = tokens.get("refresh_token")
+    expires_in = tokens.get("expires_in", 3600)
+
+    if not access_token:
+        logger.error("No access token in response")
+        return 1
+
+    # Get user email
+    email = get_user_email(access_token)
+    if email:
+        logger.info(f"Authenticated as: {email}")
+
+    # Load existing accounts and add/update
+    accounts_data = load_accounts()
+    accounts = accounts_data.get("accounts", [])
+
+    # Build new account entry (V4 schema)
+    expires_ms = int((time.time() + expires_in) * 1000)
+    refresh_entry = f"{refresh_token}|{_DEFAULT_PROJECT_ID}"
+
+    new_account = {
+        "access": access_token,
+        "refresh": refresh_entry,
+        "expires": expires_ms,
+        "email": email,
+        "enabled": True,
+    }
+
+    # Update existing account or add new one
+    existing_idx = next((i for i, a in enumerate(accounts) if a.get("email") == email), None)
+    if existing_idx is not None:
+        accounts[existing_idx] = new_account
+        logger.info(f"Updated existing account: {email}")
+    else:
+        accounts.append(new_account)
+        logger.info(f"Added new account: {email}")
+
+    accounts_data["accounts"] = accounts
+    accounts_data["schemaVersion"] = 4
+    accounts_data["last_refresh"] = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+
+    save_accounts(accounts_data)
+    logger.info("\n✓ Authentication complete!")
+    return 0
+
+
+def cmd_account_list(args: argparse.Namespace) -> int:
+    """List all stored accounts."""
+    data = load_accounts()
+    accounts = data.get("accounts", [])
+
+    if not accounts:
+        logger.info("No accounts configured.")
+        logger.info("Run 'antigravity auth account add' to add one.")
+        return 0
+
+    logger.info("Configured accounts:\n")
+    for i, account in enumerate(accounts, 1):
+        email = account.get("email", "unknown")
+        enabled = "enabled" if account.get("enabled", True) else "disabled"
+        logger.info(f"  {i}. {email} ({enabled})")
+
+    return 0
+
+
+def cmd_account_remove(args: argparse.Namespace) -> int:
+    """Remove an account by email."""
+    email = args.email
+    data = load_accounts()
+    accounts = data.get("accounts", [])
+
+    original_len = len(accounts)
+    accounts = [a for a in accounts if a.get("email") != email]
+
+    if len(accounts) == original_len:
+        logger.error(f"No account found with email: {email}")
+        return 1
+
+    data["accounts"] = accounts
+    save_accounts(data)
+    logger.info(f"Removed account: {email}")
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Antigravity authentication CLI",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    subparsers = parser.add_subparsers(dest="command", help="Commands")
+
+    # auth account add
+    auth_parser = subparsers.add_parser("auth", help="Authentication commands")
+    auth_subparsers = auth_parser.add_subparsers(dest="auth_command")
+
+    account_parser = auth_subparsers.add_parser("account", help="Account management")
+    account_subparsers = account_parser.add_subparsers(dest="account_command")
+
+    add_parser = account_subparsers.add_parser("add", help="Add a new account via OAuth2")
+    add_parser.set_defaults(func=cmd_account_add)
+
+    list_parser = account_subparsers.add_parser("list", help="List configured accounts")
+    list_parser.set_defaults(func=cmd_account_list)
+
+    remove_parser = account_subparsers.add_parser("remove", help="Remove an account")
+    remove_parser.add_argument("email", help="Email of account to remove")
+    remove_parser.set_defaults(func=cmd_account_remove)
+
+    args = parser.parse_args()
+
+    if hasattr(args, "func"):
+        return args.func(args)
+
+    parser.print_help()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
@@ -17,6 +17,7 @@ import http.server
 import json
 import os
 import platform
+import queue
 import secrets
 import subprocess
 import sys
@@ -27,6 +28,7 @@ import urllib.parse
 import urllib.request
 from datetime import UTC, datetime
 from pathlib import Path
+from typing import TextIO

 # OAuth constants (from the Codex CLI binary)
 CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann"
@@ -165,11 +167,11 @@ def open_browser(url: str) -> bool:
        if system == "Darwin":
            subprocess.Popen(["open", url], stdout=devnull, stderr=devnull)
        elif system == "Windows":
-            subprocess.Popen(["cmd", "/c", "start", url], stdout=devnull, stderr=devnull)
+            os.startfile(url)  # type: ignore[attr-defined]
        else:
            subprocess.Popen(["xdg-open", url], stdout=devnull, stderr=devnull)
        return True
-    except OSError:
+    except (AttributeError, OSError):
        return False


@@ -266,6 +268,71 @@ def parse_manual_input(value: str, expected_state: str) -> str | None:
    return None


+def _read_manual_input_lines(
+    manual_inputs: queue.Queue[str],
+    stop_event: threading.Event,
+    stdin: TextIO | None = None,
+) -> None:
+    stream = sys.stdin if stdin is None else stdin
+
+    while not stop_event.is_set():
+        try:
+            manual = stream.readline()
+        except (EOFError, OSError):
+            return
+
+        if not manual:
+            return
+
+        if manual.strip():
+            manual_inputs.put(manual)
+
+
+def wait_for_code_from_callback_or_stdin(
+    expected_state: str,
+    callback_result: list[str | None],
+    callback_done: threading.Event,
+    timeout_secs: float = 120,
+    poll_interval: float = 0.1,
+    stdin: TextIO | None = None,
+) -> str | None:
+    manual_inputs: queue.Queue[str] = queue.Queue()
+    stop_event = threading.Event()
+
+    # Read stdin on a daemon thread so manual paste works on platforms where
+    # select() cannot poll console handles, including Windows terminals.
+    threading.Thread(
+        target=_read_manual_input_lines,
+        args=(manual_inputs, stop_event, stdin),
+        daemon=True,
+    ).start()
+
+    deadline = time.time() + timeout_secs
+    try:
+        while time.time() < deadline:
+            if callback_result[0]:
+                return callback_result[0]
+
+            while True:
+                try:
+                    manual = manual_inputs.get_nowait()
+                except queue.Empty:
+                    break
+
+                code = parse_manual_input(manual, expected_state)
+                if code:
+                    return code
+
+            if callback_done.is_set():
+                return callback_result[0]
+
+            time.sleep(poll_interval)
+
+        return callback_result[0]
+    finally:
+        stop_event.set()
+
+
 def main() -> int:
    # Generate PKCE and state
    verifier, challenge = generate_pkce()
@@ -315,41 +382,28 @@ def main() -> int:

        # Start callback server in background
        callback_result: list[str | None] = [None]
+        callback_done = threading.Event()

        def run_server() -> None:
-            callback_result[0] = wait_for_callback(state, timeout_secs=120)
+            try:
+                callback_result[0] = wait_for_callback(state, timeout_secs=120)
+            finally:
+                callback_done.set()

        server_thread = threading.Thread(target=run_server)
        server_thread.daemon = True
        server_thread.start()

-        # Also accept manual input in parallel
-        # We poll for both the server result and stdin
        try:
-            import select
-
-            while server_thread.is_alive():
-                # Check if stdin has data (non-blocking on unix)
-                if hasattr(select, "select"):
-                    ready, _, _ = select.select([sys.stdin], [], [], 0.5)
-                    if ready:
-                        manual = sys.stdin.readline()
-                        if manual.strip():
-                            code = parse_manual_input(manual, state)
-                            if code:
-                                break
-                else:
-                    time.sleep(0.5)
-
-                if callback_result[0]:
-                    code = callback_result[0]
-                    break
-        except (KeyboardInterrupt, EOFError):
+            code = wait_for_code_from_callback_or_stdin(
+                state,
+                callback_result,
+                callback_done,
+                timeout_secs=120,
+            )
+        except KeyboardInterrupt:
            print("\n\033[0;31mCancelled.\033[0m")
            return 1
-
-        if not code:
-            code = callback_result[0]
    else:
        # Manual paste mode
        try:
@@ -1,740 +0,0 @@
-#!/usr/bin/env python3
-"""
-EventLoopNode WebSocket Demo
-
-Real LLM, real FileConversationStore, real EventBus.
-Streams EventLoopNode execution to a browser via WebSocket.
-
-Usage:
-    cd /home/timothy/oss/hive/core
-    python demos/event_loop_wss_demo.py
-
-    Then open http://localhost:8765 in your browser.
-"""
-
-import asyncio
-import json
-import logging
-import sys
-import tempfile
-from http import HTTPStatus
-from pathlib import Path
-
-import httpx
-import websockets
-from bs4 import BeautifulSoup
-from websockets.http11 import Request, Response
-
-# Add core, tools, and hive root to path
-_CORE_DIR = Path(__file__).resolve().parent.parent
-_HIVE_DIR = _CORE_DIR.parent
-sys.path.insert(0, str(_CORE_DIR))  # framework.*
-sys.path.insert(0, str(_HIVE_DIR / "tools" / "src"))  # aden_tools.*
-sys.path.insert(0, str(_HIVE_DIR))  # core.framework.* (for aden_tools imports)
-
-import os  # noqa: E402
-
-from aden_tools.credentials import CREDENTIAL_SPECS, CredentialStoreAdapter  # noqa: E402
-from core.framework.credentials import CredentialStore  # noqa: E402
-
-from framework.credentials.storage import (  # noqa: E402
-    CompositeStorage,
-    EncryptedFileStorage,
-    EnvVarStorage,
-)
-from framework.graph.event_loop_node import EventLoopNode, LoopConfig  # noqa: E402
-from framework.graph.node import NodeContext, NodeSpec, SharedMemory  # noqa: E402
-from framework.llm.litellm import LiteLLMProvider  # noqa: E402
-from framework.llm.provider import Tool  # noqa: E402
-from framework.runner.tool_registry import ToolRegistry  # noqa: E402
-from framework.runtime.core import Runtime  # noqa: E402
-from framework.runtime.event_bus import EventBus, EventType  # noqa: E402
-from framework.storage.conversation_store import FileConversationStore  # noqa: E402
-
-logging.basicConfig(level=logging.INFO, format="%(asctime)s %(name)s %(message)s")
-logger = logging.getLogger("demo")
-
-# -------------------------------------------------------------------------
-# Persistent state (shared across WebSocket connections)
-# -------------------------------------------------------------------------
-
-STORE_DIR = Path(tempfile.mkdtemp(prefix="hive_demo_"))
-STORE = FileConversationStore(STORE_DIR / "conversation")
-RUNTIME = Runtime(STORE_DIR / "runtime")
-LLM = LiteLLMProvider(model="claude-sonnet-4-5-20250929")
-
-# -------------------------------------------------------------------------
-# Tool Registry — real tools via ToolRegistry (same pattern as GraphExecutor)
-# -------------------------------------------------------------------------
-
-TOOL_REGISTRY = ToolRegistry()
-
-# Credential store: Aden sync (OAuth2 tokens) + encrypted files + env var fallback
-_env_mapping = {name: spec.env_var for name, spec in CREDENTIAL_SPECS.items()}
-_local_storage = CompositeStorage(
-    primary=EncryptedFileStorage(),
-    fallbacks=[EnvVarStorage(env_mapping=_env_mapping)],
-)
-
-if os.environ.get("ADEN_API_KEY"):
-    try:
-        from framework.credentials.aden import (  # noqa: E402
-            AdenCachedStorage,
-            AdenClientConfig,
-            AdenCredentialClient,
-            AdenSyncProvider,
-        )
-
-        _client = AdenCredentialClient(AdenClientConfig(base_url="https://api.adenhq.com"))
-        _provider = AdenSyncProvider(client=_client)
-        _storage = AdenCachedStorage(
-            local_storage=_local_storage,
-            aden_provider=_provider,
-        )
-        _cred_store = CredentialStore(storage=_storage, providers=[_provider], auto_refresh=True)
-        _synced = _provider.sync_all(_cred_store)
-        logger.info("Synced %d credentials from Aden", _synced)
-    except Exception as e:
-        logger.warning("Aden sync unavailable: %s", e)
-        _cred_store = CredentialStore(storage=_local_storage)
-else:
-    logger.info("ADEN_API_KEY not set, using local credential storage")
-    _cred_store = CredentialStore(storage=_local_storage)
-
-CREDENTIALS = CredentialStoreAdapter(_cred_store)
-
-# Debug: log which credentials resolved
-for _name in ["brave_search", "hubspot", "anthropic"]:
-    _val = CREDENTIALS.get(_name)
-    if _val:
-        logger.debug("credential %s: OK (len=%d)", _name, len(_val))
-    else:
-        logger.debug("credential %s: not found", _name)
-
-# --- web_search (Brave Search API) ---
-
-TOOL_REGISTRY.register(
-    name="web_search",
-    tool=Tool(
-        name="web_search",
-        description=(
-            "Search the web for current information. "
-            "Returns titles, URLs, and snippets from search results."
-        ),
-        parameters={
-            "type": "object",
-            "properties": {
-                "query": {
-                    "type": "string",
-                    "description": "The search query (1-500 characters)",
-                },
-                "num_results": {
-                    "type": "integer",
-                    "description": "Number of results to return (1-20, default 10)",
-                },
-            },
-            "required": ["query"],
-        },
-    ),
-    executor=lambda inputs: _exec_web_search(inputs),
-)
-
-
-def _exec_web_search(inputs: dict) -> dict:
-    api_key = CREDENTIALS.get("brave_search")
-    if not api_key:
-        return {"error": "brave_search credential not configured"}
-    query = inputs.get("query", "")
-    num_results = min(inputs.get("num_results", 10), 20)
-    resp = httpx.get(
-        "https://api.search.brave.com/res/v1/web/search",
-        params={"q": query, "count": num_results},
-        headers={"X-Subscription-Token": api_key, "Accept": "application/json"},
-        timeout=30.0,
-    )
-    if resp.status_code != 200:
-        return {"error": f"Brave API HTTP {resp.status_code}"}
-    data = resp.json()
-    results = [
-        {
-            "title": item.get("title", ""),
-            "url": item.get("url", ""),
-            "snippet": item.get("description", ""),
-        }
-        for item in data.get("web", {}).get("results", [])[:num_results]
-    ]
-    return {"query": query, "results": results, "total": len(results)}
-
-
-# --- web_scrape (httpx + BeautifulSoup, no playwright for sync compat) ---
-
-TOOL_REGISTRY.register(
-    name="web_scrape",
-    tool=Tool(
-        name="web_scrape",
-        description=(
-            "Scrape and extract text content from a webpage URL. "
-            "Returns the page title and main text content."
-        ),
-        parameters={
-            "type": "object",
-            "properties": {
-                "url": {
-                    "type": "string",
-                    "description": "URL of the webpage to scrape",
-                },
-                "max_length": {
-                    "type": "integer",
-                    "description": "Maximum text length (default 50000)",
-                },
-            },
-            "required": ["url"],
-        },
-    ),
-    executor=lambda inputs: _exec_web_scrape(inputs),
-)
-
-_SCRAPE_HEADERS = {
-    "User-Agent": (
-        "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
-        "AppleWebKit/537.36 (KHTML, like Gecko) "
-        "Chrome/131.0.0.0 Safari/537.36"
-    ),
-    "Accept": "text/html,application/xhtml+xml",
-}
-
-
-def _exec_web_scrape(inputs: dict) -> dict:
-    url = inputs.get("url", "")
-    max_length = max(1000, min(inputs.get("max_length", 50000), 500000))
-    if not url.startswith(("http://", "https://")):
-        url = "https://" + url
-    try:
-        resp = httpx.get(url, timeout=30.0, follow_redirects=True, headers=_SCRAPE_HEADERS)
-        if resp.status_code != 200:
-            return {"error": f"HTTP {resp.status_code}"}
-        soup = BeautifulSoup(resp.text, "html.parser")
-        for tag in soup(["script", "style", "nav", "footer", "header", "aside", "noscript"]):
-            tag.decompose()
-        title = soup.title.get_text(strip=True) if soup.title else ""
-        main = (
-            soup.find("article")
-            or soup.find("main")
-            or soup.find(attrs={"role": "main"})
-            or soup.find("body")
-        )
-        text = main.get_text(separator=" ", strip=True) if main else ""
-        text = " ".join(text.split())
-        if len(text) > max_length:
-            text = text[:max_length] + "..."
-        return {"url": url, "title": title, "content": text, "length": len(text)}
-    except httpx.TimeoutException:
-        return {"error": "Request timed out"}
-    except Exception as e:
-        return {"error": f"Scrape failed: {e}"}
-
-
-# --- HubSpot CRM tools (optional, requires HUBSPOT_ACCESS_TOKEN) ---
-
-_HUBSPOT_API = "https://api.hubapi.com"
-
-
-def _hubspot_headers() -> dict | None:
-    token = CREDENTIALS.get("hubspot")
-    if token:
-        logger.debug("HubSpot token: %s...%s (len=%d)", token[:8], token[-4:], len(token))
-    else:
-        logger.debug("HubSpot token: not found")
-    if not token:
-        return None
-    return {
-        "Authorization": f"Bearer {token}",
-        "Content-Type": "application/json",
-        "Accept": "application/json",
-    }
-
-
-def _exec_hubspot_search(inputs: dict) -> dict:
-    headers = _hubspot_headers()
-    if not headers:
-        return {"error": "HUBSPOT_ACCESS_TOKEN not set"}
-    object_type = inputs.get("object_type", "contacts")
-    query = inputs.get("query", "")
-    limit = min(inputs.get("limit", 10), 100)
-    body: dict = {"limit": limit}
-    if query:
-        body["query"] = query
-    try:
-        resp = httpx.post(
-            f"{_HUBSPOT_API}/crm/v3/objects/{object_type}/search",
-            headers=headers,
-            json=body,
-            timeout=30.0,
-        )
-        if resp.status_code != 200:
-            return {"error": f"HubSpot API HTTP {resp.status_code}: {resp.text[:200]}"}
-        return resp.json()
-    except httpx.TimeoutException:
-        return {"error": "Request timed out"}
-    except Exception as e:
-        return {"error": f"HubSpot error: {e}"}
-
-
-TOOL_REGISTRY.register(
-    name="hubspot_search",
-    tool=Tool(
-        name="hubspot_search",
-        description=(
-            "Search HubSpot CRM objects (contacts, companies, or deals). "
-            "Returns matching records with their properties."
-        ),
-        parameters={
-            "type": "object",
-            "properties": {
-                "object_type": {
-                    "type": "string",
-                    "description": "CRM object type: 'contacts', 'companies', or 'deals'",
-                },
-                "query": {
-                    "type": "string",
-                    "description": "Search query (name, email, domain, etc.)",
-                },
-                "limit": {
-                    "type": "integer",
-                    "description": "Max results (1-100, default 10)",
-                },
-            },
-            "required": ["object_type"],
-        },
-    ),
-    executor=lambda inputs: _exec_hubspot_search(inputs),
-)
-
-logger.info(
-    "ToolRegistry loaded: %s",
-    ", ".join(TOOL_REGISTRY.get_registered_names()),
-)
-
-
-# -------------------------------------------------------------------------
-# HTML page (embedded)
-# -------------------------------------------------------------------------
-
-HTML_PAGE = (  # noqa: E501
-    """<!DOCTYPE html>
-<html lang="en">
-<head>
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width, initial-scale=1">
-<title>EventLoopNode Live Demo</title>
-<style>
-  * { box-sizing: border-box; margin: 0; padding: 0; }
-  body {
-    font-family: 'SF Mono', 'Fira Code', monospace;
-    background: #0d1117; color: #c9d1d9;
-    height: 100vh; display: flex; flex-direction: column;
-  }
-  header {
-    background: #161b22; padding: 12px 20px;
-    border-bottom: 1px solid #30363d;
-    display: flex; align-items: center; gap: 16px;
-  }
-  header h1 { font-size: 16px; color: #58a6ff; font-weight: 600; }
-  .status {
-    font-size: 12px; padding: 3px 10px; border-radius: 12px;
-    background: #21262d; color: #8b949e;
-  }
-  .status.running { background: #1a4b2e; color: #3fb950; }
-  .status.done { background: #1a3a5c; color: #58a6ff; }
-  .status.error { background: #4b1a1a; color: #f85149; }
-  .chat { flex: 1; overflow-y: auto; padding: 16px; }
-  .msg {
-    margin: 8px 0; padding: 10px 14px; border-radius: 8px;
-    line-height: 1.6; white-space: pre-wrap; word-wrap: break-word;
-  }
-  .msg.user { background: #1a3a5c; color: #58a6ff; }
-  .msg.assistant { background: #161b22; color: #c9d1d9; }
-  .msg.event {
-    background: transparent; color: #8b949e; font-size: 11px;
-    padding: 4px 14px; border-left: 3px solid #30363d;
-  }
-  .msg.event.loop { border-left-color: #58a6ff; }
-  .msg.event.tool { border-left-color: #d29922; }
-  .msg.event.stall { border-left-color: #f85149; }
-  .input-bar {
-    padding: 12px 16px; background: #161b22;
-    border-top: 1px solid #30363d; display: flex; gap: 8px;
-  }
-  .input-bar input {
-    flex: 1; background: #0d1117; border: 1px solid #30363d;
-    color: #c9d1d9; padding: 8px 12px; border-radius: 6px;
-    font-family: inherit; font-size: 14px; outline: none;
-  }
-  .input-bar input:focus { border-color: #58a6ff; }
-  .input-bar button {
-    background: #238636; color: #fff; border: none;
-    padding: 8px 20px; border-radius: 6px; cursor: pointer;
-    font-family: inherit; font-weight: 600;
-  }
-  .input-bar button:hover { background: #2ea043; }
-  .input-bar button:disabled {
-    background: #21262d; color: #484f58; cursor: not-allowed;
-  }
-  .input-bar button.clear { background: #da3633; }
-  .input-bar button.clear:hover { background: #f85149; }
-</style>
-</head>
-<body>
-  <header>
-    <h1>EventLoopNode Live</h1>
-    <span id="status" class="status">Idle</span>
-    <span id="iter" class="status" style="display:none">Step 0</span>
-  </header>
-  <div id="chat" class="chat"></div>
-  <div class="input-bar">
-    <input id="input" type="text"
-           placeholder="Ask anything..." autofocus />
-    <button id="go" onclick="run()">Send</button>
-    <button class="clear"
-            onclick="clearConversation()">Clear</button>
-  </div>
-
-<script>
-let ws = null;
-let currentAssistantEl = null;
-let iterCount = 0;
-const chat = document.getElementById('chat');
-const status = document.getElementById('status');
-const iterEl = document.getElementById('iter');
-const goBtn = document.getElementById('go');
-const inputEl = document.getElementById('input');
-
-inputEl.addEventListener('keydown', e => {
-  if (e.key === 'Enter') run();
-});
-
-function setStatus(text, cls) {
-  status.textContent = text;
-  status.className = 'status ' + cls;
-}
-
-function addMsg(text, cls) {
-  const el = document.createElement('div');
-  el.className = 'msg ' + cls;
-  el.textContent = text;
-  chat.appendChild(el);
-  chat.scrollTop = chat.scrollHeight;
-  return el;
-}
-
-function connect() {
-  ws = new WebSocket('ws://' + location.host + '/ws');
-  ws.onopen = () => {
-    setStatus('Ready', 'done');
-    goBtn.disabled = false;
-  };
-  ws.onmessage = handleEvent;
-  ws.onerror = () => { setStatus('Error', 'error'); };
-  ws.onclose = () => {
-    setStatus('Reconnecting...', '');
-    goBtn.disabled = true;
-    setTimeout(connect, 2000);
-  };
-}
-
-function handleEvent(msg) {
-  const evt = JSON.parse(msg.data);
-
-  if (evt.type === 'llm_text_delta') {
-    if (currentAssistantEl) {
-      currentAssistantEl.textContent += evt.content;
-      chat.scrollTop = chat.scrollHeight;
-    }
-  }
-  else if (evt.type === 'ready') {
-    setStatus('Ready', 'done');
-    if (currentAssistantEl && !currentAssistantEl.textContent)
-      currentAssistantEl.remove();
-    goBtn.disabled = false;
-  }
-  else if (evt.type === 'node_loop_iteration') {
-    iterCount = evt.iteration || (iterCount + 1);
-    iterEl.textContent = 'Step ' + iterCount;
-    iterEl.style.display = '';
-  }
-  else if (evt.type === 'tool_call_started') {
-    var info = evt.tool_name + '('
-      + JSON.stringify(evt.tool_input).slice(0, 120) + ')';
-    addMsg('TOOL  ' + info, 'event tool');
-  }
-  else if (evt.type === 'tool_call_completed') {
-    var preview = (evt.result || '').slice(0, 200);
-    var cls = evt.is_error ? 'stall' : 'tool';
-    addMsg('RESULT  ' + evt.tool_name + ': ' + preview,
-           'event ' + cls);
-    currentAssistantEl = addMsg('', 'assistant');
-  }
-  else if (evt.type === 'result') {
-    setStatus('Session ended', evt.success ? 'done' : 'error');
-    if (evt.error) addMsg('ERROR  ' + evt.error, 'event stall');
-    if (currentAssistantEl && !currentAssistantEl.textContent)
-      currentAssistantEl.remove();
-    goBtn.disabled = false;
-  }
-  else if (evt.type === 'node_stalled') {
-    addMsg('STALLED  ' + evt.reason, 'event stall');
-  }
-  else if (evt.type === 'cleared') {
-    chat.innerHTML = '';
-    iterCount = 0;
-    iterEl.textContent = 'Step 0';
-    iterEl.style.display = 'none';
-    setStatus('Ready', 'done');
-    goBtn.disabled = false;
-  }
-}
-
-function run() {
-  const text = inputEl.value.trim();
-  if (!text || !ws || ws.readyState !== 1) return;
-  addMsg(text, 'user');
-  currentAssistantEl = addMsg('', 'assistant');
-  inputEl.value = '';
-  setStatus('Running', 'running');
-  goBtn.disabled = true;
-  ws.send(JSON.stringify({ topic: text }));
-}
-
-function clearConversation() {
-  if (ws && ws.readyState === 1) {
-    ws.send(JSON.stringify({ command: 'clear' }));
-  }
-}
-
-connect();
-</script>
-</body>
-</html>"""
-)
-
-
-# -------------------------------------------------------------------------
-# WebSocket handler
-# -------------------------------------------------------------------------
-
-
-async def handle_ws(websocket):
-    """Persistent WebSocket: long-lived EventLoopNode with client_facing blocking."""
-    global STORE
-
-    # -- Event forwarding (WebSocket ← EventBus) ----------------------------
-    bus = EventBus()
-
-    async def forward_event(event):
-        try:
-            payload = {"type": event.type.value, **event.data}
-            if event.node_id:
-                payload["node_id"] = event.node_id
-            await websocket.send(json.dumps(payload))
-        except Exception:
-            pass
-
-    bus.subscribe(
-        event_types=[
-            EventType.NODE_LOOP_STARTED,
-            EventType.NODE_LOOP_ITERATION,
-            EventType.NODE_LOOP_COMPLETED,
-            EventType.LLM_TEXT_DELTA,
-            EventType.TOOL_CALL_STARTED,
-            EventType.TOOL_CALL_COMPLETED,
-            EventType.NODE_STALLED,
-        ],
-        handler=forward_event,
-    )
-
-    # -- Per-connection state -----------------------------------------------
-    node = None
-    loop_task = None
-
-    tools = list(TOOL_REGISTRY.get_tools().values())
-    tool_executor = TOOL_REGISTRY.get_executor()
-
-    node_spec = NodeSpec(
-        id="assistant",
-        name="Chat Assistant",
-        description="A conversational assistant that remembers context across messages",
-        node_type="event_loop",
-        client_facing=True,
-        system_prompt=(
-            "You are a helpful assistant with access to tools. "
-            "You can search the web, scrape webpages, and query HubSpot CRM. "
-            "Use tools when the user asks for current information or external data. "
-            "You have full conversation history, so you can reference previous messages."
-        ),
-    )
-
-    # -- Ready callback: subscribe to CLIENT_INPUT_REQUESTED on the bus ---
-    async def on_input_requested(event):
-        try:
-            await websocket.send(json.dumps({"type": "ready"}))
-        except Exception:
-            pass
-
-    bus.subscribe(
-        event_types=[EventType.CLIENT_INPUT_REQUESTED],
-        handler=on_input_requested,
-    )
-
-    async def start_loop(first_message: str):
-        """Create an EventLoopNode and run it as a background task."""
-        nonlocal node, loop_task
-
-        memory = SharedMemory()
-        ctx = NodeContext(
-            runtime=RUNTIME,
-            node_id="assistant",
-            node_spec=node_spec,
-            memory=memory,
-            input_data={},
-            llm=LLM,
-            available_tools=tools,
-        )
-        node = EventLoopNode(
-            event_bus=bus,
-            config=LoopConfig(max_iterations=10_000, max_history_tokens=32_000),
-            conversation_store=STORE,
-            tool_executor=tool_executor,
-        )
-        await node.inject_event(first_message)
-
-        async def _run():
-            try:
-                result = await node.execute(ctx)
-                try:
-                    await websocket.send(
-                        json.dumps(
-                            {
-                                "type": "result",
-                                "success": result.success,
-                                "output": result.output,
-                                "error": result.error,
-                                "tokens": result.tokens_used,
-                            }
-                        )
-                    )
-                except Exception:
-                    pass
-                logger.info(f"Loop ended: success={result.success}, tokens={result.tokens_used}")
-            except websockets.exceptions.ConnectionClosed:
-                logger.info("Loop stopped: WebSocket closed")
-            except Exception as e:
-                logger.exception("Loop error")
-                try:
-                    await websocket.send(
-                        json.dumps(
-                            {
-                                "type": "result",
-                                "success": False,
-                                "error": str(e),
-                                "output": {},
-                            }
-                        )
-                    )
-                except Exception:
-                    pass
-
-        loop_task = asyncio.create_task(_run())
-
-    async def stop_loop():
-        """Signal the node and wait for the loop task to finish."""
-        nonlocal node, loop_task
-        if loop_task and not loop_task.done():
-            if node:
-                node.signal_shutdown()
-            try:
-                await asyncio.wait_for(loop_task, timeout=5.0)
-            except (TimeoutError, asyncio.CancelledError):
-                loop_task.cancel()
-        node = None
-        loop_task = None
-
-    # -- Message loop (runs for the lifetime of this WebSocket) -------------
-    try:
-        async for raw in websocket:
-            try:
-                msg = json.loads(raw)
-            except Exception:
-                continue
-
-            # Clear command
-            if msg.get("command") == "clear":
-                import shutil
-
-                await stop_loop()
-                await STORE.close()
-                conv_dir = STORE_DIR / "conversation"
-                if conv_dir.exists():
-                    shutil.rmtree(conv_dir)
-                STORE = FileConversationStore(conv_dir)
-                await websocket.send(json.dumps({"type": "cleared"}))
-                logger.info("Conversation cleared")
-                continue
-
-            topic = msg.get("topic", "")
-            if not topic:
-                continue
-
-            if node is None:
-                # First message — spin up the loop
-                logger.info(f"Starting persistent loop: {topic}")
-                await start_loop(topic)
-            else:
-                # Subsequent message — inject into the running loop
-                logger.info(f"Injecting message: {topic}")
-                await node.inject_event(topic)
-
-    except websockets.exceptions.ConnectionClosed:
-        pass
-    finally:
-        await stop_loop()
-        logger.info("WebSocket closed, loop stopped")
-
-
-# -------------------------------------------------------------------------
-# HTTP handler for serving the HTML page
-# -------------------------------------------------------------------------
-
-
-async def process_request(connection, request: Request):
-    """Serve HTML on GET /, upgrade to WebSocket on /ws."""
-    if request.path == "/ws":
-        return None  # let websockets handle the upgrade
-    # Serve the HTML page for any other path
-    return Response(
-        HTTPStatus.OK,
-        "OK",
-        websockets.Headers({"Content-Type": "text/html; charset=utf-8"}),
-        HTML_PAGE.encode(),
-    )
-
-
-# -------------------------------------------------------------------------
-# Main
-# -------------------------------------------------------------------------
-
-
-async def main():
-    port = 8765
-    async with websockets.serve(
-        handle_ws,
-        "0.0.0.0",
-        port,
-        process_request=process_request,
-    ):
-        logger.info(f"Demo running at http://localhost:{port}")
-        logger.info("Open in your browser and enter a topic to research.")
-        await asyncio.Future()  # run forever
-
-
-if __name__ == "__main__":
-    asyncio.run(main())
@@ -1,930 +0,0 @@
-#!/usr/bin/env python3
-"""
-Two-Node ContextHandoff Demo
-
-Demonstrates ContextHandoff between two EventLoopNode instances:
-  Node A (Researcher) → ContextHandoff → Node B (Analyst)
-
-Real LLM, real FileConversationStore, real EventBus.
-Streams both nodes to a browser via WebSocket.
-
-Usage:
-    cd /home/timothy/oss/hive/core
-    python demos/handoff_demo.py
-
-    Then open http://localhost:8766 in your browser.
-"""
-
-import asyncio
-import json
-import logging
-import sys
-import tempfile
-from http import HTTPStatus
-from pathlib import Path
-
-import httpx
-import websockets
-from bs4 import BeautifulSoup
-from websockets.http11 import Request, Response
-
-# Add core, tools, and hive root to path
-_CORE_DIR = Path(__file__).resolve().parent.parent
-_HIVE_DIR = _CORE_DIR.parent
-sys.path.insert(0, str(_CORE_DIR))  # framework.*
-sys.path.insert(0, str(_HIVE_DIR / "tools" / "src"))  # aden_tools.*
-sys.path.insert(0, str(_HIVE_DIR))  # core.framework.* (for aden_tools imports)
-
-from aden_tools.credentials import CREDENTIAL_SPECS, CredentialStoreAdapter  # noqa: E402
-from core.framework.credentials import CredentialStore  # noqa: E402
-
-from framework.credentials.storage import (  # noqa: E402
-    CompositeStorage,
-    EncryptedFileStorage,
-    EnvVarStorage,
-)
-from framework.graph.context_handoff import ContextHandoff  # noqa: E402
-from framework.graph.conversation import NodeConversation  # noqa: E402
-from framework.graph.event_loop_node import EventLoopNode, LoopConfig  # noqa: E402
-from framework.graph.node import NodeContext, NodeSpec, SharedMemory  # noqa: E402
-from framework.llm.litellm import LiteLLMProvider  # noqa: E402
-from framework.llm.provider import Tool  # noqa: E402
-from framework.runner.tool_registry import ToolRegistry  # noqa: E402
-from framework.runtime.core import Runtime  # noqa: E402
-from framework.runtime.event_bus import EventBus, EventType  # noqa: E402
-from framework.storage.conversation_store import FileConversationStore  # noqa: E402
-
-logging.basicConfig(level=logging.INFO, format="%(asctime)s %(name)s %(message)s")
-logger = logging.getLogger("handoff_demo")
-
-# -------------------------------------------------------------------------
-# Persistent state
-# -------------------------------------------------------------------------
-
-STORE_DIR = Path(tempfile.mkdtemp(prefix="hive_handoff_"))
-RUNTIME = Runtime(STORE_DIR / "runtime")
-LLM = LiteLLMProvider(model="claude-sonnet-4-5-20250929")
-
-# -------------------------------------------------------------------------
-# Credentials
-# -------------------------------------------------------------------------
-
-# Composite credential store: encrypted files (primary) + env vars (fallback)
-_env_mapping = {name: spec.env_var for name, spec in CREDENTIAL_SPECS.items()}
-_composite = CompositeStorage(
-    primary=EncryptedFileStorage(),
-    fallbacks=[EnvVarStorage(env_mapping=_env_mapping)],
-)
-CREDENTIALS = CredentialStoreAdapter(CredentialStore(storage=_composite))
-
-for _name in ["brave_search", "hubspot"]:
-    _val = CREDENTIALS.get(_name)
-    if _val:
-        logger.debug("credential %s: OK (len=%d)", _name, len(_val))
-    else:
-        logger.debug("credential %s: not found", _name)
-
-# -------------------------------------------------------------------------
-# Tool Registry — web_search + web_scrape for Node A (Researcher)
-# -------------------------------------------------------------------------
-
-TOOL_REGISTRY = ToolRegistry()
-
-
-def _exec_web_search(inputs: dict) -> dict:
-    api_key = CREDENTIALS.get("brave_search")
-    if not api_key:
-        return {"error": "brave_search credential not configured"}
-    query = inputs.get("query", "")
-    num_results = min(inputs.get("num_results", 10), 20)
-    resp = httpx.get(
-        "https://api.search.brave.com/res/v1/web/search",
-        params={"q": query, "count": num_results},
-        headers={
-            "X-Subscription-Token": api_key,
-            "Accept": "application/json",
-        },
-        timeout=30.0,
-    )
-    if resp.status_code != 200:
-        return {"error": f"Brave API HTTP {resp.status_code}"}
-    data = resp.json()
-    results = [
-        {
-            "title": item.get("title", ""),
-            "url": item.get("url", ""),
-            "snippet": item.get("description", ""),
-        }
-        for item in data.get("web", {}).get("results", [])[:num_results]
-    ]
-    return {"query": query, "results": results, "total": len(results)}
-
-
-TOOL_REGISTRY.register(
-    name="web_search",
-    tool=Tool(
-        name="web_search",
-        description=(
-            "Search the web for current information. "
-            "Returns titles, URLs, and snippets from search results."
-        ),
-        parameters={
-            "type": "object",
-            "properties": {
-                "query": {
-                    "type": "string",
-                    "description": "The search query (1-500 characters)",
-                },
-                "num_results": {
-                    "type": "integer",
-                    "description": "Number of results (1-20, default 10)",
-                },
-            },
-            "required": ["query"],
-        },
-    ),
-    executor=lambda inputs: _exec_web_search(inputs),
-)
-
-_SCRAPE_HEADERS = {
-    "User-Agent": (
-        "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
-        "AppleWebKit/537.36 (KHTML, like Gecko) "
-        "Chrome/131.0.0.0 Safari/537.36"
-    ),
-    "Accept": "text/html,application/xhtml+xml",
-}
-
-
-def _exec_web_scrape(inputs: dict) -> dict:
-    url = inputs.get("url", "")
-    max_length = max(1000, min(inputs.get("max_length", 50000), 500000))
-    if not url.startswith(("http://", "https://")):
-        url = "https://" + url
-    try:
-        resp = httpx.get(
-            url,
-            timeout=30.0,
-            follow_redirects=True,
-            headers=_SCRAPE_HEADERS,
-        )
-        if resp.status_code != 200:
-            return {"error": f"HTTP {resp.status_code}"}
-        soup = BeautifulSoup(resp.text, "html.parser")
-        for tag in soup(["script", "style", "nav", "footer", "header", "aside", "noscript"]):
-            tag.decompose()
-        title = soup.title.get_text(strip=True) if soup.title else ""
-        main = (
-            soup.find("article")
-            or soup.find("main")
-            or soup.find(attrs={"role": "main"})
-            or soup.find("body")
-        )
-        text = main.get_text(separator=" ", strip=True) if main else ""
-        text = " ".join(text.split())
-        if len(text) > max_length:
-            text = text[:max_length] + "..."
-        return {
-            "url": url,
-            "title": title,
-            "content": text,
-            "length": len(text),
-        }
-    except httpx.TimeoutException:
-        return {"error": "Request timed out"}
-    except Exception as e:
-        return {"error": f"Scrape failed: {e}"}
-
-
-TOOL_REGISTRY.register(
-    name="web_scrape",
-    tool=Tool(
-        name="web_scrape",
-        description=(
-            "Scrape and extract text content from a webpage URL. "
-            "Returns the page title and main text content."
-        ),
-        parameters={
-            "type": "object",
-            "properties": {
-                "url": {
-                    "type": "string",
-                    "description": "URL of the webpage to scrape",
-                },
-                "max_length": {
-                    "type": "integer",
-                    "description": "Maximum text length (default 50000)",
-                },
-            },
-            "required": ["url"],
-        },
-    ),
-    executor=lambda inputs: _exec_web_scrape(inputs),
-)
-
-logger.info(
-    "ToolRegistry loaded: %s",
-    ", ".join(TOOL_REGISTRY.get_registered_names()),
-)
-
-# -------------------------------------------------------------------------
-# Node Specs
-# -------------------------------------------------------------------------
-
-RESEARCHER_SPEC = NodeSpec(
-    id="researcher",
-    name="Researcher",
-    description="Researches a topic using web search and scraping tools",
-    node_type="event_loop",
-    input_keys=["topic"],
-    output_keys=["research_summary"],
-    system_prompt=(
-        "You are a thorough research assistant. Your job is to research "
-        "the given topic using the web_search and web_scrape tools.\n\n"
-        "1. Search for relevant information on the topic\n"
-        "2. Scrape 1-2 of the most promising URLs for details\n"
-        "3. Synthesize your findings into a comprehensive summary\n"
-        "4. Use set_output with key='research_summary' to save your "
-        "findings\n\n"
-        "Be thorough but efficient. Aim for 2-4 search/scrape calls, "
-        "then summarize and set_output."
-    ),
-)
-
-ANALYST_SPEC = NodeSpec(
-    id="analyst",
-    name="Analyst",
-    description="Analyzes research findings and provides insights",
-    node_type="event_loop",
-    input_keys=["context"],
-    output_keys=["analysis"],
-    system_prompt=(
-        "You are a strategic analyst. You receive research findings from "
-        "a previous researcher and must:\n\n"
-        "1. Identify key themes and patterns\n"
-        "2. Assess the reliability and significance of the findings\n"
-        "3. Provide actionable insights and recommendations\n"
-        "4. Use set_output with key='analysis' to save your analysis\n\n"
-        "Be concise but insightful. Focus on what matters most."
-    ),
-)
-
-
-# -------------------------------------------------------------------------
-# HTML page
-# -------------------------------------------------------------------------
-
-HTML_PAGE = (  # noqa: E501
-    """<!DOCTYPE html>
-<html lang="en">
-<head>
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width, initial-scale=1">
-<title>ContextHandoff Demo</title>
-<style>
-  * {
-    box-sizing: border-box;
-    margin: 0;
-    padding: 0;
-  }
-  body {
-    font-family: 'SF Mono', 'Fira Code', monospace;
-    background: #0d1117;
-    color: #c9d1d9;
-    height: 100vh;
-    display: flex;
-    flex-direction: column;
-  }
-  header {
-    background: #161b22;
-    padding: 12px 20px;
-    border-bottom: 1px solid #30363d;
-    display: flex;
-    align-items: center;
-    gap: 16px;
-  }
-  header h1 {
-    font-size: 16px;
-    color: #58a6ff;
-    font-weight: 600;
-  }
-  .badge {
-    font-size: 12px;
-    padding: 3px 10px;
-    border-radius: 12px;
-    background: #21262d;
-    color: #8b949e;
-  }
-  .badge.researcher {
-    background: #1a3a5c;
-    color: #58a6ff;
-  }
-  .badge.analyst {
-    background: #1a4b2e;
-    color: #3fb950;
-  }
-  .badge.handoff {
-    background: #3d1f00;
-    color: #d29922;
-  }
-  .badge.done {
-    background: #21262d;
-    color: #8b949e;
-  }
-  .badge.error {
-    background: #4b1a1a;
-    color: #f85149;
-  }
-  .chat {
-    flex: 1;
-    overflow-y: auto;
-    padding: 16px;
-  }
-  .msg {
-    margin: 8px 0;
-    padding: 10px 14px;
-    border-radius: 8px;
-    line-height: 1.6;
-    white-space: pre-wrap;
-    word-wrap: break-word;
-  }
-  .msg.user {
-    background: #1a3a5c;
-    color: #58a6ff;
-  }
-  .msg.assistant {
-    background: #161b22;
-    color: #c9d1d9;
-  }
-  .msg.assistant.analyst-msg {
-    border-left: 3px solid #3fb950;
-  }
-  .msg.event {
-    background: transparent;
-    color: #8b949e;
-    font-size: 11px;
-    padding: 4px 14px;
-    border-left: 3px solid #30363d;
-  }
-  .msg.event.loop {
-    border-left-color: #58a6ff;
-  }
-  .msg.event.tool {
-    border-left-color: #d29922;
-  }
-  .msg.event.stall {
-    border-left-color: #f85149;
-  }
-  .handoff-banner {
-    margin: 16px 0;
-    padding: 16px;
-    background: #1c1200;
-    border: 1px solid #d29922;
-    border-radius: 8px;
-    text-align: center;
-  }
-  .handoff-banner h3 {
-    color: #d29922;
-    font-size: 14px;
-    margin-bottom: 8px;
-  }
-  .handoff-banner p, .result-banner p {
-    color: #8b949e;
-    font-size: 12px;
-    line-height: 1.5;
-    max-height: 200px;
-    overflow-y: auto;
-    white-space: pre-wrap;
-    text-align: left;
-  }
-  .result-banner {
-    margin: 16px 0;
-    padding: 16px;
-    background: #0a2614;
-    border: 1px solid #3fb950;
-    border-radius: 8px;
-  }
-  .result-banner h3 {
-    color: #3fb950;
-    font-size: 14px;
-    margin-bottom: 8px;
-    text-align: center;
-  }
-  .result-banner .label {
-    color: #58a6ff;
-    font-size: 11px;
-    font-weight: 600;
-    margin-top: 10px;
-    margin-bottom: 2px;
-  }
-  .result-banner .tokens {
-    color: #484f58;
-    font-size: 11px;
-    text-align: center;
-    margin-top: 10px;
-  }
-  .input-bar {
-    padding: 12px 16px;
-    background: #161b22;
-    border-top: 1px solid #30363d;
-    display: flex;
-    gap: 8px;
-  }
-  .input-bar input {
-    flex: 1;
-    background: #0d1117;
-    border: 1px solid #30363d;
-    color: #c9d1d9;
-    padding: 8px 12px;
-    border-radius: 6px;
-    font-family: inherit;
-    font-size: 14px;
-    outline: none;
-  }
-  .input-bar input:focus {
-    border-color: #58a6ff;
-  }
-  .input-bar button {
-    background: #238636;
-    color: #fff;
-    border: none;
-    padding: 8px 20px;
-    border-radius: 6px;
-    cursor: pointer;
-    font-family: inherit;
-    font-weight: 600;
-  }
-  .input-bar button:hover {
-    background: #2ea043;
-  }
-  .input-bar button:disabled {
-    background: #21262d;
-    color: #484f58;
-    cursor: not-allowed;
-  }
-</style>
-</head>
-<body>
-  <header>
-    <h1>ContextHandoff Demo</h1>
-    <span id="phase" class="badge">Idle</span>
-    <span id="iter" class="badge" style="display:none">Step 0</span>
-  </header>
-  <div id="chat" class="chat"></div>
-  <div class="input-bar">
-    <input id="input" type="text"
-           placeholder="Enter a research topic..." autofocus />
-    <button id="go" onclick="run()">Research</button>
-  </div>
-
-<script>
-let ws = null;
-let currentAssistantEl = null;
-let iterCount = 0;
-let currentPhase = 'idle';
-const chat = document.getElementById('chat');
-const phase = document.getElementById('phase');
-const iterEl = document.getElementById('iter');
-const goBtn = document.getElementById('go');
-const inputEl = document.getElementById('input');
-
-inputEl.addEventListener('keydown', e => {
-  if (e.key === 'Enter') run();
-});
-
-function setPhase(text, cls) {
-  phase.textContent = text;
-  phase.className = 'badge ' + cls;
-  currentPhase = cls;
-}
-
-function addMsg(text, cls) {
-  const el = document.createElement('div');
-  el.className = 'msg ' + cls;
-  el.textContent = text;
-  chat.appendChild(el);
-  chat.scrollTop = chat.scrollHeight;
-  return el;
-}
-
-function addHandoffBanner(summary) {
-  const banner = document.createElement('div');
-  banner.className = 'handoff-banner';
-  const h3 = document.createElement('h3');
-  h3.textContent = 'Context Handoff: Researcher -> Analyst';
-  const p = document.createElement('p');
-  p.textContent = summary || 'Passing research context...';
-  banner.appendChild(h3);
-  banner.appendChild(p);
-  chat.appendChild(banner);
-  chat.scrollTop = chat.scrollHeight;
-}
-
-function addResultBanner(researcher, analyst, tokens) {
-  const banner = document.createElement('div');
-  banner.className = 'result-banner';
-  const h3 = document.createElement('h3');
-  h3.textContent = 'Pipeline Complete';
-  banner.appendChild(h3);
-
-  if (researcher && researcher.research_summary) {
-    const lbl = document.createElement('div');
-    lbl.className = 'label';
-    lbl.textContent = 'RESEARCH SUMMARY';
-    banner.appendChild(lbl);
-    const p = document.createElement('p');
-    p.textContent = researcher.research_summary;
-    banner.appendChild(p);
-  }
-
-  if (analyst && analyst.analysis) {
-    const lbl = document.createElement('div');
-    lbl.className = 'label';
-    lbl.textContent = 'ANALYSIS';
-    lbl.style.color = '#3fb950';
-    banner.appendChild(lbl);
-    const p = document.createElement('p');
-    p.textContent = analyst.analysis;
-    banner.appendChild(p);
-  }
-
-  if (tokens) {
-    const t = document.createElement('div');
-    t.className = 'tokens';
-    t.textContent = 'Total tokens: ' + tokens.toLocaleString();
-    banner.appendChild(t);
-  }
-
-  chat.appendChild(banner);
-  chat.scrollTop = chat.scrollHeight;
-}
-
-function connect() {
-  ws = new WebSocket('ws://' + location.host + '/ws');
-  ws.onopen = () => {
-    setPhase('Ready', 'done');
-    goBtn.disabled = false;
-  };
-  ws.onmessage = handleEvent;
-  ws.onerror = () => { setPhase('Error', 'error'); };
-  ws.onclose = () => {
-    setPhase('Reconnecting...', '');
-    goBtn.disabled = true;
-    setTimeout(connect, 2000);
-  };
-}
-
-function handleEvent(msg) {
-  const evt = JSON.parse(msg.data);
-
-  if (evt.type === 'phase') {
-    if (evt.phase === 'researcher') {
-      setPhase('Researcher', 'researcher');
-    } else if (evt.phase === 'handoff') {
-      setPhase('Handoff', 'handoff');
-    } else if (evt.phase === 'analyst') {
-      setPhase('Analyst', 'analyst');
-    }
-    iterCount = 0;
-    iterEl.style.display = 'none';
-  }
-  else if (evt.type === 'llm_text_delta') {
-    if (currentAssistantEl) {
-      currentAssistantEl.textContent += evt.content;
-      chat.scrollTop = chat.scrollHeight;
-    }
-  }
-  else if (evt.type === 'node_loop_iteration') {
-    iterCount = evt.iteration || (iterCount + 1);
-    iterEl.textContent = 'Step ' + iterCount;
-    iterEl.style.display = '';
-  }
-  else if (evt.type === 'tool_call_started') {
-    var info = evt.tool_name + '('
-      + JSON.stringify(evt.tool_input).slice(0, 120) + ')';
-    addMsg('TOOL  ' + info, 'event tool');
-  }
-  else if (evt.type === 'tool_call_completed') {
-    var preview = (evt.result || '').slice(0, 200);
-    var cls = evt.is_error ? 'stall' : 'tool';
-    addMsg(
-      'RESULT  ' + evt.tool_name + ': ' + preview,
-      'event ' + cls
-    );
-    var assistCls = currentPhase === 'analyst'
-      ? 'assistant analyst-msg' : 'assistant';
-    currentAssistantEl = addMsg('', assistCls);
-  }
-  else if (evt.type === 'handoff_context') {
-    addHandoffBanner(evt.summary);
-    var assistCls = 'assistant analyst-msg';
-    currentAssistantEl = addMsg('', assistCls);
-  }
-  else if (evt.type === 'node_result') {
-    if (evt.node_id === 'researcher') {
-      if (currentAssistantEl
-          && !currentAssistantEl.textContent) {
-        currentAssistantEl.remove();
-      }
-    }
-  }
-  else if (evt.type === 'done') {
-    setPhase('Done', 'done');
-    iterEl.style.display = 'none';
-    if (currentAssistantEl
-        && !currentAssistantEl.textContent) {
-      currentAssistantEl.remove();
-    }
-    currentAssistantEl = null;
-    addResultBanner(
-      evt.researcher, evt.analyst, evt.total_tokens
-    );
-    goBtn.disabled = false;
-    inputEl.placeholder = 'Enter another topic...';
-  }
-  else if (evt.type === 'error') {
-    setPhase('Error', 'error');
-    addMsg('ERROR  ' + evt.message, 'event stall');
-    goBtn.disabled = false;
-  }
-  else if (evt.type === 'node_stalled') {
-    addMsg('STALLED  ' + evt.reason, 'event stall');
-  }
-}
-
-function run() {
-  const text = inputEl.value.trim();
-  if (!text || !ws || ws.readyState !== 1) return;
-  chat.innerHTML = '';
-  addMsg(text, 'user');
-  currentAssistantEl = addMsg('', 'assistant');
-  inputEl.value = '';
-  goBtn.disabled = true;
-  ws.send(JSON.stringify({ topic: text }));
-}
-
-connect();
-</script>
-</body>
-</html>"""
-)
-
-
-# -------------------------------------------------------------------------
-# WebSocket handler — sequential Node A → Handoff → Node B
-# -------------------------------------------------------------------------
-
-
-async def handle_ws(websocket):
-    """Run the two-node handoff pipeline per user message."""
-    try:
-        async for raw in websocket:
-            try:
-                msg = json.loads(raw)
-            except Exception:
-                continue
-
-            topic = msg.get("topic", "")
-            if not topic:
-                continue
-
-            logger.info(f"Starting handoff pipeline for: {topic}")
-
-            try:
-                await _run_pipeline(websocket, topic)
-            except websockets.exceptions.ConnectionClosed:
-                logger.info("WebSocket closed during pipeline")
-                return
-            except Exception as e:
-                logger.exception("Pipeline error")
-                try:
-                    await websocket.send(json.dumps({"type": "error", "message": str(e)}))
-                except Exception:
-                    pass
-
-    except websockets.exceptions.ConnectionClosed:
-        pass
-
-
-async def _run_pipeline(websocket, topic: str):
-    """Execute: Node A (research) → ContextHandoff → Node B (analysis)."""
-    import shutil
-
-    # Fresh stores for each run
-    run_dir = Path(tempfile.mkdtemp(prefix="hive_run_", dir=STORE_DIR))
-    store_a = FileConversationStore(run_dir / "node_a")
-    store_b = FileConversationStore(run_dir / "node_b")
-
-    # Shared event bus
-    bus = EventBus()
-
-    async def forward_event(event):
-        try:
-            payload = {"type": event.type.value, **event.data}
-            if event.node_id:
-                payload["node_id"] = event.node_id
-            await websocket.send(json.dumps(payload))
-        except Exception:
-            pass
-
-    bus.subscribe(
-        event_types=[
-            EventType.NODE_LOOP_STARTED,
-            EventType.NODE_LOOP_ITERATION,
-            EventType.NODE_LOOP_COMPLETED,
-            EventType.LLM_TEXT_DELTA,
-            EventType.TOOL_CALL_STARTED,
-            EventType.TOOL_CALL_COMPLETED,
-            EventType.NODE_STALLED,
-        ],
-        handler=forward_event,
-    )
-
-    tools = list(TOOL_REGISTRY.get_tools().values())
-    tool_executor = TOOL_REGISTRY.get_executor()
-
-    # ---- Phase 1: Researcher ------------------------------------------------
-    await websocket.send(json.dumps({"type": "phase", "phase": "researcher"}))
-
-    node_a = EventLoopNode(
-        event_bus=bus,
-        judge=None,  # implicit judge: accept when output_keys filled
-        config=LoopConfig(
-            max_iterations=20,
-            max_tool_calls_per_turn=30,
-            max_history_tokens=32_000,
-        ),
-        conversation_store=store_a,
-        tool_executor=tool_executor,
-    )
-
-    ctx_a = NodeContext(
-        runtime=RUNTIME,
-        node_id="researcher",
-        node_spec=RESEARCHER_SPEC,
-        memory=SharedMemory(),
-        input_data={"topic": topic},
-        llm=LLM,
-        available_tools=tools,
-    )
-
-    result_a = await node_a.execute(ctx_a)
-    logger.info(
-        "Researcher done: success=%s, tokens=%s",
-        result_a.success,
-        result_a.tokens_used,
-    )
-
-    await websocket.send(
-        json.dumps(
-            {
-                "type": "node_result",
-                "node_id": "researcher",
-                "success": result_a.success,
-                "output": result_a.output,
-            }
-        )
-    )
-
-    if not result_a.success:
-        await websocket.send(
-            json.dumps(
-                {
-                    "type": "error",
-                    "message": f"Researcher failed: {result_a.error}",
-                }
-            )
-        )
-        return
-
-    # ---- Phase 2: Context Handoff -------------------------------------------
-    await websocket.send(json.dumps({"type": "phase", "phase": "handoff"}))
-
-    # Restore the researcher's conversation from store
-    conversation_a = await NodeConversation.restore(store_a)
-    if conversation_a is None:
-        await websocket.send(
-            json.dumps(
-                {
-                    "type": "error",
-                    "message": "Failed to restore researcher conversation",
-                }
-            )
-        )
-        return
-
-    handoff_engine = ContextHandoff(llm=LLM)
-    handoff_context = handoff_engine.summarize_conversation(
-        conversation=conversation_a,
-        node_id="researcher",
-        output_keys=["research_summary"],
-    )
-
-    formatted_handoff = ContextHandoff.format_as_input(handoff_context)
-    logger.info(
-        "Handoff: %d turns, ~%d tokens, keys=%s",
-        handoff_context.turn_count,
-        handoff_context.total_tokens_used,
-        list(handoff_context.key_outputs.keys()),
-    )
-
-    # Send handoff context to browser
-    await websocket.send(
-        json.dumps(
-            {
-                "type": "handoff_context",
-                "summary": handoff_context.summary[:500],
-                "turn_count": handoff_context.turn_count,
-                "tokens": handoff_context.total_tokens_used,
-                "key_outputs": handoff_context.key_outputs,
-            }
-        )
-    )
-
-    # ---- Phase 3: Analyst ---------------------------------------------------
-    await websocket.send(json.dumps({"type": "phase", "phase": "analyst"}))
-
-    node_b = EventLoopNode(
-        event_bus=bus,
-        judge=None,  # implicit judge
-        config=LoopConfig(
-            max_iterations=10,
-            max_tool_calls_per_turn=30,
-            max_history_tokens=32_000,
-        ),
-        conversation_store=store_b,
-    )
-
-    ctx_b = NodeContext(
-        runtime=RUNTIME,
-        node_id="analyst",
-        node_spec=ANALYST_SPEC,
-        memory=SharedMemory(),
-        input_data={"context": formatted_handoff},
-        llm=LLM,
-        available_tools=[],
-    )
-
-    result_b = await node_b.execute(ctx_b)
-    logger.info(
-        "Analyst done: success=%s, tokens=%s",
-        result_b.success,
-        result_b.tokens_used,
-    )
-
-    # ---- Done ---------------------------------------------------------------
-    await websocket.send(
-        json.dumps(
-            {
-                "type": "done",
-                "researcher": result_a.output,
-                "analyst": result_b.output,
-                "total_tokens": ((result_a.tokens_used or 0) + (result_b.tokens_used or 0)),
-            }
-        )
-    )
-
-    # Clean up temp stores
-    try:
-        shutil.rmtree(run_dir)
-    except Exception:
-        pass
-
-
-# -------------------------------------------------------------------------
-# HTTP handler
-# -------------------------------------------------------------------------
-
-
-async def process_request(connection, request: Request):
-    """Serve HTML on GET /, upgrade to WebSocket on /ws."""
-    if request.path == "/ws":
-        return None
-    return Response(
-        HTTPStatus.OK,
-        "OK",
-        websockets.Headers({"Content-Type": "text/html; charset=utf-8"}),
-        HTML_PAGE.encode(),
-    )
-
-
-# -------------------------------------------------------------------------
-# Main
-# -------------------------------------------------------------------------
-
-
-async def main():
-    port = 8766
-    async with websockets.serve(
-        handle_ws,
-        "0.0.0.0",
-        port,
-        process_request=process_request,
-    ):
-        logger.info(f"Handoff demo at http://localhost:{port}")
-        logger.info("Enter a research topic to start the pipeline.")
-        await asyncio.Future()
-
-
-if __name__ == "__main__":
-    asyncio.run(main())
@@ -27,7 +27,7 @@ class GreeterNode(NodeProtocol):
    async def execute(self, ctx: NodeContext) -> NodeResult:
        name = ctx.input_data.get("name", "World")
        greeting = f"Hello, {name}!"
-        ctx.memory.write("greeting", greeting)
+        ctx.buffer.write("greeting", greeting)
        return NodeResult(success=True, output={"greeting": greeting})


@@ -35,9 +35,9 @@ class UppercaserNode(NodeProtocol):
    """Convert text to uppercase."""

    async def execute(self, ctx: NodeContext) -> NodeResult:
-        greeting = ctx.input_data.get("greeting") or ctx.memory.read("greeting") or ""
+        greeting = ctx.input_data.get("greeting") or ctx.buffer.read("greeting") or ""
        result = greeting.upper()
-        ctx.memory.write("final_greeting", result)
+        ctx.buffer.write("final_greeting", result)
        return NodeResult(success=True, output={"final_greeting": result})


@@ -79,7 +79,7 @@ async def example_3_config_file():
    # Copy example config (in practice, you'd place this in your agent folder)
    import shutil

-    shutil.copy("examples/mcp_servers.json", test_agent_path / "mcp_servers.json")
+    shutil.copy(Path(__file__).parent / "mcp_servers.json", test_agent_path / "mcp_servers.json")

    # Load agent - MCP servers will be auto-discovered
    runner = AgentRunner.load(test_agent_path)
@@ -22,9 +22,8 @@ The framework includes a Goal-Based Testing system (Goal → Agent → Eval):
 See `framework.testing` for details.
 """

-from framework.builder.query import BuilderQuery
 from framework.llm import AnthropicProvider, LLMProvider
-from framework.runner import AgentOrchestrator, AgentRunner
+from framework.runner import AgentRunner
 from framework.runtime.core import Runtime
 from framework.schemas.decision import Decision, DecisionEvaluation, Option, Outcome
 from framework.schemas.run import Problem, Run, RunSummary
@@ -51,14 +50,11 @@ __all__ = [
    "Problem",
    # Runtime
    "Runtime",
-    # Builder
-    "BuilderQuery",
    # LLM
    "LLMProvider",
    "AnthropicProvider",
    # Runner
    "AgentRunner",
-    "AgentOrchestrator",
    # Testing
    "Test",
    "TestResult",
@@ -1,8 +1,6 @@
 """CLI entry point for Credential Tester agent."""

 import asyncio
-import logging
-import sys

 import click

@@ -10,13 +8,14 @@ from .agent import CredentialTesterAgent


 def setup_logging(verbose=False, debug=False):
+    from framework.observability import configure_logging
+
    if debug:
-        level, fmt = logging.DEBUG, "%(asctime)s %(name)s: %(message)s"
+        configure_logging(level="DEBUG")
    elif verbose:
-        level, fmt = logging.INFO, "%(message)s"
+        configure_logging(level="INFO")
    else:
-        level, fmt = logging.WARNING, "%(levelname)s: %(message)s"
-    logging.basicConfig(level=level, format=fmt, stream=sys.stderr)
+        configure_logging(level="WARNING")


 def pick_account(agent: CredentialTesterAgent) -> dict | None:
@@ -51,42 +50,6 @@ def cli():
    pass


-@cli.command()
-@click.option("--verbose", "-v", is_flag=True)
-@click.option("--debug", is_flag=True)
-def tui(verbose, debug):
-    """Launch TUI to test a credential interactively."""
-    setup_logging(verbose=verbose, debug=debug)
-
-    try:
-        from framework.tui.app import AdenTUI
-    except ImportError:
-        click.echo("TUI requires 'textual'. Install with: pip install textual")
-        sys.exit(1)
-
-    agent = CredentialTesterAgent()
-    account = pick_account(agent)
-    if account is None:
-        sys.exit(1)
-
-    agent.select_account(account)
-    provider = account.get("provider", "?")
-    alias = account.get("alias", "?")
-    click.echo(f"\nTesting {provider}/{alias}...\n")
-
-    async def run_tui():
-        agent._setup()
-        runtime = agent._agent_runtime
-        await runtime.start()
-        try:
-            app = AdenTUI(runtime)
-            await app.run_async()
-        finally:
-            await runtime.stop()
-
-    asyncio.run(run_tui())
-
-
@cli.command()
@click.option("--verbose", "-v", is_flag=True)
@click.option("--debug", is_flag=True)
@@ -16,14 +16,17 @@ after the user picks an account programmatically.

 from __future__ import annotations

+import logging
 from pathlib import Path
 from typing import TYPE_CHECKING

+from framework.config import get_max_context_tokens
 from framework.graph import Goal, NodeSpec, SuccessCriterion
 from framework.graph.checkpoint_config import CheckpointConfig
 from framework.graph.edge import GraphSpec
 from framework.graph.executor import ExecutionResult
 from framework.llm import LiteLLMProvider
+from framework.runner.mcp_registry import MCPRegistry
 from framework.runner.tool_registry import ToolRegistry
 from framework.runtime.agent_runtime import AgentRuntime, create_agent_runtime
 from framework.runtime.execution_stream import EntryPointSpec
@@ -31,9 +34,13 @@ from framework.runtime.execution_stream import EntryPointSpec
 from .config import default_config
 from .nodes import build_tester_node

+logger = logging.getLogger(__name__)
+
 if TYPE_CHECKING:
    from framework.runner import AgentRunner

+logger = logging.getLogger(__name__)
+
 # ---------------------------------------------------------------------------
 # Goal
 # ---------------------------------------------------------------------------
@@ -106,7 +113,11 @@ def _list_aden_accounts() -> list[dict]:
            for c in integrations
            if c.status == "active"
        ]
+    except (ImportError, OSError) as exc:
+        logger.debug("Could not list Aden accounts: %s", exc)
+        return []
    except Exception:
+        logger.warning("Unexpected error listing Aden accounts", exc_info=True)
        return []


@@ -118,7 +129,11 @@ def _list_local_accounts() -> list[dict]:
        return [
            info.to_account_dict() for info in LocalCredentialRegistry.default().list_accounts()
        ]
+    except ImportError as exc:
+        logger.debug("Local credential registry unavailable: %s", exc)
+        return []
    except Exception:
+        logger.warning("Unexpected error listing local accounts", exc_info=True)
        return []


@@ -139,7 +154,11 @@ def _list_env_fallback_accounts() -> list[dict]:
        from framework.credentials.storage import EncryptedFileStorage

        encrypted_ids: set[str] = set(EncryptedFileStorage().list_all())
+    except (ImportError, OSError) as exc:
+        logger.debug("Could not read encrypted store: %s", exc)
+        encrypted_ids = set()
    except Exception:
+        logger.warning("Unexpected error reading encrypted store", exc_info=True)
        encrypted_ids = set()

    def _is_configured(cred_name: str, spec) -> bool:
@@ -299,8 +318,10 @@ def _activate_local_account(credential_id: str, alias: str) -> None:

            if key:
                os.environ[spec.env_var] = key
+    except (ImportError, KeyError, OSError) as exc:
+        logger.debug("Could not inject credentials: %s", exc)
    except Exception:
-        pass
+        logger.warning("Unexpected error injecting credentials", exc_info=True)


 def _configure_aden_node(
@@ -455,7 +476,6 @@ identity_prompt = (
 loop_config = {
    "max_iterations": 50,
    "max_tool_calls_per_turn": 30,
-    "max_history_tokens": 32000,
 }

 # ---------------------------------------------------------------------------
@@ -541,7 +561,7 @@ class CredentialTesterAgent:
            loop_config={
                "max_iterations": 50,
                "max_tool_calls_per_turn": 30,
-                "max_history_tokens": 32000,
+                "max_context_tokens": get_max_context_tokens(),
            },
            conversation_mode="continuous",
            identity_prompt=(
@@ -563,6 +583,23 @@ class CredentialTesterAgent:
        if mcp_config_path.exists():
            self._tool_registry.load_mcp_config(mcp_config_path)

+        try:
+            agent_dir = Path(__file__).parent
+            registry = MCPRegistry()
+            registry.initialize()
+            if (agent_dir / "mcp_registry.json").is_file():
+                self._tool_registry.set_mcp_registry_agent_path(agent_dir)
+            registry_configs, selection_max_tools = registry.load_agent_selection(agent_dir)
+            if registry_configs:
+                self._tool_registry.load_registry_servers(
+                    registry_configs,
+                    preserve_existing_tools=True,
+                    log_collisions=True,
+                    max_tools=selection_max_tools,
+                )
+        except Exception:
+            logger.warning("MCP registry config failed to load", exc_info=True)
+
        extra_kwargs = getattr(self.config, "extra_kwargs", {}) or {}
        llm = LiteLLMProvider(
            model=self.config.model,
@@ -0,0 +1,209 @@
+"""Agent discovery — scan known directories and return categorised AgentEntry lists."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass
+class AgentEntry:
+    """Lightweight agent metadata for the picker / API discover endpoint."""
+
+    path: Path
+    name: str
+    description: str
+    category: str
+    session_count: int = 0
+    run_count: int = 0
+    node_count: int = 0
+    tool_count: int = 0
+    tags: list[str] = field(default_factory=list)
+    last_active: str | None = None
+
+
+def _get_last_active(agent_path: Path) -> str | None:
+    """Return the most recent updated_at timestamp across all sessions.
+
+    Checks both worker sessions (``~/.hive/agents/{name}/sessions/``) and
+    queen sessions (``~/.hive/queen/session/``) whose ``meta.json`` references
+    the same *agent_path*.
+    """
+    from datetime import datetime
+
+    agent_name = agent_path.name
+    latest: str | None = None
+
+    # 1. Worker sessions
+    sessions_dir = Path.home() / ".hive" / "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_"):
+                continue
+            state_file = session_dir / "state.json"
+            if not state_file.exists():
+                continue
+            try:
+                data = json.loads(state_file.read_text(encoding="utf-8"))
+                ts = data.get("timestamps", {}).get("updated_at")
+                if ts and (latest is None or ts > latest):
+                    latest = ts
+            except Exception:
+                continue
+
+    # 2. Queen sessions
+    queen_sessions_dir = Path.home() / ".hive" / "queen" / "session"
+    if queen_sessions_dir.exists():
+        resolved = agent_path.resolve()
+        for d in queen_sessions_dir.iterdir():
+            if not d.is_dir():
+                continue
+            meta_file = d / "meta.json"
+            if not meta_file.exists():
+                continue
+            try:
+                meta = json.loads(meta_file.read_text(encoding="utf-8"))
+                stored = meta.get("agent_path")
+                if not stored or Path(stored).resolve() != resolved:
+                    continue
+                ts = datetime.fromtimestamp(d.stat().st_mtime).isoformat()
+                if latest is None or ts > latest:
+                    latest = ts
+            except Exception:
+                continue
+
+    return latest
+
+
+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"
+    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_"))
+
+
+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"
+    if not sessions_dir.exists():
+        return 0
+    run_ids: set[str] = set()
+    for session_dir in sessions_dir.iterdir():
+        if not session_dir.is_dir() or not session_dir.name.startswith("session_"):
+            continue
+        # runs.jsonl lives inside workspace subdirectories
+        for runs_file in session_dir.rglob("runs.jsonl"):
+            try:
+                for line in runs_file.read_text(encoding="utf-8").splitlines():
+                    line = line.strip()
+                    if not line:
+                        continue
+                    record = json.loads(line)
+                    rid = record.get("run_id")
+                    if rid:
+                        run_ids.add(rid)
+            except Exception:
+                continue
+    return len(run_ids)
+
+
+def _extract_agent_stats(agent_path: Path) -> tuple[int, int, list[str]]:
+    """Extract node count, tool count, and tags from an agent directory.
+
+    Prefers agent.py (AST-parsed) over agent.json for node/tool counts
+    since agent.json may be stale.  Tags are only available from agent.json.
+    """
+    import ast
+
+    node_count, tool_count, tags = 0, 0, []
+
+    agent_py = agent_path / "agent.py"
+    if agent_py.exists():
+        try:
+            tree = ast.parse(agent_py.read_text(encoding="utf-8"))
+            for node in ast.walk(tree):
+                if isinstance(node, ast.Assign):
+                    for target in node.targets:
+                        if isinstance(target, ast.Name) and target.id == "nodes":
+                            if isinstance(node.value, ast.List):
+                                node_count = len(node.value.elts)
+        except Exception:
+            pass
+
+    agent_json = agent_path / "agent.json"
+    if agent_json.exists():
+        try:
+            data = json.loads(agent_json.read_text(encoding="utf-8"))
+            json_nodes = data.get("graph", {}).get("nodes", []) or data.get("nodes", [])
+            if node_count == 0:
+                node_count = len(json_nodes)
+            tools: set[str] = set()
+            for n in json_nodes:
+                tools.update(n.get("tools", []))
+            tool_count = len(tools)
+            tags = data.get("agent", {}).get("tags", [])
+        except Exception:
+            pass
+
+    return node_count, tool_count, tags
+
+
+def discover_agents() -> dict[str, list[AgentEntry]]:
+    """Discover agents from all known sources grouped by category."""
+    from framework.runner.cli import (
+        _extract_python_agent_metadata,
+        _get_framework_agents_dir,
+        _is_valid_agent_dir,
+    )
+
+    groups: dict[str, list[AgentEntry]] = {}
+    sources = [
+        ("Your Agents", Path("exports")),
+        ("Framework", _get_framework_agents_dir()),
+        ("Examples", Path("examples/templates")),
+    ]
+
+    for category, base_dir in sources:
+        if not base_dir.exists():
+            continue
+        entries: list[AgentEntry] = []
+        for path in sorted(base_dir.iterdir(), key=lambda p: p.name):
+            if not _is_valid_agent_dir(path):
+                continue
+
+            name, desc = _extract_python_agent_metadata(path)
+            config_fallback_name = path.name.replace("_", " ").title()
+            used_config = name != config_fallback_name
+
+            node_count, tool_count, tags = _extract_agent_stats(path)
+            if not used_config:
+                agent_json = path / "agent.json"
+                if agent_json.exists():
+                    try:
+                        data = json.loads(agent_json.read_text(encoding="utf-8"))
+                        meta = data.get("agent", {})
+                        name = meta.get("name", name)
+                        desc = meta.get("description", desc)
+                    except Exception:
+                        pass
+
+            entries.append(
+                AgentEntry(
+                    path=path,
+                    name=name,
+                    description=desc,
+                    category=category,
+                    session_count=_count_sessions(path.name),
+                    run_count=_count_runs(path.name),
+                    node_count=node_count,
+                    tool_count=tool_count,
+                    tags=tags,
+                    last_active=_get_last_active(path),
+                )
+            )
+        if entries:
+            groups[category] = entries
+
+    return groups
@@ -1,60 +0,0 @@
-"""CLI entry point for Hive Coder agent."""
-
-import json
-import logging
-import sys
-
-import click
-
-from .agent import entry_node, goal, nodes
-from .config import metadata
-
-
-def setup_logging(verbose=False, debug=False):
-    """Configure logging for execution visibility."""
-    if debug:
-        level, fmt = logging.DEBUG, "%(asctime)s %(name)s: %(message)s"
-    elif verbose:
-        level, fmt = logging.INFO, "%(message)s"
-    else:
-        level, fmt = logging.WARNING, "%(levelname)s: %(message)s"
-    logging.basicConfig(level=level, format=fmt, stream=sys.stderr)
-    logging.getLogger("framework").setLevel(level)
-
-
-@click.group()
-@click.version_option(version="1.0.0")
-def cli():
-    """Hive Coder — Build Hive agent packages from natural language."""
-    pass
-
-
-@cli.command()
-@click.option("--json", "output_json", is_flag=True)
-def info(output_json):
-    """Show agent information."""
-    info_data = {
-        "name": metadata.name,
-        "version": metadata.version,
-        "description": metadata.description,
-        "goal": {
-            "name": goal.name,
-            "description": goal.description,
-        },
-        "nodes": [n.id for n in nodes],
-        "entry_node": entry_node,
-        "client_facing_nodes": [n.id for n in nodes if n.client_facing],
-    }
-    if output_json:
-        click.echo(json.dumps(info_data, indent=2))
-    else:
-        click.echo(f"Agent: {info_data['name']}")
-        click.echo(f"Version: {info_data['version']}")
-        click.echo(f"Description: {info_data['description']}")
-        click.echo(f"\nNodes: {', '.join(info_data['nodes'])}")
-        click.echo(f"Client-facing: {', '.join(info_data['client_facing_nodes'])}")
-        click.echo(f"Entry: {info_data['entry_node']}")
-
-
-if __name__ == "__main__":
-    cli()
@@ -1,153 +0,0 @@
-"""Agent graph construction for Hive Coder."""
-
-from framework.graph import Constraint, Goal, SuccessCriterion
-from framework.graph.edge import GraphSpec
-
-from .nodes import coder_node, queen_node
-
-# Goal definition
-goal = Goal(
-    id="hive-coder",
-    name="Hive Agent Builder",
-    description=(
-        "Build complete, validated Hive agent packages from natural language "
-        "specifications. Produces production-ready Python packages with goals, "
-        "nodes, edges, system prompts, MCP configuration, and tests."
-    ),
-    success_criteria=[
-        SuccessCriterion(
-            id="valid-package",
-            description="Generated agent package passes structural validation",
-            metric="validation_pass",
-            target="true",
-            weight=0.30,
-        ),
-        SuccessCriterion(
-            id="complete-files",
-            description=(
-                "All required files generated: agent.py, config.py, "
-                "nodes/__init__.py, __init__.py, __main__.py, mcp_servers.json"
-            ),
-            metric="file_count",
-            target=">=6",
-            weight=0.25,
-        ),
-        SuccessCriterion(
-            id="user-satisfaction",
-            description="User reviews and approves the generated agent",
-            metric="user_approval",
-            target="true",
-            weight=0.25,
-        ),
-        SuccessCriterion(
-            id="framework-compliance",
-            description=(
-                "Generated code follows framework patterns: STEP 1/STEP 2 "
-                "for client-facing and correct imports"
-            ),
-            metric="pattern_compliance",
-            target="100%",
-            weight=0.20,
-        ),
-    ],
-    constraints=[
-        Constraint(
-            id="dynamic-tool-discovery",
-            description=(
-                "Always discover available tools dynamically via "
-                "list_agent_tools before referencing tools in agent designs"
-            ),
-            constraint_type="hard",
-            category="correctness",
-        ),
-        Constraint(
-            id="no-fabricated-tools",
-            description="Only reference tools that exist in hive-tools MCP",
-            constraint_type="hard",
-            category="correctness",
-        ),
-        Constraint(
-            id="valid-python",
-            description="All generated Python files must be syntactically correct",
-            constraint_type="hard",
-            category="correctness",
-        ),
-        Constraint(
-            id="self-verification",
-            description="Run validation after writing code; fix errors before presenting",
-            constraint_type="hard",
-            category="quality",
-        ),
-    ],
-)
-
-# Nodes: primary coder node only.  The queen runs as an independent
-# GraphExecutor with queen_node — not as part of this graph.
-nodes = [coder_node]
-
-# No edges needed — single event_loop node
-edges = []
-
-# Graph configuration
-entry_node = "coder"
-entry_points = {"start": "coder"}
-pause_nodes = []
-terminal_nodes = []  # Coder node has output_keys and can terminate
-
-# No async entry points needed — the queen is now an independent executor,
-# not a secondary graph receiving events via add_graph().
-async_entry_points = []
-
-# Module-level variables read by AgentRunner.load()
-conversation_mode = "continuous"
-identity_prompt = (
-    "You are Hive Coder, the best agent-building coding agent on the planet. "
-    "You deeply understand the Hive agent framework at the source code level "
-    "and produce production-ready agent packages from natural language. "
-    "You can dynamically discover available framework tools, inspect runtime "
-    "sessions and checkpoints from agents you build, and run their test suites. "
-    "You follow coding agent discipline: read before writing, verify "
-    "assumptions by reading actual code, adhere to project conventions, "
-    "self-verify with validation, and fix your own errors. You are concise, "
-    "direct, and technically rigorous. No emojis. No fluff."
-)
-loop_config = {
-    "max_iterations": 100,
-    "max_tool_calls_per_turn": 30,
-    "max_history_tokens": 32000,
-}
-
-
-# ---------------------------------------------------------------------------
-# Queen graph — runs as an independent persistent conversation in the TUI.
-# Loaded by _load_judge_and_queen() in app.py, NOT by AgentRunner.
-# ---------------------------------------------------------------------------
-
-queen_goal = Goal(
-    id="queen-manager",
-    name="Queen Manager",
-    description=(
-        "Manage the worker agent lifecycle and serve as the user's primary "
-        "interactive interface. Triage health escalations from the judge."
-    ),
-    success_criteria=[],
-    constraints=[],
-)
-
-queen_graph = GraphSpec(
-    id="queen-graph",
-    goal_id=queen_goal.id,
-    version="1.0.0",
-    entry_node="queen",
-    entry_points={"start": "queen"},
-    terminal_nodes=[],
-    pause_nodes=[],
-    nodes=[queen_node],
-    edges=[],
-    conversation_mode="continuous",
-    loop_config={
-        "max_iterations": 999_999,
-        "max_tool_calls_per_turn": 30,
-        "max_history_tokens": 32000,
-    },
-)
@@ -1,933 +0,0 @@
-"""Node definitions for Hive Coder agent."""
-
-from pathlib import Path
-
-from framework.graph import NodeSpec
-
-# Load reference docs at import time so they're always in the system prompt.
-# No voluntary read_file() calls needed — the LLM gets everything upfront.
-_ref_dir = Path(__file__).parent.parent / "reference"
-_framework_guide = (_ref_dir / "framework_guide.md").read_text(encoding="utf-8")
-_anti_patterns = (_ref_dir / "anti_patterns.md").read_text(encoding="utf-8")
-_gcu_guide_path = _ref_dir / "gcu_guide.md"
-_gcu_guide = _gcu_guide_path.read_text(encoding="utf-8") if _gcu_guide_path.exists() else ""
-
-
-def _is_gcu_enabled() -> bool:
-    try:
-        from framework.config import get_gcu_enabled
-
-        return get_gcu_enabled()
-    except Exception:
-        return False
-
-
-def _build_appendices() -> str:
-    parts = (
-        "\n\n# Appendix: Framework Reference\n\n"
-        + _framework_guide
-        + "\n\n# Appendix: Anti-Patterns\n\n"
-        + _anti_patterns
-    )
-    return parts
-
-
-# Shared appendices — appended to every coding node's system prompt.
-_appendices = _build_appendices()
-
-# GCU first-class section for building phase (when GCU is enabled).
-# This is placed prominently in the main prompt body, not as an appendix.
-_gcu_building_section = (
-    ("\n\n# GCU Nodes — Browser Automation\n\n" + _gcu_guide)
-    if _is_gcu_enabled() and _gcu_guide
-    else ""
-)
-
-# Tools available to both coder (worker) and queen.
-_SHARED_TOOLS = [
-    # File I/O
-    "read_file",
-    "write_file",
-    "edit_file",
-    "hashline_edit",
-    "list_directory",
-    "search_files",
-    "run_command",
-    "undo_changes",
-    # Meta-agent
-    "list_agent_tools",
-    "validate_agent_package",
-    "list_agents",
-    "list_agent_sessions",
-    "list_agent_checkpoints",
-    "get_agent_checkpoint",
-    "initialize_agent_package",
-]
-
-# Queen phase-specific tool sets.
-# Building phase: full coding + agent construction tools.
-_QUEEN_BUILDING_TOOLS = _SHARED_TOOLS + [
-    "load_built_agent",
-    "list_credentials",
-]
-
-# Staging phase: agent loaded but not yet running — inspect, configure, launch.
-_QUEEN_STAGING_TOOLS = [
-    # Read-only (inspect agent files, logs)
-    "read_file",
-    "list_directory",
-    "search_files",
-    "run_command",
-    # Agent inspection
-    "list_credentials",
-    "get_worker_status",
-    # Launch or go back
-    "run_agent_with_input",
-    "stop_worker_and_edit",
-]
-
-# Running phase: worker is executing — monitor and control.
-_QUEEN_RUNNING_TOOLS = [
-    # Read-only coding (for inspecting logs, files)
-    "read_file",
-    "list_directory",
-    "search_files",
-    "run_command",
-    # Credentials
-    "list_credentials",
-    # Worker lifecycle
-    "stop_worker",
-    "stop_worker_and_edit",
-    "get_worker_status",
-    "inject_worker_message",
-    # Monitoring
-    "get_worker_health_summary",
-    "notify_operator",
-]
-
-
-# ---------------------------------------------------------------------------
-# Shared agent-building knowledge: core mandates, tool docs, meta-agent
-# capabilities, and workflow phases 1-6.  Both the coder (worker) and
-# queen compose their system prompts from this block + role-specific
-# additions.
-# ---------------------------------------------------------------------------
-
-_package_builder_knowledge = """\
-**A responsible engineer doesn't jump into building. First, \
-understand the problem and be transparent about what the framework can and cannot do.**
-
-Use the user's selection (or their custom description if they chose "Other") \
-as context when shaping the goal below. If the user already described \
-what they want before this step, skip the question and proceed directly.
-
-# Core Mandates
- **DO NOT propose a complete goal on your own.** Instead, \
-collaborate with the user to define it.
- **Verify assumptions.** Never assume a class, import, or pattern \
-exists. Read actual source to confirm. Search if unsure.
- **Discover tools dynamically.** NEVER reference tools from static \
-docs. Always run list_agent_tools() to see what actually exists.
- **Self-verify.** After writing code, run validation and tests. Fix \
-errors yourself. Don't declare success until validation passes.
-
-# Tools
-## Paths (MANDATORY)
-**Always use RELATIVE paths**
-(e.g. `exports/agent_name/config.py`, `exports/agent_name/nodes/__init__.py`).
-**Never use absolute paths** like `/mnt/data/...` or `/workspace/...` — they fail.
-The project root is implicit.
-
-## File I/O
- read_file(path, offset?, limit?, hashline?) — read with line numbers; \
-hashline=True for N:hhhh|content anchors (use with hashline_edit)
- write_file(path, content) — create/overwrite, auto-mkdir
- edit_file(path, old_text, new_text, replace_all?) — fuzzy-match edit
- hashline_edit(path, edits, auto_cleanup?, encoding?) — anchor-based \
-editing using N:hhhh refs from read_file(hashline=True). Ops: set_line, \
-replace_lines, insert_after, insert_before, replace, append
- list_directory(path, recursive?) — list contents
- search_files(pattern, path?, include?, hashline?) — regex search; \
-hashline=True for anchors in results
- run_command(command, cwd?, timeout?) — shell execution
- undo_changes(path?) — restore from git snapshot
-
-## Meta-Agent
- list_agent_tools(server_config_path?, output_schema?, group?) — discover \
-available tools grouped by category. output_schema: "simple" (default, \
-descriptions truncated to ~200 chars) or "full" (complete descriptions + \
-input_schema). group: "all" (default) or a provider like "google". \
-Call FIRST before designing.
- validate_agent_package(agent_name) — run ALL validation checks in one call \
-(class validation, runner load, tool validation, tests). Call after building.
- list_agents() — list all agent packages in exports/ with session counts
- list_agent_sessions(agent_name, status?, limit?) — list sessions
- list_agent_checkpoints(agent_name, session_id) — list checkpoints
- get_agent_checkpoint(agent_name, session_id, checkpoint_id?) — load checkpoint
-
-# Meta-Agent Capabilities
-
-You are not just a file writer. You have deep integration with the \
-Hive framework:
-
-## Tool Discovery (MANDATORY before designing)
-Before designing any agent, run list_agent_tools() with NO arguments \
-to see ALL available tools (names + descriptions, grouped by category). \
-ONLY use tools from this list in your node definitions. \
-NEVER guess or fabricate tool names from memory.
-
-  list_agent_tools()  # ALWAYS call this first (simple mode)
-  list_agent_tools(group="google", output_schema="full")  # drill into a provider
-
-NEVER skip the first call. Always start with the full list \
-so you know what providers and tools exist before drilling in. \
-Simple mode truncates long descriptions — use group + "full" to \
-get the complete description and input_schema for the tools you need.
-
-## Post-Build Validation
-After writing agent code, run a single comprehensive check:
-  validate_agent_package("{name}")
-This runs class validation, runner load, tool validation, and tests \
-in one call. Do NOT run these steps individually.
-
-## Debugging Built Agents
-When a user says "my agent is failing" or "debug this agent":
-1. list_agent_sessions("{agent_name}") — find the session
-2. get_worker_status(focus="issues") — check for problems
-3. list_agent_checkpoints / get_agent_checkpoint — trace execution
-
-# Agent Building Workflow
-
-You operate in a continuous loop. The user describes what they want, \
-you build it. No rigid phases — use judgment. But the general flow is:
-
-## 1: Fast Discovery (3-6 Turns)
-
-**The core principle**: Discovery should feel like progress, not paperwork. \
-The stakeholder should walk away feeling like you understood them faster \
-than anyone else would have.
-
-**Communication sytle**: Be concise. Say less. Mean more. Impatient stakeholders \
-don't want a wall of text — they want to know you get it. Every sentence you say \
-should either move the conversation forward or prove you understood something. \
-If it does neither, cut it.
-
-**Ask Question Rules: Respect Their Time.** Every question must earn its place by:
-1. **Preventing a costly wrong turn** — you're about to build the wrong thing
-2. **Unlocking a shortcut** — their answer lets you simplify the design
-3. **Surfacing a dealbreaker** — there's a constraint that changes everything
-4. **Provide Options** - Provide options to your questions if possible, \
-but also always allow the user to type something beyong the options.
-
-If a question doesn't do one of these, don't ask it. Make an assumption, state it, and move on.
-
---
-
-### 1.1: Let Them Talk, But Listen Like an Solution Architect
-
-When the stakeholder describes what they want, mentally construct:
-
- **The pain**: What about today's situation is broken, slow, or missing?
- **The actors**: Who are the people/systems involved?
- **The trigger**: What kicks off the workflow?
- **The core loop**: What's the main thing that happens repeatedly?
- **The output**: What's the valuable thing produced at the end?
-
---
-
-### 1.2: Use Domain Knowledge to Fill In the Blanks
-
-You have broad knowledge of how systems work. Use it aggressively.
-
-If they say "I need a research agent," you already know it probably involves: \
-search, summarization, source tracking, and iteration. Don't ask about each — \
-use them as your starting mental model and let their specifics override your defaults.
-
-If they say "I need to monitor files and alert me," you know this probably involves: \
-watch patterns, triggers, notifications, and state tracking.
-
---
-
-### 1.3: Play Back a Proposed Model (Not a List of Questions)
-
-After listening, present a **concrete picture** of what you think they need. \
-Make it specific enough that they can spot what's wrong. \
-Can you ASCII to show the user
-
-**Pattern: "Here's what I heard — tell me where I'm off"**
-
-> "OK here's how I'm picturing this: [User type] needs to [core action]. \
-Right now they're [current painful workflow]. \
-What you want is [proposed solution that replaces the pain].
-> The way I'd structure this: [key entities] connected by [key relationships], \
-with the main flow being [trigger → steps → outcome].
-> For the MVP, I'd focus on [the one thing that delivers the most value] \
-and hold off on [things that can wait].
-> Before I start — [1-2 specific questions you genuinely can't infer]."
-
---
-
-### 1.4: Ask Only What You Cannot Infer
-
-Your questions should be **narrow, specific, and consequential**. \
-Never ask what you could answer yourself.
-
-**Good questions** (high-stakes, can't infer):
- "Who's the primary user — you or your end customers?"
- "Is this replacing a spreadsheet, or is there literally nothing today?"
- "Does this need to integrate with anything, or standalone?"
- "Is there existing data to migrate, or starting fresh?"
-
-**Bad questions** (low-stakes, inferable):
- "What should happen if there's an error?" *(handle gracefully, obviously)*
- "Should it have search?" *(if there's a list, yes)*
- "How should we handle permissions?" *(follow standard patterns)*
- "What tools should I use?" *(your call, not theirs)*
-
---
-
-## 2: Capability Assessment & Gap Analysis
-
-**After the user responds, assess fit and gaps together.** Be honest and specific. \
-Reference tools from list_agent_tools() AND built-in capabilities:
- **GCU browser automation** (`node_type="gcu"`) provides full Playwright-based \
-browser control (navigation, clicking, typing, scrolling, JS-rendered pages, \
-multi-tab). Do NOT list browser automation as missing — use GCU nodes.
-
-Present a short **Framework Fit Assessment**:
- **Works well**: 2-4 strengths for this use case
- **Limitations**: 2-3 workable constraints (e.g., LLM latency, context limits)
- **Gaps/Deal-breakers**: Only list genuinely missing capabilities after checking \
-both list_agent_tools() and built-in features like GCU
-
-## 3: Design Graph and Propose
-
-Act like an experienced AI solution architect Design the agent architecture:
- Goal: id, name, description, 3-5 success criteria, 2-4 constraints
- Nodes: **3-6 nodes** (HARD RULE: never fewer than 3, never more than 6). \
-2 nodes is ALWAYS wrong — it means you under-decomposed the task. \
-Use as many nodes as the use case requires, but don't create nodes without \
-tools — merge them into nodes that do real work.
- Edges: on_success for linear, conditional for routing
- Lifecycle: ALWAYS have terminal_nodes
-
-**MERGE nodes when:**
- Node has NO tools (pure LLM reasoning) → merge into predecessor/successor
- Node sets only 1 trivial output → collapse into predecessor
-
-**SEPARATE nodes when:**
- Fundamentally different tool sets (e.g., search vs. write vs. validate)
- Fan-out parallelism (parallel branches MUST be separate)
- Different failure/retry semantics (e.g., gather can retry, transform cannot)
- Distinct phases of work (e.g., research, transform, validate, deliver)
- A node would need more than ~5 tools — split by responsibility
-
-**Typical patterns (queen manages all user interaction):**
- 3 nodes: `gather → work → review`
- 4 nodes: `gather → analyze → transform → review`
- 5 nodes: `gather → research → transform → validate → deliver`
- WRONG: 2 nodes where everything is crammed into one giant node
- WRONG: 7 nodes where half have no tools and just do LLM reasoning
-
-Read reference agents before designing:
-  list_agents()
-  read_file("exports/deep_research_agent/agent.py")
-  read_file("exports/deep_research_agent/nodes/__init__.py")
-
-Present the design to the user. Lead with a large ASCII graph inside \
-a code block so it renders in monospace. Make it visually prominent — \
-use box-drawing characters and clear flow arrows:
-
-```
-┌─────────────────────────┐
-│  gather                 │
-│  subagent: gcu_search   │
-│  input:  user_request   │
-│  tools: web_search,     │
-│         write_file      │
-└────────────┬────────────┘
-             │ on_success
-             ▼
-┌─────────────────────────┐
-│  work                   │
-│  subagent: gcu_interact │
-│  tools: read_file,      │
-│         write_file      │
-└────────────┬────────────┘
-             │ on_success
-             ▼
-┌─────────────────────────┐
-│  review                 │
-│  tools: write_file      │
-└────────────┬────────────┘
-             │ on_failure
-             └──────► back to gather
-```
-
-The queen owns intake: she gathers user requirements, then calls \
-`run_agent_with_input(task)` with a structured task description. \
-When building the agent, design the entry node's `input_keys` to \
-match what the queen will provide at run time. Worker nodes should \
-use `escalate` for blockers.
-
-Follow the graph with a brief summary of each node's purpose. \
-Get user approval before implementing.
-
-## 4: Get User Confirmation by ask_user
-
-**WAIT for user response.**
- If **Proceed**: Move to next implementing
- If **Adjust scope**: Discuss what to change, update your notes, re-assess if needed
- If **More questions**: Answer them honestly, then ask again
- If **Reconsider**: Discuss alternatives. If they decide to proceed anyway, \
-that's their informed choice
-
-## 5. Implement
-
-**Please make sure you have propose the design to the user before implementing**
-
-Call `initialize_agent_package(agent_name)` to generate all package files \
-from your graph session. The agent_name must be snake_case (e.g., "my_agent").
-The tool creates: config.py, nodes/__init__.py, agent.py, \
-__init__.py, __main__.py, mcp_servers.json, tests/conftest.py, \
-agent.json, README.md.
-
-`mcp_servers.json` is auto-generated with hive-tools as the default. \
-Do NOT manually create or overwrite `mcp_servers.json`.
-
-After initialization, review and customize if needed:
- System prompts in nodes/__init__.py
- CLI options in __main__.py
- Identity prompt in agent.py
- For async entry points (timers/webhooks), add AsyncEntryPointSpec \
-and AgentRuntimeConfig to agent.py manually
-
-Do NOT manually write these files from scratch — always use the tool.
-
-## 6. Verify and Load
-
-Call `validate_agent_package("{name}")` after initialization. \
-It runs structural checks (class validation, graph validation, tool \
-validation, tests) and returns a consolidated result. If anything \
-fails: read the error, fix with edit_file, re-validate. Up to 3x.
-
-When validation passes, immediately call \
-`load_built_agent("exports/{name}")` to load the agent into the \
-session. This switches to STAGING phase and shows the graph in the \
-visualizer. Do NOT wait for user input between validation and loading.
-"""
-
-
-# ---------------------------------------------------------------------------
-# Queen-specific: extra tool docs, behavior, phase 7, style
-# ---------------------------------------------------------------------------
-
-# -- Phase-specific identities --
-
-_queen_identity_building = """\
-You are an experienced, responsible and curious Solution Architect. \
-"Queen" is the internal alias.\
-You design and build production-ready agent systems \
-from natural language requirements. You understand the Hive framework at the \
-source code level and create agents that are robust, well-tested, and follow \
-best practices. You collaborate with users to refine requirements, assess fit, \
-and deliver complete solutions. \
-You design and build the agent to do the job but don't do the job on your own
-"""
-
-_queen_identity_staging = """\
-You are a Solution Engineer preparing an agent for deployment. \
-"Queen" is your internal alias. \
-The agent is loaded and ready. \
-Your role is to verify configuration, confirm credentials, and ensure the user \
-understands what the agent will do. You guide the user through the final checks \
-before execution.
-"""
-
-_queen_identity_running = """\
-You are a Solution Engineer running agents on behalf of the user. \
-"Queen" is your internal alias. You monitor execution, handle \
-escalations when the agent gets stuck, and care deeply about outcomes. When the \
-agent finishes, you report results clearly and help the user decide what to do next.
-"""
-
-# -- Phase-specific tool docs --
-
-_queen_tools_building = """
-# Tools (BUILDING phase)
-
-You have full coding tools for building and modifying agents:
- File I/O: read_file, write_file, edit_file, list_directory, search_files, \
-run_command, undo_changes
- Meta-agent: list_agent_tools, validate_agent_package, \
-list_agents, list_agent_sessions, \
-list_agent_checkpoints, get_agent_checkpoint
- load_built_agent(agent_path) — Load the agent and switch to STAGING phase
- list_credentials(credential_id?) — List authorized credentials
-
-When you finish building an agent, call load_built_agent(path) to stage it.
-"""
-
-_queen_tools_staging = """
-# Tools (STAGING phase)
-
-The agent is loaded and ready to run. You can inspect it and launch it:
- Read-only: read_file, list_directory, search_files, run_command
- list_credentials(credential_id?) — Verify credentials are configured
- get_worker_status(focus?) — Brief status. Drill in with focus: memory, tools, issues, progress
- run_agent_with_input(task) — Start the worker and switch to RUNNING phase
- stop_worker_and_edit() — Go back to BUILDING phase
-
-You do NOT have write tools. If you need to modify the agent, \
-call stop_worker_and_edit() to go back to BUILDING phase.
-"""
-
-_queen_tools_running = """
-# Tools (RUNNING phase)
-
-The worker is running. You have monitoring and lifecycle tools:
- Read-only: read_file, list_directory, search_files, run_command
- get_worker_status(focus?) — Brief status. Drill in: activity, memory, tools, issues, progress
- inject_worker_message(content) — Send a message to the running worker
- get_worker_health_summary() — Read the latest health data
- notify_operator(ticket_id, analysis, urgency) — Alert the user (use sparingly)
- stop_worker() — Stop the worker and return to STAGING phase, then ask the user what to do next
- stop_worker_and_edit() — Stop the worker and switch back to BUILDING phase
-
-You do NOT have write tools or agent construction tools. \
-If you need to modify the agent, call stop_worker_and_edit() to switch back \
-to BUILDING phase. To stop the worker and ask the user what to do next, call \
-stop_worker() to return to STAGING phase.
-"""
-
-# -- Behavior shared across all phases --
-
-_queen_behavior_always = """
-# Behavior
-
-## CRITICAL RULE — ask_user tool
-
-Every response that ends with a question, a prompt, or expects user \
-input MUST finish with a call to ask_user(prompt, options). \
-The system CANNOT detect that you are waiting for \
-input unless you call ask_user. You MUST call ask_user as the LAST \
-action in your response.
-
-NEVER end a response with a question in text without calling ask_user. \
-NEVER rely on the user seeing your text and replying — call ask_user.
-
-Always provide 2-4 short options that cover the most likely answers. \
-The user can always type a custom response.
-
-Examples:
- ask_user("What do you need?",
-  ["Build a new agent", "Run the loaded worker", "Help with code"])
- ask_user("Which pattern?",
-  ["Simple 3-node", "Rich with feedback", "Custom"])
- ask_user("Ready to proceed?",
-  ["Yes, go ahead", "Let me change something"])
-
-## Greeting
-
-When the user greets you, respond concisely (under 10 lines) with worker \
-status only:
-1. Use plain, user-facing wording about load/run state; avoid internal phase \
-labels ("staging phase", "building phase", "running phase") unless the user \
-explicitly asks for phase details.
-2. If loaded, prefer this format: "<worker_name> has been loaded. <one sentence \
-on what it does from Worker Profile>."
-3. Do NOT include identity details unless the user explicitly asks about identity.
-4. THEN call ask_user to prompt them — do NOT just write text.
-5. Preferred loaded example:
-   local_business_extractor/*agent name*/ has been loaded. It finds local businesses on \
-Google Maps, extracts contact details, and syncs them to Google Sheets.
-   ask_user("Do you want to run it?", ["Yes, run it", "Check credentials first",
-            "Modify the worker"])
-
-## When user ask identity and responsibility
-
-Only answer identity when the user explicitly asks (for example: "who are you?", \
-"what is your identity?", "what does Queen mean?").
-1. Use the alias "Queen" and "Worker" in the response.
-2. Explain role/responsibility for the current phase:
-   - BUILDING: architect and implement agents.
-   - STAGING: verify readiness, credentials, and launch conditions.
-   - RUNNING: monitor execution, handle escalations, and report outcomes.
-3. Keep identity responses concise and do NOT include extra process details.
-"""
-
-# -- BUILDING phase behavior --
-
-_queen_behavior_building = """
-
-## Direct coding
-You can do any coding task directly — reading files, writing code, running \
-commands, building agents, debugging. For quick tasks, do them yourself.
-
-**Decision rule — if worker exists, read the Worker Profile first:**
- The user's request directly matches the worker's goal → use \
-run_agent_with_input(task) (if in staging) or load then run (if in building)
- Anything else → do it yourself. Do NOT reframe user requests into \
-subtasks to justify delegation.
- Building, modifying, or configuring agents is ALWAYS your job. Never \
-delegate agent construction to the worker, even as a "research" subtask.
-"""
-
-# -- STAGING phase behavior --
-
-_queen_behavior_staging = """
-## Worker delegation
-The worker is a specialized agent (see Worker Profile at the end of this \
-prompt). It can ONLY do what its goal and tools allow.
-
-**Decision rule — read the Worker Profile first:**
- The user's request directly matches the worker's goal → use \
-run_agent_with_input(task) (if in staging) or load then run (if in building)
- Anything else → do it yourself. Do NOT reframe user requests into \
-subtasks to justify delegation.
- Building, modifying, or configuring agents is ALWAYS your job. \
-Use stop_worker_and_edit when you need to.
-
-## When the user says "run", "execute", or "start" (without specifics)
-
-The loaded worker is described in the Worker Profile below. You MUST \
-ask the user what task or input they want using ask_user — do NOT \
-invent a task, do NOT call list_agents() or list directories. \
-The worker is already loaded. Just ask for the specific input the \
-worker needs (e.g., a research topic, a target domain, a job description). \
-NEVER call run_agent_with_input until the user has provided their input.
-
-If NO worker is loaded, say so and offer to build one.
-
-## When in staging phase (agent loaded, not running):
- Tell the user the agent is loaded and ready in plain language (for example, \
-"<worker_name> has been loaded.").
- Avoid lead-ins like "A worker is loaded and ready in staging phase: ...".
- For tasks matching the worker's goal: ALWAYS ask the user for their \
-specific input BEFORE calling run_agent_with_input(task). NEVER make up \
-or assume what the user wants. Use ask_user to collect the task details \
-(e.g., topic, target, requirements). Once you have the user's answer, \
-compose a structured task description from their input and call \
-run_agent_with_input(task). The worker has no intake node — it receives \
-your task and starts processing.
- If the user wants to modify the agent, call stop_worker_and_edit().
-
-## When idle (worker not running):
- Greet the user. Mention what the worker can do in one sentence.
- For tasks matching the worker's goal, use run_agent_with_input(task) \
-(if in staging) or load the agent first (if in building).
- For everything else, do it directly.
-
-## When the user clicks Run (external event notification)
-When you receive an event that the user clicked Run:
- If the worker started successfully, briefly acknowledge it — do NOT \
-repeat the full status. The user can see the graph is running.
- If the worker failed to start (credential or structural error), \
-explain the problem clearly and help fix it. For credential errors, \
-guide the user to set up the missing credentials. For structural \
-issues, offer to fix the agent graph directly.
-
-## Showing or describing the loaded worker
-
-When the user asks to "show the graph", "describe the agent", or \
-"re-generate the graph", read the Worker Profile and present the \
-worker's current architecture as an ASCII diagram. Use the processing \
-stages, tools, and edges from the loaded worker. Do NOT enter the \
-agent building workflow — you are describing what already exists, not \
-building something new.
-
-## Modifying the loaded worker
-
-When the user asks to change, modify, or update the loaded worker \
-(e.g., "change the report node", "add a node", "delete node X"):
-
-1. Call stop_worker_and_edit() — this stops the worker and gives you \
-coding tools (switches to BUILDING phase).
-"""
-
-# -- RUNNING phase behavior --
-
-_queen_behavior_running = """
-## When worker is running — queen is the only user interface
-
-After run_agent_with_input(task), the worker should run autonomously and \
-talk to YOU (queen) via  when blocked. The worker should \
-NOT ask the user directly.
-
-You wake up when:
- The user explicitly addresses you
- A worker escalation arrives (`[WORKER_ESCALATION_REQUEST]`)
- An escalation ticket arrives from the judge
- The worker finishes (`[WORKER_TERMINAL]`)
-
-If the user asks for progress, call get_worker_status() ONCE and report. \
-If the summary mentions issues, follow up with get_worker_status(focus="issues").
-
-## Handling worker termination ([WORKER_TERMINAL])
-
-When you receive a `[WORKER_TERMINAL]` event, the worker has finished:
-
-1. **Report to the user** — Summarize what the worker accomplished (from the \
-output keys) or explain the failure (from the error message).
-
-2. **Ask what's next** — Use ask_user to offer options:
-   - If successful: "Run again with new input", "Modify the agent", "Done for now"
-   - If failed: "Retry with same input", "Debug/modify the agent", "Done for now"
-
-3. **Default behavior** — Always report and wait for user direction. Only \
-start another run if the user EXPLICITLY asks to continue.
-
-Example response:
-> "The worker finished. It found 5 relevant articles and saved them to \
-output.md.
->
-> What would you like to do next?"
-> [ask_user with options]
-
-## Handling worker escalations ([WORKER_ESCALATION_REQUEST])
-
-When a worker escalation arrives, read the reason/context and handle by type. \
-IMPORTANT: Only auto-handle if the user has NOT explicitly told you how to handle \
-escalations. If the user gave you instructions (e.g., "just retry on errors", \
-"skip any auth issues"), follow those instructions instead.
-
-**Auth blocks / credential issues:**
- ALWAYS ask the user (unless user explicitly told you how to handle this).
- The worker cannot proceed without valid credentials.
- Explain which credential is missing or invalid.
- Use ask_user to get guidance: "Provide credentials", "Skip this task", "Stop and edit agent"
- Use inject_worker_message() to relay user decisions back to the worker.
-
-**Need human review / approval:**
- ALWAYS ask the user (unless user explicitly told you how to handle this).
- The worker is explicitly requesting human judgment.
- Present the context clearly (what decision is needed, what are the options).
- Use ask_user with the actual decision options.
- Use inject_worker_message() to relay user decisions back to the worker.
-
-**Errors / unexpected failures:**
- Explain what went wrong in plain terms.
- Ask the user: "Fix the agent and retry?" → use stop_worker_and_edit() if yes.
- Or offer: "Retry as-is", "Skip this task", "Abort run"
- (Skip asking if user explicitly told you to auto-retry or auto-skip errors.)
-
-**Informational / progress updates:**
- Acknowledge briefly and let the worker continue.
- Only interrupt the user if the escalation is truly important.
-
-## Showing or describing the loaded worker
-
-When the user asks to "show the graph", "describe the agent", or \
-"re-generate the graph", read the Worker Profile and present the \
-worker's current architecture as an ASCII diagram. Use the processing \
-stages, tools, and edges from the loaded worker. Do NOT enter the \
-agent building workflow — you are describing what already exists, not \
-building something new.
-
- Call get_worker_status(focus="issues") for more details when needed.
-
-## Modifying the loaded worker
-
-When the user asks to change, modify, or update the loaded worker \
-(e.g., "change the report node", "add a node", "delete node X"):
-
-1. Call stop_worker_and_edit() — this stops the worker and gives you \
-coding tools (switches to BUILDING phase).
-"""
-
-# -- Backward-compatible composed versions (used by queen_node.system_prompt default) --
-
-_queen_tools_docs = (
-    "\n\n## Queen Operating Phases\n\n"
-    "You operate in one of three phases. Your available tools change based on the "
-    "phase. The system notifies you when a phase change occurs.\n\n"
-    "### BUILDING phase (default)\n"
-    + _queen_tools_building.strip()
-    + "\n\n### STAGING phase (agent loaded, not yet running)\n"
-    + _queen_tools_staging.strip()
-    + "\n\n### RUNNING phase (worker is executing)\n"
-    + _queen_tools_running.strip()
-    + "\n\n### Phase transitions\n"
-    "- load_built_agent(path) → switches to STAGING phase\n"
-    "- run_agent_with_input(task) → starts worker, switches to RUNNING phase\n"
-    "- stop_worker() → stops worker, switches to STAGING phase (ask user: re-run or edit?)\n"
-    "- stop_worker_and_edit() → stops worker (if running), switches to BUILDING phase\n"
-)
-
-_queen_behavior = (
-    _queen_behavior_always
-    + _queen_behavior_building
-    + _queen_behavior_staging
-    + _queen_behavior_running
-)
-
-_queen_phase_7 = """
-## Running the Agent
-
-After validation passes and load_built_agent succeeds (STAGING phase), \
-offer to run the agent. Call run_agent_with_input(task) to start it. \
-Do NOT tell the user to run `python -m {name} run` — run it here.
-"""
-
-_queen_style = """
-# Style
- Responsible and thoughtful
- Concise. No fluff. Direct. No emojis.
- When starting the worker, describe what you told it in one sentence.
- When an escalation arrives, lead with severity and recommended action.
-"""
-
-
-# ---------------------------------------------------------------------------
-# Node definitions
-# ---------------------------------------------------------------------------
-
-# Single node — like opencode's while(true) loop.
-# One continuous context handles the entire workflow:
-# discover → design → implement → verify → present → iterate.
-coder_node = NodeSpec(
-    id="coder",
-    name="Hive Coder",
-    description=(
-        "Autonomous coding agent that builds Hive agent packages. "
-        "Handles the full lifecycle: understanding user intent, "
-        "designing architecture, writing code, validating, and "
-        "iterating on feedback — all in one continuous conversation."
-    ),
-    node_type="event_loop",
-    client_facing=True,
-    max_node_visits=0,
-    input_keys=["user_request"],
-    output_keys=["agent_name", "validation_result"],
-    success_criteria=(
-        "A complete, validated Hive agent package exists at "
-        "exports/{agent_name}/ and passes structural validation."
-    ),
-    tools=_SHARED_TOOLS
-    + [
-        # Graph lifecycle tools (multi-graph sessions)
-        "load_agent",
-        "unload_agent",
-        "start_agent",
-        "restart_agent",
-        "get_user_presence",
-    ],
-    system_prompt=(
-        "You are Hive Coder, the best agent-building coding agent. You build "
-        "production-ready Hive agent packages from natural language.\n"
-        + _package_builder_knowledge
-        + _gcu_building_section
-        + _appendices
-    ),
-)
-
-
-ticket_triage_node = NodeSpec(
-    id="ticket_triage",
-    name="Ticket Triage",
-    description=(
-        "Queen's triage node. Receives an EscalationTicket from the Health Judge "
-        "via event-driven entry point and decides: dismiss or notify the operator."
-    ),
-    node_type="event_loop",
-    client_facing=True,  # Operator can chat with queen once connected (Ctrl+Q)
-    max_node_visits=0,
-    input_keys=["ticket"],
-    output_keys=["intervention_decision"],
-    nullable_output_keys=["intervention_decision"],
-    success_criteria=(
-        "A clear intervention decision: either dismissed with documented reasoning, "
-        "or operator notified via notify_operator with specific analysis."
-    ),
-    tools=["notify_operator"],
-    system_prompt="""\
-You are the Queen (Hive Coder). The Worker Health Judge has escalated a worker \
-issue to you. The ticket is in your memory under key "ticket". Read it carefully.
-
-## Dismiss criteria — do NOT call notify_operator:
- severity is "low" AND steps_since_last_accept < 8
- Cause is clearly a transient issue (single API timeout, brief stall that \
-  self-resolved based on the evidence)
- Evidence shows the agent is making real progress despite bad verdicts
-
-## Intervene criteria — call notify_operator:
- severity is "high" or "critical"
- steps_since_last_accept >= 10 with no sign of recovery
- stall_minutes > 4 (worker definitively stuck)
- Evidence shows a doom loop (same error, same tool, no progress)
- Cause suggests a logic bug, missing configuration, or unrecoverable state
-
-## When intervening:
-Call notify_operator with:
-  ticket_id: <ticket["ticket_id"]>
-  analysis: "<2-3 sentences: what is wrong, why it matters, suggested action>"
-  urgency: "<low|medium|high|critical>"
-
-## After deciding:
-set_output("intervention_decision", "dismissed: <reason>" or "escalated: <summary>")
-
-Be conservative but not passive. You are the last quality gate before the human \
-is disturbed. One unnecessary alert is less costly than alert fatigue — but \
-genuine stuck agents must be caught.
-""",
-)
-
-ALL_QUEEN_TRIAGE_TOOLS = ["notify_operator"]
-
-
-queen_node = NodeSpec(
-    id="queen",
-    name="Queen",
-    description=(
-        "User's primary interactive interface with full coding capability. "
-        "Can build agents directly or delegate to the worker. Manages the "
-        "worker agent lifecycle and triages health escalations from the judge."
-    ),
-    node_type="event_loop",
-    client_facing=True,
-    max_node_visits=0,
-    input_keys=["greeting"],
-    output_keys=[],  # Queen should never have this
-    nullable_output_keys=[],  # Queen should never have this
-    skip_judge=True,  # Queen is a conversational agent; suppress tool-use pressure feedback
-    tools=sorted(set(_QUEEN_BUILDING_TOOLS + _QUEEN_STAGING_TOOLS + _QUEEN_RUNNING_TOOLS)),
-    system_prompt=(
-        _queen_identity_building
-        + _queen_style
-        + _package_builder_knowledge
-        + _gcu_building_section  # GCU as first-class citizen (not appendix)
-        + _queen_tools_docs
-        + _queen_behavior
-        + _queen_phase_7
-        + _appendices
-    ),
-)
-
-ALL_QUEEN_TOOLS = sorted(set(_QUEEN_BUILDING_TOOLS + _QUEEN_STAGING_TOOLS + _QUEEN_RUNNING_TOOLS))
-
-__all__ = [
-    "coder_node",
-    "ticket_triage_node",
-    "queen_node",
-    "ALL_QUEEN_TRIAGE_TOOLS",
-    "ALL_QUEEN_TOOLS",
-    "_QUEEN_BUILDING_TOOLS",
-    "_QUEEN_STAGING_TOOLS",
-    "_QUEEN_RUNNING_TOOLS",
-    # Phase-specific prompt segments (used by session_manager for dynamic prompts)
-    "_queen_identity_building",
-    "_queen_identity_staging",
-    "_queen_identity_running",
-    "_queen_tools_building",
-    "_queen_tools_staging",
-    "_queen_tools_running",
-    "_queen_behavior_always",
-    "_queen_behavior_building",
-    "_queen_behavior_staging",
-    "_queen_behavior_running",
-    "_queen_phase_7",
-    "_queen_style",
-    "_package_builder_knowledge",
-    "_appendices",
-    "_gcu_building_section",
-]
@@ -1,27 +0,0 @@
-"""Queen's ticket receiver entry point.
-
-When the Worker Health Judge emits a WORKER_ESCALATION_TICKET event on the
-shared EventBus, this entry point fires and routes to the ``ticket_triage``
-node, where the Queen deliberates and decides whether to notify the operator.
-
-Isolation level is ``isolated`` — the queen's triage memory is kept separate
-from the worker's shared memory. Each ticket triage runs in its own context.
-"""
-
-from __future__ import annotations
-
-from framework.graph.edge import AsyncEntryPointSpec
-
-TICKET_RECEIVER_ENTRY_POINT = AsyncEntryPointSpec(
-    id="ticket_receiver",
-    name="Worker Escalation Ticket Receiver",
-    entry_node="ticket_triage",
-    trigger_type="event",
-    trigger_config={
-        "event_types": ["worker_escalation_ticket"],
-        # Do not fire on our own graph's events (prevents loops if queen
-        # somehow emits a worker_escalation_ticket for herself)
-        "exclude_own_graph": True,
-    },
-    isolation_level="isolated",
-)
@@ -0,0 +1,21 @@
+"""
+Queen — Native agent builder for the Hive framework.
+
+Deeply understands the agent framework and produces complete Python packages
+with goals, nodes, edges, system prompts, MCP configuration, and tests
+from natural language specifications.
+"""
+
+from .agent import queen_goal, queen_graph
+from .config import AgentMetadata, RuntimeConfig, default_config, metadata
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "queen_goal",
+    "queen_graph",
+    "RuntimeConfig",
+    "AgentMetadata",
+    "default_config",
+    "metadata",
+]
@@ -0,0 +1,38 @@
+"""Queen graph definition."""
+
+from framework.graph import Goal
+from framework.graph.edge import GraphSpec
+
+from .nodes import queen_node
+
+# ---------------------------------------------------------------------------
+# Queen graph — the primary persistent conversation.
+# Loaded by queen_orchestrator.create_queen(), NOT by AgentRunner.
+# ---------------------------------------------------------------------------
+
+queen_goal = Goal(
+    id="queen-manager",
+    name="Queen Manager",
+    description=(
+        "Manage the worker agent lifecycle and serve as the user's primary interactive interface."
+    ),
+    success_criteria=[],
+    constraints=[],
+)
+
+queen_graph = GraphSpec(
+    id="queen-graph",
+    goal_id=queen_goal.id,
+    version="1.0.0",
+    entry_node="queen",
+    entry_points={"start": "queen"},
+    terminal_nodes=[],
+    pause_nodes=[],
+    nodes=[queen_node],
+    edges=[],
+    conversation_mode="continuous",
+    loop_config={
+        "max_iterations": 999_999,
+        "max_tool_calls_per_turn": 30,
+    },
+)
@@ -1,4 +1,4 @@
-"""Runtime configuration for Hive Coder agent."""
+"""Runtime configuration for Queen agent."""

 import json
 from dataclasses import dataclass, field
@@ -34,7 +34,7 @@ default_config = RuntimeConfig()

@dataclass
 class AgentMetadata:
-    name: str = "Hive Coder"
+    name: str = "Queen"
    version: str = "1.0.0"
    description: str = (
        "Native coding agent that builds production-ready Hive agent packages "
@@ -43,7 +43,7 @@ class AgentMetadata:
        "MCP configuration, and tests."
    )
    intro_message: str = (
-        "I'm Hive Coder — I build Hive agents. Describe what kind of agent "
+        "I'm Queen — I build Hive agents. Describe what kind of agent "
        "you want to create and I'll design, implement, and validate it for you."
    )

@@ -0,0 +1,553 @@
+"""Shared memory helpers for queen/worker recall and reflection.
+
+Each memory is an individual ``.md`` file in ``~/.hive/queen/memories/``
+with optional YAML frontmatter (name, type, description).  Frontmatter
+is a convention enforced by prompt instructions — parsing is lenient and
+malformed files degrade gracefully (appear in scans with ``None`` metadata).
+
+Cursor-based incremental processing tracks which conversation messages
+have already been processed by the reflection agent.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+import shutil
+import time
+from dataclasses import dataclass, field
+from datetime import date
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+MEMORY_TYPES: tuple[str, ...] = ("goal", "environment", "technique", "reference", "diary")
+GLOBAL_MEMORY_CATEGORIES: tuple[str, ...] = ("profile", "preference", "environment", "feedback")
+
+_HIVE_QUEEN_DIR = Path.home() / ".hive" / "queen"
+# Legacy shared v2 root.  Colony memory now lives under queen sessions.
+MEMORY_DIR: Path = _HIVE_QUEEN_DIR / "memories"
+
+MAX_FILES: int = 200
+MAX_FILE_SIZE_BYTES: int = 4096  # 4 KB hard limit per memory file
+
+# How many lines of a memory file to read for header scanning.
+_HEADER_LINE_LIMIT: int = 30
+_MIGRATION_MARKER = ".migrated-from-shared-memory"
+_GLOBAL_MEMORY_CODE_PATTERN = re.compile(
+    r"(/Users/|~/.hive|\.py\b|\.ts\b|\.tsx\b|\.js\b|"
+    r"\b(graph|node|runtime|session|execution|worker|queen|subagent|checkpoint|flowchart)\b)",
+    re.IGNORECASE,
+)
+
+# Frontmatter example provided to the reflection agent via prompt.
+MEMORY_FRONTMATTER_EXAMPLE: list[str] = [
+    "```markdown",
+    "---",
+    "name: {{memory name}}",
+    (
+        "description: {{one-line description — used to decide "
+        "relevance in future conversations, so be specific}}"
+    ),
+    f"type: {{{{{', '.join(MEMORY_TYPES)}}}}}",
+    "---",
+    "",
+    (
+        "{{memory content — for feedback/project types, "
+        "structure as: rule/fact, then **Why:** "
+        "and **How to apply:** lines}}"
+    ),
+    "```",
+]
+
+
+def colony_memory_dir(colony_id: str) -> Path:
+    """Return the colony memory directory for a queen session."""
+    return _HIVE_QUEEN_DIR / "session" / colony_id / "memory" / "colony"
+
+
+def global_memory_dir() -> Path:
+    """Return the queen-global memory directory."""
+    return _HIVE_QUEEN_DIR / "global_memory"
+
+
+# ---------------------------------------------------------------------------
+# Frontmatter parsing (lenient)
+# ---------------------------------------------------------------------------
+
+_FRONTMATTER_RE = re.compile(r"^---\s*\n(.*?)\n---\s*\n?", re.DOTALL)
+
+
+def parse_frontmatter(text: str) -> dict[str, str]:
+    """Extract YAML-ish frontmatter from *text*.
+
+    Returns a dict of key-value pairs.  Never raises — returns ``{}`` on
+    any parse failure.  Values are stripped strings; no nested structures.
+    """
+    m = _FRONTMATTER_RE.match(text)
+    if not m:
+        return {}
+    result: dict[str, str] = {}
+    for line in m.group(1).splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        colon = line.find(":")
+        if colon < 1:
+            continue
+        key = line[:colon].strip().lower()
+        val = line[colon + 1 :].strip()
+        if val:
+            result[key] = val
+    return result
+
+
+def parse_memory_type(raw: str | None) -> str | None:
+    """Validate *raw* against supported memory categories."""
+    if raw is None:
+        return None
+    normalized = raw.strip().lower()
+    allowed = set(MEMORY_TYPES) | set(GLOBAL_MEMORY_CATEGORIES)
+    return normalized if normalized in allowed else None
+
+
+def parse_global_memory_category(raw: str | None) -> str | None:
+    """Validate *raw* against ``GLOBAL_MEMORY_CATEGORIES``."""
+    if raw is None:
+        return None
+    normalized = raw.strip().lower()
+    return normalized if normalized in GLOBAL_MEMORY_CATEGORIES else None
+
+
+# ---------------------------------------------------------------------------
+# MemoryFile dataclass
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class MemoryFile:
+    """Parsed representation of a single memory file on disk."""
+
+    filename: str
+    path: Path
+    # Frontmatter fields — all nullable (lenient parsing).
+    name: str | None = None
+    type: str | None = None
+    description: str | None = None
+    # First N lines of the file (for manifest / header scanning).
+    header_lines: list[str] = field(default_factory=list)
+    # Filesystem modification time (seconds since epoch).
+    mtime: float = 0.0
+
+    @classmethod
+    def from_path(cls, path: Path) -> MemoryFile:
+        """Read a memory file and leniently parse its frontmatter."""
+        try:
+            text = path.read_text(encoding="utf-8")
+        except OSError:
+            return cls(filename=path.name, path=path)
+
+        fm = parse_frontmatter(text)
+        lines = text.splitlines()[:_HEADER_LINE_LIMIT]
+
+        try:
+            mtime = path.stat().st_mtime
+        except OSError:
+            mtime = 0.0
+
+        return cls(
+            filename=path.name,
+            path=path,
+            name=fm.get("name"),
+            type=parse_memory_type(fm.get("type")),
+            description=fm.get("description"),
+            header_lines=lines,
+            mtime=mtime,
+        )
+
+
+# ---------------------------------------------------------------------------
+# Scanning
+# ---------------------------------------------------------------------------
+
+
+def scan_memory_files(memory_dir: Path | None = None) -> list[MemoryFile]:
+    """Scan *memory_dir* for ``.md`` files, returning up to ``MAX_FILES``.
+
+    Files are sorted by modification time (newest first).  Dotfiles and
+    subdirectories are ignored.
+    """
+    d = memory_dir or MEMORY_DIR
+    if not d.is_dir():
+        return []
+
+    md_files = sorted(
+        (f for f in d.glob("*.md") if f.is_file() and not f.name.startswith(".")),
+        key=lambda p: p.stat().st_mtime,
+        reverse=True,
+    )
+
+    return [MemoryFile.from_path(f) for f in md_files[:MAX_FILES]]
+
+
+def slugify_memory_name(raw: str) -> str:
+    """Create a filesystem-safe slug for a memory filename."""
+    slug = re.sub(r"[^a-z0-9]+", "-", raw.strip().lower()).strip("-")
+    return slug or "memory"
+
+
+def allocate_memory_filename(
+    memory_dir: Path,
+    name: str,
+    *,
+    suffix: str = ".md",
+) -> str:
+    """Allocate a unique filename in *memory_dir* based on *name*."""
+    base = slugify_memory_name(name)
+    candidate = f"{base}{suffix}"
+    counter = 2
+    while (memory_dir / candidate).exists():
+        candidate = f"{base}-{counter}{suffix}"
+        counter += 1
+    return candidate
+
+
+def build_memory_document(
+    *,
+    name: str,
+    description: str,
+    mem_type: str,
+    body: str,
+) -> str:
+    """Build one memory file with frontmatter and body."""
+    return (
+        f"---\n"
+        f"name: {name.strip()}\n"
+        f"description: {description.strip()}\n"
+        f"type: {mem_type.strip()}\n"
+        f"---\n\n"
+        f"{body.strip()}\n"
+    )
+
+
+def diary_filename(d: date | None = None) -> str:
+    """Return the diary memory filename for date *d* (default: today)."""
+    d = d or date.today()
+    return f"MEMORY-{d.strftime('%Y-%m-%d')}.md"
+
+
+def build_diary_document(*, date_str: str, body: str) -> str:
+    """Build a diary memory file with frontmatter."""
+    return build_memory_document(
+        name=f"diary-{date_str}",
+        description=f"Daily session narrative for {date_str}",
+        mem_type="diary",
+        body=body,
+    )
+
+
+def validate_global_memory_payload(
+    *,
+    category: str,
+    description: str,
+    content: str,
+) -> str:
+    """Validate a queen-global memory save request."""
+    parsed = parse_global_memory_category(category)
+    if parsed is None:
+        raise ValueError(
+            "Invalid global memory category. Use one of: "
+            + ", ".join(GLOBAL_MEMORY_CATEGORIES)
+        )
+    if not description.strip():
+        raise ValueError("Global memory description cannot be empty.")
+    if not content.strip():
+        raise ValueError("Global memory content cannot be empty.")
+
+    probe = f"{description}\n{content}"
+    if _GLOBAL_MEMORY_CODE_PATTERN.search(probe):
+        raise ValueError(
+            "Global memory is only for durable user profile, preferences, "
+            "environment, or feedback — not task/code/runtime details."
+        )
+    return parsed
+
+
+def save_global_memory(
+    *,
+    category: str,
+    description: str,
+    content: str,
+    name: str | None = None,
+    memory_dir: Path | None = None,
+) -> tuple[str, Path]:
+    """Persist one queen-global memory entry."""
+    parsed = validate_global_memory_payload(
+        category=category,
+        description=description,
+        content=content,
+    )
+    target_dir = memory_dir or global_memory_dir()
+    target_dir.mkdir(parents=True, exist_ok=True)
+    memory_name = (name or description).strip()
+    filename = allocate_memory_filename(target_dir, memory_name)
+    doc = build_memory_document(
+        name=memory_name,
+        description=description,
+        mem_type=parsed,
+        body=content,
+    )
+    if len(doc.encode("utf-8")) > MAX_FILE_SIZE_BYTES:
+        raise ValueError(
+            f"Global memory entry exceeds the {MAX_FILE_SIZE_BYTES} byte limit."
+        )
+    path = target_dir / filename
+    path.write_text(doc, encoding="utf-8")
+    return filename, path
+
+
+# ---------------------------------------------------------------------------
+# Manifest formatting
+# ---------------------------------------------------------------------------
+
+def _age_label(mtime: float) -> str:
+    """Human-readable age string from an mtime."""
+    age_days = memory_age_days(mtime)
+    if age_days <= 0:
+        return "today"
+    if age_days == 1:
+        return "1 day ago"
+    return f"{age_days} days ago"
+
+
+def format_memory_manifest(files: list[MemoryFile]) -> str:
+    """One-line-per-file text manifest for the recall selector / reflection agent.
+
+    Format: ``[type] filename (age): description``
+    """
+    lines: list[str] = []
+    for mf in files:
+        t = mf.type or "unknown"
+        desc = mf.description or "(no description)"
+        age = _age_label(mf.mtime)
+        lines.append(f"[{t}] {mf.filename} ({age}): {desc}")
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# Freshness / staleness
+# ---------------------------------------------------------------------------
+
+_SECONDS_PER_DAY = 86_400
+
+
+def memory_age_days(mtime: float) -> int:
+    """Return the age of a memory file in whole days."""
+    if mtime <= 0:
+        return 0
+    return int((time.time() - mtime) / _SECONDS_PER_DAY)
+
+
+def memory_freshness_text(mtime: float) -> str:
+    """Return a staleness warning for injection, or empty string if fresh."""
+    d = memory_age_days(mtime)
+    if d <= 1:
+        return ""
+    return (
+        f"This memory is {d} days old. "
+        "Memories are point-in-time observations, not live state — "
+        "claims about code behavior or file:line citations may be outdated. "
+        "Verify against current code before asserting as fact."
+    )
+
+
+# ---------------------------------------------------------------------------
+# Cursor-based incremental processing
+# ---------------------------------------------------------------------------
+
+
+async def read_conversation_parts(session_dir: Path) -> list[dict[str, Any]]:
+    """Read all conversation parts for a session using FileConversationStore.
+
+    Returns a list of raw message dicts in sequence order.
+    """
+    from framework.storage.conversation_store import FileConversationStore
+
+    store = FileConversationStore(session_dir / "conversations")
+    return await store.read_parts()
+
+
+# ---------------------------------------------------------------------------
+# Initialisation and legacy migration
+# ---------------------------------------------------------------------------
+
+
+def init_memory_dir(
+    memory_dir: Path | None = None,
+    *,
+    migrate_legacy: bool = False,
+) -> None:
+    """Create the memory directory if missing.
+
+    When ``migrate_legacy`` is true, migrate both v1 memory files and the
+    previous shared v2 queen memory store into this directory.
+    """
+    d = memory_dir or MEMORY_DIR
+    first_run = not d.exists()
+    d.mkdir(parents=True, exist_ok=True)
+    if migrate_legacy:
+        migrate_legacy_memories(d)
+        migrate_shared_v2_memories(d)
+    elif first_run and d == MEMORY_DIR:
+        migrate_legacy_memories(d)
+
+
+def migrate_legacy_memories(memory_dir: Path | None = None) -> None:
+    """Convert old MEMORY.md + MEMORY-YYYY-MM-DD.md files to individual memory files.
+
+    Originals are moved to ``{memory_dir}/.legacy/``.
+    """
+    d = memory_dir or MEMORY_DIR
+    queen_dir = _HIVE_QUEEN_DIR
+    legacy_archive = d / ".legacy"
+
+    migrated_any = False
+
+    # --- Semantic memory (MEMORY.md) ---
+    semantic = queen_dir / "MEMORY.md"
+    if semantic.exists():
+        content = semantic.read_text(encoding="utf-8").strip()
+        # Skip the blank seed template.
+        if content and not content.startswith("# My Understanding of the User\n\n*No sessions"):
+            _write_migration_file(
+                d,
+                filename="legacy-semantic-memory.md",
+                name="legacy-semantic-memory",
+                mem_type="reference",
+                description="Migrated semantic memory from previous memory system",
+                body=content,
+            )
+            migrated_any = True
+        # Archive original.
+        legacy_archive.mkdir(parents=True, exist_ok=True)
+        semantic.rename(legacy_archive / "MEMORY.md")
+
+    # --- Episodic memories (MEMORY-YYYY-MM-DD.md) ---
+    old_memories_dir = queen_dir / "memories"
+    if old_memories_dir.is_dir():
+        for ep_file in sorted(old_memories_dir.glob("MEMORY-*.md")):
+            content = ep_file.read_text(encoding="utf-8").strip()
+            if not content:
+                continue
+            date_part = ep_file.stem.replace("MEMORY-", "")
+            slug = f"legacy-diary-{date_part}.md"
+            _write_migration_file(
+                d,
+                filename=slug,
+                name=f"legacy-diary-{date_part}",
+                mem_type="diary",
+                description=f"Migrated diary entry from {date_part}",
+                body=content,
+            )
+            migrated_any = True
+            # Archive original.
+            legacy_archive.mkdir(parents=True, exist_ok=True)
+            ep_file.rename(legacy_archive / ep_file.name)
+
+    if migrated_any:
+        logger.info("queen_memory_v2: migrated legacy memory files to %s", d)
+
+
+def migrate_shared_v2_memories(
+    memory_dir: Path | None = None,
+    *,
+    source_dir: Path | None = None,
+) -> None:
+    """Move shared queen v2 memory files into a colony directory once."""
+    d = memory_dir or MEMORY_DIR
+    d.mkdir(parents=True, exist_ok=True)
+    src = source_dir or MEMORY_DIR
+    if d.resolve() == src.resolve():
+        return
+
+    marker = d / _MIGRATION_MARKER
+    if marker.exists():
+        return
+
+    if not src.is_dir():
+        return
+
+    md_files = sorted(
+        f for f in src.glob("*.md")
+        if f.is_file() and not f.name.startswith(".")
+    )
+    if not md_files:
+        marker.write_text("no shared memories found\n", encoding="utf-8")
+        return
+
+    archive = src / ".legacy_colony_migration"
+    archive.mkdir(parents=True, exist_ok=True)
+    migrated_any = False
+
+    for src_file in md_files:
+        target = d / src_file.name
+        if not target.exists():
+            try:
+                shutil.copy2(src_file, target)
+                migrated_any = True
+            except OSError:
+                logger.debug("shared memory migration copy failed for %s", src_file, exc_info=True)
+                continue
+
+        archived = archive / src_file.name
+        counter = 2
+        while archived.exists():
+            archived = archive / f"{src_file.stem}-{counter}{src_file.suffix}"
+            counter += 1
+        try:
+            src_file.rename(archived)
+        except OSError:
+            logger.debug("shared memory migration archive failed for %s", src_file, exc_info=True)
+
+    if migrated_any:
+        logger.info("queen_memory_v2: migrated shared queen memories to %s", d)
+    marker.write_text(
+        f"migrated_at={int(time.time())}\nsource={src}\n",
+        encoding="utf-8",
+    )
+
+
+def _write_migration_file(
+    memory_dir: Path,
+    filename: str,
+    name: str,
+    mem_type: str,
+    description: str,
+    body: str,
+) -> None:
+    """Write a single migrated memory file with frontmatter."""
+    # Truncate body to respect file size limit (leave room for frontmatter).
+    header = (
+        f"---\n"
+        f"name: {name}\n"
+        f"description: {description}\n"
+        f"type: {mem_type}\n"
+        f"---\n\n"
+    )
+    max_body = MAX_FILE_SIZE_BYTES - len(header.encode("utf-8"))
+    if len(body.encode("utf-8")) > max_body:
+        # Rough truncation — cut at character level then trim to last newline.
+        body = body[: max_body - 20]
+        nl = body.rfind("\n")
+        if nl > 0:
+            body = body[:nl]
+        body += "\n\n...(truncated during migration)"
+
+    path = memory_dir / filename
+    path.write_text(header + body + "\n", encoding="utf-8")
@@ -0,0 +1,236 @@
+"""Recall selector — pre-turn memory selection for queen and worker memory.
+
+Before each conversation turn the system:
+  1. Scans the memory directory for ``.md`` files (cap: 200).
+  2. Reads headers (frontmatter + first 30 lines).
+  3. Uses a single LLM call with structured JSON output to pick the ~5
+     most relevant memories.
+  4. Injects them into context with staleness warnings for older ones.
+
+The selector only sees the user's query string — no full conversation
+context.  This keeps it cheap and fast.  Errors are caught and return
+``[]`` so the main conversation is never blocked.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from pathlib import Path
+from typing import Any
+
+from framework.agents.queen.queen_memory_v2 import (
+    MEMORY_DIR,
+    format_memory_manifest,
+    memory_freshness_text,
+    scan_memory_files,
+)
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Structured output schema
+# ---------------------------------------------------------------------------
+
+RECALL_SCHEMA: dict[str, Any] = {
+    "type": "json_schema",
+    "json_schema": {
+        "name": "memory_selection",
+        "strict": True,
+        "schema": {
+            "type": "object",
+            "properties": {
+                "selected_memories": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                },
+            },
+            "required": ["selected_memories"],
+            "additionalProperties": False,
+        },
+    },
+}
+
+# ---------------------------------------------------------------------------
+# System prompt
+# ---------------------------------------------------------------------------
+
+SELECT_MEMORIES_SYSTEM_PROMPT = """\
+You are selecting memories that will be useful to the Queen agent as it \
+processes a user's query.
+
+You will be given the user's query and a list of available memory files \
+with their filenames and descriptions.
+
+Return a JSON object with a single key "selected_memories" containing a \
+list of filenames for the memories that will clearly be useful as the \
+Queen processes the user's query (up to 5).
+
+Only include memories that you are certain will be helpful based on their \
+name and description.
+- If you are unsure if a memory will be useful in processing the user's \
+query, then do not include it in your list.  Be selective and discerning.
+- If there are no memories in the list that would clearly be useful, \
+return an empty list.
+- If a list of recently-used tools is provided, do not select memories \
+that are usage reference or API documentation for those tools (the Queen \
+is already exercising them).  Still select warnings or gotchas about them.
+"""
+
+# ---------------------------------------------------------------------------
+# Core functions
+# ---------------------------------------------------------------------------
+
+
+async def select_memories(
+    query: str,
+    llm: Any,
+    memory_dir: Path | None = None,
+    active_tools: list[str] | None = None,
+    *,
+    max_results: int = 5,
+) -> list[str]:
+    """Select up to 5 relevant memory filenames for *query*.
+
+    Returns a list of filenames.  Best-effort: on any error returns ``[]``.
+    """
+    mem_dir = memory_dir or MEMORY_DIR
+    files = scan_memory_files(mem_dir)
+    if not files:
+        logger.debug("recall: no memory files found, skipping selection")
+        return []
+
+    logger.debug("recall: selecting from %d memory files for query: %.80s", len(files), query)
+    manifest = format_memory_manifest(files)
+
+    user_msg_parts = [f"## User query\n\n{query}\n\n## Available memories\n\n{manifest}"]
+    if active_tools:
+        user_msg_parts.append(f"\n\n## Recently-used tools\n\n{', '.join(active_tools)}")
+
+    user_msg = "".join(user_msg_parts)
+
+    try:
+        resp = await llm.acomplete(
+            messages=[{"role": "user", "content": user_msg}],
+            system=SELECT_MEMORIES_SYSTEM_PROMPT,
+            max_tokens=512,
+            response_format=RECALL_SCHEMA,
+        )
+        data = json.loads(resp.content)
+        selected = data.get("selected_memories", [])
+        # Validate: only return filenames that actually exist.
+        valid_names = {f.filename for f in files}
+        result = [s for s in selected if s in valid_names][:max_results]
+        logger.debug("recall: selected %d memories: %s", len(result), result)
+        return result
+    except Exception:
+        logger.debug("recall: memory selection failed, returning []", exc_info=True)
+        return []
+
+
+def format_recall_injection(
+    filenames: list[str],
+    memory_dir: Path | None = None,
+    *,
+    heading: str = "Selected Memories",
+) -> str:
+    """Read selected memory files and format for system prompt injection.
+
+    Prepends a staleness warning for memories older than 1 day.
+    """
+    mem_dir = memory_dir or MEMORY_DIR
+    if not filenames:
+        return ""
+
+    blocks: list[str] = []
+    for fname in filenames:
+        path = mem_dir / fname
+        if not path.is_file():
+            continue
+        try:
+            content = path.read_text(encoding="utf-8").strip()
+        except OSError:
+            continue
+
+        try:
+            mtime = path.stat().st_mtime
+        except OSError:
+            mtime = 0.0
+
+        freshness = memory_freshness_text(mtime)
+        header = f"### {fname}"
+        if freshness:
+            header += f"\n\n> {freshness}"
+        blocks.append(f"{header}\n\n{content}")
+
+    if not blocks:
+        return ""
+
+    body = "\n\n---\n\n".join(blocks)
+    logger.debug("recall: injecting %d memory blocks into context", len(blocks))
+    return f"--- {heading} ---\n\n{body}\n\n--- End {heading} ---"
+
+
+# ---------------------------------------------------------------------------
+# Cache update (called after each queen turn)
+# ---------------------------------------------------------------------------
+
+
+async def update_recall_cache(
+    session_dir: Path,
+    llm: Any,
+    phase_state: Any | None = None,
+    memory_dir: Path | None = None,
+    *,
+    cache_setter: Any = None,
+    heading: str = "Selected Memories",
+    active_tools: list[str] | None = None,
+) -> None:
+    """Update the recall cache on *phase_state* for the next turn.
+
+    Reads the latest user message from conversation parts to use as the
+    query for memory selection.
+    """
+    mem_dir = memory_dir or MEMORY_DIR
+
+    # Extract latest user message as the query.
+    query = _extract_latest_user_query(session_dir)
+    if not query:
+        logger.debug("recall: no user query found, skipping cache update")
+        return
+    logger.debug("recall: updating cache for query: %.80s", query)
+
+    try:
+        selected = await select_memories(
+            query,
+            llm,
+            mem_dir,
+            active_tools=active_tools,
+        )
+        injection = format_recall_injection(selected, mem_dir, heading=heading)
+        if cache_setter is not None:
+            cache_setter(injection)
+        elif phase_state is not None:
+            phase_state._cached_recall_block = injection
+    except Exception:
+        logger.debug("recall: cache update failed", exc_info=True)
+
+
+def _extract_latest_user_query(session_dir: Path) -> str:
+    """Read the most recent user message from conversation parts."""
+    parts_dir = session_dir / "conversations" / "parts"
+    if not parts_dir.is_dir():
+        return ""
+
+    part_files = sorted(parts_dir.glob("*.json"), reverse=True)
+    for f in part_files[:20]:  # Look back at most 20 messages.
+        try:
+            data = json.loads(f.read_text(encoding="utf-8"))
+            if data.get("role") == "user":
+                content = str(data.get("content", "")).strip()
+                if content:
+                    # Truncate very long queries.
+                    return content[:1000] if len(content) > 1000 else content
+        except (json.JSONDecodeError, OSError):
+            continue
+    return ""
@@ -27,7 +27,9 @@
 ## GCU Errors
 15. **Manually wiring browser tools on event_loop nodes** — Use `node_type="gcu"` which auto-includes browser tools. Do NOT manually list browser tool names.
 16. **Using GCU nodes as regular graph nodes** — GCU nodes are subagents only. They must ONLY appear in `sub_agents=["gcu-node-id"]` and be invoked via `delegate_to_sub_agent()`. Never connect via edges or use as entry/terminal nodes.
+17. **Reusing the same GCU node ID for parallel tasks** — Each concurrent browser task needs a distinct GCU node ID (e.g. `gcu-site-a`, `gcu-site-b`). Two `delegate_to_sub_agent` calls with the same `agent_id` share a browser profile and will interfere with each other's pages.
+18. **Passing `profile=` in GCU tool calls** — Profile isolation for parallel subagents is automatic. The framework injects a unique profile per subagent via an asyncio `ContextVar`. Hardcoding `profile="default"` in a GCU system prompt breaks this isolation.

 ## Worker Agent Errors
-17. **Adding client-facing intake node to workers** — The queen owns intake. Workers should start with an autonomous processing node. Client-facing nodes in workers are for mid-execution review/approval only.
-18. **Putting `escalate` or `set_output` in NodeSpec `tools=[]`** — These are synthetic framework tools, auto-injected at runtime. Only list MCP tools from `list_agent_tools()`.
+19. **Adding client-facing intake node to workers** — The queen owns intake. Workers should start with an autonomous processing node. Route worker review/approval through queen escalation instead of direct worker HITL.
+20. **Putting `escalate` or `set_output` in NodeSpec `tools=[]`** — These are synthetic framework tools, auto-injected at runtime. Only list MCP tools from `list_agent_tools()`.
@@ -180,7 +180,7 @@ terminal_nodes = []  # Forever-alive
 # Module-level vars read by AgentRunner.load()
 conversation_mode = "continuous"
 identity_prompt = "You are a helpful agent."
-loop_config = {"max_iterations": 100, "max_tool_calls_per_turn": 20, "max_history_tokens": 32000}
+loop_config = {"max_iterations": 100, "max_tool_calls_per_turn": 20, "max_context_tokens": 32000}


 class MyAgent:
@@ -332,81 +332,46 @@ class MyAgent:
 default_agent = MyAgent()
 ```

-## agent.py — Async Entry Points Variant
+## triggers.json — Timer and Webhook Triggers

-When an agent needs timers, webhooks, or event-driven triggers, add
-`async_entry_points` and optionally `runtime_config` as module-level variables.
-These are IN ADDITION to the standard variables above.
+When an agent needs timers, webhooks, or event-driven triggers, create a
+`triggers.json` file in the agent's directory (alongside `agent.py`).
+The queen loads these at session start and the user can manage them via
+the `set_trigger` / `remove_trigger` tools at runtime.

-```python
-# Additional imports for async entry points
-from framework.graph.edge import GraphSpec, AsyncEntryPointSpec
-from framework.runtime.agent_runtime import (
-    AgentRuntime, AgentRuntimeConfig, create_agent_runtime,
-)
-
-# ... (goal, nodes, edges, entry_node, entry_points, etc. as above) ...
-
-# Async entry points — event-driven triggers
-async_entry_points = [
-    # Timer with cron: daily at 9am
-    AsyncEntryPointSpec(
-        id="daily-check",
-        name="Daily Check",
-        entry_node="process-node",
-        trigger_type="timer",
-        trigger_config={"cron": "0 9 * * *"},
-        isolation_level="shared",
-        max_concurrent=1,
-    ),
-    # Timer with fixed interval: every 20 minutes
-    AsyncEntryPointSpec(
-        id="scheduled-check",
-        name="Scheduled Check",
-        entry_node="process-node",
-        trigger_type="timer",
-        trigger_config={"interval_minutes": 20, "run_immediately": False},
-        isolation_level="shared",
-        max_concurrent=1,
-    ),
-    # Event: reacts to webhook events
-    AsyncEntryPointSpec(
-        id="webhook-event",
-        name="Webhook Event Handler",
-        entry_node="process-node",
-        trigger_type="event",
-        trigger_config={"event_types": ["webhook_received"]},
-        isolation_level="shared",
-        max_concurrent=10,
-    ),
+```json
+[
+  {
+    "id": "daily-check",
+    "name": "Daily Check",
+    "trigger_type": "timer",
+    "trigger_config": {"cron": "0 9 * * *"},
+    "task": "Run the daily check process"
+  },
+  {
+    "id": "scheduled-check",
+    "name": "Scheduled Check",
+    "trigger_type": "timer",
+    "trigger_config": {"interval_minutes": 20},
+    "task": "Run the scheduled check"
+  },
+  {
+    "id": "webhook-event",
+    "name": "Webhook Event Handler",
+    "trigger_type": "webhook",
+    "trigger_config": {"event_types": ["webhook_received"]},
+    "task": "Process incoming webhook event"
+  }
 ]
-
-# Webhook server config (only needed if using webhooks)
-runtime_config = AgentRuntimeConfig(
-    webhook_host="127.0.0.1",
-    webhook_port=8080,
-    webhook_routes=[
-        {
-            "source_id": "my-source",
-            "path": "/webhooks/my-source",
-            "methods": ["POST"],
-        },
-    ],
-)
 ```

-**Key rules for async entry points:**
- `async_entry_points` is a list of `AsyncEntryPointSpec` (NOT `EntryPointSpec`)
- `runtime_config` is `AgentRuntimeConfig` (NOT `RuntimeConfig` from config.py)
- Valid trigger_types: `timer`, `event`, `webhook`, `manual`, `api`
- Valid isolation_levels: `isolated`, `shared`, `synchronized`
+**Key rules for triggers.json:**
+- Valid trigger_types: `timer`, `webhook`
 - Timer trigger_config (cron): `{"cron": "0 9 * * *"}` — standard 5-field cron expression
- Timer trigger_config (interval): `{"interval_minutes": float, "run_immediately": bool}`
- Event trigger_config: `{"event_types": ["webhook_received"], "filter_stream": "...", "filter_node": "..."}`
- Use `isolation_level="shared"` for async entry points that need to read
-  the primary session's memory (e.g., user-configured rules)
- The `_build_graph()` method passes `async_entry_points` to GraphSpec
- Reference: `exports/gmail_inbox_guardian/agent.py`
+- Timer trigger_config (interval): `{"interval_minutes": float}`
+- Each trigger must have a unique `id`
+- The `task` field describes what the worker should do when the trigger fires
+- Triggers are persisted back to `triggers.json` when modified via queen tools

 ## __init__.py

@@ -453,21 +418,6 @@ __all__ = [
 ]
 ```

-**If the agent uses async entry points**, also import and export:
-```python
-from .agent import (
-    ...,
-    async_entry_points,
-    runtime_config,  # Only if using webhooks
-)
-
-__all__ = [
-    ...,
-    "async_entry_points",
-    "runtime_config",
-]
-```
-
 ## __main__.py

 ```python
@@ -559,7 +509,7 @@ if __name__ == "__main__":

 ## mcp_servers.json

-> **Auto-generated.** `initialize_agent_package` creates this file with hive-tools
+> **Auto-generated.** `initialize_and_build_agent` creates this file with hive-tools
 > as the default. Only edit manually to add additional MCP servers.

 ```json
@@ -31,8 +31,7 @@ module-level variables via `getattr()`:
 | `conversation_mode` | no | not passed | Isolated mode (no context carryover) |
 | `identity_prompt` | no | not passed | No agent-level identity |
 | `loop_config` | no | `{}` | No iteration limits |
-| `async_entry_points` | no | `[]` | No async triggers (timers, webhooks, events) |
-| `runtime_config` | no | `None` | No webhook server |
+| `triggers.json` (file) | no | not present | No triggers (timers, webhooks) |

 **CRITICAL:** `__init__.py` MUST import and re-export ALL of these from
 `agent.py`. Missing exports silently fall back to defaults, causing
@@ -77,7 +76,7 @@ goal = Goal(
 | output_keys | list[str] | required | Memory keys this node writes via set_output |
 | system_prompt | str | "" | LLM instructions |
 | tools | list[str] | [] | Tool names from MCP servers |
-| client_facing | bool | False | If True, streams to user and blocks for input |
+| client_facing | bool | False | Deprecated compatibility field. Queen interactivity is implicit; workers should escalate instead |
 | nullable_output_keys | list[str] | [] | Keys that may remain unset |
 | max_node_visits | int | 0 | 0=unlimited (default); >1 for one-shot feedback loops |
 | max_retries | int | 3 | Retries on failure |
@@ -111,7 +110,7 @@ This prevents premature set_output before user interaction.
 **Hard limit: 3-6 nodes for most agents.** Never exceed 6 unless the user
 explicitly requests a complex multi-phase pipeline.

-Each node boundary serializes outputs to shared memory and **destroys** all
+Each node boundary serializes outputs to the shared buffer and **destroys** all
 in-context information: tool call results, intermediate reasoning, conversation
 history. A research node that searches, fetches, and analyzes in ONE node keeps
 all source material in its conversation context. Split across 3 nodes, each
@@ -133,13 +132,14 @@ downstream node only sees the serialized summary string.

 **Typical agent structure (2 nodes):**
 ```
-process (autonomous) ←→ review (client-facing)
+process (autonomous) ←→ review (queen-mediated)
 ```
 The queen owns intake — she gathers requirements from the user, then
 passes structured input via `run_agent_with_input(task)`. When building
 the agent, design the entry node's `input_keys` to match what the queen
 will provide at run time. Worker agents should NOT have a client-facing
-intake node. Client-facing nodes are for mid-execution review/approval only.
+intake node. Mid-execution review/approval should happen through queen
+escalation rather than direct worker HITL.

 For simpler agents, just 1 autonomous node:
 ```
@@ -173,7 +173,7 @@ Use `conversation_mode="continuous"` to preserve context across transitions.
 ### set_output
 - Synthetic tool injected by framework
 - Call separately from real tool calls (separate turn)
- `set_output("key", "value")` stores to shared memory
+- `set_output("key", "value")` stores to the shared buffer

 ## Edge Conditions

@@ -226,7 +226,7 @@ Only three valid keys:
 loop_config = {
    "max_iterations": 100,          # Max LLM turns per node visit
    "max_tool_calls_per_turn": 20,  # Max tool calls per LLM response
-    "max_history_tokens": 32000,    # Triggers conversation compaction
+    "max_context_tokens": 32000,    # Triggers conversation compaction
 }
 ```
 **INVALID keys** (do NOT use): `"strategy"`, `"mode"`, `"timeout"`,
@@ -247,7 +247,7 @@ For large data that exceeds context:
 Multiple ON_SUCCESS edges from same source → parallel execution via asyncio.gather().
 - Parallel nodes must have disjoint output_keys
 - Only one branch may have client_facing nodes
- Fan-in node gets all outputs in shared memory
+- Fan-in node gets all outputs in the shared buffer

 ## Judge System

@@ -257,44 +257,28 @@ Multiple ON_SUCCESS edges from same source → parallel execution via asyncio.ga

 Judge is the SOLE acceptance mechanism — no ad-hoc framework gating.

-## Async Entry Points (Webhooks, Timers, Events)
+## Triggers (Timers, Webhooks)

-For agents that react to external events, use `AsyncEntryPointSpec`:
+For agents that react to external events, create a `triggers.json` file
+in the agent's export directory:

-```python
-from framework.graph.edge import AsyncEntryPointSpec
-from framework.runtime.agent_runtime import AgentRuntimeConfig
-
-# Timer trigger (cron or interval)
-async_entry_points = [
-    AsyncEntryPointSpec(
-        id="daily-check",
-        name="Daily Check",
-        entry_node="process",
-        trigger_type="timer",
-        trigger_config={"cron": "0 9 * * *"},  # daily at 9am
-        isolation_level="shared",
-    )
+```json
+[
+  {
+    "id": "daily-check",
+    "name": "Daily Check",
+    "trigger_type": "timer",
+    "trigger_config": {"cron": "0 9 * * *"},
+    "task": "Run the daily check process"
+  }
 ]
-
-# Webhook server (optional)
-runtime_config = AgentRuntimeConfig(
-    webhook_host="127.0.0.1",
-    webhook_port=8080,
-    webhook_routes=[{"source_id": "gmail", "path": "/webhooks/gmail", "methods": ["POST"]}],
-)
 ```

 ### Key Fields
- `trigger_type`: `"timer"`, `"event"`, `"webhook"`, `"manual"`
+- `trigger_type`: `"timer"` or `"webhook"`
 - `trigger_config`: `{"cron": "0 9 * * *"}` or `{"interval_minutes": 20}`
- `isolation_level`: `"shared"` (recommended), `"isolated"`, `"synchronized"`
- `event_types`: For event triggers, e.g., `["webhook_received"]`
-
-### Exports Required
-Both `async_entry_points` and `runtime_config` must be exported from `__init__.py`.
-
-See `exports/gmail_inbox_guardian/agent.py` for complete example.
+- `task`: describes what the worker should do when the trigger fires
+- Triggers can also be created/removed at runtime via `set_trigger` / `remove_trigger` queen tools

 ## Tool Discovery

@@ -109,9 +109,48 @@ Key rules to bake into GCU node prompts:
 - Keep tool calls per turn ≤10
 - Tab isolation: when browser is already running, use `browser_open(background=true)` and pass `target_id` to every call

+## Multiple Concurrent GCU Subagents
+
+When a task can be parallelized across multiple sites or profiles, declare a distinct GCU
+node for each and invoke them all in the same LLM turn.  The framework batches all
+`delegate_to_sub_agent` calls made in one turn and runs them with `asyncio.gather`, so
+they execute concurrently — not sequentially.
+
+**Each GCU subagent automatically gets its own isolated browser context** — no `profile=`
+argument is needed in tool calls.  The framework derives a unique profile from the subagent's
+node ID and instance counter and injects it via an asyncio `ContextVar` before the subagent
+runs.
+
+### Example: three sites in parallel
+
+```python
+# Three distinct GCU nodes
+gcu_site_a = NodeSpec(id="gcu-site-a", node_type="gcu", ...)
+gcu_site_b = NodeSpec(id="gcu-site-b", node_type="gcu", ...)
+gcu_site_c = NodeSpec(id="gcu-site-c", node_type="gcu", ...)
+
+orchestrator = NodeSpec(
+    id="orchestrator",
+    node_type="event_loop",
+    sub_agents=["gcu-site-a", "gcu-site-b", "gcu-site-c"],
+    system_prompt="""\
+Call all three subagents in a single response to run them in parallel:
+  delegate_to_sub_agent(agent_id="gcu-site-a", task="Scrape prices from site A")
+  delegate_to_sub_agent(agent_id="gcu-site-b", task="Scrape prices from site B")
+  delegate_to_sub_agent(agent_id="gcu-site-c", task="Scrape prices from site C")
+""",
+)
+```
+
+**Rules:**
+- Use distinct node IDs for each concurrent task — sharing an ID shares the browser context.
+- The GCU node prompts do not need to mention `profile=`; isolation is automatic.
+- Cleanup is automatic at session end, but GCU nodes can call `browser_stop()` explicitly
+  if they want to release resources mid-run.
+
 ## GCU Anti-Patterns

- Using `browser_screenshot` to read text (use `browser_snapshot`)
+- Using `browser_screenshot` to read text (use `browser_snapshot` instead; screenshots are for visual context only)
 - Re-navigating after scrolling (resets scroll position)
 - Attempting login on auth walls
 - Forgetting `target_id` in multi-tab scenarios
@@ -0,0 +1,686 @@
+"""Reflect agent — background memory extraction for queen and worker memory.
+
+A lightweight side agent that runs after each queen LLM turn.  It
+inspects recent conversation messages (cursor-based incremental
+processing) and extracts learnings into individual memory files.
+
+Two reflection types:
+  - **Short reflection**: every queen turn. Distills learnings. Nudged
+    toward a 2-turn pattern (batch reads → batch writes).
+  - **Long reflection**: every 5 short reflections, on CONTEXT_COMPACTED,
+    and at session end.  Organises, deduplicates, trims holistically.
+
+The agent has restricted tool access: it can only read/write/delete
+memory files in ``~/.hive/queen/memories/`` and list them.
+
+Concurrency: an ``asyncio.Lock`` prevents overlapping runs.  If a
+trigger fires while a reflection is already active the event is skipped
+(cursor hasn't advanced, so messages will be reconsidered next time).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import re
+import traceback
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from framework.agents.queen.queen_memory_v2 import (
+    MAX_FILE_SIZE_BYTES,
+    MAX_FILES,
+    MEMORY_DIR,
+    MEMORY_FRONTMATTER_EXAMPLE,
+    MEMORY_TYPES,
+    build_diary_document,
+    diary_filename,
+    format_memory_manifest,
+    read_conversation_parts,
+    scan_memory_files,
+)
+from framework.llm.provider import LLMResponse, Tool
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Reflection tool definitions (internal — not in queen's main registry)
+# ---------------------------------------------------------------------------
+
+_REFLECTION_TOOLS: list[Tool] = [
+    Tool(
+        name="list_memory_files",
+        description=(
+            "List all memory files with their type, name, age, and description. "
+            "Returns a text manifest — one line per file."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {},
+            "additionalProperties": False,
+        },
+    ),
+    Tool(
+        name="read_memory_file",
+        description="Read the full content of a memory file by filename.",
+        parameters={
+            "type": "object",
+            "properties": {
+                "filename": {
+                    "type": "string",
+                    "description": "The filename (e.g. 'user-prefers-dark-mode.md').",
+                },
+            },
+            "required": ["filename"],
+            "additionalProperties": False,
+        },
+    ),
+    Tool(
+        name="write_memory_file",
+        description=(
+            "Create or overwrite a memory file.  Content should include YAML "
+            "frontmatter (name, description, type) followed by the memory body.  "
+            f"Max file size: {MAX_FILE_SIZE_BYTES} bytes.  Max files: {MAX_FILES}."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "filename": {
+                    "type": "string",
+                    "description": "Filename ending in .md (e.g. 'user-prefers-dark-mode.md').",
+                },
+                "content": {
+                    "type": "string",
+                    "description": "Full file content including frontmatter.",
+                },
+            },
+            "required": ["filename", "content"],
+            "additionalProperties": False,
+        },
+    ),
+    Tool(
+        name="delete_memory_file",
+        description=(
+            "Delete a memory file by filename.  Use during long "
+            "reflection to prune stale or redundant memories."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "filename": {
+                    "type": "string",
+                    "description": "The filename to delete.",
+                },
+            },
+            "required": ["filename"],
+            "additionalProperties": False,
+        },
+    ),
+]
+
+
+def _safe_memory_path(filename: str, memory_dir: Path) -> Path:
+    """Resolve *filename* inside *memory_dir*, raising if it escapes."""
+    if not filename or filename.strip() != filename:
+        raise ValueError(f"Invalid filename: {filename!r}")
+    if "/" in filename or "\\" in filename or ".." in filename:
+        raise ValueError(f"Invalid filename: path components not allowed: {filename!r}")
+    candidate = (memory_dir / filename).resolve()
+    root = memory_dir.resolve()
+    if not candidate.is_relative_to(root):
+        raise ValueError(f"Path escapes memory directory: {filename!r}")
+    return candidate
+
+
+def _execute_tool(name: str, args: dict[str, Any], memory_dir: Path) -> str:
+    """Execute a reflection tool synchronously.  Returns the result string."""
+    if name == "list_memory_files":
+        files = scan_memory_files(memory_dir)
+        logger.debug("reflect: tool list_memory_files → %d files", len(files))
+        if not files:
+            return "(no memory files yet)"
+        return format_memory_manifest(files)
+
+    if name == "read_memory_file":
+        filename = args.get("filename", "")
+        try:
+            path = _safe_memory_path(filename, memory_dir)
+        except ValueError as exc:
+            return f"ERROR: {exc}"
+        if not path.exists() or not path.is_file():
+            return f"ERROR: File not found: {filename}"
+        try:
+            return path.read_text(encoding="utf-8")
+        except OSError as e:
+            return f"ERROR: {e}"
+
+    if name == "write_memory_file":
+        filename = args.get("filename", "")
+        content = args.get("content", "")
+        if not filename.endswith(".md"):
+            return "ERROR: Filename must end with .md"
+        # Enforce file size limit.
+        if len(content.encode("utf-8")) > MAX_FILE_SIZE_BYTES:
+            return f"ERROR: Content exceeds {MAX_FILE_SIZE_BYTES} byte limit."
+        # Enforce file cap (only for new files).
+        try:
+            path = _safe_memory_path(filename, memory_dir)
+        except ValueError as exc:
+            return f"ERROR: {exc}"
+        if not path.exists():
+            existing = list(memory_dir.glob("*.md"))
+            if len(existing) >= MAX_FILES:
+                return f"ERROR: File cap reached ({MAX_FILES}).  Delete a file first."
+        memory_dir.mkdir(parents=True, exist_ok=True)
+        path.write_text(content, encoding="utf-8")
+        logger.debug("reflect: tool write_memory_file → %s (%d chars)", filename, len(content))
+        return f"Wrote {filename} ({len(content)} chars)."
+
+    if name == "delete_memory_file":
+        filename = args.get("filename", "")
+        try:
+            path = _safe_memory_path(filename, memory_dir)
+        except ValueError as exc:
+            return f"ERROR: {exc}"
+        if not path.exists():
+            return f"ERROR: File not found: {filename}"
+        path.unlink()
+        logger.debug("reflect: tool delete_memory_file → %s", filename)
+        return f"Deleted {filename}."
+
+    return f"ERROR: Unknown tool: {name}"
+
+
+# ---------------------------------------------------------------------------
+# Mini event loop
+# ---------------------------------------------------------------------------
+
+_MAX_TURNS = 5
+
+
+async def _reflection_loop(
+    llm: Any,
+    system: str,
+    user_msg: str,
+    memory_dir: Path,
+    max_turns: int = _MAX_TURNS,
+) -> bool:
+    """Run a mini tool-use loop: LLM → tool calls → repeat.
+
+    Hard cap of *max_turns* iterations.  Prompt nudges the LLM toward a
+    2-turn pattern (batch reads in turn 1, batch writes in turn 2).
+
+    Returns ``True`` if the loop completed without LLM errors, ``False``
+    if an LLM call failed (cursor should not advance).
+    """
+    messages: list[dict[str, Any]] = [{"role": "user", "content": user_msg}]
+    logger.debug("reflect: starting loop (max %d turns)", max_turns)
+
+    for _turn in range(max_turns):
+        try:
+            resp: LLMResponse = await llm.acomplete(
+                messages=messages,
+                system=system,
+                tools=_REFLECTION_TOOLS,
+                max_tokens=2048,
+            )
+        except Exception:
+            logger.warning("reflect: LLM call failed", exc_info=True)
+            return False
+
+        # Build assistant message.
+        tool_calls_raw: list[dict[str, Any]] = []
+        if resp.raw_response and isinstance(resp.raw_response, dict):
+            tool_calls_raw = resp.raw_response.get("tool_calls", [])
+
+        assistant_msg: dict[str, Any] = {
+            "role": "assistant",
+            "content": resp.content or "",
+        }
+        if tool_calls_raw:
+            # Convert to OpenAI format for the conversation.
+            assistant_msg["tool_calls"] = [
+                {
+                    "id": tc["id"],
+                    "type": "function",
+                    "function": {
+                        "name": tc["name"],
+                        "arguments": json.dumps(tc.get("input", {})),
+                    },
+                }
+                for tc in tool_calls_raw
+            ]
+        messages.append(assistant_msg)
+
+        # No tool calls → agent is done.
+        if not tool_calls_raw:
+            logger.debug("reflect: loop done after %d turn(s) (no tool calls)", _turn + 1)
+            break
+
+        # Execute each tool call and append results.
+        logger.debug("reflect: turn %d — executing %d tool call(s): %s", _turn + 1, len(tool_calls_raw), [tc["name"] for tc in tool_calls_raw])
+        for tc in tool_calls_raw:
+            result = _execute_tool(tc["name"], tc.get("input", {}), memory_dir)
+            messages.append({
+                "role": "tool",
+                "tool_call_id": tc["id"],
+                "content": result,
+            })
+
+    return True
+
+
+# ---------------------------------------------------------------------------
+# System prompts
+# ---------------------------------------------------------------------------
+
+_FRONTMATTER_EXAMPLE = "\n".join(MEMORY_FRONTMATTER_EXAMPLE)
+
+_SHORT_REFLECT_SYSTEM = f"""\
+You are a reflection agent that distills learnings from a conversation into
+persistent memory files.  You run in the background after each assistant turn.
+
+Your goal: identify anything from the recent messages worth remembering across
+future sessions — user preferences, project context, techniques that worked,
+goals, environment details, reference pointers.
+
+Memory types: {', '.join(MEMORY_TYPES)}
+
+Expected format for each memory file:
+{_FRONTMATTER_EXAMPLE}
+
+Workflow (aim for 2 turns):
+  Turn 1 — call list_memory_files to see what already exists, then
+            read_memory_file for any that might need updating.
+  Turn 2 — call write_memory_file for new/updated memories.
+
+Rules:
+- Only persist information that would be useful in a *future* conversation.
+  Skip ephemeral task details, routine tool output, and anything obvious
+  from the code or git history.
+- Keep files concise.  Each file should cover ONE topic.
+- If an existing memory already covers the learning, UPDATE it rather than
+  creating a duplicate.
+- If there is nothing worth remembering from these messages, do nothing
+  (just respond with a short note — no tool calls needed).
+- File names should be kebab-case slugs ending in .md.
+- Include a specific, search-friendly description in the frontmatter.
+- Do NOT exceed {MAX_FILE_SIZE_BYTES} bytes per file or {MAX_FILES} total files.
+"""
+
+_LONG_REFLECT_SYSTEM = f"""\
+You are a reflection agent performing a periodic housekeeping pass over the
+memory directory.  Your job is to organise, deduplicate, and trim noise from
+the accumulated memory files.
+
+Memory types: {', '.join(MEMORY_TYPES)}
+
+Expected format for each memory file:
+{_FRONTMATTER_EXAMPLE}
+
+Workflow:
+  1. list_memory_files to get the full manifest.
+  2. read_memory_file for files that look redundant, stale, or overlapping.
+  3. Merge duplicates, delete stale entries, consolidate related memories.
+  4. Ensure descriptions are specific and search-friendly.
+  5. Enforce limits: max {MAX_FILES} files, max {MAX_FILE_SIZE_BYTES} bytes each.
+
+Rules:
+- Prefer merging over deleting — combine related memories into one file.
+- Remove memories that are no longer relevant or are superseded.
+- Keep the total collection lean and high-signal.
+- Do NOT invent new information — only reorganise what exists.
+- Do NOT delete or merge MEMORY-*.md diary files. These are daily narratives
+  managed by a separate process. You may read them for context but should not
+  modify them.
+"""
+
+_DIARY_SYSTEM = """\
+You maintain a daily diary entry for an AI colony session. You receive:
+(1) Today's existing diary content (may be empty if this is the first entry).
+(2) A transcript of recent conversation messages.
+
+Write a cohesive 3-8 sentence narrative about what happened in this session today.
+Cover: what the user asked for, what was accomplished, key decisions or obstacles,
+and current status.
+
+Rules:
+- If an existing diary is provided, rewrite it as a unified narrative incorporating
+  the new developments. Merge and deduplicate — do not simply append.
+- Keep the total narrative under 3000 characters.
+- Focus on the story arc of the day, not individual tool calls or code details.
+- If the recent messages contain nothing substantive (greetings, routine
+  confirmations), return the existing diary text unchanged.
+- Output only the diary prose. No headings, no timestamps, no code fences, no
+  frontmatter.
+"""
+
+
+# ---------------------------------------------------------------------------
+# Short & long reflection entry points
+# ---------------------------------------------------------------------------
+
+
+async def run_short_reflection(
+    session_dir: Path,
+    llm: Any,
+    memory_dir: Path | None = None,
+) -> None:
+    """Run a short reflection: extract learnings from conversation."""
+    mem_dir = memory_dir or MEMORY_DIR
+
+    messages = await read_conversation_parts(session_dir)
+    if not messages:
+        logger.debug("reflect: short — no conversation parts")
+        return
+
+    logger.debug("reflect: short — %d conversation parts", len(messages))
+
+    # Build a readable transcript from recent messages.
+    transcript_lines: list[str] = []
+    for msg in messages[-50:]:
+        role = msg.get("role", "")
+        content = str(msg.get("content", "")).strip()
+        if role == "tool":
+            continue  # Skip verbose tool results.
+        if not content:
+            continue
+        label = "user" if role == "user" else "assistant"
+        if len(content) > 800:
+            content = content[:800] + "…"
+        transcript_lines.append(f"[{label}]: {content}")
+
+    if not transcript_lines:
+        return
+
+    transcript = "\n".join(transcript_lines)
+    user_msg = (
+        f"## Recent conversation ({len(messages)} messages total)\n\n"
+        f"{transcript}\n\n"
+        f"Timestamp: {datetime.now().isoformat(timespec='minutes')}"
+    )
+
+    await _reflection_loop(llm, _SHORT_REFLECT_SYSTEM, user_msg, mem_dir)
+    logger.debug("reflect: short reflection done")
+
+
+async def run_long_reflection(
+    llm: Any,
+    memory_dir: Path | None = None,
+) -> None:
+    """Run a long reflection: organise and deduplicate all memories."""
+    mem_dir = memory_dir or MEMORY_DIR
+    files = scan_memory_files(mem_dir)
+
+    if not files:
+        logger.debug("reflect: long — no memory files to organise")
+        return
+
+    logger.debug("reflect: long — organising %d memory files", len(files))
+    manifest = format_memory_manifest(files)
+    user_msg = (
+        f"## Current memory manifest ({len(files)} files)\n\n"
+        f"{manifest}\n\n"
+        f"Timestamp: {datetime.now().isoformat(timespec='minutes')}"
+    )
+
+    await _reflection_loop(llm, _LONG_REFLECT_SYSTEM, user_msg, mem_dir)
+    logger.debug("reflect: long reflection done (%d files)", len(files))
+
+
+async def run_diary_update(
+    session_dir: Path,
+    llm: Any,
+    memory_dir: Path | None = None,
+) -> None:
+    """Update today's diary file with a narrative of recent activity."""
+    mem_dir = memory_dir or MEMORY_DIR
+
+    fname = diary_filename()
+    diary_path = mem_dir / fname
+    today_str = datetime.now().strftime("%Y-%m-%d")
+
+    # Read existing diary body (strip frontmatter).
+    existing_body = ""
+    if diary_path.exists():
+        try:
+            raw = diary_path.read_text(encoding="utf-8")
+            m = re.match(r"^---\s*\n.*?\n---\s*\n?", raw, re.DOTALL)
+            existing_body = raw[m.end() :].strip() if m else raw.strip()
+        except OSError:
+            pass
+
+    # Read all conversation messages for context.
+    messages = await read_conversation_parts(session_dir)
+    transcript_lines: list[str] = []
+    for msg in messages[-40:]:
+        role = msg.get("role", "")
+        content = str(msg.get("content", "")).strip()
+        if role == "tool" or not content:
+            continue
+        label = "user" if role == "user" else "assistant"
+        if len(content) > 600:
+            content = content[:600] + "..."
+        transcript_lines.append(f"[{label}]: {content}")
+
+    if not transcript_lines:
+        return
+
+    transcript = "\n".join(transcript_lines)
+    user_msg = (
+        f"## Today's Diary So Far\n\n"
+        f"{existing_body or '(no entries yet)'}\n\n"
+        f"## Recent Conversation\n\n"
+        f"{transcript}\n\n"
+        f"Date: {today_str}"
+    )
+
+    try:
+        from framework.agents.queen.config import default_config
+
+        resp = await llm.acomplete(
+            messages=[{"role": "user", "content": user_msg}],
+            system=_DIARY_SYSTEM,
+            max_tokens=min(default_config.max_tokens, 1024),
+        )
+        new_body = (resp.content or "").strip()
+        if not new_body:
+            return
+
+        doc = build_diary_document(date_str=today_str, body=new_body)
+        if len(doc.encode("utf-8")) > MAX_FILE_SIZE_BYTES:
+            new_body = new_body[:2800]
+            doc = build_diary_document(date_str=today_str, body=new_body)
+
+        mem_dir.mkdir(parents=True, exist_ok=True)
+        diary_path.write_text(doc, encoding="utf-8")
+        logger.debug("diary: updated %s (%d chars)", fname, len(doc))
+    except Exception:
+        logger.warning("diary: update failed", exc_info=True)
+
+
+# ---------------------------------------------------------------------------
+# Event-bus integration
+# ---------------------------------------------------------------------------
+
+# Run a long reflection every N short reflections.
+_LONG_REFLECT_INTERVAL = 5
+
+
+async def subscribe_reflection_triggers(
+    event_bus: Any,
+    session_dir: Path,
+    llm: Any,
+    memory_dir: Path | None = None,
+    phase_state: Any = None,
+) -> list[str]:
+    """Subscribe to queen turn events and return subscription IDs.
+
+    Call this once during queen setup.  Returns a list of event-bus
+    subscription IDs for cleanup during session teardown.
+    """
+    from framework.runtime.event_bus import EventType
+
+    mem_dir = memory_dir or MEMORY_DIR
+    _lock = asyncio.Lock()
+    _short_count = 0
+
+    async def _on_turn_complete(event: Any) -> None:
+        nonlocal _short_count
+
+        # Only process queen turns.
+        if getattr(event, "stream_id", None) != "queen":
+            return
+
+        if _lock.locked():
+            logger.debug("reflect: skipping — reflection already in progress")
+            return
+
+        async with _lock:
+            try:
+                _short_count += 1
+                logger.debug("reflect: turn complete — short count %d/%d", _short_count, _LONG_REFLECT_INTERVAL)
+                if _short_count % _LONG_REFLECT_INTERVAL == 0:
+                    await run_short_reflection(session_dir, llm, mem_dir)
+                    await run_long_reflection(llm, mem_dir)
+                else:
+                    await run_short_reflection(session_dir, llm, mem_dir)
+            except Exception:
+                logger.warning("reflect: reflection failed", exc_info=True)
+                _write_error("short/long reflection")
+
+            # Update daily diary after reflection.
+            try:
+                await run_diary_update(session_dir, llm, mem_dir)
+            except Exception:
+                logger.warning("reflect: diary update failed", exc_info=True)
+
+            # Update recall cache after reflection completes, guaranteeing
+            # recall sees the current turn's extracted memories.
+            if phase_state is not None:
+                try:
+                    from framework.agents.queen.recall_selector import update_recall_cache
+                    await update_recall_cache(
+                        session_dir,
+                        llm,
+                        cache_setter=lambda block: (
+                            setattr(phase_state, "_cached_colony_recall_block", block),
+                            setattr(phase_state, "_cached_recall_block", block),
+                        ),
+                        memory_dir=mem_dir,
+                        heading="Colony Memories",
+                    )
+                    await update_recall_cache(
+                        session_dir,
+                        llm,
+                        cache_setter=lambda block: setattr(
+                            phase_state, "_cached_global_recall_block", block
+                        ),
+                        memory_dir=getattr(phase_state, "global_memory_dir", None),
+                        heading="Global Memories",
+                    )
+                except Exception:
+                    logger.debug("recall: cache update failed", exc_info=True)
+
+    async def _on_compaction(event: Any) -> None:
+        if getattr(event, "stream_id", None) != "queen":
+            return
+
+        if _lock.locked():
+            return
+
+        async with _lock:
+            try:
+                await run_long_reflection(llm, mem_dir)
+            except Exception:
+                logger.warning("reflect: compaction-triggered reflection failed", exc_info=True)
+                _write_error("compaction reflection")
+
+    sub_ids: list[str] = []
+
+    sub1 = event_bus.subscribe(
+        event_types=[EventType.LLM_TURN_COMPLETE],
+        handler=_on_turn_complete,
+    )
+    sub_ids.append(sub1)
+
+    sub2 = event_bus.subscribe(
+        event_types=[EventType.CONTEXT_COMPACTED],
+        handler=_on_compaction,
+    )
+    sub_ids.append(sub2)
+
+    return sub_ids
+
+
+async def subscribe_worker_memory_triggers(
+    event_bus: Any,
+    llm: Any,
+    *,
+    worker_sessions_dir: Path,
+    colony_memory_dir: Path,
+    recall_cache: dict[str, str],
+) -> list[str]:
+    """Subscribe colony memory lifecycle events for worker runs.
+
+    Short reflection is now handled synchronously at node handoff in
+    ``WorkerAgent._reflect_colony_memory()``.  This function only manages:
+    - Recall cache initialisation on execution start
+    - Final long reflection + cleanup on execution end
+    """
+    from framework.runtime.event_bus import EventType
+
+    _terminal_lock = asyncio.Lock()
+
+    def _is_worker_event(event: Any) -> bool:
+        return bool(
+            getattr(event, "execution_id", None)
+            and getattr(event, "stream_id", None) not in ("queen", "judge")
+        )
+
+    async def _on_execution_started(event: Any) -> None:
+        if not _is_worker_event(event):
+            return
+        if event.execution_id is not None:
+            recall_cache[event.execution_id] = ""
+
+    async def _on_execution_terminal(event: Any) -> None:
+        if not _is_worker_event(event):
+            return
+        execution_id = event.execution_id
+        if execution_id is None:
+            return
+        async with _terminal_lock:
+            try:
+                await run_long_reflection(llm, colony_memory_dir)
+            except Exception:
+                logger.warning("reflect: worker final reflection failed", exc_info=True)
+                _write_error("worker final reflection")
+            finally:
+                recall_cache.pop(execution_id, None)
+
+    return [
+        event_bus.subscribe(
+            event_types=[EventType.EXECUTION_STARTED],
+            handler=_on_execution_started,
+        ),
+        event_bus.subscribe(
+            event_types=[EventType.EXECUTION_COMPLETED, EventType.EXECUTION_FAILED],
+            handler=_on_execution_terminal,
+        ),
+    ]
+
+
+def _write_error(context: str) -> None:
+    """Best-effort write of the last traceback to an error file."""
+    try:
+        error_path = MEMORY_DIR / ".reflection_error.txt"
+        error_path.parent.mkdir(parents=True, exist_ok=True)
+        error_path.write_text(
+            f"context: {context}\ntime: {datetime.now().isoformat()}\n\n{traceback.format_exc()}",
+            encoding="utf-8",
+        )
+    except OSError:
+        pass
@@ -1,4 +1,4 @@
-"""Test fixtures for Hive Coder agent."""
+"""Test fixtures for Queen agent."""

 import sys
 from pathlib import Path
@@ -1,7 +0,0 @@
-"""Builder interface for analyzing and building agents."""
-
-from framework.builder.query import BuilderQuery
-
-__all__ = [
-    "BuilderQuery",
-]
@@ -1,501 +0,0 @@
-"""
-Builder Query Interface - How I (Builder) analyze agent runs.
-
-This is designed around the questions I need to answer:
-1. What happened? (summaries, narratives)
-2. Why did it fail? (failure analysis, decision traces)
-3. What patterns emerge? (across runs, across nodes)
-4. What should we change? (suggestions)
-"""
-
-from collections import defaultdict
-from pathlib import Path
-from typing import Any
-
-from framework.schemas.decision import Decision
-from framework.schemas.run import Run, RunStatus, RunSummary
-from framework.storage.backend import FileStorage
-
-
-class FailureAnalysis:
-    """Structured analysis of why a run failed."""
-
-    def __init__(
-        self,
-        run_id: str,
-        failure_point: str,
-        root_cause: str,
-        decision_chain: list[str],
-        problems: list[str],
-        suggestions: list[str],
-    ):
-        self.run_id = run_id
-        self.failure_point = failure_point
-        self.root_cause = root_cause
-        self.decision_chain = decision_chain
-        self.problems = problems
-        self.suggestions = suggestions
-
-    def to_dict(self) -> dict[str, Any]:
-        return {
-            "run_id": self.run_id,
-            "failure_point": self.failure_point,
-            "root_cause": self.root_cause,
-            "decision_chain": self.decision_chain,
-            "problems": self.problems,
-            "suggestions": self.suggestions,
-        }
-
-    def __str__(self) -> str:
-        lines = [
-            f"=== Failure Analysis for {self.run_id} ===",
-            "",
-            f"Failure Point: {self.failure_point}",
-            f"Root Cause: {self.root_cause}",
-            "",
-            "Decision Chain Leading to Failure:",
-        ]
-        for i, dec in enumerate(self.decision_chain, 1):
-            lines.append(f"  {i}. {dec}")
-
-        if self.problems:
-            lines.append("")
-            lines.append("Reported Problems:")
-            for prob in self.problems:
-                lines.append(f"  - {prob}")
-
-        if self.suggestions:
-            lines.append("")
-            lines.append("Suggestions:")
-            for sug in self.suggestions:
-                lines.append(f"  → {sug}")
-
-        return "\n".join(lines)
-
-
-class PatternAnalysis:
-    """Patterns detected across multiple runs."""
-
-    def __init__(
-        self,
-        goal_id: str,
-        run_count: int,
-        success_rate: float,
-        common_failures: list[tuple[str, int]],
-        problematic_nodes: list[tuple[str, float]],
-        decision_patterns: dict[str, Any],
-    ):
-        self.goal_id = goal_id
-        self.run_count = run_count
-        self.success_rate = success_rate
-        self.common_failures = common_failures
-        self.problematic_nodes = problematic_nodes
-        self.decision_patterns = decision_patterns
-
-    def to_dict(self) -> dict[str, Any]:
-        return {
-            "goal_id": self.goal_id,
-            "run_count": self.run_count,
-            "success_rate": self.success_rate,
-            "common_failures": self.common_failures,
-            "problematic_nodes": self.problematic_nodes,
-            "decision_patterns": self.decision_patterns,
-        }
-
-    def __str__(self) -> str:
-        lines = [
-            f"=== Pattern Analysis for Goal {self.goal_id} ===",
-            "",
-            f"Runs Analyzed: {self.run_count}",
-            f"Success Rate: {self.success_rate:.1%}",
-        ]
-
-        if self.common_failures:
-            lines.append("")
-            lines.append("Common Failures:")
-            for failure, count in self.common_failures:
-                lines.append(f"  - {failure} ({count} occurrences)")
-
-        if self.problematic_nodes:
-            lines.append("")
-            lines.append("Problematic Nodes (failure rate):")
-            for node, rate in self.problematic_nodes:
-                lines.append(f"  - {node}: {rate:.1%} failure rate")
-
-        return "\n".join(lines)
-
-
-class BuilderQuery:
-    """
-    The interface I (Builder) use to understand what agents are doing.
-
-    This is optimized for the questions I need to answer when analyzing
-    agent behavior and deciding what to improve.
-    """
-
-    def __init__(self, storage_path: str | Path):
-        self.storage = FileStorage(storage_path)
-
-    # === WHAT HAPPENED? ===
-
-    def get_run_summary(self, run_id: str) -> RunSummary | None:
-        """Get a quick summary of a run."""
-        return self.storage.load_summary(run_id)
-
-    def get_full_run(self, run_id: str) -> Run | None:
-        """Get the complete run with all decisions."""
-        return self.storage.load_run(run_id)
-
-    def list_runs_for_goal(self, goal_id: str) -> list[RunSummary]:
-        """Get summaries of all runs for a goal."""
-        run_ids = self.storage.get_runs_by_goal(goal_id)
-        summaries = []
-        for run_id in run_ids:
-            summary = self.storage.load_summary(run_id)
-            if summary:
-                summaries.append(summary)
-        return summaries
-
-    def get_recent_failures(self, limit: int = 10) -> list[RunSummary]:
-        """Get recent failed runs."""
-        run_ids = self.storage.get_runs_by_status(RunStatus.FAILED)
-        summaries = []
-        for run_id in run_ids[:limit]:
-            summary = self.storage.load_summary(run_id)
-            if summary:
-                summaries.append(summary)
-        return summaries
-
-    # === WHY DID IT FAIL? ===
-
-    def analyze_failure(self, run_id: str) -> FailureAnalysis | None:
-        """
-        Deep analysis of why a run failed.
-
-        This is my primary tool for understanding what went wrong.
-        """
-        run = self.storage.load_run(run_id)
-        if run is None or run.status != RunStatus.FAILED:
-            return None
-
-        # Find the first failed decision
-        failed_decisions = [d for d in run.decisions if not d.was_successful]
-        if not failed_decisions:
-            failure_point = "Unknown - no decision marked as failed"
-            root_cause = "Run failed but all decisions succeeded (external cause?)"
-        else:
-            first_failure = failed_decisions[0]
-            failure_point = first_failure.summary_for_builder()
-            root_cause = first_failure.outcome.error if first_failure.outcome else "Unknown"
-
-        # Build the decision chain leading to failure
-        decision_chain = []
-        for d in run.decisions:
-            decision_chain.append(d.summary_for_builder())
-            if not d.was_successful:
-                break
-
-        # Extract problems
-        problems = [f"[{p.severity}] {p.description}" for p in run.problems]
-
-        # Generate suggestions based on the failure
-        suggestions = self._generate_suggestions(run, failed_decisions)
-
-        return FailureAnalysis(
-            run_id=run_id,
-            failure_point=failure_point,
-            root_cause=root_cause,
-            decision_chain=decision_chain,
-            problems=problems,
-            suggestions=suggestions,
-        )
-
-    def get_decision_trace(self, run_id: str) -> list[str]:
-        """Get a readable trace of all decisions in a run."""
-        run = self.storage.load_run(run_id)
-        if run is None:
-            return []
-        return [d.summary_for_builder() for d in run.decisions]
-
-    # === WHAT PATTERNS EMERGE? ===
-
-    def find_patterns(self, goal_id: str) -> PatternAnalysis | None:
-        """
-        Find patterns across runs for a goal.
-
-        This helps me understand systemic issues vs one-off failures.
-        """
-        run_ids = self.storage.get_runs_by_goal(goal_id)
-        if not run_ids:
-            return None
-
-        runs = []
-        for run_id in run_ids:
-            run = self.storage.load_run(run_id)
-            if run:
-                runs.append(run)
-
-        if not runs:
-            return None
-
-        # Calculate success rate
-        completed = [r for r in runs if r.status == RunStatus.COMPLETED]
-        success_rate = len(completed) / len(runs) if runs else 0.0
-
-        # Find common failures
-        failure_counts: dict[str, int] = defaultdict(int)
-        for run in runs:
-            for decision in run.decisions:
-                if not decision.was_successful and decision.outcome:
-                    error = decision.outcome.error or "Unknown error"
-                    failure_counts[error] += 1
-
-        common_failures = sorted(failure_counts.items(), key=lambda x: x[1], reverse=True)[:5]
-
-        # Find problematic nodes
-        node_stats: dict[str, dict[str, int]] = defaultdict(lambda: {"total": 0, "failed": 0})
-        for run in runs:
-            for decision in run.decisions:
-                node_stats[decision.node_id]["total"] += 1
-                if not decision.was_successful:
-                    node_stats[decision.node_id]["failed"] += 1
-
-        problematic_nodes = []
-        for node_id, stats in node_stats.items():
-            if stats["total"] > 0:
-                failure_rate = stats["failed"] / stats["total"]
-                if failure_rate > 0.1:  # More than 10% failure rate
-                    problematic_nodes.append((node_id, failure_rate))
-
-        problematic_nodes.sort(key=lambda x: x[1], reverse=True)
-
-        # Decision patterns
-        decision_patterns = self._analyze_decision_patterns(runs)
-
-        return PatternAnalysis(
-            goal_id=goal_id,
-            run_count=len(runs),
-            success_rate=success_rate,
-            common_failures=common_failures,
-            problematic_nodes=problematic_nodes,
-            decision_patterns=decision_patterns,
-        )
-
-    def compare_runs(self, run_id_1: str, run_id_2: str) -> dict[str, Any]:
-        """Compare two runs to understand what differed."""
-        run1 = self.storage.load_run(run_id_1)
-        run2 = self.storage.load_run(run_id_2)
-
-        if run1 is None or run2 is None:
-            return {"error": "One or both runs not found"}
-
-        return {
-            "run_1": {
-                "id": run1.id,
-                "status": run1.status.value,
-                "decisions": len(run1.decisions),
-                "success_rate": run1.metrics.success_rate,
-            },
-            "run_2": {
-                "id": run2.id,
-                "status": run2.status.value,
-                "decisions": len(run2.decisions),
-                "success_rate": run2.metrics.success_rate,
-            },
-            "differences": self._find_differences(run1, run2),
-        }
-
-    # === WHAT SHOULD WE CHANGE? ===
-
-    def suggest_improvements(self, goal_id: str) -> list[dict[str, Any]]:
-        """
-        Generate improvement suggestions based on run analysis.
-
-        This is what I use to propose changes to the human engineer.
-        """
-        patterns = self.find_patterns(goal_id)
-        if patterns is None:
-            return []
-
-        suggestions = []
-
-        # Suggestion: Fix problematic nodes
-        for node_id, failure_rate in patterns.problematic_nodes:
-            suggestions.append(
-                {
-                    "type": "node_improvement",
-                    "target": node_id,
-                    "reason": f"Node has {failure_rate:.1%} failure rate",
-                    "recommendation": (
-                        f"Review and improve node '{node_id}' - "
-                        "high failure rate suggests prompt or tool issues"
-                    ),
-                    "priority": "high" if failure_rate > 0.3 else "medium",
-                }
-            )
-
-        # Suggestion: Address common failures
-        for failure, count in patterns.common_failures:
-            if count >= 2:
-                suggestions.append(
-                    {
-                        "type": "error_handling",
-                        "target": failure,
-                        "reason": f"Error occurred {count} times",
-                        "recommendation": f"Add handling for: {failure}",
-                        "priority": "high" if count >= 5 else "medium",
-                    }
-                )
-
-        # Suggestion: Overall success rate
-        if patterns.success_rate < 0.8:
-            suggestions.append(
-                {
-                    "type": "architecture",
-                    "target": goal_id,
-                    "reason": f"Goal success rate is only {patterns.success_rate:.1%}",
-                    "recommendation": (
-                        "Consider restructuring the agent graph or improving goal definition"
-                    ),
-                    "priority": "high",
-                }
-            )
-
-        return suggestions
-
-    def get_node_performance(self, node_id: str) -> dict[str, Any]:
-        """Get performance metrics for a specific node across all runs."""
-        run_ids = self.storage.get_runs_by_node(node_id)
-
-        total_decisions = 0
-        successful_decisions = 0
-        total_latency = 0
-        total_tokens = 0
-        decision_types: dict[str, int] = defaultdict(int)
-
-        for run_id in run_ids:
-            run = self.storage.load_run(run_id)
-            if run:
-                for decision in run.decisions:
-                    if decision.node_id == node_id:
-                        total_decisions += 1
-                        if decision.was_successful:
-                            successful_decisions += 1
-                        if decision.outcome:
-                            total_latency += decision.outcome.latency_ms
-                            total_tokens += decision.outcome.tokens_used
-                        decision_types[decision.decision_type.value] += 1
-
-        return {
-            "node_id": node_id,
-            "total_decisions": total_decisions,
-            "success_rate": successful_decisions / total_decisions if total_decisions > 0 else 0,
-            "avg_latency_ms": total_latency / total_decisions if total_decisions > 0 else 0,
-            "total_tokens": total_tokens,
-            "decision_type_distribution": dict(decision_types),
-        }
-
-    # === PRIVATE HELPERS ===
-
-    def _generate_suggestions(
-        self,
-        run: Run,
-        failed_decisions: list[Decision],
-    ) -> list[str]:
-        """Generate suggestions based on failure analysis."""
-        suggestions = []
-
-        for decision in failed_decisions:
-            # Check if there were alternatives
-            if len(decision.options) > 1:
-                chosen = decision.chosen_option
-                alternatives = [o for o in decision.options if o.id != decision.chosen_option_id]
-                if alternatives:
-                    alt_desc = alternatives[0].description
-                    chosen_desc = chosen.description if chosen else "unknown"
-                    suggestions.append(
-                        f"Consider alternative: '{alt_desc}' instead of '{chosen_desc}'"
-                    )
-
-            # Check for missing context
-            if not decision.input_context:
-                suggestions.append(
-                    f"Decision '{decision.intent}' had no input context - "
-                    "ensure relevant data is passed"
-                )
-
-            # Check for constraint issues
-            if decision.active_constraints:
-                constraints = ", ".join(decision.active_constraints)
-                suggestions.append(f"Review constraints: {constraints} - may be too restrictive")
-
-        # Check for reported problems with suggestions
-        for problem in run.problems:
-            if problem.suggested_fix:
-                suggestions.append(problem.suggested_fix)
-
-        return suggestions
-
-    def _analyze_decision_patterns(self, runs: list[Run]) -> dict[str, Any]:
-        """Analyze decision patterns across runs."""
-        type_counts: dict[str, int] = defaultdict(int)
-        option_counts: dict[str, dict[str, int]] = defaultdict(lambda: defaultdict(int))
-
-        for run in runs:
-            for decision in run.decisions:
-                type_counts[decision.decision_type.value] += 1
-
-                # Track which options are chosen for similar intents
-                intent_key = decision.intent[:50]  # Truncate for grouping
-                if decision.chosen_option:
-                    option_counts[intent_key][decision.chosen_option.description] += 1
-
-        # Find most common choices per intent
-        common_choices = {}
-        for intent, choices in option_counts.items():
-            if choices:
-                most_common = max(choices.items(), key=lambda x: x[1])
-                common_choices[intent] = {
-                    "choice": most_common[0],
-                    "count": most_common[1],
-                    "alternatives": len(choices) - 1,
-                }
-
-        return {
-            "decision_type_distribution": dict(type_counts),
-            "common_choices": common_choices,
-        }
-
-    def _find_differences(self, run1: Run, run2: Run) -> list[str]:
-        """Find key differences between two runs."""
-        differences = []
-
-        # Status difference
-        if run1.status != run2.status:
-            differences.append(f"Status: {run1.status.value} vs {run2.status.value}")
-
-        # Decision count difference
-        if len(run1.decisions) != len(run2.decisions):
-            differences.append(f"Decision count: {len(run1.decisions)} vs {len(run2.decisions)}")
-
-        # Find first divergence point
-        for i, (d1, d2) in enumerate(zip(run1.decisions, run2.decisions, strict=False)):
-            if d1.chosen_option_id != d2.chosen_option_id:
-                differences.append(
-                    f"Diverged at decision {i}: "
-                    f"chose '{d1.chosen_option_id}' vs '{d2.chosen_option_id}'"
-                )
-                break
-
-        # Node differences
-        nodes1 = set(run1.metrics.nodes_executed)
-        nodes2 = set(run2.metrics.nodes_executed)
-        if nodes1 != nodes2:
-            only_1 = nodes1 - nodes2
-            only_2 = nodes2 - nodes1
-            if only_1:
-                differences.append(f"Nodes only in run 1: {only_1}")
-            if only_2:
-                differences.append(f"Nodes only in run 2: {only_2}")
-
-        return differences
@@ -6,7 +6,6 @@ Usage:
    hive info exports/my-agent
    hive validate exports/my-agent
    hive list exports/
-    hive dispatch exports/ --input '{"key": "value"}'
    hive shell exports/my-agent

 Testing commands:
@@ -79,7 +78,7 @@ def main():

    subparsers = parser.add_subparsers(dest="command", required=True)

-    # Register runner commands (run, info, validate, list, dispatch, shell)
+    # Register runner commands (run, info, validate, list, shell)
    from framework.runner.cli import register_commands

    register_commands(subparsers)
@@ -89,6 +88,21 @@ def main():

    register_testing_commands(subparsers)

+    # Register skill commands (skill list, skill trust, ...)
+    from framework.skills.cli import register_skill_commands
+
+    register_skill_commands(subparsers)
+
+    # Register debugger commands (debugger)
+    from framework.debugger.cli import register_debugger_commands
+
+    register_debugger_commands(subparsers)
+
+    # Register MCP registry commands (mcp install, mcp add, ...)
+    from framework.runner.mcp_registry_cli import register_mcp_commands
+
+    register_mcp_commands(subparsers)
+
    args = parser.parse_args()

    if hasattr(args, "func"):
@@ -19,6 +19,10 @@ from framework.graph.edge import DEFAULT_MAX_TOKENS
 # ---------------------------------------------------------------------------

 HIVE_CONFIG_FILE = Path.home() / ".hive" / "configuration.json"
+
+# Hive LLM router endpoint (Anthropic-compatible).
+# litellm's Anthropic handler appends /v1/messages, so this is just the base host.
+HIVE_LLM_ENDPOINT = "https://api.adenhq.com"
 logger = logging.getLogger(__name__)


@@ -47,15 +51,176 @@ def get_preferred_model() -> str:
    """Return the user's preferred LLM model string (e.g. 'anthropic/claude-sonnet-4-20250514')."""
    llm = get_hive_config().get("llm", {})
    if llm.get("provider") and llm.get("model"):
-        return f"{llm['provider']}/{llm['model']}"
+        provider = str(llm["provider"])
+        model = str(llm["model"]).strip()
+        # OpenRouter quickstart stores raw model IDs; tolerate pasted "openrouter/<id>" too.
+        if provider.lower() == "openrouter" and model.lower().startswith("openrouter/"):
+            model = model[len("openrouter/") :]
+        if model:
+            return f"{provider}/{model}"
    return "anthropic/claude-sonnet-4-20250514"


+def get_preferred_worker_model() -> str | None:
+    """Return the user's preferred worker LLM model, or None if not configured.
+
+    Reads from the ``worker_llm`` section of ~/.hive/configuration.json.
+    Returns None when no worker-specific model is set, so callers can
+    fall back to the default (queen) model via ``get_preferred_model()``.
+    """
+    worker_llm = get_hive_config().get("worker_llm", {})
+    if worker_llm.get("provider") and worker_llm.get("model"):
+        provider = str(worker_llm["provider"])
+        model = str(worker_llm["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_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", {})
+    if not worker_llm:
+        return get_api_key()
+
+    # Worker-specific subscription / env var
+    if worker_llm.get("use_claude_code_subscription"):
+        try:
+            from framework.runner.runner import get_claude_code_token
+
+            token = get_claude_code_token()
+            if token:
+                return token
+        except ImportError:
+            pass
+
+    if worker_llm.get("use_codex_subscription"):
+        try:
+            from framework.runner.runner import get_codex_token
+
+            token = get_codex_token()
+            if token:
+                return token
+        except ImportError:
+            pass
+
+    if worker_llm.get("use_kimi_code_subscription"):
+        try:
+            from framework.runner.runner import get_kimi_code_token
+
+            token = get_kimi_code_token()
+            if token:
+                return token
+        except ImportError:
+            pass
+
+    if worker_llm.get("use_antigravity_subscription"):
+        try:
+            from framework.runner.runner import get_antigravity_token
+
+            token = get_antigravity_token()
+            if token:
+                return token
+        except ImportError:
+            pass
+
+    api_key_env_var = worker_llm.get("api_key_env_var")
+    if api_key_env_var:
+        return os.environ.get(api_key_env_var)
+
+    # Fall back to default key
+    return get_api_key()
+
+
+def get_worker_api_base() -> str | None:
+    """Return the api_base for the worker LLM, falling back to the default."""
+    worker_llm = get_hive_config().get("worker_llm", {})
+    if not worker_llm:
+        return get_api_base()
+
+    if worker_llm.get("use_codex_subscription"):
+        return "https://chatgpt.com/backend-api/codex"
+    if worker_llm.get("use_kimi_code_subscription"):
+        return "https://api.kimi.com/coding"
+    if worker_llm.get("use_antigravity_subscription"):
+        # Antigravity uses AntigravityProvider directly — no api_base needed.
+        return None
+    if worker_llm.get("api_base"):
+        return worker_llm["api_base"]
+    if str(worker_llm.get("provider", "")).lower() == "openrouter":
+        return OPENROUTER_API_BASE
+    return None
+
+
+def get_worker_llm_extra_kwargs() -> dict[str, Any]:
+    """Return extra kwargs for the worker LLM provider."""
+    worker_llm = get_hive_config().get("worker_llm", {})
+    if not worker_llm:
+        return get_llm_extra_kwargs()
+
+    if worker_llm.get("use_claude_code_subscription"):
+        api_key = get_worker_api_key()
+        if api_key:
+            return {
+                "extra_headers": {"authorization": f"Bearer {api_key}"},
+            }
+    if worker_llm.get("use_codex_subscription"):
+        api_key = get_worker_api_key()
+        if api_key:
+            headers: dict[str, str] = {
+                "Authorization": f"Bearer {api_key}",
+                "User-Agent": "CodexBar",
+            }
+            try:
+                from framework.runner.runner import get_codex_account_id
+
+                account_id = get_codex_account_id()
+                if account_id:
+                    headers["ChatGPT-Account-Id"] = account_id
+            except ImportError:
+                pass
+            return {
+                "extra_headers": headers,
+                "store": False,
+                "allowed_openai_params": ["store"],
+            }
+    if worker_llm.get("provider") == "ollama":
+        return {"num_ctx": worker_llm.get("num_ctx", 16384)}
+    return {}
+
+
+def get_worker_max_tokens() -> int:
+    """Return max_tokens for the worker LLM, falling back to default."""
+    worker_llm = get_hive_config().get("worker_llm", {})
+    if worker_llm and "max_tokens" in worker_llm:
+        return worker_llm["max_tokens"]
+    return get_max_tokens()
+
+
+def get_worker_max_context_tokens() -> int:
+    """Return max_context_tokens for the worker LLM, falling back to default."""
+    worker_llm = get_hive_config().get("worker_llm", {})
+    if worker_llm and "max_context_tokens" in worker_llm:
+        return worker_llm["max_context_tokens"]
+    return get_max_context_tokens()
+
+
 def get_max_tokens() -> int:
    """Return the configured max_tokens, falling back to DEFAULT_MAX_TOKENS."""
    return get_hive_config().get("llm", {}).get("max_tokens", DEFAULT_MAX_TOKENS)


+DEFAULT_MAX_CONTEXT_TOKENS = 32_000
+OPENROUTER_API_BASE = "https://openrouter.ai/api/v1"
+
+
+def get_max_context_tokens() -> int:
+    """Return the configured max_context_tokens, falling back to DEFAULT_MAX_CONTEXT_TOKENS."""
+    return get_hive_config().get("llm", {}).get("max_context_tokens", DEFAULT_MAX_CONTEXT_TOKENS)
+
+
 def get_api_key() -> str | None:
    """Return the API key, supporting env var, Claude Code subscription, Codex, and ZAI Code.

@@ -90,6 +255,28 @@ def get_api_key() -> str | None:
        except ImportError:
            pass

+    # Kimi Code subscription: read API key from ~/.kimi/config.toml
+    if llm.get("use_kimi_code_subscription"):
+        try:
+            from framework.runner.runner import get_kimi_code_token
+
+            token = get_kimi_code_token()
+            if token:
+                return token
+        except ImportError:
+            pass
+
+    # Antigravity subscription: read OAuth token from accounts JSON
+    if llm.get("use_antigravity_subscription"):
+        try:
+            from framework.runner.runner import get_antigravity_token
+
+            token = get_antigravity_token()
+            if token:
+                return token
+        except ImportError:
+            pass
+
    # Standard env-var path (covers ZAI Code and all API-key providers)
    api_key_env_var = llm.get("api_key_env_var")
    if api_key_env_var:
@@ -97,18 +284,116 @@ def get_api_key() -> str | None:
    return None


+# OAuth credentials for Antigravity are fetched from the opencode-antigravity-auth project.
+# This project reverse-engineered and published the public OAuth credentials
+# for Google's Antigravity/Cloud Code Assist API.
+# Source: https://github.com/NoeFabris/opencode-antigravity-auth
+_ANTIGRAVITY_CREDENTIALS_URL = (
+    "https://raw.githubusercontent.com/NoeFabris/opencode-antigravity-auth/dev/src/constants.ts"
+)
+_antigravity_credentials_cache: tuple[str | None, str | None] = (None, None)
+
+
+def _fetch_antigravity_credentials() -> tuple[str | None, str | None]:
+    """Fetch OAuth client ID and secret from the public npm package source on GitHub."""
+    global _antigravity_credentials_cache
+    if _antigravity_credentials_cache[0] and _antigravity_credentials_cache[1]:
+        return _antigravity_credentials_cache
+
+    import re
+    import urllib.request
+
+    try:
+        req = urllib.request.Request(
+            _ANTIGRAVITY_CREDENTIALS_URL, headers={"User-Agent": "Hive/1.0"}
+        )
+        with urllib.request.urlopen(req, timeout=10) as resp:
+            content = resp.read().decode("utf-8")
+            id_match = re.search(r'ANTIGRAVITY_CLIENT_ID\s*=\s*"([^"]+)"', content)
+            secret_match = re.search(r'ANTIGRAVITY_CLIENT_SECRET\s*=\s*"([^"]+)"', content)
+            client_id = id_match.group(1) if id_match else None
+            client_secret = secret_match.group(1) if secret_match else None
+            if client_id and client_secret:
+                _antigravity_credentials_cache = (client_id, client_secret)
+            return client_id, client_secret
+    except Exception as e:
+        logger.debug("Failed to fetch Antigravity credentials from public source: %s", e)
+    return None, None
+
+
+def get_antigravity_client_id() -> str:
+    """Return the Antigravity OAuth application client ID.
+
+    Checked in order:
+    1. ``ANTIGRAVITY_CLIENT_ID`` environment variable
+    2. ``llm.antigravity_client_id`` in ~/.hive/configuration.json
+    3. Fetch from public source (opencode-antigravity-auth project on GitHub)
+    """
+    env = os.environ.get("ANTIGRAVITY_CLIENT_ID")
+    if env:
+        return env
+    cfg_val = get_hive_config().get("llm", {}).get("antigravity_client_id")
+    if cfg_val:
+        return cfg_val
+    # Fetch from public source
+    client_id, _ = _fetch_antigravity_credentials()
+    if client_id:
+        return client_id
+    raise RuntimeError("Could not obtain Antigravity OAuth client ID")
+
+
+def get_antigravity_client_secret() -> str | None:
+    """Return the Antigravity OAuth client secret.
+
+    Checked in order:
+    1. ``ANTIGRAVITY_CLIENT_SECRET`` environment variable
+    2. ``llm.antigravity_client_secret`` in ~/.hive/configuration.json
+    3. Fetch from public source (opencode-antigravity-auth project on GitHub)
+
+    Returns None when not found — token refresh will be skipped and
+    the caller must use whatever access token is already available.
+    """
+    env = os.environ.get("ANTIGRAVITY_CLIENT_SECRET")
+    if env:
+        return env
+    cfg_val = get_hive_config().get("llm", {}).get("antigravity_client_secret") or None
+    if cfg_val:
+        return cfg_val
+    # Fetch from public source
+    _, secret = _fetch_antigravity_credentials()
+    return secret
+
+
 def get_gcu_enabled() -> bool:
    """Return whether GCU (browser automation) is enabled in user config."""
    return get_hive_config().get("gcu_enabled", True)


+def get_gcu_viewport_scale() -> float:
+    """Return GCU viewport scale factor (0.1-1.0), default 0.8."""
+    scale = get_hive_config().get("gcu_viewport_scale", 0.8)
+    if isinstance(scale, (int, float)) and 0.1 <= scale <= 1.0:
+        return float(scale)
+    return 0.8
+
+
 def get_api_base() -> str | None:
    """Return the api_base URL for OpenAI-compatible endpoints, if configured."""
    llm = get_hive_config().get("llm", {})
    if llm.get("use_codex_subscription"):
        # Codex subscription routes through the ChatGPT backend, not api.openai.com.
        return "https://chatgpt.com/backend-api/codex"
-    return llm.get("api_base")
+    if llm.get("use_kimi_code_subscription"):
+        # Kimi Code uses an Anthropic-compatible endpoint (no /v1 suffix).
+        return "https://api.kimi.com/coding"
+    if llm.get("use_antigravity_subscription"):
+        # Antigravity uses AntigravityProvider directly — no api_base needed.
+        return None
+    if llm.get("api_base"):
+        return llm["api_base"]
+    if str(llm.get("provider", "")).lower() == "openrouter":
+        return OPENROUTER_API_BASE
+    return None


 def get_llm_extra_kwargs() -> dict[str, Any]:
@@ -149,6 +434,11 @@ def get_llm_extra_kwargs() -> dict[str, Any]:
                "store": False,
                "allowed_openai_params": ["store"],
            }
+    if llm.get("provider") == "ollama":
+        # Pass num_ctx to Ollama so it doesn't silently truncate the ~9.5k Queen prompt.
+        # Ollama's default num_ctx is only 2048. We set it to 16384 here so LiteLLM
+        # passes it through as a provider-specific option.
+        return {"num_ctx": llm.get("num_ctx", 16384)}
    return {}


@@ -164,6 +454,7 @@ class RuntimeConfig:
    model: str = field(default_factory=get_preferred_model)
    temperature: float = 0.7
    max_tokens: int = field(default_factory=get_max_tokens)
+    max_context_tokens: int = field(default_factory=get_max_context_tokens)
    api_key: str | None = field(default_factory=get_api_key)
    api_base: str | None = field(default_factory=get_api_base)
    extra_kwargs: dict[str, Any] = field(default_factory=get_llm_extra_kwargs)
@@ -6,7 +6,7 @@ This module provides secure credential storage with:
 - Template-based usage: {{cred.key}} patterns for injection
 - Bipartisan model: Store stores values, tools define usage
 - Provider system: Extensible lifecycle management (refresh, validate)
- Multiple backends: Encrypted files, env vars, HashiCorp Vault
+- Multiple backends: Encrypted files, env vars

 Quick Start:
    from core.framework.credentials import CredentialStore, CredentialObject
@@ -38,8 +38,6 @@ For Aden server sync:
        AdenSyncProvider,
    )

-For Vault integration:
-    from core.framework.credentials.vault import HashiCorpVaultStorage
 """

 from .key_storage import (
@@ -142,17 +142,27 @@ def save_aden_api_key(key: str) -> None:
    os.environ[ADEN_ENV_VAR] = key


-def delete_aden_api_key() -> None:
-    """Remove ADEN_API_KEY from the encrypted store and ``os.environ``."""
+def delete_aden_api_key() -> bool:
+    """Remove ADEN_API_KEY from the encrypted store and ``os.environ``.
+
+    Returns True if the key existed and was deleted, False otherwise.
+    """
+    deleted = False
    try:
        from .storage import EncryptedFileStorage

        storage = EncryptedFileStorage()
-        storage.delete(ADEN_CREDENTIAL_ID)
+        deleted = storage.delete(ADEN_CREDENTIAL_ID)
+    except (FileNotFoundError, PermissionError) as e:
+        logger.debug("Could not delete %s from encrypted store: %s", ADEN_CREDENTIAL_ID, e)
    except Exception:
-        logger.debug("Could not delete %s from encrypted store", ADEN_CREDENTIAL_ID)
-
+        logger.warning(
+            "Unexpected error deleting %s from encrypted store",
+            ADEN_CREDENTIAL_ID,
+            exc_info=True,
+        )
    os.environ.pop(ADEN_ENV_VAR, None)
+    return deleted


 # ---------------------------------------------------------------------------
@@ -167,8 +177,10 @@ def _read_credential_key_file() -> str | None:
            value = CREDENTIAL_KEY_PATH.read_text(encoding="utf-8").strip()
            if value:
                return value
+    except (FileNotFoundError, PermissionError) as e:
+        logger.debug("Could not read %s: %s", CREDENTIAL_KEY_PATH, e)
    except Exception:
-        logger.debug("Could not read %s", CREDENTIAL_KEY_PATH)
+        logger.warning("Unexpected error reading %s", CREDENTIAL_KEY_PATH, exc_info=True)
    return None


@@ -196,6 +208,12 @@ def _read_aden_from_encrypted_store() -> str | None:
        cred = storage.load(ADEN_CREDENTIAL_ID)
        if cred:
            return cred.get_key("api_key")
+    except (FileNotFoundError, PermissionError, KeyError) as e:
+        logger.debug("Could not load %s from encrypted store: %s", ADEN_CREDENTIAL_ID, e)
    except Exception:
-        logger.debug("Could not load %s from encrypted store", ADEN_CREDENTIAL_ID)
+        logger.warning(
+            "Unexpected error loading %s from encrypted store",
+            ADEN_CREDENTIAL_ID,
+            exc_info=True,
+        )
    return None
@@ -27,6 +27,7 @@ from __future__ import annotations

 import getpass
 import json
+import logging
 import os
 import sys
 from collections.abc import Callable
@@ -37,6 +38,8 @@ from typing import TYPE_CHECKING, Any
 if TYPE_CHECKING:
    from framework.graph import NodeSpec

+logger = logging.getLogger(__name__)
+

 # ANSI colors for terminal output
 class Colors:
@@ -365,8 +368,11 @@ class CredentialSetupSession:
        self._print("")
        try:
            api_key = self.password_fn(f"Paste your {cred.env_var}: ").strip()
+        except (EOFError, OSError) as exc:
+            logger.debug("Password input unavailable, falling back to plain input: %s", exc)
+            api_key = self._input(f"Paste your {cred.env_var}: ").strip()
        except Exception:
-            # Fallback to regular input if password input fails
+            logger.warning("Unexpected error reading password input", exc_info=True)
            api_key = self._input(f"Paste your {cred.env_var}: ").strip()

        if not api_key:
@@ -403,7 +409,11 @@ class CredentialSetupSession:

            try:
                aden_key = self.password_fn("Paste your ADEN_API_KEY: ").strip()
+            except (EOFError, OSError) as exc:
+                logger.debug("Password input unavailable for ADEN_API_KEY: %s", exc)
+                aden_key = self._input("Paste your ADEN_API_KEY: ").strip()
            except Exception:
+                logger.warning("Unexpected error reading ADEN_API_KEY input", exc_info=True)
                aden_key = self._input("Paste your ADEN_API_KEY: ").strip()

            if not aden_key:
@@ -433,8 +443,10 @@ class CredentialSetupSession:
                    value = store.get_key(cred_id, cred.credential_key)
                    if value:
                        os.environ[cred.env_var] = value
+                except (KeyError, OSError) as exc:
+                    logger.debug("Could not export credential to env: %s", exc)
                except Exception:
-                    pass
+                    logger.warning("Unexpected error exporting credential to env", exc_info=True)
                return True
            else:
                self._print(
@@ -457,9 +469,12 @@ class CredentialSetupSession:
                "message": result.message,
                "details": result.details,
            }
-        except Exception:
+        except ImportError:
            # No health checker available
            return None
+        except Exception:
+            logger.warning("Health check failed for %s", cred.credential_name, exc_info=True)
+            return None

    def _store_credential(self, cred: MissingCredential, value: str) -> None:
        """Store credential in encrypted store and export to env."""
@@ -561,7 +576,11 @@ def _load_nodes_from_python_agent(agent_path: Path) -> list:
        sys.modules[spec.name] = module
        spec.loader.exec_module(module)
        return getattr(module, "nodes", [])
+    except (ImportError, OSError) as exc:
+        logger.debug("Could not load agent module: %s", exc)
+        return []
    except Exception:
+        logger.warning("Unexpected error loading agent module", exc_info=True)
        return []


@@ -588,7 +607,11 @@ def _load_nodes_from_json_agent(agent_json: Path) -> list:
                )
            )
        return nodes
+    except (json.JSONDecodeError, KeyError, OSError) as exc:
+        logger.debug("Could not load JSON agent: %s", exc)
+        return []
    except Exception:
+        logger.warning("Unexpected error loading JSON agent", exc_info=True)
        return []


@@ -51,6 +51,16 @@ def ensure_credential_key_env() -> None:
                    if found and value:
                        os.environ[var_name] = value
                        logger.debug("Loaded %s from shell config", var_name)
+        # Also load the currently configured LLM env var even if it's not in CREDENTIAL_SPECS.
+        # This keeps quickstart-written keys available to fresh processes on Unix shells.
+        from framework.config import get_hive_config
+
+        llm_env_var = str(get_hive_config().get("llm", {}).get("api_key_env_var", "")).strip()
+        if llm_env_var and not os.environ.get(llm_env_var):
+            found, value = check_env_var_in_shell_config(llm_env_var)
+            if found and value:
+                os.environ[llm_env_var] = value
+                logger.debug("Loaded configured LLM env var %s from shell config", llm_env_var)
    except ImportError:
        pass

@@ -1,55 +0,0 @@
-"""
-HashiCorp Vault integration for the credential store.
-
-This module provides enterprise-grade secret management through
-HashiCorp Vault integration.
-
-Quick Start:
-    from core.framework.credentials import CredentialStore
-    from core.framework.credentials.vault import HashiCorpVaultStorage
-
-    # Configure Vault storage
-    storage = HashiCorpVaultStorage(
-        url="https://vault.example.com:8200",
-        # token read from VAULT_TOKEN env var
-        mount_point="secret",
-        path_prefix="hive/agents/prod"
-    )
-
-    # Create credential store with Vault backend
-    store = CredentialStore(storage=storage)
-
-    # Use normally - credentials are stored in Vault
-    credential = store.get_credential("my_api")
-
-Requirements:
-    pip install hvac
-
-Authentication:
-    Set the VAULT_TOKEN environment variable or pass the token directly:
-
-        export VAULT_TOKEN="hvs.xxxxxxxxxxxxx"
-
-    For production, consider using Vault auth methods:
-    - Kubernetes auth
-    - AppRole auth
-    - AWS IAM auth
-
-Vault Configuration:
-    Ensure KV v2 secrets engine is enabled:
-
-        vault secrets enable -path=secret kv-v2
-
-    Grant appropriate policies:
-
-        path "secret/data/hive/credentials/*" {
-            capabilities = ["create", "read", "update", "delete", "list"]
-        }
-        path "secret/metadata/hive/credentials/*" {
-            capabilities = ["list", "delete"]
-        }
-"""
-
-from .hashicorp import HashiCorpVaultStorage
-
-__all__ = ["HashiCorpVaultStorage"]
@@ -1,394 +0,0 @@
-"""
-HashiCorp Vault storage adapter.
-
-Provides integration with HashiCorp Vault for enterprise secret management.
-Requires the 'hvac' package: uv pip install hvac
-"""
-
-from __future__ import annotations
-
-import logging
-import os
-from datetime import datetime
-from typing import Any
-
-from pydantic import SecretStr
-
-from ..models import CredentialKey, CredentialObject, CredentialType
-from ..storage import CredentialStorage
-
-logger = logging.getLogger(__name__)
-
-
-class HashiCorpVaultStorage(CredentialStorage):
-    """
-    HashiCorp Vault storage adapter.
-
-    Features:
-    - KV v2 secrets engine support
-    - Namespace support (Enterprise)
-    - Automatic secret versioning
-    - Audit logging via Vault
-
-    The adapter stores credentials in Vault's KV v2 secrets engine with
-    the following structure:
-
-        {mount_point}/data/{path_prefix}/{credential_id}
-        └── data:
-            ├── _type: "oauth2"
-            ├── access_token: "xxx"
-            ├── refresh_token: "yyy"
-            ├── _expires_access_token: "2024-01-26T12:00:00"
-            └── _provider_id: "oauth2"
-
-    Example:
-        storage = HashiCorpVaultStorage(
-            url="https://vault.example.com:8200",
-            token="hvs.xxx",  # Or use VAULT_TOKEN env var
-            mount_point="secret",
-            path_prefix="hive/credentials"
-        )
-
-        store = CredentialStore(storage=storage)
-
-        # Credentials are now stored in Vault
-        store.save_credential(credential)
-        credential = store.get_credential("my_api")
-
-    Authentication:
-        The adapter uses token-based authentication. The token can be provided:
-        1. Directly via the 'token' parameter
-        2. Via the VAULT_TOKEN environment variable
-
-        For production, consider using:
-        - Kubernetes auth method
-        - AppRole auth method
-        - AWS IAM auth method
-
-    Requirements:
-        uv pip install hvac
-    """
-
-    def __init__(
-        self,
-        url: str,
-        token: str | None = None,
-        mount_point: str = "secret",
-        path_prefix: str = "hive/credentials",
-        namespace: str | None = None,
-        verify_ssl: bool = True,
-    ):
-        """
-        Initialize Vault storage.
-
-        Args:
-            url: Vault server URL (e.g., https://vault.example.com:8200)
-            token: Vault token. If None, reads from VAULT_TOKEN env var
-            mount_point: KV secrets engine mount point (default: "secret")
-            path_prefix: Path prefix for all credentials
-            namespace: Vault namespace (Enterprise feature)
-            verify_ssl: Whether to verify SSL certificates
-
-        Raises:
-            ImportError: If hvac is not installed
-            ValueError: If authentication fails
-        """
-        try:
-            import hvac
-        except ImportError as e:
-            raise ImportError(
-                "HashiCorp Vault support requires 'hvac'. Install with: uv pip install hvac"
-            ) from e
-
-        self._url = url
-        self._token = token or os.environ.get("VAULT_TOKEN")
-        self._mount = mount_point
-        self._prefix = path_prefix
-        self._namespace = namespace
-
-        if not self._token:
-            raise ValueError(
-                "Vault token required. Set VAULT_TOKEN env var or pass token parameter."
-            )
-
-        self._client = hvac.Client(
-            url=url,
-            token=self._token,
-            namespace=namespace,
-            verify=verify_ssl,
-        )
-
-        if not self._client.is_authenticated():
-            raise ValueError("Vault authentication failed. Check token and server URL.")
-
-        logger.info(f"Connected to HashiCorp Vault at {url}")
-
-    def _path(self, credential_id: str) -> str:
-        """Build Vault path for credential."""
-        # Sanitize credential_id
-        safe_id = credential_id.replace("/", "_").replace("\\", "_")
-        return f"{self._prefix}/{safe_id}"
-
-    def save(self, credential: CredentialObject) -> None:
-        """Save credential to Vault KV v2."""
-        path = self._path(credential.id)
-        data = self._serialize_for_vault(credential)
-
-        try:
-            self._client.secrets.kv.v2.create_or_update_secret(
-                path=path,
-                secret=data,
-                mount_point=self._mount,
-            )
-            logger.debug(f"Saved credential '{credential.id}' to Vault at {path}")
-        except Exception as e:
-            logger.error(f"Failed to save credential '{credential.id}' to Vault: {e}")
-            raise
-
-    def load(self, credential_id: str) -> CredentialObject | None:
-        """Load credential from Vault."""
-        path = self._path(credential_id)
-
-        try:
-            response = self._client.secrets.kv.v2.read_secret_version(
-                path=path,
-                mount_point=self._mount,
-            )
-            data = response["data"]["data"]
-            return self._deserialize_from_vault(credential_id, data)
-        except Exception as e:
-            # Check if it's a "not found" error
-            error_str = str(e).lower()
-            if "not found" in error_str or "404" in error_str:
-                logger.debug(f"Credential '{credential_id}' not found in Vault")
-                return None
-            logger.error(f"Failed to load credential '{credential_id}' from Vault: {e}")
-            raise
-
-    def delete(self, credential_id: str) -> bool:
-        """Delete credential from Vault (all versions)."""
-        path = self._path(credential_id)
-
-        try:
-            self._client.secrets.kv.v2.delete_metadata_and_all_versions(
-                path=path,
-                mount_point=self._mount,
-            )
-            logger.debug(f"Deleted credential '{credential_id}' from Vault")
-            return True
-        except Exception as e:
-            error_str = str(e).lower()
-            if "not found" in error_str or "404" in error_str:
-                return False
-            logger.error(f"Failed to delete credential '{credential_id}' from Vault: {e}")
-            raise
-
-    def list_all(self) -> list[str]:
-        """List all credentials under the prefix."""
-        try:
-            response = self._client.secrets.kv.v2.list_secrets(
-                path=self._prefix,
-                mount_point=self._mount,
-            )
-            keys = response.get("data", {}).get("keys", [])
-            # Remove trailing slashes from folder names
-            return [k.rstrip("/") for k in keys]
-        except Exception as e:
-            error_str = str(e).lower()
-            if "not found" in error_str or "404" in error_str:
-                return []
-            logger.error(f"Failed to list credentials from Vault: {e}")
-            raise
-
-    def exists(self, credential_id: str) -> bool:
-        """Check if credential exists in Vault."""
-        try:
-            path = self._path(credential_id)
-            self._client.secrets.kv.v2.read_secret_version(
-                path=path,
-                mount_point=self._mount,
-            )
-            return True
-        except Exception:
-            return False
-
-    def _serialize_for_vault(self, credential: CredentialObject) -> dict[str, Any]:
-        """Convert credential to Vault secret format."""
-        data: dict[str, Any] = {
-            "_type": credential.credential_type.value,
-        }
-
-        if credential.provider_id:
-            data["_provider_id"] = credential.provider_id
-
-        if credential.description:
-            data["_description"] = credential.description
-
-        if credential.auto_refresh:
-            data["_auto_refresh"] = "true"
-
-        # Store each key
-        for key_name, key in credential.keys.items():
-            data[key_name] = key.get_secret_value()
-
-            if key.expires_at:
-                data[f"_expires_{key_name}"] = key.expires_at.isoformat()
-
-            if key.metadata:
-                data[f"_metadata_{key_name}"] = str(key.metadata)
-
-        return data
-
-    def _deserialize_from_vault(self, credential_id: str, data: dict[str, Any]) -> CredentialObject:
-        """Reconstruct credential from Vault secret."""
-        # Extract metadata fields
-        cred_type = CredentialType(data.pop("_type", "api_key"))
-        provider_id = data.pop("_provider_id", None)
-        description = data.pop("_description", "")
-        auto_refresh = data.pop("_auto_refresh", "") == "true"
-
-        # Build keys dict
-        keys: dict[str, CredentialKey] = {}
-
-        # Find all non-metadata keys
-        key_names = [k for k in data.keys() if not k.startswith("_")]
-
-        for key_name in key_names:
-            value = data[key_name]
-
-            # Check for expiration
-            expires_at = None
-            expires_key = f"_expires_{key_name}"
-            if expires_key in data:
-                try:
-                    expires_at = datetime.fromisoformat(data[expires_key])
-                except (ValueError, TypeError):
-                    pass
-
-            # Check for metadata
-            metadata: dict[str, Any] = {}
-            metadata_key = f"_metadata_{key_name}"
-            if metadata_key in data:
-                try:
-                    import ast
-
-                    metadata = ast.literal_eval(data[metadata_key])
-                except (ValueError, SyntaxError):
-                    pass
-
-            keys[key_name] = CredentialKey(
-                name=key_name,
-                value=SecretStr(value),
-                expires_at=expires_at,
-                metadata=metadata,
-            )
-
-        return CredentialObject(
-            id=credential_id,
-            credential_type=cred_type,
-            keys=keys,
-            provider_id=provider_id,
-            description=description,
-            auto_refresh=auto_refresh,
-        )
-
-    # --- Vault-Specific Operations ---
-
-    def get_secret_metadata(self, credential_id: str) -> dict[str, Any] | None:
-        """
-        Get Vault metadata for a secret (version info, timestamps, etc.).
-
-        Args:
-            credential_id: The credential identifier
-
-        Returns:
-            Metadata dict or None if not found
-        """
-        path = self._path(credential_id)
-
-        try:
-            response = self._client.secrets.kv.v2.read_secret_metadata(
-                path=path,
-                mount_point=self._mount,
-            )
-            return response.get("data", {})
-        except Exception:
-            return None
-
-    def soft_delete(self, credential_id: str, versions: list[int] | None = None) -> bool:
-        """
-        Soft delete specific versions (can be recovered).
-
-        Args:
-            credential_id: The credential identifier
-            versions: Version numbers to delete. If None, deletes latest.
-
-        Returns:
-            True if successful
-        """
-        path = self._path(credential_id)
-
-        try:
-            if versions:
-                self._client.secrets.kv.v2.delete_secret_versions(
-                    path=path,
-                    versions=versions,
-                    mount_point=self._mount,
-                )
-            else:
-                self._client.secrets.kv.v2.delete_latest_version_of_secret(
-                    path=path,
-                    mount_point=self._mount,
-                )
-            return True
-        except Exception as e:
-            logger.error(f"Soft delete failed for '{credential_id}': {e}")
-            return False
-
-    def undelete(self, credential_id: str, versions: list[int]) -> bool:
-        """
-        Recover soft-deleted versions.
-
-        Args:
-            credential_id: The credential identifier
-            versions: Version numbers to recover
-
-        Returns:
-            True if successful
-        """
-        path = self._path(credential_id)
-
-        try:
-            self._client.secrets.kv.v2.undelete_secret_versions(
-                path=path,
-                versions=versions,
-                mount_point=self._mount,
-            )
-            return True
-        except Exception as e:
-            logger.error(f"Undelete failed for '{credential_id}': {e}")
-            return False
-
-    def load_version(self, credential_id: str, version: int) -> CredentialObject | None:
-        """
-        Load a specific version of a credential.
-
-        Args:
-            credential_id: The credential identifier
-            version: Version number to load
-
-        Returns:
-            CredentialObject or None
-        """
-        path = self._path(credential_id)
-
-        try:
-            response = self._client.secrets.kv.v2.read_secret_version(
-                path=path,
-                version=version,
-                mount_point=self._mount,
-            )
-            data = response["data"]["data"]
-            return self._deserialize_from_vault(credential_id, data)
-        except Exception:
-            return None
@@ -0,0 +1,76 @@
+"""CLI command for the LLM debug log viewer."""
+
+import argparse
+import subprocess
+import sys
+from pathlib import Path
+
+_SCRIPT = Path(__file__).resolve().parents[3] / "scripts" / "llm_debug_log_visualizer.py"
+
+
+def register_debugger_commands(subparsers: argparse._SubParsersAction) -> None:
+    """Register the ``hive debugger`` command."""
+    parser = subparsers.add_parser(
+        "debugger",
+        help="Open the LLM debug log viewer",
+        description=(
+            "Start a local server that lets you browse LLM debug sessions "
+            "recorded in ~/.hive/llm_logs. Sessions are loaded on demand so "
+            "the browser stays responsive."
+        ),
+    )
+    parser.add_argument(
+        "--session",
+        help="Execution ID to select initially.",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=0,
+        help="Port for the local server (0 = auto-pick a free port).",
+    )
+    parser.add_argument(
+        "--logs-dir",
+        help="Directory containing JSONL log files (default: ~/.hive/llm_logs).",
+    )
+    parser.add_argument(
+        "--limit-files",
+        type=int,
+        default=None,
+        help="Maximum number of newest log files to scan (default: 200).",
+    )
+    parser.add_argument(
+        "--output",
+        help="Write a static HTML file instead of starting a server.",
+    )
+    parser.add_argument(
+        "--no-open",
+        action="store_true",
+        help="Start the server but do not open a browser.",
+    )
+    parser.add_argument(
+        "--include-tests",
+        action="store_true",
+        help="Show test/mock sessions (hidden by default).",
+    )
+    parser.set_defaults(func=cmd_debugger)
+
+
+def cmd_debugger(args: argparse.Namespace) -> int:
+    """Launch the LLM debug log visualizer."""
+    cmd: list[str] = [sys.executable, str(_SCRIPT)]
+    if args.session:
+        cmd += ["--session", args.session]
+    if args.port:
+        cmd += ["--port", str(args.port)]
+    if args.logs_dir:
+        cmd += ["--logs-dir", args.logs_dir]
+    if args.limit_files is not None:
+        cmd += ["--limit-files", str(args.limit_files)]
+    if args.output:
+        cmd += ["--output", args.output]
+    if args.no_open:
+        cmd.append("--no-open")
+    if args.include_tests:
+        cmd.append("--include-tests")
+    return subprocess.call(cmd)
@@ -1,11 +1,6 @@
 """Graph structures: Goals, Nodes, Edges, and Execution."""

-from framework.graph.client_io import (
-    ActiveNodeClientIO,
-    ClientIOGateway,
-    InertNodeClientIO,
-    NodeClientIO,
-)
+from framework.graph.context import GraphContext
 from framework.graph.context_handoff import ContextHandoff, HandoffContext
 from framework.graph.conversation import ConversationStore, Message, NodeConversation
 from framework.graph.edge import DEFAULT_MAX_TOKENS, EdgeCondition, EdgeSpec, GraphSpec
@@ -19,6 +14,14 @@ from framework.graph.event_loop_node import (
 from framework.graph.executor import GraphExecutor
 from framework.graph.goal import Constraint, Goal, GoalStatus, SuccessCriterion
 from framework.graph.node import NodeContext, NodeProtocol, NodeResult, NodeSpec
+from framework.graph.worker_agent import (
+    Activation,
+    FanOutTag,
+    FanOutTracker,
+    WorkerAgent,
+    WorkerCompletion,
+    WorkerLifecycle,
+)

 __all__ = [
    # Goal
@@ -51,9 +54,12 @@ __all__ = [
    # Context Handoff
    "ContextHandoff",
    "HandoffContext",
-    # Client I/O
-    "NodeClientIO",
-    "ActiveNodeClientIO",
-    "InertNodeClientIO",
-    "ClientIOGateway",
+    # Worker Agent
+    "WorkerAgent",
+    "WorkerLifecycle",
+    "WorkerCompletion",
+    "Activation",
+    "FanOutTag",
+    "FanOutTracker",
+    "GraphContext",
 ]
@@ -1,175 +0,0 @@
-"""
-Client I/O gateway for graph nodes.
-
-Provides the bridge between node code and external clients:
- ActiveNodeClientIO: for client_facing=True nodes (streams output, accepts input)
- InertNodeClientIO: for client_facing=False nodes (logs internally, redirects input)
- ClientIOGateway: factory that creates the right variant per node
-"""
-
-from __future__ import annotations
-
-import asyncio
-import logging
-from abc import ABC, abstractmethod
-from collections.abc import AsyncIterator
-from typing import TYPE_CHECKING
-
-if TYPE_CHECKING:
-    from framework.runtime.event_bus import EventBus
-
-logger = logging.getLogger(__name__)
-
-
-class NodeClientIO(ABC):
-    """Abstract base for node client I/O."""
-
-    @abstractmethod
-    async def emit_output(self, content: str, is_final: bool = False) -> None:
-        """Emit output content. If is_final=True, signal end of stream."""
-
-    @abstractmethod
-    async def request_input(self, prompt: str = "", timeout: float | None = None) -> str:
-        """Request input. Behavior depends on whether the node is client-facing."""
-
-
-class ActiveNodeClientIO(NodeClientIO):
-    """
-    Client I/O for client_facing=True nodes.
-
-    - emit_output() queues content and publishes CLIENT_OUTPUT_DELTA.
-    - request_input() publishes CLIENT_INPUT_REQUESTED, then awaits provide_input().
-    - output_stream() yields queued content until the final sentinel.
-    """
-
-    def __init__(
-        self,
-        node_id: str,
-        event_bus: EventBus | None = None,
-        execution_id: str = "",
-    ) -> None:
-        self.node_id = node_id
-        self._event_bus = event_bus
-        self._execution_id = execution_id
-
-        self._output_queue: asyncio.Queue[str | None] = asyncio.Queue()
-        self._output_snapshot = ""
-
-        self._input_event: asyncio.Event | None = None
-        self._input_result: str | None = None
-
-    async def emit_output(self, content: str, is_final: bool = False) -> None:
-        self._output_snapshot += content
-        await self._output_queue.put(content)
-
-        if self._event_bus is not None:
-            await self._event_bus.emit_client_output_delta(
-                stream_id=self.node_id,
-                node_id=self.node_id,
-                content=content,
-                snapshot=self._output_snapshot,
-                execution_id=self._execution_id or None,
-            )
-
-        if is_final:
-            await self._output_queue.put(None)
-
-    async def request_input(self, prompt: str = "", timeout: float | None = None) -> str:
-        if self._input_event is not None:
-            raise RuntimeError("request_input already pending for this node")
-
-        self._input_event = asyncio.Event()
-        self._input_result = None
-
-        if self._event_bus is not None:
-            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,
-            )
-
-        try:
-            if timeout is not None:
-                await asyncio.wait_for(self._input_event.wait(), timeout=timeout)
-            else:
-                await self._input_event.wait()
-        finally:
-            self._input_event = None
-
-        if self._input_result is None:
-            raise RuntimeError("input event was set but no input was provided")
-        result = self._input_result
-        self._input_result = None
-        return result
-
-    async def provide_input(self, content: str) -> None:
-        """Called externally to fulfill a pending request_input()."""
-        if self._input_event is None:
-            raise RuntimeError("no pending request_input to fulfill")
-        self._input_result = content
-        self._input_event.set()
-
-    async def output_stream(self) -> AsyncIterator[str]:
-        """Async iterator that yields output chunks until the final sentinel."""
-        while True:
-            chunk = await self._output_queue.get()
-            if chunk is None:
-                break
-            yield chunk
-
-
-class InertNodeClientIO(NodeClientIO):
-    """
-    Client I/O for client_facing=False nodes.
-
-    - emit_output() publishes NODE_INTERNAL_OUTPUT (content is not discarded).
-    - request_input() publishes NODE_INPUT_BLOCKED and returns a redirect string.
-    """
-
-    def __init__(
-        self,
-        node_id: str,
-        event_bus: EventBus | None = None,
-    ) -> None:
-        self.node_id = node_id
-        self._event_bus = event_bus
-
-    async def emit_output(self, content: str, is_final: bool = False) -> None:
-        if self._event_bus is not None:
-            await self._event_bus.emit_node_internal_output(
-                stream_id=self.node_id,
-                node_id=self.node_id,
-                content=content,
-            )
-
-    async def request_input(self, prompt: str = "", timeout: float | None = None) -> str:
-        if self._event_bus is not None:
-            await self._event_bus.emit_node_input_blocked(
-                stream_id=self.node_id,
-                node_id=self.node_id,
-                prompt=prompt,
-            )
-        return (
-            "You are an internal processing node. There is no user to interact with."
-            " Work with the data provided in your inputs to complete your task."
-        )
-
-
-class ClientIOGateway:
-    """Factory that creates the appropriate NodeClientIO for a node."""
-
-    def __init__(self, event_bus: EventBus | None = None) -> None:
-        self._event_bus = event_bus
-
-    def create_io(self, node_id: str, client_facing: bool, execution_id: str = "") -> NodeClientIO:
-        if client_facing:
-            return ActiveNodeClientIO(
-                node_id=node_id,
-                event_bus=self._event_bus,
-                execution_id=execution_id,
-            )
-        return InertNodeClientIO(
-            node_id=node_id,
-            event_bus=self._event_bus,
-        )
@@ -0,0 +1,327 @@
+"""Shared graph execution context helpers.
+
+This module centralizes:
+- Graph-run shared state (`GraphContext`)
+- Scoped buffer permission shaping for a node
+- Per-node accounts prompt resolution
+- Canonical `NodeContext` construction
+"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass, field
+from typing import Any
+
+from framework.graph.edge import GraphSpec
+from framework.graph.goal import Goal
+from framework.graph.node import DataBuffer, NodeContext, NodeProtocol, NodeSpec
+from framework.runtime.core import Runtime
+
+
+@dataclass
+class GraphContext:
+    """Shared state for one graph execution run."""
+
+    graph: GraphSpec
+    goal: Goal
+    buffer: DataBuffer
+    runtime: Runtime
+    llm: Any  # LLMProvider
+    tools: list[Any]  # list[Tool]
+    tool_executor: Any  # Callable
+    event_bus: Any  # GraphScopedEventBus
+    execution_id: str
+    stream_id: str
+    run_id: str
+    storage_path: Any  # Path | None
+    runtime_logger: Any = None
+    node_registry: dict[str, NodeProtocol] = field(default_factory=dict)
+    node_spec_registry: dict[str, NodeSpec] = field(default_factory=dict)
+    parallel_config: Any = None  # ParallelExecutionConfig | None
+    enable_parallel_execution: bool = True
+    is_continuous: bool = False
+    continuous_conversation: Any = None
+    cumulative_tools: list[Any] = field(default_factory=list)
+    cumulative_tool_names: set[str] = field(default_factory=set)
+    cumulative_output_keys: list[str] = field(default_factory=list)
+    accounts_prompt: str = ""
+    accounts_data: list[dict] | None = None
+    tool_provider_map: dict[str, str] | None = None
+    skills_catalog_prompt: str = ""
+    protocols_prompt: str = ""
+    skill_dirs: list[str] = field(default_factory=list)
+    context_warn_ratio: float | None = None
+    batch_init_nudge: str | None = None
+    dynamic_tools_provider: Any = None
+    dynamic_prompt_provider: Any = None
+    dynamic_memory_provider: Any = None
+    iteration_metadata_provider: Any = None
+    loop_config: dict[str, Any] = field(default_factory=dict)
+    path: list[str] = field(default_factory=list)
+    node_visit_counts: dict[str, int] = field(default_factory=dict)
+    _path_lock: asyncio.Lock = field(default_factory=asyncio.Lock)
+    _visits_lock: asyncio.Lock = field(default_factory=asyncio.Lock)
+    # Fan-out buffer conflict tracking: key → worker_id that wrote it
+    _fanout_written_keys: dict[str, str] = field(default_factory=dict)
+    # Retry tracking: worker_id → retry_count (for execution quality assessment)
+    retry_counts: dict[str, int] = field(default_factory=dict)
+    nodes_with_retries: set[str] = field(default_factory=set)
+    # Colony memory reflection at node handoff
+    colony_memory_dir: Any = None  # Path | None
+    worker_sessions_dir: Any = None  # Path | None
+    colony_recall_cache: dict[str, str] = field(default_factory=dict)
+    colony_reflect_llm: Any = None  # LLMProvider for reflection
+    _colony_reflect_lock: asyncio.Lock = field(default_factory=asyncio.Lock)
+
+
+def build_scoped_buffer(buffer: DataBuffer, node_spec: NodeSpec) -> DataBuffer:
+    """Create a node-scoped buffer view.
+
+    When permissions are already restricted, auto-include framework-managed
+    `_`-prefixed keys used by the default skill protocols.
+    """
+
+    read_keys = list(node_spec.input_keys)
+    write_keys = list(node_spec.output_keys)
+
+    if read_keys or write_keys:
+        from framework.skills.defaults import DATA_BUFFER_KEYS as _skill_keys
+
+        existing_underscore = [k for k in buffer._data if k.startswith("_")]
+        extra_keys = set(_skill_keys) | set(existing_underscore)
+
+        for key in extra_keys:
+            if read_keys and key not in read_keys:
+                read_keys.append(key)
+            if write_keys and key not in write_keys:
+                write_keys.append(key)
+
+    return buffer.with_permissions(read_keys=read_keys, write_keys=write_keys)
+
+
+def build_node_accounts_prompt(
+    *,
+    accounts_prompt: str,
+    accounts_data: list[dict] | None,
+    tool_provider_map: dict[str, str] | None,
+    node_tool_names: list[str] | None,
+    fallback_to_default: bool = False,
+) -> str:
+    """Resolve the accounts prompt for one node."""
+
+    resolved = accounts_prompt
+    if accounts_data and tool_provider_map:
+        from framework.graph.prompting import build_accounts_prompt
+
+        filtered = build_accounts_prompt(
+            accounts_data,
+            tool_provider_map,
+            node_tool_names=node_tool_names,
+        )
+        if filtered or not fallback_to_default:
+            resolved = filtered
+
+    return resolved
+
+
+def _resolve_available_tools(
+    *,
+    node_spec: NodeSpec,
+    tools: list[Any],
+    override_tools: list[Any] | None,
+) -> list[Any]:
+    """Select tools available to the current node."""
+
+    if override_tools is not None:
+        return list(override_tools)
+
+    if not node_spec.tools:
+        return []
+
+    return [tool for tool in tools if tool.name in node_spec.tools]
+
+
+def _derive_input_data(buffer: DataBuffer, input_keys: list[str]) -> dict[str, Any]:
+    """Collect node inputs from the shared buffer."""
+
+    input_data: dict[str, Any] = {}
+    for key in input_keys:
+        value = buffer.read(key)
+        if value is not None:
+            input_data[key] = value
+    return input_data
+
+
+def build_node_context(
+    *,
+    runtime: Runtime,
+    node_spec: NodeSpec,
+    buffer: DataBuffer,
+    goal: Goal,
+    llm: Any,
+    tools: list[Any],
+    max_tokens: int,
+    input_data: dict[str, Any] | None = None,
+    derive_input_data_from_buffer: bool = False,
+    runtime_logger: Any = None,
+    pause_event: Any = None,
+    continuous_mode: bool = False,
+    inherited_conversation: Any = None,
+    override_tools: list[Any] | None = None,
+    cumulative_output_keys: list[str] | None = None,
+    event_triggered: bool = False,
+    accounts_prompt: str = "",
+    accounts_data: list[dict] | None = None,
+    tool_provider_map: dict[str, str] | None = None,
+    fallback_to_default_accounts_prompt: bool = False,
+    identity_prompt: str = "",
+    narrative: str = "",
+    execution_id: str = "",
+    run_id: str = "",
+    stream_id: str = "",
+    node_registry: dict[str, NodeSpec] | None = None,
+    all_tools: list[Any] | None = None,
+    shared_node_registry: dict[str, NodeProtocol] | None = None,
+    dynamic_tools_provider: Any = None,
+    dynamic_prompt_provider: Any = None,
+    dynamic_memory_provider: Any = None,
+    iteration_metadata_provider: Any = None,
+    skills_catalog_prompt: str = "",
+    protocols_prompt: str = "",
+    skill_dirs: list[str] | None = None,
+    default_skill_warn_ratio: float | None = None,
+    default_skill_batch_nudge: str | None = None,
+    memory_prompt: str = "",
+) -> NodeContext:
+    """Build a canonical `NodeContext` for graph execution."""
+
+    available_tools = _resolve_available_tools(
+        node_spec=node_spec,
+        tools=tools,
+        override_tools=override_tools,
+    )
+    scoped_buffer = build_scoped_buffer(buffer, node_spec)
+    node_accounts_prompt = build_node_accounts_prompt(
+        accounts_prompt=accounts_prompt,
+        accounts_data=accounts_data,
+        tool_provider_map=tool_provider_map,
+        node_tool_names=node_spec.tools,
+        fallback_to_default=fallback_to_default_accounts_prompt,
+    )
+
+    resolved_input_data = (
+        _derive_input_data(buffer, node_spec.input_keys)
+        if input_data is None and derive_input_data_from_buffer
+        else dict(input_data or {})
+    )
+
+    return NodeContext(
+        runtime=runtime,
+        node_id=node_spec.id,
+        node_spec=node_spec,
+        buffer=scoped_buffer,
+        input_data=resolved_input_data,
+        llm=llm,
+        available_tools=available_tools,
+        goal_context=goal.to_prompt_context(),
+        goal=goal,
+        max_tokens=max_tokens,
+        runtime_logger=runtime_logger,
+        pause_event=pause_event,
+        continuous_mode=continuous_mode,
+        inherited_conversation=inherited_conversation,
+        cumulative_output_keys=cumulative_output_keys or [],
+        event_triggered=event_triggered,
+        accounts_prompt=node_accounts_prompt,
+        identity_prompt=identity_prompt,
+        narrative=narrative,
+        memory_prompt=memory_prompt,
+        execution_id=execution_id,
+        run_id=run_id,
+        stream_id=stream_id,
+        node_registry=node_registry or {},
+        all_tools=list(all_tools or tools),
+        shared_node_registry=shared_node_registry or {},
+        dynamic_tools_provider=dynamic_tools_provider,
+        dynamic_prompt_provider=dynamic_prompt_provider,
+        dynamic_memory_provider=dynamic_memory_provider,
+        iteration_metadata_provider=iteration_metadata_provider,
+        skills_catalog_prompt=skills_catalog_prompt,
+        protocols_prompt=protocols_prompt,
+        skill_dirs=list(skill_dirs or []),
+        default_skill_warn_ratio=default_skill_warn_ratio,
+        default_skill_batch_nudge=default_skill_batch_nudge,
+    )
+
+
+def build_node_context_from_graph_context(
+    graph_context: GraphContext,
+    *,
+    node_spec: NodeSpec,
+    pause_event: Any = None,
+    input_data: dict[str, Any] | None = None,
+    derive_input_data_from_buffer: bool = True,
+    override_tools: list[Any] | None = None,
+    inherited_conversation: Any = None,
+    cumulative_output_keys: list[str] | None = None,
+    event_triggered: bool = False,
+    identity_prompt: str | None = None,
+    narrative: str = "",
+    node_registry: dict[str, NodeSpec] | None = None,
+    fallback_to_default_accounts_prompt: bool = True,
+) -> NodeContext:
+    """Build `NodeContext` using shared graph-run state."""
+
+    gc = graph_context
+    resolved_override_tools = override_tools
+    if resolved_override_tools is None and gc.is_continuous and gc.cumulative_tools:
+        resolved_override_tools = list(gc.cumulative_tools)
+
+    resolved_inherited_conversation = inherited_conversation
+    if resolved_inherited_conversation is None and gc.is_continuous:
+        resolved_inherited_conversation = gc.continuous_conversation
+
+    resolved_output_keys = cumulative_output_keys
+    if resolved_output_keys is None and gc.is_continuous:
+        resolved_output_keys = list(gc.cumulative_output_keys)
+
+    return build_node_context(
+        runtime=gc.runtime,
+        node_spec=node_spec,
+        buffer=gc.buffer,
+        goal=gc.goal,
+        llm=gc.llm,
+        tools=gc.tools,
+        max_tokens=gc.graph.max_tokens,
+        input_data=input_data,
+        derive_input_data_from_buffer=derive_input_data_from_buffer,
+        runtime_logger=gc.runtime_logger,
+        pause_event=pause_event,
+        continuous_mode=gc.is_continuous,
+        inherited_conversation=resolved_inherited_conversation,
+        override_tools=resolved_override_tools,
+        cumulative_output_keys=resolved_output_keys,
+        event_triggered=event_triggered,
+        accounts_prompt=gc.accounts_prompt,
+        accounts_data=gc.accounts_data,
+        tool_provider_map=gc.tool_provider_map,
+        fallback_to_default_accounts_prompt=fallback_to_default_accounts_prompt,
+        identity_prompt=identity_prompt if identity_prompt is not None else getattr(gc.graph, "identity_prompt", "") or "",
+        narrative=narrative,
+        execution_id=gc.execution_id,
+        run_id=gc.run_id,
+        stream_id=gc.stream_id,
+        node_registry=node_registry or gc.node_spec_registry,
+        all_tools=gc.tools,
+        shared_node_registry=gc.node_registry,
+        dynamic_tools_provider=gc.dynamic_tools_provider,
+        dynamic_prompt_provider=gc.dynamic_prompt_provider,
+        dynamic_memory_provider=gc.dynamic_memory_provider,
+        iteration_metadata_provider=gc.iteration_metadata_provider,
+        skills_catalog_prompt=gc.skills_catalog_prompt,
+        protocols_prompt=gc.protocols_prompt,
+        skill_dirs=gc.skill_dirs,
+        default_skill_warn_ratio=gc.context_warn_ratio,
+        default_skill_batch_nudge=gc.batch_init_nudge,
+    )
@@ -8,6 +8,13 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Any, Literal, Protocol, runtime_checkable

+LEGACY_RUN_ID = "__legacy_run__"
+
+
+def is_legacy_run_id(run_id: str | None) -> bool:
+    """True when run_id represents pre-migration (no run boundary) data."""
+    return run_id is None or run_id == LEGACY_RUN_ID
+

@dataclass
 class Message:
@@ -33,10 +40,22 @@ class Message:
    is_transition_marker: bool = False
    # True when this message is real human input (from /chat), not a system prompt
    is_client_input: bool = False
+    # Optional image content blocks (e.g. from browser_screenshot)
+    image_content: list[dict[str, Any]] | None = None
+    # True when message contains an activated skill body (AS-10: never prune)
+    is_skill_content: bool = False
+    # Logical worker run identifier for shared-session persistence
+    run_id: str | None = None

    def to_llm_dict(self) -> dict[str, Any]:
        """Convert to OpenAI-format message dict."""
        if self.role == "user":
+            if self.image_content:
+                blocks: list[dict[str, Any]] = []
+                if self.content:
+                    blocks.append({"type": "text", "text": self.content})
+                blocks.extend(self.image_content)
+                return {"role": "user", "content": blocks}
            return {"role": "user", "content": self.content}

        if self.role == "assistant":
@@ -47,6 +66,15 @@ class Message:

        # role == "tool"
        content = f"ERROR: {self.content}" if self.is_error else self.content
+        if self.image_content:
+            # Multimodal tool result: text + image content blocks
+            blocks: list[dict[str, Any]] = [{"type": "text", "text": content}]
+            blocks.extend(self.image_content)
+            return {
+                "role": "tool",
+                "tool_call_id": self.tool_use_id,
+                "content": blocks,
+            }
        return {
            "role": "tool",
            "tool_call_id": self.tool_use_id,
@@ -72,6 +100,10 @@ class Message:
            d["is_transition_marker"] = self.is_transition_marker
        if self.is_client_input:
            d["is_client_input"] = self.is_client_input
+        if self.image_content is not None:
+            d["image_content"] = self.image_content
+        if self.run_id is not None:
+            d["run_id"] = self.run_id
        return d

    @classmethod
@@ -87,9 +119,41 @@ class Message:
            phase_id=data.get("phase_id"),
            is_transition_marker=data.get("is_transition_marker", False),
            is_client_input=data.get("is_client_input", False),
+            image_content=data.get("image_content"),
+            run_id=data.get("run_id"),
        )


+def _normalize_cursor(cursor: dict[str, Any] | None) -> dict[str, Any]:
+    """Normalize legacy and run-scoped cursor formats into one flat shape."""
+    return dict(cursor) if cursor else {}
+
+
+def get_cursor_next_seq(cursor: dict[str, Any] | None) -> int | None:
+    next_seq = (cursor or {}).get("next_seq")
+    return next_seq if isinstance(next_seq, int) else None
+
+
+def update_cursor_next_seq(cursor: dict[str, Any] | None, next_seq: int) -> dict[str, Any]:
+    updated = dict(cursor or {})
+    updated["next_seq"] = next_seq
+    return updated
+
+
+def get_run_cursor(cursor: dict[str, Any] | None, run_id: str | None) -> dict[str, Any] | None:
+    return dict(cursor) if cursor else None
+
+
+def update_run_cursor(
+    cursor: dict[str, Any] | None,
+    run_id: str | None,
+    values: dict[str, Any],
+) -> dict[str, Any]:
+    updated = dict(cursor or {})
+    updated.update(values)
+    return updated
+
+
 def _extract_spillover_filename(content: str) -> str | None:
    """Extract spillover filename from a tool result annotation.

@@ -239,7 +303,7 @@ class ConversationStore(Protocol):

    async def read_cursor(self) -> dict[str, Any] | None: ...

-    async def delete_parts_before(self, seq: int) -> None: ...
+    async def delete_parts_before(self, seq: int, run_id: str | None = None) -> None: ...

    async def close(self) -> None: ...

@@ -307,13 +371,14 @@ class NodeConversation:
    def __init__(
        self,
        system_prompt: str = "",
-        max_history_tokens: int = 32000,
+        max_context_tokens: int = 32000,
        compaction_threshold: float = 0.8,
        output_keys: list[str] | None = None,
        store: ConversationStore | None = None,
+        run_id: str | None = None,
    ) -> None:
        self._system_prompt = system_prompt
-        self._max_history_tokens = max_history_tokens
+        self._max_context_tokens = max_context_tokens
        self._compaction_threshold = compaction_threshold
        self._output_keys = output_keys
        self._store = store
@@ -322,6 +387,7 @@ class NodeConversation:
        self._meta_persisted: bool = False
        self._last_api_input_tokens: int | None = None
        self._current_phase: str | None = None
+        self._run_id: str | None = run_id

    # --- Properties --------------------------------------------------------

@@ -373,14 +439,17 @@ class NodeConversation:
        *,
        is_transition_marker: bool = False,
        is_client_input: bool = False,
+        image_content: list[dict[str, Any]] | None = None,
    ) -> Message:
        msg = Message(
            seq=self._next_seq,
            role="user",
            content=content,
            phase_id=self._current_phase,
+            run_id=self._run_id,
            is_transition_marker=is_transition_marker,
            is_client_input=is_client_input,
+            image_content=image_content,
        )
        self._messages.append(msg)
        self._next_seq += 1
@@ -398,6 +467,7 @@ class NodeConversation:
            content=content,
            tool_calls=tool_calls,
            phase_id=self._current_phase,
+            run_id=self._run_id,
        )
        self._messages.append(msg)
        self._next_seq += 1
@@ -409,6 +479,8 @@ class NodeConversation:
        tool_use_id: str,
        content: str,
        is_error: bool = False,
+        image_content: list[dict[str, Any]] | None = None,
+        is_skill_content: bool = False,
    ) -> Message:
        msg = Message(
            seq=self._next_seq,
@@ -417,6 +489,9 @@ class NodeConversation:
            tool_use_id=tool_use_id,
            is_error=is_error,
            phase_id=self._current_phase,
+            image_content=image_content,
+            is_skill_content=is_skill_content,
+            run_id=self._run_id,
        )
        self._messages.append(msg)
        self._next_seq += 1
@@ -525,16 +600,16 @@ class NodeConversation:
        self._last_api_input_tokens = actual_input_tokens

    def usage_ratio(self) -> float:
-        """Current token usage as a fraction of *max_history_tokens*.
+        """Current token usage as a fraction of *max_context_tokens*.

-        Returns 0.0 when ``max_history_tokens`` is zero (unlimited).
+        Returns 0.0 when ``max_context_tokens`` is zero (unlimited).
        """
-        if self._max_history_tokens <= 0:
+        if self._max_context_tokens <= 0:
            return 0.0
-        return self.estimate_tokens() / self._max_history_tokens
+        return self.estimate_tokens() / self._max_context_tokens

    def needs_compaction(self) -> bool:
-        return self.estimate_tokens() >= self._max_history_tokens * self._compaction_threshold
+        return self.estimate_tokens() >= self._max_context_tokens * self._compaction_threshold

    # --- Output-key extraction ---------------------------------------------

@@ -610,8 +685,15 @@ class NodeConversation:
                continue
            if msg.is_error:
                continue  # never prune errors
+            if msg.is_skill_content:
+                continue  # never prune activated skill instructions (AS-10)
            if msg.content.startswith("[Pruned tool result"):
                continue  # already pruned
+            # Tiny results (set_output acks, confirmations) — pruning
+            # saves negligible space but makes the LLM think the call
+            # failed, causing costly retries.
+            if len(msg.content) < 100:
+                continue

            # Phase-aware: protect current phase messages
            if self._current_phase and msg.phase_id == self._current_phase:
@@ -653,6 +735,7 @@ class NodeConversation:
                is_error=msg.is_error,
                phase_id=msg.phase_id,
                is_transition_marker=msg.is_transition_marker,
+                run_id=msg.run_id,
            )
            count += 1

@@ -729,14 +812,14 @@ class NodeConversation:
            summary_seq = self._next_seq
            self._next_seq += 1

-        summary_msg = Message(seq=summary_seq, role="user", content=summary)
+        summary_msg = Message(seq=summary_seq, role="user", content=summary, run_id=self._run_id)

        # Persist
        if self._store:
            delete_before = recent_messages[0].seq if recent_messages else self._next_seq
            await self._store.delete_parts_before(delete_before)
            await self._store.write_part(summary_msg.seq, summary_msg.to_storage_dict())
-            await self._store.write_cursor({"next_seq": self._next_seq})
+            await self._write_next_seq()

        self._messages = [summary_msg] + recent_messages
        self._last_api_input_tokens = None  # reset; next LLM call will recalibrate
@@ -842,6 +925,7 @@ class NodeConversation:
                                is_error=msg.is_error,
                                phase_id=msg.phase_id,
                                is_transition_marker=msg.is_transition_marker,
+                                run_id=msg.run_id,
                            )
                        )
                    else:
@@ -869,6 +953,7 @@ class NodeConversation:
                            is_error=msg.is_error,
                            phase_id=msg.phase_id,
                            is_transition_marker=msg.is_transition_marker,
+                            run_id=msg.run_id,
                        )
                    )
                else:
@@ -901,8 +986,7 @@ class NodeConversation:
            full_path = str((spill_path / conv_filename).resolve())
            ref_parts.append(
                f"[Previous conversation saved to '{full_path}'. "
-                f"Use load_data('{conv_filename}'), read_file('{full_path}'), "
-                f"or run_command('cat \"{full_path}\"') to review if needed.]"
+                f"Use load_data('{conv_filename}') to review if needed.]"
            )
        elif not collapsed_msgs:
            ref_parts.append("[Previous freeform messages compacted.]")
@@ -927,7 +1011,7 @@ class NodeConversation:
            ref_seq = self._next_seq
            self._next_seq += 1

-        ref_msg = Message(seq=ref_seq, role="user", content=ref_content)
+        ref_msg = Message(seq=ref_seq, role="user", content=ref_content, run_id=self._run_id)

        # Persist: delete old messages from store, write reference + kept structural.
        # In aggressive mode, collapsed messages may be interspersed with kept
@@ -941,7 +1025,7 @@ class NodeConversation:
            # Write kept structural messages (they may have been modified)
            for msg in kept_structural:
                await self._store.write_part(msg.seq, msg.to_storage_dict())
-            await self._store.write_cursor({"next_seq": self._next_seq})
+            await self._write_next_seq()

        # Reassemble: reference + kept structural (in original order) + recent
        self._messages = [ref_msg] + kept_structural + recent_messages
@@ -978,7 +1062,7 @@ class NodeConversation:
        """Remove all messages, keep system prompt, preserve ``_next_seq``."""
        if self._store:
            await self._store.delete_parts_before(self._next_seq)
-            await self._store.write_cursor({"next_seq": self._next_seq})
+            await self._write_next_seq()
        self._messages.clear()
        self._last_api_input_tokens = None

@@ -1020,22 +1104,32 @@ class NodeConversation:
        if not self._meta_persisted:
            await self._persist_meta()
        await self._store.write_part(message.seq, message.to_storage_dict())
-        await self._store.write_cursor({"next_seq": self._next_seq})
+        await self._write_next_seq()

    async def _persist_meta(self) -> None:
-        """Lazily write conversation metadata to the store (called once)."""
+        """Lazily write conversation metadata to the store (called once).
+
+        When ``self._run_id`` is set, metadata is written flat for backward
+        compatibility (run-scoped isolation has been reverted).
+        """
        if self._store is None:
            return
-        await self._store.write_meta(
-            {
-                "system_prompt": self._system_prompt,
-                "max_history_tokens": self._max_history_tokens,
-                "compaction_threshold": self._compaction_threshold,
-                "output_keys": self._output_keys,
-            }
-        )
+        run_meta = {
+            "system_prompt": self._system_prompt,
+            "max_context_tokens": self._max_context_tokens,
+            "compaction_threshold": self._compaction_threshold,
+            "output_keys": self._output_keys,
+        }
+        await self._store.write_meta(run_meta)
        self._meta_persisted = True

+    async def _write_next_seq(self) -> None:
+        if self._store is None:
+            return
+        cursor = await self._store.read_cursor() or {}
+        cursor["next_seq"] = self._next_seq
+        await self._store.write_cursor(cursor)
+
    # --- Restore -----------------------------------------------------------

    @classmethod
@@ -1043,6 +1137,7 @@ class NodeConversation:
        cls,
        store: ConversationStore,
        phase_id: str | None = None,
+        run_id: str | None = None,
    ) -> NodeConversation | None:
        """Reconstruct a NodeConversation from a store.

@@ -1052,6 +1147,9 @@ class NodeConversation:
                Used in isolated mode so a node only sees its own
                messages in the shared flat store.  In continuous mode
                pass ``None`` to load all parts.
+            run_id: If set, only load parts matching this run_id.
+                Ensures intentional restarts (new run_id) start fresh
+                while crash recovery (same run_id) resumes correctly.

        Returns ``None`` if the store contains no metadata (i.e. the
        conversation was never persisted).
@@ -1062,21 +1160,27 @@ class NodeConversation:

        conv = cls(
            system_prompt=meta.get("system_prompt", ""),
-            max_history_tokens=meta.get("max_history_tokens", 32000),
+            max_context_tokens=meta.get("max_context_tokens", 32000),
            compaction_threshold=meta.get("compaction_threshold", 0.8),
            output_keys=meta.get("output_keys"),
            store=store,
+            run_id=run_id,
        )
        conv._meta_persisted = True

        parts = await store.read_parts()
        if phase_id:
            parts = [p for p in parts if p.get("phase_id") == phase_id]
+        # Filter by run_id so intentional restarts (new run_id) start fresh
+        # while crash recovery (same run_id) loads prior parts.
+        if run_id and not is_legacy_run_id(run_id):
+            parts = [p for p in parts if p.get("run_id") == run_id]
        conv._messages = [Message.from_storage_dict(p) for p in parts]

        cursor = await store.read_cursor()
-        if cursor:
-            conv._next_seq = cursor["next_seq"]
+        next_seq = get_cursor_next_seq(cursor)
+        if next_seq is not None:
+            conv._next_seq = next_seq
        elif conv._messages:
            conv._next_seq = conv._messages[-1].seq + 1

@@ -37,7 +37,7 @@ async def evaluate_phase_completion(
    phase_description: str,
    success_criteria: str,
    accumulator_state: dict[str, Any],
-    max_history_tokens: int = 8_196,
+    max_context_tokens: int = 8_196,
 ) -> PhaseVerdict:
    """Level 2 judge: read the conversation and evaluate quality.

@@ -50,7 +50,7 @@ async def evaluate_phase_completion(
        phase_description: Description of the phase
        success_criteria: Natural-language criteria for phase completion
        accumulator_state: Current output key values
-        max_history_tokens: Main conversation token budget (judge gets 20%)
+        max_context_tokens: Main conversation token budget (judge gets 20%)

    Returns:
        PhaseVerdict with action and optional feedback
@@ -89,7 +89,7 @@ FEEDBACK: (reason if RETRY, empty if ACCEPT)"""
        response = await llm.acomplete(
            messages=[{"role": "user", "content": user_prompt}],
            system=system_prompt,
-            max_tokens=max(1024, max_history_tokens // 5),
+            max_tokens=max(1024, max_context_tokens // 5),
            max_retries=1,
        )
        if not response.content or not response.content.strip():
@@ -108,7 +108,7 @@ class EdgeSpec(BaseModel):
        self,
        source_success: bool,
        source_output: dict[str, Any],
-        memory: dict[str, Any],
+        buffer_data: dict[str, Any],
        llm: Any | None = None,
        goal: Any | None = None,
        source_node_name: str | None = None,
@@ -120,7 +120,7 @@ class EdgeSpec(BaseModel):
        Args:
            source_success: Whether the source node succeeded
            source_output: Output from the source node
-            memory: Current shared memory state
+            buffer_data: Current data buffer state
            llm: LLM provider for LLM_DECIDE edges
            goal: Goal object for LLM_DECIDE edges
            source_node_name: Name of source node (for LLM context)
@@ -139,7 +139,7 @@ class EdgeSpec(BaseModel):
            return not source_success

        if self.condition == EdgeCondition.CONDITIONAL:
-            return self._evaluate_condition(source_output, memory)
+            return self._evaluate_condition(source_output, buffer_data)

        if self.condition == EdgeCondition.LLM_DECIDE:
            if llm is None or goal is None:
@@ -150,7 +150,7 @@ class EdgeSpec(BaseModel):
                goal=goal,
                source_success=source_success,
                source_output=source_output,
-                memory=memory,
+                buffer_data=buffer_data,
                source_node_name=source_node_name,
                target_node_name=target_node_name,
            )
@@ -160,7 +160,7 @@ class EdgeSpec(BaseModel):
    def _evaluate_condition(
        self,
        output: dict[str, Any],
-        memory: dict[str, Any],
+        buffer_data: dict[str, Any],
    ) -> bool:
        """Evaluate a conditional expression."""

@@ -168,14 +168,14 @@ class EdgeSpec(BaseModel):
            return True

        # Build evaluation context
-        # Include memory keys directly for easier access in conditions
+        # Include buffer keys directly for easier access in conditions
        context = {
            "output": output,
-            "memory": memory,
+            "buffer": buffer_data,
            "result": output.get("result"),
            "true": True,  # Allow lowercase true/false in conditions
            "false": False,
-            **memory,  # Unpack memory keys directly into context
+            **buffer_data,  # Unpack buffer keys directly into context
        }

        try:
@@ -186,7 +186,7 @@ class EdgeSpec(BaseModel):
            expr_vars = {
                k: repr(context[k])
                for k in context
-                if k not in ("output", "memory", "result", "true", "false")
+                if k not in ("output", "buffer", "result", "true", "false")
                and k in self.condition_expr
            }
            logger.info(
@@ -209,7 +209,7 @@ class EdgeSpec(BaseModel):
        goal: Any,
        source_success: bool,
        source_output: dict[str, Any],
-        memory: dict[str, Any],
+        buffer_data: dict[str, Any],
        source_node_name: str | None,
        target_node_name: str | None,
    ) -> bool:
@@ -234,8 +234,8 @@ class EdgeSpec(BaseModel):
 Should we proceed to: {target_node_name or self.target}?
 Edge description: {self.description or "No description"}

-**Context from memory**:
-{json.dumps({k: str(v)[:100] for k, v in list(memory.items())[:5]}, indent=2)}
+**Context from data buffer**:
+{json.dumps({k: str(v)[:100] for k, v in list(buffer_data.items())[:5]}, indent=2)}

 Evaluate whether proceeding to this next node is the right step toward achieving the goal.
 Consider:
@@ -276,14 +276,14 @@ Respond with ONLY a JSON object:
    def map_inputs(
        self,
        source_output: dict[str, Any],
-        memory: dict[str, Any],
+        buffer_data: dict[str, Any],
    ) -> dict[str, Any]:
        """
        Map source outputs to target inputs.

        Args:
            source_output: Output from source node
-            memory: Current shared memory
+            buffer_data: Current data buffer

        Returns:
            Input dict for target node
@@ -294,64 +294,14 @@ Respond with ONLY a JSON object:

        result = {}
        for target_key, source_key in self.input_mapping.items():
-            # Try source output first, then memory
+            # Try source output first, then buffer
            if source_key in source_output:
                result[target_key] = source_output[source_key]
-            elif source_key in memory:
-                result[target_key] = memory[source_key]
+            elif source_key in buffer_data:
+                result[target_key] = buffer_data[source_key]

        return result

-
-class AsyncEntryPointSpec(BaseModel):
-    """
-    Specification for an asynchronous entry point.
-
-    Used with AgentRuntime for multi-entry-point agents that handle
-    concurrent execution streams (e.g., webhook + API handlers).
-
-    Example:
-        AsyncEntryPointSpec(
-            id="webhook",
-            name="Zendesk Webhook Handler",
-            entry_node="process-webhook",
-            trigger_type="webhook",
-            isolation_level="shared",
-        )
-    """
-
-    id: str = Field(description="Unique identifier for this entry point")
-    name: str = Field(description="Human-readable name")
-    entry_node: str = Field(description="Node ID to start execution from")
-    trigger_type: str = Field(
-        default="manual",
-        description="How this entry point is triggered: webhook, api, timer, event, manual",
-    )
-    trigger_config: dict[str, Any] = Field(
-        default_factory=dict,
-        description="Trigger-specific configuration (e.g., webhook URL, timer interval)",
-    )
-    isolation_level: str = Field(
-        default="shared", description="State isolation: isolated, shared, or synchronized"
-    )
-    priority: int = Field(default=0, description="Execution priority (higher = more priority)")
-    max_concurrent: int = Field(
-        default=10, description="Maximum concurrent executions for this entry point"
-    )
-    max_resurrections: int = Field(
-        default=3,
-        description="Auto-restart on non-fatal failure (0 to disable)",
-    )
-
-    model_config = {"extra": "allow"}
-
-    def get_isolation_level(self):
-        """Convert string isolation level to enum (duck-type with EntryPointSpec)."""
-        from framework.runtime.execution_stream import IsolationLevel
-
-        return IsolationLevel(self.isolation_level)
-
-
 class GraphSpec(BaseModel):
    """
    Complete specification of an agent graph.
@@ -368,28 +318,8 @@ class GraphSpec(BaseModel):
            edges=[...],
        )

-    For multi-entry-point agents (concurrent streams):
-        GraphSpec(
-            id="support-agent-graph",
-            goal_id="support-001",
-            entry_node="process-webhook",  # Default entry
-            async_entry_points=[
-                AsyncEntryPointSpec(
-                    id="webhook",
-                    name="Zendesk Webhook",
-                    entry_node="process-webhook",
-                    trigger_type="webhook",
-                ),
-                AsyncEntryPointSpec(
-                    id="api",
-                    name="API Handler",
-                    entry_node="process-request",
-                    trigger_type="api",
-                ),
-            ],
-            nodes=[...],
-            edges=[...],
-        )
+    Triggers (timer, webhook, event) are now defined in ``triggers.json``
+    alongside the agent directory, not embedded in the graph spec.
    """

    id: str
@@ -402,12 +332,6 @@ class GraphSpec(BaseModel):
        default_factory=dict,
        description="Named entry points for resuming execution. Format: {name: node_id}",
    )
-    async_entry_points: list[AsyncEntryPointSpec] = Field(
-        default_factory=list,
-        description=(
-            "Asynchronous entry points for concurrent execution streams (used with AgentRuntime)"
-        ),
-    )
    terminal_nodes: list[str] = Field(
        default_factory=list, description="IDs of nodes that end execution"
    )
@@ -421,9 +345,9 @@ class GraphSpec(BaseModel):
    )
    edges: list[EdgeSpec] = Field(default_factory=list, description="All edge specifications")

-    # Shared memory keys
-    memory_keys: list[str] = Field(
-        default_factory=list, description="Keys available in shared memory"
+    # Data buffer keys
+    buffer_keys: list[str] = Field(
+        default_factory=list, description="Keys available in data buffer"
    )

    # Default LLM settings
@@ -486,17 +410,6 @@ class GraphSpec(BaseModel):
                return node
        return None

-    def has_async_entry_points(self) -> bool:
-        """Check if this graph uses async entry points (multi-stream execution)."""
-        return len(self.async_entry_points) > 0
-
-    def get_async_entry_point(self, entry_point_id: str) -> AsyncEntryPointSpec | None:
-        """Get an async entry point by ID."""
-        for ep in self.async_entry_points:
-            if ep.id == entry_point_id:
-                return ep
-        return None
-
    def get_outgoing_edges(self, node_id: str) -> list[EdgeSpec]:
        """Get all edges leaving a node, sorted by priority."""
        edges = [e for e in self.edges if e.source == node_id]
@@ -587,37 +500,6 @@ class GraphSpec(BaseModel):
        if not self.get_node(self.entry_node):
            errors.append(f"Entry node '{self.entry_node}' not found")

-        # Check async entry points
-        seen_entry_ids = set()
-        for entry_point in self.async_entry_points:
-            # Check for duplicate IDs
-            if entry_point.id in seen_entry_ids:
-                errors.append(f"Duplicate async entry point ID: '{entry_point.id}'")
-            seen_entry_ids.add(entry_point.id)
-
-            # Check entry node exists
-            if not self.get_node(entry_point.entry_node):
-                errors.append(
-                    f"Async entry point '{entry_point.id}' references "
-                    f"missing node '{entry_point.entry_node}'"
-                )
-
-            # Validate isolation level
-            valid_isolation = {"isolated", "shared", "synchronized"}
-            if entry_point.isolation_level not in valid_isolation:
-                errors.append(
-                    f"Async entry point '{entry_point.id}' has invalid isolation_level "
-                    f"'{entry_point.isolation_level}'. Valid: {valid_isolation}"
-                )
-
-            # Validate trigger type
-            valid_triggers = {"webhook", "api", "timer", "event", "manual"}
-            if entry_point.trigger_type not in valid_triggers:
-                errors.append(
-                    f"Async entry point '{entry_point.id}' has invalid trigger_type "
-                    f"'{entry_point.trigger_type}'. Valid: {valid_triggers}"
-                )
-
        # Check terminal nodes exist
        for term in self.terminal_nodes:
            if not self.get_node(term):
@@ -646,10 +528,6 @@ class GraphSpec(BaseModel):
        for entry_point_node in self.entry_points.values():
            to_visit.append(entry_point_node)

-        # Add all async entry points as valid starting points
-        for async_entry in self.async_entry_points:
-            to_visit.append(async_entry.entry_node)
-
        # Traverse from all entry points
        while to_visit:
            current = to_visit.pop()
@@ -666,36 +544,23 @@ class GraphSpec(BaseModel):
                for sub_agent_id in sub_agents:
                    reachable.add(sub_agent_id)

-        # Build set of async entry point nodes for quick lookup
-        async_entry_nodes = {ep.entry_node for ep in self.async_entry_points}
-
        for node in self.nodes:
            if node.id not in reachable:
-                # Skip if node is a pause node, entry point target, or async entry
-                # (pause/resume architecture and async entry points make reachable)
-                if (
-                    node.id in self.pause_nodes
-                    or node.id in self.entry_points.values()
-                    or node.id in async_entry_nodes
-                ):
+                # Skip if node is a pause node or entry point target
+                if node.id in self.pause_nodes or node.id in self.entry_points.values():
                    continue
                errors.append(f"Node '{node.id}' is unreachable from entry")

-        # Client-facing fan-out validation
-        fan_outs = self.detect_fan_out_nodes()
-        for source_id, targets in fan_outs.items():
-            client_facing_targets = [
-                t
-                for t in targets
-                if self.get_node(t) and getattr(self.get_node(t), "client_facing", False)
-            ]
-            if len(client_facing_targets) > 1:
-                errors.append(
-                    f"Fan-out from '{source_id}' has multiple client-facing nodes: "
-                    f"{client_facing_targets}. Only one branch may be client-facing."
+        for node in self.nodes:
+            if getattr(node, "client_facing", False) and getattr(node, "id", "") != "queen":
+                warnings.append(
+                    f"Node '{node.id}' sets deprecated client_facing=True. "
+                    "Only the queen talks directly to users now; migrate this node "
+                    "to queen-mediated escalation."
                )

        # Output key overlap on parallel event_loop nodes
+        fan_outs = self.detect_fan_out_nodes()
        for source_id, targets in fan_outs.items():
            event_loop_targets = [
                t
@@ -0,0 +1,6 @@
+"""EventLoopNode subpackage — modular components of the event loop orchestrator.
+
+All public symbols are re-exported by the parent ``event_loop_node.py`` for
+backward compatibility.  Internal consumers may import directly from these
+submodules for clarity.
+"""
@@ -0,0 +1,641 @@
+"""Conversation compaction pipeline.
+
+Implements the multi-level compaction strategy:
+1. Prune old tool results
+2. Structure-preserving compaction (spillover)
+3. LLM summary compaction (with recursive splitting)
+4. Emergency deterministic summary (no LLM)
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import re
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from framework.graph.conversation import NodeConversation
+from framework.graph.event_loop.event_publishing import publish_context_usage
+from framework.graph.event_loop.types import LoopConfig, OutputAccumulator
+from framework.graph.node import NodeContext
+from framework.runtime.event_bus import EventBus
+
+logger = logging.getLogger(__name__)
+
+# Limits for LLM compaction
+LLM_COMPACT_CHAR_LIMIT: int = 240_000
+LLM_COMPACT_MAX_DEPTH: int = 10
+
+
+async def compact(
+    ctx: NodeContext,
+    conversation: NodeConversation,
+    accumulator: OutputAccumulator | None,
+    *,
+    config: LoopConfig,
+    event_bus: EventBus | None,
+    char_limit: int = LLM_COMPACT_CHAR_LIMIT,
+    max_depth: int = LLM_COMPACT_MAX_DEPTH,
+) -> None:
+    """Run the full compaction pipeline if conversation needs compaction.
+
+    Pipeline stages (in order, short-circuits when budget is restored):
+    1. Prune old tool results
+    2. Structure-preserving compaction (free, no LLM)
+    3. LLM summary compaction (recursive split if too large)
+    4. Emergency deterministic summary (fallback)
+    """
+    ratio_before = conversation.usage_ratio()
+    phase_grad = getattr(ctx, "continuous_mode", False)
+    pre_inventory: list[dict[str, Any]] | None = None
+
+    if ratio_before >= 1.0:
+        pre_inventory = build_message_inventory(conversation)
+
+    # --- Step 1: Prune old tool results (free, fast) ---
+    protect = max(2000, config.max_context_tokens // 12)
+    pruned = await conversation.prune_old_tool_results(
+        protect_tokens=protect,
+        min_prune_tokens=max(1000, protect // 3),
+    )
+    if pruned > 0:
+        logger.info(
+            "Pruned %d old tool results: %.0f%% -> %.0f%%",
+            pruned,
+            ratio_before * 100,
+            conversation.usage_ratio() * 100,
+        )
+    if not conversation.needs_compaction():
+        await log_compaction(
+            ctx,
+            conversation,
+            ratio_before,
+            event_bus,
+            pre_inventory=pre_inventory,
+        )
+        return
+
+    # --- Step 2: Standard structure-preserving compaction (free, no LLM) ---
+    spill_dir = config.spillover_dir
+    if spill_dir:
+        await conversation.compact_preserving_structure(
+            spillover_dir=spill_dir,
+            keep_recent=4,
+            phase_graduated=phase_grad,
+        )
+    if not conversation.needs_compaction():
+        await log_compaction(
+            ctx,
+            conversation,
+            ratio_before,
+            event_bus,
+            pre_inventory=pre_inventory,
+        )
+        return
+
+    # --- Step 3: LLM summary compaction ---
+    if ctx.llm is not None:
+        logger.info(
+            "LLM summary compaction triggered (%.0f%% usage)",
+            conversation.usage_ratio() * 100,
+        )
+        try:
+            summary = await llm_compact(
+                ctx,
+                list(conversation.messages),
+                accumulator,
+                char_limit=char_limit,
+                max_depth=max_depth,
+                max_context_tokens=config.max_context_tokens,
+            )
+            await conversation.compact(
+                summary,
+                keep_recent=2,
+                phase_graduated=phase_grad,
+            )
+        except Exception as e:
+            logger.warning("LLM compaction failed: %s", e)
+
+    if not conversation.needs_compaction():
+        await log_compaction(
+            ctx,
+            conversation,
+            ratio_before,
+            event_bus,
+            pre_inventory=pre_inventory,
+        )
+        return
+
+    # --- Step 4: Emergency deterministic summary (LLM failed/unavailable) ---
+    logger.warning(
+        "Emergency compaction (%.0f%% usage)",
+        conversation.usage_ratio() * 100,
+    )
+    summary = build_emergency_summary(ctx, accumulator, conversation, config)
+    await conversation.compact(
+        summary,
+        keep_recent=1,
+        phase_graduated=phase_grad,
+    )
+    await log_compaction(
+        ctx,
+        conversation,
+        ratio_before,
+        event_bus,
+        pre_inventory=pre_inventory,
+    )
+
+
+# --- LLM compaction with binary-search splitting ----------------------
+
+
+async def llm_compact(
+    ctx: NodeContext,
+    messages: list,
+    accumulator: OutputAccumulator | None = None,
+    _depth: int = 0,
+    *,
+    char_limit: int = LLM_COMPACT_CHAR_LIMIT,
+    max_depth: int = LLM_COMPACT_MAX_DEPTH,
+    max_context_tokens: int = 128_000,
+) -> str:
+    """Summarise *messages* with LLM, splitting recursively if too large.
+
+    If the formatted text exceeds ``LLM_COMPACT_CHAR_LIMIT`` or the LLM
+    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``).
+    """
+    from framework.graph.conversation import extract_tool_call_history
+    from framework.graph.event_loop.tool_result_handler import is_context_too_large_error
+
+    if _depth > max_depth:
+        raise RuntimeError(f"LLM compaction recursion limit ({max_depth})")
+
+    formatted = format_messages_for_summary(messages)
+
+    # Proactive split: avoid wasting an API call on oversized input
+    if len(formatted) > char_limit and len(messages) > 1:
+        summary = await _llm_compact_split(
+            ctx,
+            messages,
+            accumulator,
+            _depth,
+            char_limit=char_limit,
+            max_depth=max_depth,
+            max_context_tokens=max_context_tokens,
+        )
+    else:
+        prompt = build_llm_compaction_prompt(
+            ctx,
+            accumulator,
+            formatted,
+            max_context_tokens=max_context_tokens,
+        )
+        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."
+                ),
+                max_tokens=summary_budget,
+            )
+            summary = response.content
+        except Exception as e:
+            if is_context_too_large_error(e) and len(messages) > 1:
+                logger.info(
+                    "LLM context too large (depth=%d, msgs=%d) — splitting",
+                    _depth,
+                    len(messages),
+                )
+                summary = await _llm_compact_split(
+                    ctx,
+                    messages,
+                    accumulator,
+                    _depth,
+                    char_limit=char_limit,
+                    max_depth=max_depth,
+                    max_context_tokens=max_context_tokens,
+                )
+            else:
+                raise
+
+    # Append tool history at top level only
+    if _depth == 0:
+        tool_history = extract_tool_call_history(messages)
+        if tool_history and "TOOLS ALREADY CALLED" not in summary:
+            summary += "\n\n" + tool_history
+
+    return summary
+
+
+async def _llm_compact_split(
+    ctx: NodeContext,
+    messages: list,
+    accumulator: OutputAccumulator | None,
+    _depth: int,
+    *,
+    char_limit: int = LLM_COMPACT_CHAR_LIMIT,
+    max_depth: int = LLM_COMPACT_MAX_DEPTH,
+    max_context_tokens: int = 128_000,
+) -> str:
+    """Split messages in half and summarise each half independently."""
+    mid = max(1, len(messages) // 2)
+    s1 = await llm_compact(
+        ctx,
+        messages[:mid],
+        None,
+        _depth + 1,
+        char_limit=char_limit,
+        max_depth=max_depth,
+        max_context_tokens=max_context_tokens,
+    )
+    s2 = await llm_compact(
+        ctx,
+        messages[mid:],
+        accumulator,
+        _depth + 1,
+        char_limit=char_limit,
+        max_depth=max_depth,
+        max_context_tokens=max_context_tokens,
+    )
+    return s1 + "\n\n" + s2
+
+
+# --- Compaction helpers ------------------------------------------------
+
+
+def format_messages_for_summary(messages: list) -> str:
+    """Format messages as text for LLM summarisation."""
+    lines: list[str] = []
+    for m in messages:
+        if m.role == "tool":
+            content = m.content[:500]
+            if len(m.content) > 500:
+                content += "..."
+            lines.append(f"[tool result]: {content}")
+        elif m.role == "assistant" and m.tool_calls:
+            names = [tc.get("function", {}).get("name", "?") for tc in m.tool_calls]
+            text = m.content[:200] if m.content else ""
+            lines.append(f"[assistant (calls: {', '.join(names)})]: {text}")
+        else:
+            lines.append(f"[{m.role}]: {m.content}")
+    return "\n\n".join(lines)
+
+
+def build_llm_compaction_prompt(
+    ctx: NodeContext,
+    accumulator: OutputAccumulator | None,
+    formatted_messages: str,
+    *,
+    max_context_tokens: int = 128_000,
+) -> str:
+    """Build prompt for LLM compaction targeting 50% of token budget."""
+    spec = ctx.node_spec
+    ctx_lines = [f"NODE: {spec.name} (id={spec.id})"]
+    if spec.description:
+        ctx_lines.append(f"PURPOSE: {spec.description}")
+    if spec.success_criteria:
+        ctx_lines.append(f"SUCCESS CRITERIA: {spec.success_criteria}")
+
+    if accumulator:
+        acc = accumulator.to_dict()
+        done = {k: v for k, v in acc.items() if v is not None}
+        todo = [k for k, v in acc.items() if v is None]
+        if done:
+            ctx_lines.append(
+                "OUTPUTS ALREADY SET:\n"
+                + "\n".join(f"  {k}: {str(v)[:150]}" for k, v in done.items())
+            )
+        if todo:
+            ctx_lines.append(f"OUTPUTS STILL NEEDED: {', '.join(todo)}")
+    elif spec.output_keys:
+        ctx_lines.append(f"OUTPUTS STILL NEEDED: {', '.join(spec.output_keys)}")
+
+    target_tokens = max_context_tokens // 2
+    target_chars = target_tokens * 4
+    node_ctx = "\n".join(ctx_lines)
+
+    return (
+        "You are compacting an AI agent's conversation history. "
+        "The agent is still working and needs to continue.\n\n"
+        f"AGENT CONTEXT:\n{node_ctx}\n\n"
+        f"CONVERSATION MESSAGES:\n{formatted_messages}\n\n"
+        "INSTRUCTIONS:\n"
+        f"Write a summary of approximately {target_chars} characters "
+        f"(~{target_tokens} tokens).\n"
+        "1. Preserve ALL user-stated rules, constraints, and preferences "
+        "verbatim.\n"
+        "2. Preserve key decisions made and results obtained.\n"
+        "3. Preserve in-progress work state so the agent can continue.\n"
+        "4. Be detailed enough that the agent can resume without "
+        "re-doing work.\n"
+    )
+
+
+def build_message_inventory(conversation: NodeConversation) -> list[dict[str, Any]]:
+    """Build a per-message size inventory for debug logging."""
+    inventory: list[dict[str, Any]] = []
+    for message in conversation.messages:
+        content_chars = len(message.content)
+        tool_call_args_chars = 0
+        tool_name = None
+        if message.tool_calls:
+            for tool_call in message.tool_calls:
+                args = tool_call.get("function", {}).get("arguments", "")
+                tool_call_args_chars += (
+                    len(args) if isinstance(args, str) else len(json.dumps(args))
+                )
+            names = [
+                tool_call.get("function", {}).get("name", "?") for tool_call in message.tool_calls
+            ]
+            tool_name = ", ".join(names)
+        elif message.role == "tool" and message.tool_use_id:
+            for previous in conversation.messages:
+                if previous.tool_calls:
+                    for tool_call in previous.tool_calls:
+                        if tool_call.get("id") == message.tool_use_id:
+                            tool_name = tool_call.get("function", {}).get("name", "?")
+                            break
+                if tool_name:
+                    break
+        entry: dict[str, Any] = {
+            "seq": message.seq,
+            "role": message.role,
+            "content_chars": content_chars,
+        }
+        if tool_call_args_chars:
+            entry["tool_call_args_chars"] = tool_call_args_chars
+        if tool_name:
+            entry["tool"] = tool_name
+        if message.is_error:
+            entry["is_error"] = True
+        if message.phase_id:
+            entry["phase"] = message.phase_id
+        if content_chars > 2000:
+            entry["preview"] = message.content[:200] + "…"
+        inventory.append(entry)
+    return inventory
+
+
+def write_compaction_debug_log(
+    ctx: NodeContext,
+    before_pct: int,
+    after_pct: int,
+    level: str,
+    inventory: list[dict[str, Any]] | None,
+) -> None:
+    """Write detailed compaction analysis to ~/.hive/compaction_log/."""
+    log_dir = Path.home() / ".hive" / "compaction_log"
+    log_dir.mkdir(parents=True, exist_ok=True)
+
+    ts = datetime.now(UTC).strftime("%Y%m%dT%H%M%S_%f")
+    node_label = ctx.node_id.replace("/", "_")
+    log_path = log_dir / f"{ts}_{node_label}.md"
+
+    lines: list[str] = [
+        f"# Compaction Debug — {ctx.node_id}",
+        f"**Time:** {datetime.now(UTC).isoformat()}",
+        f"**Node:** {ctx.node_spec.name} (`{ctx.node_id}`)",
+    ]
+    if ctx.stream_id:
+        lines.append(f"**Stream:** {ctx.stream_id}")
+    lines.append(f"**Level:** {level}")
+    lines.append(f"**Usage:** {before_pct}% → {after_pct}%")
+    lines.append("")
+
+    if inventory:
+        total_chars = sum(
+            entry.get("content_chars", 0) + entry.get("tool_call_args_chars", 0)
+            for entry in inventory
+        )
+        lines.append(
+            "## Pre-Compaction Message Inventory "
+            f"({len(inventory)} messages, {total_chars:,} total chars)"
+        )
+        lines.append("")
+        ranked = sorted(
+            inventory,
+            key=lambda entry: entry.get("content_chars", 0) + entry.get("tool_call_args_chars", 0),
+            reverse=True,
+        )
+        lines.append("| # | seq | role | tool | chars | % of total | flags |")
+        lines.append("|---|-----|------|------|------:|------------|-------|")
+        for i, entry in enumerate(ranked, 1):
+            chars = entry.get("content_chars", 0) + entry.get("tool_call_args_chars", 0)
+            pct = (chars / total_chars * 100) if total_chars else 0
+            tool = entry.get("tool", "")
+            flags: list[str] = []
+            if entry.get("is_error"):
+                flags.append("error")
+            if entry.get("phase"):
+                flags.append(f"phase={entry['phase']}")
+            lines.append(
+                f"| {i} | {entry['seq']} | {entry['role']} | {tool} "
+                f"| {chars:,} | {pct:.1f}% | {', '.join(flags)} |"
+            )
+
+        large = [entry for entry in ranked if entry.get("preview")]
+        if large:
+            lines.append("")
+            lines.append("### Large message previews")
+            for entry in large:
+                lines.append(
+                    f"\n**seq={entry['seq']}** ({entry['role']}, {entry.get('tool', '')}):"
+                )
+                lines.append(f"```\n{entry['preview']}\n```")
+    lines.append("")
+
+    try:
+        log_path.write_text("\n".join(lines), encoding="utf-8")
+        logger.debug("Compaction debug log written to %s", log_path)
+    except OSError:
+        logger.debug("Failed to write compaction debug log to %s", log_path)
+
+
+async def log_compaction(
+    ctx: NodeContext,
+    conversation: NodeConversation,
+    ratio_before: float,
+    event_bus: EventBus | None,
+    *,
+    pre_inventory: list[dict[str, Any]] | None = None,
+) -> None:
+    """Log compaction result to runtime logger and event bus."""
+    ratio_after = conversation.usage_ratio()
+    before_pct = round(ratio_before * 100)
+    after_pct = round(ratio_after * 100)
+
+    # Determine label from what happened
+    if after_pct >= before_pct - 1:
+        level = "prune_only"
+    elif ratio_after <= 0.6:
+        level = "llm"
+    else:
+        level = "structural"
+
+    logger.info(
+        "Compaction complete (%s): %d%% -> %d%%",
+        level,
+        before_pct,
+        after_pct,
+    )
+
+    if ctx.runtime_logger:
+        ctx.runtime_logger.log_step(
+            node_id=ctx.node_id,
+            node_type="event_loop",
+            step_index=-1,
+            llm_text=f"Context compacted ({level}): {before_pct}% \u2192 {after_pct}%",
+            verdict="COMPACTION",
+            verdict_feedback=f"level={level} before={before_pct}% after={after_pct}%",
+        )
+
+    if event_bus:
+        from framework.runtime.event_bus import AgentEvent, EventType
+
+        event_data: dict[str, Any] = {
+            "level": level,
+            "usage_before": before_pct,
+            "usage_after": after_pct,
+        }
+        if pre_inventory is not None:
+            event_data["message_inventory"] = pre_inventory
+        await event_bus.publish(
+            AgentEvent(
+                type=EventType.CONTEXT_COMPACTED,
+                stream_id=ctx.stream_id or ctx.node_id,
+                node_id=ctx.node_id,
+                data=event_data,
+            )
+        )
+
+    await publish_context_usage(event_bus, ctx, conversation, "post_compaction")
+
+    if os.environ.get("HIVE_COMPACTION_DEBUG"):
+        write_compaction_debug_log(ctx, before_pct, after_pct, level, pre_inventory)
+
+
+def build_emergency_summary(
+    ctx: NodeContext,
+    accumulator: OutputAccumulator | None = None,
+    conversation: NodeConversation | None = None,
+    config: LoopConfig | None = None,
+) -> str:
+    """Build a structured emergency compaction summary.
+
+    Unlike normal/aggressive compaction which uses an LLM summary,
+    emergency compaction cannot afford an LLM call (context is already
+    way over budget).  Instead, build a deterministic summary from the
+    node's known state so the LLM can continue working after
+    compaction without losing track of its task and inputs.
+    """
+    parts = [
+        "EMERGENCY COMPACTION — previous conversation was too large "
+        "and has been replaced with this summary.\n"
+    ]
+
+    # 1. Node identity
+    spec = ctx.node_spec
+    parts.append(f"NODE: {spec.name} (id={spec.id})")
+    if spec.description:
+        parts.append(f"PURPOSE: {spec.description}")
+
+    # 2. Inputs the node received
+    input_lines = []
+    for key in spec.input_keys:
+        value = ctx.input_data.get(key) or ctx.buffer.read(key)
+        if value is not None:
+            # Truncate long values but keep them recognisable
+            v_str = str(value)
+            if len(v_str) > 200:
+                v_str = v_str[:200] + "…"
+            input_lines.append(f"  {key}: {v_str}")
+    if input_lines:
+        parts.append("INPUTS:\n" + "\n".join(input_lines))
+
+    # 3. Output accumulator state (what's been set so far)
+    if accumulator:
+        acc_state = accumulator.to_dict()
+        set_keys = {k: v for k, v in acc_state.items() if v is not None}
+        missing = [k for k, v in acc_state.items() if v is None]
+        if set_keys:
+            lines = [f"  {k}: {str(v)[:150]}" for k, v in set_keys.items()]
+            parts.append("OUTPUTS ALREADY SET:\n" + "\n".join(lines))
+        if missing:
+            parts.append(f"OUTPUTS STILL NEEDED: {', '.join(missing)}")
+    elif spec.output_keys:
+        parts.append(f"OUTPUTS STILL NEEDED: {', '.join(spec.output_keys)}")
+
+    # 4. Available tools reminder
+    if spec.tools:
+        parts.append(f"AVAILABLE TOOLS: {', '.join(spec.tools)}")
+
+    # 5. Spillover files — list actual files so the LLM can load
+    # them immediately instead of having to call list_data_files first.
+    spillover_dir = config.spillover_dir if config else None
+    if spillover_dir:
+        try:
+            from pathlib import Path
+
+            data_dir = Path(spillover_dir)
+            if data_dir.is_dir():
+                all_files = sorted(f.name for f in data_dir.iterdir() if f.is_file())
+                # Separate conversation history files from regular data files
+                conv_files = [f for f in all_files if re.match(r"conversation_\d+\.md$", f)]
+                data_files = [f for f in all_files if f not in conv_files]
+
+                if conv_files:
+                    conv_list = "\n".join(
+                        f"  - {f}  (full path: {data_dir / f})" for f in conv_files
+                    )
+                    parts.append(
+                        "CONVERSATION HISTORY (freeform messages saved during compaction — "
+                        "use load_data('<filename>') to review earlier dialogue):\n" + conv_list
+                    )
+                if data_files:
+                    file_list = "\n".join(
+                        f"  - {f}  (full path: {data_dir / f})" for f in data_files[:30]
+                    )
+                    parts.append("DATA FILES (use load_data('<filename>') to read):\n" + file_list)
+                if not all_files:
+                    parts.append(
+                        "NOTE: Large tool results may have been saved to files. "
+                        "Use list_directory 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."
+            )
+
+    # 6. Tool call history (prevent re-calling tools)
+    if conversation is not None:
+        tool_history = _extract_tool_call_history(conversation)
+        if tool_history:
+            parts.append(tool_history)
+
+    parts.append(
+        "\nContinue working towards setting the remaining outputs. "
+        "Use your tools and the inputs above."
+    )
+    return "\n\n".join(parts)
+
+
+def _extract_tool_call_history(conversation: NodeConversation) -> str:
+    """Extract tool call history from conversation messages.
+
+    This is the instance-level variant that operates on a NodeConversation
+    directly (vs. the module-level extract_tool_call_history in conversation.py
+    which works on raw message lists).
+    """
+    from framework.graph.conversation import extract_tool_call_history
+
+    return extract_tool_call_history(list(conversation.messages))
@@ -0,0 +1,255 @@
+"""Cursor persistence, queue draining, and pause detection.
+
+Handles the checkpoint/resume cycle: restoring state from a previous
+conversation store, writing cursor data, and managing injection/trigger
+queues between iterations.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import Any
+
+from framework.graph.conversation import ConversationStore, NodeConversation
+from framework.graph.event_loop.types import LoopConfig, OutputAccumulator, TriggerEvent
+from framework.graph.node import NodeContext
+from framework.llm.capabilities import supports_image_tool_results
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class RestoredState:
+    """State recovered from a previous checkpoint."""
+
+    conversation: NodeConversation
+    accumulator: OutputAccumulator
+    start_iteration: int
+    recent_responses: list[str]
+    recent_tool_fingerprints: list[list[tuple[str, str]]]
+    pending_input: dict[str, Any] | None
+
+
+async def restore(
+    conversation_store: ConversationStore | None,
+    ctx: NodeContext,
+    config: LoopConfig,
+) -> RestoredState | None:
+    """Attempt to restore from a previous checkpoint.
+
+    Returns a ``RestoredState`` with conversation, accumulator, iteration
+    counter, and stall/doom-loop detection state — everything needed to
+    resume exactly where execution stopped.
+    """
+    if conversation_store is None:
+        return None
+
+    # In isolated mode, filter parts by phase_id so the node only sees
+    # its own messages in the shared flat conversation store.  In
+    # continuous mode (or when _restore is called for timer-resume)
+    # load all parts — the full conversation threads across nodes.
+    _is_continuous = getattr(ctx, "continuous_mode", False)
+    phase_filter = None if _is_continuous else ctx.node_id
+    conversation = await NodeConversation.restore(
+        conversation_store,
+        phase_id=phase_filter,
+        run_id=ctx.effective_run_id,
+    )
+    if conversation is None:
+        return None
+
+    # If run_id filtering removed all messages, this is an intentional
+    # restart (new run), not a crash recovery.  Return None so the caller
+    # falls through to the fresh-conversation path.
+    if conversation.message_count == 0:
+        return None
+
+    accumulator = await OutputAccumulator.restore(conversation_store, run_id=ctx.effective_run_id)
+    accumulator.spillover_dir = config.spillover_dir
+    accumulator.max_value_chars = config.max_output_value_chars
+
+    cursor = await conversation_store.read_cursor() or {}
+    start_iteration = cursor.get("iteration", 0) + 1
+
+    # Restore stall/doom-loop detection state
+    recent_responses: list[str] = cursor.get("recent_responses", [])
+    raw_fps = cursor.get("recent_tool_fingerprints", [])
+    recent_tool_fingerprints: list[list[tuple[str, str]]] = [
+        [tuple(pair) for pair in fps]  # type: ignore[misc]
+        for fps in raw_fps
+    ]
+    pending_input = cursor.get("pending_input")
+    if not isinstance(pending_input, dict):
+        pending_input = None
+
+    logger.info(
+        f"Restored event loop: iteration={start_iteration}, "
+        f"messages={conversation.message_count}, "
+        f"outputs={list(accumulator.values.keys())}, "
+        f"stall_window={len(recent_responses)}, "
+        f"doom_window={len(recent_tool_fingerprints)}"
+    )
+    return RestoredState(
+        conversation=conversation,
+        accumulator=accumulator,
+        start_iteration=start_iteration,
+        recent_responses=recent_responses,
+        recent_tool_fingerprints=recent_tool_fingerprints,
+        pending_input=pending_input,
+    )
+
+
+async def write_cursor(
+    conversation_store: ConversationStore | None,
+    ctx: NodeContext,
+    conversation: NodeConversation,
+    accumulator: OutputAccumulator,
+    iteration: int,
+    *,
+    recent_responses: list[str] | None = None,
+    recent_tool_fingerprints: list[list[tuple[str, str]]] | None = None,
+    pending_input: dict[str, Any] | None = None,
+) -> None:
+    """Write checkpoint cursor for crash recovery.
+
+    Persists iteration counter, accumulator outputs, and stall/doom-loop
+    detection state so that resume picks up exactly where execution stopped.
+    """
+    if conversation_store:
+        cursor = await conversation_store.read_cursor() or {}
+        cursor.update(
+            {
+                "iteration": iteration,
+                "node_id": ctx.node_id,
+                "outputs": accumulator.to_dict(),
+            }
+        )
+        # Persist stall/doom-loop detection state for reliable resume
+        if recent_responses is not None:
+            cursor["recent_responses"] = recent_responses
+        if recent_tool_fingerprints is not None:
+            # Convert list[list[tuple]] → list[list[list]] for JSON
+            cursor["recent_tool_fingerprints"] = [
+                [list(pair) for pair in fps] for fps in recent_tool_fingerprints
+            ]
+        # Persist blocked-input state so restored runs re-block instead of
+        # manufacturing a synthetic continuation turn.
+        cursor["pending_input"] = pending_input
+        await conversation_store.write_cursor(cursor)
+
+
+async def drain_injection_queue(
+    queue: asyncio.Queue,
+    conversation: NodeConversation,
+    *,
+    ctx: NodeContext,
+    describe_images_as_text_fn: (
+        Callable[[list[dict[str, Any]]], Awaitable[str | None]] | None
+    ) = None,
+) -> int:
+    """Drain all pending injected events as user messages. Returns count."""
+    count = 0
+    logger.debug("[drain_injection_queue] Starting to drain queue, initial queue size: %s", queue.qsize() if hasattr(queue, 'qsize') else 'unknown')
+    while not queue.empty():
+        try:
+            content, is_client_input, image_content = queue.get_nowait()
+            logger.info(
+                "[drain] injected message (client_input=%s, images=%d): %s",
+                is_client_input,
+                len(image_content) if image_content else 0,
+                content[:200] if content else "(empty)",
+            )
+            if image_content and ctx.llm and not supports_image_tool_results(ctx.llm.model):
+                logger.info(
+                    "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:
+                        content = f"{content}\n\n{description}" if content else description
+                        logger.info("[drain] image described as text via vision fallback")
+                    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
+            if is_client_input:
+                await conversation.add_user_message(
+                    content,
+                    is_client_input=True,
+                    image_content=image_content,
+                )
+            else:
+                await conversation.add_user_message(f"[External event]: {content}")
+            count += 1
+        except asyncio.QueueEmpty:
+            break
+    return count
+
+
+async def drain_trigger_queue(
+    queue: asyncio.Queue,
+    conversation: NodeConversation,
+) -> int:
+    """Drain all pending trigger events as a single batched user message.
+
+    Multiple triggers are merged so the LLM sees them atomically and can
+    reason about all pending triggers before acting.
+    """
+    triggers: list[TriggerEvent] = []
+    while not queue.empty():
+        try:
+            triggers.append(queue.get_nowait())
+        except asyncio.QueueEmpty:
+            break
+
+    if not triggers:
+        return 0
+
+    parts: list[str] = []
+    for t in triggers:
+        task = t.payload.get("task", "")
+        task_line = f"\nTask: {task}" if task else ""
+        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)
+    logger.info("[drain] %d trigger(s): %s", len(triggers), combined[:200])
+    await conversation.add_user_message(combined)
+    return len(triggers)
+
+
+async def check_pause(
+    ctx: NodeContext,
+    conversation: NodeConversation,
+    iteration: int,
+) -> bool:
+    """
+    Check if pause has been requested. Returns True if paused.
+
+    Note: This check happens BEFORE starting iteration N, after completing N-1.
+    If paused, the node exits having completed {iteration} iterations (0 to iteration-1).
+    """
+    # Check executor-level pause event (for /pause command, Ctrl+Z)
+    if ctx.pause_event and ctx.pause_event.is_set():
+        completed = iteration  # 0-indexed: iteration=3 means 3 iterations completed (0,1,2)
+        logger.info(f"⏸ Pausing after {completed} iteration(s) completed (executor-level)")
+        return True
+
+    # Check context-level pause flags (legacy/alternative methods)
+    pause_requested = ctx.input_data.get("pause_requested", False)
+    if not pause_requested:
+        try:
+            pause_requested = ctx.buffer.read("pause_requested") or False
+        except (PermissionError, KeyError):
+            pause_requested = False
+    if pause_requested:
+        completed = iteration
+        logger.info(f"⏸ Pausing after {completed} iteration(s) completed (context-level)")
+        return True
+
+    return False
@@ -0,0 +1,360 @@
+"""EventBus publishing helpers for the event loop.
+
+Thin wrappers around EventBus.emit_*() calls that check for bus existence
+before publishing.  Extracted to reduce noise in the main orchestrator.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+
+from framework.graph.conversation import NodeConversation
+from framework.graph.event_loop.types import HookContext
+from framework.graph.node import NodeContext
+from framework.runtime.event_bus import EventBus
+
+logger = logging.getLogger(__name__)
+
+
+async def publish_loop_started(
+    event_bus: EventBus | None,
+    stream_id: str,
+    node_id: str,
+    max_iterations: int,
+    execution_id: str = "",
+) -> None:
+    if event_bus:
+        await event_bus.emit_node_loop_started(
+            stream_id=stream_id,
+            node_id=node_id,
+            max_iterations=max_iterations,
+            execution_id=execution_id,
+        )
+
+
+async def generate_action_plan(
+    event_bus: EventBus | None,
+    ctx: NodeContext,
+    stream_id: str,
+    node_id: str,
+    execution_id: str,
+) -> None:
+    """Generate a brief action plan via LLM and emit it as an SSE event.
+
+    Runs as a fire-and-forget task so it never blocks the main loop.
+    """
+    try:
+        system_prompt = ctx.node_spec.system_prompt or ""
+        # Trim to keep the prompt small
+        prompt_summary = system_prompt[:500]
+        if len(system_prompt) > 500:
+            prompt_summary += "..."
+
+        tool_names = [t.name for t in ctx.available_tools]
+        output_keys = ctx.node_spec.output_keys or []
+
+        prompt = (
+            f'You are about to work on a task as node "{node_id}".\n\n'
+            f"System prompt:\n{prompt_summary}\n\n"
+            f"Tools available: {tool_names}\n"
+            f"Required outputs: {output_keys}\n\n"
+            f"Write a brief action plan (2-5 bullet points) describing "
+            f"what you will do to complete this task. Be specific and concise.\n"
+            f"Return ONLY the plan text, no preamble."
+        )
+
+        response = await ctx.llm.acomplete(
+            messages=[{"role": "user", "content": prompt}],
+            max_tokens=1024,
+        )
+
+        plan = response.content.strip()
+        if plan and event_bus:
+            await event_bus.emit_node_action_plan(
+                stream_id=stream_id,
+                node_id=node_id,
+                plan=plan,
+                execution_id=execution_id,
+            )
+    except Exception as e:
+        logger.warning("Action plan generation failed for node '%s': %s", node_id, e)
+
+
+async def publish_iteration(
+    event_bus: EventBus | None,
+    stream_id: str,
+    node_id: str,
+    iteration: int,
+    execution_id: str = "",
+    extra_data: dict | None = None,
+) -> None:
+    if event_bus:
+        await event_bus.emit_node_loop_iteration(
+            stream_id=stream_id,
+            node_id=node_id,
+            iteration=iteration,
+            execution_id=execution_id,
+            extra_data=extra_data,
+        )
+
+
+async def publish_llm_turn_complete(
+    event_bus: EventBus | None,
+    stream_id: str,
+    node_id: str,
+    stop_reason: str,
+    model: str,
+    input_tokens: int,
+    output_tokens: int,
+    cached_tokens: int = 0,
+    execution_id: str = "",
+    iteration: int | None = None,
+) -> None:
+    if event_bus:
+        await event_bus.emit_llm_turn_complete(
+            stream_id=stream_id,
+            node_id=node_id,
+            stop_reason=stop_reason,
+            model=model,
+            input_tokens=input_tokens,
+            output_tokens=output_tokens,
+            cached_tokens=cached_tokens,
+            execution_id=execution_id,
+            iteration=iteration,
+        )
+
+
+def log_skip_judge(
+    ctx: NodeContext,
+    node_id: str,
+    iteration: int,
+    feedback: str,
+    tool_calls: list[dict],
+    llm_text: str,
+    turn_tokens: dict[str, int],
+    iter_start: float,
+) -> None:
+    """Log a CONTINUE step that skips judge evaluation (e.g., waiting for input)."""
+    if ctx.runtime_logger:
+        ctx.runtime_logger.log_step(
+            node_id=node_id,
+            node_type="event_loop",
+            step_index=iteration,
+            verdict="CONTINUE",
+            verdict_feedback=feedback,
+            tool_calls=tool_calls,
+            llm_text=llm_text,
+            input_tokens=turn_tokens.get("input", 0),
+            output_tokens=turn_tokens.get("output", 0),
+            latency_ms=int((time.time() - iter_start) * 1000),
+        )
+
+
+async def publish_loop_completed(
+    event_bus: EventBus | None,
+    stream_id: str,
+    node_id: str,
+    iterations: int,
+    execution_id: str = "",
+) -> None:
+    if event_bus:
+        await event_bus.emit_node_loop_completed(
+            stream_id=stream_id,
+            node_id=node_id,
+            iterations=iterations,
+            execution_id=execution_id,
+        )
+
+
+async def publish_context_usage(
+    event_bus: EventBus | None,
+    ctx: NodeContext,
+    conversation: NodeConversation,
+    trigger: str,
+) -> None:
+    """Emit a CONTEXT_USAGE_UPDATED event with current context window state."""
+    if not event_bus:
+        return
+
+    from framework.runtime.event_bus import AgentEvent, EventType
+
+    estimated = conversation.estimate_tokens()
+    max_tokens = conversation._max_context_tokens
+    ratio = estimated / max_tokens if max_tokens > 0 else 0.0
+    await event_bus.publish(
+        AgentEvent(
+            type=EventType.CONTEXT_USAGE_UPDATED,
+            stream_id=ctx.stream_id or ctx.node_id,
+            node_id=ctx.node_id,
+            data={
+                "usage_ratio": round(ratio, 4),
+                "usage_pct": round(ratio * 100),
+                "message_count": conversation.message_count,
+                "estimated_tokens": estimated,
+                "max_context_tokens": max_tokens,
+                "trigger": trigger,
+            },
+        )
+    )
+
+
+async def publish_stalled(
+    event_bus: EventBus | None,
+    stream_id: str,
+    node_id: str,
+    execution_id: str = "",
+) -> None:
+    if event_bus:
+        await event_bus.emit_node_stalled(
+            stream_id=stream_id,
+            node_id=node_id,
+            reason="Consecutive similar responses detected",
+            execution_id=execution_id,
+        )
+
+
+async def publish_text_delta(
+    event_bus: EventBus | None,
+    stream_id: str,
+    node_id: str,
+    content: str,
+    snapshot: str,
+    ctx: NodeContext,
+    execution_id: str = "",
+    iteration: int | None = None,
+    inner_turn: int = 0,
+) -> None:
+    if event_bus:
+        if ctx.emits_client_io:
+            await event_bus.emit_client_output_delta(
+                stream_id=stream_id,
+                node_id=node_id,
+                content=content,
+                snapshot=snapshot,
+                execution_id=execution_id,
+                iteration=iteration,
+                inner_turn=inner_turn,
+            )
+        else:
+            await event_bus.emit_llm_text_delta(
+                stream_id=stream_id,
+                node_id=node_id,
+                content=content,
+                snapshot=snapshot,
+                execution_id=execution_id,
+                inner_turn=inner_turn,
+            )
+
+
+async def publish_tool_started(
+    event_bus: EventBus | None,
+    stream_id: str,
+    node_id: str,
+    tool_use_id: str,
+    tool_name: str,
+    tool_input: dict,
+    execution_id: str = "",
+) -> None:
+    if event_bus:
+        await event_bus.emit_tool_call_started(
+            stream_id=stream_id,
+            node_id=node_id,
+            tool_use_id=tool_use_id,
+            tool_name=tool_name,
+            tool_input=tool_input,
+            execution_id=execution_id,
+        )
+
+
+async def publish_tool_completed(
+    event_bus: EventBus | None,
+    stream_id: str,
+    node_id: str,
+    tool_use_id: str,
+    tool_name: str,
+    result: str,
+    is_error: bool,
+    execution_id: str = "",
+) -> None:
+    if event_bus:
+        await event_bus.emit_tool_call_completed(
+            stream_id=stream_id,
+            node_id=node_id,
+            tool_use_id=tool_use_id,
+            tool_name=tool_name,
+            result=result,
+            is_error=is_error,
+            execution_id=execution_id,
+        )
+
+
+async def publish_judge_verdict(
+    event_bus: EventBus | None,
+    stream_id: str,
+    node_id: str,
+    action: str,
+    feedback: str = "",
+    judge_type: str = "implicit",
+    iteration: int = 0,
+    execution_id: str = "",
+) -> None:
+    if event_bus:
+        await event_bus.emit_judge_verdict(
+            stream_id=stream_id,
+            node_id=node_id,
+            action=action,
+            feedback=feedback,
+            judge_type=judge_type,
+            iteration=iteration,
+            execution_id=execution_id,
+        )
+
+
+async def publish_output_key_set(
+    event_bus: EventBus | None,
+    stream_id: str,
+    node_id: str,
+    key: str,
+    execution_id: str = "",
+) -> None:
+    if event_bus:
+        await event_bus.emit_output_key_set(
+            stream_id=stream_id, node_id=node_id, key=key, execution_id=execution_id
+        )
+
+
+async def run_hooks(
+    hooks_config: dict[str, list],
+    event: str,
+    conversation: NodeConversation,
+    trigger: str | None = None,
+) -> None:
+    """Run all registered hooks for *event*, applying their results.
+
+    Each hook receives a HookContext and may return a HookResult that:
+    - replaces the system prompt (result.system_prompt)
+    - injects an extra user message (result.inject)
+    Hooks run in registration order; each sees the prompt as left by the
+    previous hook.
+    """
+    hook_list = hooks_config.get(event, [])
+    if not hook_list:
+        return
+    for hook in hook_list:
+        ctx = HookContext(
+            event=event,
+            trigger=trigger,
+            system_prompt=conversation.system_prompt,
+        )
+        try:
+            result = await hook(ctx)
+        except Exception:
+            logger.warning("Hook '%s' raised an exception", event, exc_info=True)
+            continue
+        if result is None:
+            continue
+        if result.system_prompt:
+            conversation.update_system_prompt(result.system_prompt)
+        if result.inject:
+            await conversation.add_user_message(result.inject)
@@ -0,0 +1,175 @@
+"""Judge evaluation pipeline for the event loop."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+
+from framework.graph.conversation import NodeConversation
+from framework.graph.event_loop.types import JudgeProtocol, JudgeVerdict, OutputAccumulator
+from framework.graph.node import NodeContext
+
+logger = logging.getLogger(__name__)
+
+
+class SubagentJudge:
+    """Judge for subagent execution."""
+
+    def __init__(self, task: str, max_iterations: int = 10):
+        self._task = task
+        self._max_iterations = max_iterations
+
+    async def evaluate(self, context: dict[str, object]) -> JudgeVerdict:
+        missing = context.get("missing_keys", [])
+        if not isinstance(missing, list) or not missing:
+            return JudgeVerdict(action="ACCEPT", feedback="")
+
+        iteration = context.get("iteration", 0)
+        if not isinstance(iteration, int):
+            iteration = 0
+        remaining = self._max_iterations - iteration - 1
+
+        if remaining <= 3:
+            urgency = (
+                f"URGENT: Only {remaining} iterations left. "
+                f"Stop all other work and call set_output NOW for: {missing}"
+            )
+        elif remaining <= self._max_iterations // 2:
+            urgency = (
+                f"WARNING: {remaining} iterations remaining. "
+                f"You must call set_output for: {missing}"
+            )
+        else:
+            urgency = f"Missing output keys: {missing}. Use set_output to provide them."
+
+        return JudgeVerdict(action="RETRY", feedback=f"Your task: {self._task}\n{urgency}")
+
+
+async def judge_turn(
+    *,
+    mark_complete_flag: bool,
+    judge: JudgeProtocol | None,
+    ctx: NodeContext,
+    conversation: NodeConversation,
+    accumulator: OutputAccumulator,
+    assistant_text: str,
+    tool_results: list[dict[str, object]],
+    iteration: int,
+    get_missing_output_keys_fn: Callable[
+        [OutputAccumulator, list[str] | None, list[str] | None],
+        list[str],
+    ],
+    max_context_tokens: int,
+) -> JudgeVerdict:
+    """Evaluate the current state using judge or implicit logic.
+
+    Evaluation levels (in order):
+      0. Short-circuits: mark_complete, skip_judge, tool-continue.
+      1. Custom judge (JudgeProtocol) — full authority when set.
+      2. Implicit judge — output-key check + optional conversation-aware
+         quality gate (when ``success_criteria`` is defined).
+
+    Returns a JudgeVerdict.  ``feedback=None`` means no real evaluation
+    happened (skip_judge, tool-continue); the caller must not inject a
+    feedback message.  Any non-None feedback (including ``""``) means a
+    real evaluation occurred and will be logged into the conversation.
+    """
+    # --- Level 0: short-circuits (no evaluation) -----------------------
+
+    if mark_complete_flag:
+        return JudgeVerdict(action="ACCEPT")
+
+    if ctx.node_spec.skip_judge:
+        return JudgeVerdict(action="RETRY")  # feedback=None → not logged
+
+    # --- Level 1: custom judge -----------------------------------------
+
+    if judge is not None:
+        context = {
+            "assistant_text": assistant_text,
+            "tool_calls": tool_results,
+            "output_accumulator": accumulator.to_dict(),
+            "accumulator": accumulator,
+            "iteration": iteration,
+            "conversation_summary": conversation.export_summary(),
+            "output_keys": ctx.node_spec.output_keys,
+            "missing_keys": get_missing_output_keys_fn(
+                accumulator, ctx.node_spec.output_keys, ctx.node_spec.nullable_output_keys
+            ),
+        }
+        verdict = await judge.evaluate(context)
+        # Ensure evaluated RETRY always carries feedback for logging.
+        if verdict.action == "RETRY" and not verdict.feedback:
+            return JudgeVerdict(action="RETRY", feedback="Custom judge returned RETRY.")
+        return verdict
+
+    # --- Level 2: implicit judge ---------------------------------------
+
+    # Real tool calls were made — let the agent keep working.
+    if tool_results:
+        return JudgeVerdict(action="RETRY")  # feedback=None → not logged
+
+    missing = get_missing_output_keys_fn(
+        accumulator, ctx.node_spec.output_keys, ctx.node_spec.nullable_output_keys
+    )
+
+    if missing:
+        return JudgeVerdict(
+            action="RETRY",
+            feedback=(
+                f"Task incomplete. Required outputs not yet produced: {missing}. "
+                f"Follow your system prompt instructions to complete the work."
+            ),
+        )
+
+    # All output keys present — run safety checks before accepting.
+
+    output_keys = ctx.node_spec.output_keys or []
+    nullable_keys = set(ctx.node_spec.nullable_output_keys or [])
+
+    # All-nullable with nothing set → node produced nothing useful.
+    all_nullable = output_keys and nullable_keys >= set(output_keys)
+    none_set = not any(accumulator.get(k) is not None for k in output_keys)
+    if all_nullable and none_set:
+        return JudgeVerdict(
+            action="RETRY",
+            feedback=(
+                f"No output keys have been set yet. "
+                f"Use set_output to set at least one of: {output_keys}"
+            ),
+        )
+
+    # Queen with no output keys → continuous interaction node.
+    # Inject tool-use pressure instead of auto-accepting.
+    if not output_keys and ctx.supports_direct_user_io:
+        return JudgeVerdict(
+            action="RETRY",
+            feedback=(
+                "STOP describing what you will do. "
+                "You have FULL access to all tools — file creation, "
+                "shell commands, MCP tools — and you CAN call them "
+                "directly in your response. Respond ONLY with tool "
+                "calls, no prose. Execute the task now."
+            ),
+        )
+
+    # Level 2b: conversation-aware quality check (if success_criteria set)
+    if ctx.node_spec.success_criteria and ctx.llm:
+        from framework.graph.conversation_judge import evaluate_phase_completion
+
+        verdict = await evaluate_phase_completion(
+            llm=ctx.llm,
+            conversation=conversation,
+            phase_name=ctx.node_spec.name,
+            phase_description=ctx.node_spec.description,
+            success_criteria=ctx.node_spec.success_criteria,
+            accumulator_state=accumulator.to_dict(),
+            max_context_tokens=max_context_tokens,
+        )
+        if verdict.action != "ACCEPT":
+            return JudgeVerdict(
+                action=verdict.action,
+                feedback=verdict.feedback or "Phase criteria not met.",
+            )
+
+    return JudgeVerdict(action="ACCEPT", feedback="")
@@ -0,0 +1,106 @@
+"""Stall and doom-loop detection for the event loop.
+
+Pure functions with no class dependencies — safe to call from any context.
+"""
+
+from __future__ import annotations
+
+import json
+
+
+def ngram_similarity(s1: str, s2: str, n: int = 2) -> float:
+    """Jaccard similarity of n-gram sets.
+
+    Returns 0.0-1.0, where 1.0 is exact match.
+    Fast: O(len(s) + len(s2)) using set operations.
+    """
+
+    def _ngrams(s: str) -> set[str]:
+        return {s[i : i + n] for i in range(len(s) - n + 1) if s.strip()}
+
+    if not s1 or not s2:
+        return 0.0
+
+    ngrams1, ngrams2 = _ngrams(s1.lower()), _ngrams(s2.lower())
+    if not ngrams1 or not ngrams2:
+        return 0.0
+
+    intersection = len(ngrams1 & ngrams2)
+    union = len(ngrams1 | ngrams2)
+    return intersection / union if union else 0.0
+
+
+def is_stalled(
+    recent_responses: list[str],
+    threshold: int,
+    similarity_threshold: float,
+) -> bool:
+    """Detect stall using n-gram similarity.
+
+    Detects when ALL N consecutive responses are mutually similar
+    (>= threshold).  A single dissimilar response resets the signal.
+    This catches phrases like "I'm still stuck" vs "I'm stuck"
+    without false-positives on "attempt 1" vs "attempt 2".
+    """
+    if len(recent_responses) < threshold:
+        return False
+    if not recent_responses[0]:
+        return False
+
+    # Every consecutive pair must be similar
+    for i in range(1, len(recent_responses)):
+        if ngram_similarity(recent_responses[i], recent_responses[i - 1]) < similarity_threshold:
+            return False
+    return True
+
+
+def fingerprint_tool_calls(
+    tool_results: list[dict],
+) -> list[tuple[str, str]]:
+    """Create deterministic fingerprints for a turn's tool calls.
+
+    Each fingerprint is (tool_name, canonical_args_json).  Order-sensitive
+    so [search("a"), fetch("b")] != [fetch("b"), search("a")].
+    """
+    fingerprints = []
+    for tr in tool_results:
+        name = tr.get("tool_name", "")
+        args = tr.get("tool_input", {})
+        try:
+            canonical = json.dumps(args, sort_keys=True, default=str)
+        except (TypeError, ValueError):
+            canonical = str(args)
+        fingerprints.append((name, canonical))
+    return fingerprints
+
+
+def is_tool_doom_loop(
+    recent_tool_fingerprints: list[list[tuple[str, str]]],
+    threshold: int,
+    enabled: bool = True,
+) -> tuple[bool, str]:
+    """Detect doom loop via exact fingerprint match.
+
+    Detects when N consecutive turns invoke the same tools with
+    identical (canonicalized) arguments.  Different arguments mean
+    different work, so only exact matches count.
+
+    Returns (is_doom_loop, description).
+    """
+    if not enabled:
+        return False, ""
+    if len(recent_tool_fingerprints) < threshold:
+        return False, ""
+    first = recent_tool_fingerprints[0]
+    if not first:
+        return False, ""
+
+    # All turns in the window must match the first exactly
+    if all(fp == first for fp in recent_tool_fingerprints[1:]):
+        tool_names = [name for name, _ in first]
+        desc = (
+            f"Doom loop detected: {len(recent_tool_fingerprints)} "
+            f"identical consecutive tool calls ({', '.join(tool_names)})"
+        )
+        return True, desc
+    return False, ""
@@ -0,0 +1,378 @@
+"""Subagent execution for the event loop.
+
+Handles the full subagent lifecycle: validation, context setup, tool filtering,
+conversation store derivation, execution, and cleanup.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import time
+from collections.abc import Awaitable, Callable
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from framework.graph.conversation import ConversationStore
+from framework.graph.event_loop.judge_pipeline import SubagentJudge
+from framework.graph.event_loop.types import LoopConfig, OutputAccumulator
+from framework.graph.node import DataBuffer, NodeContext
+from framework.llm.provider import ToolResult, ToolUse
+from framework.runtime.event_bus import EventBus
+
+if TYPE_CHECKING:
+    from framework.graph.event_loop_node import EventLoopNode
+
+logger = logging.getLogger(__name__)
+
+
+async def execute_subagent(
+    ctx: NodeContext,
+    agent_id: str,
+    task: str,
+    *,
+    config: LoopConfig,
+    event_loop_node_cls: type[EventLoopNode],
+    escalation_receiver_cls: Callable[[], Any],
+    accumulator: OutputAccumulator | None = None,
+    event_bus: EventBus | None = None,
+    tool_executor: Callable[[ToolUse], ToolResult | Awaitable[ToolResult]] | None = None,
+    conversation_store: ConversationStore | None = None,
+    subagent_instance_counter: dict[str, int] | None = None,
+) -> ToolResult:
+    """Execute a subagent and return the result as a ToolResult.
+
+    The subagent:
+    - Gets a fresh conversation with just the task
+    - Has read-only access to the parent's readable memory
+    - Cannot delegate to its own subagents (prevents recursion)
+    - Returns its output in structured JSON format
+
+    Args:
+        ctx: Parent node's context (for memory, tools, LLM access).
+        agent_id: The node ID of the subagent to invoke.
+        task: The task description to give the subagent.
+        accumulator: Parent's OutputAccumulator.
+        event_bus: EventBus for lifecycle events.
+        config: LoopConfig for iteration/tool limits.
+        tool_executor: Tool executor callable.
+        conversation_store: Parent conversation store (for deriving subagent store).
+        subagent_instance_counter: Mutable counter dict for unique subagent paths.
+
+    Returns:
+        ToolResult with structured JSON output.
+    """
+    # Log subagent invocation start
+    logger.info(
+        "\n" + "=" * 60 + "\n"
+        "🤖 SUBAGENT INVOCATION\n"
+        "=" * 60 + "\n"
+        "Parent Node: %s\n"
+        "Subagent ID: %s\n"
+        "Task: %s\n" + "=" * 60,
+        ctx.node_id,
+        agent_id,
+        task[:500] + "..." if len(task) > 500 else task,
+    )
+
+    # 1. Validate agent exists in registry
+    if agent_id not in ctx.node_registry:
+        return ToolResult(
+            tool_use_id="",
+            content=json.dumps(
+                {
+                    "message": f"Sub-agent '{agent_id}' not found in registry",
+                    "data": None,
+                    "metadata": {"agent_id": agent_id, "success": False, "error": "not_found"},
+                }
+            ),
+            is_error=True,
+        )
+
+    subagent_spec = ctx.node_registry[agent_id]
+
+    # 2. Create read-only memory snapshot
+    parent_data = ctx.buffer.read_all()
+
+    # Merge in-flight outputs from the parent's accumulator.
+    if accumulator:
+        for key, value in accumulator.to_dict().items():
+            if key not in parent_data:
+                parent_data[key] = value
+
+    subagent_buffer = DataBuffer()
+    for key, value in parent_data.items():
+        subagent_buffer.write(key, value, validate=False)
+
+    read_keys = set(parent_data.keys()) | set(subagent_spec.input_keys or [])
+    scoped_buffer = subagent_buffer.with_permissions(
+        read_keys=list(read_keys),
+        write_keys=[],  # Read-only!
+    )
+
+    # 2b. Compute instance counter early so the callback and child context
+    # share the same stable node_id for this subagent invocation.
+    if subagent_instance_counter is not None:
+        subagent_instance_counter.setdefault(agent_id, 0)
+        subagent_instance_counter[agent_id] += 1
+        subagent_instance = str(subagent_instance_counter[agent_id])
+    else:
+        subagent_instance = "1"
+
+    if subagent_instance == "1":
+        sa_node_id = f"{ctx.node_id}:subagent:{agent_id}"
+    else:
+        sa_node_id = f"{ctx.node_id}:subagent:{agent_id}:{subagent_instance}"
+
+    # 2c. Set up report callback (one-way channel to parent / event bus)
+    subagent_reports: list[dict] = []
+
+    async def _report_callback(
+        message: str,
+        data: dict | None = None,
+        *,
+        wait_for_response: bool = False,
+    ) -> str | None:
+        subagent_reports.append({"message": message, "data": data, "timestamp": time.time()})
+        if event_bus:
+            await event_bus.emit_subagent_report(
+                stream_id=ctx.node_id,
+                node_id=sa_node_id,
+                subagent_id=agent_id,
+                message=message,
+                data=data,
+                execution_id=ctx.execution_id,
+            )
+
+        if not wait_for_response:
+            return None
+
+        if not event_bus:
+            logger.warning(
+                "Subagent '%s' requested user response but no event_bus available",
+                agent_id,
+            )
+            return None
+
+        # Create isolated receiver and register for input routing
+        import uuid
+
+        escalation_id = f"{ctx.node_id}:escalation:{uuid.uuid4().hex[:8]}"
+        receiver = escalation_receiver_cls()
+        registry = ctx.shared_node_registry
+
+        registry[escalation_id] = receiver
+        try:
+            await event_bus.emit_escalation_requested(
+                stream_id=ctx.stream_id or ctx.node_id,
+                node_id=escalation_id,
+                reason=f"Subagent report (wait_for_response) from {agent_id}",
+                context=message,
+                execution_id=ctx.execution_id,
+            )
+            # Block until queen responds
+            return await receiver.wait()
+        finally:
+            registry.pop(escalation_id, None)
+
+    # 3. Filter tools for subagent
+    subagent_tool_names = set(subagent_spec.tools or [])
+    tool_source = ctx.all_tools if ctx.all_tools else ctx.available_tools
+
+    # GCU auto-population
+    if subagent_spec.node_type == "gcu" and not subagent_tool_names:
+        subagent_tools = [t for t in tool_source if t.name != "delegate_to_sub_agent"]
+    else:
+        subagent_tools = [
+            t
+            for t in tool_source
+            if t.name in subagent_tool_names and t.name != "delegate_to_sub_agent"
+        ]
+
+    missing = subagent_tool_names - {t.name for t in subagent_tools}
+    if missing:
+        logger.warning(
+            "Subagent '%s' requested tools not found in catalog: %s",
+            agent_id,
+            sorted(missing),
+        )
+
+    logger.info(
+        "📦 Subagent '%s' configuration:\n"
+        "   - System prompt: %s\n"
+        "   - Tools available (%d): %s\n"
+        "   - Memory keys inherited: %s",
+        agent_id,
+        (subagent_spec.system_prompt[:200] + "...")
+        if subagent_spec.system_prompt and len(subagent_spec.system_prompt) > 200
+        else subagent_spec.system_prompt,
+        len(subagent_tools),
+        [t.name for t in subagent_tools],
+        list(parent_data.keys()),
+    )
+
+    # 4. Build subagent context
+    max_iter = min(config.max_iterations, 10)
+    subagent_ctx = NodeContext(
+        runtime=ctx.runtime,
+        node_id=sa_node_id,
+        node_spec=subagent_spec,
+        buffer=scoped_buffer,
+        input_data={"task": task, **parent_data},
+        llm=ctx.llm,
+        available_tools=subagent_tools,
+        goal_context=(
+            f"Your specific task: {task}\n\n"
+            f"COMPLETION REQUIREMENTS:\n"
+            f"When your task is done, you MUST call set_output() "
+            f"for each required key: {subagent_spec.output_keys}\n"
+            f"Alternatively, call report_to_parent(mark_complete=true) "
+            f"with your findings in message/data.\n"
+            f"You have a maximum of {max_iter} turns to complete this task."
+        ),
+        goal=ctx.goal,
+        max_tokens=ctx.max_tokens,
+        runtime_logger=ctx.runtime_logger,
+        is_subagent_mode=True,  # Prevents nested delegation
+        report_callback=_report_callback,
+        node_registry={},  # Empty - no nested subagents
+        shared_node_registry=ctx.shared_node_registry,  # For escalation routing
+    )
+
+    # 5. Create and execute subagent EventLoopNode
+    subagent_conv_store = None
+    if conversation_store is not None:
+        from framework.storage.conversation_store import FileConversationStore
+
+        parent_base = getattr(conversation_store, "_base", None)
+        if parent_base is not None:
+            conversations_dir = parent_base.parent
+            subagent_dir_name = f"{agent_id}-{subagent_instance}"
+            subagent_store_path = conversations_dir / subagent_dir_name
+            subagent_conv_store = FileConversationStore(base_path=subagent_store_path)
+
+    # Derive a subagent-scoped spillover dir
+    subagent_spillover = None
+    if config.spillover_dir:
+        subagent_spillover = str(Path(config.spillover_dir) / agent_id / subagent_instance)
+
+    subagent_node = event_loop_node_cls(
+        event_bus=event_bus,
+        judge=SubagentJudge(task=task, max_iterations=max_iter),
+        config=LoopConfig(
+            max_iterations=max_iter,
+            max_tool_calls_per_turn=config.max_tool_calls_per_turn,
+            tool_call_overflow_margin=config.tool_call_overflow_margin,
+            max_context_tokens=config.max_context_tokens,
+            stall_detection_threshold=config.stall_detection_threshold,
+            max_tool_result_chars=config.max_tool_result_chars,
+            spillover_dir=subagent_spillover,
+        ),
+        tool_executor=tool_executor,
+        conversation_store=subagent_conv_store,
+    )
+
+    # Inject a unique GCU browser profile for this subagent
+    _profile_token = None
+    try:
+        from gcu.browser.session import set_active_profile as _set_gcu_profile
+
+        _profile_token = _set_gcu_profile(f"{agent_id}-{subagent_instance}")
+    except ImportError:
+        pass  # GCU tools not installed; no-op
+
+    try:
+        logger.info("🚀 Starting subagent '%s' execution...", agent_id)
+        start_time = time.time()
+        result = await subagent_node.execute(subagent_ctx)
+        latency_ms = int((time.time() - start_time) * 1000)
+
+        separator = "-" * 60
+        logger.info(
+            "\n%s\n"
+            "✅ SUBAGENT '%s' COMPLETED\n"
+            "%s\n"
+            "Success: %s\n"
+            "Latency: %dms\n"
+            "Tokens used: %s\n"
+            "Output keys: %s\n"
+            "%s",
+            separator,
+            agent_id,
+            separator,
+            result.success,
+            latency_ms,
+            result.tokens_used,
+            list(result.output.keys()) if result.output else [],
+            separator,
+        )
+
+        result_json = {
+            "message": (
+                f"Sub-agent '{agent_id}' completed successfully"
+                if result.success
+                else f"Sub-agent '{agent_id}' failed: {result.error}"
+            ),
+            "data": result.output,
+            "reports": subagent_reports if subagent_reports else None,
+            "metadata": {
+                "agent_id": agent_id,
+                "success": result.success,
+                "tokens_used": result.tokens_used,
+                "latency_ms": latency_ms,
+                "report_count": len(subagent_reports),
+            },
+        }
+
+        return ToolResult(
+            tool_use_id="",
+            content=json.dumps(result_json, indent=2, default=str),
+            is_error=not result.success,
+        )
+
+    except Exception as e:
+        logger.exception(
+            "\n" + "!" * 60 + "\n❌ SUBAGENT '%s' FAILED\nError: %s\n" + "!" * 60,
+            agent_id,
+            str(e),
+        )
+        result_json = {
+            "message": f"Sub-agent '{agent_id}' raised exception: {e}",
+            "data": None,
+            "metadata": {
+                "agent_id": agent_id,
+                "success": False,
+                "error": str(e),
+            },
+        }
+        return ToolResult(
+            tool_use_id="",
+            content=json.dumps(result_json, indent=2),
+            is_error=True,
+        )
+    finally:
+        # Restore the GCU profile context
+        if _profile_token is not None:
+            from gcu.browser.session import _active_profile as _gcu_profile_var
+
+            _gcu_profile_var.reset(_profile_token)
+
+            # Stop the browser session for this subagent's profile
+            if tool_executor is not None:
+                _subagent_profile = f"{agent_id}-{subagent_instance}"
+                try:
+                    _stop_use = ToolUse(
+                        id="gcu-cleanup",
+                        name="browser_stop",
+                        input={"profile": _subagent_profile},
+                    )
+                    _stop_result = tool_executor(_stop_use)
+                    if asyncio.iscoroutine(_stop_result) or asyncio.isfuture(_stop_result):
+                        await _stop_result
+                except Exception as _gcu_exc:
+                    logger.warning(
+                        "GCU browser_stop failed for profile %r: %s",
+                        _subagent_profile,
+                        _gcu_exc,
+                    )
@@ -0,0 +1,369 @@
+"""Synthetic tool builders for the event loop.
+
+Factory functions that create ``Tool`` definitions for framework-level
+synthetic tools (set_output, ask_user, escalate, delegate, report_to_parent).
+Also includes the ``handle_set_output`` validation logic.
+
+All functions are pure — they receive explicit parameters and return
+``Tool`` or ``ToolResult`` objects with no side effects.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from framework.llm.provider import Tool, ToolResult
+
+
+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.
+    """
+    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. "
+            "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'). "
+            '{"question": "What would you like to do?", "options": '
+            '["Build a new agent", "Modify existing agent", "Run tests"]} '
+            "Free-form example: "
+            '{"question": "Describe the agent you want to build."}'
+        ),
+        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?"}'
+            "]}"
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "questions": {
+                    "type": "array",
+                    "items": {
+                        "type": "object",
+                        "properties": {
+                            "id": {
+                                "type": "string",
+                                "description": (
+                                    "Short identifier for this question (used in the response)."
+                                ),
+                            },
+                            "prompt": {
+                                "type": "string",
+                                "description": "The question text shown to the user.",
+                            },
+                            "options": {
+                                "type": "array",
+                                "items": {"type": "string"},
+                                "description": (
+                                    "2-3 predefined choices. The UI appends an "
+                                    "'Other' free-text input automatically. "
+                                    "Omit only when the user must type a free-form answer."
+                                ),
+                                "minItems": 2,
+                                "maxItems": 3,
+                            },
+                        },
+                        "required": ["id", "prompt"],
+                    },
+                    "minItems": 2,
+                    "maxItems": 8,
+                    "description": "List of questions to present to the user.",
+                },
+            },
+            "required": ["questions"],
+        },
+    )
+
+
+def build_set_output_tool(output_keys: list[str] | None) -> Tool | None:
+    """Build the synthetic set_output tool for explicit output declaration."""
+    if not output_keys:
+        return None
+    return Tool(
+        name="set_output",
+        description=(
+            "Set an output value for this node. Call once per output key. "
+            "Use this for brief notes, counts, status, and file references — "
+            "NOT for large data payloads. When a tool result was saved to a "
+            "data file, pass the filename as the value "
+            "(e.g. 'google_sheets_get_values_1.txt') so the next phase can "
+            "load the full data. Values exceeding ~2000 characters are "
+            "auto-saved to data files. "
+            f"Valid keys: {output_keys}"
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "key": {
+                    "type": "string",
+                    "description": f"Output key. Must be one of: {output_keys}",
+                    "enum": output_keys,
+                },
+                "value": {
+                    "type": "string",
+                    "description": (
+                        "The output value — a brief note, count, status, "
+                        "or data filename reference."
+                    ),
+                },
+            },
+            "required": ["key", "value"],
+        },
+    )
+
+
+def build_escalate_tool() -> Tool:
+    """Build the synthetic escalate tool for worker -> queen handoff."""
+    return Tool(
+        name="escalate",
+        description=(
+            "Escalate to the queen when requesting user input, "
+            "blocked by errors, missing "
+            "credentials, or ambiguous constraints that require supervisor "
+            "guidance. Include a concise reason and optional context. "
+            "The node will pause until the queen injects guidance."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "reason": {
+                    "type": "string",
+                    "description": (
+                        "Short reason for escalation (e.g. 'Tool repeatedly failing')."
+                    ),
+                },
+                "context": {
+                    "type": "string",
+                    "description": "Optional diagnostic details for the queen.",
+                },
+            },
+            "required": ["reason"],
+        },
+    )
+
+
+def build_delegate_tool(sub_agents: list[str], node_registry: dict[str, Any]) -> Tool | None:
+    """Build the synthetic delegate_to_sub_agent tool for subagent invocation.
+
+    Args:
+        sub_agents: List of node IDs that can be invoked as subagents.
+        node_registry: Map of node_id -> NodeSpec for looking up subagent descriptions.
+
+    Returns:
+        Tool definition if sub_agents is non-empty, None otherwise.
+    """
+    if not sub_agents:
+        return None
+
+    agent_descriptions = []
+    for agent_id in sub_agents:
+        spec = node_registry.get(agent_id)
+        if spec:
+            desc = getattr(spec, "description", "(no description)")
+            agent_descriptions.append(f"- {agent_id}: {desc}")
+        else:
+            agent_descriptions.append(f"- {agent_id}: (not found in registry)")
+
+    return Tool(
+        name="delegate_to_sub_agent",
+        description=(
+            "Delegate a task to a specialized sub-agent. The sub-agent runs "
+            "autonomously with read-only access to current memory and returns "
+            "its result. Use this to parallelize work or leverage specialized capabilities.\n\n"
+            "Available sub-agents:\n" + "\n".join(agent_descriptions)
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "agent_id": {
+                    "type": "string",
+                    "description": f"The sub-agent to invoke. Must be one of: {sub_agents}",
+                    "enum": sub_agents,
+                },
+                "task": {
+                    "type": "string",
+                    "description": (
+                        "The task description for the sub-agent to execute. "
+                        "Be specific about what you want the sub-agent to do and "
+                        "what information to return."
+                    ),
+                },
+            },
+            "required": ["agent_id", "task"],
+        },
+    )
+
+
+def build_report_to_parent_tool() -> Tool:
+    """Build the synthetic report_to_parent tool for sub-agent progress reports.
+
+    Sub-agents call this to send one-way progress updates, partial findings,
+    or status reports to the parent node (and external observers via event bus)
+    without blocking execution.
+
+    When ``wait_for_response`` is True, the sub-agent blocks until the parent
+    relays the user's response — used for escalation (e.g. login pages, CAPTCHAs).
+
+    When ``mark_complete`` is True, the sub-agent terminates immediately after
+    sending the report — no need to call set_output for each output key.
+    """
+    return Tool(
+        name="report_to_parent",
+        description=(
+            "Send a report to the parent agent. By default this is fire-and-forget: "
+            "the parent receives the report but does not respond. "
+            "Set wait_for_response=true to BLOCK until the user replies — use this "
+            "when you need human intervention (e.g. login pages, CAPTCHAs, "
+            "authentication walls). The user's response is returned as the tool result. "
+            "Set mark_complete=true to finish your task and terminate immediately "
+            "after sending the report — use this when your findings are in the "
+            "message/data fields and you don't need to call set_output."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "message": {
+                    "type": "string",
+                    "description": "A human-readable status or progress message.",
+                },
+                "data": {
+                    "type": "object",
+                    "description": "Optional structured data to include with the report.",
+                },
+                "wait_for_response": {
+                    "type": "boolean",
+                    "description": (
+                        "If true, block execution until the user responds. "
+                        "Use for escalation scenarios requiring human intervention."
+                    ),
+                    "default": False,
+                },
+                "mark_complete": {
+                    "type": "boolean",
+                    "description": (
+                        "If true, terminate the sub-agent immediately after sending "
+                        "this report. The report message and data are delivered to the "
+                        "parent as the final result. No set_output calls are needed."
+                    ),
+                    "default": False,
+                },
+            },
+            "required": ["message"],
+        },
+    )
+
+
+def handle_set_output(
+    tool_input: dict[str, Any],
+    output_keys: list[str] | None,
+) -> ToolResult:
+    """Handle set_output tool call. Returns ToolResult (sync)."""
+    import logging
+    import re
+
+    logger = logging.getLogger(__name__)
+
+    key = tool_input.get("key", "")
+    value = tool_input.get("value", "")
+    valid_keys = output_keys or []
+
+    # Recover from truncated JSON (max_tokens hit mid-argument).
+    # The _raw key is set by litellm when json.loads fails.
+    if not key and "_raw" in tool_input:
+        raw = tool_input["_raw"]
+        key_match = re.search(r'"key"\s*:\s*"(\w+)"', raw)
+        if key_match:
+            key = key_match.group(1)
+        val_match = re.search(r'"value"\s*:\s*"', raw)
+        if val_match:
+            start = val_match.end()
+            value = raw[start:].rstrip()
+            for suffix in ('"}\n', '"}', '"'):
+                if value.endswith(suffix):
+                    value = value[: -len(suffix)]
+                    break
+        if key:
+            logger.warning(
+                "Recovered set_output args from truncated JSON: key=%s, value_len=%d",
+                key,
+                len(value),
+            )
+            # Re-inject so the caller sees proper key/value
+            tool_input["key"] = key
+            tool_input["value"] = value
+
+    if key not in valid_keys:
+        return ToolResult(
+            tool_use_id="",
+            content=f"Invalid output key '{key}'. Valid keys: {valid_keys}",
+            is_error=True,
+        )
+
+    return ToolResult(
+        tool_use_id="",
+        content=f"Output '{key}' set successfully.",
+        is_error=False,
+    )
@@ -0,0 +1,496 @@
+"""Tool result handling: truncation, spillover, JSON preview, and execution.
+
+Manages tool result size limits, file spillover for large results, and
+smart JSON previews.  Also includes transient error classification and
+the context-window-exceeded error detector.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextvars
+import json
+import logging
+import re
+from pathlib import Path
+from typing import Any
+
+from framework.llm.provider import ToolResult, ToolUse
+from framework.llm.stream_events import ToolCallEvent
+
+logger = logging.getLogger(__name__)
+
+# Pattern for detecting context-window-exceeded errors across LLM providers.
+_CONTEXT_TOO_LARGE_RE = re.compile(
+    r"context.{0,20}(length|window|limit|size)|"
+    r"too.{0,10}(long|large|many.{0,10}tokens)|"
+    r"(exceed|exceeds|exceeded).{0,30}(limit|window|context|tokens)|"
+    r"maximum.{0,20}token|prompt.{0,20}too.{0,10}long",
+    re.IGNORECASE,
+)
+
+
+def is_context_too_large_error(exc: BaseException) -> bool:
+    """Detect whether an exception indicates the LLM input was too large."""
+    cls = type(exc).__name__
+    if "ContextWindow" in cls:
+        return True
+    return bool(_CONTEXT_TOO_LARGE_RE.search(str(exc)))
+
+
+def is_transient_error(exc: BaseException) -> bool:
+    """Classify whether an exception is transient (retryable) vs permanent.
+
+    Transient: network errors, rate limits, server errors, timeouts.
+    Permanent: auth errors, bad requests, context window exceeded.
+    """
+    try:
+        from litellm.exceptions import (
+            APIConnectionError,
+            BadGatewayError,
+            InternalServerError,
+            RateLimitError,
+            ServiceUnavailableError,
+        )
+
+        transient_types: tuple[type[BaseException], ...] = (
+            RateLimitError,
+            APIConnectionError,
+            InternalServerError,
+            BadGatewayError,
+            ServiceUnavailableError,
+            TimeoutError,
+            ConnectionError,
+            OSError,
+        )
+    except ImportError:
+        transient_types = (TimeoutError, ConnectionError, OSError)
+
+    if isinstance(exc, transient_types):
+        return True
+
+    # RuntimeError from StreamErrorEvent with "Stream error:" prefix
+    if isinstance(exc, RuntimeError):
+        error_str = str(exc).lower()
+        transient_keywords = [
+            "rate limit",
+            "429",
+            "timeout",
+            "connection",
+            "internal server",
+            "502",
+            "503",
+            "504",
+            "service unavailable",
+            "bad gateway",
+            "overloaded",
+            "failed to parse tool call",
+        ]
+        return any(kw in error_str for kw in transient_keywords)
+
+    return False
+
+
+def extract_json_metadata(parsed: Any, *, _depth: int = 0, _max_depth: int = 3) -> str:
+    """Return a concise structural summary of parsed JSON.
+
+    Reports key names, value types, and — crucially — array lengths so
+    the LLM knows how much data exists beyond the preview.
+
+    Returns an empty string for simple scalars.
+    """
+    if _depth >= _max_depth:
+        if isinstance(parsed, dict):
+            return f"dict with {len(parsed)} keys"
+        if isinstance(parsed, list):
+            return f"list of {len(parsed)} items"
+        return type(parsed).__name__
+
+    if isinstance(parsed, dict):
+        if not parsed:
+            return "empty dict"
+        lines: list[str] = []
+        indent = "  " * (_depth + 1)
+        for key, value in list(parsed.items())[:20]:
+            if isinstance(value, list):
+                line = f'{indent}"{key}": list of {len(value)} items'
+                if value:
+                    first = value[0]
+                    if isinstance(first, dict):
+                        sample_keys = list(first.keys())[:10]
+                        line += f" (each item: dict with keys {sample_keys})"
+                    elif isinstance(first, list):
+                        line += f" (each item: list of {len(first)} elements)"
+                lines.append(line)
+            elif isinstance(value, dict):
+                child = extract_json_metadata(value, _depth=_depth + 1, _max_depth=_max_depth)
+                lines.append(f'{indent}"{key}": {child}')
+            else:
+                lines.append(f'{indent}"{key}": {type(value).__name__}')
+        if len(parsed) > 20:
+            lines.append(f"{indent}... and {len(parsed) - 20} more keys")
+        return "\n".join(lines)
+
+    if isinstance(parsed, list):
+        if not parsed:
+            return "empty list"
+        desc = f"list of {len(parsed)} items"
+        first = parsed[0]
+        if isinstance(first, dict):
+            sample_keys = list(first.keys())[:10]
+            desc += f" (each item: dict with keys {sample_keys})"
+        elif isinstance(first, list):
+            desc += f" (each item: list of {len(first)} elements)"
+        return desc
+
+    return ""
+
+
+def build_json_preview(parsed: Any, *, max_chars: int = 5000) -> str | None:
+    """Build a smart preview of parsed JSON, truncating large arrays.
+
+    Shows first 3 + last 1 items of large arrays with explicit count
+    markers so the LLM cannot mistake the preview for the full dataset.
+
+    Returns ``None`` if no truncation was needed (no large arrays).
+    """
+    _LARGE_ARRAY_THRESHOLD = 10
+
+    def _truncate_arrays(obj: Any) -> tuple[Any, bool]:
+        """Return (truncated_copy, was_truncated)."""
+        if isinstance(obj, list) and len(obj) > _LARGE_ARRAY_THRESHOLD:
+            n = len(obj)
+            head = obj[:3]
+            tail = obj[-1:]
+            marker = f"... ({n - 4} more items omitted, {n} total) ..."
+            return head + [marker] + tail, True
+        if isinstance(obj, dict):
+            changed = False
+            out: dict[str, Any] = {}
+            for k, v in obj.items():
+                new_v, did = _truncate_arrays(v)
+                out[k] = new_v
+                changed = changed or did
+            return (out, True) if changed else (obj, False)
+        return obj, False
+
+    preview_obj, was_truncated = _truncate_arrays(parsed)
+    if not was_truncated:
+        return None  # No large arrays — caller should use raw slicing
+
+    try:
+        result = json.dumps(preview_obj, indent=2, ensure_ascii=False)
+    except (TypeError, ValueError):
+        return None
+
+    if len(result) > max_chars:
+        # Even 3+1 items too big — try just 1 item
+        def _minimal_arrays(obj: Any) -> Any:
+            if isinstance(obj, list) and len(obj) > _LARGE_ARRAY_THRESHOLD:
+                n = len(obj)
+                return obj[:1] + [f"... ({n - 1} more items omitted, {n} total) ..."]
+            if isinstance(obj, dict):
+                return {k: _minimal_arrays(v) for k, v in obj.items()}
+            return obj
+
+        preview_obj = _minimal_arrays(parsed)
+        try:
+            result = json.dumps(preview_obj, indent=2, ensure_ascii=False)
+        except (TypeError, ValueError):
+            return None
+        if len(result) > max_chars:
+            result = result[:max_chars] + "…"
+
+    return result
+
+
+def truncate_tool_result(
+    result: ToolResult,
+    tool_name: str,
+    *,
+    max_tool_result_chars: int,
+    spillover_dir: str | None,
+    next_spill_filename_fn: Any,  # Callable[[str], str]
+) -> ToolResult:
+    """Persist tool result to file and optionally truncate for context.
+
+    When *spillover_dir* is configured, EVERY non-error tool result is
+    saved to a file (short filename like ``web_search_1.txt``).  A
+    ``[Saved to '...']`` annotation is appended so the reference
+    survives pruning and compaction.
+
+    - Small results (≤ limit): full content kept + file annotation
+    - Large results (> limit): preview + file reference
+    - Errors: pass through unchanged
+    - load_data results: truncate with pagination hint (no re-spill)
+    """
+    limit = max_tool_result_chars
+
+    # Errors always pass through unchanged
+    if result.is_error:
+        return result
+
+    # load_data reads FROM spilled files — never re-spill (circular).
+    # Just truncate with a pagination hint if the result is too large.
+    if tool_name == "load_data":
+        if limit <= 0 or len(result.content) <= limit:
+            return result  # Small load_data result — pass through as-is
+        # Large load_data result — truncate with smart preview
+        PREVIEW_CAP = min(5000, max(limit - 500, limit // 2))
+
+        metadata_str = ""
+        smart_preview: str | None = None
+        try:
+            parsed_ld = json.loads(result.content)
+            metadata_str = extract_json_metadata(parsed_ld)
+            smart_preview = build_json_preview(parsed_ld, max_chars=PREVIEW_CAP)
+        except (json.JSONDecodeError, TypeError, ValueError):
+            pass
+
+        if smart_preview is not None:
+            preview_block = smart_preview
+        else:
+            preview_block = result.content[:PREVIEW_CAP] + "…"
+
+        header = (
+            f"[{tool_name} result: {len(result.content):,} chars — "
+            f"too large for context. Use offset_bytes/limit_bytes "
+            f"parameters to read smaller chunks.]"
+        )
+        if metadata_str:
+            header += f"\n\nData structure:\n{metadata_str}"
+        header += (
+            "\n\nWARNING: This is an INCOMPLETE preview. Do NOT draw conclusions or counts from it."
+        )
+
+        truncated = f"{header}\n\nPreview (small sample only):\n{preview_block}"
+        logger.info(
+            "%s result truncated: %d → %d chars (use offset/limit to paginate)",
+            tool_name,
+            len(result.content),
+            len(truncated),
+        )
+        return ToolResult(
+            tool_use_id=result.tool_use_id,
+            content=truncated,
+            is_error=False,
+            image_content=result.image_content,
+            is_skill_content=result.is_skill_content,
+        )
+
+    spill_dir = spillover_dir
+    if spill_dir:
+        spill_path = Path(spill_dir)
+        spill_path.mkdir(parents=True, exist_ok=True)
+        filename = next_spill_filename_fn(tool_name)
+
+        # Pretty-print JSON content so load_data's line-based
+        # pagination works correctly.
+        write_content = result.content
+        parsed_json: Any = None  # track for metadata extraction
+        try:
+            parsed_json = json.loads(result.content)
+            write_content = json.dumps(parsed_json, indent=2, ensure_ascii=False)
+        except (json.JSONDecodeError, TypeError, ValueError):
+            pass  # Not JSON — write as-is
+
+        (spill_path / filename).write_text(write_content, encoding="utf-8")
+
+        if limit > 0 and len(result.content) > limit:
+            # Large result: build a small, metadata-rich preview so the
+            # LLM cannot mistake it for the complete dataset.
+            PREVIEW_CAP = 5000
+
+            # Extract structural metadata (array lengths, key names)
+            metadata_str = ""
+            smart_preview: str | None = None
+            if parsed_json is not None:
+                metadata_str = extract_json_metadata(parsed_json)
+                smart_preview = build_json_preview(parsed_json, max_chars=PREVIEW_CAP)
+
+            if smart_preview is not None:
+                preview_block = smart_preview
+            else:
+                preview_block = result.content[:PREVIEW_CAP] + "…"
+
+            # Assemble header with structural info + warning
+            header = (
+                f"[Result from {tool_name}: {len(result.content):,} chars — "
+                f"too large for context, saved to '{filename}'.]\n"
+            )
+            if metadata_str:
+                header += f"\nData structure:\n{metadata_str}"
+            header += (
+                f"\n\nWARNING: The preview below is INCOMPLETE. "
+                f"Do NOT draw conclusions or counts from it. "
+                f"Use load_data(filename='{filename}') to read the "
+                f"full data before analysis."
+            )
+
+            content = f"{header}\n\nPreview (small sample only):\n{preview_block}"
+            logger.info(
+                "Tool result spilled to file: %s (%d chars → %s)",
+                tool_name,
+                len(result.content),
+                filename,
+            )
+        else:
+            # Small result: keep full content + annotation
+            content = f"{result.content}\n\n[Saved to '{filename}']"
+            logger.info(
+                "Tool result saved to file: %s (%d chars → %s)",
+                tool_name,
+                len(result.content),
+                filename,
+            )
+
+        return ToolResult(
+            tool_use_id=result.tool_use_id,
+            content=content,
+            is_error=False,
+            image_content=result.image_content,
+            is_skill_content=result.is_skill_content,
+        )
+
+    # No spillover_dir — truncate in-place if needed
+    if limit > 0 and len(result.content) > limit:
+        PREVIEW_CAP = min(5000, max(limit - 500, limit // 2))
+
+        metadata_str = ""
+        smart_preview: str | None = None
+        try:
+            parsed_inline = json.loads(result.content)
+            metadata_str = extract_json_metadata(parsed_inline)
+            smart_preview = build_json_preview(parsed_inline, max_chars=PREVIEW_CAP)
+        except (json.JSONDecodeError, TypeError, ValueError):
+            pass
+
+        if smart_preview is not None:
+            preview_block = smart_preview
+        else:
+            preview_block = result.content[:PREVIEW_CAP] + "…"
+
+        header = (
+            f"[Result from {tool_name}: {len(result.content):,} chars — "
+            f"truncated to fit context budget.]"
+        )
+        if metadata_str:
+            header += f"\n\nData structure:\n{metadata_str}"
+        header += (
+            "\n\nWARNING: This is an INCOMPLETE preview. "
+            "Do NOT draw conclusions or counts from the preview alone."
+        )
+
+        truncated = f"{header}\n\n{preview_block}"
+        logger.info(
+            "Tool result truncated in-place: %s (%d → %d chars)",
+            tool_name,
+            len(result.content),
+            len(truncated),
+        )
+        return ToolResult(
+            tool_use_id=result.tool_use_id,
+            content=truncated,
+            is_error=False,
+            image_content=result.image_content,
+            is_skill_content=result.is_skill_content,
+        )
+
+    return result
+
+
+async def execute_tool(
+    tool_executor: Any,  # Callable[[ToolUse], ToolResult | Awaitable[ToolResult]] | None
+    tc: ToolCallEvent,
+    timeout: float,
+    skill_dirs: list[str] | None = None,
+) -> ToolResult:
+    """Execute a tool call, handling both sync and async executors.
+
+    Applies ``tool_call_timeout_seconds`` to prevent hung MCP servers
+    from blocking the event loop indefinitely.  The initial executor
+    call is offloaded to a thread pool so that sync executors don't
+    freeze the event loop.
+    """
+    if tool_executor is None:
+        return ToolResult(
+            tool_use_id=tc.tool_use_id,
+            content=f"No tool executor configured for '{tc.tool_name}'",
+            is_error=True,
+        )
+
+    skill_dirs = skill_dirs or []
+    skill_read_tools = {"view_file", "load_data", "read_file"}
+    if tc.tool_name in skill_read_tools and skill_dirs:
+        raw_path = tc.tool_input.get("path", "")
+        if raw_path:
+            resolved = Path(raw_path).resolve(strict=False)
+            resolved_roots = [Path(skill_dir).resolve(strict=False) for skill_dir in skill_dirs]
+            if any(resolved.is_relative_to(root) for root in resolved_roots):
+                try:
+                    content = resolved.read_text(encoding="utf-8")
+                except Exception as exc:
+                    return ToolResult(
+                        tool_use_id=tc.tool_use_id,
+                        content=f"Could not read skill resource '{raw_path}': {exc}",
+                        is_error=True,
+                    )
+                return ToolResult(
+                    tool_use_id=tc.tool_use_id,
+                    content=content,
+                    is_skill_content=resolved.name == "SKILL.md",
+                )
+
+    tool_use = ToolUse(id=tc.tool_use_id, name=tc.tool_name, input=tc.tool_input)
+
+    async def _run() -> ToolResult:
+        # Offload the executor call to a thread.  Sync MCP executors
+        # block on future.result() — running in a thread keeps the
+        # event loop free so asyncio.wait_for can fire the timeout.
+        # Copy the current context so contextvars (e.g. data_dir from
+        # execution context) propagate into the worker thread.
+        loop = asyncio.get_running_loop()
+        ctx = contextvars.copy_context()
+        result = await loop.run_in_executor(None, ctx.run, tool_executor, tool_use)
+        # Async executors return a coroutine — await it on the loop
+        if asyncio.iscoroutine(result) or asyncio.isfuture(result):
+            result = await result
+        return result
+
+    try:
+        if timeout > 0:
+            result = await asyncio.wait_for(_run(), timeout=timeout)
+        else:
+            result = await _run()
+    except TimeoutError:
+        logger.warning("Tool '%s' timed out after %.0fs", tc.tool_name, timeout)
+        return ToolResult(
+            tool_use_id=tc.tool_use_id,
+            content=(
+                f"Tool '{tc.tool_name}' timed out after {timeout:.0f}s. "
+                "The operation took too long and was cancelled. "
+                "Try a simpler request or a different approach."
+            ),
+            is_error=True,
+        )
+    return result
+
+
+def restore_spill_counter(spillover_dir: str | None) -> int:
+    """Scan spillover_dir for existing spill files and return the max counter.
+
+    Returns the highest spill number found (or 0 if none).
+    """
+    if not spillover_dir:
+        return 0
+    spill_path = Path(spillover_dir)
+    if not spill_path.is_dir():
+        return 0
+    max_n = 0
+    for f in spill_path.iterdir():
+        if not f.is_file():
+            continue
+        m = re.search(r"_(\d+)\.txt$", f.name)
+        if m:
+            max_n = max(max_n, int(m.group(1)))
+    return max_n
@@ -0,0 +1,197 @@
+"""Shared types and state containers for the event loop package."""
+
+from __future__ import annotations
+
+import json
+import logging
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Literal, Protocol, runtime_checkable
+
+from framework.graph.conversation import (
+    ConversationStore,
+    get_run_cursor,
+    update_run_cursor,
+)
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class TriggerEvent:
+    """A framework-level trigger signal (timer tick or webhook hit)."""
+
+    trigger_type: str
+    source_id: str
+    payload: dict[str, Any] = field(default_factory=dict)
+    timestamp: float = field(default_factory=time.time)
+
+
+@dataclass
+class JudgeVerdict:
+    """Result of judge evaluation for the event loop."""
+
+    action: Literal["ACCEPT", "RETRY", "ESCALATE"]
+    # None  = no evaluation happened (skip_judge, tool-continue); not logged.
+    # ""    = evaluated but no feedback; logged with default text.
+    # "..." = evaluated with feedback; logged as-is.
+    feedback: str | None = None
+
+
+@runtime_checkable
+class JudgeProtocol(Protocol):
+    """Protocol for event-loop judges."""
+
+    async def evaluate(self, context: dict[str, Any]) -> JudgeVerdict: ...
+
+
+@dataclass
+class LoopConfig:
+    """Configuration for the event loop."""
+
+    max_iterations: int = 50
+    max_tool_calls_per_turn: int = 30
+    judge_every_n_turns: int = 1
+    stall_detection_threshold: int = 3
+    stall_similarity_threshold: float = 0.85
+    max_context_tokens: int = 32_000
+    store_prefix: str = ""
+
+    # Overflow margin for max_tool_calls_per_turn. Tool calls are only
+    # discarded when the count exceeds max_tool_calls_per_turn * (1 + margin).
+    tool_call_overflow_margin: float = 0.5
+
+    # Tool result context management.
+    max_tool_result_chars: int = 30_000
+    spillover_dir: str | None = None
+
+    # set_output value spilling.
+    max_output_value_chars: int = 2_000
+
+    # Stream retry.
+    max_stream_retries: int = 3
+    stream_retry_backoff_base: float = 2.0
+    stream_retry_max_delay: float = 60.0
+
+    # Tool doom loop detection.
+    tool_doom_loop_threshold: int = 3
+
+    # Client-facing auto-block grace period.
+    cf_grace_turns: int = 1
+    tool_doom_loop_enabled: bool = True
+
+    # Per-tool-call timeout.
+    tool_call_timeout_seconds: float = 60.0
+
+    # Subagent delegation timeout.
+    subagent_timeout_seconds: float = 600.0
+
+    # Lifecycle hooks.
+    hooks: dict[str, list] | None = None
+
+    def __post_init__(self) -> None:
+        if self.hooks is None:
+            object.__setattr__(self, "hooks", {})
+
+
+@dataclass
+class HookContext:
+    """Context passed to every lifecycle hook."""
+
+    event: str
+    trigger: str | None
+    system_prompt: str
+
+
+@dataclass
+class HookResult:
+    """What a hook may return to modify node state."""
+
+    system_prompt: str | None = None
+    inject: str | None = None
+
+
+@dataclass
+class OutputAccumulator:
+    """Accumulates output key-value pairs with optional write-through persistence."""
+
+    values: dict[str, Any] = field(default_factory=dict)
+    store: ConversationStore | None = None
+    spillover_dir: str | None = None
+    max_value_chars: int = 0
+    run_id: str | None = None
+
+    async def set(self, key: str, value: Any) -> None:
+        """Set a key-value pair, auto-spilling large values to files."""
+        value = self._auto_spill(key, value)
+        self.values[key] = value
+        if self.store:
+            cursor = await self.store.read_cursor() or {}
+            outputs = cursor.get("outputs", {})
+            outputs[key] = value
+            cursor["outputs"] = outputs
+            await self.store.write_cursor(cursor)
+
+    def _auto_spill(self, key: str, value: Any) -> Any:
+        """Save large values to a file and return a reference string."""
+        if self.max_value_chars <= 0 or not self.spillover_dir:
+            return value
+
+        val_str = json.dumps(value, ensure_ascii=False) if not isinstance(value, str) else value
+        if len(val_str) <= self.max_value_chars:
+            return value
+
+        spill_path = Path(self.spillover_dir)
+        spill_path.mkdir(parents=True, exist_ok=True)
+        ext = ".json" if isinstance(value, (dict, list)) else ".txt"
+        filename = f"output_{key}{ext}"
+        write_content = (
+            json.dumps(value, indent=2, ensure_ascii=False)
+            if isinstance(value, (dict, list))
+            else str(value)
+        )
+        (spill_path / filename).write_text(write_content, encoding="utf-8")
+        file_size = (spill_path / filename).stat().st_size
+        logger.info(
+            "set_output value auto-spilled: key=%s, %d chars -> %s (%d bytes)",
+            key,
+            len(val_str),
+            filename,
+            file_size,
+        )
+        return (
+            f"[Saved to '{filename}' ({file_size:,} bytes). "
+            f"Use load_data(filename='{filename}') "
+            f"to access full data.]"
+        )
+
+    def get(self, key: str) -> Any | None:
+        return self.values.get(key)
+
+    def to_dict(self) -> dict[str, Any]:
+        return dict(self.values)
+
+    def has_all_keys(self, required: list[str]) -> bool:
+        return all(key in self.values and self.values[key] is not None for key in required)
+
+    @classmethod
+    async def restore(
+        cls,
+        store: ConversationStore,
+        run_id: str | None = None,
+    ) -> OutputAccumulator:
+        cursor = await store.read_cursor()
+        values = cursor.get("outputs", {}) if cursor else {}
+        return cls(values=values, store=store, run_id=run_id)
+
+
+__all__ = [
+    "HookContext",
+    "HookResult",
+    "JudgeProtocol",
+    "JudgeVerdict",
+    "LoopConfig",
+    "OutputAccumulator",
+    "TriggerEvent",
+]
@@ -37,24 +37,45 @@ Follow these rules for reliable, efficient browser interaction.
 ## Reading Pages
 - ALWAYS prefer `browser_snapshot` over `browser_get_text("body")`
  — it returns a compact ~1-5 KB accessibility tree vs 100+ KB of raw HTML.
- Use `browser_snapshot_aria` when you need full ARIA properties
-  for detailed element inspection.
- Do NOT use `browser_screenshot` for reading text content
-  — it produces huge base64 images with no searchable text.
+- Interaction tools (`browser_click`, `browser_type`, `browser_fill`,
+  `browser_scroll`, etc.) return a page snapshot automatically in their
+  result. Use it to decide your next action — do NOT call
+  `browser_snapshot` separately after every action.
+  Only call `browser_snapshot` when you need a fresh view without
+  performing an action, or after setting `auto_snapshot=false`.
+- Do NOT use `browser_screenshot` to read text — use
+  `browser_snapshot` for that (compact, searchable, fast).
+- DO use `browser_screenshot` when you need visual context:
+  charts, images, canvas elements, layout verification, or when
+  the snapshot doesn't capture what you need.
 - Only fall back to `browser_get_text` for extracting specific
  small elements by CSS selector.

 ## Navigation & Waiting
- Always call `browser_wait` after navigation actions
-  (`browser_open`, `browser_navigate`, `browser_click` on links)
-  to let the page load.
+- `browser_navigate` and `browser_open` already wait for the page to
+  load (`domcontentloaded`). Do NOT call `browser_wait` with no
+  arguments after navigation — it wastes time.
+  Only use `browser_wait` when you need a *specific element* or *text*
+  to appear (pass `selector` or `text`).
 - NEVER re-navigate to the same URL after scrolling
  — this resets your scroll position and loses loaded content.

 ## Scrolling
 - Use large scroll amounts ~2000 when loading more content
  — sites like twitter and linkedin have lazy loading for paging.
- After scrolling, take a new `browser_snapshot` to see updated content.
+- The scroll result includes a snapshot automatically — no need to call
+  `browser_snapshot` separately.
+
+## Batching Actions
+- You can call multiple tools in a single turn — they execute in parallel.
+  ALWAYS batch independent actions together. Examples:
+  - Fill multiple form fields in one turn.
+  - Navigate + snapshot in one turn.
+  - Click + scroll if targeting different elements.
+- When batching, set `auto_snapshot=false` on all but the last action
+  to avoid redundant snapshots.
+- Aim for 3-5 tool calls per turn minimum. One tool call per turn is
+  wasteful.

 ## Error Recovery
 - If a tool fails, retry once with the same approach.
@@ -65,11 +86,33 @@ Follow these rules for reliable, efficient browser interaction.
  then `browser_start`, then retry.

 ## Tab Management
- Use `browser_tabs` to list open tabs when managing multiple pages.
- Pass `target_id` to tools when operating on a specific tab.
- Open background tabs with `browser_open(url=..., background=true)`
-  to avoid losing your current context.
- Close tabs you no longer need with `browser_close` to free resources.
+
+**Close tabs as soon as you are done with them** — not only at the end of the task.
+After reading or extracting data from a tab, close it immediately.
+
+**Decision rules:**
+- Finished reading/extracting from a tab? → `browser_close(target_id=...)`
+- Completed a multi-tab workflow? → `browser_close_finished()` to clean up all your tabs
+- More than 3 tabs open? → stop and close finished ones before opening more
+- Popup appeared that you didn't need? → close it immediately
+
+**Origin awareness:** `browser_tabs` returns an `origin` field for each tab:
+- `"agent"` — you opened it; you own it; close it when done
+- `"popup"` — opened by a link or script; close after extracting what you need
+- `"startup"` or `"user"` — leave these alone unless the task requires it
+
+**Cleanup tools:**
+- `browser_close(target_id=...)` — close one specific tab
+- `browser_close_finished()` — close all your agent/popup tabs (safe: leaves startup/user tabs)
+- `browser_close_all()` — close everything except the active tab (use only for full reset)
+
+**Multi-tab workflow pattern:**
+1. Open background tabs with `browser_open(url=..., background=true)` to stay on current tab
+2. Process each tab and close it with `browser_close` when done
+3. When the full workflow completes, call `browser_close_finished()` to confirm cleanup
+4. Check `browser_tabs` at any point — it shows `origin` and `age_seconds` per tab
+
+Never accumulate tabs. Treat every tab you open as a resource you must free.

 ## Login & Auth Walls
 - If you see a "Log in" or "Sign up" prompt instead of expected
@@ -167,14 +167,6 @@ class Goal(BaseModel):

        return met_weight >= total_weight * 0.9  # 90% threshold

-    def check_constraint(self, constraint_id: str, value: Any) -> bool:
-        """Check if a specific constraint is satisfied."""
-        for c in self.constraints:
-            if c.id == constraint_id:
-                # This would be expanded with actual evaluation logic
-                return True
-        return True
-
    def to_prompt_context(self) -> str:
        """Generate context string for LLM prompts.

@@ -1,203 +0,0 @@
-"""
-Standardized HITL (Human-In-The-Loop) Protocol
-
-This module defines the formal structure for pause/resume interactions
-where agents need to gather input from humans.
-"""
-
-from dataclasses import dataclass, field
-from enum import StrEnum
-from typing import Any
-
-
-class HITLInputType(StrEnum):
-    """Type of input expected from human."""
-
-    FREE_TEXT = "free_text"  # Open-ended text response
-    STRUCTURED = "structured"  # Specific fields to fill
-    SELECTION = "selection"  # Choose from options
-    APPROVAL = "approval"  # Yes/no/modify decision
-    MULTI_FIELD = "multi_field"  # Multiple related inputs
-
-
-@dataclass
-class HITLQuestion:
-    """A single question to ask the human."""
-
-    id: str
-    question: str
-    input_type: HITLInputType = HITLInputType.FREE_TEXT
-
-    # For SELECTION type
-    options: list[str] = field(default_factory=list)
-
-    # For STRUCTURED type
-    fields: dict[str, str] = field(default_factory=dict)  # {field_name: description}
-
-    # Metadata
-    required: bool = True
-    help_text: str = ""
-
-
-@dataclass
-class HITLRequest:
-    """
-    Formal request for human input at a pause node.
-
-    This is what the agent produces when it needs human input.
-    """
-
-    # Context
-    objective: str  # What we're trying to accomplish
-    current_state: str  # Where we are in the process
-
-    # What we need
-    questions: list[HITLQuestion] = field(default_factory=list)
-    missing_info: list[str] = field(default_factory=list)
-
-    # Guidance
-    instructions: str = ""
-    examples: list[str] = field(default_factory=list)
-
-    # Metadata
-    request_id: str = ""
-    node_id: str = ""
-
-    def to_dict(self) -> dict[str, Any]:
-        """Convert to dictionary for serialization."""
-        return {
-            "objective": self.objective,
-            "current_state": self.current_state,
-            "questions": [
-                {
-                    "id": q.id,
-                    "question": q.question,
-                    "input_type": q.input_type.value,
-                    "options": q.options,
-                    "fields": q.fields,
-                    "required": q.required,
-                    "help_text": q.help_text,
-                }
-                for q in self.questions
-            ],
-            "missing_info": self.missing_info,
-            "instructions": self.instructions,
-            "examples": self.examples,
-            "request_id": self.request_id,
-            "node_id": self.node_id,
-        }
-
-
-@dataclass
-class HITLResponse:
-    """
-    Human's response to a HITL request.
-
-    This is what gets passed back when resuming from a pause.
-    """
-
-    # Original request reference
-    request_id: str
-
-    # Human's answers
-    answers: dict[str, Any] = field(default_factory=dict)  # {question_id: answer}
-    raw_input: str = ""  # Raw text if provided
-
-    # Metadata
-    response_time_ms: int = 0
-
-    def to_dict(self) -> dict[str, Any]:
-        """Convert to dictionary for serialization."""
-        return {
-            "request_id": self.request_id,
-            "answers": self.answers,
-            "raw_input": self.raw_input,
-            "response_time_ms": self.response_time_ms,
-        }
-
-
-class HITLProtocol:
-    """
-    Standardized protocol for HITL interactions.
-
-    Usage in pause nodes:
-
-    1. Pause Node: Generates HITLRequest with questions
-    2. Executor: Saves state and returns request to user
-    3. User: Provides HITLResponse with answers
-    4. Resume Node: Processes response and merges into context
-    """
-
-    @staticmethod
-    def create_request(
-        objective: str,
-        questions: list[HITLQuestion],
-        missing_info: list[str] | None = None,
-        node_id: str = "",
-    ) -> HITLRequest:
-        """Create a standardized HITL request."""
-        return HITLRequest(
-            objective=objective,
-            current_state="Awaiting clarification",
-            questions=questions,
-            missing_info=missing_info or [],
-            request_id=f"{node_id}_{hash(objective) % 10000}",
-            node_id=node_id,
-        )
-
-    @staticmethod
-    def parse_response(
-        raw_input: str,
-        request: HITLRequest,
-        use_haiku: bool = True,
-    ) -> HITLResponse:
-        """
-        Parse human's raw input into structured response.
-
-        Maps the raw input to the first question. For multi-question HITL,
-        the caller should present one question at a time.
-        """
-        response = HITLResponse(request_id=request.request_id, raw_input=raw_input)
-
-        # If no questions, just return raw input
-        if not request.questions:
-            return response
-
-        # Map raw input to first question
-        response.answers[request.questions[0].id] = raw_input
-        return response
-
-    @staticmethod
-    def format_for_display(request: HITLRequest) -> str:
-        """Format HITL request for user-friendly display."""
-        parts = []
-
-        if request.objective:
-            parts.append(f"📋 Objective: {request.objective}")
-
-        if request.current_state:
-            parts.append(f"📍 Current State: {request.current_state}")
-
-        if request.instructions:
-            parts.append(f"\n{request.instructions}")
-
-        if request.questions:
-            parts.append(f"\n❓ Questions ({len(request.questions)}):")
-            for i, q in enumerate(request.questions, 1):
-                parts.append(f"{i}. {q.question}")
-                if q.help_text:
-                    parts.append(f"   💡 {q.help_text}")
-                if q.options:
-                    parts.append(f"   Options: {', '.join(q.options)}")
-
-        if request.missing_info:
-            parts.append("\n📝 Missing Information:")
-            for info in request.missing_info:
-                parts.append(f"  • {info}")
-
-        if request.examples:
-            parts.append("\n📚 Examples:")
-            for example in request.examples:
-                parts.append(f"  • {example}")
-
-        return "\n".join(parts)
@@ -2,7 +2,7 @@
 Node Protocol - The building block of agent graphs.

 A Node is a unit of work that:
-1. Receives context (goal, shared memory, input)
+1. Receives context (goal, shared buffer, input)
 2. Makes decisions (using LLM, tools, or logic)
 3. Produces results (output, state changes)
 4. Records everything to the Runtime
@@ -30,62 +30,6 @@ from framework.runtime.core import Runtime
 logger = logging.getLogger(__name__)


-def _fix_unescaped_newlines_in_json(json_str: str) -> str:
-    """Fix unescaped newlines inside JSON string values.
-
-    LLMs sometimes output actual newlines inside JSON strings instead of \\n.
-    This function fixes that by properly escaping newlines within string values.
-    """
-    result = []
-    in_string = False
-    escape_next = False
-    i = 0
-
-    while i < len(json_str):
-        char = json_str[i]
-
-        if escape_next:
-            result.append(char)
-            escape_next = False
-            i += 1
-            continue
-
-        if char == "\\" and in_string:
-            escape_next = True
-            result.append(char)
-            i += 1
-            continue
-
-        if char == '"' and not escape_next:
-            in_string = not in_string
-            result.append(char)
-            i += 1
-            continue
-
-        # Fix unescaped newlines inside strings
-        if in_string and char == "\n":
-            result.append("\\n")
-            i += 1
-            continue
-
-        # Fix unescaped carriage returns inside strings
-        if in_string and char == "\r":
-            result.append("\\r")
-            i += 1
-            continue
-
-        # Fix unescaped tabs inside strings
-        if in_string and char == "\t":
-            result.append("\\t")
-            i += 1
-            continue
-
-        result.append(char)
-        i += 1
-
-    return "".join(result)
-
-
 def find_json_object(text: str) -> str | None:
    """Find the first valid JSON object in text using balanced brace matching.

@@ -171,10 +115,10 @@ class NodeSpec(BaseModel):

    # Data flow
    input_keys: list[str] = Field(
-        default_factory=list, description="Keys this node reads from shared memory or input"
+        default_factory=list, description="Keys this node reads from the shared buffer or input"
    )
    output_keys: list[str] = Field(
-        default_factory=list, description="Keys this node writes to shared memory or output"
+        default_factory=list, description="Keys this node writes to the shared buffer or output"
    )
    nullable_output_keys: list[str] = Field(
        default_factory=list,
@@ -249,7 +193,10 @@ class NodeSpec(BaseModel):
    # Client-facing behavior
    client_facing: bool = Field(
        default=False,
-        description="If True, this node streams output to the end user and can request input.",
+        description=(
+            "Deprecated compatibility field. The queen is intrinsically interactive; "
+            "non-queen nodes should escalate to the queen instead of talking to users directly."
+        ),
    )

    # Phase completion criteria for conversation-aware judge (Level 2)
@@ -274,20 +221,46 @@ class NodeSpec(BaseModel):

    model_config = {"extra": "allow", "arbitrary_types_allowed": True}

+    def is_queen_node(self) -> bool:
+        """Return True when this spec is the queen conversational node."""
+        return self.id == "queen"

-class MemoryWriteError(Exception):
-    """Raised when an invalid value is written to memory."""
+    def supports_direct_user_io(self) -> bool:
+        """Return True when this node may talk to the user directly."""
+        return self.is_queen_node()
+
+
+def deprecated_client_facing_warning(node_spec: NodeSpec) -> str | None:
+    """Return a deprecation warning for legacy non-queen client_facing nodes."""
+    if node_spec.client_facing and not node_spec.is_queen_node():
+        return (
+            f"Node '{node_spec.id}' sets deprecated client_facing=True. "
+            "Non-queen direct human I/O is no longer supported; route worker "
+            "questions and approvals through queen escalation instead."
+        )
+    return None
+
+
+def warn_if_deprecated_client_facing(node_spec: NodeSpec) -> None:
+    """Log a compatibility warning once the node is loaded for execution."""
+    warning = deprecated_client_facing_warning(node_spec)
+    if warning:
+        logger.warning(warning)
+
+
+class DataBufferWriteError(Exception):
+    """Raised when an invalid value is written to the data buffer."""

    pass


@dataclass
-class SharedMemory:
+class DataBuffer:
    """
-    Shared state between nodes in a graph execution.
+    Shared data buffer between nodes in a graph execution.

-    Nodes read and write to shared memory using typed keys.
-    The memory is scoped to a single run.
+    Nodes read and write to the data buffer using typed keys.
+    The buffer is scoped to a single run.

    For parallel execution, use write_async() which provides per-key locking
    to prevent race conditions when multiple nodes write concurrently.
@@ -306,23 +279,23 @@ class SharedMemory:
            self._lock = asyncio.Lock()

    def read(self, key: str) -> Any:
-        """Read a value from shared memory."""
+        """Read a value from the data buffer."""
        if self._allowed_read and key not in self._allowed_read:
            raise PermissionError(f"Node not allowed to read key: {key}")
        return self._data.get(key)

    def write(self, key: str, value: Any, validate: bool = True) -> None:
        """
-        Write a value to shared memory.
+        Write a value to the data buffer.

        Args:
-            key: The memory key to write to
+            key: The buffer key to write to
            value: The value to write
            validate: If True, check for suspicious content (default True)

        Raises:
            PermissionError: If node doesn't have write permission
-            MemoryWriteError: If value appears to be hallucinated content
+            DataBufferWriteError: If value appears to be hallucinated content
        """
        if self._allowed_write and key not in self._allowed_write:
            raise PermissionError(f"Node not allowed to write key: {key}")
@@ -336,7 +309,7 @@ class SharedMemory:
                        f"⚠ Suspicious write to key '{key}': appears to be code "
                        f"({len(value)} chars). Consider using validate=False if intended."
                    )
-                    raise MemoryWriteError(
+                    raise DataBufferWriteError(
                        f"Rejected suspicious content for key '{key}': "
                        f"appears to be hallucinated code ({len(value)} chars). "
                        "If this is intentional, use validate=False."
@@ -352,13 +325,13 @@ class SharedMemory:
        parallel execution. Each key has its own lock to minimize contention.

        Args:
-            key: The memory key to write to
+            key: The buffer key to write to
            value: The value to write
            validate: If True, check for suspicious content (default True)

        Raises:
            PermissionError: If node doesn't have write permission
-            MemoryWriteError: If value appears to be hallucinated content
+            DataBufferWriteError: If value appears to be hallucinated content
        """
        # Check permissions first (no lock needed)
        if self._allowed_write and key not in self._allowed_write:
@@ -379,7 +352,7 @@ class SharedMemory:
                            f"⚠ Suspicious write to key '{key}': appears to be code "
                            f"({len(value)} chars). Consider using validate=False if intended."
                        )
-                        raise MemoryWriteError(
+                        raise DataBufferWriteError(
                            f"Rejected suspicious content for key '{key}': "
                            f"appears to be hallucinated code ({len(value)} chars). "
                            "If this is intentional, use validate=False."
@@ -457,13 +430,13 @@ class SharedMemory:
        self,
        read_keys: list[str],
        write_keys: list[str],
-    ) -> "SharedMemory":
+    ) -> "DataBuffer":
        """Create a view with restricted permissions for a specific node.

        The scoped view shares the same underlying data and locks,
        enabling thread-safe parallel execution across scoped views.
        """
-        return SharedMemory(
+        return DataBuffer(
            _data=self._data,
            _allowed_read=set(read_keys) if read_keys else set(),
            _allowed_write=set(write_keys) if write_keys else set(),
@@ -479,7 +452,7 @@ class NodeContext:

    This is passed to every node and provides:
    - Access to the runtime (for decision logging)
-    - Access to shared memory (for state)
+    - Access to the data buffer (for state)
    - Access to LLM (for generation)
    - Access to tools (for actions)
    - The goal context (for guidance)
@@ -493,7 +466,7 @@ class NodeContext:
    node_spec: NodeSpec

    # State
-    memory: SharedMemory
+    buffer: DataBuffer
    input_data: dict[str, Any] = field(default_factory=dict)

    # LLM access (if applicable)
@@ -529,12 +502,25 @@ class NodeContext:
    # rebuilding the full system prompt when restoring from conversation store.
    identity_prompt: str = ""
    narrative: str = ""
+    # Static memory block injected into the system prompt.
+    memory_prompt: str = ""

    # Event-triggered execution (no interactive user attached)
    event_triggered: bool = False

    # Execution ID (from StreamRuntimeAdapter)
    execution_id: str = ""
+    run_id: str = ""
+
+    @property
+    def effective_run_id(self) -> str | None:
+        """Normalized run_id: returns run_id if truthy, otherwise None.
+
+        The field defaults to ``""``; callers should use this property
+        instead of ``self.run_id or None`` to avoid silently falling
+        back to session-scoped storage.
+        """
+        return self.run_id or None

    # Stream identity — the ExecutionStream this node runs within.
    # Falls back to node_id when not set (legacy / standalone executor).
@@ -564,6 +550,38 @@ class NodeContext:
    # the queen to switch between phase-specific prompts (building /
    # staging / running) without restarting the conversation.
    dynamic_prompt_provider: Any = None  # Callable[[], str] | None
+    # 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
+
+    # Skill system prompts — injected by the skill discovery pipeline
+    skills_catalog_prompt: str = ""  # Available skills XML catalog
+    protocols_prompt: str = ""  # Default skill operational protocols
+    skill_dirs: list[str] = field(default_factory=list)  # Skill base dirs for resource access
+    # DS-12: batch auto-detection nudge appended to system prompt when input looks like a batch
+    default_skill_batch_nudge: str | None = None
+    # DS-13: token usage ratio at which to inject a context preservation warning
+    default_skill_warn_ratio: float | None = None
+
+    # Per-iteration metadata provider — when set, EventLoopNode merges
+    # the returned dict into node_loop_iteration event data.  Used by
+    # the queen to record the current phase per iteration.
+    iteration_metadata_provider: Any = None  # Callable[[], dict] | None
+
+    @property
+    def is_queen_stream(self) -> bool:
+        """Return True when this context belongs to the queen conversation."""
+        return self.stream_id == "queen" or self.node_spec.is_queen_node()
+
+    @property
+    def emits_client_io(self) -> bool:
+        """Return True when text should be published to user-facing streams."""
+        return self.is_queen_stream
+
+    @property
+    def supports_direct_user_io(self) -> bool:
+        """Return True when the node may directly request user input."""
+        return self.is_queen_stream and not self.event_triggered


@dataclass
@@ -672,6 +690,6 @@ class NodeProtocol(ABC):
        """
        errors = []
        for key in ctx.node_spec.input_keys:
-            if key not in ctx.input_data and ctx.memory.read(key) is None:
+            if key not in ctx.input_data and ctx.buffer.read(key) is None:
                errors.append(f"Missing required input: {key}")
        return errors
@@ -1,138 +1,29 @@
-"""Prompt composition for continuous agent mode.
+"""Legacy compatibility wrapper around :mod:`framework.graph.prompting`.

-Composes the three-layer system prompt (onion model) and generates
-transition markers inserted into the conversation at phase boundaries.
-
-Layer 1 — Identity (static, defined at agent level, never changes):
-  "You are a thorough research agent. You prefer clarity over jargon..."
-
-Layer 2 — Narrative (auto-generated from conversation/memory state):
-  "We've finished scoping the project. The user wants to focus on..."
-
-Layer 3 — Focus (per-node system_prompt, reframed as focus directive):
-  "Your current attention: synthesize findings into a report..."
+New runtime code should import from ``framework.graph.prompting`` directly.
 """

 from __future__ import annotations

-import logging
-from datetime import datetime
+import json
 from pathlib import Path
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING
+
+from framework.graph.prompting import (
+    EXECUTION_SCOPE_PREAMBLE,
+    TransitionSpec,
+    build_accounts_prompt,
+    build_narrative,
+    build_system_prompt,
+    stamp_prompt_datetime,
+)

 if TYPE_CHECKING:
    from framework.graph.edge import GraphSpec
-    from framework.graph.node import NodeSpec, SharedMemory
-
-logger = logging.getLogger(__name__)
+    from framework.graph.node import DataBuffer, NodeSpec


-def _with_datetime(prompt: str) -> str:
-    """Append current datetime with local timezone to a system prompt."""
-    local = datetime.now().astimezone()
-    stamp = f"Current date and time: {local.strftime('%Y-%m-%d %H:%M %Z (UTC%z)')}"
-    return f"{prompt}\n\n{stamp}" if prompt else stamp
-
-
-def build_accounts_prompt(
-    accounts: list[dict[str, Any]],
-    tool_provider_map: dict[str, str] | None = None,
-    node_tool_names: list[str] | None = None,
-) -> str:
-    """Build a prompt section describing connected accounts.
-
-    When tool_provider_map is provided, produces structured output grouped
-    by provider with tool mapping, so the LLM knows which ``account`` value
-    to pass to which tool.
-
-    When node_tool_names is also provided, filters to only show providers
-    whose tools overlap with the node's tool list.
-
-    Args:
-        accounts: List of account info dicts from
-            CredentialStoreAdapter.get_all_account_info().
-        tool_provider_map: Mapping of tool_name -> provider_name
-            (e.g. {"gmail_list_messages": "google"}).
-        node_tool_names: Tool names available to the current node.
-            When provided, only providers with matching tools are shown.
-
-    Returns:
-        Formatted accounts block, or empty string if no accounts.
-    """
-    if not accounts:
-        return ""
-
-    # Flat format (backward compat) when no tool mapping provided
-    if tool_provider_map is None:
-        lines = [
-            "Connected accounts (use the alias as the `account` parameter "
-            "when calling tools to target a specific account):"
-        ]
-        for acct in accounts:
-            provider = acct.get("provider", "unknown")
-            alias = acct.get("alias", "unknown")
-            identity = acct.get("identity", {})
-            detail_parts = [f"{k}: {v}" for k, v in identity.items() if v]
-            detail = f" ({', '.join(detail_parts)})" if detail_parts else ""
-            lines.append(f"- {provider}/{alias}{detail}")
-        return "\n".join(lines)
-
-    # --- Structured format: group by provider with tool mapping ---
-
-    # Invert tool_provider_map to provider -> [tools]
-    provider_tools: dict[str, list[str]] = {}
-    for tool_name, provider in tool_provider_map.items():
-        provider_tools.setdefault(provider, []).append(tool_name)
-
-    # Filter to relevant providers based on node tools
-    node_tool_set = set(node_tool_names) if node_tool_names else None
-
-    # Group accounts by provider
-    provider_accounts: dict[str, list[dict[str, Any]]] = {}
-    for acct in accounts:
-        provider = acct.get("provider", "unknown")
-        provider_accounts.setdefault(provider, []).append(acct)
-
-    sections: list[str] = ["Connected accounts:"]
-
-    for provider, acct_list in provider_accounts.items():
-        tools_for_provider = sorted(provider_tools.get(provider, []))
-
-        # If node tools specified, only show providers with overlapping tools
-        if node_tool_set is not None:
-            relevant_tools = [t for t in tools_for_provider if t in node_tool_set]
-            if not relevant_tools:
-                continue
-            tools_for_provider = relevant_tools
-
-        # Local-only providers: tools read from env vars, no account= routing
-        all_local = all(a.get("source") == "local" for a in acct_list)
-
-        # Provider header with tools
-        display_name = provider.replace("_", " ").title()
-        if tools_for_provider and not all_local:
-            tools_str = ", ".join(tools_for_provider)
-            sections.append(f'\n{display_name} (use account="<alias>" with: {tools_str}):')
-        elif tools_for_provider and all_local:
-            tools_str = ", ".join(tools_for_provider)
-            sections.append(f"\n{display_name} (tools: {tools_str}):")
-        else:
-            sections.append(f"\n{display_name}:")
-
-        # Account entries
-        for acct in acct_list:
-            alias = acct.get("alias", "unknown")
-            identity = acct.get("identity", {})
-            detail_parts = [f"{k}: {v}" for k, v in identity.items() if v]
-            detail = f" ({', '.join(detail_parts)})" if detail_parts else ""
-            source_tag = " [local]" if acct.get("source") == "local" else ""
-            sections.append(f"  - {provider}/{alias}{detail}{source_tag}")
-
-    # If filtering removed all providers, return empty
-    if len(sections) <= 1:
-        return ""
-
-    return "\n".join(sections)
+_with_datetime = stamp_prompt_datetime


 def compose_system_prompt(
@@ -140,167 +31,120 @@ def compose_system_prompt(
    focus_prompt: str | None,
    narrative: str | None = None,
    accounts_prompt: str | None = None,
+    skills_catalog_prompt: str | None = None,
+    protocols_prompt: str | None = None,
+    execution_preamble: str | None = None,
+    node_type_preamble: str | None = None,
 ) -> str:
-    """Compose the three-layer system prompt.
+    """Compatibility wrapper for the legacy function signature."""
+    from framework.graph.prompting import NodePromptSpec

-    Args:
-        identity_prompt: Layer 1 — static agent identity (from GraphSpec).
-        focus_prompt: Layer 3 — per-node focus directive (from NodeSpec.system_prompt).
-        narrative: Layer 2 — auto-generated from conversation state.
-        accounts_prompt: Connected accounts block (sits between identity and narrative).
-
-    Returns:
-        Composed system prompt with all layers present, plus current datetime.
-    """
-    parts: list[str] = []
-
-    # Layer 1: Identity (always first, anchors the personality)
-    if identity_prompt:
-        parts.append(identity_prompt)
-
-    # Accounts (semi-static, deployment-specific)
-    if accounts_prompt:
-        parts.append(f"\n{accounts_prompt}")
-
-    # Layer 2: Narrative (what's happened so far)
-    if narrative:
-        parts.append(f"\n--- Context (what has happened so far) ---\n{narrative}")
-
-    # Layer 3: Focus (current phase directive)
-    if focus_prompt:
-        parts.append(f"\n--- Current Focus ---\n{focus_prompt}")
-
-    return _with_datetime("\n".join(parts) if parts else "")
-
-
-def build_narrative(
-    memory: SharedMemory,
-    execution_path: list[str],
-    graph: GraphSpec,
-) -> str:
-    """Build Layer 2 (narrative) from structured state.
-
-    Deterministic — no LLM call. Reads SharedMemory and execution path
-    to describe what has happened so far. Cheap and fast.
-
-    Args:
-        memory: Current shared memory state.
-        execution_path: List of node IDs visited so far.
-        graph: Graph spec (for node names/descriptions).
-
-    Returns:
-        Narrative string describing the session state.
-    """
-    parts: list[str] = []
-
-    # Describe execution path
-    if execution_path:
-        phase_descriptions: list[str] = []
-        for node_id in execution_path:
-            node_spec = graph.get_node(node_id)
-            if node_spec:
-                phase_descriptions.append(f"- {node_spec.name}: {node_spec.description}")
-            else:
-                phase_descriptions.append(f"- {node_id}")
-        parts.append("Phases completed:\n" + "\n".join(phase_descriptions))
-
-    # Describe key memory values (skip very long values)
-    all_memory = memory.read_all()
-    if all_memory:
-        memory_lines: list[str] = []
-        for key, value in all_memory.items():
-            if value is None:
-                continue
-            val_str = str(value)
-            if len(val_str) > 200:
-                val_str = val_str[:200] + "..."
-            memory_lines.append(f"- {key}: {val_str}")
-        if memory_lines:
-            parts.append("Current state:\n" + "\n".join(memory_lines))
-
-    return "\n\n".join(parts) if parts else ""
+    spec = NodePromptSpec(
+        identity_prompt=identity_prompt or "",
+        focus_prompt=focus_prompt or "",
+        narrative=narrative or "",
+        accounts_prompt=accounts_prompt or "",
+        skills_catalog_prompt=skills_catalog_prompt or "",
+        protocols_prompt=protocols_prompt or "",
+        # Legacy callers explicitly passed these preambles. Preserve them by
+        # folding them into the focus block when present.
+        node_type="event_loop",
+    )
+    if execution_preamble or node_type_preamble:
+        focus_parts = []
+        if execution_preamble:
+            focus_parts.append(execution_preamble)
+        if node_type_preamble:
+            focus_parts.append(node_type_preamble)
+        if spec.focus_prompt:
+            focus_parts.append(spec.focus_prompt)
+        spec = NodePromptSpec(
+            identity_prompt=spec.identity_prompt,
+            focus_prompt="\n\n".join(focus_parts),
+            narrative=spec.narrative,
+            accounts_prompt=spec.accounts_prompt,
+            skills_catalog_prompt=spec.skills_catalog_prompt,
+            protocols_prompt=spec.protocols_prompt,
+            node_type=spec.node_type,
+            output_keys=spec.output_keys,
+            is_subagent_mode=spec.is_subagent_mode,
+        )
+    return build_system_prompt(spec)


 def build_transition_marker(
    previous_node: NodeSpec,
    next_node: NodeSpec,
-    memory: SharedMemory,
+    buffer: DataBuffer,
    cumulative_tool_names: list[str],
    data_dir: Path | str | None = None,
-    adapt_content: str | None = None,
 ) -> str:
-    """Build a 'State of the World' transition marker.
+    """Legacy transition builder with best-effort spillover compatibility."""
+    buffer_items: dict[str, str] = {}
+    data_files: list[str] = []

-    Inserted into the conversation as a user message at phase boundaries.
-    Gives the LLM full situational awareness: what happened, what's stored,
-    what tools are available, and what to focus on next.
+    all_buffer = buffer.read_all()
+    for key, value in all_buffer.items():
+        if value is None:
+            continue
+        val_str = str(value)
+        if len(val_str) > 300 and data_dir:
+            data_path = Path(data_dir)
+            data_path.mkdir(parents=True, exist_ok=True)
+            ext = ".json" if isinstance(value, (dict, list)) else ".txt"
+            filename = f"output_{key}{ext}"
+            file_path = data_path / filename
+            try:
+                write_content = (
+                    json.dumps(value, indent=2, ensure_ascii=False)
+                    if isinstance(value, (dict, list))
+                    else str(value)
+                )
+                file_path.write_text(write_content, encoding="utf-8")
+                file_size = file_path.stat().st_size
+                buffer_items[key] = (
+                    f"[Saved to '{filename}' ({file_size:,} bytes). "
+                    f"Use load_data(filename='{filename}') to access.]"
+                )
+            except Exception:
+                buffer_items[key] = val_str[:300] + "..."
+        elif len(val_str) > 300:
+            buffer_items[key] = val_str[:300] + "..."
+        else:
+            buffer_items[key] = val_str

-    Args:
-        previous_node: NodeSpec of the phase just completed.
-        next_node: NodeSpec of the phase about to start.
-        memory: Current shared memory state.
-        cumulative_tool_names: All tools available (cumulative set).
-        data_dir: Path to spillover data directory.
-        adapt_content: Agent working memory (adapt.md) content.
-
-    Returns:
-        Transition marker message text.
-    """
-    sections: list[str] = []
-
-    # Header
-    sections.append(f"--- PHASE TRANSITION: {previous_node.name} → {next_node.name} ---")
-
-    # What just completed
-    sections.append(f"\nCompleted: {previous_node.name}")
-    sections.append(f"  {previous_node.description}")
-
-    # Outputs in memory
-    all_memory = memory.read_all()
-    if all_memory:
-        memory_lines: list[str] = []
-        for key, value in all_memory.items():
-            if value is None:
-                continue
-            val_str = str(value)
-            if len(val_str) > 300:
-                val_str = val_str[:300] + "..."
-            memory_lines.append(f"  {key}: {val_str}")
-        if memory_lines:
-            sections.append("\nOutputs available:\n" + "\n".join(memory_lines))
-
-    # Files in data directory
    if data_dir:
        data_path = Path(data_dir)
        if data_path.exists():
-            files = sorted(data_path.iterdir())
-            if files:
-                file_lines = [
-                    f"  {f.name} ({f.stat().st_size:,} bytes)" for f in files if f.is_file()
-                ]
-                if file_lines:
-                    sections.append(
-                        "\nData files (use read_file to access):\n" + "\n".join(file_lines)
-                    )
+            data_files = [
+                f"{entry.name} ({entry.stat().st_size:,} bytes)"
+                for entry in sorted(data_path.iterdir())
+                if entry.is_file()
+            ]

-    # Agent working memory
-    if adapt_content:
-        sections.append(f"\n--- Agent Memory ---\n{adapt_content}")
-
-    # Available tools
-    if cumulative_tool_names:
-        sections.append("\nAvailable tools: " + ", ".join(sorted(cumulative_tool_names)))
-
-    # Next phase
-    sections.append(f"\nNow entering: {next_node.name}")
-    sections.append(f"  {next_node.description}")
-
-    # Reflection prompt (engineered metacognition)
-    sections.append(
-        "\nBefore proceeding, briefly reflect: what went well in the "
-        "previous phase? Are there any gaps or surprises worth noting?"
+    return build_transition_message(
+        TransitionSpec(
+            previous_name=previous_node.name,
+            previous_description=previous_node.description,
+            next_name=next_node.name,
+            next_description=next_node.description,
+            next_output_keys=tuple(next_node.output_keys or ()),
+            buffer_items=buffer_items,
+            cumulative_tool_names=tuple(sorted(cumulative_tool_names)),
+            data_files=tuple(data_files),
+        )
    )

-    sections.append("\n--- END TRANSITION ---")

-    return "\n".join(sections)
+from framework.graph.prompting import build_transition_message
+
+
+__all__ = [
+    "EXECUTION_SCOPE_PREAMBLE",
+    "_with_datetime",
+    "build_accounts_prompt",
+    "build_narrative",
+    "build_transition_marker",
+    "build_transition_message",
+    "compose_system_prompt",
+]
@@ -0,0 +1,312 @@
+"""Pure prompt rendering helpers for graph execution.
+
+This module owns all prompt text assembly for graph nodes.
+It intentionally avoids side effects so runtime code can prepare any
+spill files or transition metadata separately and then pass plain data in.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from framework.graph.edge import GraphSpec
+    from framework.graph.node import DataBuffer
+
+
+# Injected into every worker node's system prompt so the LLM understands
+# it is one step in a multi-node pipeline and should not overreach.
+EXECUTION_SCOPE_PREAMBLE = (
+    "EXECUTION SCOPE: You are one node in a multi-step workflow graph. "
+    "Focus ONLY on the task described in your instructions below. "
+    "Call set_output() for each of your declared output keys, then stop. "
+    "Do NOT attempt work that belongs to other nodes - the framework "
+    "routes data between nodes automatically."
+)
+
+
+@dataclass(frozen=True)
+class NodePromptSpec:
+    """Structured inputs for building one node system prompt."""
+
+    identity_prompt: str = ""
+    focus_prompt: str = ""
+    narrative: str = ""
+    accounts_prompt: str = ""
+    skills_catalog_prompt: str = ""
+    protocols_prompt: str = ""
+    memory_prompt: str = ""
+    node_type: str = "event_loop"
+    output_keys: tuple[str, ...] = ()
+    is_subagent_mode: bool = False
+
+
+@dataclass(frozen=True)
+class TransitionSpec:
+    """Structured inputs for a transition marker message."""
+
+    previous_name: str
+    previous_description: str
+    next_name: str
+    next_description: str
+    next_output_keys: tuple[str, ...] = ()
+    buffer_items: dict[str, str] = field(default_factory=dict)
+    cumulative_tool_names: tuple[str, ...] = ()
+    data_files: tuple[str, ...] = ()
+
+
+def stamp_prompt_datetime(prompt: str) -> str:
+    """Append current datetime with local timezone to a prompt."""
+    local = datetime.now().astimezone()
+    stamp = f"Current date and time: {local.strftime('%Y-%m-%d %H:%M %Z (UTC%z)')}"
+    return f"{prompt}\n\n{stamp}" if prompt else stamp
+
+
+def build_accounts_prompt(
+    accounts: list[dict[str, Any]],
+    tool_provider_map: dict[str, str] | None = None,
+    node_tool_names: list[str] | None = None,
+) -> str:
+    """Build a prompt section describing connected accounts."""
+    if not accounts:
+        return ""
+
+    if tool_provider_map is None:
+        lines = [
+            "Connected accounts (use the alias as the `account` parameter "
+            "when calling tools to target a specific account):"
+        ]
+        for acct in accounts:
+            provider = acct.get("provider", "unknown")
+            alias = acct.get("alias", "unknown")
+            identity = acct.get("identity", {})
+            detail_parts = [f"{k}: {v}" for k, v in identity.items() if v]
+            detail = f" ({', '.join(detail_parts)})" if detail_parts else ""
+            lines.append(f"- {provider}/{alias}{detail}")
+        return "\n".join(lines)
+
+    provider_tools: dict[str, list[str]] = {}
+    for tool_name, provider in tool_provider_map.items():
+        provider_tools.setdefault(provider, []).append(tool_name)
+
+    node_tool_set = set(node_tool_names) if node_tool_names else None
+
+    provider_accounts: dict[str, list[dict[str, Any]]] = {}
+    for acct in accounts:
+        provider = acct.get("provider", "unknown")
+        provider_accounts.setdefault(provider, []).append(acct)
+
+    sections: list[str] = ["Connected accounts:"]
+
+    for provider, acct_list in provider_accounts.items():
+        tools_for_provider = sorted(provider_tools.get(provider, []))
+
+        if node_tool_set is not None:
+            relevant_tools = [tool_name for tool_name in tools_for_provider if tool_name in node_tool_set]
+            if not relevant_tools:
+                continue
+            tools_for_provider = relevant_tools
+
+        all_local = all(acct.get("source") == "local" for acct in acct_list)
+        display_name = provider.replace("_", " ").title()
+        if tools_for_provider and not all_local:
+            tools_str = ", ".join(tools_for_provider)
+            sections.append(f'\n{display_name} (use account="<alias>" with: {tools_str}):')
+        elif tools_for_provider and all_local:
+            tools_str = ", ".join(tools_for_provider)
+            sections.append(f"\n{display_name} (tools: {tools_str}):")
+        else:
+            sections.append(f"\n{display_name}:")
+
+        for acct in acct_list:
+            alias = acct.get("alias", "unknown")
+            identity = acct.get("identity", {})
+            detail_parts = [f"{k}: {v}" for k, v in identity.items() if v]
+            detail = f" ({', '.join(detail_parts)})" if detail_parts else ""
+            source_tag = " [local]" if acct.get("source") == "local" else ""
+            sections.append(f"  - {provider}/{alias}{detail}{source_tag}")
+
+    if len(sections) <= 1:
+        return ""
+
+    return "\n".join(sections)
+
+
+def build_prompt_spec_from_node_context(
+    ctx: Any,
+    *,
+    focus_prompt: str | None = None,
+    narrative: str | None = None,
+    memory_prompt: str | None = None,
+) -> NodePromptSpec:
+    """Convert a NodeContext-like object into structured prompt inputs."""
+    resolved_memory_prompt = memory_prompt
+    if resolved_memory_prompt is None:
+        resolved_memory_prompt = getattr(ctx, "memory_prompt", "") or ""
+        dynamic_memory_provider = getattr(ctx, "dynamic_memory_provider", None)
+        if dynamic_memory_provider is not None:
+            try:
+                resolved_memory_prompt = dynamic_memory_provider() or ""
+            except Exception:
+                resolved_memory_prompt = getattr(ctx, "memory_prompt", "") or ""
+    return NodePromptSpec(
+        identity_prompt=ctx.identity_prompt or "",
+        focus_prompt=focus_prompt if focus_prompt is not None else (ctx.node_spec.system_prompt or ""),
+        narrative=narrative if narrative is not None else (ctx.narrative or ""),
+        accounts_prompt=ctx.accounts_prompt or "",
+        skills_catalog_prompt=ctx.skills_catalog_prompt or "",
+        protocols_prompt=ctx.protocols_prompt or "",
+        memory_prompt=resolved_memory_prompt,
+        node_type=ctx.node_spec.node_type,
+        output_keys=tuple(ctx.node_spec.output_keys or ()),
+        is_subagent_mode=bool(getattr(ctx, "is_subagent_mode", False)),
+    )
+
+
+def build_system_prompt(spec: NodePromptSpec) -> str:
+    """Compose one canonical system prompt for a node."""
+    parts: list[str] = []
+
+    if spec.identity_prompt:
+        parts.append(spec.identity_prompt)
+
+    if spec.accounts_prompt:
+        parts.append(f"\n{spec.accounts_prompt}")
+
+    if spec.skills_catalog_prompt:
+        parts.append(f"\n{spec.skills_catalog_prompt}")
+
+    if spec.protocols_prompt:
+        parts.append(f"\n{spec.protocols_prompt}")
+
+    if spec.memory_prompt:
+        parts.append(
+            "\nRelevant recalled memories may appear below. Treat them as "
+            "point-in-time guidance and verify stale details against current context."
+        )
+        parts.append(f"\n{spec.memory_prompt}")
+
+    if spec.narrative:
+        parts.append(f"\n--- Context (what has happened so far) ---\n{spec.narrative}")
+
+    if (
+        not spec.is_subagent_mode
+        and spec.node_type in ("event_loop", "gcu")
+        and spec.output_keys
+    ):
+        parts.append(f"\n{EXECUTION_SCOPE_PREAMBLE}")
+
+    if spec.node_type == "gcu":
+        from framework.graph.gcu import GCU_BROWSER_SYSTEM_PROMPT
+
+        parts.append(f"\n{GCU_BROWSER_SYSTEM_PROMPT}")
+
+    if spec.focus_prompt:
+        parts.append(f"\n--- Current Focus ---\n{spec.focus_prompt}")
+
+    return stamp_prompt_datetime("\n".join(parts) if parts else "")
+
+
+def build_system_prompt_for_node_context(
+    ctx: Any,
+    *,
+    focus_prompt: str | None = None,
+    narrative: str | None = None,
+    memory_prompt: str | None = None,
+) -> str:
+    """Build a canonical system prompt from a NodeContext-like object."""
+    spec = build_prompt_spec_from_node_context(
+        ctx,
+        focus_prompt=focus_prompt,
+        narrative=narrative,
+        memory_prompt=memory_prompt,
+    )
+    return build_system_prompt(spec)
+
+
+def build_narrative(
+    buffer: DataBuffer,
+    execution_path: list[str],
+    graph: GraphSpec,
+) -> str:
+    """Build a deterministic Layer 2 narrative from graph state."""
+    parts: list[str] = []
+
+    if execution_path:
+        phase_descriptions: list[str] = []
+        for node_id in execution_path:
+            node_spec = graph.get_node(node_id)
+            if node_spec:
+                phase_descriptions.append(f"- {node_spec.name}: {node_spec.description}")
+            else:
+                phase_descriptions.append(f"- {node_id}")
+        parts.append("Phases completed:\n" + "\n".join(phase_descriptions))
+
+    all_buffer = buffer.read_all()
+    if all_buffer:
+        memory_lines: list[str] = []
+        for key, value in all_buffer.items():
+            if value is None:
+                continue
+            val_str = str(value)
+            if len(val_str) > 200:
+                val_str = val_str[:200] + "..."
+            memory_lines.append(f"- {key}: {val_str}")
+        if memory_lines:
+            parts.append("Current state:\n" + "\n".join(memory_lines))
+
+    return "\n\n".join(parts) if parts else ""
+
+
+def build_transition_message(spec: TransitionSpec) -> str:
+    """Build a pure transition marker message."""
+    sections: list[str] = [
+        f"--- PHASE TRANSITION: {spec.previous_name} -> {spec.next_name} ---",
+        f"\nCompleted: {spec.previous_name}",
+        f"  {spec.previous_description}",
+    ]
+
+    if spec.buffer_items:
+        lines = [f"  {key}: {value}" for key, value in spec.buffer_items.items()]
+        sections.append("\nOutputs available:\n" + "\n".join(lines))
+
+    if spec.data_files:
+        sections.append(
+            "\nData files (use load_data to access):\n"
+            + "\n".join(f"  {entry}" for entry in spec.data_files)
+        )
+
+    if spec.cumulative_tool_names:
+        sections.append("\nAvailable tools: " + ", ".join(sorted(spec.cumulative_tool_names)))
+
+    sections.append(f"\nNow entering: {spec.next_name}")
+    sections.append(f"  {spec.next_description}")
+    if spec.next_output_keys:
+        sections.append(
+            f"\nYour ONLY job in this phase: complete the task above and call "
+            f"set_output() for {list(spec.next_output_keys)}. Do NOT do work that "
+            f"belongs to later phases."
+        )
+
+    sections.append(
+        "\nBefore proceeding, briefly reflect: what went well in the "
+        "previous phase? Are there any gaps or surprises worth noting?"
+    )
+    sections.append("\n--- END TRANSITION ---")
+    return "\n".join(sections)
+
+
+__all__ = [
+    "EXECUTION_SCOPE_PREAMBLE",
+    "NodePromptSpec",
+    "TransitionSpec",
+    "build_accounts_prompt",
+    "build_narrative",
+    "build_prompt_spec_from_node_context",
+    "build_system_prompt",
+    "build_system_prompt_for_node_context",
+    "build_transition_message",
+    "stamp_prompt_datetime",
+]
@@ -115,11 +115,23 @@ class SafeEvalVisitor(ast.NodeVisitor):
        return True

    def visit_BoolOp(self, node: ast.BoolOp) -> Any:
-        values = [self.visit(v) for v in node.values]
+        # Short-circuit evaluation to match Python semantics.
+        # Previously all operands were eagerly evaluated, which broke
+        # guard patterns like: ``x is not None and x.get("key")``
        if isinstance(node.op, ast.And):
-            return all(values)
+            result = True
+            for v in node.values:
+                result = self.visit(v)
+                if not result:
+                    return result
+            return result
        elif isinstance(node.op, ast.Or):
-            return any(values)
+            result = False
+            for v in node.values:
+                result = self.visit(v)
+                if result:
+                    return result
+            return result
        raise ValueError(f"Boolean operator {type(node.op).__name__} is not allowed")

    def visit_IfExp(self, node: ast.IfExp) -> Any:
@@ -216,10 +228,6 @@ class SafeEvalVisitor(ast.NodeVisitor):

        return func(*args, **keywords)

-    def visit_Index(self, node: ast.Index) -> Any:
-        # Python < 3.9
-        return self.visit(node.value)
-

 def safe_eval(expr: str, context: dict[str, Any] | None = None) -> Any:
    """
@@ -0,0 +1,898 @@
+"""
+WorkerAgent — First-class autonomous worker for event-driven graph execution.
+
+Each node in a graph becomes a WorkerAgent that:
+- Owns its lifecycle, retry logic, memory scope, and LLM config
+- Receives activations from upstream workers (via GraphExecutor routing)
+- Self-checks readiness (fan-out group tracking)
+- Self-triggers when ready
+- Evaluates outgoing edges and publishes activations for downstream workers
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+import uuid
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import Any
+
+from framework.graph.context import GraphContext, build_node_context_from_graph_context
+from framework.graph.edge import EdgeCondition, EdgeSpec
+from framework.graph.node import (
+    NodeContext,
+    NodeProtocol,
+    NodeResult,
+    NodeSpec,
+)
+from framework.graph.validator import OutputValidator
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Enums & data types
+# ---------------------------------------------------------------------------
+
+
+class WorkerLifecycle(StrEnum):
+    PENDING = "pending"
+    RUNNING = "running"
+    COMPLETED = "completed"
+    FAILED = "failed"
+
+
+@dataclass
+class FanOutTag:
+    """Carried in activations, propagated through the worker chain.
+
+    When a source activates multiple targets (fan-out), each activation
+    receives a FanOutTag.  Downstream convergence workers track these tags
+    to determine when all parallel branches have reached them.
+    """
+
+    fan_out_id: str  # Unique ID for this fan-out event
+    fan_out_source: str  # Node that performed the fan-out
+    branches: frozenset[str]  # All target node IDs in this fan-out
+    via_branch: str  # Which branch this activation passed through
+
+
+@dataclass
+class FanOutTracker:
+    """Per fan-out group, tracked by the target worker."""
+
+    fan_out_id: str
+    branches: frozenset[str]
+    reached: set[str] = field(default_factory=set)
+
+    @property
+    def is_complete(self) -> bool:
+        return self.reached == self.branches
+
+
+@dataclass
+class Activation:
+    """Payload sent from a completed source to a target worker."""
+
+    source_id: str
+    target_id: str
+    edge_id: str
+    edge: EdgeSpec
+    mapped_inputs: dict[str, Any]
+    fan_out_tags: list[FanOutTag] = field(default_factory=list)
+
+
+@dataclass
+class WorkerCompletion:
+    """Payload in WORKER_COMPLETED event."""
+
+    worker_id: str
+    success: bool
+    output: dict[str, Any]
+    tokens_used: int = 0
+    latency_ms: int = 0
+    conversation: Any = None  # NodeConversation for continuous mode
+    activations: list[Activation] = field(default_factory=list)
+
+
+@dataclass
+class RetryState:
+    attempt: int = 0
+    max_retries: int = 3
+    is_event_loop: bool = False
+
+
+# ---------------------------------------------------------------------------
+# WorkerAgent
+# ---------------------------------------------------------------------------
+
+
+class WorkerAgent:
+    """First-class autonomous worker for one node in the graph.
+
+    Lifecycle:
+        PENDING - waiting for activations
+        RUNNING - executing the node
+        COMPLETED- finished successfully, activations published
+        FAILED  - failed after retries exhausted
+    """
+
+    def __init__(
+        self,
+        node_spec: NodeSpec,
+        graph_context: GraphContext,
+    ) -> None:
+        self.node_spec = node_spec
+        self._gc = graph_context
+
+        # Edge topology (resolved at construction, immutable)
+        self.incoming_edges: list[EdgeSpec] = graph_context.graph.get_incoming_edges(node_spec.id)
+        self.outgoing_edges: list[EdgeSpec] = graph_context.graph.get_outgoing_edges(node_spec.id)
+
+        # Lifecycle
+        self.lifecycle: WorkerLifecycle = WorkerLifecycle.PENDING
+        self._task: asyncio.Task | None = None
+
+        # Retry state
+        self.retry_state = RetryState(
+            max_retries=node_spec.max_retries,
+            is_event_loop=node_spec.node_type == "event_loop",
+        )
+
+        # Activation tracking
+        self._inherited_fan_out_tags: list[FanOutTag] = []
+        self._active_fan_outs: dict[str, FanOutTracker] = {}
+        self._received_activations: list[Activation] = []
+        self._has_been_activated = False
+
+        # Pause support
+        # _run_gate controls whether worker execution may proceed.
+        # _pause_requested mirrors the pause-request semantics expected by
+        # EventLoopNode, where is_set() means "pause requested".
+        self._run_gate: asyncio.Event = asyncio.Event()
+        self._run_gate.set()  # Not paused by default
+        self._pause_requested: asyncio.Event = asyncio.Event()
+
+        # Validator
+        self._validator = OutputValidator()
+
+        # Node implementation (lazy)
+        self._node_impl: NodeProtocol | None = None
+
+        # Metrics for this worker
+        self._tokens_used: int = 0
+        self._latency_ms: int = 0
+
+        # Last execution result (accessible by polling executor)
+        self._last_result: NodeResult | None = None
+        self._last_activations: list[Activation] = []
+
+    # ------------------------------------------------------------------
+    # Public activation interface
+    # ------------------------------------------------------------------
+
+    def activate(self, inherited_tags: list[FanOutTag] | None = None) -> None:
+        """Activate this worker — launch execution as an asyncio.Task."""
+        if self.lifecycle != WorkerLifecycle.PENDING:
+            return
+
+        self._inherited_fan_out_tags = inherited_tags or []
+        self._has_been_activated = True
+        self.lifecycle = WorkerLifecycle.RUNNING
+        self._task = asyncio.ensure_future(self._execute_self())
+
+    def receive_activation(self, activation: Activation) -> None:
+        """Receive an activation from an upstream worker.
+
+        Called by GraphExecutor when routing a WORKER_COMPLETED event's
+        activations to their target workers.
+        """
+        if self.lifecycle != WorkerLifecycle.PENDING:
+            return
+
+        self._received_activations.append(activation)
+
+        # Update fan-out trackers from this activation's tags.
+        # Skip tags where this worker IS the via_branch — those tags exist
+        # for downstream convergence tracking, not for gating this worker.
+        for tag in activation.fan_out_tags:
+            if tag.via_branch == self.node_spec.id:
+                continue
+            if tag.fan_out_id not in self._active_fan_outs:
+                self._active_fan_outs[tag.fan_out_id] = FanOutTracker(
+                    fan_out_id=tag.fan_out_id,
+                    branches=tag.branches,
+                )
+            self._active_fan_outs[tag.fan_out_id].reached.add(tag.via_branch)
+
+    def check_readiness(self) -> bool:
+        """Check if all fan-out groups have been satisfied."""
+        if self._has_been_activated:
+            return True
+        if not self._active_fan_outs:
+            # No fan-out tracking — ready on first activation
+            return bool(self._received_activations)
+        return all(t.is_complete for t in self._active_fan_outs.values())
+
+    def reset_for_revisit(self) -> None:
+        """Reset a completed worker so it can execute again (feedback loops).
+
+        Preserves the node implementation (cached) but clears lifecycle,
+        activation, and result state.
+        """
+        self.lifecycle = WorkerLifecycle.PENDING
+        self._inherited_fan_out_tags = []
+        self._active_fan_outs = {}
+        self._received_activations = []
+        self._has_been_activated = False
+        self._task = None
+        self._last_result = None
+        self._last_activations = []
+        self._tokens_used = 0
+        self._latency_ms = 0
+
+    # ------------------------------------------------------------------
+    # Execution
+    # ------------------------------------------------------------------
+
+    async def _execute_self(self) -> None:
+        """Main execution loop: run node, handle retries, publish result."""
+        gc = self._gc
+        node_spec = self.node_spec
+        try:
+            # Write all mapped inputs from received activations to buffer
+            for activation in self._received_activations:
+                for key, value in activation.mapped_inputs.items():
+                    gc.buffer.write(key, value, validate=False)
+
+            # Increment visit count (always, even if skipped)
+            async with gc._visits_lock:
+                visit_count = gc.node_visit_counts.get(node_spec.id, 0) + 1
+                gc.node_visit_counts[node_spec.id] = visit_count
+
+            # Check max_node_visits — skip execution but still propagate edges
+            if node_spec.max_node_visits > 0 and visit_count > node_spec.max_node_visits:
+                logger.info(
+                    "Worker %s: visit %d exceeds max_node_visits=%d, skipping",
+                    node_spec.id, visit_count, node_spec.max_node_visits,
+                )
+                # Build a synthetic success result from current buffer state
+                existing_output: dict[str, Any] = {}
+                for key in node_spec.output_keys:
+                    val = gc.buffer.read(key)
+                    if val is not None:
+                        existing_output[key] = val
+
+                result = NodeResult(success=True, output=existing_output)
+
+                # Evaluate outgoing edges so the cycle continues
+                activations = await self._evaluate_outgoing_edges(result)
+
+                self.lifecycle = WorkerLifecycle.COMPLETED
+                self._last_result = result
+                self._last_activations = activations
+                return
+
+            # Clear stale nullable outputs on re-visit
+            if visit_count > 1:
+                nullable_keys = getattr(node_spec, "nullable_output_keys", None) or []
+                for key in nullable_keys:
+                    if gc.buffer.read(key) is not None:
+                        gc.buffer.write(key, None, validate=False)
+
+            # Continuous mode: accumulate tools and output keys
+            if gc.is_continuous and node_spec.tools:
+                for t in gc.tools:
+                    if t.name in node_spec.tools and t.name not in gc.cumulative_tool_names:
+                        gc.cumulative_tools.append(t)
+                        gc.cumulative_tool_names.add(t.name)
+            if gc.is_continuous and node_spec.output_keys:
+                for k in node_spec.output_keys:
+                    if k not in gc.cumulative_output_keys:
+                        gc.cumulative_output_keys.append(k)
+
+            # Append to execution path
+            async with gc._path_lock:
+                gc.path.append(node_spec.id)
+
+            # Get node implementation
+            node_impl = self._get_node_implementation()
+
+            # Build context
+            ctx = self._build_node_context()
+
+            # Execute with retry
+            result = await self._execute_with_retries(node_impl, ctx)
+
+            # Handle result
+            if result.success:
+                # Validate and write outputs
+                self._write_outputs(result)
+
+                # Evaluate outgoing edges
+                activations = await self._evaluate_outgoing_edges(result)
+
+                # Publish completion
+                self.lifecycle = WorkerLifecycle.COMPLETED
+                self._last_result = result
+                self._last_activations = activations
+                # Colony memory reflection — runs before downstream activation
+                await self._reflect_colony_memory()
+                completion = WorkerCompletion(
+                    worker_id=node_spec.id,
+                    success=True,
+                    output=result.output,
+                    tokens_used=result.tokens_used,
+                    latency_ms=result.latency_ms,
+                    conversation=result.conversation,
+                    activations=activations,
+                )
+                if gc.is_continuous and completion.conversation is not None:
+                    gc.continuous_conversation = completion.conversation
+                    await self._apply_continuous_transition(completion.activations)
+                await self._publish_completion(completion)
+            else:
+                # Evaluate outgoing edges even on failure (ON_FAILURE edges)
+                activations = await self._evaluate_outgoing_edges(result)
+
+                self.lifecycle = WorkerLifecycle.FAILED
+                self._last_result = result
+                self._last_activations = activations
+                # Colony memory reflection — capture learnings even on failure
+                await self._reflect_colony_memory()
+                await self._publish_failure(result.error or "Unknown error")
+        except Exception as exc:
+            error = str(exc) or type(exc).__name__
+            logger.exception("Worker %s crashed during execution", node_spec.id)
+            self.lifecycle = WorkerLifecycle.FAILED
+            self._last_result = NodeResult(success=False, error=error)
+            self._last_activations = []
+            await self._publish_failure(error)
+
+    async def _execute_with_retries(
+        self, node_impl: NodeProtocol, ctx: NodeContext
+    ) -> NodeResult:
+        """Execute node with exponential backoff retry."""
+        gc = self._gc
+        # Only skip retries for actual EventLoopNode instances (they handle
+        # retries internally).  Custom NodeProtocol impls registered via
+        # register_node should be retried by the executor.
+        from framework.graph.event_loop_node import EventLoopNode as _ELN
+        if isinstance(node_impl, _ELN):
+            max_retries = 0
+        else:
+            max_retries = self.retry_state.max_retries
+
+        total_attempts = max(1, max_retries)
+        for attempt in range(total_attempts):
+            # Check pause
+            await self._run_gate.wait()
+
+            ctx.attempt = attempt + 1
+            start = time.monotonic()
+
+            try:
+                result = await node_impl.execute(ctx)
+                result.latency_ms = int((time.monotonic() - start) * 1000)
+
+                if result.success:
+                    return result
+
+                # Failure
+                if attempt + 1 < total_attempts:
+                    gc.retry_counts[self.node_spec.id] = gc.retry_counts.get(self.node_spec.id, 0) + 1
+                    gc.nodes_with_retries.add(self.node_spec.id)
+                    delay = 1.0 * (2**attempt)
+                    logger.warning(
+                        "Worker %s failed (attempt %d/%d), retrying in %.1fs: %s",
+                        self.node_spec.id,
+                        attempt + 1,
+                        max_retries,
+                        delay,
+                        result.error,
+                    )
+                    # Emit retry event
+                    if gc.event_bus:
+                        await gc.event_bus.emit_node_retry(
+                            stream_id=gc.stream_id,
+                            node_id=self.node_spec.id,
+                            attempt=attempt + 1,
+                            max_retries=max_retries,
+                            execution_id=gc.execution_id,
+                        )
+                    await asyncio.sleep(delay)
+                    continue
+                else:
+                    return NodeResult(
+                        success=False,
+                        error=f"failed after {attempt + 1} attempts: {result.error}",
+                    )
+
+            except Exception as exc:
+                if attempt + 1 < total_attempts:
+                    gc.retry_counts[self.node_spec.id] = gc.retry_counts.get(self.node_spec.id, 0) + 1
+                    gc.nodes_with_retries.add(self.node_spec.id)
+                    delay = 1.0 * (2**attempt)
+                    logger.warning(
+                        "Worker %s raised %s (attempt %d/%d), retrying in %.1fs",
+                        self.node_spec.id,
+                        type(exc).__name__,
+                        attempt + 1,
+                        max(1, max_retries),
+                        delay,
+                    )
+                    await asyncio.sleep(delay)
+                    continue
+                return NodeResult(
+                    success=False,
+                    error=f"failed after {attempt + 1} attempts: {exc}",
+                )
+
+        return NodeResult(
+            success=False,
+            error=f"failed after {max(1, max_retries)} attempts",
+        )
+
+    # ------------------------------------------------------------------
+    # Edge evaluation (source-side)
+    # ------------------------------------------------------------------
+
+    async def _evaluate_outgoing_edges(
+        self, result: NodeResult
+    ) -> list[Activation]:
+        """Evaluate outgoing edges and create activations for downstream.
+
+        Same logic as current _get_all_traversable_edges() plus
+        priority filtering for CONDITIONAL edges.
+        """
+        gc = self._gc
+        edges = gc.graph.get_outgoing_edges(self.node_spec.id)
+
+        traversable: list[EdgeSpec] = []
+        for edge in edges:
+            target_spec = gc.graph.get_node(edge.target)
+            if await edge.should_traverse(
+                source_success=result.success,
+                source_output=result.output,
+                buffer_data=gc.buffer.read_all(),
+                llm=gc.llm,
+                goal=gc.goal,
+                source_node_name=self.node_spec.name,
+                target_node_name=target_spec.name if target_spec else edge.target,
+            ):
+                traversable.append(edge)
+
+        # Priority filtering for CONDITIONAL edges
+        if len(traversable) > 1:
+            conditionals = [e for e in traversable if e.condition == EdgeCondition.CONDITIONAL]
+            if len(conditionals) > 1:
+                max_prio = max(e.priority for e in conditionals)
+                traversable = [
+                    e
+                    for e in traversable
+                    if e.condition != EdgeCondition.CONDITIONAL or e.priority == max_prio
+                ]
+
+        # When parallel execution is disabled, follow first match only (sequential)
+        if not gc.enable_parallel_execution and len(traversable) > 1:
+            traversable = traversable[:1]
+
+        # Build activations
+        is_fan_out = len(traversable) > 1
+        fan_out_id = f"{self.node_spec.id}_{uuid.uuid4().hex[:8]}" if is_fan_out else None
+
+        activations: list[Activation] = []
+        for edge in traversable:
+            mapped = edge.map_inputs(result.output, gc.buffer.read_all())
+
+            # Build fan-out tags: inherited + new
+            tags = list(self._inherited_fan_out_tags)
+            if is_fan_out:
+                tags.append(
+                    FanOutTag(
+                        fan_out_id=fan_out_id,
+                        fan_out_source=self.node_spec.id,
+                        branches=frozenset(e.target for e in traversable),
+                        via_branch=edge.target,
+                    )
+                )
+
+            activations.append(
+                Activation(
+                    source_id=self.node_spec.id,
+                    target_id=edge.target,
+                    edge_id=edge.id,
+                    edge=edge,
+                    mapped_inputs=mapped,
+                    fan_out_tags=tags,
+                )
+            )
+
+        if traversable:
+            logger.info(
+                "Worker %s → %d outgoing activation(s)%s",
+                self.node_spec.id,
+                len(activations),
+                f" (fan-out: {[a.target_id for a in activations]})" if is_fan_out else "",
+            )
+
+        return activations
+
+    # ------------------------------------------------------------------
+    # Output handling
+    # ------------------------------------------------------------------
+
+    def _write_outputs(self, result: NodeResult) -> None:
+        """Validate and write node outputs to buffer."""
+        gc = self._gc
+        node_spec = self.node_spec
+
+        # Event loop nodes skip executor-level validation (judge is the authority)
+        if node_spec.node_type != "event_loop":
+            errors = self._validator.validate_all(
+                output=result.output,
+                output_keys=node_spec.output_keys,
+                nullable_keys=getattr(node_spec, "nullable_output_keys", []) or [],
+                output_schema=getattr(node_spec, "output_schema", None),
+                output_model=getattr(node_spec, "output_model", None),
+            )
+            if errors:
+                logger.warning("Worker %s output validation warnings: %s", node_spec.id, errors)
+
+        # Determine if this worker is a fan-out branch
+        is_fanout_branch = any(
+            tag.via_branch == node_spec.id for tag in self._inherited_fan_out_tags
+        )
+
+        # Collect keys to write: declared output_keys + any extra output items
+        # (for fan-out branches, all output items need conflict checking)
+        keys_to_write: set[str] = set(node_spec.output_keys)
+        if is_fanout_branch:
+            keys_to_write |= set(result.output.keys())
+
+        # Write all keys to buffer
+        for key in keys_to_write:
+            value = result.output.get(key)
+            if value is not None:
+                if is_fanout_branch:
+                    conflict_strategy = (
+                        getattr(gc.parallel_config, "buffer_conflict_strategy", "last_wins")
+                        if gc.parallel_config
+                        else "last_wins"
+                    )
+                    prior_worker = gc._fanout_written_keys.get(key)
+                    if prior_worker and prior_worker != node_spec.id:
+                        if conflict_strategy == "error":
+                            raise RuntimeError(
+                                f"Buffer write failed (conflict): key '{key}' already written "
+                                f"by worker '{prior_worker}', "
+                                f"conflicting write from '{node_spec.id}'"
+                            )
+                        elif conflict_strategy == "first_wins":
+                            logger.debug(
+                                "Skipping write to '%s' (first_wins: already set by %s)",
+                                key, prior_worker,
+                            )
+                            continue
+                        else:
+                            # last_wins: log and overwrite
+                            logger.debug(
+                                "Key '%s' overwritten (last_wins: %s -> %s)",
+                                key, prior_worker, node_spec.id,
+                            )
+                    gc._fanout_written_keys[key] = node_spec.id
+                gc.buffer.write(key, value, validate=False)
+
+    # ------------------------------------------------------------------
+    # Context building
+    # ------------------------------------------------------------------
+
+    def _get_node_implementation(self) -> NodeProtocol:
+        """Get or create node implementation."""
+        gc = self._gc
+        if self._node_impl is not None:
+            return self._node_impl
+
+        # Check shared registry first
+        if self.node_spec.id in gc.node_registry:
+            self._node_impl = gc.node_registry[self.node_spec.id]
+            return self._node_impl
+
+        # Auto-create EventLoopNode
+        if self.node_spec.node_type in ("event_loop", "gcu"):
+            from framework.graph.event_loop_node import EventLoopNode
+            from framework.graph.event_loop.types import LoopConfig
+            from framework.graph.node import warn_if_deprecated_client_facing
+
+            conv_store = None
+            if gc.storage_path:
+                from framework.storage.conversation_store import FileConversationStore
+
+                conv_store = FileConversationStore(base_path=gc.storage_path / "conversations")
+
+            spillover = str(gc.storage_path / "data") if gc.storage_path else None
+            lc = gc.loop_config
+            warn_if_deprecated_client_facing(self.node_spec)
+            default_max_iter = 100 if self.node_spec.supports_direct_user_io() else 50
+
+            node = EventLoopNode(
+                event_bus=gc.event_bus,
+                judge=None,
+                config=LoopConfig(
+                    max_iterations=lc.get("max_iterations", default_max_iter),
+                    max_tool_calls_per_turn=lc.get("max_tool_calls_per_turn", 30),
+                    tool_call_overflow_margin=lc.get("tool_call_overflow_margin", 0.5),
+                    stall_detection_threshold=lc.get("stall_detection_threshold", 3),
+                    max_context_tokens=lc.get(
+                        "max_context_tokens",
+                        _default_max_context_tokens(),
+                    ),
+                    max_tool_result_chars=lc.get("max_tool_result_chars", 30_000),
+                    spillover_dir=spillover,
+                    hooks=lc.get("hooks", {}),
+                ),
+                tool_executor=gc.tool_executor,
+                conversation_store=conv_store,
+            )
+            gc.node_registry[self.node_spec.id] = node
+            self._node_impl = node
+            return node
+
+        raise RuntimeError(
+            f"No implementation for node '{self.node_spec.id}' "
+            f"(type: {self.node_spec.node_type})"
+        )
+
+    def _build_node_context(self) -> NodeContext:
+        """Build NodeContext for this worker's execution."""
+        return build_node_context_from_graph_context(
+            self._gc,
+            node_spec=self.node_spec,
+            pause_event=self._pause_requested,
+        )
+
+    async def _reflect_colony_memory(self) -> None:
+        """Run colony memory reflection at node handoff.
+
+        Awaits the shared colony lock so parallel workers queue (never skip).
+        """
+        gc = self._gc
+        if gc.colony_memory_dir is None or gc.colony_reflect_llm is None:
+            return
+        if gc.worker_sessions_dir is None:
+            return
+
+        from pathlib import Path
+
+        session_dir = Path(gc.worker_sessions_dir) / gc.execution_id
+        if not session_dir.exists():
+            return
+
+        # Await lock — serializes reflection but never skips
+        async with gc._colony_reflect_lock:
+            try:
+                from framework.agents.queen.reflection_agent import run_short_reflection
+
+                await run_short_reflection(
+                    session_dir, gc.colony_reflect_llm, gc.colony_memory_dir
+                )
+            except Exception:
+                logger.warning(
+                    "Worker %s: colony reflection failed",
+                    self.node_spec.id,
+                    exc_info=True,
+                )
+
+        # Update recall cache outside lock (per-execution key, no write races)
+        try:
+            from framework.agents.queen.recall_selector import update_recall_cache
+
+            await update_recall_cache(
+                session_dir,
+                gc.colony_reflect_llm,
+                memory_dir=gc.colony_memory_dir,
+                cache_setter=lambda block: gc.colony_recall_cache.__setitem__(
+                    gc.execution_id, block
+                ),
+                heading="Colony Memories",
+            )
+        except Exception:
+            logger.warning(
+                "Worker %s: recall cache update failed",
+                self.node_spec.id,
+                exc_info=True,
+            )
+
+    # ------------------------------------------------------------------
+    # Event publishing
+    # ------------------------------------------------------------------
+
+    async def _publish_completion(self, completion: WorkerCompletion) -> None:
+        """Publish WORKER_COMPLETED event via the graph-scoped event bus."""
+        gc = self._gc
+        if not gc.event_bus:
+            return
+        if not hasattr(gc.event_bus, "emit_worker_completed"):
+            return
+
+        # Serialize activations to dicts for event data
+        activations_data = []
+        for act in completion.activations:
+            activations_data.append({
+                "source_id": act.source_id,
+                "target_id": act.target_id,
+                "edge_id": act.edge_id,
+                "mapped_inputs": act.mapped_inputs,
+                "fan_out_tags": [
+                    {
+                        "fan_out_id": t.fan_out_id,
+                        "fan_out_source": t.fan_out_source,
+                        "branches": list(t.branches),
+                        "via_branch": t.via_branch,
+                    }
+                    for t in act.fan_out_tags
+                ],
+            })
+
+        await gc.event_bus.emit_worker_completed(
+            stream_id=gc.stream_id,
+            node_id=self.node_spec.id,
+            worker_id=self.node_spec.id,
+            success=completion.success,
+            output=completion.output,
+            activations=activations_data,
+            execution_id=gc.execution_id,
+            tokens_used=completion.tokens_used,
+            latency_ms=completion.latency_ms,
+            conversation=completion.conversation,
+        )
+
+    async def _publish_failure(self, error: str) -> None:
+        """Publish WORKER_FAILED event."""
+        gc = self._gc
+        if not gc.event_bus:
+            return
+        if not hasattr(gc.event_bus, "emit_worker_failed"):
+            return
+
+        await gc.event_bus.emit_worker_failed(
+            stream_id=gc.stream_id,
+            node_id=self.node_spec.id,
+            worker_id=self.node_spec.id,
+            error=error,
+            execution_id=gc.execution_id,
+        )
+
+    async def _apply_continuous_transition(self, activations: list[Activation]) -> None:
+        """Apply continuous mode conversation threading for the next node.
+
+        This prepares the inherited conversation before the completion event
+        is published so downstream workers receive a fully updated thread.
+        """
+        gc = self._gc
+        if not gc.is_continuous or not gc.continuous_conversation:
+            return
+
+        next_node_id = next((activation.target_id for activation in activations), None)
+        if not next_node_id:
+            return
+
+        next_spec = gc.graph.get_node(next_node_id)
+        if not next_spec or next_spec.node_type != "event_loop":
+            return
+
+        from framework.graph.prompting import (
+            TransitionSpec,
+            build_narrative,
+            build_system_prompt_for_node_context,
+            build_transition_message,
+        )
+
+        narrative = build_narrative(gc.buffer, gc.path, gc.graph)
+        next_ctx = build_node_context_from_graph_context(
+            gc,
+            node_spec=next_spec,
+            pause_event=self._pause_requested,
+            inherited_conversation=gc.continuous_conversation,
+            narrative=narrative,
+        )
+        gc.continuous_conversation.update_system_prompt(
+            build_system_prompt_for_node_context(next_ctx)
+        )
+        gc.continuous_conversation.set_current_phase(next_spec.id)
+
+        buffer_items, data_files = self._prepare_transition_payload()
+        marker = build_transition_message(
+            TransitionSpec(
+                previous_name=self.node_spec.name,
+                previous_description=self.node_spec.description,
+                next_name=next_spec.name,
+                next_description=next_spec.description,
+                next_output_keys=tuple(next_spec.output_keys or ()),
+                buffer_items=buffer_items,
+                cumulative_tool_names=tuple(sorted(gc.cumulative_tool_names)),
+                data_files=tuple(data_files),
+            )
+        )
+        await gc.continuous_conversation.add_user_message(
+            marker,
+            is_transition_marker=True,
+        )
+
+    def _prepare_transition_payload(self) -> tuple[dict[str, str], list[str]]:
+        """Build transition marker data and spill oversized values when possible."""
+        import json
+        from pathlib import Path
+
+        gc = self._gc
+        data_dir = Path(gc.storage_path / "data") if gc.storage_path else None
+        buffer_items: dict[str, str] = {}
+
+        for key, value in gc.buffer.read_all().items():
+            if value is None:
+                continue
+            val_str = str(value)
+            if len(val_str) > 300 and data_dir is not None:
+                data_dir.mkdir(parents=True, exist_ok=True)
+                ext = ".json" if isinstance(value, (dict, list)) else ".txt"
+                filename = f"output_{key}{ext}"
+                file_path = data_dir / filename
+                try:
+                    write_content = (
+                        json.dumps(value, indent=2, ensure_ascii=False)
+                        if isinstance(value, (dict, list))
+                        else str(value)
+                    )
+                    file_path.write_text(write_content, encoding="utf-8")
+                    file_size = file_path.stat().st_size
+                    buffer_items[key] = (
+                        f"[Saved to '{filename}' ({file_size:,} bytes). "
+                        f"Use load_data(filename='{filename}') to access.]"
+                    )
+                    continue
+                except Exception:
+                    pass
+
+            buffer_items[key] = val_str[:300] + "..." if len(val_str) > 300 else val_str
+
+        data_files: list[str] = []
+        if data_dir is not None and data_dir.exists():
+            data_files = [
+                f"{entry.name} ({entry.stat().st_size:,} bytes)"
+                for entry in sorted(data_dir.iterdir())
+                if entry.is_file()
+            ]
+
+        return buffer_items, data_files
+
+    # ------------------------------------------------------------------
+    # Utility
+    # ------------------------------------------------------------------
+
+    def pause(self) -> None:
+        self._pause_requested.set()
+        self._run_gate.clear()
+
+    def resume(self) -> None:
+        self._pause_requested.clear()
+        self._run_gate.set()
+
+    @property
+    def is_terminal(self) -> bool:
+        return self.node_spec.id in (self._gc.graph.terminal_nodes or [])
+
+    @property
+    def is_entry(self) -> bool:
+        return len(self.incoming_edges) == 0
+
+
+def _default_max_context_tokens() -> int:
+    """Resolve max_context_tokens from global config, falling back to 32000."""
+    try:
+        from framework.config import get_max_context_tokens  # type: ignore[import-untyped]
+
+        return get_max_context_tokens()
+    except Exception:
+        return 32_000
@@ -0,0 +1,706 @@
+"""Antigravity (Google internal Cloud Code Assist) LLM provider.
+
+Antigravity is Google's unified gateway API that routes requests to Gemini,
+Claude, and GPT-OSS models through a single Gemini-style interface.  It is
+NOT the public ``generativelanguage.googleapis.com`` API.
+
+Authentication uses Google OAuth2.  Token refresh is done directly with the
+OAuth client secret — no local proxy required.
+
+Credential sources (checked in order):
+  1. ``~/.hive/antigravity-accounts.json`` (native OAuth implementation)
+  2. Antigravity IDE SQLite state DB (macOS / Linux)
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+import time
+import uuid
+from collections.abc import AsyncIterator, Callable, Iterator
+from pathlib import Path
+from typing import Any
+
+from framework.llm.provider import LLMProvider, LLMResponse, Tool
+from framework.llm.stream_events import (
+    FinishEvent,
+    StreamErrorEvent,
+    StreamEvent,
+    TextDeltaEvent,
+    TextEndEvent,
+    ToolCallEvent,
+)
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+_TOKEN_URL = "https://oauth2.googleapis.com/token"
+
+# Fallback order: daily sandbox → autopush sandbox → production
+_ENDPOINTS = [
+    "https://daily-cloudcode-pa.sandbox.googleapis.com",
+    "https://autopush-cloudcode-pa.sandbox.googleapis.com",
+    "https://cloudcode-pa.googleapis.com",
+]
+_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"
+_IDE_STATE_DB_MAC = (
+    Path.home()
+    / "Library"
+    / "Application Support"
+    / "Antigravity"
+    / "User"
+    / "globalStorage"
+    / "state.vscdb"
+)
+_IDE_STATE_DB_LINUX = (
+    Path.home() / ".config" / "Antigravity" / "User" / "globalStorage" / "state.vscdb"
+)
+_IDE_STATE_DB_KEY = "antigravityUnifiedStateSync.oauthToken"
+
+_BASE_HEADERS: dict[str, str] = {
+    # Mimic the Antigravity Electron app so the API accepts the request.
+    "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"
+    ),
+    "X-Goog-Api-Client": "google-cloud-sdk vscode_cloudshelleditor/0.1",
+    "Client-Metadata": '{"ideType":"ANTIGRAVITY","platform":"MACOS","pluginType":"GEMINI"}',
+}
+
+
+# ---------------------------------------------------------------------------
+# Credential loading helpers
+# ---------------------------------------------------------------------------
+
+
+def _load_from_json_file() -> tuple[str | None, str | None, str, float]:
+    """Read credentials from JSON accounts file.
+
+    Reads from ~/.hive/antigravity-accounts.json.
+
+    Returns ``(access_token | None, refresh_token | None, project_id, expires_at)``.
+    ``expires_at`` is a Unix timestamp (seconds); 0.0 means unknown.
+    """
+    if not _ACCOUNTS_FILE.exists():
+        return None, None, _DEFAULT_PROJECT_ID, 0.0
+    try:
+        with open(_ACCOUNTS_FILE, encoding="utf-8") as fh:
+            data = json.load(fh)
+    except (OSError, json.JSONDecodeError) as exc:
+        logger.debug("Failed to read Antigravity accounts file: %s", exc)
+        return None, None, _DEFAULT_PROJECT_ID, 0.0
+
+    accounts = data.get("accounts", [])
+    if not accounts:
+        return None, None, _DEFAULT_PROJECT_ID, 0.0
+
+    account = next((a for a in accounts if a.get("enabled", True) is not False), accounts[0])
+    schema_version = data.get("schemaVersion", 1)
+
+    if schema_version >= 4:
+        # V4 schema: refresh = "refreshToken|projectId[|managedProjectId]"
+        refresh_str = account.get("refresh", "")
+        parts = refresh_str.split("|") if refresh_str else []
+        refresh_token: str | None = parts[0] if parts else None
+        project_id = parts[1] if len(parts) >= 2 and parts[1] else _DEFAULT_PROJECT_ID
+
+        access_token: str | None = account.get("access")
+        expires_ms: int = account.get("expires", 0)
+        expires_at = float(expires_ms) / 1000.0 if expires_ms else 0.0
+
+        # Treat near-expiry tokens as absent so _ensure_token() triggers a refresh.
+        if access_token and expires_at and time.time() >= expires_at - _TOKEN_REFRESH_BUFFER_SECS:
+            access_token = None
+            expires_at = 0.0
+
+        return access_token, refresh_token, project_id, expires_at
+    else:
+        # V1–V3 schema: plain accessToken / refreshToken fields
+        access_token = account.get("accessToken")
+        refresh_token = account.get("refreshToken")
+        # Estimate expiry from last_refresh + 1 h
+        last_refresh_str: str | None = data.get("last_refresh")
+        expires_at = 0.0
+        if last_refresh_str:
+            try:
+                from datetime import datetime  # noqa: PLC0415
+
+                ts = datetime.fromisoformat(last_refresh_str.replace("Z", "+00:00")).timestamp()
+                expires_at = ts + 3600.0
+                if time.time() >= expires_at - _TOKEN_REFRESH_BUFFER_SECS:
+                    access_token = None
+            except (ValueError, TypeError):
+                pass
+        return access_token, refresh_token, _DEFAULT_PROJECT_ID, expires_at
+
+
+def _load_from_ide_db() -> tuple[str | None, str | None, float]:
+    """Extract ``(access_token, refresh_token, expires_at)`` from the IDE SQLite DB."""
+    import base64  # noqa: PLC0415
+    import sqlite3  # noqa: PLC0415
+
+    for db_path in (_IDE_STATE_DB_MAC, _IDE_STATE_DB_LINUX):
+        if not db_path.exists():
+            continue
+        try:
+            con = sqlite3.connect(f"file:{db_path}?mode=ro", uri=True)
+            try:
+                row = con.execute(
+                    "SELECT value FROM ItemTable WHERE key = ?",
+                    (_IDE_STATE_DB_KEY,),
+                ).fetchone()
+            finally:
+                con.close()
+            if not row:
+                continue
+
+            blob = base64.b64decode(row[0])
+            candidates = re.findall(rb"[A-Za-z0-9+/=_\-]{40,}", blob)
+            access_token: str | None = None
+            refresh_token: str | None = None
+            for candidate in candidates:
+                try:
+                    padded = candidate + b"=" * (-len(candidate) % 4)
+                    inner = base64.urlsafe_b64decode(padded)
+                except Exception:
+                    continue
+                if not access_token:
+                    m = re.search(rb"ya29\.[A-Za-z0-9_\-\.]+", inner)
+                    if m:
+                        access_token = m.group(0).decode("ascii")
+                if not refresh_token:
+                    m = re.search(rb"1//[A-Za-z0-9_\-\.]+", inner)
+                    if m:
+                        refresh_token = m.group(0).decode("ascii")
+                if access_token and refresh_token:
+                    break
+
+            if access_token:
+                # Estimate expiry from DB mtime (IDE refreshes while running)
+                mtime = db_path.stat().st_mtime
+                expires_at = mtime + 3600.0
+                return access_token, refresh_token, expires_at
+        except Exception as exc:
+            logger.debug("Failed to read Antigravity IDE state DB: %s", exc)
+            continue
+    return None, None, 0.0
+
+
+def _do_token_refresh(refresh_token: str) -> tuple[str, float] | None:
+    """POST to Google OAuth endpoint and return ``(new_access_token, expires_at)``.
+
+    The client secret is sourced via ``get_antigravity_client_secret()`` (env var,
+    config file, or npm package fallback). When unavailable the refresh is attempted
+    without it — Google will reject it for web-app clients, but the npm fallback in
+    ``get_antigravity_client_secret()`` should ensure the secret is found at runtime.
+
+    Returns None when the HTTP request fails.
+    """
+    from framework.config import get_antigravity_client_secret  # noqa: PLC0415
+
+    client_secret = get_antigravity_client_secret()
+    if not client_secret:
+        logger.debug(
+            "Antigravity client secret not configured — attempting refresh without it. "
+            "Set ANTIGRAVITY_CLIENT_SECRET or run quickstart to configure."
+        )
+
+    import urllib.error  # noqa: PLC0415
+    import urllib.parse  # noqa: PLC0415
+    import urllib.request  # noqa: PLC0415
+
+    from framework.config import get_antigravity_client_id  # noqa: PLC0415
+
+    params: dict[str, str] = {
+        "grant_type": "refresh_token",
+        "refresh_token": refresh_token,
+        "client_id": get_antigravity_client_id(),
+    }
+    if client_secret:
+        params["client_secret"] = client_secret
+    body = urllib.parse.urlencode(params).encode("utf-8")
+
+    req = urllib.request.Request(
+        _TOKEN_URL,
+        data=body,
+        headers={"Content-Type": "application/x-www-form-urlencoded"},
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=15) as resp:  # noqa: S310
+            payload = json.loads(resp.read())
+        access_token: str = payload["access_token"]
+        expires_in: int = payload.get("expires_in", 3600)
+        logger.debug("Antigravity token refreshed successfully")
+        return access_token, time.time() + expires_in
+    except Exception as exc:
+        logger.debug("Antigravity token refresh failed: %s", exc)
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Message conversion helpers
+# ---------------------------------------------------------------------------
+
+
+def _clean_tool_name(name: str) -> str:
+    """Sanitize a tool name for the Antigravity function-calling schema."""
+    name = re.sub(r"[/\s]", "_", name)
+    if name and not (name[0].isalpha() or name[0] == "_"):
+        name = "_" + name
+    return name[:64]
+
+
+def _to_gemini_contents(
+    messages: list[dict[str, Any]],
+    thought_sigs: dict[str, str] | None = None,
+) -> list[dict[str, Any]]:
+    """Convert OpenAI-format messages to Gemini-style ``contents`` array."""
+    # Pre-build a map tool_call_id → function_name from assistant messages.
+    # Tool result messages (role="tool") only carry tool_call_id, not the name,
+    # but Gemini requires functionResponse.name to match the functionCall.name.
+    tc_id_to_name: dict[str, str] = {}
+    for msg in messages:
+        if msg.get("role") == "assistant":
+            for tc in msg.get("tool_calls") or []:
+                tc_id = tc.get("id")
+                fn_name = tc.get("function", {}).get("name", "")
+                if tc_id and fn_name:
+                    tc_id_to_name[tc_id] = fn_name
+
+    contents: list[dict[str, Any]] = []
+    # Consecutive tool-result messages must be batched into one user turn.
+    pending_tool_parts: list[dict[str, Any]] = []
+
+    def _flush_tool_results() -> None:
+        if pending_tool_parts:
+            contents.append({"role": "user", "parts": list(pending_tool_parts)})
+            pending_tool_parts.clear()
+
+    for msg in messages:
+        role = msg.get("role", "user")
+        content = msg.get("content")
+
+        if role == "system":
+            continue  # Handled via systemInstruction, not in contents.
+
+        if role == "tool":
+            # OpenAI tool result → Gemini functionResponse part.
+            result_str = content if isinstance(content, str) else str(content or "")
+            tc_id = msg.get("tool_call_id", "")
+            # Look up function name from the pre-built map; fall back to msg.name.
+            fn_name = tc_id_to_name.get(tc_id) or msg.get("name", "")
+            pending_tool_parts.append(
+                {
+                    "functionResponse": {
+                        "name": fn_name,
+                        "id": tc_id,
+                        "response": {"content": result_str},
+                    }
+                }
+            )
+            continue
+
+        _flush_tool_results()
+
+        gemini_role = "model" if role == "assistant" else "user"
+        parts: list[dict[str, Any]] = []
+
+        if isinstance(content, str) and content:
+            parts.append({"text": content})
+        elif isinstance(content, list):
+            for block in content:
+                if not isinstance(block, dict):
+                    continue
+                if block.get("type") == "text":
+                    text = block.get("text", "")
+                    if text:
+                        parts.append({"text": text})
+                # Other block types (image_url etc.) skipped.
+
+        # Assistant messages may carry OpenAI-style tool_calls.
+        for tc in msg.get("tool_calls") or []:
+            fn = tc.get("function", {})
+            try:
+                args = json.loads(fn.get("arguments", "{}") or "{}")
+            except (json.JSONDecodeError, TypeError):
+                args = {}
+            tc_id = tc.get("id", str(uuid.uuid4()))
+            fc_part: dict[str, Any] = {
+                "functionCall": {
+                    "name": fn.get("name", ""),
+                    "args": args,
+                    "id": tc_id,
+                }
+            }
+            if thought_sigs:
+                sig = thought_sigs.get(tc_id, "")
+                if sig:
+                    fc_part["thoughtSignature"] = sig  # part-level, not inside functionCall
+            parts.append(fc_part)
+
+        if parts:
+            contents.append({"role": gemini_role, "parts": parts})
+
+    _flush_tool_results()
+
+    # Gemini requires the first turn to be a user turn.  Drop any leading
+    # model messages so the API doesn't reject with a 400.
+    while contents and contents[0].get("role") == "model":
+        contents.pop(0)
+
+    return contents
+
+
+# ---------------------------------------------------------------------------
+# Response parsing helpers
+# ---------------------------------------------------------------------------
+
+
+def _map_finish_reason(reason: str) -> str:
+    return {"STOP": "stop", "MAX_TOKENS": "max_tokens", "OTHER": "tool_use"}.get(
+        (reason or "").upper(), "stop"
+    )
+
+
+def _parse_complete_response(raw: dict[str, Any], model: str) -> LLMResponse:
+    """Parse a non-streaming Antigravity response dict → LLMResponse."""
+    payload: dict[str, Any] = raw.get("response", raw)
+    candidates: list[dict[str, Any]] = payload.get("candidates", [])
+    usage: dict[str, Any] = payload.get("usageMetadata", {})
+
+    text_parts: list[str] = []
+    if candidates:
+        for part in candidates[0].get("content", {}).get("parts", []):
+            if "text" in part and not part.get("thought"):
+                text_parts.append(part["text"])
+
+    return LLMResponse(
+        content="".join(text_parts),
+        model=payload.get("modelVersion", model),
+        input_tokens=usage.get("promptTokenCount", 0),
+        output_tokens=usage.get("candidatesTokenCount", 0),
+        stop_reason=_map_finish_reason(candidates[0].get("finishReason", "") if candidates else ""),
+        raw_response=raw,
+    )
+
+
+def _parse_sse_stream(
+    response: Any,
+    model: str,
+    on_thought_signature: Callable[[str, str], None] | None = None,
+) -> Iterator[StreamEvent]:
+    """Parse Antigravity SSE response line-by-line → StreamEvents.
+
+    Each SSE line looks like::
+
+        data: {"response": {"candidates": [...], "usageMetadata": {...}}, "traceId": "..."}
+    """
+    accumulated = ""
+    input_tokens = 0
+    output_tokens = 0
+    finish_reason = ""
+
+    for raw_line in response:
+        line: str = raw_line.decode("utf-8", errors="replace").rstrip("\r\n")
+        if not line.startswith("data:"):
+            continue
+        data_str = line[5:].strip()
+        if not data_str or data_str == "[DONE]":
+            continue
+        try:
+            data: dict[str, Any] = json.loads(data_str)
+        except json.JSONDecodeError:
+            continue
+
+        # The outer envelope is {"response": {...}, "traceId": "..."}.
+        payload: dict[str, Any] = data.get("response", data)
+
+        usage = payload.get("usageMetadata", {})
+        if usage:
+            input_tokens = usage.get("promptTokenCount", input_tokens)
+            output_tokens = usage.get("candidatesTokenCount", output_tokens)
+
+        for candidate in payload.get("candidates", []):
+            fr = candidate.get("finishReason", "")
+            if fr:
+                finish_reason = fr
+
+            for part in candidate.get("content", {}).get("parts", []):
+                if "text" in part and not part.get("thought"):
+                    delta: str = part["text"]
+                    accumulated += delta
+                    yield TextDeltaEvent(content=delta, snapshot=accumulated)
+                elif "functionCall" in part:
+                    fc: dict[str, Any] = part["functionCall"]
+                    tool_use_id = fc.get("id") or str(uuid.uuid4())
+                    thought_sig = part.get("thoughtSignature", "")  # sibling of functionCall
+                    if thought_sig and on_thought_signature:
+                        on_thought_signature(tool_use_id, thought_sig)
+                    args = fc.get("args", {})
+                    if isinstance(args, str):
+                        try:
+                            args = json.loads(args)
+                        except json.JSONDecodeError:
+                            args = {}
+                    yield ToolCallEvent(
+                        tool_use_id=tool_use_id,
+                        tool_name=fc.get("name", ""),
+                        tool_input=args,
+                    )
+
+    if accumulated:
+        yield TextEndEvent(full_text=accumulated)
+    yield FinishEvent(
+        stop_reason=_map_finish_reason(finish_reason),
+        input_tokens=input_tokens,
+        output_tokens=output_tokens,
+        model=model,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Provider
+# ---------------------------------------------------------------------------
+
+
+class AntigravityProvider(LLMProvider):
+    """LLM provider for Google's internal Antigravity Code Assist gateway.
+
+    No local proxy required.  Handles OAuth token refresh, Gemini-format
+    request/response conversion, and SSE streaming directly.
+    """
+
+    def __init__(self, model: str = "gemini-3-flash") -> None:
+        # Strip any provider prefix ("openai/gemini-3-flash" → "gemini-3-flash").
+        if "/" in model:
+            model = model.split("/", 1)[1]
+        self.model = model
+
+        self._access_token: str | None = None
+        self._refresh_token: str | None = None
+        self._project_id: str = _DEFAULT_PROJECT_ID
+        self._token_expires_at: float = 0.0
+        self._thought_sigs: dict[str, str] = {}  # tool_use_id → thoughtSignature
+
+        self._init_credentials()
+
+    # --- Credential management -------------------------------------------- #
+
+    def _init_credentials(self) -> None:
+        """Load credentials from the best available source."""
+        access, refresh, project_id, expires_at = _load_from_json_file()
+        if refresh:
+            self._refresh_token = refresh
+            self._project_id = project_id
+            self._access_token = access
+            self._token_expires_at = expires_at
+            return
+
+        # Fall back to IDE state DB.
+        access, refresh, expires_at = _load_from_ide_db()
+        if access:
+            self._access_token = access
+            self._refresh_token = refresh
+            self._token_expires_at = expires_at
+
+    def has_credentials(self) -> bool:
+        """Return True if any credential is available."""
+        return bool(self._access_token or self._refresh_token)
+
+    def _ensure_token(self) -> str:
+        """Return a valid access token, refreshing via OAuth if needed."""
+        if (
+            self._access_token
+            and self._token_expires_at
+            and time.time() < self._token_expires_at - _TOKEN_REFRESH_BUFFER_SECS
+        ):
+            return self._access_token
+
+        if self._refresh_token:
+            result = _do_token_refresh(self._refresh_token)
+            if result:
+                self._access_token, self._token_expires_at = result
+                return self._access_token
+
+        if self._access_token:
+            logger.warning("Using potentially stale Antigravity access token")
+            return self._access_token
+
+        raise RuntimeError(
+            "No valid Antigravity credentials. "
+            "Run: uv run python core/antigravity_auth.py auth account add"
+        )
+
+    # --- Request building -------------------------------------------------- #
+
+    def _build_body(
+        self,
+        messages: list[dict[str, Any]],
+        system: str,
+        tools: list[Tool] | None,
+        max_tokens: int,
+    ) -> dict[str, Any]:
+        contents = _to_gemini_contents(messages, self._thought_sigs)
+        inner: dict[str, Any] = {
+            "contents": contents,
+            "generationConfig": {"maxOutputTokens": max_tokens},
+        }
+        if system:
+            inner["systemInstruction"] = {"parts": [{"text": system}]}
+        if tools:
+            inner["tools"] = [
+                {
+                    "functionDeclarations": [
+                        {
+                            "name": _clean_tool_name(t.name),
+                            "description": t.description,
+                            "parameters": t.parameters
+                            or {
+                                "type": "object",
+                                "properties": {},
+                            },
+                        }
+                        for t in tools
+                    ]
+                }
+            ]
+        return {
+            "project": self._project_id,
+            "model": self.model,
+            "request": inner,
+            "requestType": "agent",
+            "userAgent": "antigravity",
+            "requestId": f"agent-{uuid.uuid4()}",
+        }
+
+    # --- HTTP transport ---------------------------------------------------- #
+
+    def _post(self, body: dict[str, Any], *, streaming: bool) -> Any:
+        """POST to the Antigravity endpoint, falling back through the endpoint list."""
+        import urllib.error  # noqa: PLC0415
+        import urllib.request  # noqa: PLC0415
+
+        token = self._ensure_token()
+        body_bytes = json.dumps(body).encode("utf-8")
+        path = (
+            "/v1internal:streamGenerateContent?alt=sse"
+            if streaming
+            else "/v1internal:generateContent"
+        )
+        headers = {
+            **_BASE_HEADERS,
+            "Authorization": f"Bearer {token}",
+            "Content-Type": "application/json",
+        }
+        if streaming:
+            headers["Accept"] = "text/event-stream"
+
+        last_exc: Exception | None = None
+        for base_url in _ENDPOINTS:
+            url = f"{base_url}{path}"
+            req = urllib.request.Request(url, data=body_bytes, headers=headers, method="POST")
+            try:
+                return urllib.request.urlopen(req, timeout=120)  # noqa: S310
+            except urllib.error.HTTPError as exc:
+                if exc.code in (401, 403) and self._refresh_token:
+                    # Token rejected — refresh once and retry this endpoint.
+                    result = _do_token_refresh(self._refresh_token)
+                    if result:
+                        self._access_token, self._token_expires_at = result
+                        headers["Authorization"] = f"Bearer {self._access_token}"
+                        req2 = urllib.request.Request(
+                            url, data=body_bytes, headers=headers, method="POST"
+                        )
+                        try:
+                            return urllib.request.urlopen(req2, timeout=120)  # noqa: S310
+                        except urllib.error.HTTPError as exc2:
+                            last_exc = exc2
+                            continue
+                    last_exc = exc
+                    continue
+                elif exc.code >= 500:
+                    last_exc = exc
+                    continue
+                # Include the API response body in the exception for easier debugging.
+                try:
+                    err_body = exc.read().decode("utf-8", errors="replace")
+                except Exception:
+                    err_body = "(unreadable)"
+                raise RuntimeError(f"Antigravity HTTP {exc.code} from {url}: {err_body}") from exc
+            except (urllib.error.URLError, OSError) as exc:
+                last_exc = exc
+                continue
+
+        raise RuntimeError(
+            f"All Antigravity endpoints failed. Last error: {last_exc}"
+        ) from last_exc
+
+    # --- LLMProvider interface --------------------------------------------- #
+
+    def complete(
+        self,
+        messages: list[dict[str, Any]],
+        system: str = "",
+        tools: list[Tool] | None = None,
+        max_tokens: int = 1024,
+        response_format: dict[str, Any] | None = None,
+        json_mode: bool = False,
+        max_retries: int | None = None,
+    ) -> LLMResponse:
+        if json_mode:
+            suffix = "\n\nPlease respond with a valid JSON object."
+            system = (system + suffix) if system else suffix.strip()
+
+        body = self._build_body(messages, system, tools, max_tokens)
+        resp = self._post(body, streaming=False)
+        return _parse_complete_response(json.loads(resp.read()), self.model)
+
+    async def stream(
+        self,
+        messages: list[dict[str, Any]],
+        system: str = "",
+        tools: list[Tool] | None = None,
+        max_tokens: int = 4096,
+    ) -> AsyncIterator[StreamEvent]:
+        import asyncio  # noqa: PLC0415
+        import concurrent.futures  # noqa: PLC0415
+
+        loop = asyncio.get_running_loop()
+        queue: asyncio.Queue[StreamEvent | None] = asyncio.Queue()
+
+        def _blocking_work() -> None:
+            try:
+                body = self._build_body(messages, system, tools, max_tokens)
+                http_resp = self._post(body, streaming=True)
+                for event in _parse_sse_stream(
+                    http_resp, self.model, self._thought_sigs.__setitem__
+                ):
+                    loop.call_soon_threadsafe(queue.put_nowait, event)
+            except Exception as exc:
+                logger.error("Antigravity stream error: %s", exc)
+                loop.call_soon_threadsafe(queue.put_nowait, StreamErrorEvent(error=str(exc)))
+            finally:
+                loop.call_soon_threadsafe(queue.put_nowait, None)  # sentinel
+
+        executor = concurrent.futures.ThreadPoolExecutor(max_workers=1)
+        fut = loop.run_in_executor(executor, _blocking_work)
+        try:
+            while True:
+                event = await queue.get()
+                if event is None:
+                    break
+                yield event
+        finally:
+            await fut
+            executor.shutdown(wait=False)
@@ -0,0 +1,106 @@
+"""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
+"""
+
+from __future__ import annotations
+
+
+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)
+    """
+    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):
+        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
@@ -45,6 +45,8 @@ class ToolResult:
    tool_use_id: str
    content: str
    is_error: bool = False
+    image_content: list[dict[str, Any]] | None = None
+    is_skill_content: bool = False  # AS-10: marks activated skill body, protected from pruning


 class LLMProvider(ABC):
@@ -71,6 +71,7 @@ class FinishEvent:
    stop_reason: str = ""
    input_tokens: int = 0
    output_tokens: int = 0
+    cached_tokens: int = 0
    model: str = ""


@@ -1,4 +0,0 @@
-"""MCP servers for worker-bee."""
-
-# Don't auto-import servers to avoid double-import issues when running with -m
-__all__ = []
@@ -1,33 +0,0 @@
-"""Framework-level worker monitoring package.
-
-Provides the Worker Health Judge: a reusable secondary graph that attaches to
-any worker agent runtime and monitors its execution health via periodic log
-inspection. Emits structured EscalationTickets when degradation is detected.
-
-Usage::
-
-    from framework.monitoring import HEALTH_JUDGE_ENTRY_POINT, judge_goal, judge_graph
-    from framework.tools.worker_monitoring_tools import register_worker_monitoring_tools
-
-    # Register tools bound to the worker runtime's EventBus
-    monitoring_registry = ToolRegistry()
-    register_worker_monitoring_tools(monitoring_registry, worker_runtime._event_bus, storage_path)
-
-    # Load judge as secondary graph on the worker runtime
-    await worker_runtime.add_graph(
-        graph_id="judge",
-        graph=judge_graph,
-        goal=judge_goal,
-        entry_points={"health_check": HEALTH_JUDGE_ENTRY_POINT},
-        storage_subpath="graphs/judge",
-    )
-"""
-
-from .judge import HEALTH_JUDGE_ENTRY_POINT, judge_goal, judge_graph, judge_node
-
-__all__ = [
-    "HEALTH_JUDGE_ENTRY_POINT",
-    "judge_goal",
-    "judge_graph",
-    "judge_node",
-]
@@ -1,258 +0,0 @@
-"""Worker Health Judge — framework-level reusable monitoring graph.
-
-Attaches to any worker agent runtime as a secondary graph. Fires on a
-2-minute timer, reads the worker's session logs via ``get_worker_health_summary``,
-accumulates observations in a continuous conversation context, and emits a
-structured ``EscalationTicket`` when it detects a degradation pattern.
-
-Usage::
-
-    from framework.monitoring import judge_graph, judge_goal, HEALTH_JUDGE_ENTRY_POINT
-    from framework.tools.worker_monitoring_tools import register_worker_monitoring_tools
-
-    # Register tools bound to the worker runtime's event bus
-    monitoring_registry = ToolRegistry()
-    register_worker_monitoring_tools(
-        monitoring_registry, worker_runtime._event_bus, storage_path
-    )
-    monitoring_tools = list(monitoring_registry.get_tools().values())
-    monitoring_executor = monitoring_registry.get_executor()
-
-    # Load judge as secondary graph on the worker runtime
-    await worker_runtime.add_graph(
-        graph_id="judge",
-        graph=judge_graph,
-        goal=judge_goal,
-        entry_points={"health_check": HEALTH_JUDGE_ENTRY_POINT},
-        storage_subpath="graphs/judge",
-    )
-
-Design:
- ``isolation_level="isolated"`` — the judge has its own memory, not
-  polluting the worker's shared memory namespace.
- ``conversation_mode="continuous"`` — the judge's conversation carries
-  across timer ticks. The conversation IS the judge's memory. It tracks
-  trends by referring to its own prior messages ("Last check I saw 47
-  steps; now 52; 5 new steps, 3 RETRY").
- No shared memory keys. No external state files.
-"""
-
-from __future__ import annotations
-
-from framework.graph import Constraint, Goal, NodeSpec, SuccessCriterion
-from framework.graph.edge import AsyncEntryPointSpec, GraphSpec
-
-# ---------------------------------------------------------------------------
-# Goal
-# ---------------------------------------------------------------------------
-
-judge_goal = Goal(
-    id="worker-health-monitor",
-    name="Worker Health Monitor",
-    description=(
-        "Periodically assess the health of the worker agent by reading its "
-        "execution logs. Detect degradation patterns (excessive retries, "
-        "stalls, doom loops) and emit structured EscalationTickets when the "
-        "worker needs attention."
-    ),
-    success_criteria=[
-        SuccessCriterion(
-            id="accurate-detection",
-            description="Only escalates genuine degradation, not normal retry cycles",
-            metric="false_positive_rate",
-            target="low",
-            weight=0.5,
-        ),
-        SuccessCriterion(
-            id="timely-detection",
-            description="Detects genuine stalls within 2 timer ticks (≤4 minutes)",
-            metric="detection_latency_minutes",
-            target="<=4",
-            weight=0.5,
-        ),
-    ],
-    constraints=[
-        Constraint(
-            id="conservative-escalation",
-            description=(
-                "Do not escalate on a single bad verdict or a brief stall. "
-                "Require clear patterns (10+ consecutive bad verdicts or 4+ minute stall) "
-                "before creating a ticket."
-            ),
-            constraint_type="hard",
-            category="quality",
-        ),
-        Constraint(
-            id="complete-ticket",
-            description=(
-                "Every EscalationTicket must have all required fields filled. "
-                "Do not emit partial or placeholder tickets."
-            ),
-            constraint_type="hard",
-            category="correctness",
-        ),
-    ],
-)
-
-# ---------------------------------------------------------------------------
-# Node
-# ---------------------------------------------------------------------------
-
-judge_node = NodeSpec(
-    id="judge",
-    name="Worker Health Judge",
-    description=(
-        "Autonomous health monitor for worker agents. Reads execution logs "
-        "on each timer tick, compares to prior observations (via conversation "
-        "history), and emits a structured EscalationTicket when a genuine "
-        "degradation pattern is detected."
-    ),
-    node_type="event_loop",
-    client_facing=False,  # Autonomous monitor, not interactive
-    max_node_visits=0,  # Unbounded — runs on every timer tick
-    input_keys=[],
-    output_keys=["health_verdict"],
-    nullable_output_keys=["health_verdict"],
-    success_criteria=(
-        "A clear health verdict is produced each check: either 'healthy' with "
-        "a brief observation, or a complete EscalationTicket is emitted via "
-        "emit_escalation_ticket and health_verdict describes the issue."
-    ),
-    tools=[
-        "get_worker_health_summary",
-        "emit_escalation_ticket",
-    ],
-    system_prompt="""\
-You are the Worker Health Judge. You run every 2 minutes alongside a worker \
-agent to monitor its execution health.
-
-# Your Role
-
-You observe the worker's iteration patterns over time and escalate only when \
-you see genuine degradation — not normal retry cycles. Your conversation history \
-IS your memory. On each check, refer to your previous observations to track trends.
-
-# Check Procedure
-
-On each timer tick (every 2 minutes):
-
-## Step 1: Read health snapshot
-Call get_worker_health_summary() with no arguments to auto-discover the active \
-session. This returns:
- worker_agent_id: the worker's agent name — use this for ticket identity fields
- worker_graph_id: the worker's primary graph ID — use this for ticket identity fields
- session_id: the session being monitored — use this for worker_session_id in tickets
- total_steps: how many log steps have been recorded
- recent_verdicts: list of recent ACCEPT/RETRY/CONTINUE verdicts
- steps_since_last_accept: consecutive non-ACCEPT steps
- stall_minutes: wall-clock since last step (null if active)
- evidence_snippet: recent LLM output
-
-## Step 2: Compare to prior check
-Look at your conversation history. What was total_steps last time?
- If total_steps is UNCHANGED from prior check AND prior check was also unchanged:
-  → STALL confirmed (worker has produced no new iterations in 4+ minutes).
-  → Escalate with severity="high" or "critical" depending on stall duration.
- If total_steps increased: worker is making progress. Examine verdicts.
-
-## Step 3: Analyze verdict pattern
- Healthy: Mix of ACCEPT and RETRY, steps_since_last_accept < 5. No action.
- Warning: steps_since_last_accept is 5-9. Note it, no escalation yet.
- Degraded: steps_since_last_accept >= 10. Examine evidence_snippet.
-  - If evidence shows the agent is making real progress (complex reasoning,
-    exploring solutions, productive tool use): may be a hard problem. Note it.
-  - If evidence shows a loop (same error, same tool call, no new information):
-    → Escalate with severity="medium" or "high".
- Critical: steps_since_last_accept >= 20, OR stall_minutes >= 4.
-  → Escalate with severity="critical".
-
-## Step 4: Decide
-
-### If healthy:
-set_output("health_verdict", "healthy: <brief observation>")
-Done.
-
-### If escalating:
-Build an EscalationTicket JSON string with ALL required fields:
-{
-  "worker_agent_id": "<worker_agent_id from get_worker_health_summary>",
-  "worker_session_id": "<session_id from get_worker_health_summary>",
-  "worker_node_id": "<worker_graph_id from get_worker_health_summary>",
-  "worker_graph_id": "<worker_graph_id from get_worker_health_summary>",
-  "severity": "<low|medium|high|critical>",
-  "cause": "<what you observed — concrete, specific>",
-  "judge_reasoning": "<why you decided to escalate, not just dismiss>",
-  "suggested_action": "<what you recommend: restart, human review, etc.>",
-  "recent_verdicts": [<list from get_worker_health_summary>],
-  "total_steps_checked": <int>,
-  "steps_since_last_accept": <int>,
-  "stall_minutes": <float or null>,
-  "evidence_snippet": "<from get_worker_health_summary>"
-}
-
-Call: emit_escalation_ticket(ticket_json=<the JSON string above>)
-Then: set_output("health_verdict", "escalated: <one-line summary>")
-
-# Severity Guide
-
- low: Mild concern, worth noting. 5-9 consecutive bad verdicts.
- medium: Clear degradation pattern. 10-15 bad verdicts or brief stall (1-2 min).
- high: Serious issue. 15+ bad verdicts or stall 2-4 minutes or clear doom loop.
- critical: Worker is definitively stuck. 20+ bad verdicts or stall > 4 minutes.
-
-# Conservative Bias
-
-You MUST resist the urge to escalate prematurely. Worker agents naturally retry.
-A node may legitimately need 5-8 retries before succeeding. Do not escalate unless:
-1. The pattern is clear and sustained across your observation window, AND
-2. The evidence shows no genuine progress
-
-One missed escalation is less costly than two false alarms. The Queen will filter \
-further. But do not be passive — genuine stalls and doom loops must be caught.
-
-# Rules
- Never escalate on the FIRST check unless stall_minutes > 4
- Always call get_worker_health_summary FIRST before deciding anything
- All ticket fields are REQUIRED — do not submit partial tickets
- After any emit_escalation_ticket call, always set_output to complete the check
-""",
-)
-
-# ---------------------------------------------------------------------------
-# Entry Point
-# ---------------------------------------------------------------------------
-
-HEALTH_JUDGE_ENTRY_POINT = AsyncEntryPointSpec(
-    id="health_check",
-    name="Worker Health Check",
-    entry_node="judge",
-    trigger_type="timer",
-    trigger_config={
-        "interval_minutes": 2,
-        "run_immediately": True,  # Fire immediately to establish a baseline
-    },
-    isolation_level="isolated",  # Own memory namespace, not polluting worker's
-)
-
-# ---------------------------------------------------------------------------
-# Graph
-# ---------------------------------------------------------------------------
-
-judge_graph = GraphSpec(
-    id="judge-graph",
-    goal_id=judge_goal.id,
-    version="1.0.0",
-    entry_node="judge",
-    entry_points={"health_check": "judge"},
-    terminal_nodes=["judge"],  # Judge node can terminate after each check
-    pause_nodes=[],
-    nodes=[judge_node],
-    edges=[],
-    conversation_mode="continuous",  # Conversation persists across timer ticks
-    async_entry_points=[HEALTH_JUDGE_ENTRY_POINT],
-    loop_config={
-        "max_iterations": 10,  # One check shouldn't take many turns
-        "max_tool_calls_per_turn": 3,  # get_summary + optionally emit_ticket
-        "max_history_tokens": 16000,  # Compact — judge only needs recent context
-    },
-)
@@ -83,18 +83,18 @@ configure_logging(level="INFO", format="auto")
 - Compact single-line format (easy to stream/parse)
 - All trace context fields included automatically

-### Human-Readable Format (Development)
+### Human-Readable Format (Development / Terminal)

 ```
-[INFO    ] [trace:12345678 | exec:a1b2c3d4 | agent:sales-agent] Starting agent execution
-[INFO    ] [trace:12345678 | exec:a1b2c3d4 | agent:sales-agent] Processing input data [node_id:input-processor]
-[INFO    ] [trace:12345678 | exec:a1b2c3d4 | agent:sales-agent] LLM call completed [latency_ms:1250] [tokens_used:450]
+[INFO    ] [agent:sales-agent] Starting agent execution
+[INFO    ] [agent:sales-agent] Processing input data [node_id:input-processor]
+[INFO    ] [agent:sales-agent] LLM call completed [latency_ms:1250] [tokens_used:450]
 ```

 **Features:**
 - Color-coded log levels
- Shortened IDs for readability (first 8 chars)
- Context prefix shows trace correlation
+- Terminal output omits trace_id and execution_id for readability
+- For full traceability (e.g. debugging), use `ENV=production` to get JSON file logs with trace_id and execution_id

 ## Trace Context Fields

@@ -4,8 +4,9 @@ Structured logging with automatic trace context propagation.
 Key Features:
 - Zero developer friction: Standard logger.info() calls get automatic context
 - ContextVar-based propagation: Thread-safe and async-safe
- Dual output modes: JSON for production, human-readable for development
- Correlation IDs: trace_id follows entire request flow automatically
+- Dual output modes: JSON for production (full trace_id/execution_id), human-readable for terminal
+- Terminal omits trace_id/execution_id for readability
+- Use ENV=production for file logs with full traceability

 Architecture:
    Runtime.start_run() → Generates trace_id, sets context once
@@ -29,6 +30,8 @@ from typing import Any
 # ContextVar is thread-safe and async-safe - perfect for concurrent agent execution
 trace_context: ContextVar[dict[str, Any] | None] = ContextVar("trace_context", default=None)

+_STANDARD_LOG_RECORD_FIELDS = set(logging.makeLogRecord({}).__dict__)
+
 # ANSI escape code pattern (matches \033[...m or \x1b[...m)
 ANSI_ESCAPE_PATTERN = re.compile(r"\x1b\[[0-9;]*m|\033\[[0-9;]*m")

@@ -91,6 +94,14 @@ class StructuredFormatter(logging.Formatter):
        if model is not None:
            log_entry["model"] = model

+        # Preserve arbitrary structured fields passed via ``extra=...``.
+        for key, value in record.__dict__.items():
+            if key in _STANDARD_LOG_RECORD_FIELDS or key.startswith("_"):
+                continue
+            if key in log_entry:
+                continue
+            log_entry[key] = value
+
        # Add exception info if present (strip ANSI codes from exception text too)
        if record.exc_info:
            exception_text = self.formatException(record.exc_info)
@@ -101,10 +112,11 @@ class StructuredFormatter(logging.Formatter):

 class HumanReadableFormatter(logging.Formatter):
    """
-    Human-readable formatter for development.
+    Human-readable formatter for development (terminal output).

-    Provides colorized logs with trace context for local debugging.
-    Includes trace_id prefix for correlation - AUTOMATIC!
+    Provides colorized logs for local debugging. Omits trace_id and execution_id
+    from the terminal for readability; use ENV=production (JSON file logs) when
+    traceability is needed.
    """

    COLORS = {
@@ -118,18 +130,11 @@ class HumanReadableFormatter(logging.Formatter):

    def format(self, record: logging.LogRecord) -> str:
        """Format log record as human-readable string."""
-        # Get trace context - AUTOMATIC!
+        # Get trace context; omit trace_id and execution_id in terminal for readability
        context = trace_context.get() or {}
-        trace_id = context.get("trace_id", "")
-        execution_id = context.get("execution_id", "")
        agent_id = context.get("agent_id", "")

-        # Build context prefix
        prefix_parts = []
-        if trace_id:
-            prefix_parts.append(f"trace:{trace_id[:8]}")
-        if execution_id:
-            prefix_parts.append(f"exec:{execution_id[-8:]}")
        if agent_id:
            prefix_parts.append(f"agent:{agent_id}")

@@ -148,8 +153,9 @@ class HumanReadableFormatter(logging.Formatter):
        if record_event is not None:
            event = f" [{record_event}]"

-        # Format message: [LEVEL] [trace context] message
-        return f"{color}[{level}]{reset} {context_prefix}{record.getMessage()}{event}"
+        timestamp = self.formatTime(record, "%Y-%m-%d %H:%M:%S")
+        # Format message: TIMESTAMP [LEVEL] [trace context] message
+        return f"{timestamp} {color}[{level}]{reset} {context_prefix}{record.getMessage()}{event}"


 def configure_logging(
@@ -210,6 +216,15 @@ def configure_logging(
    root_logger.addHandler(handler)
    root_logger.setLevel(level.upper())

+    # Suppress noisy LiteLLM INFO logs (model/provider line + Provider List URL
+    # printed on every single completion call).  Warnings and errors still show.
+    # Honour LITELLM_LOG env var so users can opt-in to debug output.
+    _litellm_level = os.getenv("LITELLM_LOG", "").upper()
+    if _litellm_level and hasattr(logging, _litellm_level):
+        logging.getLogger("LiteLLM").setLevel(getattr(logging, _litellm_level))
+    else:
+        logging.getLogger("LiteLLM").setLevel(logging.WARNING)
+
    # When in JSON mode, configure known third-party loggers to use JSON formatter
    # This ensures libraries like LiteLLM, httpcore also output clean JSON
    if format == "json":
--- a/Show More
+++ b/Show More