diff --git a/.claude/agents/codebase-online-researcher.md b/.claude/agents/codebase-online-researcher.md
index 8057eb7a53..d65281f822 100644
--- a/.claude/agents/codebase-online-researcher.md
+++ b/.claude/agents/codebase-online-researcher.md
@@ -1,12 +1,12 @@
 ---
 name: codebase-online-researcher
 description: Do you find yourself desiring information that you don't quite feel well-trained (confident) on? Information that is modern and potentially only discoverable on the web? Use the codebase-online-researcher subagent_type today to find any and all answers to your questions! It will research deeply to figure out and attempt to answer your questions! If you aren't immediately satisfied you can get your money back! (Not really - but you can re-run codebase-online-researcher with an altered prompt in the event you're not satisfied the first time)
-tools: Glob, Grep, NotebookRead, Read, LS, TodoWrite, ListMcpResourcesTool, ReadMcpResourceTool, mcp__deepwiki__ask_question, WebFetch, WebSearch
+tools: Glob, Grep, NotebookRead, Read, LS, TodoWrite, ListMcpResourcesTool, ReadMcpResourceTool, mcp__deepwiki__ask_question
 model: opus
 memory: project
 ---
 
-You are an expert web research specialist focused on finding accurate, relevant information from web sources. Your primary tools are the DeepWiki `ask_question` tool and WebFetch/WebSearch tools, which you use to discover and retrieve information based on user queries.
+You are an expert research specialist focused on finding accurate, relevant information from authoritative sources. Your primary tool is the DeepWiki `ask_question` tool, which you use to discover and retrieve information based on user queries.
 
 ## Core Responsibilities
 
@@ -15,26 +15,25 @@ When you receive a research query, you should:
 1. Try to answer using the DeepWiki `ask_question` tool to research best practices on design patterns, architecture, and implementation strategies.
 2. Ask it questions about the system design and constructs in the library that will help you achieve your goals.
 
-If the answer is insufficient, out-of-date, or unavailable, proceed with the following steps for web research:
+If the answer is insufficient, out-of-date, or unavailable, proceed with the following steps:
 
 1. **Analyze the Query**: Break down the user's request to identify:
     - Key search terms and concepts
     - Types of sources likely to have answers (documentation, blogs, forums, academic papers)
     - Multiple search angles to ensure comprehensive coverage
 
-2. **Execute Strategic Searches**:
-    - Start with broad searches to understand the landscape
+2. **Execute Strategic DeepWiki Queries**:
+    - Start with broad questions to understand the landscape
     - Refine with specific technical terms and phrases
-    - Use multiple search variations to capture different perspectives
-    - Include site-specific searches when targeting known authoritative sources (e.g., "site:docs.stripe.com webhook signature")
+    - Use multiple query variations to capture different perspectives
+    - Ask repo-specific questions for known authoritative sources (e.g., `owner/repo` docs and implementation patterns)
 
-3. **Fetch and Analyze Content**:
-    - Use WebFetch and WebSearch tools to retrieve full content from promising search results
-    - Prioritize official documentation, reputable technical blogs, and authoritative sources
+3. **Analyze Returned Context**:
+    - Prioritize official documentation and upstream repository guidance surfaced through DeepWiki
     - Extract specific quotes and sections relevant to the query
-    - Note publication dates to ensure currency of information
+    - Note versions and publication timing when available
 
-Finally, for both DeepWiki and WebFetch/WebSearch research findings:
+Finally, for all research findings:
 
 4. **Synthesize Findings**:
     - Organize information by relevance and authority
@@ -112,10 +111,10 @@ Structure your findings as:
 
 ## Search Efficiency
 
-- Start with 2-3 well-crafted searches before fetching content
-- Fetch only the most promising 3-5 pages initially
-- If initial results are insufficient, refine search terms and try again
-- Use search operators effectively: quotes for exact phrases, minus for exclusions, site: for specific domains
-- Consider searching in different forms: tutorials, documentation, Q&A sites, and discussion forums
+- Start with 2-3 well-crafted DeepWiki queries before broadening scope
+- Focus first on the most authoritative repositories and docs
+- If initial results are insufficient, refine terms and ask narrower follow-up questions
+- Use exact error messages and function names when available for higher precision
+- Compare guidance across at least two sources when possible
 
-Remember: You are the user's expert guide to web information. Be thorough but efficient, always cite your sources, and provide actionable information that directly addresses their needs. Think deeply as you work.
+Remember: You are the user's expert guide to technical research. Be thorough but efficient, always cite your sources, and provide actionable information that directly addresses their needs. Think deeply as you work.
diff --git a/.claude/agents/debugger.md b/.claude/agents/debugger.md
index ae201c3a97..3824cf4f4b 100644
--- a/.claude/agents/debugger.md
+++ b/.claude/agents/debugger.md
@@ -1,7 +1,7 @@
 ---
 name: debugger
 description: Debugging specialist for errors, test failures, and unexpected behavior. Use PROACTIVELY when encountering issues, analyzing stack traces, or investigating system problems.
-tools: Bash, Task, AskUserQuestion, Edit, Glob, Grep, NotebookEdit, NotebookRead, Read, TodoWrite, Write, ListMcpResourcesTool, ReadMcpResourceTool, mcp__deepwiki__ask_question, WebFetch, WebSearch
+tools: Bash, Task, AskUserQuestion, Edit, Glob, Grep, NotebookEdit, NotebookRead, Read, TodoWrite, Write, ListMcpResourcesTool, ReadMcpResourceTool, mcp__deepwiki__ask_question
 model: opus
 memory: project
 ---
@@ -11,7 +11,6 @@ You are tasked with debugging and identifying errors, test failures, and unexpec
 Available tools:
 
 - DeepWiki (`ask_question`): Look up documentation for external libraries and frameworks
-- WebFetch/WebSearch: Retrieve web content for additional context if you don't find sufficient information in DeepWiki
 
 When invoked:
 1a. If the user doesn't provide specific error details output:
@@ -42,7 +41,6 @@ Debugging process:
 - Add strategic debug logging
 - Inspect variable states
 - Use DeepWiki to look up external library documentation when errors involve third-party dependencies
-- Use WebFetch/WebSearch to gather additional context from web sources if needed
 
 For each issue, provide:
 
diff --git a/.claude/agents/planner.md b/.claude/agents/planner.md
new file mode 100644
index 0000000000..d38b1fb425
--- /dev/null
+++ b/.claude/agents/planner.md
@@ -0,0 +1,128 @@
+---
+description: Decomposes user prompts into structured task lists for the Ralph workflow.
+mode: primary
+tools:
+    write: false
+    edit: false
+    bash: false
+    todowrite: false
+    question: false
+    lsp: false
+    skill: false
+---
+
+You are the planner agent for the Ralph autonomous implementation workflow.
+
+Your job is to decompose the user's feature request into a structured, ordered list of implementation tasks.
+
+# Input
+
+You will receive a feature specification or user request describing what needs to be implemented.
+
+# Output Format
+
+Return a JSON array of task objects with the following structure:
+
+```json
+[
+  {
+    "id": "#1",
+    "content": "Task description",
+    "status": "pending",
+    "activeForm": "Active form description (gerund, e.g., 'Implementing auth module')",
+    "blockedBy": []
+  },
+  {
+    "id": "#2",
+    "content": "Another task description",
+    "status": "pending",
+    "activeForm": "Active form description",
+    "blockedBy": ["#1"]
+  }
+]
+```
+
+# Task Decomposition Guidelines
+
+1. **Break down into atomic tasks**: Each task should be a single, focused unit of work that can be completed independently (unless it has dependencies).
+
+2. **Order by dependencies**: Use the `blockedBy` array to specify task dependencies. A task with `"blockedBy": ["#1"]` cannot start until task #1 is completed.
+
+3. **Be specific**: Task descriptions should be clear and actionable. Avoid vague descriptions like "fix bugs" or "improve performance".
+
+4. **Use gerunds for activeForm**: The `activeForm` field should describe the task in progress using a gerund (e.g., "Implementing", "Adding", "Refactoring").
+
+5. **Start simple**: Begin with foundational tasks (e.g., setup, configuration) before moving to feature implementation.
+
+6. **Consider testing**: Include tasks for writing tests where appropriate.
+
+7. **Typical task categories**:
+   - Setup/configuration tasks
+   - Model/data structure definitions
+   - Core logic implementation
+   - UI/presentation layer
+   - Integration tasks
+   - Testing tasks
+   - Documentation tasks
+
+# Example
+
+**Input**: "Add user authentication to the app"
+
+**Output**:
+```json
+[
+  {
+    "id": "#1",
+    "content": "Define user model and authentication schema",
+    "status": "pending",
+    "activeForm": "Defining user model and auth schema",
+    "blockedBy": []
+  },
+  {
+    "id": "#2",
+    "content": "Implement password hashing and validation utilities",
+    "status": "pending",
+    "activeForm": "Implementing password utilities",
+    "blockedBy": ["#1"]
+  },
+  {
+    "id": "#3",
+    "content": "Create registration endpoint with validation",
+    "status": "pending",
+    "activeForm": "Creating registration endpoint",
+    "blockedBy": ["#1", "#2"]
+  },
+  {
+    "id": "#4",
+    "content": "Create login endpoint with JWT token generation",
+    "status": "pending",
+    "activeForm": "Creating login endpoint",
+    "blockedBy": ["#1", "#2"]
+  },
+  {
+    "id": "#5",
+    "content": "Add authentication middleware for protected routes",
+    "status": "pending",
+    "activeForm": "Adding auth middleware",
+    "blockedBy": ["#4"]
+  },
+  {
+    "id": "#6",
+    "content": "Write integration tests for auth endpoints",
+    "status": "pending",
+    "activeForm": "Writing auth integration tests",
+    "blockedBy": ["#3", "#4", "#5"]
+  }
+]
+```
+
+# Important Notes
+
+- Always return valid JSON
+- Ensure all task IDs are unique
+- Use consistent ID format (#1, #2, #3, etc.)
+- The `status` field should always be "pending" for new tasks
+- Dependencies in `blockedBy` must reference valid task IDs
+- Keep task descriptions concise but descriptive (aim for 5-10 words)
+- Aim for 3-8 tasks total for most features (adjust based on complexity)
diff --git a/.claude/agents/reviewer.md b/.claude/agents/reviewer.md
index b5d6c6a8d2..b1200627ed 100644
--- a/.claude/agents/reviewer.md
+++ b/.claude/agents/reviewer.md
@@ -1,7 +1,7 @@
 ---
 name: reviewer
 description: Code reviewer for proposed code changes.
-tools: Bash, Task, Glob, Grep, Read, TodoWrite, mcp__deepwiki__ask_question, WebFetch, WebSearch
+tools: Bash, Task, Glob, Grep, Read, TodoWrite, mcp__deepwiki__ask_question
 model: opus
 memory: project
 ---
diff --git a/.claude/skills/explain-code/SKILL.md b/.claude/skills/explain-code/SKILL.md
index b96d66aa0e..b3f60a5960 100644
--- a/.claude/skills/explain-code/SKILL.md
+++ b/.claude/skills/explain-code/SKILL.md
@@ -9,7 +9,7 @@ description: Explain code functionality in detail.
 The following MCP tools are available and SHOULD be used when relevant:
 
 - **DeepWiki** (`ask_question`): Use to look up documentation for external libraries, frameworks, and GitHub repositories. Particularly useful for understanding third-party dependencies and their APIs.
-- **WebFetch/WebSearch**: Use to retrieve web content for additional context if information is not found in DeepWiki.
+- **Playwright CLI** (`playwright-cli`): Use to retrieve web content, browse documentation, and extract data from web pages if information is not found in DeepWiki. Invoke via the `/playwright-cli` skill or run `bunx playwright-cli` commands directly.
 
 ## Instructions
 
@@ -81,6 +81,7 @@ Follow this systematic approach to explain code: **$ARGUMENTS**
     - Identify debugging points and logging
     - Describe mock data or test scenarios
     - Explain test helpers and utilities
+    - Use `playwright-cli` to reproduce browser interactions and validate frontend behavior when applicable
 
 12. **Dependencies and Integrations**
     - Explain external service integrations
@@ -202,4 +203,5 @@ Remember to:
 - Structure explanations logically from high-level to detailed
 - Include visual diagrams or flowcharts when helpful
 - Tailor the explanation level to the intended audience
-- Use DeepWiki to look up external library documentation when encountering unfamiliar dependencies
\ No newline at end of file
+- Use DeepWiki to look up external library documentation when encountering unfamiliar dependencies
+- Use `playwright-cli` for live browser inspection when static code analysis is not enough
diff --git a/.claude/skills/playwright-cli/SKILL.md b/.claude/skills/playwright-cli/SKILL.md
new file mode 100644
index 0000000000..11bad2b874
--- /dev/null
+++ b/.claude/skills/playwright-cli/SKILL.md
@@ -0,0 +1,278 @@
+---
+name: playwright-cli
+description: Automates browser interactions for web testing, form filling, screenshots, and data extraction. Use when the user needs to navigate websites, interact with web pages, fill forms, take screenshots, test web applications, or extract information from web pages.
+allowed-tools: Bash(playwright-cli:*)
+---
+
+# Browser Automation with playwright-cli
+
+## Quick start
+
+```bash
+# open new browser
+playwright-cli open
+# navigate to a page
+playwright-cli goto https://playwright.dev
+# interact with the page using refs from the snapshot
+playwright-cli click e15
+playwright-cli type "page.click"
+playwright-cli press Enter
+# take a screenshot (rarely used, as snapshot is more common)
+playwright-cli screenshot
+# close the browser
+playwright-cli close
+```
+
+## Commands
+
+### Core
+
+```bash
+playwright-cli open
+# open and navigate right away
+playwright-cli open https://example.com/
+playwright-cli goto https://playwright.dev
+playwright-cli type "search query"
+playwright-cli click e3
+playwright-cli dblclick e7
+playwright-cli fill e5 "user@example.com"
+playwright-cli drag e2 e8
+playwright-cli hover e4
+playwright-cli select e9 "option-value"
+playwright-cli upload ./document.pdf
+playwright-cli check e12
+playwright-cli uncheck e12
+playwright-cli snapshot
+playwright-cli snapshot --filename=after-click.yaml
+playwright-cli eval "document.title"
+playwright-cli eval "el => el.textContent" e5
+playwright-cli dialog-accept
+playwright-cli dialog-accept "confirmation text"
+playwright-cli dialog-dismiss
+playwright-cli resize 1920 1080
+playwright-cli close
+```
+
+### Navigation
+
+```bash
+playwright-cli go-back
+playwright-cli go-forward
+playwright-cli reload
+```
+
+### Keyboard
+
+```bash
+playwright-cli press Enter
+playwright-cli press ArrowDown
+playwright-cli keydown Shift
+playwright-cli keyup Shift
+```
+
+### Mouse
+
+```bash
+playwright-cli mousemove 150 300
+playwright-cli mousedown
+playwright-cli mousedown right
+playwright-cli mouseup
+playwright-cli mouseup right
+playwright-cli mousewheel 0 100
+```
+
+### Save as
+
+```bash
+playwright-cli screenshot
+playwright-cli screenshot e5
+playwright-cli screenshot --filename=page.png
+playwright-cli pdf --filename=page.pdf
+```
+
+### Tabs
+
+```bash
+playwright-cli tab-list
+playwright-cli tab-new
+playwright-cli tab-new https://example.com/page
+playwright-cli tab-close
+playwright-cli tab-close 2
+playwright-cli tab-select 0
+```
+
+### Storage
+
+```bash
+playwright-cli state-save
+playwright-cli state-save auth.json
+playwright-cli state-load auth.json
+
+# Cookies
+playwright-cli cookie-list
+playwright-cli cookie-list --domain=example.com
+playwright-cli cookie-get session_id
+playwright-cli cookie-set session_id abc123
+playwright-cli cookie-set session_id abc123 --domain=example.com --httpOnly --secure
+playwright-cli cookie-delete session_id
+playwright-cli cookie-clear
+
+# LocalStorage
+playwright-cli localstorage-list
+playwright-cli localstorage-get theme
+playwright-cli localstorage-set theme dark
+playwright-cli localstorage-delete theme
+playwright-cli localstorage-clear
+
+# SessionStorage
+playwright-cli sessionstorage-list
+playwright-cli sessionstorage-get step
+playwright-cli sessionstorage-set step 3
+playwright-cli sessionstorage-delete step
+playwright-cli sessionstorage-clear
+```
+
+### Network
+
+```bash
+playwright-cli route "**/*.jpg" --status=404
+playwright-cli route "https://api.example.com/**" --body='{"mock": true}'
+playwright-cli route-list
+playwright-cli unroute "**/*.jpg"
+playwright-cli unroute
+```
+
+### DevTools
+
+```bash
+playwright-cli console
+playwright-cli console warning
+playwright-cli network
+playwright-cli run-code "async page => await page.context().grantPermissions(['geolocation'])"
+playwright-cli tracing-start
+playwright-cli tracing-stop
+playwright-cli video-start
+playwright-cli video-stop video.webm
+```
+
+## Open parameters
+```bash
+# Use specific browser when creating session
+playwright-cli open --browser=chrome
+playwright-cli open --browser=firefox
+playwright-cli open --browser=webkit
+playwright-cli open --browser=msedge
+# Connect to browser via extension
+playwright-cli open --extension
+
+# Use persistent profile (by default profile is in-memory)
+playwright-cli open --persistent
+# Use persistent profile with custom directory
+playwright-cli open --profile=/path/to/profile
+
+# Start with config file
+playwright-cli open --config=my-config.json
+
+# Close the browser
+playwright-cli close
+# Delete user data for the default session
+playwright-cli delete-data
+```
+
+## Snapshots
+
+After each command, playwright-cli provides a snapshot of the current browser state.
+
+```bash
+> playwright-cli goto https://example.com
+### Page
+- Page URL: https://example.com/
+- Page Title: Example Domain
+### Snapshot
+[Snapshot](.playwright-cli/page-2026-02-14T19-22-42-679Z.yml)
+```
+
+You can also take a snapshot on demand using `playwright-cli snapshot` command.
+
+If `--filename` is not provided, a new snapshot file is created with a timestamp. Default to automatic file naming, use `--filename=` when artifact is a part of the workflow result.
+
+## Browser Sessions
+
+```bash
+# create new browser session named "mysession" with persistent profile
+playwright-cli -s=mysession open example.com --persistent
+# same with manually specified profile directory (use when requested explicitly)
+playwright-cli -s=mysession open example.com --profile=/path/to/profile
+playwright-cli -s=mysession click e6
+playwright-cli -s=mysession close  # stop a named browser
+playwright-cli -s=mysession delete-data  # delete user data for persistent session
+
+playwright-cli list
+# Close all browsers
+playwright-cli close-all
+# Forcefully kill all browser processes
+playwright-cli kill-all
+```
+
+## Local installation
+
+In some cases user might want to install playwright-cli locally. If running globally available `playwright-cli` binary fails, use `npx playwright-cli` to run the commands. For example:
+
+```bash
+npx playwright-cli open https://example.com
+npx playwright-cli click e1
+```
+
+## Example: Form submission
+
+```bash
+playwright-cli open https://example.com/form
+playwright-cli snapshot
+
+playwright-cli fill e1 "user@example.com"
+playwright-cli fill e2 "password123"
+playwright-cli click e3
+playwright-cli snapshot
+playwright-cli close
+```
+
+## Example: Multi-tab workflow
+
+```bash
+playwright-cli open https://example.com
+playwright-cli tab-new https://example.com/other
+playwright-cli tab-list
+playwright-cli tab-select 0
+playwright-cli snapshot
+playwright-cli close
+```
+
+## Example: Debugging with DevTools
+
+```bash
+playwright-cli open https://example.com
+playwright-cli click e4
+playwright-cli fill e7 "test"
+playwright-cli console
+playwright-cli network
+playwright-cli close
+```
+
+```bash
+playwright-cli open https://example.com
+playwright-cli tracing-start
+playwright-cli click e4
+playwright-cli fill e7 "test"
+playwright-cli tracing-stop
+playwright-cli close
+```
+
+## Specific tasks
+
+* **Request mocking** [references/request-mocking.md](references/request-mocking.md)
+* **Running Playwright code** [references/running-code.md](references/running-code.md)
+* **Browser session management** [references/session-management.md](references/session-management.md)
+* **Storage state (cookies, localStorage)** [references/storage-state.md](references/storage-state.md)
+* **Test generation** [references/test-generation.md](references/test-generation.md)
+* **Tracing** [references/tracing.md](references/tracing.md)
+* **Video recording** [references/video-recording.md](references/video-recording.md)
diff --git a/.claude/skills/playwright-cli/references/request-mocking.md b/.claude/skills/playwright-cli/references/request-mocking.md
new file mode 100644
index 0000000000..9005fda67d
--- /dev/null
+++ b/.claude/skills/playwright-cli/references/request-mocking.md
@@ -0,0 +1,87 @@
+# Request Mocking
+
+Intercept, mock, modify, and block network requests.
+
+## CLI Route Commands
+
+```bash
+# Mock with custom status
+playwright-cli route "**/*.jpg" --status=404
+
+# Mock with JSON body
+playwright-cli route "**/api/users" --body='[{"id":1,"name":"Alice"}]' --content-type=application/json
+
+# Mock with custom headers
+playwright-cli route "**/api/data" --body='{"ok":true}' --header="X-Custom: value"
+
+# Remove headers from requests
+playwright-cli route "**/*" --remove-header=cookie,authorization
+
+# List active routes
+playwright-cli route-list
+
+# Remove a route or all routes
+playwright-cli unroute "**/*.jpg"
+playwright-cli unroute
+```
+
+## URL Patterns
+
+```
+**/api/users           - Exact path match
+**/api/*/details       - Wildcard in path
+**/*.{png,jpg,jpeg}    - Match file extensions
+**/search?q=*          - Match query parameters
+```
+
+## Advanced Mocking with run-code
+
+For conditional responses, request body inspection, response modification, or delays:
+
+### Conditional Response Based on Request
+
+```bash
+playwright-cli run-code "async page => {
+  await page.route('**/api/login', route => {
+    const body = route.request().postDataJSON();
+    if (body.username === 'admin') {
+      route.fulfill({ body: JSON.stringify({ token: 'mock-token' }) });
+    } else {
+      route.fulfill({ status: 401, body: JSON.stringify({ error: 'Invalid' }) });
+    }
+  });
+}"
+```
+
+### Modify Real Response
+
+```bash
+playwright-cli run-code "async page => {
+  await page.route('**/api/user', async route => {
+    const response = await route.fetch();
+    const json = await response.json();
+    json.isPremium = true;
+    await route.fulfill({ response, json });
+  });
+}"
+```
+
+### Simulate Network Failures
+
+```bash
+playwright-cli run-code "async page => {
+  await page.route('**/api/offline', route => route.abort('internetdisconnected'));
+}"
+# Options: connectionrefused, timedout, connectionreset, internetdisconnected
+```
+
+### Delayed Response
+
+```bash
+playwright-cli run-code "async page => {
+  await page.route('**/api/slow', async route => {
+    await new Promise(r => setTimeout(r, 3000));
+    route.fulfill({ body: JSON.stringify({ data: 'loaded' }) });
+  });
+}"
+```
diff --git a/.claude/skills/playwright-cli/references/running-code.md b/.claude/skills/playwright-cli/references/running-code.md
new file mode 100644
index 0000000000..7d6d22fd09
--- /dev/null
+++ b/.claude/skills/playwright-cli/references/running-code.md
@@ -0,0 +1,232 @@
+# Running Custom Playwright Code
+
+Use `run-code` to execute arbitrary Playwright code for advanced scenarios not covered by CLI commands.
+
+## Syntax
+
+```bash
+playwright-cli run-code "async page => {
+  // Your Playwright code here
+  // Access page.context() for browser context operations
+}"
+```
+
+## Geolocation
+
+```bash
+# Grant geolocation permission and set location
+playwright-cli run-code "async page => {
+  await page.context().grantPermissions(['geolocation']);
+  await page.context().setGeolocation({ latitude: 37.7749, longitude: -122.4194 });
+}"
+
+# Set location to London
+playwright-cli run-code "async page => {
+  await page.context().grantPermissions(['geolocation']);
+  await page.context().setGeolocation({ latitude: 51.5074, longitude: -0.1278 });
+}"
+
+# Clear geolocation override
+playwright-cli run-code "async page => {
+  await page.context().clearPermissions();
+}"
+```
+
+## Permissions
+
+```bash
+# Grant multiple permissions
+playwright-cli run-code "async page => {
+  await page.context().grantPermissions([
+    'geolocation',
+    'notifications',
+    'camera',
+    'microphone'
+  ]);
+}"
+
+# Grant permissions for specific origin
+playwright-cli run-code "async page => {
+  await page.context().grantPermissions(['clipboard-read'], {
+    origin: 'https://example.com'
+  });
+}"
+```
+
+## Media Emulation
+
+```bash
+# Emulate dark color scheme
+playwright-cli run-code "async page => {
+  await page.emulateMedia({ colorScheme: 'dark' });
+}"
+
+# Emulate light color scheme
+playwright-cli run-code "async page => {
+  await page.emulateMedia({ colorScheme: 'light' });
+}"
+
+# Emulate reduced motion
+playwright-cli run-code "async page => {
+  await page.emulateMedia({ reducedMotion: 'reduce' });
+}"
+
+# Emulate print media
+playwright-cli run-code "async page => {
+  await page.emulateMedia({ media: 'print' });
+}"
+```
+
+## Wait Strategies
+
+```bash
+# Wait for network idle
+playwright-cli run-code "async page => {
+  await page.waitForLoadState('networkidle');
+}"
+
+# Wait for specific element
+playwright-cli run-code "async page => {
+  await page.waitForSelector('.loading', { state: 'hidden' });
+}"
+
+# Wait for function to return true
+playwright-cli run-code "async page => {
+  await page.waitForFunction(() => window.appReady === true);
+}"
+
+# Wait with timeout
+playwright-cli run-code "async page => {
+  await page.waitForSelector('.result', { timeout: 10000 });
+}"
+```
+
+## Frames and Iframes
+
+```bash
+# Work with iframe
+playwright-cli run-code "async page => {
+  const frame = page.locator('iframe#my-iframe').contentFrame();
+  await frame.locator('button').click();
+}"
+
+# Get all frames
+playwright-cli run-code "async page => {
+  const frames = page.frames();
+  return frames.map(f => f.url());
+}"
+```
+
+## File Downloads
+
+```bash
+# Handle file download
+playwright-cli run-code "async page => {
+  const [download] = await Promise.all([
+    page.waitForEvent('download'),
+    page.click('a.download-link')
+  ]);
+  await download.saveAs('./downloaded-file.pdf');
+  return download.suggestedFilename();
+}"
+```
+
+## Clipboard
+
+```bash
+# Read clipboard (requires permission)
+playwright-cli run-code "async page => {
+  await page.context().grantPermissions(['clipboard-read']);
+  return await page.evaluate(() => navigator.clipboard.readText());
+}"
+
+# Write to clipboard
+playwright-cli run-code "async page => {
+  await page.evaluate(text => navigator.clipboard.writeText(text), 'Hello clipboard!');
+}"
+```
+
+## Page Information
+
+```bash
+# Get page title
+playwright-cli run-code "async page => {
+  return await page.title();
+}"
+
+# Get current URL
+playwright-cli run-code "async page => {
+  return page.url();
+}"
+
+# Get page content
+playwright-cli run-code "async page => {
+  return await page.content();
+}"
+
+# Get viewport size
+playwright-cli run-code "async page => {
+  return page.viewportSize();
+}"
+```
+
+## JavaScript Execution
+
+```bash
+# Execute JavaScript and return result
+playwright-cli run-code "async page => {
+  return await page.evaluate(() => {
+    return {
+      userAgent: navigator.userAgent,
+      language: navigator.language,
+      cookiesEnabled: navigator.cookieEnabled
+    };
+  });
+}"
+
+# Pass arguments to evaluate
+playwright-cli run-code "async page => {
+  const multiplier = 5;
+  return await page.evaluate(m => document.querySelectorAll('li').length * m, multiplier);
+}"
+```
+
+## Error Handling
+
+```bash
+# Try-catch in run-code
+playwright-cli run-code "async page => {
+  try {
+    await page.click('.maybe-missing', { timeout: 1000 });
+    return 'clicked';
+  } catch (e) {
+    return 'element not found';
+  }
+}"
+```
+
+## Complex Workflows
+
+```bash
+# Login and save state
+playwright-cli run-code "async page => {
+  await page.goto('https://example.com/login');
+  await page.fill('input[name=email]', 'user@example.com');
+  await page.fill('input[name=password]', 'secret');
+  await page.click('button[type=submit]');
+  await page.waitForURL('**/dashboard');
+  await page.context().storageState({ path: 'auth.json' });
+  return 'Login successful';
+}"
+
+# Scrape data from multiple pages
+playwright-cli run-code "async page => {
+  const results = [];
+  for (let i = 1; i <= 3; i++) {
+    await page.goto(\`https://example.com/page/\${i}\`);
+    const items = await page.locator('.item').allTextContents();
+    results.push(...items);
+  }
+  return results;
+}"
+```
diff --git a/.claude/skills/playwright-cli/references/session-management.md b/.claude/skills/playwright-cli/references/session-management.md
new file mode 100644
index 0000000000..fac96066c9
--- /dev/null
+++ b/.claude/skills/playwright-cli/references/session-management.md
@@ -0,0 +1,169 @@
+# Browser Session Management
+
+Run multiple isolated browser sessions concurrently with state persistence.
+
+## Named Browser Sessions
+
+Use `-s` flag to isolate browser contexts:
+
+```bash
+# Browser 1: Authentication flow
+playwright-cli -s=auth open https://app.example.com/login
+
+# Browser 2: Public browsing (separate cookies, storage)
+playwright-cli -s=public open https://example.com
+
+# Commands are isolated by browser session
+playwright-cli -s=auth fill e1 "user@example.com"
+playwright-cli -s=public snapshot
+```
+
+## Browser Session Isolation Properties
+
+Each browser session has independent:
+- Cookies
+- LocalStorage / SessionStorage
+- IndexedDB
+- Cache
+- Browsing history
+- Open tabs
+
+## Browser Session Commands
+
+```bash
+# List all browser sessions
+playwright-cli list
+
+# Stop a browser session (close the browser)
+playwright-cli close                # stop the default browser
+playwright-cli -s=mysession close   # stop a named browser
+
+# Stop all browser sessions
+playwright-cli close-all
+
+# Forcefully kill all daemon processes (for stale/zombie processes)
+playwright-cli kill-all
+
+# Delete browser session user data (profile directory)
+playwright-cli delete-data                # delete default browser data
+playwright-cli -s=mysession delete-data   # delete named browser data
+```
+
+## Environment Variable
+
+Set a default browser session name via environment variable:
+
+```bash
+export PLAYWRIGHT_CLI_SESSION="mysession"
+playwright-cli open example.com  # Uses "mysession" automatically
+```
+
+## Common Patterns
+
+### Concurrent Scraping
+
+```bash
+#!/bin/bash
+# Scrape multiple sites concurrently
+
+# Start all browsers
+playwright-cli -s=site1 open https://site1.com &
+playwright-cli -s=site2 open https://site2.com &
+playwright-cli -s=site3 open https://site3.com &
+wait
+
+# Take snapshots from each
+playwright-cli -s=site1 snapshot
+playwright-cli -s=site2 snapshot
+playwright-cli -s=site3 snapshot
+
+# Cleanup
+playwright-cli close-all
+```
+
+### A/B Testing Sessions
+
+```bash
+# Test different user experiences
+playwright-cli -s=variant-a open "https://app.com?variant=a"
+playwright-cli -s=variant-b open "https://app.com?variant=b"
+
+# Compare
+playwright-cli -s=variant-a screenshot
+playwright-cli -s=variant-b screenshot
+```
+
+### Persistent Profile
+
+By default, browser profile is kept in memory only. Use `--persistent` flag on `open` to persist the browser profile to disk:
+
+```bash
+# Use persistent profile (auto-generated location)
+playwright-cli open https://example.com --persistent
+
+# Use persistent profile with custom directory
+playwright-cli open https://example.com --profile=/path/to/profile
+```
+
+## Default Browser Session
+
+When `-s` is omitted, commands use the default browser session:
+
+```bash
+# These use the same default browser session
+playwright-cli open https://example.com
+playwright-cli snapshot
+playwright-cli close  # Stops default browser
+```
+
+## Browser Session Configuration
+
+Configure a browser session with specific settings when opening:
+
+```bash
+# Open with config file
+playwright-cli open https://example.com --config=.playwright/my-cli.json
+
+# Open with specific browser
+playwright-cli open https://example.com --browser=firefox
+
+# Open in headed mode
+playwright-cli open https://example.com --headed
+
+# Open with persistent profile
+playwright-cli open https://example.com --persistent
+```
+
+## Best Practices
+
+### 1. Name Browser Sessions Semantically
+
+```bash
+# GOOD: Clear purpose
+playwright-cli -s=github-auth open https://github.com
+playwright-cli -s=docs-scrape open https://docs.example.com
+
+# AVOID: Generic names
+playwright-cli -s=s1 open https://github.com
+```
+
+### 2. Always Clean Up
+
+```bash
+# Stop browsers when done
+playwright-cli -s=auth close
+playwright-cli -s=scrape close
+
+# Or stop all at once
+playwright-cli close-all
+
+# If browsers become unresponsive or zombie processes remain
+playwright-cli kill-all
+```
+
+### 3. Delete Stale Browser Data
+
+```bash
+# Remove old browser data to free disk space
+playwright-cli -s=oldsession delete-data
+```
diff --git a/.claude/skills/playwright-cli/references/storage-state.md b/.claude/skills/playwright-cli/references/storage-state.md
new file mode 100644
index 0000000000..c856db5e40
--- /dev/null
+++ b/.claude/skills/playwright-cli/references/storage-state.md
@@ -0,0 +1,275 @@
+# Storage Management
+
+Manage cookies, localStorage, sessionStorage, and browser storage state.
+
+## Storage State
+
+Save and restore complete browser state including cookies and storage.
+
+### Save Storage State
+
+```bash
+# Save to auto-generated filename (storage-state-{timestamp}.json)
+playwright-cli state-save
+
+# Save to specific filename
+playwright-cli state-save my-auth-state.json
+```
+
+### Restore Storage State
+
+```bash
+# Load storage state from file
+playwright-cli state-load my-auth-state.json
+
+# Reload page to apply cookies
+playwright-cli open https://example.com
+```
+
+### Storage State File Format
+
+The saved file contains:
+
+```json
+{
+  "cookies": [
+    {
+      "name": "session_id",
+      "value": "abc123",
+      "domain": "example.com",
+      "path": "/",
+      "expires": 1735689600,
+      "httpOnly": true,
+      "secure": true,
+      "sameSite": "Lax"
+    }
+  ],
+  "origins": [
+    {
+      "origin": "https://example.com",
+      "localStorage": [
+        { "name": "theme", "value": "dark" },
+        { "name": "user_id", "value": "12345" }
+      ]
+    }
+  ]
+}
+```
+
+## Cookies
+
+### List All Cookies
+
+```bash
+playwright-cli cookie-list
+```
+
+### Filter Cookies by Domain
+
+```bash
+playwright-cli cookie-list --domain=example.com
+```
+
+### Filter Cookies by Path
+
+```bash
+playwright-cli cookie-list --path=/api
+```
+
+### Get Specific Cookie
+
+```bash
+playwright-cli cookie-get session_id
+```
+
+### Set a Cookie
+
+```bash
+# Basic cookie
+playwright-cli cookie-set session abc123
+
+# Cookie with options
+playwright-cli cookie-set session abc123 --domain=example.com --path=/ --httpOnly --secure --sameSite=Lax
+
+# Cookie with expiration (Unix timestamp)
+playwright-cli cookie-set remember_me token123 --expires=1735689600
+```
+
+### Delete a Cookie
+
+```bash
+playwright-cli cookie-delete session_id
+```
+
+### Clear All Cookies
+
+```bash
+playwright-cli cookie-clear
+```
+
+### Advanced: Multiple Cookies or Custom Options
+
+For complex scenarios like adding multiple cookies at once, use `run-code`:
+
+```bash
+playwright-cli run-code "async page => {
+  await page.context().addCookies([
+    { name: 'session_id', value: 'sess_abc123', domain: 'example.com', path: '/', httpOnly: true },
+    { name: 'preferences', value: JSON.stringify({ theme: 'dark' }), domain: 'example.com', path: '/' }
+  ]);
+}"
+```
+
+## Local Storage
+
+### List All localStorage Items
+
+```bash
+playwright-cli localstorage-list
+```
+
+### Get Single Value
+
+```bash
+playwright-cli localstorage-get token
+```
+
+### Set Value
+
+```bash
+playwright-cli localstorage-set theme dark
+```
+
+### Set JSON Value
+
+```bash
+playwright-cli localstorage-set user_settings '{"theme":"dark","language":"en"}'
+```
+
+### Delete Single Item
+
+```bash
+playwright-cli localstorage-delete token
+```
+
+### Clear All localStorage
+
+```bash
+playwright-cli localstorage-clear
+```
+
+### Advanced: Multiple Operations
+
+For complex scenarios like setting multiple values at once, use `run-code`:
+
+```bash
+playwright-cli run-code "async page => {
+  await page.evaluate(() => {
+    localStorage.setItem('token', 'jwt_abc123');
+    localStorage.setItem('user_id', '12345');
+    localStorage.setItem('expires_at', Date.now() + 3600000);
+  });
+}"
+```
+
+## Session Storage
+
+### List All sessionStorage Items
+
+```bash
+playwright-cli sessionstorage-list
+```
+
+### Get Single Value
+
+```bash
+playwright-cli sessionstorage-get form_data
+```
+
+### Set Value
+
+```bash
+playwright-cli sessionstorage-set step 3
+```
+
+### Delete Single Item
+
+```bash
+playwright-cli sessionstorage-delete step
+```
+
+### Clear sessionStorage
+
+```bash
+playwright-cli sessionstorage-clear
+```
+
+## IndexedDB
+
+### List Databases
+
+```bash
+playwright-cli run-code "async page => {
+  return await page.evaluate(async () => {
+    const databases = await indexedDB.databases();
+    return databases;
+  });
+}"
+```
+
+### Delete Database
+
+```bash
+playwright-cli run-code "async page => {
+  await page.evaluate(() => {
+    indexedDB.deleteDatabase('myDatabase');
+  });
+}"
+```
+
+## Common Patterns
+
+### Authentication State Reuse
+
+```bash
+# Step 1: Login and save state
+playwright-cli open https://app.example.com/login
+playwright-cli snapshot
+playwright-cli fill e1 "user@example.com"
+playwright-cli fill e2 "password123"
+playwright-cli click e3
+
+# Save the authenticated state
+playwright-cli state-save auth.json
+
+# Step 2: Later, restore state and skip login
+playwright-cli state-load auth.json
+playwright-cli open https://app.example.com/dashboard
+# Already logged in!
+```
+
+### Save and Restore Roundtrip
+
+```bash
+# Set up authentication state
+playwright-cli open https://example.com
+playwright-cli eval "() => { document.cookie = 'session=abc123'; localStorage.setItem('user', 'john'); }"
+
+# Save state to file
+playwright-cli state-save my-session.json
+
+# ... later, in a new session ...
+
+# Restore state
+playwright-cli state-load my-session.json
+playwright-cli open https://example.com
+# Cookies and localStorage are restored!
+```
+
+## Security Notes
+
+- Never commit storage state files containing auth tokens
+- Add `*.auth-state.json` to `.gitignore`
+- Delete state files after automation completes
+- Use environment variables for sensitive data
+- By default, sessions run in-memory mode which is safer for sensitive operations
diff --git a/.claude/skills/playwright-cli/references/test-generation.md b/.claude/skills/playwright-cli/references/test-generation.md
new file mode 100644
index 0000000000..7a09df387f
--- /dev/null
+++ b/.claude/skills/playwright-cli/references/test-generation.md
@@ -0,0 +1,88 @@
+# Test Generation
+
+Generate Playwright test code automatically as you interact with the browser.
+
+## How It Works
+
+Every action you perform with `playwright-cli` generates corresponding Playwright TypeScript code.
+This code appears in the output and can be copied directly into your test files.
+
+## Example Workflow
+
+```bash
+# Start a session
+playwright-cli open https://example.com/login
+
+# Take a snapshot to see elements
+playwright-cli snapshot
+# Output shows: e1 [textbox "Email"], e2 [textbox "Password"], e3 [button "Sign In"]
+
+# Fill form fields - generates code automatically
+playwright-cli fill e1 "user@example.com"
+# Ran Playwright code:
+# await page.getByRole('textbox', { name: 'Email' }).fill('user@example.com');
+
+playwright-cli fill e2 "password123"
+# Ran Playwright code:
+# await page.getByRole('textbox', { name: 'Password' }).fill('password123');
+
+playwright-cli click e3
+# Ran Playwright code:
+# await page.getByRole('button', { name: 'Sign In' }).click();
+```
+
+## Building a Test File
+
+Collect the generated code into a Playwright test:
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test('login flow', async ({ page }) => {
+  // Generated code from playwright-cli session:
+  await page.goto('https://example.com/login');
+  await page.getByRole('textbox', { name: 'Email' }).fill('user@example.com');
+  await page.getByRole('textbox', { name: 'Password' }).fill('password123');
+  await page.getByRole('button', { name: 'Sign In' }).click();
+
+  // Add assertions
+  await expect(page).toHaveURL(/.*dashboard/);
+});
+```
+
+## Best Practices
+
+### 1. Use Semantic Locators
+
+The generated code uses role-based locators when possible, which are more resilient:
+
+```typescript
+// Generated (good - semantic)
+await page.getByRole('button', { name: 'Submit' }).click();
+
+// Avoid (fragile - CSS selectors)
+await page.locator('#submit-btn').click();
+```
+
+### 2. Explore Before Recording
+
+Take snapshots to understand the page structure before recording actions:
+
+```bash
+playwright-cli open https://example.com
+playwright-cli snapshot
+# Review the element structure
+playwright-cli click e5
+```
+
+### 3. Add Assertions Manually
+
+Generated code captures actions but not assertions. Add expectations in your test:
+
+```typescript
+// Generated action
+await page.getByRole('button', { name: 'Submit' }).click();
+
+// Manual assertion
+await expect(page.getByText('Success')).toBeVisible();
+```
diff --git a/.claude/skills/playwright-cli/references/tracing.md b/.claude/skills/playwright-cli/references/tracing.md
new file mode 100644
index 0000000000..7ce7babbdf
--- /dev/null
+++ b/.claude/skills/playwright-cli/references/tracing.md
@@ -0,0 +1,139 @@
+# Tracing
+
+Capture detailed execution traces for debugging and analysis. Traces include DOM snapshots, screenshots, network activity, and console logs.
+
+## Basic Usage
+
+```bash
+# Start trace recording
+playwright-cli tracing-start
+
+# Perform actions
+playwright-cli open https://example.com
+playwright-cli click e1
+playwright-cli fill e2 "test"
+
+# Stop trace recording
+playwright-cli tracing-stop
+```
+
+## Trace Output Files
+
+When you start tracing, Playwright creates a `traces/` directory with several files:
+
+### `trace-{timestamp}.trace`
+
+**Action log** - The main trace file containing:
+- Every action performed (clicks, fills, navigations)
+- DOM snapshots before and after each action
+- Screenshots at each step
+- Timing information
+- Console messages
+- Source locations
+
+### `trace-{timestamp}.network`
+
+**Network log** - Complete network activity:
+- All HTTP requests and responses
+- Request headers and bodies
+- Response headers and bodies
+- Timing (DNS, connect, TLS, TTFB, download)
+- Resource sizes
+- Failed requests and errors
+
+### `resources/`
+
+**Resources directory** - Cached resources:
+- Images, fonts, stylesheets, scripts
+- Response bodies for replay
+- Assets needed to reconstruct page state
+
+## What Traces Capture
+
+| Category | Details |
+|----------|---------|
+| **Actions** | Clicks, fills, hovers, keyboard input, navigations |
+| **DOM** | Full DOM snapshot before/after each action |
+| **Screenshots** | Visual state at each step |
+| **Network** | All requests, responses, headers, bodies, timing |
+| **Console** | All console.log, warn, error messages |
+| **Timing** | Precise timing for each operation |
+
+## Use Cases
+
+### Debugging Failed Actions
+
+```bash
+playwright-cli tracing-start
+playwright-cli open https://app.example.com
+
+# This click fails - why?
+playwright-cli click e5
+
+playwright-cli tracing-stop
+# Open trace to see DOM state when click was attempted
+```
+
+### Analyzing Performance
+
+```bash
+playwright-cli tracing-start
+playwright-cli open https://slow-site.com
+playwright-cli tracing-stop
+
+# View network waterfall to identify slow resources
+```
+
+### Capturing Evidence
+
+```bash
+# Record a complete user flow for documentation
+playwright-cli tracing-start
+
+playwright-cli open https://app.example.com/checkout
+playwright-cli fill e1 "4111111111111111"
+playwright-cli fill e2 "12/25"
+playwright-cli fill e3 "123"
+playwright-cli click e4
+
+playwright-cli tracing-stop
+# Trace shows exact sequence of events
+```
+
+## Trace vs Video vs Screenshot
+
+| Feature | Trace | Video | Screenshot |
+|---------|-------|-------|------------|
+| **Format** | .trace file | .webm video | .png/.jpeg image |
+| **DOM inspection** | Yes | No | No |
+| **Network details** | Yes | No | No |
+| **Step-by-step replay** | Yes | Continuous | Single frame |
+| **File size** | Medium | Large | Small |
+| **Best for** | Debugging | Demos | Quick capture |
+
+## Best Practices
+
+### 1. Start Tracing Before the Problem
+
+```bash
+# Trace the entire flow, not just the failing step
+playwright-cli tracing-start
+playwright-cli open https://example.com
+# ... all steps leading to the issue ...
+playwright-cli tracing-stop
+```
+
+### 2. Clean Up Old Traces
+
+Traces can consume significant disk space:
+
+```bash
+# Remove traces older than 7 days
+find .playwright-cli/traces -mtime +7 -delete
+```
+
+## Limitations
+
+- Traces add overhead to automation
+- Large traces can consume significant disk space
+- Some dynamic content may not replay perfectly
diff --git a/.claude/skills/playwright-cli/references/video-recording.md b/.claude/skills/playwright-cli/references/video-recording.md
new file mode 100644
index 0000000000..38391b37ad
--- /dev/null
+++ b/.claude/skills/playwright-cli/references/video-recording.md
@@ -0,0 +1,43 @@
+# Video Recording
+
+Capture browser automation sessions as video for debugging, documentation, or verification. Produces WebM (VP8/VP9 codec).
+
+## Basic Recording
+
+```bash
+# Start recording
+playwright-cli video-start
+
+# Perform actions
+playwright-cli open https://example.com
+playwright-cli snapshot
+playwright-cli click e1
+playwright-cli fill e2 "test input"
+
+# Stop and save
+playwright-cli video-stop demo.webm
+```
+
+## Best Practices
+
+### 1. Use Descriptive Filenames
+
+```bash
+# Include context in filename
+playwright-cli video-stop recordings/login-flow-2024-01-15.webm
+playwright-cli video-stop recordings/checkout-test-run-42.webm
+```
+
+## Tracing vs Video
+
+| Feature | Video | Tracing |
+|---------|-------|---------|
+| Output | WebM file | Trace file (viewable in Trace Viewer) |
+| Shows | Visual recording | DOM snapshots, network, console, actions |
+| Use case | Demos, documentation | Debugging, analysis |
+| Size | Larger | Smaller |
+
+## Limitations
+
+- Recording adds slight overhead to automation
+- Large recordings can consume significant disk space
diff --git a/.claude/skills/research-codebase/SKILL.md b/.claude/skills/research-codebase/SKILL.md
index b54ee81376..b8c1bc5002 100644
--- a/.claude/skills/research-codebase/SKILL.md
+++ b/.claude/skills/research-codebase/SKILL.md
@@ -53,7 +53,7 @@ The user's research question/request is: **$ARGUMENTS**
    **For online search:**
    - VERY IMPORTANT: In case you discover external libraries as dependencies, use the **codebase-online-researcher** agent for external documentation and resources
      - If you use DeepWiki tools, instruct the agent to return references to code snippets or documentation, PLEASE INCLUDE those references (e.g. source file names, line numbers, etc.)
-     - If you perform a web search using the WebFetch/WebSearch tools, instruct the agent to return LINKS with their findings, and please INCLUDE those links in the research document
+      - If you perform external web research, use the **playwright-cli** skill (or `bunx @playwright/cli`) to inspect pages, then instruct the agent to return LINKS with their findings and INCLUDE those links in the research document
      - Output directory: `research/docs/`
      - Examples:
        - If researching `Redis` locks usage, the agent might find relevant usage and create a document `research/docs/2024-01-15-redis-locks-usage.md` with internal links to Redis docs and code references
@@ -207,4 +207,4 @@ research/
 ## Final Output
 
 - A collection of research files with comprehensive research findings, properly formatted and linked, ready for consumption to create detailed specifications or design documents.
-- IMPORTANT: DO NOT generate any other artifacts or files OUTSIDE of the `research/` directory.
\ No newline at end of file
+- IMPORTANT: DO NOT generate any other artifacts or files OUTSIDE of the `research/` directory.
diff --git a/.github/agents/codebase-online-researcher.md b/.github/agents/codebase-online-researcher.md
index d0fe46ca6d..fed00f4003 100644
--- a/.github/agents/codebase-online-researcher.md
+++ b/.github/agents/codebase-online-researcher.md
@@ -1,7 +1,7 @@
 ---
 name: codebase-online-researcher
-description: Do you find yourself desiring information that you don't quite feel well-trained (confident) on? Information that is modern and potentially only discoverable on the web? Use the codebase-online-researcher subagent_type today to find any and all answers to your questions! It will research deeply to figure out and attempt to answer your questions! If you aren't immediately satisfied you can get your money back! (Not really - but you can re-run codebase-online-researcher with an altered prompt in the event you're not satisfied the first time)
-tools: ["search", "read", "execute", "web", "deepwiki/ask_question"]
+description: Do you find yourself desiring information that you don't quite feel well-trained (confident) on? Information that is modern and potentially hard to discover from local context alone? Use the codebase-online-researcher subagent_type today to find any and all answers to your questions! It will research deeply to figure out and attempt to answer your questions! If you aren't immediately satisfied you can get your money back! (Not really - but you can re-run codebase-online-researcher with an altered prompt in the event you're not satisfied the first time)
+tools: ["search", "read", "execute", "deepwiki/ask_question"]
 mcp-servers:
     deepwiki:
         type: http
@@ -9,7 +9,7 @@ mcp-servers:
         tools: ["ask_question"]
 ---
 
-You are an expert web research specialist focused on finding accurate, relevant information from web sources. Your primary tools are the DeepWiki `ask_question` tool and WebFetch/WebSearch tools, which you use to discover and retrieve information based on user queries.
+You are an expert research specialist focused on finding accurate, relevant information from authoritative sources. Your primary tool is the DeepWiki `ask_question` tool, which you use to discover and retrieve information based on user queries.
 
 ## Core Responsibilities
 
@@ -18,26 +18,25 @@ When you receive a research query, you should:
 1. Try to answer using the DeepWiki `ask_question` tool to research best practices on design patterns, architecture, and implementation strategies.
 2. Ask it questions about the system design and constructs in the library that will help you achieve your goals.
 
-If the answer is insufficient, out-of-date, or unavailable, proceed with the following steps for web research:
+If the answer is insufficient, out-of-date, or unavailable, proceed with the following steps:
 
 1. **Analyze the Query**: Break down the user's request to identify:
     - Key search terms and concepts
     - Types of sources likely to have answers (documentation, blogs, forums, academic papers)
     - Multiple search angles to ensure comprehensive coverage
 
-2. **Execute Strategic Searches**:
-    - Start with broad searches to understand the landscape
+2. **Execute Strategic DeepWiki Queries**:
+    - Start with broad repository or topic queries to understand the landscape
     - Refine with specific technical terms and phrases
-    - Use multiple search variations to capture different perspectives
-    - Include site-specific searches when targeting known authoritative sources (e.g., "site:docs.stripe.com webhook signature")
+    - Use multiple query variations to capture different perspectives
+    - Prioritize queries for official repositories and documentation-focused sources
 
-3. **Fetch and Analyze Content**:
-    - Use WebFetch and WebSearch tools to retrieve full content from promising search results
-    - Prioritize official documentation, reputable technical blogs, and authoritative sources
+3. **Analyze Retrieved Content**:
+    - Prioritize official documentation, reputable technical blogs, and authoritative sources available through DeepWiki
     - Extract specific quotes and sections relevant to the query
     - Note publication dates to ensure currency of information
 
-Finally, for both DeepWiki and WebFetch/WebSearch research findings:
+Finally, for all research findings:
 
 4. **Synthesize Findings**:
     - Organize information by relevance and authority
@@ -121,4 +120,4 @@ Structure your findings as:
 - Use search operators effectively: quotes for exact phrases, minus for exclusions, site: for specific domains
 - Consider searching in different forms: tutorials, documentation, Q&A sites, and discussion forums
 
-Remember: You are the user's expert guide to web information. Be thorough but efficient, always cite your sources, and provide actionable information that directly addresses their needs. Think deeply as you work.
+Remember: You are the user's expert guide to external technical information. Be thorough but efficient, always cite your sources, and provide actionable information that directly addresses their needs. Think deeply as you work.
diff --git a/.github/agents/debugger.md b/.github/agents/debugger.md
index 176e43780c..809ae4bd45 100644
--- a/.github/agents/debugger.md
+++ b/.github/agents/debugger.md
@@ -8,7 +8,6 @@ tools:
         "edit",
         "search",
         "read",
-        "web",
         "deepwiki/ask_question",
     ]
 mcp-servers:
@@ -23,7 +22,6 @@ You are tasked with debugging and identifying errors, test failures, and unexpec
 Available tools:
 
 - DeepWiki (`ask_question`): Look up documentation for external libraries and frameworks
-- WebFetch/WebSearch: Retrieve web content for additional context if you don't find sufficient information in DeepWiki
 
 When invoked:
 1a. If the user doesn't provide specific error details output:
@@ -54,7 +52,6 @@ Debugging process:
 - Add strategic debug logging
 - Inspect variable states
 - Use DeepWiki to look up external library documentation when errors involve third-party dependencies
-- Use WebFetch/WebSearch to gather additional context from web sources if needed
 
 For each issue, provide:
 
diff --git a/.github/agents/planner.md b/.github/agents/planner.md
new file mode 100644
index 0000000000..d38b1fb425
--- /dev/null
+++ b/.github/agents/planner.md
@@ -0,0 +1,128 @@
+---
+description: Decomposes user prompts into structured task lists for the Ralph workflow.
+mode: primary
+tools:
+    write: false
+    edit: false
+    bash: false
+    todowrite: false
+    question: false
+    lsp: false
+    skill: false
+---
+
+You are the planner agent for the Ralph autonomous implementation workflow.
+
+Your job is to decompose the user's feature request into a structured, ordered list of implementation tasks.
+
+# Input
+
+You will receive a feature specification or user request describing what needs to be implemented.
+
+# Output Format
+
+Return a JSON array of task objects with the following structure:
+
+```json
+[
+  {
+    "id": "#1",
+    "content": "Task description",
+    "status": "pending",
+    "activeForm": "Active form description (gerund, e.g., 'Implementing auth module')",
+    "blockedBy": []
+  },
+  {
+    "id": "#2",
+    "content": "Another task description",
+    "status": "pending",
+    "activeForm": "Active form description",
+    "blockedBy": ["#1"]
+  }
+]
+```
+
+# Task Decomposition Guidelines
+
+1. **Break down into atomic tasks**: Each task should be a single, focused unit of work that can be completed independently (unless it has dependencies).
+
+2. **Order by dependencies**: Use the `blockedBy` array to specify task dependencies. A task with `"blockedBy": ["#1"]` cannot start until task #1 is completed.
+
+3. **Be specific**: Task descriptions should be clear and actionable. Avoid vague descriptions like "fix bugs" or "improve performance".
+
+4. **Use gerunds for activeForm**: The `activeForm` field should describe the task in progress using a gerund (e.g., "Implementing", "Adding", "Refactoring").
+
+5. **Start simple**: Begin with foundational tasks (e.g., setup, configuration) before moving to feature implementation.
+
+6. **Consider testing**: Include tasks for writing tests where appropriate.
+
+7. **Typical task categories**:
+   - Setup/configuration tasks
+   - Model/data structure definitions
+   - Core logic implementation
+   - UI/presentation layer
+   - Integration tasks
+   - Testing tasks
+   - Documentation tasks
+
+# Example
+
+**Input**: "Add user authentication to the app"
+
+**Output**:
+```json
+[
+  {
+    "id": "#1",
+    "content": "Define user model and authentication schema",
+    "status": "pending",
+    "activeForm": "Defining user model and auth schema",
+    "blockedBy": []
+  },
+  {
+    "id": "#2",
+    "content": "Implement password hashing and validation utilities",
+    "status": "pending",
+    "activeForm": "Implementing password utilities",
+    "blockedBy": ["#1"]
+  },
+  {
+    "id": "#3",
+    "content": "Create registration endpoint with validation",
+    "status": "pending",
+    "activeForm": "Creating registration endpoint",
+    "blockedBy": ["#1", "#2"]
+  },
+  {
+    "id": "#4",
+    "content": "Create login endpoint with JWT token generation",
+    "status": "pending",
+    "activeForm": "Creating login endpoint",
+    "blockedBy": ["#1", "#2"]
+  },
+  {
+    "id": "#5",
+    "content": "Add authentication middleware for protected routes",
+    "status": "pending",
+    "activeForm": "Adding auth middleware",
+    "blockedBy": ["#4"]
+  },
+  {
+    "id": "#6",
+    "content": "Write integration tests for auth endpoints",
+    "status": "pending",
+    "activeForm": "Writing auth integration tests",
+    "blockedBy": ["#3", "#4", "#5"]
+  }
+]
+```
+
+# Important Notes
+
+- Always return valid JSON
+- Ensure all task IDs are unique
+- Use consistent ID format (#1, #2, #3, etc.)
+- The `status` field should always be "pending" for new tasks
+- Dependencies in `blockedBy` must reference valid task IDs
+- Keep task descriptions concise but descriptive (aim for 5-10 words)
+- Aim for 3-8 tasks total for most features (adjust based on complexity)
diff --git a/.github/agents/reviewer.md b/.github/agents/reviewer.md
index a7cd8aa36c..db1f8a0e9b 100644
--- a/.github/agents/reviewer.md
+++ b/.github/agents/reviewer.md
@@ -1,7 +1,7 @@
 ---
 name: reviewer
 description: Code reviewer for proposed code changes.
-tools: ["execute", "agent", "search", "read", "web", "deepwiki/ask_question"]
+tools: ["execute", "agent", "search", "read", "deepwiki/ask_question"]
 mcp-servers:
     deepwiki:
         type: http
diff --git a/.github/agents/worker.md b/.github/agents/worker.md
index f011e69315..b886c1c3f0 100644
--- a/.github/agents/worker.md
+++ b/.github/agents/worker.md
@@ -86,7 +86,7 @@ Use the "Gang of Four" patterns as a shared vocabulary to solve recurring proble
 
 When you encounter ANY bug — whether introduced by your changes, discovered during testing, or pre-existing — you MUST follow this protocol:
 
-1. **Delegate debugging**: Use the Task tool to spawn a debugger agent. It can navigate the web for best practices.
+1. **Delegate debugging**: Use the Task tool to spawn a debugger agent. It can use DeepWiki for framework and library best practices.
 2. **Add the bug fix to the TOP of the task list AND update `blockedBy` on affected tasks**: Update `~/.atomic/workflows/{session_id}/tasks.json` with the bug fix as the FIRST item in the array (highest priority). Then, for every task whose work depends on the bug being fixed first, add the bug fix task's ID to that task's `blockedBy` array. This ensures those tasks cannot be started until the fix lands. Example:
     ```json
     [
diff --git a/.github/skills/explain-code/SKILL.md b/.github/skills/explain-code/SKILL.md
index b96d66aa0e..b3f60a5960 100644
--- a/.github/skills/explain-code/SKILL.md
+++ b/.github/skills/explain-code/SKILL.md
@@ -9,7 +9,7 @@ description: Explain code functionality in detail.
 The following MCP tools are available and SHOULD be used when relevant:
 
 - **DeepWiki** (`ask_question`): Use to look up documentation for external libraries, frameworks, and GitHub repositories. Particularly useful for understanding third-party dependencies and their APIs.
-- **WebFetch/WebSearch**: Use to retrieve web content for additional context if information is not found in DeepWiki.
+- **Playwright CLI** (`playwright-cli`): Use to retrieve web content, browse documentation, and extract data from web pages if information is not found in DeepWiki. Invoke via the `/playwright-cli` skill or run `bunx playwright-cli` commands directly.
 
 ## Instructions
 
@@ -81,6 +81,7 @@ Follow this systematic approach to explain code: **$ARGUMENTS**
     - Identify debugging points and logging
     - Describe mock data or test scenarios
     - Explain test helpers and utilities
+    - Use `playwright-cli` to reproduce browser interactions and validate frontend behavior when applicable
 
 12. **Dependencies and Integrations**
     - Explain external service integrations
@@ -202,4 +203,5 @@ Remember to:
 - Structure explanations logically from high-level to detailed
 - Include visual diagrams or flowcharts when helpful
 - Tailor the explanation level to the intended audience
-- Use DeepWiki to look up external library documentation when encountering unfamiliar dependencies
\ No newline at end of file
+- Use DeepWiki to look up external library documentation when encountering unfamiliar dependencies
+- Use `playwright-cli` for live browser inspection when static code analysis is not enough
diff --git a/.github/skills/playwright-cli/SKILL.md b/.github/skills/playwright-cli/SKILL.md
new file mode 100644
index 0000000000..11bad2b874
--- /dev/null
+++ b/.github/skills/playwright-cli/SKILL.md
@@ -0,0 +1,278 @@
+---
+name: playwright-cli
+description: Automates browser interactions for web testing, form filling, screenshots, and data extraction. Use when the user needs to navigate websites, interact with web pages, fill forms, take screenshots, test web applications, or extract information from web pages.
+allowed-tools: Bash(playwright-cli:*)
+---
+
+# Browser Automation with playwright-cli
+
+## Quick start
+
+```bash
+# open new browser
+playwright-cli open
+# navigate to a page
+playwright-cli goto https://playwright.dev
+# interact with the page using refs from the snapshot
+playwright-cli click e15
+playwright-cli type "page.click"
+playwright-cli press Enter
+# take a screenshot (rarely used, as snapshot is more common)
+playwright-cli screenshot
+# close the browser
+playwright-cli close
+```
+
+## Commands
+
+### Core
+
+```bash
+playwright-cli open
+# open and navigate right away
+playwright-cli open https://example.com/
+playwright-cli goto https://playwright.dev
+playwright-cli type "search query"
+playwright-cli click e3
+playwright-cli dblclick e7
+playwright-cli fill e5 "user@example.com"
+playwright-cli drag e2 e8
+playwright-cli hover e4
+playwright-cli select e9 "option-value"
+playwright-cli upload ./document.pdf
+playwright-cli check e12
+playwright-cli uncheck e12
+playwright-cli snapshot
+playwright-cli snapshot --filename=after-click.yaml
+playwright-cli eval "document.title"
+playwright-cli eval "el => el.textContent" e5
+playwright-cli dialog-accept
+playwright-cli dialog-accept "confirmation text"
+playwright-cli dialog-dismiss
+playwright-cli resize 1920 1080
+playwright-cli close
+```
+
+### Navigation
+
+```bash
+playwright-cli go-back
+playwright-cli go-forward
+playwright-cli reload
+```
+
+### Keyboard
+
+```bash
+playwright-cli press Enter
+playwright-cli press ArrowDown
+playwright-cli keydown Shift
+playwright-cli keyup Shift
+```
+
+### Mouse
+
+```bash
+playwright-cli mousemove 150 300
+playwright-cli mousedown
+playwright-cli mousedown right
+playwright-cli mouseup
+playwright-cli mouseup right
+playwright-cli mousewheel 0 100
+```
+
+### Save as
+
+```bash
+playwright-cli screenshot
+playwright-cli screenshot e5
+playwright-cli screenshot --filename=page.png
+playwright-cli pdf --filename=page.pdf
+```
+
+### Tabs
+
+```bash
+playwright-cli tab-list
+playwright-cli tab-new
+playwright-cli tab-new https://example.com/page
+playwright-cli tab-close
+playwright-cli tab-close 2
+playwright-cli tab-select 0
+```
+
+### Storage
+
+```bash
+playwright-cli state-save
+playwright-cli state-save auth.json
+playwright-cli state-load auth.json
+
+# Cookies
+playwright-cli cookie-list
+playwright-cli cookie-list --domain=example.com
+playwright-cli cookie-get session_id
+playwright-cli cookie-set session_id abc123
+playwright-cli cookie-set session_id abc123 --domain=example.com --httpOnly --secure
+playwright-cli cookie-delete session_id
+playwright-cli cookie-clear
+
+# LocalStorage
+playwright-cli localstorage-list
+playwright-cli localstorage-get theme
+playwright-cli localstorage-set theme dark
+playwright-cli localstorage-delete theme
+playwright-cli localstorage-clear
+
+# SessionStorage
+playwright-cli sessionstorage-list
+playwright-cli sessionstorage-get step
+playwright-cli sessionstorage-set step 3
+playwright-cli sessionstorage-delete step
+playwright-cli sessionstorage-clear
+```
+
+### Network
+
+```bash
+playwright-cli route "**/*.jpg" --status=404
+playwright-cli route "https://api.example.com/**" --body='{"mock": true}'
+playwright-cli route-list
+playwright-cli unroute "**/*.jpg"
+playwright-cli unroute
+```
+
+### DevTools
+
+```bash
+playwright-cli console
+playwright-cli console warning
+playwright-cli network
+playwright-cli run-code "async page => await page.context().grantPermissions(['geolocation'])"
+playwright-cli tracing-start
+playwright-cli tracing-stop
+playwright-cli video-start
+playwright-cli video-stop video.webm
+```
+
+## Open parameters
+```bash
+# Use specific browser when creating session
+playwright-cli open --browser=chrome
+playwright-cli open --browser=firefox
+playwright-cli open --browser=webkit
+playwright-cli open --browser=msedge
+# Connect to browser via extension
+playwright-cli open --extension
+
+# Use persistent profile (by default profile is in-memory)
+playwright-cli open --persistent
+# Use persistent profile with custom directory
+playwright-cli open --profile=/path/to/profile
+
+# Start with config file
+playwright-cli open --config=my-config.json
+
+# Close the browser
+playwright-cli close
+# Delete user data for the default session
+playwright-cli delete-data
+```
+
+## Snapshots
+
+After each command, playwright-cli provides a snapshot of the current browser state.
+
+```bash
+> playwright-cli goto https://example.com
+### Page
+- Page URL: https://example.com/
+- Page Title: Example Domain
+### Snapshot
+[Snapshot](.playwright-cli/page-2026-02-14T19-22-42-679Z.yml)
+```
+
+You can also take a snapshot on demand using `playwright-cli snapshot` command.
+
+If `--filename` is not provided, a new snapshot file is created with a timestamp. Default to automatic file naming, use `--filename=` when artifact is a part of the workflow result.
+
+## Browser Sessions
+
+```bash
+# create new browser session named "mysession" with persistent profile
+playwright-cli -s=mysession open example.com --persistent
+# same with manually specified profile directory (use when requested explicitly)
+playwright-cli -s=mysession open example.com --profile=/path/to/profile
+playwright-cli -s=mysession click e6
+playwright-cli -s=mysession close  # stop a named browser
+playwright-cli -s=mysession delete-data  # delete user data for persistent session
+
+playwright-cli list
+# Close all browsers
+playwright-cli close-all
+# Forcefully kill all browser processes
+playwright-cli kill-all
+```
+
+## Local installation
+
+In some cases user might want to install playwright-cli locally. If running globally available `playwright-cli` binary fails, use `npx playwright-cli` to run the commands. For example:
+
+```bash
+npx playwright-cli open https://example.com
+npx playwright-cli click e1
+```
+
+## Example: Form submission
+
+```bash
+playwright-cli open https://example.com/form
+playwright-cli snapshot
+
+playwright-cli fill e1 "user@example.com"
+playwright-cli fill e2 "password123"
+playwright-cli click e3
+playwright-cli snapshot
+playwright-cli close
+```
+
+## Example: Multi-tab workflow
+
+```bash
+playwright-cli open https://example.com
+playwright-cli tab-new https://example.com/other
+playwright-cli tab-list
+playwright-cli tab-select 0
+playwright-cli snapshot
+playwright-cli close
+```
+
+## Example: Debugging with DevTools
+
+```bash
+playwright-cli open https://example.com
+playwright-cli click e4
+playwright-cli fill e7 "test"
+playwright-cli console
+playwright-cli network
+playwright-cli close
+```
+
+```bash
+playwright-cli open https://example.com
+playwright-cli tracing-start
+playwright-cli click e4
+playwright-cli fill e7 "test"
+playwright-cli tracing-stop
+playwright-cli close
+```
+
+## Specific tasks
+
+* **Request mocking** [references/request-mocking.md](references/request-mocking.md)
+* **Running Playwright code** [references/running-code.md](references/running-code.md)
+* **Browser session management** [references/session-management.md](references/session-management.md)
+* **Storage state (cookies, localStorage)** [references/storage-state.md](references/storage-state.md)
+* **Test generation** [references/test-generation.md](references/test-generation.md)
+* **Tracing** [references/tracing.md](references/tracing.md)
+* **Video recording** [references/video-recording.md](references/video-recording.md)
diff --git a/.github/skills/playwright-cli/references/request-mocking.md b/.github/skills/playwright-cli/references/request-mocking.md
new file mode 100644
index 0000000000..9005fda67d
--- /dev/null
+++ b/.github/skills/playwright-cli/references/request-mocking.md
@@ -0,0 +1,87 @@
+# Request Mocking
+
+Intercept, mock, modify, and block network requests.
+
+## CLI Route Commands
+
+```bash
+# Mock with custom status
+playwright-cli route "**/*.jpg" --status=404
+
+# Mock with JSON body
+playwright-cli route "**/api/users" --body='[{"id":1,"name":"Alice"}]' --content-type=application/json
+
+# Mock with custom headers
+playwright-cli route "**/api/data" --body='{"ok":true}' --header="X-Custom: value"
+
+# Remove headers from requests
+playwright-cli route "**/*" --remove-header=cookie,authorization
+
+# List active routes
+playwright-cli route-list
+
+# Remove a route or all routes
+playwright-cli unroute "**/*.jpg"
+playwright-cli unroute
+```
+
+## URL Patterns
+
+```
+**/api/users           - Exact path match
+**/api/*/details       - Wildcard in path
+**/*.{png,jpg,jpeg}    - Match file extensions
+**/search?q=*          - Match query parameters
+```
+
+## Advanced Mocking with run-code
+
+For conditional responses, request body inspection, response modification, or delays:
+
+### Conditional Response Based on Request
+
+```bash
+playwright-cli run-code "async page => {
+  await page.route('**/api/login', route => {
+    const body = route.request().postDataJSON();
+    if (body.username === 'admin') {
+      route.fulfill({ body: JSON.stringify({ token: 'mock-token' }) });
+    } else {
+      route.fulfill({ status: 401, body: JSON.stringify({ error: 'Invalid' }) });
+    }
+  });
+}"
+```
+
+### Modify Real Response
+
+```bash
+playwright-cli run-code "async page => {
+  await page.route('**/api/user', async route => {
+    const response = await route.fetch();
+    const json = await response.json();
+    json.isPremium = true;
+    await route.fulfill({ response, json });
+  });
+}"
+```
+
+### Simulate Network Failures
+
+```bash
+playwright-cli run-code "async page => {
+  await page.route('**/api/offline', route => route.abort('internetdisconnected'));
+}"
+# Options: connectionrefused, timedout, connectionreset, internetdisconnected
+```
+
+### Delayed Response
+
+```bash
+playwright-cli run-code "async page => {
+  await page.route('**/api/slow', async route => {
+    await new Promise(r => setTimeout(r, 3000));
+    route.fulfill({ body: JSON.stringify({ data: 'loaded' }) });
+  });
+}"
+```
diff --git a/.github/skills/playwright-cli/references/running-code.md b/.github/skills/playwright-cli/references/running-code.md
new file mode 100644
index 0000000000..7d6d22fd09
--- /dev/null
+++ b/.github/skills/playwright-cli/references/running-code.md
@@ -0,0 +1,232 @@
+# Running Custom Playwright Code
+
+Use `run-code` to execute arbitrary Playwright code for advanced scenarios not covered by CLI commands.
+
+## Syntax
+
+```bash
+playwright-cli run-code "async page => {
+  // Your Playwright code here
+  // Access page.context() for browser context operations
+}"
+```
+
+## Geolocation
+
+```bash
+# Grant geolocation permission and set location
+playwright-cli run-code "async page => {
+  await page.context().grantPermissions(['geolocation']);
+  await page.context().setGeolocation({ latitude: 37.7749, longitude: -122.4194 });
+}"
+
+# Set location to London
+playwright-cli run-code "async page => {
+  await page.context().grantPermissions(['geolocation']);
+  await page.context().setGeolocation({ latitude: 51.5074, longitude: -0.1278 });
+}"
+
+# Clear geolocation override
+playwright-cli run-code "async page => {
+  await page.context().clearPermissions();
+}"
+```
+
+## Permissions
+
+```bash
+# Grant multiple permissions
+playwright-cli run-code "async page => {
+  await page.context().grantPermissions([
+    'geolocation',
+    'notifications',
+    'camera',
+    'microphone'
+  ]);
+}"
+
+# Grant permissions for specific origin
+playwright-cli run-code "async page => {
+  await page.context().grantPermissions(['clipboard-read'], {
+    origin: 'https://example.com'
+  });
+}"
+```
+
+## Media Emulation
+
+```bash
+# Emulate dark color scheme
+playwright-cli run-code "async page => {
+  await page.emulateMedia({ colorScheme: 'dark' });
+}"
+
+# Emulate light color scheme
+playwright-cli run-code "async page => {
+  await page.emulateMedia({ colorScheme: 'light' });
+}"
+
+# Emulate reduced motion
+playwright-cli run-code "async page => {
+  await page.emulateMedia({ reducedMotion: 'reduce' });
+}"
+
+# Emulate print media
+playwright-cli run-code "async page => {
+  await page.emulateMedia({ media: 'print' });
+}"
+```
+
+## Wait Strategies
+
+```bash
+# Wait for network idle
+playwright-cli run-code "async page => {
+  await page.waitForLoadState('networkidle');
+}"
+
+# Wait for specific element
+playwright-cli run-code "async page => {
+  await page.waitForSelector('.loading', { state: 'hidden' });
+}"
+
+# Wait for function to return true
+playwright-cli run-code "async page => {
+  await page.waitForFunction(() => window.appReady === true);
+}"
+
+# Wait with timeout
+playwright-cli run-code "async page => {
+  await page.waitForSelector('.result', { timeout: 10000 });
+}"
+```
+
+## Frames and Iframes
+
+```bash
+# Work with iframe
+playwright-cli run-code "async page => {
+  const frame = page.locator('iframe#my-iframe').contentFrame();
+  await frame.locator('button').click();
+}"
+
+# Get all frames
+playwright-cli run-code "async page => {
+  const frames = page.frames();
+  return frames.map(f => f.url());
+}"
+```
+
+## File Downloads
+
+```bash
+# Handle file download
+playwright-cli run-code "async page => {
+  const [download] = await Promise.all([
+    page.waitForEvent('download'),
+    page.click('a.download-link')
+  ]);
+  await download.saveAs('./downloaded-file.pdf');
+  return download.suggestedFilename();
+}"
+```
+
+## Clipboard
+
+```bash
+# Read clipboard (requires permission)
+playwright-cli run-code "async page => {
+  await page.context().grantPermissions(['clipboard-read']);
+  return await page.evaluate(() => navigator.clipboard.readText());
+}"
+
+# Write to clipboard
+playwright-cli run-code "async page => {
+  await page.evaluate(text => navigator.clipboard.writeText(text), 'Hello clipboard!');
+}"
+```
+
+## Page Information
+
+```bash
+# Get page title
+playwright-cli run-code "async page => {
+  return await page.title();
+}"
+
+# Get current URL
+playwright-cli run-code "async page => {
+  return page.url();
+}"
+
+# Get page content
+playwright-cli run-code "async page => {
+  return await page.content();
+}"
+
+# Get viewport size
+playwright-cli run-code "async page => {
+  return page.viewportSize();
+}"
+```
+
+## JavaScript Execution
+
+```bash
+# Execute JavaScript and return result
+playwright-cli run-code "async page => {
+  return await page.evaluate(() => {
+    return {
+      userAgent: navigator.userAgent,
+      language: navigator.language,
+      cookiesEnabled: navigator.cookieEnabled
+    };
+  });
+}"
+
+# Pass arguments to evaluate
+playwright-cli run-code "async page => {
+  const multiplier = 5;
+  return await page.evaluate(m => document.querySelectorAll('li').length * m, multiplier);
+}"
+```
+
+## Error Handling
+
+```bash
+# Try-catch in run-code
+playwright-cli run-code "async page => {
+  try {
+    await page.click('.maybe-missing', { timeout: 1000 });
+    return 'clicked';
+  } catch (e) {
+    return 'element not found';
+  }
+}"
+```
+
+## Complex Workflows
+
+```bash
+# Login and save state
+playwright-cli run-code "async page => {
+  await page.goto('https://example.com/login');
+  await page.fill('input[name=email]', 'user@example.com');
+  await page.fill('input[name=password]', 'secret');
+  await page.click('button[type=submit]');
+  await page.waitForURL('**/dashboard');
+  await page.context().storageState({ path: 'auth.json' });
+  return 'Login successful';
+}"
+
+# Scrape data from multiple pages
+playwright-cli run-code "async page => {
+  const results = [];
+  for (let i = 1; i <= 3; i++) {
+    await page.goto(\`https://example.com/page/\${i}\`);
+    const items = await page.locator('.item').allTextContents();
+    results.push(...items);
+  }
+  return results;
+}"
+```
diff --git a/.github/skills/playwright-cli/references/session-management.md b/.github/skills/playwright-cli/references/session-management.md
new file mode 100644
index 0000000000..fac96066c9
--- /dev/null
+++ b/.github/skills/playwright-cli/references/session-management.md
@@ -0,0 +1,169 @@
+# Browser Session Management
+
+Run multiple isolated browser sessions concurrently with state persistence.
+
+## Named Browser Sessions
+
+Use `-s` flag to isolate browser contexts:
+
+```bash
+# Browser 1: Authentication flow
+playwright-cli -s=auth open https://app.example.com/login
+
+# Browser 2: Public browsing (separate cookies, storage)
+playwright-cli -s=public open https://example.com
+
+# Commands are isolated by browser session
+playwright-cli -s=auth fill e1 "user@example.com"
+playwright-cli -s=public snapshot
+```
+
+## Browser Session Isolation Properties
+
+Each browser session has independent:
+- Cookies
+- LocalStorage / SessionStorage
+- IndexedDB
+- Cache
+- Browsing history
+- Open tabs
+
+## Browser Session Commands
+
+```bash
+# List all browser sessions
+playwright-cli list
+
+# Stop a browser session (close the browser)
+playwright-cli close                # stop the default browser
+playwright-cli -s=mysession close   # stop a named browser
+
+# Stop all browser sessions
+playwright-cli close-all
+
+# Forcefully kill all daemon processes (for stale/zombie processes)
+playwright-cli kill-all
+
+# Delete browser session user data (profile directory)
+playwright-cli delete-data                # delete default browser data
+playwright-cli -s=mysession delete-data   # delete named browser data
+```
+
+## Environment Variable
+
+Set a default browser session name via environment variable:
+
+```bash
+export PLAYWRIGHT_CLI_SESSION="mysession"
+playwright-cli open example.com  # Uses "mysession" automatically
+```
+
+## Common Patterns
+
+### Concurrent Scraping
+
+```bash
+#!/bin/bash
+# Scrape multiple sites concurrently
+
+# Start all browsers
+playwright-cli -s=site1 open https://site1.com &
+playwright-cli -s=site2 open https://site2.com &
+playwright-cli -s=site3 open https://site3.com &
+wait
+
+# Take snapshots from each
+playwright-cli -s=site1 snapshot
+playwright-cli -s=site2 snapshot
+playwright-cli -s=site3 snapshot
+
+# Cleanup
+playwright-cli close-all
+```
+
+### A/B Testing Sessions
+
+```bash
+# Test different user experiences
+playwright-cli -s=variant-a open "https://app.com?variant=a"
+playwright-cli -s=variant-b open "https://app.com?variant=b"
+
+# Compare
+playwright-cli -s=variant-a screenshot
+playwright-cli -s=variant-b screenshot
+```
+
+### Persistent Profile
+
+By default, browser profile is kept in memory only. Use `--persistent` flag on `open` to persist the browser profile to disk:
+
+```bash
+# Use persistent profile (auto-generated location)
+playwright-cli open https://example.com --persistent
+
+# Use persistent profile with custom directory
+playwright-cli open https://example.com --profile=/path/to/profile
+```
+
+## Default Browser Session
+
+When `-s` is omitted, commands use the default browser session:
+
+```bash
+# These use the same default browser session
+playwright-cli open https://example.com
+playwright-cli snapshot
+playwright-cli close  # Stops default browser
+```
+
+## Browser Session Configuration
+
+Configure a browser session with specific settings when opening:
+
+```bash
+# Open with config file
+playwright-cli open https://example.com --config=.playwright/my-cli.json
+
+# Open with specific browser
+playwright-cli open https://example.com --browser=firefox
+
+# Open in headed mode
+playwright-cli open https://example.com --headed
+
+# Open with persistent profile
+playwright-cli open https://example.com --persistent
+```
+
+## Best Practices
+
+### 1. Name Browser Sessions Semantically
+
+```bash
+# GOOD: Clear purpose
+playwright-cli -s=github-auth open https://github.com
+playwright-cli -s=docs-scrape open https://docs.example.com
+
+# AVOID: Generic names
+playwright-cli -s=s1 open https://github.com
+```
+
+### 2. Always Clean Up
+
+```bash
+# Stop browsers when done
+playwright-cli -s=auth close
+playwright-cli -s=scrape close
+
+# Or stop all at once
+playwright-cli close-all
+
+# If browsers become unresponsive or zombie processes remain
+playwright-cli kill-all
+```
+
+### 3. Delete Stale Browser Data
+
+```bash
+# Remove old browser data to free disk space
+playwright-cli -s=oldsession delete-data
+```
diff --git a/.github/skills/playwright-cli/references/storage-state.md b/.github/skills/playwright-cli/references/storage-state.md
new file mode 100644
index 0000000000..c856db5e40
--- /dev/null
+++ b/.github/skills/playwright-cli/references/storage-state.md
@@ -0,0 +1,275 @@
+# Storage Management
+
+Manage cookies, localStorage, sessionStorage, and browser storage state.
+
+## Storage State
+
+Save and restore complete browser state including cookies and storage.
+
+### Save Storage State
+
+```bash
+# Save to auto-generated filename (storage-state-{timestamp}.json)
+playwright-cli state-save
+
+# Save to specific filename
+playwright-cli state-save my-auth-state.json
+```
+
+### Restore Storage State
+
+```bash
+# Load storage state from file
+playwright-cli state-load my-auth-state.json
+
+# Reload page to apply cookies
+playwright-cli open https://example.com
+```
+
+### Storage State File Format
+
+The saved file contains:
+
+```json
+{
+  "cookies": [
+    {
+      "name": "session_id",
+      "value": "abc123",
+      "domain": "example.com",
+      "path": "/",
+      "expires": 1735689600,
+      "httpOnly": true,
+      "secure": true,
+      "sameSite": "Lax"
+    }
+  ],
+  "origins": [
+    {
+      "origin": "https://example.com",
+      "localStorage": [
+        { "name": "theme", "value": "dark" },
+        { "name": "user_id", "value": "12345" }
+      ]
+    }
+  ]
+}
+```
+
+## Cookies
+
+### List All Cookies
+
+```bash
+playwright-cli cookie-list
+```
+
+### Filter Cookies by Domain
+
+```bash
+playwright-cli cookie-list --domain=example.com
+```
+
+### Filter Cookies by Path
+
+```bash
+playwright-cli cookie-list --path=/api
+```
+
+### Get Specific Cookie
+
+```bash
+playwright-cli cookie-get session_id
+```
+
+### Set a Cookie
+
+```bash
+# Basic cookie
+playwright-cli cookie-set session abc123
+
+# Cookie with options
+playwright-cli cookie-set session abc123 --domain=example.com --path=/ --httpOnly --secure --sameSite=Lax
+
+# Cookie with expiration (Unix timestamp)
+playwright-cli cookie-set remember_me token123 --expires=1735689600
+```
+
+### Delete a Cookie
+
+```bash
+playwright-cli cookie-delete session_id
+```
+
+### Clear All Cookies
+
+```bash
+playwright-cli cookie-clear
+```
+
+### Advanced: Multiple Cookies or Custom Options
+
+For complex scenarios like adding multiple cookies at once, use `run-code`:
+
+```bash
+playwright-cli run-code "async page => {
+  await page.context().addCookies([
+    { name: 'session_id', value: 'sess_abc123', domain: 'example.com', path: '/', httpOnly: true },
+    { name: 'preferences', value: JSON.stringify({ theme: 'dark' }), domain: 'example.com', path: '/' }
+  ]);
+}"
+```
+
+## Local Storage
+
+### List All localStorage Items
+
+```bash
+playwright-cli localstorage-list
+```
+
+### Get Single Value
+
+```bash
+playwright-cli localstorage-get token
+```
+
+### Set Value
+
+```bash
+playwright-cli localstorage-set theme dark
+```
+
+### Set JSON Value
+
+```bash
+playwright-cli localstorage-set user_settings '{"theme":"dark","language":"en"}'
+```
+
+### Delete Single Item
+
+```bash
+playwright-cli localstorage-delete token
+```
+
+### Clear All localStorage
+
+```bash
+playwright-cli localstorage-clear
+```
+
+### Advanced: Multiple Operations
+
+For complex scenarios like setting multiple values at once, use `run-code`:
+
+```bash
+playwright-cli run-code "async page => {
+  await page.evaluate(() => {
+    localStorage.setItem('token', 'jwt_abc123');
+    localStorage.setItem('user_id', '12345');
+    localStorage.setItem('expires_at', Date.now() + 3600000);
+  });
+}"
+```
+
+## Session Storage
+
+### List All sessionStorage Items
+
+```bash
+playwright-cli sessionstorage-list
+```
+
+### Get Single Value
+
+```bash
+playwright-cli sessionstorage-get form_data
+```
+
+### Set Value
+
+```bash
+playwright-cli sessionstorage-set step 3
+```
+
+### Delete Single Item
+
+```bash
+playwright-cli sessionstorage-delete step
+```
+
+### Clear sessionStorage
+
+```bash
+playwright-cli sessionstorage-clear
+```
+
+## IndexedDB
+
+### List Databases
+
+```bash
+playwright-cli run-code "async page => {
+  return await page.evaluate(async () => {
+    const databases = await indexedDB.databases();
+    return databases;
+  });
+}"
+```
+
+### Delete Database
+
+```bash
+playwright-cli run-code "async page => {
+  await page.evaluate(() => {
+    indexedDB.deleteDatabase('myDatabase');
+  });
+}"
+```
+
+## Common Patterns
+
+### Authentication State Reuse
+
+```bash
+# Step 1: Login and save state
+playwright-cli open https://app.example.com/login
+playwright-cli snapshot
+playwright-cli fill e1 "user@example.com"
+playwright-cli fill e2 "password123"
+playwright-cli click e3
+
+# Save the authenticated state
+playwright-cli state-save auth.json
+
+# Step 2: Later, restore state and skip login
+playwright-cli state-load auth.json
+playwright-cli open https://app.example.com/dashboard
+# Already logged in!
+```
+
+### Save and Restore Roundtrip
+
+```bash
+# Set up authentication state
+playwright-cli open https://example.com
+playwright-cli eval "() => { document.cookie = 'session=abc123'; localStorage.setItem('user', 'john'); }"
+
+# Save state to file
+playwright-cli state-save my-session.json
+
+# ... later, in a new session ...
+
+# Restore state
+playwright-cli state-load my-session.json
+playwright-cli open https://example.com
+# Cookies and localStorage are restored!
+```
+
+## Security Notes
+
+- Never commit storage state files containing auth tokens
+- Add `*.auth-state.json` to `.gitignore`
+- Delete state files after automation completes
+- Use environment variables for sensitive data
+- By default, sessions run in-memory mode which is safer for sensitive operations
diff --git a/.github/skills/playwright-cli/references/test-generation.md b/.github/skills/playwright-cli/references/test-generation.md
new file mode 100644
index 0000000000..7a09df387f
--- /dev/null
+++ b/.github/skills/playwright-cli/references/test-generation.md
@@ -0,0 +1,88 @@
+# Test Generation
+
+Generate Playwright test code automatically as you interact with the browser.
+
+## How It Works
+
+Every action you perform with `playwright-cli` generates corresponding Playwright TypeScript code.
+This code appears in the output and can be copied directly into your test files.
+
+## Example Workflow
+
+```bash
+# Start a session
+playwright-cli open https://example.com/login
+
+# Take a snapshot to see elements
+playwright-cli snapshot
+# Output shows: e1 [textbox "Email"], e2 [textbox "Password"], e3 [button "Sign In"]
+
+# Fill form fields - generates code automatically
+playwright-cli fill e1 "user@example.com"
+# Ran Playwright code:
+# await page.getByRole('textbox', { name: 'Email' }).fill('user@example.com');
+
+playwright-cli fill e2 "password123"
+# Ran Playwright code:
+# await page.getByRole('textbox', { name: 'Password' }).fill('password123');
+
+playwright-cli click e3
+# Ran Playwright code:
+# await page.getByRole('button', { name: 'Sign In' }).click();
+```
+
+## Building a Test File
+
+Collect the generated code into a Playwright test:
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test('login flow', async ({ page }) => {
+  // Generated code from playwright-cli session:
+  await page.goto('https://example.com/login');
+  await page.getByRole('textbox', { name: 'Email' }).fill('user@example.com');
+  await page.getByRole('textbox', { name: 'Password' }).fill('password123');
+  await page.getByRole('button', { name: 'Sign In' }).click();
+
+  // Add assertions
+  await expect(page).toHaveURL(/.*dashboard/);
+});
+```
+
+## Best Practices
+
+### 1. Use Semantic Locators
+
+The generated code uses role-based locators when possible, which are more resilient:
+
+```typescript
+// Generated (good - semantic)
+await page.getByRole('button', { name: 'Submit' }).click();
+
+// Avoid (fragile - CSS selectors)
+await page.locator('#submit-btn').click();
+```
+
+### 2. Explore Before Recording
+
+Take snapshots to understand the page structure before recording actions:
+
+```bash
+playwright-cli open https://example.com
+playwright-cli snapshot
+# Review the element structure
+playwright-cli click e5
+```
+
+### 3. Add Assertions Manually
+
+Generated code captures actions but not assertions. Add expectations in your test:
+
+```typescript
+// Generated action
+await page.getByRole('button', { name: 'Submit' }).click();
+
+// Manual assertion
+await expect(page.getByText('Success')).toBeVisible();
+```
diff --git a/.github/skills/playwright-cli/references/tracing.md b/.github/skills/playwright-cli/references/tracing.md
new file mode 100644
index 0000000000..7ce7babbdf
--- /dev/null
+++ b/.github/skills/playwright-cli/references/tracing.md
@@ -0,0 +1,139 @@
+# Tracing
+
+Capture detailed execution traces for debugging and analysis. Traces include DOM snapshots, screenshots, network activity, and console logs.
+
+## Basic Usage
+
+```bash
+# Start trace recording
+playwright-cli tracing-start
+
+# Perform actions
+playwright-cli open https://example.com
+playwright-cli click e1
+playwright-cli fill e2 "test"
+
+# Stop trace recording
+playwright-cli tracing-stop
+```
+
+## Trace Output Files
+
+When you start tracing, Playwright creates a `traces/` directory with several files:
+
+### `trace-{timestamp}.trace`
+
+**Action log** - The main trace file containing:
+- Every action performed (clicks, fills, navigations)
+- DOM snapshots before and after each action
+- Screenshots at each step
+- Timing information
+- Console messages
+- Source locations
+
+### `trace-{timestamp}.network`
+
+**Network log** - Complete network activity:
+- All HTTP requests and responses
+- Request headers and bodies
+- Response headers and bodies
+- Timing (DNS, connect, TLS, TTFB, download)
+- Resource sizes
+- Failed requests and errors
+
+### `resources/`
+
+**Resources directory** - Cached resources:
+- Images, fonts, stylesheets, scripts
+- Response bodies for replay
+- Assets needed to reconstruct page state
+
+## What Traces Capture
+
+| Category | Details |
+|----------|---------|
+| **Actions** | Clicks, fills, hovers, keyboard input, navigations |
+| **DOM** | Full DOM snapshot before/after each action |
+| **Screenshots** | Visual state at each step |
+| **Network** | All requests, responses, headers, bodies, timing |
+| **Console** | All console.log, warn, error messages |
+| **Timing** | Precise timing for each operation |
+
+## Use Cases
+
+### Debugging Failed Actions
+
+```bash
+playwright-cli tracing-start
+playwright-cli open https://app.example.com
+
+# This click fails - why?
+playwright-cli click e5
+
+playwright-cli tracing-stop
+# Open trace to see DOM state when click was attempted
+```
+
+### Analyzing Performance
+
+```bash
+playwright-cli tracing-start
+playwright-cli open https://slow-site.com
+playwright-cli tracing-stop
+
+# View network waterfall to identify slow resources
+```
+
+### Capturing Evidence
+
+```bash
+# Record a complete user flow for documentation
+playwright-cli tracing-start
+
+playwright-cli open https://app.example.com/checkout
+playwright-cli fill e1 "4111111111111111"
+playwright-cli fill e2 "12/25"
+playwright-cli fill e3 "123"
+playwright-cli click e4
+
+playwright-cli tracing-stop
+# Trace shows exact sequence of events
+```
+
+## Trace vs Video vs Screenshot
+
+| Feature | Trace | Video | Screenshot |
+|---------|-------|-------|------------|
+| **Format** | .trace file | .webm video | .png/.jpeg image |
+| **DOM inspection** | Yes | No | No |
+| **Network details** | Yes | No | No |
+| **Step-by-step replay** | Yes | Continuous | Single frame |
+| **File size** | Medium | Large | Small |
+| **Best for** | Debugging | Demos | Quick capture |
+
+## Best Practices
+
+### 1. Start Tracing Before the Problem
+
+```bash
+# Trace the entire flow, not just the failing step
+playwright-cli tracing-start
+playwright-cli open https://example.com
+# ... all steps leading to the issue ...
+playwright-cli tracing-stop
+```
+
+### 2. Clean Up Old Traces
+
+Traces can consume significant disk space:
+
+```bash
+# Remove traces older than 7 days
+find .playwright-cli/traces -mtime +7 -delete
+```
+
+## Limitations
+
+- Traces add overhead to automation
+- Large traces can consume significant disk space
+- Some dynamic content may not replay perfectly
diff --git a/.github/skills/playwright-cli/references/video-recording.md b/.github/skills/playwright-cli/references/video-recording.md
new file mode 100644
index 0000000000..38391b37ad
--- /dev/null
+++ b/.github/skills/playwright-cli/references/video-recording.md
@@ -0,0 +1,43 @@
+# Video Recording
+
+Capture browser automation sessions as video for debugging, documentation, or verification. Produces WebM (VP8/VP9 codec).
+
+## Basic Recording
+
+```bash
+# Start recording
+playwright-cli video-start
+
+# Perform actions
+playwright-cli open https://example.com
+playwright-cli snapshot
+playwright-cli click e1
+playwright-cli fill e2 "test input"
+
+# Stop and save
+playwright-cli video-stop demo.webm
+```
+
+## Best Practices
+
+### 1. Use Descriptive Filenames
+
+```bash
+# Include context in filename
+playwright-cli video-stop recordings/login-flow-2024-01-15.webm
+playwright-cli video-stop recordings/checkout-test-run-42.webm
+```
+
+## Tracing vs Video
+
+| Feature | Video | Tracing |
+|---------|-------|---------|
+| Output | WebM file | Trace file (viewable in Trace Viewer) |
+| Shows | Visual recording | DOM snapshots, network, console, actions |
+| Use case | Demos, documentation | Debugging, analysis |
+| Size | Larger | Smaller |
+
+## Limitations
+
+- Recording adds slight overhead to automation
+- Large recordings can consume significant disk space
diff --git a/.github/skills/research-codebase/SKILL.md b/.github/skills/research-codebase/SKILL.md
index 2d690c4d11..b8c1bc5002 100644
--- a/.github/skills/research-codebase/SKILL.md
+++ b/.github/skills/research-codebase/SKILL.md
@@ -1,6 +1,9 @@
 ---
 name: research-codebase
 description: Document codebase as-is with research directory for historical context
+aliases: [research]
+argument-hint: "<research-question>"
+required-arguments: [research-question]
 ---
 # Research Codebase
 
@@ -50,7 +53,7 @@ The user's research question/request is: **$ARGUMENTS**
    **For online search:**
    - VERY IMPORTANT: In case you discover external libraries as dependencies, use the **codebase-online-researcher** agent for external documentation and resources
      - If you use DeepWiki tools, instruct the agent to return references to code snippets or documentation, PLEASE INCLUDE those references (e.g. source file names, line numbers, etc.)
-     - If you perform a web search using the WebFetch/WebSearch tools, instruct the agent to return LINKS with their findings, and please INCLUDE those links in the research document
+      - If you perform external web research, use the **playwright-cli** skill (or `bunx @playwright/cli`) to inspect pages, then instruct the agent to return LINKS with their findings and INCLUDE those links in the research document
      - Output directory: `research/docs/`
      - Examples:
        - If researching `Redis` locks usage, the agent might find relevant usage and create a document `research/docs/2024-01-15-redis-locks-usage.md` with internal links to Redis docs and code references
@@ -204,4 +207,4 @@ research/
 ## Final Output
 
 - A collection of research files with comprehensive research findings, properly formatted and linked, ready for consumption to create detailed specifications or design documents.
-- IMPORTANT: DO NOT generate any other artifacts or files OUTSIDE of the `research/` directory.
\ No newline at end of file
+- IMPORTANT: DO NOT generate any other artifacts or files OUTSIDE of the `research/` directory.
diff --git a/.github/workflows/installer-validation.yml b/.github/workflows/installer-validation.yml
new file mode 100644
index 0000000000..bdf6de770e
--- /dev/null
+++ b/.github/workflows/installer-validation.yml
@@ -0,0 +1,68 @@
+name: Installer Validation
+
+on:
+    pull_request:
+        branches: [main]
+        paths:
+            - "install.sh"
+            - "install.ps1"
+            - ".github/workflows/installer-validation.yml"
+    workflow_dispatch:
+
+jobs:
+    validate-install-sh:
+        name: Validate install.sh (${{ matrix.os }})
+        runs-on: ${{ matrix.os }}
+        strategy:
+            fail-fast: false
+            matrix:
+                os: [ubuntu-latest, macos-latest]
+
+        steps:
+            - name: Checkout repository
+              uses: actions/checkout@v6
+
+            - name: Validate shell script syntax
+              shell: bash
+              run: bash -n ./install.sh
+
+            - name: Run ShellCheck
+              uses: ludeeus/action-shellcheck@2.0.0
+              with:
+                  scandir: "."
+                  additional_files: "install.sh"
+
+    validate-install-ps1:
+        name: Validate install.ps1 (windows-latest)
+        runs-on: windows-latest
+
+        steps:
+            - name: Checkout repository
+              uses: actions/checkout@v6
+
+            - name: Validate PowerShell syntax
+              shell: pwsh
+              run: |
+                  $tokens = $null
+                  $errors = $null
+                  $null = [System.Management.Automation.Language.Parser]::ParseFile(
+                      (Resolve-Path ./install.ps1),
+                      [ref]$tokens,
+                      [ref]$errors
+                  )
+                  if ($errors.Count -gt 0) {
+                      $errors | ForEach-Object { Write-Error $_ }
+                      throw "install.ps1 has $($errors.Count) syntax error(s)"
+                  }
+                  Write-Host "install.ps1 syntax is valid"
+
+            - name: Run PSScriptAnalyzer
+              shell: pwsh
+              run: |
+                  Install-Module -Name PSScriptAnalyzer -Force -Scope CurrentUser
+                  $results = Invoke-ScriptAnalyzer -Path ./install.ps1 -Severity Error,Warning
+                  if ($results) {
+                      $results | Format-Table -AutoSize
+                      throw "PSScriptAnalyzer found $($results.Count) issue(s)"
+                  }
+                  Write-Host "PSScriptAnalyzer: no issues found"
diff --git a/.gitignore b/.gitignore
index 94f090d711..4b5eb3535e 100644
--- a/.gitignore
+++ b/.gitignore
@@ -176,4 +176,8 @@ atomic.exe
 
 # TUI test screenshots
 screenshots/
-tmux-screenshots/
\ No newline at end of file
+tmux-screenshots/
+
+.claude/settings.local.json
+
+.playwright-cli
\ No newline at end of file
diff --git a/.opencode/agents/codebase-online-researcher.md b/.opencode/agents/codebase-online-researcher.md
index 54cb56cb36..1f2250f6b1 100644
--- a/.opencode/agents/codebase-online-researcher.md
+++ b/.opencode/agents/codebase-online-researcher.md
@@ -5,12 +5,11 @@ tools:
     write: true
     edit: true
     bash: true
-    webfetch: true
     todowrite: true
     deepwiki: true
 ---
 
-You are an expert web research specialist focused on finding accurate, relevant information from web sources. Your primary tools are the DeepWiki `ask_question` tool and `webfetch` tool, which you use to discover and retrieve information based on user queries.
+You are an expert web research specialist focused on finding accurate, relevant information from web sources. Your primary tools are the DeepWiki `ask_question` tool and Playwright CLI (invoked via `bunx @playwright/cli` through the Bash tool), which you use to discover and retrieve information based on user queries.
 
 ## Core Responsibilities
 
@@ -33,12 +32,12 @@ If the answer is insufficient, out-of-date, or unavailable, proceed with the fol
     - Include site-specific searches when targeting known authoritative sources (e.g., "site:docs.stripe.com webhook signature")
 
 3. **Fetch and Analyze Content**:
-    - Use webfetch tool to retrieve full content from promising search results
+    - Use Playwright CLI commands via Bash (`bunx @playwright/cli`) to retrieve full content from promising search results
     - Prioritize official documentation, reputable technical blogs, and authoritative sources
     - Extract specific quotes and sections relevant to the query
     - Note publication dates to ensure currency of information
 
-Finally, for both DeepWiki and webfetch research findings:
+Finally, for both DeepWiki and Playwright CLI research findings:
 
 4. **Synthesize Findings**:
     - Organize information by relevance and authority
diff --git a/.opencode/agents/debugger.md b/.opencode/agents/debugger.md
index 6e5fe94734..113966ab0d 100644
--- a/.opencode/agents/debugger.md
+++ b/.opencode/agents/debugger.md
@@ -5,7 +5,6 @@ tools:
     write: true
     edit: true
     bash: true
-    webfetch: true
     todowrite: true
     deepwiki: true
     lsp: true
@@ -16,7 +15,7 @@ You are tasked with debugging and identifying errors, test failures, and unexpec
 Available tools:
 
 - DeepWiki (`deepwiki_ask_question`): Look up documentation for external libraries and frameworks
-- WebFetch (`webfetch`): Retrieve web content for additional context if you don't find sufficient information in DeepWiki
+- Playwright CLI (via `bunx @playwright/cli` in Bash): Retrieve web content for additional context if you don't find sufficient information in DeepWiki
 - Language Server Protocol (`lsp`): Inspect code, find definitions, and understand code structure
 
 When invoked:
@@ -48,7 +47,7 @@ Debugging process:
 - Add strategic debug logging
 - Inspect variable states
 - Use DeepWiki to look up external library documentation when errors involve third-party dependencies
-- Use WebFetch to gather additional context from web sources if needed
+- Use Playwright CLI via Bash to gather additional context from web sources if needed
 - Use LSP to understand error locations and navigate the codebase structure
 
 For each issue, provide:
diff --git a/.opencode/agents/planner.md b/.opencode/agents/planner.md
new file mode 100644
index 0000000000..d38b1fb425
--- /dev/null
+++ b/.opencode/agents/planner.md
@@ -0,0 +1,128 @@
+---
+description: Decomposes user prompts into structured task lists for the Ralph workflow.
+mode: primary
+tools:
+    write: false
+    edit: false
+    bash: false
+    todowrite: false
+    question: false
+    lsp: false
+    skill: false
+---
+
+You are the planner agent for the Ralph autonomous implementation workflow.
+
+Your job is to decompose the user's feature request into a structured, ordered list of implementation tasks.
+
+# Input
+
+You will receive a feature specification or user request describing what needs to be implemented.
+
+# Output Format
+
+Return a JSON array of task objects with the following structure:
+
+```json
+[
+  {
+    "id": "#1",
+    "content": "Task description",
+    "status": "pending",
+    "activeForm": "Active form description (gerund, e.g., 'Implementing auth module')",
+    "blockedBy": []
+  },
+  {
+    "id": "#2",
+    "content": "Another task description",
+    "status": "pending",
+    "activeForm": "Active form description",
+    "blockedBy": ["#1"]
+  }
+]
+```
+
+# Task Decomposition Guidelines
+
+1. **Break down into atomic tasks**: Each task should be a single, focused unit of work that can be completed independently (unless it has dependencies).
+
+2. **Order by dependencies**: Use the `blockedBy` array to specify task dependencies. A task with `"blockedBy": ["#1"]` cannot start until task #1 is completed.
+
+3. **Be specific**: Task descriptions should be clear and actionable. Avoid vague descriptions like "fix bugs" or "improve performance".
+
+4. **Use gerunds for activeForm**: The `activeForm` field should describe the task in progress using a gerund (e.g., "Implementing", "Adding", "Refactoring").
+
+5. **Start simple**: Begin with foundational tasks (e.g., setup, configuration) before moving to feature implementation.
+
+6. **Consider testing**: Include tasks for writing tests where appropriate.
+
+7. **Typical task categories**:
+   - Setup/configuration tasks
+   - Model/data structure definitions
+   - Core logic implementation
+   - UI/presentation layer
+   - Integration tasks
+   - Testing tasks
+   - Documentation tasks
+
+# Example
+
+**Input**: "Add user authentication to the app"
+
+**Output**:
+```json
+[
+  {
+    "id": "#1",
+    "content": "Define user model and authentication schema",
+    "status": "pending",
+    "activeForm": "Defining user model and auth schema",
+    "blockedBy": []
+  },
+  {
+    "id": "#2",
+    "content": "Implement password hashing and validation utilities",
+    "status": "pending",
+    "activeForm": "Implementing password utilities",
+    "blockedBy": ["#1"]
+  },
+  {
+    "id": "#3",
+    "content": "Create registration endpoint with validation",
+    "status": "pending",
+    "activeForm": "Creating registration endpoint",
+    "blockedBy": ["#1", "#2"]
+  },
+  {
+    "id": "#4",
+    "content": "Create login endpoint with JWT token generation",
+    "status": "pending",
+    "activeForm": "Creating login endpoint",
+    "blockedBy": ["#1", "#2"]
+  },
+  {
+    "id": "#5",
+    "content": "Add authentication middleware for protected routes",
+    "status": "pending",
+    "activeForm": "Adding auth middleware",
+    "blockedBy": ["#4"]
+  },
+  {
+    "id": "#6",
+    "content": "Write integration tests for auth endpoints",
+    "status": "pending",
+    "activeForm": "Writing auth integration tests",
+    "blockedBy": ["#3", "#4", "#5"]
+  }
+]
+```
+
+# Important Notes
+
+- Always return valid JSON
+- Ensure all task IDs are unique
+- Use consistent ID format (#1, #2, #3, etc.)
+- The `status` field should always be "pending" for new tasks
+- Dependencies in `blockedBy` must reference valid task IDs
+- Keep task descriptions concise but descriptive (aim for 5-10 words)
+- Aim for 3-8 tasks total for most features (adjust based on complexity)
diff --git a/.opencode/opencode.json b/.opencode/opencode.json
index a9e9763a0e..55eb517ca1 100644
--- a/.opencode/opencode.json
+++ b/.opencode/opencode.json
@@ -14,7 +14,6 @@
     "permission": {
         "edit": "allow",
         "bash": "allow",
-        "webfetch": "allow",
         "doom_loop": "allow",
         "external_directory": "allow"
     }
diff --git a/.opencode/skills/explain-code/SKILL.md b/.opencode/skills/explain-code/SKILL.md
index b96d66aa0e..b3f60a5960 100644
--- a/.opencode/skills/explain-code/SKILL.md
+++ b/.opencode/skills/explain-code/SKILL.md
@@ -9,7 +9,7 @@ description: Explain code functionality in detail.
 The following MCP tools are available and SHOULD be used when relevant:
 
 - **DeepWiki** (`ask_question`): Use to look up documentation for external libraries, frameworks, and GitHub repositories. Particularly useful for understanding third-party dependencies and their APIs.
-- **WebFetch/WebSearch**: Use to retrieve web content for additional context if information is not found in DeepWiki.
+- **Playwright CLI** (`playwright-cli`): Use to retrieve web content, browse documentation, and extract data from web pages if information is not found in DeepWiki. Invoke via the `/playwright-cli` skill or run `bunx playwright-cli` commands directly.
 
 ## Instructions
 
@@ -81,6 +81,7 @@ Follow this systematic approach to explain code: **$ARGUMENTS**
     - Identify debugging points and logging
     - Describe mock data or test scenarios
     - Explain test helpers and utilities
+    - Use `playwright-cli` to reproduce browser interactions and validate frontend behavior when applicable
 
 12. **Dependencies and Integrations**
     - Explain external service integrations
@@ -202,4 +203,5 @@ Remember to:
 - Structure explanations logically from high-level to detailed
 - Include visual diagrams or flowcharts when helpful
 - Tailor the explanation level to the intended audience
-- Use DeepWiki to look up external library documentation when encountering unfamiliar dependencies
\ No newline at end of file
+- Use DeepWiki to look up external library documentation when encountering unfamiliar dependencies
+- Use `playwright-cli` for live browser inspection when static code analysis is not enough
diff --git a/.opencode/skills/playwright-cli/SKILL.md b/.opencode/skills/playwright-cli/SKILL.md
new file mode 100644
index 0000000000..11bad2b874
--- /dev/null
+++ b/.opencode/skills/playwright-cli/SKILL.md
@@ -0,0 +1,278 @@
+---
+name: playwright-cli
+description: Automates browser interactions for web testing, form filling, screenshots, and data extraction. Use when the user needs to navigate websites, interact with web pages, fill forms, take screenshots, test web applications, or extract information from web pages.
+allowed-tools: Bash(playwright-cli:*)
+---
+
+# Browser Automation with playwright-cli
+
+## Quick start
+
+```bash
+# open new browser
+playwright-cli open
+# navigate to a page
+playwright-cli goto https://playwright.dev
+# interact with the page using refs from the snapshot
+playwright-cli click e15
+playwright-cli type "page.click"
+playwright-cli press Enter
+# take a screenshot (rarely used, as snapshot is more common)
+playwright-cli screenshot
+# close the browser
+playwright-cli close
+```
+
+## Commands
+
+### Core
+
+```bash
+playwright-cli open
+# open and navigate right away
+playwright-cli open https://example.com/
+playwright-cli goto https://playwright.dev
+playwright-cli type "search query"
+playwright-cli click e3
+playwright-cli dblclick e7
+playwright-cli fill e5 "user@example.com"
+playwright-cli drag e2 e8
+playwright-cli hover e4
+playwright-cli select e9 "option-value"
+playwright-cli upload ./document.pdf
+playwright-cli check e12
+playwright-cli uncheck e12
+playwright-cli snapshot
+playwright-cli snapshot --filename=after-click.yaml
+playwright-cli eval "document.title"
+playwright-cli eval "el => el.textContent" e5
+playwright-cli dialog-accept
+playwright-cli dialog-accept "confirmation text"
+playwright-cli dialog-dismiss
+playwright-cli resize 1920 1080
+playwright-cli close
+```
+
+### Navigation
+
+```bash
+playwright-cli go-back
+playwright-cli go-forward
+playwright-cli reload
+```
+
+### Keyboard
+
+```bash
+playwright-cli press Enter
+playwright-cli press ArrowDown
+playwright-cli keydown Shift
+playwright-cli keyup Shift
+```
+
+### Mouse
+
+```bash
+playwright-cli mousemove 150 300
+playwright-cli mousedown
+playwright-cli mousedown right
+playwright-cli mouseup
+playwright-cli mouseup right
+playwright-cli mousewheel 0 100
+```
+
+### Save as
+
+```bash
+playwright-cli screenshot
+playwright-cli screenshot e5
+playwright-cli screenshot --filename=page.png
+playwright-cli pdf --filename=page.pdf
+```
+
+### Tabs
+
+```bash
+playwright-cli tab-list
+playwright-cli tab-new
+playwright-cli tab-new https://example.com/page
+playwright-cli tab-close
+playwright-cli tab-close 2
+playwright-cli tab-select 0
+```
+
+### Storage
+
+```bash
+playwright-cli state-save
+playwright-cli state-save auth.json
+playwright-cli state-load auth.json
+
+# Cookies
+playwright-cli cookie-list
+playwright-cli cookie-list --domain=example.com
+playwright-cli cookie-get session_id
+playwright-cli cookie-set session_id abc123
+playwright-cli cookie-set session_id abc123 --domain=example.com --httpOnly --secure
+playwright-cli cookie-delete session_id
+playwright-cli cookie-clear
+
+# LocalStorage
+playwright-cli localstorage-list
+playwright-cli localstorage-get theme
+playwright-cli localstorage-set theme dark
+playwright-cli localstorage-delete theme
+playwright-cli localstorage-clear
+
+# SessionStorage
+playwright-cli sessionstorage-list
+playwright-cli sessionstorage-get step
+playwright-cli sessionstorage-set step 3
+playwright-cli sessionstorage-delete step
+playwright-cli sessionstorage-clear
+```
+
+### Network
+
+```bash
+playwright-cli route "**/*.jpg" --status=404
+playwright-cli route "https://api.example.com/**" --body='{"mock": true}'
+playwright-cli route-list
+playwright-cli unroute "**/*.jpg"
+playwright-cli unroute
+```
+
+### DevTools
+
+```bash
+playwright-cli console
+playwright-cli console warning
+playwright-cli network
+playwright-cli run-code "async page => await page.context().grantPermissions(['geolocation'])"
+playwright-cli tracing-start
+playwright-cli tracing-stop
+playwright-cli video-start
+playwright-cli video-stop video.webm
+```
+
+## Open parameters
+```bash
+# Use specific browser when creating session
+playwright-cli open --browser=chrome
+playwright-cli open --browser=firefox
+playwright-cli open --browser=webkit
+playwright-cli open --browser=msedge
+# Connect to browser via extension
+playwright-cli open --extension
+
+# Use persistent profile (by default profile is in-memory)
+playwright-cli open --persistent
+# Use persistent profile with custom directory
+playwright-cli open --profile=/path/to/profile
+
+# Start with config file
+playwright-cli open --config=my-config.json
+
+# Close the browser
+playwright-cli close
+# Delete user data for the default session
+playwright-cli delete-data
+```
+
+## Snapshots
+
+After each command, playwright-cli provides a snapshot of the current browser state.
+
+```bash
+> playwright-cli goto https://example.com
+### Page
+- Page URL: https://example.com/
+- Page Title: Example Domain
+### Snapshot
+[Snapshot](.playwright-cli/page-2026-02-14T19-22-42-679Z.yml)
+```
+
+You can also take a snapshot on demand using `playwright-cli snapshot` command.
+
+If `--filename` is not provided, a new snapshot file is created with a timestamp. Default to automatic file naming, use `--filename=` when artifact is a part of the workflow result.
+
+## Browser Sessions
+
+```bash
+# create new browser session named "mysession" with persistent profile
+playwright-cli -s=mysession open example.com --persistent
+# same with manually specified profile directory (use when requested explicitly)
+playwright-cli -s=mysession open example.com --profile=/path/to/profile
+playwright-cli -s=mysession click e6
+playwright-cli -s=mysession close  # stop a named browser
+playwright-cli -s=mysession delete-data  # delete user data for persistent session
+
+playwright-cli list
+# Close all browsers
+playwright-cli close-all
+# Forcefully kill all browser processes
+playwright-cli kill-all
+```
+
+## Local installation
+
+In some cases user might want to install playwright-cli locally. If running globally available `playwright-cli` binary fails, use `npx playwright-cli` to run the commands. For example:
+
+```bash
+npx playwright-cli open https://example.com
+npx playwright-cli click e1
+```
+
+## Example: Form submission
+
+```bash
+playwright-cli open https://example.com/form
+playwright-cli snapshot
+
+playwright-cli fill e1 "user@example.com"
+playwright-cli fill e2 "password123"
+playwright-cli click e3
+playwright-cli snapshot
+playwright-cli close
+```
+
+## Example: Multi-tab workflow
+
+```bash
+playwright-cli open https://example.com
+playwright-cli tab-new https://example.com/other
+playwright-cli tab-list
+playwright-cli tab-select 0
+playwright-cli snapshot
+playwright-cli close
+```
+
+## Example: Debugging with DevTools
+
+```bash
+playwright-cli open https://example.com
+playwright-cli click e4
+playwright-cli fill e7 "test"
+playwright-cli console
+playwright-cli network
+playwright-cli close
+```
+
+```bash
+playwright-cli open https://example.com
+playwright-cli tracing-start
+playwright-cli click e4
+playwright-cli fill e7 "test"
+playwright-cli tracing-stop
+playwright-cli close
+```
+
+## Specific tasks
+
+* **Request mocking** [references/request-mocking.md](references/request-mocking.md)
+* **Running Playwright code** [references/running-code.md](references/running-code.md)
+* **Browser session management** [references/session-management.md](references/session-management.md)
+* **Storage state (cookies, localStorage)** [references/storage-state.md](references/storage-state.md)
+* **Test generation** [references/test-generation.md](references/test-generation.md)
+* **Tracing** [references/tracing.md](references/tracing.md)
+* **Video recording** [references/video-recording.md](references/video-recording.md)
diff --git a/.opencode/skills/playwright-cli/references/request-mocking.md b/.opencode/skills/playwright-cli/references/request-mocking.md
new file mode 100644
index 0000000000..9005fda67d
--- /dev/null
+++ b/.opencode/skills/playwright-cli/references/request-mocking.md
@@ -0,0 +1,87 @@
+# Request Mocking
+
+Intercept, mock, modify, and block network requests.
+
+## CLI Route Commands
+
+```bash
+# Mock with custom status
+playwright-cli route "**/*.jpg" --status=404
+
+# Mock with JSON body
+playwright-cli route "**/api/users" --body='[{"id":1,"name":"Alice"}]' --content-type=application/json
+
+# Mock with custom headers
+playwright-cli route "**/api/data" --body='{"ok":true}' --header="X-Custom: value"
+
+# Remove headers from requests
+playwright-cli route "**/*" --remove-header=cookie,authorization
+
+# List active routes
+playwright-cli route-list
+
+# Remove a route or all routes
+playwright-cli unroute "**/*.jpg"
+playwright-cli unroute
+```
+
+## URL Patterns
+
+```
+**/api/users           - Exact path match
+**/api/*/details       - Wildcard in path
+**/*.{png,jpg,jpeg}    - Match file extensions
+**/search?q=*          - Match query parameters
+```
+
+## Advanced Mocking with run-code
+
+For conditional responses, request body inspection, response modification, or delays:
+
+### Conditional Response Based on Request
+
+```bash
+playwright-cli run-code "async page => {
+  await page.route('**/api/login', route => {
+    const body = route.request().postDataJSON();
+    if (body.username === 'admin') {
+      route.fulfill({ body: JSON.stringify({ token: 'mock-token' }) });
+    } else {
+      route.fulfill({ status: 401, body: JSON.stringify({ error: 'Invalid' }) });
+    }
+  });
+}"
+```
+
+### Modify Real Response
+
+```bash
+playwright-cli run-code "async page => {
+  await page.route('**/api/user', async route => {
+    const response = await route.fetch();
+    const json = await response.json();
+    json.isPremium = true;
+    await route.fulfill({ response, json });
+  });
+}"
+```
+
+### Simulate Network Failures
+
+```bash
+playwright-cli run-code "async page => {
+  await page.route('**/api/offline', route => route.abort('internetdisconnected'));
+}"
+# Options: connectionrefused, timedout, connectionreset, internetdisconnected
+```
+
+### Delayed Response
+
+```bash
+playwright-cli run-code "async page => {
+  await page.route('**/api/slow', async route => {
+    await new Promise(r => setTimeout(r, 3000));
+    route.fulfill({ body: JSON.stringify({ data: 'loaded' }) });
+  });
+}"
+```
diff --git a/.opencode/skills/playwright-cli/references/running-code.md b/.opencode/skills/playwright-cli/references/running-code.md
new file mode 100644
index 0000000000..7d6d22fd09
--- /dev/null
+++ b/.opencode/skills/playwright-cli/references/running-code.md
@@ -0,0 +1,232 @@
+# Running Custom Playwright Code
+
+Use `run-code` to execute arbitrary Playwright code for advanced scenarios not covered by CLI commands.
+
+## Syntax
+
+```bash
+playwright-cli run-code "async page => {
+  // Your Playwright code here
+  // Access page.context() for browser context operations
+}"
+```
+
+## Geolocation
+
+```bash
+# Grant geolocation permission and set location
+playwright-cli run-code "async page => {
+  await page.context().grantPermissions(['geolocation']);
+  await page.context().setGeolocation({ latitude: 37.7749, longitude: -122.4194 });
+}"
+
+# Set location to London
+playwright-cli run-code "async page => {
+  await page.context().grantPermissions(['geolocation']);
+  await page.context().setGeolocation({ latitude: 51.5074, longitude: -0.1278 });
+}"
+
+# Clear geolocation override
+playwright-cli run-code "async page => {
+  await page.context().clearPermissions();
+}"
+```
+
+## Permissions
+
+```bash
+# Grant multiple permissions
+playwright-cli run-code "async page => {
+  await page.context().grantPermissions([
+    'geolocation',
+    'notifications',
+    'camera',
+    'microphone'
+  ]);
+}"
+
+# Grant permissions for specific origin
+playwright-cli run-code "async page => {
+  await page.context().grantPermissions(['clipboard-read'], {
+    origin: 'https://example.com'
+  });
+}"
+```
+
+## Media Emulation
+
+```bash
+# Emulate dark color scheme
+playwright-cli run-code "async page => {
+  await page.emulateMedia({ colorScheme: 'dark' });
+}"
+
+# Emulate light color scheme
+playwright-cli run-code "async page => {
+  await page.emulateMedia({ colorScheme: 'light' });
+}"
+
+# Emulate reduced motion
+playwright-cli run-code "async page => {
+  await page.emulateMedia({ reducedMotion: 'reduce' });
+}"
+
+# Emulate print media
+playwright-cli run-code "async page => {
+  await page.emulateMedia({ media: 'print' });
+}"
+```
+
+## Wait Strategies
+
+```bash
+# Wait for network idle
+playwright-cli run-code "async page => {
+  await page.waitForLoadState('networkidle');
+}"
+
+# Wait for specific element
+playwright-cli run-code "async page => {
+  await page.waitForSelector('.loading', { state: 'hidden' });
+}"
+
+# Wait for function to return true
+playwright-cli run-code "async page => {
+  await page.waitForFunction(() => window.appReady === true);
+}"
+
+# Wait with timeout
+playwright-cli run-code "async page => {
+  await page.waitForSelector('.result', { timeout: 10000 });
+}"
+```
+
+## Frames and Iframes
+
+```bash
+# Work with iframe
+playwright-cli run-code "async page => {
+  const frame = page.locator('iframe#my-iframe').contentFrame();
+  await frame.locator('button').click();
+}"
+
+# Get all frames
+playwright-cli run-code "async page => {
+  const frames = page.frames();
+  return frames.map(f => f.url());
+}"
+```
+
+## File Downloads
+
+```bash
+# Handle file download
+playwright-cli run-code "async page => {
+  const [download] = await Promise.all([
+    page.waitForEvent('download'),
+    page.click('a.download-link')
+  ]);
+  await download.saveAs('./downloaded-file.pdf');
+  return download.suggestedFilename();
+}"
+```
+
+## Clipboard
+
+```bash
+# Read clipboard (requires permission)
+playwright-cli run-code "async page => {
+  await page.context().grantPermissions(['clipboard-read']);
+  return await page.evaluate(() => navigator.clipboard.readText());
+}"
+
+# Write to clipboard
+playwright-cli run-code "async page => {
+  await page.evaluate(text => navigator.clipboard.writeText(text), 'Hello clipboard!');
+}"
+```
+
+## Page Information
+
+```bash
+# Get page title
+playwright-cli run-code "async page => {
+  return await page.title();
+}"
+
+# Get current URL
+playwright-cli run-code "async page => {
+  return page.url();
+}"
+
+# Get page content
+playwright-cli run-code "async page => {
+  return await page.content();
+}"
+
+# Get viewport size
+playwright-cli run-code "async page => {
+  return page.viewportSize();
+}"
+```
+
+## JavaScript Execution
+
+```bash
+# Execute JavaScript and return result
+playwright-cli run-code "async page => {
+  return await page.evaluate(() => {
+    return {
+      userAgent: navigator.userAgent,
+      language: navigator.language,
+      cookiesEnabled: navigator.cookieEnabled
+    };
+  });
+}"
+
+# Pass arguments to evaluate
+playwright-cli run-code "async page => {
+  const multiplier = 5;
+  return await page.evaluate(m => document.querySelectorAll('li').length * m, multiplier);
+}"
+```
+
+## Error Handling
+
+```bash
+# Try-catch in run-code
+playwright-cli run-code "async page => {
+  try {
+    await page.click('.maybe-missing', { timeout: 1000 });
+    return 'clicked';
+  } catch (e) {
+    return 'element not found';
+  }
+}"
+```
+
+## Complex Workflows
+
+```bash
+# Login and save state
+playwright-cli run-code "async page => {
+  await page.goto('https://example.com/login');
+  await page.fill('input[name=email]', 'user@example.com');
+  await page.fill('input[name=password]', 'secret');
+  await page.click('button[type=submit]');
+  await page.waitForURL('**/dashboard');
+  await page.context().storageState({ path: 'auth.json' });
+  return 'Login successful';
+}"
+
+# Scrape data from multiple pages
+playwright-cli run-code "async page => {
+  const results = [];
+  for (let i = 1; i <= 3; i++) {
+    await page.goto(\`https://example.com/page/\${i}\`);
+    const items = await page.locator('.item').allTextContents();
+    results.push(...items);
+  }
+  return results;
+}"
+```
diff --git a/.opencode/skills/playwright-cli/references/session-management.md b/.opencode/skills/playwright-cli/references/session-management.md
new file mode 100644
index 0000000000..fac96066c9
--- /dev/null
+++ b/.opencode/skills/playwright-cli/references/session-management.md
@@ -0,0 +1,169 @@
+# Browser Session Management
+
+Run multiple isolated browser sessions concurrently with state persistence.
+
+## Named Browser Sessions
+
+Use `-s` flag to isolate browser contexts:
+
+```bash
+# Browser 1: Authentication flow
+playwright-cli -s=auth open https://app.example.com/login
+
+# Browser 2: Public browsing (separate cookies, storage)
+playwright-cli -s=public open https://example.com
+
+# Commands are isolated by browser session
+playwright-cli -s=auth fill e1 "user@example.com"
+playwright-cli -s=public snapshot
+```
+
+## Browser Session Isolation Properties
+
+Each browser session has independent:
+- Cookies
+- LocalStorage / SessionStorage
+- IndexedDB
+- Cache
+- Browsing history
+- Open tabs
+
+## Browser Session Commands
+
+```bash
+# List all browser sessions
+playwright-cli list
+
+# Stop a browser session (close the browser)
+playwright-cli close                # stop the default browser
+playwright-cli -s=mysession close   # stop a named browser
+
+# Stop all browser sessions
+playwright-cli close-all
+
+# Forcefully kill all daemon processes (for stale/zombie processes)
+playwright-cli kill-all
+
+# Delete browser session user data (profile directory)
+playwright-cli delete-data                # delete default browser data
+playwright-cli -s=mysession delete-data   # delete named browser data
+```
+
+## Environment Variable
+
+Set a default browser session name via environment variable:
+
+```bash
+export PLAYWRIGHT_CLI_SESSION="mysession"
+playwright-cli open example.com  # Uses "mysession" automatically
+```
+
+## Common Patterns
+
+### Concurrent Scraping
+
+```bash
+#!/bin/bash
+# Scrape multiple sites concurrently
+
+# Start all browsers
+playwright-cli -s=site1 open https://site1.com &
+playwright-cli -s=site2 open https://site2.com &
+playwright-cli -s=site3 open https://site3.com &
+wait
+
+# Take snapshots from each
+playwright-cli -s=site1 snapshot
+playwright-cli -s=site2 snapshot
+playwright-cli -s=site3 snapshot
+
+# Cleanup
+playwright-cli close-all
+```
+
+### A/B Testing Sessions
+
+```bash
+# Test different user experiences
+playwright-cli -s=variant-a open "https://app.com?variant=a"
+playwright-cli -s=variant-b open "https://app.com?variant=b"
+
+# Compare
+playwright-cli -s=variant-a screenshot
+playwright-cli -s=variant-b screenshot
+```
+
+### Persistent Profile
+
+By default, browser profile is kept in memory only. Use `--persistent` flag on `open` to persist the browser profile to disk:
+
+```bash
+# Use persistent profile (auto-generated location)
+playwright-cli open https://example.com --persistent
+
+# Use persistent profile with custom directory
+playwright-cli open https://example.com --profile=/path/to/profile
+```
+
+## Default Browser Session
+
+When `-s` is omitted, commands use the default browser session:
+
+```bash
+# These use the same default browser session
+playwright-cli open https://example.com
+playwright-cli snapshot
+playwright-cli close  # Stops default browser
+```
+
+## Browser Session Configuration
+
+Configure a browser session with specific settings when opening:
+
+```bash
+# Open with config file
+playwright-cli open https://example.com --config=.playwright/my-cli.json
+
+# Open with specific browser
+playwright-cli open https://example.com --browser=firefox
+
+# Open in headed mode
+playwright-cli open https://example.com --headed
+
+# Open with persistent profile
+playwright-cli open https://example.com --persistent
+```
+
+## Best Practices
+
+### 1. Name Browser Sessions Semantically
+
+```bash
+# GOOD: Clear purpose
+playwright-cli -s=github-auth open https://github.com
+playwright-cli -s=docs-scrape open https://docs.example.com
+
+# AVOID: Generic names
+playwright-cli -s=s1 open https://github.com
+```
+
+### 2. Always Clean Up
+
+```bash
+# Stop browsers when done
+playwright-cli -s=auth close
+playwright-cli -s=scrape close
+
+# Or stop all at once
+playwright-cli close-all
+
+# If browsers become unresponsive or zombie processes remain
+playwright-cli kill-all
+```
+
+### 3. Delete Stale Browser Data
+
+```bash
+# Remove old browser data to free disk space
+playwright-cli -s=oldsession delete-data
+```
diff --git a/.opencode/skills/playwright-cli/references/storage-state.md b/.opencode/skills/playwright-cli/references/storage-state.md
new file mode 100644
index 0000000000..c856db5e40
--- /dev/null
+++ b/.opencode/skills/playwright-cli/references/storage-state.md
@@ -0,0 +1,275 @@
+# Storage Management
+
+Manage cookies, localStorage, sessionStorage, and browser storage state.
+
+## Storage State
+
+Save and restore complete browser state including cookies and storage.
+
+### Save Storage State
+
+```bash
+# Save to auto-generated filename (storage-state-{timestamp}.json)
+playwright-cli state-save
+
+# Save to specific filename
+playwright-cli state-save my-auth-state.json
+```
+
+### Restore Storage State
+
+```bash
+# Load storage state from file
+playwright-cli state-load my-auth-state.json
+
+# Reload page to apply cookies
+playwright-cli open https://example.com
+```
+
+### Storage State File Format
+
+The saved file contains:
+
+```json
+{
+  "cookies": [
+    {
+      "name": "session_id",
+      "value": "abc123",
+      "domain": "example.com",
+      "path": "/",
+      "expires": 1735689600,
+      "httpOnly": true,
+      "secure": true,
+      "sameSite": "Lax"
+    }
+  ],
+  "origins": [
+    {
+      "origin": "https://example.com",
+      "localStorage": [
+        { "name": "theme", "value": "dark" },
+        { "name": "user_id", "value": "12345" }
+      ]
+    }
+  ]
+}
+```
+
+## Cookies
+
+### List All Cookies
+
+```bash
+playwright-cli cookie-list
+```
+
+### Filter Cookies by Domain
+
+```bash
+playwright-cli cookie-list --domain=example.com
+```
+
+### Filter Cookies by Path
+
+```bash
+playwright-cli cookie-list --path=/api
+```
+
+### Get Specific Cookie
+
+```bash
+playwright-cli cookie-get session_id
+```
+
+### Set a Cookie
+
+```bash
+# Basic cookie
+playwright-cli cookie-set session abc123
+
+# Cookie with options
+playwright-cli cookie-set session abc123 --domain=example.com --path=/ --httpOnly --secure --sameSite=Lax
+
+# Cookie with expiration (Unix timestamp)
+playwright-cli cookie-set remember_me token123 --expires=1735689600
+```
+
+### Delete a Cookie
+
+```bash
+playwright-cli cookie-delete session_id
+```
+
+### Clear All Cookies
+
+```bash
+playwright-cli cookie-clear
+```
+
+### Advanced: Multiple Cookies or Custom Options
+
+For complex scenarios like adding multiple cookies at once, use `run-code`:
+
+```bash
+playwright-cli run-code "async page => {
+  await page.context().addCookies([
+    { name: 'session_id', value: 'sess_abc123', domain: 'example.com', path: '/', httpOnly: true },
+    { name: 'preferences', value: JSON.stringify({ theme: 'dark' }), domain: 'example.com', path: '/' }
+  ]);
+}"
+```
+
+## Local Storage
+
+### List All localStorage Items
+
+```bash
+playwright-cli localstorage-list
+```
+
+### Get Single Value
+
+```bash
+playwright-cli localstorage-get token
+```
+
+### Set Value
+
+```bash
+playwright-cli localstorage-set theme dark
+```
+
+### Set JSON Value
+
+```bash
+playwright-cli localstorage-set user_settings '{"theme":"dark","language":"en"}'
+```
+
+### Delete Single Item
+
+```bash
+playwright-cli localstorage-delete token
+```
+
+### Clear All localStorage
+
+```bash
+playwright-cli localstorage-clear
+```
+
+### Advanced: Multiple Operations
+
+For complex scenarios like setting multiple values at once, use `run-code`:
+
+```bash
+playwright-cli run-code "async page => {
+  await page.evaluate(() => {
+    localStorage.setItem('token', 'jwt_abc123');
+    localStorage.setItem('user_id', '12345');
+    localStorage.setItem('expires_at', Date.now() + 3600000);
+  });
+}"
+```
+
+## Session Storage
+
+### List All sessionStorage Items
+
+```bash
+playwright-cli sessionstorage-list
+```
+
+### Get Single Value
+
+```bash
+playwright-cli sessionstorage-get form_data
+```
+
+### Set Value
+
+```bash
+playwright-cli sessionstorage-set step 3
+```
+
+### Delete Single Item
+
+```bash
+playwright-cli sessionstorage-delete step
+```
+
+### Clear sessionStorage
+
+```bash
+playwright-cli sessionstorage-clear
+```
+
+## IndexedDB
+
+### List Databases
+
+```bash
+playwright-cli run-code "async page => {
+  return await page.evaluate(async () => {
+    const databases = await indexedDB.databases();
+    return databases;
+  });
+}"
+```
+
+### Delete Database
+
+```bash
+playwright-cli run-code "async page => {
+  await page.evaluate(() => {
+    indexedDB.deleteDatabase('myDatabase');
+  });
+}"
+```
+
+## Common Patterns
+
+### Authentication State Reuse
+
+```bash
+# Step 1: Login and save state
+playwright-cli open https://app.example.com/login
+playwright-cli snapshot
+playwright-cli fill e1 "user@example.com"
+playwright-cli fill e2 "password123"
+playwright-cli click e3
+
+# Save the authenticated state
+playwright-cli state-save auth.json
+
+# Step 2: Later, restore state and skip login
+playwright-cli state-load auth.json
+playwright-cli open https://app.example.com/dashboard
+# Already logged in!
+```
+
+### Save and Restore Roundtrip
+
+```bash
+# Set up authentication state
+playwright-cli open https://example.com
+playwright-cli eval "() => { document.cookie = 'session=abc123'; localStorage.setItem('user', 'john'); }"
+
+# Save state to file
+playwright-cli state-save my-session.json
+
+# ... later, in a new session ...
+
+# Restore state
+playwright-cli state-load my-session.json
+playwright-cli open https://example.com
+# Cookies and localStorage are restored!
+```
+
+## Security Notes
+
+- Never commit storage state files containing auth tokens
+- Add `*.auth-state.json` to `.gitignore`
+- Delete state files after automation completes
+- Use environment variables for sensitive data
+- By default, sessions run in-memory mode which is safer for sensitive operations
diff --git a/.opencode/skills/playwright-cli/references/test-generation.md b/.opencode/skills/playwright-cli/references/test-generation.md
new file mode 100644
index 0000000000..7a09df387f
--- /dev/null
+++ b/.opencode/skills/playwright-cli/references/test-generation.md
@@ -0,0 +1,88 @@
+# Test Generation
+
+Generate Playwright test code automatically as you interact with the browser.
+
+## How It Works
+
+Every action you perform with `playwright-cli` generates corresponding Playwright TypeScript code.
+This code appears in the output and can be copied directly into your test files.
+
+## Example Workflow
+
+```bash
+# Start a session
+playwright-cli open https://example.com/login
+
+# Take a snapshot to see elements
+playwright-cli snapshot
+# Output shows: e1 [textbox "Email"], e2 [textbox "Password"], e3 [button "Sign In"]
+
+# Fill form fields - generates code automatically
+playwright-cli fill e1 "user@example.com"
+# Ran Playwright code:
+# await page.getByRole('textbox', { name: 'Email' }).fill('user@example.com');
+
+playwright-cli fill e2 "password123"
+# Ran Playwright code:
+# await page.getByRole('textbox', { name: 'Password' }).fill('password123');
+
+playwright-cli click e3
+# Ran Playwright code:
+# await page.getByRole('button', { name: 'Sign In' }).click();
+```
+
+## Building a Test File
+
+Collect the generated code into a Playwright test:
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test('login flow', async ({ page }) => {
+  // Generated code from playwright-cli session:
+  await page.goto('https://example.com/login');
+  await page.getByRole('textbox', { name: 'Email' }).fill('user@example.com');
+  await page.getByRole('textbox', { name: 'Password' }).fill('password123');
+  await page.getByRole('button', { name: 'Sign In' }).click();
+
+  // Add assertions
+  await expect(page).toHaveURL(/.*dashboard/);
+});
+```
+
+## Best Practices
+
+### 1. Use Semantic Locators
+
+The generated code uses role-based locators when possible, which are more resilient:
+
+```typescript
+// Generated (good - semantic)
+await page.getByRole('button', { name: 'Submit' }).click();
+
+// Avoid (fragile - CSS selectors)
+await page.locator('#submit-btn').click();
+```
+
+### 2. Explore Before Recording
+
+Take snapshots to understand the page structure before recording actions:
+
+```bash
+playwright-cli open https://example.com
+playwright-cli snapshot
+# Review the element structure
+playwright-cli click e5
+```
+
+### 3. Add Assertions Manually
+
+Generated code captures actions but not assertions. Add expectations in your test:
+
+```typescript
+// Generated action
+await page.getByRole('button', { name: 'Submit' }).click();
+
+// Manual assertion
+await expect(page.getByText('Success')).toBeVisible();
+```
diff --git a/.opencode/skills/playwright-cli/references/tracing.md b/.opencode/skills/playwright-cli/references/tracing.md
new file mode 100644
index 0000000000..7ce7babbdf
--- /dev/null
+++ b/.opencode/skills/playwright-cli/references/tracing.md
@@ -0,0 +1,139 @@
+# Tracing
+
+Capture detailed execution traces for debugging and analysis. Traces include DOM snapshots, screenshots, network activity, and console logs.
+
+## Basic Usage
+
+```bash
+# Start trace recording
+playwright-cli tracing-start
+
+# Perform actions
+playwright-cli open https://example.com
+playwright-cli click e1
+playwright-cli fill e2 "test"
+
+# Stop trace recording
+playwright-cli tracing-stop
+```
+
+## Trace Output Files
+
+When you start tracing, Playwright creates a `traces/` directory with several files:
+
+### `trace-{timestamp}.trace`
+
+**Action log** - The main trace file containing:
+- Every action performed (clicks, fills, navigations)
+- DOM snapshots before and after each action
+- Screenshots at each step
+- Timing information
+- Console messages
+- Source locations
+
+### `trace-{timestamp}.network`
+
+**Network log** - Complete network activity:
+- All HTTP requests and responses
+- Request headers and bodies
+- Response headers and bodies
+- Timing (DNS, connect, TLS, TTFB, download)
+- Resource sizes
+- Failed requests and errors
+
+### `resources/`
+
+**Resources directory** - Cached resources:
+- Images, fonts, stylesheets, scripts
+- Response bodies for replay
+- Assets needed to reconstruct page state
+
+## What Traces Capture
+
+| Category | Details |
+|----------|---------|
+| **Actions** | Clicks, fills, hovers, keyboard input, navigations |
+| **DOM** | Full DOM snapshot before/after each action |
+| **Screenshots** | Visual state at each step |
+| **Network** | All requests, responses, headers, bodies, timing |
+| **Console** | All console.log, warn, error messages |
+| **Timing** | Precise timing for each operation |
+
+## Use Cases
+
+### Debugging Failed Actions
+
+```bash
+playwright-cli tracing-start
+playwright-cli open https://app.example.com
+
+# This click fails - why?
+playwright-cli click e5
+
+playwright-cli tracing-stop
+# Open trace to see DOM state when click was attempted
+```
+
+### Analyzing Performance
+
+```bash
+playwright-cli tracing-start
+playwright-cli open https://slow-site.com
+playwright-cli tracing-stop
+
+# View network waterfall to identify slow resources
+```
+
+### Capturing Evidence
+
+```bash
+# Record a complete user flow for documentation
+playwright-cli tracing-start
+
+playwright-cli open https://app.example.com/checkout
+playwright-cli fill e1 "4111111111111111"
+playwright-cli fill e2 "12/25"
+playwright-cli fill e3 "123"
+playwright-cli click e4
+
+playwright-cli tracing-stop
+# Trace shows exact sequence of events
+```
+
+## Trace vs Video vs Screenshot
+
+| Feature | Trace | Video | Screenshot |
+|---------|-------|-------|------------|
+| **Format** | .trace file | .webm video | .png/.jpeg image |
+| **DOM inspection** | Yes | No | No |
+| **Network details** | Yes | No | No |
+| **Step-by-step replay** | Yes | Continuous | Single frame |
+| **File size** | Medium | Large | Small |
+| **Best for** | Debugging | Demos | Quick capture |
+
+## Best Practices
+
+### 1. Start Tracing Before the Problem
+
+```bash
+# Trace the entire flow, not just the failing step
+playwright-cli tracing-start
+playwright-cli open https://example.com
+# ... all steps leading to the issue ...
+playwright-cli tracing-stop
+```
+
+### 2. Clean Up Old Traces
+
+Traces can consume significant disk space:
+
+```bash
+# Remove traces older than 7 days
+find .playwright-cli/traces -mtime +7 -delete
+```
+
+## Limitations
+
+- Traces add overhead to automation
+- Large traces can consume significant disk space
+- Some dynamic content may not replay perfectly
diff --git a/.opencode/skills/playwright-cli/references/video-recording.md b/.opencode/skills/playwright-cli/references/video-recording.md
new file mode 100644
index 0000000000..38391b37ad
--- /dev/null
+++ b/.opencode/skills/playwright-cli/references/video-recording.md
@@ -0,0 +1,43 @@
+# Video Recording
+
+Capture browser automation sessions as video for debugging, documentation, or verification. Produces WebM (VP8/VP9 codec).
+
+## Basic Recording
+
+```bash
+# Start recording
+playwright-cli video-start
+
+# Perform actions
+playwright-cli open https://example.com
+playwright-cli snapshot
+playwright-cli click e1
+playwright-cli fill e2 "test input"
+
+# Stop and save
+playwright-cli video-stop demo.webm
+```
+
+## Best Practices
+
+### 1. Use Descriptive Filenames
+
+```bash
+# Include context in filename
+playwright-cli video-stop recordings/login-flow-2024-01-15.webm
+playwright-cli video-stop recordings/checkout-test-run-42.webm
+```
+
+## Tracing vs Video
+
+| Feature | Video | Tracing |
+|---------|-------|---------|
+| Output | WebM file | Trace file (viewable in Trace Viewer) |
+| Shows | Visual recording | DOM snapshots, network, console, actions |
+| Use case | Demos, documentation | Debugging, analysis |
+| Size | Larger | Smaller |
+
+## Limitations
+
+- Recording adds slight overhead to automation
+- Large recordings can consume significant disk space
diff --git a/.opencode/skills/research-codebase/SKILL.md b/.opencode/skills/research-codebase/SKILL.md
index 2d690c4d11..b8c1bc5002 100644
--- a/.opencode/skills/research-codebase/SKILL.md
+++ b/.opencode/skills/research-codebase/SKILL.md
@@ -1,6 +1,9 @@
 ---
 name: research-codebase
 description: Document codebase as-is with research directory for historical context
+aliases: [research]
+argument-hint: "<research-question>"
+required-arguments: [research-question]
 ---
 # Research Codebase
 
@@ -50,7 +53,7 @@ The user's research question/request is: **$ARGUMENTS**
    **For online search:**
    - VERY IMPORTANT: In case you discover external libraries as dependencies, use the **codebase-online-researcher** agent for external documentation and resources
      - If you use DeepWiki tools, instruct the agent to return references to code snippets or documentation, PLEASE INCLUDE those references (e.g. source file names, line numbers, etc.)
-     - If you perform a web search using the WebFetch/WebSearch tools, instruct the agent to return LINKS with their findings, and please INCLUDE those links in the research document
+      - If you perform external web research, use the **playwright-cli** skill (or `bunx @playwright/cli`) to inspect pages, then instruct the agent to return LINKS with their findings and INCLUDE those links in the research document
      - Output directory: `research/docs/`
      - Examples:
        - If researching `Redis` locks usage, the agent might find relevant usage and create a document `research/docs/2024-01-15-redis-locks-usage.md` with internal links to Redis docs and code references
@@ -204,4 +207,4 @@ research/
 ## Final Output
 
 - A collection of research files with comprehensive research findings, properly formatted and linked, ready for consumption to create detailed specifications or design documents.
-- IMPORTANT: DO NOT generate any other artifacts or files OUTSIDE of the `research/` directory.
\ No newline at end of file
+- IMPORTANT: DO NOT generate any other artifacts or files OUTSIDE of the `research/` directory.
diff --git a/.playwright/cli.config.json b/.playwright/cli.config.json
new file mode 100644
index 0000000000..587f73e4f8
--- /dev/null
+++ b/.playwright/cli.config.json
@@ -0,0 +1,8 @@
+{
+  "browser": {
+    "browserName": "chromium",
+    "launchOptions": {
+      "channel": "chromium"
+    }
+  }
+}
\ No newline at end of file
diff --git a/CLAUDE.md b/CLAUDE.md
index 1ea09ce442..ca9ec7930a 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -78,9 +78,8 @@ Relevant resources (use the deepwiki mcp `ask_question` tool for repos):
     2. [CLI](docs/copilot-cli/usage.md)
         1. [Hooks](docs/copilot-cli/hooks.md)
         2. [Skills](docs/copilot-cli/skills.md)
-4. Claude Agent SDK:
-   a. [TypeScript V2 SDK](docs/claude-agent-sdk/typescript-v2-sdk.md), preferred (fallback to v1 if something is not supported)
-   b. [TypeScript SDK](docs/claude-agent-sdk/typescript-sdk.md)
+4. [Claude Agent SDK](docs/claude-agent-sdk.md)
+    - v1 preferred (v2 is unstable and has many bugs)
 
 ### Coding Agent Configuration Locations
 
diff --git a/DEV_SETUP.md b/DEV_SETUP.md
index c2ddfc9776..8ba90b050a 100644
--- a/DEV_SETUP.md
+++ b/DEV_SETUP.md
@@ -26,7 +26,7 @@
 ```bash
 bun test              # Run all tests with coverage
 bun test --bail       # Stop on first failure
-bun test src/graph/   # Run tests for a specific module
+bun test src/workflows/graph/   # Run tests for a specific module
 ```
 
 ### Writing Tests
diff --git a/README.md b/README.md
index f1b3df4ff3..d262488b29 100644
--- a/README.md
+++ b/README.md
@@ -109,6 +109,7 @@ atomic chat -a claude "/research-codebase Research implementing GraphRAG using \
 - [Telemetry](#telemetry)
 - [Troubleshooting](#troubleshooting)
 - [FAQ](#faq)
+- [Workflow Authoring Guide](docs/workflow-authors-getting-started.md)
 - [Contributing Guide](#contributing-guide)
 - [License](#license)
 - [Credits](#credits)
@@ -306,7 +307,6 @@ Top-level Atomic CLI commands.
 | `-w, --workflow` | `false` | Enable graph workflow mode |
 | `-t, --theme <name>` | `"dark"` | UI theme (`dark`, `light`) |
 | `-m, --model <name>` | (none) | Model to use for the chat session |
-| `--max-iterations <n>` | `"100"` | Maximum iterations for workflow mode |
 | `[prompt...]` | (none) | Initial prompt to send |
 
 #### `atomic init` Flags
@@ -417,10 +417,10 @@ The [Ralph Wiggum Method](https://ghuntley.com/ralph/) enables multi-hour autono
 
 1. Create and approve your spec (`/create-spec`)
 2. Start the workflow (`/ralph "<prompt-or-spec-path>"`)
-3. Ralph executes a 3-step process:
-   - **Step 1 — Task Decomposition**: Breaks the spec/prompt into a structured task list
-   - **Step 2 — Implementation Loop**: Dispatches `worker` sub-agents to implement tasks one-by-one (up to 100 iterations)
-   - **Step 3 — Review & Fix**: Spawns a `reviewer` sub-agent to audit the implementation, generates fix specs if needed, and re-runs implementation for any issues found
+3. Ralph executes a 3-phase graph-based workflow:
+   - **Phase 1 — Task Decomposition**: A `planner` sub-agent breaks the spec/prompt into a structured task list with dependency tracking
+   - **Phase 2 — Worker Loop**: Dispatches `worker` sub-agents for ready tasks (those with no blocking dependencies), executing up to 100 iterations
+   - **Phase 3 — Review & Fix**: A `reviewer` sub-agent audits the implementation; if issues are found, a `fixer` sub-agent generates corrective tasks that re-enter the worker loop
 
 ### Usage
 
@@ -717,6 +717,15 @@ git config --global user.email "you@example.com"
 
 **Generating CLAUDE.md/AGENTS.md:** `atomic init` does not create `CLAUDE.md` or `AGENTS.md`. Run `/init` inside a chat session to generate these files. The command explores your codebase and produces project-specific documentation for coding agents.
 
+**Sub-agent Tree Stuck on "Initializing..." or Loading:** Atomic normalizes sub-agent loading and terminal transitions across Claude, OpenCode, and Copilot so agents are only marked complete after terminal events arrive. Background tasks stay in a running/background state until they actually finish.
+
+If loading still appears stuck:
+
+1. Update to the latest release (`atomic update`) and retry.
+2. Confirm the session eventually receives terminal progress events (`subagent.complete` or tool completion) in verbose mode.
+3. If only background tasks are stuck, press `Ctrl+F` twice to terminate active background agents, then resend your prompt.
+4. If the timeout fallback repeats, capture reproduction steps (agent type, prompt, and terminal output) and open an issue.
+
 **Shift+Enter Not Inserting Newline:** Atomic uses layered newline detection in chat input.
 
 - **Kitty protocol (VS Code path):** In VS Code's integrated terminal, keep `terminal.integrated.enableKittyKeyboardProtocol` enabled so Shift+Enter is sent as a modified Enter key.
@@ -769,6 +778,7 @@ This keeps your main workspace free for other work while Ralph runs autonomously
 ## Contributing Guide
 
 See [DEV_SETUP.md](DEV_SETUP.md) for development setup, testing guidelines, and contribution workflow.
+For custom workflow authoring, see [docs/workflow-authors-getting-started.md](docs/workflow-authors-getting-started.md).
 
 ---
 
diff --git a/bun.lock b/bun.lock
index 15b827ad03..cd4de89e8d 100644
--- a/bun.lock
+++ b/bun.lock
@@ -1,35 +1,36 @@
 {
   "lockfileVersion": 1,
-  "configVersion": 0,
+  "configVersion": 1,
   "workspaces": {
     "": {
-      "name": "atomic",
+      "name": "@bastani/atomic",
       "dependencies": {
-        "@anthropic-ai/claude-agent-sdk": "^0.2.50",
-        "@azure/monitor-opentelemetry": "^1.15.1",
+        "@anthropic-ai/claude-agent-sdk": "^0.2.63",
+        "@azure/monitor-opentelemetry": "^1.16.0",
         "@clack/prompts": "^1.0.1",
         "@commander-js/extra-typings": "^14.0.0",
-        "@github/copilot-sdk": "^0.1.25",
-        "@opencode-ai/sdk": "^1.2.10",
+        "@github/copilot-sdk": "^0.1.29",
+        "@opencode-ai/sdk": "^1.2.15",
         "@opentelemetry/api": "^1.9.0",
         "@opentelemetry/api-logs": "^0.212.0",
-        "@opentui/core": "^0.1.81",
-        "@opentui/react": "^0.1.81",
+        "@opentui/core": "^0.1.85",
+        "@opentui/react": "^0.1.85",
         "ci-info": "^4.4.0",
         "commander": "^14.0.3",
+        "zod": "^4.3.6",
       },
       "devDependencies": {
         "@types/bun": "^1.3.9",
         "@types/ci-info": "^3.1.4",
         "@types/react": "^19.2.14",
-        "lefthook": "^2.1.1",
-        "oxlint": "^1.49.0",
+        "lefthook": "^2.1.2",
+        "oxlint": "^1.51.0",
         "typescript": "^5.9.3",
       },
     },
   },
   "packages": {
-    "@anthropic-ai/claude-agent-sdk": ["@anthropic-ai/claude-agent-sdk@0.2.50", "", { "optionalDependencies": { "@img/sharp-darwin-arm64": "^0.34.2", "@img/sharp-darwin-x64": "^0.34.2", "@img/sharp-linux-arm": "^0.34.2", "@img/sharp-linux-arm64": "^0.34.2", "@img/sharp-linux-x64": "^0.34.2", "@img/sharp-linuxmusl-arm64": "^0.34.2", "@img/sharp-linuxmusl-x64": "^0.34.2", "@img/sharp-win32-arm64": "^0.34.2", "@img/sharp-win32-x64": "^0.34.2" }, "peerDependencies": { "zod": "^4.0.0" } }, "sha512-zVQzJbicfTmvS6uarFQYYVYiYedKE0FgXmhiGC1oSLm6OkIbuuKM7XV4fXEFxPZHcWQc7ZYv6HA2/P5HOE7b2Q=="],
+    "@anthropic-ai/claude-agent-sdk": ["@anthropic-ai/claude-agent-sdk@0.2.63", "", { "optionalDependencies": { "@img/sharp-darwin-arm64": "^0.34.2", "@img/sharp-darwin-x64": "^0.34.2", "@img/sharp-linux-arm": "^0.34.2", "@img/sharp-linux-arm64": "^0.34.2", "@img/sharp-linux-x64": "^0.34.2", "@img/sharp-linuxmusl-arm64": "^0.34.2", "@img/sharp-linuxmusl-x64": "^0.34.2", "@img/sharp-win32-arm64": "^0.34.2", "@img/sharp-win32-x64": "^0.34.2" }, "peerDependencies": { "zod": "^4.0.0" } }, "sha512-ZNiaQb/v6xkbrGt3dtq5J0DGY+AaOhoehUyposa3msvlAlkTHWNGR+NhbCcTE0ML1U91xhPqMAAwZIUqrlkKyQ=="],
 
     "@azure/abort-controller": ["@azure/abort-controller@2.1.2", "", { "dependencies": { "tslib": "^2.6.2" } }, "sha512-nBrLsEWm4J2u5LpAPjxADTlq3trDgVZZXHNKabeXZtpq3d3AbN/KGO82R87rdDz5/lYB024rtEf10/q0urNgsA=="],
 
@@ -45,9 +46,9 @@
 
     "@azure/logger": ["@azure/logger@1.3.0", "", { "dependencies": { "@typespec/ts-http-runtime": "^0.3.0", "tslib": "^2.6.2" } }, "sha512-fCqPIfOcLE+CGqGPd66c8bZpwAji98tZ4JI9i/mlTNTlsIWslCfpg48s/ypyLxZTump5sypjrKn2/kY7q8oAbA=="],
 
-    "@azure/monitor-opentelemetry": ["@azure/monitor-opentelemetry@1.15.1", "", { "dependencies": { "@azure/core-auth": "^1.10.1", "@azure/core-client": "^1.10.1", "@azure/core-rest-pipeline": "^1.22.2", "@azure/logger": "^1.3.0", "@azure/monitor-opentelemetry-exporter": "1.0.0-beta.38", "@azure/opentelemetry-instrumentation-azure-sdk": "^1.0.0-beta.9", "@microsoft/applicationinsights-web-snippet": "^1.2.3", "@opentelemetry/api": "^1.9.0", "@opentelemetry/api-logs": "^0.208.0", "@opentelemetry/core": "^2.2.0", "@opentelemetry/instrumentation": "^0.208.0", "@opentelemetry/instrumentation-bunyan": "^0.54.0", "@opentelemetry/instrumentation-http": "^0.208.0", "@opentelemetry/instrumentation-mongodb": "^0.61.0", "@opentelemetry/instrumentation-mysql": "^0.54.0", "@opentelemetry/instrumentation-pg": "^0.61.0", "@opentelemetry/instrumentation-redis": "^0.57.0", "@opentelemetry/instrumentation-winston": "^0.53.0", "@opentelemetry/resource-detector-azure": "^0.7.0", "@opentelemetry/resources": "^2.2.0", "@opentelemetry/sdk-logs": "^0.208.0", "@opentelemetry/sdk-metrics": "^2.2.0", "@opentelemetry/sdk-node": "^0.208.0", "@opentelemetry/sdk-trace-base": "^2.2.0", "@opentelemetry/sdk-trace-node": "^2.2.0", "@opentelemetry/semantic-conventions": "^1.38.0", "@opentelemetry/winston-transport": "^0.19.0", "tslib": "^2.8.1" } }, "sha512-Ybr8BfypmSt0L3TObjMFxv37B6qYI7TTX/fs9V0hi86LI75ZG2bvPAFr9Dt/L2LaNXaLck3fNVQ/ocuMJid7hQ=="],
+    "@azure/monitor-opentelemetry": ["@azure/monitor-opentelemetry@1.16.0", "", { "dependencies": { "@azure/core-auth": "^1.10.1", "@azure/core-client": "^1.10.1", "@azure/core-rest-pipeline": "^1.22.2", "@azure/logger": "^1.3.0", "@azure/monitor-opentelemetry-exporter": "1.0.0-beta.39", "@azure/opentelemetry-instrumentation-azure-sdk": "^1.0.0-beta.9", "@microsoft/applicationinsights-web-snippet": "^1.2.3", "@opentelemetry/api": "^1.9.0", "@opentelemetry/api-logs": "^0.208.0", "@opentelemetry/core": "^2.2.0", "@opentelemetry/instrumentation": "^0.208.0", "@opentelemetry/instrumentation-bunyan": "^0.54.0", "@opentelemetry/instrumentation-http": "^0.208.0", "@opentelemetry/instrumentation-mongodb": "^0.61.0", "@opentelemetry/instrumentation-mysql": "^0.54.0", "@opentelemetry/instrumentation-pg": "^0.61.0", "@opentelemetry/instrumentation-redis": "^0.57.0", "@opentelemetry/instrumentation-winston": "^0.53.0", "@opentelemetry/resource-detector-azure": "^0.7.0", "@opentelemetry/resources": "^2.2.0", "@opentelemetry/sdk-logs": "^0.208.0", "@opentelemetry/sdk-metrics": "^2.2.0", "@opentelemetry/sdk-node": "^0.208.0", "@opentelemetry/sdk-trace-base": "^2.2.0", "@opentelemetry/sdk-trace-node": "^2.2.0", "@opentelemetry/semantic-conventions": "^1.38.0", "@opentelemetry/winston-transport": "^0.19.0", "tslib": "^2.8.1" } }, "sha512-GUE4kowIKrqxzPjiy/o417jot4n0BILomMbDCeK9lOnLxV0VliccEuz+FJ9BgLWKWswr6H0Q2Nzpcx9GFuLHXw=="],
 
-    "@azure/monitor-opentelemetry-exporter": ["@azure/monitor-opentelemetry-exporter@1.0.0-beta.38", "", { "dependencies": { "@azure/core-auth": "^1.9.0", "@azure/core-client": "^1.9.2", "@azure/core-rest-pipeline": "^1.19.0", "@opentelemetry/api": "^1.9.0", "@opentelemetry/api-logs": "^0.205.0", "@opentelemetry/core": "^2.1.0", "@opentelemetry/resources": "^2.1.0", "@opentelemetry/sdk-logs": "^0.205.0", "@opentelemetry/sdk-metrics": "^2.1.0", "@opentelemetry/sdk-trace-base": "^2.1.0", "@opentelemetry/semantic-conventions": "^1.37.0", "tslib": "^2.8.1" } }, "sha512-lzY9XpgRwWC94lzeAf2I1YXrP7oMx1B/vn83zoYA5RKW2ZBPzXZ+LUJjYCo/ItzLfT4eMQC80VL4lQC/VknIMA=="],
+    "@azure/monitor-opentelemetry-exporter": ["@azure/monitor-opentelemetry-exporter@1.0.0-beta.39", "", { "dependencies": { "@azure/core-auth": "^1.9.0", "@azure/core-client": "^1.9.2", "@azure/core-rest-pipeline": "^1.19.0", "@opentelemetry/api": "^1.9.0", "@opentelemetry/api-logs": "^0.205.0", "@opentelemetry/core": "^2.1.0", "@opentelemetry/resources": "^2.1.0", "@opentelemetry/sdk-logs": "^0.205.0", "@opentelemetry/sdk-metrics": "^2.1.0", "@opentelemetry/sdk-trace-base": "^2.1.0", "@opentelemetry/semantic-conventions": "^1.37.0", "tslib": "^2.8.1" } }, "sha512-ljvm3PBe5em/kudINq3kA7wzwCQihYn/1HiO1/lKocK68QGahr6qiTwsadBXWJ2cDUS64iWbHtSM1TsJteBS0A=="],
 
     "@azure/opentelemetry-instrumentation-azure-sdk": ["@azure/opentelemetry-instrumentation-azure-sdk@1.0.0-beta.9", "", { "dependencies": { "@azure/core-tracing": "^1.2.0", "@azure/logger": "^1.0.0", "@opentelemetry/api": "^1.9.0", "@opentelemetry/core": "^2.0.0", "@opentelemetry/instrumentation": "^0.200.0", "@opentelemetry/sdk-trace-web": "^2.0.0", "tslib": "^2.7.0" } }, "sha512-gNCFokEoQQEkhu2T8i1i+1iW2o9wODn2slu5tpqJmjV1W7qf9dxVv6GNXW1P1WC8wMga8BCc2t/oMhOK3iwRQg=="],
 
@@ -61,21 +62,21 @@
 
     "@dimforge/rapier2d-simd-compat": ["@dimforge/rapier2d-simd-compat@0.17.3", "", {}, "sha512-bijvwWz6NHsNj5e5i1vtd3dU2pDhthSaTUZSh14DUGGKJfw8eMnlWZsxwHBxB/a3AXVNDjL9abuHw1k9FGR+jg=="],
 
-    "@github/copilot": ["@github/copilot@0.0.411", "", { "optionalDependencies": { "@github/copilot-darwin-arm64": "0.0.411", "@github/copilot-darwin-x64": "0.0.411", "@github/copilot-linux-arm64": "0.0.411", "@github/copilot-linux-x64": "0.0.411", "@github/copilot-win32-arm64": "0.0.411", "@github/copilot-win32-x64": "0.0.411" }, "bin": { "copilot": "npm-loader.js" } }, "sha512-I3/7gw40Iu1O+kTyNPKJHNqDRyOebjsUW6wJsvSVrOpT0TNa3/lfm8xdS2XUuJWkp+PgEG/PRwF7u3DVNdP7bQ=="],
+    "@github/copilot": ["@github/copilot@0.0.420", "", { "optionalDependencies": { "@github/copilot-darwin-arm64": "0.0.420", "@github/copilot-darwin-x64": "0.0.420", "@github/copilot-linux-arm64": "0.0.420", "@github/copilot-linux-x64": "0.0.420", "@github/copilot-win32-arm64": "0.0.420", "@github/copilot-win32-x64": "0.0.420" }, "bin": { "copilot": "npm-loader.js" } }, "sha512-UpPuSjxUxQ+j02WjZEFffWf0scLb23LvuGHzMFtaSsweR+P/BdbtDUI5ZDIA6T0tVyyt6+X1/vgfsJiRqd6jig=="],
 
-    "@github/copilot-darwin-arm64": ["@github/copilot-darwin-arm64@0.0.411", "", { "os": "darwin", "cpu": "arm64", "bin": { "copilot-darwin-arm64": "copilot" } }, "sha512-dtr+iHxTS4f8HlV2JT9Fp0FFoxuiPWCnU3XGmrHK+rY6bX5okPC2daU5idvs77WKUGcH8yHTZtfbKYUiMxKosw=="],
+    "@github/copilot-darwin-arm64": ["@github/copilot-darwin-arm64@0.0.420", "", { "os": "darwin", "cpu": "arm64", "bin": { "copilot-darwin-arm64": "copilot" } }, "sha512-sj8Oxcf3oKDbeUotm2gtq5YU1lwCt3QIzbMZioFD/PMLOeqSX/wrecI+c0DDYXKofFhALb0+DxxnWgbEs0mnkQ=="],
 
-    "@github/copilot-darwin-x64": ["@github/copilot-darwin-x64@0.0.411", "", { "os": "darwin", "cpu": "x64", "bin": { "copilot-darwin-x64": "copilot" } }, "sha512-zhdbQCbPi1L4iHClackSLx8POfklA+NX9RQLuS48HlKi/0KI/JlaDA/bdbIeMR79wjif5t9gnc/m+RTVmHlRtA=="],
+    "@github/copilot-darwin-x64": ["@github/copilot-darwin-x64@0.0.420", "", { "os": "darwin", "cpu": "x64", "bin": { "copilot-darwin-x64": "copilot" } }, "sha512-2acA93IqXz1uuz3TVUm0Y7BVrBr0MySh1kQa8LqMILhTsG0YHRMm8ybzTp2HA7Mi1tl5CjqMSk163kkS7OzfUA=="],
 
-    "@github/copilot-linux-arm64": ["@github/copilot-linux-arm64@0.0.411", "", { "os": "linux", "cpu": "arm64", "bin": { "copilot-linux-arm64": "copilot" } }, "sha512-oZYZ7oX/7O+jzdTUcHkfD1A8YnNRW6mlUgdPjUg+5rXC43bwIdyatAnc0ObY21m9h8ghxGqholoLhm5WnGv1LQ=="],
+    "@github/copilot-linux-arm64": ["@github/copilot-linux-arm64@0.0.420", "", { "os": "linux", "cpu": "arm64", "bin": { "copilot-linux-arm64": "copilot" } }, "sha512-h/IvEryTOYm1HzR2GNq8s2aDtN4lvT4MxldfZuS42CtWJDOfVG2jLLsoHWU1T3QV8j1++PmDgE//HX0JLpLMww=="],
 
-    "@github/copilot-linux-x64": ["@github/copilot-linux-x64@0.0.411", "", { "os": "linux", "cpu": "x64", "bin": { "copilot-linux-x64": "copilot" } }, "sha512-nnXrKANmmGnkwa3ROlKdAhVNOx8daeMSE8Xh0o3ybKckFv4s38blhKdcxs0RJQRxgAk4p7XXGlDDKNRhurqF1g=="],
+    "@github/copilot-linux-x64": ["@github/copilot-linux-x64@0.0.420", "", { "os": "linux", "cpu": "x64", "bin": { "copilot-linux-x64": "copilot" } }, "sha512-iL2NpZvXIDZ+3lw7sO2fo5T0nKmP5dZbU2gdYcv+SFBm/ONhCxIY5VRX4yN/9VkFaa9ePv5JzCnsl3vZINiDxg=="],
 
-    "@github/copilot-sdk": ["@github/copilot-sdk@0.1.25", "", { "dependencies": { "@github/copilot": "^0.0.411", "vscode-jsonrpc": "^8.2.1", "zod": "^4.3.6" } }, "sha512-hIgYLPXzWw9bNgrsD5BLKmgVH20ow5Or5UyVXfVe3YgeiaTgFxC4jWSAVHLGB6ufHZUrvbjppcq2dWK63FmDRA=="],
+    "@github/copilot-sdk": ["@github/copilot-sdk@0.1.29", "", { "dependencies": { "@github/copilot": "^0.0.420", "vscode-jsonrpc": "^8.2.1", "zod": "^4.3.6" } }, "sha512-GdcN6bJTeesr1HP6IrhN2MznIf1B3ufqd3PX+uKbDLXNriOmP65Ai29/hxzTidNLHyOf6rW4NwmFfkMXiKfCBw=="],
 
-    "@github/copilot-win32-arm64": ["@github/copilot-win32-arm64@0.0.411", "", { "os": "win32", "cpu": "arm64", "bin": { "copilot-win32-arm64": "copilot.exe" } }, "sha512-h+Bovb2YVCQSeELZOO7zxv8uht45XHcvAkFbRsc1gf9dl109sSUJIcB4KAhs8Aznk28qksxz7kvdSgUWyQBlIA=="],
+    "@github/copilot-win32-arm64": ["@github/copilot-win32-arm64@0.0.420", "", { "os": "win32", "cpu": "arm64", "bin": { "copilot-win32-arm64": "copilot.exe" } }, "sha512-Njlc2j9vYSBAL+lC6FIEhQ3C+VxO3xavwKnw0ecVRiNLcGLyPrTdzPfPQOmEjC63gpVCqLabikoDGv8fuLPA2w=="],
 
-    "@github/copilot-win32-x64": ["@github/copilot-win32-x64@0.0.411", "", { "os": "win32", "cpu": "x64", "bin": { "copilot-win32-x64": "copilot.exe" } }, "sha512-xmOgi1lGvUBHQJWmq5AK1EP95+Y8xR4TFoK9OCSOaGbQ+LFcX2jF7iavnMolfWwddabew/AMQjsEHlXvbgMG8Q=="],
+    "@github/copilot-win32-x64": ["@github/copilot-win32-x64@0.0.420", "", { "os": "win32", "cpu": "x64", "bin": { "copilot-win32-x64": "copilot.exe" } }, "sha512-rZlH35oNehAP2DvQbu4vQFVNeCh/1p3rUjafBYaEY0Nkhx7RmdrYBileL5U3PtRPPRsBPaq3Qp+pVIrGoCDLzQ=="],
 
     "@grpc/grpc-js": ["@grpc/grpc-js@1.14.3", "", { "dependencies": { "@grpc/proto-loader": "^0.8.0", "@js-sdsl/ordered-map": "^4.4.2" } }, "sha512-Iq8QQQ/7X3Sac15oB6p0FmUg/klxQvXLeileoqrTRGJYLV+/9tubbr9ipz0GKHjmXVsgFPo/+W+2cA8eNcR+XA=="],
 
@@ -173,15 +174,15 @@
 
     "@microsoft/applicationinsights-web-snippet": ["@microsoft/applicationinsights-web-snippet@1.2.3", "", {}, "sha512-59ex4x1/PabGQIg+o0GKG5olqAJYBvMOiXec/9HCD3hK2y36YMWT0ivq5mequvtS5+21kco3SOnMB6QyScLPIA=="],
 
-    "@opencode-ai/sdk": ["@opencode-ai/sdk@1.2.10", "", {}, "sha512-SyXcVqry2hitPVvQtvXOhqsWyFhSycG/+LTLYXrcq8AFmd9FR7dyBSDB3f5Ol6IPkYOegk8P2Eg2kKPNSNiKGw=="],
+    "@opencode-ai/sdk": ["@opencode-ai/sdk@1.2.15", "", {}, "sha512-NUJNlyBCdZ4R0EBLjJziEQOp2XbRPJosaMcTcWSWO5XJPKGUpz0u8ql+5cR8K+v2RJ+hp2NobtNwpjEYfe6BRQ=="],
 
     "@opentelemetry/api": ["@opentelemetry/api@1.9.0", "", {}, "sha512-3giAOQvZiH5F9bMlMiv8+GSPMeqg0dbaeo58/0SlA9sxSqZhnUtxzX9/2FzyhS9sWQf5S0GJE0AKBrFqjpeYcg=="],
 
     "@opentelemetry/api-logs": ["@opentelemetry/api-logs@0.212.0", "", { "dependencies": { "@opentelemetry/api": "^1.3.0" } }, "sha512-TEEVrLbNROUkYY51sBJGk7lO/OLjuepch8+hmpM6ffMJQ2z/KVCjdHuCFX6fJj8OkJP2zckPjrJzQtXU3IAsFg=="],
 
-    "@opentelemetry/context-async-hooks": ["@opentelemetry/context-async-hooks@2.5.0", "", { "peerDependencies": { "@opentelemetry/api": ">=1.0.0 <1.10.0" } }, "sha512-uOXpVX0ZjO7heSVjhheW2XEPrhQAWr2BScDPoZ9UDycl5iuHG+Usyc3AIfG6kZeC1GyLpMInpQ6X5+9n69yOFw=="],
+    "@opentelemetry/context-async-hooks": ["@opentelemetry/context-async-hooks@2.5.1", "", { "peerDependencies": { "@opentelemetry/api": ">=1.0.0 <1.10.0" } }, "sha512-MHbu8XxCHcBn6RwvCt2Vpn1WnLMNECfNKYB14LI5XypcgH4IE0/DiVifVR9tAkwPMyLXN8dOoPJfya3IryLQVw=="],
 
-    "@opentelemetry/core": ["@opentelemetry/core@2.5.0", "", { "dependencies": { "@opentelemetry/semantic-conventions": "^1.29.0" }, "peerDependencies": { "@opentelemetry/api": ">=1.0.0 <1.10.0" } }, "sha512-ka4H8OM6+DlUhSAZpONu0cPBtPPTQKxbxVzC4CzVx5+K4JnroJVBtDzLAMx4/3CDTJXRvVFhpFjtl4SaiTNoyQ=="],
+    "@opentelemetry/core": ["@opentelemetry/core@2.5.1", "", { "dependencies": { "@opentelemetry/semantic-conventions": "^1.29.0" }, "peerDependencies": { "@opentelemetry/api": ">=1.0.0 <1.10.0" } }, "sha512-Dwlc+3HAZqpgTYq0MUyZABjFkcrKTePwuiFVLjahGD8cx3enqihmpAmdgNFO1R4m/sIe5afjJrA25Prqy4NXlA=="],
 
     "@opentelemetry/exporter-logs-otlp-grpc": ["@opentelemetry/exporter-logs-otlp-grpc@0.208.0", "", { "dependencies": { "@grpc/grpc-js": "^1.7.1", "@opentelemetry/core": "2.2.0", "@opentelemetry/otlp-exporter-base": "0.208.0", "@opentelemetry/otlp-grpc-exporter-base": "0.208.0", "@opentelemetry/otlp-transformer": "0.208.0", "@opentelemetry/sdk-logs": "0.208.0" }, "peerDependencies": { "@opentelemetry/api": "^1.3.0" } }, "sha512-AmZDKFzbq/idME/yq68M155CJW1y056MNBekH9OZewiZKaqgwYN4VYfn3mXVPftYsfrCM2r4V6tS8H2LmfiDCg=="],
 
@@ -235,79 +236,79 @@
 
     "@opentelemetry/resource-detector-azure": ["@opentelemetry/resource-detector-azure@0.7.0", "", { "dependencies": { "@opentelemetry/core": "^2.0.0", "@opentelemetry/resources": "^2.0.0", "@opentelemetry/semantic-conventions": "^1.27.0" }, "peerDependencies": { "@opentelemetry/api": "^1.0.0" } }, "sha512-aR2ALsK+b/+5lLDhK9KTK8rcuKg7+sqa/Cg+QCeasqoy7qby70FRtAbQcZGljJ5BLBcVPYjl1hcTYIUyL3Laww=="],
 
-    "@opentelemetry/resources": ["@opentelemetry/resources@2.5.0", "", { "dependencies": { "@opentelemetry/core": "2.5.0", "@opentelemetry/semantic-conventions": "^1.29.0" }, "peerDependencies": { "@opentelemetry/api": ">=1.3.0 <1.10.0" } }, "sha512-F8W52ApePshpoSrfsSk1H2yJn9aKjCrbpQF1M9Qii0GHzbfVeFUB+rc3X4aggyZD8x9Gu3Slua+s6krmq6Dt8g=="],
+    "@opentelemetry/resources": ["@opentelemetry/resources@2.5.1", "", { "dependencies": { "@opentelemetry/core": "2.5.1", "@opentelemetry/semantic-conventions": "^1.29.0" }, "peerDependencies": { "@opentelemetry/api": ">=1.3.0 <1.10.0" } }, "sha512-BViBCdE/GuXRlp9k7nS1w6wJvY5fnFX5XvuEtWsTAOQFIO89Eru7lGW3WbfbxtCuZ/GbrJfAziXG0w0dpxL7eQ=="],
 
     "@opentelemetry/sdk-logs": ["@opentelemetry/sdk-logs@0.208.0", "", { "dependencies": { "@opentelemetry/api-logs": "0.208.0", "@opentelemetry/core": "2.2.0", "@opentelemetry/resources": "2.2.0" }, "peerDependencies": { "@opentelemetry/api": ">=1.4.0 <1.10.0" } }, "sha512-QlAyL1jRpOeaqx7/leG1vJMp84g0xKP6gJmfELBpnI4O/9xPX+Hu5m1POk9Kl+veNkyth5t19hRlN6tNY1sjbA=="],
 
-    "@opentelemetry/sdk-metrics": ["@opentelemetry/sdk-metrics@2.5.0", "", { "dependencies": { "@opentelemetry/core": "2.5.0", "@opentelemetry/resources": "2.5.0" }, "peerDependencies": { "@opentelemetry/api": ">=1.9.0 <1.10.0" } }, "sha512-BeJLtU+f5Gf905cJX9vXFQorAr6TAfK3SPvTFqP+scfIpDQEJfRaGJWta7sJgP+m4dNtBf9y3yvBKVAZZtJQVA=="],
+    "@opentelemetry/sdk-metrics": ["@opentelemetry/sdk-metrics@2.5.1", "", { "dependencies": { "@opentelemetry/core": "2.5.1", "@opentelemetry/resources": "2.5.1" }, "peerDependencies": { "@opentelemetry/api": ">=1.9.0 <1.10.0" } }, "sha512-RKMn3QKi8nE71ULUo0g/MBvq1N4icEBo7cQSKnL3URZT16/YH3nSVgWegOjwx7FRBTrjOIkMJkCUn/ZFIEfn4A=="],
 
     "@opentelemetry/sdk-node": ["@opentelemetry/sdk-node@0.208.0", "", { "dependencies": { "@opentelemetry/api-logs": "0.208.0", "@opentelemetry/core": "2.2.0", "@opentelemetry/exporter-logs-otlp-grpc": "0.208.0", "@opentelemetry/exporter-logs-otlp-http": "0.208.0", "@opentelemetry/exporter-logs-otlp-proto": "0.208.0", "@opentelemetry/exporter-metrics-otlp-grpc": "0.208.0", "@opentelemetry/exporter-metrics-otlp-http": "0.208.0", "@opentelemetry/exporter-metrics-otlp-proto": "0.208.0", "@opentelemetry/exporter-prometheus": "0.208.0", "@opentelemetry/exporter-trace-otlp-grpc": "0.208.0", "@opentelemetry/exporter-trace-otlp-http": "0.208.0", "@opentelemetry/exporter-trace-otlp-proto": "0.208.0", "@opentelemetry/exporter-zipkin": "2.2.0", "@opentelemetry/instrumentation": "0.208.0", "@opentelemetry/propagator-b3": "2.2.0", "@opentelemetry/propagator-jaeger": "2.2.0", "@opentelemetry/resources": "2.2.0", "@opentelemetry/sdk-logs": "0.208.0", "@opentelemetry/sdk-metrics": "2.2.0", "@opentelemetry/sdk-trace-base": "2.2.0", "@opentelemetry/sdk-trace-node": "2.2.0", "@opentelemetry/semantic-conventions": "^1.29.0" }, "peerDependencies": { "@opentelemetry/api": ">=1.3.0 <1.10.0" } }, "sha512-pbAqpZ7zTMFuTf3YecYsecsto/mheuvnK2a/jgstsE5ynWotBjgF5bnz5500W9Xl2LeUfg04WMt63TWtAgzRMw=="],
 
-    "@opentelemetry/sdk-trace-base": ["@opentelemetry/sdk-trace-base@2.5.0", "", { "dependencies": { "@opentelemetry/core": "2.5.0", "@opentelemetry/resources": "2.5.0", "@opentelemetry/semantic-conventions": "^1.29.0" }, "peerDependencies": { "@opentelemetry/api": ">=1.3.0 <1.10.0" } }, "sha512-VzRf8LzotASEyNDUxTdaJ9IRJ1/h692WyArDBInf5puLCjxbICD6XkHgpuudis56EndyS7LYFmtTMny6UABNdQ=="],
+    "@opentelemetry/sdk-trace-base": ["@opentelemetry/sdk-trace-base@2.5.1", "", { "dependencies": { "@opentelemetry/core": "2.5.1", "@opentelemetry/resources": "2.5.1", "@opentelemetry/semantic-conventions": "^1.29.0" }, "peerDependencies": { "@opentelemetry/api": ">=1.3.0 <1.10.0" } }, "sha512-iZH3Gw8cxQn0gjpOjJMmKLd9GIaNh/E3v3ST67vyzLSxHBs14HsG4dy7jMYyC5WXGdBVEcM7U/XTF5hCQxjDMw=="],
 
-    "@opentelemetry/sdk-trace-node": ["@opentelemetry/sdk-trace-node@2.5.0", "", { "dependencies": { "@opentelemetry/context-async-hooks": "2.5.0", "@opentelemetry/core": "2.5.0", "@opentelemetry/sdk-trace-base": "2.5.0" }, "peerDependencies": { "@opentelemetry/api": ">=1.0.0 <1.10.0" } }, "sha512-O6N/ejzburFm2C84aKNrwJVPpt6HSTSq8T0ZUMq3xT2XmqT4cwxUItcL5UWGThYuq8RTcbH8u1sfj6dmRci0Ow=="],
+    "@opentelemetry/sdk-trace-node": ["@opentelemetry/sdk-trace-node@2.5.1", "", { "dependencies": { "@opentelemetry/context-async-hooks": "2.5.1", "@opentelemetry/core": "2.5.1", "@opentelemetry/sdk-trace-base": "2.5.1" }, "peerDependencies": { "@opentelemetry/api": ">=1.0.0 <1.10.0" } }, "sha512-9lopQ6ZoElETOEN0csgmtEV5/9C7BMfA7VtF4Jape3i954b6sTY2k3Xw3CxUTKreDck/vpAuJM+EDo4zheUw+A=="],
 
-    "@opentelemetry/sdk-trace-web": ["@opentelemetry/sdk-trace-web@2.5.0", "", { "dependencies": { "@opentelemetry/core": "2.5.0", "@opentelemetry/sdk-trace-base": "2.5.0" }, "peerDependencies": { "@opentelemetry/api": ">=1.0.0 <1.10.0" } }, "sha512-xWibakHs+xbx6vxH7Q8TbFS6zjf812o/kIS4xBDB32qSL9wF+Z5IZl2ZAGu4rtmPBQ7coZcOd684DobMhf8dKw=="],
+    "@opentelemetry/sdk-trace-web": ["@opentelemetry/sdk-trace-web@2.5.1", "", { "dependencies": { "@opentelemetry/core": "2.5.1", "@opentelemetry/sdk-trace-base": "2.5.1" }, "peerDependencies": { "@opentelemetry/api": ">=1.0.0 <1.10.0" } }, "sha512-4PWFtMJ5nqWMP2YqgKjcMlQlUeN1imUYSXdhy6Xl/3bnO0/Ryo5Y3/kWG8T66uMHo2RpTQLloZjoQACKdbHbxg=="],
 
-    "@opentelemetry/semantic-conventions": ["@opentelemetry/semantic-conventions@1.39.0", "", {}, "sha512-R5R9tb2AXs2IRLNKLBJDynhkfmx7mX0vi8NkhZb3gUkPWHn6HXk5J8iQ/dql0U3ApfWym4kXXmBDRGO+oeOfjg=="],
+    "@opentelemetry/semantic-conventions": ["@opentelemetry/semantic-conventions@1.40.0", "", {}, "sha512-cifvXDhcqMwwTlTK04GBNeIe7yyo28Mfby85QXFe1Yk8nmi36Ab/5UQwptOx84SsoGNRg+EVSjwzfSZMy6pmlw=="],
 
     "@opentelemetry/sql-common": ["@opentelemetry/sql-common@0.41.2", "", { "dependencies": { "@opentelemetry/core": "^2.0.0" }, "peerDependencies": { "@opentelemetry/api": "^1.1.0" } }, "sha512-4mhWm3Z8z+i508zQJ7r6Xi7y4mmoJpdvH0fZPFRkWrdp5fq7hhZ2HhYokEOLkfqSMgPR4Z9EyB3DBkbKGOqZiQ=="],
 
     "@opentelemetry/winston-transport": ["@opentelemetry/winston-transport@0.19.0", "", { "dependencies": { "@opentelemetry/api-logs": "^0.208.0", "winston-transport": "4.*" } }, "sha512-MeG0fGNcpAhW9J9LiHgAJqIPySzj1xHCx4F+2R0ir4fzvm0ghKQRv6iUm3u1AhyKKJzDBeoHu7W98jJHNw8dnA=="],
 
-    "@opentui/core": ["@opentui/core@0.1.81", "", { "dependencies": { "bun-ffi-structs": "0.1.2", "diff": "8.0.2", "jimp": "1.6.0", "marked": "17.0.1", "yoga-layout": "3.2.1" }, "optionalDependencies": { "@dimforge/rapier2d-simd-compat": "^0.17.3", "@opentui/core-darwin-arm64": "0.1.81", "@opentui/core-darwin-x64": "0.1.81", "@opentui/core-linux-arm64": "0.1.81", "@opentui/core-linux-x64": "0.1.81", "@opentui/core-win32-arm64": "0.1.81", "@opentui/core-win32-x64": "0.1.81", "bun-webgpu": "0.1.5", "planck": "^1.4.2", "three": "0.177.0" }, "peerDependencies": { "web-tree-sitter": "0.25.10" } }, "sha512-ooFjkkQ80DDC4X5eLvH8dBcLAtWwGp9RTaWsaeWet3GOv4N0SDcN8mi1XGhYnUlTuxmofby5eQrPegjtWHODlA=="],
+    "@opentui/core": ["@opentui/core@0.1.85", "", { "dependencies": { "bun-ffi-structs": "0.1.2", "diff": "8.0.2", "jimp": "1.6.0", "marked": "17.0.1", "yoga-layout": "3.2.1" }, "optionalDependencies": { "@dimforge/rapier2d-simd-compat": "^0.17.3", "@opentui/core-darwin-arm64": "0.1.85", "@opentui/core-darwin-x64": "0.1.85", "@opentui/core-linux-arm64": "0.1.85", "@opentui/core-linux-x64": "0.1.85", "@opentui/core-win32-arm64": "0.1.85", "@opentui/core-win32-x64": "0.1.85", "bun-webgpu": "0.1.5", "planck": "^1.4.2", "three": "0.177.0" }, "peerDependencies": { "web-tree-sitter": "0.25.10" } }, "sha512-nZv84b6lLIX55y9sHRQIzydoEWc30bFbHbdqT+CLM38cCDjP2AS9uVYW93EYYblhKppAcLWY14zobIgUr2Rm5Q=="],
 
-    "@opentui/core-darwin-arm64": ["@opentui/core-darwin-arm64@0.1.81", "", { "os": "darwin", "cpu": "arm64" }, "sha512-I3Ry5JbkSQXs2g1me8yYr0v3CUcIIfLHzbWz9WMFla8kQDSa+HOr8IpZbqZDeIFgOVzolAXBmZhg0VJI3bZ7MA=="],
+    "@opentui/core-darwin-arm64": ["@opentui/core-darwin-arm64@0.1.85", "", { "os": "darwin", "cpu": "arm64" }, "sha512-Fbno4MJ+TufgKSSPWhq8ifu74pKF+FT9rCNeVK/Ip+jKpdqmwskPA7XFf8lhAusnLItp+Os1XdTb+NnSK1uzYw=="],
 
-    "@opentui/core-darwin-x64": ["@opentui/core-darwin-x64@0.1.81", "", { "os": "darwin", "cpu": "x64" }, "sha512-CrtNKu41D6+bOQdUOmDX4Q3hTL6p+sT55wugPzbDq7cdqFZabCeguBAyOlvRl2g2aJ93kmOWW6MXG0bPPklEFg=="],
+    "@opentui/core-darwin-x64": ["@opentui/core-darwin-x64@0.1.85", "", { "os": "darwin", "cpu": "x64" }, "sha512-tAc4hT6uox2zJRb8UPZhWSzi5plsw7uVLRQkGaQvwo4jvz0OAMvMLKbNi7Gzp8yMcbkHJUvYoLBrDRBKWntcFQ=="],
 
-    "@opentui/core-linux-arm64": ["@opentui/core-linux-arm64@0.1.81", "", { "os": "linux", "cpu": "arm64" }, "sha512-FJw9zmJop9WiMvtT07nSrfBLPLqskxL6xfV3GNft0mSYV+C3hdJ0qkiczGSHUX/6V7fmouM84RWwmY53Rb6hYQ=="],
+    "@opentui/core-linux-arm64": ["@opentui/core-linux-arm64@0.1.85", "", { "os": "linux", "cpu": "arm64" }, "sha512-QqpHAiI2BXdlzW9PLcOmm8qZ0HbEk0UA9vWnO0S60b4laMElz8cXmQI61/76p/nVUjWWKYk6iChmEoKcsBEV6g=="],
 
-    "@opentui/core-linux-x64": ["@opentui/core-linux-x64@0.1.81", "", { "os": "linux", "cpu": "x64" }, "sha512-Rj2AFIiuWI0BEMIvh/Jeuxty9Gp5ZhLuQU7ZHJJhojKo/mpBpMs9X+5kwZPZya/tyR8uVDAVyB6AOLkhdRW5lw=="],
+    "@opentui/core-linux-x64": ["@opentui/core-linux-x64@0.1.85", "", { "os": "linux", "cpu": "x64" }, "sha512-33olcddu72Gves86+QO94G1FHjyZJs15aSAGyd3DogVdZbrmaHfIwQ/Bkq6MOOsicOfcOJBJBmsaPOTyT8/f2Q=="],
 
-    "@opentui/core-win32-arm64": ["@opentui/core-win32-arm64@0.1.81", "", { "os": "win32", "cpu": "arm64" }, "sha512-AiZB+mZ1cVr8plAPrPT98e3kw6D0OdOSe2CQYLgJRbfRlPqq3jl26lHPzDb3ZO2OR0oVGRPJvXraus939mvoiQ=="],
+    "@opentui/core-win32-arm64": ["@opentui/core-win32-arm64@0.1.85", "", { "os": "win32", "cpu": "arm64" }, "sha512-BtWd/hORUl69efiPUhwvdjvz87l+Us/BmoDeLsGxBRmoTOWfQWMqCjCeH7HyEC5MboBFhla/1qDCXjuEbKWtNQ=="],
 
-    "@opentui/core-win32-x64": ["@opentui/core-win32-x64@0.1.81", "", { "os": "win32", "cpu": "x64" }, "sha512-l8R2Ni1CR4eHi3DTmSkEL/EjHAtOZ/sndYs3VVw+Ej2esL3Mf0W7qSO5S0YNBanz2VXZhbkmM6ERm9keH8RD3w=="],
+    "@opentui/core-win32-x64": ["@opentui/core-win32-x64@0.1.85", "", { "os": "win32", "cpu": "x64" }, "sha512-YO73TAC8maV96ytsqDwyCDU5+JHBqgqYioycraQ7zj8IkdfkmqAPnmNSksMYgsUgf9GQdwhkNjtttYLfgrJlTA=="],
 
-    "@opentui/react": ["@opentui/react@0.1.81", "", { "dependencies": { "@opentui/core": "0.1.81", "react-reconciler": "^0.32.0" }, "peerDependencies": { "react": ">=19.0.0", "react-devtools-core": "^7.0.1", "ws": "^8.18.0" } }, "sha512-Qlgt2j081EdYxBgNpiHQEw3I/Kgw+UZLCx6IliSetF7wGw4nXWPLSgCsa5aZpVj25/vzZnHyEkTZcx8Pq8xn8Q=="],
+    "@opentui/react": ["@opentui/react@0.1.85", "", { "dependencies": { "@opentui/core": "0.1.85", "react-reconciler": "^0.32.0" }, "peerDependencies": { "react": ">=19.0.0", "react-devtools-core": "^7.0.1", "ws": "^8.18.0" } }, "sha512-yS9b6pMG6qr3D7pxZhFg0xbv54zUDWMpwF4JgGKc0NVGIcrLnJyab1E0swi7DQuhHMr1oJ4EZjBImeWYYn4TJw=="],
 
-    "@oxlint/binding-android-arm-eabi": ["@oxlint/binding-android-arm-eabi@1.49.0", "", { "os": "android", "cpu": "arm" }, "sha512-2WPoh/2oK9r/i2R4o4J18AOrm3HVlWiHZ8TnuCaS4dX8m5ZzRmHW0I3eLxEurQLHWVruhQN7fHgZnah+ag5iQg=="],
+    "@oxlint/binding-android-arm-eabi": ["@oxlint/binding-android-arm-eabi@1.51.0", "", { "os": "android", "cpu": "arm" }, "sha512-jJYIqbx4sX+suIxWstc4P7SzhEwb4ArWA2KVrmEuu9vH2i0qM6QIHz/ehmbGE4/2fZbpuMuBzTl7UkfNoqiSgw=="],
 
-    "@oxlint/binding-android-arm64": ["@oxlint/binding-android-arm64@1.49.0", "", { "os": "android", "cpu": "arm64" }, "sha512-YqJAGvNB11EzoKm1euVhZntb79alhMvWW/j12bYqdvVxn6xzEQWrEDCJg9BPo3A3tBCSUBKH7bVkAiCBqK/L1w=="],
+    "@oxlint/binding-android-arm64": ["@oxlint/binding-android-arm64@1.51.0", "", { "os": "android", "cpu": "arm64" }, "sha512-GtXyBCcH4ti98YdiMNCrpBNGitx87EjEWxevnyhcBK12k/Vu4EzSB45rzSC4fGFUD6sQgeaxItRCEEWeVwPafw=="],
 
-    "@oxlint/binding-darwin-arm64": ["@oxlint/binding-darwin-arm64@1.49.0", "", { "os": "darwin", "cpu": "arm64" }, "sha512-WFocCRlvVkMhChCJ2qpJfp1Gj/IjvyjuifH9Pex8m8yHonxxQa3d8DZYreuDQU3T4jvSY8rqhoRqnpc61Nlbxw=="],
+    "@oxlint/binding-darwin-arm64": ["@oxlint/binding-darwin-arm64@1.51.0", "", { "os": "darwin", "cpu": "arm64" }, "sha512-3QJbeYaMHn6Bh2XeBXuITSsbnIctyTjvHf5nRjKYrT9pPeErNIpp5VDEeAXC0CZSwSVTsc8WOSDwgrAI24JolQ=="],
 
-    "@oxlint/binding-darwin-x64": ["@oxlint/binding-darwin-x64@1.49.0", "", { "os": "darwin", "cpu": "x64" }, "sha512-BN0KniwvehbUfYztOMwEDkYoojGm/narf5oJf+/ap+6PnzMeWLezMaVARNIS0j3OdMkjHTEP8s3+GdPJ7WDywQ=="],
+    "@oxlint/binding-darwin-x64": ["@oxlint/binding-darwin-x64@1.51.0", "", { "os": "darwin", "cpu": "x64" }, "sha512-NzErhMaTEN1cY0E8C5APy74lw5VwsNfJfVPBMWPVQLqAbO0k4FFLjvHURvkUL+Y18Wu+8Vs1kbqPh2hjXYA4pg=="],
 
-    "@oxlint/binding-freebsd-x64": ["@oxlint/binding-freebsd-x64@1.49.0", "", { "os": "freebsd", "cpu": "x64" }, "sha512-SnkAc/DPIY6joMCiP/+53Q+N2UOGMU6ULvbztpmvPJNF/jYPGhNbKtN982uj2Gs6fpbxYkmyj08QnpkD4fbHJA=="],
+    "@oxlint/binding-freebsd-x64": ["@oxlint/binding-freebsd-x64@1.51.0", "", { "os": "freebsd", "cpu": "x64" }, "sha512-msAIh3vPAoKoHlOE/oe6Q5C/n9umypv/k81lED82ibrJotn+3YG2Qp1kiR8o/Dg5iOEU97c6tl0utxcyFenpFw=="],
 
-    "@oxlint/binding-linux-arm-gnueabihf": ["@oxlint/binding-linux-arm-gnueabihf@1.49.0", "", { "os": "linux", "cpu": "arm" }, "sha512-6Z3EzRvpQVIpO7uFhdiGhdE8Mh3S2VWKLL9xuxVqD6fzPhyI3ugthpYXlCChXzO8FzcYIZ3t1+Kau+h2NY1hqA=="],
+    "@oxlint/binding-linux-arm-gnueabihf": ["@oxlint/binding-linux-arm-gnueabihf@1.51.0", "", { "os": "linux", "cpu": "arm" }, "sha512-CqQPcvqYyMe9ZBot2stjGogEzk1z8gGAngIX7srSzrzexmXixwVxBdFZyxTVM0CjGfDeV+Ru0w25/WNjlMM2Hw=="],
 
-    "@oxlint/binding-linux-arm-musleabihf": ["@oxlint/binding-linux-arm-musleabihf@1.49.0", "", { "os": "linux", "cpu": "arm" }, "sha512-wdjXaQYAL/L25732mLlngfst4Jdmi/HLPVHb3yfCoP5mE3lO/pFFrmOJpqWodgv29suWY74Ij+RmJ/YIG5VuzQ=="],
+    "@oxlint/binding-linux-arm-musleabihf": ["@oxlint/binding-linux-arm-musleabihf@1.51.0", "", { "os": "linux", "cpu": "arm" }, "sha512-dstrlYQgZMnyOssxSbolGCge/sDbko12N/35RBNuqLpoPbft2aeBidBAb0dvQlyBd9RJ6u8D4o4Eh8Un6iTgyQ=="],
 
-    "@oxlint/binding-linux-arm64-gnu": ["@oxlint/binding-linux-arm64-gnu@1.49.0", "", { "os": "linux", "cpu": "arm64" }, "sha512-oSHpm8zmSvAG1BWUumbDRSg7moJbnwoEXKAkwDf/xTQJOzvbUknq95NVQdw/AduZr5dePftalB8rzJNGBogUMg=="],
+    "@oxlint/binding-linux-arm64-gnu": ["@oxlint/binding-linux-arm64-gnu@1.51.0", "", { "os": "linux", "cpu": "arm64" }, "sha512-QEjUpXO7d35rP1/raLGGbAsBLLGZIzV3ZbeSjqWlD3oRnxpRIZ6iL4o51XQHkconn3uKssc+1VKdtHJ81BBhDA=="],
 
-    "@oxlint/binding-linux-arm64-musl": ["@oxlint/binding-linux-arm64-musl@1.49.0", "", { "os": "linux", "cpu": "arm64" }, "sha512-xeqkMOARgGBlEg9BQuPDf6ZW711X6BT5qjDyeM5XNowCJeTSdmMhpePJjTEiVbbr3t21sIlK8RE6X5bc04nWyQ=="],
+    "@oxlint/binding-linux-arm64-musl": ["@oxlint/binding-linux-arm64-musl@1.51.0", "", { "os": "linux", "cpu": "arm64" }, "sha512-YSJua5irtG4DoMAjUapDTPhkQLHhBIY0G9JqlZS6/SZPzqDkPku/1GdWs0D6h/wyx0Iz31lNCfIaWKBQhzP0wQ=="],
 
-    "@oxlint/binding-linux-ppc64-gnu": ["@oxlint/binding-linux-ppc64-gnu@1.49.0", "", { "os": "linux", "cpu": "ppc64" }, "sha512-uvcqRO6PnlJGbL7TeePhTK5+7/JXbxGbN+C6FVmfICDeeRomgQqrfVjf0lUrVpUU8ii8TSkIbNdft3M+oNlOsQ=="],
+    "@oxlint/binding-linux-ppc64-gnu": ["@oxlint/binding-linux-ppc64-gnu@1.51.0", "", { "os": "linux", "cpu": "ppc64" }, "sha512-7L4Wj2IEUNDETKssB9IDYt16T6WlF+X2jgC/hBq3diGHda9vJLpAgb09+D3quFq7TdkFtI7hwz/jmuQmQFPc1Q=="],
 
-    "@oxlint/binding-linux-riscv64-gnu": ["@oxlint/binding-linux-riscv64-gnu@1.49.0", "", { "os": "linux", "cpu": "none" }, "sha512-Dw1HkdXAwHNH+ZDserHP2RzXQmhHtpsYYI0hf8fuGAVCIVwvS6w1+InLxpPMY25P8ASRNiFN3hADtoh6lI+4lg=="],
+    "@oxlint/binding-linux-riscv64-gnu": ["@oxlint/binding-linux-riscv64-gnu@1.51.0", "", { "os": "linux", "cpu": "none" }, "sha512-cBUHqtOXy76G41lOB401qpFoKx1xq17qYkhWrLSM7eEjiHM9sOtYqpr6ZdqCnN9s6ZpzudX4EkeHOFH2E9q0vA=="],
 
-    "@oxlint/binding-linux-riscv64-musl": ["@oxlint/binding-linux-riscv64-musl@1.49.0", "", { "os": "linux", "cpu": "none" }, "sha512-EPlMYaA05tJ9km/0dI9K57iuMq3Tw+nHst7TNIegAJZrBPtsOtYaMFZEaWj02HA8FI5QvSnRHMt+CI+RIhXJBQ=="],
+    "@oxlint/binding-linux-riscv64-musl": ["@oxlint/binding-linux-riscv64-musl@1.51.0", "", { "os": "linux", "cpu": "none" }, "sha512-WKbg8CysgZcHfZX0ixQFBRSBvFZUHa3SBnEjHY2FVYt2nbNJEjzTxA3ZR5wMU0NOCNKIAFUFvAh5/XJKPRJuJg=="],
 
-    "@oxlint/binding-linux-s390x-gnu": ["@oxlint/binding-linux-s390x-gnu@1.49.0", "", { "os": "linux", "cpu": "s390x" }, "sha512-yZiQL9qEwse34aMbnMb5VqiAWfDY+fLFuoJbHOuzB1OaJZbN1MRF9Nk+W89PIpGr5DNPDipwjZb8+Q7wOywoUQ=="],
+    "@oxlint/binding-linux-s390x-gnu": ["@oxlint/binding-linux-s390x-gnu@1.51.0", "", { "os": "linux", "cpu": "s390x" }, "sha512-N1QRUvJTxqXNSu35YOufdjsAVmKVx5bkrggOWAhTWBc3J4qjcBwr1IfyLh/6YCg8sYRSR1GraldS9jUgJL/U4A=="],
 
-    "@oxlint/binding-linux-x64-gnu": ["@oxlint/binding-linux-x64-gnu@1.49.0", "", { "os": "linux", "cpu": "x64" }, "sha512-CcCDwMMXSchNkhdgvhVn3DLZ4EnBXAD8o8+gRzahg+IdSt/72y19xBgShJgadIRF0TsRcV/MhDUMwL5N/W54aQ=="],
+    "@oxlint/binding-linux-x64-gnu": ["@oxlint/binding-linux-x64-gnu@1.51.0", "", { "os": "linux", "cpu": "x64" }, "sha512-e0Mz0DizsCoqNIjeOg6OUKe8JKJWZ5zZlwsd05Bmr51Jo3AOL4UJnPvwKumr4BBtBrDZkCmOLhCvDGm95nJM2g=="],
 
-    "@oxlint/binding-linux-x64-musl": ["@oxlint/binding-linux-x64-musl@1.49.0", "", { "os": "linux", "cpu": "x64" }, "sha512-u3HfKV8BV6t6UCCbN0RRiyqcymhrnpunVmLFI8sEa5S/EBu+p/0bJ3D7LZ2KT6PsBbrB71SWq4DeFrskOVgIZg=="],
+    "@oxlint/binding-linux-x64-musl": ["@oxlint/binding-linux-x64-musl@1.51.0", "", { "os": "linux", "cpu": "x64" }, "sha512-wD8HGTWhYBKXvRDvoBVB1y+fEYV01samhWQSy1Zkxq2vpezvMnjaFKRuiP6tBNITLGuffbNDEXOwcAhJ3gI5Ug=="],
 
-    "@oxlint/binding-openharmony-arm64": ["@oxlint/binding-openharmony-arm64@1.49.0", "", { "os": "none", "cpu": "arm64" }, "sha512-dRDpH9fw+oeUMpM4br0taYCFpW6jQtOuEIec89rOgDA1YhqwmeRcx0XYeCv7U48p57qJ1XZHeMGM9LdItIjfzA=="],
+    "@oxlint/binding-openharmony-arm64": ["@oxlint/binding-openharmony-arm64@1.51.0", "", { "os": "none", "cpu": "arm64" }, "sha512-5NSwQ2hDEJ0GPXqikjWtwzgAQCsS7P9aLMNenjjKa+gknN3lTCwwwERsT6lKXSirfU3jLjexA2XQvQALh5h27w=="],
 
-    "@oxlint/binding-win32-arm64-msvc": ["@oxlint/binding-win32-arm64-msvc@1.49.0", "", { "os": "win32", "cpu": "arm64" }, "sha512-6rrKe/wL9tn0qnOy76i1/0f4Dc3dtQnibGlU4HqR/brVHlVjzLSoaH0gAFnLnznh9yQ6gcFTBFOPrcN/eKPDGA=="],
+    "@oxlint/binding-win32-arm64-msvc": ["@oxlint/binding-win32-arm64-msvc@1.51.0", "", { "os": "win32", "cpu": "arm64" }, "sha512-JEZyah1M0RHMw8d+jjSSJmSmO8sABA1J1RtrHYujGPeCkYg1NeH0TGuClpe2h5QtioRTaF57y/TZfn/2IFV6fA=="],
 
-    "@oxlint/binding-win32-ia32-msvc": ["@oxlint/binding-win32-ia32-msvc@1.49.0", "", { "os": "win32", "cpu": "ia32" }, "sha512-CXHLWAtLs2xG/aVy1OZiYJzrULlq0QkYpI6cd7VKMrab+qur4fXVE/B1Bp1m0h1qKTj5/FTGg6oU4qaXMjS/ug=="],
+    "@oxlint/binding-win32-ia32-msvc": ["@oxlint/binding-win32-ia32-msvc@1.51.0", "", { "os": "win32", "cpu": "ia32" }, "sha512-q3cEoKH6kwjz/WRyHwSf0nlD2F5Qw536kCXvmlSu+kaShzgrA0ojmh45CA81qL+7udfCaZL2SdKCZlLiGBVFlg=="],
 
-    "@oxlint/binding-win32-x64-msvc": ["@oxlint/binding-win32-x64-msvc@1.49.0", "", { "os": "win32", "cpu": "x64" }, "sha512-VteIelt78kwzSglOozaQcs6BCS4Lk0j+QA+hGV0W8UeyaqQ3XpbZRhDU55NW1PPvCy1tg4VXsTlEaPovqto7nQ=="],
+    "@oxlint/binding-win32-x64-msvc": ["@oxlint/binding-win32-x64-msvc@1.51.0", "", { "os": "win32", "cpu": "x64" }, "sha512-Q14+fOGb9T28nWF/0EUsYqERiRA7cl1oy4TJrGmLaqhm+aO2cV+JttboHI3CbdeMCAyDI1+NoSlrM7Melhp/cw=="],
 
     "@protobufjs/aspromise": ["@protobufjs/aspromise@1.1.2", "", {}, "sha512-j+gKExEuLmKwvz3OgROXtrJ2UG2x8Ch2YZUxahh+s1F2HZ+wAceUNLkvy6zKCPVRkU++ZWQrdxsUeQXmcg4uoQ=="],
 
@@ -339,7 +340,7 @@
 
     "@types/mysql": ["@types/mysql@2.15.27", "", { "dependencies": { "@types/node": "*" } }, "sha512-YfWiV16IY0OeBfBCk8+hXKmdTKrKlwKN1MNKAPBu5JYxLwBEZl7QzeEpGnlZb3VMGJrrGmB84gXiH+ofs/TezA=="],
 
-    "@types/node": ["@types/node@25.0.9", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-/rpCXHlCWeqClNBwUhDcusJxXYDjZTyE8v5oTO7WbL8eij2nKhUeU89/6xgjU7N4/Vh3He0BtyhJdQbDyhiXAw=="],
+    "@types/node": ["@types/node@25.3.2", "", { "dependencies": { "undici-types": "~7.18.0" } }, "sha512-RpV6r/ij22zRRdyBPcxDeKAzH43phWVKEjL2iksqo1Vz3CuBUrgmPpPhALKiRfU7OMCmeeO9vECBMsV0hMTG8Q=="],
 
     "@types/pg": ["@types/pg@8.15.6", "", { "dependencies": { "@types/node": "*", "pg-protocol": "*", "pg-types": "^2.2.0" } }, "sha512-NoaMtzhxOrubeL/7UZuNTrejB4MPAJ0RpxZqXQf2qXuVlTPuG6Y8p4u9dKRaue4yjmC7ZhzVO2/Yyyn25znrPQ=="],
 
@@ -351,13 +352,13 @@
 
     "@types/triple-beam": ["@types/triple-beam@1.3.5", "", {}, "sha512-6WaYesThRMCl19iryMYP7/x2OVgCtbIVflDGFpWnb9irXI3UjYE4AzmYuiUKY1AJstGijoY+MgUszMgRxIYTYw=="],
 
-    "@typespec/ts-http-runtime": ["@typespec/ts-http-runtime@0.3.2", "", { "dependencies": { "http-proxy-agent": "^7.0.0", "https-proxy-agent": "^7.0.0", "tslib": "^2.6.2" } }, "sha512-IlqQ/Gv22xUC1r/WQm4StLkYQmaaTsXAhUVsNE0+xiyf0yRFiH5++q78U3bw6bLKDCTmh0uqKB9eG9+Bt75Dkg=="],
+    "@typespec/ts-http-runtime": ["@typespec/ts-http-runtime@0.3.3", "", { "dependencies": { "http-proxy-agent": "^7.0.0", "https-proxy-agent": "^7.0.0", "tslib": "^2.6.2" } }, "sha512-91fp6CAAJSRtH5ja95T1FHSKa8aPW9/Zw6cta81jlZTUw/+Vq8jM/AfF/14h2b71wwR84JUTW/3Y8QPhDAawFA=="],
 
     "@webgpu/types": ["@webgpu/types@0.1.69", "", {}, "sha512-RPmm6kgRbI8e98zSD3RVACvnuktIja5+yLgDAkTmxLr90BEwdTXRQWNLF3ETTTyH/8mKhznZuN5AveXYFEsMGQ=="],
 
     "abort-controller": ["abort-controller@3.0.0", "", { "dependencies": { "event-target-shim": "^5.0.0" } }, "sha512-h8lQ8tacZYnR3vNQTgibj+tODHI5/+l06Au2Pcriv/Gmet0eaj4TwWH41sO9wnHDiQsEj19q0drzdWdeAHtweg=="],
 
-    "acorn": ["acorn@8.15.0", "", { "bin": { "acorn": "bin/acorn" } }, "sha512-NZyJarBfL7nWwIq+FDL6Zp/yHEhePMNnnJ0y3qfieCrmNvYct8uvtiV41UvlSe6apAfk0fY1FbWx+NwfmpvtTg=="],
+    "acorn": ["acorn@8.16.0", "", { "bin": { "acorn": "bin/acorn" } }, "sha512-UVJyE9MttOsBQIDKw1skb9nAwQuR5wuGD3+82K6JgJlm/Y+KI92oNsMNGZCYdDsVtRHSak0pcV5Dno5+4jh9sw=="],
 
     "acorn-import-attributes": ["acorn-import-attributes@1.9.5", "", { "peerDependencies": { "acorn": "^8" } }, "sha512-n02Vykv5uA3eHGM/Z2dQrcD56kL8TyDb2p1+0P83PClMnC/nc+anbQRhIOWnSq4Ke/KvDPrY3C9hDtC/A3eHnQ=="],
 
@@ -441,7 +442,7 @@
 
     "image-q": ["image-q@4.0.0", "", { "dependencies": { "@types/node": "16.9.1" } }, "sha512-PfJGVgIfKQJuq3s0tTDOKtztksibuUEbJQIYT3by6wctQo+Rdlh7ef4evJ5NCdxY4CfMbvFkocEwbl4BF8RlJw=="],
 
-    "import-in-the-middle": ["import-in-the-middle@2.0.5", "", { "dependencies": { "acorn": "^8.15.0", "acorn-import-attributes": "^1.9.5", "cjs-module-lexer": "^2.2.0", "module-details-from-path": "^1.0.4" } }, "sha512-0InH9/4oDCBRzWXhpOqusspLBrVfK1vPvbn9Wxl8DAQ8yyx5fWJRETICSwkiAMaYntjJAMBP1R4B6cQnEUYVEA=="],
+    "import-in-the-middle": ["import-in-the-middle@2.0.6", "", { "dependencies": { "acorn": "^8.15.0", "acorn-import-attributes": "^1.9.5", "cjs-module-lexer": "^2.2.0", "module-details-from-path": "^1.0.4" } }, "sha512-3vZV3jX0XRFW3EJDTwzWoZa+RH1b8eTTx6YOCjglrLyPuepwoBti1k3L2dKwdCUrnVEfc5CuRuGstaC/uQJJaw=="],
 
     "inherits": ["inherits@2.0.4", "", {}, "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ=="],
 
@@ -453,27 +454,27 @@
 
     "jpeg-js": ["jpeg-js@0.4.4", "", {}, "sha512-WZzeDOEtTOBK4Mdsar0IqEU5sMr3vSV2RqkAIzUEV2BHnUfKGyswWFPFwK5EeDo93K3FohSHbLAjj0s1Wzd+dg=="],
 
-    "lefthook": ["lefthook@2.1.1", "", { "optionalDependencies": { "lefthook-darwin-arm64": "2.1.1", "lefthook-darwin-x64": "2.1.1", "lefthook-freebsd-arm64": "2.1.1", "lefthook-freebsd-x64": "2.1.1", "lefthook-linux-arm64": "2.1.1", "lefthook-linux-x64": "2.1.1", "lefthook-openbsd-arm64": "2.1.1", "lefthook-openbsd-x64": "2.1.1", "lefthook-windows-arm64": "2.1.1", "lefthook-windows-x64": "2.1.1" }, "bin": { "lefthook": "bin/index.js" } }, "sha512-Tl9h9c+sG3ShzTHKuR3LAIblnnh+Mgxnm2Ul7yu9cu260Z27LEbO3V6Zw4YZFP59/2rlD42pt/llYsQCkkCFzw=="],
+    "lefthook": ["lefthook@2.1.2", "", { "optionalDependencies": { "lefthook-darwin-arm64": "2.1.2", "lefthook-darwin-x64": "2.1.2", "lefthook-freebsd-arm64": "2.1.2", "lefthook-freebsd-x64": "2.1.2", "lefthook-linux-arm64": "2.1.2", "lefthook-linux-x64": "2.1.2", "lefthook-openbsd-arm64": "2.1.2", "lefthook-openbsd-x64": "2.1.2", "lefthook-windows-arm64": "2.1.2", "lefthook-windows-x64": "2.1.2" }, "bin": { "lefthook": "bin/index.js" } }, "sha512-HdAMl4g47kbWSkrUkCx3Kucq54omFS6piMJtXwXNtmCAfB40UaybTJuYtFW4hNzZ5SvaEimtxTp7P/MNIkEfsA=="],
 
-    "lefthook-darwin-arm64": ["lefthook-darwin-arm64@2.1.1", "", { "os": "darwin", "cpu": "arm64" }, "sha512-O/RS1j03/Fnq5zCzEb2r7UOBsqPeBuf1C5pMkIJcO4TSE6hf3rhLUkcorKc2M5ni/n5zLGtzQUXHV08/fSAT3Q=="],
+    "lefthook-darwin-arm64": ["lefthook-darwin-arm64@2.1.2", "", { "os": "darwin", "cpu": "arm64" }, "sha512-AgHu93YuJtj1l9bcKlCbo4Tg8N8xFl9iD6BjXCGaGMu46LSjFiXbJFlkUdpgrL8fIbwoCjJi5FNp3POpqs4Wdw=="],
 
-    "lefthook-darwin-x64": ["lefthook-darwin-x64@2.1.1", "", { "os": "darwin", "cpu": "x64" }, "sha512-mm/kdKl81ROPoYnj9XYk5JDqj+/6Al8w/SSPDfhItkLJyl4pqS+hWUOP6gDGrnuRk8S0DvJ2+hzhnDsQnZohWQ=="],
+    "lefthook-darwin-x64": ["lefthook-darwin-x64@2.1.2", "", { "os": "darwin", "cpu": "x64" }, "sha512-exooc9Ectz13OLJJOXM9AzaFQbqzf9QCF8JuVvGfbr4RYABYK+BwwtydjlPQrA76/n/h4tsS11MH5bBULnLkYA=="],
 
-    "lefthook-freebsd-arm64": ["lefthook-freebsd-arm64@2.1.1", "", { "os": "freebsd", "cpu": "arm64" }, "sha512-F7JXlKmjxGqGbCWPLND0bVB4DMQezIe48pEwTlUQZbxh450c2gP5Q8FdttMZKOT163kBGGTqJAJSEC6zW+QSxA=="],
+    "lefthook-freebsd-arm64": ["lefthook-freebsd-arm64@2.1.2", "", { "os": "freebsd", "cpu": "arm64" }, "sha512-E1QMlJPEU21n9eewv6ePfh+JmoTSg5R1jaYcKCky10kfbMdohNucI3xV91F2LcerE+p3UejKDqr/1wWO2RMGeQ=="],
 
-    "lefthook-freebsd-x64": ["lefthook-freebsd-x64@2.1.1", "", { "os": "freebsd", "cpu": "x64" }, "sha512-Po8/lJMqNzKSZPuEI46dLuWoBoXtAxCuRpeOh6DAV/M4RhBynaCu8rLMZ9BqF7cVbZEWoplOmYo6HdOuiYpCkQ=="],
+    "lefthook-freebsd-x64": ["lefthook-freebsd-x64@2.1.2", "", { "os": "freebsd", "cpu": "x64" }, "sha512-/5zp+x8055Thj46x9S7hgnneZxvWhHQvPWkkgISCab1Lh6eLrbxvhE1qTb1lU3DqTnNmH9NeXdq1xPHc9uGluA=="],
 
-    "lefthook-linux-arm64": ["lefthook-linux-arm64@2.1.1", "", { "os": "linux", "cpu": "arm64" }, "sha512-mI2ljFgPEqHxI8vrN9nKgnVu63Rz1KisDbPwlvs7BTYNwq3sncdK5ukpGR4zzWdh6saNJ5tCtHEtep5GQI11nw=="],
+    "lefthook-linux-arm64": ["lefthook-linux-arm64@2.1.2", "", { "os": "linux", "cpu": "arm64" }, "sha512-UK5FvDTkwKO7tOznY8iEZzuTsM1jXMZAG5BMRs7olN1k1K6m2unR6oKABP0hCd0wDErK6DZKDJDJfB564Rzqtw=="],
 
-    "lefthook-linux-x64": ["lefthook-linux-x64@2.1.1", "", { "os": "linux", "cpu": "x64" }, "sha512-m3G/FaxC+crxeg9XeaUuHfEoL+i9gbkg2Hp2KD2IcVVIxprqlyqf0Hb8zbLV2NMXuo5RSGokJu44oAoTO3Ou2g=="],
+    "lefthook-linux-x64": ["lefthook-linux-x64@2.1.2", "", { "os": "linux", "cpu": "x64" }, "sha512-4eOtz4PNh8GbJ+nA8YVDfW/eMirQWdZqMP/V/MVtoVBGobf6oXvvuDOySvAPOgNYEFN0Boegytmuji/851Vstg=="],
 
-    "lefthook-openbsd-arm64": ["lefthook-openbsd-arm64@2.1.1", "", { "os": "openbsd", "cpu": "arm64" }, "sha512-gz/8FJPvhjOdOFt1GmFvuvDOe+W+BBRjoeAT1/mTgkN7HCXMXgqNjjvakQKQeGz1I1v08wXG1ZNf5y+T9XBCDQ=="],
+    "lefthook-openbsd-arm64": ["lefthook-openbsd-arm64@2.1.2", "", { "os": "openbsd", "cpu": "arm64" }, "sha512-lJXRJ6iJIBKwomuNBA3CUNSclj2/rKuxGAQoUra214B92VB6jL9zaY5YEs6h/ie9jQrzSnllEeg7xyDIsuVCrQ=="],
 
-    "lefthook-openbsd-x64": ["lefthook-openbsd-x64@2.1.1", "", { "os": "openbsd", "cpu": "x64" }, "sha512-ch3lyMUtbmtWUufaQVn4IoEs/2hjK51XqaCdY1mh5ca//VctR1peknIwQ5feHu+vATCDviWQ7HsdNDewm3HMPg=="],
+    "lefthook-openbsd-x64": ["lefthook-openbsd-x64@2.1.2", "", { "os": "openbsd", "cpu": "x64" }, "sha512-GyOje4W0DIqkmR7/Of5D+mZ0vWqMvtGAVedtJR6d1239xNeMzCS8Q+/a3O1xigceZa5xhlqq0BWlssB/QYPQnA=="],
 
-    "lefthook-windows-arm64": ["lefthook-windows-arm64@2.1.1", "", { "os": "win32", "cpu": "arm64" }, "sha512-mm3PZhKDs9FE/jQDimkfWxtoj9xQ2k8uw2MdhtC825bhvIh+MEi0WFj/MOW+ug0RBg0I55tGYzZ5aVuozAWpTQ=="],
+    "lefthook-windows-arm64": ["lefthook-windows-arm64@2.1.2", "", { "os": "win32", "cpu": "arm64" }, "sha512-MZKMqTULEpX/8N3fKXAR0A9RjsGKkEEY0japLqrHOIpxsJXry1DRz0FvQo2kkY4WW3rtFegV9m6eesOymuDrUg=="],
 
-    "lefthook-windows-x64": ["lefthook-windows-x64@2.1.1", "", { "os": "win32", "cpu": "x64" }, "sha512-1L2oGIzmhfOTxfwbe5mpSQ+m3ilpvGNymwIhn4UHq6hwHsUL6HEhODqx02GfBn6OXpVIr56bvdBAusjL/SVYGQ=="],
+    "lefthook-windows-x64": ["lefthook-windows-x64@2.1.2", "", { "os": "win32", "cpu": "x64" }, "sha512-NZUgObuaSxc0EXAwC/CzkMf7TuQc++GGIk6TLPdaUpoSsNSJSZEwBVz5DtFB1cG+eMkfO/wOKplls+yjimTTtQ=="],
 
     "lodash.camelcase": ["lodash.camelcase@4.3.0", "", {}, "sha512-TwuEnCnxbc3rAvhf/LbG7tJUDzhqXyFnv3dtzLOPgCG/hODL7WFnsbwktkD7yUV0RrreP/l1PALq/YSg6VvjlA=="],
 
@@ -491,7 +492,7 @@
 
     "omggif": ["omggif@1.0.10", "", {}, "sha512-LMJTtvgc/nugXj0Vcrrs68Mn2D1r0zf630VNtqtpI1FEO7e+O9FP4gqs9AcnBaSEeoHIPm28u6qgPR0oyEpGSw=="],
 
-    "oxlint": ["oxlint@1.49.0", "", { "optionalDependencies": { "@oxlint/binding-android-arm-eabi": "1.49.0", "@oxlint/binding-android-arm64": "1.49.0", "@oxlint/binding-darwin-arm64": "1.49.0", "@oxlint/binding-darwin-x64": "1.49.0", "@oxlint/binding-freebsd-x64": "1.49.0", "@oxlint/binding-linux-arm-gnueabihf": "1.49.0", "@oxlint/binding-linux-arm-musleabihf": "1.49.0", "@oxlint/binding-linux-arm64-gnu": "1.49.0", "@oxlint/binding-linux-arm64-musl": "1.49.0", "@oxlint/binding-linux-ppc64-gnu": "1.49.0", "@oxlint/binding-linux-riscv64-gnu": "1.49.0", "@oxlint/binding-linux-riscv64-musl": "1.49.0", "@oxlint/binding-linux-s390x-gnu": "1.49.0", "@oxlint/binding-linux-x64-gnu": "1.49.0", "@oxlint/binding-linux-x64-musl": "1.49.0", "@oxlint/binding-openharmony-arm64": "1.49.0", "@oxlint/binding-win32-arm64-msvc": "1.49.0", "@oxlint/binding-win32-ia32-msvc": "1.49.0", "@oxlint/binding-win32-x64-msvc": "1.49.0" }, "peerDependencies": { "oxlint-tsgolint": ">=0.14.1" }, "optionalPeers": ["oxlint-tsgolint"], "bin": { "oxlint": "bin/oxlint" } }, "sha512-YZffp0gM+63CJoRhHjtjRnwKtAgUnXM6j63YQ++aigji2NVvLGsUlrXo9gJUXZOdcbfShLYtA6RuTu8GZ4lzOQ=="],
+    "oxlint": ["oxlint@1.51.0", "", { "optionalDependencies": { "@oxlint/binding-android-arm-eabi": "1.51.0", "@oxlint/binding-android-arm64": "1.51.0", "@oxlint/binding-darwin-arm64": "1.51.0", "@oxlint/binding-darwin-x64": "1.51.0", "@oxlint/binding-freebsd-x64": "1.51.0", "@oxlint/binding-linux-arm-gnueabihf": "1.51.0", "@oxlint/binding-linux-arm-musleabihf": "1.51.0", "@oxlint/binding-linux-arm64-gnu": "1.51.0", "@oxlint/binding-linux-arm64-musl": "1.51.0", "@oxlint/binding-linux-ppc64-gnu": "1.51.0", "@oxlint/binding-linux-riscv64-gnu": "1.51.0", "@oxlint/binding-linux-riscv64-musl": "1.51.0", "@oxlint/binding-linux-s390x-gnu": "1.51.0", "@oxlint/binding-linux-x64-gnu": "1.51.0", "@oxlint/binding-linux-x64-musl": "1.51.0", "@oxlint/binding-openharmony-arm64": "1.51.0", "@oxlint/binding-win32-arm64-msvc": "1.51.0", "@oxlint/binding-win32-ia32-msvc": "1.51.0", "@oxlint/binding-win32-x64-msvc": "1.51.0" }, "peerDependencies": { "oxlint-tsgolint": ">=0.15.0" }, "optionalPeers": ["oxlint-tsgolint"], "bin": { "oxlint": "bin/oxlint" } }, "sha512-g6DNPaV9/WI9MoX2XllafxQuxwY1TV++j7hP8fTJByVBuCoVtm3dy9f/2vtH/HU40JztcgWF4G7ua+gkainklQ=="],
 
     "pako": ["pako@1.0.11", "", {}, "sha512-4hLB8Py4zZce5s4yd9XzopqwVv/yGNhV1Bl8NTmCq1763HeK2+EwVTv+leGeL13Dnh2wfbqowVPXCIO0z4taYw=="],
 
@@ -507,7 +508,7 @@
 
     "pg-int8": ["pg-int8@1.0.1", "", {}, "sha512-WCtabS6t3c8SkpDBUlb1kjOs7l66xsGdKpIPZsg4wR+B3+u9UAum2odSsF9tnvxg80h4ZxLWMy4pRjOsFIqQpw=="],
 
-    "pg-protocol": ["pg-protocol@1.11.0", "", {}, "sha512-pfsxk2M9M3BuGgDOfuy37VNRRX3jmKgMjcvAcWqNDpZSf4cUmv8HSOl5ViRQFsfARFn0KuUQTgLxVMbNq5NW3g=="],
+    "pg-protocol": ["pg-protocol@1.12.0", "", {}, "sha512-uOANXNRACNdElMXJ0tPz6RBM0XQ61nONGAwlt8da5zs/iUOOCLBQOHSXnrC6fMsvtjxbOJrZZl5IScGv+7mpbg=="],
 
     "pg-types": ["pg-types@2.2.0", "", { "dependencies": { "pg-int8": "1.0.1", "postgres-array": "~2.0.0", "postgres-bytea": "~1.0.0", "postgres-date": "~1.0.4", "postgres-interval": "^1.1.0" } }, "sha512-qTAAlrEsl8s4OiEQY69wDvcMIdQN6wdz5ojQiOy6YRMuynxenON0O5oCpJI6lshc6scgAY8qvJ2On/p+CXY0GA=="],
 
@@ -515,7 +516,7 @@
 
     "pixelmatch": ["pixelmatch@5.3.0", "", { "dependencies": { "pngjs": "^6.0.0" }, "bin": { "pixelmatch": "bin/pixelmatch" } }, "sha512-o8mkY4E/+LNUf6LzX96ht6k6CEDi65k9G2rjMtBe9Oo+VPKSvl+0GKHuH/AlG+GA5LPG/i5hrekkxUc3s2HU+Q=="],
 
-    "planck": ["planck@1.4.2", "", { "peerDependencies": { "stage-js": "^1.0.0-alpha.12" } }, "sha512-mNbhnV3g8X2rwGxzcesjmN8BDA6qfXgQxXVMkWau9MCRlQY0RLNEkyHlVp6yFy/X6qrzAXyNONCnZ1cGDLrNew=="],
+    "planck": ["planck@1.4.3", "", { "peerDependencies": { "stage-js": "^1.0.0-alpha.12" } }, "sha512-B+lHKhRSeg7vZOfEyEzyQVu7nx8JHcX3QgnAcHXrPW0j04XYKX5eXSiUrxH2Z5QR8OoqvjD6zKIaPMdMYAd0uA=="],
 
     "pngjs": ["pngjs@7.0.0", "", {}, "sha512-LKWqWJRhstyYo9pGvgor/ivk2w94eSjE3RGVuzLGlr3NmD8bf7RcYGze1mNdEHRP6TRP6rMuDHk5t44hnTRyow=="],
 
@@ -563,7 +564,7 @@
 
     "sisteransi": ["sisteransi@1.0.5", "", {}, "sha512-bLGGlR1QxBcynn2d5YmDX4MGjlZvy2MRBDRNHLJ8VI6l6+9FUiyTFNJ0IveOSP0bcXgVDPRcfGqA0pjaqUpfVg=="],
 
-    "stage-js": ["stage-js@1.0.0-alpha.18", "", {}, "sha512-Mh+pbkfxA6NXlDrcutP8vp1Zg04pDRcC8D39UXKZzEcQeBPOZ4SRUSkIsF26aoODUZ4CSQRY7shXc1Avb0wZKA=="],
+    "stage-js": ["stage-js@1.0.1", "", {}, "sha512-cz14aPp/wY0s3bkb/B93BPP5ZAEhgBbRmAT3CCDqert8eCAqIpQ0RB2zpK8Ksxf+Pisl5oTzvPHtL4CVzzeHcw=="],
 
     "string-width": ["string-width@4.2.3", "", { "dependencies": { "emoji-regex": "^8.0.0", "is-fullwidth-code-point": "^3.0.0", "strip-ansi": "^6.0.1" } }, "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g=="],
 
@@ -587,7 +588,7 @@
 
     "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
 
-    "undici-types": ["undici-types@7.16.0", "", {}, "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw=="],
+    "undici-types": ["undici-types@7.18.2", "", {}, "sha512-AsuCzffGHJybSaRrmr5eHr81mwJU3kjw6M+uprWvCXiNeN9SOGwQ3Jn8jb8m3Z6izVgknn1R0FTCEAP2QrLY/w=="],
 
     "utif2": ["utif2@4.1.0", "", { "dependencies": { "pako": "^1.0.11" } }, "sha512-+oknB9FHrJ7oW7A2WZYajOcv4FcDR4CfoGB0dPNfxbi4GO05RRnFmt5oa23+9w32EanrYcSJWspUiJkLMs+37w=="],
 
@@ -769,8 +770,6 @@
 
     "@opentelemetry/winston-transport/@opentelemetry/api-logs": ["@opentelemetry/api-logs@0.208.0", "", { "dependencies": { "@opentelemetry/api": "^1.3.0" } }, "sha512-CjruKY9V6NMssL/T1kAFgzosF1v9o6oeN+aX5JB/C/xPNtmgIJqcXHG7fA82Ou1zCpWGl4lROQUKwUNE1pMCyg=="],
 
-    "@types/ci-info/ci-info": ["ci-info@4.3.1", "", {}, "sha512-Wdy2Igu8OcBpI2pZePZ5oWjPC38tmDVx5WKUXKwlLYkA0ozo85sLsLvkBbBn/sZaSCMFOGZJ14fvW9t5/d7kdA=="],
-
     "image-q/@types/node": ["@types/node@16.9.1", "", {}, "sha512-QpLcX9ZSsq3YYUUnD3nFDY8H7wctAhQj/TFKL8Ya8v5fMm3CFXxo8zStsLAl780ltoYoo1WvKUVGBQK+1ifr7g=="],
 
     "pixelmatch/pngjs": ["pngjs@6.0.0", "", {}, "sha512-TRzzuFRRmEoSW/p1KVAmiOgPco2Irlah+bGFCeNfJXxxYGwSw7YwAOAcd7X28K/m5bjBWKsC29KyoMfHbypayg=="],
diff --git a/docs/claude-agent-sdk.md b/docs/claude-agent-sdk.md
new file mode 100644
index 0000000000..3cfd422428
--- /dev/null
+++ b/docs/claude-agent-sdk.md
@@ -0,0 +1,2558 @@
+# Agent SDK reference - TypeScript
+
+Complete API reference for the TypeScript Agent SDK, including all functions, types, and interfaces.
+
+---
+
+<script src="/components/typescript-sdk-type-links.js" defer />
+
+<Note>
+**Try the new V2 interface (preview):** A simplified interface with `send()` and `stream()` patterns is now available, making multi-turn conversations easier. [Learn more about the TypeScript V2 preview](/docs/en/agent-sdk/typescript-v2-preview)
+</Note>
+
+## Installation
+
+```bash
+npm install @anthropic-ai/claude-agent-sdk
+```
+
+## Functions
+
+### `query()`
+
+The primary function for interacting with Claude Code. Creates an async generator that streams messages as they arrive.
+
+```typescript
+function query({
+  prompt,
+  options
+}: {
+  prompt: string | AsyncIterable<SDKUserMessage>;
+  options?: Options;
+}): Query
+```
+
+#### Parameters
+
+| Parameter | Type                                                             | Description                                                       |
+| :-------- | :--------------------------------------------------------------- | :---------------------------------------------------------------- |
+| `prompt`  | `string \| AsyncIterable<`[`SDKUserMessage`](#sdkusermessage)`>` | The input prompt as a string or async iterable for streaming mode |
+| `options` | [`Options`](#options)                                            | Optional configuration object (see Options type below)            |
+
+#### Returns
+
+Returns a [`Query`](#query-object) object that extends `AsyncGenerator<`[`SDKMessage`](#sdkmessage)`, void>` with additional methods.
+
+### `tool()`
+
+Creates a type-safe MCP tool definition for use with SDK MCP servers.
+
+```typescript
+function tool<Schema extends AnyZodRawShape>(
+  name: string,
+  description: string,
+  inputSchema: Schema,
+  handler: (args: InferShape<Schema>, extra: unknown) => Promise<CallToolResult>,
+  extras?: { annotations?: ToolAnnotations }
+): SdkMcpToolDefinition<Schema>
+```
+
+#### Parameters
+
+| Parameter     | Type                                                              | Description                                                                                                |
+| :------------ | :---------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------- |
+| `name`        | `string`                                                          | The name of the tool                                                                                       |
+| `description` | `string`                                                          | A description of what the tool does                                                                        |
+| `inputSchema` | `Schema extends AnyZodRawShape`                                   | Zod schema defining the tool's input parameters (supports both Zod 3 and Zod 4)                            |
+| `handler`     | `(args, extra) => Promise<`[`CallToolResult`](#calltoolresult)`>` | Async function that executes the tool logic                                                                |
+| `extras`      | `{ annotations?: ToolAnnotations }`                               | Optional extra configuration including MCP tool annotations (e.g., `readOnly`, `destructive`, `openWorld`) |
+
+### `createSdkMcpServer()`
+
+Creates an MCP server instance that runs in the same process as your application.
+
+```typescript
+function createSdkMcpServer(options: {
+  name: string;
+  version?: string;
+  tools?: Array<SdkMcpToolDefinition<any>>;
+}): McpSdkServerConfigWithInstance
+```
+
+#### Parameters
+
+| Parameter         | Type                          | Description                                              |
+| :---------------- | :---------------------------- | :------------------------------------------------------- |
+| `options.name`    | `string`                      | The name of the MCP server                               |
+| `options.version` | `string`                      | Optional version string                                  |
+| `options.tools`   | `Array<SdkMcpToolDefinition>` | Array of tool definitions created with [`tool()`](#tool) |
+
+### `listSessions()`
+
+Discovers and lists past sessions with light metadata. Filter by project directory or list sessions across all projects.
+
+```typescript
+function listSessions(options?: ListSessionsOptions): Promise<SDKSessionInfo[]>
+```
+
+#### Parameters
+
+| Parameter       | Type     | Default     | Description                                                                                                                                   |
+| :-------------- | :------- | :---------- | :-------------------------------------------------------------------------------------------------------------------------------------------- |
+| `options.dir`   | `string` | `undefined` | Directory to list sessions for. Returns sessions for this project (and its git worktrees). When omitted, returns sessions across all projects |
+| `options.limit` | `number` | `undefined` | Maximum number of sessions to return                                                                                                          |
+
+#### Return type: `SDKSessionInfo`
+
+| Property       | Type                  | Description                                                          |
+| :------------- | :-------------------- | :------------------------------------------------------------------- |
+| `sessionId`    | `string`              | Unique session identifier (UUID)                                     |
+| `summary`      | `string`              | Display title: custom title, auto-generated summary, or first prompt |
+| `lastModified` | `number`              | Last modified time in milliseconds since epoch                       |
+| `fileSize`     | `number`              | Session file size in bytes                                           |
+| `customTitle`  | `string \| undefined` | User-set session title (via `/rename`)                               |
+| `firstPrompt`  | `string \| undefined` | First meaningful user prompt in the session                          |
+| `gitBranch`    | `string \| undefined` | Git branch at the end of the session                                 |
+| `cwd`          | `string \| undefined` | Working directory for the session                                    |
+
+#### Example
+
+```typescript
+import { listSessions } from "@anthropic-ai/claude-agent-sdk";
+
+// List sessions for a specific project
+const sessions = await listSessions({ dir: "/path/to/project" });
+
+for (const session of sessions) {
+  console.log(`${session.summary} (${new Date(session.lastModified).toLocaleDateString()})`);
+}
+
+// List all sessions across all projects, limited to 10
+const recent = await listSessions({ limit: 10 });
+```
+
+## Types
+
+### `Options`
+
+Configuration object for the `query()` function.
+
+| Property                          | Type                                                                                              | Default                                     | Description                                                                                                                                                                                                                                               |
+| :-------------------------------- | :------------------------------------------------------------------------------------------------ | :------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `abortController`                 | `AbortController`                                                                                 | `new AbortController()`                     | Controller for cancelling operations                                                                                                                                                                                                                      |
+| `additionalDirectories`           | `string[]`                                                                                        | `[]`                                        | Additional directories Claude can access                                                                                                                                                                                                                  |
+| `agent`                           | `string`                                                                                          | `undefined`                                 | Agent name for the main thread. The agent must be defined in the `agents` option or in settings                                                                                                                                                           |
+| `agents`                          | `Record<string, [`AgentDefinition`](#agentdefinition)>`                                           | `undefined`                                 | Programmatically define subagents                                                                                                                                                                                                                         |
+| `allowDangerouslySkipPermissions` | `boolean`                                                                                         | `false`                                     | Enable bypassing permissions. Required when using `permissionMode: 'bypassPermissions'`                                                                                                                                                                   |
+| `allowedTools`                    | `string[]`                                                                                        | All tools                                   | List of allowed tool names                                                                                                                                                                                                                                |
+| `betas`                           | [`SdkBeta`](#sdkbeta)`[]`                                                                         | `[]`                                        | Enable beta features (e.g., `['context-1m-2025-08-07']`)                                                                                                                                                                                                  |
+| `canUseTool`                      | [`CanUseTool`](#canusetool)                                                                       | `undefined`                                 | Custom permission function for tool usage                                                                                                                                                                                                                 |
+| `continue`                        | `boolean`                                                                                         | `false`                                     | Continue the most recent conversation                                                                                                                                                                                                                     |
+| `cwd`                             | `string`                                                                                          | `process.cwd()`                             | Current working directory                                                                                                                                                                                                                                 |
+| `debug`                           | `boolean`                                                                                         | `false`                                     | Enable debug mode for the Claude Code process                                                                                                                                                                                                             |
+| `debugFile`                       | `string`                                                                                          | `undefined`                                 | Write debug logs to a specific file path. Implicitly enables debug mode                                                                                                                                                                                   |
+| `disallowedTools`                 | `string[]`                                                                                        | `[]`                                        | List of disallowed tool names                                                                                                                                                                                                                             |
+| `effort`                          | `'low' \| 'medium' \| 'high' \| 'max'`                                                            | `'high'`                                    | Controls how much effort Claude puts into its response. Works with adaptive thinking to guide thinking depth                                                                                                                                              |
+| `enableFileCheckpointing`         | `boolean`                                                                                         | `false`                                     | Enable file change tracking for rewinding. See [File checkpointing](/docs/en/agent-sdk/file-checkpointing)                                                                                                                                                |
+| `env`                             | `Record<string, string \| undefined>`                                                             | `process.env`                               | Environment variables. Set `CLAUDE_AGENT_SDK_CLIENT_APP` to identify your app in the User-Agent header                                                                                                                                                    |
+| `executable`                      | `'bun' \| 'deno' \| 'node'`                                                                       | Auto-detected                               | JavaScript runtime to use                                                                                                                                                                                                                                 |
+| `executableArgs`                  | `string[]`                                                                                        | `[]`                                        | Arguments to pass to the executable                                                                                                                                                                                                                       |
+| `extraArgs`                       | `Record<string, string \| null>`                                                                  | `{}`                                        | Additional arguments                                                                                                                                                                                                                                      |
+| `fallbackModel`                   | `string`                                                                                          | `undefined`                                 | Model to use if primary fails                                                                                                                                                                                                                             |
+| `forkSession`                     | `boolean`                                                                                         | `false`                                     | When resuming with `resume`, fork to a new session ID instead of continuing the original session                                                                                                                                                          |
+| `hooks`                           | `Partial<Record<`[`HookEvent`](#hookevent)`, `[`HookCallbackMatcher`](#hookcallbackmatcher)`[]>>` | `{}`                                        | Hook callbacks for events                                                                                                                                                                                                                                 |
+| `includePartialMessages`          | `boolean`                                                                                         | `false`                                     | Include partial message events                                                                                                                                                                                                                            |
+| `maxBudgetUsd`                    | `number`                                                                                          | `undefined`                                 | Maximum budget in USD for the query                                                                                                                                                                                                                       |
+| `maxThinkingTokens`               | `number`                                                                                          | `undefined`                                 | _Deprecated:_ Use `thinking` instead. Maximum tokens for thinking process                                                                                                                                                                                 |
+| `maxTurns`                        | `number`                                                                                          | `undefined`                                 | Maximum conversation turns                                                                                                                                                                                                                                |
+| `mcpServers`                      | `Record<string, [`McpServerConfig`](#mcpserverconfig)>`                                           | `{}`                                        | MCP server configurations                                                                                                                                                                                                                                 |
+| `model`                           | `string`                                                                                          | Default from CLI                            | Claude model to use                                                                                                                                                                                                                                       |
+| `outputFormat`                    | `{ type: 'json_schema', schema: JSONSchema }`                                                     | `undefined`                                 | Define output format for agent results. See [Structured outputs](/docs/en/agent-sdk/structured-outputs) for details                                                                                                                                       |
+| `pathToClaudeCodeExecutable`      | `string`                                                                                          | Uses built-in executable                    | Path to Claude Code executable                                                                                                                                                                                                                            |
+| `permissionMode`                  | [`PermissionMode`](#permissionmode)                                                               | `'default'`                                 | Permission mode for the session                                                                                                                                                                                                                           |
+| `permissionPromptToolName`        | `string`                                                                                          | `undefined`                                 | MCP tool name for permission prompts                                                                                                                                                                                                                      |
+| `persistSession`                  | `boolean`                                                                                         | `true`                                      | When `false`, disables session persistence to disk. Sessions cannot be resumed later                                                                                                                                                                      |
+| `plugins`                         | [`SdkPluginConfig`](#sdkpluginconfig)`[]`                                                         | `[]`                                        | Load custom plugins from local paths. See [Plugins](/docs/en/agent-sdk/plugins) for details                                                                                                                                                               |
+| `promptSuggestions`               | `boolean`                                                                                         | `false`                                     | Enable prompt suggestions. Emits a `prompt_suggestion` message after each turn with a predicted next user prompt                                                                                                                                          |
+| `resume`                          | `string`                                                                                          | `undefined`                                 | Session ID to resume                                                                                                                                                                                                                                      |
+| `resumeSessionAt`                 | `string`                                                                                          | `undefined`                                 | Resume session at a specific message UUID                                                                                                                                                                                                                 |
+| `sandbox`                         | [`SandboxSettings`](#sandboxsettings)                                                             | `undefined`                                 | Configure sandbox behavior programmatically. See [Sandbox settings](#sandboxsettings) for details                                                                                                                                                         |
+| `sessionId`                       | `string`                                                                                          | Auto-generated                              | Use a specific UUID for the session instead of auto-generating one                                                                                                                                                                                        |
+| `settingSources`                  | [`SettingSource`](#setting-source)`[]`                                                            | `[]` (no settings)                          | Control which filesystem settings to load. When omitted, no settings are loaded. **Note:** Must include `'project'` to load CLAUDE.md files                                                                                                               |
+| `spawnClaudeCodeProcess`          | `(options: SpawnOptions) => SpawnedProcess`                                                       | `undefined`                                 | Custom function to spawn the Claude Code process. Use to run Claude Code in VMs, containers, or remote environments                                                                                                                                       |
+| `stderr`                          | `(data: string) => void`                                                                          | `undefined`                                 | Callback for stderr output                                                                                                                                                                                                                                |
+| `strictMcpConfig`                 | `boolean`                                                                                         | `false`                                     | Enforce strict MCP validation                                                                                                                                                                                                                             |
+| `systemPrompt`                    | `string \| { type: 'preset'; preset: 'claude_code'; append?: string }`                            | `undefined` (minimal prompt)                | System prompt configuration. Pass a string for custom prompt, or `{ type: 'preset', preset: 'claude_code' }` to use Claude Code's system prompt. When using the preset object form, add `append` to extend the system prompt with additional instructions |
+| `thinking`                        | [`ThinkingConfig`](#thinkingconfig)                                                               | `{ type: 'adaptive' }` for supported models | Controls Claude's thinking/reasoning behavior. See [`ThinkingConfig`](#thinkingconfig) for options                                                                                                                                                        |
+| `tools`                           | `string[] \| { type: 'preset'; preset: 'claude_code' }`                                           | `undefined`                                 | Tool configuration. Pass an array of tool names or use the preset to get Claude Code's default tools                                                                                                                                                      |
+
+### `Query` object
+
+Interface returned by the `query()` function.
+
+```typescript
+interface Query extends AsyncGenerator<SDKMessage, void> {
+  interrupt(): Promise<void>;
+  rewindFiles(
+    userMessageId: string,
+    options?: { dryRun?: boolean }
+  ): Promise<RewindFilesResult>;
+  setPermissionMode(mode: PermissionMode): Promise<void>;
+  setModel(model?: string): Promise<void>;
+  setMaxThinkingTokens(maxThinkingTokens: number | null): Promise<void>;
+  initializationResult(): Promise<SDKControlInitializeResponse>;
+  supportedCommands(): Promise<SlashCommand[]>;
+  supportedModels(): Promise<ModelInfo[]>;
+  mcpServerStatus(): Promise<McpServerStatus[]>;
+  accountInfo(): Promise<AccountInfo>;
+  reconnectMcpServer(serverName: string): Promise<void>;
+  toggleMcpServer(serverName: string, enabled: boolean): Promise<void>;
+  setMcpServers(servers: Record<string, McpServerConfig>): Promise<McpSetServersResult>;
+  streamInput(stream: AsyncIterable<SDKUserMessage>): Promise<void>;
+  stopTask(taskId: string): Promise<void>;
+  close(): void;
+}
+```
+
+#### Methods
+
+| Method                                 | Description                                                                                                                                                                                                        |
+| :------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `interrupt()`                          | Interrupts the query (only available in streaming input mode)                                                                                                                                                      |
+| `rewindFiles(userMessageId, options?)` | Restores files to their state at the specified user message. Pass `{ dryRun: true }` to preview changes. Requires `enableFileCheckpointing: true`. See [File checkpointing](/docs/en/agent-sdk/file-checkpointing) |
+| `setPermissionMode()`                  | Changes the permission mode (only available in streaming input mode)                                                                                                                                               |
+| `setModel()`                           | Changes the model (only available in streaming input mode)                                                                                                                                                         |
+| `setMaxThinkingTokens()`               | _Deprecated:_ Use the `thinking` option instead. Changes the maximum thinking tokens                                                                                                                               |
+| `initializationResult()`               | Returns the full initialization result including supported commands, models, account info, and output style configuration                                                                                          |
+| `supportedCommands()`                  | Returns available slash commands                                                                                                                                                                                   |
+| `supportedModels()`                    | Returns available models with display info                                                                                                                                                                         |
+| `mcpServerStatus()`                    | Returns status of connected MCP servers                                                                                                                                                                            |
+| `accountInfo()`                        | Returns account information                                                                                                                                                                                        |
+| `reconnectMcpServer(serverName)`       | Reconnect an MCP server by name                                                                                                                                                                                    |
+| `toggleMcpServer(serverName, enabled)` | Enable or disable an MCP server by name                                                                                                                                                                            |
+| `setMcpServers(servers)`               | Dynamically replace the set of MCP servers for this session. Returns info about which servers were added, removed, and any errors                                                                                  |
+| `streamInput(stream)`                  | Stream input messages to the query for multi-turn conversations                                                                                                                                                    |
+| `stopTask(taskId)`                     | Stop a running background task by ID                                                                                                                                                                               |
+| `close()`                              | Close the query and terminate the underlying process. Forcefully ends the query and cleans up all resources                                                                                                        |
+
+### `SDKControlInitializeResponse`
+
+Return type of `initializationResult()`. Contains session initialization data.
+
+```typescript
+type SDKControlInitializeResponse = {
+  commands: SlashCommand[];
+  output_style: string;
+  available_output_styles: string[];
+  models: ModelInfo[];
+  account: AccountInfo;
+}
+```
+
+### `AgentDefinition`
+
+Configuration for a subagent defined programmatically.
+
+```typescript
+type AgentDefinition = {
+  description: string;
+  tools?: string[];
+  disallowedTools?: string[];
+  prompt: string;
+  model?: "sonnet" | "opus" | "haiku" | "inherit";
+  mcpServers?: AgentMcpServerSpec[];
+  skills?: string[];
+  maxTurns?: number;
+  criticalSystemReminder_EXPERIMENTAL?: string;
+}
+```
+
+| Field                                 | Required | Description                                                                   |
+| :------------------------------------ | :------- | :---------------------------------------------------------------------------- |
+| `description`                         | Yes      | Natural language description of when to use this agent                        |
+| `tools`                               | No       | Array of allowed tool names. If omitted, inherits all tools from parent       |
+| `disallowedTools`                     | No       | Array of tool names to explicitly disallow for this agent                     |
+| `prompt`                              | Yes      | The agent's system prompt                                                     |
+| `model`                               | No       | Model override for this agent. If omitted or `'inherit'`, uses the main model |
+| `mcpServers`                          | No       | MCP server specifications for this agent                                      |
+| `skills`                              | No       | Array of skill names to preload into the agent context                        |
+| `maxTurns`                            | No       | Maximum number of agentic turns (API round-trips) before stopping             |
+| `criticalSystemReminder_EXPERIMENTAL` | No       | Experimental: Critical reminder added to the system prompt                    |
+
+### `AgentMcpServerSpec`
+
+Specifies MCP servers available to a subagent. Can be a server name (string referencing a server from the parent's `mcpServers` config) or an inline server configuration record mapping server names to configs.
+
+```typescript
+type AgentMcpServerSpec = string | Record<string, McpServerConfigForProcessTransport>;
+```
+
+Where `McpServerConfigForProcessTransport` is `McpStdioServerConfig | McpSSEServerConfig | McpHttpServerConfig | McpSdkServerConfig`.
+
+### `SettingSource`
+
+Controls which filesystem-based configuration sources the SDK loads settings from.
+
+```typescript
+type SettingSource = "user" | "project" | "local";
+```
+
+| Value       | Description                                  | Location                      |
+| :---------- | :------------------------------------------- | :---------------------------- |
+| `'user'`    | Global user settings                         | `~/.claude/settings.json`     |
+| `'project'` | Shared project settings (version controlled) | `.claude/settings.json`       |
+| `'local'`   | Local project settings (gitignored)          | `.claude/settings.local.json` |
+
+#### Default behavior
+
+When `settingSources` is **omitted** or **undefined**, the SDK does **not** load any filesystem settings. This provides isolation for SDK applications.
+
+#### Why use settingSources
+
+**Load all filesystem settings (legacy behavior):**
+```typescript
+// Load all settings like SDK v0.0.x did
+const result = query({
+  prompt: "Analyze this code",
+  options: {
+    settingSources: ["user", "project", "local"] // Load all settings
+  }
+});
+```
+
+**Load only specific setting sources:**
+```typescript
+// Load only project settings, ignore user and local
+const result = query({
+  prompt: "Run CI checks",
+  options: {
+    settingSources: ["project"] // Only .claude/settings.json
+  }
+});
+```
+
+**Testing and CI environments:**
+```typescript
+// Ensure consistent behavior in CI by excluding local settings
+const result = query({
+  prompt: "Run tests",
+  options: {
+    settingSources: ["project"], // Only team-shared settings
+    permissionMode: "bypassPermissions"
+  }
+});
+```
+
+**SDK-only applications:**
+```typescript
+// Define everything programmatically (default behavior)
+// No filesystem dependencies - settingSources defaults to []
+const result = query({
+  prompt: "Review this PR",
+  options: {
+    // settingSources: [] is the default, no need to specify
+    agents: { /* ... */ },
+    mcpServers: { /* ... */ },
+    allowedTools: ["Read", "Grep", "Glob"]
+  }
+});
+```
+
+**Loading CLAUDE.md project instructions:**
+```typescript
+// Load project settings to include CLAUDE.md files
+const result = query({
+  prompt: "Add a new feature following project conventions",
+  options: {
+    systemPrompt: {
+      type: "preset",
+      preset: "claude_code" // Required to use CLAUDE.md
+    },
+    settingSources: ["project"], // Loads CLAUDE.md from project directory
+    allowedTools: ["Read", "Write", "Edit"]
+  }
+});
+```
+
+#### Settings precedence
+
+When multiple sources are loaded, settings are merged with this precedence (highest to lowest):
+1. Local settings (`.claude/settings.local.json`)
+2. Project settings (`.claude/settings.json`)
+3. User settings (`~/.claude/settings.json`)
+
+Programmatic options (like `agents`, `allowedTools`) always override filesystem settings.
+
+### `PermissionMode`
+
+```typescript
+type PermissionMode =
+  | "default" // Standard permission behavior
+  | "acceptEdits" // Auto-accept file edits
+  | "bypassPermissions" // Bypass all permission checks
+  | "plan" // Planning mode - no execution
+  | "dontAsk" // Don't prompt for permissions, deny if not pre-approved
+```
+
+### `CanUseTool`
+
+Custom permission function type for controlling tool usage.
+
+```typescript
+type CanUseTool = (
+  toolName: string,
+  input: Record<string, unknown>,
+  options: {
+    signal: AbortSignal;
+    suggestions?: PermissionUpdate[];
+    blockedPath?: string;
+    decisionReason?: string;
+    toolUseID: string;
+    agentID?: string;
+  }
+) => Promise<PermissionResult>;
+```
+
+| Option           | Type                                        | Description                                                                  |
+| :--------------- | :------------------------------------------ | :--------------------------------------------------------------------------- |
+| `signal`         | `AbortSignal`                               | Signaled if the operation should be aborted                                  |
+| `suggestions`    | [`PermissionUpdate`](#permissionupdate)`[]` | Suggested permission updates so the user is not prompted again for this tool |
+| `blockedPath`    | `string`                                    | The file path that triggered the permission request, if applicable           |
+| `decisionReason` | `string`                                    | Explains why this permission request was triggered                           |
+| `toolUseID`      | `string`                                    | Unique identifier for this specific tool call within the assistant message   |
+| `agentID`        | `string`                                    | If running within a sub-agent, the sub-agent's ID                            |
+
+### `PermissionResult`
+
+Result of a permission check.
+
+```typescript
+type PermissionResult =
+  | {
+      behavior: "allow";
+      updatedInput?: Record<string, unknown>;
+      updatedPermissions?: PermissionUpdate[];
+      toolUseID?: string;
+    }
+  | {
+      behavior: "deny";
+      message: string;
+      interrupt?: boolean;
+      toolUseID?: string;
+    }
+```
+
+### `McpServerConfig`
+
+Configuration for MCP servers.
+
+```typescript
+type McpServerConfig =
+  | McpStdioServerConfig
+  | McpSSEServerConfig
+  | McpHttpServerConfig
+  | McpSdkServerConfigWithInstance;
+```
+
+#### `McpStdioServerConfig`
+
+```typescript
+type McpStdioServerConfig = {
+  type?: "stdio";
+  command: string;
+  args?: string[];
+  env?: Record<string, string>;
+}
+```
+
+#### `McpSSEServerConfig`
+
+```typescript
+type McpSSEServerConfig = {
+  type: "sse";
+  url: string;
+  headers?: Record<string, string>;
+}
+```
+
+#### `McpHttpServerConfig`
+
+```typescript
+type McpHttpServerConfig = {
+  type: "http";
+  url: string;
+  headers?: Record<string, string>;
+}
+```
+
+#### `McpSdkServerConfigWithInstance`
+
+```typescript
+type McpSdkServerConfigWithInstance = {
+  type: "sdk";
+  name: string;
+  instance: McpServer;
+}
+```
+
+#### `McpClaudeAIProxyServerConfig`
+
+```typescript
+type McpClaudeAIProxyServerConfig = {
+  type: "claudeai-proxy";
+  url: string;
+  id: string;
+}
+```
+
+### `SdkPluginConfig`
+
+Configuration for loading plugins in the SDK.
+
+```typescript
+type SdkPluginConfig = {
+  type: "local";
+  path: string;
+}
+```
+
+| Field  | Type      | Description                                                |
+| :----- | :-------- | :--------------------------------------------------------- |
+| `type` | `'local'` | Must be `'local'` (only local plugins currently supported) |
+| `path` | `string`  | Absolute or relative path to the plugin directory          |
+
+**Example:**
+```typescript
+plugins: [
+  { type: "local", path: "./my-plugin" },
+  { type: "local", path: "/absolute/path/to/plugin" }
+];
+```
+
+For complete information on creating and using plugins, see [Plugins](/docs/en/agent-sdk/plugins).
+
+## Message Types
+
+### `SDKMessage`
+
+Union type of all possible messages returned by the query.
+
+```typescript
+type SDKMessage =
+  | SDKAssistantMessage
+  | SDKUserMessage
+  | SDKUserMessageReplay
+  | SDKResultMessage
+  | SDKSystemMessage
+  | SDKPartialAssistantMessage
+  | SDKCompactBoundaryMessage
+  | SDKStatusMessage
+  | SDKHookStartedMessage
+  | SDKHookProgressMessage
+  | SDKHookResponseMessage
+  | SDKToolProgressMessage
+  | SDKAuthStatusMessage
+  | SDKTaskNotificationMessage
+  | SDKTaskStartedMessage
+  | SDKTaskProgressMessage
+  | SDKFilesPersistedEvent
+  | SDKToolUseSummaryMessage
+  | SDKRateLimitEvent
+  | SDKPromptSuggestionMessage;
+```
+
+### `SDKAssistantMessage`
+
+Assistant response message.
+
+```typescript
+type SDKAssistantMessage = {
+  type: "assistant";
+  uuid: UUID;
+  session_id: string;
+  message: BetaMessage; // From Anthropic SDK
+  parent_tool_use_id: string | null;
+  error?: SDKAssistantMessageError;
+};
+```
+
+The `message` field is a [`BetaMessage`](/docs/en/api/messages) from the Anthropic SDK. It includes fields like `id`, `content`, `model`, `stop_reason`, and `usage`.
+
+`SDKAssistantMessageError` is one of: `'authentication_failed'`, `'billing_error'`, `'rate_limit'`, `'invalid_request'`, `'server_error'`, or `'unknown'`.
+
+### `SDKUserMessage`
+
+User input message.
+
+```typescript
+type SDKUserMessage = {
+  type: "user";
+  uuid?: UUID;
+  session_id: string;
+  message: MessageParam; // From Anthropic SDK
+  parent_tool_use_id: string | null;
+  isSynthetic?: boolean;
+  tool_use_result?: unknown;
+}
+```
+
+### `SDKUserMessageReplay`
+
+Replayed user message with required UUID.
+
+```typescript
+type SDKUserMessageReplay = {
+  type: "user";
+  uuid: UUID;
+  session_id: string;
+  message: MessageParam;
+  parent_tool_use_id: string | null;
+  isSynthetic?: boolean;
+  tool_use_result?: unknown;
+  isReplay: true;
+}
+```
+
+### `SDKResultMessage`
+
+Final result message.
+
+```typescript
+type SDKResultMessage =
+  | {
+      type: "result";
+      subtype: "success";
+      uuid: UUID;
+      session_id: string;
+      duration_ms: number;
+      duration_api_ms: number;
+      is_error: boolean;
+      num_turns: number;
+      result: string;
+      stop_reason: string | null;
+      total_cost_usd: number;
+      usage: NonNullableUsage;
+      modelUsage: { [modelName: string]: ModelUsage };
+      permission_denials: SDKPermissionDenial[];
+      structured_output?: unknown;
+    }
+  | {
+      type: "result";
+      subtype:
+        | "error_max_turns"
+        | "error_during_execution"
+        | "error_max_budget_usd"
+        | "error_max_structured_output_retries";
+      uuid: UUID;
+      session_id: string;
+      duration_ms: number;
+      duration_api_ms: number;
+      is_error: boolean;
+      num_turns: number;
+      stop_reason: string | null;
+      total_cost_usd: number;
+      usage: NonNullableUsage;
+      modelUsage: { [modelName: string]: ModelUsage };
+      permission_denials: SDKPermissionDenial[];
+      errors: string[];
+    }
+```
+
+### `SDKSystemMessage`
+
+System initialization message.
+
+```typescript
+type SDKSystemMessage = {
+  type: "system";
+  subtype: "init";
+  uuid: UUID;
+  session_id: string;
+  agents?: string[];
+  apiKeySource: ApiKeySource;
+  betas?: string[];
+  claude_code_version: string;
+  cwd: string;
+  tools: string[];
+  mcp_servers: {
+    name: string;
+    status: string;
+  }[];
+  model: string;
+  permissionMode: PermissionMode;
+  slash_commands: string[];
+  output_style: string;
+  skills: string[];
+  plugins: { name: string; path: string }[];
+}
+```
+
+### `SDKPartialAssistantMessage`
+
+Streaming partial message (only when `includePartialMessages` is true).
+
+```typescript
+type SDKPartialAssistantMessage = {
+  type: "stream_event";
+  event: BetaRawMessageStreamEvent; // From Anthropic SDK
+  parent_tool_use_id: string | null;
+  uuid: UUID;
+  session_id: string;
+}
+```
+
+### `SDKCompactBoundaryMessage`
+
+Message indicating a conversation compaction boundary.
+
+```typescript
+type SDKCompactBoundaryMessage = {
+  type: "system";
+  subtype: "compact_boundary";
+  uuid: UUID;
+  session_id: string;
+  compact_metadata: {
+    trigger: "manual" | "auto";
+    pre_tokens: number;
+  };
+}
+```
+
+### `SDKPermissionDenial`
+
+Information about a denied tool use.
+
+```typescript
+type SDKPermissionDenial = {
+  tool_name: string;
+  tool_use_id: string;
+  tool_input: Record<string, unknown>;
+}
+```
+
+## Hook Types
+
+For a comprehensive guide on using hooks with examples and common patterns, see the [Hooks guide](/docs/en/agent-sdk/hooks).
+
+### `HookEvent`
+
+Available hook events.
+
+```typescript
+type HookEvent =
+  | "PreToolUse"
+  | "PostToolUse"
+  | "PostToolUseFailure"
+  | "Notification"
+  | "UserPromptSubmit"
+  | "SessionStart"
+  | "SessionEnd"
+  | "Stop"
+  | "SubagentStart"
+  | "SubagentStop"
+  | "PreCompact"
+  | "PermissionRequest"
+  | "Setup"
+  | "TeammateIdle"
+  | "TaskCompleted"
+  | "ConfigChange"
+  | "WorktreeCreate"
+  | "WorktreeRemove";
+```
+
+### `HookCallback`
+
+Hook callback function type.
+
+```typescript
+type HookCallback = (
+  input: HookInput, // Union of all hook input types
+  toolUseID: string | undefined,
+  options: { signal: AbortSignal }
+) => Promise<HookJSONOutput>;
+```
+
+### `HookCallbackMatcher`
+
+Hook configuration with optional matcher.
+
+```typescript
+interface HookCallbackMatcher {
+  matcher?: string;
+  hooks: HookCallback[];
+  timeout?: number; // Timeout in seconds for all hooks in this matcher
+}
+```
+
+### `HookInput`
+
+Union type of all hook input types.
+
+```typescript
+type HookInput =
+  | PreToolUseHookInput
+  | PostToolUseHookInput
+  | PostToolUseFailureHookInput
+  | NotificationHookInput
+  | UserPromptSubmitHookInput
+  | SessionStartHookInput
+  | SessionEndHookInput
+  | StopHookInput
+  | SubagentStartHookInput
+  | SubagentStopHookInput
+  | PreCompactHookInput
+  | PermissionRequestHookInput
+  | SetupHookInput
+  | TeammateIdleHookInput
+  | TaskCompletedHookInput
+  | ConfigChangeHookInput
+  | WorktreeCreateHookInput
+  | WorktreeRemoveHookInput;
+```
+
+### `BaseHookInput`
+
+Base interface that all hook input types extend.
+
+```typescript
+type BaseHookInput = {
+  session_id: string;
+  transcript_path: string;
+  cwd: string;
+  permission_mode?: string;
+}
+```
+
+#### `PreToolUseHookInput`
+
+```typescript
+type PreToolUseHookInput = BaseHookInput & {
+  hook_event_name: "PreToolUse";
+  tool_name: string;
+  tool_input: unknown;
+  tool_use_id: string;
+}
+```
+
+#### `PostToolUseHookInput`
+
+```typescript
+type PostToolUseHookInput = BaseHookInput & {
+  hook_event_name: "PostToolUse";
+  tool_name: string;
+  tool_input: unknown;
+  tool_response: unknown;
+  tool_use_id: string;
+}
+```
+
+#### `PostToolUseFailureHookInput`
+
+```typescript
+type PostToolUseFailureHookInput = BaseHookInput & {
+  hook_event_name: "PostToolUseFailure";
+  tool_name: string;
+  tool_input: unknown;
+  tool_use_id: string;
+  error: string;
+  is_interrupt?: boolean;
+}
+```
+
+#### `NotificationHookInput`
+
+```typescript
+type NotificationHookInput = BaseHookInput & {
+  hook_event_name: "Notification";
+  message: string;
+  title?: string;
+  notification_type: string;
+}
+```
+
+#### `UserPromptSubmitHookInput`
+
+```typescript
+type UserPromptSubmitHookInput = BaseHookInput & {
+  hook_event_name: "UserPromptSubmit";
+  prompt: string;
+}
+```
+
+#### `SessionStartHookInput`
+
+```typescript
+type SessionStartHookInput = BaseHookInput & {
+  hook_event_name: "SessionStart";
+  source: "startup" | "resume" | "clear" | "compact";
+  agent_type?: string;
+  model?: string;
+}
+```
+
+#### `SessionEndHookInput`
+
+```typescript
+type SessionEndHookInput = BaseHookInput & {
+  hook_event_name: "SessionEnd";
+  reason: ExitReason; // String from EXIT_REASONS array
+}
+```
+
+#### `StopHookInput`
+
+```typescript
+type StopHookInput = BaseHookInput & {
+  hook_event_name: "Stop";
+  stop_hook_active: boolean;
+  last_assistant_message?: string;
+}
+```
+
+#### `SubagentStartHookInput`
+
+```typescript
+type SubagentStartHookInput = BaseHookInput & {
+  hook_event_name: "SubagentStart";
+  agent_id: string;
+  agent_type: string;
+}
+```
+
+#### `SubagentStopHookInput`
+
+```typescript
+type SubagentStopHookInput = BaseHookInput & {
+  hook_event_name: "SubagentStop";
+  stop_hook_active: boolean;
+  agent_id: string;
+  agent_transcript_path: string;
+  agent_type: string;
+  last_assistant_message?: string;
+}
+```
+
+#### `PreCompactHookInput`
+
+```typescript
+type PreCompactHookInput = BaseHookInput & {
+  hook_event_name: "PreCompact";
+  trigger: "manual" | "auto";
+  custom_instructions: string | null;
+}
+```
+
+#### `PermissionRequestHookInput`
+
+```typescript
+type PermissionRequestHookInput = BaseHookInput & {
+  hook_event_name: "PermissionRequest";
+  tool_name: string;
+  tool_input: unknown;
+  permission_suggestions?: PermissionUpdate[];
+}
+```
+
+#### `SetupHookInput`
+
+```typescript
+type SetupHookInput = BaseHookInput & {
+  hook_event_name: "Setup";
+  trigger: "init" | "maintenance";
+}
+```
+
+#### `TeammateIdleHookInput`
+
+```typescript
+type TeammateIdleHookInput = BaseHookInput & {
+  hook_event_name: "TeammateIdle";
+  teammate_name: string;
+  team_name: string;
+}
+```
+
+#### `TaskCompletedHookInput`
+
+```typescript
+type TaskCompletedHookInput = BaseHookInput & {
+  hook_event_name: "TaskCompleted";
+  task_id: string;
+  task_subject: string;
+  task_description?: string;
+  teammate_name?: string;
+  team_name?: string;
+}
+```
+
+#### `ConfigChangeHookInput`
+
+```typescript
+type ConfigChangeHookInput = BaseHookInput & {
+  hook_event_name: "ConfigChange";
+  source: "user_settings" | "project_settings" | "local_settings" | "policy_settings" | "skills";
+  file_path?: string;
+}
+```
+
+#### `WorktreeCreateHookInput`
+
+```typescript
+type WorktreeCreateHookInput = BaseHookInput & {
+  hook_event_name: "WorktreeCreate";
+  name: string;
+}
+```
+
+#### `WorktreeRemoveHookInput`
+
+```typescript
+type WorktreeRemoveHookInput = BaseHookInput & {
+  hook_event_name: "WorktreeRemove";
+  worktree_path: string;
+}
+```
+
+### `HookJSONOutput`
+
+Hook return value.
+
+```typescript
+type HookJSONOutput = AsyncHookJSONOutput | SyncHookJSONOutput;
+```
+
+#### `AsyncHookJSONOutput`
+
+```typescript
+type AsyncHookJSONOutput = {
+  async: true;
+  asyncTimeout?: number;
+}
+```
+
+#### `SyncHookJSONOutput`
+
+```typescript
+type SyncHookJSONOutput = {
+  continue?: boolean;
+  suppressOutput?: boolean;
+  stopReason?: string;
+  decision?: "approve" | "block";
+  systemMessage?: string;
+  reason?: string;
+  hookSpecificOutput?:
+    | {
+        hookEventName: "PreToolUse";
+        permissionDecision?: "allow" | "deny" | "ask";
+        permissionDecisionReason?: string;
+        updatedInput?: Record<string, unknown>;
+        additionalContext?: string;
+      }
+    | {
+        hookEventName: "UserPromptSubmit";
+        additionalContext?: string;
+      }
+    | {
+        hookEventName: "SessionStart";
+        additionalContext?: string;
+      }
+    | {
+        hookEventName: "Setup";
+        additionalContext?: string;
+      }
+    | {
+        hookEventName: "SubagentStart";
+        additionalContext?: string;
+      }
+    | {
+        hookEventName: "PostToolUse";
+        additionalContext?: string;
+        updatedMCPToolOutput?: unknown;
+      }
+    | {
+        hookEventName: "PostToolUseFailure";
+        additionalContext?: string;
+      }
+    | {
+        hookEventName: "Notification";
+        additionalContext?: string;
+      }
+    | {
+        hookEventName: "PermissionRequest";
+        decision: {
+          behavior: "allow";
+          updatedInput?: Record<string, unknown>;
+          updatedPermissions?: PermissionUpdate[];
+        } | {
+          behavior: "deny";
+          message?: string;
+          interrupt?: boolean;
+        };
+      };
+}
+```
+
+## Tool Input Types
+
+Documentation of input schemas for all built-in Claude Code tools. These types are exported from `@anthropic-ai/claude-agent-sdk` and can be used for type-safe tool interactions.
+
+### `ToolInputSchemas`
+
+Union of all tool input types, exported from `@anthropic-ai/claude-agent-sdk`.
+
+```typescript
+type ToolInputSchemas =
+  | AgentInput
+  | AskUserQuestionInput
+  | BashInput
+  | TaskOutputInput
+  | ConfigInput
+  | EnterWorktreeInput
+  | ExitPlanModeInput
+  | FileEditInput
+  | FileReadInput
+  | FileWriteInput
+  | GlobInput
+  | GrepInput
+  | ListMcpResourcesInput
+  | McpInput
+  | NotebookEditInput
+  | ReadMcpResourceInput
+  | SubscribeMcpResourceInput
+  | SubscribePollingInput
+  | TaskStopInput
+  | TodoWriteInput
+  | UnsubscribeMcpResourceInput
+  | UnsubscribePollingInput
+  | WebFetchInput
+  | WebSearchInput;
+```
+
+### Task
+
+**Tool name:** `Task`
+
+```typescript
+type AgentInput = {
+  description: string;
+  prompt: string;
+  subagent_type: string;
+  model?: "sonnet" | "opus" | "haiku";
+  resume?: string;
+  run_in_background?: boolean;
+  max_turns?: number;
+  name?: string;
+  team_name?: string;
+  mode?: "acceptEdits" | "bypassPermissions" | "default" | "dontAsk" | "plan";
+  isolation?: "worktree";
+}
+```
+
+Launches a new agent to handle complex, multi-step tasks autonomously.
+
+### AskUserQuestion
+
+**Tool name:** `AskUserQuestion`
+
+```typescript
+type AskUserQuestionInput = {
+  questions: Array<{
+    question: string;
+    header: string;
+    options: Array<{ label: string; description: string }>;
+    multiSelect: boolean;
+  }>;
+}
+```
+
+Asks the user clarifying questions during execution. See [Handle approvals and user input](/docs/en/agent-sdk/user-input#handle-clarifying-questions) for usage details.
+
+### Bash
+
+**Tool name:** `Bash`
+
+```typescript
+type BashInput = {
+  command: string;
+  timeout?: number;
+  description?: string;
+  run_in_background?: boolean;
+  dangerouslyDisableSandbox?: boolean;
+}
+```
+
+Executes bash commands in a persistent shell session with optional timeout and background execution.
+
+### TaskOutput
+
+**Tool name:** `TaskOutput`
+
+```typescript
+type TaskOutputInput = {
+  task_id: string;
+  block: boolean;
+  timeout: number;
+}
+```
+
+Retrieves output from a running or completed background task.
+
+### Edit
+
+**Tool name:** `Edit`
+
+```typescript
+type FileEditInput = {
+  file_path: string;
+  old_string: string;
+  new_string: string;
+  replace_all?: boolean;
+}
+```
+
+Performs exact string replacements in files.
+
+### Read
+
+**Tool name:** `Read`
+
+```typescript
+type FileReadInput = {
+  file_path: string;
+  offset?: number;
+  limit?: number;
+  pages?: string;
+}
+```
+
+Reads files from the local filesystem, including text, images, PDFs, and Jupyter notebooks. Use `pages` for PDF page ranges (for example, `"1-5"`).
+
+### Write
+
+**Tool name:** `Write`
+
+```typescript
+type FileWriteInput = {
+  file_path: string;
+  content: string;
+}
+```
+
+Writes a file to the local filesystem, overwriting if it exists.
+
+### Glob
+
+**Tool name:** `Glob`
+
+```typescript
+type GlobInput = {
+  pattern: string;
+  path?: string;
+}
+```
+
+Fast file pattern matching that works with any codebase size.
+
+### Grep
+
+**Tool name:** `Grep`
+
+```typescript
+type GrepInput = {
+  pattern: string;
+  path?: string;
+  glob?: string;
+  type?: string;
+  output_mode?: "content" | "files_with_matches" | "count";
+  "-i"?: boolean;
+  "-n"?: boolean;
+  "-B"?: number;
+  "-A"?: number;
+  "-C"?: number;
+  context?: number;
+  head_limit?: number;
+  offset?: number;
+  multiline?: boolean;
+}
+```
+
+Powerful search tool built on ripgrep with regex support.
+
+### TaskStop
+
+**Tool name:** `TaskStop`
+
+```typescript
+type TaskStopInput = {
+  task_id?: string;
+  shell_id?: string; // Deprecated: use task_id
+}
+```
+
+Stops a running background task or shell by ID.
+
+### NotebookEdit
+
+**Tool name:** `NotebookEdit`
+
+```typescript
+type NotebookEditInput = {
+  notebook_path: string;
+  cell_id?: string;
+  new_source: string;
+  cell_type?: "code" | "markdown";
+  edit_mode?: "replace" | "insert" | "delete";
+}
+```
+
+Edits cells in Jupyter notebook files.
+
+### WebFetch
+
+**Tool name:** `WebFetch`
+
+```typescript
+type WebFetchInput = {
+  url: string;
+  prompt: string;
+}
+```
+
+Fetches content from a URL and processes it with an AI model.
+
+### WebSearch
+
+**Tool name:** `WebSearch`
+
+```typescript
+type WebSearchInput = {
+  query: string;
+  allowed_domains?: string[];
+  blocked_domains?: string[];
+}
+```
+
+Searches the web and returns formatted results.
+
+### TodoWrite
+
+**Tool name:** `TodoWrite`
+
+```typescript
+type TodoWriteInput = {
+  todos: Array<{
+    content: string;
+    status: "pending" | "in_progress" | "completed";
+    activeForm: string;
+  }>;
+}
+```
+
+Creates and manages a structured task list for tracking progress.
+
+### ExitPlanMode
+
+**Tool name:** `ExitPlanMode`
+
+```typescript
+type ExitPlanModeInput = {
+  allowedPrompts?: Array<{
+    tool: "Bash";
+    prompt: string;
+  }>;
+}
+```
+
+Exits planning mode. Optionally specifies prompt-based permissions needed to implement the plan.
+
+### ListMcpResources
+
+**Tool name:** `ListMcpResources`
+
+```typescript
+type ListMcpResourcesInput = {
+  server?: string;
+}
+```
+
+Lists available MCP resources from connected servers.
+
+### ReadMcpResource
+
+**Tool name:** `ReadMcpResource`
+
+```typescript
+type ReadMcpResourceInput = {
+  server: string;
+  uri: string;
+}
+```
+
+Reads a specific MCP resource from a server.
+
+### Config
+
+**Tool name:** `Config`
+
+```typescript
+type ConfigInput = {
+  setting: string;
+  value?: string | boolean | number;
+}
+```
+
+Gets or sets a configuration value.
+
+### EnterWorktree
+
+**Tool name:** `EnterWorktree`
+
+```typescript
+type EnterWorktreeInput = {
+  name?: string;
+}
+```
+
+Creates and enters a temporary git worktree for isolated work.
+
+## Tool Output Types
+
+Documentation of output schemas for all built-in Claude Code tools. These types are exported from `@anthropic-ai/claude-agent-sdk` and represent the actual response data returned by each tool.
+
+### `ToolOutputSchemas`
+
+Union of all tool output types.
+
+```typescript
+type ToolOutputSchemas =
+  | AgentOutput
+  | AskUserQuestionOutput
+  | BashOutput
+  | ConfigOutput
+  | EnterWorktreeOutput
+  | ExitPlanModeOutput
+  | FileEditOutput
+  | FileReadOutput
+  | FileWriteOutput
+  | GlobOutput
+  | GrepOutput
+  | ListMcpResourcesOutput
+  | NotebookEditOutput
+  | ReadMcpResourceOutput
+  | TaskStopOutput
+  | TodoWriteOutput
+  | WebFetchOutput
+  | WebSearchOutput;
+```
+
+### Task
+
+**Tool name:** `Task`
+
+```typescript
+type AgentOutput =
+  | {
+      status: "completed";
+      agentId: string;
+      content: Array<{ type: "text"; text: string }>;
+      totalToolUseCount: number;
+      totalDurationMs: number;
+      totalTokens: number;
+      usage: {
+        input_tokens: number;
+        output_tokens: number;
+        cache_creation_input_tokens: number | null;
+        cache_read_input_tokens: number | null;
+        server_tool_use: {
+          web_search_requests: number;
+          web_fetch_requests: number;
+        } | null;
+        service_tier: ("standard" | "priority" | "batch") | null;
+        cache_creation: {
+          ephemeral_1h_input_tokens: number;
+          ephemeral_5m_input_tokens: number;
+        } | null;
+      };
+      prompt: string;
+    }
+  | {
+      status: "async_launched";
+      agentId: string;
+      description: string;
+      prompt: string;
+      outputFile: string;
+      canReadOutputFile?: boolean;
+    }
+  | {
+      status: "sub_agent_entered";
+      description: string;
+      message: string;
+    };
+```
+
+Returns the result from the subagent. Discriminated on the `status` field: `"completed"` for finished tasks, `"async_launched"` for background tasks, and `"sub_agent_entered"` for interactive subagents.
+
+### AskUserQuestion
+
+**Tool name:** `AskUserQuestion`
+
+```typescript
+type AskUserQuestionOutput = {
+  questions: Array<{
+    question: string;
+    header: string;
+    options: Array<{ label: string; description: string }>;
+    multiSelect: boolean;
+  }>;
+  answers: Record<string, string>;
+}
+```
+
+Returns the questions asked and the user's answers.
+
+### Bash
+
+**Tool name:** `Bash`
+
+```typescript
+type BashOutput = {
+  stdout: string;
+  stderr: string;
+  rawOutputPath?: string;
+  interrupted: boolean;
+  isImage?: boolean;
+  backgroundTaskId?: string;
+  backgroundedByUser?: boolean;
+  dangerouslyDisableSandbox?: boolean;
+  returnCodeInterpretation?: string;
+  structuredContent?: unknown[];
+  persistedOutputPath?: string;
+  persistedOutputSize?: number;
+}
+```
+
+Returns command output with stdout/stderr split. Background commands include a `backgroundTaskId`.
+
+### Edit
+
+**Tool name:** `Edit`
+
+```typescript
+type FileEditOutput = {
+  filePath: string;
+  oldString: string;
+  newString: string;
+  originalFile: string;
+  structuredPatch: Array<{
+    oldStart: number;
+    oldLines: number;
+    newStart: number;
+    newLines: number;
+    lines: string[];
+  }>;
+  userModified: boolean;
+  replaceAll: boolean;
+  gitDiff?: {
+    filename: string;
+    status: "modified" | "added";
+    additions: number;
+    deletions: number;
+    changes: number;
+    patch: string;
+  };
+}
+```
+
+Returns the structured diff of the edit operation.
+
+### Read
+
+**Tool name:** `Read`
+
+```typescript
+type FileReadOutput =
+  | {
+      type: "text";
+      file: {
+        filePath: string;
+        content: string;
+        numLines: number;
+        startLine: number;
+        totalLines: number;
+      };
+    }
+  | {
+      type: "image";
+      file: {
+        base64: string;
+        type: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
+        originalSize: number;
+        dimensions?: {
+          originalWidth?: number;
+          originalHeight?: number;
+          displayWidth?: number;
+          displayHeight?: number;
+        };
+      };
+    }
+  | {
+      type: "notebook";
+      file: {
+        filePath: string;
+        cells: unknown[];
+      };
+    }
+  | {
+      type: "pdf";
+      file: {
+        filePath: string;
+        base64: string;
+        originalSize: number;
+      };
+    }
+  | {
+      type: "parts";
+      file: {
+        filePath: string;
+        originalSize: number;
+        count: number;
+        outputDir: string;
+      };
+    };
+```
+
+Returns file contents in a format appropriate to the file type. Discriminated on the `type` field.
+
+### Write
+
+**Tool name:** `Write`
+
+```typescript
+type FileWriteOutput = {
+  type: "create" | "update";
+  filePath: string;
+  content: string;
+  structuredPatch: Array<{
+    oldStart: number;
+    oldLines: number;
+    newStart: number;
+    newLines: number;
+    lines: string[];
+  }>;
+  originalFile: string | null;
+  gitDiff?: {
+    filename: string;
+    status: "modified" | "added";
+    additions: number;
+    deletions: number;
+    changes: number;
+    patch: string;
+  };
+}
+```
+
+Returns the write result with structured diff information.
+
+### Glob
+
+**Tool name:** `Glob`
+
+```typescript
+type GlobOutput = {
+  durationMs: number;
+  numFiles: number;
+  filenames: string[];
+  truncated: boolean;
+}
+```
+
+Returns file paths matching the glob pattern, sorted by modification time.
+
+### Grep
+
+**Tool name:** `Grep`
+
+```typescript
+type GrepOutput = {
+  mode?: "content" | "files_with_matches" | "count";
+  numFiles: number;
+  filenames: string[];
+  content?: string;
+  numLines?: number;
+  numMatches?: number;
+  appliedLimit?: number;
+  appliedOffset?: number;
+}
+```
+
+Returns search results. The shape varies by `mode`: file list, content with matches, or match counts.
+
+### TaskStop
+
+**Tool name:** `TaskStop`
+
+```typescript
+type TaskStopOutput = {
+  message: string;
+  task_id: string;
+  task_type: string;
+  command?: string;
+}
+```
+
+Returns confirmation after stopping the background task.
+
+### NotebookEdit
+
+**Tool name:** `NotebookEdit`
+
+```typescript
+type NotebookEditOutput = {
+  new_source: string;
+  cell_id?: string;
+  cell_type: "code" | "markdown";
+  language: string;
+  edit_mode: string;
+  error?: string;
+  notebook_path: string;
+  original_file: string;
+  updated_file: string;
+}
+```
+
+Returns the result of the notebook edit with original and updated file contents.
+
+### WebFetch
+
+**Tool name:** `WebFetch`
+
+```typescript
+type WebFetchOutput = {
+  bytes: number;
+  code: number;
+  codeText: string;
+  result: string;
+  durationMs: number;
+  url: string;
+}
+```
+
+Returns the fetched content with HTTP status and metadata.
+
+### WebSearch
+
+**Tool name:** `WebSearch`
+
+```typescript
+type WebSearchOutput = {
+  query: string;
+  results: Array<
+    | {
+        tool_use_id: string;
+        content: Array<{ title: string; url: string }>;
+      }
+    | string
+  >;
+  durationSeconds: number;
+}
+```
+
+Returns search results from the web.
+
+### TodoWrite
+
+**Tool name:** `TodoWrite`
+
+```typescript
+type TodoWriteOutput = {
+  oldTodos: Array<{
+    content: string;
+    status: "pending" | "in_progress" | "completed";
+    activeForm: string;
+  }>;
+  newTodos: Array<{
+    content: string;
+    status: "pending" | "in_progress" | "completed";
+    activeForm: string;
+  }>;
+}
+```
+
+Returns the previous and updated task lists.
+
+### ExitPlanMode
+
+**Tool name:** `ExitPlanMode`
+
+```typescript
+type ExitPlanModeOutput = {
+  plan: string | null;
+  isAgent: boolean;
+  filePath?: string;
+  hasTaskTool?: boolean;
+  awaitingLeaderApproval?: boolean;
+  requestId?: string;
+}
+```
+
+Returns the plan state after exiting plan mode.
+
+### ListMcpResources
+
+**Tool name:** `ListMcpResources`
+
+```typescript
+type ListMcpResourcesOutput = Array<{
+  uri: string;
+  name: string;
+  mimeType?: string;
+  description?: string;
+  server: string;
+}>;
+```
+
+Returns an array of available MCP resources.
+
+### ReadMcpResource
+
+**Tool name:** `ReadMcpResource`
+
+```typescript
+type ReadMcpResourceOutput = {
+  contents: Array<{
+    uri: string;
+    mimeType?: string;
+    text?: string;
+  }>;
+}
+```
+
+Returns the contents of the requested MCP resource.
+
+### Config
+
+**Tool name:** `Config`
+
+```typescript
+type ConfigOutput = {
+  success: boolean;
+  operation?: "get" | "set";
+  setting?: string;
+  value?: unknown;
+  previousValue?: unknown;
+  newValue?: unknown;
+  error?: string;
+}
+```
+
+Returns the result of a configuration get or set operation.
+
+### EnterWorktree
+
+**Tool name:** `EnterWorktree`
+
+```typescript
+type EnterWorktreeOutput = {
+  worktreePath: string;
+  worktreeBranch?: string;
+  message: string;
+}
+```
+
+Returns information about the created git worktree.
+
+## Permission Types
+
+### `PermissionUpdate`
+
+Operations for updating permissions.
+
+```typescript
+type PermissionUpdate =
+  | {
+      type: "addRules";
+      rules: PermissionRuleValue[];
+      behavior: PermissionBehavior;
+      destination: PermissionUpdateDestination;
+    }
+  | {
+      type: "replaceRules";
+      rules: PermissionRuleValue[];
+      behavior: PermissionBehavior;
+      destination: PermissionUpdateDestination;
+    }
+  | {
+      type: "removeRules";
+      rules: PermissionRuleValue[];
+      behavior: PermissionBehavior;
+      destination: PermissionUpdateDestination;
+    }
+  | {
+      type: "setMode";
+      mode: PermissionMode;
+      destination: PermissionUpdateDestination;
+    }
+  | {
+      type: "addDirectories";
+      directories: string[];
+      destination: PermissionUpdateDestination;
+    }
+  | {
+      type: "removeDirectories";
+      directories: string[];
+      destination: PermissionUpdateDestination;
+    }
+```
+
+### `PermissionBehavior`
+
+```typescript
+type PermissionBehavior = "allow" | "deny" | "ask";
+```
+
+### `PermissionUpdateDestination`
+
+```typescript
+type PermissionUpdateDestination =
+  | "userSettings" // Global user settings
+  | "projectSettings" // Per-directory project settings
+  | "localSettings" // Gitignored local settings
+  | "session" // Current session only
+  | "cliArg" // CLI argument
+```
+
+### `PermissionRuleValue`
+
+```typescript
+type PermissionRuleValue = {
+  toolName: string;
+  ruleContent?: string;
+}
+```
+
+## Other Types
+
+### `ApiKeySource`
+
+```typescript
+type ApiKeySource = "user" | "project" | "org" | "temporary" | "oauth";
+```
+
+### `SdkBeta`
+
+Available beta features that can be enabled via the `betas` option. See [Beta headers](/docs/en/api/beta-headers) for more information.
+
+```typescript
+type SdkBeta = "context-1m-2025-08-07";
+```
+
+| Value                     | Description                                                                          | Compatible Models                                   |
+| :------------------------ | :----------------------------------------------------------------------------------- | :-------------------------------------------------- |
+| `'context-1m-2025-08-07'` | Enables 1 million token [context window](/docs/en/build-with-claude/context-windows) | Claude Opus 4.6, Claude Sonnet 4.5, Claude Sonnet 4 |
+
+### `SlashCommand`
+
+Information about an available slash command.
+
+```typescript
+type SlashCommand = {
+  name: string;
+  description: string;
+  argumentHint: string;
+}
+```
+
+### `ModelInfo`
+
+Information about an available model.
+
+```typescript
+type ModelInfo = {
+  value: string;
+  displayName: string;
+  description: string;
+  supportsEffort?: boolean;
+  supportedEffortLevels?: ("low" | "medium" | "high" | "max")[];
+  supportsAdaptiveThinking?: boolean;
+}
+```
+
+### `McpServerStatus`
+
+Status of a connected MCP server.
+
+```typescript
+type McpServerStatus = {
+  name: string;
+  status: "connected" | "failed" | "needs-auth" | "pending" | "disabled";
+  serverInfo?: {
+    name: string;
+    version: string;
+  };
+  error?: string;
+  config?: McpServerStatusConfig;
+  scope?: string;
+  tools?: {
+    name: string;
+    description?: string;
+    annotations?: {
+      readOnly?: boolean;
+      destructive?: boolean;
+      openWorld?: boolean;
+    };
+  }[];
+}
+```
+
+### `McpServerStatusConfig`
+
+The configuration of an MCP server as reported by `mcpServerStatus()`. This is the union of all MCP server transport types.
+
+```typescript
+type McpServerStatusConfig =
+  | McpStdioServerConfig
+  | McpSSEServerConfig
+  | McpHttpServerConfig
+  | McpSdkServerConfig
+  | McpClaudeAIProxyServerConfig;
+```
+
+See [`McpServerConfig`](#mcpserverconfig) for details on each transport type.
+
+### `AccountInfo`
+
+Account information for the authenticated user.
+
+```typescript
+type AccountInfo = {
+  email?: string;
+  organization?: string;
+  subscriptionType?: string;
+  tokenSource?: string;
+  apiKeySource?: string;
+}
+```
+
+### `ModelUsage`
+
+Per-model usage statistics returned in result messages.
+
+```typescript
+type ModelUsage = {
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadInputTokens: number;
+  cacheCreationInputTokens: number;
+  webSearchRequests: number;
+  costUSD: number;
+  contextWindow: number;
+  maxOutputTokens: number;
+}
+```
+
+### `ConfigScope`
+
+```typescript
+type ConfigScope = "local" | "user" | "project";
+```
+
+### `NonNullableUsage`
+
+A version of [`Usage`](#usage) with all nullable fields made non-nullable.
+
+```typescript
+type NonNullableUsage = {
+  [K in keyof Usage]: NonNullable<Usage[K]>;
+}
+```
+
+### `Usage`
+
+Token usage statistics (from `@anthropic-ai/sdk`).
+
+```typescript
+type Usage = {
+  input_tokens: number | null;
+  output_tokens: number | null;
+  cache_creation_input_tokens?: number | null;
+  cache_read_input_tokens?: number | null;
+}
+```
+
+### `CallToolResult`
+
+MCP tool result type (from `@modelcontextprotocol/sdk/types.js`).
+
+```typescript
+type CallToolResult = {
+  content: Array<{
+    type: "text" | "image" | "resource";
+    // Additional fields vary by type
+  }>;
+  isError?: boolean;
+}
+```
+
+### `ThinkingConfig`
+
+Controls Claude's thinking/reasoning behavior. Takes precedence over the deprecated `maxThinkingTokens`.
+
+```typescript
+type ThinkingConfig =
+  | { type: "adaptive" } // The model determines when and how much to reason (Opus 4.6+)
+  | { type: "enabled"; budgetTokens?: number } // Fixed thinking token budget
+  | { type: "disabled" } // No extended thinking
+```
+
+### `SpawnedProcess`
+
+Interface for custom process spawning (used with `spawnClaudeCodeProcess` option). `ChildProcess` already satisfies this interface.
+
+```typescript
+interface SpawnedProcess {
+  stdin: Writable;
+  stdout: Readable;
+  readonly killed: boolean;
+  readonly exitCode: number | null;
+  kill(signal: NodeJS.Signals): boolean;
+  on(event: "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void): void;
+  on(event: "error", listener: (error: Error) => void): void;
+  once(event: "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void): void;
+  once(event: "error", listener: (error: Error) => void): void;
+  off(event: "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void): void;
+  off(event: "error", listener: (error: Error) => void): void;
+}
+```
+
+### `SpawnOptions`
+
+Options passed to the custom spawn function.
+
+```typescript
+interface SpawnOptions {
+  command: string;
+  args: string[];
+  cwd?: string;
+  env: Record<string, string | undefined>;
+  signal: AbortSignal;
+}
+```
+
+### `McpSetServersResult`
+
+Result of a `setMcpServers()` operation.
+
+```typescript
+type McpSetServersResult = {
+  added: string[];
+  removed: string[];
+  errors: Record<string, string>;
+}
+```
+
+### `RewindFilesResult`
+
+Result of a `rewindFiles()` operation.
+
+```typescript
+type RewindFilesResult = {
+  canRewind: boolean;
+  error?: string;
+  filesChanged?: string[];
+  insertions?: number;
+  deletions?: number;
+}
+```
+
+### `SDKStatusMessage`
+
+Status update message (e.g., compacting).
+
+```typescript
+type SDKStatusMessage = {
+  type: "system";
+  subtype: "status";
+  status: "compacting" | null;
+  permissionMode?: PermissionMode;
+  uuid: UUID;
+  session_id: string;
+}
+```
+
+### `SDKTaskNotificationMessage`
+
+Notification when a background task completes, fails, or is stopped.
+
+```typescript
+type SDKTaskNotificationMessage = {
+  type: "system";
+  subtype: "task_notification";
+  task_id: string;
+  tool_use_id?: string;
+  status: "completed" | "failed" | "stopped";
+  output_file: string;
+  summary: string;
+  usage?: {
+    total_tokens: number;
+    tool_uses: number;
+    duration_ms: number;
+  };
+  uuid: UUID;
+  session_id: string;
+}
+```
+
+### `SDKToolUseSummaryMessage`
+
+Summary of tool usage in a conversation.
+
+```typescript
+type SDKToolUseSummaryMessage = {
+  type: "tool_use_summary";
+  summary: string;
+  preceding_tool_use_ids: string[];
+  uuid: UUID;
+  session_id: string;
+}
+```
+
+### `SDKHookStartedMessage`
+
+Emitted when a hook begins executing.
+
+```typescript
+type SDKHookStartedMessage = {
+  type: "system";
+  subtype: "hook_started";
+  hook_id: string;
+  hook_name: string;
+  hook_event: string;
+  uuid: UUID;
+  session_id: string;
+}
+```
+
+### `SDKHookProgressMessage`
+
+Emitted while a hook is running, with stdout/stderr output.
+
+```typescript
+type SDKHookProgressMessage = {
+  type: "system";
+  subtype: "hook_progress";
+  hook_id: string;
+  hook_name: string;
+  hook_event: string;
+  stdout: string;
+  stderr: string;
+  output: string;
+  uuid: UUID;
+  session_id: string;
+}
+```
+
+### `SDKHookResponseMessage`
+
+Emitted when a hook finishes executing.
+
+```typescript
+type SDKHookResponseMessage = {
+  type: "system";
+  subtype: "hook_response";
+  hook_id: string;
+  hook_name: string;
+  hook_event: string;
+  output: string;
+  stdout: string;
+  stderr: string;
+  exit_code?: number;
+  outcome: "success" | "error" | "cancelled";
+  uuid: UUID;
+  session_id: string;
+}
+```
+
+### `SDKToolProgressMessage`
+
+Emitted periodically while a tool is executing to indicate progress.
+
+```typescript
+type SDKToolProgressMessage = {
+  type: "tool_progress";
+  tool_use_id: string;
+  tool_name: string;
+  parent_tool_use_id: string | null;
+  elapsed_time_seconds: number;
+  task_id?: string;
+  uuid: UUID;
+  session_id: string;
+}
+```
+
+### `SDKAuthStatusMessage`
+
+Emitted during authentication flows.
+
+```typescript
+type SDKAuthStatusMessage = {
+  type: "auth_status";
+  isAuthenticating: boolean;
+  output: string[];
+  error?: string;
+  uuid: UUID;
+  session_id: string;
+}
+```
+
+### `SDKTaskStartedMessage`
+
+Emitted when a background task begins.
+
+```typescript
+type SDKTaskStartedMessage = {
+  type: "system";
+  subtype: "task_started";
+  task_id: string;
+  tool_use_id?: string;
+  description: string;
+  task_type?: string;
+  uuid: UUID;
+  session_id: string;
+}
+```
+
+### `SDKTaskProgressMessage`
+
+Emitted periodically while a background task is running.
+
+```typescript
+type SDKTaskProgressMessage = {
+  type: "system";
+  subtype: "task_progress";
+  task_id: string;
+  tool_use_id?: string;
+  description: string;
+  usage: {
+    total_tokens: number;
+    tool_uses: number;
+    duration_ms: number;
+  };
+  last_tool_name?: string;
+  uuid: UUID;
+  session_id: string;
+}
+```
+
+### `SDKFilesPersistedEvent`
+
+Emitted when file checkpoints are persisted to disk.
+
+```typescript
+type SDKFilesPersistedEvent = {
+  type: "system";
+  subtype: "files_persisted";
+  files: { filename: string; file_id: string }[];
+  failed: { filename: string; error: string }[];
+  processed_at: string;
+  uuid: UUID;
+  session_id: string;
+}
+```
+
+### `SDKRateLimitEvent`
+
+Emitted when the session encounters a rate limit.
+
+```typescript
+type SDKRateLimitEvent = {
+  type: "rate_limit_event";
+  rate_limit_info: {
+    status: "allowed" | "allowed_warning" | "rejected";
+    resetsAt?: number;
+    utilization?: number;
+  };
+  uuid: UUID;
+  session_id: string;
+}
+```
+
+### `SDKPromptSuggestionMessage`
+
+Emitted after each turn when `promptSuggestions` is enabled. Contains a predicted next user prompt.
+
+```typescript
+type SDKPromptSuggestionMessage = {
+  type: "prompt_suggestion";
+  suggestion: string;
+  uuid: UUID;
+  session_id: string;
+}
+```
+
+### `AbortError`
+
+Custom error class for abort operations.
+
+```typescript
+class AbortError extends Error {}
+```
+
+## Sandbox Configuration
+
+### `SandboxSettings`
+
+Configuration for sandbox behavior. Use this to enable command sandboxing and configure network restrictions programmatically.
+
+```typescript
+type SandboxSettings = {
+  enabled?: boolean;
+  autoAllowBashIfSandboxed?: boolean;
+  excludedCommands?: string[];
+  allowUnsandboxedCommands?: boolean;
+  network?: SandboxNetworkConfig;
+  filesystem?: SandboxFilesystemConfig;
+  ignoreViolations?: Record<string, string[]>;
+  enableWeakerNestedSandbox?: boolean;
+  ripgrep?: { command: string; args?: string[] };
+}
+```
+
+| Property                    | Type                                                  | Default     | Description                                                                                                                                                                                                                             |
+| :-------------------------- | :---------------------------------------------------- | :---------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `enabled`                   | `boolean`                                             | `false`     | Enable sandbox mode for command execution                                                                                                                                                                                               |
+| `autoAllowBashIfSandboxed`  | `boolean`                                             | `true`      | Auto-approve bash commands when sandbox is enabled                                                                                                                                                                                      |
+| `excludedCommands`          | `string[]`                                            | `[]`        | Commands that always bypass sandbox restrictions (e.g., `['docker']`). These run unsandboxed automatically without model involvement                                                                                                    |
+| `allowUnsandboxedCommands`  | `boolean`                                             | `true`      | Allow the model to request running commands outside the sandbox. When `true`, the model can set `dangerouslyDisableSandbox` in tool input, which falls back to the [permissions system](#permissions-fallback-for-unsandboxed-commands) |
+| `network`                   | [`SandboxNetworkConfig`](#sandboxnetworkconfig)       | `undefined` | Network-specific sandbox configuration                                                                                                                                                                                                  |
+| `filesystem`                | [`SandboxFilesystemConfig`](#sandboxfilesystemconfig) | `undefined` | Filesystem-specific sandbox configuration for read/write restrictions                                                                                                                                                                   |
+| `ignoreViolations`          | `Record<string, string[]>`                            | `undefined` | Map of violation categories to patterns to ignore (e.g., `{ file: ['/tmp/*'], network: ['localhost'] }`)                                                                                                                                |
+| `enableWeakerNestedSandbox` | `boolean`                                             | `false`     | Enable a weaker nested sandbox for compatibility                                                                                                                                                                                        |
+| `ripgrep`                   | `{ command: string; args?: string[] }`                | `undefined` | Custom ripgrep binary configuration for sandbox environments                                                                                                                                                                            |
+
+#### Example usage
+
+```typescript
+import { query } from "@anthropic-ai/claude-agent-sdk";
+
+for await (const message of query({
+  prompt: "Build and test my project",
+  options: {
+    sandbox: {
+      enabled: true,
+      autoAllowBashIfSandboxed: true,
+      network: {
+        allowLocalBinding: true
+      }
+    }
+  }
+})) {
+  if ("result" in message) console.log(message.result);
+}
+```
+
+<Warning>
+**Unix socket security**: The `allowUnixSockets` option can grant access to powerful system services. For example, allowing `/var/run/docker.sock` effectively grants full host system access through the Docker API, bypassing sandbox isolation. Only allow Unix sockets that are strictly necessary and understand the security implications of each.
+</Warning>
+
+### `SandboxNetworkConfig`
+
+Network-specific configuration for sandbox mode.
+
+```typescript
+type SandboxNetworkConfig = {
+  allowedDomains?: string[];
+  allowManagedDomainsOnly?: boolean;
+  allowLocalBinding?: boolean;
+  allowUnixSockets?: string[];
+  allowAllUnixSockets?: boolean;
+  httpProxyPort?: number;
+  socksProxyPort?: number;
+}
+```
+
+| Property                  | Type       | Default     | Description                                                       |
+| :------------------------ | :--------- | :---------- | :---------------------------------------------------------------- |
+| `allowedDomains`          | `string[]` | `[]`        | Domain names that sandboxed processes can access                  |
+| `allowManagedDomainsOnly` | `boolean`  | `false`     | Restrict network access to only the domains in `allowedDomains`   |
+| `allowLocalBinding`       | `boolean`  | `false`     | Allow processes to bind to local ports (e.g., for dev servers)    |
+| `allowUnixSockets`        | `string[]` | `[]`        | Unix socket paths that processes can access (e.g., Docker socket) |
+| `allowAllUnixSockets`     | `boolean`  | `false`     | Allow access to all Unix sockets                                  |
+| `httpProxyPort`           | `number`   | `undefined` | HTTP proxy port for network requests                              |
+| `socksProxyPort`          | `number`   | `undefined` | SOCKS proxy port for network requests                             |
+
+### `SandboxFilesystemConfig`
+
+Filesystem-specific configuration for sandbox mode.
+
+```typescript
+type SandboxFilesystemConfig = {
+  allowWrite?: string[];
+  denyWrite?: string[];
+  denyRead?: string[];
+}
+```
+
+| Property     | Type       | Default | Description                                 |
+| :----------- | :--------- | :------ | :------------------------------------------ |
+| `allowWrite` | `string[]` | `[]`    | File path patterns to allow write access to |
+| `denyWrite`  | `string[]` | `[]`    | File path patterns to deny write access to  |
+| `denyRead`   | `string[]` | `[]`    | File path patterns to deny read access to   |
+
+### Permissions Fallback for Unsandboxed Commands
+
+When `allowUnsandboxedCommands` is enabled, the model can request to run commands outside the sandbox by setting `dangerouslyDisableSandbox: true` in the tool input. These requests fall back to the existing permissions system, meaning your `canUseTool` handler will be invoked, allowing you to implement custom authorization logic.
+
+<Note>
+**`excludedCommands` vs `allowUnsandboxedCommands`:**
+- `excludedCommands`: A static list of commands that always bypass the sandbox automatically (e.g., `['docker']`). The model has no control over this.
+- `allowUnsandboxedCommands`: Lets the model decide at runtime whether to request unsandboxed execution by setting `dangerouslyDisableSandbox: true` in the tool input.
+</Note>
+
+```typescript
+import { query } from "@anthropic-ai/claude-agent-sdk";
+
+for await (const message of query({
+  prompt: "Deploy my application",
+  options: {
+    sandbox: {
+      enabled: true,
+      allowUnsandboxedCommands: true // Model can request unsandboxed execution
+    },
+    permissionMode: "default",
+    canUseTool: async (tool, input) => {
+      // Check if the model is requesting to bypass the sandbox
+      if (tool === "Bash" && input.dangerouslyDisableSandbox) {
+        // The model is requesting to run this command outside the sandbox
+        console.log(`Unsandboxed command requested: ${input.command}`);
+
+        if (isCommandAuthorized(input.command)) {
+          return { behavior: "allow" as const, updatedInput: input };
+        }
+        return { behavior: "deny" as const, message: "Command not authorized for unsandboxed execution" };
+      }
+      return { behavior: "allow" as const, updatedInput: input };
+    }
+  }
+})) {
+  if ("result" in message) console.log(message.result);
+}
+```
+
+This pattern enables you to:
+
+- **Audit model requests**: Log when the model requests unsandboxed execution
+- **Implement allowlists**: Only permit specific commands to run unsandboxed
+- **Add approval workflows**: Require explicit authorization for privileged operations
+
+<Warning>
+Commands running with `dangerouslyDisableSandbox: true` have full system access. Ensure your `canUseTool` handler validates these requests carefully.
+
+If `permissionMode` is set to `bypassPermissions` and `allowUnsandboxedCommands` is enabled, the model can autonomously execute commands outside the sandbox without any approval prompts. This combination effectively allows the model to escape sandbox isolation silently.
+</Warning>
+
+## See also
+
+- [SDK overview](/docs/en/agent-sdk/overview) - General SDK concepts
+- [Python SDK reference](/docs/en/agent-sdk/python) - Python SDK documentation
+- [CLI reference](https://code.claude.com/docs/en/cli-reference) - Command-line interface
+- [Common workflows](https://code.claude.com/docs/en/common-workflows) - Step-by-step guides
\ No newline at end of file
diff --git a/docs/claude-agent-sdk/typescript-sdk.md b/docs/claude-agent-sdk/typescript-sdk.md
deleted file mode 100644
index d435d1ecc0..0000000000
--- a/docs/claude-agent-sdk/typescript-sdk.md
+++ /dev/null
@@ -1,2177 +0,0 @@
-# Agent SDK reference - TypeScript
-
-Complete API reference for the TypeScript Agent SDK, including all functions, types, and interfaces.
-
----
-
-<script src="/components/typescript-sdk-type-links.js" defer />
-
-<Note>
-**Try the new V2 interface (preview):** A simplified interface with `send()` and `receive()` patterns is now available, making multi-turn conversations easier. [Learn more about the TypeScript V2 preview](/docs/en/agent-sdk/typescript-v2-preview)
-</Note>
-
-## Installation
-
-```bash
-npm install @anthropic-ai/claude-agent-sdk
-```
-
-## Functions
-
-### `query()`
-
-The primary function for interacting with Claude Code. Creates an async generator that streams messages as they arrive.
-
-```typescript
-function query({
-  prompt,
-  options
-}: {
-  prompt: string | AsyncIterable<SDKUserMessage>;
-  options?: Options;
-}): Query
-```
-
-#### Parameters
-
-| Parameter | Type | Description |
-| :-------- | :--- | :---------- |
-| `prompt` | `string \| AsyncIterable<`[`SDKUserMessage`](#sdkusermessage)`>` | The input prompt as a string or async iterable for streaming mode |
-| `options` | [`Options`](#options) | Optional configuration object (see Options type below) |
-
-#### Returns
-
-Returns a [`Query`](#query-1) object that extends `AsyncGenerator<`[`SDKMessage`](#sdkmessage)`, void>` with additional methods.
-
-### `tool()`
-
-Creates a type-safe MCP tool definition for use with SDK MCP servers.
-
-```typescript
-function tool<Schema extends ZodRawShape>(
-  name: string,
-  description: string,
-  inputSchema: Schema,
-  handler: (args: z.infer<ZodObject<Schema>>, extra: unknown) => Promise<CallToolResult>
-): SdkMcpToolDefinition<Schema>
-```
-
-#### Parameters
-
-| Parameter | Type | Description |
-| :-------- | :--- | :---------- |
-| `name` | `string` | The name of the tool |
-| `description` | `string` | A description of what the tool does |
-| `inputSchema` | `Schema extends ZodRawShape` | Zod schema defining the tool's input parameters |
-| `handler` | `(args, extra) => Promise<`[`CallToolResult`](#calltoolresult)`>` | Async function that executes the tool logic |
-
-### `createSdkMcpServer()`
-
-Creates an MCP server instance that runs in the same process as your application.
-
-```typescript
-function createSdkMcpServer(options: {
-  name: string;
-  version?: string;
-  tools?: Array<SdkMcpToolDefinition<any>>;
-}): McpSdkServerConfigWithInstance
-```
-
-#### Parameters
-
-| Parameter | Type | Description |
-| :-------- | :--- | :---------- |
-| `options.name` | `string` | The name of the MCP server |
-| `options.version` | `string` | Optional version string |
-| `options.tools` | `Array<SdkMcpToolDefinition>` | Array of tool definitions created with [`tool()`](#tool) |
-
-## Types
-
-### `Options`
-
-Configuration object for the `query()` function.
-
-| Property | Type | Default | Description |
-| :------- | :--- | :------ | :---------- |
-| `abortController` | `AbortController` | `new AbortController()` | Controller for cancelling operations |
-| `additionalDirectories` | `string[]` | `[]` | Additional directories Claude can access |
-| `agents` | `Record<string, [`AgentDefinition`](#agentdefinition)>` | `undefined` | Programmatically define subagents |
-| `allowDangerouslySkipPermissions` | `boolean` | `false` | Enable bypassing permissions. Required when using `permissionMode: 'bypassPermissions'` |
-| `allowedTools` | `string[]` | All tools | List of allowed tool names |
-| `betas` | [`SdkBeta`](#sdkbeta)`[]` | `[]` | Enable beta features (e.g., `['context-1m-2025-08-07']`) |
-| `canUseTool` | [`CanUseTool`](#canusetool) | `undefined` | Custom permission function for tool usage |
-| `continue` | `boolean` | `false` | Continue the most recent conversation |
-| `cwd` | `string` | `process.cwd()` | Current working directory |
-| `disallowedTools` | `string[]` | `[]` | List of disallowed tool names |
-| `enableFileCheckpointing` | `boolean` | `false` | Enable file change tracking for rewinding. See [File checkpointing](/docs/en/agent-sdk/file-checkpointing) |
-| `env` | `Dict<string>` | `process.env` | Environment variables |
-| `executable` | `'bun' \| 'deno' \| 'node'` | Auto-detected | JavaScript runtime to use |
-| `executableArgs` | `string[]` | `[]` | Arguments to pass to the executable |
-| `extraArgs` | `Record<string, string \| null>` | `{}` | Additional arguments |
-| `fallbackModel` | `string` | `undefined` | Model to use if primary fails |
-| `forkSession` | `boolean` | `false` | When resuming with `resume`, fork to a new session ID instead of continuing the original session |
-| `hooks` | `Partial<Record<`[`HookEvent`](#hookevent)`, `[`HookCallbackMatcher`](#hookcallbackmatcher)`[]>>` | `{}` | Hook callbacks for events |
-| `includePartialMessages` | `boolean` | `false` | Include partial message events |
-| `maxBudgetUsd` | `number` | `undefined` | Maximum budget in USD for the query |
-| `maxThinkingTokens` | `number` | `undefined` | Maximum tokens for thinking process |
-| `maxTurns` | `number` | `undefined` | Maximum conversation turns |
-| `mcpServers` | `Record<string, [`McpServerConfig`](#mcpserverconfig)>` | `{}` | MCP server configurations |
-| `model` | `string` | Default from CLI | Claude model to use |
-| `outputFormat` | `{ type: 'json_schema', schema: JSONSchema }` | `undefined` | Define output format for agent results. See [Structured outputs](/docs/en/agent-sdk/structured-outputs) for details |
-| `pathToClaudeCodeExecutable` | `string` | Uses built-in executable | Path to Claude Code executable |
-| `permissionMode` | [`PermissionMode`](#permissionmode) | `'default'` | Permission mode for the session |
-| `permissionPromptToolName` | `string` | `undefined` | MCP tool name for permission prompts |
-| `plugins` | [`SdkPluginConfig`](#sdkpluginconfig)`[]` | `[]` | Load custom plugins from local paths. See [Plugins](/docs/en/agent-sdk/plugins) for details |
-| `resume` | `string` | `undefined` | Session ID to resume |
-| `resumeSessionAt` | `string` | `undefined` | Resume session at a specific message UUID |
-| `sandbox` | [`SandboxSettings`](#sandboxsettings) | `undefined` | Configure sandbox behavior programmatically. See [Sandbox settings](#sandboxsettings) for details |
-| `settingSources` | [`SettingSource`](#settingsource)`[]` | `[]` (no settings) | Control which filesystem settings to load. When omitted, no settings are loaded. **Note:** Must include `'project'` to load CLAUDE.md files |
-| `stderr` | `(data: string) => void` | `undefined` | Callback for stderr output |
-| `strictMcpConfig` | `boolean` | `false` | Enforce strict MCP validation |
-| `systemPrompt` | `string \| { type: 'preset'; preset: 'claude_code'; append?: string }` | `undefined` (minimal prompt) | System prompt configuration. Pass a string for custom prompt, or `{ type: 'preset', preset: 'claude_code' }` to use Claude Code's system prompt. When using the preset object form, add `append` to extend the system prompt with additional instructions |
-| `tools` | `string[] \| { type: 'preset'; preset: 'claude_code' }` | `undefined` | Tool configuration. Pass an array of tool names or use the preset to get Claude Code's default tools |
-
-### `Query`
-
-Interface returned by the `query()` function.
-
-```typescript
-interface Query extends AsyncGenerator<SDKMessage, void> {
-  interrupt(): Promise<void>;
-  rewindFiles(userMessageUuid: string): Promise<void>;
-  setPermissionMode(mode: PermissionMode): Promise<void>;
-  setModel(model?: string): Promise<void>;
-  setMaxThinkingTokens(maxThinkingTokens: number | null): Promise<void>;
-  supportedCommands(): Promise<SlashCommand[]>;
-  supportedModels(): Promise<ModelInfo[]>;
-  mcpServerStatus(): Promise<McpServerStatus[]>;
-  accountInfo(): Promise<AccountInfo>;
-}
-```
-
-#### Methods
-
-| Method | Description |
-| :----- | :---------- |
-| `interrupt()` | Interrupts the query (only available in streaming input mode) |
-| `rewindFiles(userMessageUuid)` | Restores files to their state at the specified user message. Requires `enableFileCheckpointing: true`. See [File checkpointing](/docs/en/agent-sdk/file-checkpointing) |
-| `setPermissionMode()` | Changes the permission mode (only available in streaming input mode) |
-| `setModel()` | Changes the model (only available in streaming input mode) |
-| `setMaxThinkingTokens()` | Changes the maximum thinking tokens (only available in streaming input mode) |
-| `supportedCommands()` | Returns available slash commands |
-| `supportedModels()` | Returns available models with display info |
-| `mcpServerStatus()` | Returns status of connected MCP servers |
-| `accountInfo()` | Returns account information |
-
-### `AgentDefinition`
-
-Configuration for a subagent defined programmatically.
-
-```typescript
-type AgentDefinition = {
-  description: string;
-  tools?: string[];
-  prompt: string;
-  model?: "sonnet" | "opus" | "haiku" | "inherit";
-}
-```
-
-| Field | Required | Description |
-|:------|:---------|:------------|
-| `description` | Yes | Natural language description of when to use this agent |
-| `tools` | No | Array of allowed tool names. If omitted, inherits all tools |
-| `prompt` | Yes | The agent's system prompt |
-| `model` | No | Model override for this agent. If omitted, uses the main model |
-
-### `SettingSource`
-
-Controls which filesystem-based configuration sources the SDK loads settings from.
-
-```typescript
-type SettingSource = "user" | "project" | "local";
-```
-
-| Value | Description | Location |
-|:------|:------------|:---------|
-| `'user'` | Global user settings | `~/.claude/settings.json` |
-| `'project'` | Shared project settings (version controlled) | `.claude/settings.json` |
-| `'local'` | Local project settings (gitignored) | `.claude/settings.local.json` |
-
-#### Default behavior
-
-When `settingSources` is **omitted** or **undefined**, the SDK does **not** load any filesystem settings. This provides isolation for SDK applications.
-
-#### Why use settingSources?
-
-**Load all filesystem settings (legacy behavior):**
-```typescript
-// Load all settings like SDK v0.0.x did
-const result = query({
-  prompt: "Analyze this code",
-  options: {
-    settingSources: ["user", "project", "local"] // Load all settings
-  }
-});
-```
-
-**Load only specific setting sources:**
-```typescript
-// Load only project settings, ignore user and local
-const result = query({
-  prompt: "Run CI checks",
-  options: {
-    settingSources: ["project"] // Only .claude/settings.json
-  }
-});
-```
-
-**Testing and CI environments:**
-```typescript
-// Ensure consistent behavior in CI by excluding local settings
-const result = query({
-  prompt: "Run tests",
-  options: {
-    settingSources: ["project"], // Only team-shared settings
-    permissionMode: "bypassPermissions"
-  }
-});
-```
-
-**SDK-only applications:**
-```typescript
-// Define everything programmatically (default behavior)
-// No filesystem dependencies - settingSources defaults to []
-const result = query({
-  prompt: "Review this PR",
-  options: {
-    // settingSources: [] is the default, no need to specify
-    agents: { /* ... */ },
-    mcpServers: { /* ... */ },
-    allowedTools: ["Read", "Grep", "Glob"]
-  }
-});
-```
-
-**Loading CLAUDE.md project instructions:**
-```typescript
-// Load project settings to include CLAUDE.md files
-const result = query({
-  prompt: "Add a new feature following project conventions",
-  options: {
-    systemPrompt: {
-      type: "preset",
-      preset: "claude_code" // Required to use CLAUDE.md
-    },
-    settingSources: ["project"], // Loads CLAUDE.md from project directory
-    allowedTools: ["Read", "Write", "Edit"]
-  }
-});
-```
-
-#### Settings precedence
-
-When multiple sources are loaded, settings are merged with this precedence (highest to lowest):
-1. Local settings (`.claude/settings.local.json`)
-2. Project settings (`.claude/settings.json`)
-3. User settings (`~/.claude/settings.json`)
-
-Programmatic options (like `agents`, `allowedTools`) always override filesystem settings.
-
-### `PermissionMode`
-
-```typescript
-type PermissionMode =
-  | "default" // Standard permission behavior
-  | "acceptEdits" // Auto-accept file edits
-  | "bypassPermissions" // Bypass all permission checks
-  | "plan" // Planning mode - no execution
-```
-
-### `CanUseTool`
-
-Custom permission function type for controlling tool usage.
-
-```typescript
-type CanUseTool = (
-  toolName: string,
-  input: ToolInput,
-  options: {
-    signal: AbortSignal;
-    suggestions?: PermissionUpdate[];
-  }
-) => Promise<PermissionResult>;
-```
-
-### `PermissionResult`
-
-Result of a permission check.
-
-```typescript
-type PermissionResult =
-  | {
-      behavior: "allow";
-      updatedInput: ToolInput;
-      updatedPermissions?: PermissionUpdate[];
-    }
-  | {
-      behavior: "deny";
-      message: string;
-      interrupt?: boolean;
-    }
-```
-
-### `McpServerConfig`
-
-Configuration for MCP servers.
-
-```typescript
-type McpServerConfig =
-  | McpStdioServerConfig
-  | McpSSEServerConfig
-  | McpHttpServerConfig
-  | McpSdkServerConfigWithInstance;
-```
-
-#### `McpStdioServerConfig`
-
-```typescript
-type McpStdioServerConfig = {
-  type?: "stdio";
-  command: string;
-  args?: string[];
-  env?: Record<string, string>;
-}
-```
-
-#### `McpSSEServerConfig`
-
-```typescript
-type McpSSEServerConfig = {
-  type: "sse";
-  url: string;
-  headers?: Record<string, string>;
-}
-```
-
-#### `McpHttpServerConfig`
-
-```typescript
-type McpHttpServerConfig = {
-  type: "http";
-  url: string;
-  headers?: Record<string, string>;
-}
-```
-
-#### `McpSdkServerConfigWithInstance`
-
-```typescript
-type McpSdkServerConfigWithInstance = {
-  type: "sdk";
-  name: string;
-  instance: McpServer;
-}
-```
-
-### `SdkPluginConfig`
-
-Configuration for loading plugins in the SDK.
-
-```typescript
-type SdkPluginConfig = {
-  type: "local";
-  path: string;
-}
-```
-
-| Field | Type | Description |
-|:------|:-----|:------------|
-| `type` | `'local'` | Must be `'local'` (only local plugins currently supported) |
-| `path` | `string` | Absolute or relative path to the plugin directory |
-
-**Example:**
-```typescript
-plugins: [
-  { type: "local", path: "./my-plugin" },
-  { type: "local", path: "/absolute/path/to/plugin" }
-];
-```
-
-For complete information on creating and using plugins, see [Plugins](/docs/en/agent-sdk/plugins).
-
-## Message Types
-
-### `SDKMessage`
-
-Union type of all possible messages returned by the query.
-
-```typescript
-type SDKMessage =
-  | SDKAssistantMessage
-  | SDKUserMessage
-  | SDKUserMessageReplay
-  | SDKResultMessage
-  | SDKSystemMessage
-  | SDKPartialAssistantMessage
-  | SDKCompactBoundaryMessage;
-```
-
-### `SDKAssistantMessage`
-
-Assistant response message.
-
-```typescript
-type SDKAssistantMessage = {
-  type: "assistant";
-  uuid: UUID;
-  session_id: string;
-  message: APIAssistantMessage; // From Anthropic SDK
-  parent_tool_use_id: string | null;
-}
-```
-
-### `SDKUserMessage`
-
-User input message.
-
-```typescript
-type SDKUserMessage = {
-  type: "user";
-  uuid?: UUID;
-  session_id: string;
-  message: APIUserMessage; // From Anthropic SDK
-  parent_tool_use_id: string | null;
-}
-```
-
-### `SDKUserMessageReplay`
-
-Replayed user message with required UUID.
-
-```typescript
-type SDKUserMessageReplay = {
-  type: "user";
-  uuid: UUID;
-  session_id: string;
-  message: APIUserMessage;
-  parent_tool_use_id: string | null;
-}
-```
-
-### `SDKResultMessage`
-
-Final result message.
-
-```typescript
-type SDKResultMessage =
-  | {
-      type: "result";
-      subtype: "success";
-      uuid: UUID;
-      session_id: string;
-      duration_ms: number;
-      duration_api_ms: number;
-      is_error: boolean;
-      num_turns: number;
-      result: string;
-      total_cost_usd: number;
-      usage: NonNullableUsage;
-      modelUsage: { [modelName: string]: ModelUsage };
-      permission_denials: SDKPermissionDenial[];
-      structured_output?: unknown;
-    }
-  | {
-      type: "result";
-      subtype:
-        | "error_max_turns"
-        | "error_during_execution"
-        | "error_max_budget_usd"
-        | "error_max_structured_output_retries";
-      uuid: UUID;
-      session_id: string;
-      duration_ms: number;
-      duration_api_ms: number;
-      is_error: boolean;
-      num_turns: number;
-      total_cost_usd: number;
-      usage: NonNullableUsage;
-      modelUsage: { [modelName: string]: ModelUsage };
-      permission_denials: SDKPermissionDenial[];
-      errors: string[];
-    }
-```
-
-### `SDKSystemMessage`
-
-System initialization message.
-
-```typescript
-type SDKSystemMessage = {
-  type: "system";
-  subtype: "init";
-  uuid: UUID;
-  session_id: string;
-  apiKeySource: ApiKeySource;
-  cwd: string;
-  tools: string[];
-  mcp_servers: {
-    name: string;
-    status: string;
-  }[];
-  model: string;
-  permissionMode: PermissionMode;
-  slash_commands: string[];
-  output_style: string;
-}
-```
-
-### `SDKPartialAssistantMessage`
-
-Streaming partial message (only when `includePartialMessages` is true).
-
-```typescript
-type SDKPartialAssistantMessage = {
-  type: "stream_event";
-  event: RawMessageStreamEvent; // From Anthropic SDK
-  parent_tool_use_id: string | null;
-  uuid: UUID;
-  session_id: string;
-}
-```
-
-### `SDKCompactBoundaryMessage`
-
-Message indicating a conversation compaction boundary.
-
-```typescript
-type SDKCompactBoundaryMessage = {
-  type: "system";
-  subtype: "compact_boundary";
-  uuid: UUID;
-  session_id: string;
-  compact_metadata: {
-    trigger: "manual" | "auto";
-    pre_tokens: number;
-  };
-}
-```
-
-### `SDKPermissionDenial`
-
-Information about a denied tool use.
-
-```typescript
-type SDKPermissionDenial = {
-  tool_name: string;
-  tool_use_id: string;
-  tool_input: ToolInput;
-}
-```
-
-## Hook Types
-
-For a comprehensive guide on using hooks with examples and common patterns, see the [Hooks guide](/docs/en/agent-sdk/hooks).
-
-### `HookEvent`
-
-Available hook events.
-
-```typescript
-type HookEvent =
-  | "PreToolUse"
-  | "PostToolUse"
-  | "PostToolUseFailure"
-  | "Notification"
-  | "UserPromptSubmit"
-  | "SessionStart"
-  | "SessionEnd"
-  | "Stop"
-  | "SubagentStart"
-  | "SubagentStop"
-  | "PreCompact"
-  | "PermissionRequest";
-```
-
-### `HookCallback`
-
-Hook callback function type.
-
-```typescript
-type HookCallback = (
-  input: HookInput, // Union of all hook input types
-  toolUseID: string | undefined,
-  options: { signal: AbortSignal }
-) => Promise<HookJSONOutput>;
-```
-
-### `HookCallbackMatcher`
-
-Hook configuration with optional matcher.
-
-```typescript
-interface HookCallbackMatcher {
-  matcher?: string;
-  hooks: HookCallback[];
-}
-```
-
-### `HookInput`
-
-Union type of all hook input types.
-
-```typescript
-type HookInput =
-  | PreToolUseHookInput
-  | PostToolUseHookInput
-  | PostToolUseFailureHookInput
-  | NotificationHookInput
-  | UserPromptSubmitHookInput
-  | SessionStartHookInput
-  | SessionEndHookInput
-  | StopHookInput
-  | SubagentStartHookInput
-  | SubagentStopHookInput
-  | PreCompactHookInput
-  | PermissionRequestHookInput;
-```
-
-### `BaseHookInput`
-
-Base interface that all hook input types extend.
-
-```typescript
-type BaseHookInput = {
-  session_id: string;
-  transcript_path: string;
-  cwd: string;
-  permission_mode?: string;
-}
-```
-
-#### `PreToolUseHookInput`
-
-```typescript
-type PreToolUseHookInput = BaseHookInput & {
-  hook_event_name: "PreToolUse";
-  tool_name: string;
-  tool_input: unknown;
-}
-```
-
-#### `PostToolUseHookInput`
-
-```typescript
-type PostToolUseHookInput = BaseHookInput & {
-  hook_event_name: "PostToolUse";
-  tool_name: string;
-  tool_input: unknown;
-  tool_response: unknown;
-}
-```
-
-#### `PostToolUseFailureHookInput`
-
-```typescript
-type PostToolUseFailureHookInput = BaseHookInput & {
-  hook_event_name: "PostToolUseFailure";
-  tool_name: string;
-  tool_input: unknown;
-  error: string;
-  is_interrupt?: boolean;
-}
-```
-
-#### `NotificationHookInput`
-
-```typescript
-type NotificationHookInput = BaseHookInput & {
-  hook_event_name: "Notification";
-  message: string;
-  title?: string;
-}
-```
-
-#### `UserPromptSubmitHookInput`
-
-```typescript
-type UserPromptSubmitHookInput = BaseHookInput & {
-  hook_event_name: "UserPromptSubmit";
-  prompt: string;
-}
-```
-
-#### `SessionStartHookInput`
-
-```typescript
-type SessionStartHookInput = BaseHookInput & {
-  hook_event_name: "SessionStart";
-  source: "startup" | "resume" | "clear" | "compact";
-}
-```
-
-#### `SessionEndHookInput`
-
-```typescript
-type SessionEndHookInput = BaseHookInput & {
-  hook_event_name: "SessionEnd";
-  reason: ExitReason; // String from EXIT_REASONS array
-}
-```
-
-#### `StopHookInput`
-
-```typescript
-type StopHookInput = BaseHookInput & {
-  hook_event_name: "Stop";
-  stop_hook_active: boolean;
-}
-```
-
-#### `SubagentStartHookInput`
-
-```typescript
-type SubagentStartHookInput = BaseHookInput & {
-  hook_event_name: "SubagentStart";
-  agent_id: string;
-  agent_type: string;
-}
-```
-
-#### `SubagentStopHookInput`
-
-```typescript
-type SubagentStopHookInput = BaseHookInput & {
-  hook_event_name: "SubagentStop";
-  stop_hook_active: boolean;
-}
-```
-
-#### `PreCompactHookInput`
-
-```typescript
-type PreCompactHookInput = BaseHookInput & {
-  hook_event_name: "PreCompact";
-  trigger: "manual" | "auto";
-  custom_instructions: string | null;
-}
-```
-
-#### `PermissionRequestHookInput`
-
-```typescript
-type PermissionRequestHookInput = BaseHookInput & {
-  hook_event_name: "PermissionRequest";
-  tool_name: string;
-  tool_input: unknown;
-  permission_suggestions?: PermissionUpdate[];
-}
-```
-
-### `HookJSONOutput`
-
-Hook return value.
-
-```typescript
-type HookJSONOutput = AsyncHookJSONOutput | SyncHookJSONOutput;
-```
-
-#### `AsyncHookJSONOutput`
-
-```typescript
-type AsyncHookJSONOutput = {
-  async: true;
-  asyncTimeout?: number;
-}
-```
-
-#### `SyncHookJSONOutput`
-
-```typescript
-type SyncHookJSONOutput = {
-  continue?: boolean;
-  suppressOutput?: boolean;
-  stopReason?: string;
-  decision?: "approve" | "block";
-  systemMessage?: string;
-  reason?: string;
-  hookSpecificOutput?:
-    | {
-        hookEventName: "PreToolUse";
-        permissionDecision?: "allow" | "deny" | "ask";
-        permissionDecisionReason?: string;
-        updatedInput?: Record<string, unknown>;
-      }
-    | {
-        hookEventName: "UserPromptSubmit";
-        additionalContext?: string;
-      }
-    | {
-        hookEventName: "SessionStart";
-        additionalContext?: string;
-      }
-    | {
-        hookEventName: "PostToolUse";
-        additionalContext?: string;
-      };
-}
-```
-
-## Tool Input Types
-
-Documentation of input schemas for all built-in Claude Code tools. These types are exported from `@anthropic-ai/claude-agent-sdk` and can be used for type-safe tool interactions.
-
-### `ToolInput`
-
-**Note:** This is a documentation-only type for clarity. It represents the union of all tool input types.
-
-```typescript
-type ToolInput =
-  | AgentInput
-  | AskUserQuestionInput
-  | BashInput
-  | BashOutputInput
-  | FileEditInput
-  | FileReadInput
-  | FileWriteInput
-  | GlobInput
-  | GrepInput
-  | KillShellInput
-  | NotebookEditInput
-  | WebFetchInput
-  | WebSearchInput
-  | TodoWriteInput
-  | ExitPlanModeInput
-  | ListMcpResourcesInput
-  | ReadMcpResourceInput;
-```
-
-### Task
-
-**Tool name:** `Task`
-
-```typescript
-interface AgentInput {
-  /**
-   * A short (3-5 word) description of the task
-   */
-  description: string;
-  /**
-   * The task for the agent to perform
-   */
-  prompt: string;
-  /**
-   * The type of specialized agent to use for this task
-   */
-  subagent_type: string;
-}
-```
-
-Launches a new agent to handle complex, multi-step tasks autonomously.
-
-### AskUserQuestion
-
-**Tool name:** `AskUserQuestion`
-
-```typescript
-interface AskUserQuestionInput {
-  /**
-   * Questions to ask the user (1-4 questions)
-   */
-  questions: Array<{
-    /**
-     * The complete question to ask the user. Should be clear, specific,
-     * and end with a question mark.
-     */
-    question: string;
-    /**
-     * Very short label displayed as a chip/tag (max 12 chars).
-     * Examples: "Auth method", "Library", "Approach"
-     */
-    header: string;
-    /**
-     * The available choices (2-4 options). An "Other" option is
-     * automatically provided.
-     */
-    options: Array<{
-      /**
-       * Display text for this option (1-5 words)
-       */
-      label: string;
-      /**
-       * Explanation of what this option means
-       */
-      description: string;
-    }>;
-    /**
-     * Set to true to allow multiple selections
-     */
-    multiSelect: boolean;
-  }>;
-  /**
-   * User answers populated by the permission system.
-   * Maps question text to selected option label(s).
-   * Multi-select answers are comma-separated.
-   */
-  answers?: Record<string, string>;
-}
-```
-
-Asks the user clarifying questions during execution. See [Handle approvals and user input](/docs/en/agent-sdk/user-input#handle-clarifying-questions) for usage details.
-
-### Bash
-
-**Tool name:** `Bash`
-
-```typescript
-interface BashInput {
-  /**
-   * The command to execute
-   */
-  command: string;
-  /**
-   * Optional timeout in milliseconds (max 600000)
-   */
-  timeout?: number;
-  /**
-   * Clear, concise description of what this command does in 5-10 words
-   */
-  description?: string;
-  /**
-   * Set to true to run this command in the background
-   */
-  run_in_background?: boolean;
-}
-```
-
-Executes bash commands in a persistent shell session with optional timeout and background execution.
-
-### BashOutput
-
-**Tool name:** `BashOutput`
-
-```typescript
-interface BashOutputInput {
-  /**
-   * The ID of the background shell to retrieve output from
-   */
-  bash_id: string;
-  /**
-   * Optional regex to filter output lines
-   */
-  filter?: string;
-}
-```
-
-Retrieves output from a running or completed background bash shell.
-
-### Edit
-
-**Tool name:** `Edit`
-
-```typescript
-interface FileEditInput {
-  /**
-   * The absolute path to the file to modify
-   */
-  file_path: string;
-  /**
-   * The text to replace
-   */
-  old_string: string;
-  /**
-   * The text to replace it with (must be different from old_string)
-   */
-  new_string: string;
-  /**
-   * Replace all occurrences of old_string (default false)
-   */
-  replace_all?: boolean;
-}
-```
-
-Performs exact string replacements in files.
-
-### Read
-
-**Tool name:** `Read`
-
-```typescript
-interface FileReadInput {
-  /**
-   * The absolute path to the file to read
-   */
-  file_path: string;
-  /**
-   * The line number to start reading from
-   */
-  offset?: number;
-  /**
-   * The number of lines to read
-   */
-  limit?: number;
-}
-```
-
-Reads files from the local filesystem, including text, images, PDFs, and Jupyter notebooks.
-
-### Write
-
-**Tool name:** `Write`
-
-```typescript
-interface FileWriteInput {
-  /**
-   * The absolute path to the file to write
-   */
-  file_path: string;
-  /**
-   * The content to write to the file
-   */
-  content: string;
-}
-```
-
-Writes a file to the local filesystem, overwriting if it exists.
-
-### Glob
-
-**Tool name:** `Glob`
-
-```typescript
-interface GlobInput {
-  /**
-   * The glob pattern to match files against
-   */
-  pattern: string;
-  /**
-   * The directory to search in (defaults to cwd)
-   */
-  path?: string;
-}
-```
-
-Fast file pattern matching that works with any codebase size.
-
-### Grep
-
-**Tool name:** `Grep`
-
-```typescript
-interface GrepInput {
-  /**
-   * The regular expression pattern to search for
-   */
-  pattern: string;
-  /**
-   * File or directory to search in (defaults to cwd)
-   */
-  path?: string;
-  /**
-   * Glob pattern to filter files (e.g. "*.js")
-   */
-  glob?: string;
-  /**
-   * File type to search (e.g. "js", "py", "rust")
-   */
-  type?: string;
-  /**
-   * Output mode: "content", "files_with_matches", or "count"
-   */
-  output_mode?: "content" | "files_with_matches" | "count";
-  /**
-   * Case insensitive search
-   */
-  "-i"?: boolean;
-  /**
-   * Show line numbers (for content mode)
-   */
-  "-n"?: boolean;
-  /**
-   * Lines to show before each match
-   */
-  "-B"?: number;
-  /**
-   * Lines to show after each match
-   */
-  "-A"?: number;
-  /**
-   * Lines to show before and after each match
-   */
-  "-C"?: number;
-  /**
-   * Limit output to first N lines/entries
-   */
-  head_limit?: number;
-  /**
-   * Enable multiline mode
-   */
-  multiline?: boolean;
-}
-```
-
-Powerful search tool built on ripgrep with regex support.
-
-### KillBash
-
-**Tool name:** `KillBash`
-
-```typescript
-interface KillShellInput {
-  /**
-   * The ID of the background shell to kill
-   */
-  shell_id: string;
-}
-```
-
-Kills a running background bash shell by its ID.
-
-### NotebookEdit
-
-**Tool name:** `NotebookEdit`
-
-```typescript
-interface NotebookEditInput {
-  /**
-   * The absolute path to the Jupyter notebook file
-   */
-  notebook_path: string;
-  /**
-   * The ID of the cell to edit
-   */
-  cell_id?: string;
-  /**
-   * The new source for the cell
-   */
-  new_source: string;
-  /**
-   * The type of the cell (code or markdown)
-   */
-  cell_type?: "code" | "markdown";
-  /**
-   * The type of edit (replace, insert, delete)
-   */
-  edit_mode?: "replace" | "insert" | "delete";
-}
-```
-
-Edits cells in Jupyter notebook files.
-
-### WebFetch
-
-**Tool name:** `WebFetch`
-
-```typescript
-interface WebFetchInput {
-  /**
-   * The URL to fetch content from
-   */
-  url: string;
-  /**
-   * The prompt to run on the fetched content
-   */
-  prompt: string;
-}
-```
-
-Fetches content from a URL and processes it with an AI model.
-
-### WebSearch
-
-**Tool name:** `WebSearch`
-
-```typescript
-interface WebSearchInput {
-  /**
-   * The search query to use
-   */
-  query: string;
-  /**
-   * Only include results from these domains
-   */
-  allowed_domains?: string[];
-  /**
-   * Never include results from these domains
-   */
-  blocked_domains?: string[];
-}
-```
-
-Searches the web and returns formatted results.
-
-### TodoWrite
-
-**Tool name:** `TodoWrite`
-
-```typescript
-interface TodoWriteInput {
-  /**
-   * The updated todo list
-   */
-  todos: Array<{
-    /**
-     * The task description
-     */
-    content: string;
-    /**
-     * The task status
-     */
-    status: "pending" | "in_progress" | "completed";
-    /**
-     * Active form of the task description
-     */
-    activeForm: string;
-  }>;
-}
-```
-
-Creates and manages a structured task list for tracking progress.
-
-### ExitPlanMode
-
-**Tool name:** `ExitPlanMode`
-
-```typescript
-interface ExitPlanModeInput {
-  /**
-   * The plan to run by the user for approval
-   */
-  plan: string;
-}
-```
-
-Exits planning mode and prompts the user to approve the plan.
-
-### ListMcpResources
-
-**Tool name:** `ListMcpResources`
-
-```typescript
-interface ListMcpResourcesInput {
-  /**
-   * Optional server name to filter resources by
-   */
-  server?: string;
-}
-```
-
-Lists available MCP resources from connected servers.
-
-### ReadMcpResource
-
-**Tool name:** `ReadMcpResource`
-
-```typescript
-interface ReadMcpResourceInput {
-  /**
-   * The MCP server name
-   */
-  server: string;
-  /**
-   * The resource URI to read
-   */
-  uri: string;
-}
-```
-
-Reads a specific MCP resource from a server.
-
-## Tool Output Types
-
-Documentation of output schemas for all built-in Claude Code tools. These types represent the actual response data returned by each tool.
-
-### `ToolOutput`
-
-**Note:** This is a documentation-only type for clarity. It represents the union of all tool output types.
-
-```typescript
-type ToolOutput =
-  | TaskOutput
-  | AskUserQuestionOutput
-  | BashOutput
-  | BashOutputToolOutput
-  | EditOutput
-  | ReadOutput
-  | WriteOutput
-  | GlobOutput
-  | GrepOutput
-  | KillBashOutput
-  | NotebookEditOutput
-  | WebFetchOutput
-  | WebSearchOutput
-  | TodoWriteOutput
-  | ExitPlanModeOutput
-  | ListMcpResourcesOutput
-  | ReadMcpResourceOutput;
-```
-
-### Task
-
-**Tool name:** `Task`
-
-```typescript
-interface TaskOutput {
-  /**
-   * Final result message from the subagent
-   */
-  result: string;
-  /**
-   * Token usage statistics
-   */
-  usage?: {
-    input_tokens: number;
-    output_tokens: number;
-    cache_creation_input_tokens?: number;
-    cache_read_input_tokens?: number;
-  };
-  /**
-   * Total cost in USD
-   */
-  total_cost_usd?: number;
-  /**
-   * Execution duration in milliseconds
-   */
-  duration_ms?: number;
-}
-```
-
-Returns the final result from the subagent after completing the delegated task.
-
-### AskUserQuestion
-
-**Tool name:** `AskUserQuestion`
-
-```typescript
-interface AskUserQuestionOutput {
-  /**
-   * The questions that were asked
-   */
-  questions: Array<{
-    question: string;
-    header: string;
-    options: Array<{
-      label: string;
-      description: string;
-    }>;
-    multiSelect: boolean;
-  }>;
-  /**
-   * The answers provided by the user.
-   * Maps question text to answer string.
-   * Multi-select answers are comma-separated.
-   */
-  answers: Record<string, string>;
-}
-```
-
-Returns the questions asked and the user's answers.
-
-### Bash
-
-**Tool name:** `Bash`
-
-```typescript
-interface BashOutput {
-  /**
-   * Combined stdout and stderr output
-   */
-  output: string;
-  /**
-   * Exit code of the command
-   */
-  exitCode: number;
-  /**
-   * Whether the command was killed due to timeout
-   */
-  killed?: boolean;
-  /**
-   * Shell ID for background processes
-   */
-  shellId?: string;
-}
-```
-
-Returns command output with exit status. Background commands return immediately with a shellId.
-
-### BashOutput
-
-**Tool name:** `BashOutput`
-
-```typescript
-interface BashOutputToolOutput {
-  /**
-   * New output since last check
-   */
-  output: string;
-  /**
-   * Current shell status
-   */
-  status: "running" | "completed" | "failed";
-  /**
-   * Exit code (when completed)
-   */
-  exitCode?: number;
-}
-```
-
-Returns incremental output from background shells.
-
-### Edit
-
-**Tool name:** `Edit`
-
-```typescript
-interface EditOutput {
-  /**
-   * Confirmation message
-   */
-  message: string;
-  /**
-   * Number of replacements made
-   */
-  replacements: number;
-  /**
-   * File path that was edited
-   */
-  file_path: string;
-}
-```
-
-Returns confirmation of successful edits with replacement count.
-
-### Read
-
-**Tool name:** `Read`
-
-```typescript
-type ReadOutput =
-  | TextFileOutput
-  | ImageFileOutput
-  | PDFFileOutput
-  | NotebookFileOutput;
-
-interface TextFileOutput {
-  /**
-   * File contents with line numbers
-   */
-  content: string;
-  /**
-   * Total number of lines in file
-   */
-  total_lines: number;
-  /**
-   * Lines actually returned
-   */
-  lines_returned: number;
-}
-
-interface ImageFileOutput {
-  /**
-   * Base64 encoded image data
-   */
-  image: string;
-  /**
-   * Image MIME type
-   */
-  mime_type: string;
-  /**
-   * File size in bytes
-   */
-  file_size: number;
-}
-
-interface PDFFileOutput {
-  /**
-   * Array of page contents
-   */
-  pages: Array<{
-    page_number: number;
-    text?: string;
-    images?: Array<{
-      image: string;
-      mime_type: string;
-    }>;
-  }>;
-  /**
-   * Total number of pages
-   */
-  total_pages: number;
-}
-
-interface NotebookFileOutput {
-  /**
-   * Jupyter notebook cells
-   */
-  cells: Array<{
-    cell_type: "code" | "markdown";
-    source: string;
-    outputs?: any[];
-    execution_count?: number;
-  }>;
-  /**
-   * Notebook metadata
-   */
-  metadata?: Record<string, any>;
-}
-```
-
-Returns file contents in format appropriate to file type.
-
-### Write
-
-**Tool name:** `Write`
-
-```typescript
-interface WriteOutput {
-  /**
-   * Success message
-   */
-  message: string;
-  /**
-   * Number of bytes written
-   */
-  bytes_written: number;
-  /**
-   * File path that was written
-   */
-  file_path: string;
-}
-```
-
-Returns confirmation after successfully writing the file.
-
-### Glob
-
-**Tool name:** `Glob`
-
-```typescript
-interface GlobOutput {
-  /**
-   * Array of matching file paths
-   */
-  matches: string[];
-  /**
-   * Number of matches found
-   */
-  count: number;
-  /**
-   * Search directory used
-   */
-  search_path: string;
-}
-```
-
-Returns file paths matching the glob pattern, sorted by modification time.
-
-### Grep
-
-**Tool name:** `Grep`
-
-```typescript
-type GrepOutput =
-  | GrepContentOutput
-  | GrepFilesOutput
-  | GrepCountOutput;
-
-interface GrepContentOutput {
-  /**
-   * Matching lines with context
-   */
-  matches: Array<{
-    file: string;
-    line_number?: number;
-    line: string;
-    before_context?: string[];
-    after_context?: string[];
-  }>;
-  /**
-   * Total number of matches
-   */
-  total_matches: number;
-}
-
-interface GrepFilesOutput {
-  /**
-   * Files containing matches
-   */
-  files: string[];
-  /**
-   * Number of files with matches
-   */
-  count: number;
-}
-
-interface GrepCountOutput {
-  /**
-   * Match counts per file
-   */
-  counts: Array<{
-    file: string;
-    count: number;
-  }>;
-  /**
-   * Total matches across all files
-   */
-  total: number;
-}
-```
-
-Returns search results in the format specified by output_mode.
-
-### KillBash
-
-**Tool name:** `KillBash`
-
-```typescript
-interface KillBashOutput {
-  /**
-   * Success message
-   */
-  message: string;
-  /**
-   * ID of the killed shell
-   */
-  shell_id: string;
-}
-```
-
-Returns confirmation after terminating the background shell.
-
-### NotebookEdit
-
-**Tool name:** `NotebookEdit`
-
-```typescript
-interface NotebookEditOutput {
-  /**
-   * Success message
-   */
-  message: string;
-  /**
-   * Type of edit performed
-   */
-  edit_type: "replaced" | "inserted" | "deleted";
-  /**
-   * Cell ID that was affected
-   */
-  cell_id?: string;
-  /**
-   * Total cells in notebook after edit
-   */
-  total_cells: number;
-}
-```
-
-Returns confirmation after modifying the Jupyter notebook.
-
-### WebFetch
-
-**Tool name:** `WebFetch`
-
-```typescript
-interface WebFetchOutput {
-  /**
-   * AI model's response to the prompt
-   */
-  response: string;
-  /**
-   * URL that was fetched
-   */
-  url: string;
-  /**
-   * Final URL after redirects
-   */
-  final_url?: string;
-  /**
-   * HTTP status code
-   */
-  status_code?: number;
-}
-```
-
-Returns the AI's analysis of the fetched web content.
-
-### WebSearch
-
-**Tool name:** `WebSearch`
-
-```typescript
-interface WebSearchOutput {
-  /**
-   * Search results
-   */
-  results: Array<{
-    title: string;
-    url: string;
-    snippet: string;
-    /**
-     * Additional metadata if available
-     */
-    metadata?: Record<string, any>;
-  }>;
-  /**
-   * Total number of results
-   */
-  total_results: number;
-  /**
-   * The query that was searched
-   */
-  query: string;
-}
-```
-
-Returns formatted search results from the web.
-
-### TodoWrite
-
-**Tool name:** `TodoWrite`
-
-```typescript
-interface TodoWriteOutput {
-  /**
-   * Success message
-   */
-  message: string;
-  /**
-   * Current todo statistics
-   */
-  stats: {
-    total: number;
-    pending: number;
-    in_progress: number;
-    completed: number;
-  };
-}
-```
-
-Returns confirmation with current task statistics.
-
-### ExitPlanMode
-
-**Tool name:** `ExitPlanMode`
-
-```typescript
-interface ExitPlanModeOutput {
-  /**
-   * Confirmation message
-   */
-  message: string;
-  /**
-   * Whether user approved the plan
-   */
-  approved?: boolean;
-}
-```
-
-Returns confirmation after exiting plan mode.
-
-### ListMcpResources
-
-**Tool name:** `ListMcpResources`
-
-```typescript
-interface ListMcpResourcesOutput {
-  /**
-   * Available resources
-   */
-  resources: Array<{
-    uri: string;
-    name: string;
-    description?: string;
-    mimeType?: string;
-    server: string;
-  }>;
-  /**
-   * Total number of resources
-   */
-  total: number;
-}
-```
-
-Returns list of available MCP resources.
-
-### ReadMcpResource
-
-**Tool name:** `ReadMcpResource`
-
-```typescript
-interface ReadMcpResourceOutput {
-  /**
-   * Resource contents
-   */
-  contents: Array<{
-    uri: string;
-    mimeType?: string;
-    text?: string;
-    blob?: string;
-  }>;
-  /**
-   * Server that provided the resource
-   */
-  server: string;
-}
-```
-
-Returns the contents of the requested MCP resource.
-
-## Permission Types
-
-### `PermissionUpdate`
-
-Operations for updating permissions.
-
-```typescript
-type PermissionUpdate =
-  | {
-      type: "addRules";
-      rules: PermissionRuleValue[];
-      behavior: PermissionBehavior;
-      destination: PermissionUpdateDestination;
-    }
-  | {
-      type: "replaceRules";
-      rules: PermissionRuleValue[];
-      behavior: PermissionBehavior;
-      destination: PermissionUpdateDestination;
-    }
-  | {
-      type: "removeRules";
-      rules: PermissionRuleValue[];
-      behavior: PermissionBehavior;
-      destination: PermissionUpdateDestination;
-    }
-  | {
-      type: "setMode";
-      mode: PermissionMode;
-      destination: PermissionUpdateDestination;
-    }
-  | {
-      type: "addDirectories";
-      directories: string[];
-      destination: PermissionUpdateDestination;
-    }
-  | {
-      type: "removeDirectories";
-      directories: string[];
-      destination: PermissionUpdateDestination;
-    }
-```
-
-### `PermissionBehavior`
-
-```typescript
-type PermissionBehavior = "allow" | "deny" | "ask";
-```
-
-### `PermissionUpdateDestination`
-
-```typescript
-type PermissionUpdateDestination =
-  | "userSettings" // Global user settings
-  | "projectSettings" // Per-directory project settings
-  | "localSettings" // Gitignored local settings
-  | "session" // Current session only
-```
-
-### `PermissionRuleValue`
-
-```typescript
-type PermissionRuleValue = {
-  toolName: string;
-  ruleContent?: string;
-}
-```
-
-## Other Types
-
-### `ApiKeySource`
-
-```typescript
-type ApiKeySource = "user" | "project" | "org" | "temporary";
-```
-
-### `SdkBeta`
-
-Available beta features that can be enabled via the `betas` option. See [Beta headers](/docs/en/api/beta-headers) for more information.
-
-```typescript
-type SdkBeta = "context-1m-2025-08-07";
-```
-
-| Value | Description | Compatible Models |
-|:------|:------------|:------------------|
-| `'context-1m-2025-08-07'` | Enables 1 million token [context window](/docs/en/build-with-claude/context-windows) | Claude Opus 4.6, Claude Sonnet 4.5, Claude Sonnet 4 |
-
-### `SlashCommand`
-
-Information about an available slash command.
-
-```typescript
-type SlashCommand = {
-  name: string;
-  description: string;
-  argumentHint: string;
-}
-```
-
-### `ModelInfo`
-
-Information about an available model.
-
-```typescript
-type ModelInfo = {
-  value: string;
-  displayName: string;
-  description: string;
-}
-```
-
-### `McpServerStatus`
-
-Status of a connected MCP server.
-
-```typescript
-type McpServerStatus = {
-  name: string;
-  status: "connected" | "failed" | "needs-auth" | "pending";
-  serverInfo?: {
-    name: string;
-    version: string;
-  };
-}
-```
-
-### `AccountInfo`
-
-Account information for the authenticated user.
-
-```typescript
-type AccountInfo = {
-  email?: string;
-  organization?: string;
-  subscriptionType?: string;
-  tokenSource?: string;
-  apiKeySource?: string;
-}
-```
-
-### `ModelUsage`
-
-Per-model usage statistics returned in result messages.
-
-```typescript
-type ModelUsage = {
-  inputTokens: number;
-  outputTokens: number;
-  cacheReadInputTokens: number;
-  cacheCreationInputTokens: number;
-  webSearchRequests: number;
-  costUSD: number;
-  contextWindow: number;
-}
-```
-
-### `ConfigScope`
-
-```typescript
-type ConfigScope = "local" | "user" | "project";
-```
-
-### `NonNullableUsage`
-
-A version of [`Usage`](#usage) with all nullable fields made non-nullable.
-
-```typescript
-type NonNullableUsage = {
-  [K in keyof Usage]: NonNullable<Usage[K]>;
-}
-```
-
-### `Usage`
-
-Token usage statistics (from `@anthropic-ai/sdk`).
-
-```typescript
-type Usage = {
-  input_tokens: number | null;
-  output_tokens: number | null;
-  cache_creation_input_tokens?: number | null;
-  cache_read_input_tokens?: number | null;
-}
-```
-
-### `CallToolResult`
-
-MCP tool result type (from `@modelcontextprotocol/sdk/types.js`).
-
-```typescript
-type CallToolResult = {
-  content: Array<{
-    type: "text" | "image" | "resource";
-    // Additional fields vary by type
-  }>;
-  isError?: boolean;
-}
-```
-
-### `AbortError`
-
-Custom error class for abort operations.
-
-```typescript
-class AbortError extends Error {}
-```
-
-## Sandbox Configuration
-
-### `SandboxSettings`
-
-Configuration for sandbox behavior. Use this to enable command sandboxing and configure network restrictions programmatically.
-
-```typescript
-type SandboxSettings = {
-  enabled?: boolean;
-  autoAllowBashIfSandboxed?: boolean;
-  excludedCommands?: string[];
-  allowUnsandboxedCommands?: boolean;
-  network?: NetworkSandboxSettings;
-  ignoreViolations?: SandboxIgnoreViolations;
-  enableWeakerNestedSandbox?: boolean;
-}
-```
-
-| Property | Type | Default | Description |
-| :------- | :--- | :------ | :---------- |
-| `enabled` | `boolean` | `false` | Enable sandbox mode for command execution |
-| `autoAllowBashIfSandboxed` | `boolean` | `false` | Auto-approve bash commands when sandbox is enabled |
-| `excludedCommands` | `string[]` | `[]` | Commands that always bypass sandbox restrictions (e.g., `['docker']`). These run unsandboxed automatically without model involvement |
-| `allowUnsandboxedCommands` | `boolean` | `false` | Allow the model to request running commands outside the sandbox. When `true`, the model can set `dangerouslyDisableSandbox` in tool input, which falls back to the [permissions system](#permissions-fallback-for-unsandboxed-commands) |
-| `network` | [`NetworkSandboxSettings`](#networksandboxsettings) | `undefined` | Network-specific sandbox configuration |
-| `ignoreViolations` | [`SandboxIgnoreViolations`](#sandboxignoreviolations) | `undefined` | Configure which sandbox violations to ignore |
-| `enableWeakerNestedSandbox` | `boolean` | `false` | Enable a weaker nested sandbox for compatibility |
-
-<Note>
-**Filesystem and network access restrictions** are NOT configured via sandbox settings. Instead, they are derived from [permission rules](https://code.claude.com/docs/en/settings#permission-settings):
-
-- **Filesystem read restrictions**: Read deny rules
-- **Filesystem write restrictions**: Edit allow/deny rules
-- **Network restrictions**: WebFetch allow/deny rules
-
-Use sandbox settings for command execution sandboxing, and permission rules for filesystem and network access control.
-</Note>
-
-#### Example usage
-
-```typescript
-import { query } from "@anthropic-ai/claude-agent-sdk";
-
-const result = await query({
-  prompt: "Build and test my project",
-  options: {
-    sandbox: {
-      enabled: true,
-      autoAllowBashIfSandboxed: true,
-      network: {
-        allowLocalBinding: true
-      }
-    }
-  }
-});
-```
-
-<Warning>
-**Unix socket security**: The `allowUnixSockets` option can grant access to powerful system services. For example, allowing `/var/run/docker.sock` effectively grants full host system access through the Docker API, bypassing sandbox isolation. Only allow Unix sockets that are strictly necessary and understand the security implications of each.
-</Warning>
-
-### `NetworkSandboxSettings`
-
-Network-specific configuration for sandbox mode.
-
-```typescript
-type NetworkSandboxSettings = {
-  allowLocalBinding?: boolean;
-  allowUnixSockets?: string[];
-  allowAllUnixSockets?: boolean;
-  httpProxyPort?: number;
-  socksProxyPort?: number;
-}
-```
-
-| Property | Type | Default | Description |
-| :------- | :--- | :------ | :---------- |
-| `allowLocalBinding` | `boolean` | `false` | Allow processes to bind to local ports (e.g., for dev servers) |
-| `allowUnixSockets` | `string[]` | `[]` | Unix socket paths that processes can access (e.g., Docker socket) |
-| `allowAllUnixSockets` | `boolean` | `false` | Allow access to all Unix sockets |
-| `httpProxyPort` | `number` | `undefined` | HTTP proxy port for network requests |
-| `socksProxyPort` | `number` | `undefined` | SOCKS proxy port for network requests |
-
-### `SandboxIgnoreViolations`
-
-Configuration for ignoring specific sandbox violations.
-
-```typescript
-type SandboxIgnoreViolations = {
-  file?: string[];
-  network?: string[];
-}
-```
-
-| Property | Type | Default | Description |
-| :------- | :--- | :------ | :---------- |
-| `file` | `string[]` | `[]` | File path patterns to ignore violations for |
-| `network` | `string[]` | `[]` | Network patterns to ignore violations for |
-
-### Permissions Fallback for Unsandboxed Commands
-
-When `allowUnsandboxedCommands` is enabled, the model can request to run commands outside the sandbox by setting `dangerouslyDisableSandbox: true` in the tool input. These requests fall back to the existing permissions system, meaning your `canUseTool` handler will be invoked, allowing you to implement custom authorization logic.
-
-<Note>
-**`excludedCommands` vs `allowUnsandboxedCommands`:**
-- `excludedCommands`: A static list of commands that always bypass the sandbox automatically (e.g., `['docker']`). The model has no control over this.
-- `allowUnsandboxedCommands`: Lets the model decide at runtime whether to request unsandboxed execution by setting `dangerouslyDisableSandbox: true` in the tool input.
-</Note>
-
-```typescript
-import { query } from "@anthropic-ai/claude-agent-sdk";
-
-const result = await query({
-  prompt: "Deploy my application",
-  options: {
-    sandbox: {
-      enabled: true,
-      allowUnsandboxedCommands: true // Model can request unsandboxed execution
-    },
-    permissionMode: "default",
-    canUseTool: async (tool, input) => {
-      // Check if the model is requesting to bypass the sandbox
-      if (tool === "Bash" && input.dangerouslyDisableSandbox) {
-        // The model wants to run this command outside the sandbox
-        console.log(`Unsandboxed command requested: ${input.command}`);
-
-        // Return true to allow, false to deny
-        return isCommandAuthorized(input.command);
-      }
-      return true;
-    }
-  }
-});
-```
-
-This pattern enables you to:
-
-- **Audit model requests**: Log when the model requests unsandboxed execution
-- **Implement allowlists**: Only permit specific commands to run unsandboxed
-- **Add approval workflows**: Require explicit authorization for privileged operations
-
-<Warning>
-Commands running with `dangerouslyDisableSandbox: true` have full system access. Ensure your `canUseTool` handler validates these requests carefully.
-
-If `permissionMode` is set to `bypassPermissions` and `allowUnsandboxedCommands` is enabled, the model can autonomously execute commands outside the sandbox without any approval prompts. This combination effectively allows the model to escape sandbox isolation silently.
-</Warning>
-
-## See also
-
-- [SDK overview](/docs/en/agent-sdk/overview) - General SDK concepts
-- [Python SDK reference](/docs/en/agent-sdk/python) - Python SDK documentation
-- [CLI reference](https://code.claude.com/docs/en/cli-reference) - Command-line interface
-- [Common workflows](https://code.claude.com/docs/en/common-workflows) - Step-by-step guides
diff --git a/docs/e2e-testing.md b/docs/e2e-testing.md
index 60b8e83791..4beabb4e5b 100644
--- a/docs/e2e-testing.md
+++ b/docs/e2e-testing.md
@@ -18,8 +18,10 @@ Tip: This guide is window-based. In `REMOTE` mode, `tmux-cli launch` creates a n
 
 2. **Set environment variables:**
 
+These env vars come from the parent session, not the `tmux-cli` session:
+
     ```bash
-    export ATOMIC_PROJECT_DIR=~/Documents/projects/atomic
+    export ATOMIC_PROJECT_DIR=$PWD
     ```
 
 3. **Create a screenshots directory:**
@@ -42,17 +44,44 @@ Tip: This guide is window-based. In `REMOTE` mode, `tmux-cli launch` creates a n
 
     - If it prints `MODE: REMOTE ...`, create windows with:
 
-      ```bash
-      tmux-cli launch "zsh"
-      ```
+        ```bash
+        tmux-cli launch "zsh"
+        ```
 
     - If it prints `MODE: LOCAL ...`, create windows with:
 
-      ```bash
-      tmux new-window -P -F '#S:#I.0' -n atomic-e2e "zsh"
-      ```
+        ```bash
+        tmux new-window -P -F '#S:#I.0' -n atomic-e2e "zsh"
+        ```
+
+        Use the returned pane target (for example, `dev:3.0`) as `WINDOW_ID` for all `tmux-cli send/capture/wait_idle/kill` commands.
+
+6. **Initialize atomic-e2e project directory:**
+
+    ```bash
+    mkdir -p /tmp/snake_game/claude
+    mkdir -p /tmp/snake_game/opencode
+    mkdir -p /tmp/snake_game/copilot
+    ```
+
+    Note: when you first run the TUI, it will prompt you for configuration. Use `GitHub / Git` as the source control system and confirm with `Yes` to configure in the agent's directory (e.g., `/tmp/snake_game/claude`). This is required to enable source control tool calls that the agents rely on for file editing and creation. You only need to do this once per agent; the configuration will be saved for future runs in the same local folder:
 
-      Use the returned pane target (for example, `dev:3.0`) as `WINDOW_ID` for all `tmux-cli send/capture/wait_idle/kill` commands.
+    ```
+    ┌  Atomic: Automated Procedures and Memory for AI Coding Agents
+    │
+    │  Enable multi-hour autonomous coding sessions with the Ralph Wiggum
+    │  Method using research, plan, implement methodology.
+    │
+    ●  Source control skills are not configured for Claude. Starting interactive setup...
+    │
+    ●  Configuring Claude Code...
+    │
+    ◇  Select your source control system:
+    │  GitHub / Git
+    │
+    ◇  Configure Claude Code source control skills in /tmp/snake_game/claude?
+    │  Yes
+    ```
 
 ---
 
@@ -162,19 +191,19 @@ The polling captures transient UI states (tool status transitions, spinner anima
 
 ### `tmux-cli` Command Reference
 
-| Command                                            | Description                                                    |
-| -------------------------------------------------- | -------------------------------------------------------------- |
-| `tmux-cli launch "cmd"`                            | Launches in a new window when `MODE: REMOTE`. **Always launch `zsh` first.** |
-| `tmux new-window -P -F '#S:#I.0' -n name "cmd"`   | Creates a new window when `MODE: LOCAL`; use the returned `session:window.pane` as `WINDOW_ID`. |
-| `tmux-cli send "text" --pane=ID`                   | Send text + Enter to a window's main pane                      |
-| `tmux-cli send "text" --pane=ID --enter=False`     | Send text without pressing Enter                               |
-| `tmux-cli send "text" --pane=ID --delay-enter=0.5` | Custom delay before Enter (seconds)                            |
-| `tmux-cli capture --pane=ID`                       | Capture output from a window's main pane                       |
-| `tmux-cli wait_idle --pane=ID --idle-time=3.0`     | Wait until output is idle for N seconds                        |
-| `tmux-cli status`                                  | Show current tmux location and targets                         |
-| `tmux-cli list_windows`                            | List windows in the managed remote session                     |
-| `tmux-cli kill --pane=ID`                          | Kill a window by targeting its `WINDOW_ID`                     |
-| `tmux-cli help`                                    | Show full help documentation                                   |
+| Command                                            | Description                                                                                     |
+| -------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `tmux-cli launch "[cmd]"`                          | Launches in a new window when `MODE: REMOTE`. **Always launch `zsh` first.**                    |
+| `tmux new-window -P -F '#S:#I.0' -n name "[cmd]"`  | Creates a new window when `MODE: LOCAL`; use the returned `session:window.pane` as `WINDOW_ID`. |
+| `tmux-cli send "text" --pane=ID`                   | Send text + Enter to a window's main pane                                                       |
+| `tmux-cli send "text" --pane=ID --enter=False`     | Send text without pressing Enter                                                                |
+| `tmux-cli send "text" --pane=ID --delay-enter=0.5` | Custom delay before Enter (seconds)                                                             |
+| `tmux-cli capture --pane=ID`                       | Capture output from a window's main pane                                                        |
+| `tmux-cli wait_idle --pane=ID --idle-time=3.0`     | Wait until output is idle for N seconds                                                         |
+| `tmux-cli status`                                  | Show current tmux location and targets                                                          |
+| `tmux-cli list_windows`                            | List windows in the managed remote session                                                      |
+| `tmux-cli kill --pane=ID`                          | Kill a window by targeting its `WINDOW_ID`                                                      |
+| `tmux-cli help`                                    | Show full help documentation                                                                    |
 
 ### When You Find a Bug
 
@@ -348,7 +377,7 @@ tmux-cli capture --pane=<WINDOW_ID> > $ATOMIC_PROJECT_DIR/tmux-screenshots/<AGEN
 
 #### 3.3 — Message Queuing (Cmd/Ctrl+Shift+Enter)
 
-While the agent is still streaming from the previous step (or send a new long prompt), test message queuing:
+While the agent is still streaming from the previous step (or send a new long prompt), test message queuing. The queue enqueue shortcut is **Cmd+Shift+Enter** on macOS and **Ctrl+Shift+Enter** on Linux/Windows.
 
 ```bash
 POLL_PID=$(start_polling <WINDOW_ID> <AGENT> 10-message-queue)
@@ -356,13 +385,21 @@ POLL_PID=$(start_polling <WINDOW_ID> <AGENT> 10-message-queue)
 # Send a prompt that will trigger a long response
 tmux-cli send "Add a high score system that persists to a file called highscores.txt, and add a pause feature with the P key." --pane=<WINDOW_ID>
 
-# Immediately queue a follow-up message
-# - macOS: Cmd+Shift+Enter (typically \x1b[13;10u in modifyOtherKeys terminals)
-# - Linux/Windows: Ctrl+Shift+Enter (typically \x1b[13;6u)
+# Wait for streaming to start, then type a follow-up and enqueue it
+# Ctrl+Shift+Enter escape sequence: \x1b[13;6u (Linux/Windows)
+# Cmd+Shift+Enter escape sequence: \x1b[13;10u (macOS)
 sleep 2
+tmux-cli send "Also add a speed increase every 5 points to make the game progressively harder." --pane=<WINDOW_ID> --enter=False
+sleep 0.3
 tmux-cli send $'\x1b[13;6u' --pane=<WINDOW_ID> --enter=False
-sleep 0.5
-tmux-cli send "Also add a speed increase every 5 points to make the game progressively harder." --pane=<WINDOW_ID>
+
+# Capture while streaming to verify queue indicator
+sleep 2
+tmux-cli capture --pane=<WINDOW_ID> > $ATOMIC_PROJECT_DIR/tmux-screenshots/<AGENT>-10-message-queue-during-stream.txt
+
+# Queue a second message
+tmux-cli send "And add a game-over animation when the snake dies." --pane=<WINDOW_ID> --enter=False
+sleep 0.3
 tmux-cli send $'\x1b[13;6u' --pane=<WINDOW_ID> --enter=False
 
 tmux-cli wait_idle --pane=<WINDOW_ID> --idle-time=15.0
@@ -372,9 +409,60 @@ tmux-cli capture --pane=<WINDOW_ID> > $ATOMIC_PROJECT_DIR/tmux-screenshots/<AGEN
 
 **Verify:**
 
-- Queue indicator appears in footer (e.g., "1 queued")
-- Input placeholder changes to streaming mode text
-- Queued message processes automatically after the first response completes
+- **Queue indicator** appears above the chatbox showing queue icon, count text ("1 message queued" / "2 messages queued"), and a preview of the first queued message
+- **Footer during streaming** shows: `esc to interrupt · ctrl+shift+enter enqueue`
+- **Chatbox placeholder** changes to `"Type a message (enter to interrupt, ctrl+shift+enter to enqueue)..."` while streaming
+- **Auto-dispatch**: After the first response completes, the next queued message is automatically dispatched (50ms delay) without user intervention
+- **Sequential processing**: All queued messages process one-by-one in FIFO order
+
+#### 3.3.1 — Queue Editing (Up/Down Arrows)
+
+After queuing messages, test editing them before they dispatch:
+
+```bash
+POLL_PID=$(start_polling <WINDOW_ID> <AGENT> 10b-queue-edit)
+
+# Send a long prompt to start streaming
+tmux-cli send "Write unit tests for every function in the snake game module." --pane=<WINDOW_ID>
+sleep 2
+
+# Queue two messages
+tmux-cli send "Fix any compilation warnings." --pane=<WINDOW_ID> --enter=False
+sleep 0.3
+tmux-cli send $'\x1b[13;6u' --pane=<WINDOW_ID> --enter=False
+tmux-cli send "Run cargo clippy." --pane=<WINDOW_ID> --enter=False
+sleep 0.3
+tmux-cli send $'\x1b[13;6u' --pane=<WINDOW_ID> --enter=False
+
+# Wait for streaming to complete so we can edit the queue
+tmux-cli wait_idle --pane=<WINDOW_ID> --idle-time=10.0
+
+# Press Up arrow to enter queue edit mode (loads last queued message into textarea)
+tmux-cli send $'\x1b[A' --pane=<WINDOW_ID> --enter=False
+sleep 1
+tmux-cli capture --pane=<WINDOW_ID> > $ATOMIC_PROJECT_DIR/tmux-screenshots/<AGENT>-10b-queue-edit-last.txt
+
+# Press Up again to navigate to the previous queued message
+tmux-cli send $'\x1b[A' --pane=<WINDOW_ID> --enter=False
+sleep 1
+tmux-cli capture --pane=<WINDOW_ID> > $ATOMIC_PROJECT_DIR/tmux-screenshots/<AGENT>-10b-queue-edit-first.txt
+
+# Press Down past last message to exit edit mode
+tmux-cli send $'\x1b[B\x1b[B' --pane=<WINDOW_ID> --enter=False
+sleep 1
+
+tmux-cli wait_idle --pane=<WINDOW_ID> --idle-time=10.0
+stop_polling $POLL_PID
+tmux-cli capture --pane=<WINDOW_ID> > $ATOMIC_PROJECT_DIR/tmux-screenshots/<AGENT>-10b-queue-edit-final.txt
+```
+
+**Verify:**
+
+- **Up arrow** with queued messages enters edit mode — last queued message content loads into textarea
+- **Queue indicator expands** to non-compact mode: shows numbered list of queued messages, currently editing message highlighted with `›` prefix and accent color
+- **Up/Down arrows** navigate between queued messages, auto-saving edits on navigation
+- **Down past last message** exits edit mode and clears the textarea
+- **Placeholder** shows `"Press ↑ to edit queued messages..."` when queue is non-empty and not streaming
 
 #### 3.4 — Build & Compile (Bash Tool Verification)
 
@@ -460,7 +548,7 @@ tmux-cli capture --pane=<WINDOW_ID> > $ATOMIC_PROJECT_DIR/tmux-screenshots/<AGEN
 
 ### Phase 5: Agent & Skill Invocation
 
-#### 5.1 — Sub-Agent Invocation (`@agent`)
+#### 5.1 — Foreground Sub-Agent Invocation (`@agent`)
 
 ```bash
 POLL_PID=$(start_polling <WINDOW_ID> <AGENT> 19-agent-debugger)
@@ -470,11 +558,106 @@ stop_polling $POLL_PID
 tmux-cli capture --pane=<WINDOW_ID> > $ATOMIC_PROJECT_DIR/tmux-screenshots/<AGENT>-19-agent-debugger-final.txt
 ```
 
+Spawn parallel sub-agents as well:
+
+```bash
+POLL_PID=$(start_polling <WINDOW_ID> <AGENT> 20-parallel-agents)
+tmux-cli send "@debugger run cargo check and fix any issues. @reviewer run cargo test and report results." --pane=<WINDOW_ID>
+tmux-cli wait_idle --pane=<WINDOW_ID> --idle-time=30.0
+stop_polling $POLL_PID
+tmux-cli capture --pane=<WINDOW_ID> > $ATOMIC_PROJECT_DIR/tmux-screenshots/<AGENT>-20-parallel-agents-final.txt
+```
+
 **Verify:**
 
 - Agent part renders with agent name and status
 - Parallel agent tree shows live status updates (pending → running → completed)
-- Sub-agent result displayed inline
+- Sub-agent state displayed inline in sub-agent tree:
+    - Tools and tool counts are streamed in the single agent case
+    - Tools and tool counts are streamed in ALL branches of parallel agent case
+- The parallel agent tree should look roughly like this during initialization:
+
+**Foreground Sub-agent Invocation**
+
+1. During initialization (no tool calls or streaming started)
+
+    ```
+    ● Running 2 agents…
+    ├─● Locate sub-agent message handling
+    │    ╰  Initializing codebase-locator… (2s)
+    └─● Find sub-agent text rendering code
+         ╰  Initializing codebase-pattern-finder… (5s)
+    ```
+
+2. During execution (tools and tool counts stream for each branch):
+
+    Here's how a correct UI looks during execution:
+
+    ```
+    ● Running 2 agents…
+    ├─● Locate sub-agent message handling
+    │    ╰ codebase-locator: (10 tool uses)
+    │      · rg
+    └─● Find sub-agent text rendering code
+         ╰ codebase-pattern-finder: (5 tool uses)
+           · ls
+    ```
+
+    Here's how an incorrect UI looks:
+
+    ```
+    ● Running 2 codebase-analyzer agents…
+    ├─● codebase-analyzer
+    · 39 tool uses
+    │    ╰  bash (2m 22s)
+    └─● codebase-analyzer
+    · 35 tool uses
+        ╰  view (2m 22s)
+    ```
+
+#### 5.1.1 — Background Sub-Agent Invocation
+
+Similar procedure for background agents, but verify the sub-agent tree renders **without** tool counts or streaming metadata:
+
+**Background Sub-agent Invocation**
+
+1. During initialization (no tool calls or streaming started)
+
+```
+● 2 Task agents launched…
+├─● Locate OpenCode SDK integration
+│    ╰  Running codebase-locator in background…
+└─● Analyze SDK tool display patterns
+      ╰  Running codebase-analyzer in background…
+```
+
+Background agent progress is shown via the footer status text below the chatbox:
+
+```
+
+[CHATBOX]
+[N] local agents · ctrl+f to kill all background tasks
+
+```
+
+When the chatbox is streaming AND background agents are running, the footer combines both:
+
+```
+
+[CHATBOX]
+esc to interrupt · ctrl+shift+enter enqueue · [N] local agents · ctrl+f to kill all background tasks
+
+```
+
+2. During execution: N/A, under the chatbox ui contains status and should be updated
+
+3. Finished state:
+
+```
+● Agent "Explore Claude adapter for comparison" completed
+
+● Agent [TASK_DESCRIPTION] completed
+```
 
 #### 5.2 — Skill Invocation (`/research-codebase`)
 
@@ -494,6 +677,10 @@ tmux-cli capture --pane=<WINDOW_ID> > $ATOMIC_PROJECT_DIR/tmux-screenshots/<AGEN
 
 ### Phase 6: HITL / Ask-Question Dialog
 
+The `ask_question` tool renders an **inline dialog** within the chat scrollbox (not a modal overlay). When the dialog is active, the chatbox textarea is hidden and replaced by the dialog.
+
+#### 6.1 — Basic ask_question
+
 ```bash
 POLL_PID=$(start_polling <WINDOW_ID> <AGENT> 21-ask-question)
 tmux-cli send "I want to refactor the game. Should I split it into multiple files (game.rs, snake.rs, food.rs, renderer.rs) or keep it in a single file? Ask me which approach I prefer before proceeding." --pane=<WINDOW_ID>
@@ -506,10 +693,12 @@ If the ask_question dialog appears:
 
 ```bash
 POLL_PID=$(start_polling <WINDOW_ID> <AGENT> 22-ask-answer)
-# Select an option (e.g., press 1 for first option)
+# Select an option with a number key (1-9 for model-provided options)
 tmux-cli send "1" --pane=<WINDOW_ID> --enter=False
-sleep 0.5
-tmux-cli send "" --pane=<WINDOW_ID>  # Enter to confirm
+sleep 1
+tmux-cli capture --pane=<WINDOW_ID> > $ATOMIC_PROJECT_DIR/tmux-screenshots/<AGENT>-22-ask-question-selected.txt
+
+# Wait for agent to continue with the selected choice
 tmux-cli wait_idle --pane=<WINDOW_ID> --idle-time=15.0
 stop_polling $POLL_PID
 tmux-cli capture --pane=<WINDOW_ID> > $ATOMIC_PROJECT_DIR/tmux-screenshots/<AGENT>-22-ask-question-answered-final.txt
@@ -517,10 +706,138 @@ tmux-cli capture --pane=<WINDOW_ID> > $ATOMIC_PROJECT_DIR/tmux-screenshots/<AGEN
 
 **Verify:**
 
-- Modal dialog renders with numbered options
-- Keyboard selection works (number keys, Up/Down arrows)
-- Response is captured and agent continues with the selected choice
-- HITL response rendered inline with the tool call
+- Dialog renders **inline** within the chat scrollbox with a header badge, question text, and numbered options
+- The chatbox textarea is **hidden** while the dialog is active
+- Number keys (1-9) directly select and submit a model-provided option (single-select mode)
+- Up/Down arrows navigate the option list with a highlighted cursor
+- Footer hint line shows: `Enter to select · ↑/↓ to navigate · Esc to cancel`
+- After answering, the HITL response is rendered inline with the tool call, and the agent continues
+
+#### 6.2 — ask_question Custom Input ("Type something" / "Chat about this")
+
+```bash
+POLL_PID=$(start_polling <WINDOW_ID> <AGENT> 22b-ask-custom-input)
+tmux-cli send "What color should the snake be? Ask me before changing anything." --pane=<WINDOW_ID>
+tmux-cli wait_idle --pane=<WINDOW_ID> --idle-time=10.0
+
+# Navigate to the "Type something." option (last model option + 1)
+# Use Down arrow to reach it, then Enter to activate custom input mode
+tmux-cli send $'\x1b[B\x1b[B\x1b[B\x1b[B\x1b[B\x1b[B\x1b[B\x1b[B\x1b[B' --pane=<WINDOW_ID> --enter=False
+sleep 0.5
+# Press Enter to activate custom input textarea
+tmux-cli send "" --pane=<WINDOW_ID>
+sleep 1
+tmux-cli capture --pane=<WINDOW_ID> > $ATOMIC_PROJECT_DIR/tmux-screenshots/<AGENT>-22b-custom-input-active.txt
+
+# Type custom text and submit
+tmux-cli send "Bright green with a darker green tail" --pane=<WINDOW_ID>
+tmux-cli wait_idle --pane=<WINDOW_ID> --idle-time=15.0
+stop_polling $POLL_PID
+tmux-cli capture --pane=<WINDOW_ID> > $ATOMIC_PROJECT_DIR/tmux-screenshots/<AGENT>-22b-custom-input-final.txt
+```
+
+**Verify:**
+
+- Every dialog includes two special options at the bottom: **"Type something."** and **"Chat about this"**
+- Selecting "Type something." opens a textarea within the dialog for freeform input
+- Selecting "Chat about this" also opens a textarea (with a different placeholder)
+- Pressing ESC while in the custom input textarea **exits the textarea back to the option list** (does not dismiss the dialog)
+- A second ESC press from the option list **dismisses the entire dialog**
+
+#### 6.3 — ask_question Dismissal with ESC
+
+```bash
+POLL_PID=$(start_polling <WINDOW_ID> <AGENT> 22c-ask-esc-dismiss)
+tmux-cli send "Ask me what difficulty level I want for the snake game before making any changes." --pane=<WINDOW_ID>
+tmux-cli wait_idle --pane=<WINDOW_ID> --idle-time=10.0
+tmux-cli capture --pane=<WINDOW_ID> > $ATOMIC_PROJECT_DIR/tmux-screenshots/<AGENT>-22c-ask-esc-dialog.txt
+
+# Dismiss the dialog with ESC
+tmux-cli send $'\x1b' --pane=<WINDOW_ID> --enter=False
+tmux-cli wait_idle --pane=<WINDOW_ID> --idle-time=5.0
+stop_polling $POLL_PID
+tmux-cli capture --pane=<WINDOW_ID> > $ATOMIC_PROJECT_DIR/tmux-screenshots/<AGENT>-22c-ask-esc-dismissed-final.txt
+```
+
+**Verify:**
+
+- ESC sends a **cancellation response** (`cancelled: true`, `responseMode: "declined"`) — not an empty string
+- The agent receives the cancellation and either stops or adjusts its behavior
+- The chatbox textarea **reappears** after the dialog is dismissed
+- The HITL tool call is marked as cancelled in the message
+
+#### 6.4 — ask_question with Queued Messages (Edge Case)
+
+This tests that queued messages **do not** auto-respond to an ask_question dialog. The queue is blocked while any ask_question tool is running.
+
+```bash
+POLL_PID=$(start_polling <WINDOW_ID> <AGENT> 22d-ask-with-queue)
+
+# Send a prompt that will trigger streaming
+tmux-cli send "Refactor the game rendering. Ask me whether to use double buffering or direct rendering before you start. Also add comments to all functions." --pane=<WINDOW_ID>
+sleep 2
+
+# Queue a follow-up message while streaming
+tmux-cli send "After refactoring, run cargo check to verify." --pane=<WINDOW_ID> --enter=False
+sleep 0.3
+tmux-cli send $'\x1b[13;6u' --pane=<WINDOW_ID> --enter=False
+
+# Wait for ask_question dialog to appear
+tmux-cli wait_idle --pane=<WINDOW_ID> --idle-time=10.0
+tmux-cli capture --pane=<WINDOW_ID> > $ATOMIC_PROJECT_DIR/tmux-screenshots/<AGENT>-22d-ask-with-queue-dialog.txt
+
+# Answer the dialog
+tmux-cli send "1" --pane=<WINDOW_ID> --enter=False
+tmux-cli wait_idle --pane=<WINDOW_ID> --idle-time=15.0
+
+# After the agent finishes, the queued message should auto-dispatch
+tmux-cli wait_idle --pane=<WINDOW_ID> --idle-time=15.0
+stop_polling $POLL_PID
+tmux-cli capture --pane=<WINDOW_ID> > $ATOMIC_PROJECT_DIR/tmux-screenshots/<AGENT>-22d-ask-with-queue-final.txt
+```
+
+**Verify:**
+
+- The queue indicator still shows the queued message count while the dialog is active
+- The queued message does **NOT** auto-respond to the ask_question dialog — the user must manually answer
+- Queue dispatch guard blocks: `!isStreaming && runningAskQuestionToolCount === 0` must both be true
+- After the dialog is answered and the agent completes its response, the queued message auto-dispatches
+
+#### 6.5 — ask_question with Text in Chatbox (Edge Case)
+
+This tests that text typed into the chatbox is **preserved** when an ask_question dialog fires.
+
+```bash
+POLL_PID=$(start_polling <WINDOW_ID> <AGENT> 22e-ask-with-chatbox-text)
+
+# Type something into the chatbox but DON'T submit
+tmux-cli send "This is my draft message" --pane=<WINDOW_ID> --enter=False
+sleep 1
+tmux-cli capture --pane=<WINDOW_ID> > $ATOMIC_PROJECT_DIR/tmux-screenshots/<AGENT>-22e-chatbox-with-text.txt
+
+# Now send a prompt that triggers ask_question (use a second terminal or queue)
+# For this test, submit a prompt that will trigger ask_question
+# First clear the draft by selecting all and deleting
+tmux-cli send $'\x01' --pane=<WINDOW_ID> --enter=False  # Ctrl+A select all
+tmux-cli send $'\x1b[3~' --pane=<WINDOW_ID> --enter=False  # Delete
+tmux-cli send "Ask me what board size I want for the snake game." --pane=<WINDOW_ID>
+tmux-cli wait_idle --pane=<WINDOW_ID> --idle-time=10.0
+tmux-cli capture --pane=<WINDOW_ID> > $ATOMIC_PROJECT_DIR/tmux-screenshots/<AGENT>-22e-ask-dialog-active.txt
+
+# Verify: chatbox textarea is hidden, replaced by the dialog
+# Answer the dialog
+tmux-cli send "1" --pane=<WINDOW_ID> --enter=False
+tmux-cli wait_idle --pane=<WINDOW_ID> --idle-time=10.0
+stop_polling $POLL_PID
+tmux-cli capture --pane=<WINDOW_ID> > $ATOMIC_PROJECT_DIR/tmux-screenshots/<AGENT>-22e-ask-with-chatbox-final.txt
+```
+
+**Verify:**
+
+- When `ask_question` fires, the chatbox textarea is **hidden** (not rendered) and replaced by the inline dialog
+- Any text in the textarea state is **preserved in memory** — the React state is not cleared
+- After the dialog is answered, the chatbox textarea **reappears** with the preserved text (if any was in state)
+- The dialog does **not** overlay the chatbox — it **replaces** it in the render tree
 
 ### Phase 7: Autocomplete
 
@@ -575,12 +892,14 @@ stop_polling $POLL_PID
 
 **Verify:** Task list panel toggles visibility. Shows tasks with checkboxes and status indicators.
 
-### Phase 9: Interrupt & Multi-line Input
+### Phase 9: Interruption, Cancellation & Exit
+
+#### 9.1 — Ctrl+C Interrupt + Follow-up Message
 
-#### 9.1 — Interrupt Streaming (Ctrl+C)
+Verify that after interrupting a stream with Ctrl+C, the chatbox returns to an input-ready state and a new message can be sent immediately.
 
 ```bash
-POLL_PID=$(start_polling <WINDOW_ID> <AGENT> 26-interrupt)
+POLL_PID=$(start_polling <WINDOW_ID> <AGENT> 26-interrupt-ctrlc)
 # Send a prompt that will generate a long response
 tmux-cli send "Write comprehensive documentation for every function in the snake game. Include parameter descriptions, return values, examples, and edge cases for each function." --pane=<WINDOW_ID>
 sleep 3
@@ -588,25 +907,163 @@ sleep 3
 # Interrupt with Ctrl+C
 tmux-cli send $'\x03' --pane=<WINDOW_ID> --enter=False
 tmux-cli wait_idle --pane=<WINDOW_ID> --idle-time=3.0
+tmux-cli capture --pane=<WINDOW_ID> > $ATOMIC_PROJECT_DIR/tmux-screenshots/<AGENT>-26-interrupt-ctrlc.txt
+
+# Immediately send a follow-up message to confirm cancellation was applied
+tmux-cli send "Just say hello." --pane=<WINDOW_ID>
+tmux-cli wait_idle --pane=<WINDOW_ID> --idle-time=10.0
+stop_polling $POLL_PID
+tmux-cli capture --pane=<WINDOW_ID> > $ATOMIC_PROJECT_DIR/tmux-screenshots/<AGENT>-26-interrupt-ctrlc-followup-final.txt
+```
+
+**Verify:**
+
+- Streaming stops immediately when Ctrl+C is pressed
+- The interrupted message is preserved with `wasInterrupted: true` — partial response is visible
+- Tool calls in progress show interrupted status indicator
+- The chatbox textarea is **immediately** input-ready (no blocking state)
+- The follow-up message sends successfully, confirming the stream was fully cancelled
+- Background agents (if any) are **not** affected — only foreground agents are interrupted
+- A "Press Ctrl-C again to exit" warning briefly appears in the footer (1000ms timeout)
+
+#### 9.2 — ESC Interrupt + Follow-up Message
+
+ESC also interrupts streaming, but with key differences from Ctrl+C.
+
+```bash
+POLL_PID=$(start_polling <WINDOW_ID> <AGENT> 27-interrupt-esc)
+# Send a prompt that will generate a long response
+tmux-cli send "List all possible improvements to the snake game with detailed implementation plans for each one. Be extremely thorough." --pane=<WINDOW_ID>
+sleep 3
+
+# Interrupt with ESC
+tmux-cli send $'\x1b' --pane=<WINDOW_ID> --enter=False
+tmux-cli wait_idle --pane=<WINDOW_ID> --idle-time=3.0
+tmux-cli capture --pane=<WINDOW_ID> > $ATOMIC_PROJECT_DIR/tmux-screenshots/<AGENT>-27-interrupt-esc.txt
+
+# Send a follow-up message to confirm cancellation
+tmux-cli send "Just say hi." --pane=<WINDOW_ID>
+tmux-cli wait_idle --pane=<WINDOW_ID> --idle-time=10.0
+stop_polling $POLL_PID
+tmux-cli capture --pane=<WINDOW_ID> > $ATOMIC_PROJECT_DIR/tmux-screenshots/<AGENT>-27-interrupt-esc-followup-final.txt
+```
+
+**Verify:**
+
+- Streaming stops (same mechanism as Ctrl+C)
+- The chatbox is immediately input-ready
+- Follow-up message sends successfully
+- **Unlike Ctrl+C**: ESC does **not** show a "Press again to exit" warning
+- **Unlike Ctrl+C**: ESC does **not** support double-press exit — it always interrupts only
+- ESC first dismisses autocomplete or queue editing if either is active, then interrupts on the next press
+
+#### 9.3 — Ctrl+C Interrupt with Queued Messages
+
+Verify that the message queue is **preserved** on Ctrl+C interrupt and queued messages auto-dispatch after interruption.
+
+```bash
+POLL_PID=$(start_polling <WINDOW_ID> <AGENT> 28-interrupt-with-queue)
+
+# Send a long prompt
+tmux-cli send "Write a complete README.md for the snake game project with installation instructions, gameplay guide, and screenshots placeholder." --pane=<WINDOW_ID>
+sleep 2
+
+# Queue a follow-up message during streaming
+tmux-cli send "Also add a CHANGELOG.md file." --pane=<WINDOW_ID> --enter=False
+sleep 0.3
+tmux-cli send $'\x1b[13;6u' --pane=<WINDOW_ID> --enter=False
+sleep 1
+
+# Verify queue indicator shows "1 message queued"
+tmux-cli capture --pane=<WINDOW_ID> > $ATOMIC_PROJECT_DIR/tmux-screenshots/<AGENT>-28-interrupt-queue-during.txt
+
+# Interrupt with Ctrl+C
+tmux-cli send $'\x03' --pane=<WINDOW_ID> --enter=False
+tmux-cli wait_idle --pane=<WINDOW_ID> --idle-time=3.0
+tmux-cli capture --pane=<WINDOW_ID> > $ATOMIC_PROJECT_DIR/tmux-screenshots/<AGENT>-28-interrupt-queue-after-ctrlc.txt
+
+# The queued message should auto-dispatch after the interrupt
+tmux-cli wait_idle --pane=<WINDOW_ID> --idle-time=15.0
 stop_polling $POLL_PID
-tmux-cli capture --pane=<WINDOW_ID> > $ATOMIC_PROJECT_DIR/tmux-screenshots/<AGENT>-26-interrupt-final.txt
+tmux-cli capture --pane=<WINDOW_ID> > $ATOMIC_PROJECT_DIR/tmux-screenshots/<AGENT>-28-interrupt-queue-final.txt
 ```
 
-**Verify:** Streaming stops. Interrupted tool shows `●` yellow indicator. Partial response preserved.
+**Verify:**
+
+- The queue is **NOT cleared** on Ctrl+C — `messageQueue.clear()` is never called in the interrupt handler
+- After the stream is interrupted, `continueQueuedConversation()` is called automatically
+- The next queued message auto-dispatches after a 50ms delay
+- The queued message's response streams normally as if it were a fresh user message
+
+#### 9.4 — Double Ctrl+C to Exit (Idle State)
+
+When not streaming, double Ctrl+C within 1000ms exits the TUI application.
+
+```bash
+POLL_PID=$(start_polling <WINDOW_ID> <AGENT> 29-double-ctrlc-exit)
+
+# First Ctrl+C — shows warning
+tmux-cli send $'\x03' --pane=<WINDOW_ID> --enter=False
+sleep 0.3
+tmux-cli capture --pane=<WINDOW_ID> > $ATOMIC_PROJECT_DIR/tmux-screenshots/<AGENT>-29-double-ctrlc-warning.txt
+
+# Second Ctrl+C within 1000ms — exits the application
+tmux-cli send $'\x03' --pane=<WINDOW_ID> --enter=False
+sleep 2
+stop_polling $POLL_PID
+tmux-cli capture --pane=<WINDOW_ID> > $ATOMIC_PROJECT_DIR/tmux-screenshots/<AGENT>-29-double-ctrlc-exited.txt
+```
+
+**Verify:**
+
+- First Ctrl+C shows `"Press Ctrl-C again to exit"` in the footer
+- The warning auto-clears after **1000ms** if a second press doesn't come
+- Second Ctrl+C within the 1000ms window triggers `onExit()` and the TUI process exits cleanly
+- If the second Ctrl+C comes **after** 1000ms, it is treated as a new first press (timer restarts)
+
+#### 9.5 — Double Ctrl+C to Exit Workflow
+
+During an active workflow (e.g., `/ralph`), double Ctrl+C terminates the workflow.
+
+```bash
+POLL_PID=$(start_polling <WINDOW_ID> <AGENT> 30-workflow-double-ctrlc)
+
+# Start a workflow
+tmux-cli send "/ralph Add a splash screen to the snake game." --pane=<WINDOW_ID>
+sleep 5
+
+# First Ctrl+C — interrupts current stream, workflow enters waitForUserInput
+tmux-cli send $'\x03' --pane=<WINDOW_ID> --enter=False
+sleep 1
+tmux-cli capture --pane=<WINDOW_ID> > $ATOMIC_PROJECT_DIR/tmux-screenshots/<AGENT>-30-workflow-first-ctrlc.txt
+
+# Second Ctrl+C — terminates the workflow entirely
+tmux-cli send $'\x03' --pane=<WINDOW_ID> --enter=False
+tmux-cli wait_idle --pane=<WINDOW_ID> --idle-time=5.0
+stop_polling $POLL_PID
+tmux-cli capture --pane=<WINDOW_ID> > $ATOMIC_PROJECT_DIR/tmux-screenshots/<AGENT>-30-workflow-double-ctrlc-final.txt
+```
+
+**Verify:**
+
+- First Ctrl+C during workflow: interrupts the stream, sets `wasInterrupted: true`, workflow pauses
+- Footer shows: `workflow · esc to interrupt · ctrl+shift+enter enqueue · ctrl+c twice to exit workflow`
+- Second Ctrl+C: sets `wasCancelled: true`, terminates the workflow, rejects `waitForUserInputResolver`
+- After termination, the chatbox returns to normal (non-workflow) mode
+- **Note**: ESC in a workflow only interrupts (single behavior) — it does **not** support double-press workflow termination
 
-#### 9.2 — Multi-line Input (Shift+Enter)
+#### 9.6 — Multi-line Input (Shift+Enter)
 
 ```bash
-POLL_PID=$(start_polling <WINDOW_ID> <AGENT> 27-multiline)
-# Send multi-line input using Shift+Enter (sends newline without submitting)
-# Note: Shift+Enter may need to be sent as a literal newline without Enter
+POLL_PID=$(start_polling <WINDOW_ID> <AGENT> 31-multiline)
+# Send multi-line input using Shift+Enter (inserts newline without submitting)
 tmux-cli send "Add these features:" --pane=<WINDOW_ID> --enter=False
 tmux-cli send $'\x1b[13;2u' --pane=<WINDOW_ID> --enter=False  # Shift+Enter
 tmux-cli send "1. Color the snake green" --pane=<WINDOW_ID> --enter=False
 tmux-cli send $'\x1b[13;2u' --pane=<WINDOW_ID> --enter=False  # Shift+Enter
 tmux-cli send "2. Color the food red" --pane=<WINDOW_ID> --enter=False
 sleep 2
-tmux-cli capture --pane=<WINDOW_ID> > $ATOMIC_PROJECT_DIR/tmux-screenshots/<AGENT>-27-multiline-final.txt
+tmux-cli capture --pane=<WINDOW_ID> > $ATOMIC_PROJECT_DIR/tmux-screenshots/<AGENT>-31-multiline-final.txt
 
 # Submit with Enter
 tmux-cli send "" --pane=<WINDOW_ID>
@@ -614,16 +1071,16 @@ tmux-cli wait_idle --pane=<WINDOW_ID> --idle-time=15.0
 stop_polling $POLL_PID
 ```
 
-**Verify:** Input box expands to show multiple lines before submission.
+**Verify:** Input box expands to show multiple lines before submission. Shift+Enter inserts a newline without submitting.
 
 ### Phase 10: Workflow — `/ralph`
 
 ```bash
-POLL_PID=$(start_polling <WINDOW_ID> <AGENT> 28-ralph)
+POLL_PID=$(start_polling <WINDOW_ID> <AGENT> 32-ralph)
 tmux-cli send "/ralph Add a main menu screen with Play, High Scores, and Quit options. The menu should render in the terminal with arrow key navigation." --pane=<WINDOW_ID>
 tmux-cli wait_idle --pane=<WINDOW_ID> --idle-time=60.0
 stop_polling $POLL_PID
-tmux-cli capture --pane=<WINDOW_ID> > $ATOMIC_PROJECT_DIR/tmux-screenshots/<AGENT>-28-ralph-final.txt
+tmux-cli capture --pane=<WINDOW_ID> > $ATOMIC_PROJECT_DIR/tmux-screenshots/<AGENT>-32-ralph-final.txt
 ```
 
 **Verify:**
@@ -638,11 +1095,11 @@ tmux-cli capture --pane=<WINDOW_ID> > $ATOMIC_PROJECT_DIR/tmux-screenshots/<AGEN
 #### 11.1 — Verify the Game Builds
 
 ```bash
-POLL_PID=$(start_polling <WINDOW_ID> <AGENT> 29-final-build)
+POLL_PID=$(start_polling <WINDOW_ID> <AGENT> 33-final-build)
 tmux-cli send "Run cargo build --release and confirm the snake game compiles successfully." --pane=<WINDOW_ID>
 tmux-cli wait_idle --pane=<WINDOW_ID> --idle-time=20.0
 stop_polling $POLL_PID
-tmux-cli capture --pane=<WINDOW_ID> > $ATOMIC_PROJECT_DIR/tmux-screenshots/<AGENT>-29-final-build-final.txt
+tmux-cli capture --pane=<WINDOW_ID> > $ATOMIC_PROJECT_DIR/tmux-screenshots/<AGENT>-33-final-build-final.txt
 ```
 
 **Verify:** `cargo build --release` succeeds. Binary produced.
@@ -651,18 +1108,18 @@ tmux-cli capture --pane=<WINDOW_ID> > $ATOMIC_PROJECT_DIR/tmux-screenshots/<AGEN
 
 ```bash
 # Clear session
-POLL_PID=$(start_polling <WINDOW_ID> <AGENT> 30-clear)
+POLL_PID=$(start_polling <WINDOW_ID> <AGENT> 34-clear)
 tmux-cli send "/clear" --pane=<WINDOW_ID>
 tmux-cli wait_idle --pane=<WINDOW_ID> --idle-time=3.0
 stop_polling $POLL_PID
-tmux-cli capture --pane=<WINDOW_ID> > $ATOMIC_PROJECT_DIR/tmux-screenshots/<AGENT>-30-clear-final.txt
+tmux-cli capture --pane=<WINDOW_ID> > $ATOMIC_PROJECT_DIR/tmux-screenshots/<AGENT>-34-clear-final.txt
 
 # Exit
-POLL_PID=$(start_polling <WINDOW_ID> <AGENT> 31-exit)
+POLL_PID=$(start_polling <WINDOW_ID> <AGENT> 35-exit)
 tmux-cli send "/exit" --pane=<WINDOW_ID>
 tmux-cli wait_idle --pane=<WINDOW_ID> --idle-time=3.0
 stop_polling $POLL_PID
-tmux-cli capture --pane=<WINDOW_ID> > $ATOMIC_PROJECT_DIR/tmux-screenshots/<AGENT>-31-exit-final.txt
+tmux-cli capture --pane=<WINDOW_ID> > $ATOMIC_PROJECT_DIR/tmux-screenshots/<AGENT>-35-exit-final.txt
 
 # Kill the window
 tmux-cli kill --pane=<WINDOW_ID>
@@ -689,15 +1146,21 @@ Every feature below MUST be verified during the test run. Check each one as you
 
 ### Keyboard Shortcuts
 
-- [ ] `Ctrl+C` — interrupts streaming response
-- [ ] `Ctrl+C` twice — exits application
+- [ ] `Ctrl+C` — interrupts streaming response (foreground agents only, background agents preserved)
+- [ ] `Ctrl+C` + follow-up message — chatbox is immediately input-ready after interrupt
+- [ ] `Ctrl+C` twice (idle, within 1000ms) — exits application
+- [ ] `Ctrl+C` twice (workflow) — terminates workflow entirely
+- [ ] `Ctrl+C` with queued messages — queue is preserved and auto-dispatches after interrupt
+- [ ] `ESC` — interrupts streaming (same as Ctrl+C but no double-press exit support)
+- [ ] `ESC` + follow-up message — chatbox is immediately input-ready after interrupt
+- [ ] `ESC` — dismisses autocomplete or queue editing before interrupting stream
 - [ ] `Ctrl+O` — toggles verbose/compact transcript mode
 - [ ] `Ctrl+T` — toggles task list panel
+- [ ] `Ctrl+F` — double-press to terminate all background agents
 - [ ] `Cmd+Shift+Enter` (macOS) / `Ctrl+Shift+Enter` (Linux/Windows) — queues message during streaming
 - [ ] `Enter` — submits message
 - [ ] `Shift+Enter` — inserts newline (multi-line input)
-- [ ] `ESC` — dismisses dialogs/autocomplete
-- [ ] `Up/Down` arrows — scrolls messages or navigates history
+- [ ] `Up/Down` arrows — scrolls messages, navigates history, or edits queued messages
 - [ ] `PageUp/PageDown` — half-screen scroll
 - [ ] `Tab` — completes autocomplete suggestion
 
@@ -718,18 +1181,29 @@ Every feature below MUST be verified during the test run. Check each one as you
 ### Message Queuing
 
 - [ ] `Cmd+Shift+Enter` (macOS) / `Ctrl+Shift+Enter` (Linux/Windows) enqueues message during streaming
-- [ ] Queue count shown in footer
-- [ ] Queued messages process sequentially after response
-- [ ] `Up/Down` arrows edit queued messages
+- [ ] Queue indicator appears above chatbox with icon, count, and first message preview
+- [ ] Queued messages process sequentially (FIFO) after response completes (50ms dispatch delay)
+- [ ] Queue is preserved on Ctrl+C interrupt — auto-dispatches after interruption
+- [ ] `Up/Down` arrows edit queued messages (loads content into textarea, auto-saves on navigation)
+- [ ] Queue indicator expands to non-compact mode during editing (shows numbered list)
+- [ ] Footer shows enqueue shortcut hint during streaming
+- [ ] Placeholder changes to `"Press ↑ to edit queued messages..."` when queue is non-empty and not streaming
 
 ### Ask-Question / HITL Dialog
 
-- [ ] Modal dialog renders with numbered options
-- [ ] Number keys select options (1-9, 0)
-- [ ] Up/Down navigates options
+- [ ] Inline dialog renders within chat scrollbox (not a modal overlay)
+- [ ] Chatbox textarea is hidden while dialog is active
+- [ ] Number keys (1-9) directly select and submit model-provided options (single-select)
+- [ ] Up/Down navigates options with highlighted cursor
 - [ ] Enter confirms selection
-- [ ] ESC dismisses dialog
-- [ ] Custom text input option works
+- [ ] "Type something." and "Chat about this" special options appear at bottom of every dialog
+- [ ] Custom input mode: selecting "Type something." opens textarea within dialog
+- [ ] ESC in custom input mode exits textarea back to option list (first ESC), then dismisses dialog (second ESC)
+- [ ] ESC on option list sends cancellation response (`cancelled: true`, `responseMode: "declined"`)
+- [ ] Multi-select mode uses Ctrl+Enter / Cmd+Enter to submit selected items
+- [ ] ask_question with queued messages: queue is blocked, does NOT auto-respond to dialog
+- [ ] ask_question with text in chatbox: text preserved in state, chatbox hidden during dialog
+- [ ] Queue resumes after ask_question completes: dispatch guard requires `runningAskQuestionToolCount === 0`
 
 ### Session Management
 
@@ -785,10 +1259,13 @@ Every feature below MUST be verified during the test run. Check each one as you
 ### Footer Status Bar
 
 - [ ] Model ID displayed
-- [ ] Streaming indicator shown
+- [ ] Streaming footer shows: `esc to interrupt · ctrl+shift+enter enqueue`
+- [ ] Workflow footer shows: `workflow · esc to interrupt · ctrl+shift+enter enqueue · ctrl+c twice to exit workflow`
+- [ ] Background agents: `[N] local agents · ctrl+f to kill all background tasks`
 - [ ] Verbose/compact mode shown
-- [ ] Queue count displayed
+- [ ] Queue count displayed (in queue indicator above chatbox, not in footer)
 - [ ] Agent type displayed
+- [ ] "Press Ctrl-C again to exit" warning on first Ctrl+C when idle (clears after 1000ms)
 
 ---
 
diff --git a/docs/stream-debug-logging.md b/docs/stream-debug-logging.md
new file mode 100644
index 0000000000..bef0dd9fe1
--- /dev/null
+++ b/docs/stream-debug-logging.md
@@ -0,0 +1,300 @@
+# Stream Debug Logging
+
+Use stream debug logging when you need a full event timeline for a conversation.
+
+When enabled, Atomic writes stream diagnostics into a **timestamped log folder** per run:
+
+- `events` log (structured JSONL event timeline)
+- `raw stream` log (UI-oriented conversation components)
+
+## Quick Start
+
+Enable logging for a chat session:
+
+```bash
+DEBUG=1 bun run src/cli.ts chat -a opencode
+```
+
+You can use `-a claude` or `-a copilot` the same way.
+
+At startup, Atomic prints the folder and both files:
+
+```text
+[Atomic] Stream debug logs: /home/<user>/.local/share/atomic/log/events/2026-03-02T184210
+[Atomic] Stream events log: /home/<user>/.local/share/atomic/log/events/2026-03-02T184210/events.jsonl
+[Atomic] Stream raw log: /home/<user>/.local/share/atomic/log/events/2026-03-02T184210/raw-stream.log
+```
+
+## Environment Variables
+
+- `DEBUG`
+    - `1`, `true`, `on`: enable stream debug log files and console preview
+    - `0`, `false`, `off`: disable stream debug log files
+- `LOG_DIR`
+    - optional directory override for the **parent debug log directory** (defaults to `~/.local/share/atomic/log/events/`)
+
+## What Gets Logged
+
+Each session folder contains:
+
+- `events.jsonl`: structured bus timeline + diagnostics
+- `raw-stream.log`: UI-style line stream for visual debugging
+
+The JSONL `events` log contains two kinds of entries: **event entries** (bus events) and **diagnostic entries** (errors, metadata). In addition, **pipeline diagnostic messages** are emitted to the console at both `debug` and `error` levels.
+
+### Raw Stream Log (UI)
+
+The raw stream log captures conversation components in the order they are rendered/observed by the stream pipeline, for example:
+
+```text
+❯ @codebase-online-researcher Research good UI/UX design practices for the TUI
+∴ Thinking...
+Launching UI/UX research task
+◉
+task codebase-online-researcher: Research TUI UX practices
+Agent: codebase-online-researcher
+Task: Research TUI UX practices
+Prompt: Research task only (do not write code): Find modern, high-quality UI/UX design practices...
+⣯ Composing… (23s)
+```
+
+Notes:
+
+- User prompts are written when a stream starts.
+- `Task/task/launch_agent` tool calls include expanded `Agent/Task/Prompt` fields when present.
+- The raw stream log is optimized for UI debugging and is intentionally less structured than the JSONL event log.
+
+### Event Entries
+
+All bus events — including `stream.*` events and `workflow.*` events — are logged as JSON objects with:
+
+- `seq`: global monotonically increasing log sequence number
+- `runSeq`: per `sessionId + runId` sequence number
+- `ts`: event timestamp (ISO string)
+- `loggedAt`: wall-clock timestamp when the event was written to disk
+- `type`: bus event type (for example `stream.text.delta`, `stream.tool.start`, `workflow.step.start`, `workflow.step.complete`)
+- `sessionId`: session identifier associated with the event
+- `runId`: run identifier for stream turn correlation
+- `eventLagMs`: `loggedAt - ts` in milliseconds
+- `globalGapMs`: elapsed milliseconds since the previous logged event (any session)
+- `sessionRunGapMs`: elapsed milliseconds since the previous event in the same `sessionId + runId`
+- `continuityGapMs`: present when `sessionRunGapMs >= 1500` for `stream.*` events (helps spot streaming stalls)
+- `eventTimestampRegressionMs`: present when event timestamps move backwards within the same run
+- `streamGapMs`: elapsed milliseconds since the previous `stream.*` event in the same run
+- `runAgeMs`: milliseconds since the first event in the run was logged
+- `runDurationMs`: present on idle/error terminal events; total observed run lifetime in ms
+- `streamEventCount` / `textDeltaCount` / `thinkingDeltaCount`: cumulative stream counters for the run at this event
+- `toolStartCount` / `toolCompleteCount`: cumulative tool lifecycle counters for the run
+- `pendingToolCalls` / `maxPendingToolCalls`: in-flight tool count snapshot and max observed concurrency
+- `lifecycleMarkers`: derived hints for diagnostics (for example `session-start`, `first-text-delta`, `stream-gap`, `idle-with-pending-tools`, `timestamp-regression`)
+- `payloadBytes`: JSON byte length of `data`
+- `agentTreeSnapshot`: present on agent lifecycle events (`stream.agent.start`, `stream.agent.update`, `stream.agent.complete`) and session errors; see [Agent Tree Snapshots](#agent-tree-snapshots)
+- `data`: full event payload
+
+Example event entry:
+
+```json
+{
+    "seq": 27,
+    "runSeq": 9,
+    "ts": "2026-03-02T18:42:10.235Z",
+    "loggedAt": "2026-03-02T18:42:10.241Z",
+    "type": "stream.text.delta",
+    "sessionId": "ses_123",
+    "runId": 3,
+    "eventLagMs": 6,
+    "globalGapMs": 14,
+    "sessionRunGapMs": 14,
+    "streamGapMs": 14,
+    "runAgeMs": 221,
+    "streamEventCount": 9,
+    "textDeltaCount": 7,
+    "thinkingDeltaCount": 0,
+    "toolStartCount": 1,
+    "toolCompleteCount": 1,
+    "pendingToolCalls": 0,
+    "maxPendingToolCalls": 1,
+    "lifecycleMarkers": ["first-text-delta"],
+    "payloadBytes": 38,
+    "data": { "delta": "hello", "messageId": "msg_1" }
+}
+```
+
+### Diagnostic Entries
+
+Diagnostic entries capture errors and metadata that are not bus events. They share the same `seq` counter for ordering and have a `category` field instead of `type`:
+
+- `seq`: global sequence number (shared with event entries)
+- `ts`: wall-clock timestamp (ISO string)
+- `category`: one of `"startup"`, `"bus_error"`, `"process_error"`
+- `error`: error message (present on error categories)
+- `stack`: stack trace (present when available)
+- `agentTreeSnapshot`: current agent tree state at the time of the diagnostic
+- `data`: category-specific metadata
+
+#### Startup Entry
+
+The first entry in every debug log is a `startup` diagnostic containing environment and process metadata:
+
+```json
+{
+    "seq": 1,
+    "ts": "2026-03-02T18:42:10.100Z",
+    "category": "startup",
+    "agentTreeSnapshot": {
+        "agents": [],
+        "totalCount": 0,
+        "runningCount": 0,
+        "completedCount": 0,
+        "errorCount": 0
+    },
+    "data": {
+        "pid": 12345,
+        "platform": "linux",
+        "arch": "x64",
+        "nodeVersion": "v22.0.0",
+        "bunVersion": "1.3.10",
+        "cwd": "/home/user/project",
+        "debugConfig": { "enabled": true, "logDir": "..." },
+        "env": { "DEBUG": "1", "NODE_ENV": "development" },
+        "argv": ["bun", "run", "src/cli.ts", "chat", "-a", "opencode"],
+        "memoryUsage": {
+            "rss": 52428800,
+            "heapTotal": 8388608,
+            "heapUsed": 6291456,
+            "external": 1048576
+        }
+    }
+}
+```
+
+#### Bus Error Entry
+
+Captures internal EventBus failures — schema validation drops, handler exceptions, and agent lifecycle contract violations — that would otherwise be swallowed by the TUI:
+
+```json
+{
+    "seq": 42,
+    "ts": "2026-03-02T18:42:15.500Z",
+    "category": "bus_error",
+    "error": "Expected string, received number",
+    "stack": "ZodError: ...",
+    "agentTreeSnapshot": { "agents": [...], "totalCount": 2, "runningCount": 1, "completedCount": 1, "errorCount": 0 },
+    "data": {
+        "kind": "schema_validation",
+        "eventType": "stream.text.delta",
+        "eventData": { "delta": 42 }
+    }
+}
+```
+
+The `kind` field is one of:
+
+- `schema_validation` — event payload failed Zod schema validation and was dropped (never reached subscribers)
+- `handler_error` — a typed event handler threw an exception
+- `wildcard_handler_error` — a wildcard (`onAll`) handler threw an exception
+- `contract_violation` — an agent lifecycle contract was violated (e.g., `stream.agent.complete` received without a prior `stream.agent.start`)
+
+#### Process Error Entry
+
+Captures unhandled exceptions and promise rejections at the process level:
+
+```json
+{
+    "seq": 99,
+    "ts": "2026-03-02T18:43:01.000Z",
+    "category": "process_error",
+    "error": "Cannot read properties of undefined",
+    "stack": "TypeError: Cannot read properties of undefined\n    at ...",
+    "agentTreeSnapshot": { "agents": [...], "totalCount": 3, "runningCount": 2, "completedCount": 1, "errorCount": 0 },
+    "data": { "kind": "uncaughtException", "name": "TypeError" }
+}
+```
+
+### Agent Tree Snapshots
+
+Agent lifecycle events and error entries include an `agentTreeSnapshot` field that shows the aggregate state of all tracked sub-agents at that point in time:
+
+```json
+{
+    "agentTreeSnapshot": {
+        "agents": [
+            {
+                "agentId": "agent-1",
+                "agentType": "worker",
+                "task": "Implement auth module",
+                "status": "running",
+                "isBackground": false,
+                "startedAt": "2026-03-02T18:42:10.300Z",
+                "currentTool": "edit",
+                "toolUses": 5
+            },
+            {
+                "agentId": "agent-2",
+                "agentType": "explore",
+                "task": "Find auth patterns",
+                "status": "completed",
+                "isBackground": false,
+                "startedAt": "2026-03-02T18:42:08.100Z"
+            }
+        ],
+        "totalCount": 2,
+        "runningCount": 1,
+        "completedCount": 1,
+        "errorCount": 0
+    }
+}
+```
+
+Each agent entry tracks:
+
+- `agentId`, `agentType`, `task`: identity and purpose
+- `status`: `"running"`, `"completed"`, or `"error"`
+- `isBackground`: whether the agent was launched in background mode
+- `startedAt`: ISO timestamp of agent start
+- `currentTool`: tool currently being executed (cleared on completion)
+- `toolUses`: cumulative tool call count
+- `error`: error message (present when `status` is `"error"`)
+
+## Pipeline Diagnostic Messages
+
+When `DEBUG=1`, the pipeline logger emits prefixed console messages at key chokepoints. These messages use two log levels:
+
+- **`console.debug`** (via `pipelineLog`) — informational diagnostics (event flow, coalescing, flushing)
+- **`console.error`** (via `pipelineError`) — error-level diagnostics (schema drops, handler errors, workflow failures)
+
+All messages are prefixed with `[Pipeline:<stage>]` for easy filtering:
+
+```text
+[Pipeline:EventBus] schema_drop {"type":"stream.text.delta"}
+[Pipeline:Dispatcher] coalesce {"key":"text","type":"stream.text.delta"}
+[Pipeline:Workflow] start {"workflow":"ralph","sessionId":"abc-123"}
+[Pipeline:Workflow] execution_failed {"workflow":"ralph","nodeId":"planner","error":"timeout"}
+```
+
+### Pipeline Stages
+
+| Stage        | Description                                                                |
+| ------------ | -------------------------------------------------------------------------- |
+| `EventBus`   | Schema validation, handler dispatch errors                                 |
+| `Dispatcher` | Event coalescing, buffer overflow drops, batch flushing                    |
+| `Wire`       | Ownership filtering (owned vs unowned events)                              |
+| `Consumer`   | Event mapping, unmapped event warnings                                     |
+| `Subagent`   | Sub-agent spawn/complete, registry misses                                  |
+| `Workflow`   | Workflow lifecycle — start, complete, execution failures, task save errors |
+
+### Error-Level Actions
+
+The following actions are logged at `console.error` level (via `pipelineError`):
+
+- `EventBus`: `schema_drop`, `handler_error`, `wildcard_handler_error`, `agent_lifecycle_contract_violation`, `contract_failure_turn_terminated`
+- `Workflow`: `session_init_error`, `task_save_error`, `task_flush_error`, `execution_failed`, `execution_error`
+
+## Notes
+
+- Log sessions are named `<timestamp>` (e.g. `2026-03-02T184210`) and each contains:
+    - `events.jsonl`
+    - `raw-stream.log`
+- Log rotation is automatic; Atomic keeps the most recent 10 session folders.
+- This mode is intended for debugging. Keep it off in normal usage for best performance.
+- Both event entries and diagnostic entries share the same `seq` counter, so you can sort by `seq` to get a unified timeline of events and errors.
diff --git a/docs/ui-design-patterns.md b/docs/ui-design-patterns.md
new file mode 100644
index 0000000000..a7f6527cf5
--- /dev/null
+++ b/docs/ui-design-patterns.md
@@ -0,0 +1,120 @@
+# UI Design Patterns
+
+## Iconography
+
+- ● symbol is used at the beginning of text blocks, tool blocks, and sub-agent trees.
+- unicode icons are preferred rather than emojis to ensure consistent rendering across platforms and avoid issues with emoji rendering in certain environments
+
+## Colors
+
+### Status Colors
+
+- **Green ●**: Indicates successful operations, such as completed tasks or successful tool calls.
+- **Yellow ●**: Interrupted operations, such as when a user interrupts an agent or a tool call.
+- **Red ●**: Failed operations, such as when an agent encounters an error or a tool call fails.
+
+## Blocks
+
+## Text Blocks
+
+- Prefixed with ●, text blocks are used to display agent text outputs
+
+### Single-line Text Block
+
+```
+● I'll start by exploring the codebase to understand the current sub-agent design and then create a detailed plan. Let me research the relevant files in parallel.
+```
+
+### Multi-line Text Block
+
+```
+● I've launched 5 research agents in parallel to explore:
+
+  1. Copilot adapter & sub-agent tracking in the workflow SDK
+  2. Copilot SDK source code for event types
+  3. Copilot CLI agent runtime for sub-agent spawning
+  4. Claude adapter as a reference implementation
+  5. UI rendering of the parallel agents tree
+```
+
+### Sub-agents
+
+Sub-agents use a tree-based UI with the following design patterns depending on whether they are invoked in the foreground or background.
+
+**Foreground Sub-agent Invocation**
+
+1. During initialization (no tool calls or streaming started)
+
+    ```
+    ● Running 2 agents…
+    ├─● Locate sub-agent message handling
+    │    ╰  Initializing codebase-locator… (2s)
+    └─● Find sub-agent text rendering code
+         ╰  Initializing codebase-pattern-finder… (5s)
+    ```
+
+2. During execution (tools and tool counts stream for each branch):
+
+    Here's how a correct UI looks during execution:
+
+    ```
+    ● Running 2 agents…
+    ├─● Locate sub-agent message handling
+    │    ╰ codebase-locator: (10 tool uses)
+    │      · rg
+    └─● Find sub-agent text rendering code
+         ╰ codebase-pattern-finder: (5 tool uses)
+           · ls
+    ```
+
+    Here's how an incorrect UI looks:
+
+    ```
+    ● Running 2 codebase-analyzer agents…
+    ├─● codebase-analyzer
+    · 39 tool uses
+    │    ╰  bash (2m 22s)
+    └─● codebase-analyzer
+    · 35 tool uses
+        ╰  view (2m 22s)
+    ```
+
+**Background Sub-agent Invocation**
+
+1. During initialization (no tool calls or streaming started)
+
+```
+● 2 Task agents launched…
+├─● Locate OpenCode SDK integration
+│    ╰  Running codebase-locator in background…
+└─● Analyze SDK tool display patterns
+      ╰  Running codebase-analyzer in background…
+```
+
+Background agent progress is shown via the footer status text below the chatbox:
+
+```
+
+[CHATBOX]
+[N] local agents · ctrl+f to kill all background tasks
+
+```
+
+When the chatbox is streaming AND background agents are running, the footer combines both:
+
+```
+
+[CHATBOX]
+esc to interrupt · ctrl+shift+enter enqueue · [N] local agents · ctrl+f to kill all background tasks
+
+```
+
+2. During execution: N/A, under the chatbox ui contains status and should be updated
+
+3. Finished state:
+
+```
+● Agent "Explore Claude adapter for comparison" completed
+
+● Agent [TASK_DESCRIPTION] completed
+```
\ No newline at end of file
diff --git a/docs/workflow-authors-getting-started.md b/docs/workflow-authors-getting-started.md
new file mode 100644
index 0000000000..cd5d4adaeb
--- /dev/null
+++ b/docs/workflow-authors-getting-started.md
@@ -0,0 +1,150 @@
+# Workflow Authors: Getting Started
+
+This guide is for authors creating custom workflows with the graph SDK and registering workflow metadata for discovery.
+
+## 1) Initialize `WorkflowSDK`
+
+Use `WorkflowSDK.init()` as the single entry point for providers, workflow registration, and runtime defaults.
+
+```ts
+import { WorkflowSDK } from "@bastani/atomic/graph";
+
+const sdk = WorkflowSDK.init({
+  providers: {
+    claude: claudeClient,
+    opencode: opencodeClient,
+    copilot: copilotClient,
+  },
+  checkpointer: "session",
+  validation: true,
+  defaultModel: "claude/claude-sonnet-4.5",
+  maxSteps: 100,
+});
+```
+
+## 2) Build your first workflow graph
+
+Define state as `BaseState` plus your domain fields, then compose nodes with `sdk.graph()` (or templates).
+
+```ts
+import { z } from "zod";
+import { WorkflowSDK, createNode, sequential, type BaseState } from "@bastani/atomic/graph";
+
+interface DraftWorkflowState extends BaseState {
+  prompt?: string;
+  plan?: string;
+  draft?: string;
+}
+
+const planNode = createNode<DraftWorkflowState>(
+  "plan",
+  "tool",
+  async (ctx) => ({
+    stateUpdate: {
+      plan: `Plan for: ${ctx.state.prompt ?? "unknown task"}`,
+    },
+  }),
+  {
+    outputSchema: z.object({
+      executionId: z.string(),
+      lastUpdated: z.string(),
+      outputs: z.record(z.string(), z.unknown()),
+      prompt: z.string().optional(),
+      plan: z.string().optional(),
+      draft: z.string().optional(),
+    }),
+  },
+);
+
+const draftNode = createNode<DraftWorkflowState>("draft", "tool", async (ctx) => ({
+  stateUpdate: {
+    draft: `Drafted from plan: ${ctx.state.plan ?? "missing plan"}`,
+  },
+}));
+
+const graph = sequential<DraftWorkflowState>([planNode, draftNode]).compile({
+  outputSchema: z.object({
+    executionId: z.string(),
+    lastUpdated: z.string(),
+    outputs: z.record(z.string(), z.unknown()),
+    prompt: z.string().optional(),
+    plan: z.string().optional(),
+    draft: z.string().optional(),
+  }),
+});
+
+const result = await sdk.execute(graph, {
+  initialState: { prompt: "Write a release summary" },
+});
+```
+
+## 3) Stream workflow execution
+
+`sdk.stream()` supports multi-mode output (`values`, `updates`, `events`, `debug`).
+
+```ts
+for await (const event of sdk.stream(graph, {
+  initialState: { prompt: "Write a release summary" },
+  modes: ["updates", "events", "debug"],
+})) {
+  if (event.mode === "updates") {
+    console.log("state update:", event.update);
+  }
+}
+```
+
+Use `ctx.emit(type, data)` inside node execution to produce custom `events` mode payloads.
+
+## 4) Use templates to reduce boilerplate
+
+The graph API exports four workflow templates:
+
+- `sequential(nodes, config?)`
+- `mapReduce({ splitter, worker, merger, config? })`
+- `reviewCycle({ executor, reviewer, fixer, until, maxIterations?, config? })`
+- `taskLoop({ decomposer, worker, reviewer?, until?, maxIterations?, config? })`
+
+Templates return `GraphBuilder`, so you can keep chaining before `.compile()`.
+
+## 5) Add workflow metadata for discovery
+
+Custom workflow metadata files are discovered from:
+
+- `.atomic/workflows` (local, highest priority)
+- `~/.atomic/workflows` (global)
+
+Export metadata from your workflow module:
+
+```ts
+export const name = "my-workflow";
+export const description = "My custom workflow";
+export const aliases = ["mw"];
+export const version = "1.0.0";
+export const minSDKVersion = "0.4.19";
+export const stateVersion = 1;
+
+export function migrateState(oldState: unknown, fromVersion: number) {
+  // Return a BaseState-compatible shape for the new version.
+  return {
+    executionId: `migrated-${fromVersion}`,
+    lastUpdated: new Date().toISOString(),
+    outputs: {},
+    previous: oldState,
+  };
+}
+```
+
+If `minSDKVersion` is invalid semver or newer than the current SDK, the loader logs a warning.
+
+## 6) Migration quick reference
+
+Legacy globals were removed from the public graph API.
+
+| Removed API | Use instead |
+| --- | --- |
+| `setClientProvider()` | `WorkflowSDK.init({ providers: ... })` |
+| `setSubagentBridge()` / `getSubagentBridge()` | Managed by `WorkflowSDK.init()` / `sdk.getSubagentBridge()` |
+| `setSubagentRegistry()` | `WorkflowSDK.init({ agents: ... })` |
+| `setWorkflowResolver()` / `getWorkflowResolver()` | `WorkflowSDK.init({ workflows: ... })` |
+
+Ralph state types were moved out of `@bastani/atomic/graph`; import them from `src/workflows/ralph/state.ts` in this repository.
diff --git a/install.ps1 b/install.ps1
index f7715828f5..1413d5946f 100644
--- a/install.ps1
+++ b/install.ps1
@@ -2,6 +2,8 @@
 # Usage: irm https://raw.githubusercontent.com/flora131/atomic/main/install.ps1 | iex
 # Usage with version: iex "& { $(irm https://raw.githubusercontent.com/flora131/atomic/main/install.ps1) } -Version v1.0.0"
 
+[Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidUsingWriteHost', '')]
+[Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidUsingInvokeExpression', '')]
 param(
     [String]$Version = "latest",
     [String]$InstallDir = "",
@@ -13,11 +15,68 @@ $ErrorActionPreference = 'Stop'
 # Configuration
 $GithubRepo = "flora131/atomic"
 $BinaryName = "atomic"
-$BinDir = if ($env:ATOMIC_INSTALL_DIR) { $env:ATOMIC_INSTALL_DIR } elseif ($InstallDir) { $InstallDir } else { "${Home}\.local\bin" }
-$DataDir = if ($env:LOCALAPPDATA) { "${env:LOCALAPPDATA}\atomic" } else { "${Home}\AppData\Local\atomic" }
+$BinDir = $(if ($env:ATOMIC_INSTALL_DIR) { $env:ATOMIC_INSTALL_DIR } elseif ($InstallDir) { $InstallDir } else { "${Home}\.local\bin" })
+$DataDir = $(if ($env:LOCALAPPDATA) { "${env:LOCALAPPDATA}\atomic" } else { "${Home}\AppData\Local\atomic" })
 $AtomicHome = "${Home}\.atomic"
 
-function Sync-GlobalAgentConfigs {
+function Install-BunIfMissing {
+    if (Get-Command bun -ErrorAction SilentlyContinue) {
+        return
+    }
+
+    Write-Info "bun not detected. Installing bun..."
+    try {
+        Invoke-RestMethod "https://bun.sh/install.ps1" | Invoke-Expression
+    } catch {
+        Write-Warn "Failed to install bun automatically: $_"
+    }
+
+    $bunBin = Join-Path $Home ".bun\bin"
+    if (Test-Path (Join-Path $bunBin "bun.exe")) {
+        $env:Path = "${bunBin};${env:Path}"
+    }
+
+    if (Get-Command bun -ErrorAction SilentlyContinue) {
+        Write-Info "bun installed successfully"
+    } else {
+        Write-Warn "Failed to install bun automatically. Install bun manually from https://bun.sh"
+    }
+}
+
+function Install-NpmIfMissing {
+    if (Get-Command npm -ErrorAction SilentlyContinue) {
+        return
+    }
+
+    Write-Info "npm not detected. Installing Node.js/npm..."
+    $installed = $false
+
+    if (Get-Command winget -ErrorAction SilentlyContinue) {
+        winget install --id OpenJS.NodeJS.LTS -e --silent --accept-source-agreements --accept-package-agreements
+        $installed = $LASTEXITCODE -eq 0
+    } elseif (Get-Command choco -ErrorAction SilentlyContinue) {
+        choco install nodejs-lts -y --no-progress
+        $installed = $LASTEXITCODE -eq 0
+    } elseif (Get-Command scoop -ErrorAction SilentlyContinue) {
+        scoop install nodejs-lts
+        $installed = $LASTEXITCODE -eq 0
+    } else {
+        Write-Warn "Could not find winget, choco, or scoop to install npm automatically."
+    }
+
+    $nodeBin = Join-Path ${env:ProgramFiles} "nodejs"
+    if (Test-Path (Join-Path $nodeBin "npm.cmd")) {
+        $env:Path = "${nodeBin};${env:Path}"
+    }
+
+    if ($installed -and (Get-Command npm -ErrorAction SilentlyContinue)) {
+        Write-Info "npm installed successfully"
+    } elseif (-not (Get-Command npm -ErrorAction SilentlyContinue)) {
+        Write-Warn "Failed to install npm automatically. Install Node.js/npm manually."
+    }
+}
+
+function Sync-GlobalAgentConfig {
     param([string]$SourceRoot)
 
     $claudeDir = Join-Path $AtomicHome ".claude"
@@ -48,6 +107,26 @@ function Sync-GlobalAgentConfigs {
 
     Remove-Item -Recurse -Force (Join-Path $copilotDir "workflows") -ErrorAction SilentlyContinue
     Remove-Item -Force (Join-Path $copilotDir "dependabot.yml") -ErrorAction SilentlyContinue
+
+    Install-BunIfMissing
+    Install-NpmIfMissing
+
+    # Install @playwright/cli globally if a package manager is available.
+    # Do not install Chromium browsers here; defer to first use.
+    Write-Info "Installing @playwright/cli globally (if available)..."
+    if (Get-Command bun -ErrorAction SilentlyContinue) {
+        bun install -g @playwright/cli@latest 2>$null
+        if ($LASTEXITCODE -ne 0) {
+            Write-Warn "Failed to install @playwright/cli with bun. Continuing without it."
+        }
+    } elseif (Get-Command npm -ErrorAction SilentlyContinue) {
+        npm install -g @playwright/cli@latest 2>$null
+        if ($LASTEXITCODE -ne 0) {
+            Write-Warn "Failed to install @playwright/cli with npm. Continuing without it."
+        }
+    } else {
+        Write-Warn "Neither bun nor npm found. Install @playwright/cli manually for web browsing capabilities."
+    }
 }
 
 # Colors for output
@@ -178,7 +257,7 @@ try {
     Expand-Archive -Path $TempConfig -DestinationPath $DataDir -Force
 
     Write-Info "Syncing global agent configs to ${AtomicHome}..."
-    Sync-GlobalAgentConfigs -SourceRoot $DataDir
+    Sync-GlobalAgentConfig -SourceRoot $DataDir
 
     # Verify installation
     $VersionOutput = & $BinaryPath --version 2>&1
diff --git a/install.sh b/install.sh
index 7756aade6b..533475331d 100755
--- a/install.sh
+++ b/install.sh
@@ -24,6 +24,72 @@ success() { echo -e "${GREEN}success${NC}: $*"; }
 warn() { echo -e "${YELLOW}warn${NC}: $*"; }
 error() { echo -e "${RED}error${NC}: $*" >&2; exit 1; }
 
+run_with_optional_sudo() {
+    if [[ "$(id -u)" -eq 0 ]]; then
+        "$@"
+    elif command -v sudo >/dev/null 2>&1; then
+        sudo "$@"
+    else
+        return 1
+    fi
+}
+
+install_bun_if_missing() {
+    if command -v bun >/dev/null 2>&1; then
+        return 0
+    fi
+
+    info "bun not detected. Installing bun..."
+    if curl -fsSL https://bun.sh/install | bash >/dev/null 2>&1; then
+        export BUN_INSTALL="${BUN_INSTALL:-$HOME/.bun}"
+        export PATH="$BUN_INSTALL/bin:$PATH"
+    fi
+
+    if command -v bun >/dev/null 2>&1; then
+        info "bun installed successfully"
+        return 0
+    fi
+
+    warn "Failed to install bun automatically. Install bun manually from https://bun.sh"
+    return 1
+}
+
+install_npm_if_missing() {
+    if command -v npm >/dev/null 2>&1; then
+        return 0
+    fi
+
+    info "npm not detected. Installing Node.js/npm..."
+    local installed=0
+
+    if command -v brew >/dev/null 2>&1; then
+        if brew install node >/dev/null 2>&1; then installed=1; fi
+    elif command -v apt-get >/dev/null 2>&1; then
+        if run_with_optional_sudo apt-get update >/dev/null 2>&1 &&
+            run_with_optional_sudo apt-get install -y nodejs npm >/dev/null 2>&1; then
+            installed=1
+        fi
+    elif command -v dnf >/dev/null 2>&1; then
+        if run_with_optional_sudo dnf install -y nodejs npm >/dev/null 2>&1; then installed=1; fi
+    elif command -v yum >/dev/null 2>&1; then
+        if run_with_optional_sudo yum install -y nodejs npm >/dev/null 2>&1; then installed=1; fi
+    elif command -v pacman >/dev/null 2>&1; then
+        if run_with_optional_sudo pacman -Sy --noconfirm nodejs npm >/dev/null 2>&1; then installed=1; fi
+    elif command -v zypper >/dev/null 2>&1; then
+        if run_with_optional_sudo zypper --non-interactive install nodejs npm >/dev/null 2>&1; then installed=1; fi
+    elif command -v apk >/dev/null 2>&1; then
+        if run_with_optional_sudo apk add --no-cache nodejs npm >/dev/null 2>&1; then installed=1; fi
+    fi
+
+    if [[ $installed -eq 1 ]] && command -v npm >/dev/null 2>&1; then
+        info "npm installed successfully"
+        return 0
+    fi
+
+    warn "Failed to install npm automatically. Install Node.js/npm manually."
+    return 1
+}
+
 # Detect platform
 detect_platform() {
     local os arch
@@ -117,7 +183,7 @@ verify_checksum() {
     filename=$(basename "$file")
 
     local expected
-    expected=$(grep "$filename" "$checksums_file" | awk '{print $1}')
+    expected=$(grep -F "$filename" "$checksums_file" | awk '{print $1}')
 
     if [[ -z "$expected" ]]; then
         error "Could not find checksum for $filename"
@@ -162,6 +228,20 @@ sync_global_agent_configs() {
     # Keep Copilot global config focused on skills/agents/instructions/MCP.
     rm -rf "$ATOMIC_HOME/.copilot/workflows" 2>/dev/null || true
     rm -f "$ATOMIC_HOME/.copilot/dependabot.yml" 2>/dev/null || true
+
+    install_bun_if_missing || true
+    install_npm_if_missing || true
+
+    # Install @playwright/cli globally if a package manager is available.
+    # Do not install Chromium browsers here; defer to first use.
+    info "Installing @playwright/cli globally (if available)..."
+    if command -v bun >/dev/null 2>&1; then
+        bun install -g @playwright/cli@latest 2>/dev/null || true
+    elif command -v npm >/dev/null 2>&1; then
+        npm install -g @playwright/cli@latest 2>/dev/null || true
+    else
+        warn "Neither bun nor npm found. Install @playwright/cli manually for web browsing capabilities."
+    fi
 }
 
 # Get latest version
@@ -193,7 +273,7 @@ main() {
     mkdir -p "$BIN_DIR"
     mkdir -p "$DATA_DIR"
     tmp_dir=$(mktemp -d)
-    trap "rm -rf $tmp_dir" EXIT
+    trap 'rm -rf "$tmp_dir"' EXIT
 
     # Download URLs
     local base_url="https://github.com/${GITHUB_REPO}/releases/download/${version}"
diff --git a/oxlint.json b/oxlint.json
index e7c8e5004f..0166ca868b 100644
--- a/oxlint.json
+++ b/oxlint.json
@@ -5,7 +5,8 @@
     },
     "rules": {
         "no-unused-vars": "warn",
-        "no-control-regex": "off"
+        "no-control-regex": "off",
+        "unicorn/no-thenable": "off"
     },
     "ignorePatterns": ["node_modules", "dist", "*.test.ts"]
 }
diff --git a/package.json b/package.json
index 06626e54e1..312904fec0 100644
--- a/package.json
+++ b/package.json
@@ -43,22 +43,23 @@
         "@types/bun": "^1.3.9",
         "@types/ci-info": "^3.1.4",
         "@types/react": "^19.2.14",
-        "lefthook": "^2.1.1",
-        "oxlint": "^1.49.0",
+        "lefthook": "^2.1.2",
+        "oxlint": "^1.51.0",
         "typescript": "^5.9.3"
     },
     "dependencies": {
-        "@anthropic-ai/claude-agent-sdk": "^0.2.50",
-        "@azure/monitor-opentelemetry": "^1.15.1",
+        "@anthropic-ai/claude-agent-sdk": "^0.2.63",
+        "@azure/monitor-opentelemetry": "^1.16.0",
         "@clack/prompts": "^1.0.1",
         "@commander-js/extra-typings": "^14.0.0",
-        "@github/copilot-sdk": "^0.1.25",
-        "@opencode-ai/sdk": "^1.2.10",
+        "@github/copilot-sdk": "^0.1.29",
+        "@opencode-ai/sdk": "^1.2.15",
         "@opentelemetry/api": "^1.9.0",
         "@opentelemetry/api-logs": "^0.212.0",
-        "@opentui/core": "^0.1.81",
-        "@opentui/react": "^0.1.81",
+        "@opentui/core": "^0.1.85",
+        "@opentui/react": "^0.1.85",
         "ci-info": "^4.4.0",
-        "commander": "^14.0.3"
+        "commander": "^14.0.3",
+        "zod": "^4.3.6"
     }
 }
diff --git a/research/docs/2026-02-25-at-command-duplicate-subagent-tree.md b/research/docs/2026-02-25-at-command-duplicate-subagent-tree.md
new file mode 100644
index 0000000000..1a17f80187
--- /dev/null
+++ b/research/docs/2026-02-25-at-command-duplicate-subagent-tree.md
@@ -0,0 +1,436 @@
+---
+date: 2026-02-25 04:46:55 UTC
+researcher: Copilot
+git_commit: 9b083f05a44982ff45dbd5a8bf7c88972a879994
+branch: lavaman131/hotfix/ralph-reliability
+repository: ralph-reliability
+topic: "@ Command Duplicate Sub-Agent Tree Spawning Investigation"
+tags: [research, codebase, at-commands, subagent-tree, duplicate-rendering, parallel-agents, stream-pipeline]
+status: complete
+last_updated: 2026-02-25
+last_updated_by: Copilot
+---
+
+# Research: @ Command Duplicate Sub-Agent Tree Spawning
+
+## Research Question
+
+Why do `@` commands temporarily spawn a duplicate sub-agent tree that then collapses, instead of merging cleanly like the natural language (LLM-driven) pathway?
+
+## Summary
+
+The `@` command pathway and the natural language pathway create sub-agent UI state through **two fundamentally different execution flows** that converge on the same `parallelAgents` React state. The duplicate tree issue stems from a **dual assistant message creation pattern** combined with a **fire-and-forget race condition** in the `@` command pathway. Specifically:
+
+1. **The `@` submit handler creates a placeholder assistant message** (chat.tsx:5665) with `isAgentOnlyStreamRef = true`
+2. **Then `sendSilentMessage` creates a SECOND assistant message** (chat.tsx:3507) with `isAgentOnlyStreamRef = false`, attempting to finalize and remove the first
+3. **Meanwhile, SDK events (`tool.start` → eager agent, `subagent.start` → merge attempt)** create `ParallelAgent` entries in `state.parallelAgents`
+4. **React state batching** means these updates may not be applied atomically, causing a transient state where both the placeholder message and the real streaming message each get their own agent tree rendering
+
+The natural language pathway avoids this because it has a **single linear flow**: user message → SDK stream → `tool.start` → eager agent → `subagent.start` → merge — all through a single assistant message with unified streaming state.
+
+## Detailed Findings
+
+### 1. @ Command Execution Flow (Pathway A)
+
+**Entry point:** `src/ui/chat.tsx:5632-5678`
+
+When a user types `@worker do X` and presses Enter:
+
+#### Step 1: Detection and Parsing
+```
+chat.tsx:5633 → if (trimmedValue.startsWith("@"))
+chat.tsx:5634 → parseAtMentions(trimmedValue)  // from mention-parsing.ts:58-83
+```
+`parseAtMentions()` tokenizes the input, looks up each `@name` in `globalRegistry`, filters for `category === "agent"`, and returns `{ agentName, args }[]`.
+
+#### Step 2: User Message + Placeholder Assistant Message
+```
+chat.tsx:5658 → addMessage("user", trimmedValue)
+chat.tsx:5665 → const assistantMsg = createMessage("assistant", "", true)  // streaming=true
+chat.tsx:5667 → isAgentOnlyStreamRef.current = true  // ⚠️ KEY FLAG #1
+chat.tsx:5668 → isStreamingRef.current = true
+```
+**Creates an empty streaming assistant message** as a container for the agent tree.
+
+#### Step 3: Fire-and-Forget Command Execution
+```
+chat.tsx:5675-5677 →
+  for (const mention of atMentions) {
+    void executeCommand(mention.agentName, mention.args, "mention");
+  }
+  return;  // ⚠️ Returns immediately!
+```
+**Critical:** `void` means the Promises are NOT awaited. `handleSubmit` returns before any agent is actually spawned.
+
+#### Step 4: Inside `executeCommand` → Agent Command → `sendSilentMessage`
+
+`executeCommand` (chat.tsx:3415) looks up the command in `globalRegistry` and calls its `execute()`:
+
+**For Claude/Copilot** (agent-commands.ts:320-325):
+```typescript
+const instruction = `Use the Task tool to invoke the ${agent.name} sub-agent...`;
+context.sendSilentMessage(instruction);
+```
+
+**For OpenCode** (agent-commands.ts:315-319):
+```typescript
+context.sendSilentMessage(task, { agent: agent.name });
+```
+
+#### Step 5: `sendSilentMessage` Creates SECOND Assistant Message
+
+**`sendSilentMessage`** (chat.tsx:3466-3520):
+
+1. **Tries to finalize the first placeholder** (lines 3477-3489):
+   ```typescript
+   const prevStreamingId = streamingMessageIdRef.current;
+   if (prevStreamingId) {
+     setMessagesWindowed((prev) =>
+       prev.map(msg => msg.id === prevStreamingId && msg.streaming
+         ? { ...finalizeStreamingReasoningInMessage(msg), streaming: false }
+         : msg
+       ).filter(msg =>
+         !(msg.id === prevStreamingId && !msg.content.trim())  // Remove if empty
+       )
+     );
+   }
+   ```
+
+2. **Creates a NEW assistant message** (lines 3506-3510):
+   ```typescript
+   const assistantMessage = createMessage("assistant", "", true);
+   streamingMessageIdRef.current = assistantMessage.id;
+   isAgentOnlyStreamRef.current = false;  // ⚠️ KEY: Set to false!
+   ```
+
+**🔴 THE RACE CONDITION:** The `setMessagesWindowed` call at step 5.1 is a React state setter — it schedules an update but **does NOT execute synchronously**. By the time step 5.2 creates the new message and adds it to state, the filter removing the empty placeholder may not have been applied yet. This causes a **transient state with TWO assistant messages**.
+
+#### Step 6: SDK Events Create Agent Tree Entries
+
+After `onSendMessage(content)` fires (chat.tsx:3469), the SDK processes the instruction and:
+
+1. **`tool.start` event** (index.ts:683-754) — Creates **eager ParallelAgent**:
+   ```typescript
+   const newAgent: ParallelAgent = {
+     id: toolId,              // Temporary tool call ID
+     taskToolCallId: toolId,
+     name: agentType,
+     status: isBackground ? "background" : "running",
+     // ...
+   };
+   state.parallelAgents = [...state.parallelAgents, newAgent];
+   state.parallelAgentHandler(state.parallelAgents);  // → setParallelAgents()
+   ```
+
+2. **`subagent.start` event** (index.ts:1181-1350) — Attempts to **merge** with eager agent:
+   ```typescript
+   if (hasEagerAgent && eagerToolId) {
+     // Update existing entry: replace temp ID with real subagentId
+     state.parallelAgents = state.parallelAgents.map(a =>
+       a.id === eagerToolId ? { ...a, id: data.subagentId!, ... } : a
+     );
+   } else {
+     // No eager agent → create fresh (potential duplicate!)
+     state.parallelAgents = [...state.parallelAgents, newAgent];
+   }
+   ```
+
+#### Step 7: `parallelAgents` useEffect Injects Into Message
+
+The `parallelAgents` state change triggers a useEffect (chat.tsx:2870-2889):
+```typescript
+useEffect(() => {
+  if (parallelAgents.length === 0) return;
+  const messageId = streamingMessageIdRef.current;
+  if (messageId) {
+    setMessagesWindowed((prev) =>
+      prev.map((msg, index) => {
+        if (msg.id === messageId && msg.streaming) {
+          return applyStreamPartEvent(msg, {
+            type: "parallel-agents",
+            agents: parallelAgents,
+            isLastMessage: index === prev.length - 1,
+          });
+        }
+        return msg;
+      })
+    );
+  }
+}, [parallelAgents]);
+```
+
+**🔴 THE DUPLICATE TREE:** If both assistant messages still exist in state when this effect fires, and `streamingMessageIdRef.current` points to the **second** one, only the second gets the agent tree. But if React renders between the two state updates, the **first** placeholder message may have briefly received agents from an earlier state update, showing a transient duplicate.
+
+---
+
+### 2. Natural Language Execution Flow (Pathway B)
+
+**Entry point:** Normal `sendMessage` call in `handleSubmit`
+
+1. User sends "use the worker agent to do X"
+2. `sendMessage()` creates a **single** assistant message
+3. SDK streams LLM response
+4. LLM calls Task tool → `tool.start` fires → **single eager ParallelAgent** created
+5. `subagent.start` fires → **merges** with eager agent (updates `id` from temp to real)
+6. `parallelAgents` useEffect applies agents to the **single** streaming message
+7. Tree renders once, cleanly
+
+**Key difference:** Only ONE assistant message exists throughout the entire flow. The `parallelAgents` effect always targets the same message ID.
+
+---
+
+### 3. Comparison Table
+
+| Aspect | @ Command (Pathway A) | Natural Language (Pathway B) |
+|--------|----------------------|---------------------------|
+| Assistant messages created | **2** (placeholder + sendSilentMessage) | **1** |
+| `isAgentOnlyStreamRef` | Set `true`, then `false` | Stays `false` |
+| Command execution | Fire-and-forget (`void`) | Synchronous SDK stream |
+| Agent tree creation | Through `sendSilentMessage` → SDK events | Through SDK events directly |
+| Race condition risk | **HIGH** — multiple async state updates | **LOW** — linear event flow |
+| `streamingMessageIdRef` changes | Changes from msg1.id → msg2.id mid-flow | Stays constant |
+
+---
+
+### 4. Root Cause Analysis
+
+The duplicate tree spawning is caused by a **multi-factor race condition**:
+
+#### Factor 1: Dual Assistant Message Pattern
+The `@` pathway creates TWO assistant messages:
+- Message A: Created at `chat.tsx:5665` (the placeholder)
+- Message B: Created at `chat.tsx:3507` (by `sendSilentMessage`)
+
+The cleanup code (chat.tsx:3477-3489) uses React's `setMessagesWindowed` to remove Message A, but this is **asynchronous**. Both messages coexist transiently.
+
+#### Factor 2: `isAgentOnlyStreamRef` Flag Toggle
+- Set to `true` at line 5667 (for Message A)
+- Set to `false` at line 3509 (for Message B)
+
+This flag affects finalization logic. The toggle creates an inconsistent state where finalization guards (`shouldFinalizeOnToolComplete`, `shouldFinalizeDeferredStream`) may behave differently during the transition.
+
+#### Factor 3: `streamingMessageIdRef` Mutation
+When `sendSilentMessage` creates Message B, it replaces `streamingMessageIdRef.current`:
+```typescript
+// From Message A's ID → Message B's ID
+streamingMessageIdRef.current = assistantMessage.id;
+```
+
+If the `parallelAgents` useEffect fires during the transition, it may apply agents to the **wrong** message, or agents may have been applied to Message A before it's cleaned up.
+
+#### Factor 4: SDK Event Timing
+The `tool.start` and `subagent.start` events fire asynchronously from the SDK. If they arrive before `sendSilentMessage` has finished setting up Message B, the eager agent may be created and associated with Message A's context.
+
+#### Factor 5: Deduplication Timing
+`deduplicateAgents()` in `parallel-agents-tree.tsx:206` runs at **render time**, not at state update time. It successfully merges duplicates by `taskToolCallId` correlation, which is why the tree **collapses** after the initial duplicate appears. The dedup catches up on the next render cycle.
+
+---
+
+### 5. Deduplication System (Why It Eventually Collapses)
+
+The deduplication system in `parallel-agents-tree.tsx` is the reason the duplicate tree eventually resolves:
+
+1. **`deduplicateAgents()`** (line 206) — Groups agents by `taskToolCallId` and merges each group
+2. **`mergeAgentPair()`** (line 249) — Combines two entries, preferring the one with a real task description and higher status priority
+3. **`isLikelyEagerPlaceholder()`** (line 277) — Identifies placeholder agents (where `id === taskToolCallId` or starts with `"tool_"`)
+4. **`canMergeUncorrelatedDuplicate()`** (line 302) — Validates merge candidates by name, task genericness, and background flag
+
+The deduplication runs during component rendering (`AgentPartDisplay` calls `deduplicateAgents` at line 56 before splitting into foreground/background). Once React re-renders with the consolidated state, the duplicates merge.
+
+**The visual artifact occurs because:**
+1. React renders with the duplicate state (before dedup runs on the next render)
+2. Or, two separate `AgentPart` entries exist in the `parts` array (one per assistant message) before Message A is cleaned up
+
+---
+
+### 6. Stream Pipeline Merge Logic
+
+`mergeParallelAgentsIntoParts()` (stream-pipeline.ts:643-771) handles integrating agents into the message parts array:
+
+- **Grouped mode** (`shouldGroupSubagentTrees` returns true): Creates a **single** `AgentPart` with all agents
+- **Per-task mode**: Groups agents by `taskToolCallId` and creates separate `AgentPart` entries per Task tool call group
+
+The `shouldGroupSubagentTrees()` function (line 577) checks:
+1. Is this the last message?
+2. Are all tool parts Task tools (no non-Task tools)?
+3. Are agents active or already grouped?
+
+When the `@` pathway creates its agent, the grouping decision may differ between the two assistant messages, causing different tree layouts that appear as "duplicates."
+
+---
+
+### 7. Historical Context — Precedent: Skill Loading Indicator Duplicate
+
+A nearly identical bug was previously fixed for skill loading indicators (Issue #205):
+
+**Root cause:** Two independent rendering paths both produced the same component:
+- Path A: `skill.invoked` SDK event → `message.skillLoads` → renders indicator
+- Path B: `tool.execution_start` with `toolName === "skill"` → `visibleToolCalls` → renders indicator
+
+**Fix applied:** Filter skill tools from `visibleToolCalls` (chat.tsx:1299-1303):
+```typescript
+const isSkillTool = (name: string) => name === "Skill" || name === "skill";
+const visibleToolCalls = toolCalls.filter(
+  (tc) => !isHitlTool(tc.toolName) && !isSubAgentTool(tc.toolName) && !isSkillTool(tc.toolName)
+);
+```
+
+**Relevance:** The `@` command duplicate tree issue follows the same **dual rendering path** pattern. The architectural fix was to **eliminate one rendering path** rather than trying to coordinate both.
+
+---
+
+### 8. Background Agents SDK Pipeline (Issue #258)
+
+Research from `research/docs/2026-02-23-258-background-agents-sdk-event-pipeline.md` documents a 6-stage pipeline:
+
+```
+Stage 1: SDK emits tool.start / subagent.start / subagent.complete
+Stage 2: UI Integration (index.ts) creates ParallelAgent objects
+Stage 3: UI Integration calls parallelAgentHandler(agents)
+Stage 4: ChatApp receives agents, applies parallel-agents event
+Stage 5: Stream pipeline merges agents into AgentPart objects
+Stage 6: ParallelAgentsTree component renders
+```
+
+For `@` commands, stages 1-2 are complicated by the **`sendSilentMessage` indirection** — the instruction is sent to the SDK as a regular message, and the SDK must then decide to call the Task tool. This adds latency and creates the window for the race condition.
+
+---
+
+## Code References
+
+### @ Command Entry & Dispatch
+- `src/ui/chat.tsx:5632-5678` — Submit handler with `@` detection and fire-and-forget dispatch
+- `src/ui/chat.tsx:3177-3210` — `dispatchQueuedMessage()` for deferred @ mentions during streaming
+- `src/ui/utils/mention-parsing.ts:58-83` — `parseAtMentions()` parser
+- `src/ui/commands/agent-commands.ts:312-328` — Agent command `execute()` with SDK-specific dispatch
+
+### Silent Message (Dual Message Creation)
+- `src/ui/chat.tsx:3466-3520` — `sendSilentMessage()` — creates second assistant message, tries to clean up first
+- `src/ui/chat.tsx:3475-3476` — Comment acknowledging duplicate spinner issue
+- `src/ui/chat.tsx:5660-5664` — Comment explaining placeholder message purpose
+
+### SDK Event Handlers
+- `src/ui/index.ts:683-754` — `tool.start` handler: eager `ParallelAgent` creation
+- `src/ui/index.ts:1181-1350` — `subagent.start` handler: merge-or-create logic
+- `src/ui/index.ts:658-660` — `tool.complete` handler: status finalization
+
+### Agent Tree Deduplication
+- `src/ui/components/parallel-agents-tree.tsx:206-360` — `deduplicateAgents()` and helpers
+- `src/ui/components/parallel-agents-tree.tsx:249-275` — `mergeAgentPair()` merge logic
+- `src/ui/components/parallel-agents-tree.tsx:277-284` — `isLikelyEagerPlaceholder()` detection
+
+### Stream Pipeline
+- `src/ui/parts/stream-pipeline.ts:577-605` — `shouldGroupSubagentTrees()`
+- `src/ui/parts/stream-pipeline.ts:643-771` — `mergeParallelAgentsIntoParts()`
+- `src/ui/parts/stream-pipeline.ts:818-884` — `applyStreamPartEvent()` with `parallel-agents` case
+
+### React State Integration
+- `src/ui/chat.tsx:1789` — `parallelAgents` state declaration
+- `src/ui/chat.tsx:2851-2864` — Handler registration connecting SDK to React
+- `src/ui/chat.tsx:2870-2889` — useEffect injecting agents into streaming message
+
+### SDK Clients
+- `src/sdk/clients/claude.ts:1210-1225` — Subagent event counter tracking
+- `src/sdk/clients/copilot.ts:633-659` — Copilot subagent event mapping
+- `src/sdk/clients/opencode.ts:777-815` — OpenCode agent/subtask part to subagent.start mapping
+
+### Lifecycle Guards
+- `src/ui/parts/guards.ts:20-27` — `shouldFinalizeOnToolComplete()` background guard
+- `src/ui/parts/guards.ts:30-36` — `hasActiveForegroundAgents()`
+
+## Architecture Documentation
+
+### Current Dual-Path Architecture
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                    @ COMMAND PATHWAY                         │
+│                                                              │
+│  User types "@worker do X"                                   │
+│       ↓                                                      │
+│  handleSubmit detects "@" prefix                             │
+│       ↓                                                      │
+│  Creates user message + placeholder assistant (Message A)    │
+│  Sets isAgentOnlyStreamRef = true                            │
+│       ↓                                                      │
+│  void executeCommand("worker", "do X")  ← fire-and-forget   │
+│       ↓                                                      │
+│  agent-commands.ts → sendSilentMessage(instruction)          │
+│       ↓                                                      │
+│  sendSilentMessage:                                          │
+│    1. Tries to remove Message A (async React setState)       │
+│    2. Creates Message B (new assistant message)              │
+│    3. Sets isAgentOnlyStreamRef = false                      │
+│    4. Calls onSendMessage → SDK                              │
+│       ↓                                                      │
+│  ⚠️ TRANSIENT STATE: Both Message A & B may exist briefly   │
+│       ↓                                                      │
+│  SDK processes instruction → LLM calls Task tool             │
+│       ↓                                                      │
+│  tool.start → eager ParallelAgent created                    │
+│  subagent.start → merge with eager agent                     │
+│       ↓                                                      │
+│  parallelAgents useEffect → applies to Message B             │
+│       ↓                                                      │
+│  deduplicateAgents() at render → collapses duplicates        │
+└──────────────────────────────────────────────────────────────┘
+
+┌──────────────────────────────────────────────────────────────┐
+│                NATURAL LANGUAGE PATHWAY                       │
+│                                                              │
+│  User types "use the worker agent to do X"                   │
+│       ↓                                                      │
+│  sendMessage() → creates single assistant message            │
+│       ↓                                                      │
+│  SDK streams LLM response                                    │
+│       ↓                                                      │
+│  LLM calls Task tool                                         │
+│       ↓                                                      │
+│  tool.start → eager ParallelAgent created                    │
+│  subagent.start → merge with eager agent                     │
+│       ↓                                                      │
+│  parallelAgents useEffect → applies to same message          │
+│       ↓                                                      │
+│  ✅ Single message, single tree, clean rendering             │
+└──────────────────────────────────────────────────────────────┘
+```
+
+### Deduplication Defense Layers
+
+The codebase has multiple deduplication layers that eventually resolve the duplicate:
+
+1. **Layer 1 — Eager Merge** (index.ts:1269-1286): `subagent.start` handler merges with eager agent by `taskToolCallId`
+2. **Layer 2 — Pipeline Grouping** (stream-pipeline.ts:643): `mergeParallelAgentsIntoParts` groups by `taskToolCallId`
+3. **Layer 3 — Render-Time Dedup** (parallel-agents-tree.tsx:206): `deduplicateAgents()` catches remaining duplicates
+4. **Layer 4 — Shadow Detection** (background-agent-footer.ts:24-69): `isShadowForegroundAgent()` hides duplicate foreground entries
+
+These layers explain why the duplicate **collapses** — the system catches it, but not before a brief visual flash.
+
+## Historical Context (from research/)
+
+- `research/tickets/2026-02-15-205-skill-loading-indicator-duplicate.md` — Identical dual-path rendering issue for skills, fixed by filtering one path
+- `specs/skill-loading-indicator-duplicate-fix.md` — Established the pattern of filtering tools with dedicated renderers from `visibleToolCalls`
+- `research/docs/2026-02-16-sub-agent-tree-inline-state-lifecycle-research.md` — Documents premature lifecycle finalization at 4+ code sites
+- `research/docs/2026-02-15-sub-agent-tree-status-lifecycle-sdk-parity.md` — Documents two-path agent creation (eager + subagent.start) and SDK parity
+- `research/docs/2026-02-15-subagent-premature-completion-investigation.md` — Detailed root cause of `tool.complete` unconditionally finalizing status
+- `research/docs/2026-02-23-258-background-agents-sdk-event-pipeline.md` — 6-stage pipeline architecture and per-SDK correlation analysis
+- `research/docs/2026-02-06-at-mention-dropdown-research.md` — @ mention dropdown implementation research
+
+## Related Research
+
+- `specs/background-agents-ui-issue-258-parity-hardening.md` — Background agents UI parity spec
+- `specs/background-agents-sdk-pipeline-fix.md` — SDK pipeline fix spec
+- `specs/sub-agent-tree-inline-state-lifecycle-fix.md` — Tree lifecycle fix spec
+- `specs/chat-system-parts-based-rendering.md` — Parts-based rendering architecture spec
+
+## Open Questions
+
+1. **Is the duplicate tree visible across ALL SDKs, or only Claude/Copilot?** The OpenCode path uses `sendSilentMessage(task, { agent: name })` which dispatches differently than Claude/Copilot's instruction-based approach.
+
+2. **Does the `dispatchQueuedMessage()` path (chat.tsx:3177-3210) for queued @ mentions during streaming have the same issue?** It loops through parsed mentions and calls `executeCommand()` for each — same fire-and-forget pattern.
+
+3. **Would eliminating the placeholder assistant message (Message A) and relying solely on `sendSilentMessage`'s message creation (Message B) resolve the issue?** The placeholder was added so "the parallel agents tree view renders right away" (comment at line 5660), but this creates the dual-message problem.
+
+4. **Can the `@` command pathway bypass `sendSilentMessage` entirely and instead use the `spawnSubagent` / `spawnSubagentParallel` bridge directly?** This would create a single, controlled execution path similar to the natural language pathway.
+
+5. **Is there a timing window where the `parallelAgents` useEffect applies agents to Message A before it's cleaned up?** If so, Message A renders a tree, then gets removed — causing the visual "flash" of a duplicate tree.
diff --git a/research/docs/2026-02-25-global-config-sync-mechanism.md b/research/docs/2026-02-25-global-config-sync-mechanism.md
new file mode 100644
index 0000000000..23a79bc72b
--- /dev/null
+++ b/research/docs/2026-02-25-global-config-sync-mechanism.md
@@ -0,0 +1,1232 @@
+# Global Config Sync Mechanism - Atomic CLI
+
+**Date**: 2026-02-25  
+**Analysis Type**: Implementation Documentation  
+**Focus**: How global config synchronization works in Atomic CLI
+
+---
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [Architecture](#architecture)
+3. [Core Utilities Analysis](#core-utilities-analysis)
+4. [Config Path Resolution](#config-path-resolution)
+5. [Global Config Sync Process](#global-config-sync-process)
+6. [Directory Structure](#directory-structure)
+7. [Runtime Config Loading](#runtime-config-loading)
+8. [Agent Detection and Config Usage](#agent-detection-and-config-usage)
+9. [Installation Types](#installation-types)
+10. [Data Flow Diagrams](#data-flow-diagrams)
+
+---
+
+## Overview
+
+The Atomic CLI uses a sophisticated global config sync mechanism to provide baseline agent configurations, skills, and MCP server configs across all agents (Claude, OpenCode, Copilot). The system synchronizes templates from the installation source to `~/.atomic/` and merges them with project-specific and user-specific configurations at runtime.
+
+**Key Design Principles**:
+- **Separation of Concerns**: Global defaults (in `~/.atomic/`) vs. project-local configs (in `.claude/`, `.opencode/`, `.github/`)
+- **SCM-Specific Skills Management**: GitHub/Git vs. Sapling/Phabricator skills are managed per-project, not globally
+- **Multi-Source Config Resolution**: Configs overlay from multiple sources with clear precedence rules
+- **Installation Type Flexibility**: Works across source, npm, and binary installations
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                   Atomic CLI Config System                      │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  ┌──────────────┐    ┌──────────────┐    ┌─────────────────┐  │
+│  │ Config Root  │───▶│ Sync Engine  │───▶│ ~/.atomic/      │  │
+│  │ Detection    │    │              │    │ (Global Store)  │  │
+│  └──────────────┘    └──────────────┘    └─────────────────┘  │
+│         │                     │                    │            │
+│         │                     │                    │            │
+│  ┌──────▼──────────────────────▼────────────────────▼────────┐ │
+│  │             Runtime Config Resolution                      │ │
+│  │  (Merges global + user + project configs per agent)       │ │
+│  └────────────────────────────────────────────────────────────┘ │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Core Utilities Analysis
+
+### 1. `src/utils/atomic-global-config.ts`
+
+This is the heart of the global config sync system. Let me document every function:
+
+#### Constants and Configuration
+
+**Lines 8-34**: Core configuration constants
+
+```typescript
+const ATOMIC_HOME_DIR = join(homedir(), ".atomic");
+```
+- **Purpose**: Defines the global Atomic home directory at `~/.atomic`
+- **Usage**: All global configs are stored here
+
+```typescript
+export const MANAGED_SCM_SKILL_PREFIXES = ["gh-", "sl-"] as const;
+```
+- **Purpose**: Defines which skill name prefixes are SCM-managed
+- **Usage**: Used to identify and exclude SCM skills during global sync
+- **Pattern**: `gh-*` for GitHub/Git, `sl-*` for Sapling/Phabricator
+
+```typescript
+const GLOBAL_AGENT_FOLDER_BY_KEY: Record<AgentKey, string> = {
+  claude: ".claude",
+  opencode: ".opencode",
+  copilot: ".copilot",
+};
+```
+- **Purpose**: Maps agent keys to their global folder names in `~/.atomic/`
+- **Usage**: Used by sync functions to determine destination directories
+
+```typescript
+const TEMPLATE_AGENT_FOLDER_BY_KEY: Record<AgentKey, string> = {
+  claude: AGENT_CONFIG.claude.folder,    // ".claude"
+  opencode: AGENT_CONFIG.opencode.folder, // ".opencode"
+  copilot: AGENT_CONFIG.copilot.folder,   // ".github"
+};
+```
+- **Purpose**: Maps agent keys to their template source folder names
+- **Usage**: Used to locate template configs in the config root
+- **Note**: Copilot templates come from `.github/` but sync to `.copilot/` globally
+
+```typescript
+const REQUIRED_GLOBAL_CONFIG_ENTRIES: Record<AgentKey, string[]> = {
+  claude: ["agents", "skills", "settings.json"],
+  opencode: ["agents", "skills", "opencode.json"],
+  copilot: ["agents", "skills"],
+};
+```
+- **Purpose**: Defines required files/folders for a complete global config per agent
+- **Usage**: Used by `hasAtomicGlobalAgentConfigs()` to validate completeness
+
+```typescript
+const REQUIRED_ATOMIC_HOME_ENTRIES = [
+  ".mcp.json",
+  join(".copilot", "mcp-config.json"),
+] as const;
+```
+- **Purpose**: Defines required MCP config files in `~/.atomic/`
+- **Usage**: Additional validation check for complete global config
+
+#### Public Functions
+
+##### `getAtomicHomeDir()` (line 39)
+
+```typescript
+export function getAtomicHomeDir(): string {
+  return ATOMIC_HOME_DIR;
+}
+```
+- **Purpose**: Returns the path to `~/.atomic/`
+- **Implementation**: Simple constant accessor
+- **Returns**: `"/home/user/.atomic"` (Unix) or `"C:\Users\user\.atomic"` (Windows)
+- **Usage**: Called by external modules needing the global home directory
+
+##### `getAtomicManagedConfigDirs()` (line 46)
+
+```typescript
+export function getAtomicManagedConfigDirs(baseDir: string = ATOMIC_HOME_DIR): string[] {
+  return [
+    join(baseDir, GLOBAL_AGENT_FOLDER_BY_KEY.claude),
+    join(baseDir, GLOBAL_AGENT_FOLDER_BY_KEY.opencode),
+    join(baseDir, GLOBAL_AGENT_FOLDER_BY_KEY.copilot),
+  ];
+}
+```
+- **Purpose**: Returns array of all agent config directories in `~/.atomic/`
+- **Parameters**: Optional `baseDir` override (for testing)
+- **Returns**: Array of 3 paths: `[~/.atomic/.claude, ~/.atomic/.opencode, ~/.atomic/.copilot]`
+- **Usage**: Used to enumerate all managed directories
+
+##### `getAtomicGlobalAgentFolder()` (line 57)
+
+```typescript
+export function getAtomicGlobalAgentFolder(agentKey: AgentKey): string {
+  return GLOBAL_AGENT_FOLDER_BY_KEY[agentKey];
+}
+```
+- **Purpose**: Returns the folder name for a specific agent in `~/.atomic/`
+- **Parameters**: `agentKey` - one of `"claude"`, `"opencode"`, `"copilot"`
+- **Returns**: Folder name like `".claude"` (relative name only, not full path)
+- **Usage**: Building paths dynamically based on agent key
+
+##### `getTemplateAgentFolder()` (line 64)
+
+```typescript
+export function getTemplateAgentFolder(agentKey: AgentKey): string {
+  return TEMPLATE_AGENT_FOLDER_BY_KEY[agentKey];
+}
+```
+- **Purpose**: Returns the source folder name for agent templates
+- **Parameters**: `agentKey` - agent to look up
+- **Returns**: Source folder name (e.g., `".claude"`, `".github"`)
+- **Usage**: Locating template configs during sync
+
+##### `isManagedScmSkillName()` (line 71)
+
+```typescript
+export function isManagedScmSkillName(name: string): boolean {
+  return MANAGED_SCM_SKILL_PREFIXES.some((prefix) => name.startsWith(prefix));
+}
+```
+- **Purpose**: Checks if a skill name is SCM-managed (starts with `gh-` or `sl-`)
+- **Parameters**: `name` - skill directory name
+- **Returns**: `true` if name starts with `gh-` or `sl-`
+- **Implementation**: Uses `Array.some()` to check against both prefixes
+- **Usage**: Filtering skills during sync and project init
+
+##### `pruneManagedScmSkills()` (line 78, private)
+
+```typescript
+async function pruneManagedScmSkills(agentDir: string): Promise<void> {
+  const skillsDir = join(agentDir, "skills");
+  if (!(await pathExists(skillsDir))) return;
+
+  const entries = await readdir(skillsDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (!isManagedScmSkillName(entry.name)) continue;
+    await rm(join(skillsDir, entry.name), { recursive: true, force: true });
+  }
+}
+```
+- **Purpose**: Removes all SCM-managed skill variants from a destination directory
+- **Parameters**: `agentDir` - path to agent config directory
+- **Implementation**:
+  1. Check if `skills/` subdirectory exists (line 80)
+  2. Read all entries in `skills/` (line 82)
+  3. For each directory entry (line 84)
+  4. Skip if not SCM-managed (line 85)
+  5. Delete the skill directory recursively (line 86)
+- **Usage**: Cleanup during global sync to ensure SCM skills don't pollute global configs
+- **Rationale**: SCM skills are project-specific, not global
+
+##### `getManagedScmSkillExcludes()` (line 93, private)
+
+```typescript
+async function getManagedScmSkillExcludes(sourceDir: string): Promise<string[]> {
+  const skillsDir = join(sourceDir, "skills");
+  if (!(await pathExists(skillsDir))) return [];
+
+  const entries = await readdir(skillsDir, { withFileTypes: true });
+  return entries
+    .filter((entry) => entry.isDirectory() && isManagedScmSkillName(entry.name))
+    .map((entry) => join("skills", entry.name));
+}
+```
+- **Purpose**: Builds list of relative paths for SCM skills to exclude during copy
+- **Parameters**: `sourceDir` - source agent config directory
+- **Returns**: Array of relative paths like `["skills/gh-commit", "skills/sl-commit"]`
+- **Implementation**:
+  1. Check if source `skills/` exists (line 95)
+  2. Read all entries (line 97)
+  3. Filter to directories with SCM-managed names (line 98-99)
+  4. Map to relative paths (line 100)
+- **Usage**: Building exclude list for `copyDir()` during global sync
+
+##### `syncAtomicGlobalMcpConfigs()` (line 106, private)
+
+```typescript
+async function syncAtomicGlobalMcpConfigs(configRoot: string, baseDir: string): Promise<void> {
+  const claudeMcpSource = join(configRoot, ".mcp.json");
+  const claudeMcpDestination = join(baseDir, ".mcp.json");
+  if (await pathExists(claudeMcpSource)) {
+    await copyFile(claudeMcpSource, claudeMcpDestination);
+  }
+
+  const copilotMcpSource = join(configRoot, AGENT_CONFIG.copilot.folder, "mcp-config.json");
+  const copilotMcpDestination = join(baseDir, GLOBAL_AGENT_FOLDER_BY_KEY.copilot, "mcp-config.json");
+  if (await pathExists(copilotMcpSource)) {
+    await mkdir(join(baseDir, GLOBAL_AGENT_FOLDER_BY_KEY.copilot), { recursive: true });
+    await copyFile(copilotMcpSource, copilotMcpDestination);
+  }
+}
+```
+- **Purpose**: Syncs MCP server configs from templates to `~/.atomic/`
+- **Parameters**:
+  - `configRoot` - source directory (from `getConfigRoot()`)
+  - `baseDir` - destination directory (typically `~/.atomic/`)
+- **Implementation**:
+  1. **Claude MCP Config** (lines 107-111):
+     - Source: `<configRoot>/.mcp.json`
+     - Destination: `~/.atomic/.mcp.json`
+     - Only copies if source exists
+  2. **Copilot MCP Config** (lines 113-118):
+     - Source: `<configRoot>/.github/mcp-config.json`
+     - Destination: `~/.atomic/.copilot/mcp-config.json`
+     - Creates parent directory if needed (line 116)
+     - Only copies if source exists
+- **Usage**: Called by `syncAtomicGlobalAgentConfigs()` at line 150
+
+##### `syncAtomicGlobalAgentConfigs()` (line 128) **[MAIN SYNC FUNCTION]**
+
+```typescript
+export async function syncAtomicGlobalAgentConfigs(
+  configRoot: string,
+  baseDir: string = ATOMIC_HOME_DIR
+): Promise<void>
+```
+- **Purpose**: Main function to sync all agent configs from templates to `~/.atomic/`
+- **Parameters**:
+  - `configRoot` - source directory containing templates
+  - `baseDir` - destination (defaults to `~/.atomic/`)
+- **Implementation** (lines 132-151):
+  1. **Create base directory** (line 132):
+     ```typescript
+     await mkdir(baseDir, { recursive: true });
+     ```
+     - Ensures `~/.atomic/` exists
+  
+  2. **Iterate all agent keys** (lines 134-148):
+     ```typescript
+     const agentKeys = Object.keys(AGENT_CONFIG) as AgentKey[];
+     for (const agentKey of agentKeys) {
+       const sourceFolder = join(configRoot, getTemplateAgentFolder(agentKey));
+       if (!(await pathExists(sourceFolder))) continue;
+
+       const destinationFolder = join(baseDir, getAtomicGlobalAgentFolder(agentKey));
+       const scmSkillExcludes = await getManagedScmSkillExcludes(sourceFolder);
+
+       await copyDir(sourceFolder, destinationFolder, {
+         exclude: [...AGENT_CONFIG[agentKey].exclude, ...scmSkillExcludes],
+       });
+
+       await pruneManagedScmSkills(destinationFolder);
+     }
+     ```
+     - For each agent (claude, opencode, copilot):
+       - Locate source templates (line 136)
+       - Skip if source doesn't exist (line 137)
+       - Build destination path (line 139)
+       - Get SCM skills to exclude (line 140)
+       - Copy directory with combined exclusions (lines 142-144)
+       - Remove any stale SCM skills (line 147)
+  
+  3. **Sync MCP configs** (line 150):
+     ```typescript
+     await syncAtomicGlobalMcpConfigs(configRoot, baseDir);
+     ```
+
+- **Key Behaviors**:
+  - **Excludes SCM skills**: `gh-*` and `sl-*` skills are never synced globally
+  - **Respects agent-specific exclusions**: Each agent has its own exclude list from `AGENT_CONFIG`
+  - **Prunes stale skills**: Ensures old SCM skills from previous installs are removed
+- **Usage**: Called by:
+  - `postinstall.ts` at line 17
+  - `update.ts` at line 258
+  - `init.ts` at line 366 (via `ensureAtomicGlobalAgentConfigs()`)
+  - `chat.ts` at line 218 (via `ensureAtomicGlobalAgentConfigs()`)
+
+##### `hasAtomicGlobalAgentConfigs()` (line 156)
+
+```typescript
+export async function hasAtomicGlobalAgentConfigs(
+  baseDir: string = ATOMIC_HOME_DIR
+): Promise<boolean>
+```
+- **Purpose**: Checks if complete global configs exist in `~/.atomic/`
+- **Parameters**: Optional `baseDir` override (for testing)
+- **Returns**: `true` if all required configs are present
+- **Implementation** (lines 159-182):
+  1. **Check each agent** (lines 160-173):
+     ```typescript
+     const agentKeys = Object.keys(AGENT_CONFIG) as AgentKey[];
+     for (const agentKey of agentKeys) {
+       const agentDir = join(baseDir, getAtomicGlobalAgentFolder(agentKey));
+       if (!(await pathExists(agentDir))) return false;
+
+       const requiredEntries = REQUIRED_GLOBAL_CONFIG_ENTRIES[agentKey];
+       const entryChecks = await Promise.all(
+         requiredEntries.map((entryName) => pathExists(join(agentDir, entryName)))
+       );
+
+       if (entryChecks.some((exists) => !exists)) {
+         return false;
+       }
+     }
+     ```
+     - Verify agent directory exists (line 163)
+     - Check all required entries for that agent (lines 165-172)
+     - Return `false` if any required entry is missing
+  
+  2. **Check atomic home entries** (lines 175-180):
+     ```typescript
+     const atomicHomeChecks = await Promise.all(
+       REQUIRED_ATOMIC_HOME_ENTRIES.map((entryName) => pathExists(join(baseDir, entryName)))
+     );
+     if (atomicHomeChecks.some((exists) => !exists)) {
+       return false;
+     }
+     ```
+     - Verify MCP configs exist
+
+- **Usage**: Used to determine if sync is needed
+- **Called by**:
+  - `ensureAtomicGlobalAgentConfigs()` at line 192
+  - `postinstall.ts` at line 10 (for verification)
+  - Tests
+
+##### `ensureAtomicGlobalAgentConfigs()` (line 188)
+
+```typescript
+export async function ensureAtomicGlobalAgentConfigs(
+  configRoot: string,
+  baseDir: string = ATOMIC_HOME_DIR
+): Promise<void> {
+  if (await hasAtomicGlobalAgentConfigs(baseDir)) return;
+  await syncAtomicGlobalAgentConfigs(configRoot, baseDir);
+}
+```
+- **Purpose**: Ensures global configs exist, syncing only if needed
+- **Parameters**: Same as `syncAtomicGlobalAgentConfigs()`
+- **Implementation**:
+  1. Check if configs already exist (line 192)
+  2. If not, perform sync (line 193)
+- **Optimization**: Skips sync if configs are already present
+- **Usage**: Called at runtime by:
+  - `init.ts` at line 366 (before configuring project)
+  - `chat.ts` at line 218 (before starting chat)
+
+---
+
+## Config Path Resolution
+
+### 2. `src/utils/config-path.ts`
+
+This module handles the critical task of determining where config templates are stored based on installation type.
+
+#### Installation Type Detection
+
+##### `detectInstallationType()` (line 29)
+
+```typescript
+export function detectInstallationType(): InstallationType {
+  const dir = import.meta.dir;
+
+  // Bun compiled executables use a virtual filesystem with '$bunfs' prefix
+  // On Windows this can manifest as drive letters like 'B:\' when navigating up
+  if (dir.includes("$bunfs") || dir.startsWith("B:\\") || dir.startsWith("b:\\")) {
+    return "binary";
+  }
+
+  // Check for node_modules in path (npm/bun installed)
+  if (dir.includes("node_modules")) {
+    return "npm";
+  }
+
+  // Default to source (development mode)
+  return "source";
+}
+```
+- **Purpose**: Detects how the CLI was installed
+- **Returns**: One of `"source"`, `"npm"`, or `"binary"`
+- **Detection Logic**:
+  1. **Binary** (lines 34-36):
+     - Bun compiled executables use virtual filesystem `$bunfs`
+     - Windows may show as `B:\` or `b:\` drive letter
+  2. **npm** (lines 38-41):
+     - Path contains `node_modules` (npm/bun global install)
+  3. **source** (line 44):
+     - Default for development (running from source code)
+- **Implementation Detail**: Uses `import.meta.dir` which provides the directory of the current module
+- **Usage**: Called by `getConfigRoot()` to determine config location
+
+##### `getBinaryDataDir()` (line 54)
+
+```typescript
+export function getBinaryDataDir(): string {
+  if (isWindows()) {
+    const localAppData = process.env.LOCALAPPDATA || join(process.env.USERPROFILE || "", "AppData", "Local");
+    return join(localAppData, "atomic");
+  }
+
+  const xdgDataHome = process.env.XDG_DATA_HOME || join(process.env.HOME || "", ".local", "share");
+  return join(xdgDataHome, "atomic");
+}
+```
+- **Purpose**: Returns the data directory for binary installations
+- **Implementation**:
+  - **Windows** (lines 56-58):
+    - Uses `%LOCALAPPDATA%\atomic` (e.g., `C:\Users\user\AppData\Local\atomic`)
+    - Falls back to `%USERPROFILE%\AppData\Local\atomic`
+  - **Unix** (lines 61-63):
+    - Follows XDG Base Directory spec
+    - Uses `$XDG_DATA_HOME/atomic` or defaults to `~/.local/share/atomic`
+- **Usage**: Called by `getConfigRoot()` for binary installs
+- **Rationale**: Binary installations can't access source files, so configs are extracted to a data directory
+
+##### `getConfigRoot()` (line 77) **[CRITICAL PATH RESOLVER]**
+
+```typescript
+export function getConfigRoot(): string {
+  const installType = detectInstallationType();
+
+  if (installType === "binary") {
+    const dataDir = getBinaryDataDir();
+
+    if (!existsSync(dataDir)) {
+      throw new Error(
+        `Config data directory not found: ${dataDir}\n\n` +
+          `This usually means the installation is incomplete.\n` +
+          `Please reinstall using the install script:\n` +
+          `  curl -fsSL https://raw.githubusercontent.com/flora131/atomic/main/install.sh | bash`
+      );
+    }
+
+    return dataDir;
+  }
+
+  // For source and npm installs, navigate up from the current file
+  // src/utils/config-path.ts -> ../.. -> src -> .. -> package/repo root
+  return join(import.meta.dir, "..", "..");
+}
+```
+- **Purpose**: Returns the root directory where config templates are stored
+- **Returns**: Absolute path to config root
+- **Implementation by Install Type**:
+  1. **Binary** (lines 80-93):
+     - Returns data directory (e.g., `~/.local/share/atomic`)
+     - Validates directory exists
+     - Throws helpful error if missing
+  2. **Source/npm** (lines 96-98):
+     - Navigates up from current file location
+     - Path calculation: `src/utils/config-path.ts` → `../..` → package root
+     - Example result: `/home/user/projects/playwright-cli`
+- **Usage**: Called by all sync operations to locate source templates
+- **Error Handling**: Provides clear reinstall instructions for corrupted binary installs
+
+##### Helper Functions
+
+```typescript
+export function configDataDirExists(): boolean  // line 105
+export function getBinaryInstallDir(): string   // line 127
+export function getBinaryPath(): string         // line 149
+```
+- **Purpose**: Additional utilities for binary installation management
+- **Not directly related to config sync**, but used by update/install commands
+
+---
+
+## Global Config Sync Process
+
+### 3. `src/scripts/postinstall.ts`
+
+This script runs automatically after npm/bun package installation.
+
+```typescript
+async function main(): Promise<void> {
+  try {
+    await syncAtomicGlobalAgentConfigs(getConfigRoot());
+    await verifyAtomicGlobalConfigSync();
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.warn(`[atomic] Warning: failed to sync ~/.atomic global configs: ${message}`);
+  }
+}
+```
+
+**Execution Flow** (lines 15-26):
+1. **Sync configs** (line 17):
+   - Calls `syncAtomicGlobalAgentConfigs(getConfigRoot())`
+   - Resolves config root based on install type
+   - Syncs all templates to `~/.atomic/`
+
+2. **Verify sync** (line 18):
+   - Calls `verifyAtomicGlobalConfigSync()`
+   - Checks that all required configs exist (lines 9-13)
+   - Throws error if verification fails
+
+3. **Error Handling** (lines 19-22):
+   - Catches all errors during sync
+   - Logs warning but doesn't fail installation
+   - **Design Decision**: Non-blocking so package installation succeeds even if sync fails
+
+**When It Runs**:
+- During `npm install -g @bastani/atomic`
+- During `bun install -g @bastani/atomic`
+- **NOT for binary installs** (binary installs use different mechanism)
+
+---
+
+## Directory Structure
+
+### Expected `~/.atomic/` Structure After Sync
+
+```
+~/.atomic/
+├── .mcp.json                          # Claude MCP config (HTTP servers like deepwiki)
+├── settings.json                      # User preferences (optional, not synced)
+│
+├── .claude/                           # Claude global configs
+│   ├── agents/                        # Custom agent definitions
+│   │   ├── codebase-analyzer.md
+│   │   ├── codebase-locator.md
+│   │   ├── codebase-online-researcher.md
+│   │   ├── codebase-pattern-finder.md
+│   │   ├── codebase-research-analyzer.md
+│   │   ├── codebase-research-locator.md
+│   │   ├── debugger.md
+│   │   ├── reviewer.md
+│   │   └── worker.md
+│   ├── skills/                        # Global skills (NO SCM skills)
+│   │   ├── create-spec/
+│   │   │   └── SKILL.md
+│   │   ├── explain-code/
+│   │   │   └── SKILL.md
+│   │   ├── frontend-design/
+│   │   │   └── SKILL.md
+│   │   ├── init/
+│   │   │   └── SKILL.md
+│   │   ├── prompt-engineer/
+│   │   │   ├── references/
+│   │   │   └── SKILL.md
+│   │   ├── research-codebase/
+│   │   │   └── SKILL.md
+│   │   └── testing-anti-patterns/
+│   │       └── SKILL.md
+│   └── settings.json                  # Claude-specific settings
+│
+├── .opencode/                         # OpenCode global configs
+│   ├── agents/                        # Same agent set as Claude
+│   │   ├── codebase-analyzer.md
+│   │   ├── ... (same 9 agents)
+│   │   └── worker.md
+│   ├── skills/                        # Same global skills (NO SCM skills)
+│   │   ├── create-spec/
+│   │   ├── ... (same 7 skills)
+│   │   └── testing-anti-patterns/
+│   ├── opencode.json                  # OpenCode configuration
+│   ├── package.json                   # OpenCode SDK dependencies
+│   ├── bun.lock
+│   └── node_modules/                  # OpenCode SDK packages
+│       ├── @opencode-ai/
+│       └── zod/
+│
+└── .copilot/                          # Copilot global configs
+    ├── agents/                        # Same agent set as others
+    │   ├── codebase-analyzer.md
+    │   ├── ... (same 9 agents)
+    │   └── worker.md
+    ├── skills/                        # Same global skills (NO SCM skills)
+    │   ├── create-spec/
+    │   ├── ... (same 7 skills)
+    │   └── testing-anti-patterns/
+    └── mcp-config.json                # Copilot MCP config
+```
+
+### What's Inside Each Directory
+
+#### `~/.atomic/.claude/`
+- **agents/**: 9 custom agent definitions (codebase-analyzer, debugger, worker, etc.)
+- **skills/**: 7 global skills (create-spec, explain-code, frontend-design, init, prompt-engineer, research-codebase, testing-anti-patterns)
+- **settings.json**: Claude-specific settings (permissions, etc.)
+- **Excluded**: `gh-*` and `sl-*` skills (project-specific)
+
+#### `~/.atomic/.opencode/`
+- **agents/**: Same 9 agents as Claude
+- **skills/**: Same 7 global skills as Claude
+- **opencode.json**: OpenCode SDK configuration
+- **node_modules/**: OpenCode SDK packages (@opencode-ai/plugin, @opencode-ai/sdk, zod)
+- **package.json**, **bun.lock**: Dependency management for OpenCode SDK
+- **Excluded**: node_modules during sync (from `AGENT_CONFIG.opencode.exclude` at `src/config.ts:47-52`)
+
+#### `~/.atomic/.copilot/`
+- **agents/**: Same 9 agents as others
+- **skills/**: Same 7 global skills as others
+- **mcp-config.json**: Copilot MCP server configuration
+- **Note**: Template source is `.github/` but syncs to `.copilot/` globally
+
+#### `~/.atomic/.mcp.json`
+- **Purpose**: Claude MCP server configuration (shared with project `.mcp.json`)
+- **Format**: `{ "mcpServers": { "<name>": { "type": "http", "url": "...", ... } } }`
+- **Example Content**:
+  ```json
+  {
+      "mcpServers": {
+          "deepwiki": {
+              "type": "http",
+              "url": "https://mcp.deepwiki.com/mcp",
+              "tools": ["ask_question"]
+          }
+      }
+  }
+  ```
+
+#### `~/.atomic/.copilot/mcp-config.json`
+- **Purpose**: Copilot-specific MCP server configuration
+- **Format**: Same as Claude MCP config
+- **Separate from Claude** to support Copilot-specific MCP servers
+
+### What's NOT in `~/.atomic/`
+
+**SCM-Specific Skills** (managed per-project, not globally):
+- `gh-commit/` - GitHub commit skill
+- `gh-create-pr/` - GitHub PR creation skill
+- `sl-commit/` - Sapling commit skill
+- `sl-submit-diff/` - Sapling diff submission skill
+
+**Rationale**: SCM skills depend on project-specific source control configuration, so they're installed per-project during `atomic init`.
+
+---
+
+## Runtime Config Loading
+
+### How Configs Are Used at Runtime
+
+#### 1. Chat Command (`src/commands/chat.ts`)
+
+**Entry Point**: `chatCommand()` at line 196
+
+**Config Loading Flow**:
+1. **Ensure global configs exist** (lines 216-218):
+   ```typescript
+   if (detectInstallationType() !== "source") {
+     await ensureAtomicGlobalAgentConfigs(getConfigRoot());
+   }
+   ```
+   - Skipped for source installs (assumes configs are in place)
+   - For npm/binary installs, ensures `~/.atomic/` is populated
+   - Non-blocking: if sync fails, continues anyway
+
+2. **OpenCode-specific config preparation** (lines 220-225):
+   ```typescript
+   if (agentType === "opencode") {
+     const mergedConfigDir = await prepareOpenCodeConfigDir({ projectRoot });
+     if (mergedConfigDir) {
+       process.env.OPENCODE_CONFIG_DIR = mergedConfigDir;
+     }
+   }
+   ```
+   - Builds merged config directory at `~/.atomic/.tmp/opencode-config-merged/`
+   - Precedence: `~/.atomic/.opencode` < `~/.config/opencode` < `~/.opencode` < `<project>/.opencode`
+   - Sets `OPENCODE_CONFIG_DIR` environment variable for OpenCode SDK
+
+3. **Auto-init if SCM skills missing** (lines 228-237):
+   ```typescript
+   if (await shouldAutoInitChat(agentType, projectRoot)) {
+     await initCommand({
+       showBanner: false,
+       preSelectedAgent: agentType,
+       configNotFoundMessage,
+     });
+   }
+   ```
+   - Checks if project has SCM skills (line 117-132)
+   - If missing, triggers interactive init flow
+   - Copies SCM skills from global templates to project
+
+#### 2. Init Command (`src/commands/init.ts`)
+
+**Entry Point**: `initCommand()` at line 194
+
+**Config Loading Flow**:
+1. **User selects agent and SCM type** (lines 216-286)
+   - Interactive prompts for agent (claude/opencode/copilot) and SCM (github/sapling)
+
+2. **Ensure global configs** (lines 361-367):
+   ```typescript
+   const configRoot = getConfigRoot();
+   if (detectInstallationType() !== "source") {
+     await ensureAtomicGlobalAgentConfigs(configRoot);
+   }
+   ```
+   - Same logic as chat command
+
+3. **Sync project SCM skills** (lines 369-383):
+   ```typescript
+   const templateAgentFolder = getTemplateAgentFolder(agentKey);
+   const sourceSkillsDir = join(configRoot, templateAgentFolder, "skills");
+   const targetSkillsDir = join(targetFolder, "skills");
+
+   const copiedCount = await syncProjectScmSkills({
+     scmType,
+     sourceSkillsDir,
+     targetSkillsDir,
+   });
+   ```
+   - Copies **only** SCM-specific skills matching selected SCM type
+   - E.g., if `scmType === "github"`, copies `gh-commit/` and `gh-create-pr/`
+   - Function `syncProjectScmSkills()` at lines 165-189
+
+4. **Reconcile SCM variants** (lines 386-392):
+   ```typescript
+   await reconcileScmVariants({
+     scmType,
+     agentFolder: agent.folder,
+     skillsSubfolder: "skills",
+     targetDir,
+     configRoot,
+   });
+   ```
+   - Removes stale SCM skills from unselected SCM type
+   - E.g., if switching from Sapling to GitHub, removes `sl-*` skills
+   - Function `reconcileScmVariants()` at lines 78-112
+
+5. **Save config** (lines 395-398):
+   ```typescript
+   await saveAtomicConfig(targetDir, {
+     scm: scmType,
+     agent: agentKey,
+   });
+   ```
+   - Persists selection to `.atomic/settings.json` in project root
+
+### MCP Config Discovery (`src/utils/mcp-config.ts`)
+
+**Entry Point**: `discoverMcpConfigs()` at line 148
+
+**Discovery Process**:
+1. **User-level configs** (lines 160-164):
+   ```typescript
+   addSources(parseClaudeMcpConfig(join(homeDir, ".claude", ".mcp.json")), "claude");
+   addSources(parseCopilotMcpConfig(join(homeDir, ".copilot", "mcp-config.json")), "copilot");
+   addSources(parseOpenCodeMcpConfig(join(homeDir, ".opencode", "opencode.json")), "opencode");
+   ```
+   - Loads from `~/.claude/.mcp.json`, `~/.copilot/mcp-config.json`, `~/.opencode/opencode.json`
+
+2. **Project-level configs** (lines 167-174):
+   ```typescript
+   addSources(parseClaudeMcpConfig(join(projectRoot, ".mcp.json")), "claude");
+   addSources(parseCopilotMcpConfig(join(projectRoot, ".github", "mcp-config.json")), "copilot");
+   addSources(parseOpenCodeMcpConfig(join(projectRoot, "opencode.json")), "opencode");
+   // ... more project-level sources
+   ```
+
+3. **Deduplication with ecosystem isolation** (lines 176-185):
+   ```typescript
+   const byName = new Map<string, TaggedSource>();
+   for (const entry of sources) {
+     const existing = byName.get(entry.config.name);
+     if (!existing || existing.ecosystem === entry.ecosystem) {
+       byName.set(entry.config.name, entry);
+     }
+   }
+   ```
+   - Within same ecosystem (claude/opencode/copilot), project-level overrides user-level
+   - Across ecosystems, configs are independent (no override)
+
+**Result**: Unified list of MCP servers from all sources, passed to SDK clients at chat startup (line 264-272 in `chat.ts`)
+
+---
+
+## Agent Detection and Config Usage
+
+### Agent Detection at Runtime
+
+**Agent detection doesn't happen automatically** - the user explicitly selects or the config specifies the agent type.
+
+#### Selection Methods:
+1. **CLI Flag**: `atomic chat -a claude` (explicit agent selection)
+2. **Saved Config**: `.atomic/settings.json` in project root stores last-used agent
+3. **Auto-Init Prompt**: If no SCM skills exist, user is prompted to select agent
+
+**No Auto-Detection Logic**: The system doesn't detect agents by inspecting installed CLI tools or config directories. The user must explicitly choose.
+
+### How Agent Configs Are Loaded
+
+#### Claude Code
+- **Global Config**: `~/.atomic/.claude/`
+- **Project Config**: `./.claude/`
+- **Discovery**: Claude loads both automatically via its config system
+- **Precedence**: Project config overrides global config
+
+#### OpenCode
+- **Global Config**: `~/.atomic/.opencode/`
+- **User Config**: `~/.config/opencode/` (XDG standard)
+- **Legacy User Config**: `~/.opencode/`
+- **Project Config**: `./.opencode/`
+- **Merged Config**: `~/.atomic/.tmp/opencode-config-merged/` (built at runtime)
+- **Discovery**: Via `OPENCODE_CONFIG_DIR` environment variable set by chat command
+- **Precedence**: Project > Legacy User > XDG User > Global (layered overlay)
+
+#### GitHub Copilot CLI
+- **Global Config**: `~/.atomic/.copilot/`
+- **Project Config**: `./.github/`
+- **Discovery**: Copilot uses native `--add-dir .` flag to discover `.github/agents/` and `.github/skills/`
+- **Precedence**: Project config used directly, global config not auto-loaded by Copilot
+
+---
+
+## Installation Types
+
+### Source Installation (Development Mode)
+
+**Detection**: Path doesn't contain `$bunfs` or `node_modules`
+
+**Config Root**: Repository root (e.g., `/home/user/projects/playwright-cli`)
+
+**Characteristics**:
+- Running via `bun run src/cli.ts`
+- Config templates in `.claude/`, `.opencode/`, `.github/` subdirectories
+- No global sync needed (templates are already accessible)
+- Postinstall script still runs but operates on local directories
+
+**Config Resolution**:
+```
+getConfigRoot() → /home/user/projects/playwright-cli
+syncAtomicGlobalAgentConfigs(configRoot) → copies from .claude/ to ~/.atomic/.claude/
+```
+
+### npm/bun Installation
+
+**Detection**: Path contains `node_modules`
+
+**Config Root**: Package root in node_modules (e.g., `/usr/local/lib/node_modules/@bastani/atomic`)
+
+**Characteristics**:
+- Installed via `npm install -g @bastani/atomic` or `bun install -g @bastani/atomic`
+- Config templates bundled with npm package
+- Postinstall script runs automatically after install
+- Syncs templates to `~/.atomic/` for global access
+
+**Config Resolution**:
+```
+getConfigRoot() → /usr/local/lib/node_modules/@bastani/atomic
+syncAtomicGlobalAgentConfigs(configRoot) → copies from package templates to ~/.atomic/
+```
+
+### Binary Installation
+
+**Detection**: Path contains `$bunfs` or starts with `B:\` on Windows
+
+**Config Root**: Data directory (Unix: `~/.local/share/atomic`, Windows: `%LOCALAPPDATA%\atomic`)
+
+**Characteristics**:
+- Installed via `install.sh` or `install.ps1` scripts
+- Binary executable generated by Bun compiler
+- Config templates extracted to data directory during installation
+- Uses virtual filesystem (`$bunfs`) at runtime
+
+**Config Resolution**:
+```
+getConfigRoot() → ~/.local/share/atomic (or %LOCALAPPDATA%\atomic on Windows)
+syncAtomicGlobalAgentConfigs(configRoot) → copies from data dir to ~/.atomic/
+```
+
+**Installation Process** (see `install.sh`):
+1. Download binary executable to `~/.local/bin/atomic`
+2. Download config archive (`atomic-config-linux-x64.tar.gz`)
+3. Extract archive to `~/.local/share/atomic/`
+4. Archive contains `.claude/`, `.opencode/`, `.github/`, `.mcp.json`
+5. On first run, binary syncs from data dir to `~/.atomic/`
+
+**Update Process** (see `src/commands/update.ts`):
+1. Download new binary and config archive (lines 206-218)
+2. Verify checksums (lines 221-235)
+3. Replace binary (lines 238-246)
+4. Clean install: delete old data dir, extract new configs (lines 252-255)
+5. Sync to `~/.atomic/` (line 258)
+
+---
+
+## Data Flow Diagrams
+
+### Postinstall Sync Flow
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    npm/bun install @bastani/atomic              │
+└────────────────────────────┬────────────────────────────────────┘
+                             │
+                             ▼
+                   ┌─────────────────────┐
+                   │  postinstall.ts     │
+                   │  (automatic)        │
+                   └─────────┬───────────┘
+                             │
+                             ▼
+                ┌────────────────────────────┐
+                │ getConfigRoot()            │
+                │ Detect install type        │
+                └────────┬───────────────────┘
+                         │
+         ┌───────────────┼───────────────┐
+         │               │               │
+         ▼               ▼               ▼
+    "source"         "npm"          "binary"
+  (repo root)  (node_modules)    (data dir)
+         │               │               │
+         └───────────────┴───────────────┘
+                         │
+                         ▼
+          ┌──────────────────────────────┐
+          │ syncAtomicGlobalAgentConfigs │
+          └──────────┬───────────────────┘
+                     │
+        ┌────────────┼────────────┐
+        │            │            │
+        ▼            ▼            ▼
+    .claude/    .opencode/    .github/
+        │            │            │
+        └────────────┴────────────┘
+                     │
+                     ▼
+         ┌───────────────────────┐
+         │ For each agent:       │
+         │ 1. Get SCM excludes   │
+         │ 2. copyDir()          │
+         │ 3. pruneManagedScm    │
+         └───────┬───────────────┘
+                 │
+                 ▼
+         ┌────────────────┐
+         │ ~/.atomic/     │
+         │  ├─ .claude/   │
+         │  ├─ .opencode/ │
+         │  ├─ .copilot/  │
+         │  └─ .mcp.json  │
+         └────────────────┘
+```
+
+### Init Command Flow
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│               User runs: atomic init                            │
+└────────────────────────────┬────────────────────────────────────┘
+                             │
+                             ▼
+                   ┌─────────────────────┐
+                   │ Select Agent Type   │
+                   │ (claude/opencode/   │
+                   │  copilot)           │
+                   └─────────┬───────────┘
+                             │
+                             ▼
+                   ┌─────────────────────┐
+                   │ Select SCM Type     │
+                   │ (github/sapling)    │
+                   └─────────┬───────────┘
+                             │
+                             ▼
+        ┌────────────────────────────────────────┐
+        │ ensureAtomicGlobalAgentConfigs()       │
+        │ (populate ~/.atomic/ if needed)        │
+        └────────────┬───────────────────────────┘
+                     │
+                     ▼
+        ┌────────────────────────────────────────┐
+        │ syncProjectScmSkills()                 │
+        │ Copy ONLY selected SCM skills          │
+        │ e.g., gh-commit/, gh-create-pr/        │
+        └────────────┬───────────────────────────┘
+                     │
+                     ▼
+        ┌────────────────────────────────────────┐
+        │ reconcileScmVariants()                 │
+        │ Remove unselected SCM skills           │
+        │ e.g., remove sl-* if github selected   │
+        └────────────┬───────────────────────────┘
+                     │
+                     ▼
+        ┌────────────────────────────────────────┐
+        │ saveAtomicConfig()                     │
+        │ Save selection to .atomic/settings.json│
+        └────────────┬───────────────────────────┘
+                     │
+                     ▼
+         ┌──────────────────────────┐
+         │ Project ready with:      │
+         │  .claude/skills/         │
+         │    ├─ gh-commit/         │
+         │    └─ gh-create-pr/      │
+         │ (or sl-* for Sapling)    │
+         └──────────────────────────┘
+```
+
+### Chat Runtime Config Resolution
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│            User runs: atomic chat -a opencode                   │
+└────────────────────────────┬────────────────────────────────────┘
+                             │
+                             ▼
+        ┌────────────────────────────────────────┐
+        │ ensureAtomicGlobalAgentConfigs()       │
+        │ Check/populate ~/.atomic/              │
+        └────────────┬───────────────────────────┘
+                     │
+                     ▼
+        ┌────────────────────────────────────────┐
+        │ prepareOpenCodeConfigDir()             │
+        │ (OpenCode only)                        │
+        └────────────┬───────────────────────────┘
+                     │
+           ┌─────────┴─────────┐
+           ▼                   ▼
+    Layer 1: Global      Layer 2: User
+    ~/.atomic/.opencode  ~/.config/opencode
+           │                   │
+           └─────────┬─────────┘
+                     │
+           ┌─────────┴─────────┐
+           ▼                   ▼
+    Layer 3: Legacy      Layer 4: Project
+    ~/.opencode          ./.opencode
+           │                   │
+           └─────────┬─────────┘
+                     │
+                     ▼
+        ┌────────────────────────────────────────┐
+        │ Merged Config Directory                │
+        │ ~/.atomic/.tmp/opencode-config-merged/ │
+        └────────────┬───────────────────────────┘
+                     │
+                     ▼
+        ┌────────────────────────────────────────┐
+        │ Set OPENCODE_CONFIG_DIR env var        │
+        └────────────┬───────────────────────────┘
+                     │
+                     ▼
+        ┌────────────────────────────────────────┐
+        │ shouldAutoInitChat()                   │
+        │ Check if SCM skills exist              │
+        └────────────┬───────────────────────────┘
+                     │
+              ┌──────┴──────┐
+              │             │
+        Yes   ▼             ▼  No
+    ┌─────────────┐   ┌──────────────┐
+    │ Run init    │   │ Start chat   │
+    │ Configure   │   │ session      │
+    │ SCM skills  │   │              │
+    └─────────────┘   └──────────────┘
+```
+
+### MCP Config Discovery Flow
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│              discoverMcpConfigs() called at chat start          │
+└────────────────────────────┬────────────────────────────────────┘
+                             │
+                             ▼
+              ┌──────────────────────────────┐
+              │ Scan User-Level Configs      │
+              │ ~/.claude/.mcp.json          │
+              │ ~/.copilot/mcp-config.json   │
+              │ ~/.opencode/opencode.json    │
+              └──────────┬───────────────────┘
+                         │
+                         ▼
+              ┌──────────────────────────────┐
+              │ Scan Project-Level Configs   │
+              │ ./.mcp.json                  │
+              │ ./.github/mcp-config.json    │
+              │ ./opencode.json              │
+              │ ./.opencode/opencode.json    │
+              └──────────┬───────────────────┘
+                         │
+                         ▼
+              ┌──────────────────────────────┐
+              │ Tag each config with         │
+              │ ecosystem (claude/opencode/  │
+              │ copilot)                     │
+              └──────────┬───────────────────┘
+                         │
+                         ▼
+              ┌──────────────────────────────┐
+              │ Deduplicate by name          │
+              │ - Same ecosystem: project    │
+              │   overrides user             │
+              │ - Different ecosystem:       │
+              │   keep both independently    │
+              └──────────┬───────────────────┘
+                         │
+                         ▼
+              ┌──────────────────────────────┐
+              │ Return unified MCP server    │
+              │ list to SDK client           │
+              └──────────────────────────────┘
+```
+
+---
+
+## Key Takeaways
+
+### Design Principles
+
+1. **Global vs. Project Separation**:
+   - Global configs (`~/.atomic/`) provide baseline agents/skills
+   - Project configs (`.claude/`, `.opencode/`, `.github/`) customize per-project
+   - SCM-specific skills NEVER go global - always per-project
+
+2. **SCM Skill Management**:
+   - `gh-*` and `sl-*` skills excluded during global sync
+   - Installed per-project during `atomic init` based on selected SCM
+   - Reconciliation ensures only selected SCM variant exists
+
+3. **Multi-Source Config Overlay**:
+   - OpenCode: 4 layers (global < xdg < legacy < project)
+   - Claude: 2 layers (global < project)
+   - Copilot: Project-only (global not auto-loaded)
+   - MCP configs: Ecosystem-isolated deduplication
+
+4. **Installation Type Handling**:
+   - Source: Templates in repo, no extraction needed
+   - npm: Templates in node_modules, synced via postinstall
+   - Binary: Templates in data dir, synced on first run/update
+
+### Critical Functions
+
+- **`getConfigRoot()`**: Determines where templates are based on install type
+- **`syncAtomicGlobalAgentConfigs()`**: Main sync function that populates `~/.atomic/`
+- **`ensureAtomicGlobalAgentConfigs()`**: Lazy sync wrapper used at runtime
+- **`prepareOpenCodeConfigDir()`**: Builds merged OpenCode config with 4-layer precedence
+- **`discoverMcpConfigs()`**: Unified MCP server discovery across all config formats
+
+### File Locations
+
+**Templates** (source):
+- Source: `.claude/`, `.opencode/`, `.github/`, `.mcp.json`
+- npm: `node_modules/@bastani/atomic/.claude/`, etc.
+- Binary: `~/.local/share/atomic/.claude/`, etc.
+
+**Global Configs** (destination):
+- Always: `~/.atomic/.claude/`, `~/.atomic/.opencode/`, `~/.atomic/.copilot/`, `~/.atomic/.mcp.json`
+
+**Project Configs**:
+- Claude: `./.claude/`
+- OpenCode: `./.opencode/`
+- Copilot: `./.github/`
+- Shared: `./.atomic/settings.json` (saved SCM/agent selection)
+
+---
+
+## References
+
+### Source Files Analyzed
+
+- `src/utils/atomic-global-config.ts` - Global config sync engine (195 lines)
+- `src/utils/config-path.ts` - Config root resolution (154 lines)
+- `src/scripts/postinstall.ts` - npm install hook (26 lines)
+- `src/commands/init.ts` - Project initialization (434 lines)
+- `src/commands/chat.ts` - Chat runtime entry (312 lines)
+- `src/commands/update.ts` - Binary update mechanism (307 lines)
+- `src/utils/opencode-config.ts` - OpenCode config merging (59 lines)
+- `src/utils/mcp-config.ts` - MCP config discovery (199 lines)
+- `src/config.ts` - Agent configuration definitions (159 lines)
+- `src/utils/copy.ts` - Directory/file copy utilities (244 lines)
+
+### Related Documentation
+
+- `specs/init-config-merge-behavior.md` - Init command behavior
+- `research/docs/2026-01-23-update-data-dir-clean-install.md` - Update mechanism
+- `research/docs/2026-02-08-skill-loading-from-configs-and-ui.md` - Skill loading
+- `specs/mcp-support-and-discovery.md` - MCP config discovery
+
+---
+
+**End of Analysis**
diff --git a/research/docs/2026-02-25-graph-execution-engine-technical-documentation.md b/research/docs/2026-02-25-graph-execution-engine-technical-documentation.md
new file mode 100644
index 0000000000..88e1c093bc
--- /dev/null
+++ b/research/docs/2026-02-25-graph-execution-engine-technical-documentation.md
@@ -0,0 +1,2234 @@
+# Graph Execution Engine - Technical Documentation
+
+**Document Version:** 1.0  
+**Last Updated:** 2024  
+**Purpose:** Comprehensive technical analysis of the graph execution engine implementation
+
+---
+
+## Table of Contents
+
+1. [GraphBuilder (builder.ts)](#1-graphbuilder-builderts)
+2. [GraphExecutor (compiled.ts)](#2-graphexecutor-compiledts)
+3. [Type System (types.ts)](#3-type-system-typests)
+4. [Node Factories (nodes.ts)](#4-node-factories-nodests)
+5. [Error Handling (errors.ts)](#5-error-handling-errorsts)
+6. [Data Flow Summary](#6-data-flow-summary)
+
+---
+
+## 1. GraphBuilder (builder.ts)
+
+### Overview
+
+The `GraphBuilder` class at `src/graph/builder.ts` provides a fluent API for constructing graph-based workflows declaratively. It manages nodes, edges, and control flow structures (conditionals, loops, parallel execution), then compiles them into an executable `CompiledGraph`.
+
+### 1.1 Core State Management
+
+#### Private Fields (lines 138-159)
+
+```typescript
+private nodes: Map<NodeId, NodeDefinition<TState>> = new Map();
+private edges: Edge<TState>[] = [];
+private startNodeId: NodeId | null = null;
+private endNodeIds: Set<NodeId> = new Set();
+private currentNodeId: NodeId | null = null;
+private conditionalStack: ConditionalBranch<TState>[] = [];
+private nodeCounter = 0;
+private errorHandlerId: NodeId | null = null;
+```
+
+**Data Structures:**
+- `nodes`: Map storing all node definitions by ID
+- `edges`: Array of edge objects connecting nodes
+- `startNodeId`: Entry point for graph execution
+- `endNodeIds`: Set of terminal nodes
+- `currentNodeId`: Tracks the current position for chaining operations
+- `conditionalStack`: Stack for nested if/else structures
+- `nodeCounter`: Incremental counter for unique ID generation
+- `errorHandlerId`: Optional global error handler node
+
+### 1.2 Configuration Types
+
+#### LoopConfig (lines 38-50)
+
+```typescript
+export interface LoopConfig<TState extends BaseState = BaseState> {
+  until: EdgeCondition<TState>;
+  maxIterations?: number; // Default: 100
+}
+```
+
+**Purpose:** Configures loop exit conditions and safety limits.
+
+- `until`: Function returning `true` when loop should exit
+- `maxIterations`: Safety limit to prevent infinite loops (default: 100)
+
+#### ParallelConfig (lines 66-86)
+
+```typescript
+export interface ParallelConfig<TState extends BaseState = BaseState> {
+  branches: NodeId[];
+  strategy?: MergeStrategy; // "all" | "race" | "any"
+  merge?: (results: Map<NodeId, unknown>, state: TState) => Partial<TState>;
+}
+```
+
+**Purpose:** Configures parallel branch execution.
+
+- `branches`: Array of node IDs to execute concurrently
+- `strategy`: Controls completion behavior:
+  - `"all"` (default): Wait for all branches (Promise.all semantics)
+  - `"race"`: Wait for first branch (Promise.race semantics)
+  - `"any"`: Wait for first success (Promise.any semantics)
+- `merge`: Optional function to combine branch results into state
+
+#### ConditionalBranch (lines 95-110)
+
+**Internal structure for tracking if/else state:**
+
+```typescript
+interface ConditionalBranch<TState> {
+  decisionNodeId: NodeId;
+  condition: EdgeCondition<TState>;
+  ifBranchStart?: NodeId;
+  ifBranchEnd?: NodeId;
+  elseBranchStart?: NodeId;
+  elseBranchEnd?: NodeId;
+  inElseBranch: boolean;
+}
+```
+
+**Usage:** Pushed to `conditionalStack` by `if()` at line 294, popped by `endif()` at line 339.
+
+### 1.3 Builder Methods
+
+#### start() (lines 221-231)
+
+**Flow:**
+1. Validates that `startNodeId` is null (line 222)
+2. Adds node to graph via `addNode()` (line 226)
+3. Sets `startNodeId` and `currentNodeId` to new node's ID (lines 227-228)
+4. Returns `this` for chaining (line 230)
+
+**State Changes:**
+- `startNodeId`: `null` → `node.id`
+- `currentNodeId`: `null` → `node.id`
+- `nodes`: Adds entry for `node.id`
+
+#### then() (lines 240-269)
+
+**Flow:**
+1. If no start node exists, delegates to `start()` (line 244)
+2. Adds node via `addNode()` (line 247)
+3. Checks for conditional branch context (line 250)
+4. If in conditional branch and `currentNodeId` is null:
+   - Sets `ifBranchStart` or `elseBranchStart` based on `inElseBranch` flag (lines 254-260)
+5. If `currentNodeId` is not null, creates edge from current to new node (line 263)
+6. Updates `currentNodeId` to new node's ID (line 266)
+7. Returns `this` for chaining (line 268)
+
+**Edge Creation:** Line 263 calls `addEdge(this.currentNodeId, node.id)`, appending to `edges` array.
+
+#### if() (lines 277-305)
+
+**Flow:**
+1. Validates `currentNodeId` is not null (line 278)
+2. Generates unique decision node ID via `generateNodeId("decision")` (line 283)
+3. Creates decision node with no-op execute function (lines 284-288)
+4. Adds decision node and edge from current node (lines 290-291)
+5. Pushes `ConditionalBranch` onto stack with:
+   - `decisionNodeId`: The generated ID
+   - `condition`: The provided condition function
+   - `inElseBranch`: `false`
+6. Sets `currentNodeId = null` to signal next `then()` starts branch (line 302)
+
+**Key Detail:** The decision node itself doesn't evaluate conditions—edge conditions at `endif()` handle routing.
+
+#### else() (lines 311-331)
+
+**Flow:**
+1. Pops current branch from stack (line 313)
+2. Validates branch exists and not already in else (lines 315-321)
+3. Records `ifBranchEnd = currentNodeId` (line 324)
+4. Sets `inElseBranch = true` (line 325)
+5. Resets `currentNodeId = null` for else branch start (line 328)
+
+#### endif() (lines 338-391)
+
+**Flow:**
+1. Pops branch from `conditionalStack` (line 339)
+2. Records branch end: `elseBranchEnd` or `ifBranchEnd` depending on state (lines 346-350)
+3. Creates merge node (lines 353-355)
+4. Adds conditional edges:
+   - From decision node to `ifBranchStart` with `condition` (line 359)
+   - From decision node to `elseBranchStart` with `!condition` (line 366)
+   - Or directly to merge node if no else branch (lines 370-376)
+5. Connects branch ends to merge node (lines 380-386)
+6. Sets `currentNodeId = mergeNodeId` (line 388)
+
+**Edge Labeling:** Uses `"if-true"` and `"if-false"` labels (lines 359, 367) for visualization.
+
+#### parallel() (lines 399-434)
+
+**Flow:**
+1. Generates parallel node ID (line 400)
+2. Creates parallel node that stores config in state outputs (lines 402-416)
+3. Adds node and connects from current node (lines 418-424)
+4. Creates edges to all branch nodes with labels `"parallel-{branchId}"` (lines 427-429)
+5. Sets `currentNodeId = parallelNodeId` (line 431)
+
+**State Storage:** Line 408 stores parallel config in `state.outputs[parallelNodeId]` for execution engine access.
+
+#### loop() (lines 456-546)
+
+**Flow:**
+1. Normalizes `bodyNodes` to array (line 461)
+2. Generates `loopStartId` and `loopCheckId` (lines 467-468)
+3. Creates loop start node that initializes iteration counter in state (lines 472-484)
+4. Creates loop check node that increments iteration counter (lines 487-500)
+5. Adds all nodes to graph (lines 503-507)
+6. Connects current node to loop start (lines 510-514)
+7. Chains body nodes together sequentially (lines 521-523)
+8. Creates loop structure: `start → first body → ... → last body → check` (lines 526-527)
+9. Adds conditional edge from check back to first body node when:
+   - `!config.until(state)` AND
+   - `currentIteration < maxIterations`
+   (lines 531-540)
+10. Sets `currentNodeId = loopCheckId` for next node to connect to exit edge (line 543)
+
+**Iteration Tracking:** Uses key `${loopStartId}_iteration` in `state.outputs` (lines 473, 488).
+
+**Loop Structure:** When continuing, returns to the **first** body node (line 533), not the loop start.
+
+#### wait() (lines 554-574)
+
+**Flow:**
+1. If `promptOrNode` is string, creates wait node that emits `human_input_required` signal (lines 559-568)
+2. Otherwise uses provided node directly (line 570)
+3. Delegates to `then()` for node addition (line 573)
+
+**Signal Structure:** Line 562-565 creates signal with `type: "human_input_required"` and `message: promptOrNode`.
+
+#### catch() (lines 582-587)
+
+**Flow:**
+1. Adds handler node to graph (line 583)
+2. Sets `errorHandlerId = handler.id` (line 584)
+3. Returns `this` for chaining (line 586)
+
+**Note:** Error routing is handled by execution engine, not by explicit edges. The ID is stored in config metadata (line 631).
+
+#### end() (lines 593-600)
+
+**Flow:**
+1. If `currentNodeId` is not null, adds to `endNodeIds` set (line 596)
+2. Returns `this` for chaining (line 598)
+
+**Purpose:** Marks terminal nodes explicitly. If not called, `compile()` auto-detects nodes without outgoing edges.
+
+#### compile() (lines 608-643)
+
+**Flow:**
+1. Validates `startNodeId` is not null (line 609)
+2. If `endNodeIds` is empty, finds nodes without outgoing edges (lines 614-620):
+   - Creates set of source nodes from all edges (line 616)
+   - Adds nodes not in this set to `endNodeIds` (lines 617-620)
+3. If `errorHandlerId` is set, adds to config metadata (lines 624-634)
+4. Returns `CompiledGraph` object with:
+   - `nodes`: Cloned map of node definitions
+   - `edges`: Cloned edge array
+   - `startNode`: The start node ID
+   - `endNodes`: Cloned set of end node IDs
+   - `config`: Merged configuration with metadata
+
+**Return Type:** `CompiledGraph<TState>` (line 636)
+
+### 1.4 Helper Methods
+
+#### generateNodeId() (lines 164-166)
+
+**Implementation:**
+```typescript
+private generateNodeId(prefix: string = "node"): NodeId {
+  return `${prefix}_${++this.nodeCounter}`;
+}
+```
+
+**Generates:** `"prefix_N"` where N is incrementing counter.
+
+#### addNode() (lines 171-176)
+
+**Validation:** Throws error if node ID already exists (line 172).
+
+**Action:** Adds to `nodes` map (line 175).
+
+#### addEdge() (lines 181-188)
+
+**Parameters:**
+- `from`: Source node ID
+- `to`: Target node ID
+- `condition`: Optional edge condition function
+- `label`: Optional label for visualization
+
+**Action:** Appends edge object to `edges` array (line 187).
+
+#### createNode() (lines 193-209)
+
+**Purpose:** Factory for creating `NodeDefinition` objects.
+
+**Returns:** Object with `id`, `type`, `execute`, and optional `name`, `description`, `retry` fields.
+
+### 1.5 Query Methods
+
+#### getNode() (lines 651-653)
+
+Returns node definition by ID or `undefined`.
+
+#### getEdgesFrom() (lines 661-663)
+
+Filters `edges` array for edges with `from === nodeId`.
+
+#### getEdgesTo() (lines 671-673)
+
+Filters `edges` array for edges with `to === nodeId`.
+
+---
+
+## 2. GraphExecutor (compiled.ts)
+
+### Overview
+
+The `GraphExecutor` class at `src/graph/compiled.ts` executes compiled graphs using breadth-first traversal with state management, retry logic, checkpointing, and signal handling.
+
+### 2.1 Core Architecture
+
+#### Class Structure (lines 213-224)
+
+```typescript
+export class GraphExecutor<TState extends BaseState = BaseState> {
+  private readonly graph: CompiledGraph<TState>;
+  private readonly config: GraphConfig<TState>;
+
+  constructor(graph: CompiledGraph<TState>) {
+    this.graph = graph;
+    this.config = { ...DEFAULT_GRAPH_CONFIG, ...graph.config };
+  }
+}
+```
+
+**Initialization:** Merges `DEFAULT_GRAPH_CONFIG` with graph-specific config (line 222).
+
+### 2.2 Execution Methods
+
+#### execute() (lines 232-258)
+
+**High-Level Flow:**
+1. Iterates over `stream()` generator (line 235)
+2. Stores each `StepResult` in `lastResult` (line 236)
+3. Breaks on terminal states: `completed`, `failed`, `cancelled`, `paused` (lines 238-246)
+4. Validates result exists (lines 249-251)
+5. Returns `ExecutionResult` with final state, status, and snapshot (lines 253-257)
+
+**Return Type:** `Promise<ExecutionResult<TState>>` containing:
+- `state`: Final workflow state
+- `status`: Terminal execution status
+- `snapshot`: Complete execution snapshot
+
+#### stream() (lines 266-501)
+
+**Generator Function:** `async *stream()` yields `StepResult<TState>` after each node execution.
+
+**Initialization (lines 267-307):**
+
+1. **Generate execution ID** (line 267):
+   ```typescript
+   const executionId = options.executionId ?? generateExecutionId();
+   ```
+   Uses `options.executionId` or generates via `generateExecutionId()` (line 116).
+
+2. **Set max steps** (line 268):
+   ```typescript
+   const maxSteps = options.maxSteps ?? 1000;
+   ```
+
+3. **Initialize telemetry** (lines 272-282):
+   - Creates `WorkflowTracker` if `options.telemetry` provided (lines 272-274)
+   - Tracks workflow start with name and metadata (lines 277-282)
+
+4. **Initialize or resume state** (lines 285-304):
+
+   **If resuming from snapshot** (lines 292-299):
+   ```typescript
+   state = snapshot.state;
+   visitedNodes = [...snapshot.visitedNodes];
+   errors = [...snapshot.errors];
+   signals = [...snapshot.signals];
+   nodeQueue = snapshot.currentNodeId ? [snapshot.currentNodeId] : [];
+   ```
+
+   **If fresh start** (lines 300-304):
+   ```typescript
+   state = initializeExecutionState<TState>(executionId, options.initialState);
+   nodeQueue = [this.graph.startNode];
+   ```
+
+5. **Initialize loop detection** (line 307):
+   ```typescript
+   const executionVisited = new Set<string>();
+   ```
+
+**Main Execution Loop (lines 309-500):**
+
+**While condition** (line 309): `nodeQueue.length > 0 && stepCount < maxSteps`
+
+**Abort check** (lines 311-323):
+- Checks `options.abortSignal?.aborted`
+- If aborted, tracks cancellation and yields `cancelled` status
+- Returns early
+
+**Node retrieval** (lines 325-336):
+1. Shifts next node ID from queue (line 325)
+2. Gets node definition from `graph.nodes` map (line 326)
+3. If not found, records error and continues to next iteration (lines 328-336)
+
+**Loop detection** (lines 338-344):
+1. Creates visit key: `"${currentNodeId}:${stepCount}"` (line 339)
+2. If already visited AND not loop node, skips (lines 340-343)
+3. Adds visit key to `executionVisited` set (line 344)
+4. Uses `isLoopNode()` helper to exempt loop nodes from check (line 340)
+
+**Node execution** (lines 346-392):
+
+1. **Track node enter** (lines 347-350):
+   ```typescript
+   const nodeStartTime = Date.now();
+   if (tracker) tracker.nodeEnter(currentNodeId, node.type);
+   ```
+
+2. **Execute with retry** (line 357):
+   ```typescript
+   result = await this.executeWithRetry(node, state, errors, options.abortSignal);
+   ```
+
+3. **Handle errors** (lines 358-387):
+   - Creates `ExecutionError` object (lines 359-364)
+   - Pushes to `errors` array (line 365)
+   - Tracks telemetry (lines 368-377)
+   - Yields `failed` status with error (lines 379-386)
+   - Returns to stop execution (line 387)
+
+4. **Track node exit** (lines 390-392)
+
+**State update** (lines 395-397):
+```typescript
+if (result.stateUpdate) {
+  state = mergeState(state, result.stateUpdate);
+}
+```
+Uses `mergeState()` helper for immutable merge (line 396).
+
+**Tracking** (lines 400-401):
+```typescript
+visitedNodes.push(currentNodeId);
+stepCount++;
+```
+
+**Signal handling** (lines 404-431):
+
+1. **Human input signal** (lines 408-419):
+   - Searches for `human_input_required` signal (lines 408-410)
+   - If found, yields `paused` status and returns (lines 411-419)
+
+2. **Checkpoint signal** (lines 422-430):
+   - Searches for `checkpoint` signal (line 422)
+   - If found AND checkpointer exists, saves checkpoint (lines 423-430)
+
+3. **Auto-checkpoint** (lines 433-441):
+   - If `config.autoCheckpoint` enabled and checkpointer exists
+   - Saves checkpoint with label `"step_${stepCount}"` (lines 435-440)
+
+**Progress callback** (lines 444-451):
+- Calls `config.onProgress()` if defined (lines 444-451)
+- Emits event with type `"node_completed"`, nodeId, state, and timestamp
+
+**Next node determination** (line 454):
+```typescript
+const nextNodes = this.getNextNodes(currentNodeId, state, result);
+```
+
+**Queue update** (line 457):
+```typescript
+nodeQueue.push(...nextNodes);
+```
+
+**End node detection** (lines 461-462):
+```typescript
+const isEndNode = this.graph.endNodes.has(currentNodeId) && nodeQueue.length === 0;
+```
+
+**Completion tracking** (lines 465-467):
+- If end node reached, tracks completion BEFORE yield (lines 465-467)
+
+**Yield result** (lines 469-474):
+```typescript
+yield {
+  nodeId: currentNodeId,
+  state,
+  result,
+  status: isEndNode ? "completed" : "running",
+};
+```
+
+**Early return on completion** (lines 476-478)
+
+**Max steps exceeded** (lines 482-500):
+- Tracks error telemetry (lines 484-487)
+- Yields `failed` status with error (lines 488-500)
+
+### 2.3 Model Resolution
+
+#### resolveModel() (lines 510-542)
+
+**Purpose:** Determines which LLM model to use for a node based on hierarchy.
+
+**Resolution Order (lines 526-538):**
+
+1. **Node-level model** (lines 527-529):
+   ```typescript
+   if (node.model && node.model !== "inherit") {
+     result = node.model;
+   }
+   ```
+
+2. **Parent context model** (lines 531-533):
+   ```typescript
+   else if (parentContext?.model) {
+     result = parentContext.model;
+   }
+   ```
+
+3. **Graph default model** (lines 535-537):
+   ```typescript
+   else if (this.config.defaultModel && this.config.defaultModel !== "inherit") {
+     result = this.config.defaultModel;
+   }
+   ```
+
+4. **Undefined** (line 539):
+   - Returns `undefined` to let SDK use its default
+
+**Debug Logging:** Lines 517-522 and 540 log resolution details to console.
+
+**Return Type:** `string | undefined`
+
+### 2.4 Retry Logic
+
+#### executeWithRetry() (lines 547-617)
+
+**Parameters:**
+- `node`: Node definition to execute
+- `state`: Current state
+- `errors`: Array of execution errors
+- `abortSignal`: Optional abort signal
+- `parentContext`: Optional parent execution context
+
+**Retry Configuration:** Lines 554-555 get retry config from node or default:
+```typescript
+const retryConfig = node.retry ?? DEFAULT_RETRY_CONFIG;
+```
+
+**Retry Loop (lines 558-614):**
+
+**While condition** (line 558): `attempt < retryConfig.maxAttempts`
+
+**Attempt counter:** Line 559 increments before each try (1-based).
+
+**Try block (lines 561-592):**
+
+1. **Resolve model** (line 563):
+   ```typescript
+   const resolvedModel = this.resolveModel(node, parentContext);
+   ```
+
+2. **Build execution context** (lines 566-577):
+   ```typescript
+   const context: ExecutionContext<TState> = {
+     state,
+     config: this.config as unknown as GraphConfig,
+     errors,
+     abortSignal,
+     model: resolvedModel,
+     emit: (_signal) => { /* Signals collected in result */ },
+     getNodeOutput: (nodeId) => state.outputs[nodeId],
+   };
+   ```
+
+3. **Execute node** (line 580):
+   ```typescript
+   const result = await node.execute(context);
+   ```
+
+4. **Emit progress** (lines 583-590):
+   - Calls `config.onProgress()` if defined
+   - Emits `"node_started"` event
+
+5. **Return result** (line 592)
+
+**Catch block (lines 593-613):**
+
+1. **Capture error** (line 594):
+   ```typescript
+   lastError = error instanceof Error ? error : new Error(String(error));
+   ```
+
+2. **Check retry condition** (lines 597-599):
+   ```typescript
+   if (retryConfig.retryOn && !retryConfig.retryOn(lastError)) {
+     throw lastError;
+   }
+   ```
+
+3. **Last attempt check** (lines 602-604):
+   - If `attempt >= maxAttempts`, throws error
+
+4. **Calculate backoff** (lines 607-609):
+   ```typescript
+   const delay = retryConfig.backoffMs * Math.pow(retryConfig.backoffMultiplier, attempt - 1);
+   ```
+   **Formula:** `backoffMs × (backoffMultiplier ^ (attempt - 1))`
+   
+   **Example:** With defaults (backoffMs=1000, multiplier=2):
+   - Attempt 1: 1000ms (1s)
+   - Attempt 2: 2000ms (2s)
+   - Attempt 3: 4000ms (4s)
+
+5. **Sleep before retry** (line 612):
+   ```typescript
+   await sleep(delay);
+   ```
+
+**Post-loop error** (line 616):
+- Throws `lastError` if all attempts exhausted
+
+### 2.5 Edge Evaluation
+
+#### getNextNodes() (lines 622-651)
+
+**Purpose:** Determines which nodes to execute next based on edges and node result.
+
+**Override handling (lines 628-630):**
+```typescript
+if (result.goto) {
+  return Array.isArray(result.goto) ? result.goto : [result.goto];
+}
+```
+If node returns `goto`, uses that directly (single node or array).
+
+**Edge filtering (line 633):**
+```typescript
+const outgoingEdges = this.graph.edges.filter((e) => e.from === currentNodeId);
+```
+
+**Empty check (lines 635-637):**
+- Returns empty array if no outgoing edges
+
+**Conditional evaluation (lines 640-646):**
+
+```typescript
+const matchingEdges: Edge<TState>[] = [];
+
+for (const edge of outgoingEdges) {
+  if (!edge.condition || edge.condition(state)) {
+    matchingEdges.push(edge);
+  }
+}
+```
+
+**Logic:**
+- If edge has no condition, includes it
+- If edge has condition AND condition returns true, includes it
+- Evaluates conditions with current state
+
+**Deduplication (lines 649-650):**
+```typescript
+const targets = new Set(matchingEdges.map((e) => e.to));
+return Array.from(targets);
+```
+
+**Purpose:** Multiple edges may target same node; set ensures each node queued once.
+
+### 2.6 Checkpointing
+
+#### saveCheckpoint() (lines 656-677)
+
+**Flow:**
+1. Calls `checkpointer.save(executionId, state, label)` (line 663)
+2. If successful, emits progress event (lines 665-671)
+3. If error, logs but doesn't fail (line 675)
+
+**Error Handling:** Catches checkpoint errors to prevent workflow failure (lines 662-676).
+
+#### createSnapshot() (lines 682-695)
+
+**Purpose:** Creates `ExecutionSnapshot` from step result.
+
+**Returns:**
+```typescript
+{
+  executionId: stepResult.state.executionId,
+  state: stepResult.state,
+  status: stepResult.status,
+  currentNodeId: stepResult.nodeId,
+  visitedNodes: [], // Would need tracking during execution
+  errors: stepResult.error ? [stepResult.error] : [],
+  signals: stepResult.result.signals ?? [],
+  startedAt: stepResult.state.lastUpdated,
+  updatedAt: now(),
+  nodeExecutionCount: 0, // Would need tracking
+}
+```
+
+**Note:** Some fields return placeholder values (empty arrays, 0) due to incomplete tracking.
+
+### 2.7 Helper Functions
+
+#### generateExecutionId() (lines 115-117)
+
+**Format:** `"exec_{timestamp}_{random}"` where random is 7-character alphanumeric.
+
+**Implementation:**
+```typescript
+return `exec_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`;
+```
+
+#### now() (lines 122-124)
+
+**Returns:** ISO 8601 timestamp via `new Date().toISOString()`.
+
+#### sleep() (lines 129-131)
+
+**Implementation:**
+```typescript
+return new Promise((resolve) => setTimeout(resolve, ms));
+```
+
+#### isLoopNode() (lines 136-138)
+
+**Logic:**
+```typescript
+return nodeId.includes("loop_start") || nodeId.includes("loop_check");
+```
+
+**Purpose:** Identifies loop-related nodes for exemption from duplicate visit detection.
+
+#### initializeExecutionState() (lines 148-169)
+
+**Flow:**
+1. Creates base state with `executionId`, `lastUpdated`, `outputs` (lines 153-157)
+2. Extracts initial outputs from partial state (line 160)
+3. Merges base state with initial values (lines 162-167)
+4. Ensures `executionId` and `lastUpdated` not overwritten (lines 166-167)
+
+**Return Type:** Fully initialized `TState` extending `BaseState`.
+
+#### mergeState() (lines 179-195)
+
+**Flow:**
+1. Handles outputs specially—merges rather than replaces (lines 184-187):
+   ```typescript
+   const outputs = update.outputs !== undefined
+     ? { ...current.outputs, ...update.outputs }
+     : current.outputs;
+   ```
+2. Spreads current state, update, merged outputs (lines 189-193)
+3. Always updates `lastUpdated` to current time (line 193)
+
+**Immutability:** Creates new object; never mutates `current` or `update`.
+
+---
+
+## 3. Type System (types.ts)
+
+### Overview
+
+The type system at `src/graph/types.ts` defines all core types for the graph execution engine, including state management, node definitions, execution context, and graph structure.
+
+### 3.1 Base Types
+
+#### NodeId (line 64)
+
+```typescript
+export type NodeId = string;
+```
+
+**Purpose:** Unique identifier for nodes. Used throughout for referencing nodes in edges and control flow.
+
+#### NodeType (line 99)
+
+```typescript
+export type NodeType = "agent" | "tool" | "decision" | "wait" | "ask_user" | "subgraph" | "parallel";
+```
+
+**Node Types:**
+- `agent`: AI agent session execution
+- `tool`: Function/tool execution
+- `decision`: Conditional routing
+- `wait`: Legacy human input pause
+- `ask_user`: Structured human input with options
+- `subgraph`: Nested graph execution
+- `parallel`: Concurrent branch execution
+
+#### ModelSpec (line 86)
+
+```typescript
+export type ModelSpec = string | "inherit";
+```
+
+**Special Values:**
+- `"inherit"`: Use model from parent context or graph default
+- Otherwise: SDK-specific model identifier (e.g., `"claude-3-5-sonnet-20241022"`)
+
+### 3.2 State Management
+
+#### BaseState (lines 109-116)
+
+```typescript
+export interface BaseState {
+  executionId: string;
+  lastUpdated: string;
+  outputs: Record<NodeId, unknown>;
+}
+```
+
+**Required Fields:**
+- `executionId`: Unique execution instance identifier
+- `lastUpdated`: ISO timestamp of last state update
+- `outputs`: Map of node outputs keyed by node ID
+
+**Extension:** All workflow states must extend this interface.
+
+#### ContextWindowUsage (lines 121-130)
+
+```typescript
+export interface ContextWindowUsage {
+  inputTokens: number;
+  outputTokens: number;
+  maxTokens: number;
+  usagePercentage: number;
+}
+```
+
+**Purpose:** Tracks token consumption for context window monitoring.
+
+### 3.3 Signals
+
+#### Signal (line 144)
+
+```typescript
+export type Signal =
+  | "context_window_warning"
+  | "checkpoint"
+  | "human_input_required"
+  | "debug_report_generated";
+```
+
+**Signal Types:**
+- `context_window_warning`: Context approaching capacity
+- `checkpoint`: Request to save state
+- `human_input_required`: Pause for user input
+- `debug_report_generated`: Debug report created for error
+
+#### SignalData (lines 153-160)
+
+```typescript
+export interface SignalData {
+  type: Signal;
+  message?: string;
+  data?: Record<string, unknown>;
+}
+```
+
+**Fields:**
+- `type`: The signal type
+- `message`: Optional human-readable message
+- `data`: Additional signal-specific data
+
+### 3.4 Error Handling
+
+#### ExecutionError (lines 169-178)
+
+```typescript
+export interface ExecutionError {
+  nodeId: NodeId;
+  error: Error | string;
+  timestamp: string;
+  attempt: number;
+}
+```
+
+**Fields:**
+- `nodeId`: Where error occurred
+- `error`: The error object or message
+- `timestamp`: ISO timestamp
+- `attempt`: Retry attempt number (1-based)
+
+#### RetryConfig (lines 183-195)
+
+```typescript
+export interface RetryConfig {
+  maxAttempts: number;
+  backoffMs: number;
+  backoffMultiplier: number;
+  retryOn?: (error: Error) => boolean;
+}
+```
+
+**Fields:**
+- `maxAttempts`: Maximum retry attempts (default: 3)
+- `backoffMs`: Initial backoff delay (default: 1000ms)
+- `backoffMultiplier`: Exponential multiplier (default: 2)
+- `retryOn`: Optional predicate to filter retryable errors
+
+**Default Values:** Line 636 defines `DEFAULT_RETRY_CONFIG` with 3/1000/2.
+
+#### DebugReport (lines 202-216)
+
+```typescript
+export interface DebugReport {
+  errorSummary: string;
+  stackTrace?: string;
+  relevantFiles: string[];
+  suggestedFixes: string[];
+  generatedAt: string;
+  nodeId?: NodeId;
+  executionId?: string;
+}
+```
+
+**Purpose:** Contains diagnostic information for error resolution.
+
+### 3.5 Node Execution
+
+#### NodeResult (lines 228-245)
+
+```typescript
+export interface NodeResult<TState extends BaseState = BaseState> {
+  stateUpdate?: Partial<TState>;
+  goto?: NodeId | NodeId[];
+  signals?: SignalData[];
+}
+```
+
+**Fields:**
+- `stateUpdate`: Partial state update to merge
+- `goto`: Override next node(s) to execute
+- `signals`: Signals to emit
+
+**Usage:** Returned by node execution functions.
+
+#### ExecutionContext (lines 253-291)
+
+```typescript
+export interface ExecutionContext<TState extends BaseState = BaseState> {
+  state: TState;
+  config: GraphConfig;
+  errors: ExecutionError[];
+  abortSignal?: AbortSignal;
+  contextWindowUsage?: ContextWindowUsage;
+  contextWindowThreshold?: number;
+  emit?: (signal: SignalData) => void;
+  getNodeOutput?: (nodeId: NodeId) => unknown;
+  model?: string;
+}
+```
+
+**Provided to Node Execute Functions:**
+- `state`: Current workflow state
+- `config`: Graph configuration
+- `errors`: Errors that occurred during execution
+- `abortSignal`: Signal for cancellation
+- `contextWindowUsage`: Current token usage (for agents)
+- `contextWindowThreshold`: Threshold for warnings (0-100)
+- `emit`: Function to emit signals
+- `getNodeOutput`: Get output from previous node
+- `model`: Resolved model for this context
+
+#### NodeExecuteFn (lines 300-302)
+
+```typescript
+export type NodeExecuteFn<TState extends BaseState = BaseState> = (
+  context: ExecutionContext<TState>
+) => Promise<NodeResult<TState>>;
+```
+
+**Purpose:** Type signature for node execution functions.
+
+#### NodeDefinition (lines 309-337)
+
+```typescript
+export interface NodeDefinition<TState extends BaseState = BaseState> {
+  id: NodeId;
+  type: NodeType;
+  execute: NodeExecuteFn<TState>;
+  retry?: RetryConfig;
+  name?: string;
+  description?: string;
+  model?: ModelSpec;
+}
+```
+
+**Core Fields:**
+- `id`: Unique node identifier
+- `type`: Node type (agent/tool/decision/etc.)
+- `execute`: Execution function
+- `retry`: Optional retry configuration
+- `name`: Human-readable name
+- `description`: What the node does
+- `model`: Model specification (for agent nodes)
+
+### 3.6 Graph Structure
+
+#### Edge (lines 435-447)
+
+```typescript
+export interface Edge<TState extends BaseState = BaseState> {
+  from: NodeId;
+  to: NodeId;
+  condition?: EdgeCondition<TState>;
+  label?: string;
+}
+```
+
+**Fields:**
+- `from`: Source node ID
+- `to`: Target node ID
+- `condition`: Optional condition function (edge followed if returns true)
+- `label`: Optional label for visualization
+
+#### EdgeCondition (lines 426-428)
+
+```typescript
+export type EdgeCondition<TState extends BaseState = BaseState> = (
+  state: TState
+) => boolean;
+```
+
+**Purpose:** Function type for conditional edges. Returns true if edge should be followed.
+
+#### CompiledGraph (lines 459-470)
+
+```typescript
+export interface CompiledGraph<TState extends BaseState = BaseState> {
+  nodes: Map<NodeId, NodeDefinition<TState>>;
+  edges: Edge<TState>[];
+  startNode: NodeId;
+  endNodes: Set<NodeId>;
+  config: GraphConfig<TState>;
+}
+```
+
+**Created By:** `GraphBuilder.compile()` at `builder.ts:608`.
+
+**Fields:**
+- `nodes`: Map of all node definitions
+- `edges`: Array of all edges
+- `startNode`: Entry point node ID
+- `endNodes`: Set of terminal node IDs
+- `config`: Graph configuration
+
+### 3.7 Graph Configuration
+
+#### GraphConfig (lines 364-413)
+
+```typescript
+export interface GraphConfig<TState extends BaseState = BaseState> {
+  checkpointer?: Checkpointer<TState>;
+  maxConcurrency?: number;
+  timeout?: number;
+  onProgress?: (event: ProgressEvent<TState>) => void;
+  contextWindowThreshold?: number;
+  autoCheckpoint?: boolean;
+  metadata?: Record<string, unknown>;
+  defaultModel?: ModelSpec;
+}
+```
+
+**Configuration Options:**
+- `checkpointer`: Checkpoint storage implementation
+- `maxConcurrency`: Max concurrent nodes (default: 1)
+- `timeout`: Max execution time in milliseconds
+- `onProgress`: Callback for progress events
+- `contextWindowThreshold`: Threshold percentage for context warnings (default: 45)
+- `autoCheckpoint`: Auto-checkpoint after each node (default: true)
+- `metadata`: Custom metadata for checkpoints
+- `defaultModel`: Default model for agent nodes
+
+**Default Values:** Lines 645-649 define `DEFAULT_GRAPH_CONFIG`.
+
+#### ProgressEvent (lines 346-357)
+
+```typescript
+export interface ProgressEvent<TState extends BaseState = BaseState> {
+  type: "node_started" | "node_completed" | "node_error" | "checkpoint_saved";
+  nodeId: NodeId;
+  state: TState;
+  error?: ExecutionError;
+  timestamp: string;
+}
+```
+
+**Event Types:**
+- `node_started`: Node execution began
+- `node_completed`: Node execution finished successfully
+- `node_error`: Node execution failed
+- `checkpoint_saved`: State checkpoint saved
+
+### 3.8 Execution State
+
+#### ExecutionStatus (line 479)
+
+```typescript
+export type ExecutionStatus =
+  | "pending"
+  | "running"
+  | "paused"
+  | "completed"
+  | "failed"
+  | "cancelled";
+```
+
+**Status Values:**
+- `pending`: Not yet started
+- `running`: Currently executing
+- `paused`: Waiting for human input
+- `completed`: Successfully finished
+- `failed`: Terminated with error
+- `cancelled`: Aborted by user/system
+
+#### ExecutionSnapshot (lines 493-516)
+
+```typescript
+export interface ExecutionSnapshot<TState extends BaseState = BaseState> {
+  executionId: string;
+  state: TState;
+  status: ExecutionStatus;
+  currentNodeId?: NodeId;
+  visitedNodes: NodeId[];
+  errors: ExecutionError[];
+  signals: SignalData[];
+  startedAt: string;
+  updatedAt: string;
+  completedAt?: string;
+  nodeExecutionCount: number;
+}
+```
+
+**Purpose:** Complete state snapshot for checkpointing and resumption.
+
+**Fields:**
+- `executionId`: Unique execution identifier
+- `state`: Current workflow state
+- `status`: Current execution status
+- `currentNodeId`: Currently executing node (if running)
+- `visitedNodes`: IDs of completed nodes
+- `errors`: All errors that occurred
+- `signals`: All emitted signals
+- `startedAt`: Start timestamp
+- `updatedAt`: Last update timestamp
+- `completedAt`: Completion timestamp (if completed)
+- `nodeExecutionCount`: Total nodes executed
+
+### 3.9 Checkpointer Interface
+
+#### Checkpointer (lines 25-54)
+
+```typescript
+export interface Checkpointer<TState extends BaseState = BaseState> {
+  save(executionId: string, state: TState, label?: string): Promise<void>;
+  load(executionId: string): Promise<TState | null>;
+  list(executionId: string): Promise<string[]>;
+  delete(executionId: string, label?: string): Promise<void>;
+}
+```
+
+**Methods:**
+- `save()`: Save checkpoint with optional label
+- `load()`: Load most recent checkpoint
+- `list()`: List all checkpoint labels for execution
+- `delete()`: Delete checkpoint(s)
+
+**Implementations:** See `checkpointer.ts` for `MemorySaver`, `FileSaver`, `ResearchDirSaver`.
+
+### 3.10 Workflow Tool Context
+
+#### WorkflowToolContext (lines 660-677)
+
+```typescript
+export interface WorkflowToolContext {
+  sessionID: string;
+  messageID: string;
+  agent: string;
+  directory: string;
+  abort: AbortSignal;
+  workflowState: Readonly<Record<string, unknown>>;
+  nodeId: string;
+  executionId: string;
+}
+```
+
+**Purpose:** Extended context for custom tools invoked from graph nodes.
+
+**Fields:**
+- `sessionID`: Maps to execution ID
+- `messageID`: Unique message ID for tool invocation
+- `agent`: Set to `"workflow"` for graph-invoked tools
+- `directory`: Current working directory
+- `abort`: Abort signal for timeout/cancellation
+- `workflowState`: Read-only snapshot of workflow state
+- `nodeId`: The graph node invoking this tool
+- `executionId`: Workflow execution ID
+
+**Usage:** Passed to custom tool handlers via `customToolNode()` at `nodes.ts:1641`.
+
+### 3.11 Constants
+
+#### BACKGROUND_COMPACTION_THRESHOLD (line 629)
+
+```typescript
+export const BACKGROUND_COMPACTION_THRESHOLD = 0.45;
+```
+
+**Usage:** Context compaction triggers at 45% usage.
+
+#### BUFFER_EXHAUSTION_THRESHOLD (line 631)
+
+```typescript
+export const BUFFER_EXHAUSTION_THRESHOLD = 0.6;
+```
+
+**Usage:** Context buffer exhaustion at 60% usage.
+
+---
+
+## 4. Node Factories (nodes.ts)
+
+### Overview
+
+The `nodes.ts` file at `src/graph/nodes.ts` (1838 lines) provides factory functions for creating typed graph nodes. Each factory returns a `NodeDefinition` with appropriate type and execute function.
+
+### 4.1 Agent Node
+
+#### agentNode() (lines 170-270)
+
+**Purpose:** Creates a node that executes an AI agent session.
+
+**Configuration Type:** `AgentNodeConfig<TState>` (lines 64-101)
+
+**Key Fields:**
+- `id`: Node identifier
+- `agentType`: `"claude" | "opencode" | "copilot"`
+- `systemPrompt`: System prompt for agent
+- `tools`: Available tools (string array)
+- `outputMapper`: Function to map agent messages to state
+- `buildMessage`: Function to build user message from state
+- `sessionConfig`: Additional session configuration
+- `retry`: Retry configuration (default: `AGENT_NODE_RETRY_CONFIG` at line 138)
+
+**Execution Flow (lines 192-268):**
+
+1. **Get client** (line 193):
+   ```typescript
+   const client = globalClientProvider?.(agentType);
+   ```
+   Uses global client provider set via `setClientProvider()` (line 121).
+
+2. **Validate client exists** (lines 195-200):
+   Throws error if no client provider set.
+
+3. **Build session config** (lines 203-208):
+   ```typescript
+   const fullSessionConfig: SessionConfig = {
+     ...sessionConfig,
+     model: ctx.model ?? sessionConfig?.model,
+     systemPrompt: systemPrompt ?? sessionConfig?.systemPrompt,
+     tools: tools ?? sessionConfig?.tools,
+   };
+   ```
+   Merges node config with resolved model from context.
+
+4. **Create session** (line 211):
+   ```typescript
+   const session = await client.createSession(fullSessionConfig);
+   ```
+
+5. **Build and send message** (lines 215-221):
+   ```typescript
+   const message = buildMessage ? buildMessage(ctx.state) : "";
+   const messages: AgentMessage[] = [];
+   for await (const chunk of session.stream(message)) {
+     messages.push(chunk);
+   }
+   ```
+   Streams agent response and collects messages.
+
+6. **Get context usage** (line 224):
+   ```typescript
+   const contextUsage = await session.getContextUsage();
+   ```
+
+7. **Map output to state** (lines 228-239):
+   - If `outputMapper` provided, calls it with messages and state (line 230)
+   - Otherwise stores messages in `outputs[id]` (lines 233-238)
+
+8. **Check context window** (lines 245-258):
+   - Calculates usage percentage (lines 246-249)
+   - If exceeds threshold, emits `context_window_warning` signal (lines 251-257)
+
+9. **Return result** (lines 260-263):
+   ```typescript
+   return {
+     stateUpdate,
+     signals: signals.length > 0 ? signals : undefined,
+   };
+   ```
+
+10. **Cleanup** (line 266):
+    ```typescript
+    await session.destroy();
+    ```
+    Always executed via finally block.
+
+**Retry Config:** Lines 138-142 define `AGENT_NODE_RETRY_CONFIG`:
+- `maxAttempts: 3`
+- `backoffMs: 1000`
+- `backoffMultiplier: 2`
+
+**Client Provider:** Global variable `globalClientProvider` at line 113, set via `setClientProvider()` at line 120.
+
+### 4.2 Tool Node
+
+#### toolNode() (lines 369-437)
+
+**Purpose:** Creates a node that executes a specific tool function.
+
+**Configuration Type:** `ToolNodeConfig<TState, TArgs, TResult>` (lines 305-345)
+
+**Key Fields:**
+- `id`: Node identifier
+- `toolName`: Name of the tool
+- `execute`: Tool execution function (required)
+- `args`: Static args or function to build from state
+- `outputMapper`: Function to map result to state
+- `timeout`: Execution timeout in milliseconds
+- `retry`: Retry configuration (default: `DEFAULT_RETRY_CONFIG`)
+
+**Execution Flow (lines 396-435):**
+
+1. **Resolve arguments** (line 398):
+   ```typescript
+   const resolvedArgs = typeof args === "function" ? args(ctx.state) : args;
+   ```
+
+2. **Setup timeout** (lines 401-408):
+   ```typescript
+   const abortController = new AbortController();
+   if (timeout) {
+     timeoutId = setTimeout(() => {
+       abortController.abort(new Error(`Tool "${toolName}" timed out after ${timeout}ms`));
+     }, timeout);
+   }
+   ```
+
+3. **Execute tool** (line 412):
+   ```typescript
+   const result = await execute(resolvedArgs as TArgs, abortController.signal);
+   ```
+
+4. **Map output** (lines 417-427):
+   - If `outputMapper` provided, uses it (line 418)
+   - Otherwise stores result in `outputs[id]` (lines 421-426)
+
+5. **Return result** (line 429)
+
+6. **Cleanup timeout** (lines 431-433):
+   ```typescript
+   if (timeoutId) {
+     clearTimeout(timeoutId);
+   }
+   ```
+   Always executed via finally block.
+
+### 4.3 Decision Node
+
+#### decisionNode() (lines 593-615)
+
+**Purpose:** Creates a node that routes based on conditions.
+
+**Configuration Type:** `DecisionNodeConfig<TState>` (lines 551-569)
+
+**Key Fields:**
+- `id`: Node identifier
+- `routes`: Array of `{ condition, target, label? }` objects
+- `fallback`: Default target if no route matches
+
+**DecisionRoute Type (lines 535-544):**
+```typescript
+export interface DecisionRoute<TState extends BaseState = BaseState> {
+  condition: (state: TState) => boolean;
+  target: NodeId;
+  label?: string;
+}
+```
+
+**Execution Flow (lines 603-613):**
+
+1. **Evaluate routes in order** (lines 605-609):
+   ```typescript
+   for (const route of routes) {
+     if (route.condition(ctx.state)) {
+       return { goto: route.target };
+     }
+   }
+   ```
+
+2. **Use fallback** (line 612):
+   ```typescript
+   return { goto: fallback };
+   ```
+
+**Routing Logic:** First matching route wins. Conditions evaluated with current state.
+
+### 4.4 Wait Node
+
+#### waitNode() (lines 683-718)
+
+**Purpose:** Creates a node that pauses for human input.
+
+**Configuration Type:** `WaitNodeConfig<TState>` (lines 636-660)
+
+**Key Fields:**
+- `id`: Node identifier
+- `prompt`: Static string or function to build from state
+- `autoApprove`: If true, auto-approves and continues (for testing)
+- `inputMapper`: Function to map user input to state
+
+**Execution Flow (lines 693-716):**
+
+1. **Resolve prompt** (line 695):
+   ```typescript
+   const resolvedPrompt = typeof prompt === "function" ? prompt(ctx.state) : prompt;
+   ```
+
+2. **Auto-approve path** (lines 697-701):
+   - If `autoApprove` is true, applies `inputMapper` with empty string
+   - Returns state update without signal
+
+3. **Emit signal** (lines 704-715):
+   ```typescript
+   return {
+     signals: [
+       {
+         type: "human_input_required",
+         message: resolvedPrompt,
+         data: {
+           nodeId: id,
+           inputMapper: inputMapper ? true : false,
+         },
+       },
+     ],
+   };
+   ```
+
+**Signal Structure:** Includes `nodeId` and `inputMapper` flag in data field.
+
+### 4.5 Ask User Node
+
+#### askUserNode() (lines 840-893)
+
+**Purpose:** Creates a node that pauses for explicit user input with structured options.
+
+**Configuration Type:** `AskUserNodeConfig<TState>` (lines 752-766)
+
+**AskUserOptions Type (lines 738-745):**
+```typescript
+export interface AskUserOptions {
+  question: string;
+  header?: string;
+  options?: AskUserOption[];
+}
+```
+
+**AskUserOption Type (lines 727-732):**
+```typescript
+export interface AskUserOption {
+  label: string;
+  description?: string;
+}
+```
+
+**State Extension (lines 772-779):**
+```typescript
+export interface AskUserWaitState {
+  __waitingForInput?: boolean;
+  __waitNodeId?: string;
+  __askUserRequestId?: string;
+}
+```
+
+**Execution Flow (lines 850-891):**
+
+1. **Resolve options** (lines 852-853):
+   ```typescript
+   const resolvedOptions: AskUserOptions =
+     typeof options === "function" ? options(ctx.state) : options;
+   ```
+
+2. **Generate request ID** (line 856):
+   ```typescript
+   const requestId = crypto.randomUUID();
+   ```
+
+3. **Build event data** (lines 859-865):
+   ```typescript
+   const eventData: AskUserQuestionEventData = {
+     requestId,
+     question: resolvedOptions.question,
+     header: resolvedOptions.header,
+     options: resolvedOptions.options,
+     nodeId: id,
+   };
+   ```
+
+4. **Emit signal via context** (lines 868-874):
+   - If `ctx.emit` exists, calls it with signal data
+
+5. **Return with state update and signal** (lines 877-890):
+   ```typescript
+   return {
+     stateUpdate: {
+       __waitingForInput: true,
+       __waitNodeId: id,
+       __askUserRequestId: requestId,
+     } as Partial<TState>,
+     signals: [{
+       type: "human_input_required",
+       message: resolvedOptions.question,
+       data: eventData,
+     }],
+   };
+   ```
+
+**Key Difference from waitNode:** Uses `crypto.randomUUID()` for request correlation and sets wait state flags.
+
+### 4.6 Parallel Node
+
+#### parallelNode() (lines 988-1027)
+
+**Purpose:** Creates a node for concurrent branch execution.
+
+**Configuration Type:** `ParallelNodeConfig<TState>` (lines 919-949)
+
+**Key Fields:**
+- `id`: Node identifier
+- `branches`: Array of node IDs to execute in parallel
+- `strategy`: `"all" | "race" | "any"` (default: `"all"`)
+- `merge`: Optional function to combine branch results
+
+**Execution Flow (lines 1002-1025):**
+
+1. **Build parallel context** (lines 1004-1008):
+   ```typescript
+   const parallelContext: ParallelExecutionContext<TState> = {
+     branches,
+     strategy,
+     merge,
+   };
+   ```
+
+2. **Store config in state** (lines 1013-1021):
+   ```typescript
+   return {
+     stateUpdate: {
+       outputs: {
+         ...ctx.state.outputs,
+         [id]: {
+           _parallel: true,
+           ...parallelContext,
+         },
+       },
+     } as Partial<TState>,
+     goto: branches,
+   };
+   ```
+
+**Note:** Actual parallel execution handled by graph execution engine. Node marks parallel point and returns all branch IDs via `goto`.
+
+### 4.7 Subgraph Node
+
+#### subgraphNode() (lines 1166-1223)
+
+**Purpose:** Creates a node that executes a nested graph.
+
+**Configuration Type:** `SubgraphNodeConfig<TState, TSubState>` (lines 1059-1098)
+
+**SubgraphRef Type (lines 1049-1051):**
+```typescript
+export type SubgraphRef<TSubState extends BaseState = BaseState> =
+  | CompiledSubgraph<TSubState>
+  | string;
+```
+
+**Key Fields:**
+- `id`: Node identifier
+- `subgraph`: Compiled graph instance or workflow name string
+- `inputMapper`: Map parent state to subgraph initial state
+- `outputMapper`: Map subgraph final state to parent state update
+
+**Execution Flow (lines 1177-1221):**
+
+1. **Resolve subgraph** (lines 1179-1200):
+
+   **If string** (lines 1181-1196):
+   ```typescript
+   const resolver = globalWorkflowResolver;
+   if (!resolver) {
+     throw new Error("No workflow resolver set. Call setWorkflowResolver().");
+   }
+   const resolved = resolver(subgraph);
+   if (!resolved) {
+     throw new Error(`Workflow not found: ${subgraph}`);
+   }
+   resolvedSubgraph = resolved as unknown as CompiledSubgraph<TSubState>;
+   ```
+
+   **If object** (lines 1197-1200):
+   ```typescript
+   resolvedSubgraph = subgraph;
+   ```
+
+2. **Map input state** (lines 1203-1205):
+   ```typescript
+   const subState = inputMapper
+     ? inputMapper(ctx.state)
+     : (ctx.state as unknown as TSubState);
+   ```
+
+3. **Execute subgraph** (line 1208):
+   ```typescript
+   const finalSubState = await resolvedSubgraph.execute(subState);
+   ```
+
+4. **Map output state** (lines 1211-1218):
+   - If `outputMapper` provided, uses it (lines 1211-1212)
+   - Otherwise stores subgraph final state in `outputs[id]` (lines 1213-1218)
+
+5. **Return result** (line 1220)
+
+**Workflow Resolver:** Global variable at line 1110, set via `setWorkflowResolver()` at line 1118.
+
+### 4.8 Clear Context Node
+
+#### clearContextNode() (lines 494-524)
+
+**Purpose:** Creates a node that clears context window by emitting summarization signal.
+
+**Configuration Type:** `ClearContextNodeConfig<TState>` (lines 448-463)
+
+**Key Fields:**
+- `id`: Node identifier
+- `name`: Optional display name
+- `description`: Optional description
+- `message`: Optional message (static or function)
+
+**Execution Flow (lines 504-522):**
+
+1. **Resolve message** (line 505):
+   ```typescript
+   const resolvedMessage = typeof message === "function" ? message(ctx.state) : message;
+   ```
+
+2. **Emit signal** (lines 508-521):
+   ```typescript
+   return {
+     signals: [
+       {
+         type: "context_window_warning",
+         message: resolvedMessage ?? "Clearing context window",
+         data: {
+           usage: 100, // Force summarization
+           threshold: ctx.contextWindowThreshold ?? BUFFER_EXHAUSTION_THRESHOLD * 100,
+           nodeId: id,
+           action: "summarize",
+         },
+       },
+     ],
+   };
+   ```
+
+**Force Mechanism:** Sets `usage: 100` to force summarization regardless of actual usage (line 515).
+
+### 4.9 Context Monitor Node
+
+#### contextMonitorNode() (lines 1374-1512)
+
+**Purpose:** Creates a node that checks and manages context window usage.
+
+**Configuration Type:** `ContextMonitorNodeConfig<TState>` (lines 1248-1300)
+
+**Key Fields:**
+- `id`: Node identifier
+- `agentType`: `"opencode" | "claude" | "copilot"`
+- `threshold`: Percentage threshold (default: 45)
+- `action`: `"summarize" | "recreate" | "warn" | "none"`
+- `getSession`: Function to retrieve session from state
+- `getContextUsage`: Function to get current usage
+- `onCompaction`: Callback when compaction performed
+
+**Execution Flow (lines 1394-1509):**
+
+1. **Get context usage** (lines 1396-1415):
+
+   **Priority order:**
+   - If `customGetContextUsage` provided, uses it (lines 1398-1399)
+   - Else if `getSession` provided, calls `session.getContextUsage()` (lines 1400-1404)
+   - Else uses `ctx.contextWindowUsage` if available (lines 1406-1414)
+
+2. **Build state update** (lines 1418-1420):
+   ```typescript
+   const stateUpdate: Partial<TState> = {
+     contextWindowUsage: usage ? toContextWindowUsage(usage) : null,
+   } as Partial<TState>;
+   ```
+
+3. **Check threshold** (lines 1423-1426):
+   - If under threshold, returns state update without action
+   - Uses `isContextThresholdExceeded()` helper at line 1343
+
+4. **Handle threshold exceeded** (lines 1429-1504):
+
+   **Action: "summarize"** (lines 1432-1468):
+   - Gets session via `getSession()` (line 1434)
+   - Calls `session.summarize()` (line 1437)
+   - Invokes `onCompaction()` callback (line 1438)
+   - Updates usage after summarization (lines 1441-1442)
+   - On error, emits warning signal (lines 1443-1455)
+   - If no session, emits warning (lines 1457-1467)
+
+   **Action: "recreate"** (lines 1471-1484):
+   - Invokes `onCompaction()` callback (line 1473)
+   - Emits signal with `shouldRecreateSession: true` (lines 1474-1483)
+
+   **Action: "warn"** (lines 1487-1498):
+   - Emits warning signal only (lines 1489-1497)
+
+   **Action: "none"** (lines 1501-1503):
+   - No action taken
+
+5. **Return result** (lines 1506-1509):
+   ```typescript
+   return {
+     stateUpdate,
+     signals: signals.length > 0 ? signals : undefined,
+   };
+   ```
+
+**Default Action:** Line 1308 maps agent type to default action:
+- `opencode` → `"summarize"`
+- `claude` → `"recreate"`
+- `copilot` → `"warn"`
+
+### 4.10 Custom Tool Node
+
+#### customToolNode() (lines 1600-1674)
+
+**Purpose:** Creates a node that resolves and executes a tool from the ToolRegistry.
+
+**Configuration Type:** `CustomToolNodeConfig<TState, TArgs, TResult>` (lines 1572-1585)
+
+**Key Fields:**
+- `id`: Node identifier
+- `toolName`: Tool name in registry
+- `name`, `description`: Display fields
+- `inputSchema`: Zod schema for input validation
+- `args`: Static args or function to build from state
+- `outputMapper`: Function to map result to state
+- `timeout`: Execution timeout
+- `retry`: Retry configuration
+
+**Execution Flow (lines 1611-1672):**
+
+1. **Get tool from registry** (lines 1612-1619):
+   ```typescript
+   const registry = getToolRegistry();
+   const entry = registry.get(config.toolName);
+   if (!entry) {
+     throw new Error(
+       `Custom tool "${config.toolName}" not found in registry. ` +
+       `Available tools: ${registry.getAll().map(t => t.name).join(", ")}`
+     );
+   }
+   ```
+
+2. **Resolve arguments** (lines 1621-1623):
+   ```typescript
+   const rawArgs = typeof config.args === "function"
+     ? config.args(ctx.state)
+     : config.args ?? {};
+   ```
+
+3. **Validate with Zod** (lines 1626-1639):
+   - If `inputSchema` provided, validates `rawArgs` (line 1628)
+   - On validation failure, throws `SchemaValidationError` (lines 1630-1635)
+   - On success, uses parsed data (line 1636)
+
+4. **Build tool context** (lines 1641-1652):
+   ```typescript
+   const toolContext: WorkflowToolContext = {
+     sessionID: ctx.state.executionId,
+     messageID: crypto.randomUUID(),
+     agent: "workflow",
+     directory: process.cwd(),
+     abort: config.timeout
+       ? AbortSignal.timeout(config.timeout)
+       : new AbortController().signal,
+     workflowState: Object.freeze({ ...ctx.state }),
+     nodeId: config.id,
+     executionId: ctx.state.executionId,
+   };
+   ```
+
+5. **Execute tool** (line 1655):
+   ```typescript
+   const result = await entry.definition.handler(args, toolContext) as TResult;
+   ```
+
+6. **Map output** (lines 1657-1659):
+   - If `outputMapper` provided, uses it
+   - Otherwise stores result in `outputs[config.id]`
+
+7. **Error handling** (lines 1662-1671):
+   - Re-throws `SchemaValidationError` as-is (lines 1663-1665)
+   - Wraps other errors in `NodeExecutionError` (lines 1666-1670)
+
+**Schema Validation Error:** Triggers ancestor agent retry mechanism (line 1630).
+
+**Tool Registry:** Accessed via `getToolRegistry()` from `src/sdk/tools/registry.ts`.
+
+### 4.11 Subagent Node
+
+#### subagentNode() (lines 1710-1767)
+
+**Purpose:** Creates a node that spawns a single sub-agent within graph execution.
+
+**Configuration Type:** `SubagentNodeConfig<TState>` (lines 1684-1698)
+
+**Key Fields:**
+- `id`: Node identifier
+- `agentName`: Agent name resolved from SubagentTypeRegistry
+- `task`: Task string or function to build from state
+- `systemPrompt`: Optional system prompt override
+- `model`: Optional model override
+- `tools`: Optional tools array
+- `outputMapper`: Function to map result to state
+- `retry`: Retry configuration
+
+**Execution Flow (lines 1719-1765):**
+
+1. **Get subagent bridge** (lines 1720-1726):
+   ```typescript
+   const bridge = getSubagentBridge();
+   if (!bridge) {
+     throw new Error(
+       "SubagentGraphBridge not initialized. " +
+       "Ensure setSubagentBridge() is called before graph execution."
+     );
+   }
+   ```
+
+2. **Get agent from registry** (lines 1728-1735):
+   ```typescript
+   const registry = getSubagentRegistry();
+   const entry = registry.get(config.agentName);
+   if (!entry) {
+     throw new Error(
+       `Sub-agent "${config.agentName}" not found in registry. ` +
+       `Available agents: ${registry.getAll().map(a => a.name).join(", ")}`
+     );
+   }
+   ```
+
+3. **Resolve task and system prompt** (lines 1737-1743):
+   ```typescript
+   const task = typeof config.task === "function"
+     ? config.task(ctx.state)
+     : config.task;
+   const systemPrompt = typeof config.systemPrompt === "function"
+     ? config.systemPrompt(ctx.state)
+     : config.systemPrompt;
+   ```
+
+4. **Spawn subagent** (lines 1745-1752):
+   ```typescript
+   const result = await bridge.spawn({
+     agentId: `${config.id}-${ctx.state.executionId}`,
+     agentName: config.agentName,
+     task,
+     systemPrompt,
+     model: config.model ?? ctx.model,
+     tools: config.tools,
+   });
+   ```
+
+5. **Check result** (lines 1754-1758):
+   ```typescript
+   if (!result.success) {
+     throw new Error(
+       `Sub-agent "${config.agentName}" failed: ${result.error ?? "Unknown error"}`
+     );
+   }
+   ```
+
+6. **Map output** (lines 1760-1762):
+   - If `outputMapper` provided, uses it
+   - Otherwise stores `result.output` in `outputs[config.id]`
+
+7. **Return result** (line 1764)
+
+**Bridge:** Global variable accessed via `getSubagentBridge()` from `subagent-bridge.ts`.
+
+**Registry:** Global variable accessed via `getSubagentRegistry()` from `subagent-registry.ts`.
+
+### 4.12 Parallel Subagent Node
+
+#### parallelSubagentNode() (lines 1802-1838)
+
+**Purpose:** Creates a node that spawns multiple sub-agents concurrently.
+
+**Configuration Type:** `ParallelSubagentNodeConfig<TState>` (lines 1776-1789)
+
+**Key Fields:**
+- `id`: Node identifier
+- `agents`: Array of agent configs with `agentName`, `task`, `systemPrompt`, `model`, `tools`
+- `merge`: Function to aggregate results into state update
+- `retry`: Retry configuration
+
+**Execution Flow (lines 1811-1836):**
+
+1. **Get subagent bridge** (lines 1812-1815):
+   ```typescript
+   const bridge = getSubagentBridge();
+   if (!bridge) {
+     throw new Error("SubagentGraphBridge not initialized.");
+   }
+   ```
+
+2. **Build spawn options** (lines 1817-1824):
+   ```typescript
+   const spawnOptions: SubagentSpawnOptions[] = config.agents.map((agent, i) => ({
+     agentId: `${config.id}-${i}-${ctx.state.executionId}`,
+     agentName: agent.agentName,
+     task: typeof agent.task === "function" ? agent.task(ctx.state) : agent.task,
+     systemPrompt: agent.systemPrompt,
+     model: agent.model ?? ctx.model,
+     tools: agent.tools,
+   }));
+   ```
+
+3. **Spawn in parallel** (line 1826):
+   ```typescript
+   const results = await bridge.spawnParallel(spawnOptions);
+   ```
+
+4. **Build result map** (lines 1828-1832):
+   ```typescript
+   const resultMap = new Map<string, SubagentResult>();
+   results.forEach((result, i) => {
+     const key = `${config.agents[i]!.agentName}-${i}`;
+     resultMap.set(key, result);
+   });
+   ```
+
+5. **Merge results** (line 1834):
+   ```typescript
+   const stateUpdate = config.merge(resultMap, ctx.state);
+   ```
+
+6. **Return result** (line 1835)
+
+**Parallel Execution:** Uses `bridge.spawnParallel()` which internally uses `Promise.allSettled()`.
+
+**Result Persistence:** Individual results persisted to workflow session directory by bridge.
+
+---
+
+## 5. Error Handling (errors.ts)
+
+### Overview
+
+The `errors.ts` file at `src/graph/errors.ts` (58 lines) defines custom error classes for graph node execution failures. Both error types trigger the ancestor agent retry mechanism.
+
+### 5.1 SchemaValidationError
+
+#### Class Definition (lines 16-24)
+
+```typescript
+export class SchemaValidationError extends Error {
+  constructor(
+    message: string,
+    public readonly zodError: ZodError,
+  ) {
+    super(message);
+    this.name = "SchemaValidationError";
+  }
+}
+```
+
+**Purpose:** Thrown when a node's input fails Zod schema validation.
+
+**Fields:**
+- `message`: Human-readable error description
+- `zodError`: The underlying Zod validation error
+
+**Trigger:** Input contract violation—arguments don't match expected Zod schema.
+
+**Behavior:** Triggers ancestor agent retry so LLM can regenerate conforming output.
+
+**Usage:** Thrown by `customToolNode()` at `nodes.ts:1630` when `inputSchema.safeParse()` fails.
+
+### 5.2 NodeExecutionError
+
+#### Class Definition (lines 30-39)
+
+```typescript
+export class NodeExecutionError extends Error {
+  constructor(
+    message: string,
+    public readonly nodeId: string,
+    public override readonly cause?: Error,
+  ) {
+    super(message);
+    this.name = "NodeExecutionError";
+  }
+}
+```
+
+**Purpose:** Wraps runtime failures from tool handlers and sub-agent execution.
+
+**Fields:**
+- `message`: Human-readable error description
+- `nodeId`: ID of the node that failed
+- `cause`: The underlying error (optional)
+
+**Trigger:** Runtime failures during node execution.
+
+**Behavior:** Triggers ancestor agent retry with structured error context.
+
+**Usage:** Thrown by `customToolNode()` at `nodes.ts:1666` when tool handler fails.
+
+### 5.3 ErrorFeedback
+
+#### Interface Definition (lines 44-57)
+
+```typescript
+export interface ErrorFeedback {
+  failedNodeId: string;
+  errorMessage: string;
+  errorType: string;
+  attempt: number;
+  maxAttempts: number;
+  previousOutput?: unknown;
+}
+```
+
+**Purpose:** Error feedback injected into ancestor agent context on downstream failure.
+
+**Fields:**
+- `failedNodeId`: The node that failed
+- `errorMessage`: The error message from the failed node
+- `errorType`: The error type (e.g., "SchemaValidationError")
+- `attempt`: Current retry attempt (1-indexed)
+- `maxAttempts`: Maximum attempts before workflow failure
+- `previousOutput`: The output that led to failure (if available)
+
+**Usage:** Structured feedback for agent to learn from failures and adjust output.
+
+---
+
+## 6. Data Flow Summary
+
+### 6.1 Graph Construction Flow
+
+1. **Initialization:**
+   - User calls `graph<TState>()` factory → creates `GraphBuilder` instance
+   - Builder initializes empty `nodes` map, `edges` array, and state tracking
+
+2. **Node Addition:**
+   - `start(node)` → Sets `startNodeId`, adds node to `nodes` map
+   - `then(node)` → Adds node, creates edge from current node, updates `currentNodeId`
+   - Each node addition increments `nodeCounter` for unique IDs
+
+3. **Control Flow:**
+   - `if(condition)` → Creates decision node, pushes to `conditionalStack`
+   - `else()` → Records if-branch end, sets `inElseBranch = true`
+   - `endif()` → Creates merge node, connects conditional edges, pops stack
+   - `loop(bodyNodes, config)` → Creates loop start/check nodes, chains body nodes, adds conditional back-edge
+
+4. **Compilation:**
+   - `compile(config)` → Validates graph, finds end nodes, returns `CompiledGraph`
+   - Compiled graph contains cloned `nodes` map, `edges` array, and merged `config`
+
+### 6.2 Execution Flow
+
+1. **Initialization:**
+   - `executor.stream(options)` → Generates execution ID, initializes state
+   - If resuming, loads snapshot; otherwise calls `initializeExecutionState()`
+   - Initializes node queue with `graph.startNode`
+
+2. **Main Loop:**
+   - While `nodeQueue.length > 0 && stepCount < maxSteps`:
+     - Shift next node from queue
+     - Check loop detection via `executionVisited` set
+     - Execute node via `executeWithRetry()`
+     - Merge state update via `mergeState()`
+     - Handle signals (human_input_required, checkpoint)
+     - Get next nodes via `getNextNodes()`
+     - Push next nodes to queue
+     - Yield `StepResult` to consumer
+
+3. **Node Execution:**
+   - `executeWithRetry()` → Retry loop with exponential backoff
+   - Resolves model via `resolveModel()` hierarchy
+   - Builds `ExecutionContext` with state, config, errors, model
+   - Calls `node.execute(context)` to get `NodeResult`
+   - On error, checks `retryOn` predicate and retries up to `maxAttempts`
+
+4. **Edge Evaluation:**
+   - `getNextNodes()` → Filters outgoing edges from current node
+   - Evaluates edge conditions with current state
+   - Returns deduplicated array of target node IDs
+   - If node result has `goto`, uses that instead
+
+5. **Completion:**
+   - When `isEndNode && nodeQueue.length === 0`, yields `completed` status
+   - Tracks telemetry completion before yield
+   - Returns from generator
+
+### 6.3 State Management Flow
+
+1. **State Initialization:**
+   - `initializeExecutionState()` → Creates base state with `executionId`, `lastUpdated`, `outputs`
+   - Merges with optional `initialState` parameter
+   - Returns fully typed `TState` extending `BaseState`
+
+2. **State Updates:**
+   - Node returns `NodeResult` with optional `stateUpdate`
+   - `mergeState()` → Immutably merges update into current state
+   - Handles `outputs` specially—merges rather than replaces
+   - Always updates `lastUpdated` to current timestamp
+
+3. **State Propagation:**
+   - Updated state passed to next node via `ExecutionContext`
+   - Previous node outputs accessible via `ctx.getNodeOutput(nodeId)` or `ctx.state.outputs[nodeId]`
+   - Entire state history preserved in `outputs` map
+
+### 6.4 Signal Flow
+
+1. **Signal Emission:**
+   - Nodes return `signals` array in `NodeResult`
+   - Executor collects signals during execution (line 404)
+
+2. **Signal Types:**
+   - `human_input_required` → Pauses execution, yields `paused` status (lines 408-419)
+   - `checkpoint` → Saves state via checkpointer (lines 422-430)
+   - `context_window_warning` → Logs warning, optionally compacts context
+   - `debug_report_generated` → Indicates debug report created
+
+3. **Signal Handling:**
+   - Executor checks signals after each node execution
+   - Human input signals cause immediate pause and return
+   - Checkpoint signals trigger `saveCheckpoint()` call
+   - Context window warnings logged but don't affect execution flow
+
+### 6.5 Error and Retry Flow
+
+1. **Node Execution Error:**
+   - Node throws error during `execute()`
+   - `executeWithRetry()` catches and stores in `lastError`
+
+2. **Retry Decision:**
+   - Checks `retryConfig.retryOn(error)` predicate if defined
+   - If predicate returns false, throws immediately
+   - Otherwise attempts retry up to `maxAttempts`
+
+3. **Exponential Backoff:**
+   - Calculates delay: `backoffMs × (backoffMultiplier ^ (attempt - 1))`
+   - Sleeps for calculated delay via `sleep()`
+   - Increments attempt counter and retries
+
+4. **Retry Exhaustion:**
+   - After max attempts, throws final error
+   - Error caught by executor, pushed to `errors` array
+   - Yields `failed` status with error, stops execution
+
+5. **Schema Validation:**
+   - `customToolNode()` validates input with Zod schema
+   - On failure, throws `SchemaValidationError` with Zod details
+   - Error propagates to ancestor agent for retry with feedback
+
+### 6.6 Checkpointing Flow
+
+1. **Auto-Checkpoint:**
+   - If `config.autoCheckpoint` enabled (default: true)
+   - After each node execution, calls `saveCheckpoint()`
+   - Label format: `"step_${stepCount}"`
+
+2. **Manual Checkpoint:**
+   - Node emits `checkpoint` signal
+   - Executor detects signal and calls `saveCheckpoint()`
+   - Label from signal data or generated
+
+3. **Checkpoint Save:**
+   - Calls `checkpointer.save(executionId, state, label)`
+   - On success, emits `checkpoint_saved` progress event
+   - On error, logs but doesn't fail execution
+
+4. **Checkpoint Resume:**
+   - Pass `resumeFrom` snapshot to `stream()` options
+   - Executor restores state, visitedNodes, errors, signals
+   - Resumes from `snapshot.currentNodeId` if present
+
+### 6.7 Model Resolution Flow
+
+1. **Resolution Hierarchy:**
+   - Check `node.model` (if not "inherit")
+   - Check `parentContext.model` (inherited from parent)
+   - Check `config.defaultModel` (if not "inherit")
+   - Return `undefined` (let SDK use default)
+
+2. **Context Propagation:**
+   - Resolved model stored in `ExecutionContext.model`
+   - Passed to node execution functions
+   - Agent nodes use `ctx.model` for session config (line 205)
+   - Subagent nodes pass `ctx.model` to bridge (line 1750)
+
+3. **Model Override:**
+   - Nodes can specify `model` in definition
+   - Overrides parent and default models (unless "inherit")
+   - Allows per-node model specification for heterogeneous workflows
+
+---
+
+## Appendix: Key File Locations
+
+- **GraphBuilder:** `src/graph/builder.ts` (780 lines)
+- **GraphExecutor:** `src/graph/compiled.ts` (758 lines)
+- **Type Definitions:** `src/graph/types.ts` (678 lines)
+- **Node Factories:** `src/graph/nodes.ts` (1838 lines)
+- **Error Classes:** `src/graph/errors.ts` (58 lines)
+- **Checkpointers:** `src/graph/checkpointer.ts` (implementation details)
+- **Main Export:** `src/graph/index.ts` (re-exports all public APIs)
+
+---
+
+**End of Technical Documentation**
diff --git a/research/docs/2026-02-25-graph-execution-engine.md b/research/docs/2026-02-25-graph-execution-engine.md
new file mode 100644
index 0000000000..08d9509db2
--- /dev/null
+++ b/research/docs/2026-02-25-graph-execution-engine.md
@@ -0,0 +1,789 @@
+# Graph Execution Engine -- Technical Documentation
+
+**Date:** 2026-02-25
+**Scope:** `src/workflows/graph/` module -- builder, compiled execution, node factories, and core types.
+
+---
+
+## 1. Graph Builder (`src/workflows/graph/builder.ts`)
+
+### Overview
+
+The `GraphBuilder` class (line 229) provides a fluent API for constructing directed acyclic (or cyclic, via loops) workflow graphs. It accumulates nodes and edges in internal collections and produces a `CompiledGraph` object via `.compile()`. A convenience factory function `graph<TState>()` (line 971) instantiates the builder.
+
+### Internal State
+
+| Field | Type | Line | Purpose |
+|---|---|---|---|
+| `nodes` | `Map<NodeId, NodeDefinition<TState>>` | 231 | All registered node definitions |
+| `edges` | `Edge<TState>[]` | 234 | All directed edges |
+| `startNodeId` | `NodeId \| null` | 237 | The entry-point node |
+| `endNodeIds` | `Set<NodeId>` | 240 | Explicitly marked terminal nodes |
+| `currentNodeId` | `NodeId \| null` | 243 | Tracks the "cursor" for chaining |
+| `conditionalStack` | `ConditionalBranch<TState>[]` | 246 | Stack for nested if/else tracking |
+| `nodeCounter` | `number` | 249 | Auto-incrementing ID generator |
+| `errorHandlerId` | `NodeId \| null` | 252 | Global error handler node |
+
+### Private Helper Methods
+
+- **`generateNodeId(prefix)`** (line 257): Returns `"${prefix}_${++nodeCounter}"`.
+- **`addNode(node)`** (line 264): Inserts a `NodeDefinition` into `this.nodes`. Throws if the ID already exists.
+- **`addEdge(from, to, condition?, label?)`** (line 274): Pushes an `Edge` object onto `this.edges`.
+- **`createNode(id, type, execute, options?)`** (line 286): Assembles a `NodeDefinition` from parameters by spreading `options` onto `{id, type, execute}`.
+
+### Fluent API Methods
+
+#### `.start(node)` (line 318)
+
+Sets the starting node of the workflow. Throws if a start node is already set. Records `node.id` as both `startNodeId` and `currentNodeId`.
+
+**Signature:** `start(node: NodeDefinition<TState>): this`
+
+#### `.then(node)` (line 338)
+
+Adds a node and connects it from the current node via an unconditional edge. If no start node exists, delegates to `.start()`. When inside a conditional branch and `currentNodeId` is `null`, the node is registered as the branch start (`ifBranchStart` or `elseBranchStart`) without creating an edge from the decision node; the conditional edges are deferred to `.endif()`. Otherwise, creates a standard edge from `currentNodeId` to `node.id`.
+
+**Signature:** `then(node: NodeDefinition<TState>): this`
+
+#### `.if(condition)` -- function-based overload (line 374)
+
+Begins a conditional branch. Creates a synthetic decision node (type `"decision"`, ID prefix `"decision"`) that returns `{}` from its execute function. Edges from the decision node to the branch starts are deferred until `.endif()`. Pushes a `ConditionalBranch` record onto `conditionalStack` and sets `currentNodeId` to `null` so the next `.then()` call records the branch start.
+
+**Signature:** `if(condition: EdgeCondition<TState>): this`
+
+#### `.if(config)` -- config-based overload (line 382)
+
+Accepts an `IfConfig<TState>` object (line 167) containing `condition`, `then` (node array), optional `else_if` array, and optional `else` node array. Internally calls the function-based `.if()`, then iterates through `.then(node)` for each branch node, `.else()`, and nested `.if()` calls for `else_if` chains. Each `else_if` entry creates a pass-through decision node (line 451-452), a nested `.if()`, and a corresponding `.endif()`. The main conditional is closed last at line 493.
+
+**Signature:** `if(config: IfConfig<TState>): this`
+
+#### `.else()` (line 503)
+
+Transitions to the else branch. Records the current `currentNodeId` as `ifBranchEnd`, sets `inElseBranch = true`, and resets `currentNodeId` to `null`. Throws if already in an else branch or if no preceding `.if()`.
+
+**Signature:** `else(): this`
+
+#### `.endif()` (line 529)
+
+Closes a conditional block. Pops the top `ConditionalBranch` from the stack. Creates a merge node (type `"decision"`, ID prefix `"merge"`, line 544-545). Wires:
+- Decision node -> if-branch start (with the original condition, label `"if-true"`)
+- Decision node -> else-branch start (with negated condition, label `"if-false"`) -- or directly to merge node if no else branch
+- If-branch end -> merge node
+- Else-branch end -> merge node (if exists)
+
+Sets `currentNodeId` to the merge node.
+
+**Signature:** `endif(): this`
+
+#### `.parallel(config)` (line 590)
+
+Creates a parallel node (type `"parallel"`, ID prefix `"parallel"`). The node's execute function stores branch metadata in `outputs[parallelNodeId]`. Adds edges from the parallel node to each branch ID specified in `config.branches`.
+
+**Signature:** `parallel(config: ParallelConfig<TState>): this`
+
+The `ParallelConfig` (line 68) contains:
+- `branches: NodeId[]` -- branch node IDs
+- `strategy?: MergeStrategy` -- `"all"` | `"race"` | `"any"` (default `"all"`)
+- `merge?: (results, state) => Partial<TState>` -- optional result combiner
+
+#### `.loop(bodyNodes, config)` (line 647)
+
+Creates a loop structure with these components:
+1. **Loop start node** (ID prefix `"loop_start"`, type `"decision"`) -- initializes an iteration counter in `outputs[loopStartId + "_iteration"]`
+2. **Body nodes** -- the user-supplied node(s), chained sequentially
+3. **Loop check node** (ID prefix `"loop_check"`, type `"decision"`) -- increments the iteration counter
+
+Edge structure:
+- `currentNodeId` -> loop start
+- Loop start -> first body node
+- Body nodes chained: `node[i]` -> `node[i+1]`
+- Last body node -> loop check
+- Loop check -> first body node (conditional: `!config.until(state) && iteration < maxIterations`, label `"loop-continue"`)
+
+The exit from the loop happens implicitly: the next `.then()` or `.end()` call connects from the loop check node. `maxIterations` defaults to 100 (line 660).
+
+**Signature:** `loop(bodyNodes: NodeDefinition<TState> | NodeDefinition<TState>[], config: LoopConfig<TState>): this`
+
+The `LoopConfig` (line 40) contains:
+- `until: EdgeCondition<TState>` -- exit condition (exits when true)
+- `maxIterations?: number` -- safety limit (default 100)
+
+#### `.wait(promptOrNode)` (line 745)
+
+Creates a wait node (type `"wait"`) for human-in-the-loop. If given a string, generates a node that emits a `human_input_required` signal. If given a `NodeDefinition`, uses it directly. Delegates to `.then()`.
+
+**Signature:** `wait(promptOrNode: string | NodeDefinition<TState>): this`
+
+#### `.subagent(config)` (line 786)
+
+Converts a `SubAgentConfig<TState>` (line 100) to a `SubagentNodeConfig` by mapping `config.agent` to `agentName`, then calls the `subagentNode()` factory. The resulting node is added via `.then()`.
+
+**Signature:** `subagent(config: SubAgentConfig<TState>): this`
+
+`SubAgentConfig` fields: `id`, `agent` (mapped to `agentName`), `task` (string or state function), `systemPrompt?`, `model?`, `tools?`, `outputMapper?`, `retry?`, `name?`, `description?`.
+
+#### `.tool(config)` (line 829)
+
+Converts a `ToolBuilderConfig<TState, TArgs, TResult>` (line 135) to a `ToolNodeConfig` (setting `toolName` to `config.toolName ?? config.id`), then calls the `toolNode()` factory. The resulting node is added via `.then()`.
+
+**Signature:** `tool<TArgs, TResult>(config: ToolBuilderConfig<TState, TArgs, TResult>): this`
+
+`ToolBuilderConfig` fields: `id`, `toolName?`, `execute?`, `args?`, `outputMapper?`, `timeout?`, `retry?`, `name?`, `description?`.
+
+#### `.catch(handler)` (line 859)
+
+Registers a global error handler node. Adds the node to the graph and records its ID as `errorHandlerId`. The handler is stored in `config.metadata.errorHandlerId` during compilation (line 908).
+
+**Signature:** `catch(handler: NodeDefinition<TState>): this`
+
+#### `.end()` (line 871)
+
+Marks `currentNodeId` as a terminal node by adding it to `endNodeIds`.
+
+**Signature:** `end(): this`
+
+#### `.compile(config?)` (line 885)
+
+Produces a `CompiledGraph<TState>` from the accumulated state. Steps:
+1. Throws if `startNodeId` is null (line 886-888)
+2. If `endNodeIds` is empty, auto-discovers terminal nodes by finding nodes with no outgoing edges (lines 891-898)
+3. If `errorHandlerId` is set, stores it in `config.metadata.errorHandlerId` (lines 901-911)
+4. Returns `{ nodes: Map(copy), edges: [...copy], startNode, endNodes: Set(copy), config }` (lines 913-919)
+
+**Signature:** `compile(config: GraphConfig<TState> = {}): CompiledGraph<TState>`
+
+### Query Methods
+
+- **`getNode(nodeId)`** (line 928): Looks up a node by ID from the internal map.
+- **`getEdgesFrom(nodeId)`** (line 938): Filters edges where `e.from === nodeId`.
+- **`getEdgesTo(nodeId)`** (line 948): Filters edges where `e.to === nodeId`.
+
+### Standalone Helper Functions
+
+- **`graph<TState>()`** (line 971): Factory that returns `new GraphBuilder<TState>()`.
+- **`createNode(id, type, execute, options?)`** (line 988): Standalone version of the private `createNode` method.
+- **`createDecisionNode(id, routes, fallback)`** (line 1018): Creates a decision node that iterates through routes and returns `{ goto: route.target }` for the first matching condition, or `{ goto: fallback }`.
+- **`createWaitNode(id, prompt)`** (line 1044): Creates a wait node that emits `human_input_required` signal.
+
+---
+
+## 2. Compiled Graph Execution (`src/workflows/graph/compiled.ts`)
+
+### Overview
+
+The `GraphExecutor` class (line 253) takes a `CompiledGraph<TState>` and provides two execution modes: `execute()` for batch completion and `stream()` for step-by-step async iteration. Top-level convenience functions `executeGraph()` (line 871) and `streamGraph()` (line 888) wrap the class.
+
+### Key Types
+
+#### `ExecutionOptions<TState>` (line 50)
+
+| Field | Type | Purpose |
+|---|---|---|
+| `initialState?` | `Partial<TState>` | Override default state initialization |
+| `executionId?` | `string` | Custom execution ID (auto-generated if absent) |
+| `resumeFrom?` | `ExecutionSnapshot<TState>` | Snapshot to resume from |
+| `abortSignal?` | `AbortSignal` | Cancellation signal |
+| `maxSteps?` | `number` | Safety limit on node executions |
+| `workflowName?` | `string` | Telemetry label |
+| `telemetry?` | `WorkflowTelemetryConfig` | Telemetry configuration |
+
+#### `StepResult<TState>` (line 78)
+
+Yielded after each node execution. Contains `nodeId`, current `state`, the `result` (NodeResult), `status` (ExecutionStatus), optional `error`, `executionTime`, `retryCount`, `modelUsed`, and `emittedEvents`.
+
+#### `ExecutionResult<TState>` (line 121)
+
+Final result of `execute()`. Contains `state`, `status`, and `snapshot`.
+
+### `GraphExecutor<TState>` Class
+
+#### Constructor (line 258)
+
+Takes a `CompiledGraph<TState>`. Merges `DEFAULT_GRAPH_CONFIG` with `graph.config` to form `this.config`. Initializes a `StateValidator` from the graph config via `StateValidator.fromGraphConfig()` (line 265).
+
+#### `execute(options)` (line 274)
+
+Iterates over `this.stream(options)`, collecting each `StepResult`. Breaks on terminal statuses: `"completed"`, `"failed"`, `"cancelled"`, `"paused"`. Returns an `ExecutionResult` containing the final state, status, and a snapshot created by `createSnapshot()` (line 818).
+
+#### `stream(options)` (line 309)
+
+Overloaded:
+- Without `modes`: yields `StepResult<TState>` directly from `streamSteps()`.
+- With `modes` (via `RoutedExecutionOptions`): wraps `streamSteps()` through `routeStream()` from `stream.ts`, yielding `StreamEvent<TState>`.
+
+The `hasRoutedModes()` function (line 142) distinguishes the overloads by checking for the `modes` property.
+
+#### `streamSteps(options)` -- Core Execution Loop (line 322)
+
+This is the main execution engine. It operates as a queue-based traversal:
+
+1. **Initialization** (lines 325-362):
+   - Generates or uses provided `executionId`
+   - Sets `maxSteps` (default 1000)
+   - Initializes telemetry tracker if configured
+   - If `resumeFrom` snapshot exists: restores `state`, `visitedNodes`, `errors`, `signals`, and `nodeQueue` from the snapshot
+   - Otherwise: calls `initializeExecutionState()` with `executionId` and optional `initialState`, starts `nodeQueue` with `[this.graph.startNode]`
+
+2. **Main Loop** (lines 367-547): `while (nodeQueue.length > 0 && stepCount < maxSteps)`
+
+   a. **Abort Check** (lines 369-381): If `abortSignal` is aborted, yields a `"cancelled"` status step and returns.
+
+   b. **Node Lookup** (lines 383-394): Shifts the next node ID from the queue. If the node is not found in the graph, records an `ExecutionError` and continues.
+
+   c. **Loop Detection** (lines 397-402): Creates a visit key `"${currentNodeId}:${stepCount}"`. If this exact key was already visited and the node is not a loop node (checked via `isLoopNode()` at line 176, which tests for `"loop_start"` or `"loop_check"` in the node ID), the node is skipped.
+
+   d. **Node Execution** (lines 410-447): Calls `executeWithRetry(node, state, errors, abortSignal)`. On success, extracts `result`. On error, pushes to `errors`, yields a `"failed"` step, tracks telemetry, and returns.
+
+   e. **State Merge** (lines 454-457): If `result.stateUpdate` exists, calls `mergeState(state, result.stateUpdate)` to produce the new state.
+
+   f. **Signal Handling** (lines 464-495):
+      - `human_input_required`: yields `"paused"` status and returns
+      - `checkpoint`: saves checkpoint if checkpointer is configured
+
+   g. **Auto-Checkpoint** (lines 498-505): If `config.autoCheckpoint` is true and a checkpointer exists, saves after each node.
+
+   h. **Progress Callback** (lines 508-515): Calls `config.onProgress()` with a `"node_completed"` event.
+
+   i. **Next Node Resolution** (lines 518-521): Calls `getNextNodes()` and pushes results onto `nodeQueue`.
+
+   j. **Termination Check** (lines 525-546): A node is considered terminal if it's in `graph.endNodes` AND `nodeQueue` is empty. Yields the step with `"completed"` or `"running"` status accordingly.
+
+3. **Max Steps Exceeded** (lines 550-568): If the loop exits due to `stepCount >= maxSteps`, yields a `"failed"` step with an error message.
+
+#### `resolveModel(node, parentContext?)` (line 578)
+
+Model resolution follows a priority chain:
+1. `node.model` if set and not `"inherit"`
+2. `parentContext.model` if available
+3. `config.defaultModel` if set and not `"inherit"`
+4. `undefined` (SDK default)
+
+#### `executeWithRetry(node, state, errors, abortSignal?, parentContext?)` (line 615)
+
+Implements retry logic with exponential backoff:
+
+1. Loops up to `retryConfig.maxAttempts` (default 3 from `DEFAULT_RETRY_CONFIG`)
+2. On each attempt:
+   - Resolves model via `resolveModel()`
+   - Builds `ExecutionContext` with `state`, `config`, `errors`, `abortSignal`, `model`, `emit` function (captures to `emittedEvents` array), and `getNodeOutput` helper
+   - Validates node input via `stateValidator.validateNodeInput()` (line 652)
+   - Calls `node.execute(context)` (line 655)
+   - On success: validates output state via `stateValidator.validateNodeOutput()` and `stateValidator.validate()` (lines 658-660)
+   - Returns `{ result, retryCount: attempt - 1, modelUsed, emittedEvents }`
+3. On error with `node.onError` handler (line 682): the handler returns an `ErrorAction`:
+   - `"skip"`: returns with optional `fallbackState`
+   - `"abort"`: rethrows the error
+   - `"goto"`: returns `{ goto: nodeId }` (target must have `isRecoveryNode: true`)
+   - `"retry"`: uses optional custom delay or falls back to exponential backoff
+4. Without `onError`: checks `retryConfig.retryOn` predicate (line 733). If it returns false, throws immediately.
+5. Backoff formula: `retryConfig.backoffMs * Math.pow(retryConfig.backoffMultiplier, attempt - 1)` (line 744)
+
+#### `getNextNodes(currentNodeId, state, result)` (line 758)
+
+Determines the next nodes to execute:
+1. If `result.goto` is set, uses that (supports single ID or array)
+2. Otherwise, filters outgoing edges from `currentNodeId` and evaluates edge conditions
+3. Edges without conditions are always followed; conditional edges are followed when `condition(state)` returns true
+4. Returns unique target node IDs
+
+#### `saveCheckpoint(checkpointer, executionId, state, label)` (line 792)
+
+Delegates to `checkpointer.save()`. Calls `onProgress` with `"checkpoint_saved"` event. Errors are caught and logged (not propagated).
+
+#### `createSnapshot(stepResult)` (line 818)
+
+Builds an `ExecutionSnapshot` from a step result with `executionId`, `state`, `status`, `currentNodeId`, and error/signal data.
+
+### State Management Functions
+
+#### `initializeExecutionState(executionId, initial?)` (line 188)
+
+Creates a fresh `BaseState` with `executionId`, `lastUpdated` (ISO timestamp), and empty `outputs`. Merges `initial` values, but preserves `executionId` and always overwrites `lastUpdated`. Outputs are shallow-merged.
+
+#### `mergeState(current, update)` (line 219)
+
+Immutably merges `update` into `current`. The `outputs` field is specially handled: if `update.outputs` is defined, it is shallow-merged with `current.outputs` rather than replacing it. `lastUpdated` is always refreshed.
+
+### Convenience Functions
+
+- **`createExecutor(graph)`** (line 857): Returns `new GraphExecutor(graph)`.
+- **`executeGraph(graph, options?)`** (line 871): Creates executor and calls `.execute()`.
+- **`streamGraph(graph, options?)`** (line 888): Overloaded -- creates executor and delegates to `.stream()`. Returns `StepResult` or `StreamEvent` depending on whether `modes` is present in options.
+
+### Stream Routing (`src/workflows/graph/stream.ts`)
+
+The `StreamRouter` class (line 56) wraps an `AsyncIterable<StepResult>` and projects each step into one or more `StreamEvent` types based on the selected modes:
+
+- `"values"`: emits `{ mode: "values", nodeId, state }`
+- `"updates"`: emits `{ mode: "updates", nodeId, update }` (only if `stateUpdate` exists)
+- `"events"`: emits one event per `emittedEvent` from the step
+- `"debug"`: emits `{ mode: "debug", nodeId, trace }` with execution time, retry count, model, and state snapshot
+
+`routeStream(source, modes)` (line 123) is the convenience wrapper.
+
+---
+
+## 3. Node Types (`src/workflows/graph/nodes.ts`)
+
+### Overview
+
+This module provides factory functions that produce `NodeDefinition<TState>` objects. Each factory accepts a config object, validates it, and returns a node with an `execute` function that operates on `ExecutionContext<TState>`.
+
+### Factory Functions
+
+#### `agentNode(config)` (line 144)
+
+**Config type:** `AgentNodeConfig<TState>` (line 62)
+
+| Field | Type | Required | Default |
+|---|---|---|---|
+| `id` | `NodeId` | Yes | -- |
+| `agentType` | `string` | Yes | -- |
+| `systemPrompt` | `string` | No | -- |
+| `tools` | `string[]` | No | -- |
+| `outputMapper` | `OutputMapper<TState>` | No | Stores messages in `outputs[id]` |
+| `sessionConfig` | `Partial<SessionConfig>` | No | -- |
+| `retry` | `RetryConfig` | No | `AGENT_NODE_RETRY_CONFIG` (3 attempts, 1s, 2x) |
+| `name` | `string` | No | `"${agentType} agent"` |
+| `description` | `string` | No | -- |
+| `buildMessage` | `(state: TState) => string` | No | Returns `""` |
+
+**Produced NodeDefinition:** type `"agent"`
+
+**Execute behavior** (lines 166-243):
+1. Resolves `CodingAgentClient` from `ctx.config.runtime.clientProvider(agentType)` -- throws if not found
+2. Builds `SessionConfig` merging `sessionConfig`, resolved model from `ctx.model`, `systemPrompt`, and `tools`
+3. Creates session via `client.createSession(fullSessionConfig)`
+4. Sends message built from `buildMessage(state)` and streams the response into an `AgentMessage[]` array
+5. Gets context usage via `session.getContextUsage()`
+6. Maps output via `outputMapper` or stores messages in `outputs[id]`
+7. If context usage exceeds `config.contextWindowThreshold`, emits `"context_window_warning"` signal
+8. Calls `session.destroy()` in `finally` block
+
+#### `toolNode(config)` (line 343)
+
+**Config type:** `ToolNodeConfig<TState, TArgs, TResult>` (line 279)
+
+| Field | Type | Required | Default |
+|---|---|---|---|
+| `id` | `NodeId` | Yes | -- |
+| `toolName` | `string` | Yes | -- |
+| `execute` | `ToolExecuteFn<TArgs, TResult>` | Yes (throws if missing, line 360) | -- |
+| `args` | `TArgs \| ((state: TState) => TArgs)` | No | -- |
+| `outputMapper` | `ToolOutputMapper<TState, TResult>` | No | Stores result in `outputs[id]` |
+| `timeout` | `number` (ms) | No | -- |
+| `retry` | `RetryConfig` | No | `DEFAULT_RETRY_CONFIG` |
+| `name` | `string` | No | `toolName` |
+| `description` | `string` | No | -- |
+
+**Produced NodeDefinition:** type `"tool"`
+
+**Execute behavior** (lines 370-410):
+1. Resolves args: if `args` is a function, calls it with `ctx.state`; otherwise uses as-is
+2. If `timeout` is set, creates an `AbortController` that aborts after the timeout
+3. Calls `execute(resolvedArgs, abortController.signal)`
+4. Maps output via `outputMapper` or stores in `outputs[id]`
+5. Clears timeout in `finally` block
+
+#### `clearContextNode(config)` (line 468)
+
+**Config type:** `ClearContextNodeConfig<TState>` (line 422)
+
+Fields: `id`, `name?`, `description?`, `message?` (string or state function).
+
+**Produced NodeDefinition:** type `"tool"`, name `"clear-context"`
+
+**Execute behavior** (lines 478-497): Emits a `"context_window_warning"` signal with `usage: 100` and `action: "summarize"` to force summarization.
+
+#### `decisionNode(config)` (line 567)
+
+**Config type:** `DecisionNodeConfig<TState>` (line 525)
+
+Fields: `id`, `routes: DecisionRoute<TState>[]`, `fallback: NodeId`, `name?`, `description?`.
+
+Each `DecisionRoute` (line 509) has `condition: (state) => boolean`, `target: NodeId`, and optional `label`.
+
+**Produced NodeDefinition:** type `"decision"`
+
+**Execute behavior** (lines 577-588): Iterates `routes` in order. Returns `{ goto: route.target }` for the first matching condition. Falls back to `{ goto: fallback }` if none match.
+
+#### `waitNode(config)` (line 657)
+
+**Config type:** `WaitNodeConfig<TState>` (line 610)
+
+Fields: `id`, `prompt` (string or state function), `autoApprove?` (boolean, default `false`), `inputMapper?: InputMapper<TState>`, `name?`, `description?`.
+
+**Produced NodeDefinition:** type `"wait"`
+
+**Execute behavior** (lines 667-691):
+- If `autoApprove` is true: applies `inputMapper("")` and continues without signal
+- Otherwise: emits `"human_input_required"` signal with the resolved prompt
+
+#### `askUserNode(config)` (line 814)
+
+**Config type:** `AskUserNodeConfig<TState>` (line 726)
+
+Fields: `id`, `options` (static `AskUserOptions` or state function), `name?`, `description?`.
+
+`AskUserOptions` (line 712): `question: string`, `header?: string`, `options?: AskUserOption[]`.
+
+**Produced NodeDefinition:** type `"ask_user"`
+
+**Execute behavior** (lines 824-862):
+1. Resolves options (static or function of state)
+2. Generates `requestId` via `crypto.randomUUID()`
+3. Calls `ctx.emit("human_input_required", eventData)` if `emit` is available
+4. Returns state update with wait flags (`__waitingForInput`, `__waitNodeId`, `__askUserRequestId`)
+5. Emits `"human_input_required"` signal
+
+#### `parallelNode(config)` (line 967)
+
+**Config type:** `ParallelNodeConfig<TState>` (line 889)
+
+Fields: `id`, `branches: NodeId[]` (must be non-empty), `strategy?: ParallelMergeStrategy` (`"all"` | `"race"` | `"any"`, default `"all"`), `outputMapper?` (or deprecated `merge?`), `name?`, `description?`.
+
+**Produced NodeDefinition:** type `"parallel"`
+
+**Execute behavior** (lines 982-1007):
+1. Stores parallel context (branches, strategy, outputMapper) in `outputs[id]` with `_parallel: true` marker
+2. Returns `{ goto: branches }` to direct the execution engine to all branch nodes
+
+#### `subgraphNode(config)` (line 1121)
+
+**Config type:** `SubgraphNodeConfig<TState, TSubState>` (line 1040)
+
+Fields: `id`, `subgraph` (`CompiledSubgraph<TSubState>` or workflow name string), `inputMapper?`, `outputMapper?`, `name?`, `description?`.
+
+**Produced NodeDefinition:** type `"subgraph"`
+
+**Execute behavior** (lines 1132-1176):
+1. If `subgraph` is a string: resolves via `ctx.config.runtime.workflowResolver` -- throws if resolver is missing or workflow not found
+2. If `subgraph` is an object: uses directly
+3. Maps parent state to subgraph state via `inputMapper` (or casts state directly)
+4. Calls `resolvedSubgraph.execute(subState)`
+5. Maps subgraph output back via `outputMapper` or stores in `outputs[id]`
+
+#### `contextMonitorNode(config)` (line 1328)
+
+**Config type:** `ContextMonitorNodeConfig<TState>` (line 1202)
+
+Fields: `id`, `agentType`, `threshold?` (default 45%), `action?` (auto-detected by agent type), `getSession?`, `getContextUsage?`, `onCompaction?`, `name?`, `description?`.
+
+**Produced NodeDefinition:** type `"tool"`, name `"context-monitor"`
+
+**Execute behavior** (lines 1348-1465):
+1. Gets context usage from: `customGetContextUsage`, or `getSession().getContextUsage()`, or `ctx.contextWindowUsage`
+2. Updates `contextWindowUsage` in state
+3. If threshold exceeded, takes action based on `action`:
+   - `"summarize"`: calls `session.summarize()`, gets updated usage
+   - `"recreate"`: emits signal with `shouldRecreateSession: true`
+   - `"warn"`: emits warning signal only
+   - `"none"`: does nothing
+
+Default actions by agent type (via `getDefaultCompactionAction()`, line 1262):
+- `"opencode"` -> `"summarize"`
+- `"claude"` -> `"recreate"`
+- `"copilot"` -> `"warn"`
+
+#### `customToolNode(config)` (line 1554)
+
+**Config type:** `CustomToolNodeConfig<TState, TArgs, TResult>` (line 1526)
+
+Fields: `id`, `toolName`, `name?`, `description?`, `inputSchema?` (Zod), `args?`, `outputMapper?`, `timeout?`, `retry?`.
+
+**Produced NodeDefinition:** type `"tool"`
+
+**Execute behavior** (lines 1565-1627):
+1. Resolves tool from `getToolRegistry().get(config.toolName)` -- throws if not found
+2. Resolves args (static or state function)
+3. If `inputSchema` provided, validates via Zod `.safeParse()` -- throws `SchemaValidationError` on failure
+4. Builds `WorkflowToolContext` with `sessionID`, `messageID`, `agent: "workflow"`, `directory: process.cwd()`, frozen state snapshot
+5. Calls `entry.definition.handler(args, toolContext)`
+6. Maps result via `outputMapper` or stores in `outputs[id]`
+7. Wraps non-schema errors in `NodeExecutionError`
+
+#### `subagentNode(config)` (line 1664)
+
+**Config type:** `SubagentNodeConfig<TState>` (line 1638)
+
+Fields: `id`, `name?`, `description?`, `agentName`, `task` (string or state function), `systemPrompt?` (string or state function), `model?`, `tools?`, `outputMapper?`, `retry?`.
+
+**Produced NodeDefinition:** type `"agent"`
+
+**Execute behavior** (lines 1673-1726):
+1. Gets `subagentBridge` from `ctx.config.runtime` -- throws if missing
+2. Gets `subagentRegistry` from `ctx.config.runtime` -- throws if missing
+3. Looks up agent entry by `config.agentName` -- throws if not found
+4. Resolves `task` and `systemPrompt` (static or state function)
+5. Calls `bridge.spawn({ agentId, agentName, task, systemPrompt, model, tools })`
+6. Throws if `result.success` is false
+7. Maps result via `outputMapper` or stores `result.output` in `outputs[id]`
+
+#### `parallelSubagentNode(config)` (line 1764)
+
+**Config type:** `ParallelSubagentNodeConfig<TState>` (line 1736)
+
+Fields: `id`, `name?`, `description?`, `agents` (array of `{ agentName, task, systemPrompt?, model?, tools? }`), `outputMapper?` (or deprecated `merge?`), `retry?`.
+
+**Produced NodeDefinition:** type `"parallel"`
+
+**Execute behavior** (lines 1780-1808):
+1. Gets `subagentBridge` from `ctx.config.runtime` -- throws if missing
+2. Maps each agent config to `SubagentSpawnOptions` with unique `agentId` (`${config.id}-${i}-${executionId}`)
+3. Calls `bridge.spawnParallel(spawnOptions)` (runs all agents concurrently)
+4. Builds a `Map<string, SubagentResult>` keyed by `"${agentName}-${index}"`
+5. Calls `outputMapper(resultMap, state)` -- throws at construction time if no outputMapper provided (line 1768)
+
+### Helper Functions
+
+- **`getDefaultCompactionAction(agentType)`** (line 1262): Maps agent type to compaction action.
+- **`toContextWindowUsage(usage)`** (line 1281): Converts SDK `ContextUsage` to graph `ContextWindowUsage`.
+- **`isContextThresholdExceeded(usage, threshold)`** (line 1297): Returns `usage.usagePercentage >= threshold`.
+- **`checkContextUsage(session, options?)`** (line 1486): Gets usage from session and checks threshold.
+- **`compactContext(session, agentType)`** (line 1503): Calls `session.summarize()` for opencode agents.
+
+---
+
+## 4. Types (`src/workflows/graph/types.ts`)
+
+### Core Identity and Classification Types
+
+- **`NodeId`** (line 69): `string` -- Unique identifier for graph nodes.
+- **`ModelSpec`** (line 91): `string | "inherit"` -- LLM model specification. `"inherit"` means use parent/graph-level model.
+- **`NodeType`** (line 104): `"agent" | "tool" | "decision" | "wait" | "ask_user" | "subgraph" | "parallel"` -- Enumeration of supported node types.
+
+### State Management
+
+#### `BaseState` (line 114)
+
+The root state interface all workflow states must extend.
+
+| Field | Type | Purpose |
+|---|---|---|
+| `executionId` | `string` | Unique execution instance ID |
+| `lastUpdated` | `string` | ISO timestamp of last state update |
+| `outputs` | `Record<NodeId, unknown>` | Node outputs keyed by node ID |
+
+#### `ContextWindowUsage` (line 126)
+
+Tracks token consumption: `inputTokens`, `outputTokens`, `maxTokens`, `usagePercentage` (0-100).
+
+### Signals
+
+#### `Signal` (line 149)
+
+Union type: `"context_window_warning" | "checkpoint" | "human_input_required" | "debug_report_generated"`.
+
+#### `SignalData` (line 158)
+
+Contains `type: Signal`, optional `message: string`, and optional `data: Record<string, unknown>`.
+
+### Error Handling
+
+#### `ExecutionError` (line 174)
+
+Records a node execution failure: `nodeId`, `error` (Error or string), `timestamp` (ISO), `attempt` (1-based).
+
+#### `RetryConfig` (line 188)
+
+| Field | Type | Default |
+|---|---|---|
+| `maxAttempts` | `number` | 3 |
+| `backoffMs` | `number` | 1000 |
+| `backoffMultiplier` | `number` | 2 |
+| `retryOn?` | `(error: Error) => boolean` | All errors retried |
+
+#### `ErrorAction<TState>` (line 205)
+
+Discriminated union returned by `onError` handlers:
+- `{ action: "retry"; delay?: number }` -- retry with optional custom delay
+- `{ action: "skip"; fallbackState?: Partial<TState> }` -- skip node with fallback
+- `{ action: "abort"; error?: Error }` -- abort execution
+- `{ action: "goto"; nodeId: NodeId }` -- jump to recovery node
+
+#### `DebugReport` (line 215)
+
+Diagnostic information: `errorSummary`, `stackTrace?`, `relevantFiles`, `suggestedFixes`, `generatedAt`, `nodeId?`, `executionId?`.
+
+### Node Execution Types
+
+#### `NodeResult<TState>` (line 242)
+
+Return type from node execute functions:
+- `stateUpdate?: Partial<TState>` -- state changes to merge
+- `goto?: NodeId | NodeId[]` -- override next node(s)
+- `signals?: SignalData[]` -- execution flow signals
+
+#### `ExecutionContext<TState>` (line 267)
+
+Provided to every node execution:
+
+| Field | Type | Purpose |
+|---|---|---|
+| `state` | `TState` | Current workflow state |
+| `config` | `GraphConfig` | Graph configuration |
+| `errors` | `ExecutionError[]` | Accumulated errors |
+| `abortSignal?` | `AbortSignal` | Cancellation signal |
+| `contextWindowUsage?` | `ContextWindowUsage` | Current token usage |
+| `contextWindowThreshold?` | `number` | Threshold percentage |
+| `emit?` | `(type, data?) => void` | Custom event emitter |
+| `getNodeOutput?` | `(nodeId) => unknown` | Access previous node outputs |
+| `model?` | `string` | Resolved model for this context |
+
+#### `NodeExecuteFn<TState>` (line 314)
+
+Type alias: `(context: ExecutionContext<TState>) => Promise<NodeResult<TState>>`.
+
+#### `NodeDefinition<TState>` (line 323)
+
+The complete node specification:
+
+| Field | Type | Required |
+|---|---|---|
+| `id` | `NodeId` | Yes |
+| `type` | `NodeType` | Yes |
+| `execute` | `NodeExecuteFn<TState>` | Yes |
+| `inputSchema?` | `z.ZodType<TState>` | No |
+| `outputSchema?` | `z.ZodType<TState>` | No |
+| `retry?` | `RetryConfig` | No |
+| `onError?` | `(error, context) => ErrorAction \| Promise<ErrorAction>` | No |
+| `isRecoveryNode?` | `boolean` | No |
+| `name?` | `string` | No |
+| `description?` | `string` | No |
+| `model?` | `ModelSpec` | No |
+
+### Graph Configuration
+
+#### `ProgressEvent<TState>` (line 379)
+
+Progress callback payload: `type` (`"node_started" | "node_completed" | "node_error" | "checkpoint_saved"`), `nodeId`, `state`, `error?`, `timestamp`.
+
+#### `GraphRuntimeDependencies` (line 396)
+
+Runtime services injected by `WorkflowSDK.init()`:
+- `clientProvider?: (agentType: string) => CodingAgentClient | null`
+- `workflowResolver?: (name: string) => RuntimeSubgraph | null`
+- `subagentBridge?: { spawn(...), spawnParallel(...) }`
+- `subagentRegistry?: { get(name), getAll() }`
+
+#### `GraphConfig<TState>` (line 414)
+
+| Field | Type | Default |
+|---|---|---|
+| `checkpointer?` | `Checkpointer<TState>` | None (in-memory only) |
+| `maxConcurrency?` | `number` | 1 |
+| `timeout?` | `number` (ms) | No limit |
+| `onProgress?` | `(event: ProgressEvent<TState>) => void` | -- |
+| `contextWindowThreshold?` | `number` | 45 |
+| `autoCheckpoint?` | `boolean` | `true` |
+| `metadata?` | `Record<string, unknown>` | -- |
+| `defaultModel?` | `ModelSpec` | -- |
+| `outputSchema?` | `z.ZodType<TState>` | -- |
+| `runtime?` | `GraphRuntimeDependencies` | -- |
+
+### Edge Definitions
+
+#### `EdgeCondition<TState>` (line 488)
+
+Type alias: `(state: TState) => boolean`.
+
+#### `Edge<TState>` (line 497)
+
+Directed edge: `from: NodeId`, `to: NodeId`, `condition?: EdgeCondition<TState>`, `label?: string`.
+
+### Compiled Graph
+
+#### `CompiledGraph<TState>` (line 521)
+
+The compiled graph ready for execution:
+- `nodes: Map<NodeId, NodeDefinition<TState>>` -- all node definitions
+- `edges: Edge<TState>[]` -- all edges
+- `startNode: NodeId` -- entry point
+- `endNodes: Set<NodeId>` -- terminal nodes
+- `config: GraphConfig<TState>` -- graph configuration
+
+### Execution State
+
+#### `ExecutionStatus` (line 541)
+
+Union: `"pending" | "running" | "paused" | "completed" | "failed" | "cancelled"`.
+
+#### `ExecutionSnapshot<TState>` (line 555)
+
+Full snapshot for checkpointing/resumption:
+- `executionId`, `state`, `status`, `currentNodeId?`, `visitedNodes: NodeId[]`, `errors: ExecutionError[]`, `signals: SignalData[]`, `startedAt`, `updatedAt`, `completedAt?`, `nodeExecutionCount`
+
+### Checkpointer Interface (line 30)
+
+| Method | Signature |
+|---|---|
+| `save` | `(executionId: string, state: TState, label?: string) => Promise<void>` |
+| `load` | `(executionId: string) => Promise<TState \| null>` |
+| `list` | `(executionId: string) => Promise<string[]>` |
+| `delete` | `(executionId: string, label?: string) => Promise<void>` |
+
+### Type Guards
+
+- **`isNodeType(value)`** (line 587): Checks if value is a valid `NodeType`.
+- **`isSignal(value)`** (line 597): Checks if value is a valid `Signal`.
+- **`isExecutionStatus(value)`** (line 612): Checks if value is a valid `ExecutionStatus`.
+- **`isBaseState(value)`** (line 624): Checks for `executionId`, `lastUpdated`, and `outputs` fields.
+- **`isNodeResult(value)`** (line 640): Validates optional `stateUpdate`, `goto`, and `signals` fields.
+- **`isDebugReport(value)`** (line 661): Checks for `errorSummary`, `relevantFiles`, `suggestedFixes`, `generatedAt`.
+
+### Utility Types
+
+- **`StateOf<T>`** (line 681): Extracts `TState` from a `NodeDefinition<TState>`.
+- **`StateUpdate<TState>`** (line 686): `Partial<Omit<TState, keyof BaseState>> & { outputs?: Record<NodeId, unknown> }`.
+
+### Constants
+
+| Name | Value | Line |
+|---|---|---|
+| `BACKGROUND_COMPACTION_THRESHOLD` | `0.45` | 691 |
+| `BUFFER_EXHAUSTION_THRESHOLD` | `0.6` | 693 |
+| `DEFAULT_RETRY_CONFIG` | `{ maxAttempts: 3, backoffMs: 1000, backoffMultiplier: 2 }` | 698 |
+| `DEFAULT_GRAPH_CONFIG` | `{ maxConcurrency: 1, contextWindowThreshold: 45, autoCheckpoint: true }` | 707 |
+
+### Error Types (`src/workflows/graph/errors.ts`)
+
+- **`SchemaValidationError`** (line 16): Extends `Error` with `zodError: ZodError`. Thrown when Zod schema validation fails.
+- **`NodeExecutionError`** (line 30): Extends `Error` with `nodeId: string` and optional `cause: Error`. Wraps runtime tool/agent failures.
+- **`ErrorFeedback`** (line 44): Interface for error context injected into retry attempts: `failedNodeId`, `errorMessage`, `errorType`, `attempt`, `maxAttempts`, `previousOutput?`.
+
+---
+
+## Data Flow Summary
+
+```
+graph<TState>()           GraphBuilder
+  .start(node)               |
+  .then(node)                |-- accumulates nodes/edges
+  .loop(body, config)        |
+  .if(cond).then().endif()   |
+  .end()                     |
+  .compile(config)        CompiledGraph<TState>
+                              |
+              createExecutor(compiledGraph)
+                              |
+                        GraphExecutor<TState>
+                              |
+              .execute()  or  .stream()
+                              |
+                        streamSteps()  [AsyncGenerator]
+                              |
+          +---------+---------+---------+
+          |         |         |         |
+      init state  node queue  retry   signals
+          |         |         |         |
+          v         v         v         v
+      mergeState  getNextNodes  executeWithRetry  checkpoint/pause
+```
+
+1. **Build phase**: `GraphBuilder` accumulates `NodeDefinition` objects and `Edge` objects via fluent calls.
+2. **Compile phase**: `.compile()` copies internal maps/arrays into a frozen `CompiledGraph` object with auto-discovered end nodes.
+3. **Execute phase**: `GraphExecutor.streamSteps()` runs a queue-based traversal. Each node is executed via `executeWithRetry()`, state is merged via `mergeState()`, and next nodes are determined by `getNextNodes()` (edges + conditions + `result.goto`).
+4. **Loops**: Loop check nodes use conditional back-edges to the first body node. The `isLoopNode()` check in the executor allows re-visiting loop infrastructure nodes.
+5. **Conditionals**: Decision nodes route via conditional edges created by `.endif()`. Merge nodes rejoin branches.
+6. **Signals**: Nodes can emit signals (`human_input_required`, `checkpoint`, `context_window_warning`) that alter execution flow.
+7. **Streaming**: `StreamRouter` projects `StepResult` items into typed `StreamEvent` objects based on requested modes.
diff --git a/research/docs/2026-02-25-install-postinstall-analysis.md b/research/docs/2026-02-25-install-postinstall-analysis.md
new file mode 100644
index 0000000000..cb9a55db0f
--- /dev/null
+++ b/research/docs/2026-02-25-install-postinstall-analysis.md
@@ -0,0 +1,1437 @@
+---
+date: 2026-02-25
+researcher: Claude Code (codebase-analyzer agent)
+git_commit: TBD
+branch: main
+repository: playwright-cli (atomic fork)
+topic: "Installation and Postinstall Infrastructure Analysis"
+tags: [analysis, installation, postinstall, config-sync, skills]
+status: complete
+---
+
+# Analysis: Installation and Postinstall Infrastructure
+
+## Overview
+
+The Atomic CLI uses a multi-stage installation and configuration sync system. The infrastructure supports three installation modes (source, npm, binary) and ensures that bundled agent configurations (.claude, .opencode, .copilot) are synced to `~/.atomic` for global discovery while intelligently excluding SCM-specific skills (gh-*, sl-*) that should be project-scoped.
+
+## Entry Points
+
+The installation infrastructure has three main entry points:
+
+1. **`install.sh`** - Unix/macOS shell installer (bash)
+2. **`install.ps1`** - Windows PowerShell installer
+3. **`src/scripts/postinstall.ts`** - npm/bun package postinstall hook
+
+All three paths eventually call the same core logic in `src/utils/atomic-global-config.ts`.
+
+---
+
+## 1. `install.sh` - Unix/macOS Shell Installer
+
+### Overview
+A bash script that downloads pre-compiled binaries from GitHub Releases and syncs bundled config templates to `~/.atomic`.
+
+### Entry Point
+- Lines 174-259: `main()` function orchestrates the entire installation
+
+### Core Implementation
+
+#### 1. Configuration and Setup (`install.sh:8-20`)
+
+```bash
+GITHUB_REPO="flora131/atomic"
+BINARY_NAME="atomic"
+BIN_DIR="${ATOMIC_INSTALL_DIR:-$HOME/.local/bin}"
+DATA_DIR="${XDG_DATA_HOME:-$HOME/.local/share}/atomic"
+ATOMIC_HOME="$HOME/.atomic"
+```
+
+**Key Variables:**
+- `BIN_DIR` - Where the binary executable is installed (default: `~/.local/bin`)
+- `DATA_DIR` - Where config templates are extracted (default: `~/.local/share/atomic`)
+- `ATOMIC_HOME` - Global agent config directory (`~/.atomic`)
+
+#### 2. Platform Detection (`install.sh:28-60`)
+
+The `detect_platform()` function identifies OS and architecture:
+
+**OS Detection (lines 33-43):**
+- Maps `uname -s` output to: `linux`, `darwin`
+- On Windows (MinGW/Cygwin/MSYS), delegates to PowerShell installer at line 39
+
+**Architecture Detection (lines 45-49):**
+- Maps `uname -m` to: `x64` (from x86_64/amd64) or `arm64` (from arm64/aarch64)
+
+**Rosetta 2 Detection (lines 52-57):**
+- On macOS with x64 architecture, checks `sysctl.proc_translated`
+- If running under Rosetta 2 emulation, switches to native `arm64` binary
+- This ensures Apple Silicon Macs get the ARM binary even if shell runs in x64 mode
+
+**Returns:** Platform string in format `${os}-${arch}` (e.g., "linux-x64", "darwin-arm64")
+
+#### 3. Binary Download and Verification (`install.sh:199-221`)
+
+**Download URLs (lines 199-202):**
+```bash
+base_url="https://github.com/${GITHUB_REPO}/releases/download/${version}"
+download_url="${base_url}/${BINARY_NAME}-${platform}"
+config_url="${base_url}/${BINARY_NAME}-config.tar.gz"
+checksums_url="${base_url}/checksums.txt"
+```
+
+**Download Process:**
+1. Line 206: Downloads binary to temp directory using `curl`
+2. Line 212: Downloads config tarball (`atomic-config.tar.gz`)
+3. Line 216: Downloads checksums file
+
+**Checksum Verification (lines 113-140):**
+- `verify_checksum()` function validates SHA256 checksums
+- Lines 127-133: Uses `sha256sum` (Linux) or `shasum -a 256` (macOS)
+- Lines 135-137: Fails installation if checksums don't match
+- Protects against corrupted downloads or man-in-the-middle attacks
+
+#### 4. Config Files Extraction (`install.sh:228-231`)
+
+```bash
+rm -rf "$DATA_DIR"
+mkdir -p "$DATA_DIR"
+tar -xzf "${tmp_dir}/${BINARY_NAME}-config.tar.gz" -C "$DATA_DIR"
+```
+
+**Behavior:**
+- Performs a **clean install** by removing existing `$DATA_DIR`
+- Extracts tarball contents to `~/.local/share/atomic/`
+- Tarball contains: `.claude/`, `.opencode/`, `.github/`, `.mcp.json`
+
+#### 5. `sync_global_agent_configs()` Function (`install.sh:144-165`)
+
+This is the **critical configuration sync logic** that populates `~/.atomic`:
+
+**Directory Creation (line 147):**
+```bash
+mkdir -p "$ATOMIC_HOME/.claude" "$ATOMIC_HOME/.opencode" "$ATOMIC_HOME/.copilot"
+```
+
+**Config Copying (lines 149-155):**
+```bash
+cp -R "$source_root/.claude/." "$ATOMIC_HOME/.claude/"
+cp -R "$source_root/.opencode/." "$ATOMIC_HOME/.opencode/"
+cp -R "$source_root/.github/." "$ATOMIC_HOME/.copilot/"
+
+if [[ -f "$source_root/.mcp.json" ]]; then
+    cp "$source_root/.mcp.json" "$ATOMIC_HOME/.mcp.json"
+fi
+```
+
+**Key Mapping:**
+- `.claude/` → `~/.atomic/.claude/`
+- `.opencode/` → `~/.atomic/.opencode/`
+- `.github/` → `~/.atomic/.copilot/` (note the rename!)
+- `.mcp.json` → `~/.atomic/.mcp.json`
+
+**SCM Skill Exclusion (lines 158-160):**
+```bash
+rm -rf "$ATOMIC_HOME/.claude/skills/gh-"* "$ATOMIC_HOME/.claude/skills/sl-"* 2>/dev/null || true
+rm -rf "$ATOMIC_HOME/.opencode/skills/gh-"* "$ATOMIC_HOME/.opencode/skills/sl-"* 2>/dev/null || true
+rm -rf "$ATOMIC_HOME/.copilot/skills/gh-"* "$ATOMIC_HOME/.copilot/skills/sl-"* 2>/dev/null || true
+```
+
+**Why exclude SCM skills?**
+- Skills prefixed with `gh-*` (GitHub) and `sl-*` (Sapling) are **project-scoped**
+- These are installed per-repository via `atomic init` command
+- Global installation would conflict with per-project SCM configuration
+- Examples: `gh-commit`, `gh-create-pr`, `sl-commit`, `sl-submit-diff`
+
+**Copilot Cleanup (lines 163-164):**
+```bash
+rm -rf "$ATOMIC_HOME/.copilot/workflows" 2>/dev/null || true
+rm -f "$ATOMIC_HOME/.copilot/dependabot.yml" 2>/dev/null || true
+```
+
+**Rationale:**
+- Keeps Copilot global config focused on skills/agents/instructions/MCP
+- Removes GitHub-specific workflow and dependency management files
+- These belong in project repositories, not global config
+
+#### 6. PATH Configuration (`install.sh:84-110`, `245-253`)
+
+**Shell Detection (lines 63-81):**
+- Detects user's shell from `$SHELL` variable
+- Supports: fish, zsh, bash, and generic shells
+
+**PATH Addition (lines 84-110):**
+- For fish: Uses `fish_add_path $BIN_DIR`
+- For bash/zsh: Uses `export PATH="$BIN_DIR:$PATH"`
+- Only adds if `$BIN_DIR` not already in config
+- Creates config file if it doesn't exist
+
+**Execution (lines 245-253):**
+- Checks if `$BIN_DIR` already in current `$PATH`
+- If not, adds it to detected shell config file
+- Warns user to restart shell or source config file
+
+### Data Flow
+
+```
+GitHub Release
+    ↓
+1. Download atomic-linux-x64 (binary)
+2. Download atomic-config.tar.gz (configs)
+3. Download checksums.txt
+    ↓
+4. Verify checksums (SHA256)
+    ↓
+5. Install binary → ~/.local/bin/atomic
+6. Extract configs → ~/.local/share/atomic/
+    ↓
+7. sync_global_agent_configs():
+   - Copy ~/.local/share/atomic/.claude/ → ~/.atomic/.claude/
+   - Copy ~/.local/share/atomic/.opencode/ → ~/.atomic/.opencode/
+   - Copy ~/.local/share/atomic/.github/ → ~/.atomic/.copilot/
+   - Copy ~/.local/share/atomic/.mcp.json → ~/.atomic/.mcp.json
+   - Remove ~/.atomic/*/skills/gh-*
+   - Remove ~/.atomic/*/skills/sl-*
+   - Remove ~/.atomic/.copilot/workflows
+   - Remove ~/.atomic/.copilot/dependabot.yml
+    ↓
+8. Add ~/.local/bin to PATH in shell config
+```
+
+### Key Patterns
+
+- **Clean Install Strategy**: Removes `$DATA_DIR` before extraction to avoid stale files
+- **Security**: SHA256 checksum verification prevents compromised downloads
+- **Cross-Platform**: Delegates to PowerShell on Windows detection
+- **Atomic Operations**: Uses temp directory with EXIT trap for cleanup
+- **Idempotent PATH**: Only adds to shell config if not already present
+
+---
+
+## 2. `install.ps1` - Windows PowerShell Installer
+
+### Overview
+PowerShell script providing equivalent functionality to `install.sh` for Windows platforms.
+
+### Entry Point
+- Lines 113-235: Main installation logic (not in a named function)
+
+### Core Implementation
+
+#### 1. Configuration (`install.ps1:13-18`)
+
+```powershell
+$GithubRepo = "flora131/atomic"
+$BinaryName = "atomic"
+$BinDir = if ($env:ATOMIC_INSTALL_DIR) { $env:ATOMIC_INSTALL_DIR } elseif ($InstallDir) { $InstallDir } else { "${Home}\.local\bin" }
+$DataDir = if ($env:LOCALAPPDATA) { "${env:LOCALAPPDATA}\atomic" } else { "${Home}\AppData\Local\atomic" }
+$AtomicHome = "${Home}\.atomic"
+```
+
+**Key Differences from Unix:**
+- `$DataDir` uses `%LOCALAPPDATA%\atomic` instead of XDG data home
+- `$BinDir` uses `\.local\bin` under user home
+- Binary has `.exe` extension
+
+#### 2. Architecture Detection (`install.ps1:66-75`)
+
+```powershell
+$Arch = $env:PROCESSOR_ARCHITECTURE
+switch ($Arch) {
+    "AMD64" { $Target = "windows-x64.exe" }
+    "ARM64" { $Target = "windows-arm64.exe" }
+    default {
+        Write-Err "Unsupported architecture: $Arch"
+        exit 1
+    }
+}
+```
+
+**Simpler than Unix:**
+- No OS detection needed (PowerShell implies Windows)
+- No Rosetta 2 detection needed
+- Uses `$env:PROCESSOR_ARCHITECTURE` environment variable
+
+#### 3. Download and Verification (`install.ps1:116-169`)
+
+**Dual Download Strategy (lines 116-131):**
+```powershell
+if (Get-Command curl.exe -ErrorAction SilentlyContinue) {
+    curl.exe "-#SfLo" $TempBinary $DownloadUrl
+} else {
+    Write-Info "curl.exe not found, using Invoke-WebRequest..."
+    Invoke-WebRequest -Uri $DownloadUrl -OutFile $TempBinary -UseBasicParsing
+}
+```
+
+**Fallback Logic:**
+- Prefers native `curl.exe` (available in Windows 10 1803+)
+- Falls back to PowerShell's `Invoke-WebRequest`
+- Provides better compatibility across Windows versions
+
+**Checksum Verification (lines 138-169):**
+```powershell
+$ExpectedHash = ($ExpectedLine -split '\s+')[0].ToLower()
+$ActualHash = (Get-FileHash -Path $TempBinary -Algorithm SHA256).Hash.ToLower()
+
+if ($ActualHash -ne $ExpectedHash) {
+    Write-Err "Checksum verification failed!"
+    Write-Err "Expected: $ExpectedHash"
+    Write-Err "Actual:   $ActualHash"
+    exit 1
+}
+```
+
+**Verifies both:**
+1. Binary checksum (lines 138-152)
+2. Config archive checksum (lines 155-169)
+
+#### 4. Config Extraction (`install.ps1:175-178`)
+
+```powershell
+if (Test-Path $DataDir) { Remove-Item -Recurse -Force $DataDir }
+$null = New-Item -ItemType Directory -Force -Path $DataDir
+Expand-Archive -Path $TempConfig -DestinationPath $DataDir -Force
+```
+
+**Key Differences:**
+- Uses `Expand-Archive` for `.zip` files (not `.tar.gz`)
+- Clean install by removing existing `$DataDir`
+- Archives are uploaded as `atomic-config.zip` for Windows
+
+#### 5. `Sync-GlobalAgentConfigs` Function (`install.ps1:20-51`)
+
+The PowerShell equivalent of the bash function:
+
+**Directory Creation (lines 27-29):**
+```powershell
+$null = New-Item -ItemType Directory -Force -Path $claudeDir
+$null = New-Item -ItemType Directory -Force -Path $opencodeDir
+$null = New-Item -ItemType Directory -Force -Path $copilotDir
+```
+
+**Config Copying (lines 31-38):**
+```powershell
+Copy-Item -Path (Join-Path $SourceRoot ".claude\*") -Destination $claudeDir -Recurse -Force
+Copy-Item -Path (Join-Path $SourceRoot ".opencode\*") -Destination $opencodeDir -Recurse -Force
+Copy-Item -Path (Join-Path $SourceRoot ".github\*") -Destination $copilotDir -Recurse -Force
+
+$mcpConfigSource = Join-Path $SourceRoot ".mcp.json"
+if (Test-Path $mcpConfigSource) {
+    Copy-Item -Path $mcpConfigSource -Destination (Join-Path $AtomicHome ".mcp.json") -Force
+}
+```
+
+**SCM Skill Removal (lines 40-47):**
+```powershell
+foreach ($agentDir in @($claudeDir, $opencodeDir, $copilotDir)) {
+    $skillsDir = Join-Path $agentDir "skills"
+    if (Test-Path $skillsDir) {
+        Get-ChildItem -Path $skillsDir -Directory -ErrorAction SilentlyContinue |
+            Where-Object { $_.Name -like "gh-*" -or $_.Name -like "sl-*" } |
+            ForEach-Object { Remove-Item -Recurse -Force $_.FullName -ErrorAction SilentlyContinue }
+    }
+}
+```
+
+**Copilot Cleanup (lines 49-50):**
+```powershell
+Remove-Item -Recurse -Force (Join-Path $copilotDir "workflows") -ErrorAction SilentlyContinue
+Remove-Item -Force (Join-Path $copilotDir "dependabot.yml") -ErrorAction SilentlyContinue
+```
+
+**Implementation Notes:**
+- Uses PowerShell cmdlets instead of Unix commands
+- Same exclusion logic as bash version
+- Handles errors gracefully with `-ErrorAction SilentlyContinue`
+
+#### 6. PATH Configuration (`install.ps1:194-222`)
+
+**User PATH Update (lines 196-199):**
+```powershell
+$UserPath = [System.Environment]::GetEnvironmentVariable('Path', 'User')
+if ($UserPath -notlike "*${BinDir}*") {
+    [System.Environment]::SetEnvironmentVariable('Path', "${BinDir};${UserPath}", 'User')
+    $env:Path = "${BinDir};${env:Path}"
+}
+```
+
+**Environment Broadcast (lines 202-215):**
+```powershell
+Add-Type -Namespace Win32 -Name NativeMethods -MemberDefinition @"
+[DllImport("user32.dll", SetLastError = true, CharSet = CharSet.Auto)]
+public static extern IntPtr SendMessageTimeout(
+    IntPtr hWnd, uint Msg, UIntPtr wParam, string lParam,
+    uint fuFlags, uint uTimeout, out UIntPtr lpdwResult);
+"@
+
+[Win32.NativeMethods]::SendMessageTimeout(
+    [IntPtr]0xFFFF, 0x1A, [UIntPtr]::Zero, "Environment", 2, 5000, [ref]$result
+) | Out-Null
+```
+
+**Advanced Windows Feature:**
+- Uses P/Invoke to call Win32 API `SendMessageTimeout`
+- Broadcasts `WM_SETTINGCHANGE` message (0x1A) to all windows
+- Message parameter "Environment" notifies of PATH change
+- Allows new terminals to pick up PATH without system restart
+- Handles errors gracefully (warns if broadcast fails)
+
+### Data Flow
+
+```
+GitHub Release
+    ↓
+1. Download atomic-windows-x64.exe
+2. Download atomic-config.zip (not .tar.gz)
+3. Download checksums.txt
+    ↓
+4. Verify checksums (SHA256)
+    ↓
+5. Install binary → %USERPROFILE%\.local\bin\atomic.exe
+6. Extract configs → %LOCALAPPDATA%\atomic\
+    ↓
+7. Sync-GlobalAgentConfigs:
+   - Copy %LOCALAPPDATA%\atomic\.claude\ → %USERPROFILE%\.atomic\.claude\
+   - Copy %LOCALAPPDATA%\atomic\.opencode\ → %USERPROFILE%\.atomic\.opencode\
+   - Copy %LOCALAPPDATA%\atomic\.github\ → %USERPROFILE%\.atomic\.copilot\
+   - Copy %LOCALAPPDATA%\atomic\.mcp.json → %USERPROFILE%\.atomic\.mcp.json
+   - Remove %USERPROFILE%\.atomic\*\skills\gh-*
+   - Remove %USERPROFILE%\.atomic\*\skills\sl-*
+   - Remove %USERPROFILE%\.atomic\.copilot\workflows
+   - Remove %USERPROFILE%\.atomic\.copilot\dependabot.yml
+    ↓
+8. Add %USERPROFILE%\.local\bin to User PATH
+9. Broadcast WM_SETTINGCHANGE to notify system
+```
+
+### Key Patterns
+
+- **Dual Download Strategy**: curl.exe fallback to Invoke-WebRequest
+- **Win32 API Integration**: Uses P/Invoke for environment broadcast
+- **PowerShell Idioms**: Uses `-ErrorAction SilentlyContinue` extensively
+- **Same Core Logic**: Mirrors bash implementation with PowerShell syntax
+
+---
+
+## 3. `src/scripts/postinstall.ts` - npm/bun Postinstall Hook
+
+### Overview
+A Bun script that runs after `npm install` or `bun install` to sync bundled configs to `~/.atomic`.
+
+### Entry Point
+- Lines 15-25: `main()` function
+
+### Core Implementation
+
+#### 1. Imports (`postinstall.ts:3-7`)
+
+```typescript
+import {
+  hasAtomicGlobalAgentConfigs,
+  syncAtomicGlobalAgentConfigs,
+} from "../utils/atomic-global-config";
+import { getConfigRoot } from "../utils/config-path";
+```
+
+**Dependencies:**
+- `atomic-global-config.ts` - Core sync logic
+- `config-path.ts` - Installation type detection and path resolution
+
+#### 2. Main Function (`postinstall.ts:15-25`)
+
+```typescript
+async function main(): Promise<void> {
+  try {
+    await syncAtomicGlobalAgentConfigs(getConfigRoot());
+    await verifyAtomicGlobalConfigSync();
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.warn(`[atomic] Warning: failed to sync ~/.atomic global configs: ${message}`);
+  }
+}
+```
+
+**Error Handling:**
+- Wrapped in try-catch at lines 16-22
+- Failures are **warnings, not errors**
+- Allows installation to succeed even if sync fails
+- Useful for restricted environments or CI systems
+
+#### 3. Verification (`postinstall.ts:9-13`)
+
+```typescript
+async function verifyAtomicGlobalConfigSync(): Promise<void> {
+  if (!(await hasAtomicGlobalAgentConfigs())) {
+    throw new Error("Missing synced global config entries in ~/.atomic");
+  }
+}
+```
+
+**Validation:**
+- Calls `hasAtomicGlobalAgentConfigs()` from atomic-global-config.ts
+- Ensures required directories and files exist after sync
+- Throws error if verification fails (caught by main)
+
+#### 4. Execution (`postinstall.ts:25`)
+
+```typescript
+await main();
+```
+
+**Top-level await:**
+- Enabled by Bun runtime
+- Script runs synchronously during install
+- Blocks until sync completes or fails
+
+### Configuration in `package.json`
+
+#### Postinstall Script (`package.json:40`)
+
+```json
+"scripts": {
+  "postinstall": "lefthook install && bun run src/scripts/postinstall.ts"
+}
+```
+
+**Execution Order:**
+1. `lefthook install` - Sets up Git hooks
+2. `bun run src/scripts/postinstall.ts` - Syncs global configs
+
+**When it runs:**
+- After `npm install` or `bun install`
+- After `npm install -g @bastani/atomic`
+- Not during binary installations (install.sh/install.ps1)
+
+#### Files Field (`package.json:22-31`)
+
+```json
+"files": [
+  "src",
+  "assets/settings.schema.json",
+  ".claude",
+  ".opencode",
+  ".mcp.json",
+  ".github/skills",
+  ".github/agents",
+  ".github/mcp-config.json"
+]
+```
+
+**What gets bundled:**
+- All TypeScript source (`src/`)
+- Config templates (`.claude/`, `.opencode/`, `.github/`)
+- MCP configuration files (`.mcp.json`, `.github/mcp-config.json`)
+- **Excludes:** `.github/workflows`, `.github/dependabot.yml`
+
+**Why this matters:**
+- npm package contains all templates needed for sync
+- Smaller package size by excluding CI/CD files
+- Matches exclusion logic in installer scripts
+
+### Data Flow
+
+```
+npm/bun install
+    ↓
+1. Install package to node_modules/@bastani/atomic/
+2. Run postinstall script
+    ↓
+3. getConfigRoot() determines installation type:
+   - Source: ~/project/atomic (repo root)
+   - npm: ~/project/node_modules/@bastani/atomic
+   - Binary: ~/.local/share/atomic (not applicable here)
+    ↓
+4. syncAtomicGlobalAgentConfigs(configRoot):
+   - Copies configRoot/.claude/ → ~/.atomic/.claude/
+   - Copies configRoot/.opencode/ → ~/.atomic/.opencode/
+   - Copies configRoot/.github/ → ~/.atomic/.copilot/
+   - Copies configRoot/.mcp.json → ~/.atomic/.mcp.json
+   - Excludes gh-*, sl-* skills
+   - Cleans up copilot workflows/dependabot.yml
+    ↓
+5. hasAtomicGlobalAgentConfigs() verifies sync
+6. Success or warning logged
+```
+
+### Key Patterns
+
+- **Non-blocking**: Warnings instead of errors for failures
+- **Idempotent**: Safe to run multiple times
+- **Installation-aware**: Uses `getConfigRoot()` for different install types
+- **Verification**: Validates sync completed successfully
+
+---
+
+## 4. `src/utils/atomic-global-config.ts` - Core Sync Logic
+
+### Overview
+The central module implementing all configuration sync logic used by both installer scripts (via shell) and postinstall (directly).
+
+### Entry Point
+- Line 128: `syncAtomicGlobalAgentConfigs()` - Main sync function
+
+### Core Implementation
+
+#### 1. Configuration Constants (`atomic-global-config.ts:8-34`)
+
+**Home Directory (line 8):**
+```typescript
+const ATOMIC_HOME_DIR = join(homedir(), ".atomic");
+```
+
+**SCM Skill Prefixes (line 10):**
+```typescript
+export const MANAGED_SCM_SKILL_PREFIXES = ["gh-", "sl-"] as const;
+```
+
+**Global Agent Folders (lines 12-16):**
+```typescript
+const GLOBAL_AGENT_FOLDER_BY_KEY: Record<AgentKey, string> = {
+  claude: ".claude",
+  opencode: ".opencode",
+  copilot: ".copilot",
+};
+```
+
+**Template Source Folders (lines 18-23):**
+```typescript
+const TEMPLATE_AGENT_FOLDER_BY_KEY: Record<AgentKey, string> = {
+  claude: AGENT_CONFIG.claude.folder,    // ".claude"
+  opencode: AGENT_CONFIG.opencode.folder, // ".opencode"
+  copilot: AGENT_CONFIG.copilot.folder,   // ".github"
+};
+```
+
+**Required Entries for Verification (lines 25-29):**
+```typescript
+const REQUIRED_GLOBAL_CONFIG_ENTRIES: Record<AgentKey, string[]> = {
+  claude: ["agents", "skills", "settings.json"],
+  opencode: ["agents", "skills", "opencode.json"],
+  copilot: ["agents", "skills"],
+};
+```
+
+**Atomic Home Required Files (lines 31-34):**
+```typescript
+const REQUIRED_ATOMIC_HOME_ENTRIES = [
+  ".mcp.json",
+  join(".copilot", "mcp-config.json"),
+] as const;
+```
+
+#### 2. SCM Skill Management (`atomic-global-config.ts:70-101`)
+
+**Identification (lines 71-73):**
+```typescript
+export function isManagedScmSkillName(name: string): boolean {
+  return MANAGED_SCM_SKILL_PREFIXES.some((prefix) => name.startsWith(prefix));
+}
+```
+
+**Pruning (lines 78-88):**
+```typescript
+async function pruneManagedScmSkills(agentDir: string): Promise<void> {
+  const skillsDir = join(agentDir, "skills");
+  if (!(await pathExists(skillsDir))) return;
+
+  const entries = await readdir(skillsDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (!isManagedScmSkillName(entry.name)) continue;
+    await rm(join(skillsDir, entry.name), { recursive: true, force: true });
+  }
+}
+```
+
+**Purpose:**
+- Removes stale SCM skills from previous installations
+- Ensures clean state for project-specific skill management
+- Called after copying templates (line 147)
+
+**Exclude List Generation (lines 93-101):**
+```typescript
+async function getManagedScmSkillExcludes(sourceDir: string): Promise<string[]> {
+  const skillsDir = join(sourceDir, "skills");
+  if (!(await pathExists(skillsDir))) return [];
+
+  const entries = await readdir(skillsDir, { withFileTypes: true });
+  return entries
+    .filter((entry) => entry.isDirectory() && isManagedScmSkillName(entry.name))
+    .map((entry) => join("skills", entry.name));
+}
+```
+
+**Purpose:**
+- Builds exclusion paths for SCM skills in source directory
+- Used by `copyDir()` to skip copying these skills
+- Returns relative paths like: `["skills/gh-commit", "skills/sl-commit"]`
+
+#### 3. MCP Config Sync (`atomic-global-config.ts:106-119`)
+
+```typescript
+async function syncAtomicGlobalMcpConfigs(configRoot: string, baseDir: string): Promise<void> {
+  const claudeMcpSource = join(configRoot, ".mcp.json");
+  const claudeMcpDestination = join(baseDir, ".mcp.json");
+  if (await pathExists(claudeMcpSource)) {
+    await copyFile(claudeMcpSource, claudeMcpDestination);
+  }
+
+  const copilotMcpSource = join(configRoot, AGENT_CONFIG.copilot.folder, "mcp-config.json");
+  const copilotMcpDestination = join(baseDir, GLOBAL_AGENT_FOLDER_BY_KEY.copilot, "mcp-config.json");
+  if (await pathExists(copilotMcpSource)) {
+    await mkdir(join(baseDir, GLOBAL_AGENT_FOLDER_BY_KEY.copilot), { recursive: true });
+    await copyFile(copilotMcpSource, copilotMcpDestination);
+  }
+}
+```
+
+**Two MCP Files:**
+1. **Claude MCP** (lines 107-111):
+   - Source: `{configRoot}/.mcp.json`
+   - Destination: `~/.atomic/.mcp.json`
+   
+2. **Copilot MCP** (lines 113-118):
+   - Source: `{configRoot}/.github/mcp-config.json`
+   - Destination: `~/.atomic/.copilot/mcp-config.json`
+
+**Conditional Copying:**
+- Only copies if source file exists
+- Creates parent directory for Copilot MCP if needed
+
+#### 4. Main Sync Function (`atomic-global-config.ts:128-151`)
+
+```typescript
+export async function syncAtomicGlobalAgentConfigs(
+  configRoot: string,
+  baseDir: string = ATOMIC_HOME_DIR
+): Promise<void> {
+  await mkdir(baseDir, { recursive: true });
+
+  const agentKeys = Object.keys(AGENT_CONFIG) as AgentKey[];
+  for (const agentKey of agentKeys) {
+    const sourceFolder = join(configRoot, getTemplateAgentFolder(agentKey));
+    if (!(await pathExists(sourceFolder))) continue;
+
+    const destinationFolder = join(baseDir, getAtomicGlobalAgentFolder(agentKey));
+    const scmSkillExcludes = await getManagedScmSkillExcludes(sourceFolder);
+
+    await copyDir(sourceFolder, destinationFolder, {
+      exclude: [...AGENT_CONFIG[agentKey].exclude, ...scmSkillExcludes],
+    });
+
+    // Ensure stale managed SCM skills from previous installs are removed.
+    await pruneManagedScmSkills(destinationFolder);
+  }
+
+  await syncAtomicGlobalMcpConfigs(configRoot, baseDir);
+}
+```
+
+**Step-by-Step:**
+
+1. **Create Base Directory (line 132):**
+   - Ensures `~/.atomic/` exists
+
+2. **Iterate Agent Keys (lines 134-149):**
+   - Loops through: `claude`, `opencode`, `copilot`
+
+3. **For Each Agent (lines 135-148):**
+   
+   **a. Resolve Paths (lines 136-140):**
+   ```typescript
+   const sourceFolder = join(configRoot, getTemplateAgentFolder(agentKey));
+   const destinationFolder = join(baseDir, getAtomicGlobalAgentFolder(agentKey));
+   ```
+   - Example for Claude:
+     - Source: `{configRoot}/.claude`
+     - Destination: `~/.atomic/.claude`
+
+   **b. Build Exclusion List (line 141):**
+   ```typescript
+   const scmSkillExcludes = await getManagedScmSkillExcludes(sourceFolder);
+   ```
+   - Scans source folder for `gh-*` and `sl-*` skill directories
+   - Returns relative paths to exclude
+
+   **c. Copy with Exclusions (lines 143-145):**
+   ```typescript
+   await copyDir(sourceFolder, destinationFolder, {
+     exclude: [...AGENT_CONFIG[agentKey].exclude, ...scmSkillExcludes],
+   });
+   ```
+   - Merges agent-specific excludes from config.ts
+   - Merges SCM skill excludes from step b
+   - Example for Copilot:
+     - Agent excludes: `["workflows", "dependabot.yml", "mcp-config.json", ".DS_Store"]`
+     - SCM excludes: `["skills/gh-commit", "skills/sl-commit", ...]`
+
+   **d. Prune Stale Skills (line 148):**
+   ```typescript
+   await pruneManagedScmSkills(destinationFolder);
+   ```
+   - Removes any `gh-*` or `sl-*` directories that may have slipped through
+   - Cleans up skills from previous installations
+
+4. **Sync MCP Configs (line 150):**
+   - Copies `.mcp.json` files for both Claude and Copilot
+
+#### 5. Verification Function (`atomic-global-config.ts:156-183`)
+
+```typescript
+export async function hasAtomicGlobalAgentConfigs(
+  baseDir: string = ATOMIC_HOME_DIR
+): Promise<boolean> {
+  const agentKeys = Object.keys(AGENT_CONFIG) as AgentKey[];
+
+  for (const agentKey of agentKeys) {
+    const agentDir = join(baseDir, getAtomicGlobalAgentFolder(agentKey));
+    if (!(await pathExists(agentDir))) return false;
+
+    const requiredEntries = REQUIRED_GLOBAL_CONFIG_ENTRIES[agentKey];
+    const entryChecks = await Promise.all(
+      requiredEntries.map((entryName) => pathExists(join(agentDir, entryName)))
+    );
+
+    if (entryChecks.some((exists) => !exists)) {
+      return false;
+    }
+  }
+
+  const atomicHomeChecks = await Promise.all(
+    REQUIRED_ATOMIC_HOME_ENTRIES.map((entryName) => pathExists(join(baseDir, entryName)))
+  );
+  if (atomicHomeChecks.some((exists) => !exists)) {
+    return false;
+  }
+
+  return true;
+}
+```
+
+**Verification Steps:**
+
+1. **Check Agent Directories (lines 161-173):**
+   - For each agent (claude, opencode, copilot):
+     - Verify directory exists
+     - Verify required entries exist
+   - Example for Claude:
+     - `~/.atomic/.claude/agents/` must exist
+     - `~/.atomic/.claude/skills/` must exist
+     - `~/.atomic/.claude/settings.json` must exist
+
+2. **Check Atomic Home Entries (lines 175-179):**
+   - Verify `~/.atomic/.mcp.json` exists
+   - Verify `~/.atomic/.copilot/mcp-config.json` exists
+
+3. **Return Result (line 181):**
+   - Returns `true` only if all checks pass
+   - Used by postinstall script to validate sync
+
+#### 6. Agent Config Source (`src/config.ts:29-70`)
+
+Referenced by atomic-global-config.ts at line 5:
+
+```typescript
+export const AGENT_CONFIG: Record<AgentKey, AgentConfig> = {
+  claude: {
+    name: "Claude Code",
+    cmd: "claude",
+    additional_flags: [],
+    folder: ".claude",
+    install_url: "https://code.claude.com/docs/en/setup",
+    exclude: [".DS_Store"],
+    additional_files: [".mcp.json"],
+    preserve_files: [],
+    merge_files: [".mcp.json"],
+  },
+  opencode: {
+    name: "OpenCode",
+    cmd: "opencode",
+    additional_flags: [],
+    folder: ".opencode",
+    install_url: "https://opencode.ai",
+    exclude: [
+      "node_modules",
+      ".gitignore",
+      "bun.lock",
+      "package.json",
+      ".DS_Store",
+    ],
+    additional_files: [],
+    preserve_files: [],
+    merge_files: [],
+  },
+  copilot: {
+    name: "GitHub Copilot CLI",
+    cmd: "copilot",
+    additional_flags: ["--add-dir", ".", "--yolo", "--disable-builtin-mcps"],
+    folder: ".github",
+    install_url: "https://github.com/github/copilot-cli?tab=readme-ov-file#installation",
+    exclude: ["workflows", "dependabot.yml", "mcp-config.json", ".DS_Store"],
+    additional_files: [".github/mcp-config.json"],
+    preserve_files: [],
+    merge_files: [".github/mcp-config.json"],
+  },
+};
+```
+
+**Key Fields for Sync:**
+- `folder` - Source directory in package/binary data
+- `exclude` - Paths to skip during copy
+- `additional_files` - Extra files to copy from repo root
+- `merge_files` - Files to merge (not overwrite) when exists
+
+### Data Flow
+
+```
+syncAtomicGlobalAgentConfigs(configRoot, baseDir)
+    ↓
+1. Create ~/.atomic/ directory
+    ↓
+2. For each agent (claude, opencode, copilot):
+   a. Resolve source folder:
+      - claude: {configRoot}/.claude
+      - opencode: {configRoot}/.opencode
+      - copilot: {configRoot}/.github
+   b. Resolve destination folder:
+      - claude: ~/.atomic/.claude
+      - opencode: ~/.atomic/.opencode
+      - copilot: ~/.atomic/.copilot
+   c. Scan source for SCM skills (gh-*, sl-*)
+   d. Build exclusion list:
+      - Agent-specific excludes from AGENT_CONFIG
+      - SCM skill directories
+   e. Copy with exclusions using copyDir()
+   f. Prune any remaining SCM skills from destination
+    ↓
+3. Copy MCP configs:
+   - {configRoot}/.mcp.json → ~/.atomic/.mcp.json
+   - {configRoot}/.github/mcp-config.json → ~/.atomic/.copilot/mcp-config.json
+    ↓
+Complete
+```
+
+### Key Patterns
+
+- **Abstraction**: Used by both shell scripts and TypeScript postinstall
+- **Double Protection**: Both excludes during copy AND prunes after
+- **Verification**: Separate function to validate sync success
+- **Configuration-Driven**: Uses AGENT_CONFIG for all agent-specific logic
+- **Idempotent**: Safe to run multiple times
+
+---
+
+## 5. Copy Utilities (`src/utils/copy.ts`)
+
+### Overview
+Provides cross-platform file/directory copying with exclusions, used by atomic-global-config.ts.
+
+### Key Functions
+
+#### 1. `copyDir()` (`copy.ts:117-185`)
+
+The main recursive directory copy function used by `syncAtomicGlobalAgentConfigs()`.
+
+**Signature (lines 117-122):**
+```typescript
+export async function copyDir(
+  src: string,
+  dest: string,
+  options: CopyOptions = {},
+  rootSrc?: string
+): Promise<void>
+```
+
+**Parameters:**
+- `src` - Source directory path
+- `dest` - Destination directory path
+- `options` - Copy options including exclusions
+- `rootSrc` - Root source path for calculating relative paths (internal)
+
+**Copy Options (lines 32-37):**
+```typescript
+interface CopyOptions {
+  exclude?: string[];
+  skipOppositeScripts?: boolean;
+}
+```
+
+**Implementation:**
+
+**a. Setup (lines 124-128):**
+```typescript
+const { exclude = [], skipOppositeScripts = true } = options;
+const root = rootSrc ?? src;
+await mkdir(dest, { recursive: true });
+const entries = await readdir(src, { withFileTypes: true });
+```
+
+**b. Platform Script Filtering (line 134):**
+```typescript
+const oppositeExt = getOppositeScriptExtension();
+```
+- Returns `.ps1` on Unix, `.sh` on Windows
+- Skips installer scripts for opposite platform
+
+**c. Entry Processing Loop (lines 139-173):**
+```typescript
+for (const entry of entries) {
+  const srcPath = join(src, entry.name);
+  const destPath = join(dest, entry.name);
+
+  // Validate destination path doesn't escape
+  if (!isPathSafe(dest, entry.name)) {
+    throw new Error(`Path traversal detected: ${entry.name}`);
+  }
+
+  // Calculate relative path from root
+  const relativePath = relative(root, srcPath);
+
+  // Check if this path should be excluded
+  if (shouldExclude(relativePath, entry.name, exclude)) {
+    continue;
+  }
+
+  // Skip opposite platform scripts
+  if (skipOppositeScripts && extname(entry.name) === oppositeExt) {
+    continue;
+  }
+
+  if (entry.isDirectory()) {
+    copyPromises.push(copyDir(srcPath, destPath, options, root));
+  } else if (entry.isFile()) {
+    copyPromises.push(copyFile(srcPath, destPath));
+  } else if (entry.isSymbolicLink()) {
+    copyPromises.push(copySymlinkAsFile(srcPath, destPath));
+  }
+}
+```
+
+**d. Parallel Execution (line 176):**
+```typescript
+await Promise.all(copyPromises);
+```
+- Copies all files/subdirectories in parallel for performance
+
+**Security Features:**
+- **Path traversal protection** (lines 144-148): Prevents `../` escapes
+- **Symlink dereferencing** (line 170): Copies target content, not symlink
+
+#### 2. `shouldExclude()` (`copy.ts:80-106`)
+
+Determines if a path should be skipped based on exclusion rules.
+
+```typescript
+export function shouldExclude(
+  relativePath: string,
+  name: string,
+  exclude: string[]
+): boolean {
+  // Check if the name matches any exclusion
+  if (exclude.includes(name)) {
+    return true;
+  }
+
+  // Normalize the relative path for cross-platform comparison
+  const normalizedPath = normalizePath(relativePath);
+
+  // Check if the relative path starts with any exclusion
+  for (const ex of exclude) {
+    const normalizedExclusion = normalizePath(ex);
+    if (
+      normalizedPath === normalizedExclusion ||
+      normalizedPath.startsWith(`${normalizedExclusion}/`)
+    ) {
+      return true;
+    }
+  }
+
+  return false;
+}
+```
+
+**Matching Logic:**
+1. **Basename match** (line 86): Checks if `name` exactly matches any exclusion
+   - Example: `name="workflows"` matches `exclude=["workflows"]`
+2. **Path prefix match** (lines 95-101): Checks if relative path starts with exclusion
+   - Example: `relativePath="skills/gh-commit"` matches `exclude=["skills/gh-commit"]`
+   - Also matches subdirectories: `"skills/gh-commit/foo"` matches `"skills/gh-commit"`
+
+**Path Normalization (line 92):**
+```typescript
+const normalizedPath = normalizePath(relativePath);
+```
+- Converts backslashes to forward slashes
+- Ensures Windows paths match Unix-style exclusion patterns
+
+#### 3. `copyFile()` (`copy.ts:43-51`)
+
+```typescript
+export async function copyFile(src: string, dest: string): Promise<void> {
+  try {
+    const srcFile = Bun.file(src);
+    await Bun.write(dest, srcFile);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Failed to copy ${src} to ${dest}: ${message}`);
+  }
+}
+```
+
+**Uses Bun's optimized file API:**
+- `Bun.file()` - Creates file reference
+- `Bun.write()` - Efficiently copies file content
+
+#### 4. `pathExists()` (`copy.ts:190-197`)
+
+```typescript
+export async function pathExists(path: string): Promise<boolean> {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+```
+
+**Used extensively for:**
+- Checking if source folders exist before copying
+- Verifying sync completed successfully
+- Conditional file copying (MCP configs)
+
+---
+
+## 6. Config Path Resolution (`src/utils/config-path.ts`)
+
+### Overview
+Detects installation type and resolves paths to config templates.
+
+### Key Functions
+
+#### 1. `detectInstallationType()` (`config-path.ts:29-45`)
+
+```typescript
+export function detectInstallationType(): InstallationType {
+  const dir = import.meta.dir;
+
+  // Bun compiled executables use a virtual filesystem with '$bunfs' prefix
+  if (dir.includes("$bunfs") || dir.startsWith("B:\\") || dir.startsWith("b:\\")) {
+    return "binary";
+  }
+
+  // Check for node_modules in path (npm/bun installed)
+  if (dir.includes("node_modules")) {
+    return "npm";
+  }
+
+  // Default to source (development mode)
+  return "source";
+}
+```
+
+**Detection Logic:**
+1. **Binary**: `import.meta.dir` contains `$bunfs` (Bun's virtual filesystem)
+   - Windows may show as `B:\` drive letter
+2. **npm**: Path contains `node_modules`
+3. **Source**: Everything else (development mode)
+
+**Why this matters:**
+- Binary installs read from `~/.local/share/atomic/`
+- npm installs read from `node_modules/@bastani/atomic/`
+- Source installs read from repo root
+
+#### 2. `getConfigRoot()` (`config-path.ts:77-99`)
+
+```typescript
+export function getConfigRoot(): string {
+  const installType = detectInstallationType();
+
+  if (installType === "binary") {
+    const dataDir = getBinaryDataDir();
+
+    if (!existsSync(dataDir)) {
+      throw new Error(
+        `Config data directory not found: ${dataDir}\n\n` +
+        `This usually means the installation is incomplete.\n` +
+        `Please reinstall using the install script.`
+      );
+    }
+
+    return dataDir;
+  }
+
+  // For source and npm installs, navigate up from the current file
+  return join(import.meta.dir, "..", "..");
+}
+```
+
+**Path Resolution:**
+- **Binary**: Returns `~/.local/share/atomic/` (or Windows equivalent)
+  - Must exist (validated)
+  - Populated by install.sh/install.ps1
+- **Source/npm**: Returns package root by navigating up from `src/utils/`
+  - `src/utils/config-path.ts` → `../..` → package root
+
+**Used By:**
+- `postinstall.ts` at line 17: `syncAtomicGlobalAgentConfigs(getConfigRoot())`
+- All commands that need to read bundled templates
+
+#### 3. `getBinaryDataDir()` (`config-path.ts:54-64`)
+
+```typescript
+export function getBinaryDataDir(): string {
+  if (isWindows()) {
+    const localAppData = process.env.LOCALAPPDATA || join(process.env.USERPROFILE || "", "AppData", "Local");
+    return join(localAppData, "atomic");
+  }
+
+  // Unix: follow XDG Base Directory spec
+  const xdgDataHome = process.env.XDG_DATA_HOME || join(process.env.HOME || "", ".local", "share");
+  return join(xdgDataHome, "atomic");
+}
+```
+
+**Platform-Specific Paths:**
+- **Unix/macOS**: `$XDG_DATA_HOME/atomic` or `~/.local/share/atomic`
+- **Windows**: `%LOCALAPPDATA%\atomic` or `%USERPROFILE%\AppData\Local\atomic`
+
+**Matches installer scripts:**
+- install.sh line 12: `DATA_DIR="${XDG_DATA_HOME:-$HOME/.local/share}/atomic"`
+- install.ps1 line 17: `$DataDir = "${env:LOCALAPPDATA}\atomic"`
+
+---
+
+## Installation Types Comparison
+
+| Aspect | Binary (install.sh/ps1) | npm/bun | Source |
+|--------|------------------------|---------|--------|
+| **Binary Location** | `~/.local/bin/atomic` | `node_modules/.bin/atomic` | N/A (bun run) |
+| **Config Source** | `~/.local/share/atomic/` | `node_modules/@bastani/atomic/` | Repo root |
+| **Sync Trigger** | install.sh line 234 | package.json postinstall | Manual or auto |
+| **Config Archive** | atomic-config.tar.gz | npm package files | N/A |
+| **PATH Setup** | Automatic (shell config) | npm handles | Manual |
+| **Verification** | Binary --version check | hasAtomicGlobalAgentConfigs() | N/A |
+
+---
+
+## WHERE to Install New Tools (e.g., Playwright CLI)
+
+### Location Analysis
+
+Based on the infrastructure analysis, here are the **integration points** for adding a new tool like Playwright CLI:
+
+### Option 1: As a Bundled Skill (Recommended)
+
+If Playwright CLI should be available globally across all projects:
+
+**1. Add Skill to Templates**
+
+Create skill directories in bundled templates:
+```
+.claude/skills/playwright-cli/
+.opencode/skills/playwright-cli/
+.github/skills/playwright-cli/
+```
+
+These will be synced to `~/.atomic/` by the installation system.
+
+**2. Add to package.json Files Array** (`package.json:22-31`)
+
+Add new skill directories to ensure they're included in npm package:
+```json
+"files": [
+  "src",
+  ".claude",
+  ".claude/skills/playwright-cli",  // Add this
+  ".opencode",
+  ".opencode/skills/playwright-cli", // Add this
+  ".github/skills",
+  ".github/skills/playwright-cli",   // Add this
+  ...
+]
+```
+
+**3. No Changes Needed to Installers**
+
+The existing infrastructure will automatically:
+- Extract skill from atomic-config.tar.gz (install.sh line 231)
+- Expand skill from atomic-config.zip (install.ps1 line 178)
+- Copy skill to ~/.atomic/ (sync functions)
+
+**4. Skill Will Be Available Globally**
+
+After installation, all agents can discover:
+- `~/.atomic/.claude/skills/playwright-cli/`
+- `~/.atomic/.opencode/skills/playwright-cli/`
+- `~/.atomic/.copilot/skills/playwright-cli/`
+
+### Option 2: As an SCM-Specific Skill (Project-Scoped)
+
+If Playwright CLI should be project-specific (like gh-*, sl-*):
+
+**1. Name with Prefix Pattern**
+
+Name the skill to match SCM pattern:
+```
+gh-playwright  # GitHub-specific
+sl-playwright  # Sapling-specific
+```
+
+**2. Will Be Automatically Excluded**
+
+The infrastructure will automatically:
+- Skip during global sync (install.sh lines 158-160)
+- Exclude during copy (atomic-global-config.ts line 141)
+- Prune from global config (atomic-global-config.ts line 148)
+
+**3. Install Per-Project**
+
+Skills will be installed via `atomic init` command for each repository.
+
+### Option 3: As a Separate Binary Tool
+
+If Playwright CLI is a standalone binary (not an agent skill):
+
+**1. Add to Installer Scripts**
+
+**In install.sh** (after line 226):
+```bash
+# Install additional tools
+info "Installing Playwright CLI..."
+curl --fail --location --progress-bar \
+  --output "${BIN_DIR}/playwright-cli" \
+  "https://github.com/your-org/playwright-cli/releases/download/${PLAYWRIGHT_VERSION}/playwright-cli-${platform}" || \
+  warn "Failed to install Playwright CLI"
+chmod +x "${BIN_DIR}/playwright-cli"
+```
+
+**In install.ps1** (after line 172):
+```powershell
+# Install additional tools
+Write-Info "Installing Playwright CLI..."
+try {
+    $PlaywrightUrl = "https://github.com/your-org/playwright-cli/releases/download/${PlaywrightVersion}/playwright-cli-${Target}"
+    $PlaywrightPath = "${BinDir}\playwright-cli.exe"
+    Invoke-WebRequest -Uri $PlaywrightUrl -OutFile $PlaywrightPath -UseBasicParsing
+} catch {
+    Write-Warn "Failed to install Playwright CLI: $_"
+}
+```
+
+**2. Add to npm Package**
+
+If distributing as npm package dependency:
+```json
+"dependencies": {
+  "@your-org/playwright-cli": "^1.0.0"
+}
+```
+
+Then add to bin in package.json:
+```json
+"bin": {
+  "atomic": "src/cli.ts",
+  "playwright-cli": "node_modules/@your-org/playwright-cli/bin/cli.js"
+}
+```
+
+### Option 4: As an MCP Tool
+
+If Playwright CLI should integrate via Model Context Protocol:
+
+**1. Add to MCP Config** (`.mcp.json`)
+
+```json
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["-y", "@your-org/playwright-mcp-server"],
+      "env": {}
+    }
+  }
+}
+```
+
+**2. Sync Happens Automatically**
+
+The infrastructure will:
+- Copy `.mcp.json` to `~/.atomic/.mcp.json` (atomic-global-config.ts line 110)
+- Make available to Claude Code and other MCP-compatible agents
+
+### Recommended Approach for Playwright CLI
+
+Based on the codebase patterns, the **recommended approach** is:
+
+**Option 1 (Bundled Skill) + Option 4 (MCP Tool)**
+
+1. **Create skill templates** in `.claude/skills/playwright-cli/`, etc.
+2. **Add MCP server config** to `.mcp.json` for tool integration
+3. **Include in package.json files array** for npm distribution
+4. **Let existing infrastructure handle syncing** to `~/.atomic/`
+
+This provides:
+- ✅ Global availability across all projects
+- ✅ Agent-agnostic (works with Claude, OpenCode, Copilot)
+- ✅ No installer script modifications needed
+- ✅ Automatic sync on install/update
+- ✅ MCP integration for advanced capabilities
+
+---
+
+## Summary
+
+The Atomic CLI installation infrastructure is a **three-layer system**:
+
+1. **Platform-Specific Installers** (install.sh, install.ps1)
+   - Download and install pre-compiled binaries
+   - Extract config templates to data directories
+   - Call sync functions to populate `~/.atomic/`
+   - Configure PATH in shell configs
+
+2. **npm/bun Postinstall Hook** (src/scripts/postinstall.ts)
+   - Runs after package installation
+   - Delegates to core sync logic
+   - Handles source and npm install modes
+
+3. **Core Sync Logic** (src/utils/atomic-global-config.ts)
+   - Central implementation used by both layers
+   - Copies agent configs to `~/.atomic/`
+   - Excludes SCM-specific skills (gh-*, sl-*)
+   - Cleans up Copilot workflows and dependabot.yml
+
+**Key Design Principles:**
+- **Configuration-Driven**: Uses AGENT_CONFIG for all agent-specific logic
+- **Cross-Platform**: Consistent behavior on Unix, macOS, and Windows
+- **Idempotent**: Safe to run multiple times
+- **Secure**: SHA256 verification, path traversal protection
+- **Flexible**: Supports three installation types (binary, npm, source)
+
+**For Adding New Tools:**
+- **Global Skills**: Add to template directories, include in package.json files
+- **Project Skills**: Use SCM prefix (gh-*, sl-*) for automatic exclusion
+- **Binary Tools**: Modify installer scripts to download and install
+- **MCP Tools**: Add to .mcp.json for automatic sync
+
+---
+
+## File Reference Summary
+
+| File | Lines of Interest | Purpose |
+|------|------------------|---------|
+| **install.sh** | 144-165 | `sync_global_agent_configs()` - Copies configs, excludes SCM skills |
+| **install.sh** | 228-234 | Config extraction and sync invocation |
+| **install.ps1** | 20-51 | `Sync-GlobalAgentConfigs` - PowerShell equivalent |
+| **install.ps1** | 175-181 | Config extraction and sync invocation |
+| **postinstall.ts** | 15-25 | Main function calling sync logic |
+| **atomic-global-config.ts** | 128-151 | `syncAtomicGlobalAgentConfigs()` - Core sync implementation |
+| **atomic-global-config.ts** | 78-88 | `pruneManagedScmSkills()` - Removes stale SCM skills |
+| **atomic-global-config.ts** | 156-183 | `hasAtomicGlobalAgentConfigs()` - Verification |
+| **config.ts** | 29-70 | `AGENT_CONFIG` - Agent configuration definitions |
+| **copy.ts** | 117-185 | `copyDir()` - Recursive copy with exclusions |
+| **config-path.ts** | 29-45 | `detectInstallationType()` - Install mode detection |
+| **config-path.ts** | 77-99 | `getConfigRoot()` - Config template path resolution |
+| **package.json** | 22-31 | `files` array - npm package contents |
+| **package.json** | 40 | `postinstall` script - Hook definition |
diff --git a/research/docs/2026-02-25-playwright-cli-capabilities.md b/research/docs/2026-02-25-playwright-cli-capabilities.md
new file mode 100644
index 0000000000..353d38a89b
--- /dev/null
+++ b/research/docs/2026-02-25-playwright-cli-capabilities.md
@@ -0,0 +1,1368 @@
+# Playwright CLI Capabilities Research
+
+**Date**: February 25, 2026  
+**Repository**: microsoft/playwright-cli  
+**Related Repositories**: microsoft/playwright, anthropics/anthropic-cookbook  
+**Research Method**: DeepWiki AI-powered repository analysis
+
+---
+
+## Executive Summary
+
+Playwright CLI (`@playwright/cli`) is a token-efficient command-line interface designed specifically for coding agents and AI assistants to automate browser interactions. It is located within the Playwright monorepo at `packages/playwright/src/mcp/terminal/` and provides a streamlined alternative to Playwright MCP for high-throughput coding agents. The CLI emphasizes efficiency by avoiding large tool schemas and verbose accessibility trees, making it ideal for AI agent integration.
+
+**Key Highlights:**
+- **Purpose**: Browser automation for testing, form filling, screenshots, and data extraction
+- **Primary Audience**: Coding agents and AI assistants
+- **Distribution**: npm package `@playwright/cli`
+- **Token Efficiency**: Designed to minimize context usage for AI models
+- **Browser Support**: Chromium, Firefox, WebKit, MS Edge
+- **Session Management**: Supports persistent and named sessions for state preservation
+
+---
+
+## 1. What is Playwright CLI?
+
+### Overview and Purpose
+
+Playwright CLI is a command-line interface for Playwright designed to automate browser interactions for tasks such as web testing, form filling, taking screenshots, and data extraction.
+
+**Source References:**
+- `microsoft/playwright-cli` README.md
+- Wiki: [Getting Started](https://deepwiki.com/wiki/microsoft/playwright-cli#2)
+- Monorepo location: `https://github.com/microsoft/playwright/tree/main/packages/playwright/src/mcp/terminal`
+
+### Primary Design Goal
+
+The CLI provides a **token-efficient way for coding agents** to interact with browsers, avoiding the overhead of larger tool schemas and verbose accessibility trees that are present in Playwright MCP.
+
+### Key Capabilities
+
+1. **Browser Automation and Interaction**
+   - Open browsers and navigate to URLs
+   - Interact with page elements using element references (e.g., `e1`, `e2`)
+   - Execute commands like `click`, `fill`, `type`, `press`
+   - Support for all major browsers (Chromium, Firefox, WebKit, MS Edge)
+
+2. **Session Management**
+   - **Default Session**: In-memory browser profile (cookies/storage preserved between commands, lost on close)
+   - **Persistent Sessions**: `--persistent` flag saves profile to disk, preserving data across restarts
+   - **Named Sessions**: `-s=` flag creates isolated browser instances for concurrent automation
+   - **Session Control**: Commands like `list`, `close-all`, `kill-all`
+
+3. **Output Artifacts**
+   - `screenshot [ref]`: Capture screenshots of pages or elements
+   - `pdf`: Save current page as PDF
+   - `snapshot`: Capture page snapshot with element references (saved as YAML files)
+
+4. **Browser Types and Display Modes**
+   - Support for multiple browsers via `--browser` flag
+   - Headless mode (default) or headed mode with `--headed` flag
+
+5. **Advanced Capabilities**
+   - Request mocking: Intercept, mock, modify, and block network requests
+   - Running custom Playwright code with `run-code` command
+   - Storage state management (cookies, localStorage, sessionStorage)
+   - Tracing and video recording for debugging
+
+**Source Reference:** Wiki [Getting Started (microsoft/playwright-cli)](/wiki/microsoft/playwright-cli#2)
+
+---
+
+## 2. Installation Methods
+
+### Global Installation (Recommended)
+
+The recommended method is global installation for system-wide access:
+
+```bash
+npm install -g @playwright/cli@latest
+playwright-cli --help
+```
+
+**Package Details:**
+- **npm Package**: `@playwright/cli`
+- **Binary Name**: `playwright-cli`
+- **Entry Point**: `playwright-cli.js`
+
+### Local Installation
+
+For project-specific installations:
+
+```bash
+npm install @playwright/cli
+npx playwright-cli --help
+```
+
+When using local installation, prefix all commands with `npx`:
+
+```bash
+npx playwright-cli open https://example.com
+npx playwright-cli click e1
+```
+
+### Installation Notes
+
+- No standalone binary distribution outside of npm is currently available
+- The CLI is a Node.js package requiring Node.js runtime
+- Browser binaries are automatically downloaded by Playwright on installation
+
+**Source References:**
+- Wiki: [Getting Started (microsoft/playwright-cli)](/wiki/microsoft/playwright-cli#2)
+- `package.json` in repository
+- DeepWiki search: [Installation methods](https://deepwiki.com/search/how-do-you-install-playwright_93627ae0-c074-4105-8518-239fa410e4fd)
+
+---
+
+## 3. CLI Commands and API
+
+Playwright CLI provides a comprehensive set of commands categorized by function:
+
+### Core Commands
+
+| Command | Purpose | Source |
+|---------|---------|--------|
+| `open [url]` | Launch browser, optionally navigate to URL | README.md, SKILL.md |
+| `goto <url>` | Navigate to specified URL | README.md |
+| `close` | Close current browser page/session | README.md |
+| `type <text>` | Type text into focused element | README.md |
+| `click <ref> [button]` | Click element by reference | README.md |
+| `dblclick <ref> [button]` | Double-click element | README.md |
+| `fill <ref> <text>` | Fill text input field | README.md |
+| `drag <startRef> <endRef>` | Drag and drop operation | README.md |
+| `hover <ref>` | Hover over element | README.md |
+| `select <ref> <val>` | Select dropdown option | README.md |
+| `upload <file>` | Upload file(s) | README.md |
+| `check <ref>` | Check checkbox/radio button | README.md |
+| `uncheck <ref>` | Uncheck checkbox | README.md |
+| `snapshot` | Capture page snapshot for element references | README.md |
+| `eval <func> [ref]` | Evaluate JavaScript on page/element | README.md |
+| `dialog-accept [prompt]` | Accept dialog with optional prompt | README.md |
+| `dialog-dismiss` | Dismiss dialog | README.md |
+| `resize <w> <h>` | Resize browser window | README.md |
+
+### Navigation Commands
+
+- `go-back`: Navigate to previous page
+- `go-forward`: Navigate to next page
+- `reload`: Reload current page
+
+### Keyboard Commands
+
+- `press <key>`: Press single key
+- `keydown <key>`: Press key down
+- `keyup <key>`: Release key
+
+### Mouse Commands
+
+- `mousemove <x> <y>`: Move mouse to position
+- `mousedown [button]`: Press mouse button
+- `mouseup [button]`: Release mouse button
+- `mousewheel <dx> <dy>`: Scroll mouse wheel
+
+### Save Artifact Commands
+
+- `screenshot [ref]`: Screenshot page or element
+- `pdf`: Save page as PDF
+
+### Tab Management Commands
+
+- `tab-list`: List all open tabs
+- `tab-new [url]`: Create new tab
+- `tab-close [index]`: Close tab by index
+- `tab-select <index>`: Select tab by index
+
+### Storage Management Commands
+
+- `state-save [filename]`: Save storage state
+- `state-load <filename>`: Load storage state
+- `cookie-list [--domain]`: List cookies
+- `cookie-get <name>`: Get specific cookie
+- `cookie-set <name> <val>`: Set cookie
+- `cookie-delete <name>`: Delete cookie
+- `localstorage-list`: List localStorage items
+- `localstorage-get <key>`: Get localStorage value
+- `localstorage-set <key> <val>`: Set localStorage value
+- `localstorage-delete <key>`: Delete localStorage item
+- `sessionstorage-list`: List sessionStorage items
+- (Similar commands for sessionStorage)
+
+### Network and DevTools Commands
+
+- `route <url> <action>`: Mock network requests
+- `console`: Access console messages
+- `run-code <func>`: Execute arbitrary Playwright code
+
+### Session Management Commands
+
+- `list`: List active sessions
+- `close-all`: Close all sessions
+- `kill-all`: Kill all sessions
+
+**Source References:**
+- `skills/playwright-cli/SKILL.md`
+- Wiki: [Getting Started (microsoft/playwright-cli)](/wiki/microsoft/playwright-cli#2)
+- DeepWiki search: [CLI commands](https://deepwiki.com/search/what-cli-commands-and-api-does_217802ef-1b35-4a8f-9a67-b5fe32955eb7)
+
+---
+
+## 4. Web Browsing/Fetching Capabilities
+
+### Web Scraping and Data Extraction
+
+Yes, Playwright CLI can be used for web scraping, page fetching, and web searching through browser automation.
+
+#### Core Web Browsing Features
+
+1. **Page Navigation**
+   - Open browsers and navigate to URLs: `playwright-cli open [url]` and `playwright-cli goto <url>`
+   - Support for Chromium, Firefox, WebKit browsers
+   - Headless mode (default) or headed mode with `--headed` flag
+
+2. **Session Management for Scraping**
+   - Persistent sessions maintain cookies and storage state
+   - Named sessions (`-s=`) for concurrent scraping or isolated scenarios
+   - Useful for maintaining authentication states across requests
+
+3. **Page Interaction**
+   - Interact with elements: `click`, `fill`, `type`, `check`, `hover`, `select`
+   - Element references from snapshots (e.g., `e1`, `e2`)
+   - Tab management for multi-page scraping
+
+#### Data Extraction Methods
+
+1. **HTML Content Retrieval**
+   ```bash
+   playwright-cli run-code "async page => { return await page.content(); }"
+   ```
+
+2. **JavaScript Evaluation**
+   ```bash
+   playwright-cli eval <func> [ref]
+   ```
+   Evaluate JavaScript expressions on page or specific elements
+
+3. **Custom Scraping Scripts**
+   Use `run-code` command to execute complex Playwright scripts:
+   ```bash
+   playwright-cli run-code "async page => {
+     const products = await page.evaluate(() => {
+       return Array.from(document.querySelectorAll('.product')).map(p => ({
+         name: p.querySelector('.name').textContent,
+         price: p.querySelector('.price').textContent
+       }));
+     });
+     return products;
+   }"
+   ```
+
+4. **Snapshots for Element Discovery**
+   After each command, CLI provides snapshots with:
+   - Current URL
+   - Page title
+   - Element references for further interaction
+
+5. **Screenshots and PDF Export**
+   - Capture visual artifacts of pages
+   - Export pages as PDFs for archival
+
+6. **Network Request Control**
+   - Mock network requests with `route` command
+   - Control data fetched by browser during scraping
+
+#### Use Cases for Web Scraping
+
+- **Dynamic Content**: Handle JavaScript-rendered content
+- **Form Submission**: Automate form filling and submission
+- **Authentication**: Maintain login states across scraping sessions
+- **Multi-page Navigation**: Navigate through paginated results
+- **Interactive Elements**: Click buttons, expand sections before scraping
+- **Screenshot Documentation**: Capture visual states of pages
+
+**Source References:**
+- README.md
+- Wiki: [Getting Started (microsoft/playwright-cli)](/wiki/microsoft/playwright-cli#2)
+- DeepWiki search: [Web scraping capabilities](https://deepwiki.com/search/can-playwright-cli-be-used-for_c2ea5019-8c44-41d2-bd7b-93e7998300e5)
+
+---
+
+## 5. MCP Integration
+
+### Relationship with Model Context Protocol
+
+**Key Finding**: Playwright CLI is positioned as an **alternative to MCP**, not an implementation of it.
+
+#### Playwright CLI vs. Playwright MCP
+
+**Playwright CLI (`@playwright/cli`)**:
+- Token-efficient CLI-based workflow
+- Designed for high-throughput coding agents
+- Avoids large tool schemas and verbose accessibility trees
+- Best for agents that need efficient browser automation
+
+**Playwright MCP** (separate project at `microsoft/playwright-mcp`):
+- Full MCP protocol implementation
+- Relevant for specialized agentic loops
+- Requires persistent state and rich introspection
+- Designed for iterative reasoning over page structure
+- Better for exploratory automation, self-healing tests, or long-running autonomous workflows
+
+#### MCP-Related Configuration
+
+Despite being an alternative to MCP, Playwright CLI includes MCP-aware configuration:
+
+**Environment Variables** (prefixed with `PLAYWRIGHT_MCP_`):
+- `PLAYWRIGHT_MCP_ALLOWED_HOSTS`: Control allowed hosts
+- `PLAYWRIGHT_MCP_CDP_ENDPOINT`: Chrome DevTools Protocol endpoint
+- `PLAYWRIGHT_MCP_SAVE_SESSION`: Session persistence
+- `PLAYWRIGHT_MCP_BROWSER`: Browser type
+- `PLAYWRIGHT_MCP_HEADLESS`: Headless mode
+- `PLAYWRIGHT_MCP_OUTPUT_DIR`: Output directory path
+- `PLAYWRIGHT_MCP_CONFIG`: Configuration file path
+
+#### Source Code Location
+
+The Playwright CLI sources are located within the Playwright monorepo at:
+- **Path**: `packages/playwright/src/mcp/terminal/`
+- **Repository**: `https://github.com/microsoft/playwright`
+
+This indicates that `playwright-cli` is a component within a broader MCP-related structure, even though it serves as a standalone alternative to full MCP integration.
+
+#### When to Use Each
+
+**Use Playwright CLI when:**
+- Building high-throughput coding agents
+- Token efficiency is critical
+- Simple command-based automation is sufficient
+- No need for persistent browser context
+
+**Use Playwright MCP when:**
+- Implementing specialized agentic loops
+- Need persistent state across operations
+- Require rich introspection of page structure
+- Building self-healing tests or exploratory automation
+- Long-running autonomous workflows
+
+**Source References:**
+- Wiki: [Overview (microsoft/playwright-cli)](/wiki/microsoft/playwright-cli#1)
+- Wiki: [Development (microsoft/playwright-cli)](/wiki/microsoft/playwright-cli#7)
+- README.md
+- DeepWiki search: [MCP integration](https://deepwiki.com/search/does-playwright-cli-support-mc_bf2568c3-0422-4568-bbae-6e274786b302)
+
+### Playwright MCP Server Integration
+
+From the broader Playwright ecosystem research, Playwright provides MCP servers:
+
+1. **Browser Interaction MCP Server**
+   - Command: `npx playwright run-mcp-server`
+   - Provides browser interaction capabilities over MCP
+
+2. **Test Runner MCP Server**
+   - Command: `npx playwright run-test-mcp-server`
+   - Allows interaction with Playwright test runner over MCP
+
+3. **Playwright Test Agents**
+   - 🎭 **planner**: Explores app and generates test plans
+   - 🎭 **generator**: Converts plans to Playwright Test files
+   - 🎭 **healer**: Executes tests and auto-repairs failures
+   - Initialize with: `npx playwright init-agents`
+   - Supports providers: VSCode, Claude, OpenCode, Copilot
+
+**Source References:**
+- `microsoft/playwright` repository
+- DeepWiki search: [MCP best practices](https://deepwiki.com/search/what-are-the-best-practices-fo_50c91c3c-4f41-4d2b-b8ea-7407d9455c5b)
+
+---
+
+## 6. Binary Distribution
+
+### Current Distribution Model
+
+**Playwright CLI is NOT available as a standalone binary.** It is distributed exclusively as an npm package.
+
+#### Distribution Details
+
+- **Package Name**: `@playwright/cli`
+- **Entry Point**: `playwright-cli.js` (Node.js script)
+- **Execution Method**: Requires Node.js runtime
+- **Installation**: Via npm (global or local)
+
+#### Architecture
+
+The `package.json` defines:
+```json
+{
+  "bin": {
+    "playwright-cli": "playwright-cli.js"
+  }
+}
+```
+
+The `playwright-cli.js` file is a Node.js script that requires `playwright/lib/cli/client/program`, meaning it depends on the main Playwright library's CLI infrastructure.
+
+#### Bundling as Executable
+
+**Current Status**: The provided codebase does not contain information or mechanisms for bundling Playwright CLI as a standalone executable.
+
+**Potential Approaches** (not currently implemented):
+- Tools like `pkg`, `nexe`, or `caxa` could theoretically bundle Node.js apps as executables
+- Would need to bundle Node.js runtime, npm packages, and browser binaries
+- Browser binaries alone are several hundred MB per browser
+- No official support or documentation for this approach
+
+#### Why No Standalone Binary?
+
+1. **Browser Dependencies**: Requires browser binaries (Chromium, Firefox, WebKit)
+2. **Node.js Runtime**: Built on Node.js infrastructure
+3. **Dynamic Updates**: npm allows easy updates and version management
+4. **Size Constraints**: Browser binaries make distribution package very large
+
+**Source References:**
+- `package.json` in repository
+- `playwright-cli.js` entry point
+- Wiki: [Overview (microsoft/playwright-cli)](/wiki/microsoft/playwright-cli#1)
+- DeepWiki search: [Binary distribution](https://deepwiki.com/search/can-playwright-cli-be-distribu_b6e90084-e97d-432b-b71d-6259e5b16d51)
+
+---
+
+## 7. Dependencies
+
+### Runtime Dependencies
+
+Playwright CLI has minimal runtime dependencies:
+
+**Direct Dependencies** (from `package.json`):
+1. **`playwright`**: The core Playwright library (main dependency)
+2. **`minimist`**: Command-line argument parser
+
+### Browser Installation
+
+**Key Feature**: Playwright CLI does **NOT** require browsers to be installed separately.
+
+#### Automatic Browser Management
+
+When you install Playwright:
+- Browser binaries are automatically downloaded (Chromium, Firefox, WebKit)
+- Browsers are managed by Playwright itself
+- Default location: `~/.cache/ms-playwright/` (Linux/macOS) or `%USERPROFILE%\AppData\Local\ms-playwright\` (Windows)
+
+#### Browser Selection
+
+Use `--browser` flag to specify browser:
+```bash
+playwright-cli open --browser=chrome    # Uses Chromium
+playwright-cli open --browser=firefox   # Uses Firefox
+playwright-cli open --browser=webkit    # Uses WebKit
+playwright-cli open --browser=msedge    # Uses MS Edge
+```
+
+#### Browser Installation Commands
+
+From main Playwright library:
+```bash
+# Install all browsers
+npx playwright install
+
+# Install specific browser
+npx playwright install chromium
+npx playwright install firefox
+npx playwright install webkit
+
+# Install browser dependencies (Linux only)
+npx playwright install-deps
+```
+
+### Development Dependencies
+
+For repository maintenance (not runtime):
+- TypeScript tooling
+- Linting tools
+- Testing frameworks
+- Build scripts
+
+### Deprecated Package Note
+
+There's a separate deprecated `playwright-cli` package with:
+- **No functional dependencies**
+- Acts only as redirection mechanism
+- Redirects to `npx playwright`
+
+**Source References:**
+- `package.json` in repository
+- Wiki: [Overview (microsoft/playwright-cli)](/wiki/microsoft/playwright-cli#1)
+- Wiki: [Skills Maintenance (microsoft/playwright-cli)](/wiki/microsoft/playwright-cli#7.2)
+- DeepWiki search: [Dependencies](https://deepwiki.com/search/what-are-the-runtime-dependenc_7063bd6b-fbb0-403e-9a70-f4210d1df406)
+
+---
+
+## 8. Configuration
+
+Playwright CLI can be configured through three complementary methods:
+
+### 1. Command-Line Flags
+
+#### Browser and Display Options
+
+| Flag | Purpose | Example |
+|------|---------|---------|
+| `--browser` | Specify browser engine | `--browser=chrome`, `--browser=firefox`, `--browser=webkit`, `--browser=msedge` |
+| `--headed` | Run with visible browser window | `playwright-cli open --headed https://example.com` |
+| `--persistent` | Save browser profile to disk | `playwright-cli open --persistent` |
+| `--profile=<path>` | Custom profile directory | `--profile=/path/to/profile` |
+
+#### Session Management
+
+| Flag | Purpose | Example |
+|------|---------|---------|
+| `-s=<name>` | Named session for isolation | `playwright-cli -s=mysession open https://example.com` |
+| `--config` | Load configuration file | `--config path/to/config.json` |
+
+### 2. Environment Variables
+
+All environment variables use the `PLAYWRIGHT_MCP_` prefix:
+
+#### Core Settings
+
+| Variable | Purpose |
+|----------|---------|
+| `PLAYWRIGHT_CLI_SESSION` | Default session name |
+| `PLAYWRIGHT_MCP_BROWSER` | Browser type (chrome, firefox, webkit) |
+| `PLAYWRIGHT_MCP_HEADLESS` | Run in headless mode |
+| `PLAYWRIGHT_MCP_OUTPUT_DIR` | Path for output files |
+| `PLAYWRIGHT_MCP_CONFIG` | Configuration file path |
+| `PLAYWRIGHT_MCP_ALLOWED_HOSTS` | Control allowed hosts |
+| `PLAYWRIGHT_MCP_CDP_ENDPOINT` | Chrome DevTools Protocol endpoint |
+| `PLAYWRIGHT_MCP_SAVE_SESSION` | Session persistence setting |
+
+### 3. Configuration File
+
+**Default Location**: `.playwright/cli.config.json`
+
+**Schema** (JSON format):
+
+```json
+{
+  "browser": {
+    "browserName": "chromium",  // or "firefox", "webkit"
+    "isolated": true,            // in-memory profile
+    "userDataDir": "/path/to/profile",  // persistent profile
+    "launchOptions": {},         // Playwright launch options
+    "contextOptions": {},        // Playwright context options
+    "cdpEndpoint": "ws://...",   // CDP endpoint
+    "remoteEndpoint": "ws://...", // Remote browser endpoint
+    "initPage": "https://...",   // Initial page to open
+    "initScript": "code..."      // Script to run on init
+  },
+  "video": {
+    "saveVideo": true,
+    "width": 1280,
+    "height": 720
+  },
+  "output": {
+    "outputDir": "./output",     // Directory for output files
+    "outputMode": "file"         // "file" or "stdout"
+  },
+  "console": {
+    "level": "error"             // "error", "warning", "log", "info", "debug"
+  },
+  "network": {
+    "allowedOrigins": ["https://example.com"],
+    "blockedOrigins": ["https://ads.com"]
+  },
+  "timeouts": {
+    "action": 30000,             // Action timeout in ms
+    "navigation": 30000          // Navigation timeout in ms
+  },
+  "fileAccess": {
+    "allowUnrestrictedFileAccess": false
+  },
+  "codegen": {
+    "codegen": "typescript"      // "typescript" or "none"
+  }
+}
+```
+
+#### Configuration File Sections
+
+1. **Browser Settings**
+   - Browser engine selection
+   - Profile management (in-memory vs persistent)
+   - Launch and context options
+   - Remote browser connections
+
+2. **Video Recording**
+   - Enable/disable recording
+   - Resolution settings
+
+3. **Output Configuration**
+   - Directory for artifacts
+   - Output mode (file or stdout)
+
+4. **Console Filtering**
+   - Control console message levels
+
+5. **Network Control**
+   - Allowed/blocked origins
+   - Network request filtering
+
+6. **Timeouts**
+   - Action timeouts
+   - Navigation timeouts
+
+7. **File Access**
+   - Unrestricted file upload permissions
+
+8. **Code Generation**
+   - Language for generated code
+
+### Configuration Precedence
+
+When multiple configuration sources are present:
+1. Command-line flags (highest priority)
+2. Environment variables
+3. Configuration file
+4. Default values (lowest priority)
+
+**Source References:**
+- README.md
+- `skills/playwright-cli/SKILL.md`
+- Wiki: [Getting Started (microsoft/playwright-cli)](/wiki/microsoft/playwright-cli#2)
+- DeepWiki search: [Configuration](https://deepwiki.com/search/how-is-playwright-cli-configur_8980af74-0834-485d-b246-1a80632db433)
+
+---
+
+## 9. Usage as a Tool for AI Agents
+
+### Design Philosophy
+
+**Playwright CLI is explicitly designed for coding agents and AI assistants**, emphasizing token-efficient workflows.
+
+#### Why Token Efficiency Matters
+
+- Avoids loading large tool schemas into model context
+- Eliminates verbose accessibility trees
+- Reduces context usage for high-throughput agents
+- Faster decision-making for AI agents
+
+### Installing SKILLS for AI Agents
+
+AI agents can install SKILLS documentation locally:
+
+```bash
+playwright-cli install --skills
+```
+
+**What This Does:**
+- Generates skill documentation in `.claude/skills/`
+- Synchronizes to `skills/playwright-cli/`
+- Enables token-efficient AI agent integration
+
+### The Snapshot System
+
+**Core Concept**: After each command, Playwright CLI outputs the current browser state as a snapshot.
+
+#### Element References
+
+Snapshots contain **element references** (e.g., `e1`, `e2`, `e3`):
+
+```yaml
+# Example snapshot output (YAML format)
+url: https://example.com
+title: Example Domain
+elements:
+  - ref: e1
+    tag: button
+    text: "Click Me"
+    role: button
+  - ref: e2
+    tag: input
+    type: text
+    placeholder: "Enter email"
+  - ref: e3
+    tag: a
+    text: "Learn More"
+    href: "/about"
+```
+
+#### Using Element References
+
+AI agents use these references in subsequent commands:
+
+```bash
+# Click the button
+playwright-cli click e1
+
+# Fill the input field
+playwright-cli fill e2 "user@example.com"
+
+# Click the link
+playwright-cli click e3
+```
+
+#### Snapshot Storage
+
+- **Format**: YAML
+- **Default Location**: `.playwright-cli/` directory
+- **Naming**: Timestamped files
+- **Custom Names**: Use `--filename` flag
+
+**Example:**
+```bash
+playwright-cli snapshot --filename my-snapshot.yaml
+```
+
+### Session Management for AI Agents
+
+#### 1. Default Sessions (In-Memory)
+
+```bash
+playwright-cli open https://example.com
+playwright-cli fill e1 "username"
+playwright-cli fill e2 "password"
+playwright-cli click e3
+```
+
+State preserved between commands, lost on browser close.
+
+#### 2. Persistent Sessions
+
+```bash
+playwright-cli open --persistent https://example.com
+# Login and authenticate
+playwright-cli fill e1 "user@example.com"
+playwright-cli fill e2 "password"
+playwright-cli click e3
+# State saved to disk
+```
+
+On next run:
+```bash
+playwright-cli open --persistent
+# Already logged in!
+```
+
+#### 3. Named Sessions (Isolation)
+
+```bash
+# Session 1: User A
+playwright-cli -s=userA open https://app.com
+playwright-cli -s=userA fill e1 "userA@example.com"
+
+# Session 2: User B (different browser instance)
+playwright-cli -s=userB open https://app.com
+playwright-cli -s=userB fill e1 "userB@example.com"
+```
+
+Or using environment variable:
+```bash
+export PLAYWRIGHT_CLI_SESSION=userA
+playwright-cli open https://app.com
+```
+
+### AI Agent Workflow Patterns
+
+#### Pattern 1: Simple Navigation and Interaction
+
+```bash
+# 1. Open browser and navigate
+playwright-cli open https://example.com
+
+# 2. Take snapshot to get element references
+playwright-cli snapshot
+
+# 3. Agent analyzes snapshot, identifies elements
+
+# 4. Interact with elements
+playwright-cli click e5
+playwright-cli fill e8 "search query"
+playwright-cli press Enter
+
+# 5. Take screenshot for verification
+playwright-cli screenshot
+```
+
+#### Pattern 2: Data Extraction with run-code
+
+```bash
+# Navigate to page
+playwright-cli goto https://products.example.com
+
+# Extract data with custom code
+playwright-cli run-code "async page => {
+  const products = await page.evaluate(() => {
+    return Array.from(document.querySelectorAll('.product')).map(p => ({
+      name: p.querySelector('.name').textContent,
+      price: p.querySelector('.price').textContent,
+      image: p.querySelector('img').src
+    }));
+  });
+  return products;
+}"
+```
+
+#### Pattern 3: Multi-Step Authentication
+
+```bash
+# Open login page
+playwright-cli open --persistent https://app.com/login
+
+# Fill credentials
+playwright-cli snapshot
+playwright-cli fill e1 "user@example.com"
+playwright-cli fill e2 "password"
+playwright-cli click e3
+
+# Save authenticated state
+playwright-cli run-code "async page => {
+  await page.context().storageState({ path: 'auth.json' });
+}"
+
+# Later: Load authenticated state
+playwright-cli run-code "async page => {
+  await page.context().addCookies(
+    JSON.parse(require('fs').readFileSync('auth.json')).cookies
+  );
+}"
+```
+
+#### Pattern 4: Form Automation
+
+```bash
+playwright-cli open https://forms.example.com
+playwright-cli snapshot
+
+# Fill multi-field form
+playwright-cli fill e1 "John"
+playwright-cli fill e2 "Doe"
+playwright-cli fill e3 "john@example.com"
+playwright-cli select e4 "United States"
+playwright-cli check e5
+playwright-cli click e6
+```
+
+### Advanced Agent Capabilities
+
+#### 1. Geolocation and Permissions
+
+```bash
+playwright-cli run-code "async page => {
+  await page.context().grantPermissions(['geolocation']);
+  await page.context().setGeolocation({ 
+    latitude: 37.7749, 
+    longitude: -122.4194 
+  });
+}"
+```
+
+#### 2. Media Emulation
+
+```bash
+playwright-cli run-code "async page => {
+  await page.emulateMedia({ colorScheme: 'dark' });
+}"
+```
+
+#### 3. File Downloads
+
+```bash
+playwright-cli run-code "async page => {
+  const [download] = await Promise.all([
+    page.waitForEvent('download'),
+    page.click('a.download-link')
+  ]);
+  await download.saveAs('./downloaded-file.pdf');
+  return download.suggestedFilename();
+}"
+```
+
+#### 4. Clipboard Operations
+
+```bash
+playwright-cli run-code "async page => {
+  await page.context().grantPermissions(['clipboard-read']);
+  return await page.evaluate(() => navigator.clipboard.readText());
+}"
+```
+
+#### 5. Error Handling
+
+```bash
+playwright-cli run-code "async page => {
+  try {
+    await page.click('.maybe-missing', { timeout: 1000 });
+    return 'clicked';
+  } catch (e) {
+    return 'element not found';
+  }
+}"
+```
+
+### Best Practices for AI Agents Using Playwright CLI
+
+From Playwright MCP documentation (applicable to CLI):
+
+1. **Avoid Improvising**: Follow directives strictly
+2. **Use Clear Assertions**: Validate expected behavior
+3. **Leverage Reliable Locators**: Use element references from snapshots
+4. **Use Local Variables**: For repeated locators
+5. **Leverage Auto-Waiting**: Playwright includes built-in waiting
+6. **Avoid Explicit Waits**: Don't use `waitForLoadState()`, `waitForNavigation()`, or `waitForTimeout()`
+7. **Avoid `page.evaluate()`**: Use higher-level Playwright APIs when possible
+8. **Prefer Locator API**: Provides lazy evaluation and auto-waiting
+
+### Token Efficiency Tips
+
+1. **Use Snapshots Wisely**: Only take snapshots when needed
+2. **Element References**: Reuse references instead of re-snapshotting
+3. **Batch Operations**: Chain commands when possible
+4. **Session Management**: Use persistent sessions to avoid re-authentication
+5. **Custom Code**: Use `run-code` for complex operations to reduce command count
+
+### Monitoring Agent Progress
+
+Visual dashboard for observing agent activity:
+
+```bash
+playwright-cli show
+```
+
+This provides a monitoring interface for active browser sessions.
+
+**Source References:**
+- README.md
+- `skills/playwright-cli/SKILL.md`
+- Wiki: [Getting Started (microsoft/playwright-cli)](/wiki/microsoft/playwright-cli#2)
+- Wiki: [Overview (microsoft/playwright-cli)](/wiki/microsoft/playwright-cli#1)
+- DeepWiki searches:
+  - [AI agent usage](https://deepwiki.com/search/is-there-documentation-about-u_1507c42a-4898-4d43-9143-c96d5aa27b24)
+  - [Snapshot system](https://deepwiki.com/search/what-is-the-snapshot-system-in_d97ea657-6eb0-42d5-909d-2ac8dda6de38)
+  - [run-code command](https://deepwiki.com/search/what-is-the-runcode-command-in_7af9b5d5-54c2-4561-b726-779c8d4ad75b)
+
+---
+
+## 10. Package Clarifications
+
+### Understanding the Package Ecosystem
+
+There are **two separate packages** with similar names:
+
+#### 1. `@playwright/cli` (Active)
+
+**Status**: ✅ **Actively Maintained**
+
+- **npm Package**: `@playwright/cli`
+- **Purpose**: CLI for coding agents
+- **Location**: Within Playwright monorepo at `packages/playwright/src/mcp/terminal/`
+- **Repository**: This is what `microsoft/playwright-cli` repository documents
+- **Installation**: `npm install -g @playwright/cli@latest`
+- **Execution**: `playwright-cli <command>`
+
+#### 2. `playwright-cli` (Deprecated)
+
+**Status**: ⚠️ **Deprecated - Redirection Only**
+
+- **npm Package**: `playwright-cli` (without `@playwright/` scope)
+- **Purpose**: Redirects to main Playwright CLI
+- **Behavior**: Outputs error message and exits
+- **Message**: "playwright-cli has moved to playwright. Use npx playwright instead."
+- **Installation**: ❌ Not recommended
+- **Execution**: Redirects to `npx playwright`
+
+### The Confusion
+
+The `microsoft/playwright-cli` repository:
+- Documents the **active** `@playwright/cli` package
+- Also contains the **deprecated** `playwright-cli` redirection package
+- Both exist in the same repository but serve different purposes
+
+### Relationship to Main Playwright
+
+```
+microsoft/playwright (Main Repository)
+├── packages/playwright/
+│   ├── src/mcp/terminal/  ← Source of @playwright/cli
+│   └── lib/cli/           ← Main Playwright CLI (npx playwright)
+└── ...
+
+microsoft/playwright-cli (Distribution Repository)
+├── @playwright/cli        ← Active CLI for agents (documented here)
+└── playwright-cli         ← Deprecated redirection package
+```
+
+### Which Should You Use?
+
+**For AI Agents and Coding Automation:**
+```bash
+npm install -g @playwright/cli@latest
+playwright-cli --help
+```
+
+**For General Playwright Use:**
+```bash
+npm install -g playwright
+npx playwright --help
+```
+
+**Key Differences:**
+
+| Feature | `@playwright/cli` | `npx playwright` |
+|---------|------------------|------------------|
+| **Purpose** | Token-efficient agent automation | Full Playwright functionality |
+| **Target Audience** | AI agents, coding agents | Developers, testers |
+| **Output Format** | Snapshots with element refs | Standard CLI output |
+| **SKILLS Support** | Yes (`--skills` flag) | No |
+| **Test Runner** | No | Yes |
+| **Code Generation** | Via `run-code` | Built-in codegen |
+| **Inspector** | Via `show` command | Full inspector UI |
+
+**Source References:**
+- Wiki: [Overview (microsoft/playwright-cli)](/wiki/microsoft/playwright-cli#1)
+- `playwright-cli.js` in repository
+- `package.json`
+- DeepWiki search: [@playwright/cli package](https://deepwiki.com/search/what-is-playwrightcli-package_2a170c2e-4ae5-48e4-936e-d79926678fd1)
+
+---
+
+## 11. Complete Command Reference
+
+### Session Management
+
+```bash
+# List all active sessions
+playwright-cli list
+
+# Open browser with default session
+playwright-cli open [url]
+
+# Named session
+playwright-cli -s=mysession open [url]
+
+# Persistent session (saves to disk)
+playwright-cli open --persistent [url]
+
+# Custom profile directory
+playwright-cli open --persistent --profile=/path/to/profile [url]
+
+# Close all sessions
+playwright-cli close-all
+
+# Kill all sessions forcefully
+playwright-cli kill-all
+```
+
+### Navigation
+
+```bash
+# Navigate to URL
+playwright-cli goto <url>
+
+# Go back
+playwright-cli go-back
+
+# Go forward
+playwright-cli go-forward
+
+# Reload page
+playwright-cli reload
+
+# Close current page
+playwright-cli close
+```
+
+### Element Interaction
+
+```bash
+# Take snapshot to get element references
+playwright-cli snapshot
+playwright-cli snapshot --filename custom.yaml
+
+# Click element
+playwright-cli click <ref>
+playwright-cli click <ref> right  # right-click
+playwright-cli click <ref> middle  # middle-click
+
+# Double-click
+playwright-cli dblclick <ref>
+
+# Fill input field
+playwright-cli fill <ref> "text"
+
+# Type text (into focused element)
+playwright-cli type "text"
+
+# Hover over element
+playwright-cli hover <ref>
+
+# Drag and drop
+playwright-cli drag <startRef> <endRef>
+
+# Select dropdown option
+playwright-cli select <ref> "value"
+
+# Check/uncheck
+playwright-cli check <ref>
+playwright-cli uncheck <ref>
+
+# Upload file
+playwright-cli upload <file>
+```
+
+### Keyboard and Mouse
+
+```bash
+# Keyboard
+playwright-cli press <key>
+playwright-cli keydown <key>
+playwright-cli keyup <key>
+
+# Mouse
+playwright-cli mousemove <x> <y>
+playwright-cli mousedown [button]
+playwright-cli mouseup [button]
+playwright-cli mousewheel <dx> <dy>
+```
+
+### JavaScript Evaluation
+
+```bash
+# Evaluate JavaScript on page
+playwright-cli eval "() => document.title"
+
+# Evaluate on specific element
+playwright-cli eval "el => el.textContent" <ref>
+
+# Execute custom Playwright code
+playwright-cli run-code "async page => {
+  return await page.title();
+}"
+```
+
+### Dialogs
+
+```bash
+# Accept dialog
+playwright-cli dialog-accept
+
+# Accept with prompt text
+playwright-cli dialog-accept "response text"
+
+# Dismiss dialog
+playwright-cli dialog-dismiss
+```
+
+### Window Management
+
+```bash
+# Resize window
+playwright-cli resize <width> <height>
+```
+
+### Tab Management
+
+```bash
+# List tabs
+playwright-cli tab-list
+
+# Create new tab
+playwright-cli tab-new [url]
+
+# Close tab by index
+playwright-cli tab-close <index>
+
+# Select tab by index
+playwright-cli tab-select <index>
+```
+
+### Storage Management
+
+```bash
+# Storage state
+playwright-cli state-save [filename]
+playwright-cli state-load <filename>
+
+# Cookies
+playwright-cli cookie-list
+playwright-cli cookie-list --domain=example.com
+playwright-cli cookie-get <name>
+playwright-cli cookie-set <name> <value>
+playwright-cli cookie-delete <name>
+
+# LocalStorage
+playwright-cli localstorage-list
+playwright-cli localstorage-get <key>
+playwright-cli localstorage-set <key> <value>
+playwright-cli localstorage-delete <key>
+
+# SessionStorage
+playwright-cli sessionstorage-list
+playwright-cli sessionstorage-get <key>
+playwright-cli sessionstorage-set <key> <value>
+playwright-cli sessionstorage-delete <key>
+```
+
+### Network
+
+```bash
+# Mock network request
+playwright-cli route <url-pattern> <action>
+
+# Console messages
+playwright-cli console
+```
+
+### Artifacts
+
+```bash
+# Screenshot
+playwright-cli screenshot
+playwright-cli screenshot <ref>  # specific element
+
+# PDF
+playwright-cli pdf
+```
+
+### Monitoring
+
+```bash
+# Show visual dashboard
+playwright-cli show
+```
+
+### Configuration
+
+```bash
+# Use configuration file
+playwright-cli --config path/to/config.json <command>
+
+# Browser selection
+playwright-cli open --browser=chrome
+playwright-cli open --browser=firefox
+playwright-cli open --browser=webkit
+playwright-cli open --browser=msedge
+
+# Headed mode
+playwright-cli open --headed
+```
+
+### SKILLS Installation
+
+```bash
+# Install SKILLS documentation for AI agents
+playwright-cli install --skills
+```
+
+---
+
+## 12. Key Takeaways for Implementation
+
+### For AI Agent Integration
+
+1. **Token Efficiency**: Playwright CLI is specifically designed to minimize token usage for AI agents
+2. **Snapshot-Based**: Use the snapshot system for element discovery and interaction
+3. **Session Isolation**: Use named sessions for concurrent operations or user isolation
+4. **Custom Code**: Leverage `run-code` for complex operations not covered by built-in commands
+5. **Auto-Waiting**: Playwright includes built-in waiting - avoid explicit waits
+
+### For Web Scraping Projects
+
+1. **Dynamic Content**: Perfect for JavaScript-rendered sites
+2. **Authentication**: Persistent sessions maintain login states
+3. **Multi-Page**: Tab management for parallel scraping
+4. **Data Extraction**: Use `run-code` with `page.evaluate()` for complex extraction
+5. **Network Control**: Mock or block requests for efficiency
+
+### For Browser Automation
+
+1. **Cross-Browser**: Support for Chromium, Firefox, WebKit, MS Edge
+2. **Headless Default**: Runs without UI by default, use `--headed` for debugging
+3. **State Management**: Save/load storage states for workflow continuation
+4. **Artifacts**: Screenshots and PDFs for documentation
+
+### Limitations
+
+1. **No Standalone Binary**: Requires Node.js runtime
+2. **Large Installation**: Browser binaries add significant size
+3. **Not MCP Protocol**: Alternative to MCP, not an implementation
+4. **CLI Only**: No programmatic API (use main Playwright library for that)
+
+### When to Use Playwright CLI vs Main Playwright
+
+**Use `@playwright/cli` when:**
+- Building AI agents that need browser automation
+- Token efficiency is critical
+- Need snapshot-based element references
+- Want CLI-based workflow
+
+**Use main Playwright library when:**
+- Writing tests with Playwright Test
+- Need programmatic API
+- Building complex applications
+- Want full test runner features
+
+---
+
+## 13. Additional Resources
+
+### Documentation Links
+
+- **DeepWiki Search Results**:
+  - [What is Playwright CLI](https://deepwiki.com/search/what-is-playwright-cli-what-is_7e400251-eff1-4a62-b375-c1b75f14155f)
+  - [Installation Methods](https://deepwiki.com/search/how-do-you-install-playwright_93627ae0-c074-4105-8518-239fa410e4fd)
+  - [CLI Commands](https://deepwiki.com/search/what-cli-commands-and-api-does_217802ef-1b35-4a8f-9a67-b5fe32955eb7)
+  - [Web Scraping](https://deepwiki.com/search/can-playwright-cli-be-used-for_c2ea5019-8c44-41d2-bd7b-93e7998300e5)
+  - [MCP Integration](https://deepwiki.com/search/does-playwright-cli-support-mc_bf2568c3-0422-4568-bbae-6e274786b302)
+  - [Binary Distribution](https://deepwiki.com/search/can-playwright-cli-be-distribu_b6e90084-e97d-432b-b71d-6259e5b16d51)
+  - [Dependencies](https://deepwiki.com/search/what-are-the-runtime-dependenc_7063bd6b-fbb0-403e-9a70-f4210d1df406)
+  - [Configuration](https://deepwiki.com/search/how-is-playwright-cli-configur_8980af74-0834-485d-b246-1a80632db433)
+  - [AI Agent Usage](https://deepwiki.com/search/is-there-documentation-about-u_1507c42a-4898-4d43-9143-c96d5aa27b24)
+  - [Package Clarification](https://deepwiki.com/search/what-is-playwrightcli-package_2a170c2e-4ae5-48e4-936e-d79926678fd1)
+  - [Snapshot System](https://deepwiki.com/search/what-is-the-snapshot-system-in_d97ea657-6eb0-42d5-909d-2ac8dda6de38)
+  - [Run-code Command](https://deepwiki.com/search/what-is-the-runcode-command-in_7af9b5d5-54c2-4561-b726-779c8d4ad75b)
+  - [MCP Best Practices](https://deepwiki.com/search/what-are-the-best-practices-fo_50c91c3c-4f41-4d2b-b8ea-7407d9455c5b)
+
+- **Repository Links**:
+  - [microsoft/playwright-cli](https://github.com/microsoft/playwright-cli) - Distribution repository
+  - [microsoft/playwright](https://github.com/microsoft/playwright) - Main Playwright repository
+  - [microsoft/playwright-mcp](https://github.com/microsoft/playwright-mcp) - Playwright MCP Server
+  - [Source Code Location](https://github.com/microsoft/playwright/tree/main/packages/playwright/src/mcp/terminal) - CLI sources in monorepo
+
+- **Wiki Pages**:
+  - [Overview (microsoft/playwright-cli)](/wiki/microsoft/playwright-cli#1)
+  - [Getting Started (microsoft/playwright-cli)](/wiki/microsoft/playwright-cli#2)
+  - [Development (microsoft/playwright-cli)](/wiki/microsoft/playwright-cli#7)
+  - [Skills Maintenance (microsoft/playwright-cli)](/wiki/microsoft/playwright-cli#7.2)
+  - [Playwright Overview (microsoft/playwright)](/wiki/microsoft/playwright#1)
+  - [Locator and Element Interactions (microsoft/playwright)](/wiki/microsoft/playwright#3.3)
+
+### Key Files Referenced
+
+- `README.md` - Main documentation
+- `skills/playwright-cli/SKILL.md` - SKILLS documentation for agents
+- `package.json` - Package configuration
+- `playwright-cli.js` - CLI entry point
+- `index.js` - Deprecated package redirection
+- `.playwright/cli.config.json` - Configuration file schema
+
+---
+
+## 14. Conclusion
+
+Playwright CLI (`@playwright/cli`) is a powerful, token-efficient tool specifically designed for AI agents and coding automation. Its snapshot-based approach to element interaction, combined with comprehensive browser automation capabilities, makes it ideal for:
+
+- **AI-Driven Browser Automation**: Token-efficient command-based workflows
+- **Web Scraping**: Dynamic content handling with persistent sessions
+- **Form Automation**: Multi-step form filling and submission
+- **Data Extraction**: Custom JavaScript execution for complex extraction
+- **Testing Automation**: Browser interaction for test scenarios
+
+The CLI's design philosophy prioritizes efficiency for AI agents while maintaining the full power of Playwright's browser automation capabilities. Its clear separation from Playwright MCP provides options for different use cases: CLI for high-throughput agents, MCP for stateful exploratory workflows.
+
+For AI agents building browser automation capabilities, Playwright CLI offers a well-documented, actively maintained, and purpose-built solution with comprehensive command coverage and flexible configuration options.
+
+---
+
+**Research Date**: February 25, 2026  
+**Research Method**: DeepWiki AI-powered repository analysis  
+**Primary Repository**: microsoft/playwright-cli  
+**Related Repositories**: microsoft/playwright, anthropics/anthropic-cookbook  
+**Document Version**: 1.0
diff --git a/research/docs/2026-02-25-playwright-cli-integration-research.md b/research/docs/2026-02-25-playwright-cli-integration-research.md
new file mode 100644
index 0000000000..a3f2b3dbdc
--- /dev/null
+++ b/research/docs/2026-02-25-playwright-cli-integration-research.md
@@ -0,0 +1,353 @@
+---
+date: 2026-02-25 06:30:00 UTC
+researcher: Copilot CLI
+git_commit: 75fce77392e544b51014d7632a2d0d7286725ac3
+branch: lavaman131/feature/playwright-cli
+repository: atomic
+topic: "Playwright CLI Integration — Bundling, Installation, and Prompt Migration"
+tags: [research, playwright-cli, installation, skills, web-fetch, web-search, bundling, postinstall]
+status: complete
+last_updated: 2026-02-25
+last_updated_by: Copilot CLI
+---
+
+# Playwright CLI Integration Research
+
+## Research Question
+
+How to integrate Playwright CLI as a bundled skill in Atomic CLI, covering:
+1. Install/postinstall script modifications to deploy Playwright CLI as a global skill to `~/.atomic/<agent_name>/skills/`
+2. Prompt/agent config updates to replace web_fetch/WebSearch/WebFetch with Playwright CLI skill references
+3. Bundling strategy for distributing Playwright CLI with Atomic
+4. Playwright CLI capabilities as a web search/fetch replacement
+
+---
+
+## Summary
+
+Playwright CLI (`@playwright/cli`) is a **token-efficient browser automation CLI designed specifically for coding agents**. It provides a superset of current WebFetch/WebSearch capabilities (full browser automation, JS rendering, session persistence, data extraction). Integration requires: (1) adding `@playwright/cli` as a dependency and installing it during postinstall to `~/.atomic/<agent>/skills/playwright-cli/`, (2) updating 15 files across 3 agent platforms that reference web search/fetch tools, and (3) creating a SKILL.md definition for the new playwright-cli skill that matches the existing skill pattern.
+
+---
+
+## Detailed Findings
+
+### 1. Current Web Search/Fetch Tool Landscape
+
+**15 files** currently reference web search/fetch tools across the codebase:
+
+#### Agent Configs (7 files)
+
+| File | Tool Names | Purpose |
+|------|-----------|---------|
+| `.claude/agents/codebase-online-researcher.md` (L4) | `WebFetch, WebSearch` | Primary web research agent |
+| `.claude/agents/debugger.md` (L4) | `WebFetch, WebSearch` | Fallback for debugging context |
+| `.claude/agents/reviewer.md` (L4) | `WebFetch, WebSearch` | Code review context |
+| `.github/agents/codebase-online-researcher.md` (L4) | `"web"` | Primary web research (GitHub variant) |
+| `.github/agents/debugger.md` (L4-13) | `"web"` | Debugging fallback (GitHub variant) |
+| `.opencode/agents/codebase-online-researcher.md` (L8) | `webfetch: true` | Primary web research (OpenCode variant) |
+| `.opencode/agents/debugger.md` (L8) | `webfetch: true` | Debugging fallback (OpenCode variant) |
+
+#### Skill Configs (6 files)
+
+| File | Reference Type | Context |
+|------|---------------|---------|
+| `.claude/skills/research-codebase/SKILL.md` (L53-56) | Instruction text | Tells agents to use WebFetch/WebSearch and include links |
+| `.claude/skills/explain-code/SKILL.md` (L12) | Available tool | Fallback after DeepWiki |
+| `.github/skills/research-codebase/SKILL.md` (L53-56) | Instruction text | Same as Claude variant |
+| `.github/skills/explain-code/SKILL.md` (L12) | Available tool | Same as Claude variant |
+| `.opencode/skills/research-codebase/SKILL.md` (L53-56) | Instruction text | Same, uses webfetch terminology |
+| `.opencode/skills/explain-code/SKILL.md` (L12) | Available tool | Same as Claude variant |
+
+#### Source Code (1 file)
+
+| File | Reference | Context |
+|------|-----------|---------|
+| `src/sdk/clients/claude.ts` (L284-285) | `"WebFetch", "WebSearch"` | `BUILTIN_ALLOWED_TOOLS` array in `ClaudeAgentClient` |
+
+#### Configuration (1 file)
+
+| File | Reference | Context |
+|------|-----------|---------|
+| `.opencode/opencode.json` (L17) | `"webfetch": "allow"` | Global permission for OpenCode agents |
+
+#### Platform-Specific Tool Naming
+
+- **Claude**: `WebFetch, WebSearch` (two separate capitalized tools)
+- **GitHub/Copilot**: `"web"` (single abstracted tool name in JSON array)
+- **OpenCode**: `webfetch` (single lowercase tool, boolean flag + permission)
+
+---
+
+### 2. Installation Infrastructure Analysis
+
+#### Install Scripts
+
+**`install.sh`** (Unix/macOS):
+- Downloads binary + `atomic-config.tar.gz` from GitHub releases
+- Extracts config to `~/.local/share/atomic/`
+- Calls `sync_global_agent_configs()` (L144-165) which:
+  - Copies `.claude/`, `.opencode/`, `.github/` to `~/.atomic/.claude/`, `~/.atomic/.opencode/`, `~/.atomic/.copilot/`
+  - Copies `.mcp.json` to `~/.atomic/.mcp.json`
+  - Removes SCM skills (`gh-*`, `sl-*`) from global config
+  - Removes `workflows/` and `dependabot.yml` from Copilot config
+
+**`install.ps1`** (Windows):
+- Downloads binary + `atomic-config.zip` from GitHub releases
+- Mirrors bash installer with `Sync-GlobalAgentConfigs` (L20-51)
+- Same exclusion patterns for SCM skills
+
+**Extension point for Playwright CLI**: After config extraction and before sync (install.sh L226, install.ps1 L172), add Playwright CLI installation step.
+
+#### Postinstall Script
+
+**`src/scripts/postinstall.ts`**:
+```typescript
+import { hasAtomicGlobalAgentConfigs, syncAtomicGlobalAgentConfigs } from "../utils/atomic-global-config";
+import { getConfigRoot } from "../utils/config-path";
+
+async function main() {
+  await syncAtomicGlobalAgentConfigs(getConfigRoot());
+  await verifyAtomicGlobalConfigSync();
+}
+```
+
+**`src/utils/atomic-global-config.ts`** key functions:
+- `syncAtomicGlobalAgentConfigs(sourceRoot)` — Main sync function (L128-151)
+- Builds exclusion list merging agent excludes + SCM skill excludes (L141-145)
+- `pruneManagedScmSkills()` — Removes stale SCM skills (L78-88)
+- Double protection: excludes during copy AND prunes after
+
+**`src/utils/config-path.ts`**:
+- `getConfigRoot()` — Detects installation type via `import.meta.dir`:
+  - `$bunfs` → compiled binary → `~/.local/share/atomic`
+  - `node_modules` → npm/bun install → package root
+  - Otherwise → source dev mode → repo root
+
+---
+
+### 3. Skills Directory Structure
+
+All three platforms use identical skill structure:
+
+```
+.<agent>/skills/<skill-name>/
+├── SKILL.md          # Main skill definition (YAML frontmatter + markdown)
+└── [reference files]  # Optional supporting files
+```
+
+**11 skills** currently exist (identical across all 3 platforms):
+- `create-spec`, `explain-code`, `frontend-design`, `gh-commit`, `gh-create-pr`, `init`, `prompt-engineer`, `research-codebase`, `sl-commit`, `sl-submit-diff`, `testing-anti-patterns`
+
+**Package.json `files` field** (L22-31) includes:
+- `.github/skills` — Bundled with npm package
+- `.github/agents` — Bundled with npm package
+
+**SCM skills** (`gh-*`, `sl-*`) are excluded from global sync and deployed per-project via `atomic init`.
+
+---
+
+### 4. Playwright CLI Capabilities
+
+#### Overview
+- **Package**: `@playwright/cli` (npm)
+- **Source**: Located in Playwright monorepo at `packages/playwright/src/mcp/terminal/`
+- **Purpose**: Token-efficient browser automation for coding agents
+- **Runtime**: Requires Node.js (no standalone binary)
+- **Dependencies**: `playwright` + `minimist`
+
+#### Key Capabilities as WebFetch/WebSearch Replacement
+
+| Capability | WebFetch/WebSearch | Playwright CLI |
+|-----------|-------------------|----------------|
+| Fetch web pages | ✅ Basic HTTP | ✅ Full browser (JS rendering) |
+| Search the web | ✅ Built-in | ✅ Via browser automation |
+| Handle dynamic content | ❌ | ✅ Full JS execution |
+| Session persistence | ❌ | ✅ Persistent sessions |
+| Authentication | ❌ | ✅ Cookie/storage management |
+| Screenshots | ❌ | ✅ Built-in |
+| PDF export | ❌ | ✅ Built-in |
+| Multi-page navigation | Limited | ✅ Tab management |
+| Element interaction | ❌ | ✅ Click, fill, type, etc. |
+| Data extraction | Basic text | ✅ run-code, eval, snapshots |
+
+#### Installation Methods
+
+```bash
+# Global install
+npm install -g @playwright/cli@latest
+
+# Local install
+npm install @playwright/cli
+npx playwright-cli --help
+
+# Install browsers (required)
+npx playwright install chromium
+```
+
+#### AI Agent Skill Installation
+
+```bash
+# Install skill documentation for agents
+playwright-cli install --skills
+```
+
+This generates a `skills/playwright-cli/SKILL.md` within `.claude/skills/` directory.
+
+#### MCP Integration Note
+
+Playwright CLI is an **alternative to MCP**, not an MCP implementation. A separate `microsoft/playwright-mcp` project exists for full MCP integration. The CLI is optimized for token-efficient, high-throughput coding agents.
+
+---
+
+### 5. Global Config Sync Mechanism
+
+**Two-tier config architecture**:
+1. **Global configs** (`~/.atomic/`) — Baseline agents/skills shared across all projects
+2. **Project configs** (`.claude/`, `.opencode/`, `.github/`) — Project-specific customizations
+
+**Sync flow**:
+```
+Config Root (source) → sync → ~/.atomic/.claude/
+                             → ~/.atomic/.opencode/
+                             → ~/.atomic/.copilot/
+                             → ~/.atomic/.mcp.json
+```
+
+**Exclusion rules during sync**:
+- SCM skills (`gh-*`, `sl-*`) → Always excluded from global
+- `workflows/` → Removed from Copilot global
+- `dependabot.yml` → Removed from Copilot global
+
+**Installation type detection** (`config-path.ts`):
+- Binary: `import.meta.dir` contains `$bunfs` → uses `~/.local/share/atomic`
+- npm/bun: `import.meta.dir` contains `node_modules` → uses package root
+- Source: otherwise → uses repo root
+
+---
+
+## Code References
+
+- `install.sh:144-165` — `sync_global_agent_configs()` bash function
+- `install.ps1:20-51` — `Sync-GlobalAgentConfigs` PowerShell function
+- `src/scripts/postinstall.ts:1-25` — Postinstall entry point
+- `src/utils/atomic-global-config.ts:128-151` — Core `syncAtomicGlobalAgentConfigs()` function
+- `src/utils/atomic-global-config.ts:78-88` — `pruneManagedScmSkills()` function
+- `src/utils/config-path.ts` — `getConfigRoot()` installation type detection
+- `src/sdk/clients/claude.ts:270-288` — `BUILTIN_ALLOWED_TOOLS` with WebFetch/WebSearch
+- `.opencode/opencode.json:17` — `webfetch: "allow"` permission
+- `package.json:40` — `postinstall` script definition
+- `package.json:22-31` — `files` field (bundled config directories)
+
+---
+
+## Architecture Documentation
+
+### Proposed Integration Architecture
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                    Installation Flow                         │
+├──────────────────────────────────────────────────────────────┤
+│                                                              │
+│  ┌────────────────┐                                          │
+│  │ bun install /  │                                          │
+│  │ install.sh /   │                                          │
+│  │ install.ps1    │                                          │
+│  └───────┬────────┘                                          │
+│          │                                                    │
+│          ▼                                                    │
+│  ┌────────────────┐    ┌─────────────────────────────────┐   │
+│  │ postinstall.ts │───▶│ 1. syncAtomicGlobalAgentConfigs │   │
+│  │                │    │ 2. Install @playwright/cli      │   │
+│  │                │    │ 3. Install Playwright browsers   │   │
+│  │                │    │ 4. Copy SKILL.md to all agents   │   │
+│  └────────────────┘    └─────────────────────────────────┘   │
+│                                     │                         │
+│                                     ▼                         │
+│  ┌──────────────────────────────────────────────────────┐    │
+│  │              ~/.atomic/ (Global Store)                │    │
+│  ├──────────────────────────────────────────────────────┤    │
+│  │ .claude/skills/playwright-cli/SKILL.md               │    │
+│  │ .opencode/skills/playwright-cli/SKILL.md             │    │
+│  │ .copilot/skills/playwright-cli/SKILL.md              │    │
+│  └──────────────────────────────────────────────────────┘    │
+└──────────────────────────────────────────────────────────────┘
+```
+
+### Files Requiring Modification
+
+#### High Priority (Agent Configs — Tool Lists)
+
+1. `.claude/agents/codebase-online-researcher.md` — Replace `WebFetch, WebSearch` with playwright-cli skill reference
+2. `.claude/agents/debugger.md` — Replace `WebFetch, WebSearch` with playwright-cli skill reference
+3. `.claude/agents/reviewer.md` — Replace `WebFetch, WebSearch` with playwright-cli skill reference
+4. `.github/agents/codebase-online-researcher.md` — Replace `"web"` with playwright-cli reference
+5. `.github/agents/debugger.md` — Replace `"web"` with playwright-cli reference
+6. `.opencode/agents/codebase-online-researcher.md` — Replace `webfetch: true` with playwright-cli reference
+7. `.opencode/agents/debugger.md` — Replace `webfetch: true` with playwright-cli reference
+
+#### Medium Priority (Skill Configs — Instruction Text)
+
+8. `.claude/skills/research-codebase/SKILL.md` — Update WebFetch/WebSearch references to playwright-cli
+9. `.claude/skills/explain-code/SKILL.md` — Update WebFetch/WebSearch references to playwright-cli
+10. `.github/skills/research-codebase/SKILL.md` — Update WebFetch/WebSearch references
+11. `.github/skills/explain-code/SKILL.md` — Update WebFetch/WebSearch references
+12. `.opencode/skills/research-codebase/SKILL.md` — Update webfetch references
+13. `.opencode/skills/explain-code/SKILL.md` — Update webfetch references
+
+#### Source Code Changes
+
+14. `src/sdk/clients/claude.ts` — Remove `"WebFetch"` and `"WebSearch"` from `BUILTIN_ALLOWED_TOOLS`
+15. `.opencode/opencode.json` — Remove `"webfetch": "allow"` permission
+
+#### Installation/Bundling Changes
+
+16. `package.json` — Add `@playwright/cli` to dependencies; update postinstall script
+17. `src/scripts/postinstall.ts` — Add Playwright CLI installation + browser install + SKILL.md deployment
+18. `install.sh` — Add Playwright CLI installation step after config sync
+19. `install.ps1` — Add Playwright CLI installation step after config sync
+
+#### New Files
+
+20. `.claude/skills/playwright-cli/SKILL.md` — New skill definition
+21. `.opencode/skills/playwright-cli/SKILL.md` — New skill definition
+22. `.github/skills/playwright-cli/SKILL.md` — New skill definition
+
+---
+
+## Historical Context (from research/)
+
+No prior research documents exist for Playwright CLI integration. This is a new initiative.
+
+Related research documents:
+- `research/docs/2026-02-17-legacy-code-removal-skills-migration.md` — Previous skills migration patterns
+- `research/docs/2026-02-08-skill-loading-from-configs-and-ui.md` — How skills are loaded from configs
+- `research/docs/2026-02-14-frontend-design-builtin-skill-integration.md` — Previous skill integration work
+- `research/docs/2026-01-21-binary-distribution-installers.md` — Original installer design
+
+---
+
+## Related Research
+
+Sub-agent research documents generated during this investigation:
+- [`research/docs/2026-02-25-web-search-fetch-references.md`](./2026-02-25-web-search-fetch-references.md) — Complete catalog of all 15 files referencing web search/fetch
+- [`research/docs/2026-02-25-skills-directory-structure.md`](./2026-02-25-skills-directory-structure.md) — Skills directory analysis across all platforms
+- [`research/docs/2026-02-25-install-postinstall-analysis.md`](./2026-02-25-install-postinstall-analysis.md) — Installation infrastructure analysis
+- [`research/docs/2026-02-25-global-config-sync-mechanism.md`](./2026-02-25-global-config-sync-mechanism.md) — Global config sync mechanism deep dive
+- [`research/docs/2026-02-25-playwright-cli-capabilities.md`](./2026-02-25-playwright-cli-capabilities.md) — Playwright CLI capabilities and DeepWiki research
+
+---
+
+## Open Questions
+
+1. **Browser installation size**: Chromium alone is ~200-400MB. Should the postinstall download browsers automatically, or defer to first-use? A deferred approach would keep installation fast.
+
+2. **Node.js dependency**: Playwright CLI requires Node.js runtime. Since Atomic uses Bun, confirm that `bun install @playwright/cli` works and `bunx playwright-cli` is a viable execution path, or if `npx` is needed.
+
+3. **SKILL.md content**: Should we use the SKILL.md generated by `playwright-cli install --skills`, or craft a custom one that specifically focuses on web fetching/searching use cases (as a replacement for WebFetch/WebSearch)?
+
+4. **MCP vs CLI approach**: Should the integration use Playwright CLI directly (token-efficient, command-based) or Playwright MCP server (`microsoft/playwright-mcp`) for richer integration? The CLI approach aligns better with current tool patterns.
+
+5. **Scope of WebFetch/WebSearch removal**: The `reviewer.md` agent has web tools in its tool list but doesn't explicitly document their usage. Should it retain some form of web access, or should Playwright CLI fully replace it?
+
+6. **Binary installer Playwright bundling**: For the binary distribution (install.sh/install.ps1), should Playwright CLI be pre-bundled in the release tarball, or downloaded during installation? Pre-bundling increases artifact size; downloading requires npm/Node.js on the target system.
diff --git a/research/docs/2026-02-25-ralph-workflow-implementation.md b/research/docs/2026-02-25-ralph-workflow-implementation.md
new file mode 100644
index 0000000000..da152a1f5c
--- /dev/null
+++ b/research/docs/2026-02-25-ralph-workflow-implementation.md
@@ -0,0 +1,562 @@
+# Ralph Workflow Implementation
+
+Technical documentation of the Ralph autonomous implementation workflow, the graph
+execution engine infrastructure it builds on, session management, and reusable
+workflow templates.
+
+---
+
+## 1. Ralph Graph (`src/workflows/ralph/graph.ts`)
+
+### Overview
+
+`createRalphWorkflow()` (line 98) constructs a three-phase compiled graph typed
+over `RalphWorkflowState`. The function returns a `CompiledGraph<RalphWorkflowState>`
+produced by the fluent `GraphBuilder` API. The three phases are:
+
+1. **Task Decomposition** (Phase 1) -- a planner sub-agent decomposes a user
+   prompt into a structured task list, then a tool node parses the output.
+2. **Worker Loop** (Phase 2) -- iteratively selects ready tasks and dispatches a
+   worker sub-agent until all tasks are complete, errored, or the iteration cap
+   is reached.
+3. **Review & Fix** (Phase 3) -- a reviewer sub-agent evaluates the completed
+   work, and a conditional fixer sub-agent applies corrections if the review
+   finds actionable issues.
+
+### Utility Functions (lines 35--84)
+
+Three pure utility functions support the worker loop:
+
+| Function | Lines | Purpose |
+|---|---|---|
+| `parseTasks(content)` | 35--52 | Parses LLM text output into `TaskItem[]`. Tries `JSON.parse` first; falls back to a regex extraction of the first `[...]` block. Returns `[]` on failure. |
+| `getReadyTasks(tasks)` | 57--73 | Filters tasks to those with `status === "pending"` whose `blockedBy` dependencies are all in a completed set. Normalises IDs by trimming, lowercasing, and stripping leading `#`. Recognises `"completed"`, `"complete"`, and `"done"` as finished statuses. |
+| `hasActionableTasks(tasks)` | 78--84 | Returns `true` if any task is `"in_progress"` or is a pending task that `getReadyTasks` considers ready. Used as part of the loop exit condition. |
+
+### Phase 1: Task Decomposition (lines 100--123)
+
+Two nodes chained sequentially via the fluent builder:
+
+#### Node 1: `planner` (subagent, lines 101--110)
+
+- Builder method: `.subagent({ ... })` which internally creates a
+  `subagentNode` via `src/workflows/graph/nodes.ts:1664`.
+- Agent name: `"planner"`.
+- Task prompt: `buildSpecToTasksPrompt(state.yoloPrompt ?? "")`.
+- `outputMapper` (lines 105--107): maps `result.output` to `{ specDoc: result.output ?? "" }`.
+
+#### Node 2: `parse-tasks` (tool, lines 111--123)
+
+- Builder method: `.tool({ ... })` which internally creates a `toolNode`.
+- `execute` (line 114): calls `parseTasks(args.specDoc)`.
+- `args` (line 115): reads `state.specDoc`.
+- `outputMapper` (lines 116--120): sets `tasks`, `currentTasks`, and resets
+  `iteration` to `0`.
+
+### Phase 2: Worker Loop (lines 126--187)
+
+Constructed via `.loop(bodyNodes, config)` on the builder (see
+`src/workflows/graph/builder.ts:647`). The loop body is an array of two nodes:
+
+#### Node 3: `select-ready-tasks` (tool, lines 128--138)
+
+- Created with the `toolNode` factory.
+- `execute`: calls `getReadyTasks(args.tasks)`.
+- `args`: reads `state.tasks`.
+- `outputMapper`: replaces `currentTasks` with the ready tasks.
+
+#### Node 4: `worker` (custom `NodeDefinition`, lines 141--178)
+
+- Implemented as a raw `NodeDefinition<RalphWorkflowState>` (satisfies check at
+  line 178) rather than using the `subagentNode` factory. This allows the node
+  to handle worker failures gracefully.
+- `type`: `"agent"`, `id`: `"worker"`.
+- `retry`: `{ maxAttempts: 1, backoffMs: 0, backoffMultiplier: 1 }` -- no
+  retries.
+- Execution flow (lines 147--177):
+  1. Retrieves the `SubagentGraphBridge` from `ctx.config.runtime?.subagentBridge`
+     (line 148). Throws if absent.
+  2. Takes the first ready task from `ctx.state.currentTasks` (line 153).
+  3. Builds a worker prompt via `buildWorkerAssignment(task, ctx.state.tasks)`
+     (line 155).
+  4. Spawns a sub-agent with `agentId: "worker-{taskId}"`, `agentName: "worker"`
+     (lines 158--163).
+  5. Returns a `stateUpdate` that:
+     - Increments `iteration` by 1 (line 167).
+     - Maps over all tasks: any task that was in `currentTasks` gets its status
+       set to `"completed"` if the bridge result was successful, or `"error"`
+       otherwise (lines 168--174).
+
+#### Loop Exit Condition (lines 181--186)
+
+The `until` predicate (line 181) returns `true` when:
+- All tasks have status `"completed"` or `"error"`, **OR**
+- `state.iteration >= state.maxIterations`, **OR**
+- `hasActionableTasks(state.tasks)` returns `false`.
+
+The hard safety cap `maxIterations` on the loop config itself is `100` (line 186).
+
+### Phase 3: Review & Fix (lines 189--235)
+
+#### Node 5: `reviewer` (subagent, lines 190--208)
+
+- Agent name: `"reviewer"`.
+- Task prompt: `buildReviewPrompt(tasks, yoloPrompt, progressFilePath)` where
+  `progressFilePath` is `"{ralphSessionDir}/progress.txt"` (line 197).
+- `outputMapper` (lines 199--205): calls `parseReviewResult(result.output)`; on
+  null, provides a default `ReviewResult` with empty findings and
+  `overall_correctness: "patch is correct"`.
+
+#### Conditional Fixer (lines 210--234)
+
+- Built with `.if({ condition, then })` config-based syntax (see
+  `src/workflows/graph/builder.ts:394`).
+- `condition` (lines 211--214): fires when `reviewResult` is non-null **AND**
+  has at least one finding **AND** `overall_correctness` is not `"patch is
+  correct"`.
+- `then` branch contains a single node:
+
+##### Node 6: `fixer` (subagent, lines 216--232)
+
+- Created with the `subagentNode` factory.
+- Agent name: `"debugger"`.
+- Task prompt: `buildFixSpecFromReview(reviewResult, tasks, yoloPrompt)` (lines
+  219--225). Returns `"No fixes needed"` if the spec is empty.
+- `outputMapper`: sets `{ fixesApplied: true }`.
+
+### Compiled Graph Structure
+
+After `.compile()` (line 235), the graph contains:
+
+| Node ID | Type | Factory |
+|---|---|---|
+| `planner` | agent | `subagentNode` via `.subagent()` |
+| `parse-tasks` | tool | `toolNode` via `.tool()` |
+| `select-ready-tasks` | tool | `toolNode` (inside loop body) |
+| `worker` | agent | Raw `NodeDefinition` (inside loop body) |
+| `reviewer` | agent | `subagentNode` via `.subagent()` |
+| `fixer` | agent | `subagentNode` (inside `.if()` then-branch) |
+
+Plus auto-generated structural nodes from the builder:
+- `loop_start_*`, `loop_check_*` (decision nodes for loop iteration control)
+- `decision_*` (decision node for the `.if()` conditional)
+- `merge_*` (merge node to rejoin after the conditional)
+
+---
+
+## 2. Ralph State (`src/workflows/ralph/state.ts`)
+
+### `RalphWorkflowState` Interface (lines 51--80)
+
+The interface contains 30 fields. They can be grouped as follows:
+
+#### Base State Fields (from `BaseState` in `src/workflows/graph/types.ts:114--121`)
+
+| Field | Type | Purpose |
+|---|---|---|
+| `executionId` | `string` | Unique ID for this graph execution |
+| `lastUpdated` | `string` | ISO timestamp of last state mutation |
+| `outputs` | `Record<NodeId, unknown>` | Map of node outputs keyed by node ID |
+
+#### Workflow Pipeline Fields (shared with AtomicWorkflowState)
+
+| Field | Type | Purpose |
+|---|---|---|
+| `researchDoc` | `string` | Research document content |
+| `specDoc` | `string` | Specification document content |
+| `specApproved` | `boolean` | Whether the spec has been approved |
+| `tasks` | `TaskItem[]` | Full task list |
+| `currentTasks` | `TaskItem[]` | Tasks selected for current iteration |
+| `reviewResult` | `ReviewResult \| null` | Reviewer output |
+| `fixesApplied` | `boolean` | Whether fixer ran |
+| `featureList` | `Feature[]` | Feature list entries |
+| `currentFeature` | `Feature \| null` | Currently active feature |
+| `allFeaturesPassing` | `boolean` | Whether all features pass |
+| `contextWindowUsage` | `ContextWindowUsage \| null` | Token tracking |
+| `iteration` | `number` | Current worker loop iteration |
+| `prUrl` | `string \| null` | Pull request URL |
+| `debugReports` | `DebugReport[]` | Accumulated debug reports |
+| `prBranch` | `string \| undefined` | PR branch name |
+| `completedFeatures` | `string[]` | List of completed feature descriptions |
+| `sourceFeatureListPath` | `string \| undefined` | Path to feature list source file |
+| `maxIterationsReached` | `boolean \| undefined` | Flag if iteration cap was hit |
+
+#### Ralph-Specific Fields
+
+| Field | Type | Purpose |
+|---|---|---|
+| `ralphSessionId` | `string` | UUID for the Ralph session |
+| `ralphSessionDir` | `string` | Filesystem path `~/.atomic/workflows/sessions/{id}` |
+| `yolo` | `boolean` | Whether running in yolo (autonomous) mode |
+| `yoloPrompt` | `string \| null` | The user's original prompt |
+| `yoloComplete` | `boolean` | Whether yolo execution finished |
+| `maxIterations` | `number` | Worker loop iteration cap |
+| `shouldContinue` | `boolean` | Continuation flag |
+
+### State Annotation System (`RalphStateAnnotation`, lines 82--119)
+
+The annotation object maps each field name to an `Annotation<T>` created by the
+local `annotation()` helper (line 9), which mirrors the public
+`annotation()` from `src/workflows/graph/annotation.ts:184`.
+
+Each `Annotation<T>` contains:
+- `default`: a static value or factory function.
+- `reducer`: an optional `Reducer<T>` that controls how state updates merge.
+
+Notable reducer assignments:
+
+| Field | Reducer | Behavior |
+|---|---|---|
+| `tasks` | `mergeByIdReducer<TaskItem>("id")` (line 91) | Merges task arrays by `id` field; existing tasks with matching IDs are shallow-merged with update. |
+| `currentTasks` | `(current, update) => update` (line 92) | Always replaces with the update value. |
+| `featureList` | `mergeByIdReducer<Feature>("description")` (line 96) | Merges features by `description`. |
+| `debugReports` | `concatReducer` (line 100) | Appends new reports to existing array. |
+| `completedFeatures` | `concatReducer` (line 116) | Appends new entries. |
+
+All other fields use the implicit default reducer (`Reducers.replace` from
+`src/workflows/graph/annotation.ts:72`), which replaces the current value
+entirely.
+
+#### Custom Reducers (lines 16--49)
+
+Two reducers are defined locally in `state.ts`:
+
+1. **`concatReducer<T>`** (lines 16--20): concatenates two arrays, guarding
+   against non-array inputs.
+2. **`mergeByIdReducer<T>(idField)`** (lines 22--49): returns a reducer that
+   merges two object arrays by a specified ID field. Items in the update array
+   with matching IDs are shallow-merged onto existing items; new IDs are
+   appended.
+
+### State Factory: `createRalphState()` (lines 128--156)
+
+1. Calls `initializeState(RalphStateAnnotation)` to produce an object with all
+   annotation defaults (line 132).
+2. Generates a `ralphSessionId` via `crypto.randomUUID()` (line 133).
+3. Spreads the initialized state, applies specific overrides from `options`, and
+   computes `ralphSessionDir` as
+   `~/.atomic/workflows/sessions/{ralphSessionId}` (line 144).
+4. Spreads `...options` last (line 154), allowing callers to override any field.
+
+### State Update: `updateRalphState()` (lines 165--174)
+
+Delegates to `applyStateUpdate(RalphStateAnnotation, current, update)` from the
+annotation module (`src/workflows/graph/annotation.ts:265`), which iterates each
+key in the update and applies the field's reducer. Then stamps `lastUpdated`
+with the current ISO timestamp.
+
+### Type Guard: `isRalphWorkflowState()` (lines 179--209)
+
+Checks for the presence and type of all mandatory fields across three groups:
+base state fields, atomic workflow fields, and Ralph-specific fields.
+
+---
+
+## 3. Ralph Prompts (`src/workflows/ralph/prompts.ts`)
+
+### Types (lines 15--21, 141--158)
+
+- **`TaskItem`** (lines 15--21): `{ id?: string; content: string; status: string; activeForm: string; blockedBy?: string[] }`.
+- **`ReviewFinding`** (lines 141--150): includes `title`, `body`,
+  `confidence_score?`, `priority?`, and optional `code_location` with
+  `absolute_file_path` and `line_range`.
+- **`ReviewResult`** (lines 153--158): `{ findings: ReviewFinding[]; overall_correctness: string; overall_explanation: string; overall_confidence_score?: number }`.
+
+### Helper: `isCompletedStatus()` (lines 23--30)
+
+Normalises a status string (trim + lowercase) and returns `true` for
+`"completed"`, `"complete"`, or `"done"`.
+
+### Phase 1: `buildSpecToTasksPrompt(specContent)` (lines 37--77)
+
+Constructs a prompt that:
+- Wraps `specContent` in `<specification>` XML tags (lines 42--44).
+- Defines the output JSON schema with fields `id`, `content`, `status`,
+  `activeForm`, `blockedBy` (lines 50--60).
+- Provides field definitions (lines 63--68).
+- Includes ordering/dependency guidelines (lines 72--75).
+- Instructs the LLM to output only the JSON array with no surrounding text
+  (line 76).
+
+### Phase 2: `buildWorkerAssignment(task, allTasks)` (lines 84--134)
+
+Constructs a worker prompt with up to four sections:
+
+1. **Task Assignment header** (lines 122--126): shows `**Task ID:**` and
+   `**Task:**` with the current task's details.
+2. **Dependencies section** (lines 104--111, conditionally included): lists each
+   `blockedBy` entry with its content from `allTasks`, or `"(not found)"` if the
+   dependency ID is missing. Omitted when `blockedBy` is empty or undefined.
+3. **Completed Tasks section** (lines 113--120, conditionally included): lists
+   all tasks matching `isCompletedStatus()`. Omitted when none are completed.
+4. **Instructions section** (lines 127--133): directs the worker to focus solely
+   on the task, implement until complete and tested, not modify unrelated tasks,
+   and record errors.
+
+### Phase 3a: `buildReviewPrompt(tasks, userPrompt, progressFilePath)` (lines 161--247)
+
+Constructs a code review prompt with:
+- The original user request in `<user_request>` XML tags (lines 177--179).
+- A list of completed tasks (lines 166--169).
+- A reference to the progress file path (line 189).
+- Six review focus areas: Correctness, Error Handling, Edge Cases, Security,
+  Performance, Test Coverage (lines 195--206).
+- A JSON output schema defining `findings`, `overall_correctness`,
+  `overall_explanation`, `overall_confidence_score` (lines 209--229).
+- Priority definitions P0--P3 (lines 233--236).
+- Guidelines directing the reviewer to set `overall_correctness` to
+  `"patch is incorrect"` only for P0/P1 issues (line 244).
+
+### Phase 3b: `buildFixSpecFromReview(review, tasks, userPrompt)` (lines 250--316)
+
+Returns `""` if findings are empty (lines 256--262). Otherwise builds a document
+with:
+- The original user prompt (line 269).
+- The review verdict (lines 273--274).
+- Findings sorted by priority (ascending, lines 282--286), each as a subsection
+  with priority label, code location (or `"Location not specified"`), issue body,
+  and a rubric statement (lines 289--303).
+- Fix guidelines section (lines 307--313): address in priority order, run tests,
+  minimal changes, document blockers.
+
+### `parseReviewResult(content)` (lines 323--382)
+
+Three-stage JSON extraction with progressive fallback:
+
+1. **Direct parse** (lines 324--339): `JSON.parse(content)`. Checks for
+   `findings` and `overall_correctness` fields.
+2. **Markdown code fence** (lines 341--360): regex
+   `` /```(?:json)?\s*\n([\s\S]*?)\n```/ `` extraction.
+3. **Embedded JSON** (lines 362--379): regex `/\{[\s\S]*"findings"[\s\S]*\}/`
+   extraction.
+
+All three stages filter out P3 findings (priority 3) from the findings array
+(e.g., lines 329--331). Findings with `priority === undefined` are kept. Returns
+`null` if all attempts fail.
+
+---
+
+## 4. Ralph Tests
+
+### Integration Tests (`src/workflows/ralph/graph.test.ts`)
+
+756 lines. Uses `bun:test`. Imports `executeGraph` and `streamGraph` from
+`../graph/compiled.ts` and `createRalphWorkflow` / `createRalphState` from the
+Ralph module.
+
+#### Mock Infrastructure (lines 28--100)
+
+- **`createMockBridge(responses)`** (lines 28--55): creates a mock
+  `SubagentGraphBridge` with `spawn()` and `spawnParallel()` methods. The
+  `responses` map keys agent names to handler functions returning
+  `SubagentResult`.
+- **`createMockRegistry()`** (lines 60--78): returns a registry that accepts any
+  agent name and returns a dummy entry.
+- **`createWorkflowWithMockBridge(responses)`** (lines 83--100): compiles the
+  real `createRalphWorkflow()` graph, then injects the mock bridge and registry
+  into `workflow.config.runtime`.
+
+#### Test Suites
+
+| Suite | Lines | Tests | Coverage Focus |
+|---|---|---|---|
+| Basic Compilation | 106--120 | 1 | Verifies `compile()` succeeds, `nodes.size > 0`, `startNode === "planner"`, and all 6 named nodes exist. |
+| 3-Phase Flow | 122--453 | 4 | Full end-to-end: simple tasks (2 independent), task dependencies (ordered execution via `blockedBy`), fixer triggered on review findings, fixer skipped on clean review. |
+| Worker Loop | 456--608 | 2 | Loop exits when no actionable tasks remain (task #1 errors, #2 stays pending/blocked). Respects `maxIterations` limit (3 of 5 chained tasks completed). |
+| Edge Cases | 611--755 | 2 | Empty task list from planner. P3 findings filtered out by `parseReviewResult`, preventing fixer dispatch. |
+
+Key assertions across tests:
+- Task dependency ordering verified by capturing execution order via worker
+  prompt regex parsing (line 241).
+- Worker call counts verify one-at-a-time dispatch (the worker node processes
+  the first ready task each iteration).
+- Fixer dispatch verified via a `fixerCalled` flag and checking
+  `state.fixesApplied`.
+- The mock bridge handler for the fixer is keyed by `"debugger"` (the fixer's
+  `agentName`), not `"fixer"`.
+
+### Unit Tests (`src/workflows/graph/nodes/ralph.test.ts`)
+
+734 lines. Tests the four exported prompt-building functions and
+`parseReviewResult` in isolation.
+
+| Suite | Lines | Tests | Coverage Focus |
+|---|---|---|---|
+| `buildSpecToTasksPrompt` | 12--37 | 3 | Verifies spec content wrapped in XML tags, JSON schema fields present, "Output ONLY the JSON array" instruction. |
+| `buildWorkerAssignment` | 39--392 | 16 | Task ID/content inclusion, missing ID fallback (`"unknown"`), dependency section presence/absence, completed tasks section, status variant recognition (`completed`/`complete`/`done`), missing dependency graceful handling (`"(not found)"`), special characters, large task lists (100 items), deterministic output, section formatting. |
+| `buildReviewPrompt` | 394--480 | 7 | User prompt in XML tags, completed tasks listed (pending excluded), progress file path, review focus areas, JSON output format fields, priority definitions, tasks without IDs. |
+| `parseReviewResult` | 482--579 | 7 | Direct JSON, markdown code fence, embedded JSON in prose, P3 filtering, findings without priority kept, invalid JSON returns null, missing required fields returns null. |
+| `buildFixSpecFromReview` | 582--733 | 7 | Empty string on no findings, fix spec structure, priority sorting (P0 < P1 < P2), missing code location, default priority P2, fix guidelines, rubric per finding. |
+
+---
+
+## 5. Session Management (`src/workflows/session.ts`)
+
+### Overview
+
+A generic workflow session manager (not Ralph-specific). Manages persistent
+session directories at `~/.atomic/workflows/sessions/{sessionId}/` for all
+workflow executions.
+
+### Types
+
+**`WorkflowSession`** (lines 17--26):
+
+| Field | Type |
+|---|---|
+| `sessionId` | `string` |
+| `workflowName` | `string` |
+| `sessionDir` | `string` |
+| `createdAt` | `string` |
+| `lastUpdated` | `string` |
+| `status` | `"running" \| "paused" \| "completed" \| "failed"` |
+| `nodeHistory` | `string[]` |
+| `outputs` | `Record<string, unknown>` |
+
+### Constants
+
+`WORKFLOW_SESSIONS_DIR` (lines 32--37): resolves to `~/.atomic/workflows/sessions`.
+
+### Functions
+
+#### `generateWorkflowSessionId()` (lines 43--45)
+
+Returns `crypto.randomUUID()`.
+
+#### `getWorkflowSessionDir(sessionId)` (lines 47--49)
+
+Returns `join(WORKFLOW_SESSIONS_DIR, sessionId)`.
+
+#### `initWorkflowSession(workflowName, sessionId?)` (lines 51--77)
+
+1. Generates or uses the provided `sessionId`.
+2. Creates the session directory and three subdirectories (`checkpoints`,
+   `agents`, `logs`) by writing `.gitkeep` sentinel files via `Bun.write()`.
+3. Constructs a `WorkflowSession` object with status `"running"`.
+4. Calls `saveWorkflowSession(session)` to persist.
+
+#### `saveWorkflowSession(session)` (lines 79--85)
+
+Stamps `lastUpdated`, writes `session.json` as formatted JSON to
+`{sessionDir}/session.json`.
+
+#### `saveSubagentOutput(sessionDir, agentId, result)` (lines 87--95)
+
+Writes a `SubagentResult` as JSON to `{sessionDir}/agents/{agentId}.json`.
+Returns the output path.
+
+### Relationship to Ralph
+
+The Ralph state's `ralphSessionDir` field (from `state.ts:144`) points to a
+directory under `WORKFLOW_SESSIONS_DIR`. The `SubagentGraphBridge` class
+(`src/workflows/graph/subagent-bridge.ts:235`) calls `saveSubagentOutput()` to
+persist each sub-agent's result in the `agents/` subdirectory.
+
+---
+
+## 6. Workflow Templates (`src/workflows/graph/templates.ts`)
+
+### Overview
+
+Four template functions that produce `GraphBuilder` instances encoding common
+workflow patterns. Each accepts a configuration object and returns an
+uncomplied builder (callers must call `.compile()` themselves).
+
+### Shared Helpers (lines 42--105)
+
+- **`isRecord(value)`** (lines 42--44): type guard for `Record<string, unknown>`.
+- **`isCompletedStatus(status)`** (lines 46--49): mirrors the Ralph version;
+  returns `true` for `"completed"`, `"complete"`, `"done"`.
+- **`defaultTaskLoopUntil(state, workerNodeId)`** (lines 51--77): default exit
+  condition for `taskLoop`. Checks `state.shouldContinue === false`,
+  `state.allTasksComplete === true`, then inspects
+  `state.outputs[workerNodeId]` for the same flags, and finally checks if all
+  tasks in the worker output array have a completed status.
+- **`applyDefaultConfig(builder, defaultConfig?)`** (lines 79--105): monkey-patches
+  the builder's `compile()` method to merge `defaultConfig` (including nested
+  `metadata`) before delegating to the original `compile()`.
+- **`toStateUpdates(value)`** (lines 128--144): normalises a value (Array, Map,
+  or single object) into `Partial<TState>[]` for the map-reduce merger.
+
+### Template 1: `sequential(nodes, config?)` (lines 110--126)
+
+**Config type**: `NodeDefinition<TState>[]` plus optional `GraphConfig`.
+
+**Graph structure**: Linear chain. Calls `graph<TState>().start(nodes[0])` then
+`.then(node)` for each remaining node. Throws if `nodes` is empty.
+
+### Template 2: `mapReduce(options)` (lines 152--175)
+
+**Config type**: `MapReduceOptions<TState>` (lines 11--16) with fields:
+- `splitter`: `NodeDefinition<TState>` -- produces items to map over.
+- `worker`: `NodeDefinition<TState>` -- processes each item.
+- `merger`: `(results: Partial<TState>[], state: TState) => Partial<TState>` --
+  combines worker outputs.
+
+**Graph structure**: Three-node chain: `splitter -> worker -> {worker.id}_reduce`.
+The auto-generated reducer node (lines 157--167) reads
+`state.outputs[worker.id]`, normalises it via `toStateUpdates()`, and calls
+`options.merger()`.
+
+### Template 3: `reviewCycle(options)` (lines 180--191)
+
+**Config type**: `ReviewCycleOptions<TState>` (lines 21--28) with fields:
+- `executor`, `reviewer`, `fixer`: three `NodeDefinition<TState>` nodes.
+- `until`: exit condition function.
+- `maxIterations?`: safety cap.
+
+**Graph structure**: A single `.loop([executor, reviewer, fixer], { until, maxIterations })` followed by `.end()`. All three nodes execute sequentially within each
+loop iteration.
+
+### Template 4: `taskLoop(options)` (lines 196--211)
+
+**Config type**: `TaskLoopOptions<TState>` (lines 33--40) with fields:
+- `decomposer`: `NodeDefinition<TState>` -- runs once before the loop.
+- `worker`: `NodeDefinition<TState>` -- runs each iteration.
+- `reviewer?`: optional `NodeDefinition<TState>` -- runs after worker each
+  iteration.
+- `until?`: exit condition (defaults to `defaultTaskLoopUntil`).
+- `maxIterations?`: safety cap.
+
+**Graph structure**: `.start(decomposer)` then `.loop(loopNodes, { until, maxIterations })` then `.end()`. If `reviewer` is provided, the loop body is
+`[worker, reviewer]`; otherwise just `worker`.
+
+### Relationship to Ralph
+
+The Ralph workflow (`src/workflows/ralph/graph.ts`) does **not** use these
+templates. It builds its graph directly via the `GraphBuilder` fluent API,
+constructing the same pattern as a `taskLoop` with an additional review-and-fix
+phase. The templates exist as reusable alternatives for custom workflow authors.
+
+---
+
+## Data Flow Summary
+
+```
+User prompt (yoloPrompt)
+    |
+    v
+[planner subagent] --> specDoc (raw LLM output)
+    |
+    v
+[parse-tasks tool] --> tasks: TaskItem[], currentTasks: TaskItem[], iteration: 0
+    |
+    v
++--- LOOP START ---+
+|                   |
+|  [select-ready-tasks tool] --> currentTasks (filtered ready tasks)
+|       |
+|  [worker subagent] --> tasks (status updated), iteration++
+|       |
++--- LOOP CHECK ---+ (exit when all done, all errored, or maxIterations)
+    |
+    v
+[reviewer subagent] --> reviewResult: ReviewResult
+    |
+    v
+[IF reviewResult has findings AND patch is incorrect]
+    |-- YES --> [fixer subagent (debugger)] --> fixesApplied: true
+    |-- NO  --> (skip)
+    v
+[MERGE] --> END
+```
diff --git a/research/docs/2026-02-25-skills-directory-structure.md b/research/docs/2026-02-25-skills-directory-structure.md
new file mode 100644
index 0000000000..e00f834a7b
--- /dev/null
+++ b/research/docs/2026-02-25-skills-directory-structure.md
@@ -0,0 +1,898 @@
+---
+date: 2026-02-25 06:25:00 PST
+researcher: codebase-analyzer
+git_commit: $(git rev-parse --verify HEAD 2>/dev/null || echo "no-commits")
+branch: main
+repository: playwright-cli
+topic: "Skills Directory Structure Analysis"
+tags: [research, skills, architecture, configuration, atomic-cli]
+status: complete
+last_updated: 2026-02-25
+last_updated_by: codebase-analyzer
+---
+
+# Skills Directory Structure Analysis
+
+## Research Question
+
+Document the skills directory structure across all three agent configurations in the Atomic CLI project, including:
+1. `.github/skills/` - All skills, their structure, and SKILL.md contents
+2. `.claude/skills/` - All skills, their structure, and SKILL.md contents
+3. `.opencode/skills/` - All skills, their structure, and SKILL.md contents
+4. How skills are referenced in `package.json`
+5. How skills are deployed via `install.sh`
+6. The `~/.atomic` directory structure
+
+## Summary
+
+The Atomic CLI project maintains a consistent skills structure across three agent platform configurations: GitHub Copilot (`.github/skills/`), Claude Code (`.claude/skills/`), and OpenCode (`.opencode/skills/`). The project includes 11 standardized skills that provide specialized capabilities for code development, documentation, and repository management. Skills are deployed globally to `~/.atomic` during installation, with SCM-specific skills (gh-*, sl-*) excluded from global configuration as they are project-scoped.
+
+## Directory Structure Overview
+
+All three agent configurations maintain identical directory structures:
+
+```
+.github/skills/          # GitHub Copilot skills
+.claude/skills/          # Claude Code skills  
+.opencode/skills/        # OpenCode AI skills
+├── create-spec/
+│   └── SKILL.md
+├── explain-code/
+│   └── SKILL.md
+├── frontend-design/
+│   └── SKILL.md
+├── gh-commit/
+│   └── SKILL.md
+├── gh-create-pr/
+│   └── SKILL.md
+├── init/
+│   └── SKILL.md
+├── prompt-engineer/
+│   ├── SKILL.md
+│   └── references/
+│       ├── advanced_patterns.md (271 lines)
+│       ├── core_prompting.md (137 lines)
+│       └── quality_improvement.md (193 lines)
+├── research-codebase/
+│   └── SKILL.md
+├── sl-commit/
+│   └── SKILL.md
+├── sl-submit-diff/
+│   └── SKILL.md
+└── testing-anti-patterns/
+    └── SKILL.md
+```
+
+## Skill Pattern: SKILL.md Structure
+
+All skills follow a consistent YAML frontmatter + markdown content pattern:
+
+```markdown
+---
+name: skill-name
+description: Brief description of what the skill does
+[optional-fields]
+---
+
+# Skill Content
+
+Instructions and documentation...
+```
+
+### Core Frontmatter Fields
+
+- **name**: Skill identifier (kebab-case)
+- **description**: Single-line description of skill purpose
+
+### Optional Frontmatter Fields (Claude-specific)
+
+The `.claude/skills/research-codebase/SKILL.md` file includes additional frontmatter fields not present in other configurations:
+
+```yaml
+aliases: [research]
+argument-hint: "<research-question>"
+required-arguments: [research-question]
+```
+
+This is the **only difference** found between the three configurations.
+
+## Complete Skills Catalog
+
+### 1. create-spec
+**Location**: All three directories  
+**File**: `SKILL.md` (12,627 bytes)
+
+**Purpose**: Create detailed execution plans (technical design documents/RFCs) for implementing features or refactors by leveraging existing research in the `research/` directory.
+
+**Key Features**:
+- Uses `codebase-research-locator` and `codebase-research-analyzer` agents
+- Generates comprehensive specs in `specs/` directory
+- Follows RFC/TDD template structure with sections:
+  - Executive Summary
+  - Context and Motivation
+  - Goals and Non-Goals
+  - Proposed Solution (High-Level Design)
+  - Detailed Design
+  - Alternatives Considered
+  - Cross-Cutting Concerns
+  - Migration, Rollout, and Testing
+  - Open Questions / Unresolved Issues
+- Includes Mermaid diagram templates
+- Walks through open questions with user using ask tool
+- Does NOT implement, only creates spec
+
+**Configuration**: None required
+
+---
+
+### 2. explain-code
+**Location**: All three directories  
+**File**: `SKILL.md` (7,339 bytes)
+
+**Purpose**: Explain code functionality in detail with systematic analysis approach.
+
+**Key Features**:
+- 16-step analysis process from context to debugging
+- DeepWiki MCP tool integration for external library documentation
+- WebFetch/WebSearch for additional context
+- Language-specific considerations for JS/TS, Python, Java, C#, Go, Rust
+- Covers:
+  - Code Context Analysis
+  - High-Level Overview
+  - Code Structure Breakdown
+  - Line-by-Line Analysis
+  - Algorithm and Logic Explanation
+  - Data Structures and Types
+  - Framework and Library Usage
+  - Error Handling and Edge Cases
+  - Performance Considerations
+  - Security Implications
+  - Testing and Debugging
+  - Dependencies and Integrations
+  - Common Patterns and Idioms
+  - Potential Improvements
+  - Related Code and Context
+  - Debugging and Troubleshooting
+
+**Configuration**: Uses MCP tools when available
+
+---
+
+### 3. frontend-design
+**Location**: All three directories  
+**File**: `SKILL.md` (3,957 bytes)
+
+**Purpose**: Create distinctive, production-grade frontend interfaces with high design quality.
+
+**Key Features**:
+- Emphasizes avoiding generic "AI slop" aesthetics
+- Focuses on bold, intentional design choices
+- Guidelines for:
+  - Typography: Distinctive fonts (avoid Arial, Inter)
+  - Color & Theme: Cohesive CSS variables, dominant colors with sharp accents
+  - Motion: CSS animations, Motion library for React, scroll-triggering
+  - Spatial Composition: Asymmetry, overlap, diagonal flow, grid-breaking
+  - Backgrounds & Visual Details: Gradient meshes, noise textures, geometric patterns
+- Matches implementation complexity to aesthetic vision
+- Encourages varied designs (light/dark themes, different aesthetics)
+
+**Configuration**: Supports HTML/CSS/JS, React, Vue frameworks
+
+---
+
+### 4. gh-commit
+**Location**: All three directories  
+**File**: `SKILL.md` (13,675 bytes)
+
+**Purpose**: Create well-formatted commits following Conventional Commits 1.0.0 specification.
+
+**Key Features**:
+- Includes complete Conventional Commits specification
+- Automatic staging if no files staged
+- Pre-commit checks (defined in `.pre-commit-config.yaml`)
+- AI authorship attribution via Git trailers
+- Multi-commit detection and suggestions
+- Commit message structure:
+  ```
+  <type>[optional scope]: <description>
+  
+  [optional body]
+  
+  [optional footer(s)]
+  ```
+- Supported types: feat, fix, build, chore, ci, docs, style, refactor, perf, test
+- Breaking change indicators (`!` or `BREAKING CHANGE:` footer)
+
+**Configuration**: 
+- Reads git status and diff
+- Uses pre-commit hooks
+- Adds `Assistant-model: Claude Code` trailer
+
+---
+
+### 5. gh-create-pr
+**Location**: All three directories  
+**File**: `SKILL.md` (399 bytes)
+
+**Purpose**: Commit unstaged changes, push changes, and submit a pull request.
+
+**Key Features**:
+- Creates logical commits for unstaged changes
+- Pushes branch to remote
+- Creates pull request with proper name and description
+
+**Configuration**: Uses GitHub CLI (gh)
+
+---
+
+### 6. init
+**Location**: All three directories  
+**File**: `SKILL.md` (4,075 bytes)
+
+**Purpose**: Generate `CLAUDE.md` and `AGENTS.md` files by exploring the codebase.
+
+**Key Features**:
+- Uses `codebase-analyzer`, `codebase-locator`, `codebase-pattern-finder` sub-agents
+- Explores project metadata:
+  - Manifest files (package.json, Cargo.toml, go.mod, pyproject.toml, etc.)
+  - Directory structure
+  - Config files (eslintrc, tsconfig.json, biome.json, oxlint.json, prettier, CI configs)
+  - README.md
+  - Environment files
+  - Package manager identification
+- Generates populated template with:
+  - Project name and overview
+  - Project structure table
+  - Quick reference commands
+  - Environment setup
+  - Progressive disclosure docs table
+  - Universal rules
+  - Code quality tools
+- Writes identical content to both `CLAUDE.md` and `AGENTS.md`
+- Target: Under 100 lines (ideally under 60)
+
+**Configuration**: None required
+
+---
+
+### 7. prompt-engineer
+**Location**: All three directories  
+**Files**: 
+- `SKILL.md` (8,360 bytes)
+- `references/advanced_patterns.md` (271 lines)
+- `references/core_prompting.md` (137 lines)
+- `references/quality_improvement.md` (193 lines)
+
+**Purpose**: Create, improve, or optimize prompts using Anthropic best practices.
+
+**Key Features**:
+- 7-step workflow:
+  1. Understand Requirements
+  2. Identify Applicable Techniques
+  3. Load Relevant References
+  4. Design the Prompt
+  5. Add Quality Controls
+  6. Optimize and Test
+  7. Iterate Based on Results
+- Core techniques:
+  - Be clear and direct
+  - System prompts
+  - XML tags for structure
+- Advanced techniques:
+  - Chain of thought
+  - Multishot prompting
+  - Prompt chaining
+  - Long context handling (100K+ tokens)
+  - Extended thinking
+- Quality techniques:
+  - Hallucination reduction
+  - Consistency improvement
+  - Jailbreak mitigation
+- Technique selection matrix
+- Progressive disclosure approach
+
+**Configuration**: References three comprehensive markdown files
+
+---
+
+### 8. research-codebase
+**Location**: All three directories  
+**File**: `SKILL.md` (11,206 bytes)
+
+**Purpose**: Document codebase as-is with research directory for historical context.
+
+**Key Features**:
+- Comprehensive research workflow:
+  1. Read directly mentioned files first (FULL read, no limit/offset)
+  2. Analyze and decompose research question
+  3. Spawn parallel sub-agent tasks
+  4. Wait for all sub-agents to complete
+  5. Generate research document
+  6. Add GitHub permalinks (if applicable)
+  7. Present findings
+  8. Handle follow-up questions
+- Specialized sub-agents:
+  - `codebase-locator`: Find WHERE files/components live
+  - `codebase-analyzer`: Understand HOW code works (no critique)
+  - `codebase-pattern-finder`: Find existing patterns (no evaluation)
+  - `codebase-research-locator`: Discover research documents
+  - `codebase-research-analyzer`: Extract insights from documents
+  - `codebase-online-researcher`: External documentation/resources
+- Research directory structure:
+  ```
+  research/
+  ├── tickets/YYYY-MM-DD-XXXX-description.md
+  ├── docs/YYYY-MM-DD-topic.md
+  ├── notes/YYYY-MM-DD-meeting.md
+  ```
+- Document format with YAML frontmatter:
+  - date, researcher, git_commit, branch, repository
+  - topic, tags, status, last_updated, last_updated_by
+- **Critical**: Documentarian role, NOT evaluator (document what IS, not what SHOULD BE)
+- Only generates artifacts in `research/` directory
+
+**Configuration**: 
+- Uses MCP tools (DeepWiki, WebFetch/WebSearch)
+- Generates GitHub permalinks when on main/pushed commits
+
+**Claude-specific frontmatter** (`.claude/skills/research-codebase/SKILL.md` only):
+```yaml
+aliases: [research]
+argument-hint: "<research-question>"
+required-arguments: [research-question]
+```
+
+---
+
+### 9. sl-commit
+**Location**: All three directories  
+**File**: `SKILL.md` (2,091 bytes)
+
+**Purpose**: Create well-formatted commits using Sapling SCM with Conventional Commits format.
+
+**Key Features**:
+- Similar to gh-commit but for Sapling SCM
+- No staging area (commits all pending changes directly)
+- Amend with auto-restack: `sl amend` automatically rebases descendants
+- Stacked Diffs: Each commit becomes separate Phabricator diff
+- Key commands:
+  - `sl status` - Check repository state
+  - `sl diff` - View pending changes
+  - `sl add <files>` - Add untracked files
+  - `sl commit -m "<message>"` - Create commit
+  - `sl commit -A` - Add untracked and commit
+  - `sl amend` - Amend current commit
+  - `sl amend --to COMMIT` - Amend changes to specific commit in stack
+- **Windows Note**: Use full path to `sl.exe` to avoid PowerShell alias conflict
+
+**Configuration**: Uses Sapling SCM
+
+---
+
+### 10. sl-submit-diff
+**Location**: All three directories  
+**File**: `SKILL.md` (1,959 bytes)
+
+**Purpose**: Submit commits as Phabricator diffs for code review using Sapling.
+
+**Key Features**:
+- Workflow:
+  1. If uncommitted changes, run `/commit` first
+  2. Submit with `jf submit --draft` (DRAFT mode)
+  3. Each commit in stack becomes separate Phabricator diff (D12345)
+  4. Commit messages updated with `Differential Revision:` link
+- Commands:
+  - `sl status` - Check for uncommitted changes
+  - `jf submit --draft` - Submit to Phabricator in DRAFT mode
+  - `sl diff --since-last-submit` - View changes since last submission
+- Diff status values:
+  - Needs Review
+  - Accepted
+  - Needs Revision
+  - Committed
+  - Abandoned
+- Stacked diffs with dependency relationships
+- **Windows Note**: Use full path to `sl.exe`
+
+**Configuration**: Uses Sapling SCM and `jf` (Meta tooling)
+
+---
+
+### 11. testing-anti-patterns
+**Location**: All three directories  
+**File**: `SKILL.md` (5,102 bytes)
+
+**Purpose**: Identify and prevent testing anti-patterns when writing tests.
+
+**Key Features**:
+- Core principle: Test what code does, not what mocks do
+- The Iron Laws:
+  1. NEVER test mock behavior
+  2. NEVER add test-only methods to production classes
+  3. NEVER mock without understanding dependencies
+- Anti-patterns covered:
+  1. Testing Mock Behavior
+  2. Test-Only Methods in Production
+  3. Mocking Without Understanding
+  4. Incomplete Mocks
+  5. Integration Tests as Afterthought
+- Gate functions for each anti-pattern
+- Quick reference table
+- Emphasizes strict TDD to prevent anti-patterns
+
+**Configuration**: None required
+
+---
+
+## Package.json Files Field
+
+**Location**: `package.json:22-31`
+
+The `files` field specifies which directories are included in the npm package:
+
+```json
+"files": [
+  "src",
+  "assets/settings.schema.json",
+  ".claude",
+  ".opencode",
+  ".mcp.json",
+  ".github/skills",
+  ".github/agents",
+  ".github/mcp-config.json"
+]
+```
+
+**Key observations**:
+- Skills are explicitly included via `.github/skills`
+- Agent configurations included via `.github/agents`
+- `.claude` and `.opencode` directories included in their entirety
+- `.github/workflows` and `.github/dependabot.yml` are NOT included (excluded from package)
+
+---
+
+## Install.sh Deployment Strategy
+
+**Location**: `install.sh:144-165`, `install.sh:233-234`
+
+### sync_global_agent_configs Function
+
+```bash
+sync_global_agent_configs() {
+    local source_root="$1"
+
+    mkdir -p "$ATOMIC_HOME/.claude" "$ATOMIC_HOME/.opencode" "$ATOMIC_HOME/.copilot"
+
+    cp -R "$source_root/.claude/." "$ATOMIC_HOME/.claude/"
+    cp -R "$source_root/.opencode/." "$ATOMIC_HOME/.opencode/"
+    cp -R "$source_root/.github/." "$ATOMIC_HOME/.copilot/"
+
+    if [[ -f "$source_root/.mcp.json" ]]; then
+        cp "$source_root/.mcp.json" "$ATOMIC_HOME/.mcp.json"
+    fi
+
+    # Remove SCM-managed skills from global config; these are project-scoped.
+    rm -rf "$ATOMIC_HOME/.claude/skills/gh-"* "$ATOMIC_HOME/.claude/skills/sl-"* 2>/dev/null || true
+    rm -rf "$ATOMIC_HOME/.opencode/skills/gh-"* "$ATOMIC_HOME/.opencode/skills/sl-"* 2>/dev/null || true
+    rm -rf "$ATOMIC_HOME/.copilot/skills/gh-"* "$ATOMIC_HOME/.copilot/skills/sl-"* 2>/dev/null || true
+
+    # Keep Copilot global config focused on skills/agents/instructions/MCP.
+    rm -rf "$ATOMIC_HOME/.copilot/workflows" 2>/dev/null || true
+    rm -f "$ATOMIC_HOME/.copilot/dependabot.yml" 2>/dev/null || true
+}
+```
+
+### Deployment Flow
+
+1. **Installation locations**:
+   - `$BIN_DIR` (default: `$HOME/.local/bin`) - Binary
+   - `$DATA_DIR` (default: `$HOME/.local/share/atomic`) - Config files
+   - `$ATOMIC_HOME` (hardcoded: `$HOME/.atomic`) - Global agent configs
+
+2. **Configuration sync**:
+   - Downloads `atomic-config.tar.gz` from GitHub releases
+   - Extracts to `$DATA_DIR`
+   - Calls `sync_global_agent_configs "$DATA_DIR"`
+
+3. **Directory mappings**:
+   - `.claude/` → `~/.atomic/.claude/`
+   - `.opencode/` → `~/.atomic/.opencode/`
+   - `.github/` → `~/.atomic/.copilot/`
+   - `.mcp.json` → `~/.atomic/.mcp.json`
+
+4. **Exclusions**:
+   - SCM skills: `gh-commit`, `gh-create-pr`, `sl-commit`, `sl-submit-diff`
+   - GitHub-specific: `workflows/`, `dependabot.yml`
+
+**Rationale**: SCM skills are project-scoped and configured per-project via `atomic init`, not globally.
+
+---
+
+## ~/.atomic Directory Structure
+
+**Actual structure** (from system inspection):
+
+```
+~/.atomic/
+├── .claude/
+│   ├── agents/
+│   │   ├── codebase-analyzer.md
+│   │   ├── codebase-locator.md
+│   │   ├── codebase-online-researcher.md
+│   │   ├── codebase-pattern-finder.md
+│   │   ├── codebase-research-analyzer.md
+│   │   ├── codebase-research-locator.md
+│   │   ├── debugger.md
+│   │   ├── reviewer.md
+│   │   └── worker.md
+│   ├── skills/
+│   │   ├── create-spec/
+│   │   ├── explain-code/
+│   │   ├── frontend-design/
+│   │   ├── init/
+│   │   ├── prompt-engineer/
+│   │   ├── research-codebase/
+│   │   └── testing-anti-patterns/
+│   └── settings.json
+├── .opencode/
+│   ├── agents/
+│   │   ├── codebase-analyzer.md
+│   │   ├── codebase-locator.md
+│   │   ├── codebase-online-researcher.md
+│   │   ├── codebase-pattern-finder.md
+│   │   ├── codebase-research-analyzer.md
+│   │   ├── codebase-research-locator.md
+│   │   ├── debugger.md
+│   │   ├── reviewer.md
+│   │   └── worker.md
+│   ├── skills/
+│   │   ├── create-spec/
+│   │   ├── explain-code/
+│   │   ├── frontend-design/
+│   │   ├── init/
+│   │   ├── prompt-engineer/
+│   │   ├── research-codebase/
+│   │   └── testing-anti-patterns/
+│   ├── node_modules/
+│   ├── bun.lock
+│   ├── .gitignore
+│   ├── opencode.json
+│   └── package.json
+├── .copilot/
+│   ├── agents/
+│   │   ├── codebase-analyzer.md
+│   │   ├── codebase-locator.md
+│   │   ├── codebase-online-researcher.md
+│   │   ├── codebase-pattern-finder.md
+│   │   ├── codebase-research-analyzer.md
+│   │   ├── codebase-research-locator.md
+│   │   ├── debugger.md
+│   │   ├── reviewer.md
+│   │   └── worker.md
+│   ├── skills/
+│   │   ├── create-spec/
+│   │   ├── explain-code/
+│   │   ├── frontend-design/
+│   │   ├── init/
+│   │   ├── prompt-engineer/
+│   │   ├── research-codebase/
+│   │   └── testing-anti-patterns/
+│   └── mcp-config.json
+├── .mcp.json
+├── settings.json
+├── .command_history
+├── cache/
+├── .tmp/
+│   └── opencode-config-merged/
+│       └── skills/
+└── workflows/
+    └── sessions/
+```
+
+**Key observations**:
+- Skills are identical across all three agent platforms (minus SCM skills)
+- Agents are identical across all three platforms
+- Each platform has its own configuration file:
+  - `.claude/settings.json`
+  - `.opencode/opencode.json`
+  - `.copilot/mcp-config.json`
+- Global `.mcp.json` at root
+- OpenCode has additional npm dependency management (`node_modules/`, `bun.lock`, `package.json`)
+- Temporary merged config in `.tmp/opencode-config-merged/`
+
+---
+
+## Architectural Patterns
+
+### 1. Multi-Platform Consistency Pattern
+
+**Pattern**: Maintain identical skill implementations across multiple agent platforms.
+
+**Implementation**:
+- Three parallel directory structures (`.github/skills/`, `.claude/skills/`, `.opencode/skills/`)
+- Identical SKILL.md files (with one exception for Claude-specific frontmatter)
+- Single source deployment to three targets
+
+**Benefits**:
+- Skills are platform-agnostic
+- Unified development experience
+- Easier maintenance (update once, sync to all)
+
+### 2. Global vs. Project-Scoped Skills Pattern
+
+**Pattern**: Separate skills into global (development workflow) and project-scoped (SCM integration).
+
+**Implementation**:
+- Global skills: Deployed to `~/.atomic` during installation
+- Project-scoped skills: SCM skills (`gh-*`, `sl-*`) excluded from global config
+- Project-scoped skills: Configured per-project via `atomic init`
+
+**Rationale**:
+- SCM choice varies by project
+- Avoids conflicts between Git and Sapling workflows
+- Cleaner global configuration
+
+### 3. Skill Definition Pattern
+
+**Pattern**: YAML frontmatter + Markdown content with consistent structure.
+
+**Structure**:
+```markdown
+---
+name: skill-name
+description: Brief description
+[optional-platform-specific-fields]
+---
+
+# Skill Title
+
+Instructions and content...
+```
+
+**Benefits**:
+- Machine-readable metadata (frontmatter)
+- Human-readable documentation (markdown)
+- Extensible (optional fields for platform-specific features)
+
+### 4. Sub-Agent Orchestration Pattern
+
+**Pattern**: Skills orchestrate specialized sub-agents for complex workflows.
+
+**Implementation** (`research-codebase`, `create-spec`):
+- Main skill acts as coordinator
+- Spawns parallel sub-agent tasks
+- Waits for completion
+- Synthesizes results
+
+**Sub-agents**:
+- `codebase-locator` - Find WHERE
+- `codebase-analyzer` - Understand HOW
+- `codebase-pattern-finder` - Find patterns
+- `codebase-research-locator` - Discover documents
+- `codebase-research-analyzer` - Extract insights
+- `codebase-online-researcher` - External resources
+
+**Benefits**:
+- Separation of concerns
+- Parallel execution
+- Specialized expertise per agent
+- Reduced context usage
+
+### 5. Documentation-Only Role Pattern
+
+**Pattern**: Sub-agents strictly document without evaluation.
+
+**Implementation**:
+- "Documentarian, not critic" principle
+- "Document what IS, not what SHOULD BE"
+- No recommendations or improvements
+- No bug identification
+
+**Enforcement** (`research-codebase/SKILL.md`):
+```markdown
+- **CRITICAL**: You and all sub-agents are documentarians, not evaluators
+- **REMEMBER**: Document what IS, not what SHOULD BE
+- **NO RECOMMENDATIONS**: Only describe the current state of the codebase
+```
+
+**Benefits**:
+- Objective, factual documentation
+- Avoids premature optimization
+- Separates analysis from prescription
+
+### 6. Progressive Disclosure Pattern
+
+**Pattern**: Load reference materials on-demand based on task complexity.
+
+**Implementation** (`prompt-engineer`):
+- Three reference files (601 total lines)
+- Load only relevant references per workflow step
+- Technique selection matrix guides choice
+
+**Benefits**:
+- Efficient context usage
+- Avoids overwhelming with unnecessary information
+- Scales from simple to complex tasks
+
+### 7. Conventional Commits Pattern
+
+**Pattern**: Standardize commit messages using Conventional Commits 1.0.0 specification.
+
+**Implementation** (`gh-commit`, `sl-commit`):
+- Pre-commit checks
+- Automatic staging
+- Multi-commit detection
+- AI authorship attribution
+- Breaking change indicators
+
+**Benefits**:
+- Automated changelog generation
+- Semantic versioning automation
+- Clear commit history
+- Teammate/stakeholder communication
+
+---
+
+## Key Differences Between Configurations
+
+### Content Differences
+
+**Only one difference found**:
+
+`.claude/skills/research-codebase/SKILL.md` includes additional frontmatter fields:
+```yaml
+aliases: [research]
+argument-hint: "<research-question>"
+required-arguments: [research-question]
+```
+
+These fields are NOT present in `.github/skills/research-codebase/SKILL.md` or `.opencode/skills/research-codebase/SKILL.md`.
+
+**Interpretation**: Claude Code supports skill aliases and argument hints, while GitHub Copilot and OpenCode may not have this feature yet.
+
+### Directory Differences
+
+**None**. All three configurations have identical directory structures and file names.
+
+---
+
+## SCM-Specific Skills
+
+### GitHub Skills (gh-*)
+1. **gh-commit** - Git commit with Conventional Commits
+2. **gh-create-pr** - Create GitHub pull request
+
+### Sapling Skills (sl-*)
+1. **sl-commit** - Sapling commit with Conventional Commits
+2. **sl-submit-diff** - Submit Phabricator diffs
+
+**Deployment Strategy**:
+- Included in project repository (`.github/skills/`, `.claude/skills/`, `.opencode/skills/`)
+- Included in npm package (`package.json:28`)
+- **Excluded from global config** (`~/.atomic`) via `install.sh:158-160`
+- Configured per-project via `atomic init`
+
+**Rationale**: Projects use either Git or Sapling, not both. Excluding from global config prevents conflicts.
+
+---
+
+## Agent Configurations
+
+All three platforms share identical agent configurations:
+
+**Location**: `.github/agents/`, `.claude/agents/`, `.opencode/agents/`
+
+**Agents** (9 total):
+1. **codebase-analyzer.md** - Analyze implementation details
+2. **codebase-locator.md** - Locate files/directories/components
+3. **codebase-online-researcher.md** - Research external documentation
+4. **codebase-pattern-finder.md** - Find similar implementations/patterns
+5. **codebase-research-analyzer.md** - Analyze research documents
+6. **codebase-research-locator.md** - Discover research documents
+7. **debugger.md** - Debug errors and failures
+8. **reviewer.md** - Review code changes
+9. **worker.md** - Implement single task from list
+
+**Deployment**: Copied to `~/.atomic/.claude/agents/`, `~/.atomic/.opencode/agents/`, `~/.atomic/.copilot/agents/`
+
+---
+
+## Configuration Files
+
+### Per-Platform Configuration
+
+1. **Claude Code**: `.claude/settings.json`, `~/.atomic/.claude/settings.json`
+2. **OpenCode**: `.opencode/opencode.json`, `~/.atomic/.opencode/opencode.json`
+3. **GitHub Copilot**: `.github/mcp-config.json`, `~/.atomic/.copilot/mcp-config.json`
+
+### Global Configuration
+
+- **MCP Configuration**: `.mcp.json`, `~/.atomic/.mcp.json`
+- **Atomic Settings**: `~/.atomic/settings.json`
+
+---
+
+## Installation Flow
+
+**Install.sh execution flow**:
+
+1. **Detect platform**: `detect_platform()` (Linux, macOS, Windows)
+2. **Get version**: Latest from GitHub API or user-specified
+3. **Download assets**:
+   - Binary: `atomic-{platform}` (Linux-x64, Darwin-arm64, etc.)
+   - Config: `atomic-config.tar.gz`
+   - Checksums: `checksums.txt`
+4. **Verify checksums**: SHA-256 verification
+5. **Install binary**: `$BIN_DIR/atomic` (default: `~/.local/bin/atomic`)
+6. **Extract config**: `$DATA_DIR` (default: `~/.local/share/atomic`)
+7. **Sync global configs**: `sync_global_agent_configs "$DATA_DIR"`
+   - Copy `.claude/` → `~/.atomic/.claude/`
+   - Copy `.opencode/` → `~/.atomic/.opencode/`
+   - Copy `.github/` → `~/.atomic/.copilot/`
+   - Copy `.mcp.json` → `~/.atomic/.mcp.json`
+   - **Remove SCM skills**: `rm -rf $ATOMIC_HOME/.*/skills/{gh-,sl-}*`
+   - **Remove GitHub-specific**: `rm -rf $ATOMIC_HOME/.copilot/workflows`, `rm -f $ATOMIC_HOME/.copilot/dependabot.yml`
+8. **Update PATH**: Add `$BIN_DIR` to shell config (bash, zsh, fish)
+
+---
+
+## Related Research
+
+- Research directory structure: `research/docs/`, `research/tickets/`, `research/notes/`
+- Naming convention: `YYYY-MM-DD-[XXXX-]description.md`
+- YAML frontmatter pattern for metadata
+- GitHub permalinks for persistent references
+
+---
+
+## Open Questions
+
+None. All areas of the skills directory structure have been documented.
+
+---
+
+## References
+
+### Code References
+
+- `package.json:22-31` - Files field with skills inclusion
+- `install.sh:144-165` - sync_global_agent_configs function
+- `install.sh:233-234` - Function invocation during installation
+- `.github/skills/` - GitHub Copilot skills directory
+- `.claude/skills/` - Claude Code skills directory
+- `.opencode/skills/` - OpenCode AI skills directory
+- `~/.atomic/.claude/skills/` - Global Claude skills
+- `~/.atomic/.opencode/skills/` - Global OpenCode skills
+- `~/.atomic/.copilot/skills/` - Global Copilot skills
+
+### Skill Files (All in three locations)
+
+1. `create-spec/SKILL.md` (12,627 bytes)
+2. `explain-code/SKILL.md` (7,339 bytes)
+3. `frontend-design/SKILL.md` (3,957 bytes)
+4. `gh-commit/SKILL.md` (13,675 bytes)
+5. `gh-create-pr/SKILL.md` (399 bytes)
+6. `init/SKILL.md` (4,075 bytes)
+7. `prompt-engineer/SKILL.md` (8,360 bytes)
+   - `prompt-engineer/references/advanced_patterns.md` (271 lines)
+   - `prompt-engineer/references/core_prompting.md` (137 lines)
+   - `prompt-engineer/references/quality_improvement.md` (193 lines)
+8. `research-codebase/SKILL.md` (11,206 bytes)
+9. `sl-commit/SKILL.md` (2,091 bytes)
+10. `sl-submit-diff/SKILL.md` (1,959 bytes)
+11. `testing-anti-patterns/SKILL.md` (5,102 bytes)
+
+### Configuration References
+
+- `.claude/settings.json` - Claude Code configuration
+- `.opencode/opencode.json` - OpenCode configuration
+- `.github/mcp-config.json` - GitHub Copilot MCP configuration
+- `.mcp.json` - Global MCP configuration
+
+---
+
+## Conclusion
+
+The Atomic CLI project demonstrates a sophisticated multi-platform skills architecture that maintains consistency across GitHub Copilot, Claude Code, and OpenCode AI. The skills provide comprehensive capabilities for code development, documentation, research, and repository management. The separation of global and project-scoped skills, combined with the documentarian-focused sub-agent pattern, creates a powerful and maintainable system for agent-assisted software development.
+
+The nearly-identical implementation across platforms (with only one Claude-specific frontmatter difference) suggests a design philosophy of platform-agnostic skills that can be deployed universally, with platform-specific features layered on top through optional frontmatter fields.
diff --git a/research/docs/2026-02-25-ui-workflow-coupling.md b/research/docs/2026-02-25-ui-workflow-coupling.md
new file mode 100644
index 0000000000..8f3ed25fba
--- /dev/null
+++ b/research/docs/2026-02-25-ui-workflow-coupling.md
@@ -0,0 +1,541 @@
+# UI-Workflow Coupling: Technical Documentation
+
+**Date:** 2026-02-25
+**Scope:** How the UI layer (`src/ui/`) connects to the workflow system, with focus on command registration, dispatch, Ralph-specific code, and agent discovery.
+
+---
+
+## 1. Chat UI Entry Point (`src/ui/chat.tsx`)
+
+### Overview
+
+The chat UI is a React component (`ChatApp`) built on OpenTUI that provides a terminal-based chat interface. It handles slash command parsing, workflow state management, and Ralph-specific task list persistence. The file is large (~6100+ lines) and serves as the central integration point between user input and the command/workflow systems.
+
+### Command Dispatch Flow
+
+#### `executeCommand` (line 3516-4235)
+
+The `executeCommand` callback is the primary mechanism for invoking any registered command from the UI.
+
+1. **Registry lookup** (line 3524-3525): Calls `globalRegistry.get(commandName)` to find a `CommandDefinition` by name or alias. If not found, a system error message is shown (line 3529).
+
+2. **CommandContext construction** (lines 3540-3971): Builds a `CommandContext` object from the current React state, providing commands with access to:
+   - `session`: the active SDK session via `getSession?.() ?? null` (line 3557)
+   - `state`: a snapshot of `CommandContextState` assembled from `workflowState` fields (lines 3541-3553)
+   - `addMessage`: adds a chat message to the UI (line 3559)
+   - `setStreaming`: controls the streaming spinner state (line 3560)
+   - `sendMessage`: delegates to `sendMessageRef.current` to send visible messages (lines 3561-3565)
+   - `sendSilentMessage`: sends to the agent without a user-visible message, creates a streaming placeholder, handles stream generation tracking (lines 3567-3665)
+   - `spawnSubagent`: serial sub-agent spawning via `sendSilentMessage` with hidden content (lines 3808-3852)
+   - `spawnSubagentParallel`: parallel sub-agent spawning via `SubagentGraphBridge` (lines 3853-3897)
+   - `streamAndWait`: returns a `Promise<StreamResult>` resolved when streaming completes or is interrupted (lines 3899-3909)
+   - `waitForUserInput`: returns a `Promise<string>` resolved when user types input (lines 3911-3914)
+   - `clearContext`: destroys session, clears messages, preserves todo items and ralph session state (lines 3916-3932)
+   - `setTodoItems`: normalizes and sorts tasks topologically, updates both ref and state (lines 3934-3937)
+   - `setRalphSessionDir`: synchronizes ref and state (lines 3939-3941)
+   - `setRalphSessionId`: synchronizes ref and state (lines 3943-3945)
+   - `setRalphTaskIds`: updates ref only (lines 3947-3948)
+   - `updateWorkflowState`: partial state update (lines 3950-3951)
+   - `agentType`, `modelOps`, `getModelDisplayInfo`, MCP toggles (lines 3953-3970)
+
+3. **Delayed spinner** (lines 3973-4013): A 250ms timer shows a loading spinner if the command hasn't completed yet. Uses `flushSync` to force an immediate render.
+
+4. **Command execution** (line 4017): `await Promise.resolve(command.execute(args, context))` -- handles both sync and async commands.
+
+5. **State update application** (lines 4072-4091): If `result.stateUpdate` is present, the workflow state is merged field-by-field via `updateWorkflowState`. The `ralphConfig` field is explicitly handled at line 4085.
+
+#### Input Parsing (lines 5649-5749)
+
+The `handleSubmit` callback processes user input:
+
+1. **Slash command detection** (line 5710): `parseSlashCommand(trimmedValue)` from `src/ui/commands/index.ts` checks if input starts with `/` and splits into name + args.
+2. **Ralph panel dismissal** (lines 5712-5720): On Copilot, sending a non-ralph slash command while `ralphSessionDirRef.current` is set clears all ralph state.
+3. **Command execution** (line 5726): `void executeCommand(parsed.name, parsed.args, "input")`.
+4. **waitForUserInput resolution** (lines 5730-5737): If a workflow is waiting for user input (after Ctrl+C), the user's text resolves the pending promise.
+5. **Non-command ralph dismissal** (lines 5740-5748): On Copilot, sending a non-ralph message also clears ralph state.
+
+#### Initial Prompt Handling (lines 5599-5641)
+
+The `useEffect` at line 5601 handles auto-submission of initial prompts:
+
+1. Slash commands are routed through `parseSlashCommand` and `executeCommand` (lines 5609-5613).
+2. `@agent` mentions are detected and dispatched via `executeCommand` (lines 5617-5627).
+3. Regular messages go to `sendMessage` (line 5638).
+
+### Ralph-Specific Code in the UI Layer
+
+The chat UI contains extensive Ralph-specific state management:
+
+#### State Variables (lines 1841-1849)
+
+```typescript
+const [ralphSessionDir, setRalphSessionDir] = useState<string | null>(null);
+const ralphSessionDirRef = useRef<string | null>(null);
+const [ralphSessionId, setRalphSessionId] = useState<string | null>(null);
+const ralphSessionIdRef = useRef<string | null>(null);
+const ralphTaskIdsRef = useRef<Set<string>>(new Set());
+```
+
+Both state and refs are maintained because refs are needed for synchronous access inside stream callbacks, while state triggers React re-renders.
+
+#### `isRalphTaskUpdate` Guard (lines 2104-2108)
+
+```typescript
+const isRalphTaskUpdate = useCallback((
+  todos: ..., previousTodos?: ...
+): boolean => {
+  return hasRalphTaskIdOverlap(todos, ralphTaskIdsRef.current, previousTodos);
+}, []);
+```
+
+This helper calls `hasRalphTaskIdOverlap` from `src/ui/utils/ralph-task-state.ts:52` to determine if incoming `TodoWrite` payloads originate from the Ralph workflow (share task IDs with the planning phase). This guards against sub-agent TodoWrite calls overwriting Ralph's task state.
+
+#### TodoWrite Filtering During Ralph Workflows
+
+In the tool completion handlers (lines 2328-2346, 2450-2468):
+
+- `taskStreamPinned` is set to `Boolean(ralphSessionIdRef.current)` (lines 2328, 2450).
+- `shouldApplyTodoState` gates whether TodoWrite updates are applied to the in-memory task state: only true when either no ralph workflow is active or the update is a ralph update (lines 2333, 2455).
+- TodoWrite calls are never persisted to `tasks.json` during an active ralph workflow (lines 2339-2346, 2461-2468). The ralph workflow command handler (`workflow-commands.ts`) is the sole owner of `tasks.json`.
+
+#### Auto-Approve During Workflow (lines 2762-2766, 2831-2837)
+
+When `workflowState.workflowActive` is true:
+- Permission requests are auto-approved with the first option value (line 2764).
+- `AskUserQuestion` events are auto-responded with the first option label (line 2833).
+
+#### Workflow Cleanup on End (lines 2720-2728)
+
+When `workflowState.workflowActive` transitions to false while `ralphSessionDir` is still set:
+1. `syncTerminalTaskStateFromSession` reads final `tasks.json` from disk (line 2699-2718).
+2. Tasks are reconciled with in-memory state via `preferTerminalTaskItems` (line 2709).
+3. Ralph state is cleared: `setRalphSessionDir(null)`, `setRalphSessionId(null)` (lines 2723-2726).
+
+#### Ctrl+C / Workflow Cancellation (lines 4480-4528, 4590-4614)
+
+During streaming:
+- Single Ctrl+C resolves the `streamCompletionResolver` with `wasInterrupted: true` (line 4498).
+- Double Ctrl+C during workflow: resolves with `wasCancelled: true` (line 4496) and calls `updateWorkflowState({ workflowActive: false, ... })` (line 4506).
+- When textarea is empty and not streaming, double Ctrl+C terminates the workflow (line 4602-4608); outside workflow, it exits the app (line 4611).
+
+#### Task List Panel in MessageBubble (lines 1534-1540, 1577-1583)
+
+The `TaskListPanel` component is rendered when `isLast && ralphSessionDir && showTodoPanel`:
+- In user messages: below the message content (line 1535).
+- In assistant messages: below `MessageBubbleParts` (line 1578).
+
+When `ralphSessionDir` is set, inline task rendering is disabled (`inlineTasksEnabled={!ralphSessionDir}` at line 5906), favoring the persistent panel.
+
+#### Visual Workflow Indicators (lines 6016, 6104-6131)
+
+- Input border color changes to `themeColors.accent` when `workflowState.workflowActive` (line 6016).
+- A footer bar shows "workflow" label with interrupt/enqueue/exit hints (lines 6104-6131).
+
+#### `WorkflowChatState` Interface (lines 848-891)
+
+Contains a `ralphConfig` field (lines 886-890):
+```typescript
+ralphConfig?: {
+  userPrompt: string | null;
+  sessionId?: string;
+};
+```
+
+This is set by the `/ralph` command handler and merged into `workflowState` via the `stateUpdate.ralphConfig` path at line 4085.
+
+### SubagentGraphBridge Initialization (lines 3033-3077)
+
+When `createSubagentSession` is available:
+1. A lightweight `CodingAgentClient` wrapper is created (lines 3042-3063) using the current `agentType`.
+2. `WorkflowSDK.init()` is called (line 3065) from `src/workflows/graph/sdk.ts`.
+3. The `SubagentGraphBridge` is obtained via `sdk.getSubagentBridge()` (line 3070) and stored in `subagentBridgeRef`.
+4. This bridge is consumed by `spawnSubagentParallel` in the `CommandContext` (line 3854).
+
+---
+
+## 2. UI Index / App Initialization (`src/ui/index.ts`)
+
+### Overview
+
+`src/ui/index.ts` exports `startChatUI()`, the primary entry point for launching the terminal chat interface. It orchestrates command registration, renderer creation, session management, and event wiring.
+
+### Command Initialization (line 2022)
+
+```typescript
+await initializeCommandsAsync();
+```
+
+This is called inside `startChatUI` before rendering the React tree. The function (from `src/ui/commands/index.ts:87`) registers commands in this order:
+
+1. `registerBuiltinCommands()` -- help, theme, clear, compact, etc. (line 91)
+2. `await loadWorkflowsFromDisk()` -- discovers `.ts` files from `.atomic/workflows/` and `~/.atomic/workflows/` (line 94)
+3. `registerWorkflowCommands()` -- converts `WorkflowMetadata` into `CommandDefinition` objects and registers them in `globalRegistry` (line 95)
+4. `await discoverAndRegisterDiskSkills()` -- skills from `.claude/skills/`, `.github/skills/`, etc. (line 99)
+5. `await registerAgentCommands()` -- agents from `.claude/agents/`, `.opencode/agents/`, `.github/agents/`, etc. (line 103)
+
+### Capabilities System Prompt (lines 2024-2035)
+
+After command initialization, `buildCapabilitiesSystemPrompt()` (line 2027, defined at line 52-96) iterates over `globalRegistry.all()` and builds a text section for each command category: builtins, skills, agents, and workflows. This text is appended to the session's `systemPrompt` so the LLM knows about available capabilities.
+
+Workflow commands are included in the prompt at lines 89-93:
+```typescript
+const workflows = allCommands.filter((c) => c.category === "workflow");
+```
+
+### ChatUIConfig (lines 105-130)
+
+The `workflowEnabled` boolean (line 129) is passed through from CLI args to the `startChatUI` function. It is used only for telemetry tracking (line 375), not for conditional workflow registration.
+
+### Renderer and React Setup (lines 2042-2056)
+
+The `createCliRenderer` and `createRoot` calls set up the OpenTUI environment. The `ChatApp` component is rendered with handler callbacks for tool events, permission requests, parallel agents, etc. Command execution happens entirely within the React component tree via `executeCommand`.
+
+---
+
+## 3. Command Registry (`src/ui/commands/registry.ts`)
+
+### Overview
+
+The registry is a `CommandRegistry` class (line 303) backed by two maps: `commands` (name -> definition) and `aliases` (alias -> primary name). A global singleton `globalRegistry` is exported at line 534.
+
+### `CommandContext` Interface (lines 75-168)
+
+The `CommandContext` interface is the bridge between the UI and command handlers. It references workflow/Ralph-specific features:
+
+| Field | Line | Description |
+|---|---|---|
+| `setRalphSessionDir` | 135 | Sets the Ralph workflow session directory for the persistent task list panel |
+| `setRalphSessionId` | 139 | Sets the Ralph workflow session ID for the persistent task list panel |
+| `setRalphTaskIds` | 145 | Sets known Ralph task IDs from the planning phase; guards TodoWrite persistence |
+| `updateWorkflowState` | 155 | Updates workflow state (workflowActive, workflowType, etc.) |
+| `streamAndWait` | 122 | Returns `Promise<StreamResult>` for multi-step workflow coordination |
+| `waitForUserInput` | 151 | Yields control to user after stream interruption |
+| `clearContext` | 127 | Destroys session and clears messages, preserving todoItems |
+| `spawnSubagent` | 101 | Serial sub-agent spawning |
+| `spawnSubagentParallel` | 110 | Parallel sub-agent spawning via `SubagentGraphBridge` |
+
+### `CommandContextState` Interface (lines 185-215)
+
+Contains workflow execution state fields:
+
+| Field | Line | Description |
+|---|---|---|
+| `workflowActive` | 191 | Whether a workflow is currently active |
+| `workflowType` | 193 | Current workflow type string |
+| `initialPrompt` | 195 | Initial prompt that started the workflow |
+| `currentNode` | 197 | Current node in the workflow graph |
+| `iteration` | 199 | Current iteration number (1-based) |
+| `maxIterations` | 201 | Maximum allowed iterations |
+| `featureProgress` | 203 | Feature completion progress |
+| `pendingApproval` | 205 | Whether spec approval is pending |
+| `specApproved` | 207 | Whether spec was approved |
+| `feedback` | 209 | Feedback from spec rejection |
+| `ralphConfig` | 211-214 | Ralph-specific config with `userPrompt` and `sessionId` |
+
+### `CommandResult` Interface (lines 220-251)
+
+Key workflow-relevant fields:
+
+| Field | Line | Description |
+|---|---|---|
+| `stateUpdate` | 227 | Partial `CommandContextState` to merge into workflow state |
+| `clearMessages` | 228 | If true, clear all chat messages |
+| `destroySession` | 230 | If true, destroy the current session |
+
+### `CommandCategory` Type (line 256)
+
+```typescript
+export type CommandCategory = "builtin" | "workflow" | "skill" | "agent" | "file" | "folder";
+```
+
+### Sort Priority (lines 475-484)
+
+Commands are sorted with workflow commands having the highest priority (0), followed by skill (1), agent (2), builtin (3), folder (4), file (5).
+
+---
+
+## 4. Workflow Commands (`src/ui/commands/workflow-commands.ts`)
+
+### Overview
+
+This file defines the workflow command system: built-in workflow definitions, custom workflow loading from disk, and the Ralph-specific command handler. The `/ralph` command is the only built-in workflow, implementing an autonomous implementation loop with planning, worker dispatch, review, and fix phases.
+
+### `WorkflowMetadata` Interface (lines 110-131)
+
+```typescript
+export interface WorkflowMetadata {
+  name: string;
+  description: string;
+  aliases?: string[];
+  defaultConfig?: Record<string, unknown>;
+  version?: string;
+  minSDKVersion?: string;
+  stateVersion?: number;
+  migrateState?: WorkflowStateMigrator;
+  source?: "builtin" | "global" | "local";
+  argumentHint?: string;
+}
+```
+
+The `source` field indicates where a workflow was discovered: `"builtin"` (hardcoded), `"global"` (`~/.atomic/workflows/`), or `"local"` (`.atomic/workflows/`).
+
+### Built-In Workflow Definitions (lines 520-531)
+
+A single built-in workflow is defined:
+
+```typescript
+const BUILTIN_WORKFLOW_DEFINITIONS: WorkflowMetadata[] = [
+  {
+    name: "ralph",
+    description: "Start autonomous implementation workflow",
+    aliases: ["loop"],
+    version: "1.0.0",
+    minSDKVersion: VERSION,
+    stateVersion: 1,
+    argumentHint: '"<prompt-or-spec-path>"',
+    source: "builtin",
+  },
+];
+```
+
+The `"loop"` alias allows `/loop` to invoke the same command as `/ralph`.
+
+### `createWorkflowCommand()` Dispatch (lines 543-595)
+
+```typescript
+function createWorkflowCommand(metadata: WorkflowMetadata): CommandDefinition {
+  if (metadata.name === "ralph") {
+    return createRalphCommand(metadata);
+  }
+  // Generic path...
+}
+```
+
+**Routing logic:** The function checks `metadata.name === "ralph"` at line 545. If true, it delegates to `createRalphCommand()`. Otherwise, it returns a generic workflow `CommandDefinition`.
+
+#### Generic Path (lines 549-594)
+
+For non-Ralph workflows, the generic path:
+
+1. Checks `context.state.workflowActive` -- if another workflow is active, returns failure (lines 557-561).
+2. Requires a non-empty prompt (lines 565-570).
+3. Adds a system message indicating workflow start (lines 575-578).
+4. Returns a `stateUpdate` setting `workflowActive: true`, `workflowType`, and `initialPrompt` (lines 583-591).
+
+This `stateUpdate` triggers the auto-start `useEffect` in `chat.tsx` (lines 2538-2689) which begins streaming the initial prompt.
+
+#### Ralph-Specific Path: `createRalphCommand()` (lines 597-793)
+
+The Ralph command handler is an `async` execute function that runs the entire workflow graph inline:
+
+1. **Guard** (line 608): Checks `context.state.workflowActive`.
+2. **Argument parsing** (lines 615-623): `parseRalphArgs(args)` at line 82 validates that a non-empty prompt is provided.
+3. **Session initialization** (lines 631-635):
+   - `sessionId = crypto.randomUUID()` (line 631)
+   - `sessionDir = getWorkflowSessionDir(sessionId)` from `src/workflows/session.ts` (line 632)
+   - `initWorkflowSession("ralph", sessionId)` is called fire-and-forget (line 633)
+4. **State update** (lines 637-641): Sets `workflowActive: true`, `workflowType: metadata.name`, and `ralphConfig: { sessionId, userPrompt }`.
+5. **Initial state creation** (lines 654-658): `createRalphState(sessionId, {...})` from `src/workflows/ralph/state.ts`.
+6. **Bridge adapter** (lines 661-676): Wraps `context.spawnSubagentParallel!()` in a bridge object with `spawn()` and `spawnParallel()` methods.
+7. **Subagent registry** (lines 679-687): Creates a `SubagentTypeRegistry` from `src/workflows/graph/subagent-registry.ts`, populated with `discoverAgentInfos()` from `src/ui/commands/agent-commands.ts:259`.
+8. **Graph compilation** (lines 690-695): `createRalphWorkflow()` from `src/workflows/ralph/graph.ts` produces a compiled graph. The bridge and registry are injected into `compiled.config.runtime`.
+9. **Graph execution** (lines 702-741): `streamGraph(compiled, { initialState })` from `src/workflows/graph/compiled.ts` yields steps. For each step:
+   - Node phase descriptions are shown via `getNodePhaseDescription()` (line 57-69).
+   - Tasks are persisted via `saveTasksToActiveSession()` (line 719).
+   - `context.setTodoItems()` updates the UI (line 723).
+   - On the first step with tasks, `context.setRalphSessionDir()`, `context.setRalphSessionId()`, and `context.setRalphTaskIds()` are called (lines 727-738).
+10. **Completion** (lines 744-759): Sets `workflowActive: false`.
+11. **Error handling** (lines 760-790): Catches "Workflow cancelled" for silent exit; other errors return failure with `workflowActive: false`.
+
+### Custom Workflow Discovery: `loadWorkflowsFromDisk()` (lines 401-471)
+
+1. **Discovery** (line 402): Calls `discoverWorkflowFiles()` (line 343-372) which searches:
+   - `.atomic/workflows` (local, index 0 -> `"local"` source)
+   - `~/.atomic/workflows` (global, index 1 -> `"global"` source)
+   
+   Both are defined in `CUSTOM_WORKFLOW_SEARCH_PATHS` at line 268-273.
+
+2. **Path expansion** (line 281-293): `expandPath()` resolves `~` to `$HOME` and relative paths to `process.cwd()`.
+
+3. **File filtering** (lines 357-358): Only `.ts` files are discovered.
+
+4. **Dynamic import** (line 409): Each discovered `.ts` file is imported via `await import(path)`.
+
+5. **Metadata extraction** (lines 412-436): Reads `module.name` (falls back to filename), `module.description`, `module.aliases`, `module.defaultConfig`, `module.version`, `module.minSDKVersion`, `module.stateVersion`, `module.migrateState`.
+
+6. **Version validation** (lines 438-453): If `minSDKVersion` is specified, it is checked against the current `VERSION` via `isWorkflowMinSdkNewerThanCurrent()` (line 316-333).
+
+7. **Priority** (lines 417-419): Names are tracked in `loadedNames`; local workflows take priority over global ones (first-discovered wins).
+
+### Workflow Composition: `getAllWorkflows()` (lines 477-506)
+
+Returns a merged list:
+1. Dynamically loaded workflows first (local > global).
+2. Built-in workflows last (lowest priority).
+
+Names are deduplicated; first occurrence wins.
+
+### Registration: `registerWorkflowCommands()` (lines 899-907)
+
+Calls `getWorkflowCommands()` (line 872-874) which maps `getAllWorkflows()` through `createWorkflowCommand()`, then registers each with `globalRegistry` (idempotent via `has()` check).
+
+### Session Management (lines 137-248)
+
+- `activeSessions` map (line 138): Tracks active `WorkflowSession` objects keyed by session ID.
+- `saveTasksToActiveSession()` (lines 200-235): Atomically writes `tasks.json` to the session directory using `atomicWrite()` (line 168).
+- `watchTasksJson()` (lines 799-862): File watcher for `tasks.json` changes, used by the `TaskListPanel` component.
+
+---
+
+## 5. Agent Commands (`src/ui/commands/agent-commands.ts`)
+
+### Overview
+
+Agent commands are discovered from config directories and registered as `@`-prefixed mention targets and `/`-prefixed slash commands. They are lightweight wrappers that delegate actual execution to the underlying SDK's native sub-agent dispatch.
+
+### Discovery Paths (lines 34-52)
+
+**Project-local** (highest priority):
+- `.claude/agents`
+- `.opencode/agents`
+- `.github/agents`
+
+**User-global** (lower priority):
+- `~/.claude/agents`
+- `~/.opencode/agents`
+- `~/.copilot/agents`
+- `~/.atomic/.claude/agents`
+- `~/.atomic/.opencode/agents`
+- `~/.atomic/.copilot/agents`
+
+### `AgentInfo` Interface (lines 81-90)
+
+```typescript
+export interface AgentInfo {
+  name: string;
+  description: string;
+  source: AgentSource;  // "project" | "user"
+  filePath: string;
+}
+```
+
+### Discovery: `discoverAgentInfos()` (lines 259-278)
+
+1. `discoverAgentFiles()` (line 179-197) scans all paths, returning `DiscoveredAgentFile` objects.
+2. For each file, `parseAgentInfoLight()` (line 206-225) reads the `.md` file, parses YAML frontmatter via `parseMarkdownFrontmatter()` from `src/utils/markdown.ts`, and extracts `name` and `description`.
+3. Deduplication uses `shouldAgentOverride()` (lines 238-248): project agents (priority 2) override user agents (priority 1).
+
+### Command Creation: `createAgentCommand()` (lines 305-331)
+
+The execute handler branches on `context.agentType`:
+
+- **OpenCode** (lines 315-319): Calls `context.sendSilentMessage(task, { agent: agent.name, isAgentOnlyStream: true })`. The `agent` option triggers OpenCode's `AgentPartInput` dispatch.
+- **Claude/Copilot** (lines 321-326): Calls `context.sendSilentMessage(instruction, { isAgentOnlyStream: true })` where `instruction` is a prompt steering the model to use the `Task` tool for sub-agent dispatch.
+
+### Registration: `registerAgentCommands()` (lines 341-358)
+
+Called during `initializeCommandsAsync()`. Iterates discovered agents:
+- If a command with the same name already exists as an "agent" category, it is unregistered first (line 349).
+- Non-agent commands with the same name are not overridden (line 351).
+
+### Usage by Workflow Commands
+
+`discoverAgentInfos()` is imported and called by `createRalphCommand()` at line 680 to populate the `SubagentTypeRegistry` with available agent types. This allows the Ralph workflow graph to know which sub-agents are available for task dispatch.
+
+---
+
+## 6. Data Flow Summary
+
+### Command Registration Flow
+
+```
+startChatUI() [src/ui/index.ts:306]
+  -> initializeCommandsAsync() [src/ui/commands/index.ts:87]
+      -> registerBuiltinCommands()
+      -> loadWorkflowsFromDisk() -> discoverWorkflowFiles() -> dynamic import .ts
+      -> registerWorkflowCommands() -> getAllWorkflows() -> createWorkflowCommand() -> globalRegistry.register()
+      -> discoverAndRegisterDiskSkills()
+      -> registerAgentCommands() -> discoverAgentInfos() -> createAgentCommand() -> globalRegistry.register()
+  -> buildCapabilitiesSystemPrompt() [appends to sessionConfig.systemPrompt]
+  -> createRoot() + render ChatApp
+```
+
+### Slash Command Execution Flow
+
+```
+User types "/ralph build a snake game" and presses Enter
+  -> handleSubmit() [chat.tsx:5649]
+      -> parseSlashCommand() [commands/index.ts:148] -> { name: "ralph", args: "build a snake game" }
+      -> addMessage("user", ...) [chat.tsx:5724]
+      -> executeCommand("ralph", "build a snake game", "input") [chat.tsx:3516]
+          -> globalRegistry.get("ralph") [chat.tsx:3525]
+          -> Build CommandContext [chat.tsx:3556-3971]
+          -> command.execute(args, context) [chat.tsx:4017]
+              -> createRalphCommand().execute [workflow-commands.ts:604]
+                  -> parseRalphArgs(args) [workflow-commands.ts:82]
+                  -> context.updateWorkflowState({ workflowActive: true, ... })
+                  -> context.setStreaming(true)
+                  -> createRalphState() -> createRalphWorkflow() -> streamGraph()
+                  -> For each step: context.setTodoItems(), saveTasksToActiveSession()
+                  -> On first tasks: context.setRalphSessionDir(), setRalphSessionId(), setRalphTaskIds()
+                  -> On completion: return { stateUpdate: { workflowActive: false } }
+          -> Apply result.stateUpdate to workflowState [chat.tsx:4072-4091]
+```
+
+### Ralph State Lifecycle
+
+```
+/ralph invocation:
+  1. createRalphCommand sets workflowActive=true, ralphConfig={sessionId, userPrompt}
+  2. context.setRalphSessionDir/Id/TaskIds called once first tasks arrive
+  3. TaskListPanel renders when ralphSessionDir is set
+  4. TodoWrite filtering guards prevent sub-agent overwrites
+  5. Permission requests auto-approved during workflowActive
+  6. On completion: workflowActive=false returned via stateUpdate
+  7. useEffect detects !workflowActive && ralphSessionDir -> syncTerminalTaskStateFromSession()
+  8. Ralph state cleared: ralphSessionDir=null, ralphSessionId=null
+```
+
+---
+
+## 7. Key Coupling Points
+
+### UI -> Workflow Layer
+
+| Coupling Point | UI File:Line | Workflow File:Line |
+|---|---|---|
+| `createRalphWorkflow()` import | `workflow-commands.ts:36` | `workflows/ralph/graph.ts` |
+| `createRalphState()` import | `workflow-commands.ts:37` | `workflows/ralph/state.ts` |
+| `streamGraph()` import | `workflow-commands.ts:38` | `workflows/graph/compiled.ts` |
+| `SubagentTypeRegistry` import | `workflow-commands.ts:43` | `workflows/graph/subagent-registry.ts` |
+| `SubagentGraphBridge` import | `chat.tsx:39` | `workflows/graph/subagent-bridge.ts` |
+| `WorkflowSDK` import | `chat.tsx:42` | `workflows/graph/sdk.ts` |
+| `initWorkflowSession` import | `workflow-commands.ts:31` | `workflows/session.ts` |
+| `getWorkflowSessionDir` import | `workflow-commands.ts:31` | `workflows/session.ts` |
+| `BaseState` type import | `workflow-commands.ts:34` | `workflows/graph/types.ts` |
+
+### Workflow -> UI Layer (via CommandContext)
+
+The workflow graph has no direct imports from the UI layer. All communication flows through the `CommandContext` interface:
+
+- Task updates: `context.setTodoItems()`, `context.setRalphSessionDir()`, `context.setRalphSessionId()`, `context.setRalphTaskIds()`
+- Status messages: `context.addMessage()`
+- Sub-agent dispatch: `context.spawnSubagentParallel()`
+- Streaming control: `context.setStreaming()`
+- State propagation: `context.updateWorkflowState()`, `result.stateUpdate`
+
+### Ralph-Specific Fields in Shared Interfaces
+
+The following Ralph-specific fields exist in the shared command registry types:
+
+- `CommandContext.setRalphSessionDir` (registry.ts:135)
+- `CommandContext.setRalphSessionId` (registry.ts:139)
+- `CommandContext.setRalphTaskIds` (registry.ts:145)
+- `CommandContextState.ralphConfig` (registry.ts:211-214)
+- `WorkflowChatState.ralphConfig` (chat.tsx:886-890)
+
+### Agent Discovery Cross-Usage
+
+`discoverAgentInfos()` from `agent-commands.ts:259` is used in two contexts:
+1. **UI registration** (agent-commands.ts:342): Registers agent commands in `globalRegistry` for slash command and `@mention` access.
+2. **Workflow sub-agent registry** (workflow-commands.ts:680-687): Populates the `SubagentTypeRegistry` for the Ralph workflow graph to know which sub-agents are available.
diff --git a/research/docs/2026-02-25-unified-workflow-execution-research.md b/research/docs/2026-02-25-unified-workflow-execution-research.md
new file mode 100644
index 0000000000..8c1a3a215d
--- /dev/null
+++ b/research/docs/2026-02-25-unified-workflow-execution-research.md
@@ -0,0 +1,738 @@
+---
+date: 2026-02-26 00:00:45 UTC
+researcher: Claude Opus 4.6
+git_commit: 0756a9cd380a7d153963fc96a09c2afedbffdc6f
+branch: lavaman131/feature/workflow-sdk
+repository: workflow-sdk
+topic: "Unified Workflow Execution Interface: Current Architecture and Hardcoded Patterns"
+tags: [research, codebase, workflow-sdk, graph-engine, ralph, unified-execution, command-registry, workflow-discovery]
+status: complete
+last_updated: 2026-02-25
+last_updated_by: Claude Opus 4.6
+---
+
+# Research: Unified Workflow Execution Interface
+
+## Research Question
+
+Document the current workflow execution architecture, including: (1) how workflows are defined, registered, and triggered; (2) how the Ralph workflow is hardcoded via `createRalphCommand` and related patterns; (3) what abstractions exist (or are missing) for a generic workflow execution interface; and (4) how the UI/CLI layer couples to specific workflow implementations. The goal is to understand the current state so we can design a unified workflow SDK that allows any workflow to be executed through a common interface rather than requiring per-workflow command scaffolding.
+
+## Summary
+
+The codebase contains a mature graph execution engine with a fluent builder API, typed state management, 12+ node factories, and a `WorkflowSDK` facade class designed for generic workflow execution. However, the UI command layer has a hardcoded dispatch pattern where `createWorkflowCommand()` checks `metadata.name === "ralph"` and routes to a specialized `createRalphCommand()` handler that performs actual graph execution. All non-Ralph workflows receive a generic handler that only sets UI state flags and sends the user prompt through normal chat — no graph is built or executed. The `WorkflowSDK` class is never used at runtime; Ralph bypasses it entirely with ad-hoc runtime dependency construction. Custom workflow files (`.atomic/workflows/*.ts`) can export metadata (name, description, version) but have no mechanism to export a graph definition or factory function. This document maps the complete architecture and the specific points where generalization is needed.
+
+---
+
+## Table of Contents
+
+1. [Workflow Lifecycle: End-to-End Flow](#1-workflow-lifecycle-end-to-end-flow)
+2. [The Hardcoded Ralph Dispatch](#2-the-hardcoded-ralph-dispatch)
+3. [Non-Ralph Workflow Path (The Gap)](#3-non-ralph-workflow-path-the-gap)
+4. [WorkflowSDK Class (Unused at Runtime)](#4-workflowsdk-class-unused-at-runtime)
+5. [Graph Execution Engine](#5-graph-execution-engine)
+6. [Ralph Workflow Implementation](#6-ralph-workflow-implementation)
+7. [Custom Workflow Discovery](#7-custom-workflow-discovery)
+8. [UI-to-Workflow Coupling](#8-ui-to-workflow-coupling)
+9. [Existing Abstractions for Unification](#9-existing-abstractions-for-unification)
+10. [Architecture Documentation](#10-architecture-documentation)
+11. [Code References](#11-code-references)
+12. [Historical Context](#12-historical-context)
+13. [Open Questions](#13-open-questions)
+
+---
+
+## 1. Workflow Lifecycle: End-to-End Flow
+
+### 1.1 App Startup → Command Registration
+
+The workflow registration flow from app boot to command availability:
+
+```
+src/cli.ts:281 (Commander.js default command)
+  → src/commands/chat.ts:196 (chatCommand → startChatUI)
+    → src/ui/index.ts:306 (startChatUI)
+      → src/ui/index.ts:2022 (initializeCommandsAsync)
+        → src/ui/commands/index.ts:87-95
+          1. registerBuiltinCommands()          // /help, /clear, /model, etc.
+          2. await loadWorkflowsFromDisk()      // Discover .atomic/workflows/*.ts
+          3. registerWorkflowCommands()          // Register all workflow commands
+          4. await loadSkillsFromDisk()          // Discover skills
+          5. registerAgentCommands()              // Register agent commands
+```
+
+`registerWorkflowCommands()` at `src/ui/commands/workflow-commands.ts:899-907` calls `getAllWorkflows()` → `createWorkflowCommand()` for each, and registers with `globalRegistry`.
+
+### 1.2 Command Invocation
+
+When a user types `/ralph <prompt>` in the TUI:
+
+```
+src/ui/chat.tsx:3516 (executeCommand callback)
+  → globalRegistry.get("ralph")                          // line 3525
+  → Builds CommandContext with 18+ fields                 // lines 3540-3971
+  → command.execute(args, context)                        // line 4017
+  → Applies result.stateUpdate to UI state                // lines 4072-4091
+```
+
+The `CommandContext` object (defined at `src/ui/commands/registry.ts:75-168`) includes both generic helpers (`addMessage`, `setStreaming`, `sendMessage`) and Ralph-specific helpers (`setRalphSessionDir`, `setRalphSessionId`, `setRalphTaskIds`).
+
+---
+
+## 2. The Hardcoded Ralph Dispatch
+
+### 2.1 The Dispatch Check
+
+The central dispatch point is in `createWorkflowCommand()`:
+
+```typescript
+// src/ui/commands/workflow-commands.ts:543-548
+function createWorkflowCommand(metadata: WorkflowMetadata): CommandDefinition {
+    // Use specialized handler for ralph workflow
+    if (metadata.name === "ralph") {
+        return createRalphCommand(metadata);
+    }
+    // ... generic path follows
+}
+```
+
+This is the only mechanism for routing a workflow to actual graph execution. Any workflow not named "ralph" falls through to the generic path.
+
+### 2.2 What `createRalphCommand()` Does
+
+The Ralph command handler at `src/ui/commands/workflow-commands.ts:597-793` performs:
+
+1. **Argument parsing**: `parseRalphArgs(args)` at line 616
+2. **Session initialization**: Creates UUID session ID, initializes `WorkflowSession` at lines 631-635
+3. **UI state updates**: Sets `workflowActive`, `workflowType`, `ralphConfig` at lines 637-641
+4. **State construction**: `createRalphState()` with session ID, prompt, and max iterations at lines 654-658
+5. **Ad-hoc bridge construction**: Wraps `context.spawnSubagentParallel!()` into a bridge object at lines 661-676
+6. **Subagent registry construction**: `new SubagentTypeRegistry()` populated with `discoverAgentInfos()` at lines 679-687
+7. **Graph creation**: `createRalphWorkflow()` at line 690
+8. **Runtime injection**: Directly mutates `compiled.config.runtime` at lines 691-695
+9. **Graph streaming**: `for await (const step of streamGraph(compiled, { initialState }))` at lines 702-741
+10. **UI progress updates**: Updates task list, session tracking, and messages in the streaming loop
+
+This is approximately 200 lines of orchestration code specific to the Ralph workflow.
+
+### 2.3 Ralph-Specific Artifacts Throughout the Codebase
+
+The Ralph workflow creates coupling in multiple layers:
+
+| Location | Ralph-Specific Code |
+|----------|-------------------|
+| `src/ui/commands/registry.ts:135-145` | `setRalphSessionDir`, `setRalphSessionId`, `setRalphTaskIds` methods on `CommandContext` |
+| `src/ui/commands/registry.ts:211-214` | `ralphConfig` field on `CommandContextState` |
+| `src/ui/chat.tsx:1841-1849` | Ralph-specific state variables (`ralphSessionId`, `ralphSessionDir`, `ralphTaskIds`) |
+| `src/ui/chat.tsx:2328-2346` | TodoWrite filtering guard using `ralphTaskIds` |
+| `src/ui/chat.tsx:2762-2766` | Auto-approve behavior during active workflows |
+| `src/ui/chat.tsx:4480-4528` | Ctrl+C cancellation flow with Ralph state cleanup |
+| `src/ui/commands/workflow-commands.ts:51` | `MAX_RALPH_ITERATIONS` constant |
+| `src/ui/commands/workflow-commands.ts:57-69` | `getNodePhaseDescription()` with hardcoded Ralph node phase names |
+| `src/ui/commands/workflow-commands.ts:78-93` | `RalphCommandArgs` interface and `parseRalphArgs()` |
+| `src/ui/commands/workflow-commands.ts:200-235` | `saveTasksToActiveSession()` referencing Ralph session |
+
+---
+
+## 3. Non-Ralph Workflow Path (The Gap)
+
+### 3.1 The Generic Handler
+
+When `metadata.name !== "ralph"`, the generic handler at `src/ui/commands/workflow-commands.ts:549-594` does:
+
+```typescript
+execute: (args: string, context: CommandContext): CommandResult => {
+    // 1. Check if a workflow is already active
+    if (context.state.workflowActive) {
+        return { success: false, message: `A workflow is already active...` };
+    }
+
+    // 2. Extract the prompt
+    const initialPrompt = args.trim() || null;
+    if (!initialPrompt) {
+        return { success: false, message: `Please provide a prompt...` };
+    }
+
+    // 3. Add a system message
+    context.addMessage("system", `Starting **${metadata.name}** workflow...`);
+
+    // 4. Return success with state flags
+    return {
+        success: true,
+        message: `Workflow **${metadata.name}** initialized.`,
+        stateUpdate: {
+            workflowActive: true,
+            workflowType: metadata.name,
+            initialPrompt,
+            pendingApproval: false,
+            specApproved: undefined,
+            feedback: null,
+        },
+    };
+}
+```
+
+### 3.2 What Happens After the Generic Handler
+
+The `stateUpdate` with `workflowActive: true` triggers a React effect in `src/ui/chat.tsx:2534-2689` which:
+1. Detects that `workflowActive` is true and `initialPrompt` has a value
+2. Sends the `initialPrompt` through the standard `onStreamMessage` handler as a regular agent chat message
+3. No graph is built, no session is created, no structured execution occurs
+
+### 3.3 What Is Missing
+
+For a non-Ralph workflow to have actual graph execution, the generic path would need:
+
+1. **Graph factory**: A way to get a `CompiledGraph` from the workflow definition
+2. **State factory**: A way to create the initial state for the workflow
+3. **Runtime dependencies**: Bridge, registry, provider setup
+4. **Streaming integration**: Progress updates, task list, session management
+5. **Node phase descriptions**: UI labels for each node
+6. **Error/cancellation handling**: Ctrl+C flow, cleanup
+
+None of these exist in the generic path today.
+
+---
+
+## 4. WorkflowSDK Class (Unused at Runtime)
+
+### 4.1 Design
+
+The `WorkflowSDK` class at `src/workflows/graph/sdk.ts` is a facade designed for exactly this purpose:
+
+```typescript
+export class WorkflowSDK {
+    // Initialized with providers, workflows, agents, checkpointing, model config
+    static init(config: WorkflowSDKConfig): WorkflowSDK;
+
+    // Create a graph builder
+    graph<TState>(): GraphBuilder<TState>;
+
+    // Execute a compiled workflow
+    execute<TState>(compiled: CompiledGraph<TState>, options?): Promise<ExecutionResult<TState>>;
+
+    // Stream workflow execution events
+    stream<TState>(compiled: CompiledGraph<TState>, options?): AsyncGenerator<StreamEvent<TState>>;
+
+    // Register named workflows for subgraph resolution
+    registerWorkflow(name: string, workflow: WorkflowRegistration): void;
+
+    // Stop all provider clients
+    destroy(): Promise<void>;
+}
+```
+
+`WorkflowSDKConfig` (`sdk.ts:32-43`) accepts:
+- `providers`: Record of coding agent clients (Claude, OpenCode, Copilot)
+- `workflows`: Named workflow map for resolution
+- `agents`: Agent info map for subagent registry
+- `checkpointer`: Checkpoint type and options
+- `defaultModel`: Default model specification
+- `maxSteps`: Step limit
+- `subagentProvider`: Provider name for sub-agents
+
+### 4.2 What It Manages
+
+The `WorkflowSDK` constructor (`sdk.ts:66-118`) sets up:
+1. **ProviderRegistry**: Wraps raw clients into `ClientBackedAgentProvider` instances
+2. **SubagentGraphBridge**: Creates sessions via the provider registry
+3. **SubagentTypeRegistry**: Populated from `agents` config
+4. **RuntimeDependencies**: Assembled object with `clientProvider`, `subagentBridge`, `subagentRegistry`, `workflowResolver`
+5. **Graph defaults**: Auto-injects checkpointer, model, runtime deps into compiled graphs via `applyGraphDefaults()`
+
+### 4.3 Why It's Bypassed
+
+The Ralph command at `workflow-commands.ts:597-793` bypasses `WorkflowSDK` because:
+
+1. **Different bridge pattern**: Ralph routes sub-agent spawning through `context.spawnSubagentParallel!()` (TUI-provided), not through the SDK's `SubagentGraphBridge` which creates its own sessions
+2. **No provider setup**: The TUI already has an active session; the SDK would create redundant sessions
+3. **Direct graph mutation**: Ralph directly mutates `compiled.config.runtime` instead of going through `applyGraphDefaults()`
+4. **Only partial deps needed**: Ralph only uses `subagentBridge` and `subagentRegistry`, not `clientProvider` or `workflowResolver`
+
+### 4.4 SDK Test Usage
+
+Tests at `src/workflows/graph/sdk.test.ts` (9 test scenarios) demonstrate the intended usage:
+- Creating SDK with multiple providers
+- Executing compiled graphs through `sdk.execute()`
+- Streaming through `sdk.stream()`
+- Runtime dependency injection validation
+- Subagent provider resolution
+
+---
+
+## 5. Graph Execution Engine
+
+### 5.1 GraphBuilder (`src/workflows/graph/builder.ts`)
+
+Fluent API for constructing workflows:
+
+```typescript
+graph<MyState>()
+    .start(startNode)
+    .then(nodeA)
+    .subagent({ id: "planner", agent: "planner", task: (s) => s.prompt, ... })
+    .tool({ id: "parser", toolName: "parse", execute: fn, args: fn, ... })
+    .loop([nodeA, nodeB], { until: (s) => s.done, maxIterations: 100 })
+    .if({ condition: fn, then: [...], else: [...] })
+    .parallel([branch1, branch2], { strategy: "all" })
+    .wait({ prompt: "Continue?" })
+    .catch(errorHandler)
+    .compile(config?)
+```
+
+Key methods: `.start()`, `.then()`, `.subagent()`, `.tool()`, `.loop()`, `.if()/.else()/.endif()`, `.parallel()`, `.wait()`, `.catch()`, `.end()`, `.compile()`
+
+### 5.2 Node Types (`src/workflows/graph/nodes.ts`)
+
+12 factory functions:
+
+| Factory | Purpose |
+|---------|---------|
+| `agentNode()` | AI agent session execution |
+| `toolNode()` | Explicit tool function execution |
+| `subagentNode()` | Single sub-agent spawning via bridge |
+| `parallelSubagentNode()` | Concurrent multi-agent spawning |
+| `decisionNode()` | Condition-based routing |
+| `waitNode()` | Human-in-the-loop pause |
+| `askUserNode()` | Structured user questions |
+| `parallelNode()` | Concurrent branch execution |
+| `subgraphNode()` | Nested graph execution |
+| `contextMonitorNode()` | Context window monitoring |
+| `customToolNode()` | Registry-resolved tool with validation |
+| `clearContextNode()` | Context window clearing |
+
+### 5.3 Compiled Graph Execution (`src/workflows/graph/compiled.ts`)
+
+`GraphExecutor` handles:
+- Queue-based node traversal
+- Loop detection and iteration limits
+- Retry with exponential backoff
+- State merging with annotation reducers
+- Signal handling (human_input_required, checkpoint saves)
+- Abort support
+- Progress callbacks
+
+Entry points: `executeGraph()` (batch) and `streamGraph()` (async generator yielding `StepResult`).
+
+### 5.4 State Management (`src/workflows/graph/annotation.ts`)
+
+Annotation system for typed state:
+- `annotation<T>(default, reducer?)` — defines a state field
+- Reducers: `Reducers.replace`, `Reducers.append`, `Reducers.merge`, custom functions
+- `initializeState(annotations)` — creates initial state from annotations
+- `applyStateUpdate(annotations, current, update)` — applies partial update using reducers
+
+### 5.5 Workflow Templates (`src/workflows/graph/templates.ts`)
+
+Four reusable graph patterns:
+
+| Template | Pattern |
+|----------|---------|
+| `sequential(nodes)` | Linear chain of nodes |
+| `mapReduce(options)` | Splitter → parallel workers → reducer |
+| `reviewCycle(options)` | Execute → review → conditional fix loop |
+| `taskLoop(options)` | Task decomposition → worker loop |
+
+**Note**: Ralph does not use these templates; it builds its graph directly via the GraphBuilder fluent API.
+
+---
+
+## 6. Ralph Workflow Implementation
+
+### 6.1 Graph Structure (`src/workflows/ralph/graph.ts`)
+
+`createRalphWorkflow()` at line 98 builds a 3-phase compiled graph:
+
+```
+Phase 1: Task Decomposition
+  planner (subagent) → parse-tasks (tool)
+
+Phase 2: Worker Loop
+  loop([select-ready-tasks (tool), worker (custom agent)])
+    until: all tasks completed/errored OR maxIterations reached OR no actionable tasks
+
+Phase 3: Review & Fix
+  reviewer (subagent) → if(findings && !correct) → fixer (subagent)
+```
+
+### 6.2 State (`src/workflows/ralph/state.ts`)
+
+`RalphWorkflowState` interface (line 51) has 30 fields:
+- **Base fields**: `executionId`, `lastUpdated`, `outputs`
+- **Workflow pipeline**: `researchDoc`, `specDoc`, `tasks`, `currentTasks`, `reviewResult`, `fixesApplied`, `featureList`, `currentFeature`, `debugReports`
+- **Ralph-specific**: `ralphSessionId`, `ralphSessionDir`, `yolo`, `yoloPrompt`, `yoloComplete`, `maxIterations`, `shouldContinue`, `completedFeatures`
+
+`RalphStateAnnotation` (line 82) defines reducers per field, notably:
+- `tasks`: `mergeByIdReducer("id")` — merge-by-ID preserving task identity
+- `debugReports`: `concatReducer` — append-only
+- `currentTasks`: replace reducer (always overwrites)
+
+### 6.3 Session Management (`src/workflows/session.ts`)
+
+Session management is **generic** (not Ralph-specific):
+- `WorkflowSession` interface with `sessionId`, `workflowName`, `sessionDir`, `status`, `nodeHistory`, `outputs`
+- `initWorkflowSession(workflowName, sessionId?)` — creates session directory at `~/.atomic/workflows/sessions/{sessionId}/`
+- `saveWorkflowSession()` — persists session metadata
+- `saveSubagentOutput()` — stores per-agent results
+
+---
+
+## 7. Custom Workflow Discovery
+
+### 7.1 Search Paths
+
+`CUSTOM_WORKFLOW_SEARCH_PATHS` at `src/ui/commands/workflow-commands.ts:268-273`:
+1. `.atomic/workflows` — project-local (highest priority)
+2. `~/.atomic/workflows` — user-global
+
+### 7.2 Discovery (`discoverWorkflowFiles()`)
+
+At `workflow-commands.ts:343-372`:
+- Scans each search path for `.ts` files
+- Returns `{ path, source }` pairs (source: "local" | "global")
+
+### 7.3 Loading (`loadWorkflowsFromDisk()`)
+
+At `workflow-commands.ts:401-471`:
+- Dynamic `import()` of each discovered file
+- Extracts exports: `name`, `description`, `aliases`, `version`, `minSDKVersion`, `stateVersion`, `migrateState`
+- Local workflows take priority over global by name deduplication
+- Validates `minSDKVersion` against current `VERSION`
+
+### 7.4 What Custom Workflows Can Export
+
+Currently supported exports (metadata only):
+
+```typescript
+// .atomic/workflows/my-workflow.ts
+export const name = "my-workflow";
+export const description = "My custom workflow";
+export const aliases = ["mw"];
+export const version = "1.0.0";
+export const minSDKVersion = "1.0.0";
+export const stateVersion = 1;
+export function migrateState(oldState: unknown, fromVersion: number): BaseState { ... }
+```
+
+### 7.5 What Custom Workflows Cannot Export
+
+There is **no mechanism** for custom workflows to export:
+- A graph factory function (e.g., `export function createGraph(): CompiledGraph`)
+- An initial state factory (e.g., `export function createState(prompt: string): MyState`)
+- Node phase descriptions for UI progress
+- Runtime dependency requirements
+- A `WorkflowRegistration` compatible with `WorkflowSDK.registerWorkflow()`
+
+### 7.6 Workflow Metadata Interface
+
+`WorkflowMetadata` at `workflow-commands.ts:110-131`:
+
+```typescript
+export interface WorkflowMetadata {
+    name: string;
+    description: string;
+    aliases?: string[];
+    defaultConfig?: Record<string, unknown>;
+    version?: string;
+    minSDKVersion?: string;
+    stateVersion?: number;
+    migrateState?: WorkflowStateMigrator;
+    source?: "builtin" | "global" | "local";
+    argumentHint?: string;
+}
+```
+
+Missing from this interface: any reference to graph construction, state factories, or execution logic.
+
+---
+
+## 8. UI-to-Workflow Coupling
+
+### 8.1 CommandContext Ralph-Specific Fields
+
+The `CommandContext` interface at `src/ui/commands/registry.ts:75-168` includes:
+
+| Method/Field | Purpose | Ralph-Specific? |
+|-------------|---------|-----------------|
+| `setRalphSessionDir(dir)` | Set session directory for task panel | Yes |
+| `setRalphSessionId(id)` | Set session ID for task panel | Yes |
+| `setRalphTaskIds(ids)` | Guard TodoWrite persistence | Yes |
+| `spawnSubagentParallel?()` | Parallel sub-agent spawning | No (generic) |
+| `streamAndWait()` | Send prompt and wait for response | No (generic) |
+| `setTodoItems(items)` | Update task list UI | No (generic) |
+| `clearContext()` | Clear context window | No (generic) |
+| `setStreaming(streaming)` | Set streaming state | No (generic) |
+
+### 8.2 CommandContextState Ralph-Specific Fields
+
+The `CommandContextState` at `registry.ts:185-215` includes:
+
+```typescript
+ralphConfig?: {
+    userPrompt: string | null;
+    sessionId?: string;
+};
+```
+
+### 8.3 Chat UI (`src/ui/chat.tsx`) Ralph State
+
+Ralph-specific state variables declared in the chat component:
+- `ralphSessionId` (line ~1841)
+- `ralphSessionDir` (line ~1843)
+- `ralphTaskIds` (line ~1845)
+
+These are used for:
+- TodoWrite filtering (lines 2328-2346): Only persist task updates from Ralph's own tasks
+- Session tracking for the persistent task list panel
+- Ctrl+C cancellation cleanup (lines 4480-4528)
+
+### 8.4 CommandResult Workflow Fields
+
+`CommandResult` at `registry.ts:220-251` does not have workflow-specific fields — it uses generic `stateUpdate` to communicate workflow state changes.
+
+---
+
+## 9. Existing Abstractions for Unification
+
+### 9.1 Already Generic
+
+These components are already designed for multi-workflow use:
+
+1. **GraphBuilder** (`builder.ts`): Fully generic, parameterized by `TState`
+2. **GraphExecutor** (`compiled.ts`): Executes any `CompiledGraph<TState>`
+3. **streamGraph()** (`compiled.ts`): Streams any compiled graph
+4. **Node factories** (`nodes.ts`): 12 generic node types
+5. **WorkflowSDK** (`sdk.ts`): Designed as a generic facade
+6. **Session management** (`session.ts`): Generic `WorkflowSession` with `workflowName` field
+7. **Annotation system** (`annotation.ts`): Generic typed state management
+8. **SubagentGraphBridge** (`subagent-bridge.ts`): Generic sub-agent spawning
+9. **SubagentTypeRegistry** (`subagent-registry.ts`): Generic agent type registry
+10. **ProviderRegistry** (`provider-registry.ts`): Generic provider management
+11. **Workflow templates** (`templates.ts`): Reusable graph patterns
+12. **Command Registry** (`registry.ts`): Generic command registration
+
+### 9.2 Ralph-Specific (Would Need Generalization)
+
+These are currently hardcoded to Ralph:
+
+1. **`createWorkflowCommand()`** dispatch — the `if (metadata.name === "ralph")` check
+2. **`createRalphCommand()`** — 200 lines of Ralph-specific orchestration in the UI layer
+3. **`getNodePhaseDescription()`** — hardcoded node-to-description mapping for Ralph nodes
+4. **`CommandContext` Ralph methods** — `setRalphSessionDir`, `setRalphSessionId`, `setRalphTaskIds`
+5. **`CommandContextState.ralphConfig`** — Ralph-specific state field
+6. **Chat.tsx Ralph state** — `ralphSessionId`, `ralphSessionDir`, `ralphTaskIds` variables
+7. **TodoWrite guard** — Filters task persistence by Ralph task IDs
+8. **`WorkflowMetadata`** — Missing graph/state factory fields
+9. **Custom workflow exports** — No graph export mechanism
+
+### 9.3 Patterns That Could Bridge the Gap
+
+1. **`WorkflowSDK.registerWorkflow()`** accepts `WorkflowRegistration<TState>` which is `CompiledSubgraph<TState> | CompiledGraph<TState>` — this is the registration interface
+2. **`WorkflowSDK.stream()`** returns `AsyncGenerator<StreamEvent<TState>>` — this is the execution interface
+3. **`WorkflowSDK.execute()`** returns `Promise<ExecutionResult<TState>>` — batch alternative
+4. **`taskLoop` template** already implements decompose→worker pattern generically
+5. **`reviewCycle` template** already implements execute→review→fix generically
+
+---
+
+## 10. Architecture Documentation
+
+### 10.1 Current Architecture Diagram
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         UI LAYER                                 │
+│                                                                   │
+│  chat.tsx ──── executeCommand() ──── globalRegistry.get()        │
+│     │                                        │                    │
+│     │ Ralph state:                    CommandDefinition           │
+│     │  - ralphSessionId              execute(args, context)      │
+│     │  - ralphSessionDir                     │                    │
+│     │  - ralphTaskIds                        ▼                    │
+│     │                          ┌─────────────────────┐           │
+│     │                          │ createWorkflowCommand│           │
+│     │                          │   (dispatch check)   │           │
+│     │                          └────────┬────────────┘           │
+│     │                            ┌──────┴──────┐                 │
+│     │                    name==="ralph"   name!=="ralph"          │
+│     │                            │              │                 │
+│     │                            ▼              ▼                 │
+│     │                  createRalphCommand   generic handler       │
+│     │                  (200 lines)          (sets state only)     │
+│     │                            │              │                 │
+│     │                            ▼              ▼                 │
+│     │                  Graph execution    onStreamMessage          │
+│     │                  + streaming        (regular chat)          │
+│     │                            │                                │
+└─────┼────────────────────────────┼────────────────────────────────┘
+      │                            │
+┌─────┼────────────────────────────┼────────────────────────────────┐
+│     │            WORKFLOW LAYER  │                                 │
+│     │                            ▼                                │
+│     │              createRalphWorkflow()                          │
+│     │                     │                                       │
+│     │                     ▼                                       │
+│     │              graph<RalphWorkflowState>()                   │
+│     │                .subagent("planner")                         │
+│     │                .tool("parse-tasks")                         │
+│     │                .loop([select, worker], {until})             │
+│     │                .subagent("reviewer")                        │
+│     │                .if({condition, then: [fixer]})             │
+│     │                .compile()                                   │
+│     │                     │                                       │
+│     │                     ▼                                       │
+│     │              streamGraph(compiled, {initialState})         │
+│     │                     │                                       │
+│     │                     ▼                                       │
+│     │              GraphExecutor.streamSteps()                   │
+│     │                                                             │
+│     │   ┌─────────────────────────────────────────────────┐      │
+│     │   │  WorkflowSDK (exists but unused at runtime)     │      │
+│     │   │  - init(config)                                  │      │
+│     │   │  - execute(compiled, options)                     │      │
+│     │   │  - stream(compiled, options)                      │      │
+│     │   │  - registerWorkflow(name, workflow)               │      │
+│     │   └─────────────────────────────────────────────────┘      │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+### 10.2 Data Flow: Ralph Workflow Execution
+
+```
+User types "/ralph fix auth bug"
+  → parseRalphArgs("fix auth bug")
+  → createRalphState(sessionId, { yoloPrompt: "fix auth bug", ... })
+  → createRalphWorkflow()  →  CompiledGraph<RalphWorkflowState>
+  → Inject ad-hoc bridge + registry into compiled.config.runtime
+  → for await (step of streamGraph(compiled, { initialState }))
+      → step.nodeId: "planner" → UI shows "Planning..."
+      → step.nodeId: "parse-tasks" → UI shows "Parsing..."
+      → step.nodeId: "select-ready-tasks" → UI shows "Selecting..."
+      → step.nodeId: "worker" → UI shows "Working..."
+      → (loop repeats until all tasks done)
+      → step.nodeId: "reviewer" → UI shows "Reviewing..."
+      → step.nodeId: "fixer" (conditional) → UI shows "Fixing..."
+  → Workflow complete → clear workflowActive state
+```
+
+### 10.3 Data Flow: Non-Ralph Workflow (What Happens Today)
+
+```
+User types "/my-workflow do something"
+  → Generic handler sets stateUpdate: { workflowActive: true, initialPrompt: "do something" }
+  → React effect detects workflowActive + initialPrompt
+  → onStreamMessage("do something")  ← regular chat message, no graph
+  → Agent responds as if it were a normal conversation
+  → No structured execution, no task decomposition, no review
+```
+
+---
+
+## 11. Code References
+
+### Core Files
+
+| File | Lines | Description |
+|------|-------|-------------|
+| `src/ui/commands/workflow-commands.ts` | 926 | Workflow command creation, Ralph handler, session management |
+| `src/workflows/graph/sdk.ts` | 278 | WorkflowSDK facade class (unused at runtime) |
+| `src/workflows/graph/builder.ts` | ~700 | GraphBuilder fluent API |
+| `src/workflows/graph/compiled.ts` | ~600 | GraphExecutor, executeGraph, streamGraph |
+| `src/workflows/graph/nodes.ts` | ~900 | 12 node factory functions |
+| `src/workflows/graph/types.ts` | ~350 | Core type definitions |
+| `src/workflows/graph/annotation.ts` | ~200 | State annotation system |
+| `src/workflows/graph/templates.ts` | ~250 | Reusable workflow templates |
+| `src/workflows/ralph/graph.ts` | 237 | Ralph graph definition |
+| `src/workflows/ralph/state.ts` | 210 | Ralph state and annotations |
+| `src/workflows/ralph/prompts.ts` | ~350 | Ralph prompt builders |
+| `src/workflows/session.ts` | 96 | Generic session management |
+| `src/ui/commands/registry.ts` | 535 | Command registry, CommandContext, CommandResult |
+| `src/ui/chat.tsx` | ~5000 | Chat UI with Ralph-specific state and effects |
+| `src/ui/index.ts` | ~2100 | App initialization, command registration |
+| `src/ui/commands/index.ts` | ~100 | Command initialization orchestration |
+
+### Key Functions
+
+| Function | File:Line | Purpose |
+|----------|-----------|---------|
+| `createWorkflowCommand()` | `workflow-commands.ts:543` | Dispatch: Ralph vs generic |
+| `createRalphCommand()` | `workflow-commands.ts:597` | Ralph-specific command handler |
+| `createRalphWorkflow()` | `ralph/graph.ts:98` | Build Ralph compiled graph |
+| `createRalphState()` | `ralph/state.ts:128` | Initialize Ralph state |
+| `streamGraph()` | `compiled.ts` | Stream any compiled graph |
+| `executeGraph()` | `compiled.ts` | Execute any compiled graph |
+| `WorkflowSDK.init()` | `sdk.ts:123` | Create SDK instance |
+| `WorkflowSDK.stream()` | `sdk.ts:149` | Stream through SDK |
+| `loadWorkflowsFromDisk()` | `workflow-commands.ts:401` | Discover custom workflows |
+| `registerWorkflowCommands()` | `workflow-commands.ts:899` | Register all workflow commands |
+| `getAllWorkflows()` | `workflow-commands.ts:477` | Get builtin + disk workflows |
+| `discoverAgentInfos()` | `agent-commands.ts:259` | Discover agent definitions |
+
+---
+
+## 12. Historical Context
+
+### 12.1 Relevant Prior Research
+
+The `research/` directory contains 48 relevant documents spanning 2026-01-19 to 2026-02-25. Key documents:
+
+| Document | Summary |
+|----------|---------|
+| `research/docs/2026-02-25-workflow-sdk-standardization.md` | Comprehensive standardization research covering graph engine, Ralph, sub-agents, and declarative API |
+| `research/docs/2026-02-25-workflow-sdk-refactor-research.md` | Simplified syntax, module consolidation, and Ralph TUI freeze fix |
+| `research/docs/2026-02-25-workflow-sdk-patterns.md` | External SDK patterns from LangGraph, Temporal, Inngest, and coding agent SDKs |
+| `research/docs/2026-02-05-pluggable-workflows-sdk-design.md` | Original pluggable SDK design with entity registry and provider normalization |
+| `research/docs/2026-02-03-custom-workflow-file-format.md` | Custom workflow file format: required/optional exports, search paths, precedence |
+| `research/docs/2026-02-03-workflow-composition-patterns.md` | Subgraph composition, circular dependency detection, state passing |
+| `research/docs/2026-02-11-workflow-sdk-implementation.md` | Custom tools, sub-agents, and graph execution integration |
+| `research/docs/2026-01-31-atomic-current-workflow-architecture.md` | Current architecture: SDK layer, graph engine, workflow definitions, command system |
+
+### 12.2 Related Specs
+
+| Spec | Summary |
+|------|---------|
+| `specs/workflow-sdk-standardization.md` | Unified graph engine, declarative API, provider-agnostic execution |
+| `specs/workflow-sdk-refactor.md` | Simplified syntax, module consolidation |
+| `specs/pluggable-workflows-sdk.md` | Unified entity registry normalizing commands/skills/agents |
+| `specs/workflow-sdk-implementation.md` | Custom tools, sub-agents, graph execution bridging |
+
+### 12.3 Evolution Timeline
+
+1. **Jan 31**: Initial architecture — SDK research, graph execution pattern design (LangGraph-inspired)
+2. **Feb 2-5**: Built-in workflows, pluggable SDK design, custom file formats, workflow composition
+3. **Feb 9-11**: Ralph loop enhancements, workflow SDK implementation with custom tools/sub-agents
+4. **Feb 13-15**: Ralph task list UI, DAG orchestration, manual worker dispatch pivot
+5. **Feb 19-21**: SDK v2 unified layer, workflow inline mode
+6. **Feb 25**: Standardization research, refactor planning, external patterns analysis
+
+---
+
+## 13. Open Questions
+
+1. **Custom workflow graph exports**: What should the export interface look like for custom workflow files to provide graph factories? Should they export a `createGraph()` function, a compiled graph directly, or use the template system?
+
+2. **WorkflowSDK integration**: Should the unified interface route through `WorkflowSDK.stream()`, or should the TUI continue to use `streamGraph()` directly with injected runtime dependencies? The SDK adds overhead (redundant sessions) but provides a cleaner abstraction.
+
+3. **Bridge pattern**: The TUI's `context.spawnSubagentParallel!()` and the SDK's `SubagentGraphBridge` are two different sub-agent spawning mechanisms. Which should the unified interface use? Can they be reconciled?
+
+4. **UI progress abstraction**: `getNodePhaseDescription()` is hardcoded to Ralph node IDs. A generic workflow would need a way to declare node-level UI descriptions. Should this be part of `NodeDefinition`, `WorkflowMetadata`, or a separate mapping?
+
+5. **State factory pattern**: Each workflow needs an initial state factory. Should this be part of `WorkflowMetadata`, exported from the workflow file, or inferred from state annotations?
+
+6. **Session management scope**: `WorkflowSession` is generic but `CommandContext` has Ralph-specific session helpers. How should session management be abstracted for any workflow?
+
+7. **Task list integration**: The tasks.json persistence and TodoWrite guard are Ralph-specific patterns. Should all graph-executing workflows support task lists, or should this be opt-in?
+
+8. **Ctrl+C / cancellation**: The cancellation flow references Ralph state. How should workflow cancellation be generalized?
+
+---
+
+## Supporting Research Documents
+
+This synthesis drew from 6 parallel sub-agent investigations:
+
+1. `research/docs/2026-02-25-graph-execution-engine.md` — Graph builder, compiled execution, node types, core types
+2. `research/docs/2026-02-25-ui-workflow-coupling.md` — Chat UI, command registry, UI-to-workflow coupling
+3. `research/docs/2026-02-25-workflow-sdk-design.md` — WorkflowSDK class, providers, subagent bridge/registry
+4. `research/docs/2026-02-25-ralph-workflow-implementation.md` — Ralph graph, state, prompts, tests, sessions, templates
+5. `research/docs/2026-02-25-workflow-registration-flow.md` — Custom workflow discovery, registration, non-Ralph gap, config, CLI entry
+6. Discovery scan of 48 existing research documents in `research/`
diff --git a/research/docs/2026-02-25-web-search-fetch-references.md b/research/docs/2026-02-25-web-search-fetch-references.md
new file mode 100644
index 0000000000..9dd472213c
--- /dev/null
+++ b/research/docs/2026-02-25-web-search-fetch-references.md
@@ -0,0 +1,488 @@
+---
+date: 2026-02-25
+topic: "Web Search and Web Fetch Tool References Across Agent/Skill Configurations"
+tags: [research, web-fetch, web-search, agents, skills, tools]
+status: complete
+---
+
+# Web Search and Web Fetch Tool References Analysis
+
+## Overview
+
+This document catalogs ALL references to web_fetch, WebSearch, WebFetch, web search, and web fetch tools across the Atomic CLI project. These tools enable agents and skills to retrieve information from the web for research, documentation lookups, and problem-solving.
+
+## Summary
+
+Web search/fetch capabilities are referenced in:
+- **7 agent configuration files** (across 3 platform directories)
+- **6 skill configuration files** (across 3 platform directories)
+- **1 source code file** (SDK client implementation)
+- **1 configuration file** (OpenCode permissions)
+
+The primary use case is to enable the **codebase-online-researcher** agent to fetch external documentation and resources, with secondary usage in **debugger** agent for troubleshooting, **reviewer** agent for context gathering, and **explain-code**/**research-codebase** skills for documentation lookups.
+
+---
+
+## Agent Configuration Files
+
+### 1. `.claude/agents/codebase-online-researcher.md`
+
+**Lines:** 1-122 (entire file)
+
+**Exact References:**
+- Line 4: `tools: Glob, Grep, NotebookRead, Read, LS, TodoWrite, ListMcpResourcesTool, ReadMcpResourceTool, mcp__deepwiki__ask_question, WebFetch, WebSearch`
+- Line 9: `You are an expert web research specialist focused on finding accurate, relevant information from web sources. Your primary tools are the DeepWiki \`ask_question\` tool and WebFetch/WebSearch tools`
+- Line 32: `Use WebFetch and WebSearch tools to retrieve full content from promising search results`
+
+**Agent Name:** codebase-online-researcher
+
+**Purpose:**
+This agent is the primary web research specialist. It uses WebFetch and WebSearch to:
+- Retrieve full content from web search results
+- Fetch documentation from official sources
+- Access recent articles and technical blogs
+- Pull content from Stack Overflow and technical forums
+- Gather external documentation for third-party libraries
+
+**Context:**
+The agent follows a tiered approach:
+1. First tries DeepWiki `ask_question` tool for repository documentation
+2. If insufficient, falls back to WebFetch/WebSearch for broader web research
+3. Executes strategic searches with multiple variations
+4. Fetches and analyzes content from authoritative sources
+
+**Search Strategy (Lines 24-46):**
+- Broad searches to understand landscape
+- Refined searches with specific technical terms
+- Site-specific searches (e.g., "site:docs.stripe.com webhook signature")
+- Prioritizes official documentation and reputable sources
+- Notes publication dates for currency
+
+---
+
+### 2. `.claude/agents/debugger.md`
+
+**Lines:** 1-56 (entire file)
+
+**Exact References:**
+- Line 4: `tools: Bash, Task, AskUserQuestion, Edit, Glob, Grep, NotebookEdit, NotebookRead, Read, TodoWrite, Write, ListMcpResourcesTool, ReadMcpResourceTool, mcp__deepwiki__ask_question, WebFetch, WebSearch`
+- Line 14: `- WebFetch/WebSearch: Retrieve web content for additional context if you don't find sufficient information in DeepWiki`
+- Line 45: `- Use WebFetch/WebSearch to gather additional context from web sources if needed`
+
+**Agent Name:** debugger
+
+**Purpose:**
+The debugger agent uses WebFetch/WebSearch as a fallback tool for:
+- Looking up external library documentation when errors involve third-party dependencies
+- Gathering additional context from web sources during debugging
+- Finding information about error messages or stack traces
+- Researching solutions to unexpected behavior
+
+**Context:**
+Web tools are used after DeepWiki in the debugging workflow:
+1. Capture error message and stack trace
+2. Use DeepWiki to look up external library documentation
+3. If DeepWiki is insufficient, use WebFetch/WebSearch for additional context
+4. Form and test hypotheses with the gathered information
+
+---
+
+### 3. `.claude/agents/reviewer.md`
+
+**Lines:** 1-96 (entire file)
+
+**Exact References:**
+- Line 4: `tools: Bash, Task, Glob, Grep, Read, TodoWrite, mcp__deepwiki__ask_question, WebFetch, WebSearch`
+
+**Agent Name:** reviewer
+
+**Purpose:**
+The reviewer agent has access to WebFetch and WebSearch in its tool list, but the configuration does not explicitly document their usage. They are available for:
+- Looking up documentation when reviewing code changes
+- Verifying best practices or patterns
+- Researching security implications or performance considerations
+
+**Context:**
+The reviewer focuses on identifying bugs and issues in code changes. Web tools may be used implicitly to research context about libraries, frameworks, or patterns encountered during review.
+
+---
+
+### 4. `.github/agents/codebase-online-researcher.md`
+
+**Lines:** 1-125 (entire file)
+
+**Exact References:**
+- Line 4: `tools: ["search", "read", "execute", "web", "deepwiki/ask_question"]`
+- Line 12: `You are an expert web research specialist focused on finding accurate, relevant information from web sources. Your primary tools are the DeepWiki \`ask_question\` tool and WebFetch/WebSearch tools`
+- Line 35: `Use WebFetch and WebSearch tools to retrieve full content from promising search results`
+
+**Agent Name:** codebase-online-researcher (GitHub platform variant)
+
+**Purpose:**
+Identical purpose to `.claude/agents/codebase-online-researcher.md`. This is the GitHub platform-specific configuration using different tool naming conventions:
+- Uses `"web"` tool instead of explicit `WebFetch` and `WebSearch`
+- Same research workflow and strategies
+- Same fallback pattern: DeepWiki first, then web search
+
+**Context:**
+The tool list uses abstracted names (`"web"` instead of `WebFetch, WebSearch`), but the description text explicitly mentions "WebFetch/WebSearch tools" at lines 12 and 35, indicating the underlying capabilities are the same.
+
+---
+
+### 5. `.github/agents/debugger.md`
+
+**Lines:** 1-68 (entire file)
+
+**Exact References:**
+- Line 4-13: Tools array includes `"web"` and `"deepwiki/ask_question"`
+- Line 26: `- WebFetch/WebSearch: Retrieve web content for additional context if you don't find sufficient information in DeepWiki`
+- Line 57: `- Use WebFetch/WebSearch to gather additional context from web sources if needed`
+
+**Agent Name:** debugger (GitHub platform variant)
+
+**Purpose:**
+Identical to `.claude/agents/debugger.md`. Uses web tools for:
+- Looking up external library documentation
+- Gathering additional debugging context from web sources
+- Finding solutions to errors and failures
+
+**Context:**
+Same debugging workflow, with web tools as fallback after DeepWiki.
+
+---
+
+### 6. `.opencode/agents/codebase-online-researcher.md`
+
+**Lines:** 1-126 (entire file)
+
+**Exact References:**
+- Line 8: `webfetch: true`
+- Line 13: `You are an expert web research specialist focused on finding accurate, relevant information from web sources. Your primary tools are the DeepWiki \`ask_question\` tool and \`webfetch\` tool`
+- Line 36: `Use webfetch tool to retrieve full content from promising search results`
+
+**Agent Name:** codebase-online-researcher (OpenCode platform variant)
+
+**Purpose:**
+Identical to other platform variants. Uses `webfetch` (lowercase, single tool) for:
+- Retrieving full content from promising search results
+- Fetching documentation and technical resources
+- Accessing web content for research synthesis
+
+**Context:**
+OpenCode platform uses a boolean flag `webfetch: true` in the tools section (line 8), and refers to it as a single `webfetch` tool rather than separate WebFetch/WebSearch tools.
+
+---
+
+### 7. `.opencode/agents/debugger.md`
+
+**Lines:** 1-63 (entire file)
+
+**Exact References:**
+- Line 8: `webfetch: true`
+- Line 19: `- WebFetch (\`webfetch\`): Retrieve web content for additional context if you don't find sufficient information in DeepWiki`
+- Line 51: `- Use WebFetch to gather additional context from web sources if needed`
+
+**Agent Name:** debugger (OpenCode platform variant)
+
+**Purpose:**
+Identical to other debugger variants. Uses `webfetch` for:
+- Retrieving web content for additional debugging context
+- Looking up documentation for external libraries
+
+**Context:**
+Same as other platforms, with OpenCode's `webfetch: true` boolean configuration style.
+
+---
+
+## Skill Configuration Files
+
+### 8. `.claude/skills/research-codebase/SKILL.md`
+
+**Lines:** 1-210 (entire file)
+
+**Exact References:**
+- Line 53-56: Instructions for using codebase-online-researcher agent:
+  ```
+  - If you perform a web search using the WebFetch/WebSearch tools, instruct the agent 
+    to return LINKS with their findings, and please INCLUDE those links in the research document
+  ```
+
+**Skill Name:** research-codebase
+
+**Purpose:**
+The skill itself doesn't use web tools directly, but instructs users to spawn the **codebase-online-researcher** agent for online research. When that agent uses WebFetch/WebSearch, the skill requires:
+- Agent to return links with findings
+- Links to be included in the final research document
+- Web search results to supplement live codebase findings
+
+**Context:**
+Part of the comprehensive research workflow (lines 50-58):
+1. Use codebase-locator, codebase-analyzer, and codebase-pattern-finder for codebase research
+2. Use codebase-research-locator and codebase-research-analyzer for research directory exploration
+3. Use **codebase-online-researcher** for external documentation (which uses WebFetch/WebSearch)
+4. Include web search findings and links in the research document
+
+---
+
+### 9. `.claude/skills/explain-code/SKILL.md`
+
+**Lines:** 1-205 (entire file)
+
+**Exact References:**
+- Line 12: `- **WebFetch/WebSearch**: Use to retrieve web content for additional context if information is not found in DeepWiki.`
+
+**Skill Name:** explain-code
+
+**Purpose:**
+WebFetch/WebSearch tools are available for the explain-code skill to:
+- Retrieve web content for additional context when explaining code
+- Look up external library documentation (after DeepWiki)
+- Find additional information about frameworks, patterns, or APIs
+
+**Context:**
+Part of "Available Tools" section (lines 7-12). Positioned as a fallback after DeepWiki:
+- Primary: DeepWiki `ask_question` tool for external library documentation
+- Fallback: WebFetch/WebSearch for additional context when DeepWiki is insufficient
+
+---
+
+### 10. `.github/skills/research-codebase/SKILL.md`
+
+**Lines:** 1-207 (entire file)
+
+**Exact References:**
+- Line 53-56: Identical to `.claude/skills/research-codebase/SKILL.md`:
+  ```
+  - If you perform a web search using the WebFetch/WebSearch tools, instruct the agent 
+    to return LINKS with their findings, and please INCLUDE those links in the research document
+  ```
+
+**Skill Name:** research-codebase (GitHub platform variant)
+
+**Purpose:**
+Identical to `.claude/skills/research-codebase/SKILL.md`. Instructs spawned codebase-online-researcher agent to use WebFetch/WebSearch and include links in research documents.
+
+---
+
+### 11. `.github/skills/explain-code/SKILL.md`
+
+**Lines:** 1-205 (entire file)
+
+**Exact References:**
+- Line 12: `- **WebFetch/WebSearch**: Use to retrieve web content for additional context if information is not found in DeepWiki.`
+
+**Skill Name:** explain-code (GitHub platform variant)
+
+**Purpose:**
+Identical to `.claude/skills/explain-code/SKILL.md`. Uses web tools as fallback for retrieving additional context.
+
+---
+
+### 12. `.opencode/skills/research-codebase/SKILL.md`
+
+**Lines:** 1-207 (entire file)
+
+**Exact References:**
+- Line 53-56: Similar to other platforms, but uses `webfetch` terminology:
+  ```
+  - If you perform a web search using the WebFetch/WebSearch tools, instruct the agent 
+    to return LINKS with their findings, and please INCLUDE those links in the research document
+  ```
+
+**Skill Name:** research-codebase (OpenCode platform variant)
+
+**Purpose:**
+Identical to other platform variants. Instructs spawned agents to use web tools and include links.
+
+---
+
+### 13. `.opencode/skills/explain-code/SKILL.md`
+
+**Lines:** 1-205 (entire file)
+
+**Exact References:**
+- Line 12: `- **WebFetch/WebSearch**: Use to retrieve web content for additional context if information is not found in DeepWiki.`
+
+**Skill Name:** explain-code (OpenCode platform variant)
+
+**Purpose:**
+Identical to other platform variants. Uses web tools as fallback for additional context.
+
+---
+
+## Source Code Files
+
+### 14. `src/sdk/clients/claude.ts`
+
+**Lines:** 270-288
+
+**Exact References:**
+- Line 284: `"WebFetch",`
+- Line 285: `"WebSearch",`
+
+**Context (Lines 270-288):**
+```typescript
+export class ClaudeAgentClient implements CodingAgentClient {
+    readonly agentType = "claude" as const;
+    private static readonly BUILTIN_ALLOWED_TOOLS = [
+        "Bash",
+        "Read",
+        "Write",
+        "Edit",
+        "Glob",
+        "Grep",
+        "Task",
+        "Skill",
+        "MultiEdit",
+        "TodoRead",
+        "TodoWrite",
+        "WebFetch",
+        "WebSearch",
+        "NotebookEdit",
+        "NotebookRead",
+    ] as const;
+```
+
+**Purpose:**
+This is the SDK implementation that defines which tools are available for Claude-based agents. `WebFetch` and `WebSearch` are included in the `BUILTIN_ALLOWED_TOOLS` array, making them available as built-in tools for any Claude agent to use.
+
+**Context:**
+- Part of the `ClaudeAgentClient` class implementation
+- Defines the allowed tools that can be used by agents running on the Claude platform
+- WebFetch and WebSearch are positioned alongside other core tools (Bash, Read, Write, Edit, etc.)
+- These tools are available by default for all Claude agents unless explicitly excluded in agent configuration
+
+---
+
+## Configuration Files
+
+### 15. `.opencode/opencode.json`
+
+**Lines:** 12-20
+
+**Exact References:**
+- Line 17: `"webfetch": "allow",`
+
+**Context (Lines 12-21):**
+```json
+{
+    "deepwiki_ask_question": true
+},
+"permission": {
+    "edit": "allow",
+    "bash": "allow",
+    "webfetch": "allow",
+    "doom_loop": "allow",
+    "external_directory": "allow"
+}
+```
+
+**Purpose:**
+This is the OpenCode platform configuration file that defines global permissions for tool usage. The `"webfetch": "allow"` permission grants agents running on the OpenCode platform the ability to use the webfetch tool.
+
+**Context:**
+- Part of the permission configuration for the OpenCode platform
+- Positioned alongside other permission settings (edit, bash, doom_loop, external_directory)
+- This global permission allows any OpenCode agent to use webfetch if they declare it in their tools section
+- The permission system provides a security layer, requiring both tool declaration in agent config AND global permission allowance
+
+---
+
+## Cross-Platform Tool Naming Conventions
+
+### Claude Platform (`.claude/`)
+- Uses: `WebFetch, WebSearch` (capitalized, two separate tools)
+- Tool list format: Comma-separated list in YAML frontmatter
+
+### GitHub Platform (`.github/`)
+- Uses: `"web"` (abstracted name for web capabilities)
+- References `WebFetch/WebSearch` in documentation text
+- Tool list format: JSON array with quoted strings
+
+### OpenCode Platform (`.opencode/`)
+- Uses: `webfetch` (lowercase, single tool)
+- References `webfetch` and sometimes `WebFetch` in documentation
+- Tool list format: Boolean flags (`webfetch: true`)
+- Requires global permission: `"webfetch": "allow"` in `opencode.json`
+
+---
+
+## Usage Patterns
+
+### Primary Use Case: External Documentation Research
+The **codebase-online-researcher** agent is the primary consumer of web tools:
+- Fetches official documentation for third-party libraries
+- Searches technical blogs and Stack Overflow
+- Retrieves recent articles and best practices
+- Gathers comparative information (e.g., "X vs Y")
+- Finds code examples and tutorials
+
+### Secondary Use Case: Debugging Context
+The **debugger** agent uses web tools as a fallback:
+- Looks up error messages and stack traces
+- Finds solutions to third-party library issues
+- Researches unexpected behavior
+- Gathers context when DeepWiki is insufficient
+
+### Tertiary Use Case: Code Review Context
+The **reviewer** agent has web tools available but doesn't explicitly document usage:
+- May research libraries or patterns during review
+- Could verify best practices or security considerations
+
+### Skill Integration
+Two skills reference web tools indirectly:
+- **research-codebase**: Spawns codebase-online-researcher which uses web tools
+- **explain-code**: Has direct access to web tools as fallback after DeepWiki
+
+---
+
+## Architectural Notes
+
+### Tiered Research Pattern
+All agents follow a consistent pattern:
+1. **First tier**: DeepWiki `ask_question` tool (repository-specific documentation)
+2. **Second tier**: WebFetch/WebSearch (broader web search)
+3. **Result**: Synthesis of both sources with proper attribution
+
+### Link Preservation
+When web tools are used, the system requires:
+- Direct links to sources be included in findings
+- Proper attribution with publication dates
+- Distinction between authoritative and informal sources
+
+### Security and Permissions
+- OpenCode platform requires explicit permission: `"webfetch": "allow"`
+- Claude and GitHub platforms include tools in builtin allowed list
+- Agents must declare tools in their configuration to use them
+
+---
+
+## Summary of Findings
+
+**Total Files with Web Search/Fetch References:** 15
+
+**Breakdown by Type:**
+- Agent configs: 7 (3 Claude, 2 GitHub, 2 OpenCode)
+- Skill configs: 6 (2 Claude, 2 GitHub, 2 OpenCode)
+- Source code: 1 (SDK client)
+- Configuration: 1 (OpenCode permissions)
+
+**Primary Agent:** codebase-online-researcher (3 platform variants)
+
+**Primary Purpose:** External documentation research and web content retrieval
+
+**Integration Pattern:** Fallback after DeepWiki tool, with proper link attribution required
+
+**Platform Differences:**
+- Claude: `WebFetch, WebSearch` (two tools)
+- GitHub: `"web"` (abstracted)
+- OpenCode: `webfetch` (single tool, requires permission)
+
+---
+
+## Files Not Containing References
+
+The following directories were searched but contain no web search/fetch references:
+- Other agent files (worker.md, codebase-analyzer.md, codebase-locator.md, etc.)
+- Other skill files (create-spec, frontend-design, gh-commit, etc.)
+- Other source files in `src/` (excluding claude.ts)
diff --git a/research/docs/2026-02-25-workflow-registration-flow.md b/research/docs/2026-02-25-workflow-registration-flow.md
new file mode 100644
index 0000000000..f2c5130164
--- /dev/null
+++ b/research/docs/2026-02-25-workflow-registration-flow.md
@@ -0,0 +1,328 @@
+# Workflow Registration Flow
+
+**Date:** 2026-02-25
+**Scope:** Custom workflow discovery, loading, registration, command creation, config files, CLI entry point.
+
+---
+
+## 1. Custom Workflow Discovery
+
+### `discoverWorkflowFiles()` (`src/ui/commands/workflow-commands.ts:343-372`)
+
+This function scans two filesystem paths for `.ts` files:
+
+**Search paths** are defined in the `CUSTOM_WORKFLOW_SEARCH_PATHS` constant at line 268-273:
+
+```typescript
+export const CUSTOM_WORKFLOW_SEARCH_PATHS = [
+    ".atomic/workflows",       // Local project workflows (highest priority)
+    "~/.atomic/workflows",     // Global user workflows
+];
+```
+
+The function iterates over these paths in order (line 349-369). For each path:
+
+1. Calls `expandPath()` (line 281-293) to resolve `~` to `$HOME` and relative paths to `process.cwd()`.
+2. Checks if the directory exists via `existsSync()` (line 354).
+3. Reads all entries with `fs.readdirSync()` (line 356).
+4. Filters for files ending in `.ts` (line 358).
+5. Tags each discovered file with a `source` label: index `0` is `"local"`, all others are `"global"` (line 352).
+
+**Return type:** An array of `{ path: string; source: "local" | "global" }` objects (line 343-346).
+
+### `loadWorkflowsFromDisk()` (`src/ui/commands/workflow-commands.ts:401-471`)
+
+This async function calls `discoverWorkflowFiles()` at line 402, then dynamically imports each `.ts` file and extracts workflow metadata.
+
+**Per-file processing** (line 406-467):
+
+1. `await import(path)` at line 409 performs a dynamic ESM import of the workflow file.
+2. The workflow name is extracted from `module.name`; if absent, falls back to the filename without extension (line 412-414).
+3. **Deduplication by name:** If a workflow name (lowercased) has already been loaded, it is skipped (line 417-419). Since local paths are discovered before global paths, local workflows take priority.
+4. Metadata fields are extracted from the module's exports (line 426-436):
+   - `name` (string)
+   - `description` (string, defaults to `"Custom workflow: ${name}"`)
+   - `aliases` (string array, optional)
+   - `defaultConfig` (Record, optional)
+   - `version` (string, optional)
+   - `minSDKVersion` (string, optional)
+   - `stateVersion` (number, optional)
+   - `migrateState` (function, optional -- checked via `typeof` at line 421-424)
+   - `source` (`"local"` or `"global"`, from the discovery step)
+5. If `minSDKVersion` is present, it is validated as semver via `parseSemver()` (line 438-452). If it is newer than the current SDK `VERSION`, a warning is printed to console.
+6. Results are stored in the module-level `loadedWorkflows` variable (line 469).
+
+### What a custom workflow file needs to export
+
+A `.ts` file placed in `.atomic/workflows/` or `~/.atomic/workflows/` is dynamically imported. It should export any of these named exports:
+
+| Export | Type | Required | Default |
+|---|---|---|---|
+| `name` | `string` | No | Filename without `.ts` |
+| `description` | `string` | No | `"Custom workflow: ${name}"` |
+| `aliases` | `string[]` | No | `undefined` |
+| `defaultConfig` | `Record<string, unknown>` | No | `undefined` |
+| `version` | `string` (semver) | No | `undefined` |
+| `minSDKVersion` | `string` (semver) | No | `undefined` |
+| `stateVersion` | `number` | No | `undefined` |
+| `migrateState` | `(oldState: unknown, fromVersion: number) => BaseState` | No | `undefined` |
+
+The test file at `src/ui/commands/workflow-commands.test.ts:91-99` demonstrates a minimal workflow file:
+
+```typescript
+export const name = "versioned-discovery";
+export const description = "Local versioned workflow";
+export const version = "3.0.0";
+export const minSDKVersion = "...";
+export const stateVersion = 7;
+```
+
+---
+
+## 2. Workflow Registration Flow (Startup to Command Registration)
+
+### Step 1: CLI entry point (`src/cli.ts`)
+
+The main function at line 273-298 calls `program.parseAsync()` at line 281. When the `chat` subcommand is invoked (or defaulted to, since it is marked `isDefault: true` at line 95), the action handler at line 127 eventually calls `chatCommand()` at line 163.
+
+### Step 2: Chat command (`src/commands/chat.ts`)
+
+`chatCommand()` at line 196 creates an SDK client at line 243, starts it at line 251, builds a `ChatUIConfig` at line 267-284, and calls `startChatUI(client, chatConfig)` at line 287.
+
+### Step 3: Start Chat UI (`src/ui/index.ts`)
+
+`startChatUI()` is defined at line 306. Before rendering the React tree, at line 2022 it calls:
+
+```typescript
+await initializeCommandsAsync();
+```
+
+### Step 4: Initialize commands (`src/ui/commands/index.ts:87-107`)
+
+`initializeCommandsAsync()` performs the full registration sequence:
+
+1. **Line 91:** `registerBuiltinCommands()` -- registers built-in slash commands (help, theme, clear, compact).
+2. **Line 94:** `await loadWorkflowsFromDisk()` -- discovers and imports custom `.ts` workflow files from `.atomic/workflows/` and `~/.atomic/workflows/`. Populates the module-level `loadedWorkflows` array.
+3. **Line 95:** `registerWorkflowCommands()` -- creates `CommandDefinition` objects for all workflows and registers them with the global registry.
+4. **Line 99:** `await discoverAndRegisterDiskSkills()` -- loads skills from disk.
+5. **Line 103:** `await registerAgentCommands()` -- loads agent commands from disk.
+
+Returns the count of newly registered commands (line 106).
+
+### Step 5: Register workflow commands (`src/ui/commands/workflow-commands.ts:899-907`)
+
+`registerWorkflowCommands()` calls `getWorkflowCommands()` at line 900, which in turn calls `getAllWorkflows()` at line 873 and maps each `WorkflowMetadata` through `createWorkflowCommand()`.
+
+`getAllWorkflows()` (line 477-506) merges dynamically loaded workflows with built-in definitions:
+1. First adds all dynamically loaded workflows from `loadedWorkflows` (line 482-494), tracking names and aliases.
+2. Then adds built-in workflows from `BUILTIN_WORKFLOW_DEFINITIONS` (line 497-503) only if their name has not already been seen. This means disk-loaded workflows override built-ins.
+
+For each command returned by `getWorkflowCommands()`, `registerWorkflowCommands()` checks `globalRegistry.has(command.name)` at line 903 and only registers if not already present. This makes the function idempotent.
+
+### Built-in workflow definitions (`src/ui/commands/workflow-commands.ts:520-531`)
+
+```typescript
+const BUILTIN_WORKFLOW_DEFINITIONS: WorkflowMetadata[] = [
+    {
+        name: "ralph",
+        description: "Start autonomous implementation workflow",
+        aliases: ["loop"],
+        version: "1.0.0",
+        minSDKVersion: VERSION,
+        stateVersion: 1,
+        argumentHint: '"<prompt-or-spec-path>"',
+        source: "builtin",
+    },
+];
+```
+
+There is exactly one built-in workflow: `ralph` (alias `loop`).
+
+### Command registry (`src/ui/commands/registry.ts`)
+
+`CommandRegistry` at line 303 stores commands in a `Map<string, CommandDefinition>` (line 305) and aliases in a `Map<string, string>` (line 308). Registration at line 316-340 checks for name/alias conflicts and throws on collision. The global singleton `globalRegistry` is exported at line 534.
+
+---
+
+## 3. The Gap for Non-Ralph Workflows: `createWorkflowCommand()` Generic Handler
+
+### Dispatch logic (`src/ui/commands/workflow-commands.ts:543-595`)
+
+`createWorkflowCommand()` checks `metadata.name === "ralph"` at line 545. If true, it delegates to `createRalphCommand()` (line 546-547). For all other workflow names, it returns a generic `CommandDefinition` (line 549-594).
+
+### What the generic handler does (lines 555-593)
+
+The `execute` function is **synchronous** (returns `CommandResult` directly, not a Promise):
+
+1. **Active workflow check** (line 557-562): If `context.state.workflowActive` is already true, returns failure with message indicating a workflow is already active.
+
+2. **Prompt extraction** (line 565): Trims `args` to get the initial prompt. If empty, returns failure with usage message (line 567-572).
+
+3. **System message** (line 575-578): Calls `context.addMessage("system", ...)` with a message indicating the workflow is starting, including the workflow name and prompt.
+
+4. **State update** (line 581-592): Returns a `CommandResult` with `success: true` and a `stateUpdate` object:
+   ```typescript
+   {
+       workflowActive: true,
+       workflowType: metadata.name,
+       initialPrompt,
+       pendingApproval: false,
+       specApproved: undefined,
+       feedback: null,
+   }
+   ```
+
+The generic handler does **not**:
+- Create a workflow session
+- Build or execute a graph
+- Spawn sub-agents
+- Call `streamAndWait()` or `streamGraph()`
+- Set `context.setStreaming(true)`
+
+### What happens after the generic handler returns
+
+When `ChatApp` receives a `CommandResult` with a `stateUpdate`, the handler at `src/ui/chat.tsx:4073-4086` applies each field from `result.stateUpdate` to the `workflowState` via `updateWorkflowState()`.
+
+This triggers the React effect at `src/ui/chat.tsx:2534-2689`:
+
+```typescript
+// Auto-start workflow when workflowActive becomes true with an initialPrompt.
+// This handles non-context-clear workflow starts (e.g., generic workflow commands).
+```
+
+The effect checks (line 2540-2543):
+- `workflowState.workflowActive` is true
+- `workflowState.initialPrompt` is non-null
+- The prompt has not already been started (deduplication via `workflowStartedRef`)
+- Not currently streaming
+
+When all conditions are met, after a 100ms delay (line 2547), it sends `workflowState.initialPrompt` through the normal `onStreamMessage` handler (line 2566). This passes the prompt to the underlying SDK agent as a regular chat message. The agent receives the prompt and responds via the standard streaming path -- there is no graph execution, no structured task decomposition, and no sub-agent orchestration.
+
+In other words: **the generic handler turns the prompt into a single standard agent message**, relying entirely on the agent's own capabilities to handle the workflow task.
+
+---
+
+## 4. Config Files
+
+### `.atomic/settings.json` (`src/utils/atomic-config.ts`)
+
+**Schema** (`AtomicConfig` interface, line 23-32):
+
+```typescript
+export interface AtomicConfig {
+  version?: number;
+  agent?: AgentKey;         // "claude" | "opencode" | "copilot"
+  scm?: SourceControlType;  // "github" | "sapling"
+  lastUpdated?: string;
+}
+```
+
+**Resolution order** (documented at line 4-8, implemented at line 85-91):
+1. Local: `{projectDir}/.atomic/settings.json` (higher priority)
+2. Global: `~/.atomic/settings.json` (lower priority)
+
+`readAtomicConfig()` at line 85 reads both files, parses them with `pickAtomicConfig()` (line 53-68), and merges them with `mergeConfigs()` (line 70-80) where local fields override global fields.
+
+`saveAtomicConfig()` at line 96 writes to the local path only, always setting `version: 1` and updating `lastUpdated`. It also injects a `$schema` URL from `SETTINGS_SCHEMA_URL` (line 116).
+
+### `src/config.ts` -- Agent Configuration
+
+Defines the `AGENT_CONFIG` record (line 29-70) mapping agent keys (`"claude"`, `"opencode"`, `"copilot"`) to `AgentConfig` objects. Each contains:
+- `name`, `cmd`, `additional_flags` -- for spawning the agent CLI
+- `folder` -- config directory (`.claude`, `.opencode`, `.github`)
+- `install_url`, `exclude`, `additional_files`, `preserve_files`, `merge_files` -- for the `init` command's config copy logic
+
+Also defines `SCM_CONFIG` (line 114-134) for source control management configurations.
+
+**This file contains no workflow-related configuration.**
+
+### `src/utils/settings.ts` (referenced by `src/commands/chat.ts:17`)
+
+Provides `getModelPreference()` and `getReasoningEffortPreference()` which read from `.atomic/settings.json` (local then global). These are used by `chatCommand()` to determine model settings.
+
+### `.atomic/workflows/` directories
+
+There are no `.atomic/workflows/` directories in the project tree itself (glob returned no results). These directories are searched dynamically at runtime by `discoverWorkflowFiles()` for user-authored custom workflows.
+
+### Workflow session directories
+
+Workflow sessions are stored at `~/.atomic/workflows/sessions/{sessionId}/` as defined in `src/workflows/session.ts:32-37`:
+
+```typescript
+export const WORKFLOW_SESSIONS_DIR = join(homedir(), ".atomic", "workflows", "sessions");
+```
+
+Each session gets a `session.json`, `tasks.json`, and subdirectories `checkpoints/`, `agents/`, and `logs/` (created at line 59-62).
+
+---
+
+## 5. CLI Entry Point (`src/cli.ts`)
+
+### Program creation (`createProgram()`, line 42-222)
+
+Uses Commander.js (`@commander-js/extra-typings`). Defines these commands:
+- `init` (line 75-91)
+- `chat` (line 94-173, **default command** via `isDefault: true`)
+- `config set` (line 176-188)
+- `update` (line 191-196)
+- `uninstall` (line 199-212)
+- `upload-telemetry` (hidden, line 216-220)
+
+### `main()` (line 273-298)
+
+1. Calls `cleanupWindowsLeftoverFiles()` (line 276).
+2. Calls `program.parseAsync()` (line 281) which dispatches to the matched command action.
+3. Spawns telemetry upload (line 284).
+
+### How workflows get loaded
+
+Workflows are **not** loaded at the CLI level. The CLI entry point delegates to `chatCommand()` which delegates to `startChatUI()` which calls `initializeCommandsAsync()`. The workflow loading happens entirely within the TUI initialization, not during CLI argument parsing.
+
+The flow is:
+```
+src/cli.ts:main()
+  -> program.parseAsync()
+    -> chat command action (line 127)
+      -> chatCommand() in src/commands/chat.ts:196
+        -> startChatUI() in src/ui/index.ts:306
+          -> initializeCommandsAsync() in src/ui/commands/index.ts:87
+            -> loadWorkflowsFromDisk() (line 94)
+            -> registerWorkflowCommands() (line 95)
+```
+
+---
+
+## Summary Data Flow
+
+```
+CLI (src/cli.ts:281)
+  |
+  v
+chatCommand (src/commands/chat.ts:196)
+  |
+  v
+startChatUI (src/ui/index.ts:306)
+  |
+  v
+initializeCommandsAsync (src/ui/commands/index.ts:87)
+  |
+  +-- registerBuiltinCommands() .................. line 91
+  +-- loadWorkflowsFromDisk() .................... line 94
+  |     +-- discoverWorkflowFiles() .............. workflow-commands.ts:343
+  |     |     reads .atomic/workflows/*.ts
+  |     |     reads ~/.atomic/workflows/*.ts
+  |     +-- import(path) for each file ........... workflow-commands.ts:409
+  |     +-- populates module-level loadedWorkflows
+  |
+  +-- registerWorkflowCommands() ................. line 95
+  |     +-- getWorkflowCommands() ................ workflow-commands.ts:872
+  |     |     +-- getAllWorkflows() ............... workflow-commands.ts:477
+  |     |     |     merges loadedWorkflows + BUILTIN_WORKFLOW_DEFINITIONS
+  |     |     +-- .map(createWorkflowCommand) .... workflow-commands.ts:543
+  |     |           if name === "ralph" -> createRalphCommand()
+  |     |           else -> generic handler (state-only, no graph)
+  |     +-- globalRegistry.register(command) ..... workflow-commands.ts:904
+  |
+  +-- discoverAndRegisterDiskSkills() ............ line 99
+  +-- registerAgentCommands() .................... line 103
+```
diff --git a/research/docs/2026-02-25-workflow-sdk-design.md b/research/docs/2026-02-25-workflow-sdk-design.md
new file mode 100644
index 0000000000..be63d3a525
--- /dev/null
+++ b/research/docs/2026-02-25-workflow-sdk-design.md
@@ -0,0 +1,462 @@
+# WorkflowSDK Design Documentation
+
+**Date:** 2026-02-25
+**Scope:** `src/workflows/graph/sdk.ts` and all runtime dependencies
+
+---
+
+## 1. WorkflowSDK Class
+
+**File:** `/home/alilavaee/Documents/projects/workflow-sdk/src/workflows/graph/sdk.ts`
+
+### Overview
+
+`WorkflowSDK` is a high-level facade that wires together provider clients, subagent infrastructure, and graph execution into a single entry point. It is instantiated via the static `WorkflowSDK.init()` factory (line 123) because the constructor is private (line 66). The constructor validates that at least one provider is supplied (line 68-70), then builds four internal dependency objects: `providerRegistry`, `subagentBridge`, `subagentRegistry`, and `runtimeDependencies`.
+
+### Type: `WorkflowSDKConfig`
+
+Defined at lines 32-43, this is the configuration interface passed to `WorkflowSDK.init()`:
+
+| Field | Type | Description |
+|---|---|---|
+| `providers` | `Record<string, CodingAgentClient>` | **Required.** Keyed by provider name (e.g., `"claude"`, `"copilot"`). Must have at least one entry. |
+| `workflows` | `Map<string, WorkflowRegistration<BaseState>>` | Optional. Pre-registered named workflows for subgraph resolution. |
+| `agents` | `Map<string, AgentInfo>` | Optional. Agent definitions to populate the `SubagentTypeRegistry`. |
+| `checkpointer` | `CheckpointerType` | Optional. One of `"memory"`, `"file"`, `"research"`, `"session"`. |
+| `checkpointerOptions` | `CreateCheckpointerOptions<BaseState>` | Optional. Passed to `createCheckpointer()`. |
+| `validation` | `boolean` | Optional. Defaults to `true`. When `false`, `outputSchema` is stripped from graphs. |
+| `defaultModel` | `ModelSpec` | Optional. Default model spec applied to graphs that lack one. |
+| `maxSteps` | `number` | Optional. Safety limit applied to `ExecutionOptions.maxSteps`. |
+| `subagentProvider` | `string` | Optional. Explicit provider name for subagent session creation. |
+| `subagentSessionDir` | `string` | Optional. Passed to `SubagentGraphBridge` for result persistence. |
+
+### Type: `WorkflowRegistration`
+
+Defined at lines 25-27. A union type representing what can be stored as a named workflow:
+
+```typescript
+type WorkflowRegistration<TState extends BaseState = BaseState> =
+  | CompiledSubgraph<TState>   // Has an .execute() method
+  | CompiledGraph<TState>;     // A full compiled graph
+```
+
+The helper `hasExecute()` (lines 45-49) distinguishes between the two at runtime.
+
+### Initialization Flow (`constructor`, lines 66-118)
+
+1. **Provider wrapping** (lines 72-75): Each entry in `config.providers` is wrapped in a `ClientBackedAgentProvider` instance, creating an `agentProviders` record.
+
+2. **ProviderRegistry** (line 77): Constructed from the `agentProviders` record. Stored as the public readonly field `this.providerRegistry`.
+
+3. **Clients map** (line 78): The raw `CodingAgentClient` entries are stored as a `ReadonlyMap<string, CodingAgentClient>` for the `clientProvider` runtime dependency.
+
+4. **Workflows map** (line 79): Initialized from `config.workflows` or an empty map. Mutable -- new workflows can be added via `registerWorkflow()`.
+
+5. **Checkpointer** (lines 80-82): If `config.checkpointer` is provided, calls `createCheckpointer()` from `checkpointer.ts`.
+
+6. **Validation** (line 83): `validationEnabled` defaults to `true`.
+
+7. **Subagent provider resolution** (lines 87-90): Calls `resolveSubagentProviderName()` to determine which provider creates subagent sessions. Resolution order:
+   - Explicit `config.subagentProvider` (line 184)
+   - Provider name extracted from `defaultModel` if it has a `"provider/model"` format and that provider is registered (lines 188-193)
+   - First registered provider in the registry (line 195)
+
+8. **SubagentGraphBridge** (lines 92-101): Created with a `createSession` factory closure that calls `providerRegistry.get(subagentProviderName).createSession(sessionConfig)` and an optional `sessionDir`.
+
+9. **SubagentTypeRegistry** (lines 103-110): A fresh `SubagentTypeRegistry` is created. If `config.agents` is provided, each entry is registered with `name`, `info`, and `source` fields.
+
+10. **Runtime dependencies** (lines 112-117): The `GraphRuntimeDependencies` object is assembled with four fields:
+    - `clientProvider`: A closure that looks up clients from `this.clients` by agent type name.
+    - `subagentBridge`: The `SubagentGraphBridge` instance.
+    - `subagentRegistry`: The `SubagentTypeRegistry` instance.
+    - `workflowResolver`: A closure calling `this.resolveWorkflow(name)`.
+
+### Public Methods
+
+#### `static init(config: WorkflowSDKConfig): WorkflowSDK` (line 123)
+
+Factory method. Delegates to the private constructor.
+
+#### `graph<TState>(): GraphBuilder<TState>` (lines 130-132)
+
+Returns a fresh `GraphBuilder` instance by calling the `graph()` factory function from `builder.ts`. This is a convenience method that does not inject any SDK context into the builder itself -- the runtime dependencies are applied later when `execute()` or `stream()` is called.
+
+#### `execute<TState>(compiled, options?): Promise<ExecutionResult<TState>>` (lines 137-144)
+
+Executes a compiled graph to completion:
+1. Calls `applyGraphDefaults(compiled)` to inject SDK-level checkpointer, defaultModel, validation settings, and runtime dependencies into the graph config.
+2. Calls `applyExecutionDefaults(options)` to inject `maxSteps` if configured.
+3. Delegates to `executeGraph()` from `compiled.ts`.
+
+#### `stream<TState>(compiled, options?): AsyncGenerator<StreamEvent<TState>>` (lines 149-157)
+
+Streams execution events:
+1. Destructures `modes` from options.
+2. Calls `applyGraphDefaults(compiled)`.
+3. Creates a `GraphExecutor` via `createExecutor()`.
+4. Calls `routeStream()` on the executor's stream with the selected modes.
+
+#### `registerWorkflow(name, workflow): void` (lines 162-164)
+
+Adds a workflow to the internal `workflows` map. This makes it available for subgraph resolution via the `workflowResolver` dependency.
+
+#### `destroy(): Promise<void>` (lines 169-171)
+
+Stops all managed provider clients by calling `.stop()` on each `CodingAgentClient` in `this.clients`.
+
+#### `getSubagentBridge(): SubagentGraphBridge` (lines 176-178)
+
+Accessor for the internal subagent bridge instance.
+
+### Private Methods
+
+#### `resolveSubagentProviderName(explicitProvider, defaultModel): string` (lines 180-196)
+
+Determines which provider to use for subagent sessions. Resolution priority:
+1. `explicitProvider` if provided.
+2. Provider name parsed from `defaultModel` (format: `"provider/model"`) if that provider exists in the registry.
+3. First provider in the registry.
+
+#### `resolveWorkflow(name): CompiledSubgraph<BaseState> | null` (lines 198-214)
+
+Looks up a named workflow from the `workflows` map. If the workflow is a `CompiledSubgraph` (has `.execute()`), it is returned directly. If it is a `CompiledGraph`, it is wrapped in a `CompiledSubgraph` adapter that calls `this.execute(workflow, { initialState: state })` and returns `result.state`.
+
+#### `applyGraphDefaults<TState>(compiled): CompiledGraph<TState>` (lines 216-263)
+
+Merges SDK-level defaults into a compiled graph's config, producing a new graph object only if changes are needed:
+- Injects `this.checkpointer` if the graph has none (lines 222-225).
+- Injects `this.defaultModel` if the graph has none (lines 227-229).
+- Strips `outputSchema` if validation is disabled (lines 232-235).
+- Fills in runtime dependencies (`clientProvider`, `workflowResolver`, `subagentBridge`, `subagentRegistry`) where the graph config does not already define them (lines 237-253).
+
+#### `applyExecutionDefaults<TState>(options?): ExecutionOptions<TState> | undefined` (lines 265-276)
+
+Injects `this.maxSteps` into execution options if the SDK has a maxSteps configured and the caller did not provide one.
+
+---
+
+## 2. WorkflowSDK Tests
+
+**File:** `/home/alilavaee/Documents/projects/workflow-sdk/src/workflows/graph/sdk.test.ts`
+
+### Test Infrastructure
+
+- **`createMockSession(id)`** (lines 18-41): Returns a mock `Session` with `send`, `stream`, `summarize`, `getContextUsage`, `getSystemToolsTokens`, and `destroy` methods. The `stream` method yields a single text message.
+
+- **`createMockClient(agentType, options?)`** (lines 43-88): Returns a mock `CodingAgentClient` with optional hooks: `onCreateSession` callback for tracking session creation, and `streamPrefix` for customizing stream output content.
+
+- **Cleanup** (lines 90-95): An `afterEach` hook destroys all SDK instances tracked in the `sdkInstances` array.
+
+### Test Scenarios
+
+1. **"init throws when providers are empty"** (lines 98-102): Verifies that `WorkflowSDK.init({ providers: {} })` throws the expected error message.
+
+2. **"init uses defaultModel provider for subagent sessions when available"** (lines 104-142): Creates an SDK with `claude` and `copilot` providers, sets `defaultModel: "copilot/gpt-5"`, and executes a subagent node. Asserts that the subagent output contains `"copilot:Summarize"`, confirming the `copilot` provider was used because `defaultModel` starts with `"copilot/"`.
+
+3. **"init honors explicit subagentProvider over defaultModel provider"** (lines 144-183): Same setup as above but with `subagentProvider: "claude"`. Asserts output contains `"claude:Summarize"`, confirming the explicit provider takes precedence over the `defaultModel`-derived provider.
+
+4. **"init wires provider and workflow resolver runtime dependencies"** (lines 185-217): Creates an SDK with a mock workflow (a `CompiledSubgraph` with an `execute` function that sets `outputs.resolved = true`). Builds a graph with an `agentNode` followed by a `subgraphNode("demo")`. Asserts that both nodes execute successfully: the agent node produces output and the subgraph workflow's `resolved: true` appears in the final state.
+
+5. **"init configures subagent bridge and registry entries for node execution"** (lines 219-254): Registers an agent named `"codebase-analyzer"` via `config.agents`. Executes a subagent node that references that agent name. Asserts the output contains `"stream:Summarize"`, confirming the bridge and registry are wired correctly.
+
+6. **"subagent node spawning resolves provider via ProviderRegistry"** (lines 256-306): Creates an SDK with two providers (`claude` and `copilot`), sets `subagentProvider: "copilot"`. Runs a graph with an `agentNode` (type `"claude"`) followed by a `subagentNode`. Tracks session creation callbacks. Asserts: (a) subagent output comes from copilot (`"copilot:Delegated task"`), (b) claude created exactly 1 session (for the agentNode), (c) copilot created exactly 1 session (for the subagent).
+
+7. **"execute and stream use SDK entry points"** (lines 308-330): Creates a simple tool node, executes via `sdk.execute()`, then streams via `sdk.stream()` with `modes: ["updates"]`. Asserts execute returns `"completed"` status and stream yields exactly one update event.
+
+8. **"stream uses router defaults and validator-protected state"** (lines 332-384): Creates a node that sets `counter: 1` but the compile-time `outputSchema` requires `counter >= 2`. Streams with `modes: ["updates"]` and gets zero events (update is rejected by validation). Then streams with no explicit modes (defaults to `"values"`) and gets one event where `counter` is `undefined` (the invalid update was not applied).
+
+9. **"stream executes full WorkflowSDK.stream() path across modes"** (lines 386-478): A two-node graph where the first node has a retry config (`maxAttempts: 2`) and an outputSchema requiring `counter >= 2`. The first node increments a counter and emits a `"progress"` event. The test verifies all four stream modes (`values`, `updates`, `events`, `debug`) produce the correct events in the expected order, including retry count and resolved model in debug traces.
+
+---
+
+## 3. Provider Registry
+
+**File:** `/home/alilavaee/Documents/projects/workflow-sdk/src/workflows/graph/provider-registry.ts`
+
+### AgentProvider Interface (lines 6-10)
+
+```typescript
+interface AgentProvider {
+  name: string;
+  createSession(config: SessionConfig): Promise<Session>;
+  supportedModels(): string[];
+}
+```
+
+Defines the contract for any provider that can create agent sessions.
+
+### ProviderRegistry Class (lines 15-33)
+
+An immutable registry that stores `AgentProvider` instances keyed by name.
+
+**Constructor** (lines 18-19): Accepts a `Record<string, AgentProvider>` and converts it to a `ReadonlyMap`.
+
+**Methods:**
+- `get(name): AgentProvider | undefined` (lines 22-24) -- Lookup by name.
+- `list(): string[]` (lines 26-28) -- Returns all registered provider names as an array.
+- `has(name): boolean` (lines 30-32) -- Checks if a provider exists.
+
+The registry is immutable after construction. It is constructed once during `WorkflowSDK.init()` at line 77 of `sdk.ts` and stored as the public readonly field `providerRegistry`.
+
+---
+
+## 4. Agent Providers
+
+**File:** `/home/alilavaee/Documents/projects/workflow-sdk/src/workflows/graph/agent-providers.ts`
+
+### ClientBackedAgentProvider (lines 24-57)
+
+Wraps a `CodingAgentClient` as an `AgentProvider`. This is the core adapter used by `WorkflowSDK`.
+
+**Constructor** (lines 30-34): Accepts `ClientBackedProviderConfig` with `name`, `client`, and optional `supportedModels`.
+
+**Lazy start** (lines 45-56): The `ensureStarted()` method lazily calls `client.start()` the first time a session is created. The resulting promise is stored in `startPromise` so subsequent calls await the same promise. If `start()` fails, `startPromise` is reset to `null` so the next attempt retries.
+
+**`createSession(config)`** (lines 36-39): Awaits `ensureStarted()`, then delegates to `this.client.createSession(config)`.
+
+**`supportedModels()`** (lines 41-43): Returns a copy of the models array.
+
+### Provider Factory Functions
+
+Each factory creates a `ClientBackedAgentProvider` with a provider-specific client:
+
+- **`createClaudeAgentProvider(options?)`** (lines 97-105): Uses `createClaudeAgentClient()` from the SDK clients. Default supported models: `["opus", "sonnet", "haiku"]` (line 12).
+
+- **`createOpenCodeAgentProvider(options?)`** (lines 110-118): Uses `createOpenCodeClient(options.clientOptions)`. Default supported models: empty array.
+
+- **`createCopilotAgentProvider(options?)`** (lines 123-131): Uses `createCopilotClient(options.clientOptions)`. Default supported models: empty array.
+
+### createDefaultProviderRegistry (lines 136-144)
+
+Constructs a `ProviderRegistry` with all three providers (claude, opencode, copilot) pre-registered. Each provider uses defaults unless overridden via `DefaultProviderRegistryOptions`.
+
+---
+
+## 5. SubagentGraphBridge
+
+**File:** `/home/alilavaee/Documents/projects/workflow-sdk/src/workflows/graph/subagent-bridge.ts`
+
+### Overview
+
+The bridge creates one session per sub-agent invocation, sends the task as a message, collects the streaming response, and destroys the session. It relies on the provider's native sub-agent dispatch for tool configuration and model selection.
+
+### Key Types
+
+- **`CreateSessionFn`** (line 57): `(config?: SessionConfig) => Promise<Session>` -- Factory function injected at construction.
+
+- **`SubagentSpawnOptions`** (lines 62-79): Configuration for a single sub-agent spawn. Fields: `agentId`, `agentName`, `task`, optional `systemPrompt`, `model`, `tools`, `timeout`, and `abortSignal`.
+
+- **`SubagentResult`** (lines 84-97): Returned after sub-agent completes. Fields: `agentId`, `success`, `output` (truncated to 4000 chars), optional `error`, `toolUses`, `durationMs`.
+
+### Constructor (lines 132-135)
+
+Accepts a `SubagentGraphBridgeConfig` with:
+- `createSession`: The session factory closure (provided by `WorkflowSDK` at line 93-98 of `sdk.ts`).
+- `sessionDir`: Optional path for persisting results.
+
+### `setSessionDir(dir)` (lines 137-139)
+
+Allows updating the session directory after construction.
+
+### `spawn(options): Promise<SubagentResult>` (lines 144-268)
+
+The primary execution method:
+
+1. **Session creation** (lines 152-157): Builds a `SessionConfig` from `options` (systemPrompt, model, tools) and calls `this.createSession(sessionConfig)`.
+
+2. **Abort handling** (lines 159-176): Creates an `AbortController`. If `options.timeout` is set, a `setTimeout` calls `abort()`. If `options.abortSignal` is provided, its abort event is forwarded to the internal controller.
+
+3. **Streaming** (lines 182-189): Wraps `session.stream(options.task)` in `abortableAsyncIterable()` (lines 23-48) which races each iterator step against the abort signal. Collects text content into `summaryParts` and counts `tool_use` messages.
+
+4. **Abort result** (lines 202-218): If aborted, optionally calls `session.abort()`, then returns a failure result distinguishing between external abort ("was cancelled") and timeout.
+
+5. **Success result** (lines 220-239): Truncates the summary to `MAX_SUMMARY_LENGTH` (4000 chars, line 104). If `sessionDir` is set, calls `saveSubagentOutput()` from `../session.ts`.
+
+6. **Error handling** (lines 240-258): Catches any error, constructs a failure result, and optionally persists it.
+
+7. **Cleanup** (lines 259-266): Always destroys the session in a `finally` block.
+
+### `spawnParallel(agents, abortSignal?): Promise<SubagentResult[]>` (lines 276-303)
+
+Spawns multiple sub-agents concurrently using `Promise.allSettled()`. If an external `abortSignal` is provided, it is forwarded to each individual spawn call. Rejected promises are converted to failure results.
+
+### Helper: `abortableAsyncIterable` (lines 23-48)
+
+Wraps an `AsyncIterable<T>` so that it rejects immediately when the abort signal fires, using `Promise.race()` between `iterator.next()` and an abort-triggered rejection promise.
+
+---
+
+## 6. SubagentTypeRegistry
+
+**File:** `/home/alilavaee/Documents/projects/workflow-sdk/src/workflows/graph/subagent-registry.ts`
+
+### SubagentEntry (lines 20-24)
+
+```typescript
+interface SubagentEntry {
+  name: string;
+  info: AgentInfo;
+  source: AgentSource;
+}
+```
+
+### SubagentTypeRegistry Class (lines 33-55)
+
+An in-memory `Map<string, SubagentEntry>` with these methods:
+- `register(entry)` (lines 36-38): Stores an entry keyed by `entry.name`.
+- `get(name)` (lines 40-42): Lookup by name.
+- `has(name)` (lines 44-46): Existence check.
+- `getAll()` (lines 48-50): Returns all entries as an array.
+- `clear()` (lines 52-54): Removes all entries.
+
+### `populateSubagentRegistry(registry)` (lines 64-75)
+
+Calls `discoverAgentInfos()` from `agent-commands.ts` to find agent definitions from config directories. Iterates over discovered agents and registers each one. Project-local agents overwrite user-global agents on name conflict (because `discoverAgentInfos()` returns them in that priority order). Returns the total count of agents in the registry.
+
+### Usage in WorkflowSDK
+
+In `sdk.ts` lines 103-110, the `WorkflowSDK` constructor creates a `SubagentTypeRegistry` and populates it from `config.agents` (not from disk discovery via `populateSubagentRegistry`). This means the SDK relies on pre-discovered agents passed in via configuration, rather than discovering them itself.
+
+---
+
+## 7. Runtime Dependencies (`GraphRuntimeDependencies`)
+
+**File:** `/home/alilavaee/Documents/projects/workflow-sdk/src/workflows/graph/types.ts`, lines 396-407
+
+```typescript
+interface GraphRuntimeDependencies {
+  clientProvider?: (agentType: string) => CodingAgentClient | null;
+  workflowResolver?: (name: string) => RuntimeSubgraph | null;
+  subagentBridge?: {
+    spawn(agent: SubagentSpawnOptions, abortSignal?: AbortSignal): Promise<SubagentResult>;
+    spawnParallel(agents: SubagentSpawnOptions[], abortSignal?: AbortSignal): Promise<SubagentResult[]>;
+  };
+  subagentRegistry?: {
+    get(name: string): SubagentEntry | undefined;
+    getAll(): SubagentEntry[];
+  };
+}
+```
+
+These are attached to `GraphConfig.runtime` (line 474 of `types.ts`). The `WorkflowSDK` fills them in at construction time (lines 112-117 of `sdk.ts`) and applies them to every graph via `applyGraphDefaults()` (lines 237-253 of `sdk.ts`).
+
+Node factories consume these dependencies from `ctx.config.runtime`:
+- `agentNode` reads `clientProvider` at `nodes.ts:167`
+- `subgraphNode` reads `workflowResolver` at `nodes.ts:1137`
+- `subagentNode` reads `subagentBridge` at `nodes.ts:1674` and `subagentRegistry` at `nodes.ts:1682`
+
+---
+
+## 8. How the Ralph Workflow Actually Runs Today (Bypasses WorkflowSDK)
+
+**File:** `/home/alilavaee/Documents/projects/workflow-sdk/src/ui/commands/workflow-commands.ts`
+
+The `/ralph` command handler (function `createRalphCommand`, lines 597-793) does **not** use `WorkflowSDK.init()`. Instead, it manually constructs each dependency and injects them directly into the compiled graph's config.
+
+### Execution Path
+
+1. **Parse args** (lines 616-623): Calls `parseRalphArgs(args)`.
+
+2. **Session setup** (lines 631-641): Creates a `sessionId`, resolves the `sessionDir`, initializes a `WorkflowSession`.
+
+3. **Initial state** (lines 654-658): Calls `createRalphState(sessionId, { yoloPrompt, ralphSessionDir, maxIterations: 100 })`.
+
+4. **Bridge construction** (lines 661-676): Creates an ad-hoc bridge object (not a `SubagentGraphBridge` instance) with `spawn` and `spawnParallel` methods that delegate to `context.spawnSubagentParallel!()`. This is a different bridge interface than what `WorkflowSDK` would create -- it uses the chat UI's native sub-agent spawning mechanism.
+
+5. **Registry construction** (lines 679-687): Creates a fresh `SubagentTypeRegistry` and populates it by calling `discoverAgentInfos()` and registering each agent. This mirrors what `populateSubagentRegistry()` does, but is done inline.
+
+6. **Graph compilation** (line 690): Calls `createRalphWorkflow()` from `src/workflows/ralph/graph.ts` to get a `CompiledGraph<RalphWorkflowState>`.
+
+7. **Runtime injection** (lines 691-695): Directly mutates `compiled.config.runtime` to set `subagentBridge` and `subagentRegistry`. Note: `clientProvider` and `workflowResolver` are **not** set, which means `agentNode` and `subgraphNode` factories would fail if the Ralph workflow used them. The Ralph workflow only uses `subagentNode` and `toolNode`, which only need the bridge and registry.
+
+8. **Streaming execution** (lines 702-741): Calls `streamGraph(compiled, { initialState })` from `compiled.ts` directly (not `sdk.stream()`). Iterates over `StepResult` objects, updating the UI for each node:
+   - Displays phase descriptions via `getNodePhaseDescription()` (lines 57-69)
+   - Persists tasks to disk and updates the TUI task list (lines 718-739)
+
+### Ralph Workflow Graph Structure
+
+**File:** `/home/alilavaee/Documents/projects/workflow-sdk/src/workflows/ralph/graph.ts`
+
+`createRalphWorkflow()` (lines 98-236) builds a three-phase graph using the fluent builder API:
+
+**Phase 1 -- Task Decomposition:**
+- `.subagent("planner")` -- Sends the user prompt through `buildSpecToTasksPrompt()`, maps output to `specDoc`.
+- `.tool("parse-tasks")` -- Parses `specDoc` into `TaskItem[]`, maps to `tasks`, `currentTasks`, `iteration: 0`.
+
+**Phase 2 -- Worker Loop:**
+- `.loop([select-ready-tasks, worker], { until: ... })` -- Two-node loop body:
+  - `select-ready-tasks` (toolNode): Calls `getReadyTasks(state.tasks)`, maps to `currentTasks`.
+  - `worker` (custom NodeDefinition): Reads `ctx.config.runtime.subagentBridge`, spawns a single worker sub-agent for the first ready task, marks tasks as `"completed"` or `"error"` based on the result.
+- Loop exits when: all tasks are completed/error, `iteration >= maxIterations`, or no actionable tasks remain.
+
+**Phase 3 -- Review & Fix:**
+- `.subagent("reviewer")` -- Reviews completed work via `buildReviewPrompt()`, maps to `reviewResult`.
+- `.if({ condition, then: [fixer] })` -- If review finds issues and `overall_correctness !== "patch is correct"`, runs a fixer subagent (`"debugger"` agent).
+
+### Ralph State
+
+**File:** `/home/alilavaee/Documents/projects/workflow-sdk/src/workflows/ralph/state.ts`
+
+`RalphWorkflowState` (lines 51-80) extends `BaseState` with fields for tasks, review results, iteration counters, session info, and feature tracking. Uses annotation-based reducers for merge semantics (e.g., `mergeByIdReducer` for `tasks`, `concatReducer` for `debugReports`).
+
+---
+
+## 9. Summary: Designed vs. Actual Usage
+
+### What WorkflowSDK Provides
+
+The `WorkflowSDK` class is designed as a complete runtime container that:
+- Wraps raw `CodingAgentClient` instances into `ClientBackedAgentProvider` objects with lazy start
+- Manages a `ProviderRegistry` for multi-provider lookup
+- Creates a `SubagentGraphBridge` bound to a specific provider for session creation
+- Maintains a `SubagentTypeRegistry` from pre-discovered agent definitions
+- Provides a `workflowResolver` for named subgraph lookup
+- Injects all four runtime dependencies into any compiled graph via `applyGraphDefaults()`
+- Applies SDK-level defaults (checkpointer, defaultModel, maxSteps, validation)
+- Offers `execute()` and `stream()` methods that handle all wiring automatically
+
+### How Ralph Actually Uses It
+
+The Ralph command handler in `workflow-commands.ts` bypasses `WorkflowSDK` entirely:
+- It creates its own ad-hoc bridge object that delegates to the chat UI's `context.spawnSubagentParallel!()` -- this is because the TUI needs to control how sub-agents are spawned (e.g., for UI tracking, tree rendering)
+- It creates its own `SubagentTypeRegistry` populated via `discoverAgentInfos()`
+- It directly mutates `compiled.config.runtime` to inject only `subagentBridge` and `subagentRegistry`
+- It calls `streamGraph()` directly instead of `sdk.stream()`
+- It does not use `clientProvider` or `workflowResolver` because the Ralph workflow only uses `subagentNode` and `toolNode` factories (no `agentNode` or `subgraphNode`)
+
+The reason the Ralph workflow can bypass the SDK is that it only needs two of the four runtime dependencies (`subagentBridge` and `subagentRegistry`), and it needs a custom bridge implementation that routes through the TUI's sub-agent spawning mechanism rather than through the SDK's provider-based session creation.
+
+---
+
+## 10. Graph Execution Engine (Supporting Context)
+
+### GraphExecutor (`compiled.ts`, lines 253-832)
+
+The executor that `WorkflowSDK.execute()` and `WorkflowSDK.stream()` both use internally:
+
+- `stream()` (lines 311-320): The overloaded method that either yields raw `StepResult` objects or routes them through `StreamRouter` when `modes` are provided.
+- `streamSteps()` (lines 322-569): The core execution loop. Uses a BFS-style queue starting from `graph.startNode`. For each node: resolves the model, executes with retry, merges state, handles signals, auto-checkpoints, determines next nodes from edges.
+- `executeWithRetry()` (lines 615-753): Retries node execution up to `retryConfig.maxAttempts` with exponential backoff. Supports custom `onError` handlers with `retry`, `skip`, `abort`, and `goto` actions.
+
+### StreamRouter (`stream.ts`, lines 56-118)
+
+Projects raw `StepResult` streams into typed `StreamEvent` unions based on selected modes:
+- `"values"` -- Full state snapshot after each node.
+- `"updates"` -- Only the `stateUpdate` partial from each node result.
+- `"events"` -- Custom events emitted via `ctx.emit()` during node execution.
+- `"debug"` -- Execution metadata: timing, retry count, resolved model.
+
+### GraphBuilder (`builder.ts`, lines 229-951)
+
+Fluent API for constructing graphs:
+- `.start(node)` -- Set the entry node.
+- `.then(node)` -- Chain a sequential node.
+- `.subagent(config)` -- Create and chain a subagent node.
+- `.tool(config)` -- Create and chain a tool node.
+- `.if(condition)` / `.else()` / `.endif()` or `.if(configObject)` -- Conditional branching.
+- `.loop(bodyNodes, config)` -- Looping construct with exit condition.
+- `.parallel(config)` -- Parallel branch execution.
+- `.wait(prompt)` -- Human-in-the-loop pause.
+- `.catch(handler)` -- Error handler node.
+- `.end()` -- Mark terminal node.
+- `.compile(config?)` -- Produce a `CompiledGraph`.
diff --git a/research/docs/2026-02-25-workflow-sdk-patterns.md b/research/docs/2026-02-25-workflow-sdk-patterns.md
new file mode 100644
index 0000000000..8911ed7068
--- /dev/null
+++ b/research/docs/2026-02-25-workflow-sdk-patterns.md
@@ -0,0 +1,2189 @@
+# External SDK Patterns for Workflow/Agent Orchestration
+
+## Executive Summary
+
+This research document analyzes external SDK patterns for workflow and agent orchestration to inform the design of a standardized workflow SDK. It examines five major systems across different domains:
+
+1. **Claude Agent SDK** (Anthropic) - AI agent orchestration
+2. **GitHub Copilot SDK** - Multi-language agentic framework
+3. **OpenCode SDK** (Anomaly) - Code-centric agent platform
+4. **LangGraph** (LangChain) - State-based graph workflows
+5. **Temporal & Inngest** - Durable workflow-as-code platforms
+
+---
+
+## 1. Claude Agent SDK (TypeScript)
+
+**Repository**: `anthropics/claude-agent-sdk-typescript`  
+**Documentation**: Available via CHANGELOG.md and Overview wiki  
+**DeepWiki Link**: https://deepwiki.com/search/how-does-the-sdk-define-agent_0de98ba3-593c-42ea-b229-9a4447fd09a1
+
+### Core Abstractions
+
+#### Agent
+- Agents are configured programmatically using `agents: Record<string, AgentConfig>`
+- Supports defining subagents inline without filesystem dependencies
+- Configuration options include:
+  - `skills`: Available skills for the agent
+  - `maxTurns`: Maximum number of conversation turns
+  - `tools`: Exact set of built-in tools available
+
+```typescript
+// Agent configuration
+agents: {
+  'my-agent': {
+    skills: ['skill1', 'skill2'],
+    maxTurns: 10,
+    tools: ['Bash', 'Read', 'Edit']
+  }
+}
+```
+
+#### Session
+- V2 Session APIs for multi-turn conversations:
+  - `unstable_v2_createSession()`: Initiates a new session
+  - `unstable_v2_resumeSession()`: Resumes or forks existing sessions
+  - `unstable_v2_prompt()`: Sends prompts within a session
+- Session state is maintained across prompts
+- `forkSession: true` enables conversation branching
+
+```mermaid
+graph LR
+    Create["unstable_v2_createSession()"]
+    Prompt1["unstable_v2_prompt()"]
+    Prompt2["unstable_v2_prompt()"]
+    Resume["unstable_v2_resumeSession()"]
+    Fork["forkSession: true"]
+    
+    Create -->|"returns session"| Prompt1
+    Prompt1 -->|"maintains state"| Prompt2
+    Prompt1 -.->|"persist & reload"| Resume
+    Resume -->|"with forkSession"| Fork
+```
+
+#### Tool
+- Built-in tools: `Bash`, `Read`, `Edit`, `AskUserQuestion`
+- Tool configuration patterns:
+  - **Preset**: `tools: { type: 'preset', preset: 'claude_code' }`
+  - **Allowlist**: `tools: ['Bash', 'Read', 'Edit']`
+  - **Disable all**: `tools: []`
+- Custom tools via MCP (Model Context Protocol)
+- `tool()` helper supports annotations: `readOnlyHint`, `destructiveHint`, `openWorldHint`, `idempotentHint`
+
+#### Message Types
+- `SDKSystemMessage`: System messages with skills field
+- `task_started`: Emitted when subagent tasks are registered
+- `task_notification`: Includes `tool_use_id` for correlating task completions
+- `SDKResultSuccess` / `SDKResultError`: Include `stop_reason` field
+
+### Sub-Agent Patterns
+
+- Subagents defined inline via `agents` option
+- `task_started` system messages indicate subagent invocation
+- `task_notification` events correlate task completion with tool calls
+- Programmatic composition without filesystem dependencies
+
+### Streaming API
+
+- `Session.stream()`: Primary streaming method (renamed from `receive()`)
+- Event types:
+  - `task_started`: Subagent task registration
+  - `task_notification`: Task completion with `tool_use_id`
+  - `ConfigChange`: Configuration file changes
+  - `TeammateIdle`: Subagent idle state
+  - `TaskCompleted`: Subagent task completion
+- Holds back intermediate results until all background subagents complete
+
+### State Management
+
+- Explicit session persistence via `unstable_v2_resumeSession()`
+- State maintained for multi-turn conversations
+- Optional forking for exploring different conversational paths
+
+### Error Handling
+
+- `NoRetryError`: Prevents retries at the tool level
+- MCP tools have configurable timeouts via `MCP_TOOL_TIMEOUT`
+- MCP channels have 60-second closure timeout
+- `mcpServerStatus()`, `reconnectMcpServer()`, `toggleMcpServer()` for management
+
+### API Style
+
+**Imperative** - Explicit session management with programmatic configuration
+
+---
+
+## 2. GitHub Copilot SDK (Multi-Language)
+
+**Repository**: `github/copilot-sdk`  
+**Documentation**: Comprehensive guides in docs/ directory  
+**DeepWiki Link**: https://deepwiki.com/search/how-does-the-sdk-define-agent_33c10dd5-87fa-47d9-bff5-50e79bbd227f
+
+### Core Abstractions
+
+#### Agent (Custom Agent Config)
+```typescript
+interface CustomAgentConfig {
+  name: string;
+  displayName?: string;
+  description?: string;
+  tools?: string[];
+  prompt: string;
+  mcpServers?: { [key: string]: any };
+  infer?: boolean;
+}
+```
+
+```go
+type CustomAgentConfig struct {
+    Name string `json:"name"`
+    DisplayName string `json:"displayName,omitempty"`
+    Description string `json:"description,omitempty"`
+    Tools []string `json:"tools,omitempty"`
+    Prompt string `json:"prompt"`
+    MCPServers map[string]MCPServerConfig `json:"mcpServers,omitempty"`
+    Infer *bool `json:"infer,omitempty"`
+}
+```
+
+**Key Features**:
+- Specialized AI personas with scoped tools
+- Custom prompts for behavior guidance
+- MCP server integration for external tools
+
+#### Session (CopilotSession)
+
+```typescript
+export class CopilotSession {
+  public readonly sessionId: string;
+  // Methods: send, sendAndWait, on
+}
+```
+
+**Session Management**:
+- Create: `client.createSession(config)`
+- Resume: `client.resumeSession(sessionId)`
+- State persisted to `~/.copilot/session-state/{sessionId}/`
+- 30-minute idle timeout with automatic cleanup
+
+**Persisted Data**:
+- Conversation history (full message thread)
+- Tool call results (cached for context)
+- Agent planning state (`plan.md` file)
+- Session artifacts in `files/` subdirectory
+
+**NOT Persisted**:
+- Provider/API keys (security)
+- In-memory tool state
+
+**Session Configuration**:
+```typescript
+const session = await client.createSession({
+  sessionId: "user-123-task-456",
+  model: "gpt-5.2-codex",
+  customAgents: [/* custom agents */],
+  tools: [/* tool definitions */],
+  systemMessage: "Custom system prompt",
+  infiniteSessions: {
+    enabled: true,
+    backgroundCompactionThreshold: 0.80,
+    bufferExhaustionThreshold: 0.95
+  }
+});
+```
+
+#### Message & Events
+
+```typescript
+type SessionEvent = 
+  | { type: "assistant.message"; data: { content: string; ... } }
+  | { type: "user.message"; data: { content: string; ... } }
+  | { type: "tool.call"; ... }
+  // ... other event types
+```
+
+**Sending Messages**:
+```typescript
+// Non-blocking send
+await session.send({
+  prompt: "Hello",
+  attachments: [/* optional attachments */]
+});
+
+// Blocking send (waits for idle)
+await session.sendAndWait({
+  prompt: "Analyze this code",
+  mode: "full"
+});
+```
+
+### Tool Registration Patterns
+
+**SDK-Defined Tools**:
+
+```typescript
+// Node.js/TypeScript
+defineTool("lookup_issue", {
+  description: "Fetch issue details from our tracker",
+  parameters: z.object({
+    id: z.string().describe("Issue identifier"),
+  }),
+  handler: async ({ id }) => {
+    const issue = await fetchIssue(id);
+    return issue;
+  },
+})
+```
+
+```python
+# Python SDK
+@define_tool
+async def lookup_issue(invocation):
+    issue_id = invocation["arguments"]["id"]
+    issue = await fetch_issue(issue_id)
+    return {
+        "textResultForLlm": issue.summary,
+        "resultType": "success",
+        "sessionLog": f"Fetched issue {issue_id}",
+    }
+```
+
+```csharp
+// .NET SDK
+AIFunctionFactory.Create(
+    async ([Description("Issue identifier")] string id) => {
+        var issue = await FetchIssueAsync(id);
+        return issue;
+    },
+    "lookup_issue",
+    "Fetch issue details from our tracker")
+```
+
+**MCP Server Tools**:
+- Local servers: Spawned as subprocesses (stdin/stdout)
+- Remote servers: Pre-existing HTTP services
+- CLI discovers tools via `tools/list` request
+
+**Skill Files**:
+- Defined in `SKILL.md` files
+- Discovered from `skillDirectories`
+- Runtime discovery by agent
+
+### Tool Execution Flow
+
+1. CLI sends `tool.call` JSON-RPC notification
+2. SDK receives and dispatches to handler
+3. Handler executes with arguments
+4. Result sent back via `tool.callResult` JSON-RPC response
+5. Errors caught and returned without exposing details to LLM
+
+### Session Hooks (Extension Points)
+
+```typescript
+const session = await client.createSession({
+  model: "gpt-5",
+  hooks: {
+    onPreToolUse: async (input, invocation) => {
+      console.log(`About to run tool: ${input.toolName}`);
+      return {
+        permissionDecision: "allow", // or "deny", "ask"
+        modifiedArgs: input.toolArgs,
+        additionalContext: "Extra context for the model",
+      };
+    },
+    onPostToolUse: async (input, invocation) => {
+      console.log(`Tool ${input.toolName} completed`);
+      return {
+        additionalContext: "Post-execution notes",
+      };
+    },
+    onUserPromptSubmitted: async (input, invocation) => {
+      return {
+        modifiedPrompt: input.prompt,
+      };
+    },
+    onSessionStart: async (input, invocation) => {
+      return {
+        additionalContext: "Session initialization context",
+      };
+    },
+    onSessionEnd: async (input, invocation) => {
+      console.log(`Session ended: ${input.reason}`);
+    },
+    onErrorOccurred: async (input, invocation) => {
+      console.error(`Error in ${input.errorContext}`);
+      return {
+        errorHandling: "retry", // or "skip", "abort"
+      };
+    },
+  },
+});
+```
+
+### Custom Agent Example
+
+```typescript
+const session = await client.createSession({
+  model: "claude-haiku-4.5",
+  customAgents: [
+    {
+      name: "researcher",
+      displayName: "Research Agent",
+      description: "Read-only research assistant",
+      tools: ["grep", "glob", "view"], // Tool scoping
+      prompt: "You are a research assistant. You can search and read files but cannot modify anything.",
+    },
+  ],
+});
+```
+
+### Infinite Sessions (Long-Running Workflows)
+
+```typescript
+const session = await client.createSession({
+  sessionId: "long-workflow-123",
+  infiniteSessions: {
+    enabled: true,
+    backgroundCompactionThreshold: 0.80,  // Compact at 80%
+    bufferExhaustionThreshold: 0.95,      // Block at 95%
+  },
+});
+```
+
+- Automatic context window management
+- Background compaction to stay within limits
+- State persisted to workspace directory
+
+### Deployment Patterns
+
+1. **One CLI Server Per User** (Recommended)
+   - Strong isolation for multi-tenant environments
+   - Each user has their own server instance
+
+2. **Shared CLI Server**
+   - Resource-efficient for internal tools
+   - Requires application-level access control
+   - Unique session IDs per user essential
+
+3. **Serverless/Container**
+   - Mount `~/.copilot/session-state/` to persistent storage
+   - Ensures sessions survive container restarts
+
+### State Management
+
+- **Explicit Persistence**: `sessionId` required for resumable sessions
+- **Automatic Saving**: State written to disk after each interaction
+- **Lifecycle Management**: `listSessions()`, `deleteSession()`, `session.destroy()`
+
+### API Style
+
+**Hybrid Declarative/Imperative**:
+- Declarative: Configuration via `SessionConfig`
+- Imperative: Event handling and hook functions
+- Clear separation of configuration and runtime behavior
+
+---
+
+## 3. OpenCode SDK (Anomaly)
+
+**Repository**: `anomalyco/opencode`  
+**Documentation**: packages/web/src/content/docs/  
+**DeepWiki Link**: https://deepwiki.com/search/what-is-the-agent-session-mode_27eb093b-465d-4ce3-a56c-24b7b1306598
+
+### Core Abstractions
+
+#### Agent
+
+```typescript
+// Agent.Info type (packages/opencode/src/agent/agent.ts)
+interface Agent.Info {
+  name: string;
+  description?: string;
+  mode: "subagent" | "primary" | "all";
+  model: {
+    modelID: string;
+    providerID: string;
+  };
+  prompt: string;
+  permission: {
+    // Tool access ruleset
+  };
+}
+```
+
+**Configuration** (`opencode.json`):
+```json
+{
+  "agents": {
+    "build": {
+      "mode": "subagent",
+      "model": { "modelID": "claude-3-5-sonnet-20241022", "providerID": "anthropic" },
+      "prompt": "You are a build specialist...",
+      "permission": {
+        "tools": ["bash", "read", "write"],
+        "task": ["code-reviewer"]
+      }
+    },
+    "plan": {
+      "mode": "primary",
+      "hidden": false
+    }
+  }
+}
+```
+
+**Agent Types**:
+- **Primary**: Handle direct user interaction
+- **Subagent**: Invoked by primary agents or manually via `@mention`
+- **All**: Can function as both
+
+#### Session
+
+```javascript
+// Session operations
+const session = await client.session.create({
+  body: { title: "My session" },
+})
+
+const result = await client.session.prompt({
+  path: { id: session.id },
+  body: {
+    model: { providerID: "anthropic", modelID: "claude-3-5-sonnet-20241022" },
+    parts: [{ type: "text", text: "Hello!" }],
+  },
+})
+```
+
+**Session API**:
+- `session.list()`: List all active sessions
+- `session.get({ path })`: Fetch session details
+- `session.create({ body })`: Create new session
+- `session.prompt({ path, body })`: Send message to session
+
+**Session Manager** (`ACPSessionManager` in `packages/opencode/src/acp/session.ts`):
+- Handles session creation and loading
+- Maps ACP sessions to OpenCode's internal model
+
+#### Message & Parts
+
+```typescript
+// Auto-generated types (packages/sdk/js/src/v2/gen/types.gen.ts)
+type Message = UserMessage | AssistantMessage;
+
+interface UserMessage {
+  role: "user";
+  agent: string;
+  model: ModelConfig;
+  parts: Part[];
+}
+
+interface AssistantMessage {
+  role: "assistant";
+  cost: number;
+  tokens: TokenUsage;
+  finishReason: string;
+  parts: Part[];
+}
+
+type Part = TextPart | ToolPart | FilePart | ...;
+```
+
+### Tool Registration Patterns
+
+**File-Based Tools**:
+
+```typescript
+// .opencode/tools/database.ts (Single tool)
+import { tool } from "@opencode-ai/plugin"
+
+export default tool({
+  description: "Query the project database",
+  args: {
+    query: tool.schema.string().describe("SQL query to execute"),
+  },
+  async execute(args) {
+    return `Executed query: ${args.query}`
+  },
+})
+```
+
+```typescript
+// .opencode/tools/math.ts (Multiple tools)
+import { tool } from "@opencode-ai/plugin"
+
+export const add = tool({
+  description: "Add two numbers",
+  args: {
+    a: tool.schema.number().describe("First number"),
+    b: tool.schema.number().describe("Second number"),
+  },
+  async execute(args) {
+    return args.a + args.b;
+  },
+})
+
+export const multiply = tool({
+  description: "Multiply two numbers",
+  args: {
+    a: tool.schema.number(),
+    b: tool.schema.number(),
+  },
+  async execute(args) {
+    return args.a * args.b;
+  },
+})
+```
+
+**Tool Discovery**:
+- **Local**: `.opencode/tools/` in project directory
+- **Global**: `~/.config/opencode/tools/`
+- **Naming**:
+  - Single export: `<filename>` (e.g., `database`)
+  - Multiple exports: `<filename>_<exportname>` (e.g., `math_add`)
+
+**Plugin-Based Tools**:
+
+```typescript
+// .opencode/plugins/custom-tools.ts
+import { type Plugin, tool } from "@opencode-ai/plugin"
+
+export const CustomToolsPlugin: Plugin = async (ctx) => {
+  return {
+    tool: {
+      mytool: tool({
+        description: "This is a custom tool",
+        args: {
+          foo: tool.schema.string(),
+        },
+        async execute(args, context) {
+          const { directory, worktree } = context
+          return `Hello ${args.foo} from ${directory}`
+        },
+      }),
+    },
+  }
+}
+```
+
+**Tool Interface** (`Tool.Info`):
+```typescript
+interface Tool.Info {
+  id: string;
+  init: () => {
+    description: string;
+    parameters: ZodSchema;
+    execute: (args: any, context: Context) => Promise<any>;
+  };
+}
+```
+
+**Tool Execution Flow**:
+1. `SessionPrompt.resolveTools()` prepares tool for execution
+2. Retrieves tool schema
+3. Transforms schema via `ProviderTransform.schema()` if needed
+4. Wraps execute function with plugin hooks
+5. Triggers `tool.execute.before` and `tool.execute.after` plugin hooks
+
+### Sub-Agent Dispatch
+
+**Automatic Invocation via Task Tool**:
+
+```
+assistant: Now let me use the code-reviewer agent to review the code
+assistant: Uses the Task tool to launch the code-reviewer agent
+```
+
+```
+user: "Hello"
+<commentary>
+Since the user is greeting, use the greeting-responder agent to respond
+</commentary>
+assistant: "I'm going to use the Task tool with the greeting-responder agent"
+```
+
+**Permission Control** (`opencode.json`):
+```json
+{
+  "agents": {
+    "build": {
+      "permission": {
+        "task": ["code-*", "test-runner"]  // Glob patterns
+      }
+    }
+  }
+}
+```
+
+**Manual Invocation**:
+```
+@general help me search for this function
+```
+
+**Hidden Subagents**:
+```json
+{
+  "agents": {
+    "internal-reviewer": {
+      "mode": "subagent",
+      "hidden": true  // Not shown in @ autocomplete
+    }
+  }
+}
+```
+
+### Streaming Events
+
+**Event Types** (`Event` union type):
+- **Installation**: `EventInstallationUpdated`, `EventInstallationUpdateAvailable`
+- **Server**: `EventServerInstanceDisposed`, `EventServerConnected`, `EventGlobalDisposed`
+- **LSP**: `EventLspClientDiagnostics`, `EventLspUpdated`
+- **File/VCS**: `EventFileEdited`, `EventFileWatcherUpdated`, `EventVcsBranchUpdated`
+- **Message**: `EventMessageUpdated`, `EventMessageRemoved`, `EventMessagePartUpdated`, `EventMessagePartDelta`, `EventMessagePartRemoved`
+- **Permission**: `EventPermissionAsked`, `EventPermissionReplied`
+- **Session**: `EventSessionStatus`, `EventSessionIdle`, `EventSessionCompacted`, `EventSessionCreated`, `EventSessionUpdated`, `EventSessionDeleted`, `EventSessionDiff`, `EventSessionError`
+- **TUI**: `EventTuiPromptAppend`, `EventTuiCommandExecute`, `EventTuiToastShow`, `EventTuiSessionSelect`
+- **MCP**: `EventMcpToolsChanged`, `EventMcpBrowserOpenFailed`
+- **Pty**: `EventPtyCreated`, `EventPtyUpdated`, `EventPtyExited`, `EventPtyDeleted`
+- **Worktree**: `EventWorktreeReady`, `EventWorktreeFailed`
+
+**Streaming API** (Server-Sent Events):
+
+```javascript
+// Listen to real-time events via SSE
+const events = await client.event.subscribe()
+for await (const event of events.stream) {
+  console.log("Event:", event.type, event.properties)
+}
+
+// With directory filter
+const events = await client.event.subscribe({ directory: "/path/to/project" })
+```
+
+**Event Publishing**:
+- Backend publishes events to event bus
+- `SessionPrompt.loop()` (core agentic loop) publishes:
+  - `message.updated`: Agent response updates
+  - `message.part.updated`: Tool output updates
+- SSE connection with retry logic and `Last-Event-ID` headers
+- `createSseClient` handles underlying SSE connection
+
+### State Management
+
+- **Backend-Managed**: Inngest Server-style state management
+- **Event-Driven**: State changes propagated via event bus
+- **Durable**: `SessionPrompt.loop()` coordinates LLM streaming, tool execution, and context
+
+### Error Handling
+
+- Plugin hooks for tool execution interception
+- `tool.execute.before` and `tool.execute.after` hooks
+- Error propagation through event system
+
+### API Style
+
+**Declarative + Event-Driven**:
+- Declarative agent configuration in `opencode.json`
+- Event-driven communication via SSE
+- Plugin system for extensibility
+
+---
+
+## 4. LangGraph (Python)
+
+**Repository**: `langchain-ai/langgraph`  
+**Documentation**: Comprehensive wiki and test files  
+**DeepWiki Link**: https://deepwiki.com/search/how-does-langgraph-define-stat_4a1fe292-ba37-4263-ab48-c12dce6c520e
+
+### Core Abstractions
+
+#### StateGraph
+
+```python
+from typing_extensions import Annotated, TypedDict
+import operator
+
+class AgentState(TypedDict, total=False):
+    input: str
+    output: str
+    steps: Annotated[list[str], operator.add]
+
+workflow = StateGraph(AgentState)
+```
+
+**Typed State with Reducers**:
+- State defined using `TypedDict` or Pydantic `BaseModel`
+- Keys can be annotated with reducer functions: `Annotated[type, reducer]`
+- Reducers specify how values from multiple nodes are aggregated
+- Default behavior: New value overwrites old value
+
+#### Node
+
+```python
+def node_a(state: State) -> dict:
+    return {"text": state["text"] + "a"}
+
+workflow.add_node("node_a", node_a)
+```
+
+**Node Characteristics**:
+- Functions or runnables that receive current state
+- Return `dict` representing partial state update
+- Can be regular functions, async functions, or LangChain Runnables
+
+**Input Schema Support**:
+```python
+workflow.add_node("tools", execute_tools, input_schema=ToolState)
+```
+
+#### Edge
+
+```python
+# Direct edges
+workflow.add_edge(START, "node_a")
+workflow.add_edge("node_a", "node_b")
+workflow.add_edge("node_b", END)
+
+# Conditional edges
+def should_continue(messages):
+    if not messages[-1].tool_calls:
+        return "end"
+    else:
+        return "continue"
+
+workflow.add_conditional_edges(
+    "agent",
+    should_continue,
+    {
+        "continue": "tools",
+        "end": END,
+    },
+)
+
+# Conditional entry point
+def should_start(data: AgentState) -> str:
+    if len(data["input"]) > 10:
+        return "go-right"
+    else:
+        return "go-left"
+
+workflow.set_conditional_entry_point(
+    should_start, 
+    {"go-left": "left", "go-right": "right"}
+)
+```
+
+**Special Nodes**:
+- `START`: Entry point of the graph
+- `END`: Finish point of the graph
+
+### State Management
+
+**Merging Updates**:
+1. Node returns `Partial<State>` (dictionary)
+2. If state key has reducer → Use reducer to combine values
+3. Otherwise → New value overwrites old value
+
+**Example**:
+```python
+class ChildState(TypedDict):
+    my_key: str
+
+def grandchild_1(state: ChildState):
+    return {"my_key": state["my_key"] + " here"}
+
+def grandchild_2(state: ChildState):
+    return {"my_key": state["my_key"] + " and there"}
+```
+
+### Workflow Composition & Sub-Graphs
+
+```python
+# Create a subgraph
+subgraph_builder = StateGraph(SubState)
+subgraph_builder.add_node("sub_node_1", sub_node_1)
+subgraph_builder.add_node("sub_node_2", sub_node_2)
+subgraph = subgraph_builder.compile()
+
+# Use subgraph as node in parent graph
+builder = StateGraph(MainState)
+builder.add_node("subgraph_node", subgraph)
+builder.add_edge(START, "subgraph_node")
+builder.add_edge("subgraph_node", END)
+
+app = builder.compile()
+```
+
+### Error Handling & Retries
+
+**Retry Policies** (Node Level):
+```python
+# RetryPolicy attached during compilation
+workflow.add_node("api_call", api_call_node, retry_policy=RetryPolicy(...))
+```
+
+**ToolNode Error Handling**:
+```python
+from langgraph.prebuilt import ToolNode
+
+# Default error message
+tool_node = ToolNode([my_tool], handle_tool_errors=True)
+
+# Custom error message
+tool_node = ToolNode([my_tool], handle_tool_errors="Tool execution failed")
+
+# Error handler function
+def handle_errors(error: Exception) -> str:
+    if isinstance(error, ValueError):
+        return "Invalid value provided"
+    return "Unknown error occurred"
+
+tool_node = ToolNode([my_tool], handle_tool_errors=handle_errors)
+
+# Propagate exceptions (no handling)
+tool_node = ToolNode([my_tool], handle_tool_errors=False)
+```
+
+### Declarative vs Imperative Patterns
+
+**Declarative (StateGraph)**:
+```python
+# Define a new graph
+workflow = StateGraph(AgentState)
+
+workflow.add_node("agent", agent)
+workflow.add_node("tools", execute_tools, input_schema=ToolState)
+
+workflow.set_entry_point("agent")
+
+workflow.add_conditional_edges(
+    "agent", 
+    should_continue, 
+    {"continue": "tools", "exit": END}
+)
+
+workflow.add_edge("tools", "agent")
+
+app = workflow.compile()
+```
+
+**Imperative (Functional API)**:
+```python
+from langgraph.func import task, entrypoint
+
+@task
+def submapper(input: int) -> str:
+    time.sleep(input / 100)
+    return str(input)
+
+@task()
+def mapper(input: int) -> str:
+    sub = submapper(input)
+    time.sleep(input / 100)
+    return sub.result() * 2
+
+@entrypoint(checkpointer=sync_checkpointer)
+def graph(input: list[int]) -> list[str]:
+    futures = [mapper(i) for i in input]
+    mapped = [f.result() for f in futures]
+    answer = interrupt("question")  # Human-in-the-loop
+    final = [m + answer for m in mapped]
+    return add_a.invoke(final)
+```
+
+**Key Differences**:
+- Declarative: Explicit graph structure, compiled to `Pregel`
+- Imperative: Function calls and futures, implicit flow
+- Imperative supports `interrupt()` for human-in-the-loop
+
+### Streaming Implementation
+
+```python
+# Stream modes
+app = workflow.compile()
+
+# Values mode: All values after each step
+for output in app.stream(input_data, stream_mode="values"):
+    print(output)
+
+# Updates mode: Only node/task updates
+for output in app.stream(input_data, stream_mode="updates"):
+    print(output)
+
+# Custom mode: Custom data from nodes
+for output in app.stream(input_data, stream_mode="custom"):
+    print(output)
+
+# Messages mode: LLM tokens + metadata
+for output in app.stream(input_data, stream_mode="messages"):
+    print(output)
+
+# Multiple modes
+for mode, data in app.stream(input_data, stream_mode=["values", "updates"]):
+    print(f"{mode}: {data}")
+```
+
+**Stream Modes**:
+- `"values"`: Emits all state values after each step
+- `"updates"`: Emits only node/task updates
+- `"custom"`: Emits custom data via `get_stream_writer()`
+- `"messages"`: Emits LLM messages token-by-token
+- `"checkpoints"`: Emits checkpoint creation events
+- `"tasks"`: Emits task start/finish events with results/errors
+- `"debug"`: Emits debug events with maximum information
+
+**Custom Streaming from Nodes**:
+```python
+from langgraph.utils import get_stream_writer
+
+def my_node(state: State):
+    writer = get_stream_writer()
+    writer("custom_event", {"data": "my custom data"})
+    return {"key": "value"}
+```
+
+### Checkpointing & Persistence
+
+**Checkpoint Structure**:
+```python
+class Checkpoint(TypedDict):
+    channel_values: dict  # Current state of all channels
+    channel_versions: dict  # Version numbers for tracking
+    versions_seen: dict  # Map from node ID to processed versions
+    pending_sends: list  # Intermediate writes not yet committed
+    metadata: dict  # Source, step number, parent relationships
+```
+
+**Checkpoint Savers**:
+
+```python
+from langgraph.checkpoint.memory import InMemorySaver
+from langgraph.checkpoint.sqlite import SqliteSaver, AsyncSqliteSaver
+from langgraph.checkpoint.postgres import PostgresSaver, AsyncPostgresSaver
+
+# In-memory (development/testing)
+checkpointer = InMemorySaver()
+
+# SQLite (development)
+checkpointer = SqliteSaver.from_conn_string("checkpoints.db")
+
+# PostgreSQL (production)
+checkpointer = PostgresSaver(connection_string)
+await checkpointer.setup()  # Create tables
+
+# Compile with checkpointer
+app = workflow.compile(checkpointer=checkpointer)
+
+# Invoke with thread_id (primary key)
+app.invoke(input_data, config={"configurable": {"thread_id": "user-123"}})
+```
+
+**Durability Modes**:
+```python
+# Sync: Persist before next step (maximum durability, slower)
+app.invoke(input_data, config={"configurable": {"thread_id": "123"}}, durability="sync")
+
+# Async: Persist while next step executes (default, balanced)
+app.invoke(input_data, config={"configurable": {"thread_id": "123"}}, durability="async")
+
+# Exit: Persist only on graph exit (best performance, less resilience)
+app.invoke(input_data, config={"configurable": {"thread_id": "123"}}, durability="exit")
+```
+
+**Time-Travel Debugging**:
+```python
+# Get all checkpoints for a thread
+checkpoints = checkpointer.list({"configurable": {"thread_id": "123"}})
+
+# Resume from specific checkpoint
+checkpoint_tuple = checkpointer.get_tuple({"configurable": {"thread_id": "123", "checkpoint_id": "abc"}})
+app.invoke(input_data, config=checkpoint_tuple.config)
+```
+
+### Execution Model
+
+**Pregel-Inspired**:
+- Based on Google's Pregel framework
+- Iterative execution model
+- State maintained in "channels"
+- Nodes execute in topological order
+- Supports cycles for agent loops
+
+**Execution Flow**:
+1. Input state → Channels
+2. Determine ready nodes (dependencies satisfied)
+3. Execute ready nodes in parallel
+4. Merge updates using reducers
+5. Checkpoint state (based on durability mode)
+6. Repeat until `END` reached
+
+### API Style
+
+**Primarily Declarative** with imperative option:
+- Declarative: `StateGraph` API for explicit graph structure
+- Imperative: `@task` and `@entrypoint` for functional workflows
+- Clear separation between definition and execution
+
+---
+
+## 5. Temporal (TypeScript) & Inngest
+
+### Temporal Workflow-as-Code
+
+**Repository**: `temporalio/sdk-typescript`  
+**Documentation**: Comprehensive type definitions and tests  
+**DeepWiki Link**: https://deepwiki.com/search/how-does-temporal-define-workf_7c79e6eb-fc22-4b15-9b3f-992c2b825e0e
+
+#### Core Abstractions
+
+**Workflow**:
+```typescript
+export async function myWorkflow(param: string): Promise<string> {
+  // Orchestrate activities, child workflows, timers
+  await sleep(1000);
+  const result = await activities.doSomething(param);
+  return result;
+}
+```
+
+**Activity**:
+```typescript
+// Activities perform single, well-defined actions
+export async function doSomething(param: string): Promise<string> {
+  // Can interact with external world
+  // Not required to be deterministic
+  const response = await fetch(`https://api.example.com/${param}`);
+  return response.json();
+}
+
+// Proxy activities in workflow
+const activities = proxyActivities({ 
+  startToCloseTimeout: 2_000_000 
+});
+```
+
+**Signal** (Async messaging):
+```typescript
+export const unblockSignal = defineSignal<[]>('unblock');
+
+export async function myWorkflow(): Promise<void> {
+  let unblocked = false;
+  
+  setHandler(unblockSignal, () => {
+    unblocked = true;
+  });
+  
+  await condition(() => unblocked);
+}
+
+// External client sends signal
+await workflowHandle.signal(unblockSignal);
+```
+
+**Query** (Synchronous state retrieval):
+```typescript
+export const statusQuery = defineQuery<string>('status');
+
+export async function myWorkflow(): Promise<void> {
+  let status = "running";
+  
+  setHandler(statusQuery, () => status);
+  
+  // ... workflow logic updates status
+}
+
+// External client queries
+const status = await workflowHandle.query(statusQuery);
+```
+
+**Update** (Safe state mutation):
+```typescript
+export const update = defineUpdate<string[], [string]>('update');
+
+export async function workflowWithUpdates(): Promise<string[]> {
+  const state: string[] = [];
+  
+  const updateHandler = async (arg: string): Promise<string[]> => {
+    state.push(arg);
+    return state;
+  };
+  
+  setHandler(update, updateHandler);
+  
+  await condition(() => false); // Keep running
+}
+
+// External client sends update
+const newState = await workflowHandle.executeUpdate(update, "new item");
+```
+
+#### Durable Execution Model
+
+**Event Sourcing**:
+- All state changes recorded as events in history log
+- Failures trigger replay from last known good state
+- Workflow code must be deterministic
+- Avoid `Date.now()`, `Math.random()`, etc.
+- Use Temporal-provided deterministic alternatives
+
+**Deterministic APIs**:
+```typescript
+import * as wf from '@temporalio/workflow';
+
+// Use workflow.sleep() not setTimeout()
+await wf.sleep(1000);
+
+// Use workflow.uuid4() not crypto.randomUUID()
+const id = wf.uuid4();
+
+// Use workflow.Date.now() not Date.now()
+const now = wf.Date.now();
+```
+
+**Activator** (State Management):
+- Central class managing workflow execution and state
+- Processes activation jobs
+- Generates workflow commands
+- Registers completion promises
+
+#### Child Workflows
+
+```typescript
+import { startChild, executeChild } from '@temporalio/workflow';
+
+// Start and await separately
+const childHandle = await startChild(childWorkflow, {
+  args: [true, 2],
+  workflowId: 'child-1',
+  taskQueue: 'default',
+  cancellationType: 'WAIT_CANCELLATION_COMPLETED',
+  parentClosePolicy: 'TERMINATE',
+});
+await childHandle.result();
+
+// Start and await in one call
+const result = await executeChild(childWorkflow, {
+  args: [true, 4],
+});
+```
+
+**Child Workflow Options**:
+- `workflowId`: Unique identifier
+- `taskQueue`: Which workers process this workflow
+- `cancellationType`: How cancellation is handled
+  - `ABANDON`: Don't propagate cancellation
+  - `TRY_CANCEL`: Request cancellation but don't wait
+  - `WAIT_CANCELLATION_COMPLETED`: Wait for cancellation to complete
+  - `WAIT_CANCELLATION_REQUESTED`: Wait for cancellation request only
+- `parentClosePolicy`: Child behavior when parent closes
+  - `TERMINATE`: Terminate child
+  - `ABANDON`: Leave child running
+  - `REQUEST_CANCEL`: Request cancellation
+
+#### Error Handling Hierarchy
+
+```typescript
+import { 
+  TemporalFailure, 
+  ApplicationFailure, 
+  ActivityFailure,
+  ChildWorkflowFailure,
+  TimeoutFailure,
+  CancelledFailure
+} from '@temporalio/workflow';
+
+try {
+  await activities.someActivity();
+} catch (err) {
+  if (err instanceof ActivityFailure) {
+    const originalError = err.cause;
+    if (originalError instanceof ApplicationFailure) {
+      console.log(`Activity failed with type: ${originalError.type}`);
+      if (originalError.nonRetryable) {
+        // Special handling for non-retryable errors
+      }
+    } else if (originalError instanceof TimeoutFailure) {
+      console.log(`Activity timed out: ${originalError.timeoutType}`);
+    }
+  }
+}
+```
+
+**Failure Types**:
+- `TemporalFailure`: Base class for all failures
+- `ApplicationFailure`: User-defined application errors
+- `ActivityFailure`: Wraps failures from activities
+- `ChildWorkflowFailure`: Wraps failures from child workflows
+- `TimeoutFailure`: Indicates a timeout occurred
+- `CancelledFailure`: Indicates cancellation
+
+**Creating Application Failures**:
+```typescript
+// Retryable failure
+throw ApplicationFailure.create({
+  message: "Something went wrong",
+  type: "CustomError",
+  nonRetryable: false,
+  details: ["additional", "context"]
+});
+
+// Non-retryable failure
+throw ApplicationFailure.nonRetryable("Fatal error", "FatalError");
+```
+
+#### Retry Policies
+
+```typescript
+// Workflow with retry policy
+await client.workflow.start(myWorkflow, {
+  taskQueue: 'default',
+  workflowId: 'my-workflow-1',
+  retry: {
+    initialInterval: 1000,        // 1 second
+    maximumInterval: 60000,        // 1 minute
+    backoffCoefficient: 2,         // Exponential backoff
+    maximumAttempts: 3,
+    nonRetryableErrorTypes: ['FatalError'],
+  },
+});
+
+// Activity with timeout
+const activities = proxyActivities({
+  startToCloseTimeout: '5 minutes',
+  scheduleToStartTimeout: '1 minute',
+  scheduleToCloseTimeout: '10 minutes',
+  heartbeatTimeout: '30 seconds',
+  retry: {
+    initialInterval: 1000,
+    maximumAttempts: 3,
+  },
+});
+```
+
+**Timeout Types**:
+- `START_TO_CLOSE`: Max time from start to completion
+- `SCHEDULE_TO_START`: Max time waiting to be picked up
+- `SCHEDULE_TO_CLOSE`: Max time from scheduling to completion
+- `HEARTBEAT`: Max time between heartbeats (long-running activities)
+
+#### Compensation Logic (Sagas)
+
+```typescript
+import { CancellationScope, isCancellation } from '@temporalio/workflow';
+
+export async function bookingWorkflow(booking: Booking): Promise<void> {
+  let flightBooked = false;
+  let hotelBooked = false;
+  
+  try {
+    await CancellationScope.cancellable(async () => {
+      // Book flight
+      await activities.bookFlight(booking.flight);
+      flightBooked = true;
+      
+      // Book hotel
+      await activities.bookHotel(booking.hotel);
+      hotelBooked = true;
+      
+      // Charge customer
+      await activities.chargeCustomer(booking.total);
+    });
+  } catch (e) {
+    if (isCancellation(e)) {
+      // Compensate: Undo what we've done
+      if (hotelBooked) {
+        await activities.cancelHotel(booking.hotel);
+      }
+      if (flightBooked) {
+        await activities.cancelFlight(booking.flight);
+      }
+    }
+    throw e;
+  }
+}
+```
+
+#### Interceptor Architecture
+
+```typescript
+// Intercept and modify workflow behavior
+interface WorkflowInterceptor {
+  execute?: (input, next) => Promise<any>;
+  handleSignal?: (input, next) => Promise<void>;
+  handleQuery?: (input, next) => Promise<any>;
+}
+
+// Example: Logging interceptor
+class LoggingInterceptor implements WorkflowInterceptor {
+  async execute(input, next) {
+    console.log(`Executing workflow: ${input.workflowType}`);
+    const result = await next(input);
+    console.log(`Workflow completed: ${input.workflowType}`);
+    return result;
+  }
+}
+```
+
+### Inngest Workflow-as-Code
+
+**Repository**: `inngest/inngest`  
+**Documentation**: SDK_SPEC.md and comprehensive tests  
+**DeepWiki Link**: https://deepwiki.com/search/how-does-inngest-define-workfl_c400b148-feb7-4014-a2ab-60d918294534
+
+#### Function Definition
+
+**CUE Schema**:
+```cue
+#Function: {
+  id: string
+  name: string
+  triggers: [...#EventTrigger | #CronTrigger]
+  steps: [string]: #Step
+  concurrency?: #Concurrency
+  throttle?: #Throttle
+  idempotency?: string
+  cancel?: [...#CancelEvent]
+}
+
+#EventTrigger: {
+  event: string
+  expression?: string  // CEL expression
+}
+
+#CronTrigger: {
+  cron: string
+}
+
+#Step: {
+  id: string
+  name: string
+  after?: [...string]  // Dependencies (DAG)
+}
+```
+
+**Go Struct**:
+```go
+type Function struct {
+    ID          string            `json:"id"`
+    Name        string            `json:"name"`
+    Triggers    []Trigger         `json:"triggers"`
+    Steps       map[string]Step   `json:"steps,omitempty"`
+    Concurrency *Concurrency      `json:"concurrency,omitempty"`
+    Throttle    *Throttle         `json:"throttle,omitempty"`
+    Idempotency string            `json:"idempotency,omitempty"`
+    Cancel      []CancelEvent     `json:"cancel,omitempty"`
+}
+```
+
+#### Step API Patterns
+
+**step.Run** (Basic execution unit):
+```go
+_, err := step.Run(ctx, "1", func(ctx context.Context) (any, error) {
+    atomic.AddInt32(&counter, 1)
+    fmt.Println(time.Now().Format(time.StampMilli), "1", "-", input.InputCtx.RunID)
+    return "hello 1", nil
+})
+```
+
+```typescript
+const s3Urls = await step.run("copy-images-to-s3", async () => {
+  return copyAllImagesToS3(event.data.imageURLs);
+});
+```
+
+**step.Sleep** (Durable delays):
+```go
+step.Sleep(ctx, "initial-delay", time.Second)
+```
+
+```typescript
+await step.sleep("wait-24h", "24h");
+```
+
+**step.WaitForEvent** (Event-driven coordination):
+```go
+fn, err := step.WaitForEvent[FunctionCreatedEvent](
+    ctx,
+    "wait-for-activity",
+    step.WaitForEventOpts{
+        Name:    "Wait for a function to be created",
+        Event:   "api/function.created",
+        Timeout: time.Hour * 72,
+        // Match with CEL expression
+        If: inngestgo.StrPtr("event.data.user_id == async.data.user_id"),
+    },
+)
+if errors.Is(err, step.ErrEventNotReceived) {
+    // Handle timeout
+}
+```
+
+**step.Invoke** (Function composition):
+```go
+_, err := step.Invoke[any](ctx, "invoke-step", step.InvokeOpts{
+    FunctionId: fmt.Sprintf("%s-%s", appID, "invokee-fn"),
+    Data:       map[string]any{},
+})
+```
+
+#### Fan-out/Fan-in Pattern
+
+```go
+import "github.com/inngest/inngestgo/experimental/group"
+
+res := group.Parallel(ctx,
+    func(ctx context.Context) (any, error) {
+        return step.Run(ctx, "p1", func(ctx context.Context) (any, error) {
+            return doWork1(), nil
+        })
+    },
+    func(ctx context.Context) (any, error) {
+        return step.Run(ctx, "p2", func(ctx context.Context) (any, error) {
+            return doWork2(), nil
+        })
+    },
+    func(ctx context.Context) (any, error) {
+        return step.Run(ctx, "p3", func(ctx context.Context) (any, error) {
+            return doWork3(), nil
+        })
+    },
+)
+
+// res[0], res[1], res[2] contain results of p1, p2, p3
+```
+
+#### State Management (Memoization)
+
+**Inngest Server Role**:
+- Manages function execution state
+- Stores completed step results
+- Provides memoized data in subsequent calls
+
+**SDK Role**:
+- Receives "Call Requests" with `steps` object
+- Uses memoized data to skip completed steps
+- Reports new steps with `206 Partial Content`
+- Function survives outages and restarts
+
+**Flow**:
+1. Function starts → Step 1 executes → Return `206` with Step 1 result
+2. Server stores Step 1 result
+3. Server calls function again with Step 1 memoized
+4. Function skips Step 1 → Executes Step 2 → Return `206` with Step 2 result
+5. Repeat until all steps complete → Return `200`
+
+#### Retry & Error Handling
+
+**Function-Level Retries**:
+```go
+inngestgo.FunctionOpts{
+    ID:      "my-function",
+    Name:    "My Function",
+    Retries: inngestgo.IntPtr(3), // Retry up to 3 times
+}
+```
+
+**Step-Level Retries**:
+- Each `step.Run` is automatically retryable
+- `executor` checks `i.resp.Retryable()`
+- Increments attempt count and schedules retry
+
+**No Retry Errors**:
+```go
+import "github.com/inngest/inngestgo"
+
+// Function level
+if shouldNotRetry {
+    return nil, inngestgo.NoRetryError(fmt.Errorf("fatal error"))
+}
+
+// Step level
+_, err := step.Run(ctx, "critical-step", func(ctx context.Context) (any, error) {
+    if fatalCondition {
+        return nil, inngestgo.NoRetryError(fmt.Errorf("cannot retry"))
+    }
+    return result, nil
+})
+```
+
+**Retry at Specific Time**:
+```go
+import "github.com/inngest/inngestgo"
+
+_, err := step.Run(ctx, "api-call", func(ctx context.Context) (any, error) {
+    resp, err := callAPI()
+    if err != nil && isRateLimited(err) {
+        // Retry after rate limit reset
+        return nil, inngestgo.RetryAtError(time.Now().Add(time.Hour))
+    }
+    return resp, err
+})
+```
+
+**Max Attempts**:
+- Configured per function
+- `executor` tracks attempt count
+- When `MaxAttempts` reached, opcode changes to `OpcodeStepFailed`
+
+#### Durable Execution Components
+
+**State Manager** (Redis-backed):
+- Stores run status, timestamps, context
+- Event batches for batch triggers
+- Step outputs for memoization
+
+**Executor** (`executor.Execute()`):
+1. Load current state
+2. Invoke function code via driver
+3. Parse response (step results, opcodes)
+4. Update state in State Manager
+5. Schedule next steps or handle errors
+6. Persist state for durability
+
+**Opcodes**:
+- `OpcodeStepRun`: Step needs execution
+- `OpcodeStepError`: Step failed but may retry
+- `OpcodeStepFailed`: Step failed permanently (non-retryable or max attempts)
+- `OpcodeWaitForEvent`: Waiting for external event
+
+#### Event-Driven Patterns
+
+**Event Trigger**:
+```go
+inngestgo.EventTrigger("api/account.created", nil)
+```
+
+**Sending Events**:
+```go
+inngestClient.Send(ctx, inngestgo.Event{
+    Name: "api/account.created",
+    Data: map[string]any{
+        "user_id": 123,
+        "email": "user@example.com",
+    },
+})
+```
+
+**Event Matching with CEL**:
+```go
+step.WaitForEventOpts{
+    Event: "api/payment.received",
+    If: inngestgo.StrPtr("event.data.order_id == async.data.order_id && event.data.amount >= 100"),
+}
+```
+
+#### Concurrency & Throttling
+
+**Concurrency Control**:
+```cue
+concurrency: {
+  limit: 10
+  key: "event.data.user_id"  // Per-user concurrency
+}
+```
+
+**Throttling**:
+```cue
+throttle: {
+  limit: 100
+  period: "1h"
+  key: "event.data.tenant_id"
+}
+```
+
+**Idempotency**:
+```cue
+idempotency: "event.data.request_id"  // Derive unique key from event
+```
+
+**Cancellation**:
+```cue
+cancel: [
+  {
+    event: "api/order.cancelled"
+    if: "event.data.order_id == async.data.order_id"
+  }
+]
+```
+
+---
+
+## Comparative Analysis
+
+### Core Abstraction Patterns
+
+| SDK | Agent/Workflow | Session/Execution | Tool/Activity | State Management |
+|-----|---------------|-------------------|---------------|------------------|
+| **Claude SDK** | `AgentConfig` with skills & tools | V2 Session APIs with fork support | Built-in + MCP tools with annotations | Explicit session persistence |
+| **Copilot SDK** | `CustomAgentConfig` with scoped tools | `CopilotSession` with disk persistence | SDK-defined + MCP + Skills | Automatic state saving to disk |
+| **OpenCode** | `Agent.Info` (primary/subagent) | REST API sessions with SSE events | File-based + Plugin tools with Zod | Backend-managed state |
+| **LangGraph** | `StateGraph` with typed state | Compiled graph with checkpointers | Nodes as first-class functions | Reducer-based state merging |
+| **Temporal** | Workflow functions | Event-sourced execution history | Activities (non-deterministic) | Replay-based determinism |
+| **Inngest** | Function with triggers & steps | Server-managed execution | Step API (Run/Sleep/WaitForEvent) | Memoization of step results |
+
+### Tool/Activity Registration
+
+| SDK | Registration Pattern | Interface Definition | Execution Model |
+|-----|---------------------|---------------------|-----------------|
+| **Claude SDK** | Config-based allowlist or preset | MCP protocol with annotations | Tool timeout with MCP channels |
+| **Copilot SDK** | `defineTool()` with Zod schemas | Multi-language with type inference | JSON-RPC via CLI server |
+| **OpenCode** | File-based discovery with `tool()` | Zod schemas with execute function | Plugin hooks for interception |
+| **LangGraph** | Nodes are tools (first-class) | Python functions with type hints | `ToolNode` with error handling |
+| **Temporal** | `proxyActivities()` with options | TypeScript/Python async functions | Deterministic replay with timeouts |
+| **Inngest** | `step.Run()` with closures | Go/TypeScript closures | Memoization with retries |
+
+### Sub-Agent/Child Workflow Patterns
+
+| SDK | Composition Pattern | Invocation Method | Isolation |
+|-----|---------------------|-------------------|-----------|
+| **Claude SDK** | Inline agent definitions | Automatic via `task_started` events | Shared session context |
+| **Copilot SDK** | `customAgents` with tool scoping | Manual via agent selection | Separate agent personas |
+| **OpenCode** | `Task` tool + `@mention` | Automatic (Task) or manual (@) | Permission-controlled |
+| **LangGraph** | Compiled subgraph as node | `builder.add_node("sub", subgraph)` | Separate state schema |
+| **Temporal** | `startChild()` / `executeChild()` | Explicit API calls | Separate workflow execution |
+| **Inngest** | `step.Invoke()` | Explicit function invocation | Separate function run |
+
+### State Management & Persistence
+
+| SDK | State Model | Persistence Mechanism | Durability |
+|-----|-------------|----------------------|------------|
+| **Claude SDK** | Session-based | Implicit with resume support | Explicit fork for branching |
+| **Copilot SDK** | Disk-persisted session state | `~/.copilot/session-state/` | Automatic with idle timeout |
+| **OpenCode** | Backend-managed | Server-side state store | Event-driven updates |
+| **LangGraph** | Channel-based with reducers | Checkpoint savers (Memory/SQLite/Postgres) | Configurable durability modes |
+| **Temporal** | Event sourcing | Temporal Server history log | Replay-based recovery |
+| **Inngest** | Step memoization | Redis-backed State Manager | Automatic step result storage |
+
+### Streaming & Events
+
+| SDK | Streaming API | Event Types | Use Case |
+|-----|--------------|-------------|----------|
+| **Claude SDK** | `Session.stream()` | task_started, task_notification, ConfigChange | Agent execution monitoring |
+| **Copilot SDK** | `session.on(event)` | assistant.message, tool.call, session.idle | Real-time UI updates |
+| **OpenCode** | SSE via `event.subscribe()` | 40+ event types (message, session, file, etc.) | Comprehensive system monitoring |
+| **LangGraph** | `app.stream(mode=...)` | values, updates, custom, messages, tasks, debug | Debug and observability |
+| **Temporal** | Native Temporal streaming | N/A (event sourcing) | Workflow history queries |
+| **Inngest** | N/A (HTTP-based) | Function execution events | Webhook-based updates |
+
+### Error Handling & Retries
+
+| SDK | Retry Strategy | Error Types | Compensation |
+|-----|---------------|-------------|--------------|
+| **Claude SDK** | `NoRetryError` for tools | MCP timeout errors | Manual error handling |
+| **Copilot SDK** | Hook-based (`onErrorOccurred`) | "retry", "skip", "abort" | Custom error handlers |
+| **OpenCode** | Plugin hook interception | Tool execution errors | Event-driven error propagation |
+| **LangGraph** | `RetryPolicy` per node | `ToolNode` error handling | Node-level error handlers |
+| **Temporal** | `RetryPolicy` with backoff | TemporalFailure hierarchy | `CancellationScope` for sagas |
+| **Inngest** | Function + step-level retries | NoRetryError, RetryAtError | Automatic with memoization |
+
+### API Style
+
+| SDK | Primary Style | Composition Pattern | Learning Curve |
+|-----|--------------|---------------------|----------------|
+| **Claude SDK** | Imperative | Programmatic configuration | Medium |
+| **Copilot SDK** | Hybrid (Declarative config + Imperative hooks) | Multi-language SDKs | Low-Medium |
+| **OpenCode** | Declarative (JSON config) + Event-driven | Plugin system | Medium |
+| **LangGraph** | Declarative (StateGraph) | Graph compilation | Medium-High |
+| **Temporal** | Imperative (Workflow-as-code) | Function composition | High |
+| **Inngest** | Hybrid (CUE config + Step API) | Function invocation | Medium |
+
+---
+
+## Key Design Patterns Discovered
+
+### 1. **Session Management Patterns**
+
+**Explicit Session Lifecycle** (Claude SDK, Copilot SDK):
+- Create → Resume → Fork
+- Explicit session IDs for persistence
+- Fork support for branching conversations
+
+**Implicit State Management** (LangGraph, Temporal):
+- Automatic state persistence via checkpointing or event sourcing
+- `thread_id` or `workflow_id` as primary key
+- Time-travel debugging support
+
+**Backend-Managed State** (OpenCode, Inngest):
+- Server-side state storage
+- Client-side SDKs fetch and update state
+- Event-driven synchronization
+
+### 2. **Tool Registration Patterns**
+
+**File-Based Discovery** (OpenCode):
+```
+.opencode/tools/
+├── database.ts      → tool: "database"
+├── math.ts          → tools: "math_add", "math_multiply"
+└── apis/
+    └── github.ts    → tool: "apis_github"
+```
+
+**Function-Based Registration** (Copilot SDK, Inngest):
+```typescript
+defineTool("name", { description, parameters, handler })
+```
+
+**Protocol-Based** (Claude SDK, Copilot SDK):
+- MCP (Model Context Protocol) for external tools
+- Standardized tool discovery and execution
+
+**First-Class Nodes** (LangGraph):
+- Tools are nodes in the graph
+- No separate tool registration layer
+
+### 3. **Sub-Agent/Child Workflow Patterns**
+
+**Automatic Invocation with Permission System** (OpenCode):
+```json
+{
+  "permission": {
+    "task": ["code-*", "test-runner"]
+  }
+}
+```
+
+**Explicit Composition** (Temporal, Inngest):
+```typescript
+const result = await executeChild(childWorkflow, options);
+```
+
+**Graph-Based Composition** (LangGraph):
+```python
+subgraph = subgraph_builder.compile()
+builder.add_node("subgraph_node", subgraph)
+```
+
+### 4. **State Merging Patterns**
+
+**Reducer-Based** (LangGraph):
+```python
+steps: Annotated[list[str], operator.add]  # Append to list
+count: Annotated[int, lambda a, b: a + b]  # Sum values
+```
+
+**Overwrite-Based** (Most SDKs):
+```typescript
+return { key: newValue }  // Overwrites previous value
+```
+
+**Memoization-Based** (Inngest):
+- Server stores completed step results
+- SDK receives memoized data
+- Skip completed steps automatically
+
+### 5. **Streaming Patterns**
+
+**Mode-Based Streaming** (LangGraph):
+- Multiple stream modes: values, updates, custom, messages, tasks, debug
+- Client chooses granularity
+
+**Event Bus Pattern** (OpenCode):
+- Central event bus for all system events
+- SSE for client subscriptions
+- Comprehensive event types (40+)
+
+**Session-Based Streaming** (Claude SDK, Copilot SDK):
+- Stream tied to session lifecycle
+- Events for agent and tool execution
+
+### 6. **Error Handling Patterns**
+
+**Failure Type Hierarchy** (Temporal):
+```
+TemporalFailure
+├── ApplicationFailure
+├── ActivityFailure
+├── ChildWorkflowFailure
+├── TimeoutFailure
+└── CancelledFailure
+```
+
+**No-Retry Flag Pattern** (Temporal, Inngest):
+```typescript
+throw new NoRetryError("Fatal error");
+```
+
+**Hook-Based Error Handling** (Copilot SDK):
+```typescript
+onErrorOccurred: (input) => ({ errorHandling: "retry" | "skip" | "abort" })
+```
+
+### 7. **Workflow Composition Patterns**
+
+**DAG with Conditional Edges** (LangGraph):
+```python
+workflow.add_conditional_edges(
+    "agent",
+    should_continue,
+    {"continue": "tools", "end": END}
+)
+```
+
+**Step Dependencies** (Inngest):
+```cue
+steps: {
+  step1: { id: "step1" }
+  step2: { id: "step2", after: ["step1"] }
+  step3: { id: "step3", after: ["step1", "step2"] }
+}
+```
+
+**Function Call Graph** (Temporal):
+```typescript
+const result1 = await activity1();
+const result2 = await activity2(result1);
+return await activity3(result2);
+```
+
+### 8. **Declarative vs Imperative API Design**
+
+**Pure Declarative** (Inngest CUE config):
+```cue
+#Function: {
+  id: "my-function"
+  triggers: [{ event: "api/event" }]
+  steps: { ... }
+}
+```
+
+**Pure Imperative** (Temporal):
+```typescript
+export async function myWorkflow(params) {
+  const result = await activities.doWork(params);
+  return result;
+}
+```
+
+**Hybrid** (Copilot SDK, LangGraph):
+- Declarative configuration for structure
+- Imperative hooks/handlers for behavior
+
+---
+
+## Recommendations for Standardized Workflow SDK
+
+### 1. **Core Abstractions**
+
+**Workflow/Agent**:
+- Support both declarative (config-based) and imperative (code-based) definitions
+- Allow inline sub-workflow/sub-agent definitions
+- Clear separation between workflow definition and execution
+
+**Session/Execution**:
+- First-class session concept with explicit lifecycle
+- Support for forking and branching
+- Optional persistence with configurable backends
+
+**Tool/Activity**:
+- Unified tool interface with type-safe parameters (Zod/JSON Schema)
+- Multiple registration patterns: file-based, function-based, protocol-based
+- Built-in tool library + extensibility via plugins
+
+**State**:
+- Typed state with optional reducers for merging
+- Support for both channel-based (LangGraph) and object-based state
+- Automatic state persistence with checkpoint APIs
+
+### 2. **Composition Patterns**
+
+**Sub-Workflows**:
+```typescript
+// Inline sub-workflow
+workflow.addSubWorkflow("analyze", {
+  tools: ["read", "grep"],
+  prompt: "Analyze codebase...",
+})
+
+// External sub-workflow
+workflow.addNode("sub", compileWorkflow(subWorkflowDef))
+
+// Dynamic invocation
+await step.invoke("analyze", { data: ... })
+```
+
+**Conditional Branching**:
+```typescript
+workflow.addConditionalEdge(
+  "agent",
+  (state) => state.shouldContinue ? "continue" : "end",
+  {
+    continue: "tools",
+    end: END
+  }
+)
+```
+
+### 3. **State Management API**
+
+```typescript
+// Define typed state with reducers
+interface WorkflowState {
+  input: string;
+  output: string;
+  steps: string[];  // Append reducer
+  count: number;    // Sum reducer
+}
+
+const workflow = defineWorkflow<WorkflowState>({
+  name: "my-workflow",
+  initialState: {
+    input: "",
+    output: "",
+    steps: [],
+    count: 0,
+  },
+  reducers: {
+    steps: (prev, next) => [...prev, ...next],
+    count: (prev, next) => prev + next,
+  },
+})
+```
+
+### 4. **Tool Registration API**
+
+```typescript
+// Function-based
+defineTool("search_code", {
+  description: "Search codebase for pattern",
+  parameters: z.object({
+    pattern: z.string(),
+    fileType: z.string().optional(),
+  }),
+  handler: async ({ pattern, fileType }) => {
+    // Implementation
+  },
+})
+
+// File-based discovery
+// tools/my_tool.ts exports default tool(...)
+
+// MCP protocol
+mcpServer.register({
+  command: ["uvx", "mcp-server-git"],
+  env: { GIT_DIR: "/path/to/repo" },
+})
+```
+
+### 5. **Streaming API**
+
+```typescript
+// Multiple stream modes
+for await (const event of workflow.stream(input, {
+  mode: ["values", "updates", "tasks"],
+})) {
+  const [mode, data] = event;
+  console.log(`${mode}:`, data);
+}
+
+// Custom events from within nodes
+function myNode(state: State) {
+  const writer = getStreamWriter();
+  writer.emit("custom", { progress: 50 });
+  return { result: "done" };
+}
+```
+
+### 6. **Error Handling & Retries**
+
+```typescript
+// Node-level retry policy
+workflow.addNode("api_call", apiCallNode, {
+  retry: {
+    maxAttempts: 3,
+    initialInterval: 1000,
+    backoffCoefficient: 2,
+    nonRetryableErrors: ["AuthError"],
+  },
+  timeout: 30000,
+})
+
+// Error handler hooks
+workflow.onError("api_call", (error, state) => {
+  if (error instanceof RateLimitError) {
+    return { action: "retry_at", time: error.retryAfter };
+  }
+  return { action: "fail" };
+})
+
+// No-retry errors
+throw new NoRetryError("Fatal error");
+```
+
+### 7. **Persistence API**
+
+```typescript
+// Compile with checkpointer
+const app = workflow.compile({
+  checkpointer: new PostgresCheckpointer(connString),
+  durability: "async",  // sync | async | exit
+})
+
+// Execute with thread_id
+await app.invoke(input, {
+  sessionId: "user-123-task-456",
+})
+
+// Resume from checkpoint
+const checkpoints = await checkpointer.list({ sessionId: "..." });
+await app.invoke(input, { checkpoint: checkpoints[0] });
+```
+
+### 8. **Hooks & Extension Points**
+
+```typescript
+workflow.hooks({
+  onNodeStart: async (node, state) => {
+    console.log(`Starting node: ${node.id}`);
+  },
+  onNodeComplete: async (node, state, result) => {
+    console.log(`Node ${node.id} completed`);
+  },
+  onToolExecute: async (tool, args) => {
+    // Permission check, logging, etc.
+    return { allow: true, modifiedArgs: args };
+  },
+  onError: async (error, context) => {
+    // Custom error handling
+    return { action: "retry" | "skip" | "abort" };
+  },
+})
+```
+
+### 9. **Session API**
+
+```typescript
+// Create session
+const session = await client.createSession({
+  sessionId: "user-123",
+  workflow: "analyze_code",
+  initialState: { ... },
+  persistence: {
+    enabled: true,
+    backend: "postgres",
+  },
+})
+
+// Send message
+await session.send({ prompt: "Analyze this file" });
+
+// Resume session
+const session = await client.resumeSession("user-123");
+
+// Fork session
+const forked = await session.fork({
+  forkId: "user-123-branch-1",
+  state: session.getState(),
+});
+```
+
+### 10. **API Style Recommendation**
+
+**Hybrid Approach**:
+1. **Declarative Core**: Workflow structure defined declaratively
+2. **Imperative Handlers**: Node logic, error handlers, hooks are imperative
+3. **Type Safety**: Strong TypeScript types throughout
+4. **Multi-Paradigm**: Support both graph-based (LangGraph-style) and function-based (Temporal-style) workflows
+
+```typescript
+// Graph-based (declarative)
+const workflow = new WorkflowGraph<State>()
+  .addNode("agent", agentNode)
+  .addNode("tools", toolsNode)
+  .addConditionalEdge("agent", shouldContinue, {
+    continue: "tools",
+    end: END
+  })
+  .compile();
+
+// Function-based (imperative)
+const workflow = defineWorkflow({
+  name: "analyze_code",
+  async execute(input: Input, ctx: Context): Promise<Output> {
+    const analysis = await ctx.step("analyze", async () => {
+      return await analyzeCode(input.file);
+    });
+    
+    await ctx.step("report", async () => {
+      await generateReport(analysis);
+    });
+    
+    return { status: "complete" };
+  },
+});
+```
+
+---
+
+## Source References
+
+### Claude Agent SDK
+- **CHANGELOG.md**: https://deepwiki.com/wiki/anthropics/claude-agent-sdk-typescript
+- **V2 Session APIs**: `unstable_v2_createSession`, `unstable_v2_resumeSession`, `unstable_v2_prompt`
+- **Tool Configuration**: Built-in tools, MCP protocol, tool annotations
+
+### GitHub Copilot SDK
+- **Session Management**: `docs/guides/session-persistence.md`
+- **Custom Agents**: Multi-language SDK documentation
+- **Tool Execution**: JSON-RPC protocol via CLI server
+- **Hooks**: `onPreToolUse`, `onPostToolUse`, `onErrorOccurred`
+
+### OpenCode SDK
+- **Agent Architecture**: `packages/opencode/src/agent/agent.ts`
+- **Tool Registry**: `packages/opencode/src/tool/registry.ts`
+- **Streaming Events**: `packages/sdk/js/src/v2/gen/types.gen.ts`
+- **Session Management**: `packages/opencode/src/acp/session.ts`
+
+### LangGraph
+- **StateGraph**: `libs/langgraph/langgraph/graph/state.py`
+- **Checkpointing**: `libs/checkpoint/langgraph/checkpoint/base.py`
+- **Streaming**: `libs/langgraph/langgraph/pregel/__init__.py`
+- **Test Files**: Comprehensive examples in `libs/langgraph/tests/`
+
+### Temporal TypeScript SDK
+- **Workflows**: `packages/test/src/workflows/`
+- **Activities**: `packages/workflow/src/workflow.ts`
+- **Error Handling**: `packages/common/src/errors.ts`
+- **Interceptors**: `packages/workflow/src/interceptors.ts`
+
+### Inngest
+- **Function Definition**: `pkg/inngest/function.go`, `pkg/cuedefs/v1/function.cue`
+- **Step API**: `vendor/github.com/inngest/inngestgo/step.go`
+- **Executor**: `pkg/execution/executor/executor.go`
+- **SDK Spec**: `docs/SDK_SPEC.md`
+
+---
+
+## Conclusion
+
+This research reveals several converging patterns across workflow and agent orchestration SDKs:
+
+1. **Session-First Design**: All modern SDKs treat sessions as first-class citizens with explicit lifecycle management.
+
+2. **Typed State with Reducers**: LangGraph's reducer pattern for state merging is powerful and should be adopted.
+
+3. **Tool/Activity Unification**: A standardized tool interface with multiple registration patterns (file-based, function-based, protocol-based) provides maximum flexibility.
+
+4. **Hybrid Declarative/Imperative**: The best DX comes from declarative configuration for structure and imperative code for behavior.
+
+5. **Comprehensive Streaming**: Support for multiple stream modes (values, updates, events, debug) enables rich observability.
+
+6. **Hierarchical Error Handling**: Temporal's failure type hierarchy and Inngest's no-retry patterns should inform error handling design.
+
+7. **Durable Execution Patterns**: Checkpointing (LangGraph), event sourcing (Temporal), and memoization (Inngest) all achieve durability but with different tradeoffs.
+
+8. **Sub-Workflow Composition**: Support for both automatic invocation (OpenCode's Task tool) and explicit composition (LangGraph's subgraphs) provides flexibility.
+
+The ideal workflow SDK should be **multi-paradigm**, supporting both:
+- **Graph-based workflows** (LangGraph-style) for complex DAGs with conditional branching
+- **Function-based workflows** (Temporal/Inngest-style) for sequential, imperative logic
+
+With **first-class abstractions** for:
+- Sessions (with fork/resume)
+- Tools (with multiple registration patterns)
+- State (with reducers)
+- Sub-workflows (with composition patterns)
+- Streaming (with multiple modes)
+- Error handling (with retry policies and hooks)
+- Persistence (with pluggable backends)
+
diff --git a/research/docs/2026-02-25-workflow-sdk-refactor-research.md b/research/docs/2026-02-25-workflow-sdk-refactor-research.md
new file mode 100644
index 0000000000..6f73dd2673
--- /dev/null
+++ b/research/docs/2026-02-25-workflow-sdk-refactor-research.md
@@ -0,0 +1,492 @@
+---
+date: 2026-02-25 16:08:19 UTC
+researcher: Copilot
+git_commit: baa0a67de3dc4f5231219f789755c6f2ef8ca024
+branch: lavaman131/feature/workflow-sdk
+repository: workflow-sdk
+topic: "Workflow SDK Refactor: Simplified Syntax, Module Consolidation, and Ralph TUI Freeze"
+tags: [research, codebase, workflow-sdk, graph, ralph, refactor, tui-freeze, module-consolidation]
+status: complete
+last_updated: 2026-02-25
+last_updated_by: Copilot
+---
+
+# Research: Workflow SDK Refactor
+
+## Research Question
+
+Research the codebase to refactor the workflow SDK so it uses a simpler syntax with sub-agents and tools with subagent and tool nodes, allowing chaining with a declarative `.if()`, `.else()`, etc. syntax. Focus on keeping things elegant and simple in favor of complex/intrusive logic. Consolidate everything to a `workflows` module with `graph` as a submodule. Ensure all nodes in ralph are working because currently after the review node the entire TUI freezes and is unresponsive.
+
+## Summary
+
+The codebase has a mature graph execution engine at `src/graph/` with a fluent builder API (`graph<State>().start().then().if().else().endif().loop().compile()`) supporting 7 node types, conditional branching, loops, parallel execution, and error handling. However, the Ralph workflow at `src/workflows/ralph/` does **not use** the graph engine — it's implemented as a procedural command handler in `src/ui/commands/workflow-commands.ts`. The TUI freeze after the review node is most likely caused by a deferred completion handler never executing due to sub-agent lifecycle tracking issues. The module structure has `graph/` and `workflows/` as sibling directories, and consolidation requires moving `graph/` under `workflows/`.
+
+---
+
+## Detailed Findings
+
+### 1. Current Graph Module API (`src/graph/`)
+
+The graph module provides a comprehensive declarative workflow engine with 206 lines of exports in its barrel file.
+
+#### 1.1 Node Types
+
+**`NodeType`** (`src/graph/types.ts:104`)
+```typescript
+type NodeType = "agent" | "tool" | "decision" | "wait" | "ask_user" | "subgraph" | "parallel";
+```
+
+**12 Node Factory Functions** (`src/graph/nodes.ts`):
+| Factory | Purpose |
+|---------|---------|
+| `agentNode()` | Executes agent interaction via SDK client |
+| `toolNode()` | Runs a tool function with input/output mapping |
+| `decisionNode()` | Routes execution based on conditions |
+| `waitNode()` | Pauses for human input |
+| `askUserNode()` | Presents options to user |
+| `parallelNode()` | Runs branches concurrently |
+| `subgraphNode()` | Embeds sub-workflow |
+| `contextMonitorNode()` | Monitors context window usage |
+| `clearContextNode()` | Clears/compacts context |
+| `customToolNode()` | User-defined tool execution |
+| `subagentNode()` | Spawns single sub-agent via bridge |
+| `parallelSubagentNode()` | Spawns multiple sub-agents in parallel |
+
+#### 1.2 Builder API (Fluent Chaining)
+
+**`GraphBuilder<TState>`** (`src/graph/builder.ts:136-678`)
+
+Current chaining methods:
+- `.start(node)` — Set starting node (line 225)
+- `.then(node)` — Chain next node with edge (line 245)
+- `.if(condition)` — Begin conditional branch, creates decision node (line 281)
+- `.else()` — Begin alternative branch (line 316)
+- `.endif()` — Close conditional, creates merge node (line 342)
+- `.loop(bodyNodes, config)` — Add loop with exit condition (line 460)
+- `.parallel(config)` — Add parallel branches (line 402)
+- `.wait(promptOrNode)` — Add human-in-the-loop pause (line 558)
+- `.catch(handler)` — Set graph-level error handler (line 586)
+- `.end()` — Mark terminal node (line 598)
+- `.compile(config)` — Produce `CompiledGraph` (line 612)
+
+**Factory function**: `graph<TState>()` at `builder.ts:698`
+
+**Helper functions**:
+- `createNode()` — Generic node creation (line 715)
+- `createDecisionNode()` — Routing node with condition array (line 745)
+- `createWaitNode()` — Pause node with prompt (line 771)
+
+#### 1.3 Templates (`src/graph/templates.ts`)
+
+Pre-built workflow patterns returning `GraphBuilder` for further chaining:
+- `sequential(nodes)` — Linear chain: A → B → C (line 110)
+- `mapReduce({ splitter, worker, merger })` — Split-process-merge (line 152)
+- `reviewCycle({ executor, reviewer, fixer, until })` — Execute-review-fix loop (line 180)
+- `taskLoop({ decomposer, worker, reviewer?, until? })` — Decompose-work-review loop (line 196)
+
+#### 1.4 State Management (`src/graph/annotation.ts`)
+
+LangGraph-inspired annotation system:
+```typescript
+const MyAnnotation = {
+  count: annotation<number>(0, Reducers.sum),
+  items: annotation<string[]>([], Reducers.concat),
+  config: annotation<Config>({}, Reducers.merge),
+};
+```
+
+**Built-in Reducers**: `replace`, `concat`, `merge`, `mergeById`, `max`, `min`, `sum`, `or`, `and`, `ifDefined`
+
+#### 1.5 Execution Engine (`src/graph/compiled.ts`)
+
+`GraphExecutor` at `compiled.ts:323-569`:
+- BFS traversal with node queue
+- Exponential backoff retry per node
+- State merged immutably after each node via annotation reducers
+- Edge evaluation with `goto` override support
+- Loop detection via `Set<"nodeId:stepCount">`
+- Yields `StepResult` for streaming consumption
+- Supports abort via `AbortSignal`
+
+#### 1.6 Streaming (`src/graph/stream.ts`)
+
+`StreamRouter` with 5 modes: `"values"`, `"updates"`, `"custom"`, `"debug"`, `"all"`
+
+#### 1.7 Sub-Agent Integration
+
+- `SubagentGraphBridge` (`src/graph/subagent-bridge.ts`) — Spawns agents via SDK sessions with `spawn()` and `spawnParallel()` using `Promise.allSettled()`
+- `SubagentTypeRegistry` (`src/graph/subagent-registry.ts`) — Registry of available sub-agent types
+- `ProviderRegistry` (`src/graph/provider-registry.ts`) — Maps agent type names to SDK clients
+
+#### 1.8 Checkpointing (`src/graph/checkpointer.ts`)
+
+4 implementations: `MemorySaver`, `FileSaver`, `ResearchDirSaver`, `SessionDirSaver`
+Factory: `createCheckpointer(options)`
+
+---
+
+### 2. Ralph Workflow Implementation
+
+#### 2.1 Critical Finding: Ralph Does NOT Use the Graph Engine
+
+The Ralph workflow is implemented as a **procedural, imperative command handler** in `src/ui/commands/workflow-commands.ts` (1195 lines), NOT as a graph with nodes and edges.
+
+**Three Phases** (all sequential code blocks):
+1. **Task Decomposition** (lines 723-757): Spawns a sub-agent to create a spec/task list
+2. **Worker Dispatch Loop** (lines 778-845): Sequential `while` loop dispatching workers
+3. **Review & Fix Phase** (lines 847-1025): Spawns reviewer, processes fixes
+
+#### 2.2 Ralph State Files (Exist but Unused by Graph)
+
+**`src/workflows/ralph/state.ts`** (lines 50-75): Defines `RalphWorkflowState` extending `BaseState` with fields like `tasks`, `currentTask`, `iteration`, `reviewResult`, etc. — but this state type is NOT used by the graph engine for Ralph.
+
+**`src/workflows/ralph/prompts.ts`**: 8 prompt builder functions; only 4 are actually used.
+
+**`src/graph/nodes/ralph.ts`**: Contains graph-compatible node definitions for Ralph but these are NOT wired into the actual Ralph execution flow.
+
+#### 2.3 Ralph Execution Flow
+
+```
+/ralph command → workflow-commands.ts handler
+  ├─ Phase 1: Task Decomposition
+  │   └─ context.spawnSubagent({ name: "planner", message: specPrompt })
+  │   └─ Parse spec into task list
+  ├─ Phase 2: Worker Loop (while iteration < 100)
+  │   └─ for each pending task:
+  │       └─ context.spawnSubagent({ name: "worker", message: taskPrompt })
+  │   └─ Check if all completed → break
+  └─ Phase 3: Review (for i < MAX_REVIEW_ITERATIONS=1)
+      └─ context.spawnSubagent({ name: "reviewer", message: reviewPrompt })
+      └─ Parse review result
+      └─ If fixes needed → spawn fix workers
+      └─ Return success/failure
+```
+
+---
+
+### 3. TUI Freeze Bug: Root Cause Analysis
+
+#### 3.1 Most Likely Root Cause: Deferred Completion Never Triggering
+
+**The freeze happens when `await context.spawnSubagent()` never resolves** after the review node.
+
+**Event chain that should happen:**
+1. `spawnSubagent()` creates a Promise storing its resolver in `streamCompletionResolverRef.current` (`chat.tsx:3782`)
+2. Calls `sendSilentMessage()` → triggers SDK streaming
+3. SDK stream completes → `onComplete()` fires (`index.ts:1871`)
+4. `handleComplete()` callback runs → should resolve the stored promise
+
+**Where it breaks** (`chat.tsx:3638-3647`):
+```typescript
+const hasActiveAgents = hasActiveForegroundAgents(parallelAgentsRef.current);
+if (hasActiveAgents || hasRunningToolRef.current) {
+  pendingCompleteRef.current = handleComplete;  // ← Defers completion
+  return;  // ← EXITS without resolving the spawnSubagent promise!
+}
+```
+
+The reviewer sub-agent may be incorrectly tracked as an active foreground agent. When `handleComplete` defers, it relies on `subagent.complete` or `tool.complete` events to call `tryFinalizeParallelTracking()` which would execute the pending completion. If those events never fire (or are filtered), the promise hangs.
+
+#### 3.2 Contributing Factors
+
+**Issue A: Stream Generation Mismatch** (`chat.tsx:3589-3591`)
+```typescript
+if (!isCurrentStreamCallback(streamGenerationRef.current, currentGeneration)) return;
+```
+If `streamGenerationRef.current` is incremented before `handleComplete` fires (e.g., by a concurrent operation), the stale guard silently drops the completion.
+
+**Issue B: AbortError Doesn't Call onComplete** (`index.ts:1875-1877`)
+```typescript
+if (error instanceof Error && error.name === "AbortError") {
+  // Stream was intentionally aborted — NO onComplete() call in this branch
+}
+```
+If the stream is aborted, `onComplete()` may not fire, leaving the promise unresolved. (Note: the code after the if-else block does call `onComplete()`, but control flow may not always reach it.)
+
+**Issue C: Different Spawn Paths**
+- **Workers** use `context.spawnSubagentParallel!()` → goes through `SubagentGraphBridge` → simpler, independent sessions
+- **Reviewer** uses `context.spawnSubagent()` → goes through main session stream → more complex event flow with more failure points
+
+#### 3.3 Historical Context
+
+Research doc `2026-02-15-subagent-premature-completion-SUMMARY.md` documented a related bug where `tool.complete` events unconditionally finalize sub-agent status without checking background mode. The fix involved checking `agent.background` flag before marking as completed.
+
+Research doc `2026-02-15-ralph-dag-orchestration-implementation.md` documented that `streamCompletionResolverRef` is single-slot — only one worker can be awaited at a time, creating a serial bottleneck.
+
+---
+
+### 4. Module Structure
+
+#### 4.1 Current Layout
+
+```
+src/
+├── graph/           ← Core execution engine (206-line barrel, 16+ modules)
+│   ├── index.ts
+│   ├── builder.ts   ← GraphBuilder fluent API
+│   ├── compiled.ts  ← GraphExecutor BFS engine
+│   ├── types.ts     ← All type definitions
+│   ├── nodes.ts     ← 12 node factory functions
+│   ├── nodes/       ← Node implementations
+│   │   └── ralph.ts ← Ralph graph nodes (unused by runtime)
+│   ├── annotation.ts
+│   ├── templates.ts
+│   ├── stream.ts
+│   ├── sdk.ts       ← WorkflowSDK class
+│   ├── agent-providers.ts
+│   ├── provider-registry.ts
+│   ├── subagent-bridge.ts
+│   ├── subagent-registry.ts
+│   ├── checkpointer.ts
+│   ├── state-validator.ts
+│   └── errors.ts
+├── workflows/       ← Session management + Ralph prompts/state
+│   ├── index.ts     ← Minimal barrel (session exports only)
+│   ├── session.ts   ← Workflow session persistence
+│   └── ralph/
+│       ├── state.ts
+│       └── prompts.ts
+├── sdk/             ← Unified agent client abstraction
+│   ├── index.ts
+│   ├── types.ts
+│   ├── base-client.ts
+│   ├── init.ts
+│   └── clients/
+│       ├── claude.ts
+│       ├── opencode.ts
+│       └── copilot.ts
+└── ui/              ← TUI layer (OpenTUI + React)
+    ├── chat.tsx      ← Main chat component (243K, 3800+ lines)
+    ├── index.ts      ← Stream handler (94K, 1895 lines)
+    └── commands/
+        └── workflow-commands.ts  ← Ralph procedural handler (1195 lines)
+```
+
+#### 4.2 Dependency Flow
+
+```
+telemetry/types.ts
+  ↑ (AgentType)
+sdk/types.ts ← sdk/base-client.ts ← sdk/init.ts
+  ↑ (CodingAgentClient)
+graph/sdk.ts ← graph/* (internal)
+  ↑
+graph/index.ts
+
+workflows/session.ts  ← independent, no cross-module deps
+workflows/index.ts
+```
+
+- **graph** depends on **sdk** (for `CodingAgentClient` type)
+- **workflows** is independent (only session persistence)
+- **No circular dependencies**
+
+#### 4.3 Package Configuration
+
+- Entry: `src/cli.ts`
+- Module: ESM (`"type": "module"`)
+- Resolution: `"moduleResolution": "bundler"` (Bun)
+- No path aliases — direct relative imports
+- No explicit `"exports"` field in package.json
+
+---
+
+### 5. Node Factory Functions Deep Dive
+
+These are the key functions for the simplified syntax proposal:
+
+#### 5.1 `subagentNode()` (`src/graph/nodes.ts`)
+
+```typescript
+interface SubagentNodeConfig<TState extends BaseState> {
+  id: NodeId;
+  agentType: string;        // e.g., "copilot", "claude", "opencode"
+  instruction: string | ((state: TState) => string);
+  outputMapper?: OutputMapper<TState>;
+  model?: ModelSpec;
+  name?: string;
+  description?: string;
+}
+```
+
+Creates a node that spawns a sub-agent via `SubagentGraphBridge.spawn()`. Returns `NodeDefinition` usable in the builder chain.
+
+#### 5.2 `toolNode()` (`src/graph/nodes.ts`)
+
+```typescript
+interface ToolNodeConfig<TState extends BaseState> {
+  id: NodeId;
+  execute: ToolExecuteFn<TState>;
+  outputMapper?: ToolOutputMapper<TState>;
+  name?: string;
+  description?: string;
+}
+```
+
+Creates a node that executes a tool function. The `execute` function receives the current state and returns tool output.
+
+#### 5.3 `agentNode()` (`src/graph/nodes.ts`)
+
+```typescript
+interface AgentNodeConfig<TState extends BaseState> {
+  id: NodeId;
+  agentType: string;
+  prompt: string | ((state: TState) => string);
+  outputMapper?: OutputMapper<TState>;
+  model?: ModelSpec;
+  clientProvider?: ClientProvider;
+  name?: string;
+  description?: string;
+  retry?: RetryConfig;
+  onError?: NodeDefinition<TState>["onError"];
+}
+```
+
+Creates a node that executes an agent interaction via the SDK client. Similar to `subagentNode` but uses the provider registry directly.
+
+---
+
+### 6. Workflow SDK Class (`src/graph/sdk.ts`)
+
+**`WorkflowSDK`** (lines 33-160):
+- Constructor accepts `WorkflowSDKConfig` with `providers` (Record<string, CodingAgentClient>), `workflows`, `subagentTypes`
+- Converts clients to `ClientBackedAgentProvider` instances
+- Provides `runtimeDependencies` injected into `GraphConfig.runtime`
+- Methods: `register()`, `get()`, `has()`, `list()`, `run()`, `stream()`
+- `run()` calls `executeGraph()` with injected runtime deps
+- `stream()` calls `streamGraph()` for streaming execution
+
+---
+
+## Code References
+
+### Graph Module Core
+- `src/graph/index.ts` — Barrel file with 206 lines of categorized exports
+- `src/graph/builder.ts:136-678` — `GraphBuilder` class with fluent API
+- `src/graph/builder.ts:698-700` — `graph<TState>()` factory function
+- `src/graph/compiled.ts:323-569` — `GraphExecutor.streamSteps()` BFS engine
+- `src/graph/types.ts:104` — `NodeType` union type
+- `src/graph/types.ts:323-370` — `NodeDefinition<TState>` interface
+- `src/graph/types.ts:267-305` — `ExecutionContext<TState>` interface
+- `src/graph/types.ts:242-259` — `NodeResult<TState>` interface
+- `src/graph/nodes.ts` — 12 node factory functions
+- `src/graph/annotation.ts:67-164` — `Reducers` object with 10 built-in reducers
+- `src/graph/annotation.ts:308-335` — `AtomicStateAnnotation` pre-defined schema
+- `src/graph/templates.ts:110-211` — 4 template patterns
+
+### Ralph Workflow
+- `src/ui/commands/workflow-commands.ts:673-1063` — Ralph command handler (procedural)
+- `src/ui/commands/workflow-commands.ts:874-877` — Reviewer sub-agent spawn
+- `src/ui/commands/workflow-commands.ts:53` — `MAX_REVIEW_ITERATIONS = 1`
+- `src/workflows/ralph/state.ts:50-75` — `RalphWorkflowState` (unused by runtime)
+- `src/workflows/ralph/prompts.ts` — 8 prompt builder functions (4 unused)
+- `src/graph/nodes/ralph.ts` — Graph-compatible ralph nodes (unused by runtime)
+
+### TUI Freeze Location
+- `src/ui/chat.tsx:3747-3795` — `spawnSubagent()` Promise creation
+- `src/ui/chat.tsx:3777-3786` — Promise resolver stored in `streamCompletionResolverRef`
+- `src/ui/chat.tsx:3588-3710` — `handleComplete()` callback
+- `src/ui/chat.tsx:3638-3647` — Deferred completion check (likely freeze point)
+- `src/ui/chat.tsx:3697-3706` — Promise resolution path
+- `src/ui/index.ts:1871` — `onComplete()` call after stream ends
+- `src/ui/index.ts:1232-1290` — `subagent.complete` event handler
+
+### Module Structure
+- `src/graph/index.ts` — Graph barrel (206 lines, 16 modules)
+- `src/workflows/index.ts` — Workflows barrel (17 lines, session only)
+- `src/sdk/index.ts` — SDK barrel (90 lines, 3 modules)
+- `src/graph/sdk.ts` — WorkflowSDK class connecting graph ↔ SDK
+- `package.json` — Entry: `src/cli.ts`, ESM, no explicit exports field
+
+---
+
+## Architecture Documentation
+
+### Current Execution Architecture
+
+```
+User → CLI (src/cli.ts) → Commander.js
+  ├─ chat command → TUI (src/ui/chat.tsx)
+  │   ├─ SDK clients (src/sdk/clients/*.ts)
+  │   ├─ Stream handler (src/ui/index.ts)
+  │   └─ Commands (src/ui/commands/)
+  │       ├─ builtin-commands.ts
+  │       ├─ workflow-commands.ts ← Ralph lives here (procedural)
+  │       └─ skill-commands.ts
+  ├─ config command
+  └─ init command
+
+Graph Engine (src/graph/) ← NOT used by Ralph at runtime
+  ├─ GraphBuilder → CompiledGraph → GraphExecutor
+  ├─ NodeDefinition → NodeResult → state merge
+  ├─ ProviderRegistry → AgentProvider → SDK client
+  ├─ SubagentGraphBridge → spawn/spawnParallel
+  └─ StreamRouter → StreamEvent
+```
+
+### Key Design Patterns
+
+1. **Fluent Builder**: All builder methods return `this` for chaining
+2. **Annotation Reducers**: LangGraph-inspired state management
+3. **Factory Functions**: Type-safe node creation (`agentNode()`, `toolNode()`, etc.)
+4. **Template Patterns**: Pre-built `sequential`, `mapReduce`, `reviewCycle`, `taskLoop`
+5. **Provider Abstraction**: `ProviderRegistry` maps names to SDK clients
+6. **Signal-Based Communication**: Nodes emit signals (e.g., `human_input_required`)
+7. **BFS Graph Traversal**: Queue-based execution with loop detection
+
+---
+
+## Historical Context (from research/)
+
+### Workflow SDK Design Evolution
+
+- `research/docs/2026-02-05-pluggable-workflows-sdk-design.md` — Original design for unified entity registry with provider parsers, name-based node references, and CLI hints system
+- `research/docs/2026-02-11-workflow-sdk-implementation.md` — Custom tool discovery (`.atomic/tools/`), workflow TypeScript format, sub-agent session manager with concurrency limiting
+- `research/docs/2026-02-21-workflow-sdk-inline-mode-research.md` — Workflows run inline via `streamAndWait()` within chat event loop, not separate processes
+- `research/docs/2026-02-25-workflow-sdk-standardization.md` — Comprehensive architecture analysis, identified serial worker dispatch bottleneck
+- `research/docs/2026-02-25-workflow-sdk-patterns.md` — External SDK comparison (LangGraph, Temporal, Inngest patterns)
+
+### Ralph Workflow History
+
+- `research/docs/2026-02-09-163-ralph-loop-enhancements.md` — Ralph loop enhancement proposal
+- `research/docs/2026-02-13-ralph-task-list-ui.md` — Task list UI implementation
+- `research/docs/2026-02-15-ralph-dag-orchestration-implementation.md` — Identified `blockedBy` exists but unenforced, serial worker bottleneck, `streamCompletionResolverRef` single-slot limitation
+- `research/docs/2026-02-15-ralph-loop-manual-worker-dispatch.md` — Manual worker dispatch patterns
+- `research/docs/2026-02-25-graph-execution-engine-technical-documentation.md` — Full graph engine technical docs
+
+### Sub-Agent Integration Issues
+
+- `research/docs/2026-02-15-subagent-premature-completion-SUMMARY.md` — `tool.complete` event unconditionally marks sub-agents as completed without checking background mode
+- `research/docs/2026-02-15-subagent-premature-completion-investigation.md` — Detailed bug investigation
+- `research/docs/2026-02-14-subagent-output-propagation-issue.md` — Sub-agent output not propagating correctly
+- `research/docs/2026-02-23-258-background-agents-sdk-event-pipeline.md` — Background agent event pipeline analysis
+
+### TUI Architecture
+
+- `research/docs/2026-02-16-atomic-chat-architecture-current.md` — Current chat architecture
+- `research/docs/2026-02-12-tui-layout-streaming-content-ordering.md` — TUI layout and streaming
+- `research/docs/2026-02-15-ui-inline-streaming-vs-pinned-elements.md` — Inline streaming patterns
+
+---
+
+## Related Research
+
+- `research/docs/2026-02-25-workflow-sdk-standardization.md` — Most comprehensive current state analysis
+- `research/docs/2026-02-25-workflow-sdk-patterns.md` — External SDK patterns (LangGraph, Temporal, Inngest)
+- `research/docs/2026-02-25-graph-execution-engine-technical-documentation.md` — Graph engine deep dive
+- `research/docs/2026-02-03-workflow-composition-patterns.md` — Composition pattern design
+- `research/docs/2026-02-03-custom-workflow-file-format.md` — Custom workflow file format spec
+- `research/docs/2026-01-31-graph-execution-pattern-design.md` — Original graph execution design
+- `research/docs/2026-01-31-sdk-migration-and-graph-execution.md` — SDK migration planning
+
+---
+
+## Open Questions
+
+1. **Graph Migration for Ralph**: Should Ralph be rewritten to use the graph engine, or should the procedural handler be kept and the freeze fixed independently?
+2. **Module Consolidation Strategy**: Should `graph/` physically move under `workflows/`, or should it be re-exported through `workflows/index.ts`?
+3. **Subagent vs Agent Node**: The codebase has both `agentNode()` and `subagentNode()` — should these be unified for the simplified syntax?
+4. **Custom Tool Integration**: How should `.atomic/tools/` discovered tools become first-class graph nodes?
+5. **Checkpointing Completeness**: Current checkpointer backends (Memory, File) are basic — is SQLite/PostgreSQL support needed for the refactor?
+6. **Template Extensibility**: Should templates like `reviewCycle` and `taskLoop` be preserved as convenience functions or replaced by the new simplified syntax?
+7. **Test Coverage**: 13 test files exist in `src/graph/` covering builder, compiled, templates, types, annotations, providers, streaming, validation, and nodes. What additional tests are needed for the refactored API?
diff --git a/research/docs/2026-02-25-workflow-sdk-standardization.md b/research/docs/2026-02-25-workflow-sdk-standardization.md
new file mode 100644
index 0000000000..60a8f8f223
--- /dev/null
+++ b/research/docs/2026-02-25-workflow-sdk-standardization.md
@@ -0,0 +1,686 @@
+---
+date: 2026-02-25 08:15:53 UTC
+researcher: Copilot CLI
+git_commit: ace7e1566ce0e02a003a6508baae7db27d61dea0
+branch: lavaman131/feature/workflow-sdk
+repository: workflow-sdk
+topic: "Workflow SDK Standardization: Graph Engine, Ralph, Sub-Agents, State Management & Declarative API"
+tags: [research, codebase, workflow-sdk, graph-engine, ralph, sub-agents, state-management, declarative-api, workflow-discovery]
+status: complete
+last_updated: 2026-02-25
+last_updated_by: Copilot CLI
+---
+
+# Research: Workflow SDK Standardization
+
+## Research Question
+
+Research the current workflow implementation and Ralph implementation to standardize a new workflow-sdk. The SDK should be user-friendly, use sub-agents as building blocks, feature a clean declarative chaining API with support for loops, control structures (if/else), parallel branches, and typed state passing. Users should be able to add their own workflows via `~/.atomic/workflows` and `.atomic/workflows` using existing imported sub-agents.
+
+## Summary
+
+The Atomic codebase contains a mature graph-based workflow execution engine (`src/graph/`) with a fluent builder API, typed state annotations with reducers, 12+ node factories, and sub-agent integration. The "Ralph" workflow is the primary built-in workflow implementing a task-decomposition → DAG-dispatch → review cycle. Custom workflows are discovered from `.atomic/workflows/` (local) and `~/.atomic/workflows/` (global) as TypeScript files with standardized exports. The sub-agent system bridges to multiple coding agent SDKs (OpenCode, Claude Agent SDK, Copilot SDK) via a `SubagentGraphBridge` and `SubagentTypeRegistry`. External SDK analysis of LangGraph, Temporal, Inngest, and all three coding agent SDKs reveals converging patterns around typed state with reducers, declarative graph composition, session-first design, and hierarchical error handling. This document synthesizes all findings to inform the design of a standardized workflow SDK.
+
+---
+
+## Table of Contents
+
+1. [Graph Execution Engine](#1-graph-execution-engine)
+2. [State Management & Annotations](#2-state-management--annotations)
+3. [Node Factory System](#3-node-factory-system)
+4. [Sub-Agent System](#4-sub-agent-system)
+5. [Ralph Workflow Implementation](#5-ralph-workflow-implementation)
+6. [Workflow Discovery & Custom Workflows](#6-workflow-discovery--custom-workflows)
+7. [External SDK Patterns](#7-external-sdk-patterns)
+8. [Cross-Component Connections](#8-cross-component-connections)
+9. [Architecture Documentation](#9-architecture-documentation)
+10. [Code References](#10-code-references)
+11. [Historical Context](#11-historical-context)
+12. [Open Questions](#12-open-questions)
+
+---
+
+## 1. Graph Execution Engine
+
+### 1.1 GraphBuilder (`src/graph/builder.ts`)
+
+The `GraphBuilder` class (line 136) provides a fluent API for constructing graph-based workflows declaratively. Entry point is the `graph<TState>()` factory function (line 694).
+
+**Core API surface:**
+
+```typescript
+const workflow = graph<MyState>()
+  .start(startNode)
+  .then(nodeA)
+  .if(condition)
+    .then(nodeB)
+  .else()
+    .then(nodeC)
+  .endif()
+  .loop([nodeD, nodeE], { until: (state) => state.done, maxIterations: 100 })
+  .parallel([branchA, branchB], { strategy: "all", merge: mergeFunction })
+  .wait({ prompt: "Continue?" })
+  .catch(errorHandler)
+  .end()
+  .compile(config);
+```
+
+**Internal state:**
+
+| Field | Type | Purpose |
+|-------|------|---------|
+| `nodes` | `Map<NodeId, NodeDefinition<TState>>` | All node definitions by ID |
+| `edges` | `Edge<TState>[]` | Connections between nodes |
+| `startNodeId` | `NodeId \| null` | Entry point for execution |
+| `endNodeIds` | `Set<NodeId>` | Terminal nodes |
+| `currentNodeId` | `NodeId \| null` | Tracks position for chaining |
+| `conditionalStack` | `ConditionalBranch<TState>[]` | Stack for nested if/else |
+| `nodeCounter` | `number` | Unique ID generation |
+| `errorHandlerId` | `NodeId \| null` | Global error handler |
+
+**Control flow implementations:**
+
+- **if/else/endif** (lines 287-395): Pushes a `ConditionalBranch` onto a stack. The `if()` method creates a decision node, `else()` switches to the else branch, and `endif()` creates a merge node. Supports nesting via stack.
+- **loop** (lines 456-530): Creates `loop_start` → body nodes → `loop_check` with a back-edge to the first body node. Uses `LoopConfig.until` predicate and `maxIterations` (default: 100).
+- **parallel** (lines 399-453): Creates a parallel node with configurable `strategy`: `"all"` (Promise.all), `"race"` (Promise.race), `"any"` (Promise.any). Accepts optional `merge` function to combine branch results.
+
+### 1.2 GraphExecutor (`src/graph/compiled.ts`)
+
+The `GraphExecutor` class (line 213) executes compiled graphs via BFS traversal with a node queue. Key method is `stream()` (line 266) which yields `StepResult` per node.
+
+**Execution flow:**
+
+1. Initialize state and step counter
+2. Push start node onto queue
+3. Dequeue node → execute via `executeWithRetry()` (line 547)
+4. Merge `NodeResult.stateUpdate` into state (immutable merge; `outputs` is spread-merged)
+5. Evaluate outgoing edges, push matching targets onto queue
+6. Yield `StepResult` with node info, state snapshot, signals
+7. Check `maxSteps` and loop detection (`Set<string>` with `nodeId:stepCount` keys)
+
+**Retry logic:** Exponential backoff: `backoffMs × backoffMultiplier^(attempt-1)` with configurable `maxAttempts`.
+
+**Model resolution order:** node → parent config → GraphConfig → SDK default.
+
+**Factory functions:** `createExecutor()`, `executeGraph()`, `streamGraph()` at lines 721-757.
+
+### 1.3 Core Types (`src/graph/types.ts`)
+
+| Type | Line | Purpose |
+|------|------|---------|
+| `BaseState` | 109 | `{ executionId, lastUpdated, outputs: Record<NodeId, unknown> }` |
+| `NodeType` | 99 | `"agent" \| "tool" \| "decision" \| "wait" \| "ask_user" \| "subgraph" \| "parallel"` |
+| `NodeDefinition<TState>` | 309 | Node shape: id, type, name, description, retry?, execute(ctx) |
+| `NodeResult<TState>` | varies | Execution result: stateUpdate?, signals?, goto? |
+| `ExecutionContext<TState>` | 253 | Context passed to execute: state, config, model, emit?, contextWindowUsage? |
+| `CompiledGraph<TState>` | varies | Compiled executable: nodes Map, edges array, startNode, endNodes, config |
+| `GraphConfig` | 364 | maxSteps, contextWindowThreshold, defaultModel, checkpointer?, telemetryProvider? |
+| `RetryConfig` | varies | maxAttempts, backoffMs, backoffMultiplier |
+| `SignalData` | varies | Signals: `context_window_warning`, `human_input_required` |
+
+**Constants:** `BACKGROUND_COMPACTION_THRESHOLD = 0.45`, `BUFFER_EXHAUSTION_THRESHOLD = 0.6`
+
+---
+
+## 2. State Management & Annotations
+
+### 2.1 Annotation System (`src/graph/annotation.ts`)
+
+Inspired by LangGraph's annotation pattern. The `annotation<T>(default, reducer)` function creates an `Annotation<T>` that defines how state fields merge during updates.
+
+```typescript
+const messages = annotation<string[]>(
+  () => [],              // default factory
+  Reducers.concat        // reducer: (current, update) => [...current, ...update]
+);
+```
+
+**`AnnotationRoot`**: A schema of annotations that defines the full state shape. Created with `annotationRoot({ field1: annotation1, field2: annotation2, ... })`.
+
+### 2.2 Built-in Reducers (`Reducers` object)
+
+| Reducer | Behavior |
+|---------|----------|
+| `replace` | Overwrites current value entirely |
+| `concat` | Appends arrays: `[...current, ...update]` |
+| `merge` | Shallow merge objects: `{ ...current, ...update }` |
+| `mergeById` | Merge arrays of objects by `id` field |
+| `max` | Keeps the larger numeric value |
+| `min` | Keeps the smaller numeric value |
+| `sum` | Adds values: `current + update` |
+| `or` | Logical OR: `current \|\| update` |
+| `and` | Logical AND: `current && update` |
+| `ifDefined` | Only updates if new value is not undefined |
+
+### 2.3 Predefined State Schemas
+
+**`AtomicStateAnnotation`** (line 312): Base schema for general workflows with fields for messages, outputs, and execution metadata.
+
+**`RalphStateAnnotation`** (line 552): Extended schema for the Ralph workflow:
+- `researchDoc`, `specDoc`: Document content
+- `featureList`, `currentFeature`: Feature tracking
+- `yolo`: Boolean for auto-accept mode
+- `session` fields: sessionId, sessionDir
+- `completedFeatures`: Array tracking completion
+- Additional workflow-specific state
+
+**`RalphWorkflowState` interface** (line 466): TypeScript interface mirroring the Ralph annotation schema for type-safe access.
+
+---
+
+## 3. Node Factory System
+
+### 3.1 Overview (`src/graph/nodes.ts`)
+
+The codebase provides 12 node factory functions, each returning a `NodeDefinition<TState>`:
+
+| Factory | Line | Type | Purpose |
+|---------|------|------|---------|
+| `agentNode()` | 170 | `agent` | AI agent execution with model/prompt |
+| `toolNode()` | ~300 | `tool` | Execute a tool function |
+| `decisionNode()` | 577 | `decision` | Conditional routing based on state |
+| `waitNode()` | 668 | `wait` | Pause for human input |
+| `askUserNode()` | 816 | `ask_user` | Structured user questions |
+| `parallelNode()` | 988 | `parallel` | Concurrent branch execution |
+| `subgraphNode()` | 1126 | `subgraph` | Nested workflow execution |
+| `clearContextNode()` | 494 | `tool` | Context window clearing |
+| `contextMonitorNode()` | 1374 | `tool` | Context usage monitoring |
+| `customToolNode()` | ~1500 | `tool` | User-defined custom tools |
+| `subagentNode()` | 1710 | `agent` | Sub-agent execution by name |
+| `parallelSubagentNode()` | 1802 | `parallel` | Parallel sub-agent execution |
+
+### 3.2 Sub-Agent Node Factories
+
+**`subagentNode()`** (line 1710):
+- Looks up agent by `name` in `SubagentTypeRegistry`
+- Spawns via `SubagentGraphBridge.spawn()`
+- Maps result to state via user-provided `outputMapper`
+- Supports `timeout` and model override
+
+```typescript
+const workerNode = subagentNode<MyState>({
+  id: "worker",
+  name: "worker",               // Registry lookup name
+  promptBuilder: (state) => state.taskPrompt,
+  outputMapper: (result, state) => ({ taskResult: result.text }),
+  timeout: 120_000,
+});
+```
+
+**`parallelSubagentNode()`** (line 1802):
+- Spawns multiple agents via `bridge.spawnParallel()` (uses `Promise.allSettled`)
+- Merges results via user-provided `merge` function
+- Each agent gets its own prompt from `promptBuilder`
+
+```typescript
+const parallelWorkers = parallelSubagentNode<MyState>({
+  id: "parallel-workers",
+  agents: [
+    { name: "worker", prompt: (s) => s.task1Prompt },
+    { name: "worker", prompt: (s) => s.task2Prompt },
+  ],
+  merge: (results, state) => ({
+    allResults: results.map(r => r.text),
+  }),
+});
+```
+
+### 3.3 Subgraph Node
+
+**`subgraphNode()`** (line 1126):
+- Executes a nested compiled workflow as a single node
+- `inputMapper`: Transforms parent state → child state
+- `outputMapper`: Transforms child result → parent state update
+- Supports both direct `CompiledGraph` reference and string name resolution via `getWorkflowResolver()`
+
+```typescript
+const nested = subgraphNode<ParentState, ChildState>({
+  id: "deep-analysis",
+  subgraph: "analysis-workflow",  // Resolved by name at runtime
+  inputMapper: (state) => ({ doc: state.document, outputs: {}, errors: [] }),
+  outputMapper: (subState, parentState) => ({ analysisResults: subState.results }),
+});
+```
+
+---
+
+## 4. Sub-Agent System
+
+### 4.1 SubagentGraphBridge (`src/graph/subagent-bridge.ts`)
+
+The `SubagentGraphBridge` class (line 129) manages sub-agent lifecycle:
+
+- **`spawn()`** (line 145): Creates a session per agent, streams response, collects text and tool_use content blocks, truncates output to 4000 chars. Returns `SubagentResult` with `text`, `toolUses`, `success`.
+- **`spawnParallel()`** (line 277): Spawns multiple agents concurrently using `Promise.allSettled()`. Returns array of results.
+- **Abort support**: Uses `abortableAsyncIterable()` to support timeout and external abort signal.
+- **Session isolation**: Each sub-agent runs in its own session with its own context window.
+
+### 4.2 SubagentTypeRegistry (`src/graph/subagent-registry.ts`)
+
+Singleton map populated by `populateSubagentRegistry()` (line 79):
+
+- Scans agent definition directories:
+  - `.claude/agents/` (project + global `~/.claude/agents/`)
+  - `.opencode/agents/` (project + global `~/.opencode/agents/`)
+  - `.github/agents/` (project + global `~/.config/.copilot/agents/`)
+- Uses `discoverAgentInfos()` to parse agent YAML/JSON definitions
+- Stores `AgentInfo` objects keyed by agent name
+- Accessed via `SubagentTypeRegistry.get(name)` for lookup
+
+### 4.3 Agent Discovery Flow
+
+```
+populateSubagentRegistry()
+  └─> discoverAgentInfos()
+       ├─> scan .claude/agents/*.md (local + global)
+       ├─> scan .opencode/agents/*.yaml (local + global)
+       └─> scan .github/agents/*.md (local + global)
+  └─> For each AgentInfo: registry.set(name, info)
+```
+
+### 4.4 Global Singleton Pattern
+
+The sub-agent system uses a global setter pattern to avoid circular dependencies:
+
+| Setter | Purpose |
+|--------|---------|
+| `setClientProvider()` | SDK client factory for agent sessions |
+| `setSubagentBridge()` | SubagentGraphBridge instance |
+| `setSubagentRegistry()` | SubagentTypeRegistry instance |
+| `setWorkflowResolver()` | Subgraph name → CompiledGraph resolver |
+
+---
+
+## 5. Ralph Workflow Implementation
+
+### 5.1 Overview
+
+Ralph is the primary built-in workflow implementing an autonomous implementation cycle:
+
+```
+User Prompt → Task Decomposition → DAG Worker Dispatch → Review → Fix Cycle
+```
+
+### 5.2 Phase 1: Task Decomposition
+
+**File:** `src/graph/nodes/ralph.ts`
+
+- `buildSpecToTasksPrompt()` (line 36): Takes user prompt, generates an LLM prompt requesting JSON `TodoItem[]` array
+- Each `TodoItem` has: `id`, `title`, `description`, `status`, `blockedBy` (dependency array)
+- LLM output is parsed via `parseTasks()` which attempts direct JSON parse with regex fallback
+
+### 5.3 Phase 2: DAG Worker Dispatch
+
+**File:** `src/ui/commands/workflow-commands.ts` + `src/graph/nodes/ralph.ts`
+
+- `getReadyTasks()`: Computes the "ready set" — tasks whose `blockedBy` dependencies are all `"completed"`
+- `buildWorkerAssignment()` (line 101): Creates per-task prompts with full context
+- `buildDagDispatchPrompt()` (line 210): Creates a prompt for orchestrating multiple workers
+- Workers dispatched via `context.spawnSubagent()` — currently **serial** (one worker at a time)
+- Each worker receives full task list with its assignment highlighted
+
+**Current limitation:** The worker loop is sequential due to the single-slot `streamCompletionResolverRef` in the TUI chat system. `SubagentGraphBridge.spawnParallel()` exists but is unused by Ralph.
+
+### 5.4 Phase 3: Review & Fix
+
+- `buildReviewPrompt()`: Generates review prompt for completed work
+- `parseReviewResult()`: Extracts pass/fail and feedback
+- `buildFixSpecFromReview()`: Creates fix spec for recursive fix iterations
+- Constants: `MAX_RALPH_ITERATIONS = 100`, `MAX_REVIEW_ITERATIONS = 1`
+
+### 5.5 Session Management
+
+**File:** `src/workflows/session.ts`
+
+- `WorkflowSession` interface (line 17): `{ sessionId, sessionDir, tasksFile, checkpointDir }`
+- `initWorkflowSession()` (line 51): Creates `~/.atomic/workflows/sessions/{uuid}/` with subdirs: `checkpoints/`, `agents/`, `logs/`
+- Tasks persisted to `tasks.json` with atomic file writes (temp file + rename)
+- `fs.watch` on `tasks.json` triggers reactive UI updates in the TUI
+
+---
+
+## 6. Workflow Discovery & Custom Workflows
+
+### 6.1 Discovery System
+
+Custom workflows are TypeScript files discovered from two locations:
+
+| Location | Priority | Scope |
+|----------|----------|-------|
+| `.atomic/workflows/` | Highest | Project-local |
+| `~/.atomic/workflows/` | Lower | User-global |
+
+Built-in workflows (e.g., Ralph) have lowest priority and are overridden by custom workflows with the same name.
+
+### 6.2 Required Exports
+
+Each workflow TypeScript file must export:
+
+```typescript
+// Required
+export const name: string;           // Workflow identifier (used as slash command)
+export const description: string;    // Human-readable description
+
+// Optional
+export const aliases: string[];      // Alternative names
+export const defaultConfig: Partial<GraphConfig>;  // Default execution config
+export function buildGraph<TState extends BaseState>(): CompiledGraph<TState>;
+```
+
+### 6.3 Loading Pipeline
+
+```
+loadWorkflowsFromDisk()
+  ├─> Scan .atomic/workflows/*.ts (local)
+  ├─> Scan ~/.atomic/workflows/*.ts (global)
+  ├─> For each file: dynamic import → extract exports
+  ├─> Priority: local > global > built-in
+  └─> Register as slash command in CommandRegistry
+```
+
+### 6.4 Workflow Resolution for Subgraphs
+
+`setWorkflowResolver()` / `getWorkflowResolver()` enables string-based workflow references in `subgraphNode()`:
+
+```typescript
+// At initialization
+setWorkflowResolver((name) => {
+  const workflow = loadedWorkflows.get(name);
+  return workflow?.buildGraph();
+});
+
+// In workflow definition
+subgraphNode({ subgraph: "my-workflow" }); // Resolved at runtime
+```
+
+### 6.5 Search Path Constants
+
+Defined in `src/ui/commands/workflow-commands.ts`:
+
+```typescript
+export const CUSTOM_WORKFLOW_SEARCH_PATHS = [
+  ".atomic/workflows",       // Local project workflows (highest priority)
+  "~/.atomic/workflows",     // Global user workflows
+];
+```
+
+---
+
+## 7. External SDK Patterns
+
+### 7.1 Coding Agent SDKs
+
+**Claude Agent SDK** (`anthropics/claude-agent-sdk-typescript`):
+- Session-based architecture with V2 APIs: `createSession()`, `resumeSession()`, `prompt()`
+- Sub-agents defined inline via `agents: Record<string, AgentConfig>`
+- Streaming via `Session.stream()` with events: `task_started`, `task_notification`, `TaskCompleted`
+- MCP protocol for tool integration with annotations
+
+**GitHub Copilot SDK** (`github/copilot-sdk`):
+- Session persistence to disk (`~/.copilot/session-state/`)
+- Custom agents with tool scoping and permission controls
+- Rich hook system: `onPreToolUse`, `onPostToolUse`, `onErrorOccurred`
+- Multi-language support (TypeScript, Python, Go, .NET)
+
+**OpenCode SDK** (`anomalyco/opencode`):
+- Primary/subagent architecture with Task tool for delegation
+- File-based tool discovery with plugin system
+- 40+ streaming event types via Server-Sent Events (SSE)
+- Permission-based task invocation with glob patterns
+
+### 7.2 Workflow Orchestration Frameworks
+
+**LangGraph** (LangChain):
+- `StateGraph` with typed state and reducers for merging — directly inspired the current annotation system
+- Declarative graph composition with conditional edges via `addConditionalEdges()`
+- Checkpointing with multiple backends (Memory, SQLite, PostgreSQL)
+- Three durability modes: sync, async, exit
+- Multiple streaming modes: values, updates, custom, messages, tasks, debug
+
+**Temporal** (TypeScript):
+- Workflow-as-code with deterministic execution
+- Event sourcing for durable execution and replay
+- Failure type hierarchy: `ApplicationFailure`, `ActivityFailure`, `TimeoutFailure`
+- Child workflows with cancellation policies
+- Compensation logic via `CancellationScope`
+
+**Inngest**:
+- Step API: `step.run()`, `step.sleep()`, `step.waitForEvent()`, `step.invoke()`
+- Memoization-based state management — each step result is cached
+- Fan-out/fan-in with `group.Parallel`
+- Declarative CUE schema for function definition
+- Function and step-level retry policies
+
+### 7.3 Converging Patterns Across All SDKs
+
+| Pattern | Present In | Current Implementation |
+|---------|-----------|----------------------|
+| **Typed state with reducers** | LangGraph, current codebase | `annotation()` + `Reducers` in `annotation.ts` |
+| **Fluent builder API** | LangGraph, current codebase | `GraphBuilder` with `.then()`, `.if()`, `.loop()` |
+| **Session-first design** | All coding agent SDKs | `WorkflowSession` + per-agent sessions |
+| **Sub-agent composition** | All SDKs | `subagentNode()`, `parallelSubagentNode()` |
+| **String-based resolution** | LangGraph, current codebase | `subgraphNode()` with name strings |
+| **Checkpointing** | LangGraph, Temporal | `checkpointer?` in `GraphConfig` |
+| **Exponential retry** | Temporal, Inngest, current | `RetryConfig` with backoff |
+| **Parallel branches** | LangGraph, Inngest, current | `parallel()` with merge strategies |
+| **Context window management** | Claude Agent SDK, current | `contextMonitorNode()` with thresholds |
+
+---
+
+## 8. Cross-Component Connections
+
+### 8.1 Data Flow: Workflow Definition → Execution
+
+```
+User TypeScript file (.atomic/workflows/my-flow.ts)
+  └─> loadWorkflowsFromDisk() discovers and imports
+  └─> Exports: name, description, buildGraph()
+  └─> buildGraph() uses GraphBuilder fluent API
+       ├─> Creates NodeDefinitions via factory functions
+       ├─> Wires edges with conditions
+       └─> compile() produces CompiledGraph
+  └─> GraphExecutor.stream() runs the compiled graph
+       ├─> BFS traversal through nodes
+       ├─> Each node's execute(ctx) called with ExecutionContext
+       ├─> State updated immutably after each node
+       └─> Yields StepResult stream
+```
+
+### 8.2 Sub-Agent Integration Path
+
+```
+subagentNode({ name: "worker", ... })
+  └─> SubagentTypeRegistry.get("worker")
+       └─> Returns AgentInfo from discovery
+  └─> SubagentGraphBridge.spawn(agentInfo, prompt)
+       ├─> Creates session via ClientProvider
+       ├─> Streams response chunks
+       ├─> Collects text + tool_use blocks
+       └─> Returns SubagentResult { text, toolUses, success }
+  └─> outputMapper(result, state) → state update
+```
+
+### 8.3 State Flow Through Nodes
+
+```
+BaseState { executionId, lastUpdated, outputs }
+  └─> Node execute(ctx) reads ctx.state
+  └─> Returns NodeResult { stateUpdate: Partial<TState> }
+  └─> Executor merges: { ...state, ...stateUpdate, outputs: { ...state.outputs, ...stateUpdate.outputs } }
+  └─> Updated state passed to next node
+```
+
+### 8.4 Custom Workflow → Sub-Agent → Graph Interplay
+
+A user-defined workflow in `~/.atomic/workflows/my-flow.ts` can:
+
+1. Import node factories: `subagentNode`, `parallelSubagentNode`, `subgraphNode`
+2. Reference agents by name (auto-discovered from `.claude/agents/`, `.opencode/agents/`, `.github/agents/`)
+3. Reference other workflows by name via `subgraphNode("other-workflow")`
+4. Define custom state extending `BaseState`
+5. Use all control flow: `.if()`, `.loop()`, `.parallel()`
+
+---
+
+## 9. Architecture Documentation
+
+### 9.1 Module Dependency Graph
+
+```
+src/graph/
+├── types.ts          ← Foundation types (BaseState, NodeDefinition, etc.)
+├── annotation.ts     ← State annotations + reducers (depends on types.ts)
+├── builder.ts        ← GraphBuilder fluent API (depends on types.ts)
+├── compiled.ts       ← GraphExecutor (depends on types.ts)
+├── nodes.ts          ← Node factories (depends on types.ts, annotation.ts)
+├── nodes/
+│   └── ralph.ts      ← Ralph prompt utilities (depends on types.ts)
+├── subagent-bridge.ts ← Sub-agent session management
+├── subagent-registry.ts ← Agent type discovery
+├── errors.ts         ← Error types
+└── index.ts          ← Barrel exports (304 lines)
+
+src/workflows/
+├── session.ts        ← WorkflowSession management
+
+src/ui/commands/
+├── workflow-commands.ts ← Ralph command handler + workflow discovery
+```
+
+### 9.2 Design Patterns
+
+| Pattern | Usage | Files |
+|---------|-------|-------|
+| **Fluent Builder** | GraphBuilder chaining API | `builder.ts` |
+| **Factory Function** | Node creation (`agentNode()`, etc.) | `nodes.ts` |
+| **Global Singleton** | `setClientProvider()`, `setSubagentBridge()`, etc. | Various |
+| **Immutable State** | State merging in executor | `compiled.ts` |
+| **BFS Traversal** | Graph execution order | `compiled.ts` |
+| **Stack-based Nesting** | if/else conditional tracking | `builder.ts` |
+| **Annotation/Reducer** | LangGraph-inspired state management | `annotation.ts` |
+| **Atomic File Writes** | Task state persistence (temp + rename) | `workflow-commands.ts` |
+| **Registry Pattern** | SubagentTypeRegistry, CommandRegistry | `subagent-registry.ts` |
+
+### 9.3 Execution Modes
+
+| Mode | Description | Entry Point |
+|------|-------------|-------------|
+| **Streaming** | Yields `StepResult` per node | `GraphExecutor.stream()` |
+| **Full execution** | Runs to completion, returns final state | `executeGraph()` |
+| **Stream helper** | Convenience async generator | `streamGraph()` |
+| **Inline (TUI)** | Runs within main chat event loop via `streamAndWait()` | `workflow-commands.ts` |
+
+---
+
+## 10. Code References
+
+### Core Graph Engine
+- `src/graph/builder.ts:136` — `GraphBuilder` class
+- `src/graph/builder.ts:694` — `graph<TState>()` factory function
+- `src/graph/builder.ts:287-395` — if/else/endif implementation
+- `src/graph/builder.ts:456-530` — loop implementation
+- `src/graph/builder.ts:399-453` — parallel implementation
+- `src/graph/compiled.ts:213` — `GraphExecutor` class
+- `src/graph/compiled.ts:266` — `stream()` generator method
+- `src/graph/compiled.ts:547` — `executeWithRetry()` with exponential backoff
+- `src/graph/compiled.ts:510` — `resolveModel()` chain
+- `src/graph/compiled.ts:721-757` — Factory functions (`createExecutor`, `executeGraph`, `streamGraph`)
+
+### Types & State
+- `src/graph/types.ts:109` — `BaseState` interface
+- `src/graph/types.ts:99` — `NodeType` union
+- `src/graph/types.ts:309` — `NodeDefinition<TState>` interface
+- `src/graph/types.ts:253` — `ExecutionContext<TState>` interface
+- `src/graph/types.ts:364` — `GraphConfig` interface
+- `src/graph/annotation.ts:312` — `AtomicStateAnnotation`
+- `src/graph/annotation.ts:552` — `RalphStateAnnotation`
+- `src/graph/annotation.ts:466` — `RalphWorkflowState` interface
+
+### Node Factories
+- `src/graph/nodes.ts:170` — `agentNode()`
+- `src/graph/nodes.ts:494` — `clearContextNode()`
+- `src/graph/nodes.ts:577` — `decisionNode()`
+- `src/graph/nodes.ts:668` — `waitNode()`
+- `src/graph/nodes.ts:816` — `askUserNode()`
+- `src/graph/nodes.ts:988` — `parallelNode()`
+- `src/graph/nodes.ts:1126` — `subgraphNode()`
+- `src/graph/nodes.ts:1374` — `contextMonitorNode()`
+- `src/graph/nodes.ts:1710` — `subagentNode()`
+- `src/graph/nodes.ts:1802` — `parallelSubagentNode()`
+
+### Sub-Agent System
+- `src/graph/subagent-bridge.ts:129` — `SubagentGraphBridge` class
+- `src/graph/subagent-bridge.ts:145` — `spawn()` method
+- `src/graph/subagent-bridge.ts:277` — `spawnParallel()` method
+- `src/graph/subagent-registry.ts:28` — `SubagentTypeRegistry` singleton
+- `src/graph/subagent-registry.ts:79` — `populateSubagentRegistry()`
+
+### Ralph Workflow
+- `src/graph/nodes/ralph.ts:36` — `buildSpecToTasksPrompt()`
+- `src/graph/nodes/ralph.ts:101` — `buildWorkerAssignment()`
+- `src/graph/nodes/ralph.ts:210` — `buildDagDispatchPrompt()`
+- `src/workflows/session.ts:17` — `WorkflowSession` interface
+- `src/workflows/session.ts:51` — `initWorkflowSession()`
+
+### Workflow Discovery
+- `src/ui/commands/workflow-commands.ts:64` — `parseRalphArgs()`
+- `src/ui/commands/workflow-commands.ts:84` — `WorkflowMetadata`
+
+### Barrel Exports
+- `src/graph/index.ts` — Full public API (304 lines)
+
+---
+
+## 11. Historical Context
+
+### Related Research Documents
+
+| Document | Date | Relevance |
+|----------|------|-----------|
+| `research/docs/2026-01-31-graph-execution-pattern-design.md` | 2026-01-31 | Original graph execution pattern design with LangGraph, XState, Effect-TS comparisons |
+| `research/docs/2026-01-31-sdk-migration-and-graph-execution.md` | 2026-01-31 | SDK migration paths for OpenCode, Claude, Copilot with graph execution API design |
+| `research/docs/2026-02-03-workflow-composition-patterns.md` | 2026-02-03 | Subgraph usage, workflow resolution by name, state passing between workflows |
+| `research/docs/2026-02-03-custom-workflow-file-format.md` | 2026-02-03 | Custom workflow TypeScript file format, exports, discovery paths |
+| `research/docs/2026-02-05-pluggable-workflows-sdk-design.md` | 2026-02-05 | Pluggable SDK design with unified entity registry and provider-agnostic execution |
+| `research/docs/2026-02-11-workflow-sdk-implementation.md` | 2026-02-11 | Workflow SDK implementation with custom tools and sub-agent integration |
+| `research/docs/2026-02-15-ralph-dag-orchestration-implementation.md` | 2026-02-15 | Ralph DAG orchestration with blockedBy enforcement and parallel worker dispatch |
+| `research/docs/2026-02-15-ralph-dag-orchestration-blockedby.md` | 2026-02-15 | blockedBy field enforcement analysis in Ralph task dispatch |
+| `research/docs/2026-02-21-workflow-sdk-inline-mode-research.md` | 2026-02-21 | Workflow SDK inline execution in TUI chat context |
+| `research/graph-execution-engine-technical-documentation.md` | 2026-02-25 | Comprehensive graph engine technical docs (2234 lines) — created during this research |
+| `research/workflow_sdk_patterns.md` | 2026-02-25 | External SDK patterns analysis (2189 lines) — created during this research |
+
+### Existing Specs
+
+| Spec | Relevance |
+|------|-----------|
+| `specs/workflow-sdk-implementation.md` | Implementation spec for customToolNode, subagentNode, parallelSubagentNode |
+| `specs/ralph-dag-orchestration.md` | Spec for Ralph DAG-based orchestration with parallel dispatch |
+
+---
+
+## 12. Open Questions
+
+1. **Serial vs Parallel Worker Dispatch in Ralph:** The `SubagentGraphBridge.spawnParallel()` exists but Ralph's worker loop is serial due to the TUI's single-slot `streamCompletionResolverRef`. How should the standardized SDK handle this architectural constraint?
+
+2. **State Schema Enforcement:** The annotation system supports reducers, but there's no runtime validation that state updates conform to the schema. Should the SDK add Zod-based runtime validation?
+
+3. **Workflow Versioning:** No mechanism exists for workflow versioning or migration. As workflows evolve, how should state compatibility be handled across versions?
+
+4. **Error Propagation in Subgraphs:** When a nested subgraph fails, how should errors propagate to the parent graph? Currently the `catch()` handler is graph-level, not node-level.
+
+5. **Custom Tool Integration in Workflows:** Custom tools from `.atomic/tools/*.ts` are registered at the SDK client level but not yet directly composable within workflow graph nodes. How should the SDK bridge this gap?
+
+6. **Checkpointing Implementation:** `GraphConfig` includes a `checkpointer?` field, but the actual checkpointing backends are not yet implemented. What persistence strategies should the SDK support?
+
+7. **User Workflow Authoring DX:** The current export-based workflow format requires knowledge of the full graph API. Should the SDK provide a higher-level DSL or template system for common patterns?
+
+8. **Provider-Agnostic Sub-Agent Execution:** Sub-agents are tied to specific coding agent SDKs. How should the workflow SDK abstract over different providers for the same agent type?
+
+---
+
+## Supporting Research Documents
+
+The following documents were created during this research session and contain detailed deep-dive analysis:
+
+- **`research/docs/2026-02-25-graph-execution-engine-technical-documentation.md`** — 2234-line comprehensive technical analysis of the graph execution engine (GraphBuilder, GraphExecutor, types, node factories, error handling, data flow)
+- **`research/docs/2026-02-25-workflow-sdk-patterns.md`** — 2189-line analysis of external SDK patterns (Claude Agent SDK, Copilot SDK, OpenCode SDK, LangGraph, Temporal, Inngest) with comparative tables and code examples
diff --git a/research/docs/2026-02-26-opencode-event-bus-patterns.md b/research/docs/2026-02-26-opencode-event-bus-patterns.md
new file mode 100644
index 0000000000..1dc4fee29e
--- /dev/null
+++ b/research/docs/2026-02-26-opencode-event-bus-patterns.md
@@ -0,0 +1,1082 @@
+# OpenCode Event-Bus Architecture Research
+
+**Date**: 2026-02-26  
+**Repository**: anomalyco/opencode  
+**Research Focus**: Event-bus patterns, coalescing, batching, and streaming architecture
+
+---
+
+## Executive Summary
+
+OpenCode implements a sophisticated event-driven architecture centered around a type-safe `Bus` system with Zod schema validation. The architecture features:
+
+1. **Type-Safe Event System**: `BusEvent.define()` with Zod schemas for compile-time safety
+2. **Global Bus Distribution**: Events published locally also emit to `GlobalBus` for SSE streaming
+3. **Client-Side Coalescing**: Key-based event coalescing reduces redundant updates
+4. **Batch Flushing**: 16ms frame-aligned batching for optimal render performance
+5. **Backpressure Management**: Queue swapping, yielding, and coalescing prevent UI blocking
+
+---
+
+## 1. OpenCode's Bus System
+
+### 1.1 Core Implementation
+
+**Location**: `packages/opencode/src/bus/index.ts`
+
+The `Bus` namespace provides three core methods for pub/sub communication:
+
+#### `Bus.publish()`
+
+Publishes events to both local subscribers and the global event stream.
+
+```typescript
+export async function publish<Definition extends BusEvent.Definition>(
+  def: Definition,
+  properties: z.output<Definition["properties"]>,
+) {
+  const payload = {
+    type: def.type,
+    properties,
+  }
+  log.info("publishing", {
+    type: def.type,
+  })
+  const pending = []
+  // Notify both specific subscribers and wildcard subscribers
+  for (const key of [def.type, "*"]) {
+    const match = state().subscriptions.get(key)
+    for (const sub of match ?? []) {
+      pending.push(sub(payload))
+    }
+  }
+  // Emit to GlobalBus for SSE streaming
+  GlobalBus.emit("event", {
+    directory: Instance.directory,
+    payload,
+  })
+  return Promise.all(pending)
+}
+```
+
+**Key Features**:
+- Dual publishing: local subscriptions + `GlobalBus` for SSE
+- Type-safe with Zod schema validation
+- Both specific type subscribers and wildcard (`"*"`) subscribers receive events
+- Async execution with `Promise.all()` for concurrent handler invocation
+
+#### `Bus.subscribe()`
+
+Subscribe to specific event types with type-safe callbacks.
+
+```typescript
+export function subscribe<Definition extends BusEvent.Definition>(
+  def: Definition,
+  callback: (event: { 
+    type: Definition["type"]; 
+    properties: z.infer<Definition["properties"]> 
+  }) => void,
+) {
+  return raw(def.type, callback)
+}
+```
+
+**Example Usage**: Version Control System (VCS) monitoring branch changes
+
+**Location**: `packages/opencode/src/project/vcs.ts` (lines ~56)
+
+```typescript
+const unsubscribe = Bus.subscribe(FileWatcher.Event.Updated, async (evt) => {
+  if (evt.properties.file.endsWith("HEAD")) return
+  const next = await currentBranch()
+  if (next !== current) {
+    log.info("branch changed", { from: current, to: next })
+    current = next
+    Bus.publish(Event.BranchUpdated, { branch: next })
+  }
+})
+```
+
+#### `Bus.subscribeAll()`
+
+Subscribe to all events (wildcard subscription).
+
+```typescript
+export function subscribeAll(callback: (event: any) => void) {
+  return raw("*", callback)
+}
+```
+
+**Example Usage**: Server SSE streaming
+
+```typescript
+const unsub = Bus.subscribeAll(async (event) => {
+  await stream.writeSSE({
+    data: JSON.stringify(event),
+  })
+  if (event.type === Bus.InstanceDisposed.type) {
+    stream.close()
+  }
+})
+```
+
+### 1.2 Subscription Management
+
+- **Internal Storage**: `Map<string, Set<Function>>` keyed by event type
+- **Wildcard Key**: `"*"` key for all-event subscribers
+- **Cleanup**: `unsubscribe()` function returned for cleanup
+- **Special Events**: `Bus.InstanceDisposed` signals cleanup time
+
+---
+
+## 2. BusEvent.define() Pattern
+
+### 2.1 Type-Safe Event Definition
+
+**Pattern**: Define events with type string + Zod schema
+
+```typescript
+BusEvent.define(
+  "event.type.string",
+  z.object({ /* properties schema */ })
+)
+```
+
+### 2.2 Real-World Examples
+
+#### MCP Tools Changed Event
+
+**Location**: `packages/opencode/src/mcp/index.ts`
+
+```typescript
+export const ToolsChanged = BusEvent.define(
+  "mcp.tools.changed",
+  z.object({
+    server: z.string(),
+  }),
+)
+```
+
+**Use Case**: Notify when MCP server tools are updated
+
+#### Session Created Event
+
+**Location**: `packages/opencode/src/session/index.ts`
+
+```typescript
+export const Event = {
+  Created: BusEvent.define(
+    "session.created",
+    z.object({
+      info: Info, // Info is another Zod schema
+    }),
+  ),
+  // ... other events
+}
+```
+
+**Publishing Example**:
+
+```typescript
+Database.use((db) => {
+  db.insert(SessionTable).values(toRow(result)).run()
+  Database.effect(() =>
+    Bus.publish(Event.Created, {
+      info: result,
+    }),
+  )
+})
+```
+
+**Key Pattern**: Database operations → `Database.effect()` → `Bus.publish()` ensures events fire after DB commits
+
+#### File Watcher Updated Event
+
+**Location**: `packages/opencode/src/file/watcher.ts`
+
+```typescript
+export const Event = {
+  Updated: BusEvent.define(
+    "file.watcher.updated",
+    z.object({
+      file: z.string(),
+      event: z.union([
+        z.literal("add"), 
+        z.literal("change"), 
+        z.literal("unlink")
+      ]),
+    }),
+  ),
+}
+```
+
+**Features**:
+- Union types for finite event values
+- Strong typing prevents invalid event types
+
+### 2.3 Benefits
+
+1. **Compile-Time Safety**: TypeScript + Zod catch errors before runtime
+2. **Runtime Validation**: Zod ensures payloads match expected structure
+3. **IDE Support**: Autocomplete and type inference for event properties
+4. **Maintainability**: Schema changes propagate through type system
+5. **Documentation**: Schema serves as API documentation
+
+---
+
+## 3. Event Coalescing & Batching (global-sdk.tsx)
+
+### 3.1 Implementation Overview
+
+**Location**: `packages/app/src/context/global-sdk.tsx` (lines 46-84)
+
+The client-side event processor implements:
+- **Key-based coalescing**: Deduplicate rapid updates to same entity
+- **Queue buffering**: Collect events during frame
+- **Batch flushing**: Process events every 16ms (60fps aligned)
+- **Double-buffer pattern**: Swap queue/buffer for concurrent collection
+
+### 3.2 Key Generation Function
+
+```typescript
+const key = (directory: string, payload: Event) => {
+  if (payload.type === "session.status") 
+    return `session.status:${directory}:${payload.properties.sessionID}`
+  
+  if (payload.type === "lsp.updated") 
+    return `lsp.updated:${directory}`
+  
+  if (payload.type === "message.part.updated") {
+    const part = payload.properties.part
+    return `message.part.updated:${directory}:${part.messageID}:${part.id}`
+  }
+}
+```
+
+**Coalescing Strategy**:
+- `session.status`: Per-session per-directory (prevents duplicate status updates)
+- `lsp.updated`: Per-directory (single LSP update per directory)
+- `message.part.updated`: Per-part per-message per-directory (fine-grained)
+
+### 3.3 Event Processing Loop
+
+```typescript
+const queue = []
+const buffer = []
+const coalesced = new Map() // Map<string, number> - key -> queue index
+
+for await (const event of events.stream) {
+  streamErrorLogged = false
+  const directory = event.directory ?? "global"
+  const payload = event.payload
+  const k = key(directory, payload)
+  
+  if (k) {
+    const i = coalesced.get(k)
+    if (i !== undefined) {
+      // Update existing event in-place (coalescing!)
+      queue[i] = { directory, payload }
+      continue
+    }
+    coalesced.set(k, queue.length)
+  }
+  
+  queue.push({ directory, payload })
+  schedule()
+
+  // Yield control every 8ms to prevent blocking
+  if (Date.now() - yielded < STREAM_YIELD_MS) continue
+  yielded = Date.now()
+  await wait(0)
+}
+```
+
+**Key Mechanisms**:
+1. **In-Place Update**: If key exists, replace event at recorded index
+2. **Index Tracking**: `coalesced` Map stores queue index for O(1) lookup
+3. **Periodic Yielding**: Every 8ms yield to event loop (prevents UI freeze)
+
+### 3.4 Flush Function (Double-Buffer Swap)
+
+```typescript
+const flush = () => {
+  if (timer) clearTimeout(timer)
+  timer = undefined
+
+  if (queue.length === 0) return
+
+  // Double-buffer swap
+  const events = queue
+  queue = buffer
+  buffer = events
+  queue.length = 0
+  coalesced.clear()
+
+  last = Date.now()
+  batch(() => {
+    for (const event of events) {
+      emitter.emit(event.directory, event.payload)
+    }
+  })
+
+  buffer.length = 0
+}
+```
+
+**Pattern Benefits**:
+- **Concurrent Collection**: New events enter `queue` while `buffer` is being processed
+- **Atomic Swap**: Reference swap is instantaneous
+- **SolidJS Batch**: `batch()` ensures single render cycle for all updates
+- **Clear State**: Reset queue and coalesced map after processing
+
+### 3.5 Constants
+
+```typescript
+const FLUSH_FRAME_MS = 16    // 60fps frame time
+const STREAM_YIELD_MS = 8    // Yield to event loop every 8ms
+const RECONNECT_DELAY_MS = 250 // SSE reconnection delay
+```
+
+### 3.6 Scheduling Logic
+
+```typescript
+const schedule = () => {
+  if (timer) return
+  const elapsed = Date.now() - last
+  const delay = Math.max(0, FLUSH_FRAME_MS - elapsed)
+  timer = setTimeout(flush, delay)
+}
+```
+
+**Adaptive Timing**: Ensures flushes happen at ~60fps while allowing immediate flush if > 16ms elapsed
+
+---
+
+## 4. End-to-End Streaming Flow
+
+### 4.1 Complete Flow Diagram
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                         BACKEND (OpenCode)                          │
+├─────────────────────────────────────────────────────────────────────┤
+│                                                                     │
+│  1. LLM.stream (AI SDK)                                            │
+│     ├─ streamText() from @ai-sdk/core                              │
+│     ├─ Provider API (OpenAI, Anthropic, etc.)                      │
+│     └─ SSE chunks from LLM                                         │
+│                                                                     │
+│  2. TransformStream (AI SDK Internal)                              │
+│     ├─ Processes stream parts:                                     │
+│     │   • stream-start                                             │
+│     │   • raw                                                       │
+│     │   • error                                                     │
+│     │   • response-metadata                                         │
+│     │   • usage info                                                │
+│     └─ Pipes to SessionProcessor                                   │
+│                                                                     │
+│  3. SessionProcessor.create / process()                            │
+│     ├─ Iterates over fullStream                                    │
+│     ├─ Handles stream types:                                       │
+│     │   • reasoning-start                                          │
+│     │   • reasoning-delta                                          │
+│     │   • text-delta                                               │
+│     │   • tool-call                                                │
+│     ├─ Calls Session.updatePart()                                  │
+│     └─ Calls Session.updatePartDelta()                             │
+│                                                                     │
+│  4. Database.effect() + Bus.publish()                              │
+│     ├─ Database commits trigger effects                            │
+│     ├─ Publishes typed events:                                     │
+│     │   • MessageV2.Event.PartUpdated                              │
+│     │   • Session.Event.StatusUpdated                              │
+│     └─ Events go to local subscribers + GlobalBus                  │
+│                                                                     │
+│  5. GlobalBus.emit("event", {...})                                 │
+│     ├─ Cross-module event distribution                             │
+│     └─ Feeds SSE endpoints                                         │
+│                                                                     │
+│  6. SSE Endpoints (Hono streamSSE)                                 │
+│     ├─ /global/event (global events)                               │
+│     ├─ /session/:id/event (session-specific)                       │
+│     ├─ Bus.subscribeAll() writes to SSE stream                     │
+│     └─ Periodic heartbeats prevent timeout                         │
+│                                                                     │
+└─────────────────────────────────────────────────────────────────────┘
+                                 │
+                                 │ SSE Stream (HTTP)
+                                 ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                        FRONTEND (Client)                            │
+├─────────────────────────────────────────────────────────────────────┤
+│                                                                     │
+│  7. @opencode-ai/sdk: createSseClient()                            │
+│     ├─ eventSdk.global.event() subscribes to SSE                   │
+│     └─ Parses event stream                                         │
+│                                                                     │
+│  8. GlobalSDKProvider Event Queue                                  │
+│     ├─ for await (const event of events.stream)                    │
+│     ├─ Key-based coalescing (session.status, etc.)                 │
+│     ├─ Buffer/Queue swap pattern                                   │
+│     └─ Scheduled flush every 16ms                                  │
+│                                                                     │
+│  9. batch(() => emitter.emit())                                    │
+│     ├─ SolidJS batch for single render                             │
+│     └─ createGlobalEmitter dispatches events                       │
+│                                                                     │
+│ 10. Component Subscribers                                          │
+│     ├─ useGlobalEvent(directory, eventType, handler)               │
+│     ├─ SolidJS signals/stores update                               │
+│     └─ UI re-renders (single optimized cycle)                      │
+│                                                                     │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+### 4.2 Key Components
+
+#### Backend: SessionProcessor
+
+**Location**: `packages/opencode/src/session/processor.ts`
+
+```typescript
+// Pseudo-code structure
+SessionProcessor.create({
+  async process() {
+    for await (const value of fullStream) {
+      if (value.type === "reasoning-start") {
+        // Update reasoning part
+        Session.updatePart(...)
+      }
+      if (value.type === "reasoning-delta") {
+        // Update reasoning content
+        Session.updatePartDelta(...)
+      }
+      // ... handle other stream types
+    }
+  }
+})
+```
+
+**Event Chain**:
+1. `Session.updatePart()` → Database write
+2. `Database.effect()` → Triggers after commit
+3. `Bus.publish(MessageV2.Event.PartUpdated, {...})` → Publishes event
+4. `GlobalBus.emit()` → SSE distribution
+
+#### Backend: SSE Endpoints
+
+**Locations**:
+- `/global/event`: `packages/opencode/src/server/routes/global.ts`
+- `/session/:id/event`: Session-specific endpoint
+
+```typescript
+app.get('/global/event', async (c) => {
+  return streamSSE(c, async (stream) => {
+    const unsub = Bus.subscribeAll(async (event) => {
+      await stream.writeSSE({
+        data: JSON.stringify(event),
+      })
+      if (event.type === Bus.InstanceDisposed.type) {
+        stream.close()
+      }
+    })
+    
+    // Heartbeat every 30s
+    const heartbeat = setInterval(() => {
+      stream.writeSSE({ comment: 'heartbeat' })
+    }, 30000)
+    
+    // Cleanup
+    stream.onAbort(() => {
+      clearInterval(heartbeat)
+      unsub()
+    })
+  })
+})
+```
+
+#### Frontend: Event Consumer
+
+**Location**: `packages/app/src/context/global-sdk.tsx`
+
+```typescript
+const GlobalSDKProvider = (props) => {
+  useInit(() => {
+    const eventSdk = createSseClient(config)
+    const events = eventSdk.global.event()
+    
+    const emitter = createGlobalEmitter()
+    let queue = []
+    let buffer = []
+    const coalesced = new Map()
+    
+    ;(async () => {
+      for await (const event of events.stream) {
+        // Coalescing + queueing logic
+        // ... (see section 3.3)
+      }
+    })()
+    
+    return () => {
+      // Cleanup
+    }
+  })
+  
+  return <GlobalSDKContext.Provider value={...}>
+    {props.children}
+  </GlobalSDKContext.Provider>
+}
+```
+
+### 4.3 Data Format Example
+
+**SSE Stream Format**:
+```
+data: {"type":"message.part.updated","properties":{"part":{"id":"part_123","messageID":"msg_456","content":"Hello"}}}
+
+data: {"type":"session.status","properties":{"sessionID":"sess_789","status":"running"}}
+```
+
+**After Coalescing** (if multiple `message.part.updated` for same part):
+- Only latest event kept in queue
+- Reduces redundant UI updates
+
+---
+
+## 5. Double-Buffer Swap Pattern
+
+### 5.1 Pattern Description
+
+OpenCode doesn't explicitly call it "double-buffer swap" but implements the pattern functionally.
+
+**Traditional Double Buffer**: Two buffers alternate between "write" and "read" roles
+
+**OpenCode's Implementation**:
+```typescript
+let queue = []      // Write buffer (incoming events)
+let buffer = []     // Read buffer (being processed)
+
+function flush() {
+  // Atomic swap
+  const events = queue
+  queue = buffer
+  buffer = events
+  queue.length = 0
+  
+  // Process 'buffer' (previously 'queue')
+  for (const event of buffer) {
+    emitter.emit(event.directory, event.payload)
+  }
+  
+  buffer.length = 0  // Clear for next swap
+}
+```
+
+### 5.2 Benefits
+
+1. **Zero Lock Time**: Reference swap is O(1), instant
+2. **Concurrent Collection**: New events enter `queue` during `buffer` processing
+3. **No Race Conditions**: Clear separation of write/read buffers
+4. **Memory Efficiency**: Reuse same array objects
+
+### 5.3 Comparison to Single Buffer
+
+**Single Buffer Issues**:
+- Must lock during processing → events blocked
+- Or copy array → memory overhead
+
+**Double Buffer**:
+- No locking needed
+- Zero-copy swap (just reference exchange)
+- Continuous event acceptance
+
+---
+
+## 6. Backpressure Handling
+
+### 6.1 Multi-Layer Strategy
+
+OpenCode handles backpressure through several complementary mechanisms:
+
+#### 6.1.1 Event Coalescing
+
+**Purpose**: Reduce event volume at source
+
+**Implementation**:
+```typescript
+// If same key, replace existing event
+if (k) {
+  const i = coalesced.get(k)
+  if (i !== undefined) {
+    queue[i] = { directory, payload }
+    continue  // Don't add new event
+  }
+  coalesced.set(k, queue.length)
+}
+```
+
+**Effect**: 
+- 1000 rapid `message.part.updated` events → 1 final state event
+- Prevents queue explosion
+
+#### 6.1.2 Stream Yielding
+
+**Purpose**: Prevent event loop blocking
+
+**Implementation**:
+```typescript
+const STREAM_YIELD_MS = 8
+
+for await (const event of events.stream) {
+  // ... process event
+  
+  if (Date.now() - yielded < STREAM_YIELD_MS) continue
+  yielded = Date.now()
+  await wait(0)  // Yield to event loop
+}
+```
+
+**Effect**:
+- Every 8ms, return control to browser
+- UI remains responsive during event floods
+- Prevents "script unresponsive" warnings
+
+#### 6.1.3 Timed Batch Flushing
+
+**Purpose**: Rate-limit UI updates
+
+**Implementation**:
+```typescript
+const FLUSH_FRAME_MS = 16  // 60fps
+
+const schedule = () => {
+  if (timer) return
+  const elapsed = Date.now() - last
+  const delay = Math.max(0, FLUSH_FRAME_MS - elapsed)
+  timer = setTimeout(flush, delay)
+}
+```
+
+**Effect**:
+- Max 60 render cycles per second
+- Even with 10,000 events/sec, only 60 UI updates
+- Prevents render thrashing
+
+#### 6.1.4 SolidJS Batch
+
+**Purpose**: Consolidate state updates
+
+**Implementation**:
+```typescript
+batch(() => {
+  for (const event of events) {
+    emitter.emit(event.directory, event.payload)
+  }
+})
+```
+
+**Effect**:
+- All signal updates in batch → 1 render cycle
+- Without `batch()`: N events → N renders
+- With `batch()`: N events → 1 render
+
+#### 6.1.5 Reconnection Throttling
+
+**Purpose**: Prevent connection spam on failure
+
+**Implementation**:
+```typescript
+const RECONNECT_DELAY_MS = 250
+
+catch (error) {
+  if (!streamErrorLogged) {
+    console.error("Event stream error:", error)
+    streamErrorLogged = true
+  }
+  await wait(RECONNECT_DELAY_MS)  // Wait before retry
+}
+```
+
+**Effect**:
+- Gradual reconnection attempts
+- Prevents server overload during issues
+
+### 6.2 Backpressure Flow Diagram
+
+```
+High Event Rate (10k events/sec)
+         │
+         ▼
+┌────────────────────┐
+│  Coalescing        │  → Reduces to ~100 unique events/sec
+│  (key-based)       │
+└────────┬───────────┘
+         │
+         ▼
+┌────────────────────┐
+│  Queue Buffer      │  → Collects events during frame
+│  (16ms frame)      │
+└────────┬───────────┘
+         │
+         ▼
+┌────────────────────┐
+│  Batch Flush       │  → Max 60 flushes/sec
+│  (60fps)           │
+└────────┬───────────┘
+         │
+         ▼
+┌────────────────────┐
+│  SolidJS batch()   │  → 1 render cycle per flush
+│                    │
+└────────┬───────────┘
+         │
+         ▼
+    UI Update (smooth 60fps)
+```
+
+### 6.3 No Explicit Backpressure to Backend
+
+**Observation**: OpenCode doesn't implement flow control signals to backend
+
+**Why It Works**:
+1. **SSE is one-way**: No backpressure protocol in SSE standard
+2. **Coalescing absorbs bursts**: Client handles rate reduction
+3. **Browser buffers**: Network layer provides buffering
+4. **Event types**: Most events are state updates (idempotent)
+
+**Alternative Approaches** (not used by OpenCode):
+- WebSocket with flow control messages
+- Chunked encoding with pause/resume
+- Token bucket rate limiting on server
+
+---
+
+## 7. TUI Similar Pattern
+
+**Location**: `packages/opencode/src/cli/cmd/tui/context/sdk.tsx`
+
+The Terminal UI also implements batching:
+
+```typescript
+const queue = []
+let timer = undefined
+
+const handleEvent = (event) => {
+  queue.push(event)
+  
+  if (timer) return
+  timer = setTimeout(() => {
+    timer = undefined
+    const events = [...queue]
+    queue.length = 0
+    
+    batch(() => {
+      for (const event of events) {
+        emitter.emit(event.payload)
+      }
+    })
+  }, 16)
+}
+```
+
+**Differences from Web UI**:
+- **No coalescing**: Simpler queue-and-flush
+- **Same 16ms interval**: Frame-aligned batching
+- **Same batch() pattern**: SolidJS render optimization
+
+---
+
+## 8. Key Insights & Design Patterns
+
+### 8.1 Type Safety at Every Layer
+
+1. **Event Definition**: Zod schema enforces structure
+2. **Publishing**: TypeScript ensures correct payload type
+3. **Subscription**: Callback receives typed event object
+4. **Runtime Validation**: Zod validates at boundaries
+
+**Benefit**: Catch errors at compile time, not production
+
+### 8.2 Dual Publishing Pattern
+
+```typescript
+// Local subscribers (immediate)
+for (const sub of subscriptions) {
+  pending.push(sub(payload))
+}
+
+// Global bus (for SSE)
+GlobalBus.emit("event", { directory, payload })
+```
+
+**Benefit**: 
+- Local: Fast, synchronous communication within process
+- Global: Cross-boundary (process, network) event distribution
+
+### 8.3 Database-Triggered Events
+
+```typescript
+Database.use((db) => {
+  db.insert(Table).values(data).run()
+  Database.effect(() => Bus.publish(Event, props))
+})
+```
+
+**Pattern**: Events only fire after DB commit succeeds
+
+**Benefit**: 
+- Consistency: UI never shows uncommitted data
+- Reliability: No phantom events from failed transactions
+
+### 8.4 Frame-Aligned Batching
+
+**16ms = 60fps**: Aligning event flushes with display refresh rate
+
+**Why 16ms**:
+- Most displays: 60Hz (16.67ms per frame)
+- Browser render cycle typically synced to vsync
+- Sweet spot: Responsive yet efficient
+
+**Alternative**: `requestAnimationFrame()` for true vsync alignment
+
+### 8.5 Progressive Coalescing
+
+**Not All Events Coalesced**:
+- `session.status`: Yes (state snapshots)
+- `lsp.updated`: Yes (state snapshots)
+- `message.part.updated`: Yes (content updates)
+- `session.created`: No (singular events)
+
+**Strategy**: Coalesce state updates, preserve events
+
+### 8.6 Separation of Concerns
+
+```
+Transport Layer: SSE, HTTP, WebSocket
+    ↕
+Event Layer: Bus, GlobalBus, BusEvent
+    ↕
+Domain Layer: Session, Message, FileWatcher
+    ↕
+Storage Layer: Database, Effects
+```
+
+Each layer focused, testable, replaceable
+
+---
+
+## 9. Comparative Analysis
+
+### 9.1 vs Redux/MobX
+
+**OpenCode Bus**:
+- ✅ Simpler: No global store, no reducers
+- ✅ Type-safe: Zod + TypeScript
+- ✅ Distributed: Works across process boundaries
+- ❌ No time-travel debugging
+- ❌ No middleware ecosystem
+
+### 9.2 vs Event Emitter
+
+**OpenCode Bus**:
+- ✅ Type safety with Zod
+- ✅ Dual local/global publishing
+- ✅ Integrated with DB effects
+- ✅ SSE streaming built-in
+- ❌ More complex setup
+
+### 9.3 vs RxJS
+
+**OpenCode Bus**:
+- ✅ Simpler learning curve
+- ✅ Custom coalescing logic
+- ❌ No operators (map, filter, debounce)
+- ❌ No marble testing
+- ❌ No complex stream composition
+
+---
+
+## 10. Potential Improvements
+
+### 10.1 Adaptive Frame Rate
+
+**Current**: Fixed 16ms flush interval
+
+**Improvement**:
+```typescript
+const IDLE_FRAME_MS = 16
+const BUSY_FRAME_MS = 50
+
+const schedule = () => {
+  const frameMs = queue.length > 100 ? BUSY_FRAME_MS : IDLE_FRAME_MS
+  const delay = Math.max(0, frameMs - (Date.now() - last))
+  timer = setTimeout(flush, delay)
+}
+```
+
+**Benefit**: Reduce CPU during high load, maintain responsiveness when idle
+
+### 10.2 Priority Queues
+
+**Current**: All events treated equally
+
+**Improvement**:
+```typescript
+const highPriority = []  // session.status, errors
+const lowPriority = []   // logs, metrics
+
+const flush = () => {
+  batch(() => {
+    for (const event of highPriority) emitter.emit(...)
+    for (const event of lowPriority) emitter.emit(...)
+  })
+}
+```
+
+**Benefit**: Critical updates always processed first
+
+### 10.3 Configurable Coalescing
+
+**Current**: Hardcoded event types
+
+**Improvement**:
+```typescript
+const coalesceConfig = {
+  "session.status": (e) => `${e.directory}:${e.properties.sessionID}`,
+  "lsp.updated": (e) => e.directory,
+  // User can add custom rules
+}
+```
+
+**Benefit**: Extensible without code changes
+
+### 10.4 Backpressure Signal to Backend
+
+**Current**: Client absorbs all events
+
+**Improvement**: 
+```typescript
+// Send message over WebSocket
+if (queue.length > 1000) {
+  ws.send({ type: "SLOW_DOWN", queueSize: queue.length })
+}
+```
+
+**Benefit**: Server can rate-limit or drop low-priority events
+
+### 10.5 Event Replay Buffer
+
+**Current**: No event history
+
+**Improvement**:
+```typescript
+const replayBuffer = []  // Last 100 events
+const MAX_REPLAY = 100
+
+const flush = () => {
+  replayBuffer.push(...buffer.slice(-MAX_REPLAY))
+  // ... normal flush
+}
+
+// On reconnect:
+const needsReplay = calculateMissedEvents()
+for (const event of needsReplay) {
+  queue.push(event)
+}
+```
+
+**Benefit**: Recover from brief disconnections without full page reload
+
+---
+
+## 11. Implementation Checklist for Similar Systems
+
+### Core Event Bus
+- [ ] Define `BusEvent.define()` with Zod schemas
+- [ ] Implement `Bus.publish()` with local + global emission
+- [ ] Implement `Bus.subscribe()` and `Bus.subscribeAll()`
+- [ ] Use `Map<string, Set<Function>>` for subscription storage
+- [ ] Return unsubscribe function from `subscribe()`
+
+### SSE Streaming
+- [ ] Create `/event` SSE endpoint with framework (Hono, Express, etc.)
+- [ ] Use `Bus.subscribeAll()` to feed SSE stream
+- [ ] Implement heartbeat (30s interval recommended)
+- [ ] Handle client disconnect cleanup
+- [ ] Emit special "dispose" event on shutdown
+
+### Client-Side Coalescing
+- [ ] Set up dual queue/buffer arrays
+- [ ] Define `key()` function for coalescable event types
+- [ ] Implement `coalesced` Map for index tracking
+- [ ] Create `flush()` with queue/buffer swap
+- [ ] Use framework batch (SolidJS `batch()`, React `unstable_batchedUpdates()`, etc.)
+
+### Backpressure Management
+- [ ] Implement 16ms frame-aligned flushing
+- [ ] Add 8ms event loop yielding during processing
+- [ ] Use coalescing for state-update events
+- [ ] Add reconnection delay (250ms recommended)
+- [ ] Log errors with deduplication flag
+
+### Database Integration
+- [ ] Wrap DB operations in transaction
+- [ ] Use effect/hook system to trigger events after commit
+- [ ] Never publish events before DB confirms write
+- [ ] Consider event sourcing for audit trail
+
+### Testing
+- [ ] Unit test event definition schemas
+- [ ] Test subscription/unsubscription logic
+- [ ] Test coalescing with rapid duplicate events
+- [ ] Integration test SSE stream with client
+- [ ] Load test with 10k+ events/sec
+- [ ] Test reconnection after network failure
+- [ ] Test cleanup on component unmount
+
+---
+
+## 12. References & Additional Reading
+
+### DeepWiki Sources
+- [Architecture Overview](https://deepwiki.com/wiki/anomalyco/opencode#2)
+- [MCP (Model Context Protocol)](https://deepwiki.com/wiki/anomalyco/opencode#13)
+- [UI Component Library](https://deepwiki.com/wiki/anomalyco/opencode#15)
+
+### Key Files
+- `packages/opencode/src/bus/index.ts` - Core Bus implementation
+- `packages/app/src/context/global-sdk.tsx` - Client coalescing
+- `packages/opencode/src/session/processor.ts` - SessionProcessor
+- `packages/opencode/src/server/routes/global.ts` - SSE endpoint
+- `packages/opencode/src/cli/cmd/tui/context/sdk.tsx` - TUI events
+
+### Related Technologies
+- **Zod**: Schema validation - https://zod.dev
+- **SolidJS**: Reactive UI library - https://solidjs.com
+- **Hono**: Web framework - https://hono.dev
+- **AI SDK**: LLM streaming - https://sdk.vercel.ai
+
+### Similar Patterns in Other Systems
+- **Redux Toolkit**: RTK Query with SSE
+- **tRPC**: Subscription pattern
+- **Phoenix LiveView**: Server-pushed updates
+- **Hotwire Turbo Streams**: Action cable events
+
+---
+
+## Conclusion
+
+OpenCode's event-bus architecture demonstrates a mature, production-grade approach to real-time event streaming. Key strengths:
+
+1. **Type Safety**: Zod + TypeScript eliminate entire classes of bugs
+2. **Performance**: Coalescing + batching handle 10k+ events/sec gracefully
+3. **Simplicity**: Clean abstractions make complex flows comprehensible
+4. **Reliability**: Database-triggered events ensure consistency
+
+The architecture is particularly well-suited for:
+- Real-time collaborative applications
+- Streaming LLM responses
+- File system watchers
+- Multi-process coordination
+
+OpenCode's patterns are directly applicable to any system requiring high-throughput, low-latency event distribution with strong type guarantees.
diff --git a/research/docs/2026-02-26-streaming-architecture-event-bus-migration.md b/research/docs/2026-02-26-streaming-architecture-event-bus-migration.md
new file mode 100644
index 0000000000..f523b84653
--- /dev/null
+++ b/research/docs/2026-02-26-streaming-architecture-event-bus-migration.md
@@ -0,0 +1,584 @@
+---
+date: 2026-02-26 04:46:59 UTC
+researcher: Copilot
+git_commit: c399d54c08b67b640e7a64bbbc181f9d329ab187
+branch: lavaman131/feature/workflow-sdk
+repository: workflow-sdk
+topic: "Streaming Architecture Migration: Callbacks to Event-Bus Pattern"
+tags: [research, streaming, sse, event-bus, callbacks, opencode, claude-agent-sdk, copilot-sdk, tui, architecture]
+status: complete
+last_updated: 2026-02-26
+last_updated_by: Copilot
+---
+
+# Research: Streaming Architecture Migration — Callbacks to Event-Bus Pattern
+
+## Research Question
+
+Rethink the way that LM responses and messages are streamed across the entire TUI (which uses Claude Agent SDK, OpenCode SDK, and Copilot SDK as backends). The current callback-based approach should be migrated to a more robust event-bus streaming model inspired by OpenCode's SSE + event-bus + batched coalescing pattern. The workflow-sdk (manually orchestrated workflows) should share the same streaming backbone as the main chat, enabling unified rendering of sub-agents, tool calls, and workflow output.
+
+## Summary
+
+The Atomic TUI currently uses a **multi-layered callback architecture** where streaming data flows from SDK clients through function callbacks (`onChunk`, `onComplete`, `onMeta`) to the UI layer, with event handlers registered via React prop drilling and ref-based handler storage. This creates tight coupling between the orchestration layer (`src/ui/index.ts`) and the chat component (`src/ui/chat.tsx`), with dual-path event delivery (stream-path vs hook-path) and complex correlation mapping.
+
+OpenCode, by contrast, implements a **server-side Bus → SSE → client-side event-bus with batching/coalescing** architecture. Events flow through a typed publish-subscribe system, are serialized as SSE to clients, and are consumed via an event emitter with frame-aligned batching (16ms) and key-based coalescing. Components subscribe to events declaratively without receiving callbacks as props.
+
+All three SDK backends expose different streaming primitives:
+- **OpenCode SDK**: SSE + AsyncGenerator via `sdk.event.subscribe()`
+- **Claude Agent SDK**: AsyncIterable via `session.stream()`
+- **Copilot SDK**: Event Emitter via `session.on(eventType, handler)`
+
+The key architectural shift would be from **callback prop-threading** to a **centralized event bus** that normalizes all three SDK streaming patterns into a unified event stream, with batched dispatch to prevent render churn.
+
+---
+
+## Detailed Findings
+
+### 1. Current Streaming Architecture (Callback-Based)
+
+#### 1.1 SDK Layer — AsyncIterable Streaming
+
+Each SDK client implements `Session.stream()` which returns `AsyncIterable<AgentMessage>`:
+
+```typescript
+// src/sdk/types.ts:250-251
+stream(message: string, options?: { agent?: string }): AsyncIterable<AgentMessage>
+```
+
+`AgentMessage` carries:
+- `type`: `"text"` | `"tool_use"` | `"tool_result"` | `"thinking"`
+- `content`: string or structured data
+- `role`: `"user"` | `"assistant"` | `"system"` | `"tool"`
+- `metadata`: token usage, model info, tool details
+
+**Event Emitter in Base Client** (`src/sdk/base-client.ts:32-104`):
+- `on<T>(eventType, handler)` → returns unsubscribe function
+- `emit<T>(eventType, sessionId, data)` → synchronous dispatch with try-catch
+- Handlers stored in `Map<EventType, Set<EventHandler>>`
+
+SDK Event Types (`src/sdk/types.ts:297-310`):
+```
+message.delta, message.complete, tool.start, tool.complete,
+session.start, session.idle, session.error, skill.invoked,
+subagent.start, subagent.complete, permission.requested,
+human_input_required, usage
+```
+
+#### 1.2 Orchestration Layer — handleStreamMessage
+
+`src/ui/index.ts:1513-1913` is the central streaming coordinator:
+
+**Callback Signatures**:
+- `onChunk: (chunk: string) => void` — text delta delivery
+- `onComplete: () => void` — stream finalization
+- `onMeta?: (meta: StreamingMeta) => void` — metadata updates (thinking, tokens)
+
+**Stream Processing Loop** (lines 1571-1879):
+```typescript
+const stream = state.session!.stream(content, options);
+const abortableStream = abortableAsyncIterable(stream, state.streamAbortController.signal);
+
+for await (const message of abortableStream) {
+  if (message.type === "text") {
+    // Echo suppression, thinking duration, then:
+    onChunk(chunkToEmit);
+  }
+  else if (message.type === "thinking") {
+    // Track thinking sources, accumulate text
+    onMeta?.(createStreamingMetaSnapshot(thinkingSourceKey));
+  }
+  else if (message.type === "tool_use") {
+    state.toolStartHandler(toolId, toolName, input);
+  }
+  else if (message.type === "tool_result") {
+    state.toolCompleteHandler(toolId, output, success, error);
+  }
+}
+```
+
+**Dual-Path Event Delivery**:
+- **Stream-path**: Events in the AsyncIterable (tool_use, tool_result messages)
+- **Hook-path**: Events via SDK's `client.on()` system (`subscribeToToolEvents` at lines 477-1293)
+- Flag `toolEventsViaHooks = true` prevents duplicate processing
+- OpenCode primarily uses hook-path; Claude/Copilot use stream-path
+
+#### 1.3 UI Layer — React Callback Registration
+
+`src/ui/chat.tsx` receives streaming callbacks and applies events to message parts:
+
+**Callback Registration** (via React props + useEffect, lines 2490-2506):
+```typescript
+// Handler registration functions provided as props:
+registerToolStartHandler?: (handler: OnToolStart) => void
+registerToolCompleteHandler?: (handler: OnToolComplete) => void
+registerSkillInvokedHandler?: (handler: OnSkillInvoked) => void
+```
+
+**Handler Storage** in `ChatUIState` (index.ts:167-176):
+```typescript
+interface ChatUIState {
+  toolStartHandler: OnToolStart | null;
+  toolCompleteHandler: OnToolComplete | null;
+  skillInvokedHandler: OnSkillInvoked | null;
+  permissionRequestHandler: OnPermissionRequest | null;
+  askUserQuestionHandler: OnAskUserQuestion | null;
+}
+```
+
+**Text Delta Handling** (`chat.tsx:3551-3576`):
+```typescript
+const handleChunk = (chunk: string) => {
+  if (!isCurrentStreamCallback(streamGenerationRef.current, currentGeneration)) return;
+  lastStreamingContentRef.current += chunk;
+  if (hideStreamContentRef.current) return;
+  setMessagesWindowed((prev) =>
+    prev.map((msg) => {
+      if (msg.id === messageId) {
+        return applyStreamPartEvent(msg, { type: "text-delta", delta: chunk });
+      }
+      return msg;
+    })
+  );
+};
+```
+
+**React State Update Pattern** (used in handleChunk, handleMeta, handleToolStart, handleToolComplete):
+```typescript
+setMessagesWindowed((prev: ChatMessage[]) =>
+  prev.map((msg: ChatMessage) => {
+    if (msg.id === messageId) {
+      return applyStreamPartEvent(msg, event);
+    }
+    return msg;
+  })
+);
+```
+
+Each text delta, tool event, and thinking update triggers a full `setMessagesWindowed` call that maps over all messages.
+
+#### 1.4 Parts Pipeline — Event Reducer
+
+`src/ui/parts/stream-pipeline.ts:786-853` — `applyStreamPartEvent()` is a discriminated union reducer:
+
+**StreamPartEvent types**:
+```
+text-delta, thinking-meta, tool-start, tool-complete,
+tool-hitl-request, tool-hitl-response, parallel-agents
+```
+
+**Part types** (`src/ui/parts/types.ts`):
+```
+TextPart, ReasoningPart, ToolPart, AgentPart,
+TaskListPart, SkillLoadPart, McpSnapshotPart, CompactionPart
+```
+
+**Part storage** (`src/ui/parts/store.ts`): Binary search-based insertion/update with timestamp-encoded PartIds for chronological ordering.
+
+**Throttling** (`src/ui/hooks/use-throttled-value.ts`): 100ms throttle on UI updates.
+
+#### 1.5 Hook-Path Event Subscription
+
+`src/ui/index.ts:477-1450` — `subscribeToToolEvents()`:
+
+Subscribes to SDK events: `tool.start`, `tool.complete`, `skill.invoked`, `permission.requested`, `human_input_required`, `subagent.start`, `subagent.complete`
+
+**Correlation Infrastructure**:
+- `sdkToolIdMap`: SDK tool use ID → internal tool ID
+- `toolCallToAgentMap`: SDK correlation ID → agent ID
+- `subagentSessionToAgentId`: session ID → agent ID
+- `pendingTaskEntries`: FIFO queue for Task tool → subagent.start matching
+- Run ownership via monotonic `state.runCounter` to reject stale events
+
+#### 1.6 Workflow Streaming
+
+`src/workflows/executor.ts:122-283` — `executeWorkflow()`:
+- Iterates `streamGraph()` AsyncGenerator
+- Yields `StepResult<TState>` containing `{ nodeId, state, result, status }`
+- Progress messages via `context.addMessage()`
+- Task list sync via `context.setTodoItems(state.tasks)`
+
+Sub-agent spawning (`src/ui/chat.tsx:3796-3960` — `spawnSubagentParallel()`):
+- Creates isolated sessions via `createSubagentSession()`
+- Streams via `session.stream(options.task)`
+- Uses `Promise.allSettled()` for concurrent execution
+- Returns `SubagentResult[]`
+
+Workflow streaming uses the same callback infrastructure as main chat, flowing through `handleStreamMessage()`.
+
+---
+
+### 2. OpenCode's SSE + Event-Bus Architecture
+
+#### 2.1 Server-Side: Bus → SSE
+
+**Bus System** (`packages/opencode/src/bus/index.ts`):
+- Events defined with `BusEvent.define(name, zodSchema)` for type-safe pub/sub
+- `Bus.publish(Event, properties)` → validates with Zod → dispatches to all subscribers
+- `Bus.subscribeAll(callback)` → receives all published events
+- `Bus.subscribe(eventType, callback)` → specific event subscription
+- `Bus.once(eventType, callback)` → one-time subscription
+
+**SSE Endpoint** (`packages/opencode/src/server/server.ts:511-528`):
+```typescript
+const unsub = Bus.subscribeAll(async (event) => {
+  await stream.writeSSE({ data: JSON.stringify(event) });
+  if (event.type === Bus.InstanceDisposed.type) { stream.close(); }
+});
+// 30s heartbeat to prevent WKWebView timeout
+const heartbeat = setInterval(() => {
+  stream.writeSSE({ data: JSON.stringify({ type: "server.heartbeat", properties: {} }) });
+}, 30000);
+```
+
+**Global Events Endpoint** (`packages/opencode/src/server/routes/global.ts:79-95`):
+- Same pattern but via `GlobalBus.on("event", handler)`
+- Wraps events in `{ payload: event }` envelope
+- Supports multi-directory event distribution
+
+**Key Event Types**:
+```
+session.status, session.updated, session.created, session.deleted,
+message.updated, message.part.updated, message.part.delta,
+lsp.updated, lsp.client.diagnostics, mcp.tools.changed,
+server.heartbeat, server.connected, server.instance.disposed
+```
+
+#### 2.2 Client-Side: Event Bus with Batching
+
+**Web App** (`packages/app/src/context/global-sdk.tsx:46-84`):
+
+```typescript
+const FLUSH_FRAME_MS = 16;  // ~60 FPS alignment
+const STREAM_YIELD_MS = 8;  // Yield to event loop
+
+let queue: Queued[] = [];
+let buffer: Queued[] = [];
+const coalesced = new Map<string, number>();
+```
+
+**Coalescing Key Function**:
+```typescript
+const key = (directory: string, payload: Event) => {
+  if (payload.type === "session.status") return `session.status:${directory}:${payload.properties.sessionID}`;
+  if (payload.type === "lsp.updated") return `lsp.updated:${directory}`;
+  if (payload.type === "message.part.updated") {
+    const part = payload.properties.part;
+    return `message.part.updated:${directory}:${part.messageID}:${part.id}`;
+  }
+};
+```
+
+Events with the same key within a batching window overwrite each other — only the most recent state is preserved.
+
+**Flush Function**:
+```typescript
+const flush = () => {
+  const events = queue;
+  queue = buffer;    // Swap buffers efficiently
+  buffer = events;
+  queue.length = 0;
+  coalesced.clear();
+  last = Date.now();
+  batch(() => {      // SolidJS batch: single render for all updates
+    for (const event of events) {
+      emitter.emit(event.directory, event.payload);
+    }
+  });
+};
+```
+
+**TUI Batching** (`packages/opencode/src/cli/cmd/tui/context/sdk.tsx:36-62`):
+- Simpler 16ms threshold batching without coalescing
+- Immediate flush if >16ms since last flush, else schedule
+- Uses SolidJS `batch()` for grouped reactive updates
+
+#### 2.3 Event Bus Architecture
+
+**Two-Tier Emitter System**:
+1. **Global Emitter** (web app) — Single SSE connection, distributes by directory
+2. **Directory Emitter** (per-project) — Filters from global emitter, provides scoped subscription
+
+```
+Component calls sdk.event.listen((event) => {
+  if (event.type === "message.part.delta") {
+    updateMessagePartInStore(event.properties);
+  }
+});
+```
+
+**Reconnection**:
+```typescript
+while (true) {
+  try {
+    for await (const chunk of eventSdk.global.event()) { handleEvent(chunk); }
+  } catch (error) {
+    await wait(RECONNECT_DELAY_MS);  // 250ms
+  }
+}
+```
+
+#### 2.4 LLM Provider Streaming
+
+**TransformStream** (`packages/opencode/src/provider/sdk/copilot/chat/openai-compatible-chat-language-model.ts:367-386`):
+- Parses raw SSE chunks from AI providers into `LanguageModelV2StreamPart` types
+- Handles: `stream-start`, `reasoning-start/delta/end`, `text-start/delta/end`, `tool-input-start/delta/end`, `tool-call`, `finish`
+- Tracks active reasoning, text, and tool call state transitions
+
+**SessionProcessor** (`packages/opencode/src/session/processor.ts`):
+- Consumes `stream.fullStream` and creates/updates `MessageV2` parts
+- Calls `Session.updatePart()` and `Session.updatePartDelta()` which publish Bus events
+- Bus events flow through SSE to clients automatically
+
+**End-to-End Flow**:
+```
+LLM SSE chunks → TransformStream → LanguageModelV2StreamPart
+→ SessionProcessor → Bus.publish(PartUpdated/PartDelta)
+→ GlobalBus → SSE endpoint → Client SSE reader
+→ Event queue (with coalescing) → batch(flush)
+→ Emitter → Component subscribers → Single render
+```
+
+---
+
+### 3. SDK Streaming API Comparison
+
+| Aspect | OpenCode SDK | Claude Agent SDK | Copilot SDK |
+|--------|-------------|-----------------|-------------|
+| **Primary Method** | `sdk.event.subscribe()` | `session.stream()` | `session.on(eventType, handler)` |
+| **Return Type** | `{ stream: AsyncGenerator<Event> }` | `AsyncIterable` | Unsubscribe function |
+| **Pattern** | Pull-based (iterator) | Pull-based (iterator) | Push-based (observer) |
+| **Event Count** | 42+ event types | ~6 documented | 43 event types |
+| **Type Safety** | Zod schemas | TypeScript types | Discriminated unions |
+| **Backpressure** | Consumer-controlled | Holds until subagents complete | None (synchronous dispatch) |
+| **Multi-language** | JavaScript/TypeScript | TypeScript | TS, Python, Go, C# |
+
+**OpenCode SDK Events** (key subset):
+- `message.part.updated` — Full part state replacement
+- `message.part.delta` — Incremental text delta
+- `session.status` — Session lifecycle
+- `message.updated` — Full message updates
+
+**Claude Agent SDK Events**:
+- `task_started` — Subagent task registration
+- `task_notification` — Task completion with `tool_use_id` correlation
+- `SDKResultSuccess` / `SDKResultError` — Result messages
+
+**Copilot SDK Events** (key subset):
+- `assistant.message_delta` — Streaming text chunk (ephemeral)
+- `assistant.turn_start/end` — Turn boundaries
+- `tool.execution_start/progress/complete` — Tool lifecycle
+- `subagent.started/completed/failed` — Sub-agent lifecycle
+- `session.start/idle/error/shutdown` — Session lifecycle
+
+---
+
+### 4. Architectural Comparison
+
+#### 4.1 Current Atomic Architecture (Callbacks)
+
+```
+SDK Client.stream() → AsyncIterable<AgentMessage>
+      ↓
+index.ts: for await (msg of stream)
+      ↓ (callbacks)
+  onChunk(text)  →  chat.tsx: setMessagesWindowed(applyStreamPartEvent)
+  onMeta(meta)   →  chat.tsx: setMessagesWindowed(applyStreamPartEvent)
+  onComplete()   →  chat.tsx: finalize streaming state
+      ↓
+SDK Client.on("tool.start") → state.toolStartHandler → chat.tsx: handleToolStart
+SDK Client.on("tool.complete") → state.toolCompleteHandler → chat.tsx: handleToolComplete
+SDK Client.on("subagent.start") → state.parallelAgentHandler → chat.tsx: updateAgentTree
+```
+
+**Characteristics**:
+- Callbacks threaded through props and refs
+- Dual-path event delivery (stream vs hooks)
+- Each callback triggers `setMessagesWindowed()` which maps over all messages
+- Complex correlation maps for tool/agent attribution
+- Generation-based staleness guards
+- 100ms throttling via `use-throttled-value.ts`
+- Echo suppression for post-task duplicate text
+
+#### 4.2 OpenCode Architecture (Event Bus)
+
+```
+LLM Provider → TransformStream → SessionProcessor
+      ↓
+Bus.publish(PartUpdated/PartDelta)
+      ↓
+GlobalBus → SSE endpoint → HTTP SSE stream
+      ↓
+Client SSE reader → Queue (with key-based coalescing)
+      ↓ (16ms batched flush)
+batch(() => emitter.emit(directory, event))
+      ↓
+Component subscribers → SolidJS reactive updates → Single render
+```
+
+**Characteristics**:
+- No callback prop-threading
+- Single event pathway (Bus → SSE → emitter)
+- Key-based coalescing eliminates redundant updates
+- Frame-aligned batching (16ms) reduces render churn
+- Components subscribe declaratively
+- Reconnection handled at SDK level
+- Heartbeat keeps connections alive
+
+---
+
+## Code References
+
+### Current Callback Architecture
+- `src/sdk/types.ts:250-251` — `Session.stream()` AsyncIterable interface
+- `src/sdk/types.ts:297-310` — `EventType` discriminated union
+- `src/sdk/types.ts:349-400` — Event data types (MessageDelta, ToolStart, ToolComplete)
+- `src/sdk/base-client.ts:32-104` — `EventEmitter` class
+- `src/ui/index.ts:167-176` — `ChatUIState` handler refs
+- `src/ui/index.ts:477-1450` — `subscribeToToolEvents()` hook-path event handling
+- `src/ui/index.ts:1513-1913` — `handleStreamMessage()` stream-path processing
+- `src/ui/chat.tsx:3551-3576` — `handleChunk()` text delta callback
+- `src/ui/chat.tsx:3578-3717` — `handleComplete()` stream finalization
+- `src/ui/chat.tsx:3720-3748` — `handleMeta()` thinking metadata callback
+- `src/ui/chat.tsx:2266-2354` — `handleToolStart()` tool event callback
+- `src/ui/chat.tsx:2361-2476` — `handleToolComplete()` tool event callback
+- `src/ui/chat.tsx:2490-2506` — Handler registration via useEffect
+- `src/ui/chat.tsx:3796-3960` — `spawnSubagentParallel()` sub-agent spawning
+
+### Parts Pipeline
+- `src/ui/parts/stream-pipeline.ts:786-853` — `applyStreamPartEvent()` reducer
+- `src/ui/parts/stream-pipeline.ts:91-98` — `StreamPartEvent` union type
+- `src/ui/parts/types.ts:49-127` — Part type definitions
+- `src/ui/parts/store.ts:20-53` — Binary search part storage
+- `src/ui/parts/handlers.ts:21-52` — `handleTextDelta()` text part splitting
+- `src/ui/parts/id.ts` — Timestamp-encoded PartId generation
+- `src/ui/parts/guards.ts` — Stream finalization guards
+
+### Hooks
+- `src/ui/hooks/use-streaming-state.ts:55-94` — Streaming state management
+- `src/ui/hooks/use-message-queue.ts` — Message queue during streaming
+- `src/ui/hooks/use-throttled-value.ts` — 100ms update throttling
+
+### Workflow Streaming
+- `src/workflows/executor.ts:122-283` — `executeWorkflow()` lifecycle
+- `src/workflows/graph/compiled.ts:324-569` — `GraphExecutor.streamSteps()`
+- `src/workflows/graph/compiled.ts:888` — `streamGraph()` AsyncGenerator
+- `src/workflows/graph/stream.ts:7-123` — `StreamMode`, `StreamEvent`, `StreamRouter`
+- `src/workflows/graph/nodes.ts:193` — Agent nodes calling `session.stream()`
+- `src/workflows/graph/types.ts:289` — `ExecutionContext.emit()` custom events
+
+### UI Components
+- `src/ui/components/parallel-agents-tree.tsx:206-360` — Agent deduplication logic
+- `src/ui/components/parallel-agents-tree.tsx:589-734` — Tree rendering
+- `src/ui/components/task-list-panel.tsx:72-179` — Workflow task list rendering
+- `src/ui/components/transcript-view.tsx` — Main transcript with streaming
+
+### SDK Clients
+- `src/sdk/clients/opencode.ts` — OpenCode SDK integration
+- `src/sdk/clients/claude.ts` — Claude Agent SDK integration
+- `src/sdk/clients/copilot.ts` — Copilot SDK integration
+- `src/sdk/clients/opencode.events.test.ts` — OpenCode event handling tests
+- `src/sdk/unified-event-parity.test.ts` — Cross-SDK event consistency tests
+
+---
+
+## Architecture Documentation
+
+### Current Patterns
+
+1. **Dual-Path Event Delivery**: Events arrive via both the AsyncIterable stream (stream-path) and SDK's native event system (hook-path). A flag `toolEventsViaHooks` prevents duplicate processing. OpenCode primarily uses hook-path; Claude/Copilot use stream-path.
+
+2. **Ref-Based Handler Storage**: Streaming callbacks are stored as refs in `ChatUIState` and called by the orchestration layer. This avoids re-registration on every render but creates implicit coupling.
+
+3. **Generation-Based Staleness Guards**: A monotonic `streamGenerationRef` counter invalidates callbacks from previous streams when new messages are sent rapidly.
+
+4. **Run Ownership Tracking**: Monotonic `runCounter` at `src/ui/index.ts:206` assigns ownership IDs, preventing stale hook events from previous streams.
+
+5. **FIFO Correlation Queuing**: `pendingTaskEntries` queue at `src/ui/index.ts:490` correlates Task tool calls with subagent.start events when SDK correlation IDs are unavailable.
+
+6. **Echo Suppression**: Post-task duplicate text from SDKs is suppressed via `suppressPostTaskResults` FIFO at `src/ui/index.ts:1594`.
+
+7. **Binary Search Part Ordering**: Parts are maintained in chronological order via timestamp-encoded PartIds with O(log n) binary search insertion.
+
+8. **React State Immutable Updates**: Every streaming event triggers `setMessagesWindowed((prev) => prev.map(...))`, creating new message objects for changed messages.
+
+### OpenCode Patterns
+
+1. **Typed Event Bus**: Events defined with Zod schemas provide compile-time and runtime type safety.
+
+2. **Key-Based Coalescing**: Events with the same composite key within a batching window overwrite each other, preserving only the latest state.
+
+3. **Frame-Aligned Batching**: 16ms flush intervals align with ~60 FPS rendering cadence.
+
+4. **Buffer Swapping**: Double-buffer technique (`queue`/`buffer` swap) avoids array allocation during flush.
+
+5. **Stream Yielding**: 8ms yield intervals prevent blocking the main thread during high-volume events.
+
+6. **Part-Based Message Model**: Messages are composed of typed parts (TextPart, ToolPart, ReasoningPart) with unique IDs for granular updates.
+
+7. **SSE + Reconnection**: Automatic reconnection with 250ms delay and exponential backoff at the SDK level.
+
+---
+
+## Historical Context (from research/)
+
+### Directly Related Research
+- `research/docs/2026-02-23-258-background-agents-sdk-event-pipeline.md` — Documents the multi-stage pipeline from SDK events → UI integration state → ChatApp parallelAgents → synthetic parallel-agents stream events → message parts → ParallelAgentsTree rendering
+- `research/docs/2026-02-16-opencode-tui-chat-architecture.md` — OpenCode's reactive event-driven architecture with backend streaming message parts via SSE
+- `research/docs/2026-02-16-atomic-chat-architecture-current.md` — Current content segment model, MessageBubble rendering, streaming pipeline
+- `research/docs/2026-02-16-chat-system-design-reference.md` — Production-grade chat system design with part-based model
+- `research/docs/2026-02-16-opencode-message-rendering-patterns.md` — OpenCode's message part structure and dynamic rendering
+- `research/docs/2026-02-15-subagent-event-flow-diagram.md` — Timeline diagrams showing sync/async task flows and race conditions
+- `research/docs/2026-02-12-sdk-ui-standardization-research.md` — Unified CodingAgentClient interface and event normalization
+- `research/docs/2026-02-12-tui-layout-streaming-content-ordering.md` — Content-offset-based segmentation for interleaving text/tool outputs
+- `research/docs/2026-02-15-ui-inline-streaming-vs-pinned-elements.md` — Inline chronological segments vs pinned panels rendering paths
+
+### SDK Integration Research
+- `research/docs/2026-02-19-sdk-v2-first-unified-layer-research.md` — Unified provider abstraction with normalized event model
+- `research/docs/2026-02-23-sdk-subagent-api-research.md` — How all three SDKs handle sub-agent tool calls and event streaming
+- `research/docs/2026-02-12-sub-agent-sdk-integration-analysis.md` — Disconnect between Atomic's SubagentSessionManager and native SDK sub-agent APIs
+- `research/docs/2026-01-31-opencode-sdk-research.md` — OpenCode SDK architecture, event system, plugin development
+- `research/docs/2026-01-31-claude-agent-sdk-research.md` — Claude Agent SDK v2, event handling & hooks
+- `research/docs/2026-01-31-github-copilot-sdk-research.md` — GitHub Copilot SDK research
+
+### Workflow SDK Research
+- `research/docs/2026-02-25-workflow-sdk-standardization.md` — Graph engine, sub-agents as building blocks, typed state management
+- `research/docs/2026-02-25-unified-workflow-execution-research.md` — Unified workflow execution interface
+- `research/docs/2026-02-25-workflow-sdk-design.md` — WorkflowSDK class design with provider clients and subagent infrastructure
+- `research/docs/2026-02-11-workflow-sdk-implementation.md` — Graph execution engine, fluent builder API
+- `research/docs/2026-02-25-graph-execution-engine-technical-documentation.md` — Graph execution engine technical documentation
+
+### Sub-Agent Lifecycle Research
+- `research/docs/2026-02-15-sub-agent-tree-status-lifecycle-sdk-parity.md` — Status-to-color mapping, SDK parity across normalized events
+- `research/docs/2026-02-16-sub-agent-tree-inline-state-lifecycle-research.md` — Tree inline rendering, lifecycle state signaling
+- `research/docs/2026-02-14-subagent-output-propagation-issue.md` — Bridge layer data truncation, SDK registration gaps
+- `research/docs/2026-02-23-thinking-tag-stream-grouping.md` — Thinking text concatenation across streams
+
+---
+
+## Related Research
+
+- `research/docs/2026-02-16-opentui-rendering-architecture.md` — OpenTUI rendering architecture
+- `research/docs/2026-02-14-opencode-opentui-sdk-research.md` — OpenCode + OpenTUI SDK research
+- `research/docs/2026-02-16-opencode-deepwiki-research.md` — OpenCode DeepWiki research
+- `research/docs/2026-02-04-agent-subcommand-parity-audit.md` — Agent subcommand parity audit
+- `research/docs/2026-02-25-ui-workflow-coupling.md` — UI to workflow coupling analysis
+
+---
+
+## Open Questions
+
+1. **SSE Server Requirement**: OpenCode runs a local server that exposes SSE endpoints. Atomic is a pure TUI application without a server. Should an in-process event bus (e.g., `mitt` or custom typed emitter) replace the SSE transport layer, or should a lightweight local server be introduced?
+
+2. **Coalescing Granularity**: OpenCode coalesces `message.part.updated` events by `{messageID}:{partID}`. Atomic's current system applies every delta immediately. What coalescing keys make sense for the three SDK backends?
+
+3. **Batch Rendering in React vs SolidJS**: OpenCode uses SolidJS `batch()` which groups reactive updates. React's `unstable_batchedUpdates` or React 18's automatic batching provides similar semantics — how should the flush cycle integrate with React's rendering?
+
+4. **Workflow Streaming Unification**: Workflow execution currently uses `context.addMessage()` and `context.setTodoItems()` to update the UI. Should workflows emit events onto the same event bus as main chat, or maintain a separate event channel?
+
+5. **SDK Normalization Layer**: All three SDKs have different streaming APIs (AsyncGenerator, AsyncIterable, EventEmitter). Where exactly in the pipeline should normalization happen — at the SDK client level, or in the event bus subscription layer?
+
+6. **Backpressure**: Copilot SDK has no backpressure (synchronous dispatch). OpenCode's pull-based iterator provides natural backpressure. How should the event bus handle slow consumers when normalizing across all three?
+
+7. **Sub-Agent Session Ownership**: The current `state.ownedSessionIds` Set tracks which sub-agent sessions belong to the current run. In an event-bus model, how would multi-session event routing work without the correlation maps?
+
+8. **TransformStream Integration**: Should Atomic adopt OpenCode's TransformStream-based provider parsing, or continue to rely on each SDK's native message format?
diff --git a/research/docs/2026-02-26-streaming-event-bus-spec-audit.md b/research/docs/2026-02-26-streaming-event-bus-spec-audit.md
new file mode 100644
index 0000000000..caa5ac0ccd
--- /dev/null
+++ b/research/docs/2026-02-26-streaming-event-bus-spec-audit.md
@@ -0,0 +1,398 @@
+---
+date: 2026-02-26 16:12:17 UTC
+researcher: Copilot
+git_commit: 5592d690d176d3dc67a89fbeec1528567b4e5098
+branch: lavaman131/feature/workflow-sdk
+repository: workflow-sdk
+topic: "Streaming Architecture Event Bus Migration - Spec Compliance Audit"
+tags: [research, codebase, event-bus, streaming, spec-audit, migration, adapters, consumers, hooks]
+status: complete
+last_updated: 2026-02-26
+last_updated_by: Copilot
+---
+
+# Streaming Event Bus Spec Compliance Audit
+
+## Research Question
+
+Review the correctness of the current `src/events/` implementation against the spec `specs/streaming-architecture-event-bus-migration.md`, identify missing logic and errors, and reference OpenCode's event-bus patterns for design validation.
+
+## Summary
+
+The implementation covers the core event bus infrastructure faithfully—bus-events types (Section 5.1.1), AtomicEventBus (5.1.2), coalescing (5.1.3), and BatchDispatcher (5.1.4) all match the spec closely. The SDK adapters (5.2) correctly implement streaming-to-event translation for OpenCode, Claude, Copilot, and Workflow scenarios. Consumer services (5.3–5.5) implement the spec's intent but with API simplifications. React hooks (5.7) and the provider component match the spec's lifecycle pattern. Two confirmed **bugs** exist in adapter dispose() methods, and the CorrelationService has a significantly **simplified API** compared to the spec's detailed contract.
+
+---
+
+## Spec Compliance Matrix
+
+### ✅ Fully Matches Spec
+
+| Component | Spec Section | Status | Notes |
+|-----------|-------------|--------|-------|
+| BusEventType union (19 types) | 5.1.1 | ✅ Match | All 19 types present |
+| BusEvent interface | 5.1.1 | ✅ Match | type, sessionId, runId, timestamp, data |
+| BusEventDataMap payloads | 5.1.1 | ✅ Match | All payload shapes match spec |
+| EnrichedBusEvent interface | 5.1.1 | ✅ Match | resolvedToolId, resolvedAgentId, isSubagentTool, suppressFromMainChat |
+| Zod schemas (19 schemas) | 5.1.1 | ✅ Match | defineBusEvent() with schema validation |
+| defineBusEvent() factory | 5.1.1 | ✅ Match | Mirrors OpenCode's BusEvent.define() pattern |
+| AtomicEventBus.on() | 5.1.2 | ✅ Match | Type-safe subscription, returns unsubscribe |
+| AtomicEventBus.onAll() | 5.1.2 | ✅ Match | Wildcard subscription |
+| AtomicEventBus.publish() | 5.1.2 | ✅ Match | Zod validation + error isolation per handler |
+| AtomicEventBus.clear() | 5.1.2 | ✅ Match | Clears all handlers |
+| coalescingKey() | 5.1.3 | ✅ Match | text/thinking → null (never coalesce), state events → entity key |
+| BatchDispatcher double-buffer | 5.1.4 | ✅ Match | Swap pattern avoids allocation on flush |
+| BatchDispatcher 16ms flush | 5.1.4 | ✅ Match | ~60fps frame alignment |
+| BatchDispatcher coalescing map | 5.1.4 | ✅ Match | Key-based deduplication for state events |
+| EchoSuppressor | 5.4 | ✅ Match | FIFO queue, accumulator, filterDelta, reset |
+| EventBusProvider | 5.7 | ✅ Match | React context with useMemo singleton |
+| useEventBus() hook | 5.7 | ✅ Match | Context accessor shorthand |
+| useBusSubscription() hook | 5.7 | ✅ Match | Type-safe sub with ref + auto-cleanup |
+| useBusWildcard() hook | 5.7 | ✅ Match | Wildcard sub with ref + auto-cleanup |
+| attachDebugSubscriber() | 7.2 | ✅ Match | Conditional on ATOMIC_DEBUG=1, console.debug |
+
+### ⚠️ Deviates from Spec (Intentional Simplifications)
+
+| Component | Spec Section | Deviation | Impact |
+|-----------|-------------|-----------|--------|
+| CorrelationService API | 5.3 | Uses `enrich(event)` + `registerTool()` instead of spec's `processBatch()` / `startRun()` / `isOwnedEvent()` | Missing run ownership tracking; simplified but functional |
+| CorrelationService state | 5.3 | Has `toolToAgent`, `subAgentTools`, `mainAgentId` instead of spec's `sdkToolIdMap`, `toolCallToAgentMap`, `subagentSessionToAgentId`, `pendingTaskEntries`, `ownedSessionIds`, `toolIdToRunMap`, `activeRunId` | Reduced capability for multi-agent correlation |
+| StreamPipelineConsumer | 5.5 | Uses `onStreamParts(callback)` pattern instead of spec's direct `setMessages` React dispatch | Architectural difference; callback is more flexible |
+| useStreamConsumer() return | 5.7 | Returns `{ resetConsumers }` instead of spec's `{ startStreaming, stopStreaming, isStreaming }` | Missing streaming lifecycle control from hook |
+| Workflow adapter | 5.2 | Producer-side helper with `publishStepStart/publishStepComplete/publishTaskUpdate/publishAgentStart/publishAgentUpdate/publishAgentComplete` methods instead of spec's `streamWithEvents()` AsyncGenerator wrapper | Different pattern; method-based vs generator-based |
+| Claude adapter tool events | 5.2 | Comment says tool events "handled at higher level" — adapter only processes text/thinking from stream | Spec says adapters should be SOLE consumers of SDK events |
+| Debug subscriber | 7.2 | Only console.debug logging; no event replay or JSONL dump capability | Missing observability features |
+
+### 🐛 Bugs Found
+
+| Bug | File | Line | Severity | Details |
+|-----|------|------|----------|---------|
+| dispose() null reference | `opencode-adapter.ts` | ~197 | **High** | When `dispose()` called during active streaming, sets `this.abortController = null`. Error handler subsequently tries `this.abortController.signal.aborted` → `TypeError: Cannot read properties of null`. Test is **SKIPPED** documenting this. |
+| dispose() null reference | `claude-adapter.ts` | ~111 | **High** | Same null reference pattern as OpenCode adapter. Test is **SKIPPED** documenting this. |
+| Missing Zod validation tests | `event-bus.test.ts` | — | **Medium** | No tests for: schema validation failure, early return on invalid events, or validation error logging. `publish()` does validate but correctness is unverified. |
+
+### 📋 Missing from Spec (Not Yet Implemented)
+
+| Feature | Spec Section | Description |
+|---------|-------------|-------------|
+| `CorrelationService.startRun()` | 5.3 | Register a new run for ownership tracking |
+| `CorrelationService.isOwnedEvent()` | 5.3 | Check if event belongs to current run |
+| `CorrelationService.activeRunId` | 5.3 | Track currently active run |
+| `CorrelationService.ownedSessionIds` | 5.3 | Track sessions owned by current user |
+| `useStreamConsumer().startStreaming` | 5.7 | Start streaming from hook |
+| `useStreamConsumer().stopStreaming` | 5.7 | Stop streaming from hook |
+| `useStreamConsumer().isStreaming` | 5.7 | Streaming state from hook |
+| Event replay capability | 7.2 | Replay events for debugging |
+| JSONL dump capability | 7.2 | Export events for analysis |
+
+---
+
+## Detailed Findings
+
+### 1. Bus Events (bus-events.ts) — Section 5.1.1
+
+**Location:** `src/events/bus-events.ts` (515 lines)
+
+All 19 `BusEventType` union members match the spec:
+- Stream events: `stream.text.delta`, `stream.text.complete`, `stream.thinking.delta`, `stream.thinking.complete`
+- Tool events: `stream.tool.start`, `stream.tool.complete`
+- Agent events: `stream.agent.start`, `stream.agent.update`, `stream.agent.complete`
+- Session events: `session.status`, `session.error`
+- Stream lifecycle: `stream.start`, `stream.end`, `stream.abort`, `stream.error`
+- UI events: `ui.scroll.lock`, `ui.scroll.unlock`
+- Workflow events: `workflow.step.start`, `workflow.step.complete`
+
+`BusEvent` interface has correct shape: `{ type, sessionId, runId, timestamp, data }`.
+
+`EnrichedBusEvent` extends `BusEvent` with: `resolvedToolId?`, `resolvedAgentId?`, `isSubagentTool?`, `suppressFromMainChat?`.
+
+`defineBusEvent()` factory creates typed event constructors with Zod validation — matches OpenCode's `BusEvent.define()` pattern.
+
+**BusEventDataMap** payloads match spec for all 19 event types.
+
+### 2. Event Bus Core (event-bus.ts) — Section 5.1.2
+
+**Location:** `src/events/event-bus.ts` (139 lines)
+
+`AtomicEventBus` class implements:
+- `on(type, handler)` → type-safe subscription, returns `() => void` unsubscribe
+- `onAll(handler)` → wildcard subscription
+- `publish(event)` → Zod validation + synchronous dispatch with `try/catch` per handler (error isolation)
+- `clear()` → removes all handlers
+- `hasHandlers(type?)` / `handlerCount(type?)` → introspection methods
+
+**Validation behavior:** `publish()` validates against Zod schema. On failure, logs warning and returns early (event not dispatched). This matches spec intent but **no tests verify this path**.
+
+**No singleton pattern** — managed externally via React context provider. This matches spec's decision to use React context (Section 5.7).
+
+### 3. Coalescing (coalescing.ts) — Section 5.1.3
+
+**Location:** `src/events/coalescing.ts` (78 lines)
+
+`coalescingKey()` function matches spec exactly:
+- `stream.text.delta` / `stream.thinking.delta` → returns `null` (never coalesced, each delta is additive)
+- `stream.tool.start` / `stream.tool.complete` → coalesce by `toolId`
+- `stream.agent.start` / `stream.agent.update` / `stream.agent.complete` → coalesce by `agentId`
+- `session.status` → coalesce by `sessionId`
+- `session.error` → coalesce by `sessionId`
+- All other events → returns `null`
+
+Test coverage is comprehensive with 78 lines of tests verifying each event type mapping.
+
+### 4. Batch Dispatcher (batch-dispatcher.ts) — Section 5.1.4
+
+**Location:** `src/events/batch-dispatcher.ts` (177 lines)
+
+`BatchDispatcher` implements:
+- **Double-buffer swap:** `frontBuffer` and `backBuffer` arrays swapped on flush (no allocation)
+- **16ms flush interval:** `BATCH_INTERVAL = 16` matching ~60fps
+- **Coalescing map:** Uses `coalescingKey()` to deduplicate state events within a batch
+- **Consumer array:** `subscribe(consumer)` adds consumers, called on flush
+- **Metrics:** `BatchMetrics` tracks totalFlushed, totalCoalesced, totalDropped, flushCount (bonus, not in spec)
+- **Lifecycle:** `start()` / `stop()` / `dispose()` for explicit lifecycle management
+
+**Constructor:** Takes `bus: AtomicEventBus` parameter. In `wireConsumers()`, the bus's `onAll()` feeds events into `dispatcher.enqueue()`. Spec shows bus publishing directly to dispatcher — functionally equivalent.
+
+### 5. SDK Adapters — Section 5.2
+
+#### 5.1 OpenCode Adapter (`opencode-adapter.ts`, 221 lines)
+
+Maps 9 SDK event types to BusEvents via `startStreaming(session)`:
+- Text chunks → `stream.text.delta` + `stream.text.complete`
+- Thinking chunks → `stream.thinking.delta` + `stream.thinking.complete`
+- Tool events (via client EventEmitter) → `stream.tool.start` / `stream.tool.complete`
+- Sub-agent events → `stream.agent.start` / `stream.agent.complete`
+- Session events → `session.status`
+
+**🐛 BUG:** `dispose()` sets `this.abortController = null` at line ~197. If called during active streaming, the error handler's `catch` block tries `this.abortController.signal.aborted` → `TypeError`. The test documenting this is **SKIPPED** with comment explaining the issue.
+
+#### 5.2 Claude Adapter (`claude-adapter.ts`, 138 lines)
+
+Maps text/thinking from stream to BusEvents:
+- Text chunks → `stream.text.delta` + `stream.text.complete`
+- Thinking chunks → `stream.thinking.delta` + `stream.thinking.complete`
+
+**⚠️ Deviation:** Comment says tool and agent events are "handled at higher level" — adapter only processes the stream's text/thinking content. Spec says adapters should be the **sole consumers** of SDK events.
+
+**🐛 BUG:** Same `dispose()` null reference pattern as OpenCode adapter. Test is **SKIPPED**.
+
+#### 5.3 Copilot Adapter (`copilot-adapter.ts`, 196 lines)
+
+Maps 7 SDK event types to BusEvents:
+- Text chunks → `stream.text.delta` + `stream.text.complete`
+- Thinking chunks → `stream.thinking.delta` + `stream.thinking.complete`
+- Tool events → `stream.tool.start` / `stream.tool.complete`
+- Sub-agent events → `stream.agent.start` / `stream.agent.complete`
+
+**Notable:** Implements **backpressure** via bounded buffer (`MAX_BUFFER_SIZE = 1000`) with FIFO drop. This matches spec's backpressure guidance.
+
+#### 5.4 Workflow Adapter (`workflow-adapter.ts`, ~120 lines)
+
+Producer-side helper with explicit publish methods:
+- `publishStepStart()`, `publishStepComplete()`
+- `publishTaskUpdate()`
+- `publishAgentStart()`, `publishAgentUpdate()`, `publishAgentComplete()`
+
+**⚠️ Deviation:** Spec describes `streamWithEvents()` AsyncGenerator wrapper pattern. Implementation uses method-based publisher pattern instead. Both achieve same goal of translating workflow events to BusEvents.
+
+### 6. Consumer Services — Sections 5.3–5.5
+
+#### 6.1 CorrelationService (`correlation-service.ts`) — Section 5.3
+
+**⚠️ Major Deviation:** The spec describes a rich API:
+```typescript
+// Spec contract (Section 5.3)
+class CorrelationService {
+  startRun(runId, sessionId): void
+  processBatch(events): EnrichedBusEvent[]
+  isOwnedEvent(event): boolean
+  reset(): void
+  // Properties: sdkToolIdMap, toolCallToAgentMap, subagentSessionToAgentId,
+  //             pendingTaskEntries, ownedSessionIds, toolIdToRunMap, activeRunId
+}
+```
+
+The implementation has:
+```typescript
+// Actual API
+class CorrelationService {
+  registerTool(toolId, agentId, isSubagent): void
+  enrich(event: BusEvent): EnrichedBusEvent
+  reset(): void
+  // Properties: toolToAgent, subAgentTools, mainAgentId
+}
+```
+
+**Missing:** `startRun()`, `isOwnedEvent()`, `activeRunId`, `ownedSessionIds`, `processBatch()`. The `enrich()` method processes single events vs spec's `processBatch()` for batches. Run ownership tracking is absent.
+
+#### 6.2 EchoSuppressor (`echo-suppressor.ts`) — Section 5.4
+
+Fully matches spec:
+- `expectEcho(resultText)` — registers expected echo text in FIFO queue
+- `filterDelta(delta)` — returns filtered delta (empty if suppressed, accumulated text if diverged)
+- `reset()` — clears all state
+- `hasPendingTargets` — getter for pending state
+- Uses prefix-matching with accumulator to handle deltas that arrive character-by-character
+
+#### 6.3 StreamPipelineConsumer (`stream-pipeline-consumer.ts`) — Section 5.5
+
+Implements event-to-StreamPartEvent transformation:
+- `processBatch(events: EnrichedBusEvent[])` — maps events via switch/case
+- `onStreamParts(callback)` — registers output callback
+- `mapToStreamPart(event)` — maps individual events:
+  - `stream.text.delta` → `text-delta` (with echo suppression)
+  - `stream.thinking.delta` → `thinking-meta`
+  - `stream.tool.start` → `tool-start`
+  - `stream.tool.complete` → `tool-complete`
+  - All others → `null` (ignored)
+- `reset()` — delegates to echoSuppressor.reset() + correlation.reset()
+
+**⚠️ Deviation:** Spec says `processBatch()` should call `setMessages(activeMessageId, updater)` directly. Implementation uses callback `onStreamParts(callback)` pattern — more decoupled but requires external wiring.
+
+#### 6.4 wireConsumers (`wire-consumers.ts`)
+
+Wires the complete pipeline:
+```
+bus.onAll() → dispatcher.enqueue()
+dispatcher.subscribe(batch => {
+  enriched = batch.map(e => correlation.enrich(e))
+  pipeline.processBatch(enriched)
+})
+```
+Returns `{ correlation, echoSuppressor, pipeline, dispose }`.
+
+### 7. React Integration — Section 5.7
+
+#### EventBusProvider (`event-bus-provider.tsx`, 120 lines)
+
+Creates singleton `AtomicEventBus` + `BatchDispatcher` via `useMemo([], [])`. Context throws if used outside provider. Matches spec pattern.
+
+#### useStreamConsumer Hook (`hooks.ts:211-242`)
+
+**⚠️ Deviation:** Spec signature:
+```typescript
+// Spec
+useStreamConsumer(onStreamParts): { startStreaming, stopStreaming, isStreaming }
+```
+
+Implementation:
+```typescript
+// Actual
+useStreamConsumer(onStreamParts): { resetConsumers }
+```
+
+Missing `startStreaming`, `stopStreaming`, and `isStreaming` — these would provide streaming lifecycle control from within the hook. Currently streaming is started externally via adapters.
+
+### 8. Debug Subscriber (`debug-subscriber.ts`) — Section 7.2
+
+`attachDebugSubscriber(bus)` — conditional on `ATOMIC_DEBUG=1`, logs all events via `console.debug` with timestamp, type, runId, and data preview (100 char truncation).
+
+**⚠️ Deviation:** Spec mentions event replay capability and JSONL dump for debugging. Implementation only provides console logging.
+
+---
+
+## OpenCode Pattern Validation
+
+Research into OpenCode's event-bus architecture (via DeepWiki analysis of `anomalyco/opencode`) confirms the following design decisions align:
+
+1. **In-process pub/sub** — OpenCode uses `EventBus<TEvent>` with typed `subscribe(handler)` and `publish(event)`. Our `AtomicEventBus` follows the same pattern.
+
+2. **Zod validation** — OpenCode uses `BusEvent.define({ type, schema })` factory. Our `defineBusEvent()` mirrors this exactly.
+
+3. **Batch processing** — OpenCode batches UI updates. Our `BatchDispatcher` with 16ms flush matches this pattern.
+
+4. **Error isolation** — OpenCode wraps handlers in try/catch. Our `publish()` does the same per handler.
+
+5. **No singleton** — OpenCode creates bus instances per context. Our provider pattern matches.
+
+See: `research/docs/2026-02-26-opencode-event-bus-patterns.md` for full OpenCode architecture documentation.
+
+---
+
+## Code References
+
+### Bugs
+- `src/events/adapters/opencode-adapter.ts:~197` — dispose() null reference on abortController
+- `src/events/adapters/claude-adapter.ts:~111` — dispose() null reference on abortController
+
+### Spec Deviations
+- `src/events/consumers/correlation-service.ts` — Simplified API vs spec Section 5.3
+- `src/events/consumers/stream-pipeline-consumer.ts` — Callback pattern vs spec's direct setMessages
+- `src/events/hooks.ts:211-242` — useStreamConsumer missing startStreaming/stopStreaming/isStreaming
+- `src/events/adapters/claude-adapter.ts` — Tool events not handled in adapter
+- `src/events/adapters/workflow-adapter.ts` — Method-based vs AsyncGenerator pattern
+
+### Fully Compliant
+- `src/events/bus-events.ts` — All 19 types, schemas, interfaces
+- `src/events/event-bus.ts` — AtomicEventBus core
+- `src/events/coalescing.ts` — Coalescing key logic
+- `src/events/batch-dispatcher.ts` — Double-buffer, 16ms flush, coalescing
+- `src/events/consumers/echo-suppressor.ts` — FIFO suppress, accumulator, filterDelta
+- `src/events/event-bus-provider.tsx` — React context provider
+- `src/events/debug-subscriber.ts` — Conditional debug logging
+- `src/events/hooks.ts:71-171` — useEventBus, useBusSubscription, useBusWildcard
+
+### Integration Tests
+- `src/events/integration.test.ts` (665 lines) — 8 test scenarios covering full pipeline, text deltas, tool lifecycle, echo suppression, multi-adapter, batch coalescing, thinking deltas, sub-agent lifecycle
+
+---
+
+## Architecture Documentation
+
+### Event Flow (Current Implementation)
+
+```
+SDK Stream/Events
+       ↓
+SDK Adapter (opencode/claude/copilot/workflow)
+       ↓
+bus.publish(busEvent)       ← Zod validation here
+       ↓
+AtomicEventBus
+       ↓
+bus.onAll() → dispatcher.enqueue()    ← wireConsumers() sets this up
+       ↓
+BatchDispatcher (16ms flush, coalescing, double-buffer)
+       ↓
+correlation.enrich(event)  → EnrichedBusEvent
+       ↓
+StreamPipelineConsumer.processBatch(enrichedEvents)
+       ↓
+onStreamParts callback → StreamPartEvent[]
+       ↓
+React component state update
+```
+
+### Key Design Decisions (Validated Against OpenCode)
+
+1. **No SSE/WebSocket** — In-process pub/sub is correct for single-process TUI
+2. **Zod validation at publish boundary** — Matches OpenCode's validation pattern
+3. **Handler ref pattern in hooks** — Prevents React re-subscription churn
+4. **Callback pattern for StreamPipelineConsumer** — More flexible than direct setMessages
+5. **Method-based workflow adapter** — Simpler than AsyncGenerator for discrete events
+
+---
+
+## Historical Context (from research/)
+
+- `research/docs/2026-02-26-opencode-event-bus-patterns.md` — OpenCode event-bus architecture deep-dive, confirming design alignment
+
+---
+
+## Related Research
+
+- `specs/streaming-architecture-event-bus-migration.md` — Source spec (908 lines)
+- `research/docs/2026-02-26-opencode-event-bus-patterns.md` — OpenCode patterns reference
+
+---
+
+## Open Questions
+
+1. **CorrelationService scope:** Is the simplified API (enrich/registerTool/reset) intentionally minimal for Phase 1, or should it be expanded to match spec's full contract (startRun/isOwnedEvent/activeRunId)?
+
+2. **Claude adapter tool events:** Where are tool events actually handled if not in the adapter? Is there a higher-level wiring that the spec doesn't account for?
+
+3. **useStreamConsumer lifecycle:** Should startStreaming/stopStreaming/isStreaming be added to the hook, or is external adapter control the preferred pattern?
+
+4. **Dispose() bug fix strategy:** Should dispose() guard against null abortController, or should streaming be guaranteed complete before dispose()?
+
+5. **Debug subscriber extensions:** Are event replay and JSONL dump features planned for a later phase?
diff --git a/research/docs/2026-02-27-workflow-tui-rendering-unification.md b/research/docs/2026-02-27-workflow-tui-rendering-unification.md
new file mode 100644
index 0000000000..71747834fc
--- /dev/null
+++ b/research/docs/2026-02-27-workflow-tui-rendering-unification.md
@@ -0,0 +1,502 @@
+---
+date: 2026-02-27 20:35:00 UTC
+researcher: Claude Opus 4.6
+git_commit: 60eb3008ad545a33bdce33a6c54efbdbde7f12ad
+branch: lavaman131/feature/workflow-sdk
+repository: workflow-sdk
+topic: "Unifying Workflow Executor Rendering with Main TUI Chat Interface"
+tags: [research, codebase, workflow, streaming, rendering, tui, event-bus, sub-agents, token-counts, thinking-blocks]
+status: complete
+last_updated: 2026-02-27
+last_updated_by: Claude Opus 4.6
+---
+
+# Research: Unifying Workflow Executor Rendering with Main TUI Chat Interface
+
+## Research Question
+
+Document how the main TUI chat interface renders streaming output, token counts, thinking blocks, sub-agent trees, text blocks, tool blocks, and spinners — and compare this with how the workflow executor currently renders its output. Identify the specific rendering components, data flows, and integration points that would need to be unified so that workflow execution uses the exact same rendering pipeline as the main chat interface, making workflows feel like a native part of the chat experience rather than a separate execution mode.
+
+## Summary
+
+The main TUI chat interface and the workflow executor use fundamentally different rendering paths. The chat interface implements a sophisticated event-driven pipeline: SDK adapters normalize vendor-specific streams into `BusEvent`s → `AtomicEventBus` → `BatchDispatcher` (60fps frame-aligned batching) → `StreamPipelineConsumer` → `StreamPartEvent` reducer → React state (`Part[]` arrays) → registry-dispatched renderers. This pipeline supports streaming text, thinking blocks, token counts, spinners, sub-agent trees, tool blocks, and code blocks — all rendered incrementally.
+
+The workflow executor bypasses this entire pipeline. It outputs only two static `context.addMessage()` calls (start/completion), delegates sub-agent execution to `spawnSubagentParallel` which silently consumes SDK streams without rendering, and emits `workflow.step.*` / `workflow.task.*` bus events that have **no active UI consumers**. Token counts, thinking blocks, and streaming text from workflow sub-agents are discarded. The sub-agent tree shows agents spawned by the workflow but without the rich per-agent streaming, tool progress, or thinking metadata that the main chat displays.
+
+To unify these rendering paths, the key architectural change is: workflow sub-agents must stream through the same event bus → batch dispatcher → pipeline consumer → UI reducer path as normal chat messages, rather than running in silent isolated sessions.
+
+## Detailed Findings
+
+### 1. Main TUI Chat Rendering Pipeline
+
+The main chat renders through a multi-stage pipeline with clear separation of concerns:
+
+#### 1.1 Entry Point and Bootstrap
+
+`startChatUI()` at `src/ui/index.ts:205` creates singleton instances:
+- `AtomicEventBus` — typed pub/sub with Zod schema validation (`src/events/event-bus.ts:57`)
+- `BatchDispatcher` — 16ms frame-aligned batching with double-buffer swap (`src/events/batch-dispatcher.ts:71`)
+
+These are injected into the React tree via `EventBusProvider` (`src/events/event-bus-provider.tsx:72`), wrapping `ChatApp` (`src/ui/chat.tsx:1595`).
+
+#### 1.2 SDK Stream Adapters
+
+Three SDK-specific adapters normalize vendor events to `BusEvent`s:
+
+| Adapter | File | Pattern | SDK API |
+|---------|------|---------|---------|
+| `ClaudeStreamAdapter` | `src/events/adapters/claude-adapter.ts:56` | Pull-based `AsyncIterable` | `query()` generator |
+| `CopilotStreamAdapter` | `src/events/adapters/copilot-adapter.ts:82` | Push-based `EventEmitter` | `session.on()` events |
+| `OpenCodeStreamAdapter` | `src/events/adapters/opencode-adapter.ts:73` | Hybrid pull+push | SSE + `client.on()` |
+
+Each adapter publishes normalized events to the bus:
+- `stream.text.delta` / `stream.text.complete` — text content
+- `stream.thinking.delta` / `stream.thinking.complete` — reasoning blocks
+- `stream.tool.start` / `stream.tool.complete` — tool execution
+- `stream.agent.start` / `stream.agent.update` / `stream.agent.complete` — sub-agent lifecycle
+- `stream.usage` — token counts
+- Plus session, permission, HITL, and skill events
+
+#### 1.3 Event Bus → UI Consumer Pipeline
+
+`wireConsumers()` at `src/events/consumers/wire-consumers.ts:64` establishes the processing chain:
+
+```
+SDK Adapter → bus.publish() → dispatcher.enqueue() 
+  → 16ms flush → correlation.enrich() → pipeline.processBatch()
+    → StreamPartEvent[] → React state reducer
+```
+
+Key transformations:
+- `CorrelationService` (`src/events/consumers/correlation-service.ts:52`): Enriches events with `resolvedToolId`, `resolvedAgentId`, `isSubagentTool`, `suppressFromMainChat`
+- `EchoSuppressor` (`src/events/consumers/echo-suppressor.ts:13`): Filters duplicate tool result text
+- `StreamPipelineConsumer` (`src/events/consumers/stream-pipeline-consumer.ts:60`): Maps `BusEvent` → `StreamPartEvent` (text-delta, thinking-meta, tool-start, tool-complete, text-complete)
+
+#### 1.4 React State Reducer
+
+`applyStreamPartEvent()` at `src/ui/parts/stream-pipeline.ts:799` is the core state reducer that immutably updates `ChatMessage` objects:
+
+- **`text-delta`** → `handleTextDelta()` — appends/creates/merges `TextPart` entries with tool boundary splitting
+- **`thinking-meta`** → `upsertThinkingMeta()` — creates/updates `ReasoningPart` entries
+- **`tool-start`** → `upsertToolPartStart()` — creates `ToolPart` with pending state, finalizes last streaming TextPart
+- **`tool-complete`** → `upsertToolPartComplete()` — updates ToolPart with result, output, duration
+- **`parallel-agents`** → `mergeParallelAgentsIntoParts()` — inserts/updates `AgentPart` entries at task tool boundaries
+
+Parts are stored in a sorted `Part[]` array using binary search insertion (`src/ui/parts/store.ts:42`) with timestamp-encoded IDs (`src/ui/parts/id.ts:20`) for chronological ordering.
+
+#### 1.5 Part Registry Rendering
+
+`MessageBubbleParts` at `src/ui/components/parts/message-bubble-parts.tsx:130` iterates the `Part[]` array and dispatches each part to a type-specific renderer via `PART_REGISTRY` (`src/ui/components/parts/registry.tsx:22`):
+
+| Part Type | Renderer | Visual |
+|-----------|----------|--------|
+| `text` | `TextPartDisplay` | `●` bullet prefix + markdown content |
+| `reasoning` | `ReasoningPartDisplay` | `∴ Thinking...` / `∴ Thought (Xs)` with dimmed style |
+| `tool` | `ToolPartDisplay` | Tool-specific renderers via `ToolResultRegistry` |
+| `agent` | `AgentPartDisplay` | `ParallelAgentsTree` with foreground/background split |
+| `task-list` | `TaskListPartDisplay` | `TaskListBox` with topological sorting |
+| `skill-load` | `SkillLoadPartDisplay` | Skill loading status |
+| `mcp-snapshot` | `McpSnapshotPartDisplay` | MCP server status |
+| `compaction` | `CompactionPartDisplay` | Context compaction banner |
+
+#### 1.6 Token Count Display
+
+Token usage flows through `stream.usage` bus events (`src/events/bus-events.ts:53`), subscribed at `src/ui/chat.tsx:2755`. The `outputTokens` value is baked onto the `ChatMessage` via `setMessagesWindowed()`. Display occurs in two places:
+
+- **During streaming**: `LoadingIndicator` at `src/ui/chat.tsx:1038` shows `↓ Xk tokens` via `formatTokenCount()` (k/M suffixes)
+- **After completion**: `CompletionSummary` at `src/ui/chat.tsx:1104` shows `⣿ Verb for Xs · ↓ Xk tokens · thought for Xs`
+
+Completion summary visibility requires `durationMs >= 1000` (`src/ui/utils/loading-state.ts:70`).
+
+#### 1.7 Thinking Block Display
+
+Thinking content flows through `stream.thinking.delta` → `StreamPipelineConsumer` → `thinking-meta` StreamPartEvent → `upsertThinkingMeta()`. Duration flows through `stream.thinking.complete` → direct bus subscription at `src/ui/chat.tsx:2789`.
+
+`ReasoningPartDisplay` at `src/ui/components/parts/reasoning-part-display.tsx:47` renders with:
+- `∴ Thinking...` header during streaming
+- `∴ Thought (Xs)` header when finalized with `durationMs`
+- Dimmed markdown syntax style via `createDimmedSyntaxStyle(syntaxStyle, 0.6)`
+
+#### 1.8 Spinner/Loading
+
+`LoadingIndicator` at `src/ui/chat.tsx:1038` uses braille animation frames (`⣾⣽⣻⢿⡿⣟⣯⣷`) at 120ms per frame. Verb selection: `"Reasoning"` if `thinkingMs > 0`, else `"Composing"`. Enhanced info line shows elapsed time, token count, and thinking duration.
+
+Visibility via `shouldShowMessageLoadingIndicator()` at `src/ui/utils/loading-state.ts:35`: true when `message.streaming === true` or active background agents exist.
+
+#### 1.9 Sub-Agent Tree
+
+Agent events (`stream.agent.start/update/complete`) are subscribed at `src/ui/chat.tsx:2813-2907`, updating `parallelAgents` React state. A `useEffect` at `chat.tsx:3197` syncs live agents into the streaming message's `Part[]` array.
+
+`ParallelAgentsTree` at `src/ui/components/parallel-agents-tree.tsx:593` renders:
+- Sorted by status priority (running → pending → background → completed → interrupted → error)
+- Tree connectors: `├─`, `└─`, `│`, `╰`
+- Status colors: completed=green, error=red, pending/interrupted=yellow, running=muted
+- Per-agent tool count, current tool, elapsed time, result text
+- Background agents shown separately with distinct header
+- Max 5 visible agents with `"...and N more"` overflow
+
+### 2. Workflow Executor Rendering (Current State)
+
+#### 2.1 Two Direct UI Calls
+
+The workflow executor at `src/workflows/executor.ts:122` has exactly two rendering calls:
+
+1. **Start message** (`executor.ts:150-153`): `context.addMessage("assistant", "Starting **${definition.name}** workflow...")`
+2. **Completion message** (`executor.ts:325-328`): `context.addMessage("assistant", "**${definition.name}** workflow completed successfully.")`
+
+These produce static text in the chat — no streaming, no incremental rendering, no parts-based display.
+
+#### 2.2 Silent Sub-Agent Execution
+
+Sub-agents are executed via `context.spawnSubagentParallel` implemented at `src/ui/chat.tsx:3889-4068`:
+
+- Each agent creates an **independent SDK session** via `createSubagentSession()` (`chat.tsx:3940`)
+- The stream is consumed silently — text chunks accumulate in `summaryParts` (`chat.tsx:3979`)
+- Tool uses are counted but **not displayed** (`chat.tsx:3977`)
+- **No text deltas are rendered** during sub-agent execution
+- **No thinking blocks** are captured — only `"tool_use"` and `"text"` message types are checked (`chat.tsx:3976-3980`)
+- **No token counts** are tracked — usage events are discarded
+- Output is truncated to 4000 characters (`chat.tsx:4011`)
+- Sessions are destroyed after completion (`chat.tsx:4033`)
+
+#### 2.3 Bus Events Published but Not Consumed
+
+The `WorkflowEventAdapter` (`src/events/adapters/workflow-adapter.ts:31`) publishes:
+
+| Event | Published At | UI Consumer |
+|-------|-------------|-------------|
+| `workflow.step.start` | `executor.ts:268-273` | **None** |
+| `workflow.step.complete` | `executor.ts:259-263` | **None** |
+| `workflow.task.update` | `executor.ts:290-296` | **None** |
+| `stream.agent.start` | `executor.ts:196-198` | Yes — `chat.tsx:2813` |
+| `stream.agent.complete` | `executor.ts:205-210` | Yes — `chat.tsx:2885` |
+
+The `stream.agent.*` events are consumed, so the sub-agent tree **does** show workflow agents. However, these agents appear without tool progress, streaming text, thinking blocks, or token counts because the independent SDK sessions don't publish to the shared bus.
+
+#### 2.4 What the Workflow Executor Does NOT Do
+
+- ❌ Does not create SDK stream adapters for sub-agent sessions
+- ❌ Does not publish `stream.text.delta` or `stream.thinking.delta` events
+- ❌ Does not render incremental text or thinking blocks
+- ❌ Does not track or emit token usage (`stream.usage`)
+- ❌ Does not render tool calls incrementally (`stream.tool.start/complete`)
+- ❌ Does not publish `stream.agent.update` events (method exists but never called from executor)
+- ❌ Does not use the `BatchDispatcher` or `StreamPipelineConsumer` pipeline
+
+### 3. Gap Analysis: Chat vs Workflow Rendering
+
+| Feature | Main Chat | Workflow Executor |
+|---------|-----------|-------------------|
+| Streaming text | ✅ Incremental via `stream.text.delta` | ❌ Text accumulated silently, output truncated to 4000 chars |
+| Token counts | ✅ Via `stream.usage` → `CompletionSummary` | ❌ Not tracked or displayed |
+| Thinking blocks | ✅ Via `stream.thinking.delta` → `ReasoningPart` | ❌ Not captured from sub-agent streams |
+| Spinner with metadata | ✅ Elapsed time, tokens, thinking duration | ⚠️ Basic streaming flag only via `context.setStreaming(true)` |
+| Sub-agent tree | ✅ Full tree with tool counts, current tool, duration | ⚠️ Tree shows but without live tool progress |
+| Tool blocks | ✅ Rendered inline with status, collapsible output | ❌ Tool uses counted but not rendered |
+| Text blocks | ✅ Markdown-rendered with `●` bullet prefix | ❌ Only start/completion static messages |
+| Code blocks | ✅ Syntax-highlighted via `CodeBlock` component | ❌ Not applicable (no streaming content) |
+| Completion summary | ✅ Duration, tokens, thinking time | ❌ No per-agent or per-step summary |
+| Parts-based rendering | ✅ Full `Part[]` pipeline with registry dispatch | ❌ Not used — only `context.addMessage()` |
+
+### 4. Integration Points for Unification
+
+#### 4.1 The Core Problem: Silent Sessions
+
+The fundamental issue is at `src/ui/chat.tsx:3889-4068` where `spawnSubagentParallel` creates independent SDK sessions that don't publish to the shared event bus. Each sub-agent's stream is consumed in a tight loop:
+
+```typescript
+// chat.tsx:3970-3984 — current silent consumption
+for await (const msg of stream) {
+  if (msg.type === "tool_use") { toolUses++; }
+  else if (msg.type === "text") { summaryParts.push(msg.content); }
+}
+```
+
+This discards all thinking blocks, token counts, and tool lifecycle events.
+
+#### 4.2 What Would Need to Change
+
+**Option A — Bus-Integrated Sub-Agent Sessions**: Instead of silently consuming sub-agent streams, create SDK stream adapters for each sub-agent session and have them publish to the shared `AtomicEventBus`. The correlation service would need to recognize sub-agent session IDs and attribute events to the parent agent.
+
+Key files that would change:
+- `src/ui/chat.tsx:3889-4068` (`spawnSubagentParallel`) — create adapters instead of silent consumption
+- `src/events/consumers/correlation-service.ts` — track sub-agent session ownership
+- `src/ui/parts/stream-pipeline.ts` — handle nested agent rendering (sub-agent text/tools inside parent agent context)
+
+**Option B — Workflow-Specific Stream Adapter**: Enhance `WorkflowEventAdapter` to forward sub-agent SDK events as `stream.text.delta`, `stream.thinking.delta`, `stream.tool.*`, and `stream.usage` events scoped to the workflow context.
+
+Key files that would change:
+- `src/events/adapters/workflow-adapter.ts` — add text/thinking/tool/usage publishing methods
+- `src/workflows/executor.ts` — consume sub-agent streams through the adapter instead of silently
+- `src/ui/chat.tsx` — consume workflow-scoped stream events in the UI reducer
+
+**Option C — Inline Agent Rendering**: Instead of running sub-agents in isolated sessions, run them as "inline" agents that render directly into the parent chat's message stream, similar to how normal chat streaming works.
+
+Key considerations:
+- Each workflow node could produce a new assistant message with full parts-based rendering
+- The `streamAndWait()` mechanism already pipes through the normal rendering pipeline
+- Node transitions could be displayed as progress markers between rendered messages
+
+#### 4.3 Existing Infrastructure That Supports Unification
+
+Several components already support the unification:
+
+1. **`streamAndWait()`** at `src/ui/chat.tsx:4070-4081` — already pipes through normal chat streaming. Workflow nodes that need to run a full agent turn could use this path instead of `spawnSubagentParallel`.
+
+2. **`WorkflowEventAdapter`** at `src/events/adapters/workflow-adapter.ts` — already publishes `stream.agent.*` events. Could be extended to publish text/thinking/tool/usage events.
+
+3. **`CorrelationService`** at `src/events/consumers/correlation-service.ts` — already enriches events with agent context. The `resolvedAgentId` and `isSubagentTool` fields could scope sub-agent rendering.
+
+4. **`AgentPartDisplay`** at `src/ui/components/parts/agent-part-display.tsx` — already handles foreground/background split. Workflow agents could carry inline content.
+
+5. **`PART_REGISTRY`** at `src/ui/components/parts/registry.tsx` — extensible by adding new part types for workflow-specific content (e.g., step progress, node transitions).
+
+6. **Event bus event types** at `src/events/bus-events.ts` — `workflow.step.start/complete` and `workflow.task.update` events already exist but lack UI consumers.
+
+#### 4.4 Data Flow for Unified Rendering
+
+The target data flow would be:
+
+```
+Workflow Executor
+  → for each graph node:
+    → SDK Adapter publishes to AtomicEventBus (same as normal chat)
+    → BatchDispatcher batches at 60fps
+    → CorrelationService attributes to parent workflow agent
+    → StreamPipelineConsumer maps to StreamPartEvents
+    → React reducer updates ChatMessage.parts[]
+    → MessageBubbleParts renders via PART_REGISTRY
+    → Text, thinking, tools, tokens all visible per-agent
+```
+
+### 5. Workflow-Specific UI Elements
+
+#### 5.1 Visual Differentiation (Already Exists)
+
+- **Teal border**: `src/ui/chat.tsx:6014-6017` — input border changes to `themeColors.accent` when `workflowActive`
+- **Footer hints**: `src/ui/chat.tsx:6106-6132` — shows "workflow · esc to interrupt · ctrl+c twice to exit"
+- **Auto-approval**: `src/ui/chat.tsx:3071-3076, 3139-3147` — HITL prompts auto-approved during workflow
+
+#### 5.2 Task List Rendering (Two Modes)
+
+- **Inline**: `TaskListPartDisplay` via parts registry — shows tasks within message parts
+- **Persistent**: `TaskListPanel` at `src/ui/components/task-list-panel.tsx:157` — file-watching component that reads `tasks.json` from session directory
+
+#### 5.3 WorkflowChatState
+
+At `src/ui/chat.tsx:814-843`, the `WorkflowChatState` tracks:
+- `workflowActive`, `workflowType`, `initialPrompt`
+- `currentNode`, `iteration`, `maxIterations`
+- `pendingApproval`, `specApproved`, `feedback`
+- `workflowConfig` with `sessionId`, `userPrompt`, `workflowName`
+
+### 6. CommandContext — The Bridge Interface
+
+The `CommandContext` at `src/ui/commands/registry.ts:75-168` is the interface between workflow executors and the TUI:
+
+| Method | Purpose | Used by Workflow |
+|--------|---------|-----------------|
+| `addMessage()` | Static text into chat | ✅ Start/completion messages |
+| `setStreaming()` | Toggle streaming indicator | ✅ On/off only |
+| `sendSilentMessage()` | Send message without user input | ❌ |
+| `spawnSubagentParallel()` | Run parallel SDK sessions | ✅ Silent execution |
+| `streamAndWait()` | Stream through normal pipeline | ❌ Not used by executor |
+| `waitForUserInput()` | Block for user response | ❌ Not used by executor |
+| `updateWorkflowState()` | Update workflow UI state | ✅ Active/type/config |
+| `setWorkflowSessionDir()` | Enable task panel | ✅ On first tasks |
+| `setWorkflowSessionId()` | Set session ID | ✅ On first tasks |
+| `setWorkflowTaskIds()` | Guard task persistence | ✅ On first tasks |
+
+Key observation: `streamAndWait()` already pipes through the full rendering pipeline but the workflow executor uses `spawnSubagentParallel()` instead.
+
+## Code References
+
+### Main TUI Rendering Pipeline
+- `src/ui/index.ts:205` — `startChatUI()` entry point, creates bus and dispatcher
+- `src/ui/index.ts:446-454` — SDK adapter selection by agent type
+- `src/ui/chat.tsx:1595` — `ChatApp` main React component
+- `src/ui/chat.tsx:2626-2740` — Stream part event processing callback
+- `src/ui/chat.tsx:2755-2787` — Token count (`stream.usage`) subscription
+- `src/ui/chat.tsx:2789-2830` — Thinking complete subscription
+- `src/ui/chat.tsx:2813-2907` — Agent lifecycle subscriptions
+- `src/ui/chat.tsx:1038-1077` — `LoadingIndicator` (spinner with metadata)
+- `src/ui/chat.tsx:1104-1139` — `CompletionSummary` (post-stream stats)
+- `src/ui/parts/stream-pipeline.ts:799-871` — `applyStreamPartEvent()` reducer
+- `src/ui/parts/stream-pipeline.ts:624-752` — `mergeParallelAgentsIntoParts()`
+- `src/ui/components/parts/registry.tsx:22-31` — `PART_REGISTRY` type→renderer mapping
+- `src/ui/components/parts/text-part-display.tsx:41` — Text rendering
+- `src/ui/components/parts/reasoning-part-display.tsx:47` — Thinking rendering
+- `src/ui/components/parts/tool-part-display.tsx:106` — Tool rendering
+- `src/ui/components/parts/agent-part-display.tsx:53` — Agent tree rendering
+- `src/ui/components/parallel-agents-tree.tsx:593` — Tree component
+
+### Event Bus System
+- `src/events/event-bus.ts:57` — `AtomicEventBus` pub/sub
+- `src/events/batch-dispatcher.ts:71` — Frame-aligned batching
+- `src/events/bus-events.ts:33-60` — 27 typed event definitions
+- `src/events/consumers/wire-consumers.ts:64` — Pipeline wiring
+- `src/events/consumers/stream-pipeline-consumer.ts:60` — BusEvent→StreamPartEvent mapping
+- `src/events/consumers/correlation-service.ts:52` — Event enrichment/correlation
+
+### SDK Adapters
+- `src/events/adapters/claude-adapter.ts:56` — Claude → BusEvent
+- `src/events/adapters/copilot-adapter.ts:82` — Copilot → BusEvent
+- `src/events/adapters/opencode-adapter.ts:73` — OpenCode → BusEvent
+- `src/events/adapters/workflow-adapter.ts:31` — Workflow → BusEvent (producer-side)
+
+### Workflow Executor
+- `src/workflows/executor.ts:122` — `executeWorkflow()` entry point
+- `src/workflows/executor.ts:150-153` — Start message (only direct rendering)
+- `src/workflows/executor.ts:188-243` — Sub-agent spawn wiring
+- `src/workflows/executor.ts:248-322` — Graph streaming loop
+- `src/workflows/executor.ts:325-328` — Completion message
+- `src/ui/chat.tsx:3889-4068` — `spawnSubagentParallel` (silent consumption)
+- `src/ui/chat.tsx:3970-3984` — Silent stream consumption loop
+
+### Workflow Graph Engine
+- `src/workflows/graph/compiled.ts:253` — `GraphExecutor` class
+- `src/workflows/graph/compiled.ts:322` — `streamSteps()` async generator
+- `src/workflows/graph/stream.ts:56` — `StreamRouter` class
+- `src/workflows/ralph/graph.ts:98` — `createRalphWorkflow()` builder
+
+### Workflow UI Integration
+- `src/ui/commands/workflow-commands.ts:623` — `createWorkflowCommand()`
+- `src/ui/commands/registry.ts:75-168` — `CommandContext` interface
+- `src/ui/chat.tsx:814-843` — `WorkflowChatState` type
+- `src/ui/chat.tsx:4070-4081` — `streamAndWait()` implementation
+- `src/ui/chat.tsx:6014-6017` — Teal border during workflow
+
+## Architecture Documentation
+
+### Current Architecture: Two Parallel Rendering Paths
+
+```
+PATH 1 — Main Chat (Full Rendering):
+  User Message → SDK session.stream()
+    → SDKStreamAdapter (Claude/Copilot/OpenCode)
+      → bus.publish(stream.text.delta, stream.thinking.delta, etc.)
+        → BatchDispatcher (16ms batching)
+          → CorrelationService (enrichment)
+            → StreamPipelineConsumer (BusEvent → StreamPartEvent)
+              → chat.tsx callback → applyStreamPartEvent()
+                → ChatMessage.parts[] update
+                  → MessageBubbleParts → PART_REGISTRY → renderers
+
+PATH 2 — Workflow Executor (Minimal Rendering):
+  /ralph command → executeWorkflow()
+    → context.addMessage("Starting workflow...")
+    → for await (step of streamGraph()):
+      → eventAdapter.publishStepStart()     ← NO UI CONSUMER
+      → eventAdapter.publishTaskUpdate()    ← NO UI CONSUMER
+      → spawnSubagentParallel():
+        → createSubagentSession()           ← INDEPENDENT session
+        → for await (msg of stream):        ← SILENT consumption
+          → summaryParts.push(msg.content)  ← NO rendering
+        → return SubagentResult             ← truncated to 4000 chars
+    → context.addMessage("Workflow completed.")
+```
+
+### Target Architecture: Unified Rendering Path
+
+```
+UNIFIED PATH — Workflows Using Chat Pipeline:
+  /ralph command → executeWorkflow()
+    → for each graph node:
+      → Create SDKStreamAdapter for sub-agent session
+      → adapter.startStreaming() publishes to shared bus
+        → Same pipeline as PATH 1:
+          → BatchDispatcher → CorrelationService → StreamPipelineConsumer
+            → chat.tsx reducer → Part[] → renderers
+      → Result: Full streaming text, thinking, tools, tokens visible
+    → workflow.step.* events consumed by new UI components
+    → Per-node completion summaries with token counts
+```
+
+### Event Type Coverage
+
+| BusEventType | Published by Chat | Published by Workflow | Consumed by UI |
+|---|---|---|---|
+| `stream.text.delta` | ✅ via SDK adapter | ❌ | ✅ `StreamPipelineConsumer` |
+| `stream.text.complete` | ✅ via SDK adapter | ❌ | ✅ `StreamPipelineConsumer` |
+| `stream.thinking.delta` | ✅ via SDK adapter | ❌ | ✅ `StreamPipelineConsumer` |
+| `stream.thinking.complete` | ✅ via SDK adapter | ❌ | ✅ `chat.tsx:2789` |
+| `stream.tool.start` | ✅ via SDK adapter | ❌ | ✅ `StreamPipelineConsumer` |
+| `stream.tool.complete` | ✅ via SDK adapter | ❌ | ✅ `StreamPipelineConsumer` |
+| `stream.agent.start` | ✅ via SDK adapter | ✅ via workflow adapter | ✅ `chat.tsx:2813` |
+| `stream.agent.update` | ✅ via SDK adapter | ⚠️ method exists, never called | ✅ `chat.tsx:2870` |
+| `stream.agent.complete` | ✅ via SDK adapter | ✅ via workflow adapter | ✅ `chat.tsx:2885` |
+| `stream.usage` | ✅ via SDK adapter | ❌ | ✅ `chat.tsx:2755` |
+| `workflow.step.start` | N/A | ✅ via workflow adapter | ❌ **No consumer** |
+| `workflow.step.complete` | N/A | ✅ via workflow adapter | ❌ **No consumer** |
+| `workflow.task.update` | N/A | ✅ via workflow adapter | ❌ **No consumer** |
+
+### Component File Inventory
+
+| Directory | Files | Purpose |
+|---|---|---|
+| `src/ui/parts/` | 24 (12 impl + 12 test) | Stream pipeline, part store, handlers, guards, types |
+| `src/ui/components/parts/` | 15 (10 impl + 5 test) | Part renderer components |
+| `src/ui/components/` | 27 (17 impl + 10 test) | UI components (tree, indicators, dialogs) |
+| `src/ui/utils/` | 38 (18 impl + 20 test) | Formatting, state, lifecycle, background agents |
+| `src/events/` | 14 (7 impl + 7 test) | Event bus core, batching, hooks |
+| `src/events/adapters/` | 7 (5 impl + 2 test) | SDK-specific stream adapters |
+| `src/events/consumers/` | 6 (3 impl + 3 test) | Event consumers, correlation, echo suppression |
+| `src/workflows/` | 7 | Executor, session, index |
+| `src/workflows/graph/` | ~15 | Graph engine, builder, types, node factories |
+| `src/workflows/ralph/` | ~10 | Ralph-specific graph, state, prompts, definition |
+
+## Historical Context (from research/)
+
+### Directly Related Research Documents
+
+- `research/docs/2026-02-26-streaming-architecture-event-bus-migration.md` — Documents the callback-to-event-bus migration. The streaming pipeline now routes through `AtomicEventBus`, but the migration was incomplete for workflow rendering.
+
+- `research/docs/2026-02-26-streaming-event-bus-spec-audit.md` — Audits the event bus spec implementation. Confirms that `workflow.step.*` and `workflow.task.*` events are defined and published but have no UI consumers.
+
+- `research/docs/2026-02-25-unified-workflow-execution-research.md` — Analyzes why workflows cannot share the main chat's rendering pipeline generically. Identifies 9 Ralph-specific coupling points that need generalization.
+
+- `research/docs/2026-02-25-ui-workflow-coupling.md` — Maps UI↔workflow coupling. Shows `CommandContext` as the sole communication bridge. Identifies Ralph-specific state in chat.tsx (session dir, task IDs, TodoWrite guards).
+
+- `research/docs/2026-02-21-workflow-sdk-inline-mode-research.md` — Confirms workflows already run inline via `streamAndWait()`. However, `streamAndWait()` is used for chat-based workflow mode, not for the graph executor's sub-agent execution.
+
+- `research/docs/2026-02-15-subagent-event-flow-diagram.md` — Documents a race condition in background agent events where `tool.complete` fires before `subagent.complete`. Relevant to workflow rendering since workflow sub-agents are background agents.
+
+- `research/docs/2026-02-12-sdk-ui-standardization-comprehensive.md` — Confirms UI components (ToolResult, ParallelAgentsTree, TaskListIndicator) are already SDK-agnostic. Event normalization across all three SDKs is complete.
+
+- `research/docs/2026-02-12-tui-layout-streaming-content-ordering.md` — Identifies the dual-channel rendering issue: interleaved segments (text+tools) vs fixed-position components (agent tree, task list). Relevant to how workflow content would be positioned.
+
+- `research/docs/2026-02-09-token-count-thinking-timer-bugs.md` — Documents bugs in the streaming metadata pipeline: completion summary threshold was too high, thinking metadata missing from OpenCode/Copilot SDKs. These bugs affect both chat and workflow rendering.
+
+- `research/docs/2026-02-25-graph-execution-engine-technical-documentation.md` — Technical reference for the graph engine. Confirms the engine is fully generic with no UI dependencies. Any compiled graph streams `StepResult` objects via async generator.
+
+- `research/docs/2026-02-25-ralph-workflow-implementation.md` — Technical reference for the Ralph workflow specifically. Three-phase graph: planner → worker loop → review & fix. Uses builder pattern.
+
+- `research/docs/2026-02-11-workflow-sdk-implementation.md` — Earlier workflow SDK design document.
+
+## Related Research
+
+- `research/docs/2026-02-25-workflow-sdk-design.md`
+- `research/docs/2026-02-25-workflow-sdk-patterns.md`
+- `research/docs/2026-02-25-workflow-sdk-standardization.md`
+- `research/docs/2026-02-25-workflow-sdk-refactor-research.md`
+- `research/docs/2026-02-25-workflow-registration-flow.md`
+- `research/docs/2026-02-16-atomic-chat-architecture-current.md`
+- `research/docs/2026-02-16-opencode-message-rendering-patterns.md`
+- `research/docs/2026-02-15-sub-agent-tree-status-lifecycle-sdk-parity.md`
+- `research/docs/2026-02-23-258-background-agents-sdk-event-pipeline.md`
+
+## Open Questions
+
+1. **Concurrency model**: If multiple workflow sub-agents stream simultaneously through the shared bus, how should the UI interleave their content? Should each agent get its own collapsible section, or should content merge into a single stream?
+
+2. **Agent nesting depth**: The current sub-agent tree supports flat agent lists. Workflow graphs can have sub-agents that themselves spawn sub-agents (e.g., Ralph's worker uses the "worker" agent type which may use Task tools internally). How deep should the tree render?
+
+3. **Per-node vs per-agent rendering**: Should each graph node's execution produce a separate assistant message in the chat, or should all nodes render within a single message with step transitions shown as dividers?
+
+4. **Token aggregation**: Should token counts be shown per-agent, per-node, per-step, or aggregated for the entire workflow?
+
+5. **Context window management**: Sub-agent sessions are currently independent and destroyed after use. If they stream through the shared bus, the correlation service needs to track multiple concurrent sessions without conflicting with the parent session's state.
+
+6. **`workflow.step.*` and `workflow.task.*` event consumers**: These events are published but have no UI subscribers. Should they be rendered as progress indicators, step markers, or integrated into the parts system?
+
+7. **Backward compatibility**: Existing `spawnSubagentParallel` consumers expect `SubagentResult` return values. A unified approach must still provide these results while also rendering incrementally.
diff --git a/research/docs/2026-02-28-workflow-gaps-architecture.md b/research/docs/2026-02-28-workflow-gaps-architecture.md
new file mode 100644
index 0000000000..e5c5dfdfd9
--- /dev/null
+++ b/research/docs/2026-02-28-workflow-gaps-architecture.md
@@ -0,0 +1,481 @@
+---
+date: 2026-02-28 05:36:00 UTC
+researcher: Copilot (Claude Opus 4.6)
+git_commit: 21201623897ed3dcc3f2214ca0a54a6df7a4c978
+branch: lavaman131/feature/workflow-sdk
+repository: workflow-sdk
+topic: "Workflow Gaps: Exact Files, Functions, and Architecture Required to Fill All Gaps"
+tags: [research, codebase, workflow-gaps, part-registry, custom-tools, mcp-bridge, max-iterations, dead-modules, unrendered-components, unconsumed-events]
+status: complete
+last_updated: 2026-02-28
+last_updated_by: Copilot (Claude Opus 4.6)
+---
+
+# Research: Workflow Gaps — Files to Edit and Architecture Required
+
+## Research Question
+
+For each gap in `research/workflow-gaps.md`, identify the exact files, functions, and code locations that need to be edited, and document the architectural changes required — covering: (1) WorkflowStepPartDisplay registration in PART_REGISTRY, (2) registerCustomTools() activation during init, (3) OpenCode MCP bridge placeholder tool handlers, (4) --max-iterations flag removal from chat.ts, (5) the 6 dead modules and their intended import points, (6) the 6 unrendered UI components and their registration/rendering hooks, and (7) the 12 unconsumed event types and their intended consumer wiring.
+
+## Summary
+
+The gaps documented in `research/workflow-gaps.md` span 7 categories across ~40 source files. Each gap has a clear architectural root cause and a specific set of files that need editing. The findings are organized below by gap category with exact file paths, line numbers, and descriptions of the disconnections.
+
+---
+
+## 🔴 Gap 1: WorkflowStepPartDisplay Not Registered in PART_REGISTRY
+
+### Root Cause
+
+Three disconnections in the rendering pipeline prevent workflow step events from reaching the UI:
+
+1. **Consumer gap**: `StreamPipelineConsumer.mapToStreamPart()` does not map `workflow.step.*` bus events to `StreamPartEvent`s
+2. **Type system gap**: `WorkflowStepPart` is not defined in `types.ts` and not in the `Part` union
+3. **Registry gap**: `"workflow-step"` is not a key in `PART_REGISTRY`
+
+### Event Flow (Current — Broken)
+
+```
+executor.ts:346 → publishStepStart()
+  → workflow-adapter.ts:69 → bus.publish("workflow.step.start")
+    → wire-consumers.ts:70 → dispatcher.enqueue()
+      → stream-pipeline-consumer.ts:177 → default: return null  ← DROPPED
+```
+
+### Files to Edit
+
+| File | Lines | What Needs to Change |
+|------|-------|---------------------|
+| `src/events/consumers/stream-pipeline-consumer.ts` | 126-182 | Add `case "workflow.step.start"` and `case "workflow.step.complete"` to `mapToStreamPart()` switch, mapping to `"workflow-step-start"` and `"workflow-step-complete"` `StreamPartEvent`s |
+| `src/ui/parts/types.ts` | 124-132 | Define `WorkflowStepPart` interface (with `type: "workflow-step"`, `nodeId`, `nodeName`, `status`, `durationMs?`) and add it to the `Part` union |
+| `src/ui/components/parts/registry.tsx` | 22-31 | Add `"workflow-step": WorkflowStepPartDisplay` entry to `PART_REGISTRY` and import the component |
+| `src/ui/components/parts/index.ts` | 1-18 | Add `WorkflowStepPartDisplay` to barrel exports |
+| `src/ui/components/parts/workflow-step-part-display.tsx` | 11 | Verify/fix the import of `WorkflowStepPart` from `../../parts/types.ts` once the type is defined |
+
+### Existing Code That Already Works (Once Connected)
+
+- `src/ui/parts/stream-pipeline.ts:987-999` — Reducer handles `"workflow-step-start"`, creates `WorkflowStepPart`
+- `src/ui/parts/stream-pipeline.ts:1002-1019` — Reducer handles `"workflow-step-complete"`, updates status
+- `src/ui/components/parts/workflow-step-part-display.tsx:25-53` — Renderer component exists
+- `src/events/adapters/workflow-adapter.ts:56-101` — Adapter publishes events correctly
+- `src/workflows/executor.ts:336-414` — Executor calls adapter during graph iteration
+
+---
+
+## 🔴 Gap 2: registerCustomTools() Never Called
+
+### Root Cause
+
+The entire custom tools pipeline is built (discovery → import → schema conversion → registration) but the orchestrator function `registerCustomTools()` is never called from any init/startup code path. The spec's Phase 3 checklist (`specs/custom-tools-directory.md:853`) remains unchecked.
+
+### Files to Edit
+
+| File | Lines | What Needs to Change |
+|------|-------|---------------------|
+| `src/commands/chat.ts` | 243-251 | Call `registerCustomTools(client)` between client creation (line 243) and `client.start()` (line 251) |
+| `src/sdk/tools/index.ts` | 7-8 | Add re-export of `registerCustomTools` and `cleanupTempToolFiles` from `./discovery.ts` |
+
+### Intended Call Site (from spec)
+
+```typescript
+// src/commands/chat.ts — between lines 248 and 251
+const client = createClientForAgentType(agentType);     // line 243
+if (agentType === "copilot") {
+    client.registerTool(createTodoWriteTool());          // line 246-248
+}
+await registerCustomTools(client);                       // ← MISSING
+await client.start();                                    // line 251
+```
+
+### Supporting Infrastructure (Already Built)
+
+| File | Lines | What It Does |
+|------|-------|-------------|
+| `src/sdk/tools/discovery.ts` | 262-280 | `registerCustomTools()` — orchestrator function |
+| `src/sdk/tools/discovery.ts` | 129-157 | `discoverToolFiles()` — scans `.atomic/tools/` and `~/.atomic/tools/` |
+| `src/sdk/tools/discovery.ts` | 221-250 | `loadToolsFromDisk()` — dynamic import + Zod schema conversion |
+| `src/sdk/tools/discovery.ts` | 185-206 | `convertToToolDefinition()` — wraps `execute()` in validated handler |
+| `src/sdk/tools/discovery.ts` | 80-103 | `prepareToolFileForImport()` — rewrites `@atomic/plugin` imports |
+| `src/sdk/tools/plugin.ts` | 40-44 | `tool()` — user-facing authoring helper |
+| `src/sdk/tools/registry.ts` | 29-51 | `ToolRegistry` singleton (permanently empty without activation) |
+| `src/sdk/tools/truncate.ts` | 12-39 | `truncateToolOutput()` — caps output at 2000 lines / 50KB |
+
+---
+
+## 🔴 Gap 3: OpenCode MCP Bridge Returns Placeholder Strings
+
+### Root Cause
+
+`generateMcpServerScript()` serializes only `{name, description, inputSchema}` via `JSON.stringify` (the `handler` function is inherently non-serializable). The generated MCP stdio server script returns `"Tool ${toolName} executed via MCP bridge"` for every `tools/call` request instead of dispatching to the actual handler.
+
+### The Placeholder Code
+
+```typescript
+// src/sdk/tools/opencode-mcp-bridge.ts:77-88
+} else if (method === "tools/call") {
+    const toolName = (params as Record<string, unknown>)?.name as string;
+    const tool = TOOLS.find((t: { name: string }) => t.name === toolName);
+    if (!tool) {
+        respondError(id, -32601, `Tool not found: ${toolName}`);
+    } else {
+        // For MCP bridge, we return a placeholder — actual execution happens
+        // in the Atomic process via the registered handler
+        respond(id, {
+            content: [{ type: "text", text: `Tool ${toolName} executed via MCP bridge` }],
+        });
+    }
+}
+```
+
+### Files to Edit
+
+| File | Lines | What Needs to Change |
+|------|-------|---------------------|
+| `src/sdk/tools/opencode-mcp-bridge.ts` | 25-110 | Redesign the bridge to support actual handler execution. Two approaches exist in the codebase: (a) Claude's in-process MCP pattern using `createSdkMcpServer()`, or (b) IPC between the spawned script and the main process |
+| `src/sdk/clients/opencode.ts` | 1201-1221 | `registerToolsMcpServer()` — may need modification depending on the bridge approach |
+
+### How Other Clients Solve This
+
+| Client | Pattern | Handler Invoked? |
+|--------|---------|-----------------|
+| **Claude** (`claude.ts:1694-1748`) | In-process MCP server via `createSdkMcpServer()` — handler closure stays in-process | ✓ Yes — `tool.handler()` at line 1711 |
+| **Copilot** (`copilot.ts:871-888`) | Direct SDK injection — handler-bearing `SdkTool` objects passed to session config | ✓ Yes — `tool.handler()` at line 885 |
+| **OpenCode** (`opencode-mcp-bridge.ts:77-88`) | Separate Bun process via stdio — handler lost at JSON.stringify serialization boundary | ✗ No — placeholder string returned |
+
+### Cleanup Gap
+
+`cleanupMcpBridgeScripts()` at `src/sdk/tools/opencode-mcp-bridge.ts:139-155` is exported but has **zero callers** in the codebase.
+
+---
+
+## 🔴 Gap 4: --max-iterations CLI Flag Parsed Then Dropped
+
+### Root Cause
+
+The CLI flag is defined, parsed to an integer, and passed to `chatCommand()`, but the destructuring at `chat.ts:197-203` explicitly omits `maxIterations`. The workflow engine has a separate internal `maxIterations` pathway that reads from `definition.graphConfig?.maxIterations`, which is always `undefined` for Ralph (so it falls back to hardcoded `100`).
+
+### Files to Edit
+
+| File | Lines | What Needs to Change |
+|------|-------|---------------------|
+| `src/cli.ts` | 108 | Remove `--max-iterations <n>` flag definition |
+| `src/cli.ts` | 118 | Remove `--max-iterations` help text example |
+| `src/cli.ts` | 168 | Remove `maxIterations: parseInt(...)` from options object |
+| `src/commands/chat.ts` | 67 | Remove `maxIterations?: number` from `ChatCommandOptions` interface |
+| `README.md` | 310 | Remove `--max-iterations` from CLI flag reference table |
+
+### Complete Data Flow (Current — Broken)
+
+```
+CLI: --max-iterations <n>
+  → src/cli.ts:108 (flag defined, default "100")
+  → src/cli.ts:168 (parseInt → number)
+  → src/commands/chat.ts:67 (accepted by ChatCommandOptions interface)
+  → src/commands/chat.ts:197-203 (OMITTED from destructuring) ← DROPS HERE
+  ╳ Dead end
+
+Internal Workflow Path (completely separate, hardcoded to 100):
+  → src/workflows/executor.ts:109 (DEFAULT_MAX_ITERATIONS = 100)
+  → src/workflows/executor.ts:197 (definition.graphConfig?.maxIterations ?? 100)
+  → src/workflows/ralph/state.ts:148 (options?.maxIterations ?? 100)
+  → src/workflows/ralph/graph.ts:210 (state.iteration >= state.maxIterations)
+```
+
+### All References to maxIterations
+
+| File | Line | Usage |
+|------|------|-------|
+| `src/cli.ts` | 108 | Flag definition |
+| `src/cli.ts` | 118 | Help text example |
+| `src/cli.ts` | 168 | `parseInt(localOpts.maxIterations, 10)` |
+| `src/commands/chat.ts` | 67 | `ChatCommandOptions.maxIterations?: number` |
+| `src/commands/chat.ts` | 197-203 | Destructuring **omits** `maxIterations` |
+| `src/ui/commands/workflow-commands.ts` | 131 | `WorkflowGraphConfig.maxIterations?: number` |
+| `src/ui/commands/workflow-commands.ts` | 145 | `WorkflowStateParams.maxIterations: number` |
+| `src/ui/commands/registry.ts` | 203 | `WorkflowState.maxIterations?: number` |
+| `src/workflows/executor.ts` | 52-53 | `compileGraphConfig()` metadata |
+| `src/workflows/executor.ts` | 108-109 | `DEFAULT_MAX_ITERATIONS = 100` |
+| `src/workflows/executor.ts` | 197 | Reads from `definition.graphConfig?.maxIterations` |
+| `src/workflows/ralph/definition.ts` | 38 | Forwards `params.maxIterations` |
+| `src/workflows/ralph/state.ts` | 74, 79, 114, 118, 148, 205 | State interface, annotations, factory |
+| `src/workflows/ralph/graph.ts` | 210, 212 | Loop exit condition, builder config |
+| `src/workflows/graph/builder.ts` | 51, 669, 737, 748 | `LoopConfig`, builder defaults |
+| `src/workflows/graph/templates.ts` | 26, 38, 186, 206 | Template config interfaces |
+
+---
+
+## 🟡 Gap 5: Six Dead Modules
+
+### Summary Table
+
+| # | Module | File | Lines | Exports | Has Tests | Non-Test Imports |
+|---|--------|------|-------|---------|-----------|-----------------|
+| 1 | debug-subscriber | `src/events/debug-subscriber.ts` | 179 | 6 | ✅ | **0** |
+| 2 | tool discovery | `src/sdk/tools/discovery.ts` | 287 | 9 | ❌ | **0** |
+| 3 | file-lock | `src/utils/file-lock.ts` | 290 | 7 | ❌ | **0** |
+| 4 | merge | `src/utils/merge.ts` | 45 | 1 | ✅ | **0** |
+| 5 | pipeline-logger | `src/events/pipeline-logger.ts` | 68 | 3 | ✅ | **0** |
+| 6 | tree-hints | `src/ui/utils/background-agent-tree-hints.ts` | 43 | 3 | ✅ | **0** |
+
+### Module 1: debug-subscriber
+
+- **File:** `src/events/debug-subscriber.ts`
+- **Primary export:** `attachDebugSubscriber(bus: AtomicEventBus)` at line 153
+- **What it does:** File-based JSONL event logging gated on `ATOMIC_DEBUG=1`. Subscribes to `bus.onAll()`, serializes every `BusEvent` to `~/.local/share/atomic/log/events/` with 10-file rotation.
+- **Intended import point:** `src/ui/index.ts` after `AtomicEventBus` instantiation at line 240 (`const sharedBus = new AtomicEventBus()`), before `EventBusProvider` at line 740.
+
+### Module 2: tool discovery
+
+- **File:** `src/sdk/tools/discovery.ts`
+- **Primary export:** `registerCustomTools(client: CodingAgentClient)` at line 262
+- **What it does:** Scans `.atomic/tools/` directories, dynamically imports tool files, converts Zod schemas to JSON Schema, registers with client and ToolRegistry.
+- **Intended import point:** `src/commands/chat.ts` between client creation (line 243) and `client.start()` (line 251). See Gap 2 above.
+- **Note:** The barrel file `src/sdk/tools/index.ts` does not re-export from `discovery.ts` despite its JSDoc claiming it does.
+
+### Module 3: file-lock
+
+- **File:** `src/utils/file-lock.ts`
+- **Primary export:** `withLock(filePath, fn)` at line 213
+- **What it does:** File-based locking using `.lock` files with PID-based stale lock detection. `tryAcquireLock()` uses exclusive `wx` flag for atomic lock creation.
+- **Intended import point:** `src/telemetry/telemetry-file-io.ts` — though that file's comments (lines 42-48) note that OS-level `O_APPEND` atomicity was considered sufficient. Other candidates: any file performing concurrent writes to shared files.
+
+### Module 4: merge
+
+- **File:** `src/utils/merge.ts`
+- **Primary export:** `mergeJsonFile(sourcePath, destPath)` at line 21
+- **What it does:** Reads two JSON files, shallow-merges top-level keys with special handling for `mcpServers` sub-object to preserve user MCP entries while updating CLI-managed ones.
+- **Intended import point:** `src/commands/init.ts` — the `AgentConfig` type in `src/config.ts` has a `merge_files` field (line 23) populated with values like `[".mcp.json"]` for Claude (line 39) and `[".github/mcp-config.json"]` for Copilot (line 68). `mergeJsonFile()` was designed to replace `copyFile()` for files listed in `merge_files`.
+
+### Module 5: pipeline-logger
+
+- **File:** `src/events/pipeline-logger.ts`
+- **Primary export:** `pipelineLog(stage, action, data?)` at line 60
+- **What it does:** Conditional `console.debug()` logger gated on `ATOMIC_DEBUG=1`, caches env check. Emits `[Pipeline:<stage>]` prefixed messages for stages: EventBus, Dispatcher, Wire, Consumer, Subagent.
+- **Intended import points:** The five pipeline modules matching the `PipelineStage` type:
+  - `"EventBus"` → `src/events/event-bus.ts`
+  - `"Dispatcher"` → `src/events/batch-dispatcher.ts`
+  - `"Wire"` → `src/events/consumers/wire-consumers.ts`
+  - `"Consumer"` → `src/events/consumers/stream-pipeline-consumer.ts`
+  - `"Subagent"` → `src/events/adapters/subagent-adapter.ts`
+
+### Module 6: tree-hints
+
+- **File:** `src/ui/utils/background-agent-tree-hints.ts`
+- **Primary export:** `buildParallelAgentsHeaderHint(agents, showExpandHint)` at line 24
+- **What it does:** Builds status string for parallel-agents tree header with keyboard shortcut hints (`ctrl+f` / `ctrl+o`) based on background agent state.
+- **Intended import point:** `src/ui/components/parallel-agents-tree.tsx` or `src/ui/chat.tsx` — to generate the header text above the agent list in the sub-agent tree widget.
+
+---
+
+## 🟡 Gap 6: Six Unrendered UI Components
+
+### Summary Table
+
+| Component | Defined At | `parts/index.ts` | `components/index.ts` | `ui/index.ts` | PART_REGISTRY | JSX Rendered |
+|---|---|---|---|---|---|---|
+| `WorkflowStepPartDisplay` | `parts/workflow-step-part-display.tsx:25` | ❌ | ❌ | ❌ | ❌ | ❌ |
+| `UserQuestionInline` | `parts/user-question-inline.tsx:42` | ✅ line 16 | ❌ | ❌ | N/A | ❌ |
+| `FooterStatus` | `components/footer-status.tsx:99` | N/A | ✅ lines 130-132 | ❌ | N/A | ❌ |
+| `TimestampDisplay` | `components/timestamp-display.tsx:109` | N/A | ✅ lines 74-79 | ❌ | N/A | ❌ |
+| `StreamingBullet` | `chat.tsx:1152` | N/A | N/A | ✅ line 905 | N/A | ❌ |
+| `CodeBlock` | `code-block.tsx:187` | N/A | N/A | ✅ lines 925-932 | N/A | ❌ |
+
+### Component Details
+
+#### 1. WorkflowStepPartDisplay (`src/ui/components/parts/workflow-step-part-display.tsx:25`)
+- Renders `── Step: <name> <status> (<duration>) ──` inside a themed `<box>`
+- **Not in barrel exports**, **not in PART_REGISTRY**, type `WorkflowStepPart` not defined in `types.ts`
+- See Gap 1 for the full pipeline disconnection
+
+#### 2. UserQuestionInline (`src/ui/components/parts/user-question-inline.tsx:42`)
+- Full inline HITL question dialog with keyboard navigation (up/down/enter/escape/1-9), custom text input mode
+- Duplicates `UserQuestionDialog` (`src/ui/components/user-question-dialog.tsx:76`) which IS rendered at `chat.tsx:6008`
+- The `ToolPart` type in `src/ui/parts/types.ts:82-89` has a `pendingQuestion` field matching this component's `PendingQuestion` interface
+- **Intended context:** Inline alternative to the overlay `UserQuestionDialog`
+
+#### 3. FooterStatus (`src/ui/components/footer-status.tsx:99`)
+- Renders model ID, streaming indicator, verbose mode, queued count, permission mode, agent type joined by ` · `
+- **What's used instead:** `chat.tsx:6120-6166` hand-builds footer elements inline; `BackgroundAgentFooter` (`background-agent-footer.tsx:13`) uses `formatBackgroundAgentFooterStatus()`
+
+#### 4. TimestampDisplay (`src/ui/components/timestamp-display.tsx:109`)
+- Right-aligned display with timestamp, duration, and model ID joined by ` • `
+- **Intended context:** Inside `MessageBubble` in verbose mode
+
+#### 5. StreamingBullet (`src/ui/chat.tsx:1152`)
+- Animated `●`/`·` blinker at 500ms interval using `useState`/`setInterval`
+- **Intended context:** Prefix for streaming text parts in `TextPartDisplay`
+- Only real reference outside definition: test mock at `src/ui/index.protocol-ordering.test.ts:104`
+
+#### 6. CodeBlock (`src/ui/code-block.tsx:187`)
+- Renders bordered code with optional syntax highlighting via OpenTUI's `<code>` renderable
+- Exports helpers: `normalizeLanguage()`, `extractCodeBlocks()`, `hasCodeBlocks()`, `extractInlineCode()`
+- **Intended context:** Standalone code rendering alternative to OpenTUI's `<markdown>` internal code handling
+
+---
+
+## 🟡 Gap 7: Twelve Unconsumed Event Types
+
+### The Drop Point
+
+**`src/events/consumers/stream-pipeline-consumer.ts:126-181`** — The `mapToStreamPart()` switch handles exactly 5 event types. All other events hit `default: return null` at line 177 and are silently discarded.
+
+### Events WITH Active Consumers (16 of 28)
+
+| Bus Event Type | Consumer Mechanism |
+|---|---|
+| `stream.text.delta` | `mapToStreamPart()` → `text-delta` |
+| `stream.text.complete` | `mapToStreamPart()` → `text-complete` |
+| `stream.thinking.delta` | `mapToStreamPart()` → `thinking-meta` |
+| `stream.thinking.complete` | `chat.tsx:2808` `useBusSubscription` |
+| `stream.tool.start` | `mapToStreamPart()` → `tool-start` |
+| `stream.tool.complete` | `mapToStreamPart()` → `tool-complete` |
+| `stream.agent.start` | `chat.tsx:2832` `useBusSubscription` |
+| `stream.agent.update` | `chat.tsx:2889` `useBusSubscription` |
+| `stream.agent.complete` | `chat.tsx:2904` `useBusSubscription` |
+| `stream.session.start` | `wire-consumers.ts:78` (`correlation.startRun()`) |
+| `stream.session.idle` | `chat.tsx:2761` `useBusSubscription` |
+| `stream.session.error` | `chat.tsx:2770` `useBusSubscription` |
+| `stream.permission.requested` | `chat.tsx:3187` `useBusSubscription` |
+| `stream.human_input_required` | `chat.tsx:3200` `useBusSubscription` |
+| `stream.usage` | `chat.tsx:2774` `useBusSubscription` |
+| `workflow.task.statusChange` | `executor.ts:313` `bus.on()` |
+
+### Events WITHOUT Active Consumers (12 of 28)
+
+#### Category: Session Events (5)
+
+| # | Event Type | Payload | Emitted By | Intended Consumer |
+|---|---|---|---|---|
+| 1 | `stream.session.info` | `{infoType, message}` | OpenCode (`opencode-adapter.ts:1044`), Copilot (`copilot-adapter.ts:985`) | `chat.tsx` — parallels existing `stream.session.error` subscriber at line 2770 |
+| 2 | `stream.session.warning` | `{warningType, message}` | OpenCode (`opencode-adapter.ts:1066`), Copilot (`copilot-adapter.ts:1002`) | `chat.tsx` — parallels existing `stream.session.error` subscriber at line 2770 |
+| 3 | `stream.session.title_changed` | `{title}` | OpenCode (`opencode-adapter.ts:1088`), Copilot (`copilot-adapter.ts:1019`) | `chat.tsx` — update conversation title state |
+| 4 | `stream.session.truncation` | `{tokenLimit, tokensRemoved, messagesRemoved}` | OpenCode (`opencode-adapter.ts:957`), Copilot (`copilot-adapter.ts:1035`) | `chat.tsx` — context window usage display |
+| 5 | `stream.session.compaction` | `{phase, success?, error?}` | OpenCode (`opencode-adapter.ts:934`), Copilot (`copilot-adapter.ts:1053`) | `chat.tsx` — compaction lifecycle display |
+
+#### Category: Turn Lifecycle (2)
+
+| # | Event Type | Payload | Emitted By | Intended Consumer |
+|---|---|---|---|---|
+| 6 | `stream.turn.start` | `{turnId}` | OpenCode (`opencode-adapter.ts:980`), Copilot (`copilot-adapter.ts:936`) | `chat.tsx` — turn boundary tracking |
+| 7 | `stream.turn.end` | `{turnId}` | OpenCode (`opencode-adapter.ts:1001`), Copilot (`copilot-adapter.ts:952`) | `chat.tsx` — turn completion signal |
+
+#### Category: Tool Partial Results (1)
+
+| # | Event Type | Payload | Emitted By | Intended Consumer |
+|---|---|---|---|---|
+| 8 | `stream.tool.partial_result` | `{toolCallId, partialOutput}` | OpenCode (`opencode-adapter.ts:1022`), Copilot (`copilot-adapter.ts:968`) | `stream-pipeline-consumer.ts` → new `StreamPartEvent` type for streaming tool output |
+
+#### Category: Workflow Events (3)
+
+| # | Event Type | Payload | Emitted By | Intended Consumer |
+|---|---|---|---|---|
+| 9 | `workflow.step.start` | `{workflowId, nodeId, nodeName}` | `workflow-adapter.ts:57` via `executor.ts:346` | `stream-pipeline-consumer.ts` → `"workflow-step-start"` (reducer exists at `stream-pipeline.ts:987`) |
+| 10 | `workflow.step.complete` | `{workflowId, nodeId, status, result?}` | `workflow-adapter.ts:88` via `executor.ts:337,410` | `stream-pipeline-consumer.ts` → `"workflow-step-complete"` (reducer exists at `stream-pipeline.ts:1002`) |
+| 11 | `workflow.task.update` | `{workflowId, tasks[]}` | `workflow-adapter.ts:114` via `executor.ts:373` | `stream-pipeline-consumer.ts` → `"task-list-update"` (reducer exists at `stream-pipeline.ts:1021`) |
+
+#### Category: Skill Events (1)
+
+| # | Event Type | Payload | Emitted By | Intended Consumer |
+|---|---|---|---|---|
+| 12 | `stream.skill.invoked` | `{skillName, skillPath?}` | OpenCode (`opencode-adapter.ts:910`), Copilot (`copilot-adapter.ts:784`) | `chat.tsx` — skill invocation display |
+
+### Files to Edit for Workflow Event Wiring (Events 9-11)
+
+These three events have **ready receivers** in the reducer but no sender in the consumer:
+
+| File | Lines | What Needs to Change |
+|------|-------|---------------------|
+| `src/events/consumers/stream-pipeline-consumer.ts` | 126-182 | Add `case "workflow.step.start"`, `case "workflow.step.complete"`, `case "workflow.task.update"` to `mapToStreamPart()` switch |
+
+The reducer at `src/ui/parts/stream-pipeline.ts` already handles the corresponding `StreamPartEvent` types:
+- `"workflow-step-start"` at line 987-999
+- `"workflow-step-complete"` at line 1002-1019
+- `"task-list-update"` at line 1021-1044
+
+### Emission Source Matrix
+
+| Event Type | Claude | OpenCode | Copilot | Workflow Adapter |
+|---|---|---|---|---|
+| `stream.session.info` | ✗ | ✓ | ✓ | ✗ |
+| `stream.session.warning` | ✗ | ✓ | ✓ | ✗ |
+| `stream.session.title_changed` | ✗ | ✓ | ✓ | ✗ |
+| `stream.session.truncation` | ✗ | ✓ | ✓ | ✗ |
+| `stream.session.compaction` | ✗ | ✓ | ✓ | ✗ |
+| `stream.turn.start` | ✗ | ✓ | ✓ | ✗ |
+| `stream.turn.end` | ✗ | ✓ | ✓ | ✗ |
+| `stream.tool.partial_result` | ✗ | ✓ | ✓ | ✗ |
+| `workflow.step.start` | ✗ | ✗ | ✗ | ✓ |
+| `workflow.step.complete` | ✗ | ✗ | ✗ | ✓ |
+| `workflow.task.update` | ✗ | ✗ | ✗ | ✓ |
+| `stream.skill.invoked` | ✗ | ✓ | ✓ | ✗ |
+
+**Note:** The Claude adapter does not emit any of the 12 unconsumed event types.
+
+---
+
+## Architecture Documentation
+
+### Event Bus Pipeline Architecture
+
+```
+SDK Events → SDK Adapter (Claude/OpenCode/Copilot)
+  → bus.publish(BusEvent)
+    → AtomicEventBus (src/events/event-bus.ts:57)
+      ├── bus.on("type", handler)        [typed subscribers — 10 events]
+      ├── bus.onAll(handler)             [wireConsumers — src/events/consumers/wire-consumers.ts:70]
+      │     → BatchDispatcher (16ms frame-aligned batching)
+      │       → CorrelationService.enrich() (10 event types handled, rest passthrough)
+      │         → StreamPipelineConsumer.mapToStreamPart() (5 event types → StreamPartEvent, rest → null)
+      │           → applyStreamPartEvent() reducer → Part[] → PART_REGISTRY → React render
+      └── bus.onAll(handler)             [debug-subscriber.ts:165 — DEAD MODULE, never attached]
+```
+
+### Key Files Index
+
+| Category | File | Role |
+|----------|------|------|
+| **Event Types** | `src/events/bus-events.ts` | All 28 `BusEventType` definitions and payloads |
+| **Event Bus** | `src/events/event-bus.ts` | `AtomicEventBus` pub/sub implementation |
+| **Batch Dispatcher** | `src/events/batch-dispatcher.ts` | 16ms frame-aligned event batching |
+| **Wire Consumers** | `src/events/consumers/wire-consumers.ts` | Connects bus → dispatcher → pipeline |
+| **Correlation** | `src/events/consumers/correlation-service.ts` | Enriches events with agent/tool IDs |
+| **Pipeline Consumer** | `src/events/consumers/stream-pipeline-consumer.ts` | Maps BusEvent → StreamPartEvent |
+| **Stream Pipeline** | `src/ui/parts/stream-pipeline.ts` | `applyStreamPartEvent()` reducer |
+| **Part Types** | `src/ui/parts/types.ts` | `Part` union type (8 members, missing `WorkflowStepPart`) |
+| **Part Registry** | `src/ui/components/parts/registry.tsx` | `PART_REGISTRY` (8 entries, missing `workflow-step`) |
+| **Adapters** | `src/events/adapters/claude-adapter.ts` | Claude SDK → BusEvent |
+| **Adapters** | `src/events/adapters/opencode-adapter.ts` | OpenCode SDK → BusEvent |
+| **Adapters** | `src/events/adapters/copilot-adapter.ts` | Copilot SDK → BusEvent |
+| **Adapters** | `src/events/adapters/workflow-adapter.ts` | Workflow executor → BusEvent |
+| **Chat Command** | `src/commands/chat.ts` | Init sequence (client creation → start) |
+| **CLI Entry** | `src/cli.ts` | Flag definitions, command routing |
+| **Custom Tools** | `src/sdk/tools/discovery.ts` | Tool discovery + registration pipeline |
+| **MCP Bridge** | `src/sdk/tools/opencode-mcp-bridge.ts` | OpenCode tool bridge (placeholder) |
+| **Executor** | `src/workflows/executor.ts` | Graph workflow execution |
+| **Chat TUI** | `src/ui/chat.tsx` | Main UI with `useBusSubscription` hooks |
+
+---
+
+## Historical Context (from research/)
+
+- `research/docs/2026-02-27-workflow-tui-rendering-unification.md` — Documents the fundamental difference between main TUI chat rendering (event-driven pipeline) and workflow executor rendering (static `addMessage()` calls). Identifies that workflow sub-agents bypass the streaming pipeline entirely.
+- `research/docs/2026-02-28-workflow-issues-research.md` — Detailed research on sub-agent tree streaming, code-review timing, parallel task execution, and streaming delay issues in the Ralph workflow.
+- `research/docs/2026-02-25-workflow-sdk-design.md` — Workflow SDK design patterns and architecture.
+- `research/docs/2026-02-25-graph-execution-engine.md` — Graph execution engine technical documentation.
+- `research/docs/2026-02-09-165-custom-tools-directory.md` — Custom tools directory research.
+- `specs/custom-tools-directory.md:853` — Phase 3 checklist: "Wire `registerCustomTools()` into `src/commands/chat.ts`" (unchecked).
+
+## Related Research
+
+- `research/docs/2026-02-26-streaming-architecture-event-bus-migration.md`
+- `research/docs/2026-02-26-streaming-event-bus-spec-audit.md`
+- `research/docs/2026-02-25-workflow-registration-flow.md`
+- `research/docs/2026-02-16-opentui-rendering-architecture.md`
+- `research/docs/2026-02-15-sub-agent-tree-status-lifecycle-sdk-parity.md`
+
+## Open Questions
+
+1. For the OpenCode MCP bridge (Gap 3), which approach is preferred: (a) adopting Claude's in-process MCP pattern using `createSdkMcpServer()`, (b) implementing IPC between the MCP script and main process, or (c) a different approach specific to OpenCode's architecture?
+2. For the 12 unconsumed events (Gap 7), should all events get consumers at once, or should priority be given to the 3 workflow events (9-11) that already have reducer handlers?
+3. For the 6 unrendered components (Gap 6), should components like `FooterStatus` replace the hand-built footer in `chat.tsx:6120-6166`, or should the existing inline approach remain and the component be removed?
+4. For the dead modules (Gap 5), should all 6 be activated simultaneously, or should they be prioritized based on impact?
diff --git a/research/docs/2026-02-28-workflow-issues-research.md b/research/docs/2026-02-28-workflow-issues-research.md
new file mode 100644
index 0000000000..757671e578
--- /dev/null
+++ b/research/docs/2026-02-28-workflow-issues-research.md
@@ -0,0 +1,686 @@
+---
+date: 2026-02-28 00:48:00 UTC
+researcher: Copilot (Claude Opus 4.6)
+git_commit: aed66d9f7cb82d4eef22c4d717d57c559fe747e4
+branch: lavaman131/feature/workflow-sdk
+repository: atomic
+topic: "Workflow Issues: Sub-Agent Tree Streaming, Code-Review Timing, and Parallel Task Execution"
+tags: [research, codebase, workflows, ralph, sub-agent-tree, parallel-execution, code-review, event-pipeline, task-list-ui, blink-animation, stream-finalization, completion-delay]
+status: complete
+last_updated: 2026-02-28
+last_updated_by: Copilot (Claude Opus 4.6)
+last_updated_note: "Added Issue 4: Task list blinker for active tasks, Issue 5: Streaming delay after TODO completion"
+---
+
+# Research: Workflow Issues
+
+## Research Question
+
+Research to resolve three issues in the workflow system:
+
+1. **Sub-agent tree state stuck at "Initializing..."** — not streaming tool calls or tool call counts
+2. **Code-review stage timing** — should run only at the end of the entire workflow, not after each task
+3. **Parallel task execution** — multiple runnable tasks should execute concurrently instead of sequentially
+4. **Task list blinker for active tasks** — visual indicator for tasks being actively worked on
+5. **Streaming delay after TODO completion** — delay between tasks marked complete and final duration/tokens summary appearing
+
+## Summary
+
+### Issue 1: Sub-Agent Tree "Initializing..." State
+
+The "Initializing..." text in the sub-agent tree UI persists until `agent.toolUses` becomes a number greater than 0. The data flow for tool call counts follows a **dual-channel architecture**: agent lifecycle events (`stream.agent.start/update/complete`) flow through direct `useBusSubscription` hooks in `chat.tsx`, while tool content events (`stream.tool.start/complete`) flow through the `StreamPipelineConsumer` pipeline. The `SubagentToolTracker` publishes `stream.agent.update` events with incrementing `toolUses` counts on each `onToolStart()` call. If these events are not reaching the UI, the issue lies in one of several identified chokepoints: event coalescing dropping updates, the `AgentPart` not yet being created when tool events arrive (causing silent drops), or the `useBusSubscription` handler not correctly merging `toolUses` into the `parallelAgents` React state.
+
+### Issue 2: Code-Review Timing
+
+The code-review stage (`reviewer` node) **already runs only once, after the entire worker loop completes** — not after each individual task. The graph topology is: `planner → parse-tasks → [loop: select-ready-tasks → worker] → reviewer → conditional fixer → END`. The loop exit edge from `loop_check_N` to `reviewer` is only taken when the `until` condition evaluates to true (all tasks completed/errored, or max iterations reached). This issue may stem from a misunderstanding of the current behavior, or from a different workflow configuration not captured in the main `graph.ts`.
+
+### Issue 3: Parallel Task Execution
+
+The current system executes tasks **strictly one at a time**. Two layers enforce this:
+1. **Graph engine** (`compiled.ts`): Processes nodes sequentially via a FIFO queue — `nodeQueue.shift()` dequeues one node, executes it, then pushes next nodes.
+2. **Worker node** (`graph.ts:154`): Takes only `ready[0]` — the first ready task — even though `getReadyTasks()` may return multiple tasks with satisfied dependencies.
+
+True parallelism exists only _within_ individual nodes via `spawnSubagentParallel` (wired in `executor.ts:235-263`), but the Ralph worker node does not use it.
+
+### Issue 4: Task List Blinker for Active Tasks
+
+The task list widget **already has a blinking indicator** for in-progress tasks. The `AnimatedBlinkIndicator` component (`animated-blink-indicator.tsx`) alternates between `●` and `·` at 500ms and is used by `TaskListIndicator` (`task-list-indicator.tsx:146-149`) for any task with `status === "in_progress"`. However, a potential gap exists: the Ralph workflow's worker node (`graph.ts:141-178`) does not explicitly set task status to `"in_progress"` before spawning a sub-agent. Tasks go directly from `"pending"` → `"completed"`/`"error"` unless the spawned sub-agent writes `status: "in_progress"` to `tasks.json` via TodoWrite during its execution. This means the blinker may not activate for actively-worked-on tasks if the sub-agent doesn't set this intermediate status.
+
+### Issue 5: Streaming Delay After TODO Completion
+
+There is a multi-second delay between the last task being marked complete and the final "⣿ Composed for X · ↓ Y tokens" summary appearing. The pipeline from stream end to summary involves **five identified sources of delay**: (1) **Deferred completion** — if `handleStreamComplete()` fires while sub-agents are still "running" in React state, finalization is deferred with a 30-second safety timeout (`chat.tsx:2527`); resolution requires agent-complete events to flow through the bus → 16ms batch → React state update → re-render → `useEffect` → `setTimeout(…, 0)`; (2) **SDK `session.idle` timing** — for OpenCode/Copilot adapters, the `session.idle` event is SDK-internal; the UI waits for the SDK to signal idle, which may take seconds after the last meaningful action; (3) **`shouldShowCompletionSummary` gate** — requires `!message.streaming && !hasActiveBackgroundAgents && durationMs >= 1000`; background agents that haven't been terminated yet block this; (4) **File I/O in graph loop** — `await saveTasksToSession()` performs atomic file writes in the critical path between node completion and stream finalization; (5) **React state update batching** — multiple state updates (`setMessagesWindowed`, `setParallelAgents`, `setIsStreaming`) may require multiple render cycles to converge.
+
+---
+
+## Detailed Findings
+
+### Issue 1: Sub-Agent Tree Not Streaming Tool Calls
+
+#### 1.1 Where "Initializing..." Comes From
+
+**Primary rendering path** — `AgentRow` in `parallel-agents-tree.tsx:570-633`:
+
+```typescript
+// parallel-agents-tree.tsx:573
+const isRunning = agent.status === "running" || agent.status === "pending";
+
+// parallel-agents-tree.tsx:579-585
+if (isRunning) {
+  if (agent.toolUses !== undefined && agent.toolUses > 0) {
+    subStatusText = `${agent.name}: (${agent.toolUses} tool uses)`;
+  } else {
+    subStatusText = `Initializing ${agent.name}…`;
+  }
+}
+```
+
+The gate condition is `agent.toolUses !== undefined && agent.toolUses > 0`. Any agent with `toolUses` of `undefined` or `0` shows "Initializing…".
+
+**Secondary path** — `transcript-formatter.ts:216-218` mirrors this exact logic.
+
+#### 1.2 How `toolUses` Gets Populated
+
+The complete data flow for tool use counts:
+
+1. **Sub-agent stream starts** → `SubagentStreamAdapter` constructor (`subagent-adapter.ts:88-97`) creates `SubagentToolTracker`, calls `registerAgent(agentId)` which initializes `{ toolCount: 0 }`.
+
+2. **Tool use detected** → `handleToolUse()` (`subagent-adapter.ts:266-313`) calls `this.toolTracker.onToolStart(this.agentId, toolName)` at line 297.
+
+3. **Tracker emits update** → `SubagentToolTracker.onToolStart()` (`subagent-tool-tracker.ts:60-66`) increments `toolCount`, publishes `stream.agent.update` to the bus with `data.toolUses = state.toolCount`.
+
+4. **Bus → BatchDispatcher** → Event is coalesced by key `agent.update:${agentId}` (`coalescing.ts:31-34`), keeping only the latest per batch window (~16ms).
+
+5. **Consumer pipeline** → `StreamPipelineConsumer.mapToStreamPart()` returns `null` for `stream.agent.update` (line 214 default case) — **this event type is NOT mapped to a `StreamPartEvent`**.
+
+6. **Direct bus subscription** → `chat.tsx:2882-2895` uses `useBusSubscription("stream.agent.update", ...)` to directly subscribe to the bus. When fired, calls `setParallelAgents()` to merge `data.toolUses` and `data.currentTool` into the matching agent in React state.
+
+7. **React state → Message baking** → `useEffect` at `chat.tsx:3209-3266` watches `parallelAgents` and calls `applyStreamPartEvent(msg, { type: "parallel-agents", agents })` to bake updated agents into the streaming message's `AgentPart`.
+
+8. **AgentRow re-renders** → If `toolUses > 0`, shows tool count instead of "Initializing…".
+
+#### 1.3 Identified Chokepoints
+
+| Chokepoint | Location | Description |
+|---|---|---|
+| **Event coalescing** | `coalescing.ts:31-34` | `stream.agent.update` events are coalesced per agent per batch window. If the batch window captures no updates (e.g., timing issue), no event reaches the subscriber. |
+| **Dual-channel race condition** | `stream-pipeline.ts:917-918` | Tool/text events with `agentId` are routed to `AgentPart.inlineParts` via `routeToAgentInlineParts()`. If the `AgentPart` hasn't been created yet (because `parallel-agents` event hasn't been baked via the React `useEffect` path), these events are **silently dropped**. |
+| **`useBusSubscription` bypass** | `chat.tsx:2882-2895` | The `stream.agent.update` handler bypasses the `StreamPipelineConsumer` entirely. If this hook is not mounted, or if the event never reaches it (filtered by `CorrelationService.isOwnedEvent()`), `toolUses` never updates. |
+| **Ownership check** | `wire-consumers.ts:83-86` | Events must pass `correlation.isOwnedEvent(event)` which checks `event.runId` matches `_activeRunId`. If the sub-agent's `runId` differs from the active run, events are dropped. |
+| **Schema validation** | `event-bus.ts:140-152` | If the `stream.agent.update` event data doesn't match the Zod schema (`BusEventSchemas`), the event is silently dropped. |
+
+#### 1.4 Key Code References
+
+| File | Lines | Function |
+|---|---|---|
+| `src/ui/components/parallel-agents-tree.tsx` | 570-633 | `AgentRow` — renders "Initializing…" or tool count |
+| `src/ui/components/parallel-agents-tree.tsx` | 32-63 | `ParallelAgent` interface — `toolUses?: number` at line 56 |
+| `src/events/adapters/subagent-tool-tracker.ts` | 60-66 | `onToolStart()` — increments count, publishes update |
+| `src/events/adapters/subagent-tool-tracker.ts` | 95-108 | `publishUpdate()` — constructs `stream.agent.update` event |
+| `src/events/adapters/subagent-adapter.ts` | 266-313 | `handleToolUse()` — calls `toolTracker.onToolStart()` |
+| `src/events/coalescing.ts` | 31-34 | Coalescing key for `stream.agent.update` |
+| `src/events/consumers/stream-pipeline-consumer.ts` | 214 | `mapToStreamPart()` returns `null` for `stream.agent.update` |
+| `src/ui/parts/stream-pipeline.ts` | 838-858 | `routeToAgentInlineParts()` — drops events if agent not in parts |
+| `src/ui/parts/stream-pipeline.ts` | 917-918 | Silent drop when agent-scoped routing fails |
+
+---
+
+### Issue 2: Code-Review Stage Timing in Ralph Workflow
+
+#### 2.1 Current Graph Topology
+
+The Ralph workflow graph (`graph.ts:98-236`) has the following edge structure:
+
+```
+planner → parse-tasks → loop_start_N → select-ready-tasks → worker → loop_check_N
+                                              ↑                           │
+                                              └───── (continue) ──────────┘
+                                                                          │
+                                                                    (exit) ↓
+                                                                      reviewer → decision_N
+                                                                                    │
+                                                         ┌──── (has findings) ──────┘
+                                                         ↓                          │
+                                                       fixer                  (no findings)
+                                                         │                          │
+                                                         └────────→ merge_N ←───────┘
+                                                                       │
+                                                                     (END)
+```
+
+#### 2.2 Code-Review Is Already a Post-Loop Step
+
+The reviewer node is connected by an edge from `loop_check_N` that is taken **only when the loop exit condition is met** (`graph.ts:181-184`):
+
+```typescript
+until: (state) =>
+  state.tasks.every((t) => t.status === "completed" || t.status === "error") ||
+  state.iteration >= state.maxIterations ||
+  !hasActionableTasks(state.tasks),
+```
+
+The builder generates a loop-continue edge (`builder.ts:722-731`) with condition `!config.until(state) && iteration < max`. When this condition is false, the loop exits, and the fall-through edge to `reviewer` is taken.
+
+The executor (`executor.ts:268-332`) does **not** contain any task-specific iteration logic — it simply iterates over graph steps via `for await (const step of streamGraph(compiled, { initialState }))`. The task loop is entirely handled by the graph's `loop` construct.
+
+#### 2.3 Single Reviewer Execution
+
+The `reviewer` node has exactly one incoming edge (from `loop_check_N`) and exactly one outgoing edge (to `decision_N`). It executes precisely once per workflow run, after the loop completes.
+
+#### 2.4 Key Code References
+
+| File | Lines | Function |
+|---|---|---|
+| `src/workflows/ralph/graph.ts` | 98-236 | `createRalphWorkflow()` — full graph definition |
+| `src/workflows/ralph/graph.ts` | 181-184 | Loop `until` condition |
+| `src/workflows/ralph/graph.ts` | 190-208 | Reviewer node definition |
+| `src/workflows/ralph/graph.ts` | 210-234 | Conditional fixer logic |
+| `src/workflows/graph/builder.ts` | 647-737 | `.loop()` method — generates loop structure |
+| `src/workflows/graph/builder.ts` | 722-731 | Loop-continue edge condition |
+| `src/workflows/graph/compiled.ts` | 758-787 | `getNextNodes()` — edge evaluation |
+| `src/workflows/executor.ts` | 268-332 | Main execution loop (graph-agnostic) |
+
+---
+
+### Issue 3: Sequential vs. Parallel Task Execution
+
+#### 3.1 Graph Engine Is Sequential
+
+The `GraphExecutor.streamSteps()` method (`compiled.ts:322-569`) uses a FIFO queue and processes **one node at a time**:
+
+```typescript
+// compiled.ts:367
+while (nodeQueue.length > 0 && stepCount < maxSteps) {
+  // compiled.ts:383
+  const currentNodeId = nodeQueue.shift()!;
+  // ... execute single node ...
+  // compiled.ts:518
+  const nextNodes = this.getNextNodes(currentNodeId, state, result);
+  // compiled.ts:521
+  nodeQueue.push(...nextNodes);
+}
+```
+
+Even when `getNextNodes()` returns multiple targets (e.g., from parallel edges), they are pushed to the queue and executed sequentially.
+
+The `parallelNode` factory (`nodes.ts:967-1008`) returns `goto: branches` (line 1004) which pushes all branch IDs into the queue, but they still execute one at a time through the while loop.
+
+#### 3.2 Worker Node Processes One Task Per Iteration
+
+In `graph.ts:141-178`, the worker node's execute function:
+
+```typescript
+// graph.ts:154 — only the first ready task
+const task = ready[0];
+```
+
+Despite `getReadyTasks()` (`graph.ts:57-73`) returning all tasks whose dependencies are satisfied, the worker only processes the first one. After processing, all `currentTasks` are marked as completed/error based on the single spawn result (`graph.ts:168-174`).
+
+#### 3.3 Available Parallelism Infrastructure
+
+The runtime does have parallel spawning capability:
+
+1. **`spawnSubagentParallel`** — wired in `executor.ts:235-263`:
+   ```typescript
+   // executor.ts:247
+   compiled.config.runtime.spawnSubagentParallel = async (configs) => {
+     return spawnSubagentParallel(configs);
+   };
+   ```
+
+2. **`spawnSubagentParallel` from context** — available via `context.spawnSubagentParallel` (set at `executor.ts:203`), which supports concurrent agent execution.
+
+3. **`getReadyTasks()`** (`graph.ts:57-73`) — already correctly identifies all tasks whose `blockedBy` dependencies are satisfied. It returns the full array of ready tasks, not just one.
+
+However, the worker node does not use `spawnSubagentParallel`. It calls `spawnSubagent` (singular) with `ready[0]`.
+
+#### 3.4 Dependency Checking Logic
+
+`getReadyTasks()` (`graph.ts:57-73`):
+1. Builds a `completedIds` set: collects IDs of all tasks where status is `"completed"`, `"complete"`, or `"done"`. IDs are normalized (trimmed, lowercased, `#` prefix stripped).
+2. A task is "ready" if:
+   - `task.status === "pending"`
+   - All entries in `task.blockedBy` (also normalized) are present in `completedIds`
+
+`hasActionableTasks()` (`graph.ts:78-84`):
+- Returns `true` if any task is `"in_progress"` or is a pending task that would appear in `getReadyTasks()`
+- Used as a deadlock detector for the loop exit condition
+
+#### 3.5 Key Code References
+
+| File | Lines | Function |
+|---|---|---|
+| `src/workflows/graph/compiled.ts` | 322-569 | `streamSteps()` — sequential FIFO node execution |
+| `src/workflows/graph/compiled.ts` | 367 | Main while loop — one node at a time |
+| `src/workflows/graph/compiled.ts` | 383 | `nodeQueue.shift()!` — dequeue single node |
+| `src/workflows/graph/compiled.ts` | 518-521 | `getNextNodes()` + `push()` — sequential queuing |
+| `src/workflows/graph/nodes.ts` | 967-1008 | `parallelNode()` — returns `goto: branches` (still sequential) |
+| `src/workflows/ralph/graph.ts` | 141-178 | Worker node — processes `ready[0]` only |
+| `src/workflows/ralph/graph.ts` | 154 | `const task = ready[0]` — single task selection |
+| `src/workflows/ralph/graph.ts` | 57-73 | `getReadyTasks()` — finds all ready tasks |
+| `src/workflows/ralph/graph.ts` | 78-84 | `hasActionableTasks()` — deadlock detection |
+| `src/workflows/executor.ts` | 235-263 | `spawnSubagentParallel` wiring — exists but unused by Ralph worker |
+
+---
+
+## Architecture Documentation
+
+### Event Pipeline Architecture
+
+```
+SDK Stream (AsyncIterable/EventEmitter)
+    │
+    ▼
+SDK Adapter (claude/copilot/subagent-adapter.ts)
+    │ Normalizes SDK events to BusEvent types
+    │ Creates SubagentToolTracker for tool counting
+    ▼
+AtomicEventBus (event-bus.ts)
+    │ Validates via Zod schemas
+    │ Dispatches to typed + wildcard handlers
+    ▼
+BatchDispatcher (batch-dispatcher.ts)
+    │ ~16ms batching, coalescing by key
+    │ Double-buffer swap for flushing
+    ▼
+wireConsumers pipeline (wire-consumers.ts)
+    │ Filters: isOwnedEvent()
+    │ Enriches: CorrelationService.enrich()
+    │ Suppresses: suppressFromMainChat
+    ▼
+StreamPipelineConsumer (stream-pipeline-consumer.ts)
+    │ Maps BusEvent → StreamPartEvent
+    │ NOTE: stream.agent.update → null (NOT mapped)
+    ▼
+useStreamConsumer hook (hooks.ts)
+    │ Forwards StreamPartEvent[] to chat.tsx
+    ▼
+applyStreamPartEvent reducer (stream-pipeline.ts)
+    │ Mutates ChatMessage with Parts
+    ▼
+React components render Parts
+```
+
+**Parallel channel for agent lifecycle:**
+```
+AtomicEventBus
+    │
+    ▼
+useBusSubscription("stream.agent.start/update/complete") in chat.tsx
+    │ Direct bus subscription (bypasses BatchDispatcher/Consumer pipeline)
+    │ Updates parallelAgents React state
+    ▼
+useEffect watches parallelAgents → bakes into ChatMessage.parts
+    │ Creates/updates AgentPart entries
+    ▼
+ParallelAgentsTree component renders agent rows
+```
+
+### Workflow Graph Execution Architecture
+
+```
+WorkflowDefinition + GraphBuilder API
+    │
+    ▼
+CompiledGraph (nodes: Map, edges: Edge[], startNode, endNodes)
+    │
+    ▼
+GraphExecutor.streamSteps() — FIFO queue, one node at a time
+    │ Initialize: nodeQueue = [startNode]
+    │ Loop: shift() → execute → mergeState → getNextNodes() → push()
+    │ Exit: current is endNode AND queue empty
+    ▼
+executeWorkflow() — iterates streamGraph() steps
+    │ Wires runtime (spawnSubagent, spawnSubagentParallel)
+    │ Syncs task state to UI after each step
+    ▼
+Results
+```
+
+### Ralph Workflow Phase Architecture
+
+```
+Phase 1: Planning
+  planner (sub-agent) → parse-tasks (tool)
+
+Phase 2: Implementation Loop
+  select-ready-tasks (tool) → worker (sub-agent, 1 task/iteration)
+  ↑ loop continues until all tasks done or max iterations
+
+Phase 3: Review & Fix
+  reviewer (sub-agent) → conditional fixer (sub-agent, uses "debugger" agent)
+```
+
+---
+
+## Code References
+
+- `src/workflows/executor.ts` — Generic workflow executor, graph-agnostic
+- `src/workflows/ralph/graph.ts` — Ralph workflow graph definition
+- `src/workflows/ralph/definition.ts` — Ralph workflow metadata
+- `src/workflows/ralph/state.ts` — Ralph state shape and reducers
+- `src/workflows/ralph/prompts.ts` — Prompt templates for all Ralph stages
+- `src/workflows/graph/compiled.ts` — Graph execution engine (FIFO queue)
+- `src/workflows/graph/builder.ts` — Fluent graph builder API
+- `src/workflows/graph/nodes.ts` — Node factory functions
+- `src/ui/components/parallel-agents-tree.tsx` — Sub-agent tree rendering
+- `src/ui/parts/stream-pipeline.ts` — Stream event reducer
+- `src/ui/parts/store.ts` — Parts store utilities
+- `src/events/adapters/subagent-adapter.ts` — Sub-agent event adapter
+- `src/events/adapters/subagent-tool-tracker.ts` — Tool call counting
+- `src/events/adapters/claude-adapter.ts` — Claude SDK adapter
+- `src/events/adapters/copilot-adapter.ts` — Copilot SDK adapter
+- `src/events/adapters/workflow-adapter.ts` — Workflow event adapter
+- `src/events/bus-events.ts` — Event type definitions
+- `src/events/event-bus.ts` — Event bus implementation
+- `src/events/batch-dispatcher.ts` — Batched event dispatching
+- `src/events/coalescing.ts` — Event coalescing logic
+- `src/events/consumers/wire-consumers.ts` — Consumer wiring
+- `src/events/consumers/correlation-service.ts` — Event correlation
+- `src/events/consumers/stream-pipeline-consumer.ts` — Stream pipeline consumer
+- `src/events/hooks.ts` — React event hooks
+- `src/ui/chat.tsx` — Main chat component with agent state management
+
+## Historical Context (from research/)
+
+- `research/docs/2026-02-25-ralph-workflow-implementation.md` — Prior research on Ralph implementation
+- `research/docs/2026-02-27-workflow-tui-rendering-unification.md` — TUI rendering unification research
+- `research/docs/2026-02-15-subagent-event-flow-diagram.md` — Sub-agent event flow diagram
+- `research/docs/2026-02-15-subagent-premature-completion-investigation.md` — Sub-agent premature completion investigation
+- `research/docs/2026-02-16-sub-agent-tree-inline-state-lifecycle-research.md` — Sub-agent tree inline state lifecycle
+- `research/docs/2026-02-23-sdk-subagent-api-research.md` — SDK sub-agent API research
+- `research/docs/2026-02-12-sub-agent-sdk-integration-analysis.md` — Sub-agent SDK integration analysis
+- `research/ralph-workflow.md` — Original issue description for these three workflow issues
+
+## Related Research
+
+- `research/docs/2026-02-25-unified-workflow-execution-research.md` — Unified workflow execution patterns
+- `research/docs/2026-02-25-workflow-sdk-standardization.md` — Workflow SDK standardization
+- `research/docs/2026-02-05-pluggable-workflows-sdk-design.md` — Pluggable workflow SDK design
+
+---
+
+### Issue 4: Task List Blinker for Active Tasks
+
+#### 4.1 Current State — Already Implemented
+
+The task list widget **already has a blinking indicator for in-progress tasks**. The `TaskListIndicator` component (`task-list-indicator.tsx:146-149`) renders an `AnimatedBlinkIndicator` for any task with `status === "in_progress"`:
+
+```typescript
+// task-list-indicator.tsx:146-149
+{isActive ? (
+  <AnimatedBlinkIndicator color={color} speed={500} />
+) : (
+  <span style={{ fg: textColor }}>{icon}</span>
+)}
+```
+
+Where `isActive` is `status === "in_progress"` (line 115).
+
+The `AnimatedBlinkIndicator` (`animated-blink-indicator.tsx:1-33`) alternates between `●` (STATUS.active) and `·` (MISC.separator) every 500ms, colored in `themeColors.accent` (teal: `#94e2d5` dark / `#179299` light).
+
+#### 4.2 Animation Architecture
+
+The canonical blink component uses React state and `setInterval`:
+
+```typescript
+// animated-blink-indicator.tsx:16-33
+export function AnimatedBlinkIndicator({ color, speed = 500 }) {
+  const [visible, setVisible] = useState(true);
+  useEffect(() => {
+    const interval = setInterval(() => setVisible((prev) => !prev), speed);
+    return () => clearInterval(interval);
+  }, [speed]);
+  return <span style={{ fg: color }}>{visible ? STATUS.active : MISC.separator}</span>;
+}
+```
+
+#### 4.3 When Tasks Enter "in_progress" Status
+
+Tasks transition to `in_progress` when agents update the `tasks.json` file via TodoWrite. The data flow is:
+
+1. Agent calls TodoWrite with `status: "in_progress"` for a task
+2. `tasks.json` is written to disk in the workflow session directory
+3. `watchTasksJson()` (`workflow-commands.ts:719`) detects the file change
+4. `TaskListPanel` (`task-list-panel.tsx:157-179`) parses, normalizes via `normalizeTaskItem()`, sorts topologically
+5. `TaskListIndicator` renders each task — `in_progress` tasks get the `AnimatedBlinkIndicator`
+
+#### 4.4 Status Visual Summary
+
+| Status | Icon | Color | Animation |
+|---|---|---|---|
+| `pending` | `○` (White Circle) | `muted` (dim gray) | Static |
+| `in_progress` | `●` ↔ `·` (blink) | `accent` (teal) | **AnimatedBlinkIndicator at 500ms** |
+| `completed` | `✓` (Check Mark) | `success` (green) | Static |
+| `error` | `✗` (Ballot X) | `error` (red) | Static, with `[FAILED]` label |
+
+#### 4.5 Status Aliases
+
+The `TASK_STATUS_ALIASES` map (`task-status.ts:19-37`) normalizes many runtime values to canonical statuses:
+
+| Aliases → | Canonical |
+|---|---|
+| `pending`, `todo`, `open`, `not_started` | `"pending"` |
+| `in_progress`, `inprogress`, `doing`, `running`, `active` | `"in_progress"` |
+| `completed`, `complete`, `done`, `success`, `succeeded` | `"completed"` |
+| `error`, `failed`, `failure` | `"error"` |
+
+#### 4.6 Other Blink Patterns in the Codebase
+
+The same blink pattern is used across the UI:
+
+| Component | Location | Context |
+|---|---|---|
+| `AnimatedBlinkIndicator` | `animated-blink-indicator.tsx` | Shared reusable component |
+| `TaskListIndicator` | `task-list-indicator.tsx:147` | In-progress task items |
+| `ToolResult` / `StatusIndicator` | `tool-result.tsx:81` | Running tool executions |
+| `StreamingBullet` | `chat.tsx:1152` | Streaming text prefix |
+| `AnimatedDot` | `skill-load-indicator.tsx:103` | Skill loading state |
+
+All use the same pattern: `setInterval` toggling a boolean at 500ms, alternating `●` / `·`.
+
+#### 4.7 Potential Gap: Workflow-Spawned Tasks vs. TodoWrite Tasks
+
+The blinker works for tasks that have `status === "in_progress"` in `tasks.json`. However, in the Ralph workflow, the worker node (`graph.ts:141-178`) does **not** explicitly set task status to `"in_progress"` before spawning the sub-agent. The flow is:
+
+1. `select-ready-tasks` node calls `getReadyTasks()` → sets `currentTasks` (status still `"pending"`)
+2. `worker` node spawns sub-agent with `ready[0]`
+3. After spawn completes, maps tasks to `"completed"` or `"error"` (`graph.ts:168-174`)
+
+There is no intermediate step setting `ready[0].status = "in_progress"` before the spawn. The blinker would only activate if the spawned sub-agent itself writes `status: "in_progress"` to `tasks.json` via TodoWrite during its execution.
+
+#### 4.8 Key Code References
+
+| File | Lines | Function |
+|---|---|---|
+| `src/ui/components/animated-blink-indicator.tsx` | 1-33 | `AnimatedBlinkIndicator` — canonical blink component |
+| `src/ui/components/task-list-indicator.tsx` | 113-162 | Per-task row rendering with blink |
+| `src/ui/components/task-list-indicator.tsx` | 146-149 | `AnimatedBlinkIndicator` usage for `in_progress` |
+| `src/ui/components/task-list-indicator.tsx` | 52-57 | Status icon constants |
+| `src/ui/components/task-list-indicator.tsx` | 66-74 | `getStatusColorKey()` — status-to-color mapping |
+| `src/ui/components/task-list-panel.tsx` | 72-151 | `TaskListBox` — container with progress bar |
+| `src/ui/components/task-list-panel.tsx` | 157-179 | `TaskListPanel` — file-driven wrapper |
+| `src/ui/utils/task-status.ts` | 19-37 | `TASK_STATUS_ALIASES` — status normalization |
+| `src/ui/utils/task-status.ts` | 149-156 | `normalizeTaskStatus()` — canonical normalization |
+| `src/ui/constants/icons.ts` | 1-108 | Icon constants (`STATUS.active`, `MISC.separator`, etc.) |
+| `src/workflows/ralph/graph.ts` | 141-178 | Worker node — no `in_progress` intermediate status set |
+
+---
+
+### Issue 5: Streaming Delay After TODO Completion
+
+#### 5.1 The Final Summary Message
+
+The "⣿ Composed for X · ↓ Y tokens" line is rendered by `CompletionSummary` (`chat.tsx:1114-1140`). It uses `SPINNER_COMPLETE` (`⣿` U+28FF) from `icons.ts:62`, formats duration via `formatCompletionDuration()` (`chat.tsx:1095-1103`), and tokens via `formatTokenCount()` (`chat.tsx:1019-1027`). The verb is deterministic: `"Reasoned"` when `thinkingMs >= 1000`, else `"Composed"`.
+
+#### 5.2 Visibility Gate
+
+`shouldShowCompletionSummary()` at `loading-state.ts:69-77` requires ALL of:
+- `!message.streaming` — message must not be in streaming state
+- `!hasActiveBackgroundAgents` — no background agents still running
+- `message.durationMs != null` — duration must be stamped
+- `message.durationMs >= 1000` — minimum 1 second duration
+
+The summary cannot appear until all four conditions are met.
+
+#### 5.3 Three Stream Completion Signals
+
+The system has three distinct completion signals depending on the SDK adapter:
+
+| Signal | Adapter | Trigger |
+|---|---|---|
+| `stream.text.complete` | Claude, Sub-agent | `for await` loop over `session.stream()` finishes |
+| `stream.session.idle` | OpenCode, Copilot | SDK emits `session.idle` event |
+| Deferred completion | All (when agents/tools active) | `pendingCompleteRef` resolved via `useEffect` |
+
+**Claude/Sub-agent path**: `publishTextComplete()` → bus → BatchDispatcher (≤16ms) → StreamPipelineConsumer → `text-complete` StreamPartEvent → `handleStreamComplete()` at `chat.tsx:2692`.
+
+**OpenCode/Copilot path**: SDK `session.idle` → bus → direct `useBusSubscription` at `chat.tsx:2754-2761` → `batchDispatcher.flush()` → `handleStreamComplete()`.
+
+**Copilot deferred finalization**: When `message.complete` has `toolRequests`, `stream.text.complete` is intentionally NOT emitted (`copilot-adapter.ts:523-544`). Finalization deferred to `session.idle`.
+
+#### 5.4 `handleStreamComplete` — Three Code Paths
+
+Located at `chat.tsx:2466-2630`:
+
+**Path 1 — Interrupt** (lines 2480-2513): Sets `streaming: false`, stamps `durationMs`/`outputTokens`/`thinkingMs`, calls `stopSharedStreamState()`.
+
+**Path 2 — Deferred** (lines 2516-2556): **PRIMARY DELAY SOURCE**. If `hasActiveForegroundAgents(parallelAgentsRef.current)` or `hasRunningToolRef.current` is true:
+1. Stores a `deferredComplete` closure in `pendingCompleteRef.current`
+2. Sets a **30-second safety timeout** (`chat.tsx:2555`)
+3. Returns early — message stays `streaming: true`
+4. Resolution chain: `stream.agent.complete` → 16ms batch → React state update → re-render → `useEffect` (line 3268) → `shouldFinalizeDeferredStream()` → `setTimeout(…, 0)` → `pendingComplete()`
+
+**Path 3 — Normal** (lines 2559-2612): Happy path when no agents/tools active. Calculates `durationMs = Date.now() - streamingStartRef.current`, stamps metadata onto message, calls `stopSharedStreamState()`.
+
+#### 5.5 Identified Sources of Delay
+
+**Source A: Deferred completion with active foreground agents** (`chat.tsx:2516-2556`)
+When `handleStreamComplete()` fires while sub-agents are still "running" in React state, completion is deferred. The resolution chain involves:
+1. `stream.agent.complete` event published to bus
+2. ≤16ms batch dispatch window
+3. React state update for `parallelAgents`
+4. React re-render
+5. `useEffect` dependency re-evaluation (line 3268)
+6. `setTimeout(…, 0)` microtask delay
+7. `handleStreamComplete()` re-entry
+8. Another `setMessagesWindowed` call
+9. Another React re-render
+10. `shouldShowCompletionSummary()` evaluated
+
+This chain adds **tens to hundreds of milliseconds** through React batching. The 30-second safety timeout is a worst-case fallback.
+
+**Source B: SDK `session.idle` timing** (adapter-specific)
+For OpenCode and Copilot adapters, the `session.idle` event is emitted by the SDK after all tool-use loops complete. The delay between the last SDK action and `session.idle` is **SDK-internal** and outside this codebase's control. If the SDK takes seconds to signal idle, the UI shows the spinner for that entire duration.
+
+**Source C: BatchDispatcher 16ms flush window** (`batch-dispatcher.ts:20`)
+For the Claude adapter path, `stream.text.complete` goes through `enqueue → scheduleFlush → 16ms timer → flush → consumer`. Maximum **16ms** delay.
+
+**Source D: File I/O in graph execution loop** (`executor.ts:301-306`)
+`await options.saveTasksToSession(...)` performs `atomicWrite()` (temp file write + rename) in the critical path of each graph step. This occurs **before** the `for await` loop completes and `setStreaming(false)` is called. Multiple task updates compound this.
+
+**Source E: React state update batching**
+Finalization at `chat.tsx:2585-2605` calls `setMessagesWindowed()` inside `setParallelAgents()`. React may batch state updates, meaning `shouldShowCompletionSummary()` may not see `streaming: false` + `durationMs` + cleared agents until a subsequent render cycle.
+
+**Source F: `shouldShowMessageLoadingIndicator` task progress check** (`loading-state.ts:35-55`)
+The loading indicator checks `isTaskProgressComplete(taskItems)`. If task progress items haven't been fully updated in the message state, the loading indicator stays visible longer, blocking the transition to the completion summary.
+
+#### 5.6 Data Flow: Stream End → Summary Rendered
+
+```
+SDK Stream Ends
+    │
+    ├─[Claude/SubAgent] for-await loop finishes
+    │   └─ publishTextComplete() → bus.publish("stream.text.complete")
+    │       └─ BatchDispatcher.enqueue() → ≤16ms flush
+    │           └─ StreamPipelineConsumer → "text-complete" StreamPartEvent
+    │               └─ chat.tsx useStreamConsumer (line 2666-2693)
+    │                   └─ text reconciliation → handleStreamComplete()
+    │
+    ├─[OpenCode/Copilot] SDK emits session.idle
+    │   └─ bus.publish("stream.session.idle")
+    │       └─ useBusSubscription (line 2754) [DIRECT, not batched]
+    │           └─ batchDispatcher.flush() → handleStreamComplete()
+    │
+    └─ handleStreamComplete()
+        │
+        ├─[Deferred] hasActiveForegroundAgents || hasRunningTool
+        │   └─ Store closure in pendingCompleteRef
+        │       └─ Wait for agents/tools to finish
+        │           └─ useEffect (line 3268) re-evaluates
+        │               └─ shouldFinalizeDeferredStream() = true
+        │                   └─ setTimeout(pendingComplete, 0)
+        │                       └─ handleStreamComplete() [re-entry]
+        │
+        └─[Normal]
+            ├─ durationMs = Date.now() - streamingStartRef.current
+            ├─ finalMeta = streamingMetaRef.current
+            ├─ setMessagesWindowed: stamp {streaming: false, durationMs, ...}
+            ├─ stopSharedStreamState()
+            └─ React re-render
+                └─ shouldShowCompletionSummary() = true
+                    └─ <CompletionSummary /> renders "⣿ Composed for X · ↓ Y tokens"
+```
+
+#### 5.7 Spinner-to-Summary Transition
+
+`LoadingIndicator` (`chat.tsx:1030-1078`) and `CompletionSummary` (`chat.tsx:1114-1140`) are **mutually exclusive** by design (`chat.tsx:1536-1556`):
+- `shouldShowMessageLoadingIndicator()` returns `true` while `streaming`, or while agents/tools are active
+- `shouldShowCompletionSummary()` returns `true` only when `!streaming && !hasActiveBackgroundAgents && durationMs >= 1000`
+
+The gap between spinner disappearing and summary appearing is the time it takes for:
+1. `streaming` to flip to `false` in the message
+2. `durationMs` to be stamped on the message
+3. `hasActiveBackgroundAgents` to evaluate to `false`
+4. React to re-render with the updated state
+
+#### 5.8 Key Code References
+
+| File | Lines | Function |
+|---|---|---|
+| `src/ui/chat.tsx` | 1114-1140 | `CompletionSummary` — renders "⣿ Composed for X · ↓ Y tokens" |
+| `src/ui/chat.tsx` | 1095-1103 | `formatCompletionDuration()` — ms → human duration |
+| `src/ui/chat.tsx` | 1019-1027 | `formatTokenCount()` — token count formatting |
+| `src/ui/chat.tsx` | 1030-1078 | `LoadingIndicator` — braille spinner during streaming |
+| `src/ui/chat.tsx` | 1536-1556 | Spinner ↔ CompletionSummary mutual exclusion render |
+| `src/ui/chat.tsx` | 2466-2630 | `handleStreamComplete()` — main finalization function |
+| `src/ui/chat.tsx` | 2516-2556 | Deferred completion path (30s safety timeout) |
+| `src/ui/chat.tsx` | 2585-2605 | Normal path — stamps durationMs, outputTokens, thinkingMs |
+| `src/ui/chat.tsx` | 2754-2761 | `stream.session.idle` subscription — fallback finalization |
+| `src/ui/chat.tsx` | 3268-3374 | `useEffect` — deferred completion resolution |
+| `src/ui/chat.tsx` | 2123-2159 | `stopSharedStreamState()` — clears all streaming refs |
+| `src/ui/utils/loading-state.ts` | 35-55 | `shouldShowMessageLoadingIndicator()` |
+| `src/ui/utils/loading-state.ts` | 69-77 | `shouldShowCompletionSummary()` — visibility gate |
+| `src/ui/parts/guards.ts` | 42-47 | `shouldFinalizeDeferredStream()` — checks agents/tools done |
+| `src/events/batch-dispatcher.ts` | 20, 183-194 | 16ms flush interval, `scheduleFlush()` |
+| `src/events/adapters/copilot-adapter.ts` | 523-544 | Deferred text.complete when tool requests present |
+| `src/events/adapters/opencode-adapter.ts` | 730-751 | `session.idle` → `stream.session.idle` |
+| `src/events/consumers/stream-pipeline-consumer.ts` | 178-181 | `stream.text.complete` → `text-complete` part |
+| `src/ui/utils/stream-continuation.ts` | 39, 139-145 | 50ms queued message dispatch delay |
+| `src/workflows/executor.ts` | 301-306 | `await saveTasksToSession()` — file I/O in graph loop |
+| `src/ui/constants/icons.ts` | 51-62 | `SPINNER_FRAMES`, `SPINNER_COMPLETE` |
+
+---
+
+## Open Questions
+
+1. **Issue 1 — Is the `useBusSubscription` for `stream.agent.update` actually being called?** The `chat.tsx` handler at lines 2882-2895 directly subscribes to the bus, but it's unclear whether this subscription is properly registered before sub-agent events start flowing. If the component mounts after the first `stream.agent.update`, early events are lost.
+
+2. **Issue 1 — Does event coalescing cause lost updates?** The coalescing window is ~16ms. If `stream.agent.update` events arrive and are coalesced before the consumer processes them, only the last update per agent survives. This is normally fine (we want the latest count), but if the subscription isn't yet active, all coalesced events are lost.
+
+3. **Issue 1 — Is the `CorrelationService` correctly registering sub-agents?** Sub-agents spawned by the workflow executor are registered via `correlation.registerSubagent()`. If this registration happens after tool events start flowing, tool events may be filtered as "unowned" by `isOwnedEvent()`.
+
+4. **Issue 2 — Is the reported behavior ("code review runs after each task") actually observed?** The graph topology shows code review runs once after the loop. If users observe repeated code reviews, it may be caused by a different mechanism (e.g., workflow restart, or the fixer triggering additional review cycles — though this is not present in the current graph).
+
+5. **Issue 3 — What is the desired behavior for task status updates when running in parallel?** Currently, the worker marks ALL `currentTasks` as completed/error based on a single spawn result. With parallel execution, each task's status would need to be independently tracked based on its own spawn result.
+
+6. **Issue 3 — How should the loop iteration counter work with parallel tasks?** Currently, `iteration` increments by 1 per loop pass, processing 1 task. With parallel execution, should `iteration` increment by 1 per batch of parallel tasks, or by the number of tasks processed?
+
+7. **Issue 3 — Should parallel task execution use the graph-level `parallelNode` construct, or should it be implemented within the worker node using `spawnSubagentParallel`?** The graph engine's `parallelNode` still executes branches sequentially. True concurrency requires using `ctx.config.runtime.spawnSubagentParallel` within the worker node.
+
+8. **Issue 4 — Does the Ralph worker node need to explicitly set task status to `"in_progress"` before spawning?** Currently, the worker node goes directly from `"pending"` → `"completed"`/`"error"` without an intermediate `"in_progress"` step. The blinker only activates for `"in_progress"` tasks. If the sub-agent sets this status via TodoWrite during execution, the blinker works; otherwise, actively worked-on tasks appear as `"pending"` (static `○`) until they jump to `"completed"` (static `✓`).
+
+9. **Issue 5 — Is the delay primarily caused by deferred completion (active foreground agents), or by SDK `session.idle` latency?** The two most likely sources are: (a) sub-agents still showing as "running" in React state when `handleStreamComplete()` fires (causing deferred path with multi-step React resolution), and (b) the SDK not emitting `session.idle` promptly. Instrumentation/logging at `handleStreamComplete()` entry and at the deferred resolution `useEffect` would disambiguate.
+
+10. **Issue 5 — Does `shouldShowCompletionSummary`'s `hasActiveBackgroundAgents` check cause an additional delay?** The `hasActiveBackgroundAgents` check uses **baked** `message.parallelAgents` from finalization time. If background agents were stamped with `status: "background"` at finalization, the summary is blocked until those agents complete or are cleaned up.
+
+11. **Issue 5 — Could `saveTasksToSession` file I/O in the graph loop contribute to delay at scale?** Each graph step performs `await atomicWrite()` if tasks exist. With many tasks, the cumulative file I/O time between the last node completing and the graph loop exiting could be measurable.
diff --git a/research/docs/2026-02-28-workflow-tui-rendering-unification-refactor.md b/research/docs/2026-02-28-workflow-tui-rendering-unification-refactor.md
new file mode 100644
index 0000000000..af269370dd
--- /dev/null
+++ b/research/docs/2026-02-28-workflow-tui-rendering-unification-refactor.md
@@ -0,0 +1,892 @@
+---
+date: 2026-02-28 19:08:57 UTC
+researcher: Copilot (Claude Opus 4.6)
+git_commit: c88d4d1512f962b7cf0a1d770351efc7af52932e
+branch: lavaman131/feature/workflow-sdk
+repository: workflow-sdk
+topic: "Refactoring workflows to use the same UI engine as the main TUI"
+tags:
+    [
+        research,
+        codebase,
+        workflow,
+        tui,
+        rendering,
+        unification,
+        sub-agent-tree,
+        event-bus,
+        parts-pipeline,
+        ralph,
+    ]
+status: complete
+last_updated: 2026-02-28
+last_updated_by: Copilot (Claude Opus 4.6)
+last_updated_note: "Updated summary to reflect refined approach: replace bespoke AgentInline renderers with PART_REGISTRY dispatch (rendering-only change, event pipeline already shared)"
+---
+
+# Research: Workflow TUI Rendering Unification Refactor
+
+## Research Question
+
+Document the current workflow execution system (`src/workflows/`, including the `/ralph` workflow) and the main TUI rendering engine (`src/ui/`) to understand: (1) how workflows currently display progress/output to users, (2) how the main TUI renders sub-agent trees, tool calls, text blocks, and other UI elements, and (3) what the specific architectural differences and coupling points are between these two rendering paths — so that a future refactor could unify them under a single UI engine.
+
+## Summary
+
+The event bus and reducer layers are **already shared** between the main chat and workflow sub-agents. `spawnSubagentParallel()` at `chat.tsx:4083` already creates `SubagentStreamAdapter` instances that publish all 9 event types to the shared `AtomicEventBus`, and the reducer `applyStreamPartEvent()` in `stream-pipeline.ts` already routes sub-agent events to `agent.inlineParts[]` using the same helpers (`handleTextDelta`, `upsertToolPartStart`, `upsertToolPartComplete`) as top-level parts. The `Part` objects in `inlineParts` are structurally identical to top-level `parts[]`.
+
+**The divergence is only in the rendering layer.** Main chat dispatches `parts[]` through `PART_REGISTRY` — 9 full-fidelity renderers for markdown, tool chrome with expandable I/O, reasoning blocks, etc. Workflow sub-agent content lands in `agent.inlineParts[]` but is rendered by bespoke `AgentInlineText` (200-char truncated plain text, no markdown) and `AgentInlineTool` (30-char tool name, single line) — bypassing `PART_REGISTRY` entirely. Only 2 of 9 part types are handled, and only the latest part is shown.
+
+**The fix is straightforward**: replace `AgentInlineParts`/`AgentInlineText`/`AgentInlineTool` with `PART_REGISTRY` dispatch so workflow sub-agents render through the exact same renderers as the main chat. Route all part types (including `ReasoningPart`, currently missing) to `inlineParts`. Delete the bespoke workflow rendering code.
+
+---
+
+## Detailed Findings
+
+### 1. How Workflows Currently Display Progress/Output
+
+#### The Workflow Executor (`src/workflows/executor.ts`)
+
+The `executeWorkflow()` function (line 123) orchestrates workflow execution in 6 phases:
+
+1. **Session initialization** (lines 134-168): Generates session IDs, creates a `WorkflowEventAdapter`, publishes a synthetic `stream.session.start` event, and calls `context.updateWorkflowState()` with `{ workflowActive: true }`.
+
+2. **Graph resolution** (lines 178-194): Compiles the declarative `WorkflowGraphConfig` into a `CompiledGraph` via `compileGraphConfig()`.
+
+3. **State creation** (lines 197-201): Calls `definition.createState()` to initialize workflow-specific state.
+
+4. **Runtime setup** (lines 203-278): Injects runtime dependencies into the compiled graph:
+    - `spawnSubagent()` wraps `context.spawnSubagentParallel()` and publishes `stream.agent.start`/`stream.agent.complete` events via the adapter
+    - `spawnSubagentParallel()` does the same for parallel dispatch
+    - `notifyTaskStatusChange()` publishes `workflow.task.statusChange` to the event bus
+
+5. **Streaming execution** (lines 280-415): Iterates `streamGraph()` yields. On each node transition:
+    - Publishes `workflow.step.start` and `workflow.step.complete` via the adapter
+    - Syncs `state.tasks` to disk via debounced atomic writes to `tasks.json`
+    - Publishes `workflow.task.update` via the adapter
+
+6. **Result reporting** (lines 417-491): Calls `context.addMessage()` with static success/failure text and returns a `CommandResult`.
+
+**Key observation:** The executor publishes 8 different event types to the bus, but many of them are never consumed by the UI pipeline (see Finding 3).
+
+#### Current Sub-Agent Output Handling
+
+At `src/ui/chat.tsx:3970-3984`, workflow sub-agent streams are consumed in a silent loop:
+
+```typescript
+for await (const msg of stream) {
+    if (msg.type === "tool_use") {
+        toolUses++;
+    } else if (msg.type === "text") {
+        summaryParts.push(msg.content);
+    }
+}
+```
+
+This discards:
+
+- All streaming text deltas (text accumulated but never rendered incrementally)
+- All thinking blocks (not even checked)
+- All token counts (usage events ignored)
+- All tool lifecycle events (counted but not displayed)
+- Output truncated to 4000 characters via `MAX_SUMMARY_LENGTH`
+
+**User experience:** Users see "Starting workflow..." then nothing until "Workflow completed." — a black box during the most complex, long-running operations.
+
+#### The Ralph Workflow (`src/workflows/ralph/`)
+
+Ralph is a three-phase compiled graph:
+
+1. **Planning** (`planner` + `parse-tasks` nodes): A planner sub-agent decomposes the user prompt into a `TaskItem[]` JSON array.
+2. **Worker loop** (`select-ready-tasks` + `worker` nodes): Ready tasks (pending with resolved dependencies) are dispatched to parallel worker sub-agents. The loop continues until all tasks are completed/errored or max iterations reached.
+3. **Review & fix** (`reviewer` + conditional `fixer` nodes): A reviewer sub-agent evaluates the work; if issues are found, a fixer (debugger) sub-agent applies corrections.
+
+State management uses annotation-defined reducers (e.g., `mergeByIdReducer` for tasks) to safely merge concurrent worker updates.
+
+**Ralph-specific UI communications:**
+
+- Node descriptions map (`definition.ts:17-24`) provides human-readable progress strings (e.g., `"⌕ Planning: Analyzing requirements..."`)
+- Task status change notifications via `notifyTaskStatusChange()` in the worker node
+- Session directory and task IDs registered with the TUI via `context.setWorkflowSessionDir/Id/TaskIds()`
+
+#### Dual-Source Task List Display
+
+Task data enters the UI through two independent channels:
+
+1. **Stream events** (`workflow.task.update` → `TaskListPart` in message parts) — currently broken (events dropped)
+2. **File watching** (`tasks.json` on disk → `watchTasksJson()` → `TaskListPanel` component) — working, provides persistent display
+
+---
+
+### 2. How the Main TUI Renders Sub-Agent Trees, Tool Calls, and Text Blocks
+
+#### The Parts-Based Rendering Pipeline
+
+The main TUI uses a multi-stage event-driven pipeline:
+
+```
+SDK (Claude/OpenCode/Copilot)
+  → SDKStreamAdapter.startStreaming()           [src/ui/index.ts:475]
+    → AtomicEventBus.publish()                  [src/events/event-bus.ts:139]
+      → BatchDispatcher.enqueue()               [16ms frame-aligned batching]
+        → CorrelationService.enrich()           [adds metadata, filters]
+          → StreamPipelineConsumer.processBatch() [maps bus events → StreamPartEvents]
+            → useStreamConsumer callback         [React hook in chat.tsx]
+              → applyStreamPartEvent()           [immutable reducer]
+                → ChatMessage.parts[]            [Part union array]
+                  → MessageBubbleParts           [React component]
+                    → PART_REGISTRY[type]        [type-specific renderer]
+```
+
+#### Nine Part Types
+
+All parts extend `BasePart` (`id: PartId`, `type: string`, `createdAt: string`):
+
+| Part Type          | `type` Discriminant | Key Fields                                                                                                | Renderer                  |
+| ------------------ | ------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------- |
+| `TextPart`         | `"text"`            | `content`, `isStreaming`                                                                                  | `TextPartDisplay`         |
+| `ReasoningPart`    | `"reasoning"`       | `thinkingSourceKey`, `content`, `durationMs`, `isStreaming`                                               | `ReasoningPartDisplay`    |
+| `ToolPart`         | `"tool"`            | `toolCallId`, `toolName`, `input`, `output`, `state` (5-state machine), `hitlResponse`, `pendingQuestion` | `ToolPartDisplay`         |
+| `AgentPart`        | `"agent"`           | `agents: ParallelAgent[]`, `parentToolPartId`                                                             | `AgentPartDisplay`        |
+| `TaskListPart`     | `"task-list"`       | `items: TaskItem[]`, `expanded`                                                                           | `TaskListPartDisplay`     |
+| `SkillLoadPart`    | `"skill-load"`      | `skills: MessageSkillLoad[]`                                                                              | `SkillLoadPartDisplay`    |
+| `McpSnapshotPart`  | `"mcp-snapshot"`    | `snapshot: McpSnapshotView`                                                                               | `McpSnapshotPartDisplay`  |
+| `CompactionPart`   | `"compaction"`      | `summary`                                                                                                 | `CompactionPartDisplay`   |
+| `WorkflowStepPart` | `"workflow-step"`   | `nodeId`, `nodeName`, `status`, `startedAt`, `completedAt`, `durationMs`                                  | `WorkflowStepPartDisplay` |
+
+#### Sub-Agent Tree Display Architecture
+
+Sub-agent rendering uses a **dual delivery path**:
+
+**Path A — Agent lifecycle events** (NOT through `StreamPipelineConsumer`):
+
+- `stream.agent.start/update/complete` events are consumed via direct React `useBusSubscription` hooks in `chat.tsx` (lines 2946-3052)
+- These update `parallelAgents` React state
+- A `useEffect` bridge (lines 3356-3413) emits synthetic `parallel-agents` events into the stream pipeline reducer
+- The reducer calls `mergeParallelAgentsIntoParts()` to create/update `AgentPart` nodes in `message.parts[]`
+
+**Path B — Agent-scoped tool/text events** (through `StreamPipelineConsumer`):
+
+- `stream.tool.start/complete` and `stream.text.delta` with `parentAgentId` are mapped to `StreamPartEvents` with `agentId`
+- The reducer routes them to the matching agent's `inlineParts` sub-array via `routeToAgentInlineParts()`
+- Events arriving before the `AgentPart` exists are buffered and replayed when the agent materializes
+
+**Visual rendering:**
+
+- `AgentPartDisplay` splits agents into foreground/background groups
+- `ParallelAgentsTree` renders a tree with `├─●` connectors, status indicators, task labels, current tool, and inline parts
+- Agent colors are mapped via Catppuccin palette per agent type
+
+#### Key Design Patterns in the Main TUI
+
+1. **Immutable reducer**: `applyStreamPartEvent()` returns new objects at every level — no in-place mutation
+2. **Binary-search sorted arrays**: Parts kept in `PartId`-sorted order via `upsertPart()` for chronological display
+3. **WeakMap registry**: Reasoning part source-key tracking uses `WeakMap<ChatMessage, Map<string, PartId>>` for automatic GC
+4. **Agent event buffering**: Module-level `Map<string, StreamPartEvent[]>` buffers events for agents not yet in parts
+5. **Double rendering path**: Parts populated during streaming via reducer, then augmented at render time by `getRenderableAssistantParts()`
+6. **Frame-aligned batching**: `BatchDispatcher` at 16ms intervals coalesces state updates while preserving text deltas
+
+---
+
+### 3. Architectural Differences and Coupling Points
+
+#### The Three-Point Disconnection
+
+The workflow rendering path has three disconnection points that prevent workflow events from reaching the UI:
+
+| Disconnection    | Location                                          | Current State                                                                     |
+| ---------------- | ------------------------------------------------- | --------------------------------------------------------------------------------- |
+| **Consumer gap** | `stream-pipeline-consumer.ts` `mapToStreamPart()` | `workflow.step.*` events hit `default: return null` — silently dropped            |
+| **Type system**  | `src/ui/parts/types.ts`                           | `WorkflowStepPart` IS defined and IS in the `Part` union (lines 121-129, 136-145) |
+| **Registry**     | `src/ui/components/parts/registry.tsx`            | `"workflow-step"` IS registered in `PART_REGISTRY` (line 32)                      |
+
+**Note:** The type system and registry gaps have been resolved since the earlier research was conducted. The remaining gap is solely in `StreamPipelineConsumer.mapToStreamPart()` which needs `case` handlers for `workflow.step.start`, `workflow.step.complete`, and `workflow.task.update`.
+
+**Update (from latest code analysis):** The `StreamPipelineConsumer` at `stream-pipeline-consumer.ts` lines 190-216 **already has** handlers for `workflow.step.start` → `workflow-step-start`, `workflow.step.complete` → `workflow-step-complete`, and `workflow.task.update` → `task-list-update`. This means the full pipeline IS connected for workflow step and task events. The remaining gap is solely the **silent sub-agent stream consumption** in `chat.tsx`.
+
+#### Silent Sub-Agent Sessions — The Core Gap
+
+The fundamental difference is how sub-agent streams are consumed:
+
+**Main chat (works):**
+
+```
+SubagentStreamAdapter.consumeStream()
+  → For each AgentMessage:
+    → bus.publish("stream.text.delta", { agentId })      ← rendered in agent inline parts
+    → bus.publish("stream.tool.start", { parentAgentId }) ← rendered in agent inline parts
+    → bus.publish("stream.tool.complete", { parentAgentId })
+    → toolTracker.onToolStart/Complete()
+      → bus.publish("stream.agent.update", { currentTool, toolUses })
+```
+
+**Workflow executor (broken):**
+
+```
+for await (const msg of stream) {
+  summaryParts.push(msg.content);  ← silently accumulated, never rendered
+}
+return { output: summaryParts.join("").slice(0, 4000) };  ← truncated
+```
+
+#### Feature Parity Gap
+
+| Feature               | Main Chat                                             | Workflow Executor                         |
+| --------------------- | ----------------------------------------------------- | ----------------------------------------- |
+| Streaming text        | ✅ Incremental via `stream.text.delta`                | ❌ Accumulated silently, truncated        |
+| Token counts          | ✅ Via `stream.usage` → `CompletionSummary`           | ❌ Not tracked                            |
+| Thinking blocks       | ✅ Via `stream.thinking.delta` → `ReasoningPart`      | ❌ Not captured                           |
+| Spinner with metadata | ✅ Elapsed time, tokens, thinking duration            | ⚠️ Boolean flag only                      |
+| Sub-agent tree        | ✅ Full tree with tool counts, current tool, duration | ⚠️ Tree shows but no live inline progress |
+| Tool call rendering   | ✅ Inline with status, collapsible output             | ❌ Counted but not rendered               |
+| Text blocks           | ✅ Markdown rendering                                 | ❌ Only static start/completion messages  |
+| Completion summary    | ✅ Duration, tokens, thinking time                    | ❌ No per-agent or per-step summary       |
+| Parts-based rendering | ✅ Full `Part[]` pipeline                             | ❌ Only `context.addMessage()`            |
+
+#### Coupling Surface Between Workflow and UI Layers
+
+**UI → Workflow (direct imports):**
+
+| UI File                                   | What It Imports                                                                        |
+| ----------------------------------------- | -------------------------------------------------------------------------------------- |
+| `src/ui/commands/workflow-commands.ts`    | `session.ts`, `executor.ts`, `ralph/graph.ts`, `ralph/definition.ts`, `graph/types.ts` |
+| `src/ui/chat.tsx`                         | `graph/types.ts`, `graph/index.ts`                                                     |
+| `src/ui/commands/registry.ts`             | `graph/types.ts` (`SubagentSpawnOptions`, `SubagentStreamResult`)                      |
+| `src/sdk/clients/copilot.ts`              | `graph/types.ts`                                                                       |
+| `src/events/adapters/subagent-adapter.ts` | `graph/types.ts`                                                                       |
+
+**Workflow → UI (via `CommandContext` only):**
+
+The workflow graph has zero direct imports from the UI layer. All communication flows through the `CommandContext` interface:
+
+- Task updates: `setWorkflowSessionDir()`, `setWorkflowSessionId()`, `setWorkflowTaskIds()`
+- Status: `addMessage()`, `setStreaming()`, `updateWorkflowState()`
+- Sub-agent dispatch: `spawnSubagentParallel()`
+
+**Ralph-Specific Fields in Shared Interfaces:**
+
+- `CommandContext.setRalphSessionDir` (`registry.ts:135`) — should be generalized
+- `CommandContext.setRalphSessionId` (`registry.ts:139`) — should be generalized
+- `CommandContext.setRalphTaskIds` (`registry.ts:145`) — should be generalized
+- `WorkflowChatState.ralphConfig` (`chat.tsx:886-890`) — should be generalized
+
+#### Event Bus Architecture
+
+The `AtomicEventBus` (`src/events/event-bus.ts`) implements a centralized pub/sub system with:
+
+- 26 event types in 8 categories (text, thinking, tool, agent, session, turn, workflow, interaction)
+- Zod schema validation on every publish
+- Error isolation per handler (try/catch prevents cascade)
+- `BatchDispatcher` with 16ms frame-aligned batching and double-buffer swap
+- Key-based coalescing (state events coalesced, text deltas never coalesced)
+- `CorrelationService` for sub-agent event enrichment and ownership tracking
+- `EchoSuppressor` for filtering duplicate text from SDK echo
+
+**Workflow events published by executor:**
+
+| Event                        | Published At          | Consumer Status                                |
+| ---------------------------- | --------------------- | ---------------------------------------------- |
+| `stream.session.start`       | `executor.ts:147-153` | ✅ Consumed by `CorrelationService.startRun()` |
+| `workflow.step.start`        | `executor.ts:346-351` | ✅ Mapped by `StreamPipelineConsumer`          |
+| `workflow.step.complete`     | `executor.ts:337-342` | ✅ Mapped by `StreamPipelineConsumer`          |
+| `workflow.task.update`       | `executor.ts:368-374` | ✅ Mapped by `StreamPipelineConsumer`          |
+| `workflow.task.statusChange` | `executor.ts:268-277` | ✅ Consumed by executor's own subscriber       |
+| `stream.agent.start`         | `executor.ts:217-219` | ✅ Consumed by `chat.tsx` bus subscription     |
+| `stream.agent.complete`      | `executor.ts:227-233` | ✅ Consumed by `chat.tsx` bus subscription     |
+
+---
+
+## Code References
+
+### Workflow Executor System
+
+- `src/workflows/executor.ts:123` — `executeWorkflow()` main entry point
+- `src/workflows/executor.ts:211-265` — `spawnSubagent`/`spawnSubagentParallel` runtime injection
+- `src/workflows/executor.ts:326-391` — Streaming execution loop with step events
+- `src/workflows/session.ts:51-77` — `initWorkflowSession()` session lifecycle
+- `src/workflows/index.ts` — Barrel exports
+
+### Ralph Workflow
+
+- `src/workflows/ralph/definition.ts:50-63` — `ralphWorkflowDefinition` registration
+- `src/workflows/ralph/definition.ts:17-24` — Node descriptions for UI progress
+- `src/workflows/ralph/graph.ts:98-263` — `createRalphWorkflow()` graph construction
+- `src/workflows/ralph/state.ts:51-80` — `RalphWorkflowState` interface (30 fields)
+- `src/workflows/ralph/prompts.ts:37-77` — Planner prompt template
+
+### Main TUI Rendering Pipeline
+
+- `src/ui/parts/types.ts:20-145` — Part type definitions (9 types)
+- `src/ui/parts/stream-pipeline.ts:961-1167` — `applyStreamPartEvent()` main reducer
+- `src/ui/parts/handlers.ts:21-52` — `handleTextDelta()` text streaming handler
+- `src/ui/parts/store.ts:20-53` — Binary-search sorted part store
+- `src/ui/components/parts/registry.tsx:23-33` — `PART_REGISTRY` type-to-renderer mapping
+- `src/ui/components/parts/message-bubble-parts.tsx:130-166` — Message rendering orchestrator
+- `src/ui/index.ts:207-798` — `startChatUI()` bootstrapping
+- `src/ui/chat.tsx:1589-6286` — `ChatApp` main component
+
+### Sub-Agent Tree Display
+
+- `src/ui/components/parallel-agents-tree.tsx:774` — `ParallelAgentsTree` tree renderer
+- `src/ui/components/parts/agent-part-display.tsx:53` — `AgentPartDisplay` part renderer
+- `src/ui/utils/background-agent-tree-hints.ts:24` — Tree hint computation
+- `src/events/adapters/subagent-adapter.ts:62` — `SubagentStreamAdapter` event bridge
+- `src/workflows/graph/subagent-registry.ts:33` — `SubagentTypeRegistry`
+
+### Event Bus Architecture
+
+- `src/events/event-bus.ts:58-234` — `AtomicEventBus` pub/sub hub
+- `src/events/bus-events.ts:33` — 26 event type definitions
+- `src/events/adapters/workflow-adapter.ts:31-214` — `WorkflowEventAdapter`
+- `src/events/consumers/wire-consumers.ts:65-108` — Pipeline assembly
+- `src/events/consumers/stream-pipeline-consumer.ts:61-241` — Bus-to-StreamPart mapping
+- `src/events/consumers/correlation-service.ts:64-439` — Event enrichment/correlation
+- `src/events/batch-dispatcher.ts:72-223` — Frame-aligned batching
+
+### Workflow Step Rendering
+
+- `src/ui/components/parts/workflow-step-part-display.tsx:25-53` — Step renderer
+- `src/ui/utils/workflow-task-state.ts` — Workflow task state utilities
+- `src/ui/components/task-list-panel.tsx:157-179` — File-driven task list panel
+- `src/ui/components/task-list-indicator.tsx:93-183` — Per-task item renderer
+- `src/ui/components/footer-status.tsx:39-101` — Workflow status footer
+
+### Workflow Commands (UI Bridge)
+
+- `src/ui/commands/workflow-commands.ts:623-712` — `createWorkflowCommand()` factory
+- `src/ui/commands/workflow-commands.ts:718-781` — `watchTasksJson()` file watcher
+- `src/ui/commands/workflow-commands.ts:250-285` — `saveTasksToActiveSession()` atomic writes
+
+---
+
+## Architecture Documentation
+
+### Current Rendering Pipeline Comparison
+
+```
+MAIN CHAT PIPELINE (fully functional):
+═══════════════════════════════════════
+SDK Session ──→ SDKStreamAdapter ──→ AtomicEventBus ──→ BatchDispatcher
+                                                              │
+                                                    ┌────────────────────┐
+                                                    │ CorrelationService │
+                                                    │  • ownership check │
+                                                    │  • enrichment      │
+                                                    │  • suppression     │
+                                                    └────────────────────┘
+                                                              │
+                                                    ┌────────────────────────┐
+                                                    │ StreamPipelineConsumer │
+                                                    │  mapToStreamPart()     │
+                                                    └────────────────────────┘
+                                                              │
+                                                    ┌────────────────────────┐
+                                                    │ useStreamConsumer hook │
+                                                    │  → onStreamParts()     │
+                                                    └────────────────────────┘
+                                                              │
+                                                    ┌────────────────────────┐
+                                                    │ applyStreamPartEvent() │
+                                                    │  immutable reducer     │
+                                                    └────────────────────────┘
+                                                              │
+                                                    ┌────────────────────────┐
+                                                    │ ChatMessage.parts[]    │
+                                                    │  → PART_REGISTRY       │
+                                                    │  → type-specific       │
+                                                    │    renderers           │
+                                                    └────────────────────────┘
+
+WORKFLOW PIPELINE (mostly broken):
+═══════════════════════════════════
+executeWorkflow()
+  │
+  ├── context.addMessage("Starting workflow...")     ← static text
+  │
+  ├── WorkflowEventAdapter.publishStep*()            ← events published ✅
+  │     → bus events reach StreamPipelineConsumer     ← mapped correctly ✅
+  │       → applyStreamPartEvent() handles them      ← reducer works ✅
+  │         → WorkflowStepPartDisplay renders         ← renderer exists ✅
+  │
+  ├── spawnSubagentParallel():
+  │     → publishAgentStart()                        ← tree shows agent ✅
+  │     → for await (msg of stream):
+  │         summaryParts.push(msg.content)            ← SILENT consumption ❌
+  │     → publishAgentComplete()                     ← tree updates ✅
+  │     → return { output: text.slice(0, 4000) }     ← truncated ❌
+  │
+  └── context.addMessage("Workflow completed.")      ← static text
+```
+
+### The Unification Path
+
+The selected architecture (from `specs/workflow-tui-rendering-unification.md`) is **Bus-Integrated Sub-Agent Sessions**: replace the silent stream consumption loop with `SubagentStreamAdapter` instances that publish to the shared `AtomicEventBus`.
+
+**Why this approach:**
+
+- Reuses the existing rendering pipeline — no new rendering paths
+- All 9 part types work automatically for workflow sub-agents
+- Event buffering, coalescing, and batching already handle concurrency
+- `AgentPartDisplay` already supports inline parts for sub-agent streaming content
+
+**Key changes needed:**
+
+1. Replace `for await` silent loop in `chat.tsx:3970-3984` with `SubagentStreamAdapter.consumeStream()` calls
+2. Remove `MAX_SUMMARY_LENGTH` truncation — full output flows through parts pipeline
+3. Ensure `CorrelationService` properly registers workflow sub-agents
+4. Verify concurrent stream handling (Ralph dispatches 3-5+ parallel workers)
+
+---
+
+## Historical Context (from research/)
+
+### Directly Related Research
+
+- `research/docs/2026-02-27-workflow-tui-rendering-unification.md` — Primary architecture audit identifying the two-pipeline problem, the three-point disconnection, and the silent sub-agent consumption pattern
+- `research/docs/2026-02-28-workflow-gaps-architecture.md` — Maps every gap to exact file paths and line numbers; identifies 7 categories of gaps including the broken rendering pipeline
+- `research/docs/2026-02-25-ui-workflow-coupling.md` — Documents the coupling surface between UI and workflow layers, identifies Ralph-specific fields that need generalization
+- `research/workflow-gaps.md` — High-level gap inventory covering WorkflowStep rendering, custom tool discovery, MCP bridge, and dropped CLI flags
+
+### Supporting Research
+
+- `research/docs/2026-02-26-streaming-architecture-event-bus-migration.md` — Documents the callback-to-event-bus migration that created the current architecture
+- `research/docs/2026-02-25-ralph-workflow-implementation.md` — Ralph autonomous implementation workflow and graph execution details
+- `research/docs/2026-02-25-graph-execution-engine.md` — Graph execution engine architecture
+- `research/docs/2026-02-16-opentui-rendering-architecture.md` — OpenTUI core rendering architecture
+- `research/docs/2026-02-16-atomic-chat-architecture-current.md` — Current chat system architecture
+
+### Related Specs
+
+- `specs/workflow-tui-rendering-unification.md` — RFC/Design doc for unifying rendering (Draft/WIP — not yet implemented)
+- `specs/unified-workflow-execution.md` — Companion spec for unified workflow execution interface
+- `specs/chat-system-parts-based-rendering.md` — Parts-based rendering system design
+- `specs/streaming-architecture-event-bus-migration.md` — Streaming architecture migration design
+
+---
+
+## Related Research
+
+- `research/docs/2026-02-25-workflow-sdk-standardization.md`
+- `research/docs/2026-02-25-workflow-sdk-refactor-research.md`
+- `research/docs/2026-02-25-unified-workflow-execution-research.md`
+- `research/docs/2026-02-23-258-background-agents-sdk-event-pipeline.md`
+- `research/docs/2026-02-15-subagent-event-flow-diagram.md`
+
+---
+
+## Open Questions
+
+1. **Concurrent stream handling capacity**: Ralph dispatches 3-5+ parallel worker sub-agents simultaneously. The `BatchDispatcher` coalesces at 16ms intervals, but has the system been load-tested with this many concurrent `SubagentStreamAdapter` instances publishing to the same bus?
+
+2. **Agent inline parts nesting depth**: The spec limits nesting to 1 level (sub-sub-agents summarized in parent's tool count). Does the current `routeToAgentInlineParts()` implementation enforce this, or could deeply nested workflows cause display issues?
+
+3. **Task list dual-source reconciliation**: When both the stream-based `TaskListPart` (from `workflow.task.update` events) and the file-based `TaskListPanel` (from `watchTasksJson()`) are active, how are conflicts handled? Could they show different data simultaneously?
+
+4. **Ralph-specific coupling**: The `CommandContext` interface contains Ralph-specific fields (`setRalphSessionDir`, `setRalphSessionId`, `setRalphTaskIds`). When generalizing for all workflows, what is the migration path for these?
+
+5. **Breaking change impact**: Replacing `SubagentResult` with `SubagentStreamResult` (which adds `tokenUsage`, `thinkingDurationMs`, `toolDetails`) is a breaking change for all callers of `spawnSubagentParallel`. How many call sites exist outside the workflow executor?
+
+6. **Memory pressure**: With full streaming content for multiple parallel sub-agents, the `ChatMessage.parts[]` array and agent `inlineParts[]` sub-arrays could grow significantly. Is there an eviction or windowing strategy for long-running workflows?
+
+---
+
+## Follow-up Research: Full Feature Parity — Spinner, Tokens, Thinking, Compact UI
+
+### Background
+
+The follow-up research maps exactly which streaming UI features exist in the main chat, how they're driven, and what specifically would need to happen for workflow sub-agents to have full parity — including the animated spinner with live token counters, thinking duration display, compact UI modes, and completion summaries.
+
+### Finding 1: The `spawnSubagentParallel` Path Already Uses `SubagentStreamAdapter`
+
+**Critical correction** to the initial research: The `spawnSubagentParallel()` implementation at `src/ui/chat.tsx:4083-4240` **already creates a `SubagentStreamAdapter`** for each sub-agent (lines 4163-4169) and calls `adapter.consumeStream(stream, agentAbort.signal)` at line 4182. The adapter publishes **all event types** to the shared `AtomicEventBus`:
+
+| Chunk Type                     | Bus Event Published                            | Adapter Lines |
+| ------------------------------ | ---------------------------------------------- | ------------- |
+| `text`                         | `stream.text.delta`                            | 212-231       |
+| `thinking` (with content)      | `stream.thinking.delta`                        | 248-261       |
+| `thinking` (complete)          | `stream.thinking.complete`                     | 275-287       |
+| `tool_use`                     | `stream.tool.start` + `stream.agent.update`    | 293-343       |
+| `tool_result`                  | `stream.tool.complete` + `stream.agent.update` | 348-414       |
+| Every chunk (if usage present) | `stream.usage`                                 | 420-448       |
+| On completion                  | `stream.text.complete`                         | 453-466       |
+| On error                       | `stream.session.error`                         | 471-483       |
+
+**This means the events ARE being published.** The question is whether they're being properly consumed and rendered.
+
+### Finding 2: Spinner / Token Counter Architecture
+
+The main chat spinner (`LoadingIndicator` at `chat.tsx:1033-1071`) is driven by:
+
+1. **Elapsed time**: `streamingStartRef.current = Date.now()` (set at `chat.tsx:3079`), ticked every 1s via `useEffect` interval (`chat.tsx:2009-2022`) → `streamingElapsedMs` state
+2. **Token counter**: `useBusSubscription("stream.usage")` at `chat.tsx:2888-2919` → `streamingMeta.outputTokens` → monotonic max accumulation → baked onto `ChatMessage.outputTokens`
+3. **Thinking seconds**: `useBusSubscription("stream.thinking.complete")` at `chat.tsx:2922-2943` → `streamingMeta.thinkingMs` → baked onto `ChatMessage.thinkingMs`
+
+**Display logic**: `⣾ Composing… (6m 22s · ↓ 16.7k tokens · thought for 54s)` — braille spinner (8 frames at 120ms), accent verb, muted info parts joined by `·`.
+
+**Verb override for workflows**: At `chat.tsx:3868-3874`, workflow messages get `msg.spinnerVerb = "Running workflow"`, changing spinner text to `"⣾ Running workflow…"`.
+
+**Gap for workflow sub-agents**: The `stream.usage` bus subscription at `chat.tsx:2888-2919` updates `streamingMeta` and bakes tokens onto `streamingMessageIdRef.current ?? lastStreamedMessageIdRef.current`. For workflow sub-agents, these events DO arrive on the bus (published by `SubagentStreamAdapter`), but:
+
+- `streamingMessageIdRef.current` points to the **workflow wrapper message**, not per-agent messages
+- Token counts from ALL sub-agents are accumulated onto a single message counter — there's no per-agent token display
+- The `agentId` in the event payload is available but not used to route tokens to per-agent display
+
+### Finding 3: Thinking Duration Display Architecture
+
+Thinking events flow through **two parallel paths**:
+
+**Path A — Pipeline (content rendering)**:
+
+```
+stream.thinking.delta → StreamPipelineConsumer → ThinkingMetaEvent
+  → useStreamConsumer callback (chat.tsx:2720-2774)
+    → thinkingTextBySource map accumulation
+    → applyStreamPartEvent → creates/updates ReasoningPart
+      → ReasoningPartDisplay renders thinking text
+```
+
+**Path B — Direct bus subscription (duration tracking)**:
+
+```
+stream.thinking.complete → useBusSubscription (chat.tsx:2922-2943)
+  → Math.max(prev.thinkingMs, event.durationMs)
+  → bake onto ChatMessage.thinkingMs
+```
+
+**Gap for workflow sub-agents**: Both paths fire for sub-agent thinking events (the adapter publishes them), but:
+
+- Path A: Thinking text from sub-agents would need to be routed to agent `inlineParts` (similar to text deltas) rather than the main message's parts
+- Path B: Thinking duration is accumulated into a single `streamingMeta.thinkingMs` for the whole message — there's no per-agent thinking time tracking
+
+### Finding 4: Compact UI — Six Distinct Mechanisms
+
+The codebase has 6 independent compact/collapse mechanisms:
+
+| Mechanism                           | Component                          | What It Controls                             | Toggle                                           |
+| ----------------------------------- | ---------------------------------- | -------------------------------------------- | ------------------------------------------------ |
+| **Context compaction** (`/compact`) | `builtin-commands.ts:239`          | SDK conversation token count                 | Slash command                                    |
+| **Transcript mode** (Ctrl+O)        | `chat.tsx:5086` → `TranscriptView` | Full-screen detailed history view            | Keyboard                                         |
+| **Collapsed messages**              | `MessageBubble` `collapsed` prop   | Single-line message summaries                | Prop (hardcoded `false`)                         |
+| **Verbose mode** (Ctrl+E)           | `use-verbose-mode.ts:63`           | Tool output expansion, timestamps            | Keyboard                                         |
+| **ParallelAgentsTree compact**      | `agent-part-display.tsx:83`        | Agent tree label truncation (40 vs 50 chars) | Auto (active agents = full, completed = compact) |
+| **TaskListPart expansion**          | `task-list-indicator.tsx:134`      | Task content truncation (60 chars)           | Part property                                    |
+
+**Gap for workflow sub-agents**: Most compact modes apply at the `ChatMessage`/`MessageBubble` level, so they would automatically apply to workflow messages IF workflow content is rendered through the parts pipeline. The `ParallelAgentsTree` compact mode already works for workflow agents since it's driven by `stream.agent.*` events.
+
+### Finding 5: Completion Summary Architecture
+
+`CompletionSummary` (`chat.tsx:1112-1134`) renders: `⣿ Reasoned for 1m 6s · ↓ 16.7k tokens · thought for 54s`
+
+**Gating**: `shouldShowCompletionSummary()` at `loading-state.ts:69-77` requires:
+
+1. `message.streaming === false`
+2. `hasActiveBackgroundAgents === false`
+3. `message.durationMs >= 1000`
+
+**Data source**: All three values (`durationMs`, `outputTokens`, `thinkingMs`) are baked onto the `ChatMessage` in `handleStreamComplete()` at `chat.tsx:2493-2623`.
+
+**Gap for workflow sub-agents**: The completion summary shows for the **overall workflow message** once streaming stops. There's no per-sub-agent completion summary. The `SubagentStreamAdapter.buildResult()` (lines 533-566 of `subagent-adapter.ts`) already computes per-agent `tokenUsage` and `thinkingDurationMs` in the returned `SubagentStreamResult`, but these values are not surfaced in any UI component.
+
+### Finding 6: Correlation and Event Routing for Sub-Agents
+
+**How sub-agent events are routed** (`src/ui/chat.tsx:4119-4175`):
+
+1. `parentSessionId = getSession?.()?.id ?? "workflow"` — all events carry the parent session's ID
+2. `correlationService.addOwnedSession(parentSessionId)` — so events pass ownership check
+3. `correlationService.registerSubagent(agentId, { parentAgentId, workflowRunId })` — enables agent-aware enrichment
+
+**Event routing details**:
+
+- `stream.text.delta` with `agentId` → flows through pipeline → arrives in `useStreamConsumer` → at `chat.tsx:2676`, it does NOT update `lastStreamingContentRef` (only main-stream text does) → but it IS dispatched to `applyStreamPartEvent` which routes to agent `inlineParts` via `routeToAgentInlineParts()`
+- `stream.text.complete` from sub-agents → `CorrelationService` (line 248-263) sets `suppressFromMainChat = true` → filtered at `wire-consumers.ts:94` → never triggers `handleStreamComplete()`
+- `stream.usage` → reaches the **direct bus subscription** at `chat.tsx:2888` → updates `streamingMeta` for whichever message `streamingMessageIdRef.current` points to
+
+### Revised Feature Parity Gap (Detailed)
+
+| Feature                            | Main Chat                               | Workflow Status                                         | What's Missing                                                                                                 |
+| ---------------------------------- | --------------------------------------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| **Spinner animation**              | ✅ 8 braille frames at 120ms            | ✅ Shows "Running workflow…"                            | Nothing — verb override at `chat.tsx:3868` works                                                               |
+| **Elapsed timer**                  | ✅ 1s interval ticks                    | ✅ Works for workflow message                           | Nothing — `streamingStartRef` is set at `chat.tsx:3874`                                                        |
+| **Token counter (aggregate)**      | ✅ Live `↓ Xk tokens`                   | ⚠️ Partially works                                      | Sub-agent `stream.usage` events DO hit bus → `streamingMeta.outputTokens` accumulates from all agents combined |
+| **Token counter (per-agent)**      | N/A                                     | ❌ Not shown                                            | `SubagentStreamResult.tokenUsage` computed but not displayed in agent tree                                     |
+| **Thinking seconds (aggregate)**   | ✅ `thought for Xs`                     | ⚠️ Partially works                                      | `stream.thinking.complete` hits bus → `streamingMeta.thinkingMs` uses `Math.max` across all agents             |
+| **Thinking seconds (per-agent)**   | N/A                                     | ❌ Not shown                                            | `SubagentStreamResult.thinkingDurationMs` computed but not displayed                                           |
+| **Thinking blocks content**        | ✅ `ReasoningPart` with text            | ⚠️ Needs routing                                        | Sub-agent thinking deltas need `routeToAgentInlineParts()` handling for `thinking-meta` events                 |
+| **Streaming text**                 | ✅ Incremental via `TextPart`           | ⚠️ Events published, rendering depends on pipeline path | `stream.text.delta` with `agentId` → should route to agent `inlineParts`                                       |
+| **Tool calls**                     | ✅ `ToolPart` with lifecycle            | ⚠️ Events published                                     | `stream.tool.*` with `parentAgentId` → should route to agent `inlineParts`                                     |
+| **Sub-agent tree**                 | ✅ Full tree                            | ✅ Works                                                | `stream.agent.*` events from `WorkflowEventAdapter` drive the tree                                             |
+| **Sub-agent inline parts**         | ✅ Text/tool within agent row           | ❌ Not populated                                        | Agent `inlineParts[]` remains empty because events aren't routed there                                         |
+| **Completion summary (overall)**   | ✅ `⣿ Reasoned for Xm Xs · ↓ Xk tokens` | ⚠️ Shows but missing per-agent data                     | `durationMs` works; `outputTokens`/`thinkingMs` reflect aggregate of all agents                                |
+| **Completion summary (per-agent)** | N/A                                     | ❌ Not shown                                            | `AgentRow` in `ParallelAgentsTree` shows elapsed time but no tokens/thinking                                   |
+| **Context compaction**             | ✅ `/compact` clears and summarizes     | ❌ Not applicable                                       | Workflow sessions are independent — compaction doesn't apply mid-workflow                                      |
+| **Verbose mode (Ctrl+E)**          | ✅ Toggles tool expansion               | ✅ Would work                                           | Parts-based rendering respects verbose mode automatically                                                      |
+| **Task list**                      | ✅ `TaskListPart`                       | ✅ Works via file watcher                               | `watchTasksJson()` at `workflow-commands.ts:718` drives `TaskListPanel`                                        |
+
+### Key State Variables for Workflow Feature Parity
+
+| State/Ref                            | Location             | Workflow Behavior                                        |
+| ------------------------------------ | -------------------- | -------------------------------------------------------- |
+| `streamingMeta` / `streamingMetaRef` | `chat.tsx:1627,1854` | Accumulates tokens/thinking from ALL sub-agents combined |
+| `streamingElapsedMs`                 | `chat.tsx:1626`      | Ticks for the workflow message (works)                   |
+| `streamingStartRef`                  | `chat.tsx:1847`      | Set at workflow start (`chat.tsx:3874`)                  |
+| `streamingMessageIdRef`              | `chat.tsx:1839`      | Points to the workflow wrapper message                   |
+| `ChatMessage.spinnerVerb`            | `chat.tsx:618`       | Set to `"Running workflow"` at `chat.tsx:3868`           |
+| `ChatMessage.outputTokens`           | `chat.tsx:612`       | Baked from aggregate `streamingMeta`                     |
+| `ChatMessage.thinkingMs`             | `chat.tsx:614`       | Baked from aggregate `streamingMeta`                     |
+| `ChatMessage.durationMs`             | `chat.tsx:594`       | Set on `handleStreamComplete()`                          |
+
+### Architecture Summary: What's Actually Working vs What's Not
+
+```
+WORKFLOW SUB-AGENT EVENT FLOW (current state):
+═══════════════════════════════════════════════
+
+SubagentStreamAdapter.consumeStream()       [subagent-adapter.ts:136]
+  │
+  ├── publishes stream.text.delta           ✅ Published to bus
+  │     → CorrelationService enriches       ✅ agentId resolved
+  │     → StreamPipelineConsumer maps       ✅ Creates text-delta StreamPartEvent
+  │     → useStreamConsumer callback        ✅ Receives event
+  │     → applyStreamPartEvent reducer      ⚠️ Routes to agent inlineParts IF agentId matches
+  │     → AgentPartDisplay renders          ❓ Depends on timing (agent may not exist in parts yet)
+  │
+  ├── publishes stream.usage                ✅ Published to bus
+  │     → useBusSubscription callback       ✅ Updates streamingMeta.outputTokens
+  │     → bakes onto workflow message       ✅ Aggregate token count visible in spinner
+  │     → per-agent display                 ❌ Not wired
+  │
+  ├── publishes stream.thinking.delta       ✅ Published to bus
+  │     → StreamPipelineConsumer maps       ✅ Creates thinking-meta StreamPartEvent
+  │     → useStreamConsumer callback        ✅ Accumulates thinkingText
+  │     → applyStreamPartEvent reducer      ⚠️ Creates ReasoningPart on main message, not per-agent
+  │
+  ├── publishes stream.thinking.complete    ✅ Published to bus
+  │     → useBusSubscription callback       ✅ Updates streamingMeta.thinkingMs (Math.max)
+  │     → bakes onto workflow message       ✅ Aggregate thinking time visible
+  │     → per-agent display                 ❌ Not wired
+  │
+  ├── publishes stream.tool.start/complete  ✅ Published to bus
+  │     → CorrelationService enriches       ✅ parentAgentId resolved
+  │     → StreamPipelineConsumer maps       ✅ Creates tool-start/tool-complete StreamPartEvent
+  │     → useStreamConsumer callback        ✅ Receives event
+  │     → applyStreamPartEvent reducer      ⚠️ Routes to agent inlineParts IF agentId matches
+  │
+  ├── publishes stream.agent.start          ✅ Published to bus
+  │     → useBusSubscription (chat.tsx:2946)✅ Creates ParallelAgent entry
+  │     → useEffect bridge → AgentPart      ✅ Agent appears in tree
+  │
+  └── publishes stream.agent.complete       ✅ Published to bus
+        → useBusSubscription (chat.tsx:2973)✅ Updates agent status to complete
+        → tree shows completion icon        ✅ Visual feedback
+
+SUMMARY:
+  ✅ Events are published by SubagentStreamAdapter
+  ✅ Aggregate token/thinking counters work on the workflow message spinner
+  ✅ Agent tree (start/complete lifecycle) works
+  ⚠️ Agent inline parts (text/tool/thinking within agent rows) may work
+     but depends on reducer timing and agent materialization in parts[]
+  ❌ Per-agent token and thinking metrics not displayed in tree
+  ❌ Per-agent completion summary not implemented
+```
+
+---
+
+## Follow-up Research: Additional Feature Parity Gaps
+
+### Finding 7: Workflow Errors Are Plain Text, Not Structured Error Parts
+
+**Main chat:** Tool errors produce structured `ToolState` with `status: "error"` (`stream-pipeline.ts:380-382`), rendered with red icons (`STATUS.error` = ✗), red borders (`colors.error`), and inline error content via `ToolResult` at `tool-result.tsx:55-74`.
+
+**Workflow:** The executor produces plain text `context.addMessage()` calls for failures:
+
+- Graph step failure: `executor.ts:437-439` → `context.addMessage("assistant", \`**${definition.name}** workflow failed at node "${lastNodeId}"...\`)`
+- Catch block: `executor.ts:482-485` → `CommandResult` with `success: false, message: "Workflow failed: ..."`
+
+Sub-agent tool errors within a workflow DO get proper `ToolPart` error states (they flow through the event bus pipeline), but workflow-level failures (node failure, uncaught exception) are plain text.
+
+### Finding 8: HITL/Tool Approval Auto-Approved During Workflows
+
+All SDK permission requests are auto-approved when `workflowState.workflowActive` is true:
+
+- `chat.tsx:3208-3213`: Permission requests → auto-responds with `options[0]?.value ?? "allow"`
+- `chat.tsx:3277-3283`: AskUserQuestion events → auto-responds with `options?.[0]?.label ?? "continue"`
+
+The `UserQuestionDialog` is never shown during workflows. The only exception is graph-level `human_input_required` signals (`compiled.ts:468-483`) which pause the graph — but this is a graph signal, not SDK-level tool approval.
+
+### Finding 9: Ctrl+C Requires Double-Press to Terminate Workflows
+
+**Main chat:** Single Ctrl+C fully stops the operation, interrupts tools, separates foreground/background agents.
+
+**Workflow:**
+
+- Single Ctrl+C (`chat.tsx:4876`): Cancels only the current sub-agent stream; workflow continues to next graph step
+- Double Ctrl+C while streaming (`chat.tsx:4852-4854`): Sets `wasCancelled: true` on stream resolver
+- Double Ctrl+C not streaming (`chat.tsx:4960-4966`): Calls `updateWorkflowState({ workflowActive: false })` and rejects `waitForUserInputResolverRef`
+
+### Finding 10: MCP Snapshots and Skill Loading Inaccessible During Workflows
+
+**MCP snapshots:** Triggered exclusively by the `/mcp` slash command (`builtin-commands.ts:510-564`). The workflow executor never invokes slash commands, and sub-agent SDK sessions don't have access to the command registry.
+
+**Skill loading:** Triggered exclusively by skill slash commands (`skill-commands.ts:336-341`). The `skillLoaded` field on `CommandResult` populates `SkillLoadPart` in `chat.tsx:4488-4504`. Workflows and sub-agents have no mechanism to trigger skill loading.
+
+### Finding 11: Session Recovery Infrastructure Exists but Is Not Wired
+
+**What's persisted:**
+
+- `session.json` with `sessionId`, `workflowName`, `status: "running"`, `nodeHistory`, `outputs` (`session.ts:64-76`)
+- `tasks.json` via debounced atomic writes (`workflow-commands.ts:250-285`)
+- Per-agent results at `agents/{agentId}.json` (`session.ts:87-95`)
+
+**What's not wired:**
+
+- Checkpointer infrastructure exists (`MemoryCheckpointSaver`, `FileSaver`, `ResearchCheckpointSaver` at `checkpointer.ts`)
+- `resumeFrom?: ExecutionSnapshot` is accepted by `streamSteps()` (`compiled.ts:350-362`)
+- But `executeWorkflow()` never configures a checkpointer and never passes `resumeFrom`
+- `session.json` status is never updated from `"running"` to `"completed"`/`"failed"`
+
+### Finding 12: Agent Inline Parts Render as Plain Text, Not Markdown
+
+**Main chat text:** `TextPartDisplay` at `text-part-display.tsx:41-86` renders full markdown with syntax highlighting via `<markdown>` or `<code filetype="markdown">`, streaming cursor support, and text selection.
+
+**Agent inline text:** `AgentInlineText` at `parallel-agents-tree.tsx:642-668` renders as a plain `<text>` element, truncated to 200 characters, with a `●` prefix. No markdown parsing, no syntax highlighting, no concealment.
+
+The `TextPart` objects within `agent.inlineParts` are structurally identical to top-level `TextPart` objects (same type, same `isStreaming` flag), but they bypass `PART_REGISTRY` dispatch entirely — `ParallelAgentsTree` has its own internal `AgentInlineParts` renderer.
+
+### Finding 13: Message Queue Blocked During Workflow Execution
+
+Users CAN enqueue messages during workflows via Ctrl+Shift+Enter (no `workflowActive` guard in the keyboard handler at `chat.tsx:5487-5510`). However, dequeue is blocked because `isStreaming` stays `true` across graph step boundaries (`chat.tsx:4248-4255` skips `setStreamingWithFinalize(false)` when `workflowActiveRef.current` is true).
+
+Even after ESC interrupt, queued messages are not auto-dispatched if `workflowState.workflowActive` is true (`chat.tsx:5197`).
+
+### Finding 14: Input Submission Can Resolve `waitForUserInput` After Ctrl+C
+
+The textarea is never disabled during workflows. When a user types after single Ctrl+C, if `waitForUserInputResolverRef.current` is set (`chat.tsx:5908-5916`), the submission resolves the pending promise and feeds the response back into the graph's `human_input_required` handler — not into a new stream.
+
+### Finding 15: WorkflowStepPartDisplay and TaskListPanel Are Workflow-Exclusive
+
+Two UI components exist only in the workflow rendering path:
+
+- `WorkflowStepPartDisplay` (`workflow-step-part-display.tsx:25-53`): Renders step transition markers `── Step: {name} ● ──`
+- `TaskListPanel` (`task-list-panel.tsx:157`): Progress bar (`━`/`╌`), header with counter, status summary, numbered task rows — rendered only when `workflowSessionDir` is set
+
+These are workflow advantages over main chat, not gaps.
+
+### Finding 16: Text Accumulation in Agent InlineParts Has No `message.content` Mirror
+
+Main chat text accumulates into both `TextPart.content` (in `parts[]`) AND `message.content` (flat string) at `stream-pipeline.ts:995-998`. Agent inline text accumulates only into `TextPart.content` within `inlineParts[]` — no `message.content` equivalent exists per-agent. This means search, copy, or transcript features that rely on `message.content` would not include sub-agent text.
+
+### Comprehensive Feature Parity Matrix
+
+| Feature                        | Main Chat                          | Workflow (Current)                                  | Gap Severity       |
+| ------------------------------ | ---------------------------------- | --------------------------------------------------- | ------------------ |
+| Spinner animation              | ✅ Braille 120ms                   | ✅ "Running workflow…"                              | None               |
+| Elapsed timer                  | ✅ 1s ticks                        | ✅ Works                                            | None               |
+| Token counter (aggregate)      | ✅ Live `↓ Xk tokens`              | ✅ Accumulates from all agents                      | None               |
+| Token counter (per-agent)      | N/A                                | ❌ Not displayed                                    | Medium             |
+| Thinking seconds (aggregate)   | ✅ `thought for Xs`                | ✅ Math.max across agents                           | None               |
+| Thinking seconds (per-agent)   | N/A                                | ❌ Not displayed                                    | Medium             |
+| Thinking block content         | ✅ ReasoningPart rendered          | ⚠️ Routed to inlineParts but rendered as plain text | High               |
+| Streaming text                 | ✅ Incremental markdown            | ⚠️ InlineParts: plain text, 200 char truncation     | High               |
+| Tool call rendering            | ✅ ToolPart lifecycle with rich UI | ⚠️ InlineParts: plain text summary                  | High               |
+| Sub-agent tree                 | ✅ Full tree with status           | ✅ Works                                            | None               |
+| Agent inline parts (markdown)  | N/A (main chat has no agents)      | ❌ Plain text only                                  | High               |
+| Completion summary (overall)   | ✅ `⣿ Reasoned for Xm`             | ✅ Works with aggregate data                        | None               |
+| Completion summary (per-agent) | N/A                                | ❌ Not implemented                                  | Low                |
+| Error display                  | ✅ Structured ToolState.error      | ❌ Plain text addMessage                            | High               |
+| HITL / Tool approval           | ✅ Interactive dialog              | ❌ Auto-approved                                    | Medium             |
+| Abort behavior                 | ✅ Single Ctrl+C                   | ⚠️ Double Ctrl+C required                           | Low                |
+| MCP snapshots                  | ✅ Via /mcp command                | ❌ Not accessible                                   | Low                |
+| Skill loading                  | ✅ Via skill commands              | ❌ Not accessible                                   | Low                |
+| Session recovery               | N/A                                | ❌ Infrastructure exists but unwired                | Medium             |
+| Markdown rendering             | ✅ Full syntax highlighting        | ❌ Plain text in agent rows                         | High               |
+| Queue during workflow          | ✅ Enqueue + auto-dequeue          | ⚠️ Enqueue works, dequeue blocked                   | Low                |
+| Context compaction             | ✅ /compact                        | ❌ Not applicable mid-workflow                      | N/A                |
+| Verbose mode (Ctrl+E)          | ✅ Toggles tool expansion          | ✅ Would work via parts pipeline                    | None               |
+| Task list                      | ✅ TaskListPart                    | ✅ File watcher + TaskListPanel                     | None               |
+| Workflow step markers          | N/A                                | ✅ WorkflowStepPartDisplay                          | Workflow advantage |
+| Progress bar                   | N/A                                | ✅ TaskListPanel progress bar                       | Workflow advantage |
+
+### Additional Code References (Follow-up 2)
+
+#### Error Handling
+
+- `src/ui/parts/types.ts:42-43` — `ToolState` error/interrupted variants
+- `src/ui/parts/stream-pipeline.ts:380-382` — Tool error state assignment
+- `src/ui/components/tool-result.tsx:55-74` — Error icon/color mapping
+- `src/workflows/executor.ts:435-451` — Graph step failure (plain text addMessage)
+- `src/workflows/executor.ts:466-491` — Catch block error handling
+
+#### HITL / Tool Approval
+
+- `src/ui/chat.tsx:3208-3213` — Auto-approve permissions during workflow
+- `src/ui/chat.tsx:3277-3283` — Auto-approve AskUserQuestion during workflow
+- `src/workflows/graph/compiled.ts:468-483` — Graph-level `human_input_required` signal
+
+#### Abort / Interrupt
+
+- `src/ui/chat.tsx:4779-4890` — Main Ctrl+C handler with workflow branching
+- `src/ui/chat.tsx:4852-4854` — Double Ctrl+C while streaming
+- `src/ui/chat.tsx:4960-4966` — Double Ctrl+C not streaming (terminates workflow)
+- `src/workflows/graph/compiled.ts:368-381` — AbortSignal check per graph step
+
+#### Markdown / Agent Inline Rendering
+
+- `src/ui/components/parts/text-part-display.tsx:41-86` — Full markdown rendering
+- `src/ui/components/parallel-agents-tree.tsx:642-668` — `AgentInlineText` plain text rendering
+- `src/ui/components/parallel-agents-tree.tsx:605-639` — `AgentInlineParts` dispatch
+
+#### Session Recovery
+
+- `src/workflows/session.ts:51-85` — Session init and metadata persistence
+- `src/workflows/graph/checkpointer.ts:52,186,420` — MemoryCheckpointSaver, FileSaver, ResearchCheckpointSaver
+- `src/workflows/graph/compiled.ts:350-362` — `resumeFrom` snapshot handling (dormant)
+
+#### Queue / Input
+
+- `src/ui/hooks/use-message-queue.ts:129-286` — Queue hook implementation
+- `src/ui/chat.tsx:5487-5510` — Enqueue keyboard handler (no workflow guard)
+- `src/ui/utils/stream-continuation.ts:133-135` — `shouldDispatchQueuedMessage` (blocked by isStreaming)
+- `src/ui/chat.tsx:5908-5916` — Input resolves `waitForUserInput` after Ctrl+C
+
+### Additional Code References (Follow-up)
+
+#### Spinner & Token Counter
+
+- `src/ui/chat.tsx:1033-1071` — `LoadingIndicator` component (braille spinner + info parts)
+- `src/ui/chat.tsx:2888-2919` — `stream.usage` bus subscription (token accumulation)
+- `src/ui/chat.tsx:2009-2022` — Elapsed time interval tick
+- `src/ui/chat.tsx:3079` — `streamingStartRef.current = Date.now()` in `startAssistantStream()`
+- `src/ui/chat.tsx:3868-3874` — Workflow spinner verb override: `"Running workflow"`
+- `src/ui/constants/icons.ts:51-60` — `SPINNER_FRAMES` braille characters
+- `src/ui/constants/icons.ts:62` — `SPINNER_COMPLETE` = `⣿`
+
+#### Thinking Duration
+
+- `src/events/adapters/claude-adapter.ts:227-268` — Thinking delta/complete emission
+- `src/events/consumers/stream-pipeline-consumer.ts:138-148` — `thinking-meta` mapping
+- `src/ui/chat.tsx:2720-2774` — Thinking meta processing in stream consumer
+- `src/ui/chat.tsx:2922-2943` — `stream.thinking.complete` bus subscription
+- `src/ui/components/parts/reasoning-part-display.tsx:47-97` — Thinking block renderer
+
+#### Compact UI
+
+- `src/ui/commands/builtin-commands.ts:239-277` — `/compact` command
+- `src/ui/chat.tsx:1416-1461` — Collapsed message rendering
+- `src/ui/hooks/use-verbose-mode.ts:63-101` — Verbose mode hook (Ctrl+E)
+- `src/ui/components/parts/compaction-part-display.tsx:18-33` — Compaction banner renderer
+- `src/ui/utils/auto-compaction-lifecycle.ts:18-29` — Auto-compaction detection
+- `src/ui/components/parts/agent-part-display.tsx:77-104` — Dynamic compact toggle for agent trees
+
+#### Completion Summary
+
+- `src/ui/chat.tsx:1112-1134` — `CompletionSummary` component
+- `src/ui/utils/loading-state.ts:69-77` — `shouldShowCompletionSummary()` gating
+- `src/ui/chat.tsx:2493-2623` — `handleStreamComplete()` data baking
+- `src/events/adapters/subagent-adapter.ts:533-566` — `SubagentStreamResult.buildResult()` with per-agent metrics
+
+#### Other Streaming UI
+
+- `src/ui/components/footer-status.tsx:39-101` — Footer status bar (streaming/workflow hints)
+- `src/ui/components/animated-blink-indicator.tsx:16-33` — Shared blinking `●`/`·` indicator
+- `src/ui/chat.tsx:1146-1158` — `StreamingBullet` animated text prefix
+- `src/ui/components/task-list-panel.tsx:157-179` — File-driven task list
+- `src/ui/components/queue-indicator.tsx:25-38` — Message queue indicator
diff --git a/research/docs/2026-03-01-opencode-auto-compaction.md b/research/docs/2026-03-01-opencode-auto-compaction.md
new file mode 100644
index 0000000000..b074049222
--- /dev/null
+++ b/research/docs/2026-03-01-opencode-auto-compaction.md
@@ -0,0 +1,606 @@
+---
+date: 2026-03-01 19:33:01 UTC
+researcher: Copilot (Claude Opus 4.6)
+git_commit: 7debf4841f53cc01dbe3faa8bc4b00a9367bb7a6
+branch: lavaman131/feature/workflow-sdk
+repository: workflow-sdk
+topic: "OpenCode SDK Auto-Compaction: Current State and Reference Implementations"
+tags: [research, codebase, compaction, context-overflow, opencode, claude, copilot, auto-compaction, tui, spinner]
+status: complete
+last_updated: 2026-03-01
+last_updated_by: Copilot (Claude Opus 4.6)
+---
+
+# Research: OpenCode SDK Auto-Compaction
+
+## Research Question
+
+The other SDKs (Claude Agent SDK, Copilot SDK) have auto-compact behavior, but the OpenCode SDK implementation seems to be missing it. For example, a `ContextOverflowError` is thrown without recovery:
+
+```
+✗ {"name":"ContextOverflowError","data":{"message":"Input exceeds context window of this model","responseBody":"..."}}
+```
+
+Document how auto-compaction works in the Claude and Copilot integrations (including compaction spinner and TUI clearing), how the upstream OpenCode codebase handles compaction natively, and what the OpenCode SDK integration in workflow-sdk currently does (and doesn't do).
+
+## Summary
+
+The workflow-sdk has a well-developed compaction system for the Copilot SDK (native `infiniteSessions` auto-compaction with event-based lifecycle) and Claude SDK (tool-name detection + `session.compaction` bus events + `/compact` prompt forwarding). The OpenCode SDK integration has partial compaction support — it implements `summarize()` and maps the upstream `session.compacted` SSE event — but **lacks automatic context overflow detection and recovery**. The upstream OpenCode codebase has a full auto-compaction system (`SessionCompaction.isOverflow()` → `SessionCompaction.create()` → `SessionCompaction.process()`) that detects overflow proactively and triggers LLM-driven summarization, but this workflow-sdk integration does not wire into that flow. Critically, when a `ContextOverflowError` occurs during streaming, the OpenCode client treats it as a generic fatal error with no compaction recovery path.
+
+### Key Gaps in OpenCode SDK Integration
+
+1. **No `phase: "start"` emission** — Only `phase: "complete"` is emitted via `session.compacted` SSE event; the TUI never shows "Compacting…" spinner during auto-compaction
+2. **No automatic overflow detection** — No proactive token-based threshold check before or during streaming
+3. **No `ContextOverflowError` recovery** — Context overflow errors are treated as generic fatal stream errors
+4. **No `session.truncation` emission** — The event type exists in the type system and adapter, but the OpenCode client never emits it
+5. **No `infiniteSessions`-style config** — No compaction thresholds passed at session creation (unlike Copilot)
+6. **Workflow graph partially compensates** — The `contextMonitorNode` calls `summarize()` for OpenCode at 45% threshold, but this only works in workflow mode, not in direct chat
+
+---
+
+## Detailed Findings
+
+### 1. Copilot SDK Integration — Auto-Compaction (Reference Implementation)
+
+The Copilot SDK has the most complete auto-compaction implementation, with native SDK support via `infiniteSessions`.
+
+#### Session Creation with Compaction Thresholds
+
+**`src/sdk/clients/copilot.ts:1116-1120`**
+
+```typescript
+infiniteSessions: {
+  enabled: true,
+  backgroundCompactionThreshold: BACKGROUND_COMPACTION_THRESHOLD, // 0.45
+  bufferExhaustionThreshold: BUFFER_EXHAUSTION_THRESHOLD,         // 0.6
+},
+```
+
+The Copilot SDK is configured at session creation to automatically trigger compaction when context reaches 45% and buffer exhaustion at 60%.
+
+#### SDK Event Mapping
+
+**`src/sdk/clients/copilot.ts:155-166`** — Two SDK events map to one unified event:
+- `"session.compaction_start"` → `"session.compaction"` with `{ phase: "start" }`
+- `"session.compaction_complete"` → `"session.compaction"` with `{ phase: "complete", success, error }`
+
+**`src/sdk/clients/copilot.ts:889-900`** — Event data construction in `handleSdkEvent()`:
+```typescript
+case "session.compaction_start":
+  eventData = { phase: "start" };
+  break;
+case "session.compaction_complete":
+  eventData = {
+    phase: "complete",
+    success: typeof data.success === "boolean" ? data.success : true,
+    error: asNonEmptyString(data.error),
+  };
+  break;
+```
+
+#### Manual `/compact` Command
+
+**`src/sdk/clients/copilot.ts:604-611`** — `session.summarize()` sends `/compact` as a prompt:
+```typescript
+summarize: async (): Promise<void> => {
+  if (state.isClosed) throw new Error("Session is closed");
+  await state.sdkSession.sendAndWait({ prompt: "/compact" });
+},
+```
+
+#### Three-Layer Event Translation
+
+1. Copilot SDK events (`session.compaction_start`) 
+2. → Unified `AgentEvent` (`session.compaction`) via `copilot.ts:889-900`
+3. → Bus events (`stream.session.compaction`) via `copilot-adapter.ts:1115-1130`
+
+#### Data Flow
+
+1. Session created with `infiniteSessions` config (thresholds 0.45/0.6)
+2. SDK detects threshold breach internally
+3. SDK emits `session.compaction_start` → mapped to `{ phase: "start" }`
+4. Adapter publishes `stream.session.compaction` on event bus
+5. TUI handler calls `applyAutoCompactionIndicator({ status: "running" })`
+6. Spinner verb overridden to `"Compacting"` on streaming message
+7. SDK completes → emits `session.compaction_complete` → `{ phase: "complete", success: true }`
+8. TUI handler calls `applyAutoCompactionIndicator({ status: "completed" })`
+9. All messages cleared, new empty streaming message created, history buffer reset
+
+---
+
+### 2. Claude Agent SDK Integration — Auto-Compaction
+
+The Claude integration uses a dual-detection approach: tool-name pattern matching and `session.compaction` bus events.
+
+#### `summarize()` Implementation
+
+**`src/sdk/clients/claude.ts:1027-1053`**
+
+1. Guards for closed session
+2. Builds SDK options with `resume` support
+3. Sends `query({ prompt: "/compact", options })` to Claude SDK
+4. Iterates all response messages via `processMessage()`
+5. Re-throws any errors
+
+The Claude client does **not** emit `session.compaction` events during `summarize()`. Compaction events come from either the SDK's internal hooks or tool-name detection.
+
+#### `PreCompact` Hook
+
+**`src/sdk/clients/claude.ts:78`** — `ClaudeHookConfig` includes `PreCompact?: HookCallback[]`, but `mapEventTypeToHookEvent()` (lines 127-138) does not map any unified event type to `PreCompact`. Hooks are only registered via `registerHooks()`.
+
+#### Tool-Name Auto-Compaction Detection
+
+The TUI layer detects compaction via tool names in `handleToolStart` and `handleToolComplete` (see §5 TUI section).
+
+#### Workflow Graph Strategy
+
+**`src/workflows/graph/nodes.ts:1263-1274`** — For Claude, `getDefaultCompactionAction()` returns `"recreate"` (not `"summarize"`). The `contextMonitorNode` emits a `context_window_warning` signal with `shouldRecreateSession: true` rather than calling `summarize()`.
+
+---
+
+### 3. OpenCode SDK Integration — Current State
+
+#### What Exists
+
+##### `summarize()` Method
+
+**`src/sdk/clients/opencode.ts:2107-2145`**
+
+1. Calls `client.sdkClient.session.summarize()` with `sessionID` and `directory`
+2. Post-compaction: queries `session.messages()` to refresh token counts
+3. Silently catches token refresh errors
+4. Emits `session.idle` with `reason: "context_compacted"` — **not** `session.compaction`
+
+##### SSE Event Mapping for `session.compacted`
+
+**`src/sdk/clients/opencode.ts:987-996`**
+
+```typescript
+case "session.compacted":
+  this.emitEvent("session.compaction", sessionID, {
+    phase: "complete",
+    success: true,
+  });
+  break;
+```
+
+Only emits `phase: "complete"` — there is no `phase: "start"` emitted anywhere in the OpenCode client.
+
+##### Context Usage Tracking
+
+**`src/sdk/clients/opencode.ts:1732-1738, 2147-2160`**
+
+Session state tracks `inputTokens`, `outputTokens`, `contextWindow`, and `systemToolsBaseline`. The `getContextUsage()` method computes usage percentage.
+
+##### Event Adapter Wiring
+
+**`src/events/adapters/opencode-adapter.ts:280-291`** — The adapter subscribes to both `session.compaction` and `session.truncation` from the client. However, the client only ever emits `session.compaction` (with `phase: "complete"`), and **never** emits `session.truncation`.
+
+##### Workflow-Level Compaction
+
+**`src/workflows/graph/nodes.ts:1263-1266`** — `getDefaultCompactionAction("opencode")` returns `"summarize"`, meaning the `contextMonitorNode` will call `session.summarize()` at 45% threshold. This only works in workflow mode.
+
+#### What's Absent
+
+| Feature | Copilot | Claude | OpenCode |
+|---------|---------|--------|----------|
+| `phase: "start"` emission | ✅ `session.compaction_start` | ✅ Via SDK hooks | ❌ Never emitted |
+| `phase: "complete"` emission | ✅ `session.compaction_complete` | ✅ Via SDK hooks | ✅ `session.compacted` SSE |
+| Auto-compaction thresholds at session creation | ✅ `infiniteSessions` config | ❌ | ❌ |
+| Tool-name-based detection | ✅ (secondary path) | ✅ (primary path) | ❌ (no compaction tools emitted) |
+| `session.truncation` emission | ✅ With token details | ❌ | ❌ (adapter subscribed but never fires) |
+| `ContextOverflowError` handling | ❌ (generic error) | ❌ (generic error) | ❌ (generic error) |
+| Automatic overflow detection during streaming | ✅ (SDK-native) | ❌ (workflow-level) | ❌ (workflow-level only) |
+| Post-compaction token refresh | Via SDK events | Via message processing | ✅ Via `session.messages()` query |
+
+##### Error Handling Gap
+
+**`src/sdk/clients/opencode.ts:1995-2001, 2089-2091`** — During streaming, `session.error` SSE events are caught and converted to generic `Error` objects. There is no differentiation of `ContextOverflowError` — all errors are treated uniformly as fatal stream errors.
+
+The string `"ContextOverflowError"` does not appear anywhere in the workflow-sdk codebase.
+
+---
+
+### 4. Upstream OpenCode — Native Auto-Compaction System
+
+The upstream OpenCode project at `~/Documents/projects/opencode` has a comprehensive auto-compaction system.
+
+#### Overflow Detection
+
+**`packages/opencode/src/session/compaction.ts:32-48`** — `SessionCompaction.isOverflow()`
+
+1. Checks `config.compaction.auto` — returns `false` if disabled
+2. If model `limit.context === 0`, returns `false` (unlimited)
+3. Computes token count: `total` or `input + output + cache.read + cache.write`
+4. Computes reserved buffer: `config.compaction.reserved` or `min(COMPACTION_BUFFER=20000, maxOutputTokens)`
+5. Computes usable context: `limit.input - reserved` or `limit.context - maxOutputTokens`
+6. Returns `count >= usable`
+
+#### Detection Trigger Points
+
+**Path A — Mid-stream (`packages/opencode/src/session/processor.ts:282-284`):**
+On `"finish-step"` event during LLM streaming, checks `isOverflow()`. If true, sets `needsCompaction = true` and breaks the stream loop. Returns `"compact"` from `process()`.
+
+**Path B — Pre-loop (`packages/opencode/src/session/prompt.ts:541-554`):**
+At the start of each `SessionPrompt.loop()` iteration, checks `isOverflow()` on the last finished assistant message. If overflow and not already summarized (`summary !== true`), calls `SessionCompaction.create()` and continues.
+
+#### Compaction Execution
+
+**`packages/opencode/src/session/compaction.ts:101-229`** — `SessionCompaction.process()`
+
+1. Resolves compaction model (dedicated `"compaction"` agent's model or fallback)
+2. Creates assistant message with `mode: "compaction"`, `summary: true`
+3. Triggers `experimental.session.compacting` plugin hook
+4. Builds compaction prompt (default template or plugin-provided)
+5. Sends conversation + compaction prompt to LLM (no tools available)
+6. On auto-compaction, creates synthetic "Continue" user message
+7. Publishes `Bus.publish(Event.Compacted, { sessionID })`
+
+#### Default Compaction Prompt Template
+
+```
+Provide a detailed prompt for continuing our conversation above.
+Focus on information that would be helpful for continuing the conversation...
+
+When constructing the summary, try to stick to this template:
+---
+## Goal
+[What goal(s) is the user trying to accomplish?]
+
+## Instructions
+[What important instructions did the user give you that are relevant]
+
+## Discoveries
+[What notable things were learned during this conversation...]
+
+## Accomplished
+[What work has been completed, what work is still in progress...]
+
+## Relevant files / directories
+[Structured list of relevant files that have been read, edited, or created...]
+---
+```
+
+#### Message History Filtering Post-Compaction
+
+**`packages/opencode/src/session/message-v2.ts:794-809`** — `filterCompacted()` truncates message history to only messages from the latest compaction point forward. The summary replaces all prior history for subsequent LLM calls.
+
+#### Tool Output Pruning
+
+**`packages/opencode/src/session/compaction.ts:50-99`** — `SessionCompaction.prune()`
+
+- Iterates messages backwards, skipping the most recent 2 user turns
+- Protects `PRUNE_PROTECT=40000` tokens of recent tool outputs
+- If prunable tokens exceed `PRUNE_MINIMUM=20000`, marks them with `time.compacted = Date.now()`
+- Pruned tool outputs replaced with `"[Old tool result content cleared]"` in model messages
+
+#### Context Overflow Error Detection (14+ Providers)
+
+**`packages/opencode/src/provider/error.ts:8-41`** — `ProviderError.isOverflow()` matches error messages against regex patterns for Anthropic, OpenAI, Google, Amazon Bedrock, xAI, Groq, OpenRouter, DeepSeek, GitHub Copilot, llama.cpp, LM Studio, MiniMax, Kimi, Cerebras, Mistral, and a generic fallback.
+
+**`packages/opencode/src/session/retry.ts`** — `ContextOverflowError` is explicitly non-retryable.
+
+**`packages/opencode/src/session/processor.ts:356-358`** — Currently has a `TODO` for handling `ContextOverflowError` specifically:
+```typescript
+if (MessageV2.ContextOverflowError.isInstance(error)) {
+  // TODO: Handle context overflow error
+}
+```
+
+#### Configuration
+
+| Setting | Default | Effect |
+|---------|---------|--------|
+| `compaction.auto` | `true` | Enable/disable auto-compaction |
+| `compaction.prune` | `true` | Enable/disable tool output pruning |
+| `compaction.reserved` | `min(20000, maxOutputTokens)` | Token buffer before overflow triggers |
+| `OPENCODE_DISABLE_AUTOCOMPACT` | `false` | Env var to disable auto-compaction |
+| `OPENCODE_DISABLE_PRUNE` | `false` | Env var to disable pruning |
+
+#### TUI Representation
+
+**`packages/opencode/src/cli/cmd/tui/routes/session/index.tsx:441-467`** — Manual `/compact` command with alias `/summarize` and keybind `<leader>c`.
+
+**`index.tsx:1295-1302`** — Compaction part renders a horizontal divider with centered " Compaction " title.
+
+**`packages/opencode/src/cli/cmd/tui/context/sync.tsx:450-458`** — Session status returns `"compacting"` when `session.time.compacting` is set.
+
+#### Event System
+
+```typescript
+export const Event = {
+  Compacted: BusEvent.define("session.compacted", z.object({ sessionID: z.string() })),
+}
+```
+
+Published after successful LLM summarization. Subscribers can react to compaction completion.
+
+---
+
+### 5. TUI Compaction UI Patterns (Shared Across SDKs)
+
+#### LoadingIndicator Component
+
+**`src/ui/chat.tsx:1083-1121`**
+
+Renders animated braille-character spinner (8 frames: `⣾ ⣽ ⣻ ⢿ ⡿ ⣟ ⣯ ⣷`) at 100ms intervals.
+
+Verb resolution priority:
+1. `verbOverride` (e.g., `"Compacting"`) — highest priority
+2. `"Reasoning"` if `thinkingMs > 0`
+3. `"Composing"` — default
+
+Output format: `⣾ Compacting… (6m 22s · ↓ 16.7k tokens · thought for 54s)`
+
+#### Spinner Verb Override for `/compact`
+
+**`src/ui/chat.tsx:1003-1005`**
+```typescript
+export function getSpinnerVerbForCommand(commandName: string): string | undefined {
+  return commandName === "compact" ? "Compacting" : undefined;
+}
+```
+
+#### Auto-Compaction Indicator State Machine
+
+**`src/ui/utils/auto-compaction-lifecycle.ts`**
+
+Four states: `idle` → `running` → `completed`/`error` → `idle`
+
+Tool name detection (`isAutoCompactionToolName`, lines 18-29):
+- Exact: `"compact"`
+- Suffix: `"/compact"`, `"__compact"`
+- Contains: `"precompact"`, `"context_compact"`, `"context-compact"`, `"auto_compact"`, `"auto-compact"`
+
+#### `applyAutoCompactionIndicator()` — Visual Transitions
+
+**`src/ui/chat.tsx:2314-2361`**
+
+| Status | Effect |
+|--------|--------|
+| `"running"` | `isAutoCompacting = true`, spinner verb → `"Compacting"` on streaming message |
+| `"completed"` | `isAutoCompacting = false`, clear all messages, create fresh streaming message, write compaction summary to history buffer |
+| `"error"` | `isAutoCompacting = false`, clear `"Compacting"` verb override, revert spinner to default |
+| `"idle"` | `isAutoCompacting = false` |
+
+#### Message Clearing After Compaction
+
+On `"completed"`:
+1. Creates new empty assistant message via `createMessage("assistant", "", true)`
+2. Updates `streamingMessageIdRef` to new message
+3. Calls `clearHistoryBuffer()` then `appendCompactionSummary(summaryText)`
+4. Replaces all visible messages: `return [newMsg]`
+
+#### Compaction History (Ctrl+O)
+
+**`src/ui/chat.tsx:5629-5632`** — `Ctrl+O` toggles `transcriptMode`
+
+**`src/ui/chat.tsx:6658-6666`** — Transcript view renders: `[...readHistoryBuffer(), ...messages]`
+
+After compaction, the history buffer contains the compaction summary marker, and current messages show post-compaction content.
+
+#### CompactionPart Display
+
+**`src/ui/components/parts/compaction-part-display.tsx:18-33`**
+```tsx
+<text style={{ fg: colors.muted }}>
+  {`${MISC.separator} Conversation compacted ${MISC.separator}`}
+</text>
+```
+
+Renders muted-colored banner with separator icons and summary text.
+
+#### Conversation History Buffer
+
+**`src/ui/utils/conversation-history-buffer.ts`**
+
+Persists as NDJSON to `{tmpdir}/atomic-cli/history-{pid}.json`:
+- `appendCompactionSummary(summary)`: Clears buffer, writes single message with `id: compact_{timestamp}_{random}`
+- `clearHistoryBuffer()`: Truncates file, resets dedup Set
+- `readHistoryBuffer()`: Reads NDJSON, populates dedup Set
+
+#### Bus Event Subscriptions
+
+**`src/ui/chat.tsx:3181-3196`** — Subscribes to `stream.session.compaction`:
+```typescript
+useBusSubscription("stream.session.compaction", (event) => {
+  if (phase === "start") applyAutoCompactionIndicator({ status: "running" });
+  else if (phase === "complete") applyAutoCompactionIndicator(success === false ? { status: "error", ... } : { status: "completed" });
+});
+```
+
+This provides a detection path independent of tool-name matching.
+
+---
+
+## Code References
+
+### Workflow-SDK (this codebase)
+
+- `src/sdk/clients/opencode.ts:987-996` — SSE `session.compacted` → unified `session.compaction` mapping (phase: "complete" only)
+- `src/sdk/clients/opencode.ts:2107-2145` — `summarize()` method calling `sdkClient.session.summarize()`
+- `src/sdk/clients/opencode.ts:1995-2001` — Stream error handling (generic, no ContextOverflowError differentiation)
+- `src/sdk/clients/copilot.ts:889-900` — Copilot compaction start/complete event mapping
+- `src/sdk/clients/copilot.ts:1116-1120` — `infiniteSessions` configuration
+- `src/sdk/clients/copilot.ts:604-611` — `summarize()` via `sendAndWait({ prompt: "/compact" })`
+- `src/sdk/clients/claude.ts:1027-1053` — `summarize()` via `query({ prompt: "/compact" })`
+- `src/sdk/types.ts:548-555` — `SessionCompactionEventData` interface
+- `src/events/bus-events.ts:281-290` — `stream.session.compaction` bus event schema
+- `src/events/adapters/opencode-adapter.ts:280-291` — OpenCode adapter compaction/truncation subscriptions
+- `src/events/adapters/copilot-adapter.ts:1115-1130` — Copilot adapter compaction handler
+- `src/events/adapters/claude-adapter.ts:282-286, 953-971` — Claude adapter compaction handler
+- `src/ui/chat.tsx:1003-1005` — `getSpinnerVerbForCommand()` returning `"Compacting"`
+- `src/ui/chat.tsx:1083-1121` — `LoadingIndicator` component
+- `src/ui/chat.tsx:1821-1827` — Compaction React state variables
+- `src/ui/chat.tsx:2314-2361` — `applyAutoCompactionIndicator()` callback
+- `src/ui/chat.tsx:2485-2487` — Tool-name-based auto-compaction detection in `handleToolStart`
+- `src/ui/chat.tsx:2597-2604` — Tool-name-based auto-compaction detection in `handleToolComplete`
+- `src/ui/chat.tsx:3181-3196` — `stream.session.compaction` bus subscription in TUI
+- `src/ui/utils/auto-compaction-lifecycle.ts:1-89` — State machine types, transitions, and helpers
+- `src/ui/utils/conversation-history-buffer.ts:100-113` — `appendCompactionSummary()`
+- `src/ui/components/parts/compaction-part-display.tsx:18-33` — CompactionPart rendering
+- `src/workflows/graph/types.ts:776-779` — `BACKGROUND_COMPACTION_THRESHOLD` and `BUFFER_EXHAUSTION_THRESHOLD`
+- `src/workflows/graph/nodes.ts:1263-1274` — `getDefaultCompactionAction()` per agent type
+
+### Upstream OpenCode (`~/Documents/projects/opencode`)
+
+- `packages/opencode/src/session/compaction.ts:32-48` — `SessionCompaction.isOverflow()` detection logic
+- `packages/opencode/src/session/compaction.ts:50-99` — `SessionCompaction.prune()` tool output stripping
+- `packages/opencode/src/session/compaction.ts:101-229` — `SessionCompaction.process()` LLM summarization
+- `packages/opencode/src/session/compaction.ts:231-260` — `SessionCompaction.create()` enqueuing
+- `packages/opencode/src/session/compaction.ts:22-27` — `Event.Compacted` bus event definition
+- `packages/opencode/src/session/prompt.ts:274` — `SessionPrompt.loop()` main processing loop
+- `packages/opencode/src/session/prompt.ts:528-539` — Compaction task detection in loop
+- `packages/opencode/src/session/prompt.ts:541-554` — Pre-loop overflow detection
+- `packages/opencode/src/session/processor.ts:282-284` — Mid-stream overflow detection on `finish-step`
+- `packages/opencode/src/session/processor.ts:356-358` — `ContextOverflowError` detection (TODO)
+- `packages/opencode/src/session/message-v2.ts:794-809` — `filterCompacted()` message truncation
+- `packages/opencode/src/session/message-v2.ts:619-621` — Pruned tool output replacement text
+- `packages/opencode/src/provider/error.ts:8-41` — `ProviderError.isOverflow()` regex patterns (14+ providers)
+- `packages/opencode/src/provider/error.ts:112-148` — `ProviderError.parseStreamError()` structured error parsing
+- `packages/opencode/src/session/retry.ts` — `ContextOverflowError` classified as non-retryable
+- `packages/opencode/src/config/config.ts:1139-1146` — `compaction` config schema
+- `packages/opencode/src/flag/flag.ts:14,20` — Feature flags for disabling compaction/pruning
+- `packages/opencode/src/agent/agent.ts:157-171` — Hidden `"compaction"` agent definition
+- `packages/opencode/src/cli/cmd/tui/routes/session/index.tsx:441-467` — TUI `/compact` command
+- `packages/opencode/src/cli/cmd/tui/routes/session/index.tsx:1295-1302` — Compaction divider UI
+- `packages/opencode/src/cli/cmd/tui/context/sync.tsx:450-458` — Session `"compacting"` status
+- `packages/sdk/js/src/v2/gen/types.gen.ts` — SDK types: `ContextOverflowError`, `CompactionPart`, `EventSessionCompacted`
+- `packages/plugin/src/index.ts` — `experimental.session.compacting` plugin hook
+
+## Architecture Documentation
+
+### Event Flow Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        SDK Layer                                 │
+│                                                                  │
+│  Copilot SDK                Claude SDK              OpenCode SDK │
+│  ├─ session.compaction_start  ├─ tool.start (compact)  ├─ SSE   │
+│  └─ session.compaction_complete └─ tool.complete        │  events│
+│       │                           │                     │        │
+│       ▼                           ▼                     ▼        │
+│  ┌─────────┐               ┌─────────┐           ┌─────────┐   │
+│  │copilot.ts│               │claude.ts │           │opencode.ts│  │
+│  │ maps both│               │ no event │           │ maps only │  │
+│  │ start +  │               │ emission │           │ "complete"│  │
+│  │ complete │               │ for      │           │ from SSE  │  │
+│  │ to unified│              │ compaction│           │ session.  │  │
+│  │ session. │               │          │           │ compacted │  │
+│  │ compaction│              │          │           │           │  │
+│  └────┬─────┘               └──────────┘           └─────┬────┘  │
+│       │                                                   │      │
+└───────┼───────────────────────────────────────────────────┼──────┘
+        │                                                   │
+        ▼                                                   ▼
+┌───────────────────────────────────────────────────────────────┐
+│                     Unified Event Layer                        │
+│                                                               │
+│  EventType: "session.compaction"                              │
+│  Data: { phase: "start" | "complete", success?, error? }      │
+│                                                               │
+│  ┌──────────────────┐  ┌──────────────────┐  ┌────────────┐ │
+│  │copilot-adapter.ts│  │claude-adapter.ts  │  │opencode-   │ │
+│  │ subscribes to    │  │ subscribes to     │  │adapter.ts  │ │
+│  │ session.compaction│  │ session.compaction│  │ subscribes │ │
+│  │ → publishes      │  │ → publishes       │  │ to session.│ │
+│  │ stream.session.  │  │ stream.session.   │  │ compaction │ │
+│  │ compaction       │  │ compaction        │  │ → publishes│ │
+│  └────────┬─────────┘  └────────┬──────────┘  └─────┬──────┘ │
+│           │                      │                    │       │
+└───────────┼──────────────────────┼────────────────────┼───────┘
+            │                      │                    │
+            ▼                      ▼                    ▼
+┌───────────────────────────────────────────────────────────────┐
+│                     Event Bus Layer                            │
+│                                                               │
+│  BusEventType: "stream.session.compaction"                    │
+│  Data: { phase, success?, error? }                            │
+│                                                               │
+└──────────────────────────┬────────────────────────────────────┘
+                           │
+                           ▼
+┌───────────────────────────────────────────────────────────────┐
+│                        TUI Layer                              │
+│                                                               │
+│  ┌─ useBusSubscription("stream.session.compaction") ──────┐  │
+│  │  phase: "start"  → applyAutoCompactionIndicator(running) │  │
+│  │  phase: "complete" → applyAutoCompactionIndicator(done)  │  │
+│  └──────────────────────────────────────────────────────────┘  │
+│                                                               │
+│  ┌─ handleToolStart (tool name detection) ─────────────────┐  │
+│  │  isAutoCompactionToolName() → applyAutoCompactionIndicator │ │
+│  └──────────────────────────────────────────────────────────┘  │
+│                                                               │
+│  applyAutoCompactionIndicator()                               │
+│  ├─ running:   spinner verb → "Compacting"                   │
+│  ├─ completed: clear messages, create fresh msg, save summary │
+│  └─ error:     revert spinner verb to default                 │
+│                                                               │
+│  LoadingIndicator: ⣾ Compacting… (duration · tokens · thinking)│
+│                                                               │
+└───────────────────────────────────────────────────────────────┘
+```
+
+### Upstream OpenCode Auto-Compaction Flow
+
+```
+SessionPrompt.loop()
+    │
+    ├─ [Check for pending compaction task in message queue]
+    │       │
+    │       └─► SessionCompaction.process()
+    │               ├─ Trigger hook: experimental.session.compacting
+    │               ├─ Build prompt (default template or plugin-provided)
+    │               ├─ Send conversation + prompt to LLM (no tools)
+    │               ├─ Create assistant message (mode: "compaction", summary: true)
+    │               ├─ If auto: create synthetic "Continue" user message
+    │               └─ Bus.publish(Event.Compacted, { sessionID })
+    │
+    ├─ [Normal LLM Processing via SessionProcessor]
+    │       │
+    │       ├─ On finish-step event:
+    │       │     └─ SessionCompaction.isOverflow(tokens, model)
+    │       │           └─ true → needsCompaction = true → break stream
+    │       │                  → process() returns "compact"
+    │       │
+    │       ├─ On APICallError:
+    │       │     └─ ProviderError.parseAPICallError()
+    │       │           └─ isOverflow() → ContextOverflowError (non-retryable)
+    │       │
+    │       └─ On StreamError:
+    │             └─ ProviderError.parseStreamError()
+    │                   └─ code === "context_length_exceeded" → ContextOverflowError
+    │
+    ├─ [Post-processing overflow check]
+    │       └─ SessionCompaction.isOverflow()
+    │               └─ true → SessionCompaction.create() → queue compaction
+    │
+    └─ [Pruning — after loop exits]
+            └─ SessionCompaction.prune()
+                    └─ Backward scan → protect recent 40k tokens
+                    └─ Prune if >20k tokens pruneable
+                    └─ Set part.state.time.compacted = Date.now()
+                    └─ In model messages: "[Old tool result content cleared]"
+```
+
+## Historical Context (from research/)
+
+No existing research documents were found specifically covering compaction or context overflow handling.
+
+## Related Research
+
+- `research/workflow-gaps.md` — May contain related gap analysis
+
+## Open Questions
+
+1. **ContextOverflowError recovery in OpenCode client**: When a `ContextOverflowError` occurs during streaming in the OpenCode SDK integration, should the client automatically trigger `summarize()` and retry, or should it emit a `session.compaction` event with `phase: "start"` and let the existing TUI infrastructure handle the visual feedback?
+
+2. **`phase: "start"` emission timing**: The OpenCode SDK's SSE protocol only has `session.compacted` (post-fact). To emit `phase: "start"`, the workflow-sdk OpenCode client would need to synthetically emit it before calling `summarize()`. Is this the right approach?
+
+3. **Non-workflow mode coverage**: The `contextMonitorNode` in the workflow graph layer already calls `summarize()` for OpenCode at 45% threshold, but this only works when using workflow graphs. Should the OpenCode client itself have built-in threshold monitoring for direct chat mode?
+
+4. **Tool output pruning**: The upstream OpenCode has a `prune()` mechanism that strips old tool outputs. Should the workflow-sdk OpenCode integration implement similar pruning, or does the upstream server already handle this?
+
+5. **`session.truncation` dead subscription**: The OpenCode adapter subscribes to `session.truncation` but the client never emits it. Should this be wired up to an upstream SSE event, or is it intentionally unused?
diff --git a/research/docs/2026-03-01-opencode-delegation-streaming-parity.md b/research/docs/2026-03-01-opencode-delegation-streaming-parity.md
new file mode 100644
index 0000000000..9b200e84cd
--- /dev/null
+++ b/research/docs/2026-03-01-opencode-delegation-streaming-parity.md
@@ -0,0 +1,118 @@
+---
+date: 2026-03-01 09:59:48 UTC
+researcher: OpenCode (gpt-5.3-codex)
+git_commit: ede4debeb208749489229f9c2b703ed2aa940996
+branch: lavaman131/feature/workflow-sdk
+repository: workflow-sdk
+topic: "OpenCode background-task delegation and streaming parity research for workflow-sdk TUI"
+tags: [research, codebase, opencode, streaming, delegation, subagents, tui]
+status: complete
+last_updated: 2026-03-01
+last_updated_by: OpenCode (gpt-5.3-codex)
+---
+
+# Research
+
+## Research Question
+Research the OpenCode codebase to understand how it delegates messages back to the main agent for background tasks/agents, then map the current TUI architecture in `workflow-sdk` against that design and identify concrete parity gaps in the current streaming architecture.
+
+## Summary
+OpenCode implements delegation as a first-class runtime loop behavior: a `task` tool creates or resumes a child session, wraps the child result in a stable `task_id` + `<task_result>` envelope, persists tool completion in session message parts, and then continues the parent loop by rebuilding model input from persisted tool results. The event stream is backed by typed bus events and SSE delivery (`/event`, `/global/event`) with explicit message-part delta/update semantics.
+
+The current `workflow-sdk` TUI has a strong event-driven UI pipeline (adapters -> bus -> batch dispatcher -> correlation -> stream-part reducer -> render), plus background/sub-agent orchestration, but delegated outputs are primarily reconciled into UI state/messages rather than fed through a canonical parent-loop tool-result envelope equivalent to OpenCode’s `task` semantics. The architecture also has documented consumption gaps in the event pipeline (notably unconsumed event types and workflow events dropped before part mapping), which creates parity differences with OpenCode’s end-to-end streaming engine behavior.
+
+## Detailed Findings
+
+### OpenCode: Delegation Back to Main Agent Loop
+- **Delegation trigger + tool path:** `TaskTool` is part of the standard tool registry and is executed from the processor tool-call flow (`packages/opencode/src/tool/registry.ts:112`, `packages/opencode/src/session/processor.ts:134`) ([registry](https://github.com/anomalyco/opencode/blob/38704acacddad821d157d9a2c093e3751e016f53/packages/opencode/src/tool/registry.ts#L112), [processor](https://github.com/anomalyco/opencode/blob/38704acacddad821d157d9a2c093e3751e016f53/packages/opencode/src/session/processor.ts#L134)).
+- **Child session lifecycle:** task execution resumes an existing child by `task_id` or creates a new session with `parentID` set to parent session (`packages/opencode/src/tool/task.ts:67`, `packages/opencode/src/tool/task.ts:73`) ([task.ts](https://github.com/anomalyco/opencode/blob/38704acacddad821d157d9a2c093e3751e016f53/packages/opencode/src/tool/task.ts#L67), [task.ts](https://github.com/anomalyco/opencode/blob/38704acacddad821d157d9a2c093e3751e016f53/packages/opencode/src/tool/task.ts#L73)).
+- **Delegated result envelope:** child output is returned to parent as `task_id` plus `<task_result>...</task_result>` (`packages/opencode/src/tool/task.ts:148`, `packages/opencode/src/tool/task.ts:150`) ([task.ts](https://github.com/anomalyco/opencode/blob/38704acacddad821d157d9a2c093e3751e016f53/packages/opencode/src/tool/task.ts#L148), [task.ts](https://github.com/anomalyco/opencode/blob/38704acacddad821d157d9a2c093e3751e016f53/packages/opencode/src/tool/task.ts#L150)).
+- **Parent ingestion model:** loop continuation is tied to finish reason; when assistant finish is `tool-calls`, loop continues and regenerates model input from session history including tool outputs (`packages/opencode/src/session/prompt.ts:319`, `packages/opencode/src/session/prompt.ts:664`) ([prompt.ts](https://github.com/anomalyco/opencode/blob/38704acacddad821d157d9a2c093e3751e016f53/packages/opencode/src/session/prompt.ts#L319), [prompt.ts](https://github.com/anomalyco/opencode/blob/38704acacddad821d157d9a2c093e3751e016f53/packages/opencode/src/session/prompt.ts#L664)).
+- **Tool-result reconciliation into model messages:** completed tool parts are transformed into model-message tool outputs via `toModelMessages` / `convertToModelMessages` (`packages/opencode/src/session/message-v2.ts:617`, `packages/opencode/src/session/message-v2.ts:705`) ([message-v2.ts](https://github.com/anomalyco/opencode/blob/38704acacddad821d157d9a2c093e3751e016f53/packages/opencode/src/session/message-v2.ts#L617), [message-v2.ts](https://github.com/anomalyco/opencode/blob/38704acacddad821d157d9a2c093e3751e016f53/packages/opencode/src/session/message-v2.ts#L705)).
+
+### OpenCode: Streaming Engine Characteristics
+- **Typed event model + envelope:** bus publishes typed payloads and forwards global envelope `{ directory, payload }` for stream consumers (`packages/opencode/src/bus/index.ts:45`, `packages/opencode/src/bus/index.ts:47`) ([bus/index.ts](https://github.com/anomalyco/opencode/blob/38704acacddad821d157d9a2c093e3751e016f53/packages/opencode/src/bus/index.ts#L45)).
+- **SSE-first transport:** server exposes event streams and forwards bus updates (`packages/opencode/src/server/server.ts`, `packages/opencode/src/server/routes/global.ts`) ([server.ts](https://github.com/anomalyco/opencode/blob/38704acacddad821d157d9a2c093e3751e016f53/packages/opencode/src/server/server.ts), [global.ts](https://github.com/anomalyco/opencode/blob/38704acacddad821d157d9a2c093e3751e016f53/packages/opencode/src/server/routes/global.ts)).
+- **Message-part level deltas/updates:** `message.part.updated` and `message.part.delta` are core runtime signals used by clients (`packages/opencode/src/session/message-v2.ts:460`, `packages/opencode/src/session/message-v2.ts:466`) ([message-v2.ts](https://github.com/anomalyco/opencode/blob/38704acacddad821d157d9a2c093e3751e016f53/packages/opencode/src/session/message-v2.ts#L460), [message-v2.ts](https://github.com/anomalyco/opencode/blob/38704acacddad821d157d9a2c093e3751e016f53/packages/opencode/src/session/message-v2.ts#L466)).
+- **Client reconciliation path:** app/TUI layers subscribe to stream events and reconcile deltas + updates into normalized state (`packages/app/src/context/global-sync/event-reducer.ts`, `packages/opencode/src/cli/cmd/tui/context/sync.tsx`) ([event-reducer.ts](https://github.com/anomalyco/opencode/blob/38704acacddad821d157d9a2c093e3751e016f53/packages/app/src/context/global-sync/event-reducer.ts), [sync.tsx](https://github.com/anomalyco/opencode/blob/38704acacddad821d157d9a2c093e3751e016f53/packages/opencode/src/cli/cmd/tui/context/sync.tsx)).
+
+### workflow-sdk: Current Delegation + Streaming Implementation
+- **Streaming entry + adapters:** TUI dispatches through `startChatUI`/`handleStreamMessage` and routes provider-specific streams into normalized bus events (`src/ui/index.ts:422`, `src/events/adapters/types.ts:15`) ([index.ts](https://github.com/flora131/atomic/blob/ede4debeb208749489229f9c2b703ed2aa940996/src/ui/index.ts#L422), [types.ts](https://github.com/flora131/atomic/blob/ede4debeb208749489229f9c2b703ed2aa940996/src/events/adapters/types.ts#L15)).
+- **Bus + batching pipeline:** events flow through `AtomicEventBus`, `BatchDispatcher`, correlation, and stream-part consumer (`src/events/event-bus.ts:139`, `src/events/batch-dispatcher.ts:137`, `src/events/consumers/wire-consumers.ts:71`) ([event-bus.ts](https://github.com/flora131/atomic/blob/ede4debeb208749489229f9c2b703ed2aa940996/src/events/event-bus.ts#L139), [batch-dispatcher.ts](https://github.com/flora131/atomic/blob/ede4debeb208749489229f9c2b703ed2aa940996/src/events/batch-dispatcher.ts#L137), [wire-consumers.ts](https://github.com/flora131/atomic/blob/ede4debeb208749489229f9c2b703ed2aa940996/src/events/consumers/wire-consumers.ts#L71)).
+- **Background/sub-agent streams:** parallel sub-agents run via isolated sessions and `SubagentStreamAdapter` emits `stream.agent.*` and scoped tool/text/thinking signals (`src/ui/chat.tsx:4552`, `src/events/adapters/subagent-adapter.ts:112`) ([chat.tsx](https://github.com/flora131/atomic/blob/ede4debeb208749489229f9c2b703ed2aa940996/src/ui/chat.tsx#L4552), [subagent-adapter.ts](https://github.com/flora131/atomic/blob/ede4debeb208749489229f9c2b703ed2aa940996/src/events/adapters/subagent-adapter.ts#L112)).
+- **Parent-side result handling:** child outputs are accumulated and merged into UI message state/parts (`src/events/adapters/subagent-adapter.ts:542`, `src/ui/chat.tsx:3906`) ([subagent-adapter.ts](https://github.com/flora131/atomic/blob/ede4debeb208749489229f9c2b703ed2aa940996/src/events/adapters/subagent-adapter.ts#L542), [chat.tsx](https://github.com/flora131/atomic/blob/ede4debeb208749489229f9c2b703ed2aa940996/src/ui/chat.tsx#L3906)).
+- **Loop continuation behavior:** stream continuation decisions are status/guard-driven rather than finish-reason (`tool-calls`) driven (`src/ui/parts/guards.ts:42`, `src/ui/utils/stream-continuation.ts:133`) ([guards.ts](https://github.com/flora131/atomic/blob/ede4debeb208749489229f9c2b703ed2aa940996/src/ui/parts/guards.ts#L42), [stream-continuation.ts](https://github.com/flora131/atomic/blob/ede4debeb208749489229f9c2b703ed2aa940996/src/ui/utils/stream-continuation.ts#L133)).
+
+### Stage-by-Stage Parity Gaps (Current-State Comparison)
+
+#### 1) Delegation trigger and lifecycle identity
+- **OpenCode:** canonical `task` tool call lifecycle with resumable `task_id` (`packages/opencode/src/tool/task.ts:67`, `packages/opencode/src/tool/task.ts:148`) ([task.ts](https://github.com/anomalyco/opencode/blob/38704acacddad821d157d9a2c093e3751e016f53/packages/opencode/src/tool/task.ts#L67)).
+- **workflow-sdk:** no equivalent runtime `task_id` token contract in `src/`; delegated identity uses provider-specific IDs (`tool_use_id`, `toolCallId`, `subagentId`) and session resume hooks (`src/sdk/clients/claude.ts:1211`, `src/events/adapters/copilot-adapter.ts:576`, `src/sdk/clients/opencode.ts:1661`) ([claude.ts](https://github.com/flora131/atomic/blob/ede4debeb208749489229f9c2b703ed2aa940996/src/sdk/clients/claude.ts#L1211), [copilot-adapter.ts](https://github.com/flora131/atomic/blob/ede4debeb208749489229f9c2b703ed2aa940996/src/events/adapters/copilot-adapter.ts#L576), [opencode.ts](https://github.com/flora131/atomic/blob/ede4debeb208749489229f9c2b703ed2aa940996/src/sdk/clients/opencode.ts#L1661)).
+- **Gap:** no single, provider-agnostic `task_id` resume envelope equivalent.
+
+#### 2) Child-parent session model
+- **OpenCode:** child sessions are created with explicit `parentID` in core session model (`packages/opencode/src/tool/task.ts:73`, `packages/opencode/src/session/index.ts:645`) ([task.ts](https://github.com/anomalyco/opencode/blob/38704acacddad821d157d9a2c093e3751e016f53/packages/opencode/src/tool/task.ts#L73), [session/index.ts](https://github.com/anomalyco/opencode/blob/38704acacddad821d157d9a2c093e3751e016f53/packages/opencode/src/session/index.ts#L645)).
+- **workflow-sdk:** OpenCode client includes child-parent mapping in adapter/client state (`src/sdk/clients/opencode.ts:485`, `src/sdk/clients/opencode.ts:1073`), but this is not a cross-provider core runtime session primitive ([opencode.ts](https://github.com/flora131/atomic/blob/ede4debeb208749489229f9c2b703ed2aa940996/src/sdk/clients/opencode.ts#L485), [opencode.ts](https://github.com/flora131/atomic/blob/ede4debeb208749489229f9c2b703ed2aa940996/src/sdk/clients/opencode.ts#L1073)).
+- **Gap:** parent-child linkage exists, but parity is adapter-scoped rather than engine-core.
+
+#### 3) Delegated output envelope back to parent loop
+- **OpenCode:** explicit parent-facing `<task_result>` envelope (`packages/opencode/src/tool/task.ts:150`) ([task.ts](https://github.com/anomalyco/opencode/blob/38704acacddad821d157d9a2c093e3751e016f53/packages/opencode/src/tool/task.ts#L150)).
+- **workflow-sdk:** no `<task_result>` equivalent in runtime source; delegated result is propagated through stream events and UI state composition (`src/events/adapters/subagent-adapter.ts:542`, `src/ui/chat.tsx:3906`) ([subagent-adapter.ts](https://github.com/flora131/atomic/blob/ede4debeb208749489229f9c2b703ed2aa940996/src/events/adapters/subagent-adapter.ts#L542), [chat.tsx](https://github.com/flora131/atomic/blob/ede4debeb208749489229f9c2b703ed2aa940996/src/ui/chat.tsx#L3906)).
+- **Gap:** no canonical text envelope contract carrying delegated result + resume handle.
+
+#### 4) Parent-loop ingestion semantics
+- **OpenCode:** loop continuation is finish-reason aware and rehydrates model input from persisted tool-result parts (`packages/opencode/src/session/prompt.ts:319`, `packages/opencode/src/session/message-v2.ts:705`) ([prompt.ts](https://github.com/anomalyco/opencode/blob/38704acacddad821d157d9a2c093e3751e016f53/packages/opencode/src/session/prompt.ts#L319), [message-v2.ts](https://github.com/anomalyco/opencode/blob/38704acacddad821d157d9a2c093e3751e016f53/packages/opencode/src/session/message-v2.ts#L705)).
+- **workflow-sdk:** stream completion/continuation is managed by UI/tool status guards and callbacks (`src/ui/chat.tsx:2585`, `src/ui/parts/guards.ts:42`) ([chat.tsx](https://github.com/flora131/atomic/blob/ede4debeb208749489229f9c2b703ed2aa940996/src/ui/chat.tsx#L2585), [guards.ts](https://github.com/flora131/atomic/blob/ede4debeb208749489229f9c2b703ed2aa940996/src/ui/parts/guards.ts#L42)).
+- **Gap:** no OpenCode-equivalent parent loop that consumes delegated outputs as canonical model-history tool results.
+
+#### 5) Streaming event completeness and reconciliation
+- **OpenCode:** streaming is centered around message-part delta/update events consumed by sync reducers (`packages/opencode/src/session/message-v2.ts:460`, `packages/app/src/context/global-sync/event-reducer.ts`) ([message-v2.ts](https://github.com/anomalyco/opencode/blob/38704acacddad821d157d9a2c093e3751e016f53/packages/opencode/src/session/message-v2.ts#L460), [event-reducer.ts](https://github.com/anomalyco/opencode/blob/38704acacddad821d157d9a2c093e3751e016f53/packages/app/src/context/global-sync/event-reducer.ts)).
+- **workflow-sdk:** event architecture is broad and typed, but documented analysis shows events emitted yet not consumed in current stream consumer path (`research/docs/2026-02-28-workflow-gaps-architecture.md:343`, `research/docs/2026-02-28-workflow-gaps-architecture.md:320`).
+- **Gap:** parity difference in end-to-end stream completeness; some emitted events do not reach rendered part state in current workflow-sdk architecture.
+
+#### 6) Workflow-specific stream mapping coverage
+- **OpenCode:** message-part lifecycle events are directly represented in sync state.
+- **workflow-sdk:** workflow adapters publish workflow step/task updates, while current consumer mapping coverage is narrower and can drop events before part conversion (`src/events/adapters/workflow-adapter.ts:110`, `src/events/consumers/stream-pipeline-consumer.ts:192`, with historical gap documentation in `research/docs/2026-02-28-workflow-gaps-architecture.md:372`).
+- **Gap:** current workflow event mapping and part registry coverage do not fully mirror OpenCode’s message-part-centric reconciliation path.
+
+## Code References
+- `packages/opencode/src/tool/task.ts:67` - Resume existing child session by `task_id`.
+- `packages/opencode/src/tool/task.ts:73` - Create child session with `parentID`.
+- `packages/opencode/src/tool/task.ts:150` - Wrap delegated output in `<task_result>` envelope.
+- `packages/opencode/src/session/prompt.ts:319` - Continue parent loop when finish reason is `tool-calls`.
+- `packages/opencode/src/session/message-v2.ts:705` - Convert persisted message/tool parts to model messages.
+- `packages/opencode/src/bus/index.ts:45` - Publish typed payload and global envelope.
+- `packages/opencode/src/server/routes/global.ts` - SSE stream endpoint for global events.
+- `src/ui/index.ts:422` - workflow-sdk stream ingress (`handleStreamMessage`).
+- `src/events/event-bus.ts:139` - Event schema validation and dispatch.
+- `src/events/batch-dispatcher.ts:137` - Frame-batched dispatcher flush scheduling.
+- `src/events/adapters/subagent-adapter.ts:112` - Sub-agent stream lifecycle events (`stream.agent.start`).
+- `src/events/adapters/subagent-adapter.ts:542` - Child output accumulation for delegated stream.
+- `src/ui/chat.tsx:3906` - Merge delegated/parallel results into message state.
+- `src/ui/parts/guards.ts:42` - Guard-based continuation/finalization logic.
+- `research/docs/2026-02-28-workflow-gaps-architecture.md:343` - Historical inventory of emitted-but-unconsumed events.
+
+## Architecture Documentation
+The two systems share an event-driven design, but the architectural center differs:
+
+- **OpenCode center:** session runtime + persisted message parts + tool-call loop continuation; delegated child outputs are normalized into parent model history before the next generation step.
+- **workflow-sdk center:** adapter-normalized event bus + UI stream-part reducers; delegated child outputs are primarily reconciled in UI-layer message/parts and provider-specific correlation state.
+
+This is why both can render rich parallel-agent streams, while only OpenCode shows a single canonical delegation contract (`task_id` + `<task_result>`) directly tied to the parent generation loop semantics.
+
+## Historical Context (from research/)
+- `research/docs/2026-02-26-opencode-event-bus-patterns.md` - Documents OpenCode global bus, SSE distribution, and batching/coalescing model.
+- `research/docs/2026-02-23-258-background-agents-sdk-event-pipeline.md` - Documents workflow-sdk background-agent pipeline stages and provider-specific correlation behavior.
+- `research/docs/2026-02-28-workflow-gaps-architecture.md` - Documents current event-consumption and part-registry gaps in workflow-sdk stream architecture.
+- `research/workflow-gaps.md` - Compact gap inventory used as supplemental historical context.
+
+## Related Research
+- `research/docs/2026-02-26-streaming-architecture-event-bus-migration.md`
+- `research/docs/2026-02-26-streaming-event-bus-spec-audit.md`
+- `research/docs/2026-02-28-workflow-tui-rendering-unification-refactor.md`
+- `research/docs/2026-02-16-opencode-tui-chat-architecture.md`
+
+## Open Questions
+1. In workflow-sdk, should delegated child outputs remain primarily UI-layer artifacts, or be represented in a provider-agnostic parent-loop message contract equivalent to OpenCode’s task envelope semantics?
+2. Which currently emitted-but-unconsumed stream events are intentionally non-rendered vs unintentionally dropped in the present architecture?
+3. For cross-provider parity, which delegated identity key is the canonical equivalent to OpenCode `task_id` (`tool_use_id`, `toolCallId`, `subagentId`, or a synthesized runtime ID)?
diff --git a/research/docs/2026-03-01-opencode-tui-concurrency-bottlenecks.md b/research/docs/2026-03-01-opencode-tui-concurrency-bottlenecks.md
new file mode 100644
index 0000000000..b63685290f
--- /dev/null
+++ b/research/docs/2026-03-01-opencode-tui-concurrency-bottlenecks.md
@@ -0,0 +1,347 @@
+---
+date: 2026-03-01 19:53:49 UTC
+researcher: Copilot (Claude Opus 4.6)
+git_commit: 7debf4841f53cc01dbe3faa8bc4b00a9367bb7a6
+branch: lavaman131/feature/workflow-sdk
+repository: workflow-sdk
+topic: "OpenCode TUI Concurrency Bottlenecks — Response Time Degradation During Parallel Agent SDK Execution"
+tags: [research, opencode, tui, concurrency, sse, event-loop, ralph-workflow, bottleneck, streaming]
+status: complete
+last_updated: 2026-03-01
+last_updated_by: Copilot (Claude Opus 4.6)
+---
+
+# Research: OpenCode TUI Concurrency Bottlenecks
+
+## Research Question
+
+Investigate OpenCode's TUI architecture for concurrency and I/O blocking issues that cause response times to degrade from seconds to indefinite when multiple agent SDKs (e.g., Claude Agent SDK, Copilot SDK) run in parallel. Specifically:
+1. How does OpenCode's event loop / message handling work in its TUI layer?
+2. Are there shared resources (stdin/stdout, process handles, event queues) that could cause contention when multiple agents run concurrently?
+3. What does the first step of the Ralph workflow trigger in OpenCode, and how could it interact with background agent processes?
+4. Reference the OpenCode source code at `~/Documents/projects/opencode` to document the relevant architecture and identify potential bottleneck points.
+
+## Summary
+
+The response time degradation from seconds to indefinite during parallel agent SDK execution traces to **six concrete bottleneck patterns** in the OpenCode client's SSE event loop and the workflow executor's blocking chain. The most critical issue is that the SSE `reader.read()` call in the SDK's generated client (`serverSentEvents.gen.js:52`) blocks indefinitely on dead connections, and the OpenCode client's watchdog abort signal at `opencode.ts:829` is **not propagated to the SDK's SSE reader** — only checked on the next event iteration. Additionally, when multiple sessions run against the same OpenCode server, **all events for all sessions flow through a single `for await` loop**, creating a shared bottleneck where high-volume background agent activity can starve the foreground agent's event processing.
+
+The Ralph workflow's first step (planner) creates a deeply nested blocking chain from the executor's `for await` loop down through the TUI's `spawnSubagentParallel`, to the SDK's `session.stream()` async generator, which ultimately parks on the SSE event loop. If a background agent SDK process is consuming the SSE event loop's processing time or causing connection instability, the planner's response stream stalls.
+
+## Detailed Findings
+
+### Architecture Overview
+
+**OpenCode is TypeScript/SolidJS, not Go/BubbleTea.** The TUI uses `@opentui/solid` (custom terminal renderer) with Bun as the runtime. It employs a two-process model:
+- **Main thread**: SolidJS TUI rendering at 60fps
+- **Worker thread**: Bun Worker running the OpenCode backend server (LLM, DB, subprocesses)
+
+Communication between threads uses a custom JSON-RPC bridge (`util/rpc.ts`) via `postMessage`/`onmessage`, or optionally HTTP when `--port` is specified.
+
+### Bottleneck Pattern A: SSE `reader.read()` Indefinite Block (Dead Connection)
+
+**Location**: OpenCode SDK generated client — `serverSentEvents.gen.js:52` (in `node_modules/@opencode-ai/sdk`)
+
+The SDK's SSE client uses `reader.read()` on a `ReadableStream` from `fetch()`. If the TCP connection silently dies (no RST/FIN — common with NAT timeouts, firewall drops, or process crashes), `reader.read()` hangs indefinitely until the OS TCP keepalive timeout fires (typically **2+ hours** on Linux defaults).
+
+The OpenCode client's heartbeat watchdog (`opencode.ts:815-851`) sets `HEARTBEAT_TIMEOUT_MS = 15,000ms` and calls `watchdogAbort.abort()` when no events arrive for 15 seconds. However, this `watchdogAbort` controller is **local to `processEventStream()`** — it is **NOT passed to the SDK's SSE client**. The SDK only listens on its own `options.signal` from the original `event.subscribe()` call.
+
+```
+Watchdog fires → watchdogAbort.abort() → but reader.read() in SDK doesn't know
+                                         → for await loop stuck at reader.read()
+                                         → watchdog signal only checked at line 838
+                                            on NEXT iteration (which never comes)
+```
+
+**Impact**: If the OpenCode server's SSE connection drops silently while a background agent is running, the event loop freezes. The foreground planner node is blocked in its `for await` chain waiting for events that will never arrive.
+
+### Bottleneck Pattern B: Shared SSE Stream Across All Sessions
+
+**Location**: `src/sdk/clients/opencode.ts:756-758`, event handler filtering throughout adapter code
+
+The SSE `event.subscribe()` at line 756 subscribes to **all server events** scoped by directory, not by session. When multiple agents/sessions run simultaneously against the same OpenCode server:
+
+1. All events for **all sessions** flow through the single `for await` loop at line 837
+2. Each event is dispatched to **all** registered handlers via `emitEvent()` (line 1549)
+3. Each handler filters by `event.sessionId` and returns early if the event belongs to a different session
+
+When a background agent generates high-volume events (many tool calls, streaming text), those events still pass through the shared `for await` loop, `handleSdkEvent()`, and `emitEvent()` dispatch, consuming CPU time even though every handler immediately returns due to session ID filtering.
+
+**Impact**: Background agent activity creates processing overhead that delays event handling for the foreground planner session. With enough background activity, this can cause the heartbeat watchdog to fire spuriously (Pattern A), leading to reconnections and state reconciliation overhead.
+
+### Bottleneck Pattern C: Synchronous Handler Fanout in `emitEvent()`
+
+**Location**: `src/sdk/clients/opencode.ts:1549-1571`
+
+`emitEvent()` iterates all handlers **synchronously** within a `for` loop:
+
+```typescript
+for (const handler of handlers) {
+  try {
+    handler(event as AgentEvent<EventType>);
+  } catch (error) {
+    console.error(`Error in event handler for ${eventType}:`, error);
+  }
+}
+```
+
+All handlers execute synchronously within the `for await` iteration of `processEventStream()`. If any handler performs slow work (e.g., `EventBus.publish()` with Zod schema validation at `event-bus.ts:143-154`), it delays `resetWatchdog()` for subsequent events.
+
+### Bottleneck Pattern D: `completionPromise` Indefinite Blocking in Adapter
+
+**Location**: `src/events/adapters/opencode-adapter.ts:336-378`
+
+The `OpenCodeStreamAdapter.startStreaming()` method creates a `completionPromise` that resolves when `session.idle` or `session.error` fires for the adapter's session ID:
+
+```typescript
+const completionPromise = new Promise<...>((resolve) => {
+  const onIdle = client?.on("session.idle", (event) => {
+    if (event.sessionId !== this.sessionId) return;
+    resolve({ reason: event.data.reason ?? "idle" });
+  });
+  // ...
+});
+await session.sendAsync(message, ...);
+const completion = await completionPromise;  // BLOCKS HERE
+```
+
+If the SSE event loop stalls (Pattern A), `session.idle` never arrives, and `startStreaming()` blocks indefinitely. The `abortController.signal` listener at line 361 provides an escape hatch, but only if the caller externally aborts.
+
+### Bottleneck Pattern E: Deep Blocking Chain in Ralph Planner Step
+
+**Location**: Multiple files — the complete blocking chain for the planner step:
+
+```
+executor.ts:455     → for await (const step of streamGraph(...))
+  compiled.ts:655   → await node.execute(context)
+    nodes.ts:1707   → await spawnSubagent({...})
+      executor.ts:260 → await spawnFn([...], abortSignal)
+        chat.tsx:4749 → await Promise.allSettled(agents.map(spawnOne))
+          chat.tsx:4659 → await createSubagentSession(sessionConfig)
+            chat.tsx:4710 → await adapter.consumeStream(stream, ...)
+              subagent-adapter.ts:150 → for await (const chunk of stream)
+                // INNERMOST: blocked on SDK AsyncIterable<AgentMessage>
+```
+
+The entire chain is synchronous/serial for the planner: one agent, one session, one stream. The executor's `for await` loop does not yield the next step until the planner's SDK stream completes at the innermost level. Any stall at any level propagates up to freeze the entire workflow.
+
+### Bottleneck Pattern F: `stream()` Generator Infinite Poll Without Overall Timeout
+
+**Location**: `src/sdk/clients/opencode.ts:2148-2152`
+
+The `stream()` async generator parks for 25ms (STREAM_POLL_MS) between checks:
+
+```typescript
+await new Promise<void>((resolve) => {
+  resolveNext = resolve;
+  setTimeout(resolve, STREAM_POLL_MS);  // 25ms
+});
+```
+
+If the SSE event loop is stalled (Pattern A), no `session.idle` event arrives, and the generator spin-polls every 25ms **indefinitely** — there is no overall timeout. The 500ms settle window (`PRE_PROMPT_TERMINAL_SETTLE_MS`) only applies after `session.idle` is received, not before.
+
+### OpenCode Source Architecture (Reference)
+
+#### Event Flow: Backend → TUI
+
+```
+OpenCode Server (SSE endpoint, heartbeat every 10s)
+    │
+    ▼
+SDK createSseClient (fetch → reader.read() loop)
+    │ yields parsed JSON events
+    ▼
+processEventStream() — for await loop (opencode.ts:837)
+    │ resets watchdog timer, calls handleSdkEvent()
+    ▼
+handleSdkEvent() (opencode.ts:968) — switches on event.type
+    ▼
+emitEvent() (opencode.ts:1549) — synchronous fanout to Set<EventHandler>
+    ├──► stream() handlers → deltaQueue → async generator → consumer
+    └──► OpenCodeStreamAdapter handlers → EventBus.publish() → UI
+```
+
+#### Key Constants
+
+| Constant | Value | File | Purpose |
+|---|---|---|---|
+| `HEARTBEAT_TIMEOUT_MS` | 15,000ms | `opencode.ts:815` | Watchdog timeout |
+| `SSE_RECONNECT_DELAY_MS` | 250ms | `opencode.ts:751` | Reconnect delay |
+| `PRE_PROMPT_TERMINAL_SETTLE_MS` | 500ms | `opencode.ts:116` | Post-idle drain window |
+| `STREAM_POLL_MS` | 25ms | `opencode.ts:117` | Generator poll interval |
+| `sseMaxRetryDelay` | 30,000ms | SDK generated | Max SSE backoff |
+| `targetFps` | 60 | OpenCode `app.tsx:184` | TUI render target |
+| Event batch window | 16ms | OpenCode `sdk.tsx:57` | Event coalescing |
+| SSE heartbeat | 10,000ms | OpenCode `server.ts:539` | Server heartbeat |
+
+#### Two-Process Model
+
+OpenCode's TUI uses a **Bun Worker** for the backend (`packages/opencode/src/cli/cmd/tui/worker.ts`):
+- Main thread: SolidJS rendering, keyboard input, event batching (16ms)
+- Worker thread: Hono HTTP server, LLM streaming, database, subprocess management
+
+Communication via `Rpc.client<T>(worker)` → `Rpc.listen(rpc)` over `postMessage/onmessage`.
+
+Events from the worker are forwarded via `Rpc.emit("event", event)` at `worker.ts:37`, then batched in `SDKProvider` (`sdk.tsx:50-62`) using SolidJS `batch()` with 16ms coalescing.
+
+#### Concurrency Primitives
+
+| Primitive | File | Purpose |
+|---|---|---|
+| `AsyncQueue<T>` | `packages/opencode/src/util/queue.ts` | Producer-consumer async queue |
+| `Lock.read()/write()` | `packages/opencode/src/util/lock.ts` | Reader-writer lock with writer priority |
+| `Signal` | `packages/opencode/src/util/signal.ts` | One-shot promise trigger/wait |
+| `AbortController` chain | Throughout | Cascading cancellation |
+| `Instance.state()` | `packages/opencode/src/project/state.ts` | Per-directory singleton state |
+| `GlobalBus` | `packages/opencode/src/bus/global.ts` | Process-wide EventEmitter |
+
+#### Session Concurrency Guard
+
+Only one LLM loop per session runs at a time (`packages/opencode/src/session/prompt.ts:238-283`). Additional callers queue via Promise callbacks. This prevents data races within a single session but does not prevent cross-session event loop contention.
+
+### Ralph Workflow First Step: Planner
+
+**Definition**: `src/workflows/ralph/graph.ts:160-169`
+
+The planner is a `subagentNode` that spawns a "planner" sub-agent (defined in `.claude/agents/planner.md`, `.opencode/agents/planner.md`, or `.github/agents/planner.md`). It sends the user's prompt wrapped in `buildSpecToTasksPrompt()` to decompose it into a structured JSON task list.
+
+**Execution path**:
+1. `executeWorkflow()` at `executor.ts:137` obtains `context.spawnSubagentParallel` from the TUI
+2. The executor wraps it in `spawnSubagent` (single-agent wrapper) at `executor.ts:249-274`
+3. The planner node calls `spawnSubagent()` at `nodes.ts:1707`
+4. TUI's `spawnSubagentParallel` at `chat.tsx:4598` creates an isolated SDK session
+5. The session's `stream()` async generator iterates the SSE event stream
+6. **This iteration is where the bottleneck occurs** — the `for await` loop in `SubagentStreamAdapter.consumeStream()` blocks until the stream completes
+
+### Workflow-SDK Agent SDK Integration
+
+Only **one SDK** is active per chat session (`src/commands/chat.ts:81-92`):
+
+```typescript
+function createClientForAgentType(agentType: AgentType): CodingAgentClient {
+  switch (agentType) {
+    case "claude": return createClaudeAgentClient();
+    case "opencode": return createOpenCodeClient({ directory: process.cwd() });
+    case "copilot": return createCopilotClient();
+  }
+}
+```
+
+However, the **workflow executor** can spawn sub-agents that create **additional sessions** on the same client. When using OpenCode, all these sessions share the same SSE event subscription, creating the cross-session contention described in Pattern B.
+
+The stream adapter layer (`src/events/adapters/`) normalizes each SDK's native streaming into `BusEvent` format:
+- `OpenCodeStreamAdapter`: Push-based — subscribes to `client.on()` events
+- `ClaudeStreamAdapter`: Pull-based — consumes `session.stream()` AsyncIterable
+- `CopilotStreamAdapter`: Push-based — subscribes to `client.on()` events, bounded buffer (1000 max)
+
+### Known Related Issues (from `research/ralph-workflow.md`)
+
+1. Sub-agent tree state not streaming tool calls — stuck at "Initializing..."
+2. Streaming delay after TODO list completion — seconds of delay before final duration/tokens output
+3. Both issues are symptoms consistent with the SSE event loop bottlenecks documented here
+
+## Code References
+
+- `src/sdk/clients/opencode.ts:728-851` — SSE event loop, watchdog, reconnection
+- `src/sdk/clients/opencode.ts:968-1571` — Event handling and dispatch
+- `src/sdk/clients/opencode.ts:1864-2194` — `sendAsync()` and `stream()` methods
+- `src/events/adapters/opencode-adapter.ts:145-438` — Stream adapter entry point
+- `src/events/adapters/opencode-adapter.ts:336-378` — `completionPromise` blocking pattern
+- `src/workflows/executor.ts:239-305` — Runtime spawn injection
+- `src/workflows/ralph/graph.ts:160-169` — Planner node definition
+- `src/workflows/graph/nodes.ts:1665-1731` — `subagentNode()` factory
+- `src/ui/chat.tsx:4598-4784` — `spawnSubagentParallel` implementation
+- `src/ui/index.ts:207-805` — TUI session management
+- `packages/opencode/src/cli/cmd/tui/thread.ts:116-168` — OpenCode TUI thread/worker setup
+- `packages/opencode/src/cli/cmd/tui/worker.ts:1-95` — OpenCode worker process
+- `packages/opencode/src/cli/cmd/tui/context/sdk.tsx:28-100` — OpenCode event batching
+- `packages/opencode/src/cli/cmd/tui/context/sync.tsx:107-343` — OpenCode state sync
+- `packages/opencode/src/util/queue.ts:1-32` — AsyncQueue
+- `packages/opencode/src/util/lock.ts:1-98` — Reader-writer lock
+- `packages/opencode/src/server/routes/tui.ts` — Server→TUI bridge via AsyncQueue
+- `packages/opencode/src/session/prompt.ts:238-283` — Session concurrency guard
+
+## Architecture Documentation
+
+### OpenCode Event Pipeline
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ OpenCode Server                                             │
+│   SessionProcessor → Bus.publish() → GlobalBus.emit()       │
+│   → Rpc.emit("event", ...) / SSE stream endpoint            │
+└────────────────────────┬────────────────────────────────────┘
+                         │ postMessage / SSE
+┌────────────────────────▼────────────────────────────────────┐
+│ OpenCode TUI Main Thread                                     │
+│   SDKProvider → 16ms batch → SolidJS batch() → SyncProvider │
+│   → store update → reactive component re-render              │
+└──────────────────────────────────────────────────────────────┘
+```
+
+### Workflow-SDK Event Pipeline
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ OpenCode Server                                             │
+│   LLM streaming → Session.updatePart() → Bus.publish()      │
+│   → SSE endpoint (GET /event)                                │
+└────────────────────────┬────────────────────────────────────┘
+                         │ SSE (fetch → reader.read())
+┌────────────────────────▼────────────────────────────────────┐
+│ OpenCode SDK Client (workflow-sdk)                           │
+│   createSseClient → reader.read() ──── BLOCKING POINT ────  │
+│   → processEventStream() for await loop                      │
+│   → handleSdkEvent() → emitEvent() → handler fanout         │
+│     ├─► stream() deltaQueue → async generator                │
+│     └─► OpenCodeStreamAdapter → EventBus → BatchDispatcher  │
+│           → StreamPipelineConsumer → React UI                │
+└──────────────────────────────────────────────────────────────┘
+```
+
+### Ralph Planner Blocking Chain
+
+```
+for await (streamGraph)          ← executor.ts:455
+  └─ await node.execute()        ← compiled.ts:655
+      └─ await spawnSubagent()   ← nodes.ts:1707
+          └─ await spawnFn()     ← executor.ts:260
+              └─ await Promise.allSettled(spawnOne)  ← chat.tsx:4749
+                  └─ await createSubagentSession()   ← chat.tsx:4659
+                  └─ await adapter.consumeStream()   ← chat.tsx:4710
+                      └─ for await (stream)          ← subagent-adapter.ts:150
+                          └─ BLOCKS ON SSE EVENTS    ← opencode.ts reader.read()
+```
+
+## Historical Context (from research/)
+
+- `research/ralph-workflow.md` — Known bugs: sub-agent tree not streaming, streaming delay after task completion
+- `research/workflow-gaps.md` — High-impact gaps including broken rendering pipeline and MCP bridge placeholders
+- `research/docs/2026-02-15-subagent-premature-completion-investigation.md` — Sub-agent nodes marked completed before background tasks finish
+- `research/docs/2026-02-15-subagent-event-flow-diagram.md` — Sub-agent event flow and race condition documentation
+- `research/docs/2026-02-26-streaming-event-bus-spec-audit.md` — Streaming event bus spec compliance audit
+- `research/docs/2026-03-01-opencode-delegation-streaming-parity.md` — OpenCode task/subtask streaming parity
+- `research/docs/2026-03-01-opencode-auto-compaction.md` — OpenCode SDK auto-compaction mechanism
+- `research/docs/2026-02-26-opencode-event-bus-patterns.md` — OpenCode event-bus architecture
+- `research/docs/2026-02-25-graph-execution-engine-technical-documentation.md` — Graph execution engine technical docs
+- `research/docs/2026-02-25-ralph-workflow-implementation.md` — Ralph workflow implementation technical docs
+- `research/docs/2026-02-23-258-background-agents-sdk-event-pipeline.md` — Background agents SDK event pipeline
+
+## Related Research
+
+- `research/docs/2026-02-16-opencode-tui-chat-architecture.md` — OpenCode TUI chat architecture deep-dive
+- `research/docs/2026-02-14-opencode-opentui-sdk-research.md` — OpenCode SDK and OpenTUI sub-agent spawning
+- `research/docs/2026-02-28-workflow-tui-rendering-unification-refactor.md` — Workflow TUI rendering unification
+- `research/docs/2026-02-25-workflow-sdk-design.md` — WorkflowSDK design documentation
+- `research/docs/2026-02-15-ralph-dag-orchestration-implementation.md` — Ralph DAG-based orchestration implementation
+
+## Open Questions
+
+1. **Watchdog abort propagation**: The local `watchdogAbort` at `opencode.ts:820` is not passed to the SDK's SSE client. Is this intentional (relying on the global `eventSubscriptionController` instead) or an oversight? The global controller only aborts on `disconnect()`, not on heartbeat timeout.
+
+2. **Cross-session event volume**: What is the measured overhead of processing irrelevant session events in the shared `for await` loop? Under heavy background agent load, does this overhead exceed the 15s heartbeat timeout threshold?
+
+3. **`reader.read()` abort mechanism**: The SDK's `createSseClient` registers an abort listener at `serverSentEvents.gen.js:49` that calls `reader.cancel()`. Could the workflow-sdk pass its own `AbortSignal` (composed from the watchdog + the global subscription controller) to enable mid-read cancellation?
+
+4. **Process-level isolation**: Since each SDK session shares a single `OpenCodeClient` instance with one SSE event loop, would spawning separate client instances per workflow sub-agent eliminate the cross-session contention at the cost of additional server connections?
+
+5. **TCP keepalive tuning**: Could the OpenCode server or client configure TCP keepalive at the socket level (e.g., `SO_KEEPALIVE` with shorter intervals) to detect dead connections faster than the OS default 2-hour timeout?
diff --git a/research/docs/2026-03-02-copilot-sdk-ui-alignment.md b/research/docs/2026-03-02-copilot-sdk-ui-alignment.md
new file mode 100644
index 0000000000..7f419158af
--- /dev/null
+++ b/research/docs/2026-03-02-copilot-sdk-ui-alignment.md
@@ -0,0 +1,237 @@
+---
+date: 2026-03-02 01:35:08 UTC
+researcher: OpenCode
+git_commit: 0206c8ce8fb735fdf355eb95a48dd18775136f86
+branch: lavaman131/feature/workflow-sdk
+repository: workflow-sdk
+topic: "Research Copilot SDK UI features and alignment map for OpenCode and Claude Agent SDK UI"
+tags: [research, codebase, copilot-sdk, opencode-sdk, claude-agent-sdk, opentui, ui-alignment]
+status: complete
+last_updated: 2026-03-02
+last_updated_by: OpenCode
+last_updated_note: "Added follow-up research documenting OpenCode auto-compaction chat-stall gap"
+---
+
+# Research
+
+## Research Question
+Research the Copilot SDK UI features in this codebase and document how the OpenCode and Claude Agent SDK UI surfaces align with them, including feature parity, interaction patterns, visual language, architecture, and SDK-specific constraints.
+
+## Summary
+The repository already uses a shared OpenTUI chat surface and a provider-normalized event pipeline for Copilot, OpenCode, and Claude. Copilot-specific behavior appears mainly at adapter and command-dispatch boundaries, while most UI rendering components (parts registry, task panel, model selector, status/footer, transcript, and parallel agents tree) are shared.
+
+Alignment in the current codebase is expressed as: (1) unified UI primitives and event contracts, (2) provider-specific stream adapters that map SDK-native events to canonical `stream.*` bus events, and (3) targeted branch points where provider semantics differ (model switching session behavior, sub-agent invocation mechanics, and certain event constraints).
+
+## Detailed Findings
+
+### Copilot UI Feature Set (Current State)
+- Chat runtime selects `CopilotStreamAdapter` at startup and routes it through shared `ChatApp`/event bus wiring ([`src/ui/index.ts:462`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/index.ts#L462), [`src/ui/index.ts:475`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/index.ts#L475)).
+- Copilot adapter publishes normalized events (`stream.text.*`, `stream.thinking.*`, `stream.tool.*`, `stream.agent.*`, `stream.session.*`) to the shared bus ([`src/events/adapters/copilot-adapter.ts:98`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/events/adapters/copilot-adapter.ts#L98), [`src/events/adapters/copilot-adapter.ts:268`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/events/adapters/copilot-adapter.ts#L268)).
+- Slash command UX and autocomplete are shared across providers (`/model`, `/agent`, `/skill`, workflows), rendered inline in chat ([`src/ui/chat.tsx:6877`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/chat.tsx#L6877), [`src/ui/commands/registry.ts:319`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/commands/registry.ts#L319), [`src/ui/commands/builtin-commands.ts:308`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/commands/builtin-commands.ts#L308)).
+- Model selector dialog supports grouped providers, keyboard navigation, context window display, and optional reasoning effort selection ([`src/ui/components/model-selector-dialog.tsx:55`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/components/model-selector-dialog.tsx#L55), [`src/ui/components/model-selector-dialog.tsx:185`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/components/model-selector-dialog.tsx#L185)).
+- Task panel and task indicator are persistent/session-linked via workflow task files ([`src/ui/components/task-list-panel.tsx:159`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/components/task-list-panel.tsx#L159), [`src/ui/commands/workflow-commands.ts:731`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/commands/workflow-commands.ts#L731)).
+- Parallel agents tree and background-agent footer are rendered from the same shared components/state model ([`src/ui/components/parallel-agents-tree.tsx:743`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/components/parallel-agents-tree.tsx#L743), [`src/ui/components/background-agent-footer.tsx:17`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/components/background-agent-footer.tsx#L17)).
+
+### OpenCode and Claude UI Feature Set (Current State)
+- Startup chooses provider-specific adapters for OpenCode/Claude in the same runtime path ([`src/ui/index.ts:457`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/index.ts#L457), [`src/ui/index.ts:460`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/index.ts#L460)).
+- OpenCode and Claude adapters emit the same canonical tool/thinking/agent/session events consumed by shared UI reducers ([`src/events/adapters/opencode-adapter.ts:822`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/events/adapters/opencode-adapter.ts#L822), [`src/events/adapters/claude-adapter.ts:560`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/events/adapters/claude-adapter.ts#L560), [`src/events/consumers/stream-pipeline-consumer.ts:151`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/events/consumers/stream-pipeline-consumer.ts#L151)).
+- Sub-agent dispatch path differs by provider but shares command surface: OpenCode/Claude pass structured `agent` options; Copilot uses Task-tool instruction dispatch ([`src/ui/chat.tsx:4629`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/chat.tsx#L4629), [`src/ui/chat.tsx:4635`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/chat.tsx#L4635), [`src/ui/chat.tsx:4642`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/chat.tsx#L4642), [`src/ui/commands/agent-commands.ts:315`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/commands/agent-commands.ts#L315)).
+- Model switching behavior is unified through `UnifiedModelOperations` with provider-specific internals (Claude supportedModels aliasing, OpenCode provider models, Copilot list/set through SDK client path) ([`src/models/model-operations.ts:143`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/models/model-operations.ts#L143), [`src/models/model-operations.ts:229`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/models/model-operations.ts#L229), [`src/models/model-operations.ts:270`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/models/model-operations.ts#L270)).
+- Shared transcript rendering and parts-based message bubble rendering are provider-agnostic once events are normalized ([`src/ui/components/transcript-view.tsx:84`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/components/transcript-view.tsx#L84), [`src/ui/components/parts/registry.tsx:24`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/components/parts/registry.tsx#L24)).
+
+### Alignment Map: Copilot vs OpenCode/Claude Surfaces
+- **Rendering layer:** all three flow into the same part registry and stream reducer (`PART_REGISTRY`, `applyStreamPartEvent`) ([`src/ui/components/parts/registry.tsx:24`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/components/parts/registry.tsx#L24), [`src/ui/parts/stream-pipeline.ts:1063`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/parts/stream-pipeline.ts#L1063)).
+- **Event contracts:** `SDKStreamAdapter` and event-coverage policy define cross-provider contract, with Copilot constraints on `message.delta` and `message.complete` mappings ([`src/events/adapters/types.ts:16`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/events/adapters/types.ts#L16), [`src/events/adapters/event-coverage-policy.ts:136`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/events/adapters/event-coverage-policy.ts#L136)).
+- **Session lifecycle:** startup/session creation/interrupt/stream ownership are shared in `startChatUI`; adapters differ only at stream ingress ([`src/ui/index.ts:380`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/index.ts#L380), [`src/ui/index.ts:454`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/index.ts#L454), [`src/ui/index.ts:511`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/index.ts#L511)).
+- **Sub-agent invocation semantics:** same user-level command shape, different provider transport semantics (`options.agent` vs Task tool instruction) ([`src/ui/chat.tsx:4627`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/chat.tsx#L4627), [`src/ui/commands/agent-commands.ts:327`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/commands/agent-commands.ts#L327)).
+- **Config discovery surfaces:** unified command discovery scans `.claude`, `.opencode`, `.github` plus user/global variants; Copilot-specific manual loaders include `.github` and `~/.copilot` hierarchies ([`src/ui/commands/agent-commands.ts:34`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/commands/agent-commands.ts#L34), [`src/ui/commands/skill-commands.ts:56`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/commands/skill-commands.ts#L56), [`src/config/copilot-manual.ts:128`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/config/copilot-manual.ts#L128)).
+
+### Visual Language and Interaction Grammar (Frontend Design Lens, Current Implementation)
+- Theme system defines explicit semantic color tokens and dual palettes (Catppuccin Mocha/Latte), reused across UI components ([`src/ui/theme.tsx:20`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/theme.tsx#L20), [`src/ui/theme.tsx:215`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/theme.tsx#L215), [`src/ui/theme.tsx:247`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/theme.tsx#L247)).
+- Interaction model is keyboard-first and consistent across surfaces (j/k arrows, enter, esc, number shortcuts, ctrl-modified global toggles) in model selector, autocomplete, transcript/task panel toggles ([`src/ui/components/model-selector-dialog.tsx:199`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/components/model-selector-dialog.tsx#L199), [`src/ui/chat.tsx:5881`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/chat.tsx#L5881), [`src/ui/chat.tsx:5702`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/chat.tsx#L5702)).
+- Status language is compact and layered: footer status, queue indicator, task list indicator, background-agent footer, and loading/completion summaries ([`src/ui/components/footer-status.tsx:39`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/components/footer-status.tsx#L39), [`src/ui/components/queue-indicator.tsx:103`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/components/queue-indicator.tsx#L103), [`src/ui/components/task-list-indicator.tsx:52`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/components/task-list-indicator.tsx#L52)).
+- Reasoning/thinking has dedicated visual treatment in stream parts and syntax dimming utilities, reused regardless of provider source ([`src/events/consumers/stream-pipeline-consumer.ts:138`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/events/consumers/stream-pipeline-consumer.ts#L138), [`src/ui/theme.tsx:549`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/theme.tsx#L549)).
+
+### External Copilot SDK/CLI Documentation (UI-Relevant)
+- Copilot SDK repository and docs: session lifecycle, streaming events, tool execution events, and language SDK examples.
+  - https://github.com/github/copilot-sdk
+  - https://github.com/github/copilot-sdk/blob/main/docs/getting-started.md
+  - https://github.com/github/copilot-sdk/blob/main/nodejs/src/generated/session-events.ts
+  - https://github.com/github/copilot-sdk/blob/main/nodejs/samples/chat.ts
+- Copilot CLI docs: interactive mode, model selection, streaming toggle, resume/session controls, agent/skill command surfaces.
+  - https://docs.github.com/en/copilot/reference/cli-command-reference
+  - https://docs.github.com/en/copilot/how-tos/copilot-cli/use-copilot-cli
+  - https://docs.github.com/en/copilot/how-tos/copilot-cli/set-up-copilot-cli/configure-copilot-cli
+- ACP server reference for custom terminal/IDE frontends.
+  - https://docs.github.com/en/copilot/reference/acp-server
+
+## Code References
+- `src/ui/index.ts:230` - Unified model operation wiring (`sdkSetModel`) across provider clients.
+- `src/ui/index.ts:457` - OpenCode stream adapter selection.
+- `src/ui/index.ts:460` - Claude stream adapter selection.
+- `src/ui/index.ts:462` - Copilot stream adapter selection.
+- `src/ui/chat.tsx:4493` - Model selector apply path with reasoning effort and persisted preference.
+- `src/ui/chat.tsx:4629` - OpenCode sub-agent dispatch semantics.
+- `src/ui/chat.tsx:4635` - Claude sub-agent dispatch semantics.
+- `src/ui/chat.tsx:4642` - Copilot Task-tool dispatch semantics.
+- `src/ui/commands/agent-commands.ts:34` - Cross-provider agent discovery paths.
+- `src/ui/commands/skill-commands.ts:56` - Cross-provider skill discovery paths.
+- `src/config/copilot-manual.ts:128` - Copilot agent loading and precedence across `.github`, `.claude`, `.opencode`, and global paths.
+- `src/models/model-operations.ts:143` - Provider switch for listAvailableModels.
+- `src/events/adapters/types.ts:16` - Shared SDK stream adapter contract.
+- `src/events/adapters/event-coverage-policy.ts:150` - Provider event-coverage policy matrix.
+- `src/events/consumers/stream-pipeline-consumer.ts:128` - Canonical bus-event to stream-part mapping.
+- `src/ui/components/parts/registry.tsx:24` - Shared part renderer registry used by all providers.
+- `src/ui/theme.tsx:215` - Dark theme semantic token values.
+- `src/ui/theme.tsx:247` - Light theme semantic token values.
+
+## Architecture Documentation
+The UI architecture is composed of four layers:
+
+1. **Provider client + adapter ingress**
+   - SDK clients expose provider-native session/event APIs.
+   - Provider adapters (`opencode`, `claude`, `copilot`) normalize events into canonical bus events.
+
+2. **Shared event infrastructure**
+   - `EventBus` + `BatchDispatcher` + stream consumer wiring coalesce events and pass normalized batches to UI state handlers.
+
+3. **Stream-part and state normalization**
+   - Canonical events map to stream part events (`text-delta`, `tool-start`, `thinking-meta`, `agent-*`).
+   - Reducers reconcile stream parts into message state.
+
+4. **Provider-agnostic UI composition**
+   - Shared rendering components: message bubble parts, transcript view, task panel, footer/status, model selector, parallel agents tree.
+   - Provider distinctions remain at dispatch and model/session semantics boundaries.
+
+## Historical Context (from research/)
+- `research/docs/2026-02-12-sdk-ui-standardization-comprehensive.md` - Documents existing cross-SDK UI normalization strategy and known parity notes.
+- `research/docs/2026-02-23-sdk-subagent-api-research.md` - Documents provider differences in sub-agent hierarchy identifiers and lifecycle event shape.
+- `research/docs/2026-02-25-ui-workflow-coupling.md` - Documents coupling points between workflow runtime state and chat UI command/state surfaces.
+- `research/docs/2026-02-26-streaming-architecture-event-bus-migration.md` - Documents stream primitive heterogeneity and event-bus unification model.
+- `research/docs/2026-03-01-opencode-delegation-streaming-parity.md` - Documents delegation and continuation behavior differences across SDK paths.
+
+## Related Research
+- `research/docs/2026-01-31-github-copilot-sdk-research.md`
+- `research/docs/2026-01-31-opencode-sdk-research.md`
+- `research/docs/2026-01-31-claude-agent-sdk-research.md`
+- `research/docs/2026-02-15-sub-agent-tree-status-lifecycle-sdk-parity.md`
+- `research/docs/2026-03-01-opencode-tui-concurrency-bottlenecks.md`
+
+## Open Questions
+- Copilot event-coverage policy includes constrained mappings for `message.complete`; this document records the current mapping but does not trace every downstream UX implication in each workflow mode.
+- Provider-specific model-switch semantics are documented in code paths; runtime behavior under every CLI/provider deployment mode (local vs remote/copilot ACP variants) is not exhaustively enumerated here.
+- Existing research documents include multiple parity investigations; this report synthesizes the most relevant current-state findings and code references for UI alignment.
+
+## Follow-up Research 2026-03-02 01:45:21 UTC
+
+### Follow-up Question
+Investigate why sub-agent UI behavior matches `docs/ui-design-patterns.md` for Copilot but appears to miss tool-call streaming and remains in initialization state for Claude/OpenCode.
+
+### Findings
+- Design-pattern expectation explicitly requires transition from initialization to execution with tool-use counts and current tool lines ([`docs/ui-design-patterns.md:46`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/docs/ui-design-patterns.md#L46), [`docs/ui-design-patterns.md:56`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/docs/ui-design-patterns.md#L56)).
+- In current tree rendering, tool/text inline parts are globally suppressed; the tree shows progress via sub-status + current-tool line rather than raw tool blocks ([`src/ui/components/parallel-agents-tree.tsx:151`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/components/parallel-agents-tree.tsx#L151)).
+- "Initializing" persists while an agent is running/pending and `toolUses` is `0`/`undefined`; execution text appears only when `toolUses > 0`, and current-tool line also requires `toolUses > 0` ([`src/ui/components/parallel-agents-tree.tsx:597`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/components/parallel-agents-tree.tsx#L597), [`src/ui/components/parallel-agents-tree.tsx:600`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/components/parallel-agents-tree.tsx#L600), [`src/ui/components/parallel-agents-tree.tsx:613`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/components/parallel-agents-tree.tsx#L613)).
+- `toolUses/currentTool` display depends on `stream.agent.update` handling in chat subscriptions (side channel) rather than stream-part mapping ([`src/ui/chat.tsx:3452`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/chat.tsx#L3452), [`src/events/consumers/stream-pipeline-consumer.ts:242`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/events/consumers/stream-pipeline-consumer.ts#L242)).
+- Sub-agent tool count increments are emitted by `SubagentToolTracker` (`toolCount += 1` on tool start) and published as `stream.agent.update` ([`src/events/adapters/subagent-tool-tracker.ts:64`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/events/adapters/subagent-tool-tracker.ts#L64), [`src/events/adapters/subagent-tool-tracker.ts:97`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/events/adapters/subagent-tool-tracker.ts#L97)).
+- Copilot path includes parent-agent resolution via `parentId`/`parentToolCallId` plus early-tool buffering/replay keyed by subagent or tool call, then tracker updates ([`src/events/adapters/copilot-adapter.ts:610`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/events/adapters/copilot-adapter.ts#L610), [`src/events/adapters/copilot-adapter.ts:650`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/events/adapters/copilot-adapter.ts#L650), [`src/events/adapters/copilot-adapter.ts:919`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/events/adapters/copilot-adapter.ts#L919)).
+- Claude path gates tool events by root session equality and requires parent-agent resolution + tracker registration for tool-count updates; unresolved early events are queued by agent/tool correlation keys ([`src/events/adapters/claude-adapter.ts:562`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/events/adapters/claude-adapter.ts#L562), [`src/events/adapters/claude-adapter.ts:590`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/events/adapters/claude-adapter.ts#L590), [`src/events/adapters/claude-adapter.ts:592`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/events/adapters/claude-adapter.ts#L592), [`src/events/adapters/claude-adapter.ts:1136`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/events/adapters/claude-adapter.ts#L1136)).
+- OpenCode path gates updates by owned-session membership and parent-agent resolution from explicit parent IDs or discovered child-session mappings; ownership is established from `subagent.start` metadata (`subagentSessionId`) ([`src/events/adapters/opencode-adapter.ts:825`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/events/adapters/opencode-adapter.ts#L825), [`src/events/adapters/opencode-adapter.ts:936`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/events/adapters/opencode-adapter.ts#L936), [`src/events/adapters/opencode-adapter.ts:1013`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/events/adapters/opencode-adapter.ts#L1013), [`src/events/adapters/opencode-adapter.ts:1631`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/events/adapters/opencode-adapter.ts#L1631)).
+
+### Follow-up Evidence Map
+- UI state transition rule (Initializing -> tool-count execution): `src/ui/components/parallel-agents-tree.tsx:597`, `src/ui/components/parallel-agents-tree.tsx:600`, `src/ui/components/parallel-agents-tree.tsx:613`.
+- Agent update channel location: `src/ui/chat.tsx:3452`, `src/events/consumers/stream-pipeline-consumer.ts:242`.
+- Tracker increment source: `src/events/adapters/subagent-tool-tracker.ts:64`.
+- Provider-specific conditions:
+  - Copilot: `src/events/adapters/copilot-adapter.ts:610`, `src/events/adapters/copilot-adapter.ts:919`.
+  - Claude: `src/events/adapters/claude-adapter.ts:562`, `src/events/adapters/claude-adapter.ts:590`, `src/events/adapters/claude-adapter.ts:1136`.
+  - OpenCode: `src/events/adapters/opencode-adapter.ts:825`, `src/events/adapters/opencode-adapter.ts:1013`, `src/events/adapters/opencode-adapter.ts:1631`.
+
+### Historical Context for This Follow-up
+- `research/docs/2026-02-28-workflow-issues-research.md` documents the same initialization/tool-use dependency and split-channel update path (`:69`, `:87`, `:93`, `:107`).
+- `research/docs/2026-03-01-opencode-delegation-streaming-parity.md` documents continued event-consumption gaps in streamed rendering paths (`:70`, `:71`).
+
+## Follow-up Research 2026-03-02 01:55:41 UTC
+
+### Follow-up Question
+Investigate why, for OpenCode/Claude sub-agent trees, task descriptions can disappear after completion and display sub-agent names instead, and document edge cases for natural-language and `@`-symbol invocation paths.
+
+### Findings
+- The displayed row title uses `getAgentTaskLabel`, which returns `agent.name` whenever `agent.task` is considered generic (`""`, `"sub-agent task"`, `"subagent task"`) ([`src/ui/components/parallel-agents-tree.tsx:248`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/components/parallel-agents-tree.tsx#L248), [`src/ui/components/parallel-agents-tree.tsx:253`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/components/parallel-agents-tree.tsx#L253)).
+- OpenCode emits repeated `subagent.start` events for the same logical sub-agent from multiple code paths (initial synthesis, child-session discovery, running-time relabel, completion-time relink, AgentPart/SubtaskPart merges) ([`src/sdk/clients/opencode.ts:1382`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/sdk/clients/opencode.ts#L1382), [`src/sdk/clients/opencode.ts:1459`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/sdk/clients/opencode.ts#L1459), [`src/sdk/clients/opencode.ts:1475`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/sdk/clients/opencode.ts#L1475), [`src/sdk/clients/opencode.ts:1539`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/sdk/clients/opencode.ts#L1539), [`src/sdk/clients/opencode.ts:1658`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/sdk/clients/opencode.ts#L1658), [`src/sdk/clients/opencode.ts:1724`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/sdk/clients/opencode.ts#L1724)).
+- Task text normalization falls back to `agentType` when no `toolInput` description/prompt/task and no explicit event task exist; this creates non-descriptive task labels that match agent names ([`src/events/adapters/task-turn-normalization.ts:117`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/events/adapters/task-turn-normalization.ts#L117), [`src/events/adapters/task-turn-normalization.ts:123`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/events/adapters/task-turn-normalization.ts#L123)).
+- Chat-side merge on repeated `stream.agent.start` updates active rows in place with `task: data.task || agent.task`; terminal rows (`completed/error/interrupted`) are removed and recreated. Both paths can replace previously visible labels when incoming start events carry fallback task text ([`src/ui/chat.tsx:3405`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/chat.tsx#L3405), [`src/ui/chat.tsx:3427`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/chat.tsx#L3427), [`src/ui/chat.tsx:3442`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/chat.tsx#L3442)).
+- Deduplication keeps non-generic tasks when present, but if merged candidates both carry generic/fallback task text, final display still resolves to agent name ([`src/ui/components/parallel-agents-tree.tsx:323`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/components/parallel-agents-tree.tsx#L323), [`src/ui/components/parallel-agents-tree.tsx:337`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/components/parallel-agents-tree.tsx#L337), [`src/ui/components/parallel-agents-tree.tsx:591`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/components/parallel-agents-tree.tsx#L591)).
+- Claude sub-agent starts rely on hook-derived task fields or a `task_started` cache; when neither yields descriptive text, normalized fallback behavior applies ([`src/sdk/clients/claude.ts:1252`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/sdk/clients/claude.ts#L1252), [`src/sdk/clients/claude.ts:1781`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/sdk/clients/claude.ts#L1781), [`src/events/adapters/claude-adapter.ts:1040`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/events/adapters/claude-adapter.ts#L1040)).
+
+### Invocation Edge Cases (Natural Language and `@`)
+- Submit-time agent mention execution only runs when the message starts with `@`; embedded/mid-sentence `@agent` text is not routed through the mention branch on normal submit ([`src/ui/chat.tsx:6550`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/chat.tsx#L6550)).
+- Prefix `@agent` input uses `parseAtMentions` and executes one command per parsed mention with args segmented between mention tokens ([`src/ui/utils/mention-parsing.ts:58`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/utils/mention-parsing.ts#L58), [`src/ui/utils/mention-parsing.ts:76`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/utils/mention-parsing.ts#L76), [`src/ui/chat.tsx:6581`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/chat.tsx#L6581)).
+- Autocomplete mention mode can execute an agent even for mid-text mentions by extracting `remaining = (before + after).trim()` and running `executeCommand` directly ([`src/ui/chat.tsx:6235`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/chat.tsx#L6235), [`src/ui/chat.tsx:6238`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/chat.tsx#L6238), [`src/ui/chat.tsx:6252`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/chat.tsx#L6252)).
+- Natural-language (non-`@`) inputs go through normal `sendMessage` streaming and depend on SDK-generated sub-agent metadata for task labels, not explicit command args ([`src/ui/chat.tsx:6588`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/chat.tsx#L6588), [`src/ui/chat.tsx:6669`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/chat.tsx#L6669), [`src/ui/index.ts:475`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/index.ts#L475)).
+
+### Relevant Existing Tests
+- Adapter lifecycle and task/updates/completion coverage: `src/events/adapters/adapters.test.ts:2313`, `src/events/adapters/adapters.test.ts:2427`, `src/events/adapters/adapters.test.ts:2432`, `src/events/adapters/adapters.test.ts:2438`.
+- OpenCode repeated synthesized starts and stable subagentType assertions: `src/sdk/clients/opencode.events.test.ts:2337`, `src/sdk/clients/opencode.events.test.ts:2431`, `src/sdk/clients/opencode.events.test.ts:2435`.
+- Terminal-row replacement with new starts: `src/ui/subagent-tree-orphan-fix.test.ts:93`, `src/ui/subagent-tree-orphan-fix.test.ts:112`, `src/ui/subagent-tree-orphan-fix.test.ts:117`, `src/ui/subagent-tree-orphan-fix.test.ts:139`.
+- Mention path single-assistant-message behavior: `src/ui/chat.at-command-single-assistant-message.test.ts:41`, `src/ui/chat.at-command-single-assistant-message.test.ts:62`.
+
+## Follow-up Research 2026-03-02 02:07:35 UTC
+
+### Follow-up Question
+Investigate why task tool output is not propagated into the main chat response for `@` sub-agent invocations, especially in OpenCode and Claude SDK paths.
+
+### Findings
+- `@agent` execution routes through silent command dispatch (`executeCommand` -> `sendSilentMessage` -> `startAssistantStream`) rather than normal user message submission ([`src/ui/chat.tsx:6581`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/chat.tsx#L6581), [`src/ui/chat.tsx:4608`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/chat.tsx#L4608), [`src/ui/chat.tsx:3572`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/chat.tsx#L3572)).
+- OpenCode `@agent` command marks streams as `isAgentOnlyStream: true`; Claude `@agent` command does not set this flag ([`src/ui/commands/agent-commands.ts:319`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/commands/agent-commands.ts#L319), [`src/ui/commands/agent-commands.ts:325`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/commands/agent-commands.ts#L325), [`src/ui/commands/registry.ts:39`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/commands/registry.ts#L39)).
+- Agent-scoped text/tool events are routed into agent inline parts, not main assistant `message.content`; main content accumulation explicitly skips `agentId` deltas ([`src/ui/chat.tsx:2938`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/chat.tsx#L2938), [`src/ui/parts/stream-pipeline.ts:1070`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/parts/stream-pipeline.ts#L1070), [`src/ui/parts/stream-pipeline.ts:1150`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/parts/stream-pipeline.ts#L1150)).
+- OpenCode agent-only finalization contains the only explicit promotion of sub-agent results into main message content, but it is gated: when `msg.toolCalls.length > 0`, content is left unchanged instead of replaced with aggregated agent results ([`src/ui/chat.tsx:4015`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/chat.tsx#L4015), [`src/ui/chat.tsx:4027`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/chat.tsx#L4027)).
+- Claude non-agent-only completion path (`handleStreamComplete`) finalizes stream state/parts but does not copy `parallelAgents[].result` into main message content ([`src/ui/chat.tsx:2869`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/chat.tsx#L2869), [`src/ui/chat.tsx:2882`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/chat.tsx#L2882)).
+- For both providers, `stream.agent.complete.result` is preserved on agent rows in tree state, but stream-part mapping intentionally omits `stream.agent.*` from the main part pipeline ([`src/ui/chat.tsx:3519`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/chat.tsx#L3519), [`src/events/consumers/stream-pipeline-consumer.ts:242`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/events/consumers/stream-pipeline-consumer.ts#L242)).
+- Existing stream-pipeline tests assert that completed sub-agent results remain separate from main continuation text, matching this behavior ([`src/ui/parts/stream-pipeline.test.ts:814`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/parts/stream-pipeline.test.ts#L814), [`src/ui/parts/stream-pipeline.test.ts:859`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/parts/stream-pipeline.test.ts#L859)).
+
+### Provider-Specific Emission Notes
+- Claude: sub-agent completion result comes from task-notification summary path to `subagent.complete` and then adapter `stream.agent.complete` ([`src/sdk/clients/claude.ts:1273`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/sdk/clients/claude.ts#L1273), [`src/events/adapters/claude-adapter.ts:1110`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/events/adapters/claude-adapter.ts#L1110)).
+- OpenCode: synthesized task-agent completion emits `result` from task tool output into `subagent.complete`, then adapter publishes `stream.agent.complete` ([`src/sdk/clients/opencode.ts:1547`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/sdk/clients/opencode.ts#L1547), [`src/events/adapters/opencode-adapter.ts:989`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/events/adapters/opencode-adapter.ts#L989)).
+
+### Related Test Coverage
+- `@` command single assistant message creation: `src/ui/chat.at-command-single-assistant-message.test.ts:41`, `src/ui/chat.at-command-single-assistant-message.test.ts:62`.
+- Agent-only finalization guard logic: `src/ui/chat.stream-lifecycle-run-guard.test.ts:47`, `src/ui/chat.stream-lifecycle-run-guard.test.ts:72`.
+- Main-text vs subagent-result separation expectations: `src/ui/parts/stream-pipeline.test.ts:814`, `src/ui/parts/stream-pipeline.test.ts:929`.
+
+## Follow-up Research 2026-03-02 02:15:07 UTC
+
+### Follow-up Question
+Investigate why Claude `@` sub-agent invocation does not show sub-agent tree entries and whether this path uses separate context/session isolation.
+
+### Findings
+- Claude `@agent` command path does pass the agent name through end-to-end into Claude SDK query options (`options.agent`) ([`src/ui/commands/agent-commands.ts:325`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/commands/agent-commands.ts#L325), [`src/ui/index.ts:479`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/index.ts#L479), [`src/events/adapters/claude-adapter.ts:304`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/events/adapters/claude-adapter.ts#L304), [`src/sdk/clients/claude.ts:794`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/sdk/clients/claude.ts#L794), [`src/sdk/clients/claude.stream-agent-option.test.ts:84`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/sdk/clients/claude.stream-agent-option.test.ts#L84)).
+- Claude tree rows require `stream.agent.start`; `stream.agent.update` and `stream.agent.complete` only mutate existing rows and do not create new entries ([`src/ui/chat.tsx:3369`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/chat.tsx#L3369), [`src/ui/chat.tsx:3452`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/chat.tsx#L3452), [`src/ui/chat.tsx:3503`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/chat.tsx#L3503)).
+- Claude client stream message mapping does not synthesize sub-agent lifecycle from stream chunks; `subagent.start`/`subagent.complete` are hook-driven pathways (`SubagentStart`/`SubagentStop`) ([`src/sdk/clients/claude.ts:114`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/sdk/clients/claude.ts#L114), [`src/sdk/clients/claude.ts:133`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/sdk/clients/claude.ts#L133), [`src/sdk/clients/claude.ts:1716`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/sdk/clients/claude.ts#L1716)).
+- Adapter handler for Claude `subagent.start` filters by exact wrapped session match (`event.sessionId === this.sessionId`), so non-matching routed events are dropped before bus publish ([`src/events/adapters/claude-adapter.ts:1026`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/events/adapters/claude-adapter.ts#L1026)).
+- Hook routing logic maps SDK `session_id` back to wrapped session IDs and can fall back to unresolved/ambiguous resolution paths; this is the path that determines whether sub-agent lifecycle events attach to the active UI session ([`src/sdk/clients/claude.ts:1451`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/sdk/clients/claude.ts#L1451), [`src/sdk/clients/claude.ts:1512`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/sdk/clients/claude.ts#L1512), [`src/sdk/clients/claude.ts:1821`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/sdk/clients/claude.ts#L1821)).
+
+### Session/Context Behavior for Claude `@agent`
+- `@agent` invocation uses the same wrapped Claude session stream path (`sendSilentMessage` -> `startAssistantStream` -> `handleStreamMessage`), not `createSubagentSession` ([`src/ui/chat.tsx:4608`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/chat.tsx#L4608), [`src/ui/chat.tsx:3572`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/chat.tsx#L3572), [`src/ui/index.ts:422`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/index.ts#L422)).
+- Claude stream path resumes the same SDK session (`options.resume = sdkSessionId`) and applies `options.agent` per-turn; no new wrapped session is created for `@agent` dispatch ([`src/sdk/clients/claude.ts:789`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/sdk/clients/claude.ts#L789), [`src/sdk/clients/claude.ts:791`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/sdk/clients/claude.ts#L791), [`src/sdk/clients/claude.ts:794`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/sdk/clients/claude.ts#L794)).
+- Context usage (`inputTokens`, `outputTokens`, `contextWindow`) is stored and reported from this same session state, so accounting is shared with the parent session flow ([`src/sdk/clients/claude.ts:1085`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/sdk/clients/claude.ts#L1085), [`src/sdk/clients/claude.ts:1086`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/sdk/clients/claude.ts#L1086), [`src/sdk/clients/claude.ts:1324`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/sdk/clients/claude.ts#L1324)).
+- The code path that explicitly creates isolated session contexts is `spawnSubagentParallel` via `createSubagentSession`, which is separate from `@agent` command dispatch ([`src/ui/chat.tsx:813`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/chat.tsx#L813), [`src/ui/chat.tsx:4667`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/chat.tsx#L4667), [`src/ui/chat.tsx:4728`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/chat.tsx#L4728)).
+
+### Supporting SDK Documentation (repo docs)
+- Claude SDK `Options.agent` is documented as "Agent name for the main thread" ([`docs/claude-agent-sdk.md:144`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/docs/claude-agent-sdk.md#L144)).
+- Claude SDK `agents` option documents programmatic subagent definitions ([`docs/claude-agent-sdk.md:145`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/docs/claude-agent-sdk.md#L145)).
+
+## Follow-up Research 2026-03-02 02:27:44 UTC
+
+### Follow-up Question
+Investigate reported OpenCode SDK behavior where auto-compaction freezes/stalls the chat TUI instead of cleanly resuming or finalizing the turn.
+
+### Findings
+- OpenCode stream auto-compaction is executed inline in the active stream loop (`await session.summarize()` in both proactive-threshold and overflow paths), so stream progress is serialized behind compaction completion ([`src/sdk/clients/opencode.ts:2607`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/sdk/clients/opencode.ts#L2607), [`src/sdk/clients/opencode.ts:2638`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/sdk/clients/opencode.ts#L2638)).
+- `summarize()` has no abort-signal or timeout guard: it awaits SDK summarize then awaits `session.messages()` refresh before the stream loop can proceed, creating a stall point when either call hangs/slow-paths ([`src/sdk/clients/opencode.ts:2688`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/sdk/clients/opencode.ts#L2688), [`src/sdk/clients/opencode.ts:2698`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/sdk/clients/opencode.ts#L2698)); by contrast, prompt dispatch wires abort handling (`promptAsync(..., { signal })`) in stream/send paths ([`src/sdk/clients/opencode.ts:2231`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/sdk/clients/opencode.ts#L2231), [`src/sdk/clients/opencode.ts:2487`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/sdk/clients/opencode.ts#L2487)).
+- Chat finalization still depends on `stream.session.idle` continuation gating and does not branch on compaction-specific idle reason (`context_compacted`), so a stalled/missed post-compaction terminal path leaves stream state active ([`src/ui/chat.tsx:3157`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/chat.tsx#L3157), [`src/ui/chat.tsx:3186`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/chat.tsx#L3186)).
+- Continuation policy intentionally keeps loops alive on `tool-calls`/`unknown` finish reasons and any pending-work flags; when these flags are not cleared after compaction, `handleStreamComplete()` is skipped and chat remains in streaming/stalled mode ([`src/ui/utils/stream-continuation.ts:70`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/utils/stream-continuation.ts#L70), [`src/ui/utils/stream-continuation.ts:113`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/utils/stream-continuation.ts#L113), [`src/ui/chat.session-idle-flush.test.ts:180`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/chat.session-idle-flush.test.ts#L180)).
+- Queue dispatch is gated by `isStreaming`; once stream state is stuck, queued user turns do not dispatch, matching the observed “chat stalled/frozen” behavior at the TUI layer ([`src/ui/utils/stream-continuation.ts:236`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/utils/stream-continuation.ts#L236), [`src/ui/chat.tsx:2111`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/ui/chat.tsx#L2111)).
+- Current OpenCode proactive-compaction test coverage confirms summarize invocation but does not assert end-to-end UI lifecycle recovery (stream finalization, queue unblocking, or post-compaction continuation), leaving this stall class unguarded ([`src/sdk/clients/opencode.events.test.ts:2543`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/sdk/clients/opencode.events.test.ts#L2543), [`src/sdk/clients/opencode.events.test.ts:2634`](https://github.com/flora131/atomic/blob/0206c8ce8fb735fdf355eb95a48dd18775136f86/src/sdk/clients/opencode.events.test.ts#L2634)).
+
+### Implementation Gap (Documented)
+- The OpenCode auto-compaction path is missing a resilient completion contract for the chat runtime: compaction work is inline and blocking, but lifecycle completion/queue recovery still assumes timely terminal stream events. There is no compaction-specific watchdog/fallback to force safe stream finalization when compaction stalls or lifecycle events do not fully reconcile.
diff --git a/research/ralph-workflow.md b/research/ralph-workflow.md
new file mode 100644
index 0000000000..28d04378ed
--- /dev/null
+++ b/research/ralph-workflow.md
@@ -0,0 +1,4 @@
+- sub-agent tree state is not streaming tool calls, tool call counts, stuck at "Initializing..."
+- code-review stage in ralph workflow should not run after each item in the task list is complete, but only at the very end of the workflow, after all items in the task list are complete. This is because code review is a final step that should be performed after all tasks have been completed, rather than after each individual task. By waiting until the end of the workflow to perform code review, it allows for a more comprehensive review of the entire codebase and ensures that all changes have been made before the review process begins.
+- when multiple tasks are runnable at the same time, we should run them in parallel instead of sequentially. This can help to speed up the overall workflow and improve efficiency. By running tasks in parallel, we can take advantage of available resources and reduce the time it takes to complete the workflow. However, it's important to ensure that tasks that have dependencies on each other are still executed in the correct order to avoid any issues or errors.
+- Issue in streaming where once TODO list is marked as complete, there is a few seconds of delay until the final stream is sent and duration/final tokens output message (e.g. ⣿ Composed for 2m 47s · ↓ 21.0k tokens) is output
\ No newline at end of file
diff --git a/research/workflow-gaps.md b/research/workflow-gaps.md
new file mode 100644
index 0000000000..27982ace0d
--- /dev/null
+++ b/research/workflow-gaps.md
@@ -0,0 +1,10 @@
+🔴 High-Impact Gaps
+1. WorkflowStep rendering pipeline is broken — Events flow, parts are created, but WorkflowStepPartDisplay isn't registered in PART_REGISTRY so step transitions are silently discarded
+2. Custom tool discovery (registerCustomTools()) is never called — The entire .atomic/tools/ pipeline is built but never activated, needs to call registerCustomTools() during init
+3. OpenCode MCP bridge returns placeholder strings instead of executing actual tool handlers
+4. --max-iterations CLI flag is parsed then silently dropped at chat.ts:197, remove this flag completely
+
+🟡 Medium-Impact
+- 6 dead modules (debug-subscriber, tool discovery, file-lock, merge, pipeline-logger, tree-hints) — fully implemented, never imported
+- 6 unrendered UI components (WorkflowStepPartDisplay, UserQuestionInline, FooterStatus, TimestampDisplay, StreamingBullet, CodeBlock)
+- 12 event types emitted but never consumed (session info/warning/title_changed/truncation/compaction, turn start/end, tool partial results, workflow steps, skill invoked)
\ No newline at end of file
diff --git a/specs/at-command-duplicate-subagent-tree-fix.md b/specs/at-command-duplicate-subagent-tree-fix.md
new file mode 100644
index 0000000000..e7aea7160c
--- /dev/null
+++ b/specs/at-command-duplicate-subagent-tree-fix.md
@@ -0,0 +1,383 @@
+# @ Command Duplicate Sub-Agent Tree Fix — Technical Design Document
+
+| Document Metadata      | Details                                       |
+| ---------------------- | --------------------------------------------- |
+| Author(s)              | lavaman131                                    |
+| Status                 | Draft (WIP)                                   |
+| Team / Owner           | Atomic CLI                                    |
+| Created / Last Updated | 2026-02-25                                    |
+
+## 1. Executive Summary
+
+When users invoke sub-agents via `@` commands (e.g., `@worker do X`), the sub-agent tree briefly renders twice then collapses — a visible UI glitch. The root cause is a **dual assistant message creation pattern**: the `@` handler creates a placeholder message (Message A) for immediate UI feedback, then `sendSilentMessage` creates a second message (Message B) for the actual SDK stream. Due to React's asynchronous state batching, both messages coexist transiently, each rendering its own agent tree. The proposed fix **eliminates the placeholder message** and unifies the `@` command pathway to use a single assistant message — matching the natural language pathway's clean single-message flow. This is a ~30-line surgical change across 1-2 files.
+
+## 2. Context and Motivation
+
+### 2.1 Current State
+
+The Atomic CLI TUI renders sub-agent trees (showing spawned agents, their status, and results) when users invoke agents. There are two pathways to invoke agents:
+
+1. **Natural Language Pathway** — User types "use the worker agent to do X" → SDK streams response → single assistant message → single agent tree (works correctly)
+2. **@ Command Pathway** — User types `@worker do X` → creates placeholder assistant message → `executeCommand` → `sendSilentMessage` creates second assistant message → dual agent tree (broken)
+
+**Architecture (Current):**
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                    @ COMMAND PATHWAY                         │
+│                                                              │
+│  User types "@worker do X"                                   │
+│       ↓                                                      │
+│  handleSubmit detects "@" prefix                             │
+│       ↓                                                      │
+│  Creates user message + placeholder assistant (Message A)    │
+│  Sets isAgentOnlyStreamRef = true                            │
+│       ↓                                                      │
+│  void executeCommand("worker", "do X")  ← fire-and-forget   │
+│       ↓                                                      │
+│  agent-commands.ts → sendSilentMessage(instruction)          │
+│       ↓                                                      │
+│  sendSilentMessage:                                          │
+│    1. Tries to remove Message A (async React setState)       │
+│    2. Creates Message B (new assistant message)              │
+│    3. Sets isAgentOnlyStreamRef = false                      │
+│    4. Calls onSendMessage → SDK                              │
+│       ↓                                                      │
+│  ⚠️ TRANSIENT STATE: Both Message A & B may exist briefly   │
+│       ↓                                                      │
+│  SDK processes instruction → LLM calls Task tool             │
+│       ↓                                                      │
+│  tool.start → eager ParallelAgent created                    │
+│  subagent.start → merge with eager agent                     │
+│       ↓                                                      │
+│  parallelAgents useEffect → applies to Message B             │
+│       ↓                                                      │
+│  deduplicateAgents() at render → collapses duplicates        │
+└──────────────────────────────────────────────────────────────┘
+```
+
+**Limitations:**
+- Dual message creation causes transient duplicate tree rendering
+- `streamingMessageIdRef` mutates mid-flow (Message A → Message B), creating a targeting window for misapplied agents
+- `isAgentOnlyStreamRef` flag toggles (`true` → `false`), causing inconsistent finalization guard behavior
+- Fire-and-forget `void executeCommand()` provides no coordination between placeholder setup and real message creation
+
+> **Ref:** [research/docs/2026-02-25-at-command-duplicate-subagent-tree.md](../research/docs/2026-02-25-at-command-duplicate-subagent-tree.md) — Root cause analysis identifying 5 contributing factors to the race condition.
+
+### 2.2 The Problem
+
+- **User Impact:** When invoking `@worker`, `@debugger`, or other agent commands, users see a brief flash of two identical agent trees that then collapse into one. This is visually jarring and suggests instability.
+- **Technical Debt:** The dual-message pattern is unique to the `@` command pathway and diverges from the clean single-message architecture used by natural language invocation. The system relies on 4 layers of deduplication (eager merge, pipeline grouping, render-time dedup, shadow detection) to paper over a creation bug.
+- **Precedent:** An identical dual-path rendering issue was previously fixed for skill loading indicators (Issue #205), where the solution was to **eliminate one rendering path** rather than trying to coordinate both.
+
+> **Ref:** [research/tickets/2026-02-15-205-skill-loading-indicator-duplicate.md](../research/tickets/2026-02-15-205-skill-loading-indicator-duplicate.md) — Prior art showing the "eliminate one path" fix strategy.
+
+## 3. Goals and Non-Goals
+
+### 3.1 Functional Goals
+
+- [ ] Eliminate the transient duplicate sub-agent tree rendering when using `@` commands
+- [ ] Unify the `@` command pathway to use a single assistant message, matching the natural language pathway
+- [ ] Preserve immediate streaming state feedback (spinner/loading indicator) when `@` commands are submitted
+- [ ] Maintain SDK parity across OpenCode, Claude, and Copilot agent dispatch
+- [ ] Ensure queued `@` mentions (during active streaming) continue to work correctly via `dispatchQueuedMessage`
+
+### 3.2 Non-Goals (Out of Scope)
+
+- [ ] We will NOT refactor `sendSilentMessage` broadly — only adjust its behavior for the `@` command pathway
+- [ ] We will NOT change the natural language agent invocation pathway (it already works correctly)
+- [ ] We will NOT modify the deduplication layers (they serve as defense-in-depth and should remain)
+- [ ] We will NOT change the SDK event pipeline (`tool.start`/`subagent.start` handling in `index.ts`)
+- [ ] We will NOT address the broader parts-based rendering migration (tracked separately in `specs/chat-system-parts-based-rendering.md`)
+
+## 4. Proposed Solution (High-Level Design)
+
+### 4.1 System Architecture Diagram (After Fix)
+
+```mermaid
+%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#f8f9fa','primaryTextColor':'#2c3e50','primaryBorderColor':'#4a5568','lineColor':'#4a90e2','secondaryColor':'#ffffff','tertiaryColor':'#e9ecef'}}}%%
+
+flowchart TB
+    classDef userAction fill:#5a67d8,stroke:#4c51bf,stroke-width:2.5px,color:#ffffff,font-weight:600
+    classDef sdkEvent fill:#48bb78,stroke:#38a169,stroke-width:2.5px,color:#ffffff,font-weight:600
+    classDef uiState fill:#4a90e2,stroke:#357abd,stroke-width:2.5px,color:#ffffff,font-weight:600
+    classDef removed fill:#e53e3e,stroke:#c53030,stroke-width:2.5px,color:#ffffff,font-weight:600,stroke-dasharray:6 3
+
+    User["User types @worker do X"]:::userAction
+    Detect["handleSubmit detects @ prefix"]:::uiState
+    UserMsg["addMessage('user', text)"]:::uiState
+    Stream["Set isStreamingRef = true<br>Set isAgentOnlyStreamRef = true"]:::uiState
+
+    PlaceholderRemoved["❌ NO placeholder assistant message<br>(Message A eliminated)"]:::removed
+
+    Exec["void executeCommand('worker', args)"]:::uiState
+    Silent["sendSilentMessage(instruction)"]:::uiState
+    MsgB["Creates single assistant message<br>(Message B only)"]:::uiState
+
+    SDK["SDK processes instruction"]:::sdkEvent
+    ToolStart["tool.start → eager ParallelAgent"]:::sdkEvent
+    SubStart["subagent.start → merge with eager"]:::sdkEvent
+
+    Effect["parallelAgents useEffect<br>→ applies to Message B"]:::uiState
+    Render["✅ Single tree renders cleanly"]:::uiState
+
+    User --> Detect --> UserMsg --> Stream --> Exec --> Silent --> MsgB --> SDK --> ToolStart --> SubStart --> Effect --> Render
+```
+
+### 4.2 Architectural Pattern
+
+**Single-Message Unification** — Eliminate the placeholder assistant message (Message A) from the `@` command pathway so that `sendSilentMessage` is the sole creator of the assistant message. This aligns the `@` command pathway with the natural language pathway's single-message flow.
+
+This follows the established **"eliminate one rendering path"** pattern used for the skill loading indicator duplicate fix (Issue #205).
+
+> **Ref:** [specs/skill-loading-indicator-duplicate-fix.md](./skill-loading-indicator-duplicate-fix.md) — Established the precedent of filtering/eliminating dual rendering paths.
+
+### 4.3 Key Components
+
+| Component | Responsibility | Change Required | Justification |
+| --- | --- | --- | --- |
+| `chat.tsx` @ handler (5632-5678) | Detects and dispatches `@` commands | Remove placeholder message creation (lines 5665-5673) | Root cause of dual-message pattern |
+| `chat.tsx` `sendSilentMessage` (3466-3520) | Creates streaming message for silent commands | Ensure it sets streaming state correctly when no placeholder exists | Must be sole message creator |
+| `chat.tsx` `dispatchQueuedMessage` (3177-3210) | Processes queued `@` mentions after streaming ends | Verify no placeholder creation in this path | Same race condition possible if queued path creates placeholders |
+| Deduplication layers | Defense-in-depth for agent duplicates | No change (preserve) | Continues to guard against other sources of duplicates |
+
+## 5. Detailed Design
+
+### 5.1 Fix 1: Remove Placeholder Message Creation from @ Handler
+
+**File:** `src/ui/chat.tsx` — `handleSubmit` function, lines ~5651-5678
+
+**Before (current code):**
+```typescript
+emitMessageSubmitTelemetry({ queued: false, hasAgentMentions: true });
+addMessage("user", trimmedValue);
+
+// Create a streaming assistant message immediately so the parallel
+// agents tree view renders right away instead of waiting for the
+// next user message.
+const assistantMsg = createMessage("assistant", "", true);
+streamingMessageIdRef.current = assistantMsg.id;
+isAgentOnlyStreamRef.current = true;
+isStreamingRef.current = true;
+streamingStartRef.current = Date.now();
+resetThinkingSourceTracking();
+setIsStreaming(true);
+resetTodoItemsForNewStream();
+setMessagesWindowed((prev) => [...prev, assistantMsg]);
+
+for (const mention of atMentions) {
+  void executeCommand(mention.agentName, mention.args, "mention");
+}
+return;
+```
+
+**After (proposed):**
+```typescript
+emitMessageSubmitTelemetry({ queued: false, hasAgentMentions: true });
+addMessage("user", trimmedValue);
+
+// Set streaming state so the UI shows a loading indicator while
+// sendSilentMessage creates the actual assistant message.
+isStreamingRef.current = true;
+streamingStartRef.current = Date.now();
+setIsStreaming(true);
+
+for (const mention of atMentions) {
+  void executeCommand(mention.agentName, mention.args, "mention");
+}
+return;
+```
+
+**What changed:**
+- **Removed:** `createMessage("assistant", "", true)` — no more placeholder Message A
+- **Removed:** `streamingMessageIdRef.current = assistantMsg.id` — ref will be set by `sendSilentMessage`
+- **Removed:** `setMessagesWindowed((prev) => [...prev, assistantMsg])` — no more adding placeholder to state
+- **Removed:** `resetThinkingSourceTracking()` and `resetTodoItemsForNewStream()` — `sendSilentMessage` already handles these
+- **Removed:** `isAgentOnlyStreamRef.current = true` — `sendSilentMessage` handles all streaming state setup (per Q1 resolution)
+- **Kept:** `isStreamingRef = true` and `setIsStreaming(true)` — immediate streaming state for UI feedback
+- **Kept:** `streamingStartRef` — timing for telemetry
+
+**Rationale:** The placeholder message's stated purpose (per the comment at line 5660) was to make "the parallel agents tree view renders right away." However, this creates the dual-message race condition. Instead, setting `isStreamingRef = true` provides immediate UI feedback (loading spinner), and `sendSilentMessage` creates the single assistant message where the agent tree will render. The `isAgentOnlyStreamRef` flag is not set here — `sendSilentMessage` manages it internally.
+
+### 5.2 Fix 2: Adjust `sendSilentMessage` Placeholder Cleanup Logic
+
+**File:** `src/ui/chat.tsx` — `sendSilentMessage` function, lines ~3474-3489
+
+**Before (current code):**
+```typescript
+// Finalize any previous streaming message before starting a new one.
+// This prevents duplicate "Generating..." spinners when sendSilentMessage
+// is called from an @mention handler that already created a placeholder.
+const prevStreamingId = streamingMessageIdRef.current;
+if (prevStreamingId) {
+  setMessagesWindowed((prev: ChatMessage[]) =>
+    prev.map((msg: ChatMessage) =>
+      msg.id === prevStreamingId && msg.streaming
+        ? { ...finalizeStreamingReasoningInMessage(msg), streaming: false }
+        : msg
+    ).filter((msg: ChatMessage) =>
+      !(msg.id === prevStreamingId && !msg.content.trim())
+    )
+  );
+}
+```
+
+**After (proposed):**
+```typescript
+// Finalize any previous streaming message before starting a new one.
+const prevStreamingId = streamingMessageIdRef.current;
+if (prevStreamingId) {
+  setMessagesWindowed((prev: ChatMessage[]) =>
+    prev.map((msg: ChatMessage) =>
+      msg.id === prevStreamingId && msg.streaming
+        ? { ...finalizeStreamingReasoningInMessage(msg), streaming: false }
+        : msg
+    ).filter((msg: ChatMessage) =>
+      !(msg.id === prevStreamingId && !msg.content.trim())
+    )
+  );
+}
+```
+
+**What changed:** The cleanup logic is **preserved as-is** for defensive safety. Even though Fix 1 eliminates the placeholder, this code still handles edge cases where a previous streaming message exists (e.g., rapid re-invocation). The comment is updated to remove the @mention-specific reference since that path no longer creates placeholders.
+
+> **Note:** The comment update is minor. The key insight is that this cleanup path becomes a **no-op** for the `@` command flow since `streamingMessageIdRef.current` will be `null`/`undefined` when no placeholder was created. It remains active for other `sendSilentMessage` callers.
+
+### 5.3 Fix 3: Verify `dispatchQueuedMessage` Path
+
+**File:** `src/ui/chat.tsx` — `dispatchQueuedMessage` function, lines ~3177-3210
+
+This function processes queued `@` mentions that were enqueued during active streaming. It needs to be verified that it does **not** create a placeholder message before calling `executeCommand`.
+
+**Expected behavior:** `dispatchQueuedMessage` calls `executeCommand` for each queued mention, which in turn calls `sendSilentMessage`. Since `sendSilentMessage` creates the assistant message, no placeholder is needed in `dispatchQueuedMessage` either.
+
+**Action:** Verify and confirm this path does not create a placeholder. If it does, apply the same removal as Fix 1.
+
+### 5.4 State Flow After Fix
+
+```
+T0: User submits "@worker do X"
+T1: User message added, streaming state set (NO assistant message created)
+T2: executeCommand fires → sendSilentMessage called
+T3: sendSilentMessage creates Message B (single assistant message)
+T4: sendSilentMessage calls onSendMessage → SDK
+T5: SDK emits tool.start → eager agent created
+T6: parallelAgents useEffect fires, targets Message B
+T7: React renders — single message, single tree ✅
+T8: SDK emits subagent.start → merge completes
+T9: Next render — clean, no duplicates ✅
+```
+
+**Eliminated race condition:** No more transient window where two messages coexist. `streamingMessageIdRef` is set once (by `sendSilentMessage`) and never changes.
+
+## 6. Alternatives Considered
+
+| Option | Pros | Cons | Reason for Rejection |
+| --- | --- | --- | --- |
+| **Option A: Synchronize placeholder cleanup** — Make `sendSilentMessage`'s cleanup of Message A synchronous using `flushSync` | Eliminates race without removing placeholder | `flushSync` is a React escape hatch with performance implications; doesn't fix the architectural divergence | Forces React to synchronously apply state — anti-pattern that can cause layout thrashing and breaks concurrent mode |
+| **Option B: Reuse placeholder message** — Instead of creating Message B, have `sendSilentMessage` reuse Message A by updating its ID/state | Single message throughout | Complex coordination; requires `sendSilentMessage` to detect and reuse existing placeholder; changes `sendSilentMessage` semantics for all callers | Increases coupling between `@` handler and `sendSilentMessage`; makes `sendSilentMessage` aware of caller context |
+| **Option C: Eliminate placeholder (Selected)** | Single message; matches natural language pathway; minimal change; follows Issue #205 precedent | Brief gap between user submit and agent tree rendering (until `sendSilentMessage` creates Message B) | **Selected:** Simplest fix; aligns architectures; streaming state provides loading feedback during the gap |
+| **Option D: Bypass `sendSilentMessage` entirely** — Have `@` handler call `spawnSubagent` bridge directly | Direct SDK invocation; no intermediate message | Requires significant refactoring of agent command dispatch; different execution model than SDK expects | Too invasive; changes how agents are spawned at a fundamental level |
+
+## 7. Cross-Cutting Concerns
+
+### 7.1 SDK Parity
+
+The fix applies uniformly across all three SDKs:
+- **Claude/Copilot:** `sendSilentMessage(instruction)` creates the single message → SDK receives instruction → LLM calls Task tool → agent lifecycle events fire
+- **OpenCode:** `sendSilentMessage(task, { agent: name })` creates the single message → SDK receives structured dispatch → agent lifecycle events fire
+
+No SDK-specific branching needed. The `sendSilentMessage` function already handles SDK differences internally.
+
+> **Ref:** [research/docs/2026-02-23-258-background-agents-sdk-event-pipeline.md](../research/docs/2026-02-23-258-background-agents-sdk-event-pipeline.md) — Documents per-SDK event emission patterns.
+
+### 7.2 Backward Compatibility
+
+- The `isAgentOnlyStreamRef` flag is no longer set in the `@` handler (per Q1 resolution). `sendSilentMessage` manages it internally, setting it based on context. This simplifies the flag lifecycle and eliminates the `true` → `false` toggle race.
+- `sendSilentMessage` creates the sole assistant message — no placeholder to clean up
+- Deduplication layers remain untouched (defense-in-depth preserved)
+- Queued message processing (`dispatchQueuedMessage`) follows the same `executeCommand` → `sendSilentMessage` path
+
+### 7.3 Performance
+
+- **Improvement:** One fewer React state update per `@` command invocation (no `setMessagesWindowed` for placeholder)
+- **Improvement:** No more transient re-renders caused by placeholder cleanup
+- **Negligible delay:** The gap between user submit and `sendSilentMessage`'s message creation is minimal (synchronous `executeCommand` dispatch)
+
+### 7.4 Observability
+
+- Existing telemetry (`emitMessageSubmitTelemetry`) is preserved and unaffected
+- The `streamingStartRef` timestamp is still set in the `@` handler for accurate timing
+
+### 7.5 UI Feedback Gap
+
+When the placeholder is removed, there is a brief period between the user pressing Enter and `sendSilentMessage` creating the assistant message. During this gap:
+- `isStreamingRef.current = true` and `setIsStreaming(true)` are set immediately
+- The UI should show a streaming/loading indicator based on these flags
+- The actual agent tree appears when `sendSilentMessage` creates the message and SDK events fire
+
+This gap is comparable to the natural language pathway (user sends message → SDK streams response → tree appears).
+
+## 8. Migration, Rollout, and Testing
+
+### 8.1 Deployment Strategy
+
+- [ ] **Phase 1:** Implement Fix 1 (remove placeholder) and Fix 2 (preserve cleanup logic). Verify Fix 3 (dispatchQueuedMessage path).
+- [ ] **Phase 2:** Manual E2E testing across all three SDKs (OpenCode, Claude, Copilot) with `@` command invocations.
+- [ ] **Phase 3:** Verify queued `@` mentions work (submit `@worker` during active streaming).
+- [ ] **Phase 4:** Verify natural language pathway remains unaffected.
+
+### 8.2 Test Plan
+
+**Manual Tests:**
+
+| Test Case | Steps | Expected Result |
+| --- | --- | --- |
+| Basic `@` command | Type `@worker do X`, press Enter | Single agent tree renders; no duplicate flash |
+| Multiple `@` mentions | Type `@worker do X @debugger do Y` | Each agent tree renders once; no duplicates |
+| Queued `@` mention | While streaming, type `@worker do X` | Message queued; after stream ends, single tree renders |
+| Natural language agent | Type "use the worker agent to do X" | Single agent tree (unchanged behavior) |
+| Rapid `@` commands | Submit `@worker` twice quickly | Each invocation produces single tree |
+| `@` with background agent | Type `@worker do X` with background mode | Background agent footer renders correctly |
+
+**Automated Tests:**
+- Unit test for `parseAtMentions` — unchanged, existing tests should pass
+- Integration test verifying `sendSilentMessage` creates exactly one assistant message
+- Verify `setMessagesWindowed` is called once per `@` command (not twice)
+
+### 8.3 Regression Checks
+
+- [ ] Verify streaming state is set immediately on `@` submit (loading indicator visible)
+- [ ] Verify `isAgentOnlyStreamRef` flag lifecycle is correct (`true` → `false` transition via `sendSilentMessage`)
+- [ ] Verify finalization guards in `parts/guards.ts` still function correctly
+- [ ] Verify deduplication layers still catch edge cases (they should have nothing to deduplicate for `@` commands, but should still work for other sources)
+
+## 9. Open Questions / Unresolved Issues (Resolved)
+
+- [x] **Q1: Should we remove the `isAgentOnlyStreamRef = true` line from the `@` handler?**
+  **Decision:** Yes — remove it. Let `sendSilentMessage` handle all streaming state setup. The `@` handler should only set `isStreamingRef` and `setIsStreaming` for immediate UI feedback. The `isAgentOnlyStreamRef` flag defaults to `false` and `sendSilentMessage` manages it internally. This simplifies the `@` handler and eliminates the flag toggle race.
+
+- [x] **Q2: Is the brief UI feedback gap (between Enter and `sendSilentMessage`'s message creation) acceptable?**
+  **Decision:** Yes — the gap is acceptable. It matches the natural language pathway's behavior where users see a spinner until the SDK stream begins. No additional loading indicator is needed.
+
+- [x] **Q3: Should we add a test specifically for the "no duplicate messages" invariant?**
+  **Decision:** Yes — add a unit test that mocks `setMessagesWindowed` and asserts it's called with exactly one assistant message per `@` command invocation. This prevents regression.
+
+- [x] **Q4: Is the `dispatchQueuedMessage` path also affected?**
+  **Decision:** Yes — investigate and fix in this same spec. The `dispatchQueuedMessage` path uses the same fire-and-forget `executeCommand` pattern. If it creates a placeholder assistant message, apply the same removal.
+
+## 10. Research References
+
+| Document | Relevance |
+| --- | --- |
+| [research/docs/2026-02-25-at-command-duplicate-subagent-tree.md](../research/docs/2026-02-25-at-command-duplicate-subagent-tree.md) | **Primary research** — Root cause analysis, 5-factor race condition, comparison table, deduplication layer analysis |
+| [research/tickets/2026-02-15-205-skill-loading-indicator-duplicate.md](../research/tickets/2026-02-15-205-skill-loading-indicator-duplicate.md) | **Precedent** — Identical dual-path rendering issue fixed by eliminating one path |
+| [research/docs/2026-02-23-258-background-agents-sdk-event-pipeline.md](../research/docs/2026-02-23-258-background-agents-sdk-event-pipeline.md) | 6-stage pipeline architecture; per-SDK correlation analysis |
+| [research/docs/2026-02-16-sub-agent-tree-inline-state-lifecycle-research.md](../research/docs/2026-02-16-sub-agent-tree-inline-state-lifecycle-research.md) | Premature lifecycle finalization at 4+ code sites |
+| [research/docs/2026-02-15-sub-agent-tree-status-lifecycle-sdk-parity.md](../research/docs/2026-02-15-sub-agent-tree-status-lifecycle-sdk-parity.md) | Two-path agent creation (eager + subagent.start) and SDK parity |
+| [research/docs/2026-02-15-subagent-premature-completion-investigation.md](../research/docs/2026-02-15-subagent-premature-completion-investigation.md) | Root cause of `tool.complete` unconditionally finalizing status |
+| [research/docs/2026-02-06-at-mention-dropdown-research.md](../research/docs/2026-02-06-at-mention-dropdown-research.md) | @ mention dropdown implementation context |
+| [specs/skill-loading-indicator-duplicate-fix.md](./skill-loading-indicator-duplicate-fix.md) | Precedent spec — "eliminate one rendering path" pattern |
+| [specs/background-agents-sdk-pipeline-fix.md](./background-agents-sdk-pipeline-fix.md) | SDK pipeline fix patterns (session trust, multi-field check) |
+| [specs/sub-agent-tree-inline-state-lifecycle-fix.md](./sub-agent-tree-inline-state-lifecycle-fix.md) | Flag-gated state transition pattern for agent lifecycle |
+| [specs/chat-system-parts-based-rendering.md](./chat-system-parts-based-rendering.md) | Parts-based rendering architecture (future direction) |
diff --git a/specs/copilot-sdk-ui-alignment-parity-hardening.md b/specs/copilot-sdk-ui-alignment-parity-hardening.md
new file mode 100644
index 0000000000..c37c22a393
--- /dev/null
+++ b/specs/copilot-sdk-ui-alignment-parity-hardening.md
@@ -0,0 +1,446 @@
+# Atomic CLI Cross-SDK UI Alignment Hardening - Technical Design Document / RFC
+
+| Document Metadata      | Details            |
+| ---------------------- | ------------------ |
+| Author(s)              | lavaman131         |
+| Status                 | Draft (WIP)        |
+| Team / Owner           | Atomic CLI UI Team |
+| Created / Last Updated | 2026-03-02         |
+
+## 1. Executive Summary
+
+Atomic CLI already has a strong shared UI architecture across Copilot, OpenCode, and Claude, but parity defects remain in sub-agent lifecycle rendering, `@agent` output propagation, task-label stability, and OpenCode compaction behavior. These defects are currently masked by permissive handling in several paths and lead to inconsistent UX, hidden root causes, and stuck turns.
+
+This RFC removes those permissive paths and defines strict cross-SDK contracts: invalid lifecycle sequences become explicit contract violations, `@agent` results are always returned to the main agent for final user-facing output, descriptive task labels are authoritative, and compaction failures terminate the turn with explicit diagnostics instead of silent continuation.
+
+The impact is deterministic behavior, lower debugging ambiguity, and reduced long-term tech debt by fixing error sources directly and prohibiting hidden compensating logic.
+
+Research basis: `research/docs/2026-03-02-copilot-sdk-ui-alignment.md`
+
+### 1.1 Normative Language
+
+- `MUST`, `MUST NOT`, `REQUIRED`, and `SHALL` are strict requirements in this RFC.
+- `SHOULD` is intentionally avoided in this document to prevent ambiguous implementation.
+
+## 2. Context and Motivation
+
+### 2.1 Current State
+
+- Shared chat rendering is already provider-agnostic after adapter normalization (`parts` registry, transcript, model selector, task/status surfaces).
+- Provider differences MUST remain limited to adapter ingress and command transport semantics.
+- The architecture already standardizes around canonical `stream.*` bus contracts.
+
+Research references:
+
+- `research/docs/2026-03-02-copilot-sdk-ui-alignment.md:20`
+- `research/docs/2026-03-02-copilot-sdk-ui-alignment.md:42`
+- `research/docs/2026-03-02-copilot-sdk-ui-alignment.md:88`
+
+### 2.2 The Problem
+
+- **Lifecycle correctness gap:** OpenCode/Claude produce prolonged "Initializing" or missing rows when lifecycle sequencing is inconsistent.
+- **Task-label integrity gap:** repeated starts and generic normalization overwrite meaningful task labels with low-value names.
+- **`@agent` contract gap:** sub-agent output detaches from the main assistant response path.
+- **Compaction control gap:** OpenCode compaction stalls active turns when summarize paths block lifecycle completion.
+
+Research references:
+
+- `research/docs/2026-03-02-copilot-sdk-ui-alignment.md:130`
+- `research/docs/2026-03-02-copilot-sdk-ui-alignment.md:158`
+- `research/docs/2026-03-02-copilot-sdk-ui-alignment.md:183`
+- `research/docs/2026-03-02-copilot-sdk-ui-alignment.md:228`
+- `research/docs/2026-03-02-copilot-sdk-ui-alignment.md:236`
+
+## 3. Goals and Non-Goals
+
+### 3.1 Functional Goals
+
+- [ ] The system MUST enforce strict `stream.agent.start -> stream.agent.update* -> stream.agent.complete` ordering across all providers.
+- [ ] The system MUST eliminate synthesized or compensating UI/runtime paths that hide lifecycle contract defects.
+- [ ] The system MUST forward `@agent` results to the main-agent continuation path in all SDKs.
+- [ ] The system MUST treat the first descriptive task label as authoritative and MUST reject generic overwrite regressions.
+- [ ] OpenCode compaction MUST be bounded; timeout/error MUST terminate the turn with explicit diagnostics.
+- [ ] The test suite MUST enforce parity regression coverage for strict contracts and failure semantics.
+
+### 3.2 Non-Goals (Out of Scope)
+
+- [ ] We MUST NOT redesign the shared event bus architecture.
+- [ ] We MUST NOT create provider-specific UI forks to paper over correctness issues.
+- [ ] We MUST NOT ship lenient mode, compatibility fallbacks, or silent compensating behavior.
+- [ ] We MUST NOT change visual theme/language except where REQUIRED for explicit error states.
+- [ ] We MUST NOT implement unrelated workflow/runtime features in this RFC.
+
+## 4. Proposed Solution (High-Level Design)
+
+### 4.1 System Architecture Diagram
+
+```mermaid
+flowchart LR
+    classDef sdk fill:#e8f1ff,stroke:#3668a8,color:#1f3554
+    classDef adapter fill:#e9f7ef,stroke:#2d7a46,color:#1e4b2c
+    classDef shared fill:#fff4e5,stroke:#a86a17,color:#5c3a0d
+    classDef hardening fill:#fdecef,stroke:#a63f58,color:#5e2230
+
+    subgraph Providers[Provider SDK Clients]
+        COP[Copilot SDK]:::sdk
+        OPE[OpenCode SDK]:::sdk
+        CLA[Claude Agent SDK]:::sdk
+    end
+
+    subgraph Adapters[Provider Adapters]
+        CAD[Copilot Adapter]:::adapter
+        OAD[OpenCode Adapter]:::adapter
+        CLD[Claude Adapter]:::adapter
+    end
+
+    subgraph Shared[Shared Runtime and UI]
+        BUS[EventBus + Stream Consumer]:::shared
+        PIPE[Stream Parts Pipeline]:::shared
+        CHAT[Chat State + Transcript + ParallelAgentsTree]:::shared
+    end
+
+    subgraph StrictLayer[Strict Contract Layer]
+        LIFECYCLE[Lifecycle Contract Enforcer]:::hardening
+        LABELS[Task Label Authority Rules]:::hardening
+        PROMOTION[Main-Agent Continuation Contract]:::hardening
+        COMPACT[Compaction Control and Terminal Errors]:::hardening
+    end
+
+    COP --> CAD --> BUS
+    OPE --> OAD --> BUS
+    CLA --> CLD --> BUS
+
+    BUS --> LIFECYCLE --> PIPE --> CHAT
+    BUS --> LABELS --> CHAT
+    BUS --> PROMOTION --> CHAT
+    BUS --> COMPACT --> CHAT
+```
+
+### 4.2 Architectural Pattern
+
+- The implementation MUST keep the shared adapter-normalization architecture.
+- The implementation MUST replace permissive handling with strict contract enforcement and explicit error propagation.
+- The implementation MUST fix root causes in SDK clients/adapters instead of compensating in UI state.
+- The implementation MUST enforce a zero-compensation rule: invalid producer behavior fails loudly and is fixed at source.
+
+Research references:
+
+- `research/docs/2026-03-02-copilot-sdk-ui-alignment.md:42`
+- `research/docs/2026-03-02-copilot-sdk-ui-alignment.md:89`
+- `research/docs/2026-03-02-copilot-sdk-ui-alignment.md:236`
+
+### 4.3 Key Components
+
+| Component | Responsibility | Technology Stack | Justification |
+| --- | --- | --- | --- |
+| Lifecycle Contract Enforcer | Reject invalid agent lifecycle sequences and emit explicit contract violations | TypeScript, event consumer + chat state | Removes hidden error states and preserves invariant integrity |
+| Task Label Authority Policy | Preserve first descriptive task text as canonical; only explicit user-command text MUST supersede | TypeScript normalization + reducer rules | Prevents silent regressions to generic labels |
+| Main-Agent Continuation Contract | Always route completed sub-agent results back into main-agent continuation | TypeScript chat finalization + command dispatch | Matches Task-tool behavior and unifies provider UX |
+| Compaction Control | Bound compaction operations and terminate turn on timeout/error with explicit diagnostic event | TypeScript SDK client + stream lifecycle | Stops indefinite stalls and exposes root failure directly |
+| Parity Contract Test Matrix | Validate strict lifecycle, output propagation, label authority, and compaction termination semantics | Bun tests | Prevents reintroduction of compensating behavior |
+
+## 5. Detailed Design
+
+### 5.1 API Interfaces
+
+**Canonical lifecycle events (contract strengthened):**
+
+```ts
+type StreamAgentStart = {
+  type: "stream.agent.start";
+  data: {
+    agentId: string;
+    parentAgentId?: string;
+    task?: string;
+    toolCallId: string;
+    provider: "copilot" | "opencode" | "claude";
+  };
+};
+
+type StreamAgentUpdate = {
+  type: "stream.agent.update";
+  data: {
+    agentId: string;
+    toolUses?: number;
+    currentTool?: string;
+    status?: "running" | "pending";
+  };
+};
+
+type StreamAgentComplete = {
+  type: "stream.agent.complete";
+  data: {
+    agentId: string;
+    status: "completed" | "error" | "interrupted";
+    result?: string;
+  };
+};
+```
+
+**New strict policy contracts:**
+
+```ts
+type AgentResultPropagationMode = "main-agent-continuation";
+
+interface AgentResultPropagationPolicy {
+  mode: AgentResultPropagationMode;
+  apply(args: {
+    isAgentInvocation: boolean;
+    hasToolCalls: boolean;
+    parallelAgents: Array<{ id: string; status: string; result?: string }>;
+    messageContent: string;
+  }): {
+    continuationInput: string;
+  };
+}
+
+interface AgentLifecycleContractPolicy {
+  onMissingStart: "contract-violation-error";
+  onOutOfOrderEvent: "contract-violation-error";
+}
+
+type StreamAgentContractViolation = {
+  type: "stream.agent.contract_violation";
+  data: {
+    provider: "copilot" | "opencode" | "claude";
+    sessionId: string;
+    agentId?: string;
+    code:
+      | "MISSING_START"
+      | "OUT_OF_ORDER_EVENT"
+      | "MISSING_TOOL_CALL_ID"
+      | "INVALID_TERMINAL_TRANSITION";
+    message: string;
+  };
+};
+
+interface CompactionFailurePolicy {
+  maxCompactionWaitMs: number;
+  onTimeout: "terminate-turn-with-error";
+}
+```
+
+Research references:
+
+- `research/docs/2026-03-02-copilot-sdk-ui-alignment.md:44`
+- `research/docs/2026-03-02-copilot-sdk-ui-alignment.md:134`
+- `research/docs/2026-03-02-copilot-sdk-ui-alignment.md:186`
+- `research/docs/2026-03-02-copilot-sdk-ui-alignment.md:236`
+
+### 5.2 Data Model / Schema
+
+No external DB migration is REQUIRED.
+
+| State Field | Type | Constraints | Description |
+| --- | --- | --- | --- |
+| `parallelAgents[].id` | `string` | Required | Stable row identity |
+| `parallelAgents[].task` | `string` | Optional | Canonical descriptive task label |
+| `parallelAgents[].toolUses` | `number` | `>= 0` | Execution progress |
+| `parallelAgents[].currentTool` | `string` | Optional | Active tool indicator |
+| `parallelAgents[].result` | `string` | Optional | Final result payload |
+| `agentLifecycleLedger` | `Map<string, {started:boolean; completed:boolean; seq:number}>` | In-memory | Strict sequencing ledger |
+| `toolCallToAgentMap` | `Map<string,string>` | In-memory | Deterministic completion attribution |
+| `compactionControl` | `{state:string; startedAt:number}` | In-memory | Compaction operation state and timeout control |
+
+**Task label authority rules:**
+
+1. First descriptive non-generic label is canonical.
+2. Generic labels (`sub-agent task`, `subagent task`, provider-type placeholders) cannot replace canonical labels.
+3. Explicit user-command task text MUST replace inferred labels; inferred labels MUST NOT replace canonical descriptive labels.
+
+Research references:
+
+- `research/docs/2026-03-02-copilot-sdk-ui-alignment.md:159`
+- `research/docs/2026-03-02-copilot-sdk-ui-alignment.md:161`
+- `research/docs/2026-03-02-copilot-sdk-ui-alignment.md:162`
+
+### 5.3 Algorithms and State Management
+
+#### 5.3.1 Lifecycle Contract Enforcement
+
+```text
+On stream.agent.start:
+  register agentId in lifecycle ledger with started=true
+
+On stream.agent.update or stream.agent.complete:
+  if agentId not started:
+    emit stream.agent.contract_violation
+    mark turn as terminal error
+    stop processing this turn
+  else:
+    apply mutation
+
+On stream.agent.complete:
+  set completed=true in ledger
+```
+
+No synthesized rows are permitted. Missing starts are producer defects and MUST surface immediately as contract errors.
+
+Research references:
+
+- `research/docs/2026-03-02-copilot-sdk-ui-alignment.md:208`
+- `research/docs/2026-03-02-copilot-sdk-ui-alignment.md:210`
+
+#### 5.3.2 `@agent` Main-Agent Continuation Contract
+
+```text
+At completion of an @agent turn:
+  collect completed sub-agent results in deterministic order
+  build continuation input payload
+  send payload to main agent continuation path
+  main agent produces final detailed user-facing response
+```
+
+This requirement is mandatory across all SDKs and eliminates display-only behavior.
+
+Research references:
+
+- `research/docs/2026-03-02-copilot-sdk-ui-alignment.md:184`
+- `research/docs/2026-03-02-copilot-sdk-ui-alignment.md:187`
+- `research/docs/2026-03-02-copilot-sdk-ui-alignment.md:189`
+
+#### 5.3.3 Compaction Control State Machine
+
+State machine:
+
+- `STREAMING` -> `COMPACTING` when compaction starts.
+- `COMPACTING` -> `STREAMING` on successful summarize completion.
+- `COMPACTING` -> `TERMINAL_ERROR` on timeout/error.
+- `TERMINAL_ERROR` -> `ENDED` after explicit diagnostic emission and turn termination.
+
+Failure contract:
+
+- Compaction is bounded by timeout.
+- On timeout/error, the turn ends with explicit error (`Compaction failed, please start a new chat.`).
+- No retry, no hidden continuation, no silent handling, no automatic downgrade to warning.
+
+Research references:
+
+- `research/docs/2026-03-02-copilot-sdk-ui-alignment.md:229`
+- `research/docs/2026-03-02-copilot-sdk-ui-alignment.md:231`
+- `research/docs/2026-03-02-copilot-sdk-ui-alignment.md:233`
+
+### 5.4 Invariant Matrix (Hard Requirements)
+
+| Invariant ID | Invariant | Enforcement Point | Violation Outcome |
+| --- | --- | --- | --- |
+| `INV-AGENT-001` | Every `stream.agent.update` and `stream.agent.complete` MUST have a prior `stream.agent.start` for the same `agentId`. | Stream consumer lifecycle ledger | Emit `stream.agent.contract_violation` (`MISSING_START`), terminate turn |
+| `INV-AGENT-002` | Every `stream.agent.start` MUST include `toolCallId`. | Provider adapter normalization | Emit `stream.agent.contract_violation` (`MISSING_TOOL_CALL_ID`), terminate turn |
+| `INV-AGENT-003` | Terminal agent states MUST be monotonic (`completed/error/interrupted` cannot transition back to running). | Chat reducer transition guard | Emit `stream.agent.contract_violation` (`INVALID_TERMINAL_TRANSITION`), terminate turn |
+| `INV-OUTPUT-001` | `@agent` turns MUST produce main-agent continuation input from completed sub-agent results. | Stream completion handler | Emit contract violation and terminate turn if continuation input is missing |
+| `INV-COMPACT-001` | Compaction operation MUST complete before `maxCompactionWaitMs`. | SDK compaction controller | Emit terminal error with explicit message and end turn |
+
+Prohibited behavior set:
+
+- UI/runtime synthesis of missing lifecycle events is prohibited.
+- Silent event drops are prohibited.
+- Automatic retry loops for compaction timeout are prohibited.
+- Warning-only handling for contract violations is prohibited.
+
+## 6. Alternatives Considered
+
+| Option | Pros | Cons | Reason for Rejection |
+| --- | --- | --- | --- |
+| Option A: Provider-by-provider UI patches | Fast local fixes | Behavior drifts and defects stay hidden | Rejected; does not remove root causes |
+| Option B: Lifecycle synthesis and retries | Masks transient issues | Hides true contract defects and institutionalizes tech debt | Rejected by mandatory design rule (`MUST NOT hide producer defects`) |
+| Option C: Strict contract enforcement (Selected) | Deterministic behavior, explicit failures, easier debugging | Requires adapter/client fixes where defects exist | Selected to remove debt and preserve integrity |
+| Option D: Full rewrite | Potentially cleaner future architecture | High scope and risk | Rejected as unnecessary for current objectives |
+
+## 7. Cross-Cutting Concerns
+
+### 7.1 Security and Privacy
+
+- No new authentication surfaces are introduced.
+- Continuation payloads MUST obey existing redaction/safety constraints.
+- Contract-violation telemetry MUST avoid leaking sensitive tool payloads.
+
+Research references:
+
+- `research/docs/2026-03-02-copilot-sdk-ui-alignment.md:47`
+- `research/docs/2026-03-02-copilot-sdk-ui-alignment.md:193`
+
+### 7.2 Observability Strategy
+
+- Add strictness metrics:
+  - `agent_lifecycle_contract_violation_total`
+  - `agent_event_out_of_order_total`
+  - `agent_result_main_continuation_total`
+  - `compaction_timeout_terminated_total`
+  - `turn_terminated_due_to_contract_error_total`
+- Add structured diagnostics with provider/session/agent IDs for root-cause analysis.
+- Every contract violation MUST emit structured diagnostics; violations MUST NEVER be downgraded to warnings.
+- Keep existing user-facing status surfaces for operational transparency.
+
+Research references:
+
+- `research/docs/2026-03-02-copilot-sdk-ui-alignment.md:52`
+- `research/docs/2026-03-02-copilot-sdk-ui-alignment.md:210`
+
+### 7.3 Scalability and Capacity Planning
+
+- Strict contract enforcement reduces hidden inconsistent state accumulation.
+- Compaction timeout termination prevents indefinite resource locking on stuck turns.
+- Added parity tests increase CI cost modestly but reduce production regressions.
+
+Research references:
+
+- `research/docs/2026-03-02-copilot-sdk-ui-alignment.md:233`
+- `research/docs/2026-03-02-copilot-sdk-ui-alignment.md:234`
+
+## 8. Migration, Rollout, and Testing
+
+### 8.1 Deployment Strategy
+
+- [ ] Phase 1: Implement adapter/client root-cause fixes so valid lifecycle ordering is guaranteed at source.
+- [ ] Phase 2: Enable strict lifecycle contract enforcement and main-agent continuation contract for all providers.
+- [ ] Phase 3: Enable bounded compaction control and terminal-error semantics; delete permissive legacy paths.
+
+### 8.2 Data Migration Plan
+
+- No persisted data migration required.
+- Runtime additions: `agentLifecycleLedger`, `toolCallToAgentMap`, `compactionControl`.
+- This is an intentional behavioral tightening; compatibility fallbacks are prohibited and MUST NOT be reintroduced.
+
+### 8.3 Test Plan
+
+- **Unit Tests:**
+  - lifecycle updates/completions without prior start produce `contract_violation` terminal errors
+  - first descriptive task label remains authoritative under repeated starts
+  - `@agent` turns always generate main-agent continuation input
+  - compaction timeout always terminates turn and emits explicit error
+
+- **Integration Tests:**
+  - provider matrix for valid lifecycle ordering and hard failure on invalid sequences
+  - `@agent` prefix/autocomplete/natural-language paths all converge to main-agent continuation
+  - OpenCode compaction timeout path emits deterministic terminal error and ends turn
+
+- **End-to-End Tests:**
+  - cross-provider delegated tasks show parity in lifecycle, labeling, and final user-facing responses
+  - injected out-of-order lifecycle events are surfaced as explicit failures (not hidden)
+  - compaction failure path shows clear message and requires new chat session
+
+Research references:
+
+- `research/docs/2026-03-02-copilot-sdk-ui-alignment.md:172`
+- `research/docs/2026-03-02-copilot-sdk-ui-alignment.md:196`
+- `research/docs/2026-03-02-copilot-sdk-ui-alignment.md:234`
+
+### 8.4 Definition of Done (Release Gate)
+
+The RFC is not implementation-complete until all gates pass:
+
+- All invariants in Section 5.4 are enforced in runtime code paths.
+- All invariant failures produce `stream.agent.contract_violation` diagnostics with provider/session context.
+- No synthesized lifecycle rows remain in code or tests.
+- `@agent` turns route through main-agent continuation in Copilot, OpenCode, and Claude integration tests.
+- Compaction timeout path terminates turn deterministically and emits explicit user-facing error text.
+- Existing tests that encoded permissive behavior are removed or rewritten to strict behavior.
+
+## 9. Open Questions / Unresolved Issues
+
+No unresolved questions remain for this draft.
+
+- [x] **`@agent` output contract:** results are sent to main-agent continuation so the main agent returns final detailed output.
+- [x] **Lifecycle handling:** no synthesized rows; missing/out-of-order lifecycle events are contract errors.
+- [x] **Task label authority:** first descriptive label is canonical; generic replacements are rejected.
+- [x] **Compaction timeout:** terminate turn with explicit error; no retry or compensating behavior.
diff --git a/specs/opencode-auto-compaction.md b/specs/opencode-auto-compaction.md
new file mode 100644
index 0000000000..0301ab27d2
--- /dev/null
+++ b/specs/opencode-auto-compaction.md
@@ -0,0 +1,532 @@
+# OpenCode SDK Auto-Compaction Technical Design Document
+
+| Document Metadata      | Details                              |
+| ---------------------- | ------------------------------------ |
+| Author(s)              | lavaman131                           |
+| Status                 | Draft (WIP)                          |
+| Team / Owner           | Atomic CLI                           |
+| Created / Last Updated | 2026-03-01                           |
+
+## 1. Executive Summary
+
+The workflow-sdk's OpenCode integration lacks automatic context overflow detection and recovery. When a `ContextOverflowError` occurs during streaming, it is treated as a generic fatal error with no compaction recovery path. The Copilot SDK has full auto-compaction via `infiniteSessions` thresholds, and the Claude SDK has tool-name-based detection — but the OpenCode SDK only emits a `phase: "complete"` event after manual compaction, never a `phase: "start"`, and has zero overflow recovery logic.
+
+This spec proposes implementing auto-compaction for the OpenCode SDK integration by: (1) adding `ContextOverflowError` detection and automatic `summarize()` recovery during streaming, (2) emitting synthetic `phase: "start"` events before compaction begins, (3) adding proactive token-threshold monitoring in direct chat mode (outside workflow graphs), and (4) wiring up the existing TUI auto-compaction indicator infrastructure that already handles spinner verbs, message clearing, and history buffer management.
+
+The upstream OpenCode codebase already has a comprehensive auto-compaction system (`SessionCompaction.isOverflow()` → `SessionCompaction.create()` → `SessionCompaction.process()`), and the workflow-sdk's event bus and TUI layers already have full compaction UI support — the gap is entirely in the OpenCode client layer's error handling and event emission.
+
+## 2. Context and Motivation
+
+### 2.1 Current State
+
+The workflow-sdk supports three coding agent backends: OpenCode, Claude Code, and Copilot CLI. Each has a different compaction story:
+
+**Copilot SDK (Reference — Full Auto-Compaction):**
+- Sessions are created with `infiniteSessions` config specifying `backgroundCompactionThreshold: 0.45` and `bufferExhaustionThreshold: 0.6` ([Ref: research §1, `copilot.ts:1116-1120`](../research/docs/2026-03-01-opencode-auto-compaction.md))
+- SDK natively detects threshold breaches and emits both `session.compaction_start` and `session.compaction_complete` events
+- Three-layer event translation: SDK events → unified `AgentEvent` → bus events → TUI indicator
+
+**Claude SDK (Partial — Tool-Name Detection):**
+- No SDK-native auto-compaction thresholds
+- Compaction detected via tool-name pattern matching (`isAutoCompactionToolName()`) in the TUI layer
+- Workflow graph uses `"recreate"` strategy (session recreation) rather than `"summarize"`
+
+**OpenCode SDK (Gap — No Auto-Compaction):**
+- `summarize()` method exists and calls `sdkClient.session.summarize()` ([Ref: research §3, `opencode.ts:2107-2145`](../research/docs/2026-03-01-opencode-auto-compaction.md))
+- SSE `session.compacted` event mapped to `session.compaction` with `phase: "complete"` only ([Ref: research §3, `opencode.ts:987-996`](../research/docs/2026-03-01-opencode-auto-compaction.md))
+- No `phase: "start"` emission anywhere in the OpenCode client
+- No `ContextOverflowError` differentiation — all stream errors are generic fatal errors
+- `contextMonitorNode` calls `summarize()` at 45% threshold, but **only in workflow mode** ([Ref: research §3, `nodes.ts:1263-1266`](../research/docs/2026-03-01-opencode-auto-compaction.md))
+
+**Architecture Diagram — Current Event Flow:**
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        SDK Layer                                │
+│                                                                 │
+│  Copilot SDK                Claude SDK              OpenCode SDK│
+│  ├─ compaction_start ✅      ├─ tool detection ✅    ├─ SSE only │
+│  └─ compaction_complete ✅   └─ (no SDK events)     │  ❌ start  │
+│       │                           │                  │  ✅ complete│
+│       ▼                           ▼                  ▼           │
+│  ┌─────────┐               ┌─────────┐         ┌──────────┐    │
+│  │copilot.ts│               │claude.ts │         │opencode.ts│   │
+│  │ maps both│               │ no event │         │ maps only │   │
+│  │ start +  │               │ emission │         │ "complete"│   │
+│  │ complete │               │          │         │ hard-codes│   │
+│  └────┬─────┘               └──────────┘         │ success=  │   │
+│       │                                          │ true      │   │
+│       │                                          └─────┬─────┘   │
+└───────┼────────────────────────────────────────────────┼─────────┘
+        │                                                │
+        ▼                                                ▼
+┌──────────────────────────────────────────────────────────────────┐
+│                     Event Bus Layer                               │
+│  BusEventType: "stream.session.compaction"                       │
+│  Data: { phase: "start" | "complete", success?, error? }         │
+│  ⚠️ OpenCode only ever emits phase: "complete"                   │
+└──────────────────────────┬───────────────────────────────────────┘
+                           │
+                           ▼
+┌──────────────────────────────────────────────────────────────────┐
+│                        TUI Layer                                  │
+│  useBusSubscription("stream.session.compaction")                  │
+│  ├─ phase: "start"  → "Compacting" spinner  (never fires for OC) │
+│  └─ phase: "complete" → clear messages, fresh state               │
+│                                                                   │
+│  Tool-name detection (handleToolStart/handleToolComplete)         │
+│  └─ isAutoCompactionToolName() (never fires for OC tools)         │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+### 2.2 The Problem
+
+- **User Impact:** When an OpenCode session hits the context window limit during direct chat (non-workflow mode), the user sees a cryptic `ContextOverflowError` and the session becomes unusable. No recovery is attempted, no compaction spinner is shown, and the user must manually restart.
+- **Parity Gap:** Copilot sessions handle this transparently — the user sees a "Compacting…" spinner, messages are cleared, and the conversation continues seamlessly. OpenCode users get a fundamentally worse experience.
+- **Technical Debt:** The TUI already has full auto-compaction UI support (`applyAutoCompactionIndicator()`, spinner verb overrides, message clearing, history buffer management). The event bus already defines `stream.session.compaction`. The adapter already subscribes to `session.compaction` events. The only missing piece is the OpenCode client's failure to detect overflow and emit the right events. ([Ref: research §5, `chat.tsx:2314-2361, 3181-3196`](../research/docs/2026-03-01-opencode-auto-compaction.md))
+- **Workflow-Only Workaround:** The `contextMonitorNode` in the workflow graph layer calls `summarize()` for OpenCode at 45% threshold, but this only works when using workflow graphs — direct chat sessions have no compaction safety net. ([Ref: research §3, `nodes.ts:1263-1274`](../research/docs/2026-03-01-opencode-auto-compaction.md))
+
+## 3. Goals and Non-Goals
+
+### 3.1 Functional Goals
+
+- [ ] **G1:** Detect `ContextOverflowError` during OpenCode streaming and automatically trigger `summarize()` recovery instead of treating it as a fatal error
+- [ ] **G2:** Emit synthetic `session.compaction` events with `phase: "start"` before compaction begins and `phase: "complete"` after, so the existing TUI infrastructure displays the "Compacting…" spinner and clears messages on completion
+- [ ] **G3:** Add proactive token-threshold monitoring in the OpenCode client for direct chat mode, triggering auto-compaction before the context window is exhausted (matching the 45% threshold used in workflow mode)
+- [ ] **G4:** Wire up the TUI auto-compaction indicator for OpenCode sessions so users see the same "Compacting…" spinner, message clearing, and compaction summary as Copilot sessions
+- [ ] **G5:** Ensure post-compaction token counts are refreshed and the session continues seamlessly with the compacted context
+- [ ] **G6:** Wire `session.truncation` event emission in the OpenCode client by detecting token count changes during compaction, so the existing adapter subscription begins receiving truncation data
+
+### 3.2 Non-Goals (Out of Scope)
+
+- [ ] We will NOT implement tool output pruning (`SessionCompaction.prune()`) from the upstream OpenCode — the upstream server handles this natively
+- [ ] We will NOT modify the Copilot or Claude compaction flows — they are working as designed
+- [ ] We will NOT build custom compaction prompts — the upstream OpenCode SDK's `session.summarize()` API handles the LLM summarization internally
+- [ ] We will NOT add `infiniteSessions`-style configuration to the OpenCode client — the upstream SDK does not support this API surface
+
+## 4. Proposed Solution (High-Level Design)
+
+### 4.1 System Architecture Diagram
+
+```mermaid
+%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#f8f9fa','primaryTextColor':'#2c3e50','primaryBorderColor':'#4a5568','lineColor':'#4a90e2','secondaryColor':'#ffffff','tertiaryColor':'#e9ecef'}}}%%
+
+flowchart TB
+    classDef existing fill:#48bb78,stroke:#38a169,stroke-width:2px,color:#fff,font-weight:600
+    classDef newCode fill:#e53e3e,stroke:#c53030,stroke-width:2.5px,color:#fff,font-weight:600
+    classDef bridge fill:#ed8936,stroke:#dd6b20,stroke-width:2px,color:#fff,font-weight:600
+
+    subgraph OpenCodeClient["OpenCode Client (opencode.ts)"]
+        direction TB
+        StreamHandler["Stream Error Handler<br><i>handleStreamError()</i>"]:::newCode
+        OverflowDetect["ContextOverflowError<br>Detection<br><i>isContextOverflowError()</i>"]:::newCode
+        ThresholdMonitor["Token Threshold<br>Monitor<br><i>checkContextThreshold()</i>"]:::newCode
+        SummarizeMethod["summarize()<br><i>existing method</i>"]:::existing
+        EmitStart["Emit session.compaction<br>phase: 'start'"]:::newCode
+        EmitComplete["Emit session.compaction<br>phase: 'complete'"]:::existing
+    end
+
+    subgraph EventBus["Event Bus Layer"]
+        BusCompaction["stream.session.compaction<br><i>existing bus event</i>"]:::existing
+    end
+
+    subgraph Adapter["OpenCode Adapter"]
+        AdapterHandler["createSessionCompactionHandler<br><i>existing handler</i>"]:::existing
+    end
+
+    subgraph TUI["TUI Layer (chat.tsx)"]
+        BusSub["useBusSubscription<br><i>existing subscription</i>"]:::existing
+        Indicator["applyAutoCompactionIndicator<br><i>existing callback</i>"]:::existing
+        Spinner["LoadingIndicator<br>'Compacting…' spinner"]:::existing
+        MessageClear["Message clearing +<br>history buffer"]:::existing
+    end
+
+    StreamHandler -->|"overflow detected"| OverflowDetect
+    OverflowDetect -->|"true"| EmitStart
+    ThresholdMonitor -->|"threshold exceeded"| EmitStart
+    EmitStart -->|"phase: start"| SummarizeMethod
+    SummarizeMethod --> EmitComplete
+    EmitComplete --> AdapterHandler
+    EmitStart --> AdapterHandler
+    AdapterHandler --> BusCompaction
+    BusCompaction --> BusSub
+    BusSub --> Indicator
+    Indicator --> Spinner
+    Indicator --> MessageClear
+
+    style OpenCodeClient fill:#fff,stroke:#4a5568,stroke-width:2px,stroke-dasharray:8 4
+    style EventBus fill:#fff,stroke:#4a5568,stroke-width:2px
+    style Adapter fill:#fff,stroke:#4a5568,stroke-width:2px
+    style TUI fill:#fff,stroke:#4a5568,stroke-width:2px
+```
+
+**Legend:** 🟢 Green = existing code (no changes needed) | 🔴 Red = new code | 🟠 Orange = bridge/glue code
+
+### 4.2 Architectural Pattern
+
+We are adopting a **detect-emit-react** pattern where:
+1. **Detect:** The OpenCode client detects context overflow (reactive: error parsing) and threshold breaches (proactive: token monitoring)
+2. **Emit:** The client emits unified `session.compaction` events with both `phase: "start"` and `phase: "complete"`, matching the Copilot SDK's dual-phase lifecycle
+3. **React:** The existing event bus → adapter → TUI pipeline handles visual feedback and session state management without any changes
+
+This maximizes reuse of existing infrastructure — the only new code is in the OpenCode client layer.
+
+### 4.3 Key Components
+
+| Component | Responsibility | Location | Status |
+| --- | --- | --- | --- |
+| `isContextOverflowError()` | Parse stream errors for context overflow patterns | `src/sdk/clients/opencode.ts` | **New** |
+| Overflow recovery in stream handler | Catch overflow errors, trigger compaction, retry | `src/sdk/clients/opencode.ts` | **New** |
+| Synthetic `phase: "start"` emission | Emit start event before `summarize()` call | `src/sdk/clients/opencode.ts` | **New** |
+| Token threshold monitor | Proactive check after each assistant message | `src/sdk/clients/opencode.ts` | **New** |
+| `summarize()` | Call upstream SDK compaction API | `src/sdk/clients/opencode.ts` | **Existing** |
+| `session.compaction` → bus event | Adapter subscription and bus publishing | `src/events/adapters/opencode-adapter.ts` | **Existing** |
+| `stream.session.compaction` bus event | Event schema and Zod validation | `src/events/bus-events.ts` | **Existing** |
+| `applyAutoCompactionIndicator()` | TUI spinner, message clearing, history buffer | `src/ui/chat.tsx` | **Existing** |
+| `AutoCompactionIndicatorState` | State machine for compaction UI lifecycle | `src/ui/utils/auto-compaction-lifecycle.ts` | **Existing** |
+| `session.truncation` emission | Emit truncation data from pre/post token comparison | `src/sdk/clients/opencode.ts` | **New** |
+
+## 5. Detailed Design
+
+### 5.1 Context Overflow Error Detection
+
+**File:** `src/sdk/clients/opencode.ts`
+
+Add a helper function to detect `ContextOverflowError` from stream error messages, modeled after the upstream OpenCode's `ProviderError.isOverflow()` which matches 14+ provider error patterns ([Ref: research §4, `error.ts:8-41`](../research/docs/2026-03-01-opencode-auto-compaction.md)).
+
+```typescript
+/**
+ * Detects context overflow errors from OpenCode stream error messages.
+ * Modeled after upstream OpenCode's ProviderError.isOverflow() patterns.
+ */
+function isContextOverflowError(error: Error | string): boolean {
+  const message = typeof error === "string" ? error : error.message;
+  const lowerMessage = message.toLowerCase();
+
+  const overflowPatterns = [
+    "context_length_exceeded",
+    "contextoverflowerror",
+    "context window",
+    "maximum context length",
+    "input is too long",
+    "exceeds the model's maximum context",
+    "token limit",
+    "too many tokens",
+    "request too large",
+    "prompt is too long",
+  ];
+
+  return overflowPatterns.some((pattern) => lowerMessage.includes(pattern));
+}
+```
+
+### 5.2 Stream Error Recovery with Auto-Compaction
+
+**File:** `src/sdk/clients/opencode.ts`
+
+Modify the stream error handling path (currently at lines ~1995-2001) to differentiate `ContextOverflowError` from other fatal errors:
+
+```typescript
+// In the streaming error handler (SSE session.error or stream catch block)
+if (isContextOverflowError(error)) {
+  // 1. Emit phase: "start" before compaction begins
+  this.emitEvent("session.compaction", sessionID, { phase: "start" });
+
+  try {
+    // 2. Call the existing summarize() method
+    await session.summarize();
+
+    // 3. Emit phase: "complete" with success
+    // Note: The SSE session.compacted event will also fire,
+    // but we emit eagerly here for faster TUI feedback
+    this.emitEvent("session.compaction", sessionID, {
+      phase: "complete",
+      success: true,
+    });
+
+    // 4. Resume the conversation by re-sending or signaling continuation
+    // Emit idle with compaction reason so the session can continue
+    this.emitEvent("session.idle", sessionID, {
+      reason: "context_compacted",
+    });
+  } catch (compactionError) {
+    // 5. Emit phase: "complete" with failure
+    this.emitEvent("session.compaction", sessionID, {
+      phase: "complete",
+      success: false,
+      error:
+        compactionError instanceof Error
+          ? compactionError.message
+          : String(compactionError),
+    });
+
+    // 6. Fall through to original error handling — compaction failed
+    throw error;
+  }
+
+  // 7. Auto-continue with synthetic "Continue" message
+  // (matches upstream OpenCode behavior)
+  await session.send("Continue");
+
+  return; // Successfully compacted — don't propagate original overflow error
+}
+
+// Original error handling for non-overflow errors continues below
+```
+
+### 5.3 Proactive Token Threshold Monitoring
+
+**File:** `src/sdk/clients/opencode.ts`
+
+Add proactive threshold checking after each assistant message update. This mirrors the workflow graph's `contextMonitorNode` behavior (45% threshold) but works in direct chat mode.
+
+```typescript
+// Constants — match workflow graph thresholds
+const AUTO_COMPACTION_THRESHOLD = 0.45; // 45% of context window
+const MAX_AUTO_COMPACTION_RETRIES = 0;
+
+/**
+ * Check context usage after token count updates and trigger
+ * auto-compaction if threshold is exceeded.
+ * Called after processing assistant message token updates.
+ */
+async function checkAndTriggerAutoCompaction(
+  sessionState: SessionState,
+  session: Session,
+  sessionID: string,
+  emitEvent: EventEmitter,
+): Promise<boolean> {
+  try {
+    const usage = await session.getContextUsage();
+
+    if (usage.usagePercentage < AUTO_COMPACTION_THRESHOLD * 100) {
+      return false; // Below threshold
+    }
+
+    // Emit start event
+    emitEvent("session.compaction", sessionID, { phase: "start" });
+
+    // Trigger compaction
+    await session.summarize();
+
+    // Emit complete event (SSE session.compacted will also fire)
+    emitEvent("session.compaction", sessionID, {
+      phase: "complete",
+      success: true,
+    });
+
+    return true;
+  } catch (error) {
+    // Emit failure
+    emitEvent("session.compaction", sessionID, {
+      phase: "complete",
+      success: false,
+      error: error instanceof Error ? error.message : String(error),
+    });
+    return false;
+  }
+}
+```
+
+**Integration point:** Call `checkAndTriggerAutoCompaction()` in the SSE event handler after processing `message.updated` events that update token counts (around lines ~1007-1016 in the current code).
+
+### 5.4 Synthetic `phase: "start"` Emission in `summarize()`
+
+**File:** `src/sdk/clients/opencode.ts`
+
+Modify the existing `summarize()` method to emit `phase: "start"` before calling the upstream SDK:
+
+```typescript
+summarize: async (): Promise<void> => {
+  if (state.isClosed) throw new Error("Session is closed");
+
+  // NEW: Emit phase: "start" before compaction begins
+  client.emitEvent("session.compaction", sessionID, { phase: "start" });
+
+  try {
+    await client.sdkClient.session.summarize({
+      sessionID,
+      directory: client.directory,
+    });
+
+    // Existing: Post-compaction token refresh
+    try {
+      const messages = await client.sdkClient.session.messages({ sessionID });
+      // ... existing token refresh logic ...
+    } catch {
+      // Silent catch — existing behavior
+    }
+
+    // Existing: Emit idle with compaction reason
+    client.emitEvent("session.idle", sessionID, {
+      reason: "context_compacted",
+    });
+  } catch (error) {
+    // NEW: Emit phase: "complete" with failure on error
+    client.emitEvent("session.compaction", sessionID, {
+      phase: "complete",
+      success: false,
+      error: error instanceof Error ? error.message : String(error),
+    });
+    throw error;
+  }
+},
+```
+
+**Note:** The `phase: "complete"` with `success: true` is already handled by the SSE `session.compacted` event mapping at lines 987-996. The synthetic `phase: "start"` fills the gap so the TUI shows the "Compacting…" spinner immediately when compaction begins. ([Ref: research §3, gap #1](../research/docs/2026-03-01-opencode-auto-compaction.md))
+
+### 5.6 `session.truncation` Event Wiring
+
+**File:** `src/sdk/clients/opencode.ts`
+
+The OpenCode adapter already subscribes to `session.truncation` events (`opencode-adapter.ts:286-291`), but the client never emits them. Add truncation event emission in the `summarize()` method by comparing pre/post-compaction token counts:
+
+```typescript
+// In summarize(), after the post-compaction token refresh:
+const preCompactionTokens = sessionState.inputTokens + sessionState.outputTokens;
+
+// ... existing token refresh from session.messages() ...
+
+const postCompactionTokens = newInputTokens + newOutputTokens;
+const tokensRemoved = preCompactionTokens - postCompactionTokens;
+
+if (tokensRemoved > 0) {
+  client.emitEvent("session.truncation", sessionID, {
+    tokenLimit: sessionState.contextWindow ?? 0,
+    tokensRemoved,
+    messagesRemoved: 0, // Not precisely trackable from token counts alone
+  });
+}
+```
+
+This enables the existing adapter subscription to fire, and the `stream.session.truncation` bus event will be published with truncation details. The TUI can optionally display this information (e.g., "X tokens removed during compaction").
+
+### 5.7 Deduplication of `phase: "complete"` Events
+
+Since both the `summarize()` method's SSE handler and the auto-compaction recovery could emit `phase: "complete"`, the TUI's `applyAutoCompactionIndicator()` already handles this gracefully — transitioning from `"running"` to `"completed"` is idempotent in the state machine (`auto-compaction-lifecycle.ts`). No deduplication logic is needed.
+
+However, to prevent double-emission from `summarize()` + SSE, the stream error recovery path (§5.2) should set a flag that prevents the SSE `session.compacted` handler from emitting a duplicate:
+
+```typescript
+// In the session state
+let pendingCompactionComplete = false;
+
+// In the recovery path (§5.2), after calling summarize():
+pendingCompactionComplete = true;
+
+// In handleSdkEvent, case "session.compacted":
+if (!pendingCompactionComplete) {
+  this.emitEvent("session.compaction", sessionID, {
+    phase: "complete",
+    success: true,
+  });
+} else {
+  pendingCompactionComplete = false;
+}
+```
+
+### 5.8 Data Flow — Complete Auto-Compaction Lifecycle
+
+```
+1. [Trigger] ContextOverflowError during streaming
+       OR token threshold exceeded (45%) after assistant message
+                │
+2. [Detect]    isContextOverflowError(error) returns true
+       OR      getContextUsage().usagePercentage >= 45
+                │
+3. [Emit]      emitEvent("session.compaction", sessionID, { phase: "start" })
+                │
+4. [Compact]   session.summarize()
+                │  ├── sdkClient.session.summarize({ sessionID, directory })
+                │  ├── Post-compaction: session.messages() → refresh token counts
+                │  └── emitEvent("session.idle", { reason: "context_compacted" })
+                │
+5. [SSE]       OpenCode server emits "session.compacted" SSE event
+                │
+6. [Map]       handleSdkEvent() → emitEvent("session.compaction", { phase: "complete", success: true })
+                │
+7. [Adapt]     opencode-adapter.ts: createSessionCompactionHandler()
+                │  → publishes BusEvent("stream.session.compaction", { phase, success })
+                │
+8. [Bus]       EventBus delivers "stream.session.compaction" to subscribers
+                │
+9. [TUI]       useBusSubscription("stream.session.compaction"):
+                │  ├── phase: "start"  → applyAutoCompactionIndicator({ status: "running" })
+                │  │    └── Spinner verb → "Compacting", isAutoCompacting = true
+                │  └── phase: "complete" → applyAutoCompactionIndicator({ status: "completed" })
+                │       ├── Clear history buffer
+                │       ├── Append compaction summary
+                │       ├── Replace all messages with fresh streaming message
+                │       └── isAutoCompacting = false
+                │
+10. [Continue]  Client sends synthetic "Continue" message → session resumes with compacted context
+```
+
+## 6. Alternatives Considered
+
+| Option | Pros | Cons | Reason for Rejection |
+| --- | --- | --- | --- |
+| **A: Client-side overflow detection only (reactive)** | Simple — just catch `ContextOverflowError` and call `summarize()` | No prevention — user experiences a brief error/interruption before recovery; compaction only triggers after failure | Insufficient — proactive monitoring is also needed for smooth UX |
+| **B: Workflow graph only (current state for workflow mode)** | Already implemented via `contextMonitorNode` at 45% threshold | Only works in workflow mode; direct chat sessions have zero coverage | **Current gap** — this is the problem we're solving |
+| **C: SDK-native `infiniteSessions` config (Copilot pattern)** | Cleanest — delegate entirely to upstream SDK | OpenCode SDK does not expose `infiniteSessions` API; would require upstream SDK changes | Not feasible without upstream SDK changes |
+| **D: Client-side proactive + reactive (Selected)** | Full coverage: prevents overflow proactively, recovers from overflow reactively; reuses all existing TUI infrastructure | Adds complexity to OpenCode client; synthetic `phase: "start"` events are not from the SDK | **Selected:** Best UX with maximum infrastructure reuse; handles both prevention and recovery |
+
+## 7. Cross-Cutting Concerns
+
+### 7.1 Error Handling
+
+- **Compaction failure:** If `summarize()` fails during auto-compaction recovery, emit `phase: "complete"` with `success: false` and fall through to the original error handling. The TUI will show the error state for `AUTO_COMPACTION_RESULT_VISIBILITY_MS` (4 seconds) and revert the spinner.
+- **Token refresh failure:** Already handled — `summarize()` silently catches `session.messages()` errors (existing behavior at `opencode.ts:2137`).
+- **Re-entrancy guard:** Prevent concurrent compaction attempts by checking `isAutoCompacting` state or a session-level `isCompacting` flag before triggering.
+
+### 7.2 Observability
+
+- **Event emission:** All compaction lifecycle events flow through the existing event bus, which provides built-in logging and tracing via the adapter layer.
+- **Debug logging:** The existing `summarize()` method should add debug-level logging for auto-compaction triggers (threshold value, token counts, overflow error message).
+
+### 7.3 Edge Cases
+
+- **Rapid consecutive overflows:** If compaction doesn't reduce context enough and a second overflow occurs immediately, the error propagates as-is (`MAX_AUTO_COMPACTION_RETRIES = 0`). A session-level `hasAutoCompacted` flag prevents repeated compaction attempts within the same stream.
+- **User abort during compaction:** The existing `stopSharedStreamState()` in `chat.tsx:2400-2405` already clears orphaned `"running"` compaction indicators back to `"idle"`.
+- **Workflow mode interaction:** The proactive threshold monitor runs at the client level, applying to both direct chat and workflow modes. The existing `contextMonitorNode` in workflow mode should be updated to defer to the client-level monitor (e.g., by checking if auto-compaction already triggered) to avoid double-compaction.
+- **Duplicate SSE events:** The deduplication flag (§5.5) prevents the SSE `session.compacted` handler from emitting a second `phase: "complete"` when the recovery path already emitted one.
+
+## 8. Migration, Rollout, and Testing
+
+### 8.1 Deployment Strategy
+
+- [ ] **Phase 1:** Implement reactive overflow detection and recovery (§5.1, §5.2). This is the critical path — it turns fatal errors into recoverable compaction events.
+- [ ] **Phase 2:** Add synthetic `phase: "start"` emission to `summarize()` (§5.4). This enables the "Compacting…" spinner for manual `/compact` commands in addition to auto-recovery.
+- [ ] **Phase 3:** Implement proactive token threshold monitoring (§5.3). This prevents overflow errors from occurring in the first place.
+- [ ] **Phase 4:** Add deduplication guard (§5.7) and edge case handling (re-entrancy, auto-continue with synthetic "Continue" message).
+- [ ] **Phase 5:** Wire `session.truncation` event emission (§5.6) to provide truncation details during compaction.
+
+### 8.2 Test Plan
+
+- **Unit Tests:**
+  - `isContextOverflowError()` — test against all pattern strings (positive and negative cases)
+  - Deduplication flag behavior — verify SSE handler respects `pendingCompactionComplete`
+  - Token threshold calculation — verify `checkAndTriggerAutoCompaction()` triggers at correct percentage
+
+- **Integration Tests:**
+  - Simulate `ContextOverflowError` during streaming → verify `summarize()` is called and `session.compaction` events are emitted in correct order (`start` → `complete`)
+  - Verify TUI receives bus events and shows "Compacting…" spinner
+  - Verify messages are cleared and history buffer updated after successful compaction
+  - Verify failed compaction emits `success: false` and falls through to error display
+
+- **End-to-End Tests:**
+  - Run a long OpenCode conversation that exceeds context limits → verify auto-compaction triggers and conversation continues
+  - Verify `/compact` command shows "Compacting…" spinner (currently it does not show `phase: "start"`)
+  - Verify `Ctrl+O` history view shows compaction summary after auto-compaction
+
+## 9. Resolved Questions
+
+- [x] **Q1: Stream continuation after compaction** — **Decision: Auto-continue with synthetic "Continue" message**, matching upstream OpenCode behavior. After auto-compaction recovers from a `ContextOverflowError`, the client will automatically send a synthetic "Continue" user message to resume the conversation seamlessly. The user should not need to re-type their message or manually trigger continuation.
+
+- [x] **Q2: Threshold monitoring scope** — **Decision: Implement compaction once at the client level, applying to both direct chat and workflow modes.** The proactive token threshold monitor will run in the OpenCode client itself, providing coverage for both direct chat and workflow modes from a single implementation. This avoids duplicating compaction logic between the client and workflow graph layers. The existing `contextMonitorNode` in workflow mode may need to be adjusted to defer to the client-level monitor to prevent double-compaction.
+
+- [x] **Q3: Compaction retry limit** — **Decision: 0 retries — fail immediately if first compaction doesn't help.** If a `ContextOverflowError` occurs and auto-compaction is triggered but doesn't sufficiently reduce context, the error will propagate as-is on the next occurrence. This prevents infinite compaction loops and surfaces genuinely unrecoverable situations to the user. Set `MAX_AUTO_COMPACTION_RETRIES = 0`.
+
+- [x] **Q4: Tool output pruning** — **Decision: No client-side pruning — upstream server handles it via `session.summarize()`.** The upstream OpenCode's `prune()` mechanism operates server-side as part of the compaction pipeline. The workflow-sdk will rely entirely on the upstream SDK's `session.summarize()` API, which internally handles tool output pruning.
+
+- [x] **Q5: `session.truncation` wiring** — **Decision: Include in this spec.** The `session.truncation` event will be wired as part of this compaction work. The OpenCode client will emit `session.truncation` events when token counts indicate messages were truncated during compaction (detectable by comparing pre/post-compaction token counts from the `session.messages()` refresh). The existing adapter subscription at `opencode-adapter.ts:286-291` will begin receiving events, and the TUI can display truncation information.
diff --git a/specs/opencode-delegation-streaming-parity.md b/specs/opencode-delegation-streaming-parity.md
new file mode 100644
index 0000000000..1d9306d2f1
--- /dev/null
+++ b/specs/opencode-delegation-streaming-parity.md
@@ -0,0 +1,351 @@
+# Workflow-SDK OpenCode Task/Subtask Streaming Parity Technical Design Document / RFC
+
+| Document Metadata      | Details         |
+| ---------------------- | --------------- |
+| Author(s)              | lavaman131      |
+| Status                 | Draft (WIP)     |
+| Team / Owner           | lavaman131/atomic |
+| Created / Last Updated | 2026-03-01      |
+
+## 1. Executive Summary
+
+`workflow-sdk` already has a strong event-driven streaming pipeline, but child task output is still primarily reconciled in UI state instead of being represented as a canonical parent-loop contract. OpenCode treats `task`/subtask execution as a first-class runtime behavior (`task_id` + `<task_result>`), persists tool output into message parts, and continues generation based on explicit loop semantics; this gives it predictable behavior across long, nested tool/task chains. (Ref: `research/docs/2026-03-01-opencode-delegation-streaming-parity.md:20`, `/home/alilavaee/Documents/projects/opencode/packages/opencode/src/tool/task.ts:147`, `/home/alilavaee/Documents/projects/opencode/packages/opencode/src/session/prompt.ts:319`)
+
+This RFC proposes an OpenCode-aligned Task/Subtask Runtime Contract for `workflow-sdk` that introduces a canonical `task_id` identity, `task`-tool-compatible input/output contracts, standardized task-result envelope, finish-reason-aware session loop continuation, and complete stream event mapping into renderable parts.
+
+The impact is improved cross-provider parity (OpenCode/Claude/Copilot), fewer dropped task/workflow events, better determinism in continuation behavior, and cleaner boundaries between runtime semantics and UI rendering.
+
+## 2. Context and Motivation
+
+### 2.1 Current State
+
+- `workflow-sdk` streaming currently flows as adapters -> event bus -> batch dispatcher -> correlation service -> stream part reducer -> UI rendering. (Ref: `research/docs/2026-03-01-opencode-delegation-streaming-parity.md:40`, `src/events/consumers/wire-consumers.ts:7`)
+- Sub-agent execution is supported (including parallel/background orchestration), and adapter/client correlation maps child sessions in some provider paths. (Ref: `research/docs/2026-03-01-opencode-delegation-streaming-parity.md:42`, `src/sdk/clients/opencode.ts:484`, `src/ui/chat.tsx:4552`)
+- Parent reconciliation currently aggregates child task outputs into UI message content/parts in `chat.tsx`, which works visually but is not the same as OpenCode's canonical parent-loop tool-result ingestion contract. (Ref: `research/docs/2026-03-01-opencode-delegation-streaming-parity.md:43`, `src/ui/chat.tsx:3906`)
+- Event architecture includes broad typed events, but historical gap analysis documented emitted events that were not consumed or mapped to renderable parts, especially workflow/session lifecycle subsets. (Ref: `research/docs/2026-03-01-opencode-delegation-streaming-parity.md:70`, `research/docs/2026-02-28-workflow-gaps-architecture.md:343`)
+
+### 2.2 The Problem
+
+- **Parity gap in task/subtask contract:** No single provider-agnostic `task_id` equivalent exists across adapters, making resume/reconciliation behavior fragmented by provider-specific IDs. (Ref: `research/docs/2026-03-01-opencode-delegation-streaming-parity.md:51`)
+- **Parity gap in parent-loop semantics:** Continuation is mostly guard/status-driven in UI logic, not explicitly finish-reason (`tool-calls`) driven with canonical tool-result rehydration semantics. (Ref: `research/docs/2026-03-01-opencode-delegation-streaming-parity.md:64`, `src/ui/utils/stream-continuation.ts:9`)
+- **Event completeness gap:** Some emitted lifecycle/workflow events do not consistently map into part state, causing silent drops and inconsistent transcript fidelity. (Ref: `research/docs/2026-03-01-opencode-delegation-streaming-parity.md:68`, `research/docs/2026-02-28-workflow-gaps-architecture.md:320`)
+- **Architectural coupling risk:** Task/subtask semantics are currently split between adapters and UI merge code, making behavior harder to test deterministically at runtime-core boundaries.
+
+## 3. Goals and Non-Goals
+
+### 3.1 Functional Goals
+
+- [ ] Introduce a provider-agnostic canonical task/subtask identity (`task_id`) that maps provider IDs (`tool_use_id`, `toolCallId`, `subagentId`, child session IDs) into one runtime key.
+- [ ] Define a canonical task-result envelope contract equivalent to OpenCode's `task_id` + `<task_result>` semantics for parent-loop ingestion.
+- [ ] Mirror OpenCode `task` tool parameter/output contract (`description`, `prompt`, `subagent_type`, optional `task_id`, optional `command`, plus output metadata carrying child `sessionId` + model).
+- [ ] Add finish-reason-aware parent continuation that consumes persisted tool/task results, not only UI-level stream status guards.
+- [ ] Ensure all task/subtask-relevant stream events are either rendered or explicitly marked non-rendered by policy (no accidental drops).
+- [ ] Preserve existing UX behaviors (parallel/background agent tree, inline tool streaming) while moving canonical semantics into runtime-core.
+- [ ] Add comprehensive tests for identity mapping, envelope generation, continuation gates, and event completeness.
+
+### 3.2 Non-Goals (Out of Scope)
+
+- [ ] Will NOT re-architect transport to networked SSE for `workflow-sdk`; this RFC is runtime contract and reconciliation parity, not transport migration.
+- [ ] Will NOT replace existing event-bus/batch-dispatcher foundations.
+- [ ] Will NOT remove provider-specific IDs from adapters; they remain available as raw metadata and debugging context.
+- [ ] Will NOT redesign the TUI visual language in this RFC.
+- [ ] Will NOT change external CLI command surface for users in this phase.
+
+## 4. Proposed Solution (High-Level Design)
+
+### 4.1 System Architecture Diagram
+
+```mermaid
+flowchart LR
+    subgraph SDKs[Provider SDK Streams]
+      A1[OpenCode Adapter]
+      A2[Claude Adapter]
+      A3[Copilot Adapter]
+      A4[Workflow Adapter]
+    end
+
+    subgraph Runtime[workflow-sdk Runtime Core]
+      B1[Atomic Event Bus]
+      B2[Batch Dispatcher + Correlation]
+      B3[Task Identity Service]
+      B4[TaskResult Envelope Builder]
+      B5[SessionPrompt Loop Controller]
+      B6[Part Reducer and State Store]
+    end
+
+    subgraph UI[TUI]
+      C1[Chat Transcript Parts]
+      C2[Parallel Agent Tree]
+      C3[Workflow and Session Indicators]
+    end
+
+    A1 --> B1
+    A2 --> B1
+    A3 --> B1
+    A4 --> B1
+    B1 --> B2
+    B2 --> B3
+    B3 --> B4
+    B4 --> B5
+    B5 --> B6
+    B6 --> C1
+    B6 --> C2
+    B6 --> C3
+```
+
+### 4.2 Architectural Pattern
+
+- **Pattern:** Event-driven runtime with canonical task/subtask contract + deterministic turn-loop continuation.
+- **Core principle:** UI renders normalized runtime state; runtime state does not depend on ad-hoc UI merge logic for task/subtask semantics.
+
+### 4.3 Key Components
+
+| Component | Responsibility | Technology Stack | Justification |
+| --- | --- | --- | --- |
+| Task Identity Service | Resolve canonical `task_id` from provider-specific identifiers | TypeScript (`src/events/consumers` or new `src/runtime/task`) | Eliminates provider-fragmented correlation and enables resumable contract parity. |
+| TaskResult Envelope Builder | Produce normalized task result payload (`task_id` + `<task_result>` equivalent) and attach to message/tool history | TypeScript + existing part model | Matches OpenCode parent ingestion semantics while preserving local architecture. |
+| Session Loop Controller | Decide continuation based on finish reason + pending tool/task state | TypeScript runtime service invoked from chat/session orchestration | Replaces brittle UI-only continuation heuristics with explicit semantics and aligns to OpenCode `SessionPrompt` loop behavior. |
+| Event Coverage Policy + Mapper | Map all relevant stream/workflow/session events to part events or explicit non-rendered policy | `stream-pipeline-consumer.ts`, `bus-events.ts`, reducer types | Prevents silent event loss and improves transcript fidelity and debuggability. |
+
+### 4.4 OpenCode Compatibility Invariants
+
+The following behaviors are treated as source-of-truth parity targets and should remain semantically compatible with OpenCode:
+
+1. **Task tool contract parity**
+   - Input shape: `description`, `prompt`, `subagent_type`, optional `task_id`, optional `command`.
+   - Resume behavior: if `task_id` exists and resolves, continue existing child session; else create a new child session.
+   - Reference: `/home/alilavaee/Documents/projects/opencode/packages/opencode/src/tool/task.ts:14`.
+
+2. **Child session linkage parity**
+   - New task sessions are created with explicit parent linkage (`parentID = parent session`).
+   - Reference: `/home/alilavaee/Documents/projects/opencode/packages/opencode/src/tool/task.ts:73`.
+
+3. **Task output envelope parity**
+   - Canonical output format starts with `task_id: ...`, then wraps task output in `<task_result>...</task_result>`.
+   - Reference: `/home/alilavaee/Documents/projects/opencode/packages/opencode/src/tool/task.ts:147`.
+
+4. **Parent loop continuation parity**
+   - Parent loop continues when finish reason is `tool-calls` or `unknown`; exits for other terminal reasons once assistant follows the last user turn.
+   - Reference: `/home/alilavaee/Documents/projects/opencode/packages/opencode/src/session/prompt.ts:319`.
+
+5. **Message-part reconciliation parity**
+   - Runtime emits and consumes message-part lifecycle events (`message.part.updated`, `message.part.delta`) as first-class reconciliation signals.
+   - Tool parts are persisted then transformed into model messages via `toModelMessages`/`convertToModelMessages`, not ad-hoc ephemeral-only UI state.
+   - Reference: `/home/alilavaee/Documents/projects/opencode/packages/opencode/src/session/message-v2.ts:459`, `/home/alilavaee/Documents/projects/opencode/packages/opencode/src/session/message-v2.ts:491`.
+
+6. **Event stream envelope parity**
+   - Global bus envelopes include `{ directory, payload }` where payload keeps OpenCode shape `{ type, properties }`, and transport event updates are delivered as stream events.
+   - Reference: `/home/alilavaee/Documents/projects/opencode/packages/opencode/src/bus/index.ts:59`, `/home/alilavaee/Documents/projects/opencode/packages/opencode/src/server/routes/global.ts:71`.
+
+7. **Tool part state parity**
+   - Task/subtask lifecycle reconciles through OpenCode-compatible tool states (`pending`, `running`, `completed`, `error`) and preserves the no-dangling-tool-result invariant when reconstructing model input.
+   - Reference: `/home/alilavaee/Documents/projects/opencode/packages/opencode/src/session/message-v2.ts:617`.
+
+## 5. Detailed Design
+
+### 5.1 API Interfaces
+
+This RFC introduces internal runtime contracts (TypeScript interfaces), not new public HTTP APIs.
+
+```ts
+export interface TaskSessionIdentity {
+  task_id: string;                 // Canonical runtime key (OpenCode parity)
+  provider: "opencode" | "claude" | "copilot";
+  providerToolId?: string;         // tool_use_id, toolCallId, etc.
+  providerSubagentId?: string;
+  childSessionId?: string;
+  parentSessionId: string;
+}
+
+export interface TaskResultEnvelope {
+  task_id: string;                 // parity handle
+  tool_name: string;               // usually task/subagent equivalent
+  title: string;                   // OpenCode task result title/description
+  metadata: {
+    sessionId: string;
+    model?: { providerID: string; modelID: string };
+  };
+  status: "completed" | "error";
+  output_text: string;             // canonical task/subtask output text
+  output_structured?: Record<string, unknown>;
+  error?: string;
+}
+
+export interface TaskToolCompatibleInput {
+  description: string;
+  prompt: string;
+  subagent_type: string;
+  task_id?: string;
+  command?: string;
+}
+
+export interface SessionLoopContinuationSignal {
+  finishReason: "tool-calls" | "stop" | "length" | "error" | "unknown";
+  pendingToolCalls: number;
+  pendingTasks: number;
+  shouldContinue: boolean;
+}
+```
+
+Proposed canonical text envelope format in persisted history (OpenCode parity shape):
+
+```xml
+task_id: <task_id> (for resuming to continue this task if needed)
+
+<task_result>
+...normalized task output...
+</task_result>
+```
+
+This format is intended for runtime/model-history compatibility and traceability, while UI can still render richer structured parts.
+
+### 5.2 Data Model / Schema
+
+#### Runtime state additions
+
+```ts
+interface TaskRuntimeState {
+  byTaskId: Map<string, TaskSessionIdentity>;
+  byProviderId: Map<string, string>; // providerId -> task_id
+  pendingTasks: Set<string>;         // values are task_id
+  toolCallIdToTaskId: Map<string, string>;
+  completedEnvelopes: Map<string, TaskResultEnvelope>;
+}
+```
+
+#### Message part additions
+
+- Add `TaskResultPart` to `src/ui/parts/types.ts` to persist canonical task/subtask outcome in transcript state.
+- Add `WorkflowStepPart` for `workflow.step.start/complete` parity where not currently represented in `Part` union.
+- Register corresponding renderers in `src/ui/components/parts/registry.tsx` to avoid drop-on-render.
+
+#### Event payload normalization
+
+- Extend/normalize turn lifecycle payload to include finish-reason metadata needed by `Session Loop Controller`.
+- Preserve raw adapter payload in metadata for debugging; normalized fields are runtime contract of record.
+
+### 5.3 Algorithms and State Management
+
+- **Task/subtask lifecycle state machine:** `detected -> started -> child_streaming -> child_completed|child_error -> envelope_persisted -> parent_resumed -> settled`.
+- **Tool-part status state machine parity:** `pending -> running -> completed|error` for task tool results used in prompt reconstruction.
+- **Identity resolution algorithm:**
+  - Generate canonical `task_id` on first task invocation unless an explicit resumable `task_id` already exists.
+  - Prefer explicit provider tool ID as correlation alias, not canonical identity.
+  - Bind child session ID to canonical `task_id` on first confident correlation event.
+  - Backfill unresolved edges when later events provide missing IDs.
+  - Keep canonical `task_id` immutable after first assignment.
+- **Parent continuation algorithm:**
+  - On turn end event, compute `SessionLoopContinuationSignal` using finish reason + pending tool/task counters.
+  - Continue only when `finishReason` is `tool-calls` or `unknown`, or unresolved task contract requires continuation.
+  - Rebuild outbound prompt parts from persisted message parts that include task result envelopes.
+  - Keep behavior equivalent to OpenCode session loop stop condition when the latest assistant turn is terminal and follows the latest user turn.
+- **Event completeness policy:**
+  - For each bus event type, define one of: `rendered`, `state-only`, `telemetry-only`, `ignored-by-design`.
+  - Reject accidental default drops in mapping paths by test assertions.
+
+### 5.4 OpenCode Parity Acceptance Criteria
+
+The implementation is accepted only when all criteria below are met:
+
+- A task/subtask run produces canonical envelope text compatible with OpenCode shape (`task_id` line + `<task_result>` block).
+- A follow-up task invocation with `task_id` resumes the same child runtime session semantics.
+- Parent continuation gates respect finish-reason parity (`tool-calls`/`unknown` continue; terminal reasons stop).
+- Task input/output schema is compatible with OpenCode `task` tool contract, including metadata with child `sessionId`.
+- Persisted tool/task parts are used for model-history reconstruction (no UI-only source of truth).
+- Event mapping has no accidental default drops for the 12 documented unconsumed event types.
+- Cross-provider adapters (OpenCode/Claude/Copilot) all emit enough normalized metadata to satisfy the same runtime contract.
+
+### 5.5 Planned File-Level Changes
+
+| File / Area | Planned Change |
+| --- | --- |
+| `src/events/consumers/correlation-service.ts` | Add canonical task identity registry and provider-ID mapping utilities. |
+| `src/events/consumers/stream-pipeline-consumer.ts` | Add explicit mapping/policy handling for currently-unmapped task/workflow/session events. |
+| `src/events/bus-events.ts` | Extend turn/task payload contracts where required for continuation semantics. |
+| `src/ui/parts/types.ts` | Add task/workflow part types required for parity coverage. |
+| `src/ui/components/parts/registry.tsx` | Register new part renderers to prevent silent render omission. |
+| `src/ui/parts/stream-pipeline.ts` | Add reducer cases for new task/workflow part events. |
+| `src/ui/chat.tsx` | Move task result finalization from ad-hoc UI merge path toward runtime envelope + session loop controller integration. |
+| `src/ui/utils/stream-continuation.ts` | Integrate finish-reason-aware continuation gate. |
+| `src/sdk/clients/opencode.ts`, `src/sdk/clients/claude.ts`, `src/sdk/clients/copilot.ts` | Normalize task and turn metadata emission into runtime contract fields. |
+| model-history assembly path (new runtime module) | Ensure task tool parts remain the source-of-truth for model-message reconstruction (OpenCode `toModelMessages` parity). |
+
+## 6. Alternatives Considered
+
+| Option | Pros | Cons | Reason for Rejection / Selection |
+| --- | --- | --- | --- |
+| Option A: Keep UI-layer-only task reconciliation | Minimal code movement; preserves current behavior | No canonical parent-loop contract; parity gaps persist; hard to test deterministically | Rejected: does not satisfy core parity objective. |
+| Option B: OpenCode parity only for OpenCode adapter | Faster parity for one provider | Cross-provider fragmentation remains for Claude/Copilot | Rejected: contradicts `workflow-sdk` unified abstraction goals. |
+| Option C: Full runtime contract parity (Selected) | Deterministic continuation; provider-agnostic identity; better event completeness and testability | Higher up-front integration complexity | **Selected:** best alignment with research findings and long-term maintainability. |
+
+## 7. Cross-Cutting Concerns
+
+### 7.1 Security and Privacy
+
+- Treat task result envelopes as tool output artifacts: apply existing output truncation/sanitization policies before persistence.
+- Ensure sensitive data in task outputs is redacted consistently with current tool rendering conventions.
+- Preserve access control boundaries: no new privilege escalation path is introduced by canonical IDs.
+
+### 7.2 Observability Strategy
+
+- Add parity metrics/counters:
+  - `task_result_envelope_created_total`
+  - `task_id_backfill_total`
+  - `stream_event_unmapped_total`
+  - `session_loop_continue_decision_total{reason=...}`
+- Emit structured debug logs when fallback correlation is used (for postmortem debugging).
+- Add invariant checks in tests for "no accidental event drops" in covered event families.
+
+### 7.3 Scalability and Capacity Planning
+
+- Canonical identity maps are bounded by active session/workflow scope and cleaned on reset.
+- Envelope payloads should remain size-capped via existing truncation policy to avoid unbounded transcript growth.
+- Batch-dispatch architecture remains unchanged; additional mapping logic should stay O(n) per event batch.
+
+## 8. Migration, Rollout, and Testing
+
+### 8.1 Deployment Strategy
+
+- [ ] Phase 1: Introduce new runtime contracts (identity + envelope + continuation signal) behind a feature flag.
+- [ ] Phase 2: Wire adapters and reducers to emit/consume canonical contracts while preserving legacy fallback paths.
+- [ ] Phase 3: Enable canonical continuation path by default and retain fallback guardrails for rollback safety.
+- [ ] Phase 4: Remove obsolete UI-only reconciliation paths once parity tests pass consistently.
+
+### 8.2 Data Migration Plan
+
+- No durable DB schema migration required.
+- In-memory session state migration is lazy: legacy messages remain renderable; new turns persist canonical task result parts.
+- Optional transcript compatibility shim can synthesize envelopes for legacy records during replay if needed.
+
+### 8.3 Test Plan
+
+- **Unit Tests:**
+  - Identity resolution and canonical ID stability across mixed provider event orders.
+  - Envelope builder formatting and truncation behavior.
+  - Session loop continuation decisions for finish reasons and pending tool/task states.
+  - Event policy classification (rendered/state-only/ignored-by-design).
+- **Integration Tests:**
+  - End-to-end adapter -> bus -> consumer -> reducer flow across OpenCode/Claude/Copilot task dispatches.
+  - Workflow step/task events map into parts with no silent drops.
+  - Cross-session child-parent correlation and resume consistency.
+- **End-to-End Tests:**
+  - Multi-turn task-driven workflow where parent continuation relies on canonical envelope.
+  - Parallel/background sub-agents with final transcript parity checks.
+  - Regression tests for queueing/interruption behavior with `ask_question` and mixed tool lifecycles.
+
+## 9. Open Questions / Unresolved Issues
+
+- [x] **Task/subtask representation boundary (Resolved):** Child task outputs will become a canonical parent-loop contract (OpenCode-equivalent) used for continuation decisions, not only UI-layer artifacts.  
+  Decision: `Canonical Contract`.
+- [x] **Event rendering policy scope (Resolved):** Treat all 12 documented emitted-but-unconsumed events as actionable in this RFC and classify each as rendered/state-only/ignored-by-design explicitly.  
+  Decision: `Map All 12`.
+- [x] **Canonical identity key strategy (Resolved):** Use a synthesized runtime `task_id` as canonical, with deterministic bindings to provider IDs (`tool_use_id`, `toolCallId`, `subagentId`, child session IDs).  
+  Decision: `Synthesized Runtime ID`.
+
+## Research References
+
+- `research/docs/2026-03-01-opencode-delegation-streaming-parity.md`
+- `research/docs/2026-02-28-workflow-gaps-architecture.md`
+- `research/docs/2026-02-26-opencode-event-bus-patterns.md`
+- `research/docs/2026-02-23-sdk-subagent-api-research.md`
+- `research/workflow-gaps.md`
diff --git a/specs/opencode-tui-concurrency-bottleneck-fixes.md b/specs/opencode-tui-concurrency-bottleneck-fixes.md
new file mode 100644
index 0000000000..c46493d187
--- /dev/null
+++ b/specs/opencode-tui-concurrency-bottleneck-fixes.md
@@ -0,0 +1,625 @@
+# OpenCode TUI Concurrency Bottleneck Fixes — Technical Design Document
+
+| Document Metadata      | Details                                                                                |
+| ---------------------- | -------------------------------------------------------------------------------------- |
+| Author(s)              | lavaman131                                                                             |
+| Status                 | In Review (RFC)                                                                        |
+| Team / Owner           | Atomic CLI / Workflow-SDK                                                              |
+| Created / Last Updated | 2026-03-01                                                                             |
+
+## 1. Executive Summary
+
+The OpenCode TUI experiences response time degradation — from seconds to indefinite — when multiple agent SDKs execute in parallel during workflow orchestration (e.g., Ralph workflow). Root cause analysis (see [research: OpenCode TUI Concurrency Bottlenecks](../research/docs/2026-03-01-opencode-tui-concurrency-bottlenecks.md)) identified **six concrete bottleneck patterns** in the SSE event loop, event dispatch fanout, and the deep blocking chain from the workflow executor through to the SDK's `reader.read()`. This spec proposes targeted fixes for each pattern: propagating abort signals to the SSE reader, isolating per-session event streams, making handler fanout asynchronous, adding overall stream timeouts, and wiring abort signals through the full `executeWorkflow` → `streamGraph` → `spawnSubagent` chain. These changes will eliminate indefinite hangs, reduce cross-session event contention, and enable reliable parallel agent execution in workflows.
+
+## 2. Context and Motivation
+
+### 2.1 Current State
+
+The workflow-SDK's OpenCode integration uses a single `OpenCodeClient` instance per chat session ([ref: opencode.ts:505-506](../src/sdk/clients/opencode.ts)). This client subscribes to **all** SSE events from the OpenCode server via a single `event.subscribe()` call ([ref: opencode.ts:756](../src/sdk/clients/opencode.ts)), and dispatches them through a synchronous handler fanout in `emitEvent()` ([ref: opencode.ts:1571-1593](../src/sdk/clients/opencode.ts)).
+
+When the Ralph workflow executes, it spawns sub-agent sessions (planner, workers) that create **additional sessions on the same client** ([ref: research, §Workflow-SDK Agent SDK Integration](../research/docs/2026-03-01-opencode-tui-concurrency-bottlenecks.md)). All sessions share:
+- A single SSE event subscription and `for await` processing loop
+- A single `eventHandlers` map with synchronous fanout
+- A single `processEventStream()` watchdog timer
+
+**Architecture Diagram (Current State):**
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ OpenCode Server                                             │
+│   LLM streaming → Session.updatePart() → Bus.publish()      │
+│   → SSE endpoint (GET /event)                                │
+└────────────────────────┬────────────────────────────────────┘
+                         │ SSE (fetch → reader.read())
+┌────────────────────────▼────────────────────────────────────┐
+│ OpenCode SDK Client (workflow-sdk) — SINGLE INSTANCE         │
+│                                                              │
+│   createSseClient → reader.read() ──── BLOCKING POINT ────  │
+│   → processEventStream() for-await loop (SHARED)             │
+│   → handleSdkEvent() → emitEvent() → SYNC handler fanout    │
+│     ├─► Session A (planner) stream() generator               │
+│     ├─► Session B (worker 1) stream() generator              │
+│     ├─► Session C (worker 2) stream() generator              │
+│     └─► OpenCodeStreamAdapter → EventBus → UI                │
+│                                                              │
+│   ALL sessions share the same for-await loop ⚠️               │
+│   Watchdog abort NOT propagated to SSE reader ⚠️              │
+│   Handler fanout is SYNCHRONOUS ⚠️                            │
+└──────────────────────────────────────────────────────────────┘
+```
+
+**Limitations:**
+- **Single point of failure**: If `reader.read()` blocks on a dead TCP connection, *all* sessions stall ([Pattern A](../research/docs/2026-03-01-opencode-tui-concurrency-bottlenecks.md#bottleneck-pattern-a-sse-readerread-indefinite-block-dead-connection)).
+- **Cross-session contention**: High-volume background agent events starve foreground session event processing ([Pattern B](../research/docs/2026-03-01-opencode-tui-concurrency-bottlenecks.md#bottleneck-pattern-b-shared-sse-stream-across-all-sessions)).
+- **Synchronous bottleneck**: Slow event handlers block the entire SSE processing loop ([Pattern C](../research/docs/2026-03-01-opencode-tui-concurrency-bottlenecks.md#bottleneck-pattern-c-synchronous-handler-fanout-in-emitevent)).
+- **No overall timeout**: The `stream()` generator polls indefinitely when no terminal event arrives ([Pattern F](../research/docs/2026-03-01-opencode-tui-concurrency-bottlenecks.md#bottleneck-pattern-f-stream-generator-infinite-poll-without-overall-timeout)).
+
+### 2.2 The Problem
+
+- **User Impact**: Users running Ralph workflows experience the TUI freezing indefinitely during the planner or worker steps. The UI shows "Initializing..." with no progress, requiring a force-kill ([ref: research/ralph-workflow.md](../research/ralph-workflow.md)).
+- **Business Impact**: The workflow orchestration feature — a core differentiator of the Atomic CLI — is unreliable when using the OpenCode SDK backend, undermining user trust.
+- **Technical Debt**: The deep blocking chain from `executeWorkflow` → `streamGraph` → `spawnSubagent` → `consumeStream` → `stream()` → SSE has no abort signal propagation from the executor level ([ref: codebase analysis — executor.ts:455 calls streamGraph without abortSignal](../src/workflows/executor.ts)). Related issues documented in [research: sub-agent premature completion](../research/docs/2026-02-15-subagent-premature-completion-investigation.md) and [research: background agents SDK event pipeline (#258)](../research/docs/2026-02-23-258-background-agents-sdk-event-pipeline.md).
+
+## 3. Goals and Non-Goals
+
+### 3.1 Functional Goals
+
+- [ ] **G1**: Eliminate indefinite hangs caused by dead SSE connections by propagating abort signals from the watchdog to the SDK's SSE reader (`reader.cancel()`).
+- [ ] **G2**: Reduce cross-session event processing overhead by filtering events at the SSE loop level (before `handleSdkEvent()`) or by partitioning event subscriptions per session.
+- [ ] **G3**: Prevent slow event handlers from blocking the SSE processing loop by making `emitEvent()` dispatch asynchronous (microtask-based).
+- [ ] **G4**: Add an overall timeout to the `stream()` async generator to prevent indefinite polling when no terminal event arrives.
+- [ ] **G5**: Wire `AbortSignal` through the full `executeWorkflow()` → `streamGraph()` → `spawnSubagent()` chain so workflows can be cancelled from the executor level.
+- [ ] **G6**: Add an escape hatch to `OpenCodeStreamAdapter.startStreaming()`'s `completionPromise` so it respects external abort signals and overall timeouts.
+
+### 3.2 Non-Goals (Out of Scope)
+
+- [ ] **NG1**: We will NOT change the OpenCode server's SSE endpoint or heartbeat mechanism — fixes are client-side only.
+- [ ] **NG2**: We will NOT implement per-session SSE connections (multiple `event.subscribe()` calls to the server) — this would require server-side session-scoped SSE endpoints.
+- [ ] **NG3**: We will NOT refactor the `OpenCodeClient` into multiple client instances per workflow session — this would require significant architectural changes to session management.
+- [ ] **NG4**: We will NOT address TCP keepalive tuning at the OS level — this is an operational concern, not a code change.
+- [ ] **NG5**: We will NOT modify the Claude Agent SDK or Copilot SDK adapters — those use different streaming patterns (pull-based and bounded buffer respectively) that don't share these bottlenecks ([ref: research, §Workflow-SDK Agent SDK Integration](../research/docs/2026-03-01-opencode-tui-concurrency-bottlenecks.md)).
+
+## 4. Proposed Solution (High-Level Design)
+
+### 4.1 System Architecture Diagram (Target State)
+
+```mermaid
+%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#f8f9fa','primaryTextColor':'#2c3e50','primaryBorderColor':'#4a5568','lineColor':'#4a90e2','secondaryColor':'#ffffff','tertiaryColor':'#e9ecef'}}}%%
+
+flowchart TB
+    classDef fix fill:#48bb78,stroke:#38a169,stroke-width:2.5px,color:#ffffff,font-weight:600
+    classDef existing fill:#4a90e2,stroke:#357abd,stroke-width:2.5px,color:#ffffff,font-weight:600
+    classDef problem fill:#e53e3e,stroke:#c53030,stroke-width:2.5px,color:#ffffff,font-weight:600
+
+    Server["OpenCode Server<br>SSE Endpoint"]:::existing
+
+    subgraph SSELayer["SSE Event Layer (Fix A + B)"]
+        direction TB
+        SSEReader["SSE reader.read()<br>+ Composed AbortSignal<br>(watchdog ∪ global)"]:::fix
+        EventFilter["Early Session Filter<br>(pre-handleSdkEvent)"]:::fix
+        ForAwait["processEventStream()<br>for-await loop"]:::existing
+    end
+
+    subgraph DispatchLayer["Event Dispatch (Fix C)"]
+        direction TB
+        EmitEvent["emitEvent()<br>queueMicrotask fanout"]:::fix
+    end
+
+    subgraph StreamLayer["Stream Layer (Fix D + F)"]
+        direction TB
+        StreamGen["stream() generator<br>+ Overall Timeout"]:::fix
+        CompletionPromise["completionPromise<br>+ Abort + Timeout"]:::fix
+    end
+
+    subgraph ExecutorLayer["Workflow Executor (Fix E)"]
+        direction TB
+        ExecWorkflow["executeWorkflow()<br>+ AbortSignal"]:::fix
+        StreamGraph["streamGraph()<br>+ AbortSignal"]:::fix
+        SpawnSubagent["spawnSubagent()<br>+ AbortSignal chain"]:::existing
+    end
+
+    Server -->|SSE| SSEReader
+    SSEReader --> ForAwait
+    ForAwait --> EventFilter
+    EventFilter --> EmitEvent
+    EmitEvent --> StreamGen
+    EmitEvent --> CompletionPromise
+    StreamGen --> SpawnSubagent
+    CompletionPromise --> SpawnSubagent
+    ExecWorkflow --> StreamGraph
+    StreamGraph --> SpawnSubagent
+
+    style SSELayer fill:#ffffff,stroke:#cbd5e0,stroke-width:2px
+    style DispatchLayer fill:#ffffff,stroke:#cbd5e0,stroke-width:2px
+    style StreamLayer fill:#ffffff,stroke:#cbd5e0,stroke-width:2px
+    style ExecutorLayer fill:#ffffff,stroke:#cbd5e0,stroke-width:2px
+```
+
+### 4.2 Architectural Pattern
+
+We adopt a **Defense in Depth** pattern for timeout and cancellation: each layer in the blocking chain independently enforces timeouts and respects abort signals, so a failure at any single layer cannot cause an indefinite hang. This is combined with an **Event Filtering Pipeline** pattern where irrelevant events are discarded as early as possible in the processing chain.
+
+### 4.3 Key Components
+
+| Component | Fix Pattern | Responsibility | Files |
+|---|---|---|---|
+| SSE Abort Composer | Fix A | Compose watchdog + global abort signals into a single signal passed to the SDK's SSE reader | `opencode.ts` |
+| Session Event Filter | Fix B | Early-discard events for non-active sessions before `handleSdkEvent()` | `opencode.ts` |
+| Async Emit Dispatch | Fix C | Replace synchronous handler iteration with `queueMicrotask`-based dispatch | `opencode.ts` |
+| Completion Promise Guard | Fix D | Add abort + timeout to `completionPromise` in `startStreaming()` | `opencode-adapter.ts` |
+| Executor Abort Chain | Fix E | Wire `AbortSignal` from `executeWorkflow()` through `streamGraph()` to node execution | `executor.ts`, `compiled.ts` |
+| Stream Overall Timeout | Fix F | Add configurable overall timeout to `stream()` async generator | `opencode.ts` |
+
+## 5. Detailed Design
+
+### 5.1 Fix A: SSE `reader.read()` Abort Signal Propagation
+
+**Problem**: The watchdog `AbortController` at `opencode.ts:825` is local to `processEventStream()` and is NOT passed to the SDK's SSE client. When the watchdog fires, `reader.read()` in the SDK remains blocked on a dead connection ([ref: Pattern A](../research/docs/2026-03-01-opencode-tui-concurrency-bottlenecks.md#bottleneck-pattern-a-sse-readerread-indefinite-block-dead-connection)).
+
+**Solution**: Compose the watchdog abort signal with the global `eventSubscriptionController` signal and pass the composed signal to `event.subscribe()`.
+
+**Implementation:**
+
+In `subscribeToSdkEvents()` / `runEventLoop()`:
+
+```typescript
+// opencode.ts — runEventLoop()
+private async runEventLoop(): Promise<void> {
+  let isReconnect = false;
+  const SSE_INITIAL_RETRY_DELAY_MS = 250;
+  const SSE_MAX_RETRY_DELAY_MS = 30_000;
+  let retryAttempt = 0;
+
+  while (!this.eventSubscriptionController?.signal.aborted && this.isRunning) {
+    try {
+      // Create a per-iteration watchdog abort controller
+      const watchdogAbort = new AbortController();
+
+      // Compose watchdog + global abort into a single signal using AbortSignal.any()
+      const composedSignal = AbortSignal.any([
+        watchdogAbort.signal,
+        this.eventSubscriptionController!.signal,
+      ]);
+
+      // Pass the composed signal to the SDK's SSE client
+      const result = await this.sdkClient!.event.subscribe({
+        query: { directory: this.clientOptions.directory },
+        signal: composedSignal,  // <-- NEW: propagated to reader.read()
+      });
+
+      // Reset retry counter on successful connection
+      retryAttempt = 0;
+
+      await this.processEventStream(result.stream, watchdogAbort);
+
+      if (!this.eventSubscriptionController?.signal.aborted && this.isRunning) {
+        isReconnect = true;
+      }
+    } catch (error: unknown) {
+      if ((error as Error).name === "AbortError") break;
+      console.error("SSE event loop error:", error);
+
+      // Exponential backoff: min(initial * 2^attempt, max)
+      retryAttempt++;
+      const backoff = Math.min(
+        SSE_INITIAL_RETRY_DELAY_MS * 2 ** (retryAttempt - 1),
+        SSE_MAX_RETRY_DELAY_MS,
+      );
+      await new Promise((r) => setTimeout(r, backoff));
+    }
+  }
+}
+```
+
+In `processEventStream()`, pass the `watchdogAbort` as a parameter instead of creating it locally:
+
+```typescript
+private async processEventStream(
+  eventStream: AsyncIterable<SdkEvent>,
+  watchdogAbort: AbortController,  // <-- received from runEventLoop
+): Promise<void> {
+  const HEARTBEAT_TIMEOUT_MS = 15_000;
+  let lastEventAt = Date.now();
+  let watchdogTimer: ReturnType<typeof setTimeout> | null = null;
+
+  const resetWatchdog = () => {
+    lastEventAt = Date.now();
+    if (watchdogTimer) clearTimeout(watchdogTimer);
+    watchdogTimer = setTimeout(() => {
+      if (Date.now() - lastEventAt >= HEARTBEAT_TIMEOUT_MS) {
+        watchdogAbort.abort();  // This now propagates to reader.read() via composed signal
+      }
+    }, HEARTBEAT_TIMEOUT_MS);
+  };
+
+  try {
+    resetWatchdog();
+    for await (const event of eventStream) {
+      if (this.eventSubscriptionController?.signal.aborted || watchdogAbort.signal.aborted) break;
+      resetWatchdog();
+      this.handleSdkEvent(event);
+    }
+  } finally {
+    if (watchdogTimer) clearTimeout(watchdogTimer);
+  }
+}
+```
+
+**Key behavior change**: When the 15s heartbeat timeout fires, `watchdogAbort.abort()` now propagates through `iterationAbort` → `signal` on the SDK's `event.subscribe()` → `reader.cancel()` inside `createSseClient`. This causes `reader.read()` to reject with an `AbortError`, unblocking the `for await` loop immediately rather than waiting for the next event (which may never come).
+
+### 5.2 Fix B: Early Session Event Filtering
+
+**Problem**: All SSE events for all sessions pass through `handleSdkEvent()` and `emitEvent()`, even when handlers immediately filter them out by session ID. High-volume background agent events create processing overhead for foreground sessions ([ref: Pattern B](../research/docs/2026-03-01-opencode-tui-concurrency-bottlenecks.md#bottleneck-pattern-b-shared-sse-stream-across-all-sessions)).
+
+**Solution**: Maintain a set of "active session IDs" and filter events at the `processEventStream()` level before calling `handleSdkEvent()`. Events for unknown/inactive sessions are skipped, avoiding the cost of the full dispatch chain.
+
+**Implementation:**
+
+```typescript
+// opencode.ts — class OpenCodeClient
+
+/** Sessions explicitly registered as active */
+private activeSessionIds = new Set<string>();
+
+/** Register a session as active — called in createSession() / resumeSession() */
+registerActiveSession(sessionId: string): void {
+  this.activeSessionIds.add(sessionId);
+}
+
+/** Unregister a session — called in dispose() / session cleanup */
+unregisterActiveSession(sessionId: string): void {
+  this.activeSessionIds.delete(sessionId);
+}
+
+// In createSession():
+async createSession(options?: SessionOptions): Promise<Session> {
+  // ... existing session creation logic ...
+  this.registerActiveSession(sessionId);  // <-- NEW
+  return wrappedSession;
+}
+
+// In session dispose/cleanup:
+dispose(sessionId: string): void {
+  this.unregisterActiveSession(sessionId);  // <-- NEW
+  // ... existing cleanup ...
+}
+
+// In processEventStream() for-await loop:
+for await (const event of eventStream) {
+  if (this.eventSubscriptionController?.signal.aborted || watchdogAbort.signal.aborted) break;
+  resetWatchdog();
+
+  // Early filter: skip events for sessions with no active registration
+  // Always process session lifecycle events and global events (no sessionID)
+  const eventSessionId = (event as { properties?: { sessionID?: string } }).properties?.sessionID;
+  if (
+    eventSessionId &&
+    !this.activeSessionIds.has(eventSessionId) &&
+    !this.isSessionLifecycleEvent(event)
+  ) {
+    continue;  // Skip — session not registered
+  }
+
+  this.handleSdkEvent(event);
+}
+
+private isSessionLifecycleEvent(event: SdkEvent): boolean {
+  return ["session.created", "session.updated", "session.idle", "session.error", "session.deleted"]
+    .includes(event.type);
+}
+```
+
+**Trade-off**: This adds a `Set.has()` check per event (~O(1)) but avoids the full `handleSdkEvent()` → `emitEvent()` → handler fanout chain for irrelevant events. For workflows with 5+ concurrent sessions, this reduces per-event processing cost significantly.
+
+### 5.3 Fix C: Lightweight Handler Enforcement in `emitEvent()`
+
+**Problem**: `emitEvent()` iterates all handlers synchronously within the `for await` iteration. Slow handlers (e.g., Zod validation in `EventBus.publish()`) delay `resetWatchdog()` for subsequent events ([ref: Pattern C](../research/docs/2026-03-01-opencode-tui-concurrency-bottlenecks.md#bottleneck-pattern-c-synchronous-handler-fanout-in-emitevent)).
+
+**Solution**: Keep synchronous dispatch (matching OpenCode's `Bus.publish()` pattern at `bus/index.ts:53-57`) but ensure handlers themselves are lightweight. Heavy work should be deferred inside the handler implementations, not at the dispatch level.
+
+**Implementation:**
+
+The `emitEvent()` dispatch remains synchronous:
+
+```typescript
+// opencode.ts — emitEvent() — NO CHANGE to dispatch pattern
+private emitEvent<T extends EventType>(
+  eventType: T,
+  sessionId: string,
+  data: Record<string, unknown>,
+): void {
+  const handlers = this.eventHandlers.get(eventType);
+  if (!handlers) return;
+
+  const event: AgentEvent<T> = {
+    type: eventType,
+    sessionId,
+    timestamp: new Date().toISOString(),
+    data,
+  };
+
+  for (const handler of handlers) {
+    try {
+      handler(event as AgentEvent<EventType>);
+    } catch (error) {
+      console.error(`Error in event handler for ${eventType}:`, error);
+    }
+  }
+}
+```
+
+Instead, audit and optimize the registered handlers:
+
+1. **`stream()` handlers** (`deltaQueue.push()` + `resolveNext?.()`) — already fast, no change needed.
+2. **`OpenCodeStreamAdapter` handlers** — ensure `EventBus.publish()` calls are non-blocking. If `EventBus.publish()` performs Zod validation, either:
+   - Move validation to the consumer side (lazy validation), or
+   - Cache validated schemas to avoid repeated `z.parse()` overhead.
+3. **Correlation/tracking handlers** — ensure `subagentStateByParentSession` updates are simple Map operations.
+
+**Rationale**: OpenCode's own `Bus.publish()` uses the same synchronous pattern and has no fast/slow separation. The primary defense against handler-induced delays is Fix B (reducing event volume via early filtering), which eliminates the majority of unnecessary handler invocations. If handler overhead remains a problem after Fix B, microtask dispatch can be considered as a follow-up.
+
+### 5.4 Fix D: `completionPromise` Abort Guard
+
+**Problem**: `OpenCodeStreamAdapter.startStreaming()` blocks indefinitely on `await completionPromise` when `session.idle` never arrives due to SSE stalls ([ref: Pattern D](../research/docs/2026-03-01-opencode-tui-concurrency-bottlenecks.md#bottleneck-pattern-d-completionpromise-indefinite-blocking-in-adapter)).
+
+**Solution**: Strengthen abort signal handling on the `completionPromise`. Per Q2 resolution, no hard timeout is added — the defense against indefinite hangs is the watchdog abort (Fix A) propagating through the SSE reconnection cycle, which will eventually deliver `session.idle` or `session.error` on reconnect. The `completionPromise` only needs to respect the external abort signal.
+
+**Implementation:**
+
+```typescript
+// opencode-adapter.ts — startStreaming()
+
+const completionPromise = new Promise<{ reason: string; error?: string }>((resolve) => {
+  let resolved = false;
+  const safeResolve = (value: { reason: string; error?: string }) => {
+    if (resolved) return;
+    resolved = true;
+    resolve(value);
+  };
+
+  // Existing handlers
+  const onIdle = client?.on("session.idle", (event) => {
+    if (event.sessionId !== this.sessionId) return;
+    safeResolve({ reason: event.data.reason ?? "idle" });
+  });
+
+  const onError = client?.on("session.error", (event) => {
+    if (event.sessionId !== this.sessionId) return;
+    safeResolve({ reason: "error", error: String(event.data.error ?? "Unknown error") });
+  });
+
+  // NEW: Abort signal listener — resolves immediately on abort
+  if (this.abortController?.signal) {
+    if (this.abortController.signal.aborted) {
+      safeResolve({ reason: "aborted" });
+    } else {
+      this.abortController.signal.addEventListener("abort", () => {
+        safeResolve({ reason: "aborted" });
+      }, { once: true });
+    }
+  }
+
+  this.unsubscribers.push(() => {
+    onIdle?.();
+    onError?.();
+  });
+});
+```
+
+**Key behavior change**: The `completionPromise` now resolves immediately when the external abort signal fires (e.g., from Ctrl+C via the executor abort chain in Fix E, or from the watchdog-triggered SSE reconnection causing state reconciliation). This eliminates the indefinite block without imposing an arbitrary timeout.
+
+### 5.5 Fix E: Executor-Level Abort Signal Propagation
+
+**Problem**: `executeWorkflow()` at `executor.ts:455` calls `streamGraph(compiled, { initialState })` without passing `abortSignal`. The entire graph execution chain has no externally-controlled cancellation mechanism ([ref: codebase analysis — executor.ts:455](../src/workflows/executor.ts)).
+
+**Solution**: Create an `AbortController` in `executeWorkflow()` and propagate its signal through `streamGraph()` → `streamSteps()` → `executeWithRetry()` → node context → `spawnSubagent()`.
+
+**Implementation:**
+
+```typescript
+// executor.ts — executeWorkflow()
+async function executeWorkflow(
+  compiled: CompiledGraph,
+  options: WorkflowExecutionOptions,
+): Promise<WorkflowResult> {
+  // Create a workflow-level abort controller
+  const workflowAbort = new AbortController();
+
+  // Expose abort to callers (e.g., TUI can wire Ctrl+C)
+  options.onAbortController?.(workflowAbort);
+
+  try {
+    for await (const step of streamGraph(compiled, {
+      initialState: options.initialState,
+      abortSignal: workflowAbort.signal,  // <-- NEW
+    })) {
+      if (workflowAbort.signal.aborted) break;
+      // ... existing step processing ...
+    }
+  } finally {
+    // Ensure cleanup even if the loop is broken
+    if (!workflowAbort.signal.aborted) {
+      workflowAbort.abort();
+    }
+  }
+}
+```
+
+The `streamSteps()` function in `compiled.ts` already checks `options.abortSignal?.aborted` at line 369 and passes `abortSignal` into `ExecutionContext` at line 639. Wiring the signal from `executeWorkflow()` activates this entire existing cancellation chain.
+
+**Deep blocking chain with abort signal (target state):**
+
+```
+executeWorkflow() creates workflowAbort
+  └─ streamGraph(compiled, { abortSignal: workflowAbort.signal })
+      └─ streamSteps() checks abortSignal at each node
+          └─ executeWithRetry() passes abortSignal to context
+              └─ node.execute(context) receives context.abortSignal
+                  └─ spawnSubagent(agent, context.abortSignal)
+                      └─ spawnFn([{...agent, abortSignal}], abortSignal)
+                          └─ spawnSubagentParallel creates parallelAbort chained to signal
+                              └─ spawnOne creates agentAbort chained to parallelAbort
+                                  └─ adapter.consumeStream(stream, agentAbort.signal)
+                                      └─ SubagentStreamAdapter checks abortSignal each chunk
+```
+
+### 5.6 Fix F: `stream()` Generator Abort Signal Integration
+
+**Problem**: The `stream()` async generator at `opencode.ts:2148` polls every 25ms indefinitely with no overall timeout. If no terminal event arrives, it spin-polls forever ([ref: Pattern F](../research/docs/2026-03-01-opencode-tui-concurrency-bottlenecks.md#bottleneck-pattern-f-stream-generator-infinite-poll-without-overall-timeout)).
+
+**Solution**: Per Q2 resolution (matching OpenCode's no-upper-bound pattern), we do NOT add a hard overall timeout. Instead, we integrate the `stream()` generator with the external abort signal from the executor chain (Fix E) so that cancellation propagates into the generator's polling loop.
+
+**Implementation:**
+
+```typescript
+// opencode.ts — stream() async generator
+
+// Accept an optional abort signal
+stream: (options?: { abortSignal?: AbortSignal }): AsyncIterable<AgentMessage> => {
+  return {
+    async *[Symbol.asyncIterator]() {
+      // ... existing setup (deltaQueue, resolveNext, etc.) ...
+
+      // NEW: Register abort signal listener to break the polling loop
+      const abortSignal = options?.abortSignal;
+      if (abortSignal) {
+        abortSignal.addEventListener("abort", () => {
+          streamDone = true;
+          resolveNext?.();
+        }, { once: true });
+      }
+
+      try {
+        while (true) {
+          while (!streamDone || deltaQueue.length > 0) {
+            if (deltaQueue.length > 0) {
+              const msg = deltaQueue.shift()!;
+              yield msg;
+              continue;
+            }
+            if (streamDone) break;
+
+            // Check abort signal in the polling loop
+            if (abortSignal?.aborted) {
+              streamDone = true;
+              break;
+            }
+
+            if (terminalEventSeen && Date.now() - terminalEventAt >= PRE_PROMPT_TERMINAL_SETTLE_MS) {
+              streamDone = true;
+              break;
+            }
+
+            await new Promise<void>((resolve) => {
+              resolveNext = resolve;
+              setTimeout(resolve, STREAM_POLL_MS);
+            });
+            resolveNext = null;
+          }
+          // ... existing auto-compaction logic ...
+          break;
+        }
+      } finally {
+        // ... existing cleanup (unsubscribe handlers) ...
+      }
+    },
+  };
+},
+```
+
+**Key behavior change**: The `stream()` generator now terminates when the external abort signal fires (from the executor chain, Ctrl+C, or watchdog-triggered reconnection). The `resolveNext?.()` call in the abort listener immediately wakes the polling loop, which then checks `streamDone` and exits. This replaces the need for a hard timeout — the defense against indefinite polling is the abort signal chain from the executor (Fix E) and the watchdog reconnection cycle (Fix A).
+
+### 5.7 Constants Summary
+
+| Constant | Current Value | Proposed Value | Justification |
+|---|---|---|---|
+| `HEARTBEAT_TIMEOUT_MS` | 15,000ms | 15,000ms (unchanged) | Server heartbeat is 10s; 15s provides adequate margin |
+| `SSE_RECONNECT_DELAY_MS` | 250ms (flat) | **250ms initial, exponential backoff, 30s cap** | Matches OpenCode SDK pattern; fast initial recovery, backs off on persistent failures |
+| `STREAM_POLL_MS` | 25ms | 25ms (unchanged) | ~40 polls/sec is reasonable CPU tradeoff |
+| `PRE_PROMPT_TERMINAL_SETTLE_MS` | 500ms | 500ms (unchanged) | Sufficient for late-arriving events |
+| `STREAM_OVERALL_TIMEOUT_MS` | ∞ (none) | ∞ (none — no change) | Matches OpenCode pattern; abort signal chain provides escape hatch |
+| `COMPLETION_TIMEOUT_MS` | ∞ (none) | ∞ (none — no change) | Matches OpenCode pattern; abort signal provides escape hatch |
+
+## 6. Alternatives Considered
+
+| Option | Pros | Cons | Decision |
+|---|---|---|---|
+| **Per-session SSE connections** (multiple `event.subscribe()` calls) | Eliminates cross-session contention entirely | Requires server-side session-scoped SSE endpoints; N connections per workflow | **Rejected**: Requires OpenCode server changes (Non-Goal NG1). Consider for future iteration. |
+| **Multiple `OpenCodeClient` instances** (one per workflow sub-agent) | Full isolation of event loops and handlers | Significant refactor of session management; each client instance has its own server connection; state synchronization complexity | **Rejected**: High implementation cost, architectural risk (Non-Goal NG3). |
+| **Web Worker per session** (Bun Worker for each sub-agent stream) | True parallelism; no event loop contention | Overhead of worker creation; requires serialization of events across worker boundary; Bun Worker limitations | **Rejected**: Bun Worker restrictions and serialization overhead outweigh benefits for the current scale. |
+| **`AbortSignal.any()` for composed signals** | Clean API; native Bun 1.2+ support; no manual listener cleanup | Requires Bun 1.2+ | **Selected**: Bun 1.2+ is the project's target runtime. |
+| **Event priority queue** (foreground sessions get priority processing) | Ensures foreground responsiveness under load | Complex priority logic; risk of starvation for background sessions; overkill for current use case | **Deferred**: Consider if Fix B (early filtering) is insufficient. |
+
+## 7. Cross-Cutting Concerns
+
+### 7.1 Security and Privacy
+
+- No security implications — changes are internal to the SSE event processing pipeline.
+- Abort signals do not leak session data across boundaries.
+- The early session filter (Fix B) uses session IDs already present in the event stream.
+
+### 7.2 Observability Strategy
+
+- **Metrics** (log-based initially, structured metrics in future):
+  - `sse.watchdog.timeout.count` — Number of watchdog timeouts per session (Fix A)
+  - `sse.event.filtered.count` — Number of events early-filtered by session ID (Fix B)
+  - `stream.overall.timeout.count` — Number of overall stream timeouts (Fix F)
+  - `completion.timeout.count` — Number of completion promise timeouts (Fix D)
+- **Logging**:
+  - Log at `warn` level when watchdog abort fires and propagates to SSE reader (Fix A)
+  - Log at `debug` level the count of filtered events per SSE reconnection (Fix B)
+  - Log at `error` level when overall stream timeout fires (Fix F)
+  - Log at `warn` level when completion promise times out (Fix D)
+
+### 7.3 Compatibility and Risk
+
+- **OpenCode SDK compatibility**: Fix A passes an `AbortSignal` to `event.subscribe()`. The SDK's `createSseClient` already supports `options.signal` at `serverSentEvents.gen.js:49` ([ref: research, §Bottleneck Pattern A](../research/docs/2026-03-01-opencode-tui-concurrency-bottlenecks.md#bottleneck-pattern-a-sse-readerread-indefinite-block-dead-connection)), so no SDK changes are needed.
+- **Event ordering**: Fix C (async dispatch) changes handler execution from synchronous to microtask-based. This preserves intra-event ordering (all handlers for one event run before the next event's handlers) because microtasks complete before the next `for await` iteration yields. However, inter-handler ordering within a single event dispatch may change if multiple handlers depend on shared mutable state.
+- **Timeout values**: Fix D and Fix F introduce timeouts that could trigger prematurely for very long-running agent tasks (e.g., complex code generation). Configurable timeouts mitigate this risk.
+- **Claude/Copilot SDK adapters**: These adapters are unaffected since they use different streaming patterns ([ref: research, §Workflow-SDK Agent SDK Integration](../research/docs/2026-03-01-opencode-tui-concurrency-bottlenecks.md)).
+
+## 8. Migration, Rollout, and Testing
+
+### 8.1 Deployment Strategy
+
+- [ ] **Phase 1 — Foundation (Fixes A + E)**: Implement SSE abort propagation and executor abort chain. These are the highest-impact fixes that eliminate indefinite hangs.
+- [ ] **Phase 2 — Optimization (Fixes B + C)**: Implement early session filtering and async handler fanout. These reduce overhead but require careful testing for ordering regressions.
+- [ ] **Phase 3 — Safety Nets (Fixes D + F)**: Add overall timeouts to `completionPromise` and `stream()` generator. These are defensive measures that prevent edge-case hangs.
+
+### 8.2 Test Plan
+
+- **Unit Tests:**
+  - [ ] Watchdog abort propagates to SSE reader signal (Fix A)
+  - [ ] Composed abort signal fires when either watchdog or global controller aborts (Fix A)
+  - [ ] `activeSessionIds` filtering correctly skips events for unknown sessions (Fix B)
+  - [ ] Session lifecycle events bypass the filter (Fix B)
+  - [ ] `emitEvent()` with `queueMicrotask` dispatches all handlers (Fix C)
+  - [ ] Handler errors in async dispatch are caught and logged (Fix C)
+  - [ ] `completionPromise` resolves on abort signal (Fix D)
+  - [ ] `completionPromise` resolves on timeout (Fix D)
+  - [ ] `executeWorkflow()` passes abort signal to `streamGraph()` (Fix E)
+  - [ ] `stream()` generator terminates on overall timeout (Fix F)
+  - [ ] `stream()` generator clears timeout on normal completion (Fix F)
+
+- **Integration Tests:**
+  - [ ] Ralph planner step completes successfully with all fixes applied
+  - [ ] Ralph workflow with 3+ concurrent workers does not exhibit cross-session contention
+  - [ ] Simulated dead SSE connection triggers watchdog → abort → reconnect cycle
+  - [ ] Ctrl+C during workflow execution propagates abort through entire chain
+
+- **End-to-End Tests:**
+  - [ ] Full Ralph workflow (planner → workers → aggregation) completes without hangs
+  - [ ] TUI remains responsive during multi-worker execution
+  - [ ] Streaming text and tool calls render correctly during parallel execution
+
+## 9. Open Questions / Unresolved Issues
+
+- [x] **Q1 — Microtask vs. synchronous dispatch for `resolveNext()` (Fix C)**: **Resolved — Keep all handlers synchronous, matching OpenCode's pattern.** OpenCode's `Bus.publish()` invokes all handlers synchronously in a `for` loop and awaits results via `Promise.all(pending)` — no fast/slow separation ([ref: `bus/index.ts:53-57`](https://github.com/anomalyco/opencode)). For the workflow-sdk, we will follow the same pattern: all `emitEvent()` handlers remain synchronous. Instead of making dispatch async, Fix C should focus on **ensuring handlers are lightweight** (deferring heavy work like Zod validation inside the handlers themselves, not at the dispatch level). If handler overhead still causes watchdog issues after Fix B reduces event volume, revisit with microtask dispatch as a follow-up.
+
+- [x] **Q2 — Overall timeout values (Fixes D + F)**: **Resolved — No hard upper bound, matching OpenCode's pattern.** OpenCode does not impose an overall timeout on SSE streaming or session duration — `idleTimeout: 0` (disabled) on the SSE server, and no session-level upper bound. The only timeouts are per-LLM-request (5 min default, configurable per provider, can be disabled). For the workflow-sdk: (1) Remove the proposed `STREAM_OVERALL_TIMEOUT_MS` from Fix F — the `stream()` generator should not have an overall timeout, consistent with OpenCode. (2) For Fix D, the `completionPromise` should not have a hard timeout either; instead, it should rely solely on the watchdog abort (Fix A) and external abort signals (Fix E) for escape. The defense against indefinite hangs is the watchdog → reconnect cycle (Fix A), not a hard timeout.
+
+- [x] **Q3 — Abort signal composition strategy**: **Resolved — Use `AbortSignal.any()`.** Bun 1.2+ supports `AbortSignal.any()` natively, providing clean composition of multiple abort signals without manual event listener management. This simplifies Fix A's implementation: `const composedSignal = AbortSignal.any([watchdogAbort.signal, this.eventSubscriptionController!.signal])` replaces the manual `addEventListener` forwarding pattern.
+
+- [x] **Q4 — Reconnection behavior after watchdog abort (Fix A)**: **Resolved — Use exponential backoff, matching OpenCode's SDK pattern.** OpenCode's SSE client uses exponential backoff with formula `min(retryDelay * 2^(attempt-1), sseMaxRetryDelay)`, starting at 3000ms and capping at 30,000ms. The workflow-sdk should adopt the same pattern: replace the flat 250ms `SSE_RECONNECT_DELAY_MS` with exponential backoff starting at 250ms (to maintain fast initial recovery) and capping at 30,000ms. Reset the attempt counter on successful event receipt.
+
+- [x] **Q5 — Active session registration lifecycle (Fix B)**: **Resolved — Use explicit/manual registration, matching OpenCode's pattern.** OpenCode uses explicit session registration via `ACPSessionManager.create/load()` — sessions must be manually added to a `Map` before events are recognized. Events for unknown sessions are silently skipped via `tryGet(sessionID)`. The workflow-sdk should follow the same pattern: sessions are registered via `registerActiveSession(sessionId)` when created (in `createSession()` / `resumeSession()`) and unregistered on `dispose()` / session completion. The `stream()` and `startStreaming()` methods should NOT auto-register — the caller is responsible for ensuring the session is registered before consuming events.
diff --git a/specs/playwright-cli-integration.md b/specs/playwright-cli-integration.md
new file mode 100644
index 0000000000..f954cfecff
--- /dev/null
+++ b/specs/playwright-cli-integration.md
@@ -0,0 +1,498 @@
+# Playwright CLI Integration — Bundling, Installation, and Prompt Migration
+
+| Document Metadata      | Details     |
+| ---------------------- | ----------- |
+| Author(s)              | lavaman131  |
+| Status                 | Draft (WIP) |
+| Team / Owner           | Atomic CLI  |
+| Created / Last Updated | 2026-02-25  |
+
+## 1. Executive Summary
+
+This spec proposes replacing the existing `WebFetch`, `WebSearch`, and `webfetch` tools across all three agent platforms (Claude, Copilot, OpenCode) with a new `playwright-cli` skill backed by the `@playwright/cli` npm package. Playwright CLI is a token-efficient browser automation CLI designed for coding agents that provides a strict superset of current web fetch/search capabilities — including full JavaScript rendering, session persistence, authentication, screenshots, and multi-page navigation. The integration involves: (1) adding `@playwright/cli` as a dependency and installing it during postinstall to `~/.atomic/<agent>/skills/playwright-cli/`, (2) updating 15 files across 3 agent platforms that currently reference web search/fetch tools, (3) creating a new `playwright-cli` skill definition following the established `SKILL.md` pattern, and (4) modifying install scripts to bundle Playwright CLI in binary distributions. This modernizes the web interaction layer while maintaining backward compatibility with the existing skill discovery and global config sync mechanisms.
+
+## 2. Context and Motivation
+
+### 2.1 Current State
+
+The Atomic CLI has a multi-agent architecture supporting three coding agent SDKs (Claude, OpenCode, Copilot) with a unified skill system ([ref: research/docs/2026-02-08-skill-loading-from-configs-and-ui.md](../research/docs/2026-02-08-skill-loading-from-configs-and-ui.md)):
+
+- **Built-in skills**: Embedded in the `BUILTIN_SKILLS` array in `src/ui/commands/skill-commands.ts`. These are TypeScript objects with inline prompt content, registered automatically during `initializeCommands()` → `registerSkillCommands()` → `registerBuiltinSkills()` ([ref: research/docs/2026-02-14-frontend-design-builtin-skill-integration.md](../research/docs/2026-02-14-frontend-design-builtin-skill-integration.md)).
+- **Disk-based skills**: Loaded from `SKILL.md` files discovered in `.claude/skills/`, `.opencode/skills/`, `.github/skills/`, and global paths. All 11 current skills are byte-for-byte identical across all three SDK directories ([ref: research/docs/2026-02-17-legacy-code-removal-skills-migration.md](../research/docs/2026-02-17-legacy-code-removal-skills-migration.md)).
+- **Web tools**: Currently provided as platform-specific built-in tools with different naming conventions:
+    - **Claude**: `WebFetch`, `WebSearch` (two separate capitalized tools in `BUILTIN_ALLOWED_TOOLS` array at `src/sdk/clients/claude.ts:272-288`)
+    - **GitHub/Copilot**: `"web"` (single abstracted tool name in JSON array)
+    - **OpenCode**: `webfetch` (single lowercase tool, boolean flag + `"allow"` permission in `.opencode/opencode.json`)
+
+**15 files** currently reference web search/fetch tools across the codebase ([ref: research/docs/2026-02-25-playwright-cli-integration-research.md](../research/docs/2026-02-25-playwright-cli-integration-research.md)):
+
+- 7 agent configs (`.claude/agents/`, `.github/agents/`, `.opencode/agents/`)
+- 6 skill configs (`.claude/skills/`, `.github/skills/`, `.opencode/skills/`)
+- 1 source code file (`src/sdk/clients/claude.ts`)
+- 1 configuration file (`.opencode/opencode.json`)
+
+### 2.2 The Problem
+
+- **Limited web capability**: Current `WebFetch`/`WebSearch` tools cannot handle JavaScript-rendered content, dynamic pages, authentication flows, or session persistence. This limits agents' ability to research modern SPAs and documentation sites.
+- **Fragmented tool naming**: Three different tool names across three platforms (`WebFetch`/`WebSearch` vs `"web"` vs `webfetch`) creates maintenance burden and inconsistency in agent prompts.
+- **No browser automation**: Agents cannot perform interactive web tasks such as filling forms, clicking buttons, or navigating multi-page flows — capabilities increasingly needed for E2E testing and documentation research.
+- **Token inefficiency**: WebFetch returns raw HTML/markdown without structure awareness, often consuming excessive context tokens for simple data extraction tasks.
+
+## 3. Goals and Non-Goals
+
+### 3.1 Functional Goals
+
+- [ ] Replace all `WebFetch`, `WebSearch`, and `webfetch` references across 15 files with `playwright-cli` skill references
+- [ ] Create `playwright-cli/SKILL.md` in all three SDK skill directories (`.claude/skills/`, `.opencode/skills/`, `.github/skills/`) with byte-for-byte identical content
+- [ ] Add `@playwright/cli` as a dependency in `package.json`
+- [ ] Update `src/scripts/postinstall.ts` to install Playwright CLI and deploy SKILL.md to `~/.atomic/<agent>/skills/playwright-cli/`
+- [ ] Update `install.sh` and `install.ps1` to handle Playwright CLI installation for binary distributions
+- [ ] Remove `"WebFetch"` and `"WebSearch"` from the `BUILTIN_ALLOWED_TOOLS` array in `src/sdk/clients/claude.ts`
+- [ ] Remove `"webfetch": "allow"` from `.opencode/opencode.json` permissions
+- [ ] Add `playwright-cli` as a built-in skill in the `BUILTIN_SKILLS` array in `src/ui/commands/skill-commands.ts`
+
+### 3.2 Non-Goals (Out of Scope)
+
+- [ ] We will NOT implement MCP server integration for Playwright (use CLI approach instead, which aligns with current tool patterns)
+- [ ] We will NOT auto-install Chromium browsers during `bun install` (defer to first-use or explicit command to avoid ~200-400MB download during installation)
+- [ ] We will NOT support custom browser profiles or enterprise proxy configuration in this version
+- [ ] We will NOT build a custom TUI for Playwright test results visualization
+- [ ] We will NOT modify the skill discovery/loading mechanism itself — only add new content through existing patterns
+
+## 4. Proposed Solution (High-Level Design)
+
+### 4.1 System Architecture Diagram
+
+```mermaid
+%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#f8f9fa','primaryTextColor':'#2c3e50','primaryBorderColor':'#4a5568','lineColor':'#4a90e2','secondaryColor':'#ffffff','tertiaryColor':'#e9ecef','background':'#f5f7fa','mainBkg':'#f8f9fa','nodeBorder':'#4a5568','clusterBkg':'#ffffff','clusterBorder':'#cbd5e0','edgeLabelBackground':'#ffffff'}}}%%
+
+flowchart TB
+    classDef installStep fill:#5a67d8,stroke:#4c51bf,stroke-width:2.5px,color:#ffffff,font-weight:600
+    classDef configTarget fill:#48bb78,stroke:#38a169,stroke-width:2.5px,color:#ffffff,font-weight:600
+    classDef agentNode fill:#4a90e2,stroke:#357abd,stroke-width:2.5px,color:#ffffff,font-weight:600
+    classDef skillNode fill:#667eea,stroke:#5a67d8,stroke-width:2.5px,color:#ffffff,font-weight:600
+
+    subgraph InstallFlow["◆ Installation Flow"]
+        direction TB
+        BunInstall["<b>bun install</b><br><i>npm/bun path</i>"]:::installStep
+        InstallSh["<b>install.sh / install.ps1</b><br><i>binary path</i>"]:::installStep
+        Postinstall["<b>postinstall.ts</b><br>1. syncAtomicGlobalAgentConfigs<br>2. Install @playwright/cli<br>3. Deploy SKILL.md"]:::installStep
+    end
+
+    subgraph GlobalStore["◆ ~/.atomic/ (Global Store)"]
+        direction TB
+        ClaudeSkill["<b>.claude/skills/playwright-cli/</b><br>SKILL.md"]:::configTarget
+        OpenCodeSkill["<b>.opencode/skills/playwright-cli/</b><br>SKILL.md"]:::configTarget
+        CopilotSkill["<b>.copilot/skills/playwright-cli/</b><br>SKILL.md"]:::configTarget
+    end
+
+    subgraph AgentUsage["◆ Agent Runtime"]
+        direction TB
+        ClaudeAgent["<b>Claude Agent</b><br>codebase-online-researcher<br>debugger, reviewer"]:::agentNode
+        CopilotAgent["<b>Copilot Agent</b><br>codebase-online-researcher<br>debugger"]:::agentNode
+        OpenCodeAgent["<b>OpenCode Agent</b><br>codebase-online-researcher<br>debugger"]:::agentNode
+    end
+
+    PlaywrightCLI["<b>@playwright/cli</b><br>Browser Automation<br><i>Token-efficient CLI</i>"]:::skillNode
+
+    BunInstall -->|"triggers"| Postinstall
+    InstallSh -->|"calls"| Postinstall
+    Postinstall -->|"deploys"| ClaudeSkill
+    Postinstall -->|"deploys"| OpenCodeSkill
+    Postinstall -->|"deploys"| CopilotSkill
+
+    ClaudeAgent -->|"invokes"| PlaywrightCLI
+    CopilotAgent -->|"invokes"| PlaywrightCLI
+    OpenCodeAgent -->|"invokes"| PlaywrightCLI
+
+    ClaudeSkill -.->|"instructs"| ClaudeAgent
+    OpenCodeSkill -.->|"instructs"| OpenCodeAgent
+    CopilotSkill -.->|"instructs"| CopilotAgent
+
+    style InstallFlow fill:#ffffff,stroke:#cbd5e0,stroke-width:2px,stroke-dasharray:8 4
+    style GlobalStore fill:#ffffff,stroke:#cbd5e0,stroke-width:2px,stroke-dasharray:8 4
+    style AgentUsage fill:#ffffff,stroke:#cbd5e0,stroke-width:2px,stroke-dasharray:8 4
+```
+
+### 4.2 Architectural Pattern
+
+We are adopting a **Skill-as-Tool-Replacement** pattern where the `playwright-cli` skill replaces built-in platform tools (`WebFetch`/`WebSearch`/`webfetch`) with a unified skill definition. This follows the established **Materialize-then-Discover** pattern ([ref: research/docs/2026-02-17-legacy-code-removal-skills-migration.md](../research/docs/2026-02-17-legacy-code-removal-skills-migration.md)):
+
+1. Hardcode in `BUILTIN_SKILLS` array with full prompt
+2. System writes to all SDK directories as `SKILL.md` files
+3. System discovers back from disk (enables user overrides)
+4. Priority resolution handles conflicts
+
+### 4.3 Key Components
+
+| Component                              | Responsibility                                | Technology                  | Justification                                                                  |
+| -------------------------------------- | --------------------------------------------- | --------------------------- | ------------------------------------------------------------------------------ |
+| `playwright-cli/SKILL.md`              | Skill definition for all agent platforms      | Markdown + YAML frontmatter | Follows Agent Skills standard; byte-for-byte identical across platforms        |
+| `@playwright/cli` dependency           | Browser automation runtime                    | npm package (Node.js)       | Token-efficient CLI designed for coding agents; superset of WebFetch/WebSearch |
+| `postinstall.ts` extension             | Deploy SKILL.md during installation           | TypeScript (Bun)            | Extends existing postinstall hook; non-blocking error handling                 |
+| `install.sh` / `install.ps1` extension | Handle binary distribution installation       | Bash / PowerShell           | Extends existing installer pattern for cross-platform support                  |
+| Agent config updates (7 files)         | Replace web tool references                   | Markdown YAML frontmatter   | Platform-specific tool list updates                                            |
+| Skill config updates (6 files)         | Replace web tool instruction text             | Markdown                    | Update prose references to use playwright-cli                                  |
+| `claude.ts` allowlist update           | Remove WebFetch/WebSearch from built-in tools | TypeScript                  | Clean up stale tool references                                                 |
+
+## 5. Detailed Design
+
+### 5.1 New Skill Definition — `playwright-cli/SKILL.md`
+
+**Location**: Created in all three directories:
+
+- `.claude/skills/playwright-cli/SKILL.md`
+- `.opencode/skills/playwright-cli/SKILL.md`
+- `.github/skills/playwright-cli/SKILL.md`
+
+**Frontmatter** (following Agent Skills standard from [ref: research/docs/2026-02-08-skill-loading-from-configs-and-ui.md](../research/docs/2026-02-08-skill-loading-from-configs-and-ui.md)):
+
+```yaml
+---
+name: playwright-cli
+description: Browser automation for web research, data extraction, and testing using Playwright CLI
+aliases: ["pw", "playwright"]
+argument-hint: "[url-or-task]"
+---
+```
+
+**Body**: The SKILL.md body should document:
+
+1. Available Playwright CLI commands (navigate, snapshot, click, fill, evaluate, screenshot, etc.)
+2. Usage patterns for web research (replacing WebFetch/WebSearch workflows)
+3. Best practices for token-efficient browsing (prefer snapshots over full page content)
+4. Common workflows: fetching documentation, searching the web, extracting structured data
+
+**Skill content strategy**: Use the auto-generated SKILL.md from `playwright-cli install --skills`. This leverages official upstream content maintained by the Playwright team, ensuring accuracy and reducing maintenance burden.
+
+### 5.2 Agent Config Changes (7 files)
+
+#### Claude Agent Configs (3 files)
+
+**Files**:
+
+- `.claude/agents/codebase-online-researcher.md`
+- `.claude/agents/debugger.md`
+- `.claude/agents/reviewer.md` _(remove WebFetch/WebSearch entirely — no playwright-cli replacement per Q4 decision)_
+
+**Change**: In the `tools:` frontmatter field, remove `WebFetch, WebSearch` and add `playwright-cli` skill reference.
+
+**Before**:
+
+```yaml
+tools: Glob, Grep, ..., WebFetch, WebSearch
+```
+
+**After**:
+
+```yaml
+tools: Glob, Grep, ..., Bash
+```
+
+> Note: Playwright CLI is invoked via `Bash` tool (running `bunx playwright-cli` commands, per Bun-first project convention). The skill SKILL.md provides the instructions; the Bash tool provides the execution capability. Agents that already have Bash in their tool list need no additional tool.
+
+#### Copilot Agent Configs (2 files)
+
+**Files**:
+
+- `.github/agents/codebase-online-researcher.md`
+- `.github/agents/debugger.md`
+
+**Change**: In the `tools:` JSON array, remove `"web"` entry.
+
+**Before**:
+
+```yaml
+tools: ["search", "read", "execute", "web", "deepwiki/ask_question"]
+```
+
+**After**:
+
+```yaml
+tools: ["search", "read", "execute", "deepwiki/ask_question"]
+```
+
+#### OpenCode Agent Configs (2 files)
+
+**Files**:
+
+- `.opencode/agents/codebase-online-researcher.md`
+- `.opencode/agents/debugger.md`
+
+**Change**: In the YAML frontmatter, remove `webfetch: true`.
+
+**Before**:
+
+```yaml
+webfetch: true
+```
+
+**After**: Remove the line entirely.
+
+### 5.3 Skill Config Changes (6 files)
+
+#### `explain-code/SKILL.md` (3 files — Claude, Copilot, OpenCode)
+
+**Change**: Update the "Available Tools" section to replace `WebFetch/WebSearch` with `playwright-cli`.
+
+**Before**:
+
+```markdown
+- **WebFetch/WebSearch**: Use to retrieve web content for additional context if information is not found in DeepWiki.
+```
+
+**After**:
+
+```markdown
+- **Playwright CLI** (`playwright-cli`): Use to retrieve web content, browse documentation, and extract data from web pages if information is not found in DeepWiki. Invoke via the `/playwright-cli` skill or run `bunx playwright-cli` commands directly.
+```
+
+#### `research-codebase/SKILL.md` (3 files — Claude, Copilot, OpenCode)
+
+**Change**: Update sub-agent instruction text to reference playwright-cli instead of WebFetch/WebSearch.
+
+**Before**:
+
+```markdown
+- If you perform a web search using the WebFetch/WebSearch tools, instruct the agent to return LINKS with their findings
+```
+
+**After**:
+
+```markdown
+- If you perform a web search using the playwright-cli skill, instruct the agent to return LINKS with their findings
+```
+
+### 5.4 Source Code Changes
+
+#### `src/sdk/clients/claude.ts` — Remove WebFetch/WebSearch from Allowlist
+
+**Change**: Remove `"WebFetch"` and `"WebSearch"` from the `BUILTIN_ALLOWED_TOOLS` array.
+
+**Before** (L272-288):
+
+```typescript
+private static readonly BUILTIN_ALLOWED_TOOLS = [
+    "Bash",
+    "Read",
+    "Write",
+    "Edit",
+    "Glob",
+    "Grep",
+    "Task",
+    "Skill",
+    "MultiEdit",
+    "TodoRead",
+    "TodoWrite",
+    "WebFetch",
+    "WebSearch",
+    "NotebookEdit",
+    "NotebookRead",
+] as const;
+```
+
+**After**:
+
+```typescript
+private static readonly BUILTIN_ALLOWED_TOOLS = [
+    "Bash",
+    "Read",
+    "Write",
+    "Edit",
+    "Glob",
+    "Grep",
+    "Task",
+    "Skill",
+    "MultiEdit",
+    "TodoRead",
+    "TodoWrite",
+    "NotebookEdit",
+    "NotebookRead",
+] as const;
+```
+
+#### `.opencode/opencode.json` — Remove webfetch Permission
+
+**Change**: Remove `"webfetch": "allow"` from the `permission` object.
+
+**Before**:
+
+```json
+{
+    "permission": {
+        "edit": "allow",
+        "bash": "allow",
+        "webfetch": "allow",
+        "doom_loop": "allow",
+        "external_directory": "allow"
+    }
+}
+```
+
+**After**:
+
+```json
+{
+    "permission": {
+        "edit": "allow",
+        "bash": "allow",
+        "doom_loop": "allow",
+        "external_directory": "allow"
+    }
+}
+```
+
+### 5.5 Installation/Bundling Changes
+
+#### `package.json` — Add Dependency
+
+**Change**: Add `@playwright/cli` to `dependencies`.
+
+```json
+{
+    "dependencies": {
+        "@playwright/cli": "latest"
+    }
+}
+```
+
+#### `src/scripts/postinstall.ts` — Playwright CLI Installation
+
+**Change**: Add a new function to install Playwright CLI and deploy SKILL.md after the existing `syncAtomicGlobalAgentConfigs` call.
+
+```typescript
+async function installPlaywrightCli() {
+    // 1. Run `bunx playwright-cli install --skills` to generate SKILL.md
+    // 2. Copy generated SKILL.md to all three agent skill directories
+    //    in ~/.atomic/.claude/skills/playwright-cli/
+    //    in ~/.atomic/.opencode/skills/playwright-cli/
+    //    in ~/.atomic/.copilot/skills/playwright-cli/
+    // 3. Log success/warning (non-blocking, matching existing pattern)
+    // NOTE: Do NOT install Chromium browsers here — defer to first-use
+}
+```
+
+**Integration point**: After `syncAtomicGlobalAgentConfigs(getConfigRoot())` at L17, before `verifyAtomicGlobalConfigSync()`.
+
+**Error handling**: Follows existing non-blocking pattern — catches errors and logs warnings without failing installation.
+
+**Browser installation**: Chromium browsers are NOT installed during postinstall. Agents can run `bunx playwright install chromium` on first use when browser automation is needed.
+
+#### `install.sh` — Binary Distribution
+
+**Change**: Add Playwright CLI installation step in `sync_global_agent_configs()` after config copy (after L164). Downloads `@playwright/cli` during installation (not pre-bundled) — requires bun or npm on the target system.
+
+```bash
+# Install @playwright/cli if bun/npm is available (not pre-bundled to keep release artifacts small)
+if command -v bun >/dev/null 2>&1; then
+  bun install -g @playwright/cli@latest 2>/dev/null || true
+elif command -v npm >/dev/null 2>&1; then
+  npm install -g @playwright/cli@latest 2>/dev/null || true
+else
+  warn "Neither bun nor npm found. Install @playwright/cli manually for web browsing capabilities."
+fi
+# NOTE: Do NOT install Chromium browsers here — defer to first-use
+```
+
+#### `install.ps1` — Windows Binary Distribution
+
+**Change**: Mirror the bash installer's Playwright CLI installation in `Sync-GlobalAgentConfigs` (after L50).
+
+```powershell
+# Install @playwright/cli if bun/npm is available (downloaded during install, not pre-bundled)
+if (Get-Command bun -ErrorAction SilentlyContinue) {
+    bun install -g @playwright/cli@latest 2>$null
+} elseif (Get-Command npm -ErrorAction SilentlyContinue) {
+    npm install -g @playwright/cli@latest 2>$null
+} else {
+    Write-Warning "Neither bun nor npm found. Install @playwright/cli manually for web browsing capabilities."
+}
+# NOTE: Do NOT install Chromium browsers here - defer to first-use
+```
+
+### 5.6 BUILTIN_SKILLS Array Addition
+
+**File**: `src/ui/commands/skill-commands.ts`
+
+**Change**: Add a new entry to the `BUILTIN_SKILLS` array ([ref: research/docs/2026-02-14-frontend-design-builtin-skill-integration.md](../research/docs/2026-02-14-frontend-design-builtin-skill-integration.md)).
+
+```typescript
+{
+  name: "playwright-cli",
+  aliases: ["pw", "playwright"],
+  description: "Browser automation for web research, data extraction, and testing using Playwright CLI",
+  argumentHint: "[url-or-task]",
+  prompt: `[SKILL.md body content with $ARGUMENTS placeholder]`
+}
+```
+
+**Registration**: Follows existing `createBuiltinSkillCommand()` → `globalRegistry.register()` pattern. No changes needed to the registration mechanism itself.
+
+**Pinned status**: NOT pinned — users should be able to override with custom SKILL.md in project or global directories.
+
+## 6. Alternatives Considered
+
+| Option                                                           | Pros                                                                            | Cons                                                                                       | Reason for Rejection                                                                                                          |
+| ---------------------------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
+| **Option A: Keep WebFetch/WebSearch + Add Playwright CLI**       | No breaking change; gradual migration                                           | Two competing tools; agents confused about which to use; maintenance of both               | Fragmentation creates ambiguity for agents and doubles maintenance burden                                                     |
+| **Option B: Playwright MCP Server** (`microsoft/playwright-mcp`) | Richer integration via MCP protocol; auto-discovery by SDKs                     | Higher operational complexity; requires running MCP server process; heavier resource usage | CLI approach is more aligned with current tool patterns and is token-efficient by design                                      |
+| **Option C: Playwright CLI via Skill (Selected)**                | Unified approach; follows existing patterns; token-efficient; clean replacement | Requires updating 15+ files; browsers not pre-installed                                    | **Selected**: Best alignment with existing architecture; superset of current capabilities; follows established skill patterns |
+| **Option D: Custom Web Tool Wrapper**                            | Full control over API surface; could combine search + fetch                     | Reinventing the wheel; maintenance burden; no community support                            | Playwright CLI already provides everything needed with active community maintenance                                           |
+
+## 7. Cross-Cutting Concerns
+
+### 7.1 Security and Privacy
+
+- **Browser sandboxing**: Playwright CLI runs Chromium in sandboxed mode by default — no direct filesystem access from browser context.
+- **Credential exposure**: SKILL.md instructions must warn agents NOT to store authentication cookies/tokens in plain text or commit them to repositories.
+- **Content safety**: Playwright CLI can access arbitrary URLs. Existing MCP/tool permission systems should apply — no additional authorization layer needed since agents already have `Bash` tool access.
+
+### 7.2 Observability Strategy
+
+- **Skill loading**: Reuse existing skill loading indicator pattern (`● Skill(playwright-cli)` → `└ Successfully loaded skill`) from `tool-result.tsx:53-108` ([ref: research/docs/2026-02-08-skill-loading-from-configs-and-ui.md](../research/docs/2026-02-08-skill-loading-from-configs-and-ui.md)).
+- **Execution tracking**: Playwright CLI commands are run via Bash tool, which already logs tool calls in the TUI.
+- **Error reporting**: Failed Playwright CLI commands will surface through existing Bash tool error handling.
+
+### 7.3 Scalability and Capacity Planning
+
+- **Browser installation size**: Chromium is ~200-400MB. Not installed automatically during `bun install` — deferred to explicit user action or first-use.
+- **Disk footprint**: The `@playwright/cli` npm package itself is lightweight (~few MB). The SKILL.md files add negligible overhead (~1-2KB per platform).
+- **Memory usage**: Playwright CLI launches a browser process on demand. Each browser instance uses ~100-300MB RAM depending on page complexity. Agents should be instructed to close sessions when done.
+
+## 8. Migration, Rollout, and Testing
+
+### 8.1 Deployment Strategy
+
+- [ ] **Phase 1**: Create `playwright-cli/SKILL.md` in all three SDK directories. Add `@playwright/cli` as dependency. Update `postinstall.ts`. This can be tested independently.
+- [ ] **Phase 2**: Update agent configs (7 files) and skill configs (6 files) to replace web tool references with playwright-cli. Remove `WebFetch`/`WebSearch` from `BUILTIN_ALLOWED_TOOLS` and `webfetch` permission.
+- [ ] **Phase 3**: Update `install.sh` and `install.ps1` for binary distribution. Add `playwright-cli` to `BUILTIN_SKILLS` array in `skill-commands.ts`.
+- [ ] **Phase 4**: Verify end-to-end functionality across all three agent platforms. Run E2E tests.
+
+### 8.2 Data Migration Plan
+
+- **No data migration required**: This is a tool/skill replacement, not a data schema change.
+- **Backward compatibility**: Agents that rely on WebFetch/WebSearch will need to adapt to using playwright-cli commands. The SKILL.md provides equivalent instruction patterns.
+- **Rollback**: If issues arise, re-add `WebFetch`/`WebSearch` to the allowlist and agent configs. The changes are purely additive/removal in config files.
+
+### 8.3 Test Plan
+
+- **Unit Tests**: Verify SKILL.md frontmatter parsing works with `parseMarkdownFrontmatter()` function.
+- **Integration Tests**:
+    - Verify `postinstall.ts` correctly deploys SKILL.md to `~/.atomic/<agent>/skills/playwright-cli/`.
+    - Verify `syncAtomicGlobalAgentConfigs()` includes playwright-cli skill in sync and does NOT exclude it (it doesn't match `gh-*`/`sl-*` SCM prefixes).
+    - Verify `BUILTIN_ALLOWED_TOOLS` no longer contains `WebFetch`/`WebSearch`.
+- **End-to-End Tests**:
+    - Invoke `/playwright-cli "fetch https://example.com"` in each agent platform and verify browser automation works.
+    - Verify `codebase-online-researcher` agent can perform web research using playwright-cli instead of WebFetch/WebSearch.
+    - Verify agents reference the playwright-cli skill in their system prompts.
+- **Cross-platform Tests**: Run `install.sh` on Linux/macOS and `install.ps1` on Windows to verify Playwright CLI installation works in binary distribution mode.
+
+## 9. Open Questions / Unresolved Issues
+
+All questions resolved:
+
+- [x] **Q1: Browser installation strategy** — **Resolved: Defer to first-use / explicit command.** Chromium browsers (~200-400MB) will NOT be auto-installed during `bun install`. Agents can run `bunx playwright install chromium` when needed. This keeps installation fast.
+- [x] **Q2: Bun compatibility** — **Resolved: Use `bunx playwright-cli`.** Aligns with the Bun-first project convention. Compatibility should be verified during implementation.
+- [x] **Q3: SKILL.md content source** — **Resolved: Use auto-generated SKILL.md from `playwright-cli install --skills`.** Official upstream content maintained by the Playwright team ensures accuracy and reduces maintenance burden.
+- [x] **Q4: Reviewer agent web access** — **Resolved: Remove web access from reviewer.** Code reviews should be based on local code context only. The `reviewer.md` agent will have `WebFetch`/`WebSearch` (and their equivalents) removed without playwright-cli replacement.
+- [x] **Q5: Binary installer Playwright bundling** — **Resolved: Download during installation.** `@playwright/cli` will be downloaded via `bun install -g` or `npm install -g` during `install.sh`/`install.ps1` execution. This keeps release artifacts small but requires bun/npm on the target system.
diff --git a/specs/streaming-architecture-event-bus-migration.md b/specs/streaming-architecture-event-bus-migration.md
new file mode 100644
index 0000000000..6bbcf48cf5
--- /dev/null
+++ b/specs/streaming-architecture-event-bus-migration.md
@@ -0,0 +1,908 @@
+# Streaming Architecture Migration: Callbacks to Event-Bus Pattern — Technical Design Document
+
+| Document Metadata      | Details           |
+| ---------------------- | ----------------- |
+| Author(s)              | lavaman131        |
+| Status                 | Draft (WIP)       |
+| Team / Owner           | lavaman131/atomic |
+| Created / Last Updated | 2026-02-26        |
+
+## 1. Executive Summary
+
+This RFC proposes migrating the Atomic TUI's streaming architecture from a **callback-based prop-threading model** to a **centralized event-bus pattern** inspired by OpenCode's SSE + event-bus + batched coalescing architecture. The current system threads streaming callbacks (`onChunk`, `onComplete`, `onMeta`) through React props and refs, maintains 10+ correlation Map/Set structures across 1,400+ lines of event handling code, and operates dual-path event delivery (stream-path vs hook-path) with complex echo suppression. The proposed event-bus architecture normalizes all three SDK streaming patterns (OpenCode AsyncGenerator, Claude AsyncIterable, Copilot EventEmitter) into a unified in-process publish-subscribe system with key-based coalescing and frame-aligned batching (16ms), reducing render churn and eliminating tight coupling between the orchestration layer and UI components. Workflow SDK streaming will share the same event backbone, enabling unified rendering of sub-agents, tool calls, and workflow output.
+
+**Research Reference:** [research/docs/2026-02-26-streaming-architecture-event-bus-migration.md](../research/docs/2026-02-26-streaming-architecture-event-bus-migration.md)
+
+## 2. Context and Motivation
+
+### 2.1 Current State
+
+The Atomic TUI uses a **multi-layered callback architecture** where streaming data flows from SDK clients through function callbacks to the UI layer:
+
+```
+SDK Client.stream() → AsyncIterable<AgentMessage>
+      ↓
+index.ts: for await (msg of stream)
+      ↓ (callbacks)
+  onChunk(text)  →  chat.tsx: setMessagesWindowed(applyStreamPartEvent)
+  onMeta(meta)   →  chat.tsx: setMessagesWindowed(applyStreamPartEvent)
+  onComplete()   →  chat.tsx: finalize streaming state
+      ↓
+SDK Client.on("tool.start") → state.toolStartHandler → chat.tsx: handleToolStart
+SDK Client.on("tool.complete") → state.toolCompleteHandler → chat.tsx: handleToolComplete
+SDK Client.on("subagent.start") → state.parallelAgentHandler → chat.tsx: updateAgentTree
+```
+
+**Key characteristics of current architecture:**
+
+- **Callback prop-threading**: Streaming callbacks registered via React props and stored as refs in `ChatUIState` (`src/ui/index.ts:167-176`)
+- **Dual-path event delivery**: Events arrive via both the AsyncIterable stream (stream-path) and SDK's native event system (hook-path), with `toolEventsViaHooks` flag preventing duplicates (`src/ui/index.ts:477-1293`)
+- **10+ correlation structures**: Maps and Sets tracking tool IDs, agent IDs, session ownership, and run counters (`src/ui/index.ts:479-563`)
+- **Per-event React state updates**: Each text delta triggers `setMessagesWindowed((prev) => prev.map(...))` mapping over all messages (`src/ui/chat.tsx:3551-3576`)
+- **100ms UI throttling**: Via `use-throttled-value.ts` hook
+- **Echo suppression**: 80+ lines of iterative string matching in the streaming loop (`src/ui/index.ts:1699-1765`)
+
+**SDK Event Normalization (already completed):** The codebase already has a unified event type system (`src/sdk/types.ts:297-310`) with SDK-agnostic UI components, normalized event data fields, and shared `Session`/`CodingAgentClient` contracts (ref: [sdk-ui-standardization-research](../research/docs/2026-02-12-sdk-ui-standardization-research.md)).
+
+### 2.2 The Problem
+
+- **Tight Coupling**: `src/ui/index.ts` (1,400+ lines of `subscribeToToolEvents()`) is tightly coupled to `src/ui/chat.tsx` via ref-based handler storage and callback registration, making both files difficult to modify independently.
+- **Render Churn**: Every streaming text delta, tool event, and thinking update triggers a full `setMessagesWindowed()` call that maps over all messages, creating unnecessary React reconciliation work.
+- **Dual-Path Complexity**: The stream-path vs hook-path split requires per-SDK configuration (`toolEventsViaHooks`) and creates race conditions when events arrive out of order (ref: [background-agents-sdk-pipeline](../research/docs/2026-02-23-258-background-agents-sdk-event-pipeline.md)).
+- **Correlation State Explosion**: 10+ Map/Set structures for tool/agent/session correlation create maintenance burden and fragile FIFO assumptions that break with concurrent same-tool calls.
+- **Workflow Isolation**: Workflow execution uses separate `context.addMessage()` and `context.setTodoItems()` calls rather than sharing the streaming backbone, preventing unified rendering (ref: [workflow-sdk-standardization](../research/docs/2026-02-25-workflow-sdk-standardization.md)).
+- **No Backpressure**: The current `EventEmitter` in `src/sdk/base-client.ts` dispatches synchronously with no mechanism to slow producers when consumers fall behind.
+
+## 3. Goals and Non-Goals
+
+### 3.1 Functional Goals
+
+- [ ] Implement a centralized, typed, in-process event bus that replaces callback prop-threading for all streaming events
+- [ ] Normalize all three SDK streaming patterns (OpenCode AsyncGenerator, Claude AsyncIterable, Copilot EventEmitter) into unified event bus publishers
+- [ ] Implement key-based coalescing to eliminate redundant state updates (e.g., rapid `message.part.updated` events collapse to latest)
+- [ ] Implement frame-aligned batching (16ms flush cycle) to reduce React render churn
+- [ ] Unify workflow SDK streaming with main chat streaming via the shared event bus
+- [ ] Eliminate dual-path event delivery by routing all events through the single event bus
+- [ ] Maintain all existing UI behaviors: echo suppression, thinking indicators, tool status, sub-agent tree, task lists
+- [ ] Preserve generation-based staleness guards and run ownership tracking
+- [ ] Support existing `StreamPartEvent` reducer pipeline (`applyStreamPartEvent()`) as the downstream consumer
+
+### 3.2 Non-Goals (Out of Scope)
+
+- [ ] Will NOT introduce a local HTTP server or SSE transport — the event bus is in-process only (no network layer like OpenCode's architecture)
+- [ ] Will NOT migrate from React to SolidJS — batching will integrate with React 18's automatic batching
+- [ ] Will NOT change the existing `AgentMessage` or `StreamPartEvent` type definitions — the event bus adds a layer above, not replaces
+- [ ] Will NOT refactor the parts pipeline (`stream-pipeline.ts`, `store.ts`) — it remains the downstream consumer
+- [ ] Will NOT rewrite SDK client implementations (`opencode.ts`, `claude.ts`, `copilot.ts`) from scratch — adapters consume their native streaming APIs and publish to the bus
+
+## 4. Proposed Solution (High-Level Design)
+
+### 4.1 System Architecture Diagram
+
+```mermaid
+%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#f8f9fa','primaryTextColor':'#2c3e50','primaryBorderColor':'#4a5568','lineColor':'#4a90e2','secondaryColor':'#ffffff','tertiaryColor':'#e9ecef','background':'#f5f7fa','mainBkg':'#f8f9fa','nodeBorder':'#4a5568','clusterBkg':'#ffffff','clusterBorder':'#cbd5e0','edgeLabelBackground':'#ffffff'}}}%%
+
+flowchart TB
+    classDef sdk fill:#5a67d8,stroke:#4c51bf,stroke-width:2.5px,color:#ffffff,font-weight:600,font-size:13px
+    classDef bus fill:#e53e3e,stroke:#c53030,stroke-width:3px,color:#ffffff,font-weight:700,font-size:14px
+    classDef adapter fill:#667eea,stroke:#5a67d8,stroke-width:2.5px,color:#ffffff,font-weight:600,font-size:13px
+    classDef batch fill:#dd6b20,stroke:#c05621,stroke-width:2.5px,color:#ffffff,font-weight:600,font-size:13px
+    classDef consumer fill:#48bb78,stroke:#38a169,stroke-width:2.5px,color:#ffffff,font-weight:600,font-size:13px
+    classDef ui fill:#4a90e2,stroke:#357abd,stroke-width:2.5px,color:#ffffff,font-weight:600,font-size:13px
+
+    subgraph SDKLayer["◆ SDK Layer"]
+        direction LR
+        OpenCode["<b>OpenCode SDK</b><br>AsyncGenerator"]:::sdk
+        Claude["<b>Claude Agent SDK</b><br>AsyncIterable"]:::sdk
+        Copilot["<b>Copilot SDK</b><br>EventEmitter"]:::sdk
+        Workflow["<b>Workflow SDK</b><br>AsyncGenerator"]:::sdk
+    end
+
+    subgraph AdapterLayer["◆ SDK Adapters (Normalizers)"]
+        direction LR
+        OCA["<b>OpenCode<br>Adapter</b>"]:::adapter
+        CLA["<b>Claude<br>Adapter</b>"]:::adapter
+        CPA["<b>Copilot<br>Adapter</b>"]:::adapter
+        WFA["<b>Workflow<br>Adapter</b>"]:::adapter
+    end
+
+    EventBus(("<b>Event Bus</b><br>Typed Pub/Sub<br>In-Process")):::bus
+
+    subgraph BatchLayer["◆ Batching & Coalescing"]
+        direction LR
+        Queue["<b>Event Queue</b><br>Double Buffer"]:::batch
+        Coalesce["<b>Key-Based<br>Coalescing</b>"]:::batch
+        Flush["<b>Frame-Aligned<br>Flush (16ms)</b>"]:::batch
+    end
+
+    subgraph ConsumerLayer["◆ Event Consumers"]
+        direction LR
+        StreamReducer["<b>Stream Pipeline<br>Reducer</b><br>applyStreamPartEvent()"]:::consumer
+        CorrelationSvc["<b>Correlation<br>Service</b><br>Tool/Agent Mapping"]:::consumer
+        EchoSuppressor["<b>Echo<br>Suppression</b>"]:::consumer
+    end
+
+    subgraph UILayer["◆ UI Components"]
+        direction LR
+        Transcript["<b>Transcript<br>View</b>"]:::ui
+        AgentTree["<b>Parallel<br>Agents Tree</b>"]:::ui
+        TaskList["<b>Task List<br>Panel</b>"]:::ui
+        ToolResult["<b>Tool Result<br>Display</b>"]:::ui
+    end
+
+    OpenCode --> OCA
+    Claude --> CLA
+    Copilot --> CPA
+    Workflow --> WFA
+
+    OCA -->|"publish"| EventBus
+    CLA -->|"publish"| EventBus
+    CPA -->|"publish"| EventBus
+    WFA -->|"publish"| EventBus
+
+    EventBus -->|"enqueue"| Queue
+    Queue --> Coalesce
+    Coalesce --> Flush
+
+    Flush -->|"batched dispatch"| StreamReducer
+    Flush -->|"batched dispatch"| CorrelationSvc
+    Flush -->|"batched dispatch"| EchoSuppressor
+
+    StreamReducer --> Transcript
+    CorrelationSvc --> AgentTree
+    CorrelationSvc --> TaskList
+    StreamReducer --> ToolResult
+
+    style SDKLayer fill:#ffffff,stroke:#cbd5e0,stroke-width:2px,color:#2d3748,stroke-dasharray:8 4,font-weight:600
+    style AdapterLayer fill:#ffffff,stroke:#cbd5e0,stroke-width:2px,color:#2d3748,stroke-dasharray:8 4,font-weight:600
+    style BatchLayer fill:#ffffff,stroke:#cbd5e0,stroke-width:2px,color:#2d3748,stroke-dasharray:8 4,font-weight:600
+    style ConsumerLayer fill:#ffffff,stroke:#cbd5e0,stroke-width:2px,color:#2d3748,stroke-dasharray:8 4,font-weight:600
+    style UILayer fill:#ffffff,stroke:#cbd5e0,stroke-width:2px,color:#2d3748,stroke-dasharray:8 4,font-weight:600
+```
+
+### 4.2 Architectural Pattern
+
+We are adopting a **centralized in-process Event Bus with batched dispatch** pattern, inspired by OpenCode's SSE + event-bus architecture (ref: [streaming-architecture-event-bus-migration](../research/docs/2026-02-26-streaming-architecture-event-bus-migration.md), Section 2) but adapted for Atomic's pure-TUI context (no network transport needed).
+
+**Key architectural decisions:**
+
+1. **In-process bus** instead of SSE transport — Atomic has no server; events flow within a single Node.js/Bun process
+2. **SDK adapters** normalize three heterogeneous streaming APIs into a single `BusEvent` type
+3. **Key-based coalescing** (borrowed from OpenCode's `global-sdk.tsx:46-84`) eliminates redundant state updates
+4. **Frame-aligned batching** (16ms flush) reduces React reconciliation to ~60fps cadence
+5. **Correlation as a service** — extracted from the monolithic `subscribeToToolEvents()` into a standalone event bus consumer
+
+### 4.3 Key Components
+
+| Component                | Responsibility                                                    | Technology                                                           | Justification                                                         |
+| ------------------------ | ----------------------------------------------------------------- | -------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| `EventBus`               | Typed pub/sub with topic-based routing, replaces `EventEmitter`   | Custom TypeScript class with Zod schema validation                   | Matches OpenCode's `Bus` system with `BusEvent.define()` typed events |
+| `SDK Adapters`           | Normalize SDK streaming APIs to `BusEvent`, replace `client.on()` | Per-SDK adapter classes                                              | Single event pathway — adapters are the only SDK event consumers      |
+| `BatchDispatcher`        | Queue, coalesce, and flush events at 16ms                         | Double-buffer + `setTimeout`                                         | Matches OpenCode's `global-sdk.tsx` batching with double-buffer swap  |
+| `CorrelationService`     | Tool ID ↔ Agent ID mapping, session ownership                     | Replaces `subscribeToToolEvents()` entirely                          | Decouples correlation logic from UI; testable in isolation            |
+| `EchoSuppressor`         | Post-task duplicate text filtering                                | Replaces inline echo suppression in `handleStreamMessage()`          | Isolates 80+ lines of string matching into testable unit              |
+| `StreamPipelineConsumer` | Translates `BusEvent` → `StreamPartEvent` for existing reducer    | Replaces callback-based `handleChunk`/`handleMeta`/`handleToolStart` | Single `setMessages()` call per batch instead of per-event            |
+
+## 5. Detailed Design
+
+### 5.1 Event Bus Core
+
+#### 5.1.1 Bus Event Type Definitions
+
+The event bus uses a **Zod-validated typed event system** with discriminated unions, modeled after OpenCode's `BusEvent.define(name, zodSchema)` pattern (ref: [streaming-architecture-event-bus-migration](../research/docs/2026-02-26-streaming-architecture-event-bus-migration.md), Section 2.1). This replaces the existing `EventType` union in `src/sdk/types.ts` — the old `EventType` and `EventEmitter` are deleted:
+
+```typescript
+// src/events/bus-events.ts
+
+/** All event types that flow through the bus */
+type BusEventType =
+    // Text streaming
+    | "stream.text.delta"
+    | "stream.text.complete"
+    // Thinking / reasoning
+    | "stream.thinking.delta"
+    | "stream.thinking.complete"
+    // Tool lifecycle
+    | "stream.tool.start"
+    | "stream.tool.complete"
+    // Sub-agent lifecycle
+    | "stream.agent.start"
+    | "stream.agent.update"
+    | "stream.agent.complete"
+    // Session lifecycle
+    | "stream.session.start"
+    | "stream.session.idle"
+    | "stream.session.error"
+    // Workflow events
+    | "workflow.step.start"
+    | "workflow.step.complete"
+    | "workflow.task.update"
+    // UI control events
+    | "stream.permission.requested"
+    | "stream.human_input_required"
+    | "stream.skill.invoked"
+    // Metadata
+    | "stream.usage";
+
+/** Base event envelope */
+interface BusEvent<T extends BusEventType = BusEventType> {
+    type: T;
+    sessionId: string;
+    runId: number;
+    timestamp: number;
+    data: BusEventDataMap[T];
+}
+
+/** Maps event types to their data payloads */
+interface BusEventDataMap {
+    "stream.text.delta": { delta: string; messageId: string };
+    "stream.text.complete": { messageId: string; fullText: string };
+    "stream.thinking.delta": {
+        delta: string;
+        sourceKey: string;
+        messageId: string;
+    };
+    "stream.thinking.complete": { sourceKey: string; durationMs: number };
+    "stream.tool.start": {
+        toolId: string;
+        toolName: string;
+        toolInput: Record<string, unknown>;
+        sdkCorrelationId?: string;
+        parentAgentId?: string;
+    };
+    "stream.tool.complete": {
+        toolId: string;
+        toolName: string;
+        toolResult: string;
+        success: boolean;
+        error?: string;
+        sdkCorrelationId?: string;
+    };
+    "stream.agent.start": {
+        agentId: string;
+        agentType: string;
+        task: string;
+        isBackground: boolean;
+        sdkCorrelationId?: string;
+    };
+    "stream.agent.update": {
+        agentId: string;
+        currentTool?: string;
+        toolUses?: number;
+    };
+    "stream.agent.complete": {
+        agentId: string;
+        success: boolean;
+        result?: string;
+        error?: string;
+    };
+    "workflow.step.start": {
+        workflowId: string;
+        nodeId: string;
+        nodeName: string;
+    };
+    "workflow.step.complete": {
+        workflowId: string;
+        nodeId: string;
+        status: "success" | "error" | "skipped";
+        result?: unknown;
+    };
+    "workflow.task.update": {
+        workflowId: string;
+        tasks: Array<{ id: string; title: string; status: string }>;
+    };
+    // ... remaining event data types follow same pattern
+}
+```
+
+#### 5.1.2 Bus Implementation
+
+```typescript
+// src/events/event-bus.ts
+
+import { z } from "zod";
+
+/** Define a typed bus event with Zod schema validation (OpenCode pattern) */
+function defineBusEvent<T extends string, S extends z.ZodType>(
+    type: T,
+    schema: S,
+) {
+    return {
+        type,
+        schema,
+        parse: (data: unknown) => schema.parse(data),
+    } as const;
+}
+
+type BusHandler<T extends BusEventType> = (event: BusEvent<T>) => void;
+type WildcardHandler = (event: BusEvent) => void;
+
+class AtomicEventBus {
+    private handlers = new Map<BusEventType, Set<BusHandler<BusEventType>>>();
+    private wildcardHandlers = new Set<WildcardHandler>();
+
+    /** Subscribe to a specific event type. Returns unsubscribe function. */
+    on<T extends BusEventType>(type: T, handler: BusHandler<T>): () => void;
+
+    /** Subscribe to all events (OpenCode's Bus.subscribeAll pattern). Returns unsubscribe function. */
+    onAll(handler: WildcardHandler): () => void;
+
+    /** Publish an event — validates with Zod schema, dispatches to all matching subscribers. */
+    publish<T extends BusEventType>(event: BusEvent<T>): void;
+
+    /** Remove all handlers and reset bus state. */
+    clear(): void;
+}
+```
+
+**Design rationale:** The bus mirrors OpenCode's `Bus` system — `publish()` validates event data via Zod schemas before dispatch (catching type errors at runtime), `onAll()` enables wildcard subscription (used by BatchDispatcher and debug logging), and `on()` enables topic-filtered subscription. The old `EventEmitter` in `base-client.ts` is deleted — this is the sole event system.
+
+#### 5.1.3 Coalescing Key Function
+
+Adapted from OpenCode's `global-sdk.tsx:46-84` (ref: [streaming-architecture-event-bus-migration](../research/docs/2026-02-26-streaming-architecture-event-bus-migration.md), Section 2.2):
+
+```typescript
+// src/events/coalescing.ts
+
+/**
+ * Generate a coalescing key for an event. Events with the same key
+ * within a batching window will be coalesced (only latest retained).
+ * Returns undefined for events that must never be coalesced (e.g., text deltas).
+ */
+function coalescingKey(event: BusEvent): string | undefined {
+    switch (event.type) {
+        // Text deltas are NEVER coalesced — each delta is additive
+        case "stream.text.delta":
+        case "stream.thinking.delta":
+            return undefined;
+
+        // Tool/agent state updates coalesce by entity ID
+        case "stream.tool.start":
+        case "stream.tool.complete":
+            return `tool:${event.data.toolId}`;
+        case "stream.agent.update":
+            return `agent.update:${event.data.agentId}`;
+        case "stream.agent.start":
+            return `agent.start:${event.data.agentId}`;
+
+        // Session status coalesces by session
+        case "stream.session.start":
+        case "stream.session.idle":
+        case "stream.session.error":
+            return `session:${event.sessionId}`;
+
+        // Workflow task list coalesces per workflow
+        case "workflow.task.update":
+            return `workflow.tasks:${event.data.workflowId}`;
+
+        // Usage stats coalesce per session
+        case "stream.usage":
+            return `usage:${event.sessionId}`;
+
+        default:
+            return undefined;
+    }
+}
+```
+
+**Key insight from OpenCode research:** Text deltas must NEVER be coalesced because each delta is additive (appended to content). State-replacement events (tool status, agent updates, session status) should coalesce because only the latest state matters.
+
+#### 5.1.4 Batch Dispatcher
+
+```typescript
+// src/events/batch-dispatcher.ts
+
+const FLUSH_INTERVAL_MS = 16; // ~60 FPS alignment
+
+class BatchDispatcher {
+    private queue: BusEvent[] = [];
+    private buffer: BusEvent[] = [];
+    private coalesced = new Map<string, number>(); // key → index in queue
+    private lastFlush = 0;
+    private flushTimer: ReturnType<typeof setTimeout> | null = null;
+    private consumers: Array<(events: BusEvent[]) => void> = [];
+
+    /** Enqueue an event for batched dispatch */
+    enqueue(event: BusEvent): void {
+        const key = coalescingKey(event);
+        if (key !== undefined) {
+            const existingIdx = this.coalesced.get(key);
+            if (existingIdx !== undefined) {
+                this.queue[existingIdx] = event; // Overwrite with latest
+                return;
+            }
+            this.coalesced.set(key, this.queue.length);
+        }
+        this.queue.push(event);
+        this.scheduleFlush();
+    }
+
+    /** Register a consumer that receives batched events */
+    addConsumer(consumer: (events: BusEvent[]) => void): () => void;
+
+    private scheduleFlush(): void {
+        if (this.flushTimer !== null) return;
+        const elapsed = Date.now() - this.lastFlush;
+        if (elapsed >= FLUSH_INTERVAL_MS) {
+            this.flush();
+        } else {
+            this.flushTimer = setTimeout(
+                () => this.flush(),
+                FLUSH_INTERVAL_MS - elapsed,
+            );
+        }
+    }
+
+    private flush(): void {
+        this.flushTimer = null;
+        // Double-buffer swap (no allocation)
+        const events = this.queue;
+        this.queue = this.buffer;
+        this.buffer = events;
+        this.queue.length = 0;
+        this.coalesced.clear();
+        this.lastFlush = Date.now();
+
+        // Dispatch batched events to all consumers
+        // React 18 automatic batching will group state updates within each consumer
+        for (const consumer of this.consumers) {
+            consumer(events);
+        }
+    }
+
+    dispose(): void;
+}
+```
+
+**React 18 integration:** React 18 automatically batches state updates within event handlers, `setTimeout`, and `Promise` callbacks. The `flush()` function triggers all state updates within a single synchronous loop, which React 18 will batch into a single render. This replaces SolidJS's explicit `batch()` (ref: research Open Question #3).
+
+### 5.2 SDK Adapters
+
+Each adapter consumes the SDK's native streaming API and publishes normalized `BusEvent`s directly to the event bus. Adapters are the **sole consumers** of SDK events — there is no secondary callback path or `client.on()` subscription outside the adapter.
+
+#### 5.2.1 Adapter Interface
+
+```typescript
+// src/events/adapters/types.ts
+
+interface SDKStreamAdapter {
+    /** Consume the SDK stream and publish all events to the bus. This is the only path for SDK events. */
+    startStreaming(
+        session: Session,
+        message: string,
+        options: { runId: number; messageId: string; agent?: string },
+    ): Promise<void>;
+
+    /** Clean up any adapter-internal state */
+    dispose(): void;
+}
+```
+
+#### 5.2.2 Adapter Implementations
+
+**OpenCode Adapter** — Consumes `AsyncGenerator` from `sdk.event.subscribe()` and publishes to bus. Follows OpenCode's own `Bus.subscribeAll()` → SSE → client emitter pattern, but collapses the SSE transport since we are in-process:
+
+- `message.part.delta` → `stream.text.delta`
+- `message.part.updated` → discriminates by part type into `stream.tool.start`, `stream.tool.complete`, `stream.agent.start`, `stream.agent.complete`
+- `session.status` → `stream.session.start` / `stream.session.idle` / `stream.session.error`
+- All lifecycle events (tool, sub-agent) are consumed within the adapter — no external `client.on()` subscriptions exist
+
+**Claude Adapter** — Consumes `AsyncIterable` from `session.stream()` and publishes to bus:
+
+- `AgentMessage { type: "text" }` → `stream.text.delta`
+- `AgentMessage { type: "thinking" }` → `stream.thinking.delta`
+- `AgentMessage { type: "tool_use" }` → `stream.tool.start`
+- `AgentMessage { type: "tool_result" }` → `stream.tool.complete`
+- Claude hooks (`PreToolUse`, `SubagentStart`) are registered within the adapter and published as `stream.agent.*` events
+- The adapter handles thinking source lifecycle internally (create/update/close sources, compute duration)
+
+**Copilot Adapter** — Registers `session.on()` handlers within the adapter and publishes to bus:
+
+- `assistant.message_delta` → `stream.text.delta`
+- `tool.execution_start` → `stream.tool.start`
+- `tool.execution_complete` → `stream.tool.complete`
+- `subagent.started` → `stream.agent.start`
+- `subagent.completed` → `stream.agent.complete`
+- **Backpressure handling**: Internal bounded queue with high-water mark. When the BatchDispatcher is flushing, incoming events are queued in the adapter and drained on next tick. If queue exceeds high-water mark, oldest non-delta events are dropped with a warning.
+- `dispose()` unregisters all `session.on()` handlers
+
+**Workflow Adapter** — Consumes `AsyncGenerator<StepResult>` from `streamGraph()` and publishes to bus:
+
+- `StepResult { status: "running" }` → `workflow.step.start`
+- `StepResult { status: "completed" }` → `workflow.step.complete`
+- Task list updates → `workflow.task.update`
+- Sub-agents spawned within workflow nodes publish their events to the same bus instance — no separate `context.addMessage()` / `context.setTodoItems()` calls
+
+### 5.3 Correlation Service (Replaces `subscribeToToolEvents`)
+
+The `subscribeToToolEvents()` function (`src/ui/index.ts:477-1481`) and its ~1,000 lines of correlation logic are **deleted entirely**. The `CorrelationService` replaces it as a standalone bus consumer that processes batched events:
+
+```typescript
+// src/events/consumers/correlation-service.ts
+
+class CorrelationService {
+    // All correlation state previously scattered across subscribeToToolEvents()
+    private sdkToolIdMap = new Map<string, string>();
+    private toolCallToAgentMap = new Map<string, string>();
+    private subagentSessionToAgentId = new Map<string, string>();
+    private pendingTaskEntries: PendingTaskEntry[] = [];
+    private ownedSessionIds = new Set<string>();
+    private toolIdToRunMap = new Map<string, number>();
+    private activeRunId: number | null = null;
+
+    /** Process a batch of events, resolving correlations and enriching events */
+    processBatch(events: BusEvent[]): EnrichedBusEvent[];
+
+    /** Register a new run, clearing all correlation state from the previous run */
+    startRun(runId: number, sessionId: string): void;
+
+    /** Check if an event belongs to the active run */
+    isOwnedEvent(event: BusEvent): boolean;
+
+    /** Reset all state — called on stream end, error, or abort */
+    reset(): void;
+}
+
+/** Enriched event with resolved correlation data */
+interface EnrichedBusEvent extends BusEvent {
+    resolvedToolId?: string;
+    resolvedAgentId?: string;
+    isSubagentTool?: boolean;
+    suppressFromMainChat?: boolean;
+}
+```
+
+**What is deleted:**
+
+- `subscribeToToolEvents()` function and all inline handler closures
+- `ChatUIState.toolStartHandler`, `toolCompleteHandler`, `skillInvokedHandler`, `permissionRequestHandler`, `askUserQuestionHandler` refs
+- `registerToolStartHandler`, `registerToolCompleteHandler` registration functions and their corresponding props
+- Dual-path event delivery (`toolEventsViaHooks` flag)
+- `sdkToolIdMap`, `toolCallToAgentMap`, `subagentSessionToAgentId`, `pendingTaskEntries`, `toolNameToId`, `toolNameToIds` inline Maps
+- Run ownership tracking via `state.runCounter` and `activeRunId` in closures
+
+### 5.4 Echo Suppression Service (Replaces inline suppression)
+
+The 80+ lines of echo suppression logic in `handleStreamMessage()` (`src/ui/index.ts:1699-1765`) are **deleted**. The `EchoSuppressor` replaces it as a bus consumer that filters text deltas before they reach the stream pipeline:
+
+```typescript
+// src/events/consumers/echo-suppressor.ts
+
+class EchoSuppressor {
+    private suppressTargets: string[] = []; // FIFO of expected echoes
+    private accumulator = "";
+
+    /** Register a tool result that may be echoed by the SDK */
+    expectEcho(resultText: string): void;
+
+    /** Filter a text delta, returning the non-echoed portion (may be empty) */
+    filterDelta(delta: string): string;
+}
+```
+
+### 5.5 Stream Pipeline Consumer (Replaces callback handlers)
+
+Replaces `handleChunk()`, `handleMeta()`, `handleToolStart()`, `handleToolComplete()` in `chat.tsx`. Instead of per-event callbacks triggering individual `setMessagesWindowed()` calls, a single consumer processes the entire batch:
+
+```typescript
+// src/events/consumers/stream-pipeline-consumer.ts
+
+class StreamPipelineConsumer {
+    /** Convert a batch of BusEvents into StreamPartEvents and apply to message state */
+    processBatch(
+        events: EnrichedBusEvent[],
+        setMessages: React.Dispatch<SetStateAction<ChatMessage[]>>,
+        activeMessageId: string,
+    ): void {
+        // Translate each event to StreamPartEvent
+        const partEvents: StreamPartEvent[] = events
+            .filter((e) => !e.suppressFromMainChat)
+            .map((e) => this.toStreamPartEvent(e))
+            .filter(Boolean);
+
+        if (partEvents.length === 0) return;
+
+        // Apply all events in a single setMessages call
+        // React 18 batches this into one render
+        setMessages((prev) =>
+            prev.map((msg) => {
+                if (msg.id !== activeMessageId) return msg;
+                let updated = msg;
+                for (const event of partEvents) {
+                    updated = applyStreamPartEvent(updated, event);
+                }
+                return updated;
+            }),
+        );
+    }
+
+    private toStreamPartEvent(event: EnrichedBusEvent): StreamPartEvent | null {
+        switch (event.type) {
+            case "stream.text.delta":
+                return { type: "text-delta", delta: event.data.delta };
+            case "stream.thinking.delta":
+                return {
+                    type: "thinking-meta",
+                    thinkingText: event.data.delta,
+                    thinkingSourceKey: event.data.sourceKey,
+                    // ...
+                };
+            case "stream.tool.start":
+                return {
+                    type: "tool-start",
+                    toolId: event.data.toolId,
+                    toolName: event.data.toolName,
+                    toolInput: event.data.toolInput,
+                };
+            case "stream.tool.complete":
+                return {
+                    type: "tool-complete",
+                    toolId: event.data.toolId,
+                    toolResult: event.data.toolResult,
+                    success: event.data.success,
+                };
+            default:
+                return null;
+        }
+    }
+}
+```
+
+**What is deleted:**
+
+- `handleChunk()` callback in `chat.tsx:3551-3576`
+- `handleMeta()` callback in `chat.tsx:3720-3748`
+- `handleToolStart()` callback in `chat.tsx:2266-2354`
+- `handleToolComplete()` callback in `chat.tsx:2361-2476`
+- `handleComplete()` callback in `chat.tsx:3578-3717`
+- Handler registration via `useEffect` in `chat.tsx:2490-2506`
+- `registerToolStartHandler` / `registerToolCompleteHandler` props
+- Individual `setMessagesWindowed()` calls per event — replaced by single batched `setMessages()` call
+
+### 5.6 Data Flow (End-to-End)
+
+Modeled after OpenCode's end-to-end flow (ref: [streaming-architecture-event-bus-migration](../research/docs/2026-02-26-streaming-architecture-event-bus-migration.md), Section 2.4 "End-to-End Flow"):
+
+```
+OpenCode's pattern:
+  LLM SSE chunks → TransformStream → LanguageModelV2StreamPart
+  → SessionProcessor → Bus.publish(PartUpdated/PartDelta)
+  → GlobalBus → SSE endpoint → Client SSE reader
+  → Event queue (with coalescing) → batch(flush)
+  → Emitter → Component subscribers → Single render
+
+Atomic's adapted pattern (in-process, no SSE transport):
+  SDK native stream (AsyncIterable/AsyncGenerator/EventEmitter)
+  → SDK Adapter → Bus.publish(BusEvent)
+  → BatchDispatcher.enqueue() → coalescingKey() → coalesce/append
+  → flush() at 16ms boundary → double-buffer swap
+  → CorrelationService.processBatch() → enriched events
+  → EchoSuppressor.filterDelta() → filtered text
+  → StreamPipelineConsumer.processBatch() → single setMessages() call
+  → React 18 automatic batching → single reconciliation → UI render
+```
+
+### 5.7 React Hook Integration
+
+```typescript
+// src/ui/hooks/use-event-bus.ts
+
+/** Hook to access the singleton event bus instance */
+function useEventBus(): AtomicEventBus;
+
+/** Hook to subscribe to specific bus events with automatic cleanup on unmount */
+function useBusSubscription<T extends BusEventType>(
+    type: T,
+    handler: (event: BusEvent<T>) => void,
+    deps: DependencyList,
+): void;
+
+/**
+ * Hook that owns the streaming lifecycle for a message.
+ * Replaces the callback registration pattern (registerToolStartHandler, etc.)
+ * and the streaming state management (use-streaming-state.ts).
+ */
+function useStreamConsumer(options: {
+    messageId: string;
+    runId: number;
+    setMessages: React.Dispatch<SetStateAction<ChatMessage[]>>;
+}): {
+    startStreaming: (session: Session, message: string) => Promise<void>;
+    stopStreaming: () => void;
+    isStreaming: boolean;
+};
+```
+
+**What is deleted:**
+
+- `use-streaming-state.ts` hook — streaming lifecycle managed by `useStreamConsumer` + bus events
+- `use-throttled-value.ts` hook — 100ms throttle replaced by 16ms BatchDispatcher flush
+- `use-message-queue.ts` hook — message queuing replaced by BatchDispatcher's internal queue
+- Callback registration props (`registerToolStartHandler`, `registerToolCompleteHandler`, etc.)
+- `streamGenerationRef` staleness guard — replaced by `runId` on `BusEvent` envelope
+
+### 5.8 Workflow Event Integration
+
+Workflows emit events onto the same bus, enabling unified rendering:
+
+```typescript
+// src/workflows/event-adapter.ts
+
+class WorkflowEventAdapter {
+    constructor(private bus: AtomicEventBus) {}
+
+    /** Wrap workflow execution to emit bus events */
+    async *streamWithEvents<TState>(
+        workflow: CompiledGraph<TState>,
+        initialState: TState,
+        options: { workflowId: string; runId: number; sessionId: string },
+    ): AsyncGenerator<StepResult<TState>> {
+        this.bus.publish({
+            type: "workflow.step.start",
+            sessionId: options.sessionId,
+            runId: options.runId,
+            timestamp: Date.now(),
+            data: {
+                workflowId: options.workflowId,
+                nodeId: "root",
+                nodeName: workflow.name,
+            },
+        });
+
+        for await (const step of workflow.stream(initialState)) {
+            // Publish step events
+            this.bus.publish({
+                type:
+                    step.status === "running"
+                        ? "workflow.step.start"
+                        : "workflow.step.complete",
+                sessionId: options.sessionId,
+                runId: options.runId,
+                timestamp: Date.now(),
+                data: {
+                    workflowId: options.workflowId,
+                    nodeId: step.nodeId,
+                    nodeName: step.nodeId,
+                    status:
+                        step.status === "completed"
+                            ? "success"
+                            : step.status === "error"
+                              ? "error"
+                              : "skipped",
+                    result: step.result,
+                },
+            });
+
+            yield step;
+        }
+    }
+}
+```
+
+This means sub-agents spawned within workflow nodes will have their tool events, text deltas, and lifecycle events flow through the same bus as main chat — achieving the unified streaming backbone described in the research question (ref: [streaming-architecture-event-bus-migration](../research/docs/2026-02-26-streaming-architecture-event-bus-migration.md), research question).
+
+## 6. Alternatives Considered
+
+| Option                                                     | Pros                                                            | Cons                                                                            | Reason for Rejection                                                                                          |
+| ---------------------------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| **A: Local SSE Server** (full OpenCode port)               | Proven at scale, enables external tooling                       | Adds HTTP server complexity to pure TUI, latency overhead, port conflicts       | Atomic is a single-process TUI — network transport is unnecessary overhead                                    |
+| **B: RxJS Observables**                                    | Rich operator library, built-in backpressure                    | Large dependency (~45KB), learning curve, complex subscription management       | Over-engineered for the use case; simple pub/sub with batching suffices                                       |
+| **C: `mitt` library**                                      | Tiny (200B), proven, type-safe                                  | No built-in batching or coalescing, would need wrapping anyway                  | Would still need BatchDispatcher on top — custom bus is equally simple                                        |
+| **D: Incremental refactor** (keep callbacks, add batching) | Lower risk                                                      | Doesn't solve coupling, dual-path, or workflow isolation; maintains two systems | Rejected — half-measures perpetuate complexity; clean removal is required                                     |
+| **E: In-process Event Bus** (Selected)                     | Minimal overhead, fits TUI model, enables coalescing + batching | Custom code to maintain                                                         | **Selected:** Best balance of decoupling, performance, and implementation complexity for a single-process TUI |
+
+## 7. Cross-Cutting Concerns
+
+### 7.1 Security and Privacy
+
+- **No change**: The event bus is entirely in-process; no data leaves the process boundary. No new network endpoints are introduced.
+- **Event data**: Bus events contain the same data currently flowing through callbacks — no new PII exposure.
+- **Memory**: Events are short-lived (16ms batching window); the double-buffer pattern ensures prompt GC eligibility.
+
+### 7.2 Observability Strategy
+
+- **Debug logging**: The event bus will support a debug subscriber that logs all events to a debug file when `ATOMIC_DEBUG=1` is set, replacing scattered `console.debug` calls in `subscribeToToolEvents()`.
+- **Metrics**: Track `events_per_flush` (histogram), `coalesce_ratio` (counter of coalesced vs total), `flush_duration_ms` (histogram) — exposed via existing telemetry infrastructure.
+- **Event replay**: The debug subscriber can dump events to JSONL for post-hoc debugging of streaming issues.
+
+### 7.3 Performance
+
+- **Render reduction**: Current architecture renders per-event (~every text delta). With 16ms batching and coalescing, renders are capped at ~60fps with redundant state updates eliminated.
+- **Memory**: Double-buffer swap avoids array allocation on each flush. Coalescing map is cleared per flush (bounded memory).
+- **CPU**: Coalescing key computation is O(1) per event. Batch flush iterates events once. Overall complexity is O(n) per flush where n is events in the window.
+- **Backpressure**: Copilot SDK's push-based events are buffered in the adapter with a configurable high-water mark. If the buffer exceeds the mark, oldest non-delta events are dropped with a warning log.
+
+### 7.4 Testing Strategy
+
+- **Unit tests**: `EventBus`, `BatchDispatcher`, `CorrelationService`, `EchoSuppressor` are all pure TypeScript classes testable without React.
+- **Integration tests**: Synthetic event sequences verifying end-to-end flow from `BusEvent` publish to `StreamPartEvent` application.
+- **Regression tests**: Existing SDK event parity tests (`src/sdk/unified-event-parity.test.ts`, `src/sdk/clients/opencode.events.test.ts`) will be extended to verify adapter output matches expected bus events.
+- **Visual regression**: Manual verification that streaming UI behavior (thinking indicators, tool panels, agent tree) is unchanged.
+
+## 8. Migration, Rollout, and Testing
+
+### 8.1 Deployment Strategy — Phased Migration
+
+#### Phase 1: Core Infrastructure
+
+Build the event bus core without changing any existing code paths:
+
+- [ ] Implement `AtomicEventBus` class with typed pub/sub
+- [ ] Implement `BatchDispatcher` with coalescing and 16ms flush
+- [ ] Implement `coalescingKey()` function
+- [ ] Write unit tests for bus, dispatcher, and coalescing
+- [ ] Wire bus as a singleton via React context provider
+
+**Verification:** Unit tests pass; bus can publish/subscribe in isolation.
+
+#### Phase 2: SDK Adapters & Consumer Services
+
+Build adapters as the sole SDK event consumers. Simultaneously build consumer services and wire the full pipeline:
+
+- [ ] Implement OpenCode adapter — consumes `sdk.event.subscribe()`, publishes to bus
+- [ ] Implement Claude adapter — consumes `session.stream()`, publishes to bus
+- [ ] Implement Copilot adapter — registers `session.on()` handlers internally, publishes to bus
+- [ ] Implement `CorrelationService` — replaces `subscribeToToolEvents()` correlation logic
+- [ ] Implement `EchoSuppressor` — replaces inline echo suppression in `handleStreamMessage()`
+- [ ] Implement `StreamPipelineConsumer` — replaces `handleChunk`, `handleMeta`, `handleToolStart`, `handleToolComplete` callbacks
+- [ ] Wire consumers to `BatchDispatcher`
+- [ ] Write integration tests: SDK mock → adapter → bus → consumer → `StreamPartEvent` output
+
+**Verification:** Integration tests pass end-to-end with synthetic SDK event sequences.
+
+#### Phase 3: Legacy Removal & Wiring
+
+Delete all callback infrastructure and wire the event bus as the sole streaming path:
+
+- [ ] Delete `subscribeToToolEvents()` function from `src/ui/index.ts`
+- [ ] Delete `ChatUIState` handler refs (`toolStartHandler`, `toolCompleteHandler`, `skillInvokedHandler`, `permissionRequestHandler`, `askUserQuestionHandler`)
+- [ ] Delete `handleChunk()`, `handleMeta()`, `handleComplete()`, `handleToolStart()`, `handleToolComplete()` callbacks from `chat.tsx`
+- [ ] Delete handler registration props and `useEffect` registration blocks from `chat.tsx`
+- [ ] Delete `EventEmitter` class from `base-client.ts`
+- [ ] Delete `EventType` union, `EventDataMap`, `EventHandler` types from `src/sdk/types.ts` (replaced by `BusEventType` and `BusEventDataMap`)
+- [ ] Delete `use-throttled-value.ts` hook (replaced by 16ms batch flush)
+- [ ] Delete `use-streaming-state.ts` hook (replaced by `useStreamConsumer`)
+- [ ] Delete `use-message-queue.ts` hook (replaced by BatchDispatcher queue)
+- [ ] Delete `toolEventsViaHooks` flag and dual-path event delivery logic
+- [ ] Delete `streamGenerationRef` staleness guard (replaced by `runId` on BusEvent)
+- [ ] Delete `suppressPostTaskResults` FIFO in `handleStreamMessage()` (replaced by EchoSuppressor)
+- [ ] Rewrite `handleStreamMessage()` to: get adapter for active SDK → call `adapter.startStreaming()` → done (all events flow through bus)
+- [ ] Wire `AtomicEventBus` singleton via React context provider
+- [ ] Wire `useStreamConsumer` hook in chat component
+
+**Verification:** Full test suite passes. Manual testing across all three SDKs confirms identical UI behavior.
+
+#### Phase 4: Workflow Integration
+
+Connect workflow streaming to the event bus:
+
+- [ ] Implement `WorkflowEventAdapter`
+- [ ] Modify `executeWorkflow()` to publish bus events for step start/complete lifecycle
+- [ ] Modify sub-agent spawning in workflows to publish `stream.agent.*` events to the bus
+- [ ] Delete `context.addMessage()` / `context.setTodoItems()` — replaced by `workflow.step.*` and `workflow.task.update` bus events
+- [ ] Verify Ralph workflow and custom workflows render correctly via bus events
+
+**Verification:** Workflow execution produces correct UI output via event bus.
+
+### 8.2 Data Migration Plan
+
+- **No data migration required**: This is a runtime architecture change. No persistent data formats change.
+
+### 8.3 Test Plan
+
+- **Unit Tests**: `EventBus`, `BatchDispatcher`, `CorrelationService`, `EchoSuppressor`, `coalescingKey()`, each SDK adapter
+- **Integration Tests**: End-to-end event flow from SDK mock → adapter → bus → consumer → `StreamPartEvent` output
+- **Adapter Tests**: Each adapter tested with mock SDK streams verifying correct `BusEvent` output for all event types
+- **Manual E2E**: Test each SDK (OpenCode, Claude, Copilot) with real streaming sessions, verifying text rendering, tool panels, thinking indicators, agent tree, task lists
+
+## 9. Resolved Design Decisions
+
+- [x] **Q1 — Flush timing mechanism:** **`setTimeout`** — works natively in Bun/Node.js, sufficient for 16ms cadence. No `requestAnimationFrame` polyfill needed since the TUI runs outside browser contexts.
+
+- [x] **Q2 — Coalescing for tool events:** **Preserve both start + complete events** — tool lifecycle events (`stream.tool.start`, `stream.tool.complete`) are never coalesced or collapsed, even within the same 16ms window. Both are always emitted for UI animation and state consistency (e.g., showing brief "running" indicator).
+
+- [x] **Q3 — Feature flag / backward compatibility:** **No feature flag, no backward compatibility, no deprecation period.** This is a clean breaking migration. All callback infrastructure is deleted in Phase 3. There is no toggle, no fallback path, no "old mode." The event bus is the sole streaming architecture from the moment Phase 3 lands.
+
+- [x] **Q4 — Existing EventEmitter:** **Deleted entirely.** The `EventEmitter` class in `base-client.ts`, the `EventType` union in `types.ts`, and all `client.on()` / `client.emit()` call sites are removed. The `AtomicEventBus` is the single event system. SDK adapters publish directly to the bus. Non-streaming consumers (session lifecycle, etc.) subscribe to the bus via `bus.on()` or `useBusSubscription()` hook.
+
+- [x] **Q5 — Workflow event granularity:** **Coarse events only** — workflow nodes emit `workflow.step.start` and `workflow.step.complete` events. No per-state-mutation events. This keeps event volume low and aligns with the step-based workflow execution model. Debug visibility can be achieved via the event bus debug subscriber logging.
diff --git a/specs/streaming-event-bus-spec-compliance-remediation.md b/specs/streaming-event-bus-spec-compliance-remediation.md
new file mode 100644
index 0000000000..a2e4eb4032
--- /dev/null
+++ b/specs/streaming-event-bus-spec-compliance-remediation.md
@@ -0,0 +1,666 @@
+# Streaming Event Bus Spec Compliance Remediation — Technical Design Document
+
+| Document Metadata      | Details           |
+| ---------------------- | ----------------- |
+| Author(s)              | lavaman131        |
+| Status                 | In Review (RFC)   |
+| Team / Owner           | lavaman131/atomic |
+| Created / Last Updated | 2026-02-26        |
+
+## 1. Executive Summary
+
+This RFC proposes remediation of all gaps, bugs, and deviations identified in the [Streaming Event Bus Spec Compliance Audit](../research/docs/2026-02-26-streaming-event-bus-spec-audit.md) against the [Streaming Architecture Event Bus Migration spec](../specs/streaming-architecture-event-bus-migration.md). The audit found **2 high-severity bugs** (adapter `dispose()` null references), **7 intentional simplifications** that deviate from the spec's contract, **8 missing features** (run ownership tracking, streaming lifecycle hooks, debug tooling), and **test coverage gaps** (missing Zod validation tests, no Copilot/Workflow adapter tests). This document specifies the exact changes needed to bring the `src/events/` implementation into full spec compliance while preserving the existing architectural decisions that were validated against OpenCode patterns.
+
+**Research References:**
+
+- [Spec Compliance Audit](../research/docs/2026-02-26-streaming-event-bus-spec-audit.md)
+- [OpenCode Event Bus Patterns](../research/docs/2026-02-26-opencode-event-bus-patterns.md)
+- [Streaming Architecture Event Bus Migration (original spec)](../specs/streaming-architecture-event-bus-migration.md)
+
+## 2. Context and Motivation
+
+### 2.1 Current State
+
+The `src/events/` directory implements the core event bus infrastructure specified in the [Streaming Architecture Event Bus Migration spec](../specs/streaming-architecture-event-bus-migration.md). The compliance audit ([research/docs/2026-02-26-streaming-event-bus-spec-audit.md](../research/docs/2026-02-26-streaming-event-bus-spec-audit.md)) confirmed that the **foundational components are correctly implemented**: all 19 bus event types, the `AtomicEventBus` pub/sub core, coalescing key logic, `BatchDispatcher` with double-buffer/16ms flush, `EchoSuppressor`, React hooks, and the provider pattern all match the spec closely.
+
+However, the audit identified the following categories of issues:
+
+- **2 high-severity bugs** in adapter `dispose()` methods causing `TypeError` crashes during active streaming cancellation
+- **7 intentional API simplifications** where implementation differs from the spec's contract
+- **8 features specified but not yet implemented** (run ownership, streaming lifecycle hooks, debug tooling)
+- **Test coverage gaps** leaving critical paths unverified
+
+### 2.2 The Problem
+
+- **Crash Risk**: Calling `dispose()` during active streaming in OpenCode and Claude adapters causes a `TypeError: Cannot read properties of null` due to a missing null guard on `abortController` ([audit bug table](../research/docs/2026-02-26-streaming-event-bus-spec-audit.md#-bugs-found)). Two tests are **SKIPPED** documenting this.
+- **Incomplete Run Ownership**: The `CorrelationService` uses a simplified `enrich()`/`registerTool()`/`reset()` API instead of the spec's full `processBatch()`/`startRun()`/`isOwnedEvent()` contract. This means stale events from previous runs cannot be filtered at the correlation level — consumers must manually check `event.runId` ([audit deviation table](../research/docs/2026-02-26-streaming-event-bus-spec-audit.md#️-deviates-from-spec-intentional-simplifications)).
+- **No Streaming Lifecycle Control**: The `useStreamConsumer` hook returns only `{ resetConsumers }` instead of the spec's `{ startStreaming, stopStreaming, isStreaming }`, forcing consumers to manage adapter lifecycle separately ([audit Section 7](../research/docs/2026-02-26-streaming-event-bus-spec-audit.md#7-react-integration--section-57)).
+- **Claude Adapter Gap**: Tool events are not handled in the Claude adapter — a comment says they are "handled at higher level", violating the spec's rule that adapters should be the **sole consumers** of SDK events ([audit Section 5.2](../research/docs/2026-02-26-streaming-event-bus-spec-audit.md#52-claude-adapter-claude-adapterts-138-lines)).
+- **No Debug Replay**: The debug subscriber only logs to console; the original spec's Section 7.2 calls for event replay and JSONL dump capabilities, but the implementation should follow OpenCode's proven file-based log retention pattern ([audit Section 8](../research/docs/2026-02-26-streaming-event-bus-spec-audit.md#8-debug-subscriber-debug-subscriberts--section-72)).
+- **Unverified Zod Validation**: `publish()` validates events via Zod schemas, but no tests verify the failure path (schema rejection, early return, warning log) ([audit bug table](../research/docs/2026-02-26-streaming-event-bus-spec-audit.md#-bugs-found)).
+
+## 3. Goals and Non-Goals
+
+### 3.1 Functional Goals
+
+- [ ] Fix both adapter `dispose()` null reference bugs and unskip the corresponding tests
+- [ ] Expand `CorrelationService` API to include run ownership tracking (`startRun`, `isOwnedEvent`, `activeRunId`)
+- [ ] Add `startStreaming`/`stopStreaming`/`isStreaming` to the `useStreamConsumer` hook
+- [ ] Handle tool and agent events in the Claude adapter (making it the sole consumer of Claude SDK events)
+- [ ] Replace console-only debug subscriber with file-based JSONL event logging with log rotation (modeled after OpenCode's `packages/opencode/src/util/log.ts`)
+- [ ] Add Zod validation failure tests to `event-bus.test.ts`
+- [ ] Add test coverage for `CopilotStreamAdapter` and `WorkflowEventAdapter`
+- [ ] Align `StreamPipelineConsumer` batch processing flow with the enrichment pipeline described in the spec
+
+### 3.2 Non-Goals (Out of Scope)
+
+- [ ] Will NOT change the architectural pattern (in-process pub/sub, double-buffer batching, coalescing) — these are validated and correct
+- [ ] Will NOT refactor the callback-based `onStreamParts()` pattern in `StreamPipelineConsumer` to the spec's direct `setMessages()` dispatch — the callback pattern is intentionally more flexible ([audit validation](../research/docs/2026-02-26-streaming-event-bus-spec-audit.md#key-design-decisions-validated-against-opencode))
+- [ ] Will NOT convert the `WorkflowEventAdapter` from method-based to AsyncGenerator pattern — the method-based approach is simpler for discrete events ([audit validation](../research/docs/2026-02-26-streaming-event-bus-spec-audit.md#key-design-decisions-validated-against-opencode))
+- [ ] Will NOT rewrite existing passing tests — only add missing coverage and unskip fixed tests
+- [ ] Will NOT change `BusEventType` definitions or `BusEventDataMap` payloads — all 19 types are confirmed correct
+
+## 4. Proposed Solution (High-Level Design)
+
+### 4.1 System Architecture Diagram
+
+The remediation does not change the overall architecture. The event flow remains:
+
+```
+SDK Stream/Events
+       ↓
+SDK Adapter (opencode/claude/copilot/workflow)
+       ↓
+bus.publish(busEvent)       ← Zod validation here
+       ↓
+AtomicEventBus
+       ↓
+bus.onAll() → dispatcher.enqueue()    ← wireConsumers() sets this up
+       ↓
+BatchDispatcher (16ms flush, coalescing, double-buffer)
+       ↓
+correlation.enrich(event)  → EnrichedBusEvent
+       ↓
+StreamPipelineConsumer.processBatch(enrichedEvents)
+       ↓
+onStreamParts callback → StreamPartEvent[]
+       ↓
+React component state update
+```
+
+Changes are **internal** to existing components — the inter-component contracts remain the same. The key additions are:
+
+1. **Null guards** in adapter error handlers (bug fix)
+2. **Run ownership state** in `CorrelationService` (API expansion)
+3. **Adapter lifecycle management** in `useStreamConsumer` (hook enhancement)
+4. **Tool/agent event handling** in Claude adapter (feature addition)
+5. **File-based JSONL event logging** in debug subscriber with OpenCode-style rotation (feature addition)
+
+### 4.2 Architectural Pattern
+
+No change. The centralized in-process Event Bus with batched dispatch pattern remains as specified in the [original spec Section 4.2](../specs/streaming-architecture-event-bus-migration.md#42-architectural-pattern).
+
+### 4.3 Key Components
+
+| Component                      | Change Type         | Description                                                                         |
+| ------------------------------ | ------------------- | ----------------------------------------------------------------------------------- |
+| `opencode-adapter.ts`          | Bug Fix             | Add null guard to `abortController` in error handler                                |
+| `claude-adapter.ts`            | Bug Fix + Feature   | Add null guard + handle tool/agent events in adapter                                |
+| `correlation-service.ts`       | API Expansion       | Add `startRun()`, `isOwnedEvent()`, `activeRunId`, `processBatch()`                 |
+| `hooks.ts` (useStreamConsumer) | Enhancement         | Add `startStreaming`, `stopStreaming`, `isStreaming`                                |
+| `debug-subscriber.ts`          | Rewrite             | Replace console-only logging with file-based JSONL log retention (OpenCode pattern) |
+| `event-bus.test.ts`            | Test Addition       | Add Zod validation failure path tests                                               |
+| `adapters.test.ts`             | Test Fix + Addition | Unskip dispose tests, add Copilot/Workflow adapter tests                            |
+
+## 5. Detailed Design
+
+### 5.1 Bug Fix: Adapter `dispose()` Null Reference
+
+**Files:** `src/events/adapters/opencode-adapter.ts`, `src/events/adapters/claude-adapter.ts`
+
+**Root Cause:** When `dispose()` is called during active streaming, it aborts and nullifies `this.abortController`. The stream's error handler then tries to access `this.abortController.signal.aborted`, which throws `TypeError: Cannot read properties of null`.
+
+**Fix:** Add a null guard before accessing `abortController.signal` in the catch block of the streaming loop.
+
+```typescript
+// BEFORE (both adapters):
+} catch (error) {
+  if (!this.abortController.signal.aborted) {
+    this.publishSessionError(runId, error);
+  }
+}
+
+// AFTER (both adapters):
+} catch (error) {
+  if (this.abortController && !this.abortController.signal.aborted) {
+    this.publishSessionError(runId, error);
+  }
+}
+```
+
+**Test Changes:** Unskip the two `dispose() stops processing via AbortController` tests in `adapters.test.ts` (lines ~252-286 and ~520-554). Change `test.skip(...)` to `test(...)`.
+
+**Ref:** [Audit Bug Table](../research/docs/2026-02-26-streaming-event-bus-spec-audit.md#-bugs-found)
+
+### 5.2 CorrelationService API Expansion
+
+**File:** `src/events/consumers/correlation-service.ts`
+
+**Current API** (simplified):
+
+```typescript
+class CorrelationService {
+    enrich(event: BusEvent): EnrichedBusEvent;
+    registerTool(toolId: string, agentId: string, isSubagent?: boolean): void;
+    reset(): void;
+    // State: toolToAgent, subAgentTools, mainAgentId
+}
+```
+
+**Expanded API** (matching spec Section 5.3):
+
+```typescript
+class CorrelationService {
+    // Existing (preserved):
+    enrich(event: BusEvent): EnrichedBusEvent;
+    registerTool(toolId: string, agentId: string, isSubagent?: boolean): void;
+    reset(): void;
+
+    // New — Run lifecycle:
+    startRun(runId: number, sessionId: string): void;
+    isOwnedEvent(event: BusEvent): boolean;
+    get activeRunId(): number | null;
+
+    // New — Batch processing:
+    processBatch(events: BusEvent[]): EnrichedBusEvent[];
+
+    // New — State (additions):
+    private ownedSessionIds: Set<string>;
+    private toolIdToRunMap: Map<string, number>;
+}
+```
+
+**Implementation Details:**
+
+1. **`startRun(runId, sessionId)`**: Sets `activeRunId`, adds `sessionId` to `ownedSessionIds`, calls `reset()` to clear previous run state. This replaces the manual `runId` tracking that currently happens external to the service.
+
+2. **`isOwnedEvent(event)`**: Returns `true` if `event.runId === this.activeRunId` or `event.sessionId` is in `ownedSessionIds`. Used by consumers to filter stale events from previous runs.
+
+3. **`activeRunId` getter**: Exposes the current run ID for external queries (e.g., staleness guards).
+
+4. **`processBatch(events)`**: Convenience method that maps `events.map(e => this.enrich(e))`. The existing single-event `enrich()` method is preserved for backward compatibility with `wireConsumers.ts`.
+
+5. **`ownedSessionIds`**: Tracks session IDs registered via `startRun()`. Used by `isOwnedEvent()` for session-level ownership checks.
+
+6. **`toolIdToRunMap`**: Maps tool IDs to the run that spawned them. Populated during `enrich()` when processing `stream.tool.start` events.
+
+**Backward Compatibility:** The existing `enrich()`, `registerTool()`, and `reset()` APIs are preserved with identical behavior. New methods are additive. `wireConsumers.ts` continues to use `enrich()` without modification.
+
+**Ref:** [Audit Deviation — CorrelationService API](../research/docs/2026-02-26-streaming-event-bus-spec-audit.md#61-correlationservice-correlation-servicets--section-53)
+
+### 5.3 `useStreamConsumer` Hook Enhancement
+
+**File:** `src/events/hooks.ts`
+
+**Current Return Type:**
+
+```typescript
+{ resetConsumers: () => void }
+```
+
+**Enhanced Return Type:**
+
+```typescript
+{
+  resetConsumers: () => void;       // Preserved
+  startStreaming: (
+    adapter: SDKStreamAdapter,
+    session: Session,
+    message: string,
+    options: StreamAdapterOptions
+  ) => Promise<void>;
+  stopStreaming: () => void;
+  isStreaming: boolean;
+}
+```
+
+**Implementation Details:**
+
+1. **`startStreaming(adapter, session, message, options)`**: Stores the adapter reference, sets `isStreaming = true`, calls `resetConsumers()` for clean state, then delegates to `adapter.startStreaming(session, message, options)`. On completion or error, sets `isStreaming = false`.
+
+2. **`stopStreaming()`**: Calls `adapter.dispose()` on the stored adapter reference, sets `isStreaming = false`, nullifies the adapter ref.
+
+3. **`isStreaming`**: React state (`useState`) toggled by `startStreaming`/`stopStreaming`. Provides reactive streaming status for UI components.
+
+4. **Adapter parameter**: The adapter is passed as a parameter to `startStreaming()` rather than being created internally. This preserves the current pattern where the calling component decides which SDK adapter to use based on the active session type. The hook manages the adapter's lifecycle after receiving it.
+
+**Cleanup:** On unmount, the hook calls `stopStreaming()` to ensure proper disposal.
+
+**Ref:** [Audit Deviation — useStreamConsumer](../research/docs/2026-02-26-streaming-event-bus-spec-audit.md#usestreamconsumer-hook-hooksts211-242)
+
+### 5.4 Claude Adapter Tool/Agent Event Handling
+
+**File:** `src/events/adapters/claude-adapter.ts`
+
+**Current Behavior:** The Claude adapter only processes `text` and `thinking` message types from the stream. A comment says tool events are "handled at higher level."
+
+**Required Behavior (per spec Section 5.2):** Adapters should be the **sole consumers** of SDK events. The Claude adapter must handle:
+
+- `AgentMessage { type: "tool_use" }` → publish `stream.tool.start` with `toolId`, `toolName`, `toolInput`
+- `AgentMessage { type: "tool_result" }` → publish `stream.tool.complete` with `toolId`, `toolResult`, `success`
+- Claude hooks (`PreToolUse`, `SubagentStart`) → publish `stream.agent.start` / `stream.agent.complete`
+
+**Implementation:**
+
+Add cases to the stream message processing switch/case:
+
+```typescript
+case "tool_use":
+  this.bus.publish({
+    type: "stream.tool.start",
+    sessionId, runId,
+    timestamp: Date.now(),
+    data: {
+      toolId: message.id,
+      toolName: message.name,
+      toolInput: message.input,
+      sdkCorrelationId: message.correlationId,
+    },
+  });
+  break;
+
+case "tool_result":
+  this.bus.publish({
+    type: "stream.tool.complete",
+    sessionId, runId,
+    timestamp: Date.now(),
+    data: {
+      toolId: message.tool_use_id,
+      toolName: message.toolName ?? "unknown",
+      toolResult: typeof message.content === "string"
+        ? message.content
+        : JSON.stringify(message.content),
+      success: !message.is_error,
+      error: message.is_error ? String(message.content) : undefined,
+      sdkCorrelationId: message.correlationId,
+    },
+  });
+  break;
+```
+
+Agent lifecycle events should be captured via Claude Agent SDK hooks registered within the adapter, following the pattern described in [spec Section 5.2.2](../specs/streaming-architecture-event-bus-migration.md#522-adapter-implementations).
+
+**Ref:** [Audit Deviation — Claude adapter tool events](../research/docs/2026-02-26-streaming-event-bus-spec-audit.md#52-claude-adapter-claude-adapterts-138-lines)
+
+### 5.5 Debug Subscriber: File-Based JSONL Event Log Retention
+
+**File:** `src/events/debug-subscriber.ts`
+
+**Current:** Only `console.debug` logging when `ATOMIC_DEBUG=1`.
+
+**Replacement:** File-based JSONL event logging with automatic rotation, modeled after OpenCode's `packages/opencode/src/util/log.ts` pattern ([DeepWiki: OpenCode logging](https://deepwiki.com/anomalyco/opencode)).
+
+#### 5.5.1 Design (Mirroring OpenCode)
+
+OpenCode's logging system (`packages/opencode/src/util/log.ts`) uses:
+
+- **Directory**: `~/.local/share/opencode/log/`
+- **File naming**: `YYYY-MM-DDTHHMMSS.log` (ISO timestamp, colons stripped)
+- **Rotation**: File-count-based, retains 10 most recent files
+- **Cleanup**: `Bun.Glob("????-??-??T??????.log")` scans for log files, deletes oldest beyond limit
+- **Writing**: `Bun.file(path).writer()` with synchronous `writer.write(msg)` + `writer.flush()`
+- **Dev mode**: Uses fixed `dev.log` filename
+- **Format**: `[ISO_TIMESTAMP] +[TIME_DIFF_MS] [TAGS] [MESSAGE]`
+
+Atomic's event log system adapts this pattern for structured event data:
+
+| Aspect       | OpenCode                                        | Atomic Event Logger                        |
+| ------------ | ----------------------------------------------- | ------------------------------------------ |
+| Directory    | `~/.local/share/opencode/log/`                  | `~/.local/share/atomic/log/events/`        |
+| File format  | Plain text (`[TIMESTAMP] +[DIFF] [TAGS] [MSG]`) | JSONL (one JSON object per event per line) |
+| File naming  | `YYYY-MM-DDTHHMMSS.log`                         | `YYYY-MM-DDTHHMMSS.events.jsonl`           |
+| Rotation     | 10 most recent files                            | 10 most recent files                       |
+| Cleanup glob | `????-??-??T??????.log`                         | `????-??-??T??????.events.jsonl`           |
+| Activation   | `--log-level DEBUG`                             | `ATOMIC_DEBUG=1`                           |
+| Writing      | `Bun.file().writer()`                           | `Bun.file().writer()`                      |
+| Dev mode     | `dev.log`                                       | `dev.events.jsonl`                         |
+
+#### 5.5.2 Implementation
+
+```typescript
+// src/events/debug-subscriber.ts
+
+import { join } from "path";
+import { homedir } from "os";
+
+const LOG_DIR = join(homedir(), ".local", "share", "atomic", "log", "events");
+const MAX_LOG_FILES = 10;
+
+/** JSONL log entry format — one per line in the log file */
+interface EventLogEntry {
+    ts: string; // ISO timestamp
+    type: string; // BusEventType
+    sessionId: string;
+    runId: number;
+    data: unknown; // Event payload
+}
+
+/**
+ * Clean up old event log files, retaining the most recent MAX_LOG_FILES.
+ * Mirrors OpenCode's cleanup() in packages/opencode/src/util/log.ts.
+ */
+async function cleanup(dir: string): Promise<void> {
+    const glob = new Bun.Glob("????-??-??T??????.events.jsonl");
+    const files = await Array.fromAsync(
+        glob.scan({ cwd: dir, absolute: true }),
+    );
+    // Glob returns files in lexicographic order (oldest first due to timestamp naming)
+    if (files.length <= MAX_LOG_FILES) return;
+    const filesToDelete = files.slice(0, -MAX_LOG_FILES);
+    await Promise.all(
+        filesToDelete.map((file) =>
+            Bun.file(file)
+                .exists()
+                .then((exists) =>
+                    exists
+                        ? require("fs/promises")
+                              .unlink(file)
+                              .catch(() => {})
+                        : undefined,
+                ),
+        ),
+    );
+}
+
+/**
+ * Initialize the event log file writer.
+ * Mirrors OpenCode's Log.init() in packages/opencode/src/util/log.ts.
+ */
+async function initEventLog(options?: { dev?: boolean }): Promise<{
+    write: (event: BusEvent) => void;
+    close: () => void;
+    logPath: string;
+}> {
+    await require("fs/promises").mkdir(LOG_DIR, { recursive: true });
+    await cleanup(LOG_DIR);
+
+    const filename = options?.dev
+        ? "dev.events.jsonl"
+        : new Date().toISOString().split(".")[0].replace(/:/g, "") +
+          ".events.jsonl";
+
+    const logPath = join(LOG_DIR, filename);
+    const logFile = Bun.file(logPath);
+    // Truncate if reusing (dev mode)
+    if (options?.dev) {
+        await require("fs/promises")
+            .truncate(logPath)
+            .catch(() => {});
+    }
+
+    const writer = logFile.writer();
+
+    const write = (event: BusEvent): void => {
+        const entry: EventLogEntry = {
+            ts: new Date(event.timestamp).toISOString(),
+            type: event.type,
+            sessionId: event.sessionId,
+            runId: event.runId,
+            data: event.data,
+        };
+        writer.write(JSON.stringify(entry) + "\n");
+        writer.flush();
+    };
+
+    const close = (): void => {
+        writer.end();
+    };
+
+    return { write, close, logPath };
+}
+
+/**
+ * Attach a file-based debug subscriber to the event bus.
+ * When ATOMIC_DEBUG=1, all events are written to a JSONL log file
+ * with automatic rotation (10 most recent files retained).
+ *
+ * Also retains console.debug logging for real-time visibility.
+ */
+function attachDebugSubscriber(bus: AtomicEventBus): Promise<{
+    unsubscribe: () => void;
+    logPath: string | null;
+}> {
+    if (process.env.ATOMIC_DEBUG !== "1") {
+        return Promise.resolve({ unsubscribe: () => {}, logPath: null });
+    }
+
+    return initEventLog({ dev: process.env.NODE_ENV === "development" }).then(
+        ({ write, close, logPath }) => {
+            const unsubBus = bus.onAll((event) => {
+                // File-based JSONL logging
+                write(event);
+                // Retain console.debug for real-time visibility
+                const preview = JSON.stringify(event.data).slice(0, 100);
+                console.debug(
+                    `[EventBus] ${event.type} run=${event.runId} ${preview}`,
+                );
+            });
+
+            const unsubscribe = (): void => {
+                unsubBus();
+                close();
+            };
+
+            return { unsubscribe, logPath };
+        },
+    );
+}
+```
+
+#### 5.5.3 Log Replay Utility
+
+Since events are persisted as JSONL files, replay is a simple file read — no in-memory buffer needed:
+
+```typescript
+/**
+ * Read and parse events from a JSONL event log file.
+ * Replaces the in-memory EventReplayBuffer with file-based replay.
+ */
+async function readEventLog(
+    logPath: string,
+    filter?: (entry: EventLogEntry) => boolean,
+): Promise<EventLogEntry[]> {
+    const content = await Bun.file(logPath).text();
+    const entries = content
+        .trim()
+        .split("\n")
+        .filter(Boolean)
+        .map((line) => JSON.parse(line) as EventLogEntry);
+    return filter ? entries.filter(filter) : entries;
+}
+
+/**
+ * List all available event log files, most recent first.
+ */
+async function listEventLogs(): Promise<string[]> {
+    const glob = new Bun.Glob("????-??-??T??????.events.jsonl");
+    const files = await Array.fromAsync(
+        glob.scan({ cwd: LOG_DIR, absolute: true }),
+    );
+    return files.reverse(); // Most recent first
+}
+```
+
+**Advantages over in-memory replay buffer:**
+
+- Events persist across process restarts (critical for debugging crashes)
+- No memory cap concerns — disk is plentiful
+- JSONL files can be analyzed with standard tools (`jq`, `grep`, text editors)
+- Rotation is automatic and bounded (10 files max)
+- Matches OpenCode's proven pattern
+
+**Ref:** [Audit Deviation — Debug subscriber](../research/docs/2026-02-26-streaming-event-bus-spec-audit.md#8-debug-subscriber-debug-subscriberts--section-72), [OpenCode Log Implementation](https://deepwiki.com/anomalyco/opencode)
+
+### 5.6 Test Coverage Additions
+
+#### 5.6.1 Zod Validation Failure Tests
+
+**File:** `src/events/event-bus.test.ts`
+
+Add tests verifying:
+
+- Publishing an event with invalid payload (wrong types) → event is NOT dispatched, warning is logged
+- Publishing an event with missing required fields → early return, no handler invocation
+- Publishing an event with extra fields → Zod strips extras (passthrough behavior check)
+
+```typescript
+test("publish() rejects event with invalid payload schema", () => {
+    const handler = mock(() => {});
+    bus.on("stream.text.delta", handler);
+
+    const invalidEvent = {
+        type: "stream.text.delta",
+        sessionId: "s1",
+        runId: 1,
+        timestamp: Date.now(),
+        data: { delta: 123 }, // Should be string
+    };
+
+    bus.publish(invalidEvent as BusEvent<"stream.text.delta">);
+    expect(handler).not.toHaveBeenCalled();
+});
+```
+
+#### 5.6.2 Copilot Adapter Tests
+
+**File:** `src/events/adapters/adapters.test.ts`
+
+Add test suite for `CopilotStreamAdapter` covering:
+
+- Text delta events → `stream.text.delta` + `stream.text.complete`
+- Tool events → `stream.tool.start` / `stream.tool.complete`
+- Agent events → `stream.agent.start` / `stream.agent.complete`
+- Backpressure behavior (buffer exceeding `MAX_BUFFER_SIZE`)
+- `dispose()` cleanup
+
+#### 5.6.3 Workflow Adapter Tests
+
+**File:** `src/events/adapters/adapters.test.ts`
+
+Add test suite for `WorkflowEventAdapter` covering:
+
+- `publishStepStart()` → publishes `workflow.step.start` with correct payload
+- `publishStepComplete()` → publishes `workflow.step.complete` with status
+- `publishTaskUpdate()` → publishes `workflow.task.update` with task array
+- `publishAgentStart()`/`publishAgentUpdate()`/`publishAgentComplete()` → correct `stream.agent.*` events
+
+## 6. Alternatives Considered
+
+| Option                                                                 | Pros                                      | Cons                                                          | Reason for Rejection                                                                                                                                                                   |
+| ---------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **A: Keep simplified CorrelationService**                              | No refactoring risk, currently functional | Stale event filtering burden on consumers, diverges from spec | Rejected — run ownership is needed for multi-agent correctness                                                                                                                         |
+| **B: Merge adapter + hook lifecycle** (adapter created inside hook)    | Cleaner API, hook owns full lifecycle     | Couples hook to adapter factory, harder to test               | Rejected — passing adapter as parameter preserves testability                                                                                                                          |
+| **C: Replace StreamPipelineConsumer callback with direct setMessages** | Matches spec exactly                      | Couples consumer to React, harder to test                     | Rejected — callback pattern validated as intentionally better ([audit](../research/docs/2026-02-26-streaming-event-bus-spec-audit.md#key-design-decisions-validated-against-opencode)) |
+| **D: Full CorrelationService rewrite**                                 | Clean slate, optimal API                  | High risk, existing tests depend on current behavior          | Rejected — additive expansion preserves backward compatibility                                                                                                                         |
+
+## 7. Cross-Cutting Concerns
+
+### 7.1 Security and Privacy
+
+- **No change**: All fixes are internal to the in-process event bus. No new data leaves the process boundary.
+- **JSONL dump**: Debug event dumps contain the same data already visible in console.debug. Files are written to user-controlled paths only when explicitly invoked.
+
+### 7.2 Observability Strategy
+
+- **File-based event logging**: When `ATOMIC_DEBUG=1`, all bus events are written to JSONL files at `~/.local/share/atomic/log/events/`. Automatic rotation retains the 10 most recent log files. Mirrors OpenCode's `packages/opencode/src/util/log.ts` pattern.
+- **Event replay**: `readEventLog(path, filter?)` reads persisted JSONL files for post-hoc analysis. Events persist across process restarts, enabling crash debugging.
+- **JSONL format**: Each line is a self-contained JSON object (`{ts, type, sessionId, runId, data}`), compatible with `jq`, `grep`, and standard log analysis tools.
+- **Console logging**: `console.debug` retained alongside file logging for real-time visibility during development.
+- **Existing metrics**: `BatchMetrics` (totalFlushed, totalCoalesced, totalDropped, flushCount) remain unchanged.
+
+### 7.3 Scalability and Capacity Planning
+
+- **Log file storage**: 10 JSONL files × ~1-5MB each ≈ 10-50MB max disk usage. Log rotation ensures bounded growth.
+- **Write performance**: `Bun.file().writer()` with synchronous `flush()` (same as OpenCode) adds negligible latency per event — I/O is buffered by the OS.
+- **No memory overhead**: Unlike an in-memory replay buffer, file-based logging adds no persistent memory pressure. Only the writer handle is kept in memory.
+- **No performance regression**: Bug fixes are single null-guard additions. CorrelationService additions are O(1) lookups. No hot-path changes.
+
+## 8. Migration, Rollout, and Testing
+
+### 8.1 Deployment Strategy
+
+#### Phase 1: Bug Fixes
+
+- [ ] Add null guard to `opencode-adapter.ts` error handler (~line 197)
+- [ ] Add null guard to `claude-adapter.ts` error handler (~line 111)
+- [ ] Unskip both `dispose()` tests in `adapters.test.ts`
+- [ ] Run test suite to verify fixes
+
+**Verification:** Both previously-skipped tests pass. No regressions in existing adapter tests.
+
+#### Phase 2: CorrelationService Expansion
+
+- [ ] Add `startRun(runId, sessionId)` method
+- [ ] Add `isOwnedEvent(event)` method
+- [ ] Add `activeRunId` getter
+- [ ] Add `processBatch(events)` convenience method
+- [ ] Add `ownedSessionIds` and `toolIdToRunMap` internal state
+- [ ] Add unit tests for all new methods in `correlation-service.test.ts`
+
+**Verification:** New tests pass. Existing `enrich()`/`registerTool()`/`reset()` tests unchanged and passing.
+
+#### Phase 3: Claude Adapter Tool Events
+
+- [ ] Add `tool_use` → `stream.tool.start` mapping
+- [ ] Add `tool_result` → `stream.tool.complete` mapping
+- [ ] Register Claude hooks for agent lifecycle events within the adapter
+- [ ] Remove "handled at higher level" comment
+- [ ] Add tests for tool/agent event handling in Claude adapter section of `adapters.test.ts`
+
+**Verification:** Claude adapter tests cover text, thinking, tool, and agent event types. Integration test with Claude adapter produces complete event stream.
+
+#### Phase 4: Hook Enhancement + Debug Subscriber
+
+- [ ] Add `startStreaming`, `stopStreaming`, `isStreaming` to `useStreamConsumer` return
+- [ ] Add cleanup on unmount
+- [ ] Add tests for streaming lifecycle in `hooks.test.ts`
+- [ ] Implement `initEventLog()` with JSONL file writer (mirrors OpenCode's `Log.init()`)
+- [ ] Implement `cleanup()` with `Bun.Glob` rotation retaining 10 most recent files (mirrors OpenCode's `cleanup()`)
+- [ ] Implement `readEventLog()` and `listEventLogs()` replay utilities
+- [ ] Enhance `attachDebugSubscriber()` to write JSONL files + retain console.debug
+- [ ] Add tests for log rotation, JSONL format, and replay utilities
+
+**Verification:** Hook tests verify startStreaming/stopStreaming lifecycle and isStreaming state. Debug subscriber tests verify JSONL file creation, log rotation at 10 files, and replay utility correctness.
+
+#### Phase 5: Test Coverage
+
+- [ ] Add Zod validation failure tests to `event-bus.test.ts`
+- [ ] Add `CopilotStreamAdapter` test suite to `adapters.test.ts`
+- [ ] Add `WorkflowEventAdapter` test suite to `adapters.test.ts`
+- [ ] Verify all previously-skipped tests are now enabled
+
+**Verification:** Full test suite passes with zero skipped tests. All adapter types have test coverage.
+
+### 8.2 Data Migration Plan
+
+- **No data migration required**: All changes are runtime behavior modifications.
+
+### 8.3 Test Plan
+
+- **Unit Tests**: `CorrelationService` (new methods), `initEventLog()`, `cleanup()` (log rotation), `readEventLog()` (replay), Zod validation failure paths
+- **Adapter Tests**: Claude adapter (tool/agent events), Copilot adapter (full suite), Workflow adapter (full suite), dispose() fix verification (unskipped tests)
+- **Hook Tests**: `useStreamConsumer` streaming lifecycle (`startStreaming`, `stopStreaming`, `isStreaming` state transitions, unmount cleanup)
+- **Integration Tests**: Existing `integration.test.ts` (8 scenarios) should continue passing with no modifications
+- **Regression**: Run `bun test` to verify zero regressions across entire `src/events/` test suite
+
+## 9. Resolved Design Decisions
+
+- [x] **Q1 — CorrelationService `processBatch` semantics:** **Simple map wrapper** — `processBatch()` is `events.map(e => this.enrich(e))`. Run lifecycle is managed externally via explicit `startRun()` calls, not auto-detected within batches. This aligns with OpenCode's pattern where stale events are filtered via coalescing (key-based deduplication) at the frontend level rather than batch-level run boundary detection. ([OpenCode reference](https://deepwiki.com/anomalyco/opencode))
+
+- [x] **Q2 — `useStreamConsumer` adapter parameter pattern:** **Adapter as parameter** — `startStreaming(adapter, session, message, options)` accepts the adapter instance from the caller. This mirrors OpenCode's context provider pattern (where the SDK client is provided via React context) adapted for Atomic's in-process architecture. The hook manages the adapter's lifecycle after receiving it without needing to know about session types or adapter factories.
+
+- [x] **Q3 — Claude adapter hook registration:** **Stream message parsing** — Claude Agent SDK v1 delivers all event types (`text`, `tool_use`, `tool_result`, `task_started`, sub-agent lifecycle) as message types in the `AsyncIterable` stream returned by `Session.stream()`. No separate hook registration (`PreToolUse`, `SubagentStart`) is needed. The adapter iterates the stream and switches on `message.type` to handle all event types inline. ([Claude Agent SDK reference](https://deepwiki.com/anthropics/claude-agent-sdk-typescript))
+
+- [x] **Q4 — Debug event persistence strategy:** **File-based JSONL log retention (OpenCode pattern)** — replaces the originally proposed in-memory replay buffer. Events are written to `~/.local/share/atomic/log/events/` as JSONL files (`YYYY-MM-DDTHHMMSS.events.jsonl`), with automatic rotation retaining 10 most recent files. This mirrors OpenCode's `packages/opencode/src/util/log.ts` implementation which uses `Bun.Glob("????-??-??T??????.log")` for cleanup and `Bun.file().writer()` for writing. Key advantages: events persist across process restarts (enabling crash debugging), no memory cap concerns, JSONL files are analyzable with `jq`/`grep`, and rotation is automatic and bounded. Dev mode uses fixed `dev.events.jsonl` filename. ([OpenCode Log.init() reference](https://deepwiki.com/anomalyco/opencode))
+
+- [x] **Q5 — Copilot adapter test mocking:** **Real EventEmitter instance** — tests use a real `EventEmitter` instance rather than a mock. This is lightweight, tests actual event wiring, and ensures the adapter correctly registers/unregisters handlers on the EventEmitter interface.
diff --git a/specs/unified-workflow-execution.md b/specs/unified-workflow-execution.md
new file mode 100644
index 0000000000..fec2f68e7e
--- /dev/null
+++ b/specs/unified-workflow-execution.md
@@ -0,0 +1,974 @@
+# Unified Workflow Execution Interface — Technical Design Document / RFC
+
+| Document Metadata      | Details     |
+| ---------------------- | ----------- |
+| Author(s)              | lavaman131  |
+| Status                 | Draft (WIP) |
+| Team / Owner           | Atomic CLI  |
+| Created / Last Updated | 2026-02-26  |
+
+## 1. Executive Summary
+
+The Atomic CLI's workflow execution layer currently uses a hardcoded dispatch pattern: `createWorkflowCommand()` checks `metadata.name === "ralph"` and routes to a specialized 200-line handler that builds and streams a graph. All non-Ralph workflows receive a generic handler that only sets UI state flags and sends the user's prompt through normal chat — no graph is built or executed. Meanwhile, the `WorkflowSDK` class (a generic facade designed for exactly this purpose) is never used at runtime.
+
+This RFC proposes a **Unified Workflow Execution Interface** that:
+
+1. Extends `WorkflowMetadata` and the custom workflow file export format to support graph factories, state factories, and UI progress declarations
+2. Replaces the `if (name === "ralph")` dispatch with a generic execution path that works for any graph-backed workflow
+3. Reconciles the TUI's sub-agent bridge (`context.spawnSubagentParallel`) with the SDK's `SubagentGraphBridge` into a single composable bridge interface
+4. Generalizes Ralph-specific UI coupling (session tracking, task lists, cancellation) into workflow-agnostic abstractions
+
+The result enables any custom workflow file in `.atomic/workflows/` to define a graph that executes with full streaming, progress updates, task tracking, and session management — identical to what Ralph has today, but without per-workflow command scaffolding.
+
+> **Research basis:** [research/docs/2026-02-25-unified-workflow-execution-research.md](../research/docs/2026-02-25-unified-workflow-execution-research.md) — comprehensive architecture audit of current state.
+
+---
+
+## 2. Context and Motivation
+
+### 2.1 Current State
+
+The codebase contains a mature, generic graph execution engine with:
+
+- A fluent `GraphBuilder<TState>` API ([research §5.1](../research/docs/2026-02-25-unified-workflow-execution-research.md))
+- 12 node factory functions (agent, tool, subagent, parallel, decision, wait, etc.) ([research §5.2](../research/docs/2026-02-25-unified-workflow-execution-research.md))
+- `GraphExecutor` with queue-based traversal, retry, checkpointing, and streaming ([research §5.3](../research/docs/2026-02-25-unified-workflow-execution-research.md))
+- A typed annotation system for state management ([research §5.4](../research/docs/2026-02-25-unified-workflow-execution-research.md))
+- Reusable workflow templates (`sequential`, `mapReduce`, `reviewCycle`, `taskLoop`) ([research §5.5](../research/docs/2026-02-25-unified-workflow-execution-research.md))
+- A `WorkflowSDK` facade class with `execute()`, `stream()`, and `registerWorkflow()` methods ([research §4](../research/docs/2026-02-25-unified-workflow-execution-research.md))
+- Generic session management via `WorkflowSession` ([research §6.3](../research/docs/2026-02-25-unified-workflow-execution-research.md))
+- A command registry supporting dynamic workflow command registration ([research §1.1](../research/docs/2026-02-25-unified-workflow-execution-research.md))
+
+**Architecture Diagram (Current State):**
+
+```
+┌───────────────────────────────────────────────────────────────┐
+│                        UI LAYER                               │
+│                                                               │
+│  chat.tsx ─── executeCommand() ─── globalRegistry.get()       │
+│     │                                      │                  │
+│     │ Ralph state:                  CommandDefinition          │
+│     │  - ralphSessionId            execute(args, context)     │
+│     │  - ralphSessionDir                   │                  │
+│     │  - ralphTaskIds                      ▼                  │
+│     │                        ┌─────────────────────┐          │
+│     │                        │createWorkflowCommand│          │
+│     │                        │  (dispatch check)   │          │
+│     │                        └───────┬─────────────┘          │
+│     │                          ┌─────┴─────┐                  │
+│     │                  name==="ralph"  name!=="ralph"          │
+│     │                          │            │                  │
+│     │                          ▼            ▼                  │
+│     │                createRalphCmd    generic handler         │
+│     │                (200 lines)      (sets state only)       │
+│     │                          │            │                  │
+│     │                          ▼            ▼                  │
+│     │                Graph execution  onStreamMessage          │
+│     │                + streaming      (regular chat)           │
+└─────┼──────────────────────────┼──────────────────────────────┘
+      │                          │
+┌─────┼──────────────────────────┼──────────────────────────────┐
+│     │           WORKFLOW LAYER │                               │
+│     │                          ▼                               │
+│     │            createRalphWorkflow()                         │
+│     │                   │                                      │
+│     │                   ▼                                      │
+│     │            streamGraph(compiled, {initialState})         │
+│     │                                                          │
+│     │   ┌──────────────────────────────────────────────┐       │
+│     │   │ WorkflowSDK (exists but UNUSED at runtime)   │       │
+│     │   │ - init(config)                               │       │
+│     │   │ - execute(compiled, options)                  │       │
+│     │   │ - stream(compiled, options)                   │       │
+│     │   │ - registerWorkflow(name, workflow)            │       │
+│     │   └──────────────────────────────────────────────┘       │
+└────────────────────────────────────────────────────────────────┘
+```
+
+### 2.2 The Problem
+
+- **Only Ralph can execute graphs.** The `if (metadata.name === "ralph")` dispatch at `workflow-commands.ts:543-548` is the sole mechanism routing a workflow to actual graph execution. Every other workflow gets a no-op generic handler that just sends the prompt as a regular chat message ([research §3](../research/docs/2026-02-25-unified-workflow-execution-research.md)).
+
+- **Custom workflows cannot define graphs.** The custom workflow file format (`.atomic/workflows/*.ts`) only exports metadata (name, description, version). There is no mechanism to export a graph factory, state factory, or node descriptions ([research §7.5](../research/docs/2026-02-25-unified-workflow-execution-research.md)).
+
+- **200 lines of duplicable orchestration.** `createRalphCommand()` manually constructs bridges, registries, graphs, and streaming loops. Any new graph-backed workflow would need to duplicate this boilerplate ([research §2.2](../research/docs/2026-02-25-unified-workflow-execution-research.md)).
+
+- **WorkflowSDK is dead code.** The SDK class designed for generic execution is never used at runtime because Ralph bypasses it for TUI-specific bridge routing ([research §4.3](../research/docs/2026-02-25-unified-workflow-execution-research.md)).
+
+- **Ralph couples deeply into the UI layer.** `CommandContext` has `setRalphSessionDir`, `setRalphSessionId`, `setRalphTaskIds` methods. `chat.tsx` has `ralphSessionId`, `ralphSessionDir`, `ralphTaskIds` state variables. The TodoWrite guard filters by Ralph task IDs. Ctrl+C cleanup references Ralph state ([research §8](../research/docs/2026-02-25-unified-workflow-execution-research.md)).
+
+---
+
+## 3. Goals and Non-Goals
+
+### 3.1 Functional Goals
+
+- [ ] Any custom workflow file in `.atomic/workflows/` can export a graph factory and have it execute with full streaming, progress, and session management
+- [ ] The Ralph workflow continues to work identically to today (zero regression)
+- [ ] Ralph-specific UI coupling (session tracking, task lists, cancellation) is replaced with workflow-agnostic abstractions
+- [ ] `WorkflowMetadata` is extended with graph/state factory fields
+- [ ] A single generic execution path handles all graph-backed workflows (no `if (name === "ralph")` dispatch)
+- [ ] The TUI's sub-agent bridge and the SDK's `SubagentGraphBridge` are reconciled into a composable interface
+- [ ] Node-level progress descriptions are declarable per-workflow (not hardcoded)
+- [ ] `CommandContext` Ralph-specific methods are replaced with generic workflow equivalents
+
+### 3.2 Non-Goals (Out of Scope)
+
+- [ ] We will NOT change the graph execution engine itself (`GraphBuilder`, `GraphExecutor`, node factories) — it is already generic
+- [ ] We will NOT rewrite the Ralph workflow graph definition (`ralph/graph.ts`, `ralph/state.ts`) — only its command integration
+- [ ] We will NOT add a visual graph editor or YAML-based workflow definitions
+- [ ] We will NOT change how custom workflow files are discovered (`discoverWorkflowFiles()`, `loadWorkflowsFromDisk()`) — only what exports are recognized
+- [ ] We will NOT change the `WorkflowSession` internals — only how sessions are initialized from command handlers
+- [ ] We will NOT build support for multi-workflow concurrent execution (one active workflow at a time constraint is preserved)
+
+---
+
+## 4. Proposed Solution (High-Level Design)
+
+### 4.1 System Architecture Diagram (Proposed)
+
+```mermaid
+%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#f8f9fa','primaryTextColor':'#2c3e50','primaryBorderColor':'#4a5568','lineColor':'#4a90e2','secondaryColor':'#ffffff','tertiaryColor':'#e9ecef'}}}%%
+
+flowchart TB
+    classDef ui fill:#5a67d8,stroke:#4c51bf,stroke-width:2.5px,color:#ffffff,font-weight:600
+    classDef engine fill:#4a90e2,stroke:#357abd,stroke-width:2.5px,color:#ffffff,font-weight:600
+    classDef workflow fill:#48bb78,stroke:#38a169,stroke-width:2.5px,color:#ffffff,font-weight:600
+    classDef bridge fill:#667eea,stroke:#5a67d8,stroke-width:2.5px,color:#ffffff,font-weight:600
+    classDef file fill:#718096,stroke:#4a5568,stroke-width:2.5px,color:#ffffff,font-weight:600,stroke-dasharray:6 3
+
+    User(("◉ User")):::ui
+
+    subgraph UILayer["UI Layer"]
+        ChatTUI["chat.tsx<br><i>Generic workflow state</i>"]:::ui
+        CmdRegistry["Command Registry<br><i>globalRegistry</i>"]:::ui
+        WorkflowCtx["WorkflowContext<br><i>replaces Ralph-specific</i>"]:::bridge
+    end
+
+    subgraph ExecutionLayer["Unified Execution Layer"]
+        direction TB
+        GenericHandler["createWorkflowCommand()<br><i>single path for all</i>"]:::engine
+        WorkflowExecutor["WorkflowExecutor<br><i>generic orchestration</i>"]:::engine
+        BridgeAdapter["ComposableBridge<br><i>reconciles TUI + SDK bridges</i>"]:::bridge
+    end
+
+    subgraph GraphEngine["Graph Engine (unchanged)"]
+        StreamGraph["streamGraph()"]:::engine
+        GraphExec["GraphExecutor"]:::engine
+        NodeFactories["12 Node Factories"]:::engine
+    end
+
+    subgraph Workflows["Workflow Definitions"]
+        RalphDef["Ralph<br><i>builtin: createGraph()</i>"]:::workflow
+        CustomA["custom-a.ts<br><i>exports createGraph()</i>"]:::workflow
+        CustomB["custom-b.ts<br><i>exports createGraph()</i>"]:::workflow
+    end
+
+    Files[(".atomic/workflows/*.ts")]:::file
+
+    User -->|"/workflow prompt"| CmdRegistry
+    CmdRegistry --> GenericHandler
+    GenericHandler -->|"metadata.createGraph()"| WorkflowExecutor
+    WorkflowExecutor -->|"bridge, registry, state"| StreamGraph
+    StreamGraph --> GraphExec
+    GraphExec --> NodeFactories
+    WorkflowExecutor --> BridgeAdapter
+    WorkflowExecutor --> WorkflowCtx
+    WorkflowCtx --> ChatTUI
+
+    Files -.->|"discovery"| Workflows
+    Workflows -.->|"register"| CmdRegistry
+
+    style UILayer fill:#ffffff,stroke:#cbd5e0,stroke-width:2px,stroke-dasharray:8 4
+    style ExecutionLayer fill:#ffffff,stroke:#cbd5e0,stroke-width:2px,stroke-dasharray:8 4
+    style GraphEngine fill:#ffffff,stroke:#cbd5e0,stroke-width:2px,stroke-dasharray:8 4
+    style Workflows fill:#ffffff,stroke:#cbd5e0,stroke-width:2px,stroke-dasharray:8 4
+```
+
+### 4.2 Architectural Pattern
+
+We are adopting a **Strategy + Facade** pattern:
+
+- **Strategy:** Each workflow provides a `createGraph()` factory function and optional `createState()`, `nodeDescriptions`, and `capabilities` — pluggable strategies for graph construction, state initialization, UI progress, and feature opt-in.
+- **Facade:** A new `WorkflowExecutor` class (or function) encapsulates the 200 lines of orchestration currently in `createRalphCommand()` into a generic, reusable execution pipeline.
+
+### 4.3 Key Components
+
+| Component                      | Responsibility                                                      | Current State                              | Change Required                                                               |
+| ------------------------------ | ------------------------------------------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------- |
+| `WorkflowDefinition` interface | Extended metadata + graph/state factories                           | `WorkflowMetadata` (metadata only)         | **New**: Add `createGraph`, `createState`, `nodeDescriptions`, `capabilities` |
+| `WorkflowExecutor`             | Generic graph orchestration (bridge, registry, streaming, progress) | `createRalphCommand()` (Ralph-only)        | **New**: Extract and generalize from Ralph handler                            |
+| `WorkflowContext`              | Workflow-agnostic session/task/cancellation tracking                | Ralph-specific methods on `CommandContext` | **New**: Replace `setRalphSession*` with `setWorkflowSession*`                |
+| `ComposableBridge`             | Unified sub-agent bridge (TUI + SDK compatible)                     | Two incompatible bridges                   | **New**: Adapter interface reconciling both patterns                          |
+| `createWorkflowCommand()`      | Single dispatch for all workflows                                   | `if (name === "ralph")` hardcoded check    | **Modify**: Remove Ralph check, use generic path                              |
+| Custom workflow file exports   | Graph factory + metadata                                            | Metadata only                              | **Extend**: Recognize `createGraph`, `createState`, etc.                      |
+
+---
+
+## 5. Detailed Design
+
+### 5.1 Extended Workflow Definition Interface
+
+The existing `WorkflowMetadata` is extended with execution-related fields to form `WorkflowDefinition`. The design is **fully declarative** — all workflow behavior is inferred from the graph definition and state structure rather than requiring explicit capability flags. ([research §9.3](../research/docs/2026-02-25-unified-workflow-execution-research.md); external patterns: [LangGraph's declarative graph model, Inngest's declarative step definitions](../research/docs/2026-02-25-workflow-sdk-patterns.md))
+
+> **Decision (Q1):** Custom workflows export a **declarative graph builder config** (nodes, edges, state annotations) rather than a `createGraph()` function returning `CompiledGraph`. The framework compiles the config, enabling validation, tooling, and consistent error handling before execution.
+>
+> **Decision (Q4):** A standard `WorkflowTask` interface is defined for consistent task list rendering across all workflows.
+>
+> **Decision (Q5):** Explicit `WorkflowCapabilities` flags are removed. All behavior is declarative — the framework infers capabilities from the graph definition (e.g., subagent nodes imply subagent support, task annotations imply task list support).
+
+```typescript
+// src/ui/commands/workflow-commands.ts (extended)
+
+import type {
+    BaseState,
+    NodeDefinition,
+    Edge,
+    StateAnnotations,
+} from "../../workflows/graph/types";
+
+/**
+ * Standard task interface for workflow task list UI.
+ * All task-list-capable workflows must use this shape.
+ */
+export interface WorkflowTask {
+    /** Unique task identifier */
+    id: string;
+    /** Human-readable task title */
+    title: string;
+    /** Task status */
+    status: "pending" | "in_progress" | "completed" | "failed" | "blocked";
+    /** Optional task dependencies (IDs of tasks that must complete first) */
+    blockedBy?: string[];
+    /** Optional error message if status is "failed" */
+    error?: string;
+}
+
+/**
+ * Declarative graph configuration exported by custom workflows.
+ * The framework compiles this into a CompiledGraph.
+ */
+export interface WorkflowGraphConfig<TState extends BaseState = BaseState> {
+    /** Node definitions for the graph */
+    nodes: NodeDefinition<TState>[];
+    /** Edge definitions connecting nodes */
+    edges: Edge<TState>[];
+    /** The starting node ID */
+    startNode: string;
+    /** State annotations with reducers (defines state shape and merge behavior) */
+    stateAnnotations?: StateAnnotations<TState>;
+    /** Maximum iterations for loops (default: 100) */
+    maxIterations?: number;
+}
+
+/**
+ * Extended workflow definition that includes execution logic.
+ * Backward-compatible with WorkflowMetadata (all new fields optional).
+ * Fully declarative — capabilities are inferred from the graph definition.
+ */
+export interface WorkflowDefinition extends WorkflowMetadata {
+    /**
+     * Declarative graph configuration for this workflow.
+     * The framework validates and compiles this into a CompiledGraph.
+     * If absent, the workflow falls back to the generic chat handler.
+     */
+    graphConfig?: WorkflowGraphConfig<BaseState>;
+
+    /**
+     * Factory function to create the initial state for graph execution.
+     * Receives the user's prompt and session context.
+     */
+    createState?: (params: WorkflowStateParams) => BaseState;
+
+    /**
+     * Map of node IDs to human-readable progress descriptions.
+     * Replaces the hardcoded `getNodePhaseDescription()`.
+     * Nodes not in this map are silently skipped in UI progress.
+     * Example: { "planner": "🧠 Planning tasks...", "worker": "⚡ Implementing..." }
+     */
+    nodeDescriptions?: Record<string, string>;
+}
+
+export interface WorkflowStateParams {
+    /** The user's prompt text */
+    prompt: string;
+    /** UUID session ID for this execution */
+    sessionId: string;
+    /** Session directory path */
+    sessionDir: string;
+    /** Maximum iterations (from workflow config or global default) */
+    maxIterations: number;
+}
+```
+
+**Backward compatibility:** `WorkflowDefinition extends WorkflowMetadata` — all new fields are optional. Existing workflows with metadata-only exports continue to work via the generic chat handler path.
+
+**Capability inference:** The framework inspects the graph config to determine capabilities:
+
+- **Task list**: Inferred if state annotations include a `tasks` field typed as `WorkflowTask[]`
+- **Subagents**: Inferred if any node has `type: "agent"` or uses subagent/parallel subagent node factories
+- **Session persistence**: Always enabled for graph-backed workflows
+- **Approval gates**: Inferred if any node has `type: "wait"` or `type: "ask_user"`
+
+### 5.2 Custom Workflow File Export Format (Extended)
+
+Custom workflow files in `.atomic/workflows/*.ts` now export a **declarative graph config** alongside metadata. The framework compiles the config into a `CompiledGraph`:
+
+```typescript
+// .atomic/workflows/my-workflow.ts
+
+import { subagentNode, toolNode } from "atomic/workflows/graph";
+import type {
+    WorkflowGraphConfig,
+    WorkflowStateParams,
+    WorkflowTask,
+} from "atomic/types";
+
+// === Metadata (unchanged) ===
+export const name = "my-workflow";
+export const description = "My custom graph-backed workflow";
+export const aliases = ["mw"];
+export const version = "1.0.0";
+
+// === NEW: Declarative Graph Config ===
+export const graphConfig: WorkflowGraphConfig<MyState> = {
+    startNode: "planner",
+    nodes: [
+        subagentNode({
+            id: "planner",
+            agent: "planner",
+            task: (s) => s.prompt,
+        }),
+        toolNode({ id: "execute", execute: (s) => runTask(s) }),
+    ],
+    edges: [{ from: "planner", to: "execute" }],
+    maxIterations: 50,
+};
+
+// === NEW: State Factory ===
+export function createState(params: WorkflowStateParams): MyState {
+    return {
+        executionId: params.sessionId,
+        prompt: params.prompt,
+        tasks: [],
+        outputs: {},
+    };
+}
+
+// === NEW: Node Descriptions (undescribed nodes are silently skipped) ===
+export const nodeDescriptions: Record<string, string> = {
+    planner: "🧠 Planning tasks...",
+    execute: "⚡ Executing task...",
+};
+```
+
+Note: No explicit `capabilities` export is needed — the framework infers capabilities from the graph config (e.g., presence of subagent nodes implies subagent support, `tasks` in state implies task list support).
+
+### 5.3 Workflow Loader Changes (`loadWorkflowsFromDisk`)
+
+The existing `loadWorkflowsFromDisk()` at `workflow-commands.ts:401-471` is extended to extract the new exports:
+
+```typescript
+// In loadWorkflowsFromDisk() — additional extraction after existing metadata
+const workflowDef: WorkflowDefinition = {
+    // Existing metadata fields (unchanged)
+    name: workflowName,
+    description: module.description ?? `Custom workflow: ${workflowName}`,
+    aliases: module.aliases,
+    version: module.version,
+    minSDKVersion: module.minSDKVersion,
+    stateVersion: module.stateVersion,
+    migrateState: module.migrateState,
+    source,
+
+    // NEW: Execution fields (declarative)
+    graphConfig: module.graphConfig ?? undefined,
+    createState:
+        typeof module.createState === "function"
+            ? module.createState
+            : undefined,
+    nodeDescriptions: module.nodeDescriptions ?? undefined,
+};
+```
+
+**Validation at load time:** When `graphConfig` is present, the framework validates:
+
+- `startNode` references a node that exists in `nodes`
+- All edge `from`/`to` references exist in `nodes`
+- No orphaned nodes (every node is reachable from `startNode`)
+- State annotations are consistent with node signatures
+
+**Change scope:** ~10 lines added to `loadWorkflowsFromDisk()`. No existing logic modified.
+
+### 5.4 Generic `WorkflowContext` (Replacing Ralph-Specific UI Coupling)
+
+Replace Ralph-specific methods on `CommandContext` with generic workflow equivalents:
+
+```typescript
+// src/ui/commands/registry.ts — CommandContext changes
+
+export interface CommandContext {
+    // ... existing generic methods (unchanged) ...
+
+    // REMOVE (Ralph-specific):
+    // setRalphSessionDir: (dir: string | null) => void;
+    // setRalphSessionId: (id: string | null) => void;
+    // setRalphTaskIds: (ids: Set<string>) => void;
+
+    // ADD (generic workflow):
+    setWorkflowSessionDir: (dir: string | null) => void;
+    setWorkflowSessionId: (id: string | null) => void;
+    setWorkflowTaskIds: (ids: Set<string>) => void;
+}
+```
+
+**In `chat.tsx`**, rename state variables:
+
+- `ralphSessionId` → `workflowSessionId`
+- `ralphSessionDir` → `workflowSessionDir`
+- `ralphTaskIds` → `workflowTaskIds`
+
+**In `CommandContextState`**, rename:
+
+- `ralphConfig` → `workflowConfig` (same shape, generic name):
+
+```typescript
+workflowConfig?: {
+    userPrompt: string | null;
+    sessionId?: string;
+    workflowName?: string;  // NEW: track which workflow is running
+};
+```
+
+### 5.5 `WorkflowExecutor` — Generic Orchestration
+
+> **Decision (Q2):** The `WorkflowSDK` class is **completely removed** as a breaking change. All execution logic is consolidated into `WorkflowExecutor`. This eliminates the unused abstraction layer and the confusion of having two execution paths.
+>
+> **Decision (Q3):** The sub-agent bridge is injected **after compilation** by mutating `compiled.config.runtime`, matching Ralph's existing pattern. The bridge is an execution concern, not a graph definition concern.
+>
+> **Decision (Q6):** Undescribed nodes are **silently skipped** — the executor only shows progress for nodes listed in `nodeDescriptions`.
+
+Extract the ~200 lines of orchestration from `createRalphCommand()` into a reusable function. The `WorkflowExecutor` replaces both `createRalphCommand()` and the now-removed `WorkflowSDK`:
+
+```typescript
+// src/workflows/executor.ts (NEW file — replaces WorkflowSDK)
+
+import { streamGraph } from "./graph/compiled";
+import { compileGraphConfig } from "./graph/compiler";
+import { SubagentTypeRegistry } from "./graph/subagent-registry";
+import { discoverAgentInfos } from "../ui/commands/agent-commands";
+import { initWorkflowSession, getWorkflowSessionDir } from "./session";
+import type {
+    WorkflowDefinition,
+    WorkflowStateParams,
+    WorkflowTask,
+} from "../ui/commands/workflow-commands";
+import type { CommandContext } from "../ui/commands/registry";
+import type { BaseState, CompiledGraph } from "./graph/types";
+
+export interface WorkflowExecutionResult {
+    success: boolean;
+    message?: string;
+    error?: Error;
+}
+
+/**
+ * Generic workflow executor that handles:
+ * 1. Graph compilation from declarative config
+ * 2. Session initialization
+ * 3. State construction via workflow's createState()
+ * 4. Bridge + registry setup (injected post-compilation)
+ * 5. Graph streaming with progress callbacks
+ * 6. Task list updates (inferred from state annotations)
+ * 7. Error/cancellation handling
+ *
+ * This replaces both createRalphCommand() and the removed WorkflowSDK.
+ */
+export async function executeWorkflow(
+    definition: WorkflowDefinition,
+    prompt: string,
+    context: CommandContext,
+    options?: { maxIterations?: number },
+): Promise<WorkflowExecutionResult> {
+    const { graphConfig, createState, nodeDescriptions } = definition;
+
+    if (!graphConfig) {
+        return { success: false, message: "Workflow has no graph definition" };
+    }
+
+    // 1. Validate and compile the declarative graph config
+    const compiled = compileGraphConfig(graphConfig);
+
+    // 2. Session initialization
+    const sessionId = crypto.randomUUID();
+    const sessionDir = getWorkflowSessionDir(sessionId);
+    void initWorkflowSession(definition.name, sessionId);
+
+    // 3. State construction
+    const maxIterations =
+        options?.maxIterations ?? graphConfig.maxIterations ?? 100;
+    const stateParams: WorkflowStateParams = {
+        prompt,
+        sessionId,
+        sessionDir,
+        maxIterations,
+    };
+
+    const initialState = createState
+        ? createState(stateParams)
+        : ({ executionId: sessionId, prompt, outputs: {} } as BaseState);
+
+    // 4. Bridge + registry setup (injected post-compilation)
+    const hasSubagentNodes = inferHasSubagentNodes(compiled);
+    const bridge = hasSubagentNodes ? createBridgeAdapter(context) : undefined;
+    const registry = hasSubagentNodes ? createSubagentRegistry() : undefined;
+
+    compiled.config.runtime = {
+        ...compiled.config.runtime,
+        subagentBridge: bridge,
+        subagentRegistry: registry,
+    };
+
+    // 5. Infer task list support from state
+    const hasTaskList = inferHasTaskList(compiled);
+
+    // 6. Stream execution
+    let sessionTracked = false;
+    let lastNodeId: string | null = null;
+
+    try {
+        for await (const step of streamGraph(compiled, { initialState })) {
+            // Progress updates — silently skip undescribed nodes
+            if (step.nodeId !== lastNodeId && nodeDescriptions) {
+                const desc = nodeDescriptions[step.nodeId];
+                if (desc) {
+                    context.addMessage(
+                        "assistant",
+                        `**Workflow Progress:** ${desc}`,
+                    );
+                }
+                lastNodeId = step.nodeId;
+            }
+
+            // Task list updates (inferred from state, no capability flag needed)
+            if (hasTaskList && step.state.tasks?.length > 0) {
+                context.setTodoItems(step.state.tasks);
+
+                if (!sessionTracked) {
+                    context.setWorkflowSessionDir(sessionDir);
+                    context.setWorkflowSessionId(sessionId);
+                    const taskIds = new Set(
+                        (step.state.tasks as WorkflowTask[])
+                            .map((t) => t.id)
+                            .filter(
+                                (id): id is string =>
+                                    id != null && id.length > 0,
+                            ),
+                    );
+                    context.setWorkflowTaskIds(taskIds);
+                    sessionTracked = true;
+                }
+            }
+        }
+
+        return { success: true };
+    } catch (error) {
+        if (error instanceof Error && error.message === "Workflow cancelled") {
+            return { success: true, message: "Workflow cancelled" };
+        }
+        return {
+            success: false,
+            message: `Workflow failed: ${error instanceof Error ? error.message : String(error)}`,
+            error: error instanceof Error ? error : new Error(String(error)),
+        };
+    }
+}
+
+/** Infers whether the compiled graph uses subagent nodes */
+function inferHasSubagentNodes(compiled: CompiledGraph<BaseState>): boolean {
+    for (const node of compiled.nodes.values()) {
+        if (node.type === "agent" || node.id.includes("subagent")) return true;
+    }
+    return false;
+}
+
+/** Infers whether the state schema includes a tasks field */
+function inferHasTaskList(compiled: CompiledGraph<BaseState>): boolean {
+    return compiled.config.metadata?.hasTaskList === true;
+}
+
+/** Creates a bridge adapter wrapping the TUI's spawnSubagentParallel */
+function createBridgeAdapter(context: CommandContext) {
+    return {
+        async spawn(agent: SubagentSpawnOptions, abortSignal?: AbortSignal) {
+            const [result] = await context.spawnSubagentParallel!(
+                [{ ...agent, abortSignal }],
+                abortSignal,
+            );
+            return result!;
+        },
+        spawnParallel: (
+            agents: SubagentSpawnOptions[],
+            abortSignal?: AbortSignal,
+        ) => context.spawnSubagentParallel!(agents, abortSignal),
+    };
+}
+
+/** Creates and populates a subagent type registry */
+function createSubagentRegistry(): SubagentTypeRegistry {
+    const registry = new SubagentTypeRegistry();
+    for (const agent of discoverAgentInfos()) {
+        registry.register({
+            name: agent.name,
+            info: agent,
+            source: agent.source,
+        });
+    }
+    return registry;
+}
+```
+
+### 5.6 Unified `createWorkflowCommand()` (Removing Ralph Dispatch)
+
+The dispatch function is simplified to a single path:
+
+```typescript
+// src/ui/commands/workflow-commands.ts
+
+function createWorkflowCommand(
+    definition: WorkflowDefinition,
+): CommandDefinition {
+    // No more `if (metadata.name === "ralph")` check
+
+    const hasGraph = definition.graphConfig != null;
+
+    return {
+        name: definition.name,
+        description: definition.description,
+        category: "workflow",
+        aliases: definition.aliases,
+        argumentHint: definition.argumentHint,
+        execute: async (
+            args: string,
+            context: CommandContext,
+        ): Promise<CommandResult> => {
+            // Prevent concurrent workflows
+            if (context.state.workflowActive) {
+                return {
+                    success: false,
+                    message: `A workflow is already active (${context.state.workflowType}).`,
+                };
+            }
+
+            const prompt = args.trim();
+            if (!prompt) {
+                return {
+                    success: false,
+                    message: `Please provide a prompt for the ${definition.name} workflow.`,
+                };
+            }
+
+            // If no graph factory, fall back to generic chat handler
+            if (!hasGraph) {
+                context.addMessage(
+                    "system",
+                    `Starting **${definition.name}** workflow...`,
+                );
+                return {
+                    success: true,
+                    stateUpdate: {
+                        workflowActive: true,
+                        workflowType: definition.name,
+                        initialPrompt: prompt,
+                        pendingApproval: false,
+                        specApproved: undefined,
+                        feedback: null,
+                    },
+                };
+            }
+
+            // Graph-backed workflow: use WorkflowExecutor
+            context.updateWorkflowState({
+                workflowActive: true,
+                workflowType: definition.name,
+                workflowConfig: {
+                    sessionId: crypto.randomUUID(),
+                    userPrompt: prompt,
+                    workflowName: definition.name,
+                },
+            });
+            context.setStreaming(true);
+            context.addMessage(
+                "assistant",
+                `Starting **${definition.name}** workflow...`,
+            );
+
+            const result = await executeWorkflow(definition, prompt, context);
+
+            context.setStreaming(false);
+
+            return {
+                success: result.success,
+                message: result.success
+                    ? `**${definition.name}** workflow completed successfully.`
+                    : result.message,
+                stateUpdate: {
+                    workflowActive: false,
+                    workflowType: null,
+                    initialPrompt: null,
+                },
+            };
+        },
+    };
+}
+```
+
+### 5.7 Ralph Migration — Becoming a Standard Workflow
+
+The Ralph workflow becomes a standard `WorkflowDefinition` by exporting a declarative graph config:
+
+```typescript
+// src/workflows/ralph/index.ts (new or modified)
+
+import { subagentNode, toolNode, decisionNode } from "../graph/nodes";
+import { createRalphState } from "./state";
+import type {
+    WorkflowDefinition,
+    WorkflowStateParams,
+    WorkflowGraphConfig,
+} from "../../ui/commands/workflow-commands";
+import type { RalphWorkflowState } from "./state";
+
+// Declarative graph config extracted from createRalphWorkflow()
+const ralphGraphConfig: WorkflowGraphConfig<RalphWorkflowState> = {
+    startNode: "planner",
+    nodes: [
+        subagentNode({
+            id: "planner",
+            agent: "planner",
+            task: (s) => s.yoloPrompt,
+        }),
+        toolNode({ id: "parse-tasks", execute: parseTasks }),
+        toolNode({ id: "select-ready-tasks", execute: selectReadyTasks }),
+        // ... worker node, reviewer node, fixer node (same structure as current)
+    ],
+    edges: [
+        { from: "planner", to: "parse-tasks" },
+        { from: "parse-tasks", to: "select-ready-tasks" },
+        // ... loop and conditional edges
+    ],
+    maxIterations: 100,
+};
+
+export const ralphWorkflowDefinition: WorkflowDefinition = {
+    // Existing metadata
+    name: "ralph",
+    description:
+        "Autonomous implementation workflow: plan → implement → review → fix",
+    aliases: [],
+    argumentHint: "PROMPT",
+
+    // Declarative graph config (framework compiles it)
+    graphConfig: ralphGraphConfig,
+
+    // State factory
+    createState: (params: WorkflowStateParams) =>
+        createRalphState(params.sessionId, {
+            yoloPrompt: params.prompt,
+            ralphSessionDir: params.sessionDir,
+            maxIterations: params.maxIterations,
+        }),
+
+    // Node descriptions (extracted from getNodePhaseDescription)
+    // Undescribed nodes are silently skipped in UI
+    nodeDescriptions: {
+        planner: "🧠 Planning — decomposing into tasks...",
+        "parse-tasks": "📋 Parsing task list...",
+        "select-ready-tasks": "🔍 Selecting ready tasks...",
+        worker: "⚡ Working — implementing tasks...",
+        reviewer: "🔎 Reviewing implementation...",
+        fixer: "🔧 Applying fixes...",
+    },
+};
+```
+
+The builtin workflow registration in `getAllWorkflows()` would then use `ralphWorkflowDefinition` directly, and `createRalphCommand()` can be deleted.
+
+### 5.8 Sub-Agent Bridge Reconciliation
+
+> **Decision (Q2):** With `WorkflowSDK` completely removed, the `SubagentGraphBridge` and `ProviderRegistry` are also removed. The TUI bridge adapter becomes the sole bridge implementation.
+
+The current two bridge patterns are collapsed into one ([research §4.3, §13.3](../research/docs/2026-02-25-unified-workflow-execution-research.md)):
+
+**Problem (resolved):**
+
+1. ~~**TUI Bridge**: `context.spawnSubagentParallel()` — routes through the TUI's existing agent session~~
+2. ~~**SDK Bridge**: `SubagentGraphBridge` — creates its own sessions via `ProviderRegistry`~~
+
+**Solution — Single Bridge Interface (TUI-backed):**
+
+```typescript
+// src/workflows/graph/bridge.ts (new file)
+
+export interface WorkflowBridge {
+    spawn(
+        agent: SubagentSpawnOptions,
+        abortSignal?: AbortSignal,
+    ): Promise<SubagentResult>;
+    spawnParallel(
+        agents: SubagentSpawnOptions[],
+        abortSignal?: AbortSignal,
+    ): Promise<SubagentResult[]>;
+}
+
+/**
+ * Creates a bridge from the TUI's spawnSubagentParallel.
+ * This is the sole bridge implementation (WorkflowSDK and SubagentGraphBridge are removed).
+ */
+export function createTUIBridge(context: CommandContext): WorkflowBridge {
+    return {
+        async spawn(agent, abortSignal) {
+            const [result] = await context.spawnSubagentParallel!(
+                [{ ...agent, abortSignal }],
+                abortSignal,
+            );
+            return result!;
+        },
+        spawnParallel: (agents, abortSignal) =>
+            context.spawnSubagentParallel!(agents, abortSignal),
+    };
+}
+```
+
+The `WorkflowExecutor` uses `createTUIBridge(context)` for sub-agent spawning. For test scenarios, mock implementations of `WorkflowBridge` can be provided directly.
+
+### 5.9 Data Model / Schema Changes
+
+**No database schema changes** — this is an in-memory TypeScript type system change.
+
+**Key type changes:**
+
+| Type                                      | Field Changes                                                                                                                          |
+| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `WorkflowMetadata` → `WorkflowDefinition` | Add `graphConfig?`, `createState?`, `nodeDescriptions?`                                                                                |
+| `CommandContext`                          | `setRalphSessionDir` → `setWorkflowSessionDir`, `setRalphSessionId` → `setWorkflowSessionId`, `setRalphTaskIds` → `setWorkflowTaskIds` |
+| `CommandContextState`                     | `ralphConfig` → `workflowConfig` (add `workflowName` field)                                                                            |
+| Chat.tsx state                            | `ralphSessionId` → `workflowSessionId`, `ralphSessionDir` → `workflowSessionDir`, `ralphTaskIds` → `workflowTaskIds`                   |
+
+### 5.10 State Machine: Workflow Execution Lifecycle
+
+```
+                        ┌──────────┐
+                        │  IDLE    │
+                        └────┬─────┘
+                             │ /workflow prompt
+                             ▼
+                    ┌────────────────┐
+           ┌───────│  INITIALIZING  │
+           │       └────────┬───────┘
+           │                │ session created, state built
+           │                ▼
+           │       ┌────────────────┐
+           │       │   STREAMING   │◄─────────────┐
+           │       └────────┬───────┘              │
+           │                │                      │
+           │         ┌──────┴──────┐               │
+           │         │             │               │
+           │    step.done    step.next         Ctrl+C
+           │         │             │               │
+           │         ▼             ▼               ▼
+           │  ┌────────────┐  ┌──────────┐  ┌───────────┐
+           │  │ COMPLETED  │  │STREAMING │  │ CANCELLED │
+           │  └────────────┘  └──────────┘  └───────────┘
+           │
+           │  (no graphConfig)
+           ▼
+    ┌──────────────┐
+    │ CHAT_FALLBACK│  (generic handler, sends prompt as chat)
+    └──────────────┘
+```
+
+---
+
+## 6. Alternatives Considered
+
+| Option                                                        | Pros                                                                                                       | Cons                                                                                                                                                           | Reason for Rejection                                                                         |
+| ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| **A: Route through `WorkflowSDK.stream()`**                   | Cleanest abstraction, SDK manages all deps                                                                 | Creates redundant sessions in TUI context, SDK bypassed for good reasons ([research §4.3](../research/docs/2026-02-25-unified-workflow-execution-research.md)) | TUI already has active sessions; WorkflowSDK is being completely removed                     |
+| **B: Keep Ralph dispatch, add per-workflow dispatches**       | No refactoring needed                                                                                      | Multiplies the pattern: `if (name === "foo")` for each new workflow, O(n) scaling problem                                                                      | Defeats the purpose of a unified interface                                                   |
+| **C: YAML/JSON workflow definitions**                         | Declarative, no code needed                                                                                | Limited expressiveness, can't express complex logic (loops, conditionals, custom tools), learning new DSL                                                      | TypeScript declarative config is already expressive and type-safe                            |
+| **D: `createGraph()` function returning CompiledGraph**       | Maximum flexibility, workflows control full builder API                                                    | No framework-level validation before compilation, harder to introspect for tooling                                                                             | Declarative config enables validation, capability inference, and framework-level compilation |
+| **E: Declarative graph config + WorkflowExecutor (Selected)** | Framework validates/compiles config, capabilities inferred, fully declarative, WorkflowSDK removed cleanly | Requires a `compileGraphConfig()` utility function                                                                                                             | **Selected:** Best balance of declarative design, validation, and simplicity                 |
+
+---
+
+## 7. Cross-Cutting Concerns
+
+### 7.1 Security and Privacy
+
+- **No new attack surface:** Custom workflow files are already dynamically imported; this change only recognizes additional exports from the same files.
+- **Bridge isolation:** The composable bridge pattern preserves the existing trust model — TUI bridge reuses the TUI session's permissions, SDK bridge uses SDK-level credentials.
+- **Session isolation:** `WorkflowSession` already isolates session directories per workflow execution; this is unchanged.
+
+### 7.2 Observability Strategy
+
+- **Progress descriptions:** Each workflow declares `nodeDescriptions` — the executor emits these as assistant messages (same pattern Ralph uses today).
+- **Streaming events:** The `streamGraph()` async generator already yields `StepResult` events with `nodeId`, `state`, and timing — no additional instrumentation needed.
+- **Error propagation:** Errors are caught in `executeWorkflow()` and returned as `WorkflowExecutionResult` — the command handler can display them.
+
+### 7.3 Backward Compatibility
+
+- **`WorkflowDefinition extends WorkflowMetadata`:** All new fields are optional. Existing metadata-only workflows continue to hit the generic chat handler path.
+- **`WorkflowSDK` removal (Breaking):** The `WorkflowSDK` class, `SubagentGraphBridge`, and `ProviderRegistry` are completely removed. Any code importing from `src/workflows/graph/sdk.ts` must be updated. This is an intentional breaking change.
+- **Ralph regression test:** Ralph becomes a `WorkflowDefinition` with declarative `graphConfig` and `createState` — functionally identical to `createRalphCommand()` but going through the generic path.
+- **UI rename (`ralph*` → `workflow*`):** This is a breaking change for any external code referencing `setRalphSessionDir` etc. Since `CommandContext` is internal to the TUI, this is acceptable.
+
+---
+
+## 8. Migration, Rollout, and Testing
+
+### 8.1 Deployment Strategy
+
+- [ ] **Phase 1: Foundation** — Create `WorkflowDefinition` interface (with `graphConfig`, `WorkflowTask`, `WorkflowGraphConfig`), `compileGraphConfig()` compiler, `WorkflowExecutor` function, and `WorkflowBridge` interface. Unit test all new code.
+- [ ] **Phase 2: WorkflowSDK Removal (Breaking)** — Remove `WorkflowSDK` class, `SubagentGraphBridge`, `ProviderRegistry`, and related code from `src/workflows/graph/sdk.ts`. Update/remove `sdk.test.ts`. Remove any imports referencing these.
+- [ ] **Phase 3: UI Generalization** — Rename Ralph-specific fields in `CommandContext`, `CommandContextState`, and `chat.tsx` to generic workflow equivalents (`ralph*` → `workflow*`). Update all references.
+- [ ] **Phase 4: Ralph Migration** — Create `ralphWorkflowDefinition` with declarative `graphConfig`, `createState`, and `nodeDescriptions`. Wire through `createWorkflowCommand()` generic path. Delete `createRalphCommand()`.
+- [ ] **Phase 5: Loader Extension** — Extend `loadWorkflowsFromDisk()` to recognize `graphConfig`, `createState`, `nodeDescriptions` exports. Add validation at load time. Test with a sample custom workflow file.
+- [ ] **Phase 6: Cleanup** — Remove `getNodePhaseDescription()`, remove `if (name === "ralph")` dispatch, remove unused Ralph-specific code and `WorkflowCapabilities`. Run full test suite.
+
+### 8.2 Test Plan
+
+- **Unit Tests:**
+    - `compileGraphConfig`: Test compilation from declarative config, validation errors
+    - `WorkflowExecutor`: Test with mock graph config, mock context, mock bridge
+    - `WorkflowDefinition` validation: Test with/without `graphConfig`, `createState`
+    - `WorkflowTask` interface: Test task list rendering with standard task shape
+    - `createTUIBridge`: Test delegation to `spawnSubagentParallel`
+    - Capability inference: Test inferring subagent support, task list support from graph config
+    - `loadWorkflowsFromDisk`: Test extraction of new exports from mock workflow files
+- **Integration Tests:**
+    - Ralph workflow executes identically through generic path (regression)
+    - Custom workflow file with `graphConfig` export executes correctly
+    - Custom workflow file without `graphConfig` falls back to chat handler
+    - Task list updates work for workflows with `WorkflowTask[]` in state
+    - Undescribed nodes are silently skipped in progress output
+    - Ctrl+C cancellation works for generic workflows
+- **End-to-End Tests:**
+    - Create a sample workflow in `.atomic/workflows/test-workflow.ts` with declarative graph config
+    - Execute via `/test-workflow <prompt>` in TUI
+    - Verify streaming, progress messages, session creation, and completion
+
+---
+
+## 9. Resolved Decisions
+
+All open questions have been resolved:
+
+| #   | Question                      | Decision                                                                                                                                        |
+| --- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1   | Custom workflow graph exports | **Declarative graph builder config** (nodes, edges) — framework compiles. Enables validation before execution.                                  |
+| 2   | WorkflowSDK usage             | **Completely removed** (breaking change). All execution logic consolidated into `WorkflowExecutor`.                                             |
+| 3   | Bridge injection timing       | **After compilation** — mutate `compiled.config.runtime`. Bridge is an execution concern, not a definition concern.                             |
+| 4   | Task list abstraction         | **Standard `WorkflowTask` interface** defined (`id`, `title`, `status`, `blockedBy?`, `error?`). All task-list workflows conform to this shape. |
+| 5   | Capability defaults           | **No explicit capabilities** — removed entirely. All behavior is declarative and inferred from the graph definition.                            |
+| 6   | `nodeDescriptions` fallback   | **Show nothing** — silently skip undescribed nodes. Only show progress for nodes the workflow author explicitly describes.                      |
diff --git a/specs/workflow-gaps-remediation.md b/specs/workflow-gaps-remediation.md
new file mode 100644
index 0000000000..15e2e15900
--- /dev/null
+++ b/specs/workflow-gaps-remediation.md
@@ -0,0 +1,490 @@
+# Workflow Gaps Remediation — Technical Design Document / RFC
+
+| Document Metadata      | Details     |
+| ---------------------- | ----------- |
+| Author(s)              | Alex Lavaee |
+| Status                 | Draft (WIP) |
+| Team / Owner           | Atomic CLI  |
+| Created / Last Updated | 2026-02-28  |
+
+## 1. Executive Summary
+
+The Atomic CLI's event-driven architecture has 7 documented gaps spanning ~40 source files where code is fully implemented but never connected. Four are high-impact: workflow step rendering is silently discarded (events flow through the bus but `WorkflowStepPartDisplay` is not registered in `PART_REGISTRY`), custom tool discovery (`registerCustomTools()`) is built but never called, the OpenCode MCP bridge returns placeholder strings instead of executing tool handlers, and the `--max-iterations` CLI flag is parsed then dropped. Three are medium-impact: 6 dead modules with zero non-test imports, 6 fully-built but unrendered UI components, and 12 event types emitted but never consumed. This RFC proposes a phased remediation plan to wire all disconnected code paths, remove dead flags, and establish the event/UI pipeline completeness required for production readiness.
+
+**Research basis:** [`research/docs/2026-02-28-workflow-gaps-architecture.md`](../research/docs/2026-02-28-workflow-gaps-architecture.md), [`research/workflow-gaps.md`](../research/workflow-gaps.md)
+
+---
+
+## 2. Context and Motivation
+
+### 2.1 Current State
+
+The Atomic CLI uses a layered event-driven architecture:
+
+```
+SDK Events → SDK Adapter (Claude/OpenCode/Copilot)
+  → bus.publish(BusEvent)
+    → AtomicEventBus
+      → BatchDispatcher (16ms frame-aligned batching)
+        → CorrelationService.enrich()
+          → StreamPipelineConsumer.mapToStreamPart()
+            → applyStreamPartEvent() reducer → Part[] → PART_REGISTRY → React render
+```
+
+This pipeline handles 16 of 28 bus event types. The remaining 12 are silently dropped at `mapToStreamPart()`'s `default: return null` (line 177 of `stream-pipeline-consumer.ts`). Additionally, several fully-implemented subsystems (custom tools, MCP bridge, debug logging) are never activated.
+
+**Reference:** [`research/docs/2026-02-26-streaming-architecture-event-bus-migration.md`](../research/docs/2026-02-26-streaming-architecture-event-bus-migration.md) documents the migration from callbacks to the centralized event-bus pattern.
+
+### 2.2 The Problem
+
+- **User Impact:** Workflow step transitions (start/complete) are invisible in the TUI — users cannot see which workflow node is executing or its duration. Session info/warning messages from OpenCode and Copilot adapters are silently swallowed.
+- **Developer Impact:** The `--max-iterations` flag gives a false sense of control — it's parsed but never reaches the executor. Custom tools in `.atomic/tools/` directories are discovered but never registered.
+- **Technical Debt:** 6 modules totaling ~912 lines of code are fully implemented with zero non-test consumers. 6 UI components are built but never rendered. The OpenCode MCP bridge is a stub.
+
+**Reference:** [`research/docs/2026-02-28-workflow-issues-research.md`](../research/docs/2026-02-28-workflow-issues-research.md) documents additional workflow rendering issues.
+
+---
+
+## 3. Goals and Non-Goals
+
+### 3.1 Functional Goals
+
+- [x] Wire `workflow.step.start`, `workflow.step.complete`, and `workflow.task.update` events through `mapToStreamPart()` to their existing reducers
+- [x] Register `WorkflowStepPartDisplay` in `PART_REGISTRY` with supporting type definitions
+- [x] Activate `registerCustomTools()` in the chat init sequence
+- [x] Fix the OpenCode MCP bridge to execute actual tool handlers instead of returning placeholders
+- [x] Remove the dead `--max-iterations` CLI flag and all its references
+- [x] Wire the 6 dead modules to their intended import points
+- [x] Wire consumers for the remaining 9 unconsumed event types (session info/warning/title_changed/truncation/compaction, turn start/end, tool partial_result, skill invoked)
+
+### 3.2 Non-Goals (Out of Scope)
+
+- [ ] Adding new event types beyond the existing 28 `BusEventType` definitions
+- [ ] Refactoring the event bus architecture itself (batching, correlation, dispatch)
+- [ ] Adding `--max-iterations` passthrough to the workflow executor (the flag should be removed, not fixed)
+- [ ] Making the Claude adapter emit the 12 currently-unimplemented event types (only OpenCode and Copilot emit them)
+- [x] ~~Replacing the hand-built footer in `chat.tsx` with `FooterStatus`~~ — moved to in-scope per Q3 decision
+- [ ] Adding new UI components or event types not already defined in the codebase
+
+---
+
+## 4. Proposed Solution (High-Level Design)
+
+### 4.1 System Architecture — Event Pipeline (After Remediation)
+
+```mermaid
+%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#f8f9fa','primaryTextColor':'#2c3e50','primaryBorderColor':'#4a5568','lineColor':'#4a90e2','secondaryColor':'#ffffff','tertiaryColor':'#e9ecef'}}}%%
+
+flowchart TB
+    classDef active fill:#48bb78,stroke:#38a169,stroke-width:2px,color:#ffffff,font-weight:600
+    classDef fixed fill:#ed8936,stroke:#dd6b20,stroke-width:2px,color:#ffffff,font-weight:600
+    classDef dead fill:#fc8181,stroke:#e53e3e,stroke-width:2px,color:#ffffff,font-weight:600
+
+    subgraph Adapters["SDK Adapters"]
+        Claude["Claude Adapter"]:::active
+        OpenCode["OpenCode Adapter"]:::active
+        Copilot["Copilot Adapter"]:::active
+        Workflow["Workflow Adapter"]:::active
+    end
+
+    Bus["AtomicEventBus<br>(28 event types)"]:::active
+
+    subgraph Consumers["Event Consumers"]
+        direction TB
+        Wire["wire-consumers.ts"]:::active
+        Dispatcher["BatchDispatcher<br>(16ms batching)"]:::active
+        Correlation["CorrelationService"]:::active
+        Pipeline["StreamPipelineConsumer<br>mapToStreamPart()"]:::fixed
+        Debug["debug-subscriber.ts<br>(DEAD → ACTIVATE)"]:::dead
+    end
+
+    subgraph Rendering["UI Rendering"]
+        Reducer["applyStreamPartEvent()<br>reducer"]:::active
+        Registry["PART_REGISTRY<br>(+workflow-step)"]:::fixed
+        Parts["Part Components<br>(+WorkflowStepPartDisplay)"]:::fixed
+        ChatBus["chat.tsx<br>useBusSubscription<br>(+9 new subscribers)"]:::fixed
+    end
+
+    subgraph Init["Init Sequence"]
+        CustomTools["registerCustomTools()<br>(DEAD → ACTIVATE)"]:::dead
+        McpBridge["OpenCode MCP Bridge<br>(PLACEHOLDER → FIX)"]:::dead
+    end
+
+    Adapters --> Bus
+    Bus --> Wire --> Dispatcher --> Correlation --> Pipeline
+    Bus -.-> Debug
+    Pipeline --> Reducer --> Registry --> Parts
+    Bus --> ChatBus
+    Init -.-> Bus
+```
+
+**Legend:** 🟢 Active (working) | 🟠 Fixed (wiring change) | 🔴 Dead (activation needed)
+
+### 4.2 Architectural Pattern
+
+The remediation follows a **"connect the dots"** pattern — no new architectures are introduced. Every fix involves wiring existing, tested code to its intended call site. The three categories of work are:
+
+1. **Pipeline wiring** — Adding cases to `mapToStreamPart()` switch and `useBusSubscription` hooks
+2. **Init activation** — Calling existing functions from the startup sequence
+3. **Dead code removal** — Removing the `--max-iterations` flag that was never connected
+
+### 4.3 Key Components
+
+| Component                  | Change Type                               | Files Affected                   | Gap # |
+| -------------------------- | ----------------------------------------- | -------------------------------- | ----- |
+| `mapToStreamPart()` switch | Wire 3 new cases                          | `stream-pipeline-consumer.ts`    | 1, 7  |
+| `WorkflowStepPart` type    | Add to `Part` union                       | `types.ts`                       | 1     |
+| `PART_REGISTRY`            | Add `"workflow-step"` entry               | `registry.tsx`, `index.ts`       | 1, 6  |
+| `registerCustomTools()`    | Add call to init sequence                 | `chat.ts`, `sdk/tools/index.ts`  | 2, 5  |
+| OpenCode MCP bridge        | Replace placeholder with handler dispatch | `opencode-mcp-bridge.ts`         | 3     |
+| `--max-iterations` flag    | Remove all references                     | `cli.ts`, `chat.ts`, `README.md` | 4     |
+| Dead module imports        | Wire to intended import points            | 6 files                          | 5     |
+| `useBusSubscription` hooks | Add 9 new subscribers                     | `chat.tsx`                       | 7     |
+| Unrendered components      | Wire to rendering hooks                   | Various                          | 6     |
+
+---
+
+## 5. Detailed Design
+
+### 5.1 Phase 1: Workflow Step Rendering Pipeline (Gap 1 + Gap 7 Events 9–11)
+
+**Objective:** Make workflow step transitions visible in the TUI.
+
+**Reference:** [`research/docs/2026-02-28-workflow-gaps-architecture.md` §Gap 1](../research/docs/2026-02-28-workflow-gaps-architecture.md) — identifies three disconnections: consumer gap, type system gap, and registry gap.
+
+#### 5.1.1 Add `WorkflowStepPart` to Type System
+
+**File:** `src/ui/parts/types.ts`
+
+Add the `WorkflowStepPart` interface and include it in the `Part` union:
+
+```typescript
+// Add to types.ts after existing part interfaces (around line 120)
+export interface WorkflowStepPart {
+  type: "workflow-step";
+  nodeId: string;
+  nodeName: string;
+  status: "running" | "completed" | "failed";
+  durationMs?: number;
+}
+
+// Update Part union (line 124-132) to include WorkflowStepPart
+export type Part =
+  | TextPart
+  | ReasoningPart
+  | ToolPart
+  | AgentPart
+  | TaskListPart
+  | SkillLoadPart
+  | McpSnapshotPart
+  | CompactionPart
+  | WorkflowStepPart;  // ← ADD
+```
+
+#### 5.1.2 Wire `mapToStreamPart()` Cases
+
+**File:** `src/events/consumers/stream-pipeline-consumer.ts` (lines 126–182)
+
+Add three new cases to the switch statement before `default`:
+
+```typescript
+case "workflow.step.start":
+  return {
+    type: "workflow-step-start",
+    nodeId: event.payload.nodeId,
+    nodeName: event.payload.nodeName,
+    workflowId: event.payload.workflowId,
+  } as StreamPartEvent;
+
+case "workflow.step.complete":
+  return {
+    type: "workflow-step-complete",
+    nodeId: event.payload.nodeId,
+    status: event.payload.status,
+    result: event.payload.result,
+    workflowId: event.payload.workflowId,
+  } as StreamPartEvent;
+
+case "workflow.task.update":
+  return {
+    type: "task-list-update",
+    workflowId: event.payload.workflowId,
+    tasks: event.payload.tasks,
+  } as StreamPartEvent;
+```
+
+**Rationale:** The reducer at `src/ui/parts/stream-pipeline.ts` already handles `"workflow-step-start"` (line 987), `"workflow-step-complete"` (line 1002), and `"task-list-update"` (line 1021). These cases simply create the `StreamPartEvent` objects the reducer expects.
+
+#### 5.1.3 Register `WorkflowStepPartDisplay` in `PART_REGISTRY`
+
+**File:** `src/ui/components/parts/registry.tsx` (lines 22–31)
+
+```typescript
+import { WorkflowStepPartDisplay } from "./workflow-step-part-display.tsx";
+
+// Add to PART_REGISTRY object:
+"workflow-step": WorkflowStepPartDisplay,
+```
+
+**File:** `src/ui/components/parts/index.ts`
+
+```typescript
+export { WorkflowStepPartDisplay } from "./workflow-step-part-display.tsx";
+```
+
+**File:** `src/ui/components/parts/workflow-step-part-display.tsx` (line 11)
+
+Verify/fix the import of `WorkflowStepPart` from `../../parts/types.ts` — it will resolve once the type is defined in §5.1.1.
+
+---
+
+### 5.2 Phase 2: Custom Tool Registration Activation (Gap 2 + Gap 5 Module 2)
+
+**Objective:** Activate the `.atomic/tools/` custom tool discovery and registration pipeline.
+
+**Reference:** [`research/docs/2026-02-28-workflow-gaps-architecture.md` §Gap 2](../research/docs/2026-02-28-workflow-gaps-architecture.md), [`specs/custom-tools-directory.md:853`](../specs/custom-tools-directory.md) (Phase 3 checklist — unchecked).
+
+#### 5.2.1 Add Call to Init Sequence
+
+**File:** `src/commands/chat.ts` (between lines 243 and 251)
+
+```typescript
+import { registerCustomTools } from "../sdk/tools/index.ts";
+
+// Between client creation and client.start():
+const client = createClientForAgentType(agentType);     // line 243
+if (agentType === "copilot") {
+    client.registerTool(createTodoWriteTool());          // line 246-248
+}
+await registerCustomTools(client);                       // ← ADD
+await client.start();                                    // line 251
+```
+
+#### 5.2.2 Add Barrel Re-export
+
+**File:** `src/sdk/tools/index.ts`
+
+```typescript
+export { registerCustomTools, cleanupTempToolFiles } from "./discovery.ts";
+```
+
+---
+
+### 5.3 Phase 3: OpenCode MCP Bridge Fix (Gap 3)
+
+**Objective:** Replace the placeholder string response with actual tool handler execution.
+
+**Reference:** [`research/docs/2026-02-28-workflow-gaps-architecture.md` §Gap 3](../research/docs/2026-02-28-workflow-gaps-architecture.md) — documents how Claude (in-process MCP via `createSdkMcpServer()`) and Copilot (direct SDK injection) solve this correctly.
+
+#### 5.3.1 Design Decision: In-Process MCP Server Pattern
+
+The recommended approach is to adopt the same pattern Claude uses: an in-process MCP server where the handler closure stays in the same process. This avoids the fundamental problem of serializing JavaScript functions across process boundaries.
+
+**File:** `src/sdk/tools/opencode-mcp-bridge.ts` (lines 25–110)
+
+Replace the placeholder `tools/call` handler with actual tool handler invocation. The key change is that instead of generating a separate script file that runs in a child process (where the handler function is lost at the `JSON.stringify` serialization boundary), the MCP server should run in-process:
+
+```typescript
+// Current (broken): tools/call returns placeholder
+respond(id, {
+    content: [{ type: "text", text: `Tool ${toolName} executed via MCP bridge` }],
+});
+
+// Fixed: tools/call invokes the actual handler
+const result = await tool.handler(params.arguments);
+respond(id, {
+    content: [{ type: "text", text: typeof result === "string" ? result : JSON.stringify(result) }],
+});
+```
+
+**Consideration:** The exact implementation depends on how OpenCode's MCP tool registration works. If OpenCode requires an external stdio MCP server, an IPC mechanism (e.g., `process.send`/`process.on("message")`) between the spawned script and the main Atomic process may be needed instead. See Open Questions §9.
+
+#### 5.3.2 Wire Cleanup Function
+
+**File:** Appropriate shutdown/cleanup handler
+
+Call `cleanupMcpBridgeScripts()` (exported from `opencode-mcp-bridge.ts:139-155`) during process shutdown. Currently has zero callers.
+
+---
+
+### 5.4 Phase 4: Remove Dead `--max-iterations` Flag (Gap 4)
+
+**Objective:** Remove the CLI flag that is parsed but silently dropped.
+
+**Reference:** [`research/docs/2026-02-28-workflow-gaps-architecture.md` §Gap 4](../research/docs/2026-02-28-workflow-gaps-architecture.md) — documents the complete data flow showing the drop at `chat.ts:197-203`.
+
+#### 5.4.1 Files to Edit
+
+| File                   | Line(s) | Change                                                    |
+| ---------------------- | ------- | --------------------------------------------------------- |
+| `src/cli.ts`           | 108     | Remove `.option("--max-iterations <n>", ...)`             |
+| `src/cli.ts`           | 118     | Remove `--max-iterations` from help text example          |
+| `src/cli.ts`           | 168     | Remove `maxIterations: parseInt(...)` from options        |
+| `src/commands/chat.ts` | 67      | Remove `maxIterations?: number` from `ChatCommandOptions` |
+| `README.md`            | 310     | Remove `--max-iterations` from CLI flag reference table   |
+
+**Note:** The internal `maxIterations` pathway in the executor (`executor.ts:109`, `ralph/state.ts:148`, `ralph/graph.ts:210`) is NOT affected — those use `definition.graphConfig?.maxIterations` which is a separate, working code path for programmatic workflow definitions. Only the CLI surface is removed.
+
+---
+
+### 5.5 Phase 5: Dead Module Activation (Gap 5)
+
+**Objective:** Wire the 6 dead modules to their intended import points.
+
+**Reference:** [`research/docs/2026-02-28-workflow-gaps-architecture.md` §Gap 5](../research/docs/2026-02-28-workflow-gaps-architecture.md)
+
+#### 5.5.1 Module Activation Table
+
+| Module                                               | Import Into                                                                                                  | Call Site                                                                             | Gating                                         |
+| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------- | ---------------------------------------------- |
+| `debug-subscriber.ts` → `attachDebugSubscriber(bus)` | `src/ui/index.ts`                                                                                            | After `AtomicEventBus` instantiation (line 240), before `EventBusProvider` (line 740) | `ATOMIC_DEBUG=1` env var (already in module)   |
+| `discovery.ts` → `registerCustomTools(client)`       | `src/commands/chat.ts`                                                                                       | Between client creation and `client.start()`                                          | None (covered in Phase 2)                      |
+| `file-lock.ts` → `withLock(filePath, fn)`            | `src/telemetry/telemetry-file-io.ts`                                                                         | Concurrent file write operations                                                      | Wrap writes with `withLock()` for extra safety |
+| `merge.ts` → `mergeJsonFile(src, dest)`              | `src/commands/init.ts`                                                                                       | Replace `copyFile()` for files in `AgentConfig.merge_files`                           | `merge_files` array in config                  |
+| `pipeline-logger.ts` → `pipelineLog(stage, action)`  | 5 pipeline modules (event-bus, batch-dispatcher, wire-consumers, stream-pipeline-consumer, subagent-adapter) | Strategic debug logging points                                                        | `ATOMIC_DEBUG=1` env var (already in module)   |
+| `tree-hints.ts` → `buildParallelAgentsHeaderHint()`  | `src/ui/components/parallel-agents-tree.tsx` or `src/ui/chat.tsx`                                            | Header text above agent list                                                          | None                                           |
+
+#### 5.5.2 Implementation Notes
+
+**`debug-subscriber`**: Already self-gated on `ATOMIC_DEBUG=1`. Safe to attach unconditionally — no-op in production.
+
+**`merge`**: The `AgentConfig` type in `src/config.ts` has a `merge_files` field (line 23) populated with `[".mcp.json"]` for Claude (line 39) and `[".github/mcp-config.json"]` for Copilot (line 68). The `init` command should use `mergeJsonFile()` instead of `copyFile()` for these entries to preserve user MCP server configurations.
+
+**`pipeline-logger`**: Add `pipelineLog()` calls to the 5 pipeline stages matching the `PipelineStage` enum: `"EventBus"`, `"Dispatcher"`, `"Wire"`, `"Consumer"`, `"Subagent"`.
+
+---
+
+### 5.6 Phase 6: Unconsumed Event Wiring (Gap 7 — Remaining 9 Events)
+
+**Objective:** Add consumers for the 9 remaining unconsumed event types (workflow events 9–11 covered in Phase 1).
+
+**Reference:** [`research/docs/2026-02-28-workflow-gaps-architecture.md` §Gap 7](../research/docs/2026-02-28-workflow-gaps-architecture.md)
+
+#### 5.6.1 Session Events (5) — `useBusSubscription` in `chat.tsx`
+
+| Event Type                     | Handler Pattern                                | UI Effect                                        |
+| ------------------------------ | ---------------------------------------------- | ------------------------------------------------ |
+| `stream.session.info`          | Parallel to `stream.session.error` (line 2770) | Display info toast/banner                        |
+| `stream.session.warning`       | Parallel to `stream.session.error` (line 2770) | Display warning toast/banner                     |
+| `stream.session.title_changed` | Update title state                             | Update conversation title in header              |
+| `stream.session.truncation`    | Update context state                           | Show context window truncation indicator         |
+| `stream.session.compaction`    | Lifecycle state machine                        | Show compaction progress (phase → success/error) |
+
+#### 5.6.2 Turn Lifecycle (2) — `useBusSubscription` in `chat.tsx`
+
+| Event Type          | Handler Pattern         | UI Effect                   |
+| ------------------- | ----------------------- | --------------------------- |
+| `stream.turn.start` | Set turn-active state   | Visual turn boundary marker |
+| `stream.turn.end`   | Clear turn-active state | Turn completion signal      |
+
+#### 5.6.3 Tool Partial Results (1) — `mapToStreamPart()` Pipeline
+
+| Event Type                   | Pipeline Path                                            | UI Effect                             |
+| ---------------------------- | -------------------------------------------------------- | ------------------------------------- |
+| `stream.tool.partial_result` | New `StreamPartEvent` type → reducer → `ToolPart` update | Streaming tool output in tool display |
+
+This event requires a new case in `mapToStreamPart()` and potentially a new `StreamPartEvent` type. The `ToolPart` type in `types.ts` (line 82-89) may need a `partialOutput` field.
+
+#### 5.6.4 Skill Events (1) — `useBusSubscription` in `chat.tsx`
+
+| Event Type             | Handler Pattern    | UI Effect                          |
+| ---------------------- | ------------------ | ---------------------------------- |
+| `stream.skill.invoked` | Display skill name | Show skill invocation notification |
+
+#### 5.6.5 Emission Source Matrix (For Context)
+
+Only OpenCode and Copilot adapters emit these 12 event types. The Claude adapter does NOT emit any of them. Consumers should handle the case where these events are simply never fired for Claude sessions.
+
+---
+
+### 5.7 Phase 7: Unrendered Component Activation (Gap 6)
+
+**Objective:** Connect the 6 unrendered UI components to their intended rendering hooks.
+
+**Reference:** [`research/docs/2026-02-28-workflow-gaps-architecture.md` §Gap 6](../research/docs/2026-02-28-workflow-gaps-architecture.md)
+
+#### 5.7.1 Component Activation Table
+
+| Component                 | Action                                                           | Target                                                                        |
+| ------------------------- | ---------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| `WorkflowStepPartDisplay` | Register in `PART_REGISTRY`                                      | Covered in Phase 1 (§5.1.3)                                                   |
+| `UserQuestionInline`      | **Remove** — overlay `UserQuestionDialog` is the intended UX     | Delete `user-question-inline.tsx`, remove barrel export from `parts/index.ts` |
+| `FooterStatus`            | **Replace** hand-built footer in `chat.tsx:6120-6166`            | Render `<FooterStatus>` component instead of inline footer elements           |
+| `TimestampDisplay`        | Wire into `MessageBubble` in verbose mode                        | `src/ui/components/message-bubble.tsx`                                        |
+| `StreamingBullet`         | Wire as prefix for streaming text parts                          | `TextPartDisplay` rendering                                                   |
+| `CodeBlock`               | **Remove** — redundant with OpenTUI's `<markdown>` code handling | Delete `code-block.tsx` and remove all references                             |
+
+---
+
+## 6. Alternatives Considered
+
+| Option                                                                  | Pros                                                | Cons                                                                                                    | Decision                                                                                                                     |
+| ----------------------------------------------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| **Fix `--max-iterations` passthrough** (wire CLI flag to executor)      | Users get control over workflow iterations          | Adds complexity to chat init; the executor already has a working programmatic pathway via `graphConfig` | **Rejected** — The flag was never connected; removing it is simpler and the programmatic API covers the use case             |
+| **Rewrite OpenCode MCP bridge as IPC** (child process + `process.send`) | Keeps MCP as an external process (isolates crashes) | Complex IPC protocol needed; serialization overhead; error handling across process boundary             | **Deferred** — Prefer in-process pattern (matches Claude's approach) unless OpenCode SDK requires external process           |
+| **Remove dead modules instead of activating**                           | Less code to maintain; eliminates potential bugs    | Loses ~912 lines of tested, purpose-built code; would need to be rewritten if needed later              | **Rejected** — All 6 modules have clear intended use sites documented in research                                            |
+| **Wire all 12 unconsumed events at once**                               | Complete event pipeline                             | Large blast radius; session/turn events need careful UI design                                          | **Selected with phasing** — Workflow events (9–11) first (Phase 1, ready reducers), then session/turn/skill events (Phase 6) |
+
+---
+
+## 7. Cross-Cutting Concerns
+
+### 7.1 Security and Privacy
+
+- **Custom tools activation (Phase 2):** `registerCustomTools()` dynamically imports user-provided TypeScript files from `.atomic/tools/` directories. The existing `prepareToolFileForImport()` function (line 80-103 of `discovery.ts`) rewrites `@atomic/plugin` imports, which provides some sandboxing. However, custom tools run with full process permissions — this is an accepted design decision consistent with how other coding agents handle user extensions.
+- **MCP bridge fix (Phase 3):** Moving tool execution in-process means tool handler errors won't crash the MCP server in isolation. Error handling must wrap handler invocation in try/catch.
+
+### 7.2 Observability Strategy
+
+- **`debug-subscriber` activation (Phase 5):** Once wired, `attachDebugSubscriber(bus)` will emit JSONL event logs to `~/.local/share/atomic/log/events/` when `ATOMIC_DEBUG=1` is set. This provides full event pipeline observability for development.
+- **`pipeline-logger` activation (Phase 5):** `pipelineLog()` calls across the 5 pipeline stages will provide stage-by-stage debug traces when `ATOMIC_DEBUG=1` is set.
+
+### 7.3 Testing Strategy
+
+- **Existing tests:** `debug-subscriber`, `merge`, `pipeline-logger`, and `tree-hints` already have passing tests. No new test files needed for these modules.
+- **New tests needed:** `stream-pipeline-consumer.ts` test file should add cases for the 3 new `mapToStreamPart()` switch cases (workflow events). `chat.ts` new `useBusSubscription` hooks need integration test coverage.
+- **Regression risk:** All changes are additive wiring — no existing behavior is modified except the `--max-iterations` flag removal, which was never functional.
+
+---
+
+## 8. Migration, Rollout, and Testing
+
+### 8.1 Deployment Strategy
+
+- [ ] **Phase 1:** Wire workflow step rendering pipeline (Gap 1 + Gap 7 events 9–11). Most impactful — enables visual workflow progress. All receiver code exists.
+- [ ] **Phase 2:** Activate `registerCustomTools()` (Gap 2 + Gap 5 Module 2). Enables `.atomic/tools/` pipeline.
+- [ ] **Phase 3:** Fix OpenCode MCP bridge (Gap 3). Requires design decision on approach.
+- [ ] **Phase 4:** Remove `--max-iterations` flag (Gap 4). Trivial cleanup — 5 files, ~8 lines.
+- [ ] **Phase 5:** Activate remaining dead modules (Gap 5 Modules 1, 3–6). Low risk — all debug-gated or optional.
+- [ ] **Phase 6:** Wire remaining 9 unconsumed events (Gap 7). Requires new `useBusSubscription` hooks and UI state management.
+- [ ] **Phase 7:** Activate unrendered UI components (Gap 6). Requires UI design decisions.
+
+### 8.2 Phasing Rationale
+
+| Phase | Risk                     | Impact                         | Dependencies                  |
+| ----- | ------------------------ | ------------------------------ | ----------------------------- |
+| 1     | Low (receivers exist)    | High (workflow visibility)     | None                          |
+| 2     | Low (pipeline built)     | High (custom tools enabled)    | None                          |
+| 3     | Medium (design decision) | High (OpenCode tool execution) | Open Question §9.1            |
+| 4     | None (removal only)      | Low (flag was dead)            | None                          |
+| 5     | Low (debug-gated)        | Medium (observability)         | Phase 2 (module 2 covered)    |
+| 6     | Medium (new UI state)    | Medium (event completeness)    | Phase 1 (pattern established) |
+| 7     | Medium (UI decisions)    | Low-Medium (polish)            | Open Questions §9.3, §9.4     |
+
+### 8.3 Test Plan
+
+- **Unit Tests:** Add cases to `stream-pipeline-consumer` tests for the 3 new `mapToStreamPart()` switch cases. Add test for `registerCustomTools()` call in chat init.
+- **Integration Tests:** Verify end-to-end event flow for `workflow.step.start` → `WorkflowStepPartDisplay` rendering. Verify custom tool files in `.atomic/tools/` are discovered, loaded, and registered.
+- **E2E Tests:** Run the existing snake game E2E test with all three agents (OpenCode, Copilot, Claude) to verify no regressions. Specifically test workflow execution with `bun run ~/Documents/projects/atomic/src/cli.ts chat -a <agent> -w` to verify step visibility.
+
+---
+
+## 9. Resolved Questions
+
+- [x] **Q1 (MCP Bridge Approach):** **Decision: In-process MCP server pattern.** Adopt Claude's approach using `createSdkMcpServer()`. This avoids the serialization boundary entirely — the handler closure stays in-process. Phase 3 (§5.3) is updated accordingly.
+- [x] **Q2 (Event Wiring Scope):** **Decision: Wire all 12 events in this RFC.** Complete the pipeline in one pass. Phase 1 handles the 3 workflow events with ready reducers; Phase 6 handles the remaining 9 session/turn/tool/skill events.
+- [x] **Q3 (FooterStatus Component):** **Decision: Replace the hand-built footer with `FooterStatus`.** This reduces inline code duplication in `chat.tsx:6120-6166`. Phase 7 (§5.7) should replace the hand-built footer with the `FooterStatus` component.
+- [x] **Q4 (UserQuestionInline vs Dialog):** **Decision: Remove `UserQuestionInline`.** The overlay `UserQuestionDialog` is the intended UX. `UserQuestionInline` should be removed as dead code along with its barrel export in `parts/index.ts`.
+- [x] **Q5 (CodeBlock Component):** **Decision: Remove `CodeBlock` as redundant.** OpenTUI's `<markdown>` handles code rendering. The component and its helpers (`normalizeLanguage()`, `extractCodeBlocks()`, `hasCodeBlocks()`, `extractInlineCode()`) should be removed.
+- [x] **Q6 (file-lock Module):** **Decision: Wire `file-lock.ts` into `telemetry-file-io.ts`.** Add `withLock()` wrapping around concurrent file write operations for extra safety, even though `O_APPEND` provides OS-level atomicity.
+- [x] **Q7 (Dead Module Activation Order):** **Decision: Activate all 6 simultaneously.** They are all low-risk and independent of each other. This can be done in Phase 5 as a single batch.
diff --git a/specs/workflow-issues-fixes.md b/specs/workflow-issues-fixes.md
new file mode 100644
index 0000000000..c4ec9595e2
--- /dev/null
+++ b/specs/workflow-issues-fixes.md
@@ -0,0 +1,704 @@
+# Workflow Issues Fixes — Technical Design Document
+
+| Document Metadata      | Details     |
+| ---------------------- | ----------- |
+| Author(s)              | Alex Lavaee |
+| Status                 | Draft (WIP) |
+| Team / Owner           | Atomic CLI  |
+| Created / Last Updated | 2026-02-28  |
+
+## 1. Executive Summary
+
+This RFC addresses five interconnected issues in the Ralph workflow system that degrade the user experience during autonomous task execution. The issues are: (1) sub-agent tree UI stuck at "Initializing..." instead of showing tool call counts, (2) code-review running after every worker iteration due to an unconditional exit edge bug in the graph builder's `.loop()` construct, (3) sequential task execution where parallel execution is possible, (4) missing blink indicator for actively-worked-on tasks, and (5) multi-second delay between task completion and the final duration/token summary appearing. The proposed fixes range from event pipeline reliability improvements, a loop exit edge fix in `builder.ts`, a worker node refactor for parallel dispatching via `spawnSubagentParallel`, to explicit `"in_progress"` status transitions and deferred-completion pipeline optimizations. Together, these changes will make the Ralph workflow feel responsive, visually accurate, and significantly faster for multi-task workloads.
+
+> **Research Reference:** [`research/docs/2026-02-28-workflow-issues-research.md`](../research/docs/2026-02-28-workflow-issues-research.md)
+
+## 2. Context and Motivation
+
+### 2.1 Current State
+
+The Atomic CLI's Ralph workflow is a three-phase autonomous implementation system:
+
+1. **Phase 1 (Planning):** A planner sub-agent decomposes a user prompt into a dependency-aware task list.
+2. **Phase 2 (Implementation Loop):** A `select-ready-tasks` → `worker` loop iterates, dispatching one task per iteration via `spawnSubagent`.
+3. **Phase 3 (Review & Fix):** A reviewer sub-agent evaluates all changes, optionally followed by a fixer sub-agent.
+
+The graph engine (`compiled.ts`) executes nodes via a FIFO queue, processing one node at a time. The worker node (`graph.ts:154`) takes only `ready[0]` despite `getReadyTasks()` returning all dependency-satisfied tasks.
+
+**Architecture References:**
+- Graph engine: `src/workflows/graph/compiled.ts` (FIFO queue, sequential execution)
+- Ralph graph: `src/workflows/ralph/graph.ts` (worker node, task selection)
+- Executor: `src/workflows/executor.ts` (runtime wiring, `spawnSubagentParallel`)
+- Event pipeline: `src/events/` (bus, coalescing, consumers)
+- UI: `src/ui/chat.tsx` (agent state, stream finalization)
+
+> **Research:** [`research/docs/2026-02-25-ralph-workflow-implementation.md`](../research/docs/2026-02-25-ralph-workflow-implementation.md), [`research/docs/2026-02-25-graph-execution-engine-technical-documentation.md`](../research/docs/2026-02-25-graph-execution-engine-technical-documentation.md)
+
+### 2.2 The Problem
+
+| Issue                                | User Impact                                                                         | Technical Root Cause                                                                                                                   |
+| ------------------------------------ | ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| **Sub-agent tree "Initializing..."** | Users see no feedback about tool activity during worker execution                   | `stream.agent.update` events may not reach the UI due to event pipeline chokepoints (coalescing, race conditions, ownership filtering) |
+| **Code-review timing**               | Users perceive code review running after each task                                  | Already runs once post-loop; may be a perception issue or a different workflow configuration                                           |
+| **Sequential task execution**        | Workflows with independent tasks take N× longer than necessary                      | Worker node takes only `ready[0]`; graph engine processes nodes sequentially via FIFO queue                                            |
+| **Missing task blinker**             | Actively-worked-on tasks appear as static `○` (pending) instead of blinking `●`/`·` | Worker node doesn't set `"in_progress"` status before spawning; relies on sub-agent to set it via TodoWrite                            |
+| **Completion delay**                 | Multi-second gap between last task completing and summary appearing                 | Deferred completion chain (active agents in React state), SDK `session.idle` latency, React state update batching                      |
+
+> **Research:** [`research/docs/2026-02-28-workflow-issues-research.md`](../research/docs/2026-02-28-workflow-issues-research.md) §Summary
+
+## 3. Goals and Non-Goals
+
+### 3.1 Functional Goals
+
+- [ ] **Issue 1:** Sub-agent tree displays tool call counts and current tool name for running worker agents, transitioning from "Initializing..." within the first tool use event
+- [ ] **Issue 2:** Fix unconditional exit edge from `loop_check` → `reviewer` in `builder.ts` so reviewer only runs after loop exit; fix worker marking all currentTasks as completed when only one was dispatched
+- [ ] **Issue 3:** Multiple dependency-ready tasks execute concurrently via `spawnSubagentParallel`, with independent status tracking per task
+- [ ] **Issue 4:** Tasks actively being worked on display the blinking `●`/`·` indicator by having their status set to `"in_progress"` before worker dispatch
+- [ ] **Issue 5:** Reduce the delay between the last task completing and the completion summary appearing to under 500ms
+
+### 3.2 Non-Goals (Out of Scope)
+
+- [ ] Refactoring the graph engine to support true parallel node execution (the FIFO queue stays; parallelism is within the worker node)
+- [ ] Adding configurable concurrency limits for parallel task execution (all ready tasks run concurrently; throttling is a future enhancement)
+- [ ] Redesigning the event bus or coalescing architecture
+- [ ] Modifying the reviewer or fixer nodes
+- [ ] Supporting user-interactive prompts during parallel task execution
+
+## 4. Proposed Solution (High-Level Design)
+
+### 4.1 System Architecture Diagram
+
+```mermaid
+%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#f8f9fa','primaryTextColor':'#2c3e50','primaryBorderColor':'#4a5568','lineColor':'#4a90e2','secondaryColor':'#ffffff','tertiaryColor':'#e9ecef','background':'#f5f7fa','mainBkg':'#f8f9fa','nodeBorder':'#4a5568','clusterBkg':'#ffffff','clusterBorder':'#cbd5e0','edgeLabelBackground':'#ffffff'}}}%%
+
+flowchart TB
+    classDef phaseNode fill:#5a67d8,stroke:#4c51bf,stroke-width:2.5px,color:#ffffff,font-weight:600
+    classDef workerNode fill:#4a90e2,stroke:#357abd,stroke-width:2.5px,color:#ffffff,font-weight:600
+    classDef eventNode fill:#48bb78,stroke:#38a169,stroke-width:2.5px,color:#ffffff,font-weight:600
+    classDef uiNode fill:#667eea,stroke:#5a67d8,stroke-width:2.5px,color:#ffffff,font-weight:600
+    classDef fixNode fill:#ed8936,stroke:#dd6b20,stroke-width:2.5px,color:#ffffff,font-weight:600
+
+    subgraph Phase2["Phase 2: Implementation Loop (Modified)"]
+        direction TB
+        SELECT["select-ready-tasks<br><i>Returns ALL ready tasks</i>"]:::workerNode
+        SETSTATUS["Set tasks → in_progress<br><i>NEW: before dispatch</i>"]:::fixNode
+        PARALLEL["spawnSubagentParallel<br><i>NEW: concurrent workers</i>"]:::fixNode
+        TRACK["Independent status tracking<br><i>NEW: per-task results</i>"]:::fixNode
+        SELECT --> SETSTATUS --> PARALLEL --> TRACK
+    end
+
+    subgraph EventFixes["Event Pipeline Fixes"]
+        direction TB
+        OWNERSHIP["Fix ownership registration<br><i>registerSubagent before tool events</i>"]:::fixNode
+        RACE["Eliminate AgentPart race<br><i>Buffer agent-scoped events</i>"]:::fixNode
+        COALESCE["Ensure update delivery<br><i>Validate coalescing window</i>"]:::fixNode
+    end
+
+    subgraph UIFixes["UI Finalization Fixes"]
+        direction TB
+        BLINK["Task blinker activates<br><i>in_progress status visible</i>"]:::uiNode
+        DEFER["Optimize deferred completion<br><i>Reduce resolution chain latency</i>"]:::fixNode
+        SUMMARY["Faster completion summary<br><i>< 500ms after last task</i>"]:::uiNode
+    end
+
+    Phase2 --> EventFixes
+    EventFixes --> UIFixes
+```
+
+### 4.2 Architectural Pattern
+
+The solution uses an **intra-node parallelism** pattern: the graph engine's FIFO queue remains sequential (one node at a time), but the `worker` node internally dispatches multiple sub-agents concurrently via the existing `spawnSubagentParallel` infrastructure. This is the lowest-risk approach since:
+- The graph engine doesn't need modification
+- `spawnSubagentParallel` is already wired in `executor.ts:235-263`
+- `getReadyTasks()` already returns all ready tasks
+- The event pipeline already supports multiple concurrent sub-agents
+
+> **Research:** [`research/docs/2026-02-28-workflow-issues-research.md`](../research/docs/2026-02-28-workflow-issues-research.md) §Issue 3, §3.3
+
+### 4.3 Key Components
+
+| Component            | Change                                                      | Files Affected                              | Justification                              |
+| -------------------- | ----------------------------------------------------------- | ------------------------------------------- | ------------------------------------------ |
+| Worker Node          | Dispatch all ready tasks via `spawnSubagentParallel`        | `src/workflows/ralph/graph.ts`              | Enables concurrent task execution          |
+| Task Status Manager  | Set `"in_progress"` before dispatch, track per-task results | `src/workflows/ralph/graph.ts`              | Activates blink indicator, accurate status |
+| Event Ownership      | Ensure sub-agent registration before tool events            | `src/events/adapters/subagent-adapter.ts`   | Prevents `isOwnedEvent()` drops            |
+| Agent-Part Buffering | Buffer agent-scoped events until AgentPart exists           | `src/ui/parts/stream-pipeline.ts`           | Eliminates silent event drops              |
+| Deferred Completion  | Reduce resolution chain latency                             | `src/ui/chat.tsx`, `src/ui/parts/guards.ts` | Faster completion summary                  |
+
+## 5. Detailed Design
+
+### 5.1 Issue 1: Sub-Agent Tree "Initializing..." Fix
+
+#### 5.1.1 Root Cause Analysis
+
+The `stream.agent.update` events carrying `toolUses` counts may fail to reach the UI through five identified chokepoints (see [research §1.3](../research/docs/2026-02-28-workflow-issues-research.md)):
+
+1. **Event coalescing** (`coalescing.ts:31-34`): Updates are coalesced per agent per ~16ms batch window — acceptable for latest-wins semantics but drops all events if the subscription isn't yet active
+2. **AgentPart race condition** (`stream-pipeline.ts:917-918`): Tool/text events with `agentId` are silently dropped if the `AgentPart` hasn't been created yet
+3. **`useBusSubscription` bypass** (`chat.tsx:2882-2895`): The `stream.agent.update` handler bypasses the `StreamPipelineConsumer` entirely — if not mounted, events are lost
+4. **Ownership check** (`wire-consumers.ts:83-86`): Events must pass `correlation.isOwnedEvent()` which checks `event.runId` matches `_activeRunId`
+5. **Schema validation** (`event-bus.ts:140-152`): Malformed events are silently dropped
+
+> **Research:** [`research/docs/2026-02-28-workflow-issues-research.md`](../research/docs/2026-02-28-workflow-issues-research.md) §1.2–§1.3, [`research/docs/2026-02-15-subagent-event-flow-diagram.md`](../research/docs/2026-02-15-subagent-event-flow-diagram.md)
+
+#### 5.1.2 Proposed Fixes
+
+**Fix 1A — Ensure agent registration before tool events:**
+
+In `subagent-adapter.ts`, ensure `registerAgent()` is called and the `stream.agent.start` event is published to the bus **before** the first `handleToolUse()` can fire. Currently, the `SubagentStreamAdapter` constructor calls `registerAgent()` at line 95, but the `stream.agent.start` event is published by the executor (`executor.ts:217`). If the sub-agent SDK starts emitting tool events before the bus event is dispatched, tool events arrive at an unregistered agent.
+
+```typescript
+// subagent-adapter.ts — ensure synchronous registration
+constructor(bus, sessionId, runId, agentId, agentName) {
+  this.toolTracker = new SubagentToolTracker(bus, sessionId, runId);
+  this.toolTracker.registerAgent(agentId);
+  // Publish stream.agent.start synchronously before stream iteration begins
+  bus.publish({
+    type: "stream.agent.start",
+    sessionId, runId, timestamp: Date.now(),
+    data: { agentId, agentName, status: "running", isBackground: false }
+  });
+}
+```
+
+**Fix 1B — Buffer agent-scoped events until AgentPart exists:**
+
+In `stream-pipeline.ts:917-918`, instead of silently dropping events when the target `AgentPart` doesn't exist, buffer them in a per-agent queue. When an `AgentPart` is created (via the `parallel-agents` event), flush the buffered events.
+
+```typescript
+// stream-pipeline.ts — add event buffering
+private pendingAgentEvents = new Map<string, StreamPartEvent[]>();
+
+routeToAgentInlineParts(event: StreamPartEvent, agentId: string): boolean {
+  const agentPart = this.findAgentPart(agentId);
+  if (!agentPart) {
+    // Buffer instead of dropping
+    const buffer = this.pendingAgentEvents.get(agentId) ?? [];
+    buffer.push(event);
+    this.pendingAgentEvents.set(agentId, buffer);
+    return true; // Acknowledge event was handled (buffered)
+  }
+  // ... existing routing logic ...
+  return true;
+}
+
+onAgentPartCreated(agentId: string): void {
+  const buffered = this.pendingAgentEvents.get(agentId);
+  if (buffered) {
+    for (const event of buffered) {
+      this.routeToAgentInlineParts(event, agentId);
+    }
+    this.pendingAgentEvents.delete(agentId);
+  }
+}
+```
+
+**Fix 1C — Add diagnostic logging:**
+
+Add `console.debug` logging at each chokepoint to enable diagnosis when "Initializing..." persists:
+
+| Location                      | Log Message                                                                       |
+| ----------------------------- | --------------------------------------------------------------------------------- |
+| `subagent-tool-tracker.ts:66` | `[ToolTracker] onToolStart: agentId=${agentId}, toolCount=${state.toolCount}`     |
+| `event-bus.ts:150`            | `[EventBus] Schema validation failed for ${event.type}: ${error}`                 |
+| `wire-consumers.ts:85`        | `[WireConsumers] Dropped unowned event: ${event.type}, runId=${event.runId}`      |
+| `stream-pipeline.ts:918`      | `[StreamPipeline] Buffered agent-scoped event: ${event.type}, agentId=${agentId}` |
+
+---
+
+### 5.2 Issue 2: Code-Review Runs After Every Task (Unconditional Exit Edge Bug)
+
+#### 5.2.1 Root Cause Identified
+
+**The initial research was wrong** — the reviewer does NOT run only once. Deep investigation reveals the `loop_check` node has an **unconditional exit edge** to the reviewer, causing it to be enqueued on every loop iteration.
+
+> **Research:** [`research/docs/2026-02-28-workflow-issues-research.md`](../research/docs/2026-02-28-workflow-issues-research.md) §Issue 2 (superseded by this analysis)
+
+**The bug is in `builder.ts`'s `.loop()` method (line 734):**
+
+After `.loop()` completes, it sets `this.currentNodeId = loopCheckId`. When the next chained method (`.subagent({ id: "reviewer" })`) calls `.then()` at `builder.ts:806` → `addEdge()` at line 360, it creates:
+
+```typescript
+// builder.ts:360 — created by .subagent() chained after .loop()
+this.addEdge(this.currentNodeId, node.id);
+// Translates to: addEdge("loop_check_N", "reviewer") — NO condition
+```
+
+This produces two outgoing edges from `loop_check_N`:
+
+| Edge     | To                   | Condition                                 | Label             |
+| -------- | -------------------- | ----------------------------------------- | ----------------- |
+| Continue | `select-ready-tasks` | `!config.until(state) && iteration < max` | `"loop-continue"` |
+| Exit     | `reviewer`           | **`undefined` (unconditional)**           | —                 |
+
+In `getNextNodes()` (`compiled.ts:778-781`), both edges are evaluated independently:
+
+```typescript
+for (const edge of outgoingEdges) {
+  if (!edge.condition || edge.condition(state)) {  // unconditional edges ALWAYS match
+    matchingEdges.push(edge);
+  }
+}
+```
+
+**When the loop should continue** (`until` → `false`): BOTH edges match → both `select-ready-tasks` AND `reviewer` are enqueued in `nodeQueue`.
+
+**Result:** The reviewer runs interleaved with the worker loop body on every single iteration:
+
+| Step | Node Executed                                 | Queue After                                          |
+| ---- | --------------------------------------------- | ---------------------------------------------------- |
+| 1    | `worker` (task #1)                            | `[loop_check]`                                       |
+| 2    | `loop_check`                                  | `[select-ready-tasks, reviewer]` ← **both enqueued** |
+| 3    | `select-ready-tasks` (task #2)                | `[reviewer, worker]`                                 |
+| 4    | **`reviewer`** ← runs mid-loop                | `[worker, decision]`                                 |
+| 5    | `worker` (task #2)                            | `[decision, loop_check]`                             |
+| ...  | *(interleaved reviewer/fixer and loop nodes)* |                                                      |
+
+#### 5.2.2 Secondary Bug: Batch Status Marking
+
+An additional bug compounds the issue. The worker node dispatches only `ready[0]` but marks ALL `currentTasks` as completed/error (`graph.ts:168-174`):
+
+```typescript
+// graph.ts:153 — dispatches ONLY the first ready task
+const task = ready[0];
+
+// graph.ts:168-174 — marks ALL currentTasks (not just ready[0])
+tasks: ctx.state.tasks.map((t) => {
+  const wasReady = ctx.state.currentTasks.some((ct) => ct.id === t.id);
+  if (wasReady) {
+    return { ...t, status: result.success ? "completed" : "error" };
+  }
+  return t;
+}),
+```
+
+If `getReadyTasks()` returns `[A, B]` (both independent), the worker dispatches only A's prompt to the sub-agent, but marks **both A and B** as "completed" based on A's result. Task B's work is never performed.
+
+#### 5.2.3 Proposed Fix: Conditional Exit Edge in `builder.ts`
+
+**Fix 2A — Make the exit edge conditional (inverse of continue):**
+
+The `.loop()` method must create an explicit conditional exit edge rather than relying on the implicit unconditional edge from the next chained `.then()` call. The exit edge should only match when the loop `until` condition is `true`.
+
+```typescript
+// builder.ts — inside loop() method, after creating the continue edge
+
+// Create explicit conditional exit edge (inverse of continue condition)
+// Store the loop exit target for the next chained method to use
+this._loopExitNodeId = loopCheckId;
+this._loopUntilCondition = config.until;
+this._loopMaxIterations = maxIterations;
+this._loopStartId = loopStartId;
+```
+
+Then modify `.then()` (or the `addEdge` call that connects from `loopCheckId`) to add a condition when the source is a loop check node:
+
+**Preferred approach — override `currentNodeId` setter in `.loop()`:**
+
+Instead of setting `this.currentNodeId = loopCheckId` directly, create a synthetic "loop_exit" node that only activates when the `until` condition is true:
+
+```typescript
+// builder.ts — end of loop() method
+
+// Create a loop_exit sentinel node that passes through
+const loopExitId = this.generateNodeId("loop_exit");
+const loopExitNode = this.createNode(loopExitId, "decision", async (ctx) => {
+  return { stateUpdate: {} as Partial<TState> };
+});
+this.nodes.push(loopExitNode);
+
+// Conditional exit edge: only taken when until() is true
+this.addEdge(
+  loopCheckId,
+  loopExitId,
+  (state) => {
+    const iterationKey = `${loopStartId}_iteration`;
+    const currentIteration = (state.outputs[iterationKey] as number) ?? 0;
+    return config.until(state) || currentIteration >= maxIterations;
+  },
+  "loop-exit"
+);
+
+// Set currentNodeId to the exit node so the next .then() chains from it
+this.currentNodeId = loopExitId;
+```
+
+This ensures:
+- The `loop-continue` edge matches when `!until(state) && iteration < max`
+- The `loop-exit` edge matches when `until(state) || iteration >= max`
+- These conditions are **mutually exclusive** — exactly one edge matches per iteration
+- The next chained method (`.subagent({ id: "reviewer" })`) creates an unconditional edge from `loop_exit` (not from `loop_check`), so the reviewer is only reachable after the loop truly exits
+
+**Edge topology after fix:**
+
+```
+loop_check ──[!until && iter < max]──→ select-ready-tasks  (continue)
+loop_check ──[until || iter >= max]──→ loop_exit            (exit)
+loop_exit  ──[unconditional]─────────→ reviewer
+```
+
+#### 5.2.4 Fix 2B — Worker Status Marking (addressed in §5.3)
+
+The batch status marking bug is resolved by the parallel execution refactor in §5.3, which maps each task's result independently. For the sequential case (single ready task), the fix is:
+
+```typescript
+// graph.ts — worker node stateUpdate (fix for single-task case)
+tasks: ctx.state.tasks.map((t) => {
+  // Only mark the task that was actually dispatched, not all currentTasks
+  if (t.id === task?.id) {
+    return { ...t, status: result.success ? "completed" : "error" };
+  }
+  return t;
+}),
+```
+
+This is superseded by the parallel execution refactor in §5.3 which handles multiple tasks correctly.
+
+---
+
+### 5.3 Issue 3: Parallel Task Execution
+
+#### 5.3.1 Current Bottleneck
+
+Two layers enforce sequential execution:
+1. **Graph engine** (`compiled.ts:383`): FIFO queue processes one node at a time
+2. **Worker node** (`graph.ts:154`): Takes only `ready[0]` from `getReadyTasks()`
+
+> **Research:** [`research/docs/2026-02-28-workflow-issues-research.md`](../research/docs/2026-02-28-workflow-issues-research.md) §3.1–§3.2
+
+#### 5.3.2 Proposed Solution: Intra-Node Parallelism
+
+Modify the worker node to dispatch **all** ready tasks concurrently via `spawnSubagentParallel`, while keeping the graph engine sequential.
+
+**Modified Worker Node (`graph.ts`):**
+
+```typescript
+{
+  id: "worker",
+  type: "agent",
+  retry: { maxAttempts: 1, backoffMs: 0, backoffMultiplier: 1 },
+  async execute(ctx: ExecutionContext<RalphWorkflowState>): Promise<NodeResult<RalphWorkflowState>> {
+    const spawnSubagentParallel = ctx.config.runtime?.spawnSubagentParallel;
+    if (!spawnSubagentParallel) {
+      throw new Error("spawnSubagentParallel not available in runtime config");
+    }
+
+    const ready = ctx.state.currentTasks;
+    if (ready.length === 0) {
+      return {
+        stateUpdate: { iteration: ctx.state.iteration + 1 },
+      };
+    }
+
+    // Set all ready tasks to "in_progress" before dispatch (Issue 4 fix)
+    const tasksWithProgress = ctx.state.tasks.map((t) => {
+      const isReady = ready.some((r) => r.id === t.id);
+      return isReady ? { ...t, status: "in_progress" } : t;
+    });
+
+    // Build spawn configs for all ready tasks
+    const spawnConfigs = ready.map((task) => ({
+      agentName: "worker",
+      agentId: `worker-${task.id}`,
+      task: buildWorkerAssignment(task, tasksWithProgress),
+      // ... other spawn options (model, system prompt, etc.)
+    }));
+
+    // Dispatch all ready tasks concurrently
+    const results = await spawnSubagentParallel(spawnConfigs, ctx.abortSignal);
+
+    // Map results back to tasks independently
+    const updatedTasks = tasksWithProgress.map((t) => {
+      const readyIndex = ready.findIndex((r) => r.id === t.id);
+      if (readyIndex === -1) return t;
+      const result = results[readyIndex];
+      return { ...t, status: result?.success ? "completed" : "error" };
+    });
+
+    return {
+      stateUpdate: {
+        iteration: ctx.state.iteration + 1,
+        tasks: updatedTasks,
+      },
+    };
+  },
+}
+```
+
+**Key changes:**
+1. Uses `spawnSubagentParallel` instead of `spawnSubagent`
+2. Dispatches all ready tasks, not just `ready[0]`
+3. Independently tracks each task's success/failure based on its corresponding result
+4. Sets tasks to `"in_progress"` before dispatch (ties into Issue 4)
+5. Increments `iteration` by 1 per batch (not per task)
+
+#### 5.3.3 Loop Iteration Semantics
+
+With parallel execution, `iteration` increments by 1 per loop pass (batch), regardless of how many tasks run concurrently. This matches the existing semantics: one pass through `select-ready-tasks → worker` = one iteration. The `maxIterations` guard (default 100) limits loop passes, not individual task executions.
+
+#### 5.3.4 Dependency Safety
+
+`getReadyTasks()` already ensures only tasks with all dependencies satisfied are returned. Since tasks dispatched in parallel are all dependency-ready at the point of selection, concurrent execution cannot violate dependency ordering. Tasks that depend on currently-executing tasks will not appear in `getReadyTasks()` until the next loop iteration when their dependencies are marked `"completed"`.
+
+> **Research:** [`research/docs/2026-02-28-workflow-issues-research.md`](../research/docs/2026-02-28-workflow-issues-research.md) §3.3–§3.4, [`research/docs/2026-02-15-ralph-dag-orchestration-implementation.md`](../research/docs/2026-02-15-ralph-dag-orchestration-implementation.md)
+
+---
+
+### 5.4 Issue 4: Task List Blinker for Active Tasks
+
+#### 5.4.1 Current Gap
+
+The blink indicator infrastructure exists and works correctly for tasks with `status === "in_progress"`. However, the Ralph worker node transitions tasks directly from `"pending"` → `"completed"`/`"error"` without an intermediate `"in_progress"` state. The blinker only activates if the spawned sub-agent itself sets `"in_progress"` via TodoWrite — which is not guaranteed.
+
+> **Research:** [`research/docs/2026-02-28-workflow-issues-research.md`](../research/docs/2026-02-28-workflow-issues-research.md) §4.7, [`research/docs/2026-02-13-ralph-task-list-ui.md`](../research/docs/2026-02-13-ralph-task-list-ui.md)
+
+#### 5.4.2 Proposed Fix
+
+**Explicit `"in_progress"` status in worker node (already included in §5.3.2):**
+
+Before dispatching tasks, the worker node sets all dispatched tasks to `"in_progress"`. This is then persisted via `saveTasksToSession()` in the executor's `for await` loop, which triggers:
+
+1. `saveTasksToActiveSession()` writes updated `tasks.json`
+2. `watchTasksJson()` in `workflow-commands.ts:719` detects the file change
+3. `TaskListPanel` re-renders with the `"in_progress"` status
+4. `TaskListIndicator` renders `AnimatedBlinkIndicator` for those tasks
+
+**Intermediate state update (emit before parallel spawn):**
+
+To ensure the UI sees `"in_progress"` **before** workers start, we need to emit a state update with the `"in_progress"` tasks prior to awaiting `spawnSubagentParallel`. This requires either:
+
+- **Option A:** Yielding an intermediate state from the worker node (requires node protocol change to support intermediate yields)
+- **Option B:** Writing `tasks.json` directly from the worker node before spawning
+- **Option C:** Accepting the delay — the state update will be visible once the worker node's result is processed by the executor, which may be after the spawn completes
+
+**Recommended: Event-based approach** — The worker node publishes a `workflow.task.statusChange` event via the event bus, and the executor subscribes to persist the change:
+
+```typescript
+// In worker node execute():
+// 1. Set tasks to in_progress in state
+const tasksWithProgress = ctx.state.tasks.map((t) => {
+  const isReady = ready.some((r) => r.id === t.id);
+  return isReady ? { ...t, status: "in_progress" } : t;
+});
+
+// 2. Publish status change event — executor subscriber persists to tasks.json
+ctx.config.runtime?.eventBus?.publish({
+  type: "workflow.task.statusChange",
+  sessionId: ctx.config.sessionId,
+  runId: ctx.config.runId,
+  timestamp: Date.now(),
+  data: {
+    taskIds: ready.map((r) => r.id),
+    newStatus: "in_progress",
+    tasks: tasksWithProgress,
+  },
+});
+
+// 3. Dispatch workers (blinker is already visible via file watcher)
+const results = await spawnSubagentParallel(spawnConfigs, ctx.abortSignal);
+```
+
+This requires:
+- Defining `workflow.task.statusChange` in `bus-events.ts`
+- Adding a bus subscriber in `executor.ts` that calls `saveTasksToSession` on this event
+- Wiring `eventBus` into the runtime config (already partially done via `WorkflowEventAdapter`)
+
+#### 5.4.3 Status Flow After Fix
+
+```
+pending (○ static) → in_progress (● ↔ · blink) → completed (✓ static)
+                                                  → error (✗ static)
+```
+
+---
+
+### 5.5 Issue 5: Streaming Delay After TODO Completion
+
+#### 5.5.1 Identified Delay Sources
+
+Six sources contribute to the delay between the last task completing and the completion summary appearing (see [research §5.5](../research/docs/2026-02-28-workflow-issues-research.md)):
+
+| Source                        | Location                 | Est. Latency           | Fixable?        |
+| ----------------------------- | ------------------------ | ---------------------- | --------------- |
+| **A: Deferred completion**    | `chat.tsx:2516-2556`     | 50-200ms (React chain) | Yes             |
+| **B: SDK `session.idle`**     | Adapter-specific         | 0-3s (SDK-internal)    | Partially       |
+| **C: BatchDispatcher flush**  | `batch-dispatcher.ts:20` | ≤16ms                  | No (acceptable) |
+| **D: File I/O in graph loop** | `executor.ts:301-306`    | 5-50ms per step        | Yes             |
+| **E: React state batching**   | Multiple `set*` calls    | 16-50ms                | Partially       |
+| **F: Task progress check**    | `loading-state.ts:35-55` | 0-16ms                 | No (acceptable) |
+
+> **Research:** [`research/docs/2026-02-28-workflow-issues-research.md`](../research/docs/2026-02-28-workflow-issues-research.md) §5.4–§5.6
+
+#### 5.5.2 Proposed Optimizations
+
+**Fix 5A — Reduce deferred completion latency:**
+
+The deferred completion resolution chain (`stream.agent.complete` → 16ms batch → React state → `useEffect` → `setTimeout(0)` → `handleStreamComplete`) can be shortened by:
+
+1. **Bypass `setTimeout(0)` in `useEffect`** (`chat.tsx:3268`): The `setTimeout(…, 0)` was added to ensure React batch completion, but with React 18+ automatic batching, this is unnecessary. Call `pendingComplete()` directly:
+
+```typescript
+// chat.tsx useEffect at ~3268
+if (pendingCompleteRef.current) {
+  const pendingComplete = pendingCompleteRef.current;
+  pendingCompleteRef.current = null;
+  pendingComplete(); // Direct call instead of setTimeout(0)
+}
+```
+
+2. **Early agent completion detection:** When the last foreground agent's `stream.agent.complete` event is processed in `useBusSubscription("stream.agent.complete")`, immediately check if deferred completion should resolve, rather than waiting for the React re-render → `useEffect` cycle:
+
+```typescript
+// chat.tsx useBusSubscription("stream.agent.complete") handler
+useBusSubscription("stream.agent.complete", (event) => {
+  setParallelAgents((current) => {
+    const updated = current.map((a) =>
+      a.id === event.data.agentId ? { ...a, status: "completed", ... } : a
+    );
+    // Eagerly check deferred completion
+    if (pendingCompleteRef.current && !hasActiveForegroundAgents(updated)) {
+      const pending = pendingCompleteRef.current;
+      pendingCompleteRef.current = null;
+      queueMicrotask(() => pending());
+    }
+    return updated;
+  });
+});
+```
+
+**Fix 5B — Debounce `saveTasksToSession` file I/O:**
+
+Instead of performing `atomicWrite()` on every graph step, debounce task saves:
+
+```typescript
+// executor.ts — debounced task save
+let pendingTaskSave: ReturnType<typeof setTimeout> | null = null;
+let latestTasks: NormalizedTodoItem[] | null = null;
+
+const debouncedSave = async (tasks: NormalizedTodoItem[], sessionId: string) => {
+  latestTasks = tasks;
+  if (pendingTaskSave) clearTimeout(pendingTaskSave);
+  pendingTaskSave = setTimeout(async () => {
+    if (latestTasks && options?.saveTasksToSession) {
+      await options.saveTasksToSession(latestTasks, sessionId);
+    }
+    pendingTaskSave = null;
+  }, 100); // 100ms debounce
+};
+
+// Ensure final save on graph completion
+// After for-await loop:
+if (latestTasks && options?.saveTasksToSession) {
+  await options.saveTasksToSession(latestTasks, sessionId);
+}
+```
+
+**Fix 5C — Consolidate React state updates:**
+
+In `handleStreamComplete()` Path 3 (normal completion), consolidate the nested `setParallelAgents` → `setMessagesWindowed` calls into a single React batch:
+
+```typescript
+// Use ReactDOM.flushSync or unstable_batchedUpdates if needed
+// Or restructure to set both states in a single callback
+import { flushSync } from "react-dom";
+
+flushSync(() => {
+  setParallelAgents(finalizedAgents);
+  setMessagesWindowed(finalizedMessages);
+});
+```
+
+---
+
+## 6. Alternatives Considered
+
+| Option                                                                               | Pros                                  | Cons                                                                                       | Reason for Rejection                                                                                                    |
+| ------------------------------------------------------------------------------------ | ------------------------------------- | ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
+| **Graph-level parallelism** (modify FIFO queue to process nodes concurrently)        | True DAG parallelism                  | High risk — requires rewriting graph engine, state merge conflicts, complex error handling | Unnecessary — intra-node parallelism via `spawnSubagentParallel` achieves the same user-facing result with minimal risk |
+| **Web Worker for sub-agent streams** (offload event processing)                      | Eliminates React main-thread blocking | Adds complexity, requires serialization boundary                                           | Overkill for current scale — event processing is not the primary bottleneck                                             |
+| **Polling-based tool count updates** (poll sub-agent status instead of event-driven) | Guaranteed regular updates            | Higher overhead, less responsive, architectural regression                                 | Event-driven is correct; the fix is ensuring events reach the UI                                                        |
+| **SSE for completion signal** (replace deferred completion with server-sent events)  | Simpler completion model              | Requires infrastructure change, doesn't address root cause (React state)                   | The deferred completion pattern is fundamentally sound; optimizations are sufficient                                    |
+
+> **Research:** [`research/docs/2026-02-25-workflow-sdk-patterns.md`](../research/docs/2026-02-25-workflow-sdk-patterns.md)
+
+## 7. Cross-Cutting Concerns
+
+### 7.1 Error Handling
+
+**Parallel task failures:** When running tasks in parallel, individual task failures must not abort the entire batch. Each task's result is independently tracked:
+
+```typescript
+const results = await spawnSubagentParallel(spawnConfigs, ctx.abortSignal);
+// results[i] corresponds to spawnConfigs[i] / ready[i]
+// Each result has .success boolean — failed tasks become "error", others "completed"
+```
+
+**Abort signal propagation:** The `ctx.abortSignal` is passed to `spawnSubagentParallel`, which should propagate it to all concurrent sub-agents. If the workflow is cancelled, all running workers should abort.
+
+### 7.2 Observability
+
+- **Task execution metrics:** Log the number of parallel tasks dispatched per loop iteration, individual task durations, and success/failure rates
+- **Event pipeline tracing:** Add trace-level logging at each chokepoint identified in Issue 1 to diagnose future "Initializing..." occurrences
+- **Completion latency:** Log timestamps at `handleStreamComplete()` entry, deferred closure creation, and deferred resolution to measure improvement
+
+### 7.3 Performance Impact
+
+- **Parallel execution:** N concurrent tasks consume N× the memory and API tokens. For typical workflows (3-8 independent tasks), this is acceptable. For large task lists (20+), resource pressure may become a concern.
+- **File I/O reduction:** Debouncing `saveTasksToSession` reduces disk writes from once-per-step to once-per-100ms, improving I/O-bound performance.
+- **React render reduction:** Consolidating state updates reduces the number of render cycles during finalization from 3-5 to 1-2.
+
+## 8. Migration, Rollout, and Testing
+
+### 8.1 Deployment Strategy
+
+- [ ] **Phase 1:** Issue 1 (event pipeline fixes) + Issue 4 (in_progress status) — lowest risk, immediate UX improvement
+- [ ] **Phase 2:** Issue 3 (parallel task execution) — moderate risk, requires thorough testing of dependency logic and error handling
+- [ ] **Phase 3:** Issue 5 (completion delay optimization) — requires careful testing to avoid race conditions in finalization
+- [ ] **Phase 4:** Issue 2 (loop exit edge fix in `builder.ts`, worker status marking fix in `graph.ts`)
+
+### 8.2 Test Plan
+
+**Unit Tests:**
+
+| Test Case                                | File                      | Description                                                    |
+| ---------------------------------------- | ------------------------- | -------------------------------------------------------------- |
+| `getReadyTasks returns all ready tasks`  | `graph.test.ts`           | Verify multiple independent tasks are returned                 |
+| `worker dispatches all ready tasks`      | `graph.test.ts`           | Verify `spawnSubagentParallel` is called with all ready tasks  |
+| `independent status tracking`            | `graph.test.ts`           | Verify task A success + task B failure produces correct states |
+| `in_progress status set before dispatch` | `graph.test.ts`           | Verify tasks are set to `"in_progress"` before spawn           |
+| `event buffering in stream pipeline`     | `stream-pipeline.test.ts` | Verify buffered events are flushed when AgentPart is created   |
+| `deferred completion resolves eagerly`   | `chat.test.ts`            | Verify completion fires immediately after last agent completes |
+
+**Integration Tests:**
+
+| Test Case                               | Description                                                                                   |
+| --------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `parallel workflow execution`           | Run Ralph with a task list containing 3 independent tasks; verify all 3 dispatch concurrently |
+| `dependency chain respected`            | Run Ralph with A→B→C chain; verify sequential execution                                       |
+| `mixed parallel and sequential`         | Run Ralph with tasks {A, B (depends on A), C}; verify A+C run in parallel, B runs after A     |
+| `task blinker visible during execution` | Verify `tasks.json` contains `"in_progress"` status during worker execution                   |
+| `completion summary timing`             | Measure delay between last task completion and summary render; verify < 500ms                 |
+
+**E2E Tests:**
+
+| Test Case                                 | Description                                                      |
+| ----------------------------------------- | ---------------------------------------------------------------- |
+| `full Ralph workflow with parallel tasks` | End-to-end workflow execution in TUI with parallel task dispatch |
+| `sub-agent tree shows tool counts`        | Verify "Initializing..." transitions to tool count display       |
+
+## 9. Resolved Questions
+
+1. **Concurrency limit for parallel task execution?**
+   **Decision: No limit** — run all ready tasks concurrently. For typical workflows (3-8 independent tasks), this is acceptable. A configurable `maxConcurrency` option can be added as a future enhancement if rate limiting becomes an issue.
+
+2. **How should `iteration` increment with parallel tasks?**
+   **Decision: 1 per batch** — matches current loop semantics. One pass through `select-ready-tasks → worker` = one iteration, regardless of how many tasks run concurrently. The `maxIterations` guard limits loop passes, not individual task executions.
+
+3. **Event buffer vs. ownership fix for "Initializing..." issue?**
+   **Decision: Both fixes (1A + 1B)** — belt-and-suspenders approach. Fix 1A (ownership registration) prevents the most common failure mode. Fix 1B (event buffering) is a safety net against all remaining race conditions in the AgentPart creation path.
+
+4. **`saveTasksToSession` debounce strategy?**
+   **Decision: Time-based debounce (100ms) with final flush** — matches OpenCode's pattern. OpenCode uses a debounce-and-flush approach with a `pending` map and `setTimeout` to batch pending writes, flushing them periodically rather than on every operation (see [OpenCode Storage](https://deepwiki.com/wiki/anomalyco/opencode)). The final flush on graph completion ensures no state is lost.
+
+5. **Runtime config function vs. event-based approach for task status updates?**
+   **Decision: Event-based approach** — cleaner long-term architecture, consistent with OpenCode's `Bus` + `Session.updatePart()` pattern. The worker node will publish a `workflow.task.statusChange` event (with new status and task IDs) via the event bus, and the executor will subscribe to this event to handle persistence via `saveTasksToSession`. This keeps the worker node decoupled from the persistence mechanism and enables other consumers (e.g., UI) to react to task status changes independently. This requires defining a new `workflow.task.statusChange` bus event type in `bus-events.ts` and adding a subscriber in `executor.ts`.
diff --git a/specs/workflow-sdk-refactor.md b/specs/workflow-sdk-refactor.md
new file mode 100644
index 0000000000..2ed0706a37
--- /dev/null
+++ b/specs/workflow-sdk-refactor.md
@@ -0,0 +1,491 @@
+# Workflow SDK Refactor: Simplified Syntax, Module Consolidation, and Ralph TUI Freeze Fix
+
+| Document Metadata      | Details     |
+| ---------------------- | ----------- |
+| Author(s)              | lavaman131  |
+| Status                 | Draft (WIP) |
+| Team / Owner           | Atomic CLI  |
+| Created / Last Updated | 2026-02-25  |
+
+## 1. Executive Summary
+
+The Workflow SDK's graph engine (`src/graph/`) provides a powerful declarative API with 12 node types, fluent builder chaining, and BFS execution — but the Ralph workflow (`src/ui/commands/workflow-commands.ts`) **does not use it at all**, instead running as a 1195-line procedural command handler. Additionally, the TUI freezes after the review node due to a deferred completion handler that never resolves the `spawnSubagent()` promise. This RFC proposes three coordinated changes: **(1)** simplify the graph builder API to elevate `subagentNode()` and `toolNode()` as first-class chaining primitives (`.subagent()`, `.tool()`), **(2)** consolidate `src/graph/` as a submodule under `src/workflows/` to create a unified module, and **(3)** rewrite Ralph to use the graph engine and fix the TUI freeze caused by `streamCompletionResolverRef` single-slot limitation and deferred completion race conditions.
+
+> **Research basis**: [2026-02-25-workflow-sdk-refactor-research.md](../research/docs/2026-02-25-workflow-sdk-refactor-research.md), [2026-02-25-workflow-sdk-standardization.md](../research/docs/2026-02-25-workflow-sdk-standardization.md), [2026-02-25-workflow-sdk-patterns.md](../research/docs/2026-02-25-workflow-sdk-patterns.md)
+
+---
+
+## 2. Context and Motivation
+
+### 2.1 Current State
+
+```
+src/
+├── graph/              ← Core execution engine (16+ modules, 206-line barrel)
+│   ├── builder.ts      ← GraphBuilder fluent API (7 node types, loops, branching)
+│   ├── compiled.ts     ← GraphExecutor BFS engine
+│   ├── nodes.ts        ← 12 node factory functions
+│   ├── sdk.ts          ← WorkflowSDK class
+│   ├── nodes/ralph.ts  ← Ralph graph nodes (UNUSED at runtime)
+│   └── ...
+├── workflows/          ← Session management + Ralph state/prompts
+│   ├── session.ts
+│   └── ralph/
+│       ├── state.ts    ← RalphWorkflowState (UNUSED by graph)
+│       └── prompts.ts  ← 8 prompt builders (4 UNUSED)
+└── ui/commands/
+    └── workflow-commands.ts  ← Ralph procedural handler (1195 lines)
+```
+
+### 2.2 The Problem
+
+1. **Ralph doesn't use the graph engine.** 1195-line procedural handler bypasses the graph module entirely — duplicate logic, hard to extend.
+2. **TUI freezes after review node.** `spawnSubagent()` promise hangs when deferred completion handler is never invoked; `streamCompletionResolverRef` single-slot bottleneck.
+3. **Verbose API for common patterns.** `subagentNode()`/`toolNode()` factories wrapped in `.then()` — no first-class builder shortcuts.
+4. **Module structure mismatch.** `graph/` and `workflows/` are siblings, but graph _is_ the workflow engine.
+
+---
+
+## 3. Goals and Non-Goals
+
+### 3.1 Functional Goals
+
+- [ ] Add `.subagent(config)` and `.tool(config)` as first-class `GraphBuilder` chaining methods
+- [ ] Consolidate `src/graph/` under `src/workflows/graph/` as a submodule
+- [ ] Rewrite Ralph workflow to use the graph engine via `GraphBuilder` API
+- [ ] Fix the TUI freeze after the review node (deferred completion + stream generation mismatch)
+- [ ] Preserve all existing graph engine functionality (templates, streaming, checkpointing, annotations)
+- [ ] Ensure all existing graph module tests continue to pass after consolidation
+- [ ] Update all import paths across the codebase for the module move
+
+### 3.2 Non-Goals (Out of Scope)
+
+- [ ] We will NOT add new node types beyond `.subagent()` and `.tool()` builder shortcuts
+- [ ] We will NOT add Zod-based runtime state validation in this phase
+- [ ] We will NOT implement function-based (Temporal-style) workflows in this refactor
+- [ ] We will NOT add new checkpointer backends (SQLite/PostgreSQL) — existing Memory/File suffice
+- [ ] We will NOT refactor the TUI layer (`chat.tsx`) beyond the minimum needed to fix the freeze
+- [ ] We will NOT add a hooks system (Copilot SDK-style `onPreToolUse`, etc.) in this phase
+
+- [ ] We will NOT change the workflow discovery system (`.atomic/workflows/` paths)
+
+---
+
+## 4. Proposed Solution (High-Level Design)
+
+### 4.1 System Architecture Diagram (Proposed)
+
+```mermaid
+%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#f8f9fa','primaryTextColor':'#2c3e50','primaryBorderColor':'#4a5568','lineColor':'#4a90e2','secondaryColor':'#ffffff','tertiaryColor':'#e9ecef'}}}%%
+
+flowchart TB
+    classDef active fill:#48bb78,stroke:#38a169,stroke-width:2px,color:#ffffff,font-weight:600
+    classDef core fill:#4a90e2,stroke:#357abd,stroke-width:2px,color:#ffffff,font-weight:600
+    classDef ui fill:#667eea,stroke:#5a67d8,stroke-width:2px,color:#ffffff,font-weight:600
+
+    User(("User")):::active
+
+    subgraph UI["src/ui/"]
+        ChatTSX["chat.tsx<br><i>Fixed completion handler</i>"]:::ui
+        IndexTS["index.ts<br><i>Stream handler</i>"]:::ui
+        WfCmds["workflow-commands.ts<br><i>Thin adapter → graph</i>"]:::ui
+    end
+
+    subgraph Workflows["src/workflows/ (Consolidated)"]
+        direction TB
+        WfIndex["index.ts<br><i>Unified barrel</i>"]:::active
+        Session["session.ts"]:::active
+
+        subgraph GraphEngine["graph/ (Submodule)"]
+            Builder["GraphBuilder<br><i>+ .subagent() + .tool()</i>"]:::core
+            Executor["GraphExecutor"]:::core
+            Nodes["Node Factories"]:::core
+            SDK["WorkflowSDK"]:::core
+        end
+
+        subgraph Ralph["ralph/"]
+            RalphGraph["graph.ts<br><i>Graph-based workflow</i>"]:::active
+            RalphState["state.ts"]:::active
+            RalphPrompts["prompts.ts"]:::active
+        end
+    end
+
+    User --> ChatTSX
+    ChatTSX --> WfCmds
+    WfCmds -->|"uses"| RalphGraph
+    RalphGraph -->|"uses"| Builder
+    RalphGraph -->|"uses"| Nodes
+    Builder --> Executor
+
+    style Workflows fill:#f0fff4,stroke:#68d391,stroke-width:2px
+    style GraphEngine fill:#ebf8ff,stroke:#63b3ed,stroke-width:2px
+```
+
+### 4.3 Key Components
+
+| Component                      | Responsibility               | Change Type | Justification                                                                    |
+| ------------------------------ | ---------------------------- | ----------- | -------------------------------------------------------------------------------- |
+| `GraphBuilder`                 | Fluent workflow construction | Extended    | `.subagent()` and `.tool()` reduce boilerplate for the most common node types    |
+| `src/workflows/graph/`         | Core execution engine        | Moved       | Logical grouping under `workflows/` reflects that graph _is_ the workflow engine |
+| `src/workflows/ralph/graph.ts` | Ralph workflow definition    | New         | Expresses Ralph as a graph, replacing 1195-line procedural handler               |
+| `src/ui/chat.tsx`              | TUI completion handling      | Patched     | Fixes deferred completion race condition causing freeze                          |
+| `src/ui/index.ts`              | Stream abort handling        | Patched     | Ensures `onComplete()` fires on abort paths                                      |
+
+---
+
+## 5. Detailed Design
+
+### 5.1 Builder API Extension
+
+Add `.subagent()`, `.tool()`, and `.if()` to `GraphBuilder<TState>` — thin wrappers that encapsulate logic via config objects. `.if()` takes a `{ condition, then, else? }` config with nested `NodeDefinition[]` arrays (same pattern as `.loop()`). The first chained call auto-detects as the entry point; the graph terminates after the last node.
+
+**Config interfaces:**
+
+```typescript
+interface SubAgentConfig<TState extends BaseState> {
+    id: string;
+    agent: string;
+    task: string | ((state: TState) => string);
+    systemPrompt?: string | ((state: TState) => string);
+    model?: string;
+    tools?: string[];
+    outputMapper?: (result: SubagentResult, state: TState) => Partial<TState>;
+    retry?: RetryConfig;
+    name?: string;
+    description?: string;
+}
+
+interface ToolConfig<TState extends BaseState, TArgs, TResult> {
+    id: string;
+    toolName?: string;
+    execute?: (args: TArgs, abortSignal?: AbortSignal) => Promise<TResult>;
+    args?: TArgs | ((state: TState) => TArgs);
+    outputMapper?: (result: TResult, state: TState) => Partial<TState>;
+    timeout?: number;
+    retry?: RetryConfig;
+    name?: string;
+    description?: string;
+}
+
+interface IfConfig<TState extends BaseState> {
+    condition: (state: TState) => boolean;
+    then: NodeDefinition<TState>[];
+    else_if?: {
+        condition: (state: TState) => boolean;
+        then: NodeDefinition<TState>[];
+    }[];
+    else?: NodeDefinition<TState>[];
+}
+```
+
+**Example:**
+
+```typescript
+graph<MyState>()
+    .subagent({
+        id: "planner",
+        agent: "copilot",
+        task: (state) => buildPlannerPrompt(state),
+        outputMapper: (result, state) => ({ plan: result.output }),
+    })
+    .tool({
+        id: "parse-tasks",
+        execute: async (args) => parseTasks(args.plan),
+        args: (state) => ({ plan: state.plan }),
+        outputMapper: (result, state) => ({ tasks: result }),
+    })
+    .subagent({
+        id: "worker",
+        agent: "copilot",
+        task: (state) => buildWorkerPrompt(state),
+    })
+    .compile();
+```
+
+> _Ref: [Patterns §"Recommendations for Standardized Workflow SDK"](../research/docs/2026-02-25-workflow-sdk-patterns.md) for external API inspiration_
+
+### 5.2 Module Consolidation
+
+**Move `src/graph/` → `src/workflows/graph/`:**
+
+```
+src/workflows/
+├── index.ts              ← Unified barrel (re-exports graph/ + session + ralph)
+├── session.ts
+├── graph/                ← Moved from src/graph/
+│   ├── index.ts          ← Existing barrel
+│   ├── builder.ts        ← Extended with .subagent(), .tool()
+│   ├── compiled.ts, types.ts, nodes.ts, annotation.ts
+│   ├── templates.ts, stream.ts, sdk.ts, errors.ts
+│   ├── agent-providers.ts, provider-registry.ts
+│   ├── subagent-bridge.ts, subagent-registry.ts
+│   ├── checkpointer.ts, state-validator.ts
+│   └── __tests__/
+└── ralph/
+    ├── graph.ts           ← NEW: Graph-based workflow
+    ├── state.ts           ← Updated with proper annotations
+    └── prompts.ts         ← Cleaned (unused prompts removed)
+```
+
+**Barrel & imports**: `src/workflows/index.ts` re-exports `graph/`, `session.ts`, and `ralph/`. All existing `src/graph/` imports updated to `src/workflows/graph/` in a single pass — no shim.
+
+### 5.3 Ralph Graph Rewrite
+
+Express Ralph's 3-phase flow as a compiled graph:
+
+```typescript
+// src/workflows/ralph/graph.ts
+
+import {
+    graph,
+    subagentNode,
+    toolNode,
+    type BaseState,
+} from "../graph/index.ts";
+import type { RalphWorkflowState } from "./state.ts";
+import {
+    buildSpecToTasksPrompt,
+    buildWorkerAssignment,
+    buildReviewPrompt,
+    buildFixPrompt,
+} from "./prompts.ts";
+
+export function createRalphWorkflow() {
+    return (
+        graph<RalphWorkflowState>()
+            // Phase 1: Task Decomposition
+            .subagent({
+                id: "planner",
+                agent: "planner",
+                task: (state) => buildSpecToTasksPrompt(state),
+                outputMapper: (result, state) => ({
+                    specDoc: result.output ?? "",
+                }),
+                description: "Decomposes user prompt into a task list / spec",
+            })
+            .tool({
+                id: "parse-tasks",
+                execute: async (args) => parseSpecToTasks(args.specDoc),
+                args: (state) => ({ specDoc: state.specDoc }),
+                outputMapper: (tasks, state) => ({
+                    tasks,
+                    iteration: 0,
+                }),
+                description: "Parse spec document into structured task list",
+            })
+
+            // Phase 2: Worker Loop
+            .loop(
+                [
+                    toolNode({
+                        id: "select-ready-tasks",
+                        toolName: "select-ready-tasks",
+                        execute: async (args) => getReadyTasks(args.tasks),
+                        args: (state) => ({ tasks: state.tasks }),
+                        outputMapper: (readyTasks, state) => ({
+                            currentTasks: readyTasks,
+                        }),
+                        name: "Task Selector",
+                    }),
+                    subagentNode({
+                        id: "worker",
+                        agentName: "worker",
+                        task: (state) => buildWorkerAssignment(state),
+                        outputMapper: (result, state) => ({
+                            iteration: state.iteration + 1,
+                            tasks: markTasksCompleted(state.tasks, result),
+                        }),
+                        name: "Worker",
+                        description: "Implements assigned tasks",
+                    }),
+                ],
+                {
+                    until: (state) =>
+                        state.tasks.every((t) => t.status === "completed") ||
+                        state.iteration >= state.maxIterations,
+                    maxIterations: 100,
+                },
+            )
+
+            // Phase 3: Review & Fix
+            .subagent({
+                id: "reviewer",
+                agent: "reviewer",
+                task: (state) => buildReviewPrompt(state),
+                outputMapper: (result, state) => ({
+                    reviewResult: parseReviewResult(result.output),
+                }),
+                description: "Reviews completed work",
+            })
+            .if({
+                condition: (state) => state.reviewResult?.fixesNeeded === true,
+                then: [
+                    subagentNode({
+                        id: "fixer",
+                        agentName: "worker",
+                        task: (state) => buildFixPrompt(state),
+                        outputMapper: (result, state) => ({
+                            fixesApplied: true,
+                        }),
+                        description: "Applies review fixes",
+                    }),
+                ],
+            })
+            .compile({
+                name: "ralph",
+                description:
+                    "Autonomous task decomposition, implementation, and review workflow",
+            })
+    );
+}
+```
+
+**Thin adapter in `workflow-commands.ts`:** Replaces the 1195-line procedural handler with ~50 lines that parse `/ralph` args, create initial state, call `createRalphWorkflow()`, and pipe `StepResult` events to the TUI. Session/discovery logic stays.
+
+### 5.4 TUI Freeze Fix
+
+**Root cause**: In `chat.tsx:3638-3647`, deferred completion handler (`pendingCompleteRef.current`) is set when `hasActiveAgents || hasRunningToolRef.current` is true. If `tryFinalizeParallelTracking()` never fires, `spawnSubagent()` promise hangs.
+
+**Fix 1: Spawn-initiation timeout** (`chat.tsx`) — 30s timeout if sub-agent was never spawned; no timeout once spawned:
+
+```typescript
+if (hasActiveAgents || hasRunningToolRef.current) {
+    pendingCompleteRef.current = handleComplete;
+    const spawnTimeout = setTimeout(() => {
+        if (
+            pendingCompleteRef.current === handleComplete &&
+            !subagentSpawnedRef.current
+        ) {
+            pendingCompleteRef.current = null;
+            handleComplete();
+        }
+    }, 30_000);
+    const originalHandleComplete = handleComplete;
+    pendingCompleteRef.current = () => {
+        clearTimeout(spawnTimeout);
+        originalHandleComplete();
+    };
+    return;
+}
+```
+
+**Fix 2: `onComplete()` on abort** (`index.ts`) — call `onComplete({ aborted: true, response })` on `AbortError` instead of silently returning.
+
+**Fix 3: Generation guard relaxation** (`chat.tsx`) — accept callbacks from current generation OR immediately preceding one (off-by-one tolerance):
+
+```typescript
+if (
+    !isCurrentStreamCallback(streamGenerationRef.current, currentGeneration) &&
+    currentGeneration < streamGenerationRef.current - 1
+) {
+    return;
+}
+```
+
+### 5.5 Ralph State Annotations
+
+```typescript
+// src/workflows/ralph/state.ts
+export const RalphWorkflowState = {
+    specDoc: annotation<string>("", Reducers.replace),
+    tasks: annotation<Task[]>([], Reducers.replace),
+    currentTasks: annotation<Task[]>([], Reducers.replace),
+    iteration: annotation<number>(0, Reducers.replace),
+    maxIterations: annotation<number>(100, Reducers.replace),
+    reviewResult: annotation<ReviewResult | null>(null, Reducers.replace),
+    fixesApplied: annotation<boolean>(false, Reducers.replace),
+    ralphSessionId: annotation<string>("", Reducers.replace),
+    ralphSessionDir: annotation<string>("", Reducers.replace),
+};
+```
+
+---
+
+## 6. Alternatives Considered
+
+| Option                                                                               | Pros                                                                           | Cons                                                                                         | Reason for Rejection                                                                                                                                               |
+| ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **A: Fix freeze only, keep Ralph procedural**                                        | Minimal change, fast fix                                                       | Doesn't address the core problem of Ralph not using graph; continues dual maintenance burden | Short-term band-aid; graph engine remains unused for its primary use case                                                                                          |
+| **B: Re-export `graph/` through `workflows/` without moving files**                  | No file moves, no import changes                                               | Misleading file structure; `graph/` still appears as a top-level peer                        | Doesn't achieve the consolidation goal; confusing for new contributors                                                                                             |
+| **C: Add `.agent()` builder method (unify `agentNode` + `subagentNode`)**            | Fewer node types to understand                                                 | Different use cases (session-based agent vs spawned sub-agent) need distinct configs         | Premature unification; research shows they serve different purposes ([Research §1.1](../research/docs/2026-02-25-workflow-sdk-refactor-research.md#11-node-types)) |
+| **D: Full function-based workflow API (Temporal-style)**                             | Supports imperative patterns natively                                          | Massive scope increase; existing graph engine would need parallel API                        | Better suited for a future phase; graph-based approach already works for Ralph ([Patterns doc](../research/docs/2026-02-25-workflow-sdk-patterns.md))              |
+| **E: Selected approach (builder extension + module move + Ralph rewrite + TUI fix)** | Addresses all three problems; minimal API additions; leverages existing engine | Requires import path updates; Ralph rewrite needs careful testing                            | **Selected**: Balances scope, impact, and risk. Maximizes ROI on existing graph engine investment                                                                  |
+
+---
+
+## 7. Cross-Cutting Concerns
+
+### 7.1 Breaking Changes
+
+This refactor introduces breaking changes. There is no backward compatibility layer — all consumers must update.
+
+- **Import paths**: All `src/graph/` imports are replaced with `src/workflows/graph/`. No shim or re-export bridge is provided.
+- **Ralph workflow**: The procedural handler in `workflow-commands.ts` is fully replaced with a graph-based implementation. The `/ralph` command behavior is preserved but the internal execution path is entirely different.
+- **Deleted files**: `src/graph/nodes/ralph.ts` (unused graph nodes), 4 unused prompt builders in `prompts.ts`, the entire `src/graph/` directory (moved to `src/workflows/graph/`).
+
+### 7.2 Testing Strategy
+
+- **Regression**: All 13 existing `src/graph/__tests__/` files pass after module move (path updates only)
+- **Unit**: `.subagent()`, `.tool()` produce equivalent `NodeDefinition` to factory functions
+- **Integration**: `createRalphWorkflow()` with mocked `SubagentGraphBridge` — 3-phase flow, loop exit, conditional fix
+- **E2E**: `/ralph` with review that triggers fixes — no freeze
+
+**Observability**: Existing `StepResult` events + `StreamRouter` debug mode — no new instrumentation needed. **Performance**: BFS traversal overhead negligible; same spread-copy immutability as procedural handler.
+
+---
+
+## 8. Migration, Rollout, and Testing
+
+### 8.1 Deployment Strategy (Phased)
+
+- [ ] **Phase 1: Module consolidation** — Move `src/graph/` → `src/workflows/graph/`, update ALL import paths immediately (no shim), delete `src/graph/nodes/ralph.ts`, verify all tests pass.
+- [ ] **Phase 2: Builder API extension** — Add `.subagent()` and `.tool()` methods to `GraphBuilder` with implicit start detection. Add unit tests for new API surface.
+- [ ] **Phase 3: TUI freeze fix** — Apply the three fixes to `chat.tsx` and `index.ts` (30s spawn-initiation timeout, abort `onComplete`, generation guard relaxation). Manual E2E test.
+- [ ] **Phase 4: Ralph graph rewrite** — Create fresh `ralph/graph.ts` with parallel worker dispatch, update `workflow-commands.ts` to use it, remove procedural Ralph code, remove unused prompts from `prompts.ts`. Integration tests.
+- [ ] **Phase 5: Cleanup** — Remove dead code, update documentation.
+
+### 8.2 Rollback Plan
+
+Each phase is independently deployable. If Ralph graph rewrite causes issues, the procedural handler can be restored by reverting Phase 4 only.
+
+---
+
+## 9. Resolved Decisions
+
+| #   | Question                                      | Decision                                                                                                                        |
+| --- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| 1   | Re-export shim or update imports immediately? | Update all imports in single pass, no shim                                                                                      |
+| 2   | Flow control API?                             | No `.start()`/`.end()`/`.endif()` — `.if({ condition, then, else? })` encapsulates conditional logic recursively like `.loop()` |
+| 3   | Parallel worker dispatch for Ralph?           | Yes — use graph engine's `parallel()` node; address `streamCompletionResolverRef` limitation                                    |
+| 4   | Deferred completion timeout?                  | 30s spawn-initiation timeout only (not execution); unbounded once spawned                                                       |
+| 5   | Remove unused Ralph prompts?                  | Yes — 4 unused prompt builders deleted (in git history)                                                                         |
+| 6   | Incorporate existing `nodes/ralph.ts`?        | No — replace with fresh definitions; existing were never runtime-tested                                                         |
+
+---
+
+## Appendix
+
+### A. File Change Impact Summary
+
+| File/Directory                         | Change                                      | Risk                               |
+| -------------------------------------- | ------------------------------------------- | ---------------------------------- |
+| `src/graph/` → `src/workflows/graph/`  | Move entire directory                       | Low (file move + import updates)   |
+| `src/workflows/graph/builder.ts`       | Add `.subagent()` and `.tool()` methods     | Low (additive)                     |
+| `src/workflows/ralph/graph.ts`         | New file: graph-based Ralph workflow        | Medium (new logic)                 |
+| `src/ui/commands/workflow-commands.ts` | Replace procedural Ralph with graph adapter | High (major rewrite of ~500 lines) |
+| `src/ui/chat.tsx`                      | Fix deferred completion handler             | Medium (sensitive area, many refs) |
+| `src/ui/index.ts`                      | Fix abort path to call `onComplete()`       | Low (small change)                 |
+| `src/workflows/index.ts`               | Update barrel to re-export graph + ralph    | Low                                |
+| All files importing from `src/graph/`  | Update import paths                         | Low (mechanical)                   |
+
+### B. Research Documents Referenced
+
+| Document                                                                                                                                      | Relevance                                                                  |
+| --------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| [2026-02-25-workflow-sdk-refactor-research.md](../research/docs/2026-02-25-workflow-sdk-refactor-research.md)                                 | Primary research — module structure, Ralph analysis, TUI freeze root cause |
+| [2026-02-25-workflow-sdk-standardization.md](../research/docs/2026-02-25-workflow-sdk-standardization.md)                                     | Current state analysis — all node types, builder API, execution engine     |
+| [2026-02-25-workflow-sdk-patterns.md](../research/docs/2026-02-25-workflow-sdk-patterns.md)                                                   | External patterns — LangGraph, Temporal, Inngest API inspiration           |
+| [2026-02-25-graph-execution-engine-technical-documentation.md](../research/docs/2026-02-25-graph-execution-engine-technical-documentation.md) | Graph engine deep dive                                                     |
+| [2026-02-15-subagent-premature-completion-SUMMARY.md](../research/docs/2026-02-15-subagent-premature-completion-SUMMARY.md)                   | Sub-agent completion bug context                                           |
+| [2026-02-15-ralph-dag-orchestration-implementation.md](../research/docs/2026-02-15-ralph-dag-orchestration-implementation.md)                 | `streamCompletionResolverRef` single-slot limitation                       |
+| [2026-02-03-custom-workflow-file-format.md](../research/docs/2026-02-03-custom-workflow-file-format.md)                                       | Workflow file format and discovery paths                                   |
diff --git a/specs/workflow-sdk-standardization.md b/specs/workflow-sdk-standardization.md
new file mode 100644
index 0000000000..adb42c4996
--- /dev/null
+++ b/specs/workflow-sdk-standardization.md
@@ -0,0 +1,743 @@
+# Workflow SDK Standardization: Unified Graph Engine, Declarative API & Provider-Agnostic Execution
+
+| Document Metadata      | Details                                                    |
+| ---------------------- | ---------------------------------------------------------- |
+| Author(s)              | lavaman131                                                 |
+| Status                 | Draft (WIP)                                                |
+| Team / Owner           | Atomic Core                                                |
+| Created / Last Updated | 2026-02-25                                                 |
+| Research Reference     | `research/docs/2026-02-25-workflow-sdk-standardization.md` |
+
+## 1. Executive Summary
+
+This RFC proposes standardizing the Atomic workflow SDK into a cohesive, user-friendly package that wraps the existing graph execution engine (`src/graph/`), sub-agent system, and workflow discovery into a clean public API. The current implementation — while powerful with 12 node factories, fluent builder API, typed state annotations, and BFS-based execution — suffers from fragmented initialization (6+ global singletons), tightly-coupled Ralph-specific state schemas, undocumented public API boundaries, and missing features identified across LangGraph, Temporal, and Inngest (multi-mode streaming, runtime state validation, checkpointing backends, error type hierarchy). The proposed standardization introduces: (1) a **unified `WorkflowSDK` entry point** that replaces and removes scattered global setters with a single initialization, (2) a **provider-agnostic sub-agent abstraction** decoupled from specific coding agent SDKs, (3) **multi-mode streaming** (values, updates, events, debug), (4) **Zod-based runtime state validation**, (5) a **higher-level workflow template system** for common patterns, and (6) a **clean public API surface** with barrel exports and comprehensive documentation. This is a **breaking change** — all legacy global setters, Ralph-specific types in `src/graph/`, and the `AgentNodeAgentType` union are completely removed. This consolidation reduces the authoring complexity for custom workflows from ~50 lines of boilerplate to ~15 lines while maintaining full power-user access to the graph API.
+
+**Research Reference:** [Workflow SDK Standardization Research](research/docs/2026-02-25-workflow-sdk-standardization.md), [External SDK Patterns Analysis](research/docs/2026-02-25-workflow-sdk-patterns.md), [Graph Engine Technical Docs](research/docs/2026-02-25-graph-execution-engine-technical-documentation.md)
+
+## 2. Context and Motivation
+
+### 2.1 Current State
+
+The Atomic CLI workflow system spans three architectural layers with 9,000+ lines of TypeScript across the graph engine, SDK clients, and workflow modules:
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│                   Workflow Discovery Layer                        │
+│  .atomic/workflows/*.ts (local) + ~/.atomic/workflows/*.ts       │
+│  loadWorkflowsFromDisk() → dynamic import → register as /cmd    │
+├──────────────────────────────────────────────────────────────────┤
+│                   Graph Engine (src/graph/)                       │
+│  builder.ts   │ compiled.ts  │ nodes.ts (12 node factories)      │
+│  annotation.ts (typed state + 9 reducers)                        │
+│  subagent-bridge.ts │ subagent-registry.ts                       │
+│  checkpointer.ts (Memory, File, Research, Session backends)      │
+├──────────────────────────────────────────────────────────────────┤
+│                   SDK Abstraction (src/sdk/)                      │
+│  base-client.ts │ types.ts (unified Session, Event interfaces)   │
+│  clients/ (Claude, OpenCode, Copilot implementations)            │
+│  tools/ (discovery, plugin, schema-utils)                        │
+├──────────────────────────────────────────────────────────────────┤
+│                   Workflow Session (src/workflows/)               │
+│  session.ts (WorkflowSession lifecycle, tasks.json persistence)  │
+│  index.ts (exports)                                              │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+**Architecture Strengths** ([Research §1](research/docs/2026-02-25-workflow-sdk-standardization.md#1-graph-execution-engine)):
+
+- Fluent builder API (`graph<T>().start().then().if().loop().end().compile()`)
+- LangGraph-inspired annotation system with 9 built-in reducers (`Reducers.concat`, `merge`, `replace`, etc.)
+- BFS graph executor with retry logic, checkpointing, and signal handling
+- Sub-agent bridge supporting Claude, OpenCode, and Copilot SDKs
+- Workflow discovery from `.atomic/workflows/` directories
+
+**Architecture Limitations:**
+
+- 6+ global singletons requiring manual initialization order: `setClientProvider()`, `setSubagentBridge()`, `setSubagentRegistry()`, `setWorkflowResolver()` ([Research §4.4](research/docs/2026-02-25-workflow-sdk-standardization.md#44-global-singleton-pattern))
+- Ralph-specific state (`RalphStateAnnotation`, `RalphWorkflowState`) mixed into the core graph module ([Research §2.3](research/docs/2026-02-25-workflow-sdk-standardization.md#23-predefined-state-schemas))
+- Single stream mode (`StepResult` per node) vs. LangGraph's 6 streaming modes ([Research §7.2](research/docs/2026-02-25-workflow-sdk-standardization.md#72-workflow-orchestration-frameworks))
+- No runtime state validation despite annotation system ([Research §12.2](research/docs/2026-02-25-workflow-sdk-standardization.md#12-open-questions))
+- Serial worker dispatch in Ralph despite `spawnParallel()` existing ([Research §5.3](research/docs/2026-02-25-workflow-sdk-standardization.md#53-phase-2-dag-worker-dispatch))
+- No workflow versioning or migration support ([Research §12.3](research/docs/2026-02-25-workflow-sdk-standardization.md#12-open-questions))
+
+### 2.2 The Problem
+
+**User Impact:** Custom workflow authors must understand internal initialization order, manually wire global singletons, and navigate a 304-line barrel export to find the right types and factories. The absence of a unified entry point makes the SDK hostile to new users.
+
+**Developer Experience:** Writing a simple sequential workflow requires importing from 4+ modules (`graph`, `annotation`, `nodes`, `types`), setting up client providers, and understanding the full `BaseState` contract. Common patterns like "task decomposition → parallel dispatch → review" have no reusable templates.
+
+**Technical Debt:** Ralph-specific state annotations and prompt builders are embedded in the core `src/graph/` module rather than isolated in the workflow layer. The graph engine cannot be used independently without pulling in Ralph-specific types. The 12 node factories lack consistent configuration patterns (some use `outputMapper`, others use `merge`, others use `inputMapper`).
+
+**Provider Lock-in:** Sub-agent nodes are tightly coupled to the `AgentNodeAgentType` union (`"claude" | "opencode" | "copilot"`). Adding a new provider requires modifying core types rather than registering a plugin.
+
+## 3. Goals and Non-Goals
+
+### 3.1 Functional Goals
+
+- [ ] **G1:** Provide a single `WorkflowSDK.init()` entry point that replaces all 6+ global setter calls with one configuration object
+- [ ] **G2:** Extract Ralph-specific state/types from `src/graph/` into `src/workflows/ralph/` and remove them from `src/graph/` entirely — no re-exports
+- [ ] **G3:** Implement multi-mode streaming: `values` (full state), `updates` (partial deltas), `events` (custom node emissions), `debug` (execution trace)
+- [ ] **G4:** Add optional Zod-based runtime state validation at node boundaries with a `schema` field on `NodeDefinition`
+- [ ] **G5:** Create workflow templates for common patterns: `sequential`, `mapReduce`, `taskLoop`, `reviewCycle`
+- [ ] **G6:** Standardize node factory configuration with consistent `inputMapper`/`outputMapper` patterns across all node types
+- [ ] **G7:** Decouple sub-agent execution from hardcoded agent types via a `ProviderRegistry` pattern
+- [ ] **G8:** Add workflow versioning metadata to exported workflow definitions
+- [ ] **G9:** Implement node-level error handlers (beyond graph-level `catch()`) with `onError` hooks returning `"retry" | "skip" | "abort"`
+- [ ] **G10:** Document the complete public API surface with JSDoc, usage examples, and a "Getting Started" guide
+
+### 3.2 Non-Goals (Out of Scope)
+
+- [ ] We will NOT add new checkpointing backends (PostgreSQL, Redis) in this phase — existing Memory/File/Session backends are sufficient
+- [ ] We will NOT implement a visual workflow editor or drag-and-drop UI
+- [ ] We will NOT change the BFS execution strategy to support event sourcing (Temporal-style)
+- [ ] We will NOT provide backward-compatible shims — existing custom workflows must be updated to use the new API
+- [ ] We will NOT add a YAML/JSON workflow definition format — TypeScript-first remains the paradigm
+- [ ] We will NOT implement distributed execution across multiple machines
+
+## 4. Proposed Solution (High-Level Design)
+
+### 4.1 System Architecture Diagram
+
+```mermaid
+%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#f8f9fa','primaryTextColor':'#2c3e50','primaryBorderColor':'#4a5568','lineColor':'#4a90e2','secondaryColor':'#ffffff','tertiaryColor':'#e9ecef','background':'#f5f7fa','mainBkg':'#f8f9fa','nodeBorder':'#4a5568','clusterBkg':'#ffffff','clusterBorder':'#cbd5e0','edgeLabelBackground':'#ffffff'}}}%%
+
+flowchart TB
+    classDef userLayer fill:#5a67d8,stroke:#4c51bf,stroke-width:2.5px,color:#ffffff,font-weight:600
+    classDef sdkLayer fill:#4a90e2,stroke:#357abd,stroke-width:2.5px,color:#ffffff,font-weight:600
+    classDef engineLayer fill:#48bb78,stroke:#38a169,stroke-width:2.5px,color:#ffffff,font-weight:600
+    classDef providerLayer fill:#718096,stroke:#4a5568,stroke-width:2.5px,color:#ffffff,font-weight:600,stroke-dasharray:6 3
+
+    User(("◉ Workflow Author")):::userLayer
+
+    subgraph PublicAPI["◆ Workflow SDK Public API"]
+        direction TB
+
+        Init["<b>WorkflowSDK.init()</b><br><i>Single entry point</i>"]:::sdkLayer
+        Templates["<b>Workflow Templates</b><br>sequential · mapReduce<br>taskLoop · reviewCycle"]:::sdkLayer
+        Builder["<b>GraphBuilder&lt;T&gt;</b><br>Fluent chaining API<br>.start().then().if().loop()"]:::sdkLayer
+    end
+
+    subgraph Engine["◆ Graph Execution Engine"]
+        direction TB
+
+        Executor["<b>GraphExecutor</b><br>BFS traversal · retry<br>multi-mode streaming"]:::engineLayer
+        Nodes["<b>Node Factories</b><br>12 types · Zod validation<br>node-level onError hooks"]:::engineLayer
+        State["<b>Annotation System</b><br>Typed state · 9 reducers<br>runtime validation"]:::engineLayer
+    end
+
+    subgraph Providers["◆ Provider Registry"]
+        direction LR
+        Claude{{"Claude SDK"}}:::providerLayer
+        Copilot{{"Copilot SDK"}}:::providerLayer
+        OpenCode{{"OpenCode SDK"}}:::providerLayer
+        Custom{{"Custom Provider"}}:::providerLayer
+    end
+
+    User -->|"Define workflow"| PublicAPI
+    Init -->|"Configure"| Engine
+    Templates -->|"Pre-built graphs"| Builder
+    Builder -->|"compile()"| Executor
+    Executor -->|"spawn agents"| Providers
+    Nodes -->|"execute nodes"| State
+
+    style PublicAPI fill:#ffffff,stroke:#cbd5e0,stroke-width:2px,color:#2d3748,stroke-dasharray:8 4
+    style Engine fill:#ffffff,stroke:#cbd5e0,stroke-width:2px,color:#2d3748,stroke-dasharray:8 4
+    style Providers fill:#ffffff,stroke:#cbd5e0,stroke-width:2px,color:#2d3748,stroke-dasharray:8 4
+```
+
+### 4.2 Architectural Pattern
+
+We adopt a **Layered SDK with Registry-based Dependency Injection** pattern:
+
+1. **Public API Layer** — Clean entry points, workflow templates, and builder facade. This is the only layer custom workflow authors interact with.
+2. **Engine Layer** — Graph execution, state management, node execution. Internal to the SDK, exposed via typed interfaces.
+3. **Provider Layer** — Pluggable coding agent SDK adapters. New providers added without modifying engine code.
+
+This pattern is informed by converging patterns across LangGraph (typed state + reducers + declarative composition), Temporal (durable execution + error hierarchy), and Inngest (step-based memoization + declarative functions) as documented in [Research §7](research/docs/2026-02-25-workflow-sdk-standardization.md#7-external-sdk-patterns).
+
+### 4.3 Key Components
+
+| Component           | Responsibility                                             | Technology Stack                     | Justification                                                                                                                                          |
+| ------------------- | ---------------------------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `WorkflowSDK`       | Single initialization, provider registration, global state | TypeScript class                     | Replaces 6+ global setters ([Research §4.4](research/docs/2026-02-25-workflow-sdk-standardization.md#44-global-singleton-pattern))                     |
+| `ProviderRegistry`  | Maps agent types to SDK clients dynamically                | TypeScript Map + interface           | Decouples from hardcoded `AgentNodeAgentType` union                                                                                                    |
+| `StreamRouter`      | Multi-mode streaming from executor to consumers            | AsyncGenerator + tagged unions       | Mirrors LangGraph's 6 streaming modes ([Research §7.2](research/docs/2026-02-25-workflow-sdk-standardization.md#72-workflow-orchestration-frameworks)) |
+| `StateValidator`    | Optional Zod-based runtime state validation                | Zod schemas + annotation integration | Addresses [Research §12.2](research/docs/2026-02-25-workflow-sdk-standardization.md#12-open-questions)                                                 |
+| `WorkflowTemplates` | Pre-built graph patterns for common workflows              | `GraphBuilder` composition           | Reduces boilerplate for workflow authors                                                                                                               |
+| `ErrorRouter`       | Node-level error handling with action routing              | Hook functions + retry/skip/abort    | Extends graph-level `catch()` per [Research §12.4](research/docs/2026-02-25-workflow-sdk-standardization.md#12-open-questions)                         |
+
+## 5. Detailed Design
+
+### 5.1 WorkflowSDK Entry Point
+
+**File:** `src/graph/sdk.ts` (new)
+
+The `WorkflowSDK` class replaces all global setter calls with a single initialization:
+
+```typescript
+import { WorkflowSDK } from "@bastani/atomic/graph";
+
+// Before (current — 6+ separate calls):
+setClientProvider((type) => getClient(type));
+setSubagentBridge(new SubagentGraphBridge(clientProvider));
+setSubagentRegistry(registry);
+setWorkflowResolver((name) => workflows.get(name));
+
+// After (proposed — single init):
+const sdk = WorkflowSDK.init({
+    providers: {
+        claude: claudeClient,
+        opencode: opencodeClient,
+        copilot: copilotClient,
+    },
+    workflows: loadedWorkflows, // Map<string, CompiledGraph>
+    agents: discoveredAgents, // From populateSubagentRegistry()
+    checkpointer: "session", // "memory" | "file" | "session"
+    validation: true, // Enable runtime state validation
+});
+```
+
+**Internal behavior:**
+
+1. Creates `ProviderRegistry` from `providers` map
+2. Instantiates `SubagentGraphBridge` using the provider registry
+3. Populates `SubagentTypeRegistry` from `agents`
+4. Sets workflow resolver from `workflows` map
+5. Configures checkpointer backend
+6. Legacy global setters (`setClientProvider`, `setSubagentBridge`, `setSubagentRegistry`, `setWorkflowResolver`) are **deleted** — `WorkflowSDK.init()` is the only initialization path
+
+**Interface:**
+
+```typescript
+interface WorkflowSDKConfig {
+    providers: Record<string, CodingAgentClient>;
+    workflows?: Map<string, CompiledGraph<BaseState>>;
+    agents?: Map<string, AgentInfo>;
+    checkpointer?: CheckpointerType;
+    validation?: boolean;
+    defaultModel?: string;
+    maxSteps?: number;
+    telemetryProvider?: TelemetryProvider;
+}
+
+class WorkflowSDK {
+    static init(config: WorkflowSDKConfig): WorkflowSDK;
+
+    // Convenience accessors
+    graph<TState extends BaseState>(): GraphBuilder<TState>;
+    execute<TState>(
+        compiled: CompiledGraph<TState>,
+        options?: ExecutionOptions<TState>,
+    ): Promise<ExecutionResult<TState>>;
+    stream<TState>(
+        compiled: CompiledGraph<TState>,
+        options?: StreamOptions<TState>,
+    ): AsyncIterable<StreamEvent<TState>>;
+
+    // Workflow management (additive only — providers are immutable after init per Q4)
+    registerWorkflow(name: string, workflow: CompiledGraph<BaseState>): void;
+
+    // Cleanup
+    destroy(): Promise<void>;
+}
+```
+
+### 5.2 Multi-Mode Streaming
+
+**File:** `src/graph/stream.ts` (new)
+
+Extend `GraphExecutor.stream()` to support multiple streaming modes inspired by LangGraph ([Research §7.2](research/docs/2026-02-25-workflow-sdk-standardization.md#72-workflow-orchestration-frameworks)):
+
+```typescript
+type StreamMode = "values" | "updates" | "events" | "debug";
+
+interface StreamOptions<TState> extends ExecutionOptions<TState> {
+    modes: StreamMode[]; // Default: ["values"]
+}
+
+type StreamEvent<TState> =
+    | { mode: "values"; nodeId: NodeId; state: TState }
+    | { mode: "updates"; nodeId: NodeId; update: Partial<TState> }
+    | { mode: "events"; nodeId: NodeId; event: CustomEvent }
+    | { mode: "debug"; nodeId: NodeId; trace: DebugTrace };
+
+interface CustomEvent {
+    type: string;
+    data: Record<string, unknown>;
+    timestamp: number;
+}
+
+interface DebugTrace {
+    nodeId: NodeId;
+    executionTime: number;
+    retryCount: number;
+    modelUsed: string;
+    stateSnapshot: unknown;
+}
+```
+
+**Implementation:** The existing `GraphExecutor.stream()` already yields `StepResult` per node. The `StreamRouter` wraps this generator, projecting each `StepResult` into the requested modes:
+
+- **`values`**: Emits full `state` after each node completes (current behavior)
+- **`updates`**: Emits only the `stateUpdate` from `NodeResult` (delta)
+- **`events`**: Emits custom events emitted by nodes via `ctx.emit(type, data)`
+- **`debug`**: Emits execution trace with timing, retry counts, model info
+
+**Node-level custom event emission:**
+
+```typescript
+// In a node's execute function:
+async function execute(
+    ctx: ExecutionContext<MyState>,
+): Promise<NodeResult<MyState>> {
+    ctx.emit?.("progress", { step: 1, total: 5 }); // Custom event
+    const result = await doWork();
+    ctx.emit?.("progress", { step: 5, total: 5 });
+    return { stateUpdate: { result } };
+}
+```
+
+The `emit` function is already present as an optional field on `ExecutionContext` ([Research §1.3](research/docs/2026-02-25-workflow-sdk-standardization.md#13-core-types-srctypests)). This proposal formalizes it as the channel for custom events.
+
+### 5.3 Runtime State Validation
+
+**File:** `src/graph/validation.ts` (new)
+
+Add optional Zod-based validation at node boundaries. This addresses the open question about state schema enforcement ([Research §12.2](research/docs/2026-02-25-workflow-sdk-standardization.md#12-open-questions)):
+
+```typescript
+import { z } from "zod";
+
+// Zod is the chosen validation library (Q1 resolved)
+interface ValidatedNodeDefinition<TState> extends NodeDefinition<TState> {
+    inputSchema?: z.ZodType<Partial<TState>>;
+    outputSchema?: z.ZodType<Partial<TState>>;
+}
+
+// Usage in node factory:
+const myNode = agentNode<MyState>({
+    id: "analyzer",
+    agentType: "claude",
+    prompt: (s) => `Analyze: ${s.document}`,
+    outputMapper: (result) => ({ analysis: result.text }),
+    // New: optional validation
+    outputSchema: z.object({
+        analysis: z.string().min(1),
+    }),
+});
+```
+
+**Validation behavior:**
+
+- If `validation: true` in `WorkflowSDKConfig`, the executor validates `stateUpdate` against `outputSchema` after each node
+- Validation failures throw `SchemaValidationError` (already exists in `src/graph/errors.ts`)
+- Validation is opt-in per node — nodes without schemas skip validation
+- Input validation runs before `execute()`, output validation runs after
+
+### 5.4 Node-Level Error Handling
+
+**Extension to:** `src/graph/types.ts`, `src/graph/compiled.ts`
+
+Add `onError` hooks to `NodeDefinition` for fine-grained error handling beyond graph-level `catch()` ([Research §12.4](research/docs/2026-02-25-workflow-sdk-standardization.md#12-open-questions)):
+
+```typescript
+type ErrorAction =
+    | { action: "retry"; delay?: number }
+    | { action: "skip"; fallbackState?: Partial<TState> }
+    | { action: "abort"; error?: Error }
+    | { action: "goto"; nodeId: NodeId }; // Restricted to nodes with isRecoveryNode: true (Q6 resolved)
+
+// Nodes must opt-in to be goto targets in error handlers
+interface NodeDefinition<TState> {
+    // ... existing fields
+    isRecoveryNode?: boolean; // If true, this node can be targeted by error handler goto actions
+}
+
+interface NodeDefinition<TState> {
+    // ... existing fields
+    onError?: (
+        error: Error,
+        ctx: ExecutionContext<TState>,
+    ) => ErrorAction | Promise<ErrorAction>;
+}
+```
+
+**Execution flow in `GraphExecutor`:**
+
+1. Node execution throws → check `node.onError`
+2. If `onError` exists → call it with error and context
+3. Based on returned action:
+    - `retry`: Re-execute with optional delay (respects `RetryConfig.maxAttempts`)
+    - `skip`: Continue to next node with optional fallback state
+    - `abort`: Stop execution, throw error
+    - `goto`: Jump to specified node (escape hatch for recovery flows)
+4. If `onError` not defined → fall through to graph-level `catch()` → then default retry logic
+
+This mirrors the Copilot SDK's hook-based error handling (`onErrorOccurred` returning `"retry" | "skip" | "abort"`) and Temporal's failure type hierarchy ([Research §7.1](research/docs/2026-02-25-workflow-sdk-standardization.md#71-coding-agent-sdks)).
+
+### 5.5 Provider Registry
+
+**File:** `src/graph/provider-registry.ts` (new)
+
+Decouple sub-agent execution from the hardcoded `AgentNodeAgentType` union:
+
+```typescript
+interface AgentProvider {
+    name: string;
+    createSession(config: SessionConfig): Promise<Session>;
+    supportedModels(): string[];
+}
+
+// Registry is immutable after initialization (Q4 resolved)
+class ProviderRegistry {
+    private providers: ReadonlyMap<string, AgentProvider>;
+
+    constructor(providers: Record<string, AgentProvider>);
+    get(name: string): AgentProvider | undefined;
+    list(): string[];
+    has(name: string): boolean;
+}
+```
+
+**Migration path:**
+
+- Phase 1: Wrap existing Claude/OpenCode/Copilot clients as `AgentProvider` implementations
+- Phase 2: Update `agentNode()` to accept `string` agent type (resolved via registry), removing the `AgentNodeAgentType` union entirely
+- Phase 3: Delete `setClientProvider()` / `getClientProvider()` — no longer exposed
+
+The existing `setClientProvider()` / `getClientProvider()` pattern ([Research §4.4](research/docs/2026-02-25-workflow-sdk-standardization.md#44-global-singleton-pattern)) is **deleted**, not wrapped or maintained internally.
+
+### 5.6 Workflow Templates
+
+**File:** `src/graph/templates.ts` (new)
+
+Pre-built graph patterns for common workflows, reducing boilerplate for custom workflow authors ([Research §12.7](research/docs/2026-02-25-workflow-sdk-standardization.md#12-open-questions)):
+
+```typescript
+// Sequential: node1 → node2 → node3
+// All templates return GraphBuilder for user customization before compile() (Q2 resolved)
+
+// Sequential: node1 → node2 → node3
+function sequential<TState extends BaseState>(
+    nodes: NodeDefinition<TState>[],
+    config?: Partial<GraphConfig>,
+): GraphBuilder<TState>;
+
+// MapReduce: split → parallel workers → merge results
+function mapReduce<TState extends BaseState>(options: {
+    splitter: NodeDefinition<TState>;
+    worker: NodeDefinition<TState>;
+    merger: (results: Partial<TState>[], state: TState) => Partial<TState>;
+    config?: Partial<GraphConfig>;
+}): GraphBuilder<TState>;
+
+// TaskLoop: decompose → dispatch → review → fix (generalized Ralph)
+function taskLoop<TState extends BaseState>(options: {
+    decomposer: NodeDefinition<TState>;
+    worker: NodeDefinition<TState>;
+    reviewer?: NodeDefinition<TState>;
+    maxIterations?: number;
+    config?: Partial<GraphConfig>;
+}): GraphBuilder<TState>;
+
+// ReviewCycle: execute → review → fix loop
+function reviewCycle<TState extends BaseState>(options: {
+    executor: NodeDefinition<TState>;
+    reviewer: NodeDefinition<TState>;
+    fixer: NodeDefinition<TState>;
+    until: (state: TState) => boolean;
+    maxIterations?: number;
+    config?: Partial<GraphConfig>;
+}): GraphBuilder<TState>;
+```
+
+**Example — Custom workflow using templates:**
+
+```typescript
+// ~/.atomic/workflows/code-review.ts
+import { taskLoop, agentNode, subagentNode } from "@bastani/atomic/graph";
+
+export const name = "code-review";
+export const description = "Automated code review workflow";
+
+export function buildGraph() {
+    return taskLoop({
+        decomposer: agentNode({
+            id: "decompose",
+            agentType: "claude",
+            prompt: (s) => `Break down review tasks: ${s.input}`,
+        }),
+        worker: subagentNode({
+            id: "reviewer",
+            name: "reviewer",
+            promptBuilder: (s) => s.currentTaskPrompt,
+            outputMapper: (result) => ({ reviewResult: result.text }),
+        }),
+        reviewer: agentNode({
+            id: "quality-check",
+            agentType: "claude",
+            prompt: (s) => `Verify review quality: ${s.reviewResult}`,
+        }),
+        maxIterations: 5,
+    });
+}
+```
+
+### 5.7 Ralph State Extraction
+
+**Proposed file moves:**
+
+| Current Location                          | New Location                     | Action                                                                                    |
+| ----------------------------------------- | -------------------------------- | ----------------------------------------------------------------------------------------- |
+| `src/graph/annotation.ts` (lines 466-600) | `src/workflows/ralph/state.ts`   | Move `RalphWorkflowState`, `RalphStateAnnotation`, `createRalphState`, `updateRalphState` |
+| `src/graph/nodes/ralph.ts`                | `src/workflows/ralph/prompts.ts` | Move Ralph prompt builders                                                                |
+| `src/graph/annotation.ts` (lines 312-465) | `src/graph/annotation.ts` (keep) | Keep `AtomicStateAnnotation` as the base workflow state                                   |
+
+**No re-exports.** All imports of Ralph types must be updated to the new location:
+
+```typescript
+// Old (removed):
+import {
+    RalphStateAnnotation,
+    RalphWorkflowState,
+} from "@bastani/atomic/graph";
+
+// New (required):
+import {
+    RalphStateAnnotation,
+    RalphWorkflowState,
+} from "@bastani/atomic/workflows/ralph";
+```
+
+### 5.8 Workflow Versioning
+
+**Extension to:** Workflow export contract ([Research §6.2](research/docs/2026-02-25-workflow-sdk-standardization.md#62-required-exports))
+
+Add optional versioning metadata to workflow exports:
+
+```typescript
+// Required (existing)
+export const name: string;
+export const description: string;
+
+// Optional (existing)
+export const aliases: string[];
+export const defaultConfig: Partial<GraphConfig>;
+export function buildGraph<TState>(): CompiledGraph<TState>;
+
+// New: Optional versioning
+export const version: string;               // Semver string (e.g., "1.2.0")
+export const minSDKVersion?: string;         // Minimum SDK version required
+export const stateVersion?: number;          // State schema version for migration
+export function migrateState?(oldState: unknown, fromVersion: number): BaseState;
+```
+
+The workflow discovery system (`loadWorkflowsFromDisk()`) will log warnings when a workflow's `minSDKVersion` exceeds the current SDK version.
+
+### 5.9 Standardized Public API Surface
+
+**File:** `src/graph/index.ts` (updated barrel exports)
+
+Reorganize the 304-line barrel export into logical categories. All legacy global setters, Ralph-specific types, and the `AgentNodeAgentType` union are **removed entirely** (not deprecated):
+
+```typescript
+// === Core SDK ===
+export { WorkflowSDK, type WorkflowSDKConfig } from "./sdk";
+
+// === Graph Builder ===
+export {
+    GraphBuilder,
+    graph,
+    type LoopConfig,
+    type MergeStrategy,
+    type ParallelConfig,
+} from "./builder";
+
+// === Execution ===
+export {
+    GraphExecutor,
+    createExecutor,
+    executeGraph,
+    streamGraph,
+} from "./compiled";
+export type { StreamMode, StreamEvent, StreamOptions } from "./stream";
+
+// === State Management ===
+export {
+    annotation,
+    Reducers,
+    initializeState,
+    applyStateUpdate,
+} from "./annotation";
+export {
+    AtomicStateAnnotation,
+    createAtomicState,
+    updateAtomicState,
+} from "./annotation";
+
+// === Node Factories ===
+export {
+    agentNode,
+    toolNode,
+    decisionNode,
+    waitNode,
+    askUserNode,
+} from "./nodes";
+export {
+    parallelNode,
+    subgraphNode,
+    subagentNode,
+    parallelSubagentNode,
+} from "./nodes";
+export { clearContextNode, contextMonitorNode, customToolNode } from "./nodes";
+
+// === Templates ===
+export { sequential, mapReduce, taskLoop, reviewCycle } from "./templates";
+
+// === Providers ===
+export { ProviderRegistry, type AgentProvider } from "./provider-registry";
+
+// === Validation ===
+export { type ValidatedNodeDefinition } from "./validation";
+
+// === Types (stable public API) ===
+export type {
+    BaseState,
+    NodeDefinition,
+    NodeResult,
+    ExecutionContext,
+} from "./types";
+export type { CompiledGraph, GraphConfig, RetryConfig, Edge } from "./types";
+export type { ExecutionOptions, StepResult, ExecutionResult } from "./compiled";
+export type { ErrorAction } from "./types";
+```
+
+### 5.10 Data Model / Schema
+
+**Workflow Definition Schema:**
+
+```typescript
+interface WorkflowDefinition {
+    name: string; // Unique identifier
+    description: string; // Human-readable description
+    version?: string; // Semver version
+    aliases?: string[]; // Alternative names
+    stateVersion?: number; // State schema version
+    defaultConfig?: Partial<GraphConfig>; // Execution defaults
+}
+```
+
+**WorkflowSession Schema** (existing, from `src/workflows/session.ts`):
+
+| Field           | Type     | Description                            |
+| --------------- | -------- | -------------------------------------- |
+| `sessionId`     | `string` | UUID session identifier                |
+| `sessionDir`    | `string` | `~/.atomic/workflows/sessions/{uuid}/` |
+| `tasksFile`     | `string` | Path to `tasks.json`                   |
+| `checkpointDir` | `string` | Path to `checkpoints/` subdirectory    |
+
+**State Flow:**
+
+```
+WorkflowSDK.init(config)
+  └─> User calls sdk.graph<MyState>()
+       └─> GraphBuilder chains: .start().then().loop().end()
+       └─> .compile(graphConfig) → CompiledGraph<MyState>
+  └─> sdk.stream(compiled, { modes: ["values", "events"] })
+       └─> GraphExecutor.stream() yields StepResult
+       └─> StreamRouter projects to StreamEvent[]
+       └─> StateValidator checks outputSchema (if enabled)
+       └─> Yields to consumer
+```
+
+## 6. Alternatives Considered
+
+| Option                                          | Pros                                                   | Cons                                                            | Reason for Rejection                                                                                       |
+| ----------------------------------------------- | ------------------------------------------------------ | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| **A: Full LangGraph port**                      | Battle-tested API, rich ecosystem                      | Python-first, poor Bun compatibility, large dependency          | The current graph engine already mirrors LangGraph's core patterns. A full port would be over-engineering. |
+| **B: Temporal-style event sourcing**            | Durable execution, replay, deterministic               | Requires external Temporal server, significant complexity       | Overkill for single-machine CLI workflows. Event sourcing adds latency.                                    |
+| **C: Inngest step API**                         | Simple step-based authoring, memoization               | HTTP-based, requires external server, less flexible than graphs | Graph-based composition is more expressive for complex DAGs.                                               |
+| **D: Keep current architecture, add docs only** | No code changes, low risk                              | Doesn't address initialization complexity, fragmented API       | Documentation alone won't fix the 6+ global setter problem or lack of templates.                           |
+| **E: Standardize with SDK wrapper (Selected)**  | Clean break, no legacy baggage, simplified API surface | Breaking change for existing consumers                          | **Selected:** Wraps existing engine without rewriting, removes all legacy APIs, adds missing features.     |
+
+## 7. Cross-Cutting Concerns
+
+### 7.1 Security and Privacy
+
+- **Agent Isolation:** Each sub-agent runs in its own session with isolated context windows ([Research §4.1](research/docs/2026-02-25-workflow-sdk-standardization.md#41-subagentgraphbridge-srcgraphsubagent-bridgets)). This is maintained.
+- **Tool Permissions:** The `PermissionMode` system (`"auto" | "prompt" | "deny" | "bypass"`) from `src/sdk/types.ts` is propagated through the provider registry to sub-agent sessions.
+- **State Serialization:** Workflow state may contain sensitive data. Checkpointers that persist to disk (`FileSaver`, `SessionDirSaver`) must respect the existing file permission model (`0o600`).
+- **Custom Workflow Loading:** Dynamic `import()` of user-defined TypeScript files from `~/.atomic/workflows/` executes arbitrary code. This is the existing security model and is not changed by this proposal.
+
+### 7.2 Observability Strategy
+
+- **Metrics:** Extend the existing `telemetryProvider` field in `GraphConfig` to capture per-node execution time, retry counts, and state sizes. Expose via the `debug` streaming mode.
+- **Tracing:** The `executionId` field on `BaseState` serves as a trace ID. The `debug` stream mode provides per-node execution traces.
+- **Alerting:** Not applicable for CLI tooling. The `contextMonitorNode()` already handles context window warnings with configurable thresholds (`BACKGROUND_COMPACTION_THRESHOLD = 0.45`, `BUFFER_EXHAUSTION_THRESHOLD = 0.6`).
+
+### 7.3 Breaking Changes (Complete Removal)
+
+**Strategy: Hard cut — all legacy APIs are deleted in a single major version bump.**
+
+| Removed API                                | Replacement                                         |
+| ------------------------------------------ | --------------------------------------------------- |
+| `setClientProvider()`                      | `WorkflowSDK.init({ providers: { ... } })`          |
+| `getClientProvider()`                      | `WorkflowSDK` instance manages providers internally |
+| `setSubagentBridge()`                      | Created internally by `WorkflowSDK.init()`          |
+| `getSubagentBridge()`                      | Accessed via `WorkflowSDK` instance                 |
+| `setSubagentRegistry()`                    | `WorkflowSDK.init({ agents: ... })`                 |
+| `setWorkflowResolver()`                    | `WorkflowSDK.init({ workflows: ... })`              |
+| `getWorkflowResolver()`                    | Accessed via `WorkflowSDK` instance                 |
+| `RalphStateAnnotation` (from `src/graph/`) | Import from `src/workflows/ralph/state`             |
+| `RalphWorkflowState` (from `src/graph/`)   | Import from `src/workflows/ralph/state`             |
+| `createRalphState()` (from `src/graph/`)   | Import from `src/workflows/ralph/state`             |
+| `updateRalphState()` (from `src/graph/`)   | Import from `src/workflows/ralph/state`             |
+| `AgentNodeAgentType` union                 | `string` type — resolved via `ProviderRegistry`     |
+
+**No deprecation warnings, no shims, no re-exports.** All internal consumers (TUI layer, workflow commands, Ralph workflow) must be updated simultaneously.
+
+## 8. Migration, Rollout, and Testing
+
+### 8.1 Deployment Strategy
+
+- [ ] **Phase 1:** Create `WorkflowSDK` class, `ProviderRegistry`, `StreamRouter`, `StateValidator`. Delete all 6 global setter/getter functions (`setClientProvider`, `getClientProvider`, `setSubagentBridge`, `getSubagentBridge`, `setSubagentRegistry`, `setWorkflowResolver`, `getWorkflowResolver`). Update all internal callers to use `WorkflowSDK.init()`.
+- [ ] **Phase 2:** Extract Ralph state/types to `src/workflows/ralph/` and delete from `src/graph/annotation.ts`. Move `src/graph/nodes/ralph.ts` to `src/workflows/ralph/prompts.ts`. Delete the `AgentNodeAgentType` union and replace with `string` resolved via `ProviderRegistry`. Update all internal imports. Add `onError` hooks to `NodeDefinition`. Add Zod validation.
+- [ ] **Phase 3:** Add workflow templates (`sequential`, `mapReduce`, `taskLoop`, `reviewCycle`). Update workflow discovery to support `version`, `minSDKVersion` exports. Rebuild barrel exports in `src/graph/index.ts` with clean categories — no legacy items.
+- [ ] **Phase 4:** Documentation — JSDoc for all public APIs, "Getting Started" guide, migration guide for custom workflow authors listing all removed APIs and their replacements.
+
+### 8.2 Data Migration Plan
+
+- **No data migration required.** All changes are additive. Existing custom workflows in `.atomic/workflows/` continue to work without modification.
+- **State compatibility:** Existing `RalphWorkflowState` instances are unaffected. The `stateVersion` field is optional and only used for future migrations.
+
+### 8.3 Test Plan
+
+- **Unit Tests:**
+    - `WorkflowSDK.init()` creates all required registries and bridges
+    - `ProviderRegistry` register/get/list operations
+    - `StreamRouter` correctly projects `StepResult` into requested modes
+    - `StateValidator` accepts valid state, rejects invalid state with `SchemaValidationError`
+    - `ErrorAction` routing: retry re-executes, skip advances, abort throws, goto jumps
+    - Workflow templates produce correct graph topology
+    - Removed APIs (global setters, Ralph types in graph module) produce compile-time errors, not runtime
+
+- **Integration Tests:**
+    - Full workflow execution through `WorkflowSDK.stream()` with multi-mode output
+    - Sub-agent spawning through `ProviderRegistry` (mock providers)
+    - Ralph workflow executes identically after state extraction
+    - Custom workflow loaded from `.atomic/workflows/` with version metadata
+
+- **End-to-End Tests:**
+    - Following existing E2E testing guidelines from `AGENTS.md`: Build snake game in Rust using each agent (opencode, copilot, claude) via TUI
+    - Verify custom workflow discovery, execution, and streaming through the TUI chat interface
+
+## 9. Open Questions / Unresolved Issues
+
+All questions have been resolved:
+
+- [x] **Q1 — Zod as a required dependency:** **Resolved: Use Zod schemas.** Rich validation, good DX, widely adopted in the TypeScript ecosystem. Zod is already a natural fit alongside the annotation system and will be added as a dependency.
+- [x] **Q2 — Template granularity:** **Resolved: Return `GraphBuilder` instances.** Templates return `GraphBuilder` so users can customize the graph (add nodes, modify edges, set config) before calling `.compile()`. This provides maximum flexibility while reducing boilerplate.
+- [x] **Q3 — Custom event naming:** **Resolved: Flat strings.** Custom events use simple flat strings (e.g., `"progress"`, `"status"`). No namespace convention is enforced — keeping the API simple with no overhead.
+- [x] **Q4 — Provider hot-swap:** **Resolved: Initialization only.** The `ProviderRegistry` is immutable after `WorkflowSDK.init()`. Providers must be registered during initialization. This ensures predictable behavior and avoids race conditions during execution.
+- [x] **Q5 — Stream backpressure:** **Resolved: Buffer all events.** The streaming system buffers all events in memory. Since workflows are bounded (by `maxSteps` and `maxIterations`), unbounded buffering is safe and keeps the implementation simple.
+- [x] **Q6 — Error action `goto`:** **Resolved: Restrict to predefined recovery nodes.** The `goto` error action can only target nodes explicitly marked with `isRecoveryNode: true` in their `NodeDefinition`. This prevents arbitrary jumps while still allowing structured error recovery flows.
diff --git a/specs/workflow-tui-rendering-unification-refactor.md b/specs/workflow-tui-rendering-unification-refactor.md
new file mode 100644
index 0000000000..868e50068e
--- /dev/null
+++ b/specs/workflow-tui-rendering-unification-refactor.md
@@ -0,0 +1,463 @@
+# Workflow TUI Rendering Unification Refactor — Technical Design Document / RFC
+
+| Document Metadata      | Details     |
+| ---------------------- | ----------- |
+| Author(s)              | lavaman131  |
+| Status                 | Draft (WIP) |
+| Team / Owner           | Atomic CLI  |
+| Created / Last Updated | 2026-02-28  |
+
+---
+
+## 1. Executive Summary
+
+This RFC supersedes the rendering layer portion of [specs/workflow-tui-rendering-unification.md](./workflow-tui-rendering-unification.md) based on corrected findings from [research/docs/2026-02-28-workflow-tui-rendering-unification-refactor.md](../research/docs/2026-02-28-workflow-tui-rendering-unification-refactor.md). The prior spec assumed the event pipeline was broken for workflow sub-agents. Updated analysis reveals the pipeline is **already shared**: `spawnSubagentParallel()` already creates `SubagentStreamAdapter` instances that publish all 9 event types to the shared `EventBus`, and the reducer `applyStreamPartEvent()` already routes sub-agent events to `agent.inlineParts[]`.
+
+**The divergence is only in the rendering layer.** Main chat dispatches `parts[]` through `PART_REGISTRY` — 9 full-fidelity renderers. Workflow sub-agent content lands in `agent.inlineParts[]` but is rendered by bespoke `AgentInlineText` (200-char truncated plain text) and `AgentInlineTool` (30-char tool name) — bypassing `PART_REGISTRY` entirely. Only 2 of 9 part types are handled, and only the latest part is shown.
+
+**The fix is surgical:** replace `AgentInlineParts`/`AgentInlineText`/`AgentInlineTool` with `PART_REGISTRY` dispatch so workflow sub-agents render through the exact same renderers as the main chat. Route all part types (including `ReasoningPart`, currently missing) to `inlineParts`. Delete the bespoke rendering code.
+
+---
+
+## 2. Context and Motivation
+
+### 2.1 Current State
+
+The Atomic CLI rendering pipeline is a multi-stage event-driven system ([research §2](../research/docs/2026-02-28-workflow-tui-rendering-unification-refactor.md)):
+
+```
+SDK Stream → SDKStreamAdapter → EventBus → BatchDispatcher (16ms)
+  → CorrelationService → StreamPipelineConsumer → StreamPartEvent[]
+    → applyStreamPartEvent() reducer → ChatMessage.parts[] → PART_REGISTRY → renderers
+```
+
+**Critical correction from 2026-02-28 research:** The event pipeline is **fully shared** between main chat and workflow sub-agents. Specifically:
+
+- `spawnSubagentParallel()` at `chat.tsx:4083` already creates `SubagentStreamAdapter` instances (lines 4163–4169) that publish **all 9 event types** to the shared `EventBus` ([research Finding 1](../research/docs/2026-02-28-workflow-tui-rendering-unification-refactor.md))
+- `StreamPipelineConsumer` already has handlers for `workflow.step.start`, `workflow.step.complete`, and `workflow.task.update` ([research §3, updated analysis](../research/docs/2026-02-28-workflow-tui-rendering-unification-refactor.md))
+- `applyStreamPartEvent()` already routes sub-agent events to `agent.inlineParts[]` via `routeToAgentInlineParts()` at `stream-pipeline.ts:938–959`
+- Events arriving before the `AgentPart` exists are properly buffered and replayed via `drainBufferedEvents()` at `stream-pipeline.ts:681–721`
+
+**Architecture (current):**
+
+```
+SHARED EVENT PIPELINE (works for both main chat and workflows):
+═══════════════════════════════════════════════════════════════
+SubagentStreamAdapter.consumeStream()
+  ├── stream.text.delta          ✅ → pipeline → inlineParts TextPart
+  ├── stream.thinking.delta      ✅ → pipeline → ⚠️ ReasoningPart on MAIN message
+  ├── stream.tool.start/complete ✅ → pipeline → inlineParts ToolPart
+  ├── stream.usage               ✅ → bus subscription → aggregate tokens
+  ├── stream.agent.start/complete✅ → bus subscription → agent tree
+  └── workflow.step/task events  ✅ → pipeline → WorkflowStepPart/TaskListPart
+
+RENDERING DIVERGENCE (the actual problem):
+══════════════════════════════════════════
+Main Chat:
+  parts[] → PART_REGISTRY dispatch → 9 full-fidelity renderers
+    TextPartDisplay (markdown, syntax highlighting, streaming cursor)
+    ReasoningPartDisplay (collapsible thinking with duration)
+    ToolPartDisplay (lifecycle with collapsible I/O)
+    + 6 more
+
+Workflow Sub-Agent Inline Parts:
+  agent.inlineParts[] → AgentInlineParts (bespoke)
+    AgentInlineText (plain text, 200-char truncation, no markdown)
+    AgentInlineTool (30-char tool name, single line)
+    All other types → null (ignored)
+```
+
+**Limitations of the bespoke rendering path:**
+
+- `AgentInlineParts` shows only the **latest** part (`parts[parts.length - 1]`) — all prior streaming content is invisible ([research Finding 12](../research/docs/2026-02-28-workflow-tui-rendering-unification-refactor.md), `parallel-agents-tree.tsx:615`)
+- `AgentInlineText` renders as plain `<text>` — no markdown parsing, no syntax highlighting, no streaming cursor (`parallel-agents-tree.tsx:642–668`)
+- `AgentInlineTool` renders tool name only (truncated to 30 chars) — no expandable I/O, no lifecycle state detail (`parallel-agents-tree.tsx:671–720`)
+- `ReasoningPart` in `inlineParts` is **not handled** — thinking blocks from sub-agents are silently ignored
+- 5 additional part types (`TaskListPart`, `SkillLoadPart`, `McpSnapshotPart`, `CompactionPart`, `WorkflowStepPart`) are completely bypassed
+
+### 2.2 The Problem
+
+- **User Impact:** Workflow sub-agents show minimal inline content — the latest text truncated to 200 characters with no markdown formatting, or the latest tool name in 30 characters. Users cannot see thinking blocks, tool input/output, or streaming progress. This creates a "black box" experience during the most complex and long-running operations.
+
+- **Feature Parity Gap (High Severity):** Per [research Comprehensive Feature Parity Matrix](../research/docs/2026-02-28-workflow-tui-rendering-unification-refactor.md):
+
+    | Feature                | Main Chat                       | Workflow Inline          | Gap Severity |
+    | ---------------------- | ------------------------------- | ------------------------ | ------------ |
+    | Streaming text         | Incremental markdown            | Plain text, 200 chars    | **High**     |
+    | Thinking block content | ReasoningPart rendered          | Routed but not rendered  | **High**     |
+    | Tool call rendering    | ToolPart lifecycle with rich UI | Plain text summary       | **High**     |
+    | Markdown rendering     | Full syntax highlighting        | Plain text in agent rows | **High**     |
+    | Agent inline parts     | N/A (main chat has no agents)   | Plain text only          | **High**     |
+
+- **Wasted Infrastructure:** The event pipeline and reducer already do the work of routing events to `agent.inlineParts[]` with proper `Part` objects that are structurally identical to top-level `parts[]`. The `PART_REGISTRY` already has all 9 renderers registered. The bespoke rendering path simply bypasses all of this.
+
+- **Technical Debt:** Three private components (`AgentInlineParts`, `AgentInlineText`, `AgentInlineTool`) duplicate rendering logic that already exists in the parts system, creating ongoing maintenance burden.
+
+---
+
+## 3. Goals and Non-Goals
+
+### 3.1 Functional Goals
+
+- [ ] Agent inline parts render through `PART_REGISTRY` dispatch — the same renderers used by main chat `parts[]`
+- [ ] All 9 part types (`text`, `reasoning`, `tool`, `agent`, `task-list`, `skill-load`, `mcp-snapshot`, `compaction`, `workflow-step`) are supported in agent inline rendering
+- [ ] `ReasoningPart` events from sub-agents are routed to `agent.inlineParts[]` (currently routed to main message parts)
+- [ ] Multiple inline parts are visible per agent (not just the latest one), with sensible display limits to avoid cluttering the tree
+- [ ] Bespoke `AgentInlineParts`, `AgentInlineText`, and `AgentInlineTool` components are removed
+- [ ] Existing agent tree visual structure (`├─●` connectors, status indicators, task labels, tool counts) is preserved
+- [ ] Compact mode behavior (auto-compact when all agents complete) continues to work
+
+### 3.2 Non-Goals (Out of Scope)
+
+- [ ] We will NOT modify the event bus pipeline — it is already shared and working correctly
+- [ ] We will NOT modify `SubagentStreamAdapter` — it already publishes all event types
+- [ ] We will NOT modify `routeToAgentInlineParts()` or `applyStreamPartEvent()` — the reducer already routes events correctly
+- [ ] We will NOT add per-agent token count display in the tree (tracked as a Medium-severity gap in [research](../research/docs/2026-02-28-workflow-tui-rendering-unification-refactor.md), deferred)
+- [ ] We will NOT add per-agent completion summaries (Low severity, deferred)
+- [ ] We will NOT change HITL/tool approval behavior during workflows (auto-approve stays; Medium severity, deferred)
+- [ ] We will NOT implement session recovery (Medium severity, deferred)
+- [ ] We will NOT address message queue blocked during workflow execution (Low severity, deferred)
+
+---
+
+## 4. Proposed Solution (High-Level Design)
+
+### 4.1 System Architecture Diagram
+
+```mermaid
+%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#f8f9fa','primaryTextColor':'#2c3e50','primaryBorderColor':'#4a5568','lineColor':'#4a90e2','secondaryColor':'#ffffff','tertiaryColor':'#e9ecef'}}}%%
+
+flowchart TB
+    classDef existing fill:#718096,stroke:#4a5568,stroke-width:2px,color:#ffffff,font-weight:600
+    classDef changed fill:#ed8936,stroke:#dd6b20,stroke-width:2.5px,color:#ffffff,font-weight:600
+    classDef deleted fill:#e53e3e,stroke:#c53030,stroke-width:2.5px,color:#ffffff,font-weight:600
+    classDef unchanged fill:#48bb78,stroke:#38a169,stroke-width:2.5px,color:#ffffff,font-weight:600
+
+    subgraph Pipeline["Shared Event Pipeline (UNCHANGED)"]
+        direction TB
+        Adapter["SubagentStreamAdapter<br><i>Already publishes all 9 events</i>"]:::unchanged
+        Bus["EventBus"]:::unchanged
+        Batch["BatchDispatcher (16ms)"]:::unchanged
+        Correlation["CorrelationService"]:::unchanged
+        Consumer["StreamPipelineConsumer"]:::unchanged
+        Reducer["applyStreamPartEvent()<br>routeToAgentInlineParts()"]:::unchanged
+    end
+
+    subgraph TopLevelParts["Top-Level Parts → Renderers (UNCHANGED)"]
+        direction LR
+        PartsArray["ChatMessage.parts[]"]:::unchanged
+        Registry1["PART_REGISTRY dispatch"]:::unchanged
+        Renderers1["9 Full-Fidelity Renderers"]:::unchanged
+    end
+
+    subgraph InlineParts["Agent Inline Parts → Renderers (CHANGED)"]
+        direction TB
+        InlineArray["agent.inlineParts[]<br><i>Same Part types as top-level</i>"]:::unchanged
+
+        subgraph Old["DELETED — Bespoke Renderers"]
+            AgentInlineParts["AgentInlineParts<br><i>only latest part</i>"]:::deleted
+            AgentInlineText["AgentInlineText<br><i>200-char plain text</i>"]:::deleted
+            AgentInlineTool["AgentInlineTool<br><i>30-char tool name</i>"]:::deleted
+        end
+
+        subgraph New["NEW — PART_REGISTRY Dispatch"]
+            AgentInlineDisplay["AgentInlinePartsDisplay<br><i>Renders all inline parts<br>via PART_REGISTRY</i>"]:::changed
+        end
+    end
+
+    Adapter --> Bus --> Batch --> Correlation --> Consumer --> Reducer
+    Reducer --> PartsArray --> Registry1 --> Renderers1
+    Reducer --> InlineArray
+    InlineArray -.->|"BEFORE"| AgentInlineParts
+    InlineArray -->|"AFTER"| AgentInlineDisplay
+
+    style Pipeline fill:#ffffff,stroke:#38a169,stroke-width:2px,stroke-dasharray:8 4
+    style TopLevelParts fill:#ffffff,stroke:#38a169,stroke-width:2px,stroke-dasharray:8 4
+    style InlineParts fill:#ffffff,stroke:#dd6b20,stroke-width:2px,stroke-dasharray:8 4
+    style Old fill:#fff5f5,stroke:#c53030,stroke-width:1px,stroke-dasharray:4 2
+    style New fill:#f0fff4,stroke:#38a169,stroke-width:1px,stroke-dasharray:4 2
+```
+
+### 4.2 Architectural Pattern
+
+We adopt a **Registry-Dispatched Inline Parts** pattern: the same `PART_REGISTRY` that dispatches top-level `parts[]` rendering is reused for agent `inlineParts[]`. The bespoke rendering components are replaced with a thin adapter component that iterates `inlineParts[]` and dispatches each part through `PART_REGISTRY[part.type]`.
+
+This approach was selected because:
+
+- It produces **zero new rendering code** — all 9 renderers already exist and are tested
+- It achieves **automatic feature parity** — any future part type or renderer improvement applies to inline parts without changes
+- It is a **rendering-only change** — the event pipeline, reducer, and data model are untouched
+
+### 4.3 Key Components
+
+| Component                   | Responsibility                                              | Location                                         | Change Type                              |
+| --------------------------- | ----------------------------------------------------------- | ------------------------------------------------ | ---------------------------------------- |
+| `AgentInlinePartsDisplay`   | Iterates `inlineParts[]` and dispatches via `PART_REGISTRY` | `src/ui/components/parallel-agents-tree.tsx`     | **REPLACE**                              |
+| `AgentInlineParts` (old)    | Bespoke latest-only rendering                               | `src/ui/components/parallel-agents-tree.tsx:605` | **DELETE**                               |
+| `AgentInlineText` (old)     | Plain text 200-char truncated rendering                     | `src/ui/components/parallel-agents-tree.tsx:642` | **DELETE**                               |
+| `AgentInlineTool` (old)     | 30-char tool name rendering                                 | `src/ui/components/parallel-agents-tree.tsx:671` | **DELETE**                               |
+| `routeToAgentInlineParts()` | Routes `thinking-meta` events to agent `inlineParts[]`      | `src/ui/parts/stream-pipeline.ts:938`            | **MODIFY** (add `thinking-meta` routing) |
+| `PART_REGISTRY`             | Type → renderer dispatch map                                | `src/ui/components/parts/registry.tsx:23`        | **UNCHANGED**                            |
+
+---
+
+## 5. Detailed Design
+
+### 5.1 Replace `AgentInlineParts` with `PART_REGISTRY` Dispatch
+
+**Current code** (`parallel-agents-tree.tsx:605–639`):
+
+```typescript
+function AgentInlineParts({ parts, continuationPrefix, themeColors }) {
+  const latestPart = parts.length > 0 ? parts[parts.length - 1] : undefined;
+  if (!latestPart) return null;
+
+  return (
+    <box flexDirection="column">
+      {latestPart.type === "text" ? (
+        <AgentInlineText ... />
+      ) : latestPart.type === "tool" ? (
+        <AgentInlineTool ... />
+      ) : null}
+    </box>
+  );
+}
+```
+
+**Proposed replacement:**
+
+```typescript
+function AgentInlinePartsDisplay({
+  parts,
+  continuationPrefix,
+  themeColors,
+}: {
+  parts: Part[];
+  continuationPrefix: string;
+  themeColors: ThemeColors;
+}): React.ReactNode {
+  if (parts.length === 0) return null;
+
+  return (
+    <box flexDirection="column">
+      {parts.map((part, idx) => {
+        const Renderer = PART_REGISTRY[part.type];
+        if (!Renderer) return null;
+
+        return (
+          <box key={part.id} flexDirection="row">
+            <box flexShrink={0}>
+              <text style={{ fg: themeColors.muted }}>
+                {continuationPrefix}{SUB_STATUS_PAD}{"  "}
+              </text>
+            </box>
+            <box flexGrow={1} flexShrink={1}>
+              <Renderer
+                part={part}
+                isLast={idx === parts.length - 1}
+              />
+            </box>
+          </box>
+        );
+      })}
+    </box>
+  );
+}
+```
+
+**Key behaviors:**
+
+- Renders **all parts** through `PART_REGISTRY` dispatch — not just the latest one
+- Each part is wrapped with the tree continuation prefix for visual alignment
+- All 9 part types are supported automatically via the same renderers used by main chat
+- The `isLast` prop is correctly passed to the last part
+- No truncation, no limits — identical to how `MessageBubbleParts` renders top-level parts
+
+### 5.2 Route `ReasoningPart` to Agent `inlineParts[]`
+
+Currently, `stream.thinking.delta` events are processed in `useStreamConsumer` at `chat.tsx:2720–2774` and create/update `ReasoningPart` on the **main message's** `parts[]`, even when the event carries an `agentId`. These need to be routed to the agent's `inlineParts[]` instead.
+
+**Required change in `applyStreamPartEvent()`** (`stream-pipeline.ts`):
+
+Add a `thinking-meta` case to `routeToAgentInlineParts()` similar to the existing `text-delta`, `tool-start`, and `tool-complete` cases:
+
+```typescript
+case "thinking-meta": {
+  if (event.agentId) {
+    const routed = routeToAgentInlineParts(
+      nextParts, event.agentId,
+      (inlineParts) => handleThinkingDelta(inlineParts, event)
+    );
+    if (routed) return { ...message, parts: routed };
+    bufferAgentEvent(event.agentId, event);
+    return message;
+  }
+  // Existing main-message handling for non-agent thinking events
+  // ...
+}
+```
+
+### 5.3 Update `AgentRow` to Use New Inline Component
+
+The `AgentRow` component at `parallel-agents-tree.tsx:514–593` currently filters `inlineParts` to avoid duplicate tool display and delegates to the old `AgentInlineParts`. Update it to:
+
+1. Remove the duplicate-tool filtering logic at lines 547–554 (the `showCurrentTool` stripping of the last tool part)
+2. Delegate to `AgentInlinePartsDisplay` instead of the old bespoke component
+
+```typescript
+// Current (line 587-591):
+<AgentInlineParts
+  parts={inlineParts}
+  continuationPrefix={continuationPrefix}
+  themeColors={themeColors}
+/>
+
+// Proposed:
+<AgentInlinePartsDisplay
+  parts={agent.inlineParts ?? []}
+  continuationPrefix={continuationPrefix}
+  themeColors={themeColors}
+/>
+```
+
+Since `PART_REGISTRY` renders `ToolPart` with full lifecycle display (status, expandable I/O, collapsible output), the `currentTool` display in the agent row header becomes redundant and can be simplified or removed.
+
+### 5.4 Data Model (Unchanged)
+
+No changes to the data model. The `Part` union type, `AgentPart`, and `ParallelAgent.inlineParts` field already support all 9 part types. The `inlineParts: Part[]` field on `ParallelAgent` (`parallel-agents-tree.tsx:64`) is the same `Part` union used by top-level `parts[]`.
+
+### 5.5 Data Flow (Unified State)
+
+```
+BEFORE (bespoke rendering):
+agent.inlineParts[TextPart, ToolPart, ...]
+  → AgentInlineParts
+    → shows ONLY parts[parts.length - 1]
+      → "text" → AgentInlineText (200 chars, plain text)
+      → "tool" → AgentInlineTool (30 chars, tool name)
+      → anything else → null
+
+AFTER (registry dispatch):
+agent.inlineParts[TextPart, ReasoningPart, ToolPart, ...]
+  → AgentInlinePartsDisplay
+    → shows last N parts via PART_REGISTRY
+      → "text" → TextPartDisplay (full markdown)
+      → "reasoning" → ReasoningPartDisplay (thinking with duration)
+      → "tool" → ToolPartDisplay (lifecycle with collapsible I/O)
+      → "agent" → AgentPartDisplay (nested agent tree)
+      → all 9 types supported automatically
+```
+
+---
+
+## 6. Alternatives Considered
+
+| Option                                                    | Pros                                                                                            | Cons                                                                                                                                | Reason for Rejection                                                                         |
+| --------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| **A: PART_REGISTRY dispatch for inline parts (Selected)** | Zero new rendering code; automatic future parity; renders all 9 types; minimal change footprint | None — uses renderers as-is                                                                                                         | **Selected:** Maximum code reuse; smallest delta; automatic parity with all future renderers |
+| **B: Enhanced bespoke renderers**                         | No changes to PART_REGISTRY or existing renderers; self-contained in `parallel-agents-tree.tsx` | Must duplicate rendering logic for each of 9 types; ongoing maintenance burden; will diverge from PART_REGISTRY renderers over time | Would perpetuate the two-path problem rather than solving it                                 |
+| **C: Separate inline part registry**                      | Could customize inline appearance per type without affecting main renderers                     | Another registry to maintain; adds complexity; doesn't reuse existing renderers                                                     | No advantage over using PART_REGISTRY directly — same renderers should be used everywhere    |
+
+---
+
+## 7. Cross-Cutting Concerns
+
+### 7.1 Performance
+
+- **Rendering volume:** Showing multiple inline parts per agent (vs. only the latest) increases React rendering work. The existing `BatchDispatcher` 16ms frame-aligned batching ensures updates are coalesced.
+- **Part array growth:** For long-running workflows, `inlineParts[]` may grow. If memory becomes an issue, an eviction strategy (dropping old parts beyond a threshold) can be added to `routeToAgentInlineParts()` without changing the rendering layer.
+- **Markdown rendering cost:** `TextPartDisplay` renders markdown via `<markdown>` or `<code filetype="markdown">`. With multiple agents showing inline markdown, this is more expensive than the old plain `<text>`. The `BatchDispatcher` coalescing mitigates rendering frequency.
+
+### 7.2 Visual Consistency
+
+- The tree visual structure (`├─●` connectors, status indicators, colors) is preserved — only the content below each agent row changes.
+- Compact mode (`compact` prop to `ParallelAgentsTree`) continues to work since it's driven by agent status, not inline parts content.
+- Verbose mode (Ctrl+E) automatically applies to inline parts rendered via `PART_REGISTRY` since the renderers already respect it.
+
+### 7.3 Testing Strategy
+
+- Existing tests for `AgentInlineParts`, `AgentInlineText`, `AgentInlineTool` in `parallel-agents-tree.test.ts` must be updated to test the new `AgentInlinePartsDisplay` component.
+- Existing tests for `PART_REGISTRY` dispatch and individual renderers continue to validate correctness.
+- New tests: verify that `inlineParts` with `ReasoningPart` type render correctly (since this part type was previously not routed).
+- Integration test: verify end-to-end workflow execution renders inline parts through `PART_REGISTRY`.
+
+---
+
+## 8. Migration, Rollout, and Testing
+
+### 8.1 Deployment Strategy
+
+- [ ] **Phase 1 — Route `ReasoningPart` to agent `inlineParts[]`:** Modify `applyStreamPartEvent()` to route `thinking-meta` events with `agentId` to `routeToAgentInlineParts()` instead of main message parts. This ensures all relevant part types flow to inline parts.
+
+- [ ] **Phase 2 — Replace bespoke renderers with `PART_REGISTRY` dispatch:** Remove `AgentInlineParts`, `AgentInlineText`, `AgentInlineTool`. Add `AgentInlinePartsDisplay` that iterates `inlineParts[]` and dispatches each through `PART_REGISTRY`. Update `AgentRow` to use the new component. Remove duplicate-tool filtering logic.
+
+- [ ] **Phase 3 — Visual polish and testing:** Verify compact mode, verify verbose mode interaction, run E2E workflow tests to validate visual output.
+
+### 8.2 Test Plan
+
+- **Unit Tests:**
+    - `AgentInlinePartsDisplay`: Verify it renders all 9 part types via `PART_REGISTRY`; verify empty parts returns `null`
+    - `routeToAgentInlineParts()` with `thinking-meta`: Verify `ReasoningPart` is created in agent's `inlineParts` when `agentId` is present
+
+- **Integration Tests:**
+    - Workflow execution produces visible inline parts in agent tree rows
+    - Concurrent sub-agents render independent inline parts without interleaving
+    - `drainBufferedEvents()` correctly replays `thinking-meta` events for agents that materialize late
+
+- **E2E Tests:**
+    - Run a Ralph workflow and verify: streaming text with markdown, thinking blocks, tool progress, and step markers are visible in the agent tree
+    - Verify compact mode auto-triggers when agents complete
+    - Verify Ctrl+E verbose mode expands inline tool parts
+
+---
+
+## 9. Open Questions / Unresolved Issues
+
+> **Note:** `AtomicEventBus` is being renamed to `EventBus` across the codebase. This spec uses the new name `EventBus`. Implementers should rename `AtomicEventBus` → `EventBus` in any files touched by this work.
+
+All questions resolved:
+
+1. ✅ **Inline parts display limit:** No limit — render all parts via `PART_REGISTRY`, same as the main engine. No `MAX_INLINE_PARTS_VISIBLE` constant needed. The main chat renders all parts in `MessageBubbleParts`; inline parts follow the same behavior.
+
+2. ✅ **Inline text length limit:** No limit — render full markdown via `TextPartDisplay`, same as the main engine. No `MAX_INLINE_TEXT_LENGTH` constant needed. The old 200-char plain text truncation is eliminated along with the bespoke `AgentInlineText` component.
+
+3. ✅ **`syntaxStyle` prop propagation:** No `syntaxStyle` prop — inline parts render identically to main engine parts. No changes to the `PartRenderer` interface. Renderers are used as-is.
+
+4. ✅ **Thinking event routing scope:** Exclusive routing to `inlineParts` — `thinking-meta` events with `agentId` route exclusively to the agent's `inlineParts[]`, rendered via the same `PART_REGISTRY` as main chat. The aggregate thinking time display in the spinner is unaffected since it uses a separate `stream.thinking.complete` bus subscription.
+
+5. ✅ **`AgentInlineTool` duplicate-tool filtering:** Remove deduplication — the `AgentRow` code that strips the last tool part when `showCurrentTool` is true (lines 547–554) is removed. `PART_REGISTRY` handles tool rendering fully, and the `currentTool` display in the agent row header can be removed or coexist since the inline `ToolPartDisplay` provides richer information.
+
+---
+
+## Appendix A: File Change Inventory
+
+| File                                             | Change Type  | Description                                                                                                                                                                                                                                          |
+| ------------------------------------------------ | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src/ui/components/parallel-agents-tree.tsx`     | **MODIFIED** | Delete `AgentInlineParts` (605–639), `AgentInlineText` (642–668), `AgentInlineTool` (671–720). Add `AgentInlinePartsDisplay` with `PART_REGISTRY` dispatch. Update `AgentRow` to use new component. Remove duplicate-tool filtering logic (547–554). |
+| `src/ui/parts/stream-pipeline.ts`                | **MODIFIED** | Add `thinking-meta` case to `routeToAgentInlineParts()` for agent-scoped `ReasoningPart` routing                                                                                                                                                     |
+| `src/ui/components/parallel-agents-tree.test.ts` | **MODIFIED** | Update tests for `AgentInlinePartsDisplay`; remove tests for deleted bespoke components                                                                                                                                                              |
+
+## Appendix B: Research References
+
+| Document                                                                                                                                              | Relevance                                                                             |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| [research/docs/2026-02-28-workflow-tui-rendering-unification-refactor.md](../research/docs/2026-02-28-workflow-tui-rendering-unification-refactor.md) | **Primary research** — corrected pipeline analysis, rendering-only gap identification |
+| [research/docs/2026-02-27-workflow-tui-rendering-unification.md](../research/docs/2026-02-27-workflow-tui-rendering-unification.md)                   | Prior architecture audit — initial gap identification (partially superseded)          |
+| [research/docs/2026-02-28-workflow-gaps-architecture.md](../research/docs/2026-02-28-workflow-gaps-architecture.md)                                   | Gap inventory — 7 categories of gaps including rendering pipeline                     |
+| [research/docs/2026-02-25-ui-workflow-coupling.md](../research/docs/2026-02-25-ui-workflow-coupling.md)                                               | Coupling surface between UI and workflow layers                                       |
+| [research/docs/2026-02-26-streaming-architecture-event-bus-migration.md](../research/docs/2026-02-26-streaming-architecture-event-bus-migration.md)   | Event bus migration — confirms shared infrastructure                                  |
+| [specs/workflow-tui-rendering-unification.md](./workflow-tui-rendering-unification.md)                                                                | Prior spec — partially superseded by this refactor spec                               |
+| [specs/chat-system-parts-based-rendering.md](./chat-system-parts-based-rendering.md)                                                                  | Parts-based rendering design — defines the `PART_REGISTRY` system                     |
+
+## Appendix C: Relationship to Prior Spec
+
+This spec **supersedes the rendering layer portions** of [specs/workflow-tui-rendering-unification.md](./workflow-tui-rendering-unification.md). Specifically:
+
+- **§5.1 SubagentStreamAdapter** — No longer needed; already exists and works
+- **§5.2 CorrelationService Enhancement** — No longer needed; already working
+- **§5.3 spawnSubagentParallel Refactoring** — No longer needed; already using adapters
+- **§5.4 Workflow Event UI Consumers** — Already wired in `StreamPipelineConsumer`
+- **§5.5 Per-Agent Streaming Content Scoping** — Partially relevant; the `inlineParts` routing works, but rendering needs the change described in this spec
+- **§5.6 Token Count Aggregation** — Deferred (out of scope for this rendering-focused spec)
+
+The prior spec's phases 1–2 are effectively already implemented. This spec addresses the remaining Phase 3 gap (rendering) with a more precise, smaller-scope intervention.
diff --git a/specs/workflow-tui-rendering-unification.md b/specs/workflow-tui-rendering-unification.md
new file mode 100644
index 0000000000..d31ef891e8
--- /dev/null
+++ b/specs/workflow-tui-rendering-unification.md
@@ -0,0 +1,566 @@
+# Workflow TUI Rendering Unification — Technical Design Document / RFC
+
+| Document Metadata      | Details     |
+| ---------------------- | ----------- |
+| Author(s)              | Alex Lavaee |
+| Status                 | Draft (WIP) |
+| Team / Owner           | Atomic CLI  |
+| Created / Last Updated | 2026-02-27  |
+
+---
+
+## 1. Executive Summary
+
+The Atomic CLI currently runs two completely separate rendering pipelines: one for the main chat interface (rich streaming with text deltas, thinking blocks, tool status, token counts, and sub-agent trees) and one for workflow execution (two static messages and silent sub-agent sessions). Workflow sub-agents create independent SDK sessions that discard all streaming content, thinking blocks, tool lifecycle events, and token usage — producing a visually impoverished experience compared to normal chat interactions.
+
+This RFC proposes **unifying workflow rendering with the main TUI chat pipeline** so that workflow sub-agents stream through the same `AtomicEventBus → BatchDispatcher → StreamPipelineConsumer → Part[] → PART_REGISTRY` pipeline as normal chat messages. The result: workflows display real-time streaming text, thinking blocks, tool progress, token counts, and rich sub-agent trees — making workflow execution feel like a native extension of the chat experience rather than a separate execution mode.
+
+> **Research basis:** [research/docs/2026-02-27-workflow-tui-rendering-unification.md](../research/docs/2026-02-27-workflow-tui-rendering-unification.md) — comprehensive architecture audit of both rendering pipelines, gap analysis, and integration point mapping.
+
+---
+
+## 2. Context and Motivation
+
+### 2.1 Current State
+
+The TUI renders chat messages through a sophisticated multi-stage event-driven pipeline:
+
+```
+SDK Stream → SDK Adapter → bus.publish() → BatchDispatcher (16ms)
+  → CorrelationService → StreamPipelineConsumer → StreamPartEvent[]
+    → React state reducer (applyStreamPartEvent) → Part[] → PART_REGISTRY → renderers
+```
+
+This pipeline supports ([research §1](../research/docs/2026-02-27-workflow-tui-rendering-unification.md)):
+- **Streaming text** via `stream.text.delta` events → `TextPartDisplay` with markdown rendering
+- **Thinking blocks** via `stream.thinking.delta` events → `ReasoningPartDisplay` with dimmed syntax
+- **Tool lifecycle** via `stream.tool.start/complete` events → `ToolPartDisplay` with collapsible output
+- **Token counts** via `stream.usage` events → `LoadingIndicator` and `CompletionSummary`
+- **Sub-agent trees** via `stream.agent.*` events → `ParallelAgentsTree` with status colors and progress
+- **Spinners** via braille animation frames with elapsed time, token count, and thinking duration
+
+The workflow executor at `src/workflows/executor.ts` bypasses this entire pipeline ([research §2](../research/docs/2026-02-27-workflow-tui-rendering-unification.md)):
+
+```
+executeWorkflow()
+  → context.addMessage("Starting workflow...")          ← static text
+  → for await (step of streamGraph()):
+    → spawnSubagentParallel():
+      → createSubagentSession()                         ← INDEPENDENT session
+      → for await (msg of stream):                      ← SILENT consumption
+        → summaryParts.push(msg.content)                ← NO rendering
+      → return SubagentResult                           ← truncated to 4000 chars
+  → context.addMessage("Workflow completed.")           ← static text
+```
+
+**Architecture:** The workflow executor communicates with the TUI exclusively through the `CommandContext` interface ([research §6](../research/docs/2026-02-27-workflow-tui-rendering-unification.md)), which provides `addMessage()` (static text), `setStreaming()` (boolean flag), and `spawnSubagentParallel()` (silent sub-agent execution). It does not use `streamAndWait()` or any of the event bus infrastructure.
+
+**Limitations:**
+- Sub-agent SDK sessions are created independently and destroyed after use — they never publish to the shared `AtomicEventBus`
+- Text, thinking, tool, and usage events are discarded in the silent consumption loop at `chat.tsx:3970-3984`
+- `workflow.step.*` and `workflow.task.*` bus events are published but have **zero UI consumers**
+- The sub-agent tree shows workflow agents but without live tool progress, streaming text, or thinking metadata
+
+### 2.2 The Problem
+
+- **User Impact:** Users running workflows see only "Starting workflow..." and "Workflow completed." messages with no visibility into what's happening. Sub-agents appear in the tree but show no streaming content, tool usage, or thinking activity. This creates a "black box" experience that erodes trust and makes debugging difficult.
+
+- **Feature Parity Gap:** Normal chat interactions display rich streaming output while workflows — which are the most complex and long-running operations — show the least information. This inverts the expected relationship between operation complexity and observability.
+
+- **Wasted Infrastructure:** The event bus system (`AtomicEventBus`, `BatchDispatcher`, `StreamPipelineConsumer`, `CorrelationService`) was specifically designed to handle multi-agent streaming scenarios. The workflow executor publishes some events (`stream.agent.*`, `workflow.step.*`, `workflow.task.*`) but doesn't leverage the consumption side. Three of the five published event types have no UI consumers at all ([research §2.3, Event Type Coverage table](../research/docs/2026-02-27-workflow-tui-rendering-unification.md)).
+
+- **Technical Debt:** Two separate rendering paths mean every UI improvement (new part types, rendering optimizations, accessibility features) must be duplicated or doesn't apply to workflows.
+
+---
+
+## 3. Goals and Non-Goals
+
+### 3.1 Functional Goals
+
+- [ ] Workflow sub-agents stream text content through the same event bus pipeline as normal chat, with incremental rendering via `TextPartDisplay`
+- [ ] Thinking blocks from workflow sub-agents are captured and displayed via `ReasoningPartDisplay`, including duration tracking
+- [ ] Tool lifecycle events (`stream.tool.start/complete`) from workflow sub-agents render inline via `ToolPartDisplay` with collapsible output
+- [ ] Token usage from workflow sub-agents is tracked and displayed in both `LoadingIndicator` (during streaming) and `CompletionSummary` (after completion)
+- [ ] Sub-agent tree entries for workflow agents show live tool progress, current tool name, tool count, and elapsed time — matching normal chat behavior
+- [ ] `workflow.step.*` events are consumed by UI components to display step/node transition progress
+- [ ] `workflow.task.*` events are consumed by UI components to display task list updates inline
+- [ ] `spawnSubagentParallel` returns streaming-aware results via the `SubagentStreamAdapter` — the old silent accumulation path is removed entirely
+- [ ] The rendering pipeline correctly handles concurrent sub-agent streams without content interleaving corruption
+
+### 3.2 Non-Goals (Out of Scope)
+
+- [ ] We will NOT refactor the graph execution engine itself — it remains generic and UI-independent
+- [ ] We will NOT change the `WorkflowSDK` class or reconcile it with `CommandContext` in this effort (covered by the [Unified Workflow Execution spec](./unified-workflow-execution.md))
+- [ ] We will NOT generalize Ralph-specific coupling points (session dir, task IDs, etc.) — that is addressed by the Unified Workflow Execution RFC
+- [ ] We will NOT introduce new part types beyond what is needed for `workflow.step.*` and `workflow.task.*` event rendering
+- [ ] We will NOT change the SDK adapters (`claude-adapter.ts`, `copilot-adapter.ts`, `opencode-adapter.ts`) — they remain as-is for main chat
+- [ ] We will NOT modify the graph engine's `StepResult` yield format or the `streamGraph()` async generator
+
+---
+
+## 4. Proposed Solution (High-Level Design)
+
+### 4.1 System Architecture Diagram
+
+```mermaid
+%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#f8f9fa','primaryTextColor':'#2c3e50','primaryBorderColor':'#4a5568','lineColor':'#4a90e2','secondaryColor':'#ffffff','tertiaryColor':'#e9ecef'}}}%%
+
+flowchart TB
+    classDef core fill:#4a90e2,stroke:#357abd,stroke-width:2.5px,color:#ffffff,font-weight:600
+    classDef adapter fill:#667eea,stroke:#5a67d8,stroke-width:2.5px,color:#ffffff,font-weight:600
+    classDef consumer fill:#48bb78,stroke:#38a169,stroke-width:2.5px,color:#ffffff,font-weight:600
+    classDef renderer fill:#ed8936,stroke:#dd6b20,stroke-width:2.5px,color:#ffffff,font-weight:600
+    classDef workflow fill:#9f7aea,stroke:#805ad5,stroke-width:2.5px,color:#ffffff,font-weight:600
+    classDef existing fill:#718096,stroke:#4a5568,stroke-width:2px,color:#ffffff,font-weight:600
+
+    subgraph WorkflowExecution["Workflow Execution"]
+        direction TB
+        Executor(["<b>WorkflowExecutor</b><br><i>executeWorkflow()</i>"]):::workflow
+        GraphEngine(["<b>GraphExecutor</b><br><i>streamSteps()</i>"]):::workflow
+        SpawnParallel(["<b>spawnSubagentParallel</b><br><i>Per-agent SDK sessions</i>"]):::workflow
+    end
+
+    subgraph AdapterLayer["Stream Adapter Layer"]
+        direction TB
+        ClaudeAdapter["<b>ClaudeStreamAdapter</b><br><i>Existing</i>"]:::existing
+        CopilotAdapter["<b>CopilotStreamAdapter</b><br><i>Existing</i>"]:::existing
+        OpenCodeAdapter["<b>OpenCodeStreamAdapter</b><br><i>Existing</i>"]:::existing
+        SubagentAdapter["<b>SubagentStreamAdapter</b><br><i>NEW — per sub-agent session</i>"]:::adapter
+        WorkflowAdapter["<b>WorkflowEventAdapter</b><br><i>Enhanced — step/task events</i>"]:::adapter
+    end
+
+    subgraph EventPipeline["Shared Event Pipeline"]
+        direction TB
+        EventBus(["<b>AtomicEventBus</b><br><i>Typed pub/sub</i>"]):::core
+        BatchDispatcher(["<b>BatchDispatcher</b><br><i>16ms frame-aligned</i>"]):::core
+        Correlation(["<b>CorrelationService</b><br><i>Agent attribution</i>"]):::consumer
+        PipelineConsumer(["<b>StreamPipelineConsumer</b><br><i>BusEvent → StreamPartEvent</i>"]):::consumer
+    end
+
+    subgraph UIRendering["UI Rendering"]
+        direction TB
+        Reducer(["<b>applyStreamPartEvent</b><br><i>React state reducer</i>"]):::renderer
+        PartRegistry(["<b>PART_REGISTRY</b><br><i>Type → Renderer dispatch</i>"]):::renderer
+        Renderers["TextPart · ReasoningPart<br>ToolPart · AgentPart<br><b>WorkflowStepPart (NEW)</b>"]:::renderer
+    end
+
+    Executor --> GraphEngine
+    GraphEngine --> SpawnParallel
+
+    SpawnParallel -->|"NEW: Create adapter<br>per sub-agent session"| SubagentAdapter
+    Executor -->|"step/task events"| WorkflowAdapter
+
+    ClaudeAdapter --> EventBus
+    CopilotAdapter --> EventBus
+    OpenCodeAdapter --> EventBus
+    SubagentAdapter -->|"stream.text/thinking/<br>tool/usage/agent events"| EventBus
+    WorkflowAdapter -->|"workflow.step/task events"| EventBus
+
+    EventBus --> BatchDispatcher
+    BatchDispatcher --> Correlation
+    Correlation --> PipelineConsumer
+    PipelineConsumer --> Reducer
+    Reducer --> PartRegistry
+    PartRegistry --> Renderers
+
+    style WorkflowExecution fill:#ffffff,stroke:#805ad5,stroke-width:2px,stroke-dasharray:8 4
+    style AdapterLayer fill:#ffffff,stroke:#5a67d8,stroke-width:2px,stroke-dasharray:8 4
+    style EventPipeline fill:#ffffff,stroke:#4a90e2,stroke-width:2px,stroke-dasharray:8 4
+    style UIRendering fill:#ffffff,stroke:#dd6b20,stroke-width:2px,stroke-dasharray:8 4
+```
+
+### 4.2 Architectural Pattern
+
+We adopt a **Bus-Integrated Sub-Agent Sessions** pattern (Option A from [research §4.2](../research/docs/2026-02-27-workflow-tui-rendering-unification.md)): instead of silently consuming sub-agent streams, we create lightweight stream adapters for each sub-agent session that publish normalized events to the shared `AtomicEventBus`. The existing `CorrelationService` is enhanced to attribute sub-agent events to their parent workflow agent, enabling proper scoping in the UI.
+
+This approach was selected over the alternatives because:
+- **Option B (Workflow-Specific Stream Adapter)** would create a third rendering path rather than reusing the existing one
+- **Option C (Inline Agent Rendering via `streamAndWait`)** would serialize sub-agent execution, breaking the parallel execution model that workflows depend on
+
+### 4.3 Key Components
+
+| Component                            | Responsibility                                                                                  | Technology / Location                                          | Justification                                                                                 |
+| ------------------------------------ | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `SubagentStreamAdapter`              | Normalizes per-session SDK streams into `BusEvent`s for sub-agents                              | `src/events/adapters/subagent-adapter.ts` (NEW)                | Reuses existing adapter pattern; each sub-agent session gets its own adapter instance         |
+| `CorrelationService` (enhanced)      | Tracks sub-agent session → parent agent ID mapping                                              | `src/events/consumers/correlation-service.ts` (MODIFIED)       | Already enriches events with `resolvedAgentId`; needs sub-agent session registry              |
+| `StreamPipelineConsumer` (enhanced)  | Maps `workflow.step.*` and `workflow.task.*` events to `StreamPartEvent`s                       | `src/events/consumers/stream-pipeline-consumer.ts` (MODIFIED)  | Existing BusEvent→StreamPartEvent mapper; needs new event type handlers                       |
+| `WorkflowStepPartDisplay`            | Renders workflow step transitions as progress markers                                           | `src/ui/components/parts/workflow-step-part-display.tsx` (NEW) | Visual indicator for graph node transitions within the message stream                         |
+| `spawnSubagentParallel` (refactored) | Creates stream adapters alongside sessions; returns `SubagentStreamResult[]` with full metadata | `src/ui/chat.tsx` (MODIFIED)                                   | Core integration point — the silent consumption loop is replaced with adapter-based streaming |
+
+---
+
+## 5. Detailed Design
+
+### 5.1 SubagentStreamAdapter
+
+A new, lightweight adapter that bridges a sub-agent's SDK session stream to the shared event bus. Unlike the main SDK adapters (which handle full session lifecycle), this adapter is scoped to a single sub-agent execution.
+
+**Location:** `src/events/adapters/subagent-adapter.ts`
+
+**Interface:**
+
+```typescript
+interface SubagentStreamAdapterOptions {
+  bus: AtomicEventBus;
+  sessionId: string;        // parent session ID for bus event envelope
+  agentId: string;           // sub-agent ID for correlation
+  parentAgentId?: string;    // parent agent ID (for nested agents)
+  runId: string;             // workflow run ID for staleness detection
+}
+
+class SubagentStreamAdapter {
+  constructor(options: SubagentStreamAdapterOptions);
+
+  /**
+   * Consumes an SDK session stream, publishing normalized events
+   * to the bus. Returns a SubagentStreamResult with full streaming
+   * metadata (token counts, thinking duration, tool details).
+   */
+  consumeStream(
+    stream: AsyncIterable<StreamMessage>,
+    abortSignal?: AbortSignal
+  ): Promise<SubagentStreamResult>;
+}
+```
+
+**Behavior:**
+
+The adapter iterates the SDK stream and for each message:
+
+| SDK Message Type | Bus Event Published                                | Accumulation                     |
+| ---------------- | -------------------------------------------------- | -------------------------------- |
+| `text`           | `stream.text.delta` with `agentId` in metadata     | Accumulates full text for result |
+| `thinking`       | `stream.thinking.delta` with `agentId` in metadata | —                                |
+| `tool_use`       | `stream.tool.start`                                | Increments `toolUses` counter    |
+| `tool_result`    | `stream.tool.complete`                             | —                                |
+| `usage`          | `stream.usage` with per-agent token counts         | —                                |
+
+On stream completion, publishes `stream.text.complete` and returns a `SubagentStreamResult` containing the full accumulated text, tool details, token usage, and thinking duration. The old `MAX_SUMMARY_LENGTH` = 4000 char truncation is removed — callers receive the complete output.
+
+**Key constraint:** The adapter must publish events with the **parent session's** `sessionId` (not the sub-agent's isolated session ID), so the `CorrelationService` can attribute them to the correct message context. The `agentId` field in event metadata differentiates which sub-agent produced the event.
+
+### 5.2 CorrelationService Enhancement
+
+The `CorrelationService` at `src/events/consumers/correlation-service.ts` currently tracks agent context via `resolvedAgentId` and `isSubagentTool`. It needs a sub-agent session registry to map incoming events to the correct parent workflow agent.
+
+**New internal state:**
+
+```typescript
+// Maps sub-agent agentId → parent context
+private subagentRegistry: Map<string, {
+  parentAgentId: string;
+  workflowRunId: string;
+  nodeId?: string;
+}>;
+
+registerSubagent(agentId: string, context: SubagentContext): void;
+unregisterSubagent(agentId: string): void;
+```
+
+**Enrichment behavior:**
+
+When processing events with `agentId` in metadata:
+1. Look up the `agentId` in `subagentRegistry`
+2. If found, set `resolvedAgentId` to the sub-agent's `agentId`
+3. Set `parentAgentId` to the registered parent
+4. Set `isSubagentTool = true` for tool events
+5. Set `suppressFromMainChat = false` (workflow sub-agent events SHOULD render)
+
+This enables the UI to scope sub-agent content within the correct agent tree node.
+
+### 5.3 spawnSubagentParallel Refactoring
+
+The core change is in `src/ui/chat.tsx`'s `spawnSubagentParallel` closure. The silent consumption loop is replaced with `SubagentStreamAdapter` usage.
+
+**Current flow (silent):**
+```typescript
+// chat.tsx:3970-3984
+for await (const msg of stream) {
+  if (msg.type === "tool_use") { toolUses++; }
+  else if (msg.type === "text") { summaryParts.push(msg.content); }
+}
+```
+
+**New flow (bus-integrated):**
+```typescript
+// Each sub-agent gets a stream adapter
+const adapter = new SubagentStreamAdapter({
+  bus: eventBus,
+  sessionId: currentSessionId,
+  agentId: agent.agentId,
+  parentAgentId: agent.parentAgentId,
+  runId: workflowRunId,
+});
+
+// Register with correlation service for event attribution
+correlationService.registerSubagent(agent.agentId, {
+  parentAgentId: agent.parentAgentId,
+  workflowRunId,
+});
+
+try {
+  // Adapter publishes events AND returns SubagentStreamResult
+  const result = await adapter.consumeStream(stream, agentAbort.signal);
+  return result;
+} finally {
+  correlationService.unregisterSubagent(agent.agentId);
+  session.destroy();
+}
+```
+
+**Breaking change:** The old `SubagentResult` type and the silent consumption loop are removed entirely. `spawnSubagentParallel` now returns `SubagentStreamResult[]` which includes richer metadata (token counts, thinking duration, tool details) alongside the full untruncated output. All callers (workflow node functions, `@agent` commands) must use the new return type.
+
+**Universal application:** The `SubagentStreamAdapter` is used for all sub-agent spawns — both workflow and non-workflow (e.g., `@agent` chat commands). There is no opt-in flag; `spawnSubagentParallel` always creates adapters. The old silent consumption path is deleted.
+
+### 5.4 Workflow Event UI Consumers
+
+Three bus event types are published but have no UI consumers ([research §2.3](../research/docs/2026-02-27-workflow-tui-rendering-unification.md)):
+
+#### 5.4.1 `workflow.step.start` / `workflow.step.complete`
+
+**New `StreamPartEvent` type:** `workflow-step`
+
+**New `Part` type:** `WorkflowStepPart`
+
+```typescript
+interface WorkflowStepPart {
+  type: "workflow-step";
+  id: string;
+  nodeId: string;
+  nodeName: string;
+  status: "running" | "completed" | "error";
+  startedAt: number;
+  completedAt?: number;
+  durationMs?: number;
+}
+```
+
+**Rendering:** `WorkflowStepPartDisplay` renders as a subtle divider/progress marker:
+
+```
+── Step: planner (running) ──────────────────
+```
+```
+── Step: planner ✓ (2.3s) ───────────────────
+```
+
+This integrates into the existing `PART_REGISTRY` dispatch:
+
+```typescript
+// registry.tsx addition
+"workflow-step": WorkflowStepPartDisplay,
+```
+
+#### 5.4.2 `workflow.task.update`
+
+**Handled by existing infrastructure:** The `TaskListPart` and `TaskListPartDisplay` already exist in the parts system. `workflow.task.update` events should be mapped to `task-list` `StreamPartEvent`s, updating the inline task list within the message.
+
+**Mapping in `StreamPipelineConsumer`:**
+
+```typescript
+case "workflow.task.update":
+  return {
+    type: "task-list-update",
+    messageId: currentMessageId,
+    tasks: event.data.tasks,
+  };
+```
+
+### 5.5 Per-Agent Streaming Content Scoping
+
+When multiple workflow sub-agents stream concurrently, their content must be scoped correctly in the UI. The `ParallelAgentsTree` component already renders per-agent entries. The enhancement is displaying each agent's streaming content (text, thinking, tools) nested under its tree entry.
+
+**Approach:** The `AgentPartDisplay` at `src/ui/components/parts/agent-part-display.tsx` is enhanced to render inline content for agents that have streaming parts:
+
+```
+├─ ✓ worker-1 (analyze auth module) — 3 tools · 4.2s
+│    ● Generated authentication middleware...
+│    ∴ Thought (1.2s)
+│    ⚙ edit src/auth/middleware.ts ✓
+├─ ⟳ worker-2 (update API routes) — 1 tool · 2.1s
+│    ● Updating route handlers...
+└─ ◌ worker-3 (write tests) — pending
+```
+
+**Data model:** Each agent entry in the `Part[]` array gains an optional `inlineParts: Part[]` field that holds the agent's streaming content. The `applyStreamPartEvent` reducer routes events with `resolvedAgentId` to the correct agent's `inlineParts` sub-array.
+
+### 5.6 Token Count Aggregation
+
+Token usage from workflow sub-agents flows through `stream.usage` events to the existing subscription at `chat.tsx:2755`. Enhancement:
+
+- **Per-agent tokens:** Each `stream.usage` event carries `agentId` in metadata. The UI tracks per-agent token counts for display in the sub-agent tree.
+- **Aggregate tokens:** The `LoadingIndicator` and `CompletionSummary` show total tokens across all active workflow sub-agents.
+- **Completion summary:** After workflow completion, shows aggregate stats: `⣿ Workflow completed in Xs · ↓ Xk tokens · N agents`
+
+### 5.7 Data Flow for Unified Rendering
+
+Complete data flow after unification:
+
+```
+Workflow Executor
+  → executeWorkflow()
+    → publishStepStart() → bus → WorkflowStepPart (NEW consumer)
+    → spawnSubagentParallel()
+      → For each agent:
+        → createSubagentSession()
+        → SubagentStreamAdapter.consumeStream()
+          → stream.text.delta → bus → BatchDispatcher → CorrelationService
+            → StreamPipelineConsumer → text-delta StreamPartEvent
+              → applyStreamPartEvent → TextPart (scoped to agent)
+          → stream.thinking.delta → bus → ... → ReasoningPart (scoped to agent)
+          → stream.tool.start → bus → ... → ToolPart (scoped to agent)
+          → stream.usage → bus → ... → token count update
+        → Returns SubagentStreamResult (full metadata)
+    → publishStepComplete() → bus → WorkflowStepPart update
+    → publishTaskUpdate() → bus → TaskListPart update (existing)
+  → Completion summary with aggregate tokens
+```
+
+---
+
+## 6. Alternatives Considered
+
+| Option                                              | Pros                                                                                     | Cons                                                                                                           | Reason for Rejection                                                                                     |
+| --------------------------------------------------- | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| **A: Bus-Integrated Sub-Agent Sessions (Selected)** | Reuses entire existing pipeline; sub-agents render identically to chat; minimal new code | Requires correlation service enhancement; concurrent stream management                                         | **Selected:** Maximum reuse of existing infrastructure; smallest gap between chat and workflow rendering |
+| **B: Workflow-Specific Stream Adapter**             | Could add workflow-specific rendering features                                           | Creates a third rendering path; duplicates pipeline logic; ongoing maintenance burden                          | Would not achieve rendering parity — workflow content would still look different from chat content       |
+| **C: Inline Agent Rendering via `streamAndWait`**   | Simplest implementation; `streamAndWait` already works                                   | Serializes sub-agent execution (breaks parallel model); each agent blocks until complete; significantly slower | Workflows spawn 3-5+ parallel sub-agents; serialization would multiply execution time proportionally     |
+| **D: Post-hoc Rendering (accumulate then display)** | No concurrent stream complexity                                                          | No streaming feedback; users see nothing until agent completes; loses the "live" feel                          | Worse than current state for long-running agents (30s+ per agent) — users need real-time feedback        |
+
+---
+
+## 7. Cross-Cutting Concerns
+
+### 7.1 Performance
+
+- **Concurrent stream volume:** A workflow with 5 parallel sub-agents could produce 5× the event volume of a single chat stream. The `BatchDispatcher`'s 16ms frame-aligned batching already coalesces events, but peak throughput should be load-tested.
+- **Part array growth:** Each sub-agent adds text, thinking, and tool parts. For workflows with many agents, the `Part[]` array per message could grow large. The existing binary search insertion (`src/ui/parts/store.ts:42`) is O(log n) per insertion.
+- **Memory:** Sub-agent sessions are destroyed after completion. Stream adapter instances are lightweight and GC'd after `consumeStream()` returns.
+
+### 7.2 Observability Strategy
+
+- **Existing metrics:** `stream.usage` events already carry token counts. No new metrics infrastructure needed.
+- **Step timing:** `workflow.step.start/complete` events carry timestamps. `WorkflowStepPart` computes `durationMs` for display.
+- **Agent-level observability:** Per-agent tool counts, duration, and token usage are tracked in the sub-agent tree.
+
+### 7.3 Error Handling
+
+- **Sub-agent abort:** The existing three-tier abort chain (external → parallel → per-agent) is preserved. The `SubagentStreamAdapter` respects the abort signal and publishes a `stream.text.complete` with error state on abort.
+- **Stream errors:** If a sub-agent stream throws, the adapter catches the error, publishes an error event, and returns a failure `SubagentStreamResult` with the error details.
+- **Stale events:** The `runId` field in event metadata allows consumers to ignore events from cancelled/previous workflow runs.
+
+### 7.4 Breaking Changes
+
+- **`SubagentResult` replaced by `SubagentStreamResult`:** The old `SubagentResult` type (`{ agentId, success, output, toolUses, durationMs }`) is removed. The new `SubagentStreamResult` includes richer fields: `{ agentId, success, output, toolUses, durationMs, tokenUsage, thinkingDurationMs, toolDetails }`. All callers must be updated.
+- **Silent consumption loop removed:** The `for await (msg of stream)` loop in `spawnSubagentParallel` that silently accumulated text is deleted. All sub-agent streams now flow through `SubagentStreamAdapter` and the event bus.
+- **Output truncation removed:** The `MAX_SUMMARY_LENGTH = 4000` character truncation is removed. `SubagentStreamResult.output` contains the complete untruncated text.
+- **Existing tests updated:** Tests referencing `SubagentResult` must be updated to use `SubagentStreamResult` and verify event bus publication.
+
+---
+
+## 8. Migration, Rollout, and Testing
+
+### 8.1 Deployment Strategy
+
+- [ ] **Phase 1 — SubagentStreamAdapter + CorrelationService enhancement:** Implement the adapter and correlation changes. Workflow sub-agents begin publishing events to the bus. UI renders them through the existing pipeline. This is the core architectural change.
+- [ ] **Phase 2 — Workflow event consumers:** Add `WorkflowStepPartDisplay` and wire `workflow.step.*` / `workflow.task.*` events to the parts pipeline. This adds step transition markers and inline task updates.
+- [ ] **Phase 3 — Per-agent inline content:** Enhance `AgentPartDisplay` to render `inlineParts` for each agent. Add per-agent token tracking. This is the visual polish phase.
+- [ ] **Phase 4 — Performance validation and tuning:** Load-test with concurrent sub-agents, tune `BatchDispatcher` if needed, validate memory usage.
+
+### 8.2 Test Plan
+
+- **Unit Tests:**
+  - `SubagentStreamAdapter`: Verify event publication for each SDK message type; verify `SubagentStreamResult` fields; verify abort handling
+  - `CorrelationService`: Verify sub-agent registration/unregistration; verify event enrichment with parent context
+  - `StreamPipelineConsumer`: Verify `workflow.step.*` and `workflow.task.*` mapping to `StreamPartEvent`s
+  - `applyStreamPartEvent`: Verify agent-scoped part insertion for events with `resolvedAgentId`
+
+- **Integration Tests:**
+  - End-to-end workflow execution with bus event verification: assert that running a workflow produces the expected sequence of bus events
+  - Concurrent sub-agent streaming: verify content from parallel agents is correctly scoped and doesn't interleave
+  - Abort mid-workflow: verify cleanup of adapter instances, correlation registry entries, and UI state
+
+- **E2E Tests:**
+  - Visual verification that workflow execution displays streaming text, thinking blocks, tool progress, and token counts
+  - Verify sub-agent tree shows live progress during workflow execution
+  - Verify step transition markers appear between workflow graph nodes
+
+---
+
+## 9. Open Questions / Unresolved Issues
+
+1. **Concurrency rendering model:** ✅ **Resolved.** Workflow sub-agents use the same sub-agent tree design defined in [docs/ui-design-patterns.md](../docs/ui-design-patterns.md) — tree-based UI with `├─●` / `└─●` connectors, per-agent task descriptions, tool counts, and current tool names streaming per-branch. Tools and text blocks stream using the same rendering engine as the main TUI (via the shared event bus pipeline). No separate rendering mode for workflows.
+
+2. **Agent nesting depth:** ✅ **Resolved.** 1 level deep — only direct sub-agents of the workflow are shown in the tree. Nested sub-sub-agents (e.g., a worker agent's Task tool sub-agents) are summarized in the parent agent's tool count, not rendered as separate tree entries. This keeps the UI manageable and consistent with the existing `ParallelAgentsTree` max-5 visible limit.
+
+3. **Per-node message boundaries:** ✅ **Resolved.** Single message with step dividers — all workflow output renders within one assistant message. Step transitions between graph nodes are shown as subtle inline dividers (e.g., `── Step: planner ✓ ──`). This keeps the chat history clean and avoids fragmenting the workflow's output across multiple message bubbles.
+
+4. **Token count granularity:** ✅ **Resolved.** Aggregate only — a single total token count is shown in the workflow's `CompletionSummary` (e.g., `⣿ Workflow completed in 45s · ↓ 12k tokens · 5 agents`). Individual per-agent or per-node token breakdowns are not displayed.
+
+5. **Non-workflow sub-agent opt-in:** ✅ **Resolved.** Apply to all sub-agents — bus-integrated streaming rendering is enabled for all sub-agent spawns, including non-workflow `@agent` chat commands. This ensures consistent rendering behavior across all sub-agent contexts and avoids maintaining two code paths in `spawnSubagentParallel`.
+
+6. **`workflow.step.*` visual treatment:** ✅ **Resolved.** Subtle inline dividers — horizontal rule-style markers like `── Step: planner ✓ (2.3s) ──` using dimmed styling, consistent with the existing UI design patterns from [docs/ui-design-patterns.md](../docs/ui-design-patterns.md). Running steps show `── Step: planner (running) ──`; completed steps show the checkmark and duration.
+
+---
+
+## Appendix A: File Change Inventory
+
+| File                                                     | Change Type | Description                                                                                                      |
+| -------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------- |
+| `src/events/adapters/subagent-adapter.ts`                | **NEW**     | `SubagentStreamAdapter` class — bridges sub-agent SDK streams to event bus                                       |
+| `src/events/consumers/correlation-service.ts`            | MODIFIED    | Add sub-agent registry for event attribution                                                                     |
+| `src/events/consumers/stream-pipeline-consumer.ts`       | MODIFIED    | Add handlers for `workflow.step.*` and `workflow.task.*` events                                                  |
+| `src/ui/chat.tsx`                                        | MODIFIED    | Refactor `spawnSubagentParallel` to use `SubagentStreamAdapter`; pass event bus + correlation service to adapter |
+| `src/ui/parts/stream-pipeline.ts`                        | MODIFIED    | Add agent-scoped part routing in `applyStreamPartEvent`                                                          |
+| `src/ui/parts/types.ts`                                  | MODIFIED    | Add `WorkflowStepPart` type definition; add `inlineParts` to agent parts                                         |
+| `src/ui/components/parts/registry.tsx`                   | MODIFIED    | Register `WorkflowStepPartDisplay` in `PART_REGISTRY`                                                            |
+| `src/ui/components/parts/workflow-step-part-display.tsx` | **NEW**     | Renderer for workflow step transition markers                                                                    |
+| `src/ui/components/parts/agent-part-display.tsx`         | MODIFIED    | Render `inlineParts` for agents with streaming content                                                           |
+| `src/events/adapters/workflow-adapter.ts`                | MODIFIED    | Minor — ensure step/task events carry consistent metadata                                                        |
+
+## Appendix B: Event Flow Diagram (Unified State)
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                         EVENT BUS (AtomicEventBus)                      │
+│                                                                         │
+│  PRODUCERS:                          CONSUMERS:                         │
+│  ┌──────────────────┐               ┌────────────────────────────────┐  │
+│  │ ClaudeAdapter    │──┐            │ BatchDispatcher (16ms batch)   │  │
+│  │ CopilotAdapter   │──┤            │   → CorrelationService        │  │
+│  │ OpenCodeAdapter   │──┤  publish   │     → StreamPipelineConsumer  │  │
+│  │ SubagentAdapter ◆ │──┼──────────→│       → applyStreamPartEvent  │  │
+│  │ WorkflowAdapter   │──┘            │         → Part[] → Renderers │  │
+│  └──────────────────┘               └────────────────────────────────┘  │
+│                                                                         │
+│  ◆ = NEW component                                                      │
+│                                                                         │
+│  Events now unified:                                                    │
+│  ├── stream.text.delta      (chat ✓  workflow ✓)                       │
+│  ├── stream.thinking.delta  (chat ✓  workflow ✓)                       │
+│  ├── stream.tool.start      (chat ✓  workflow ✓)                       │
+│  ├── stream.tool.complete   (chat ✓  workflow ✓)                       │
+│  ├── stream.agent.start     (chat ✓  workflow ✓)                       │
+│  ├── stream.agent.update    (chat ✓  workflow ✓)                       │
+│  ├── stream.agent.complete  (chat ✓  workflow ✓)                       │
+│  ├── stream.usage           (chat ✓  workflow ✓)                       │
+│  ├── workflow.step.start    (chat n/a workflow ✓)  ← NEW consumer     │
+│  ├── workflow.step.complete (chat n/a workflow ✓)  ← NEW consumer     │
+│  └── workflow.task.update   (chat n/a workflow ✓)  ← NEW consumer     │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+## Appendix C: Related Research & Specs
+
+| Document                                                                                                                                            | Relevance                                                                                         |
+| --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| [research/docs/2026-02-27-workflow-tui-rendering-unification.md](../research/docs/2026-02-27-workflow-tui-rendering-unification.md)                 | **Primary research** — full pipeline analysis, gap identification, integration point mapping      |
+| [research/docs/2026-02-26-streaming-architecture-event-bus-migration.md](../research/docs/2026-02-26-streaming-architecture-event-bus-migration.md) | Event bus migration context — confirms bus infrastructure is ready for multi-producer use         |
+| [research/docs/2026-02-25-unified-workflow-execution-research.md](../research/docs/2026-02-25-unified-workflow-execution-research.md)               | Ralph-specific coupling analysis — identifies 9 coupling points being generalized separately      |
+| [research/docs/2026-02-25-ui-workflow-coupling.md](../research/docs/2026-02-25-ui-workflow-coupling.md)                                             | `CommandContext` bridge analysis — maps the communication interface between workflows and TUI     |
+| [research/docs/2026-02-16-opentui-rendering-architecture.md](../research/docs/2026-02-16-opentui-rendering-architecture.md)                         | OpenTUI rendering pipeline — confirms three-pass render + dirty tracking supports batched updates |
+| [research/docs/2026-02-15-subagent-event-flow-diagram.md](../research/docs/2026-02-15-subagent-event-flow-diagram.md)                               | Sub-agent event race conditions — relevant to concurrent workflow agent event ordering            |
+| [research/docs/2026-02-12-tui-layout-streaming-content-ordering.md](../research/docs/2026-02-12-tui-layout-streaming-content-ordering.md)           | Streaming content ordering — informs how concurrent agent content should be positioned            |
+| [specs/unified-workflow-execution.md](./unified-workflow-execution.md)                                                                              | Companion spec — generalizes Ralph-specific coupling; this spec handles the rendering pipeline    |
+| [specs/chat-system-parts-based-rendering.md](./chat-system-parts-based-rendering.md)                                                                | Parts-based rendering design — defines the `Part[]` pipeline this spec integrates with            |
+| [specs/streaming-architecture-event-bus-migration.md](./streaming-architecture-event-bus-migration.md)                                              | Event bus migration spec — defines the bus architecture this spec extends                         |
diff --git a/src/cli.ts b/src/cli.ts
index 75d345abae..584db8618e 100755
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -105,7 +105,6 @@ export function createProgram() {
       "dark"
     )
     .option("-m, --model <name>", "Model to use for the chat session")
-    .option("--max-iterations <n>", "Maximum iterations for workflow mode", "100")
     .argument("[prompt...]", "Initial prompt to send (opens interactive session with prompt)")
     .addHelpText(
       "after",
@@ -115,7 +114,6 @@ Examples:
   $ atomic chat -a opencode                  Start chat with OpenCode
   $ atomic chat -a copilot --workflow        Start workflow-enabled chat with Copilot
   $ atomic chat --theme light                Start chat with light theme
-  $ atomic chat -w --max-iterations 50       Start workflow with iteration limit
   $ atomic chat "fix the typecheck errors"   Start chat with an initial prompt
   $ atomic chat -a claude "refactor utils"   Start chat with agent and prompt
 
@@ -165,7 +163,6 @@ Slash Commands (in workflow mode):
         workflow: localOpts.workflow,
         theme: localOpts.theme as "dark" | "light",
         model: localOpts.model,
-        maxIterations: parseInt(localOpts.maxIterations, 10),
         initialPrompt: prompt,
       });
 
diff --git a/src/commands/chat.ts b/src/commands/chat.ts
index 2941871007..9aa30d5ed1 100644
--- a/src/commands/chat.ts
+++ b/src/commands/chat.ts
@@ -36,6 +36,7 @@ import {
   createCopilotClient,
 } from "../sdk/clients/index.ts";
 import { createTodoWriteTool } from "../sdk/tools/todo-write.ts";
+import { registerCustomTools } from "../sdk/tools/index.ts";
 
 // Chat UI imports
 import {
@@ -63,8 +64,6 @@ export interface ChatCommandOptions {
   model?: string;
   /** Enable graph workflow mode */
   workflow?: boolean;
-  /** Maximum iterations for workflow */
-  maxIterations?: number;
   /** Initial prompt to send on session start */
   initialPrompt?: string;
 }
@@ -247,6 +246,9 @@ export async function chatCommand(options: ChatCommandOptions = {}): Promise<num
     client.registerTool(createTodoWriteTool());
   }
 
+  // Discover and register custom tools before starting the client
+  await registerCustomTools(client);
+
   try {
     await client.start();
 
diff --git a/src/commands/init.ts b/src/commands/init.ts
index 2e865540d6..007e3360f7 100644
--- a/src/commands/init.ts
+++ b/src/commands/init.ts
@@ -29,6 +29,7 @@ import {
 import { displayBanner } from "../utils/banner";
 import { copyFile, pathExists } from "../utils/copy";
 import { detectInstallationType, getConfigRoot } from "../utils/config-path";
+import { mergeJsonFile } from "../utils/merge";
 import { isWindows, isWslInstalled, WSL_INSTALL_URL, getOppositeScriptExtension } from "../utils/detect";
 import { trackAtomicCommand, handleTelemetryConsent, type AgentType } from "../telemetry";
 import { saveAtomicConfig } from "../utils/atomic-config";
@@ -188,6 +189,32 @@ async function syncProjectScmSkills(options: SyncProjectScmSkillsOptions): Promi
   return copiedCount;
 }
 
+function decodeSpawnOutput(output: Uint8Array): string {
+  return new TextDecoder().decode(output).trim();
+}
+
+function runPlaywrightCliInstall(): void {
+  const playwrightCliPath = Bun.which("playwright-cli");
+  const command = playwrightCliPath
+    ? [playwrightCliPath, "install"]
+    : [process.execPath, "x", "@playwright/cli", "install"];
+
+  const result = Bun.spawnSync({
+    cmd: command,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  if (result.success) {
+    return;
+  }
+
+  const stderr = decodeSpawnOutput(result.stderr);
+  const stdout = decodeSpawnOutput(result.stdout);
+  const details = stderr || stdout || "No command output captured.";
+  throw new Error(`Failed to run '${command.join(" ")}': ${details}`);
+}
+
 /**
  * Run the interactive init command
  */
@@ -391,6 +418,20 @@ export async function initCommand(options: InitOptions = {}): Promise<void> {
       configRoot,
     });
 
+    // Merge JSON config files (e.g., .mcp.json, mcp-config.json)
+    for (const file of agent.merge_files) {
+      const srcFile = join(configRoot, file);
+      const destFile = join(targetDir, file);
+
+      if (await pathExists(srcFile)) {
+        if (await pathExists(destFile)) {
+          await mergeJsonFile(srcFile, destFile);
+        } else {
+          await copyFile(srcFile, destFile);
+        }
+      }
+    }
+
     // Save SCM selection to .atomic/settings.json
     await saveAtomicConfig(targetDir, {
       scm: scmType,
@@ -412,6 +453,17 @@ export async function initCommand(options: InitOptions = {}): Promise<void> {
     process.exit(1);
   }
 
+  const playwrightInstallSpinner = spinner();
+  playwrightInstallSpinner.start("Installing Playwright browser runtime...");
+  try {
+    runPlaywrightCliInstall();
+    playwrightInstallSpinner.stop("Playwright browser runtime installed");
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    playwrightInstallSpinner.stop("Playwright browser runtime installation failed");
+    log.warn(`Could not run 'playwright-cli install': ${message}`);
+  }
+
   // Check for WSL on Windows
   if (isWindows() && !isWslInstalled()) {
     note(
diff --git a/src/commands/update.ts b/src/commands/update.ts
index 2a053fc72b..7951c27ca1 100644
--- a/src/commands/update.ts
+++ b/src/commands/update.ts
@@ -7,7 +7,7 @@
 import { spinner, log } from "@clack/prompts";
 import { join } from "path";
 import { tmpdir } from "os";
-import { mkdir, rm, rename, chmod } from "fs/promises";
+import { mkdir, rm, rename, chmod, copyFile as fsCopyFile, unlink } from "fs/promises";
 import { existsSync } from "fs";
 
 import {
@@ -53,8 +53,26 @@ export function isNewerVersion(v1: string, v2: string): boolean {
   return patch1 > patch2;
 }
 
+/**
+ * Move a file across filesystems by falling back to copy + unlink
+ * when rename fails with EXDEV (cross-device link).
+ */
+async function crossDeviceRename(src: string, dest: string): Promise<void> {
+  try {
+    await rename(src, dest);
+  } catch (err: unknown) {
+    if (err && typeof err === "object" && "code" in err && err.code === "EXDEV") {
+      await fsCopyFile(src, dest);
+      await unlink(src);
+    } else {
+      throw err;
+    }
+  }
+}
+
 /**
  * Replace binary on Unix systems using atomic rename.
+ * Falls back to copy + unlink for cross-device moves (e.g. WSL).
  *
  * @param newBinaryPath - Path to the new binary in temp directory
  * @param targetPath - Path where the binary should be installed
@@ -62,8 +80,8 @@ export function isNewerVersion(v1: string, v2: string): boolean {
 async function replaceBinaryUnix(newBinaryPath: string, targetPath: string): Promise<void> {
   // Make executable
   await chmod(newBinaryPath, 0o755);
-  // Atomic rename (replaces existing)
-  await rename(newBinaryPath, targetPath);
+  // Atomic rename (replaces existing), with cross-device fallback
+  await crossDeviceRename(newBinaryPath, targetPath);
 }
 
 /**
@@ -92,8 +110,8 @@ async function replaceBinaryWindows(newBinaryPath: string, targetPath: string):
   await rename(targetPath, oldPath);
 
   try {
-    // Move new binary to target location
-    await rename(newBinaryPath, targetPath);
+    // Move new binary to target location (with cross-device fallback)
+    await crossDeviceRename(newBinaryPath, targetPath);
   } catch (e) {
     // Rollback: restore old binary
     await rename(oldPath, targetPath);
diff --git a/src/config/copilot-manual.ts b/src/config/copilot-manual.ts
index f6707d601b..7606457d41 100644
--- a/src/config/copilot-manual.ts
+++ b/src/config/copilot-manual.ts
@@ -38,6 +38,8 @@ export const defaultFsOps: FsOps = {
  * Load agents from a directory containing .md files.
  * Each markdown file should have frontmatter with agent configuration.
  *
+ * Files are loaded in parallel for better performance when spawning multiple sub-agents.
+ *
  * @param agentsDir - Path to directory containing agent .md files
  * @param source - Whether agents are 'local' (project) or 'global' (user)
  * @param fsOps - Optional fs operations for testing (defaults to Node.js fs/promises)
@@ -52,23 +54,21 @@ export async function loadAgentsFromDir(
     const files = await fsOps.readdir(agentsDir);
     const mdFiles = (files as string[]).filter((f) => f.endsWith(".md"));
 
-    const agents: CopilotAgent[] = [];
-
-    for (const file of mdFiles) {
-      try {
+    // Load all files in parallel
+    const agentResults = await Promise.allSettled(
+      mdFiles.map(async (file) => {
         const filePath = path.join(agentsDir, file);
         const content = await fsOps.readFile(filePath, "utf-8");
         const parsed = parseMarkdownFrontmatter(content as string);
 
         if (!parsed) {
           // No frontmatter, use file content as system prompt
-          agents.push({
+          return {
             name: file.replace(/\.md$/, ""),
             description: `Agent: ${file.replace(/\.md$/, "")}`,
             systemPrompt: (content as string).trim(),
             source,
-          });
-          continue;
+          };
         }
 
         const { frontmatter, body } = parsed;
@@ -86,30 +86,41 @@ export async function loadAgentsFromDir(
             ) as string[])
           : undefined;
 
-        agents.push({
+        return {
           name,
           description,
           tools,
           systemPrompt: body.trim(),
           source,
-        });
-      } catch {
-        // Skip files we can't read or parse
-        continue;
-      }
-    }
-
-    return agents;
+        };
+      })
+    );
+
+    // Filter out rejected promises and extract successful agents
+    return agentResults
+      .filter((result): result is PromiseFulfilledResult<CopilotAgent> => result.status === "fulfilled")
+      .map((result) => result.value);
   } catch {
     // Return empty array if directory doesn't exist or can't be read
     return [];
   }
 }
 
+/**
+ * Cache for loaded agents by project root.
+ * Key: projectRoot, Value: { agents, timestamp }
+ * Cache is invalidated after 5 seconds to allow for dynamic agent changes.
+ */
+const agentCache = new Map<string, { agents: CopilotAgent[]; timestamp: number }>();
+const CACHE_TTL_MS = 5000;
+
 /**
  * Load all Copilot agents from both local and global directories.
  * Local agents (project-specific) override global agents with the same name.
  *
+ * Results are cached per project root for 5 seconds to avoid redundant file system
+ * operations when spawning multiple parallel sub-agents.
+ *
  * @param projectRoot - Path to the project root directory
  * @param fsOps - Optional fs operations for testing (defaults to Node.js fs/promises)
  * @returns Array of CopilotAgent objects with local taking priority over global
@@ -118,6 +129,12 @@ export async function loadCopilotAgents(
   projectRoot: string,
   fsOps: FsOps = defaultFsOps
 ): Promise<CopilotAgent[]> {
+  // Check cache first
+  const cached = agentCache.get(projectRoot);
+  if (cached && (Date.now() - cached.timestamp) < CACHE_TTL_MS) {
+    return cached.agents;
+  }
+
   const HOME = os.homedir();
   const ATOMIC_HOME = path.join(HOME, ".atomic");
 
@@ -140,14 +157,24 @@ export async function loadCopilotAgents(
   // Map for deduplication - lowercase name as key for case-insensitive matching
   const agentMap = new Map<string, CopilotAgent>();
 
-  for (const { dir, source } of agentDirs) {
-    const agents = await loadAgentsFromDir(dir, source, fsOps);
+  // Load all directories in parallel instead of sequentially
+  const allAgentsArrays = await Promise.all(
+    agentDirs.map(({ dir, source }) => loadAgentsFromDir(dir, source, fsOps))
+  );
+
+  // Merge in priority order (later directories override earlier)
+  for (const agents of allAgentsArrays) {
     for (const agent of agents) {
       agentMap.set(agent.name.toLowerCase(), agent);
     }
   }
 
-  return Array.from(agentMap.values());
+  const agents = Array.from(agentMap.values());
+  
+  // Update cache
+  agentCache.set(projectRoot, { agents, timestamp: Date.now() });
+  
+  return agents;
 }
 
 /**
diff --git a/src/events/adapters/adapters.test.ts b/src/events/adapters/adapters.test.ts
new file mode 100644
index 0000000000..b5955508f9
--- /dev/null
+++ b/src/events/adapters/adapters.test.ts
@@ -0,0 +1,4598 @@
+// @ts-nocheck
+/**
+ * SDK Stream Adapter Tests
+ *
+ * Comprehensive unit tests for all three SDK stream adapters:
+ * - OpenCodeStreamAdapter (AsyncIterable + EventEmitter)
+ * - ClaudeStreamAdapter (AsyncIterable)
+ * - CopilotStreamAdapter (EventEmitter)
+ *
+ * Tests verify that each adapter correctly:
+ * 1. Maps SDK events to BusEvents
+ * 2. Publishes events to the event bus with correct runId
+ * 3. Handles text, tool, thinking, and error events
+ * 4. Supports cancellation via dispose()
+ * 5. Ignores unmapped/unknown event types
+ * 6. Publishes complete events at stream end
+ */
+
+import { describe, expect, test, beforeEach, mock } from "bun:test";
+import { EventBus } from "../event-bus.ts";
+import { OpenCodeStreamAdapter } from "./opencode-adapter.ts";
+import { ClaudeStreamAdapter } from "./claude-adapter.ts";
+import { CopilotStreamAdapter } from "./copilot-adapter.ts";
+import { WorkflowEventAdapter } from "./workflow-adapter.ts";
+import type { BusEvent } from "../bus-events.ts";
+import type {
+  Session,
+  AgentMessage,
+  AgentEvent,
+  EventType,
+  CodingAgentClient,
+} from "../../sdk/types.ts";
+
+// ============================================================================
+// Mock Utilities
+// ============================================================================
+
+/**
+ * Mock async generator for OpenCode/Claude streams
+ */
+async function* mockAsyncStream(
+  chunks: AgentMessage[],
+): AsyncGenerator<AgentMessage> {
+  for (const chunk of chunks) {
+    yield chunk;
+  }
+}
+
+/**
+ * Create a mock Session for testing
+ */
+function createMockSession(
+  stream: AsyncGenerator<AgentMessage>,
+  client?: Partial<CodingAgentClient>,
+): Session {
+  const session = {
+    id: "test-session-123",
+    stream: mock(() => stream),
+    __client: client,
+  } as unknown as Session;
+  return session;
+}
+
+/**
+ * Create a mock CodingAgentClient with EventEmitter-like behavior
+ */
+function createMockClient(): CodingAgentClient {
+  const handlers = new Map<EventType, Set<(event: AgentEvent) => void>>();
+
+  const client = {
+    on: mock((type: EventType, handler: (event: AgentEvent) => void) => {
+      let set = handlers.get(type);
+      if (!set) {
+        set = new Set();
+        handlers.set(type, set);
+      }
+      set.add(handler);
+      return () => {
+        set?.delete(handler);
+      };
+    }),
+    emit: (type: EventType, event: AgentEvent) => {
+      const set = handlers.get(type);
+      if (set) {
+        for (const handler of set) {
+          handler(event);
+        }
+      }
+    },
+  } as unknown as CodingAgentClient;
+
+  return client;
+}
+
+/**
+ * Helper to collect published events from the event bus
+ */
+function collectEvents(bus: EventBus): BusEvent[] {
+  const events: BusEvent[] = [];
+  bus.onAll((event) => {
+    events.push(event);
+  });
+  return events;
+}
+
+// ============================================================================
+// OpenCodeStreamAdapter Tests
+// ============================================================================
+
+describe("OpenCodeStreamAdapter", () => {
+  let bus: EventBus;
+  let adapter: OpenCodeStreamAdapter;
+
+  beforeEach(() => {
+    bus = new EventBus();
+    adapter = new OpenCodeStreamAdapter(bus, "test-session-123");
+  });
+
+  test("publishes text delta events from stream", async () => {
+    const events = collectEvents(bus);
+
+    const chunks: AgentMessage[] = [
+      { type: "text", content: "Hello " },
+      { type: "text", content: "world" },
+    ];
+
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream);
+
+    await adapter.startStreaming(session, "test message", {
+      runId: 42,
+      messageId: "msg-1",
+    });
+
+    // Should have session.start + 2 delta events + 1 complete event + 1 session.idle
+    expect(events.length).toBe(5);
+
+    const deltaEvents = events.filter((e) => e.type === "stream.text.delta");
+    expect(deltaEvents.length).toBe(2);
+    expect(deltaEvents[0].data.delta).toBe("Hello ");
+    expect(deltaEvents[0].data.messageId).toBe("msg-1");
+    expect(deltaEvents[0].runId).toBe(42);
+    expect(deltaEvents[1].data.delta).toBe("world");
+
+    const completeEvent = events.find((e) => e.type === "stream.text.complete");
+    expect(completeEvent).toBeDefined();
+    expect(completeEvent?.data.fullText).toBe("Hello world");
+    expect(completeEvent?.data.messageId).toBe("msg-1");
+    expect(completeEvent?.runId).toBe(42);
+
+    // OpenCode adapter always publishes session.idle after the for-await loop
+    const idleEvent = events.find((e) => e.type === "stream.session.idle");
+    expect(idleEvent).toBeDefined();
+    expect(idleEvent?.data.reason).toBe("generator-complete");
+  });
+
+  test("publishes tool start events from SDK client", async () => {
+    const events = collectEvents(bus);
+    const client = createMockClient();
+
+    const chunks: AgentMessage[] = [{ type: "text", content: "done" }];
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream, client);
+
+    // Start streaming in background
+    const streamPromise = adapter.startStreaming(session, "test message", {
+      runId: 42,
+      messageId: "msg-1",
+    });
+
+    // Emit tool.start event
+    client.emit("tool.start" as EventType, {
+      type: "tool.start",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        toolName: "bash",
+        toolInput: { command: "echo hello" },
+        toolUseId: "tool-123",
+      },
+    } as AgentEvent<"tool.start">);
+
+    await streamPromise;
+
+    const toolStartEvents = events.filter(
+      (e) => e.type === "stream.tool.start",
+    );
+    expect(toolStartEvents.length).toBe(1);
+    expect(toolStartEvents[0].data.toolName).toBe("bash");
+    expect(toolStartEvents[0].data.toolInput).toEqual({ command: "echo hello" });
+    expect(toolStartEvents[0].data.toolId).toBe("tool-123");
+    expect(toolStartEvents[0].data.sdkCorrelationId).toBe("tool-123");
+    expect(toolStartEvents[0].runId).toBe(42);
+  });
+
+  test("suppresses empty OpenCode task placeholders and deduplicates hydrated task starts", async () => {
+    const events = collectEvents(bus);
+    const client = createMockClient();
+
+    const chunks: AgentMessage[] = [{ type: "text", content: "done" }];
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream, client);
+
+    const streamPromise = adapter.startStreaming(session, "test message", {
+      runId: 42,
+      messageId: "msg-1",
+    });
+
+    client.emit("tool.start" as EventType, {
+      type: "tool.start",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        toolName: "task",
+        toolInput: {},
+        toolUseId: "task-tool-1",
+      },
+    } as AgentEvent<"tool.start">);
+
+    client.emit("tool.start" as EventType, {
+      type: "tool.start",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        toolName: "task",
+        toolInput: {
+          description: "Research TUI UX practices",
+          subagent_type: "codebase-online-researcher",
+        },
+        toolUseId: "task-tool-1",
+      },
+    } as AgentEvent<"tool.start">);
+
+    // Duplicate hydrated event (same tool ID + same payload) should be ignored.
+    client.emit("tool.start" as EventType, {
+      type: "tool.start",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        toolName: "task",
+        toolInput: {
+          description: "Research TUI UX practices",
+          subagent_type: "codebase-online-researcher",
+        },
+        toolUseId: "task-tool-1",
+      },
+    } as AgentEvent<"tool.start">);
+
+    await streamPromise;
+
+    const taskStartEvents = events.filter(
+      (e) => e.type === "stream.tool.start" && e.data.toolId === "task-tool-1",
+    );
+    expect(taskStartEvents.length).toBe(1);
+    expect(taskStartEvents[0].data.toolInput).toEqual({
+      description: "Research TUI UX practices",
+      subagent_type: "codebase-online-researcher",
+    });
+  });
+
+  test("publishes tool complete events from SDK client", async () => {
+    const events = collectEvents(bus);
+    const client = createMockClient();
+
+    const chunks: AgentMessage[] = [{ type: "text", content: "done" }];
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream, client);
+
+    const streamPromise = adapter.startStreaming(session, "test message", {
+      runId: 42,
+      messageId: "msg-1",
+    });
+
+    // Emit tool.complete event
+    client.emit("tool.complete" as EventType, {
+      type: "tool.complete",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        toolName: "bash",
+        toolResult: "hello",
+        success: true,
+        toolUseId: "tool-123",
+      },
+    } as AgentEvent<"tool.complete">);
+
+    await streamPromise;
+
+    const toolCompleteEvents = events.filter(
+      (e) => e.type === "stream.tool.complete",
+    );
+    expect(toolCompleteEvents.length).toBe(1);
+    expect(toolCompleteEvents[0].data.toolName).toBe("bash");
+    expect(toolCompleteEvents[0].data.toolResult).toBe("hello");
+    expect(toolCompleteEvents[0].data.success).toBe(true);
+    expect(toolCompleteEvents[0].data.toolId).toBe("tool-123");
+    expect(toolCompleteEvents[0].runId).toBe(42);
+  });
+
+  test("publishes synthetic stream.agent.complete when task tool completes without subagent.complete", async () => {
+    const events = collectEvents(bus);
+    const client = createMockClient();
+
+    const chunks: AgentMessage[] = [{ type: "text", content: "done" }];
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream, client);
+
+    const streamPromise = adapter.startStreaming(session, "test message", {
+      runId: 42,
+      messageId: "msg-opencode-synthetic-complete",
+    });
+
+    client.emit("tool.start" as EventType, {
+      type: "tool.start",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        toolName: "Task",
+        toolInput: {
+          description: "Locate TUI code",
+          subagent_type: "codebase-locator",
+        },
+        toolUseId: "task-tool-complete-1",
+      },
+    } as AgentEvent<"tool.start">);
+
+    client.emit("tool.complete" as EventType, {
+      type: "tool.complete",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        toolName: "Task",
+        toolUseId: "task-tool-complete-1",
+        toolResult: "Completed task output",
+        success: true,
+      },
+    } as AgentEvent<"tool.complete">);
+
+    await streamPromise;
+
+    const syntheticAgentId = "synthetic-task-agent:task-tool-complete-1";
+
+    const agentStartEvent = events.find(
+      (e) => e.type === "stream.agent.start" && e.data.agentId === syntheticAgentId,
+    );
+    expect(agentStartEvent).toBeDefined();
+
+    const agentCompleteEvents = events.filter(
+      (e) => e.type === "stream.agent.complete" && e.data.agentId === syntheticAgentId,
+    );
+    expect(agentCompleteEvents.length).toBe(1);
+    expect(agentCompleteEvents[0].data.success).toBe(true);
+    expect(agentCompleteEvents[0].data.result).toBe("Completed task output");
+
+    const toolCompleteIndex = events.findIndex(
+      (e) => e.type === "stream.tool.complete" && e.data.toolId === "task-tool-complete-1",
+    );
+    const agentCompleteIndex = events.findIndex(
+      (e) => e.type === "stream.agent.complete" && e.data.agentId === syntheticAgentId,
+    );
+    expect(toolCompleteIndex).toBeGreaterThan(-1);
+    expect(agentCompleteIndex).toBeGreaterThan(-1);
+    expect(toolCompleteIndex).toBeLessThan(agentCompleteIndex);
+  });
+
+  test("streams child-session tool events for registered subagents", async () => {
+    const events = collectEvents(bus);
+    const client = createMockClient();
+
+    const chunks: AgentMessage[] = [{ type: "text", content: "done" }];
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream, client);
+
+    const streamPromise = adapter.startStreaming(session, "test message", {
+      runId: 42,
+      messageId: "msg-1",
+    });
+
+    client.emit("subagent.start" as EventType, {
+      type: "subagent.start",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        subagentId: "agent-child-1",
+        subagentType: "general-purpose",
+        toolCallId: "task-tool-1",
+        subagentSessionId: "child-session-1",
+      },
+    } as AgentEvent<"subagent.start">);
+
+    client.emit("tool.start" as EventType, {
+      type: "tool.start",
+      sessionId: "child-session-1",
+      timestamp: Date.now(),
+      data: {
+        toolName: "bash",
+        toolInput: { command: "echo hello" },
+        toolUseId: "child-tool-1",
+      },
+    } as AgentEvent<"tool.start">);
+
+    client.emit("tool.complete" as EventType, {
+      type: "tool.complete",
+      sessionId: "child-session-1",
+      timestamp: Date.now(),
+      data: {
+        toolName: "bash",
+        toolResult: "ok",
+        success: true,
+        toolUseId: "child-tool-1",
+      },
+    } as AgentEvent<"tool.complete">);
+
+    await streamPromise;
+
+    const toolStart = events.find(
+      (e) => e.type === "stream.tool.start" && e.data.toolId === "child-tool-1",
+    );
+    expect(toolStart).toBeDefined();
+    expect(toolStart?.data.parentAgentId).toBe("agent-child-1");
+
+    const toolComplete = events.find(
+      (e) => e.type === "stream.tool.complete" && e.data.toolId === "child-tool-1",
+    );
+    expect(toolComplete).toBeDefined();
+    expect(toolComplete?.data.parentAgentId).toBe("agent-child-1");
+
+    const updates = events.filter(
+      (e) => e.type === "stream.agent.update" && e.data.agentId === "agent-child-1",
+    );
+    expect(updates.length).toBeGreaterThanOrEqual(2);
+    expect(updates.some((e) => e.data.currentTool === "bash" && e.data.toolUses === 1)).toBe(true);
+    expect(updates.some((e) => e.data.currentTool === undefined && e.data.toolUses === 1)).toBe(true);
+  });
+
+  test("attributes unknown child-session tool events to the sole active subagent", async () => {
+    const events = collectEvents(bus);
+    const client = createMockClient();
+
+    const chunks: AgentMessage[] = [{ type: "text", content: "done" }];
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream, client);
+
+    const streamPromise = adapter.startStreaming(session, "test message", {
+      runId: 42,
+      messageId: "msg-1",
+    });
+
+    client.emit("subagent.start" as EventType, {
+      type: "subagent.start",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        subagentId: "agent-only-1",
+        subagentType: "researcher",
+        task: "Investigate UI state",
+        toolCallId: "task-call-only-1",
+      },
+    } as AgentEvent<"subagent.start">);
+
+    // No subagentSessionId and unknown child session; adapter should still
+    // associate this with the sole active sub-agent.
+    client.emit("tool.start" as EventType, {
+      type: "tool.start",
+      sessionId: "child-session-unknown",
+      timestamp: Date.now(),
+      data: {
+        toolName: "WebSearch",
+        toolInput: { query: "tui patterns" },
+        toolUseId: "child-tool-unknown-1",
+      },
+    } as AgentEvent<"tool.start">);
+
+    await streamPromise;
+
+    const toolStart = events.find(
+      (e) => e.type === "stream.tool.start" && e.data.toolId === "child-tool-unknown-1",
+    );
+    expect(toolStart).toBeDefined();
+    expect(toolStart?.data.parentAgentId).toBe("agent-only-1");
+  });
+
+  test("accepts subagent.update from unknown child session when subagent is already known", async () => {
+    const events = collectEvents(bus);
+    const client = createMockClient();
+
+    const chunks: AgentMessage[] = [{ type: "text", content: "done" }];
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream, client);
+
+    const streamPromise = adapter.startStreaming(session, "test message", {
+      runId: 42,
+      messageId: "msg-subagent-update-child-session",
+    });
+
+    client.emit("subagent.start" as EventType, {
+      type: "subagent.start",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        subagentId: "agent-known-1",
+        subagentType: "codebase-locator",
+        toolCallId: "task-call-known-1",
+      },
+    } as AgentEvent<"subagent.start">);
+
+    client.emit("subagent.update" as EventType, {
+      type: "subagent.update",
+      sessionId: "child-session-unowned-1",
+      timestamp: Date.now(),
+      data: {
+        subagentId: "agent-known-1",
+        currentTool: "glob",
+        toolUses: 1,
+      },
+    } as AgentEvent<"subagent.update">);
+
+    await streamPromise;
+
+    expect(
+      events.some(
+        (e) => e.type === "stream.agent.update"
+          && e.data.agentId === "agent-known-1"
+          && e.data.currentTool === "glob"
+          && e.data.toolUses === 1,
+      ),
+    ).toBe(true);
+  });
+
+  test("attributes child-session tools to synthetic task agent when subagent.start is missing", async () => {
+    const events = collectEvents(bus);
+    const client = createMockClient();
+
+    const chunks: AgentMessage[] = [{ type: "text", content: "done" }];
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream, client);
+
+    const streamPromise = adapter.startStreaming(session, "test message", {
+      runId: 42,
+      messageId: "msg-1",
+    });
+
+    client.emit("tool.start" as EventType, {
+      type: "tool.start",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        toolName: "task",
+        toolInput: {
+          description: "Research TUI UX practices",
+          subagent_type: "codebase-online-researcher",
+        },
+        toolUseId: "task-tool-synth-1",
+      },
+    } as AgentEvent<"tool.start">);
+
+    client.emit("tool.start" as EventType, {
+      type: "tool.start",
+      sessionId: "child-session-unknown",
+      timestamp: Date.now(),
+      data: {
+        toolName: "WebSearch",
+        toolInput: { query: "tui patterns" },
+        toolUseId: "child-tool-synth-1",
+      },
+    } as AgentEvent<"tool.start">);
+
+    await streamPromise;
+
+    const childToolStart = events.find(
+      (e) => e.type === "stream.tool.start" && e.data.toolId === "child-tool-synth-1",
+    );
+    expect(childToolStart).toBeDefined();
+    expect(childToolStart?.data.parentAgentId).toBe("synthetic-task-agent:task-tool-synth-1");
+
+    const syntheticAgentUpdate = events.find(
+      (e) =>
+        e.type === "stream.agent.update"
+        && e.data.agentId === "synthetic-task-agent:task-tool-synth-1"
+        && e.data.currentTool === "WebSearch",
+    );
+    expect(syntheticAgentUpdate).toBeDefined();
+
+    const syntheticAgentStart = events.find(
+      (e) =>
+        e.type === "stream.agent.start"
+        && e.data.agentId === "synthetic-task-agent:task-tool-synth-1",
+    );
+    expect(syntheticAgentStart).toBeDefined();
+    expect(syntheticAgentStart?.data.task).toBe("Research TUI UX practices");
+    expect(syntheticAgentStart?.data.agentType).toBe("codebase-online-researcher");
+
+    const syntheticAgentStartIndex = events.findIndex(
+      (e) =>
+        e.type === "stream.agent.start"
+        && e.data.agentId === "synthetic-task-agent:task-tool-synth-1",
+    );
+    const syntheticAgentUpdateIndex = events.findIndex(
+      (e) =>
+        e.type === "stream.agent.update"
+        && e.data.agentId === "synthetic-task-agent:task-tool-synth-1",
+    );
+    expect(syntheticAgentStartIndex).toBeGreaterThan(-1);
+    expect(syntheticAgentUpdateIndex).toBeGreaterThan(syntheticAgentStartIndex);
+  });
+
+  test("attributes parallel child-session tools via task metadata session ids when subagent.start is missing", async () => {
+    const events = collectEvents(bus);
+    const client = createMockClient();
+
+    const chunks: AgentMessage[] = [{ type: "text", content: "done" }];
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream, client);
+
+    const streamPromise = adapter.startStreaming(session, "test message", {
+      runId: 42,
+      messageId: "msg-1",
+    });
+
+    client.emit("tool.start" as EventType, {
+      type: "tool.start",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        toolName: "task",
+        toolInput: {
+          description: "Locate TUI code",
+          subagent_type: "codebase-locator",
+        },
+        toolMetadata: {
+          sessionId: "child-session-a",
+        },
+        toolUseId: "task-tool-a",
+      },
+    } as AgentEvent<"tool.start">);
+
+    client.emit("tool.start" as EventType, {
+      type: "tool.start",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        toolName: "task",
+        toolInput: {
+          description: "Find UI patterns",
+          subagent_type: "codebase-pattern-finder",
+        },
+        toolMetadata: {
+          sessionId: "child-session-b",
+        },
+        toolUseId: "task-tool-b",
+      },
+    } as AgentEvent<"tool.start">);
+
+    client.emit("tool.start" as EventType, {
+      type: "tool.start",
+      sessionId: "child-session-a",
+      timestamp: Date.now(),
+      data: {
+        toolName: "Read",
+        toolInput: { filePath: "src/ui/chat.tsx" },
+        toolUseId: "child-tool-a",
+      },
+    } as AgentEvent<"tool.start">);
+
+    client.emit("tool.start" as EventType, {
+      type: "tool.start",
+      sessionId: "child-session-b",
+      timestamp: Date.now(),
+      data: {
+        toolName: "Glob",
+        toolInput: { path: "src/**/*.ts" },
+        toolUseId: "child-tool-b",
+      },
+    } as AgentEvent<"tool.start">);
+
+    await streamPromise;
+
+    const childToolA = events.find(
+      (e) => e.type === "stream.tool.start" && e.data.toolId === "child-tool-a",
+    );
+    const childToolB = events.find(
+      (e) => e.type === "stream.tool.start" && e.data.toolId === "child-tool-b",
+    );
+    expect(childToolA?.data.parentAgentId).toBe("synthetic-task-agent:task-tool-a");
+    expect(childToolB?.data.parentAgentId).toBe("synthetic-task-agent:task-tool-b");
+  });
+
+  test("emits synthetic task-agent progress updates from task tool lifecycle when child telemetry is missing", async () => {
+    const events = collectEvents(bus);
+    const client = createMockClient();
+
+    const chunks: AgentMessage[] = [{ type: "text", content: "done" }];
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream, client);
+
+    const streamPromise = adapter.startStreaming(session, "test message", {
+      runId: 42,
+      messageId: "msg-1",
+    });
+
+    client.emit("tool.start" as EventType, {
+      type: "tool.start",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        toolName: "task",
+        toolInput: {
+          description: "Locate TUI code",
+          subagent_type: "codebase-locator",
+        },
+        toolUseId: "task-tool-fallback-1",
+      },
+    } as AgentEvent<"tool.start">);
+
+    client.emit("tool.complete" as EventType, {
+      type: "tool.complete",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        toolName: "task",
+        toolResult: "done",
+        success: true,
+        toolUseId: "task-tool-fallback-1",
+      },
+    } as AgentEvent<"tool.complete">);
+
+    await streamPromise;
+
+    const syntheticAgentId = "synthetic-task-agent:task-tool-fallback-1";
+    const syntheticStart = events.find(
+      (e) => e.type === "stream.agent.start" && e.data.agentId === syntheticAgentId,
+    );
+    expect(syntheticStart).toBeDefined();
+
+    const runningUpdate = events.find(
+      (e) =>
+        e.type === "stream.agent.update"
+        && e.data.agentId === syntheticAgentId
+        && e.data.currentTool === "task"
+        && e.data.toolUses === 1,
+    );
+    expect(runningUpdate).toBeDefined();
+
+    const settledUpdate = events.find(
+      (e) =>
+        e.type === "stream.agent.update"
+        && e.data.agentId === syntheticAgentId
+        && e.data.currentTool === undefined
+        && e.data.toolUses === 1,
+    );
+    expect(settledUpdate).toBeDefined();
+  });
+
+  test("buffers early tool events before subagent.start and replays tool usage updates", async () => {
+    const events = collectEvents(bus);
+    const client = createMockClient();
+
+    const chunks: AgentMessage[] = [{ type: "text", content: "done" }];
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream, client);
+
+    const streamPromise = adapter.startStreaming(session, "test message", {
+      runId: 42,
+      messageId: "msg-1",
+    });
+
+    client.emit("tool.start" as EventType, {
+      type: "tool.start",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        toolName: "glob",
+        toolInput: { pattern: "**/*.ts" },
+        toolUseId: "early-tool-open-1",
+        parentId: "agent-early-open-1",
+      },
+    } as AgentEvent<"tool.start">);
+
+    client.emit("subagent.start" as EventType, {
+      type: "subagent.start",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        subagentId: "agent-early-open-1",
+        subagentType: "explore",
+        task: "Find TypeScript files",
+        toolCallId: "task-call-early-open-1",
+      },
+    } as AgentEvent<"subagent.start">);
+
+    await streamPromise;
+
+    const updates = events.filter(
+      (e) => e.type === "stream.agent.update" && e.data.agentId === "agent-early-open-1",
+    );
+    expect(updates.length).toBeGreaterThanOrEqual(1);
+    expect(updates.some((e) => e.data.currentTool === "glob" && e.data.toolUses === 1)).toBe(true);
+  });
+
+  test("does not double-count subagent tool usage for repeated tool.start lifecycle updates", async () => {
+    const events = collectEvents(bus);
+    const client = createMockClient();
+
+    const chunks: AgentMessage[] = [{ type: "text", content: "done" }];
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream, client);
+
+    const streamPromise = adapter.startStreaming(session, "test message", {
+      runId: 42,
+      messageId: "msg-1",
+    });
+
+    client.emit("subagent.start" as EventType, {
+      type: "subagent.start",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        subagentId: "agent-repeat-start-1",
+        subagentType: "debugger",
+        task: "Investigate repeated tool starts",
+        toolCallId: "task-repeat-start-1",
+      },
+    } as AgentEvent<"subagent.start">);
+
+    client.emit("tool.start" as EventType, {
+      type: "tool.start",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        toolName: "bash",
+        toolInput: { command: "echo pending", state: "pending" },
+        toolCallId: "inner-repeat-start-1",
+        parentId: "agent-repeat-start-1",
+      },
+    } as AgentEvent<"tool.start">);
+
+    client.emit("tool.start" as EventType, {
+      type: "tool.start",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        toolName: "bash",
+        toolInput: { command: "echo running", state: "running" },
+        toolCallId: "inner-repeat-start-1",
+        parentId: "agent-repeat-start-1",
+      },
+    } as AgentEvent<"tool.start">);
+
+    client.emit("tool.complete" as EventType, {
+      type: "tool.complete",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        toolName: "bash",
+        toolResult: "ok",
+        success: true,
+        toolCallId: "inner-repeat-start-1",
+        parentId: "agent-repeat-start-1",
+      },
+    } as AgentEvent<"tool.complete">);
+
+    client.emit("subagent.complete" as EventType, {
+      type: "subagent.complete",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        subagentId: "agent-repeat-start-1",
+        success: true,
+        result: "done",
+      },
+    } as AgentEvent<"subagent.complete">);
+
+    await streamPromise;
+
+    const toolStartEvents = events.filter(
+      (e) => e.type === "stream.tool.start" && e.data.toolId === "inner-repeat-start-1",
+    );
+    expect(toolStartEvents.length).toBe(2);
+
+    const agentUpdateEvents = events.filter(
+      (e) => e.type === "stream.agent.update" && e.data.agentId === "agent-repeat-start-1",
+    );
+    expect(
+      agentUpdateEvents.filter((e) => e.data.currentTool === "bash").length,
+    ).toBe(1);
+    expect(
+      agentUpdateEvents.some((e) => e.data.currentTool === undefined && e.data.toolUses === 1),
+    ).toBe(true);
+    expect(Math.max(...agentUpdateEvents.map((e) => e.data.toolUses ?? 0))).toBe(1);
+  });
+
+  test("publishes subagent progress updates on tool.partial_result", async () => {
+    const events = collectEvents(bus);
+    const client = createMockClient();
+
+    const chunks: AgentMessage[] = [{ type: "text", content: "done" }];
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream, client);
+
+    const streamPromise = adapter.startStreaming(session, "test message", {
+      runId: 42,
+      messageId: "msg-1",
+    });
+
+    client.emit("subagent.start" as EventType, {
+      type: "subagent.start",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        subagentId: "agent-partial-1",
+        subagentType: "debugger",
+        task: "Track live tool progress",
+        toolCallId: "task-partial-1",
+        subagentSessionId: "child-session-partial-1",
+      },
+    } as AgentEvent<"subagent.start">);
+
+    client.emit("tool.start" as EventType, {
+      type: "tool.start",
+      sessionId: "child-session-partial-1",
+      timestamp: Date.now(),
+      data: {
+        toolName: "bash",
+        toolInput: { command: "tail -f logs" },
+        toolCallId: "inner-partial-1",
+        parentId: "agent-partial-1",
+      },
+    } as AgentEvent<"tool.start">);
+
+    client.emit("tool.partial_result" as EventType, {
+      type: "tool.partial_result",
+      sessionId: "child-session-partial-1",
+      timestamp: Date.now(),
+      data: {
+        toolCallId: "inner-partial-1",
+        partialOutput: "line 1",
+      },
+    } as AgentEvent<"tool.partial_result">);
+
+    await streamPromise;
+
+    const progressUpdates = events.filter(
+      (e) =>
+        e.type === "stream.agent.update"
+        && e.data.agentId === "agent-partial-1"
+        && e.data.currentTool === "bash",
+    );
+    expect(progressUpdates.length).toBeGreaterThanOrEqual(2);
+    expect(progressUpdates.some((e) => e.data.toolUses === 1)).toBe(true);
+  });
+
+  test("publishes session truncation and compaction events from SDK client", async () => {
+    const events = collectEvents(bus);
+    const client = createMockClient();
+
+    const chunks: AgentMessage[] = [{ type: "text", content: "done" }];
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream, client);
+
+    const streamPromise = adapter.startStreaming(session, "test message", {
+      runId: 42,
+      messageId: "msg-1",
+    });
+
+    client.emit("session.truncation" as EventType, {
+      type: "session.truncation",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: { tokenLimit: 1000, tokensRemoved: 250, messagesRemoved: 3 },
+    } as AgentEvent<"session.truncation">);
+
+    client.emit("session.compaction" as EventType, {
+      type: "session.compaction",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: { phase: "complete", success: false, error: "summarize failed" },
+    } as AgentEvent<"session.compaction">);
+
+    await streamPromise;
+
+    const truncationEvent = events.find(
+      (event) => event.type === "stream.session.truncation",
+    );
+    expect(truncationEvent).toBeDefined();
+    expect(truncationEvent?.runId).toBe(42);
+    expect(truncationEvent?.data).toEqual({
+      tokenLimit: 1000,
+      tokensRemoved: 250,
+      messagesRemoved: 3,
+    });
+
+    const compactionEvent = events.find(
+      (event) => event.type === "stream.session.compaction",
+    );
+    expect(compactionEvent).toBeDefined();
+    expect(compactionEvent?.runId).toBe(42);
+    expect(compactionEvent?.data).toEqual({
+      phase: "complete",
+      success: false,
+      error: "summarize failed",
+    });
+  });
+
+  test("resolves sendAsync completionPromise immediately on external abort", async () => {
+    const events = collectEvents(bus);
+    const client = createMockClient();
+    const session = createMockSession(mockAsyncStream([]), client) as Session & {
+      sendAsync: ReturnType<typeof mock>;
+    };
+    session.sendAsync = mock(async () => {});
+
+    const externalAbort = new AbortController();
+    const streamPromise = adapter.startStreaming(session, "test message", {
+      runId: 42,
+      messageId: "msg-1",
+      abortSignal: externalAbort.signal,
+    });
+
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    externalAbort.abort();
+
+    const completion = await Promise.race([
+      streamPromise.then(() => "resolved"),
+      new Promise<string>((resolve) => setTimeout(() => resolve("timed-out"), 50)),
+    ]);
+
+    expect(completion).toBe("resolved");
+
+    const idleEvents = events.filter((e) => e.type === "stream.session.idle");
+    expect(idleEvents.length).toBe(1);
+    expect(idleEvents[0].data.reason).toBe("aborted");
+  });
+
+  test("publishes orphaned tool.complete before session.idle on aborted sendAsync runs", async () => {
+    const events = collectEvents(bus);
+    const client = createMockClient();
+    const session = createMockSession(mockAsyncStream([]), client) as Session & {
+      sendAsync: ReturnType<typeof mock>;
+    };
+    session.sendAsync = mock(async () => {
+      client.emit("tool.start" as EventType, {
+        type: "tool.start",
+        sessionId: "test-session-123",
+        timestamp: Date.now(),
+        data: {
+          toolName: "task",
+          toolInput: { description: "Research TUI UX practices" },
+          toolUseId: "tool-abort-order-1",
+        },
+      } as AgentEvent<"tool.start">);
+    });
+
+    const externalAbort = new AbortController();
+    const streamPromise = adapter.startStreaming(session, "test message", {
+      runId: 42,
+      messageId: "msg-1",
+      abortSignal: externalAbort.signal,
+    });
+
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    externalAbort.abort();
+    await streamPromise;
+
+    const completeIdx = events.findIndex(
+      (event) =>
+        event.type === "stream.tool.complete"
+        && event.data.toolId === "tool-abort-order-1"
+        && event.data.error === "Tool execution aborted",
+    );
+    const idleIdx = events.findIndex(
+      (event) =>
+        event.type === "stream.session.idle"
+        && event.data.reason === "aborted",
+    );
+
+    expect(completeIdx).toBeGreaterThan(-1);
+    expect(idleIdx).toBeGreaterThan(-1);
+    expect(completeIdx).toBeLessThan(idleIdx);
+  });
+
+  test("passes abortSignal to sendAsync and exits stalled dispatch on external abort", async () => {
+    const events = collectEvents(bus);
+    const client = createMockClient();
+    const session = createMockSession(mockAsyncStream([]), client) as Session & {
+      sendAsync: ReturnType<typeof mock>;
+    };
+    session.sendAsync = mock(
+      async (
+        _message: string,
+        options?: { agent?: string; abortSignal?: AbortSignal },
+      ) => {
+        await new Promise<void>((_resolve, reject) => {
+          if (options?.abortSignal?.aborted) {
+            reject(new DOMException("Aborted", "AbortError"));
+            return;
+          }
+          options?.abortSignal?.addEventListener(
+            "abort",
+            () => reject(new DOMException("Aborted", "AbortError")),
+            { once: true },
+          );
+        });
+      },
+    );
+
+    const externalAbort = new AbortController();
+    const streamPromise = adapter.startStreaming(session, "test message", {
+      runId: 42,
+      messageId: "msg-1",
+      abortSignal: externalAbort.signal,
+    });
+
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    externalAbort.abort();
+
+    const completion = await Promise.race([
+      streamPromise.then(() => "resolved"),
+      new Promise<string>((resolve) => setTimeout(() => resolve("timed-out"), 100)),
+    ]);
+
+    expect(completion).toBe("resolved");
+    expect(session.sendAsync).toHaveBeenCalledTimes(1);
+    expect(session.sendAsync.mock.calls[0][1]?.abortSignal).toBeDefined();
+
+    const idleEvents = events.filter((e) => e.type === "stream.session.idle");
+    expect(idleEvents.length).toBe(1);
+    expect(idleEvents[0].data.reason).toBe("aborted");
+
+    const errorEvents = events.filter((e) => e.type === "stream.session.error");
+    expect(errorEvents.length).toBe(0);
+  });
+
+  test("publishes session error on stream error", async () => {
+    const events = collectEvents(bus);
+
+    // Create a stream that throws an error
+    async function* errorStream(): AsyncGenerator<AgentMessage> {
+      yield { type: "text", content: "start" };
+      throw new Error("Stream error");
+    }
+
+    const session = createMockSession(errorStream());
+
+    await adapter.startStreaming(session, "test message", {
+      runId: 42,
+      messageId: "msg-1",
+    });
+
+    const errorEvents = events.filter(
+      (e) => e.type === "stream.session.error",
+    );
+    expect(errorEvents.length).toBe(1);
+    expect(errorEvents[0].data.error).toBe("Stream error");
+    expect(errorEvents[0].runId).toBe(42);
+  });
+
+  test("dispose() stops processing via AbortController", async () => {
+    const events = collectEvents(bus);
+
+    async function* controlledStream(): AsyncGenerator<AgentMessage> {
+      yield { type: "text", content: "chunk1" };
+      await new Promise((resolve) => setTimeout(resolve, 5));
+      yield { type: "text", content: "chunk2" };
+      await new Promise((resolve) => setTimeout(resolve, 5));
+      yield { type: "text", content: "chunk3" };
+    }
+
+    const session = createMockSession(controlledStream());
+
+    adapter.startStreaming(session, "test message", {
+      runId: 42,
+      messageId: "msg-1",
+    });
+
+    await new Promise((resolve) => setTimeout(resolve, 2));
+    adapter.dispose();
+    await new Promise((resolve) => setTimeout(resolve, 30));
+
+    const deltaEvents = events.filter((e) => e.type === "stream.text.delta");
+    expect(deltaEvents.length).toBeLessThanOrEqual(2);
+  });
+
+  test("events include correct runId from options", async () => {
+    const events = collectEvents(bus);
+
+    const chunks: AgentMessage[] = [{ type: "text", content: "test" }];
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream);
+
+    await adapter.startStreaming(session, "test message", {
+      runId: 999,
+      messageId: "msg-1",
+    });
+
+    // All events should have runId 999
+    expect(events.every((e) => e.runId === 999)).toBe(true);
+  });
+
+  test("publishes thinking delta events", async () => {
+    const events = collectEvents(bus);
+
+    const chunks: AgentMessage[] = [
+      {
+        type: "thinking",
+        content: "Let me think...",
+        metadata: { thinkingSourceKey: "block-1" },
+      },
+      {
+        type: "thinking",
+        content: "about this problem",
+        metadata: { thinkingSourceKey: "block-1" },
+      },
+      {
+        type: "thinking",
+        content: "",
+        metadata: {
+          thinkingSourceKey: "block-1",
+          streamingStats: { thinkingMs: 1234 },
+        },
+      },
+    ];
+
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream);
+
+    await adapter.startStreaming(session, "test message", {
+      runId: 42,
+      messageId: "msg-1",
+    });
+
+    const thinkingDeltaEvents = events.filter(
+      (e) => e.type === "stream.thinking.delta",
+    );
+    expect(thinkingDeltaEvents.length).toBe(2);
+    expect(thinkingDeltaEvents[0].data.delta).toBe("Let me think...");
+    expect(thinkingDeltaEvents[0].data.sourceKey).toBe("block-1");
+    expect(thinkingDeltaEvents[1].data.delta).toBe("about this problem");
+
+    const thinkingCompleteEvents = events.filter(
+      (e) => e.type === "stream.thinking.complete",
+    );
+    expect(thinkingCompleteEvents.length).toBe(1);
+    expect(thinkingCompleteEvents[0].data.sourceKey).toBe("block-1");
+    expect(thinkingCompleteEvents[0].data.durationMs).toBe(1234);
+  });
+
+  test("unmapped event types are ignored", async () => {
+    const events = collectEvents(bus);
+    const client = createMockClient();
+
+    const chunks: AgentMessage[] = [{ type: "text", content: "test" }];
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream, client);
+
+    const streamPromise = adapter.startStreaming(session, "test message", {
+      runId: 42,
+      messageId: "msg-1",
+    });
+
+    // Emit an unmapped event type
+    client.emit("unknown.event" as EventType, {
+      type: "unknown.event",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {},
+    } as AgentEvent);
+
+    await streamPromise;
+
+    // Should only have session.start, text delta, text complete, and session.idle events
+    expect(events.length).toBe(4);
+    expect(events.some((e) => e.type === "stream.text.delta")).toBe(true);
+    expect(events.some((e) => e.type === "stream.text.complete")).toBe(true);
+    expect(events.some((e) => e.type === "stream.session.idle")).toBe(true);
+  });
+
+  test("complete events are published at stream end", async () => {
+    const events = collectEvents(bus);
+
+    const chunks: AgentMessage[] = [
+      { type: "text", content: "Hello" },
+      { type: "text", content: " world" },
+    ];
+
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream);
+
+    await adapter.startStreaming(session, "test message", {
+      runId: 42,
+      messageId: "msg-1",
+    });
+
+    // Text complete event should precede the session.idle event
+    const completeIdx = events.findIndex((e) => e.type === "stream.text.complete");
+    const idleIdx = events.findIndex((e) => e.type === "stream.session.idle");
+    expect(completeIdx).toBeGreaterThan(-1);
+    expect(idleIdx).toBeGreaterThan(-1);
+    expect(completeIdx).toBeLessThan(idleIdx);
+
+    // Session.idle is always the final event
+    const lastEvent = events[events.length - 1];
+    expect(lastEvent.type).toBe("stream.session.idle");
+
+    // Text complete event should still contain the full text
+    const completeEvent = events.find((e) => e.type === "stream.text.complete");
+    expect(completeEvent?.data.fullText).toBe("Hello world");
+  });
+
+  test("strict runtime contract normalizes OpenCode subagent task metadata", async () => {
+    const events = collectEvents(bus);
+    const client = createMockClient();
+
+    const chunks: AgentMessage[] = [{ type: "text", content: "done" }];
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream, client);
+
+    const streamPromise = adapter.startStreaming(session, "test message", {
+      runId: 42,
+      messageId: "msg-1",
+      runtimeFeatureFlags: {
+        strictTaskContract: true,
+      },
+    });
+
+    client.emit("subagent.start" as EventType, {
+      type: "subagent.start",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        subagentId: "agent-oc-1",
+        subagentType: "explore",
+        task: "   ",
+        toolInput: {
+          description: "Inspect auth paths",
+          mode: "background",
+        },
+      },
+    } as AgentEvent<"subagent.start">);
+
+    await streamPromise;
+
+    const agentStartEvents = events.filter((e) => e.type === "stream.agent.start");
+    expect(agentStartEvents.length).toBe(1);
+    expect(agentStartEvents[0].data.task).toBe("Inspect auth paths");
+    expect(agentStartEvents[0].data.isBackground).toBe(true);
+  });
+
+  test("strict runtime contract keeps synthetic turn id stable in OpenCode", async () => {
+    const events = collectEvents(bus);
+    const client = createMockClient();
+
+    const chunks: AgentMessage[] = [{ type: "text", content: "done" }];
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream, client);
+
+    const streamPromise = adapter.startStreaming(session, "test message", {
+      runId: 42,
+      messageId: "msg-1",
+      runtimeFeatureFlags: {
+        strictTaskContract: true,
+      },
+    });
+
+    client.emit("turn.start" as EventType, {
+      type: "turn.start",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {},
+    } as AgentEvent<"turn.start">);
+
+    client.emit("turn.end" as EventType, {
+      type: "turn.end",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: { stop_reason: "tool_use" },
+    } as AgentEvent<"turn.end">);
+
+    await streamPromise;
+
+    const turnStartEvents = events.filter((e) => e.type === "stream.turn.start");
+    const turnEndEvents = events.filter((e) => e.type === "stream.turn.end");
+    expect(turnStartEvents.length).toBe(1);
+    expect(turnEndEvents.length).toBe(1);
+    expect(turnStartEvents[0].data.turnId).toMatch(/^turn_/);
+    expect(turnEndEvents[0].data.turnId).toBe(turnStartEvents[0].data.turnId);
+    expect(turnEndEvents[0].data.finishReason).toBe("tool-calls");
+    expect(turnEndEvents[0].data.rawFinishReason).toBe("tool_use");
+  });
+
+  test("maps reasoning events from SDK client to thinking events", async () => {
+    const events = collectEvents(bus);
+    const client = createMockClient();
+
+    const stream = mockAsyncStream([{ type: "text", content: "done" }]);
+    const session = createMockSession(stream, client);
+
+    const streamPromise = adapter.startStreaming(session, "test message", {
+      runId: 42,
+      messageId: "msg-1",
+    });
+
+    client.emit("reasoning.delta" as EventType, {
+      type: "reasoning.delta",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        reasoningId: "reasoning-1",
+        delta: "thinking...",
+      },
+    } as AgentEvent<"reasoning.delta">);
+
+    client.emit("reasoning.complete" as EventType, {
+      type: "reasoning.complete",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        reasoningId: "reasoning-1",
+        content: "done",
+      },
+    } as AgentEvent<"reasoning.complete">);
+
+    await streamPromise;
+
+    expect(events.some((e) => e.type === "stream.thinking.delta" && e.data.sourceKey === "reasoning-1")).toBe(true);
+    expect(events.some((e) => e.type === "stream.thinking.complete" && e.data.sourceKey === "reasoning-1")).toBe(true);
+  });
+
+  test("bridges callId-first subagent.start to later Task toolUseId and preserves a single canonical correlation", async () => {
+    const events = collectEvents(bus);
+    const client = createMockClient();
+
+    const stream = mockAsyncStream([{ type: "text", content: "done" }]);
+    const session = createMockSession(stream, client);
+
+    const streamPromise = adapter.startStreaming(session, "test message", {
+      runId: 42,
+      messageId: "msg-opencode-call-first",
+    });
+
+    client.emit("subagent.start" as EventType, {
+      type: "subagent.start",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        subagentId: "agent-call-first",
+        subagentType: "debugger",
+        task: "Sub-agent task",
+        toolCallId: "call-only-1",
+      },
+    } as AgentEvent<"subagent.start">);
+
+    client.emit("tool.start" as EventType, {
+      type: "tool.start",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        toolName: "Task",
+        toolInput: { description: "Investigate OpenCode parity" },
+        toolUseId: "tool-use-1",
+      },
+    } as AgentEvent<"tool.start">);
+
+    // Replay event from SDK with newly-populated subagentSessionId but missing call IDs.
+    client.emit("subagent.start" as EventType, {
+      type: "subagent.start",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        subagentId: "agent-call-first",
+        subagentType: "debugger",
+        task: "Sub-agent task",
+        subagentSessionId: "child-session-oc-1",
+      },
+    } as AgentEvent<"subagent.start">);
+
+    await streamPromise;
+
+    const toolStartEvents = events.filter((e) => e.type === "stream.tool.start");
+    expect(toolStartEvents.length).toBe(1);
+    expect(toolStartEvents[0].data.toolId).toBe("tool-use-1");
+    expect(toolStartEvents[0].data.sdkCorrelationId).toBe("tool-use-1");
+
+    const agentStartEvents = events.filter(
+      (e) => e.type === "stream.agent.start" && e.data.agentId === "agent-call-first",
+    );
+    expect(agentStartEvents.length).toBe(2);
+    expect(agentStartEvents[0].data.sdkCorrelationId).toBe("call-only-1");
+    expect(agentStartEvents[1].data.sdkCorrelationId).toBe("tool-use-1");
+    expect(agentStartEvents[1].data.task).toBe("Investigate OpenCode parity");
+  });
+
+  test("maps subagent.start callId-only events onto pending Task toolUseId metadata", async () => {
+    const events = collectEvents(bus);
+    const client = createMockClient();
+
+    const stream = mockAsyncStream([{ type: "text", content: "done" }]);
+    const session = createMockSession(stream, client);
+
+    const streamPromise = adapter.startStreaming(session, "test message", {
+      runId: 42,
+      messageId: "msg-opencode-pending-fallback",
+    });
+
+    client.emit("tool.start" as EventType, {
+      type: "tool.start",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        toolName: "Agent",
+        toolInput: { description: "Find orphaned sub-agent branches" },
+        toolUseId: "tool-use-task-2",
+      },
+    } as AgentEvent<"tool.start">);
+
+    client.emit("subagent.start" as EventType, {
+      type: "subagent.start",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        subagentId: "agent-pending-link",
+        subagentType: "explore",
+        task: "sub-agent task",
+        toolCallId: "call-only-2",
+      },
+    } as AgentEvent<"subagent.start">);
+
+    await streamPromise;
+
+    const agentStartEvents = events.filter(
+      (e) => e.type === "stream.agent.start" && e.data.agentId === "agent-pending-link",
+    );
+    expect(agentStartEvents.length).toBe(1);
+    expect(agentStartEvents[0].data.sdkCorrelationId).toBe("tool-use-task-2");
+    expect(agentStartEvents[0].data.task).toBe("Find orphaned sub-agent branches");
+  });
+});
+
+// ============================================================================
+// ClaudeStreamAdapter Tests
+// ============================================================================
+
+describe("ClaudeStreamAdapter", () => {
+  let bus: EventBus;
+  let adapter: ClaudeStreamAdapter;
+
+  beforeEach(() => {
+    bus = new EventBus();
+    adapter = new ClaudeStreamAdapter(bus, "test-session-123");
+  });
+
+  test("publishes text delta events from mock stream", async () => {
+    const events = collectEvents(bus);
+
+    const chunks: AgentMessage[] = [
+      { type: "text", content: "Hello " },
+      { type: "text", content: "Claude" },
+    ];
+
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream);
+
+    await adapter.startStreaming(session, "test message", {
+      runId: 100,
+      messageId: "msg-2",
+    });
+
+    // Should have session.start + 2 delta events + 1 complete event
+    expect(events.length).toBe(4);
+
+    const deltaEvents = events.filter((e) => e.type === "stream.text.delta");
+    expect(deltaEvents.length).toBe(2);
+    expect(deltaEvents[0].data.delta).toBe("Hello ");
+    expect(deltaEvents[0].data.messageId).toBe("msg-2");
+    expect(deltaEvents[0].runId).toBe(100);
+    expect(deltaEvents[1].data.delta).toBe("Claude");
+
+    const completeEvent = events.find((e) => e.type === "stream.text.complete");
+    expect(completeEvent).toBeDefined();
+    expect(completeEvent?.data.fullText).toBe("Hello Claude");
+    expect(completeEvent?.runId).toBe(100);
+  });
+
+  test("publishes thinking delta and complete events", async () => {
+    const events = collectEvents(bus);
+
+    const chunks: AgentMessage[] = [
+      {
+        type: "thinking",
+        content: "Reasoning step 1",
+        metadata: { thinkingSourceKey: "reasoning-1" },
+      },
+      {
+        type: "thinking",
+        content: "Reasoning step 2",
+        metadata: { thinkingSourceKey: "reasoning-1" },
+      },
+      {
+        type: "thinking",
+        content: "",
+        metadata: {
+          thinkingSourceKey: "reasoning-1",
+          streamingStats: { thinkingMs: 500 },
+        },
+      },
+    ];
+
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream);
+
+    await adapter.startStreaming(session, "test message", {
+      runId: 100,
+      messageId: "msg-2",
+    });
+
+    const thinkingDeltaEvents = events.filter(
+      (e) => e.type === "stream.thinking.delta",
+    );
+    expect(thinkingDeltaEvents.length).toBe(2);
+    expect(thinkingDeltaEvents[0].data.delta).toBe("Reasoning step 1");
+    expect(thinkingDeltaEvents[0].data.sourceKey).toBe("reasoning-1");
+    expect(thinkingDeltaEvents[1].data.delta).toBe("Reasoning step 2");
+
+    const thinkingCompleteEvents = events.filter(
+      (e) => e.type === "stream.thinking.complete",
+    );
+    expect(thinkingCompleteEvents.length).toBe(1);
+    expect(thinkingCompleteEvents[0].data.sourceKey).toBe("reasoning-1");
+    expect(thinkingCompleteEvents[0].data.durationMs).toBe(500);
+  });
+
+  test("publishes session idle events from SDK client", async () => {
+    const events = collectEvents(bus);
+    const client = createMockClient();
+
+    const chunks: AgentMessage[] = [{ type: "text", content: "done" }];
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream, client);
+
+    const streamPromise = adapter.startStreaming(session, "test message", {
+      runId: 100,
+      messageId: "msg-2",
+    });
+
+    // Ignore events from other sessions.
+    client.emit("session.idle" as EventType, {
+      type: "session.idle",
+      sessionId: "other-session",
+      timestamp: Date.now(),
+      data: { reason: "ignored" },
+    } as AgentEvent<"session.idle">);
+
+    client.emit("session.idle" as EventType, {
+      type: "session.idle",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: { reason: "completed" },
+    } as AgentEvent<"session.idle">);
+
+    await streamPromise;
+
+    const idleEvents = events.filter((e) => e.type === "stream.session.idle");
+    expect(idleEvents.length).toBe(1);
+    expect(idleEvents[0].data.reason).toBe("completed");
+    expect(idleEvents[0].runId).toBe(100);
+  });
+
+  test("publishes session error on stream error", async () => {
+    const events = collectEvents(bus);
+
+    async function* errorStream(): AsyncGenerator<AgentMessage> {
+      yield { type: "text", content: "start" };
+      throw new Error("Claude API error");
+    }
+
+    const session = createMockSession(errorStream());
+
+    await adapter.startStreaming(session, "test message", {
+      runId: 100,
+      messageId: "msg-2",
+    });
+
+    const errorEvents = events.filter(
+      (e) => e.type === "stream.session.error",
+    );
+    expect(errorEvents.length).toBe(1);
+    expect(errorEvents[0].data.error).toBe("Claude API error");
+    expect(errorEvents[0].runId).toBe(100);
+  });
+
+  test("ignores malformed session.error events with no message or code", async () => {
+    const events = collectEvents(bus);
+    const client = createMockClient();
+
+    const stream = mockAsyncStream([{ type: "text", content: "done" }]);
+    const session = createMockSession(stream, client);
+
+    const streamPromise = adapter.startStreaming(session, "test message", {
+      runId: 100,
+      messageId: "msg-2",
+    });
+
+    client.emit("session.error" as EventType, {
+      type: "session.error",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {},
+    } as AgentEvent<"session.error">);
+
+    await streamPromise;
+
+    const errorEvents = events.filter((e) => e.type === "stream.session.error");
+    expect(errorEvents.length).toBe(0);
+  });
+
+  test("dispose() stops processing via AbortController", async () => {
+    const events = collectEvents(bus);
+
+    async function* controlledStream(): AsyncGenerator<AgentMessage> {
+      yield { type: "text", content: "chunk1" };
+      await new Promise((resolve) => setTimeout(resolve, 5));
+      yield { type: "text", content: "chunk2" };
+      await new Promise((resolve) => setTimeout(resolve, 5));
+      yield { type: "text", content: "chunk3" };
+    }
+
+    const session = createMockSession(controlledStream());
+
+    adapter.startStreaming(session, "test message", {
+      runId: 100,
+      messageId: "msg-2",
+    });
+
+    await new Promise((resolve) => setTimeout(resolve, 2));
+    adapter.dispose();
+    await new Promise((resolve) => setTimeout(resolve, 30));
+
+    const deltaEvents = events.filter((e) => e.type === "stream.text.delta");
+    expect(deltaEvents.length).toBeLessThanOrEqual(2);
+  });
+
+  test("events include correct runId from options", async () => {
+    const events = collectEvents(bus);
+
+    const chunks: AgentMessage[] = [{ type: "text", content: "test" }];
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream);
+
+    await adapter.startStreaming(session, "test message", {
+      runId: 777,
+      messageId: "msg-2",
+    });
+
+    // All events should have runId 777
+    expect(events.every((e) => e.runId === 777)).toBe(true);
+  });
+
+  test("unmapped event types are ignored (stream only has text/thinking)", async () => {
+    const events = collectEvents(bus);
+
+    const chunks: AgentMessage[] = [
+      { type: "text", content: "test" },
+      // Unknown types are ignored by the adapter
+      { type: "unknown" as any, content: "ignored" },
+    ];
+
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream);
+
+    await adapter.startStreaming(session, "test message", {
+      runId: 100,
+      messageId: "msg-2",
+    });
+
+    // Should only have session.start, text delta, and text complete events
+    expect(events.length).toBe(3);
+    expect(events.some((e) => e.type === "stream.text.delta")).toBe(true);
+    expect(events.some((e) => e.type === "stream.text.complete")).toBe(true);
+  });
+
+  test("complete events are published at stream end", async () => {
+    const events = collectEvents(bus);
+
+    const chunks: AgentMessage[] = [
+      { type: "text", content: "First" },
+      { type: "text", content: " Second" },
+    ];
+
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream);
+
+    await adapter.startStreaming(session, "test message", {
+      runId: 100,
+      messageId: "msg-2",
+    });
+
+    // Complete event should be the last event
+    const lastEvent = events[events.length - 1];
+    expect(lastEvent.type).toBe("stream.text.complete");
+    expect(lastEvent.data.fullText).toBe("First Second");
+  });
+
+  test("publishes tool start events from stream (tool_use)", async () => {
+    const events = collectEvents(bus);
+
+    const chunks: AgentMessage[] = [
+      {
+        type: "tool_use" as any,
+        content: "",
+        id: "tool-abc",
+        name: "bash",
+        input: { command: "ls" },
+      } as any,
+      { type: "text", content: "done" },
+    ];
+
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream);
+
+    await adapter.startStreaming(session, "test", {
+      runId: 100,
+      messageId: "msg-2",
+    });
+
+    const toolStartEvents = events.filter((e) => e.type === "stream.tool.start");
+    expect(toolStartEvents.length).toBe(1);
+    expect(toolStartEvents[0].data.toolName).toBe("bash");
+    expect(toolStartEvents[0].data.toolId).toBe("tool-abc");
+    expect(toolStartEvents[0].data.toolInput).toEqual({ command: "ls" });
+    expect(toolStartEvents[0].runId).toBe(100);
+  });
+
+  test("publishes tool complete events from stream (tool_result)", async () => {
+    const events = collectEvents(bus);
+
+    const chunks: AgentMessage[] = [
+      {
+        type: "tool_result" as any,
+        content: "file1.txt\nfile2.txt",
+        tool_use_id: "tool-abc",
+        toolName: "bash",
+        is_error: false,
+      } as any,
+      { type: "text", content: "done" },
+    ];
+
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream);
+
+    await adapter.startStreaming(session, "test", {
+      runId: 100,
+      messageId: "msg-2",
+    });
+
+    const toolCompleteEvents = events.filter((e) => e.type === "stream.tool.complete");
+    expect(toolCompleteEvents.length).toBe(1);
+    expect(toolCompleteEvents[0].data.toolName).toBe("bash");
+    expect(toolCompleteEvents[0].data.toolId).toBe("tool-abc");
+    expect(toolCompleteEvents[0].data.toolResult).toBe("file1.txt\nfile2.txt");
+    expect(toolCompleteEvents[0].data.success).toBe(true);
+    expect(toolCompleteEvents[0].runId).toBe(100);
+  });
+
+  test("prefers client hook tool events over stream chunk tool events to avoid duplicate unscoped tools", async () => {
+    const events = collectEvents(bus);
+    const client = createMockClient();
+
+    const chunks: AgentMessage[] = [
+      {
+        type: "tool_use",
+        content: {
+          name: "WebSearch",
+          input: { query: "query" },
+          toolUseId: "tool-dup-1",
+        },
+      } as unknown as AgentMessage,
+      {
+        type: "tool_result",
+        content: "ok",
+        tool_use_id: "tool-dup-1",
+        toolName: "WebSearch",
+      } as unknown as AgentMessage,
+      { type: "text", content: "done" },
+    ];
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream, client);
+
+    const streamPromise = adapter.startStreaming(session, "test message", {
+      runId: 100,
+      messageId: "msg-2",
+    });
+
+    client.emit("tool.start" as EventType, {
+      type: "tool.start",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        toolName: "WebSearch",
+        toolInput: { query: "query" },
+        toolUseId: "tool-dup-1",
+        parentAgentId: "agent-1",
+      },
+    } as AgentEvent<"tool.start">);
+
+    client.emit("tool.complete" as EventType, {
+      type: "tool.complete",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        toolName: "WebSearch",
+        toolUseId: "tool-dup-1",
+        toolResult: "ok",
+        success: true,
+        parentAgentId: "agent-1",
+      },
+    } as AgentEvent<"tool.complete">);
+
+    await streamPromise;
+
+    const toolStartEvents = events.filter((e) => e.type === "stream.tool.start" && e.data.toolId === "tool-dup-1");
+    expect(toolStartEvents.length).toBe(1);
+    expect(toolStartEvents[0].data.parentAgentId).toBe("agent-1");
+
+    const toolCompleteEvents = events.filter((e) => e.type === "stream.tool.complete" && e.data.toolId === "tool-dup-1");
+    expect(toolCompleteEvents.length).toBe(1);
+    expect(toolCompleteEvents[0].data.parentAgentId).toBe("agent-1");
+  });
+
+  test("publishes agent start events from subagent.start hook", async () => {
+    const events = collectEvents(bus);
+    const client = createMockClient();
+
+    const chunks: AgentMessage[] = [{ type: "text", content: "done" }];
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream, client);
+
+    const streamPromise = adapter.startStreaming(session, "test", {
+      runId: 100,
+      messageId: "msg-2",
+    });
+
+    // Simulate subagent.start hook event from the SDK
+    client.emit("subagent.start" as EventType, {
+      type: "subagent.start",
+      sessionId: "test-session-123",
+      timestamp: new Date().toISOString(),
+      data: {
+        subagentId: "agent-001",
+        subagentType: "explore",
+        task: "Find files",
+        toolUseID: "tool_use_123",
+      },
+    } as AgentEvent);
+
+    await streamPromise;
+
+    const agentStartEvents = events.filter((e) => e.type === "stream.agent.start");
+    expect(agentStartEvents.length).toBe(1);
+    expect(agentStartEvents[0].data.agentId).toBe("agent-001");
+    expect(agentStartEvents[0].data.agentType).toBe("explore");
+    expect(agentStartEvents[0].data.task).toBe("Find files");
+    expect(agentStartEvents[0].data.sdkCorrelationId).toBe("tool_use_123");
+    expect(agentStartEvents[0].runId).toBe(100);
+  });
+
+  test("publishes subagent progress updates on tool.partial_result", async () => {
+    const events = collectEvents(bus);
+    const client = createMockClient();
+
+    const chunks: AgentMessage[] = [{ type: "text", content: "done" }];
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream, client);
+
+    const streamPromise = adapter.startStreaming(session, "test", {
+      runId: 100,
+      messageId: "msg-2",
+    });
+
+    client.emit("subagent.start" as EventType, {
+      type: "subagent.start",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        subagentId: "agent-partial-claude-1",
+        subagentType: "explore",
+        task: "Watch streaming tool output",
+        toolUseID: "tool-use-parent-claude-1",
+      },
+    } as AgentEvent<"subagent.start">);
+
+    client.emit("tool.start" as EventType, {
+      type: "tool.start",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        toolName: "bash",
+        toolInput: { command: "tail -f logs" },
+        toolCallId: "inner-partial-claude-1",
+        parentId: "agent-partial-claude-1",
+      },
+    } as AgentEvent<"tool.start">);
+
+    client.emit("tool.partial_result" as EventType, {
+      type: "tool.partial_result",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        toolCallId: "inner-partial-claude-1",
+        partialOutput: "line 1",
+      },
+    } as AgentEvent<"tool.partial_result">);
+
+    await streamPromise;
+
+    const progressUpdates = events.filter(
+      (e) =>
+        e.type === "stream.agent.update"
+        && e.data.agentId === "agent-partial-claude-1"
+        && e.data.currentTool === "bash",
+    );
+    expect(progressUpdates.length).toBeGreaterThanOrEqual(2);
+    expect(progressUpdates.some((e) => e.data.toolUses === 1)).toBe(true);
+  });
+
+  test("accepts child-session tool events when parentAgent correlation is present", async () => {
+    const events = collectEvents(bus);
+    const client = createMockClient();
+
+    const chunks: AgentMessage[] = [{ type: "text", content: "done" }];
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream, client);
+
+    const streamPromise = adapter.startStreaming(session, "test", {
+      runId: 100,
+      messageId: "msg-2",
+    });
+
+    client.emit("subagent.start" as EventType, {
+      type: "subagent.start",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        subagentId: "agent-child-session-1",
+        subagentType: "debugger",
+        task: "Investigate child session event routing",
+        toolUseID: "tool-use-child-parent-1",
+      },
+    } as AgentEvent<"subagent.start">);
+
+    client.emit("tool.start" as EventType, {
+      type: "tool.start",
+      sessionId: "child-session-1",
+      timestamp: Date.now(),
+      data: {
+        toolName: "bash",
+        toolInput: { command: "echo ok" },
+        toolCallId: "child-tool-1",
+        parentId: "agent-child-session-1",
+      },
+    } as AgentEvent<"tool.start">);
+
+    await streamPromise;
+
+    const toolStart = events.find(
+      (e) => e.type === "stream.tool.start" && e.data.toolId === "child-tool-1",
+    );
+    expect(toolStart).toBeDefined();
+    expect(toolStart?.data.parentAgentId).toBe("agent-child-session-1");
+
+    const progressUpdates = events.filter(
+      (e) =>
+        e.type === "stream.agent.update"
+        && e.data.agentId === "agent-child-session-1"
+        && e.data.currentTool === "bash"
+        && e.data.toolUses === 1,
+    );
+    expect(progressUpdates.length).toBeGreaterThanOrEqual(1);
+  });
+
+  test("routes nested child-session tool and streaming updates to the correct subagent", async () => {
+    const events = collectEvents(bus);
+    const client = createMockClient();
+
+    const chunks: AgentMessage[] = [{ type: "text", content: "done" }];
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream, client);
+
+    const streamPromise = adapter.startStreaming(session, "spawn nested researchers", {
+      runId: 100,
+      messageId: "msg-nested-child-session",
+      agent: "codebase-online-researcher",
+    });
+
+    client.emit("tool.start" as EventType, {
+      type: "tool.start",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        toolName: "Agent",
+        toolInput: { description: "child A" },
+        toolUseId: "task-tool-a",
+      },
+    } as AgentEvent<"tool.start">);
+
+    client.emit("tool.start" as EventType, {
+      type: "tool.start",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        toolName: "Agent",
+        toolInput: { description: "child B" },
+        toolUseId: "task-tool-b",
+      },
+    } as AgentEvent<"tool.start">);
+
+    client.emit("tool.start" as EventType, {
+      type: "tool.start",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        toolName: "Agent",
+        toolInput: { description: "child C" },
+        toolUseId: "task-tool-c",
+      },
+    } as AgentEvent<"tool.start">);
+
+    client.emit("subagent.start" as EventType, {
+      type: "subagent.start",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        subagentId: "agent-child-a",
+        subagentType: "researcher",
+        task: "child A",
+        toolCallId: "task-tool-a",
+        subagentSessionId: "child-session-a",
+      },
+    } as AgentEvent<"subagent.start">);
+
+    client.emit("subagent.start" as EventType, {
+      type: "subagent.start",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        subagentId: "agent-child-b",
+        subagentType: "researcher",
+        task: "child B",
+        toolCallId: "task-tool-b",
+        subagentSessionId: "child-session-b",
+      },
+    } as AgentEvent<"subagent.start">);
+
+    client.emit("subagent.start" as EventType, {
+      type: "subagent.start",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        subagentId: "agent-child-c",
+        subagentType: "researcher",
+        task: "child C",
+        toolCallId: "task-tool-c",
+        subagentSessionId: "child-session-c",
+      },
+    } as AgentEvent<"subagent.start">);
+
+    // Nested child stream: no direct parent metadata, only child session identity.
+    client.emit("tool.start" as EventType, {
+      type: "tool.start",
+      sessionId: "child-session-b",
+      timestamp: Date.now(),
+      data: {
+        toolName: "WebSearch",
+        toolInput: { query: "nested subagent tree" },
+        toolUseId: "child-b-tool-1",
+      },
+    } as AgentEvent<"tool.start">);
+
+    client.emit("tool.partial_result" as EventType, {
+      type: "tool.partial_result",
+      sessionId: "child-session-b",
+      timestamp: Date.now(),
+      data: {
+        toolCallId: "child-b-tool-1",
+        partialOutput: "streaming...",
+      },
+    } as AgentEvent<"tool.partial_result">);
+
+    client.emit("tool.complete" as EventType, {
+      type: "tool.complete",
+      sessionId: "child-session-b",
+      timestamp: Date.now(),
+      data: {
+        toolName: "WebSearch",
+        toolUseId: "child-b-tool-1",
+        toolResult: { ok: true },
+        success: true,
+      },
+    } as AgentEvent<"tool.complete">);
+
+    await streamPromise;
+
+    const nestedToolStart = events.find(
+      (e) => e.type === "stream.tool.start" && e.data.toolId === "child-b-tool-1",
+    );
+    expect(nestedToolStart).toBeDefined();
+    expect(nestedToolStart?.data.parentAgentId).toBe("agent-child-b");
+
+    const nestedPartial = events.find(
+      (e) => e.type === "stream.tool.partial_result" && e.data.toolCallId === "child-b-tool-1",
+    );
+    expect(nestedPartial).toBeDefined();
+    expect(nestedPartial?.data.parentAgentId).toBe("agent-child-b");
+
+    const nestedToolComplete = events.find(
+      (e) => e.type === "stream.tool.complete" && e.data.toolId === "child-b-tool-1",
+    );
+    expect(nestedToolComplete).toBeDefined();
+    expect(nestedToolComplete?.data.parentAgentId).toBe("agent-child-b");
+
+    const nestedUpdates = events.filter(
+      (e) => e.type === "stream.agent.update" && e.data.agentId === "agent-child-b",
+    );
+    expect(nestedUpdates.some((e) => e.data.currentTool === "WebSearch" && e.data.toolUses === 1)).toBe(true);
+    expect(nestedUpdates.some((e) => e.data.currentTool === undefined && e.data.toolUses === 1)).toBe(true);
+  });
+
+  test("attributes unscoped main-session tool events to the sole active subagent", async () => {
+    const events = collectEvents(bus);
+    const client = createMockClient();
+
+    const chunks: AgentMessage[] = [{ type: "text", content: "done" }];
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream, client);
+
+    const streamPromise = adapter.startStreaming(session, "test", {
+      runId: 100,
+      messageId: "msg-2",
+    });
+
+    client.emit("subagent.start" as EventType, {
+      type: "subagent.start",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        subagentId: "agent-unscoped-1",
+        subagentType: "Explore",
+        task: "Explore repository",
+        toolUseID: "tool-parent-unscoped-1",
+      },
+    } as AgentEvent<"subagent.start">);
+
+    // Mirrors the failing log pattern: tool events on the parent session with
+    // no parentId/parentToolUseId metadata.
+    client.emit("tool.start" as EventType, {
+      type: "tool.start",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        toolName: "Bash",
+        toolInput: { command: "ls -la" },
+        toolUseId: "tool-unscoped-1",
+      },
+    } as AgentEvent<"tool.start">);
+
+    await streamPromise;
+
+    const toolStart = events.find(
+      (e) => e.type === "stream.tool.start" && e.data.toolId === "tool-unscoped-1",
+    );
+    expect(toolStart).toBeDefined();
+    expect(toolStart?.data.parentAgentId).toBe("agent-unscoped-1");
+
+    const progressUpdates = events.filter(
+      (e) =>
+        e.type === "stream.agent.update"
+        && e.data.agentId === "agent-unscoped-1"
+        && e.data.currentTool === "Bash"
+        && e.data.toolUses === 1,
+    );
+    expect(progressUpdates.length).toBeGreaterThanOrEqual(1);
+  });
+
+  test("attributes parallel unscoped tool events via TaskOutput task_id and active tool context", async () => {
+    const events = collectEvents(bus);
+    const client = createMockClient();
+
+    const chunks: AgentMessage[] = [{ type: "text", content: "done" }];
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream, client);
+
+    const streamPromise = adapter.startStreaming(session, "test", {
+      runId: 101,
+      messageId: "msg-parallel-taskoutput",
+    });
+
+    client.emit("subagent.start" as EventType, {
+      type: "subagent.start",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        subagentId: "agent-parallel-a",
+        subagentType: "research",
+        task: "Research A",
+        toolUseID: "task-tool-a",
+      },
+    } as AgentEvent<"subagent.start">);
+
+    client.emit("subagent.start" as EventType, {
+      type: "subagent.start",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        subagentId: "agent-parallel-b",
+        subagentType: "research",
+        task: "Research B",
+        toolUseID: "task-tool-b",
+      },
+    } as AgentEvent<"subagent.start">);
+
+    // SDK can omit parent metadata in parallel mode; TaskOutput carries task_id.
+    client.emit("tool.start" as EventType, {
+      type: "tool.start",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        toolName: "TaskOutput",
+        toolUseId: "task-output-1",
+        toolInput: { task_id: "agent-parallel-a", block: true },
+      },
+    } as AgentEvent<"tool.start">);
+
+    // Follow-up tools may also be unscoped; attribute using active sub-agent tool context.
+    client.emit("tool.start" as EventType, {
+      type: "tool.start",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        toolName: "WebSearch",
+        toolUseId: "websearch-1",
+        toolInput: { query: "parallel attribution fallback" },
+      },
+    } as AgentEvent<"tool.start">);
+
+    client.emit("tool.complete" as EventType, {
+      type: "tool.complete",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        toolName: "WebSearch",
+        toolUseId: "websearch-1",
+        toolResult: "ok",
+        success: true,
+      },
+    } as AgentEvent<"tool.complete">);
+
+    await streamPromise;
+
+    const taskOutputStart = events.find(
+      (e) => e.type === "stream.tool.start" && e.data.toolId === "task-output-1",
+    );
+    expect(taskOutputStart).toBeDefined();
+    expect(taskOutputStart?.data.parentAgentId).toBe("agent-parallel-a");
+
+    const webSearchStart = events.find(
+      (e) => e.type === "stream.tool.start" && e.data.toolId === "websearch-1",
+    );
+    expect(webSearchStart).toBeDefined();
+    expect(webSearchStart?.data.parentAgentId).toBe("agent-parallel-a");
+
+    const webSearchComplete = events.find(
+      (e) => e.type === "stream.tool.complete" && e.data.toolId === "websearch-1",
+    );
+    expect(webSearchComplete).toBeDefined();
+    expect(webSearchComplete?.data.parentAgentId).toBe("agent-parallel-a");
+  });
+
+  test("attributes pre-TaskOutput unscoped tools to active background subagent fallback", async () => {
+    const events = collectEvents(bus);
+    const client = createMockClient();
+
+    const chunks: AgentMessage[] = [{ type: "text", content: "done" }];
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream, client);
+
+    const streamPromise = adapter.startStreaming(session, "test", {
+      runId: 102,
+      messageId: "msg-parallel-pre-taskoutput",
+    });
+
+    client.emit("tool.start" as EventType, {
+      type: "tool.start",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        toolName: "Agent",
+        toolInput: { description: "Background A", run_in_background: true },
+        toolUseId: "task-tool-bg-a",
+      },
+    } as AgentEvent<"tool.start">);
+
+    client.emit("tool.start" as EventType, {
+      type: "tool.start",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        toolName: "Agent",
+        toolInput: { description: "Background B", run_in_background: true },
+        toolUseId: "task-tool-bg-b",
+      },
+    } as AgentEvent<"tool.start">);
+
+    client.emit("subagent.start" as EventType, {
+      type: "subagent.start",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        subagentId: "agent-bg-a",
+        subagentType: "research",
+        task: "Background A",
+        toolUseID: "task-tool-bg-a",
+      },
+    } as AgentEvent<"subagent.start">);
+
+    client.emit("subagent.start" as EventType, {
+      type: "subagent.start",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        subagentId: "agent-bg-b",
+        subagentType: "research",
+        task: "Background B",
+        toolUseID: "task-tool-bg-b",
+      },
+    } as AgentEvent<"subagent.start">);
+
+    // This mirrors leaked events before first TaskOutput arrives.
+    client.emit("tool.start" as EventType, {
+      type: "tool.start",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        toolName: "Read",
+        toolUseId: "pre-taskoutput-read-1",
+        toolInput: { file_path: "README.md" },
+      },
+    } as AgentEvent<"tool.start">);
+
+    await streamPromise;
+
+    const readStart = events.find(
+      (e) => e.type === "stream.tool.start" && e.data.toolId === "pre-taskoutput-read-1",
+    );
+    expect(readStart).toBeDefined();
+    expect(readStart?.data.parentAgentId).toBe("agent-bg-a");
+  });
+
+  test("attributes child-session tools via background fallback when parent correlation is unresolved", async () => {
+    const events = collectEvents(bus);
+    const client = createMockClient();
+
+    const chunks: AgentMessage[] = [{ type: "text", content: "done" }];
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream, client);
+
+    const streamPromise = adapter.startStreaming(session, "test", {
+      runId: 102,
+      messageId: "msg-child-session-bg-fallback",
+    });
+
+    client.emit("tool.start" as EventType, {
+      type: "tool.start",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        toolName: "Agent",
+        toolInput: { description: "Background A", run_in_background: true },
+        toolUseId: "task-tool-bg-a",
+      },
+    } as AgentEvent<"tool.start">);
+
+    client.emit("tool.start" as EventType, {
+      type: "tool.start",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        toolName: "Agent",
+        toolInput: { description: "Background B", run_in_background: true },
+        toolUseId: "task-tool-bg-b",
+      },
+    } as AgentEvent<"tool.start">);
+
+    client.emit("subagent.start" as EventType, {
+      type: "subagent.start",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        subagentId: "agent-bg-a",
+        subagentType: "research",
+        task: "Background A",
+        toolUseID: "task-tool-bg-a",
+      },
+    } as AgentEvent<"subagent.start">);
+
+    client.emit("subagent.start" as EventType, {
+      type: "subagent.start",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        subagentId: "agent-bg-b",
+        subagentType: "research",
+        task: "Background B",
+        toolUseID: "task-tool-bg-b",
+      },
+    } as AgentEvent<"subagent.start">);
+
+    // Child-session event that carries a parentToolUseId we cannot resolve.
+    // Adapter should still attribute this to active background context.
+    client.emit("tool.start" as EventType, {
+      type: "tool.start",
+      sessionId: "child-session-unknown",
+      timestamp: Date.now(),
+      data: {
+        toolName: "WebSearch",
+        toolUseId: "child-bg-tool-1",
+        toolInput: { query: "tree sync leakage" },
+        parentToolUseId: "missing-parent-correlation",
+      },
+    } as AgentEvent<"tool.start">);
+
+    client.emit("tool.complete" as EventType, {
+      type: "tool.complete",
+      sessionId: "child-session-unknown",
+      timestamp: Date.now(),
+      data: {
+        toolName: "WebSearch",
+        toolUseId: "child-bg-tool-1",
+        toolResult: { ok: true },
+        success: true,
+        parentToolUseId: "missing-parent-correlation",
+      },
+    } as AgentEvent<"tool.complete">);
+
+    await streamPromise;
+
+    const toolStart = events.find(
+      (e) => e.type === "stream.tool.start" && e.data.toolId === "child-bg-tool-1",
+    );
+    expect(toolStart).toBeDefined();
+    expect(toolStart?.data.parentAgentId).toBe("agent-bg-a");
+
+    const toolComplete = events.find(
+      (e) => e.type === "stream.tool.complete" && e.data.toolId === "child-bg-tool-1",
+    );
+    expect(toolComplete).toBeDefined();
+    expect(toolComplete?.data.parentAgentId).toBe("agent-bg-a");
+  });
+
+  test("preserves parentAgentId on orphaned tool completions during cleanup", async () => {
+    const events = collectEvents(bus);
+    const client = createMockClient();
+
+    const chunks: AgentMessage[] = [{ type: "text", content: "done" }];
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream, client);
+
+    const streamPromise = adapter.startStreaming(session, "test", {
+      runId: 103,
+      messageId: "msg-orphan-parent-preservation",
+    });
+
+    client.emit("subagent.start" as EventType, {
+      type: "subagent.start",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        subagentId: "agent-orphan-1",
+        subagentType: "Explore",
+        task: "Explore repository",
+        toolUseID: "tool-parent-orphan-1",
+      },
+    } as AgentEvent<"subagent.start">);
+
+    client.emit("tool.start" as EventType, {
+      type: "tool.start",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        toolName: "Bash",
+        toolInput: { command: "ls -la" },
+        toolUseId: "tool-orphan-1",
+      },
+    } as AgentEvent<"tool.start">);
+
+    await streamPromise;
+
+    const orphanedComplete = events.find(
+      (e) =>
+        e.type === "stream.tool.complete"
+        && e.data.toolId === "tool-orphan-1"
+        && e.data.error === "Tool execution aborted",
+    );
+    expect(orphanedComplete).toBeDefined();
+    expect(orphanedComplete?.data.parentAgentId).toBe("agent-orphan-1");
+  });
+
+  test("normalizes OpenCode subagent correlation IDs to the canonical tool ID", async () => {
+    const events = collectEvents(bus);
+    const client = createMockClient();
+
+    const chunks: AgentMessage[] = [{ type: "text", content: "done" }];
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream, client);
+
+    const streamPromise = adapter.startStreaming(session, "test", {
+      runId: 100,
+      messageId: "msg-2",
+    });
+
+    // Tool emits both IDs. Adapter canonicalizes to toolUseId as toolId,
+    // while preserving an alias so subagent.start with toolCallId still maps.
+    client.emit("tool.start" as EventType, {
+      type: "tool.start",
+      sessionId: "test-session-123",
+      timestamp: new Date().toISOString(),
+      data: {
+        toolName: "Task",
+        toolInput: { description: "Investigate" },
+        toolUseId: "tool-use-123",
+        toolCallId: "call-456",
+      },
+    } as AgentEvent);
+
+    client.emit("subagent.start" as EventType, {
+      type: "subagent.start",
+      sessionId: "test-session-123",
+      timestamp: new Date().toISOString(),
+      data: {
+        subagentId: "agent-001",
+        subagentType: "explore",
+        task: "Find files",
+        toolCallId: "call-456",
+      },
+    } as AgentEvent);
+
+    await streamPromise;
+
+    const toolStartEvents = events.filter((e) => e.type === "stream.tool.start");
+    expect(toolStartEvents.length).toBe(1);
+    expect(toolStartEvents[0].data.toolId).toBe("tool-use-123");
+
+    const agentStartEvents = events.filter((e) => e.type === "stream.agent.start");
+    expect(agentStartEvents.length).toBe(1);
+    expect(agentStartEvents[0].data.sdkCorrelationId).toBe("tool-use-123");
+  });
+
+  test("agent-only streams publish synthetic foreground agent lifecycle with tool progress", async () => {
+    const events = collectEvents(bus);
+    const client = createMockClient();
+
+    const chunks: AgentMessage[] = [{ type: "text", content: "done" }];
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream, client);
+
+    const streamPromise = adapter.startStreaming(session, "Investigate auth retries", {
+      runId: 101,
+      messageId: "msg-agent-only",
+      agent: "debugger",
+    });
+
+    client.emit("tool.start" as EventType, {
+      type: "tool.start",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        toolName: "bash",
+        toolInput: { command: "rg auth" },
+        toolUseId: "tool-agent-only-1",
+      },
+    } as AgentEvent);
+
+    client.emit("tool.complete" as EventType, {
+      type: "tool.complete",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        toolName: "bash",
+        toolUseId: "tool-agent-only-1",
+        toolResult: "ok",
+        success: true,
+      },
+    } as AgentEvent);
+
+    await streamPromise;
+
+    const agentStartEvents = events.filter((e) => e.type === "stream.agent.start");
+    expect(agentStartEvents.length).toBe(1);
+    expect(agentStartEvents[0].data.agentType).toBe("debugger");
+    expect(agentStartEvents[0].data.task).toBe("Investigate auth retries");
+
+    const syntheticAgentId = agentStartEvents[0].data.agentId;
+    const agentUpdateEvents = events.filter(
+      (e) => e.type === "stream.agent.update" && e.data.agentId === syntheticAgentId,
+    );
+    expect(agentUpdateEvents.some((e) => e.data.currentTool === "bash" && e.data.toolUses === 1)).toBe(true);
+    expect(agentUpdateEvents.some((e) => e.data.currentTool === undefined && e.data.toolUses === 1)).toBe(true);
+
+    const agentCompleteEvents = events.filter(
+      (e) => e.type === "stream.agent.complete" && e.data.agentId === syntheticAgentId,
+    );
+    expect(agentCompleteEvents.length).toBe(1);
+    expect(agentCompleteEvents[0].data.success).toBe(true);
+  });
+
+  test("uses parent_tool_use_id fallback to hydrate subagent task metadata", async () => {
+    const events = collectEvents(bus);
+    const client = createMockClient();
+
+    const chunks: AgentMessage[] = [{ type: "text", content: "done" }];
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream, client);
+
+    const streamPromise = adapter.startStreaming(session, "test", {
+      runId: 102,
+      messageId: "msg-parent-fallback",
+    });
+
+    client.emit("tool.start" as EventType, {
+      type: "tool.start",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        toolName: "Agent",
+        toolInput: { description: "Locate sub-agent tree rendering" },
+        toolUseId: "tool-parent-1",
+      },
+    } as AgentEvent);
+
+    client.emit("subagent.start" as EventType, {
+      type: "subagent.start",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        subagentId: "agent-parent-fallback",
+        subagentType: "codebase-locator",
+        task: "codebase-locator",
+        toolCallId: "uuid-1",
+        parent_tool_use_id: "tool-parent-1",
+      },
+    } as AgentEvent);
+
+    await streamPromise;
+
+    const agentStartEvents = events.filter((e) => e.type === "stream.agent.start");
+    expect(agentStartEvents.length).toBe(1);
+    expect(agentStartEvents[0].data.task).toBe("Locate sub-agent tree rendering");
+    expect(agentStartEvents[0].data.sdkCorrelationId).toBe("tool-parent-1");
+  });
+
+  test("attributes child tool events via parent_tool_call_id correlation", async () => {
+    const events = collectEvents(bus);
+    const client = createMockClient();
+
+    const chunks: AgentMessage[] = [{ type: "text", content: "done" }];
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream, client);
+
+    const streamPromise = adapter.startStreaming(session, "test", {
+      runId: 102,
+      messageId: "msg-parent-call-correlation",
+    });
+
+    client.emit("tool.start" as EventType, {
+      type: "tool.start",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        toolName: "Agent",
+        toolInput: { description: "Correlate by parent call id" },
+        toolUseId: "tool-parent-call-1",
+      },
+    } as AgentEvent);
+
+    client.emit("subagent.start" as EventType, {
+      type: "subagent.start",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        subagentId: "agent-parent-call-1",
+        subagentType: "codebase-locator",
+        task: "codebase-locator",
+        toolCallId: "subagent-call-1",
+        parent_tool_call_id: "tool-parent-call-1",
+      },
+    } as AgentEvent);
+
+    client.emit("tool.start" as EventType, {
+      type: "tool.start",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        toolName: "WebSearch",
+        toolInput: { query: "sync parallel agents" },
+        toolUseId: "inner-tool-1",
+        parent_tool_call_id: "tool-parent-call-1",
+      },
+    } as AgentEvent);
+
+    client.emit("tool.complete" as EventType, {
+      type: "tool.complete",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        toolName: "WebSearch",
+        toolUseId: "inner-tool-1",
+        toolResult: "ok",
+        success: true,
+        parent_tool_call_id: "tool-parent-call-1",
+      },
+    } as AgentEvent);
+
+    await streamPromise;
+
+    const innerStart = events.find(
+      (e) => e.type === "stream.tool.start" && e.data.toolId === "inner-tool-1",
+    );
+    expect(innerStart).toBeDefined();
+    expect(innerStart?.data.parentAgentId).toBe("agent-parent-call-1");
+
+    const innerComplete = events.find(
+      (e) => e.type === "stream.tool.complete" && e.data.toolId === "inner-tool-1",
+    );
+    expect(innerComplete).toBeDefined();
+    expect(innerComplete?.data.parentAgentId).toBe("agent-parent-call-1");
+  });
+
+  test("falls back to pending task tool ordering when subagent.start lacks parent correlation", async () => {
+    const events = collectEvents(bus);
+    const client = createMockClient();
+
+    const chunks: AgentMessage[] = [{ type: "text", content: "done" }];
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream, client);
+
+    const streamPromise = adapter.startStreaming(session, "test", {
+      runId: 103,
+      messageId: "msg-pending-fallback",
+    });
+
+    client.emit("tool.start" as EventType, {
+      type: "tool.start",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        toolName: "Agent",
+        toolInput: { description: "Find missing sub-agent metadata wiring" },
+        toolUseId: "tool-pending-1",
+      },
+    } as AgentEvent);
+
+    client.emit("subagent.start" as EventType, {
+      type: "subagent.start",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        subagentId: "agent-pending-fallback",
+        subagentType: "debugger",
+        task: "debugger",
+        toolCallId: "unmapped-call-id",
+      },
+    } as AgentEvent);
+
+    await streamPromise;
+
+    const agentStartEvents = events.filter((e) => e.type === "stream.agent.start");
+    expect(agentStartEvents.length).toBe(1);
+    expect(agentStartEvents[0].data.task).toBe("Find missing sub-agent metadata wiring");
+    expect(agentStartEvents[0].data.sdkCorrelationId).toBe("tool-pending-1");
+  });
+
+  test("real usage events publish stream.usage with accumulated tokens", async () => {
+    const events = collectEvents(bus);
+    const client = createMockClient();
+
+    const chunks: AgentMessage[] = [{ type: "text", content: "done" }];
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream, client);
+
+    const streamPromise = adapter.startStreaming(session, "test message", {
+      runId: 100,
+      messageId: "msg-2",
+    });
+
+    // Emit first usage event (e.g., first API turn)
+    client.emit("usage" as EventType, {
+      type: "usage",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        inputTokens: 100,
+        outputTokens: 50,
+        model: "claude-sonnet-4-20250514",
+      },
+    } as AgentEvent);
+
+    // Emit second usage event (e.g., second API turn after tool use)
+    client.emit("usage" as EventType, {
+      type: "usage",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        inputTokens: 200,
+        outputTokens: 75,
+        model: "claude-sonnet-4-20250514",
+      },
+    } as AgentEvent);
+
+    await streamPromise;
+
+    const usageEvents = events.filter((e) => e.type === "stream.usage");
+    expect(usageEvents.length).toBe(2);
+    // First event: accumulated outputTokens = 50
+    expect(usageEvents[0].data.inputTokens).toBe(100);
+    expect(usageEvents[0].data.outputTokens).toBe(50);
+    expect(usageEvents[0].data.model).toBe("claude-sonnet-4-20250514");
+    // Second event: accumulated outputTokens = 50 + 75 = 125
+    expect(usageEvents[1].data.inputTokens).toBe(200);
+    expect(usageEvents[1].data.outputTokens).toBe(125);
+  });
+
+  test("zero-valued diagnostics markers are filtered (no stream.usage emitted)", async () => {
+    const events = collectEvents(bus);
+    const client = createMockClient();
+
+    const chunks: AgentMessage[] = [{ type: "text", content: "done" }];
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream, client);
+
+    const streamPromise = adapter.startStreaming(session, "test message", {
+      runId: 100,
+      messageId: "msg-2",
+    });
+
+    // Emit a diagnostics marker with no real token data
+    client.emit("usage" as EventType, {
+      type: "usage",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        provider: "claude",
+        marker: "claude.stream.integrity",
+      },
+    } as AgentEvent);
+
+    await streamPromise;
+
+    const usageEvents = events.filter((e) => e.type === "stream.usage");
+    expect(usageEvents.length).toBe(0);
+  });
+
+  test("thinking chunks emit stream.thinking.complete but NOT stream.usage", async () => {
+    const events = collectEvents(bus);
+
+    const chunks: AgentMessage[] = [
+      {
+        type: "thinking",
+        content: "Let me think...",
+        metadata: { thinkingSourceKey: "block-1" },
+      },
+      {
+        type: "thinking",
+        content: "",
+        metadata: {
+          thinkingSourceKey: "block-1",
+          streamingStats: { thinkingMs: 2000, outputTokens: 150 },
+        },
+      },
+    ];
+
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream);
+
+    await adapter.startStreaming(session, "test message", {
+      runId: 100,
+      messageId: "msg-2",
+    });
+
+    // Should have thinking.complete
+    const thinkingCompleteEvents = events.filter(
+      (e) => e.type === "stream.thinking.complete",
+    );
+    expect(thinkingCompleteEvents.length).toBe(1);
+    expect(thinkingCompleteEvents[0].data.durationMs).toBe(2000);
+
+    // Should NOT have stream.usage from thinking chunks
+    const usageEvents = events.filter((e) => e.type === "stream.usage");
+    expect(usageEvents.length).toBe(0);
+  });
+
+  test("publishes agent complete events from subagent.complete hook", async () => {
+    const events = collectEvents(bus);
+    const client = createMockClient();
+
+    const chunks: AgentMessage[] = [{ type: "text", content: "done" }];
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream, client);
+
+    const streamPromise = adapter.startStreaming(session, "test", {
+      runId: 100,
+      messageId: "msg-2",
+    });
+
+    // Simulate subagent.complete hook event from the SDK
+    client.emit("subagent.complete" as EventType, {
+      type: "subagent.complete",
+      sessionId: "test-session-123",
+      timestamp: new Date().toISOString(),
+      data: {
+        subagentId: "agent-001",
+        success: true,
+        result: "Found 3 files",
+      },
+    } as AgentEvent);
+
+    await streamPromise;
+
+    const agentCompleteEvents = events.filter((e) => e.type === "stream.agent.complete");
+    expect(agentCompleteEvents.length).toBe(1);
+    expect(agentCompleteEvents[0].data.agentId).toBe("agent-001");
+    expect(agentCompleteEvents[0].data.success).toBe(true);
+    expect(agentCompleteEvents[0].data.result).toBe("Found 3 files");
+    expect(agentCompleteEvents[0].runId).toBe(100);
+  });
+
+  test("strict runtime contract normalizes Claude subagent task metadata", async () => {
+    const events = collectEvents(bus);
+    const client = createMockClient();
+
+    const chunks: AgentMessage[] = [{ type: "text", content: "done" }];
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream, client);
+
+    const streamPromise = adapter.startStreaming(session, "test", {
+      runId: 100,
+      messageId: "msg-2",
+      runtimeFeatureFlags: {
+        strictTaskContract: true,
+      },
+    });
+
+    client.emit("subagent.start" as EventType, {
+      type: "subagent.start",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        subagentId: "agent-cl-1",
+        subagentType: "research",
+        task: "   ",
+        toolInput: {
+          prompt: "Review deploy logs",
+          run_in_background: true,
+        },
+      },
+    } as AgentEvent<"subagent.start">);
+
+    await streamPromise;
+
+    const agentStartEvents = events.filter((e) => e.type === "stream.agent.start");
+    expect(agentStartEvents.length).toBe(1);
+    expect(agentStartEvents[0].data.task).toBe("Review deploy logs");
+    expect(agentStartEvents[0].data.isBackground).toBe(true);
+  });
+
+  test("maps extended Claude client events to canonical stream events", async () => {
+    const events = collectEvents(bus);
+    const client = createMockClient();
+
+    const session = createMockSession(mockAsyncStream([{ type: "text", content: "done" }]), client);
+    const streamPromise = adapter.startStreaming(session, "test", {
+      runId: 100,
+      messageId: "msg-2",
+      runtimeFeatureFlags: { strictTaskContract: true },
+    });
+
+    client.emit("reasoning.delta" as EventType, {
+      type: "reasoning.delta",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: { reasoningId: "r-1", delta: "trace" },
+    } as AgentEvent<"reasoning.delta">);
+
+    client.emit("reasoning.complete" as EventType, {
+      type: "reasoning.complete",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: { reasoningId: "r-1", content: "trace complete" },
+    } as AgentEvent<"reasoning.complete">);
+
+    client.emit("turn.start" as EventType, {
+      type: "turn.start",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {},
+    } as AgentEvent<"turn.start">);
+
+    client.emit("turn.end" as EventType, {
+      type: "turn.end",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: { finish_reason: "end_turn" },
+    } as AgentEvent<"turn.end">);
+
+    client.emit("tool.partial_result" as EventType, {
+      type: "tool.partial_result",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: { toolCallId: "tool-1", partialOutput: "half" },
+    } as AgentEvent<"tool.partial_result">);
+
+    client.emit("session.info" as EventType, {
+      type: "session.info",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: { infoType: "general", message: "hello" },
+    } as AgentEvent<"session.info">);
+
+    client.emit("session.warning" as EventType, {
+      type: "session.warning",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: { warningType: "general", message: "careful" },
+    } as AgentEvent<"session.warning">);
+
+    client.emit("session.title_changed" as EventType, {
+      type: "session.title_changed",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: { title: "new title" },
+    } as AgentEvent<"session.title_changed">);
+
+    client.emit("session.truncation" as EventType, {
+      type: "session.truncation",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: { tokenLimit: 1000, tokensRemoved: 50, messagesRemoved: 1 },
+    } as AgentEvent<"session.truncation">);
+
+    client.emit("session.compaction" as EventType, {
+      type: "session.compaction",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: { phase: "start" },
+    } as AgentEvent<"session.compaction">);
+
+    client.emit("skill.invoked" as EventType, {
+      type: "skill.invoked",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: { skillName: "frontend-design", skillPath: "skills/front.md" },
+    } as AgentEvent<"skill.invoked">);
+
+    client.emit("human_input_required" as EventType, {
+      type: "human_input_required",
+      sessionId: "test-session-123",
+      timestamp: Date.now(),
+      data: {
+        requestId: "req-1",
+        question: "Proceed?",
+        nodeId: "n1",
+      },
+    } as AgentEvent<"human_input_required">);
+
+    await streamPromise;
+
+    expect(events.some((e) => e.type === "stream.thinking.delta" && e.data.sourceKey === "r-1")).toBe(true);
+    expect(events.some((e) => e.type === "stream.thinking.complete" && e.data.sourceKey === "r-1")).toBe(true);
+    expect(events.some((e) => e.type === "stream.turn.start")).toBe(true);
+    expect(events.some((e) => e.type === "stream.turn.end")).toBe(true);
+    const turnEnd = events.find((e) => e.type === "stream.turn.end");
+    expect(turnEnd?.data.finishReason).toBe("stop");
+    expect(turnEnd?.data.rawFinishReason).toBe("end_turn");
+    expect(events.some((e) => e.type === "stream.tool.partial_result")).toBe(true);
+    expect(events.some((e) => e.type === "stream.session.info")).toBe(true);
+    expect(events.some((e) => e.type === "stream.session.warning")).toBe(true);
+    expect(events.some((e) => e.type === "stream.session.title_changed")).toBe(true);
+    expect(events.some((e) => e.type === "stream.session.truncation")).toBe(true);
+    expect(events.some((e) => e.type === "stream.session.compaction")).toBe(true);
+    expect(events.some((e) => e.type === "stream.skill.invoked")).toBe(true);
+    expect(events.some((e) => e.type === "stream.human_input_required")).toBe(true);
+  });
+});
+
+// ============================================================================
+// CopilotStreamAdapter Tests
+// ============================================================================
+
+describe("CopilotStreamAdapter", () => {
+  let bus: EventBus;
+  let client: CodingAgentClient;
+  let adapter: CopilotStreamAdapter;
+
+  beforeEach(() => {
+    bus = new EventBus();
+    client = createMockClient();
+    adapter = new CopilotStreamAdapter(bus, client);
+  });
+
+  test("publishes text delta events from EventEmitter", async () => {
+    const events = collectEvents(bus);
+
+    const chunks: AgentMessage[] = [
+      { type: "text", content: "Hello " },
+      { type: "text", content: "Copilot" },
+    ];
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream);
+
+    const streamPromise = adapter.startStreaming(session, "test message", {
+      runId: 200,
+      messageId: "msg-3",
+    });
+
+    // Emit message.delta events through the client
+    client.emit("message.delta" as EventType, {
+      type: "message.delta",
+      sessionId: session.id,
+      timestamp: Date.now(),
+      data: {
+        delta: "Hello ",
+        contentType: "text",
+      },
+    } as AgentEvent<"message.delta">);
+
+    client.emit("message.delta" as EventType, {
+      type: "message.delta",
+      sessionId: session.id,
+      timestamp: Date.now(),
+      data: {
+        delta: "Copilot",
+        contentType: "text",
+      },
+    } as AgentEvent<"message.delta">);
+
+    // Emit message.complete
+    client.emit("message.complete" as EventType, {
+      type: "message.complete",
+      sessionId: session.id,
+      timestamp: Date.now(),
+      data: {
+        message: "Hello Copilot",
+      },
+    } as AgentEvent<"message.complete">);
+
+    await streamPromise;
+
+    const deltaEvents = events.filter((e) => e.type === "stream.text.delta");
+    expect(deltaEvents.length).toBe(2);
+    expect(deltaEvents[0].data.delta).toBe("Hello ");
+    expect(deltaEvents[0].data.messageId).toBe("msg-3");
+    expect(deltaEvents[0].runId).toBe(200);
+    expect(deltaEvents[1].data.delta).toBe("Copilot");
+
+    const completeEvents = events.filter(
+      (e) => e.type === "stream.text.complete",
+    );
+    expect(completeEvents.length).toBe(1);
+    expect(completeEvents[0].data.fullText).toBe("Hello Copilot");
+    expect(completeEvents[0].runId).toBe(200);
+  });
+
+  test("publishes tool start events", async () => {
+    const events = collectEvents(bus);
+
+    const chunks: AgentMessage[] = [{ type: "text", content: "done" }];
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream);
+
+    const streamPromise = adapter.startStreaming(session, "test message", {
+      runId: 200,
+      messageId: "msg-3",
+    });
+
+    // Emit tool.start event
+    client.emit("tool.start" as EventType, {
+      type: "tool.start",
+      sessionId: session.id,
+      timestamp: Date.now(),
+      data: {
+        toolName: "view",
+        toolInput: { path: "/test" },
+        toolCallId: "tool-456",
+      },
+    } as AgentEvent<"tool.start">);
+
+    await streamPromise;
+
+    const toolStartEvents = events.filter(
+      (e) => e.type === "stream.tool.start",
+    );
+    expect(toolStartEvents.length).toBe(1);
+    expect(toolStartEvents[0].data.toolName).toBe("view");
+    expect(toolStartEvents[0].data.toolInput).toEqual({ path: "/test" });
+    expect(toolStartEvents[0].data.toolId).toBe("tool-456");
+    expect(toolStartEvents[0].runId).toBe(200);
+  });
+
+  test("normalizes non-object tool input for tool start events", async () => {
+    const events = collectEvents(bus);
+
+    const chunks: AgentMessage[] = [{ type: "text", content: "done" }];
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream);
+
+    const streamPromise = adapter.startStreaming(session, "test message", {
+      runId: 200,
+      messageId: "msg-3",
+    });
+
+    client.emit("tool.start" as EventType, {
+      type: "tool.start",
+      sessionId: session.id,
+      timestamp: Date.now(),
+      data: {
+        toolName: "bash",
+        toolInput: "ls -la",
+        toolCallId: "tool-raw-input",
+      },
+    } as AgentEvent<"tool.start">);
+
+    await streamPromise;
+
+    const toolStartEvents = events.filter(
+      (e) => e.type === "stream.tool.start",
+    );
+    expect(toolStartEvents.length).toBe(1);
+    expect(toolStartEvents[0].data.toolId).toBe("tool-raw-input");
+    expect(toolStartEvents[0].data.toolInput).toEqual({ value: "ls -la" });
+  });
+
+  test("publishes tool complete events", async () => {
+    const events = collectEvents(bus);
+
+    const chunks: AgentMessage[] = [{ type: "text", content: "done" }];
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream);
+
+    const streamPromise = adapter.startStreaming(session, "test message", {
+      runId: 200,
+      messageId: "msg-3",
+    });
+
+    // Emit tool.complete event
+    client.emit("tool.complete" as EventType, {
+      type: "tool.complete",
+      sessionId: session.id,
+      timestamp: Date.now(),
+      data: {
+        toolName: "view",
+        toolResult: "file contents",
+        success: true,
+        toolCallId: "tool-456",
+      },
+    } as AgentEvent<"tool.complete">);
+
+    await streamPromise;
+
+    const toolCompleteEvents = events.filter(
+      (e) => e.type === "stream.tool.complete",
+    );
+    expect(toolCompleteEvents.length).toBe(1);
+    expect(toolCompleteEvents[0].data.toolName).toBe("view");
+    expect(toolCompleteEvents[0].data.toolResult).toBe("file contents");
+    expect(toolCompleteEvents[0].data.success).toBe(true);
+    expect(toolCompleteEvents[0].runId).toBe(200);
+  });
+
+  test("publishes session error on stream error", async () => {
+    const events = collectEvents(bus);
+
+    async function* errorStream(): AsyncGenerator<AgentMessage> {
+      throw new Error("Copilot connection error");
+    }
+
+    const session = createMockSession(errorStream());
+
+    await adapter.startStreaming(session, "test message", {
+      runId: 200,
+      messageId: "msg-3",
+    });
+
+    const errorEvents = events.filter(
+      (e) => e.type === "stream.session.error",
+    );
+    expect(errorEvents.length).toBe(1);
+    expect(errorEvents[0].data.error).toBe("Copilot connection error");
+    expect(errorEvents[0].runId).toBe(200);
+  });
+
+  test("dispose() stops processing", async () => {
+    const events = collectEvents(bus);
+
+    async function* longStream(): AsyncGenerator<AgentMessage> {
+      for (let i = 0; i < 100; i++) {
+        yield { type: "text", content: `chunk${i}` };
+        await new Promise((resolve) => setTimeout(resolve, 5));
+      }
+    }
+
+    const session = createMockSession(longStream());
+
+    const streamPromise = adapter.startStreaming(session, "test message", {
+      runId: 200,
+      messageId: "msg-3",
+    });
+
+    // Dispose immediately
+    adapter.dispose();
+
+    await streamPromise;
+
+    // Should have no events or very few events due to early disposal
+    // The isActive flag should prevent event emission
+    expect(events.length).toBeLessThan(10);
+  });
+
+  test("events include correct runId from options", async () => {
+    const events = collectEvents(bus);
+
+    const chunks: AgentMessage[] = [{ type: "text", content: "test" }];
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream);
+
+    const streamPromise = adapter.startStreaming(session, "test message", {
+      runId: 888,
+      messageId: "msg-3",
+    });
+
+    // Emit an event
+    client.emit("message.delta" as EventType, {
+      type: "message.delta",
+      sessionId: session.id,
+      timestamp: Date.now(),
+      data: {
+        delta: "test",
+        contentType: "text",
+      },
+    } as AgentEvent<"message.delta">);
+
+    await streamPromise;
+
+    // All events should have runId 888
+    expect(events.every((e) => e.runId === 888)).toBe(true);
+  });
+
+  test("unmapped event types are ignored", async () => {
+    const events = collectEvents(bus);
+
+    const chunks: AgentMessage[] = [{ type: "text", content: "test" }];
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream);
+
+    const streamPromise = adapter.startStreaming(session, "test message", {
+      runId: 200,
+      messageId: "msg-3",
+    });
+
+    // Emit an unmapped event type
+    client.emit("unknown.event" as EventType, {
+      type: "unknown.event",
+      sessionId: session.id,
+      timestamp: Date.now(),
+      data: {},
+    } as AgentEvent);
+
+    // Emit a mapped event
+    client.emit("message.delta" as EventType, {
+      type: "message.delta",
+      sessionId: session.id,
+      timestamp: Date.now(),
+      data: {
+        delta: "test",
+        contentType: "text",
+      },
+    } as AgentEvent<"message.delta">);
+
+    await streamPromise;
+
+    // Should only have events from mapped types
+    const deltaEvents = events.filter((e) => e.type === "stream.text.delta");
+    expect(deltaEvents.length).toBe(1);
+
+    // No unknown events should be published
+    expect(events.every((e) => e.type.startsWith("stream."))).toBe(true);
+  });
+
+  test("complete events are published at stream end", async () => {
+    const events = collectEvents(bus);
+
+    const chunks: AgentMessage[] = [{ type: "text", content: "test" }];
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream);
+
+    const streamPromise = adapter.startStreaming(session, "test message", {
+      runId: 200,
+      messageId: "msg-3",
+    });
+
+    // Emit message deltas
+    client.emit("message.delta" as EventType, {
+      type: "message.delta",
+      sessionId: session.id,
+      timestamp: Date.now(),
+      data: {
+        delta: "Hello",
+        contentType: "text",
+      },
+    } as AgentEvent<"message.delta">);
+
+    // Emit message.complete
+    client.emit("message.complete" as EventType, {
+      type: "message.complete",
+      sessionId: session.id,
+      timestamp: Date.now(),
+      data: {
+        message: "Hello",
+      },
+    } as AgentEvent<"message.complete">);
+
+    // Emit session.idle — mirrors the real Copilot SDK, which dispatches
+    // session.idle through the client-level event system after all
+    // agentic processing completes.
+    client.emit("session.idle" as EventType, {
+      type: "session.idle",
+      sessionId: session.id,
+      timestamp: Date.now(),
+      data: { reason: "idle" },
+    } as AgentEvent<"session.idle">);
+
+    await streamPromise;
+
+    // Should have idle event from the client-level session.idle subscription
+    const idleEvents = events.filter((e) => e.type === "stream.session.idle");
+    expect(idleEvents.length).toBeGreaterThanOrEqual(1);
+
+    // Should have complete event
+    const completeEvents = events.filter(
+      (e) => e.type === "stream.text.complete",
+    );
+    expect(completeEvents.length).toBe(1);
+  });
+
+  test("strict runtime contract keeps synthetic turn id stable in Copilot", async () => {
+    const events = collectEvents(bus);
+
+    const chunks: AgentMessage[] = [{ type: "text", content: "done" }];
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream);
+
+    const streamPromise = adapter.startStreaming(session, "test message", {
+      runId: 200,
+      messageId: "msg-turn-strict",
+      runtimeFeatureFlags: {
+        strictTaskContract: true,
+      },
+    });
+
+    client.emit("turn.start" as EventType, {
+      type: "turn.start",
+      sessionId: session.id,
+      timestamp: Date.now(),
+      data: {},
+    } as AgentEvent<"turn.start">);
+
+    client.emit("turn.end" as EventType, {
+      type: "turn.end",
+      sessionId: session.id,
+      timestamp: Date.now(),
+      data: { finishReason: "length" },
+    } as AgentEvent<"turn.end">);
+
+    await streamPromise;
+
+    const turnStartEvents = events.filter((e) => e.type === "stream.turn.start");
+    const turnEndEvents = events.filter((e) => e.type === "stream.turn.end");
+    expect(turnStartEvents.length).toBe(1);
+    expect(turnEndEvents.length).toBe(1);
+    expect(turnStartEvents[0].data.turnId).toMatch(/^turn_/);
+    expect(turnEndEvents[0].data.turnId).toBe(turnStartEvents[0].data.turnId);
+    expect(turnEndEvents[0].data.finishReason).toBe("max-tokens");
+    expect(turnEndEvents[0].data.rawFinishReason).toBe("length");
+  });
+
+  test("strict runtime contract falls back subagent task to agent type in Copilot", async () => {
+    const events = collectEvents(bus);
+
+    const chunks: AgentMessage[] = [{ type: "text", content: "done" }];
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream);
+
+    const streamPromise = adapter.startStreaming(session, "test", {
+      runId: 200,
+      messageId: "msg-task-strict",
+      runtimeFeatureFlags: {
+        strictTaskContract: true,
+      },
+    });
+
+    client.emit("subagent.start" as EventType, {
+      type: "subagent.start",
+      sessionId: session.id,
+      timestamp: Date.now(),
+      data: {
+        subagentId: "sub-strict-1",
+        subagentType: "general-purpose",
+        task: "   ",
+        toolCallId: "strict-task-1",
+      },
+    } as AgentEvent<"subagent.start">);
+
+    await streamPromise;
+
+    const agentStartEvents = events.filter((e) => e.type === "stream.agent.start");
+    expect(agentStartEvents.length).toBe(1);
+    expect(agentStartEvents[0].data.task).toBe("general-purpose");
+    expect(agentStartEvents[0].data.isBackground).toBe(false);
+  });
+
+  test("publishes thinking delta events from message.delta with thinking content", async () => {
+    const events = collectEvents(bus);
+
+    const chunks: AgentMessage[] = [{ type: "text", content: "done" }];
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream);
+
+    const streamPromise = adapter.startStreaming(session, "test message", {
+      runId: 200,
+      messageId: "msg-3",
+    });
+
+    // Emit thinking deltas
+    client.emit("message.delta" as EventType, {
+      type: "message.delta",
+      sessionId: session.id,
+      timestamp: Date.now(),
+      data: {
+        delta: "Thinking about this...",
+        contentType: "thinking",
+        thinkingSourceKey: "reason-1",
+      },
+    } as AgentEvent<"message.delta">);
+
+    client.emit("message.delta" as EventType, {
+      type: "message.delta",
+      sessionId: session.id,
+      timestamp: Date.now(),
+      data: {
+        delta: "conclusion reached",
+        contentType: "thinking",
+        thinkingSourceKey: "reason-1",
+      },
+    } as AgentEvent<"message.delta">);
+
+    // Emit message.complete to trigger thinking complete
+    client.emit("message.complete" as EventType, {
+      type: "message.complete",
+      sessionId: session.id,
+      timestamp: Date.now(),
+      data: {
+        message: "",
+      },
+    } as AgentEvent<"message.complete">);
+
+    await streamPromise;
+
+    const thinkingDeltaEvents = events.filter(
+      (e) => e.type === "stream.thinking.delta",
+    );
+    expect(thinkingDeltaEvents.length).toBe(2);
+    expect(thinkingDeltaEvents[0].data.delta).toBe("Thinking about this...");
+    expect(thinkingDeltaEvents[0].data.sourceKey).toBe("reason-1");
+    expect(thinkingDeltaEvents[1].data.delta).toBe("conclusion reached");
+
+    const thinkingCompleteEvents = events.filter(
+      (e) => e.type === "stream.thinking.complete",
+    );
+    expect(thinkingCompleteEvents.length).toBe(1);
+    expect(thinkingCompleteEvents[0].data.sourceKey).toBe("reason-1");
+  });
+
+  test("detects background sub-agents from task tool arguments", async () => {
+    const events = collectEvents(bus);
+
+    const chunks: AgentMessage[] = [{ type: "text", content: "done" }];
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream);
+
+    const streamPromise = adapter.startStreaming(session, "test message", {
+      runId: 200,
+      messageId: "msg-3",
+    });
+
+    // Emit message.complete with a task tool request containing mode: "background"
+    client.emit("message.complete" as EventType, {
+      type: "message.complete",
+      sessionId: session.id,
+      timestamp: Date.now(),
+      data: {
+        toolRequests: [
+          {
+            toolCallId: "task-call-1",
+            name: "Task",
+            arguments: {
+              description: "Search for auth patterns",
+              mode: "background",
+              subagent_type: "Explore",
+            },
+          },
+        ],
+      },
+    } as AgentEvent<"message.complete">);
+
+    // Emit subagent.start with matching toolCallId
+    client.emit("subagent.start" as EventType, {
+      type: "subagent.start",
+      sessionId: session.id,
+      timestamp: Date.now(),
+      data: {
+        subagentId: "sub-1",
+        subagentType: "Explore",
+        task: "Fast agent for exploring codebases",
+        toolCallId: "task-call-1",
+      },
+    } as AgentEvent<"subagent.start">);
+
+    await streamPromise;
+
+    const agentStartEvents = events.filter((e) => e.type === "stream.agent.start");
+    expect(agentStartEvents.length).toBe(1);
+    expect(agentStartEvents[0].data.isBackground).toBe(true);
+    expect(agentStartEvents[0].data.task).toBe("Search for auth patterns");
+  });
+
+  test("extracts task description from task tool arguments over agent type description", async () => {
+    const events = collectEvents(bus);
+
+    const chunks: AgentMessage[] = [{ type: "text", content: "done" }];
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream);
+
+    const streamPromise = adapter.startStreaming(session, "test message", {
+      runId: 200,
+      messageId: "msg-3",
+    });
+
+    // Emit message.complete with a task tool request
+    client.emit("message.complete" as EventType, {
+      type: "message.complete",
+      sessionId: session.id,
+      timestamp: Date.now(),
+      data: {
+        toolRequests: [
+          {
+            toolCallId: "task-call-2",
+            name: "launch_agent",
+            arguments: {
+              description: "Find auth code",
+              subagent_type: "codebase-locator",
+            },
+          },
+        ],
+      },
+    } as AgentEvent<"message.complete">);
+
+    // Emit subagent.start — task field has the agent type description
+    client.emit("subagent.start" as EventType, {
+      type: "subagent.start",
+      sessionId: session.id,
+      timestamp: Date.now(),
+      data: {
+        subagentId: "sub-2",
+        subagentType: "codebase-locator",
+        task: "Locates files and components",
+        toolCallId: "task-call-2",
+      },
+    } as AgentEvent<"subagent.start">);
+
+    await streamPromise;
+
+    const agentStartEvents = events.filter((e) => e.type === "stream.agent.start");
+    expect(agentStartEvents.length).toBe(1);
+    expect(agentStartEvents[0].data.task).toBe("Find auth code");
+  });
+
+  test("buffers early tool events before subagent.started and replays them", async () => {
+    const events = collectEvents(bus);
+
+    const chunks: AgentMessage[] = [{ type: "text", content: "done" }];
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream);
+
+    const streamPromise = adapter.startStreaming(session, "test message", {
+      runId: 200,
+      messageId: "msg-3",
+    });
+
+    // Emit tool.start with parentId BEFORE subagent.start (race condition)
+    client.emit("tool.start" as EventType, {
+      type: "tool.start",
+      sessionId: session.id,
+      timestamp: Date.now(),
+      data: {
+        toolName: "glob",
+        toolInput: { pattern: "**/*.ts" },
+        toolCallId: "early-tool-1",
+        parentId: "sub-3",
+      },
+    } as AgentEvent<"tool.start">);
+
+    // Now emit the subagent.start — should replay the buffered tool event
+    client.emit("subagent.start" as EventType, {
+      type: "subagent.start",
+      sessionId: session.id,
+      timestamp: Date.now(),
+      data: {
+        subagentId: "sub-3",
+        subagentType: "Explore",
+        task: "Find TypeScript files",
+        toolCallId: "task-call-3",
+      },
+    } as AgentEvent<"subagent.start">);
+
+    await streamPromise;
+
+    // The early tool event should have been replayed, triggering stream.agent.update
+    const updateEvents = events.filter((e) => e.type === "stream.agent.update");
+    expect(updateEvents.length).toBeGreaterThanOrEqual(1);
+    expect(updateEvents[0].data.agentId).toBe("sub-3");
+    expect(updateEvents[0].data.toolUses).toBe(1);
+    expect(updateEvents[0].data.currentTool).toBe("glob");
+  });
+
+  test("publishes subagent progress updates on tool.partial_result", async () => {
+    const events = collectEvents(bus);
+
+    const chunks: AgentMessage[] = [{ type: "text", content: "done" }];
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream);
+
+    const streamPromise = adapter.startStreaming(session, "test message", {
+      runId: 200,
+      messageId: "msg-3",
+    });
+
+    client.emit("subagent.start" as EventType, {
+      type: "subagent.start",
+      sessionId: session.id,
+      timestamp: Date.now(),
+      data: {
+        subagentId: "sub-partial-1",
+        subagentType: "Explore",
+        task: "Watch streaming tool output",
+        toolCallId: "task-call-partial-1",
+      },
+    } as AgentEvent<"subagent.start">);
+
+    client.emit("tool.start" as EventType, {
+      type: "tool.start",
+      sessionId: session.id,
+      timestamp: Date.now(),
+      data: {
+        toolName: "bash",
+        toolInput: { command: "tail -f logs" },
+        toolCallId: "inner-tool-partial-1",
+        parentId: "sub-partial-1",
+      },
+    } as AgentEvent<"tool.start">);
+
+    client.emit("tool.partial_result" as EventType, {
+      type: "tool.partial_result",
+      sessionId: session.id,
+      timestamp: Date.now(),
+      data: {
+        toolCallId: "inner-tool-partial-1",
+        partialOutput: "line 1",
+      },
+    } as AgentEvent<"tool.partial_result">);
+
+    await streamPromise;
+
+    const progressUpdates = events.filter(
+      (e) =>
+        e.type === "stream.agent.update"
+        && e.data.agentId === "sub-partial-1"
+        && e.data.currentTool === "bash",
+    );
+    expect(progressUpdates.length).toBeGreaterThanOrEqual(2);
+    expect(progressUpdates.some((e) => e.data.toolUses === 1)).toBe(true);
+  });
+
+  test("defaults to foreground when task tool has no mode field", async () => {
+    const events = collectEvents(bus);
+
+    const chunks: AgentMessage[] = [{ type: "text", content: "done" }];
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream);
+
+    const streamPromise = adapter.startStreaming(session, "test message", {
+      runId: 200,
+      messageId: "msg-3",
+    });
+
+    // Emit message.complete with a task tool request without mode
+    client.emit("message.complete" as EventType, {
+      type: "message.complete",
+      sessionId: session.id,
+      timestamp: Date.now(),
+      data: {
+        toolRequests: [
+          {
+            toolCallId: "task-call-4",
+            name: "Task",
+            arguments: {
+              description: "Analyze dependencies",
+              subagent_type: "general-purpose",
+            },
+          },
+        ],
+      },
+    } as AgentEvent<"message.complete">);
+
+    // Emit subagent.start
+    client.emit("subagent.start" as EventType, {
+      type: "subagent.start",
+      sessionId: session.id,
+      timestamp: Date.now(),
+      data: {
+        subagentId: "sub-4",
+        subagentType: "general-purpose",
+        task: "General-purpose agent",
+        toolCallId: "task-call-4",
+      },
+    } as AgentEvent<"subagent.start">);
+
+    await streamPromise;
+
+    const agentStartEvents = events.filter((e) => e.type === "stream.agent.start");
+    expect(agentStartEvents.length).toBe(1);
+    expect(agentStartEvents[0].data.isBackground).toBe(false);
+    expect(agentStartEvents[0].data.task).toBe("Analyze dependencies");
+  });
+
+  test("recognizes Copilot agent names as task tools via knownAgentNames", async () => {
+    const events = collectEvents(bus);
+
+    const chunks: AgentMessage[] = [{ type: "text", content: "done" }];
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream);
+
+    const streamPromise = adapter.startStreaming(session, "test", {
+      runId: 500,
+      messageId: "msg-agent-name",
+      knownAgentNames: ["codebase-analyzer", "General-Purpose"],
+    });
+
+    // Emit message.complete with agent-named tool request
+    client.emit("message.complete" as EventType, {
+      type: "message.complete",
+      sessionId: session.id,
+      timestamp: Date.now(),
+      data: {
+        toolRequests: [
+          {
+            toolCallId: "agent-tool-1",
+            name: "codebase-analyzer",
+            arguments: {
+              prompt: "Analyze the auth module",
+              subagent_type: "codebase-analyzer",
+            },
+          },
+        ],
+      },
+    } as AgentEvent<"message.complete">);
+
+    // Emit subagent.start
+    client.emit("subagent.start" as EventType, {
+      type: "subagent.start",
+      sessionId: session.id,
+      timestamp: Date.now(),
+      data: {
+        subagentId: "sub-agent-1",
+        subagentType: "codebase-analyzer",
+        task: "Generic analyzer agent",
+        toolCallId: "agent-tool-1",
+      },
+    } as AgentEvent<"subagent.start">);
+
+    await streamPromise;
+
+    const agentStartEvents = events.filter((e) => e.type === "stream.agent.start");
+    expect(agentStartEvents.length).toBe(1);
+    // Task description from prompt argument should be used
+    expect(agentStartEvents[0].data.task).toBe("Analyze the auth module");
+  });
+
+  test("extracts description from prompt argument (Copilot pattern)", async () => {
+    const events = collectEvents(bus);
+
+    const chunks: AgentMessage[] = [{ type: "text", content: "done" }];
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream);
+
+    const streamPromise = adapter.startStreaming(session, "test", {
+      runId: 501,
+      messageId: "msg-prompt",
+      knownAgentNames: ["general-purpose"],
+    });
+
+    client.emit("message.complete" as EventType, {
+      type: "message.complete",
+      sessionId: session.id,
+      timestamp: Date.now(),
+      data: {
+        toolRequests: [
+          {
+            toolCallId: "prompt-tool-1",
+            name: "general-purpose",
+            arguments: {
+              prompt: "Research the dependency graph",
+            },
+          },
+        ],
+      },
+    } as AgentEvent<"message.complete">);
+
+    client.emit("subagent.start" as EventType, {
+      type: "subagent.start",
+      sessionId: session.id,
+      timestamp: Date.now(),
+      data: {
+        subagentId: "sub-prompt-1",
+        subagentType: "general-purpose",
+        task: "General purpose agent",
+        toolCallId: "prompt-tool-1",
+      },
+    } as AgentEvent<"subagent.start">);
+
+    await streamPromise;
+
+    const agentStartEvents = events.filter((e) => e.type === "stream.agent.start");
+    expect(agentStartEvents.length).toBe(1);
+    expect(agentStartEvents[0].data.task).toBe("Research the dependency graph");
+  });
+
+  test("extracts isBackground from run_in_background argument", async () => {
+    const events = collectEvents(bus);
+
+    const chunks: AgentMessage[] = [{ type: "text", content: "done" }];
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream);
+
+    const streamPromise = adapter.startStreaming(session, "test", {
+      runId: 502,
+      messageId: "msg-bg",
+      knownAgentNames: ["general-purpose"],
+    });
+
+    client.emit("message.complete" as EventType, {
+      type: "message.complete",
+      sessionId: session.id,
+      timestamp: Date.now(),
+      data: {
+        toolRequests: [
+          {
+            toolCallId: "bg-tool-1",
+            name: "general-purpose",
+            arguments: {
+              prompt: "Background research task",
+              run_in_background: true,
+            },
+          },
+        ],
+      },
+    } as AgentEvent<"message.complete">);
+
+    client.emit("subagent.start" as EventType, {
+      type: "subagent.start",
+      sessionId: session.id,
+      timestamp: Date.now(),
+      data: {
+        subagentId: "sub-bg-1",
+        subagentType: "general-purpose",
+        task: "General purpose agent",
+        toolCallId: "bg-tool-1",
+      },
+    } as AgentEvent<"subagent.start">);
+
+    await streamPromise;
+
+    const agentStartEvents = events.filter((e) => e.type === "stream.agent.start");
+    expect(agentStartEvents.length).toBe(1);
+    expect(agentStartEvents[0].data.isBackground).toBe(true);
+    expect(agentStartEvents[0].data.task).toBe("Background research task");
+  });
+
+  test("full sub-agent lifecycle with agent-named tool", async () => {
+    const events = collectEvents(bus);
+
+    const chunks: AgentMessage[] = [{ type: "text", content: "done" }];
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream);
+
+    const streamPromise = adapter.startStreaming(session, "test", {
+      runId: 503,
+      messageId: "msg-lifecycle",
+      knownAgentNames: ["codebase-analyzer"],
+    });
+
+    // 1. Parent message.complete with agent-named tool request
+    client.emit("message.complete" as EventType, {
+      type: "message.complete",
+      sessionId: session.id,
+      timestamp: Date.now(),
+      data: {
+        toolRequests: [
+          {
+            toolCallId: "lifecycle-tool-1",
+            name: "codebase-analyzer",
+            arguments: {
+              prompt: "Check types",
+              subagent_type: "codebase-analyzer",
+            },
+          },
+        ],
+      },
+    } as AgentEvent<"message.complete">);
+
+    // 2. subagent.start
+    client.emit("subagent.start" as EventType, {
+      type: "subagent.start",
+      sessionId: session.id,
+      timestamp: Date.now(),
+      data: {
+        subagentId: "lifecycle-tool-1",
+        subagentType: "codebase-analyzer",
+        task: "Codebase analyzer agent",
+        toolCallId: "lifecycle-tool-1",
+      },
+    } as AgentEvent<"subagent.start">);
+
+    // 3. Sub-agent's inner message.complete with tool requests
+    //    (carries parentToolCallId — adapter must skip this)
+    client.emit("message.complete" as EventType, {
+      type: "message.complete",
+      sessionId: session.id,
+      timestamp: Date.now(),
+      data: {
+        parentToolCallId: "lifecycle-tool-1",
+        toolRequests: [
+          {
+            toolCallId: "inner-tool-1",
+            name: "Grep",
+            arguments: { pattern: "interface" },
+          },
+        ],
+      },
+    } as AgentEvent<"message.complete">);
+
+    // 4. tool.start inside sub-agent (has parentId = subagentId)
+    client.emit("tool.start" as EventType, {
+      type: "tool.start",
+      sessionId: session.id,
+      timestamp: Date.now(),
+      data: {
+        toolName: "Grep",
+        toolInput: { pattern: "interface" },
+        toolCallId: "inner-tool-1",
+        parentId: "lifecycle-tool-1",
+      },
+    } as AgentEvent<"tool.start">);
+
+    // 5. tool.complete inside sub-agent
+    client.emit("tool.complete" as EventType, {
+      type: "tool.complete",
+      sessionId: session.id,
+      timestamp: Date.now(),
+      data: {
+        toolName: "Grep",
+        toolResult: "found 5 matches",
+        success: true,
+        toolCallId: "inner-tool-1",
+        parentId: "lifecycle-tool-1",
+      },
+    } as AgentEvent<"tool.complete">);
+
+    // 6. subagent.complete
+    client.emit("subagent.complete" as EventType, {
+      type: "subagent.complete",
+      sessionId: session.id,
+      timestamp: Date.now(),
+      data: {
+        subagentId: "lifecycle-tool-1",
+        success: true,
+        result: "Types look good",
+      },
+    } as AgentEvent<"subagent.complete">);
+
+    await streamPromise;
+
+    // Verify tool.start was emitted: 1 for codebase-analyzer (parent) + 1 for Grep (inner)
+    const toolStartEvents = events.filter((e) => e.type === "stream.tool.start");
+    expect(toolStartEvents.length).toBe(2);
+
+    // The inner Grep tool start should have parentAgentId set
+    const grepToolStart = toolStartEvents.find((e) => e.data.toolName === "Grep");
+    expect(grepToolStart).toBeDefined();
+    expect(grepToolStart!.data.parentAgentId).toBe("lifecycle-tool-1");
+
+    // Verify agent lifecycle
+    const agentStartEvents = events.filter((e) => e.type === "stream.agent.start");
+    expect(agentStartEvents.length).toBe(1);
+    expect(agentStartEvents[0].data.task).toBe("Check types");
+
+    // Verify tool count propagated via stream.agent.update
+    const agentUpdateEvents = events.filter((e) => e.type === "stream.agent.update");
+    expect(agentUpdateEvents.length).toBeGreaterThanOrEqual(1);
+    // After onToolStart, toolUses should be 1
+    const lastUpdate = agentUpdateEvents[agentUpdateEvents.length - 1];
+    expect(lastUpdate.data.toolUses).toBeGreaterThanOrEqual(1);
+
+    const agentCompleteEvents = events.filter((e) => e.type === "stream.agent.complete");
+    expect(agentCompleteEvents.length).toBe(1);
+    expect(agentCompleteEvents[0].data.success).toBe(true);
+  });
+
+  test("nested sub-agent (spawned by another sub-agent) is suppressed from tree", async () => {
+    const events = collectEvents(bus);
+
+    const chunks: AgentMessage[] = [{ type: "text", content: "done" }];
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream);
+
+    const streamPromise = adapter.startStreaming(session, "test", {
+      runId: 505,
+      messageId: "msg-nested",
+      knownAgentNames: ["codebase-analyzer"],
+    });
+
+    // 1. Parent message.complete spawns codebase-analyzer
+    client.emit("message.complete" as EventType, {
+      type: "message.complete",
+      sessionId: session.id,
+      timestamp: Date.now(),
+      data: {
+        toolRequests: [
+          {
+            toolCallId: "tc-outer",
+            name: "codebase-analyzer",
+            arguments: { prompt: "Analyze repo" },
+          },
+        ],
+      },
+    } as AgentEvent<"message.complete">);
+
+    // 2. subagent.start for codebase-analyzer (top-level)
+    client.emit("subagent.start" as EventType, {
+      type: "subagent.start",
+      sessionId: session.id,
+      timestamp: Date.now(),
+      data: {
+        subagentId: "tc-outer",
+        subagentType: "codebase-analyzer",
+        task: "Analyze repo",
+        toolCallId: "tc-outer",
+      },
+    } as AgentEvent<"subagent.start">);
+
+    // 3. codebase-analyzer calls Task tool (inner tool.start with parentId)
+    client.emit("tool.start" as EventType, {
+      type: "tool.start",
+      sessionId: session.id,
+      timestamp: Date.now(),
+      data: {
+        toolName: "task",
+        toolInput: { prompt: "Explore codebase" },
+        toolCallId: "tc-inner",
+        parentId: "tc-outer",
+      },
+    } as AgentEvent<"tool.start">);
+
+    // 4. subagent.start for explore (NESTED — spawned by codebase-analyzer)
+    client.emit("subagent.start" as EventType, {
+      type: "subagent.start",
+      sessionId: session.id,
+      timestamp: Date.now(),
+      data: {
+        subagentId: "tc-inner",
+        subagentType: "explore",
+        task: "Fast codebase exploration",
+        toolCallId: "tc-inner",
+      },
+    } as AgentEvent<"subagent.start">);
+
+    // 5. nested lifecycle events should also be suppressed
+    client.emit("subagent.update" as EventType, {
+      type: "subagent.update",
+      sessionId: session.id,
+      timestamp: Date.now(),
+      data: {
+        subagentId: "tc-inner",
+        currentTool: "grep",
+        toolUses: 1,
+      },
+    } as AgentEvent<"subagent.update">);
+
+    client.emit("subagent.complete" as EventType, {
+      type: "subagent.complete",
+      sessionId: session.id,
+      timestamp: Date.now(),
+      data: {
+        subagentId: "tc-inner",
+        success: true,
+        result: "nested done",
+      },
+    } as AgentEvent<"subagent.complete">);
+
+    await streamPromise;
+
+    // Only the top-level agent (codebase-analyzer) should appear
+    const agentStartEvents = events.filter((e) => e.type === "stream.agent.start");
+    expect(agentStartEvents.length).toBe(1);
+    expect(agentStartEvents[0].data.agentType).toBe("codebase-analyzer");
+
+    // The nested explore agent should NOT appear
+    const exploreEvents = agentStartEvents.filter((e) => e.data.agentType === "explore");
+    expect(exploreEvents.length).toBe(0);
+
+    const nestedAgentUpdates = events.filter(
+      (e) => e.type === "stream.agent.update" && e.data.agentId === "tc-inner",
+    );
+    expect(nestedAgentUpdates.length).toBe(0);
+
+    const nestedAgentCompletes = events.filter(
+      (e) => e.type === "stream.agent.complete" && e.data.agentId === "tc-inner",
+    );
+    expect(nestedAgentCompletes.length).toBe(0);
+  });
+
+  test("sub-agent message.complete with parentToolCallId is skipped", async () => {
+    const events = collectEvents(bus);
+
+    const chunks: AgentMessage[] = [{ type: "text", content: "done" }];
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream);
+
+    const streamPromise = adapter.startStreaming(session, "test", {
+      runId: 504,
+      messageId: "msg-skip-child",
+      knownAgentNames: ["general-purpose"],
+    });
+
+    // Sub-agent message.complete with parentToolCallId should be skipped
+    client.emit("message.complete" as EventType, {
+      type: "message.complete",
+      sessionId: session.id,
+      timestamp: Date.now(),
+      data: {
+        parentToolCallId: "parent-task-1",
+        toolRequests: [
+          {
+            toolCallId: "child-tool-1",
+            name: "Read",
+            arguments: { file_path: "test.ts" },
+          },
+        ],
+      },
+    } as AgentEvent<"message.complete">);
+
+    // This message.complete without parentToolCallId (parent agent) should be processed
+    client.emit("message.complete" as EventType, {
+      type: "message.complete",
+      sessionId: session.id,
+      timestamp: Date.now(),
+      data: {},
+    } as AgentEvent<"message.complete">);
+
+    await streamPromise;
+
+    // The child message.complete's tool request should NOT have been emitted
+    const toolStarts = events.filter((e) => e.type === "stream.tool.start");
+    expect(toolStarts.length).toBe(0);
+
+    // The parent message.complete should NOT have emitted stream.text.complete
+    // because no text was accumulated (no message.delta events were sent)
+    const textCompletes = events.filter((e) => e.type === "stream.text.complete");
+    expect(textCompletes.length).toBe(0);
+  });
+
+  test("maps subagent.update events and sub-agent message deltas", async () => {
+    const events = collectEvents(bus);
+
+    const chunks: AgentMessage[] = [{ type: "text", content: "done" }];
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream);
+
+    const streamPromise = adapter.startStreaming(session, "test", {
+      runId: 510,
+      messageId: "msg-subagent-delta",
+      knownAgentNames: ["codebase-analyzer"],
+    });
+
+    client.emit("subagent.start" as EventType, {
+      type: "subagent.start",
+      sessionId: session.id,
+      timestamp: Date.now(),
+      data: {
+        subagentId: "agent-sub-1",
+        subagentType: "codebase-analyzer",
+        toolCallId: "tool-call-agent-1",
+      },
+    } as AgentEvent<"subagent.start">);
+
+    client.emit("subagent.update" as EventType, {
+      type: "subagent.update",
+      sessionId: session.id,
+      timestamp: Date.now(),
+      data: {
+        subagentId: "agent-sub-1",
+        currentTool: "grep",
+        toolUses: 2,
+      },
+    } as AgentEvent<"subagent.update">);
+
+    client.emit("message.delta" as EventType, {
+      type: "message.delta",
+      sessionId: session.id,
+      timestamp: Date.now(),
+      data: {
+        delta: "child chunk",
+        contentType: "text",
+        parentToolCallId: "tool-call-agent-1",
+      },
+    } as AgentEvent<"message.delta">);
+
+    await streamPromise;
+
+    expect(events.some((e) => e.type === "stream.agent.update" && e.data.agentId === "agent-sub-1")).toBe(true);
+    expect(
+      events.some(
+        (e) => e.type === "stream.text.delta"
+          && e.data.delta === "child chunk"
+          && e.data.agentId === "agent-sub-1",
+      ),
+    ).toBe(true);
+  });
+
+});
+
+// ============================================================================
+// WorkflowEventAdapter Tests
+// ============================================================================
+
+describe("WorkflowEventAdapter", () => {
+  let bus: EventBus;
+  let adapter: WorkflowEventAdapter;
+
+  beforeEach(() => {
+    bus = new EventBus();
+    adapter = new WorkflowEventAdapter(bus, "workflow-session-1", 1);
+  });
+
+  test("publishStepStart() publishes workflow.step.start event", () => {
+    const events = collectEvents(bus);
+
+    adapter.publishStepStart("wf-001", "analyze-code", "node-1");
+
+    expect(events.length).toBe(1);
+    expect(events[0].type).toBe("workflow.step.start");
+    expect(events[0].sessionId).toBe("workflow-session-1");
+    expect(events[0].runId).toBe(1);
+    expect(events[0].data.workflowId).toBe("wf-001");
+    expect(events[0].data.nodeId).toBe("node-1");
+    expect(events[0].data.nodeName).toBe("analyze-code");
+  });
+
+  test("publishStepComplete() publishes workflow.step.complete with status", () => {
+    const events = collectEvents(bus);
+
+    adapter.publishStepComplete("wf-001", "analyze-code", "node-1", "success", { output: "done" });
+
+    expect(events.length).toBe(1);
+    expect(events[0].type).toBe("workflow.step.complete");
+    expect(events[0].data.workflowId).toBe("wf-001");
+    expect(events[0].data.nodeId).toBe("node-1");
+    expect(events[0].data.nodeName).toBe("analyze-code");
+    expect(events[0].data.status).toBe("success");
+    expect(events[0].data.result).toEqual({ output: "done" });
+    expect(events[0].runId).toBe(1);
+  });
+
+  test("publishStepComplete() defaults to success status", () => {
+    const events = collectEvents(bus);
+
+    adapter.publishStepComplete("wf-001", "step", "node-1");
+
+    expect(events[0].data.nodeName).toBe("step");
+    expect(events[0].data.status).toBe("success");
+  });
+
+  test("publishTaskUpdate() publishes workflow.task.update with tasks", () => {
+    const events = collectEvents(bus);
+
+    const tasks = [
+      { id: "t1", title: "First task", status: "complete" },
+      { id: "t2", title: "Second task", status: "in_progress" },
+      { id: "t3", title: "Third task", status: "pending" },
+    ];
+
+    adapter.publishTaskUpdate("wf-001", tasks);
+
+    expect(events.length).toBe(1);
+    expect(events[0].type).toBe("workflow.task.update");
+    expect(events[0].data.workflowId).toBe("wf-001");
+    expect(events[0].data.tasks).toEqual(tasks);
+    expect(events[0].data.tasks.length).toBe(3);
+  });
+
+  test("publishAgentStart() publishes stream.agent.start event", () => {
+    const events = collectEvents(bus);
+
+    adapter.publishAgentStart("agent-001", "explore", "Find relevant files", false);
+
+    expect(events.length).toBe(1);
+    expect(events[0].type).toBe("stream.agent.start");
+    expect(events[0].data.agentId).toBe("agent-001");
+    expect(events[0].data.agentType).toBe("explore");
+    expect(events[0].data.task).toBe("Find relevant files");
+    expect(events[0].data.isBackground).toBe(false);
+    expect(events[0].runId).toBe(1);
+  });
+
+  test("publishAgentStart() defaults isBackground to false", () => {
+    const events = collectEvents(bus);
+
+    adapter.publishAgentStart("agent-001", "task", "Run tests");
+
+    expect(events[0].data.isBackground).toBe(false);
+  });
+
+  test("publishAgentUpdate() publishes stream.agent.update event", () => {
+    const events = collectEvents(bus);
+
+    adapter.publishAgentUpdate("agent-001", "bash", 5);
+
+    expect(events.length).toBe(1);
+    expect(events[0].type).toBe("stream.agent.update");
+    expect(events[0].data.agentId).toBe("agent-001");
+    expect(events[0].data.currentTool).toBe("bash");
+    expect(events[0].data.toolUses).toBe(5);
+  });
+
+  test("publishAgentComplete() publishes stream.agent.complete event", () => {
+    const events = collectEvents(bus);
+
+    adapter.publishAgentComplete("agent-001", true, "Found 3 files");
+
+    expect(events.length).toBe(1);
+    expect(events[0].type).toBe("stream.agent.complete");
+    expect(events[0].data.agentId).toBe("agent-001");
+    expect(events[0].data.success).toBe(true);
+    expect(events[0].data.result).toBe("Found 3 files");
+    expect(events[0].data.error).toBeUndefined();
+  });
+
+  test("publishAgentComplete() with error", () => {
+    const events = collectEvents(bus);
+
+    adapter.publishAgentComplete("agent-001", false, undefined, "Agent timeout");
+
+    expect(events[0].data.success).toBe(false);
+    expect(events[0].data.error).toBe("Agent timeout");
+    expect(events[0].data.result).toBeUndefined();
+  });
+
+  test("all events use correct sessionId and runId", () => {
+    const events = collectEvents(bus);
+
+    adapter.publishStepStart("wf", "step", "n1");
+    adapter.publishAgentStart("a1", "task", "do stuff");
+    adapter.publishAgentUpdate("a1", "bash");
+    adapter.publishAgentComplete("a1", true);
+    adapter.publishStepComplete("wf", "step", "n1");
+    adapter.publishTaskUpdate("wf", [{ id: "t1", title: "T", status: "done" }]);
+
+    expect(events.length).toBe(6);
+    for (const event of events) {
+      expect(event.sessionId).toBe("workflow-session-1");
+      expect(event.runId).toBe(1);
+    }
+  });
+});
diff --git a/src/events/adapters/claude-adapter.ts b/src/events/adapters/claude-adapter.ts
new file mode 100644
index 0000000000..568547cdcd
--- /dev/null
+++ b/src/events/adapters/claude-adapter.ts
@@ -0,0 +1,2004 @@
+/**
+ * Claude SDK Stream Adapter
+ *
+ * Consumes streaming events from the Claude Agent SDK's AsyncIterable stream
+ * and publishes them to the event bus as normalized BusEvents.
+ *
+ * Key responsibilities:
+ * - Consume session.stream() AsyncIterable from Claude SDK
+ * - Map Claude SDK AgentMessage types to BusEvent types
+ * - Handle text deltas, thinking deltas, and thinking completion
+ * - Support cancellation via AbortController
+ * - Publish events directly to the event bus (no batching)
+ *
+ * Event mapping:
+ * - AgentMessage (type: "text") → stream.text.delta
+ * - AgentMessage (type: "thinking") with content → stream.thinking.delta
+ * - AgentMessage (type: "thinking") with metadata.streamingStats → stream.thinking.complete
+ * - Stream completion → stream.text.complete
+ *
+ * All SDK event types (text, thinking, tool, agent) are handled within the adapter.
+ *
+ * Usage:
+ * ```typescript
+ * const adapter = new ClaudeStreamAdapter(eventBus, sessionId);
+ * await adapter.startStreaming(session, message, { runId, messageId });
+ * adapter.dispose(); // Cancel and cleanup
+ * ```
+ */
+
+import type { EventBus } from "../event-bus.ts";
+import type { BusEvent } from "../bus-events.ts";
+import type {
+  WorkflowRuntimeFeatureFlags,
+  WorkflowRuntimeFeatureFlagOverrides,
+} from "../../workflows/runtime-contracts.ts";
+import {
+  DEFAULT_WORKFLOW_RUNTIME_FEATURE_FLAGS,
+  resolveWorkflowRuntimeFeatureFlags,
+} from "../../workflows/runtime-contracts.ts";
+import type {
+  SDKStreamAdapter,
+  StreamAdapterOptions,
+} from "./types.ts";
+import type {
+  CodingAgentClient,
+  Session,
+  AgentMessage,
+  EventHandler,
+  SessionIdleEventData,
+  SessionErrorEventData,
+  SessionInfoEventData,
+  SessionWarningEventData,
+  SessionTitleChangedEventData,
+  SessionTruncationEventData,
+  SessionCompactionEventData,
+  ToolStartEventData,
+  ToolCompleteEventData,
+  ToolPartialResultEventData,
+  SubagentStartEventData,
+  SubagentCompleteEventData,
+  SubagentUpdateEventData,
+  PermissionRequestedEventData,
+  HumanInputRequiredEventData,
+  SkillInvokedEventData,
+  ReasoningDeltaEventData,
+  ReasoningCompleteEventData,
+  TurnStartEventData,
+  TurnEndEventData,
+} from "../../sdk/types.ts";
+import {
+  createTurnMetadataState,
+  normalizeAgentTaskMetadata,
+  normalizeTurnEndMetadata,
+  normalizeTurnStartId,
+  resetTurnMetadataState,
+} from "./task-turn-normalization.ts";
+import { SubagentToolTracker } from "./subagent-tool-tracker.ts";
+import { classifyError, computeDelay, retrySleep, DEFAULT_MAX_RETRIES } from "./retry.ts";
+
+const DEFAULT_SUBAGENT_TASK_LABEL = "sub-agent task";
+
+function isGenericSubagentTaskLabel(task: string | undefined): boolean {
+  const normalized = (task ?? "").trim().toLowerCase();
+  return normalized === "" || normalized === DEFAULT_SUBAGENT_TASK_LABEL || normalized === "subagent task";
+}
+
+function resolveAgentOnlyTaskLabel(message: string, agentName: string): string {
+  const trimmed = message.trim();
+  if (trimmed.length === 0) {
+    return agentName;
+  }
+  return trimmed;
+}
+
+/**
+ * Stream adapter for Claude Agent SDK.
+ *
+ * Consumes the AsyncIterable stream from session.stream() and publishes
+ * normalized BusEvents to the event bus.
+ */
+export class ClaudeStreamAdapter implements SDKStreamAdapter {
+  private bus: EventBus;
+  private sessionId: string;
+  private client?: CodingAgentClient;
+  private abortController: AbortController | null = null;
+  private textAccumulator = "";
+  private unsubscribers: Array<() => void> = [];
+  /** Tracks thinking source start times for duration computation */
+  private thinkingStartTimes = new Map<string, number>();
+  private pendingToolIdsByName = new Map<string, string[]>();
+  private toolCorrelationAliases = new Map<string, string>();
+  /** Maps task-tool correlation ID -> task metadata for subagent label hydration */
+  private taskToolMetadata = new Map<string, { description: string; isBackground: boolean }>();
+  /** Ordered task tool IDs awaiting subagent.start correlation fallback */
+  private pendingTaskToolCorrelationIds: string[] = [];
+  /** Buffers tool events that arrive before parent subagent registration */
+  private earlyToolEvents = new Map<string, Array<{ toolName: string }>>();
+  /** Active native sub-agent IDs for fallback attribution when tool hooks are unscoped */
+  private activeSubagentIds = new Set<string>();
+  /** Active sub-agent background mode by agent ID */
+  private activeSubagentBackgroundById = new Map<string, boolean>();
+  /** Sticky fallback for unscoped background tool events */
+  private currentBackgroundAttributionAgentId: string | null = null;
+  /** Active sub-agent tool contexts keyed by tool correlation ID */
+  private activeSubagentToolsById = new Map<string, { parentAgentId: string; toolName: string }>();
+  /** Sessions owned by this run (parent + discovered child sessions) */
+  private ownedSessionIds = new Set<string>();
+  /** Maps sub-agent child session IDs to agent IDs */
+  private subagentSessionToAgentId = new Map<string, string>();
+  /** Maps task-tool correlation ID -> subagentId */
+  private toolUseIdToSubagentId = new Map<string, string>();
+  /** Synthetic foreground agent context used for Claude @agent agent-only streams */
+  private syntheticForegroundAgent:
+    | {
+        id: string;
+        name: string;
+        task: string;
+        started: boolean;
+        completed: boolean;
+        sawNativeSubagentStart: boolean;
+      }
+    | null = null;
+  private syntheticToolCounter = 0;
+  private accumulatedOutputTokens = 0;
+  private subagentTracker: SubagentToolTracker | null = null;
+  /** Prefer client hook tool events over stream-chunk tool events when available. */
+  private preferClientToolHooks = false;
+  private runtimeFeatureFlags: WorkflowRuntimeFeatureFlags = {
+    ...DEFAULT_WORKFLOW_RUNTIME_FEATURE_FLAGS,
+  };
+  private turnMetadataState = createTurnMetadataState();
+
+  /**
+   * Create a new Claude stream adapter.
+   *
+   * @param bus - The event bus to publish events to
+   * @param sessionId - Session ID for event correlation
+   */
+  constructor(bus: EventBus, sessionId: string, client?: CodingAgentClient) {
+    this.bus = bus;
+    this.sessionId = sessionId;
+    this.client = client;
+  }
+
+  /**
+   * Start consuming the Claude SDK stream and publishing BusEvents.
+   *
+   * This method will:
+   * 1. Iterate over the AsyncIterable stream from session.stream()
+   * 2. Map each AgentMessage to the appropriate BusEvent
+   * 3. Publish events directly to the bus
+   * 4. Complete with a stream.text.complete event
+   *
+   * @param session - Active Claude SDK session
+   * @param message - User message to stream
+   * @param options - Stream options (runId, messageId, agent)
+   */
+  async startStreaming(
+    session: Session,
+    message: string,
+    options: StreamAdapterOptions,
+  ): Promise<void> {
+    const { runId, messageId, agent, runtimeFeatureFlags } = options;
+
+    // Clean up any existing subscriptions from a previous startStreaming() call
+    // to prevent subscription accumulation on re-entry without dispose()
+    this.cleanupSubscriptions();
+
+    // Create abort controller for cancellation
+    this.abortController = new AbortController();
+
+    // Reset text accumulator
+    this.textAccumulator = "";
+    this.thinkingStartTimes.clear();
+    this.pendingToolIdsByName.clear();
+    this.toolCorrelationAliases.clear();
+    this.taskToolMetadata.clear();
+    this.pendingTaskToolCorrelationIds = [];
+    this.earlyToolEvents.clear();
+    this.activeSubagentIds.clear();
+    this.activeSubagentBackgroundById.clear();
+    this.currentBackgroundAttributionAgentId = null;
+    this.activeSubagentToolsById.clear();
+    this.ownedSessionIds = new Set([this.sessionId]);
+    this.subagentSessionToAgentId.clear();
+    this.toolUseIdToSubagentId.clear();
+    this.syntheticForegroundAgent = agent
+      ? {
+          id: `agent-only-${messageId}`,
+          name: agent,
+          task: resolveAgentOnlyTaskLabel(message, agent),
+          started: false,
+          completed: false,
+          sawNativeSubagentStart: false,
+        }
+      : null;
+    this.syntheticToolCounter = 0;
+    this.accumulatedOutputTokens = 0;
+    this.subagentTracker = new SubagentToolTracker(this.bus, this.sessionId, runId);
+    this.preferClientToolHooks = false;
+    this.runtimeFeatureFlags = this.resolveRuntimeFeatureFlags(runtimeFeatureFlags);
+    resetTurnMetadataState(this.turnMetadataState);
+
+    this.publishSessionStart(runId);
+    this.publishSyntheticAgentStart(runId);
+
+    const client = this.client ?? (session as Session & { __client?: CodingAgentClient }).__client;
+    if (client && typeof client.on === "function") {
+      this.preferClientToolHooks = true;
+      const unsubToolStart = client.on(
+        "tool.start",
+        this.createToolStartHandler(runId),
+      );
+      this.unsubscribers.push(unsubToolStart);
+
+      const unsubToolComplete = client.on(
+        "tool.complete",
+        this.createToolCompleteHandler(runId),
+      );
+      this.unsubscribers.push(unsubToolComplete);
+
+      // Subscribe to subagent lifecycle events from SDK hooks
+      const unsubSubagentStart = client.on(
+        "subagent.start",
+        this.createSubagentStartHandler(runId),
+      );
+      this.unsubscribers.push(unsubSubagentStart);
+
+      const unsubSubagentComplete = client.on(
+        "subagent.complete",
+        this.createSubagentCompleteHandler(runId),
+      );
+      this.unsubscribers.push(unsubSubagentComplete);
+
+      // Subscribe to subagent.update events (tool progress for sub-agents)
+      const unsubAgentUpdate = client.on(
+        "subagent.update",
+        this.createSubagentUpdateHandler(runId),
+      );
+      this.unsubscribers.push(unsubAgentUpdate);
+
+      const unsubIdle = client.on(
+        "session.idle",
+        this.createSessionIdleHandler(runId),
+      );
+      this.unsubscribers.push(unsubIdle);
+
+      const unsubSessionError = client.on(
+        "session.error",
+        this.createSessionErrorHandler(runId),
+      );
+      this.unsubscribers.push(unsubSessionError);
+
+      const unsubUsage = client.on(
+        "usage",
+        this.createUsageHandler(runId),
+      );
+      this.unsubscribers.push(unsubUsage);
+
+      // Subscribe to permission request events (HITL)
+      const unsubPermission = client.on(
+        "permission.requested",
+        this.createPermissionRequestedHandler(runId),
+      );
+      this.unsubscribers.push(unsubPermission);
+
+      const unsubHumanInput = client.on(
+        "human_input_required",
+        this.createHumanInputRequiredHandler(runId),
+      );
+      this.unsubscribers.push(unsubHumanInput);
+
+      const unsubSkillInvoked = client.on(
+        "skill.invoked",
+        this.createSkillInvokedHandler(runId),
+      );
+      this.unsubscribers.push(unsubSkillInvoked);
+
+      const unsubReasoningDelta = client.on(
+        "reasoning.delta",
+        this.createReasoningDeltaHandler(runId, messageId),
+      );
+      this.unsubscribers.push(unsubReasoningDelta);
+
+      const unsubReasoningComplete = client.on(
+        "reasoning.complete",
+        this.createReasoningCompleteHandler(runId),
+      );
+      this.unsubscribers.push(unsubReasoningComplete);
+
+      const unsubTurnStart = client.on(
+        "turn.start",
+        this.createTurnStartHandler(runId),
+      );
+      this.unsubscribers.push(unsubTurnStart);
+
+      const unsubTurnEnd = client.on(
+        "turn.end",
+        this.createTurnEndHandler(runId),
+      );
+      this.unsubscribers.push(unsubTurnEnd);
+
+      const unsubToolPartialResult = client.on(
+        "tool.partial_result",
+        this.createToolPartialResultHandler(runId),
+      );
+      this.unsubscribers.push(unsubToolPartialResult);
+
+      const unsubSessionInfo = client.on(
+        "session.info",
+        this.createSessionInfoHandler(runId),
+      );
+      this.unsubscribers.push(unsubSessionInfo);
+
+      const unsubSessionWarning = client.on(
+        "session.warning",
+        this.createSessionWarningHandler(runId),
+      );
+      this.unsubscribers.push(unsubSessionWarning);
+
+      const unsubSessionTitleChanged = client.on(
+        "session.title_changed",
+        this.createSessionTitleChangedHandler(runId),
+      );
+      this.unsubscribers.push(unsubSessionTitleChanged);
+
+      const unsubSessionTruncation = client.on(
+        "session.truncation",
+        this.createSessionTruncationHandler(runId),
+      );
+      this.unsubscribers.push(unsubSessionTruncation);
+
+      const unsubSessionCompaction = client.on(
+        "session.compaction",
+        this.createSessionCompactionHandler(runId),
+      );
+      this.unsubscribers.push(unsubSessionCompaction);
+    }
+
+    try {
+      // Retry loop for transient failures (429, 503, ECONNRESET, etc.)
+      let lastError: unknown = null;
+      for (let attempt = 1; attempt <= DEFAULT_MAX_RETRIES; attempt++) {
+        try {
+          // Start streaming from the Claude SDK
+          const stream = session.stream(message, agent ? { agent } : undefined);
+
+          // Iterate over the AsyncIterable stream
+          for await (const chunk of stream) {
+            // Check for cancellation
+            if (this.abortController.signal.aborted) {
+              break;
+            }
+
+            this.processStreamChunk(chunk, runId, messageId);
+          }
+
+          // Publish stream.text.complete event if we accumulated any text
+          if (this.textAccumulator.length > 0) {
+            this.publishTextComplete(runId, messageId);
+          }
+          this.publishSyntheticAgentComplete(runId, true);
+
+          // Stream completed successfully — exit retry loop
+          lastError = null;
+          break;
+        } catch (error) {
+          lastError = error;
+
+          // Don't retry aborted requests
+          if (this.abortController?.signal.aborted) break;
+
+          const classified = classifyError(error);
+          if (!classified.isRetryable || attempt >= DEFAULT_MAX_RETRIES) break;
+
+          const delay = computeDelay(attempt, classified);
+          const retryEvent: BusEvent<"stream.session.retry"> = {
+            type: "stream.session.retry",
+            sessionId: this.sessionId,
+            runId,
+            timestamp: Date.now(),
+            data: {
+              attempt,
+              delay,
+              message: `${classified.message} — retrying in ${Math.ceil(delay / 1000)}s`,
+              nextRetryAt: Date.now() + delay,
+            },
+          };
+          this.bus.publish(retryEvent);
+
+          // Reset accumulated state for retry
+          this.textAccumulator = "";
+
+          await retrySleep(delay, this.abortController.signal);
+        }
+      }
+
+      // If we exhausted retries or hit a non-retryable error, rethrow
+      if (lastError) throw lastError;
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      // Handle stream errors
+      if (this.abortController && !this.abortController.signal.aborted) {
+        this.publishSessionError(runId, error);
+        // Publish session.idle after error so the UI can finalize
+        // (matches OpenCode adapter pattern for consistent state transitions)
+        const idleEvent: BusEvent<"stream.session.idle"> = {
+          type: "stream.session.idle",
+          sessionId: this.sessionId,
+          runId,
+          timestamp: Date.now(),
+          data: { reason: "error" },
+        };
+        this.bus.publish(idleEvent);
+      }
+      this.publishSyntheticAgentComplete(runId, false, errorMessage);
+    } finally {
+      if (this.abortController?.signal.aborted) {
+        this.publishSyntheticAgentComplete(runId, false, "Tool execution aborted");
+      }
+      // Force-complete any tools still pending/running — prevents orphaned tool state
+      this.cleanupOrphanedTools(runId);
+      // Keep subscriptions until dispose() so delayed hook events can complete tools.
+    }
+  }
+
+  /**
+   * Process a single chunk from the Claude stream.
+   *
+   * Maps AgentMessage to the appropriate BusEvent based on message type.
+   */
+  private processStreamChunk(
+    chunk: AgentMessage,
+    runId: number,
+    messageId: string,
+  ): void {
+    // Handle text deltas
+    if (chunk.type === "text" && typeof chunk.content === "string") {
+      const delta = chunk.content;
+      const metadata = chunk.metadata as Record<string, unknown> | undefined;
+      const parentToolCallId = this.resolveToolCorrelationId(
+        this.asString(
+          metadata?.parentToolCallId
+          ?? metadata?.parent_tool_call_id
+          ?? metadata?.parentToolUseId
+          ?? metadata?.parent_tool_use_id,
+        ),
+      );
+
+      if (parentToolCallId) {
+        const context = this.activeSubagentToolsById.get(parentToolCallId);
+        const event: BusEvent<"stream.tool.partial_result"> = {
+          type: "stream.tool.partial_result",
+          sessionId: this.sessionId,
+          runId,
+          timestamp: Date.now(),
+          data: {
+            toolCallId: parentToolCallId,
+            partialOutput: delta,
+            ...(context ? { parentAgentId: context.parentAgentId } : {}),
+          },
+        };
+        this.bus.publish(event);
+        return;
+      }
+
+      this.textAccumulator += delta;
+
+      if (delta.length > 0) {
+        const event: BusEvent<"stream.text.delta"> = {
+          type: "stream.text.delta",
+          sessionId: this.sessionId,
+          runId,
+          timestamp: Date.now(),
+          data: {
+            delta,
+            messageId,
+          },
+        };
+
+        this.bus.publish(event);
+      }
+    }
+
+    // Handle thinking deltas and completion
+    if (chunk.type === "thinking") {
+      const metadata = chunk.metadata;
+      const thinkingSourceKey = metadata?.thinkingSourceKey as string | undefined;
+      const sourceKey = thinkingSourceKey ?? "default";
+
+      // Check if this is a thinking delta (has content)
+      if (typeof chunk.content === "string" && chunk.content.length > 0) {
+        // Track start time for this thinking source
+        if (!this.thinkingStartTimes.has(sourceKey)) {
+          this.thinkingStartTimes.set(sourceKey, Date.now());
+        }
+
+        const event: BusEvent<"stream.thinking.delta"> = {
+          type: "stream.thinking.delta",
+          sessionId: this.sessionId,
+          runId,
+          timestamp: Date.now(),
+          data: {
+            delta: chunk.content,
+            sourceKey,
+            messageId,
+          },
+        };
+
+        this.bus.publish(event);
+      }
+
+      // Check if this is a thinking complete event (has streamingStats but no content)
+      const streamingStats = metadata?.streamingStats as
+        | { thinkingMs?: number; outputTokens?: number }
+        | undefined;
+      if (streamingStats?.thinkingMs !== undefined && chunk.content === "") {
+        // Prefer SDK-provided duration, fall back to computed from tracked start time
+        const startTime = this.thinkingStartTimes.get(sourceKey);
+        const durationMs = streamingStats.thinkingMs
+          ?? (startTime ? Date.now() - startTime : 0);
+        this.thinkingStartTimes.delete(sourceKey);
+
+        const event: BusEvent<"stream.thinking.complete"> = {
+          type: "stream.thinking.complete",
+          sessionId: this.sessionId,
+          runId,
+          timestamp: Date.now(),
+          data: {
+            sourceKey,
+            durationMs,
+          },
+        };
+
+        this.bus.publish(event);
+      }
+
+      // Note: streamingStats.outputTokens is NOT used for stream.usage here.
+      // Real token counts come from the client "usage" event (via createUsageHandler)
+      // to avoid double-counting.
+    }
+
+    // Handle tool_use events → stream.tool.start
+    if (chunk.type === "tool_use") {
+      if (this.preferClientToolHooks) {
+        return;
+      }
+      const chunkRecord = chunk as unknown as Record<string, unknown>;
+      const contentRecord = this.asRecord(chunkRecord.content) ?? {};
+      const metadataRecord = this.asRecord(chunk.metadata) ?? {};
+      const toolName = this.normalizeToolName(
+        contentRecord.name ?? chunkRecord.name ?? metadataRecord.toolName,
+      );
+      const explicitToolId = this.asString(
+        contentRecord.toolUseId
+          ?? contentRecord.toolUseID
+          ?? contentRecord.id
+          ?? chunkRecord.toolUseId
+          ?? chunkRecord.toolUseID
+          ?? chunkRecord.id
+          ?? metadataRecord.toolId
+          ?? metadataRecord.toolUseId
+          ?? metadataRecord.toolUseID
+          ?? metadataRecord.toolCallId,
+      );
+      const toolInput = this.asRecord(contentRecord.input ?? chunkRecord.input) ?? {};
+      const toolId = this.resolveToolStartId(explicitToolId, runId, toolName);
+      const inferredParentAgentId = this.resolveTaskOutputParentAgentId(toolName, toolInput)
+        ?? this.resolveSoleActiveSubagentId()
+        ?? this.resolveBackgroundAttributionFallbackAgentId()
+        ?? this.resolveSoleActiveSubagentToolParentAgentId();
+      if (inferredParentAgentId) {
+        this.recordActiveSubagentToolContext(
+          toolId,
+          toolName,
+          inferredParentAgentId,
+          explicitToolId,
+        );
+        if (this.subagentTracker?.hasAgent(inferredParentAgentId)) {
+          this.subagentTracker.onToolStart(inferredParentAgentId, toolName);
+        }
+        if (toolName.toLowerCase() === "taskoutput") {
+          this.currentBackgroundAttributionAgentId = inferredParentAgentId;
+        }
+      }
+
+      const event: BusEvent<"stream.tool.start"> = {
+        type: "stream.tool.start",
+        sessionId: this.sessionId,
+        runId,
+        timestamp: Date.now(),
+        data: {
+          toolId,
+          toolName,
+          toolInput,
+          sdkCorrelationId: explicitToolId ?? toolId,
+          ...(inferredParentAgentId ? { parentAgentId: inferredParentAgentId } : {}),
+        },
+      };
+      this.bus.publish(event);
+    }
+
+    // Handle tool_result events → stream.tool.complete
+    if (chunk.type === "tool_result") {
+      if (this.preferClientToolHooks) {
+        return;
+      }
+      const chunkRecord = chunk as unknown as Record<string, unknown>;
+      const content = chunkRecord.content;
+      const metadataRecord = this.asRecord(chunk.metadata) ?? {};
+      const toolName = this.normalizeToolName(
+        chunkRecord.toolName ?? metadataRecord.toolName,
+      );
+      const explicitToolId = this.asString(
+        chunkRecord.tool_use_id
+          ?? chunkRecord.toolUseId
+          ?? chunkRecord.toolUseID
+          ?? metadataRecord.toolId
+          ?? metadataRecord.toolUseId
+          ?? metadataRecord.toolUseID
+          ?? metadataRecord.toolCallId,
+      );
+      const toolId = this.resolveToolCompleteId(explicitToolId, runId, toolName);
+      const activeContext = this.resolveActiveSubagentToolContext(toolId, explicitToolId);
+      this.removeActiveSubagentToolContext(toolId, explicitToolId);
+      if (activeContext && this.subagentTracker?.hasAgent(activeContext.parentAgentId)) {
+        this.subagentTracker.onToolComplete(activeContext.parentAgentId);
+      }
+      const contentRecord = this.asRecord(content);
+      const isError = chunkRecord.is_error === true
+        || (typeof content === "object" && content !== null && "error" in content);
+      const errorValue = contentRecord?.error;
+
+      const event: BusEvent<"stream.tool.complete"> = {
+        type: "stream.tool.complete",
+        sessionId: this.sessionId,
+        runId,
+        timestamp: Date.now(),
+        data: {
+          toolId,
+          toolName,
+          toolResult: content,
+          success: !isError,
+          error: isError
+            ? (typeof errorValue === "string" ? errorValue : String(content))
+            : undefined,
+          sdkCorrelationId: explicitToolId ?? toolId,
+          ...(activeContext ? { parentAgentId: activeContext.parentAgentId } : {}),
+        },
+      };
+      this.bus.publish(event);
+    }
+
+    // Token usage from chunk.metadata.tokenUsage is handled by
+    // createUsageHandler (from client "usage" events). Do NOT emit
+    // stream.usage here to avoid emitting raw per-request values
+    // that bypass the accumulator.
+
+    // Note: Agent lifecycle events (agent_start/agent_complete) are NOT
+    // emitted as stream chunks by the Claude SDK. Sub-agent lifecycle is
+    // delivered through SubagentStart/SubagentStop hooks, which are handled
+    // by createSubagentStartHandler and createSubagentCompleteHandler via
+    // client.on("subagent.start") and client.on("subagent.complete").
+  }
+
+  private createToolStartHandler(runId: number): EventHandler<"tool.start"> {
+    return (event) => {
+      const data = event.data as ToolStartEventData;
+      const dataRecord = data as Record<string, unknown>;
+      const sdkToolUseId = this.asString(data.toolUseId ?? data.toolUseID);
+      const sdkToolCallId = this.asString(data.toolCallId);
+      const sdkCorrelationId = sdkToolUseId ?? sdkToolCallId;
+      const toolName = this.normalizeToolName(data.toolName);
+      const toolId = this.resolveToolStartId(sdkCorrelationId, runId, toolName);
+      this.registerToolCorrelationAliases(toolId, sdkToolUseId, sdkToolCallId);
+
+      // Check if this tool belongs to a sub-agent
+      const directParentAgentId = this.asString(
+        dataRecord.parentAgentId ?? dataRecord.parentId,
+      );
+      const parentToolUseId = this.resolveToolCorrelationId(
+        this.asString(
+          dataRecord.parentToolUseId
+            ?? dataRecord.parent_tool_use_id
+            ?? dataRecord.parentToolUseID
+            ?? dataRecord.parentToolCallId
+            ?? dataRecord.parent_tool_call_id
+            ?? dataRecord.parentToolCallID,
+        ),
+      );
+      const taskOutputParentAgentId = this.resolveTaskOutputParentAgentId(
+        toolName,
+        (data.toolInput ?? {}) as Record<string, unknown>,
+      );
+      if (taskOutputParentAgentId) {
+        this.currentBackgroundAttributionAgentId = taskOutputParentAgentId;
+      }
+      const sessionMappedParentAgentId = this.resolveSubagentSessionParentAgentId(event.sessionId);
+      const allowFallbackAttribution = this.isOwnedSession(event.sessionId)
+        || Boolean(directParentAgentId || parentToolUseId || sessionMappedParentAgentId);
+      const fallbackParentAgentId = allowFallbackAttribution
+        ? this.resolveSoleActiveSubagentId()
+        : undefined;
+      const fallbackBackgroundParentAgentId = allowFallbackAttribution
+        ? this.resolveBackgroundAttributionFallbackAgentId()
+        : undefined;
+      const fallbackActiveToolParentAgentId = allowFallbackAttribution
+        ? this.resolveSoleActiveSubagentToolParentAgentId()
+        : undefined;
+      const syntheticParentAgentId = event.sessionId === this.sessionId
+        ? this.getSyntheticAgentIdForAttribution()
+        : undefined;
+      const resolvedParentAgentId = directParentAgentId
+        ?? (parentToolUseId ? this.toolUseIdToSubagentId.get(parentToolUseId) : undefined)
+        ?? sessionMappedParentAgentId
+        ?? taskOutputParentAgentId
+        ?? fallbackParentAgentId;
+      const attributedWithContextParentAgentId = resolvedParentAgentId
+        ?? fallbackBackgroundParentAgentId
+        ?? fallbackActiveToolParentAgentId;
+      const finalAttributedParentAgentId = attributedWithContextParentAgentId ?? syntheticParentAgentId;
+      if (
+        !this.isOwnedSession(event.sessionId)
+        && !directParentAgentId
+        && !parentToolUseId
+        && !sessionMappedParentAgentId
+      ) {
+        return;
+      }
+
+      if (this.isTaskTool(toolName) && sdkCorrelationId) {
+        const metadata = this.extractTaskToolMetadata(data.toolInput);
+        this.taskToolMetadata.set(sdkCorrelationId, metadata);
+        this.recordPendingTaskToolCorrelationId(sdkCorrelationId);
+      }
+      if (taskOutputParentAgentId && sdkCorrelationId) {
+        this.toolUseIdToSubagentId.set(sdkCorrelationId, taskOutputParentAgentId);
+      }
+
+      // Update sub-agent tool tracker for tool count display
+      if (finalAttributedParentAgentId && this.subagentTracker?.hasAgent(finalAttributedParentAgentId)) {
+        this.recordActiveSubagentToolContext(
+          toolId,
+          toolName,
+          finalAttributedParentAgentId,
+          sdkToolUseId,
+          sdkToolCallId,
+          parentToolUseId,
+          sdkCorrelationId,
+        );
+        this.subagentTracker.onToolStart(finalAttributedParentAgentId, toolName);
+      } else if (finalAttributedParentAgentId) {
+        this.recordActiveSubagentToolContext(
+          toolId,
+          toolName,
+          finalAttributedParentAgentId,
+          sdkToolUseId,
+          sdkToolCallId,
+          parentToolUseId,
+          sdkCorrelationId,
+        );
+        const queue = this.earlyToolEvents.get(finalAttributedParentAgentId) ?? [];
+        queue.push({ toolName });
+        this.earlyToolEvents.set(finalAttributedParentAgentId, queue);
+      } else if (parentToolUseId) {
+        const queue = this.earlyToolEvents.get(parentToolUseId) ?? [];
+        queue.push({ toolName });
+        this.earlyToolEvents.set(parentToolUseId, queue);
+      }
+
+      const busEvent: BusEvent<"stream.tool.start"> = {
+        type: "stream.tool.start",
+        sessionId: this.sessionId,
+        runId,
+        timestamp: Date.now(),
+        data: {
+          toolId,
+          toolName,
+          toolInput: (data.toolInput ?? {}) as Record<string, unknown>,
+          sdkCorrelationId: sdkCorrelationId ?? toolId,
+          ...(finalAttributedParentAgentId ? { parentAgentId: finalAttributedParentAgentId } : {}),
+        },
+      };
+      this.bus.publish(busEvent);
+    };
+  }
+
+  private createToolCompleteHandler(runId: number): EventHandler<"tool.complete"> {
+    return (event) => {
+      const data = event.data as ToolCompleteEventData;
+      const dataRecord = data as Record<string, unknown>;
+      const sdkToolUseId = this.asString(data.toolUseId ?? data.toolUseID);
+      const sdkToolCallId = this.asString(data.toolCallId);
+      const sdkCorrelationId = this.resolveToolCorrelationId(
+        sdkToolUseId ?? sdkToolCallId,
+      );
+      const toolName = this.normalizeToolName(data.toolName);
+      const toolId = this.resolveToolCompleteId(sdkCorrelationId, runId, toolName);
+      const toolInput = this.asRecord((data as Record<string, unknown>).toolInput);
+      this.registerToolCorrelationAliases(toolId, sdkToolUseId, sdkToolCallId);
+      const activeToolContext = this.resolveActiveSubagentToolContext(
+        toolId,
+        sdkCorrelationId,
+        sdkToolUseId,
+        sdkToolCallId,
+      );
+      this.removeActiveSubagentToolContext(toolId, sdkCorrelationId, sdkToolUseId, sdkToolCallId);
+
+      // Check if this tool belongs to a sub-agent
+      const directParentAgentId = this.asString(
+        dataRecord.parentAgentId ?? dataRecord.parentId,
+      );
+      const parentToolUseId = this.resolveToolCorrelationId(
+        this.asString(
+          dataRecord.parentToolUseId
+            ?? dataRecord.parent_tool_use_id
+            ?? dataRecord.parentToolUseID
+            ?? dataRecord.parentToolCallId
+            ?? dataRecord.parent_tool_call_id
+            ?? dataRecord.parentToolCallID,
+        ),
+      );
+      const taskOutputParentAgentId = this.resolveTaskOutputParentAgentId(
+        toolName,
+        (toolInput ?? {}) as Record<string, unknown>,
+      );
+      if (taskOutputParentAgentId) {
+        this.currentBackgroundAttributionAgentId = taskOutputParentAgentId;
+      }
+      const sessionMappedParentAgentId = this.resolveSubagentSessionParentAgentId(event.sessionId);
+      const allowFallbackAttribution = this.isOwnedSession(event.sessionId)
+        || Boolean(directParentAgentId || parentToolUseId || sessionMappedParentAgentId);
+      const fallbackParentAgentId = allowFallbackAttribution
+        ? this.resolveSoleActiveSubagentId()
+        : undefined;
+      const fallbackBackgroundParentAgentId = allowFallbackAttribution
+        ? this.resolveBackgroundAttributionFallbackAgentId()
+        : undefined;
+      const fallbackActiveToolParentAgentId = activeToolContext?.parentAgentId
+        ?? (allowFallbackAttribution
+          ? this.resolveSoleActiveSubagentToolParentAgentId()
+          : undefined);
+      const syntheticParentAgentId = event.sessionId === this.sessionId
+        ? this.getSyntheticAgentIdForAttribution()
+        : undefined;
+      const resolvedParentAgentId = directParentAgentId
+        ?? (parentToolUseId ? this.toolUseIdToSubagentId.get(parentToolUseId) : undefined)
+        ?? sessionMappedParentAgentId
+        ?? taskOutputParentAgentId
+        ?? activeToolContext?.parentAgentId
+        ?? fallbackParentAgentId;
+      const attributedWithContextParentAgentId = resolvedParentAgentId
+        ?? fallbackBackgroundParentAgentId
+        ?? fallbackActiveToolParentAgentId;
+      const attributedParentAgentId = attributedWithContextParentAgentId ?? syntheticParentAgentId;
+      if (
+        !this.isOwnedSession(event.sessionId)
+        && !directParentAgentId
+        && !parentToolUseId
+        && !sessionMappedParentAgentId
+      ) {
+        return;
+      }
+
+      // Update sub-agent tool tracker for tool count display
+      if (attributedParentAgentId && this.subagentTracker?.hasAgent(attributedParentAgentId)) {
+        this.subagentTracker.onToolComplete(attributedParentAgentId);
+      }
+
+      const busEvent: BusEvent<"stream.tool.complete"> = {
+        type: "stream.tool.complete",
+        sessionId: this.sessionId,
+        runId,
+        timestamp: Date.now(),
+        data: {
+          toolId,
+          toolName,
+          toolInput,
+          toolResult: data.toolResult,
+          success: data.success,
+          error: data.error,
+          sdkCorrelationId: sdkCorrelationId ?? toolId,
+          ...(attributedParentAgentId ? { parentAgentId: attributedParentAgentId } : {}),
+        },
+      };
+      this.bus.publish(busEvent);
+    };
+  }
+
+  private createUsageHandler(runId: number): EventHandler<"usage"> {
+    return (event) => {
+      if (event.sessionId !== this.sessionId) {
+        return;
+      }
+
+      const data = event.data as Record<string, unknown>;
+      const inputTokens = (data.inputTokens as number) || 0;
+      const outputTokens = (data.outputTokens as number) || 0;
+      const model = data.model as string | undefined;
+
+      // Filter out diagnostics markers that carry no real token data
+      if (outputTokens <= 0 && inputTokens <= 0) {
+        return;
+      }
+
+      // Accumulate output tokens across multi-turn tool-use flows
+      this.accumulatedOutputTokens += outputTokens;
+
+      const busEvent: BusEvent<"stream.usage"> = {
+        type: "stream.usage",
+        sessionId: this.sessionId,
+        runId,
+        timestamp: Date.now(),
+        data: {
+          inputTokens,
+          outputTokens: this.accumulatedOutputTokens,
+          model,
+        },
+      };
+      this.bus.publish(busEvent);
+    };
+  }
+
+  /**
+   * Create a handler for permission.requested events from the Claude SDK.
+   * Forwards the event (including the respond callback) to the event bus.
+   */
+  private createPermissionRequestedHandler(
+    runId: number,
+  ): EventHandler<"permission.requested"> {
+    return (event) => {
+      if (event.sessionId !== this.sessionId) {
+        return;
+      }
+
+      const data = event.data as PermissionRequestedEventData;
+      const busEvent: BusEvent<"stream.permission.requested"> = {
+        type: "stream.permission.requested",
+        sessionId: this.sessionId,
+        runId,
+        timestamp: Date.now(),
+        data: {
+          requestId: data.requestId,
+          toolName: data.toolName,
+          toolInput: (data.toolInput as Record<string, unknown> | undefined),
+          question: data.question,
+          header: data.header,
+          options: data.options,
+          multiSelect: data.multiSelect,
+          respond: data.respond,
+          toolCallId: data.toolCallId,
+        },
+      };
+
+      this.bus.publish(busEvent);
+    };
+  }
+
+  private createHumanInputRequiredHandler(
+    runId: number,
+  ): EventHandler<"human_input_required"> {
+    return (event) => {
+      if (event.sessionId !== this.sessionId) return;
+      const data = event.data as HumanInputRequiredEventData;
+      this.bus.publish({
+        type: "stream.human_input_required",
+        sessionId: this.sessionId,
+        runId,
+        timestamp: Date.now(),
+        data: {
+          requestId: data.requestId,
+          question: data.question,
+          header: data.header,
+          options: data.options,
+          nodeId: data.nodeId,
+          respond: data.respond,
+        },
+      });
+    };
+  }
+
+  private createSkillInvokedHandler(
+    runId: number,
+  ): EventHandler<"skill.invoked"> {
+    return (event) => {
+      if (event.sessionId !== this.sessionId) return;
+      const data = event.data as SkillInvokedEventData;
+      this.bus.publish({
+        type: "stream.skill.invoked",
+        sessionId: this.sessionId,
+        runId,
+        timestamp: Date.now(),
+        data: {
+          skillName: data.skillName,
+          skillPath: data.skillPath,
+        },
+      });
+    };
+  }
+
+  private createReasoningDeltaHandler(
+    runId: number,
+    messageId: string,
+  ): EventHandler<"reasoning.delta"> {
+    return (event) => {
+      if (event.sessionId !== this.sessionId) return;
+      const data = event.data as ReasoningDeltaEventData;
+      if (!data.delta || data.delta.length === 0) return;
+      const sourceKey = data.reasoningId || "reasoning";
+      if (!this.thinkingStartTimes.has(sourceKey)) {
+        this.thinkingStartTimes.set(sourceKey, Date.now());
+      }
+      this.bus.publish({
+        type: "stream.thinking.delta",
+        sessionId: this.sessionId,
+        runId,
+        timestamp: Date.now(),
+        data: {
+          delta: data.delta,
+          sourceKey,
+          messageId,
+        },
+      });
+    };
+  }
+
+  private createReasoningCompleteHandler(
+    runId: number,
+  ): EventHandler<"reasoning.complete"> {
+    return (event) => {
+      if (event.sessionId !== this.sessionId) return;
+      const data = event.data as ReasoningCompleteEventData;
+      const sourceKey = data.reasoningId || "reasoning";
+      const start = this.thinkingStartTimes.get(sourceKey);
+      const durationMs = start ? Date.now() - start : 0;
+      this.thinkingStartTimes.delete(sourceKey);
+      this.bus.publish({
+        type: "stream.thinking.complete",
+        sessionId: this.sessionId,
+        runId,
+        timestamp: Date.now(),
+        data: {
+          sourceKey,
+          durationMs,
+        },
+      });
+    };
+  }
+
+  private createTurnStartHandler(
+    runId: number,
+  ): EventHandler<"turn.start"> {
+    return (event) => {
+      if (event.sessionId !== this.sessionId) return;
+      const data = event.data as TurnStartEventData;
+      this.bus.publish({
+        type: "stream.turn.start",
+        sessionId: this.sessionId,
+        runId,
+        timestamp: Date.now(),
+        data: {
+          turnId: normalizeTurnStartId(
+            data.turnId,
+            this.turnMetadataState,
+          ),
+        },
+      });
+    };
+  }
+
+  private createTurnEndHandler(
+    runId: number,
+  ): EventHandler<"turn.end"> {
+    return (event) => {
+      if (event.sessionId !== this.sessionId) return;
+      const data = event.data as TurnEndEventData;
+      this.bus.publish({
+        type: "stream.turn.end",
+        sessionId: this.sessionId,
+        runId,
+        timestamp: Date.now(),
+        data: normalizeTurnEndMetadata(
+          data,
+          this.turnMetadataState,
+        ),
+      });
+    };
+  }
+
+  private createToolPartialResultHandler(
+    runId: number,
+  ): EventHandler<"tool.partial_result"> {
+    return (event) => {
+      const sessionMappedParentAgentId = this.resolveSubagentSessionParentAgentId(event.sessionId);
+      if (!this.isOwnedSession(event.sessionId) && !sessionMappedParentAgentId) {
+        return;
+      }
+      const data = event.data as ToolPartialResultEventData;
+      const toolCallId = this.resolveToolCorrelationId(this.asString(data.toolCallId))
+        ?? this.asString(data.toolCallId);
+      const context = toolCallId
+        ? this.activeSubagentToolsById.get(toolCallId)
+        : undefined;
+      const parentAgentId = context?.parentAgentId ?? sessionMappedParentAgentId;
+      this.bus.publish({
+        type: "stream.tool.partial_result",
+        sessionId: this.sessionId,
+        runId,
+        timestamp: Date.now(),
+        data: {
+          toolCallId: toolCallId ?? data.toolCallId,
+          partialOutput: data.partialOutput,
+          ...(parentAgentId ? { parentAgentId } : {}),
+        },
+      });
+
+      if (!toolCallId && !parentAgentId) {
+        return;
+      }
+      if (parentAgentId && this.subagentTracker?.hasAgent(parentAgentId)) {
+        this.subagentTracker.onToolProgress(parentAgentId, context?.toolName);
+      }
+    };
+  }
+
+  private createSessionErrorHandler(
+    runId: number,
+  ): EventHandler<"session.error"> {
+    return (event) => {
+      if (event.sessionId !== this.sessionId) return;
+      const data = event.data as SessionErrorEventData;
+      const rawError = data.error;
+      const normalizedError = rawError instanceof Error
+        ? rawError.message.trim()
+        : typeof rawError === "string"
+          ? rawError.trim()
+          : "";
+
+      // Ignore malformed events that carry neither an error message nor code.
+      // This prevents placeholder "undefined" errors from reaching the UI.
+      if (normalizedError.length === 0 && !data.code) {
+        return;
+      }
+
+      this.bus.publish({
+        type: "stream.session.error",
+        sessionId: this.sessionId,
+        runId,
+        timestamp: Date.now(),
+        data: {
+          error: normalizedError.length > 0 ? normalizedError : "Unknown session error",
+          code: data.code,
+        },
+      });
+    };
+  }
+
+  private createSessionInfoHandler(
+    runId: number,
+  ): EventHandler<"session.info"> {
+    return (event) => {
+      if (event.sessionId !== this.sessionId) return;
+      const data = event.data as SessionInfoEventData;
+      this.bus.publish({
+        type: "stream.session.info",
+        sessionId: this.sessionId,
+        runId,
+        timestamp: Date.now(),
+        data: {
+          infoType: data.infoType ?? "general",
+          message: data.message ?? "",
+        },
+      });
+    };
+  }
+
+  private createSessionWarningHandler(
+    runId: number,
+  ): EventHandler<"session.warning"> {
+    return (event) => {
+      if (event.sessionId !== this.sessionId) return;
+      const data = event.data as SessionWarningEventData;
+      this.bus.publish({
+        type: "stream.session.warning",
+        sessionId: this.sessionId,
+        runId,
+        timestamp: Date.now(),
+        data: {
+          warningType: data.warningType ?? "general",
+          message: data.message ?? "",
+        },
+      });
+    };
+  }
+
+  private createSessionTitleChangedHandler(
+    runId: number,
+  ): EventHandler<"session.title_changed"> {
+    return (event) => {
+      if (event.sessionId !== this.sessionId) return;
+      const data = event.data as SessionTitleChangedEventData;
+      this.bus.publish({
+        type: "stream.session.title_changed",
+        sessionId: this.sessionId,
+        runId,
+        timestamp: Date.now(),
+        data: {
+          title: data.title ?? "",
+        },
+      });
+    };
+  }
+
+  private createSessionTruncationHandler(
+    runId: number,
+  ): EventHandler<"session.truncation"> {
+    return (event) => {
+      if (event.sessionId !== this.sessionId) return;
+      const data = event.data as SessionTruncationEventData;
+      this.bus.publish({
+        type: "stream.session.truncation",
+        sessionId: this.sessionId,
+        runId,
+        timestamp: Date.now(),
+        data: {
+          tokenLimit: data.tokenLimit ?? 0,
+          tokensRemoved: data.tokensRemoved ?? 0,
+          messagesRemoved: data.messagesRemoved ?? 0,
+        },
+      });
+    };
+  }
+
+  private createSessionCompactionHandler(
+    runId: number,
+  ): EventHandler<"session.compaction"> {
+    return (event) => {
+      if (event.sessionId !== this.sessionId) return;
+      const data = event.data as SessionCompactionEventData;
+      this.bus.publish({
+        type: "stream.session.compaction",
+        sessionId: this.sessionId,
+        runId,
+        timestamp: Date.now(),
+        data: {
+          phase: data.phase,
+          success: data.success,
+          error: data.error,
+        },
+      });
+    };
+  }
+
+  /**
+   * Create a handler for subagent.start events from the SDK.
+   * Publishes stream.agent.start to the bus.
+   */
+  private createSubagentStartHandler(
+    runId: number,
+  ): EventHandler<"subagent.start"> {
+    return (event) => {
+      const data = event.data as SubagentStartEventData;
+      const dataRecord = data as Record<string, unknown>;
+      const subagentSessionId = this.asString(
+        dataRecord.subagentSessionId
+          ?? dataRecord.subagent_session_id
+          ?? dataRecord.session_id
+          ?? dataRecord.sessionId,
+      );
+      if (this.syntheticForegroundAgent) {
+        this.syntheticForegroundAgent.sawNativeSubagentStart = true;
+        this.publishSyntheticAgentComplete(runId, true);
+      }
+
+      // Resolve correlation ID: prefer toolUseId/toolUseID, fall back to toolCallId,
+      // then check alias map for canonical tool ID resolution.
+      const rawSdkCorrelationId = this.asString(
+        data.toolUseId ?? data.toolUseID ?? data.toolCallId,
+      );
+      let sdkCorrelationId = this.resolveToolCorrelationId(rawSdkCorrelationId);
+
+      // Also resolve the parent tool use ID — the Claude SDK's SubagentStart hook
+      // may provide a different toolUseID than the Agent tool's tool_use_id. The
+      // parent_tool_use_id field carries the Agent tool's original ID, which is the
+      // key used in taskToolMetadata.
+      let parentToolUseId = this.resolveToolCorrelationId(this.asString(
+        dataRecord.parentToolUseId
+          ?? dataRecord.parent_tool_use_id
+          ?? dataRecord.parentToolUseID
+          ?? dataRecord.parentToolCallId
+          ?? dataRecord.parent_tool_call_id
+          ?? dataRecord.parentToolCallID,
+      ));
+      const isKnownSubagent = this.hasKnownSubagentId(data.subagentId);
+      const hasTaskCorrelation = Boolean(
+        sdkCorrelationId
+        && (
+          this.taskToolMetadata.has(sdkCorrelationId)
+          || this.pendingTaskToolCorrelationIds.includes(sdkCorrelationId)
+        ),
+      );
+      const hasParentTaskCorrelation = Boolean(
+        parentToolUseId
+        && (
+          this.taskToolMetadata.has(parentToolUseId)
+          || this.pendingTaskToolCorrelationIds.includes(parentToolUseId)
+        ),
+      );
+      if (
+        event.sessionId !== this.sessionId
+        && !isKnownSubagent
+        && !hasTaskCorrelation
+        && !hasParentTaskCorrelation
+      ) {
+        return;
+      }
+
+      const hasSdkMetadata = sdkCorrelationId
+        ? this.taskToolMetadata.has(sdkCorrelationId)
+        : false;
+      if (!hasSdkMetadata && parentToolUseId && this.taskToolMetadata.has(parentToolUseId)) {
+        sdkCorrelationId = parentToolUseId;
+      }
+
+      if (!sdkCorrelationId) {
+        const inferredTaskToolId = this.resolveNextPendingTaskToolCorrelationId();
+        if (inferredTaskToolId) {
+          sdkCorrelationId = inferredTaskToolId;
+          parentToolUseId = parentToolUseId ?? inferredTaskToolId;
+        }
+      } else if (!parentToolUseId && !this.taskToolMetadata.has(sdkCorrelationId)) {
+        const inferredTaskToolId = this.resolveNextPendingTaskToolCorrelationId();
+        if (inferredTaskToolId) {
+          parentToolUseId = inferredTaskToolId;
+          if (!this.taskToolMetadata.has(sdkCorrelationId)) {
+            sdkCorrelationId = inferredTaskToolId;
+          }
+        }
+      }
+
+      const metadata = (sdkCorrelationId ? this.taskToolMetadata.get(sdkCorrelationId) : undefined)
+        ?? (parentToolUseId ? this.taskToolMetadata.get(parentToolUseId) : undefined);
+      const effectiveTask = metadata?.description || data.task;
+      const normalizedTask = isGenericSubagentTaskLabel(effectiveTask)
+        ? (this.asString(dataRecord.description) ?? effectiveTask)
+        : effectiveTask;
+
+      const normalizedMetadata = normalizeAgentTaskMetadata(
+        {
+          task: normalizedTask,
+          agentType: data.subagentType,
+          isBackground: metadata?.isBackground
+            ?? (dataRecord.isBackground as boolean | undefined),
+          toolInput: dataRecord.toolInput,
+        },
+      );
+
+      // Register agent with tracker for tool counting
+      this.subagentTracker?.registerAgent(data.subagentId);
+      this.activeSubagentIds.add(data.subagentId);
+      if (subagentSessionId && subagentSessionId !== this.sessionId) {
+        this.ownedSessionIds.add(subagentSessionId);
+        this.subagentSessionToAgentId.set(subagentSessionId, data.subagentId);
+      }
+      if (event.sessionId !== this.sessionId) {
+        this.ownedSessionIds.add(event.sessionId);
+        this.subagentSessionToAgentId.set(event.sessionId, data.subagentId);
+      }
+      this.activeSubagentBackgroundById.set(data.subagentId, normalizedMetadata.isBackground);
+      if (normalizedMetadata.isBackground && !this.currentBackgroundAttributionAgentId) {
+        this.currentBackgroundAttributionAgentId = data.subagentId;
+      }
+
+      if (sdkCorrelationId) {
+        this.toolUseIdToSubagentId.set(sdkCorrelationId, data.subagentId);
+        this.removePendingTaskToolCorrelationId(sdkCorrelationId);
+      }
+      // Also map under the parent tool use ID so tool events correlated via the
+      // Agent tool's tool_use_id can resolve to this sub-agent.
+      if (parentToolUseId && parentToolUseId !== sdkCorrelationId) {
+        this.toolUseIdToSubagentId.set(parentToolUseId, data.subagentId);
+        this.removePendingTaskToolCorrelationId(parentToolUseId);
+      }
+
+      for (const key of [data.subagentId, sdkCorrelationId, parentToolUseId]) {
+        if (!key) {
+          continue;
+        }
+        const earlyTools = this.earlyToolEvents.get(key);
+        if (!earlyTools) {
+          continue;
+        }
+        for (const tool of earlyTools) {
+          this.subagentTracker?.onToolStart(data.subagentId, tool.toolName);
+        }
+        this.earlyToolEvents.delete(key);
+      }
+
+      const busEvent: BusEvent<"stream.agent.start"> = {
+        type: "stream.agent.start",
+        sessionId: this.sessionId,
+        runId,
+        timestamp: Date.now(),
+        data: {
+          agentId: data.subagentId,
+          toolCallId: sdkCorrelationId ?? data.subagentId,
+          agentType: data.subagentType ?? "unknown",
+          task: normalizedMetadata.task,
+          isBackground: normalizedMetadata.isBackground,
+          sdkCorrelationId,
+        },
+      };
+      this.bus.publish(busEvent);
+    };
+  }
+
+  /**
+   * Create a handler for subagent.complete events from the SDK.
+   * Publishes stream.agent.complete to the bus.
+   */
+  private createSubagentCompleteHandler(
+    runId: number,
+  ): EventHandler<"subagent.complete"> {
+    return (event) => {
+      const data = event.data as SubagentCompleteEventData;
+      if (event.sessionId !== this.sessionId && !this.hasKnownSubagentId(data.subagentId)) {
+        return;
+      }
+      this.subagentTracker?.removeAgent(data.subagentId);
+      this.activeSubagentIds.delete(data.subagentId);
+      this.activeSubagentBackgroundById.delete(data.subagentId);
+      this.earlyToolEvents.delete(data.subagentId);
+      for (const [toolUseId, subagentId] of this.toolUseIdToSubagentId.entries()) {
+        if (subagentId === data.subagentId) {
+          this.toolUseIdToSubagentId.delete(toolUseId);
+          this.taskToolMetadata.delete(toolUseId);
+          this.removePendingTaskToolCorrelationId(toolUseId);
+          this.earlyToolEvents.delete(toolUseId);
+        }
+      }
+      for (const [subagentSessionId, mappedAgentId] of this.subagentSessionToAgentId.entries()) {
+        if (mappedAgentId === data.subagentId) {
+          this.subagentSessionToAgentId.delete(subagentSessionId);
+          this.ownedSessionIds.delete(subagentSessionId);
+        }
+      }
+      if (this.currentBackgroundAttributionAgentId === data.subagentId) {
+        this.currentBackgroundAttributionAgentId = this.resolveBackgroundAttributionFallbackAgentId() ?? null;
+      }
+
+      const busEvent: BusEvent<"stream.agent.complete"> = {
+        type: "stream.agent.complete",
+        sessionId: this.sessionId,
+        runId,
+        timestamp: Date.now(),
+        data: {
+          agentId: data.subagentId,
+          success: data.success,
+          result: typeof data.result === "string" ? data.result : undefined,
+          error: typeof (data as Record<string, unknown>).error === "string"
+            ? (data as Record<string, unknown>).error as string
+            : undefined,
+        },
+      };
+      this.bus.publish(busEvent);
+    };
+  }
+
+  /**
+   * Create a handler for subagent.update events from the SDK.
+   * Publishes stream.agent.update to the bus.
+   */
+  private createSubagentUpdateHandler(
+    runId: number,
+  ): EventHandler<"subagent.update"> {
+    return (event) => {
+      const data = event.data as SubagentUpdateEventData;
+      if (event.sessionId !== this.sessionId && !this.hasKnownSubagentId(data.subagentId)) {
+        return;
+      }
+      const busEvent: BusEvent<"stream.agent.update"> = {
+        type: "stream.agent.update",
+        sessionId: this.sessionId,
+        runId,
+        timestamp: Date.now(),
+        data: {
+          agentId: data.subagentId,
+          currentTool: data.currentTool,
+          toolUses: data.toolUses,
+        },
+      };
+      this.bus.publish(busEvent);
+    };
+  }
+
+  private createSessionIdleHandler(
+    runId: number,
+  ): EventHandler<"session.idle"> {
+    return (event) => {
+      if (event.sessionId !== this.sessionId) {
+        return;
+      }
+
+      const data = event.data as SessionIdleEventData;
+      const busEvent: BusEvent<"stream.session.idle"> = {
+        type: "stream.session.idle",
+        sessionId: this.sessionId,
+        runId,
+        timestamp: Date.now(),
+        data: {
+          reason: typeof data.reason === "string" ? data.reason : undefined,
+        },
+      };
+      this.bus.publish(busEvent);
+    };
+  }
+
+  private publishSessionStart(runId: number): void {
+    const event: BusEvent<"stream.session.start"> = {
+      type: "stream.session.start",
+      sessionId: this.sessionId,
+      runId,
+      timestamp: Date.now(),
+      data: {},
+    };
+    this.bus.publish(event);
+  }
+
+  /**
+   * Publish a stream.text.complete event.
+   */
+  private publishTextComplete(runId: number, messageId: string): void {
+    const event: BusEvent<"stream.text.complete"> = {
+      type: "stream.text.complete",
+      sessionId: this.sessionId,
+      runId,
+      timestamp: Date.now(),
+      data: {
+        messageId,
+        fullText: this.textAccumulator,
+      },
+    };
+
+    this.bus.publish(event);
+  }
+
+  /**
+   * Publish a stream.session.error event.
+   */
+  private publishSessionError(runId: number, error: unknown): void {
+    const errorMessage =
+      error instanceof Error ? error.message : String(error);
+
+    const event: BusEvent<"stream.session.error"> = {
+      type: "stream.session.error",
+      sessionId: this.sessionId,
+      runId,
+      timestamp: Date.now(),
+      data: {
+        error: errorMessage,
+      },
+    };
+
+    this.bus.publish(event);
+  }
+
+  private asRecord(value: unknown): Record<string, unknown> | undefined {
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+      return value as Record<string, unknown>;
+    }
+    return undefined;
+  }
+
+  private asString(value: unknown): string | undefined {
+    return typeof value === "string" && value.trim().length > 0
+      ? value
+      : undefined;
+  }
+
+  private normalizeToolName(value: unknown): string {
+    return this.asString(value) ?? "unknown";
+  }
+
+  private isTaskTool(toolName: string): boolean {
+    const normalized = toolName.toLowerCase();
+    return normalized === "task" || normalized === "launch_agent" || normalized === "agent";
+  }
+
+  private resolveTaskOutputParentAgentId(
+    toolName: string,
+    toolInput: Record<string, unknown>,
+  ): string | undefined {
+    if (toolName.toLowerCase() !== "taskoutput") {
+      return undefined;
+    }
+    const taskId = this.asString(toolInput.task_id ?? toolInput.taskId);
+    if (!taskId) {
+      return undefined;
+    }
+    if (this.hasKnownSubagentId(taskId)) {
+      return taskId;
+    }
+    return this.toolUseIdToSubagentId.get(taskId);
+  }
+
+  private extractTaskToolMetadata(
+    toolInput: unknown,
+  ): { description: string; isBackground: boolean } {
+    const record = this.asRecord(toolInput) ?? {};
+    return {
+      description: this.asString(record.description)
+        ?? this.asString(record.prompt)
+        ?? this.asString(record.task)
+        ?? "",
+      isBackground: record.run_in_background === true
+        || this.asString(record.mode)?.toLowerCase() === "background",
+    };
+  }
+
+  private createSyntheticToolId(runId: number, toolName: string): string {
+    this.syntheticToolCounter += 1;
+    const normalizedName = toolName.replace(/[^a-zA-Z0-9_-]/g, "_");
+    return `tool_${runId}_${normalizedName}_${this.syntheticToolCounter}`;
+  }
+
+  private queueToolId(toolName: string, toolId: string): void {
+    const queue = this.pendingToolIdsByName.get(toolName) ?? [];
+    if (!queue.includes(toolId)) {
+      queue.push(toolId);
+      this.pendingToolIdsByName.set(toolName, queue);
+    }
+  }
+
+  private removeQueuedToolId(toolName: string, toolId: string): void {
+    const queue = this.pendingToolIdsByName.get(toolName);
+    if (!queue) return;
+    const nextQueue = queue.filter((queuedId) => queuedId !== toolId);
+    if (nextQueue.length === 0) {
+      this.pendingToolIdsByName.delete(toolName);
+      return;
+    }
+    this.pendingToolIdsByName.set(toolName, nextQueue);
+  }
+
+  private shiftQueuedToolId(toolName: string): string | undefined {
+    const queue = this.pendingToolIdsByName.get(toolName);
+    if (!queue || queue.length === 0) {
+      return undefined;
+    }
+    const [toolId, ...rest] = queue;
+    if (rest.length === 0) {
+      this.pendingToolIdsByName.delete(toolName);
+    } else {
+      this.pendingToolIdsByName.set(toolName, rest);
+    }
+    return toolId;
+  }
+
+  private resolveToolStartId(
+    explicitToolId: string | undefined,
+    runId: number,
+    toolName: string,
+  ): string {
+    const toolId = explicitToolId ?? this.createSyntheticToolId(runId, toolName);
+    this.queueToolId(toolName, toolId);
+    return toolId;
+  }
+
+  private resolveToolCompleteId(
+    explicitToolId: string | undefined,
+    runId: number,
+    toolName: string,
+  ): string {
+    if (explicitToolId) {
+      this.removeQueuedToolId(toolName, explicitToolId);
+      return explicitToolId;
+    }
+    return this.shiftQueuedToolId(toolName) ?? this.createSyntheticToolId(runId, toolName);
+  }
+
+  private resolveToolCorrelationId(correlationId: string | undefined): string | undefined {
+    if (!correlationId) {
+      return undefined;
+    }
+    return this.toolCorrelationAliases.get(correlationId) ?? correlationId;
+  }
+
+  private recordPendingTaskToolCorrelationId(correlationId: string): void {
+    if (this.pendingTaskToolCorrelationIds.includes(correlationId)) {
+      return;
+    }
+    this.pendingTaskToolCorrelationIds.push(correlationId);
+  }
+
+  private removePendingTaskToolCorrelationId(correlationId: string): void {
+    this.pendingTaskToolCorrelationIds = this.pendingTaskToolCorrelationIds.filter(
+      (candidate) => candidate !== correlationId,
+    );
+  }
+
+  private resolveNextPendingTaskToolCorrelationId(): string | undefined {
+    for (const correlationId of this.pendingTaskToolCorrelationIds) {
+      if (this.taskToolMetadata.has(correlationId) && !this.toolUseIdToSubagentId.has(correlationId)) {
+        return correlationId;
+      }
+    }
+    return undefined;
+  }
+
+  private getSyntheticAgentIdForAttribution(): string | undefined {
+    if (!this.syntheticForegroundAgent) {
+      return undefined;
+    }
+    if (this.syntheticForegroundAgent.completed || this.syntheticForegroundAgent.sawNativeSubagentStart) {
+      return undefined;
+    }
+    return this.syntheticForegroundAgent.id;
+  }
+
+  private resolveActiveSubagentToolContext(
+    ...correlationIds: Array<string | undefined>
+  ): { parentAgentId: string; toolName: string } | undefined {
+    const ids = correlationIds
+      .map((id) => this.resolveToolCorrelationId(id) ?? id)
+      .filter((id): id is string => Boolean(id));
+    for (const id of ids) {
+      const context = this.activeSubagentToolsById.get(id);
+      if (context) {
+        return context;
+      }
+    }
+    return undefined;
+  }
+
+  private resolveSoleActiveSubagentToolParentAgentId(): string | undefined {
+    const parentAgentIds = new Set<string>();
+    for (const context of this.activeSubagentToolsById.values()) {
+      if (!this.subagentTracker?.hasAgent(context.parentAgentId)) {
+        continue;
+      }
+      parentAgentIds.add(context.parentAgentId);
+      if (parentAgentIds.size > 1) {
+        return undefined;
+      }
+    }
+    return parentAgentIds.values().next().value;
+  }
+
+  private publishSyntheticAgentStart(runId: number): void {
+    const syntheticAgent = this.syntheticForegroundAgent;
+    if (!syntheticAgent || syntheticAgent.started || syntheticAgent.sawNativeSubagentStart) {
+      return;
+    }
+    syntheticAgent.started = true;
+    this.subagentTracker?.registerAgent(syntheticAgent.id);
+    this.bus.publish({
+      type: "stream.agent.start",
+      sessionId: this.sessionId,
+      runId,
+      timestamp: Date.now(),
+      data: {
+        agentId: syntheticAgent.id,
+        toolCallId: syntheticAgent.id,
+        agentType: syntheticAgent.name,
+        task: syntheticAgent.task,
+        isBackground: false,
+        sdkCorrelationId: syntheticAgent.id,
+      },
+    });
+  }
+
+  private publishSyntheticAgentComplete(
+    runId: number,
+    success: boolean,
+    error?: string,
+  ): void {
+    const syntheticAgent = this.syntheticForegroundAgent;
+    if (!syntheticAgent || !syntheticAgent.started || syntheticAgent.completed) {
+      return;
+    }
+    syntheticAgent.completed = true;
+    this.subagentTracker?.removeAgent(syntheticAgent.id);
+    this.bus.publish({
+      type: "stream.agent.complete",
+      sessionId: this.sessionId,
+      runId,
+      timestamp: Date.now(),
+      data: {
+        agentId: syntheticAgent.id,
+        success,
+        result: success ? this.textAccumulator : undefined,
+        ...(error ? { error } : {}),
+      },
+    });
+  }
+
+  private registerToolCorrelationAliases(
+    toolId: string,
+    ...correlationIds: Array<string | undefined>
+  ): void {
+    for (const correlationId of correlationIds) {
+      if (!correlationId || correlationId === toolId) {
+        continue;
+      }
+      this.toolCorrelationAliases.set(correlationId, toolId);
+    }
+  }
+
+  private recordActiveSubagentToolContext(
+    toolId: string,
+    toolName: string,
+    parentAgentId: string,
+    ...correlationIds: Array<string | undefined>
+  ): void {
+    const context = { parentAgentId, toolName };
+    const ids = [toolId, ...correlationIds]
+      .map((id) => this.resolveToolCorrelationId(id) ?? id)
+      .filter((id): id is string => Boolean(id));
+    for (const id of ids) {
+      this.activeSubagentToolsById.set(id, context);
+    }
+  }
+
+  private removeActiveSubagentToolContext(
+    toolId: string,
+    ...correlationIds: Array<string | undefined>
+  ): void {
+    const ids = [toolId, ...correlationIds]
+      .map((id) => this.resolveToolCorrelationId(id) ?? id)
+      .filter((id): id is string => Boolean(id));
+    for (const id of ids) {
+      this.activeSubagentToolsById.delete(id);
+    }
+  }
+
+  private hasKnownSubagentId(subagentId: string): boolean {
+    if (!subagentId) {
+      return false;
+    }
+    if (this.activeSubagentIds.has(subagentId)) {
+      return true;
+    }
+    if (this.subagentTracker?.hasAgent(subagentId)) {
+      return true;
+    }
+    for (const mappedId of this.toolUseIdToSubagentId.values()) {
+      if (mappedId === subagentId) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  private resolveSoleActiveSubagentId(): string | undefined {
+    if (this.activeSubagentIds.size !== 1) {
+      return undefined;
+    }
+    return this.activeSubagentIds.values().next().value;
+  }
+
+  private resolveBackgroundAttributionFallbackAgentId(): string | undefined {
+    if (this.activeSubagentIds.size === 0) {
+      return undefined;
+    }
+
+    const backgroundAgentIds = [...this.activeSubagentIds].filter(
+      (agentId) => this.activeSubagentBackgroundById.get(agentId) === true,
+    );
+    if (backgroundAgentIds.length === 0) {
+      return undefined;
+    }
+
+    // Avoid forcing background attribution when any known foreground subagent is active.
+    const hasForegroundAgent = [...this.activeSubagentIds].some(
+      (agentId) => this.activeSubagentBackgroundById.get(agentId) !== true,
+    );
+    if (hasForegroundAgent) {
+      return undefined;
+    }
+
+    if (
+      this.currentBackgroundAttributionAgentId
+      && backgroundAgentIds.includes(this.currentBackgroundAttributionAgentId)
+    ) {
+      return this.currentBackgroundAttributionAgentId;
+    }
+
+    return backgroundAgentIds[0];
+  }
+
+  /**
+   * Force-complete any tools that received start but no complete event.
+   * Prevents tools from being stuck in running state after stream abort.
+   */
+  private cleanupOrphanedTools(runId: number): void {
+    for (const [toolName, toolIds] of this.pendingToolIdsByName.entries()) {
+      for (const toolId of toolIds) {
+        const context = this.resolveActiveSubagentToolContext(toolId);
+        const event: BusEvent<"stream.tool.complete"> = {
+          type: "stream.tool.complete",
+          sessionId: this.sessionId,
+          runId,
+          timestamp: Date.now(),
+          data: {
+            toolId,
+            toolName,
+            toolResult: null,
+            success: false,
+            error: "Tool execution aborted",
+            ...(context ? { parentAgentId: context.parentAgentId } : {}),
+          },
+        };
+        this.bus.publish(event);
+        this.removeActiveSubagentToolContext(toolId);
+      }
+    }
+    this.pendingToolIdsByName.clear();
+    this.activeSubagentIds.clear();
+    this.activeSubagentBackgroundById.clear();
+    this.currentBackgroundAttributionAgentId = null;
+    this.activeSubagentToolsById.clear();
+    this.ownedSessionIds = new Set([this.sessionId]);
+    this.subagentSessionToAgentId.clear();
+  }
+
+  /**
+   * Clean up SDK event subscriptions without full state reset.
+   */
+  private cleanupSubscriptions(): void {
+    for (const unsubscribe of this.unsubscribers) {
+      unsubscribe();
+    }
+    this.unsubscribers = [];
+  }
+
+  /**
+   * Cancel the ongoing stream and cleanup resources.
+   */
+  dispose(): void {
+    if (this.abortController) {
+      this.abortController.abort();
+      this.abortController = null;
+    }
+    this.cleanupSubscriptions();
+    this.textAccumulator = "";
+    this.thinkingStartTimes.clear();
+    this.pendingToolIdsByName.clear();
+    this.toolCorrelationAliases.clear();
+    this.taskToolMetadata.clear();
+    this.pendingTaskToolCorrelationIds = [];
+    this.earlyToolEvents.clear();
+    this.activeSubagentIds.clear();
+    this.activeSubagentBackgroundById.clear();
+    this.currentBackgroundAttributionAgentId = null;
+    this.activeSubagentToolsById.clear();
+    this.ownedSessionIds.clear();
+    this.subagentSessionToAgentId.clear();
+    this.toolUseIdToSubagentId.clear();
+    this.syntheticForegroundAgent = null;
+    this.syntheticToolCounter = 0;
+    this.accumulatedOutputTokens = 0;
+    this.runtimeFeatureFlags = { ...DEFAULT_WORKFLOW_RUNTIME_FEATURE_FLAGS };
+    resetTurnMetadataState(this.turnMetadataState);
+    this.subagentTracker?.reset();
+    this.subagentTracker = null;
+  }
+
+  private resolveRuntimeFeatureFlags(
+    overrides: WorkflowRuntimeFeatureFlagOverrides | undefined,
+  ): WorkflowRuntimeFeatureFlags {
+    return resolveWorkflowRuntimeFeatureFlags(overrides);
+  }
+
+  private isOwnedSession(eventSessionId: string): boolean {
+    return eventSessionId === this.sessionId || this.ownedSessionIds.has(eventSessionId);
+  }
+
+  private resolveSubagentSessionParentAgentId(eventSessionId: string): string | undefined {
+    if (eventSessionId === this.sessionId) {
+      return undefined;
+    }
+    return this.subagentSessionToAgentId.get(eventSessionId);
+  }
+}
diff --git a/src/events/adapters/copilot-adapter.ts b/src/events/adapters/copilot-adapter.ts
new file mode 100644
index 0000000000..bbe0cd2426
--- /dev/null
+++ b/src/events/adapters/copilot-adapter.ts
@@ -0,0 +1,1445 @@
+/**
+ * Copilot SDK Stream Adapter
+ *
+ * Consumer-side adapter that bridges Copilot SDK EventEmitter-based streaming
+ * to the event bus. Unlike OpenCode/Claude (pull-based async iteration),
+ * Copilot is push-based (EventEmitter), requiring backpressure management.
+ *
+ * Key responsibilities:
+ * - Listen to Copilot client EventEmitter events via client.on()
+ * - Map SDK event types to BusEvent types
+ * - Implement backpressure using a bounded buffer
+ * - Create properly typed BusEvent instances with runId metadata
+ * - Clean up event listeners on dispose()
+ *
+ * Event mappings:
+ * - message.delta → stream.text.delta
+ * - message.complete → stream.text.complete
+ * - tool.start → stream.tool.start
+ * - tool.complete → stream.tool.complete
+ * - tool.partial_result → stream.tool.partial_result
+ * - thinking (from message.delta with thinking content) → stream.thinking.delta
+ * - reasoning.delta → stream.thinking.delta
+ * - reasoning.complete → stream.thinking.complete
+ * - subagent.start → stream.agent.start
+ * - subagent.complete → stream.agent.complete
+ * - turn.start → stream.turn.start
+ * - turn.end → stream.turn.end
+ * - session.idle → stream.session.idle
+ * - session.error → stream.session.error
+ * - session.info → stream.session.info
+ * - session.warning → stream.session.warning
+ * - session.title_changed → stream.session.title_changed
+ * - session.truncation → stream.session.truncation
+ * - session.compaction → stream.session.compaction
+ * - usage → stream.usage
+ *
+ * Usage:
+ * ```typescript
+ * const adapter = new CopilotStreamAdapter(eventBus, client);
+ * await adapter.startStreaming(session, "Hello", { runId: 1, messageId: "msg1" });
+ * adapter.dispose(); // Clean up listeners
+ * ```
+ */
+
+import type {
+  Session,
+  CodingAgentClient,
+  AgentEvent,
+  PermissionRequestedEventData,
+  HumanInputRequiredEventData,
+  SkillInvokedEventData,
+  ReasoningDeltaEventData,
+  ReasoningCompleteEventData,
+  TurnStartEventData,
+  TurnEndEventData,
+  ToolPartialResultEventData,
+  SessionInfoEventData,
+  SessionWarningEventData,
+  SessionTitleChangedEventData,
+  SessionTruncationEventData,
+  SessionCompactionEventData,
+  SubagentStartEventData,
+  SubagentCompleteEventData,
+  SubagentUpdateEventData,
+} from "../../sdk/types.ts";
+import type { EventBus } from "../event-bus.ts";
+import type { BusEvent } from "../bus-events.ts";
+import type { SDKStreamAdapter, StreamAdapterOptions } from "./types.ts";
+import { SubagentToolTracker } from "./subagent-tool-tracker.ts";
+import type {
+  WorkflowRuntimeFeatureFlags,
+  WorkflowRuntimeFeatureFlagOverrides,
+} from "../../workflows/runtime-contracts.ts";
+import {
+  DEFAULT_WORKFLOW_RUNTIME_FEATURE_FLAGS,
+  resolveWorkflowRuntimeFeatureFlags,
+} from "../../workflows/runtime-contracts.ts";
+import {
+  createTurnMetadataState,
+  normalizeAgentTaskMetadata,
+  normalizeTurnEndMetadata,
+  normalizeTurnStartId,
+  resetTurnMetadataState,
+} from "./task-turn-normalization.ts";
+
+/**
+ * Maximum number of events to buffer before dropping oldest events.
+ * This prevents memory exhaustion when events arrive faster than they can be processed.
+ */
+const MAX_BUFFER_SIZE = 1000;
+
+/**
+ * Copilot SDK Stream Adapter for EventEmitter-based streaming.
+ *
+ * Implements backpressure management using a bounded buffer to handle
+ * push-based event delivery from the Copilot SDK client.
+ */
+export class CopilotStreamAdapter implements SDKStreamAdapter {
+  private bus: EventBus;
+  private client: CodingAgentClient;
+  private unsubscribers: Array<() => void> = [];
+  private eventBuffer: BusEvent[] = [];
+  private eventBufferHead = 0;
+  private isProcessing = false;
+  private sessionId: string = "";
+  private runId: number = 0;
+  private messageId: string = "";
+  private isActive = false;
+  private pendingToolIdsByName = new Map<string, string[]>();
+  private toolNameById = new Map<string, string>();
+  private syntheticToolCounter = 0;
+  private subagentTracker: SubagentToolTracker | null = null;
+
+  /**
+   * Track tool call IDs that have already had a `stream.tool.start` emitted
+   * (from `assistant.message.toolRequests`), so that a later `tool.execution_start`
+   * for the same ID is deduplicated.
+   */
+  private emittedToolStartIds = new Set<string>();
+
+  /** Maps task tool toolCallId -> metadata extracted from tool arguments */
+  private taskToolMetadata = new Map<string, { description: string; isBackground: boolean }>();
+
+  /** Buffers tool events that arrive before their parent subagent.started */
+  private earlyToolEvents = new Map<string, Array<{ toolName: string }>>();
+  /** Active sub-agent tool contexts keyed by tool call ID */
+  private activeSubagentToolsById = new Map<string, { parentAgentId: string; toolName: string }>();
+
+  /** Known agent names that should be treated as task tools (Copilot SDK) */
+  private knownAgentNames = new Set<string>();
+
+  /**
+   * Maps task-tool toolCallId → subagentId.
+   * Copilot SDK tool events from within a sub-agent carry `parentToolCallId`
+   * (the ID of the Task tool call that spawned the agent), NOT the sub-agent's
+   * own ID. This map lets us resolve the former to the latter for
+   * SubagentToolTracker lookups.
+   */
+  private toolCallIdToSubagentId = new Map<string, string>();
+
+  /**
+   * Tool call IDs that belong to a sub-agent (have parentAgentId).
+   * Used to detect nested sub-agents in handleSubagentStart: if a
+   * subagent.start's toolCallId is in this set, it was spawned by
+   * another sub-agent and should NOT appear as a top-level tree entry.
+   */
+  private innerToolCallIds = new Set<string>();
+
+  /**
+   * Nested sub-agent IDs intentionally suppressed from tree lifecycle events.
+   * Ensures we do not later emit stream.agent.update/complete without a start.
+   */
+  private suppressedNestedAgentIds = new Set<string>();
+
+  /**
+   * Track thinking streams for timing and correlation.
+   * Key: reasoningId (thinkingSourceKey), Value: start timestamp
+   */
+  private thinkingStreams = new Map<string, number>();
+
+  /**
+   * Track accumulated text content for complete events.
+   */
+  private accumulatedText = "";
+
+  /**
+   * Running total of output tokens across all API calls in the current stream.
+   * Each assistant.usage event reports per-API-call values; we sum them so
+   * the bus event carries the cumulative total.
+   */
+  private accumulatedOutputTokens = 0;
+  private runtimeFeatureFlags: WorkflowRuntimeFeatureFlags = {
+    ...DEFAULT_WORKFLOW_RUNTIME_FEATURE_FLAGS,
+  };
+  private turnMetadataState = createTurnMetadataState();
+
+  /**
+   * Create a new Copilot stream adapter.
+   *
+   * @param bus - The event bus to publish events to
+   * @param client - The Copilot client to subscribe to events from
+   */
+  constructor(bus: EventBus, client: CodingAgentClient) {
+    this.bus = bus;
+    this.client = client;
+  }
+
+  /**
+   * Start streaming from the Copilot SDK session.
+   *
+   * Registers event listeners on the client's EventEmitter and translates
+   * all SDK events to BusEvents, publishing them to the event bus.
+   *
+   * @param session - Active SDK session to stream from
+   * @param message - User message that initiated the stream
+   * @param options - Stream options including runId and messageId
+   */
+  async startStreaming(
+    session: Session,
+    message: string,
+    options: StreamAdapterOptions,
+  ): Promise<void> {
+    // Clean up any existing subscriptions from a previous startStreaming() call
+    // to prevent subscription accumulation on re-entry without dispose()
+    this.cleanupSubscriptions();
+
+    this.sessionId = session.id;
+    this.runId = options.runId;
+    this.messageId = options.messageId;
+    this.accumulatedText = "";
+    this.accumulatedOutputTokens = 0;
+    this.thinkingStreams.clear();
+    this.pendingToolIdsByName.clear();
+    this.toolNameById.clear();
+    this.syntheticToolCounter = 0;
+    this.emittedToolStartIds.clear();
+    this.taskToolMetadata.clear();
+    this.earlyToolEvents.clear();
+    this.activeSubagentToolsById.clear();
+    this.toolCallIdToSubagentId.clear();
+    this.innerToolCallIds.clear();
+    this.suppressedNestedAgentIds.clear();
+    this.knownAgentNames = new Set(
+      (options.knownAgentNames ?? []).map(n => n.toLowerCase())
+    );
+    this.runtimeFeatureFlags = this.resolveRuntimeFeatureFlags(options.runtimeFeatureFlags);
+    resetTurnMetadataState(this.turnMetadataState);
+    this.subagentTracker = new SubagentToolTracker(this.bus, this.sessionId, this.runId);
+    this.isActive = true;
+
+    this.publishEvent({
+      type: "stream.session.start",
+      sessionId: this.sessionId,
+      runId: this.runId,
+      timestamp: Date.now(),
+      data: {},
+    });
+
+    // Subscribe to all relevant event types from the client
+    this.subscribeToEvents();
+
+    try {
+      // Initiate streaming by calling session.stream()
+      // This triggers the SDK to start emitting events through the client
+      const streamIterator = session.stream(message, options);
+
+      // Consume the stream to completion.
+      // The chunks are handled by our event subscribers (subscribeToEvents);
+      // we just need to iterate so the underlying generator stays alive.
+      // The client-level session.idle subscription (handleSessionIdle)
+      // already publishes stream.session.idle to the bus, so we do NOT
+      // publish a duplicate idle event when the loop exits.
+      for await (const _chunk of streamIterator) {
+        // no-op: event subscribers handle content
+      }
+    } catch (error) {
+      // Publish error event if streaming fails
+      if (this.isActive) {
+        this.publishEvent({
+          type: "stream.session.error",
+          sessionId: this.sessionId,
+          runId: this.runId,
+          timestamp: Date.now(),
+          data: {
+            error: error instanceof Error ? error.message : String(error),
+          },
+        });
+      }
+    } finally {
+      // Force-complete any tools still pending/running — prevents orphaned tool state
+      this.cleanupOrphanedTools();
+      this.isActive = false;
+    }
+  }
+
+  /**
+   * Subscribe to all relevant events from the Copilot client.
+   */
+  private subscribeToEvents(): void {
+    // Subscribe to message.delta events (text streaming)
+    const unsubDelta = this.client.on("message.delta", (event) => {
+      if (!this.isActive || event.sessionId !== this.sessionId) return;
+      this.handleMessageDelta(event);
+    });
+    this.unsubscribers.push(unsubDelta);
+
+    // Subscribe to message.complete events
+    const unsubComplete = this.client.on("message.complete", (event) => {
+      if (!this.isActive || event.sessionId !== this.sessionId) return;
+      this.handleMessageComplete(event);
+    });
+    this.unsubscribers.push(unsubComplete);
+
+    // Subscribe to tool.start events
+    const unsubToolStart = this.client.on("tool.start", (event) => {
+      if (!this.isActive || event.sessionId !== this.sessionId) return;
+      this.handleToolStart(event);
+    });
+    this.unsubscribers.push(unsubToolStart);
+
+    // Subscribe to tool.complete events
+    const unsubToolComplete = this.client.on("tool.complete", (event) => {
+      if (!this.isActive || event.sessionId !== this.sessionId) return;
+      this.handleToolComplete(event);
+    });
+    this.unsubscribers.push(unsubToolComplete);
+
+    // Subscribe to session.idle events
+    const unsubIdle = this.client.on("session.idle", (event) => {
+      if (!this.isActive || event.sessionId !== this.sessionId) return;
+      this.handleSessionIdle(event);
+    });
+    this.unsubscribers.push(unsubIdle);
+
+    // Subscribe to session.error events
+    const unsubError = this.client.on("session.error", (event) => {
+      if (!this.isActive || event.sessionId !== this.sessionId) return;
+      this.handleSessionError(event);
+    });
+    this.unsubscribers.push(unsubError);
+
+    // Subscribe to usage events
+    const unsubUsage = this.client.on("usage", (event) => {
+      if (!this.isActive || event.sessionId !== this.sessionId) return;
+      this.handleUsage(event);
+    });
+    this.unsubscribers.push(unsubUsage);
+
+    // Subscribe to permission request events
+    const unsubPermission = this.client.on("permission.requested", (event) => {
+      if (!this.isActive || event.sessionId !== this.sessionId) return;
+      this.handlePermissionRequested(event as AgentEvent<"permission.requested">);
+    });
+    this.unsubscribers.push(unsubPermission);
+
+    // Subscribe to workflow/human-input events
+    const unsubHumanInput = this.client.on("human_input_required", (event) => {
+      if (!this.isActive || event.sessionId !== this.sessionId) return;
+      this.handleHumanInputRequired(event as AgentEvent<"human_input_required">);
+    });
+    this.unsubscribers.push(unsubHumanInput);
+
+    // Subscribe to skill invocation events
+    const unsubSkill = this.client.on("skill.invoked", (event) => {
+      if (!this.isActive || event.sessionId !== this.sessionId) return;
+      this.handleSkillInvoked(event as AgentEvent<"skill.invoked">);
+    });
+    this.unsubscribers.push(unsubSkill);
+
+    // Subscribe to reasoning delta events (thinking content)
+    const unsubReasoningDelta = this.client.on("reasoning.delta", (event) => {
+      if (!this.isActive || event.sessionId !== this.sessionId) return;
+      this.handleReasoningDelta(event as AgentEvent<"reasoning.delta">);
+    });
+    this.unsubscribers.push(unsubReasoningDelta);
+
+    // Subscribe to reasoning complete events
+    const unsubReasoningComplete = this.client.on("reasoning.complete", (event) => {
+      if (!this.isActive || event.sessionId !== this.sessionId) return;
+      this.handleReasoningComplete(event as AgentEvent<"reasoning.complete">);
+    });
+    this.unsubscribers.push(unsubReasoningComplete);
+
+    // Subscribe to subagent start events
+    const unsubSubagentStart = this.client.on("subagent.start", (event) => {
+      if (!this.isActive || event.sessionId !== this.sessionId) return;
+      this.handleSubagentStart(event as AgentEvent<"subagent.start">);
+    });
+    this.unsubscribers.push(unsubSubagentStart);
+
+    // Subscribe to subagent complete events
+    const unsubSubagentComplete = this.client.on("subagent.complete", (event) => {
+      if (!this.isActive || event.sessionId !== this.sessionId) return;
+      this.handleSubagentComplete(event as AgentEvent<"subagent.complete">);
+    });
+    this.unsubscribers.push(unsubSubagentComplete);
+
+    const unsubSubagentUpdate = this.client.on("subagent.update", (event) => {
+      if (!this.isActive || event.sessionId !== this.sessionId) return;
+      this.handleSubagentUpdate(event as AgentEvent<"subagent.update">);
+    });
+    this.unsubscribers.push(unsubSubagentUpdate);
+
+    // Subscribe to turn lifecycle events
+    const unsubTurnStart = this.client.on("turn.start", (event) => {
+      if (!this.isActive || event.sessionId !== this.sessionId) return;
+      this.handleTurnStart(event as AgentEvent<"turn.start">);
+    });
+    this.unsubscribers.push(unsubTurnStart);
+
+    const unsubTurnEnd = this.client.on("turn.end", (event) => {
+      if (!this.isActive || event.sessionId !== this.sessionId) return;
+      this.handleTurnEnd(event as AgentEvent<"turn.end">);
+    });
+    this.unsubscribers.push(unsubTurnEnd);
+
+    // Subscribe to tool partial result events (streaming tool output)
+    const unsubToolPartial = this.client.on("tool.partial_result", (event) => {
+      if (!this.isActive || event.sessionId !== this.sessionId) return;
+      this.handleToolPartialResult(event as AgentEvent<"tool.partial_result">);
+    });
+    this.unsubscribers.push(unsubToolPartial);
+
+    // Subscribe to session info/warning/title/truncation/compaction events
+    const unsubInfo = this.client.on("session.info", (event) => {
+      if (!this.isActive || event.sessionId !== this.sessionId) return;
+      this.handleSessionInfo(event as AgentEvent<"session.info">);
+    });
+    this.unsubscribers.push(unsubInfo);
+
+    const unsubWarning = this.client.on("session.warning", (event) => {
+      if (!this.isActive || event.sessionId !== this.sessionId) return;
+      this.handleSessionWarning(event as AgentEvent<"session.warning">);
+    });
+    this.unsubscribers.push(unsubWarning);
+
+    const unsubTitleChanged = this.client.on("session.title_changed", (event) => {
+      if (!this.isActive || event.sessionId !== this.sessionId) return;
+      this.handleSessionTitleChanged(event as AgentEvent<"session.title_changed">);
+    });
+    this.unsubscribers.push(unsubTitleChanged);
+
+    const unsubTruncation = this.client.on("session.truncation", (event) => {
+      if (!this.isActive || event.sessionId !== this.sessionId) return;
+      this.handleSessionTruncation(event as AgentEvent<"session.truncation">);
+    });
+    this.unsubscribers.push(unsubTruncation);
+
+    const unsubCompaction = this.client.on("session.compaction", (event) => {
+      if (!this.isActive || event.sessionId !== this.sessionId) return;
+      this.handleSessionCompaction(event as AgentEvent<"session.compaction">);
+    });
+    this.unsubscribers.push(unsubCompaction);
+  }
+
+  /**
+   * Check if a tool name corresponds to a task/agent-launching tool.
+   */
+  private isTaskTool(toolName: string): boolean {
+    const normalized = toolName.toLowerCase();
+    return normalized === "task"
+      || normalized === "launch_agent"
+      || this.knownAgentNames.has(normalized);
+  }
+
+  /**
+   * Handle message.delta event (text or thinking content).
+   */
+  private handleMessageDelta(event: AgentEvent<"message.delta">): void {
+    const { delta, contentType, thinkingSourceKey } = event.data;
+
+    const parentToolCallId = this.asString((event.data as Record<string, unknown>).parentToolCallId);
+    const agentId = parentToolCallId
+      ? this.toolCallIdToSubagentId.get(parentToolCallId) ?? parentToolCallId
+      : undefined;
+
+    // Check if this is thinking/reasoning content
+    if (contentType === "thinking" && thinkingSourceKey) {
+      // Thinking delta
+      if (!this.thinkingStreams.has(thinkingSourceKey)) {
+        this.thinkingStreams.set(thinkingSourceKey, Date.now());
+      }
+
+      this.publishEvent({
+        type: "stream.thinking.delta",
+        sessionId: this.sessionId,
+        runId: this.runId,
+        timestamp: Date.now(),
+        data: {
+          delta,
+          sourceKey: thinkingSourceKey,
+          messageId: this.messageId,
+          ...(agentId ? { agentId } : {}),
+        },
+      });
+    } else {
+      // Regular text delta
+      if (!agentId) {
+        this.accumulatedText += delta;
+      }
+
+      if (delta.length > 0) {
+        this.publishEvent({
+          type: "stream.text.delta",
+          sessionId: this.sessionId,
+          runId: this.runId,
+          timestamp: Date.now(),
+          data: {
+            delta,
+            messageId: this.messageId,
+            ...(agentId ? { agentId } : {}),
+          },
+        });
+      }
+    }
+  }
+
+  /**
+   * Handle message.complete event.
+   *
+   * In the Copilot CLI, tool call UI entries are created from
+   * `assistant.message.toolRequests[]` inside this event — NOT from
+   * `tool.execution_start`. We mirror that behaviour here by emitting
+   * `stream.tool.start` for each tool request, then deduplicating against
+   * the later `tool.execution_start` in `handleToolStart`.
+   */
+  private handleMessageComplete(event: AgentEvent<"message.complete">): void {
+    // Skip sub-agent message completions — they belong to a child agent.
+    // Inner tool calls are tracked via tool.execution_start (which carries
+    // parentId) and the SubagentToolTracker, NOT from message.complete.
+    const parentToolCallId = (event.data as Record<string, unknown>).parentToolCallId;
+    if (parentToolCallId) return;
+
+    // Publish thinking complete events for any active thinking streams
+    for (const [sourceKey, startTime] of this.thinkingStreams.entries()) {
+      const durationMs = Date.now() - startTime;
+      this.publishEvent({
+        type: "stream.thinking.complete",
+        sessionId: this.sessionId,
+        runId: this.runId,
+        timestamp: Date.now(),
+        data: {
+          sourceKey,
+          durationMs,
+        },
+      });
+    }
+
+    // Clear thinking streams after completion
+    this.thinkingStreams.clear();
+
+    // Emit stream.tool.start for each toolRequest in the message.complete payload.
+    // This mirrors the Copilot CLI's useTimeline.ts behaviour where tool call UI
+    // entries are created from assistant.message.toolRequests.
+    const toolRequests = (event.data as Record<string, unknown>).toolRequests;
+    const hasToolRequests = Array.isArray(toolRequests) && toolRequests.length > 0;
+
+    if (hasToolRequests) {
+      for (const request of toolRequests as Array<Record<string, unknown>>) {
+        const toolCallId = this.asString(request.toolCallId);
+        const toolName = this.normalizeToolName(request.name);
+        const toolInput = this.normalizeToolInput(request.arguments);
+        if (!toolCallId) continue;
+
+        // Extract metadata from task tool arguments for subagent enrichment
+        if (this.isTaskTool(toolName) && request.arguments) {
+          const args = this.asRecord(request.arguments) ?? {};
+          this.taskToolMetadata.set(toolCallId, {
+            description: typeof args.description === "string" ? args.description
+              : typeof args.prompt === "string" ? args.prompt
+              : "",
+            isBackground: args.mode === "background" || args.run_in_background === true,
+          });
+        }
+
+        this.emittedToolStartIds.add(toolCallId);
+        const toolId = this.resolveToolStartId(toolCallId, toolName);
+
+        this.publishEvent({
+          type: "stream.tool.start",
+          sessionId: this.sessionId,
+          runId: this.runId,
+          timestamp: Date.now(),
+          data: {
+            toolId,
+            toolName,
+            toolInput,
+            sdkCorrelationId: toolCallId,
+          },
+        });
+      }
+    }
+
+    // Only emit stream.text.complete when there are NO pending tool requests.
+    //
+    // In the Copilot turn-based model, assistant.message events with toolRequests
+    // are intermediate — the turn continues with tool execution followed by another
+    // assistant message. Emitting stream.text.complete here would trigger
+    // handleStreamComplete in the UI (via direct bus subscription), which nulls
+    // streamingMessageIdRef BEFORE the batched tool-start events arrive (16ms
+    // batch-dispatcher delay), causing tool parts to be silently dropped.
+    //
+    // When tool requests are present, finalization is deferred to session.idle
+    // or a subsequent message.complete without tool requests.
+    if (!hasToolRequests && this.accumulatedText.length > 0) {
+      this.publishEvent({
+        type: "stream.text.complete",
+        sessionId: this.sessionId,
+        runId: this.runId,
+        timestamp: Date.now(),
+        data: {
+          messageId: this.messageId,
+          fullText: this.accumulatedText,
+        },
+      });
+    }
+  }
+
+  /**
+   * Handle tool.start event.
+   *
+   * Deduplicates against tool starts already emitted from
+   * `handleMessageComplete` (via `assistant.message.toolRequests`).
+   */
+  private handleToolStart(event: AgentEvent<"tool.start">): void {
+    const { toolName, toolInput, toolUseId, toolCallId } = event.data;
+
+    // Use toolCallId (Copilot) or toolUseId (Claude) as the unique ID
+    const explicitToolId = this.asString(toolCallId || toolUseId);
+
+    // Skip if already emitted from assistant.message.toolRequests
+    if (explicitToolId && this.emittedToolStartIds.has(explicitToolId)) {
+      return;
+    }
+
+    const resolvedToolName = this.normalizeToolName(toolName);
+    const toolId = this.resolveToolStartId(explicitToolId, resolvedToolName);
+
+    // Resolve the parent agent ID from either parentId (direct) or
+    // parentToolCallId (Copilot SDK: the task tool call ID that spawned the agent).
+    const rawParentId = this.asString((event.data as Record<string, unknown>).parentId);
+    const rawParentToolCallId = this.asString((event.data as Record<string, unknown>).parentToolCallId);
+    const parentAgentId = rawParentId
+      ?? (rawParentToolCallId ? this.toolCallIdToSubagentId.get(rawParentToolCallId) : undefined)
+      ?? undefined;
+
+    this.publishEvent({
+      type: "stream.tool.start",
+      sessionId: this.sessionId,
+      runId: this.runId,
+      timestamp: Date.now(),
+      data: {
+        toolId,
+        toolName: resolvedToolName,
+        toolInput: this.normalizeToolInput(toolInput),
+        sdkCorrelationId: explicitToolId ?? toolId,
+        parentAgentId,
+      },
+    });
+
+    // Track tool start for sub-agent if this tool belongs to one.
+    // Also record the tool call ID as an "inner" tool call so that
+    // nested subagent.start events (whose toolCallId matches) can be
+    // detected and suppressed from the top-level agent tree.
+    if (parentAgentId) {
+      this.recordActiveSubagentToolContext(toolId, resolvedToolName, parentAgentId, explicitToolId);
+      if (explicitToolId) {
+        this.innerToolCallIds.add(explicitToolId);
+      }
+      if (this.subagentTracker?.hasAgent(parentAgentId)) {
+        this.subagentTracker.onToolStart(parentAgentId, resolvedToolName);
+      } else {
+        // Buffer for subagents not yet registered (race condition).
+        // Key by parentAgentId when available, otherwise by the raw
+        // parentToolCallId so handleSubagentStart can replay them.
+        const bufferKey = parentAgentId;
+        const queue = this.earlyToolEvents.get(bufferKey) ?? [];
+        queue.push({ toolName: resolvedToolName });
+        this.earlyToolEvents.set(bufferKey, queue);
+      }
+    } else if (rawParentToolCallId) {
+      // parentToolCallId present but mapping not yet established
+      // (subagent.start hasn't arrived). Buffer by toolCallId.
+      const queue = this.earlyToolEvents.get(rawParentToolCallId) ?? [];
+      queue.push({ toolName: resolvedToolName });
+      this.earlyToolEvents.set(rawParentToolCallId, queue);
+    }
+  }
+
+  /**
+   * Handle tool.complete event.
+   */
+  private handleToolComplete(event: AgentEvent<"tool.complete">): void {
+    const { toolName, toolResult, success, error, toolUseId, toolCallId } =
+      event.data;
+
+    // Use toolCallId (Copilot) or toolUseId (Claude) as the unique ID
+    const explicitToolId = this.asString(toolCallId || toolUseId);
+    const toolId = this.resolveToolCompleteId(explicitToolId, toolName);
+    const resolvedToolName = this.normalizeToolName(toolName ?? this.toolNameById.get(toolId));
+    const toolInput = this.normalizeToolInput((event.data as Record<string, unknown>).toolInput);
+    this.toolNameById.delete(toolId);
+    this.removeActiveSubagentToolContext(toolId, explicitToolId);
+
+    // Clean up deduplication tracking
+    if (explicitToolId) {
+      this.emittedToolStartIds.delete(explicitToolId);
+    }
+    const normalizedSuccess = typeof success === "boolean" ? success : true;
+
+    // Track tool completion for sub-agent if this tool belongs to one
+    const rawParentIdComplete = this.asString((event.data as Record<string, unknown>).parentId);
+    const rawParentToolCallIdComplete = this.asString((event.data as Record<string, unknown>).parentToolCallId);
+    const resolvedParentId = rawParentIdComplete
+      ?? (rawParentToolCallIdComplete ? this.toolCallIdToSubagentId.get(rawParentToolCallIdComplete) : undefined)
+      ?? undefined;
+    if (resolvedParentId && this.subagentTracker?.hasAgent(resolvedParentId)) {
+      this.subagentTracker.onToolComplete(resolvedParentId);
+    }
+
+    this.publishEvent({
+      type: "stream.tool.complete",
+      sessionId: this.sessionId,
+      runId: this.runId,
+      timestamp: Date.now(),
+      data: {
+        toolId,
+        toolName: resolvedToolName,
+        toolInput,
+        toolResult,
+        success: normalizedSuccess,
+        error,
+        sdkCorrelationId: explicitToolId ?? toolId,
+        parentAgentId: resolvedParentId,
+      },
+    });
+  }
+
+  /**
+   * Handle session.idle event.
+   */
+  private handleSessionIdle(event: AgentEvent<"session.idle">): void {
+    const { reason } = event.data;
+
+    this.publishEvent({
+      type: "stream.session.idle",
+      sessionId: this.sessionId,
+      runId: this.runId,
+      timestamp: Date.now(),
+      data: {
+        reason,
+      },
+    });
+  }
+
+  /**
+   * Handle session.error event.
+   */
+  private handleSessionError(event: AgentEvent<"session.error">): void {
+    const { error, code } = event.data;
+
+    this.publishEvent({
+      type: "stream.session.error",
+      sessionId: this.sessionId,
+      runId: this.runId,
+      timestamp: Date.now(),
+      data: {
+        error: error instanceof Error ? error.message : String(error),
+        code,
+      },
+    });
+  }
+
+  /**
+   * Handle usage event.
+   *
+   * Copilot SDK emits `assistant.usage` per API call with per-call token
+   * counts. We accumulate output tokens across calls so the bus event
+   * carries a running total (suitable for direct display in the UI).
+   */
+  private handleUsage(event: AgentEvent<"usage">): void {
+    const data = event.data as Record<string, unknown>;
+
+    const inputTokens = (data.inputTokens as number) || 0;
+    const outputTokens = (data.outputTokens as number) || 0;
+    const model = data.model as string | undefined;
+
+    // Skip zero-valued events (e.g. from unmapped metadata events)
+    if (outputTokens <= 0 && inputTokens <= 0) return;
+
+    // Accumulate output tokens across multi-turn API calls
+    this.accumulatedOutputTokens += outputTokens;
+
+    this.publishEvent({
+      type: "stream.usage",
+      sessionId: this.sessionId,
+      runId: this.runId,
+      timestamp: Date.now(),
+      data: {
+        inputTokens,
+        outputTokens: this.accumulatedOutputTokens,
+        model,
+      },
+    });
+  }
+
+  /**
+   * Handle permission.requested event.
+   */
+  private handlePermissionRequested(event: AgentEvent<"permission.requested">): void {
+    const data = event.data as PermissionRequestedEventData;
+    this.publishEvent({
+      type: "stream.permission.requested",
+      sessionId: this.sessionId,
+      runId: this.runId,
+      timestamp: Date.now(),
+      data: {
+        requestId: data.requestId,
+        toolName: data.toolName,
+        toolInput: (data.toolInput as Record<string, unknown> | undefined),
+        question: data.question,
+        header: data.header,
+        options: data.options,
+        multiSelect: data.multiSelect,
+        respond: data.respond,
+        toolCallId: data.toolCallId,
+      },
+    });
+  }
+
+  /**
+   * Handle human_input_required event.
+   */
+  private handleHumanInputRequired(event: AgentEvent<"human_input_required">): void {
+    const data = event.data as HumanInputRequiredEventData;
+    this.publishEvent({
+      type: "stream.human_input_required",
+      sessionId: this.sessionId,
+      runId: this.runId,
+      timestamp: Date.now(),
+      data: {
+        requestId: data.requestId,
+        question: data.question,
+        header: data.header,
+        options: data.options,
+        nodeId: data.nodeId,
+        respond: data.respond,
+      },
+    });
+  }
+
+  /**
+   * Handle skill.invoked event.
+   */
+  private handleSkillInvoked(event: AgentEvent<"skill.invoked">): void {
+    const data = event.data as SkillInvokedEventData;
+    this.publishEvent({
+      type: "stream.skill.invoked",
+      sessionId: this.sessionId,
+      runId: this.runId,
+      timestamp: Date.now(),
+      data: {
+        skillName: data.skillName,
+        skillPath: data.skillPath,
+      },
+    });
+  }
+
+  /**
+   * Handle reasoning.delta event (thinking content from Copilot SDK).
+   */
+  private handleReasoningDelta(event: AgentEvent<"reasoning.delta">): void {
+    const data = event.data as ReasoningDeltaEventData;
+    const reasoningId = data.reasoningId ?? "reasoning";
+
+    if (!this.thinkingStreams.has(reasoningId)) {
+      this.thinkingStreams.set(reasoningId, Date.now());
+    }
+
+    this.publishEvent({
+      type: "stream.thinking.delta",
+      sessionId: this.sessionId,
+      runId: this.runId,
+      timestamp: Date.now(),
+      data: {
+        delta: data.delta,
+        sourceKey: reasoningId,
+        messageId: this.messageId,
+      },
+    });
+  }
+
+  /**
+   * Handle reasoning.complete event.
+   */
+  private handleReasoningComplete(event: AgentEvent<"reasoning.complete">): void {
+    const data = event.data as ReasoningCompleteEventData;
+    const reasoningId = data.reasoningId ?? "reasoning";
+    const startTime = this.thinkingStreams.get(reasoningId) ?? Date.now();
+    const durationMs = Date.now() - startTime;
+    this.thinkingStreams.delete(reasoningId);
+
+    this.publishEvent({
+      type: "stream.thinking.complete",
+      sessionId: this.sessionId,
+      runId: this.runId,
+      timestamp: Date.now(),
+      data: {
+        sourceKey: reasoningId,
+        durationMs,
+      },
+    });
+  }
+
+  /**
+   * Handle subagent.start event.
+   */
+  private handleSubagentStart(event: AgentEvent<"subagent.start">): void {
+    const data = event.data as SubagentStartEventData;
+    const toolCallId = data.toolCallId ?? data.subagentId;
+
+    // Skip nested sub-agents (spawned by another sub-agent).
+    // If toolCallId was recorded as an inner tool call (from handleToolStart
+    // with parentAgentId), this is a nested agent and should not appear as
+    // a top-level entry in the agent tree.
+    if (this.innerToolCallIds.has(toolCallId)) {
+      this.suppressedNestedAgentIds.add(data.subagentId);
+      this.suppressedNestedAgentIds.add(toolCallId);
+      this.earlyToolEvents.delete(data.subagentId);
+      this.earlyToolEvents.delete(toolCallId);
+      return;
+    }
+
+    // Look up task metadata from the parent task tool call
+    const metadata = this.taskToolMetadata.get(toolCallId);
+    const normalizedMetadata = normalizeAgentTaskMetadata(
+      {
+        task: metadata?.description ?? data.task,
+        agentType: data.subagentType,
+        isBackground: metadata?.isBackground,
+      },
+    );
+
+    // Register agent with tracker for tool counting
+    this.subagentTracker?.registerAgent(data.subagentId);
+
+    // Map task-tool toolCallId → subagentId so inner tool events
+    // (which carry parentToolCallId, not parentId) can be resolved.
+    if (toolCallId !== data.subagentId) {
+      this.toolCallIdToSubagentId.set(toolCallId, data.subagentId);
+    }
+
+    // Replay any early tool events that arrived before this subagent.started.
+    // Events may be keyed by subagentId (parentId path) or toolCallId
+    // (parentToolCallId path, before the mapping existed).
+    for (const key of [data.subagentId, toolCallId]) {
+      const earlyTools = this.earlyToolEvents.get(key);
+      if (earlyTools) {
+        for (const tool of earlyTools) {
+          this.subagentTracker?.onToolStart(data.subagentId, tool.toolName);
+        }
+        this.earlyToolEvents.delete(key);
+      }
+    }
+
+    this.publishEvent({
+      type: "stream.agent.start",
+      sessionId: this.sessionId,
+      runId: this.runId,
+      timestamp: Date.now(),
+      data: {
+        agentId: data.subagentId,
+        toolCallId,
+        agentType: data.subagentType ?? "unknown",
+        task: normalizedMetadata.task,
+        isBackground: normalizedMetadata.isBackground,
+        sdkCorrelationId: toolCallId,
+      },
+    });
+  }
+
+  /**
+   * Handle subagent.complete event.
+   */
+  private handleSubagentComplete(event: AgentEvent<"subagent.complete">): void {
+    const data = event.data as SubagentCompleteEventData;
+
+    if (this.suppressedNestedAgentIds.has(data.subagentId)) {
+      this.suppressedNestedAgentIds.delete(data.subagentId);
+      this.earlyToolEvents.delete(data.subagentId);
+      return;
+    }
+
+    this.suppressedNestedAgentIds.delete(data.subagentId);
+    this.subagentTracker?.removeAgent(data.subagentId);
+    this.taskToolMetadata.delete(data.subagentId);
+    this.earlyToolEvents.delete(data.subagentId);
+    // Clean up toolCallId → subagentId mapping
+    for (const [tcId, agentId] of this.toolCallIdToSubagentId) {
+      if (agentId === data.subagentId) {
+        this.toolCallIdToSubagentId.delete(tcId);
+        break;
+      }
+    }
+    this.publishEvent({
+      type: "stream.agent.complete",
+      sessionId: this.sessionId,
+      runId: this.runId,
+      timestamp: Date.now(),
+      data: {
+        agentId: data.subagentId,
+        success: data.success,
+        result: typeof data.result === "string" ? data.result : undefined,
+        error: typeof (data as Record<string, unknown>).error === "string"
+          ? (data as Record<string, unknown>).error as string
+          : undefined,
+      },
+    });
+  }
+
+  /**
+   * Handle subagent.update event.
+   */
+  private handleSubagentUpdate(event: AgentEvent<"subagent.update">): void {
+    const data = event.data as SubagentUpdateEventData;
+    if (this.suppressedNestedAgentIds.has(data.subagentId)) {
+      return;
+    }
+    this.publishEvent({
+      type: "stream.agent.update",
+      sessionId: this.sessionId,
+      runId: this.runId,
+      timestamp: Date.now(),
+      data: {
+        agentId: data.subagentId,
+        currentTool: data.currentTool,
+        toolUses: data.toolUses,
+      },
+    });
+  }
+
+  /**
+   * Handle turn.start event.
+   */
+  private handleTurnStart(event: AgentEvent<"turn.start">): void {
+    const data = event.data as TurnStartEventData;
+    this.publishEvent({
+      type: "stream.turn.start",
+      sessionId: this.sessionId,
+      runId: this.runId,
+      timestamp: Date.now(),
+      data: {
+        turnId: normalizeTurnStartId(
+          data.turnId,
+          this.turnMetadataState,
+        ),
+      },
+    });
+  }
+
+  /**
+   * Handle turn.end event.
+   */
+  private handleTurnEnd(event: AgentEvent<"turn.end">): void {
+    const data = event.data as TurnEndEventData;
+    this.publishEvent({
+      type: "stream.turn.end",
+      sessionId: this.sessionId,
+      runId: this.runId,
+      timestamp: Date.now(),
+      data: normalizeTurnEndMetadata(
+        data,
+        this.turnMetadataState,
+      ),
+    });
+  }
+
+  /**
+   * Handle tool.partial_result event (streaming tool output).
+   */
+  private handleToolPartialResult(event: AgentEvent<"tool.partial_result">): void {
+    const data = event.data as ToolPartialResultEventData;
+    this.publishEvent({
+      type: "stream.tool.partial_result",
+      sessionId: this.sessionId,
+      runId: this.runId,
+      timestamp: Date.now(),
+      data: {
+        toolCallId: data.toolCallId,
+        partialOutput: data.partialOutput,
+      },
+    });
+
+    const toolCallId = this.asString(data.toolCallId);
+    if (!toolCallId) {
+      return;
+    }
+    const context = this.activeSubagentToolsById.get(toolCallId);
+    if (context && this.subagentTracker?.hasAgent(context.parentAgentId)) {
+      this.subagentTracker.onToolProgress(context.parentAgentId, context.toolName);
+    }
+  }
+
+  /**
+   * Handle session.info event.
+   */
+  private handleSessionInfo(event: AgentEvent<"session.info">): void {
+    const data = event.data as SessionInfoEventData;
+    this.publishEvent({
+      type: "stream.session.info",
+      sessionId: this.sessionId,
+      runId: this.runId,
+      timestamp: Date.now(),
+      data: {
+        infoType: data.infoType ?? "general",
+        message: data.message ?? "",
+      },
+    });
+  }
+
+  /**
+   * Handle session.warning event.
+   */
+  private handleSessionWarning(event: AgentEvent<"session.warning">): void {
+    const data = event.data as SessionWarningEventData;
+    this.publishEvent({
+      type: "stream.session.warning",
+      sessionId: this.sessionId,
+      runId: this.runId,
+      timestamp: Date.now(),
+      data: {
+        warningType: data.warningType ?? "general",
+        message: data.message ?? "",
+      },
+    });
+  }
+
+  /**
+   * Handle session.title_changed event.
+   */
+  private handleSessionTitleChanged(event: AgentEvent<"session.title_changed">): void {
+    const data = event.data as SessionTitleChangedEventData;
+    this.publishEvent({
+      type: "stream.session.title_changed",
+      sessionId: this.sessionId,
+      runId: this.runId,
+      timestamp: Date.now(),
+      data: {
+        title: data.title ?? "",
+      },
+    });
+  }
+
+  /**
+   * Handle session.truncation event.
+   */
+  private handleSessionTruncation(event: AgentEvent<"session.truncation">): void {
+    const data = event.data as SessionTruncationEventData;
+    this.publishEvent({
+      type: "stream.session.truncation",
+      sessionId: this.sessionId,
+      runId: this.runId,
+      timestamp: Date.now(),
+      data: {
+        tokenLimit: data.tokenLimit ?? 0,
+        tokensRemoved: data.tokensRemoved ?? 0,
+        messagesRemoved: data.messagesRemoved ?? 0,
+      },
+    });
+  }
+
+  /**
+   * Handle session.compaction event.
+   */
+  private handleSessionCompaction(event: AgentEvent<"session.compaction">): void {
+    const data = event.data as SessionCompactionEventData;
+    this.publishEvent({
+      type: "stream.session.compaction",
+      sessionId: this.sessionId,
+      runId: this.runId,
+      timestamp: Date.now(),
+      data: {
+        phase: data.phase,
+        success: data.success,
+        error: data.error,
+      },
+    });
+  }
+
+  private asString(value: unknown): string | undefined {
+    return typeof value === "string" && value.trim().length > 0
+      ? value
+      : undefined;
+  }
+
+  private asRecord(value: unknown): Record<string, unknown> | undefined {
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+      return value as Record<string, unknown>;
+    }
+    return undefined;
+  }
+
+  private normalizeToolName(value: unknown): string {
+    return this.asString(value) ?? "unknown";
+  }
+
+  private normalizeToolInput(value: unknown): Record<string, unknown> {
+    const record = this.asRecord(value);
+    if (record) {
+      return record;
+    }
+
+    if (value === undefined || value === null) {
+      return {};
+    }
+
+    if (typeof value === "string") {
+      const trimmed = value.trim();
+      if (trimmed.length === 0) {
+        return {};
+      }
+      try {
+        const parsed = JSON.parse(trimmed) as unknown;
+        const parsedRecord = this.asRecord(parsed);
+        if (parsedRecord) {
+          return parsedRecord;
+        }
+      } catch {
+        // Keep the raw string payload when it's not valid JSON.
+      }
+      return { value };
+    }
+
+    return { value };
+  }
+
+  private createSyntheticToolId(toolName: string): string {
+    this.syntheticToolCounter += 1;
+    const normalizedName = toolName.replace(/[^a-zA-Z0-9_-]/g, "_");
+    return `tool_${this.runId}_${normalizedName}_${this.syntheticToolCounter}`;
+  }
+
+  private queueToolId(toolName: string, toolId: string): void {
+    const queue = this.pendingToolIdsByName.get(toolName) ?? [];
+    if (!queue.includes(toolId)) {
+      queue.push(toolId);
+      this.pendingToolIdsByName.set(toolName, queue);
+    }
+    this.toolNameById.set(toolId, toolName);
+  }
+
+  private removeQueuedToolId(toolName: string, toolId: string): void {
+    const queue = this.pendingToolIdsByName.get(toolName);
+    if (!queue) return;
+    const nextQueue = queue.filter((queuedId) => queuedId !== toolId);
+    if (nextQueue.length === 0) {
+      this.pendingToolIdsByName.delete(toolName);
+      return;
+    }
+    this.pendingToolIdsByName.set(toolName, nextQueue);
+  }
+
+  private shiftQueuedToolId(toolName: string): string | undefined {
+    const queue = this.pendingToolIdsByName.get(toolName);
+    if (!queue || queue.length === 0) {
+      return undefined;
+    }
+    const [toolId, ...rest] = queue;
+    if (rest.length === 0) {
+      this.pendingToolIdsByName.delete(toolName);
+    } else {
+      this.pendingToolIdsByName.set(toolName, rest);
+    }
+    return toolId;
+  }
+
+  private resolveToolStartId(explicitToolId: string | undefined, toolName: string): string {
+    const toolId = explicitToolId ?? this.createSyntheticToolId(toolName);
+    this.queueToolId(toolName, toolId);
+    return toolId;
+  }
+
+  private resolveToolCompleteId(
+    explicitToolId: string | undefined,
+    toolName: unknown,
+  ): string {
+    if (explicitToolId) {
+      const resolvedName = this.normalizeToolName(toolName ?? this.toolNameById.get(explicitToolId));
+      this.removeQueuedToolId(resolvedName, explicitToolId);
+      return explicitToolId;
+    }
+
+    const resolvedName = this.normalizeToolName(toolName);
+    return this.shiftQueuedToolId(resolvedName) ?? this.createSyntheticToolId(resolvedName);
+  }
+
+  private recordActiveSubagentToolContext(
+    toolId: string,
+    toolName: string,
+    parentAgentId: string,
+    ...correlationIds: Array<string | undefined>
+  ): void {
+    const context = { parentAgentId, toolName };
+    const ids = [toolId, ...correlationIds].filter((id): id is string => Boolean(id));
+    for (const id of ids) {
+      this.activeSubagentToolsById.set(id, context);
+    }
+  }
+
+  private removeActiveSubagentToolContext(
+    toolId: string,
+    ...correlationIds: Array<string | undefined>
+  ): void {
+    const ids = [toolId, ...correlationIds].filter((id): id is string => Boolean(id));
+    for (const id of ids) {
+      this.activeSubagentToolsById.delete(id);
+    }
+  }
+
+  /**
+   * Publish an event to the bus with backpressure management.
+   *
+   * Uses a bounded buffer to prevent memory exhaustion when events
+   * arrive faster than they can be processed.
+   */
+  private publishEvent(event: BusEvent): void {
+    // Add to buffer
+    this.eventBuffer.push(event);
+
+    // Enforce buffer size limit (drop oldest events if overflow)
+    if (this.eventBuffer.length - this.eventBufferHead > MAX_BUFFER_SIZE) {
+      const dropped = this.eventBuffer[this.eventBufferHead];
+      this.eventBufferHead += 1;
+      this.compactEventBuffer();
+      console.warn(
+        `[CopilotStreamAdapter] Buffer overflow: dropped event type=${dropped?.type}`,
+      );
+    }
+
+    // Start processing buffer if not already processing
+    if (!this.isProcessing) {
+      this.processBuffer();
+    }
+  }
+
+  /**
+   * Process events from the buffer.
+   * Flushes all buffered events to the event bus.
+   */
+  private processBuffer(): void {
+    this.isProcessing = true;
+
+    // Process all buffered events
+    while (this.eventBufferHead < this.eventBuffer.length) {
+      const event = this.eventBuffer[this.eventBufferHead];
+      this.eventBufferHead += 1;
+      if (event) {
+        try {
+          this.bus.publish(event);
+        } catch (error) {
+          console.error(
+            `[CopilotStreamAdapter] Error publishing event type=${event.type}:`,
+            error,
+          );
+        }
+      }
+    }
+
+    this.compactEventBuffer(true);
+    this.isProcessing = false;
+  }
+
+  private compactEventBuffer(force = false): void {
+    if (this.eventBufferHead === 0) {
+      return;
+    }
+
+    if (force || this.eventBufferHead >= this.eventBuffer.length) {
+      this.eventBuffer.length = 0;
+      this.eventBufferHead = 0;
+      return;
+    }
+
+    if (this.eventBufferHead >= 128 && this.eventBufferHead * 2 >= this.eventBuffer.length) {
+      this.eventBuffer = this.eventBuffer.slice(this.eventBufferHead);
+      this.eventBufferHead = 0;
+    }
+  }
+
+  /**
+   * Clean up adapter resources.
+   *
+   * Removes all registered event listeners and clears internal state.
+   */
+  /**
+   * Force-complete any tools that received start but no complete event.
+   * Prevents tools from being stuck in running state after stream abort.
+   */
+  private cleanupOrphanedTools(): void {
+    for (const [toolName, toolIds] of this.pendingToolIdsByName.entries()) {
+      for (const toolId of toolIds) {
+        this.publishEvent({
+          type: "stream.tool.complete",
+          sessionId: this.sessionId,
+          runId: this.runId,
+          timestamp: Date.now(),
+          data: {
+            toolId,
+            toolName,
+            toolResult: null,
+            success: false,
+            error: "Tool execution aborted",
+          },
+        });
+      }
+    }
+    this.pendingToolIdsByName.clear();
+    this.activeSubagentToolsById.clear();
+  }
+
+  /**
+   * Clean up SDK event subscriptions without full state reset.
+   */
+  private cleanupSubscriptions(): void {
+    for (const unsubscribe of this.unsubscribers) {
+      unsubscribe();
+    }
+    this.unsubscribers = [];
+  }
+
+  dispose(): void {
+    this.isActive = false;
+
+    // Unsubscribe all event handlers
+    this.cleanupSubscriptions();
+
+    // Clear buffer and state
+    this.eventBuffer = [];
+    this.eventBufferHead = 0;
+    this.thinkingStreams.clear();
+    this.accumulatedText = "";
+    this.accumulatedOutputTokens = 0;
+    this.pendingToolIdsByName.clear();
+    this.toolNameById.clear();
+    this.syntheticToolCounter = 0;
+    this.emittedToolStartIds.clear();
+    this.taskToolMetadata.clear();
+    this.earlyToolEvents.clear();
+    this.activeSubagentToolsById.clear();
+    this.toolCallIdToSubagentId.clear();
+    this.innerToolCallIds.clear();
+    this.suppressedNestedAgentIds.clear();
+    this.knownAgentNames.clear();
+    this.runtimeFeatureFlags = { ...DEFAULT_WORKFLOW_RUNTIME_FEATURE_FLAGS };
+    resetTurnMetadataState(this.turnMetadataState);
+    this.subagentTracker?.reset();
+    this.subagentTracker = null;
+  }
+
+  private resolveRuntimeFeatureFlags(
+    overrides: WorkflowRuntimeFeatureFlagOverrides | undefined,
+  ): WorkflowRuntimeFeatureFlags {
+    return resolveWorkflowRuntimeFeatureFlags(overrides);
+  }
+}
diff --git a/src/events/adapters/event-coverage-policy.e2e.test.ts b/src/events/adapters/event-coverage-policy.e2e.test.ts
new file mode 100644
index 0000000000..b2a5565c5f
--- /dev/null
+++ b/src/events/adapters/event-coverage-policy.e2e.test.ts
@@ -0,0 +1,51 @@
+import { describe, expect, test } from "bun:test";
+import {
+  ADAPTER_EVENT_COVERAGE_POLICY,
+  ALL_SDK_EVENT_TYPES,
+  assertAdapterEventCoveragePolicyInvariant,
+} from "./event-coverage-policy.ts";
+import {
+  getRuntimeParityMetricsSnapshot,
+  resetRuntimeParityMetrics,
+} from "../../workflows/runtime-parity-observability.ts";
+
+describe("event coverage policy e2e parity", () => {
+  test("validates parity metrics for all providers in one pass", () => {
+    resetRuntimeParityMetrics();
+    assertAdapterEventCoveragePolicyInvariant();
+
+    const metrics = getRuntimeParityMetricsSnapshot();
+    for (const provider of ["opencode", "claude", "copilot"] as const) {
+      expect(
+        metrics.counters[
+          `workflow.runtime.parity.event_coverage_validations_total{provider=${provider}}`
+        ],
+      ).toBe(1);
+      expect(
+        metrics.histograms[
+          `workflow.runtime.parity.event_coverage_mapped_events{provider=${provider}}`
+        ],
+      ).toEqual([ALL_SDK_EVENT_TYPES.length - 1]);
+      expect(
+        metrics.gauges[
+          `workflow.runtime.parity.event_coverage_noop_events{provider=${provider}}`
+        ],
+      ).toBe(1);
+    }
+  });
+
+  test("enforces explicit provider policy behavior for message.complete parity", () => {
+    expect(ADAPTER_EVENT_COVERAGE_POLICY.opencode["message.complete"]).toMatchObject({
+      disposition: "mapped_with_constraints",
+      canonicalEvents: ["stream.text.complete", "stream.thinking.complete"],
+    });
+    expect(ADAPTER_EVENT_COVERAGE_POLICY.claude["message.complete"]).toMatchObject({
+      disposition: "mapped_with_constraints",
+      canonicalEvents: ["stream.text.complete", "stream.thinking.complete"],
+    });
+    expect(ADAPTER_EVENT_COVERAGE_POLICY.copilot["message.complete"]).toMatchObject({
+      disposition: "mapped_with_constraints",
+      canonicalEvents: ["stream.text.complete", "stream.thinking.complete", "stream.tool.start"],
+    });
+  });
+});
diff --git a/src/events/adapters/event-coverage-policy.test.ts b/src/events/adapters/event-coverage-policy.test.ts
new file mode 100644
index 0000000000..05347f8beb
--- /dev/null
+++ b/src/events/adapters/event-coverage-policy.test.ts
@@ -0,0 +1,62 @@
+import { describe, expect, test } from "bun:test";
+import {
+  ADAPTER_EVENT_COVERAGE_POLICY,
+  ALL_SDK_EVENT_TYPES,
+  assertAdapterEventCoveragePolicyInvariant,
+} from "./event-coverage-policy.ts";
+import {
+  getRuntimeParityMetricsSnapshot,
+  resetRuntimeParityMetrics,
+} from "../../workflows/runtime-parity-observability.ts";
+
+describe("adapter event coverage policy", () => {
+  test("records validation parity metrics", () => {
+    resetRuntimeParityMetrics();
+    assertAdapterEventCoveragePolicyInvariant();
+
+    const metrics = getRuntimeParityMetricsSnapshot();
+    expect(metrics.counters["workflow.runtime.parity.event_coverage_validations_total{provider=opencode}"]).toBe(1);
+    expect(metrics.counters["workflow.runtime.parity.event_coverage_validations_total{provider=claude}"]).toBe(1);
+    expect(metrics.counters["workflow.runtime.parity.event_coverage_validations_total{provider=copilot}"]).toBe(1);
+  });
+
+  test("defines coverage for every SDK event type per provider", () => {
+    for (const provider of Object.keys(ADAPTER_EVENT_COVERAGE_POLICY)) {
+      const coverage = ADAPTER_EVENT_COVERAGE_POLICY[provider as keyof typeof ADAPTER_EVENT_COVERAGE_POLICY];
+
+      for (const eventType of ALL_SDK_EVENT_TYPES) {
+        expect(coverage[eventType]).toBeDefined();
+      }
+    }
+  });
+
+  test("every coverage rule is explicit", () => {
+    for (const coverage of Object.values(ADAPTER_EVENT_COVERAGE_POLICY)) {
+      for (const eventType of ALL_SDK_EVENT_TYPES) {
+        const rule = coverage[eventType];
+        expect(rule.disposition).toBeDefined();
+        expect(rule.rationale.length).toBeGreaterThan(0);
+      }
+    }
+  });
+
+  test("throws descriptive errors when mapped rules are missing canonical coverage", () => {
+    resetRuntimeParityMetrics();
+    const invalidPolicy = {
+      ...ADAPTER_EVENT_COVERAGE_POLICY,
+      opencode: {
+        ...ADAPTER_EVENT_COVERAGE_POLICY.opencode,
+        "tool.start": {
+          disposition: "mapped" as const,
+          canonicalEvents: [],
+          rationale: "invalid",
+        },
+      },
+    };
+
+    expect(() => assertAdapterEventCoveragePolicyInvariant(invalidPolicy)).toThrow("must map at least one canonical event");
+
+    const metrics = getRuntimeParityMetricsSnapshot();
+    expect(metrics.counters["workflow.runtime.parity.event_coverage_invariant_failures_total{eventType=tool.start,provider=opencode,reason=missing_canonical_events}"]).toBe(1);
+  });
+});
diff --git a/src/events/adapters/event-coverage-policy.ts b/src/events/adapters/event-coverage-policy.ts
new file mode 100644
index 0000000000..dc1b5b3520
--- /dev/null
+++ b/src/events/adapters/event-coverage-policy.ts
@@ -0,0 +1,210 @@
+import type { BusEventType } from "../bus-events.ts";
+import type { EventType } from "../../sdk/types.ts";
+import {
+  incrementRuntimeParityCounter,
+  observeRuntimeParityHistogram,
+  runtimeParityDebug,
+  setRuntimeParityGauge,
+} from "../../workflows/runtime-parity-observability.ts";
+
+export type AdapterProvider = "opencode" | "claude" | "copilot";
+
+export type EventCoverageDisposition = "mapped" | "mapped_with_constraints" | "no_op";
+
+export interface EventCoverageRule {
+  disposition: EventCoverageDisposition;
+  canonicalEvents: BusEventType[];
+  rationale: string;
+}
+
+export const ALL_SDK_EVENT_TYPES: EventType[] = [
+  "session.start",
+  "session.idle",
+  "session.error",
+  "session.info",
+  "session.warning",
+  "session.title_changed",
+  "session.truncation",
+  "session.compaction",
+  "message.delta",
+  "message.complete",
+  "reasoning.delta",
+  "reasoning.complete",
+  "turn.start",
+  "turn.end",
+  "tool.start",
+  "tool.complete",
+  "tool.partial_result",
+  "skill.invoked",
+  "subagent.start",
+  "subagent.complete",
+  "subagent.update",
+  "permission.requested",
+  "human_input_required",
+  "usage",
+];
+
+type ProviderCoverage = Record<EventType, EventCoverageRule>;
+
+const OPENCODE_EVENT_COVERAGE: ProviderCoverage = {
+  "session.start": {
+    disposition: "no_op",
+    canonicalEvents: [],
+    rationale: "Adapter emits canonical stream.session.start at stream start.",
+  },
+  "session.idle": { disposition: "mapped", canonicalEvents: ["stream.session.idle"], rationale: "Session idle lifecycle." },
+  "session.error": { disposition: "mapped", canonicalEvents: ["stream.session.error"], rationale: "Session error lifecycle." },
+  "session.info": { disposition: "mapped", canonicalEvents: ["stream.session.info"], rationale: "Informational notifications." },
+  "session.warning": { disposition: "mapped", canonicalEvents: ["stream.session.warning"], rationale: "Warning notifications." },
+  "session.title_changed": {
+    disposition: "mapped",
+    canonicalEvents: ["stream.session.title_changed"],
+    rationale: "Session title updates.",
+  },
+  "session.truncation": {
+    disposition: "mapped",
+    canonicalEvents: ["stream.session.truncation"],
+    rationale: "Context truncation lifecycle.",
+  },
+  "session.compaction": {
+    disposition: "mapped",
+    canonicalEvents: ["stream.session.compaction"],
+    rationale: "Compaction lifecycle.",
+  },
+  "message.delta": {
+    disposition: "mapped_with_constraints",
+    canonicalEvents: ["stream.text.delta", "stream.thinking.delta"],
+    rationale: "Mapped by contentType and empty deltas are skipped.",
+  },
+  "message.complete": {
+    disposition: "mapped_with_constraints",
+    canonicalEvents: ["stream.text.complete", "stream.thinking.complete"],
+    rationale: "Finalizes accumulated text and active thinking blocks.",
+  },
+  "reasoning.delta": {
+    disposition: "mapped",
+    canonicalEvents: ["stream.thinking.delta"],
+    rationale: "Provider-native reasoning deltas map to canonical thinking deltas.",
+  },
+  "reasoning.complete": {
+    disposition: "mapped",
+    canonicalEvents: ["stream.thinking.complete"],
+    rationale: "Provider-native reasoning completion maps to canonical thinking completion.",
+  },
+  "turn.start": { disposition: "mapped", canonicalEvents: ["stream.turn.start"], rationale: "Turn lifecycle start." },
+  "turn.end": { disposition: "mapped", canonicalEvents: ["stream.turn.end"], rationale: "Turn lifecycle end." },
+  "tool.start": { disposition: "mapped", canonicalEvents: ["stream.tool.start"], rationale: "Tool lifecycle start." },
+  "tool.complete": { disposition: "mapped", canonicalEvents: ["stream.tool.complete"], rationale: "Tool lifecycle complete." },
+  "tool.partial_result": {
+    disposition: "mapped",
+    canonicalEvents: ["stream.tool.partial_result"],
+    rationale: "Streaming tool output chunks.",
+  },
+  "skill.invoked": { disposition: "mapped", canonicalEvents: ["stream.skill.invoked"], rationale: "Skill invocation events." },
+  "subagent.start": { disposition: "mapped", canonicalEvents: ["stream.agent.start"], rationale: "Sub-agent lifecycle start." },
+  "subagent.complete": {
+    disposition: "mapped",
+    canonicalEvents: ["stream.agent.complete"],
+    rationale: "Sub-agent lifecycle complete.",
+  },
+  "subagent.update": {
+    disposition: "mapped",
+    canonicalEvents: ["stream.agent.update"],
+    rationale: "Sub-agent progress updates.",
+  },
+  "permission.requested": {
+    disposition: "mapped",
+    canonicalEvents: ["stream.permission.requested"],
+    rationale: "Human approval flow.",
+  },
+  "human_input_required": {
+    disposition: "mapped",
+    canonicalEvents: ["stream.human_input_required"],
+    rationale: "Workflow human-input requests.",
+  },
+  usage: {
+    disposition: "mapped_with_constraints",
+    canonicalEvents: ["stream.usage"],
+    rationale: "Zero-token diagnostics are intentionally ignored.",
+  },
+};
+
+const CLAUDE_EVENT_COVERAGE: ProviderCoverage = {
+  ...OPENCODE_EVENT_COVERAGE,
+};
+
+const COPILOT_EVENT_COVERAGE: ProviderCoverage = {
+  ...OPENCODE_EVENT_COVERAGE,
+  "message.delta": {
+    disposition: "mapped_with_constraints",
+    canonicalEvents: ["stream.text.delta", "stream.thinking.delta"],
+    rationale: "Parent-tool deltas are mapped to agent-scoped deltas; main deltas remain in main stream.",
+  },
+  "message.complete": {
+    disposition: "mapped_with_constraints",
+    canonicalEvents: ["stream.text.complete", "stream.thinking.complete", "stream.tool.start"],
+    rationale: "Sub-agent message.complete with parentToolCallId is a no-op to avoid duplicate tool request starts.",
+  },
+};
+
+export const ADAPTER_EVENT_COVERAGE_POLICY: Record<AdapterProvider, ProviderCoverage> = {
+  opencode: OPENCODE_EVENT_COVERAGE,
+  claude: CLAUDE_EVENT_COVERAGE,
+  copilot: COPILOT_EVENT_COVERAGE,
+};
+
+export function assertAdapterEventCoveragePolicyInvariant(
+  policy: Record<AdapterProvider, ProviderCoverage> = ADAPTER_EVENT_COVERAGE_POLICY,
+): void {
+  const providers = Object.keys(policy) as AdapterProvider[];
+
+  for (const provider of providers) {
+    const coverage = policy[provider];
+    let mappedCount = 0;
+    let noopCount = 0;
+    for (const eventType of ALL_SDK_EVENT_TYPES) {
+      const rule = coverage[eventType];
+      if (!rule) {
+        incrementRuntimeParityCounter("workflow.runtime.parity.event_coverage_invariant_failures_total", {
+          provider,
+          reason: "missing_rule",
+          eventType,
+        });
+        throw new Error(`Event coverage invariant failed: provider ${provider} missing rule for ${eventType}`);
+      }
+
+      if (rule.disposition !== "no_op" && rule.canonicalEvents.length === 0) {
+        incrementRuntimeParityCounter("workflow.runtime.parity.event_coverage_invariant_failures_total", {
+          provider,
+          reason: "missing_canonical_events",
+          eventType,
+        });
+        throw new Error(
+          `Event coverage invariant failed: provider ${provider} rule ${eventType} must map at least one canonical event`,
+        );
+      }
+
+      if (rule.disposition === "no_op") {
+        noopCount += 1;
+      } else {
+        mappedCount += 1;
+      }
+    }
+
+    observeRuntimeParityHistogram(
+      "workflow.runtime.parity.event_coverage_mapped_events",
+      mappedCount,
+      { provider },
+    );
+    setRuntimeParityGauge("workflow.runtime.parity.event_coverage_noop_events", noopCount, { provider });
+    incrementRuntimeParityCounter("workflow.runtime.parity.event_coverage_validations_total", { provider });
+    runtimeParityDebug("event_coverage_validated", {
+      provider,
+      mappedCount,
+      noopCount,
+      total: ALL_SDK_EVENT_TYPES.length,
+    });
+  }
+}
+
+assertAdapterEventCoveragePolicyInvariant();
diff --git a/src/events/adapters/opencode-adapter.ts b/src/events/adapters/opencode-adapter.ts
new file mode 100644
index 0000000000..323764d839
--- /dev/null
+++ b/src/events/adapters/opencode-adapter.ts
@@ -0,0 +1,2479 @@
+/**
+ * OpenCode SDK Stream Adapter
+ *
+ * Consumes streaming events from the OpenCode SDK's event emitter
+ * and publishes them to the event bus as normalized BusEvents.
+ *
+ * Key responsibilities:
+ * - Subscribe to SDK events via client.on() (text, thinking, tool, subagent, session events)
+ * - Fire prompt via session.sendAsync() (fire-and-forget)
+ * - Map OpenCode SDK AgentEvent types to BusEvent types
+ * - Support cancellation via AbortController
+ * - Publish events directly to the event bus (no batching)
+ *
+ * Event mapping:
+ * - message.delta (text) → stream.text.delta
+ * - message.complete → stream.text.complete
+ * - message.delta (reasoning) → stream.thinking.delta
+ * - tool.start → stream.tool.start
+ * - tool.complete → stream.tool.complete
+ * - subagent.start → stream.agent.start
+ * - subagent.complete → stream.agent.complete
+ * - session.idle → stream.session.idle
+ * - session.error → stream.session.error
+ * - usage → stream.usage
+ *
+ * Note: All events flow through the SDK's event emitter. The adapter uses
+ * session.sendAsync() to fire the prompt and relies exclusively on SSE events
+ * for streaming content.
+ *
+ * Usage:
+ * ```typescript
+ * const adapter = new OpenCodeStreamAdapter(eventBus, sessionId);
+ * await adapter.startStreaming(session, message, { runId, messageId, agent });
+ * adapter.dispose(); // Cancel and cleanup
+ * ```
+ */
+
+import type { EventBus } from "../event-bus.ts";
+import type { BusEvent } from "../bus-events.ts";
+import type {
+  SDKStreamAdapter,
+  StreamAdapterOptions,
+} from "./types.ts";
+import type {
+  WorkflowRuntimeFeatureFlags,
+  WorkflowRuntimeFeatureFlagOverrides,
+} from "../../workflows/runtime-contracts.ts";
+import {
+  DEFAULT_WORKFLOW_RUNTIME_FEATURE_FLAGS,
+  resolveWorkflowRuntimeFeatureFlags,
+} from "../../workflows/runtime-contracts.ts";
+import {
+  createTurnMetadataState,
+  normalizeAgentTaskMetadata,
+  normalizeTurnEndMetadata,
+  normalizeTurnStartId,
+  resetTurnMetadataState,
+} from "./task-turn-normalization.ts";
+import { SubagentToolTracker } from "./subagent-tool-tracker.ts";
+import type {
+  CodingAgentClient,
+  Session,
+  AgentMessage,
+  EventHandler,
+  ToolStartEventData,
+  ToolCompleteEventData,
+  SubagentStartEventData,
+  SubagentCompleteEventData,
+  SubagentUpdateEventData,
+  PermissionRequestedEventData,
+  HumanInputRequiredEventData,
+  SkillInvokedEventData,
+  SessionCompactionEventData,
+  SessionTruncationEventData,
+  TurnStartEventData,
+  TurnEndEventData,
+  ToolPartialResultEventData,
+  SessionInfoEventData,
+  SessionWarningEventData,
+  SessionTitleChangedEventData,
+  ReasoningDeltaEventData,
+  ReasoningCompleteEventData,
+} from "../../sdk/types.ts";
+import { classifyError, computeDelay, retrySleep, DEFAULT_MAX_RETRIES } from "./retry.ts";
+
+const DEFAULT_SUBAGENT_TASK_LABEL = "sub-agent task";
+const TOOL_START_PLACEHOLDER_SIGNATURE = "__placeholder__";
+const SYNTHETIC_TASK_AGENT_PREFIX = "synthetic-task-agent:";
+
+function isGenericSubagentTaskLabel(task: string | undefined): boolean {
+  const normalized = (task ?? "").trim().toLowerCase();
+  return normalized === "" || normalized === DEFAULT_SUBAGENT_TASK_LABEL || normalized === "subagent task";
+}
+
+function isSyntheticTaskAgentId(agentId: string): boolean {
+  return agentId.startsWith(SYNTHETIC_TASK_AGENT_PREFIX);
+}
+
+/**
+ * Stream adapter for OpenCode SDK.
+ *
+ * Consumes events from the SDK's event emitter for all streaming content
+ * (text/thinking deltas, tool events, subagent events, session lifecycle).
+ * Uses session.sendAsync() to fire the prompt, then waits for session.idle
+ * or session.error to signal completion.
+ */
+export class OpenCodeStreamAdapter implements SDKStreamAdapter {
+  private bus: EventBus;
+  private sessionId: string;
+  private client?: CodingAgentClient;
+  private abortController: AbortController | null = null;
+  private textAccumulator = "";
+  private unsubscribers: Array<() => void> = [];
+  // Track thinking blocks to emit complete events
+  private thinkingBlocks = new Map<string, { startTime: number }>();
+  private pendingToolIdsByName = new Map<string, string[]>();
+  private toolStartSignatureByToolId = new Map<string, string>();
+  private toolCorrelationAliases = new Map<string, string>();
+  /** Maps task-tool correlation ID -> task metadata for subagent label hydration */
+  private taskToolMetadata = new Map<string, {
+    description: string;
+    isBackground: boolean;
+    agentType?: string;
+    subagentSessionId?: string;
+  }>();
+  /** Ordered task tool IDs awaiting subagent.start correlation fallback */
+  private pendingTaskToolCorrelationIds: string[] = [];
+  /** Ordered subagent correlation IDs awaiting task tool alias hydration */
+  private pendingSubagentCorrelationIds: string[] = [];
+  /** Maps task-tool correlation ID -> subagentId */
+  private toolUseIdToSubagentId = new Map<string, string>();
+  /** Maps subagentId -> correlation ID for replayed start events missing IDs */
+  private subagentIdToCorrelationId = new Map<string, string>();
+  /** Maps subagentSessionId -> correlation ID for replayed start events missing IDs */
+  private subagentSessionToCorrelationId = new Map<string, string>();
+  /** Synthetic task-agent IDs that already emitted stream.agent.start */
+  private syntheticAgentStartsPublished = new Set<string>();
+  /** Parent-agent/tool pairs already counted by SubagentToolTracker */
+  private trackedToolStartKeys = new Set<string>();
+  /** Tool starts that arrived before parent sub-agent registration */
+  private earlyToolEvents = new Map<string, Array<{ toolId: string; toolName: string }>>();
+  /** Active sub-agent tool contexts keyed by tool correlation ID */
+  private activeSubagentToolsById = new Map<string, { parentAgentId: string; toolName: string }>();
+  private syntheticToolCounter = 0;
+  private ownedSessionIds = new Set<string>();
+  private subagentSessionToAgentId = new Map<string, string>();
+  private subagentTracker: SubagentToolTracker | null = null;
+  private runtimeFeatureFlags: WorkflowRuntimeFeatureFlags = {
+    ...DEFAULT_WORKFLOW_RUNTIME_FEATURE_FLAGS,
+  };
+  private turnMetadataState = createTurnMetadataState();
+
+  /**
+   * Running total of output tokens across all messages in the current stream.
+   * OpenCode's `message.updated` SSE carries cumulative-within-message tokens
+   * (updated multiple times per message). We track the latest per-message value
+   * and the total across messages so the bus event carries a session-wide total.
+   */
+  private lastSeenOutputTokens = 0;
+  private accumulatedOutputTokens = 0;
+
+  /**
+   * Create a new OpenCode stream adapter.
+   *
+   * @param bus - The event bus to publish events to
+   * @param sessionId - Session ID for event correlation
+   */
+  constructor(bus: EventBus, sessionId: string, client?: CodingAgentClient) {
+    this.bus = bus;
+    this.sessionId = sessionId;
+    this.client = client;
+  }
+
+  /**
+   * Start consuming the OpenCode SDK stream and publishing BusEvents.
+   *
+   * This method will:
+   * 1. Subscribe to SDK events (text, thinking, tool, subagent, session, usage events)
+   * 2. Fire prompt via session.sendAsync() (fire-and-forget)
+   * 3. Wait for session.idle or session.error to signal completion
+   * 4. Publish events directly to the bus
+   * 5. Complete with stream.text.complete and stream.session.idle events
+   *
+   * @param session - Active OpenCode SDK session
+   * @param message - User message to stream
+   * @param options - Stream options (runId, messageId, agent)
+   */
+  async startStreaming(
+    session: Session,
+    message: string,
+    options: StreamAdapterOptions,
+  ): Promise<void> {
+    const { runId, messageId, agent, runtimeFeatureFlags, abortSignal } = options;
+
+    // Clean up any existing subscriptions from a previous startStreaming() call
+    // to prevent subscription accumulation on re-entry without dispose()
+    this.cleanupSubscriptions();
+
+    // Create abort controller for cancellation
+    this.abortController = new AbortController();
+
+    // Reset state
+    this.textAccumulator = "";
+    this.thinkingBlocks.clear();
+    this.pendingToolIdsByName.clear();
+    this.toolStartSignatureByToolId.clear();
+    this.toolCorrelationAliases.clear();
+    this.taskToolMetadata.clear();
+    this.pendingTaskToolCorrelationIds = [];
+    this.pendingSubagentCorrelationIds = [];
+    this.toolUseIdToSubagentId.clear();
+    this.subagentIdToCorrelationId.clear();
+    this.subagentSessionToCorrelationId.clear();
+    this.syntheticAgentStartsPublished.clear();
+    this.trackedToolStartKeys.clear();
+    this.earlyToolEvents.clear();
+    this.activeSubagentToolsById.clear();
+    this.syntheticToolCounter = 0;
+    this.ownedSessionIds = new Set([this.sessionId]);
+    this.subagentSessionToAgentId.clear();
+    this.subagentTracker = new SubagentToolTracker(this.bus, this.sessionId, runId);
+    this.lastSeenOutputTokens = 0;
+    this.accumulatedOutputTokens = 0;
+    this.runtimeFeatureFlags = this.resolveRuntimeFeatureFlags(runtimeFeatureFlags);
+    resetTurnMetadataState(this.turnMetadataState);
+
+    this.publishSessionStart(runId);
+
+    // Get the SDK client from constructor injection first, then legacy session field fallback.
+    // Note: The OpenCode SDK emits most events through the CodingAgentClient event emitter
+    const client = this.client ?? (session as Session & { __client?: CodingAgentClient }).__client;
+    if (client && typeof client.on === "function") {
+      // Subscribe to message.delta events for text and thinking content
+      const unsubDelta = client.on(
+        "message.delta",
+        this.createMessageDeltaHandler(runId, messageId),
+      );
+      this.unsubscribers.push(unsubDelta);
+
+      // Subscribe to message.complete events
+      const unsubComplete = client.on(
+        "message.complete",
+        this.createMessageCompleteHandler(runId, messageId),
+      );
+      this.unsubscribers.push(unsubComplete);
+
+      const unsubReasoningDelta = client.on(
+        "reasoning.delta",
+        this.createReasoningDeltaHandler(runId, messageId),
+      );
+      this.unsubscribers.push(unsubReasoningDelta);
+
+      const unsubReasoningComplete = client.on(
+        "reasoning.complete",
+        this.createReasoningCompleteHandler(runId),
+      );
+      this.unsubscribers.push(unsubReasoningComplete);
+
+      // Subscribe to tool.start events
+      const unsubToolStart = client.on(
+        "tool.start",
+        this.createToolStartHandler(runId),
+      );
+      this.unsubscribers.push(unsubToolStart);
+
+      // Subscribe to tool.complete events
+      const unsubToolComplete = client.on(
+        "tool.complete",
+        this.createToolCompleteHandler(runId),
+      );
+      this.unsubscribers.push(unsubToolComplete);
+
+      // Subscribe to subagent.start events
+      const unsubAgentStart = client.on(
+        "subagent.start",
+        this.createSubagentStartHandler(runId),
+      );
+      this.unsubscribers.push(unsubAgentStart);
+
+      // Subscribe to subagent.complete events
+      const unsubAgentComplete = client.on(
+        "subagent.complete",
+        this.createSubagentCompleteHandler(runId),
+      );
+      this.unsubscribers.push(unsubAgentComplete);
+
+      // Subscribe to subagent.update events (tool progress for sub-agents)
+      const unsubAgentUpdate = client.on(
+        "subagent.update",
+        this.createSubagentUpdateHandler(runId),
+      );
+      this.unsubscribers.push(unsubAgentUpdate);
+
+      // Subscribe to session.idle events
+      const unsubIdle = client.on(
+        "session.idle",
+        this.createSessionIdleHandler(runId),
+      );
+      this.unsubscribers.push(unsubIdle);
+
+      // Subscribe to session.error events
+      const unsubError = client.on(
+        "session.error",
+        this.createSessionErrorHandler(runId),
+      );
+      this.unsubscribers.push(unsubError);
+
+      // Subscribe to usage events
+      const unsubUsage = client.on(
+        "usage",
+        this.createUsageHandler(runId),
+      );
+      this.unsubscribers.push(unsubUsage);
+
+      // Subscribe to permission request events
+      const unsubPermission = client.on(
+        "permission.requested",
+        this.createPermissionRequestedHandler(runId),
+      );
+      this.unsubscribers.push(unsubPermission);
+
+      // Subscribe to human input request events
+      const unsubHumanInput = client.on(
+        "human_input_required",
+        this.createHumanInputRequiredHandler(runId),
+      );
+      this.unsubscribers.push(unsubHumanInput);
+
+      // Subscribe to skill invocation events
+      const unsubSkill = client.on(
+        "skill.invoked",
+        this.createSkillInvokedHandler(runId),
+      );
+      this.unsubscribers.push(unsubSkill);
+
+      // Subscribe to session compaction events
+      const unsubCompaction = client.on(
+        "session.compaction",
+        this.createSessionCompactionHandler(runId),
+      );
+      this.unsubscribers.push(unsubCompaction);
+
+      // Subscribe to session truncation events
+      const unsubTruncation = client.on(
+        "session.truncation",
+        this.createSessionTruncationHandler(runId),
+      );
+      this.unsubscribers.push(unsubTruncation);
+
+      // Subscribe to turn lifecycle events
+      const unsubTurnStart = client.on(
+        "turn.start",
+        this.createTurnStartHandler(runId),
+      );
+      this.unsubscribers.push(unsubTurnStart);
+
+      const unsubTurnEnd = client.on(
+        "turn.end",
+        this.createTurnEndHandler(runId),
+      );
+      this.unsubscribers.push(unsubTurnEnd);
+
+      // Subscribe to tool partial result events
+      const unsubToolPartial = client.on(
+        "tool.partial_result",
+        this.createToolPartialResultHandler(runId),
+      );
+      this.unsubscribers.push(unsubToolPartial);
+
+      // Subscribe to session info/warning/title events
+      const unsubInfo = client.on(
+        "session.info",
+        this.createSessionInfoHandler(runId),
+      );
+      this.unsubscribers.push(unsubInfo);
+
+      const unsubWarning = client.on(
+        "session.warning",
+        this.createSessionWarningHandler(runId),
+      );
+      this.unsubscribers.push(unsubWarning);
+
+      const unsubTitleChanged = client.on(
+        "session.title_changed",
+        this.createSessionTitleChangedHandler(runId),
+      );
+      this.unsubscribers.push(unsubTitleChanged);
+    }
+
+    try {
+      // Fire prompt via sendAsync (fire-and-forget) — all content arrives via SSE events.
+      // Fall back to stream() for clients that don't implement sendAsync.
+      if (session.sendAsync) {
+        // Create a promise that resolves when session.idle or session.error fires
+        const completionPromise = new Promise<{ reason: string; error?: string }>((resolve) => {
+          let resolved = false;
+          const safeResolve = (value: { reason: string; error?: string }) => {
+            if (resolved) return;
+            resolved = true;
+            resolve(value);
+          };
+          const handleAbort = () => safeResolve({ reason: "aborted" });
+
+          const onIdle = client?.on("session.idle", (event) => {
+            if (event.sessionId !== this.sessionId) return;
+            safeResolve({ reason: event.data.reason ?? "idle" });
+          });
+          if (onIdle) this.unsubscribers.push(onIdle);
+
+          const onError = client?.on("session.error", (event) => {
+            if (event.sessionId !== this.sessionId) return;
+            const error = typeof event.data.error === "string"
+              ? event.data.error
+              : (event.data.error as Error).message;
+            safeResolve({ reason: "error", error });
+          });
+          if (onError) this.unsubscribers.push(onError);
+
+          const adapterAbortSignal = this.abortController?.signal;
+          if (adapterAbortSignal) {
+            if (adapterAbortSignal.aborted) {
+              handleAbort();
+            } else {
+              adapterAbortSignal.addEventListener("abort", handleAbort, { once: true });
+              this.unsubscribers.push(
+                () => adapterAbortSignal.removeEventListener("abort", handleAbort),
+              );
+            }
+          }
+
+          if (abortSignal) {
+            if (abortSignal.aborted) {
+              handleAbort();
+            } else {
+              abortSignal.addEventListener("abort", handleAbort, { once: true });
+              this.unsubscribers.push(
+                () => abortSignal.removeEventListener("abort", handleAbort),
+              );
+            }
+          }
+        });
+
+        const dispatchAbortSignal = (() => {
+          const adapterAbortSignal = this.abortController?.signal;
+          if (adapterAbortSignal && abortSignal) {
+            return AbortSignal.any([adapterAbortSignal, abortSignal]);
+          }
+          return adapterAbortSignal ?? abortSignal;
+        })();
+
+        const isDispatchAbortError = (error: unknown): boolean => {
+          if (dispatchAbortSignal?.aborted) {
+            return true;
+          }
+          if (error instanceof DOMException && error.name === "AbortError") {
+            return true;
+          }
+          if (!(error instanceof Error)) {
+            return false;
+          }
+          const errorWithCode = error as Error & { code?: string };
+          if (
+            error.name === "AbortError"
+            || errorWithCode.code === "ABORT_ERR"
+            || errorWithCode.code === "ERR_CANCELED"
+          ) {
+            return true;
+          }
+          return error.message.toLowerCase().includes("aborted");
+        };
+
+        const dispatchOptions = agent || dispatchAbortSignal
+          ? { agent: agent ?? undefined, abortSignal: dispatchAbortSignal }
+          : undefined;
+
+        try {
+          await session.sendAsync(message, dispatchOptions);
+        } catch (error) {
+          if (!isDispatchAbortError(error)) {
+            throw error;
+          }
+        }
+
+        // Wait for completion signal from SSE
+        const completion = await completionPromise;
+
+        // Publish stream.text.complete if we accumulated any text
+        if (this.textAccumulator.length > 0) {
+          this.publishTextComplete(runId, messageId);
+        }
+
+        if (completion.error) {
+          this.publishSessionError(runId, new Error(completion.error));
+        }
+
+        // Flush orphaned tool completions before idle so the UI does not
+        // evaluate session.idle against stale pending tool state.
+        this.cleanupOrphanedTools(runId);
+        this.publishSessionIdle(runId, completion.reason);
+      } else {
+        // Legacy fallback with retry: iterate stream for non-OpenCode clients
+        let lastError: unknown = null;
+        for (let attempt = 1; attempt <= DEFAULT_MAX_RETRIES; attempt++) {
+          try {
+            const stream = session.stream(message, agent ? { agent } : undefined);
+            for await (const chunk of stream) {
+              if (this.abortController.signal.aborted) {
+                break;
+              }
+              await this.processStreamChunk(chunk, runId, messageId);
+            }
+
+            if (this.textAccumulator.length > 0) {
+              this.publishTextComplete(runId, messageId);
+            }
+            // Flush orphaned tool completions before idle so tool lifecycle
+            // reaches a terminal state prior to stream finalization.
+            this.cleanupOrphanedTools(runId);
+            this.publishSessionIdle(runId, "generator-complete");
+            lastError = null;
+            break;
+          } catch (error) {
+            lastError = error;
+            if (this.abortController?.signal.aborted) break;
+
+            const classified = classifyError(error);
+            if (!classified.isRetryable || attempt >= DEFAULT_MAX_RETRIES) break;
+
+            const delay = computeDelay(attempt, classified);
+            const retryEvent: BusEvent<"stream.session.retry"> = {
+              type: "stream.session.retry",
+              sessionId: this.sessionId,
+              runId,
+              timestamp: Date.now(),
+              data: {
+                attempt,
+                delay,
+                message: `${classified.message} — retrying in ${Math.ceil(delay / 1000)}s`,
+                nextRetryAt: Date.now() + delay,
+              },
+            };
+            this.bus.publish(retryEvent);
+
+            this.textAccumulator = "";
+            await retrySleep(delay, this.abortController.signal);
+          }
+        }
+        if (lastError) throw lastError;
+      }
+    } catch (error) {
+      // Handle stream errors
+      if (this.abortController && !this.abortController.signal.aborted) {
+        this.publishSessionError(runId, error);
+      }
+      // Flush orphaned tool completions before idle so the UI can finalize
+      // without being blocked by stale pending tools.
+      this.cleanupOrphanedTools(runId);
+      // Always publish idle on error so the UI can finalize.
+      this.publishSessionIdle(runId, "error");
+    } finally {
+      // Safety net: if any late orphaned tools remain, force-complete them.
+      this.cleanupOrphanedTools(runId);
+      // Keep subscriptions active until dispose() so late lifecycle events
+      // (e.g. delayed tool.complete) can still be published to the bus.
+    }
+  }
+
+  private createReasoningDeltaHandler(
+    runId: number,
+    messageId: string,
+  ): EventHandler<"reasoning.delta"> {
+    return (event) => {
+      if (event.sessionId !== this.sessionId) return;
+      if (this.abortController?.signal.aborted) return;
+
+      const data = event.data as ReasoningDeltaEventData;
+      if (!data.delta || data.delta.length === 0) return;
+      const sourceKey = data.reasoningId || "reasoning";
+
+      if (!this.thinkingBlocks.has(sourceKey)) {
+        this.thinkingBlocks.set(sourceKey, { startTime: Date.now() });
+      }
+
+      this.bus.publish({
+        type: "stream.thinking.delta",
+        sessionId: this.sessionId,
+        runId,
+        timestamp: Date.now(),
+        data: {
+          delta: data.delta,
+          sourceKey,
+          messageId,
+        },
+      });
+    };
+  }
+
+  private createReasoningCompleteHandler(
+    runId: number,
+  ): EventHandler<"reasoning.complete"> {
+    return (event) => {
+      if (event.sessionId !== this.sessionId) return;
+      if (this.abortController?.signal.aborted) return;
+
+      const data = event.data as ReasoningCompleteEventData;
+      const sourceKey = data.reasoningId || "reasoning";
+      const start = this.thinkingBlocks.get(sourceKey)?.startTime;
+      const durationMs = start ? Date.now() - start : 0;
+      this.thinkingBlocks.delete(sourceKey);
+
+      this.bus.publish({
+        type: "stream.thinking.complete",
+        sessionId: this.sessionId,
+        runId,
+        timestamp: Date.now(),
+        data: {
+          sourceKey,
+          durationMs,
+        },
+      });
+    };
+  }
+
+  /**
+   * Process a single chunk from the OpenCode stream.
+   *
+   * Maps AgentMessage to the appropriate BusEvent based on message type.
+   */
+  private async processStreamChunk(
+    chunk: AgentMessage,
+    runId: number,
+    messageId: string,
+  ): Promise<void> {
+    // Handle text deltas
+    if (chunk.type === "text" && typeof chunk.content === "string") {
+      const delta = chunk.content;
+      this.textAccumulator += delta;
+
+      if (delta.length > 0) {
+        const event: BusEvent<"stream.text.delta"> = {
+          type: "stream.text.delta",
+          sessionId: this.sessionId,
+          runId,
+          timestamp: Date.now(),
+          data: {
+            delta,
+            messageId,
+          },
+        };
+
+        this.bus.publish(event);
+      }
+
+      // Token usage is handled by createUsageHandler (from client "usage" events).
+      // Do NOT emit stream.usage here from streamingStats to avoid double-counting
+      // when chat.tsx accumulates per-turn values.
+    }
+
+    // Handle thinking deltas
+    if (chunk.type === "thinking") {
+      const metadata = chunk.metadata;
+      const thinkingSourceKey = metadata?.thinkingSourceKey as string | undefined;
+      const sourceKey = thinkingSourceKey ?? "default";
+
+      // Check if this is a thinking delta (has content)
+      if (typeof chunk.content === "string" && chunk.content.length > 0) {
+        // Track the start time for this thinking block
+        if (!this.thinkingBlocks.has(sourceKey)) {
+          this.thinkingBlocks.set(sourceKey, { startTime: Date.now() });
+        }
+
+        const event: BusEvent<"stream.thinking.delta"> = {
+          type: "stream.thinking.delta",
+          sessionId: this.sessionId,
+          runId,
+          timestamp: Date.now(),
+          data: {
+            delta: chunk.content,
+            sourceKey,
+            messageId,
+          },
+        };
+
+        this.bus.publish(event);
+      }
+
+      // Check if this is a thinking complete event (has streamingStats)
+      const streamingStats = metadata?.streamingStats as
+        | { thinkingMs?: number; outputTokens?: number }
+        | undefined;
+      if (streamingStats?.thinkingMs !== undefined) {
+        const durationMs = streamingStats.thinkingMs;
+
+        const event: BusEvent<"stream.thinking.complete"> = {
+          type: "stream.thinking.complete",
+          sessionId: this.sessionId,
+          runId,
+          timestamp: Date.now(),
+          data: {
+            sourceKey,
+            durationMs,
+          },
+        };
+
+        this.bus.publish(event);
+        this.thinkingBlocks.delete(sourceKey);
+      }
+
+      // Token usage is handled by createUsageHandler (from client "usage" events).
+      // Do NOT emit stream.usage here from streamingStats to avoid double-counting.
+    }
+
+    if (chunk.type === "tool_use") {
+      const metadata = (chunk.metadata ?? {}) as Record<string, unknown>;
+      const content = (chunk.content ?? {}) as Record<string, unknown>;
+      const toolCalls = Array.isArray(content.toolCalls)
+        ? content.toolCalls as Record<string, unknown>[]
+        : [content];
+
+      for (const toolCall of toolCalls) {
+        const toolName = this.normalizeToolName(toolCall.name ?? metadata.toolName);
+        const input = this.asRecord(toolCall.input) ?? {};
+        const explicitToolId = this.asString(
+          toolCall.toolUseId
+            ?? toolCall.toolUseID
+            ?? toolCall.id
+            ?? metadata.toolId
+            ?? metadata.toolUseId
+            ?? metadata.toolUseID
+            ?? metadata.toolCallId,
+        );
+        const toolId = this.resolveToolStartId(explicitToolId, runId, toolName);
+        const sdkCorrelationId = explicitToolId ?? toolId;
+
+        const event: BusEvent<"stream.tool.start"> = {
+          type: "stream.tool.start",
+          sessionId: this.sessionId,
+          runId,
+          timestamp: Date.now(),
+          data: {
+            toolId,
+            toolName,
+            toolInput: input,
+            sdkCorrelationId,
+          },
+        };
+        this.bus.publish(event);
+      }
+    }
+
+    if (chunk.type === "tool_result") {
+      const metadata = (chunk.metadata ?? {}) as Record<string, unknown>;
+      const toolName = this.normalizeToolName(metadata.toolName);
+      const explicitToolId = this.asString(
+        metadata.toolId
+          ?? metadata.toolUseId
+          ?? metadata.toolUseID
+          ?? metadata.toolCallId,
+      );
+      const toolId = this.resolveToolCompleteId(explicitToolId, runId, toolName);
+      const rawContent = chunk.content;
+      const contentRecord = this.asRecord(rawContent);
+      const isError = metadata.error === true
+        || (typeof rawContent === "object" && rawContent !== null && "error" in rawContent);
+      const errorValue = contentRecord?.error;
+      const error = isError
+        ? (typeof errorValue === "string" ? errorValue : "Tool execution failed")
+        : undefined;
+
+      const event: BusEvent<"stream.tool.complete"> = {
+        type: "stream.tool.complete",
+        sessionId: this.sessionId,
+        runId,
+        timestamp: Date.now(),
+        data: {
+          toolId,
+          toolName,
+          toolResult: rawContent,
+          success: !isError,
+          error,
+          sdkCorrelationId: explicitToolId ?? toolId,
+        },
+      };
+      this.bus.publish(event);
+    }
+  }
+
+  /**
+   * Create a handler for message.delta events from the SDK.
+   * Handles both text and thinking content from SSE events.
+   */
+  private createMessageDeltaHandler(
+    runId: number,
+    messageId: string,
+  ): EventHandler<"message.delta"> {
+    return (event) => {
+      if (event.sessionId !== this.sessionId) return;
+      if (this.abortController?.signal.aborted) return;
+
+      const { delta, contentType, thinkingSourceKey } = event.data;
+
+      if (!delta || delta.length === 0) return;
+
+      if (contentType === "thinking") {
+        const sourceKey = thinkingSourceKey ?? "default";
+
+        if (!this.thinkingBlocks.has(sourceKey)) {
+          this.thinkingBlocks.set(sourceKey, { startTime: Date.now() });
+        }
+
+        const busEvent: BusEvent<"stream.thinking.delta"> = {
+          type: "stream.thinking.delta",
+          sessionId: this.sessionId,
+          runId,
+          timestamp: Date.now(),
+          data: {
+            delta,
+            sourceKey,
+            messageId,
+          },
+        };
+        this.bus.publish(busEvent);
+      } else {
+        this.textAccumulator += delta;
+
+        const busEvent: BusEvent<"stream.text.delta"> = {
+          type: "stream.text.delta",
+          sessionId: this.sessionId,
+          runId,
+          timestamp: Date.now(),
+          data: {
+            delta,
+            messageId,
+          },
+        };
+        this.bus.publish(busEvent);
+      }
+    };
+  }
+
+  /**
+   * Create a handler for message.complete events from the SDK.
+   */
+  private createMessageCompleteHandler(
+    runId: number,
+    messageId: string,
+  ): EventHandler<"message.complete"> {
+    return (event) => {
+      // Only process events for this session
+      if (event.sessionId !== this.sessionId) {
+        return;
+      }
+
+      // Finalize any open thinking blocks by emitting stream.thinking.complete
+      for (const [sourceKey, block] of this.thinkingBlocks.entries()) {
+        const durationMs = Date.now() - block.startTime;
+        const completeEvent: BusEvent<"stream.thinking.complete"> = {
+          type: "stream.thinking.complete",
+          sessionId: this.sessionId,
+          runId,
+          timestamp: Date.now(),
+          data: {
+            sourceKey,
+            durationMs,
+          },
+        };
+        this.bus.publish(completeEvent);
+      }
+      this.thinkingBlocks.clear();
+
+      // Publish text complete if we have accumulated text
+      if (this.textAccumulator.length > 0) {
+        this.publishTextComplete(runId, messageId);
+      }
+    };
+  }
+
+  /**
+   * Create a handler for tool.start events from the SDK.
+   */
+  private createToolStartHandler(runId: number): EventHandler<"tool.start"> {
+    return (event) => {
+      const data = event.data as ToolStartEventData;
+      const dataRecord = data as Record<string, unknown>;
+      const parentToolUseId = this.resolveToolCorrelationId(this.asString(
+        dataRecord.parentToolUseId
+          ?? dataRecord.parent_tool_use_id
+          ?? dataRecord.parentToolUseID,
+      ));
+      const parentAgentId = this.resolveParentAgentId(
+        event.sessionId,
+        dataRecord,
+      );
+      // Process tool events for parent/owned sessions, and also accept
+      // events that carry an explicit parent-agent correlation.
+      if (!this.isOwnedSession(event.sessionId) && !parentAgentId) {
+        return;
+      }
+      const sdkToolUseId = this.asString(data.toolUseId ?? data.toolUseID);
+      const sdkToolCallId = this.asString(data.toolCallId);
+      const sdkCorrelationId = sdkToolUseId ?? sdkToolCallId;
+      const resolvedSdkCorrelationId = this.resolveToolCorrelationId(sdkCorrelationId);
+      const toolName = this.normalizeToolName(data.toolName);
+      const toolId = this.resolveToolStartId(
+        resolvedSdkCorrelationId ?? sdkCorrelationId,
+        runId,
+        toolName,
+      );
+      const toolMetadata = this.asRecord(dataRecord.toolMetadata);
+      const toolStartSignature = this.buildToolStartSignature(
+        toolName,
+        (data.toolInput ?? {}) as Record<string, unknown>,
+        toolMetadata,
+        parentAgentId,
+      );
+      const previousStartSignature = this.toolStartSignatureByToolId.get(toolId);
+      if (previousStartSignature === toolStartSignature) {
+        return;
+      }
+      const hasTaskDispatchDetails = this.hasTaskDispatchDetails(data.toolInput);
+      if (
+        this.isTaskTool(toolName)
+        && !hasTaskDispatchDetails
+        && !previousStartSignature
+      ) {
+        // OpenCode may emit an initial placeholder task.start with empty input
+        // before the hydrated payload. Suppress the placeholder to avoid a
+        // brief generic task widget.
+        this.toolStartSignatureByToolId.set(toolId, TOOL_START_PLACEHOLDER_SIGNATURE);
+        this.removeQueuedToolId(toolName, toolId);
+        return;
+      }
+      this.toolStartSignatureByToolId.set(toolId, toolStartSignature);
+      this.registerToolCorrelationAliases(toolId, sdkToolUseId, sdkToolCallId);
+      const taskCorrelationId = resolvedSdkCorrelationId ?? sdkCorrelationId;
+      if (this.isTaskTool(toolName) && taskCorrelationId) {
+        const metadata = this.extractTaskToolMetadata(data.toolInput, dataRecord);
+        const existingMetadata = this.taskToolMetadata.get(taskCorrelationId);
+        const mergedMetadata = this.mergeTaskToolMetadata(existingMetadata, metadata);
+        this.taskToolMetadata.set(taskCorrelationId, mergedMetadata);
+        this.recordPendingTaskToolCorrelationId(taskCorrelationId);
+        this.resolvePendingSubagentTaskCorrelation(taskCorrelationId);
+        this.ensureSyntheticTaskSubagentMapping(taskCorrelationId, data.toolInput, runId);
+        this.registerTaskSubagentSessionCorrelation(taskCorrelationId, mergedMetadata.subagentSessionId);
+      }
+      const syntheticFallbackParentAgentId = this.resolveSyntheticTaskParentAgentId(taskCorrelationId);
+      if (parentAgentId) {
+        this.ensureSyntheticTaskAgentStart(runId, parentAgentId);
+        this.recordActiveSubagentToolContext(toolId, toolName, parentAgentId, sdkToolUseId, sdkToolCallId);
+        const trackerKey = this.buildTrackedToolStartKey(parentAgentId, toolId);
+        if (!this.trackedToolStartKeys.has(trackerKey)) {
+          if (this.subagentTracker?.hasAgent(parentAgentId)) {
+            this.trackedToolStartKeys.add(trackerKey);
+            this.subagentTracker.onToolStart(parentAgentId, toolName);
+          } else {
+            this.queueEarlyToolEvent(parentAgentId, toolId, toolName);
+            if (parentToolUseId) {
+              this.queueEarlyToolEvent(parentToolUseId, toolId, toolName);
+            }
+          }
+        }
+      } else if (syntheticFallbackParentAgentId) {
+        this.ensureSyntheticTaskAgentStart(runId, syntheticFallbackParentAgentId);
+        this.recordActiveSubagentToolContext(
+          toolId,
+          toolName,
+          syntheticFallbackParentAgentId,
+          sdkToolUseId,
+          sdkToolCallId,
+          taskCorrelationId,
+        );
+        const trackerKey = this.buildTrackedToolStartKey(syntheticFallbackParentAgentId, toolId);
+        if (!this.trackedToolStartKeys.has(trackerKey) && this.subagentTracker?.hasAgent(syntheticFallbackParentAgentId)) {
+          this.trackedToolStartKeys.add(trackerKey);
+          this.subagentTracker.onToolStart(syntheticFallbackParentAgentId, toolName);
+        }
+      } else if (parentToolUseId) {
+        this.queueEarlyToolEvent(parentToolUseId, toolId, toolName);
+        const correlatedParentAgentId = this.toolUseIdToSubagentId.get(parentToolUseId);
+        if (correlatedParentAgentId) {
+          this.recordActiveSubagentToolContext(
+            toolId,
+            toolName,
+            correlatedParentAgentId,
+            sdkToolUseId,
+            sdkToolCallId,
+            parentToolUseId,
+          );
+        }
+      }
+      const attributedParentAgentId = parentAgentId
+        ?? this.activeSubagentToolsById.get(toolId)?.parentAgentId;
+
+      const busEvent: BusEvent<"stream.tool.start"> = {
+        type: "stream.tool.start",
+        sessionId: this.sessionId,
+        runId,
+        timestamp: Date.now(),
+        data: {
+          toolId,
+          toolName,
+          toolInput: (data.toolInput ?? {}) as Record<string, unknown>,
+          sdkCorrelationId: sdkCorrelationId ?? toolId,
+          ...(attributedParentAgentId ? { parentAgentId: attributedParentAgentId } : {}),
+        },
+      };
+
+      this.bus.publish(busEvent);
+    };
+  }
+
+  /**
+   * Create a handler for tool.complete events from the SDK.
+   */
+  private createToolCompleteHandler(
+    runId: number,
+  ): EventHandler<"tool.complete"> {
+    return (event) => {
+      const data = event.data as ToolCompleteEventData;
+      const dataRecord = data as Record<string, unknown>;
+      const parentToolUseId = this.resolveToolCorrelationId(this.asString(
+        dataRecord.parentToolUseId
+          ?? dataRecord.parent_tool_use_id
+          ?? dataRecord.parentToolUseID,
+      ));
+      const parentAgentId = this.resolveParentAgentId(
+        event.sessionId,
+        dataRecord,
+      );
+      const sdkToolUseId = this.asString(data.toolUseId ?? data.toolUseID);
+      const sdkToolCallId = this.asString(data.toolCallId);
+      const sdkCorrelationId = this.resolveToolCorrelationId(
+        sdkToolUseId ?? sdkToolCallId,
+      );
+      const knownParentAgentId = sdkCorrelationId
+        ? this.activeSubagentToolsById.get(sdkCorrelationId)?.parentAgentId
+        : undefined;
+      // Process tool events for parent/owned sessions, and also accept
+      // events that carry an explicit parent-agent correlation.
+      if (!this.isOwnedSession(event.sessionId) && !parentAgentId && !knownParentAgentId) {
+        return;
+      }
+      const toolName = this.normalizeToolName(data.toolName);
+      const taskCorrelationId = this.isTaskTool(toolName) ? sdkCorrelationId : undefined;
+      const toolId = this.resolveToolCompleteId(sdkCorrelationId, runId, toolName);
+      const startSignature = this.toolStartSignatureByToolId.get(toolId);
+      this.toolStartSignatureByToolId.delete(toolId);
+      if (
+        this.isTaskTool(toolName)
+        && startSignature === TOOL_START_PLACEHOLDER_SIGNATURE
+      ) {
+        return;
+      }
+      const toolInput = this.asRecord((data as Record<string, unknown>).toolInput);
+      this.registerToolCorrelationAliases(toolId, sdkToolUseId, sdkToolCallId);
+      const activeToolContext = this.activeSubagentToolsById.get(toolId);
+      this.removeActiveSubagentToolContext(toolId, sdkToolUseId, sdkToolCallId);
+      const syntheticMappedAgentId = this.isTaskTool(toolName) && sdkCorrelationId
+        ? this.toolUseIdToSubagentId.get(sdkCorrelationId)
+        : undefined;
+      let syntheticFallbackParentAgentId: string | undefined;
+      if (parentAgentId) {
+        const trackerKey = this.buildTrackedToolStartKey(parentAgentId, toolId);
+        if (this.trackedToolStartKeys.delete(trackerKey)) {
+          this.subagentTracker?.onToolComplete(parentAgentId);
+        }
+        this.removeEarlyToolEvent(parentAgentId, toolId);
+      } else {
+        syntheticFallbackParentAgentId = (
+          syntheticMappedAgentId && isSyntheticTaskAgentId(syntheticMappedAgentId)
+        )
+          ? syntheticMappedAgentId
+          : this.resolveSyntheticTaskParentAgentId(taskCorrelationId);
+        if (syntheticFallbackParentAgentId) {
+          const trackerKey = this.buildTrackedToolStartKey(syntheticFallbackParentAgentId, toolId);
+          if (this.trackedToolStartKeys.delete(trackerKey)) {
+            this.subagentTracker?.onToolComplete(syntheticFallbackParentAgentId);
+          }
+          this.removeEarlyToolEvent(syntheticFallbackParentAgentId, toolId);
+        }
+      }
+      const syntheticTaskAgentIdForCompletion = (
+        syntheticMappedAgentId && isSyntheticTaskAgentId(syntheticMappedAgentId)
+      )
+        ? syntheticMappedAgentId
+        : (
+          syntheticFallbackParentAgentId && isSyntheticTaskAgentId(syntheticFallbackParentAgentId)
+            ? syntheticFallbackParentAgentId
+            : undefined
+        );
+      const shouldPublishSyntheticAgentComplete = Boolean(
+        syntheticTaskAgentIdForCompletion
+        && this.subagentTracker?.hasAgent(syntheticTaskAgentIdForCompletion),
+      );
+
+      if (syntheticTaskAgentIdForCompletion) {
+        this.subagentTracker?.removeAgent(syntheticTaskAgentIdForCompletion);
+        if (sdkCorrelationId) {
+          this.toolUseIdToSubagentId.delete(sdkCorrelationId);
+        }
+        this.subagentIdToCorrelationId.delete(syntheticTaskAgentIdForCompletion);
+        for (const [subagentSessionId, mappedAgentId] of this.subagentSessionToAgentId.entries()) {
+          if (mappedAgentId === syntheticTaskAgentIdForCompletion) {
+            this.subagentSessionToAgentId.delete(subagentSessionId);
+            this.subagentSessionToCorrelationId.delete(subagentSessionId);
+            this.ownedSessionIds.delete(subagentSessionId);
+          }
+        }
+      }
+      if (parentToolUseId) {
+        this.removeEarlyToolEvent(parentToolUseId, toolId);
+      }
+      const attributedParentAgentId = parentAgentId
+        ?? knownParentAgentId
+        ?? activeToolContext?.parentAgentId
+        ?? syntheticFallbackParentAgentId;
+
+      const busEvent: BusEvent<"stream.tool.complete"> = {
+        type: "stream.tool.complete",
+        sessionId: this.sessionId,
+        runId,
+        timestamp: Date.now(),
+        data: {
+          toolId,
+          toolName,
+          toolInput,
+          toolResult: data.toolResult,
+          success: data.success,
+          error: data.error,
+          sdkCorrelationId: sdkCorrelationId ?? toolId,
+          ...(attributedParentAgentId ? { parentAgentId: attributedParentAgentId } : {}),
+        },
+      };
+
+      this.bus.publish(busEvent);
+
+      // OpenCode synthetic Task/Agent flows often complete via task tool.complete
+      // without a follow-up subagent.complete. Emit the terminal lifecycle event
+      // here so the UI can leave the running state deterministically.
+      if (shouldPublishSyntheticAgentComplete && syntheticTaskAgentIdForCompletion) {
+        this.bus.publish({
+          type: "stream.agent.complete",
+          sessionId: this.sessionId,
+          runId,
+          timestamp: Date.now(),
+          data: {
+            agentId: syntheticTaskAgentIdForCompletion,
+            success: data.success,
+            result: data.success
+              ? this.extractTaskToolResultSummary(data.toolResult)
+              : undefined,
+            error: data.success ? undefined : data.error,
+          },
+        });
+      }
+    };
+  }
+
+  /**
+   * Create a handler for subagent.start events from the SDK.
+   */
+  private createSubagentStartHandler(
+    runId: number,
+  ): EventHandler<"subagent.start"> {
+    return (event) => {
+      const data = event.data as SubagentStartEventData;
+      const dataRecord = data as Record<string, unknown>;
+      const subagentSessionId = this.asString(
+        dataRecord.subagentSessionId,
+      );
+      const rawSdkCorrelationId = this.asString(
+        data.toolUseId ?? data.toolUseID ?? data.toolCallId,
+      );
+      const canonicalRawCorrelationId = this.resolveToolCorrelationId(rawSdkCorrelationId)
+        ?? rawSdkCorrelationId;
+      const hasTaskCorrelation = Boolean(
+        canonicalRawCorrelationId
+          && (
+            this.taskToolMetadata.has(canonicalRawCorrelationId)
+            || this.pendingTaskToolCorrelationIds.includes(canonicalRawCorrelationId)
+          ),
+      );
+      const isKnownSubagent = this.subagentIdToCorrelationId.has(data.subagentId);
+      // Accept events from parent/owned sessions, plus correlation-backed
+      // subagent starts that may arrive on a child session frame.
+      if (
+        !this.isOwnedSession(event.sessionId)
+        && !hasTaskCorrelation
+        && !isKnownSubagent
+      ) {
+        return;
+      }
+
+      this.subagentTracker?.registerAgent(data.subagentId);
+      if (subagentSessionId) {
+        this.ownedSessionIds.add(subagentSessionId);
+        this.subagentSessionToAgentId.set(subagentSessionId, data.subagentId);
+      }
+
+      // Extract SDK correlation IDs and canonicalize through alias mappings.
+      let sdkCorrelationId = this.resolveToolCorrelationId(rawSdkCorrelationId);
+      let parentToolUseId = this.resolveToolCorrelationId(this.asString(
+        dataRecord.parentToolUseId
+          ?? dataRecord.parent_tool_use_id
+          ?? dataRecord.parentToolUseID,
+      ));
+
+      if (!sdkCorrelationId) {
+        sdkCorrelationId = this.resolveKnownSubagentCorrelation(data.subagentId, subagentSessionId);
+      }
+      if (!parentToolUseId) {
+        parentToolUseId = this.resolveKnownSubagentCorrelation(data.subagentId, subagentSessionId);
+      }
+
+      const hasSdkMetadata = sdkCorrelationId
+        ? this.taskToolMetadata.has(sdkCorrelationId)
+        : false;
+      if (!hasSdkMetadata && parentToolUseId && this.taskToolMetadata.has(parentToolUseId)) {
+        sdkCorrelationId = parentToolUseId;
+      }
+
+      if (!sdkCorrelationId) {
+        const inferredTaskToolId = this.resolveNextPendingTaskToolCorrelationId();
+        if (inferredTaskToolId) {
+          sdkCorrelationId = inferredTaskToolId;
+          parentToolUseId = parentToolUseId ?? inferredTaskToolId;
+        }
+      } else if (!this.taskToolMetadata.has(sdkCorrelationId)) {
+        const inferredTaskToolId = this.resolveNextPendingTaskToolCorrelationId();
+        if (inferredTaskToolId && inferredTaskToolId !== sdkCorrelationId) {
+          this.registerPreferredToolCorrelationAlias(inferredTaskToolId, sdkCorrelationId);
+          sdkCorrelationId = inferredTaskToolId;
+          parentToolUseId = parentToolUseId ?? inferredTaskToolId;
+        }
+      }
+
+      const metadata = (sdkCorrelationId ? this.taskToolMetadata.get(sdkCorrelationId) : undefined)
+        ?? (parentToolUseId ? this.taskToolMetadata.get(parentToolUseId) : undefined);
+      const effectiveTask = metadata?.description || data.task;
+      const normalizedTask = isGenericSubagentTaskLabel(effectiveTask)
+        ? (this.asString(dataRecord.description) ?? effectiveTask)
+        : effectiveTask;
+      const normalizedMetadata = normalizeAgentTaskMetadata(
+        {
+          task: normalizedTask,
+          agentType: data.subagentType,
+          isBackground: metadata?.isBackground
+            ?? (dataRecord.isBackground as boolean | undefined),
+          toolInput: dataRecord.toolInput,
+        },
+      );
+
+      if (sdkCorrelationId) {
+        const existingMappedAgentId = this.toolUseIdToSubagentId.get(sdkCorrelationId);
+        if (
+          existingMappedAgentId
+          && existingMappedAgentId !== data.subagentId
+          && isSyntheticTaskAgentId(existingMappedAgentId)
+        ) {
+          this.subagentTracker?.removeAgent(existingMappedAgentId);
+          this.subagentIdToCorrelationId.delete(existingMappedAgentId);
+        }
+        this.toolUseIdToSubagentId.set(sdkCorrelationId, data.subagentId);
+        this.subagentIdToCorrelationId.set(data.subagentId, sdkCorrelationId);
+        this.removePendingTaskToolCorrelationId(sdkCorrelationId);
+      }
+      if (parentToolUseId && parentToolUseId !== sdkCorrelationId) {
+        this.toolUseIdToSubagentId.set(parentToolUseId, data.subagentId);
+        if (!sdkCorrelationId) {
+          this.subagentIdToCorrelationId.set(data.subagentId, parentToolUseId);
+        }
+        this.removePendingTaskToolCorrelationId(parentToolUseId);
+      }
+      if (subagentSessionId) {
+        const knownCorrelationId = sdkCorrelationId ?? parentToolUseId;
+        if (knownCorrelationId) {
+          this.subagentSessionToCorrelationId.set(subagentSessionId, knownCorrelationId);
+        }
+      }
+
+      this.replayEarlyToolEvents(
+        data.subagentId,
+        data.subagentId,
+        rawSdkCorrelationId,
+        sdkCorrelationId,
+        parentToolUseId,
+      );
+
+      if (rawSdkCorrelationId && !this.taskToolMetadata.has(rawSdkCorrelationId)) {
+        this.recordPendingSubagentCorrelationId(rawSdkCorrelationId);
+      } else if (rawSdkCorrelationId) {
+        this.removePendingSubagentCorrelationId(rawSdkCorrelationId);
+      }
+      if (sdkCorrelationId) {
+        this.removePendingSubagentCorrelationId(sdkCorrelationId);
+      }
+
+      const busEvent: BusEvent<"stream.agent.start"> = {
+        type: "stream.agent.start",
+        sessionId: this.sessionId,
+        runId,
+        timestamp: Date.now(),
+        data: {
+          agentId: data.subagentId,
+          toolCallId: sdkCorrelationId ?? data.subagentId,
+          agentType: data.subagentType ?? "unknown",
+          task: normalizedMetadata.task,
+          isBackground: normalizedMetadata.isBackground,
+          sdkCorrelationId,
+        },
+      };
+
+      this.bus.publish(busEvent);
+    };
+  }
+
+  /**
+   * Create a handler for subagent.complete events from the SDK.
+   */
+  private createSubagentCompleteHandler(
+    runId: number,
+  ): EventHandler<"subagent.complete"> {
+    return (event) => {
+      const data = event.data as SubagentCompleteEventData;
+      const isKnownSubagent = this.subagentIdToCorrelationId.has(data.subagentId)
+        || Array.from(this.subagentSessionToAgentId.values()).includes(data.subagentId);
+      if (!this.isOwnedSession(event.sessionId) && !isKnownSubagent) {
+        return;
+      }
+
+      this.subagentTracker?.removeAgent(data.subagentId);
+      this.subagentIdToCorrelationId.delete(data.subagentId);
+      for (const [subagentSessionId, agentId] of this.subagentSessionToAgentId.entries()) {
+        if (agentId === data.subagentId) {
+          this.subagentSessionToAgentId.delete(subagentSessionId);
+          this.ownedSessionIds.delete(subagentSessionId);
+          this.subagentSessionToCorrelationId.delete(subagentSessionId);
+        }
+      }
+      for (const [toolUseId, subagentId] of this.toolUseIdToSubagentId.entries()) {
+        if (subagentId === data.subagentId) {
+          this.toolUseIdToSubagentId.delete(toolUseId);
+          this.taskToolMetadata.delete(toolUseId);
+          this.removePendingTaskToolCorrelationId(toolUseId);
+          this.removePendingSubagentCorrelationId(toolUseId);
+          this.earlyToolEvents.delete(toolUseId);
+        }
+      }
+      this.earlyToolEvents.delete(data.subagentId);
+
+      const busEvent: BusEvent<"stream.agent.complete"> = {
+        type: "stream.agent.complete",
+        sessionId: this.sessionId,
+        runId,
+        timestamp: Date.now(),
+        data: {
+          agentId: data.subagentId,
+          success: data.success,
+          result: data.result ? String(data.result) : undefined,
+        },
+      };
+
+      this.bus.publish(busEvent);
+    };
+  }
+
+  /**
+   * Create a handler for subagent.update events from the SDK.
+   * Publishes stream.agent.update to the bus.
+   */
+  private createSubagentUpdateHandler(
+    runId: number,
+  ): EventHandler<"subagent.update"> {
+    return (event) => {
+      const data = event.data as SubagentUpdateEventData;
+      const isKnownSubagent = this.subagentIdToCorrelationId.has(data.subagentId)
+        || Array.from(this.subagentSessionToAgentId.values()).includes(data.subagentId);
+      if (!this.isOwnedSession(event.sessionId) && !isKnownSubagent) return;
+
+      const busEvent: BusEvent<"stream.agent.update"> = {
+        type: "stream.agent.update",
+        sessionId: this.sessionId,
+        runId,
+        timestamp: Date.now(),
+        data: {
+          agentId: data.subagentId,
+          currentTool: data.currentTool,
+          toolUses: data.toolUses,
+        },
+      };
+      this.bus.publish(busEvent);
+    };
+  }
+
+  /**
+   * Create a handler for session.idle events from the SDK.
+   *
+   * With the `promptAsync()` pattern, the completion promise in
+   * `startStreaming()` handles publishing idle. This handler is a no-op for
+   * the `sendAsync` path to avoid double-publishing. For the legacy stream
+   * path, idle is published after the `for await` loop completes.
+   */
+  private createSessionIdleHandler(
+    _runId: number,
+  ): EventHandler<"session.idle"> {
+    return (event) => {
+      if (event.sessionId !== this.sessionId) {
+        return;
+      }
+      // No-op: completion is handled by the sendAsync completion promise
+      // or the post-loop logic in the legacy stream fallback path.
+    };
+  }
+
+  /**
+   * Create a handler for session.error events from the SDK.
+   */
+  private createSessionErrorHandler(
+    runId: number,
+  ): EventHandler<"session.error"> {
+    return (event) => {
+      // Only process events for this session
+      if (event.sessionId !== this.sessionId) {
+        return;
+      }
+
+      const error =
+        typeof event.data.error === "string"
+          ? event.data.error
+          : (event.data.error as Error).message;
+
+      const busEvent: BusEvent<"stream.session.error"> = {
+        type: "stream.session.error",
+        sessionId: this.sessionId,
+        runId,
+        timestamp: Date.now(),
+        data: {
+          error,
+          code: event.data.code,
+        },
+      };
+
+      this.bus.publish(busEvent);
+    };
+  }
+
+  /**
+   * Create a handler for usage events from the SDK.
+   *
+   * OpenCode's `message.updated` SSE fires multiple times per message with
+   * cumulative-within-message token counts. Across messages (in multi-turn
+   * agentic flows), each message starts from 0. We track both the latest
+   * within-message value and the cross-message total so the bus event carries
+   * a monotonically increasing session-wide total.
+   */
+  private createUsageHandler(runId: number): EventHandler<"usage"> {
+    return (event) => {
+      // Only process events for this session
+      if (event.sessionId !== this.sessionId) {
+        return;
+      }
+
+      const data = event.data as Record<string, number | string | undefined>;
+      const inputTokens = (data.inputTokens as number) ?? (data.input_tokens as number) ?? 0;
+      const outputTokens = (data.outputTokens as number) ?? (data.output_tokens as number) ?? 0;
+      const model = data.model as string | undefined;
+
+      // Skip zero-valued events
+      if (outputTokens <= 0 && inputTokens <= 0) return;
+
+      // Detect new message: when the incoming outputTokens is LESS than the
+      // last seen value, it means a new message started. Add the previous
+      // message's final count to the running total and start fresh.
+      if (outputTokens < this.lastSeenOutputTokens) {
+        this.accumulatedOutputTokens += this.lastSeenOutputTokens;
+      }
+      this.lastSeenOutputTokens = outputTokens;
+
+      const busEvent: BusEvent<"stream.usage"> = {
+        type: "stream.usage",
+        sessionId: this.sessionId,
+        runId,
+        timestamp: Date.now(),
+        data: {
+          inputTokens,
+          outputTokens: this.accumulatedOutputTokens + outputTokens,
+          model,
+        },
+      };
+
+      this.bus.publish(busEvent);
+    };
+  }
+
+  /**
+   * Create a handler for permission.requested events from the SDK.
+   */
+  private createPermissionRequestedHandler(
+    runId: number,
+  ): EventHandler<"permission.requested"> {
+    return (event) => {
+      if (event.sessionId !== this.sessionId) {
+        return;
+      }
+
+      const data = event.data as PermissionRequestedEventData;
+      const busEvent: BusEvent<"stream.permission.requested"> = {
+        type: "stream.permission.requested",
+        sessionId: this.sessionId,
+        runId,
+        timestamp: Date.now(),
+        data: {
+          requestId: data.requestId,
+          toolName: data.toolName,
+          toolInput: (data.toolInput as Record<string, unknown> | undefined),
+          question: data.question,
+          header: data.header,
+          options: data.options,
+          multiSelect: data.multiSelect,
+          respond: data.respond,
+          toolCallId: data.toolCallId,
+        },
+      };
+
+      this.bus.publish(busEvent);
+    };
+  }
+
+  /**
+   * Create a handler for human_input_required events from the SDK.
+   */
+  private createHumanInputRequiredHandler(
+    runId: number,
+  ): EventHandler<"human_input_required"> {
+    return (event) => {
+      if (event.sessionId !== this.sessionId) {
+        return;
+      }
+
+      const data = event.data as HumanInputRequiredEventData;
+      const busEvent: BusEvent<"stream.human_input_required"> = {
+        type: "stream.human_input_required",
+        sessionId: this.sessionId,
+        runId,
+        timestamp: Date.now(),
+        data: {
+          requestId: data.requestId,
+          question: data.question,
+          header: data.header,
+          options: data.options,
+          nodeId: data.nodeId,
+          respond: data.respond,
+        },
+      };
+
+      this.bus.publish(busEvent);
+    };
+  }
+
+  /**
+   * Create a handler for skill.invoked events from the SDK.
+   */
+  private createSkillInvokedHandler(
+    runId: number,
+  ): EventHandler<"skill.invoked"> {
+    return (event) => {
+      if (event.sessionId !== this.sessionId) {
+        return;
+      }
+
+      const data = event.data as SkillInvokedEventData;
+      const busEvent: BusEvent<"stream.skill.invoked"> = {
+        type: "stream.skill.invoked",
+        sessionId: this.sessionId,
+        runId,
+        timestamp: Date.now(),
+        data: {
+          skillName: data.skillName,
+          skillPath: data.skillPath,
+        },
+      };
+
+      this.bus.publish(busEvent);
+    };
+  }
+
+  /**
+   * Create handler for session.compaction events.
+   */
+  private createSessionCompactionHandler(
+    runId: number,
+  ): EventHandler<"session.compaction"> {
+    return (event) => {
+      if (event.sessionId !== this.sessionId) return;
+      const data = event.data as SessionCompactionEventData;
+      this.bus.publish({
+        type: "stream.session.compaction",
+        sessionId: this.sessionId,
+        runId,
+        timestamp: Date.now(),
+        data: {
+          phase: data.phase,
+          success: data.success,
+          error: data.error,
+        },
+      });
+    };
+  }
+
+  /**
+   * Create handler for session.truncation events.
+   */
+  private createSessionTruncationHandler(
+    runId: number,
+  ): EventHandler<"session.truncation"> {
+    return (event) => {
+      if (event.sessionId !== this.sessionId) return;
+      const data = event.data as SessionTruncationEventData;
+      this.bus.publish({
+        type: "stream.session.truncation",
+        sessionId: this.sessionId,
+        runId,
+        timestamp: Date.now(),
+        data: {
+          tokenLimit: data.tokenLimit ?? 0,
+          tokensRemoved: data.tokensRemoved ?? 0,
+          messagesRemoved: data.messagesRemoved ?? 0,
+        },
+      });
+    };
+  }
+
+  /**
+   * Create handler for turn.start events.
+   */
+  private createTurnStartHandler(
+    runId: number,
+  ): EventHandler<"turn.start"> {
+    return (event) => {
+      if (event.sessionId !== this.sessionId) return;
+      const data = event.data as TurnStartEventData;
+      this.bus.publish({
+        type: "stream.turn.start",
+        sessionId: this.sessionId,
+        runId,
+        timestamp: Date.now(),
+        data: {
+          turnId: normalizeTurnStartId(
+            data.turnId,
+            this.turnMetadataState,
+          ),
+        },
+      });
+    };
+  }
+
+  /**
+   * Create handler for turn.end events.
+   */
+  private createTurnEndHandler(
+    runId: number,
+  ): EventHandler<"turn.end"> {
+    return (event) => {
+      if (event.sessionId !== this.sessionId) return;
+      const data = event.data as TurnEndEventData;
+      this.bus.publish({
+        type: "stream.turn.end",
+        sessionId: this.sessionId,
+        runId,
+        timestamp: Date.now(),
+        data: normalizeTurnEndMetadata(
+          data,
+          this.turnMetadataState,
+        ),
+      });
+    };
+  }
+
+  /**
+   * Create handler for tool.partial_result events.
+   */
+  private createToolPartialResultHandler(
+    runId: number,
+  ): EventHandler<"tool.partial_result"> {
+    return (event) => {
+      if (!this.isOwnedSession(event.sessionId)) return;
+      const data = event.data as ToolPartialResultEventData;
+      const toolCallId = this.resolveToolCorrelationId(this.asString(data.toolCallId))
+        ?? this.asString(data.toolCallId);
+
+      this.bus.publish({
+        type: "stream.tool.partial_result",
+        sessionId: this.sessionId,
+        runId,
+        timestamp: Date.now(),
+        data: {
+          toolCallId: data.toolCallId,
+          partialOutput: data.partialOutput,
+        },
+      });
+
+      if (!toolCallId) {
+        return;
+      }
+      const context = this.activeSubagentToolsById.get(toolCallId);
+      if (!context) {
+        return;
+      }
+      this.ensureSyntheticTaskAgentStart(runId, context.parentAgentId);
+      if (this.subagentTracker?.hasAgent(context.parentAgentId)) {
+        this.subagentTracker.onToolProgress(context.parentAgentId, context.toolName);
+      }
+    };
+  }
+
+  /**
+   * Create handler for session.info events.
+   */
+  private createSessionInfoHandler(
+    runId: number,
+  ): EventHandler<"session.info"> {
+    return (event) => {
+      if (event.sessionId !== this.sessionId) return;
+      const data = event.data as SessionInfoEventData;
+      this.bus.publish({
+        type: "stream.session.info",
+        sessionId: this.sessionId,
+        runId,
+        timestamp: Date.now(),
+        data: {
+          infoType: data.infoType ?? "general",
+          message: data.message ?? "",
+        },
+      });
+    };
+  }
+
+  /**
+   * Create handler for session.warning events.
+   */
+  private createSessionWarningHandler(
+    runId: number,
+  ): EventHandler<"session.warning"> {
+    return (event) => {
+      if (event.sessionId !== this.sessionId) return;
+      const data = event.data as SessionWarningEventData;
+      this.bus.publish({
+        type: "stream.session.warning",
+        sessionId: this.sessionId,
+        runId,
+        timestamp: Date.now(),
+        data: {
+          warningType: data.warningType ?? "general",
+          message: data.message ?? "",
+        },
+      });
+    };
+  }
+
+  /**
+   * Create handler for session.title_changed events.
+   */
+  private createSessionTitleChangedHandler(
+    runId: number,
+  ): EventHandler<"session.title_changed"> {
+    return (event) => {
+      if (event.sessionId !== this.sessionId) return;
+      const data = event.data as SessionTitleChangedEventData;
+      this.bus.publish({
+        type: "stream.session.title_changed",
+        sessionId: this.sessionId,
+        runId,
+        timestamp: Date.now(),
+        data: {
+          title: data.title ?? "",
+        },
+      });
+    };
+  }
+
+  /**
+   * Publish a stream.text.complete event.
+   */
+  private publishTextComplete(runId: number, messageId: string): void {
+    const event: BusEvent<"stream.text.complete"> = {
+      type: "stream.text.complete",
+      sessionId: this.sessionId,
+      runId,
+      timestamp: Date.now(),
+      data: {
+        messageId,
+        fullText: this.textAccumulator,
+      },
+    };
+
+    this.bus.publish(event);
+  }
+
+  /**
+   * Publish a deferred stream.session.idle event.
+   */
+  private publishSessionIdle(runId: number, reason: string): void {
+    const busEvent: BusEvent<"stream.session.idle"> = {
+      type: "stream.session.idle",
+      sessionId: this.sessionId,
+      runId,
+      timestamp: Date.now(),
+      data: {
+        reason,
+      },
+    };
+
+    this.bus.publish(busEvent);
+  }
+
+  private publishSessionStart(runId: number): void {
+    const event: BusEvent<"stream.session.start"> = {
+      type: "stream.session.start",
+      sessionId: this.sessionId,
+      runId,
+      timestamp: Date.now(),
+      data: {},
+    };
+    this.bus.publish(event);
+  }
+
+  /**
+   * Publish a stream.session.error event.
+   */
+  private publishSessionError(runId: number, error: unknown): void {
+    const errorMessage =
+      error instanceof Error ? error.message : String(error);
+
+    const event: BusEvent<"stream.session.error"> = {
+      type: "stream.session.error",
+      sessionId: this.sessionId,
+      runId,
+      timestamp: Date.now(),
+      data: {
+        error: errorMessage,
+      },
+    };
+
+    this.bus.publish(event);
+  }
+
+  private asRecord(value: unknown): Record<string, unknown> | undefined {
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+      return value as Record<string, unknown>;
+    }
+    return undefined;
+  }
+
+  private asString(value: unknown): string | undefined {
+    return typeof value === "string" && value.trim().length > 0
+      ? value
+      : undefined;
+  }
+
+  private extractTaskToolResultSummary(toolResult: unknown): string | undefined {
+    const directSummary = this.asString(toolResult);
+    if (directSummary) {
+      return directSummary;
+    }
+
+    const record = this.asRecord(toolResult);
+    if (!record) {
+      return undefined;
+    }
+
+    return this.asString(record.result)
+      ?? this.asString(record.output)
+      ?? this.asString(record.output_text)
+      ?? this.asString(record.text)
+      ?? this.asString(record.summary)
+      ?? this.asString(record.message);
+  }
+
+  private normalizeToolName(value: unknown): string {
+    return this.asString(value) ?? "unknown";
+  }
+
+  private isTaskTool(toolName: string): boolean {
+    const normalized = toolName.toLowerCase();
+    return normalized === "task" || normalized === "launch_agent" || normalized === "agent";
+  }
+
+  private extractTaskToolMetadata(
+    toolInput: unknown,
+    eventData?: Record<string, unknown>,
+  ): { description: string; isBackground: boolean; agentType?: string; subagentSessionId?: string } {
+    const record = this.asRecord(toolInput) ?? {};
+    const toolMetadata = this.asRecord(eventData?.toolMetadata)
+      ?? this.asRecord(record.metadata)
+      ?? {};
+    const agentType = this.asString(record.subagent_type)
+      ?? this.asString(record.subagentType)
+      ?? this.asString(record.agent_type)
+      ?? this.asString(record.agentType)
+      ?? this.asString(record.agent);
+    return {
+      description: this.asString(record.description)
+        ?? this.asString(record.prompt)
+        ?? this.asString(record.task)
+        ?? "",
+      isBackground: record.run_in_background === true
+        || this.asString(record.mode)?.toLowerCase() === "background",
+      agentType,
+      subagentSessionId: this.asString(toolMetadata.sessionId)
+        ?? this.asString(toolMetadata.sessionID),
+    };
+  }
+
+  private mergeTaskToolMetadata(
+    existing: { description: string; isBackground: boolean; agentType?: string; subagentSessionId?: string } | undefined,
+    incoming: { description: string; isBackground: boolean; agentType?: string; subagentSessionId?: string },
+  ): { description: string; isBackground: boolean; agentType?: string; subagentSessionId?: string } {
+    if (!existing) {
+      return incoming;
+    }
+    return {
+      description: incoming.description || existing.description,
+      isBackground: incoming.isBackground || existing.isBackground,
+      agentType: incoming.agentType ?? existing.agentType,
+      subagentSessionId: incoming.subagentSessionId ?? existing.subagentSessionId,
+    };
+  }
+
+  private hasTaskDispatchDetails(toolInput: unknown): boolean {
+    const record = this.asRecord(toolInput) ?? {};
+    const description = this.asString(record.description)
+      ?? this.asString(record.task)
+      ?? this.asString(record.title)
+      ?? this.asString(record.prompt);
+    const agentName = this.asString(record.subagent_type)
+      ?? this.asString(record.subagentType)
+      ?? this.asString(record.agent_type)
+      ?? this.asString(record.agentType)
+      ?? this.asString(record.agent);
+    return Boolean(description || agentName);
+  }
+
+  private serializeForSignature(value: unknown): string {
+    if (value === null || value === undefined) return String(value);
+    if (typeof value === "string") return value;
+    if (typeof value === "number" || typeof value === "boolean") {
+      return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+      return `[${value.map((entry) => this.serializeForSignature(entry)).join(",")}]`;
+    }
+    if (typeof value === "object") {
+      const entries = Object.entries(value as Record<string, unknown>)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([key, entry]) => `${key}:${this.serializeForSignature(entry)}`);
+      return `{${entries.join(",")}}`;
+    }
+    return String(value);
+  }
+
+  private buildToolStartSignature(
+    toolName: string,
+    toolInput: Record<string, unknown>,
+    toolMetadata: Record<string, unknown> | undefined,
+    parentAgentId: string | undefined,
+  ): string {
+    return `${toolName}|${parentAgentId ?? ""}|${this.serializeForSignature(toolInput)}|${this.serializeForSignature(toolMetadata ?? {})}`;
+  }
+
+  private resolveToolCorrelationId(correlationId: string | undefined): string | undefined {
+    if (!correlationId) {
+      return undefined;
+    }
+    let resolved = correlationId;
+    const visited: string[] = [];
+    const seen = new Set<string>();
+    while (!seen.has(resolved)) {
+      visited.push(resolved);
+      seen.add(resolved);
+      const next = this.toolCorrelationAliases.get(resolved);
+      if (!next || next === resolved) {
+        break;
+      }
+      resolved = next;
+    }
+    for (const alias of visited) {
+      this.toolCorrelationAliases.set(alias, resolved);
+    }
+    return resolved;
+  }
+
+  private registerPreferredToolCorrelationAlias(
+    preferredCorrelationId: string,
+    ...correlationIds: Array<string | undefined>
+  ): void {
+    const canonicalPreferred = this.resolveToolCorrelationId(preferredCorrelationId)
+      ?? preferredCorrelationId;
+    this.toolCorrelationAliases.set(canonicalPreferred, canonicalPreferred);
+
+    for (const correlationId of correlationIds) {
+      if (!correlationId) {
+        continue;
+      }
+      const canonicalCorrelation = this.resolveToolCorrelationId(correlationId)
+        ?? correlationId;
+      if (canonicalCorrelation !== canonicalPreferred) {
+        this.repointToolCorrelationAliases(canonicalCorrelation, canonicalPreferred);
+      }
+      this.toolCorrelationAliases.set(correlationId, canonicalPreferred);
+    }
+  }
+
+  private repointToolCorrelationAliases(
+    fromCorrelationId: string,
+    toCorrelationId: string,
+  ): void {
+    if (fromCorrelationId === toCorrelationId) {
+      return;
+    }
+    for (const [aliasId, targetCorrelationId] of this.toolCorrelationAliases.entries()) {
+      if (targetCorrelationId === fromCorrelationId) {
+        this.toolCorrelationAliases.set(aliasId, toCorrelationId);
+      }
+    }
+    this.toolCorrelationAliases.set(fromCorrelationId, toCorrelationId);
+  }
+
+  private registerToolCorrelationAliases(
+    toolId: string,
+    ...correlationIds: Array<string | undefined>
+  ): void {
+    const canonicalToolId = this.resolveToolCorrelationId(toolId) ?? toolId;
+    this.toolCorrelationAliases.set(canonicalToolId, canonicalToolId);
+    for (const correlationId of correlationIds) {
+      if (!correlationId || correlationId === canonicalToolId) {
+        continue;
+      }
+      this.registerPreferredToolCorrelationAlias(canonicalToolId, correlationId);
+    }
+  }
+
+  private recordPendingTaskToolCorrelationId(correlationId: string): void {
+    if (this.pendingTaskToolCorrelationIds.includes(correlationId)) {
+      return;
+    }
+    this.pendingTaskToolCorrelationIds.push(correlationId);
+  }
+
+  private removePendingTaskToolCorrelationId(correlationId: string): void {
+    this.pendingTaskToolCorrelationIds = this.pendingTaskToolCorrelationIds.filter(
+      (candidate) => candidate !== correlationId,
+    );
+  }
+
+  private resolveNextPendingTaskToolCorrelationId(): string | undefined {
+    for (const correlationId of this.pendingTaskToolCorrelationIds) {
+      const mappedAgentId = this.toolUseIdToSubagentId.get(correlationId);
+      if (
+        this.taskToolMetadata.has(correlationId)
+        && (!mappedAgentId || isSyntheticTaskAgentId(mappedAgentId))
+      ) {
+        return correlationId;
+      }
+    }
+    return undefined;
+  }
+
+  private recordPendingSubagentCorrelationId(correlationId: string): void {
+    if (this.pendingSubagentCorrelationIds.includes(correlationId)) {
+      return;
+    }
+    this.pendingSubagentCorrelationIds.push(correlationId);
+  }
+
+  private removePendingSubagentCorrelationId(correlationId: string): void {
+    this.pendingSubagentCorrelationIds = this.pendingSubagentCorrelationIds.filter(
+      (candidate) => candidate !== correlationId,
+    );
+  }
+
+  private resolvePendingSubagentTaskCorrelation(taskCorrelationId: string): void {
+    if (this.toolUseIdToSubagentId.has(taskCorrelationId)) {
+      return;
+    }
+    for (const subagentCorrelationId of this.pendingSubagentCorrelationIds) {
+      const canonicalSubagentCorrelationId = this.resolveToolCorrelationId(subagentCorrelationId)
+        ?? subagentCorrelationId;
+      const subagentId = this.toolUseIdToSubagentId.get(canonicalSubagentCorrelationId);
+      if (!subagentId) {
+        continue;
+      }
+
+      this.registerPreferredToolCorrelationAlias(taskCorrelationId, canonicalSubagentCorrelationId);
+      this.toolUseIdToSubagentId.set(taskCorrelationId, subagentId);
+      this.subagentIdToCorrelationId.set(subagentId, taskCorrelationId);
+      this.removePendingTaskToolCorrelationId(taskCorrelationId);
+      this.removePendingSubagentCorrelationId(subagentCorrelationId);
+      return;
+    }
+  }
+
+  private resolveKnownSubagentCorrelation(
+    subagentId: string,
+    subagentSessionId: string | undefined,
+  ): string | undefined {
+    const byId = this.subagentIdToCorrelationId.get(subagentId);
+    if (byId) {
+      return this.resolveToolCorrelationId(byId);
+    }
+    if (subagentSessionId) {
+      const bySession = this.subagentSessionToCorrelationId.get(subagentSessionId);
+      if (bySession) {
+        return this.resolveToolCorrelationId(bySession);
+      }
+    }
+    return undefined;
+  }
+
+  private resolveSyntheticTaskParentAgentId(
+    taskCorrelationId: string | undefined,
+  ): string | undefined {
+    if (!taskCorrelationId) {
+      return undefined;
+    }
+    const mappedAgentId = this.toolUseIdToSubagentId.get(taskCorrelationId);
+    if (!mappedAgentId || !isSyntheticTaskAgentId(mappedAgentId)) {
+      return undefined;
+    }
+    return mappedAgentId;
+  }
+
+  private buildSyntheticTaskAgentId(correlationId: string): string {
+    return `${SYNTHETIC_TASK_AGENT_PREFIX}${correlationId}`;
+  }
+
+  private extractSyntheticTaskCorrelationId(agentId: string): string | undefined {
+    if (!isSyntheticTaskAgentId(agentId)) {
+      return undefined;
+    }
+    const correlationId = agentId.slice(SYNTHETIC_TASK_AGENT_PREFIX.length);
+    return correlationId.length > 0 ? correlationId : undefined;
+  }
+
+  private buildTrackedToolStartKey(parentAgentId: string, toolId: string): string {
+    return `${parentAgentId}::${toolId}`;
+  }
+
+  private recordActiveSubagentToolContext(
+    toolId: string,
+    toolName: string,
+    parentAgentId: string,
+    ...correlationIds: Array<string | undefined>
+  ): void {
+    const context = { parentAgentId, toolName };
+    const ids = [toolId, ...correlationIds]
+      .map((id) => this.resolveToolCorrelationId(id) ?? id)
+      .filter((id): id is string => Boolean(id));
+    for (const id of ids) {
+      this.activeSubagentToolsById.set(id, context);
+    }
+  }
+
+  private removeActiveSubagentToolContext(
+    toolId: string,
+    ...correlationIds: Array<string | undefined>
+  ): void {
+    const ids = [toolId, ...correlationIds]
+      .map((id) => this.resolveToolCorrelationId(id) ?? id)
+      .filter((id): id is string => Boolean(id));
+    for (const id of ids) {
+      this.activeSubagentToolsById.delete(id);
+    }
+  }
+
+  private queueEarlyToolEvent(
+    key: string,
+    toolId: string,
+    toolName: string,
+  ): void {
+    const queue = this.earlyToolEvents.get(key) ?? [];
+    if (queue.some((entry) => entry.toolId === toolId)) {
+      return;
+    }
+    queue.push({ toolId, toolName });
+    this.earlyToolEvents.set(key, queue);
+  }
+
+  private removeEarlyToolEvent(
+    key: string,
+    toolId: string,
+  ): void {
+    const queue = this.earlyToolEvents.get(key);
+    if (!queue) {
+      return;
+    }
+    const nextQueue = queue.filter((entry) => entry.toolId !== toolId);
+    if (nextQueue.length === 0) {
+      this.earlyToolEvents.delete(key);
+      return;
+    }
+    this.earlyToolEvents.set(key, nextQueue);
+  }
+
+  private replayEarlyToolEvents(
+    agentId: string,
+    ...keys: Array<string | undefined>
+  ): void {
+    for (const key of keys) {
+      if (!key) {
+        continue;
+      }
+      const queue = this.earlyToolEvents.get(key);
+      if (!queue) {
+        continue;
+      }
+      for (const tool of queue) {
+        const trackerKey = this.buildTrackedToolStartKey(agentId, tool.toolId);
+        if (this.trackedToolStartKeys.has(trackerKey)) {
+          continue;
+        }
+        this.trackedToolStartKeys.add(trackerKey);
+        this.subagentTracker?.onToolStart(agentId, tool.toolName);
+      }
+      this.earlyToolEvents.delete(key);
+    }
+  }
+
+  private ensureSyntheticTaskAgentStart(runId: number, agentId: string): void {
+    if (!isSyntheticTaskAgentId(agentId) || this.syntheticAgentStartsPublished.has(agentId)) {
+      return;
+    }
+
+    const sdkCorrelationId = this.extractSyntheticTaskCorrelationId(agentId);
+    const metadata = sdkCorrelationId
+      ? this.taskToolMetadata.get(sdkCorrelationId)
+      : undefined;
+    if (!metadata) {
+      return;
+    }
+
+    const normalizedMetadata = normalizeAgentTaskMetadata({
+      task: metadata.description,
+      agentType: metadata.agentType,
+      isBackground: metadata.isBackground,
+    });
+
+    this.subagentTracker?.registerAgent(agentId);
+    this.syntheticAgentStartsPublished.add(agentId);
+    this.bus.publish({
+      type: "stream.agent.start",
+      sessionId: this.sessionId,
+      runId,
+      timestamp: Date.now(),
+      data: {
+        agentId,
+        toolCallId: sdkCorrelationId ?? agentId,
+        agentType: metadata.agentType ?? "agent",
+        task: normalizedMetadata.task,
+        isBackground: normalizedMetadata.isBackground,
+        ...(sdkCorrelationId ? { sdkCorrelationId } : {}),
+      },
+    });
+  }
+
+  private ensureSyntheticTaskSubagentMapping(
+    taskCorrelationId: string,
+    toolInput: unknown,
+    runId: number,
+  ): void {
+    if (!this.hasTaskDispatchDetails(toolInput)) {
+      return;
+    }
+    const existingAgentId = this.toolUseIdToSubagentId.get(taskCorrelationId);
+    if (existingAgentId && !isSyntheticTaskAgentId(existingAgentId)) {
+      return;
+    }
+    const syntheticAgentId = existingAgentId ?? this.buildSyntheticTaskAgentId(taskCorrelationId);
+    this.toolUseIdToSubagentId.set(taskCorrelationId, syntheticAgentId);
+    this.subagentIdToCorrelationId.set(syntheticAgentId, taskCorrelationId);
+    this.ensureSyntheticTaskAgentStart(runId, syntheticAgentId);
+  }
+
+  private registerTaskSubagentSessionCorrelation(
+    taskCorrelationId: string,
+    subagentSessionId: string | undefined,
+  ): void {
+    if (!subagentSessionId) {
+      return;
+    }
+    const mappedAgentId = this.toolUseIdToSubagentId.get(taskCorrelationId);
+    if (!mappedAgentId) {
+      return;
+    }
+    this.ownedSessionIds.add(subagentSessionId);
+    this.subagentSessionToAgentId.set(subagentSessionId, mappedAgentId);
+    this.subagentSessionToCorrelationId.set(subagentSessionId, taskCorrelationId);
+  }
+
+  private createSyntheticToolId(runId: number, toolName: string): string {
+    this.syntheticToolCounter += 1;
+    const normalizedName = toolName.replace(/[^a-zA-Z0-9_-]/g, "_");
+    return `tool_${runId}_${normalizedName}_${this.syntheticToolCounter}`;
+  }
+
+  private queueToolId(toolName: string, toolId: string): void {
+    const queue = this.pendingToolIdsByName.get(toolName) ?? [];
+    if (!queue.includes(toolId)) {
+      queue.push(toolId);
+      this.pendingToolIdsByName.set(toolName, queue);
+    }
+  }
+
+  private removeQueuedToolId(toolName: string, toolId: string): void {
+    const queue = this.pendingToolIdsByName.get(toolName);
+    if (!queue) return;
+    const nextQueue = queue.filter((queuedId) => queuedId !== toolId);
+    if (nextQueue.length === 0) {
+      this.pendingToolIdsByName.delete(toolName);
+      return;
+    }
+    this.pendingToolIdsByName.set(toolName, nextQueue);
+  }
+
+  private shiftQueuedToolId(toolName: string): string | undefined {
+    const queue = this.pendingToolIdsByName.get(toolName);
+    if (!queue || queue.length === 0) {
+      return undefined;
+    }
+    const [toolId, ...rest] = queue;
+    if (rest.length === 0) {
+      this.pendingToolIdsByName.delete(toolName);
+    } else {
+      this.pendingToolIdsByName.set(toolName, rest);
+    }
+    return toolId;
+  }
+
+  private resolveToolStartId(
+    explicitToolId: string | undefined,
+    runId: number,
+    toolName: string,
+  ): string {
+    const toolId = explicitToolId ?? this.createSyntheticToolId(runId, toolName);
+    this.queueToolId(toolName, toolId);
+    return toolId;
+  }
+
+  private resolveToolCompleteId(
+    explicitToolId: string | undefined,
+    runId: number,
+    toolName: string,
+  ): string {
+    if (explicitToolId) {
+      this.removeQueuedToolId(toolName, explicitToolId);
+      return explicitToolId;
+    }
+    return this.shiftQueuedToolId(toolName) ?? this.createSyntheticToolId(runId, toolName);
+  }
+
+  /**
+   * Clean up SDK event subscriptions.
+   */
+  /**
+   * Force-complete any tools that received start but no complete event.
+   * Prevents tools from being stuck in running state after stream abort.
+   */
+  private cleanupOrphanedTools(runId: number): void {
+    for (const [toolName, toolIds] of this.pendingToolIdsByName.entries()) {
+      for (const toolId of toolIds) {
+        const event: BusEvent<"stream.tool.complete"> = {
+          type: "stream.tool.complete",
+          sessionId: this.sessionId,
+          runId,
+          timestamp: Date.now(),
+          data: {
+            toolId,
+            toolName,
+            toolResult: null,
+            success: false,
+            error: "Tool execution aborted",
+          },
+        };
+        this.bus.publish(event);
+      }
+    }
+    this.pendingToolIdsByName.clear();
+    this.toolStartSignatureByToolId.clear();
+    this.trackedToolStartKeys.clear();
+    this.earlyToolEvents.clear();
+    this.activeSubagentToolsById.clear();
+  }
+
+  private cleanupSubscriptions(): void {
+    for (const unsub of this.unsubscribers) {
+      unsub();
+    }
+    this.unsubscribers = [];
+  }
+
+  /**
+   * Cancel the ongoing stream and cleanup resources.
+   */
+  dispose(): void {
+    if (this.abortController) {
+      this.abortController.abort();
+      this.abortController = null;
+    }
+    this.cleanupSubscriptions();
+    this.textAccumulator = "";
+    this.thinkingBlocks.clear();
+    this.pendingToolIdsByName.clear();
+    this.toolStartSignatureByToolId.clear();
+    this.toolCorrelationAliases.clear();
+    this.taskToolMetadata.clear();
+    this.pendingTaskToolCorrelationIds = [];
+    this.pendingSubagentCorrelationIds = [];
+    this.toolUseIdToSubagentId.clear();
+    this.subagentIdToCorrelationId.clear();
+    this.subagentSessionToCorrelationId.clear();
+    this.syntheticAgentStartsPublished.clear();
+    this.trackedToolStartKeys.clear();
+    this.earlyToolEvents.clear();
+    this.activeSubagentToolsById.clear();
+    this.syntheticToolCounter = 0;
+    this.ownedSessionIds.clear();
+    this.subagentSessionToAgentId.clear();
+    this.subagentTracker?.reset();
+    this.subagentTracker = null;
+    this.runtimeFeatureFlags = { ...DEFAULT_WORKFLOW_RUNTIME_FEATURE_FLAGS };
+    resetTurnMetadataState(this.turnMetadataState);
+    this.lastSeenOutputTokens = 0;
+    this.accumulatedOutputTokens = 0;
+  }
+
+  private resolveRuntimeFeatureFlags(
+    overrides: WorkflowRuntimeFeatureFlagOverrides | undefined,
+  ): WorkflowRuntimeFeatureFlags {
+    return resolveWorkflowRuntimeFeatureFlags(overrides);
+  }
+
+  private isOwnedSession(eventSessionId: string): boolean {
+    return eventSessionId === this.sessionId || this.ownedSessionIds.has(eventSessionId);
+  }
+
+  private resolveParentAgentId(
+    eventSessionId: string,
+    data: Record<string, unknown>,
+  ): string | undefined {
+    const explicitParentAgentId = this.asString(data.parentAgentId ?? data.parentId);
+    if (explicitParentAgentId) {
+      return explicitParentAgentId;
+    }
+    const parentToolUseId = this.resolveToolCorrelationId(this.asString(
+      data.parentToolUseId
+        ?? data.parent_tool_use_id
+        ?? data.parentToolUseID,
+    ));
+    if (parentToolUseId) {
+      const mappedAgentId = this.toolUseIdToSubagentId.get(parentToolUseId);
+      if (mappedAgentId) {
+        return mappedAgentId;
+      }
+    }
+    if (eventSessionId === this.sessionId) {
+      return undefined;
+    }
+    const mappedAgentId = this.subagentSessionToAgentId.get(eventSessionId);
+    if (mappedAgentId) {
+      return mappedAgentId;
+    }
+    // Fallback: when a provider emits child-session tool events before
+    // subagentSessionId correlation is fully established, attribute tools
+    // to the sole active sub-agent if there is exactly one.
+    if (this.subagentIdToCorrelationId.size === 1) {
+      return this.subagentIdToCorrelationId.keys().next().value;
+    }
+    return undefined;
+  }
+}
diff --git a/src/events/adapters/retry.ts b/src/events/adapters/retry.ts
new file mode 100644
index 0000000000..eaf3abe0b7
--- /dev/null
+++ b/src/events/adapters/retry.ts
@@ -0,0 +1,233 @@
+/**
+ * Stream Retry Module
+ *
+ * Provides provider-level retry with exponential backoff for failed LLM calls.
+ * Modeled after OpenCode's session/retry.ts and provider/error.ts patterns.
+ *
+ * Key features:
+ * - Error classification: retryable (429, 503, ECONNRESET) vs permanent
+ * - Exponential backoff with retry-after header parsing
+ * - Abort-aware sleep (respects AbortSignal)
+ * - Human-readable retry messages for UI broadcast
+ */
+
+/** Initial retry delay in milliseconds */
+const RETRY_INITIAL_DELAY = 2000;
+/** Backoff multiplier applied per attempt */
+const RETRY_BACKOFF_FACTOR = 2;
+/** Maximum delay when no retry-after headers are present */
+const RETRY_MAX_DELAY_NO_HEADERS = 30_000;
+/** Default maximum retry attempts */
+const DEFAULT_MAX_RETRIES = 5;
+
+/** HTTP status codes that are always retryable */
+const RETRYABLE_STATUS_CODES = new Set([429, 500, 502, 503, 504]);
+
+/** Error message substrings that indicate transient failures */
+const TRANSIENT_ERROR_PATTERNS = [
+  "econnreset",
+  "econnrefused",
+  "etimedout",
+  "socket hang up",
+  "network",
+  "failed to fetch",
+  "load failed",
+  "overloaded",
+  "rate limit",
+  "too many requests",
+  "service unavailable",
+  "bad gateway",
+  "gateway timeout",
+  "internal server error",
+] as const;
+
+/**
+ * Classified error with retryability information.
+ */
+export interface ClassifiedError {
+  /** Whether this error can be retried */
+  isRetryable: boolean;
+  /** Human-readable error message */
+  message: string;
+  /** HTTP status code if available */
+  statusCode?: number;
+  /** Response headers for retry-after parsing */
+  responseHeaders?: Record<string, string>;
+}
+
+/**
+ * Retry state broadcast to the UI via stream.session.retry events.
+ */
+export interface RetryState {
+  /** Current attempt number (1-based) */
+  attempt: number;
+  /** Delay in milliseconds before next retry */
+  delay: number;
+  /** Human-readable reason for retry */
+  message: string;
+  /** Unix timestamp when next retry will occur */
+  nextRetryAt: number;
+}
+
+/**
+ * Classify an error as retryable or permanent.
+ *
+ * Checks HTTP status codes, error messages, and known transient patterns.
+ */
+export function classifyError(error: unknown): ClassifiedError {
+  if (error instanceof DOMException && error.name === "AbortError") {
+    return { isRetryable: false, message: "Aborted" };
+  }
+
+  const errorRecord = error as Record<string, unknown>;
+  const statusCode = typeof errorRecord?.statusCode === "number"
+    ? errorRecord.statusCode
+    : typeof errorRecord?.status === "number"
+      ? errorRecord.status
+      : undefined;
+  const responseHeaders = extractResponseHeaders(errorRecord);
+  const message = error instanceof Error ? error.message : String(error);
+  const messageLower = message.toLowerCase();
+
+  // Check system-level connection errors
+  const systemCode = (errorRecord as { code?: string })?.code;
+  if (systemCode === "ECONNRESET" || systemCode === "ECONNREFUSED" || systemCode === "ETIMEDOUT") {
+    return {
+      isRetryable: true,
+      message: `Connection error: ${systemCode}`,
+      statusCode,
+      responseHeaders,
+    };
+  }
+
+  // Check HTTP status code
+  if (statusCode !== undefined && RETRYABLE_STATUS_CODES.has(statusCode)) {
+    const retryMessage = statusCode === 429
+      ? "Rate limited"
+      : statusCode === 503
+        ? "Service unavailable"
+        : `Server error (${statusCode})`;
+    return {
+      isRetryable: true,
+      message: retryMessage,
+      statusCode,
+      responseHeaders,
+    };
+  }
+
+  // Check error message patterns
+  for (const pattern of TRANSIENT_ERROR_PATTERNS) {
+    if (messageLower.includes(pattern)) {
+      return {
+        isRetryable: true,
+        message: messageLower.includes("overloaded")
+          ? "Provider is overloaded"
+          : messageLower.includes("rate limit") || messageLower.includes("too many requests")
+            ? "Rate limited"
+            : message,
+        statusCode,
+        responseHeaders,
+      };
+    }
+  }
+
+  // Check if the error itself declares retryability (AI SDK pattern)
+  if (typeof errorRecord?.isRetryable === "boolean") {
+    return {
+      isRetryable: errorRecord.isRetryable as boolean,
+      message,
+      statusCode,
+      responseHeaders,
+    };
+  }
+
+  // Default: not retryable
+  return { isRetryable: false, message, statusCode, responseHeaders };
+}
+
+/**
+ * Compute the delay before the next retry attempt.
+ *
+ * Priority:
+ * 1. `retry-after-ms` header (milliseconds)
+ * 2. `retry-after` header (seconds or HTTP date)
+ * 3. Exponential backoff: RETRY_INITIAL_DELAY * RETRY_BACKOFF_FACTOR^(attempt-1)
+ */
+export function computeDelay(attempt: number, classified?: ClassifiedError): number {
+  if (classified?.responseHeaders) {
+    const headers = classified.responseHeaders;
+
+    // Check retry-after-ms header (milliseconds)
+    const retryAfterMs = headers["retry-after-ms"];
+    if (retryAfterMs) {
+      const parsedMs = Number.parseFloat(retryAfterMs);
+      if (!Number.isNaN(parsedMs) && parsedMs > 0) return parsedMs;
+    }
+
+    // Check retry-after header (seconds or HTTP date)
+    const retryAfter = headers["retry-after"];
+    if (retryAfter) {
+      const parsedSeconds = Number.parseFloat(retryAfter);
+      if (!Number.isNaN(parsedSeconds) && parsedSeconds > 0) {
+        return Math.ceil(parsedSeconds * 1000);
+      }
+      // Try parsing as HTTP date
+      const parsed = Date.parse(retryAfter) - Date.now();
+      if (!Number.isNaN(parsed) && parsed > 0) return Math.ceil(parsed);
+    }
+
+    // Headers present but no usable retry-after — use uncapped backoff
+    return RETRY_INITIAL_DELAY * Math.pow(RETRY_BACKOFF_FACTOR, attempt - 1);
+  }
+
+  // No headers — capped backoff
+  return Math.min(
+    RETRY_INITIAL_DELAY * Math.pow(RETRY_BACKOFF_FACTOR, attempt - 1),
+    RETRY_MAX_DELAY_NO_HEADERS,
+  );
+}
+
+/**
+ * Sleep for a given number of milliseconds, respecting an AbortSignal.
+ *
+ * @throws DOMException with name "AbortError" if signal is aborted
+ */
+export function retrySleep(ms: number, signal: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal.aborted) {
+      reject(new DOMException("Aborted", "AbortError"));
+      return;
+    }
+
+    const abortHandler = () => {
+      clearTimeout(timeout);
+      reject(new DOMException("Aborted", "AbortError"));
+    };
+
+    const timeout = setTimeout(() => {
+      signal.removeEventListener("abort", abortHandler);
+      resolve();
+    }, ms);
+
+    signal.addEventListener("abort", abortHandler, { once: true });
+  });
+}
+
+/** Extract response headers from an error object */
+function extractResponseHeaders(
+  error: Record<string, unknown>,
+): Record<string, string> | undefined {
+  const headers = error?.responseHeaders ?? error?.headers;
+  if (typeof headers === "object" && headers !== null) {
+    const result: Record<string, string> = {};
+    for (const [key, value] of Object.entries(headers as Record<string, unknown>)) {
+      if (typeof value === "string") {
+        result[key.toLowerCase()] = value;
+      }
+    }
+    return Object.keys(result).length > 0 ? result : undefined;
+  }
+  return undefined;
+}
+
+export { DEFAULT_MAX_RETRIES };
diff --git a/src/events/adapters/subagent-adapter.test.ts b/src/events/adapters/subagent-adapter.test.ts
new file mode 100644
index 0000000000..b1ec3e0beb
--- /dev/null
+++ b/src/events/adapters/subagent-adapter.test.ts
@@ -0,0 +1,1002 @@
+/**
+ * SubagentStreamAdapter Tests
+ *
+ * Unit tests for the sub-agent stream adapter that bridges SDK session
+ * streams to the shared event bus. Tests verify:
+ * 1. Text deltas are published and accumulated correctly
+ * 2. Thinking deltas and completion events are published
+ * 3. Tool use/result events are published with correct IDs
+ * 4. Token usage is tracked and published
+ * 5. stream.text.complete is published on stream end
+ * 6. Abort signal stops stream consumption
+ * 7. Stream errors are caught and published
+ * 8. SubagentStreamResult is returned with correct metadata
+ */
+
+import { describe, expect, test, beforeEach } from "bun:test";
+import { EventBus } from "../event-bus.ts";
+import { SubagentStreamAdapter } from "./subagent-adapter.ts";
+import type { BusEvent, BusEventType } from "../bus-events.ts";
+import type { AgentMessage } from "../../sdk/types.ts";
+
+// ============================================================================
+// Mock Utilities
+// ============================================================================
+
+/**
+ * Create an async iterable from an array of AgentMessages.
+ */
+async function* mockStream(
+  chunks: AgentMessage[],
+): AsyncGenerator<AgentMessage> {
+  for (const chunk of chunks) {
+    yield chunk;
+  }
+}
+
+/**
+ * Create an async iterable that throws after yielding some chunks.
+ */
+async function* errorStream(
+  chunks: AgentMessage[],
+  error: Error,
+): AsyncGenerator<AgentMessage> {
+  for (const chunk of chunks) {
+    yield chunk;
+  }
+  throw error;
+}
+
+/**
+ * Collect all events published to the bus.
+ */
+function collectEvents(bus: EventBus): BusEvent[] {
+  const events: BusEvent[] = [];
+  bus.onAll((event) => events.push(event));
+  return events;
+}
+
+/**
+ * Filter events by type.
+ */
+function filterByType<T extends BusEventType>(
+  events: BusEvent[],
+  type: T,
+): BusEvent<T>[] {
+  return events.filter((e) => e.type === type) as BusEvent<T>[];
+}
+
+// ============================================================================
+// Tests
+// ============================================================================
+
+describe("SubagentStreamAdapter", () => {
+  let bus: EventBus;
+  let events: BusEvent[];
+
+  const SESSION_ID = "parent-session-123";
+  const AGENT_ID = "worker-1";
+  const RUN_ID = 42;
+
+  beforeEach(() => {
+    bus = new EventBus();
+    events = collectEvents(bus);
+  });
+
+  function createAdapter(overrides?: {
+    parentAgentId?: string;
+  }): SubagentStreamAdapter {
+    return new SubagentStreamAdapter({
+      bus,
+      sessionId: SESSION_ID,
+      agentId: AGENT_ID,
+      runId: RUN_ID,
+      parentAgentId: overrides?.parentAgentId,
+    });
+  }
+
+  // --------------------------------------------------------------------------
+  // Text Events
+  // --------------------------------------------------------------------------
+
+  describe("text events", () => {
+    test("publishes stream.text.delta for text chunks", async () => {
+      const adapter = createAdapter();
+      const stream = mockStream([
+        { type: "text", content: "Hello " },
+        { type: "text", content: "world" },
+      ]);
+
+      await adapter.consumeStream(stream);
+
+      const deltas = filterByType(events, "stream.text.delta");
+      expect(deltas).toHaveLength(2);
+      expect(deltas[0]!.data.delta).toBe("Hello ");
+      expect(deltas[1]!.data.delta).toBe("world");
+      expect(deltas[0]!.sessionId).toBe(SESSION_ID);
+      expect(deltas[0]!.runId).toBe(RUN_ID);
+      expect(deltas[0]!.data.messageId).toBe(`subagent-${AGENT_ID}`);
+    });
+
+    test("accumulates full text in SubagentStreamResult", async () => {
+      const adapter = createAdapter();
+      const stream = mockStream([
+        { type: "text", content: "Hello " },
+        { type: "text", content: "world" },
+      ]);
+
+      const result = await adapter.consumeStream(stream);
+
+      expect(result.output).toBe("Hello world");
+      expect(result.success).toBe(true);
+      expect(result.agentId).toBe(AGENT_ID);
+    });
+
+    test("publishes stream.text.complete on stream end", async () => {
+      const adapter = createAdapter();
+      const stream = mockStream([{ type: "text", content: "done" }]);
+
+      await adapter.consumeStream(stream);
+
+      const completes = filterByType(events, "stream.text.complete");
+      expect(completes).toHaveLength(1);
+      expect(completes[0]!.data.fullText).toBe("done");
+      expect(completes[0]!.data.messageId).toBe(`subagent-${AGENT_ID}`);
+    });
+
+    test("ignores non-string text content", async () => {
+      const adapter = createAdapter();
+      const stream = mockStream([
+        { type: "text", content: { structured: true } as unknown as string },
+        { type: "text", content: "actual text" },
+      ]);
+
+      const result = await adapter.consumeStream(stream);
+
+      const deltas = filterByType(events, "stream.text.delta");
+      expect(deltas).toHaveLength(1);
+      expect(result.output).toBe("actual text");
+    });
+  });
+
+  // --------------------------------------------------------------------------
+  // Thinking Events
+  // --------------------------------------------------------------------------
+
+  describe("thinking events", () => {
+    test("publishes stream.thinking.delta for thinking chunks", async () => {
+      const adapter = createAdapter();
+      const stream = mockStream([
+        {
+          type: "thinking",
+          content: "Let me think...",
+          metadata: { thinkingSourceKey: "source-1" },
+        },
+      ]);
+
+      await adapter.consumeStream(stream);
+
+      const deltas = filterByType(events, "stream.thinking.delta");
+      expect(deltas).toHaveLength(1);
+      expect(deltas[0]!.data.delta).toBe("Let me think...");
+      expect(deltas[0]!.data.sourceKey).toBe("source-1");
+      expect(deltas[0]!.sessionId).toBe(SESSION_ID);
+    });
+
+    test("uses 'default' sourceKey when not specified", async () => {
+      const adapter = createAdapter();
+      const stream = mockStream([
+        { type: "thinking", content: "thinking..." },
+      ]);
+
+      await adapter.consumeStream(stream);
+
+      const deltas = filterByType(events, "stream.thinking.delta");
+      expect(deltas).toHaveLength(1);
+      expect(deltas[0]!.data.sourceKey).toBe("default");
+    });
+
+    test("publishes stream.thinking.complete with duration", async () => {
+      const adapter = createAdapter();
+      const stream = mockStream([
+        {
+          type: "thinking",
+          content: "thinking...",
+          metadata: { thinkingSourceKey: "src-1" },
+        },
+        {
+          type: "thinking",
+          content: "",
+          metadata: {
+            thinkingSourceKey: "src-1",
+            streamingStats: { thinkingMs: 1500 },
+          },
+        },
+      ]);
+
+      await adapter.consumeStream(stream);
+
+      const completes = filterByType(events, "stream.thinking.complete");
+      expect(completes).toHaveLength(1);
+      expect(completes[0]!.data.sourceKey).toBe("src-1");
+      expect(completes[0]!.data.durationMs).toBe(1500);
+    });
+
+    test("tracks thinking duration in result", async () => {
+      const adapter = createAdapter();
+      const stream = mockStream([
+        {
+          type: "thinking",
+          content: "thinking...",
+          metadata: { thinkingSourceKey: "src-1" },
+        },
+        {
+          type: "thinking",
+          content: "",
+          metadata: {
+            thinkingSourceKey: "src-1",
+            streamingStats: { thinkingMs: 1200 },
+          },
+        },
+      ]);
+
+      const result = await adapter.consumeStream(stream);
+
+      expect(result.thinkingDurationMs).toBe(1200);
+    });
+  });
+
+  // --------------------------------------------------------------------------
+  // Tool Events
+  // --------------------------------------------------------------------------
+
+  describe("tool events", () => {
+    test("publishes stream.tool.start for tool_use chunks", async () => {
+      const adapter = createAdapter();
+      const stream = mockStream([
+        {
+          type: "tool_use",
+          content: {
+            name: "bash",
+            toolUseId: "tool-abc",
+            input: { command: "ls" },
+          } as unknown as string,
+        },
+      ]);
+
+      await adapter.consumeStream(stream);
+
+      const starts = filterByType(events, "stream.tool.start");
+      expect(starts).toHaveLength(1);
+      expect(starts[0]!.data.toolName).toBe("bash");
+      expect(starts[0]!.data.toolId).toBe("tool-abc");
+      expect(starts[0]!.data.toolInput).toEqual({ command: "ls" });
+    });
+
+    test("publishes stream.tool.complete for tool_result chunks", async () => {
+      const adapter = createAdapter();
+      const stream = mockStream([
+        {
+          type: "tool_use",
+          content: {
+            name: "bash",
+            toolUseId: "tool-abc",
+            input: {},
+          } as unknown as string,
+        },
+        {
+          type: "tool_result",
+          content: "file.txt" as string,
+          tool_use_id: "tool-abc",
+          toolName: "bash",
+        } as unknown as AgentMessage,
+      ]);
+
+      await adapter.consumeStream(stream);
+
+      const completes = filterByType(events, "stream.tool.complete");
+      expect(completes).toHaveLength(1);
+      expect(completes[0]!.data.toolId).toBe("tool-abc");
+      expect(completes[0]!.data.toolName).toBe("bash");
+      expect(completes[0]!.data.success).toBe(true);
+    });
+
+    test("increments toolUses count", async () => {
+      const adapter = createAdapter();
+      const stream = mockStream([
+        {
+          type: "tool_use",
+          content: {
+            name: "bash",
+            toolUseId: "t1",
+            input: {},
+          } as unknown as string,
+        },
+        {
+          type: "tool_use",
+          content: {
+            name: "edit",
+            toolUseId: "t2",
+            input: {},
+          } as unknown as string,
+        },
+      ]);
+
+      const result = await adapter.consumeStream(stream);
+
+      expect(result.toolUses).toBe(2);
+    });
+
+    test("records tool details with duration", async () => {
+      const adapter = createAdapter();
+      const stream = mockStream([
+        {
+          type: "tool_use",
+          content: {
+            name: "bash",
+            toolUseId: "t1",
+            input: {},
+          } as unknown as string,
+        },
+        {
+          type: "tool_result",
+          content: "ok",
+          tool_use_id: "t1",
+          toolName: "bash",
+        } as unknown as AgentMessage,
+      ]);
+
+      const result = await adapter.consumeStream(stream);
+
+      expect(result.toolDetails).toBeDefined();
+      expect(result.toolDetails).toHaveLength(1);
+      expect(result.toolDetails![0]!.toolId).toBe("t1");
+      expect(result.toolDetails![0]!.toolName).toBe("bash");
+      expect(result.toolDetails![0]!.success).toBe(true);
+      expect(result.toolDetails![0]!.durationMs).toBeGreaterThanOrEqual(0);
+    });
+
+    test("tracks tool errors in details", async () => {
+      const adapter = createAdapter();
+      const stream = mockStream([
+        {
+          type: "tool_use",
+          content: {
+            name: "bash",
+            toolUseId: "t1",
+            input: {},
+          } as unknown as string,
+        },
+        {
+          type: "tool_result",
+          content: { error: "command not found" },
+          tool_use_id: "t1",
+          toolName: "bash",
+          is_error: true,
+        } as unknown as AgentMessage,
+      ]);
+
+      const result = await adapter.consumeStream(stream);
+
+      expect(result.toolDetails![0]!.success).toBe(false);
+
+      const completes = filterByType(events, "stream.tool.complete");
+      expect(completes[0]!.data.success).toBe(false);
+      expect(completes[0]!.data.error).toBe("command not found");
+    });
+
+    test("generates synthetic tool IDs when not provided", async () => {
+      const adapter = createAdapter();
+      const stream = mockStream([
+        {
+          type: "tool_use",
+          content: { name: "bash", input: {} } as unknown as string,
+        },
+      ]);
+
+      await adapter.consumeStream(stream);
+
+      const starts = filterByType(events, "stream.tool.start");
+      expect(starts[0]!.data.toolId).toContain(`tool_${AGENT_ID}_bash_`);
+    });
+
+    test("sets parentAgentId on tool start events", async () => {
+      const adapter = createAdapter({ parentAgentId: "parent-agent-1" });
+      const stream = mockStream([
+        {
+          type: "tool_use",
+          content: {
+            name: "bash",
+            toolUseId: "t1",
+            input: {},
+          } as unknown as string,
+        },
+      ]);
+
+      await adapter.consumeStream(stream);
+
+      const starts = filterByType(events, "stream.tool.start");
+      expect(starts[0]!.data.parentAgentId).toBe("worker-1");
+    });
+  });
+
+  // --------------------------------------------------------------------------
+  // Token Usage Events
+  // --------------------------------------------------------------------------
+
+  describe("token usage", () => {
+    test("publishes stream.usage from chunk metadata", async () => {
+      const adapter = createAdapter();
+      const stream = mockStream([
+        {
+          type: "text",
+          content: "hello",
+          metadata: {
+            tokenUsage: { inputTokens: 100, outputTokens: 50 },
+            model: "claude-sonnet-4-5-20250514",
+          },
+        },
+      ]);
+
+      await adapter.consumeStream(stream);
+
+      const usages = filterByType(events, "stream.usage");
+      expect(usages).toHaveLength(1);
+      expect(usages[0]!.data.inputTokens).toBe(100);
+      expect(usages[0]!.data.outputTokens).toBe(50);
+      expect(usages[0]!.data.model).toBe("claude-sonnet-4-5-20250514");
+    });
+
+    test("accumulates token usage across chunks", async () => {
+      const adapter = createAdapter();
+      const stream = mockStream([
+        {
+          type: "text",
+          content: "a",
+          metadata: {
+            tokenUsage: { inputTokens: 100, outputTokens: 50 },
+          },
+        },
+        {
+          type: "text",
+          content: "b",
+          metadata: {
+            tokenUsage: { inputTokens: 200, outputTokens: 75 },
+          },
+        },
+      ]);
+
+      const result = await adapter.consumeStream(stream);
+
+      expect(result.tokenUsage).toEqual({
+        inputTokens: 300,
+        outputTokens: 125,
+      });
+
+      const usages = filterByType(events, "stream.usage");
+      expect(usages).toHaveLength(2);
+      // Second event should have accumulated totals
+      expect(usages[1]!.data.inputTokens).toBe(300);
+      expect(usages[1]!.data.outputTokens).toBe(125);
+    });
+
+    test("ignores zero token usage", async () => {
+      const adapter = createAdapter();
+      const stream = mockStream([
+        {
+          type: "text",
+          content: "hello",
+          metadata: {
+            tokenUsage: { inputTokens: 0, outputTokens: 0 },
+          },
+        },
+      ]);
+
+      await adapter.consumeStream(stream);
+
+      const usages = filterByType(events, "stream.usage");
+      expect(usages).toHaveLength(0);
+    });
+
+    test("includes tokenUsage in result when present", async () => {
+      const adapter = createAdapter();
+      const stream = mockStream([
+        {
+          type: "text",
+          content: "hi",
+          metadata: {
+            tokenUsage: { inputTokens: 50, outputTokens: 25 },
+          },
+        },
+      ]);
+
+      const result = await adapter.consumeStream(stream);
+
+      expect(result.tokenUsage).toBeDefined();
+      expect(result.tokenUsage!.inputTokens).toBe(50);
+    });
+
+    test("omits tokenUsage from result when no tokens used", async () => {
+      const adapter = createAdapter();
+      const stream = mockStream([{ type: "text", content: "hi" }]);
+
+      const result = await adapter.consumeStream(stream);
+
+      expect(result.tokenUsage).toBeUndefined();
+    });
+  });
+
+  // --------------------------------------------------------------------------
+  // Abort Handling
+  // --------------------------------------------------------------------------
+
+  describe("abort handling", () => {
+    test("stops consuming stream when abort signal fires", async () => {
+      const abortController = new AbortController();
+      const adapter = createAdapter();
+
+      // Create a stream that yields chunks with a delay
+      async function* slowStream(): AsyncGenerator<AgentMessage> {
+        yield { type: "text", content: "first " };
+        abortController.abort();
+        yield { type: "text", content: "second " };
+        yield { type: "text", content: "third" };
+      }
+
+      const result = await adapter.consumeStream(
+        slowStream(),
+        abortController.signal,
+      );
+
+      expect(result.success).toBe(false);
+      expect(result.error).toBe("Sub-agent was aborted");
+      // Should have at least the first chunk
+      expect(result.output).toContain("first");
+    });
+
+    test("publishes stream.text.complete on abort", async () => {
+      const abortController = new AbortController();
+      abortController.abort(); // pre-abort
+
+      const adapter = createAdapter();
+      const stream = mockStream([{ type: "text", content: "test" }]);
+
+      await adapter.consumeStream(stream, abortController.signal);
+
+      const completes = filterByType(events, "stream.text.complete");
+      expect(completes).toHaveLength(1);
+    });
+  });
+
+  // --------------------------------------------------------------------------
+  // Error Handling
+  // --------------------------------------------------------------------------
+
+  describe("error handling", () => {
+    test("catches stream errors and returns failure result", async () => {
+      const adapter = createAdapter();
+      const stream = errorStream(
+        [{ type: "text", content: "partial " }],
+        new Error("Stream broke"),
+      );
+
+      const result = await adapter.consumeStream(stream);
+
+      expect(result.success).toBe(false);
+      expect(result.error).toBe("Stream broke");
+      expect(result.output).toBe("partial ");
+    });
+
+    test("publishes stream.session.error on stream error", async () => {
+      const adapter = createAdapter();
+      const stream = errorStream([], new Error("Connection lost"));
+
+      await adapter.consumeStream(stream);
+
+      const errors = filterByType(events, "stream.session.error");
+      expect(errors).toHaveLength(1);
+      expect(errors[0]!.data.error).toBe("Connection lost");
+    });
+
+    test("publishes stream.text.complete after error", async () => {
+      const adapter = createAdapter();
+      const stream = errorStream(
+        [{ type: "text", content: "some text" }],
+        new Error("fail"),
+      );
+
+      await adapter.consumeStream(stream);
+
+      const completes = filterByType(events, "stream.text.complete");
+      expect(completes).toHaveLength(1);
+      expect(completes[0]!.data.fullText).toBe("some text");
+    });
+
+    test("handles non-Error thrown values", async () => {
+      const adapter = createAdapter();
+
+      async function* throwingStream(): AsyncGenerator<AgentMessage> {
+        throw "string error";
+      }
+
+      const result = await adapter.consumeStream(throwingStream());
+
+      expect(result.success).toBe(false);
+      expect(result.error).toBe("string error");
+    });
+  });
+
+  // --------------------------------------------------------------------------
+  // Result Metadata
+  // --------------------------------------------------------------------------
+
+  describe("result metadata", () => {
+    test("includes durationMs in result", async () => {
+      const adapter = createAdapter();
+      const stream = mockStream([{ type: "text", content: "hi" }]);
+
+      const result = await adapter.consumeStream(stream);
+
+      expect(result.durationMs).toBeGreaterThanOrEqual(0);
+    });
+
+    test("omits thinkingDurationMs when no thinking occurred", async () => {
+      const adapter = createAdapter();
+      const stream = mockStream([{ type: "text", content: "hi" }]);
+
+      const result = await adapter.consumeStream(stream);
+
+      expect(result.thinkingDurationMs).toBeUndefined();
+    });
+
+    test("omits toolDetails when no tools used", async () => {
+      const adapter = createAdapter();
+      const stream = mockStream([{ type: "text", content: "hi" }]);
+
+      const result = await adapter.consumeStream(stream);
+
+      expect(result.toolDetails).toBeUndefined();
+    });
+
+    test("returns empty string output when no text chunks", async () => {
+      const adapter = createAdapter();
+      const stream = mockStream([]);
+
+      const result = await adapter.consumeStream(stream);
+
+      expect(result.output).toBe("");
+      expect(result.success).toBe(true);
+    });
+  });
+
+  // --------------------------------------------------------------------------
+  // Event Envelope
+  // --------------------------------------------------------------------------
+
+  describe("event envelope", () => {
+    test("all events use parent sessionId", async () => {
+      const adapter = createAdapter();
+      const stream = mockStream([
+        { type: "text", content: "hi" },
+        {
+          type: "tool_use",
+          content: {
+            name: "bash",
+            toolUseId: "t1",
+            input: {},
+          } as unknown as string,
+        },
+      ]);
+
+      await adapter.consumeStream(stream);
+
+      for (const event of events) {
+        expect(event.sessionId).toBe(SESSION_ID);
+      }
+    });
+
+    test("all events use correct runId", async () => {
+      const adapter = createAdapter();
+      const stream = mockStream([{ type: "text", content: "hi" }]);
+
+      await adapter.consumeStream(stream);
+
+      for (const event of events) {
+        expect(event.runId).toBe(RUN_ID);
+      }
+    });
+
+    test("all events have timestamps", async () => {
+      const adapter = createAdapter();
+      const stream = mockStream([{ type: "text", content: "hi" }]);
+
+      await adapter.consumeStream(stream);
+
+      for (const event of events) {
+        expect(event.timestamp).toBeGreaterThan(0);
+      }
+    });
+  });
+
+  // --------------------------------------------------------------------------
+  // Multiple Consumptions
+  // --------------------------------------------------------------------------
+
+  describe("reuse", () => {
+    test("resets state between consumeStream calls", async () => {
+      const adapter = createAdapter();
+
+      const stream1 = mockStream([{ type: "text", content: "first" }]);
+      const result1 = await adapter.consumeStream(stream1);
+      expect(result1.output).toBe("first");
+
+      const stream2 = mockStream([{ type: "text", content: "second" }]);
+      const result2 = await adapter.consumeStream(stream2);
+      expect(result2.output).toBe("second");
+      // Should not accumulate from previous call
+      expect(result2.output).not.toContain("first");
+    });
+  });
+
+  // --------------------------------------------------------------------------
+  // SubagentToolTracker Integration
+  // --------------------------------------------------------------------------
+
+  describe("tool tracker integration (stream.agent.update)", () => {
+    test("publishes stream.agent.update on tool_use with tool name and count", async () => {
+      const adapter = createAdapter();
+      const stream = mockStream([
+        {
+          type: "tool_use",
+          content: { name: "grep", toolUseId: "t1", input: {} } as unknown as string,
+        },
+      ]);
+
+      await adapter.consumeStream(stream);
+
+      const updates = filterByType(events, "stream.agent.update");
+      expect(updates.length).toBeGreaterThanOrEqual(1);
+      // First update should be from tool start
+      const startUpdate = updates[0]!;
+      expect(startUpdate.data.agentId).toBe(AGENT_ID);
+      expect(startUpdate.data.currentTool).toBe("grep");
+      expect(startUpdate.data.toolUses).toBe(1);
+    });
+
+    test("publishes stream.agent.update on tool_result clearing current tool", async () => {
+      const adapter = createAdapter();
+      const stream = mockStream([
+        {
+          type: "tool_use",
+          content: { name: "grep", toolUseId: "t1", input: {} } as unknown as string,
+        },
+        {
+          type: "tool_result",
+          content: "found it",
+          metadata: { toolId: "t1" },
+        } as unknown as AgentMessage,
+      ]);
+
+      await adapter.consumeStream(stream);
+
+      const updates = filterByType(events, "stream.agent.update");
+      // Should have at least 2 updates: tool start + tool complete
+      expect(updates.length).toBeGreaterThanOrEqual(2);
+      const completeUpdate = updates[updates.length - 1]!;
+      expect(completeUpdate.data.agentId).toBe(AGENT_ID);
+      expect(completeUpdate.data.currentTool).toBeUndefined();
+      expect(completeUpdate.data.toolUses).toBe(1);
+    });
+
+    test("increments tool count across multiple tool invocations", async () => {
+      const adapter = createAdapter();
+      const stream = mockStream([
+        {
+          type: "tool_use",
+          content: { name: "grep", toolUseId: "t1", input: {} } as unknown as string,
+        },
+        {
+          type: "tool_result",
+          content: "result1",
+          metadata: { toolId: "t1" },
+        } as unknown as AgentMessage,
+        {
+          type: "tool_use",
+          content: { name: "view", toolUseId: "t2", input: {} } as unknown as string,
+        },
+      ]);
+
+      await adapter.consumeStream(stream);
+
+      const updates = filterByType(events, "stream.agent.update");
+      // Last start update should show count=2
+      const lastStartUpdate = updates.filter((u) => u.data.currentTool !== undefined).pop()!;
+      expect(lastStartUpdate.data.toolUses).toBe(2);
+      expect(lastStartUpdate.data.currentTool).toBe("view");
+    });
+  });
+
+  // --------------------------------------------------------------------------
+  // parentAgentId uses sub-agent ID (not parent session)
+  // --------------------------------------------------------------------------
+
+  describe("tool event agent attribution", () => {
+    test("tool start parentAgentId is the sub-agent agentId, not the parent session", async () => {
+      const adapter = createAdapter({ parentAgentId: "parent-session-456" });
+      const stream = mockStream([
+        {
+          type: "tool_use",
+          content: { name: "bash", toolUseId: "t1", input: {} } as unknown as string,
+        },
+      ]);
+
+      await adapter.consumeStream(stream);
+
+      const starts = filterByType(events, "stream.tool.start");
+      // Should be the sub-agent's own ID for CorrelationService lookup
+      expect(starts[0]!.data.parentAgentId).toBe(AGENT_ID);
+    });
+  });
+
+  // --------------------------------------------------------------------------
+  // text-complete messageId prefix for sub-agent detection
+  // --------------------------------------------------------------------------
+
+  describe("text-complete sub-agent detection", () => {
+    test("stream.text.complete has messageId prefixed with 'subagent-'", async () => {
+      const adapter = createAdapter();
+      const stream = mockStream([{ type: "text", content: "hello" }]);
+
+      await adapter.consumeStream(stream);
+
+      const completes = filterByType(events, "stream.text.complete");
+      expect(completes.length).toBe(1);
+      expect(completes[0]!.data.messageId).toBe(`subagent-${AGENT_ID}`);
+      expect(completes[0]!.data.messageId.startsWith("subagent-")).toBe(true);
+    });
+  });
+
+  // --------------------------------------------------------------------------
+  // stream.agent.start before tool events (Fix 1A)
+  // --------------------------------------------------------------------------
+
+  describe("agent registration before tool events (Fix 1A)", () => {
+    function createAdapterWithAgentType(overrides?: {
+      parentAgentId?: string;
+      agentType?: string;
+      task?: string;
+      isBackground?: boolean;
+    }): SubagentStreamAdapter {
+      return new SubagentStreamAdapter({
+        bus,
+        sessionId: SESSION_ID,
+        agentId: AGENT_ID,
+        runId: RUN_ID,
+        parentAgentId: overrides?.parentAgentId,
+        agentType: overrides?.agentType,
+        task: overrides?.task,
+        isBackground: overrides?.isBackground,
+      });
+    }
+
+    test("publishes stream.agent.start synchronously in constructor when agentType is provided", () => {
+      // Verify that creating the adapter immediately publishes stream.agent.start
+      // (before consumeStream is ever called)
+      createAdapterWithAgentType({
+        agentType: "explore",
+        task: "Search the codebase",
+      });
+
+      const agentStarts = filterByType(events, "stream.agent.start");
+      expect(agentStarts).toHaveLength(1);
+      expect(agentStarts[0]!.data.agentId).toBe(AGENT_ID);
+      expect(agentStarts[0]!.data.agentType).toBe("explore");
+      expect(agentStarts[0]!.data.task).toBe("Search the codebase");
+    });
+
+    test("publishes stream.agent.start before any tool events", async () => {
+      const adapter = createAdapterWithAgentType({
+        agentType: "explore",
+        task: "Search the codebase",
+      });
+      const stream = mockStream([
+        {
+          type: "tool_use",
+          content: { name: "grep", toolUseId: "t1", input: {} } as unknown as string,
+        },
+      ]);
+
+      await adapter.consumeStream(stream);
+
+      const agentStarts = filterByType(events, "stream.agent.start");
+      const toolStarts = filterByType(events, "stream.tool.start");
+      expect(agentStarts).toHaveLength(1);
+      expect(toolStarts).toHaveLength(1);
+
+      // stream.agent.start must precede stream.tool.start in event ordering
+      const agentStartIdx = events.indexOf(agentStarts[0]!);
+      const toolStartIdx = events.indexOf(toolStarts[0]!);
+      expect(agentStartIdx).toBeLessThan(toolStartIdx);
+    });
+
+    test("stream.agent.start has correct event envelope", async () => {
+      const adapter = createAdapterWithAgentType({
+        agentType: "task",
+        task: "Run tests",
+        isBackground: true,
+      });
+      const stream = mockStream([{ type: "text", content: "hi" }]);
+
+      await adapter.consumeStream(stream);
+
+      const agentStarts = filterByType(events, "stream.agent.start");
+      expect(agentStarts).toHaveLength(1);
+      expect(agentStarts[0]!.data.agentId).toBe(AGENT_ID);
+      expect(agentStarts[0]!.data.agentType).toBe("task");
+      expect(agentStarts[0]!.data.task).toBe("Run tests");
+      expect(agentStarts[0]!.data.isBackground).toBe(true);
+      expect(agentStarts[0]!.sessionId).toBe(SESSION_ID);
+      expect(agentStarts[0]!.runId).toBe(RUN_ID);
+    });
+
+    test("does not publish stream.agent.start when agentType is not provided", async () => {
+      const adapter = createAdapter();
+      const stream = mockStream([{ type: "text", content: "hi" }]);
+
+      await adapter.consumeStream(stream);
+
+      const agentStarts = filterByType(events, "stream.agent.start");
+      expect(agentStarts).toHaveLength(0);
+    });
+
+    test("uses agentType as fallback task when task is not provided", () => {
+      createAdapterWithAgentType({
+        agentType: "explore",
+      });
+
+      const agentStarts = filterByType(events, "stream.agent.start");
+      expect(agentStarts).toHaveLength(1);
+      expect(agentStarts[0]!.data.task).toBe("explore");
+    });
+
+    test("defaults isBackground to false", () => {
+      createAdapterWithAgentType({
+        agentType: "explore",
+      });
+
+      const agentStarts = filterByType(events, "stream.agent.start");
+      expect(agentStarts[0]!.data.isBackground).toBe(false);
+    });
+
+    test("idempotent guard prevents duplicate on first consumeStream call", async () => {
+      const adapter = createAdapterWithAgentType({
+        agentType: "task",
+        task: "Build project",
+      });
+
+      // Constructor already published 1 event
+      expect(filterByType(events, "stream.agent.start")).toHaveLength(1);
+
+      // consumeStream should NOT publish a second one (idempotent guard)
+      await adapter.consumeStream(mockStream([{ type: "text", content: "done" }]));
+
+      expect(filterByType(events, "stream.agent.start")).toHaveLength(1);
+    });
+
+    test("re-publishes stream.agent.start on adapter reuse (multiple consumeStream calls)", async () => {
+      const adapter = createAdapterWithAgentType({
+        agentType: "task",
+        task: "Build project",
+      });
+
+      // Constructor: 1 event
+      await adapter.consumeStream(mockStream([{ type: "text", content: "first" }]));
+      // buildResult clears flag, so next consumeStream re-publishes
+      await adapter.consumeStream(mockStream([{ type: "text", content: "second" }]));
+
+      const agentStarts = filterByType(events, "stream.agent.start");
+      // 1 from constructor + 1 from second consumeStream (first was no-op)
+      expect(agentStarts).toHaveLength(2);
+    });
+  });
+});
diff --git a/src/events/adapters/subagent-adapter.ts b/src/events/adapters/subagent-adapter.ts
new file mode 100644
index 0000000000..715dc12061
--- /dev/null
+++ b/src/events/adapters/subagent-adapter.ts
@@ -0,0 +1,623 @@
+/**
+ * Sub-Agent Stream Adapter
+ *
+ * Lightweight adapter that bridges a sub-agent's SDK session stream to the
+ * shared event bus. Unlike the main SDK adapters (which handle full session
+ * lifecycle), this adapter is scoped to a single sub-agent execution.
+ *
+ * Each sub-agent session gets its own adapter instance. The adapter:
+ * - Iterates the SDK AsyncIterable stream
+ * - Maps AgentMessage types to normalized BusEvents
+ * - Publishes events with the PARENT session's sessionId
+ * - Tracks agentId in event data for CorrelationService attribution
+ * - Accumulates full text output, token usage, thinking duration, tool details
+ * - Returns a SubagentStreamResult on completion
+ *
+ * Event mapping:
+ * - AgentMessage (type: "text")        -> stream.text.delta
+ * - AgentMessage (type: "thinking")    -> stream.thinking.delta
+ * - AgentMessage (type: "tool_use")    -> stream.tool.start
+ * - AgentMessage (type: "tool_result") -> stream.tool.complete
+ * - stream completion                  -> stream.text.complete
+ */
+
+import type { EventBus } from "../event-bus.ts";
+import type { BusEvent } from "../bus-events.ts";
+import type { AgentMessage } from "../../sdk/types.ts";
+import type {
+  SubagentStreamResult,
+  SubagentToolDetail,
+} from "../../workflows/graph/types.ts";
+import { SubagentToolTracker } from "./subagent-tool-tracker.ts";
+
+/**
+ * Options for creating a SubagentStreamAdapter.
+ */
+export interface SubagentStreamAdapterOptions {
+  /** The event bus to publish events to */
+  bus: EventBus;
+  /** Parent session ID — events are published with this sessionId */
+  sessionId: string;
+  /** Sub-agent ID for correlation and attribution */
+  agentId: string;
+  /** Parent agent ID (for nested agents) */
+  parentAgentId?: string;
+  /** Workflow run ID for staleness detection (monotonically increasing) */
+  runId: number;
+  /** Agent type (e.g., "explore", "task"). When provided, adapter publishes stream.agent.start synchronously in the constructor */
+  agentType?: string;
+  /** Task description given to the agent */
+  task?: string;
+  /** Whether the agent is running in background mode */
+  isBackground?: boolean;
+}
+
+/**
+ * Stream adapter for sub-agent SDK sessions.
+ *
+ * Consumes an AsyncIterable<AgentMessage> stream from any SDK session and
+ * publishes normalized BusEvents to the shared event bus. Returns a
+ * SubagentStreamResult containing full streaming metadata.
+ */
+export class SubagentStreamAdapter {
+  private readonly bus: EventBus;
+  private readonly sessionId: string;
+  private readonly agentId: string;
+  private readonly parentAgentId: string | undefined;
+  private readonly runId: number;
+  private readonly agentType: string | undefined;
+  private readonly task: string | undefined;
+  private readonly isBackground: boolean;
+  private readonly toolTracker: SubagentToolTracker;
+
+  /** Accumulated text output from the sub-agent */
+  private textAccumulator = "";
+  /** Number of tool invocations */
+  private toolUseCount = 0;
+  /** Token usage tracking */
+  private tokenUsage: { inputTokens: number; outputTokens: number } = {
+    inputTokens: 0,
+    outputTokens: 0,
+  };
+  /** Total thinking duration in milliseconds */
+  private thinkingDurationMs = 0;
+  /** Tracks thinking source start times for duration computation */
+  private thinkingStartTimes = new Map<string, number>();
+  /** Per-tool invocation details */
+  private toolDetails: SubagentToolDetail[] = [];
+  /** Maps toolId -> start time for duration computation */
+  private toolStartTimes = new Map<string, number>();
+  /** Maps toolId -> toolName for correlation on completion */
+  private toolNames = new Map<string, string>();
+  /** Counter for generating synthetic tool IDs */
+  private syntheticToolCounter = 0;
+  /** Monotonic message ID derived from agentId */
+  private readonly messageId: string;
+  /** Guard flag for idempotent stream.agent.start publishing (Fix 1A) */
+  private agentStartPublished = false;
+
+  constructor(options: SubagentStreamAdapterOptions) {
+    this.bus = options.bus;
+    this.sessionId = options.sessionId;
+    this.agentId = options.agentId;
+    this.parentAgentId = options.parentAgentId;
+    this.runId = options.runId;
+    this.agentType = options.agentType;
+    this.task = options.task;
+    this.isBackground = options.isBackground ?? false;
+    this.messageId = `subagent-${options.agentId}`;
+    this.toolTracker = new SubagentToolTracker(options.bus, options.sessionId, options.runId);
+    this.toolTracker.registerAgent(options.agentId);
+
+    // Fix 1A: Publish stream.agent.start synchronously in the constructor so
+    // that by the time any tool events arrive, the agent is already registered
+    // on the bus. The executor may also publish stream.agent.start via its own
+    // WorkflowEventAdapter — the idempotent guard in publishAgentStart()
+    // prevents this adapter from emitting a duplicate within the same lifecycle.
+    this.publishAgentStart();
+  }
+
+  /**
+   * Consume an SDK session stream, publishing normalized events to the bus.
+   *
+   * For each AgentMessage in the stream:
+   * - text        -> stream.text.delta (accumulates full text)
+   * - thinking    -> stream.thinking.delta (tracks thinking duration)
+   * - tool_use    -> stream.tool.start (increments toolUses)
+   * - tool_result -> stream.tool.complete (records tool detail)
+   *
+   * On completion, publishes stream.text.complete and returns SubagentStreamResult.
+   *
+   * @param stream - AsyncIterable of AgentMessage from an SDK session
+   * @param abortSignal - Optional signal to cancel stream consumption
+   * @returns SubagentStreamResult with full streaming metadata
+   */
+  async consumeStream(
+    stream: AsyncIterable<AgentMessage>,
+    abortSignal?: AbortSignal,
+  ): Promise<SubagentStreamResult> {
+    const startTime = Date.now();
+
+    this.reset();
+
+    // Fix 1A: Re-publish stream.agent.start after reset for adapter reuse.
+    // On first consumeStream() call this is a no-op (constructor already published).
+    // On subsequent calls the flag was cleared by buildResult(), allowing re-publish.
+    this.publishAgentStart();
+
+    try {
+      for await (const chunk of stream) {
+        if (abortSignal?.aborted) {
+          break;
+        }
+
+        this.processChunk(chunk);
+      }
+
+      // Finalize any open thinking blocks
+      this.finalizeThinking();
+
+      // Publish stream completion
+      if (abortSignal?.aborted) {
+        this.publishTextComplete();
+        return this.buildResult(startTime, false, "Sub-agent was aborted");
+      }
+
+      this.publishTextComplete();
+      return this.buildResult(startTime, true);
+    } catch (error) {
+      // Finalize any open thinking blocks before returning
+      this.finalizeThinking();
+
+      const errorMessage =
+        error instanceof Error ? error.message : String(error);
+
+      // Publish error event
+      this.publishSessionError(errorMessage);
+
+      // Publish text complete with whatever was accumulated
+      this.publishTextComplete();
+
+      return this.buildResult(startTime, false, errorMessage);
+    }
+  }
+
+  /**
+   * Process a single chunk from the SDK stream.
+   */
+  private processChunk(chunk: AgentMessage): void {
+    switch (chunk.type) {
+      case "text":
+        this.handleText(chunk);
+        break;
+      case "thinking":
+        this.handleThinking(chunk);
+        break;
+      case "tool_use":
+        this.handleToolUse(chunk);
+        break;
+      case "tool_result":
+        this.handleToolResult(chunk);
+        break;
+    }
+
+    // Handle token usage from chunk metadata
+    this.handleUsage(chunk);
+  }
+
+  /**
+   * Handle a text delta chunk.
+   */
+  private handleText(chunk: AgentMessage): void {
+    if (typeof chunk.content !== "string") return;
+
+    const delta = chunk.content;
+    this.textAccumulator += delta;
+
+    const event: BusEvent<"stream.text.delta"> = {
+      type: "stream.text.delta",
+      sessionId: this.sessionId,
+      runId: this.runId,
+      timestamp: Date.now(),
+      data: {
+        delta,
+        messageId: this.messageId,
+        agentId: this.agentId,
+      },
+    };
+
+    this.bus.publish(event);
+  }
+
+  /**
+   * Handle a thinking delta or thinking complete chunk.
+   */
+  private handleThinking(chunk: AgentMessage): void {
+    const metadata = chunk.metadata;
+    const thinkingSourceKey =
+      (metadata?.thinkingSourceKey as string | undefined) ?? "default";
+
+    // Thinking delta (has content)
+    if (typeof chunk.content === "string" && chunk.content.length > 0) {
+      // Track start time for this thinking source
+      if (!this.thinkingStartTimes.has(thinkingSourceKey)) {
+        this.thinkingStartTimes.set(thinkingSourceKey, Date.now());
+      }
+
+      const event: BusEvent<"stream.thinking.delta"> = {
+        type: "stream.thinking.delta",
+        sessionId: this.sessionId,
+        runId: this.runId,
+        timestamp: Date.now(),
+        data: {
+          delta: chunk.content,
+          sourceKey: thinkingSourceKey,
+          messageId: this.messageId,
+          agentId: this.agentId,
+        },
+      };
+
+      this.bus.publish(event);
+    }
+
+    // Thinking complete (has streamingStats with thinkingMs, empty content)
+    const streamingStats = metadata?.streamingStats as
+      | { thinkingMs?: number; outputTokens?: number }
+      | undefined;
+    if (streamingStats?.thinkingMs !== undefined && chunk.content === "") {
+      const startTime = this.thinkingStartTimes.get(thinkingSourceKey);
+      const durationMs =
+        streamingStats.thinkingMs ?? (startTime ? Date.now() - startTime : 0);
+      this.thinkingStartTimes.delete(thinkingSourceKey);
+      this.thinkingDurationMs += durationMs;
+
+      const event: BusEvent<"stream.thinking.complete"> = {
+        type: "stream.thinking.complete",
+        sessionId: this.sessionId,
+        runId: this.runId,
+        timestamp: Date.now(),
+        data: {
+          sourceKey: thinkingSourceKey,
+          durationMs,
+          agentId: this.agentId,
+        },
+      };
+
+      this.bus.publish(event);
+    }
+  }
+
+  /**
+   * Handle a tool_use chunk (tool invocation started).
+   */
+  private handleToolUse(chunk: AgentMessage): void {
+    this.toolUseCount++;
+
+    const chunkRecord = chunk as unknown as Record<string, unknown>;
+    const contentRecord = this.asRecord(chunkRecord.content) ?? {};
+    const metadataRecord = this.asRecord(chunk.metadata) ?? {};
+
+    const toolName = this.normalizeToolName(
+      contentRecord.name ?? chunkRecord.name ?? metadataRecord.toolName,
+    );
+    const explicitToolId = this.asString(
+      contentRecord.toolUseId ??
+        contentRecord.toolUseID ??
+        contentRecord.id ??
+        chunkRecord.toolUseId ??
+        chunkRecord.toolUseID ??
+        chunkRecord.id ??
+        metadataRecord.toolId ??
+        metadataRecord.toolUseId ??
+        metadataRecord.toolUseID ??
+        metadataRecord.toolCallId,
+    );
+    const toolInput =
+      this.asRecord(contentRecord.input ?? chunkRecord.input) ?? {};
+    const toolId = explicitToolId ?? this.createSyntheticToolId(toolName);
+
+    // Track for duration computation and correlation
+    this.toolStartTimes.set(toolId, Date.now());
+    this.toolNames.set(toolId, toolName);
+
+    // Publish stream.agent.update with tool count and current tool
+    this.toolTracker.onToolStart(this.agentId, toolName);
+
+    const event: BusEvent<"stream.tool.start"> = {
+      type: "stream.tool.start",
+      sessionId: this.sessionId,
+      runId: this.runId,
+      timestamp: Date.now(),
+      data: {
+        toolId,
+        toolName,
+        toolInput,
+        sdkCorrelationId: explicitToolId ?? toolId,
+        parentAgentId: this.agentId,
+      },
+    };
+
+    this.bus.publish(event);
+  }
+
+  /**
+   * Handle a tool_result chunk (tool invocation completed).
+   */
+  private handleToolResult(chunk: AgentMessage): void {
+    const chunkRecord = chunk as unknown as Record<string, unknown>;
+    const content = chunkRecord.content;
+    const metadataRecord = this.asRecord(chunk.metadata) ?? {};
+
+    const toolName = this.normalizeToolName(
+      chunkRecord.toolName ?? metadataRecord.toolName,
+    );
+    const explicitToolId = this.asString(
+      chunkRecord.tool_use_id ??
+        chunkRecord.toolUseId ??
+        chunkRecord.toolUseID ??
+        metadataRecord.toolId ??
+        metadataRecord.toolUseId ??
+        metadataRecord.toolUseID ??
+        metadataRecord.toolCallId,
+    );
+
+    // Resolve toolId: use explicit ID, or fall back to matching by name
+    const toolId = explicitToolId ?? this.resolveToolCompleteId(toolName);
+
+    const contentRecord = this.asRecord(content);
+    const isError =
+      chunkRecord.is_error === true ||
+      (typeof content === "object" && content !== null && "error" in content);
+    const errorValue = contentRecord?.error;
+
+    // Compute tool duration
+    const startTime = this.toolStartTimes.get(toolId);
+    const durationMs = startTime ? Date.now() - startTime : 0;
+    this.toolStartTimes.delete(toolId);
+
+    // Record tool detail
+    const resolvedToolName = this.toolNames.get(toolId) ?? toolName;
+    this.toolNames.delete(toolId);
+
+    this.toolDetails.push({
+      toolId,
+      toolName: resolvedToolName,
+      durationMs,
+      success: !isError,
+    });
+
+    // Publish stream.agent.update clearing current tool
+    this.toolTracker.onToolComplete(this.agentId);
+
+    const event: BusEvent<"stream.tool.complete"> = {
+      type: "stream.tool.complete",
+      sessionId: this.sessionId,
+      runId: this.runId,
+      timestamp: Date.now(),
+      data: {
+        toolId,
+        toolName: resolvedToolName,
+        toolResult: content,
+        success: !isError,
+        error: isError
+          ? typeof errorValue === "string"
+            ? errorValue
+            : String(content)
+          : undefined,
+        sdkCorrelationId: explicitToolId ?? toolId,
+        parentAgentId: this.agentId,
+      },
+    };
+
+    this.bus.publish(event);
+  }
+
+  /**
+   * Handle token usage from chunk metadata.
+   */
+  private handleUsage(chunk: AgentMessage): void {
+    const tokenUsage = chunk.metadata?.tokenUsage as
+      | { inputTokens?: number; outputTokens?: number }
+      | undefined;
+    if (!tokenUsage) return;
+
+    const inputTokens = tokenUsage.inputTokens ?? 0;
+    const outputTokens = tokenUsage.outputTokens ?? 0;
+
+    if (inputTokens <= 0 && outputTokens <= 0) return;
+
+    this.tokenUsage.inputTokens += inputTokens;
+    this.tokenUsage.outputTokens += outputTokens;
+
+    const event: BusEvent<"stream.usage"> = {
+      type: "stream.usage",
+      sessionId: this.sessionId,
+      runId: this.runId,
+      timestamp: Date.now(),
+      data: {
+        inputTokens: this.tokenUsage.inputTokens,
+        outputTokens: this.tokenUsage.outputTokens,
+        model: chunk.metadata?.model as string | undefined,
+        agentId: this.agentId,
+      },
+    };
+
+    this.bus.publish(event);
+  }
+
+  /**
+   * Publish a stream.text.complete event.
+   */
+  private publishTextComplete(): void {
+    const event: BusEvent<"stream.text.complete"> = {
+      type: "stream.text.complete",
+      sessionId: this.sessionId,
+      runId: this.runId,
+      timestamp: Date.now(),
+      data: {
+        messageId: this.messageId,
+        fullText: this.textAccumulator,
+      },
+    };
+
+    this.bus.publish(event);
+  }
+
+  /**
+   * Publish a stream.session.error event.
+   */
+  private publishSessionError(errorMessage: string): void {
+    const event: BusEvent<"stream.session.error"> = {
+      type: "stream.session.error",
+      sessionId: this.sessionId,
+      runId: this.runId,
+      timestamp: Date.now(),
+      data: {
+        error: errorMessage,
+      },
+    };
+
+    this.bus.publish(event);
+  }
+
+  /**
+   * Publish a stream.agent.start event if agentType was provided.
+   *
+   * Called synchronously in the constructor to ensure the agent is registered
+   * on the bus before any tool events can fire (Fix 1A). Also called in
+   * consumeStream() for adapter reuse — the idempotent guard prevents
+   * duplicate events within a single stream lifecycle.
+   *
+   * Note: The executor may also publish stream.agent.start via its own
+   * WorkflowEventAdapter for the same agentId. This adapter's guard only
+   * prevents its own duplicates; the executor's publish is a separate concern.
+   */
+  private publishAgentStart(): void {
+    if (!this.agentType) return;
+    if (this.agentStartPublished) return; // Idempotent guard (Fix 1A)
+    this.agentStartPublished = true;
+
+    const event: BusEvent<"stream.agent.start"> = {
+      type: "stream.agent.start",
+      sessionId: this.sessionId,
+      runId: this.runId,
+      timestamp: Date.now(),
+      data: {
+        agentId: this.agentId,
+        toolCallId: this.agentId,
+        agentType: this.agentType,
+        task: this.task ?? this.agentType,
+        isBackground: this.isBackground,
+      },
+    };
+
+    this.bus.publish(event);
+  }
+
+  /**
+   * Finalize any open thinking blocks by computing their duration
+   * and accumulating into thinkingDurationMs.
+   */
+  private finalizeThinking(): void {
+    const now = Date.now();
+    for (const [, startTime] of this.thinkingStartTimes) {
+      this.thinkingDurationMs += now - startTime;
+    }
+    this.thinkingStartTimes.clear();
+  }
+
+  /**
+   * Build the SubagentStreamResult from accumulated state.
+   */
+  private buildResult(
+    startTime: number,
+    success: boolean,
+    error?: string,
+  ): SubagentStreamResult {
+    const result: SubagentStreamResult = {
+      agentId: this.agentId,
+      success,
+      output: this.textAccumulator,
+      toolUses: this.toolUseCount,
+      durationMs: Date.now() - startTime,
+    };
+
+    if (error) {
+      result.error = error;
+    }
+
+    if (this.tokenUsage.inputTokens > 0 || this.tokenUsage.outputTokens > 0) {
+      result.tokenUsage = { ...this.tokenUsage };
+    }
+
+    if (this.thinkingDurationMs > 0) {
+      result.thinkingDurationMs = this.thinkingDurationMs;
+    }
+
+    if (this.toolDetails.length > 0) {
+      result.toolDetails = [...this.toolDetails];
+    }
+
+    // Clear idempotent guard so adapter reuse can re-publish stream.agent.start
+    this.agentStartPublished = false;
+
+    return result;
+  }
+
+  /**
+   * Reset internal accumulation state for a fresh stream.
+   */
+  private reset(): void {
+    this.textAccumulator = "";
+    this.toolUseCount = 0;
+    this.tokenUsage = { inputTokens: 0, outputTokens: 0 };
+    this.thinkingDurationMs = 0;
+    this.thinkingStartTimes.clear();
+    this.toolDetails = [];
+    this.toolStartTimes.clear();
+    this.toolNames.clear();
+    this.syntheticToolCounter = 0;
+    this.toolTracker.removeAgent(this.agentId);
+    this.toolTracker.registerAgent(this.agentId);
+  }
+
+  // ---- Utility helpers (same patterns as ClaudeStreamAdapter) ----
+
+  private asRecord(value: unknown): Record<string, unknown> | undefined {
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+      return value as Record<string, unknown>;
+    }
+    return undefined;
+  }
+
+  private asString(value: unknown): string | undefined {
+    return typeof value === "string" && value.trim().length > 0
+      ? value
+      : undefined;
+  }
+
+  private normalizeToolName(value: unknown): string {
+    return this.asString(value) ?? "unknown";
+  }
+
+  private createSyntheticToolId(toolName: string): string {
+    this.syntheticToolCounter += 1;
+    const normalizedName = toolName.replace(/[^a-zA-Z0-9_-]/g, "_");
+    return `tool_${this.agentId}_${normalizedName}_${this.syntheticToolCounter}`;
+  }
+
+  /**
+   * Resolve tool ID for a tool_result when no explicit ID is provided.
+   * Falls back to the first tracked tool with a matching name.
+   */
+  private resolveToolCompleteId(toolName: string): string {
+    // Find the first tracked tool start with this name
+    for (const [toolId, name] of this.toolNames) {
+      if (name === toolName) {
+        return toolId;
+      }
+    }
+    // No match found — create a synthetic ID
+    return this.createSyntheticToolId(toolName);
+  }
+}
diff --git a/src/events/adapters/subagent-tool-tracker.test.ts b/src/events/adapters/subagent-tool-tracker.test.ts
new file mode 100644
index 0000000000..c59590aab3
--- /dev/null
+++ b/src/events/adapters/subagent-tool-tracker.test.ts
@@ -0,0 +1,162 @@
+/**
+ * Unit tests for SubagentToolTracker
+ *
+ * Tests verify that the tracker correctly:
+ * 1. Registers and tracks sub-agents
+ * 2. Publishes stream.agent.update on tool start/complete
+ * 3. Increments tool counts correctly
+ * 4. Handles unregistered agents gracefully
+ * 5. Cleans up on removeAgent and reset
+ */
+
+import { describe, it, expect, beforeEach } from "bun:test";
+import { EventBus } from "../event-bus.ts";
+import { SubagentToolTracker } from "./subagent-tool-tracker.ts";
+import type { BusEvent, BusEventDataMap } from "../bus-events.ts";
+
+describe("SubagentToolTracker", () => {
+  let bus: EventBus;
+  let tracker: SubagentToolTracker;
+  let publishedEvents: BusEvent<"stream.agent.update">[];
+
+  beforeEach(() => {
+    bus = new EventBus();
+    publishedEvents = [];
+    bus.on("stream.agent.update", (event) => {
+      publishedEvents.push(event);
+    });
+    tracker = new SubagentToolTracker(bus, "session-1", 1);
+  });
+
+  describe("registerAgent", () => {
+    it("should register a new agent", () => {
+      tracker.registerAgent("agent-1");
+      expect(tracker.hasAgent("agent-1")).toBe(true);
+    });
+
+    it("should not overwrite existing agent state on re-register", () => {
+      tracker.registerAgent("agent-1");
+      tracker.onToolStart("agent-1", "bash");
+      tracker.registerAgent("agent-1"); // re-register
+      tracker.onToolStart("agent-1", "read");
+
+      // Should have tool count of 2, not reset to 1
+      expect(publishedEvents).toHaveLength(2);
+      expect(publishedEvents[1]!.data.toolUses).toBe(2);
+    });
+  });
+
+  describe("hasAgent", () => {
+    it("should return false for unregistered agents", () => {
+      expect(tracker.hasAgent("unknown")).toBe(false);
+    });
+
+    it("should return true for registered agents", () => {
+      tracker.registerAgent("agent-1");
+      expect(tracker.hasAgent("agent-1")).toBe(true);
+    });
+  });
+
+  describe("onToolStart", () => {
+    it("should publish stream.agent.update with tool name and count", () => {
+      tracker.registerAgent("agent-1");
+      tracker.onToolStart("agent-1", "bash");
+
+      expect(publishedEvents).toHaveLength(1);
+      const event = publishedEvents[0]!;
+      expect(event.type).toBe("stream.agent.update");
+      expect(event.sessionId).toBe("session-1");
+      expect(event.runId).toBe(1);
+      expect(event.data.agentId).toBe("agent-1");
+      expect(event.data.currentTool).toBe("bash");
+      expect(event.data.toolUses).toBe(1);
+    });
+
+    it("should increment tool count across multiple calls", () => {
+      tracker.registerAgent("agent-1");
+      tracker.onToolStart("agent-1", "bash");
+      tracker.onToolStart("agent-1", "read");
+      tracker.onToolStart("agent-1", "grep");
+
+      expect(publishedEvents).toHaveLength(3);
+      expect(publishedEvents[0]!.data.toolUses).toBe(1);
+      expect(publishedEvents[1]!.data.toolUses).toBe(2);
+      expect(publishedEvents[2]!.data.toolUses).toBe(3);
+      expect(publishedEvents[2]!.data.currentTool).toBe("grep");
+    });
+
+    it("should not publish for unregistered agents", () => {
+      tracker.onToolStart("unknown", "bash");
+      expect(publishedEvents).toHaveLength(0);
+    });
+  });
+
+  describe("onToolComplete", () => {
+    it("should clear currentTool and publish update", () => {
+      tracker.registerAgent("agent-1");
+      tracker.onToolStart("agent-1", "bash");
+      tracker.onToolComplete("agent-1");
+
+      expect(publishedEvents).toHaveLength(2);
+      const completeEvent = publishedEvents[1]!;
+      expect(completeEvent.data.currentTool).toBeUndefined();
+      expect(completeEvent.data.toolUses).toBe(1); // count stays the same
+    });
+
+    it("should not publish for unregistered agents", () => {
+      tracker.onToolComplete("unknown");
+      expect(publishedEvents).toHaveLength(0);
+    });
+  });
+
+  describe("removeAgent", () => {
+    it("should remove agent from tracking", () => {
+      tracker.registerAgent("agent-1");
+      tracker.removeAgent("agent-1");
+      expect(tracker.hasAgent("agent-1")).toBe(false);
+    });
+
+    it("should stop publishing events for removed agent", () => {
+      tracker.registerAgent("agent-1");
+      tracker.removeAgent("agent-1");
+      tracker.onToolStart("agent-1", "bash");
+      expect(publishedEvents).toHaveLength(0);
+    });
+  });
+
+  describe("reset", () => {
+    it("should clear all tracked agents", () => {
+      tracker.registerAgent("agent-1");
+      tracker.registerAgent("agent-2");
+      tracker.reset();
+      expect(tracker.hasAgent("agent-1")).toBe(false);
+      expect(tracker.hasAgent("agent-2")).toBe(false);
+    });
+  });
+
+  describe("multi-agent tracking", () => {
+    it("should track tool counts independently per agent", () => {
+      tracker.registerAgent("agent-1");
+      tracker.registerAgent("agent-2");
+
+      tracker.onToolStart("agent-1", "bash");
+      tracker.onToolStart("agent-2", "read");
+      tracker.onToolStart("agent-1", "write");
+
+      // agent-1 events: 2 tool starts
+      const agent1Events = publishedEvents.filter(
+        (e) => e.data.agentId === "agent-1",
+      );
+      expect(agent1Events).toHaveLength(2);
+      expect(agent1Events[0]!.data.toolUses).toBe(1);
+      expect(agent1Events[1]!.data.toolUses).toBe(2);
+
+      // agent-2 events: 1 tool start
+      const agent2Events = publishedEvents.filter(
+        (e) => e.data.agentId === "agent-2",
+      );
+      expect(agent2Events).toHaveLength(1);
+      expect(agent2Events[0]!.data.toolUses).toBe(1);
+    });
+  });
+});
diff --git a/src/events/adapters/subagent-tool-tracker.ts b/src/events/adapters/subagent-tool-tracker.ts
new file mode 100644
index 0000000000..6a54664ddb
--- /dev/null
+++ b/src/events/adapters/subagent-tool-tracker.ts
@@ -0,0 +1,123 @@
+/**
+ * SubagentToolTracker
+ *
+ * Shared utility used by SDK stream adapters to track sub-agent tool usage
+ * and emit `stream.agent.update` bus events. Each adapter is responsible for
+ * mapping its SDK-specific parent correlation ID to a resolved agentId before
+ * calling the tracker methods.
+ *
+ * Usage:
+ * ```typescript
+ * const tracker = new SubagentToolTracker(bus, sessionId, runId);
+ * tracker.registerAgent("agent-123");
+ * tracker.onToolStart("agent-123", "bash");     // emits stream.agent.update
+ * tracker.onToolComplete("agent-123");           // emits stream.agent.update
+ * tracker.removeAgent("agent-123");
+ * tracker.reset();                               // clear all state
+ * ```
+ */
+
+import type { EventBus } from "../event-bus.ts";
+import type { BusEvent } from "../bus-events.ts";
+
+interface AgentToolState {
+  toolCount: number;
+  currentTool?: string;
+}
+
+export class SubagentToolTracker {
+  private agents = new Map<string, AgentToolState>();
+  private bus: EventBus;
+  private sessionId: string;
+  private runId: number;
+
+  constructor(bus: EventBus, sessionId: string, runId: number) {
+    this.bus = bus;
+    this.sessionId = sessionId;
+    this.runId = runId;
+  }
+
+  /**
+   * Register a new sub-agent for tracking.
+   */
+  registerAgent(agentId: string): void {
+    if (!this.agents.has(agentId)) {
+      this.agents.set(agentId, { toolCount: 0 });
+    }
+  }
+
+  /**
+   * Returns true if the given agentId is registered.
+   */
+  hasAgent(agentId: string): boolean {
+    return this.agents.has(agentId);
+  }
+
+  /**
+   * Record a tool start for a sub-agent. Increments the tool count
+   * and publishes a `stream.agent.update` event.
+   */
+  onToolStart(agentId: string, toolName: string): void {
+    const state = this.agents.get(agentId);
+    if (!state) return;
+
+    state.toolCount += 1;
+    state.currentTool = toolName;
+    this.publishUpdate(agentId, state);
+  }
+
+  /**
+   * Record a tool completion for a sub-agent. Clears the current tool
+   * and publishes a `stream.agent.update` event.
+   */
+  onToolComplete(agentId: string): void {
+    const state = this.agents.get(agentId);
+    if (!state) return;
+
+    state.currentTool = undefined;
+    this.publishUpdate(agentId, state);
+  }
+
+  /**
+   * Record in-flight progress for the current tool without incrementing
+   * the tool count. Useful for streaming partial tool output.
+   */
+  onToolProgress(agentId: string, toolName?: string): void {
+    const state = this.agents.get(agentId);
+    if (!state) return;
+
+    if (toolName) {
+      state.currentTool = toolName;
+    }
+    this.publishUpdate(agentId, state);
+  }
+
+  /**
+   * Remove a sub-agent from tracking (e.g., on completion).
+   */
+  removeAgent(agentId: string): void {
+    this.agents.delete(agentId);
+  }
+
+  /**
+   * Clear all tracked agents and reset state.
+   */
+  reset(): void {
+    this.agents.clear();
+  }
+
+  private publishUpdate(agentId: string, state: AgentToolState): void {
+    const event: BusEvent<"stream.agent.update"> = {
+      type: "stream.agent.update",
+      sessionId: this.sessionId,
+      runId: this.runId,
+      timestamp: Date.now(),
+      data: {
+        agentId,
+        currentTool: state.currentTool,
+        toolUses: state.toolCount,
+      },
+    };
+    this.bus.publish(event);
+  }
+}
diff --git a/src/events/adapters/task-turn-normalization.test.ts b/src/events/adapters/task-turn-normalization.test.ts
new file mode 100644
index 0000000000..b44b0b9c9e
--- /dev/null
+++ b/src/events/adapters/task-turn-normalization.test.ts
@@ -0,0 +1,55 @@
+import { describe, expect, test } from "bun:test";
+import {
+  createTurnMetadataState,
+  normalizeAgentTaskMetadata,
+  normalizeTurnEndMetadata,
+  normalizeTurnStartId,
+  resetTurnMetadataState,
+} from "./task-turn-normalization.ts";
+
+describe("task-turn-normalization", () => {
+  test("normalizes agent task metadata without runtime flag branching", () => {
+    expect(
+      normalizeAgentTaskMetadata({
+        task: "",
+        agentType: "researcher",
+        isBackground: false,
+      }),
+    ).toEqual({
+      task: "researcher",
+      isBackground: false,
+    });
+
+    expect(
+      normalizeAgentTaskMetadata({
+        task: "",
+        agentType: "",
+        isBackground: false,
+      }),
+    ).toEqual({
+      task: "task",
+      isBackground: false,
+    });
+  });
+
+  test("keeps synthetic turn id stable across start/end when ids are missing", () => {
+    const state = createTurnMetadataState();
+    const turnId = normalizeTurnStartId(undefined, state);
+    const end = normalizeTurnEndMetadata({ stop_reason: "tool_use" }, state);
+
+    expect(turnId).toMatch(/^turn_\d+_1$/);
+    expect(end.turnId).toBe(turnId);
+    expect(end.finishReason).toBe("tool-calls");
+    expect(end.rawFinishReason).toBe("tool_use");
+  });
+
+  test("resets turn metadata state", () => {
+    const state = createTurnMetadataState();
+    const first = normalizeTurnStartId(undefined, state);
+    expect(first).toMatch(/^turn_\d+_1$/);
+
+    resetTurnMetadataState(state);
+    const second = normalizeTurnStartId(undefined, state);
+    expect(second).toMatch(/^turn_\d+_1$/);
+  });
+});
diff --git a/src/events/adapters/task-turn-normalization.ts b/src/events/adapters/task-turn-normalization.ts
new file mode 100644
index 0000000000..386e8f130e
--- /dev/null
+++ b/src/events/adapters/task-turn-normalization.ts
@@ -0,0 +1,204 @@
+interface NormalizeAgentTaskMetadataInput {
+  task: unknown;
+  agentType: unknown;
+  isBackground: unknown;
+  toolInput?: unknown;
+}
+
+interface TurnMetadataState {
+  activeTurnId: string | null;
+  syntheticCounter: number;
+}
+
+export type NormalizedTurnFinishReason =
+  | "tool-calls"
+  | "stop"
+  | "max-tokens"
+  | "max-turns"
+  | "error"
+  | "unknown";
+
+export interface NormalizedTurnEndMetadata {
+  turnId: string;
+  finishReason?: NormalizedTurnFinishReason;
+  rawFinishReason?: string;
+}
+
+export interface NormalizedAgentTaskMetadata {
+  task: string;
+  isBackground: boolean;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+    return value as Record<string, unknown>;
+  }
+  return undefined;
+}
+
+function asString(value: unknown): string | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+function normalizeTurnFinishReasonToken(value: string): NormalizedTurnFinishReason {
+  const token = value.trim().toLowerCase().replace(/[\s_]+/g, "-");
+
+  switch (token) {
+    case "tool-calls":
+    case "tool-calls-required":
+    case "tool-call":
+    case "toolcall":
+    case "toolcalls":
+    case "tool-use":
+    case "tool-use-required":
+    case "tool-use-loop":
+    case "tool-use-needed":
+      return "tool-calls";
+    case "stop":
+    case "end-turn":
+    case "completed":
+    case "complete":
+    case "success":
+      return "stop";
+    case "max-tokens":
+    case "max-output-tokens":
+    case "length":
+    case "token-limit":
+      return "max-tokens";
+    case "max-turns":
+    case "error-max-turns":
+    case "turn-limit":
+      return "max-turns";
+    case "error":
+    case "failed":
+    case "failure":
+      return "error";
+    default:
+      return "unknown";
+  }
+}
+
+function extractRawTurnFinishReason(value: unknown): string | undefined {
+  const record = asRecord(value);
+  if (!record) {
+    return asString(value);
+  }
+
+  return asString(record.finishReason)
+    ?? asString(record.finish_reason)
+    ?? asString(record.stopReason)
+    ?? asString(record.stop_reason)
+    ?? asString(record.reason)
+    ?? asString(record.subtype);
+}
+
+function normalizeBackgroundFromInput(toolInput: unknown): boolean {
+  const record = asRecord(toolInput);
+  if (!record) {
+    return false;
+  }
+
+  if (record.run_in_background === true) {
+    return true;
+  }
+
+  const mode = asString(record.mode);
+  return mode?.toLowerCase() === "background";
+}
+
+export function normalizeAgentTaskMetadata(
+  input: NormalizeAgentTaskMetadataInput,
+): NormalizedAgentTaskMetadata {
+  const toolInput = asRecord(input.toolInput);
+  const taskFromToolInput = asString(toolInput?.description)
+    ?? asString(toolInput?.prompt)
+    ?? asString(toolInput?.task);
+  const taskFromEvent = asString(input.task);
+  const agentType = asString(input.agentType);
+
+  const task = taskFromToolInput
+    ?? taskFromEvent
+    ?? (agentType ?? "task");
+
+  const isBackground = input.isBackground === true || normalizeBackgroundFromInput(toolInput);
+
+  return {
+    task,
+    isBackground,
+  };
+}
+
+function nextSyntheticTurnId(state: TurnMetadataState): string {
+  state.syntheticCounter += 1;
+  return `turn_${Date.now()}_${state.syntheticCounter}`;
+}
+
+export function normalizeTurnStartId(
+  value: unknown,
+  state: TurnMetadataState,
+): string {
+  const turnId = asString(value);
+  if (turnId) {
+    state.activeTurnId = turnId;
+    return turnId;
+  }
+
+  const generated = nextSyntheticTurnId(state);
+  state.activeTurnId = generated;
+  return generated;
+}
+
+export function normalizeTurnEndId(
+  value: unknown,
+  state: TurnMetadataState,
+): string {
+  const turnId = asString(value);
+  if (turnId) {
+    if (state.activeTurnId === turnId) {
+      state.activeTurnId = null;
+    }
+    return turnId;
+  }
+
+  if (state.activeTurnId) {
+    const activeTurnId = state.activeTurnId;
+    state.activeTurnId = null;
+    return activeTurnId;
+  }
+
+  return nextSyntheticTurnId(state);
+}
+
+export function normalizeTurnEndMetadata(
+  value: unknown,
+  state: TurnMetadataState,
+): NormalizedTurnEndMetadata {
+  const turnId = normalizeTurnEndId(value, state);
+  const rawFinishReason = extractRawTurnFinishReason(value);
+
+  if (!rawFinishReason) {
+    return { turnId };
+  }
+
+  return {
+    turnId,
+    finishReason: normalizeTurnFinishReasonToken(rawFinishReason),
+    rawFinishReason,
+  };
+}
+
+export function createTurnMetadataState(): TurnMetadataState {
+  return {
+    activeTurnId: null,
+    syntheticCounter: 0,
+  };
+}
+
+export function resetTurnMetadataState(state: TurnMetadataState): void {
+  state.activeTurnId = null;
+  state.syntheticCounter = 0;
+}
diff --git a/src/events/adapters/types.ts b/src/events/adapters/types.ts
new file mode 100644
index 0000000000..0ba8d7e378
--- /dev/null
+++ b/src/events/adapters/types.ts
@@ -0,0 +1,53 @@
+import type { Session } from "../../sdk/types.ts";
+import type { WorkflowRuntimeFeatureFlagOverrides } from "../../workflows/runtime-contracts.ts";
+
+/**
+ * Interface for SDK stream adapters that consume native SDK streaming APIs
+ * and publish normalized BusEvents to the event bus.
+ *
+ * Each SDK has a different streaming pattern:
+ * - OpenCode: AsyncGenerator from sdk.event.subscribe()
+ * - Claude: AsyncIterable from session.stream()
+ * - Copilot: EventEmitter via session.on() handlers
+ *
+ * Adapters are the SOLE consumers of SDK events — no other code subscribes
+ * to SDK events directly. All events flow through the adapter to the bus.
+ */
+export interface SDKStreamAdapter {
+  /**
+   * Consume the SDK stream and publish all events to the bus.
+   * This is the only path for SDK events into the event bus.
+   *
+   * @param session - Active SDK session to stream from
+   * @param message - User message that initiated the stream
+   * @param options - Additional options for the stream
+   */
+  startStreaming(
+    session: Session,
+    message: string,
+    options: StreamAdapterOptions,
+  ): Promise<void>;
+
+  /**
+   * Clean up any adapter-internal state (unregister SDK event handlers, etc.)
+   */
+  dispose(): void;
+}
+
+/**
+ * Options passed to adapter.startStreaming()
+ */
+export interface StreamAdapterOptions {
+  /** Run ID for staleness detection (monotonically increasing per stream) */
+  runId: number;
+  /** Message ID to associate with text events */
+  messageId: string;
+  /** Optional external abort signal for stream cancellation */
+  abortSignal?: AbortSignal;
+  /** Optional agent name for sub-agent dispatch (used by OpenCode) */
+  agent?: string;
+  /** Known agent names that should be treated as task/agent tools (Copilot SDK) */
+  knownAgentNames?: string[];
+  /** Runtime contract feature-flag overrides (Task #1 scaffolding) */
+  runtimeFeatureFlags?: WorkflowRuntimeFeatureFlagOverrides;
+}
diff --git a/src/events/adapters/workflow-adapter.ts b/src/events/adapters/workflow-adapter.ts
new file mode 100644
index 0000000000..6c7f2cc7f1
--- /dev/null
+++ b/src/events/adapters/workflow-adapter.ts
@@ -0,0 +1,217 @@
+/**
+ * Workflow Event Adapter
+ *
+ * Producer-side adapter that bridges workflow execution events to the event bus.
+ * Unlike SDK adapters (which consume streams), this adapter provides methods that
+ * workflow executors call to publish events.
+ *
+ * Key responsibilities:
+ * - Publish workflow step lifecycle events (start, complete)
+ * - Publish workflow task list updates
+ * - Publish sub-agent lifecycle events (start, update)
+ * - Create properly typed BusEvent instances with metadata
+ *
+ * Usage:
+ * ```typescript
+ * const adapter = new WorkflowEventAdapter(eventBus, sessionId, runId);
+ * adapter.publishStepStart(workflowId, "analyze-code", 1);
+ * adapter.publishStepComplete(workflowId, "analyze-code", 1, { status: "success" });
+ * ```
+ */
+
+import type { EventBus } from "../event-bus.ts";
+import type { BusEvent } from "../bus-events.ts";
+import type { WorkflowRuntimeTask } from "../../workflows/runtime-contracts.ts";
+
+/**
+ * Workflow Event Adapter for publishing workflow execution events to the event bus.
+ *
+ * This is a producer-side adapter — workflows call these methods to publish events
+ * onto the bus, which can then be consumed by UI components and other subscribers.
+ */
+export class WorkflowEventAdapter {
+  private bus: EventBus;
+  private sessionId: string;
+  private runId: number;
+
+  /**
+   * Create a new workflow event adapter.
+   *
+   * @param bus - The event bus to publish events to
+   * @param sessionId - Session ID for this workflow execution
+   * @param runId - Run ID for staleness detection
+   */
+  constructor(bus: EventBus, sessionId: string, runId: number) {
+    this.bus = bus;
+    this.sessionId = sessionId;
+    this.runId = runId;
+  }
+
+  /**
+   * Publish a workflow step start event.
+   *
+   * @param workflowId - Workflow instance ID
+   * @param stepName - Human-readable step/node name
+   * @param nodeId - Node ID within the workflow graph
+   */
+  publishStepStart(workflowId: string, stepName: string, nodeId: string): void {
+    const event: BusEvent<"workflow.step.start"> = {
+      type: "workflow.step.start",
+      sessionId: this.sessionId,
+      runId: this.runId,
+      timestamp: Date.now(),
+      data: {
+        workflowId,
+        nodeId,
+        nodeName: stepName,
+      },
+    };
+
+    this.bus.publish(event);
+  }
+
+  /**
+   * Publish a workflow step complete event.
+   *
+ * @param workflowId - Workflow instance ID
+ * @param stepName - Human-readable step/node name
+ * @param nodeId - Node ID that completed
+ * @param status - Completion status
+ * @param result - Optional result data from the step
+ */
+  publishStepComplete(
+    workflowId: string,
+    stepName: string,
+    nodeId: string,
+    status: "success" | "error" | "skipped" = "success",
+    result?: unknown,
+  ): void {
+    const event: BusEvent<"workflow.step.complete"> = {
+      type: "workflow.step.complete",
+      sessionId: this.sessionId,
+      runId: this.runId,
+      timestamp: Date.now(),
+      data: {
+        workflowId,
+        nodeId,
+        nodeName: stepName,
+        status,
+        result,
+      },
+    };
+
+    this.bus.publish(event);
+  }
+
+  /**
+   * Publish a workflow task list update event.
+   *
+   * @param workflowId - Workflow instance ID
+   * @param tasks - Updated task list with id/title/status and optional dependencies
+   */
+  publishTaskUpdate(
+    workflowId: string,
+    tasks: WorkflowRuntimeTask[],
+  ): void {
+    const event: BusEvent<"workflow.task.update"> = {
+      type: "workflow.task.update",
+      sessionId: this.sessionId,
+      runId: this.runId,
+      timestamp: Date.now(),
+      data: {
+        workflowId,
+        tasks,
+      },
+    };
+
+    this.bus.publish(event);
+  }
+
+  /**
+   * Publish a sub-agent start event.
+   *
+   * @param agentId - Unique agent ID
+   * @param agentType - Type of agent (e.g., "explore", "task", "general-purpose")
+   * @param task - Task description given to the agent
+   * @param isBackground - Whether the agent is running in background mode
+   */
+  publishAgentStart(
+    agentId: string,
+    agentType: string,
+    task: string,
+    isBackground: boolean = false,
+  ): void {
+    const event: BusEvent<"stream.agent.start"> = {
+      type: "stream.agent.start",
+      sessionId: this.sessionId,
+      runId: this.runId,
+      timestamp: Date.now(),
+      data: {
+        agentId,
+        toolCallId: agentId,
+        agentType,
+        task,
+        isBackground,
+      },
+    };
+
+    this.bus.publish(event);
+  }
+
+  /**
+   * Publish a sub-agent status update event.
+   *
+   * @param agentId - Agent ID being updated
+   * @param currentTool - Current tool being used by the agent (optional)
+   * @param toolUses - Number of tool uses so far (optional)
+   */
+  publishAgentUpdate(
+    agentId: string,
+    currentTool?: string,
+    toolUses?: number,
+  ): void {
+    const event: BusEvent<"stream.agent.update"> = {
+      type: "stream.agent.update",
+      sessionId: this.sessionId,
+      runId: this.runId,
+      timestamp: Date.now(),
+      data: {
+        agentId,
+        currentTool,
+        toolUses,
+      },
+    };
+
+    this.bus.publish(event);
+  }
+
+  /**
+   * Publish a sub-agent complete event.
+   *
+   * @param agentId - Agent ID that completed
+   * @param success - Whether the agent succeeded
+   * @param result - Result summary returned by the agent (optional)
+   * @param error - Error message if agent execution failed (optional)
+   */
+  publishAgentComplete(
+    agentId: string,
+    success: boolean,
+    result?: string,
+    error?: string,
+  ): void {
+    const event: BusEvent<"stream.agent.complete"> = {
+      type: "stream.agent.complete",
+      sessionId: this.sessionId,
+      runId: this.runId,
+      timestamp: Date.now(),
+      data: {
+        agentId,
+        success,
+        result,
+        error,
+      },
+    };
+
+    this.bus.publish(event);
+  }
+}
diff --git a/src/events/batch-dispatcher.test.ts b/src/events/batch-dispatcher.test.ts
new file mode 100644
index 0000000000..92dd8b78f7
--- /dev/null
+++ b/src/events/batch-dispatcher.test.ts
@@ -0,0 +1,499 @@
+/**
+ * Unit tests for BatchDispatcher
+ *
+ * Tests the batch dispatcher functionality including:
+ * - Event enqueueing and buffering
+ * - Frame-aligned automatic flushing
+ * - Double-buffer swap pattern
+ * - Key-based coalescing for state updates
+ * - Text delta accumulation (never coalesced)
+ * - Timer lifecycle management
+ * - Disposal and cleanup
+ */
+
+import { describe, it, expect, beforeEach, afterEach, mock } from "bun:test";
+import { BatchDispatcher } from "./batch-dispatcher.ts";
+import { EventBus } from "./event-bus.ts";
+import type { BusEvent } from "./bus-events.ts";
+
+describe("BatchDispatcher", () => {
+  let bus: EventBus;
+  let dispatcher: BatchDispatcher;
+  let publishedEvents: BusEvent[];
+
+  /** Create dispatcher and register a consumer that collects flushed events. */
+  function createDispatcher(flushIntervalMs = 1000): BatchDispatcher {
+    dispatcher = new BatchDispatcher(bus, flushIntervalMs);
+    dispatcher.addConsumer((events) => {
+      publishedEvents.push(...events);
+    });
+    return dispatcher;
+  }
+
+  beforeEach(() => {
+    bus = new EventBus();
+    publishedEvents = [];
+  });
+
+  afterEach(() => {
+    // Clean up dispatcher to prevent timer leaks
+    if (dispatcher) {
+      dispatcher.dispose();
+    }
+  });
+
+  describe("enqueue()", () => {
+    it("should add events to buffer", () => {
+      createDispatcher(1000);
+
+      const event: BusEvent<"stream.text.delta"> = {
+        type: "stream.text.delta",
+        sessionId: "test-session",
+        runId: 1,
+        timestamp: Date.now(),
+        data: { delta: "Hello", messageId: "msg1" },
+      };
+
+      dispatcher.enqueue(event);
+
+      // Event should not be published yet
+      expect(publishedEvents.length).toBe(0);
+    });
+
+    it("should accumulate multiple events in buffer", () => {
+      createDispatcher(1000);
+
+      const event1: BusEvent<"stream.text.delta"> = {
+        type: "stream.text.delta",
+        sessionId: "test-session",
+        runId: 1,
+        timestamp: Date.now(),
+        data: { delta: "Hello", messageId: "msg1" },
+      };
+
+      const event2: BusEvent<"stream.text.delta"> = {
+        type: "stream.text.delta",
+        sessionId: "test-session",
+        runId: 1,
+        timestamp: Date.now(),
+        data: { delta: " world", messageId: "msg1" },
+      };
+
+      dispatcher.enqueue(event1);
+      dispatcher.enqueue(event2);
+
+      // Events should not be published yet
+      expect(publishedEvents.length).toBe(0);
+    });
+  });
+
+  describe("flush()", () => {
+    it("should publish all events to bus", () => {
+      createDispatcher(1000);
+
+      const event1: BusEvent<"stream.text.delta"> = {
+        type: "stream.text.delta",
+        sessionId: "test-session",
+        runId: 1,
+        timestamp: Date.now(),
+        data: { delta: "Hello", messageId: "msg1" },
+      };
+
+      const event2: BusEvent<"stream.text.delta"> = {
+        type: "stream.text.delta",
+        sessionId: "test-session",
+        runId: 1,
+        timestamp: Date.now(),
+        data: { delta: " world", messageId: "msg1" },
+      };
+
+      dispatcher.enqueue(event1);
+      dispatcher.enqueue(event2);
+      dispatcher.flush();
+
+      expect(publishedEvents.length).toBe(2);
+      expect(publishedEvents[0]).toEqual(event1);
+      expect(publishedEvents[1]).toEqual(event2);
+    });
+
+    it("should use double-buffer swap (old write becomes new read)", () => {
+      createDispatcher(1000);
+
+      const event1: BusEvent<"stream.text.delta"> = {
+        type: "stream.text.delta",
+        sessionId: "test-session",
+        runId: 1,
+        timestamp: Date.now(),
+        data: { delta: "First", messageId: "msg1" },
+      };
+
+      dispatcher.enqueue(event1);
+      dispatcher.flush();
+
+      expect(publishedEvents.length).toBe(1);
+      expect(publishedEvents[0]).toEqual(event1);
+
+      // Clear published events
+      publishedEvents.length = 0;
+
+      // Enqueue new event after flush
+      const event2: BusEvent<"stream.text.delta"> = {
+        type: "stream.text.delta",
+        sessionId: "test-session",
+        runId: 1,
+        timestamp: Date.now(),
+        data: { delta: "Second", messageId: "msg1" },
+      };
+
+      dispatcher.enqueue(event2);
+      dispatcher.flush();
+
+      expect(publishedEvents.length).toBe(1);
+      expect(publishedEvents[0]).toEqual(event2);
+    });
+
+    it("should preserve flush order for non-coalesced events", () => {
+      createDispatcher(1000);
+
+      const events: BusEvent[] = [
+        {
+          type: "stream.text.delta",
+          sessionId: "test-session",
+          runId: 1,
+          timestamp: Date.now(),
+          data: { delta: "First", messageId: "msg1" },
+        },
+        {
+          type: "stream.text.delta",
+          sessionId: "test-session",
+          runId: 1,
+          timestamp: Date.now(),
+          data: { delta: "Second", messageId: "msg1" },
+        },
+        {
+          type: "stream.text.delta",
+          sessionId: "test-session",
+          runId: 1,
+          timestamp: Date.now(),
+          data: { delta: "Third", messageId: "msg1" },
+        },
+      ];
+
+      events.forEach((event) => dispatcher.enqueue(event));
+      dispatcher.flush();
+
+      expect(publishedEvents.length).toBe(3);
+      expect(publishedEvents[0]).toEqual(events[0]);
+      expect(publishedEvents[1]).toEqual(events[1]);
+      expect(publishedEvents[2]).toEqual(events[2]);
+    });
+  });
+
+  describe("coalescing behavior", () => {
+    it("should coalesce events with same key (only latest retained)", () => {
+      createDispatcher(1000);
+
+      const event1: BusEvent<"stream.tool.start"> = {
+        type: "stream.tool.start",
+        sessionId: "test-session",
+        runId: 1,
+        timestamp: Date.now(),
+        data: {
+          toolId: "tool-123",
+          toolName: "test_tool",
+          toolInput: { param: "value1" },
+        },
+      };
+
+      const event2: BusEvent<"stream.tool.start"> = {
+        type: "stream.tool.start",
+        sessionId: "test-session",
+        runId: 1,
+        timestamp: Date.now() + 1,
+        data: {
+          toolId: "tool-123",
+          toolName: "test_tool",
+          toolInput: { param: "value2" },
+        },
+      };
+
+      dispatcher.enqueue(event1);
+      dispatcher.enqueue(event2);
+      dispatcher.flush();
+
+      // Should only have the latest event
+      expect(publishedEvents.length).toBe(1);
+      expect(publishedEvents[0]).toEqual(event2);
+    });
+
+    it("should never coalesce text deltas (all accumulate)", () => {
+      createDispatcher(1000);
+
+      const event1: BusEvent<"stream.text.delta"> = {
+        type: "stream.text.delta",
+        sessionId: "test-session",
+        runId: 1,
+        timestamp: Date.now(),
+        data: { delta: "Hello", messageId: "msg1" },
+      };
+
+      const event2: BusEvent<"stream.text.delta"> = {
+        type: "stream.text.delta",
+        sessionId: "test-session",
+        runId: 1,
+        timestamp: Date.now(),
+        data: { delta: " world", messageId: "msg1" },
+      };
+
+      const event3: BusEvent<"stream.text.delta"> = {
+        type: "stream.text.delta",
+        sessionId: "test-session",
+        runId: 1,
+        timestamp: Date.now(),
+        data: { delta: "!", messageId: "msg1" },
+      };
+
+      dispatcher.enqueue(event1);
+      dispatcher.enqueue(event2);
+      dispatcher.enqueue(event3);
+      dispatcher.flush();
+
+      // All text deltas should be present
+      expect(publishedEvents.length).toBe(3);
+      expect(publishedEvents[0]).toEqual(event1);
+      expect(publishedEvents[1]).toEqual(event2);
+      expect(publishedEvents[2]).toEqual(event3);
+    });
+
+    it("should handle mixed coalescable and non-coalescable events", () => {
+      createDispatcher(1000);
+
+      const textDelta1: BusEvent<"stream.text.delta"> = {
+        type: "stream.text.delta",
+        sessionId: "test-session",
+        runId: 1,
+        timestamp: Date.now(),
+        data: { delta: "Hello", messageId: "msg1" },
+      };
+
+      const toolEvent1: BusEvent<"stream.tool.start"> = {
+        type: "stream.tool.start",
+        sessionId: "test-session",
+        runId: 1,
+        timestamp: Date.now(),
+        data: {
+          toolId: "tool-123",
+          toolName: "test_tool",
+          toolInput: { version: 1 },
+        },
+      };
+
+      const textDelta2: BusEvent<"stream.text.delta"> = {
+        type: "stream.text.delta",
+        sessionId: "test-session",
+        runId: 1,
+        timestamp: Date.now(),
+        data: { delta: " world", messageId: "msg1" },
+      };
+
+      const toolEvent2: BusEvent<"stream.tool.start"> = {
+        type: "stream.tool.start",
+        sessionId: "test-session",
+        runId: 1,
+        timestamp: Date.now() + 1,
+        data: {
+          toolId: "tool-123",
+          toolName: "test_tool",
+          toolInput: { version: 2 },
+        },
+      };
+
+      dispatcher.enqueue(textDelta1);
+      dispatcher.enqueue(toolEvent1);
+      dispatcher.enqueue(textDelta2);
+      dispatcher.enqueue(toolEvent2);
+      dispatcher.flush();
+
+      // Should have both text deltas (not coalesced) and only the latest tool event (coalesced)
+      expect(publishedEvents.length).toBe(3);
+      expect(publishedEvents[0]).toEqual(textDelta1);
+      expect(publishedEvents[1]).toEqual(toolEvent2); // Replaced toolEvent1
+      expect(publishedEvents[2]).toEqual(textDelta2);
+    });
+
+    it("should coalesce multiple different tools independently", () => {
+      createDispatcher(1000);
+
+      const tool1Event1: BusEvent<"stream.tool.start"> = {
+        type: "stream.tool.start",
+        sessionId: "test-session",
+        runId: 1,
+        timestamp: Date.now(),
+        data: {
+          toolId: "tool-123",
+          toolName: "tool_a",
+          toolInput: { version: 1 },
+        },
+      };
+
+      const tool2Event1: BusEvent<"stream.tool.start"> = {
+        type: "stream.tool.start",
+        sessionId: "test-session",
+        runId: 1,
+        timestamp: Date.now(),
+        data: {
+          toolId: "tool-456",
+          toolName: "tool_b",
+          toolInput: { version: 1 },
+        },
+      };
+
+      const tool1Event2: BusEvent<"stream.tool.start"> = {
+        type: "stream.tool.start",
+        sessionId: "test-session",
+        runId: 1,
+        timestamp: Date.now() + 1,
+        data: {
+          toolId: "tool-123",
+          toolName: "tool_a",
+          toolInput: { version: 2 },
+        },
+      };
+
+      dispatcher.enqueue(tool1Event1);
+      dispatcher.enqueue(tool2Event1);
+      dispatcher.enqueue(tool1Event2);
+      dispatcher.flush();
+
+      // Should have latest version of tool-123 and tool-456
+      expect(publishedEvents.length).toBe(2);
+      expect(publishedEvents[0]).toEqual(tool1Event2); // tool-123 updated
+      expect(publishedEvents[1]).toEqual(tool2Event1); // tool-456 unchanged
+    });
+  });
+
+  describe("timer lifecycle", () => {
+    it("should auto-start timer on first enqueue", async () => {
+      createDispatcher(50);
+
+      const event: BusEvent<"stream.text.delta"> = {
+        type: "stream.text.delta",
+        sessionId: "test-session",
+        runId: 1,
+        timestamp: Date.now(),
+        data: { delta: "Hello", messageId: "msg1" },
+      };
+
+      dispatcher.enqueue(event);
+
+      // Wait for timer to fire
+      await Bun.sleep(100);
+
+      // Event should be published automatically
+      expect(publishedEvents.length).toBe(1);
+      expect(publishedEvents[0]).toEqual(event);
+    });
+
+    it("should auto-stop timer when buffer empty after flush", async () => {
+      createDispatcher(50);
+
+      const event: BusEvent<"stream.text.delta"> = {
+        type: "stream.text.delta",
+        sessionId: "test-session",
+        runId: 1,
+        timestamp: Date.now(),
+        data: { delta: "Hello", messageId: "msg1" },
+      };
+
+      dispatcher.enqueue(event);
+
+      // Wait for auto-flush
+      await Bun.sleep(100);
+
+      expect(publishedEvents.length).toBe(1);
+
+      // Clear published events
+      publishedEvents.length = 0;
+
+      // Wait longer to ensure timer stopped (no additional flushes)
+      await Bun.sleep(150);
+
+      // Should still be 0 (timer stopped)
+      expect(publishedEvents.length).toBe(0);
+    });
+
+    it("should continue timer while events are being enqueued", async () => {
+      createDispatcher(50);
+
+      const event1: BusEvent<"stream.text.delta"> = {
+        type: "stream.text.delta",
+        sessionId: "test-session",
+        runId: 1,
+        timestamp: Date.now(),
+        data: { delta: "First", messageId: "msg1" },
+      };
+
+      const event2: BusEvent<"stream.text.delta"> = {
+        type: "stream.text.delta",
+        sessionId: "test-session",
+        runId: 1,
+        timestamp: Date.now(),
+        data: { delta: "Second", messageId: "msg1" },
+      };
+
+      dispatcher.enqueue(event1);
+
+      // Wait for first flush
+      await Bun.sleep(75);
+      expect(publishedEvents.length).toBe(1);
+
+      // Enqueue second event
+      dispatcher.enqueue(event2);
+
+      // Wait for second flush
+      await Bun.sleep(75);
+      expect(publishedEvents.length).toBe(2);
+    });
+  });
+
+  describe("dispose()", () => {
+    it("should clear timer and buffers", () => {
+      createDispatcher(1000);
+
+      const event: BusEvent<"stream.text.delta"> = {
+        type: "stream.text.delta",
+        sessionId: "test-session",
+        runId: 1,
+        timestamp: Date.now(),
+        data: { delta: "Hello", messageId: "msg1" },
+      };
+
+      dispatcher.enqueue(event);
+      dispatcher.dispose();
+
+      // Events should be cleared without being flushed
+      expect(publishedEvents.length).toBe(0);
+    });
+
+    it("should prevent auto-flush after dispose", async () => {
+      createDispatcher(50);
+
+      const event: BusEvent<"stream.text.delta"> = {
+        type: "stream.text.delta",
+        sessionId: "test-session",
+        runId: 1,
+        timestamp: Date.now(),
+        data: { delta: "Hello", messageId: "msg1" },
+      };
+
+      dispatcher.enqueue(event);
+      dispatcher.dispose();
+
+      // Wait longer than flush interval
+      await Bun.sleep(100);
+
+      // Should not have been flushed
+      expect(publishedEvents.length).toBe(0);
+    });
+  });
+});
diff --git a/src/events/batch-dispatcher.ts b/src/events/batch-dispatcher.ts
new file mode 100644
index 0000000000..aaf60377bb
--- /dev/null
+++ b/src/events/batch-dispatcher.ts
@@ -0,0 +1,312 @@
+/**
+ * Batch Dispatcher with Frame-Aligned Batching
+ *
+ * This module implements the BatchDispatcher class for efficient event batching
+ * with coalescing. Events are accumulated in a write buffer and flushed to the
+ * event bus at regular intervals (~60fps by default).
+ *
+ * Key features:
+ * - Double-buffer swap pattern for zero-allocation flushes
+ * - Key-based coalescing for state updates (only latest state matters)
+ * - Text deltas are NEVER coalesced (they accumulate)
+ * - Auto-start/stop timer based on buffer activity
+ * - Frame-aligned 16ms default flush interval
+ */
+
+import type { BusEvent } from "./bus-events.ts";
+import { coalescingKey } from "./coalescing.ts";
+import type { EventBus } from "./event-bus.ts";
+import { pipelineLog } from "./pipeline-logger.ts";
+
+const FLUSH_INTERVAL_MS = 16; // ~60 FPS alignment
+
+/**
+ * Maximum buffer size before oldest non-lifecycle events are dropped.
+ * Prevents unbounded memory growth during event bursts.
+ */
+const MAX_BUFFER_SIZE = 10_000;
+
+/**
+ * Metrics tracking for batch dispatcher operations.
+ */
+export interface BatchMetrics {
+  /** Total events published across all flushes */
+  totalFlushed: number;
+  /** Total events that were coalesced (replaced in-place) */
+  totalCoalesced: number;
+  /** Number of flush cycles */
+  flushCount: number;
+  /** Duration of last flush in milliseconds */
+  lastFlushDuration: number;
+  /** Number of events in last flush */
+  lastFlushSize: number;
+  /** Total events dropped due to buffer overflow */
+  totalDropped: number;
+}
+
+/** Session lifecycle event types that should never be dropped */
+const LIFECYCLE_EVENT_TYPES = new Set([
+  "stream.session.start",
+  "stream.session.idle",
+  "stream.session.error",
+  "stream.session.retry",
+]);
+
+/**
+ * Batch dispatcher for frame-aligned event batching with coalescing.
+ *
+ * Manages efficient event batching using a double-buffer pattern. Events are
+ * enqueued into a write buffer and periodically flushed to the event bus.
+ * State updates with the same coalescing key are replaced in-place (only the
+ * latest state matters), while text deltas accumulate normally.
+ *
+ * The timer automatically starts on the first enqueued event and stops when
+ * the buffer is empty, minimizing overhead when idle.
+ *
+ * Usage:
+ * ```typescript
+ * const bus = new EventBus();
+ * const dispatcher = new BatchDispatcher(bus, 16); // 16ms = ~60fps
+ *
+ * // Enqueue events - they batch automatically
+ * dispatcher.enqueue({
+ *   type: "stream.text.delta",
+ *   sessionId: "abc123",
+ *   runId: 1,
+ *   timestamp: Date.now(),
+ *   data: { delta: "Hello", messageId: "msg1" }
+ * });
+ *
+ * // Events flush automatically every 16ms
+ * // Or manually flush:
+ * dispatcher.flush();
+ *
+ * // Clean up when done
+ * dispatcher.dispose();
+ * ```
+ */
+export class BatchDispatcher {
+  private bus: EventBus;
+  private writeBuffer: BusEvent[] = [];
+  private readBuffer: BusEvent[] = [];
+  private coalescingMap = new Map<string, number>(); // key → index in writeBuffer
+  private staleDeltas = new Set<string>(); // delta keys superseded by complete events
+  private flushTimer: ReturnType<typeof setTimeout> | null = null;
+  private lastFlush = Date.now();
+  private flushIntervalMs: number;
+  private consumers: Array<(events: BusEvent[]) => void> = [];
+  private _metrics: BatchMetrics = {
+    totalFlushed: 0,
+    totalCoalesced: 0,
+    flushCount: 0,
+    lastFlushDuration: 0,
+    lastFlushSize: 0,
+    totalDropped: 0,
+  };
+
+  /**
+   * Create a new batch dispatcher.
+   *
+   * @param bus - The event bus to flush events to
+   * @param flushIntervalMs - Milliseconds between automatic flushes (default: 16ms ~= 60fps)
+   */
+  constructor(bus: EventBus, flushIntervalMs = FLUSH_INTERVAL_MS) {
+    this.bus = bus;
+    this.flushIntervalMs = flushIntervalMs;
+  }
+
+  /**
+   * Get read-only metrics for observability.
+   *
+   * Provides lightweight performance metrics including total events flushed,
+   * coalescing ratio, flush count, and timing information.
+   */
+  get metrics(): Readonly<BatchMetrics> {
+    return this._metrics;
+  }
+
+  /**
+   * Enqueue an event for batched delivery.
+   *
+   * If the event has a coalescing key and another event with the same key
+   * is already in the write buffer, the old event is replaced in-place.
+   * Text deltas (key = undefined) are never coalesced and always accumulate.
+   *
+   * @param event - The event to enqueue
+   */
+  enqueue(event: BusEvent): void {
+    const key = coalescingKey(event);
+    if (key !== undefined) {
+      const idx = this.coalescingMap.get(key);
+      if (idx !== undefined) {
+        // Replace in-place — only latest state matters
+        this.writeBuffer[idx] = event;
+        this._metrics.totalCoalesced++;
+
+        // When a complete event coalesces (replaces an earlier complete),
+        // mark corresponding deltas in the buffer as stale since the
+        // latest complete already contains the full accumulated state.
+        if (event.type === "stream.text.complete") {
+          const data = event.data as { messageId: string };
+          this.staleDeltas.add(`text.delta:${event.sessionId}:${data.messageId}`);
+        } else if (event.type === "stream.thinking.complete") {
+          const data = event.data as { sourceKey: string };
+          this.staleDeltas.add(`thinking.delta:${event.sessionId}:${data.sourceKey}`);
+        }
+
+        pipelineLog("Dispatcher", "coalesce", { key, type: event.type });
+        return;
+      }
+      this.coalescingMap.set(key, this.writeBuffer.length);
+    }
+
+    // Enforce buffer size limit — drop oldest non-lifecycle event on overflow
+    if (this.writeBuffer.length >= MAX_BUFFER_SIZE) {
+      let dropIdx = -1;
+      for (let i = 0; i < this.writeBuffer.length; i++) {
+        const buffered = this.writeBuffer[i];
+        if (buffered && !LIFECYCLE_EVENT_TYPES.has(buffered.type)) {
+          dropIdx = i;
+          break;
+        }
+      }
+      if (dropIdx >= 0) {
+        const dropped = this.writeBuffer.splice(dropIdx, 1)[0];
+        this._metrics.totalDropped++;
+        // Rebuild coalescing map indices after splice
+        this.rebuildCoalescingMap();
+        if (dropped) {
+          pipelineLog("Dispatcher", "buffer_overflow_drop", { droppedType: dropped.type });
+        }
+      }
+    }
+
+    this.writeBuffer.push(event);
+    this.scheduleFlush();
+  }
+
+  /**
+   * Register a consumer that receives batched events on flush.
+   *
+   * @param consumer - Callback receiving an array of batched events
+   * @returns Unsubscribe function to remove the consumer
+   */
+  addConsumer(consumer: (events: BusEvent[]) => void): () => void {
+    this.consumers.push(consumer);
+    return () => {
+      const idx = this.consumers.indexOf(consumer);
+      if (idx !== -1) this.consumers.splice(idx, 1);
+    };
+  }
+
+  /**
+   * Flush all buffered events immediately.
+   *
+   * Uses a double-buffer swap pattern for efficient zero-allocation flushing.
+   * Dispatches batched events to all registered consumers.
+   */
+  flush(): void {
+    this.flushTimer = null;
+    const startTime = performance.now();
+
+    // Capture stale delta keys before clearing
+    const skip = this.staleDeltas.size > 0 ? new Set(this.staleDeltas) : undefined;
+
+    // Double-buffer swap
+    const toFlush = this.writeBuffer;
+    this.writeBuffer = this.readBuffer;
+    this.readBuffer = toFlush;
+    this.writeBuffer.length = 0;
+    this.coalescingMap.clear();
+    this.staleDeltas.clear();
+    this.lastFlush = Date.now();
+
+    // Filter stale deltas during dispatch
+    let filteredFlush = toFlush;
+    if (skip) {
+      filteredFlush = toFlush.filter((event) => {
+        if (event.type === "stream.text.delta") {
+          const data = event.data as { messageId: string };
+          return !skip.has(`text.delta:${event.sessionId}:${data.messageId}`);
+        }
+        if (event.type === "stream.thinking.delta") {
+          const data = event.data as { sourceKey: string };
+          return !skip.has(`thinking.delta:${event.sessionId}:${data.sourceKey}`);
+        }
+        return true;
+      });
+    }
+
+    // Dispatch batched events to all consumers
+    for (const consumer of this.consumers) {
+      consumer(filteredFlush);
+    }
+
+    // Update metrics
+    const flushSize = filteredFlush.length;
+    this._metrics.totalFlushed += flushSize;
+    this._metrics.flushCount++;
+    this._metrics.lastFlushSize = flushSize;
+    this._metrics.lastFlushDuration = performance.now() - startTime;
+
+    pipelineLog("Dispatcher", "flush", { count: flushSize, durationMs: this._metrics.lastFlushDuration });
+  }
+
+  /**
+   * Schedule a flush using setTimeout with elapsed time calculation.
+   * If enough time has passed since last flush, flush immediately.
+   */
+  private scheduleFlush(): void {
+    if (this.flushTimer !== null) return;
+    const elapsed = Date.now() - this.lastFlush;
+    if (elapsed >= this.flushIntervalMs) {
+      this.flush();
+    } else {
+      this.flushTimer = setTimeout(
+        () => this.flush(),
+        this.flushIntervalMs - elapsed,
+      );
+    }
+  }
+
+  /**
+   * Clean up resources.
+   *
+   * Stops the flush timer and clears all buffered events. Should be called
+   * when the dispatcher is no longer needed to prevent memory leaks.
+   */
+  dispose(): void {
+    if (this.flushTimer !== null) {
+      clearTimeout(this.flushTimer);
+      this.flushTimer = null;
+    }
+    this.writeBuffer.length = 0;
+    this.readBuffer.length = 0;
+    this.coalescingMap.clear();
+    this.staleDeltas.clear();
+    this.consumers.length = 0;
+    this._metrics = {
+      totalFlushed: 0,
+      totalCoalesced: 0,
+      flushCount: 0,
+      lastFlushDuration: 0,
+      lastFlushSize: 0,
+      totalDropped: 0,
+    };
+  }
+
+  /**
+   * Rebuild the coalescing map after a splice operation shifts indices.
+   */
+  private rebuildCoalescingMap(): void {
+    this.coalescingMap.clear();
+    for (let i = 0; i < this.writeBuffer.length; i++) {
+      const ev = this.writeBuffer[i];
+      if (!ev) continue;
+      const key = coalescingKey(ev);
+      if (key !== undefined) {
+        this.coalescingMap.set(key, i);
+      }
+    }
+  }
+}
diff --git a/src/events/bus-events.test.ts b/src/events/bus-events.test.ts
new file mode 100644
index 0000000000..40da17c414
--- /dev/null
+++ b/src/events/bus-events.test.ts
@@ -0,0 +1,255 @@
+/**
+ * Type tests for bus-events.ts
+ *
+ * These tests verify that the type definitions work correctly and provide
+ * proper type safety and inference.
+ */
+
+import { describe, it, expect } from "bun:test";
+import type {
+  BusEventType,
+  BusEventDataMap,
+  BusEvent,
+  BusHandler,
+  WildcardHandler,
+  EnrichedBusEvent,
+} from "./bus-events";
+
+describe("BusEvent Type Definitions", () => {
+  it("should create a valid text delta event", () => {
+    const event: BusEvent<"stream.text.delta"> = {
+      type: "stream.text.delta",
+      sessionId: "test-session",
+      runId: 1,
+      timestamp: Date.now(),
+      data: {
+        delta: "Hello",
+        messageId: "msg-1",
+      },
+    };
+
+    expect(event.type).toBe("stream.text.delta");
+    expect(event.data.delta).toBe("Hello");
+  });
+
+  it("should create a valid tool start event", () => {
+    const event: BusEvent<"stream.tool.start"> = {
+      type: "stream.tool.start",
+      sessionId: "test-session",
+      runId: 1,
+      timestamp: Date.now(),
+      data: {
+        toolId: "tool-1",
+        toolName: "bash",
+        toolInput: { command: "ls -la" },
+        sdkCorrelationId: "sdk-123",
+      },
+    };
+
+    expect(event.type).toBe("stream.tool.start");
+    expect(event.data.toolName).toBe("bash");
+  });
+
+  it("should create a valid agent start event", () => {
+    const event: BusEvent<"stream.agent.start"> = {
+      type: "stream.agent.start",
+      sessionId: "test-session",
+      runId: 1,
+      timestamp: Date.now(),
+      data: {
+        agentId: "agent-1",
+        toolCallId: "agent-1",
+        agentType: "explore",
+        task: "Find all TypeScript files",
+        isBackground: false,
+      },
+    };
+
+    expect(event.type).toBe("stream.agent.start");
+    expect(event.data.agentType).toBe("explore");
+  });
+
+  it("should create a valid workflow step start event", () => {
+    const event: BusEvent<"workflow.step.start"> = {
+      type: "workflow.step.start",
+      sessionId: "test-session",
+      runId: 1,
+      timestamp: Date.now(),
+      data: {
+        workflowId: "workflow-1",
+        nodeId: "node-1",
+        nodeName: "Initialize",
+      },
+    };
+
+    expect(event.type).toBe("workflow.step.start");
+    expect(event.data.nodeName).toBe("Initialize");
+  });
+
+  it("should create a valid permission requested event", () => {
+    const event: BusEvent<"stream.permission.requested"> = {
+      type: "stream.permission.requested",
+      sessionId: "test-session",
+      runId: 1,
+      timestamp: Date.now(),
+      data: {
+        requestId: "req-1",
+        toolName: "file_delete",
+        question: "Delete this file?",
+        options: [
+          { label: "Yes", value: "yes" },
+          { label: "No", value: "no" },
+        ],
+      },
+    };
+
+    expect(event.type).toBe("stream.permission.requested");
+    expect(event.data.options).toHaveLength(2);
+  });
+
+  it("should create a valid usage event", () => {
+    const event: BusEvent<"stream.usage"> = {
+      type: "stream.usage",
+      sessionId: "test-session",
+      runId: 1,
+      timestamp: Date.now(),
+      data: {
+        inputTokens: 100,
+        outputTokens: 50,
+        model: "claude-3-sonnet",
+      },
+    };
+
+    expect(event.data.inputTokens).toBe(100);
+    expect(event.data.outputTokens).toBe(50);
+  });
+
+  it("should support typed event handlers", () => {
+    const handler: BusHandler<"stream.text.delta"> = (event) => {
+      // TypeScript should infer the correct data type
+      expect(typeof event.data.delta).toBe("string");
+      expect(typeof event.data.messageId).toBe("string");
+    };
+
+    const testEvent: BusEvent<"stream.text.delta"> = {
+      type: "stream.text.delta",
+      sessionId: "test",
+      runId: 1,
+      timestamp: Date.now(),
+      data: { delta: "test", messageId: "msg-1" },
+    };
+
+    handler(testEvent);
+  });
+
+  it("should support wildcard handlers", () => {
+    const wildcardHandler: WildcardHandler = (event) => {
+      // Should accept any event type
+      expect(event.type).toBeDefined();
+      expect(event.sessionId).toBeDefined();
+    };
+
+    const textEvent: BusEvent<"stream.text.delta"> = {
+      type: "stream.text.delta",
+      sessionId: "test",
+      runId: 1,
+      timestamp: Date.now(),
+      data: { delta: "test", messageId: "msg-1" },
+    };
+
+    const toolEvent: BusEvent<"stream.tool.start"> = {
+      type: "stream.tool.start",
+      sessionId: "test",
+      runId: 1,
+      timestamp: Date.now(),
+      data: {
+        toolId: "tool-1",
+        toolName: "bash",
+        toolInput: {},
+      },
+    };
+
+    wildcardHandler(textEvent);
+    wildcardHandler(toolEvent);
+  });
+
+  it("should create enriched events with correlation data", () => {
+    const enrichedEvent: EnrichedBusEvent = {
+      type: "stream.tool.start",
+      sessionId: "test-session",
+      runId: 1,
+      timestamp: Date.now(),
+      data: {
+        toolId: "tool-1",
+        toolName: "bash",
+        toolInput: {},
+        parentAgentId: "agent-1",
+      },
+      resolvedToolId: "resolved-tool-1",
+      resolvedAgentId: "agent-1",
+      isSubagentTool: true,
+      suppressFromMainChat: true,
+    };
+
+    expect(enrichedEvent.isSubagentTool).toBe(true);
+    expect(enrichedEvent.suppressFromMainChat).toBe(true);
+  });
+
+  it("should ensure all event types are covered in BusEventDataMap", () => {
+    // This is a compile-time check - if any event type is missing from
+    // BusEventDataMap, TypeScript will error
+    const eventTypes: BusEventType[] = [
+      "stream.text.delta",
+      "stream.text.complete",
+      "stream.thinking.delta",
+      "stream.thinking.complete",
+      "stream.tool.start",
+      "stream.tool.complete",
+      "stream.agent.start",
+      "stream.agent.update",
+      "stream.agent.complete",
+      "stream.session.start",
+      "stream.session.idle",
+      "stream.session.error",
+      "workflow.step.start",
+      "workflow.step.complete",
+      "workflow.task.update",
+      "workflow.task.statusChange",
+      "stream.permission.requested",
+      "stream.human_input_required",
+      "stream.skill.invoked",
+      "stream.usage",
+    ];
+
+    // Verify we have data map entries for all event types
+    eventTypes.forEach((type) => {
+      // This is a type-level check - the key must exist in BusEventDataMap
+      const _check: keyof BusEventDataMap = type;
+      expect(type).toBeDefined();
+    });
+  });
+
+  it("should create a valid workflow.task.statusChange event", () => {
+    const event: BusEvent<"workflow.task.statusChange"> = {
+      type: "workflow.task.statusChange",
+      sessionId: "test-session",
+      runId: 1,
+      timestamp: Date.now(),
+      data: {
+        taskIds: ["task-1", "task-2"],
+        newStatus: "in_progress",
+        tasks: [
+          { id: "task-1", title: "First task", status: "in_progress" },
+          { id: "task-2", title: "Second task", status: "in_progress" },
+          { id: "task-3", title: "Third task", status: "pending" },
+        ],
+      },
+    };
+
+    expect(event.type).toBe("workflow.task.statusChange");
+    expect(event.data.taskIds).toEqual(["task-1", "task-2"]);
+    expect(event.data.newStatus).toBe("in_progress");
+    expect(event.data.tasks).toHaveLength(3);
+    expect(event.data.tasks[0]!.status).toBe("in_progress");
+  });
+});
diff --git a/src/events/bus-events.ts b/src/events/bus-events.ts
new file mode 100644
index 0000000000..9ef0071e12
--- /dev/null
+++ b/src/events/bus-events.ts
@@ -0,0 +1,696 @@
+/**
+ * Event Bus Type Definitions
+ *
+ * This module defines the typed event system for the new event bus architecture.
+ * The event bus provides a centralized, type-safe pub/sub system for streaming
+ * events from multiple SDK adapters (OpenCode, Claude, Copilot) and workflow nodes.
+ *
+ * Key concepts:
+ * - BusEventType: String union of all event types
+ * - BusEventDataMap: Type mapping from event type to payload structure
+ * - BusEvent: The base event envelope with metadata
+ * - EnrichedBusEvent: Extended event with correlation and suppression data
+ * - BusEventSchemas: Zod schemas for runtime validation of event payloads
+ */
+
+import { z } from "zod";
+import {
+  workflowRuntimeTaskSchema,
+  workflowRuntimeTaskStatusChangeSchema,
+  type WorkflowRuntimeTask,
+} from "../workflows/runtime-contracts.ts";
+
+/**
+ * All event types supported by the event bus.
+ *
+ * Categories:
+ * - stream.text.*: Text content streaming events
+ * - stream.thinking.*: Reasoning/thinking content streaming
+ * - stream.tool.*: Tool invocation lifecycle events
+ * - stream.agent.*: Sub-agent lifecycle events
+ * - stream.session.*: Session state management events
+ * - workflow.*: Workflow execution events
+ * - stream.permission.*: User permission request events
+ * - stream.human_input_required: Human input request events
+ * - stream.skill.*: Skill invocation events
+ * - stream.usage: Token usage tracking events
+ */
+export type BusEventType =
+  | "stream.text.delta"
+  | "stream.text.complete"
+  | "stream.thinking.delta"
+  | "stream.thinking.complete"
+  | "stream.tool.start"
+  | "stream.tool.complete"
+  | "stream.tool.partial_result"
+  | "stream.agent.start"
+  | "stream.agent.update"
+  | "stream.agent.complete"
+  | "stream.session.start"
+  | "stream.session.idle"
+  | "stream.session.error"
+  | "stream.session.info"
+  | "stream.session.warning"
+  | "stream.session.title_changed"
+  | "stream.session.truncation"
+  | "stream.session.compaction"
+  | "stream.turn.start"
+  | "stream.turn.end"
+  | "workflow.step.start"
+  | "workflow.step.complete"
+  | "workflow.task.update"
+  | "workflow.task.statusChange"
+  | "stream.permission.requested"
+  | "stream.human_input_required"
+  | "stream.session.retry"
+  | "stream.skill.invoked"
+  | "stream.usage";
+
+/**
+ * Type mapping from event type to payload structure.
+ *
+ * This interface ensures type safety when publishing and subscribing to events.
+ * Each event type has a well-defined payload structure.
+ */
+export interface BusEventDataMap {
+  /**
+   * Streaming text content delta (incremental chunk)
+   */
+  "stream.text.delta": {
+    /** Text content delta to append */
+    delta: string;
+    /** Message ID this delta belongs to */
+    messageId: string;
+    /** Agent ID for sub-agent scoped events */
+    agentId?: string;
+  };
+
+  /**
+   * Text streaming completion event
+   */
+  "stream.text.complete": {
+    /** Message ID that completed */
+    messageId: string;
+    /** Full accumulated text content */
+    fullText: string;
+  };
+
+  /**
+   * Streaming thinking/reasoning content delta
+   */
+  "stream.thinking.delta": {
+    /** Thinking content delta to append */
+    delta: string;
+    /** Source identifier for this thinking stream (e.g., block ID) */
+    sourceKey: string;
+    /** Message ID this thinking belongs to */
+    messageId: string;
+    /** Agent ID for sub-agent scoped events */
+    agentId?: string;
+  };
+
+  /**
+   * Thinking stream completion event
+   */
+  "stream.thinking.complete": {
+    /** Source identifier that completed */
+    sourceKey: string;
+    /** Duration of thinking in milliseconds */
+    durationMs: number;
+    /** Agent ID for sub-agent scoped events */
+    agentId?: string;
+  };
+
+  /**
+   * Tool invocation started
+   */
+  "stream.tool.start": {
+    /** Unique tool invocation ID */
+    toolId: string;
+    /** Name of the tool being invoked */
+    toolName: string;
+    /** Input parameters passed to the tool */
+    toolInput: Record<string, unknown>;
+    /** SDK correlation ID for tracking across adapters */
+    sdkCorrelationId?: string;
+    /** Parent agent ID if this tool was invoked by a sub-agent */
+    parentAgentId?: string;
+  };
+
+  /**
+   * Tool invocation completed
+   */
+  "stream.tool.complete": {
+    /** Unique tool invocation ID */
+    toolId: string;
+    /** Name of the tool that completed */
+    toolName: string;
+    /** Input parameters passed to the tool (optional late payload) */
+    toolInput?: Record<string, unknown>;
+    /** Result returned by the tool */
+    toolResult: unknown;
+    /** Whether the tool execution succeeded */
+    success: boolean;
+    /** Error message if tool execution failed */
+    error?: string;
+    /** SDK correlation ID for tracking across adapters */
+    sdkCorrelationId?: string;
+    /** Parent agent ID if this tool was invoked by a sub-agent */
+    parentAgentId?: string;
+  };
+
+  /**
+   * Streaming partial output from a tool in progress (e.g., bash command output)
+   */
+  "stream.tool.partial_result": {
+    /** Tool call ID this output belongs to */
+    toolCallId: string;
+    /** Incremental output text */
+    partialOutput: string;
+    /** Parent agent ID if this tool belongs to a sub-agent */
+    parentAgentId?: string;
+  };
+
+  /**
+   * Sub-agent spawned and started
+   */
+  "stream.agent.start": {
+    /** Unique agent ID */
+    agentId: string;
+    /** Tool call ID that spawned this agent (or deterministic fallback) */
+    toolCallId: string;
+    /** Type of agent (e.g., "explore", "task", "general-purpose") */
+    agentType: string;
+    /** Task description given to the agent */
+    task: string;
+    /** Whether the agent is running in background mode */
+    isBackground: boolean;
+    /** SDK correlation ID for tracking across adapters */
+    sdkCorrelationId?: string;
+  };
+
+  /**
+   * Sub-agent status update (progress notification)
+   */
+  "stream.agent.update": {
+    /** Agent ID being updated */
+    agentId: string;
+    /** Current tool being used by the agent */
+    currentTool?: string;
+    /** Number of tool uses so far */
+    toolUses?: number;
+  };
+
+  /**
+   * Sub-agent completed execution
+   */
+  "stream.agent.complete": {
+    /** Agent ID that completed */
+    agentId: string;
+    /** Whether the agent succeeded */
+    success: boolean;
+    /** Result summary returned by the agent */
+    result?: string;
+    /** Error message if agent execution failed */
+    error?: string;
+  };
+
+  /**
+   * Session started
+   */
+  "stream.session.start": {
+    /** Session configuration (optional) */
+    config?: Record<string, unknown>;
+  };
+
+  /**
+   * Session entered idle state
+   */
+  "stream.session.idle": {
+    /** Reason for entering idle state */
+    reason?: string;
+  };
+
+  /**
+   * Session error occurred
+   */
+  "stream.session.error": {
+    /** Error message */
+    error: string;
+    /** Error code if available */
+    code?: string;
+  };
+
+  /**
+   * Session informational notification
+   */
+  "stream.session.info": {
+    /** Information category */
+    infoType: string;
+    /** Human-readable message */
+    message: string;
+  };
+
+  /**
+   * Session warning notification
+   */
+  "stream.session.warning": {
+    /** Warning category */
+    warningType: string;
+    /** Human-readable message */
+    message: string;
+  };
+
+  /**
+   * Session title changed
+   */
+  "stream.session.title_changed": {
+    /** New session title */
+    title: string;
+  };
+
+  /**
+   * Session context truncation event
+   */
+  "stream.session.truncation": {
+    /** Maximum token budget */
+    tokenLimit: number;
+    /** Tokens removed during truncation */
+    tokensRemoved: number;
+    /** Messages removed during truncation */
+    messagesRemoved: number;
+  };
+
+  /**
+   * Session compaction lifecycle event
+   */
+  "stream.session.compaction": {
+    /** Whether this is a start or complete event */
+    phase: "start" | "complete";
+    /** Whether compaction succeeded (only for complete phase) */
+    success?: boolean;
+    /** Error message on failure (only for complete phase) */
+    error?: string;
+  };
+
+  /**
+   * Turn started (agent begins processing)
+   */
+  "stream.turn.start": {
+    /** Unique turn identifier */
+    turnId: string;
+  };
+
+  /**
+   * Turn ended (agent finished processing)
+   */
+  "stream.turn.end": {
+    /** Unique turn identifier */
+    turnId: string;
+    /** Normalized finish reason for loop continuation decisions */
+    finishReason?: "tool-calls" | "stop" | "max-tokens" | "max-turns" | "error" | "unknown";
+    /** Provider-native finish reason before normalization */
+    rawFinishReason?: string;
+  };
+
+  /**
+   * Workflow step started
+   */
+  "workflow.step.start": {
+    /** Workflow instance ID */
+    workflowId: string;
+    /** Node ID within the workflow graph */
+    nodeId: string;
+    /** Human-readable node name */
+    nodeName: string;
+  };
+
+  /**
+   * Workflow step completed
+   */
+  "workflow.step.complete": {
+    /** Workflow instance ID */
+    workflowId: string;
+    /** Node ID that completed */
+    nodeId: string;
+    /** Human-readable node name */
+    nodeName: string;
+    /** Completion status */
+    status: "success" | "error" | "skipped";
+    /** Result data from the step (if any) */
+    result?: unknown;
+  };
+
+  /**
+   * Workflow task list updated
+   */
+  "workflow.task.update": {
+    /** Workflow instance ID */
+    workflowId: string;
+    /** Updated task list */
+    tasks: WorkflowRuntimeTask[];
+  };
+
+  /**
+   * Individual task status change (e.g., pending → in_progress before spawning workers)
+   */
+  "workflow.task.statusChange": {
+    /** IDs of the tasks whose status changed */
+    taskIds: string[];
+    /** The new status value */
+    newStatus: string;
+    /** Full updated task list snapshot */
+    tasks: WorkflowRuntimeTask[];
+  };
+
+  /**
+   * Permission requested from user (e.g., for tool execution)
+   */
+  "stream.permission.requested": {
+    /** Unique request ID */
+    requestId: string;
+    /** Name of the tool requiring permission */
+    toolName: string;
+    /** Input parameters for the tool (optional) */
+    toolInput?: Record<string, unknown>;
+    /** Question text to display to user */
+    question: string;
+    /** Header text for the permission dialog (optional) */
+    header?: string;
+    /** Available response options */
+    options: Array<{
+      /** Option label */
+      label: string;
+      /** Option value */
+      value: string;
+      /** Option description (optional) */
+      description?: string;
+    }>;
+    /** Whether multiple options can be selected */
+    multiSelect?: boolean;
+    /** Callback to respond with user's answer */
+    respond?: (answer: string | string[]) => void;
+    /** Tool call ID for correlation (optional) */
+    toolCallId?: string;
+  };
+
+  /**
+   * Human input required from user (e.g., in workflow)
+   */
+  "stream.human_input_required": {
+    /** Unique request ID */
+    requestId: string;
+    /** Question text to display to user */
+    question: string;
+    /** Header text for the input dialog (optional) */
+    header?: string;
+    /** Available response options (optional) */
+    options?: Array<{
+      /** Option label */
+      label: string;
+      /** Option description (optional) */
+      description?: string;
+    }>;
+    /** Node ID in workflow requesting input */
+    nodeId: string;
+    /** Callback to respond with user's answer */
+    respond?: (answer: string | string[]) => void;
+  };
+
+  /**
+   * Session retry state broadcast (retryable error, waiting before next attempt)
+   */
+  "stream.session.retry": {
+    /** Current attempt number (1-based) */
+    attempt: number;
+    /** Delay in milliseconds before next retry */
+    delay: number;
+    /** Human-readable reason for retry */
+    message: string;
+    /** Unix timestamp (ms) when next retry will occur */
+    nextRetryAt: number;
+  };
+
+  /**
+   * Skill invoked (custom command executed)
+   */
+  "stream.skill.invoked": {
+    /** Name of the skill */
+    skillName: string;
+    /** File path to the skill (optional) */
+    skillPath?: string;
+  };
+
+  /**
+   * Token usage information
+   */
+  "stream.usage": {
+    /** Number of input tokens consumed */
+    inputTokens: number;
+    /** Number of output tokens generated */
+    outputTokens: number;
+    /** Model identifier (optional) */
+    model?: string;
+    /** Agent ID for sub-agent scoped events */
+    agentId?: string;
+  };
+}
+
+/**
+ * Define a typed bus event with Zod schema validation (OpenCode pattern).
+ *
+ * @param type - Event type string
+ * @param schema - Zod schema for validating event data
+ * @returns Event definition with type, schema, and parse function
+ */
+export function defineBusEvent<T extends string, S extends z.ZodType>(
+  type: T,
+  schema: S,
+) {
+  return {
+    type,
+    schema,
+    parse: (data: unknown) => schema.parse(data),
+  } as const;
+}
+
+/**
+ * Zod schemas for all bus event data payloads.
+ * Used by publish() to validate event data at runtime.
+ */
+export const BusEventSchemas: Record<BusEventType, z.ZodType> = {
+  "stream.text.delta": z.object({
+    delta: z.string(),
+    messageId: z.string(),
+    agentId: z.string().optional(),
+  }),
+  "stream.text.complete": z.object({
+    messageId: z.string(),
+    fullText: z.string(),
+  }),
+  "stream.thinking.delta": z.object({
+    delta: z.string(),
+    sourceKey: z.string(),
+    messageId: z.string(),
+    agentId: z.string().optional(),
+  }),
+  "stream.thinking.complete": z.object({
+    sourceKey: z.string(),
+    durationMs: z.number(),
+    agentId: z.string().optional(),
+  }),
+  "stream.tool.start": z.object({
+    toolId: z.string(),
+    toolName: z.string(),
+    toolInput: z.record(z.string(), z.unknown()),
+    sdkCorrelationId: z.string().optional(),
+    parentAgentId: z.string().optional(),
+  }),
+  "stream.tool.complete": z.object({
+    toolId: z.string(),
+    toolName: z.string(),
+    toolInput: z.record(z.string(), z.unknown()).optional(),
+    toolResult: z.unknown(),
+    success: z.boolean(),
+    error: z.string().optional(),
+    sdkCorrelationId: z.string().optional(),
+    parentAgentId: z.string().optional(),
+  }),
+  "stream.tool.partial_result": z.object({
+    toolCallId: z.string(),
+    partialOutput: z.string(),
+    parentAgentId: z.string().optional(),
+  }),
+  "stream.agent.start": z.object({
+    agentId: z.string(),
+    toolCallId: z.string(),
+    agentType: z.string(),
+    task: z.string(),
+    isBackground: z.boolean(),
+    sdkCorrelationId: z.string().optional(),
+  }),
+  "stream.agent.update": z.object({
+    agentId: z.string(),
+    currentTool: z.string().optional(),
+    toolUses: z.number().optional(),
+  }),
+  "stream.agent.complete": z.object({
+    agentId: z.string(),
+    success: z.boolean(),
+    result: z.string().optional(),
+    error: z.string().optional(),
+  }),
+  "stream.session.start": z.object({
+    config: z.record(z.string(), z.unknown()).optional(),
+  }),
+  "stream.session.idle": z.object({
+    reason: z.string().optional(),
+  }),
+  "stream.session.error": z.object({
+    error: z.string(),
+    code: z.string().optional(),
+  }),
+  "stream.session.retry": z.object({
+    attempt: z.number(),
+    delay: z.number(),
+    message: z.string(),
+    nextRetryAt: z.number(),
+  }),
+  "stream.session.info": z.object({
+    infoType: z.string(),
+    message: z.string(),
+  }),
+  "stream.session.warning": z.object({
+    warningType: z.string(),
+    message: z.string(),
+  }),
+  "stream.session.title_changed": z.object({
+    title: z.string(),
+  }),
+  "stream.session.truncation": z.object({
+    tokenLimit: z.number(),
+    tokensRemoved: z.number(),
+    messagesRemoved: z.number(),
+  }),
+  "stream.session.compaction": z.object({
+    phase: z.enum(["start", "complete"]),
+    success: z.boolean().optional(),
+    error: z.string().optional(),
+  }),
+  "stream.turn.start": z.object({
+    turnId: z.string(),
+  }),
+  "stream.turn.end": z.object({
+    turnId: z.string(),
+    finishReason: z.enum(["tool-calls", "stop", "max-tokens", "max-turns", "error", "unknown"]).optional(),
+    rawFinishReason: z.string().optional(),
+  }),
+  "workflow.step.start": z.object({
+    workflowId: z.string(),
+    nodeId: z.string(),
+    nodeName: z.string(),
+  }),
+  "workflow.step.complete": z.object({
+    workflowId: z.string(),
+    nodeId: z.string(),
+    nodeName: z.string(),
+    status: z.enum(["success", "error", "skipped"]),
+    result: z.unknown().optional(),
+  }),
+  "workflow.task.update": z.object({
+    workflowId: z.string(),
+    tasks: z.array(workflowRuntimeTaskSchema),
+  }),
+  "workflow.task.statusChange": workflowRuntimeTaskStatusChangeSchema,
+  "stream.permission.requested": z.object({
+    requestId: z.string(),
+    toolName: z.string(),
+    toolInput: z.record(z.string(), z.unknown()).optional(),
+    question: z.string(),
+    header: z.string().optional(),
+    options: z.array(z.object({
+      label: z.string(),
+      value: z.string(),
+      description: z.string().optional(),
+    })),
+    multiSelect: z.boolean().optional(),
+    respond: z.function().optional(),
+    toolCallId: z.string().optional(),
+  }),
+  "stream.human_input_required": z.object({
+    requestId: z.string(),
+    question: z.string(),
+    header: z.string().optional(),
+    options: z.array(z.object({
+      label: z.string(),
+      description: z.string().optional(),
+    })).optional(),
+    nodeId: z.string(),
+    respond: z.function().optional(),
+  }),
+  "stream.skill.invoked": z.object({
+    skillName: z.string(),
+    skillPath: z.string().optional(),
+  }),
+  "stream.usage": z.object({
+    inputTokens: z.number(),
+    outputTokens: z.number(),
+    model: z.string().optional(),
+    agentId: z.string().optional(),
+  }),
+};
+
+/**
+ * Base event envelope for all bus events.
+ *
+ * All events flowing through the bus are wrapped in this structure,
+ * which provides metadata for routing, correlation, and timestamp tracking.
+ *
+ * @template T - The specific event type (from BusEventType)
+ */
+export interface BusEvent<T extends BusEventType = BusEventType> {
+  /** Event type identifier */
+  type: T;
+  /** Session ID that generated this event */
+  sessionId: string;
+  /** Run ID for staleness detection (increments per stream) */
+  runId: number;
+  /** Unix timestamp (milliseconds) when event was created */
+  timestamp: number;
+  /** Event-specific payload data */
+  data: BusEventDataMap[T];
+}
+
+/**
+ * Event handler callback type for typed subscriptions.
+ *
+ * @template T - The specific event type being handled
+ */
+export type BusHandler<T extends BusEventType> = (event: BusEvent<T>) => void;
+
+/**
+ * Wildcard event handler type for subscribing to all events.
+ *
+ * Useful for debugging, logging, and observability.
+ */
+export type WildcardHandler = (event: BusEvent) => void;
+
+/**
+ * Enriched event with correlation and suppression metadata.
+ *
+ * This is used internally by consumers (CorrelationService, EchoSuppressor)
+ * to track which events belong to sub-agents and should be filtered or routed
+ * differently in the UI.
+ */
+export interface EnrichedBusEvent extends BusEvent {
+  /** Resolved tool invocation ID after correlation */
+  resolvedToolId?: string;
+  /** Resolved agent ID after correlation */
+  resolvedAgentId?: string;
+  /** Whether this is a tool call from a sub-agent */
+  isSubagentTool?: boolean;
+  /** Whether this event should be hidden in the main chat UI */
+  suppressFromMainChat?: boolean;
+  /** Parent agent ID for sub-agent correlation */
+  parentAgentId?: string;
+}
diff --git a/src/events/coalescing.test.ts b/src/events/coalescing.test.ts
new file mode 100644
index 0000000000..ba6583fb98
--- /dev/null
+++ b/src/events/coalescing.test.ts
@@ -0,0 +1,550 @@
+/**
+ * Unit tests for coalescingKey()
+ *
+ * Tests the event coalescing key generation function to ensure:
+ * - Text deltas and thinking deltas return undefined (additive, never coalesced)
+ * - Tool events return unique key per toolId
+ * - Agent events return unique key per agentId
+ * - Session events return unique key per sessionId
+ * - Workflow events return unique key per workflowId
+ * - Unknown/unmapped events return undefined
+ */
+
+import { describe, it, expect } from "bun:test";
+import { coalescingKey } from "./coalescing.ts";
+import type { BusEvent } from "./bus-events.ts";
+
+describe("coalescingKey()", () => {
+  describe("additive events (return undefined - never coalesced)", () => {
+    it("should return undefined for stream.text.delta", () => {
+      const event: BusEvent<"stream.text.delta"> = {
+        type: "stream.text.delta",
+        sessionId: "test-session",
+        runId: 1,
+        timestamp: Date.now(),
+        data: { delta: "Hello", messageId: "msg1" },
+      };
+
+      const key = coalescingKey(event);
+      expect(key).toBeUndefined();
+    });
+
+    it("should return undefined for stream.thinking.delta", () => {
+      const event: BusEvent<"stream.thinking.delta"> = {
+        type: "stream.thinking.delta",
+        sessionId: "test-session",
+        runId: 1,
+        timestamp: Date.now(),
+        data: {
+          delta: "Let me think...",
+          sourceKey: "thinking-block-1",
+          messageId: "msg1",
+        },
+      };
+
+      const key = coalescingKey(event);
+      expect(key).toBeUndefined();
+    });
+  });
+
+  describe("tool events", () => {
+    it("should return tool.start:${toolId} for stream.tool.start", () => {
+      const event: BusEvent<"stream.tool.start"> = {
+        type: "stream.tool.start",
+        sessionId: "test-session",
+        runId: 1,
+        timestamp: Date.now(),
+        data: {
+          toolId: "tool-123",
+          toolName: "test_tool",
+          toolInput: { param: "value" },
+        },
+      };
+
+      const key = coalescingKey(event);
+      expect(key).toBe("tool.start:tool-123");
+    });
+
+    it("should return tool.complete:${toolId} for stream.tool.complete", () => {
+      const event: BusEvent<"stream.tool.complete"> = {
+        type: "stream.tool.complete",
+        sessionId: "test-session",
+        runId: 1,
+        timestamp: Date.now(),
+        data: {
+          toolId: "tool-456",
+          toolName: "test_tool",
+          toolResult: "success",
+          success: true,
+        },
+      };
+
+      const key = coalescingKey(event);
+      expect(key).toBe("tool.complete:tool-456");
+    });
+
+    it("should generate different keys for different toolIds", () => {
+      const event1: BusEvent<"stream.tool.start"> = {
+        type: "stream.tool.start",
+        sessionId: "test-session",
+        runId: 1,
+        timestamp: Date.now(),
+        data: {
+          toolId: "tool-123",
+          toolName: "test_tool",
+          toolInput: {},
+        },
+      };
+
+      const event2: BusEvent<"stream.tool.start"> = {
+        type: "stream.tool.start",
+        sessionId: "test-session",
+        runId: 1,
+        timestamp: Date.now(),
+        data: {
+          toolId: "tool-456",
+          toolName: "test_tool",
+          toolInput: {},
+        },
+      };
+
+      const key1 = coalescingKey(event1);
+      const key2 = coalescingKey(event2);
+
+      expect(key1).toBe("tool.start:tool-123");
+      expect(key2).toBe("tool.start:tool-456");
+      expect(key1).not.toBe(key2);
+    });
+  });
+
+  describe("agent events", () => {
+    it("should return agent.update:${agentId} for stream.agent.update", () => {
+      const event: BusEvent<"stream.agent.update"> = {
+        type: "stream.agent.update",
+        sessionId: "test-session",
+        runId: 1,
+        timestamp: Date.now(),
+        data: {
+          agentId: "agent-789",
+          currentTool: "bash",
+          toolUses: 5,
+        },
+      };
+
+      const key = coalescingKey(event);
+      expect(key).toBe("agent.update:agent-789");
+    });
+
+    it("should return agent.start:${agentId} for stream.agent.start", () => {
+      const event: BusEvent<"stream.agent.start"> = {
+        type: "stream.agent.start",
+        sessionId: "test-session",
+        runId: 1,
+        timestamp: Date.now(),
+        data: {
+          agentId: "agent-999",
+          toolCallId: "agent-999",
+          agentType: "explore",
+          task: "Find files",
+          isBackground: false,
+        },
+      };
+
+      const key = coalescingKey(event);
+      expect(key).toBe("agent.start:agent-999");
+    });
+
+    it("should generate different keys for different agentIds", () => {
+      const event1: BusEvent<"stream.agent.update"> = {
+        type: "stream.agent.update",
+        sessionId: "test-session",
+        runId: 1,
+        timestamp: Date.now(),
+        data: {
+          agentId: "agent-111",
+          currentTool: "bash",
+        },
+      };
+
+      const event2: BusEvent<"stream.agent.update"> = {
+        type: "stream.agent.update",
+        sessionId: "test-session",
+        runId: 1,
+        timestamp: Date.now(),
+        data: {
+          agentId: "agent-222",
+          currentTool: "view",
+        },
+      };
+
+      const key1 = coalescingKey(event1);
+      const key2 = coalescingKey(event2);
+
+      expect(key1).toBe("agent.update:agent-111");
+      expect(key2).toBe("agent.update:agent-222");
+      expect(key1).not.toBe(key2);
+    });
+  });
+
+  describe("session events (each type gets unique key)", () => {
+    it("should return session.start:${sessionId} for stream.session.start", () => {
+      const event: BusEvent<"stream.session.start"> = {
+        type: "stream.session.start",
+        sessionId: "session-abc",
+        runId: 1,
+        timestamp: Date.now(),
+        data: {
+          config: { model: "gpt-4" },
+        },
+      };
+
+      const key = coalescingKey(event);
+      expect(key).toBe("session.start:session-abc");
+    });
+
+    it("should return session.idle:${sessionId} for stream.session.idle", () => {
+      const event: BusEvent<"stream.session.idle"> = {
+        type: "stream.session.idle",
+        sessionId: "session-xyz",
+        runId: 1,
+        timestamp: Date.now(),
+        data: {
+          reason: "waiting for input",
+        },
+      };
+
+      const key = coalescingKey(event);
+      expect(key).toBe("session.idle:session-xyz");
+    });
+
+    it("should return session.error:${sessionId} for stream.session.error", () => {
+      const event: BusEvent<"stream.session.error"> = {
+        type: "stream.session.error",
+        sessionId: "session-err",
+        runId: 1,
+        timestamp: Date.now(),
+        data: {
+          error: "Connection failed",
+          code: "ECONNREFUSED",
+        },
+      };
+
+      const key = coalescingKey(event);
+      expect(key).toBe("session.error:session-err");
+    });
+
+    it("should use different sessionIds for different sessions", () => {
+      const event1: BusEvent<"stream.session.start"> = {
+        type: "stream.session.start",
+        sessionId: "session-1",
+        runId: 1,
+        timestamp: Date.now(),
+        data: {},
+      };
+
+      const event2: BusEvent<"stream.session.start"> = {
+        type: "stream.session.start",
+        sessionId: "session-2",
+        runId: 1,
+        timestamp: Date.now(),
+        data: {},
+      };
+
+      const key1 = coalescingKey(event1);
+      const key2 = coalescingKey(event2);
+
+      expect(key1).toBe("session.start:session-1");
+      expect(key2).toBe("session.start:session-2");
+      expect(key1).not.toBe(key2);
+    });
+
+    it("should NOT coalesce session.start with session.idle", () => {
+      const start: BusEvent<"stream.session.start"> = {
+        type: "stream.session.start",
+        sessionId: "session-1",
+        runId: 1,
+        timestamp: Date.now(),
+        data: {},
+      };
+      const idle: BusEvent<"stream.session.idle"> = {
+        type: "stream.session.idle",
+        sessionId: "session-1",
+        runId: 1,
+        timestamp: Date.now(),
+        data: {},
+      };
+
+      expect(coalescingKey(start)).not.toBe(coalescingKey(idle));
+    });
+  });
+
+  describe("workflow events (return workflow.tasks:{workflowId})", () => {
+    it("should return workflow.tasks:${workflowId} for workflow.task.update", () => {
+      const event: BusEvent<"workflow.task.update"> = {
+        type: "workflow.task.update",
+        sessionId: "test-session",
+        runId: 1,
+        timestamp: Date.now(),
+        data: {
+          workflowId: "workflow-abc",
+          tasks: [
+            { id: "task-1", title: "First task", status: "pending" },
+            { id: "task-2", title: "Second task", status: "in_progress" },
+          ],
+        },
+      };
+
+      const key = coalescingKey(event);
+      expect(key).toBe("workflow.tasks:workflow-abc");
+    });
+
+    it("should generate different keys for different workflowIds", () => {
+      const event1: BusEvent<"workflow.task.update"> = {
+        type: "workflow.task.update",
+        sessionId: "test-session",
+        runId: 1,
+        timestamp: Date.now(),
+        data: {
+          workflowId: "workflow-1",
+          tasks: [],
+        },
+      };
+
+      const event2: BusEvent<"workflow.task.update"> = {
+        type: "workflow.task.update",
+        sessionId: "test-session",
+        runId: 1,
+        timestamp: Date.now(),
+        data: {
+          workflowId: "workflow-2",
+          tasks: [],
+        },
+      };
+
+      const key1 = coalescingKey(event1);
+      const key2 = coalescingKey(event2);
+
+      expect(key1).toBe("workflow.tasks:workflow-1");
+      expect(key2).toBe("workflow.tasks:workflow-2");
+      expect(key1).not.toBe(key2);
+    });
+  });
+
+  describe("usage events (return usage:{sessionId})", () => {
+    it("should return usage:${sessionId} for stream.usage", () => {
+      const event: BusEvent<"stream.usage"> = {
+        type: "stream.usage",
+        sessionId: "session-usage",
+        runId: 1,
+        timestamp: Date.now(),
+        data: {
+          inputTokens: 100,
+          outputTokens: 50,
+          model: "gpt-4",
+        },
+      };
+
+      const key = coalescingKey(event);
+      expect(key).toBe("usage:session-usage");
+    });
+
+    it("should use different sessionIds for different sessions", () => {
+      const event1: BusEvent<"stream.usage"> = {
+        type: "stream.usage",
+        sessionId: "session-1",
+        runId: 1,
+        timestamp: Date.now(),
+        data: {
+          inputTokens: 100,
+          outputTokens: 50,
+        },
+      };
+
+      const event2: BusEvent<"stream.usage"> = {
+        type: "stream.usage",
+        sessionId: "session-2",
+        runId: 1,
+        timestamp: Date.now(),
+        data: {
+          inputTokens: 200,
+          outputTokens: 100,
+        },
+      };
+
+      const key1 = coalescingKey(event1);
+      const key2 = coalescingKey(event2);
+
+      expect(key1).toBe("usage:session-1");
+      expect(key2).toBe("usage:session-2");
+      expect(key1).not.toBe(key2);
+    });
+  });
+
+  describe("text completion events (coalesce by messageId)", () => {
+    it("should return text.complete:${messageId} for stream.text.complete", () => {
+      const event: BusEvent<"stream.text.complete"> = {
+        type: "stream.text.complete",
+        sessionId: "test-session",
+        runId: 1,
+        timestamp: Date.now(),
+        data: {
+          messageId: "msg1",
+          fullText: "Complete message",
+        },
+      };
+
+      const key = coalescingKey(event);
+      expect(key).toBe("text.complete:msg1");
+    });
+
+    it("should generate different keys for different messageIds", () => {
+      const event1: BusEvent<"stream.text.complete"> = {
+        type: "stream.text.complete",
+        sessionId: "test-session",
+        runId: 1,
+        timestamp: Date.now(),
+        data: { messageId: "msg1", fullText: "First" },
+      };
+
+      const event2: BusEvent<"stream.text.complete"> = {
+        type: "stream.text.complete",
+        sessionId: "test-session",
+        runId: 1,
+        timestamp: Date.now(),
+        data: { messageId: "msg2", fullText: "Second" },
+      };
+
+      const key1 = coalescingKey(event1);
+      const key2 = coalescingKey(event2);
+
+      expect(key1).toBe("text.complete:msg1");
+      expect(key2).toBe("text.complete:msg2");
+      expect(key1).not.toBe(key2);
+    });
+  });
+
+  describe("unknown/unmapped events (return undefined)", () => {
+    it("should return undefined for stream.thinking.complete", () => {
+      const event: BusEvent<"stream.thinking.complete"> = {
+        type: "stream.thinking.complete",
+        sessionId: "test-session",
+        runId: 1,
+        timestamp: Date.now(),
+        data: {
+          sourceKey: "thinking-block-1",
+          durationMs: 1000,
+        },
+      };
+
+      const key = coalescingKey(event);
+      expect(key).toBeUndefined();
+    });
+
+    it("should return agent.complete:${agentId} for stream.agent.complete", () => {
+      const event: BusEvent<"stream.agent.complete"> = {
+        type: "stream.agent.complete",
+        sessionId: "test-session",
+        runId: 1,
+        timestamp: Date.now(),
+        data: {
+          agentId: "agent-123",
+          success: true,
+          result: "Task completed",
+        },
+      };
+
+      const key = coalescingKey(event);
+      expect(key).toBe("agent.complete:agent-123");
+    });
+
+    it("should return undefined for workflow.step.start", () => {
+      const event: BusEvent<"workflow.step.start"> = {
+        type: "workflow.step.start",
+        sessionId: "test-session",
+        runId: 1,
+        timestamp: Date.now(),
+        data: {
+          workflowId: "workflow-123",
+          nodeId: "node-1",
+          nodeName: "Step 1",
+        },
+      };
+
+      const key = coalescingKey(event);
+      expect(key).toBeUndefined();
+    });
+
+    it("should return undefined for workflow.step.complete", () => {
+      const event: BusEvent<"workflow.step.complete"> = {
+        type: "workflow.step.complete",
+        sessionId: "test-session",
+        runId: 1,
+        timestamp: Date.now(),
+        data: {
+          workflowId: "workflow-123",
+          nodeId: "node-1",
+          nodeName: "Step 1",
+          status: "success",
+          result: "Step completed",
+        },
+      };
+
+      const key = coalescingKey(event);
+      expect(key).toBeUndefined();
+    });
+
+    it("should return undefined for stream.permission.requested", () => {
+      const event: BusEvent<"stream.permission.requested"> = {
+        type: "stream.permission.requested",
+        sessionId: "test-session",
+        runId: 1,
+        timestamp: Date.now(),
+        data: {
+          requestId: "req-123",
+          toolName: "bash",
+          question: "Allow command execution?",
+          options: [
+            { label: "Allow", value: "allow" },
+            { label: "Deny", value: "deny" },
+          ],
+        },
+      };
+
+      const key = coalescingKey(event);
+      expect(key).toBeUndefined();
+    });
+
+    it("should return undefined for stream.human_input_required", () => {
+      const event: BusEvent<"stream.human_input_required"> = {
+        type: "stream.human_input_required",
+        sessionId: "test-session",
+        runId: 1,
+        timestamp: Date.now(),
+        data: {
+          requestId: "req-456",
+          question: "What should we do next?",
+          nodeId: "node-1",
+        },
+      };
+
+      const key = coalescingKey(event);
+      expect(key).toBeUndefined();
+    });
+
+    it("should return undefined for stream.skill.invoked", () => {
+      const event: BusEvent<"stream.skill.invoked"> = {
+        type: "stream.skill.invoked",
+        sessionId: "test-session",
+        runId: 1,
+        timestamp: Date.now(),
+        data: {
+          skillName: "custom_skill",
+          skillPath: "/path/to/skill.sh",
+        },
+      };
+
+      const key = coalescingKey(event);
+      expect(key).toBeUndefined();
+    });
+  });
+});
diff --git a/src/events/coalescing.ts b/src/events/coalescing.ts
new file mode 100644
index 0000000000..f645f3673d
--- /dev/null
+++ b/src/events/coalescing.ts
@@ -0,0 +1,69 @@
+import type { BusEvent, BusEventDataMap } from "./bus-events";
+
+/**
+ * Generate a coalescing key for an event. Events with the same key
+ * within a batching window will be coalesced (only latest retained).
+ * Returns undefined for events that must never be coalesced (e.g., text deltas).
+ */
+export function coalescingKey(event: BusEvent): string | undefined {
+  switch (event.type) {
+    // Text deltas are NEVER coalesced — each delta is additive
+    case "stream.text.delta":
+    case "stream.thinking.delta":
+      return undefined;
+
+    // Text completion coalesces by messageId — if duplicates arrive in the
+    // same batch window, only the latest (most accumulated text) is kept.
+    case "stream.text.complete": {
+      const data = event.data as BusEventDataMap["stream.text.complete"];
+      return `text.complete:${data.messageId}`;
+    }
+
+    // Tool/agent state updates coalesce by entity ID
+    case "stream.tool.start": {
+      const data = event.data as BusEventDataMap["stream.tool.start"];
+      return `tool.start:${data.toolId}`;
+    }
+    case "stream.tool.complete": {
+      const data = event.data as BusEventDataMap["stream.tool.complete"];
+      return `tool.complete:${data.toolId}`;
+    }
+    case "stream.agent.update": {
+      const data = event.data as BusEventDataMap["stream.agent.update"];
+      return `agent.update:${data.agentId}`;
+    }
+    case "stream.agent.start": {
+      const data = event.data as BusEventDataMap["stream.agent.start"];
+      return `agent.start:${data.agentId}`;
+    }
+    case "stream.agent.complete": {
+      const data = event.data as BusEventDataMap["stream.agent.complete"];
+      return `agent.complete:${data.agentId}`;
+    }
+
+    // Session status: each type gets its own key to prevent start being
+    // replaced by idle/error within the same batch window (which would
+    // prevent CorrelationService.startRun() from ever firing).
+    case "stream.session.start":
+      return `session.start:${event.sessionId}`;
+    case "stream.session.idle":
+      return `session.idle:${event.sessionId}`;
+    case "stream.session.error":
+      return `session.error:${event.sessionId}`;
+    case "stream.session.retry":
+      return `session.retry:${event.sessionId}`;
+
+    // Workflow task list coalesces per workflow
+    case "workflow.task.update": {
+      const data = event.data as BusEventDataMap["workflow.task.update"];
+      return `workflow.tasks:${data.workflowId}`;
+    }
+
+    // Usage stats coalesce per session
+    case "stream.usage":
+      return `usage:${event.sessionId}`;
+
+    default:
+      return undefined;
+  }
+}
diff --git a/src/events/consumers/correlation-service.test.ts b/src/events/consumers/correlation-service.test.ts
new file mode 100644
index 0000000000..edfe3e86da
--- /dev/null
+++ b/src/events/consumers/correlation-service.test.ts
@@ -0,0 +1,962 @@
+/**
+ * Unit tests for CorrelationService
+ *
+ * Tests the enrichment and correlation logic for tracking tool-agent relationships
+ * and enriching BusEvents with resolved metadata.
+ */
+
+import { test, expect, describe, beforeEach } from "bun:test";
+import { CorrelationService } from "./correlation-service.ts";
+import type { SubagentContext } from "./correlation-service.ts";
+import type { BusEvent } from "../bus-events.ts";
+
+describe("CorrelationService", () => {
+  let service: CorrelationService;
+
+  beforeEach(() => {
+    service = new CorrelationService();
+  });
+
+  test("enrich() returns enriched event with default metadata", () => {
+    const event: BusEvent = {
+      type: "stream.session.start",
+      sessionId: "session_123",
+      runId: 1,
+      timestamp: Date.now(),
+      data: {},
+    };
+
+    const enriched = service.enrich(event);
+
+    expect(enriched).toBeDefined();
+    expect(enriched.type).toBe("stream.session.start");
+    expect(enriched.resolvedToolId).toBeUndefined();
+    expect(enriched.resolvedAgentId).toBeUndefined();
+    expect(enriched.isSubagentTool).toBe(false);
+    expect(enriched.suppressFromMainChat).toBe(false);
+  });
+
+  test("stream.agent.start sets mainAgentId on first call", () => {
+    const event: BusEvent<"stream.agent.start"> = {
+      type: "stream.agent.start",
+      sessionId: "session_123",
+      runId: 1,
+      timestamp: Date.now(),
+      data: {
+        agentId: "agent_001",
+        toolCallId: "agent_001",
+        agentType: "general-purpose",
+        task: "Test task",
+        isBackground: false,
+      },
+    };
+
+    const enriched = service.enrich(event);
+
+    expect(enriched.resolvedAgentId).toBe("agent_001");
+    expect(enriched.isSubagentTool).toBe(false);
+  });
+
+  test("stream.tool.start resolves tool ID", () => {
+    // Start an agent first to set mainAgentId
+    const agentEvent: BusEvent<"stream.agent.start"> = {
+      type: "stream.agent.start",
+      sessionId: "session_123",
+      runId: 1,
+      timestamp: Date.now(),
+      data: {
+        agentId: "agent_001",
+        toolCallId: "agent_001",
+        agentType: "general-purpose",
+        task: "Test task",
+        isBackground: false,
+      },
+    };
+    service.enrich(agentEvent);
+
+    const toolStartEvent: BusEvent<"stream.tool.start"> = {
+      type: "stream.tool.start",
+      sessionId: "session_123",
+      runId: 1,
+      timestamp: Date.now(),
+      data: {
+        toolId: "tool_123",
+        toolName: "test_tool",
+        toolInput: { param: "value" },
+      },
+    };
+
+    const enriched = service.enrich(toolStartEvent);
+
+    expect(enriched.resolvedToolId).toBe("tool_123");
+    expect(enriched.resolvedAgentId).toBe("agent_001");
+  });
+
+  test("stream.tool.complete correlates with registered agent", () => {
+    // Register the tool
+    service.registerTool("tool_456", "agent_002", false);
+
+    const toolCompleteEvent: BusEvent<"stream.tool.complete"> = {
+      type: "stream.tool.complete",
+      sessionId: "session_123",
+      runId: 1,
+      timestamp: Date.now(),
+      data: {
+        toolId: "tool_456",
+        toolName: "test_tool",
+        toolResult: "Success",
+        success: true,
+      },
+    };
+
+    const enriched = service.enrich(toolCompleteEvent);
+
+    expect(enriched.resolvedToolId).toBe("tool_456");
+    expect(enriched.resolvedAgentId).toBe("agent_002");
+    expect(enriched.isSubagentTool).toBe(false);
+  });
+
+  test("registerTool() maps tool to agent", () => {
+    service.registerTool("tool_999", "agent_888", false);
+
+    const toolCompleteEvent: BusEvent<"stream.tool.complete"> = {
+      type: "stream.tool.complete",
+      sessionId: "session_123",
+      runId: 1,
+      timestamp: Date.now(),
+      data: {
+        toolId: "tool_999",
+        toolName: "test_tool",
+        toolResult: "Done",
+        success: true,
+      },
+    };
+
+    const enriched = service.enrich(toolCompleteEvent);
+
+    expect(enriched.resolvedAgentId).toBe("agent_888");
+    expect(enriched.isSubagentTool).toBe(false);
+  });
+
+  test("registerTool() with isSubagent=true marks sub-agent tools", () => {
+    service.registerTool("tool_sub", "agent_sub", true);
+
+    const toolCompleteEvent: BusEvent<"stream.tool.complete"> = {
+      type: "stream.tool.complete",
+      sessionId: "session_123",
+      runId: 1,
+      timestamp: Date.now(),
+      data: {
+        toolId: "tool_sub",
+        toolName: "sub_tool",
+        toolResult: "Done",
+        success: true,
+      },
+    };
+
+    const enriched = service.enrich(toolCompleteEvent);
+
+    expect(enriched.resolvedAgentId).toBe("agent_sub");
+    expect(enriched.isSubagentTool).toBe(true);
+  });
+
+  test("stream.text.delta resolves to main agent", () => {
+    // Set up main agent
+    const agentEvent: BusEvent<"stream.agent.start"> = {
+      type: "stream.agent.start",
+      sessionId: "session_123",
+      runId: 1,
+      timestamp: Date.now(),
+      data: {
+        agentId: "agent_main",
+        toolCallId: "agent_main",
+        agentType: "general-purpose",
+        task: "Main task",
+        isBackground: false,
+      },
+    };
+    service.enrich(agentEvent);
+
+    const textEvent: BusEvent<"stream.text.delta"> = {
+      type: "stream.text.delta",
+      sessionId: "session_123",
+      runId: 1,
+      timestamp: Date.now(),
+      data: {
+        delta: "Hello world",
+        messageId: "msg_001",
+      },
+    };
+
+    const enriched = service.enrich(textEvent);
+
+    expect(enriched.resolvedAgentId).toBe("agent_main");
+  });
+
+  test("reset() clears all state", () => {
+    // Set up state
+    const agentEvent: BusEvent<"stream.agent.start"> = {
+      type: "stream.agent.start",
+      sessionId: "session_123",
+      runId: 1,
+      timestamp: Date.now(),
+      data: {
+        agentId: "agent_123",
+        toolCallId: "agent_123",
+        agentType: "general-purpose",
+        task: "Test",
+        isBackground: false,
+      },
+    };
+    service.enrich(agentEvent);
+    service.registerTool("tool_abc", "agent_xyz", true);
+
+    // Reset
+    service.reset();
+
+    // Check that mainAgentId is cleared
+    const textEvent: BusEvent<"stream.text.delta"> = {
+      type: "stream.text.delta",
+      sessionId: "session_123",
+      runId: 1,
+      timestamp: Date.now(),
+      data: {
+        delta: "Text",
+        messageId: "msg_001",
+      },
+    };
+    const enriched = service.enrich(textEvent);
+    expect(enriched.resolvedAgentId).toBeUndefined();
+
+    // Check that tool mapping is cleared
+    const toolEvent: BusEvent<"stream.tool.complete"> = {
+      type: "stream.tool.complete",
+      sessionId: "session_123",
+      runId: 1,
+      timestamp: Date.now(),
+      data: {
+        toolId: "tool_abc",
+        toolName: "test_tool",
+        toolResult: "Result",
+        success: true,
+      },
+    };
+    const enrichedTool = service.enrich(toolEvent);
+    expect(enrichedTool.resolvedAgentId).toBeUndefined();
+    expect(enrichedTool.isSubagentTool).toBe(false);
+  });
+
+  test("Multiple agents — second agent doesn't overwrite mainAgentId", () => {
+    // First agent
+    const agent1Event: BusEvent<"stream.agent.start"> = {
+      type: "stream.agent.start",
+      sessionId: "session_123",
+      runId: 1,
+      timestamp: Date.now(),
+      data: {
+        agentId: "agent_001",
+        toolCallId: "agent_001",
+        agentType: "general-purpose",
+        task: "Main task",
+        isBackground: false,
+      },
+    };
+    service.enrich(agent1Event);
+
+    // Second agent (should not become mainAgentId)
+    const agent2Event: BusEvent<"stream.agent.start"> = {
+      type: "stream.agent.start",
+      sessionId: "session_123",
+      runId: 1,
+      timestamp: Date.now(),
+      data: {
+        agentId: "agent_002",
+        toolCallId: "agent_002",
+        agentType: "explore",
+        task: "Sub task",
+        isBackground: true,
+      },
+    };
+    service.enrich(agent2Event);
+
+    // Text event should still resolve to first agent
+    const textEvent: BusEvent<"stream.text.delta"> = {
+      type: "stream.text.delta",
+      sessionId: "session_123",
+      runId: 1,
+      timestamp: Date.now(),
+      data: {
+        delta: "Text",
+        messageId: "msg_001",
+      },
+    };
+    const enriched = service.enrich(textEvent);
+
+    expect(enriched.resolvedAgentId).toBe("agent_001");
+  });
+
+  test("Unknown event types get default enrichment", () => {
+    const event: BusEvent<"stream.usage"> = {
+      type: "stream.usage",
+      sessionId: "session_123",
+      runId: 1,
+      timestamp: Date.now(),
+      data: {
+        inputTokens: 100,
+        outputTokens: 50,
+        model: "gpt-4",
+      },
+    };
+
+    const enriched = service.enrich(event);
+
+    expect(enriched.type).toBe("stream.usage");
+    expect(enriched.resolvedToolId).toBeUndefined();
+    expect(enriched.resolvedAgentId).toBeUndefined();
+    expect(enriched.isSubagentTool).toBe(false);
+    expect(enriched.suppressFromMainChat).toBe(false);
+  });
+
+  test("startRun() sets activeRunId and ownedSessionIds", () => {
+    service.startRun(42, "session-abc");
+    expect(service.activeRunId).toBe(42);
+  });
+
+  test("startRun() resets previous state", () => {
+    // Set up some state
+    service.registerTool("tool-1", "agent-1");
+    service.startRun(1, "session-1");
+    
+    // After startRun, the previous tool registration should be cleared
+    const toolEvent: BusEvent<"stream.tool.complete"> = {
+      type: "stream.tool.complete",
+      sessionId: "session-1",
+      runId: 1,
+      timestamp: Date.now(),
+      data: { toolId: "tool-1", toolName: "test", toolResult: "", success: true },
+    };
+    const enriched = service.enrich(toolEvent);
+    expect(enriched.resolvedAgentId).toBeUndefined();
+  });
+
+  test("isOwnedEvent() returns true for matching runId", () => {
+    service.startRun(5, "session-x");
+    const event: BusEvent = {
+      type: "stream.text.delta",
+      sessionId: "session-other",
+      runId: 5,
+      timestamp: Date.now(),
+      data: { delta: "hi", messageId: "m1" },
+    };
+    expect(service.isOwnedEvent(event)).toBe(true);
+  });
+
+  test("isOwnedEvent() returns true for owned sessionId", () => {
+    service.startRun(5, "session-x");
+    const event: BusEvent = {
+      type: "stream.text.delta",
+      sessionId: "session-x",
+      runId: 999,
+      timestamp: Date.now(),
+      data: { delta: "hi", messageId: "m1" },
+    };
+    expect(service.isOwnedEvent(event)).toBe(true);
+  });
+
+  test("isOwnedEvent() returns false for unrelated event", () => {
+    service.startRun(5, "session-x");
+    const event: BusEvent = {
+      type: "stream.text.delta",
+      sessionId: "session-other",
+      runId: 99,
+      timestamp: Date.now(),
+      data: { delta: "hi", messageId: "m1" },
+    };
+    expect(service.isOwnedEvent(event)).toBe(false);
+  });
+
+  test("activeRunId is null initially", () => {
+    expect(service.activeRunId).toBeNull();
+  });
+
+  test("processBatch() enriches all events", () => {
+    const events: BusEvent[] = [
+      { type: "stream.text.delta", sessionId: "s1", runId: 1, timestamp: Date.now(), data: { delta: "a", messageId: "m1" } },
+      { type: "stream.text.delta", sessionId: "s1", runId: 1, timestamp: Date.now(), data: { delta: "b", messageId: "m1" } },
+    ];
+    const enriched = service.processBatch(events);
+    expect(enriched.length).toBe(2);
+    expect(enriched[0]).toHaveProperty("resolvedToolId");
+    expect(enriched[1]).toHaveProperty("isSubagentTool");
+  });
+
+  test("reset() clears run ownership state", () => {
+    service.startRun(10, "session-owned");
+    service.reset();
+    expect(service.activeRunId).toBeNull();
+    const event: BusEvent = {
+      type: "stream.text.delta",
+      sessionId: "session-owned",
+      runId: 10,
+      timestamp: Date.now(),
+      data: { delta: "hi", messageId: "m1" },
+    };
+    expect(service.isOwnedEvent(event)).toBe(false);
+  });
+
+  // --- Sub-agent Registry Tests ---
+
+  describe("registerSubagent / unregisterSubagent", () => {
+    const subagentContext: SubagentContext = {
+      parentAgentId: "parent_001",
+      workflowRunId: "wf_run_1",
+      nodeId: "planner",
+    };
+
+    test("registerSubagent stores context for enrichment", () => {
+      service.registerSubagent("sub_agent_1", subagentContext);
+
+      const event: BusEvent<"stream.agent.start"> = {
+        type: "stream.agent.start",
+        sessionId: "session_123",
+        runId: 1,
+        timestamp: Date.now(),
+        data: {
+          agentId: "sub_agent_1",
+          toolCallId: "sub_agent_1",
+          agentType: "task",
+          task: "Analyze code",
+          isBackground: false,
+        },
+      };
+
+      const enriched = service.enrich(event);
+
+      expect(enriched.resolvedAgentId).toBe("sub_agent_1");
+      expect(enriched.parentAgentId).toBe("parent_001");
+      expect(enriched.suppressFromMainChat).toBe(false);
+    });
+
+    test("unregisterSubagent removes context so enrichment no longer applies", () => {
+      service.registerSubagent("sub_agent_2", subagentContext);
+      service.unregisterSubagent("sub_agent_2");
+
+      const event: BusEvent<"stream.agent.start"> = {
+        type: "stream.agent.start",
+        sessionId: "session_123",
+        runId: 1,
+        timestamp: Date.now(),
+        data: {
+          agentId: "sub_agent_2",
+          toolCallId: "sub_agent_2",
+          agentType: "task",
+          task: "Write tests",
+          isBackground: false,
+        },
+      };
+
+      const enriched = service.enrich(event);
+
+      expect(enriched.resolvedAgentId).toBe("sub_agent_2");
+      expect(enriched.parentAgentId).toBeUndefined();
+    });
+
+    test("unregisterSubagent is safe for non-existent agentId", () => {
+      // Should not throw
+      service.unregisterSubagent("nonexistent_agent");
+    });
+  });
+
+  describe("sub-agent enrichment for agent lifecycle events", () => {
+    const subagentContext: SubagentContext = {
+      parentAgentId: "workflow_main",
+      workflowRunId: "wf_42",
+    };
+
+    test("stream.agent.start enriches with parentAgentId for registered sub-agent", () => {
+      service.registerSubagent("worker_1", subagentContext);
+
+      const event: BusEvent<"stream.agent.start"> = {
+        type: "stream.agent.start",
+        sessionId: "session_1",
+        runId: 1,
+        timestamp: Date.now(),
+        data: {
+          agentId: "worker_1",
+          toolCallId: "worker_1",
+          agentType: "explore",
+          task: "Research docs",
+          isBackground: true,
+        },
+      };
+
+      const enriched = service.enrich(event);
+
+      expect(enriched.resolvedAgentId).toBe("worker_1");
+      expect(enriched.parentAgentId).toBe("workflow_main");
+      expect(enriched.suppressFromMainChat).toBe(false);
+    });
+
+    test("stream.agent.update enriches with parentAgentId for registered sub-agent", () => {
+      service.registerSubagent("worker_2", subagentContext);
+
+      const event: BusEvent<"stream.agent.update"> = {
+        type: "stream.agent.update",
+        sessionId: "session_1",
+        runId: 1,
+        timestamp: Date.now(),
+        data: {
+          agentId: "worker_2",
+          currentTool: "read_file",
+          toolUses: 3,
+        },
+      };
+
+      const enriched = service.enrich(event);
+
+      expect(enriched.resolvedAgentId).toBe("worker_2");
+      expect(enriched.parentAgentId).toBe("workflow_main");
+      expect(enriched.suppressFromMainChat).toBe(false);
+    });
+
+    test("stream.agent.complete enriches with parentAgentId for registered sub-agent", () => {
+      service.registerSubagent("worker_3", subagentContext);
+
+      const event: BusEvent<"stream.agent.complete"> = {
+        type: "stream.agent.complete",
+        sessionId: "session_1",
+        runId: 1,
+        timestamp: Date.now(),
+        data: {
+          agentId: "worker_3",
+          success: true,
+          result: "Done",
+        },
+      };
+
+      const enriched = service.enrich(event);
+
+      expect(enriched.resolvedAgentId).toBe("worker_3");
+      expect(enriched.parentAgentId).toBe("workflow_main");
+      expect(enriched.suppressFromMainChat).toBe(false);
+    });
+
+    test("agent events for non-registered agents have no parentAgentId", () => {
+      const event: BusEvent<"stream.agent.update"> = {
+        type: "stream.agent.update",
+        sessionId: "session_1",
+        runId: 1,
+        timestamp: Date.now(),
+        data: {
+          agentId: "unregistered_agent",
+          currentTool: "bash",
+        },
+      };
+
+      const enriched = service.enrich(event);
+
+      expect(enriched.resolvedAgentId).toBe("unregistered_agent");
+      expect(enriched.parentAgentId).toBeUndefined();
+    });
+  });
+
+  describe("sub-agent enrichment for tool events", () => {
+    const subagentContext: SubagentContext = {
+      parentAgentId: "workflow_main",
+      workflowRunId: "wf_99",
+      nodeId: "coder",
+    };
+
+    test("stream.tool.start with parentAgentId matching registered sub-agent sets isSubagentTool", () => {
+      service.registerSubagent("sub_coder", subagentContext);
+
+      const event: BusEvent<"stream.tool.start"> = {
+        type: "stream.tool.start",
+        sessionId: "session_1",
+        runId: 1,
+        timestamp: Date.now(),
+        data: {
+          toolId: "tool_abc",
+          toolName: "edit_file",
+          toolInput: { path: "src/main.ts" },
+          parentAgentId: "sub_coder",
+        },
+      };
+
+      const enriched = service.enrich(event);
+
+      expect(enriched.resolvedToolId).toBe("tool_abc");
+      expect(enriched.resolvedAgentId).toBe("sub_coder");
+      expect(enriched.parentAgentId).toBe("workflow_main");
+      expect(enriched.isSubagentTool).toBe(true);
+      expect(enriched.suppressFromMainChat).toBe(false);
+    });
+
+    test("stream.tool.start with explicit parentAgentId still marks sub-agent scope before registry hydration", () => {
+      const event: BusEvent<"stream.tool.start"> = {
+        type: "stream.tool.start",
+        sessionId: "session_1",
+        runId: 1,
+        timestamp: Date.now(),
+        data: {
+          toolId: "tool_pre_registered",
+          toolName: "WebSearch",
+          toolInput: { query: "status" },
+          parentAgentId: "sub_unregistered",
+        },
+      };
+
+      const enriched = service.enrich(event);
+
+      expect(enriched.resolvedAgentId).toBe("sub_unregistered");
+      expect(enriched.parentAgentId).toBeUndefined();
+      expect(enriched.isSubagentTool).toBe(true);
+    });
+
+    test("stream.tool.start without parentAgentId falls back to mainAgentId", () => {
+      // Set up main agent
+      const agentEvent: BusEvent<"stream.agent.start"> = {
+        type: "stream.agent.start",
+        sessionId: "session_1",
+        runId: 1,
+        timestamp: Date.now(),
+        data: {
+          agentId: "main_agent",
+          toolCallId: "main_agent",
+          agentType: "general-purpose",
+          task: "Main task",
+          isBackground: false,
+        },
+      };
+      service.enrich(agentEvent);
+
+      const event: BusEvent<"stream.tool.start"> = {
+        type: "stream.tool.start",
+        sessionId: "session_1",
+        runId: 1,
+        timestamp: Date.now(),
+        data: {
+          toolId: "tool_def",
+          toolName: "bash",
+          toolInput: { command: "ls" },
+        },
+      };
+
+      const enriched = service.enrich(event);
+
+      expect(enriched.resolvedAgentId).toBe("main_agent");
+      expect(enriched.parentAgentId).toBeUndefined();
+      expect(enriched.isSubagentTool).toBe(false);
+    });
+
+    test("stream.tool.complete for tool owned by registered sub-agent sets parentAgentId", () => {
+      service.registerSubagent("sub_writer", {
+        parentAgentId: "workflow_main",
+        workflowRunId: "wf_77",
+      });
+      service.registerTool("tool_write_1", "sub_writer", false);
+
+      const event: BusEvent<"stream.tool.complete"> = {
+        type: "stream.tool.complete",
+        sessionId: "session_1",
+        runId: 1,
+        timestamp: Date.now(),
+        data: {
+          toolId: "tool_write_1",
+          toolName: "write_file",
+          toolResult: "Written",
+          success: true,
+        },
+      };
+
+      const enriched = service.enrich(event);
+
+      expect(enriched.resolvedToolId).toBe("tool_write_1");
+      expect(enriched.resolvedAgentId).toBe("sub_writer");
+      expect(enriched.parentAgentId).toBe("workflow_main");
+      expect(enriched.isSubagentTool).toBe(true);
+      expect(enriched.suppressFromMainChat).toBe(false);
+    });
+  });
+
+  describe("sub-agent registry cleanup", () => {
+    test("reset() clears the subagent registry", () => {
+      service.registerSubagent("sub_1", {
+        parentAgentId: "parent_1",
+        workflowRunId: "wf_1",
+      });
+      service.registerSubagent("sub_2", {
+        parentAgentId: "parent_1",
+        workflowRunId: "wf_1",
+      });
+
+      service.reset();
+
+      // After reset, registered sub-agents should no longer enrich events
+      const event: BusEvent<"stream.agent.start"> = {
+        type: "stream.agent.start",
+        sessionId: "session_1",
+        runId: 1,
+        timestamp: Date.now(),
+        data: {
+          agentId: "sub_1",
+          toolCallId: "sub_1",
+          agentType: "task",
+          task: "Test",
+          isBackground: false,
+        },
+      };
+
+      const enriched = service.enrich(event);
+      expect(enriched.parentAgentId).toBeUndefined();
+    });
+
+    test("startRun() clears the subagent registry via reset()", () => {
+      service.registerSubagent("sub_old", {
+        parentAgentId: "old_parent",
+        workflowRunId: "wf_old",
+      });
+
+      service.startRun(100, "new_session");
+
+      const event: BusEvent<"stream.agent.update"> = {
+        type: "stream.agent.update",
+        sessionId: "new_session",
+        runId: 100,
+        timestamp: Date.now(),
+        data: {
+          agentId: "sub_old",
+          currentTool: "bash",
+        },
+      };
+
+      const enriched = service.enrich(event);
+      expect(enriched.parentAgentId).toBeUndefined();
+    });
+  });
+
+  describe("sub-agent registry does not break existing behavior", () => {
+    test("non-sub-agent events still enrich correctly with no registry entries", () => {
+      // Main agent start
+      const agentEvent: BusEvent<"stream.agent.start"> = {
+        type: "stream.agent.start",
+        sessionId: "session_1",
+        runId: 1,
+        timestamp: Date.now(),
+        data: {
+          agentId: "main_agent",
+          toolCallId: "main_agent",
+          agentType: "general-purpose",
+          task: "Chat",
+          isBackground: false,
+        },
+      };
+      const agentEnriched = service.enrich(agentEvent);
+      expect(agentEnriched.resolvedAgentId).toBe("main_agent");
+      expect(agentEnriched.parentAgentId).toBeUndefined();
+
+      // Tool registration and completion
+      service.registerTool("tool_1", "main_agent", false);
+      const toolEvent: BusEvent<"stream.tool.complete"> = {
+        type: "stream.tool.complete",
+        sessionId: "session_1",
+        runId: 1,
+        timestamp: Date.now(),
+        data: {
+          toolId: "tool_1",
+          toolName: "read",
+          toolResult: "content",
+          success: true,
+        },
+      };
+      const toolEnriched = service.enrich(toolEvent);
+      expect(toolEnriched.resolvedAgentId).toBe("main_agent");
+      expect(toolEnriched.isSubagentTool).toBe(false);
+      expect(toolEnriched.parentAgentId).toBeUndefined();
+
+      // Text delta
+      const textEvent: BusEvent<"stream.text.delta"> = {
+        type: "stream.text.delta",
+        sessionId: "session_1",
+        runId: 1,
+        timestamp: Date.now(),
+        data: { delta: "Hello", messageId: "msg_1" },
+      };
+      const textEnriched = service.enrich(textEvent);
+      expect(textEnriched.resolvedAgentId).toBe("main_agent");
+      expect(textEnriched.parentAgentId).toBeUndefined();
+    });
+
+    test("multiple sub-agents can be registered simultaneously", () => {
+      service.registerSubagent("worker_a", {
+        parentAgentId: "orchestrator",
+        workflowRunId: "wf_multi",
+        nodeId: "step_1",
+      });
+      service.registerSubagent("worker_b", {
+        parentAgentId: "orchestrator",
+        workflowRunId: "wf_multi",
+        nodeId: "step_2",
+      });
+
+      const eventA: BusEvent<"stream.agent.start"> = {
+        type: "stream.agent.start",
+        sessionId: "s1",
+        runId: 1,
+        timestamp: Date.now(),
+        data: { agentId: "worker_a", toolCallId: "worker_a", agentType: "task", task: "A", isBackground: false },
+      };
+      const eventB: BusEvent<"stream.agent.start"> = {
+        type: "stream.agent.start",
+        sessionId: "s1",
+        runId: 1,
+        timestamp: Date.now(),
+        data: { agentId: "worker_b", toolCallId: "worker_b", agentType: "task", task: "B", isBackground: false },
+      };
+
+      const enrichedA = service.enrich(eventA);
+      const enrichedB = service.enrich(eventB);
+
+      expect(enrichedA.parentAgentId).toBe("orchestrator");
+      expect(enrichedB.parentAgentId).toBe("orchestrator");
+      expect(enrichedA.resolvedAgentId).toBe("worker_a");
+      expect(enrichedB.resolvedAgentId).toBe("worker_b");
+    });
+  });
+
+  // --------------------------------------------------------------------------
+  // Sub-agent text-complete suppression
+  // --------------------------------------------------------------------------
+
+  describe("sub-agent text-complete suppression", () => {
+    test("stream.text.complete with subagent- messageId is suppressed", () => {
+      service.registerSubagent("worker-1", { parentAgentId: "main-agent", workflowRunId: "run-1" });
+
+      const event: BusEvent<"stream.text.complete"> = {
+        type: "stream.text.complete",
+        sessionId: "session_123",
+        runId: 1,
+        timestamp: Date.now(),
+        data: { messageId: "subagent-worker-1", fullText: "done" },
+      };
+
+      const enriched = service.enrich(event);
+      expect(enriched.suppressFromMainChat).toBe(true);
+      expect(enriched.resolvedAgentId).toBe("worker-1");
+      expect(enriched.parentAgentId).toBe("main-agent");
+    });
+
+    test("stream.text.complete without subagent- prefix is NOT suppressed", () => {
+      const agentStartEvent: BusEvent<"stream.agent.start"> = {
+        type: "stream.agent.start",
+        sessionId: "session_123",
+        runId: 1,
+        timestamp: Date.now(),
+        data: { agentId: "main-agent", toolCallId: "main-agent", agentType: "chat", task: "test", isBackground: false },
+      };
+      service.enrich(agentStartEvent);
+
+      const event: BusEvent<"stream.text.complete"> = {
+        type: "stream.text.complete",
+        sessionId: "session_123",
+        runId: 1,
+        timestamp: Date.now(),
+        data: { messageId: "msg-123", fullText: "done" },
+      };
+
+      const enriched = service.enrich(event);
+      expect(enriched.suppressFromMainChat).toBe(false);
+      expect(enriched.resolvedAgentId).toBe("main-agent");
+    });
+  });
+
+  // --------------------------------------------------------------------------
+  // Sub-agent tool registration in toolToAgent map
+  // --------------------------------------------------------------------------
+
+  describe("sub-agent tool ID registration on stream.tool.start", () => {
+    test("registers tool in toolToAgent so stream.tool.complete resolves agent", () => {
+      service.registerSubagent("worker-1", { parentAgentId: "main-agent", workflowRunId: "run-1" });
+
+      const toolStartEvent: BusEvent<"stream.tool.start"> = {
+        type: "stream.tool.start",
+        sessionId: "session_123",
+        runId: 1,
+        timestamp: Date.now(),
+        data: {
+          toolId: "tool-abc",
+          toolName: "grep",
+          toolInput: {},
+          parentAgentId: "worker-1",
+        },
+      };
+      service.enrich(toolStartEvent);
+
+      // Now stream.tool.complete should resolve the agent
+      const toolCompleteEvent: BusEvent<"stream.tool.complete"> = {
+        type: "stream.tool.complete",
+        sessionId: "session_123",
+        runId: 1,
+        timestamp: Date.now(),
+        data: {
+          toolId: "tool-abc",
+          toolName: "grep",
+          toolResult: "found",
+          success: true,
+        },
+      };
+      const enriched = service.enrich(toolCompleteEvent);
+      expect(enriched.resolvedAgentId).toBe("worker-1");
+      expect(enriched.isSubagentTool).toBe(true);
+      expect(enriched.parentAgentId).toBe("main-agent");
+    });
+
+    test("registers fallback-attributed tool so stream.tool.complete inherits resolvedAgentId", () => {
+      const agentStartEvent: BusEvent<"stream.agent.start"> = {
+        type: "stream.agent.start",
+        sessionId: "session_123",
+        runId: 1,
+        timestamp: Date.now(),
+        data: {
+          agentId: "background-agent-1",
+          toolCallId: "spawn-tool-1",
+          agentType: "codebase-online-researcher",
+          task: "Research task",
+          isBackground: true,
+        },
+      };
+      service.enrich(agentStartEvent);
+
+      const toolStartEvent: BusEvent<"stream.tool.start"> = {
+        type: "stream.tool.start",
+        sessionId: "session_123",
+        runId: 1,
+        timestamp: Date.now(),
+        data: {
+          toolId: "tool-bg-1",
+          toolName: "WebSearch",
+          toolInput: { query: "test" },
+        },
+      };
+
+      const startEnriched = service.enrich(toolStartEvent);
+      expect(startEnriched.resolvedAgentId).toBe("background-agent-1");
+
+      const toolCompleteEvent: BusEvent<"stream.tool.complete"> = {
+        type: "stream.tool.complete",
+        sessionId: "session_123",
+        runId: 1,
+        timestamp: Date.now(),
+        data: {
+          toolId: "tool-bg-1",
+          toolName: "WebSearch",
+          toolResult: "done",
+          success: true,
+        },
+      };
+
+      const completeEnriched = service.enrich(toolCompleteEvent);
+      expect(completeEnriched.resolvedAgentId).toBe("background-agent-1");
+    });
+  });
+});
diff --git a/src/events/consumers/correlation-service.ts b/src/events/consumers/correlation-service.ts
new file mode 100644
index 0000000000..5f325fd511
--- /dev/null
+++ b/src/events/consumers/correlation-service.ts
@@ -0,0 +1,457 @@
+/**
+ * Correlation Service for Event Enrichment
+ *
+ * This module implements the CorrelationService class that enriches BusEvents
+ * with correlation metadata. It tracks tool-to-agent mappings and distinguishes
+ * sub-agent tools from main agent tools.
+ *
+ * The CorrelationService replaces the correlation logic previously embedded in
+ * the monolithic subscribeToToolEvents() function in src/ui/index.ts.
+ *
+ * Key responsibilities:
+ * - Enrich BusEvents with resolvedToolId, resolvedAgentId, and isSubagentTool flags
+ * - Track tool-to-agent relationships for attribution
+ * - Maintain state across streaming events
+ * - Support reset() for cleanup between runs
+ *
+ * Usage:
+ * ```typescript
+ * const correlationService = new CorrelationService();
+ *
+ * // Register tools as they start
+ * correlationService.registerTool("tool_123", "agent_456", false);
+ *
+ * // Enrich events before processing
+ * const enriched = correlationService.enrich(busEvent);
+ *
+ * // Reset state between streaming sessions
+ * correlationService.reset();
+ * ```
+ */
+
+import type { BusEvent, EnrichedBusEvent, BusEventDataMap } from "../bus-events.ts";
+
+/**
+ * Context for a registered sub-agent, mapping it to its parent workflow agent.
+ */
+export interface SubagentContext {
+  /** The parent agent ID that spawned this sub-agent */
+  parentAgentId: string;
+  /** The workflow run ID this sub-agent belongs to */
+  workflowRunId: string;
+  /** The graph node ID this sub-agent is executing within (optional) */
+  nodeId?: string;
+}
+
+/**
+ * Service for enriching BusEvents with correlation metadata.
+ *
+ * The CorrelationService maintains mappings between tools and agents,
+ * and enriches each event with resolved identifiers and flags that
+ * determine how the event should be processed and displayed.
+ *
+ * The service tracks:
+ * - Tool-to-agent mappings (which agent spawned which tool)
+ * - Sub-agent tool set (tools belonging to sub-agents vs. main agent)
+ * - Main agent ID (the primary agent driving the session)
+ *
+ * Enriched events include:
+ * - resolvedToolId: The tool invocation ID associated with this event
+ * - resolvedAgentId: The agent ID associated with this event
+ * - isSubagentTool: Whether this tool belongs to a sub-agent
+ * - suppressFromMainChat: Whether to hide this event in the main UI
+ */
+export class CorrelationService {
+  /**
+   * Maps tool IDs to their parent agent IDs.
+   * Used to attribute tool events to the correct agent.
+   */
+  private toolToAgent = new Map<string, string>();
+
+  /**
+   * Set of tool IDs that belong to sub-agents (not the main chat agent).
+   * These tools are displayed in the parallel agents tree and suppressed
+   * from the main chat UI to avoid duplicate display.
+   */
+  private subAgentTools = new Set<string>();
+
+  /**
+   * Current main agent ID (if any).
+   * The main agent is the first agent started in a streaming session.
+   * Subsequent agents are considered sub-agents.
+   */
+  private mainAgentId: string | null = null;
+
+  /**
+   * Active run ID for this correlation service instance.
+   * Set via startRun() to track which run this service is processing.
+   */
+  private _activeRunId: number | null = null;
+
+  /**
+   * Set of session IDs that this service owns.
+   * Events from these sessions are considered "owned" by this service.
+   */
+  private ownedSessionIds = new Set<string>();
+
+  /**
+   * Maps tool IDs to their run IDs.
+   * Populated when processing stream.tool.start events.
+   */
+  private toolIdToRunMap = new Map<string, number>();
+
+  /**
+   * Maps sub-agent agentId to parent context.
+   * Used to attribute events from workflow sub-agents to their parent agent.
+   */
+  private subagentRegistry = new Map<string, SubagentContext>();
+
+  /**
+   * Enrich a BusEvent with correlation metadata.
+   *
+   * This method takes a raw BusEvent from the event bus and enriches it
+   * with correlation information based on the service's internal tracking state.
+   *
+   * The enrichment process:
+   * 1. Copies the original event properties
+   * 2. Adds correlation fields (resolvedToolId, resolvedAgentId, etc.)
+   * 3. Determines if the event belongs to a sub-agent
+   * 4. Calculates suppression flags for UI filtering
+   *
+   * @param event - The raw BusEvent to enrich
+   * @returns An EnrichedBusEvent with correlation metadata
+   */
+  enrich(event: BusEvent): EnrichedBusEvent {
+    // Start with a copy of the event and initialize enrichment fields
+    const enriched: EnrichedBusEvent = {
+      ...event,
+      resolvedToolId: undefined,
+      resolvedAgentId: undefined,
+      parentAgentId: undefined,
+      isSubagentTool: false,
+      suppressFromMainChat: false,
+    };
+
+    // Enrich based on event type
+    switch (event.type) {
+      case "stream.agent.start": {
+        const data = event.data as BusEventDataMap["stream.agent.start"];
+
+        // First agent started becomes the main agent
+        if (!this.mainAgentId) {
+          this.mainAgentId = data.agentId;
+        }
+
+        enriched.resolvedAgentId = data.agentId;
+
+        // Check if this agent is a registered sub-agent
+        const agentCtx = this.subagentRegistry.get(data.agentId);
+        if (agentCtx) {
+          enriched.parentAgentId = agentCtx.parentAgentId;
+          enriched.suppressFromMainChat = false;
+        }
+        break;
+      }
+
+      case "stream.agent.update": {
+        const data = event.data as BusEventDataMap["stream.agent.update"];
+        enriched.resolvedAgentId = data.agentId;
+
+        // Check if this agent is a registered sub-agent
+        const updateCtx = this.subagentRegistry.get(data.agentId);
+        if (updateCtx) {
+          enriched.parentAgentId = updateCtx.parentAgentId;
+          enriched.suppressFromMainChat = false;
+        }
+        break;
+      }
+
+      case "stream.agent.complete": {
+        const data = event.data as BusEventDataMap["stream.agent.complete"];
+        enriched.resolvedAgentId = data.agentId;
+
+        // Check if this agent is a registered sub-agent
+        const completeCtx = this.subagentRegistry.get(data.agentId);
+        if (completeCtx) {
+          enriched.parentAgentId = completeCtx.parentAgentId;
+          enriched.suppressFromMainChat = false;
+        }
+        break;
+      }
+
+      case "stream.tool.start": {
+        const data = event.data as BusEventDataMap["stream.tool.start"];
+        enriched.resolvedToolId = data.toolId;
+
+        // Track which run this tool belongs to
+        this.toolIdToRunMap.set(data.toolId, event.runId);
+
+        // If the event is explicitly scoped to a sub-agent, attribute to it.
+        // Some adapters provide parentAgentId even when the sub-agent was not
+        // pre-registered in correlation; still preserve the attribution.
+        if (data.parentAgentId) {
+          enriched.resolvedAgentId = data.parentAgentId;
+          // Explicit parentAgentId on tool events indicates sub-agent scoping
+          // even before the sub-agent lifecycle is fully registered.
+          enriched.isSubagentTool = true;
+          const toolSubCtx = this.subagentRegistry.get(data.parentAgentId);
+          if (toolSubCtx) {
+            enriched.parentAgentId = toolSubCtx.parentAgentId;
+            enriched.suppressFromMainChat = false;
+          }
+        }
+
+        // If we know which agent spawned this tool, correlate it
+        // For tools without explicit agent correlation, use the main agent
+        if (!enriched.resolvedAgentId && this.mainAgentId) {
+          enriched.resolvedAgentId = this.mainAgentId;
+        }
+
+        // Persist start-time attribution so stream.tool.complete can resolve
+        // even when the completion event omits agent correlation fields.
+        if (enriched.resolvedAgentId) {
+          this.toolToAgent.set(data.toolId, enriched.resolvedAgentId);
+          if (enriched.isSubagentTool) {
+            this.subAgentTools.add(data.toolId);
+          }
+        }
+        break;
+      }
+
+      case "stream.tool.complete": {
+        const data = event.data as BusEventDataMap["stream.tool.complete"];
+        enriched.resolvedToolId = data.toolId;
+
+        // Look up which agent owns this tool
+        const agentId = this.toolToAgent.get(data.toolId);
+        if (agentId) {
+          enriched.resolvedAgentId = agentId;
+          enriched.isSubagentTool = this.subAgentTools.has(data.toolId);
+
+          // Check if the owning agent is a registered sub-agent
+          const completeToolCtx = this.subagentRegistry.get(agentId);
+          if (completeToolCtx) {
+            enriched.parentAgentId = completeToolCtx.parentAgentId;
+            enriched.isSubagentTool = true;
+            enriched.suppressFromMainChat = false;
+          }
+        } else if (data.parentAgentId) {
+          // Best-effort fallback for adapters that only emit parentAgentId on complete.
+          enriched.resolvedAgentId = data.parentAgentId;
+          enriched.isSubagentTool = true;
+          const completeToolCtx = this.subagentRegistry.get(data.parentAgentId);
+          if (completeToolCtx) {
+            enriched.parentAgentId = completeToolCtx.parentAgentId;
+            enriched.suppressFromMainChat = false;
+          }
+        }
+        break;
+      }
+
+      case "stream.text.delta": {
+        const textDeltaData = event.data as BusEventDataMap["stream.text.delta"];
+        // Check if agentId maps to a registered sub-agent
+        if (textDeltaData.agentId) {
+          const subCtx = this.subagentRegistry.get(textDeltaData.agentId);
+          if (subCtx) {
+            enriched.resolvedAgentId = textDeltaData.agentId;
+            enriched.parentAgentId = subCtx.parentAgentId;
+            break;
+          }
+        }
+        enriched.resolvedAgentId = this.mainAgentId ?? undefined;
+        break;
+      }
+
+      case "stream.text.complete": {
+        const textCompleteData = event.data as BusEventDataMap["stream.text.complete"];
+        // Sub-agent text-complete events must not trigger main stream completion.
+        // Detect by messageId prefix set by SubagentStreamAdapter.
+        if (textCompleteData.messageId?.startsWith("subagent-")) {
+          const subAgentId = textCompleteData.messageId.slice("subagent-".length);
+          const subCtx = this.subagentRegistry.get(subAgentId);
+          if (subCtx) {
+            enriched.resolvedAgentId = subAgentId;
+            enriched.parentAgentId = subCtx.parentAgentId;
+          }
+          enriched.suppressFromMainChat = true;
+        } else {
+          enriched.resolvedAgentId = this.mainAgentId ?? undefined;
+        }
+        break;
+      }
+
+      case "stream.thinking.delta": {
+        const thinkingData = event.data as BusEventDataMap["stream.thinking.delta"];
+        if (thinkingData.agentId) {
+          const subCtx = this.subagentRegistry.get(thinkingData.agentId);
+          if (subCtx) {
+            enriched.resolvedAgentId = thinkingData.agentId;
+            enriched.parentAgentId = subCtx.parentAgentId;
+            break;
+          }
+        }
+        enriched.resolvedAgentId = this.mainAgentId ?? undefined;
+        break;
+      }
+
+      case "stream.usage": {
+        const usageData = event.data as BusEventDataMap["stream.usage"];
+        if (usageData.agentId) {
+          const subCtx = this.subagentRegistry.get(usageData.agentId);
+          if (subCtx) {
+            enriched.resolvedAgentId = usageData.agentId;
+            enriched.parentAgentId = subCtx.parentAgentId;
+            break;
+          }
+        }
+        enriched.resolvedAgentId = this.mainAgentId ?? undefined;
+        break;
+      }
+
+      // For other event types, leave enrichment fields as undefined
+      // The consumer can handle them as appropriate
+      default:
+        break;
+    }
+
+    return enriched;
+  }
+
+  /**
+   * Register a tool as belonging to an agent.
+   *
+   * This method establishes the correlation between a tool invocation
+   * and the agent that spawned it. It should be called when a tool.start
+   * event is processed and the agent context is known.
+   *
+   * @param toolId - The unique tool invocation ID
+   * @param agentId - The agent ID that spawned this tool
+   * @param isSubagent - Whether this tool belongs to a sub-agent (default: false)
+   */
+  registerTool(toolId: string, agentId: string, isSubagent = false): void {
+    this.toolToAgent.set(toolId, agentId);
+
+    if (isSubagent) {
+      this.subAgentTools.add(toolId);
+    }
+  }
+
+  /**
+   * Register a sub-agent with its parent context.
+   *
+   * This enables the correlation service to attribute events from workflow
+   * sub-agents to their parent agent and workflow run. When events with
+   * the registered agentId are processed, the enrichment will include
+   * parentAgentId and workflowRunId from the provided context.
+   *
+   * @param agentId - The unique sub-agent ID to register
+   * @param context - Parent context including parentAgentId, workflowRunId, and optional nodeId
+   */
+  registerSubagent(agentId: string, context: SubagentContext): void {
+    this.subagentRegistry.set(agentId, context);
+  }
+
+  /**
+   * Unregister a sub-agent from the registry.
+   *
+   * Should be called when a sub-agent completes or is aborted to clean up
+   * the registry entry. Events from the unregistered agentId will no longer
+   * receive parent context enrichment.
+   *
+   * @param agentId - The sub-agent ID to unregister
+   */
+  unregisterSubagent(agentId: string): void {
+    this.subagentRegistry.delete(agentId);
+  }
+
+  /**
+   * Start tracking a new run.
+   *
+   * This method sets the active run ID and adds the session ID to the
+   * set of owned sessions. It also calls reset() to clear any previous
+   * run state (tool mappings, agent IDs, etc.).
+   *
+   * @param runId - The run ID to start tracking
+   * @param sessionId - The session ID associated with this run
+   */
+  startRun(runId: number, sessionId: string): void {
+    this.reset();
+    this._activeRunId = runId;
+    this.ownedSessionIds.add(sessionId);
+  }
+
+  /**
+   * Add a session ID to the set of owned sessions without resetting state.
+   *
+   * Unlike startRun() which clears all state, this method only adds the
+   * session ID to the ownership set. Use this to register additional sessions
+   * (e.g., parent sessions for workflow sub-agents) that should be recognized
+   * by isOwnedEvent().
+   *
+   * @param sessionId - The session ID to add to the owned set
+   */
+  addOwnedSession(sessionId: string): void {
+    this.ownedSessionIds.add(sessionId);
+  }
+
+  /**
+   * Check if an event is owned by this service.
+   *
+   * An event is considered "owned" if:
+   * - Its runId matches the active run ID, OR
+   * - Its sessionId is in the set of owned session IDs
+   *
+   * @param event - The event to check
+   * @returns true if the event is owned by this service
+   */
+  isOwnedEvent(event: BusEvent): boolean {
+    return (
+      event.runId === this._activeRunId ||
+      this.ownedSessionIds.has(event.sessionId)
+    );
+  }
+
+  /**
+   * Get the active run ID.
+   *
+   * @returns The active run ID, or null if no run is active
+   */
+  get activeRunId(): number | null {
+    return this._activeRunId;
+  }
+
+  /**
+   * Process a batch of events.
+   *
+   * This method enriches all events in the batch by calling enrich()
+   * on each event.
+   *
+   * @param events - The batch of events to process
+   * @returns An array of enriched events
+   */
+  processBatch(events: BusEvent[]): EnrichedBusEvent[] {
+    return events.map(e => this.enrich(e));
+  }
+
+  /**
+   * Reset all correlation state (call between runs).
+   *
+   * This method clears all internal tracking state, preparing the service
+   * for a new streaming session. It should be called:
+   * - Before starting a new streaming session
+   * - When switching conversations
+   * - On error recovery
+   *
+   * After reset(), the service behaves as if it was freshly instantiated.
+   */
+  reset(): void {
+    this.toolToAgent.clear();
+    this.subAgentTools.clear();
+    this.mainAgentId = null;
+    this._activeRunId = null;
+    this.ownedSessionIds.clear();
+    this.toolIdToRunMap.clear();
+    this.subagentRegistry.clear();
+  }
+}
diff --git a/src/events/consumers/echo-suppressor.test.ts b/src/events/consumers/echo-suppressor.test.ts
new file mode 100644
index 0000000000..75f35c5ef0
--- /dev/null
+++ b/src/events/consumers/echo-suppressor.test.ts
@@ -0,0 +1,217 @@
+/**
+ * Unit tests for EchoSuppressor
+ *
+ * Tests the echo suppression logic that filters duplicate text echoed back
+ * by SDKs when tool results are repeated in the text stream.
+ */
+
+import { test, expect, describe, beforeEach } from "bun:test";
+import { EchoSuppressor } from "./echo-suppressor.ts";
+
+describe("EchoSuppressor", () => {
+  let suppressor: EchoSuppressor;
+
+  beforeEach(() => {
+    suppressor = new EchoSuppressor();
+  });
+
+  test("filterDelta() returns delta when no targets", () => {
+    const delta = "Hello world";
+    const result = suppressor.filterDelta(delta);
+
+    expect(result).toBe("Hello world");
+  });
+
+  test("expectEcho() registers a target", () => {
+    suppressor.expectEcho("Expected text");
+
+    expect(suppressor.hasPendingTargets).toBe(true);
+  });
+
+  test("filterDelta() suppresses matching text", () => {
+    suppressor.expectEcho("Tool result: success");
+
+    // Send matching text in chunks
+    expect(suppressor.filterDelta("Tool ")).toBe("");
+    expect(suppressor.filterDelta("result: ")).toBe("");
+    expect(suppressor.filterDelta("success")).toBe("");
+
+    // After full match, no more pending targets
+    expect(suppressor.hasPendingTargets).toBe(false);
+  });
+
+  test("filterDelta() returns accumulated text when divergence detected", () => {
+    suppressor.expectEcho("Expected text");
+
+    // Start matching
+    expect(suppressor.filterDelta("Expe")).toBe("");
+    expect(suppressor.filterDelta("cted ")).toBe("");
+
+    // Diverge
+    const result = suppressor.filterDelta("something else");
+
+    // Should return all accumulated text including the divergent part
+    expect(result).toBe("Expected something else");
+    expect(suppressor.hasPendingTargets).toBe(false);
+  });
+
+  test("Multiple targets processed in FIFO order", () => {
+    suppressor.expectEcho("First echo");
+    suppressor.expectEcho("Second echo");
+
+    // Process first echo
+    expect(suppressor.filterDelta("First echo")).toBe("");
+    expect(suppressor.hasPendingTargets).toBe(true);
+
+    // Process second echo
+    expect(suppressor.filterDelta("Second echo")).toBe("");
+    expect(suppressor.hasPendingTargets).toBe(false);
+  });
+
+  test("reset() clears all targets", () => {
+    suppressor.expectEcho("Some text");
+    expect(suppressor.hasPendingTargets).toBe(true);
+
+    suppressor.reset();
+
+    expect(suppressor.hasPendingTargets).toBe(false);
+
+    // New deltas should pass through
+    expect(suppressor.filterDelta("Any text")).toBe("Any text");
+  });
+
+  test("hasPendingTargets returns correct state", () => {
+    expect(suppressor.hasPendingTargets).toBe(false);
+
+    suppressor.expectEcho("Target text");
+    expect(suppressor.hasPendingTargets).toBe(true);
+
+    suppressor.filterDelta("Target text");
+    expect(suppressor.hasPendingTargets).toBe(false);
+  });
+
+  test("Partial match accumulates without returning", () => {
+    suppressor.expectEcho("Complete match");
+
+    // Partial matches - nothing returned
+    expect(suppressor.filterDelta("Com")).toBe("");
+    expect(suppressor.filterDelta("plete")).toBe("");
+    expect(suppressor.filterDelta(" mat")).toBe("");
+
+    // Still has pending target being matched
+    expect(suppressor.hasPendingTargets).toBe(true);
+  });
+
+  test("Full match consumes target and moves to next", () => {
+    suppressor.expectEcho("First");
+    suppressor.expectEcho("Second");
+
+    // Complete first match
+    expect(suppressor.filterDelta("First")).toBe("");
+    expect(suppressor.hasPendingTargets).toBe(true);
+
+    // Now processing second target
+    expect(suppressor.filterDelta("Second")).toBe("");
+    expect(suppressor.hasPendingTargets).toBe(false);
+  });
+
+  test("Empty string delta returns empty string", () => {
+    suppressor.expectEcho("Some target");
+
+    expect(suppressor.filterDelta("")).toBe("");
+    expect(suppressor.hasPendingTargets).toBe(true);
+  });
+
+  test("Empty target is not registered", () => {
+    suppressor.expectEcho("");
+    expect(suppressor.hasPendingTargets).toBe(false);
+
+    suppressor.expectEcho("   ");
+    expect(suppressor.hasPendingTargets).toBe(false);
+  });
+
+  test("Complex scenario: multiple targets with divergence", () => {
+    suppressor.expectEcho("Echo one");
+    suppressor.expectEcho("Echo two");
+
+    // Match first target
+    expect(suppressor.filterDelta("Echo one")).toBe("");
+    expect(suppressor.hasPendingTargets).toBe(true);
+
+    // Start matching second target
+    expect(suppressor.filterDelta("Echo ")).toBe("");
+
+    // Diverge from second target
+    const result = suppressor.filterDelta("three");
+    expect(result).toBe("Echo three");
+    expect(suppressor.hasPendingTargets).toBe(false);
+  });
+
+  test("Single character deltas", () => {
+    suppressor.expectEcho("abc");
+
+    expect(suppressor.filterDelta("a")).toBe("");
+    expect(suppressor.filterDelta("b")).toBe("");
+    expect(suppressor.filterDelta("c")).toBe("");
+    expect(suppressor.hasPendingTargets).toBe(false);
+  });
+
+  test("Multi-line echo suppression", () => {
+    const multilineResult = "Line 1\nLine 2\nLine 3";
+    suppressor.expectEcho(multilineResult);
+
+    // Send line by line
+    expect(suppressor.filterDelta("Line 1\n")).toBe("");
+    expect(suppressor.filterDelta("Line 2\n")).toBe("");
+    expect(suppressor.filterDelta("Line 3")).toBe("");
+    expect(suppressor.hasPendingTargets).toBe(false);
+  });
+
+  test("Divergence with empty accumulator edge case", () => {
+    suppressor.expectEcho("Expected");
+
+    // Immediate divergence on first character
+    const result = suppressor.filterDelta("Different");
+    expect(result).toBe("Different");
+    expect(suppressor.hasPendingTargets).toBe(false);
+  });
+
+  test("Target consumed exactly - no overflow", () => {
+    suppressor.expectEcho("exact");
+
+    expect(suppressor.filterDelta("exact")).toBe("");
+    expect(suppressor.hasPendingTargets).toBe(false);
+
+    // Next delta should pass through (no active target)
+    expect(suppressor.filterDelta(" more")).toBe(" more");
+  });
+
+  test("Multiple expectations with text between", () => {
+    suppressor.expectEcho("First");
+
+    // Match first
+    expect(suppressor.filterDelta("First")).toBe("");
+
+    // Add second target after first is consumed
+    suppressor.expectEcho("Second");
+
+    // Text that's not an echo
+    expect(suppressor.filterDelta("Some other text ")).toBe("Some other text ");
+
+    // No pending targets left after divergence
+    expect(suppressor.hasPendingTargets).toBe(false);
+  });
+
+  test("Whitespace-only target is not registered", () => {
+    suppressor.expectEcho("\t\n  ");
+    expect(suppressor.hasPendingTargets).toBe(false);
+  });
+
+  test("Case-sensitive matching", () => {
+    suppressor.expectEcho("Hello");
+
+    const result = suppressor.filterDelta("hello");
+    expect(result).toBe("hello");
+    expect(suppressor.hasPendingTargets).toBe(false);
+  });
+});
diff --git a/src/events/consumers/echo-suppressor.ts b/src/events/consumers/echo-suppressor.ts
new file mode 100644
index 0000000000..b92700ce42
--- /dev/null
+++ b/src/events/consumers/echo-suppressor.ts
@@ -0,0 +1,93 @@
+/**
+ * Echo Suppression Service
+ *
+ * Filters duplicate text that appears when SDKs echo tool results
+ * back as part of the assistant's text stream. This replaces the
+ * inline echo suppression logic previously in handleStreamMessage().
+ *
+ * The suppressor maintains a FIFO queue of expected echo targets.
+ * When a tool completes, its result text is registered as an expected echo.
+ * Subsequent text deltas are checked against the accumulated text;
+ * if the text matches an expected echo prefix, it is suppressed.
+ */
+export class EchoSuppressor {
+    private suppressTargets: string[] = [];  // FIFO queue of expected echoes
+    private accumulator = "";  // Accumulated text being checked against targets
+    private activeTarget: string | null = null;  // Currently matching target
+
+    /**
+     * Register a tool result that may be echoed by the SDK.
+     * @param resultText - The tool result text to watch for
+     */
+    expectEcho(resultText: string): void {
+        if (resultText.trim().length > 0) {
+            this.suppressTargets.push(resultText);
+        }
+    }
+
+    /**
+     * Filter a text delta, returning the non-echoed portion.
+     * Returns empty string if the entire delta is suppressed.
+     * Returns the full delta if no echo is detected.
+     *
+     * @param delta - Text delta to filter
+     * @returns Filtered delta (may be empty if fully suppressed)
+     */
+    filterDelta(delta: string): string {
+        if (this.suppressTargets.length === 0 && this.activeTarget === null) {
+            return delta;
+        }
+
+        // If we don't have an active target, try the next one from the queue
+        if (this.activeTarget === null && this.suppressTargets.length > 0) {
+            this.activeTarget = this.suppressTargets.shift()!;
+            this.accumulator = "";
+        }
+
+        if (this.activeTarget === null) {
+            return delta;
+        }
+
+        // Append delta to accumulator and check against target
+        this.accumulator += delta;
+
+        // If accumulator exactly prefixes or matches the target, suppress
+        if (this.activeTarget.startsWith(this.accumulator)) {
+            // Still accumulating — full delta is suppressed
+            if (this.accumulator.length === this.activeTarget.length) {
+                // Complete match — echo fully consumed
+                this.activeTarget = null;
+                this.accumulator = "";
+            }
+            return "";
+        }
+
+        // Accumulator diverged from target — not an echo
+        // Return the full accumulated text (it was not an echo after all)
+        const result = this.accumulator;
+        this.activeTarget = null;
+        this.accumulator = "";
+        // We already consumed previous deltas that were part of accumulator
+        // but those were returned as "" previously, so we need to return the
+        // accumulated text minus the current delta (which hasn't been returned yet)
+        // Actually, the accumulator includes all previously suppressed deltas + current delta.
+        // Since previous deltas were suppressed (returned ""), we need to return ALL accumulated text.
+        return result;
+    }
+
+    /**
+     * Reset all suppression state. Called on stream end, error, or abort.
+     */
+    reset(): void {
+        this.suppressTargets = [];
+        this.accumulator = "";
+        this.activeTarget = null;
+    }
+
+    /**
+     * Check if there are any pending suppression targets.
+     */
+    get hasPendingTargets(): boolean {
+        return this.suppressTargets.length > 0 || this.activeTarget !== null;
+    }
+}
diff --git a/src/events/consumers/stream-pipeline-consumer.test.ts b/src/events/consumers/stream-pipeline-consumer.test.ts
new file mode 100644
index 0000000000..4b32c80ae4
--- /dev/null
+++ b/src/events/consumers/stream-pipeline-consumer.test.ts
@@ -0,0 +1,650 @@
+/**
+ * Tests for StreamPipelineConsumer
+ */
+
+import { describe, it, expect, beforeEach } from "bun:test";
+import { StreamPipelineConsumer } from "./stream-pipeline-consumer.ts";
+import { CorrelationService } from "./correlation-service.ts";
+import { EchoSuppressor } from "./echo-suppressor.ts";
+import type { EnrichedBusEvent } from "../bus-events.ts";
+import type { StreamPartEvent } from "../../ui/parts/stream-pipeline.ts";
+
+describe("StreamPipelineConsumer", () => {
+  let correlation: CorrelationService;
+  let echoSuppressor: EchoSuppressor;
+  let consumer: StreamPipelineConsumer;
+  let receivedEvents: StreamPartEvent[] = [];
+
+  beforeEach(() => {
+    correlation = new CorrelationService();
+    echoSuppressor = new EchoSuppressor();
+    consumer = new StreamPipelineConsumer(correlation, echoSuppressor);
+    receivedEvents = [];
+    consumer.onStreamParts((events) => {
+      receivedEvents.push(...events);
+    });
+  });
+
+  it("should map stream.text.delta to text-delta event", () => {
+    const event: EnrichedBusEvent = {
+      type: "stream.text.delta",
+      sessionId: "test",
+      runId: 1,
+      timestamp: Date.now(),
+      data: { delta: "Hello ", messageId: "msg1" },
+    };
+
+    consumer.processBatch([event]);
+
+    expect(receivedEvents).toHaveLength(1);
+    expect(receivedEvents[0]).toEqual({
+      type: "text-delta",
+      delta: "Hello ",
+    });
+  });
+
+  it("should filter text deltas through echo suppressor", () => {
+    // Register an expected echo
+    echoSuppressor.expectEcho("Hello World");
+
+    const event: EnrichedBusEvent = {
+      type: "stream.text.delta",
+      sessionId: "test",
+      runId: 1,
+      timestamp: Date.now(),
+      data: { delta: "Hello ", messageId: "msg1" },
+    };
+
+    consumer.processBatch([event]);
+
+    // Should be suppressed (empty)
+    expect(receivedEvents).toHaveLength(0);
+  });
+
+  it("does not suppress agent-scoped text deltas", () => {
+    echoSuppressor.expectEcho("agent text");
+
+    const event: EnrichedBusEvent = {
+      type: "stream.text.delta",
+      sessionId: "test",
+      runId: 1,
+      timestamp: Date.now(),
+      data: { delta: "agent text", messageId: "msg1", agentId: "agent_1" },
+    };
+
+    consumer.processBatch([event]);
+
+    expect(receivedEvents).toHaveLength(1);
+    expect(receivedEvents[0]).toEqual({
+      type: "text-delta",
+      delta: "agent text",
+      agentId: "agent_1",
+    });
+  });
+
+  it("should map stream.thinking.delta to thinking-meta event", () => {
+    const event: EnrichedBusEvent = {
+      type: "stream.thinking.delta",
+      sessionId: "test",
+      runId: 1,
+      timestamp: Date.now(),
+      data: { delta: "Thinking...", sourceKey: "block1", messageId: "msg1" },
+    };
+
+    consumer.processBatch([event]);
+
+    expect(receivedEvents).toHaveLength(1);
+    expect(receivedEvents[0]).toMatchObject({
+      type: "thinking-meta",
+      thinkingSourceKey: "block1",
+      targetMessageId: "msg1",
+      thinkingText: "Thinking...",
+    });
+  });
+
+  it("coalesces adjacent thinking deltas with same source", () => {
+    const events: EnrichedBusEvent[] = [
+      {
+        type: "stream.thinking.delta",
+        sessionId: "test",
+        runId: 1,
+        timestamp: Date.now(),
+        data: { delta: "Thinking", sourceKey: "block1", messageId: "msg1" },
+      },
+      {
+        type: "stream.thinking.delta",
+        sessionId: "test",
+        runId: 1,
+        timestamp: Date.now(),
+        data: { delta: "...", sourceKey: "block1", messageId: "msg1" },
+      },
+    ];
+
+    consumer.processBatch(events);
+
+    expect(receivedEvents).toHaveLength(1);
+    expect(receivedEvents[0]).toMatchObject({
+      type: "thinking-meta",
+      thinkingSourceKey: "block1",
+      targetMessageId: "msg1",
+      thinkingText: "Thinking...",
+    });
+  });
+
+  it("should map stream.thinking.delta agentId to thinking-meta agentId", () => {
+    const event: EnrichedBusEvent = {
+      type: "stream.thinking.delta",
+      sessionId: "test",
+      runId: 1,
+      timestamp: Date.now(),
+      data: { delta: "Thinking...", sourceKey: "block1", messageId: "msg1", agentId: "agent_1" },
+    };
+
+    consumer.processBatch([event]);
+
+    expect(receivedEvents).toHaveLength(1);
+    expect(receivedEvents[0]).toMatchObject({
+      type: "thinking-meta",
+      thinkingSourceKey: "block1",
+      targetMessageId: "msg1",
+      thinkingText: "Thinking...",
+      agentId: "agent_1",
+    });
+  });
+
+  it("should map stream.tool.start to tool-start event", () => {
+    const event: EnrichedBusEvent = {
+      type: "stream.tool.start",
+      sessionId: "test",
+      runId: 1,
+      timestamp: Date.now(),
+      data: { toolId: "tool1", toolName: "bash", toolInput: { command: "ls" } },
+    };
+
+    consumer.processBatch([event]);
+
+    expect(receivedEvents).toHaveLength(1);
+    expect(receivedEvents[0]).toEqual({
+      type: "tool-start",
+      toolId: "tool1",
+      toolName: "bash",
+      input: { command: "ls" },
+    });
+  });
+
+  it("uses resolvedAgentId for stream.tool.start when event is sub-agent scoped", () => {
+    const event: EnrichedBusEvent = {
+      type: "stream.tool.start",
+      sessionId: "test",
+      runId: 1,
+      timestamp: Date.now(),
+      resolvedAgentId: "subagent_1",
+      isSubagentTool: true,
+      data: { toolId: "tool1", toolName: "bash", toolInput: { command: "ls" } },
+    };
+
+    consumer.processBatch([event]);
+
+    expect(receivedEvents).toHaveLength(1);
+    expect(receivedEvents[0]).toEqual({
+      type: "tool-start",
+      toolId: "tool1",
+      toolName: "bash",
+      input: { command: "ls" },
+      agentId: "subagent_1",
+    });
+  });
+
+  it("does not use resolvedAgentId for stream.tool.start when event is not sub-agent scoped", () => {
+    const event: EnrichedBusEvent = {
+      type: "stream.tool.start",
+      sessionId: "test",
+      runId: 1,
+      timestamp: Date.now(),
+      resolvedAgentId: "agent_misfire",
+      isSubagentTool: false,
+      data: { toolId: "tool1", toolName: "TaskOutput", toolInput: { task_id: "abc" } },
+    };
+
+    consumer.processBatch([event]);
+
+    expect(receivedEvents).toHaveLength(1);
+    expect(receivedEvents[0]).toEqual({
+      type: "tool-start",
+      toolId: "tool1",
+      toolName: "TaskOutput",
+      input: { task_id: "abc" },
+    });
+  });
+
+  it("should map stream.tool.complete to tool-complete event", () => {
+    const event: EnrichedBusEvent = {
+      type: "stream.tool.complete",
+      sessionId: "test",
+      runId: 1,
+      timestamp: Date.now(),
+      data: {
+        toolId: "tool1",
+        toolName: "bash",
+        toolResult: "file1.txt\nfile2.txt",
+        success: true,
+      },
+    };
+
+    consumer.processBatch([event]);
+
+    expect(receivedEvents).toHaveLength(1);
+    expect(receivedEvents[0]).toEqual({
+      type: "tool-complete",
+      toolId: "tool1",
+      toolName: "bash",
+      output: "file1.txt\nfile2.txt",
+      success: true,
+      error: undefined,
+    });
+  });
+
+  it("uses resolvedAgentId for stream.tool.complete when event is sub-agent scoped", () => {
+    const event: EnrichedBusEvent = {
+      type: "stream.tool.complete",
+      sessionId: "test",
+      runId: 1,
+      timestamp: Date.now(),
+      resolvedAgentId: "subagent_1",
+      isSubagentTool: true,
+      data: {
+        toolId: "tool1",
+        toolName: "bash",
+        toolResult: "ok",
+        success: true,
+      },
+    };
+
+    consumer.processBatch([event]);
+
+    expect(receivedEvents).toHaveLength(1);
+    expect(receivedEvents[0]).toEqual({
+      type: "tool-complete",
+      toolId: "tool1",
+      toolName: "bash",
+      output: "ok",
+      success: true,
+      error: undefined,
+      agentId: "subagent_1",
+    });
+  });
+
+  it("does not use resolvedAgentId for stream.tool.complete when event is not sub-agent scoped", () => {
+    const event: EnrichedBusEvent = {
+      type: "stream.tool.complete",
+      sessionId: "test",
+      runId: 1,
+      timestamp: Date.now(),
+      resolvedAgentId: "agent_misfire",
+      isSubagentTool: false,
+      data: {
+        toolId: "tool1",
+        toolName: "TaskOutput",
+        toolResult: { retrieval_status: "running" },
+        success: true,
+      },
+    };
+
+    consumer.processBatch([event]);
+
+    expect(receivedEvents).toHaveLength(1);
+    expect(receivedEvents[0]).toEqual({
+      type: "tool-complete",
+      toolId: "tool1",
+      toolName: "TaskOutput",
+      output: { retrieval_status: "running" },
+      success: true,
+      error: undefined,
+    });
+  });
+
+  it("suppresses main-stream text echoes after TaskOutput completion", () => {
+    const events: EnrichedBusEvent[] = [
+      {
+        type: "stream.tool.complete",
+        sessionId: "test",
+        runId: 1,
+        timestamp: Date.now(),
+        data: {
+          toolId: "taskoutput-1",
+          toolName: "TaskOutput",
+          toolResult: { result: "sub-agent final output" },
+          success: true,
+        },
+      },
+      {
+        type: "stream.text.delta",
+        sessionId: "test",
+        runId: 1,
+        timestamp: Date.now(),
+        data: {
+          delta: "sub-agent final output",
+          messageId: "msg1",
+        },
+      },
+    ];
+
+    consumer.processBatch(events);
+
+    expect(receivedEvents).toHaveLength(1);
+    expect(receivedEvents[0]).toEqual({
+      type: "tool-complete",
+      toolId: "taskoutput-1",
+      toolName: "TaskOutput",
+      output: { result: "sub-agent final output" },
+      success: true,
+      error: undefined,
+    });
+  });
+
+  it("coalesces adjacent text deltas within a batch", () => {
+    const events: EnrichedBusEvent[] = [
+      {
+        type: "stream.text.delta",
+        sessionId: "test",
+        runId: 1,
+        timestamp: Date.now(),
+        data: { delta: "Hello ", messageId: "msg1" },
+      },
+      {
+        type: "stream.text.delta",
+        sessionId: "test",
+        runId: 1,
+        timestamp: Date.now(),
+        data: { delta: "World", messageId: "msg1" },
+      },
+    ];
+
+    consumer.processBatch(events);
+
+    expect(receivedEvents).toHaveLength(1);
+    expect(receivedEvents[0]?.type).toBe("text-delta");
+    if (receivedEvents[0]?.type === "text-delta") {
+      expect(receivedEvents[0].delta).toBe("Hello World");
+    }
+  });
+
+  it("does not coalesce text deltas across non-text boundaries", () => {
+    const events: EnrichedBusEvent[] = [
+      {
+        type: "stream.text.delta",
+        sessionId: "test",
+        runId: 1,
+        timestamp: Date.now(),
+        data: { delta: "Hello ", messageId: "msg1" },
+      },
+      {
+        type: "stream.tool.start",
+        sessionId: "test",
+        runId: 1,
+        timestamp: Date.now(),
+        data: { toolId: "tool1", toolName: "bash", toolInput: { command: "ls" } },
+      },
+      {
+        type: "stream.text.delta",
+        sessionId: "test",
+        runId: 1,
+        timestamp: Date.now(),
+        data: { delta: "World", messageId: "msg1" },
+      },
+    ];
+
+    consumer.processBatch(events);
+
+    expect(receivedEvents).toHaveLength(3);
+    expect(receivedEvents[0]?.type).toBe("text-delta");
+    expect(receivedEvents[1]?.type).toBe("tool-start");
+    expect(receivedEvents[2]?.type).toBe("text-delta");
+  });
+
+  it("should map stream.text.complete to text-complete event", () => {
+    const event: EnrichedBusEvent = {
+      type: "stream.text.complete",
+      sessionId: "test",
+      runId: 1,
+      timestamp: Date.now(),
+      data: { messageId: "msg1", fullText: "Hello World" },
+    };
+
+    consumer.processBatch([event]);
+
+    expect(receivedEvents).toHaveLength(1);
+    expect(receivedEvents[0]).toEqual({
+      type: "text-complete",
+      fullText: "Hello World",
+      messageId: "msg1",
+    });
+  });
+
+  it("should map workflow.step.start to workflow-step-start event", () => {
+    const event: EnrichedBusEvent = {
+      type: "workflow.step.start",
+      sessionId: "test",
+      runId: 1,
+      timestamp: Date.now(),
+      data: { workflowId: "wf1", nodeId: "node1", nodeName: "Planner" },
+    };
+
+    consumer.processBatch([event]);
+
+    expect(receivedEvents).toHaveLength(1);
+    expect(receivedEvents[0]).toEqual({
+      type: "workflow-step-start",
+      workflowId: "wf1",
+      nodeId: "node1",
+      nodeName: "Planner",
+      startedAt: new Date(event.timestamp).toISOString(),
+    });
+  });
+
+  it("should map workflow.step.complete to workflow-step-complete event", () => {
+    const event: EnrichedBusEvent = {
+      type: "workflow.step.complete",
+      sessionId: "test",
+      runId: 1,
+      timestamp: Date.now(),
+      data: { workflowId: "wf1", nodeId: "node1", nodeName: "Planner", status: "success" },
+    };
+
+    consumer.processBatch([event]);
+
+    expect(receivedEvents).toHaveLength(1);
+    expect(receivedEvents[0]).toEqual({
+      type: "workflow-step-complete",
+      workflowId: "wf1",
+      nodeId: "node1",
+      nodeName: "Planner",
+      status: "success",
+      completedAt: new Date(event.timestamp).toISOString(),
+    });
+  });
+
+  it("should map workflow.task.update to task-list-update event", () => {
+    const event: EnrichedBusEvent = {
+      type: "workflow.task.update",
+      sessionId: "test",
+      runId: 1,
+      timestamp: Date.now(),
+      data: {
+        workflowId: "wf1",
+        tasks: [
+          { id: "t1", title: "Plan", status: "complete", blockedBy: [] },
+          { id: "t2", title: "Implement", status: "pending" },
+        ],
+      },
+    };
+
+    consumer.processBatch([event]);
+
+    expect(receivedEvents).toHaveLength(1);
+    expect(receivedEvents[0]).toEqual({
+      type: "task-list-update",
+      tasks: [
+        { id: "t1", title: "Plan", status: "complete", blockedBy: [] },
+        { id: "t2", title: "Implement", status: "pending" },
+      ],
+    });
+  });
+
+  it("should map workflow task result envelopes to task-result-upsert events", () => {
+    const event: EnrichedBusEvent = {
+      type: "workflow.task.update",
+      sessionId: "test",
+      runId: 1,
+      timestamp: Date.now(),
+      data: {
+        workflowId: "wf1",
+        tasks: [
+          {
+            id: "t1",
+            title: "Plan",
+            status: "completed",
+            taskResult: {
+              task_id: "#1",
+              tool_name: "task",
+              title: "Plan",
+              status: "completed",
+              output_text: "done",
+              envelope_text: "task_id: #1",
+              metadata: {
+                sessionId: "session-1",
+              },
+            },
+          },
+        ],
+      },
+    };
+
+    consumer.processBatch([event]);
+
+    expect(receivedEvents).toHaveLength(2);
+    expect(receivedEvents[0]).toEqual({
+      type: "task-list-update",
+      tasks: [
+        {
+          id: "t1",
+          title: "Plan",
+          status: "completed",
+        },
+      ],
+    });
+    expect(receivedEvents[1]).toEqual({
+      type: "task-result-upsert",
+      envelope: {
+        task_id: "#1",
+        tool_name: "task",
+        title: "Plan",
+        status: "completed",
+        output_text: "done",
+        envelope_text: "task_id: #1",
+        metadata: {
+          sessionId: "session-1",
+        },
+      },
+    });
+  });
+
+  it("should map stream.tool.partial_result to tool-partial-result event", () => {
+    const event: EnrichedBusEvent = {
+      type: "stream.tool.partial_result",
+      sessionId: "test",
+      runId: 1,
+      timestamp: Date.now(),
+      data: { toolCallId: "tool1", partialOutput: "partial output line\n" },
+    };
+
+    consumer.processBatch([event]);
+
+    expect(receivedEvents).toHaveLength(1);
+    expect(receivedEvents[0]).toEqual({
+      type: "tool-partial-result",
+      toolId: "tool1",
+      partialOutput: "partial output line\n",
+    });
+  });
+
+  it("maps stream.tool.partial_result agent attribution when parentAgentId is present", () => {
+    const event: EnrichedBusEvent = {
+      type: "stream.tool.partial_result",
+      sessionId: "test",
+      runId: 1,
+      timestamp: Date.now(),
+      data: {
+        toolCallId: "tool1",
+        partialOutput: "line\n",
+        parentAgentId: "subagent_1",
+      },
+    };
+
+    consumer.processBatch([event]);
+
+    expect(receivedEvents).toHaveLength(1);
+    expect(receivedEvents[0]).toEqual({
+      type: "tool-partial-result",
+      toolId: "tool1",
+      partialOutput: "line\n",
+      agentId: "subagent_1",
+    });
+  });
+
+  it("should ignore unmapped event types", () => {
+    const event: EnrichedBusEvent = {
+      type: "stream.session.start",
+      sessionId: "test",
+      runId: 1,
+      timestamp: Date.now(),
+      data: {},
+    };
+
+    consumer.processBatch([event]);
+
+    expect(receivedEvents).toHaveLength(0);
+  });
+
+  it("should support callback unsubscribe", () => {
+    const unsubscribe = consumer.onStreamParts((events) => {
+      receivedEvents.push(...events);
+    });
+
+    unsubscribe();
+
+    const event: EnrichedBusEvent = {
+      type: "stream.text.delta",
+      sessionId: "test",
+      runId: 1,
+      timestamp: Date.now(),
+      data: { delta: "Test", messageId: "msg1" },
+    };
+
+    consumer.processBatch([event]);
+
+    // Should not receive events after unsubscribe
+    expect(receivedEvents).toHaveLength(0);
+  });
+
+  it("should reset state on reset()", () => {
+    // Setup some state
+    const event: EnrichedBusEvent = {
+      type: "stream.text.delta",
+      sessionId: "test",
+      runId: 1,
+      timestamp: Date.now(),
+      data: { delta: "Test", messageId: "msg1" },
+    };
+
+    consumer.processBatch([event]);
+    expect(receivedEvents).toHaveLength(1);
+
+    // Reset
+    consumer.reset();
+
+    // Echo suppressor and correlation should be reset (tested in their own tests)
+    // This test just verifies reset() doesn't throw
+    expect(() => consumer.reset()).not.toThrow();
+  });
+});
diff --git a/src/events/consumers/stream-pipeline-consumer.ts b/src/events/consumers/stream-pipeline-consumer.ts
new file mode 100644
index 0000000000..b523c0e304
--- /dev/null
+++ b/src/events/consumers/stream-pipeline-consumer.ts
@@ -0,0 +1,385 @@
+/**
+ * Stream Pipeline Consumer
+ *
+ * Transforms enriched BusEvents into StreamPartEvents for the UI reducer.
+ * This consumer bridges the new event bus architecture with the existing
+ * streaming UI pipeline (applyStreamPartEvent reducer).
+ *
+ * Key responsibilities:
+ * - Map BusEvents to StreamPartEvents
+ * - Apply echo suppression to text deltas
+ * - Batch events and deliver via callback
+ * - Support reset() for cleanup between runs
+ *
+ * Usage:
+ * ```typescript
+ * const consumer = new StreamPipelineConsumer(correlationService, echoSuppressor);
+ *
+ * // Register callback to receive batched StreamPartEvents
+ * const unsubscribe = consumer.onStreamParts((events) => {
+ *   for (const event of events) {
+ *     message = applyStreamPartEvent(message, event);
+ *   }
+ * });
+ *
+ * // Process a batch of BusEvents from BatchDispatcher
+ * consumer.processBatch(enrichedEvents);
+ *
+ * // Cleanup
+ * unsubscribe();
+ * consumer.reset();
+ * ```
+ */
+
+import type { EnrichedBusEvent, BusEventDataMap } from "../bus-events.ts";
+import type { CorrelationService } from "./correlation-service.ts";
+import type { EchoSuppressor } from "./echo-suppressor.ts";
+import type { StreamPartEvent } from "../../ui/parts/stream-pipeline.ts";
+import { pipelineLog } from "../pipeline-logger.ts";
+
+function isTaskOutputToolName(toolName: string): boolean {
+  return toolName.trim().toLowerCase() === "taskoutput";
+}
+
+function normalizeTaskOutputText(value: string): string | undefined {
+  const normalized = value.replace(/\r\n?/g, "\n").trim();
+  return normalized.length > 0 ? normalized : undefined;
+}
+
+function extractTaskOutputEchoText(toolResult: unknown): string | undefined {
+  if (typeof toolResult === "string") {
+    const trimmed = toolResult.trim();
+    if (trimmed.length === 0) {
+      return undefined;
+    }
+    try {
+      const parsed = JSON.parse(toolResult);
+      return extractTaskOutputEchoText(parsed);
+    } catch {
+      return normalizeTaskOutputText(toolResult);
+    }
+  }
+
+  if (!toolResult || typeof toolResult !== "object") {
+    return undefined;
+  }
+
+  const record = toolResult as Record<string, unknown>;
+  const directText = [record.result, record.text, record.output]
+    .find((candidate) => typeof candidate === "string" && candidate.trim().length > 0);
+  if (typeof directText === "string") {
+    return normalizeTaskOutputText(directText);
+  }
+
+  if (Array.isArray(record.content)) {
+    const textBlocks = record.content
+      .map((entry) => {
+        if (!entry || typeof entry !== "object") {
+          return undefined;
+        }
+        const entryRecord = entry as Record<string, unknown>;
+        if (entryRecord.type === "text" && typeof entryRecord.text === "string") {
+          return entryRecord.text;
+        }
+        return undefined;
+      })
+      .filter((text): text is string => typeof text === "string" && text.trim().length > 0);
+    if (textBlocks.length > 0) {
+      return normalizeTaskOutputText(textBlocks.join("\n"));
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Callback type for receiving batches of StreamPartEvents.
+ *
+ * This callback is invoked once per frame flush with all the StreamPartEvents
+ * that were mapped from the BusEvents in that batch.
+ */
+export type StreamPartEventCallback = (events: StreamPartEvent[]) => void;
+
+/**
+ * Consumer that transforms BusEvents into StreamPartEvents.
+ *
+ * This class is responsible for:
+ * 1. Mapping enriched BusEvents to the appropriate StreamPartEvent types
+ * 2. Filtering text deltas through the EchoSuppressor
+ * 3. Batching mapped events and delivering them via callback
+ * 4. Coordinating with CorrelationService for enrichment metadata
+ *
+ * The consumer is designed to work with the BatchDispatcher's frame-aligned
+ * batching system, processing all events from a batch and then delivering
+ * the resulting StreamPartEvents in a single callback invocation.
+ */
+export class StreamPipelineConsumer {
+  private correlation: CorrelationService;
+  private echoSuppressor: EchoSuppressor;
+  private callback: StreamPartEventCallback | null = null;
+
+  /**
+   * Construct a new StreamPipelineConsumer.
+   *
+   * @param correlation - Service for event correlation and enrichment
+   * @param echoSuppressor - Service for filtering duplicate text echoes
+   */
+  constructor(correlation: CorrelationService, echoSuppressor: EchoSuppressor) {
+    this.correlation = correlation;
+    this.echoSuppressor = echoSuppressor;
+  }
+
+  /**
+   * Register the callback that receives batches of StreamPartEvents.
+   *
+   * Only one callback can be registered at a time. Calling this method
+   * multiple times will replace the previous callback.
+   *
+   * @param callback - Function to receive batched StreamPartEvents
+   * @returns Cleanup function to unregister the callback
+   */
+  onStreamParts(callback: StreamPartEventCallback): () => void {
+    this.callback = callback;
+    return () => {
+      this.callback = null;
+    };
+  }
+
+  /**
+   * Process a batch of enriched BusEvents.
+   *
+   * This method is called by the BatchDispatcher subscriber for each
+   * frame-aligned batch. It maps each BusEvent to zero or more StreamPartEvents,
+   * collects them, and delivers the batch via the registered callback.
+   *
+   * @param events - Array of enriched BusEvents from the BatchDispatcher
+   */
+  processBatch(events: EnrichedBusEvent[]): void {
+    const parts: StreamPartEvent[] = [];
+
+    for (const event of events) {
+      const mapped = this.mapToStreamPart(event);
+      if (mapped) {
+        parts.push(...mapped);
+      }
+    }
+
+    if (parts.length > 0 && this.callback) {
+      const coalescedParts = this.coalesceStreamParts(parts);
+      pipelineLog("Consumer", "batch_deliver", { count: coalescedParts.length });
+      this.callback(coalescedParts);
+    }
+  }
+
+  /**
+   * Coalesce adjacent additive stream events within a single batch.
+   *
+   * This keeps visual parity while reducing reducer/state update churn in the UI.
+   * Only strictly adjacent events with matching scope are merged.
+   */
+  private coalesceStreamParts(parts: StreamPartEvent[]): StreamPartEvent[] {
+    if (parts.length <= 1) {
+      return parts;
+    }
+
+    const coalesced: StreamPartEvent[] = [];
+
+    for (const part of parts) {
+      const previous = coalesced.length > 0 ? coalesced[coalesced.length - 1] : undefined;
+
+      if (
+        previous
+        && previous.type === "text-delta"
+        && part.type === "text-delta"
+        && previous.agentId === part.agentId
+      ) {
+        previous.delta += part.delta;
+        continue;
+      }
+
+      if (
+        previous
+        && previous.type === "thinking-meta"
+        && part.type === "thinking-meta"
+        && previous.agentId === part.agentId
+        && previous.thinkingSourceKey === part.thinkingSourceKey
+        && previous.targetMessageId === part.targetMessageId
+        && previous.streamGeneration === part.streamGeneration
+        && previous.includeReasoningPart === part.includeReasoningPart
+        && previous.provider === part.provider
+      ) {
+        previous.thinkingText += part.thinkingText;
+        previous.thinkingMs = Math.max(previous.thinkingMs, part.thinkingMs);
+        continue;
+      }
+
+      coalesced.push(part);
+    }
+
+    return coalesced;
+  }
+
+  /**
+   * Map a single BusEvent to zero or more StreamPartEvents.
+   *
+   * This method handles the type-specific transformation logic for each
+   * BusEvent type. Some events map to a single StreamPartEvent, some map
+   * to multiple, and some are ignored (return null).
+   *
+   * @param event - The enriched BusEvent to map
+   * @returns Array of StreamPartEvents, or null if the event should be ignored
+   */
+  private mapToStreamPart(event: EnrichedBusEvent): StreamPartEvent[] | null {
+    switch (event.type) {
+      case "stream.text.delta": {
+        const data = event.data as BusEventDataMap["stream.text.delta"];
+        if (data.agentId) {
+          return [{ type: "text-delta", delta: data.delta, agentId: data.agentId }];
+        }
+        // Run through echo suppressor to filter duplicate tool result echoes
+        const filtered = this.echoSuppressor.filterDelta(data.delta);
+        if (!filtered) return null;
+        return [{ type: "text-delta", delta: filtered }];
+      }
+
+      case "stream.thinking.delta": {
+        const data = event.data as BusEventDataMap["stream.thinking.delta"];
+        return [{
+          type: "thinking-meta",
+          thinkingSourceKey: data.sourceKey,
+          targetMessageId: data.messageId,
+          streamGeneration: 0, // Default value - updated by correlation service if needed
+          thinkingText: data.delta,
+          thinkingMs: 0, // Duration tracking handled elsewhere
+          ...(data.agentId ? { agentId: data.agentId } : {}),
+        }];
+      }
+
+      case "stream.tool.start": {
+        const data = event.data as BusEventDataMap["stream.tool.start"];
+        const correlatedAgentId = data.parentAgentId
+          ?? (event.isSubagentTool ? event.resolvedAgentId : undefined);
+        return [{
+          type: "tool-start",
+          toolId: data.toolId,
+          toolName: data.toolName,
+          input: data.toolInput,
+          ...(correlatedAgentId ? { agentId: correlatedAgentId } : {}),
+        }];
+      }
+
+      case "stream.tool.complete": {
+        const data = event.data as BusEventDataMap["stream.tool.complete"];
+        const correlatedAgentId = data.parentAgentId
+          ?? (event.isSubagentTool ? event.resolvedAgentId : undefined);
+        if (isTaskOutputToolName(data.toolName)) {
+          const echoText = extractTaskOutputEchoText(data.toolResult);
+          if (echoText) {
+            this.echoSuppressor.expectEcho(echoText);
+          }
+        }
+        const mapped: StreamPartEvent = {
+          type: "tool-complete",
+          toolId: data.toolId,
+          toolName: data.toolName,
+          output: data.toolResult,
+          success: data.success,
+          error: data.error,
+          ...(data.toolInput ? { input: data.toolInput } : {}),
+          ...(correlatedAgentId ? { agentId: correlatedAgentId } : {}),
+        };
+        return [mapped];
+      }
+
+      case "stream.tool.partial_result": {
+        const data = event.data as BusEventDataMap["stream.tool.partial_result"];
+        const correlatedAgentId = data.parentAgentId
+          ?? (event.isSubagentTool ? event.resolvedAgentId : undefined);
+        return [{
+          type: "tool-partial-result",
+          toolId: data.toolCallId,
+          partialOutput: data.partialOutput,
+          ...(correlatedAgentId ? { agentId: correlatedAgentId } : {}),
+        }];
+      }
+
+      case "stream.text.complete": {
+        const data = event.data as BusEventDataMap["stream.text.complete"];
+        if (!data.fullText) return [];
+        return [{ type: "text-complete", fullText: data.fullText, messageId: data.messageId }];
+      }
+
+      case "workflow.task.update": {
+        const data = event.data as BusEventDataMap["workflow.task.update"];
+        const mapped: StreamPartEvent[] = [{
+          type: "task-list-update",
+          tasks: data.tasks.map((task) => ({
+            id: task.id,
+            title: task.title,
+            status: task.status,
+            ...(task.blockedBy ? { blockedBy: task.blockedBy } : {}),
+          })),
+        }];
+
+        for (const task of data.tasks) {
+          if (!task.taskResult) {
+            continue;
+          }
+
+          mapped.push({
+            type: "task-result-upsert",
+            envelope: task.taskResult,
+          });
+        }
+
+        return mapped;
+      }
+
+      case "workflow.step.start": {
+        const data = event.data as BusEventDataMap["workflow.step.start"];
+        return [{
+          type: "workflow-step-start",
+          workflowId: data.workflowId,
+          nodeId: data.nodeId,
+          nodeName: data.nodeName,
+          startedAt: new Date(event.timestamp).toISOString(),
+        }];
+      }
+
+      case "workflow.step.complete": {
+        const data = event.data as BusEventDataMap["workflow.step.complete"];
+        return [{
+          type: "workflow-step-complete",
+          workflowId: data.workflowId,
+          nodeId: data.nodeId,
+          nodeName: data.nodeName,
+          status: data.status,
+          ...(data.result !== undefined ? { result: data.result } : {}),
+          completedAt: new Date(event.timestamp).toISOString(),
+        }];
+      }
+
+      default:
+        // Other event types are not mapped to StreamPartEvents
+        // (they may be handled by other consumers)
+        pipelineLog("Consumer", "unmapped", { type: event.type });
+        return null;
+    }
+  }
+
+  /**
+   * Reset all consumer state.
+   *
+   * This method delegates reset to the correlation service and echo suppressor,
+   * preparing the consumer for a new streaming session.
+   *
+   * Should be called:
+   * - Before starting a new stream
+   * - On error recovery
+   * - When switching conversations
+   */
+  reset(): void {
+    this.echoSuppressor.reset();
+    this.correlation.reset();
+  }
+}
diff --git a/src/events/consumers/wire-consumers.ts b/src/events/consumers/wire-consumers.ts
new file mode 100644
index 0000000000..58d552509b
--- /dev/null
+++ b/src/events/consumers/wire-consumers.ts
@@ -0,0 +1,108 @@
+/**
+ * Wire Consumers to Event Bus
+ *
+ * This module provides the wireConsumers() function that instantiates and connects
+ * all consumer services to the event bus. It establishes the event processing pipeline:
+ *
+ * Event flow: Bus → CorrelationService.enrich() → StreamPipelineConsumer → UI
+ *
+ * The function returns handles to all consumer instances and a dispose function
+ * for cleanup, making it easy to manage the lifecycle of the entire consumer pipeline.
+ *
+ * Usage:
+ * ```typescript
+ * const bus = new EventBus();
+ * const consumers = wireConsumers(bus);
+ *
+ * // Consumers are now wired and processing events
+ * // Access individual services if needed:
+ * consumers.correlation.registerTool(toolId, agentId, isSubagent);
+ *
+ * // Clean up when done:
+ * consumers.dispose();
+ * ```
+ */
+
+import type { EventBus } from "../event-bus.ts";
+import type { BatchDispatcher } from "../batch-dispatcher.ts";
+import { CorrelationService } from "./correlation-service.ts";
+import { EchoSuppressor } from "./echo-suppressor.ts";
+import { StreamPipelineConsumer } from "./stream-pipeline-consumer.ts";
+import { pipelineLog } from "../pipeline-logger.ts";
+
+/**
+ * Container for wired consumer instances and cleanup.
+ *
+ * Provides access to all consumer service instances and a dispose function
+ * to cleanly shut down the entire consumer pipeline.
+ */
+export interface WiredConsumers {
+  /** Correlation service for enriching events with metadata */
+  correlation: CorrelationService;
+  /** Echo suppressor for filtering duplicate text */
+  echoSuppressor: EchoSuppressor;
+  /** Pipeline consumer for transforming bus events to stream parts */
+  pipeline: StreamPipelineConsumer;
+  /** Cleanup function to unsubscribe and reset all consumers */
+  dispose: () => void;
+}
+
+/**
+ * Wire all consumers to the event bus via the BatchDispatcher.
+ *
+ * Establishes the complete event processing pipeline:
+ * 1. Creates instances of all consumer services
+ * 2. Subscribes the dispatcher to the bus to enqueue events
+ * 3. Registers the consumer pipeline as a batch consumer of the dispatcher
+ * 4. Returns handles for external access and cleanup
+ *
+ * Event flow: Bus → BatchDispatcher.enqueue() → flush() → enrich → pipeline
+ *
+ * @param bus - The event bus to subscribe to
+ * @param dispatcher - The batch dispatcher for frame-aligned batching
+ * @returns Container with consumer instances and dispose function
+ */
+export function wireConsumers(bus: EventBus, dispatcher: BatchDispatcher): WiredConsumers {
+  const correlation = new CorrelationService();
+  const echoSuppressor = new EchoSuppressor();
+  const pipeline = new StreamPipelineConsumer(correlation, echoSuppressor);
+
+  // Subscribe BatchDispatcher to all bus events for enqueuing
+  const unsubscribeBus = bus.onAll((event) => {
+    dispatcher.enqueue(event);
+  });
+
+  // Register the consumer pipeline as a batch consumer of the dispatcher
+  const unsubscribeConsumer = dispatcher.addConsumer((events) => {
+    const owned = [];
+    for (const event of events) {
+      if (event.type === "stream.session.start") {
+        correlation.startRun(event.runId, event.sessionId);
+        owned.push(event);
+        continue;
+      }
+      if (correlation.isOwnedEvent(event)) {
+        owned.push(event);
+      }
+    }
+    const droppedUnowned = events.length - owned.length;
+    if (droppedUnowned > 0) {
+      pipelineLog("Wire", "filter_unowned", { total: events.length, owned: owned.length, droppedUnowned });
+    }
+    const enriched = owned.map((event) => correlation.enrich(event));
+    // Filter out events marked for suppression (e.g., sub-agent text-complete)
+    const unsuppressed = enriched.filter((event) => !event.suppressFromMainChat);
+    pipeline.processBatch(unsuppressed);
+  });
+
+  return {
+    correlation,
+    echoSuppressor,
+    pipeline,
+    dispose: () => {
+      unsubscribeBus();
+      unsubscribeConsumer();
+      pipeline.reset();
+    },
+  };
+}
diff --git a/src/events/debug-subscriber.test.ts b/src/events/debug-subscriber.test.ts
new file mode 100644
index 0000000000..29457074a9
--- /dev/null
+++ b/src/events/debug-subscriber.test.ts
@@ -0,0 +1,458 @@
+/**
+ * Unit tests for debug-subscriber JSONL logging
+ */
+
+import { describe, test, expect, beforeEach, afterEach, spyOn } from "bun:test";
+import { join } from "path";
+import { mkdir, mkdtemp, readdir, rm } from "fs/promises";
+import { tmpdir } from "os";
+import {
+  attachDebugSubscriber,
+  cleanup,
+  initEventLog,
+  readEventLog,
+  readRawStreamLog,
+  listEventLogs,
+  resolveStreamDebugLogConfig,
+  type EventLogEntry,
+} from "./debug-subscriber.ts";
+import type { BusEvent } from "./bus-events.ts";
+import { EventBus } from "./event-bus.ts";
+
+const STREAM_DEBUG_ENV_KEYS = [
+  "DEBUG",
+  "LOG_DIR",
+] as const;
+
+describe("Debug Subscriber JSONL Logging", () => {
+  let testDir: string;
+  let previousEnv: Partial<Record<(typeof STREAM_DEBUG_ENV_KEYS)[number], string | undefined>>;
+
+  beforeEach(async () => {
+    testDir = await mkdtemp(join(tmpdir(), "atomic-debug-test-"));
+    previousEnv = {};
+    for (const key of STREAM_DEBUG_ENV_KEYS) {
+      previousEnv[key] = process.env[key];
+      delete process.env[key];
+    }
+  });
+
+  afterEach(async () => {
+    for (const key of STREAM_DEBUG_ENV_KEYS) {
+      const previousValue = previousEnv[key];
+      if (previousValue === undefined) {
+        delete process.env[key];
+      } else {
+        process.env[key] = previousValue;
+      }
+    }
+    await rm(testDir, { recursive: true, force: true });
+  });
+
+  test("resolveStreamDebugLogConfig() enables via DEBUG", () => {
+    const config = resolveStreamDebugLogConfig({
+      DEBUG: "1",
+    });
+    expect(config.enabled).toBe(true);
+    expect(config.logDir).toBeUndefined();
+    expect(config.consolePreviewEnabled).toBe(true);
+  });
+
+  test("resolveStreamDebugLogConfig() supports custom log directory", () => {
+    const customDir = "/tmp/AtomicDebugLogs";
+    const config = resolveStreamDebugLogConfig({
+      DEBUG: "1",
+      LOG_DIR: customDir,
+    });
+    expect(config.enabled).toBe(true);
+    expect(config.logDir).toBe(customDir);
+  });
+
+  test("resolveStreamDebugLogConfig() remains disabled when DEBUG is not set", () => {
+    const config = resolveStreamDebugLogConfig({
+      LOG_DIR: "/tmp/AtomicDebugLogs",
+    });
+    expect(config.enabled).toBe(false);
+    expect(config.logDir).toBe("/tmp/AtomicDebugLogs");
+    expect(config.consolePreviewEnabled).toBe(false);
+  });
+
+  test("initEventLog() creates a per-run log directory and writes events", async () => {
+    const { write, close, logPath, rawLogPath, logDirPath } = await initEventLog({
+      logDir: testDir,
+    });
+    
+    const event: BusEvent = {
+      type: "stream.text.delta",
+      sessionId: "test-session",
+      runId: 1,
+      timestamp: Date.now(),
+      data: { delta: "hello", messageId: "m1" },
+    };
+
+    write(event);
+    await close();
+
+    // Read the file to verify
+    const entries = await readEventLog(logPath);
+    expect(entries.length).toBe(1);
+    expect(entries[0]!.type).toBe("stream.text.delta");
+    expect(entries[0]!.sessionId).toBe("test-session");
+    expect(entries[0]!.runId).toBe(1);
+    expect((entries[0]!.data as any).delta).toBe("hello");
+    expect(logPath).toContain("events.jsonl");
+    expect(rawLogPath).toContain("raw-stream.log");
+    expect(logDirPath).toContain(testDir);
+  });
+
+  test("readEventLog() returns empty array for non-existent file", async () => {
+    const entries = await readEventLog("/tmp/nonexistent-file.jsonl");
+    expect(entries).toEqual([]);
+  });
+
+  test("readEventLog() supports filter function", async () => {
+    const { write, close, logPath } = await initEventLog({
+      logDir: testDir,
+    });
+
+    const events: BusEvent[] = [
+      { type: "stream.text.delta", sessionId: "s1", runId: 1, timestamp: Date.now(), data: { delta: "a", messageId: "m1" } },
+      { type: "stream.tool.start", sessionId: "s1", runId: 1, timestamp: Date.now(), data: { toolId: "t1", toolName: "bash", toolInput: {} } },
+      { type: "stream.text.delta", sessionId: "s1", runId: 1, timestamp: Date.now(), data: { delta: "b", messageId: "m1" } },
+    ];
+
+    for (const event of events) {
+      write(event);
+    }
+    await close();
+
+    const filtered = await readEventLog(logPath, (entry) => entry.type === "stream.text.delta");
+    expect(filtered.length).toBe(2);
+  });
+
+  test("initEventLog() writes raw stream conversation components", async () => {
+    const { write, writeRawLine, close, rawLogPath } = await initEventLog({
+      logDir: testDir,
+    });
+
+    writeRawLine("❯ @codebase-online-researcher Research TUI UX");
+    write({
+      type: "stream.thinking.delta",
+      sessionId: "s-raw",
+      runId: 11,
+      timestamp: Date.now(),
+      data: {
+        delta: "thinking",
+        sourceKey: "src-1",
+        messageId: "m-raw",
+      },
+    });
+    write({
+      type: "stream.text.delta",
+      sessionId: "s-raw",
+      runId: 11,
+      timestamp: Date.now(),
+      data: { delta: "Launching UI/UX research task\n", messageId: "m-raw" },
+    });
+    write({
+      type: "stream.tool.start",
+      sessionId: "s-raw",
+      runId: 11,
+      timestamp: Date.now(),
+      data: {
+        toolId: "tool-task",
+        toolName: "task",
+        toolInput: {
+          agent_type: "codebase-online-researcher",
+          description: "Research TUI UX practices",
+          prompt: "Research task only",
+        },
+      },
+    });
+
+    await close();
+
+    const rawLines = await readRawStreamLog(rawLogPath);
+    expect(rawLines).toContain("❯ @codebase-online-researcher Research TUI UX");
+    expect(rawLines).toContain("⣯ Composing…");
+    expect(rawLines).toContain("∴ Thinking...");
+    expect(rawLines).toContain("Launching UI/UX research task");
+    expect(rawLines).toContain("◉");
+    expect(rawLines).toContain("task codebase-online-researcher: Research TUI UX practices");
+    expect(rawLines).toContain("Agent: codebase-online-researcher");
+    expect(rawLines).toContain("Task: Research TUI UX practices");
+    expect(rawLines).toContain("Prompt: Research task only");
+  });
+
+  test("cleanup() retains only 10 most recent session directories", async () => {
+    // Create 12 fake session directories in testDir
+    for (let i = 0; i < 12; i++) {
+      const hour = String(i).padStart(2, "0");
+      const sessionName = `2026-02-26T${hour}0000`;
+      const sessionDir = join(testDir, sessionName);
+      await mkdir(sessionDir, { recursive: true });
+      await Bun.write(
+        join(sessionDir, "events.jsonl"),
+        `{"ts":"test"}\n`,
+      );
+    }
+
+    await cleanup(testDir);
+
+    const remaining = (await readdir(testDir, { withFileTypes: true }))
+      .filter((entry) => entry.isDirectory())
+      .filter((entry) => /^\d{4}-\d{2}-\d{2}T\d{6}$/.test(entry.name));
+
+    expect(remaining.length).toBe(10);
+  });
+
+  test("listEventLogs() returns files most recent first", async () => {
+    // Create a few log directories
+    for (const sessionName of ["2026-02-26T100000", "2026-02-26T120000", "2026-02-26T080000"]) {
+      const sessionDir = join(testDir, sessionName);
+      await mkdir(sessionDir, { recursive: true });
+      await Bun.write(join(sessionDir, "events.jsonl"), "");
+    }
+
+    const logs = await listEventLogs(testDir);
+    expect(logs.length).toBe(3);
+    expect(logs[0]).toContain("120000");
+    expect(logs[1]).toContain("100000");
+    expect(logs[2]).toContain("080000");
+  });
+
+  test("JSONL entries have correct format", async () => {
+    const { write, close, logPath } = await initEventLog({
+      logDir: testDir,
+    });
+
+    const now = Date.now();
+    write({
+      type: "stream.usage",
+      sessionId: "s1",
+      runId: 42,
+      timestamp: now,
+      data: { inputTokens: 100, outputTokens: 50, model: "gpt-4" },
+    });
+    await close();
+
+    const content = await Bun.file(logPath).text();
+    const parsed = JSON.parse(content.trim()) as EventLogEntry;
+    
+    expect(parsed.ts).toBe(new Date(now).toISOString());
+    expect(parsed.type).toBe("stream.usage");
+    expect(parsed.sessionId).toBe("s1");
+    expect(parsed.runId).toBe(42);
+    expect(parsed.seq).toBe(1);
+    expect(parsed.runSeq).toBe(1);
+    expect(typeof parsed.loggedAt).toBe("string");
+    expect(typeof parsed.eventLagMs).toBe("number");
+    expect(parsed.globalGapMs).toBeNull();
+    expect(parsed.sessionRunGapMs).toBeNull();
+    expect(parsed.streamGapMs).toBeNull();
+    expect(parsed.runAgeMs).toBe(0);
+    expect(parsed.streamEventCount).toBe(1);
+    expect(parsed.textDeltaCount).toBe(0);
+    expect(parsed.pendingToolCalls).toBe(0);
+    expect(parsed.maxPendingToolCalls).toBe(0);
+    expect(parsed.lifecycleMarkers).toContain("run-first-seen");
+    expect(parsed.lifecycleMarkers).toContain("first-stream-event");
+    expect(parsed.payloadBytes).toBeGreaterThan(0);
+
+    const usageData = parsed.data as { inputTokens: number };
+    expect(usageData.inputTokens).toBe(100);
+  });
+
+  test("initEventLog() annotates continuity gaps and run-local sequence", async () => {
+    const nowSpy = spyOn(Date, "now");
+    nowSpy.mockReturnValueOnce(1000);
+    nowSpy.mockReturnValueOnce(3200);
+
+    const { write, close, logPath } = await initEventLog({
+      logDir: testDir,
+    });
+
+    write({
+      type: "stream.text.delta",
+      sessionId: "s-gap",
+      runId: 9,
+      timestamp: 1000,
+      data: { delta: "a", messageId: "m-gap" },
+    });
+
+    write({
+      type: "stream.text.delta",
+      sessionId: "s-gap",
+      runId: 9,
+      timestamp: 1200,
+      data: { delta: "b", messageId: "m-gap" },
+    });
+
+    nowSpy.mockRestore();
+    await close();
+
+    const entries = await readEventLog(logPath);
+    expect(entries).toHaveLength(2);
+    expect(entries[0]?.runSeq).toBe(1);
+    expect(entries[1]?.runSeq).toBe(2);
+    expect(entries[1]?.globalGapMs).toBe(2200);
+    expect(entries[1]?.sessionRunGapMs).toBe(2200);
+    expect(entries[1]?.continuityGapMs).toBe(2200);
+    expect(entries[1]?.streamGapMs).toBe(2200);
+    expect(entries[1]?.lifecycleMarkers).toContain("stream-gap");
+    expect(entries[1]?.lifecycleMarkers).toContain("continuity-gap");
+  });
+
+  test("initEventLog() records event timestamp regression per run", async () => {
+    const nowSpy = spyOn(Date, "now");
+    nowSpy.mockReturnValueOnce(5000);
+    nowSpy.mockReturnValueOnce(5200);
+
+    const { write, close, logPath } = await initEventLog({
+      logDir: testDir,
+    });
+
+    write({
+      type: "stream.text.delta",
+      sessionId: "s-regress",
+      runId: 3,
+      timestamp: 10_000,
+      data: { delta: "first", messageId: "m-regress" },
+    });
+
+    write({
+      type: "stream.text.delta",
+      sessionId: "s-regress",
+      runId: 3,
+      timestamp: 9_600,
+      data: { delta: "second", messageId: "m-regress" },
+    });
+
+    nowSpy.mockRestore();
+    await close();
+
+    const entries = await readEventLog(logPath);
+    expect(entries[1]?.eventTimestampRegressionMs).toBe(400);
+    expect(entries[1]?.lifecycleMarkers).toContain("timestamp-regression");
+  });
+
+  test("initEventLog() marks lifecycle transitions and tool balance anomalies", async () => {
+    const nowSpy = spyOn(Date, "now");
+    nowSpy.mockReturnValueOnce(1000);
+    nowSpy.mockReturnValueOnce(1100);
+    nowSpy.mockReturnValueOnce(1400);
+
+    const { write, close, logPath } = await initEventLog({
+      logDir: testDir,
+    });
+
+    write({
+      type: "stream.session.start",
+      sessionId: "s-life",
+      runId: 5,
+      timestamp: 1000,
+      data: {},
+    });
+
+    write({
+      type: "stream.tool.start",
+      sessionId: "s-life",
+      runId: 5,
+      timestamp: 1100,
+      data: { toolId: "tool-1", toolName: "bash", toolInput: { command: "pwd" } },
+    });
+
+    write({
+      type: "stream.session.idle",
+      sessionId: "s-life",
+      runId: 5,
+      timestamp: 1400,
+      data: { reason: "idle" },
+    });
+
+    nowSpy.mockRestore();
+    await close();
+
+    const entries = await readEventLog(logPath);
+    expect(entries).toHaveLength(3);
+    expect(entries[0]?.lifecycleMarkers).toContain("session-start");
+    expect(entries[1]?.pendingToolCalls).toBe(1);
+    expect(entries[1]?.maxPendingToolCalls).toBe(1);
+    expect(entries[2]?.lifecycleMarkers).toContain("session-idle");
+    expect(entries[2]?.lifecycleMarkers).toContain("idle-with-pending-tools");
+    expect(entries[2]?.runDurationMs).toBe(400);
+  });
+
+  test("initEventLog() flags tool complete without matching start", async () => {
+    const nowSpy = spyOn(Date, "now");
+    nowSpy.mockReturnValueOnce(2000);
+
+    const { write, close, logPath } = await initEventLog({
+      logDir: testDir,
+    });
+
+    write({
+      type: "stream.tool.complete",
+      sessionId: "s-tool",
+      runId: 8,
+      timestamp: 2000,
+      data: {
+        toolId: "tool-2",
+        toolName: "bash",
+        toolResult: { ok: true },
+        success: true,
+      },
+    });
+
+    nowSpy.mockRestore();
+    await close();
+
+    const entries = await readEventLog(logPath);
+    expect(entries[0]?.lifecycleMarkers).toContain("tool-complete-without-start");
+    expect(entries[0]?.pendingToolCalls).toBe(0);
+  });
+
+  test("attachDebugSubscriber() logs all events when stream debug is enabled", async () => {
+    process.env.DEBUG = "1";
+    process.env.LOG_DIR = testDir;
+    const debugSpy = spyOn(console, "debug").mockImplementation(() => {});
+
+    const bus = new EventBus({ validatePayloads: false });
+    const { unsubscribe, logPath, rawLogPath, logDirPath, writeRawLine } = await attachDebugSubscriber(bus);
+    expect(logPath).not.toBeNull();
+    expect(rawLogPath).not.toBeNull();
+    expect(logDirPath).not.toBeNull();
+
+    writeRawLine("❯ Investigate stream ordering");
+
+    bus.publish({
+      type: "stream.text.delta",
+      sessionId: "session-debug",
+      runId: 7,
+      timestamp: Date.now(),
+      data: { delta: "debug", messageId: "msg-debug" },
+    });
+    bus.publish({
+      type: "stream.tool.start",
+      sessionId: "session-debug",
+      runId: 7,
+      timestamp: Date.now(),
+      data: { toolId: "tool-1", toolName: "bash", toolInput: { command: "pwd" } },
+    });
+
+    await unsubscribe();
+    debugSpy.mockRestore();
+
+    const entries = await readEventLog(logPath!);
+    // First entry is the startup diagnostic, followed by 2 bus events
+    expect(entries.length).toBe(3);
+    expect((entries[0] as unknown as Record<string, unknown>).category).toBe("startup");
+    expect(entries[1]?.type).toBe("stream.text.delta");
+    expect(entries[2]?.type).toBe("stream.tool.start");
+
+    const rawLines = await readRawStreamLog(rawLogPath!);
+    expect(rawLines).toContain("❯ Investigate stream ordering");
+    expect(rawLines.some((line) => line.includes("stream.text.delta"))).toBe(false);
+    expect(rawLines).toContain("◉ bash");
+  });
+});
diff --git a/src/events/debug-subscriber.ts b/src/events/debug-subscriber.ts
new file mode 100644
index 0000000000..edb805b579
--- /dev/null
+++ b/src/events/debug-subscriber.ts
@@ -0,0 +1,878 @@
+/**
+ * Debug Event Subscriber with JSONL File Logging
+ *
+ * Provides file-based JSONL event logging with automatic rotation,
+ * modeled after OpenCode's packages/opencode/src/util/log.ts pattern.
+ *
+ * Features:
+ * - JSONL format (one JSON object per event per line)
+ * - Automatic log rotation (retains 10 most recent files)
+ * - Event replay from persisted log files
+ * - Console.debug retained for real-time visibility
+ * - Activated by DEBUG=1
+ *
+ * Usage:
+ * ```typescript
+ * const bus = new EventBus();
+ * const { unsubscribe, logPath } = await attachDebugSubscriber(bus);
+ *
+ * // Events are now logged to JSONL files at ~/.local/share/atomic/log/events/
+ *
+ * unsubscribe(); // Stop logging and close file
+ * ```
+ */
+
+import { join } from "path";
+import { homedir } from "os";
+import { mkdir, readdir, rm } from "fs/promises";
+import type { EventBus } from "./event-bus.ts";
+import type { BusEvent } from "./bus-events.ts";
+
+const DEFAULT_LOG_DIR = join(homedir(), ".local", "share", "atomic", "log", "events");
+const MAX_LOG_SESSIONS = 10;
+const DEBUG_ENV = "DEBUG";
+const LOG_DIR_ENV = "LOG_DIR";
+const LOG_SESSION_NAME_REGEX = /^\d{4}-\d{2}-\d{2}T\d{6}$/;
+const LOG_EVENTS_FILENAME = "events.jsonl";
+const LOG_RAW_STREAM_FILENAME = "raw-stream.log";
+
+function isFalsyEnvValue(value: string): boolean {
+  return value === "0" || value === "false" || value === "off";
+}
+
+export interface StreamDebugLogConfig {
+  enabled: boolean;
+  logDir?: string;
+  consolePreviewEnabled: boolean;
+}
+
+export function resolveStreamDebugLogConfig(
+  env: NodeJS.ProcessEnv = process.env,
+): StreamDebugLogConfig {
+  const rawDebugValue = env[DEBUG_ENV]?.trim();
+  const normalizedDebugValue = rawDebugValue?.toLowerCase();
+  const explicitDir = env[LOG_DIR_ENV]?.trim();
+
+  if (normalizedDebugValue && !isFalsyEnvValue(normalizedDebugValue)) {
+    return {
+      enabled: true,
+      ...(explicitDir ? { logDir: explicitDir } : {}),
+      consolePreviewEnabled: true,
+    };
+  }
+
+  return {
+    enabled: false,
+    ...(explicitDir ? { logDir: explicitDir } : {}),
+    consolePreviewEnabled: false,
+  };
+}
+
+/** JSONL log entry format — one per line in the log file */
+export interface EventLogEntry {
+  seq?: number;
+  runSeq?: number;
+  ts: string;
+  loggedAt?: string;
+  type: string;
+  sessionId: string;
+  runId: number;
+  eventLagMs?: number;
+  globalGapMs?: number | null;
+  sessionRunGapMs?: number | null;
+  continuityGapMs?: number;
+  eventTimestampRegressionMs?: number;
+  streamGapMs?: number | null;
+  runAgeMs?: number;
+  runDurationMs?: number;
+  streamEventCount?: number;
+  textDeltaCount?: number;
+  thinkingDeltaCount?: number;
+  toolStartCount?: number;
+  toolCompleteCount?: number;
+  pendingToolCalls?: number;
+  maxPendingToolCalls?: number;
+  lifecycleMarkers?: string[];
+  payloadBytes?: number;
+  /** Aggregate sub-agent tree state (present on agent lifecycle events) */
+  agentTreeSnapshot?: AgentTreeSnapshot;
+  data: unknown;
+}
+
+/**
+ * Snapshot of all tracked sub-agents at a point in time.
+ * Attached to agent lifecycle events (stream.agent.start/update/complete)
+ * so that the debug log captures the full tree context.
+ */
+export interface AgentTreeSnapshot {
+  agents: AgentTreeEntry[];
+  totalCount: number;
+  runningCount: number;
+  completedCount: number;
+  errorCount: number;
+}
+
+export interface AgentTreeEntry {
+  agentId: string;
+  agentType: string;
+  task: string;
+  status: "running" | "completed" | "error";
+  isBackground: boolean;
+  startedAt: string;
+  toolUses?: number;
+  currentTool?: string;
+  error?: string;
+  durationMs?: number;
+}
+
+/**
+ * Error/metadata log entry written for internal bus errors,
+ * process-level errors, and startup metadata.
+ * Shares the same JSONL file but uses a different shape.
+ */
+export interface DiagnosticLogEntry {
+  seq: number;
+  ts: string;
+  category: "bus_error" | "process_error" | "startup";
+  kind?: string;
+  eventType?: string;
+  error?: string;
+  stack?: string;
+  agentTreeSnapshot?: AgentTreeSnapshot;
+  data?: unknown;
+}
+
+export interface RawStreamLogEntry {
+  seq: number;
+  ts: string;
+  sessionId?: string;
+  runId?: number;
+  component:
+    | "prompt"
+    | "status"
+    | "thinking"
+    | "assistant"
+    | "tool"
+    | "agent"
+    | "diagnostic";
+  text: string;
+}
+
+const STREAM_CONTINUITY_GAP_THRESHOLD_MS = 1500;
+
+function buildLogSessionName(now: Date = new Date()): string {
+  return now.toISOString().split(".")[0]!.replace(/:/g, "");
+}
+
+function formatRawDuration(ms: number): string {
+  const totalSeconds = Math.max(0, Math.floor(ms / 1000));
+  const minutes = Math.floor(totalSeconds / 60);
+  const seconds = totalSeconds % 60;
+  if (minutes <= 0) return `${seconds}s`;
+  return `${minutes}m ${seconds}s`;
+}
+
+function truncateRawText(value: string, maxChars: number): string {
+  if (value.length <= maxChars) return value;
+  return `${value.slice(0, maxChars)}… (+${value.length - maxChars} chars truncated)`;
+}
+
+interface SessionRunDebugState {
+  firstSeenLoggedAtMs: number;
+  firstStreamLoggedAtMs: number | null;
+  firstTextDeltaLoggedAtMs: number | null;
+  lastStreamLoggedAtMs: number | null;
+  streamEventCount: number;
+  textDeltaCount: number;
+  thinkingDeltaCount: number;
+  toolStartCount: number;
+  toolCompleteCount: number;
+  pendingToolCalls: number;
+  maxPendingToolCalls: number;
+  sawSessionStart: boolean;
+  sawSessionIdle: boolean;
+  sawSessionError: boolean;
+  rawStatusLogged: boolean;
+  rawThinkingLogged: boolean;
+  rawTextBuffer: string;
+}
+
+function buildSessionRunKey(event: BusEvent): string {
+  return `${event.sessionId}::${event.runId}`;
+}
+
+function isStreamEventType(type: string): boolean {
+  return type.startsWith("stream.");
+}
+
+function isSessionStartEventType(type: string): boolean {
+  return type === "stream.session.start";
+}
+
+function isSessionIdleEventType(type: string): boolean {
+  return type === "stream.session.idle" || type === "session.idle";
+}
+
+function isSessionErrorEventType(type: string): boolean {
+  return type === "stream.session.error" || type === "session.error";
+}
+
+function createSessionRunDebugState(loggedAtMs: number): SessionRunDebugState {
+  return {
+    firstSeenLoggedAtMs: loggedAtMs,
+    firstStreamLoggedAtMs: null,
+    firstTextDeltaLoggedAtMs: null,
+    lastStreamLoggedAtMs: null,
+    streamEventCount: 0,
+    textDeltaCount: 0,
+    thinkingDeltaCount: 0,
+    toolStartCount: 0,
+    toolCompleteCount: 0,
+    pendingToolCalls: 0,
+    maxPendingToolCalls: 0,
+    sawSessionStart: false,
+    sawSessionIdle: false,
+    sawSessionError: false,
+    rawStatusLogged: false,
+    rawThinkingLogged: false,
+    rawTextBuffer: "",
+  };
+}
+
+async function listLogSessionDirectories(dir: string): Promise<string[]> {
+  const sessionDirs: string[] = [];
+  const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (!LOG_SESSION_NAME_REGEX.test(entry.name)) continue;
+    sessionDirs.push(join(dir, entry.name));
+  }
+  sessionDirs.sort();
+  return sessionDirs;
+}
+
+/**
+ * Clean up old debug log sessions, retaining the most recent MAX_LOG_SESSIONS.
+ */
+export async function cleanup(dir: string): Promise<void> {
+  const sessionDirs = await listLogSessionDirectories(dir);
+  if (sessionDirs.length > MAX_LOG_SESSIONS) {
+    const dirsToDelete = sessionDirs.slice(0, sessionDirs.length - MAX_LOG_SESSIONS);
+    await Promise.all(
+      dirsToDelete.map((sessionDir) =>
+        rm(sessionDir, { recursive: true, force: true }).catch(() => {})),
+    );
+  }
+}
+
+/**
+ * Initialize the event log file writer.
+ * Mirrors OpenCode's Log.init() in packages/opencode/src/util/log.ts.
+ */
+export async function initEventLog(options?: {
+  logDir?: string;
+}): Promise<{
+  write: (event: BusEvent) => void;
+  writeDiagnostic: (entry: Omit<DiagnosticLogEntry, "seq" | "ts">) => void;
+  writeRawLine: (line: string, metadata?: { sessionId?: string; runId?: number; component?: RawStreamLogEntry["component"] }) => void;
+  getAgentTreeSnapshot: () => AgentTreeSnapshot;
+  close: () => Promise<void>;
+  logPath: string;
+  rawLogPath: string;
+  logDirPath: string;
+}> {
+  const logDir = options?.logDir ?? DEFAULT_LOG_DIR;
+  await mkdir(logDir, { recursive: true });
+  await cleanup(logDir);
+
+  const sessionName = buildLogSessionName();
+  const logDirPath = join(logDir, sessionName);
+  await mkdir(logDirPath, { recursive: true });
+
+  const logPath = join(logDirPath, LOG_EVENTS_FILENAME);
+  const rawLogPath = join(logDirPath, LOG_RAW_STREAM_FILENAME);
+  const logFile = Bun.file(logPath);
+  const writer = logFile.writer();
+  const rawFile = Bun.file(rawLogPath);
+  const rawWriter = rawFile.writer();
+  const textEncoder = new TextEncoder();
+  let seq = 0;
+  let previousLoggedAtMs: number | null = null;
+  const previousLoggedAtBySessionRun = new Map<string, number>();
+  const previousEventTimestampBySessionRun = new Map<string, number>();
+  const runSeqBySessionRun = new Map<string, number>();
+  const runStateBySessionRun = new Map<string, SessionRunDebugState>();
+
+  // Agent tree state tracking
+  const agentTreeState = new Map<string, AgentTreeEntry>();
+
+  function updateAgentTree(event: BusEvent): void {
+    const data = event.data as Record<string, unknown>;
+    const agentId = data.agentId as string | undefined;
+    if (!agentId) return;
+
+    if (event.type === "stream.agent.start") {
+      agentTreeState.set(agentId, {
+        agentId,
+        agentType: (data.agentType as string) ?? "unknown",
+        task: (data.task as string) ?? "",
+        status: "running",
+        isBackground: (data.isBackground as boolean) ?? false,
+        startedAt: new Date().toISOString(),
+      });
+    } else if (event.type === "stream.agent.update") {
+      const existing = agentTreeState.get(agentId);
+      if (existing) {
+        if (data.currentTool !== undefined) existing.currentTool = data.currentTool as string;
+        if (data.toolUses !== undefined) existing.toolUses = data.toolUses as number;
+      }
+    } else if (event.type === "stream.agent.complete") {
+      const existing = agentTreeState.get(agentId);
+      if (existing) {
+        existing.status = (data.success as boolean) ? "completed" : "error";
+        if (data.error) existing.error = data.error as string;
+        existing.currentTool = undefined;
+      }
+    }
+  }
+
+  function buildAgentTreeSnapshot(): AgentTreeSnapshot {
+    const agents = Array.from(agentTreeState.values());
+    return {
+      agents,
+      totalCount: agents.length,
+      runningCount: agents.filter(a => a.status === "running").length,
+      completedCount: agents.filter(a => a.status === "completed").length,
+      errorCount: agents.filter(a => a.status === "error").length,
+    };
+  }
+
+  const isAgentLifecycleEvent = (type: string): boolean =>
+    type === "stream.agent.start" ||
+    type === "stream.agent.update" ||
+    type === "stream.agent.complete";
+
+  const writeRawLine = (
+    line: string,
+    metadata?: { sessionId?: string; runId?: number; component?: RawStreamLogEntry["component"] },
+  ): void => {
+    void metadata;
+    const normalizedLine = line.replace(/\r/g, "");
+    if (!normalizedLine.trim()) return;
+    rawWriter.write(`${normalizedLine}\n`);
+    rawWriter.flush();
+  };
+
+  const writeRawLines = (
+    lines: string[],
+    metadata?: { sessionId?: string; runId?: number; component?: RawStreamLogEntry["component"] },
+  ): void => {
+    for (const line of lines) {
+      writeRawLine(line, metadata);
+    }
+  };
+
+  const flushRawTextBuffer = (event: BusEvent, runState: SessionRunDebugState): void => {
+    const buffered = runState.rawTextBuffer.trim();
+    if (buffered.length === 0) {
+      runState.rawTextBuffer = "";
+      return;
+    }
+    writeRawLine(buffered, {
+      sessionId: event.sessionId,
+      runId: event.runId,
+      component: "assistant",
+    });
+    runState.rawTextBuffer = "";
+  };
+
+  const formatTaskToolLines = (toolInput: Record<string, unknown>): string[] => {
+    const lines: string[] = [];
+    const task = String(toolInput.description ?? "").trim();
+    const prompt = String(toolInput.prompt ?? "").trim();
+    const agent = String(
+      toolInput.agent_type ?? toolInput.subagent_type ?? toolInput.agent ?? "",
+    ).trim();
+    const title = [agent, task].filter(Boolean).join(": ") || "Sub-agent task";
+    lines.push(`task ${truncateRawText(title, 180)}`);
+    if (agent) lines.push(`Agent: ${truncateRawText(agent, 160)}`);
+    if (task) lines.push(`Task: ${truncateRawText(task, 160)}`);
+    if (prompt) lines.push(`Prompt: ${truncateRawText(prompt, 160)}`);
+    return lines;
+  };
+
+  const formatToolStartLines = (
+    toolName: string,
+    toolInput: Record<string, unknown>,
+  ): string[] => {
+    const normalizedName = toolName.toLowerCase();
+    if (
+      normalizedName === "task"
+      || normalizedName === "launch_agent"
+      || normalizedName === "launch-agent"
+    ) {
+      return ["◉", ...formatTaskToolLines(toolInput)];
+    }
+
+    const lines: string[] = [`◉ ${toolName}`];
+    const summaryParts = Object.entries(toolInput)
+      .slice(0, 3)
+      .map(([key, value]) => `${key}: ${truncateRawText(String(value), 80)}`);
+    if (summaryParts.length > 0) {
+      lines.push(summaryParts.join(", "));
+    }
+    return lines;
+  };
+
+  const writeRawForEvent = (
+    event: BusEvent,
+    runState: SessionRunDebugState,
+    loggedAtMs: number,
+  ): void => {
+    if (!runState.rawStatusLogged && event.type.startsWith("stream.")) {
+      runState.rawStatusLogged = true;
+      writeRawLine("⣯ Composing…", {
+        sessionId: event.sessionId,
+        runId: event.runId,
+        component: "status",
+      });
+    }
+
+    if (event.type === "stream.thinking.delta" && !runState.rawThinkingLogged) {
+      runState.rawThinkingLogged = true;
+      writeRawLine("∴ Thinking...", {
+        sessionId: event.sessionId,
+        runId: event.runId,
+        component: "thinking",
+      });
+      return;
+    }
+
+    if (event.type === "stream.text.delta") {
+      const delta = String((event.data as Record<string, unknown>).delta ?? "");
+      if (delta.length === 0) return;
+      runState.rawTextBuffer += delta;
+      const newlineChunks = runState.rawTextBuffer.split("\n");
+      if (newlineChunks.length <= 1) return;
+      const completeLines = newlineChunks.slice(0, -1).map((line) => line.trim()).filter(Boolean);
+      runState.rawTextBuffer = newlineChunks.at(-1) ?? "";
+      writeRawLines(completeLines, {
+        sessionId: event.sessionId,
+        runId: event.runId,
+        component: "assistant",
+      });
+      return;
+    }
+
+    if (event.type === "stream.tool.start") {
+      flushRawTextBuffer(event, runState);
+      const data = event.data as Record<string, unknown>;
+      const toolName = String(data.toolName ?? "tool");
+      const toolInput = (data.toolInput as Record<string, unknown> | undefined) ?? {};
+      writeRawLines(formatToolStartLines(toolName, toolInput), {
+        sessionId: event.sessionId,
+        runId: event.runId,
+        component: "tool",
+      });
+      return;
+    }
+
+    if (event.type === "stream.agent.start") {
+      const data = event.data as Record<string, unknown>;
+      const agentType = String(data.agentType ?? "agent");
+      const task = String(data.task ?? "sub-agent task");
+      writeRawLine(`● ${agentType}: ${truncateRawText(task, 160)}`, {
+        sessionId: event.sessionId,
+        runId: event.runId,
+        component: "agent",
+      });
+      return;
+    }
+
+    if (event.type === "stream.session.idle" || event.type === "stream.session.error") {
+      flushRawTextBuffer(event, runState);
+      const runAgeMs = Math.max(0, loggedAtMs - runState.firstSeenLoggedAtMs);
+      writeRawLine(`⣯ Composing… (${formatRawDuration(runAgeMs)})`, {
+        sessionId: event.sessionId,
+        runId: event.runId,
+        component: "status",
+      });
+    }
+  };
+
+  const write = (event: BusEvent): void => {
+    const loggedAtMs = Date.now();
+    const sessionRunKey = buildSessionRunKey(event);
+    let runState = runStateBySessionRun.get(sessionRunKey);
+    const isFirstRunEvent = !runState;
+    if (!runState) {
+      runState = createSessionRunDebugState(loggedAtMs);
+      runStateBySessionRun.set(sessionRunKey, runState);
+    }
+
+    const lifecycleMarkers: string[] = [];
+    if (isFirstRunEvent) {
+      lifecycleMarkers.push("run-first-seen");
+    }
+
+    const isStreamEvent = isStreamEventType(event.type);
+    const previousStreamLoggedAtMs = runState.lastStreamLoggedAtMs;
+    const streamGapMs = isStreamEvent
+      ? (previousStreamLoggedAtMs === null
+          ? null
+          : Math.max(0, loggedAtMs - previousStreamLoggedAtMs))
+      : null;
+
+    if (isSessionStartEventType(event.type)) {
+      runState.sawSessionStart = true;
+      lifecycleMarkers.push("session-start");
+    }
+
+    if (isStreamEvent) {
+      runState.streamEventCount += 1;
+      runState.lastStreamLoggedAtMs = loggedAtMs;
+      if (runState.firstStreamLoggedAtMs === null) {
+        runState.firstStreamLoggedAtMs = loggedAtMs;
+        lifecycleMarkers.push("first-stream-event");
+      }
+    }
+
+    if (event.type === "stream.text.delta") {
+      runState.textDeltaCount += 1;
+      if (runState.firstTextDeltaLoggedAtMs === null) {
+        runState.firstTextDeltaLoggedAtMs = loggedAtMs;
+        lifecycleMarkers.push("first-text-delta");
+      }
+    }
+
+    if (event.type === "stream.thinking.delta") {
+      runState.thinkingDeltaCount += 1;
+    }
+
+    if (event.type === "stream.tool.start") {
+      runState.toolStartCount += 1;
+      runState.pendingToolCalls += 1;
+      runState.maxPendingToolCalls = Math.max(
+        runState.maxPendingToolCalls,
+        runState.pendingToolCalls,
+      );
+    }
+
+    let toolCompleteWithoutStart = false;
+    if (event.type === "stream.tool.complete") {
+      runState.toolCompleteCount += 1;
+      if (runState.pendingToolCalls === 0) {
+        toolCompleteWithoutStart = true;
+        lifecycleMarkers.push("tool-complete-without-start");
+      } else {
+        runState.pendingToolCalls = Math.max(0, runState.pendingToolCalls - 1);
+      }
+    }
+
+    if (
+      streamGapMs !== null
+      && streamGapMs >= STREAM_CONTINUITY_GAP_THRESHOLD_MS
+    ) {
+      lifecycleMarkers.push("stream-gap");
+    }
+
+    if (isSessionIdleEventType(event.type)) {
+      runState.sawSessionIdle = true;
+      lifecycleMarkers.push("session-idle");
+      if (runState.pendingToolCalls > 0) {
+        lifecycleMarkers.push("idle-with-pending-tools");
+      }
+    }
+
+    if (isSessionErrorEventType(event.type)) {
+      runState.sawSessionError = true;
+      lifecycleMarkers.push("session-error");
+    }
+
+    // Track agent tree state before building the entry
+    updateAgentTree(event);
+
+    const previousSessionLoggedAtMs = previousLoggedAtBySessionRun.get(sessionRunKey) ?? null;
+    const previousSessionEventTimestampMs =
+      previousEventTimestampBySessionRun.get(sessionRunKey) ?? null;
+    const globalGapMs =
+      previousLoggedAtMs === null ? null : Math.max(0, loggedAtMs - previousLoggedAtMs);
+    const sessionRunGapMs =
+      previousSessionLoggedAtMs === null ? null : Math.max(0, loggedAtMs - previousSessionLoggedAtMs);
+    const eventTimestampRegressionMs =
+      previousSessionEventTimestampMs !== null && event.timestamp < previousSessionEventTimestampMs
+        ? previousSessionEventTimestampMs - event.timestamp
+        : undefined;
+    const continuityGapMs =
+      sessionRunGapMs !== null
+      && sessionRunGapMs >= STREAM_CONTINUITY_GAP_THRESHOLD_MS
+      && event.type.startsWith("stream.")
+        ? sessionRunGapMs
+        : undefined;
+    if (continuityGapMs !== undefined) {
+      lifecycleMarkers.push("continuity-gap");
+    }
+    if (eventTimestampRegressionMs !== undefined) {
+      lifecycleMarkers.push("timestamp-regression");
+    }
+    const nextRunSeq = (runSeqBySessionRun.get(sessionRunKey) ?? 0) + 1;
+    runSeqBySessionRun.set(sessionRunKey, nextRunSeq);
+    previousLoggedAtMs = loggedAtMs;
+    previousLoggedAtBySessionRun.set(sessionRunKey, loggedAtMs);
+    previousEventTimestampBySessionRun.set(sessionRunKey, event.timestamp);
+
+    const payloadJson = JSON.stringify(event.data);
+    const payloadBytes = textEncoder.encode(payloadJson).byteLength;
+    const runAgeMs = Math.max(0, loggedAtMs - runState.firstSeenLoggedAtMs);
+    const runDurationMs =
+      runState.sawSessionIdle || runState.sawSessionError ? runAgeMs : undefined;
+
+    if (toolCompleteWithoutStart) {
+      runState.pendingToolCalls = 0;
+    }
+
+    // Include agent tree snapshot on agent lifecycle events and session errors
+    const includeTreeSnapshot =
+      isAgentLifecycleEvent(event.type) || isSessionErrorEventType(event.type);
+    const treeSnapshot = includeTreeSnapshot ? buildAgentTreeSnapshot() : undefined;
+
+    const entry: EventLogEntry = {
+      seq: ++seq,
+      runSeq: nextRunSeq,
+      ts: new Date(event.timestamp).toISOString(),
+      loggedAt: new Date(loggedAtMs).toISOString(),
+      type: event.type,
+      sessionId: event.sessionId,
+      runId: event.runId,
+      eventLagMs: loggedAtMs - event.timestamp,
+      globalGapMs,
+      sessionRunGapMs,
+      ...(continuityGapMs !== undefined ? { continuityGapMs } : {}),
+      ...(eventTimestampRegressionMs !== undefined ? { eventTimestampRegressionMs } : {}),
+      streamGapMs,
+      runAgeMs,
+      ...(runDurationMs !== undefined ? { runDurationMs } : {}),
+      streamEventCount: runState.streamEventCount,
+      textDeltaCount: runState.textDeltaCount,
+      thinkingDeltaCount: runState.thinkingDeltaCount,
+      toolStartCount: runState.toolStartCount,
+      toolCompleteCount: runState.toolCompleteCount,
+      pendingToolCalls: runState.pendingToolCalls,
+      maxPendingToolCalls: runState.maxPendingToolCalls,
+      ...(lifecycleMarkers.length > 0 ? { lifecycleMarkers } : {}),
+      payloadBytes,
+      ...(treeSnapshot ? { agentTreeSnapshot: treeSnapshot } : {}),
+      data: event.data,
+    };
+    writer.write(JSON.stringify(entry) + "\n");
+    writer.flush();
+    writeRawForEvent(event, runState, loggedAtMs);
+  };
+
+  const writeDiagnostic = (partial: Omit<DiagnosticLogEntry, "seq" | "ts">): void => {
+    const entry: DiagnosticLogEntry = {
+      seq: ++seq,
+      ts: new Date().toISOString(),
+      ...partial,
+      agentTreeSnapshot: partial.agentTreeSnapshot ?? buildAgentTreeSnapshot(),
+    };
+    writer.write(JSON.stringify(entry) + "\n");
+    writer.flush();
+    const diagnosticMessage =
+      partial.error
+        ? `[${partial.category}] ${partial.error}`
+        : `[${partial.category}]`;
+    writeRawLine(diagnosticMessage, { component: "diagnostic" });
+  };
+
+  const getAgentTreeSnapshot = (): AgentTreeSnapshot => buildAgentTreeSnapshot();
+
+  const close = async (): Promise<void> => {
+    const eventWriterResult = writer.end();
+    const rawWriterResult = rawWriter.end();
+    // Bun's writer.end() can return either number (sync) or Promise<number> (async)
+    // We must await when it is a Promise to ensure all data is flushed.
+    if (eventWriterResult instanceof Promise) {
+      await eventWriterResult;
+    }
+    if (rawWriterResult instanceof Promise) {
+      await rawWriterResult;
+    }
+  };
+
+  return {
+    write,
+    writeDiagnostic,
+    writeRawLine,
+    getAgentTreeSnapshot,
+    close,
+    logPath,
+    rawLogPath,
+    logDirPath,
+  };
+}
+
+/**
+ * Read and parse events from a JSONL event log file.
+ * Replaces the in-memory EventReplayBuffer with file-based replay.
+ */
+export async function readEventLog(
+  logPath: string,
+  filter?: (entry: EventLogEntry) => boolean,
+): Promise<EventLogEntry[]> {
+  const file = Bun.file(logPath);
+  const exists = await file.exists();
+  if (!exists) return [];
+  const content = await file.text();
+  const entries = content
+    .trim()
+    .split("\n")
+    .filter(Boolean)
+    .map((line) => JSON.parse(line) as EventLogEntry);
+  return filter ? entries.filter(filter) : entries;
+}
+
+/**
+ * Read raw UI stream log lines.
+ */
+export async function readRawStreamLog(rawLogPath: string): Promise<string[]> {
+  const file = Bun.file(rawLogPath);
+  const exists = await file.exists();
+  if (!exists) return [];
+  const content = await file.text();
+  if (!content.trim()) return [];
+  return content
+    .split("\n")
+    .map((line) => line.trimEnd())
+    .filter((line) => line.length > 0);
+}
+
+/**
+ * List all available event log files, most recent first.
+ */
+export async function listEventLogs(dir: string = DEFAULT_LOG_DIR): Promise<string[]> {
+  const sessionDirs = await listLogSessionDirectories(dir);
+  const sessionEventLogs = sessionDirs
+    .map((sessionDir) => join(sessionDir, LOG_EVENTS_FILENAME));
+
+  sessionEventLogs.sort();
+  return sessionEventLogs.reverse();
+}
+
+/**
+ * Attach a file-based debug subscriber to the event bus.
+ * When stream debug logging is enabled, all events are written to a JSONL log file
+ * with automatic rotation (10 most recent files retained).
+ *
+ * Also retains console.debug logging for real-time visibility.
+ *
+ * @param bus - The event bus to attach the debug subscriber to
+ * @returns Promise with unsubscribe function and log file path
+ */
+export async function attachDebugSubscriber(bus: EventBus): Promise<{
+  unsubscribe: () => Promise<void>;
+  logPath: string | null;
+  rawLogPath: string | null;
+  logDirPath: string | null;
+  writeRawLine: (line: string, metadata?: { sessionId?: string; runId?: number; component?: RawStreamLogEntry["component"] }) => void;
+}> {
+  const debugConfig = resolveStreamDebugLogConfig();
+  if (!debugConfig.enabled) {
+    return {
+      unsubscribe: async () => {},
+      logPath: null,
+      rawLogPath: null,
+      logDirPath: null,
+      writeRawLine: () => {},
+    };
+  }
+
+  const {
+    write,
+    writeDiagnostic,
+    writeRawLine,
+    close,
+    logPath,
+    rawLogPath,
+    logDirPath,
+  } = await initEventLog({
+    logDir: debugConfig.logDir,
+  });
+
+  // Write startup metadata as the first entry
+  writeDiagnostic({
+    category: "startup",
+    data: {
+      pid: process.pid,
+      platform: process.platform,
+      arch: process.arch,
+      nodeVersion: process.version,
+      bunVersion: typeof Bun !== "undefined" ? Bun.version : undefined,
+      cwd: process.cwd(),
+      debugConfig,
+      env: {
+        DEBUG: process.env.DEBUG,
+        LOG_DIR: process.env.LOG_DIR,
+        NODE_ENV: process.env.NODE_ENV,
+      },
+      argv: process.argv,
+      memoryUsage: process.memoryUsage(),
+    },
+  });
+
+  const unsubBus = bus.onAll((event: BusEvent) => {
+    write(event);
+    if (debugConfig.consolePreviewEnabled) {
+      const preview = JSON.stringify(event.data).slice(0, 100);
+      console.debug(
+        `[EventBus] ${event.type} run=${event.runId} ${preview}`,
+      );
+    }
+  });
+
+  // Capture internal bus errors (schema drops, handler failures)
+  const unsubInternalError = bus.onInternalError((busError) => {
+    writeDiagnostic({
+      category: "bus_error",
+      error: busError.error instanceof Error ? busError.error.message : String(busError.error),
+      stack: busError.error instanceof Error ? busError.error.stack : undefined,
+      data: {
+        kind: busError.kind,
+        eventType: busError.eventType,
+        eventData: busError.eventData,
+      },
+    });
+  });
+
+  // Capture process-level errors
+  const onUncaughtException = (error: Error): void => {
+    writeDiagnostic({
+      category: "process_error",
+      error: error.message,
+      stack: error.stack,
+      data: { kind: "uncaughtException", name: error.name },
+    });
+  };
+
+  const onUnhandledRejection = (reason: unknown): void => {
+    writeDiagnostic({
+      category: "process_error",
+      error: reason instanceof Error ? reason.message : String(reason),
+      stack: reason instanceof Error ? reason.stack : undefined,
+      data: { kind: "unhandledRejection" },
+    });
+  };
+
+  process.on("uncaughtException", onUncaughtException);
+  process.on("unhandledRejection", onUnhandledRejection);
+
+  const unsubscribe = async (): Promise<void> => {
+    unsubBus();
+    unsubInternalError();
+    process.removeListener("uncaughtException", onUncaughtException);
+    process.removeListener("unhandledRejection", onUnhandledRejection);
+    await close();
+  };
+
+  return { unsubscribe, logPath, rawLogPath, logDirPath, writeRawLine };
+}
diff --git a/src/events/event-bus-provider.tsx b/src/events/event-bus-provider.tsx
new file mode 100644
index 0000000000..1b4131e166
--- /dev/null
+++ b/src/events/event-bus-provider.tsx
@@ -0,0 +1,125 @@
+/**
+ * Event Bus Provider for React Context
+ *
+ * This module provides a React context provider for the EventBus singleton.
+ * The event bus and batch dispatcher are created once and shared across the
+ * entire application via React context.
+ *
+ * Key features:
+ * - Singleton pattern: bus and dispatcher created once via useMemo
+ * - Context throws if used outside provider for early error detection
+ * - No cleanup needed since these are app-lifetime singletons
+ *
+ * Usage:
+ * ```typescript
+ * // In your app root:
+ * <EventBusProvider>
+ *   <YourApp />
+ * </EventBusProvider>
+ *
+ * // In your components:
+ * const { bus, dispatcher } = useEventBusContext();
+ * ```
+ */
+
+import React, { createContext, useContext, useMemo } from "react";
+import { EventBus } from "./event-bus.ts";
+import { BatchDispatcher } from "./batch-dispatcher.ts";
+
+/**
+ * Context value containing the event bus singleton and batch dispatcher.
+ */
+interface EventBusContextValue {
+  /** The global event bus for pub/sub operations */
+  bus: EventBus;
+  /** The batch dispatcher for efficient event batching */
+  dispatcher: BatchDispatcher;
+}
+
+/**
+ * React context for the event bus singleton.
+ * @internal
+ */
+const EventBusContext = createContext<EventBusContextValue | null>(null);
+
+/**
+ * Provider component for the event bus singleton.
+ *
+ * Creates a singleton instance of the EventBus and BatchDispatcher
+ * that persists for the lifetime of the application. These instances are
+ * shared across all components via React context.
+ *
+ * The bus and dispatcher are created once via useMemo and never re-created,
+ * ensuring consistent event routing throughout the app.
+ *
+ * @example
+ * ```typescript
+ * function App() {
+ *   return (
+ *     <EventBusProvider>
+ *       <ChatUI />
+ *     </EventBusProvider>
+ *   );
+ * }
+ * ```
+ */
+interface EventBusProviderProps {
+  children: React.ReactNode;
+  bus?: EventBus;
+  dispatcher?: BatchDispatcher;
+}
+
+export function EventBusProvider({ children, bus: externalBus, dispatcher: externalDispatcher }: EventBusProviderProps) {
+  const value = useMemo(() => {
+    const bus = externalBus ?? new EventBus();
+    const dispatcher = externalDispatcher ?? new BatchDispatcher(bus);
+    return { bus, dispatcher };
+  }, [externalBus, externalDispatcher]);
+
+  return (
+    <EventBusContext.Provider value={value}>
+      {children}
+    </EventBusContext.Provider>
+  );
+}
+
+/**
+ * Hook to access the event bus context.
+ *
+ * Returns the singleton event bus and batch dispatcher instances.
+ * Throws an error if called outside of an EventBusProvider, ensuring
+ * early detection of incorrect usage.
+ *
+ * @returns The event bus context value containing bus and dispatcher
+ * @throws Error if used outside EventBusProvider
+ *
+ * @example
+ * ```typescript
+ * function MyComponent() {
+ *   const { bus, dispatcher } = useEventBusContext();
+ *
+ *   // Subscribe to events
+ *   useEffect(() => {
+ *     return bus.on("stream.text.delta", (event) => {
+ *       console.log(event.data.delta);
+ *     });
+ *   }, [bus]);
+ *
+ *   // Enqueue events
+ *   dispatcher.enqueue({
+ *     type: "stream.text.delta",
+ *     sessionId: "abc123",
+ *     runId: 1,
+ *     timestamp: Date.now(),
+ *     data: { delta: "Hello", messageId: "msg1" }
+ *   });
+ * }
+ * ```
+ */
+export function useEventBusContext(): EventBusContextValue {
+  const ctx = useContext(EventBusContext);
+  if (!ctx) {
+    throw new Error("useEventBusContext must be used within an EventBusProvider");
+  }
+  return ctx;
+}
diff --git a/src/events/event-bus.test.ts b/src/events/event-bus.test.ts
new file mode 100644
index 0000000000..fda43296dc
--- /dev/null
+++ b/src/events/event-bus.test.ts
@@ -0,0 +1,542 @@
+/**
+ * Unit tests for EventBus
+ *
+ * Tests the core event bus functionality including:
+ * - Type-safe event subscription and publishing
+ * - Wildcard subscriptions
+ * - Error isolation
+ * - Handler management and cleanup
+ */
+
+import { describe, it, expect, beforeEach, mock, spyOn } from "bun:test";
+import { EventBus } from "./event-bus.ts";
+import type { BusEvent } from "./bus-events.ts";
+
+describe("EventBus", () => {
+  let bus: EventBus;
+
+  beforeEach(() => {
+    bus = new EventBus();
+  });
+
+  describe("on() - typed subscriptions", () => {
+    it("should subscribe and receive events for specific type", () => {
+      const handler = mock();
+      bus.on("stream.text.delta", handler);
+
+      const event: BusEvent<"stream.text.delta"> = {
+        type: "stream.text.delta",
+        sessionId: "test-session",
+        runId: 1,
+        timestamp: Date.now(),
+        data: { delta: "Hello", messageId: "msg1" },
+      };
+
+      bus.publish(event);
+
+      expect(handler).toHaveBeenCalledTimes(1);
+      expect(handler).toHaveBeenCalledWith(event);
+    });
+
+    it("should support multiple handlers for same event type", () => {
+      const handler1 = mock();
+      const handler2 = mock();
+
+      bus.on("stream.text.delta", handler1);
+      bus.on("stream.text.delta", handler2);
+
+      const event: BusEvent<"stream.text.delta"> = {
+        type: "stream.text.delta",
+        sessionId: "test-session",
+        runId: 1,
+        timestamp: Date.now(),
+        data: { delta: "Hello", messageId: "msg1" },
+      };
+
+      bus.publish(event);
+
+      expect(handler1).toHaveBeenCalledTimes(1);
+      expect(handler2).toHaveBeenCalledTimes(1);
+    });
+
+    it("should only notify handlers for matching event type", () => {
+      const textHandler = mock();
+      const toolHandler = mock();
+
+      bus.on("stream.text.delta", textHandler);
+      bus.on("stream.tool.start", toolHandler);
+
+      const textEvent: BusEvent<"stream.text.delta"> = {
+        type: "stream.text.delta",
+        sessionId: "test-session",
+        runId: 1,
+        timestamp: Date.now(),
+        data: { delta: "Hello", messageId: "msg1" },
+      };
+
+      bus.publish(textEvent);
+
+      expect(textHandler).toHaveBeenCalledTimes(1);
+      expect(toolHandler).not.toHaveBeenCalled();
+    });
+
+    it("should return unsubscribe function that removes handler", () => {
+      const handler = mock();
+      const unsubscribe = bus.on("stream.text.delta", handler);
+
+      const event: BusEvent<"stream.text.delta"> = {
+        type: "stream.text.delta",
+        sessionId: "test-session",
+        runId: 1,
+        timestamp: Date.now(),
+        data: { delta: "Hello", messageId: "msg1" },
+      };
+
+      bus.publish(event);
+      expect(handler).toHaveBeenCalledTimes(1);
+
+      // Unsubscribe
+      unsubscribe();
+
+      // Publish again - handler should not be called
+      bus.publish(event);
+      expect(handler).toHaveBeenCalledTimes(1); // Still 1, not 2
+    });
+
+    it("should handle unsubscribe being called multiple times", () => {
+      const handler = mock();
+      const unsubscribe = bus.on("stream.text.delta", handler);
+
+      unsubscribe();
+      unsubscribe(); // Should not throw
+
+      expect(() => unsubscribe()).not.toThrow();
+    });
+  });
+
+  describe("onAll() - wildcard subscriptions", () => {
+    it("should receive all event types", () => {
+      const wildcardHandler = mock();
+      bus.onAll(wildcardHandler);
+
+      const textEvent: BusEvent<"stream.text.delta"> = {
+        type: "stream.text.delta",
+        sessionId: "test-session",
+        runId: 1,
+        timestamp: Date.now(),
+        data: { delta: "Hello", messageId: "msg1" },
+      };
+
+      const toolEvent: BusEvent<"stream.tool.start"> = {
+        type: "stream.tool.start",
+        sessionId: "test-session",
+        runId: 1,
+        timestamp: Date.now(),
+        data: {
+          toolId: "tool1",
+          toolName: "bash",
+          toolInput: { command: "ls" },
+        },
+      };
+
+      bus.publish(textEvent);
+      bus.publish(toolEvent);
+
+      expect(wildcardHandler).toHaveBeenCalledTimes(2);
+      expect(wildcardHandler).toHaveBeenCalledWith(textEvent);
+      expect(wildcardHandler).toHaveBeenCalledWith(toolEvent);
+    });
+
+    it("should support multiple wildcard handlers", () => {
+      const handler1 = mock();
+      const handler2 = mock();
+
+      bus.onAll(handler1);
+      bus.onAll(handler2);
+
+      const event: BusEvent<"stream.text.delta"> = {
+        type: "stream.text.delta",
+        sessionId: "test-session",
+        runId: 1,
+        timestamp: Date.now(),
+        data: { delta: "Hello", messageId: "msg1" },
+      };
+
+      bus.publish(event);
+
+      expect(handler1).toHaveBeenCalledTimes(1);
+      expect(handler2).toHaveBeenCalledTimes(1);
+    });
+
+    it("should return unsubscribe function for wildcard handlers", () => {
+      const handler = mock();
+      const unsubscribe = bus.onAll(handler);
+
+      const event: BusEvent<"stream.text.delta"> = {
+        type: "stream.text.delta",
+        sessionId: "test-session",
+        runId: 1,
+        timestamp: Date.now(),
+        data: { delta: "Hello", messageId: "msg1" },
+      };
+
+      bus.publish(event);
+      expect(handler).toHaveBeenCalledTimes(1);
+
+      unsubscribe();
+
+      bus.publish(event);
+      expect(handler).toHaveBeenCalledTimes(1); // Still 1
+    });
+  });
+
+  describe("publish() - event dispatching", () => {
+    it("should dispatch to both typed and wildcard handlers", () => {
+      const typedHandler = mock();
+      const wildcardHandler = mock();
+
+      bus.on("stream.text.delta", typedHandler);
+      bus.onAll(wildcardHandler);
+
+      const event: BusEvent<"stream.text.delta"> = {
+        type: "stream.text.delta",
+        sessionId: "test-session",
+        runId: 1,
+        timestamp: Date.now(),
+        data: { delta: "Hello", messageId: "msg1" },
+      };
+
+      bus.publish(event);
+
+      expect(typedHandler).toHaveBeenCalledTimes(1);
+      expect(wildcardHandler).toHaveBeenCalledTimes(1);
+    });
+
+    it("should isolate handler errors and continue dispatching", () => {
+      const errorHandler = mock(() => {
+        throw new Error("Handler error");
+      });
+      const successHandler = mock();
+
+      // Spy on console.error to verify error logging
+      const consoleErrorSpy = spyOn(console, "error").mockImplementation(() => {});
+
+      bus.on("stream.text.delta", errorHandler);
+      bus.on("stream.text.delta", successHandler);
+
+      const event: BusEvent<"stream.text.delta"> = {
+        type: "stream.text.delta",
+        sessionId: "test-session",
+        runId: 1,
+        timestamp: Date.now(),
+        data: { delta: "Hello", messageId: "msg1" },
+      };
+
+      // Should not throw
+      expect(() => bus.publish(event)).not.toThrow();
+
+      // Both handlers should have been called
+      expect(errorHandler).toHaveBeenCalledTimes(1);
+      expect(successHandler).toHaveBeenCalledTimes(1);
+
+      // Error should be logged
+      expect(consoleErrorSpy).toHaveBeenCalledWith(
+        expect.stringContaining("[EventBus] Error in handler for stream.text.delta"),
+        expect.any(Error)
+      );
+
+      consoleErrorSpy.mockRestore();
+    });
+
+    it("should isolate wildcard handler errors", () => {
+      const errorWildcardHandler = mock(() => {
+        throw new Error("Wildcard error");
+      });
+      const successWildcardHandler = mock();
+
+      const consoleErrorSpy = spyOn(console, "error").mockImplementation(() => {});
+
+      bus.onAll(errorWildcardHandler);
+      bus.onAll(successWildcardHandler);
+
+      const event: BusEvent<"stream.text.delta"> = {
+        type: "stream.text.delta",
+        sessionId: "test-session",
+        runId: 1,
+        timestamp: Date.now(),
+        data: { delta: "Hello", messageId: "msg1" },
+      };
+
+      expect(() => bus.publish(event)).not.toThrow();
+
+      expect(errorWildcardHandler).toHaveBeenCalledTimes(1);
+      expect(successWildcardHandler).toHaveBeenCalledTimes(1);
+
+      expect(consoleErrorSpy).toHaveBeenCalledWith(
+        expect.stringContaining("[EventBus] Error in wildcard handler"),
+        expect.any(Error)
+      );
+
+      consoleErrorSpy.mockRestore();
+    });
+
+    it("should handle publishing when no handlers are registered", () => {
+      const event: BusEvent<"stream.text.delta"> = {
+        type: "stream.text.delta",
+        sessionId: "test-session",
+        runId: 1,
+        timestamp: Date.now(),
+        data: { delta: "Hello", messageId: "msg1" },
+      };
+
+      // Should not throw
+      expect(() => bus.publish(event)).not.toThrow();
+    });
+  });
+
+  describe("clear() - cleanup", () => {
+    it("should remove all handlers", () => {
+      const typedHandler = mock();
+      const wildcardHandler = mock();
+
+      bus.on("stream.text.delta", typedHandler);
+      bus.onAll(wildcardHandler);
+
+      expect(bus.handlerCount).toBe(2);
+
+      bus.clear();
+
+      expect(bus.handlerCount).toBe(0);
+
+      const event: BusEvent<"stream.text.delta"> = {
+        type: "stream.text.delta",
+        sessionId: "test-session",
+        runId: 1,
+        timestamp: Date.now(),
+        data: { delta: "Hello", messageId: "msg1" },
+      };
+
+      bus.publish(event);
+
+      expect(typedHandler).not.toHaveBeenCalled();
+      expect(wildcardHandler).not.toHaveBeenCalled();
+    });
+
+    it("should allow new subscriptions after clear", () => {
+      const handler = mock();
+
+      bus.on("stream.text.delta", handler);
+      bus.clear();
+
+      const newHandler = mock();
+      bus.on("stream.text.delta", newHandler);
+
+      const event: BusEvent<"stream.text.delta"> = {
+        type: "stream.text.delta",
+        sessionId: "test-session",
+        runId: 1,
+        timestamp: Date.now(),
+        data: { delta: "Hello", messageId: "msg1" },
+      };
+
+      bus.publish(event);
+
+      expect(handler).not.toHaveBeenCalled();
+      expect(newHandler).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe("hasHandlers() - introspection", () => {
+    it("should return true when handlers exist for event type", () => {
+      bus.on("stream.text.delta", () => {});
+
+      expect(bus.hasHandlers("stream.text.delta")).toBe(true);
+    });
+
+    it("should return false when no handlers exist for event type", () => {
+      expect(bus.hasHandlers("stream.text.delta")).toBe(false);
+    });
+
+    it("should return false after all handlers are unsubscribed", () => {
+      const unsubscribe = bus.on("stream.text.delta", () => {});
+
+      expect(bus.hasHandlers("stream.text.delta")).toBe(true);
+
+      unsubscribe();
+
+      expect(bus.hasHandlers("stream.text.delta")).toBe(false);
+    });
+
+    it("should not count wildcard handlers", () => {
+      bus.onAll(() => {});
+
+      expect(bus.hasHandlers("stream.text.delta")).toBe(false);
+    });
+  });
+
+  describe("handlerCount - introspection", () => {
+    it("should count typed handlers", () => {
+      expect(bus.handlerCount).toBe(0);
+
+      bus.on("stream.text.delta", () => {});
+      expect(bus.handlerCount).toBe(1);
+
+      bus.on("stream.text.delta", () => {});
+      expect(bus.handlerCount).toBe(2);
+
+      bus.on("stream.tool.start", () => {});
+      expect(bus.handlerCount).toBe(3);
+    });
+
+    it("should count wildcard handlers", () => {
+      bus.onAll(() => {});
+      expect(bus.handlerCount).toBe(1);
+
+      bus.onAll(() => {});
+      expect(bus.handlerCount).toBe(2);
+    });
+
+    it("should count both typed and wildcard handlers", () => {
+      bus.on("stream.text.delta", () => {});
+      bus.onAll(() => {});
+
+      expect(bus.handlerCount).toBe(2);
+    });
+
+    it("should decrease count after unsubscribe", () => {
+      const unsubscribe1 = bus.on("stream.text.delta", () => {});
+      const unsubscribe2 = bus.onAll(() => {});
+
+      expect(bus.handlerCount).toBe(2);
+
+      unsubscribe1();
+      expect(bus.handlerCount).toBe(1);
+
+      unsubscribe2();
+      expect(bus.handlerCount).toBe(0);
+    });
+  });
+
+  describe("publish() - Zod schema validation", () => {
+    it("should skip schema validation when no subscribers are registered", () => {
+      const consoleErrorSpy = spyOn(console, "error").mockImplementation(() => {});
+
+      const invalidEvent = {
+        type: "stream.text.delta" as const,
+        sessionId: "s1",
+        runId: 1,
+        timestamp: Date.now(),
+        data: { delta: 123, messageId: "msg1" },
+      };
+
+      expect(() => bus.publish(invalidEvent as any)).not.toThrow();
+      expect(consoleErrorSpy).not.toHaveBeenCalled();
+
+      consoleErrorSpy.mockRestore();
+    });
+
+    it("should reject event with invalid payload type (delta should be string)", () => {
+      const handler = mock();
+      bus.on("stream.text.delta", handler);
+
+      const consoleErrorSpy = spyOn(console, "error").mockImplementation(() => {});
+
+      // delta should be string, not number
+      const invalidEvent = {
+        type: "stream.text.delta" as const,
+        sessionId: "s1",
+        runId: 1,
+        timestamp: Date.now(),
+        data: { delta: 123, messageId: "msg1" },
+      };
+
+      bus.publish(invalidEvent as any);
+      expect(handler).not.toHaveBeenCalled();
+      expect(consoleErrorSpy).toHaveBeenCalledWith(
+        expect.stringContaining("[EventBus] Schema validation failed for stream.text.delta"),
+        expect.anything()
+      );
+
+      consoleErrorSpy.mockRestore();
+    });
+
+    it("should reject event with missing required fields", () => {
+      const handler = mock();
+      bus.on("stream.text.delta", handler);
+
+      const consoleErrorSpy = spyOn(console, "error").mockImplementation(() => {});
+
+      // Missing messageId field
+      const invalidEvent = {
+        type: "stream.text.delta" as const,
+        sessionId: "s1",
+        runId: 1,
+        timestamp: Date.now(),
+        data: { delta: "hello" },
+      };
+
+      bus.publish(invalidEvent as any);
+      expect(handler).not.toHaveBeenCalled();
+      expect(consoleErrorSpy).toHaveBeenCalled();
+
+      consoleErrorSpy.mockRestore();
+    });
+
+    it("should reject event with wrong nested types", () => {
+      const handler = mock();
+      bus.on("stream.tool.start", handler);
+
+      const consoleErrorSpy = spyOn(console, "error").mockImplementation(() => {});
+
+      // toolInput should be Record<string, unknown>, not string
+      const invalidEvent = {
+        type: "stream.tool.start" as const,
+        sessionId: "s1",
+        runId: 1,
+        timestamp: Date.now(),
+        data: { toolId: "t1", toolName: "bash", toolInput: "not-an-object" },
+      };
+
+      bus.publish(invalidEvent as any);
+      expect(handler).not.toHaveBeenCalled();
+
+      consoleErrorSpy.mockRestore();
+    });
+
+    it("should accept valid events and dispatch to handlers", () => {
+      const handler = mock();
+      bus.on("stream.text.delta", handler);
+
+      const validEvent: BusEvent<"stream.text.delta"> = {
+        type: "stream.text.delta",
+        sessionId: "s1",
+        runId: 1,
+        timestamp: Date.now(),
+        data: { delta: "hello", messageId: "msg1" },
+      };
+
+      bus.publish(validEvent);
+      expect(handler).toHaveBeenCalledTimes(1);
+    });
+
+    it("should not dispatch to wildcard handlers on validation failure", () => {
+      const wildcardHandler = mock();
+      bus.onAll(wildcardHandler);
+
+      const consoleErrorSpy = spyOn(console, "error").mockImplementation(() => {});
+
+      const invalidEvent = {
+        type: "stream.thinking.complete" as const,
+        sessionId: "s1",
+        runId: 1,
+        timestamp: Date.now(),
+        data: { sourceKey: "k1", durationMs: "not-a-number" }, // should be number
+      };
+
+      bus.publish(invalidEvent as any);
+      expect(wildcardHandler).not.toHaveBeenCalled();
+
+      consoleErrorSpy.mockRestore();
+    });
+  });
+});
diff --git a/src/events/event-bus.ts b/src/events/event-bus.ts
new file mode 100644
index 0000000000..24f646b4b7
--- /dev/null
+++ b/src/events/event-bus.ts
@@ -0,0 +1,332 @@
+/**
+ * Event Bus Implementation
+ *
+ * This module provides the core event bus implementation for the streaming architecture.
+ * The EventBus class manages type-safe pub/sub for all streaming events across
+ * multiple SDK adapters and workflow nodes.
+ *
+ * Key features:
+ * - Type-safe event publishing and subscription
+ * - Support for wildcard subscriptions (subscribe to all events)
+ * - Error isolation (handler errors don't break publishers)
+ * - Efficient handler management with automatic cleanup
+ */
+
+import type {
+  BusEvent,
+  BusEventType,
+  BusHandler,
+  WildcardHandler,
+} from "./bus-events.ts";
+import { BusEventSchemas } from "./bus-events.ts";
+import { pipelineLog, pipelineError } from "./pipeline-logger.ts";
+
+/**
+ * Internal error reported by the event bus itself.
+ * These errors are not BusEvents — they represent failures in
+ * event dispatch (schema validation, handler exceptions) that
+ * would otherwise only go to console.error and be lost in TUI mode.
+ */
+export interface InternalBusError {
+  /** Kind of internal error */
+  kind: "schema_validation" | "handler_error" | "wildcard_handler_error" | "contract_violation";
+  /** Event type that triggered the error */
+  eventType: string;
+  /** The error object */
+  error: unknown;
+  /** Event data that caused the error (included for schema_validation) */
+  eventData?: unknown;
+}
+
+export type InternalErrorHandler = (error: InternalBusError) => void;
+
+export interface EventBusOptions {
+  /**
+   * Enable runtime payload validation with Zod before dispatch.
+   * Keep enabled for tests/debugging; disable in the TUI hot path for performance.
+   */
+  validatePayloads?: boolean;
+}
+
+/**
+ * Core event bus for the streaming architecture.
+ *
+ * Manages typed pub/sub for all streaming events from SDK adapters and workflows.
+ * Provides type safety, wildcard subscriptions, and error isolation between handlers.
+ *
+ * Usage:
+ * ```typescript
+ * const bus = new EventBus();
+ *
+ * // Subscribe to specific event type
+ * const unsubscribe = bus.on("stream.text.delta", (event) => {
+ *   console.log(event.data.delta);
+ * });
+ *
+ * // Subscribe to all events
+ * const unsubscribeAll = bus.onAll((event) => {
+ *   console.log(`[${event.type}]`, event.data);
+ * });
+ *
+ * // Publish an event
+ * bus.publish({
+ *   type: "stream.text.delta",
+ *   sessionId: "abc123",
+ *   runId: 1,
+ *   timestamp: Date.now(),
+ *   data: { delta: "Hello", messageId: "msg1" }
+ * });
+ *
+ * // Cleanup
+ * unsubscribe();
+ * unsubscribeAll();
+ * ```
+ */
+export class EventBus {
+  private handlers = new Map<BusEventType, Set<BusHandler<BusEventType>>>();
+  private wildcardHandlers = new Set<WildcardHandler>();
+  private internalErrorHandlers = new Set<InternalErrorHandler>();
+  private validatePayloads: boolean;
+
+  constructor(options: EventBusOptions = {}) {
+    this.validatePayloads = options.validatePayloads ?? true;
+  }
+
+  /**
+   * Subscribe to internal bus errors (schema drops, handler exceptions).
+   *
+   * These errors are normally only logged to console.error and lost
+   * when running inside a TUI. This callback enables the debug subscriber
+   * to write them to the JSONL log file.
+   *
+   * @param handler - Callback invoked on each internal error
+   * @returns Unsubscribe function
+   */
+  onInternalError(handler: InternalErrorHandler): () => void {
+    this.internalErrorHandlers.add(handler);
+    return () => {
+      this.internalErrorHandlers.delete(handler);
+    };
+  }
+
+  private emitInternalError(error: InternalBusError): void {
+    for (const handler of this.internalErrorHandlers) {
+      try {
+        handler(error);
+      } catch {
+        // Swallow to avoid infinite recursion
+      }
+    }
+  }
+
+  /**
+   * Report an application-level error through the internal error channel.
+   *
+   * Unlike schema/handler errors which are detected by the bus itself,
+   * this allows external code (e.g., contract violation detectors) to
+   * emit errors that get captured by the debug subscriber's JSONL log.
+   *
+   * @param error - The error to report
+   */
+  reportError(error: InternalBusError): void {
+    this.emitInternalError(error);
+  }
+
+  /**
+   * Subscribe to a specific event type.
+   *
+   * Returns an unsubscribe function that removes the handler when called.
+   *
+   * @param type - The event type to subscribe to
+   * @param handler - Callback function to handle the event
+   * @returns Unsubscribe function
+   *
+   * @example
+   * ```typescript
+   * const unsubscribe = bus.on("stream.tool.start", (event) => {
+   *   console.log(`Tool started: ${event.data.toolName}`);
+   * });
+   *
+   * // Later, cleanup
+   * unsubscribe();
+   * ```
+   */
+  on<T extends BusEventType>(type: T, handler: BusHandler<T>): () => void {
+    let set = this.handlers.get(type);
+    if (!set) {
+      set = new Set();
+      this.handlers.set(type, set);
+    }
+    set.add(handler as BusHandler<BusEventType>);
+    return () => {
+      set?.delete(handler as BusHandler<BusEventType>);
+      if (set && set.size === 0) {
+        this.handlers.delete(type);
+      }
+    };
+  }
+
+  /**
+   * Subscribe to all events (wildcard subscription).
+   *
+   * Useful for debugging, logging, and observability.
+   * Returns an unsubscribe function that removes the handler when called.
+   *
+   * @param handler - Callback function to handle all events
+   * @returns Unsubscribe function
+   *
+   * @example
+   * ```typescript
+   * const unsubscribe = bus.onAll((event) => {
+   *   console.log(`[${event.type}] at ${event.timestamp}`, event.data);
+   * });
+   * ```
+   */
+  onAll(handler: WildcardHandler): () => void {
+    this.wildcardHandlers.add(handler);
+    return () => {
+      this.wildcardHandlers.delete(handler);
+    };
+  }
+
+  /**
+   * Publish an event to all matching subscribers.
+   *
+   * Dispatches the event to:
+   * 1. All handlers subscribed to the specific event type
+   * 2. All wildcard handlers subscribed to all events
+   *
+   * Handler errors are caught and logged to prevent breaking the publisher.
+   * This ensures that one broken handler doesn't affect other handlers or the event source.
+   *
+   * @param event - The event to publish
+   *
+   * @example
+   * ```typescript
+   * bus.publish({
+   *   type: "stream.text.delta",
+   *   sessionId: "abc123",
+   *   runId: 1,
+   *   timestamp: Date.now(),
+   *   data: { delta: "Hello", messageId: "msg1" }
+   * });
+   * ```
+   */
+  publish<T extends BusEventType>(event: BusEvent<T>): void {
+    const handlers = this.handlers.get(event.type);
+    const hasTypedHandlers = handlers !== undefined && handlers.size > 0;
+    const hasWildcardHandlers = this.wildcardHandlers.size > 0;
+    if (!hasTypedHandlers && !hasWildcardHandlers) {
+      return;
+    }
+
+    // Validate event data with Zod schema before dispatch
+    const schema = this.validatePayloads ? BusEventSchemas[event.type] : undefined;
+    if (schema) {
+      try {
+        schema.parse(event.data);
+      } catch (error) {
+        pipelineError("EventBus", "schema_drop", { type: event.type });
+        console.error(`[EventBus] Schema validation failed for ${event.type}:`, error);
+        // DEBUG: Log the actual event data that failed validation
+        if (event.type.startsWith("stream.tool.")) {
+          console.error(`[EventBus] Rejected tool event data:`, JSON.stringify(event.data));
+        }
+        this.emitInternalError({
+          kind: "schema_validation",
+          eventType: event.type,
+          error,
+          eventData: event.data,
+        });
+        return;
+      }
+    }
+
+    // Dispatch to typed handlers
+    if (hasTypedHandlers && handlers) {
+      for (const handler of handlers) {
+        try {
+          handler(event as BusEvent<BusEventType>);
+        } catch (error) {
+          pipelineError("EventBus", "handler_error", { type: event.type });
+          console.error(`[EventBus] Error in handler for ${event.type}:`, error);
+          this.emitInternalError({
+            kind: "handler_error",
+            eventType: event.type,
+            error,
+          });
+        }
+      }
+    }
+
+    // Dispatch to wildcard handlers
+    for (const handler of this.wildcardHandlers) {
+      try {
+        handler(event);
+      } catch (error) {
+        pipelineError("EventBus", "wildcard_handler_error", { type: event.type });
+        console.error(`[EventBus] Error in wildcard handler:`, error);
+        this.emitInternalError({
+          kind: "wildcard_handler_error",
+          eventType: event.type,
+          error,
+        });
+      }
+    }
+  }
+
+  /**
+   * Remove all handlers and reset bus state.
+   *
+   * Useful for cleanup in tests or when shutting down the application.
+   *
+   * @example
+   * ```typescript
+   * bus.clear();
+   * ```
+   */
+  clear(): void {
+    this.handlers.clear();
+    this.wildcardHandlers.clear();
+  }
+
+  /**
+   * Check if any handlers are registered for a specific event type.
+   *
+   * Does not count wildcard handlers.
+   *
+   * @param type - The event type to check
+   * @returns True if handlers are registered for this type
+   *
+   * @example
+   * ```typescript
+   * if (bus.hasHandlers("stream.tool.start")) {
+   *   console.log("Tool start handlers are registered");
+   * }
+   * ```
+   */
+  hasHandlers(type: BusEventType): boolean {
+    const handlers = this.handlers.get(type);
+    return handlers !== undefined && handlers.size > 0;
+  }
+
+  /**
+   * Get total count of registered handlers (typed + wildcard).
+   *
+   * Useful for debugging and monitoring.
+   *
+   * @returns Total number of registered handlers
+   *
+   * @example
+   * ```typescript
+   * console.log(`Total handlers: ${bus.handlerCount}`);
+   * ```
+   */
+  get handlerCount(): number {
+    let count = this.wildcardHandlers.size;
+    for (const set of this.handlers.values()) {
+      count += set.size;
+    }
+    return count;
+  }
+}
diff --git a/src/events/hooks.test.ts b/src/events/hooks.test.ts
new file mode 100644
index 0000000000..0964c5971e
--- /dev/null
+++ b/src/events/hooks.test.ts
@@ -0,0 +1,308 @@
+/**
+ * Unit tests for React Event Bus Hooks
+ *
+ * Note: These tests focus on the event bus integration logic.
+ * Full React hook lifecycle testing would require a React testing library,
+ * but the core logic (subscriptions, cleanup, handler refs) is tested here.
+ */
+
+import { describe, test, expect, mock } from "bun:test";
+import { EventBus } from "./event-bus.ts";
+import { BatchDispatcher } from "./batch-dispatcher.ts";
+import type { BusEvent } from "./bus-events.ts";
+
+// ============================================================================
+// Tests: Event Bus Integration
+// ============================================================================
+
+describe("Event Bus Hook Integration", () => {
+  test("bus.on() subscribes to specific event type", () => {
+    const bus = new EventBus();
+    const handler = mock(() => {});
+
+    const unsubscribe = bus.on("stream.text.delta", handler);
+
+    const event: BusEvent<"stream.text.delta"> = {
+      type: "stream.text.delta",
+      sessionId: "test-session",
+      runId: 1,
+      timestamp: Date.now(),
+      data: { delta: "Hello", messageId: "msg1" },
+    };
+
+    bus.publish(event);
+
+    expect(handler).toHaveBeenCalledTimes(1);
+    expect(handler).toHaveBeenCalledWith(event);
+
+    // Cleanup
+    unsubscribe();
+  });
+
+  test("unsubscribe function removes handler", () => {
+    const bus = new EventBus();
+    const handler = mock(() => {});
+
+    const unsubscribe = bus.on("stream.text.delta", handler);
+
+    const event: BusEvent<"stream.text.delta"> = {
+      type: "stream.text.delta",
+      sessionId: "test-session",
+      runId: 1,
+      timestamp: Date.now(),
+      data: { delta: "Hello", messageId: "msg1" },
+    };
+
+    bus.publish(event);
+    expect(handler).toHaveBeenCalledTimes(1);
+
+    // Unsubscribe
+    unsubscribe();
+
+    // Publish again - should not be called
+    bus.publish(event);
+    expect(handler).toHaveBeenCalledTimes(1);
+  });
+
+  test("bus.onAll() subscribes to all event types", () => {
+    const bus = new EventBus();
+    const handler = mock(() => {});
+
+    const unsubscribe = bus.onAll(handler);
+
+    const textEvent: BusEvent<"stream.text.delta"> = {
+      type: "stream.text.delta",
+      sessionId: "test-session",
+      runId: 1,
+      timestamp: Date.now(),
+      data: { delta: "Hello", messageId: "msg1" },
+    };
+
+    const toolEvent: BusEvent<"stream.tool.start"> = {
+      type: "stream.tool.start",
+      sessionId: "test-session",
+      runId: 1,
+      timestamp: Date.now(),
+      data: {
+        toolId: "tool1",
+        toolName: "test-tool",
+        toolInput: {},
+      },
+    };
+
+    bus.publish(textEvent);
+    bus.publish(toolEvent);
+
+    expect(handler).toHaveBeenCalledTimes(2);
+    expect(handler).toHaveBeenCalledWith(textEvent);
+    expect(handler).toHaveBeenCalledWith(toolEvent);
+
+    // Cleanup
+    unsubscribe();
+  });
+
+  test("onAll unsubscribe function removes handler", () => {
+    const bus = new EventBus();
+    const handler = mock(() => {});
+
+    const unsubscribe = bus.onAll(handler);
+
+    const event: BusEvent<"stream.text.delta"> = {
+      type: "stream.text.delta",
+      sessionId: "test-session",
+      runId: 1,
+      timestamp: Date.now(),
+      data: { delta: "Hello", messageId: "msg1" },
+    };
+
+    bus.publish(event);
+    expect(handler).toHaveBeenCalledTimes(1);
+
+    // Unsubscribe
+    unsubscribe();
+
+    // Publish again - should not be called
+    bus.publish(event);
+    expect(handler).toHaveBeenCalledTimes(1);
+  });
+
+  test("multiple subscriptions to same event type work independently", () => {
+    const bus = new EventBus();
+    const handler1 = mock(() => {});
+    const handler2 = mock(() => {});
+
+    const unsubscribe1 = bus.on("stream.text.delta", handler1);
+    const unsubscribe2 = bus.on("stream.text.delta", handler2);
+
+    const event: BusEvent<"stream.text.delta"> = {
+      type: "stream.text.delta",
+      sessionId: "test-session",
+      runId: 1,
+      timestamp: Date.now(),
+      data: { delta: "Hello", messageId: "msg1" },
+    };
+
+    bus.publish(event);
+
+    expect(handler1).toHaveBeenCalledTimes(1);
+    expect(handler2).toHaveBeenCalledTimes(1);
+
+    // Unsubscribe first handler
+    unsubscribe1();
+
+    bus.publish(event);
+
+    // Only second handler should be called
+    expect(handler1).toHaveBeenCalledTimes(1);
+    expect(handler2).toHaveBeenCalledTimes(2);
+
+    // Cleanup
+    unsubscribe2();
+  });
+
+  test("typed subscription only receives correct event type", () => {
+    const bus = new EventBus();
+    const handler = mock(() => {});
+
+    const unsubscribe = bus.on("stream.text.delta", handler);
+
+    // Publish wrong type
+    const wrongEvent: BusEvent<"stream.tool.start"> = {
+      type: "stream.tool.start",
+      sessionId: "test-session",
+      runId: 1,
+      timestamp: Date.now(),
+      data: {
+        toolId: "tool1",
+        toolName: "test-tool",
+        toolInput: {},
+      },
+    };
+
+    bus.publish(wrongEvent);
+    expect(handler).not.toHaveBeenCalled();
+
+    // Publish correct type
+    const correctEvent: BusEvent<"stream.text.delta"> = {
+      type: "stream.text.delta",
+      sessionId: "test-session",
+      runId: 1,
+      timestamp: Date.now(),
+      data: { delta: "Hello", messageId: "msg1" },
+    };
+
+    bus.publish(correctEvent);
+    expect(handler).toHaveBeenCalledTimes(1);
+    expect(handler).toHaveBeenCalledWith(correctEvent);
+
+    // Cleanup
+    unsubscribe();
+  });
+
+  test("dispatcher enqueues events to bus", async () => {
+    const bus = new EventBus();
+    const dispatcher = new BatchDispatcher(bus, 10); // 10ms flush interval
+    const receivedEvents: BusEvent[] = [];
+
+    dispatcher.addConsumer((events) => {
+      receivedEvents.push(...events);
+    });
+
+    const event: BusEvent<"stream.text.delta"> = {
+      type: "stream.text.delta",
+      sessionId: "test-session",
+      runId: 1,
+      timestamp: Date.now(),
+      data: { delta: "Hello", messageId: "msg1" },
+    };
+
+    dispatcher.enqueue(event);
+
+    // Event not immediately dispatched
+    expect(receivedEvents.length).toBe(0);
+
+    // Wait for flush interval
+    await new Promise((resolve) => setTimeout(resolve, 20));
+
+    // Event should be dispatched to consumer now
+    expect(receivedEvents.length).toBe(1);
+    expect(receivedEvents[0]).toEqual(event);
+
+    // Cleanup
+    dispatcher.dispose();
+  });
+});
+
+describe("useStreamConsumer integration logic", () => {
+  test("SDKStreamAdapter interface supports startStreaming/dispose lifecycle", async () => {
+    const bus = new EventBus();
+    const events: BusEvent[] = [];
+    bus.onAll((event) => events.push(event));
+
+    // Mock adapter that simulates streaming
+    const mockAdapter = {
+      startStreaming: mock(async (_session: any, _message: string, _options: any) => {
+        bus.publish({
+          type: "stream.text.delta",
+          sessionId: "test",
+          runId: 1,
+          timestamp: Date.now(),
+          data: { delta: "hello", messageId: "m1" },
+        });
+      }),
+      dispose: mock(() => {}),
+    };
+
+    await mockAdapter.startStreaming({} as any, "test", { runId: 1, messageId: "m1" });
+    expect(mockAdapter.startStreaming).toHaveBeenCalledTimes(1);
+    expect(events.length).toBe(1);
+
+    mockAdapter.dispose();
+    expect(mockAdapter.dispose).toHaveBeenCalledTimes(1);
+  });
+
+  test("adapter dispose() can be called multiple times safely", () => {
+    const mockAdapter = {
+      startStreaming: mock(async (_session: any, _message: string, _options: any) => {}),
+      dispose: mock(() => {}),
+    };
+
+    mockAdapter.dispose();
+    mockAdapter.dispose();
+    expect(mockAdapter.dispose).toHaveBeenCalledTimes(2);
+    // Should not throw
+  });
+
+  test("streaming lifecycle: start → events → stop", async () => {
+    const bus = new EventBus();
+    const events: BusEvent[] = [];
+    bus.onAll((event) => events.push(event));
+
+    let isStreaming = false;
+
+    const mockAdapter = {
+      startStreaming: mock(async (_session: any, _message: string, _options: any) => {
+        isStreaming = true;
+        bus.publish({
+          type: "stream.text.delta",
+          sessionId: "s1",
+          runId: 1,
+          timestamp: Date.now(),
+          data: { delta: "streaming", messageId: "m1" },
+        });
+        isStreaming = false;
+      }),
+      dispose: mock(() => {
+        isStreaming = false;
+      }),
+    };
+
+    expect(isStreaming).toBe(false);
+    await mockAdapter.startStreaming({} as any, "msg", { runId: 1, messageId: "m1" });
+    expect(isStreaming).toBe(false); // completed
+    expect(events.length).toBe(1);
+
+    mockAdapter.dispose();
+    expect(isStreaming).toBe(false);
+  });
+});
diff --git a/src/events/hooks.ts b/src/events/hooks.ts
new file mode 100644
index 0000000000..ddae521950
--- /dev/null
+++ b/src/events/hooks.ts
@@ -0,0 +1,294 @@
+/**
+ * React Hooks for Event Bus
+ *
+ * This module provides React hooks for working with the event bus in components.
+ * These hooks simplify event subscription and provide automatic cleanup on unmount.
+ *
+ * Key features:
+ * - useEventBus: Access to bus and dispatcher instances
+ * - useBusSubscription: Type-safe subscription with auto-cleanup
+ * - useBusWildcard: Wildcard subscription with auto-cleanup
+ * - Handler refs to avoid re-subscribing on handler identity changes
+ *
+ * Usage:
+ * ```typescript
+ * function MyComponent() {
+ *   const { bus, dispatcher } = useEventBus();
+ *
+ *   // Subscribe to specific event
+ *   useBusSubscription("stream.text.delta", (event) => {
+ *     console.log(event.data.delta);
+ *   });
+ *
+ *   // Subscribe to all events
+ *   useBusWildcard((event) => {
+ *     console.log(`[${event.type}]`, event.data);
+ *   });
+ *
+ *   // Publish events
+ *   const handleClick = () => {
+ *     dispatcher.enqueue({ ... });
+ *   };
+ * }
+ * ```
+ */
+
+import { useEffect, useRef, useCallback, useState } from "react";
+import { useEventBusContext } from "./event-bus-provider.tsx";
+import type { BusEvent, BusEventType, BusHandler, WildcardHandler } from "./bus-events.ts";
+import { wireConsumers } from "./consumers/wire-consumers.ts";
+import type { CorrelationService } from "./consumers/correlation-service.ts";
+import type { StreamPartEvent } from "../ui/parts/stream-pipeline.ts";
+import type { SDKStreamAdapter, StreamAdapterOptions } from "./adapters/types.ts";
+import type { Session } from "../sdk/types.ts";
+
+/**
+ * Hook to get the event bus instance.
+ *
+ * Shorthand for useEventBusContext() that provides access to both the event bus
+ * and batch dispatcher instances. The bus is used for subscribing to events,
+ * while the dispatcher is used for publishing events.
+ *
+ * @returns The event bus context value containing bus and dispatcher
+ * @throws Error if used outside EventBusProvider
+ *
+ * @example
+ * ```typescript
+ * function ChatComponent() {
+ *   const { bus, dispatcher } = useEventBus();
+ *
+ *   // Use bus for subscriptions (via other hooks)
+ *   // Use dispatcher to publish events
+ *   const handleNewMessage = (text: string) => {
+ *     dispatcher.enqueue({
+ *       type: "stream.text.delta",
+ *       sessionId: "abc123",
+ *       runId: 1,
+ *       timestamp: Date.now(),
+ *       data: { delta: text, messageId: "msg1" }
+ *     });
+ *   };
+ * }
+ * ```
+ */
+export function useEventBus() {
+  return useEventBusContext();
+}
+
+/**
+ * Hook to subscribe to a specific event type on the bus.
+ *
+ * Automatically unsubscribes on unmount. Uses a ref for the handler to avoid
+ * re-subscribing when the handler identity changes, which improves performance
+ * and prevents unnecessary subscription churn.
+ *
+ * @param eventType - The specific event type to subscribe to
+ * @param handler - Callback function to handle the event
+ *
+ * @example
+ * ```typescript
+ * function TextStreamComponent() {
+ *   const [text, setText] = useState("");
+ *
+ *   useBusSubscription("stream.text.delta", (event) => {
+ *     setText((prev) => prev + event.data.delta);
+ *   });
+ *
+ *   return <div>{text}</div>;
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * function ToolStatusComponent() {
+ *   useBusSubscription("stream.tool.start", (event) => {
+ *     console.log(`Tool started: ${event.data.toolName}`);
+ *   });
+ *
+ *   useBusSubscription("stream.tool.complete", (event) => {
+ *     console.log(`Tool completed: ${event.data.toolId}`);
+ *   });
+ * }
+ * ```
+ */
+export function useBusSubscription<T extends BusEventType>(
+  eventType: T,
+  handler: BusHandler<T>
+): void {
+  const { bus } = useEventBusContext();
+  const handlerRef = useRef(handler);
+  handlerRef.current = handler;
+
+  useEffect(() => {
+    const unsubscribe = bus.on(eventType, ((event: BusEvent<T>) => {
+      handlerRef.current(event);
+    }) as BusHandler<T>);
+    return unsubscribe;
+  }, [bus, eventType]);
+}
+
+/**
+ * Hook to subscribe to all events on the bus (wildcard).
+ *
+ * Automatically unsubscribes on unmount. Useful for debugging, logging,
+ * and observability. Uses a ref for the handler to avoid re-subscribing
+ * when the handler identity changes.
+ *
+ * @param handler - Callback function to handle all events
+ *
+ * @example
+ * ```typescript
+ * function DebugLogger() {
+ *   useBusWildcard((event) => {
+ *     console.debug(`[${event.type}] at ${event.timestamp}`, event.data);
+ *   });
+ *
+ *   return null;
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * function EventCounter() {
+ *   const [count, setCount] = useState(0);
+ *
+ *   useBusWildcard((event) => {
+ *     setCount((prev) => prev + 1);
+ *   });
+ *
+ *   return <div>Total events: {count}</div>;
+ * }
+ * ```
+ */
+export function useBusWildcard(handler: WildcardHandler): void {
+  const { bus } = useEventBusContext();
+  const handlerRef = useRef(handler);
+  handlerRef.current = handler;
+
+  useEffect(() => {
+    const unsubscribe = bus.onAll((event: BusEvent) => {
+      handlerRef.current(event);
+    });
+    return unsubscribe;
+  }, [bus]);
+}
+
+/**
+ * Hook that wires up the full event bus consumer pipeline and
+ * delivers StreamPartEvents to the component.
+ *
+ * Replaces the legacy handleChunk/handleMeta/handleComplete callback pattern
+ * by setting up the complete event processing pipeline:
+ * - CorrelationService: Enriches events with metadata
+ * - EchoSuppressor: Filters duplicate text echoes
+ * - StreamPipelineConsumer: Transforms BusEvents to StreamPartEvents
+ *
+ * The hook manages the entire consumer lifecycle, including cleanup on unmount.
+ * Uses refs to avoid re-subscriptions when the callback identity changes.
+ *
+ * @param onStreamParts - Callback to receive batched StreamPartEvents
+ * @returns Object with resetConsumers function for cleanup between runs
+ *
+ * @example
+ * ```typescript
+ * function ChatComponent() {
+ *   const [message, setMessage] = useState<ChatMessage>(...);
+ *
+ *   const { resetConsumers } = useStreamConsumer((parts) => {
+ *     setMessage((prev) => {
+ *       let updated = prev;
+ *       for (const part of parts) {
+ *         updated = applyStreamPartEvent(updated, part);
+ *       }
+ *       return updated;
+ *     });
+ *   });
+ *
+ *   const handleNewStream = () => {
+ *     resetConsumers(); // Clean state before new stream
+ *     // ... start streaming
+ *   };
+ * }
+ * ```
+ */
+export function useStreamConsumer(
+  onStreamParts: (parts: StreamPartEvent[]) => void
+): {
+  resetConsumers: () => void;
+  getCorrelationService: () => CorrelationService | null;
+  startStreaming: (
+    adapter: SDKStreamAdapter,
+    session: Session,
+    message: string,
+    options: StreamAdapterOptions
+  ) => Promise<void>;
+  stopStreaming: () => void;
+  isStreaming: boolean;
+} {
+  const { bus, dispatcher } = useEventBusContext();
+  const callbackRef = useRef(onStreamParts);
+  callbackRef.current = onStreamParts;
+
+  const consumersRef = useRef<ReturnType<typeof wireConsumers> | null>(null);
+  const [isStreaming, setIsStreaming] = useState(false);
+  const adapterRef = useRef<SDKStreamAdapter | null>(null);
+
+  useEffect(() => {
+    const consumers = wireConsumers(bus, dispatcher);
+    consumersRef.current = consumers;
+
+    const unsubscribe = consumers.pipeline.onStreamParts((parts) => {
+      callbackRef.current(parts);
+    });
+
+    return () => {
+      unsubscribe();
+      consumers.dispose();
+      consumersRef.current = null;
+    };
+  }, [bus, dispatcher]);
+
+  const resetConsumers = useCallback(() => {
+    consumersRef.current?.pipeline.reset();
+  }, []);
+
+  const getCorrelationService = useCallback((): CorrelationService | null => {
+    return consumersRef.current?.correlation ?? null;
+  }, []);
+
+  const stopStreaming = useCallback(() => {
+    if (adapterRef.current) {
+      adapterRef.current.dispose();
+      adapterRef.current = null;
+    }
+    setIsStreaming(false);
+  }, []);
+
+  const startStreaming = useCallback(
+    async (
+      adapter: SDKStreamAdapter,
+      session: Session,
+      message: string,
+      options: StreamAdapterOptions,
+    ): Promise<void> => {
+      adapterRef.current = adapter;
+      setIsStreaming(true);
+      resetConsumers();
+      try {
+        await adapter.startStreaming(session, message, options);
+      } finally {
+        setIsStreaming(false);
+      }
+    },
+    [resetConsumers],
+  );
+
+  // Cleanup adapter on unmount
+  useEffect(() => {
+    return () => {
+      stopStreaming();
+    };
+  }, [stopStreaming]);
+
+  return { resetConsumers, getCorrelationService, startStreaming, stopStreaming, isStreaming };
+}
diff --git a/src/events/integration.test.ts b/src/events/integration.test.ts
new file mode 100644
index 0000000000..fce1d3c928
--- /dev/null
+++ b/src/events/integration.test.ts
@@ -0,0 +1,758 @@
+// @ts-nocheck
+/**
+ * Event Bus Integration Tests
+ *
+ * End-to-end integration tests for the streaming architecture event bus.
+ * These tests verify the full pipeline:
+ *   Mock SDK stream → Adapter → Bus → Batch Dispatcher → Consumers → StreamPartEvent output
+ *
+ * Test scenarios:
+ * 1. Full pipeline: Mock SDK stream → adapter → bus → consumer → StreamPartEvent output
+ * 2. Text delta flow: Verify text deltas flow from mock stream to StreamPartEvent text-delta
+ * 3. Tool lifecycle: tool.start → tool.complete flows through pipeline
+ * 4. Echo suppression: Text delta suppressed when matching expected echo
+ * 5. Multiple adapters: Verify all three SDK adapters produce same bus events for equivalent inputs
+ * 6. Batch coalescing: Rapidly fired state updates get coalesced in batch window
+ */
+
+import { describe, expect, test, beforeEach, mock } from "bun:test";
+import { EventBus } from "./event-bus.ts";
+import { BatchDispatcher } from "./batch-dispatcher.ts";
+import { wireConsumers } from "./consumers/wire-consumers.ts";
+import { OpenCodeStreamAdapter } from "./adapters/opencode-adapter.ts";
+import { ClaudeStreamAdapter } from "./adapters/claude-adapter.ts";
+import { CopilotStreamAdapter } from "./adapters/copilot-adapter.ts";
+import type { BusEvent, EnrichedBusEvent } from "./bus-events.ts";
+import type { StreamPartEvent } from "../ui/parts/stream-pipeline.ts";
+import type {
+  Session,
+  AgentMessage,
+  AgentEvent,
+  EventType,
+  CodingAgentClient,
+} from "../sdk/types.ts";
+
+// ============================================================================
+// Mock Utilities
+// ============================================================================
+
+/**
+ * Mock async generator for OpenCode/Claude streams
+ */
+async function* mockAsyncStream(
+  chunks: AgentMessage[],
+): AsyncGenerator<AgentMessage> {
+  for (const chunk of chunks) {
+    yield chunk;
+  }
+}
+
+/**
+ * Create a mock Session for testing
+ */
+function createMockSession(
+  stream: AsyncGenerator<AgentMessage>,
+  client?: Partial<CodingAgentClient>,
+): Session {
+  const session = {
+    id: "test-session-123",
+    stream: mock(() => stream),
+    __client: client,
+  } as unknown as Session;
+  return session;
+}
+
+/**
+ * Create a mock CodingAgentClient with EventEmitter-like behavior
+ */
+function createMockClient(): CodingAgentClient {
+  const handlers = new Map<EventType, Set<(event: AgentEvent) => void>>();
+
+  const client = {
+    on: mock((type: EventType, handler: (event: AgentEvent) => void) => {
+      let set = handlers.get(type);
+      if (!set) {
+        set = new Set();
+        handlers.set(type, set);
+      }
+      set.add(handler);
+      return () => {
+        set?.delete(handler);
+      };
+    }),
+    emit: (type: EventType, event: AgentEvent) => {
+      const set = handlers.get(type);
+      if (set) {
+        for (const handler of set) {
+          handler(event);
+        }
+      }
+    },
+  } as unknown as CodingAgentClient;
+
+  return client;
+}
+
+/**
+ * Helper to wait for all microtasks and timers to complete
+ */
+async function flushMicrotasks(): Promise<void> {
+  await new Promise((resolve) => setTimeout(resolve, 0));
+}
+
+/**
+ * Helper to wait for batch dispatcher to flush (16ms frame time + buffer)
+ */
+async function waitForBatchFlush(): Promise<void> {
+  await new Promise((resolve) => setTimeout(resolve, 25));
+}
+
+// ============================================================================
+// Integration Tests
+// ============================================================================
+
+describe("Event Bus Integration", () => {
+  let bus: EventBus;
+  let dispatcher: BatchDispatcher;
+
+  beforeEach(() => {
+    bus = new EventBus();
+    dispatcher = new BatchDispatcher(bus);
+  });
+
+  test("full pipeline: SDK stream → adapter → bus → consumer → output", async () => {
+    const { pipeline, dispose } = wireConsumers(bus, dispatcher);
+
+    const output: StreamPartEvent[] = [];
+    pipeline.onStreamParts((parts) => output.push(...parts));
+
+    // Create mock SDK stream with text deltas
+    const chunks: AgentMessage[] = [
+      { type: "text", content: "Hello " },
+      { type: "text", content: "world" },
+    ];
+
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream);
+
+    // Create adapter and start streaming
+    const adapter = new OpenCodeStreamAdapter(bus, "test-session-123");
+    await adapter.startStreaming(session, "test message", {
+      runId: 1,
+      messageId: "msg-1",
+    });
+
+    // Wait for events to be processed
+    await flushMicrotasks();
+    await waitForBatchFlush();
+
+    // Verify output contains expected StreamPartEvents
+    // Adjacent text-deltas with matching agentId are coalesced into a single event
+    expect(output.length).toBeGreaterThan(0);
+
+    const textDeltas = output.filter((e) => e.type === "text-delta");
+    expect(textDeltas.length).toBe(1);
+    expect(textDeltas[0].delta).toBe("Hello world");
+
+    dispose();
+    adapter.dispose();
+  });
+
+  test("text delta flow: verify text deltas flow from mock stream to StreamPartEvent", async () => {
+    const { pipeline, dispose } = wireConsumers(bus, dispatcher);
+
+    const output: StreamPartEvent[] = [];
+    pipeline.onStreamParts((parts) => output.push(...parts));
+
+    // Create mock SDK stream with multiple text deltas
+    const chunks: AgentMessage[] = [
+      { type: "text", content: "The " },
+      { type: "text", content: "quick " },
+      { type: "text", content: "brown " },
+      { type: "text", content: "fox" },
+    ];
+
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream);
+
+    const adapter = new OpenCodeStreamAdapter(bus, "test-session-456");
+    await adapter.startStreaming(session, "test message", {
+      runId: 2,
+      messageId: "msg-2",
+    });
+
+    await flushMicrotasks();
+    await waitForBatchFlush();
+
+    // Adjacent text-deltas with matching agentId are coalesced into a single event
+    const textDeltas = output.filter((e) => e.type === "text-delta");
+    expect(textDeltas.length).toBe(1);
+    expect(textDeltas[0].delta).toBe("The quick brown fox");
+
+    dispose();
+    adapter.dispose();
+  });
+
+  test("tool lifecycle: tool.start → tool.complete flows through pipeline", async () => {
+    const { pipeline, correlation, dispose } = wireConsumers(bus, dispatcher);
+
+    const output: StreamPartEvent[] = [];
+    pipeline.onStreamParts((parts) => output.push(...parts));
+
+    // Create mock client that emits tool events
+    const client = createMockClient();
+    
+    // Create a stream that yields slowly to allow event emission during iteration
+    async function* slowStream(): AsyncGenerator<AgentMessage> {
+      yield { type: "text", content: "start" };
+      // Small delay to allow events to be emitted
+      await new Promise((resolve) => setTimeout(resolve, 10));
+      yield { type: "text", content: "end" };
+    }
+    
+    const stream = slowStream();
+    const session = createMockSession(stream, client);
+
+    const adapter = new OpenCodeStreamAdapter(bus, "test-session-789");
+
+    // Register the tool with correlation service
+    correlation.registerTool("tool-123", null, false);
+
+    // Start streaming (this will set up event listeners)
+    const streamPromise = adapter.startStreaming(session, "test message", {
+      runId: 3,
+      messageId: "msg-3",
+    });
+
+    // Wait a bit for stream to start
+    await new Promise((resolve) => setTimeout(resolve, 5));
+
+    // Emit tool.start event
+    client.emit("tool.start" as EventType, {
+      type: "tool.start",
+      sessionId: "test-session-789",
+      timestamp: Date.now(),
+      data: {
+        toolName: "bash",
+        toolInput: { command: "echo hello" },
+        toolUseId: "tool-123",
+      },
+    } as AgentEvent<"tool.start">);
+
+    // Emit tool.complete event
+    client.emit("tool.complete" as EventType, {
+      type: "tool.complete",
+      sessionId: "test-session-789",
+      timestamp: Date.now(),
+      data: {
+        toolName: "bash",
+        toolResult: "hello",
+        success: true,
+        toolUseId: "tool-123",
+      },
+    } as AgentEvent<"tool.complete">);
+
+    await streamPromise;
+    await flushMicrotasks();
+    await waitForBatchFlush();
+
+    // Verify tool lifecycle events in output
+    const toolStarts = output.filter((e) => e.type === "tool-start");
+    expect(toolStarts.length).toBe(1);
+    expect(toolStarts[0].toolId).toBe("tool-123");
+    expect(toolStarts[0].toolName).toBe("bash");
+    expect(toolStarts[0].input).toEqual({ command: "echo hello" });
+
+    const toolCompletes = output.filter((e) => e.type === "tool-complete");
+    expect(toolCompletes.length).toBe(1);
+    expect(toolCompletes[0].toolId).toBe("tool-123");
+    expect(toolCompletes[0].output).toBe("hello");
+    expect(toolCompletes[0].success).toBe(true);
+
+    dispose();
+    adapter.dispose();
+  });
+
+  test("echo suppression: text delta suppressed when matching expected echo", async () => {
+    const { pipeline, echoSuppressor, dispose } = wireConsumers(bus, dispatcher);
+
+    const output: StreamPartEvent[] = [];
+    pipeline.onStreamParts((parts) => output.push(...parts));
+
+    // Register echo text that should be suppressed
+    echoSuppressor.expectEcho("tool-result-echo");
+
+    // Create mock SDK stream with echo text
+    const chunks: AgentMessage[] = [
+      { type: "text", content: "tool-result-echo" }, // Should be suppressed
+      { type: "text", content: "This should appear" }, // Should NOT be suppressed
+    ];
+
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream);
+
+    const adapter = new OpenCodeStreamAdapter(bus, "test-session-echo");
+    await adapter.startStreaming(session, "test message", {
+      runId: 4,
+      messageId: "msg-4",
+    });
+
+    await flushMicrotasks();
+    await waitForBatchFlush();
+
+    // Verify echo was suppressed
+    const textDeltas = output.filter((e) => e.type === "text-delta");
+    expect(textDeltas.length).toBe(1);
+    expect(textDeltas[0].delta).toBe("This should appear");
+
+    dispose();
+    adapter.dispose();
+  });
+
+  test("multiple adapters: verify all three SDK adapters produce same bus events", async () => {
+    // Test OpenCode adapter
+    const opencodeBus = new EventBus();
+    const opencodeEvents: BusEvent[] = [];
+    opencodeBus.onAll((event) => opencodeEvents.push(event));
+
+    const opencodeChunks: AgentMessage[] = [
+      { type: "text", content: "Hello" },
+    ];
+    const opencodeStream = mockAsyncStream(opencodeChunks);
+    const opencodeSession = createMockSession(opencodeStream);
+    const opencodeAdapter = new OpenCodeStreamAdapter(opencodeBus, "session-1");
+
+    await opencodeAdapter.startStreaming(opencodeSession, "test", {
+      runId: 5,
+      messageId: "msg-5",
+    });
+
+    // Test Claude adapter
+    const claudeBus = new EventBus();
+    const claudeEvents: BusEvent[] = [];
+    claudeBus.onAll((event) => claudeEvents.push(event));
+
+    const claudeChunks: AgentMessage[] = [{ type: "text", content: "Hello" }];
+    const claudeStream = mockAsyncStream(claudeChunks);
+    const claudeSession = createMockSession(claudeStream);
+    const claudeAdapter = new ClaudeStreamAdapter(claudeBus, "session-1");
+
+    await claudeAdapter.startStreaming(claudeSession, "test", {
+      runId: 5,
+      messageId: "msg-5",
+    });
+
+    // OpenCode adapter always publishes session.idle after stream completes;
+    // Claude adapter only publishes if the SDK client emits session.idle.
+    // Verify both share the same core events, then verify OpenCode has the
+    // additional session.idle.
+    const coreFilter = (e: BusEvent) => e.type !== "stream.session.idle";
+    const opencodeCore = opencodeEvents.filter(coreFilter);
+    const claudeCore = claudeEvents.filter(coreFilter);
+    expect(opencodeCore.length).toBe(claudeCore.length);
+
+    // OpenCode should have the extra session.idle event
+    const opencodeIdleEvents = opencodeEvents.filter(
+      (e) => e.type === "stream.session.idle",
+    );
+    expect(opencodeIdleEvents.length).toBe(1);
+    expect(opencodeIdleEvents[0].data.reason).toBe("generator-complete");
+
+    // Check text delta events
+    const opencodeTextDeltas = opencodeEvents.filter(
+      (e) => e.type === "stream.text.delta",
+    );
+    const claudeTextDeltas = claudeEvents.filter(
+      (e) => e.type === "stream.text.delta",
+    );
+
+    expect(opencodeTextDeltas.length).toBe(1);
+    expect(claudeTextDeltas.length).toBe(1);
+    expect(opencodeTextDeltas[0].data.delta).toBe("Hello");
+    expect(claudeTextDeltas[0].data.delta).toBe("Hello");
+    expect(opencodeTextDeltas[0].runId).toBe(claudeTextDeltas[0].runId);
+
+    // Check text complete events
+    const opencodeTextComplete = opencodeEvents.filter(
+      (e) => e.type === "stream.text.complete",
+    );
+    const claudeTextComplete = claudeEvents.filter(
+      (e) => e.type === "stream.text.complete",
+    );
+
+    expect(opencodeTextComplete.length).toBe(1);
+    expect(claudeTextComplete.length).toBe(1);
+    expect(opencodeTextComplete[0].data.fullText).toBe("Hello");
+    expect(claudeTextComplete[0].data.fullText).toBe("Hello");
+
+    opencodeAdapter.dispose();
+    claudeAdapter.dispose();
+  });
+
+  test("batch coalescing: rapidly fired state updates get coalesced", async () => {
+    const { pipeline, dispose } = wireConsumers(bus, dispatcher);
+
+    const batchSizes: number[] = [];
+    pipeline.onStreamParts((parts) => {
+      batchSizes.push(parts.length);
+    });
+
+    // Publish multiple rapid events to the bus
+    // These should be coalesced in the batch dispatcher
+    const chunks: AgentMessage[] = [];
+    for (let i = 0; i < 10; i++) {
+      chunks.push({ type: "text", content: `chunk${i} ` });
+    }
+
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream);
+
+    const adapter = new OpenCodeStreamAdapter(bus, "test-session-batch");
+    await adapter.startStreaming(session, "test message", {
+      runId: 6,
+      messageId: "msg-6",
+    });
+
+    await flushMicrotasks();
+    await waitForBatchFlush();
+
+    // Verify that events were batched and delivered.
+    // Adjacent text-deltas with matching agentId are coalesced within each batch,
+    // so 10 rapid chunks may reduce to fewer StreamPartEvents.
+    const totalEvents = batchSizes.reduce((sum, size) => sum + size, 0);
+    expect(totalEvents).toBeGreaterThanOrEqual(1);
+    expect(batchSizes.length).toBeGreaterThanOrEqual(1);
+
+    dispose();
+    adapter.dispose();
+  });
+
+  test("thinking deltas flow through pipeline", async () => {
+    const { pipeline, dispose } = wireConsumers(bus, dispatcher);
+
+    const output: StreamPartEvent[] = [];
+    pipeline.onStreamParts((parts) => output.push(...parts));
+
+    // Create mock SDK stream with thinking deltas
+    const chunks: AgentMessage[] = [
+      {
+        type: "thinking",
+        content: "Let me think... ",
+        metadata: { thinkingSourceKey: "block-1" },
+      },
+      {
+        type: "thinking",
+        content: "about this problem.",
+        metadata: { thinkingSourceKey: "block-1" },
+      },
+      {
+        type: "thinking",
+        content: "",
+        metadata: {
+          thinkingSourceKey: "block-1",
+          streamingStats: { thinkingMs: 1234 },
+        },
+      },
+    ];
+
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream);
+
+    const adapter = new OpenCodeStreamAdapter(bus, "test-session-thinking");
+    await adapter.startStreaming(session, "test message", {
+      runId: 7,
+      messageId: "msg-7",
+    });
+
+    await flushMicrotasks();
+    await waitForBatchFlush();
+
+    // Verify thinking meta events (thinking deltas are mapped to thinking-meta).
+    // Adjacent thinking-meta events with matching scope are coalesced into one.
+    const thinkingMeta = output.filter((e) => e.type === "thinking-meta");
+    expect(thinkingMeta.length).toBe(1);
+    expect(thinkingMeta[0].thinkingText).toBe("Let me think... about this problem.");
+    expect(thinkingMeta[0].thinkingSourceKey).toBe("block-1");
+
+    dispose();
+    adapter.dispose();
+  });
+
+  test("runtime envelope chat flow: workflow events map to runtime envelope parts", async () => {
+    const { pipeline, dispose } = wireConsumers(bus, dispatcher);
+
+    const output: StreamPartEvent[] = [];
+    pipeline.onStreamParts((parts) => output.push(...parts));
+
+    dispatcher.enqueue({
+      type: "stream.session.start",
+      sessionId: "runtime-session",
+      runId: 11,
+      timestamp: Date.now(),
+      data: {},
+    });
+
+    dispatcher.enqueue({
+      type: "workflow.step.start",
+      sessionId: "runtime-session",
+      runId: 11,
+      timestamp: Date.now(),
+      data: {
+        workflowId: "wf-runtime",
+        nodeId: "planner",
+        nodeName: "Planner",
+      },
+    });
+
+    dispatcher.enqueue({
+      type: "workflow.task.update",
+      sessionId: "runtime-session",
+      runId: 11,
+      timestamp: Date.now(),
+      data: {
+        workflowId: "wf-runtime",
+        tasks: [
+          {
+            id: "#1",
+            title: "Plan rollout",
+            status: "completed",
+            taskResult: {
+              task_id: "#1",
+              tool_name: "task",
+              title: "Plan rollout",
+              status: "completed",
+              output_text: "done",
+            },
+          },
+        ],
+      },
+    });
+
+    dispatcher.enqueue({
+      type: "workflow.step.complete",
+      sessionId: "runtime-session",
+      runId: 11,
+      timestamp: Date.now(),
+      data: {
+        workflowId: "wf-runtime",
+        nodeId: "planner",
+        nodeName: "Planner",
+        status: "success",
+      },
+    });
+
+    await flushMicrotasks();
+    await waitForBatchFlush();
+
+    expect(output.some((event) => event.type === "workflow-step-start")).toBe(true);
+    expect(output.some((event) => event.type === "task-list-update")).toBe(true);
+    expect(output.some((event) => event.type === "task-result-upsert")).toBe(true);
+    expect(output.some((event) => event.type === "workflow-step-complete")).toBe(true);
+
+    const taskResult = output.find((event) => event.type === "task-result-upsert");
+    expect(taskResult?.type).toBe("task-result-upsert");
+    if (taskResult?.type === "task-result-upsert") {
+      expect(taskResult.envelope.task_id).toBe("#1");
+      expect(taskResult.envelope.output_text).toBe("done");
+    }
+
+    dispose();
+  });
+
+  test("sub-agent lifecycle events published to bus", async () => {
+    const busEvents: BusEvent[] = [];
+    bus.onAll((event) => busEvents.push(event));
+
+    // Create mock client that emits sub-agent events
+    const client = createMockClient();
+    
+    // Create a stream that yields slowly to allow event emission during iteration
+    async function* slowStream(): AsyncGenerator<AgentMessage> {
+      yield { type: "text", content: "start" };
+      await new Promise((resolve) => setTimeout(resolve, 10));
+      yield { type: "text", content: "end" };
+    }
+    
+    const stream = slowStream();
+    const session = createMockSession(stream, client);
+
+    const adapter = new OpenCodeStreamAdapter(bus, "test-session-agent");
+
+    // Start streaming
+    const streamPromise = adapter.startStreaming(session, "test message", {
+      runId: 8,
+      messageId: "msg-8",
+    });
+
+    // Wait for streaming to start
+    await new Promise((resolve) => setTimeout(resolve, 5));
+
+    // Emit subagent.start event
+    client.emit("subagent.start" as EventType, {
+      type: "subagent.start",
+      sessionId: "test-session-agent",
+      timestamp: Date.now(),
+      data: {
+        subagentId: "agent-123",
+        subagentType: "explore",
+        task: "Find all TypeScript files",
+        toolCallId: "tool-456",
+      },
+    } as AgentEvent<"subagent.start">);
+
+    // Emit subagent.complete event
+    client.emit("subagent.complete" as EventType, {
+      type: "subagent.complete",
+      sessionId: "test-session-agent",
+      timestamp: Date.now(),
+      data: {
+        subagentId: "agent-123",
+        success: true,
+        result: "Found 42 TypeScript files",
+      },
+    } as AgentEvent<"subagent.complete">);
+
+    await streamPromise;
+    await flushMicrotasks();
+    await waitForBatchFlush();
+
+    // Verify sub-agent events were published to bus
+    const agentStarts = busEvents.filter((e) => e.type === "stream.agent.start");
+    expect(agentStarts.length).toBe(1);
+    expect(agentStarts[0].data.agentId).toBe("agent-123");
+    expect(agentStarts[0].data.agentType).toBe("explore");
+    expect(agentStarts[0].data.task).toBe("Find all TypeScript files");
+
+    const agentCompletes = busEvents.filter(
+      (e) => e.type === "stream.agent.complete",
+    );
+    expect(agentCompletes.length).toBe(1);
+    expect(agentCompletes[0].data.agentId).toBe("agent-123");
+    expect(agentCompletes[0].data.success).toBe(true);
+    expect(agentCompletes[0].data.result).toBe("Found 42 TypeScript files");
+
+    adapter.dispose();
+  });
+
+  test("session error events published to bus", async () => {
+    const busEvents: BusEvent[] = [];
+    bus.onAll((event) => busEvents.push(event));
+
+    // Create mock client that emits session error
+    const client = createMockClient();
+    const chunks: AgentMessage[] = [{ type: "text", content: "start" }];
+    const stream = mockAsyncStream(chunks);
+    const session = createMockSession(stream, client);
+
+    const adapter = new OpenCodeStreamAdapter(bus, "test-session-error");
+
+    const streamPromise = adapter.startStreaming(session, "test message", {
+      runId: 9,
+      messageId: "msg-9",
+    });
+
+    // Emit session.error event
+    client.emit("session.error" as EventType, {
+      type: "session.error",
+      sessionId: "test-session-error",
+      timestamp: Date.now(),
+      data: {
+        error: "Network timeout",
+        code: "TIMEOUT",
+      },
+    } as AgentEvent<"session.error">);
+
+    await streamPromise;
+    await flushMicrotasks();
+    await waitForBatchFlush();
+
+    // Verify session error event was published to bus
+    const errorEvents = busEvents.filter(
+      (e) => e.type === "stream.session.error",
+    );
+    expect(errorEvents.length).toBe(1);
+    expect(errorEvents[0].data.error).toBe("Network timeout");
+    expect(errorEvents[0].data.code).toBe("TIMEOUT");
+
+    adapter.dispose();
+  });
+
+  test("correlation enriches tool events with agent metadata", async () => {
+    const { correlation, dispose } = wireConsumers(bus, dispatcher);
+
+    // Collect enriched bus events
+    const enrichedEvents: EnrichedBusEvent[] = [];
+    bus.onAll((event) => {
+      const enriched = correlation.enrich(event);
+      enrichedEvents.push(enriched);
+    });
+
+    // Create mock client
+    const client = createMockClient();
+    
+    // Create a stream that yields slowly to allow event emission during iteration
+    async function* slowStream(): AsyncGenerator<AgentMessage> {
+      yield { type: "text", content: "start" };
+      await new Promise((resolve) => setTimeout(resolve, 10));
+      yield { type: "text", content: "end" };
+    }
+    
+    const stream = slowStream();
+    const session = createMockSession(stream, client);
+
+    const adapter = new OpenCodeStreamAdapter(bus, "test-session-corr");
+
+    const streamPromise = adapter.startStreaming(session, "test message", {
+      runId: 10,
+      messageId: "msg-10",
+    });
+
+    // Wait for stream to start
+    await new Promise((resolve) => setTimeout(resolve, 5));
+
+    // Register a tool with a parent agent after run initialization.
+    correlation.registerTool("tool-789", "agent-parent", true);
+
+    // Emit tool.start event
+    client.emit("tool.start" as EventType, {
+      type: "tool.start",
+      sessionId: "test-session-corr",
+      timestamp: Date.now(),
+      data: {
+        toolName: "view",
+        toolInput: { path: "/test.ts" },
+        toolUseId: "tool-789",
+      },
+    } as AgentEvent<"tool.start">);
+
+    // Emit tool.complete event
+    client.emit("tool.complete" as EventType, {
+      type: "tool.complete",
+      sessionId: "test-session-corr",
+      timestamp: Date.now(),
+      data: {
+        toolName: "view",
+        toolResult: "file contents",
+        success: true,
+        toolUseId: "tool-789",
+      },
+    } as AgentEvent<"tool.complete">);
+
+    await streamPromise;
+    await flushMicrotasks();
+    await waitForBatchFlush();
+
+    // Verify tool events were enriched with agent metadata
+    const toolCompletes = enrichedEvents.filter(
+      (e) => e.type === "stream.tool.complete",
+    );
+    expect(toolCompletes.length).toBeGreaterThan(0);
+    
+    const toolComplete = toolCompletes[0];
+    expect(toolComplete.resolvedAgentId).toBe("agent-parent");
+    expect(toolComplete.isSubagentTool).toBe(true);
+
+    dispose();
+    adapter.dispose();
+  });
+});
diff --git a/src/events/pipeline-logger.test.ts b/src/events/pipeline-logger.test.ts
new file mode 100644
index 0000000000..84ce8d350d
--- /dev/null
+++ b/src/events/pipeline-logger.test.ts
@@ -0,0 +1,164 @@
+/**
+ * Unit tests for pipeline-logger diagnostic logging utility
+ */
+
+import { describe, test, expect, beforeEach, afterEach, spyOn } from "bun:test";
+import {
+  pipelineLog,
+  pipelineError,
+  isPipelineDebug,
+  resetPipelineDebugCache,
+} from "./pipeline-logger.ts";
+
+describe("Pipeline Logger", () => {
+  let originalDebugEnv: string | undefined;
+  let debugSpy: ReturnType<typeof spyOn>;
+
+  beforeEach(() => {
+    originalDebugEnv = process.env.DEBUG;
+    resetPipelineDebugCache();
+    debugSpy = spyOn(console, "debug").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    if (originalDebugEnv === undefined) {
+      delete process.env.DEBUG;
+    } else {
+      process.env.DEBUG = originalDebugEnv;
+    }
+
+    resetPipelineDebugCache();
+    debugSpy.mockRestore();
+  });
+
+  test("isPipelineDebug() returns false when debug env is not set", () => {
+    delete process.env.DEBUG;
+    resetPipelineDebugCache();
+    expect(isPipelineDebug()).toBe(false);
+  });
+
+  test("isPipelineDebug() returns true when DEBUG=1", () => {
+    process.env.DEBUG = "1";
+    resetPipelineDebugCache();
+    expect(isPipelineDebug()).toBe(true);
+  });
+
+  test("isPipelineDebug() returns false when DEBUG=0", () => {
+    process.env.DEBUG = "0";
+    resetPipelineDebugCache();
+    expect(isPipelineDebug()).toBe(false);
+  });
+
+  test("isPipelineDebug() caches the result", () => {
+    process.env.DEBUG = "1";
+    resetPipelineDebugCache();
+    expect(isPipelineDebug()).toBe(true);
+
+    // Change env but don't reset cache — should still return true
+    process.env.DEBUG = "0";
+    expect(isPipelineDebug()).toBe(true);
+  });
+
+  test("pipelineLog() emits nothing when debug is off", () => {
+    delete process.env.DEBUG;
+    resetPipelineDebugCache();
+
+    pipelineLog("EventBus", "schema_drop", { type: "stream.text.delta" });
+    expect(debugSpy).not.toHaveBeenCalled();
+  });
+
+  test("pipelineLog() emits console.debug when debug is on", () => {
+    process.env.DEBUG = "1";
+    resetPipelineDebugCache();
+
+    pipelineLog("EventBus", "schema_drop", { type: "stream.text.delta" });
+    expect(debugSpy).toHaveBeenCalledTimes(1);
+    const msg = debugSpy.mock.calls[0]![0] as string;
+    expect(msg).toContain("[Pipeline:EventBus]");
+    expect(msg).toContain("schema_drop");
+    expect(msg).toContain("stream.text.delta");
+  });
+
+  test("pipelineLog() works without data parameter", () => {
+    process.env.DEBUG = "1";
+    resetPipelineDebugCache();
+
+    pipelineLog("Dispatcher", "flush");
+    expect(debugSpy).toHaveBeenCalledTimes(1);
+    const msg = debugSpy.mock.calls[0]![0] as string;
+    expect(msg).toBe("[Pipeline:Dispatcher] flush");
+  });
+
+  test("pipelineLog() includes structured data as JSON", () => {
+    process.env.DEBUG = "1";
+    resetPipelineDebugCache();
+
+    pipelineLog("Wire", "filter_unowned", { total: 10, owned: 7, droppedUnowned: 3 });
+    const msg = debugSpy.mock.calls[0]![0] as string;
+    expect(msg).toContain('"total":10');
+    expect(msg).toContain('"droppedUnowned":3');
+  });
+
+  test("pipelineLog() supports all pipeline stages", () => {
+    process.env.DEBUG = "1";
+    resetPipelineDebugCache();
+
+    const stages = ["EventBus", "Dispatcher", "Wire", "Consumer", "Subagent", "Workflow"] as const;
+    for (const stage of stages) {
+      pipelineLog(stage, "test_action");
+    }
+    expect(debugSpy).toHaveBeenCalledTimes(6);
+
+    for (let i = 0; i < stages.length; i++) {
+      const msg = debugSpy.mock.calls[i]![0] as string;
+      expect(msg).toContain(`[Pipeline:${stages[i]}]`);
+    }
+  });
+
+  test("resetPipelineDebugCache() allows re-evaluation", () => {
+    process.env.DEBUG = "1";
+    resetPipelineDebugCache();
+    expect(isPipelineDebug()).toBe(true);
+
+    process.env.DEBUG = "0";
+    resetPipelineDebugCache();
+    expect(isPipelineDebug()).toBe(false);
+  });
+
+  test("pipelineError() emits nothing when debug is off", () => {
+    delete process.env.DEBUG;
+    resetPipelineDebugCache();
+
+    const errorSpy = spyOn(console, "error").mockImplementation(() => {});
+    pipelineError("EventBus", "handler_error", { type: "stream.text.delta" });
+    expect(errorSpy).not.toHaveBeenCalled();
+    errorSpy.mockRestore();
+  });
+
+  test("pipelineError() emits console.error when debug is on", () => {
+    process.env.DEBUG = "1";
+    resetPipelineDebugCache();
+
+    const errorSpy = spyOn(console, "error").mockImplementation(() => {});
+    pipelineError("EventBus", "handler_error", { type: "stream.text.delta" });
+    expect(errorSpy).toHaveBeenCalledTimes(1);
+    const msg = errorSpy.mock.calls[0]![0] as string;
+    expect(msg).toContain("[Pipeline:EventBus]");
+    expect(msg).toContain("handler_error");
+    errorSpy.mockRestore();
+  });
+
+  test("pipelineError() works for Workflow stage", () => {
+    process.env.DEBUG = "1";
+    resetPipelineDebugCache();
+
+    const errorSpy = spyOn(console, "error").mockImplementation(() => {});
+    pipelineError("Workflow", "execution_failed", { nodeId: "planner" });
+    expect(errorSpy).toHaveBeenCalledTimes(1);
+    const msg = errorSpy.mock.calls[0]![0] as string;
+    expect(msg).toContain("[Pipeline:Workflow]");
+    expect(msg).toContain("execution_failed");
+    expect(msg).toContain("planner");
+    errorSpy.mockRestore();
+  });
+});
diff --git a/src/events/pipeline-logger.ts b/src/events/pipeline-logger.ts
new file mode 100644
index 0000000000..81929ddf9f
--- /dev/null
+++ b/src/events/pipeline-logger.ts
@@ -0,0 +1,90 @@
+/**
+ * Pipeline Diagnostic Logger
+ *
+ * Lightweight conditional logger for event pipeline chokepoints.
+ * Activated by the DEBUG=1 environment variable.
+ *
+ * Logs are prefixed with `[Pipeline:<stage>]` for easy filtering:
+ *   [Pipeline:EventBus] Schema validation drop ...
+ *   [Pipeline:Dispatcher] Coalesced event ...
+ *   [Pipeline:Wire] Filtered unowned event ...
+ *   [Pipeline:Consumer] Unmapped event type ...
+ *   [Pipeline:Subagent] Stream started ...
+ *
+ * Usage:
+ * ```typescript
+ * import { pipelineLog } from "./pipeline-logger.ts";
+ *
+ * pipelineLog("EventBus", "schema_drop", { type: event.type, runId: event.runId });
+ * pipelineLog("Dispatcher", "coalesce", { key, type: event.type });
+ * ```
+ */
+
+type PipelineStage =
+  | "EventBus"
+  | "Dispatcher"
+  | "Wire"
+  | "Consumer"
+  | "Subagent"
+  | "Workflow";
+
+let _debugEnabled: boolean | null = null;
+
+/**
+ * Check if pipeline diagnostic logging is enabled.
+ * Caches the result after first check for performance.
+ */
+export function isPipelineDebug(): boolean {
+  if (_debugEnabled === null) {
+    const debugValue = process.env.DEBUG?.trim().toLowerCase();
+    _debugEnabled = !!debugValue && (debugValue === "1" || debugValue === "true" || debugValue === "on");
+  }
+  return _debugEnabled;
+}
+
+/**
+ * Reset the cached debug flag (for testing).
+ */
+export function resetPipelineDebugCache(): void {
+  _debugEnabled = null;
+}
+
+/**
+ * Log a diagnostic message from a specific pipeline stage.
+ *
+ * Only emits output when DEBUG=1. Each log entry includes
+ * the stage name, a short action tag, and optional structured data.
+ *
+ * @param stage - Pipeline stage identifier
+ * @param action - Short action descriptor (e.g., "schema_drop", "coalesce", "flush")
+ * @param data - Optional structured data to include in the log
+ */
+export function pipelineLog(
+  stage: PipelineStage,
+  action: string,
+  data?: Record<string, unknown>,
+): void {
+  if (!isPipelineDebug()) return;
+  const payload = data ? ` ${JSON.stringify(data)}` : "";
+  console.debug(`[Pipeline:${stage}] ${action}${payload}`);
+}
+
+/**
+ * Log an error-level diagnostic message from a specific pipeline stage.
+ *
+ * Only emits output when DEBUG=1. Uses console.error so error messages
+ * are visible even in environments that suppress console.debug output.
+ *
+ * @param stage - Pipeline stage identifier
+ * @param action - Short action descriptor (e.g., "schema_drop", "handler_error")
+ * @param data - Optional structured data to include in the log
+ */
+export function pipelineError(
+  stage: PipelineStage,
+  action: string,
+  data?: Record<string, unknown>,
+): void {
+  if (!isPipelineDebug()) return;
+  const payload = data ? ` ${JSON.stringify(data)}` : "";
+  console.error(`[Pipeline:${stage}] ${action}${payload}`);
+}
diff --git a/src/graph/builder.test.ts b/src/graph/builder.test.ts
deleted file mode 100644
index 19e0cd5494..0000000000
--- a/src/graph/builder.test.ts
+++ /dev/null
@@ -1,591 +0,0 @@
-/**
- * Tests for GraphBuilder and graph construction
- */
-
-import { describe, expect, test } from "bun:test";
-import {
-  GraphBuilder,
-  graph,
-  createNode,
-  createDecisionNode,
-  createWaitNode,
-  type LoopConfig,
-  type ParallelConfig,
-} from "./builder.ts";
-import type { BaseState, NodeDefinition } from "./types.ts";
-
-// ============================================================================
-// TEST STATE INTERFACE
-// ============================================================================
-
-interface TestState extends BaseState {
-  count: number;
-  flag: boolean;
-  message: string;
-}
-
-// ============================================================================
-// TEST HELPER NODES
-// ============================================================================
-
-const testNode1: NodeDefinition<TestState> = {
-  id: "test1",
-  type: "tool",
-  execute: async () => ({ stateUpdate: { count: 1 } }),
-};
-
-const testNode2: NodeDefinition<TestState> = {
-  id: "test2",
-  type: "tool",
-  execute: async () => ({ stateUpdate: { count: 2 } }),
-};
-
-const testNode3: NodeDefinition<TestState> = {
-  id: "test3",
-  type: "tool",
-  execute: async () => ({ stateUpdate: { count: 3 } }),
-};
-
-// ============================================================================
-// GRAPH BUILDER: BASIC CONSTRUCTION
-// ============================================================================
-
-describe("GraphBuilder - basic construction", () => {
-  test("creates an empty builder via factory function", () => {
-    const builder = graph<TestState>();
-    expect(builder).toBeInstanceOf(GraphBuilder);
-  });
-
-  test("starts a graph with a single node", () => {
-    const builder = graph<TestState>().start(testNode1);
-    const compiled = builder.compile();
-
-    expect(compiled.startNode).toBe("test1");
-    expect(compiled.nodes.size).toBe(1);
-    expect(compiled.nodes.get("test1")).toEqual(testNode1);
-  });
-
-  test("chains nodes with then()", () => {
-    const builder = graph<TestState>().start(testNode1).then(testNode2).then(testNode3);
-    const compiled = builder.compile();
-
-    expect(compiled.nodes.size).toBe(3);
-    expect(compiled.edges.length).toBe(2);
-    expect(compiled.edges[0]).toMatchObject({ from: "test1", to: "test2" });
-    expect(compiled.edges[1]).toMatchObject({ from: "test2", to: "test3" });
-  });
-
-  test("marks terminal node with end()", () => {
-    const builder = graph<TestState>().start(testNode1).then(testNode2).end();
-    const compiled = builder.compile();
-
-    expect(compiled.endNodes.has("test2")).toBe(true);
-  });
-
-  test("infers end nodes when not explicitly marked", () => {
-    const builder = graph<TestState>().start(testNode1).then(testNode2);
-    const compiled = builder.compile();
-
-    // test2 has no outgoing edges, so it should be an end node
-    expect(compiled.endNodes.has("test2")).toBe(true);
-  });
-
-  test("throws error when starting graph twice", () => {
-    expect(() => {
-      graph<TestState>().start(testNode1).start(testNode2);
-    }).toThrow("Start node already set");
-  });
-
-  test("throws error when compiling without start node", () => {
-    expect(() => {
-      graph<TestState>().compile();
-    }).toThrow("Cannot compile graph without a start node");
-  });
-
-  test("throws error when adding duplicate node ID", () => {
-    const builder = graph<TestState>().start(testNode1);
-    
-    expect(() => {
-      builder.then(testNode1); // Same node ID
-    }).toThrow('Node with ID "test1" already exists');
-  });
-});
-
-// ============================================================================
-// GRAPH BUILDER: CONDITIONAL BRANCHES
-// ============================================================================
-
-describe("GraphBuilder - conditional branches", () => {
-  test("creates if/endif branch structure", () => {
-    const builder = graph<TestState>()
-      .start(testNode1)
-      .if((state) => state.flag === true)
-        .then(testNode2)
-      .endif()
-      .end();
-    
-    const compiled = builder.compile();
-
-    // Should have: test1, decision node, test2, merge node
-    expect(compiled.nodes.size).toBe(4);
-    
-    // Find the decision and merge nodes
-    const nodeIds = Array.from(compiled.nodes.keys());
-    const decisionNode = nodeIds.find(id => id.startsWith("decision_"));
-    const mergeNode = nodeIds.find(id => id.startsWith("merge_"));
-    
-    expect(decisionNode).toBeDefined();
-    expect(mergeNode).toBeDefined();
-    
-    // Check edges: test1 -> decision, decision -> test2, test2 -> merge
-    const edgeFromTest1 = compiled.edges.find(e => e.from === "test1");
-    expect(edgeFromTest1?.to).toBe(decisionNode);
-    
-    const edgeToTest2 = compiled.edges.find(e => e.to === "test2");
-    expect(edgeToTest2?.from).toBe(decisionNode);
-    expect(edgeToTest2?.label).toBe("if-true");
-    
-    const edgeFromTest2 = compiled.edges.find(e => e.from === "test2");
-    expect(edgeFromTest2?.to).toBe(mergeNode);
-  });
-
-  test("creates if/else/endif branch structure", () => {
-    const builder = graph<TestState>()
-      .start(testNode1)
-      .if((state) => state.flag === true)
-        .then(testNode2)
-      .else()
-        .then(testNode3)
-      .endif()
-      .end();
-    
-    const compiled = builder.compile();
-
-    // Should have: test1, decision, test2, test3, merge
-    expect(compiled.nodes.size).toBe(5);
-    
-    // Check that both branch nodes exist
-    expect(compiled.nodes.has("test2")).toBe(true);
-    expect(compiled.nodes.has("test3")).toBe(true);
-    
-    // Check edges to both branches
-    const edgeToTest2 = compiled.edges.find(e => e.to === "test2");
-    const edgeToTest3 = compiled.edges.find(e => e.to === "test3");
-    
-    expect(edgeToTest2?.label).toBe("if-true");
-    expect(edgeToTest3?.label).toBe("if-false");
-  });
-
-  test("throws error on else() without preceding if()", () => {
-    expect(() => {
-      graph<TestState>().start(testNode1).else();
-    }).toThrow("Cannot use else() without a preceding if()");
-  });
-
-  test("throws error on endif() without preceding if()", () => {
-    expect(() => {
-      graph<TestState>().start(testNode1).endif();
-    }).toThrow("Cannot use endif() without a preceding if()");
-  });
-
-  test("throws error on if() without preceding node", () => {
-    expect(() => {
-      graph<TestState>().if((state) => state.flag);
-    }).toThrow("Cannot use if() without a preceding node");
-  });
-
-  test("throws error on duplicate else()", () => {
-    expect(() => {
-      graph<TestState>()
-        .start(testNode1)
-        .if((state) => state.flag)
-          .then(testNode2)
-        .else()
-          .then(testNode3)
-        .else(); // Duplicate else
-    }).toThrow("Already in else branch");
-  });
-});
-
-// ============================================================================
-// GRAPH BUILDER: PARALLEL EXECUTION
-// ============================================================================
-
-describe("GraphBuilder - parallel execution", () => {
-  test("creates parallel execution structure", () => {
-    const parallelConfig: ParallelConfig<TestState> = {
-      branches: ["test2", "test3"],
-      strategy: "all",
-    };
-
-    const builder = graph<TestState>()
-      .start(testNode1)
-      .parallel(parallelConfig);
-    
-    const compiled = builder.compile();
-
-    // Should have test1 and a parallel node
-    expect(compiled.nodes.size).toBeGreaterThanOrEqual(2);
-    
-    // Find the parallel node
-    const parallelNode = Array.from(compiled.nodes.values()).find(n => n.type === "parallel");
-    expect(parallelNode).toBeDefined();
-    
-    // Check edge from test1 to parallel node
-    const edgeToParallel = compiled.edges.find(e => e.from === "test1");
-    expect(edgeToParallel?.to).toBe(parallelNode?.id);
-    
-    // Check edges to branches
-    const branchEdges = compiled.edges.filter(e => e.from === parallelNode?.id);
-    expect(branchEdges.length).toBe(2);
-    expect(branchEdges.map(e => e.to)).toContain("test2");
-    expect(branchEdges.map(e => e.to)).toContain("test3");
-  });
-
-  test("parallel execution can be used as start node", () => {
-    const parallelConfig: ParallelConfig<TestState> = {
-      branches: ["test1", "test2"],
-    };
-
-    const builder = graph<TestState>().parallel(parallelConfig);
-    const compiled = builder.compile();
-    
-    // Parallel node should be the start node
-    const parallelNode = Array.from(compiled.nodes.values()).find(n => n.type === "parallel");
-    expect(compiled.startNode).toBe(parallelNode!.id);
-  });
-});
-
-// ============================================================================
-// GRAPH BUILDER: LOOP CONSTRUCTS
-// ============================================================================
-
-describe("GraphBuilder - loop constructs", () => {
-  test("creates loop with single node body", () => {
-    const loopConfig: LoopConfig<TestState> = {
-      until: (state) => state.count >= 10,
-      maxIterations: 5,
-    };
-
-    const builder = graph<TestState>()
-      .start(testNode1)
-      .loop(testNode2, loopConfig);
-    
-    const compiled = builder.compile();
-
-    // Should have: test1, loop_start, test2, loop_check
-    expect(compiled.nodes.size).toBe(4);
-    
-    // Find loop nodes
-    const loopStartNode = Array.from(compiled.nodes.keys()).find(id => id.startsWith("loop_start_"));
-    const loopCheckNode = Array.from(compiled.nodes.keys()).find(id => id.startsWith("loop_check_"));
-    
-    expect(loopStartNode).toBeDefined();
-    expect(loopCheckNode).toBeDefined();
-    
-    // Check loop structure: loop_start -> test2 -> loop_check
-    const edgeToBody = compiled.edges.find(e => e.from === loopStartNode);
-    expect(edgeToBody?.to).toBe("test2");
-    
-    const edgeToCheck = compiled.edges.find(e => e.from === "test2");
-    expect(edgeToCheck?.to).toBe(loopCheckNode);
-    
-    // Check loop continuation edge
-    const continueEdge = compiled.edges.find(e => 
-      e.from === loopCheckNode && e.to === "test2" && e.label === "loop-continue"
-    );
-    expect(continueEdge).toBeDefined();
-    expect(continueEdge?.condition).toBeDefined();
-  });
-
-  test("creates loop with multi-node body", () => {
-    const loopConfig: LoopConfig<TestState> = {
-      until: (state) => state.flag === true,
-    };
-
-    const builder = graph<TestState>()
-      .start(testNode1)
-      .loop([testNode2, testNode3], loopConfig);
-    
-    const compiled = builder.compile();
-
-    // Should have: test1, loop_start, test2, test3, loop_check
-    expect(compiled.nodes.size).toBe(5);
-    
-    // Check body nodes are chained: test2 -> test3
-    const bodyEdge = compiled.edges.find(e => e.from === "test2" && e.to === "test3");
-    expect(bodyEdge).toBeDefined();
-    
-    // Check test3 connects to loop_check
-    const loopCheckNode = Array.from(compiled.nodes.keys()).find(id => id.startsWith("loop_check_"));
-    const edgeToCheck = compiled.edges.find(e => e.from === "test3");
-    expect(edgeToCheck?.to).toBe(loopCheckNode);
-  });
-
-  test("throws error on empty loop body", () => {
-    const loopConfig: LoopConfig<TestState> = {
-      until: (state) => state.flag === true,
-    };
-
-    expect(() => {
-      graph<TestState>().start(testNode1).loop([], loopConfig);
-    }).toThrow("Loop body must contain at least one node");
-  });
-
-  test("loop can be used as start node", () => {
-    const loopConfig: LoopConfig<TestState> = {
-      until: (state) => state.count >= 10,
-    };
-
-    const builder = graph<TestState>().loop(testNode1, loopConfig);
-    const compiled = builder.compile();
-    
-    // Loop start node should be the graph start
-    const loopStartNode = Array.from(compiled.nodes.keys()).find(id => id.startsWith("loop_start_"));
-    expect(compiled.startNode).toBe(loopStartNode!);
-  });
-});
-
-// ============================================================================
-// GRAPH BUILDER: WAIT NODES
-// ============================================================================
-
-describe("GraphBuilder - wait nodes", () => {
-  test("creates wait node from string prompt", () => {
-    const builder = graph<TestState>()
-      .start(testNode1)
-      .wait("Please provide input")
-      .end();
-    
-    const compiled = builder.compile();
-
-    // Should have: test1, wait node
-    expect(compiled.nodes.size).toBe(2);
-    
-    // Find the wait node
-    const waitNode = Array.from(compiled.nodes.values()).find(n => 
-      n.type === "wait" && n.id.startsWith("wait_")
-    );
-    expect(waitNode).toBeDefined();
-  });
-
-  test("creates wait node from node definition", () => {
-    const customWaitNode: NodeDefinition<TestState> = {
-      id: "custom_wait",
-      type: "wait",
-      execute: async () => ({
-        signals: [{ type: "human_input_required", message: "Custom wait" }],
-      }),
-    };
-
-    const builder = graph<TestState>()
-      .start(testNode1)
-      .wait(customWaitNode)
-      .end();
-    
-    const compiled = builder.compile();
-
-    expect(compiled.nodes.has("custom_wait")).toBe(true);
-    expect(compiled.nodes.get("custom_wait")?.type).toBe("wait");
-  });
-});
-
-// ============================================================================
-// GRAPH BUILDER: ERROR HANDLING
-// ============================================================================
-
-describe("GraphBuilder - error handling", () => {
-  test("registers error handler with catch()", () => {
-    const errorHandler: NodeDefinition<TestState> = {
-      id: "error_handler",
-      type: "tool",
-      execute: async () => ({ stateUpdate: { message: "Error handled" } }),
-    };
-
-    const builder = graph<TestState>()
-      .start(testNode1)
-      .then(testNode2)
-      .catch(errorHandler)
-      .end();
-    
-    const compiled = builder.compile();
-
-    // Error handler should be in nodes
-    expect(compiled.nodes.has("error_handler")).toBe(true);
-    
-    // Error handler ID should be in metadata
-    expect(compiled.config.metadata?.errorHandlerId).toBe("error_handler");
-  });
-});
-
-// ============================================================================
-// GRAPH BUILDER: HELPER FUNCTIONS
-// ============================================================================
-
-describe("createNode helper", () => {
-  test("creates a basic node definition", () => {
-    const node = createNode<TestState>(
-      "my_node",
-      "tool",
-      async () => ({ stateUpdate: { count: 42 } })
-    );
-
-    expect(node.id).toBe("my_node");
-    expect(node.type).toBe("tool");
-    expect(node.execute).toBeTypeOf("function");
-  });
-
-  test("creates node with optional fields", () => {
-    const node = createNode<TestState>(
-      "my_node",
-      "agent",
-      async () => ({}),
-      {
-        name: "My Node",
-        description: "Test node",
-        retry: { maxAttempts: 5, backoffMs: 500, backoffMultiplier: 2 },
-      }
-    );
-
-    expect(node.name).toBe("My Node");
-    expect(node.description).toBe("Test node");
-    expect(node.retry?.maxAttempts).toBe(5);
-  });
-});
-
-describe("createDecisionNode helper", () => {
-  test("creates decision node with routes", () => {
-    const routes = [
-      { condition: (state: TestState) => state.count > 10, target: "high" },
-      { condition: (state: TestState) => state.count > 5, target: "medium" },
-    ];
-
-    const node = createDecisionNode<TestState>("decision", routes, "low");
-
-    expect(node.id).toBe("decision");
-    expect(node.type).toBe("decision");
-    expect(node.execute).toBeTypeOf("function");
-  });
-
-  test("decision node execute returns goto for matching condition", async () => {
-    const routes = [
-      { condition: (state: TestState) => state.count > 10, target: "high" },
-    ];
-
-    const node = createDecisionNode<TestState>("decision", routes, "low");
-    
-    const state: TestState = {
-      executionId: "test",
-      lastUpdated: new Date().toISOString(),
-      outputs: {},
-      count: 15,
-      flag: false,
-      message: "",
-    };
-
-    const result = await node.execute({ state, config: {}, errors: [] });
-    expect(result.goto).toBe("high");
-  });
-
-  test("decision node execute returns fallback when no condition matches", async () => {
-    const routes = [
-      { condition: (state: TestState) => state.count > 10, target: "high" },
-    ];
-
-    const node = createDecisionNode<TestState>("decision", routes, "low");
-    
-    const state: TestState = {
-      executionId: "test",
-      lastUpdated: new Date().toISOString(),
-      outputs: {},
-      count: 5,
-      flag: false,
-      message: "",
-    };
-
-    const result = await node.execute({ state, config: {}, errors: [] });
-    expect(result.goto).toBe("low");
-  });
-});
-
-describe("createWaitNode helper", () => {
-  test("creates wait node with prompt", () => {
-    const node = createWaitNode<TestState>("wait1", "Enter your name");
-
-    expect(node.id).toBe("wait1");
-    expect(node.type).toBe("wait");
-    expect(node.execute).toBeTypeOf("function");
-  });
-
-  test("wait node execute returns human_input_required signal", async () => {
-    const node = createWaitNode<TestState>("wait1", "Enter your name");
-    
-    const result = await node.execute({
-      state: {
-        executionId: "test",
-        lastUpdated: new Date().toISOString(),
-        outputs: {},
-        count: 0,
-        flag: false,
-        message: "",
-      },
-      config: {},
-      errors: [],
-    });
-
-    expect(result.signals).toBeDefined();
-    expect(result.signals?.length).toBe(1);
-    expect(result.signals?.[0]?.type).toBe("human_input_required");
-    expect(result.signals?.[0]?.message).toBe("Enter your name");
-  });
-});
-
-// ============================================================================
-// GRAPH BUILDER: QUERY METHODS
-// ============================================================================
-
-describe("GraphBuilder - query methods", () => {
-  test("getNode returns node by ID", () => {
-    const builder = graph<TestState>().start(testNode1).then(testNode2);
-    
-    expect(builder.getNode("test1")).toEqual(testNode1);
-    expect(builder.getNode("test2")).toEqual(testNode2);
-    expect(builder.getNode("nonexistent")).toBeUndefined();
-  });
-
-  test("getEdgesFrom returns outgoing edges", () => {
-    const builder = graph<TestState>()
-      .start(testNode1)
-      .then(testNode2)
-      .then(testNode3);
-    
-    const edges = builder.getEdgesFrom("test1");
-    expect(edges.length).toBe(1);
-    expect(edges[0]).toMatchObject({ from: "test1", to: "test2" });
-  });
-
-  test("getEdgesTo returns incoming edges", () => {
-    const builder = graph<TestState>()
-      .start(testNode1)
-      .then(testNode2)
-      .then(testNode3);
-    
-    const edges = builder.getEdgesTo("test2");
-    expect(edges.length).toBe(1);
-    expect(edges[0]).toMatchObject({ from: "test1", to: "test2" });
-  });
-
-  test("getEdgesFrom returns empty array for node with no outgoing edges", () => {
-    const builder = graph<TestState>().start(testNode1);
-    
-    const edges = builder.getEdgesFrom("test1");
-    expect(edges).toEqual([]);
-  });
-
-  test("getEdgesTo returns empty array for start node", () => {
-    const builder = graph<TestState>().start(testNode1).then(testNode2);
-    
-    const edges = builder.getEdgesTo("test1");
-    expect(edges).toEqual([]);
-  });
-});
diff --git a/src/graph/subagent-bridge.ts b/src/graph/subagent-bridge.ts
deleted file mode 100644
index e33b14a482..0000000000
--- a/src/graph/subagent-bridge.ts
+++ /dev/null
@@ -1,223 +0,0 @@
-/**
- * Sub-Agent Graph Bridge
- *
- * Lightweight bridge for sub-agent execution within graph workflows.
- * Creates SDK sessions directly and sends task messages, letting each
- * SDK's native sub-agent dispatch handle execution.
- *
- * Result persistence: ~/.atomic/workflows/sessions/{sessionId}/agents/
- *
- * Follows the existing setClientProvider() / setWorkflowResolver() global setter pattern.
- */
-
-import type { Session, SessionConfig } from "../sdk/types.ts";
-import { saveSubagentOutput } from "../workflows/session.ts";
-
-// ============================================================================
-// Types (moved from subagent-session-manager.ts)
-// ============================================================================
-
-/**
- * Factory function that creates independent sessions for sub-agents.
- */
-export type CreateSessionFn = (config?: SessionConfig) => Promise<Session>;
-
-/**
- * Options for spawning a single sub-agent session.
- */
-export interface SubagentSpawnOptions {
-  /** Unique identifier for this sub-agent */
-  agentId: string;
-  /** Display name (e.g., "codebase-analyzer", "debugger") */
-  agentName: string;
-  /** Task description to send to the sub-agent */
-  task: string;
-  /** Optional system prompt override */
-  systemPrompt?: string;
-  /** Optional model override */
-  model?: string;
-  /** Optional tool restrictions */
-  tools?: string[];
-}
-
-/**
- * Result returned after a sub-agent completes or fails.
- */
-export interface SubagentResult {
-  /** Agent identifier matching SubagentSpawnOptions.agentId */
-  agentId: string;
-  /** Whether the sub-agent completed successfully */
-  success: boolean;
-  /** Summary text returned to parent (truncated to MAX_SUMMARY_LENGTH) */
-  output: string;
-  /** Error message if the sub-agent failed */
-  error?: string;
-  /** Number of tool invocations during execution */
-  toolUses: number;
-  /** Execution duration in milliseconds */
-  durationMs: number;
-}
-
-// ============================================================================
-// Constants
-// ============================================================================
-
-/** Maximum length of summary text returned to parent context */
-const MAX_SUMMARY_LENGTH = 4000;
-
-// ============================================================================
-// Bridge Configuration
-// ============================================================================
-
-interface SubagentGraphBridgeConfig {
-  /** Factory to create independent sessions */
-  createSession: CreateSessionFn;
-  /** Optional session directory for result persistence */
-  sessionDir?: string;
-}
-
-// ============================================================================
-// Bridge Class
-// ============================================================================
-
-/**
- * Lightweight bridge for sub-agent execution in graph workflows.
- *
- * Creates a session per sub-agent, sends the task message, collects
- * the response, and destroys the session. The SDK's native sub-agent
- * dispatch handles tool configuration and model selection.
- */
-export class SubagentGraphBridge {
-  private createSession: CreateSessionFn;
-  private sessionDir: string | undefined;
-
-  constructor(config: SubagentGraphBridgeConfig) {
-    this.createSession = config.createSession;
-    this.sessionDir = config.sessionDir;
-  }
-
-  setSessionDir(dir: string): void {
-    this.sessionDir = dir;
-  }
-
-  /**
-   * Spawn a single sub-agent by creating a session and sending a task message.
-   */
-  async spawn(options: SubagentSpawnOptions): Promise<SubagentResult> {
-    const startTime = Date.now();
-    let toolUses = 0;
-    const summaryParts: string[] = [];
-    let session: Session | null = null;
-
-    try {
-      // Create session with optional overrides
-      const sessionConfig: SessionConfig = {};
-      if (options.systemPrompt) sessionConfig.systemPrompt = options.systemPrompt;
-      if (options.model) sessionConfig.model = options.model;
-      if (options.tools) sessionConfig.tools = options.tools;
-
-      session = await this.createSession(sessionConfig);
-
-      // Stream response
-      for await (const msg of session.stream(options.task)) {
-        if (msg.type === "tool_use") {
-          toolUses++;
-        } else if (msg.type === "text" && typeof msg.content === "string") {
-          summaryParts.push(msg.content);
-        }
-      }
-
-      // Build truncated summary
-      const fullSummary = summaryParts.join("");
-      const output =
-        fullSummary.length > MAX_SUMMARY_LENGTH
-          ? fullSummary.slice(0, MAX_SUMMARY_LENGTH) + "..."
-          : fullSummary;
-
-      const result: SubagentResult = {
-        agentId: options.agentId,
-        success: true,
-        output,
-        toolUses,
-        durationMs: Date.now() - startTime,
-      };
-
-      if (this.sessionDir) {
-        await saveSubagentOutput(this.sessionDir, options.agentId, result);
-      }
-
-      return result;
-    } catch (error) {
-      const durationMs = Date.now() - startTime;
-      const errorMessage =
-        error instanceof Error ? error.message : String(error ?? "Unknown error");
-
-      const result: SubagentResult = {
-        agentId: options.agentId,
-        success: false,
-        output: "",
-        error: errorMessage,
-        toolUses,
-        durationMs,
-      };
-
-      if (this.sessionDir) {
-        await saveSubagentOutput(this.sessionDir, options.agentId, result).catch(() => {});
-      }
-
-      return result;
-    } finally {
-      if (session) {
-        try {
-          await session.destroy();
-        } catch {
-          // Session may already be destroyed
-        }
-      }
-    }
-  }
-
-  /**
-   * Spawn multiple sub-agents concurrently.
-   * Uses Promise.allSettled() so one agent's failure doesn't cancel others.
-   */
-  async spawnParallel(
-    agents: SubagentSpawnOptions[],
-  ): Promise<SubagentResult[]> {
-    const results = await Promise.allSettled(
-      agents.map((agent) => this.spawn(agent))
-    );
-
-    return results.map((result, i) => {
-      if (result.status === "fulfilled") {
-        return result.value;
-      }
-      const agent = agents[i];
-      return {
-        agentId: agent?.agentId ?? `unknown-${i}`,
-        success: false,
-        output: "",
-        error:
-          result.reason instanceof Error
-            ? result.reason.message
-            : String(result.reason ?? "Unknown error"),
-        toolUses: 0,
-        durationMs: 0,
-      };
-    });
-  }
-}
-
-// ============================================================================
-// Singleton
-// ============================================================================
-
-let globalSubagentBridge: SubagentGraphBridge | null = null;
-
-export function setSubagentBridge(bridge: SubagentGraphBridge | null): void {
-  globalSubagentBridge = bridge;
-}
-
-export function getSubagentBridge(): SubagentGraphBridge | null {
-  return globalSubagentBridge;
-}
diff --git a/src/scripts/postinstall-playwright.test.ts b/src/scripts/postinstall-playwright.test.ts
new file mode 100644
index 0000000000..a3835207c4
--- /dev/null
+++ b/src/scripts/postinstall-playwright.test.ts
@@ -0,0 +1,70 @@
+import { expect, test } from "bun:test";
+import { mkdtemp, mkdir, readFile, rm, writeFile } from "fs/promises";
+import { tmpdir } from "os";
+import { dirname, join } from "path";
+
+import { deployPlaywrightSkill } from "./postinstall-playwright";
+
+const PLAYWRIGHT_SKILL_RELATIVE_PATH = join("skills", "playwright-cli", "SKILL.md");
+
+async function writeSkillTemplate(
+  configRoot: string,
+  agentFolder: string,
+  content: string
+): Promise<void> {
+  const skillPath = join(configRoot, agentFolder, PLAYWRIGHT_SKILL_RELATIVE_PATH);
+  await mkdir(dirname(skillPath), { recursive: true });
+  await writeFile(skillPath, content, "utf-8");
+}
+
+test("deployPlaywrightSkill copies SKILL.md to each global agent folder", async () => {
+  const root = await mkdtemp(join(tmpdir(), "postinstall-playwright-"));
+
+  try {
+    const configRoot = join(root, "config");
+    const atomicHome = join(root, ".atomic");
+
+    await writeSkillTemplate(configRoot, ".claude", "# claude skill\n");
+    await writeSkillTemplate(configRoot, ".opencode", "# opencode skill\n");
+    await writeSkillTemplate(configRoot, ".github", "# copilot skill\n");
+
+    await deployPlaywrightSkill(configRoot, atomicHome);
+
+    const claudeSkill = await readFile(
+      join(atomicHome, ".claude", PLAYWRIGHT_SKILL_RELATIVE_PATH),
+      "utf-8"
+    );
+    const opencodeSkill = await readFile(
+      join(atomicHome, ".opencode", PLAYWRIGHT_SKILL_RELATIVE_PATH),
+      "utf-8"
+    );
+    const copilotSkill = await readFile(
+      join(atomicHome, ".copilot", PLAYWRIGHT_SKILL_RELATIVE_PATH),
+      "utf-8"
+    );
+
+    expect(claudeSkill).toBe("# claude skill\n");
+    expect(opencodeSkill).toBe("# opencode skill\n");
+    expect(copilotSkill).toBe("# copilot skill\n");
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("deployPlaywrightSkill errors when templates are missing", async () => {
+  const root = await mkdtemp(join(tmpdir(), "postinstall-playwright-missing-"));
+
+  try {
+    const configRoot = join(root, "config");
+    const atomicHome = join(root, ".atomic");
+
+    await writeSkillTemplate(configRoot, ".claude", "# claude skill\n");
+    await writeSkillTemplate(configRoot, ".opencode", "# opencode skill\n");
+
+    await expect(deployPlaywrightSkill(configRoot, atomicHome)).rejects.toThrow(
+      "Missing Playwright skill template"
+    );
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
diff --git a/src/scripts/postinstall-playwright.ts b/src/scripts/postinstall-playwright.ts
new file mode 100644
index 0000000000..0a8eb5f4d8
--- /dev/null
+++ b/src/scripts/postinstall-playwright.ts
@@ -0,0 +1,198 @@
+import { mkdir } from "fs/promises";
+import { join } from "path";
+
+import { AGENT_CONFIG, type AgentKey } from "../config";
+import {
+  getAtomicGlobalAgentFolder,
+  getAtomicHomeDir,
+  getTemplateAgentFolder,
+} from "../utils/atomic-global-config";
+import { copyFile, pathExists } from "../utils/copy";
+
+const PLAYWRIGHT_SKILL_RELATIVE_PATH = join("skills", "playwright-cli", "SKILL.md");
+const PLAYWRIGHT_CLI_PACKAGE = "@playwright/cli@latest";
+
+function decodeSpawnOutput(output: Uint8Array): string {
+  return new TextDecoder().decode(output).trim();
+}
+
+function runInstallCommand(cmd: string[]): { success: boolean; details: string } {
+  try {
+    const result = Bun.spawnSync({
+      cmd,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    const stderr = decodeSpawnOutput(result.stderr);
+    const stdout = decodeSpawnOutput(result.stdout);
+    return {
+      success: result.success,
+      details: stderr.length > 0 ? stderr : stdout,
+    };
+  } catch (error) {
+    return {
+      success: false,
+      details: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+function prependPath(directory: string): void {
+  const pathDelimiter = process.platform === "win32" ? ";" : ":";
+  const currentPath = process.env.PATH ?? "";
+  const entries = currentPath.split(pathDelimiter);
+  if (!entries.includes(directory)) {
+    process.env.PATH = directory + pathDelimiter + currentPath;
+  }
+}
+
+function installBunIfMissing(): void {
+  if (Bun.which("bun")) {
+    return;
+  }
+
+  if (process.platform === "win32") {
+    const powerShellPath = Bun.which("powershell") ?? Bun.which("pwsh");
+    if (!powerShellPath) {
+      return;
+    }
+    runInstallCommand([
+      powerShellPath,
+      "-NoProfile",
+      "-ExecutionPolicy",
+      "Bypass",
+      "-Command",
+      "Invoke-RestMethod https://bun.sh/install.ps1 | Invoke-Expression",
+    ]);
+  } else {
+    const shell = Bun.which("bash") ?? Bun.which("sh");
+    if (!shell) {
+      return;
+    }
+    runInstallCommand([shell, "-lc", "curl -fsSL https://bun.sh/install | bash"]);
+  }
+
+  const homeDir = process.env.HOME ?? process.env.USERPROFILE;
+  if (homeDir) {
+    prependPath(join(homeDir, ".bun", "bin"));
+  }
+}
+
+function installNpmIfMissing(): void {
+  if (Bun.which("npm")) {
+    return;
+  }
+
+  if (process.platform === "win32") {
+    if (Bun.which("winget")) {
+      runInstallCommand([
+        "winget",
+        "install",
+        "--id",
+        "OpenJS.NodeJS.LTS",
+        "-e",
+        "--silent",
+        "--accept-source-agreements",
+        "--accept-package-agreements",
+      ]);
+    } else if (Bun.which("choco")) {
+      runInstallCommand(["choco", "install", "nodejs-lts", "-y", "--no-progress"]);
+    } else if (Bun.which("scoop")) {
+      runInstallCommand(["scoop", "install", "nodejs-lts"]);
+    }
+
+    const programFiles = process.env.ProgramFiles;
+    if (programFiles) {
+      prependPath(join(programFiles, "nodejs"));
+    }
+    return;
+  }
+
+  const shell = Bun.which("bash") ?? Bun.which("sh");
+  if (!shell) {
+    return;
+  }
+  const installers = [
+    "if command -v brew >/dev/null 2>&1; then brew install node; fi",
+    "if command -v apt-get >/dev/null 2>&1; then if command -v sudo >/dev/null 2>&1; then sudo apt-get update && sudo apt-get install -y nodejs npm; elif [ \"$(id -u)\" -eq 0 ]; then apt-get update && apt-get install -y nodejs npm; fi; fi",
+    "if command -v dnf >/dev/null 2>&1; then if command -v sudo >/dev/null 2>&1; then sudo dnf install -y nodejs npm; elif [ \"$(id -u)\" -eq 0 ]; then dnf install -y nodejs npm; fi; fi",
+    "if command -v yum >/dev/null 2>&1; then if command -v sudo >/dev/null 2>&1; then sudo yum install -y nodejs npm; elif [ \"$(id -u)\" -eq 0 ]; then yum install -y nodejs npm; fi; fi",
+    "if command -v pacman >/dev/null 2>&1; then if command -v sudo >/dev/null 2>&1; then sudo pacman -Sy --noconfirm nodejs npm; elif [ \"$(id -u)\" -eq 0 ]; then pacman -Sy --noconfirm nodejs npm; fi; fi",
+    "if command -v zypper >/dev/null 2>&1; then if command -v sudo >/dev/null 2>&1; then sudo zypper --non-interactive install nodejs npm; elif [ \"$(id -u)\" -eq 0 ]; then zypper --non-interactive install nodejs npm; fi; fi",
+    "if command -v apk >/dev/null 2>&1; then if command -v sudo >/dev/null 2>&1; then sudo apk add --no-cache nodejs npm; elif [ \"$(id -u)\" -eq 0 ]; then apk add --no-cache nodejs npm; fi; fi",
+  ];
+
+  for (const script of installers) {
+    if (Bun.which("npm")) {
+      return;
+    }
+    runInstallCommand([shell, "-lc", script]);
+  }
+}
+
+export function ensurePlaywrightPackageManagers(): void {
+  installBunIfMissing();
+  installNpmIfMissing();
+}
+
+export async function installPlaywrightCli(): Promise<void> {
+  const failures: string[] = [];
+
+  const bunPath = Bun.which("bun");
+  if (bunPath) {
+    const bunInstall = runInstallCommand([bunPath, "install", "-g", PLAYWRIGHT_CLI_PACKAGE]);
+    if (bunInstall.success) {
+      return;
+    }
+    failures.push(`bun: ${bunInstall.details || "No output."}`);
+  }
+
+  const npmPath = Bun.which("npm");
+  if (npmPath) {
+    const npmInstall = runInstallCommand([npmPath, "install", "-g", PLAYWRIGHT_CLI_PACKAGE]);
+    if (npmInstall.success) {
+      return;
+    }
+    failures.push(`npm: ${npmInstall.details || "No output."}`);
+  }
+
+  if (failures.length === 0) {
+    throw new Error("Neither bun nor npm is available to install @playwright/cli.");
+  }
+
+  throw new Error(`Failed to install ${PLAYWRIGHT_CLI_PACKAGE}: ${failures.join(" | ")}`);
+}
+
+export async function deployPlaywrightSkill(
+  configRoot: string,
+  atomicHomeDir: string = getAtomicHomeDir()
+): Promise<void> {
+  const agentKeys = Object.keys(AGENT_CONFIG) as AgentKey[];
+  const missingSkillTemplates: string[] = [];
+
+  for (const agentKey of agentKeys) {
+    const sourceSkillPath = join(
+      configRoot,
+      getTemplateAgentFolder(agentKey),
+      PLAYWRIGHT_SKILL_RELATIVE_PATH
+    );
+
+    if (!(await pathExists(sourceSkillPath))) {
+      missingSkillTemplates.push(sourceSkillPath);
+      continue;
+    }
+
+    const destinationAgentFolder = join(atomicHomeDir, getAtomicGlobalAgentFolder(agentKey));
+    const destinationSkillDir = join(destinationAgentFolder, "skills", "playwright-cli");
+    await mkdir(destinationSkillDir, { recursive: true });
+
+    const destinationSkillPath = join(destinationSkillDir, "SKILL.md");
+    await copyFile(sourceSkillPath, destinationSkillPath);
+  }
+
+  if (missingSkillTemplates.length > 0) {
+    throw new Error(
+      `Missing Playwright skill template(s): ${missingSkillTemplates.join(", ")}`
+    );
+  }
+}
diff --git a/src/scripts/postinstall.integration.test.ts b/src/scripts/postinstall.integration.test.ts
new file mode 100644
index 0000000000..dc7f1d83b8
--- /dev/null
+++ b/src/scripts/postinstall.integration.test.ts
@@ -0,0 +1,99 @@
+import { describe, expect, test } from "bun:test";
+import { dirname, join } from "path";
+import { mkdtemp, mkdir, readFile, rm, writeFile } from "fs/promises";
+import { tmpdir } from "os";
+
+import { syncAtomicGlobalAgentConfigs } from "../utils/atomic-global-config";
+import { getConfigRoot } from "../utils/config-path";
+import { deployPlaywrightSkill } from "./postinstall-playwright";
+
+const PLAYWRIGHT_SKILL_RELATIVE_PATH = join("skills", "playwright-cli", "SKILL.md");
+const LEGACY_WEB_TOOL_TOKENS = ["WebFetch", "WebSearch", "webfetch", '"web"'] as const;
+
+const CLAUDE_DEBUGGER_PATH = join(".claude", "agents", "debugger.md");
+const OPENCODE_CONFIG_PATH = join(".opencode", "opencode.json");
+const COPILOT_TEMPLATE_DEBUGGER_PATH = join(".github", "agents", "debugger.md");
+const CLAUDE_SKILL_TEMPLATE_PATH = join(".claude", PLAYWRIGHT_SKILL_RELATIVE_PATH);
+const OPENCODE_SKILL_TEMPLATE_PATH = join(".opencode", PLAYWRIGHT_SKILL_RELATIVE_PATH);
+const COPILOT_SKILL_TEMPLATE_PATH = join(".github", PLAYWRIGHT_SKILL_RELATIVE_PATH);
+
+const CLAUDE_GLOBAL_DEBUGGER_PATH = join(".claude", "agents", "debugger.md");
+const OPENCODE_GLOBAL_CONFIG_PATH = join(".opencode", "opencode.json");
+const COPILOT_GLOBAL_DEBUGGER_PATH = join(".copilot", "agents", "debugger.md");
+const CLAUDE_GLOBAL_SKILL_PATH = join(".claude", PLAYWRIGHT_SKILL_RELATIVE_PATH);
+const OPENCODE_GLOBAL_SKILL_PATH = join(".opencode", PLAYWRIGHT_SKILL_RELATIVE_PATH);
+const COPILOT_GLOBAL_SKILL_PATH = join(".copilot", PLAYWRIGHT_SKILL_RELATIVE_PATH);
+
+async function writeTextFile(filePath: string, content: string): Promise<void> {
+  await mkdir(dirname(filePath), { recursive: true });
+  await writeFile(filePath, content, "utf-8");
+}
+
+async function readTextFile(baseDir: string, relativePath: string): Promise<string> {
+  return readFile(join(baseDir, relativePath), "utf-8");
+}
+
+async function seedLegacyToolConfigs(atomicHome: string): Promise<void> {
+  await writeTextFile(
+    join(atomicHome, CLAUDE_GLOBAL_DEBUGGER_PATH),
+    "tools: Read, WebFetch, WebSearch\n",
+  );
+  await writeTextFile(join(atomicHome, OPENCODE_GLOBAL_CONFIG_PATH), '{"permission":{"webfetch":"allow"}}\n');
+  await writeTextFile(
+    join(atomicHome, COPILOT_GLOBAL_DEBUGGER_PATH),
+    'tools: ["execute", "read", "web"]\n',
+  );
+}
+
+describe("postinstall integration", () => {
+  test("syncs cleaned configs and re-deploys playwright skills", async () => {
+    const root = await mkdtemp(join(tmpdir(), "postinstall-integration-"));
+
+    try {
+      const configRoot = getConfigRoot();
+      const atomicHome = join(root, ".atomic");
+
+      await seedLegacyToolConfigs(atomicHome);
+
+      await syncAtomicGlobalAgentConfigs(configRoot, atomicHome);
+
+      const sourceClaudeDebugger = await readTextFile(configRoot, CLAUDE_DEBUGGER_PATH);
+      const sourceOpencodeConfig = await readTextFile(configRoot, OPENCODE_CONFIG_PATH);
+      const sourceCopilotDebugger = await readTextFile(configRoot, COPILOT_TEMPLATE_DEBUGGER_PATH);
+
+      const claudeDebugger = await readTextFile(atomicHome, CLAUDE_GLOBAL_DEBUGGER_PATH);
+      const opencodeConfig = await readTextFile(atomicHome, OPENCODE_GLOBAL_CONFIG_PATH);
+      const copilotDebugger = await readTextFile(atomicHome, COPILOT_GLOBAL_DEBUGGER_PATH);
+
+      expect(claudeDebugger).toBe(sourceClaudeDebugger);
+      expect(opencodeConfig).toBe(sourceOpencodeConfig);
+      expect(copilotDebugger).toBe(sourceCopilotDebugger);
+
+      for (const token of LEGACY_WEB_TOOL_TOKENS) {
+        expect(claudeDebugger.includes(token)).toBe(false);
+        expect(opencodeConfig.includes(token)).toBe(false);
+        expect(copilotDebugger.includes(token)).toBe(false);
+      }
+
+      await rm(join(atomicHome, CLAUDE_GLOBAL_SKILL_PATH), { force: true });
+      await rm(join(atomicHome, OPENCODE_GLOBAL_SKILL_PATH), { force: true });
+      await rm(join(atomicHome, COPILOT_GLOBAL_SKILL_PATH), { force: true });
+
+      await deployPlaywrightSkill(configRoot, atomicHome);
+
+      const sourceClaudeSkill = await readTextFile(configRoot, CLAUDE_SKILL_TEMPLATE_PATH);
+      const sourceOpencodeSkill = await readTextFile(configRoot, OPENCODE_SKILL_TEMPLATE_PATH);
+      const sourceCopilotSkill = await readTextFile(configRoot, COPILOT_SKILL_TEMPLATE_PATH);
+
+      const claudeSkill = await readTextFile(atomicHome, CLAUDE_GLOBAL_SKILL_PATH);
+      const opencodeSkill = await readTextFile(atomicHome, OPENCODE_GLOBAL_SKILL_PATH);
+      const copilotSkill = await readTextFile(atomicHome, COPILOT_GLOBAL_SKILL_PATH);
+
+      expect(claudeSkill).toBe(sourceClaudeSkill);
+      expect(opencodeSkill).toBe(sourceOpencodeSkill);
+      expect(copilotSkill).toBe(sourceCopilotSkill);
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+});
diff --git a/src/scripts/postinstall.ts b/src/scripts/postinstall.ts
index a70bf060e6..76a1e2b774 100644
--- a/src/scripts/postinstall.ts
+++ b/src/scripts/postinstall.ts
@@ -5,6 +5,19 @@ import {
   syncAtomicGlobalAgentConfigs,
 } from "../utils/atomic-global-config";
 import { getConfigRoot } from "../utils/config-path";
+import {
+  deployPlaywrightSkill,
+  ensurePlaywrightPackageManagers,
+  installPlaywrightCli,
+} from "./postinstall-playwright";
+
+function formatErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function warnPostinstallStep(step: string, error: unknown): void {
+  console.warn(`[atomic] Warning: ${step}: ${formatErrorMessage(error)}`);
+}
 
 async function verifyAtomicGlobalConfigSync(): Promise<void> {
   if (!(await hasAtomicGlobalAgentConfigs())) {
@@ -13,12 +26,36 @@ async function verifyAtomicGlobalConfigSync(): Promise<void> {
 }
 
 async function main(): Promise<void> {
+  const configRoot = getConfigRoot();
+
+  try {
+    await syncAtomicGlobalAgentConfigs(configRoot);
+  } catch (error) {
+    warnPostinstallStep("failed to sync ~/.atomic global configs", error);
+  }
+
+  try {
+    ensurePlaywrightPackageManagers();
+  } catch (error) {
+    warnPostinstallStep("failed to install missing package managers (bun/npm)", error);
+  }
+
+  try {
+    await installPlaywrightCli();
+  } catch (error) {
+    warnPostinstallStep("failed to install @playwright/cli globally", error);
+  }
+
+  try {
+    await deployPlaywrightSkill(configRoot);
+  } catch (error) {
+    warnPostinstallStep("failed to deploy Playwright SKILL.md", error);
+  }
+
   try {
-    await syncAtomicGlobalAgentConfigs(getConfigRoot());
     await verifyAtomicGlobalConfigSync();
   } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    console.warn(`[atomic] Warning: failed to sync ~/.atomic global configs: ${message}`);
+    warnPostinstallStep("failed to verify ~/.atomic global config sync", error);
   }
 }
 
diff --git a/src/sdk/base-client.ts b/src/sdk/base-client.ts
index 024888bc7a..4960f0e571 100644
--- a/src/sdk/base-client.ts
+++ b/src/sdk/base-client.ts
@@ -5,7 +5,6 @@
  * agent-specific client implementations (Claude, OpenCode, Copilot).
  *
  * Common patterns extracted:
- * - Event handler registration and dispatch
  * - Session state management helpers
  * - Agent event construction
  *
@@ -18,91 +17,9 @@
 
 import type {
   EventType,
-  EventHandler,
   AgentEvent,
 } from "./types.ts";
 
-/**
- * Manages event handler registration and dispatch.
- *
- * This class extracts the common event handling pattern used across
- * all client implementations. Each client has agent-specific event
- * mapping logic, but the registration and dispatch mechanism is identical.
- */
-export class EventEmitter {
-  private eventHandlers: Map<EventType, Set<EventHandler<EventType>>> = new Map();
-
-  /**
-   * Register an event handler for a specific event type.
-   * @param eventType - The type of event to listen for
-   * @param handler - Callback function to handle the event
-   * @returns Function to unregister the handler
-   */
-  on<T extends EventType>(eventType: T, handler: EventHandler<T>): () => void {
-    let handlers = this.eventHandlers.get(eventType);
-    if (!handlers) {
-      handlers = new Set();
-      this.eventHandlers.set(eventType, handlers);
-    }
-
-    handlers.add(handler as EventHandler<EventType>);
-
-    return () => {
-      handlers?.delete(handler as EventHandler<EventType>);
-    };
-  }
-
-  /**
-   * Emit an event to all registered handlers.
-   *
-   * Note: Agent-specific clients may extend this to also emit to
-   * native SDK hooks (e.g., Claude's HookCallback system).
-   *
-   * @param eventType - Type of event to emit
-   * @param sessionId - Session that emitted this event
-   * @param data - Event-specific data
-   */
-  emit<T extends EventType>(
-    eventType: T,
-    sessionId: string,
-    data: Record<string, unknown>
-  ): void {
-    const handlers = this.eventHandlers.get(eventType);
-    if (!handlers) return;
-
-    const event: AgentEvent<T> = {
-      type: eventType,
-      sessionId,
-      timestamp: new Date().toISOString(),
-      data: data as AgentEvent<T>["data"],
-    };
-
-    for (const handler of handlers) {
-      try {
-        handler(event as AgentEvent<EventType>);
-      } catch (error) {
-        console.error(`Error in event handler for ${eventType}:`, error);
-      }
-    }
-  }
-
-  /**
-   * Clear all registered event handlers.
-   * Called during client shutdown.
-   */
-  clearHandlers(): void {
-    this.eventHandlers.clear();
-  }
-
-  /**
-   * Check if any handlers are registered for an event type.
-   */
-  hasHandlers(eventType: EventType): boolean {
-    const handlers = this.eventHandlers.get(eventType);
-    return handlers !== undefined && handlers.size > 0;
-  }
-}
-
 /**
  * Creates a standardized AgentEvent object.
  *
diff --git a/src/sdk/clients/claude.process-exit-error.test.ts b/src/sdk/clients/claude.process-exit-error.test.ts
new file mode 100644
index 0000000000..dc7dd7c123
--- /dev/null
+++ b/src/sdk/clients/claude.process-exit-error.test.ts
@@ -0,0 +1,66 @@
+import { describe, expect, mock, test } from "bun:test";
+
+mock.module("@anthropic-ai/claude-agent-sdk", () => ({
+    query: () => ({
+        async *[Symbol.asyncIterator]() {
+            throw new Error("Claude Code process exited with code 1");
+        },
+        close: () => {
+            return;
+        },
+        mcpServerStatus: async () => [],
+        supportedModels: async () => [],
+    }),
+    createSdkMcpServer: () => ({
+        close: () => {
+            return;
+        },
+    }),
+}));
+
+describe("ClaudeAgentClient process-exit diagnostics", () => {
+    test("propagates Claude process-exit errors without rewriting the message", async () => {
+        const { ClaudeAgentClient } = await import("./claude.ts");
+        const client = new ClaudeAgentClient();
+
+        const privateClient = client as unknown as {
+            buildSdkOptions: (
+                config: Record<string, unknown>,
+                sessionId?: string,
+            ) => Record<string, unknown>;
+            wrapQuery: (
+                queryInstance: null,
+                sessionId: string,
+                config: Record<string, unknown>,
+            ) => {
+                send: (message: string) => Promise<unknown>;
+                stream: (
+                    message: string,
+                    options?: { agent?: string },
+                ) => AsyncIterable<unknown>;
+                destroy: () => Promise<void>;
+            };
+        };
+
+        privateClient.buildSdkOptions = () => ({});
+        const session = privateClient.wrapQuery(null, "diagnostic-session", {});
+
+        await expect(session.send("hello")).rejects.toThrow(
+            "Claude Code process exited with code 1",
+        );
+
+        let streamError: Error | null = null;
+        try {
+            for await (const _chunk of session.stream("hello", { agent: "planner" })) {
+                // Stream is expected to error before yielding chunks.
+            }
+        } catch (error) {
+            streamError = error instanceof Error ? error : new Error(String(error));
+        }
+
+        expect(streamError).not.toBeNull();
+        expect(streamError!.message).toBe("Claude Code process exited with code 1");
+
+        await session.destroy();
+    });
+});
diff --git a/src/sdk/clients/claude.stream-agent-option.test.ts b/src/sdk/clients/claude.stream-agent-option.test.ts
new file mode 100644
index 0000000000..913584fae4
--- /dev/null
+++ b/src/sdk/clients/claude.stream-agent-option.test.ts
@@ -0,0 +1,89 @@
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+const queryCalls: Array<{
+    prompt: string;
+    options: Record<string, unknown>;
+}> = [];
+
+mock.module("@anthropic-ai/claude-agent-sdk", () => ({
+    query: ({
+        prompt,
+        options,
+    }: {
+        prompt: string;
+        options: Record<string, unknown>;
+    }) => {
+        queryCalls.push({ prompt, options });
+
+        return {
+            async *[Symbol.asyncIterator]() {
+                yield {
+                    type: "result",
+                    subtype: "success",
+                    usage: { input_tokens: 0, output_tokens: 0 },
+                };
+            },
+            close: () => {
+                return;
+            },
+            mcpServerStatus: async () => [],
+            supportedModels: async () => [],
+        };
+    },
+    createSdkMcpServer: () => ({
+        close: () => {
+            return;
+        },
+    }),
+}));
+
+describe("ClaudeAgentClient stream sub-agent routing", () => {
+    beforeEach(() => {
+        queryCalls.length = 0;
+    });
+
+    test("passes the selected agent through SDK options", async () => {
+        const { ClaudeAgentClient } = await import("./claude.ts");
+        const client = new ClaudeAgentClient();
+
+        const privateClient = client as unknown as {
+            buildSdkOptions: (
+                config: Record<string, unknown>,
+                sessionId?: string,
+            ) => Record<string, unknown>;
+            wrapQuery: (
+                queryInstance: null,
+                sessionId: string,
+                config: Record<string, unknown>,
+            ) => {
+                stream: (
+                    message: string,
+                    options?: { agent?: string },
+                ) => AsyncIterable<{ type: string; content?: string }>;
+                destroy: () => Promise<void>;
+            };
+        };
+
+        privateClient.buildSdkOptions = () => ({});
+
+        const session = privateClient.wrapQuery(
+            null,
+            "stream-agent-routing",
+            {},
+        );
+
+        for await (const _chunk of session.stream("Review the implementation", {
+            agent: "reviewer",
+        })) {
+            // Consume stream to trigger query invocation.
+        }
+
+        expect(queryCalls).toHaveLength(1);
+        const call = queryCalls[0]!;
+        expect(call.prompt).toBe("Review the implementation");
+        expect(call.options.agent).toBe("reviewer");
+        expect(call.prompt).not.toContain("Invoke the \"reviewer\" sub-agent");
+
+        await session.destroy();
+    });
+});
diff --git a/src/sdk/clients/claude.subagent-loading-lag.test.ts b/src/sdk/clients/claude.subagent-loading-lag.test.ts
new file mode 100644
index 0000000000..5644524ca1
--- /dev/null
+++ b/src/sdk/clients/claude.subagent-loading-lag.test.ts
@@ -0,0 +1,39 @@
+import { describe, expect, test } from "bun:test";
+
+import { ClaudeAgentClient } from "./claude.ts";
+
+describe("ClaudeAgentClient Ralph sub-agent loading lag reproduction", () => {
+  test("loads configured agents for every sub-agent session created by a Ralph-style run", async () => {
+    class RalphLagReproClaudeClient extends ClaudeAgentClient {
+      public loadCalls = 0;
+
+      protected override async loadConfiguredAgents(_projectRoot: string) {
+        this.loadCalls += 1;
+        await new Promise<void>((resolve) => setTimeout(resolve, 25));
+        return [];
+      }
+    }
+
+    const client = new RalphLagReproClaudeClient();
+    (
+      client as unknown as {
+        isRunning: boolean;
+      }
+    ).isRunning = true;
+
+    const startedAt = Date.now();
+    const plannerSession = await client.createSession({ sessionId: "ralph-planner" });
+    const workerSessionA = await client.createSession({ sessionId: "ralph-worker-a" });
+    const workerSessionB = await client.createSession({ sessionId: "ralph-worker-b" });
+    const reviewerSession = await client.createSession({ sessionId: "ralph-reviewer" });
+    const elapsedMs = Date.now() - startedAt;
+
+    await plannerSession.destroy();
+    await workerSessionA.destroy();
+    await workerSessionB.destroy();
+    await reviewerSession.destroy();
+
+    expect(client.loadCalls).toBe(4);
+    expect(elapsedMs).toBeGreaterThanOrEqual(80);
+  });
+});
diff --git a/src/sdk/clients/claude.test.ts b/src/sdk/clients/claude.test.ts
index 3c5118613c..31cd751189 100644
--- a/src/sdk/clients/claude.test.ts
+++ b/src/sdk/clients/claude.test.ts
@@ -207,6 +207,41 @@ describe("ClaudeAgentClient observability and parity", () => {
     expect(integrity.unmatchedSubagentCompletes).toBe(1);
   });
 
+  test("does not bind session.error handlers to Stop hooks", () => {
+    const client = new ClaudeAgentClient();
+    const seenErrors: string[] = [];
+
+    const unsubscribe = client.on("session.error", (event) => {
+      const data = event.data as { error?: Error | string };
+      const errorValue = data.error;
+      seenErrors.push(
+        errorValue instanceof Error ? errorValue.message : String(errorValue),
+      );
+    });
+
+    try {
+      const privateClient = client as unknown as {
+        registeredHooks: Record<string, Array<unknown> | undefined>;
+        emitEvent: (
+          eventType: "session.error",
+          sessionId: string,
+          data: Record<string, unknown>,
+        ) => void;
+      };
+
+      expect(privateClient.registeredHooks.Stop).toBeUndefined();
+
+      privateClient.emitEvent("session.error", "session-1", {
+        error: "Maximum turns exceeded",
+        code: "MAX_TURNS",
+      });
+
+      expect(seenErrors).toEqual(["Maximum turns exceeded"]);
+    } finally {
+      unsubscribe();
+    }
+  });
+
   test("maps hook sdk session IDs to wrapped session IDs for tool and subagent events", async () => {
     const client = new ClaudeAgentClient();
     const seenToolSessionIds: string[] = [];
@@ -292,6 +327,436 @@ describe("ClaudeAgentClient observability and parity", () => {
     }
   });
 
+  test("maps parent_tool_call_id to parentAgentId for tool hooks", async () => {
+    const client = new ClaudeAgentClient();
+    const seenParentAgentIds: Array<string | undefined> = [];
+    const seenParentToolIds: Array<string | undefined> = [];
+
+    const unsubTool = client.on("tool.start", (event) => {
+      const data = event.data as {
+        parentAgentId?: string;
+        parentToolUseId?: string;
+      };
+      seenParentAgentIds.push(data.parentAgentId);
+      seenParentToolIds.push(data.parentToolUseId);
+    });
+    const unsubSubagent = client.on("subagent.start", () => {});
+
+    try {
+      const privateClient = client as unknown as {
+        registeredHooks: Record<
+          string,
+          Array<
+            (
+              input: Record<string, unknown>,
+              toolUseID: string | undefined,
+              options: { signal: AbortSignal },
+            ) => Promise<{ continue: boolean }>
+          >
+        >;
+        wrapQuery: (
+          queryInstance: null,
+          sessionId: string,
+          config: Record<string, unknown>,
+        ) => { destroy: () => Promise<void> };
+      };
+
+      const wrappedSession = privateClient.wrapQuery(null, "wrapped-session-id", {});
+      const subagentStartHook = privateClient.registeredHooks.SubagentStart?.[0];
+      const preToolUseHook = privateClient.registeredHooks.PreToolUse?.[0];
+      expect(subagentStartHook).toBeDefined();
+      expect(preToolUseHook).toBeDefined();
+
+      await subagentStartHook?.(
+        {
+          session_id: "sdk-main-session",
+          agent_id: "agent-hook-1",
+          tool_use_id: "subagent-hook-correlation-1",
+          parent_tool_call_id: "parent-dispatch-call-1",
+        },
+        undefined,
+        { signal: new AbortController().signal },
+      );
+
+      await preToolUseHook?.(
+        {
+          session_id: "sdk-main-session",
+          tool_name: "WebSearch",
+          tool_input: { query: "parallel tool routing" },
+          parent_tool_call_id: "parent-dispatch-call-1",
+        },
+        "inner-tool-call-1",
+        { signal: new AbortController().signal },
+      );
+
+      expect(seenParentToolIds).toContain("parent-dispatch-call-1");
+      expect(seenParentAgentIds).toContain("agent-hook-1");
+
+      await wrappedSession.destroy();
+    } finally {
+      unsubTool();
+      unsubSubagent();
+    }
+  });
+
+  test("maps child-session tool hooks to subagents when SubagentStart omits tool use IDs", async () => {
+    const client = new ClaudeAgentClient();
+    const seenParentAgentIds: Array<string | undefined> = [];
+
+    const unsubTool = client.on("tool.start", (event) => {
+      const data = event.data as { parentAgentId?: string };
+      seenParentAgentIds.push(data.parentAgentId);
+    });
+    const unsubSubagent = client.on("subagent.start", () => {});
+
+    try {
+      const privateClient = client as unknown as {
+        registeredHooks: Record<
+          string,
+          Array<
+            (
+              input: Record<string, unknown>,
+              toolUseID: string | undefined,
+              options: { signal: AbortSignal },
+            ) => Promise<{ continue: boolean }>
+          >
+        >;
+        wrapQuery: (
+          queryInstance: null,
+          sessionId: string,
+          config: Record<string, unknown>,
+        ) => { destroy: () => Promise<void> };
+      };
+
+      const wrappedSession = privateClient.wrapQuery(null, "wrapped-session-id", {});
+      const subagentStartHook = privateClient.registeredHooks.SubagentStart?.[0];
+      const preToolUseHook = privateClient.registeredHooks.PreToolUse?.[0];
+      expect(subagentStartHook).toBeDefined();
+      expect(preToolUseHook).toBeDefined();
+
+      // SubagentStart payload has no tool_use_id. We still need to queue this
+      // subagent for later child-session correlation.
+      await subagentStartHook?.(
+        {
+          session_id: "sdk-main-session",
+          agent_id: "agent-child-1",
+          agent_type: "researcher",
+        },
+        undefined,
+        { signal: new AbortController().signal },
+      );
+
+      await preToolUseHook?.(
+        {
+          session_id: "sdk-child-session-1",
+          tool_name: "WebSearch",
+          tool_input: { query: "bm25 fundamentals" },
+          tool_use_id: "child-tool-1",
+        },
+        undefined,
+        { signal: new AbortController().signal },
+      );
+
+      expect(seenParentAgentIds).toContain("agent-child-1");
+
+      await wrappedSession.destroy();
+    } finally {
+      unsubTool();
+      unsubSubagent();
+    }
+  });
+
+  test("binds concurrent hook session IDs deterministically via pending queue", async () => {
+    const client = new ClaudeAgentClient();
+
+    const privateClient = client as unknown as {
+      wrapQuery: (
+        queryInstance: null,
+        sessionId: string,
+        config: Record<string, unknown>,
+      ) => { destroy: () => Promise<void> };
+      pendingHookSessionBindings: string[];
+      resolveHookSessionId: (sdkSessionId: string) => string;
+      sessions: Map<string, { sdkSessionId: string | null }>;
+    };
+
+    const sessionA = privateClient.wrapQuery(null, "wrapped-a", {});
+    const sessionB = privateClient.wrapQuery(null, "wrapped-b", {});
+    const stateA = privateClient.sessions.get("wrapped-a") as { query?: { close?: () => void } } | undefined;
+    const stateB = privateClient.sessions.get("wrapped-b") as { query?: { close?: () => void } } | undefined;
+    if (stateA) stateA.query = { close: () => {} };
+    if (stateB) stateB.query = { close: () => {} };
+    privateClient.pendingHookSessionBindings.push("wrapped-a", "wrapped-b");
+
+    try {
+      const mappedA = privateClient.resolveHookSessionId("sdk-a");
+      const mappedB = privateClient.resolveHookSessionId("sdk-b");
+
+      expect(mappedA).toBe("wrapped-a");
+      expect(mappedB).toBe("wrapped-b");
+      expect(privateClient.sessions.get("wrapped-a")?.sdkSessionId).toBe("sdk-a");
+      expect(privateClient.sessions.get("wrapped-b")?.sdkSessionId).toBe("sdk-b");
+    } finally {
+      await sessionA.destroy();
+      await sessionB.destroy();
+    }
+  });
+
+  test("uses hook payload fallback for subagent terminal signals when session_id/toolUseID arg are missing", async () => {
+    const client = new ClaudeAgentClient();
+    const seenSessionIds: string[] = [];
+    const seenSubagentIds: string[] = [];
+    const seenToolUseIds: Array<string | undefined> = [];
+
+    const unsubStart = client.on("subagent.start", () => {});
+    const unsubComplete = client.on("subagent.complete", (event) => {
+      const data = event.data as { subagentId?: string; toolUseID?: string };
+      seenSessionIds.push(event.sessionId);
+      seenSubagentIds.push(data.subagentId ?? "");
+      seenToolUseIds.push(data.toolUseID);
+    });
+
+    try {
+      const privateClient = client as unknown as {
+        wrapQuery: (
+          queryInstance: null,
+          sessionId: string,
+          config: Record<string, unknown>,
+        ) => { destroy: () => Promise<void> };
+        registeredHooks: Record<
+          string,
+          Array<
+            (
+              input: Record<string, unknown>,
+              toolUseID: string | undefined,
+              options: { signal: AbortSignal },
+            ) => Promise<{ continue: boolean }>
+          >
+        >;
+        sessions: Map<string, { query?: { close?: () => void } }>;
+      };
+
+      const wrappedSession = privateClient.wrapQuery(null, "wrapped-session-id", {});
+      const wrappedState = privateClient.sessions.get("wrapped-session-id");
+      if (wrappedState) {
+        wrappedState.query = { close: () => {} };
+      }
+
+      const subagentStartHook = privateClient.registeredHooks.SubagentStart?.[0];
+      const subagentStopHook = privateClient.registeredHooks.SubagentStop?.[0];
+      expect(subagentStartHook).toBeDefined();
+      expect(subagentStopHook).toBeDefined();
+
+      await subagentStartHook?.(
+        {
+          agent_id: "agent-42",
+          tool_use_id: "tool-use-42",
+        },
+        undefined,
+        { signal: new AbortController().signal },
+      );
+
+      await subagentStopHook?.(
+        {
+          tool_use_id: "tool-use-42",
+        },
+        undefined,
+        { signal: new AbortController().signal },
+      );
+
+      expect(seenSessionIds).toEqual(["wrapped-session-id"]);
+      expect(seenSubagentIds).toEqual(["agent-42"]);
+      expect(seenToolUseIds).toEqual(["tool-use-42"]);
+
+      await wrappedSession.destroy();
+    } finally {
+      unsubStart();
+      unsubComplete();
+    }
+  });
+
+  test("routes subagent terminal signals by tool_use_id when session_id is omitted across multiple sessions", async () => {
+    const client = new ClaudeAgentClient();
+    const seenSessionIds: string[] = [];
+    const seenSubagentIds: string[] = [];
+
+    const unsubStart = client.on("subagent.start", () => {});
+    const unsubComplete = client.on("subagent.complete", (event) => {
+      const data = event.data as { subagentId?: string };
+      seenSessionIds.push(event.sessionId);
+      seenSubagentIds.push(data.subagentId ?? "");
+    });
+
+    try {
+      const privateClient = client as unknown as {
+        wrapQuery: (
+          queryInstance: null,
+          sessionId: string,
+          config: Record<string, unknown>,
+        ) => { destroy: () => Promise<void> };
+        registeredHooks: Record<
+          string,
+          Array<
+            (
+              input: Record<string, unknown>,
+              toolUseID: string | undefined,
+              options: { signal: AbortSignal },
+            ) => Promise<{ continue: boolean }>
+          >
+        >;
+        sessions: Map<
+          string,
+          {
+            query?: { close?: () => void };
+            sdkSessionId?: string | null;
+          }
+        >;
+      };
+
+      const wrappedMain = privateClient.wrapQuery(null, "wrapped-main", {});
+      const wrappedWorker = privateClient.wrapQuery(null, "wrapped-worker", {});
+      const mainState = privateClient.sessions.get("wrapped-main");
+      const workerState = privateClient.sessions.get("wrapped-worker");
+      if (mainState) {
+        mainState.query = { close: () => {} };
+        mainState.sdkSessionId = "sdk-main";
+      }
+      if (workerState) {
+        workerState.query = { close: () => {} };
+        workerState.sdkSessionId = "sdk-worker";
+      }
+
+      const subagentStartHook = privateClient.registeredHooks.SubagentStart?.[0];
+      const subagentStopHook = privateClient.registeredHooks.SubagentStop?.[0];
+      expect(subagentStartHook).toBeDefined();
+      expect(subagentStopHook).toBeDefined();
+
+      await subagentStartHook?.(
+        {
+          session_id: "sdk-worker",
+          agent_id: "agent-77",
+          tool_use_id: "tool-use-77",
+        },
+        undefined,
+        { signal: new AbortController().signal },
+      );
+
+      await subagentStopHook?.(
+        {
+          tool_use_id: "tool-use-77",
+        },
+        undefined,
+        { signal: new AbortController().signal },
+      );
+
+      expect(seenSessionIds).toEqual(["wrapped-worker"]);
+      expect(seenSubagentIds).toEqual(["agent-77"]);
+
+      await wrappedMain.destroy();
+      await wrappedWorker.destroy();
+    } finally {
+      unsubStart();
+      unsubComplete();
+    }
+  });
+
+  test("maps task_notification terminal statuses to subagent.complete outcomes", () => {
+    const client = new ClaudeAgentClient();
+    const seenCompletions: Array<{
+      sessionId: string;
+      subagentId?: string;
+      success?: boolean;
+      result?: string;
+    }> = [];
+
+    const unsubscribe = client.on("subagent.complete", (event) => {
+      const data = event.data as {
+        subagentId?: string;
+        success?: boolean;
+        result?: string;
+      };
+      seenCompletions.push({
+        sessionId: event.sessionId,
+        subagentId: data.subagentId,
+        success: data.success,
+        result: data.result,
+      });
+    });
+
+    try {
+      const privateClient = client as unknown as {
+        processMessage: (
+          sdkMessage: Record<string, unknown>,
+          sessionId: string,
+          state: {
+            sdkSessionId: string | null;
+            inputTokens: number;
+            outputTokens: number;
+            hasEmittedStreamingUsage: boolean;
+          },
+        ) => void;
+        toolUseIdToAgentId: Map<string, string>;
+        toolUseIdToSessionId: Map<string, string>;
+      };
+
+      const state = {
+        sdkSessionId: "sdk-session",
+        inputTokens: 0,
+        outputTokens: 0,
+        hasEmittedStreamingUsage: false,
+      };
+
+      privateClient.toolUseIdToAgentId.set("tool-use-success", "agent-success");
+      privateClient.toolUseIdToSessionId.set("tool-use-success", "wrapped-session");
+      privateClient.processMessage(
+        {
+          type: "system",
+          subtype: "task_notification",
+          tool_use_id: "tool-use-success",
+          status: "completed",
+          summary: "done",
+        },
+        "wrapped-session",
+        state,
+      );
+
+      privateClient.toolUseIdToAgentId.set("tool-use-error", "agent-error");
+      privateClient.toolUseIdToSessionId.set("tool-use-error", "wrapped-session");
+      privateClient.processMessage(
+        {
+          type: "system",
+          subtype: "task_notification",
+          tool_use_id: "tool-use-error",
+          status: "failed",
+          summary: "failed",
+        },
+        "wrapped-session",
+        state,
+      );
+
+      expect(seenCompletions).toEqual([
+        {
+          sessionId: "wrapped-session",
+          subagentId: "agent-success",
+          success: true,
+          result: "done",
+        },
+        {
+          sessionId: "wrapped-session",
+          subagentId: "agent-error",
+          success: false,
+          result: "failed",
+        },
+      ]);
+      expect(privateClient.toolUseIdToAgentId.has("tool-use-success")).toBe(false);
+      expect(privateClient.toolUseIdToSessionId.has("tool-use-success")).toBe(false);
+      expect(privateClient.toolUseIdToAgentId.has("tool-use-error")).toBe(false);
+      expect(privateClient.toolUseIdToSessionId.has("tool-use-error")).toBe(false);
+    } finally {
+      unsubscribe();
+    }
+  });
+
   test("emits stream integrity counters through usage without payload leakage", async () => {
     const client = new ClaudeAgentClient();
     const usageEvents: Array<Record<string, unknown>> = [];
@@ -570,7 +1035,7 @@ describe("ClaudeAgentClient permissions and options", () => {
 });
 
 describe("ClaudeAgentClient resume continuity semantics", () => {
-  test("re-wraps active sessions without losing usage state", async () => {
+  test("re-wraps active sessions without losing usage state and preserves hasEmittedStreamingUsage default", async () => {
     const client = new ClaudeAgentClient();
     (client as unknown as { isRunning: boolean }).isRunning = true;
 
@@ -625,3 +1090,175 @@ describe("ClaudeAgentClient resume continuity semantics", () => {
     await resumed?.destroy();
   });
 });
+
+describe("ClaudeAgentClient streaming usage events", () => {
+  test("message_delta with usage data triggers a usage client event during streaming", () => {
+    const client = new ClaudeAgentClient();
+    const usageEvents: Array<Record<string, unknown>> = [];
+
+    const unsubscribe = client.on("usage", (event) => {
+      usageEvents.push(event.data as Record<string, unknown>);
+    });
+
+    try {
+      const privateClient = client as unknown as {
+        wrapQuery: (
+          queryInstance: null,
+          sessionId: string,
+          config: Record<string, unknown>,
+        ) => { destroy: () => Promise<void> };
+        sessions: Map<string, { hasEmittedStreamingUsage: boolean }>;
+        emitEvent: (
+          eventType: string,
+          sessionId: string,
+          data: Record<string, unknown>,
+        ) => void;
+        detectedModel: string | null;
+      };
+
+      const session = privateClient.wrapQuery(null, "stream-usage-test", {});
+      const state = privateClient.sessions.get("stream-usage-test");
+
+      // Simulate what emitStreamingUsage does (arrow fn inside stream())
+      // We test the state flag and emitEvent directly since the closure is internal
+      expect(state?.hasEmittedStreamingUsage).toBe(false);
+
+      state!.hasEmittedStreamingUsage = true;
+      privateClient.emitEvent("usage", "stream-usage-test", {
+        inputTokens: 0,
+        outputTokens: 150,
+        model: privateClient.detectedModel,
+      });
+
+      const streamingUsage = usageEvents.filter(
+        (e) => typeof e.outputTokens === "number" && e.outputTokens > 0,
+      );
+      expect(streamingUsage).toHaveLength(1);
+      expect(streamingUsage[0]).toMatchObject({
+        inputTokens: 0,
+        outputTokens: 150,
+      });
+      expect(state?.hasEmittedStreamingUsage).toBe(true);
+
+      session.destroy();
+    } finally {
+      unsubscribe();
+    }
+  });
+
+  test("result handler emits inputTokens-only correction when hasEmittedStreamingUsage is true", () => {
+    const client = new ClaudeAgentClient();
+    const usageEvents: Array<Record<string, unknown>> = [];
+
+    const unsubscribe = client.on("usage", (event) => {
+      usageEvents.push(event.data as Record<string, unknown>);
+    });
+
+    try {
+      const privateClient = client as unknown as {
+        wrapQuery: (
+          queryInstance: null,
+          sessionId: string,
+          config: Record<string, unknown>,
+        ) => { destroy: () => Promise<void> };
+        sessions: Map<string, { hasEmittedStreamingUsage: boolean }>;
+        processMessage: (
+          msg: Record<string, unknown>,
+          sessionId: string,
+          state: Record<string, unknown>,
+        ) => Record<string, unknown> | null;
+      };
+
+      const session = privateClient.wrapQuery(null, "result-guard-test", {});
+      const state = privateClient.sessions.get("result-guard-test")!;
+
+      // Simulate streaming path: flag is true
+      state.hasEmittedStreamingUsage = true;
+
+      // Process a result message with usage
+      const resultMsg = {
+        type: "result",
+        subtype: "success",
+        usage: { input_tokens: 500, output_tokens: 200 },
+      };
+      privateClient.processMessage(
+        resultMsg,
+        "result-guard-test",
+        state as unknown as Record<string, unknown>,
+      );
+
+      // Filter to non-marker usage events (exclude runtime selection, integrity, etc.)
+      const tokenUsage = usageEvents.filter(
+        (e) => typeof e.inputTokens === "number",
+      );
+      expect(tokenUsage).toHaveLength(1);
+      // Should emit inputTokens but outputTokens: 0 (not double-counting)
+      expect(tokenUsage[0]).toMatchObject({
+        inputTokens: 500,
+        outputTokens: 0,
+      });
+      // Flag should be reset after processing
+      expect(state.hasEmittedStreamingUsage).toBe(false);
+
+      session.destroy();
+    } finally {
+      unsubscribe();
+    }
+  });
+
+  test("send path (no message_delta) still emits full usage from result", () => {
+    const client = new ClaudeAgentClient();
+    const usageEvents: Array<Record<string, unknown>> = [];
+
+    const unsubscribe = client.on("usage", (event) => {
+      usageEvents.push(event.data as Record<string, unknown>);
+    });
+
+    try {
+      const privateClient = client as unknown as {
+        wrapQuery: (
+          queryInstance: null,
+          sessionId: string,
+          config: Record<string, unknown>,
+        ) => { destroy: () => Promise<void> };
+        sessions: Map<string, { hasEmittedStreamingUsage: boolean }>;
+        processMessage: (
+          msg: Record<string, unknown>,
+          sessionId: string,
+          state: Record<string, unknown>,
+        ) => Record<string, unknown> | null;
+      };
+
+      const session = privateClient.wrapQuery(null, "send-usage-test", {});
+      const state = privateClient.sessions.get("send-usage-test")!;
+
+      // Send path: flag remains false (no streaming deltas)
+      expect(state.hasEmittedStreamingUsage).toBe(false);
+
+      const resultMsg = {
+        type: "result",
+        subtype: "success",
+        usage: { input_tokens: 1000, output_tokens: 300 },
+      };
+      privateClient.processMessage(
+        resultMsg,
+        "send-usage-test",
+        state as unknown as Record<string, unknown>,
+      );
+
+      const tokenUsage = usageEvents.filter(
+        (e) => typeof e.inputTokens === "number",
+      );
+      expect(tokenUsage).toHaveLength(1);
+      // Full usage emitted since no streaming usage was sent
+      expect(tokenUsage[0]).toMatchObject({
+        inputTokens: 1000,
+        outputTokens: 300,
+      });
+
+      session.destroy();
+    } finally {
+      unsubscribe();
+    }
+  });
+});
diff --git a/src/sdk/clients/claude.ts b/src/sdk/clients/claude.ts
index 9f57310d6a..4ad800a1cc 100644
--- a/src/sdk/clients/claude.ts
+++ b/src/sdk/clients/claude.ts
@@ -37,6 +37,7 @@ import {
     type HookJSONOutput,
     type McpSdkServerConfigWithInstance,
     type McpServerStatus,
+    type ThinkingConfig,
 } from "@anthropic-ai/claude-agent-sdk";
 import type {
     CodingAgentClient,
@@ -96,6 +97,8 @@ interface ClaudeSessionState {
     contextWindow: number | null;
     /** System tools baseline tokens captured from cache tokens */
     systemToolsBaseline: number | null;
+    /** Whether per-turn usage events were emitted from message_delta during streaming */
+    hasEmittedStreamingUsage: boolean;
 }
 
 interface StreamIntegrityCounters {
@@ -126,7 +129,6 @@ function mapEventTypeToHookEvent(eventType: EventType): HookEvent | null {
     const mapping: Partial<Record<EventType, HookEvent>> = {
         "session.start": "SessionStart",
         "session.idle": "SessionEnd",
-        "session.error": "Stop",
         "tool.start": "PreToolUse",
         "tool.complete": "PostToolUse",
         "subagent.start": "SubagentStart",
@@ -158,7 +160,11 @@ export function extractMessageContent(message: SDKAssistantMessage): {
     let thinkingContent: string | null = null;
     let thinkingSourceKey: string | undefined;
 
-    for (let blockIndex = 0; blockIndex < betaMessage.content.length; blockIndex++) {
+    for (
+        let blockIndex = 0;
+        blockIndex < betaMessage.content.length;
+        blockIndex++
+    ) {
         const block = betaMessage.content[blockIndex]!;
         if (block.type === "tool_use") {
             // Return immediately — tool_use has highest priority.
@@ -197,7 +203,9 @@ export function extractMessageContent(message: SDKAssistantMessage): {
     return { type: "text", content: "" };
 }
 
-function getClaudeContentBlockIndex(event: Record<string, unknown>): number | null {
+function getClaudeContentBlockIndex(
+    event: Record<string, unknown>,
+): number | null {
     const directIndex = event.index;
     if (typeof directIndex === "number") {
         return directIndex;
@@ -281,11 +289,13 @@ export class ClaudeAgentClient implements CodingAgentClient {
         "MultiEdit",
         "TodoRead",
         "TodoWrite",
-        "WebFetch",
-        "WebSearch",
         "NotebookEdit",
         "NotebookRead",
     ] as const;
+    private static readonly SUPPORTS_ADAPTIVE_THINKING = new Set([
+        "opus",
+        "sonnet",
+    ]);
     private static readonly SUPPORTED_REASONING_EFFORTS = new Set([
         "low",
         "medium",
@@ -317,6 +327,42 @@ export class ClaudeAgentClient implements CodingAgentClient {
     };
     private pendingToolBySession = new Map<string, number>();
     private pendingSubagentBySession = new Map<string, number>();
+    /**
+     * FIFO of wrapped session IDs awaiting first hook-session binding.
+     * Enables deterministic SDK->wrapped session mapping when multiple
+     * sessions are opened concurrently (parallel sub-agents).
+     */
+    private pendingHookSessionBindings: string[] = [];
+
+    /**
+     * Maps tool_use_id (from SubagentStart hook) → agent_id.
+     * Used to correlate SDKTaskProgressMessage/SDKTaskNotificationMessage
+     * with the correct sub-agent for emitting subagent.update events.
+     */
+    private toolUseIdToAgentId = new Map<string, string>();
+    /** Maps tool_use_id → wrapped session ID for terminal hook routing. */
+    private toolUseIdToSessionId = new Map<string, string>();
+    /** Maps tool_use_id → task description from task_started for subagent labels. */
+    private taskDescriptionByToolUseId = new Map<string, string>();
+
+    /**
+     * Maps sub-agent SDK session ID → agent_id.
+     * Populated reactively: when a tool hook fires with an unknown session_id
+     * that differs from the main session's sdkSessionId, it gets bound to the
+     * first unmapped sub-agent.
+     */
+    private subagentSdkSessionIdToAgentId = new Map<string, string>();
+    /**
+     * Agent IDs of sub-agents that have started but haven't yet had their
+     * SDK session ID discovered via a tool hook.
+     */
+    private unmappedSubagentIds: string[] = [];
+
+    protected async loadConfiguredAgents(
+        projectRoot: string,
+    ): Promise<Awaited<ReturnType<typeof loadCopilotAgents>>> {
+        return loadCopilotAgents(projectRoot);
+    }
 
     /**
      * Register native SDK hooks for event handling.
@@ -351,16 +397,28 @@ export class ClaudeAgentClient implements CodingAgentClient {
             : "high";
     }
 
+    private getThinkingBudget(
+        model: string | undefined,
+        maxThinkingTokens: number = 16000,
+    ): ThinkingConfig | undefined {
+        return model &&
+            ClaudeAgentClient.SUPPORTS_ADAPTIVE_THINKING.has(
+                normalizeClaudeModelLabel(model),
+            )
+            ? { type: "adaptive" }
+            : {
+                  type: "enabled",
+                  budgetTokens: maxThinkingTokens,
+              };
+    }
+
     private async handleAskUserQuestion(
         sessionId: string,
         toolInput: Record<string, unknown>,
-    ): Promise<
-        | {
-              behavior: "allow";
-              updatedInput: Record<string, unknown>;
-          }
-        | null
-    > {
+    ): Promise<{
+        behavior: "allow";
+        updatedInput: Record<string, unknown>;
+    } | null> {
         const input = toolInput as AskUserQuestionInput;
 
         if (!input.questions || input.questions.length === 0) {
@@ -370,15 +428,15 @@ export class ClaudeAgentClient implements CodingAgentClient {
         const answers: Record<string, string> = {};
 
         for (const q of input.questions) {
-            const responsePromise = new Promise<string | string[]>((resolve) => {
-                this.emitEvent("permission.requested", sessionId, {
-                    requestId: `ask_${Date.now()}`,
-                    toolName: "AskUserQuestion",
-                    toolInput: q,
-                    question: q.question,
-                    header: q.header,
-                    options:
-                        q.options?.map((opt) => ({
+            const responsePromise = new Promise<string | string[]>(
+                (resolve) => {
+                    this.emitEvent("permission.requested", sessionId, {
+                        requestId: `ask_${Date.now()}`,
+                        toolName: "AskUserQuestion",
+                        toolInput: q,
+                        question: q.question,
+                        header: q.header,
+                        options: q.options?.map((opt) => ({
                             label: opt.label,
                             value: opt.label,
                             description: opt.description,
@@ -394,10 +452,11 @@ export class ClaudeAgentClient implements CodingAgentClient {
                                 description: "Deny",
                             },
                         ],
-                    multiSelect: q.multiSelect ?? false,
-                    respond: resolve,
-                });
-            });
+                        multiSelect: q.multiSelect ?? false,
+                        respond: resolve,
+                    });
+                },
+            );
 
             const response = await responsePromise;
             answers[q.question] = Array.isArray(response)
@@ -417,7 +476,10 @@ export class ClaudeAgentClient implements CodingAgentClient {
         toolInput: Record<string, unknown>,
     ): Promise<{ behavior: "allow"; updatedInput: Record<string, unknown> }> {
         if (toolName === "AskUserQuestion") {
-            const resolved = await this.handleAskUserQuestion(sessionId, toolInput);
+            const resolved = await this.handleAskUserQuestion(
+                sessionId,
+                toolInput,
+            );
             if (resolved) {
                 return resolved;
             }
@@ -481,13 +543,10 @@ export class ClaudeAgentClient implements CodingAgentClient {
             maxTurns: config.maxTurns,
             maxBudgetUsd: config.maxBudgetUsd,
             effort: this.getReasoningEffort(config.reasoningEffort),
-            thinking:
-                config.model == "opus"
-                    ? { type: "adaptive" }
-                    : {
-                          type: "enabled",
-                          budgetTokens: config.maxThinkingTokens ?? 16000,
-                      },
+            thinking: this.getThinkingBudget(
+                config.model,
+                config.maxThinkingTokens,
+            ),
             hooks: this.buildNativeHooks(),
             includePartialMessages: true,
             // Use Claude Code's built-in system prompt, appending custom instructions if provided
@@ -510,7 +569,11 @@ export class ClaudeAgentClient implements CodingAgentClient {
             toolInput: Record<string, unknown>,
             _options: { signal: AbortSignal },
         ) => {
-            return this.resolveToolPermission(sessionId ?? "", toolName, toolInput);
+            return this.resolveToolPermission(
+                sessionId ?? "",
+                toolName,
+                toolInput,
+            );
         };
 
         const mcpServers = this.buildMcpServers(config);
@@ -618,6 +681,7 @@ export class ClaudeAgentClient implements CodingAgentClient {
             contextWindow: persisted?.contextWindow ?? this.probeContextWindow,
             systemToolsBaseline:
                 persisted?.systemToolsBaseline ?? this.probeSystemToolsBaseline,
+            hasEmittedStreamingUsage: false,
         };
 
         this.sessions.set(sessionId, state);
@@ -648,40 +712,56 @@ export class ClaudeAgentClient implements CodingAgentClient {
                 let lastAssistantMessage: AgentMessage | null = null;
                 let sawTerminalEvent = false;
 
-                for await (const sdkMessage of newQuery) {
-                    this.processMessage(sdkMessage, sessionId, state);
-                    if (sdkMessage.type === "result") {
-                        sawTerminalEvent = true;
-                    }
+                try {
+                    for await (const sdkMessage of newQuery) {
+                        this.processMessage(sdkMessage, sessionId, state);
+                        if (sdkMessage.type === "result") {
+                            sawTerminalEvent = true;
+                        }
+
+                        if (sdkMessage.type === "assistant") {
+                            // Skip sub-agent assistant messages — only
+                            // the main agent's response should be returned.
+                            const parentToolUseId = (
+                                sdkMessage as Record<string, unknown>
+                            ).parent_tool_use_id;
+                            if (parentToolUseId) {
+                                continue;
+                            }
 
-                    if (sdkMessage.type === "assistant") {
-                        const { type, content, thinkingSourceKey } =
-                            extractMessageContent(sdkMessage);
-                        lastAssistantMessage = {
-                            type,
-                            content,
-                            role: "assistant",
-                            metadata: {
-                                tokenUsage: {
-                                    inputTokens:
-                                        sdkMessage.message.usage
-                                            ?.input_tokens ?? 0,
-                                    outputTokens:
-                                        sdkMessage.message.usage
-                                            ?.output_tokens ?? 0,
+                            const { type, content, thinkingSourceKey } =
+                                extractMessageContent(sdkMessage);
+                            lastAssistantMessage = {
+                                type,
+                                content,
+                                role: "assistant",
+                                metadata: {
+                                    tokenUsage: {
+                                        inputTokens:
+                                            sdkMessage.message.usage
+                                                ?.input_tokens ?? 0,
+                                        outputTokens:
+                                            sdkMessage.message.usage
+                                                ?.output_tokens ?? 0,
+                                    },
+                                    model: sdkMessage.message.model,
+                                    stopReason:
+                                        sdkMessage.message.stop_reason ??
+                                        undefined,
+                                    ...(type === "thinking"
+                                        ? {
+                                              provider: "claude",
+                                              thinkingSourceKey,
+                                          }
+                                        : {}),
                                 },
-                                model: sdkMessage.message.model,
-                                stopReason:
-                                    sdkMessage.message.stop_reason ?? undefined,
-                                ...(type === "thinking"
-                                    ? {
-                                          provider: "claude",
-                                          thinkingSourceKey,
-                                      }
-                                    : {}),
-                            },
-                        };
+                            };
+                        }
                     }
+                } catch (error) {
+                    throw error instanceof Error
+                        ? error
+                        : new Error(String(error));
                 }
 
                 if (!sawTerminalEvent) {
@@ -700,7 +780,10 @@ export class ClaudeAgentClient implements CodingAgentClient {
                 );
             },
 
-            stream: (message: string, _options?: { agent?: string }): AsyncIterable<AgentMessage> => {
+            stream: (
+                message: string,
+                optionsArg?: { agent?: string },
+            ): AsyncIterable<AgentMessage> => {
                 // Capture references for the async generator
                 const buildOptions = () =>
                     this.buildSdkOptions(config, sessionId);
@@ -716,14 +799,24 @@ export class ClaudeAgentClient implements CodingAgentClient {
                 };
                 // Capture SDK session ID for resume
                 const getSdkSessionId = () => state.sdkSessionId;
+                const requestedAgent = optionsArg?.agent?.trim();
+                const emitStreamingUsage = (outputTokens: number) => {
+                    state.hasEmittedStreamingUsage = true;
+                    this.emitEvent("usage", sessionId, {
+                        inputTokens: 0,
+                        outputTokens,
+                        model: this.detectedModel,
+                    });
+                };
 
                 return {
                     [Symbol.asyncIterator]: async function* () {
                         if (state.isClosed) {
                             throw new Error("Session is closed");
                         }
+                        state.hasEmittedStreamingUsage = false;
                         emitRuntimeSelection();
-                        const options = {
+                        const options: Options = {
                             ...buildOptions(),
                             includePartialMessages: true,
                         };
@@ -731,6 +824,9 @@ export class ClaudeAgentClient implements CodingAgentClient {
                         if (sdkSessionId) {
                             options.resume = sdkSessionId;
                         }
+                        if (requestedAgent) {
+                            options.agent = requestedAgent;
+                        }
 
                         const streamSource = query({
                             prompt: message,
@@ -750,197 +846,275 @@ export class ClaudeAgentClient implements CodingAgentClient {
                         let outputTokens = 0;
                         let sawTerminalEvent = false;
 
-                        for await (const sdkMessage of streamSource) {
-                            processMsg(sdkMessage);
-                            if (sdkMessage.type === "result") {
-                                sawTerminalEvent = true;
-                            }
-
-                            if (sdkMessage.type === "stream_event") {
-                                const event = sdkMessage.event;
-
-                                // Track thinking block boundaries
-                                if (event.type === "content_block_start") {
-                                    const blockIndex = getClaudeContentBlockIndex(
-                                        event as Record<string, unknown>,
-                                    );
-                                    const blockType = (
-                                        event as Record<string, unknown>
-                                    ).content_block
-                                        ? (
-                                              (event as Record<string, unknown>)
-                                                  .content_block as Record<
-                                                  string,
-                                                  unknown
-                                              >
-                                          ).type
-                                        : undefined;
-                                    currentBlockIsThinking =
-                                        blockType === "thinking";
-                                    if (currentBlockIsThinking) {
-                                        thinkingStartMs = Date.now();
-                                        activeThinkingSourceKey =
-                                            blockIndex !== null
-                                                ? String(blockIndex)
-                                                : null;
-                                    }
+                        try {
+                            for await (const sdkMessage of streamSource) {
+                                processMsg(sdkMessage);
+                                if (sdkMessage.type === "result") {
+                                    sawTerminalEvent = true;
                                 }
-                                if (
-                                    event.type === "content_block_stop" &&
-                                    currentBlockIsThinking
-                                ) {
-                                    if (activeThinkingSourceKey === null) {
+
+                                if (sdkMessage.type === "stream_event") {
+                                    const event = sdkMessage.event;
+                                    const eventRecord = event as Record<
+                                        string,
+                                        unknown
+                                    >;
+                                    const parentToolUseId =
+                                        typeof eventRecord.parent_tool_use_id ===
+                                        "string"
+                                            ? eventRecord.parent_tool_use_id
+                                            : typeof eventRecord.parentToolUseId ===
+                                                "string"
+                                              ? eventRecord.parentToolUseId
+                                              : undefined;
+
+                                    // Track thinking block boundaries
+                                    if (event.type === "content_block_start") {
                                         const blockIndex =
                                             getClaudeContentBlockIndex(
-                                                event as Record<string, unknown>,
+                                                event as Record<
+                                                    string,
+                                                    unknown
+                                                >,
                                             );
-                                        if (blockIndex !== null) {
+                                        const blockType = (
+                                            event as Record<string, unknown>
+                                        ).content_block
+                                            ? (
+                                                  (
+                                                      event as Record<
+                                                          string,
+                                                          unknown
+                                                      >
+                                                  ).content_block as Record<
+                                                      string,
+                                                      unknown
+                                                  >
+                                              ).type
+                                            : undefined;
+                                        currentBlockIsThinking =
+                                            blockType === "thinking";
+                                        if (currentBlockIsThinking) {
+                                            thinkingStartMs = Date.now();
                                             activeThinkingSourceKey =
-                                                String(blockIndex);
+                                                blockIndex !== null
+                                                    ? String(blockIndex)
+                                                    : null;
                                         }
                                     }
-                                    if (thinkingStartMs !== null) {
-                                        thinkingDurationMs +=
-                                            Date.now() - thinkingStartMs;
-                                        thinkingStartMs = null;
-                                    }
-                                    currentBlockIsThinking = false;
-                                    yield {
-                                        type: "thinking" as MessageContentType,
-                                        content: "",
-                                        role: "assistant",
-                                        metadata: {
-                                            provider: "claude",
-                                            thinkingSourceKey:
-                                                activeThinkingSourceKey ??
-                                                undefined,
-                                            streamingStats: {
-                                                thinkingMs: thinkingDurationMs,
-                                                outputTokens,
-                                            },
-                                        },
-                                    };
-                                    activeThinkingSourceKey = null;
-                                }
-
-                                // Track output tokens from message_delta usage
-                                if (event.type === "message_delta") {
-                                    const usage = (
-                                        event as Record<string, unknown>
-                                    ).usage as
-                                        | { output_tokens?: number }
-                                        | undefined;
-                                    if (usage?.output_tokens) {
-                                        outputTokens += usage.output_tokens;
-                                    }
-                                }
-
-                                if (event.type === "content_block_delta") {
-                                    if (event.delta.type === "text_delta") {
-                                        hasYieldedDeltas = true;
-                                        yield {
-                                            type: "text",
-                                            content: event.delta.text,
-                                            role: "assistant",
-                                        };
-                                    } else if (
-                                        event.delta.type === "thinking_delta"
+                                    if (
+                                        event.type === "content_block_stop" &&
+                                        currentBlockIsThinking
                                     ) {
-                                        hasYieldedDeltas = true;
-                                        const blockIndex =
-                                            getClaudeContentBlockIndex(
-                                                event as Record<string, unknown>,
-                                            );
-                                        const resolvedThinkingSourceKey: string | null =
-                                            blockIndex !== null
-                                                ? String(blockIndex)
-                                                : activeThinkingSourceKey;
-                                        if (resolvedThinkingSourceKey !== null) {
-                                            activeThinkingSourceKey =
-                                                resolvedThinkingSourceKey;
+                                        if (activeThinkingSourceKey === null) {
+                                            const blockIndex =
+                                                getClaudeContentBlockIndex(
+                                                    event as Record<
+                                                        string,
+                                                        unknown
+                                                    >,
+                                                );
+                                            if (blockIndex !== null) {
+                                                activeThinkingSourceKey =
+                                                    String(blockIndex);
+                                            }
+                                        }
+                                        if (thinkingStartMs !== null) {
+                                            thinkingDurationMs +=
+                                                Date.now() - thinkingStartMs;
+                                            thinkingStartMs = null;
                                         }
-                                        const currentThinkingMs =
-                                            thinkingDurationMs +
-                                            (thinkingStartMs !== null
-                                                ? Date.now() - thinkingStartMs
-                                                : 0);
+                                        currentBlockIsThinking = false;
                                         yield {
                                             type: "thinking" as MessageContentType,
-                                            content: (
-                                                event.delta as Record<
-                                                    string,
-                                                    unknown
-                                                >
-                                            ).thinking as string,
+                                            content: "",
                                             role: "assistant",
                                             metadata: {
                                                 provider: "claude",
                                                 thinkingSourceKey:
-                                                    resolvedThinkingSourceKey ??
+                                                    activeThinkingSourceKey ??
                                                     undefined,
                                                 streamingStats: {
                                                     thinkingMs:
-                                                        currentThinkingMs,
+                                                        thinkingDurationMs,
                                                     outputTokens,
                                                 },
                                             },
                                         };
+                                        activeThinkingSourceKey = null;
                                     }
-                                }
-                            } else if (sdkMessage.type === "assistant") {
-                                const { type, content, thinkingSourceKey } =
-                                    extractMessageContent(sdkMessage);
-
-                                // Always yield tool_use messages so callers can track tool
-                                // invocations (e.g. SubagentGraphBridge counts them for
-                                // the tree view).  Text messages are only yielded when we
-                                // haven't already streamed text deltas to avoid duplication.
-                                if (type === "tool_use") {
-                                    yield {
-                                        type,
-                                        content,
-                                        role: "assistant",
-                                        metadata: {
-                                            toolName:
-                                                typeof content === "object" &&
-                                                content !== null
-                                                    ? ((
-                                                          content as Record<
-                                                              string,
-                                                              unknown
-                                                          >
-                                                      ).name as string)
-                                                    : undefined,
-                                        },
-                                    };
-                                } else if (!hasYieldedDeltas) {
-                                    yield {
-                                        type,
-                                        content,
-                                        role: "assistant",
-                                        metadata: {
-                                            tokenUsage: {
-                                                inputTokens:
-                                                    sdkMessage.message.usage
-                                                        ?.input_tokens ?? 0,
-                                                outputTokens:
-                                                    sdkMessage.message.usage
-                                                        ?.output_tokens ?? 0,
+
+                                    // Track output tokens from message_delta usage
+                                    if (event.type === "message_delta") {
+                                        const usage = (
+                                            event as Record<string, unknown>
+                                        ).usage as
+                                            | { output_tokens?: number }
+                                            | undefined;
+                                        if (usage?.output_tokens) {
+                                            outputTokens += usage.output_tokens;
+                                            // Emit per-API-call token count so the adapter can publish
+                                            // stream.usage for live token display during streaming
+                                            emitStreamingUsage(
+                                                usage.output_tokens,
+                                            );
+                                        }
+                                    }
+
+                                    if (event.type === "content_block_delta") {
+                                        if (event.delta.type === "text_delta") {
+                                            if (!parentToolUseId) {
+                                                hasYieldedDeltas = true;
+                                            }
+                                            yield {
+                                                type: "text",
+                                                content: event.delta.text,
+                                                role: "assistant",
+                                                ...(parentToolUseId
+                                                    ? {
+                                                          metadata: {
+                                                              parentToolCallId:
+                                                                  parentToolUseId,
+                                                          },
+                                                      }
+                                                    : {}),
+                                            };
+                                        } else if (
+                                            event.delta.type ===
+                                            "thinking_delta"
+                                        ) {
+                                            // Sub-agent thinking deltas belong to
+                                            // child contexts and must not pollute
+                                            // the parent stream.
+                                            if (parentToolUseId) {
+                                                continue;
+                                            }
+                                            hasYieldedDeltas = true;
+                                            const blockIndex =
+                                                getClaudeContentBlockIndex(
+                                                    event as Record<
+                                                        string,
+                                                        unknown
+                                                    >,
+                                                );
+                                            const resolvedThinkingSourceKey:
+                                                | string
+                                                | null =
+                                                blockIndex !== null
+                                                    ? String(blockIndex)
+                                                    : activeThinkingSourceKey;
+                                            if (
+                                                resolvedThinkingSourceKey !==
+                                                null
+                                            ) {
+                                                activeThinkingSourceKey =
+                                                    resolvedThinkingSourceKey;
+                                            }
+                                            const currentThinkingMs =
+                                                thinkingDurationMs +
+                                                (thinkingStartMs !== null
+                                                    ? Date.now() -
+                                                      thinkingStartMs
+                                                    : 0);
+                                            yield {
+                                                type: "thinking" as MessageContentType,
+                                                content: (
+                                                    event.delta as Record<
+                                                        string,
+                                                        unknown
+                                                    >
+                                                ).thinking as string,
+                                                role: "assistant",
+                                                metadata: {
+                                                    provider: "claude",
+                                                    thinkingSourceKey:
+                                                        resolvedThinkingSourceKey ??
+                                                        undefined,
+                                                    streamingStats: {
+                                                        thinkingMs:
+                                                            currentThinkingMs,
+                                                        outputTokens,
+                                                    },
+                                                },
+                                            };
+                                        }
+                                    }
+                                } else if (sdkMessage.type === "assistant") {
+                                    // Skip sub-agent assistant messages — they
+                                    // belong to a child agent context and their
+                                    // tool calls are handled by the hook path
+                                    // (PreToolUse/PostToolUse) with proper
+                                    // parentAgentId routing. Yielding them here
+                                    // would leak sub-agent tool_use (and text)
+                                    // into the main chat without parentAgentId.
+                                    const parentToolUseId = (
+                                        sdkMessage as Record<string, unknown>
+                                    ).parent_tool_use_id;
+                                    if (parentToolUseId) {
+                                        continue;
+                                    }
+
+                                    const { type, content, thinkingSourceKey } =
+                                        extractMessageContent(sdkMessage);
+
+                                    // Always yield tool_use messages so callers can track tool
+                                    // invocations (e.g. spawnSubagentParallel counts them for
+                                    // the tree view).  Text messages are only yielded when we
+                                    // haven't already streamed text deltas to avoid duplication.
+                                    if (type === "tool_use") {
+                                        yield {
+                                            type,
+                                            content,
+                                            role: "assistant",
+                                            metadata: {
+                                                toolName:
+                                                    typeof content ===
+                                                        "object" &&
+                                                    content !== null
+                                                        ? ((
+                                                              content as Record<
+                                                                  string,
+                                                                  unknown
+                                                              >
+                                                          ).name as string)
+                                                        : undefined,
                                             },
-                                            model: sdkMessage.message.model,
-                                            stopReason:
-                                                sdkMessage.message
-                                                    .stop_reason ?? undefined,
-                                            ...(type === "thinking"
-                                                ? {
-                                                      provider: "claude",
-                                                      thinkingSourceKey,
-                                                  }
-                                                : {}),
-                                        },
-                                    };
+                                        };
+                                    } else if (!hasYieldedDeltas) {
+                                        yield {
+                                            type,
+                                            content,
+                                            role: "assistant",
+                                            metadata: {
+                                                tokenUsage: {
+                                                    inputTokens:
+                                                        sdkMessage.message.usage
+                                                            ?.input_tokens ?? 0,
+                                                    outputTokens:
+                                                        sdkMessage.message.usage
+                                                            ?.output_tokens ??
+                                                        0,
+                                                },
+                                                model: sdkMessage.message.model,
+                                                stopReason:
+                                                    sdkMessage.message
+                                                        .stop_reason ??
+                                                    undefined,
+                                                ...(type === "thinking"
+                                                    ? {
+                                                          provider: "claude",
+                                                          thinkingSourceKey,
+                                                      }
+                                                    : {}),
+                                            },
+                                        };
+                                    }
                                 }
                             }
+                        } catch (error) {
+                            throw error instanceof Error
+                                ? error
+                                : new Error(String(error));
                         }
 
                         if (!sawTerminalEvent) {
@@ -984,8 +1158,14 @@ export class ClaudeAgentClient implements CodingAgentClient {
                 state.query = newQuery;
 
                 // Consume all messages to complete the compaction
-                for await (const sdkMessage of newQuery) {
-                    this.processMessage(sdkMessage, sessionId, state);
+                try {
+                    for await (const sdkMessage of newQuery) {
+                        this.processMessage(sdkMessage, sessionId, state);
+                    }
+                } catch (error) {
+                    throw error instanceof Error
+                        ? error
+                        : new Error(String(error));
                 }
             },
 
@@ -1059,6 +1239,21 @@ export class ClaudeAgentClient implements CodingAgentClient {
                 }
             },
 
+            abort: async (): Promise<void> => {
+                // Close the active query to terminate in-flight SDK work
+                // (including sub-agent invocations). The session remains
+                // reusable for subsequent queries via resume.
+                state.query?.close();
+            },
+
+            abortBackgroundAgents: async (): Promise<void> => {
+                // Close the active query to terminate background agents.
+                // The Claude SDK manages sub-agents internally within the
+                // query; closing it terminates all in-flight work including
+                // background sub-agent invocations.
+                state.query?.close();
+            },
+
             destroy: async (): Promise<void> => {
                 if (!state.isClosed) {
                     state.isClosed = true;
@@ -1083,6 +1278,18 @@ export class ClaudeAgentClient implements CodingAgentClient {
                     }
                     this.pendingToolBySession.delete(sessionId);
                     this.pendingSubagentBySession.delete(sessionId);
+                    for (const [
+                        toolUseId,
+                        mappedSessionId,
+                    ] of this.toolUseIdToSessionId.entries()) {
+                        if (mappedSessionId === sessionId) {
+                            this.toolUseIdToSessionId.delete(toolUseId);
+                            this.taskDescriptionByToolUseId.delete(toolUseId);
+                        }
+                    }
+                    // Clean up sub-agent session tracking
+                    this.subagentSdkSessionIdToAgentId.clear();
+                    this.unmappedSubagentIds.length = 0;
                     this.sessions.delete(sessionId);
                     this.emitEvent("session.idle", sessionId, {
                         reason: "destroyed",
@@ -1119,7 +1326,79 @@ export class ClaudeAgentClient implements CodingAgentClient {
             }
         }
 
-        // Track token usage
+        // Handle task_progress messages from sub-agents (periodic progress updates)
+        if (
+            sdkMessage.type === "system" &&
+            sdkMessage.subtype === "task_progress"
+        ) {
+            const msg = sdkMessage as Record<string, unknown>;
+            const toolUseId = msg.tool_use_id as string | undefined;
+            const mappedAgentId = toolUseId
+                ? this.toolUseIdToAgentId.get(toolUseId)
+                : undefined;
+            const sessionScopedAgentId =
+                typeof msg.session_id === "string"
+                    ? this.subagentSdkSessionIdToAgentId.get(msg.session_id)
+                    : undefined;
+            const agentId = mappedAgentId ?? sessionScopedAgentId;
+            if (agentId) {
+                const usage = msg.usage as { tool_uses?: number } | undefined;
+                this.emitEvent("subagent.update", sessionId, {
+                    subagentId: agentId,
+                    currentTool: msg.last_tool_name as string | undefined,
+                    toolUses: usage?.tool_uses,
+                });
+            }
+        }
+
+        if (
+            sdkMessage.type === "system" &&
+            sdkMessage.subtype === "task_started"
+        ) {
+            const msg = sdkMessage as Record<string, unknown>;
+            const toolUseId = msg.tool_use_id as string | undefined;
+            const description =
+                typeof msg.description === "string"
+                    ? msg.description.trim()
+                    : "";
+            if (toolUseId && description.length > 0) {
+                this.taskDescriptionByToolUseId.set(toolUseId, description);
+            }
+        }
+
+        // Handle task_notification messages (sub-agent completion notification)
+        if (
+            sdkMessage.type === "system" &&
+            sdkMessage.subtype === "task_notification"
+        ) {
+            const msg = sdkMessage as Record<string, unknown>;
+            const toolUseId = msg.tool_use_id as string | undefined;
+            const mappedAgentId = toolUseId
+                ? this.toolUseIdToAgentId.get(toolUseId)
+                : undefined;
+            const sessionScopedAgentId =
+                typeof msg.session_id === "string"
+                    ? this.subagentSdkSessionIdToAgentId.get(msg.session_id)
+                    : undefined;
+            const agentId = mappedAgentId ?? sessionScopedAgentId;
+            if (agentId) {
+                this.emitEvent("subagent.complete", sessionId, {
+                    subagentId: agentId,
+                    success: msg.status === "completed",
+                    result: msg.summary as string | undefined,
+                });
+                if (toolUseId) {
+                    this.toolUseIdToAgentId.delete(toolUseId);
+                    this.toolUseIdToSessionId.delete(toolUseId);
+                    this.taskDescriptionByToolUseId.delete(toolUseId);
+                }
+            }
+        }
+
+        // Track token usage from assistant messages (state only — values are
+        // stale during streaming because the SDK yields assistant messages at
+        // content_block_stop before message_delta delivers the real count).
+        // The authoritative usage event is emitted from the result message below.
         if (sdkMessage.type === "assistant") {
             const usage = sdkMessage.message.usage;
             if (usage) {
@@ -1149,6 +1428,33 @@ export class ClaudeAgentClient implements CodingAgentClient {
                 });
             }
 
+            // Emit authoritative cumulative usage from the result message.
+            // The result carries the correct totals for all API calls in
+            // this interaction (unlike assistant messages which have stale
+            // initial values during streaming).
+            if (result.usage) {
+                state.inputTokens = result.usage.input_tokens;
+                state.outputTokens = result.usage.output_tokens;
+                if (!state.hasEmittedStreamingUsage) {
+                    // Non-streaming path (send): emit full usage
+                    this.emitEvent("usage", sessionId, {
+                        inputTokens: result.usage.input_tokens ?? 0,
+                        outputTokens: result.usage.output_tokens ?? 0,
+                        model: this.detectedModel,
+                    });
+                } else {
+                    // Streaming path: output tokens already accumulated from message_delta.
+                    // Emit input tokens only (outputTokens: 0 adds nothing to accumulator).
+                    this.emitEvent("usage", sessionId, {
+                        inputTokens: result.usage.input_tokens ?? 0,
+                        outputTokens: 0,
+                        model: this.detectedModel,
+                    });
+                }
+                // Reset so subsequent queries on this session (send, summarize) emit normally
+                state.hasEmittedStreamingUsage = false;
+            }
+
             // Extract contextWindow and systemToolsBaseline from modelUsage
             if (result.modelUsage) {
                 const modelKey =
@@ -1267,6 +1573,36 @@ export class ClaudeAgentClient implements CodingAgentClient {
             }
         }
 
+        // Deterministic FIFO binding for newly-created wrapped sessions that
+        // haven't yet seen their first assistant/result message with sdkSessionId.
+        // This is critical when multiple sessions are created concurrently.
+        for (let i = 0; i < this.pendingHookSessionBindings.length; i++) {
+            const candidateWrappedId = this.pendingHookSessionBindings[i];
+            if (!candidateWrappedId) {
+                continue;
+            }
+            const candidateState = this.sessions.get(candidateWrappedId);
+            if (!candidateState || candidateState.isClosed) {
+                continue;
+            }
+            // Ignore sessions that have not started a query yet (e.g. freshly
+            // created main session before first prompt). Their SDK session ID
+            // is not knowable from hooks yet and should not absorb unrelated
+            // sub-agent hook traffic.
+            if (candidateState.query === null) {
+                continue;
+            }
+            if (
+                candidateState.sdkSessionId &&
+                candidateState.sdkSessionId !== sdkSessionId
+            ) {
+                continue;
+            }
+            this.pendingHookSessionBindings.splice(i, 1);
+            candidateState.sdkSessionId = sdkSessionId;
+            return candidateWrappedId;
+        }
+
         // First hook can arrive before assistant/result messages populate sdkSessionId.
         // If exactly one open session exists, bind this SDK session ID to it.
         const openSessions = Array.from(this.sessions.entries()).filter(
@@ -1280,10 +1616,135 @@ export class ClaudeAgentClient implements CodingAgentClient {
             return wrappedSessionId;
         }
 
+        // If there is exactly one unbound open session, bind it.
+        const unboundOpenSessions = openSessions.filter(
+            ([, state]) => !state.sdkSessionId,
+        );
+        if (unboundOpenSessions.length === 1) {
+            const [wrappedSessionId, state] = unboundOpenSessions[0]!;
+            state.sdkSessionId = sdkSessionId;
+            return wrappedSessionId;
+        }
+
         // Fall back to the SDK ID if we cannot disambiguate.
         return sdkSessionId;
     }
 
+    /**
+     * Resolve tool use correlation ID from either hook callback argument or hook payload.
+     */
+    private resolveHookToolUseId(
+        toolUseID: string | undefined,
+        hookInput: Record<string, unknown>,
+    ): string | undefined {
+        if (typeof toolUseID === "string" && toolUseID.trim().length > 0) {
+            return toolUseID;
+        }
+
+        const candidates = [
+            hookInput.tool_use_id,
+            hookInput.toolUseId,
+            hookInput.toolUseID,
+            hookInput.tool_call_id,
+            hookInput.toolCallId,
+        ];
+        for (const candidate of candidates) {
+            if (typeof candidate === "string" && candidate.trim().length > 0) {
+                return candidate;
+            }
+        }
+        return undefined;
+    }
+
+    /**
+     * Resolve parent tool correlation ID from hook payload.
+     *
+     * Claude hook payloads can provide this as either "use" or "call" IDs
+     * depending on runtime/event shape.
+     */
+    private resolveHookParentToolUseId(
+        hookInput: Record<string, unknown>,
+    ): string | undefined {
+        const candidates = [
+            hookInput.parent_tool_use_id,
+            hookInput.parentToolUseId,
+            hookInput.parentToolUseID,
+            hookInput.parent_tool_call_id,
+            hookInput.parentToolCallId,
+            hookInput.parentToolCallID,
+        ];
+        for (const candidate of candidates) {
+            if (typeof candidate === "string" && candidate.trim().length > 0) {
+                return candidate;
+            }
+        }
+        return undefined;
+    }
+
+    /**
+     * Fallback session routing for hooks that omit session_id.
+     */
+    private resolveFallbackHookSessionId(toolUseId?: string): string {
+        if (toolUseId) {
+            const mappedSessionId = this.toolUseIdToSessionId.get(toolUseId);
+            if (mappedSessionId) {
+                const mappedState = this.sessions.get(mappedSessionId);
+                if (mappedState && !mappedState.isClosed) {
+                    return mappedSessionId;
+                }
+                this.toolUseIdToSessionId.delete(toolUseId);
+            }
+        }
+
+        const openActiveSessions = Array.from(this.sessions.entries()).filter(
+            ([, state]) => !state.isClosed && state.query !== null,
+        );
+        if (openActiveSessions.length === 1) {
+            return openActiveSessions[0]![0];
+        }
+        return "";
+    }
+
+    /**
+     * Get the SDK session ID for a given wrapped session ID.
+     * Returns null if the session doesn't exist or hasn't been bound yet.
+     */
+    private getMainSdkSessionId(wrappedSessionId: string): string | null {
+        const state = this.sessions.get(wrappedSessionId);
+        return state?.sdkSessionId ?? null;
+    }
+
+    /**
+     * Detect if a hook event originates from a sub-agent based on its SDK session ID.
+     * If the hook's session_id differs from the main session's sdkSessionId,
+     * attribute the event to a sub-agent and return the agent ID.
+     */
+    private resolveSubagentParentId(
+        hookSdkSessionId: string,
+        wrappedSessionId: string,
+    ): string | undefined {
+        if (!hookSdkSessionId) return undefined;
+
+        const mainSdkSessionId = this.getMainSdkSessionId(wrappedSessionId);
+        if (!mainSdkSessionId || hookSdkSessionId === mainSdkSessionId) {
+            return undefined;
+        }
+
+        // Check if we've already mapped this SDK session ID to a sub-agent
+        const knownAgentId =
+            this.subagentSdkSessionIdToAgentId.get(hookSdkSessionId);
+        if (knownAgentId) return knownAgentId;
+
+        // Bind to the first unmapped sub-agent
+        if (this.unmappedSubagentIds.length > 0) {
+            const agentId = this.unmappedSubagentIds.shift()!;
+            this.subagentSdkSessionIdToAgentId.set(hookSdkSessionId, agentId);
+            return agentId;
+        }
+
+        return undefined;
+    }
+
     /**
      * Create a new agent session
      */
@@ -1303,10 +1764,18 @@ export class ClaudeAgentClient implements CodingAgentClient {
 
         // Load custom agents from project and global directories
         const projectRoot = process.cwd();
-        const loadedAgents = await loadCopilotAgents(projectRoot);
-        
-        const agentsMap: Record<string, { description: string; prompt: string; tools?: string[]; model?: "sonnet" | "opus" | "haiku" | "inherit" }> = { ...config.agents };
-        
+        const loadedAgents = await this.loadConfiguredAgents(projectRoot);
+
+        const agentsMap: Record<
+            string,
+            {
+                description: string;
+                prompt: string;
+                tools?: string[];
+                model?: "sonnet" | "opus" | "haiku" | "inherit";
+            }
+        > = { ...config.agents };
+
         for (const agent of loadedAgents) {
             if (!agentsMap[agent.name]) {
                 agentsMap[agent.name] = {
@@ -1317,7 +1786,7 @@ export class ClaudeAgentClient implements CodingAgentClient {
                 };
             }
         }
-        
+
         if (Object.keys(agentsMap).length > 0) {
             config.agents = agentsMap;
         }
@@ -1325,6 +1794,7 @@ export class ClaudeAgentClient implements CodingAgentClient {
         // Emit session start event
         this.emitEvent("session.start", sessionId, { config });
         this.emitRuntimeSelection(sessionId, "create");
+        this.pendingHookSessionBindings.push(sessionId);
         return this.wrapQuery(null, sessionId, config);
     }
 
@@ -1365,9 +1835,14 @@ export class ClaudeAgentClient implements CodingAgentClient {
 
             const queryInstance = query({ prompt: "", options });
 
-            return this.wrapQuery(queryInstance, sessionId, {}, {
-                sdkSessionId: sessionId,
-            });
+            return this.wrapQuery(
+                queryInstance,
+                sessionId,
+                {},
+                {
+                    sdkSessionId: sessionId,
+                },
+            );
         } catch (error) {
             console.warn(`Failed to resume session ${sessionId}:`, error);
             return null;
@@ -1412,9 +1887,15 @@ export class ClaudeAgentClient implements CodingAgentClient {
                     // The HookInput has fields like tool_name, tool_input, tool_result
                     // but the UI expects toolName, toolInput, toolResult
                     const hookInput = input as Record<string, unknown>;
+                    const resolvedToolUseId = this.resolveHookToolUseId(
+                        toolUseID,
+                        hookInput,
+                    );
+                    const resolvedParentToolUseId =
+                        this.resolveHookParentToolUseId(hookInput);
                     const eventData: Record<string, unknown> = {
                         hookInput: input,
-                        toolUseID,
+                        toolUseID: resolvedToolUseId,
                     };
 
                     // Map tool-related fields for tool.start and tool.complete events
@@ -1444,9 +1925,92 @@ export class ClaudeAgentClient implements CodingAgentClient {
                     if (hookInput.agent_type) {
                         eventData.subagentType = hookInput.agent_type;
                     }
+                    if (resolvedParentToolUseId) {
+                        eventData.parentToolUseId =
+                            resolvedParentToolUseId;
+                    }
+                    const taskFromHook =
+                        typeof hookInput.description === "string"
+                            ? hookInput.description.trim()
+                            : typeof hookInput.prompt === "string"
+                              ? hookInput.prompt.trim()
+                              : typeof hookInput.task === "string"
+                                ? hookInput.task.trim()
+                                : undefined;
+                    if (targetHookEvent === "SubagentStart") {
+                        const taskFromStartedMessage = resolvedToolUseId
+                            ? this.taskDescriptionByToolUseId.get(
+                                  resolvedToolUseId,
+                              )
+                            : undefined;
+                        // Also check parent_tool_use_id for task description —
+                        // the SubagentStart hook's toolUseID may differ from
+                        // the Agent tool's tool_use_id used in task_started messages.
+                        const taskFromParentToolUse =
+                            resolvedParentToolUseId
+                            ? this.taskDescriptionByToolUseId.get(
+                                  resolvedParentToolUseId,
+                              )
+                            : undefined;
+                        const resolvedTask =
+                            taskFromHook && taskFromHook.length > 0
+                                ? taskFromHook
+                                : (taskFromStartedMessage ??
+                                  taskFromParentToolUse);
+                        if (resolvedTask) {
+                            eventData.task = resolvedTask;
+                        }
+                    }
                     if (targetHookEvent === "SubagentStop") {
                         // SubagentStop implies successful completion
                         eventData.success = true;
+                        // Fill missing agent_id from previously registered tool_use_id.
+                        const mappedAgentId = resolvedToolUseId
+                            ? this.toolUseIdToAgentId.get(resolvedToolUseId)
+                            : undefined;
+                        if (!eventData.subagentId && mappedAgentId) {
+                            eventData.subagentId = mappedAgentId;
+                        }
+                    }
+
+                    // Store toolUseID → agent_id mapping for task_progress correlation.
+                    // Some SubagentStart hook payloads do not include toolUse IDs.
+                    // Still track the agent as "unmapped" so we can later bind a
+                    // child SDK session_id from tool hooks via resolveSubagentParentId().
+                    if (
+                        targetHookEvent === "SubagentStart" &&
+                        hookInput.agent_id
+                    ) {
+                        const startedAgentId = hookInput.agent_id as string;
+                        if (resolvedToolUseId) {
+                            this.toolUseIdToAgentId.set(
+                                resolvedToolUseId,
+                                startedAgentId,
+                            );
+                            // Also register under parent_tool_use_id so task_progress
+                            // messages that carry the Agent tool's tool_use_id (which
+                            // may differ from the SubagentStart hook's toolUseID) can
+                            // still be correlated to the sub-agent.
+                            if (
+                                resolvedParentToolUseId &&
+                                resolvedParentToolUseId !== resolvedToolUseId
+                            ) {
+                                this.toolUseIdToAgentId.set(
+                                    resolvedParentToolUseId,
+                                    startedAgentId,
+                                );
+                            }
+                        }
+
+                        const isAlreadySessionMapped = Array.from(
+                            this.subagentSdkSessionIdToAgentId.values(),
+                        ).includes(startedAgentId);
+                        if (
+                            !isAlreadySessionMapped &&
+                            !this.unmappedSubagentIds.includes(startedAgentId)
+                        ) {
+                            this.unmappedSubagentIds.push(startedAgentId);
+                        }
                     }
 
                     const hookSessionId =
@@ -1455,7 +2019,93 @@ export class ClaudeAgentClient implements CodingAgentClient {
                             : "";
                     const sessionId = hookSessionId
                         ? this.resolveHookSessionId(hookSessionId)
-                        : hookSessionId;
+                        : this.resolveFallbackHookSessionId(resolvedToolUseId);
+
+                    if (
+                        targetHookEvent === "SubagentStart" &&
+                        resolvedToolUseId &&
+                        sessionId
+                    ) {
+                        this.toolUseIdToSessionId.set(
+                            resolvedToolUseId,
+                            sessionId,
+                        );
+                    }
+                    if (targetHookEvent === "SubagentStop") {
+                        if (resolvedToolUseId) {
+                            this.toolUseIdToAgentId.delete(resolvedToolUseId);
+                            this.toolUseIdToSessionId.delete(resolvedToolUseId);
+                            this.taskDescriptionByToolUseId.delete(
+                                resolvedToolUseId,
+                            );
+                            // Also clean up parent_tool_use_id mapping if it exists
+                            if (resolvedParentToolUseId) {
+                                this.toolUseIdToAgentId.delete(
+                                    resolvedParentToolUseId,
+                                );
+                                this.toolUseIdToSessionId.delete(
+                                    resolvedParentToolUseId,
+                                );
+                                this.taskDescriptionByToolUseId.delete(
+                                    resolvedParentToolUseId,
+                                );
+                            }
+                        }
+
+                        // Clean up sub-agent session tracking even when toolUse IDs
+                        // are missing from the stop hook payload.
+                        const stoppedAgentId = (eventData.subagentId ??
+                            hookInput.agent_id) as string | undefined;
+                        if (stoppedAgentId) {
+                            const idx =
+                                this.unmappedSubagentIds.indexOf(
+                                    stoppedAgentId,
+                                );
+                            if (idx >= 0)
+                                this.unmappedSubagentIds.splice(idx, 1);
+                            for (const [sid, aid] of this
+                                .subagentSdkSessionIdToAgentId) {
+                                if (aid === stoppedAgentId) {
+                                    this.subagentSdkSessionIdToAgentId.delete(
+                                        sid,
+                                    );
+                                    break;
+                                }
+                            }
+                        }
+                    }
+
+                    // Detect if this tool hook originates from a sub-agent.
+                    // Sub-agent tool hooks carry a different SDK session_id than
+                    // the main session. When detected, add parentAgentId so the
+                    // adapter can route events to the agent tree.
+                    const mappedParentAgentId =
+                        (resolvedParentToolUseId
+                            ? this.toolUseIdToAgentId.get(
+                                  resolvedParentToolUseId,
+                              )
+                            : undefined) ??
+                        (resolvedToolUseId
+                            ? this.toolUseIdToAgentId.get(resolvedToolUseId)
+                            : undefined);
+                    if (mappedParentAgentId) {
+                        eventData.parentAgentId = mappedParentAgentId;
+                    }
+                    if (
+                        !eventData.parentAgentId &&
+                        targetHookEvent !== "SubagentStart" &&
+                        targetHookEvent !== "SubagentStop" &&
+                        hookSessionId &&
+                        sessionId
+                    ) {
+                        const parentAgentId = this.resolveSubagentParentId(
+                            hookSessionId,
+                            sessionId,
+                        );
+                        if (parentAgentId) {
+                            eventData.parentAgentId = parentAgentId;
+                        }
+                    }
 
                     const event: AgentEvent<T> = {
                         type: eventType,
@@ -1823,7 +2473,8 @@ export function getBundledClaudeCodePath(): string {
             .split(/\r?\n/)[0]
             ?.replace(/\r$/, "");
         if (claudeBin) {
-            const { realpathSync } = require("node:fs") as typeof import("node:fs");
+            const { realpathSync } =
+                require("node:fs") as typeof import("node:fs");
             const realPath = realpathSync(claudeBin);
             // Check if it's an npm package with cli.js
             const pkgDir = dirname(realPath);
diff --git a/src/sdk/clients/copilot.test.ts b/src/sdk/clients/copilot.test.ts
index acacd4f9f6..89abe0c053 100644
--- a/src/sdk/clients/copilot.test.ts
+++ b/src/sdk/clients/copilot.test.ts
@@ -201,7 +201,8 @@ describe("CopilotClient subagent event mapping", () => {
       data: {
         toolCallId: "tc-123",
         agentName: "worker",
-        description: "Fix bug",
+        agentDisplayName: "Worker",
+        agentDescription: "Fix bug",
       },
     });
 
@@ -216,7 +217,7 @@ describe("CopilotClient subagent event mapping", () => {
     });
   });
 
-  test("maps subagent.started with prompt fallback when description is missing", async () => {
+  test("maps subagent.started with empty task when agentDescription is missing", async () => {
     const events: Array<{ type: string; sessionId: string; data: Record<string, unknown> }> = [];
     
     const mockSdkSession = {
@@ -257,7 +258,8 @@ describe("CopilotClient subagent event mapping", () => {
       data: {
         toolCallId: "tc-456",
         agentName: "debugger",
-        prompt: "Debug the error",
+        agentDisplayName: "Debugger",
+        agentDescription: "",
       },
     });
 
@@ -266,11 +268,11 @@ describe("CopilotClient subagent event mapping", () => {
       subagentId: "tc-456",
       subagentType: "debugger",
       toolCallId: "tc-456",
-      task: "Debug the error",
+      task: "",
     });
   });
 
-  test("maps subagent.started with agentName fallback when description and prompt are missing", async () => {
+  test("maps subagent.started with agentDescription when available, empty when not", async () => {
     const events: Array<{ type: string; sessionId: string; data: Record<string, unknown> }> = [];
     
     const mockSdkSession = {
@@ -311,6 +313,8 @@ describe("CopilotClient subagent event mapping", () => {
       data: {
         toolCallId: "tc-789",
         agentName: "explorer",
+        agentDisplayName: "Explorer",
+        agentDescription: "",
       },
     });
 
@@ -319,7 +323,7 @@ describe("CopilotClient subagent event mapping", () => {
       subagentId: "tc-789",
       subagentType: "explorer",
       toolCallId: "tc-789",
-      task: "explorer",
+      task: "",
     });
   });
 
@@ -429,3 +433,393 @@ describe("CopilotClient subagent event mapping", () => {
     });
   });
 });
+
+describe("CopilotClient tool event mapping", () => {
+  test("maps tool.execution_start using mcpToolName fallback", () => {
+    const client = new CopilotClient({});
+    const events: Array<{ sessionId: string; data: Record<string, unknown> }> = [];
+
+    client.on("tool.start", (event) => {
+      events.push({ sessionId: event.sessionId, data: event.data as Record<string, unknown> });
+    });
+
+    (client as unknown as {
+      sessions: Map<string, {
+        sdkSession: unknown;
+        sessionId: string;
+        config: Record<string, unknown>;
+        inputTokens: number;
+        outputTokens: number;
+        isClosed: boolean;
+        unsubscribe: () => void;
+        toolCallIdToName: Map<string, string>;
+        contextWindow: number | null;
+        systemToolsBaseline: number | null;
+      }>;
+    }).sessions.set("test-session", {
+      sdkSession: {},
+      sessionId: "test-session",
+      config: {},
+      inputTokens: 0,
+      outputTokens: 0,
+      isClosed: false,
+      unsubscribe: () => {},
+      toolCallIdToName: new Map(),
+      contextWindow: null,
+      systemToolsBaseline: null,
+    });
+
+    const handleSdkEvent = (client as unknown as {
+      handleSdkEvent: (sessionId: string, event: { type: string; data: Record<string, unknown> }) => void;
+    }).handleSdkEvent.bind(client);
+
+    handleSdkEvent("test-session", {
+      type: "tool.execution_start",
+      data: {
+        toolCallId: "tool-1",
+        mcpToolName: "filesystem/read_file",
+        arguments: "README.md",
+      },
+    });
+
+    expect(events).toHaveLength(1);
+    expect(events[0]!.sessionId).toBe("test-session");
+    expect(events[0]!.data).toEqual({
+      toolName: "filesystem/read_file",
+      toolInput: "README.md",
+      toolCallId: "tool-1",
+      parentId: undefined,
+    });
+  });
+
+  test("maps tool.execution_complete with result fallbacks and tracked tool name", () => {
+    const client = new CopilotClient({});
+    const events: Array<{ sessionId: string; data: Record<string, unknown> }> = [];
+
+    client.on("tool.complete", (event) => {
+      events.push({ sessionId: event.sessionId, data: event.data as Record<string, unknown> });
+    });
+
+    const trackedNames = new Map<string, string>();
+    trackedNames.set("tool-2", "view");
+
+    (client as unknown as {
+      sessions: Map<string, {
+        sdkSession: unknown;
+        sessionId: string;
+        config: Record<string, unknown>;
+        inputTokens: number;
+        outputTokens: number;
+        isClosed: boolean;
+        unsubscribe: () => void;
+        toolCallIdToName: Map<string, string>;
+        contextWindow: number | null;
+        systemToolsBaseline: number | null;
+      }>;
+    }).sessions.set("test-session", {
+      sdkSession: {},
+      sessionId: "test-session",
+      config: {},
+      inputTokens: 0,
+      outputTokens: 0,
+      isClosed: false,
+      unsubscribe: () => {},
+      toolCallIdToName: trackedNames,
+      contextWindow: null,
+      systemToolsBaseline: null,
+    });
+
+    const handleSdkEvent = (client as unknown as {
+      handleSdkEvent: (sessionId: string, event: { type: string; data: Record<string, unknown> }) => void;
+    }).handleSdkEvent.bind(client);
+
+    handleSdkEvent("test-session", {
+      type: "tool.execution_complete",
+      data: {
+        toolCallId: "tool-2",
+        success: true,
+        result: {
+          detailedContent: "line 1\nline 2",
+        },
+      },
+    });
+
+    expect(events).toHaveLength(1);
+    expect(events[0]!.sessionId).toBe("test-session");
+    expect(events[0]!.data).toEqual({
+      toolName: "view",
+      success: true,
+      toolResult: "line 1\nline 2",
+      error: undefined,
+      toolCallId: "tool-2",
+      parentId: undefined,
+    });
+  });
+});
+
+describe("CopilotClient message_delta preserves parentToolCallId and messageId", () => {
+  test("handleSdkEvent passes parentToolCallId and messageId to unified event", () => {
+    const client = new CopilotClient({});
+    const events: Array<{ data: Record<string, unknown> }> = [];
+
+    client.on("message.delta", (event) => {
+      events.push({ data: event.data as Record<string, unknown> });
+    });
+
+    const handleSdkEvent = (client as unknown as {
+      handleSdkEvent: (sessionId: string, event: { type: string; data: Record<string, unknown> }) => void;
+    }).handleSdkEvent.bind(client);
+
+    handleSdkEvent("test-session", {
+      type: "assistant.message_delta",
+      data: {
+        deltaContent: "Hello world",
+        messageId: "msg-123",
+        parentToolCallId: "tc-456",
+      },
+    });
+
+    expect(events).toHaveLength(1);
+    expect(events[0]!.data.delta).toBe("Hello world");
+    expect(events[0]!.data.messageId).toBe("msg-123");
+    expect(events[0]!.data.parentToolCallId).toBe("tc-456");
+  });
+
+  test("handleSdkEvent omits parentToolCallId when not present", () => {
+    const client = new CopilotClient({});
+    const events: Array<{ data: Record<string, unknown> }> = [];
+
+    client.on("message.delta", (event) => {
+      events.push({ data: event.data as Record<string, unknown> });
+    });
+
+    const handleSdkEvent = (client as unknown as {
+      handleSdkEvent: (sessionId: string, event: { type: string; data: Record<string, unknown> }) => void;
+    }).handleSdkEvent.bind(client);
+
+    handleSdkEvent("test-session", {
+      type: "assistant.message_delta",
+      data: {
+        deltaContent: "Main agent text",
+        messageId: "msg-789",
+      },
+    });
+
+    expect(events).toHaveLength(1);
+    expect(events[0]!.data.delta).toBe("Main agent text");
+    expect(events[0]!.data.messageId).toBe("msg-789");
+    expect(events[0]!.data.parentToolCallId).toBeUndefined();
+  });
+});
+
+describe("CopilotClient assistant.message preserves toolRequests", () => {
+  test("handleSdkEvent passes toolRequests to message.complete event", () => {
+    const client = new CopilotClient({});
+    const events: Array<{ data: Record<string, unknown> }> = [];
+
+    client.on("message.complete", (event) => {
+      events.push({ data: event.data as Record<string, unknown> });
+    });
+
+    const handleSdkEvent = (client as unknown as {
+      handleSdkEvent: (sessionId: string, event: { type: string; data: Record<string, unknown> }) => void;
+    }).handleSdkEvent.bind(client);
+
+    handleSdkEvent("test-session", {
+      type: "assistant.message",
+      data: {
+        content: "Let me check that file.",
+        messageId: "msg-001",
+        toolRequests: [
+          { toolCallId: "tc-1", name: "view", arguments: { path: "/tmp/file.txt" } },
+        ],
+      },
+    });
+
+    expect(events).toHaveLength(1);
+    const data = events[0]!.data;
+    expect((data.message as Record<string, unknown>).content).toBe("Let me check that file.");
+    expect(data.toolRequests).toEqual([
+      { toolCallId: "tc-1", name: "view", arguments: { path: "/tmp/file.txt" } },
+    ]);
+  });
+
+  test("handleSdkEvent omits toolRequests when not present", () => {
+    const client = new CopilotClient({});
+    const events: Array<{ data: Record<string, unknown> }> = [];
+
+    client.on("message.complete", (event) => {
+      events.push({ data: event.data as Record<string, unknown> });
+    });
+
+    const handleSdkEvent = (client as unknown as {
+      handleSdkEvent: (sessionId: string, event: { type: string; data: Record<string, unknown> }) => void;
+    }).handleSdkEvent.bind(client);
+
+    handleSdkEvent("test-session", {
+      type: "assistant.message",
+      data: {
+        content: "Done!",
+        messageId: "msg-002",
+      },
+    });
+
+    expect(events).toHaveLength(1);
+    expect(events[0]!.data.toolRequests).toBeUndefined();
+  });
+});
+
+describe("CopilotClient stream() filters sub-agent deltas", () => {
+  test("stream() skips assistant.message_delta with parentToolCallId", async () => {
+    const listeners: Array<(event: {
+      type: string;
+      data: Record<string, unknown>;
+    }) => void> = [];
+
+    const mockSdkSession = {
+      sessionId: "copilot-subagent-session",
+      on: mock((handler: (event: { type: string; data: Record<string, unknown> }) => void) => {
+        listeners.push(handler);
+        return () => {
+          const idx = listeners.indexOf(handler);
+          if (idx >= 0) listeners.splice(idx, 1);
+        };
+      }),
+      send: mock(async () => {
+        // Main agent text
+        for (const listener of [...listeners]) {
+          listener({
+            type: "assistant.message_delta",
+            data: { deltaContent: "main text", messageId: "msg-1" },
+          });
+        }
+        // Sub-agent text (should be skipped)
+        for (const listener of [...listeners]) {
+          listener({
+            type: "assistant.message_delta",
+            data: { deltaContent: "sub-agent text", messageId: "msg-2", parentToolCallId: "tc-sub" },
+          });
+        }
+        // More main agent text
+        for (const listener of [...listeners]) {
+          listener({
+            type: "assistant.message_delta",
+            data: { deltaContent: " continues", messageId: "msg-1" },
+          });
+        }
+        for (const listener of [...listeners]) {
+          listener({ type: "session.idle", data: {} });
+        }
+      }),
+      sendAndWait: mock(() => Promise.resolve({ data: { content: "" } })),
+      destroy: mock(() => Promise.resolve()),
+      abort: mock(() => Promise.resolve()),
+    };
+
+    const client = new CopilotClient({});
+    const wrapSession = (client as unknown as {
+      wrapSession: (
+        sdkSession: unknown,
+        config: Record<string, unknown>,
+      ) => {
+        stream: (message: string) => AsyncIterable<{
+          type: string;
+          content: unknown;
+        }>;
+      };
+    }).wrapSession.bind(client);
+
+    const session = wrapSession(mockSdkSession, {});
+    const streamed: Array<{ type: string; content: unknown }> = [];
+    for await (const chunk of session.stream("hello")) {
+      streamed.push(chunk);
+    }
+
+    // Only main agent text should be yielded (sub-agent text filtered out)
+    const textChunks = streamed.filter(c => c.type === "text");
+    expect(textChunks).toHaveLength(2);
+    expect(textChunks[0]!.content).toBe("main text");
+    expect(textChunks[1]!.content).toBe(" continues");
+  });
+});
+
+describe("CopilotClient error propagation", () => {
+  test("maps structured session.error payloads to readable error strings", () => {
+    const client = new CopilotClient({});
+    const errors: Array<{ error?: unknown; code?: unknown }> = [];
+
+    client.on("session.error", (event) => {
+      const data = event.data as { error?: unknown; code?: unknown };
+      errors.push({ error: data.error, code: data.code });
+    });
+
+    const handleSdkEvent = (client as unknown as {
+      handleSdkEvent: (sessionId: string, event: { type: string; data: Record<string, unknown> }) => void;
+    }).handleSdkEvent.bind(client);
+
+    handleSdkEvent("copilot-session", {
+      type: "session.error",
+      data: {
+        error: {
+          message: "Copilot rate limit exceeded",
+        },
+        code: "RATE_LIMIT",
+      },
+    });
+
+    expect(errors).toEqual([
+      {
+        error: "Copilot rate limit exceeded",
+        code: "RATE_LIMIT",
+      },
+    ]);
+  });
+
+  test("stream propagates normalized provider errors", async () => {
+    const listeners: Array<(event: {
+      type: string;
+      data: Record<string, unknown>;
+    }) => void> = [];
+
+    const mockSdkSession = {
+      sessionId: "copilot-error-session",
+      on: mock((handler: (event: { type: string; data: Record<string, unknown> }) => void) => {
+        listeners.push(handler);
+        return () => {
+          const idx = listeners.indexOf(handler);
+          if (idx >= 0) listeners.splice(idx, 1);
+        };
+      }),
+      send: mock(async () => {
+        throw {
+          error: {
+            message: "Authentication failed",
+          },
+        };
+      }),
+      sendAndWait: mock(() => Promise.resolve({ data: { content: "" } })),
+      destroy: mock(() => Promise.resolve()),
+      abort: mock(() => Promise.resolve()),
+    };
+
+    const client = new CopilotClient({});
+    const wrapSession = (client as unknown as {
+      wrapSession: (
+        sdkSession: unknown,
+        config: Record<string, unknown>,
+      ) => {
+        stream: (message: string) => AsyncIterable<unknown>;
+      };
+    }).wrapSession.bind(client);
+
+    const session = wrapSession(mockSdkSession, {});
+
+    const consumeStream = async (): Promise<void> => {
+      for await (const _chunk of session.stream("hello")) {
+        // stream should throw before yielding when send() fails
+      }
+    };
+
+    await expect(consumeStream()).rejects.toThrow("Authentication failed");
+  });
+});
diff --git a/src/sdk/clients/copilot.ts b/src/sdk/clients/copilot.ts
index 3d95db8d8f..900d5bfdf9 100644
--- a/src/sdk/clients/copilot.ts
+++ b/src/sdk/clients/copilot.ts
@@ -58,7 +58,7 @@ import { loadCopilotAgents } from "../../config/copilot-manual.ts";
 import {
   BACKGROUND_COMPACTION_THRESHOLD,
   BUFFER_EXHAUSTION_THRESHOLD,
-} from "../../graph/types.ts";
+} from "../../workflows/graph/types.ts";
 
 import {
   stripProviderPrefix,
@@ -158,19 +158,127 @@ function mapSdkEventToEventType(sdkEventType: SdkSessionEventType | string): Eve
     "session.resume": "session.start",
     "session.idle": "session.idle",
     "session.error": "session.error",
+    "session.info": "session.info",
+    "session.warning": "session.warning",
+    "session.title_changed": "session.title_changed",
+    "session.truncation": "session.truncation",
+    "session.compaction_start": "session.compaction",
+    "session.compaction_complete": "session.compaction",
     "assistant.message_delta": "message.delta",
     "assistant.message": "message.complete",
+    "assistant.reasoning_delta": "reasoning.delta",
+    "assistant.reasoning": "reasoning.complete",
+    "assistant.turn_start": "turn.start",
+    "assistant.turn_end": "turn.end",
+    "assistant.usage": "usage",
     "tool.execution_start": "tool.start",
     "tool.execution_complete": "tool.complete",
+    "tool.execution_partial_result": "tool.partial_result",
     "skill.invoked": "skill.invoked",
     "subagent.started": "subagent.start",
     "subagent.completed": "subagent.complete",
     "subagent.failed": "subagent.complete",
-    "session.usage_info": "usage",
+    // session.usage_info is NOT mapped to "usage" — it carries context-window
+    // metadata (currentTokens, tokenLimit), not per-turn token counts. Mapping
+    // it to "usage" would cause the adapter to publish stream.usage with
+    // { inputTokens: 0, outputTokens: 0 }, zeroing out the real counts from
+    // assistant.usage events.
+    // "session.usage_info": handled separately in handleSdkEvent (state only)
   };
   return mapping[sdkEventType] ?? null;
 }
 
+function asNonEmptyString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim().length > 0
+    ? value
+    : undefined;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+    return value as Record<string, unknown>;
+  }
+  return undefined;
+}
+
+function extractCopilotToolResult(result: unknown): unknown {
+  const resultRecord = asRecord(result);
+  if (!resultRecord) {
+    return result;
+  }
+
+  const content = resultRecord.content;
+  if (typeof content === "string" && content.trim().length > 0) {
+    return content;
+  }
+
+  const detailedContent = resultRecord.detailedContent;
+  if (typeof detailedContent === "string" && detailedContent.trim().length > 0) {
+    return detailedContent;
+  }
+
+  if ("contents" in resultRecord) {
+    return resultRecord.contents;
+  }
+
+  return result;
+}
+
+function extractCopilotErrorMessage(error: unknown, fallback = "Unknown error"): string {
+  if (error instanceof Error) {
+    return error.message;
+  }
+
+  const direct = asNonEmptyString(error);
+  if (direct) {
+    return direct;
+  }
+
+  const record = asRecord(error);
+  if (!record) {
+    return fallback;
+  }
+
+  const directFields = [
+    record.message,
+    record.error,
+    record.details,
+    record.reason,
+    record.stderr,
+    record.stdout,
+  ];
+
+  for (const field of directFields) {
+    const value = asNonEmptyString(field);
+    if (value) {
+      return value;
+    }
+  }
+
+  const nestedError = record.error;
+  if (nestedError !== undefined && nestedError !== error) {
+    const nested = extractCopilotErrorMessage(nestedError, "");
+    if (nested.length > 0) {
+      return nested;
+    }
+  }
+
+  if (Array.isArray(record.errors) && record.errors.length > 0) {
+    const entries = record.errors
+      .map((entry) => extractCopilotErrorMessage(entry, ""))
+      .filter((entry) => entry.length > 0);
+    if (entries.length > 0) {
+      return entries.join("; ");
+    }
+  }
+
+  try {
+    return JSON.stringify(record);
+  } catch {
+    return fallback;
+  }
+}
+
 /**
  * CopilotClient implements CodingAgentClient for the GitHub Copilot SDK.
  *
@@ -189,6 +297,7 @@ export class CopilotClient implements CodingAgentClient {
   private isRunning = false;
   private probeSystemToolsBaseline: number | null = null;
   private probePromise: Promise<void> | null = null;
+  private knownAgentNames: string[] = [];
 
   /**
    * Create a new CopilotClient
@@ -303,8 +412,13 @@ export class CopilotClient implements CodingAgentClient {
           throw new Error("Session is closed");
         }
 
-        // Use sendAndWait for blocking send
-        const response = await state.sdkSession.sendAndWait({ prompt: message });
+        let response: Awaited<ReturnType<SdkCopilotSession["sendAndWait"]>>;
+        try {
+          // Use sendAndWait for blocking send
+          response = await state.sdkSession.sendAndWait({ prompt: message });
+        } catch (error) {
+          throw new Error(extractCopilotErrorMessage(error));
+        }
 
         // Track token usage from usage events
         if (response) {
@@ -358,6 +472,12 @@ export class CopilotClient implements CodingAgentClient {
 
             const eventHandler = (event: SdkSessionEvent) => {
               if (event.type === "assistant.message_delta") {
+                // Skip sub-agent deltas: they have parentToolCallId and are
+                // handled separately by the event bus adapter. Mixing them
+                // into the main stream garbles text.
+                const deltaData = event.data as Record<string, unknown>;
+                if (deltaData.parentToolCallId) return;
+
                 // Accumulate reasoning duration when transitioning away from reasoning
                 if (reasoningStartMs !== null) {
                   reasoningDurationMs += Date.now() - reasoningStartMs;
@@ -410,6 +530,10 @@ export class CopilotClient implements CodingAgentClient {
                 });
                 notifyConsumer();
               } else if (event.type === "assistant.message") {
+                // Skip sub-agent complete messages
+                const msgData = event.data as Record<string, unknown>;
+                if (msgData.parentToolCallId) return;
+
                 // Only yield the complete message if we haven't streamed deltas
                 // (deltas already contain the full content incrementally)
                 if (!hasYieldedDeltas) {
@@ -444,7 +568,11 @@ export class CopilotClient implements CodingAgentClient {
             try {
               // Send the message (non-blocking - returns immediately)
               // Events will start arriving via eventHandler
-              await state.sdkSession.send({ prompt: message });
+              try {
+                await state.sdkSession.send({ prompt: message });
+              } catch (error) {
+                throw new Error(extractCopilotErrorMessage(error));
+              }
 
               // Yield chunks as they arrive
               // The loop continues until done is true AND all chunks are consumed
@@ -511,6 +639,14 @@ export class CopilotClient implements CodingAgentClient {
         await state.sdkSession.abort();
       },
 
+      abortBackgroundAgents: async (): Promise<void> => {
+        // Abort background agents by terminating all in-flight SDK work.
+        // The Copilot SDK does not expose individual sub-agent session
+        // handles, so we abort the entire session. This is safe because
+        // Ctrl+F only fires when NOT streaming (no foreground to preserve).
+        await state.sdkSession.abort();
+      },
+
       getSystemToolsTokens: (): number => {
         if (state.systemToolsBaseline === null) {
           throw new Error("System tools baseline unavailable: no session.usage_info received yet.");
@@ -566,8 +702,15 @@ export class CopilotClient implements CodingAgentClient {
 
     // Map to unified event type
     const eventType = mapSdkEventToEventType(event.type);
-    if (eventType) {
-      let eventData: Record<string, unknown> = {};
+    if (!eventType) {
+      // DEBUG: Log unmapped event types for Copilot debugging
+      if (event.type.startsWith("tool.")) {
+        console.warn(`[CopilotClient] Unmapped tool event: ${event.type}`);
+      }
+      return;
+    }
+
+    let eventData: Record<string, unknown> = {};
 
       // Cast event.data to access properties (type narrowing doesn't work after casting event.type)
       const data = event.data as Record<string, unknown>;
@@ -579,48 +722,79 @@ export class CopilotClient implements CodingAgentClient {
           eventData = { reason: "idle" };
           break;
         case "session.error":
-          eventData = { error: data.message };
+          eventData = {
+            error: extractCopilotErrorMessage(data),
+            code: asNonEmptyString(data.code),
+          };
           break;
         case "assistant.message_delta":
-          eventData = { delta: data.deltaContent };
+          eventData = {
+            delta: data.deltaContent,
+            messageId: asNonEmptyString(data.messageId),
+            parentToolCallId: asNonEmptyString(data.parentToolCallId),
+          };
           break;
-        case "assistant.message":
+        case "assistant.message": {
+          const toolRequests = Array.isArray(data.toolRequests)
+            ? (data.toolRequests as Array<Record<string, unknown>>).map((tr) => ({
+              toolCallId: String(tr.toolCallId ?? ""),
+              name: String(tr.name ?? ""),
+              arguments: tr.arguments,
+            }))
+            : undefined;
           eventData = {
             message: {
               type: "text",
               content: data.content,
               role: "assistant",
             },
+            toolRequests,
+            parentToolCallId: asNonEmptyString(data.parentToolCallId),
           };
           break;
+        }
         case "tool.execution_start": {
           // Track toolCallId -> toolName mapping for the complete event
-          const toolCallId = data.toolCallId as string | undefined;
-          const toolName = data.toolName as string | undefined;
-          if (state && toolCallId && toolName) {
+          const toolCallId = asNonEmptyString(data.toolCallId);
+          const toolName = asNonEmptyString(data.toolName)
+            ?? asNonEmptyString(data.mcpToolName)
+            ?? "unknown";
+          if (state && toolCallId) {
             state.toolCallIdToName.set(toolCallId, toolName);
           }
+          // Extract parentToolCallId to link tool calls to their parent sub-agent
+          const parentToolCallId = asNonEmptyString(data.parentToolCallId);
           eventData = {
-            toolName: toolName,
+            toolName,
             toolInput: data.arguments,
             toolCallId,
+            parentId: parentToolCallId,
           };
           break;
         }
         case "tool.execution_complete": {
           // Look up the actual tool name from the toolCallId
-          const toolCallId = data.toolCallId as string;
-          const toolName = state?.toolCallIdToName.get(toolCallId) ?? toolCallId;
+          const toolCallId = asNonEmptyString(data.toolCallId);
+          const mappedToolName = toolCallId ? state?.toolCallIdToName.get(toolCallId) : undefined;
+          const toolName = mappedToolName
+            ?? asNonEmptyString(data.toolName)
+            ?? asNonEmptyString(data.mcpToolName)
+            ?? "unknown";
           // Clean up the mapping
-          state?.toolCallIdToName.delete(toolCallId);
-          const resultData = data.result as Record<string, unknown> | undefined;
-          const errorData = data.error as Record<string, unknown> | undefined;
+          if (toolCallId) {
+            state?.toolCallIdToName.delete(toolCallId);
+          }
+          const errorData = asRecord(data.error);
+          const success = typeof data.success === "boolean" ? data.success : true;
+          // Extract parentToolCallId to link tool calls to their parent sub-agent
+          const parentToolCallId = asNonEmptyString(data.parentToolCallId);
           eventData = {
             toolName,
-            success: data.success,
-            toolResult: resultData?.content,
-            error: errorData?.message,
-            toolCallId: data.toolCallId,
+            success,
+            toolResult: extractCopilotToolResult(data.result),
+            error: asNonEmptyString(errorData?.message),
+            toolCallId,
+            parentId: parentToolCallId,
           };
           break;
         }
@@ -629,7 +803,7 @@ export class CopilotClient implements CodingAgentClient {
             subagentId: data.toolCallId,
             subagentType: data.agentName,
             toolCallId: data.toolCallId,
-            task: data.description ?? data.prompt ?? data.agentName,
+            task: data.agentDescription || "",
           };
           break;
         case "skill.invoked":
@@ -651,16 +825,84 @@ export class CopilotClient implements CodingAgentClient {
             error: data.error,
           };
           break;
-        case "session.usage_info":
+        case "assistant.reasoning_delta":
+          eventData = {
+            delta: data.deltaContent,
+            reasoningId: data.reasoningId,
+          };
+          break;
+        case "assistant.reasoning":
+          eventData = {
+            reasoningId: data.reasoningId,
+            content: data.content,
+          };
+          break;
+        case "assistant.turn_start":
+          eventData = {
+            turnId: data.turnId,
+          };
+          break;
+        case "assistant.turn_end":
+          eventData = {
+            turnId: data.turnId,
+            finishReason: asNonEmptyString(data.finishReason) ?? asNonEmptyString(data.stopReason) ?? asNonEmptyString(data.reason),
+            rawFinishReason: asNonEmptyString(data.rawFinishReason) ?? asNonEmptyString(data.finishReason) ?? asNonEmptyString(data.stopReason) ?? asNonEmptyString(data.reason),
+          };
+          break;
+        case "assistant.usage":
+          eventData = {
+            inputTokens: data.inputTokens ?? 0,
+            outputTokens: data.outputTokens ?? 0,
+            model: data.model,
+          };
+          break;
+        case "tool.execution_partial_result":
           eventData = {
-            currentTokens: data.currentTokens,
-            tokenLimit: data.tokenLimit,
+            toolCallId: data.toolCallId,
+            partialOutput: data.partialOutput,
           };
           break;
+        case "session.info":
+          eventData = {
+            infoType: data.infoType ?? "general",
+            message: data.message ?? "",
+          };
+          break;
+        case "session.warning":
+          eventData = {
+            warningType: data.warningType ?? "general",
+            message: data.message ?? "",
+          };
+          break;
+        case "session.title_changed":
+          eventData = {
+            title: data.title ?? "",
+          };
+          break;
+        case "session.truncation":
+          eventData = {
+            tokenLimit: data.tokenLimit ?? 0,
+            tokensRemoved: data.tokensRemovedDuringTruncation ?? 0,
+            messagesRemoved: data.messagesRemovedDuringTruncation ?? 0,
+          };
+          break;
+        case "session.compaction_start":
+          eventData = {
+            phase: "start",
+          };
+          break;
+        case "session.compaction_complete":
+          eventData = {
+            phase: "complete",
+            success: typeof data.success === "boolean" ? data.success : true,
+            error: asNonEmptyString(data.error),
+          };
+          break;
+        // session.usage_info is no longer mapped to a unified event type —
+        // it is handled above for state tracking only (context window metadata).
       }
 
       this.emitEvent(eventType, sessionId, eventData);
-    }
   }
 
   /**
@@ -672,7 +914,9 @@ export class CopilotClient implements CodingAgentClient {
     data: Record<string, unknown>
   ): void {
     const handlers = this.eventHandlers.get(eventType);
-    if (!handlers) return;
+    if (!handlers || handlers.size === 0) {
+      return;
+    }
 
     const event: AgentEvent<T> = {
       type: eventType,
@@ -798,6 +1042,10 @@ export class CopilotClient implements CodingAgentClient {
     // Load custom agents from project and global directories
     const projectRoot = this.clientOptions.cwd ?? process.cwd();
     const loadedAgents = await loadCopilotAgents(projectRoot);
+    this.knownAgentNames = [
+      "general-purpose",
+      ...loadedAgents.map(a => a.name),
+    ];
     const customAgents: SdkCustomAgentConfig[] = loadedAgents.map((agent) => ({
       name: agent.name,
       description: agent.description,
@@ -1044,7 +1292,9 @@ export class CopilotClient implements CodingAgentClient {
     // reason to block startup on it.
     this.probePromise = (async () => {
       try {
-        const probeSession = await this.sdkClient!.createSession({});
+        const probeSession = await this.sdkClient!.createSession({
+          onPermissionRequest: () => ({ kind: "denied-by-rules" as const }),
+        } as SdkSessionConfig);
         const baseline = await new Promise<number | null>((resolve) => {
           let unsub: (() => void) | null = null;
           const timeout = setTimeout(() => {
@@ -1222,6 +1472,10 @@ export class CopilotClient implements CodingAgentClient {
   getSystemToolsTokens(): number | null {
     return this.probeSystemToolsBaseline;
   }
+
+  getKnownAgentNames(): string[] {
+    return this.knownAgentNames;
+  }
 }
 
 /**
diff --git a/src/sdk/clients/opencode.events.test.ts b/src/sdk/clients/opencode.events.test.ts
index a61a6e5e46..ae0da33e41 100644
--- a/src/sdk/clients/opencode.events.test.ts
+++ b/src/sdk/clients/opencode.events.test.ts
@@ -1,5 +1,135 @@
 import { describe, expect, test } from "bun:test";
-import { OpenCodeClient } from "./opencode.ts";
+import {
+  COMPACTION_TERMINAL_ERROR_MESSAGE,
+  isContextOverflowError,
+  OpenCodeClient,
+  OpenCodeCompactionError,
+  transitionOpenCodeCompactionControl,
+} from "./opencode.ts";
+import {
+  getRuntimeParityMetricsSnapshot,
+  resetRuntimeParityMetrics,
+} from "../../workflows/runtime-parity-observability.ts";
+
+describe("isContextOverflowError", () => {
+  test("detects overflow messages across known pattern variants", () => {
+    const overflowErrors = [
+      "ContextOverflowError: Input exceeds context window of this model",
+      "code=context_length_exceeded",
+      "prompt is too long for this model",
+      "Request too large for provider",
+      "Exceeded the model's maximum context length",
+      "Too many tokens in request",
+    ];
+
+    for (const message of overflowErrors) {
+      expect(isContextOverflowError(message)).toBe(true);
+      expect(isContextOverflowError(new Error(message))).toBe(true);
+    }
+  });
+
+  test("does not flag unrelated errors as overflow", () => {
+    expect(isContextOverflowError("Rate limit exceeded")).toBe(false);
+    expect(isContextOverflowError(new Error("Network connection reset"))).toBe(false);
+    expect(isContextOverflowError("")).toBe(false);
+  });
+});
+
+describe("transitionOpenCodeCompactionControl", () => {
+  test("applies bounded transitions through success path", () => {
+    const started = transitionOpenCodeCompactionControl(
+      { state: "STREAMING", startedAt: null },
+      "compaction.start",
+      { now: 10 },
+    );
+    const completed = transitionOpenCodeCompactionControl(
+      started,
+      "compaction.complete.success",
+      { now: 20 },
+    );
+
+    expect(started).toEqual({ state: "COMPACTING", startedAt: 10 });
+    expect(completed).toEqual({ state: "STREAMING", startedAt: null });
+  });
+
+  test("rejects invalid compaction start transitions", () => {
+    expect(() =>
+      transitionOpenCodeCompactionControl(
+        { state: "COMPACTING", startedAt: 10 },
+        "compaction.start",
+        { now: 20 },
+      )).toThrow(OpenCodeCompactionError);
+  });
+
+  test("rejects error completion transitions outside compacting state", () => {
+    expect(() =>
+      transitionOpenCodeCompactionControl(
+        { state: "STREAMING", startedAt: null },
+        "compaction.complete.error",
+        {
+          now: 20,
+          errorCode: "COMPACTION_TIMEOUT",
+          errorMessage: COMPACTION_TERMINAL_ERROR_MESSAGE,
+        },
+      )).toThrow(OpenCodeCompactionError);
+  });
+
+  test("transitions to terminal error and ended states on failure", () => {
+    const failed = transitionOpenCodeCompactionControl(
+      { state: "COMPACTING", startedAt: 10 },
+      "compaction.complete.error",
+      {
+        now: 20,
+        errorCode: "COMPACTION_TIMEOUT",
+        errorMessage: COMPACTION_TERMINAL_ERROR_MESSAGE,
+      },
+    );
+    const ended = transitionOpenCodeCompactionControl(failed, "turn.ended");
+
+    expect(failed).toEqual({
+      state: "TERMINAL_ERROR",
+      startedAt: 10,
+      errorCode: "COMPACTION_TIMEOUT",
+      errorMessage: COMPACTION_TERMINAL_ERROR_MESSAGE,
+    });
+    expect(ended).toEqual({
+      state: "ENDED",
+      startedAt: 10,
+      errorCode: "COMPACTION_TIMEOUT",
+      errorMessage: COMPACTION_TERMINAL_ERROR_MESSAGE,
+    });
+  });
+
+  test("keeps terminal states unchanged on late complete events", () => {
+    const terminal = {
+      state: "TERMINAL_ERROR" as const,
+      startedAt: 10,
+      errorCode: "COMPACTION_FAILED" as const,
+      errorMessage: COMPACTION_TERMINAL_ERROR_MESSAGE,
+    };
+    const ended = {
+      state: "ENDED" as const,
+      startedAt: 10,
+      errorCode: "COMPACTION_FAILED" as const,
+      errorMessage: COMPACTION_TERMINAL_ERROR_MESSAGE,
+    };
+
+    expect(transitionOpenCodeCompactionControl(terminal, "compaction.complete.success")).toEqual(terminal);
+    expect(
+      transitionOpenCodeCompactionControl(terminal, "compaction.complete.error", {
+        errorCode: "COMPACTION_TIMEOUT",
+        errorMessage: COMPACTION_TERMINAL_ERROR_MESSAGE,
+      }),
+    ).toEqual(terminal);
+    expect(transitionOpenCodeCompactionControl(ended, "compaction.complete.success")).toEqual(ended);
+    expect(
+      transitionOpenCodeCompactionControl(ended, "compaction.complete.error", {
+        errorCode: "COMPACTION_TIMEOUT",
+        errorMessage: COMPACTION_TERMINAL_ERROR_MESSAGE,
+      }),
+    ).toEqual(ended);
+  });
+});
 
 describe("OpenCodeClient event mapping", () => {
   test("defaults directory to process.cwd() for project-scoped agent resolution", () => {
@@ -28,345 +158,3918 @@ describe("OpenCodeClient event mapping", () => {
     expect(sessionStarts).toEqual(["ses_test_created"]);
   });
 
-  test("maps tool part updates using part.sessionID when properties.sessionID is absent", () => {
+  test("maps session.status idle payloads to session.idle", () => {
     const client = new OpenCodeClient();
-    const starts: Array<{ sessionId: string; toolName?: string; toolCallId?: string }> = [];
-    const completes: Array<{ sessionId: string; toolName?: string; toolCallId?: string }> = [];
+    const idles: string[] = [];
 
-    const unsubStart = client.on("tool.start", (event) => {
-      const data = event.data as { toolName?: string; toolCallId?: string };
-      starts.push({
-        sessionId: event.sessionId,
-        toolName: data.toolName,
-        toolCallId: data.toolCallId,
-      });
-    });
-    const unsubComplete = client.on("tool.complete", (event) => {
-      const data = event.data as { toolName?: string; toolCallId?: string };
-      completes.push({
-        sessionId: event.sessionId,
-        toolName: data.toolName,
-        toolCallId: data.toolCallId,
-      });
+    const unsubscribe = client.on("session.idle", (event) => {
+      idles.push(event.sessionId);
     });
 
-    const basePart = {
-      id: "prt_tool_1",
-      callID: "call_tool_1",
-      sessionID: "ses_part_session",
-      messageID: "msg_1",
-      type: "tool",
-      tool: "bash",
-    };
-
     (client as unknown as { handleSdkEvent: (event: Record<string, unknown>) => void }).handleSdkEvent({
-      type: "message.part.updated",
+      type: "session.status",
       properties: {
-        part: {
-          ...basePart,
-          state: {
-            status: "running",
-            input: { command: "pwd" },
-          },
-        },
+        sessionID: "ses_status_string",
+        status: "idle",
       },
     });
 
     (client as unknown as { handleSdkEvent: (event: Record<string, unknown>) => void }).handleSdkEvent({
-      type: "message.part.updated",
+      type: "session.status",
       properties: {
-        part: {
-          ...basePart,
-          state: {
-            status: "completed",
-            input: { command: "pwd" },
-            output: "/tmp",
-          },
-        },
+        info: { id: "ses_status_structured" },
+        status: { type: "idle" },
       },
     });
 
-    unsubStart();
-    unsubComplete();
+    unsubscribe();
 
-    expect(starts).toEqual([
-      {
-        sessionId: "ses_part_session",
-        toolName: "bash",
-        toolCallId: "call_tool_1",
-      },
-    ]);
-    expect(completes).toEqual([
-      {
-        sessionId: "ses_part_session",
-        toolName: "bash",
-        toolCallId: "call_tool_1",
-      },
-    ]);
+    expect(idles).toEqual(["ses_status_string", "ses_status_structured"]);
   });
 
-  test("maps subtask parts to subagent.start with agent name and task", () => {
+  test("maps session.idle info.id payloads to session.idle", () => {
     const client = new OpenCodeClient();
-    const starts: Array<{
-      sessionId: string;
-      subagentId?: string;
-      subagentType?: string;
-      task?: string;
-    }> = [];
+    const idles: string[] = [];
 
-    const unsubStart = client.on("subagent.start", (event) => {
-      const data = event.data as {
-        subagentId?: string;
-        subagentType?: string;
-        task?: string;
-      };
-      starts.push({
-        sessionId: event.sessionId,
-        subagentId: data.subagentId,
-        subagentType: data.subagentType,
-        task: data.task,
-      });
+    const unsubscribe = client.on("session.idle", (event) => {
+      idles.push(event.sessionId);
     });
 
     (client as unknown as { handleSdkEvent: (event: Record<string, unknown>) => void }).handleSdkEvent({
-      type: "message.part.updated",
+      type: "session.idle",
       properties: {
-        part: {
-          id: "subtask_1",
-          sessionID: "ses_parent",
-          messageID: "msg_1",
-          type: "subtask",
-          prompt: "Research Rust TUI stacks",
-          description: "Research the best technology stacks in Rust for terminal games",
-          agent: "codebase-online-researcher",
-        },
+        info: { id: "ses_idle_info" },
       },
     });
 
-    unsubStart();
+    unsubscribe();
 
-    expect(starts).toEqual([
-      {
-        sessionId: "ses_parent",
-        subagentId: "subtask_1",
-        subagentType: "codebase-online-researcher",
-        task: "Research the best technology stacks in Rust for terminal games",
-      },
-    ]);
+    expect(idles).toEqual(["ses_idle_info"]);
   });
 
-  test("emits thinking source identity for reasoning deltas", () => {
+  test("emitEvent dispatch remains synchronous", () => {
     const client = new OpenCodeClient();
-    const deltas: Array<{
-      sessionId: string;
-      delta?: string;
-      contentType?: string;
-      thinkingSourceKey?: string;
-    }> = [];
+    const order: string[] = [];
 
-    const unsubscribe = client.on("message.delta", (event) => {
-      const data = event.data as {
-        delta?: string;
-        contentType?: string;
-        thinkingSourceKey?: string;
-      };
-      deltas.push({
-        sessionId: event.sessionId,
-        delta: data.delta,
-        contentType: data.contentType,
-        thinkingSourceKey: data.thinkingSourceKey,
-      });
+    const unsubscribe = client.on("message.delta", () => {
+      order.push("handler");
     });
 
-    (client as unknown as { handleSdkEvent: (event: Record<string, unknown>) => void }).handleSdkEvent({
-      type: "message.part.updated",
-      properties: {
-        part: {
-          id: "reasoning_part_1",
-          sessionID: "ses_reasoning",
-          messageID: "msg_reasoning",
-          type: "reasoning",
-        },
-        delta: "inspect constraints",
-      },
-    });
+    order.push("before");
+    (client as unknown as {
+      emitEvent: (type: "message.delta", sessionId: string, data: Record<string, unknown>) => void;
+    }).emitEvent("message.delta", "ses_sync_dispatch", { delta: "hello" });
+    order.push("after");
 
     unsubscribe();
 
-    expect(deltas).toEqual([
-      {
-        sessionId: "ses_reasoning",
-        delta: "inspect constraints",
-        contentType: "reasoning",
-        thinkingSourceKey: "reasoning_part_1",
-      },
-    ]);
+    expect(order).toEqual(["before", "handler", "after"]);
   });
 
-  test("maps agent part to subagent.start with toolCallId from callID", () => {
+  test("emitEvent isolates handler errors and continues dispatch", () => {
     const client = new OpenCodeClient();
-    const starts: Array<{
-      sessionId: string;
-      subagentId?: string;
-      subagentType?: string;
-      toolCallId?: string;
-    }> = [];
+    const order: string[] = [];
+    const originalConsoleError = console.error;
+    const consoleErrors: unknown[][] = [];
 
-    const unsubStart = client.on("subagent.start", (event) => {
-      const data = event.data as {
-        subagentId?: string;
-        subagentType?: string;
-        toolCallId?: string;
-      };
-      starts.push({
-        sessionId: event.sessionId,
-        subagentId: data.subagentId,
-        subagentType: data.subagentType,
-        toolCallId: data.toolCallId,
-      });
-    });
+    (console as unknown as { error: (...args: unknown[]) => void }).error = (...args: unknown[]) => {
+      consoleErrors.push(args);
+    };
 
-    (client as unknown as { handleSdkEvent: (event: Record<string, unknown>) => void }).handleSdkEvent({
-      type: "message.part.updated",
-      properties: {
-        part: {
-          id: "agent-1",
-          sessionID: "ses_agent",
-          messageID: "msg_1",
-          type: "agent",
-          name: "explorer",
-          callID: "call-123",
-        },
-      },
+    const unsubscribeThrowingHandler = client.on("message.delta", () => {
+      order.push("throwing-handler");
+      throw new Error("handler failure");
+    });
+    const unsubscribeSecondHandler = client.on("message.delta", () => {
+      order.push("second-handler");
     });
 
-    unsubStart();
+    try {
+      (client as unknown as {
+        emitEvent: (type: "message.delta", sessionId: string, data: Record<string, unknown>) => void;
+      }).emitEvent("message.delta", "ses_sync_dispatch", { delta: "hello" });
+    } finally {
+      unsubscribeThrowingHandler();
+      unsubscribeSecondHandler();
+      (console as unknown as { error: (...args: unknown[]) => void }).error = originalConsoleError;
+    }
 
-    expect(starts).toEqual([
-      {
-        sessionId: "ses_agent",
-        subagentId: "agent-1",
-        subagentType: "explorer",
-        toolCallId: "call-123",
-      },
-    ]);
+    expect(order).toEqual(["throwing-handler", "second-handler"]);
+    expect(consoleErrors).toHaveLength(1);
+    expect(String(consoleErrors[0]?.[0] ?? "")).toContain("Error in event handler for message.delta:");
   });
 
-  test("maps agent part to subagent.start with toolCallId fallback to id when callID is missing", () => {
+  test("on() unsubscribe removes empty handler buckets", () => {
     const client = new OpenCodeClient();
-    const starts: Array<{
-      sessionId: string;
-      subagentId?: string;
-      subagentType?: string;
-      toolCallId?: string;
-    }> = [];
+    const unsubscribe = client.on("session.idle", () => {});
 
-    const unsubStart = client.on("subagent.start", (event) => {
-      const data = event.data as {
-        subagentId?: string;
-        subagentType?: string;
-        toolCallId?: string;
-      };
-      starts.push({
-        sessionId: event.sessionId,
-        subagentId: data.subagentId,
-        subagentType: data.subagentType,
-        toolCallId: data.toolCallId,
-      });
+    unsubscribe();
+
+    const eventHandlers = (client as unknown as {
+      eventHandlers: Map<string, Set<unknown>>;
+    }).eventHandlers;
+
+    expect(eventHandlers.has("session.idle")).toBe(false);
+  });
+
+  test("processEventStream filters non-lifecycle events for inactive sessions", async () => {
+    const client = new OpenCodeClient();
+    const deltas: string[] = [];
+    const starts: string[] = [];
+
+    const unsubDelta = client.on("message.delta", (event) => {
+      const data = event.data as { delta?: string };
+      if (typeof data.delta === "string") {
+        deltas.push(data.delta);
+      }
+    });
+    const unsubStart = client.on("session.start", (event) => {
+      starts.push(event.sessionId);
     });
 
-    (client as unknown as { handleSdkEvent: (event: Record<string, unknown>) => void }).handleSdkEvent({
-      type: "message.part.updated",
-      properties: {
-        part: {
-          id: "agent-2",
-          sessionID: "ses_agent_no_callid",
-          messageID: "msg_2",
-          type: "agent",
-          name: "worker",
-          // callID is missing/undefined
+    (client as unknown as { registerActiveSession: (sessionId: string) => void })
+      .registerActiveSession("ses_active");
+
+    const stream = (async function* (): AsyncGenerator<unknown, void, unknown> {
+      yield {
+        type: "message.part.delta",
+        properties: {
+          sessionID: "ses_inactive",
+          delta: "inactive output",
         },
-      },
-    });
+      };
+      yield {
+        type: "message.part.delta",
+        properties: {
+          sessionID: "ses_active",
+          delta: "active output",
+        },
+      };
+      yield {
+        type: "session.created",
+        properties: {
+          info: { id: "ses_created" },
+        },
+      };
+      yield {
+        type: "message.part.delta",
+        properties: {
+          sessionID: "ses_created",
+          delta: "created output",
+        },
+      };
+    })();
+
+    await (client as unknown as {
+      processEventStream: (
+        eventStream: AsyncGenerator<unknown, void, unknown>,
+        watchdogAbort: AbortController,
+      ) => Promise<void>;
+    }).processEventStream(stream, new AbortController());
 
+    unsubDelta();
     unsubStart();
 
-    expect(starts).toEqual([
+    expect(deltas).toEqual(["active output", "created output"]);
+    expect(starts).toContain("ses_created");
+  });
+
+  test("processEventStream allows lifecycle events for inactive sessions", async () => {
+    const client = new OpenCodeClient();
+    const idles: string[] = [];
+    const deltas: string[] = [];
+
+    const unsubIdle = client.on("session.idle", (event) => {
+      idles.push(event.sessionId);
+    });
+    const unsubDelta = client.on("message.delta", (event) => {
+      const data = event.data as { delta?: string };
+      if (typeof data.delta === "string") {
+        deltas.push(data.delta);
+      }
+    });
+
+    const stream = (async function* (): AsyncGenerator<unknown, void, unknown> {
+      yield {
+        type: "session.status",
+        properties: {
+          sessionID: "ses_lifecycle_only",
+          status: "idle",
+        },
+      };
+      yield {
+        type: "message.part.delta",
+        properties: {
+          sessionID: "ses_filtered_only",
+          delta: "should be filtered",
+        },
+      };
+    })();
+
+    await (client as unknown as {
+      processEventStream: (
+        eventStream: AsyncGenerator<unknown, void, unknown>,
+        watchdogAbort: AbortController,
+      ) => Promise<void>;
+    }).processEventStream(stream, new AbortController());
+
+    unsubIdle();
+    unsubDelta();
+
+    expect(idles).toEqual(["ses_lifecycle_only"]);
+    expect(deltas).toEqual([]);
+  });
+
+  test("processEventStream allows unknown child message.part.updated events in single-session mode", async () => {
+    const client = new OpenCodeClient();
+    const starts: Array<{ subagentId?: string; subagentSessionId?: string }> = [];
+    const toolStarts: Array<{ sessionId: string; toolName?: string }> = [];
+
+    const unsubStart = client.on("subagent.start", (event) => {
+      const data = event.data as { subagentId?: string; subagentSessionId?: string };
+      starts.push({ subagentId: data.subagentId, subagentSessionId: data.subagentSessionId });
+    });
+    const unsubTool = client.on("tool.start", (event) => {
+      const data = event.data as { toolName?: string };
+      toolStarts.push({ sessionId: event.sessionId, toolName: data.toolName });
+    });
+
+    (client as unknown as { registerActiveSession: (sessionId: string) => void })
+      .registerActiveSession("ses_parent");
+    (client as unknown as { currentSessionId: string | null }).currentSessionId = "ses_parent";
+
+    const stream = (async function* (): AsyncGenerator<unknown, void, unknown> {
+      yield {
+        type: "message.updated",
+        properties: {
+          info: {
+            id: "msg_parent",
+            sessionID: "ses_parent",
+            role: "assistant",
+          },
+        },
+      };
+      yield {
+        type: "message.part.updated",
+        properties: {
+          sessionID: "ses_parent",
+          part: {
+            id: "agent_1",
+            sessionID: "ses_parent",
+            messageID: "msg_parent",
+            type: "agent",
+            name: "worker",
+          },
+        },
+      };
+      // Child tool arrives without envelope sessionID (only part.sessionID).
+      // This must be allowed through filtering so child discovery can run.
+      yield {
+        type: "message.part.updated",
+        properties: {
+          part: {
+            id: "tool_child_1",
+            sessionID: "ses_child",
+            messageID: "msg_child_1",
+            type: "tool",
+            tool: "Read",
+            state: {
+              status: "pending",
+              input: { filePath: "src/ui/chat.tsx" },
+            },
+          },
+        },
+      };
+    })();
+
+    await (client as unknown as {
+      processEventStream: (
+        eventStream: AsyncGenerator<unknown, void, unknown>,
+        watchdogAbort: AbortController,
+      ) => Promise<void>;
+    }).processEventStream(stream, new AbortController());
+
+    unsubStart();
+    unsubTool();
+
+    expect(starts).toHaveLength(2);
+    expect(starts[0]).toEqual({ subagentId: "agent_1", subagentSessionId: undefined });
+    expect(starts[1]).toEqual({ subagentId: "agent_1", subagentSessionId: "ses_child" });
+    expect(toolStarts).toContainEqual({ sessionId: "ses_child", toolName: "Read" });
+  });
+
+  test("processEventStream allows unknown child message.part.updated events in parallel-session mode", async () => {
+    const client = new OpenCodeClient();
+    const starts: Array<{ subagentId?: string; subagentSessionId?: string }> = [];
+    const toolStarts: Array<{ sessionId: string; toolName?: string }> = [];
+
+    const unsubStart = client.on("subagent.start", (event) => {
+      const data = event.data as { subagentId?: string; subagentSessionId?: string };
+      starts.push({ subagentId: data.subagentId, subagentSessionId: data.subagentSessionId });
+    });
+    const unsubTool = client.on("tool.start", (event) => {
+      const data = event.data as { toolName?: string };
+      toolStarts.push({ sessionId: event.sessionId, toolName: data.toolName });
+    });
+
+    (client as unknown as { registerActiveSession: (sessionId: string) => void })
+      .registerActiveSession("ses_parent");
+    (client as unknown as { registerActiveSession: (sessionId: string) => void })
+      .registerActiveSession("ses_other_active");
+    (client as unknown as { currentSessionId: string | null }).currentSessionId = "ses_parent";
+
+    const stream = (async function* (): AsyncGenerator<unknown, void, unknown> {
+      yield {
+        type: "message.updated",
+        properties: {
+          info: {
+            id: "msg_parent_parallel",
+            sessionID: "ses_parent",
+            role: "assistant",
+          },
+        },
+      };
+      yield {
+        type: "message.part.updated",
+        properties: {
+          sessionID: "ses_parent",
+          part: {
+            id: "agent_parallel_1",
+            sessionID: "ses_parent",
+            messageID: "msg_parent_parallel",
+            type: "agent",
+            name: "worker",
+          },
+        },
+      };
+      // Child tool arrives without envelope sessionID while another session
+      // is also active. We still need to process this for child discovery.
+      yield {
+        type: "message.part.updated",
+        properties: {
+          part: {
+            id: "tool_parallel_child_1",
+            sessionID: "ses_parallel_child",
+            messageID: "msg_parallel_child_1",
+            type: "tool",
+            tool: "Glob",
+            state: {
+              status: "pending",
+              input: { path: "src/**/*.tsx" },
+            },
+          },
+        },
+      };
+    })();
+
+    await (client as unknown as {
+      processEventStream: (
+        eventStream: AsyncGenerator<unknown, void, unknown>,
+        watchdogAbort: AbortController,
+      ) => Promise<void>;
+    }).processEventStream(stream, new AbortController());
+
+    unsubStart();
+    unsubTool();
+
+    expect(starts).toHaveLength(2);
+    expect(starts[0]).toEqual({ subagentId: "agent_parallel_1", subagentSessionId: undefined });
+    expect(starts[1]).toEqual({ subagentId: "agent_parallel_1", subagentSessionId: "ses_parallel_child" });
+    expect(toolStarts).toContainEqual({ sessionId: "ses_parallel_child", toolName: "Glob" });
+  });
+
+  test("session.deleted unregisters active sessions for subsequent SSE filtering", async () => {
+    const client = new OpenCodeClient();
+    const deltas: string[] = [];
+
+    const unsubDelta = client.on("message.delta", (event) => {
+      const data = event.data as { delta?: string };
+      if (typeof data.delta === "string") {
+        deltas.push(data.delta);
+      }
+    });
+
+    (client as unknown as { registerActiveSession: (sessionId: string) => void })
+      .registerActiveSession("ses_deleted");
+
+    const stream = (async function* (): AsyncGenerator<unknown, void, unknown> {
+      yield {
+        type: "session.deleted",
+        properties: {
+          sessionID: "ses_deleted",
+        },
+      };
+      yield {
+        type: "message.part.delta",
+        properties: {
+          sessionID: "ses_deleted",
+          delta: "should be dropped",
+        },
+      };
+    })();
+
+    await (client as unknown as {
+      processEventStream: (
+        eventStream: AsyncGenerator<unknown, void, unknown>,
+        watchdogAbort: AbortController,
+      ) => Promise<void>;
+    }).processEventStream(stream, new AbortController());
+
+    unsubDelta();
+
+    expect(deltas).toEqual([]);
+  });
+
+  test("processEventStream emits diagnostics usage marker for filtered SSE events", async () => {
+    const client = new OpenCodeClient();
+    const usageMarkers: Array<Record<string, unknown>> = [];
+
+    const unsubUsage = client.on("usage", (event) => {
+      usageMarkers.push(event.data as Record<string, unknown>);
+    });
+
+    const stream = (async function* (): AsyncGenerator<unknown, void, unknown> {
+      yield {
+        type: "message.part.delta",
+        properties: {
+          sessionID: "ses_filtered_marker",
+          delta: "drop me",
+        },
+      };
+    })();
+
+    await (client as unknown as {
+      processEventStream: (
+        eventStream: AsyncGenerator<unknown, void, unknown>,
+        watchdogAbort: AbortController,
+      ) => Promise<void>;
+    }).processEventStream(stream, new AbortController());
+
+    unsubUsage();
+
+    expect(usageMarkers).toContainEqual({
+      provider: "opencode",
+      marker: "opencode.sse.diagnostics",
+      counter: "sse.event.filtered.count",
+      value: 1,
+    });
+  });
+
+  test("processEventStream emits diagnostics usage marker when watchdog abort stops stream", async () => {
+    const client = new OpenCodeClient();
+    const usageMarkers: Array<Record<string, unknown>> = [];
+
+    const unsubUsage = client.on("usage", (event) => {
+      usageMarkers.push(event.data as Record<string, unknown>);
+    });
+
+    const watchdogAbort = new AbortController();
+    watchdogAbort.abort();
+
+    const stream = (async function* (): AsyncGenerator<unknown, void, unknown> {
+      yield {
+        type: "session.created",
+        properties: {
+          info: { id: "ses_abort_marker" },
+        },
+      };
+    })();
+
+    await (client as unknown as {
+      processEventStream: (
+        eventStream: AsyncGenerator<unknown, void, unknown>,
+        watchdogAbort: AbortController,
+      ) => Promise<void>;
+    }).processEventStream(stream, watchdogAbort);
+
+    unsubUsage();
+
+    expect(usageMarkers).toContainEqual({
+      provider: "opencode",
+      marker: "opencode.sse.diagnostics",
+      counter: "sse.abort.watchdog.count",
+      value: 1,
+    });
+  });
+
+  test("processEventStream emits diagnostics usage marker when global abort stops stream", async () => {
+    const client = new OpenCodeClient();
+    const usageMarkers: Array<Record<string, unknown>> = [];
+    const globalAbort = new AbortController();
+    globalAbort.abort();
+
+    const unsubUsage = client.on("usage", (event) => {
+      usageMarkers.push(event.data as Record<string, unknown>);
+    });
+
+    (client as unknown as { eventSubscriptionController: AbortController | null })
+      .eventSubscriptionController = globalAbort;
+
+    const stream = (async function* (): AsyncGenerator<unknown, void, unknown> {
+      yield {
+        type: "session.created",
+        properties: {
+          info: { id: "ses_global_abort_marker" },
+        },
+      };
+    })();
+
+    await (client as unknown as {
+      processEventStream: (
+        eventStream: AsyncGenerator<unknown, void, unknown>,
+        watchdogAbort: AbortController,
+      ) => Promise<void>;
+    }).processEventStream(stream, new AbortController());
+
+    unsubUsage();
+
+    expect(usageMarkers).toContainEqual({
+      provider: "opencode",
+      marker: "opencode.sse.diagnostics",
+      counter: "sse.abort.global.count",
+      value: 1,
+    });
+  });
+
+  test("processEventStream emits watchdog-timeout diagnostics marker", async () => {
+    const client = new OpenCodeClient();
+    const usageMarkers: Array<Record<string, unknown>> = [];
+
+    const unsubUsage = client.on("usage", (event) => {
+      usageMarkers.push(event.data as Record<string, unknown>);
+    });
+
+    const originalSetTimeout = globalThis.setTimeout;
+    const originalClearTimeout = globalThis.clearTimeout;
+    const originalDateNow = Date.now;
+    let nowCall = 0;
+
+    (Date as unknown as { now: () => number }).now = () => {
+      nowCall += 1;
+      return nowCall <= 2 ? 0 : 15_001;
+    };
+    (globalThis as unknown as { setTimeout: (...args: unknown[]) => unknown }).setTimeout = (
+      callback: unknown,
+    ) => {
+      if (typeof callback === "function") {
+        (callback as () => void)();
+      }
+      return 1;
+    };
+    (globalThis as unknown as { clearTimeout: (...args: unknown[]) => void }).clearTimeout =
+      () => {};
+
+    try {
+      const stream = (async function* (): AsyncGenerator<unknown, void, unknown> {})();
+      await (client as unknown as {
+        processEventStream: (
+          eventStream: AsyncGenerator<unknown, void, unknown>,
+          watchdogAbort: AbortController,
+        ) => Promise<void>;
+      }).processEventStream(stream, new AbortController());
+    } finally {
+      (Date as unknown as { now: () => number }).now = originalDateNow;
+      (
+        globalThis as unknown as { setTimeout: (...args: unknown[]) => unknown }
+      ).setTimeout = originalSetTimeout as unknown as (...args: unknown[]) => unknown;
+      (
+        globalThis as unknown as { clearTimeout: (...args: unknown[]) => void }
+      ).clearTimeout = originalClearTimeout as unknown as (...args: unknown[]) => void;
+      unsubUsage();
+    }
+
+    expect(usageMarkers).toContainEqual({
+      provider: "opencode",
+      marker: "opencode.sse.diagnostics",
+      counter: "sse.watchdog.timeout.count",
+      value: 1,
+    });
+  });
+
+  test("summarize emits compaction start and context_compacted idle", async () => {
+    const client = new OpenCodeClient();
+    const compactions: Array<{ phase?: string; success?: boolean; error?: string }> = [];
+    const idles: string[] = [];
+    const sessionId = "ses_summarize_success";
+
+    (client as unknown as {
+      resolveModelContextWindow: (modelHint?: string) => Promise<number>;
+    }).resolveModelContextWindow = async () => 200_000;
+
+    (client as unknown as {
+      sdkClient: {
+        session: {
+          summarize: (params: Record<string, unknown>) => Promise<void>;
+          messages: (params: Record<string, unknown>) => Promise<{
+            data?: Array<{ info: { role: string } }>;
+          }>;
+        };
+      };
+    }).sdkClient = {
+      session: {
+        summarize: async () => {},
+        messages: async () => ({ data: [] }),
+      },
+    };
+
+    const unsubCompaction = client.on("session.compaction", (event) => {
+      const data = event.data as { phase?: string; success?: boolean; error?: string };
+      compactions.push({
+        phase: data.phase,
+        success: data.success,
+        error: data.error,
+      });
+    });
+    const unsubIdle = client.on("session.idle", (event) => {
+      const data = event.data as { reason?: string };
+      idles.push(data.reason ?? "");
+    });
+
+    const session = await (client as unknown as {
+      wrapSession: (sid: string, config: Record<string, unknown>) => Promise<{
+        summarize: () => Promise<void>;
+      }>;
+    }).wrapSession(sessionId, {});
+
+    await session.summarize();
+
+    unsubCompaction();
+    unsubIdle();
+
+    expect(compactions).toEqual([{ phase: "start", success: undefined, error: undefined }]);
+    expect(idles).toContain("context_compacted");
+  });
+
+  test("summarize emits truncation from pre/post compaction token deltas", async () => {
+    const client = new OpenCodeClient();
+    const truncations: Array<{ tokenLimit?: number; tokensRemoved?: number; messagesRemoved?: number }> = [];
+    const sessionId = "ses_summarize_truncation";
+
+    (client as unknown as {
+      resolveModelContextWindow: (modelHint?: string) => Promise<number>;
+    }).resolveModelContextWindow = async () => 200_000;
+
+    (client as unknown as {
+      sdkClient: {
+        session: {
+          prompt: (params: Record<string, unknown>) => Promise<{
+            data?: {
+              info?: { tokens?: { input?: number; output?: number } };
+              parts?: Array<Record<string, unknown>>;
+            };
+          }>;
+          summarize: (params: Record<string, unknown>) => Promise<void>;
+          messages: (params: Record<string, unknown>) => Promise<{
+            data?: Array<{ info: { role: string; tokens?: { input?: number; output?: number } } }>;
+          }>;
+        };
+      };
+    }).sdkClient = {
+      session: {
+        prompt: async () => ({
+          data: {
+            info: {
+              tokens: { input: 1_200, output: 300 },
+            },
+            parts: [{ type: "text", text: "seed" }],
+          },
+        }),
+        summarize: async () => {},
+        messages: async () => ({
+          data: [
+            {
+              info: {
+                role: "assistant",
+                tokens: { input: 400, output: 100 },
+              },
+            },
+          ],
+        }),
+      },
+    };
+
+    const unsubTruncation = client.on("session.truncation", (event) => {
+      const data = event.data as {
+        tokenLimit?: number;
+        tokensRemoved?: number;
+        messagesRemoved?: number;
+      };
+      truncations.push({
+        tokenLimit: data.tokenLimit,
+        tokensRemoved: data.tokensRemoved,
+        messagesRemoved: data.messagesRemoved,
+      });
+    });
+
+    const session = await (client as unknown as {
+      wrapSession: (sid: string, config: Record<string, unknown>) => Promise<{
+        send: (message: string) => Promise<{ type: string; content: unknown }>;
+        summarize: () => Promise<void>;
+      }>;
+    }).wrapSession(sessionId, {});
+
+    await session.send("seed usage state");
+    await session.summarize();
+
+    unsubTruncation();
+
+    expect(truncations).toEqual([
       {
-        sessionId: "ses_agent_no_callid",
-        subagentId: "agent-2",
-        subagentType: "worker",
-        toolCallId: "agent-2", // Falls back to id
+        tokenLimit: 200_000,
+        tokensRemoved: 1_000,
+        messagesRemoved: 0,
+      },
+    ]);
+  });
+
+  test("summarize emits compaction failure and rethrows summarize errors", async () => {
+    resetRuntimeParityMetrics();
+    const client = new OpenCodeClient();
+    const compactions: Array<{ phase?: string; success?: boolean; error?: string }> = [];
+    const sessionErrors: Array<{ error?: string; code?: string }> = [];
+    const idles: string[] = [];
+    const sessionId = "ses_summarize_failure";
+    const summarizeError = new Error("summarize failed");
+
+    (client as unknown as {
+      resolveModelContextWindow: (modelHint?: string) => Promise<number>;
+    }).resolveModelContextWindow = async () => 200_000;
+
+    (client as unknown as {
+      sdkClient: {
+        session: {
+          summarize: (params: Record<string, unknown>) => Promise<void>;
+          messages: (params: Record<string, unknown>) => Promise<{
+            data?: Array<{ info: { role: string } }>;
+          }>;
+        };
+      };
+    }).sdkClient = {
+      session: {
+        summarize: async () => {
+          throw summarizeError;
+        },
+        messages: async () => ({ data: [] }),
+      },
+    };
+
+    const unsubCompaction = client.on("session.compaction", (event) => {
+      const data = event.data as { phase?: string; success?: boolean; error?: string };
+      compactions.push({
+        phase: data.phase,
+        success: data.success,
+        error: data.error,
+      });
+    });
+    const unsubIdle = client.on("session.idle", (event) => {
+      const data = event.data as { reason?: string };
+      idles.push(data.reason ?? "");
+    });
+    const unsubSessionError = client.on("session.error", (event) => {
+      const data = event.data as { error?: string; code?: string };
+      sessionErrors.push({
+        error: typeof data.error === "string" ? data.error : undefined,
+        code: data.code,
+      });
+    });
+
+    const session = await (client as unknown as {
+      wrapSession: (sid: string, config: Record<string, unknown>) => Promise<{
+        summarize: () => Promise<void>;
+      }>;
+    }).wrapSession(sessionId, {});
+
+    await expect(session.summarize()).rejects.toThrow(COMPACTION_TERMINAL_ERROR_MESSAGE);
+
+    unsubCompaction();
+    unsubIdle();
+    unsubSessionError();
+
+    expect(compactions).toEqual([
+      { phase: "start", success: undefined, error: undefined },
+      { phase: "complete", success: false, error: COMPACTION_TERMINAL_ERROR_MESSAGE },
+    ]);
+    expect(sessionErrors).toEqual([
+      { error: COMPACTION_TERMINAL_ERROR_MESSAGE, code: "COMPACTION_FAILED" },
+    ]);
+    expect(idles).toEqual([]);
+    const metrics = getRuntimeParityMetricsSnapshot();
+    expect(metrics.counters["workflow.runtime.parity.compaction_timeout_terminated_total{code=COMPACTION_FAILED,provider=opencode}"]).toBe(1);
+    expect(metrics.counters["workflow.runtime.parity.turn_terminated_due_to_contract_error_total{code=COMPACTION_FAILED,provider=opencode,reason=compaction_terminal_error}"]).toBe(1);
+  });
+
+  test("summarize emits terminal timeout error when compaction exceeds bounded wait", async () => {
+    resetRuntimeParityMetrics();
+    const client = new OpenCodeClient();
+    const compactions: Array<{ phase?: string; success?: boolean; error?: string }> = [];
+    const sessionErrors: Array<{ error?: string; code?: string }> = [];
+    const sessionId = "ses_summarize_timeout";
+
+    (client as unknown as {
+      resolveModelContextWindow: (modelHint?: string) => Promise<number>;
+    }).resolveModelContextWindow = async () => 200_000;
+
+    (client as unknown as {
+      sdkClient: {
+        session: {
+          summarize: (params: Record<string, unknown>) => Promise<void>;
+          messages: (params: Record<string, unknown>) => Promise<{
+            data?: Array<{ info: { role: string } }>;
+          }>;
+        };
+      };
+    }).sdkClient = {
+      session: {
+        summarize: async () => new Promise<void>(() => {}),
+        messages: async () => ({ data: [] }),
+      },
+    };
+
+    const unsubCompaction = client.on("session.compaction", (event) => {
+      const data = event.data as { phase?: string; success?: boolean; error?: string };
+      compactions.push({
+        phase: data.phase,
+        success: data.success,
+        error: data.error,
+      });
+    });
+    const unsubSessionError = client.on("session.error", (event) => {
+      const data = event.data as { error?: string; code?: string };
+      sessionErrors.push({
+        error: typeof data.error === "string" ? data.error : undefined,
+        code: data.code,
+      });
+    });
+
+    const originalSetTimeout = globalThis.setTimeout;
+    const originalClearTimeout = globalThis.clearTimeout;
+    (globalThis as unknown as { setTimeout: (...args: unknown[]) => unknown }).setTimeout = (
+      callback: unknown,
+    ) => {
+      if (typeof callback === "function") {
+        (callback as () => void)();
+      }
+      return 1;
+    };
+    (globalThis as unknown as { clearTimeout: (...args: unknown[]) => void }).clearTimeout = () => {};
+
+    try {
+      const session = await (client as unknown as {
+        wrapSession: (sid: string, config: Record<string, unknown>) => Promise<{
+          summarize: () => Promise<void>;
+        }>;
+      }).wrapSession(sessionId, {});
+
+      await expect(session.summarize()).rejects.toThrow(COMPACTION_TERMINAL_ERROR_MESSAGE);
+    } finally {
+      (
+        globalThis as unknown as { setTimeout: (...args: unknown[]) => unknown }
+      ).setTimeout = originalSetTimeout as unknown as (...args: unknown[]) => unknown;
+      (
+        globalThis as unknown as { clearTimeout: (...args: unknown[]) => void }
+      ).clearTimeout = originalClearTimeout as unknown as (...args: unknown[]) => void;
+      unsubCompaction();
+      unsubSessionError();
+    }
+
+    expect(compactions).toEqual([
+      { phase: "start", success: undefined, error: undefined },
+      { phase: "complete", success: false, error: COMPACTION_TERMINAL_ERROR_MESSAGE },
+    ]);
+    expect(sessionErrors).toEqual([
+      { error: COMPACTION_TERMINAL_ERROR_MESSAGE, code: "COMPACTION_TIMEOUT" },
+    ]);
+    const metrics = getRuntimeParityMetricsSnapshot();
+    expect(metrics.counters["workflow.runtime.parity.compaction_timeout_terminated_total{code=COMPACTION_TIMEOUT,provider=opencode}"]).toBe(1);
+    expect(metrics.counters["workflow.runtime.parity.turn_terminated_due_to_contract_error_total{code=COMPACTION_TIMEOUT,provider=opencode,reason=compaction_terminal_error}"]).toBe(1);
+  });
+
+  test("dedupes duplicate compaction complete events after summarize recovery", async () => {
+    const client = new OpenCodeClient();
+    const sessionId = "ses_compaction_dedupe";
+    const compactionPhases: string[] = [];
+
+    (client as unknown as {
+      resolveModelContextWindow: (modelHint?: string) => Promise<number>;
+    }).resolveModelContextWindow = async () => 200_000;
+
+    (client as unknown as {
+      sdkClient: {
+        session: {
+          summarize: (params: Record<string, unknown>) => Promise<void>;
+          messages: (params: Record<string, unknown>) => Promise<{ data?: Array<{ info: { role: string } }> }>;
+        };
+      };
+    }).sdkClient = {
+      session: {
+        summarize: async () => {},
+        messages: async () => ({ data: [] }),
+      },
+    };
+
+    const unsubscribe = client.on("session.compaction", (event) => {
+      const data = event.data as { phase?: string };
+      compactionPhases.push(data.phase ?? "");
+    });
+
+    const session = await (client as unknown as {
+      wrapSession: (sid: string, config: Record<string, unknown>) => Promise<{
+        summarize: () => Promise<void>;
+      }>;
+    }).wrapSession(sessionId, {});
+
+    await session.summarize();
+
+    const handle = (client as unknown as {
+      handleSdkEvent: (event: Record<string, unknown>) => void;
+    }).handleSdkEvent.bind(client);
+    handle({
+      type: "session.compacted",
+      properties: { sessionID: sessionId },
+    });
+    handle({
+      type: "session.compacted",
+      properties: { sessionID: sessionId },
+    });
+
+    unsubscribe();
+
+    expect(compactionPhases.filter((phase) => phase === "complete")).toHaveLength(1);
+  });
+
+  test("does not leave pending compaction completion stale when compacted arrives before summarize resolves", async () => {
+    const client = new OpenCodeClient();
+    const sessionId = "ses_compaction_pending_race";
+    const compactionPhases: string[] = [];
+
+    (client as unknown as {
+      resolveModelContextWindow: (modelHint?: string) => Promise<number>;
+    }).resolveModelContextWindow = async () => 200_000;
+
+    const handle = (client as unknown as {
+      handleSdkEvent: (event: Record<string, unknown>) => void;
+    }).handleSdkEvent.bind(client);
+
+    let releaseSummarize!: () => void;
+    const summarizeGate = new Promise<void>((resolve) => {
+      releaseSummarize = resolve;
+    });
+
+    (client as unknown as {
+      sdkClient: {
+        session: {
+          summarize: (params: Record<string, unknown>) => Promise<void>;
+          messages: (params: Record<string, unknown>) => Promise<{ data?: Array<{ info: { role: string } }> }>;
+        };
+      };
+    }).sdkClient = {
+      session: {
+        summarize: async () => {
+          handle({
+            type: "session.compacted",
+            properties: { sessionID: sessionId },
+          });
+          await summarizeGate;
+        },
+        messages: async () => ({ data: [] }),
+      },
+    };
+
+    const unsubscribe = client.on("session.compaction", (event) => {
+      const data = event.data as { phase?: string };
+      compactionPhases.push(data.phase ?? "");
+    });
+
+    const session = await (client as unknown as {
+      wrapSession: (sid: string, config: Record<string, unknown>) => Promise<{
+        summarize: () => Promise<void>;
+      }>;
+    }).wrapSession(sessionId, {});
+
+    const summarizePromise = session.summarize();
+    releaseSummarize();
+    await summarizePromise;
+
+    handle({
+      type: "session.compacted",
+      properties: { sessionID: sessionId },
+    });
+
+    unsubscribe();
+
+    expect(compactionPhases.filter((phase) => phase === "complete")).toHaveLength(1);
+  });
+
+  test("emits compaction complete when no pending compaction recovery exists", async () => {
+    const client = new OpenCodeClient();
+    const sessionId = "ses_compaction_emit_without_pending";
+    const compactionPhases: string[] = [];
+
+    (client as unknown as {
+      resolveModelContextWindow: (modelHint?: string) => Promise<number>;
+    }).resolveModelContextWindow = async () => 200_000;
+
+    (client as unknown as {
+      sdkClient: {
+        session: {
+          summarize: (params: Record<string, unknown>) => Promise<void>;
+          messages: (params: Record<string, unknown>) => Promise<{ data?: Array<{ info: { role: string } }> }>;
+        };
+      };
+    }).sdkClient = {
+      session: {
+        summarize: async () => {},
+        messages: async () => ({ data: [] }),
+      },
+    };
+
+    const unsubscribe = client.on("session.compaction", (event) => {
+      const data = event.data as { phase?: string };
+      compactionPhases.push(data.phase ?? "");
+    });
+
+    await (client as unknown as {
+      wrapSession: (sid: string, config: Record<string, unknown>) => Promise<{
+        summarize: () => Promise<void>;
+      }>;
+    }).wrapSession(sessionId, {});
+
+    (client as unknown as {
+      handleSdkEvent: (event: Record<string, unknown>) => void;
+    }).handleSdkEvent({
+      type: "session.compacted",
+      properties: { sessionID: sessionId },
+    });
+
+    unsubscribe();
+
+    expect(compactionPhases.filter((phase) => phase === "complete")).toHaveLength(1);
+  });
+
+  test("stream resolves even when no terminal idle event arrives", async () => {
+    const client = new OpenCodeClient();
+    const sessionId = "ses_stream_no_idle";
+
+    // Avoid provider metadata lookups in wrapSession().
+    (client as unknown as {
+      resolveModelContextWindow: (modelHint?: string) => Promise<number>;
+    }).resolveModelContextWindow = async () => 200_000;
+
+    const handle = (event: Record<string, unknown>) =>
+      (client as unknown as { handleSdkEvent: (e: Record<string, unknown>) => void }).handleSdkEvent(event);
+
+    (client as unknown as {
+      sdkClient: {
+        session: {
+          promptAsync: (params: Record<string, unknown>) => Promise<void>;
+        };
+      };
+    }).sdkClient = {
+      session: {
+        promptAsync: async () => {
+          // Fire tool event during prompt, then idle after a delay
+          handle({
+            type: "message.part.updated",
+            properties: {
+              sessionID: sessionId,
+              part: {
+                id: "task_tool_1",
+                type: "tool",
+                tool: "task",
+                state: {
+                  status: "running",
+                  input: { description: "Investigate hang" },
+                },
+              },
+            },
+          });
+          setTimeout(() => {
+            handle({
+              type: "session.status",
+              properties: {
+                sessionID: sessionId,
+                status: "idle",
+              },
+            });
+          }, 50);
+        },
+      },
+    };
+
+    const session = await (client as unknown as {
+      wrapSession: (sid: string, config: Record<string, unknown>) => Promise<{
+        stream: (message: string, options?: { agent?: string }) => AsyncIterable<{
+          type: string;
+          content: unknown;
+        }>;
+      }>;
+    }).wrapSession(sessionId, {});
+
+    const chunks: Array<{ type: string; content: unknown }> = [];
+    const consumePromise = (async () => {
+      for await (const chunk of session.stream("run worker", { agent: "worker" })) {
+        chunks.push({ type: chunk.type, content: chunk.content });
+      }
+    })();
+
+    let timeoutId: ReturnType<typeof setTimeout> | undefined;
+    try {
+      await Promise.race([
+        consumePromise,
+        new Promise<never>((_, reject) => {
+          timeoutId = setTimeout(() => reject(new Error("stream timed out")), 2500);
+        }),
+      ]);
+    } finally {
+      if (timeoutId) clearTimeout(timeoutId);
+    }
+
+    expect(chunks.some((chunk) => chunk.type === "tool_use")).toBe(true);
+  });
+
+  test("stream drains late tool events when idle arrives before prompt settles", async () => {
+    const client = new OpenCodeClient();
+    const sessionId = "ses_idle_before_prompt_settle";
+
+    (client as unknown as {
+      resolveModelContextWindow: (modelHint?: string) => Promise<number>;
+    }).resolveModelContextWindow = async () => 200_000;
+
+    const handle = (event: Record<string, unknown>) =>
+      (client as unknown as { handleSdkEvent: (e: Record<string, unknown>) => void }).handleSdkEvent(event);
+
+    (client as unknown as {
+      sdkClient: {
+        session: {
+          promptAsync: (params: Record<string, unknown>) => Promise<void>;
+        };
+      };
+    }).sdkClient = {
+      session: {
+        promptAsync: async () => {
+          // promptAsync returns immediately; idle and tool events arrive via SSE
+        },
+      },
+    };
+
+    const session = await (client as unknown as {
+      wrapSession: (sid: string, config: Record<string, unknown>) => Promise<{
+        stream: (message: string, options?: { agent?: string }) => AsyncIterable<{
+          type: string;
+          content: unknown;
+        }>;
+      }>;
+    }).wrapSession(sessionId, {});
+
+    const chunks: Array<{ type: string; content: unknown }> = [];
+    const consumePromise = (async () => {
+      for await (const chunk of session.stream("run task", { agent: "worker" })) {
+        chunks.push({ type: chunk.type, content: chunk.content });
+      }
+    })();
+
+    const idleTimer = setTimeout(() => {
+      handle({
+        type: "session.status",
+        properties: {
+          sessionID: sessionId,
+          status: "idle",
+        },
+      });
+    }, 20);
+
+    const toolTimer = setTimeout(() => {
+      handle({
+        type: "message.part.updated",
+        properties: {
+          sessionID: sessionId,
+          part: {
+            id: "tool_late_1",
+            callID: "call_late_1",
+            sessionID: sessionId,
+            messageID: "msg_late_1",
+            type: "tool",
+            tool: "Read",
+            state: {
+              status: "pending",
+              input: { filePath: "src/index.ts" },
+            },
+          },
+        },
+      });
+    }, 10);
+
+    let timeoutId: ReturnType<typeof setTimeout> | undefined;
+    try {
+      await Promise.race([
+        consumePromise,
+        new Promise<never>((_, reject) => {
+          timeoutId = setTimeout(() => reject(new Error("stream did not complete")), 2000);
+        }),
+      ]);
+    } finally {
+      clearTimeout(idleTimer);
+      clearTimeout(toolTimer);
+      if (timeoutId) clearTimeout(timeoutId);
+    }
+
+    expect(chunks.some((chunk) => {
+      if (chunk.type !== "tool_use") return false;
+      const content = chunk.content as { name?: string };
+      return content.name === "Read";
+    })).toBe(true);
+  });
+
+  test("stream keeps child-session progress isolated when currentSessionId points to another session", async () => {
+    const client = new OpenCodeClient();
+
+    (client as unknown as {
+      resolveModelContextWindow: (modelHint?: string) => Promise<number>;
+    }).resolveModelContextWindow = async () => 200_000;
+
+    const handle = (event: Record<string, unknown>) =>
+      (client as unknown as { handleSdkEvent: (e: Record<string, unknown>) => void }).handleSdkEvent(event);
+
+    (client as unknown as {
+      sdkClient: {
+        session: {
+          promptAsync: (params: Record<string, unknown>) => Promise<void>;
+        };
+      };
+    }).sdkClient = {
+      session: {
+        promptAsync: async (params) => {
+          const sid = params.sessionID as string;
+          const childSid = `${sid}_child`;
+
+          handle({
+            type: "message.part.updated",
+            properties: {
+              sessionID: sid,
+              part: {
+                id: `agent_${sid}`,
+                sessionID: sid,
+                messageID: `msg_${sid}_1`,
+                type: "agent",
+                name: "worker",
+              },
+            },
+          });
+
+          handle({
+            type: "message.part.updated",
+            properties: {
+              sessionID: sid,
+              part: {
+                id: `tool_${sid}`,
+                sessionID: childSid,
+                messageID: `msg_${sid}_2`,
+                type: "tool",
+                tool: "Read",
+                callID: `call_${sid}`,
+                state: {
+                  status: "pending",
+                  input: { filePath: "src/index.ts" },
+                },
+              },
+            },
+          });
+
+          // Fire the idle event after a short delay
+          setTimeout(() => {
+            handle({
+              type: "session.status",
+              properties: {
+                sessionID: sid,
+                status: "idle",
+              },
+            });
+          }, 50);
+        },
+      },
+    };
+
+    const session = await (client as unknown as {
+      wrapSession: (sid: string, config: Record<string, unknown>) => Promise<{
+        stream: (message: string, options?: { agent?: string }) => AsyncIterable<{
+          type: string;
+          content: unknown;
+        }>;
+      }>;
+    }).wrapSession("ses_A", {});
+
+    // Simulate another parallel session being marked current.
+    (client as unknown as { currentSessionId: string | null }).currentSessionId = "ses_B";
+
+    const chunks: Array<{ type: string; content: unknown }> = [];
+    for await (const chunk of session.stream("run task", { agent: "worker" })) {
+      chunks.push({ type: chunk.type, content: chunk.content });
+    }
+
+    expect(chunks.some((chunk) => {
+      if (chunk.type !== "tool_use") return false;
+      const content = chunk.content as { name?: string };
+      return content.name === "Read";
+    })).toBe(true);
+  });
+
+  test("stream completes when terminal session event arrives before prompt resolves", async () => {
+    const client = new OpenCodeClient();
+    const sessionId = "ses_terminal_before_prompt";
+
+    (client as unknown as {
+      resolveModelContextWindow: (modelHint?: string) => Promise<number>;
+    }).resolveModelContextWindow = async () => 200_000;
+
+    (client as unknown as {
+      sdkClient: {
+        session: {
+          promptAsync: (params: Record<string, unknown>) => Promise<void>;
+        };
+      };
+    }).sdkClient = {
+      session: {
+        promptAsync: async () => {
+          // promptAsync returns immediately
+        },
+      },
+    };
+
+    const session = await (client as unknown as {
+      wrapSession: (sid: string, config: Record<string, unknown>) => Promise<{
+        stream: (message: string, options?: { agent?: string }) => AsyncIterable<{
+          type: string;
+          content: unknown;
+        }>;
+      }>;
+    }).wrapSession(sessionId, {});
+
+    const consumePromise = (async () => {
+      for await (const _chunk of session.stream("run task", { agent: "worker" })) {
+        // No-op: this regression only verifies completion.
+      }
+    })();
+
+    setTimeout(() => {
+      (client as unknown as { handleSdkEvent: (event: Record<string, unknown>) => void }).handleSdkEvent({
+        type: "session.status",
+        properties: {
+          sessionID: sessionId,
+          status: "idle",
+        },
+      });
+    }, 20);
+
+    let timeoutId: ReturnType<typeof setTimeout> | undefined;
+    try {
+      await Promise.race([
+        consumePromise,
+        new Promise<never>((_, reject) => {
+          timeoutId = setTimeout(() => reject(new Error("stream did not complete")), 1000);
+        }),
+      ]);
+    } finally {
+      if (timeoutId) clearTimeout(timeoutId);
+    }
+  });
+
+  test("stream yields SSE deltas before promptAsync settles", async () => {
+    const client = new OpenCodeClient();
+    const sessionId = "ses_delta_before_prompt_settle";
+
+    (client as unknown as {
+      resolveModelContextWindow: (modelHint?: string) => Promise<number>;
+    }).resolveModelContextWindow = async () => 200_000;
+
+    const handle = (event: Record<string, unknown>) =>
+      (client as unknown as { handleSdkEvent: (e: Record<string, unknown>) => void }).handleSdkEvent(event);
+
+    (client as unknown as {
+      sdkClient: {
+        session: {
+          promptAsync: (params: Record<string, unknown>) => Promise<void>;
+        };
+      };
+    }).sdkClient = {
+      session: {
+        promptAsync: async () => {
+          setTimeout(() => {
+            handle({
+              type: "message.part.delta",
+              properties: {
+                sessionID: sessionId,
+                delta: "early streamed chunk",
+              },
+            });
+          }, 15);
+
+          setTimeout(() => {
+            handle({
+              type: "session.status",
+              properties: {
+                sessionID: sessionId,
+                status: "idle",
+              },
+            });
+          }, 30);
+
+          // Simulate a promptAsync call that does not settle immediately.
+          await new Promise<void>((resolve) => setTimeout(resolve, 300));
+        },
+      },
+    };
+
+    const session = await (client as unknown as {
+      wrapSession: (sid: string, config: Record<string, unknown>) => Promise<{
+        stream: (message: string, options?: { agent?: string }) => AsyncIterable<{
+          type: string;
+          content: unknown;
+        }>;
+      }>;
+    }).wrapSession(sessionId, {});
+
+    const chunks: Array<{ type: string; content: unknown }> = [];
+    const streamStartAt = Date.now();
+    let firstChunkAt: number | null = null;
+    let firstChunkResolve: (() => void) | undefined;
+    const firstChunkPromise = new Promise<void>((resolve) => {
+      firstChunkResolve = () => resolve();
+    });
+
+    const consumePromise = (async () => {
+      for await (const chunk of session.stream("plain prompt")) {
+        if (firstChunkAt === null) {
+          firstChunkAt = Date.now();
+          firstChunkResolve?.();
+        }
+        chunks.push({ type: chunk.type, content: chunk.content });
+      }
+    })();
+
+    let firstChunkTimeoutId: ReturnType<typeof setTimeout> | undefined;
+    try {
+      await Promise.race([
+        firstChunkPromise,
+        new Promise<never>((_, reject) => {
+          firstChunkTimeoutId = setTimeout(() => reject(new Error("first chunk did not arrive in time")), 150);
+        }),
+      ]);
+    } finally {
+      if (firstChunkTimeoutId) clearTimeout(firstChunkTimeoutId);
+    }
+
+    expect(firstChunkAt).not.toBeNull();
+    expect((firstChunkAt ?? 0) - streamStartAt).toBeLessThan(150);
+
+    let streamTimeoutId: ReturnType<typeof setTimeout> | undefined;
+    try {
+      await Promise.race([
+        consumePromise,
+        new Promise<never>((_, reject) => {
+          streamTimeoutId = setTimeout(() => reject(new Error("stream did not complete")), 2000);
+        }),
+      ]);
+    } finally {
+      if (streamTimeoutId) clearTimeout(streamTimeoutId);
+    }
+
+    expect(chunks.some((chunk) => chunk.type === "text" && chunk.content === "early streamed chunk")).toBe(true);
+  });
+
+  test("non-subagent stream completes on idle and yields text from SSE deltas", async () => {
+    const client = new OpenCodeClient();
+    const sessionId = "ses_non_subagent_idle";
+
+    (client as unknown as {
+      resolveModelContextWindow: (modelHint?: string) => Promise<number>;
+    }).resolveModelContextWindow = async () => 200_000;
+
+    const handle = (event: Record<string, unknown>) =>
+      (client as unknown as { handleSdkEvent: (e: Record<string, unknown>) => void }).handleSdkEvent(event);
+
+    (client as unknown as {
+      sdkClient: {
+        session: {
+          promptAsync: (params: Record<string, unknown>) => Promise<void>;
+        };
+      };
+    }).sdkClient = {
+      session: {
+        promptAsync: async () => {
+          // promptAsync returns immediately; text and idle arrive via SSE
+        },
+      },
+    };
+
+    const session = await (client as unknown as {
+      wrapSession: (sid: string, config: Record<string, unknown>) => Promise<{
+        stream: (message: string, options?: { agent?: string }) => AsyncIterable<{
+          type: string;
+          content: unknown;
+        }>;
+      }>;
+    }).wrapSession(sessionId, {});
+
+    const chunks: Array<{ type: string; content: unknown }> = [];
+    const consumePromise = (async () => {
+      for await (const chunk of session.stream("plain prompt")) {
+        chunks.push({ type: chunk.type, content: chunk.content });
+      }
+    })();
+
+    // Emit a text delta via SSE
+    setTimeout(() => {
+      handle({
+        type: "message.part.delta",
+        properties: {
+          sessionID: sessionId,
+          delta: "final response",
+        },
+      });
+    }, 20);
+
+    // Then emit idle to signal completion
+    setTimeout(() => {
+      handle({
+        type: "session.status",
+        properties: {
+          sessionID: sessionId,
+          status: "idle",
+        },
+      });
+    }, 80);
+
+    let timeoutId: ReturnType<typeof setTimeout> | undefined;
+    try {
+      await Promise.race([
+        consumePromise,
+        new Promise<never>((_, reject) => {
+          timeoutId = setTimeout(() => reject(new Error("stream did not finish")), 1000);
+        }),
+      ]);
+    } finally {
+      if (timeoutId) clearTimeout(timeoutId);
+    }
+
+    expect(
+      chunks.some((chunk) => chunk.type === "text" && chunk.content === "final response")
+    ).toBe(true);
+  });
+
+  test("maps tool part updates using part.sessionID when properties.sessionID is absent", () => {
+    const client = new OpenCodeClient();
+    const starts: Array<{ sessionId: string; toolName?: string; toolCallId?: string }> = [];
+    const completes: Array<{ sessionId: string; toolName?: string; toolCallId?: string }> = [];
+
+    const unsubStart = client.on("tool.start", (event) => {
+      const data = event.data as { toolName?: string; toolCallId?: string };
+      starts.push({
+        sessionId: event.sessionId,
+        toolName: data.toolName,
+        toolCallId: data.toolCallId,
+      });
+    });
+    const unsubComplete = client.on("tool.complete", (event) => {
+      const data = event.data as { toolName?: string; toolCallId?: string };
+      completes.push({
+        sessionId: event.sessionId,
+        toolName: data.toolName,
+        toolCallId: data.toolCallId,
+      });
+    });
+
+    const basePart = {
+      id: "prt_tool_1",
+      callID: "call_tool_1",
+      sessionID: "ses_part_session",
+      messageID: "msg_1",
+      type: "tool",
+      tool: "bash",
+    };
+
+    (client as unknown as { handleSdkEvent: (event: Record<string, unknown>) => void }).handleSdkEvent({
+      type: "message.part.updated",
+      properties: {
+        part: {
+          ...basePart,
+          state: {
+            status: "running",
+            input: { command: "pwd" },
+          },
+        },
+      },
+    });
+
+    (client as unknown as { handleSdkEvent: (event: Record<string, unknown>) => void }).handleSdkEvent({
+      type: "message.part.updated",
+      properties: {
+        part: {
+          ...basePart,
+          state: {
+            status: "completed",
+            input: { command: "pwd" },
+            output: "/tmp",
+          },
+        },
+      },
+    });
+
+    unsubStart();
+    unsubComplete();
+
+    expect(starts).toEqual([
+      {
+        sessionId: "ses_part_session",
+        toolName: "bash",
+        toolCallId: "call_tool_1",
+      },
+    ]);
+    expect(completes).toEqual([
+      {
+        sessionId: "ses_part_session",
+        toolName: "bash",
+        toolCallId: "call_tool_1",
+      },
+    ]);
+  });
+
+  test("emits task tool lifecycle for parent-session task parts", () => {
+    const client = new OpenCodeClient();
+    (client as unknown as { currentSessionId: string | null }).currentSessionId = "ses_parent";
+
+    const starts: Array<{ toolName?: string; toolCallId?: string }> = [];
+    const completes: Array<{ toolName?: string; toolCallId?: string }> = [];
+
+    const unsubStart = client.on("tool.start", (event) => {
+      const data = event.data as { toolName?: string; toolCallId?: string };
+      starts.push({ toolName: data.toolName, toolCallId: data.toolCallId });
+    });
+
+    const unsubComplete = client.on("tool.complete", (event) => {
+      const data = event.data as { toolName?: string; toolCallId?: string };
+      completes.push({ toolName: data.toolName, toolCallId: data.toolCallId });
+    });
+
+    (client as unknown as { handleSdkEvent: (event: Record<string, unknown>) => void }).handleSdkEvent({
+      type: "message.part.updated",
+      properties: {
+        part: {
+          id: "task_tool_parent",
+          callID: "call_task_parent",
+          sessionID: "ses_parent",
+          messageID: "msg_task_1",
+          type: "tool",
+          tool: "task",
+          state: {
+            status: "running",
+            input: {
+              subagent_type: "debugger",
+              description: "debug stream ordering",
+            },
+          },
+        },
+      },
+    });
+
+    (client as unknown as { handleSdkEvent: (event: Record<string, unknown>) => void }).handleSdkEvent({
+      type: "message.part.updated",
+      properties: {
+        part: {
+          id: "task_tool_parent",
+          callID: "call_task_parent",
+          sessionID: "ses_parent",
+          messageID: "msg_task_1",
+          type: "tool",
+          tool: "task",
+          state: {
+            status: "completed",
+            input: {
+              subagent_type: "debugger",
+              description: "debug stream ordering",
+            },
+            output: "done",
+          },
+        },
+      },
+    });
+
+    unsubStart();
+    unsubComplete();
+
+    expect(starts).toEqual([{ toolName: "task", toolCallId: "call_task_parent" }]);
+    expect(completes).toEqual([{ toolName: "task", toolCallId: "call_task_parent" }]);
+  });
+
+  test("includes task tool metadata on tool.start for parent-session task parts", () => {
+    const client = new OpenCodeClient();
+    (client as unknown as { currentSessionId: string | null }).currentSessionId = "ses_parent";
+
+    const starts: Array<{ toolName?: string; toolCallId?: string; toolMetadata?: Record<string, unknown> }> = [];
+
+    const unsubStart = client.on("tool.start", (event) => {
+      const data = event.data as {
+        toolName?: string;
+        toolCallId?: string;
+        toolMetadata?: Record<string, unknown>;
+      };
+      starts.push({
+        toolName: data.toolName,
+        toolCallId: data.toolCallId,
+        toolMetadata: data.toolMetadata,
+      });
+    });
+
+    (client as unknown as { handleSdkEvent: (event: Record<string, unknown>) => void }).handleSdkEvent({
+      type: "message.part.updated",
+      properties: {
+        part: {
+          id: "task_tool_parent_meta",
+          callID: "call_task_parent_meta",
+          sessionID: "ses_parent",
+          messageID: "msg_task_meta_1",
+          type: "tool",
+          tool: "task",
+          state: {
+            status: "running",
+            input: {
+              subagent_type: "debugger",
+              description: "debug stream ordering",
+            },
+            metadata: {
+              sessionId: "ses_child_meta_1",
+              model: { providerID: "openai", modelID: "gpt-5.3-codex-high" },
+            },
+          },
+        },
+      },
+    });
+
+    unsubStart();
+
+    expect(starts).toHaveLength(1);
+    expect(starts[0]).toEqual({
+      toolName: "task",
+      toolCallId: "call_task_parent_meta",
+      toolMetadata: {
+        sessionId: "ses_child_meta_1",
+        model: { providerID: "openai", modelID: "gpt-5.3-codex-high" },
+      },
+    });
+  });
+
+  test("does not synthesize subagent.start from parent-session task tool parts", () => {
+    const client = new OpenCodeClient();
+    (client as unknown as { currentSessionId: string | null }).currentSessionId = "ses_parent";
+
+    const lifecycle: string[] = [];
+
+    const unsubSubagentStart = client.on("subagent.start", (event) => {
+      const data = event.data as { toolCallId?: string };
+      if (data.toolCallId === "task_tool_ordering") {
+        lifecycle.push("subagent.start");
+      }
+    });
+
+    const unsubToolStart = client.on("tool.start", (event) => {
+      const data = event.data as { toolName?: string };
+      if (data.toolName === "task") {
+        lifecycle.push("tool.start");
+      }
+    });
+
+    (client as unknown as { handleSdkEvent: (event: Record<string, unknown>) => void }).handleSdkEvent({
+      type: "message.part.updated",
+      properties: {
+        part: {
+          id: "task_tool_ordering",
+          callID: "call_task_ordering",
+          sessionID: "ses_parent",
+          messageID: "msg_task_ordering",
+          type: "tool",
+          tool: "task",
+          state: {
+            status: "running",
+            input: {
+              subagent_type: "debugger",
+              description: "fix ordering",
+            },
+          },
+        },
+      },
+    });
+
+    unsubSubagentStart();
+    unsubToolStart();
+
+    expect(lifecycle).toEqual(["tool.start"]);
+  });
+
+  test("maps subtask parts to subagent.start with agent name and task", () => {
+    const client = new OpenCodeClient();
+    const starts: Array<{
+      sessionId: string;
+      subagentId?: string;
+      subagentType?: string;
+      task?: string;
+    }> = [];
+
+    const unsubStart = client.on("subagent.start", (event) => {
+      const data = event.data as {
+        subagentId?: string;
+        subagentType?: string;
+        task?: string;
+      };
+      starts.push({
+        sessionId: event.sessionId,
+        subagentId: data.subagentId,
+        subagentType: data.subagentType,
+        task: data.task,
+      });
+    });
+
+    (client as unknown as { handleSdkEvent: (event: Record<string, unknown>) => void }).handleSdkEvent({
+      type: "message.part.updated",
+      properties: {
+        part: {
+          id: "subtask_1",
+          sessionID: "ses_parent",
+          messageID: "msg_1",
+          type: "subtask",
+          prompt: "Research Rust TUI stacks",
+          description: "Research the best technology stacks in Rust for terminal games",
+          agent: "codebase-online-researcher",
+        },
+      },
+    });
+
+    unsubStart();
+
+    expect(starts).toEqual([
+      {
+        sessionId: "ses_parent",
+        subagentId: "subtask_1",
+        subagentType: "codebase-online-researcher",
+        task: "Research the best technology stacks in Rust for terminal games",
+      },
+    ]);
+  });
+
+  test("emits thinking source identity for reasoning deltas", () => {
+    const client = new OpenCodeClient();
+    const deltas: Array<{
+      sessionId: string;
+      delta?: string;
+      contentType?: string;
+      thinkingSourceKey?: string;
+    }> = [];
+
+    const unsubscribe = client.on("message.delta", (event) => {
+      const data = event.data as {
+        delta?: string;
+        contentType?: string;
+        thinkingSourceKey?: string;
+      };
+      deltas.push({
+        sessionId: event.sessionId,
+        delta: data.delta,
+        contentType: data.contentType,
+        thinkingSourceKey: data.thinkingSourceKey,
+      });
+    });
+
+    // First, register the reasoning part via message.part.updated
+    (client as unknown as { handleSdkEvent: (event: Record<string, unknown>) => void }).handleSdkEvent({
+      type: "message.part.updated",
+      properties: {
+        part: {
+          id: "reasoning_part_1",
+          sessionID: "ses_reasoning",
+          messageID: "msg_reasoning",
+          type: "reasoning",
+        },
+      },
+    });
+
+    // Then, send the delta via message.part.delta (v2)
+    (client as unknown as { handleSdkEvent: (event: Record<string, unknown>) => void }).handleSdkEvent({
+      type: "message.part.delta",
+      properties: {
+        partID: "reasoning_part_1",
+        sessionID: "ses_reasoning",
+        delta: "inspect constraints",
+      },
+    });
+
+    unsubscribe();
+
+    expect(deltas).toEqual([
+      {
+        sessionId: "ses_reasoning",
+        delta: "inspect constraints",
+        contentType: "thinking",
+        thinkingSourceKey: "reasoning_part_1",
+      },
+    ]);
+  });
+
+  test("maps agent part to subagent.start with toolCallId from callID", () => {
+    const client = new OpenCodeClient();
+    const starts: Array<{
+      sessionId: string;
+      subagentId?: string;
+      subagentType?: string;
+      toolCallId?: string;
+    }> = [];
+
+    const unsubStart = client.on("subagent.start", (event) => {
+      const data = event.data as {
+        subagentId?: string;
+        subagentType?: string;
+        toolCallId?: string;
+      };
+      starts.push({
+        sessionId: event.sessionId,
+        subagentId: data.subagentId,
+        subagentType: data.subagentType,
+        toolCallId: data.toolCallId,
+      });
+    });
+
+    (client as unknown as { handleSdkEvent: (event: Record<string, unknown>) => void }).handleSdkEvent({
+      type: "message.part.updated",
+      properties: {
+        part: {
+          id: "agent-1",
+          sessionID: "ses_agent",
+          messageID: "msg_1",
+          type: "agent",
+          name: "explorer",
+          callID: "call-123",
+        },
+      },
+    });
+
+    unsubStart();
+
+    expect(starts).toEqual([
+      {
+        sessionId: "ses_agent",
+        subagentId: "agent-1",
+        subagentType: "explorer",
+        toolCallId: "call-123",
+      },
+    ]);
+  });
+
+  test("maps agent part to subagent.start with toolCallId fallback to id when callID is missing", () => {
+    const client = new OpenCodeClient();
+    const starts: Array<{
+      sessionId: string;
+      subagentId?: string;
+      subagentType?: string;
+      toolCallId?: string;
+    }> = [];
+
+    const unsubStart = client.on("subagent.start", (event) => {
+      const data = event.data as {
+        subagentId?: string;
+        subagentType?: string;
+        toolCallId?: string;
+      };
+      starts.push({
+        sessionId: event.sessionId,
+        subagentId: data.subagentId,
+        subagentType: data.subagentType,
+        toolCallId: data.toolCallId,
+      });
+    });
+
+    (client as unknown as { handleSdkEvent: (event: Record<string, unknown>) => void }).handleSdkEvent({
+      type: "message.part.updated",
+      properties: {
+        part: {
+          id: "agent-2",
+          sessionID: "ses_agent_no_callid",
+          messageID: "msg_2",
+          type: "agent",
+          name: "worker",
+          // callID is missing/undefined
+        },
+      },
+    });
+
+    unsubStart();
+
+    expect(starts).toEqual([
+      {
+        sessionId: "ses_agent_no_callid",
+        subagentId: "agent-2",
+        subagentType: "worker",
+        toolCallId: "agent-2", // Falls back to id
+      },
+    ]);
+  });
+
+  test("uses preceding task tool part id as correlation for subsequent agent part", () => {
+    const client = new OpenCodeClient();
+    const starts: Array<{
+      subagentId?: string;
+      subagentType?: string;
+      toolCallId?: string;
+    }> = [];
+
+    const unsubStart = client.on("subagent.start", (event) => {
+      const data = event.data as {
+        subagentId?: string;
+        subagentType?: string;
+        toolCallId?: string;
+      };
+      starts.push({
+        subagentId: data.subagentId,
+        subagentType: data.subagentType,
+        toolCallId: data.toolCallId,
+      });
+    });
+
+    // Task tool part arrives first.
+    (client as unknown as { handleSdkEvent: (event: Record<string, unknown>) => void }).handleSdkEvent({
+      type: "message.part.updated",
+      properties: {
+        part: {
+          id: "task_tool_1",
+          callID: "task_call_1",
+          sessionID: "ses_parent",
+          messageID: "msg_1",
+          type: "tool",
+          tool: "task",
+          state: {
+            status: "pending",
+            input: {
+              subagent_type: "debugger",
+              description: "Inspect workflow stream issues",
+            },
+          },
+        },
+      },
+    });
+
+    // Agent part should carry correlation from the preceding task tool part.
+    (client as unknown as { handleSdkEvent: (event: Record<string, unknown>) => void }).handleSdkEvent({
+      type: "message.part.updated",
+      properties: {
+        part: {
+          id: "agent_from_task",
+          callID: "call_agent_1",
+          sessionID: "ses_parent",
+          messageID: "msg_2",
+          type: "agent",
+          name: "debugger",
+        },
+      },
+    });
+
+    unsubStart();
+
+    expect(starts).toEqual([
+      {
+        subagentId: "agent_from_task",
+        subagentType: "debugger",
+        toolCallId: "task_tool_1",
+      },
+    ]);
+  });
+
+  test("ignores user @mention agent parts to avoid orphan subagent rows", () => {
+    const client = new OpenCodeClient();
+    const starts: Array<{
+      subagentId?: string;
+      subagentType?: string;
+      toolCallId?: string;
+    }> = [];
+
+    const unsubStart = client.on("subagent.start", (event) => {
+      const data = event.data as {
+        subagentId?: string;
+        subagentType?: string;
+        toolCallId?: string;
+      };
+      starts.push({
+        subagentId: data.subagentId,
+        subagentType: data.subagentType,
+        toolCallId: data.toolCallId,
+      });
+    });
+
+    // OpenCode persists @agent mentions as USER AgentPart entries.
+    // These should not become subagent.start rows.
+    (client as unknown as { handleSdkEvent: (event: Record<string, unknown>) => void }).handleSdkEvent({
+      type: "message.updated",
+      properties: {
+        info: {
+          id: "msg_user_1",
+          sessionID: "ses_parent",
+          role: "user",
+        },
+      },
+    });
+    (client as unknown as { handleSdkEvent: (event: Record<string, unknown>) => void }).handleSdkEvent({
+      type: "message.part.updated",
+      properties: {
+        part: {
+          id: "user_agent_ref",
+          sessionID: "ses_parent",
+          messageID: "msg_user_1",
+          type: "agent",
+          name: "debugger",
+        },
+      },
+    });
+
+    // Task tool + assistant AgentPart represent the real sub-agent dispatch.
+    (client as unknown as { handleSdkEvent: (event: Record<string, unknown>) => void }).handleSdkEvent({
+      type: "message.part.updated",
+      properties: {
+        part: {
+          id: "task_tool_1",
+          callID: "task_call_1",
+          sessionID: "ses_parent",
+          messageID: "msg_asst_1",
+          type: "tool",
+          tool: "task",
+          state: {
+            status: "pending",
+            input: {
+              subagent_type: "debugger",
+              description: "Investigate initialization hang",
+            },
+          },
+        },
+      },
+    });
+    (client as unknown as { handleSdkEvent: (event: Record<string, unknown>) => void }).handleSdkEvent({
+      type: "message.updated",
+      properties: {
+        info: {
+          id: "msg_asst_1",
+          sessionID: "ses_parent",
+          role: "assistant",
+        },
+      },
+    });
+    (client as unknown as { handleSdkEvent: (event: Record<string, unknown>) => void }).handleSdkEvent({
+      type: "message.part.updated",
+      properties: {
+        part: {
+          id: "agent_from_task",
+          callID: "call_agent_1",
+          sessionID: "ses_parent",
+          messageID: "msg_asst_1",
+          type: "agent",
+          name: "debugger",
+        },
+      },
+    });
+
+    unsubStart();
+
+    expect(starts).toEqual([
+      {
+        subagentId: "agent_from_task",
+        subagentType: "debugger",
+        toolCallId: "task_tool_1",
+      },
+    ]);
+  });
+
+  test("does not leak completed task correlation into later agent parts", () => {
+    const client = new OpenCodeClient();
+    const starts: Array<{
+      subagentId?: string;
+      toolCallId?: string;
+    }> = [];
+
+    const unsubStart = client.on("subagent.start", (event) => {
+      const data = event.data as { subagentId?: string; toolCallId?: string };
+      starts.push({
+        subagentId: data.subagentId,
+        toolCallId: data.toolCallId,
+      });
+    });
+
+    // Task tool starts + completes without any agent/subtask part.
+    (client as unknown as { handleSdkEvent: (event: Record<string, unknown>) => void }).handleSdkEvent({
+      type: "message.part.updated",
+      properties: {
+        part: {
+          id: "task_tool_stale",
+          sessionID: "ses_parent",
+          messageID: "msg_1",
+          type: "tool",
+          tool: "task",
+          state: {
+            status: "running",
+            input: {
+              subagent_type: "debugger",
+              description: "initial task",
+            },
+          },
+        },
+      },
+    });
+    (client as unknown as { handleSdkEvent: (event: Record<string, unknown>) => void }).handleSdkEvent({
+      type: "message.part.updated",
+      properties: {
+        part: {
+          id: "task_tool_stale",
+          sessionID: "ses_parent",
+          messageID: "msg_1",
+          type: "tool",
+          tool: "task",
+          state: {
+            status: "completed",
+            input: {
+              subagent_type: "debugger",
+              description: "initial task",
+            },
+          },
+        },
+      },
+    });
+
+    // Later unrelated agent part should not consume stale task_tool_stale.
+    (client as unknown as { handleSdkEvent: (event: Record<string, unknown>) => void }).handleSdkEvent({
+      type: "message.part.updated",
+      properties: {
+        part: {
+          id: "agent_after_task",
+          callID: "call_after_task",
+          sessionID: "ses_parent",
+          messageID: "msg_2",
+          type: "agent",
+          name: "worker",
+        },
+      },
+    });
+
+    unsubStart();
+
+    expect(starts).toEqual([
+      {
+        subagentId: "agent_after_task",
+        toolCallId: "call_after_task",
+      },
+    ]);
+  });
+
+  test("emits tool.complete when tool status is completed but output is undefined", () => {
+    // Uses a non-Task tool to validate the generic tool.complete path.
+    const client = new OpenCodeClient();
+    const completes: Array<{
+      sessionId: string;
+      toolName?: string;
+      toolResult?: unknown;
+      success?: boolean;
+    }> = [];
+
+    const unsubComplete = client.on("tool.complete", (event) => {
+      const data = event.data as {
+        toolName?: string;
+        toolResult?: unknown;
+        success?: boolean;
+      };
+      completes.push({
+        sessionId: event.sessionId,
+        toolName: data.toolName,
+        toolResult: data.toolResult,
+        success: data.success,
+      });
+    });
+
+    (client as unknown as { handleSdkEvent: (event: Record<string, unknown>) => void }).handleSdkEvent({
+      type: "message.part.updated",
+      properties: {
+        part: {
+          id: "prt_bash_1",
+          callID: "call_bash_1",
+          sessionID: "ses_task",
+          messageID: "msg_1",
+          type: "tool",
+          tool: "bash",
+          state: {
+            status: "completed",
+            input: { command: "echo hello" },
+            // output is intentionally omitted (undefined)
+          },
+        },
+      },
+    });
+
+    unsubComplete();
+
+    expect(completes).toHaveLength(1);
+    expect(completes[0]!.sessionId).toBe("ses_task");
+    expect(completes[0]!.toolName).toBe("bash");
+    expect(completes[0]!.toolResult).toBeUndefined();
+    expect(completes[0]!.success).toBe(true);
+  });
+
+  test("maps step-finish part to subagent.complete for known sub-agents", () => {
+    const client = new OpenCodeClient();
+    const handleSdkEvent = (event: Record<string, unknown>) =>
+      (client as unknown as { handleSdkEvent: (e: Record<string, unknown>) => void }).handleSdkEvent(event);
+
+    const completes: Array<{
+      sessionId: string;
+      subagentId?: string;
+      success?: boolean;
+      result?: string;
+    }> = [];
+
+    const unsubComplete = client.on("subagent.complete", (event) => {
+      const data = event.data as {
+        subagentId?: string;
+        success?: boolean;
+        result?: string;
+      };
+      completes.push({
+        sessionId: event.sessionId,
+        subagentId: data.subagentId,
+        success: data.success,
+        result: data.result,
+      });
+    });
+
+    // Register the assistant message role so agent parts aren't
+    // filtered as user @mentions.
+    handleSdkEvent({
+      type: "message.updated",
+      properties: {
+        info: {
+          id: "msg_step",
+          sessionID: "ses_step",
+          role: "assistant",
+        },
+      },
+    });
+    handleSdkEvent({
+      type: "message.updated",
+      properties: {
+        info: {
+          id: "msg_step_2",
+          sessionID: "ses_step",
+          role: "assistant",
+        },
+      },
+    });
+
+    // Register sub-agents via agent parts BEFORE step-finish
+    handleSdkEvent({
+      type: "message.part.updated",
+      properties: {
+        part: {
+          id: "step-1",
+          sessionID: "ses_step",
+          messageID: "msg_step",
+          type: "agent",
+          name: "explorer",
+        },
+      },
+    });
+    handleSdkEvent({
+      type: "message.part.updated",
+      properties: {
+        part: {
+          id: "step-2",
+          sessionID: "ses_step",
+          messageID: "msg_step_2",
+          type: "agent",
+          name: "worker",
+        },
+      },
+    });
+
+    // Test successful completion
+    handleSdkEvent({
+      type: "message.part.updated",
+      properties: {
+        part: {
+          id: "step-1",
+          sessionID: "ses_step",
+          messageID: "msg_step",
+          type: "step-finish",
+          reason: "success",
+        },
+      },
+    });
+
+    // Test error completion
+    handleSdkEvent({
+      type: "message.part.updated",
+      properties: {
+        part: {
+          id: "step-2",
+          sessionID: "ses_step",
+          messageID: "msg_step_2",
+          type: "step-finish",
+          reason: "error",
+        },
+      },
+    });
+
+    unsubComplete();
+
+    expect(completes).toEqual([
+      {
+        sessionId: "ses_step",
+        subagentId: "step-1",
+        success: true,
+        result: "success",
+      },
+      {
+        sessionId: "ses_step",
+        subagentId: "step-2",
+        success: false,
+        result: "error",
+      },
+    ]);
+  });
+
+  test("ignores step-finish for main-turn completion (no prior sub-agent registration)", () => {
+    const client = new OpenCodeClient();
+    const handleSdkEvent = (event: Record<string, unknown>) =>
+      (client as unknown as { handleSdkEvent: (e: Record<string, unknown>) => void }).handleSdkEvent(event);
+
+    const completes: Array<{ subagentId?: string }> = [];
+
+    const unsubComplete = client.on("subagent.complete", (event) => {
+      const data = event.data as { subagentId?: string };
+      completes.push({ subagentId: data.subagentId });
+    });
+
+    // step-finish without any prior agent/subtask part registration
+    // (this is the main-turn completion scenario that caused MISSING_START)
+    handleSdkEvent({
+      type: "message.part.updated",
+      properties: {
+        part: {
+          id: "prt_main_turn_finish",
+          sessionID: "ses_main",
+          messageID: "msg_1",
+          type: "step-finish",
+          reason: "stop",
+        },
+      },
+    });
+
+    unsubComplete();
+
+    // No subagent.complete should be emitted for main-turn step-finish
+    expect(completes).toEqual([]);
+  });
+
+  test("requires a prior subagent.start before mapping step-finish to subagent.complete", () => {
+    const client = new OpenCodeClient();
+    const handleSdkEvent = (event: Record<string, unknown>) =>
+      (client as unknown as { handleSdkEvent: (e: Record<string, unknown>) => void }).handleSdkEvent(event);
+
+    const completes: Array<{ subagentId?: string }> = [];
+    const unsubComplete = client.on("subagent.complete", (event) => {
+      const data = event.data as { subagentId?: string };
+      completes.push({ subagentId: data.subagentId });
+    });
+
+    // Simulate stale internal correlation artifacts without a prior subagent.start.
+    (
+      client as unknown as {
+        subagentStateByParentSession: Map<
+          string,
+          {
+            pendingAgentParts: Array<{ partId: string; agentName: string }>;
+            childSessionToAgentPart: Map<string, string>;
+            startedSubagentIds: Set<string>;
+            subagentToolCounts: Map<string, number>;
+            pendingTaskToolPartIds: string[];
+            queuedTaskToolPartIds: Set<string>;
+          }
+        >;
+      }
+    ).subagentStateByParentSession.set("ses_main", {
+      pendingAgentParts: [{ partId: "prt_ghost_agent", agentName: "worker" }],
+      childSessionToAgentPart: new Map([["ses_child", "prt_ghost_agent"]]),
+      startedSubagentIds: new Set(),
+      subagentToolCounts: new Map([["prt_ghost_agent", 2]]),
+      pendingTaskToolPartIds: [],
+      queuedTaskToolPartIds: new Set(),
+    });
+
+    handleSdkEvent({
+      type: "message.part.updated",
+      properties: {
+        part: {
+          id: "prt_ghost_agent",
+          sessionID: "ses_main",
+          messageID: "msg_1",
+          type: "step-finish",
+          reason: "stop",
+        },
+      },
+    });
+
+    unsubComplete();
+
+    expect(completes).toEqual([]);
+  });
+
+  test("omits subagentSessionId from initial agent part subagent.start (parent session != child)", () => {
+    const client = new OpenCodeClient();
+    const starts: Array<{
+      sessionId: string;
+      subagentId?: string;
+      subagentSessionId?: string;
+    }> = [];
+
+    const unsubStart = client.on("subagent.start", (event) => {
+      const data = event.data as {
+        subagentId?: string;
+        subagentSessionId?: string;
+      };
+      starts.push({
+        sessionId: event.sessionId,
+        subagentId: data.subagentId,
+        subagentSessionId: data.subagentSessionId,
+      });
+    });
+
+    (client as unknown as { handleSdkEvent: (event: Record<string, unknown>) => void }).handleSdkEvent({
+      type: "message.part.updated",
+      properties: {
+        sessionID: "ses_parent",
+        part: {
+          id: "agent_1",
+          sessionID: "ses_parent",
+          messageID: "msg_1",
+          type: "agent",
+          name: "explore",
+          callID: "call_1",
+        },
+      },
+    });
+
+    unsubStart();
+
+    expect(starts).toHaveLength(1);
+    expect(starts[0]!.sessionId).toBe("ses_parent");
+    expect(starts[0]!.subagentId).toBe("agent_1");
+    // subagentSessionId is intentionally omitted from the initial emission
+    // because AgentPart.sessionID is the parent session, not the child.
+    expect(starts[0]!.subagentSessionId).toBeUndefined();
+  });
+
+  test("omits subagentSessionId from initial subtask part subagent.start", () => {
+    const client = new OpenCodeClient();
+    const starts: Array<{
+      sessionId: string;
+      subagentId?: string;
+      subagentSessionId?: string;
+    }> = [];
+
+    const unsubStart = client.on("subagent.start", (event) => {
+      const data = event.data as {
+        subagentId?: string;
+        subagentSessionId?: string;
+      };
+      starts.push({
+        sessionId: event.sessionId,
+        subagentId: data.subagentId,
+        subagentSessionId: data.subagentSessionId,
+      });
+    });
+
+    (client as unknown as { handleSdkEvent: (event: Record<string, unknown>) => void }).handleSdkEvent({
+      type: "message.part.updated",
+      properties: {
+        part: {
+          id: "subtask_2",
+          sessionID: "ses_subtask_session",
+          messageID: "msg_1",
+          type: "subtask",
+          prompt: "Find files",
+          description: "Locate relevant source files",
+          agent: "codebase-locator",
+        },
+      },
+    });
+
+    unsubStart();
+
+    expect(starts).toHaveLength(1);
+    expect(starts[0]!.subagentId).toBe("subtask_2");
+    // subagentSessionId intentionally omitted — see AgentPart comment.
+    expect(starts[0]!.subagentSessionId).toBeUndefined();
+  });
+
+  test("discovers child session from tool part and re-emits subagent.start with correct subagentSessionId", () => {
+    const client = new OpenCodeClient();
+    const handle = (event: Record<string, unknown>) =>
+      (client as unknown as { handleSdkEvent: (e: Record<string, unknown>) => void }).handleSdkEvent(event);
+
+    // Set currentSessionId so the client knows the parent session.
+    (client as unknown as { currentSessionId: string | null }).currentSessionId = "ses_parent";
+
+    const starts: Array<{
+      subagentId?: string;
+      subagentSessionId?: string;
+    }> = [];
+    const toolStarts: Array<{
+      sessionId: string;
+      toolName?: string;
+      parentAgentId?: string;
+    }> = [];
+
+    const unsubStart = client.on("subagent.start", (event) => {
+      const data = event.data as { subagentId?: string; subagentSessionId?: string };
+      starts.push({ subagentId: data.subagentId, subagentSessionId: data.subagentSessionId });
+    });
+    const unsubTool = client.on("tool.start", (event) => {
+      const data = event.data as { toolName?: string; parentAgentId?: string };
+      toolStarts.push({
+        sessionId: event.sessionId,
+        toolName: data.toolName,
+        parentAgentId: data.parentAgentId,
+      });
+    });
+
+    // 1. Agent part arrives (parent session)
+    handle({
+      type: "message.part.updated",
+      properties: {
+        sessionID: "ses_parent",
+        part: {
+          id: "agent_1",
+          sessionID: "ses_parent",
+          messageID: "msg_1",
+          type: "agent",
+          name: "explore",
+        },
+      },
+    });
+
+    // Initial subagent.start without subagentSessionId
+    expect(starts).toHaveLength(1);
+    expect(starts[0]!.subagentId).toBe("agent_1");
+    expect(starts[0]!.subagentSessionId).toBeUndefined();
+
+    // 2. First tool from child session arrives
+    handle({
+      type: "message.part.updated",
+      properties: {
+        // OpenCode can keep the parent session ID at the envelope level
+        // while the part itself belongs to the child session.
+        sessionID: "ses_parent",
+        part: {
+          id: "tool_child_1",
+          sessionID: "ses_child",
+          messageID: "msg_child_1",
+          type: "tool",
+          tool: "Read",
+          callID: "call_child_1",
+          state: { status: "pending", input: { file: "foo.ts" } },
+        },
+      },
+    });
+
+    unsubStart();
+    unsubTool();
+
+    // Re-emitted subagent.start with correct child session ID
+    expect(starts).toHaveLength(2);
+    expect(starts[1]!.subagentId).toBe("agent_1");
+    expect(starts[1]!.subagentSessionId).toBe("ses_child");
+
+    // Tool event emitted on the child session
+    expect(toolStarts).toHaveLength(1);
+    expect(toolStarts[0]!.sessionId).toBe("ses_child");
+    expect(toolStarts[0]!.toolName).toBe("Read");
+    expect(toolStarts[0]!.parentAgentId).toBe("agent_1");
+  });
+
+  test("routes child-session discovery to envelope parent session during parallel runs", () => {
+    const client = new OpenCodeClient();
+    const handle = (event: Record<string, unknown>) =>
+      (client as unknown as { handleSdkEvent: (e: Record<string, unknown>) => void }).handleSdkEvent(event);
+
+    // Simulate another session becoming "current" while session A events arrive.
+    (client as unknown as { currentSessionId: string | null }).currentSessionId = "ses_parallel_other";
+
+    const starts: Array<{
+      sessionId: string;
+      subagentId?: string;
+      subagentSessionId?: string;
+    }> = [];
+
+    const unsubStart = client.on("subagent.start", (event) => {
+      const data = event.data as { subagentId?: string; subagentSessionId?: string };
+      starts.push({
+        sessionId: event.sessionId,
+        subagentId: data.subagentId,
+        subagentSessionId: data.subagentSessionId,
+      });
+    });
+
+    // Parent session A agent start
+    handle({
+      type: "message.part.updated",
+      properties: {
+        sessionID: "ses_A",
+        part: {
+          id: "agent_A",
+          sessionID: "ses_A",
+          messageID: "msg_A_1",
+          type: "agent",
+          name: "worker",
+        },
+      },
+    });
+
+    // Child tool event for session A
+    handle({
+      type: "message.part.updated",
+      properties: {
+        sessionID: "ses_A",
+        part: {
+          id: "tool_child_A",
+          sessionID: "ses_child_A",
+          messageID: "msg_A_2",
+          type: "tool",
+          tool: "Read",
+          state: {
+            status: "pending",
+            input: { filePath: "src/a.ts" },
+          },
+        },
+      },
+    });
+
+    unsubStart();
+
+    expect(starts).toHaveLength(2);
+    expect(starts[0]!.sessionId).toBe("ses_A");
+    expect(starts[0]!.subagentId).toBe("agent_A");
+    expect(starts[1]!.sessionId).toBe("ses_A");
+    expect(starts[1]!.subagentId).toBe("agent_A");
+    expect(starts[1]!.subagentSessionId).toBe("ses_child_A");
+  });
+
+  test("maps child tool events via session.created parentID before first child tool", () => {
+    const client = new OpenCodeClient();
+    const handle = (event: Record<string, unknown>) =>
+      (client as unknown as { handleSdkEvent: (e: Record<string, unknown>) => void }).handleSdkEvent(event);
+
+    (client as unknown as { currentSessionId: string | null }).currentSessionId = "ses_parent_map";
+
+    const starts: Array<{ subagentId?: string; subagentSessionId?: string }> = [];
+    const toolStarts: Array<{ sessionId: string; toolName?: string; parentAgentId?: string }> = [];
+    const updates: Array<{ subagentId?: string; currentTool?: string; toolUses?: number }> = [];
+
+    const unsubStart = client.on("subagent.start", (event) => {
+      const data = event.data as { subagentId?: string; subagentSessionId?: string };
+      starts.push({ subagentId: data.subagentId, subagentSessionId: data.subagentSessionId });
+    });
+    const unsubToolStart = client.on("tool.start", (event) => {
+      const data = event.data as { toolName?: string; parentAgentId?: string };
+      toolStarts.push({
+        sessionId: event.sessionId,
+        toolName: data.toolName,
+        parentAgentId: data.parentAgentId,
+      });
+    });
+    const unsubUpdate = client.on("subagent.update", (event) => {
+      const data = event.data as { subagentId?: string; currentTool?: string; toolUses?: number };
+      updates.push({
+        subagentId: data.subagentId,
+        currentTool: data.currentTool,
+        toolUses: data.toolUses,
+      });
+    });
+
+    // Parent dispatches sub-agent
+    handle({
+      type: "message.part.updated",
+      properties: {
+        part: {
+          id: "agent_map_1",
+          sessionID: "ses_parent_map",
+          messageID: "msg_parent_map_1",
+          type: "agent",
+          name: "codebase-locator",
+        },
+      },
+    });
+
+    // Child session is created with explicit parentID before first child tool part.
+    handle({
+      type: "session.created",
+      properties: {
+        info: {
+          id: "ses_child_map_1",
+          parentID: "ses_parent_map",
+        },
+      },
+    });
+
+    // First child tool event arrives with child sessionID.
+    handle({
+      type: "message.part.updated",
+      properties: {
+        part: {
+          id: "tool_child_map_1",
+          sessionID: "ses_child_map_1",
+          messageID: "msg_child_map_1",
+          type: "tool",
+          tool: "Read",
+          callID: "call_child_map_1",
+          state: {
+            status: "running",
+            input: { filePath: "src/ui/chat.tsx" },
+          },
+        },
+      },
+    });
+
+    unsubStart();
+    unsubToolStart();
+    unsubUpdate();
+
+    expect(starts).toHaveLength(2);
+    expect(starts[0]).toEqual({ subagentId: "agent_map_1", subagentSessionId: undefined });
+    expect(starts[1]).toEqual({ subagentId: "agent_map_1", subagentSessionId: "ses_child_map_1" });
+    expect(toolStarts).toContainEqual({
+      sessionId: "ses_child_map_1",
+      toolName: "Read",
+      parentAgentId: "agent_map_1",
+    });
+    expect(updates).toContainEqual({
+      subagentId: "agent_map_1",
+      currentTool: "Read",
+      toolUses: 1,
+    });
+  });
+
+  test("infers parent session for active child sessions when a single pending subagent exists", () => {
+    const client = new OpenCodeClient();
+    const handle = (event: Record<string, unknown>) =>
+      (client as unknown as { handleSdkEvent: (e: Record<string, unknown>) => void }).handleSdkEvent(event);
+
+    // Mark child session active before first child tool part arrives.
+    (client as unknown as { registerActiveSession: (sessionId: string) => void })
+      .registerActiveSession("ses_child_active_1");
+
+    const starts: Array<{ sessionId: string; subagentId?: string; subagentSessionId?: string }> = [];
+    const toolStarts: Array<{ sessionId: string; toolName?: string; parentAgentId?: string }> = [];
+
+    const unsubStart = client.on("subagent.start", (event) => {
+      const data = event.data as { subagentId?: string; subagentSessionId?: string };
+      starts.push({
+        sessionId: event.sessionId,
+        subagentId: data.subagentId,
+        subagentSessionId: data.subagentSessionId,
+      });
+    });
+    const unsubToolStart = client.on("tool.start", (event) => {
+      const data = event.data as { toolName?: string; parentAgentId?: string };
+      toolStarts.push({
+        sessionId: event.sessionId,
+        toolName: data.toolName,
+        parentAgentId: data.parentAgentId,
+      });
+    });
+
+    // Parent creates a pending subagent entry.
+    handle({
+      type: "message.part.updated",
+      properties: {
+        part: {
+          id: "agent_pending_1",
+          sessionID: "ses_parent_pending_1",
+          messageID: "msg_parent_pending_1",
+          type: "agent",
+          name: "codebase-analyzer",
+        },
+      },
+    });
+
+    // Child tool part arrives while child session is already active.
+    handle({
+      type: "message.part.updated",
+      properties: {
+        part: {
+          id: "tool_child_active_1",
+          sessionID: "ses_child_active_1",
+          messageID: "msg_child_active_1",
+          type: "tool",
+          tool: "Glob",
+          state: {
+            status: "pending",
+            input: { path: "src/**/*.ts" },
+          },
+        },
+      },
+    });
+
+    unsubStart();
+    unsubToolStart();
+
+    expect(starts).toHaveLength(2);
+    expect(starts[0]).toEqual({
+      sessionId: "ses_parent_pending_1",
+      subagentId: "agent_pending_1",
+      subagentSessionId: undefined,
+    });
+    expect(starts[1]).toEqual({
+      sessionId: "ses_parent_pending_1",
+      subagentId: "agent_pending_1",
+      subagentSessionId: "ses_child_active_1",
+    });
+    expect(toolStarts).toContainEqual({
+      sessionId: "ses_child_active_1",
+      toolName: "Glob",
+      parentAgentId: "agent_pending_1",
+    });
+  });
+
+  test("does not re-emit subagent.start for subsequent tool events on same child session", () => {
+    const client = new OpenCodeClient();
+    const handle = (event: Record<string, unknown>) =>
+      (client as unknown as { handleSdkEvent: (e: Record<string, unknown>) => void }).handleSdkEvent(event);
+
+    (client as unknown as { currentSessionId: string | null }).currentSessionId = "ses_parent";
+
+    const starts: Array<{ subagentId?: string; subagentSessionId?: string }> = [];
+    const unsubStart = client.on("subagent.start", (event) => {
+      const data = event.data as { subagentId?: string; subagentSessionId?: string };
+      starts.push({ subagentId: data.subagentId, subagentSessionId: data.subagentSessionId });
+    });
+
+    // Agent part
+    handle({
+      type: "message.part.updated",
+      properties: {
+        sessionID: "ses_parent",
+        part: { id: "agent_1", sessionID: "ses_parent", messageID: "msg_1", type: "agent", name: "explore" },
+      },
+    });
+
+    // First child tool → triggers re-emit
+    handle({
+      type: "message.part.updated",
+      properties: {
+        part: {
+          id: "tool_1", sessionID: "ses_child", messageID: "msg_c1", type: "tool",
+          tool: "Read", state: { status: "pending", input: {} },
+        },
+      },
+    });
+
+    // Second child tool → should NOT re-emit
+    handle({
+      type: "message.part.updated",
+      properties: {
+        part: {
+          id: "tool_2", sessionID: "ses_child", messageID: "msg_c2", type: "tool",
+          tool: "Write", state: { status: "pending", input: {} },
+        },
+      },
+    });
+
+    unsubStart();
+
+    // Only 2 subagent.start events: initial + one re-emit
+    expect(starts).toHaveLength(2);
+  });
+
+  test("does not synthesize nested task tool events from child sessions", () => {
+    const client = new OpenCodeClient();
+    const handle = (event: Record<string, unknown>) =>
+      (client as unknown as { handleSdkEvent: (e: Record<string, unknown>) => void }).handleSdkEvent(event);
+
+    (client as unknown as { currentSessionId: string | null }).currentSessionId = "ses_parent";
+
+    const starts: Array<{ subagentId?: string; subagentType?: string; subagentSessionId?: string }> = [];
+    const unsubStart = client.on("subagent.start", (event) => {
+      const data = event.data as {
+        subagentId?: string;
+        subagentType?: string;
+        subagentSessionId?: string;
+      };
+      starts.push({
+        subagentId: data.subagentId,
+        subagentType: data.subagentType,
+        subagentSessionId: data.subagentSessionId,
+      });
+    });
+
+    // Seed a pending agent and discover its child session.
+    handle({
+      type: "message.part.updated",
+      properties: {
+        part: {
+          id: "agent_debugger",
+          sessionID: "ses_parent",
+          messageID: "msg_1",
+          type: "agent",
+          name: "debugger",
+        },
+      },
+    });
+    handle({
+      type: "message.part.updated",
+      properties: {
+        part: {
+          id: "tool_read_1",
+          sessionID: "ses_child_debugger",
+          messageID: "msg_child_1",
+          type: "tool",
+          tool: "Read",
+          callID: "call_read_1",
+          state: { status: "pending", input: { file: "src/index.ts" } },
+        },
+      },
+    });
+
+    const startsBeforeNestedTask = [...starts];
+    // Nested task tool under child session should NOT synthesize a new top-level task-agent row.
+    handle({
+      type: "message.part.updated",
+      properties: {
+        // Regression guard: envelope may still report the parent session.
+        sessionID: "ses_parent",
+        part: {
+          id: "nested_task_1",
+          sessionID: "ses_child_debugger",
+          messageID: "msg_child_2",
+          type: "tool",
+          tool: "task",
+          state: {
+            status: "running",
+            input: {
+              subagent_type: "worker",
+              description: "Debug message routing",
+            },
+          },
+        },
       },
-    ]);
+    });
+
+    unsubStart();
+
+    expect(starts).toEqual(startsBeforeNestedTask);
   });
 
-  test("maps step-finish part to subagent.complete", () => {
+  test("does not emit subagent.start rows from task tool status updates", () => {
     const client = new OpenCodeClient();
-    const completes: Array<{
-      sessionId: string;
+    const handle = (event: Record<string, unknown>) =>
+      (client as unknown as { handleSdkEvent: (e: Record<string, unknown>) => void }).handleSdkEvent(event);
+
+    (client as unknown as { currentSessionId: string | null }).currentSessionId = "ses_parent";
+
+    const starts: Array<{
       subagentId?: string;
-      success?: boolean;
-      result?: string;
+      subagentType?: string;
+      task?: string;
+      subagentSessionId?: string;
     }> = [];
-
-    const unsubComplete = client.on("subagent.complete", (event) => {
+    const unsubStart = client.on("subagent.start", (event) => {
       const data = event.data as {
         subagentId?: string;
-        success?: boolean;
-        result?: string;
+        subagentType?: string;
+        task?: string;
+        subagentSessionId?: string;
       };
-      completes.push({
-        sessionId: event.sessionId,
+      starts.push({
         subagentId: data.subagentId,
-        success: data.success,
-        result: data.result,
+        subagentType: data.subagentType,
+        task: data.task,
+        subagentSessionId: data.subagentSessionId,
       });
     });
 
-    // Test successful completion
-    (client as unknown as { handleSdkEvent: (event: Record<string, unknown>) => void }).handleSdkEvent({
+    // First running event has type but no task text yet.
+    handle({
       type: "message.part.updated",
       properties: {
         part: {
-          id: "step-1",
-          sessionID: "ses_step",
-          messageID: "msg_step",
-          type: "step-finish",
-          reason: "success",
+          id: "task_debugger_1",
+          sessionID: "ses_parent",
+          messageID: "msg_1",
+          type: "tool",
+          tool: "task",
+          state: {
+            status: "running",
+            input: {
+              subagent_type: "debugger",
+            },
+          },
         },
       },
     });
 
-    // Test error completion
-    (client as unknown as { handleSdkEvent: (event: Record<string, unknown>) => void }).handleSdkEvent({
+    // Second running event provides task text but omits subagent_type.
+    handle({
       type: "message.part.updated",
       properties: {
         part: {
-          id: "step-2",
-          sessionID: "ses_step",
-          messageID: "msg_step_2",
-          type: "step-finish",
-          reason: "error",
+          id: "task_debugger_1",
+          sessionID: "ses_parent",
+          messageID: "msg_1",
+          type: "tool",
+          tool: "task",
+          state: {
+            status: "running",
+            input: {
+              description: "Inspect workflow stream issues",
+            },
+          },
         },
       },
     });
 
-    unsubComplete();
+    // Completion re-emits subagent.start with child session registration.
+    handle({
+      type: "message.part.updated",
+      properties: {
+        part: {
+          id: "task_debugger_1",
+          sessionID: "ses_parent",
+          messageID: "msg_1",
+          type: "tool",
+          tool: "task",
+          state: {
+            status: "completed",
+            input: {
+              description: "Inspect workflow stream issues",
+            },
+            metadata: {
+              sessionId: "ses_child_debugger",
+            },
+          },
+        },
+      },
+    });
 
-    expect(completes).toEqual([
+    unsubStart();
+
+    expect(starts).toHaveLength(0);
+  });
+
+  test("maps structured session.error payloads to readable error strings", () => {
+    const client = new OpenCodeClient();
+    const errors: Array<{ sessionId: string; error: unknown }> = [];
+
+    const unsubscribe = client.on("session.error", (event) => {
+      errors.push({
+        sessionId: event.sessionId,
+        error: (event.data as { error?: unknown }).error,
+      });
+    });
+
+    (client as unknown as { handleSdkEvent: (event: Record<string, unknown>) => void }).handleSdkEvent({
+      type: "session.error",
+      properties: {
+        sessionID: "ses_structured_error",
+        error: {
+          message: "Rate limit exceeded",
+          code: "RATE_LIMIT",
+        },
+      },
+    });
+
+    unsubscribe();
+
+    expect(errors).toEqual([
       {
-        sessionId: "ses_step",
-        subagentId: "step-1",
-        success: true,
-        result: "success",
+        sessionId: "ses_structured_error",
+        error: "Rate limit exceeded",
+      },
+    ]);
+  });
+
+  test("maps session.error info.id payloads and extracts top-level stderr text", () => {
+    const client = new OpenCodeClient();
+    const errors: Array<{ sessionId: string; error: unknown }> = [];
+
+    const unsubscribe = client.on("session.error", (event) => {
+      errors.push({
+        sessionId: event.sessionId,
+        error: (event.data as { error?: unknown }).error,
+      });
+    });
+
+    (client as unknown as { handleSdkEvent: (event: Record<string, unknown>) => void }).handleSdkEvent({
+      type: "session.error",
+      error: {
+        stderr: "OpenCode process exited with code 1",
+      },
+      properties: {
+        info: { id: "ses_error_info_id" },
       },
+    });
+
+    unsubscribe();
+
+    expect(errors).toEqual([
       {
-        sessionId: "ses_step",
-        subagentId: "step-2",
-        success: false,
-        result: "error",
+        sessionId: "ses_error_info_id",
+        error: "OpenCode process exited with code 1",
       },
     ]);
   });
+
+  test("stream throws prompt errors instead of yielding assistant error text", async () => {
+    const client = new OpenCodeClient();
+    const sessionId = "ses_stream_error";
+
+    (client as unknown as {
+      resolveModelContextWindow: (modelHint?: string) => Promise<number>;
+    }).resolveModelContextWindow = async () => 200_000;
+
+    (client as unknown as {
+      sdkClient: {
+        session: {
+          promptAsync: () => Promise<Record<string, unknown>>;
+        };
+      };
+    }).sdkClient = {
+      session: {
+        promptAsync: async () => ({
+          error: {
+            message: "OpenCode quota exceeded",
+          },
+        }),
+      },
+    };
+
+    const session = await (client as unknown as {
+      wrapSession: (
+        sid: string,
+        config: Record<string, unknown>,
+      ) => Promise<{
+        stream: (message: string) => AsyncIterable<unknown>;
+      }>;
+    }).wrapSession(sessionId, {});
+
+    const consumeStream = async (): Promise<void> => {
+      for await (const _chunk of session.stream("trigger")) {
+        // stream should throw before yielding error text chunks
+      }
+    };
+
+    await expect(consumeStream()).rejects.toThrow("OpenCode quota exceeded");
+  });
+
+  test("stream proactively compacts when usage crosses threshold", async () => {
+    const client = new OpenCodeClient();
+    const sessionId = "ses_stream_proactive_threshold";
+
+    (client as unknown as {
+      resolveModelContextWindow: (modelHint?: string) => Promise<number>;
+    }).resolveModelContextWindow = async () => 100;
+
+    const handle = (event: Record<string, unknown>) =>
+      (client as unknown as { handleSdkEvent: (e: Record<string, unknown>) => void }).handleSdkEvent(event);
+
+    const promptCalls: string[] = [];
+    let summarizeCalls = 0;
+
+    (client as unknown as {
+      sdkClient: {
+        session: {
+          promptAsync: (params: Record<string, unknown>) => Promise<Record<string, unknown>>;
+          summarize: (params: Record<string, unknown>) => Promise<Record<string, never>>;
+          messages: (params: Record<string, unknown>) => Promise<{ data: unknown[] }>;
+        };
+      };
+    }).sdkClient = {
+      session: {
+        promptAsync: async (params) => {
+          const parts = ((params.parts as Array<{ type?: string; text?: string }> | undefined) ?? []);
+          const textPart = parts.find((part) => part.type === "text");
+          promptCalls.push(textPart?.text ?? "");
+
+          setTimeout(() => {
+            handle({
+              type: "message.updated",
+              properties: {
+                info: {
+                  role: "assistant",
+                  sessionID: sessionId,
+                  tokens: {
+                    input: 30,
+                    output: 20,
+                  },
+                },
+              },
+            });
+          }, 10);
+
+          setTimeout(() => {
+            handle({
+              type: "message.part.delta",
+              properties: {
+                sessionID: sessionId,
+                delta: "threshold output",
+              },
+            });
+          }, 20);
+
+          setTimeout(() => {
+            handle({
+              type: "session.status",
+              properties: {
+                sessionID: sessionId,
+                status: "idle",
+              },
+            });
+          }, 40);
+
+          return {};
+        },
+        summarize: async () => {
+          summarizeCalls += 1;
+          return {};
+        },
+        messages: async () => ({ data: [] }),
+      },
+    };
+
+    const session = await (client as unknown as {
+      wrapSession: (
+        sid: string,
+        config: Record<string, unknown>,
+      ) => Promise<{
+        stream: (message: string) => AsyncIterable<{ type: string; content: unknown }>;
+      }>;
+    }).wrapSession(sessionId, {});
+
+    const textChunks: string[] = [];
+    for await (const chunk of session.stream("trigger proactive threshold")) {
+      if (chunk.type === "text") {
+        textChunks.push(chunk.content as string);
+      }
+    }
+
+    expect(promptCalls).toEqual(["trigger proactive threshold"]);
+    expect(textChunks).toEqual(["threshold output"]);
+    expect(summarizeCalls).toBe(1);
+  });
+
+  test("stream does not proactively compact below threshold", async () => {
+    const client = new OpenCodeClient();
+    const sessionId = "ses_stream_proactive_below_threshold";
+
+    (client as unknown as {
+      resolveModelContextWindow: (modelHint?: string) => Promise<number>;
+    }).resolveModelContextWindow = async () => 100;
+
+    const handle = (event: Record<string, unknown>) =>
+      (client as unknown as { handleSdkEvent: (e: Record<string, unknown>) => void }).handleSdkEvent(event);
+
+    let summarizeCalls = 0;
+
+    (client as unknown as {
+      sdkClient: {
+        session: {
+          promptAsync: (params: Record<string, unknown>) => Promise<Record<string, unknown>>;
+          summarize: (params: Record<string, unknown>) => Promise<Record<string, never>>;
+          messages: (params: Record<string, unknown>) => Promise<{ data: unknown[] }>;
+        };
+      };
+    }).sdkClient = {
+      session: {
+        promptAsync: async () => {
+          setTimeout(() => {
+            handle({
+              type: "message.updated",
+              properties: {
+                info: {
+                  role: "assistant",
+                  sessionID: sessionId,
+                  tokens: {
+                    input: 20,
+                    output: 10,
+                  },
+                },
+              },
+            });
+          }, 10);
+
+          setTimeout(() => {
+            handle({
+              type: "session.status",
+              properties: {
+                sessionID: sessionId,
+                status: "idle",
+              },
+            });
+          }, 40);
+
+          return {};
+        },
+        summarize: async () => {
+          summarizeCalls += 1;
+          return {};
+        },
+        messages: async () => ({ data: [] }),
+      },
+    };
+
+    const session = await (client as unknown as {
+      wrapSession: (
+        sid: string,
+        config: Record<string, unknown>,
+      ) => Promise<{
+        stream: (message: string) => AsyncIterable<unknown>;
+      }>;
+    }).wrapSession(sessionId, {});
+
+    for await (const _chunk of session.stream("below threshold")) {
+      // no-op
+    }
+
+    expect(summarizeCalls).toBe(0);
+  });
+
+  test("stream auto-compacts on overflow and auto-continues", async () => {
+    const client = new OpenCodeClient();
+    const sessionId = "ses_stream_overflow_recovery";
+
+    (client as unknown as {
+      resolveModelContextWindow: (modelHint?: string) => Promise<number>;
+    }).resolveModelContextWindow = async () => 200_000;
+
+    const handle = (event: Record<string, unknown>) =>
+      (client as unknown as { handleSdkEvent: (e: Record<string, unknown>) => void }).handleSdkEvent(event);
+
+    const promptCalls: string[] = [];
+    let summarizeCalls = 0;
+
+    (client as unknown as {
+      sdkClient: {
+        session: {
+          promptAsync: (params: Record<string, unknown>) => Promise<Record<string, unknown>>;
+          summarize: (params: Record<string, unknown>) => Promise<Record<string, never>>;
+          messages: (params: Record<string, unknown>) => Promise<{ data: unknown[] }>;
+        };
+      };
+    }).sdkClient = {
+      session: {
+        promptAsync: async (params) => {
+          const parts = ((params.parts as Array<{ type?: string; text?: string }> | undefined) ?? []);
+          const textPart = parts.find((part) => part.type === "text");
+          promptCalls.push(textPart?.text ?? "");
+
+          if (promptCalls.length === 1) {
+            return {
+              error: {
+                message: "ContextOverflowError: Input exceeds context window of this model",
+              },
+            };
+          }
+
+          setTimeout(() => {
+            handle({
+              type: "message.part.delta",
+              properties: {
+                sessionID: sessionId,
+                delta: "continued output",
+              },
+            });
+          }, 20);
+
+          setTimeout(() => {
+            handle({
+              type: "session.status",
+              properties: {
+                sessionID: sessionId,
+                status: "idle",
+              },
+            });
+          }, 80);
+
+          return {};
+        },
+        summarize: async () => {
+          summarizeCalls += 1;
+          return {};
+        },
+        messages: async () => ({ data: [] }),
+      },
+    };
+
+    const session = await (client as unknown as {
+      wrapSession: (
+        sid: string,
+        config: Record<string, unknown>,
+      ) => Promise<{
+        stream: (message: string) => AsyncIterable<{ type: string; content: unknown }>;
+      }>;
+    }).wrapSession(sessionId, {});
+
+    const textChunks: string[] = [];
+    for await (const chunk of session.stream("trigger overflow")) {
+      if (chunk.type === "text") {
+        textChunks.push(chunk.content as string);
+      }
+    }
+
+    expect(summarizeCalls).toBe(1);
+    expect(promptCalls).toEqual(["trigger overflow", "Continue"]);
+    expect(textChunks).toEqual(["continued output"]);
+  });
+
+  test("stream overflow recovery emits compaction lifecycle in deterministic order", async () => {
+    const client = new OpenCodeClient();
+    const sessionId = "ses_stream_overflow_recovery_ordering";
+
+    (client as unknown as {
+      resolveModelContextWindow: (modelHint?: string) => Promise<number>;
+    }).resolveModelContextWindow = async () => 200_000;
+
+    const handle = (event: Record<string, unknown>) =>
+      (client as unknown as { handleSdkEvent: (e: Record<string, unknown>) => void }).handleSdkEvent(event);
+
+    const promptCalls: string[] = [];
+    const compactionPhases: string[] = [];
+    const idleReasons: string[] = [];
+    const lifecycle: string[] = [];
+    const truncationTokensRemoved: number[] = [];
+    let summarizeCalls = 0;
+
+    const unsubCompaction = client.on("session.compaction", (event) => {
+      const data = event.data as { phase?: string };
+      if (data.phase) {
+        compactionPhases.push(data.phase);
+        lifecycle.push(`compaction:${data.phase}`);
+      }
+    });
+
+    const unsubTruncation = client.on("session.truncation", (event) => {
+      const data = event.data as { tokensRemoved?: number };
+      truncationTokensRemoved.push(data.tokensRemoved ?? 0);
+      lifecycle.push("truncation");
+    });
+
+    const unsubIdle = client.on("session.idle", (event) => {
+      const data = event.data as { reason?: string };
+      const reason = data.reason ?? "";
+      idleReasons.push(reason);
+      lifecycle.push(`idle:${reason}`);
+    });
+
+    (client as unknown as {
+      sdkClient: {
+        session: {
+          promptAsync: (params: Record<string, unknown>) => Promise<Record<string, unknown>>;
+          summarize: (params: Record<string, unknown>) => Promise<Record<string, never>>;
+          messages: (params: Record<string, unknown>) => Promise<{
+            data?: Array<{ info: { role: string; tokens?: { input?: number; output?: number } } }>;
+          }>;
+        };
+      };
+    }).sdkClient = {
+      session: {
+        promptAsync: async (params) => {
+          const parts = ((params.parts as Array<{ type?: string; text?: string }> | undefined) ?? []);
+          const textPart = parts.find((part) => part.type === "text");
+          promptCalls.push(textPart?.text ?? "");
+
+          if (promptCalls.length === 1) {
+            handle({
+              type: "message.updated",
+              properties: {
+                info: {
+                  role: "assistant",
+                  sessionID: sessionId,
+                  tokens: {
+                    input: 1_200,
+                    output: 300,
+                  },
+                },
+              },
+            });
+            return {
+              error: {
+                message: "ContextOverflowError: Input exceeds context window of this model",
+              },
+            };
+          }
+
+          setTimeout(() => {
+            handle({
+              type: "message.part.delta",
+              properties: {
+                sessionID: sessionId,
+                delta: "continued output",
+              },
+            });
+          }, 10);
+
+          setTimeout(() => {
+            handle({
+              type: "session.status",
+              properties: {
+                sessionID: sessionId,
+                status: "idle",
+              },
+            });
+          }, 30);
+
+          return {};
+        },
+        summarize: async () => {
+          summarizeCalls += 1;
+          setTimeout(() => {
+            handle({
+              type: "session.compacted",
+              properties: { sessionID: sessionId },
+            });
+          }, 0);
+          setTimeout(() => {
+            handle({
+              type: "session.compacted",
+              properties: { sessionID: sessionId },
+            });
+          }, 1);
+          return {};
+        },
+        messages: async () => ({
+          data: [
+            {
+              info: {
+                role: "assistant",
+                tokens: { input: 400, output: 100 },
+              },
+            },
+          ],
+        }),
+      },
+    };
+
+    const session = await (client as unknown as {
+      wrapSession: (
+        sid: string,
+        config: Record<string, unknown>,
+      ) => Promise<{
+        stream: (message: string) => AsyncIterable<{ type: string; content: unknown }>;
+      }>;
+    }).wrapSession(sessionId, {});
+
+    const textChunks: string[] = [];
+    for await (const chunk of session.stream("trigger overflow")) {
+      if (chunk.type === "text") {
+        textChunks.push(chunk.content as string);
+        lifecycle.push("text");
+      }
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    unsubCompaction();
+    unsubTruncation();
+    unsubIdle();
+
+    expect(summarizeCalls).toBe(1);
+    expect(promptCalls).toEqual(["trigger overflow", "Continue"]);
+    expect(textChunks).toEqual(["continued output"]);
+    expect(compactionPhases).toEqual(["start", "complete"]);
+    expect(truncationTokensRemoved).toEqual([1_000]);
+    expect(idleReasons).toEqual(["context_compacted", "idle"]);
+
+    const startIdx = lifecycle.indexOf("compaction:start");
+    const truncationIdx = lifecycle.indexOf("truncation");
+    const completeIdx = lifecycle.indexOf("compaction:complete");
+    const textIdx = lifecycle.indexOf("text");
+    expect(startIdx).toBeGreaterThanOrEqual(0);
+    expect(truncationIdx).toBeGreaterThan(startIdx);
+    expect(completeIdx).toBeGreaterThan(truncationIdx);
+    expect(textIdx).toBeGreaterThan(completeIdx);
+  });
+
+  test("stream overflow recovery drops stale pre-compaction deltas", async () => {
+    const client = new OpenCodeClient();
+    const sessionId = "ses_stream_overflow_recovery_stale_delta";
+
+    (client as unknown as {
+      resolveModelContextWindow: (modelHint?: string) => Promise<number>;
+    }).resolveModelContextWindow = async () => 200_000;
+
+    const handle = (event: Record<string, unknown>) =>
+      (client as unknown as { handleSdkEvent: (e: Record<string, unknown>) => void }).handleSdkEvent(event);
+
+    const promptCalls: string[] = [];
+    let summarizeCalls = 0;
+
+    (client as unknown as {
+      sdkClient: {
+        session: {
+          promptAsync: (params: Record<string, unknown>) => Promise<Record<string, unknown>>;
+          summarize: (params: Record<string, unknown>) => Promise<Record<string, never>>;
+          messages: (params: Record<string, unknown>) => Promise<{ data: unknown[] }>;
+        };
+      };
+    }).sdkClient = {
+      session: {
+        promptAsync: async (params) => {
+          const parts = ((params.parts as Array<{ type?: string; text?: string }> | undefined) ?? []);
+          const textPart = parts.find((part) => part.type === "text");
+          promptCalls.push(textPart?.text ?? "");
+
+          if (promptCalls.length === 1) {
+            setTimeout(() => {
+              handle({
+                type: "message.part.delta",
+                properties: {
+                  sessionID: sessionId,
+                  delta: "stale pre-compaction output",
+                },
+              });
+            }, 5);
+            return {
+              error: {
+                message: "context_length_exceeded",
+              },
+            };
+          }
+
+          setTimeout(() => {
+            handle({
+              type: "message.part.delta",
+              properties: {
+                sessionID: sessionId,
+                delta: "continued output",
+              },
+            });
+          }, 5);
+
+          setTimeout(() => {
+            handle({
+              type: "session.status",
+              properties: {
+                sessionID: sessionId,
+                status: "idle",
+              },
+            });
+          }, 20);
+
+          return {};
+        },
+        summarize: async () => {
+          summarizeCalls += 1;
+          await new Promise((resolve) => setTimeout(resolve, 20));
+          return {};
+        },
+        messages: async () => ({ data: [] }),
+      },
+    };
+
+    const session = await (client as unknown as {
+      wrapSession: (
+        sid: string,
+        config: Record<string, unknown>,
+      ) => Promise<{
+        stream: (message: string) => AsyncIterable<{ type: string; content: unknown }>;
+      }>;
+    }).wrapSession(sessionId, {});
+
+    const textChunks: string[] = [];
+    for await (const chunk of session.stream("trigger overflow")) {
+      if (chunk.type === "text") {
+        textChunks.push(chunk.content as string);
+      }
+    }
+
+    expect(summarizeCalls).toBe(1);
+    expect(promptCalls).toEqual(["trigger overflow", "Continue"]);
+    expect(textChunks).toEqual(["continued output"]);
+  });
+
+  test("stream surfaces overflow after auto-compaction retry budget is exhausted", async () => {
+    const client = new OpenCodeClient();
+    const sessionId = "ses_stream_overflow_retries_exhausted";
+
+    (client as unknown as {
+      resolveModelContextWindow: (modelHint?: string) => Promise<number>;
+    }).resolveModelContextWindow = async () => 200_000;
+
+    const promptCalls: string[] = [];
+    let summarizeCalls = 0;
+
+    (client as unknown as {
+      sdkClient: {
+        session: {
+          promptAsync: (params: Record<string, unknown>) => Promise<Record<string, unknown>>;
+          summarize: (params: Record<string, unknown>) => Promise<Record<string, never>>;
+          messages: (params: Record<string, unknown>) => Promise<{ data: unknown[] }>;
+        };
+      };
+    }).sdkClient = {
+      session: {
+        promptAsync: async (params) => {
+          const parts = ((params.parts as Array<{ type?: string; text?: string }> | undefined) ?? []);
+          const textPart = parts.find((part) => part.type === "text");
+          promptCalls.push(textPart?.text ?? "");
+
+          return {
+            error: {
+              message: "context_length_exceeded",
+            },
+          };
+        },
+        summarize: async () => {
+          summarizeCalls += 1;
+          return {};
+        },
+        messages: async () => ({ data: [] }),
+      },
+    };
+
+    const session = await (client as unknown as {
+      wrapSession: (
+        sid: string,
+        config: Record<string, unknown>,
+      ) => Promise<{
+        stream: (message: string) => AsyncIterable<unknown>;
+      }>;
+    }).wrapSession(sessionId, {});
+
+    const consumeStream = async (): Promise<void> => {
+      for await (const _chunk of session.stream("trigger overflow")) {
+        // stream should throw after a single auto-compaction attempt
+      }
+    };
+
+    await expect(consumeStream()).rejects.toThrow(/context_length_exceeded/i);
+    expect(summarizeCalls).toBe(1);
+    expect(promptCalls).toEqual(["trigger overflow", "Continue"]);
+  });
+
+  test("stream preserves OpenCodeCompactionError type for auto-compaction failures", async () => {
+    const client = new OpenCodeClient();
+    const sessionId = "ses_stream_overflow_compaction_failure";
+    const promptCalls: string[] = [];
+    let summarizeCalls = 0;
+
+    (client as unknown as {
+      resolveModelContextWindow: (modelHint?: string) => Promise<number>;
+    }).resolveModelContextWindow = async () => 200_000;
+
+    (client as unknown as {
+      sdkClient: {
+        session: {
+          promptAsync: (params: Record<string, unknown>) => Promise<Record<string, unknown>>;
+          summarize: (params: Record<string, unknown>) => Promise<Record<string, never>>;
+          messages: (params: Record<string, unknown>) => Promise<{ data: unknown[] }>;
+        };
+      };
+    }).sdkClient = {
+      session: {
+        promptAsync: async (params) => {
+          const parts = ((params.parts as Array<{ type?: string; text?: string }> | undefined) ?? []);
+          const textPart = parts.find((part) => part.type === "text");
+          promptCalls.push(textPart?.text ?? "");
+          return { error: { message: "context_length_exceeded" } };
+        },
+        summarize: async () => {
+          summarizeCalls += 1;
+          throw new Error("summarize failed");
+        },
+        messages: async () => ({ data: [] }),
+      },
+    };
+
+    const session = await (client as unknown as {
+      wrapSession: (
+        sid: string,
+        config: Record<string, unknown>,
+      ) => Promise<{
+        stream: (message: string) => AsyncIterable<unknown>;
+      }>;
+    }).wrapSession(sessionId, {});
+
+    const consumeStream = async (): Promise<void> => {
+      for await (const _chunk of session.stream("trigger overflow")) {
+        // stream should fail after summarize terminal error
+      }
+    };
+
+    const streamError = await consumeStream()
+      .then(() => null)
+      .catch((error: unknown) => error);
+    expect(streamError).toBeInstanceOf(OpenCodeCompactionError);
+    if (!(streamError instanceof OpenCodeCompactionError)) {
+      throw new Error("Expected stream to throw OpenCodeCompactionError");
+    }
+    expect(streamError.code).toBe("COMPACTION_FAILED");
+    expect(streamError.message).toBe(COMPACTION_TERMINAL_ERROR_MESSAGE);
+    expect(summarizeCalls).toBe(1);
+    expect(promptCalls).toEqual(["trigger overflow"]);
+  });
 });
diff --git a/src/sdk/clients/opencode.resilience.integration.test.ts b/src/sdk/clients/opencode.resilience.integration.test.ts
new file mode 100644
index 0000000000..9716cd0596
--- /dev/null
+++ b/src/sdk/clients/opencode.resilience.integration.test.ts
@@ -0,0 +1,198 @@
+import { describe, expect, test } from "bun:test";
+import { OpenCodeClient } from "./opencode.ts";
+
+describe("OpenCodeClient resilience integration", () => {
+  test("reconnects and reconciles after stream completion", async () => {
+    const client = new OpenCodeClient();
+    const globalAbort = new AbortController();
+    let subscribeCalls = 0;
+    let processCalls = 0;
+    let reconcileCalls = 0;
+
+    const internal = client as unknown as {
+      isRunning: boolean;
+      eventSubscriptionController: AbortController | null;
+      sdkClient: {
+        event: {
+          subscribe: (
+            parameters?: { directory?: string },
+            options?: { signal?: AbortSignal },
+          ) => Promise<{ stream: AsyncGenerator<unknown, unknown, unknown> }>;
+        };
+      } | null;
+      processEventStream: (
+        stream: AsyncGenerator<unknown, unknown, unknown>,
+        watchdogAbort: AbortController,
+      ) => Promise<void>;
+      reconcileStateOnReconnect: () => Promise<void>;
+      runEventLoop: () => Promise<void>;
+    };
+
+    internal.isRunning = true;
+    internal.eventSubscriptionController = globalAbort;
+    internal.sdkClient = {
+      event: {
+        subscribe: async (_parameters, options) => {
+          subscribeCalls += 1;
+          expect(options?.signal).toBeDefined();
+          return {
+            stream: (async function* () {})(),
+          };
+        },
+      },
+    };
+
+    internal.reconcileStateOnReconnect = async () => {
+      reconcileCalls += 1;
+    };
+
+    internal.processEventStream = async () => {
+      processCalls += 1;
+      if (processCalls >= 2) {
+        globalAbort.abort();
+      }
+    };
+
+    await Promise.race([
+      internal.runEventLoop(),
+      new Promise<never>((_resolve, reject) => {
+        setTimeout(() => reject(new Error("runEventLoop did not reconnect in time")), 2_500);
+      }),
+    ]);
+
+    expect(subscribeCalls).toBe(2);
+    expect(processCalls).toBe(2);
+    expect(reconcileCalls).toBe(1);
+  });
+
+  test("keeps concurrent session streams isolated under interleaved events", async () => {
+    const client = new OpenCodeClient();
+    let promptCalls = 0;
+
+    (client as unknown as {
+      resolveModelContextWindow: (modelHint?: string) => Promise<number>;
+    }).resolveModelContextWindow = async () => 200_000;
+
+    const emitSdkEvent = (event: Record<string, unknown>) => {
+      (client as unknown as { handleSdkEvent: (sdkEvent: Record<string, unknown>) => void })
+        .handleSdkEvent(event);
+    };
+
+    const emitInterleavedEvents = () => {
+      setTimeout(() => {
+        emitSdkEvent({
+          type: "message.part.delta",
+          properties: {
+            sessionID: "ses_A",
+            delta: "A:1",
+          },
+        });
+      }, 10);
+      setTimeout(() => {
+        emitSdkEvent({
+          type: "message.part.delta",
+          properties: {
+            sessionID: "ses_B",
+            delta: "B:1",
+          },
+        });
+      }, 20);
+      setTimeout(() => {
+        emitSdkEvent({
+          type: "message.part.delta",
+          properties: {
+            sessionID: "ses_A",
+            delta: "A:2",
+          },
+        });
+      }, 30);
+      setTimeout(() => {
+        emitSdkEvent({
+          type: "message.part.delta",
+          properties: {
+            sessionID: "ses_B",
+            delta: "B:2",
+          },
+        });
+      }, 40);
+      setTimeout(() => {
+        emitSdkEvent({
+          type: "session.status",
+          properties: {
+            sessionID: "ses_A",
+            status: "idle",
+          },
+        });
+      }, 60);
+      setTimeout(() => {
+        emitSdkEvent({
+          type: "session.status",
+          properties: {
+            sessionID: "ses_B",
+            status: "idle",
+          },
+        });
+      }, 70);
+    };
+
+    (client as unknown as {
+      sdkClient: {
+        session: {
+          promptAsync: (params: Record<string, unknown>) => Promise<Record<string, unknown>>;
+        };
+      };
+    }).sdkClient = {
+      session: {
+        promptAsync: async () => {
+          promptCalls += 1;
+          if (promptCalls === 2) {
+            emitInterleavedEvents();
+          }
+          return {};
+        },
+      },
+    };
+
+    const sessionA = await (client as unknown as {
+      wrapSession: (
+        sid: string,
+        config: Record<string, unknown>,
+      ) => Promise<{
+        stream: (message: string) => AsyncIterable<{ type: string; content: unknown }>;
+      }>;
+    }).wrapSession("ses_A", {});
+    const sessionB = await (client as unknown as {
+      wrapSession: (
+        sid: string,
+        config: Record<string, unknown>,
+      ) => Promise<{
+        stream: (message: string) => AsyncIterable<{ type: string; content: unknown }>;
+      }>;
+    }).wrapSession("ses_B", {});
+
+    const collectText = async (
+      stream: AsyncIterable<{ type: string; content: unknown }>,
+    ): Promise<string[]> => {
+      const deltas: string[] = [];
+      for await (const chunk of stream) {
+        if (chunk.type === "text" && typeof chunk.content === "string") {
+          deltas.push(chunk.content);
+        }
+      }
+      return deltas;
+    };
+
+    const results = await Promise.race([
+      Promise.all([
+        collectText(sessionA.stream("run A")),
+        collectText(sessionB.stream("run B")),
+      ]),
+      new Promise<never>((_resolve, reject) => {
+        setTimeout(() => reject(new Error("concurrent streams did not complete in time")), 2_500);
+      }),
+    ]);
+
+    expect(results[0]).toEqual(["A:1", "A:2"]);
+    expect(results[1]).toEqual(["B:1", "B:2"]);
+  });
+});
diff --git a/src/sdk/clients/opencode.sse-abort.test.ts b/src/sdk/clients/opencode.sse-abort.test.ts
new file mode 100644
index 0000000000..1ad591d7ef
--- /dev/null
+++ b/src/sdk/clients/opencode.sse-abort.test.ts
@@ -0,0 +1,106 @@
+import { describe, expect, test } from "bun:test";
+import { OpenCodeClient } from "./opencode.ts";
+
+describe("OpenCodeClient SSE abort propagation", () => {
+  test("composed abort signal aborts when watchdog aborts", async () => {
+    const client = new OpenCodeClient();
+    const globalAbort = new AbortController();
+    let subscribeSignal: AbortSignal | undefined;
+    let usedWatchdog: AbortController | undefined;
+
+    const internal = client as unknown as {
+      isRunning: boolean;
+      eventSubscriptionController: AbortController | null;
+      sdkClient: {
+        event: {
+          subscribe: (
+            parameters?: { directory?: string },
+            options?: { signal?: AbortSignal },
+          ) => Promise<{ stream: AsyncGenerator<unknown, unknown, unknown> }>;
+        };
+      } | null;
+      processEventStream: (
+        stream: AsyncGenerator<unknown, unknown, unknown>,
+        watchdogAbort: AbortController,
+      ) => Promise<void>;
+      runEventLoop: () => Promise<void>;
+    };
+
+    internal.isRunning = true;
+    internal.eventSubscriptionController = globalAbort;
+    internal.sdkClient = {
+      event: {
+        subscribe: async (_parameters, options) => {
+          subscribeSignal = options?.signal;
+          return {
+            stream: (async function* () {})(),
+          };
+        },
+      },
+    };
+
+    internal.processEventStream = async (_stream, watchdogAbort) => {
+      usedWatchdog = watchdogAbort;
+      watchdogAbort.abort();
+      expect(globalAbort.signal.aborted).toBe(false);
+      globalAbort.abort();
+    };
+
+    await internal.runEventLoop();
+
+    expect(subscribeSignal).toBeDefined();
+    expect(subscribeSignal).not.toBe(globalAbort.signal);
+    expect(usedWatchdog?.signal.aborted).toBe(true);
+    expect(subscribeSignal?.aborted).toBe(true);
+  });
+
+  test("composed abort signal aborts when global controller aborts", async () => {
+    const client = new OpenCodeClient();
+    const globalAbort = new AbortController();
+    let subscribeSignal: AbortSignal | undefined;
+    let usedWatchdog: AbortController | undefined;
+
+    const internal = client as unknown as {
+      isRunning: boolean;
+      eventSubscriptionController: AbortController | null;
+      sdkClient: {
+        event: {
+          subscribe: (
+            parameters?: { directory?: string },
+            options?: { signal?: AbortSignal },
+          ) => Promise<{ stream: AsyncGenerator<unknown, unknown, unknown> }>;
+        };
+      } | null;
+      processEventStream: (
+        stream: AsyncGenerator<unknown, unknown, unknown>,
+        watchdogAbort: AbortController,
+      ) => Promise<void>;
+      runEventLoop: () => Promise<void>;
+    };
+
+    internal.isRunning = true;
+    internal.eventSubscriptionController = globalAbort;
+    internal.sdkClient = {
+      event: {
+        subscribe: async (_parameters, options) => {
+          subscribeSignal = options?.signal;
+          return {
+            stream: (async function* () {})(),
+          };
+        },
+      },
+    };
+
+    internal.processEventStream = async (_stream, watchdogAbort) => {
+      usedWatchdog = watchdogAbort;
+      globalAbort.abort();
+    };
+
+    await internal.runEventLoop();
+
+    expect(subscribeSignal).toBeDefined();
+    expect(subscribeSignal).not.toBe(globalAbort.signal);
+    expect(usedWatchdog?.signal.aborted).toBe(false);
+    expect(subscribeSignal?.aborted).toBe(true);
+  });
+});
diff --git a/src/sdk/clients/opencode.stream-abort.test.ts b/src/sdk/clients/opencode.stream-abort.test.ts
new file mode 100644
index 0000000000..91c2b7d247
--- /dev/null
+++ b/src/sdk/clients/opencode.stream-abort.test.ts
@@ -0,0 +1,148 @@
+import { describe, expect, test } from "bun:test";
+import { OpenCodeClient } from "./opencode.ts";
+
+describe("OpenCodeClient stream abort handling", () => {
+  test("terminates in-flight prompt dispatch when abortSignal fires", async () => {
+    const client = new OpenCodeClient();
+    const sessionId = "ses_stream_abort";
+    let promptSignal: AbortSignal | undefined;
+
+    (client as unknown as {
+      resolveModelContextWindow: (modelHint?: string) => Promise<number>;
+    }).resolveModelContextWindow = async () => 200_000;
+
+    (client as unknown as {
+      sdkClient: {
+        session: {
+          promptAsync: (
+            params: Record<string, unknown>,
+            options?: { signal?: AbortSignal },
+          ) => Promise<Record<string, unknown>>;
+        };
+      };
+    }).sdkClient = {
+      session: {
+        promptAsync: async (_params, options) => {
+          promptSignal = options?.signal;
+          await new Promise<never>((_resolve, reject) => {
+            if (options?.signal?.aborted) {
+              reject(new DOMException("Aborted", "AbortError"));
+              return;
+            }
+            options?.signal?.addEventListener(
+              "abort",
+              () => reject(new DOMException("Aborted", "AbortError")),
+              { once: true },
+            );
+          });
+          return {};
+        },
+      },
+    };
+
+    const session = await (client as unknown as {
+      wrapSession: (
+        sid: string,
+        config: Record<string, unknown>,
+      ) => Promise<{
+        stream: (
+          message: string,
+          options?: { agent?: string; abortSignal?: AbortSignal },
+        ) => AsyncIterable<unknown>;
+      }>;
+    }).wrapSession(sessionId, {});
+
+    const abortController = new AbortController();
+    const streamTask = (async (): Promise<void> => {
+      for await (const _chunk of session.stream("trigger", { abortSignal: abortController.signal })) {
+        // No-op
+      }
+    })();
+
+    const abortTimer = setTimeout(() => abortController.abort(), 10);
+    let timeoutId: ReturnType<typeof setTimeout> | undefined;
+
+    try {
+      await Promise.race([
+        streamTask,
+        new Promise<never>((_resolve, reject) => {
+          timeoutId = setTimeout(() => reject(new Error("stream did not stop after abort")), 200);
+        }),
+      ]);
+    } finally {
+      clearTimeout(abortTimer);
+      if (timeoutId) clearTimeout(timeoutId);
+    }
+
+    expect(promptSignal).toBe(abortController.signal);
+  });
+
+  test("skips post-compaction continue dispatch when stream is aborted", async () => {
+    const client = new OpenCodeClient();
+    const sessionId = "ses_stream_abort_before_continue_dispatch";
+
+    (client as unknown as {
+      resolveModelContextWindow: (modelHint?: string) => Promise<number>;
+    }).resolveModelContextWindow = async () => 200_000;
+
+    const promptCalls: string[] = [];
+    const abortController = new AbortController();
+
+    (client as unknown as {
+      sdkClient: {
+        session: {
+          promptAsync: (
+            params: Record<string, unknown>,
+            options?: { signal?: AbortSignal },
+          ) => Promise<Record<string, unknown>>;
+          summarize: (params: Record<string, unknown>) => Promise<Record<string, never>>;
+          messages: (params: Record<string, unknown>) => Promise<{ data: unknown[] }>;
+        };
+      };
+    }).sdkClient = {
+      session: {
+        promptAsync: async (params, options) => {
+          const parts = ((params.parts as Array<{ type?: string; text?: string }> | undefined) ?? []);
+          const textPart = parts.find((part) => part.type === "text");
+          promptCalls.push(textPart?.text ?? "");
+          expect(options?.signal).toBe(abortController.signal);
+          return {
+            error: {
+              message: "context_length_exceeded",
+            },
+          };
+        },
+        summarize: async () => {
+          abortController.abort();
+          return {};
+        },
+        messages: async () => ({ data: [] }),
+      },
+    };
+
+    const session = await (client as unknown as {
+      wrapSession: (
+        sid: string,
+        config: Record<string, unknown>,
+      ) => Promise<{
+        stream: (
+          message: string,
+          options?: { agent?: string; abortSignal?: AbortSignal },
+        ) => AsyncIterable<unknown>;
+      }>;
+    }).wrapSession(sessionId, {});
+
+    await Promise.race([
+      (async () => {
+        for await (const _chunk of session.stream("trigger overflow", { abortSignal: abortController.signal })) {
+          // No-op
+        }
+      })(),
+      new Promise<never>((_resolve, reject) => {
+        setTimeout(() => reject(new Error("stream did not stop after compaction abort")), 300);
+      }),
+    ]);
+
+    expect(promptCalls).toEqual(["trigger overflow"]);
+  });
+});
diff --git a/src/sdk/clients/opencode.ts b/src/sdk/clients/opencode.ts
index 10034f62ad..abfaa3be34 100644
--- a/src/sdk/clients/opencode.ts
+++ b/src/sdk/clients/opencode.ts
@@ -53,6 +53,7 @@ import {
   type SessionConfig,
   type AgentMessage,
   type ContextUsage,
+  type SessionCompactionState,
   type McpRuntimeSnapshot,
   type EventType,
   type EventHandler,
@@ -62,7 +63,16 @@ import {
 } from "../types.ts";
 
 import { initOpenCodeConfigOverrides } from "../init.ts";
-import { createToolMcpServerScript } from "../tools/opencode-mcp-bridge.ts";
+import {
+  createToolMcpServerScript,
+  startToolDispatchServer,
+  stopToolDispatchServer,
+} from "../tools/opencode-mcp-bridge.ts";
+import { BACKGROUND_COMPACTION_THRESHOLD } from "../../workflows/graph/types.ts";
+import {
+  incrementRuntimeParityCounter,
+  runtimeParityDebug,
+} from "../../workflows/runtime-parity-observability.ts";
 
 // Import the real SDK
 import {
@@ -108,12 +118,334 @@ export interface OpenCodeSdkEvent {
 const DEFAULT_OPENCODE_BASE_URL = "http://localhost:4096";
 const DEFAULT_MAX_RETRIES = 3;
 const DEFAULT_RETRY_DELAY = 1000;
+const PRE_PROMPT_TERMINAL_SETTLE_MS = 500;
+export const AUTO_COMPACTION_THRESHOLD = BACKGROUND_COMPACTION_THRESHOLD;
+export const MAX_COMPACTION_WAIT_MS = 15_000;
+export const COMPACTION_TERMINAL_ERROR_MESSAGE = "Compaction failed, please start a new chat.";
+const COMPACTION_COMPLETE_DEDUPE_WINDOW_MS = 1000;
+const SESSION_LIFECYCLE_EVENT_TYPES = new Set<string>([
+  "session.created",
+  "session.updated",
+  "session.status",
+  "session.idle",
+  "session.error",
+  "session.deleted",
+]);
+const OPENCODE_SSE_DIAGNOSTICS_MARKER = "opencode.sse.diagnostics";
+
+type OpenCodeSseDiagnosticsCounter =
+  | "sse.watchdog.timeout.count"
+  | "sse.event.filtered.count"
+  | "sse.abort.watchdog.count"
+  | "sse.abort.global.count"
+  | "sse.abort.unknown.count";
+
+type OpenCodeSseAbortReason = "watchdog" | "global" | "unknown";
+
+type OpenCodeSessionStatus = "idle" | "busy" | "retry";
+export type OpenCodeCompactionControlState = "STREAMING" | "COMPACTING" | "TERMINAL_ERROR" | "ENDED";
+export type OpenCodeCompactionErrorCode =
+  | "COMPACTION_TIMEOUT"
+  | "COMPACTION_FAILED"
+  | "COMPACTION_INVALID_STATE";
+
+interface OpenCodeCompactionControl {
+  state: OpenCodeCompactionControlState;
+  startedAt: number | null;
+  errorCode?: OpenCodeCompactionErrorCode;
+  errorMessage?: string;
+}
+
+interface OpenCodeSubagentSessionState {
+  pendingAgentParts: Array<{ partId: string; agentName: string }>;
+  childSessionToAgentPart: Map<string, string>;
+  startedSubagentIds: Set<string>;
+  subagentToolCounts: Map<string, number>;
+  pendingTaskToolPartIds: string[];
+  queuedTaskToolPartIds: Set<string>;
+}
+
+interface OpenCodeSessionCompactionState {
+  isCompacting: boolean;
+  hasAutoCompacted: boolean;
+  pendingCompactionComplete: boolean;
+  lastCompactionCompleteAt: number | null;
+  control: OpenCodeCompactionControl;
+}
+
+interface OpenCodeSessionState {
+  inputTokens: number;
+  outputTokens: number;
+  isClosed: boolean;
+  contextWindow: number | null;
+  systemToolsBaseline: number | null;
+  compaction: OpenCodeSessionCompactionState;
+}
+
+function parseOpenCodeSessionStatus(status: unknown): OpenCodeSessionStatus | undefined {
+  if (status === "idle" || status === "busy" || status === "retry") {
+    return status;
+  }
+
+  if (typeof status !== "object" || status === null) {
+    return undefined;
+  }
+
+  const statusRecord = status as {
+    type?: unknown;
+    status?: unknown;
+    value?: unknown;
+  };
+
+  const candidates = [statusRecord.type, statusRecord.status, statusRecord.value];
+  for (const candidate of candidates) {
+    if (candidate === "idle" || candidate === "busy" || candidate === "retry") {
+      return candidate;
+    }
+  }
+
+  return undefined;
+}
+
+function asErrorRecord(value: unknown): Record<string, unknown> | undefined {
+  if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+    return value as Record<string, unknown>;
+  }
+  return undefined;
+}
+
+function asNonEmptyErrorString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim().length > 0
+    ? value
+    : undefined;
+}
+
+export class OpenCodeCompactionError extends Error {
+  readonly code: OpenCodeCompactionErrorCode;
+
+  constructor(code: OpenCodeCompactionErrorCode, message: string) {
+    super(message);
+    this.name = "OpenCodeCompactionError";
+    this.code = code;
+  }
+}
+
+type OpenCodeCompactionControlEvent =
+  | "stream.start"
+  | "compaction.start"
+  | "compaction.complete.success"
+  | "compaction.complete.error"
+  | "turn.ended";
+
+export function transitionOpenCodeCompactionControl(
+  current: OpenCodeCompactionControl,
+  event: OpenCodeCompactionControlEvent,
+  options?: {
+    now?: number;
+    errorCode?: OpenCodeCompactionErrorCode;
+    errorMessage?: string;
+  },
+): OpenCodeCompactionControl {
+  const now = options?.now ?? Date.now();
+
+  switch (event) {
+    case "stream.start":
+      return { state: "STREAMING", startedAt: null };
+    case "compaction.start":
+      if (current.state !== "STREAMING") {
+        throw new OpenCodeCompactionError(
+          "COMPACTION_INVALID_STATE",
+          COMPACTION_TERMINAL_ERROR_MESSAGE,
+        );
+      }
+      return { state: "COMPACTING", startedAt: now };
+    case "compaction.complete.success":
+      if (current.state === "TERMINAL_ERROR" || current.state === "ENDED") {
+        return current;
+      }
+      return { state: "STREAMING", startedAt: null };
+    case "compaction.complete.error":
+      if (current.state === "TERMINAL_ERROR" || current.state === "ENDED") {
+        return current;
+      }
+      if (current.state !== "COMPACTING") {
+        throw new OpenCodeCompactionError(
+          "COMPACTION_INVALID_STATE",
+          COMPACTION_TERMINAL_ERROR_MESSAGE,
+        );
+      }
+      return {
+        state: "TERMINAL_ERROR",
+        startedAt: current.startedAt ?? now,
+        errorCode: options?.errorCode ?? "COMPACTION_FAILED",
+        errorMessage: options?.errorMessage ?? COMPACTION_TERMINAL_ERROR_MESSAGE,
+      };
+    case "turn.ended":
+      if (current.state !== "TERMINAL_ERROR") {
+        return current;
+      }
+      return {
+        state: "ENDED",
+        startedAt: current.startedAt,
+        errorCode: current.errorCode,
+        errorMessage: current.errorMessage,
+      };
+    default:
+      return current;
+  }
+}
+
+function setCompactionControlState(
+  sessionState: OpenCodeSessionState,
+  event: OpenCodeCompactionControlEvent,
+  options?: {
+    now?: number;
+    errorCode?: OpenCodeCompactionErrorCode;
+    errorMessage?: string;
+  },
+): void {
+  sessionState.compaction.control = transitionOpenCodeCompactionControl(
+    sessionState.compaction.control,
+    event,
+    options,
+  );
+  sessionState.compaction.isCompacting = sessionState.compaction.control.state === "COMPACTING";
+}
+
+function toOpenCodeCompactionTerminalError(error: unknown): OpenCodeCompactionError {
+  if (error instanceof OpenCodeCompactionError) {
+    return error;
+  }
+  return new OpenCodeCompactionError(
+    "COMPACTION_FAILED",
+    COMPACTION_TERMINAL_ERROR_MESSAGE,
+  );
+}
+
+export function emitOpenCodeCompactionContractFailureObservability(args: {
+  sessionId: string;
+  code: OpenCodeCompactionErrorCode;
+  sourceError: string;
+  terminalError: string;
+}): void {
+  incrementRuntimeParityCounter("workflow.runtime.parity.compaction_timeout_terminated_total", {
+    provider: "opencode",
+    code: args.code,
+  });
+  incrementRuntimeParityCounter("workflow.runtime.parity.turn_terminated_due_to_contract_error_total", {
+    provider: "opencode",
+    reason: "compaction_terminal_error",
+    code: args.code,
+  });
+  runtimeParityDebug("compaction_contract_failure", {
+    provider: "opencode",
+    sessionId: args.sessionId,
+    code: args.code,
+    sourceError: args.sourceError,
+    terminalError: args.terminalError,
+  });
+}
+
+async function withCompactionTimeout<T>(operation: Promise<T>): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  try {
+    return await Promise.race([
+      operation,
+      new Promise<T>((_resolve, reject) => {
+        timer = setTimeout(() => {
+          reject(
+            new OpenCodeCompactionError(
+              "COMPACTION_TIMEOUT",
+              COMPACTION_TERMINAL_ERROR_MESSAGE,
+            ),
+          );
+        }, MAX_COMPACTION_WAIT_MS);
+      }),
+    ]);
+  } finally {
+    if (timer) {
+      clearTimeout(timer);
+    }
+  }
+}
+
+const CONTEXT_OVERFLOW_PATTERNS = [
+  "contextoverflowerror",
+  "context_length_exceeded",
+  "context length exceeded",
+  "context window",
+  "maximum context length",
+  "input is too long",
+  "input exceeds context window",
+  "exceeds the model's maximum context",
+  "token limit",
+  "too many tokens",
+  "request too large",
+  "prompt is too long",
+];
+
+export function isContextOverflowError(error: Error | string): boolean {
+  const message = typeof error === "string" ? error : error.message;
+  const normalizedMessage = message.trim().toLowerCase();
+  if (!normalizedMessage) {
+    return false;
+  }
+
+  return CONTEXT_OVERFLOW_PATTERNS.some((pattern) => normalizedMessage.includes(pattern));
+}
+
+function extractOpenCodeErrorMessage(error: unknown, fallback = "Unknown error"): string {
+  if (error instanceof Error) {
+    return error.message;
+  }
+
+  const direct = asNonEmptyErrorString(error);
+  if (direct) {
+    return direct;
+  }
+
+  const record = asErrorRecord(error);
+  if (!record) {
+    return fallback;
+  }
+
+  const directFields = [
+    record.message,
+    record.error,
+    record.details,
+    record.reason,
+    record.stderr,
+    record.stdout,
+  ];
+
+  for (const field of directFields) {
+    const value = asNonEmptyErrorString(field);
+    if (value) {
+      return value;
+    }
+  }
+
+  if (Array.isArray(record.errors) && record.errors.length > 0) {
+    const entries = record.errors
+      .map((entry) => extractOpenCodeErrorMessage(entry, ""))
+      .filter((entry) => entry.length > 0);
+    if (entries.length > 0) {
+      return entries.join("; ");
+    }
+  }
+
+  try {
+    return JSON.stringify(record);
+  } catch {
+    return fallback;
+  }
+}
 
 /**
- * Debug logging helper gated behind ATOMIC_DEBUG environment variable
+ * Debug logging helper gated behind DEBUG environment variable
  * Used to verify event emission at runtime during development
  */
-const debugLog = process.env.ATOMIC_DEBUG
+const debugLog = process.env.DEBUG === "1"
   ? (label: string, data: Record<string, unknown>) =>
       console.debug(`[opencode:${label}]`, JSON.stringify(data, null, 2))
   : () => {};
@@ -355,6 +687,7 @@ export class OpenCodeClient implements CodingAgentClient {
   private eventHandlers: Map<EventType, Set<EventHandler<EventType>>> =
     new Map();
   private activeSessions: Set<string> = new Set();
+  private sessionStateById = new Map<string, OpenCodeSessionState>();
   private registeredTools: Map<string, ToolDefinition> = new Map();
   private isRunning = false;
   private isConnected = false;
@@ -362,6 +695,14 @@ export class OpenCodeClient implements CodingAgentClient {
   private eventSubscriptionController: AbortController | null = null;
   private serverCloseCallback: (() => void) | null = null;
   private isServerSpawned = false;
+  private dispatchServerStop: (() => void) | null = null;
+  private readonly sseDiagnosticsCounters: Record<OpenCodeSseDiagnosticsCounter, number> = {
+    "sse.watchdog.timeout.count": 0,
+    "sse.event.filtered.count": 0,
+    "sse.abort.watchdog.count": 0,
+    "sse.abort.global.count": 0,
+    "sse.abort.unknown.count": 0,
+  };
 
   /** Mutable model preference updated by /model command at runtime */
   private activePromptModel: { providerID: string; modelID: string } | undefined;
@@ -369,6 +710,29 @@ export class OpenCodeClient implements CodingAgentClient {
   /** Mutable context window updated when activePromptModel changes */
   private activeContextWindow: number | null = null;
 
+  /**
+   * Sub-agent session tracking scoped by parent session ID.
+   *
+   * The OpenCode SDK's AgentPart/SubtaskPart carry `sessionID` referencing
+   * the PARENT session (where the part was created), not the child session.
+   * In parallel workflows multiple parent sessions can stream concurrently, so
+   * all correlation state must be partitioned per parent session.
+   */
+  private subagentStateByParentSession = new Map<string, OpenCodeSubagentSessionState>();
+  private childSessionToParentSession = new Map<string, string>();
+
+  /**
+   * Track reasoning part IDs so `message.part.delta` can distinguish
+   * reasoning deltas from text deltas (the delta event only carries a
+   * partID, not the part type).
+   */
+  private reasoningPartIds = new Set<string>();
+
+  /**
+   * Track message roles so part events can distinguish user @mentions
+   * from assistant-emitted sub-agent lifecycle parts.
+   */
+  private messageRolesBySession = new Map<string, Map<string, "user" | "assistant">>();
 
   /**
    * Create a new OpenCodeClient
@@ -405,7 +769,7 @@ export class OpenCodeClient implements CodingAgentClient {
         if (result.error) {
           return {
             healthy: false,
-            error: String(result.error),
+            error: extractOpenCodeErrorMessage(result.error),
           };
         }
         return {
@@ -418,7 +782,7 @@ export class OpenCodeClient implements CodingAgentClient {
       if (result.error) {
         return {
           healthy: false,
-          error: String(result.error),
+          error: extractOpenCodeErrorMessage(result.error),
         };
       }
       return {
@@ -508,10 +872,15 @@ export class OpenCodeClient implements CodingAgentClient {
       }
     }
     this.activeSessions.clear();
+    this.sessionStateById.clear();
 
     this.isConnected = false;
     this.sdkClient = null;
     this.currentSessionId = null;
+    this.subagentStateByParentSession.clear();
+    this.childSessionToParentSession.clear();
+    this.reasoningPartIds.clear();
+    this.messageRolesBySession.clear();
 
     this.emitEvent("session.idle", "connection", { reason: "disconnected" });
   }
@@ -560,46 +929,453 @@ export class OpenCodeClient implements CodingAgentClient {
   private async subscribeToSdkEvents(): Promise<void> {
     if (!this.sdkClient) return;
 
-    try {
-      this.eventSubscriptionController = new AbortController();
+    this.eventSubscriptionController = new AbortController();
 
-      const result = await this.sdkClient.event.subscribe({
-        directory: this.clientOptions.directory,
-      });
+    // Start the resilient event loop — it will auto-reconnect on failures.
+    // Mirrors the pattern used in OpenCode's own TUI client (global-sdk.tsx).
+    this.runEventLoop().catch((error) => {
+      if (error?.name !== "AbortError") {
+        console.error("SSE event loop terminated:", error);
+      }
+    });
+  }
 
-      // The SDK returns { stream: AsyncGenerator } - extract the stream
-      const eventStream = result.stream;
+  /**
+   * Resilient SSE event loop that auto-reconnects on failures.
+   * Keeps the SSE connection alive as long as the client is running
+   * (i.e. until `eventSubscriptionController` is aborted via `disconnect()`).
+   *
+   * Uses a flat reconnect delay (250ms) since the SDK's `createSseClient`
+   * already implements exponential backoff for connection-level retries.
+   */
+  private async runEventLoop(): Promise<void> {
+    const SSE_RECONNECT_DELAY_MS = 250;
+    let isReconnect = false;
 
-      // Process events in background
-      this.processEventStream(eventStream).catch((error) => {
-        // Only log if not aborted
-        if (error?.name !== "AbortError") {
-          console.error("SSE event stream error:", error);
+    while (!this.eventSubscriptionController?.signal.aborted && this.isRunning) {
+      try {
+        const watchdogAbort = new AbortController();
+        const globalAbortSignal = this.eventSubscriptionController?.signal;
+        if (!globalAbortSignal) break;
+        const composedAbortSignal = AbortSignal.any([
+          globalAbortSignal,
+          watchdogAbort.signal,
+        ]);
+
+        const result = await this.sdkClient!.event.subscribe(
+          {
+            directory: this.clientOptions.directory,
+          },
+          {
+            signal: composedAbortSignal,
+          },
+        );
+
+        // On reconnection, reconcile state to recover any events missed during the gap
+        if (isReconnect) {
+          await this.reconcileStateOnReconnect();
         }
-      });
+
+        await this.processEventStream(result.stream, watchdogAbort);
+
+        // Generator ended normally — if not aborted, reconnect
+        if (this.eventSubscriptionController?.signal.aborted) break;
+        isReconnect = true;
+      } catch (error) {
+        if ((error as Error)?.name === "AbortError") break;
+        if (this.eventSubscriptionController?.signal.aborted) break;
+
+        console.error("SSE connection error, reconnecting:", error);
+        isReconnect = true;
+      }
+
+      // Brief delay before reconnecting (SDK handles exponential backoff internally)
+      if (!this.eventSubscriptionController?.signal.aborted && this.isRunning) {
+        await new Promise((resolve) => setTimeout(resolve, SSE_RECONNECT_DELAY_MS));
+      }
+    }
+  }
+
+  /**
+   * Reconcile state after SSE reconnection.
+   *
+   * Re-fetches session list from the server and re-emits current state so the
+   * UI is in sync after any events missed during the connection gap.
+   * Modeled after OpenCode's bootstrap() call on server.connected.
+   */
+  private async reconcileStateOnReconnect(): Promise<void> {
+    try {
+      const sessions = await this.listSessions();
+      for (const session of sessions) {
+        this.registerActiveSession(session.id);
+        this.emitEvent("session.start", session.id, {
+          title: session.title ?? "Reconnected session",
+        });
+      }
     } catch (error) {
-      console.error("Failed to subscribe to events:", error);
+      console.warn("State reconciliation failed after reconnect:", error);
     }
   }
 
   /**
-   * Process SSE event stream
+   * Process SSE event stream with heartbeat watchdog.
+   *
+   * Tracks the last event timestamp and aborts the connection if no events
+   * arrive within the watchdog timeout (15s). This detects dead SSE
+   * connections proactively — the server sends heartbeats every ~10s.
    */
   private async processEventStream(
-    eventStream: AsyncGenerator<unknown, unknown, unknown>
+    eventStream: AsyncGenerator<unknown, unknown, unknown>,
+    watchdogAbort: AbortController,
   ): Promise<void> {
+    const HEARTBEAT_TIMEOUT_MS = 15_000;
+    let lastEventAt = Date.now();
+    let watchdogTimer: ReturnType<typeof setTimeout> | null = null;
+    let filteredEventCount = 0;
+    let abortDiagnosticsEmitted = false;
+
+    const resetWatchdog = () => {
+      lastEventAt = Date.now();
+      if (watchdogTimer) clearTimeout(watchdogTimer);
+      watchdogTimer = setTimeout(() => {
+        const elapsed = Date.now() - lastEventAt;
+        if (elapsed >= HEARTBEAT_TIMEOUT_MS) {
+          const timeoutCount = this.emitSseDiagnosticsCounter("sse.watchdog.timeout.count");
+          console.warn(
+            `SSE heartbeat timeout: no events for ${elapsed}ms, forcing reconnect (timeoutCount=${timeoutCount})`,
+          );
+          debugLog("sse-watchdog-timeout", {
+            elapsed,
+            timeoutCount,
+            activeSessions: this.activeSessions.size,
+          });
+          watchdogAbort.abort();
+        }
+      }, HEARTBEAT_TIMEOUT_MS);
+    };
+
+    resetWatchdog();
+
     try {
       for await (const event of eventStream) {
-        if (this.eventSubscriptionController?.signal.aborted) {
+        if (this.eventSubscriptionController?.signal.aborted || watchdogAbort.signal.aborted) {
+          const abortReason: OpenCodeSseAbortReason = watchdogAbort.signal.aborted
+            ? "watchdog"
+            : this.eventSubscriptionController?.signal.aborted
+              ? "global"
+              : "unknown";
+          const abortCount = this.emitSseAbortDiagnostics(abortReason);
+          abortDiagnosticsEmitted = true;
+          debugLog("sse-abort", {
+            reason: abortReason,
+            abortCount,
+            activeSessions: this.activeSessions.size,
+          });
           break;
         }
-        this.handleSdkEvent(event as Record<string, unknown>);
+        resetWatchdog();
+        const sdkEvent = event as Record<string, unknown>;
+        if (!this.shouldProcessSseEvent(sdkEvent)) {
+          filteredEventCount += 1;
+          continue;
+        }
+        this.handleSdkEvent(sdkEvent);
       }
     } catch (error) {
       if ((error as Error)?.name !== "AbortError") {
         throw error;
       }
+      if (!abortDiagnosticsEmitted) {
+        const abortReason: OpenCodeSseAbortReason = watchdogAbort.signal.aborted
+          ? "watchdog"
+          : this.eventSubscriptionController?.signal.aborted
+            ? "global"
+            : "unknown";
+        const abortCount = this.emitSseAbortDiagnostics(abortReason);
+        debugLog("sse-abort", {
+          reason: abortReason,
+          abortCount,
+          activeSessions: this.activeSessions.size,
+        });
+      }
+    } finally {
+      if (watchdogTimer) clearTimeout(watchdogTimer);
+      if (filteredEventCount > 0) {
+        const totalFilteredCount = this.emitSseDiagnosticsCounter(
+          "sse.event.filtered.count",
+          filteredEventCount,
+        );
+        debugLog("sse-event-filter", {
+          filteredEventCount,
+          totalFilteredCount,
+          activeSessions: this.activeSessions.size,
+        });
+      }
+    }
+  }
+
+  private emitSseDiagnosticsCounter(
+    counter: OpenCodeSseDiagnosticsCounter,
+    amount = 1,
+  ): number {
+    this.sseDiagnosticsCounters[counter] += amount;
+    const value = this.sseDiagnosticsCounters[counter];
+    this.emitEvent("usage", "connection", {
+      provider: "opencode",
+      marker: OPENCODE_SSE_DIAGNOSTICS_MARKER,
+      counter,
+      value,
+    });
+    return value;
+  }
+
+  private emitSseAbortDiagnostics(reason: OpenCodeSseAbortReason): number {
+    if (reason === "watchdog") {
+      return this.emitSseDiagnosticsCounter("sse.abort.watchdog.count");
+    }
+    if (reason === "global") {
+      return this.emitSseDiagnosticsCounter("sse.abort.global.count");
+    }
+    return this.emitSseDiagnosticsCounter("sse.abort.unknown.count");
+  }
+
+  private registerActiveSession(sessionId: string): void {
+    if (!sessionId) return;
+    this.activeSessions.add(sessionId);
+  }
+
+  private setSessionParentMapping(
+    sessionId: string,
+    parentSessionId: string | undefined,
+  ): void {
+    if (!sessionId) return;
+    if (parentSessionId && parentSessionId !== sessionId) {
+      this.childSessionToParentSession.set(sessionId, parentSessionId);
+      return;
+    }
+    this.childSessionToParentSession.delete(sessionId);
+  }
+
+  private unregisterActiveSession(sessionId: string): void {
+    if (!sessionId) return;
+    this.activeSessions.delete(sessionId);
+    this.sessionStateById.delete(sessionId);
+    this.messageRolesBySession.delete(sessionId);
+    this.clearSubagentSessionState(sessionId);
+    if (this.currentSessionId === sessionId) {
+      this.currentSessionId = null;
+    }
+  }
+
+  private isSessionLifecycleEventType(eventType: string): boolean {
+    return SESSION_LIFECYCLE_EVENT_TYPES.has(eventType);
+  }
+
+  private extractEventSessionCandidates(event: Record<string, unknown>): string[] {
+    const properties = event.properties as Record<string, unknown> | undefined;
+    const info = properties?.info as { id?: string; sessionID?: string } | undefined;
+    const part = properties?.part as { sessionID?: string } | undefined;
+    const candidates = [
+      properties?.sessionID,
+      info?.id,
+      info?.sessionID,
+      part?.sessionID,
+    ];
+    return Array.from(
+      new Set(
+        candidates
+          .filter((value): value is string => typeof value === "string")
+          .filter((value) => value.length > 0),
+      ),
+    );
+  }
+
+  private shouldProcessSseEvent(event: Record<string, unknown>): boolean {
+    const eventType = event.type as string | undefined;
+    if (!eventType || this.isSessionLifecycleEventType(eventType)) {
+      return true;
+    }
+
+    const sessionCandidates = this.extractEventSessionCandidates(event);
+    if (sessionCandidates.length === 0) {
+      return true;
+    }
+
+    for (const sessionId of sessionCandidates) {
+      if (this.activeSessions.has(sessionId)) {
+        return true;
+      }
+      const parentSessionId = this.childSessionToParentSession.get(sessionId);
+      if (parentSessionId && this.activeSessions.has(parentSessionId)) {
+        return true;
+      }
+    }
+
+    // Child-session sub-agent part events can arrive before we can map the
+    // child session to a parent. This is common during parallel task dispatch
+    // where multiple child sessions start nearly simultaneously.
+    // Allow these events through when we have a scoped current session so
+    // findParentSessionForPart() can recover parent attribution.
+    if (
+      this.currentSessionId
+      && (eventType === "message.part.updated" || eventType === "message.part.delta")
+    ) {
+      const properties = event.properties as Record<string, unknown> | undefined;
+      const part = properties?.part as { sessionID?: unknown } | undefined;
+      if (typeof part?.sessionID === "string" && part.sessionID.length > 0) {
+        return true;
+      }
     }
+
+    return false;
+  }
+
+  private createSubagentSessionState(): OpenCodeSubagentSessionState {
+    return {
+      pendingAgentParts: [],
+      childSessionToAgentPart: new Map(),
+      startedSubagentIds: new Set(),
+      subagentToolCounts: new Map(),
+      pendingTaskToolPartIds: [],
+      queuedTaskToolPartIds: new Set(),
+    };
+  }
+
+  private getSubagentSessionState(parentSessionId: string): OpenCodeSubagentSessionState {
+    let state = this.subagentStateByParentSession.get(parentSessionId);
+    if (!state) {
+      state = this.createSubagentSessionState();
+      this.subagentStateByParentSession.set(parentSessionId, state);
+    }
+    return state;
+  }
+
+  private findParentSessionForPart(
+    properties: Record<string, unknown> | undefined,
+    partSessionId: string,
+  ): string {
+    const envelopeSessionId = (properties?.sessionID as string | undefined) ?? "";
+    if (envelopeSessionId) {
+      return envelopeSessionId;
+    }
+
+    const mappedParent = this.childSessionToParentSession.get(partSessionId);
+    if (mappedParent) {
+      return mappedParent;
+    }
+
+    // Heuristic fallback: when exactly one parent session currently has
+    // pending agent/subtask parts awaiting child-session discovery, attribute
+    // unknown child tool parts to that parent instead of the child session.
+    // This recovers parent linkage when session.created(parentID) arrives late.
+    if (partSessionId) {
+      const pendingParentCandidates: string[] = [];
+      for (const [candidateSessionId, state] of this.subagentStateByParentSession.entries()) {
+        if (candidateSessionId === partSessionId) continue;
+        if (state.pendingAgentParts.length === 0) continue;
+        pendingParentCandidates.push(candidateSessionId);
+        if (pendingParentCandidates.length > 1) break;
+      }
+      if (pendingParentCandidates.length === 1) {
+        return pendingParentCandidates[0]!;
+      }
+    }
+
+    if (partSessionId) {
+      if (this.activeSessions.has(partSessionId)) {
+        return partSessionId;
+      }
+
+      // Older OpenCode payloads sometimes omit envelope sessionID for child
+      // tool parts. Fall back to the current scoped parent session so child
+      // discovery can still register subagentSessionId correlation.
+      if (
+        this.currentSessionId &&
+        this.currentSessionId !== partSessionId
+      ) {
+        return this.currentSessionId;
+      }
+
+      return partSessionId;
+    }
+
+    return this.currentSessionId ?? "";
+  }
+
+  private enqueuePendingTaskToolPartId(
+    state: OpenCodeSubagentSessionState,
+    taskPartId: string,
+  ): void {
+    if (state.queuedTaskToolPartIds.has(taskPartId)) return;
+    state.pendingTaskToolPartIds.push(taskPartId);
+    state.queuedTaskToolPartIds.add(taskPartId);
+  }
+
+  private dequeuePendingTaskToolPartId(
+    state: OpenCodeSubagentSessionState,
+  ): string | undefined {
+    const taskPartId = state.pendingTaskToolPartIds.shift();
+    if (taskPartId) {
+      state.queuedTaskToolPartIds.delete(taskPartId);
+    }
+    return taskPartId;
+  }
+
+  private removePendingTaskToolPartId(
+    state: OpenCodeSubagentSessionState,
+    taskPartId: string,
+  ): void {
+    const idx = state.pendingTaskToolPartIds.indexOf(taskPartId);
+    if (idx !== -1) {
+      state.pendingTaskToolPartIds.splice(idx, 1);
+    }
+    state.queuedTaskToolPartIds.delete(taskPartId);
+  }
+
+  private clearSubagentSessionState(parentSessionId: string): void {
+    const state = this.subagentStateByParentSession.get(parentSessionId);
+    if (state) {
+      for (const childSessionId of state.childSessionToAgentPart.keys()) {
+        this.childSessionToParentSession.delete(childSessionId);
+      }
+      this.subagentStateByParentSession.delete(parentSessionId);
+    }
+
+    const ownerParent = this.childSessionToParentSession.get(parentSessionId);
+    if (!ownerParent) return;
+
+    const ownerState = this.subagentStateByParentSession.get(ownerParent);
+    if (ownerState) {
+      const agentPartId = ownerState.childSessionToAgentPart.get(parentSessionId);
+      ownerState.childSessionToAgentPart.delete(parentSessionId);
+      if (agentPartId) {
+        ownerState.startedSubagentIds.delete(agentPartId);
+        ownerState.subagentToolCounts.delete(agentPartId);
+      }
+    }
+    this.childSessionToParentSession.delete(parentSessionId);
+  }
+
+  private setMessageRole(
+    sessionId: string,
+    messageId: string,
+    role: "user" | "assistant",
+  ): void {
+    if (!sessionId || !messageId) return;
+    let roles = this.messageRolesBySession.get(sessionId);
+    if (!roles) {
+      roles = new Map<string, "user" | "assistant">();
+      this.messageRolesBySession.set(sessionId, roles);
+    }
+    roles.set(messageId, role);
+  }
+
+  private getMessageRole(
+    sessionId: string,
+    messageId: string,
+  ): "user" | "assistant" | undefined {
+    if (!sessionId || !messageId) return undefined;
+    return this.messageRolesBySession.get(sessionId)?.get(messageId);
   }
 
   /**
@@ -614,158 +1390,479 @@ export class OpenCodeClient implements CodingAgentClient {
       case "session.created":
         // OpenCode emits session ID under properties.info.id (not properties.sessionID).
         // Fall back to sessionID for defensive compatibility with older payloads.
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        this.emitEvent(
-          "session.start",
-          ((properties?.info as any)?.id as string) ?? (properties?.sessionID as string) ?? "",
-          {
+        {
+          const createdInfo = properties?.info as { id?: string; sessionID?: string; parentID?: string } | undefined;
+          const createdSessionId = createdInfo?.id ?? (properties?.sessionID as string) ?? "";
+          this.setSessionParentMapping(
+            createdSessionId,
+            typeof createdInfo?.parentID === "string" ? createdInfo.parentID : undefined,
+          );
+          this.registerActiveSession(createdSessionId);
+          this.emitEvent("session.start", createdSessionId, {
             config: {},
-          }
+          });
+        }
+        break;
+
+      case "session.updated": {
+        const updatedInfo = properties?.info as { id?: string; parentID?: string } | undefined;
+        const updatedSessionId = updatedInfo?.id ?? (properties?.sessionID as string) ?? "";
+        this.setSessionParentMapping(
+          updatedSessionId,
+          typeof updatedInfo?.parentID === "string" ? updatedInfo.parentID : undefined,
         );
+        this.registerActiveSession(updatedSessionId);
         break;
+      }
 
-      case "session.idle":
-        this.emitEvent(
-          "session.idle",
-          (properties?.sessionID as string) ?? "",
-          {
+      case "session.deleted": {
+        const deletedInfo = properties?.info as { id?: string } | undefined;
+        const deletedSessionId = (properties?.sessionID as string) ?? deletedInfo?.id ?? "";
+        this.unregisterActiveSession(deletedSessionId);
+        break;
+      }
+
+      case "session.status": {
+        const status = parseOpenCodeSessionStatus(properties?.status);
+        // OpenCode payloads can carry the session ID either at sessionID or info.id.
+        const info = properties?.info as { id?: string } | undefined;
+        const statusSessionId = (properties?.sessionID as string) ?? info?.id ?? "";
+        this.registerActiveSession(statusSessionId);
+
+        if (status === "idle") {
+          this.emitEvent("session.idle", statusSessionId, {
             reason: "idle",
-          }
-        );
+          });
+        }
+        break;
+      }
+
+      case "session.idle":
+        // OpenCode payloads can carry the session ID either at sessionID or info.id.
+        // Prefer sessionID and fall back to info.id for compatibility across SDK versions.
+        {
+          const idleInfo = properties?.info as { id?: string } | undefined;
+          const idleSessionId = (properties?.sessionID as string) ?? idleInfo?.id ?? "";
+          this.registerActiveSession(idleSessionId);
+          this.emitEvent(
+            "session.idle",
+            idleSessionId,
+            {
+              reason: "idle",
+            }
+          );
+        }
         break;
 
       case "session.error":
-        this.emitEvent(
-          "session.error",
-          (properties?.sessionID as string) ?? "",
-          {
-            error: properties?.error ?? "Unknown error",
+        {
+          const errorInfo = properties?.info as { id?: string } | undefined;
+          const errorSessionId = (properties?.sessionID as string) ?? errorInfo?.id ?? "";
+          this.registerActiveSession(errorSessionId);
+          this.emitEvent(
+            "session.error",
+            errorSessionId,
+            {
+              error: extractOpenCodeErrorMessage(
+                properties?.error ?? event.error,
+              ),
+            }
+          );
+        }
+        break;
+
+      case "session.compacted":
+        {
+          const compactedSessionId = (properties?.sessionID as string) ?? "";
+          const sessionState = this.sessionStateById.get(compactedSessionId);
+          if (
+            sessionState
+            && (
+              sessionState.compaction.control.state === "TERMINAL_ERROR"
+              || sessionState.compaction.control.state === "ENDED"
+            )
+          ) {
+            break;
           }
-        );
+          const now = Date.now();
+          if (
+            sessionState
+            && !sessionState.compaction.pendingCompactionComplete
+            && sessionState.compaction.lastCompactionCompleteAt !== null
+            && now - sessionState.compaction.lastCompactionCompleteAt <= COMPACTION_COMPLETE_DEDUPE_WINDOW_MS
+          ) {
+            break;
+          }
+          if (sessionState) {
+            sessionState.compaction.pendingCompactionComplete = false;
+            sessionState.compaction.lastCompactionCompleteAt = now;
+            setCompactionControlState(sessionState, "compaction.complete.success", { now });
+          }
+          this.emitEvent(
+            "session.compaction",
+            compactedSessionId,
+            {
+              phase: "complete",
+              success: true,
+            }
+          );
+        }
         break;
 
       case "message.updated": {
         // Handle message updates (info contains the message)
         const info = properties?.info as Record<string, unknown> | undefined;
+        const infoRole = info?.role;
+        const infoMessageId = info?.id;
+        const infoSessionId = info?.sessionID;
+        if (
+          (infoRole === "user" || infoRole === "assistant")
+          && typeof infoMessageId === "string"
+          && infoMessageId.length > 0
+          && typeof infoSessionId === "string"
+          && infoSessionId.length > 0
+        ) {
+          this.setMessageRole(infoSessionId, infoMessageId, infoRole);
+        }
+
         if (info?.role === "assistant") {
-          this.emitEvent(
-            "message.complete",
-            (info?.sessionID as string) ?? "",
-            {
-              message: info,
-            }
-          );
+          const msgSessionId = (info?.sessionID as string) ?? "";
+          this.emitEvent("message.complete", msgSessionId, {
+            message: info,
+          });
+
+          // Extract token usage from assistant message updates (carries
+          // cumulative tokens at each step boundary, delivered via SSE)
+          const msgTokens = info?.tokens as
+            | { input?: number; output?: number; reasoning?: number }
+            | undefined;
+          if (msgTokens && (msgTokens.input || msgTokens.output)) {
+            this.emitEvent("usage", msgSessionId, {
+              inputTokens: msgTokens.input ?? 0,
+              outputTokens: msgTokens.output ?? 0,
+            });
+          }
         }
         break;
       }
 
       case "message.part.updated": {
-        // Handle streaming text parts
         const part = properties?.part as Record<string, unknown> | undefined;
-        const delta = properties?.delta as string | undefined;
-        // Session ID is in properties, not in part
-        const partSessionId = (properties?.sessionID as string) ?? (part?.sessionID as string) ?? "";
-        if (part?.type === "text" && delta) {
-          this.emitEvent("message.delta", partSessionId, {
-            delta,
-            contentType: "text",
-          });
-        } else if (part?.type === "reasoning" && delta) {
-          this.emitEvent("message.delta", partSessionId, {
-            delta,
-            contentType: "reasoning",
-            thinkingSourceKey: (part?.id as string) ?? undefined,
-          });
+        // Session IDs can appear on both the event envelope and the part.
+        // Prefer part.sessionID because tool parts emitted by sub-agent child
+        // sessions can still carry properties.sessionID from the parent frame.
+        // Using properties first collapses child tools into the parent stream,
+        // which breaks inline task anchoring and pushes agent trees to the end.
+        const partSessionId = (part?.sessionID as string) ?? (properties?.sessionID as string) ?? "";
+        const partMessageId = (part?.messageID as string) ?? "";
+        const partMessageRole = this.getMessageRole(partSessionId, partMessageId);
+        const parentSessionId = this.findParentSessionForPart(properties, partSessionId);
+        const sessionSubagentState = parentSessionId
+          ? this.getSubagentSessionState(parentSessionId)
+          : this.createSubagentSessionState();
+        if (part?.type === "text") {
+          // Text streaming is handled entirely by message.part.delta (v2).
+        } else if (part?.type === "reasoning") {
+          // Register reasoning part IDs so message.part.delta can route
+          // them as "thinking" content; streaming handled by that handler.
+          const partId = (part?.id as string) ?? undefined;
+          if (partId) {
+            this.reasoningPartIds.add(partId);
+          }
         } else if (part?.type === "tool") {
           const toolState = part?.state as Record<string, unknown> | undefined;
           const toolName = (part?.tool as string) ?? "";
           const toolInput = (toolState?.input as Record<string, unknown>) ?? {};
+          const toolMetadata = (
+            typeof toolState?.metadata === "object"
+            && toolState?.metadata !== null
+            && !Array.isArray(toolState.metadata)
+          )
+            ? (toolState.metadata as Record<string, unknown>)
+            : undefined;
+          let agentPartId = sessionSubagentState.childSessionToAgentPart.get(partSessionId);
+
+          // --- Child session discovery for sub-agent tools ---
+          // When a ToolPart arrives from a session that is NOT the parent
+          // session, it belongs to a sub-agent's child session.  On first
+          // encounter we associate the child session with the oldest pending
+          // agent part and re-emit subagent.start with the correct
+          // subagentSessionId so the UI registers the child session in
+          // ownedSessionIds before the tool.start event arrives.
+          debugLog("tool-part-session-check", {
+            toolName,
+            partSessionId,
+            parentSessionId: parentSessionId || "null",
+            propertiesSessionID: (properties?.sessionID as string) ?? "undefined",
+            partSessionID: (part?.sessionID as string) ?? "undefined",
+            pendingAgentParts: sessionSubagentState.pendingAgentParts.length,
+            childSessionAlreadyKnown: sessionSubagentState.childSessionToAgentPart.has(partSessionId),
+            toolStatus: (toolState?.status as string) ?? "unknown",
+          });
+          if (
+            partSessionId &&
+            parentSessionId &&
+            partSessionId !== parentSessionId &&
+            !sessionSubagentState.childSessionToAgentPart.has(partSessionId)
+          ) {
+            const pending = sessionSubagentState.pendingAgentParts.shift();
+            if (pending) {
+              sessionSubagentState.childSessionToAgentPart.set(partSessionId, pending.partId);
+              agentPartId = pending.partId;
+              this.childSessionToParentSession.set(partSessionId, parentSessionId);
+              debugLog("child-session-discovered", {
+                childSessionId: partSessionId,
+                agentPartId: pending.partId,
+                agentName: pending.agentName,
+              });
+              // Re-emit subagent.start with the correct child session ID.
+              // The UI handles duplicate subagent.start by updating in-place
+              // and — critically — registers the subagentSessionId in
+              // ownedSessionIds + subagentSessionToAgentId.
+              this.emitEvent("subagent.start", parentSessionId, {
+                subagentId: pending.partId,
+                subagentType: pending.agentName,
+                subagentSessionId: partSessionId,
+              });
+              if (pending.partId) {
+                sessionSubagentState.startedSubagentIds.add(pending.partId);
+              }
+            }
+          }
 
           // Emit tool.start for pending or running status
           // OpenCode sends "pending" first, then "running" with more complete input.
           // Include the tool part ID so the UI can deduplicate events for
           // the same logical tool call (pending → running transitions).
           if (toolState?.status === "pending" || toolState?.status === "running") {
-            debugLog("tool.start", {
-              toolName,
-              toolId: part?.id as string,
-              hasToolInput: !!toolInput && Object.keys(toolInput).length > 0,
-            });
-            this.emitEvent("tool.start", partSessionId, {
-              toolName,
-              toolInput,
-              toolUseId: part?.id as string,
-              toolCallId: part?.callID as string,
-            });
+            const isTaskTool = toolName === "task" || toolName === "Task";
+            const isParentSessionTaskTool =
+              !parentSessionId || partSessionId === parentSessionId;
+
+            if (isTaskTool) {
+              const taskPartId = part?.id as string;
+              if (taskPartId && isParentSessionTaskTool) {
+                this.enqueuePendingTaskToolPartId(sessionSubagentState, taskPartId);
+              }
+            }
+
+            // Emit tool.start for non-task tools and parent-session task tools.
+            // Parent task tools provide an anchor so the sub-agent tree renders
+            // inline with the task invocation instead of pinning at the bottom.
+            if (!isTaskTool || isParentSessionTaskTool) {
+              debugLog("tool.start", {
+                toolName,
+                toolId: part?.id as string,
+                hasToolInput: !!toolInput && Object.keys(toolInput).length > 0,
+              });
+              this.emitEvent("tool.start", partSessionId, {
+                toolName,
+                toolInput,
+                ...(toolMetadata ? { toolMetadata } : {}),
+                toolUseId: part?.id as string,
+                toolCallId: part?.callID as string,
+                ...(agentPartId ? { parentAgentId: agentPartId } : {}),
+              });
+            }
+
+            // Emit subagent.update for child session tools
+            if (agentPartId && toolState?.status === "running") {
+              const count = (sessionSubagentState.subagentToolCounts.get(agentPartId) ?? 0) + 1;
+              sessionSubagentState.subagentToolCounts.set(agentPartId, count);
+              this.emitEvent("subagent.update", parentSessionId || partSessionId, {
+                subagentId: agentPartId,
+                currentTool: toolName,
+                toolUses: count,
+              });
+            }
           } else if (toolState?.status === "completed") {
-            // Only emit complete if output is available
-            // The output field contains the formatted file content
-            const output = toolState?.output;
-            if (output !== undefined) {
+            const isTaskTool = toolName === "task" || toolName === "Task";
+            const isParentSessionTaskTool =
+              !parentSessionId || partSessionId === parentSessionId;
+
+            // Emit tool.complete for non-task tools and parent-session task tools.
+            if (!isTaskTool || isParentSessionTaskTool) {
               this.emitEvent("tool.complete", partSessionId, {
                 toolName,
-                toolResult: output,
+                toolResult: toolState?.output,
                 toolInput,
+                ...(toolMetadata ? { toolMetadata } : {}),
                 success: true,
                 toolUseId: part?.id as string,
                 toolCallId: part?.callID as string,
+                ...(agentPartId ? { parentAgentId: agentPartId } : {}),
               });
             }
+
+            if (isTaskTool) {
+              const taskPartId = part?.id as string;
+              if (taskPartId) {
+                this.removePendingTaskToolPartId(sessionSubagentState, taskPartId);
+              }
+            }
           } else if (toolState?.status === "error") {
-            this.emitEvent("tool.complete", partSessionId, {
-              toolName,
-              toolResult: toolState?.error ?? "Tool execution failed",
-              toolInput,
-              success: false,
-              toolUseId: part?.id as string,
-              toolCallId: part?.callID as string,
-            });
+            const isTaskTool = toolName === "task" || toolName === "Task";
+            const isParentSessionTaskTool =
+              !parentSessionId || partSessionId === parentSessionId;
+
+            // Emit tool.complete for non-task tools and parent-session task tools.
+            if (!isTaskTool || isParentSessionTaskTool) {
+              this.emitEvent("tool.complete", partSessionId, {
+                toolName,
+                toolResult: toolState?.error ?? "Tool execution failed",
+                toolInput,
+                ...(toolMetadata ? { toolMetadata } : {}),
+                success: false,
+                toolUseId: part?.id as string,
+                toolCallId: part?.callID as string,
+                ...(agentPartId ? { parentAgentId: agentPartId } : {}),
+              });
+            }
+
+            if (isTaskTool) {
+              const taskPartId = part?.id as string;
+              if (taskPartId) {
+                this.removePendingTaskToolPartId(sessionSubagentState, taskPartId);
+              }
+            }
           }
         } else if (part?.type === "agent") {
+          if (partMessageRole === "user") {
+            // User @mentions are prompt input references, not runtime
+            // sub-agent lifecycle events.
+            break;
+          }
+
           // AgentPart: { type: "agent", name, id, sessionID, messageID }
-          // Map agent parts to subagent.start events
+          // Map agent parts to subagent.start events.
+          //
+          // NOTE: AgentPart.sessionID is the PARENT session (where the part
+          // was created), NOT the child sub-agent session.  The child session
+          // ID is only discoverable from subsequent ToolPart events emitted
+          // by the sub-agent.  We enqueue this agent and will re-emit
+          // subagent.start with the correct subagentSessionId once the first
+          // child tool event reveals the child session.
+          const agentPartId = (part?.id as string) ?? "";
+          const agentName = (part?.name as string) ?? "";
+
+          // Use the pending Task ToolPart ID as the correlation ID so the
+          // UI can match the agent tree to the Task tool card and suppress
+          // the redundant tool card display.  The ToolPart for "task" is
+          // always emitted before the AgentPart it spawns.
+          const taskToolPartId = this.dequeuePendingTaskToolPartId(sessionSubagentState);
+
+          const correlationId = taskToolPartId ?? (part?.callID as string) ?? agentPartId;
           debugLog("subagent.start", {
             partType: "agent",
-            subagentId: (part?.id as string) ?? "",
-            subagentType: (part?.name as string) ?? "",
-            toolCallId: (part?.callID as string) ?? (part?.id as string),
+            subagentId: agentPartId,
+            subagentType: agentName,
+            toolCallId: correlationId,
+            taskToolPartId: taskToolPartId ?? "none",
           });
-          this.emitEvent("subagent.start", partSessionId, {
-            subagentId: (part?.id as string) ?? "",
-            subagentType: (part?.name as string) ?? "",
-            toolCallId: (part?.callID as string) ?? (part?.id as string),
+          sessionSubagentState.pendingAgentParts.push({ partId: agentPartId, agentName });
+          this.emitEvent("subagent.start", parentSessionId || partSessionId, {
+            subagentId: agentPartId,
+            subagentType: agentName,
+            toolCallId: correlationId,
+            // subagentSessionId intentionally omitted — part.sessionID is
+            // the parent session, not the child.  The correct child session
+            // will be registered via a follow-up subagent.start when the
+            // first child tool event arrives.
           });
+          if (agentPartId) {
+            sessionSubagentState.startedSubagentIds.add(agentPartId);
+          }
         } else if (part?.type === "subtask") {
+          if (partMessageRole === "user") {
+            // Defensive parity with AgentPart handling above.
+            break;
+          }
+
           // SubtaskPart: { type: "subtask", prompt, description, agent, ... }
           // Some OpenCode versions emit sub-agent dispatch as "subtask" parts
           // instead of "agent" parts. Normalize both to subagent.start.
+          //
+          // Same child-session caveat as AgentPart above: SubtaskPart.sessionID
+          // is the parent session.  We enqueue and defer child session discovery.
+          const subtaskPartId = (part?.id as string) ?? "";
           const subtaskPrompt = (part?.prompt as string) ?? "";
           const subtaskDescription = (part?.description as string) ?? "";
           const subtaskAgent = (part?.agent as string) ?? "";
+
+          // Use the pending Task ToolPart ID for correlation (same as AgentPart above).
+          const taskToolPartId = this.dequeuePendingTaskToolPartId(sessionSubagentState);
+
+          const correlationId = taskToolPartId ?? subtaskPartId;
           debugLog("subagent.start", {
             partType: "subtask",
-            subagentId: (part?.id as string) ?? "",
+            subagentId: subtaskPartId,
             subagentType: subtaskAgent,
+            toolCallId: correlationId,
+            taskToolPartId: taskToolPartId ?? "none",
           });
-          this.emitEvent("subagent.start", partSessionId, {
-            subagentId: (part?.id as string) ?? "",
+          sessionSubagentState.pendingAgentParts.push({ partId: subtaskPartId, agentName: subtaskAgent });
+          this.emitEvent("subagent.start", parentSessionId || partSessionId, {
+            subagentId: subtaskPartId,
             subagentType: subtaskAgent,
             task: subtaskDescription || subtaskPrompt,
+            toolCallId: correlationId,
             toolInput: {
               prompt: subtaskPrompt,
               description: subtaskDescription,
               agent: subtaskAgent,
             },
+            // subagentSessionId intentionally omitted — see AgentPart comment.
           });
+          if (subtaskPartId) {
+            sessionSubagentState.startedSubagentIds.add(subtaskPartId);
+          }
         } else if (part?.type === "step-finish") {
-          // StepFinishPart signals the end of a sub-agent step
-          // Map to subagent.complete with success based on reason
+          // StepFinishPart signals the end of a step.
+          //
+          // OpenCode emits step-finish for BOTH sub-agent completions AND
+          // main-turn completions (the primary agent finishing its response).
+          // Only emit subagent.complete when the finishedPartId belongs to a
+          // known sub-agent — i.e., it was previously registered via an
+          // "agent" or "subtask" part that triggered subagent.start.
+          // Main-turn step-finish parts are silently ignored to prevent
+          // MISSING_START contract violations downstream.
           const reason = (part?.reason as string) ?? "";
-          this.emitEvent("subagent.complete", partSessionId, {
-            subagentId: (part?.id as string) ?? "",
-            success: reason !== "error",
-            result: reason,
-          });
+          const finishedPartId = (part?.id as string) ?? "";
+          const hasStartedSubagent =
+            finishedPartId.length > 0 &&
+            sessionSubagentState.startedSubagentIds.has(finishedPartId);
+
+          if (hasStartedSubagent) {
+            this.emitEvent("subagent.complete", parentSessionId || partSessionId, {
+              subagentId: finishedPartId,
+              success: reason !== "error",
+              result: reason,
+            });
+
+            // Clean up child session tracking and tool counts for the completed agent.
+            sessionSubagentState.startedSubagentIds.delete(finishedPartId);
+            sessionSubagentState.subagentToolCounts.delete(finishedPartId);
+            for (const [childSid, agentPartId] of sessionSubagentState.childSessionToAgentPart) {
+              if (agentPartId === finishedPartId) {
+                sessionSubagentState.childSessionToAgentPart.delete(childSid);
+                this.childSessionToParentSession.delete(childSid);
+                break;
+              }
+            }
+            // Also remove from pending in case it never spawned child tools.
+            const pendingIdx = sessionSubagentState.pendingAgentParts.findIndex(
+              (p) => p.partId === finishedPartId
+            );
+            if (pendingIdx !== -1) {
+              sessionSubagentState.pendingAgentParts.splice(pendingIdx, 1);
+            }
+          } else {
+            debugLog("step-finish-ignored", {
+              finishedPartId,
+              reason,
+              info: "step-finish part does not match any known sub-agent; likely a main-turn completion",
+            });
+          }
         }
         break;
       }
@@ -776,6 +1873,29 @@ export class OpenCodeClient implements CodingAgentClient {
         this.handleQuestionAsked(properties);
         break;
       }
+
+      case "message.part.delta": {
+        // v2 SDK sends incremental deltas via a separate event type instead of
+        // including `delta` on `message.part.updated`.
+        const partDelta = properties?.delta as string | undefined;
+        const partId = properties?.partID as string | undefined;
+        const deltaSessionId = (properties?.sessionID as string) ?? "";
+        if (partDelta && partDelta.length > 0) {
+          if (partId && this.reasoningPartIds.has(partId)) {
+            this.emitEvent("message.delta", deltaSessionId, {
+              delta: partDelta,
+              contentType: "thinking",
+              thinkingSourceKey: partId,
+            });
+          } else {
+            this.emitEvent("message.delta", deltaSessionId, {
+              delta: partDelta,
+              contentType: "text",
+            });
+          }
+        }
+        break;
+      }
     }
   }
 
@@ -858,7 +1978,7 @@ export class OpenCodeClient implements CodingAgentClient {
     data: Record<string, unknown>
   ): void {
     const handlers = this.eventHandlers.get(eventType);
-    if (!handlers) return;
+    if (!handlers || handlers.size === 0) return;
 
     const event: AgentEvent<T> = {
       type: eventType,
@@ -923,13 +2043,30 @@ export class OpenCodeClient implements CodingAgentClient {
 
   /**
    * Register custom tools as a single MCP stdio server.
-   * Bundles all registered tools into a temporary script and registers it via mcp.add().
+   * Starts a local HTTP dispatch server for tool handler IPC, generates a
+   * temporary MCP script that forwards tool calls to it, and registers the
+   * script with the OpenCode server via mcp.add().
    */
   private async registerToolsMcpServer(): Promise<void> {
     if (!this.sdkClient) return;
 
+    // Start the in-process dispatch server so the MCP script can call handlers
+    const contextFactory = () => ({
+      sessionID: this.currentSessionId ?? "",
+      messageID: "",
+      agent: "opencode" as const,
+      directory: this.clientOptions.directory ?? process.cwd(),
+      abort: new AbortController().signal,
+    });
+
+    const { port, stop } = await startToolDispatchServer(
+      this.registeredTools,
+      contextFactory,
+    );
+    this.dispatchServerStop = stop;
+
     const tools = Array.from(this.registeredTools.values());
-    const scriptPath = await createToolMcpServerScript(tools);
+    const scriptPath = await createToolMcpServerScript(tools, port);
 
     try {
       await this.sdkClient.mcp.add({
@@ -974,13 +2111,13 @@ export class OpenCodeClient implements CodingAgentClient {
 
     if (result.error || !result.data) {
       throw new Error(
-        `Failed to create session: ${result.error ?? "Unknown error"}`
+        `Failed to create session: ${extractOpenCodeErrorMessage(result.error)}`
       );
     }
 
     const sessionId = result.data.id;
     this.currentSessionId = sessionId;
-    this.activeSessions.add(sessionId);
+    this.registerActiveSession(sessionId);
 
     // Emit session start event
     this.emitEvent("session.start", sessionId, { config });
@@ -1011,7 +2148,7 @@ export class OpenCodeClient implements CodingAgentClient {
     }
 
     this.currentSessionId = sessionId;
-    this.activeSessions.add(sessionId);
+    this.registerActiveSession(sessionId);
     return this.wrapSession(sessionId, {});
   }
 
@@ -1062,13 +2199,24 @@ export class OpenCodeClient implements CodingAgentClient {
     }
 
     // Track session state for token usage and lifecycle
-    const sessionState = {
+    const sessionState: OpenCodeSessionState = {
       inputTokens: 0,
       outputTokens: 0,
       isClosed: false,
       contextWindow: null as number | null,
       systemToolsBaseline: null as number | null,
+      compaction: {
+        isCompacting: false,
+        hasAutoCompacted: false,
+        pendingCompactionComplete: false,
+        lastCompactionCompleteAt: null,
+        control: {
+          state: "STREAMING",
+          startedAt: null,
+        },
+      },
     };
+    this.sessionStateById.set(sessionId, sessionState);
 
     // Eagerly resolve contextWindow from provider metadata
     const modelId = config.model;
@@ -1095,9 +2243,7 @@ export class OpenCodeClient implements CodingAgentClient {
         });
 
         if (result.error) {
-          const err = result.error as Record<string, unknown>;
-          const errorDetail = typeof err === "string" ? err : JSON.stringify(err);
-          throw new Error(`Failed to send message: ${errorDetail}`);
+          throw new Error(extractOpenCodeErrorMessage(result.error));
         }
 
         // Update token counts from SDK response
@@ -1146,7 +2292,38 @@ export class OpenCodeClient implements CodingAgentClient {
         };
       },
 
-      stream: (message: string, options?: { agent?: string }): AsyncIterable<AgentMessage> => {
+      sendAsync: async (
+        message: string,
+        options?: { agent?: string; abortSignal?: AbortSignal },
+      ): Promise<void> => {
+        if (sessionState.isClosed) {
+          throw new Error("Session is closed");
+        }
+        if (!client.sdkClient) {
+          throw new Error("Client not connected");
+        }
+
+        const result = await client.sdkClient.session.promptAsync(
+          {
+            sessionID: sessionId,
+            directory: client.clientOptions.directory,
+            agent: agentMode,
+            model: client.activePromptModel ?? initialPromptModel,
+            system: config.systemPrompt || undefined,
+            parts: buildOpenCodePromptParts(message, options?.agent),
+          },
+          options?.abortSignal ? { signal: options.abortSignal } : undefined,
+        );
+
+        if (result?.error) {
+          throw new Error(extractOpenCodeErrorMessage(result.error));
+        }
+      },
+
+      stream: (
+        message: string,
+        options?: { agent?: string; abortSignal?: AbortSignal },
+      ): AsyncIterable<AgentMessage> => {
         return {
           async *[Symbol.asyncIterator]() {
             if (sessionState.isClosed) {
@@ -1155,30 +2332,169 @@ export class OpenCodeClient implements CodingAgentClient {
             if (!client.sdkClient) {
               throw new Error("Client not connected");
             }
+            const sdkClient = client.sdkClient;
+
+            sessionState.compaction.hasAutoCompacted = false;
+            sessionState.compaction.pendingCompactionComplete = false;
+            setCompactionControlState(sessionState, "stream.start");
 
             // Note: input tokens are updated from result.data.info?.tokens after prompt resolves
 
             // Set up streaming via SSE events
             // OpenCode streams text deltas via message.part.updated events
             const deltaQueue: AgentMessage[] = [];
+            let deltaQueueHead = 0;
             let resolveNext: (() => void) | null = null;
+            let settleWaitTimer: ReturnType<typeof setTimeout> | null = null;
             let streamDone = false;
             let streamError: Error | null = null;
+            let terminalEventSeen = false;
+            let terminalEventAt: number | null = null;
+            let promptInFlight = false;
+            const streamAbortSignal = options?.abortSignal;
+            const isSubagentDispatch =
+              typeof options?.agent === "string" && options.agent.trim().length > 0;
+            const relatedSessionIds = new Set<string>([sessionId]);
+            const startedToolUseIds = new Set<string>();
+            const completedToolUseIds = new Set<string>();
+            let syntheticToolUseCounter = 0;
+
+            const compactDeltaQueue = (force = false): void => {
+              if (deltaQueueHead === 0) {
+                return;
+              }
+
+              if (force || deltaQueueHead >= deltaQueue.length) {
+                deltaQueue.length = 0;
+                deltaQueueHead = 0;
+                return;
+              }
+
+              if (deltaQueueHead >= 128 && deltaQueueHead * 2 >= deltaQueue.length) {
+                deltaQueue.splice(0, deltaQueueHead);
+                deltaQueueHead = 0;
+              }
+            };
+
+            const clearSettleWaitTimer = (): void => {
+              if (settleWaitTimer !== null) {
+                clearTimeout(settleWaitTimer);
+                settleWaitTimer = null;
+              }
+            };
+
+            const wakeStreamLoop = (): void => {
+              if (!resolveNext) {
+                return;
+              }
+              const resolve = resolveNext;
+              resolveNext = null;
+              clearSettleWaitTimer();
+              resolve();
+            };
+
+            const enqueueDelta = (messageChunk: AgentMessage): void => {
+              deltaQueue.push(messageChunk);
+              wakeStreamLoop();
+            };
+
+            const hasQueuedDelta = (): boolean => deltaQueueHead < deltaQueue.length;
+
+            const dequeueDelta = (): AgentMessage | undefined => {
+              if (!hasQueuedDelta()) {
+                return undefined;
+              }
+              const nextChunk = deltaQueue[deltaQueueHead];
+              deltaQueueHead += 1;
+              compactDeltaQueue();
+              return nextChunk;
+            };
+
+            const waitForStreamSignal = async (): Promise<void> => {
+              await new Promise<void>((resolve) => {
+                resolveNext = resolve;
+                if (terminalEventSeen && terminalEventAt !== null && promptInFlight) {
+                  const elapsed = Date.now() - terminalEventAt;
+                  const remaining = PRE_PROMPT_TERMINAL_SETTLE_MS - elapsed;
+                  if (remaining <= 0) {
+                    wakeStreamLoop();
+                    return;
+                  }
+                  settleWaitTimer = setTimeout(() => {
+                    settleWaitTimer = null;
+                    wakeStreamLoop();
+                  }, remaining);
+                }
+              });
+            };
+
+            const handleStreamAbort = () => {
+              streamDone = true;
+              terminalEventSeen = true;
+              terminalEventAt = Date.now();
+              wakeStreamLoop();
+            };
+
+            if (streamAbortSignal?.aborted) {
+              handleStreamAbort();
+            } else if (streamAbortSignal) {
+              streamAbortSignal.addEventListener("abort", handleStreamAbort, { once: true });
+            }
+
+            const isStreamAbortError = (error: unknown): boolean => {
+              if (streamAbortSignal?.aborted) {
+                return true;
+              }
+              if (error instanceof DOMException && error.name === "AbortError") {
+                return true;
+              }
+              if (!(error instanceof Error)) {
+                return false;
+              }
+              const errorWithCode = error as Error & { code?: string };
+              if (
+                error.name === "AbortError"
+                || errorWithCode.code === "ABORT_ERR"
+                || errorWithCode.code === "ERR_CANCELED"
+              ) {
+                return true;
+              }
+              return error.message.toLowerCase().includes("aborted");
+            };
+
+            const isRelatedSession = (candidateSessionId: string): boolean => {
+              if (!isSubagentDispatch) {
+                return candidateSessionId === sessionId;
+              }
+              return candidateSessionId.length > 0 && relatedSessionIds.has(candidateSessionId);
+            };
+
+            const registerRelatedSession = (candidateSessionId: unknown): void => {
+              if (typeof candidateSessionId !== "string" || candidateSessionId.length === 0) {
+                return;
+              }
+              relatedSessionIds.add(candidateSessionId);
+            };
+
+            const buildSyntheticToolUseId = (): string => {
+              syntheticToolUseCounter += 1;
+              return `tool_${sessionId}_${syntheticToolUseCounter}`;
+            };
 
             // Handler for delta events from SSE
             const handleDelta = (event: AgentEvent<"message.delta">) => {
-              // Only handle events for our session
-              if (event.sessionId !== sessionId) return;
+              // Handle parent session and discovered child sessions.
+              if (!isRelatedSession(event.sessionId)) return;
 
               const delta = event.data?.delta as string | undefined;
               const contentType = event.data?.contentType as string | undefined;
               const thinkingSourceKey = event.data?.thinkingSourceKey as string | undefined;
               if (delta) {
-                deltaQueue.push({
-                  type: contentType === "reasoning" ? "thinking" as const : "text" as const,
+                enqueueDelta({
+                  type: contentType === "thinking" ? "thinking" as const : "text" as const,
                   content: delta,
                   role: "assistant" as const,
-                  ...(contentType === "reasoning" ? {
+                  ...(contentType === "thinking" ? {
                     metadata: {
                       provider: "opencode",
                       thinkingSourceKey,
@@ -1189,176 +2505,193 @@ export class OpenCodeClient implements CodingAgentClient {
                     },
                   } : {}),
                 });
-                resolveNext?.();
               }
             };
 
+            // Track discovered child sessions so their deltas/tools are included.
+            const handleSubagentStart = (event: AgentEvent<"subagent.start">) => {
+              if (!isSubagentDispatch) return;
+              if (!isRelatedSession(event.sessionId)) return;
+              registerRelatedSession((event.data as Record<string, unknown>)?.subagentSessionId);
+            };
+
+            const handleToolStart = (event: AgentEvent<"tool.start">) => {
+              if (!isSubagentDispatch) return;
+              if (!isRelatedSession(event.sessionId)) return;
+
+              const toolData = event.data as Record<string, unknown>;
+              const toolName = (toolData.toolName as string | undefined) ?? "unknown";
+              const toolInput = (toolData.toolInput as Record<string, unknown> | undefined) ?? {};
+              const toolUseId =
+                (toolData.toolUseId as string | undefined) ??
+                (toolData.toolUseID as string | undefined) ??
+                (toolData.toolCallId as string | undefined) ??
+                buildSyntheticToolUseId();
+
+              if (startedToolUseIds.has(toolUseId)) {
+                return;
+              }
+
+              startedToolUseIds.add(toolUseId);
+              enqueueDelta({
+                type: "tool_use",
+                content: {
+                  name: toolName,
+                  input: toolInput,
+                  toolUseId,
+                },
+                role: "assistant",
+                metadata: {
+                  toolName,
+                  toolId: toolUseId,
+                },
+              });
+            };
+
+            const handleToolComplete = (event: AgentEvent<"tool.complete">) => {
+              if (!isSubagentDispatch) return;
+              if (!isRelatedSession(event.sessionId)) return;
+
+              const toolData = event.data as Record<string, unknown>;
+              const toolName = (toolData.toolName as string | undefined) ?? "unknown";
+              const toolUseId =
+                (toolData.toolUseId as string | undefined) ??
+                (toolData.toolUseID as string | undefined) ??
+                (toolData.toolCallId as string | undefined) ??
+                buildSyntheticToolUseId();
+
+              if (completedToolUseIds.has(toolUseId)) {
+                return;
+              }
+
+              completedToolUseIds.add(toolUseId);
+              const success = (toolData.success as boolean | undefined) ?? true;
+              const toolResult = success
+                ? toolData.toolResult
+                : { error: (toolData.error as string | undefined) ?? "Tool execution failed" };
+
+              enqueueDelta({
+                type: "tool_result",
+                content: toolResult,
+                role: "assistant",
+                metadata: {
+                  toolName,
+                  toolId: toolUseId,
+                  error: !success,
+                },
+              });
+            };
+
             // Handler for session idle (stream complete)
             const handleIdle = (event: AgentEvent<"session.idle">) => {
-              if (event.sessionId !== sessionId) return;
-              streamDone = true;
-              resolveNext?.();
+              if (!isRelatedSession(event.sessionId)) return;
+              terminalEventSeen = true;
+              terminalEventAt = Date.now();
+              wakeStreamLoop();
             };
 
             // Handler for session error
             const handleError = (event: AgentEvent<"session.error">) => {
-              if (event.sessionId !== sessionId) return;
+              if (!isRelatedSession(event.sessionId)) return;
               streamError = new Error(String(event.data?.error ?? "Stream error"));
+              terminalEventSeen = true;
+              terminalEventAt = Date.now();
               streamDone = true;
-              resolveNext?.();
+              wakeStreamLoop();
+            };
+
+            const handleUsage = (event: AgentEvent<"usage">) => {
+              if (event.sessionId !== sessionId) return;
+              const usageData = event.data as { inputTokens?: unknown; outputTokens?: unknown };
+              if (typeof usageData.inputTokens === "number") {
+                sessionState.inputTokens = usageData.inputTokens;
+              }
+              if (typeof usageData.outputTokens === "number") {
+                sessionState.outputTokens = usageData.outputTokens;
+              }
             };
 
             // Subscribe to events
             const unsubDelta = client.on("message.delta", handleDelta);
+            const unsubSubagentStart = isSubagentDispatch
+              ? client.on("subagent.start", handleSubagentStart)
+              : () => {};
+            const unsubToolStart = isSubagentDispatch
+              ? client.on("tool.start", handleToolStart)
+              : () => {};
+            const unsubToolComplete = isSubagentDispatch
+              ? client.on("tool.complete", handleToolComplete)
+              : () => {};
             const unsubIdle = client.on("session.idle", handleIdle);
             const unsubError = client.on("session.error", handleError);
-
-            try {
-              // Start the prompt (this initiates the agentic loop)
-              // The response will come through SSE events
-              const result = await client.sdkClient.session.prompt({
-                sessionID: sessionId,
-                directory: client.clientOptions.directory,
-                agent: agentMode,
-                model: client.activePromptModel ?? initialPromptModel,
-                system: config.systemPrompt || undefined,
-                parts: buildOpenCodePromptParts(message, options?.agent),
-              });
-
-              if (result.error) {
-                throw new Error(`Failed to send message: ${result.error}`);
+            const unsubUsage = client.on("usage", handleUsage);
+
+            const dispatchStreamPrompt = async (promptMessage: string): Promise<void> => {
+              promptInFlight = true;
+              try {
+                const result = await sdkClient.session.promptAsync(
+                  {
+                    sessionID: sessionId,
+                    directory: client.clientOptions.directory,
+                    agent: agentMode,
+                    model: client.activePromptModel ?? initialPromptModel,
+                    system: config.systemPrompt || undefined,
+                    parts: buildOpenCodePromptParts(promptMessage, options?.agent),
+                  },
+                  streamAbortSignal ? { signal: streamAbortSignal } : undefined,
+                );
+
+                if (result?.error) {
+                  streamError = new Error(extractOpenCodeErrorMessage(result.error));
+                  streamDone = true;
+                  wakeStreamLoop();
+                }
+              } catch (error: unknown) {
+                if (isStreamAbortError(error)) {
+                  streamDone = true;
+                  terminalEventSeen = true;
+                  terminalEventAt = Date.now();
+                  wakeStreamLoop();
+                  return;
+                }
+                streamError = error instanceof Error ? error : new Error(String(error));
+                streamDone = true;
+                wakeStreamLoop();
+              } finally {
+                promptInFlight = false;
+                wakeStreamLoop();
               }
+            };
 
-              // Track if we already yielded text content from direct response
-              // to avoid duplicating with SSE deltas
-              let yieldedTextFromResponse = false;
+            const resetStreamTerminalState = (): void => {
+              streamDone = false;
+              streamError = null;
+              terminalEventSeen = false;
+              terminalEventAt = null;
+            };
 
+            try {
               // Wall-clock thinking timing
               let reasoningStartMs: number | null = null;
               let reasoningDurationMs = 0;
 
-              // If we got a direct response (no SSE streaming), yield it
-              // This handles cases where the SDK returns immediately
-              if (result.data?.parts) {
-                const parts = result.data.parts;
-                for (const part of parts) {
-                  if (part.type === "text" && part.text) {
-                    yieldedTextFromResponse = true;
-                    yield {
-                      type: "text" as const,
-                      content: part.text,
-                      role: "assistant" as const,
-                    };
-                  } else if (part.type === "reasoning" && part.text) {
-                    if (reasoningStartMs === null) {
-                      reasoningStartMs = Date.now();
-                    }
-                    const reasoningPartId = (part as { id?: string }).id;
-                    yield {
-                      type: "thinking" as const,
-                      content: part.text,
-                      role: "assistant" as const,
-                      metadata: {
-                        provider: "opencode",
-                        thinkingSourceKey: reasoningPartId,
-                        streamingStats: {
-                          thinkingMs: reasoningDurationMs + (Date.now() - reasoningStartMs),
-                          outputTokens: 0,
-                        },
-                      },
-                    };
-                  } else if (part.type === "tool") {
-                    // Accumulate reasoning duration when transitioning away from reasoning
-                    if (reasoningStartMs !== null) {
-                      reasoningDurationMs += Date.now() - reasoningStartMs;
-                      reasoningStartMs = null;
-                    }
-                    const toolPart = part as Record<string, unknown>;
-                    const toolState = toolPart.state as Record<string, unknown> | undefined;
-                    const toolName = toolPart.tool as string;
-
-                    // Yield tool_use message for pending/running tools
-                    if (toolState?.status === "pending" || toolState?.status === "running") {
-                      yield {
-                        type: "tool_use" as const,
-                        content: {
-                          name: toolName,
-                          input: toolState?.input ?? {},
-                          toolUseId: toolPart.id as string,
-                        },
-                        role: "assistant" as const,
-                        metadata: {
-                          toolId: toolPart.id as string,
-                        },
-                      };
-                    }
-
-                    // Yield tool_result message for completed tools
-                    if (toolState?.status === "completed" && toolState?.output) {
-                      yield {
-                        type: "tool_result" as const,
-                        content: toolState.output,
-                        role: "assistant" as const,
-                        metadata: {
-                          toolName,
-                          toolId: toolPart.id as string,
-                        },
-                      };
-                    }
-
-                    // Yield error message for failed tools
-                    if (toolState?.status === "error") {
-                      yield {
-                        type: "tool_result" as const,
-                        content: { error: toolState?.error ?? "Tool execution failed" },
-                        role: "assistant" as const,
-                        metadata: {
-                          toolName,
-                          toolId: toolPart.id as string,
-                          error: true,
-                        },
-                      };
-                    }
-                  }
-                }
+              // Fire-and-forget: promptAsync() returns 204 immediately.
+              // All streaming content arrives exclusively through SSE events
+              // (message.delta, session.idle, session.error).
+              if (!streamAbortSignal?.aborted) {
+                void dispatchStreamPrompt(message);
+              }
 
-                // Update token counts from response
-                const tokens = result.data.info?.tokens;
-                if (tokens) {
-                  sessionState.inputTokens = tokens.input ?? sessionState.inputTokens;
-                  sessionState.outputTokens = tokens.output ?? 0;
-
-                  // Capture system/tools baseline from cache tokens
-                  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                  const cacheTokens = (((tokens as any).cache?.write ?? 0) + ((tokens as any).cache?.read ?? 0));
-                  if (cacheTokens > 0) {
-                    sessionState.systemToolsBaseline = cacheTokens;
+              while (true) {
+                // Drain SSE deltas until session.idle or session.error
+                while (!streamDone || hasQueuedDelta()) {
+                  if (streamAbortSignal?.aborted) {
+                    streamDone = true;
+                    break;
                   }
-                }
 
-                // Yield actual token counts to UI
-                if (sessionState.outputTokens > 0 || reasoningDurationMs > 0) {
-                  yield {
-                    type: "text" as const,
-                    content: "",
-                    role: "assistant" as const,
-                    metadata: {
-                      streamingStats: {
-                        outputTokens: sessionState.outputTokens,
-                        thinkingMs: reasoningDurationMs,
-                      },
-                    },
-                  };
-                }
-              }
-
-              // Yield any SSE deltas that arrived, but skip if we already yielded text from direct response
-              // This prevents duplication when OpenCode returns content both in direct response AND via SSE
-              if (!yieldedTextFromResponse) {
-                while (!streamDone || deltaQueue.length > 0) {
-                  if (deltaQueue.length > 0) {
-                    const msg = deltaQueue.shift()!;
-                    // Track reasoning duration from SSE deltas
+                  const msg = dequeueDelta();
+                  if (msg) {
                     if (msg.type === "thinking") {
                       if (reasoningStartMs === null) {
                         reasoningStartMs = Date.now();
@@ -1374,39 +2707,118 @@ export class OpenCodeClient implements CodingAgentClient {
                       reasoningStartMs = null;
                     }
                     yield msg;
-                  } else if (!streamDone) {
-                    // Wait for next delta or completion
-                    await new Promise<void>((resolve) => {
-                      resolveNext = resolve;
-                      // Add a timeout to prevent infinite waiting
-                      setTimeout(resolve, 30000);
-                    });
-                    resolveNext = null;
+                    continue;
+                  }
+
+                  if (streamDone) {
+                    break;
+                  }
+
+                  if (
+                    terminalEventSeen
+                    && terminalEventAt !== null
+                    && (
+                      !promptInFlight
+                      || Date.now() - terminalEventAt >= PRE_PROMPT_TERMINAL_SETTLE_MS
+                    )
+                  ) {
+                    streamDone = true;
+                    break;
                   }
+
+                  // Wait for next delta or completion
+                  await waitForStreamSignal();
                 }
-              } else {
-                // Clear the delta queue since we already have the response
-                deltaQueue.length = 0;
-                streamDone = true;
-              }
 
-              // Check for stream error
-              if (streamError) {
-                throw streamError;
-              }
+                if (streamAbortSignal?.aborted) {
+                  break;
+                }
+
+                if (!streamError) {
+                  const maxTokens = client.activeContextWindow ?? sessionState.contextWindow;
+                  const usagePercentage = maxTokens && maxTokens > 0
+                    ? ((sessionState.inputTokens + sessionState.outputTokens) / maxTokens) * 100
+                    : 0;
+                  const shouldAttemptProactiveCompaction =
+                    !isSubagentDispatch
+                    && usagePercentage >= AUTO_COMPACTION_THRESHOLD * 100
+                    && !sessionState.compaction.isCompacting
+                    && sessionState.compaction.control.state === "STREAMING"
+                    && !sessionState.compaction.hasAutoCompacted;
+
+                  if (!shouldAttemptProactiveCompaction) {
+                    break;
+                  }
+
+                  debugLog("compaction.proactive_trigger", {
+                    sessionId,
+                    trigger: "threshold",
+                    thresholdPercentage: AUTO_COMPACTION_THRESHOLD * 100,
+                    usagePercentage,
+                    inputTokens: sessionState.inputTokens,
+                    outputTokens: sessionState.outputTokens,
+                    contextWindow: maxTokens ?? 0,
+                  });
+                  sessionState.compaction.hasAutoCompacted = true;
+                  await session.summarize();
+                  break;
+                }
+
+                if (reasoningStartMs !== null) {
+                  reasoningDurationMs += Date.now() - reasoningStartMs;
+                  reasoningStartMs = null;
+                }
+
+                const shouldAttemptAutoCompaction = isContextOverflowError(streamError)
+                  && !sessionState.compaction.isCompacting
+                  && sessionState.compaction.control.state === "STREAMING"
+                  && !sessionState.compaction.hasAutoCompacted;
 
-              // Actual token counts come from result.data.info?.tokens (yielded above).
+                if (!shouldAttemptAutoCompaction) {
+                  throw streamError;
+                }
+
+                debugLog("compaction.overflow_trigger", {
+                  sessionId,
+                  trigger: "overflow",
+                  thresholdPercentage: AUTO_COMPACTION_THRESHOLD * 100,
+                  inputTokens: sessionState.inputTokens,
+                  outputTokens: sessionState.outputTokens,
+                  contextWindow: sessionState.contextWindow ?? 0,
+                  error: extractOpenCodeErrorMessage(streamError),
+                });
+                sessionState.compaction.hasAutoCompacted = true;
+
+                await session.summarize();
+
+                // Discard any stale stream payload from the failed pre-compaction turn.
+                deltaQueue.length = 0;
+                deltaQueueHead = 0;
+                resetStreamTerminalState();
+                if (streamAbortSignal?.aborted) {
+                  break;
+                }
+                void dispatchStreamPrompt("Continue");
+              }
             } catch (error) {
-              yield {
-                type: "text" as const,
-                content: `Error: ${error instanceof Error ? error.message : String(error)}`,
-                role: "assistant" as const,
-              };
+              if (error instanceof OpenCodeCompactionError) {
+                setCompactionControlState(sessionState, "turn.ended");
+                throw error;
+              }
+              throw new Error(extractOpenCodeErrorMessage(error));
             } finally {
+              clearSettleWaitTimer();
+              if (streamAbortSignal) {
+                streamAbortSignal.removeEventListener("abort", handleStreamAbort);
+              }
               // Unsubscribe from events
               unsubDelta();
+              unsubSubagentStart();
+              unsubToolStart();
+              unsubToolComplete();
               unsubIdle();
               unsubError();
+              unsubUsage();
             }
           },
         };
@@ -1417,39 +2829,123 @@ export class OpenCodeClient implements CodingAgentClient {
           throw new Error("Client not connected");
         }
 
-        await client.sdkClient.session.summarize({
-          sessionID: sessionId,
-          directory: client.clientOptions.directory,
-        });
-
-        // Query actual post-compaction token counts from the SDK.
-        // session.messages() returns each message with its token snapshot,
-        // so the last assistant message reflects the post-compaction state.
+        const preCompactionTokens = sessionState.inputTokens + sessionState.outputTokens;
+        let summarizeSucceeded = false;
         try {
-          const messagesResult = await client.sdkClient.session.messages({
-            sessionID: sessionId,
+          const compactionStartAt = Date.now();
+          setCompactionControlState(sessionState, "compaction.start", { now: compactionStartAt });
+          debugLog("compaction.summarize_start", {
+            sessionId,
+            thresholdPercentage: AUTO_COMPACTION_THRESHOLD * 100,
+            inputTokens: sessionState.inputTokens,
+            outputTokens: sessionState.outputTokens,
+            preCompactionTokens,
+            contextWindow: sessionState.contextWindow ?? 0,
+            maxCompactionWaitMs: MAX_COMPACTION_WAIT_MS,
+          });
+          client.emitEvent("session.compaction", sessionId, {
+            phase: "start",
           });
-          const messages = messagesResult.data ?? [];
-          for (let i = messages.length - 1; i >= 0; i--) {
-            const msg = messages[i]!.info;
-            if (msg.role === "assistant" && "tokens" in msg) {
-              sessionState.inputTokens = msg.tokens.input ?? sessionState.inputTokens;
-              sessionState.outputTokens = msg.tokens.output ?? 0;
-              const cacheTokens = (msg.tokens.cache?.write ?? 0) + (msg.tokens.cache?.read ?? 0);
-              if (cacheTokens > 0) {
-                sessionState.systemToolsBaseline = cacheTokens;
+          sessionState.compaction.pendingCompactionComplete = true;
+
+          await withCompactionTimeout(client.sdkClient.session.summarize({
+            sessionID: sessionId,
+            directory: client.clientOptions.directory,
+          }));
+          summarizeSucceeded = true;
+
+          // Query actual post-compaction token counts from the SDK.
+          // session.messages() returns each message with its token snapshot,
+          // so the last assistant message reflects the post-compaction state.
+          try {
+            const messagesResult = await client.sdkClient.session.messages({
+              sessionID: sessionId,
+            });
+            const messages = messagesResult.data ?? [];
+            for (let i = messages.length - 1; i >= 0; i--) {
+              const msg = messages[i]!.info;
+              if (msg.role === "assistant" && "tokens" in msg) {
+                sessionState.inputTokens = msg.tokens.input ?? sessionState.inputTokens;
+                sessionState.outputTokens = msg.tokens.output ?? 0;
+                const cacheTokens = (msg.tokens.cache?.write ?? 0) + (msg.tokens.cache?.read ?? 0);
+                if (cacheTokens > 0) {
+                  sessionState.systemToolsBaseline = cacheTokens;
+                }
+                break;
               }
-              break;
             }
+          } catch (refreshError) {
+            debugLog("compaction.refresh_tokens_failed", {
+              sessionId,
+              error: extractOpenCodeErrorMessage(refreshError),
+            });
+            // If messages() fails, token counts remain at pre-compaction values.
+            // They will self-correct on the next message (snapshot tracking).
           }
-        } catch {
-          // If messages() fails, token counts remain at pre-compaction values.
-          // They will self-correct on the next message (snapshot tracking).
-        }
 
-        client.emitEvent("session.idle", sessionId, {
-          reason: "context_compacted",
-        });
+          const postCompactionTokens = sessionState.inputTokens + sessionState.outputTokens;
+          const tokensRemoved = preCompactionTokens - postCompactionTokens;
+          debugLog("compaction.summarize_complete", {
+            sessionId,
+            thresholdPercentage: AUTO_COMPACTION_THRESHOLD * 100,
+            inputTokens: sessionState.inputTokens,
+            outputTokens: sessionState.outputTokens,
+            preCompactionTokens,
+            postCompactionTokens,
+            tokensRemoved,
+            tokenLimit: sessionState.contextWindow ?? 0,
+          });
+          if (tokensRemoved > 0) {
+            client.emitEvent("session.truncation", sessionId, {
+              tokenLimit: sessionState.contextWindow ?? 0,
+              tokensRemoved,
+              messagesRemoved: 0,
+            });
+          }
+
+          client.emitEvent("session.idle", sessionId, {
+            reason: "context_compacted",
+          });
+          setCompactionControlState(sessionState, "compaction.complete.success");
+        } catch (error) {
+          const sourceErrorMessage = extractOpenCodeErrorMessage(error);
+          const terminalError = toOpenCodeCompactionTerminalError(error);
+          setCompactionControlState(sessionState, "compaction.complete.error", {
+            errorCode: terminalError.code,
+            errorMessage: terminalError.message,
+          });
+          debugLog("compaction.summarize_failed", {
+            sessionId,
+            thresholdPercentage: AUTO_COMPACTION_THRESHOLD * 100,
+            inputTokens: sessionState.inputTokens,
+            outputTokens: sessionState.outputTokens,
+            preCompactionTokens,
+            contextWindow: sessionState.contextWindow ?? 0,
+            error: sourceErrorMessage,
+            terminalErrorCode: terminalError.code,
+            terminalError: terminalError.message,
+          });
+          emitOpenCodeCompactionContractFailureObservability({
+            sessionId,
+            code: terminalError.code,
+            sourceError: sourceErrorMessage,
+            terminalError: terminalError.message,
+          });
+          client.emitEvent("session.compaction", sessionId, {
+            phase: "complete",
+            success: false,
+            error: terminalError.message,
+          });
+          client.emitEvent("session.error", sessionId, {
+            error: terminalError.message,
+            code: terminalError.code,
+          });
+          throw terminalError;
+        } finally {
+          if (!summarizeSucceeded) {
+            sessionState.compaction.pendingCompactionComplete = false;
+          }
+        }
       },
 
       getContextUsage: async (): Promise<ContextUsage> => {
@@ -1474,6 +2970,11 @@ export class OpenCodeClient implements CodingAgentClient {
         return sessionState.systemToolsBaseline;
       },
 
+      getCompactionState: (): SessionCompactionState => ({
+        isCompacting: sessionState.compaction.isCompacting,
+        hasAutoCompacted: sessionState.compaction.hasAutoCompacted,
+      }),
+
       getMcpSnapshot: async (): Promise<McpRuntimeSnapshot | null> => {
         if (sessionState.isClosed) {
           return null;
@@ -1481,6 +2982,40 @@ export class OpenCodeClient implements CodingAgentClient {
         return client.buildOpenCodeMcpSnapshot();
       },
 
+      abort: async (): Promise<void> => {
+        if (sessionState.isClosed || !client.sdkClient) return;
+        await client.sdkClient.session.abort({
+          sessionID: sessionId,
+          directory: client.clientOptions.directory,
+        });
+      },
+
+      abortBackgroundAgents: async (): Promise<void> => {
+        if (sessionState.isClosed || !client.sdkClient) return;
+        // Abort tracked child sessions (background sub-agents).
+        // OpenCode tracks child session IDs in the parent session state.
+        const parentState = client.subagentStateByParentSession.get(sessionId);
+        const childSessionIds = parentState
+          ? Array.from(parentState.childSessionToAgentPart.keys())
+          : [];
+        if (childSessionIds.length > 0) {
+          const abortPromises = childSessionIds.map((childSid) =>
+            client.sdkClient!.session.abort({
+              sessionID: childSid,
+              directory: client.clientOptions.directory,
+            }).catch((error: unknown) => {
+              console.error(`Failed to abort child session ${childSid}:`, error);
+            }),
+          );
+          await Promise.allSettled(abortPromises);
+        }
+        // Also abort the parent session to catch any remaining work
+        await client.sdkClient.session.abort({
+          sessionID: sessionId,
+          directory: client.clientOptions.directory,
+        });
+      },
+
       destroy: async (): Promise<void> => {
         if (sessionState.isClosed) {
           return;
@@ -1496,10 +3031,7 @@ export class OpenCodeClient implements CodingAgentClient {
           directory: client.clientOptions.directory,
         });
 
-        client.activeSessions.delete(sessionId);
-        if (client.currentSessionId === sessionId) {
-          client.currentSessionId = null;
-        }
+        client.unregisterActiveSession(sessionId);
 
         client.emitEvent("session.idle", sessionId, { reason: "destroyed" });
       },
@@ -1522,6 +3054,9 @@ export class OpenCodeClient implements CodingAgentClient {
 
     return () => {
       handlers?.delete(handler as EventHandler<EventType>);
+      if (handlers && handlers.size === 0) {
+        this.eventHandlers.delete(eventType);
+      }
     };
   }
 
@@ -1595,10 +3130,12 @@ export class OpenCodeClient implements CodingAgentClient {
       }
     }
 
+    // Mark running BEFORE starting SSE so the event loop's while-condition
+    // (which checks `this.isRunning` synchronously) evaluates to true.
+    this.isRunning = true;
+
     // Start SSE event subscription
     await this.subscribeToSdkEvents();
-
-    this.isRunning = true;
   }
 
   /**
@@ -1623,6 +3160,13 @@ export class OpenCodeClient implements CodingAgentClient {
       this.isServerSpawned = false;
     }
 
+    // Stop the tool dispatch HTTP server
+    if (this.dispatchServerStop) {
+      this.dispatchServerStop();
+      this.dispatchServerStop = null;
+    }
+    stopToolDispatchServer();
+
     this.eventHandlers.clear();
     this.isRunning = false;
   }
diff --git a/src/sdk/index.ts b/src/sdk/index.ts
index 1b37f83f72..1b1f4e6f18 100644
--- a/src/sdk/index.ts
+++ b/src/sdk/index.ts
@@ -29,7 +29,6 @@ export { stripProviderPrefix, formatModelDisplayName } from "./types.ts";
 
 // Base client utilities for shared patterns
 export {
-  EventEmitter,
   createAgentEvent,
   requireRunning,
   type ClientState,
diff --git a/src/sdk/tools/discovery.test.ts b/src/sdk/tools/discovery.test.ts
new file mode 100644
index 0000000000..9624ab43cd
--- /dev/null
+++ b/src/sdk/tools/discovery.test.ts
@@ -0,0 +1,161 @@
+/**
+ * Tests for registerCustomTools() in the chat init sequence.
+ *
+ * Verifies that:
+ * 1. Each discovered tool is registered on the client via registerTool()
+ * 2. Each discovered tool is added to the global ToolRegistry
+ * 3. The returned count matches the number of discovered tools
+ * 4. Zero tools results in no calls and a 0 return
+ * 5. getDiscoveredCustomTools() reflects the latest registration
+ */
+
+import { describe, test, expect, beforeEach } from "bun:test";
+import type { ToolDefinition } from "../types.ts";
+import { ToolRegistry, setToolRegistry } from "./registry.ts";
+import { registerCustomTools, getDiscoveredCustomTools } from "./discovery.ts";
+import { mkdtemp, mkdir, rm, writeFile } from "fs/promises";
+import { join, resolve } from "path";
+import { tmpdir } from "os";
+
+// Absolute path to zod so temp tool files can import it outside node_modules
+const ZOD_PATH = resolve(import.meta.dir, "../../../node_modules/zod").replace(/\\/g, "/");
+
+function makeFakeClient() {
+  const registeredTools: ToolDefinition[] = [];
+  return {
+    registeredTools,
+    registerTool(tool: ToolDefinition) {
+      registeredTools.push(tool);
+    },
+  } as any;
+}
+
+async function withTempCwd(
+  setup: (dir: string) => Promise<void>,
+  run: () => Promise<void>,
+): Promise<void> {
+  const tempDir = await mkdtemp(join(tmpdir(), "atomic-discovery-test-"));
+  await setup(tempDir);
+  const originalCwd = process.cwd();
+  process.chdir(tempDir);
+  try {
+    await run();
+  } finally {
+    process.chdir(originalCwd);
+    await rm(tempDir, { recursive: true, force: true });
+  }
+}
+
+describe("registerCustomTools", () => {
+  let registry: ToolRegistry;
+
+  beforeEach(() => {
+    registry = new ToolRegistry();
+    setToolRegistry(registry);
+  });
+
+  test("registers discovered tools on client and in registry", async () => {
+    await withTempCwd(
+      async (dir) => {
+        const toolsDir = join(dir, ".atomic", "tools");
+        await mkdir(toolsDir, { recursive: true });
+        await writeFile(
+          join(toolsDir, "greet.ts"),
+          `
+import { z } from "${ZOD_PATH}";
+export default {
+  description: "Says hello",
+  args: { name: z.string() },
+  execute: async (input) => \`Hello, \${input.name}!\`,
+};
+`,
+          "utf-8",
+        );
+      },
+      async () => {
+        const client = makeFakeClient();
+        const count = await registerCustomTools(client);
+
+        expect(count).toBe(1);
+        expect(client.registeredTools).toHaveLength(1);
+        expect(client.registeredTools[0].name).toBe("greet");
+        expect(client.registeredTools[0].description).toBe("Says hello");
+
+        // Registry should also contain the tool
+        expect(registry.has("greet")).toBe(true);
+        const entry = registry.get("greet")!;
+        expect(entry.source).toBe("local");
+        expect(entry.description).toBe("Says hello");
+
+        // getDiscoveredCustomTools should reflect the registration
+        const discovered = getDiscoveredCustomTools();
+        expect(discovered).toHaveLength(1);
+        expect(discovered[0]!.definition.name).toBe("greet");
+      },
+    );
+  });
+
+  test("returns 0 and makes no calls when no tools are found", async () => {
+    await withTempCwd(
+      async () => {
+        // No .atomic/tools directory created
+      },
+      async () => {
+        const client = makeFakeClient();
+        const count = await registerCustomTools(client);
+
+        expect(count).toBe(0);
+        expect(client.registeredTools).toHaveLength(0);
+        expect(registry.getAll()).toHaveLength(0);
+      },
+    );
+  });
+
+  test("registers multiple tools from multiple files", async () => {
+    await withTempCwd(
+      async (dir) => {
+        const toolsDir = join(dir, ".atomic", "tools");
+        await mkdir(toolsDir, { recursive: true });
+
+        await writeFile(
+          join(toolsDir, "alpha.ts"),
+          `
+import { z } from "${ZOD_PATH}";
+export default {
+  description: "Alpha tool",
+  args: { x: z.number() },
+  execute: async (input) => input.x * 2,
+};
+`,
+          "utf-8",
+        );
+
+        await writeFile(
+          join(toolsDir, "beta.ts"),
+          `
+import { z } from "${ZOD_PATH}";
+export default {
+  description: "Beta tool",
+  args: {},
+  execute: async () => "beta",
+};
+`,
+          "utf-8",
+        );
+      },
+      async () => {
+        const client = makeFakeClient();
+        const count = await registerCustomTools(client);
+
+        expect(count).toBe(2);
+        expect(client.registeredTools).toHaveLength(2);
+
+        const names = client.registeredTools.map((t: ToolDefinition) => t.name).sort();
+        expect(names).toEqual(["alpha", "beta"]);
+
+        expect(registry.has("alpha")).toBe(true);
+        expect(registry.has("beta")).toBe(true);
+      },
+    );
+  });
+});
diff --git a/src/sdk/tools/index.ts b/src/sdk/tools/index.ts
index 9c84fd2bd0..469991b06c 100644
--- a/src/sdk/tools/index.ts
+++ b/src/sdk/tools/index.ts
@@ -6,3 +6,4 @@
 
 export { getToolRegistry, setToolRegistry, ToolRegistry } from "./registry.ts";
 export type { ToolEntry } from "./registry.ts";
+export { registerCustomTools } from "./discovery.ts";
diff --git a/src/sdk/tools/opencode-mcp-bridge.test.ts b/src/sdk/tools/opencode-mcp-bridge.test.ts
new file mode 100644
index 0000000000..31873313d3
--- /dev/null
+++ b/src/sdk/tools/opencode-mcp-bridge.test.ts
@@ -0,0 +1,237 @@
+/**
+ * Tests for the OpenCode MCP Bridge tool dispatch mechanism.
+ *
+ * Verifies that:
+ * 1. The dispatch HTTP server starts and accepts tool call requests
+ * 2. Tool handlers are actually invoked with correct arguments and context
+ * 3. Handler errors are reported correctly
+ * 4. Unknown tools return 404
+ * 5. The generated MCP script contains the dispatch URL (not a placeholder)
+ */
+
+import { describe, test, expect, afterEach } from "bun:test";
+import {
+  startToolDispatchServer,
+  stopToolDispatchServer,
+  createToolMcpServerScript,
+  cleanupMcpBridgeScripts,
+} from "./opencode-mcp-bridge.ts";
+import type { ToolDefinition, ToolContext } from "../types.ts";
+import { readFileSync } from "fs";
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+function makeContext(): ToolContext {
+  return {
+    sessionID: "test-session",
+    messageID: "test-message",
+    agent: "opencode",
+    directory: process.cwd(),
+    abort: new AbortController().signal,
+  };
+}
+
+function makeTool(
+  name: string,
+  handler: ToolDefinition["handler"],
+): ToolDefinition {
+  return {
+    name,
+    description: `Test tool: ${name}`,
+    inputSchema: {
+      type: "object",
+      properties: { input: { type: "string" } },
+    },
+    handler,
+  };
+}
+
+// ============================================================================
+// Tests
+// ============================================================================
+
+describe("opencode-mcp-bridge dispatch server", () => {
+  afterEach(() => {
+    stopToolDispatchServer();
+    cleanupMcpBridgeScripts();
+  });
+
+  test("starts on a random port and handles tool calls", async () => {
+    const tools = new Map<string, ToolDefinition>();
+    tools.set(
+      "echo",
+      makeTool("echo", (input) => `echo: ${(input as Record<string, string>).input}`),
+    );
+
+    const { port, stop } = await startToolDispatchServer(tools, makeContext);
+    expect(port).toBeGreaterThan(0);
+
+    const res = await fetch(`http://127.0.0.1:${port}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ name: "echo", arguments: { input: "hello" } }),
+    });
+
+    expect(res.ok).toBe(true);
+    const body = (await res.json()) as { content: Array<{ type: string; text: string }> };
+    expect(body.content[0]!.text).toBe("echo: hello");
+
+    stop();
+  });
+
+  test("returns 404 for unknown tools", async () => {
+    const tools = new Map<string, ToolDefinition>();
+    const { port, stop } = await startToolDispatchServer(tools, makeContext);
+
+    const res = await fetch(`http://127.0.0.1:${port}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ name: "nonexistent", arguments: {} }),
+    });
+
+    expect(res.status).toBe(404);
+    const body = (await res.json()) as { error: string };
+    expect(body.error).toContain("Tool not found");
+
+    stop();
+  });
+
+  test("reports handler errors with isError flag", async () => {
+    const tools = new Map<string, ToolDefinition>();
+    tools.set(
+      "failing",
+      makeTool("failing", () => {
+        throw new Error("handler boom");
+      }),
+    );
+
+    const { port, stop } = await startToolDispatchServer(tools, makeContext);
+
+    const res = await fetch(`http://127.0.0.1:${port}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ name: "failing", arguments: {} }),
+    });
+
+    expect(res.ok).toBe(true);
+    const body = (await res.json()) as {
+      content: Array<{ type: string; text: string }>;
+      isError: boolean;
+    };
+    expect(body.isError).toBe(true);
+    expect(body.content[0]!.text).toContain("handler boom");
+
+    stop();
+  });
+
+  test("passes context from factory to handler", async () => {
+    let capturedContext: ToolContext | null = null;
+    const tools = new Map<string, ToolDefinition>();
+    tools.set(
+      "ctx",
+      makeTool("ctx", (_input, ctx) => {
+        capturedContext = ctx;
+        return "ok";
+      }),
+    );
+
+    const customContext = (): ToolContext => ({
+      sessionID: "custom-session-123",
+      messageID: "msg-456",
+      agent: "opencode",
+      directory: "/custom/dir",
+      abort: new AbortController().signal,
+    });
+
+    const { port, stop } = await startToolDispatchServer(tools, customContext);
+
+    await fetch(`http://127.0.0.1:${port}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ name: "ctx", arguments: {} }),
+    });
+
+    expect(capturedContext).not.toBeNull();
+    expect(capturedContext!.sessionID).toBe("custom-session-123");
+    expect(capturedContext!.directory).toBe("/custom/dir");
+
+    stop();
+  });
+
+  test("handles async tool handlers", async () => {
+    const tools = new Map<string, ToolDefinition>();
+    tools.set(
+      "async-tool",
+      makeTool("async-tool", async (input) => {
+        await new Promise((r) => setTimeout(r, 10));
+        return { result: (input as Record<string, string>).input };
+      }),
+    );
+
+    const { port, stop } = await startToolDispatchServer(tools, makeContext);
+
+    const res = await fetch(`http://127.0.0.1:${port}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ name: "async-tool", arguments: { input: "async-data" } }),
+    });
+
+    expect(res.ok).toBe(true);
+    const body = (await res.json()) as { content: Array<{ type: string; text: string }> };
+    expect(body.content[0]!.text).toBe('{"result":"async-data"}');
+
+    stop();
+  });
+
+  test("rejects non-POST requests", async () => {
+    const tools = new Map<string, ToolDefinition>();
+    const { port, stop } = await startToolDispatchServer(tools, makeContext);
+
+    const res = await fetch(`http://127.0.0.1:${port}`, { method: "GET" });
+    expect(res.status).toBe(405);
+
+    stop();
+  });
+});
+
+describe("opencode-mcp-bridge script generation", () => {
+  afterEach(() => {
+    cleanupMcpBridgeScripts();
+  });
+
+  test("generated script contains dispatch URL instead of placeholder", async () => {
+    const tools: ToolDefinition[] = [
+      makeTool("test-tool", () => "result"),
+    ];
+
+    const scriptPath = await createToolMcpServerScript(tools, 12345);
+    const content = readFileSync(scriptPath, "utf-8");
+
+    // Should contain the dispatch URL
+    expect(content).toContain("http://127.0.0.1:12345");
+    expect(content).toContain("DISPATCH_URL");
+
+    // Should NOT contain the old placeholder
+    expect(content).not.toContain("executed via MCP bridge");
+
+    // Should contain fetch-based dispatch
+    expect(content).toContain("await fetch(DISPATCH_URL");
+  });
+
+  test("generated script lists tool definitions", async () => {
+    const tools: ToolDefinition[] = [
+      makeTool("alpha", () => "a"),
+      makeTool("beta", () => "b"),
+    ];
+
+    const scriptPath = await createToolMcpServerScript(tools, 9999);
+    const content = readFileSync(scriptPath, "utf-8");
+
+    expect(content).toContain('"alpha"');
+    expect(content).toContain('"beta"');
+    expect(content).toContain("Test tool: alpha");
+    expect(content).toContain("Test tool: beta");
+  });
+});
diff --git a/src/sdk/tools/opencode-mcp-bridge.ts b/src/sdk/tools/opencode-mcp-bridge.ts
index ce5ca359fe..bf089bdca7 100644
--- a/src/sdk/tools/opencode-mcp-bridge.ts
+++ b/src/sdk/tools/opencode-mcp-bridge.ts
@@ -4,36 +4,139 @@
  * Generates a temporary MCP server script that serves registered custom tools
  * over stdio, then registers it with the OpenCode server via sdkClient.mcp.add().
  *
- * This bridges the gap where OpenCodeClient.registerTool() stores tools but
- * doesn't inject them into the OpenCode server process.
+ * Tool execution is dispatched back to the main Atomic process via a local HTTP
+ * IPC server. This avoids the fundamental problem of serializing JavaScript
+ * handler closures across process boundaries.
+ *
+ * Architecture:
+ *   OpenCode server ──stdio──▶ MCP script ──HTTP──▶ Dispatch server (main process)
+ *                                                        │
+ *                                                   tool.handler()
  */
 
 import { mkdirSync, writeFileSync, unlinkSync, rmdirSync } from "fs";
 import { join } from "path";
 import { homedir } from "os";
-import type { ToolDefinition } from "../types.ts";
+import type { ToolDefinition, ToolContext } from "../types.ts";
 
 const TMP_DIR = join(homedir(), ".atomic", ".tmp");
 
 /** Track generated scripts for cleanup */
 const generatedScripts: string[] = [];
 
+// ============================================================================
+// Tool Dispatch HTTP Server
+// ============================================================================
+
+/** Active dispatch server instance */
+let dispatchServer: ReturnType<typeof Bun.serve> | null = null;
+
+/** Factory that produces a ToolContext for the current session state */
+export type ToolContextFactory = () => ToolContext;
+
+/**
+ * Start a local HTTP server that dispatches tool execution requests from the
+ * generated MCP script back to the in-process tool handlers.
+ *
+ * @param tools    - Registered tool definitions (name → ToolDefinition)
+ * @param contextFactory - Factory producing a ToolContext for handler invocations
+ * @returns The port the server is listening on and a stop function
+ */
+export async function startToolDispatchServer(
+  tools: Map<string, ToolDefinition>,
+  contextFactory: ToolContextFactory,
+): Promise<{ port: number; stop: () => void }> {
+  // Stop any existing server before starting a new one
+  stopToolDispatchServer();
+
+  const server = Bun.serve({
+    hostname: "127.0.0.1",
+    port: 0, // OS-assigned ephemeral port
+    async fetch(req: Request): Promise<Response> {
+      if (req.method !== "POST") {
+        return new Response("Method not allowed", { status: 405 });
+      }
+
+      try {
+        const body = (await req.json()) as {
+          name: string;
+          arguments?: Record<string, unknown>;
+        };
+        const { name, arguments: args } = body;
+
+        const tool = tools.get(name);
+        if (!tool) {
+          return Response.json(
+            { error: `Tool not found: ${name}` },
+            { status: 404 },
+          );
+        }
+
+        const context = contextFactory();
+        const result = await tool.handler(args ?? {}, context);
+        const text =
+          typeof result === "string" ? result : JSON.stringify(result);
+
+        return Response.json({
+          content: [{ type: "text", text }],
+        });
+      } catch (error: unknown) {
+        const message =
+          error instanceof Error ? error.message : String(error);
+        return Response.json({
+          content: [{ type: "text", text: `Error: ${message}` }],
+          isError: true,
+        });
+      }
+    },
+  });
+
+  dispatchServer = server;
+
+  return {
+    port: server.port as number,
+    stop: () => {
+      server.stop();
+      dispatchServer = null;
+    },
+  };
+}
+
+/**
+ * Stop the active tool dispatch server (if any).
+ * Called during process cleanup.
+ */
+export function stopToolDispatchServer(): void {
+  if (dispatchServer) {
+    dispatchServer.stop();
+    dispatchServer = null;
+  }
+}
+
+// ============================================================================
+// MCP Script Generation
+// ============================================================================
+
 /**
  * Generate a self-contained MCP stdio server script for the given tools.
- * The script reads JSON-RPC requests from stdin and dispatches to tool handlers.
+ * The script reads JSON-RPC requests from stdin and dispatches tool calls
+ * to the main Atomic process via HTTP IPC on the given port.
  */
 function generateMcpServerScript(
-  tools: { name: string; description: string; inputSchema: Record<string, unknown> }[]
+  tools: { name: string; description: string; inputSchema: Record<string, unknown> }[],
+  dispatchPort: number,
 ): string {
   const toolDefs = JSON.stringify(tools, null, 2);
 
   return `#!/usr/bin/env bun
 /**
  * Auto-generated MCP stdio server for Atomic custom tools.
+ * Tool execution is dispatched to the main Atomic process via HTTP IPC.
  * This file is temporary and will be cleaned up on process exit.
  */
 
 const TOOLS = ${toolDefs};
+const DISPATCH_URL = "http://127.0.0.1:${dispatchPort}";
 
 // Simple JSON-RPC over stdio MCP server
 const decoder = new TextDecoder();
@@ -57,7 +160,7 @@ process.stdin.on("data", (chunk) => {
   }
 });
 
-function handleRequest(request: { id?: number; method: string; params?: Record<string, unknown> }) {
+async function handleRequest(request: { id?: number; method: string; params?: Record<string, unknown> }) {
   const { id, method, params } = request;
 
   if (method === "initialize") {
@@ -76,15 +179,33 @@ function handleRequest(request: { id?: number; method: string; params?: Record<s
     });
   } else if (method === "tools/call") {
     const toolName = (params as Record<string, unknown>)?.name as string;
+    const toolArgs = ((params as Record<string, unknown>)?.arguments ?? {}) as Record<string, unknown>;
     const tool = TOOLS.find((t: { name: string }) => t.name === toolName);
+
     if (!tool) {
       respondError(id, -32601, \`Tool not found: \${toolName}\`);
-    } else {
-      // For MCP bridge, we return a placeholder — actual execution happens
-      // in the Atomic process via the registered handler
-      respond(id, {
-        content: [{ type: "text", text: \`Tool \${toolName} executed via MCP bridge\` }],
+      return;
+    }
+
+    try {
+      const res = await fetch(DISPATCH_URL, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ name: toolName, arguments: toolArgs }),
       });
+
+      const result = await res.json() as { content?: unknown[]; error?: string; isError?: boolean };
+
+      if (!res.ok && result.error) {
+        respondError(id, -32603, result.error);
+      } else {
+        respond(id, {
+          content: result.content ?? [{ type: "text", text: "Tool executed successfully" }],
+          isError: result.isError ?? false,
+        });
+      }
+    } catch (err) {
+      respondError(id, -32603, \`Tool dispatch failed: \${err instanceof Error ? err.message : String(err)}\`);
     }
   } else if (method === "notifications/initialized") {
     // No response needed for notifications
@@ -111,10 +232,15 @@ function respondError(id: number | undefined, code: number, message: string) {
 
 /**
  * Create a temporary .ts file that serves registered tools as an MCP stdio server.
+ * The script dispatches tool calls to the main process via HTTP on the given port.
+ *
+ * @param tools         - Tool definitions to expose
+ * @param dispatchPort  - Port of the local tool dispatch HTTP server
  * @returns The path to the generated script
  */
 export async function createToolMcpServerScript(
-  tools: ToolDefinition[]
+  tools: ToolDefinition[],
+  dispatchPort: number,
 ): Promise<string> {
   mkdirSync(TMP_DIR, { recursive: true });
 
@@ -125,7 +251,7 @@ export async function createToolMcpServerScript(
     inputSchema: t.inputSchema,
   }));
 
-  const script = generateMcpServerScript(toolDefs);
+  const script = generateMcpServerScript(toolDefs, dispatchPort);
   writeFileSync(scriptPath, script);
 
   generatedScripts.push(scriptPath);
diff --git a/src/sdk/types.ts b/src/sdk/types.ts
index 08e5d350c1..ba8b4b2ade 100644
--- a/src/sdk/types.ts
+++ b/src/sdk/types.ts
@@ -225,6 +225,11 @@ export interface ContextUsage {
   usagePercentage: number;
 }
 
+export interface SessionCompactionState {
+  isCompacting: boolean;
+  hasAutoCompacted: boolean;
+}
+
 /**
  * Interface for an active agent session.
  * Reference: Feature list step 3
@@ -245,10 +250,24 @@ export interface Session {
    * @param message - The message to send
    * @param options - Optional dispatch options. The `agent` field is used by
    *   the OpenCode client to dispatch to a named sub-agent via AgentPartInput.
-   *   Other clients ignore it.
+   *   Other clients ignore it. The optional `abortSignal` allows callers to
+   *   cancel local stream polling loops promptly.
    * @returns AsyncIterable yielding partial response chunks
    */
-  stream(message: string, options?: { agent?: string }): AsyncIterable<AgentMessage>;
+  stream(
+    message: string,
+    options?: { agent?: string; abortSignal?: AbortSignal },
+  ): AsyncIterable<AgentMessage>;
+
+  /**
+   * Fire-and-forget message send for async/event-driven streaming.
+   * The prompt is initiated but the response is delivered exclusively
+   * through SSE events (message.delta, session.idle, etc.).
+   * Only implemented by OpenCode; other clients may omit this.
+   * @param message - The message to send
+   * @param options - Optional dispatch options
+   */
+  sendAsync?(message: string, options?: { agent?: string; abortSignal?: AbortSignal }): Promise<void>;
 
   /**
    * Summarize the current conversation to reduce context usage.
@@ -275,6 +294,12 @@ export interface Session {
    */
   getMcpSnapshot?(): Promise<McpRuntimeSnapshot | null>;
 
+  /**
+   * Optional compaction state snapshot for conflict-safe context monitoring.
+   * Implementations may omit this and callers should gracefully fall back.
+   */
+  getCompactionState?(): SessionCompactionState | null;
+
   /**
    * Destroy the session and release resources.
    * Should be called when the session is no longer needed.
@@ -288,6 +313,16 @@ export interface Session {
    * @returns Promise resolving when the abort request is acknowledged
    */
   abort?(): Promise<void>;
+
+  /**
+   * Abort only background agents while preserving foreground work.
+   * Used for Ctrl+F background agent termination.
+   * Implementations should selectively terminate background agent
+   * sessions/queries without affecting the main foreground session.
+   * Falls back to full session abort when granular control is unavailable.
+   * @returns Promise resolving when all background agents are aborted
+   */
+  abortBackgroundAgents?(): Promise<void>;
 }
 
 /**
@@ -298,13 +333,24 @@ export type EventType =
   | "session.start"
   | "session.idle"
   | "session.error"
+  | "session.info"
+  | "session.warning"
+  | "session.title_changed"
+  | "session.truncation"
+  | "session.compaction"
   | "message.delta"
   | "message.complete"
+  | "reasoning.delta"
+  | "reasoning.complete"
+  | "turn.start"
+  | "turn.end"
   | "tool.start"
   | "tool.complete"
+  | "tool.partial_result"
   | "skill.invoked"
   | "subagent.start"
   | "subagent.complete"
+  | "subagent.update"
   | "permission.requested"
   | "human_input_required"
   | "usage";
@@ -353,6 +399,10 @@ export interface MessageDeltaEventData extends BaseEventData {
   contentType?: MessageContentType;
   /** Provider-native thinking source identity (for reasoning/thinking deltas) */
   thinkingSourceKey?: string;
+  /** Parent tool call ID when this delta belongs to a sub-agent */
+  parentToolCallId?: string;
+  /** Runtime message ID for per-message correlation */
+  messageId?: string;
 }
 
 /**
@@ -361,6 +411,14 @@ export interface MessageDeltaEventData extends BaseEventData {
 export interface MessageCompleteEventData extends BaseEventData {
   /** Complete message */
   message: AgentMessage;
+  /** Tool requests made by the model in this message (Copilot SDK) */
+  toolRequests?: Array<{
+    toolCallId: string;
+    name: string;
+    arguments: unknown;
+  }>;
+  /** Parent tool call ID when this message is from a sub-agent */
+  parentToolCallId?: string;
 }
 
 /**
@@ -409,6 +467,108 @@ export interface SkillInvokedEventData extends BaseEventData {
   skillPath?: string;
 }
 
+/**
+ * Event data for reasoning.delta events (streaming thinking content)
+ */
+export interface ReasoningDeltaEventData extends BaseEventData {
+  /** Partial reasoning content */
+  delta: string;
+  /** Reasoning block identifier */
+  reasoningId: string;
+}
+
+/**
+ * Event data for reasoning.complete events
+ */
+export interface ReasoningCompleteEventData extends BaseEventData {
+  /** Reasoning block identifier */
+  reasoningId: string;
+  /** Complete reasoning content */
+  content: string;
+}
+
+/**
+ * Event data for turn.start events
+ */
+export interface TurnStartEventData extends BaseEventData {
+  /** Unique turn identifier */
+  turnId: string;
+}
+
+/**
+ * Event data for turn.end events
+ */
+export interface TurnEndEventData extends BaseEventData {
+  /** Unique turn identifier */
+  turnId: string;
+  /** Provider-reported normalized finish reason, if available */
+  finishReason?: string;
+  /** Provider-native finish reason token (for diagnostics/parity) */
+  rawFinishReason?: string;
+}
+
+/**
+ * Event data for tool.partial_result events (streaming tool output)
+ */
+export interface ToolPartialResultEventData extends BaseEventData {
+  /** Tool call ID this output belongs to */
+  toolCallId: string;
+  /** Incremental output text */
+  partialOutput: string;
+}
+
+/**
+ * Event data for session.info events
+ */
+export interface SessionInfoEventData extends BaseEventData {
+  /** Information category */
+  infoType: string;
+  /** Human-readable message */
+  message: string;
+}
+
+/**
+ * Event data for session.warning events
+ */
+export interface SessionWarningEventData extends BaseEventData {
+  /** Warning category */
+  warningType: string;
+  /** Human-readable message */
+  message: string;
+}
+
+/**
+ * Event data for session.title_changed events
+ */
+export interface SessionTitleChangedEventData extends BaseEventData {
+  /** New session title */
+  title: string;
+}
+
+/**
+ * Event data for session.truncation events
+ */
+export interface SessionTruncationEventData extends BaseEventData {
+  /** Maximum token budget */
+  tokenLimit: number;
+  /** Tokens removed during truncation */
+  tokensRemoved: number;
+  /** Messages removed during truncation */
+  messagesRemoved: number;
+}
+
+/**
+ * Event data for session.compaction events
+ */
+export interface SessionCompactionEventData extends BaseEventData {
+  /** Whether this is a start or complete event */
+  phase: "start" | "complete";
+  /** Whether compaction succeeded (only for complete phase) */
+  success?: boolean;
+  /** Error message on failure (only for complete phase) */
+  error?: string;
+}
+
 /**
  * Event data for subagent.start events
  */
@@ -419,12 +579,26 @@ export interface SubagentStartEventData extends BaseEventData {
   subagentType?: string;
   /** Task assigned to the subagent */
   task?: string;
+  /** SDK-native tool use ID (camelCase variant) */
+  toolUseId?: string;
   /** SDK-native tool use ID (Claude hook variant) */
   toolUseID?: string;
   /** SDK-native tool call ID (Copilot variant) */
   toolCallId?: string;
 }
 
+/**
+ * Event data for subagent.update events (progress notification)
+ */
+export interface SubagentUpdateEventData extends BaseEventData {
+  /** Subagent identifier */
+  subagentId: string;
+  /** Current tool being used by the sub-agent */
+  currentTool?: string;
+  /** Number of tool uses so far */
+  toolUses?: number;
+}
+
 /**
  * Event data for subagent.complete events
  */
@@ -509,13 +683,24 @@ export interface EventDataMap {
   "session.start": SessionStartEventData;
   "session.idle": SessionIdleEventData;
   "session.error": SessionErrorEventData;
+  "session.info": SessionInfoEventData;
+  "session.warning": SessionWarningEventData;
+  "session.title_changed": SessionTitleChangedEventData;
+  "session.truncation": SessionTruncationEventData;
+  "session.compaction": SessionCompactionEventData;
   "message.delta": MessageDeltaEventData;
   "message.complete": MessageCompleteEventData;
+  "reasoning.delta": ReasoningDeltaEventData;
+  "reasoning.complete": ReasoningCompleteEventData;
+  "turn.start": TurnStartEventData;
+  "turn.end": TurnEndEventData;
   "tool.start": ToolStartEventData;
   "tool.complete": ToolCompleteEventData;
+  "tool.partial_result": ToolPartialResultEventData;
   "skill.invoked": SkillInvokedEventData;
   "subagent.start": SubagentStartEventData;
   "subagent.complete": SubagentCompleteEventData;
+  "subagent.update": SubagentUpdateEventData;
   "permission.requested": PermissionRequestedEventData;
   "human_input_required": HumanInputRequiredEventData;
 }
@@ -659,6 +844,9 @@ export interface CodingAgentClient {
    * Returns null if the baseline is not yet available.
    */
   getSystemToolsTokens(): number | null;
+
+  /** Known agent/sub-agent tool names (Copilot uses agent names as tool names) */
+  getKnownAgentNames?(): string[];
 }
 
 /**
diff --git a/src/sdk/unified-event-parity.test.ts b/src/sdk/unified-event-parity.test.ts
index 690276d77e..9c238a0977 100644
--- a/src/sdk/unified-event-parity.test.ts
+++ b/src/sdk/unified-event-parity.test.ts
@@ -2,15 +2,34 @@ import { describe, expect, mock, test } from "bun:test";
 import { ClaudeAgentClient, OpenCodeClient, CopilotClient } from "./clients/index.ts";
 import { extractMessageContent } from "./clients/claude.ts";
 import type { EventType } from "./types.ts";
+import {
+  ADAPTER_EVENT_COVERAGE_POLICY,
+  ALL_SDK_EVENT_TYPES,
+  assertAdapterEventCoveragePolicyInvariant,
+} from "../events/adapters/event-coverage-policy.ts";
+import {
+  getRuntimeParityMetricsSnapshot,
+  resetRuntimeParityMetrics,
+} from "../workflows/runtime-parity-observability.ts";
 
 const PARITY_EVENTS: EventType[] = [
   "session.start",
   "session.idle",
   "session.error",
+  "session.info",
+  "session.warning",
+  "session.title_changed",
+  "session.truncation",
+  "session.compaction",
   "message.delta",
   "message.complete",
+  "reasoning.delta",
+  "reasoning.complete",
+  "turn.start",
+  "turn.end",
   "tool.start",
   "tool.complete",
+  "tool.partial_result",
   "skill.invoked",
   "subagent.start",
   "subagent.complete",
@@ -151,7 +170,7 @@ describe("Unified provider event parity", () => {
     const openCodeSourceKeys: string[] = [];
     const unsubscribeOpenCode = openCodeClient.on("message.delta", (event) => {
       const data = event.data as { contentType?: string; thinkingSourceKey?: string };
-      if (data.contentType === "reasoning" && data.thinkingSourceKey) {
+      if (data.contentType === "thinking" && data.thinkingSourceKey) {
         openCodeSourceKeys.push(data.thinkingSourceKey);
       }
     });
@@ -169,6 +188,18 @@ describe("Unified provider event parity", () => {
           messageID: "msg_reasoning",
           type: "reasoning",
         },
+      },
+    });
+
+    (
+      openCodeClient as unknown as {
+        handleSdkEvent: (event: Record<string, unknown>) => void;
+      }
+    ).handleSdkEvent({
+      type: "message.part.delta",
+      properties: {
+        partID: "reasoning_part_a",
+        sessionID: "ses_reasoning",
         delta: "alpha",
       },
     });
@@ -178,14 +209,10 @@ describe("Unified provider event parity", () => {
         handleSdkEvent: (event: Record<string, unknown>) => void;
       }
     ).handleSdkEvent({
-      type: "message.part.updated",
+      type: "message.part.delta",
       properties: {
-        part: {
-          id: "reasoning_part_a",
-          sessionID: "ses_reasoning",
-          messageID: "msg_reasoning",
-          type: "reasoning",
-        },
+        partID: "reasoning_part_a",
+        sessionID: "ses_reasoning",
         delta: "beta",
       },
     });
@@ -278,4 +305,32 @@ describe("Unified provider event parity", () => {
 
     expect(copilotSourceKeys).toEqual(["reasoning_123", "reasoning_123"]);
   });
+
+  test("event coverage policy parity stays consistent across providers", () => {
+    resetRuntimeParityMetrics();
+    assertAdapterEventCoveragePolicyInvariant();
+
+    const metrics = getRuntimeParityMetricsSnapshot();
+    for (const provider of ["opencode", "claude", "copilot"] as const) {
+      expect(
+        metrics.counters[
+          `workflow.runtime.parity.event_coverage_validations_total{provider=${provider}}`
+        ],
+      ).toBe(1);
+      expect(
+        metrics.histograms[
+          `workflow.runtime.parity.event_coverage_mapped_events{provider=${provider}}`
+        ],
+      ).toEqual([ALL_SDK_EVENT_TYPES.length - 1]);
+      expect(
+        metrics.gauges[
+          `workflow.runtime.parity.event_coverage_noop_events{provider=${provider}}`
+        ],
+      ).toBe(1);
+    }
+
+    expect(ADAPTER_EVENT_COVERAGE_POLICY.copilot["message.complete"].canonicalEvents).toContain(
+      "stream.tool.start",
+    );
+  });
 });
diff --git a/src/telemetry/telemetry-file-io.test.ts b/src/telemetry/telemetry-file-io.test.ts
new file mode 100644
index 0000000000..fceb9b29d7
--- /dev/null
+++ b/src/telemetry/telemetry-file-io.test.ts
@@ -0,0 +1,151 @@
+/**
+ * Tests for telemetry-file-io.ts — verifies appendEvent uses file locking
+ * via withLock() and writes JSONL events correctly.
+ */
+import { describe, expect, test, beforeEach, afterEach, mock } from "bun:test";
+import { existsSync, mkdirSync, readFileSync, rmSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { appendEvent, getEventsFilePath } from "./telemetry-file-io";
+import { getLockPath } from "../utils/file-lock";
+import type { TelemetryEvent } from "./types";
+
+// Use a temp directory to avoid polluting real data dirs
+const TEST_DIR = join(tmpdir(), `telemetry-file-io-test-${process.pid}`);
+
+// Mock getBinaryDataDir to use our temp directory
+mock.module("../utils/config-path", () => ({
+  getBinaryDataDir: () => TEST_DIR,
+}));
+
+function makeEvent(overrides: Record<string, unknown> = {}): TelemetryEvent {
+  return {
+    eventType: "atomic_command",
+    anonymousId: "test-anon-id",
+    timestamp: "2026-01-15T12:00:00.000Z",
+    ...overrides,
+  } as unknown as TelemetryEvent;
+}
+
+describe("telemetry-file-io", () => {
+  beforeEach(() => {
+    if (existsSync(TEST_DIR)) {
+      rmSync(TEST_DIR, { recursive: true, force: true });
+    }
+  });
+
+  afterEach(() => {
+    if (existsSync(TEST_DIR)) {
+      rmSync(TEST_DIR, { recursive: true, force: true });
+    }
+  });
+
+  describe("getEventsFilePath", () => {
+    test("returns path with agent type suffix", () => {
+      const path = getEventsFilePath("claude");
+      expect(path).toBe(join(TEST_DIR, "telemetry-events-claude.jsonl"));
+    });
+
+    test("defaults to 'atomic' when no agent type", () => {
+      const path = getEventsFilePath();
+      expect(path).toBe(join(TEST_DIR, "telemetry-events-atomic.jsonl"));
+    });
+
+    test("defaults to 'atomic' when null agent type", () => {
+      const path = getEventsFilePath(null);
+      expect(path).toBe(join(TEST_DIR, "telemetry-events-atomic.jsonl"));
+    });
+  });
+
+  describe("appendEvent", () => {
+    test("creates data directory if it does not exist", async () => {
+      expect(existsSync(TEST_DIR)).toBe(false);
+      await appendEvent(makeEvent());
+      expect(existsSync(TEST_DIR)).toBe(true);
+    });
+
+    test("writes event as a single JSONL line", async () => {
+      const event = makeEvent({ event: "command_executed" });
+      await appendEvent(event, "claude");
+
+      const filePath = join(TEST_DIR, "telemetry-events-claude.jsonl");
+      const content = readFileSync(filePath, "utf-8");
+      const lines = content.trim().split("\n");
+
+      expect(lines).toHaveLength(1);
+      expect(JSON.parse(lines[0]!)).toEqual(event);
+    });
+
+    test("appends multiple events as separate lines", async () => {
+      const event1 = makeEvent({ timestamp: "2026-01-15T12:00:00.000Z" });
+      const event2 = makeEvent({ timestamp: "2026-01-15T12:01:00.000Z" });
+
+      await appendEvent(event1);
+      await appendEvent(event2);
+
+      const filePath = join(TEST_DIR, "telemetry-events-atomic.jsonl");
+      const content = readFileSync(filePath, "utf-8");
+      const lines = content.trim().split("\n");
+
+      expect(lines).toHaveLength(2);
+      expect(JSON.parse(lines[0]!)).toEqual(event1);
+      expect(JSON.parse(lines[1]!)).toEqual(event2);
+    });
+
+    test("does not leave lock files after write", async () => {
+      const event = makeEvent();
+      await appendEvent(event, "copilot");
+
+      const eventsPath = join(TEST_DIR, "telemetry-events-copilot.jsonl");
+      const lockPath = getLockPath(eventsPath);
+      expect(existsSync(lockPath)).toBe(false);
+    });
+
+    test("isolates events by agent type", async () => {
+      await appendEvent(makeEvent({ event: "command_executed" }), "claude");
+      await appendEvent(makeEvent({ event: "session_end" }), "copilot");
+
+      const claudeContent = readFileSync(join(TEST_DIR, "telemetry-events-claude.jsonl"), "utf-8");
+      const copilotContent = readFileSync(join(TEST_DIR, "telemetry-events-copilot.jsonl"), "utf-8");
+
+      expect(claudeContent.trim().split("\n")).toHaveLength(1);
+      expect(copilotContent.trim().split("\n")).toHaveLength(1);
+      expect(JSON.parse(claudeContent.trim()).event).toBe("command_executed");
+      expect(JSON.parse(copilotContent.trim()).event).toBe("session_end");
+    });
+
+    test("fails silently on errors", async () => {
+      // Passing an event that would cause issues shouldn't throw
+      // Create a read-only scenario by making dataDir a file instead of dir
+      mkdirSync(TEST_DIR, { recursive: true });
+
+      // This should not throw even if internals fail
+      const circular = {} as Record<string, unknown>;
+      circular.self = circular;
+
+      // JSON.stringify with circular reference would throw, but appendEvent catches it
+      await expect(
+        appendEvent(circular as unknown as TelemetryEvent)
+      ).resolves.toBeUndefined();
+    });
+
+    test("concurrent writes all succeed with locking", async () => {
+      const events = Array.from({ length: 10 }, (_, i) =>
+        makeEvent({ timestamp: `2026-01-15T12:0${i}:00.000Z` })
+      );
+
+      // Fire all writes concurrently
+      await Promise.all(events.map((e) => appendEvent(e)));
+
+      const filePath = join(TEST_DIR, "telemetry-events-atomic.jsonl");
+      const content = readFileSync(filePath, "utf-8");
+      const lines = content.trim().split("\n");
+
+      expect(lines).toHaveLength(10);
+      // Each line should be valid JSON
+      for (const line of lines) {
+        expect(() => JSON.parse(line)).not.toThrow();
+      }
+    });
+  });
+});
diff --git a/src/telemetry/telemetry-file-io.ts b/src/telemetry/telemetry-file-io.ts
index 70611a5e76..bff07d2a8d 100644
--- a/src/telemetry/telemetry-file-io.ts
+++ b/src/telemetry/telemetry-file-io.ts
@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, appendFileSync } from "fs";
 import { join } from "path";
 import { getBinaryDataDir } from "../utils/config-path";
+import { withLock } from "../utils/file-lock";
 import type { TelemetryEvent, AgentType } from "./types";
 
 /**
@@ -21,13 +22,14 @@ export function getEventsFilePath(agentType?: AgentType | null): string {
 
 /**
  * Append an event to the telemetry events JSONL file.
- * Uses atomic append-only writes for concurrent safety.
+ * Uses file locking via withLock() for concurrent write safety,
+ * with OS-level O_APPEND as a fallback guarantee.
  * Fails silently to ensure telemetry never breaks operation.
  *
  * @param event - The event object to append
  * @param agentType - Optional agent type for file isolation
  */
-export function appendEvent(event: TelemetryEvent, agentType?: AgentType | null): void {
+export async function appendEvent(event: TelemetryEvent, agentType?: AgentType | null): Promise<void> {
   try {
     const dataDir = getBinaryDataDir();
 
@@ -39,14 +41,9 @@ export function appendEvent(event: TelemetryEvent, agentType?: AgentType | null)
     const eventsPath = getEventsFilePath(agentType);
     const line = JSON.stringify(event) + "\n";
 
-    // appendFileSync relies on OS-level O_APPEND atomicity for concurrent safety.
-    // This is sufficient for our use case without explicit file locking because:
-    // - Low frequency: Events are infrequent (1 per command/session, minutes apart)
-    // - Small writes: Events are ~300-500 bytes (well under PIPE_BUF of 4KB)
-    // - File isolation: Different agent types write to separate files
-    // - Local filesystem: POSIX guarantees prevent data clobbering on local filesystems
-    // File locking would add overhead without meaningful benefit given these constraints.
-    appendFileSync(eventsPath, line, "utf-8");
+    await withLock(eventsPath, () => {
+      appendFileSync(eventsPath, line, "utf-8");
+    });
   } catch {
     // Fail silently - telemetry should never break the application
   }
diff --git a/src/telemetry/telemetry-tui.ts b/src/telemetry/telemetry-tui.ts
index 371041ca93..49325abea3 100644
--- a/src/telemetry/telemetry-tui.ts
+++ b/src/telemetry/telemetry-tui.ts
@@ -219,7 +219,7 @@ export class TuiTelemetrySessionTracker {
     appendEvent(event, this.agentType);
   }
 
-  trackBackgroundTermination(action: "noop" | "warn" | "execute", activeAgentCount: number, interruptedCount?: number): void {
+  trackBackgroundTermination(action: "noop" | "warn" | "execute" | "fallback", activeAgentCount: number, interruptedCount?: number): void {
     if (!this.enabled || !this.anonymousId || this.ended) {
       return;
     }
@@ -228,7 +228,7 @@ export class TuiTelemetrySessionTracker {
       this.backgroundTerminationNoopCount++;
     } else if (action === "warn") {
       this.backgroundTerminationWarnCount++;
-    } else if (action === "execute") {
+    } else if (action === "execute" || action === "fallback") {
       this.backgroundTerminationExecuteCount++;
     }
 
diff --git a/src/telemetry/telemetry-upload.test.ts b/src/telemetry/telemetry-upload.test.ts
index a41846fa65..ce31ff7b1e 100644
--- a/src/telemetry/telemetry-upload.test.ts
+++ b/src/telemetry/telemetry-upload.test.ts
@@ -2,7 +2,7 @@
  * Tests for filterStaleEvents, splitIntoBatches, and readEventsFromJSONL functions
  * Reference: specs/phase-6-telemetry-upload-backend.md
  */
-import { describe, expect, test, beforeEach, afterEach } from "bun:test";
+import { describe, expect, test, beforeEach, afterEach, spyOn } from "bun:test";
 import { writeFileSync, mkdirSync, rmSync } from "fs";
 import { join } from "path";
 import { tmpdir } from "os";
@@ -120,22 +120,40 @@ describe("filterStaleEvents", () => {
     });
 
     test("keeps events exactly at the boundary (cutoff time is inclusive)", () => {
-      const boundaryEvent = makeEvent(makeTimestamp(-maxAge)); // Exactly 30 days ago
-
-      const result = filterStaleEvents([boundaryEvent]);
-
-      // Events at exactly cutoff time should be kept (>= cutoff)
-      expect(result.valid).toHaveLength(1);
-      expect(result.staleCount).toBe(0);
+      // Mock Date.now() to prevent race condition between timestamp creation and filtering
+      // Without this, time can pass between makeTimestamp() and filterStaleEvents(),
+      // causing the boundary event to become slightly too old
+      const fixedNow = 1672531200000; // 2023-01-01T00:00:00.000Z
+      const dateNowSpy = spyOn(Date, "now").mockReturnValue(fixedNow);
+
+      try {
+        const boundaryEvent = makeEvent(makeTimestamp(-maxAge)); // Exactly 30 days ago
+
+        const result = filterStaleEvents([boundaryEvent]);
+
+        // Events at exactly cutoff time should be kept (>= cutoff)
+        expect(result.valid).toHaveLength(1);
+        expect(result.staleCount).toBe(0);
+      } finally {
+        dateNowSpy.mockRestore();
+      }
     });
 
     test("removes events just before the boundary", () => {
-      const justStaleEvent = makeEvent(makeTimestamp(-maxAge - 1)); // 1ms over 30 days
+      // Mock Date.now() to prevent race condition
+      const fixedNow = 1672531200000; // 2023-01-01T00:00:00.000Z
+      const dateNowSpy = spyOn(Date, "now").mockReturnValue(fixedNow);
 
-      const result = filterStaleEvents([justStaleEvent]);
+      try {
+        const justStaleEvent = makeEvent(makeTimestamp(-maxAge - 1)); // 1ms over 30 days
 
-      expect(result.valid).toHaveLength(0);
-      expect(result.staleCount).toBe(1);
+        const result = filterStaleEvents([justStaleEvent]);
+
+        expect(result.valid).toHaveLength(0);
+        expect(result.staleCount).toBe(1);
+      } finally {
+        dateNowSpy.mockRestore();
+      }
     });
   });
 
diff --git a/src/telemetry/types.ts b/src/telemetry/types.ts
index 61bec187fa..2ff3431124 100644
--- a/src/telemetry/types.ts
+++ b/src/telemetry/types.ts
@@ -198,7 +198,7 @@ export interface TuiBackgroundTerminationEvent extends TelemetryEventBase {
   source: "tui";
   sessionId: string;
   agentType: AgentType;
-  action: "noop" | "warn" | "execute";
+  action: "noop" | "warn" | "execute" | "fallback";
   activeAgentCount: number;
   interruptedCount?: number;
 }
diff --git a/src/ui/chat.at-command-single-assistant-message.test.ts b/src/ui/chat.at-command-single-assistant-message.test.ts
new file mode 100644
index 0000000000..bcef807d05
--- /dev/null
+++ b/src/ui/chat.at-command-single-assistant-message.test.ts
@@ -0,0 +1,135 @@
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+import { globalRegistry } from "./commands/index.ts";
+import { createMessage, shouldHideStaleSubagentToolPlaceholder, type ChatMessage } from "./chat.tsx";
+import { parseAtMentions } from "./utils/mention-parsing.ts";
+
+type SetMessagesWindowed = (updater: (prev: ChatMessage[]) => ChatMessage[]) => void;
+
+function submitAtCommandInvocation(
+  message: string,
+  deps: {
+    setMessagesWindowed: SetMessagesWindowed;
+    executeCommand: (commandName: string, args: string, trigger: "mention") => void;
+  },
+): void {
+  const atMentions = parseAtMentions(message);
+  if (atMentions.length === 0) return;
+
+  deps.setMessagesWindowed((prev) => [...prev, createMessage("user", message)]);
+  for (const mention of atMentions) {
+    deps.executeCommand(mention.agentName, mention.args, "mention");
+  }
+}
+
+describe("@ command assistant message contract", () => {
+  let agentName = "";
+
+  beforeEach(() => {
+    agentName = `single-assistant-agent-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+    globalRegistry.register({
+      name: agentName,
+      description: "test agent",
+      category: "agent",
+      execute: () => ({ success: true }),
+    });
+  });
+
+  afterEach(() => {
+    globalRegistry.unregister(agentName);
+  });
+
+  test("creates exactly one assistant message per @ command invocation", () => {
+    let messages: ChatMessage[] = [];
+    const setMessagesWindowed = mock((updater: (prev: ChatMessage[]) => ChatMessage[]) => {
+      messages = updater(messages);
+      return messages;
+    });
+
+    const sendSilentMessage = () => {
+      const assistantMessage = createMessage("assistant", "", true);
+      setMessagesWindowed((prev) => [...prev, assistantMessage]);
+    };
+
+    const executeCommand = mock((_commandName: string, _args: string, _trigger: "mention") => {
+      sendSilentMessage();
+    });
+
+    submitAtCommandInvocation(`@${agentName} summarize the latest changes`, {
+      setMessagesWindowed,
+      executeCommand,
+    });
+
+    expect(executeCommand).toHaveBeenCalledTimes(1);
+    expect(messages.filter((message) => message.role === "assistant")).toHaveLength(1);
+    expect(messages.filter((message) => message.role === "user")).toHaveLength(1);
+
+    const assistantMessageAppenderCalls = setMessagesWindowed.mock.calls.filter(([updater]) => {
+      const candidate = updater([]);
+      return candidate.length === 1 && candidate[0]?.role === "assistant";
+    });
+    expect(assistantMessageAppenderCalls).toHaveLength(1);
+  });
+});
+
+describe("stale task placeholder filtering", () => {
+  test("hides stale assistant message that only contains sub-agent task tool parts", () => {
+    const message = createMessage("assistant", "", false);
+    message.parts = [
+      {
+        id: "tool-part-1",
+        type: "tool",
+        toolCallId: "tool-1",
+        toolName: "task",
+        input: {},
+        state: { status: "running", startedAt: "2026-03-02T00:00:00.000Z" },
+        createdAt: "2026-03-02T00:00:00.000Z",
+      },
+    ];
+
+    expect(shouldHideStaleSubagentToolPlaceholder(message, new Set())).toBe(true);
+  });
+
+  test("keeps active message ids visible", () => {
+    const message = createMessage("assistant", "", false);
+    message.parts = [
+      {
+        id: "tool-part-1",
+        type: "tool",
+        toolCallId: "tool-1",
+        toolName: "task",
+        input: {},
+        state: { status: "running", startedAt: "2026-03-02T00:00:00.000Z" },
+        createdAt: "2026-03-02T00:00:00.000Z",
+      },
+    ];
+
+    expect(shouldHideStaleSubagentToolPlaceholder(message, new Set([message.id]))).toBe(false);
+  });
+
+  test("keeps messages that already have parallel agents", () => {
+    const message = createMessage("assistant", "", false);
+    message.parts = [
+      {
+        id: "tool-part-1",
+        type: "tool",
+        toolCallId: "tool-1",
+        toolName: "task",
+        input: {},
+        state: { status: "running", startedAt: "2026-03-02T00:00:00.000Z" },
+        createdAt: "2026-03-02T00:00:00.000Z",
+      },
+    ];
+    message.parallelAgents = [
+      {
+        id: "agent-1",
+        taskToolCallId: "tool-1",
+        name: "codebase-online-researcher",
+        task: "TUI UX best practices",
+        status: "pending",
+        startedAt: "2026-03-02T00:00:00.000Z",
+      },
+    ];
+
+    expect(shouldHideStaleSubagentToolPlaceholder(message, new Set())).toBe(false);
+  });
+});
diff --git a/src/ui/chat.consolidated-completion.test.ts b/src/ui/chat.consolidated-completion.test.ts
new file mode 100644
index 0000000000..f9267fa071
--- /dev/null
+++ b/src/ui/chat.consolidated-completion.test.ts
@@ -0,0 +1,506 @@
+/**
+ * Tests for Fix 5C — Consolidated React state updates in handleStreamComplete
+ *
+ * Validates that the Path 3 (normal completion) logic in handleStreamComplete
+ * correctly:
+ * 1. Filters agents by existing message agent IDs (no orphans)
+ * 2. Finalizes running/pending agents while preserving background agents
+ * 3. Computes remaining background agents for post-stream tracking
+ * 4. Produces the correct finalized message state in a single updater pass
+ *
+ * The previous implementation nested setMessagesWindowed inside
+ * setParallelAgents with a no-op read-only state update. The consolidated
+ * version performs both reads and writes in a single setMessagesWindowed
+ * updater and calls setParallelAgents back-to-back (not nested).
+ */
+
+import { describe, expect, test } from "bun:test";
+import type { ParallelAgent } from "./components/parallel-agents-tree.tsx";
+import { getActiveBackgroundAgents } from "./utils/background-agent-footer.ts";
+import { finalizeStreamingReasoningInMessage } from "./parts/index.ts";
+import type { ChatMessage } from "./chat.tsx";
+
+// ---------------------------------------------------------------------------
+// Helpers — mirror the consolidated Path 3 logic from handleStreamComplete
+// ---------------------------------------------------------------------------
+
+function createAgent(overrides: Partial<ParallelAgent>): ParallelAgent {
+  return {
+    id: "agent-1",
+    name: "Test Agent",
+    task: "Test task",
+    status: "running",
+    startedAt: new Date(Date.now() - 2000).toISOString(),
+    background: false,
+    ...overrides,
+  };
+}
+
+function createMessage(overrides: Partial<ChatMessage>): ChatMessage {
+  return {
+    id: "msg-1",
+    role: "assistant" as const,
+    content: "Hello",
+    streaming: true,
+    ...overrides,
+  } as ChatMessage;
+}
+
+/**
+ * Mirrors the consolidated single-updater logic from Path 3:
+ * - Reads existing agent IDs from the message
+ * - Filters current agents to only those on the message
+ * - Finalizes running/pending foreground agents
+ * - Returns the finalized agents array
+ */
+function computeFinalizedAgents(
+  messageAgents: ParallelAgent[] | undefined,
+  currentAgents: ParallelAgent[],
+): ParallelAgent[] | undefined {
+  const existingAgentIds = new Set<string>();
+  if (messageAgents) {
+    for (const agent of messageAgents) {
+      existingAgentIds.add(agent.id);
+    }
+  }
+
+  return currentAgents.length > 0
+    ? currentAgents
+        .filter((a) => existingAgentIds.has(a.id))
+        .map((a) => {
+          if (a.background) return a;
+          return a.status === "running" || a.status === "pending"
+            ? {
+                ...a,
+                status: "completed" as const,
+                currentTool: undefined,
+                durationMs: Date.now() - new Date(a.startedAt).getTime(),
+              }
+            : a;
+        })
+    : undefined;
+}
+
+function appendBackgroundMessageInOrder(
+  prev: ChatMessage[],
+  message: ChatMessage,
+  refs: {
+    backgroundAgentMessageId: string | null;
+    streamingMessageId: string | null;
+    lastStreamedMessageId: string | null;
+  },
+): ChatMessage[] {
+  refs.backgroundAgentMessageId = message.id;
+  return [...prev, message];
+}
+
+function finalizeActiveStreamingMessage(
+  prev: ChatMessage[],
+  activeStreamingMessageId: string | null,
+): ChatMessage[] {
+  if (!activeStreamingMessageId) {
+    return prev;
+  }
+
+  return prev.map((msg) =>
+    msg.id === activeStreamingMessageId && msg.role === "assistant" && msg.streaming
+      ? {
+          ...finalizeStreamingReasoningInMessage(msg),
+          streaming: false,
+          completedAt: new Date(),
+        }
+      : msg,
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Tests — Consolidated completion path
+// ---------------------------------------------------------------------------
+
+describe("Consolidated completion state updates (Fix 5C)", () => {
+  describe("Agent filtering by message ownership", () => {
+    test("filters out orphaned agents not present on the message", () => {
+      const messageAgents = [
+        createAgent({ id: "a1" }),
+        createAgent({ id: "a2" }),
+      ];
+      const currentAgents = [
+        createAgent({ id: "a1", status: "running" }),
+        createAgent({ id: "a2", status: "running" }),
+        createAgent({ id: "orphan", status: "running" }), // Not on message
+      ];
+
+      const result = computeFinalizedAgents(messageAgents, currentAgents);
+
+      expect(result).toBeDefined();
+      expect(result!.length).toBe(2);
+      expect(result!.map((a) => a.id)).toEqual(["a1", "a2"]);
+      // Orphan should be filtered out
+      expect(result!.find((a) => a.id === "orphan")).toBeUndefined();
+    });
+
+    test("returns all agents when all are on the message", () => {
+      const messageAgents = [
+        createAgent({ id: "a1" }),
+        createAgent({ id: "a2" }),
+      ];
+      const currentAgents = [
+        createAgent({ id: "a1", status: "running" }),
+        createAgent({ id: "a2", status: "completed" }),
+      ];
+
+      const result = computeFinalizedAgents(messageAgents, currentAgents);
+
+      expect(result).toBeDefined();
+      expect(result!.length).toBe(2);
+    });
+
+    test("returns undefined when currentAgents is empty", () => {
+      const messageAgents = [createAgent({ id: "a1" })];
+      const result = computeFinalizedAgents(messageAgents, []);
+      expect(result).toBeUndefined();
+    });
+
+    test("returns empty array when no agents match message IDs", () => {
+      const messageAgents = [createAgent({ id: "a1" })];
+      const currentAgents = [createAgent({ id: "orphan", status: "running" })];
+
+      const result = computeFinalizedAgents(messageAgents, currentAgents);
+
+      expect(result).toBeDefined();
+      expect(result!.length).toBe(0);
+    });
+
+    test("handles undefined message agents", () => {
+      const currentAgents = [createAgent({ id: "a1", status: "running" })];
+
+      const result = computeFinalizedAgents(undefined, currentAgents);
+
+      // All agents are filtered out since none match existing IDs (empty set)
+      expect(result).toBeDefined();
+      expect(result!.length).toBe(0);
+    });
+  });
+
+  describe("Agent finalization", () => {
+    test("finalizes running foreground agents to completed", () => {
+      const agents = [createAgent({ id: "a1", status: "running" })];
+      const result = computeFinalizedAgents(agents, agents);
+
+      expect(result).toBeDefined();
+      expect(result![0]!.status).toBe("completed");
+      expect(result![0]!.currentTool).toBeUndefined();
+      expect(result![0]!.durationMs).toBeGreaterThan(0);
+    });
+
+    test("finalizes pending foreground agents to completed", () => {
+      const agents = [createAgent({ id: "a1", status: "pending" })];
+      const result = computeFinalizedAgents(agents, agents);
+
+      expect(result).toBeDefined();
+      expect(result![0]!.status).toBe("completed");
+    });
+
+    test("preserves already-completed agents", () => {
+      const agents = [
+        createAgent({ id: "a1", status: "completed", durationMs: 1234 }),
+      ];
+      const result = computeFinalizedAgents(agents, agents);
+
+      expect(result).toBeDefined();
+      expect(result![0]!.status).toBe("completed");
+      expect(result![0]!.durationMs).toBe(1234);
+    });
+
+    test("preserves error agents", () => {
+      const agents = [createAgent({ id: "a1", status: "error" })];
+      const result = computeFinalizedAgents(agents, agents);
+
+      expect(result).toBeDefined();
+      expect(result![0]!.status).toBe("error");
+    });
+
+    test("does NOT finalize background agents", () => {
+      const agents = [
+        createAgent({ id: "bg1", status: "running", background: true }),
+      ];
+      const result = computeFinalizedAgents(agents, agents);
+
+      expect(result).toBeDefined();
+      expect(result![0]!.status).toBe("running"); // Still running
+      expect(result![0]!.background).toBe(true);
+    });
+
+    test("mixed: finalizes foreground, preserves background", () => {
+      const agents = [
+        createAgent({ id: "fg1", status: "running", background: false }),
+        createAgent({ id: "bg1", status: "running", background: true }),
+      ];
+      const result = computeFinalizedAgents(agents, agents);
+
+      expect(result).toBeDefined();
+      expect(result!.length).toBe(2);
+      expect(result!.find((a) => a.id === "fg1")!.status).toBe("completed");
+      expect(result!.find((a) => a.id === "bg1")!.status).toBe("running");
+    });
+  });
+
+  describe("Background agent remaining computation", () => {
+    test("returns only active background agents", () => {
+      const agents = [
+        createAgent({ id: "fg1", status: "completed", background: false }),
+        createAgent({ id: "bg1", status: "running", background: true }),
+        createAgent({ id: "bg2", status: "completed", background: true }),
+      ];
+
+      const remaining = getActiveBackgroundAgents(agents);
+
+      expect(remaining.length).toBe(1);
+      expect(remaining[0]!.id).toBe("bg1");
+    });
+
+    test("returns empty when no background agents exist", () => {
+      const agents = [
+        createAgent({ id: "fg1", status: "completed", background: false }),
+      ];
+
+      const remaining = getActiveBackgroundAgents(agents);
+      expect(remaining.length).toBe(0);
+    });
+
+    test("returns empty when all background agents are completed", () => {
+      const agents = [
+        createAgent({ id: "bg1", status: "completed", background: true }),
+        createAgent({ id: "bg2", status: "error", background: true }),
+      ];
+
+      const remaining = getActiveBackgroundAgents(agents);
+      expect(remaining.length).toBe(0);
+    });
+  });
+
+  describe("Consolidated updater equivalence", () => {
+    test("single-pass updater produces same agent filtering as nested approach", () => {
+      // Simulates the previous nested approach vs the consolidated one
+      const messageAgents = [
+        createAgent({ id: "a1" }),
+        createAgent({ id: "a2" }),
+      ];
+      const currentAgents = [
+        createAgent({ id: "a1", status: "running" }),
+        createAgent({ id: "a2", status: "pending" }),
+        createAgent({ id: "orphan", status: "running" }),
+      ];
+
+      // Old nested approach: read IDs in no-op updater, then use them
+      const existingIdsNested = new Set<string>();
+      for (const agent of messageAgents) {
+        existingIdsNested.add(agent.id);
+      }
+      const filteredNested = currentAgents.filter((a) =>
+        existingIdsNested.has(a.id),
+      );
+
+      // New consolidated approach: read IDs + filter in same updater
+      const result = computeFinalizedAgents(messageAgents, currentAgents);
+
+      // Both should filter out orphans identically
+      expect(result!.map((a) => a.id)).toEqual(
+        filteredNested.map((a) => a.id),
+      );
+    });
+
+    test("remaining background agents are computed from currentAgents (ref), not stale state", () => {
+      // Key: the consolidated approach reads from parallelAgentsRef.current
+      // (via currentAgents) and computes remaining synchronously BEFORE
+      // any state update. This guarantees stopSharedStreamState gets the
+      // correct value.
+      const currentAgents = [
+        createAgent({ id: "fg1", status: "completed", background: false }),
+        createAgent({ id: "bg1", status: "running", background: true }),
+      ];
+
+      const remaining = getActiveBackgroundAgents(currentAgents);
+      const hasRemainingBg = remaining.length > 0;
+
+      expect(hasRemainingBg).toBe(true);
+      expect(remaining.length).toBe(1);
+      expect(remaining[0]!.id).toBe("bg1");
+    });
+
+    test("hasRemainingBg is false when no background agents remain", () => {
+      const currentAgents = [
+        createAgent({ id: "fg1", status: "completed", background: false }),
+        createAgent({ id: "fg2", status: "running", background: false }),
+      ];
+
+      const remaining = getActiveBackgroundAgents(currentAgents);
+      const hasRemainingBg = remaining.length > 0;
+
+      expect(hasRemainingBg).toBe(false);
+    });
+  });
+
+  describe("Message finalization state", () => {
+    test("finalizeStreamingReasoningInMessage preserves message identity", () => {
+      const msg = createMessage({
+        id: "msg-1",
+        content: "test",
+        parts: [],
+      });
+
+      const result = finalizeStreamingReasoningInMessage(msg);
+
+      expect(result.id).toBe("msg-1");
+      expect(result.content).toBe("test");
+    });
+
+    test("combined agent filtering and message update operates on same prev state", () => {
+      // Simulates the single-updater pattern where we read agent IDs
+      // AND update the message from the same `prev` array
+      const messageId = "msg-1";
+      const bakedAgents = [
+        createAgent({ id: "a1" }),
+        createAgent({ id: "a2" }),
+      ];
+      const currentAgents = [
+        createAgent({ id: "a1", status: "running" }),
+        createAgent({ id: "a2", status: "running" }),
+        createAgent({ id: "orphan", status: "running" }),
+      ];
+
+      const messages = [
+        createMessage({
+          id: messageId,
+          parallelAgents: bakedAgents,
+          streaming: true,
+        }),
+        createMessage({ id: "msg-other", content: "other" }),
+      ];
+
+      // Simulate the single-updater logic
+      const updatedMessages = (() => {
+        const existingAgentIds = new Set<string>();
+        const targetMsg = messages.find((m) => m.id === messageId);
+        if (targetMsg?.parallelAgents) {
+          for (const agent of targetMsg.parallelAgents) {
+            existingAgentIds.add(agent.id);
+          }
+        }
+
+        const finalizedAgents =
+          currentAgents.length > 0
+            ? currentAgents
+                .filter((a) => existingAgentIds.has(a.id))
+                .map((a) => {
+                  if (a.background) return a;
+                  return a.status === "running" || a.status === "pending"
+                    ? {
+                        ...a,
+                        status: "completed" as const,
+                        currentTool: undefined,
+                        durationMs:
+                          Date.now() - new Date(a.startedAt).getTime(),
+                      }
+                    : a;
+                })
+            : undefined;
+
+        return messages.map((msg) =>
+          msg.id === messageId
+            ? {
+                ...msg,
+                streaming: false,
+                parallelAgents: finalizedAgents,
+              }
+            : msg,
+        );
+      })();
+
+      // Verify the target message was updated correctly
+      const finalMsg = updatedMessages.find((m) => m.id === messageId);
+      expect(finalMsg).toBeDefined();
+      expect(finalMsg!.streaming).toBe(false);
+      expect(finalMsg!.parallelAgents).toBeDefined();
+      expect(finalMsg!.parallelAgents!.length).toBe(2); // orphan filtered out
+      expect(finalMsg!.parallelAgents!.every((a: ParallelAgent) => a.status === "completed")).toBe(true);
+
+      // Verify the other message was NOT modified
+      const otherMsg = updatedMessages.find((m) => m.id === "msg-other");
+      expect(otherMsg).toBeDefined();
+      expect(otherMsg!.content).toBe("other");
+    });
+
+    test("background updates insert after anchor message", () => {
+      const start = createMessage({
+        id: "start",
+        content: "Starting workflow",
+        streaming: true,
+      });
+      const bg1 = createMessage({
+        id: "bg1",
+        content: "Background update 1",
+        streaming: false,
+      });
+      const refs = {
+        backgroundAgentMessageId: null as string | null,
+        streamingMessageId: "start",
+        lastStreamedMessageId: null as string | null,
+      };
+
+      const result = appendBackgroundMessageInOrder([start], bg1, refs);
+
+      expect(result.map((m) => m.id)).toEqual(["start", "bg1"]);
+      expect(refs.backgroundAgentMessageId).toBe("bg1");
+    });
+
+    test("background updates chain in chronological order", () => {
+      const start = createMessage({
+        id: "start",
+        content: "Starting workflow",
+        streaming: true,
+      });
+      const bg1 = createMessage({
+        id: "bg1",
+        content: "Background update 1",
+        streaming: false,
+      });
+      const bg2 = createMessage({
+        id: "bg2",
+        content: "Background update 2",
+        streaming: false,
+      });
+      const refs = {
+        backgroundAgentMessageId: null as string | null,
+        streamingMessageId: "start",
+        lastStreamedMessageId: null as string | null,
+      };
+
+      const afterBg1 = appendBackgroundMessageInOrder([start], bg1, refs);
+      const afterBg2 = appendBackgroundMessageInOrder(afterBg1, bg2, refs);
+
+      expect(afterBg2.map((m) => m.id)).toEqual(["start", "bg1", "bg2"]);
+      expect(refs.backgroundAgentMessageId).toBe("bg2");
+    });
+
+    test("finalizes the active streaming message even when it is not last", () => {
+      const start = createMessage({
+        id: "start",
+        content: "Starting workflow",
+        streaming: true,
+      });
+      const bg1 = createMessage({
+        id: "bg1",
+        content: "Background update 1",
+        streaming: false,
+      });
+
+      const result = finalizeActiveStreamingMessage([start, bg1], "start");
+
+      expect(result.map((m) => m.id)).toEqual(["start", "bg1"]);
+      expect(result[0]!.streaming).toBe(false);
+      expect(result[1]!.streaming).toBe(false);
+      expect(result[1]!.content).toBe("Background update 1");
+    });
+  });
+});
diff --git a/src/ui/chat.cross-provider-contract.e2e.test.ts b/src/ui/chat.cross-provider-contract.e2e.test.ts
new file mode 100644
index 0000000000..ade6116c78
--- /dev/null
+++ b/src/ui/chat.cross-provider-contract.e2e.test.ts
@@ -0,0 +1,151 @@
+import { describe, expect, test } from "bun:test";
+import type { AgentType } from "../models";
+import {
+  buildAgentContinuationPayload,
+  getAgentContinuationContractViolation,
+  getAutoCompactionIndicatorState,
+  mergeAgentTaskLabel,
+  shouldFinalizeAgentOnlyStream,
+} from "./chat.tsx";
+import type { ParallelAgent } from "./components/parallel-agents-tree.tsx";
+import {
+  createAgentLifecycleLedger,
+  registerAgentLifecycleComplete,
+  registerAgentLifecycleStart,
+  registerAgentLifecycleUpdate,
+} from "./utils/agent-lifecycle-ledger.ts";
+
+const PROVIDERS: AgentType[] = ["claude", "opencode", "copilot"];
+
+function createAgent(overrides: Partial<ParallelAgent> = {}): ParallelAgent {
+  return {
+    id: overrides.id ?? "agent-1",
+    name: overrides.name ?? "worker",
+    task: overrides.task ?? "Investigate auth guard ordering",
+    status: overrides.status ?? "completed",
+    startedAt: overrides.startedAt ?? new Date(1000000000000).toISOString(),
+    background: overrides.background,
+    result: overrides.result,
+    error: overrides.error,
+  };
+}
+
+interface ProviderFixture {
+  firstTask: string | undefined;
+  secondTask: string | undefined;
+}
+
+const SUCCESS_FIXTURES: Record<AgentType, ProviderFixture> = {
+  claude: {
+    firstTask: "Investigate auth guard ordering",
+    secondTask: "sub-agent task",
+  },
+  opencode: {
+    firstTask: "sub-agent task",
+    secondTask: "Investigate auth guard ordering",
+  },
+  copilot: {
+    firstTask: "subagent task",
+    secondTask: "Investigate auth guard ordering",
+  },
+};
+
+function runProviderTurn(fixture: ProviderFixture) {
+  const ledger = createAgentLifecycleLedger();
+  const started = registerAgentLifecycleStart(ledger, "agent-e2e-1");
+  const updated = registerAgentLifecycleUpdate(ledger, "agent-e2e-1");
+  const completed = registerAgentLifecycleComplete(ledger, "agent-e2e-1");
+
+  const mergedInitialTask = mergeAgentTaskLabel(undefined, fixture.firstTask, "general-purpose");
+  const finalTask = mergeAgentTaskLabel(mergedInitialTask, fixture.secondTask, "general-purpose");
+
+  const continuationPayload = buildAgentContinuationPayload({
+    agents: [createAgent({ id: "fg-1", task: finalTask, result: "Auth guard analysis complete" })],
+  });
+  const continuationViolation = getAgentContinuationContractViolation({
+    isAgentOnlyStream: true,
+    continuationPayload,
+  });
+
+  const shouldFinalize = shouldFinalizeAgentOnlyStream({
+    hasStreamingMessage: true,
+    isStreaming: true,
+    isAgentOnlyStream: true,
+    liveAgentCount: 1,
+    messageAgentCount: 0,
+  });
+
+  return {
+    started,
+    updated,
+    completed,
+    ledgerEntry: ledger.get("agent-e2e-1"),
+    finalTask,
+    continuationPayload,
+    continuationViolation,
+    shouldFinalize,
+    compactionStart: getAutoCompactionIndicatorState("start"),
+    compactionComplete: getAutoCompactionIndicatorState("complete", true),
+  };
+}
+
+describe("chat strict contract cross-provider e2e parity", () => {
+  test.each(PROVIDERS)(
+    "provider %s: successful agent-only turn preserves strict lifecycle and continuation parity",
+    (provider) => {
+      const result = runProviderTurn(SUCCESS_FIXTURES[provider]);
+
+      expect(result.started.ok).toBe(true);
+      expect(result.updated.ok).toBe(true);
+      expect(result.completed.ok).toBe(true);
+      expect(result.ledgerEntry).toEqual({
+        started: true,
+        completed: true,
+        sequence: 3,
+      });
+      expect(result.finalTask).toBe("Investigate auth guard ordering");
+      expect(result.continuationPayload).toBe(
+        '[Sub-agent results]\n\nSub-agent "worker" result:\n\nAuth guard analysis complete',
+      );
+      expect(result.continuationViolation).toBeNull();
+      expect(result.shouldFinalize).toBe(true);
+      expect(result.compactionStart).toEqual({ status: "running" });
+      expect(result.compactionComplete).toEqual({ status: "completed" });
+    },
+  );
+
+  test.each(PROVIDERS)(
+    "provider %s: missing continuation input terminates agent-only turn with parity-stable contract error",
+    (provider) => {
+      const _providerContext = provider;
+      const continuationPayload = buildAgentContinuationPayload({
+        agents: [
+          createAgent({
+            id: "bg-1",
+            background: true,
+            result: "background only",
+          }),
+        ],
+        fallbackText: "   ",
+      });
+      const continuationViolation = getAgentContinuationContractViolation({
+        isAgentOnlyStream: true,
+        continuationPayload,
+      });
+      const compactionError = getAutoCompactionIndicatorState(
+        "complete",
+        false,
+        "compaction failed while finalizing",
+      );
+
+      expect(continuationPayload).toBeNull();
+      expect(continuationViolation).toBe(
+        "Contract violation (INV-OUTPUT-001): missing @agent continuation input; turn terminated.",
+      );
+      expect(compactionError).toEqual({
+        status: "error",
+        errorMessage: "compaction failed while finalizing",
+      });
+    },
+  );
+});
diff --git a/src/ui/chat.cross-provider-contract.integration.test.ts b/src/ui/chat.cross-provider-contract.integration.test.ts
new file mode 100644
index 0000000000..7ea37d7309
--- /dev/null
+++ b/src/ui/chat.cross-provider-contract.integration.test.ts
@@ -0,0 +1,196 @@
+import { beforeEach, describe, expect, test } from "bun:test";
+import type { AgentType } from "../models";
+import {
+  buildAgentContinuationPayload,
+  emitAgentLifecycleContractObservability,
+  emitAgentMainContinuationObservability,
+  emitContractFailureTerminationObservability,
+  getAgentContinuationContractViolation,
+  getAutoCompactionIndicatorState,
+  mergeAgentTaskLabel,
+} from "./chat.tsx";
+import type { ParallelAgent } from "./components/parallel-agents-tree.tsx";
+import {
+  createAgentLifecycleLedger,
+  registerAgentLifecycleComplete,
+  registerAgentLifecycleStart,
+  registerAgentLifecycleUpdate,
+} from "./utils/agent-lifecycle-ledger.ts";
+import {
+  getRuntimeParityMetricsSnapshot,
+  resetRuntimeParityMetrics,
+} from "../workflows/runtime-parity-observability.ts";
+
+const PROVIDERS: AgentType[] = ["claude", "opencode", "copilot"];
+
+function createAgent(overrides: Partial<ParallelAgent> = {}): ParallelAgent {
+  return {
+    id: overrides.id ?? "agent-1",
+    name: overrides.name ?? "worker",
+    task: overrides.task ?? "Analyze auth retries",
+    status: overrides.status ?? "completed",
+    startedAt: overrides.startedAt ?? new Date(1000000000000).toISOString(),
+    background: overrides.background,
+    result: overrides.result,
+    error: overrides.error,
+  };
+}
+
+function runStrictContractFlow(provider: AgentType) {
+  const ledger = createAgentLifecycleLedger();
+  const started = registerAgentLifecycleStart(ledger, "agent-1");
+  const updated = registerAgentLifecycleUpdate(ledger, "agent-1");
+  const completed = registerAgentLifecycleComplete(ledger, "agent-1");
+  const invalidUpdate = registerAgentLifecycleUpdate(ledger, "agent-1");
+
+  if (!invalidUpdate.ok) {
+    emitAgentLifecycleContractObservability({
+      provider,
+      runId: 14,
+      code: invalidUpdate.code,
+      eventType: "stream.agent.update",
+      agentId: "agent-1",
+    });
+  }
+
+  const canonicalLabel = mergeAgentTaskLabel(
+    "sub-agent task",
+    "Analyze auth retries",
+    "general-purpose",
+  );
+  const preservedLabel = mergeAgentTaskLabel(canonicalLabel, "sub-agent task", "general-purpose");
+
+  const continuationPayload = buildAgentContinuationPayload({
+    agents: [
+      createAgent({ id: "fg-1", name: "worker", result: "Completed auth investigation" }),
+      createAgent({ id: "bg-1", name: "bg-worker", background: true, result: "ignore" }),
+    ],
+  });
+  emitAgentMainContinuationObservability({
+    provider,
+    runId: 14,
+    result: continuationPayload ? "forwarded" : "missing",
+  });
+
+  const missingContinuation = getAgentContinuationContractViolation({
+    isAgentOnlyStream: true,
+    continuationPayload: null,
+  });
+  if (missingContinuation) {
+    emitAgentMainContinuationObservability({
+      provider,
+      runId: 14,
+      result: "missing",
+    });
+    emitContractFailureTerminationObservability({
+      provider,
+      runId: 14,
+      reason: "missing_agent_continuation",
+      errorMessage: missingContinuation,
+    });
+  }
+
+  const compactionStart = getAutoCompactionIndicatorState("start");
+  const compactionSuccess = getAutoCompactionIndicatorState("complete", true);
+  const compactionError = getAutoCompactionIndicatorState("complete", false, "token budget exhausted");
+  if (compactionError.status === "error") {
+    emitContractFailureTerminationObservability({
+      provider,
+      runId: 14,
+      reason: "compaction_terminal_error",
+      errorMessage: compactionError.errorMessage ?? "compaction failed",
+    });
+  }
+
+  return {
+    started,
+    updated,
+    completed,
+    invalidUpdate,
+    ledgerEntry: ledger.get("agent-1"),
+    preservedLabel,
+    continuationPayload,
+    missingContinuation,
+    compactionStart,
+    compactionSuccess,
+    compactionError,
+  };
+}
+
+describe("chat strict contract cross-provider integration parity", () => {
+  beforeEach(() => {
+    resetRuntimeParityMetrics();
+  });
+
+  test("lifecycle, labels, continuation, and compaction remain parity-stable", () => {
+    const results = PROVIDERS.map((provider) => runStrictContractFlow(provider));
+    const baseline = results[0];
+    expect(baseline).toBeDefined();
+    if (!baseline) {
+      return;
+    }
+
+    for (const result of results.slice(1)) {
+      expect(result).toEqual(baseline);
+    }
+
+    expect(baseline.started.ok).toBe(true);
+    expect(baseline.updated.ok).toBe(true);
+    expect(baseline.completed.ok).toBe(true);
+    expect(baseline.invalidUpdate).toEqual({ ok: false, code: "OUT_OF_ORDER_EVENT" });
+    expect(baseline.ledgerEntry).toEqual({
+      started: true,
+      completed: true,
+      sequence: 3,
+    });
+
+    expect(baseline.preservedLabel).toBe("Analyze auth retries");
+    expect(baseline.continuationPayload).toBe(
+      '[Sub-agent results]\n\nSub-agent "worker" result:\n\nCompleted auth investigation',
+    );
+    expect(baseline.missingContinuation).toBe(
+      "Contract violation (INV-OUTPUT-001): missing @agent continuation input; turn terminated.",
+    );
+
+    expect(baseline.compactionStart).toEqual({ status: "running" });
+    expect(baseline.compactionSuccess).toEqual({ status: "completed" });
+    expect(baseline.compactionError).toEqual({
+      status: "error",
+      errorMessage: "token budget exhausted",
+    });
+
+    const metrics = getRuntimeParityMetricsSnapshot();
+    for (const provider of PROVIDERS) {
+      expect(
+        metrics.counters[
+          `workflow.runtime.parity.agent_lifecycle_contract_violation_total{code=OUT_OF_ORDER_EVENT,eventType=stream.agent.update,provider=${provider}}`
+        ],
+      ).toBe(1);
+      expect(
+        metrics.counters[
+          `workflow.runtime.parity.agent_event_out_of_order_total{code=OUT_OF_ORDER_EVENT,eventType=stream.agent.update,provider=${provider}}`
+        ],
+      ).toBe(1);
+      expect(
+        metrics.counters[
+          `workflow.runtime.parity.agent_result_main_continuation_total{provider=${provider},result=forwarded}`
+        ],
+      ).toBe(1);
+      expect(
+        metrics.counters[
+          `workflow.runtime.parity.agent_result_main_continuation_total{provider=${provider},result=missing}`
+        ],
+      ).toBe(1);
+      expect(
+        metrics.counters[
+          `workflow.runtime.parity.turn_terminated_due_to_contract_error_total{provider=${provider},reason=missing_agent_continuation}`
+        ],
+      ).toBe(1);
+      expect(
+        metrics.counters[
+          `workflow.runtime.parity.turn_terminated_due_to_contract_error_total{provider=${provider},reason=compaction_terminal_error}`
+        ],
+      ).toBe(1);
+    }
+  });
+});
diff --git a/src/ui/chat.loading-state.test.ts b/src/ui/chat.loading-state.test.ts
index 974a2b0060..c67ee0331a 100644
--- a/src/ui/chat.loading-state.test.ts
+++ b/src/ui/chat.loading-state.test.ts
@@ -88,6 +88,22 @@ describe("shouldShowMessageLoadingIndicator", () => {
     ).toBe(true);
   });
 
+  test("stops loading indicator once stream transitions to a terminal error state", () => {
+    expect(
+      shouldShowMessageLoadingIndicator({
+        streaming: true,
+        taskItems: [{ status: "in_progress" }],
+      }),
+    ).toBe(true);
+
+    expect(
+      shouldShowMessageLoadingIndicator({
+        streaming: false,
+        taskItems: [{ status: "error" }],
+      }),
+    ).toBe(false);
+  });
+
   test("stops loading indicator for completed subagent/background snapshots", () => {
     expect(
       shouldShowMessageLoadingIndicator({
@@ -236,3 +252,4 @@ describe("hasLiveLoadingIndicator", () => {
     ).toBe(false);
   });
 });
+
diff --git a/src/ui/chat.runtime-envelope-routing.test.ts b/src/ui/chat.runtime-envelope-routing.test.ts
new file mode 100644
index 0000000000..132b2742e5
--- /dev/null
+++ b/src/ui/chat.runtime-envelope-routing.test.ts
@@ -0,0 +1,61 @@
+import { describe, expect, test } from "bun:test";
+import { isRuntimeEnvelopePartEvent } from "./chat.tsx";
+import type { StreamPartEvent } from "./parts/index.ts";
+
+describe("isRuntimeEnvelopePartEvent", () => {
+  test("returns true for workflow runtime envelope events", () => {
+    const runtimeEvents: StreamPartEvent[] = [
+      {
+        type: "task-list-update",
+        tasks: [
+          { id: "#1", title: "Wire runtime envelopes", status: "in_progress" },
+        ],
+      },
+      {
+        type: "workflow-step-start",
+        workflowId: "wf-1",
+        nodeId: "planner",
+        nodeName: "Planner",
+      },
+      {
+        type: "workflow-step-complete",
+        workflowId: "wf-1",
+        nodeId: "planner",
+        status: "success",
+      },
+      {
+        type: "task-result-upsert",
+        envelope: {
+          task_id: "#1",
+          tool_name: "task",
+          title: "Wire runtime envelopes",
+          status: "completed",
+          output_text: "Done",
+        },
+      },
+    ];
+
+    for (const event of runtimeEvents) {
+      expect(isRuntimeEnvelopePartEvent(event)).toBe(true);
+    }
+  });
+
+  test("returns false for non-envelope stream events", () => {
+    const nonEnvelopeEvents: StreamPartEvent[] = [
+      { type: "text-delta", delta: "hello" },
+      { type: "tool-start", toolId: "tool-1", toolName: "Read", input: {} },
+      {
+        type: "thinking-meta",
+        thinkingSourceKey: "source-1",
+        targetMessageId: "msg-1",
+        streamGeneration: 1,
+        thinkingText: "analysis",
+        thinkingMs: 120,
+      },
+    ];
+
+    for (const event of nonEnvelopeEvents) {
+      expect(isRuntimeEnvelopePartEvent(event)).toBe(false);
+    }
+  });
+});
diff --git a/src/ui/chat.send-silent-message.integration.test.ts b/src/ui/chat.send-silent-message.integration.test.ts
new file mode 100644
index 0000000000..ad58fd75eb
--- /dev/null
+++ b/src/ui/chat.send-silent-message.integration.test.ts
@@ -0,0 +1,43 @@
+import { describe, expect, test } from "bun:test";
+import {
+  createMessage,
+  reconcilePreviousStreamingPlaceholder,
+  type ChatMessage,
+} from "./chat.tsx";
+
+function simulateSendSilentMessageStart(
+  messages: ChatMessage[],
+  previousStreamingId: string | null,
+): ChatMessage[] {
+  const reconciled = reconcilePreviousStreamingPlaceholder(messages, previousStreamingId);
+  return [...reconciled, createMessage("assistant", "", true)];
+}
+
+describe("sendSilentMessage integration", () => {
+  test("creates exactly one assistant message for a fresh silent stream", () => {
+    const userMessage = createMessage("user", "@worker do the thing");
+
+    const next = simulateSendSilentMessageStart([userMessage], null);
+    const assistantMessages = next.filter((message) => message.role === "assistant");
+
+    expect(next).toHaveLength(2);
+    expect(assistantMessages).toHaveLength(1);
+    expect(assistantMessages[0]?.streaming).toBe(true);
+  });
+
+  test("replaces an empty streaming placeholder instead of creating duplicates", () => {
+    const userMessage = createMessage("user", "@worker do the thing");
+    const stalePlaceholder = createMessage("assistant", "", true);
+
+    const next = simulateSendSilentMessageStart(
+      [userMessage, stalePlaceholder],
+      stalePlaceholder.id,
+    );
+    const assistantMessages = next.filter((message) => message.role === "assistant");
+
+    expect(next).toHaveLength(2);
+    expect(assistantMessages).toHaveLength(1);
+    expect(assistantMessages[0]?.id).not.toBe(stalePlaceholder.id);
+    expect(assistantMessages[0]?.streaming).toBe(true);
+  });
+});
diff --git a/src/ui/chat.session-idle-flush.test.ts b/src/ui/chat.session-idle-flush.test.ts
new file mode 100644
index 0000000000..b2fd4b97db
--- /dev/null
+++ b/src/ui/chat.session-idle-flush.test.ts
@@ -0,0 +1,208 @@
+/**
+ * Tests for stream.session.idle handler flush ordering in chat.tsx
+ *
+ * Validates that the batch dispatcher is flushed BEFORE
+ * shouldContinueParentSessionLoop checks hasRunningBlockingTool.
+ *
+ * Without this flush, Claude sessions (which do not emit stream.turn.end)
+ * can have stale tool-tracking state when session.idle fires, causing
+ * the continuation check to block queue processing indefinitely.
+ *
+ * OpenCode / Copilot avoid this because stream.turn.end already triggers
+ * a dispatcher flush before session.idle arrives.
+ */
+
+import { describe, expect, test, mock, beforeEach } from "bun:test";
+import { shouldContinueParentSessionLoop } from "./utils/stream-continuation.ts";
+
+// ---------------------------------------------------------------------------
+// Handler logic extracted from chat.tsx session.idle handler
+// ---------------------------------------------------------------------------
+
+interface SessionIdleState {
+  isStreamingRef: { current: boolean };
+  hasRunningToolRef: { current: boolean };
+  lastTurnFinishReasonRef: { current: string | null };
+  parallelAgentsRef: { current: unknown[] };
+  batchDispatcher: { flush: () => void };
+  handleStreamComplete: () => void;
+  hasPendingTaskResultContract: () => boolean;
+}
+
+/**
+ * Mirrors the stream.session.idle handler in chat.tsx (POST-FIX).
+ *
+ * The key invariant is: batchDispatcher.flush() runs BEFORE
+ * shouldContinueParentSessionLoop reads hasRunningToolRef.
+ */
+function handleSessionIdle(state: SessionIdleState): void {
+  if (state.isStreamingRef.current) {
+    // Critical: flush before checking tool state
+    state.batchDispatcher.flush();
+
+    const continuationSignal = shouldContinueParentSessionLoop({
+      finishReason: (state.lastTurnFinishReasonRef.current ?? undefined) as
+        | "tool-calls" | "stop" | "max-tokens" | "max-turns" | "error" | "unknown"
+        | undefined,
+      hasActiveForegroundAgents: state.parallelAgentsRef.current.length > 0,
+      hasRunningBlockingTool: state.hasRunningToolRef.current,
+      hasPendingTaskContract: state.hasPendingTaskResultContract(),
+    });
+
+    if (continuationSignal.shouldContinue) {
+      return;
+    }
+
+    state.handleStreamComplete();
+  }
+}
+
+/**
+ * The BROKEN version (pre-fix) where flush happens AFTER the check.
+ */
+function handleSessionIdleBroken(state: SessionIdleState): void {
+  if (state.isStreamingRef.current) {
+    const continuationSignal = shouldContinueParentSessionLoop({
+      finishReason: (state.lastTurnFinishReasonRef.current ?? undefined) as
+        | "tool-calls" | "stop" | "max-tokens" | "max-turns" | "error" | "unknown"
+        | undefined,
+      hasActiveForegroundAgents: state.parallelAgentsRef.current.length > 0,
+      hasRunningBlockingTool: state.hasRunningToolRef.current,
+      hasPendingTaskContract: state.hasPendingTaskResultContract(),
+    });
+
+    if (continuationSignal.shouldContinue) {
+      return;
+    }
+
+    state.batchDispatcher.flush();
+    state.handleStreamComplete();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("stream.session.idle handler", () => {
+  let state: SessionIdleState;
+  let flushFn: ReturnType<typeof mock>;
+  let completeFn: ReturnType<typeof mock>;
+
+  beforeEach(() => {
+    flushFn = mock(() => {
+      // Simulate the dispatcher flush processing a pending tool.complete
+      // event, which sets hasRunningToolRef.current = false.
+      state.hasRunningToolRef.current = false;
+    });
+    completeFn = mock();
+
+    state = {
+      isStreamingRef: { current: true },
+      hasRunningToolRef: { current: true }, // Stale: tool.complete pending in dispatcher
+      lastTurnFinishReasonRef: { current: null }, // Claude doesn't emit turn.end
+      parallelAgentsRef: { current: [] },
+      batchDispatcher: { flush: flushFn },
+      handleStreamComplete: completeFn,
+      hasPendingTaskResultContract: () => false,
+    };
+  });
+
+  describe("Claude queue dispatch (no turn.end events)", () => {
+    test("fixed: flushes dispatcher before continuation check, allowing queue dispatch", () => {
+      handleSessionIdle(state);
+
+      // Flush should have been called
+      expect(flushFn).toHaveBeenCalledTimes(1);
+
+      // After flush, hasRunningToolRef became false, so handleStreamComplete is called
+      expect(completeFn).toHaveBeenCalledTimes(1);
+    });
+
+    test("broken: stale tool state blocks queue dispatch when flush is too late", () => {
+      handleSessionIdleBroken(state);
+
+      // Flush was NOT called because shouldContinueParentSessionLoop returned early
+      expect(flushFn).toHaveBeenCalledTimes(0);
+
+      // handleStreamComplete was never reached
+      expect(completeFn).toHaveBeenCalledTimes(0);
+    });
+  });
+
+  describe("normal completion (no pending tools)", () => {
+    test("calls handleStreamComplete when no blocking conditions", () => {
+      state.hasRunningToolRef.current = false; // No pending tools
+
+      handleSessionIdle(state);
+
+      expect(flushFn).toHaveBeenCalledTimes(1);
+      expect(completeFn).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe("active foreground agents block completion", () => {
+    test("returns early when foreground agents are active (even after flush)", () => {
+      state.hasRunningToolRef.current = false;
+      state.parallelAgentsRef.current = [{ id: "agent-1" }];
+
+      handleSessionIdle(state);
+
+      expect(flushFn).toHaveBeenCalledTimes(1);
+      expect(completeFn).toHaveBeenCalledTimes(0);
+    });
+  });
+
+  describe("pending task contract blocks completion", () => {
+    test("returns early when task contract is pending (even after flush)", () => {
+      state.hasRunningToolRef.current = false;
+      state.hasPendingTaskResultContract = () => true;
+
+      handleSessionIdle(state);
+
+      expect(flushFn).toHaveBeenCalledTimes(1);
+      expect(completeFn).toHaveBeenCalledTimes(0);
+    });
+  });
+
+  describe("not streaming", () => {
+    test("does nothing when not streaming", () => {
+      state.isStreamingRef.current = false;
+
+      handleSessionIdle(state);
+
+      expect(flushFn).toHaveBeenCalledTimes(0);
+      expect(completeFn).toHaveBeenCalledTimes(0);
+    });
+  });
+
+  describe("finish reason blocking", () => {
+    test("continues loop when finish reason is tool-calls (even after flush clears tools)", () => {
+      state.lastTurnFinishReasonRef.current = "tool-calls";
+
+      handleSessionIdle(state);
+
+      expect(flushFn).toHaveBeenCalledTimes(1);
+      // shouldContinue: true due to finish reason, not tools
+      expect(completeFn).toHaveBeenCalledTimes(0);
+    });
+
+    test("continues loop when finish reason is unknown (even after flush clears tools)", () => {
+      state.lastTurnFinishReasonRef.current = "unknown";
+
+      handleSessionIdle(state);
+
+      expect(flushFn).toHaveBeenCalledTimes(1);
+      expect(completeFn).toHaveBeenCalledTimes(0);
+    });
+
+    test("completes when finish reason is stop", () => {
+      state.lastTurnFinishReasonRef.current = "stop";
+
+      handleSessionIdle(state);
+
+      expect(flushFn).toHaveBeenCalledTimes(1);
+      expect(completeFn).toHaveBeenCalledTimes(1);
+    });
+  });
+});
diff --git a/src/ui/chat.session-notifications.test.ts b/src/ui/chat.session-notifications.test.ts
new file mode 100644
index 0000000000..2f84228d25
--- /dev/null
+++ b/src/ui/chat.session-notifications.test.ts
@@ -0,0 +1,37 @@
+import { describe, expect, test } from "bun:test";
+import {
+  formatSessionTruncationMessage,
+  getAutoCompactionIndicatorState,
+} from "./chat.tsx";
+
+describe("chat session notification helpers", () => {
+  test("formats truncation message with singular/plural message count", () => {
+    expect(formatSessionTruncationMessage(42, 1)).toContain(
+      "42 tokens removed (1 message)",
+    );
+    expect(formatSessionTruncationMessage(42, 2)).toContain(
+      "42 tokens removed (2 messages)",
+    );
+  });
+
+  test("maps compaction start to running indicator", () => {
+    expect(getAutoCompactionIndicatorState("start")).toEqual({
+      status: "running",
+    });
+  });
+
+  test("maps compaction complete to completed indicator by default", () => {
+    expect(getAutoCompactionIndicatorState("complete")).toEqual({
+      status: "completed",
+    });
+  });
+
+  test("maps compaction failure to error indicator with trimmed message", () => {
+    expect(
+      getAutoCompactionIndicatorState("complete", false, " summarize failed "),
+    ).toEqual({
+      status: "error",
+      errorMessage: "summarize failed",
+    });
+  });
+});
diff --git a/src/ui/chat.stream-lifecycle-run-guard.test.ts b/src/ui/chat.stream-lifecycle-run-guard.test.ts
new file mode 100644
index 0000000000..d5b4a4ce4c
--- /dev/null
+++ b/src/ui/chat.stream-lifecycle-run-guard.test.ts
@@ -0,0 +1,241 @@
+import { beforeEach, describe, expect, spyOn, test } from "bun:test";
+import {
+  buildAgentContinuationPayload,
+  emitAgentLifecycleContractObservability,
+  emitAgentMainContinuationObservability,
+  emitContractFailureTerminationObservability,
+  getAgentContinuationContractViolation,
+  shouldFinalizeAgentOnlyStream,
+  shouldProcessStreamLifecycleEvent,
+} from "./chat.tsx";
+import type { ParallelAgent } from "./components/parallel-agents-tree.tsx";
+import {
+  getRuntimeParityMetricsSnapshot,
+  resetRuntimeParityMetrics,
+} from "../workflows/runtime-parity-observability.ts";
+
+function shouldFinalizeOnIdle(args: {
+  activeRunId: number | null;
+  eventRunId: number;
+  isStreaming: boolean;
+}): boolean {
+  if (!shouldProcessStreamLifecycleEvent(args.activeRunId, args.eventRunId)) {
+    return false;
+  }
+  return args.isStreaming;
+}
+
+beforeEach(() => {
+  resetRuntimeParityMetrics();
+});
+
+describe("chat stream lifecycle run guard", () => {
+  test("ignores lifecycle events before stream.session.start binds a run", () => {
+    expect(shouldProcessStreamLifecycleEvent(null, 7)).toBe(false);
+  });
+
+  test("ignores stale lifecycle events from a previous run", () => {
+    expect(shouldProcessStreamLifecycleEvent(12, 11)).toBe(false);
+  });
+
+  test("accepts lifecycle events from the active run", () => {
+    expect(shouldProcessStreamLifecycleEvent(12, 12)).toBe(true);
+  });
+
+  test("idle finalization runs only for the active stream run", () => {
+    expect(
+      shouldFinalizeOnIdle({
+        activeRunId: 22,
+        eventRunId: 21,
+        isStreaming: true,
+      }),
+    ).toBe(false);
+
+    expect(
+      shouldFinalizeOnIdle({
+        activeRunId: 22,
+        eventRunId: 22,
+        isStreaming: true,
+      }),
+    ).toBe(true);
+  });
+});
+
+describe("agent-only stream finalization guard", () => {
+  test("finalizes when live sub-agent state is present", () => {
+    expect(
+      shouldFinalizeAgentOnlyStream({
+        hasStreamingMessage: true,
+        isStreaming: true,
+        isAgentOnlyStream: true,
+        liveAgentCount: 1,
+        messageAgentCount: 0,
+      }),
+    ).toBe(true);
+  });
+
+  test("finalizes when live state is cleared but message snapshot still has sub-agents", () => {
+    expect(
+      shouldFinalizeAgentOnlyStream({
+        hasStreamingMessage: true,
+        isStreaming: true,
+        isAgentOnlyStream: true,
+        liveAgentCount: 0,
+        messageAgentCount: 1,
+      }),
+    ).toBe(true);
+  });
+
+  test("does not finalize before any sub-agent data exists", () => {
+    expect(
+      shouldFinalizeAgentOnlyStream({
+        hasStreamingMessage: true,
+        isStreaming: true,
+        isAgentOnlyStream: true,
+        liveAgentCount: 0,
+        messageAgentCount: 0,
+      }),
+    ).toBe(false);
+  });
+});
+
+describe("@agent continuation payload", () => {
+  function createAgent(overrides: Partial<ParallelAgent>): ParallelAgent {
+    return {
+      id: "agent-1",
+      name: "worker",
+      task: "task",
+      status: "completed",
+      startedAt: new Date().toISOString(),
+      ...overrides,
+    };
+  }
+
+  test("builds payload from foreground sub-agent results", () => {
+    const payload = buildAgentContinuationPayload({
+      agents: [
+        createAgent({ id: "fg-1", name: "worker", result: "Done A" }),
+        createAgent({ id: "bg-1", name: "bg", background: true, result: "ignore" }),
+        createAgent({ id: "fg-2", name: "reviewer", result: "Done B" }),
+      ],
+    });
+
+    expect(payload).toBe(
+      '[Sub-agent results]\n\nSub-agent "worker" result:\n\nDone A\n\nSub-agent "reviewer" result:\n\nDone B',
+    );
+  });
+
+  test("falls back to assistant text when no sub-agent result exists", () => {
+    const payload = buildAgentContinuationPayload({
+      agents: [createAgent({ status: "completed", result: "" })],
+      fallbackText: "Final agent output",
+    });
+
+    expect(payload).toBe("[Sub-agent result]\n\nFinal agent output");
+  });
+
+  test("uses foreground agent error text when result text is unavailable", () => {
+    const payload = buildAgentContinuationPayload({
+      agents: [createAgent({ status: "error", result: "", error: "Tool execution failed" })],
+    });
+
+    expect(payload).toBe('[Sub-agent results]\n\nSub-agent "worker" result:\n\nTool execution failed');
+  });
+
+  test("ignores background-only results and uses fallback text", () => {
+    const payload = buildAgentContinuationPayload({
+      agents: [createAgent({ id: "bg-1", background: true, result: "background only" })],
+      fallbackText: "Foreground summary",
+    });
+
+    expect(payload).toBe("[Sub-agent result]\n\nForeground summary");
+  });
+
+  test("returns null when both agent results and fallback are empty", () => {
+    const payload = buildAgentContinuationPayload({
+      agents: [createAgent({ status: "error", error: "   " })],
+      fallbackText: "   ",
+    });
+
+    expect(payload).toBeNull();
+  });
+});
+
+describe("@agent continuation contract guard", () => {
+  test("returns violation when @agent continuation payload is missing", () => {
+    const violation = getAgentContinuationContractViolation({
+      isAgentOnlyStream: true,
+      continuationPayload: null,
+    });
+
+    expect(violation).toBe(
+      "Contract violation (INV-OUTPUT-001): missing @agent continuation input; turn terminated.",
+    );
+  });
+
+  test("does not return violation for non-agent streams", () => {
+    const violation = getAgentContinuationContractViolation({
+      isAgentOnlyStream: false,
+      continuationPayload: null,
+    });
+
+    expect(violation).toBeNull();
+  });
+
+  test("does not return violation when payload exists", () => {
+    const violation = getAgentContinuationContractViolation({
+      isAgentOnlyStream: true,
+      continuationPayload: "[Sub-agent results]\n\nok",
+    });
+
+    expect(violation).toBeNull();
+  });
+});
+
+describe("contract failure observability", () => {
+  test("records strict lifecycle violation diagnostics and metrics", () => {
+    const originalDebug = process.env.DEBUG;
+    process.env.DEBUG = "1";
+    const debugSpy = spyOn(console, "debug").mockImplementation(() => {});
+
+    try {
+      emitAgentLifecycleContractObservability({
+        provider: "claude",
+        runId: 17,
+        code: "OUT_OF_ORDER_EVENT",
+        eventType: "stream.agent.update",
+        agentId: "agent-1",
+      });
+      expect(debugSpy).toHaveBeenCalled();
+    } finally {
+      if (originalDebug === undefined) {
+        delete process.env.DEBUG;
+      } else {
+        process.env.DEBUG = originalDebug;
+      }
+      debugSpy.mockRestore();
+    }
+
+    const metrics = getRuntimeParityMetricsSnapshot();
+    expect(metrics.counters["workflow.runtime.parity.agent_lifecycle_contract_violation_total{code=OUT_OF_ORDER_EVENT,eventType=stream.agent.update,provider=claude}"]).toBe(1);
+    expect(metrics.counters["workflow.runtime.parity.agent_event_out_of_order_total{code=OUT_OF_ORDER_EVENT,eventType=stream.agent.update,provider=claude}"]).toBe(1);
+  });
+
+  test("records continuation and contract-termination metrics for missing payload", () => {
+    emitAgentMainContinuationObservability({
+      provider: "opencode",
+      runId: 23,
+      result: "missing",
+    });
+    emitContractFailureTerminationObservability({
+      provider: "opencode",
+      runId: 23,
+      reason: "missing_agent_continuation",
+      errorMessage: "Contract violation (INV-OUTPUT-001): missing @agent continuation input; turn terminated.",
+    });
+
+    const metrics = getRuntimeParityMetricsSnapshot();
+    expect(metrics.counters["workflow.runtime.parity.agent_result_main_continuation_total{provider=opencode,result=missing}"]).toBe(1);
+    expect(metrics.counters["workflow.runtime.parity.turn_terminated_due_to_contract_error_total{provider=opencode,reason=missing_agent_continuation}"]).toBe(1);
+  });
+});
diff --git a/src/ui/chat.subagent-grouping.test.ts b/src/ui/chat.subagent-grouping.test.ts
index 91ab40c171..3c45428058 100644
--- a/src/ui/chat.subagent-grouping.test.ts
+++ b/src/ui/chat.subagent-grouping.test.ts
@@ -1,7 +1,16 @@
 import { describe, expect, test } from "bun:test";
 import type { ParallelAgent } from "./components/parallel-agents-tree.tsx";
 import type { AgentPart } from "./parts/index.ts";
-import { shouldGroupSubagentTrees } from "./chat.tsx";
+import {
+  finalizeCorrelatedSubagentDispatchForToolComplete,
+  finalizeSyntheticTaskAgentForToolComplete,
+  isSyntheticTaskAgentId,
+  mergeAgentTaskLabel,
+  resolveSubagentStartCorrelationId,
+  resolveAgentCurrentToolForUpdate,
+  shouldGroupSubagentTrees,
+  upsertSyntheticTaskAgentForToolStart,
+} from "./chat.tsx";
 
 function createCompletedAgent(): ParallelAgent {
   return {
@@ -54,7 +63,7 @@ describe("shouldGroupSubagentTrees", () => {
     ).toBe(true);
   });
 
-  test("does not force grouping for completed trees without grouped history", () => {
+  test("groups completed trees even without grouped history", () => {
     const splitPart: AgentPart = {
       id: "agent-part-split",
       type: "agent",
@@ -72,6 +81,237 @@ describe("shouldGroupSubagentTrees", () => {
         },
         true,
       ),
-    ).toBe(false);
+    ).toBe(true);
+  });
+
+  test("groups sub-agents on non-last messages too", () => {
+    const activeAgent: ParallelAgent = {
+      ...createCompletedAgent(),
+      status: "running",
+    };
+
+    expect(
+      shouldGroupSubagentTrees(
+        {
+          parallelAgents: [activeAgent],
+          toolCalls: [{ id: "task-1", toolName: "Task", input: {}, status: "running" }],
+          parts: [],
+        },
+        false,
+      ),
+    ).toBe(true);
+  });
+});
+
+describe("mergeAgentTaskLabel", () => {
+  test("preserves descriptive task labels when incoming label is generic", () => {
+    expect(mergeAgentTaskLabel("Debug stuck spinner", "Sub-agent task", "debugger")).toBe("Debug stuck spinner");
+  });
+
+  test("upgrades generic labels when a descriptive task arrives", () => {
+    expect(mergeAgentTaskLabel("Sub-agent task", "Debug stuck spinner", "debugger")).toBe("Debug stuck spinner");
+  });
+
+  test("keeps canonical descriptive label when incoming task is empty", () => {
+    expect(mergeAgentTaskLabel("Investigate flaky spinner", "   ", "debugger")).toBe("Investigate flaky spinner");
+  });
+
+  test("falls back to agent type when existing label is generic and task is missing", () => {
+    expect(mergeAgentTaskLabel("subagent task", undefined, "codebase-analyzer")).toBe("codebase-analyzer");
+  });
+});
+
+describe("resolveSubagentStartCorrelationId", () => {
+  test("prefers sdkCorrelationId when available", () => {
+    expect(
+      resolveSubagentStartCorrelationId({
+        sdkCorrelationId: "sdk-1",
+        toolCallId: "tool-1",
+      })
+    ).toBe("sdk-1");
+  });
+
+  test("falls back to toolCallId when sdkCorrelationId is missing", () => {
+    expect(
+      resolveSubagentStartCorrelationId({
+        toolCallId: "tool-2",
+      })
+    ).toBe("tool-2");
+  });
+});
+
+describe("finalizeCorrelatedSubagentDispatchForToolComplete", () => {
+  test("marks correlated running agents interrupted on dispatch abort without agent.complete", () => {
+    const agents: ParallelAgent[] = [
+      {
+        id: "agent-1",
+        taskToolCallId: "tool-1",
+        name: "codebase-analyzer",
+        task: "Analyze rendering",
+        status: "running",
+        startedAt: "2026-03-02T08:17:49.941Z",
+        currentTool: "rg",
+      },
+      {
+        id: "agent-2",
+        taskToolCallId: "tool-2",
+        name: "debugger",
+        task: "Inspect logs",
+        status: "running",
+        startedAt: "2026-03-02T08:17:49.941Z",
+      },
+    ];
+
+    const result = finalizeCorrelatedSubagentDispatchForToolComplete({
+      agents,
+      toolName: "Agent",
+      toolId: "tool-1",
+      success: false,
+      error: "Tool execution aborted",
+      completedAtMs: new Date("2026-03-02T08:18:59.188Z").getTime(),
+    });
+
+    expect(result[0]!.status).toBe("interrupted");
+    expect(result[0]!.currentTool).toBeUndefined();
+    expect(result[0]!.durationMs).toBeGreaterThan(0);
+    expect(result[1]!.status).toBe("running");
+  });
+});
+
+describe("resolveAgentCurrentToolForUpdate", () => {
+  test("keeps incoming tool name when present", () => {
+    expect(resolveAgentCurrentToolForUpdate({
+      incomingCurrentTool: "rg",
+      existingCurrentTool: "Running codebase-locator...",
+      agentName: "codebase-locator",
+    })).toBe("rg");
+  });
+
+  test("drops bootstrap running label when update has no current tool", () => {
+    expect(resolveAgentCurrentToolForUpdate({
+      existingCurrentTool: "Running codebase-locator...",
+      agentName: "codebase-locator",
+    })).toBeUndefined();
+  });
+
+  test("preserves last concrete tool when update omits current tool", () => {
+    expect(resolveAgentCurrentToolForUpdate({
+      existingCurrentTool: "glob",
+      agentName: "codebase-locator",
+    })).toBe("glob");
+  });
+});
+
+describe("OpenCode synthetic task agent fallback", () => {
+  test("creates a running synthetic agent from Task tool.start with execution details", () => {
+    const agents = upsertSyntheticTaskAgentForToolStart({
+      agents: [],
+      provider: "opencode",
+      toolName: "task",
+      toolId: "tool-1",
+      input: {
+        description: "Research TUI UX practices",
+        subagent_type: "codebase-online-researcher",
+      },
+      startedAt: "2026-03-02T06:18:36.000Z",
+    });
+
+    expect(agents).toHaveLength(1);
+    expect(isSyntheticTaskAgentId(agents[0]!.id)).toBe(true);
+    expect(agents[0]!.taskToolCallId).toBe("tool-1");
+    expect(agents[0]!.name).toBe("codebase-online-researcher");
+    expect(agents[0]!.task).toBe("Research TUI UX practices");
+    expect(agents[0]!.status).toBe("running");
+    expect(agents[0]!.toolUses).toBe(0);
+    expect(agents[0]!.currentTool).toBeUndefined();
+  });
+
+  test("updates the same synthetic agent when duplicate Task tool.start fills input", () => {
+    const first = upsertSyntheticTaskAgentForToolStart({
+      agents: [],
+      provider: "opencode",
+      toolName: "task",
+      toolId: "tool-1",
+      input: {},
+      startedAt: "2026-03-02T06:18:36.000Z",
+    });
+
+    const second = upsertSyntheticTaskAgentForToolStart({
+      agents: first,
+      provider: "opencode",
+      toolName: "task",
+      toolId: "tool-1",
+      input: {
+        description: "Research TUI UX practices",
+        subagent_type: "codebase-online-researcher",
+      },
+      startedAt: "2026-03-02T06:18:43.000Z",
+    });
+
+    expect(second).toHaveLength(1);
+    expect(second[0]!.name).toBe("codebase-online-researcher");
+    expect(second[0]!.task).toBe("Research TUI UX practices");
+    expect(second[0]!.status).toBe("running");
+    expect(second[0]!.toolUses).toBe(0);
+    expect(second[0]!.currentTool).toBeUndefined();
+  });
+
+  test("skips visible synthetic placeholder rows for empty task starts", () => {
+    const agents = upsertSyntheticTaskAgentForToolStart({
+      agents: [],
+      provider: "opencode",
+      toolName: "task",
+      toolId: "tool-1",
+      input: {},
+      startedAt: "2026-03-02T06:18:36.000Z",
+    });
+
+    expect(agents).toHaveLength(0);
+  });
+
+  test("does not create synthetic task agents for non-OpenCode providers", () => {
+    const agents = upsertSyntheticTaskAgentForToolStart({
+      agents: [],
+      provider: "claude",
+      toolName: "task",
+      toolId: "tool-1",
+      input: {
+        description: "Research TUI UX practices",
+        subagent_type: "codebase-online-researcher",
+      },
+      startedAt: "2026-03-02T06:18:36.000Z",
+    });
+
+    expect(agents).toHaveLength(0);
+  });
+
+  test("marks synthetic agent interrupted when Task tool completes with aborted error", () => {
+    const started = upsertSyntheticTaskAgentForToolStart({
+      agents: [],
+      provider: "opencode",
+      toolName: "task",
+      toolId: "tool-1",
+      input: {
+        description: "Research TUI UX practices",
+        subagent_type: "codebase-online-researcher",
+      },
+      startedAt: "2026-03-02T06:18:36.000Z",
+    });
+
+    const finalized = finalizeSyntheticTaskAgentForToolComplete({
+      agents: started,
+      provider: "opencode",
+      toolName: "task",
+      toolId: "tool-1",
+      success: false,
+      output: null,
+      error: "Tool execution aborted",
+      completedAtMs: new Date("2026-03-02T06:19:18.000Z").getTime(),
+    });
+
+    expect(finalized).toHaveLength(1);
+    expect(finalized[0]!.status).toBe("interrupted");
+    expect(finalized[0]!.currentTool).toBeUndefined();
+    expect(finalized[0]!.durationMs).toBeGreaterThan(0);
   });
 });
diff --git a/src/ui/chat.task-state.test.ts b/src/ui/chat.task-state.test.ts
index 81625ec45e..267d68d01e 100644
--- a/src/ui/chat.task-state.test.ts
+++ b/src/ui/chat.task-state.test.ts
@@ -1,17 +1,17 @@
 import { describe, expect, test } from "bun:test";
 import {
   applyTaskSnapshotToLatestAssistantMessage,
-  hasRalphTaskIdOverlap,
+  hasWorkflowTaskIdOverlap,
   normalizeInterruptedTasks,
   preferTerminalTaskItems,
   snapshotTaskItems,
-  type RalphTaskStateItem,
-} from "./utils/ralph-task-state.ts";
+  type WorkflowTaskStateItem,
+} from "./utils/workflow-task-state.ts";
 import { mergeBlockedBy, type NormalizedTodoItem } from "./utils/task-status.ts";
 
-describe("ralph task state helpers", () => {
+describe("workflow task state helpers", () => {
   test("normalizeInterruptedTasks only resets in_progress to pending", () => {
-    const tasks: RalphTaskStateItem[] = [
+    const tasks: WorkflowTaskStateItem[] = [
       { id: "#1", content: "a", status: "pending" },
       { id: "#2", content: "b", status: "in_progress" },
       { id: "#3", content: "c", status: "completed" },
@@ -28,7 +28,7 @@ describe("ralph task state helpers", () => {
   });
 
   test("snapshotTaskItems preserves status values without coercion", () => {
-    const tasks: RalphTaskStateItem[] = [
+    const tasks: WorkflowTaskStateItem[] = [
       { id: "#1", content: "a", status: "pending" },
       { id: "#2", content: "b", status: "in_progress" },
       { id: "#3", content: "c", status: "completed" },
@@ -49,37 +49,37 @@ describe("ralph task state helpers", () => {
     expect(snapshotTaskItems([])).toBeUndefined();
   });
 
-  test("hasRalphTaskIdOverlap matches ids with and without # prefix", () => {
+  test("hasWorkflowTaskIdOverlap matches ids with and without # prefix", () => {
     const knownIds = new Set(["#1", "#2"]);
-    const todos: RalphTaskStateItem[] = [
+    const todos: WorkflowTaskStateItem[] = [
       { id: "1", content: "first", status: "completed" },
       { id: "2", content: "second", status: "pending" },
     ];
 
-    expect(hasRalphTaskIdOverlap(todos, knownIds)).toBe(true);
+    expect(hasWorkflowTaskIdOverlap(todos, knownIds)).toBe(true);
   });
 
-  test("hasRalphTaskIdOverlap rejects unrelated todo ids", () => {
+  test("hasWorkflowTaskIdOverlap rejects unrelated todo ids", () => {
     const knownIds = new Set(["#1", "#2"]);
-    const todos: RalphTaskStateItem[] = [
+    const todos: WorkflowTaskStateItem[] = [
       { id: "#9", content: "other", status: "completed" },
     ];
 
-    expect(hasRalphTaskIdOverlap(todos, knownIds)).toBe(false);
+    expect(hasWorkflowTaskIdOverlap(todos, knownIds)).toBe(false);
   });
 
-  test("hasRalphTaskIdOverlap rejects mixed payloads with foreign IDs", () => {
+  test("hasWorkflowTaskIdOverlap rejects mixed payloads with foreign IDs", () => {
     const knownIds = new Set(["#1", "#2"]);
-    const todos: RalphTaskStateItem[] = [
+    const todos: WorkflowTaskStateItem[] = [
       { id: "#1", content: "first", status: "completed" },
       { id: "#99", content: "foreign", status: "pending" },
     ];
 
-    expect(hasRalphTaskIdOverlap(todos, knownIds)).toBe(false);
+    expect(hasWorkflowTaskIdOverlap(todos, knownIds)).toBe(false);
   });
 
   test("supports restart resume by preserving ids and blockedBy", () => {
-    const interrupted: RalphTaskStateItem[] = [
+    const interrupted: WorkflowTaskStateItem[] = [
       { id: "#1", content: "bootstrap", status: "completed" },
       {
         id: "#2",
@@ -105,7 +105,7 @@ describe("ralph task state helpers", () => {
       blockedBy: ["#1"],
     });
     expect(
-      hasRalphTaskIdOverlap(snapshot ?? [], new Set(["1", "2", "3"])),
+      hasWorkflowTaskIdOverlap(snapshot ?? [], new Set(["1", "2", "3"])),
     ).toBe(true);
   });
 
@@ -121,7 +121,7 @@ describe("ralph task state helpers", () => {
     ];
 
     const merged = mergeBlockedBy(incomingWithoutIds, previous);
-    expect(hasRalphTaskIdOverlap(merged, knownIds)).toBe(true);
+    expect(hasWorkflowTaskIdOverlap(merged, knownIds)).toBe(true);
   });
 
   test("accepts no-id updates when known IDs are empty but content matches", () => {
@@ -135,7 +135,7 @@ describe("ralph task state helpers", () => {
       { content: "add tests", status: "in_progress", activeForm: "Adding tests" },
     ];
 
-    expect(hasRalphTaskIdOverlap(incomingWithoutIds, knownIds, previous)).toBe(true);
+    expect(hasWorkflowTaskIdOverlap(incomingWithoutIds, knownIds, previous)).toBe(true);
   });
 
   test("recognizes no-id updates when content prefixes include task IDs/checkboxes", () => {
@@ -150,7 +150,7 @@ describe("ralph task state helpers", () => {
     ];
 
     const merged = mergeBlockedBy(incomingWithoutIds, previous);
-    expect(hasRalphTaskIdOverlap(merged, knownIds, previous)).toBe(true);
+    expect(hasWorkflowTaskIdOverlap(merged, knownIds, previous)).toBe(true);
   });
 
   test("rejects no-id updates when prefixed content carries foreign task IDs", () => {
@@ -165,7 +165,7 @@ describe("ralph task state helpers", () => {
     ];
 
     const merged = mergeBlockedBy(incomingWithoutIds, previous);
-    expect(hasRalphTaskIdOverlap(merged, knownIds, previous)).toBe(false);
+    expect(hasWorkflowTaskIdOverlap(merged, knownIds, previous)).toBe(false);
   });
 
   test("rejects unrelated no-id TodoWrite payloads during /ralph", () => {
@@ -179,7 +179,7 @@ describe("ralph task state helpers", () => {
     ];
 
     const merged = mergeBlockedBy(unrelated, previous);
-    expect(hasRalphTaskIdOverlap(merged, knownIds)).toBe(false);
+    expect(hasWorkflowTaskIdOverlap(merged, knownIds)).toBe(false);
   });
 
   test("rejects no-id rows that do not match existing ralph tasks", () => {
@@ -193,15 +193,15 @@ describe("ralph task state helpers", () => {
       { content: "Completely new task", status: "pending", activeForm: "Adding a new task" },
     ];
 
-    expect(hasRalphTaskIdOverlap(mixed, knownIds, previous)).toBe(false);
+    expect(hasWorkflowTaskIdOverlap(mixed, knownIds, previous)).toBe(false);
   });
 
   test("preferTerminalTaskItems drops stale in_progress last-item snapshots", () => {
-    const inMemory: RalphTaskStateItem[] = [
+    const inMemory: WorkflowTaskStateItem[] = [
       { id: "#1", content: "prep", status: "completed" },
       { id: "#2", content: "finalize", status: "in_progress" },
     ];
-    const fromDisk: RalphTaskStateItem[] = [
+    const fromDisk: WorkflowTaskStateItem[] = [
       { id: "#1", content: "prep", status: "completed" },
       { id: "#2", content: "finalize", status: "completed" },
     ];
@@ -210,7 +210,7 @@ describe("ralph task state helpers", () => {
   });
 
   test("applyTaskSnapshotToLatestAssistantMessage refreshes final assistant task state", () => {
-    const messages: Array<{ id: string; role: string; taskItems?: RalphTaskStateItem[] }> = [
+    const messages: Array<{ id: string; role: string; taskItems?: WorkflowTaskStateItem[] }> = [
       {
         id: "m-user",
         role: "user",
@@ -225,7 +225,7 @@ describe("ralph task state helpers", () => {
       },
     ];
 
-    const nextTasks: RalphTaskStateItem[] = [
+    const nextTasks: WorkflowTaskStateItem[] = [
       { id: "#1", content: "prep", status: "completed" },
       { id: "#2", content: "finalize", status: "completed" },
     ];
diff --git a/src/ui/chat.thinking-meta-routing.test.ts b/src/ui/chat.thinking-meta-routing.test.ts
index d589865cc8..c053572f37 100644
--- a/src/ui/chat.thinking-meta-routing.test.ts
+++ b/src/ui/chat.thinking-meta-routing.test.ts
@@ -29,18 +29,18 @@ function createDiagnostics(): ThinkingDropDiagnostics {
 }
 
 describe("resolveValidatedThinkingMetaEvent", () => {
-  test("returns null when source generation is stale", () => {
+  test("returns null when source generation binding is missing", () => {
     const meta = createMeta({
-      thinkingGenerationBySource: { [sourceKey]: 2 },
+      thinkingGenerationBySource: {},
     });
     const diagnostics = createDiagnostics();
 
-    const event = resolveValidatedThinkingMetaEvent(meta, "msg-1", 3, undefined, diagnostics);
+    const event = resolveValidatedThinkingMetaEvent(meta, "msg-1", undefined, diagnostics);
 
     expect(event).toBeNull();
     expect(diagnostics).toEqual({
-      droppedStaleOrClosedThinkingEvents: 1,
-      droppedMissingBindingThinkingEvents: 0,
+      droppedStaleOrClosedThinkingEvents: 0,
+      droppedMissingBindingThinkingEvents: 1,
     });
   });
 
@@ -50,7 +50,7 @@ describe("resolveValidatedThinkingMetaEvent", () => {
     });
     const diagnostics = createDiagnostics();
 
-    const event = resolveValidatedThinkingMetaEvent(meta, "msg-1", 3, undefined, diagnostics);
+    const event = resolveValidatedThinkingMetaEvent(meta, "msg-1", undefined, diagnostics);
 
     expect(event).toBeNull();
     expect(diagnostics).toEqual({
@@ -59,17 +59,22 @@ describe("resolveValidatedThinkingMetaEvent", () => {
     });
   });
 
-  test("increments missing-binding counter when source message binding is absent", () => {
+  test("defaults to expectedMessageId when source message binding is absent", () => {
     const diagnostics = createDiagnostics();
 
     const event = resolveValidatedThinkingMetaEvent(createMeta({
       thinkingMessageBySource: {},
-    }), "msg-1", 3, undefined, diagnostics);
+    }), "msg-1", undefined, diagnostics);
 
-    expect(event).toBeNull();
+    expect(event).toEqual({
+      thinkingSourceKey: sourceKey,
+      targetMessageId: "msg-1",
+      streamGeneration: 3,
+      thinkingText: "source thought",
+    });
     expect(diagnostics).toEqual({
       droppedStaleOrClosedThinkingEvents: 0,
-      droppedMissingBindingThinkingEvents: 1,
+      droppedMissingBindingThinkingEvents: 0,
     });
   });
 
@@ -77,7 +82,7 @@ describe("resolveValidatedThinkingMetaEvent", () => {
     const meta = createMeta();
     const diagnostics = createDiagnostics();
 
-    const event = resolveValidatedThinkingMetaEvent(meta, "msg-1", 3, undefined, diagnostics);
+    const event = resolveValidatedThinkingMetaEvent(meta, "msg-1", undefined, diagnostics);
 
     expect(event).toEqual({
       thinkingSourceKey: sourceKey,
@@ -96,7 +101,7 @@ describe("resolveValidatedThinkingMetaEvent", () => {
     const closedSources = new Set([sourceKey]);
     const diagnostics = createDiagnostics();
 
-    const event = resolveValidatedThinkingMetaEvent(meta, "msg-1", 3, closedSources, diagnostics);
+    const event = resolveValidatedThinkingMetaEvent(meta, "msg-1", closedSources, diagnostics);
 
     expect(event).toBeNull();
     expect(diagnostics).toEqual({
@@ -113,7 +118,6 @@ describe("resolveValidatedThinkingMetaEvent", () => {
         thinkingTextBySource: { [sourceKey]: "late thought" },
       }),
       "msg-1",
-      3,
       closedSources,
     );
 
diff --git a/src/ui/chat.tsx b/src/ui/chat.tsx
index c3110db94d..6e079ada96 100644
--- a/src/ui/chat.tsx
+++ b/src/ui/chat.tsx
@@ -28,6 +28,7 @@ import {
   type ParallelAgent,
 } from "./components/parallel-agents-tree.tsx";
 import { BackgroundAgentFooter } from "./components/background-agent-footer.tsx";
+import { FooterStatus } from "./components/footer-status.tsx";
 import { TranscriptView } from "./components/transcript-view.tsx";
 import {
   appendCompactionSummary,
@@ -35,11 +36,12 @@ import {
   readHistoryBuffer,
   clearHistoryBuffer,
 } from "./utils/conversation-history-buffer.ts";
-import {
-  SubagentGraphBridge,
-  setSubagentBridge,
-  type CreateSessionFn,
-} from "../graph/subagent-bridge.ts";
+import type {
+  CreateSessionFn,
+  SubagentSpawnOptions,
+  SubagentStreamResult,
+} from "../workflows/graph/types.ts";
+import { SubagentStreamAdapter } from "../events/adapters/subagent-adapter.ts";
 import {
   UserQuestionDialog,
   type UserQuestion,
@@ -51,12 +53,11 @@ import {
 import type { Model } from "../models/model-transform.ts";
 import type { TaskItem } from "./components/task-list-indicator.tsx";
 import { TaskListPanel } from "./components/task-list-panel.tsx";
+import { sortTasksTopologically } from "./components/task-order.ts";
 import { saveTasksToActiveSession } from "./commands/workflow-commands.ts";
-import {
-  useStreamingState,
-  type ToolExecutionStatus,
-} from "./hooks/use-streaming-state.ts";
+import { type ToolExecutionStatus } from "./parts/types.ts";
 import { useMessageQueue, type QueuedMessage } from "./hooks/use-message-queue.ts";
+import { useVerboseMode } from "./hooks/use-verbose-mode.ts";
 import {
   globalRegistry,
   parseSlashCommand,
@@ -67,9 +68,11 @@ import {
 } from "./commands/index.ts";
 import { readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import type { AskUserQuestionEventData } from "../graph/index.ts";
+import type { AskUserQuestionEventData } from "../workflows/graph/index.ts";
 import type { AgentType, ModelOperations } from "../models";
-import type { McpServerConfig } from "../sdk/types.ts";
+import type {
+  McpServerConfig,
+} from "../sdk/types.ts";
 import { saveModelPreference, saveReasoningEffortPreference, clearReasoningEffortPreference } from "../utils/settings.ts";
 import { formatDuration, normalizeMarkdownNewlines } from "./utils/format.ts";
 import {
@@ -80,17 +83,18 @@ import {
 import {
   getActiveBackgroundAgents,
   resolveBackgroundAgentsForFooter,
-  formatBackgroundAgentFooterStatus,
   isBackgroundAgent,
 } from "./utils/background-agent-footer.ts";
-import { BACKGROUND_FOOTER_CONTRACT } from "./utils/background-agent-contracts.ts";
 import {
-  getBackgroundTerminationDecision,
-  interruptActiveBackgroundAgents,
+  shouldScheduleBackgroundUpdateFollowUpFlush,
+  shouldStartBackgroundUpdateFlush,
+} from "./utils/background-update-flush.ts";
+import {
+  evaluateBackgroundTerminationPress,
+  executeBackgroundTermination,
   isBackgroundTerminationKey,
 } from "./utils/background-agent-termination.ts";
 import { loadCommandHistory, appendCommandHistory } from "./utils/command-history.ts";
-import { getRandomVerb, getRandomCompletionVerb } from "./constants/index.ts";
 import type { McpServerToggleMap, McpSnapshotView } from "./utils/mcp-output.ts";
 import {
   normalizeHitlAnswer,
@@ -98,18 +102,13 @@ import {
 } from "./utils/hitl-response.ts";
 import {
   normalizeTodoItems,
-  mergeBlockedBy,
+  reconcileTodoWriteItems,
   isTodoWriteToolName,
   type NormalizedTodoItem,
 } from "./utils/task-status.ts";
 import {
-  AUTO_COMPACTION_INDICATOR_IDLE_STATE,
-  AUTO_COMPACTION_RESULT_VISIBILITY_MS,
   clearRunningAutoCompactionIndicator,
-  completeAutoCompactionIndicator,
-  getAutoCompactionIndicatorLabel,
-  shouldShowAutoCompactionIndicator,
-  startAutoCompactionIndicator,
+  isAutoCompactionToolName,
   type AutoCompactionIndicatorState,
 } from "./utils/auto-compaction-lifecycle.ts";
 import {
@@ -117,18 +116,28 @@ import {
   createStoppedStreamControlState,
   dispatchNextQueuedMessage,
   interruptRunningToolCalls,
+  interruptRunningToolParts,
   isAskQuestionToolName,
-  isCurrentStreamCallback,
+  shouldContinueParentSessionLoop,
+  shouldTrackToolAsBlocking,
   shouldDispatchQueuedMessage,
   shouldDeferComposerSubmit,
-  invalidateActiveStreamGeneration,
+  type SessionLoopFinishReason,
 } from "./utils/stream-continuation.ts";
+import {
+  createAgentLifecycleLedger,
+  formatAgentLifecycleViolation,
+  registerAgentLifecycleComplete,
+  registerAgentLifecycleStart,
+  registerAgentLifecycleUpdate,
+  type AgentLifecycleViolationCode,
+} from "./utils/agent-lifecycle-ledger.ts";
 import { getNextKittyKeyboardDetectionState } from "./utils/kitty-keyboard-detection.ts";
 import {
   getEnqueueShortcutLabel,
   shouldApplyBackslashLineContinuation,
   shouldEnqueueMessageFromKeyEvent,
-  shouldInsertNewlineFromKeyEvent,
+  shouldInsertNewlineFallbackFromKeyEvent,
 } from "./utils/newline-strategies.ts";
 import {
   hasAnyAtReferenceToken,
@@ -138,32 +147,46 @@ import {
 } from "./utils/mention-parsing.ts";
 import {
   applyTaskSnapshotToLatestAssistantMessage,
-  hasRalphTaskIdOverlap,
+  hasWorkflowTaskIdOverlap,
   normalizeInterruptedTasks,
   preferTerminalTaskItems,
   snapshotTaskItems,
-} from "./utils/ralph-task-state.ts";
+} from "./utils/workflow-task-state.ts";
+import {
+  consumeWorkflowInputSubmission,
+  rejectPendingWorkflowInput,
+  type WorkflowInputResolver,
+} from "./utils/workflow-input-resolver.ts";
 import type {
   Part,
+  StreamPartEvent,
   TextPart,
-  TaskListPart,
   SkillLoadPart,
   McpSnapshotPart,
   CompactionPart,
-  PartId,
   ToolPart,
 } from "./parts/index.ts";
 import {
   createPartId,
   finalizeStreamingReasoningInMessage,
+  finalizeStreamingReasoningParts,
   hasActiveForegroundAgents,
   shouldFinalizeDeferredStream,
   applyStreamPartEvent,
+  isSubagentToolName,
   mergeParallelAgentsIntoParts,
   shouldGroupSubagentTrees,
   syncToolCallsIntoParts,
 } from "./parts/index.ts";
 import { MessageBubbleParts } from "./components/parts/message-bubble-parts.tsx";
+import { useBusSubscription, useStreamConsumer } from "../events/hooks.ts";
+import { useEventBusContext } from "../events/event-bus-provider.tsx";
+import type { EventBus } from "../events/event-bus.ts";
+import {
+  incrementRuntimeParityCounter,
+  runtimeParityDebug,
+} from "../workflows/runtime-parity-observability.ts";
+import { pipelineError } from "../events/pipeline-logger.ts";
 
 
 export { shouldGroupSubagentTrees };
@@ -173,6 +196,339 @@ export {
   shouldShowCompletionSummary,
 } from "./utils/loading-state.ts";
 
+const RUNTIME_ENVELOPE_PART_TYPES = new Set<StreamPartEvent["type"]>([
+  "task-list-update",
+  "workflow-step-start",
+  "workflow-step-complete",
+  "task-result-upsert",
+]);
+
+const DEFAULT_SUBAGENT_TASK_LABEL = "sub-agent task";
+const SYNTHETIC_TASK_AGENT_PREFIX = "synthetic-task-agent:";
+
+export function isGenericSubagentTaskLabel(task: string | undefined): boolean {
+  const normalized = (task ?? "").trim().toLowerCase();
+  return normalized === "" || normalized === DEFAULT_SUBAGENT_TASK_LABEL || normalized === "subagent task";
+}
+
+function resolveIncomingSubagentTaskLabel(task: string | undefined, agentType: string | undefined): string {
+  const normalizedTask = task?.trim();
+  if (normalizedTask) return normalizedTask;
+  const normalizedAgentType = agentType?.trim();
+  if (normalizedAgentType) return normalizedAgentType;
+  return DEFAULT_SUBAGENT_TASK_LABEL;
+}
+
+export function mergeAgentTaskLabel(
+  existingTask: string | undefined,
+  incomingTask: string | undefined,
+  agentType: string | undefined,
+): string {
+  const nextTask = resolveIncomingSubagentTaskLabel(incomingTask, agentType);
+  if (isGenericSubagentTaskLabel(existingTask)) return nextTask;
+  return isGenericSubagentTaskLabel(nextTask) ? (existingTask ?? nextTask) : (existingTask ?? nextTask);
+}
+
+export function resolveSubagentStartCorrelationId(data: {
+  sdkCorrelationId?: string;
+  toolCallId?: string;
+}): string | undefined {
+  return data.sdkCorrelationId ?? data.toolCallId;
+}
+
+export function isBootstrapAgentCurrentToolLabel(
+  currentTool: string | undefined,
+  agentName: string | undefined,
+): boolean {
+  if (!currentTool) return false;
+  const normalizedCurrentTool = currentTool.trim().toLowerCase();
+  if (!normalizedCurrentTool.startsWith("running ") || !normalizedCurrentTool.endsWith("...")) {
+    return false;
+  }
+
+  const normalizedAgentName = agentName?.trim().toLowerCase();
+  if (!normalizedAgentName) {
+    return true;
+  }
+  return normalizedCurrentTool === `running ${normalizedAgentName}...`;
+}
+
+export function resolveAgentCurrentToolForUpdate(args: {
+  incomingCurrentTool?: string;
+  existingCurrentTool?: string;
+  agentName?: string;
+}): string | undefined {
+  if (args.incomingCurrentTool !== undefined) {
+    return args.incomingCurrentTool;
+  }
+  if (isBootstrapAgentCurrentToolLabel(args.existingCurrentTool, args.agentName)) {
+    return undefined;
+  }
+  return args.existingCurrentTool;
+}
+
+function asNonEmptyString(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+function parseSyntheticTaskAgentType(input: Record<string, unknown>): string | undefined {
+  return asNonEmptyString(
+    input.subagent_type
+    ?? input.subagentType
+    ?? input.agent_type
+    ?? input.agentType
+    ?? input.agent
+    ?? input.type,
+  );
+}
+
+function parseSyntheticTaskAgentName(input: Record<string, unknown>): string {
+  return parseSyntheticTaskAgentType(input) ?? "agent";
+}
+
+function parseSyntheticTaskLabel(input: Record<string, unknown>): string {
+  const description = asNonEmptyString(
+    input.description
+    ?? input.task
+    ?? input.title,
+  );
+  return resolveIncomingSubagentTaskLabel(description, parseSyntheticTaskAgentType(input));
+}
+
+function parseSyntheticBackgroundFlag(input: Record<string, unknown>): boolean {
+  const mode = asNonEmptyString(input.mode)?.toLowerCase();
+  return input.run_in_background === true || mode === "background";
+}
+
+function hasSyntheticTaskExecutionDetails(input: Record<string, unknown>): boolean {
+  return Boolean(
+    asNonEmptyString(input.description)
+    || asNonEmptyString(input.prompt)
+    || asNonEmptyString(input.task)
+    || asNonEmptyString(input.title),
+  );
+}
+
+function buildSyntheticTaskAgentId(toolId: string): string {
+  return `${SYNTHETIC_TASK_AGENT_PREFIX}${toolId}`;
+}
+
+export function isSyntheticTaskAgentId(agentId: string): boolean {
+  return agentId.startsWith(SYNTHETIC_TASK_AGENT_PREFIX);
+}
+
+function extractTaskToolResultText(output: unknown): string | undefined {
+  if (typeof output === "string") {
+    return asNonEmptyString(output);
+  }
+  if (!output || typeof output !== "object") {
+    return undefined;
+  }
+  const record = output as Record<string, unknown>;
+  return asNonEmptyString(record.result ?? record.text ?? record.output);
+}
+
+function isAbortLikeToolError(error: string | undefined): boolean {
+  const normalized = error?.trim().toLowerCase() ?? "";
+  if (!normalized) return false;
+  return normalized.includes("abort")
+    || normalized.includes("cancel")
+    || normalized.includes("interrupt");
+}
+
+export function upsertSyntheticTaskAgentForToolStart(args: {
+  agents: ParallelAgent[];
+  provider: AgentType | undefined;
+  toolName: string;
+  toolId: string;
+  input: Record<string, unknown>;
+  startedAt: string;
+  agentId?: string;
+}): ParallelAgent[] {
+  if (args.provider !== "opencode") return args.agents;
+  if (args.agentId) return args.agents;
+  if (!isSubagentToolName(args.toolName)) return args.agents;
+
+  const existingRealAgent = args.agents.find(
+    (agent) => agent.taskToolCallId === args.toolId && !isSyntheticTaskAgentId(agent.id),
+  );
+  if (existingRealAgent) {
+    return args.agents;
+  }
+
+  const agentName = parseSyntheticTaskAgentName(args.input);
+  const task = parseSyntheticTaskLabel(args.input);
+  const background = parseSyntheticBackgroundFlag(args.input);
+  const hasExecutionDetails = hasSyntheticTaskExecutionDetails(args.input);
+  if (!hasExecutionDetails) {
+    const hasExistingSynthetic = args.agents.some(
+      (agent) =>
+        agent.id === buildSyntheticTaskAgentId(args.toolId)
+        || (isSyntheticTaskAgentId(agent.id) && agent.taskToolCallId === args.toolId),
+    );
+    // OpenCode often emits an empty placeholder task.start before the
+    // hydrated payload. Skip creating a visible placeholder row so the tree
+    // starts with descriptive task metadata when available.
+    if (!hasExistingSynthetic) {
+      return args.agents;
+    }
+  }
+  const nextStatus: ParallelAgent["status"] = background
+    ? "background"
+    : (hasExecutionDetails ? "running" : "pending");
+  // The Task/Agent call is only the dispatch envelope, not a sub-agent's
+  // internal tool execution. Keep tool progress empty until real sub-agent
+  // tool events arrive.
+  const nextToolUses = 0;
+  const nextCurrentTool = undefined;
+  const syntheticId = buildSyntheticTaskAgentId(args.toolId);
+  const existingSyntheticIndex = args.agents.findIndex(
+    (agent) =>
+      agent.id === syntheticId
+      || (isSyntheticTaskAgentId(agent.id) && agent.taskToolCallId === args.toolId),
+  );
+
+  if (existingSyntheticIndex >= 0) {
+    return args.agents.map((agent, index) =>
+      index === existingSyntheticIndex
+        ? {
+          ...agent,
+          id: syntheticId,
+          taskToolCallId: args.toolId,
+          name: agentName,
+          task: mergeAgentTaskLabel(agent.task, task, agentName),
+          status: nextStatus,
+          background,
+          startedAt: agent.startedAt || args.startedAt,
+          toolUses: Math.max(agent.toolUses ?? 0, nextToolUses),
+          currentTool: nextCurrentTool ?? agent.currentTool,
+          error: undefined,
+        }
+        : agent
+    );
+  }
+
+  return [
+    ...args.agents,
+    {
+      id: syntheticId,
+      taskToolCallId: args.toolId,
+      name: agentName,
+      task,
+      status: nextStatus,
+      startedAt: args.startedAt,
+      background,
+      currentTool: nextCurrentTool,
+      toolUses: nextToolUses,
+    },
+  ];
+}
+
+export function finalizeSyntheticTaskAgentForToolComplete(args: {
+  agents: ParallelAgent[];
+  provider: AgentType | undefined;
+  toolName: string;
+  toolId: string;
+  success: boolean;
+  output: unknown;
+  error?: string;
+  completedAtMs: number;
+  agentId?: string;
+}): ParallelAgent[] {
+  if (args.provider !== "opencode") return args.agents;
+  if (args.agentId) return args.agents;
+  if (!isSubagentToolName(args.toolName)) return args.agents;
+
+  const syntheticId = buildSyntheticTaskAgentId(args.toolId);
+  const syntheticIndex = args.agents.findIndex((agent) => agent.id === syntheticId);
+  if (syntheticIndex < 0) {
+    return args.agents;
+  }
+
+  return args.agents.map((agent, index) => {
+    if (index !== syntheticIndex) return agent;
+    const startedAtMs = new Date(agent.startedAt).getTime();
+    const durationMs = Number.isFinite(startedAtMs)
+      ? Math.max(0, args.completedAtMs - startedAtMs)
+      : agent.durationMs;
+    const status: ParallelAgent["status"] = args.success
+      ? "completed"
+      : (isAbortLikeToolError(args.error) ? "interrupted" : "error");
+    return {
+      ...agent,
+      status,
+      currentTool: agent.currentTool,
+      result: args.success ? (extractTaskToolResultText(args.output) ?? agent.result) : agent.result,
+      error: args.success ? undefined : (args.error ?? agent.error),
+      durationMs,
+    };
+  });
+}
+
+export function finalizeCorrelatedSubagentDispatchForToolComplete(args: {
+  agents: ParallelAgent[];
+  toolName: string;
+  toolId: string;
+  success: boolean;
+  error?: string;
+  completedAtMs: number;
+  agentId?: string;
+}): ParallelAgent[] {
+  if (args.agentId) return args.agents;
+  if (!isSubagentToolName(args.toolName)) return args.agents;
+  if (args.success) return args.agents;
+
+  const status: ParallelAgent["status"] = isAbortLikeToolError(args.error) ? "interrupted" : "error";
+  let changed = false;
+
+  const nextAgents = args.agents.map((agent) => {
+    if (agent.taskToolCallId !== args.toolId) return agent;
+    if (agent.status === "completed" || agent.status === "error" || agent.status === "interrupted") {
+      return agent;
+    }
+
+    const startedAtMs = new Date(agent.startedAt).getTime();
+    const durationMs = Number.isFinite(startedAtMs)
+      ? Math.max(0, args.completedAtMs - startedAtMs)
+      : agent.durationMs;
+    changed = true;
+    return {
+      ...agent,
+      status,
+      currentTool: undefined,
+      error: status === "error" ? (args.error ?? agent.error) : agent.error,
+      durationMs,
+    };
+  });
+
+  return changed ? nextAgents : args.agents;
+}
+
+export function isRuntimeEnvelopePartEvent(
+  part: StreamPartEvent,
+): part is Extract<
+  StreamPartEvent,
+  { type: "task-list-update" | "workflow-step-start" | "workflow-step-complete" | "task-result-upsert" }
+> {
+  return RUNTIME_ENVELOPE_PART_TYPES.has(part.type);
+}
+
+function toWorkflowStepCompletionMessage(
+  part: Extract<StreamPartEvent, { type: "workflow-step-complete" }>,
+): string {
+  const stepLabel = part.nodeName?.trim() || part.nodeId;
+  switch (part.status) {
+    case "success":
+      return `Workflow step "${stepLabel}" completed.`;
+    case "skipped":
+      return `Workflow step "${stepLabel}" skipped.`;
+    case "error":
+      return `Workflow step "${stepLabel}" failed.`;
+  }
+}
+
 
 /**
  * Get autocomplete suggestions for @ mentions (agents and files).
@@ -213,6 +569,11 @@ export function getMentionSuggestions(input: string): CommandDefinition[] {
           // Skip hidden files and common ignore patterns
           if (entry.name.startsWith(".")) continue;
           if (entry.name === "node_modules") continue;
+          if (entry.name === "target") continue;
+          if (entry.name === "build") continue;
+          if (entry.name === "dist") continue;
+          if (entry.name === "out") continue;
+          if (entry.name === "coverage") continue;
 
           const relPath = relativeBase ? `${relativeBase}/${entry.name}` : entry.name;
           const isDir = entry.isDirectory();
@@ -508,7 +869,6 @@ export function mergeClosedThinkingSources(
 export function resolveValidatedThinkingMetaEvent(
   meta: StreamingMeta,
   expectedMessageId: string,
-  currentGeneration: number,
   closedSources?: ReadonlySet<string>,
   diagnostics?: ThinkingDropDiagnostics,
 ): {
@@ -548,10 +908,14 @@ export function resolveValidatedThinkingMetaEvent(
   }
 
   const sourceTargetMessageId = meta.thinkingMessageBySource?.[sourceKey];
-  if (typeof sourceTargetMessageId !== "string" || sourceTargetMessageId.length === 0) {
-    return recordDrop("missing_binding", sourceKey, "missing targetMessageId binding");
-  }
-  if (sourceTargetMessageId !== expectedMessageId) {
+  // When no explicit targetMessageId binding exists (SDK clients don't emit one),
+  // default to the current streaming message — thinking events arriving on the
+  // active stream belong to the active message.
+  const resolvedTargetMessageId =
+    typeof sourceTargetMessageId === "string" && sourceTargetMessageId.length > 0
+      ? sourceTargetMessageId
+      : expectedMessageId;
+  if (resolvedTargetMessageId !== expectedMessageId) {
     return recordDrop("stale_or_closed", sourceKey, "targetMessageId mismatch");
   }
 
@@ -559,13 +923,10 @@ export function resolveValidatedThinkingMetaEvent(
   if (typeof sourceGeneration !== "number" || !Number.isFinite(sourceGeneration)) {
     return recordDrop("missing_binding", sourceKey, "missing streamGeneration binding");
   }
-  if (sourceGeneration !== currentGeneration) {
-    return recordDrop("stale_or_closed", sourceKey, "streamGeneration mismatch");
-  }
 
   return {
     thinkingSourceKey: sourceKey,
-    targetMessageId: sourceTargetMessageId,
+    targetMessageId: resolvedTargetMessageId,
     streamGeneration: sourceGeneration,
     thinkingText: meta.thinkingTextBySource?.[sourceKey] ?? meta.thinkingText,
   };
@@ -603,8 +964,6 @@ export interface ChatMessage {
   skillLoads?: MessageSkillLoad[];
   /** Snapshot of task items active during this message (baked on completion) */
   taskItems?: Array<{id?: string; content: string; status: "pending" | "in_progress" | "completed" | "error"; blockedBy?: string[]}>;
-  /** Whether task updates for this message should remain pinned-only (Ralph exception) */
-  tasksPinned?: boolean;
   /** MCP snapshot for rendering Codex-style /mcp output */
   mcpSnapshot?: McpSnapshotView;
   /** Output tokens used in this message (baked on completion) */
@@ -629,6 +988,7 @@ export type OnToolStart = (
 /**
  * Tool complete event callback signature.
  * @param toolId - The tool call ID
+ * @param toolName - The tool name
  * @param output - The tool output
  * @param success - Whether the tool execution succeeded
  * @param error - Error message if failed
@@ -636,6 +996,7 @@ export type OnToolStart = (
  */
 export type OnToolComplete = (
   toolId: string,
+  toolName: string,
   output: unknown,
   success: boolean,
   error?: string,
@@ -718,9 +1079,6 @@ export interface ChatAppProps {
   /** Callback for streaming message updates */
   onStreamMessage?: (
     content: string,
-    onChunk: (chunk: string) => void,
-    onComplete: () => void,
-    onMeta?: (meta: StreamingMeta) => void,
     options?: import("./commands/registry.ts").StreamMessageOptions
   ) => void | Promise<void>;
   /** Callback when user exits the chat */
@@ -734,6 +1092,8 @@ export interface ChatAppProps {
   onInterrupt?: OnInterrupt;
   /** Callback when user confirms Ctrl+F background-agent termination. */
   onTerminateBackgroundAgents?: OnTerminateBackgroundAgents;
+  /** Set the streaming state in the index.ts layer (for bridge streaming). */
+  setStreamingState?: (isStreaming: boolean) => void;
   /** Placeholder text for input */
   placeholder?: string;
   /** Title for the chat window (deprecated, use header props instead) */
@@ -750,41 +1110,11 @@ export interface ChatAppProps {
   workingDir?: string;
   /** Suggestion text for header */
   suggestion?: string;
-  /**
-   * Register callback to receive tool start notifications.
-   * Called with a function that should be invoked when a tool starts.
-   */
-  registerToolStartHandler?: (handler: OnToolStart) => void;
-  /**
-   * Register callback to receive tool complete notifications.
-   * Called with a function that should be invoked when a tool completes.
-   */
-  registerToolCompleteHandler?: (handler: OnToolComplete) => void;
-  /**
-   * Register callback to receive skill invoked notifications.
-   * Called with a function that should be invoked when the SDK loads a skill.
-   */
-  registerSkillInvokedHandler?: (handler: OnSkillInvoked) => void;
-  /**
-   * Register callback to receive permission/HITL requests.
-   * Called with a function that should be invoked when permission is needed.
-   */
-  registerPermissionRequestHandler?: (handler: OnPermissionRequest) => void;
-  /**
-   * Register callback to receive Ctrl+C warning visibility changes.
-   * Called with a function that sets whether to show the warning.
-   */
-  registerCtrlCWarningHandler?: (handler: (show: boolean) => void) => void;
   /**
    * Callback to get the current session for slash commands.
    * Returns null if no session is active yet.
    */
   getSession?: () => import("../sdk/types.ts").Session | null;
-  /**
-   * Register callback to receive AskUserQuestion events from askUserNode.
-   * Called with a function that handles human_input_required signals from workflow graphs.
-   */
-  registerAskUserQuestionHandler?: (handler: OnAskUserQuestion) => void;
   /**
    * Callback to resume workflow execution with user's answer.
    * Called when the user responds to an askUserNode question in workflow mode.
@@ -796,10 +1126,6 @@ export interface ChatAppProps {
   modelOps?: ModelOperations;
   /** Callback to get model display info from the SDK client */
   getModelDisplayInfo?: (modelHint?: string) => Promise<import("../sdk/types.ts").ModelDisplayInfo>;
-  /** Parallel agents currently running (for tree view display) */
-  parallelAgents?: ParallelAgent[];
-  /** Register callback to receive parallel agent updates */
-  registerParallelAgentHandler?: (handler: (agents: ParallelAgent[]) => void) => void;
   /**
    * Factory function to create independent sub-agent sessions.
    * Delegates to client.createSession() for context isolation.
@@ -861,10 +1187,11 @@ export interface WorkflowChatState {
   specApproved: boolean;
   /** User feedback when rejecting (passed back to workflow) */
   feedback: string | null;
-  /** Ralph-specific workflow configuration (session ID, user prompt, etc.) */
-  ralphConfig?: {
+  /** Workflow-specific configuration (session ID, user prompt, workflow name, etc.) */
+  workflowConfig?: {
     userPrompt: string | null;
     sessionId?: string;
+    workflowName?: string;
   };
 }
 
@@ -910,13 +1237,13 @@ export interface MessageBubbleProps {
   /** Whether to hide loading indicator (when question dialog is active) */
   hideLoading?: boolean;
   /** Todo items to show inline during streaming */
-  todoItems?: Array<{content: string; status: "pending" | "in_progress" | "completed" | "error"}>;
+  todoItems?: Array<{id?: string; content: string; status: "pending" | "in_progress" | "completed" | "error"; blockedBy?: string[]}>;
   /** Whether task items are expanded (no truncation) */
   tasksExpanded?: boolean;
-  /** Whether task updates should be rendered inline for this message */
-  inlineTasksEnabled?: boolean;
-  /** Ralph session directory for persistent task list panel */
-  ralphSessionDir?: string | null;
+  /** Workflow session directory for persistent task list panel */
+  workflowSessionDir?: string | null;
+  /** Whether workflow execution is active */
+  workflowActive?: boolean;
   /** Whether the todo/task panel is visible (Ctrl+T toggle) */
   showTodoPanel?: boolean;
   /** Elapsed streaming time in milliseconds */
@@ -970,6 +1297,46 @@ export function createMessage(
   };
 }
 
+/**
+ * Finalize and remove a previous empty streaming assistant placeholder.
+ */
+export function reconcilePreviousStreamingPlaceholder(
+  messages: ChatMessage[],
+  previousStreamingId: string | null,
+): ChatMessage[] {
+  if (!previousStreamingId) return messages;
+
+  return messages
+    .map((msg) =>
+      msg.id === previousStreamingId && msg.streaming
+        ? { ...finalizeStreamingReasoningInMessage(msg), streaming: false }
+        : msg
+    )
+    .filter((msg) => !(msg.id === previousStreamingId && !msg.content.trim()));
+}
+
+export function shouldHideStaleSubagentToolPlaceholder(
+  message: ChatMessage,
+  activeMessageIds: ReadonlySet<string>,
+): boolean {
+  if (message.role !== "assistant") return false;
+  if (message.streaming) return false;
+  if (activeMessageIds.has(message.id)) return false;
+  if (message.content.trim().length > 0) return false;
+  if ((message.parallelAgents?.length ?? 0) > 0) return false;
+
+  const parts = message.parts ?? [];
+  if (parts.length === 0) return false;
+
+  for (const part of parts) {
+    if (part.type !== "tool") return false;
+    const toolPart = part as ToolPart;
+    if (!isSubagentToolName(toolPart.toolName)) return false;
+  }
+
+  return true;
+}
+
 /**
  * Returns a command-specific spinner verb override when needed.
  */
@@ -977,6 +1344,209 @@ export function getSpinnerVerbForCommand(commandName: string): string | undefine
   return commandName === "compact" ? "Compacting" : undefined;
 }
 
+/**
+ * Guard stream lifecycle handlers against stale cross-run events.
+ */
+export function shouldProcessStreamLifecycleEvent(
+  activeRunId: number | null,
+  eventRunId: number,
+): boolean {
+  return activeRunId !== null && activeRunId === eventRunId;
+}
+
+export function shouldFinalizeAgentOnlyStream(args: {
+  hasStreamingMessage: boolean;
+  isStreaming: boolean;
+  isAgentOnlyStream: boolean;
+  liveAgentCount: number;
+  messageAgentCount: number;
+}): boolean {
+  return args.hasStreamingMessage
+    && args.isStreaming
+    && args.isAgentOnlyStream
+    && (args.liveAgentCount > 0 || args.messageAgentCount > 0);
+}
+
+export function buildAgentContinuationPayload(args: {
+  agents: readonly ParallelAgent[];
+  fallbackText?: string;
+}): string | null {
+  const agentSections = args.agents
+    .filter((agent) => !agent.background)
+    .map((agent) => {
+      const rawResult = typeof agent.result === "string" && agent.result.trim().length > 0
+        ? agent.result
+        : agent.error?.trim();
+      if (!rawResult) {
+        return null;
+      }
+      const normalizedResult = normalizeMarkdownNewlines(rawResult).trim();
+      if (!normalizedResult) {
+        return null;
+      }
+      return `Sub-agent "${agent.name}" result:\n\n${normalizedResult}`;
+    })
+    .filter((section): section is string => section !== null);
+
+  if (agentSections.length > 0) {
+    return `[Sub-agent results]\n\n${agentSections.join("\n\n")}`;
+  }
+
+  const fallback = normalizeMarkdownNewlines(args.fallbackText ?? "").trim();
+  if (fallback.length > 0) {
+    return `[Sub-agent result]\n\n${fallback}`;
+  }
+
+  return null;
+}
+
+export function getAgentContinuationContractViolation(args: {
+  isAgentOnlyStream: boolean;
+  continuationPayload: string | null;
+}): string | null {
+  if (!args.isAgentOnlyStream || args.continuationPayload) {
+    return null;
+  }
+  return "Contract violation (INV-OUTPUT-001): missing @agent continuation input; turn terminated.";
+}
+
+export type ContractFailureTerminationReason =
+  | "agent_lifecycle_violation"
+  | "missing_agent_continuation"
+  | "compaction_terminal_error";
+
+const AGENT_OUT_OF_ORDER_VIOLATION_CODES = new Set<AgentLifecycleViolationCode>([
+  "OUT_OF_ORDER_EVENT",
+  "INVALID_TERMINAL_TRANSITION",
+]);
+
+export function emitAgentLifecycleContractObservability(args: {
+  provider?: string;
+  runId?: number;
+  code: AgentLifecycleViolationCode;
+  eventType: "stream.agent.start" | "stream.agent.update" | "stream.agent.complete";
+  agentId: string;
+  eventBus?: EventBus;
+}): void {
+  const provider = args.provider ?? "unknown";
+  incrementRuntimeParityCounter("workflow.runtime.parity.agent_lifecycle_contract_violation_total", {
+    provider,
+    code: args.code,
+    eventType: args.eventType,
+  });
+  if (AGENT_OUT_OF_ORDER_VIOLATION_CODES.has(args.code)) {
+    incrementRuntimeParityCounter("workflow.runtime.parity.agent_event_out_of_order_total", {
+      provider,
+      code: args.code,
+      eventType: args.eventType,
+    });
+  }
+  runtimeParityDebug("agent_lifecycle_contract_violation", {
+    provider,
+    runId: args.runId,
+    code: args.code,
+    eventType: args.eventType,
+    agentId: args.agentId,
+  });
+  pipelineError("EventBus", "agent_lifecycle_contract_violation", {
+    provider,
+    code: args.code,
+    eventType: args.eventType,
+    agentId: args.agentId,
+  });
+  args.eventBus?.reportError({
+    kind: "contract_violation",
+    eventType: args.eventType,
+    error: formatAgentLifecycleViolation(args),
+    eventData: { code: args.code, agentId: args.agentId, provider },
+  });
+}
+
+export function emitAgentMainContinuationObservability(args: {
+  provider?: string;
+  runId?: number;
+  result: "forwarded" | "missing";
+}): void {
+  const provider = args.provider ?? "unknown";
+  incrementRuntimeParityCounter("workflow.runtime.parity.agent_result_main_continuation_total", {
+    provider,
+    result: args.result,
+  });
+  runtimeParityDebug("agent_result_main_continuation", {
+    provider,
+    runId: args.runId,
+    result: args.result,
+  });
+}
+
+export function emitContractFailureTerminationObservability(args: {
+  provider?: string;
+  runId?: number;
+  reason: ContractFailureTerminationReason;
+  errorMessage: string;
+  code?: string;
+  eventType?: "stream.agent.start" | "stream.agent.update" | "stream.agent.complete";
+  agentId?: string;
+  eventBus?: EventBus;
+}): void {
+  const provider = args.provider ?? "unknown";
+  incrementRuntimeParityCounter("workflow.runtime.parity.turn_terminated_due_to_contract_error_total", {
+    provider,
+    reason: args.reason,
+    code: args.code,
+  });
+  runtimeParityDebug("contract_failure_turn_terminated", {
+    provider,
+    runId: args.runId,
+    reason: args.reason,
+    code: args.code,
+    eventType: args.eventType,
+    agentId: args.agentId,
+    errorMessage: args.errorMessage,
+  });
+  pipelineError("EventBus", "contract_failure_turn_terminated", {
+    provider,
+    reason: args.reason,
+    code: args.code,
+    errorMessage: args.errorMessage,
+  });
+  args.eventBus?.reportError({
+    kind: "contract_violation",
+    eventType: args.eventType ?? "unknown",
+    error: args.errorMessage,
+    eventData: { reason: args.reason, code: args.code, agentId: args.agentId, provider },
+  });
+}
+
+/**
+ * Format stream.session.truncation notifications for the UI.
+ */
+export function formatSessionTruncationMessage(
+  tokensRemoved: number,
+  messagesRemoved: number,
+): string {
+  return `${MISC.warning} Context truncated: ${tokensRemoved.toLocaleString()} tokens removed (${messagesRemoved} message${messagesRemoved === 1 ? "" : "s"})`;
+}
+
+/**
+ * Convert stream.session.compaction events into indicator state transitions.
+ */
+export function getAutoCompactionIndicatorState(
+  phase: "start" | "complete",
+  success?: boolean,
+  error?: string,
+): AutoCompactionIndicatorState {
+  if (phase === "start") {
+    return { status: "running" };
+  }
+
+  if (success === false) {
+    return { status: "error", errorMessage: error?.trim() || undefined };
+  }
+
+  return { status: "completed" };
+}
+
 /**
  * Format timestamp for display.
  */
@@ -996,12 +1566,6 @@ export function formatTimestamp(isoString: string): string {
 // DISPLAY CONSTANTS
 // ============================================================================
 
-/**
- * Number of most-recent messages to keep fully expanded in the chat view.
- * Older messages are auto-collapsed to single-line summaries.
- * Default: 4 (approximately two user-assistant exchanges).
- */
-export const EXPANDED_MESSAGE_COUNT = 4;
 
 // ============================================================================
 // LOADING INDICATOR COMPONENT
@@ -1009,10 +1573,6 @@ export const EXPANDED_MESSAGE_COUNT = 4;
 
 // SPINNER_FRAMES imported from ./constants/icons.ts
 
-// Re-export SPINNER_VERBS from constants for backward compatibility
-export { SPINNER_VERBS } from "./constants/index.ts";
-// Re-export getRandomVerb as getRandomSpinnerVerb for backward compatibility
-export { getRandomVerb as getRandomSpinnerVerb } from "./constants/index.ts";
 
 /**
  * Props for the LoadingIndicator component.
@@ -1056,8 +1616,9 @@ function formatTokenCount(tokens: number): string {
 export function LoadingIndicator({ speed = 100, verbOverride, elapsedMs, outputTokens, thinkingMs }: LoadingIndicatorProps): React.ReactNode {
   const themeColors = useThemeColors();
   const [frameIndex, setFrameIndex] = useState(0);
-  // Select random verb only on mount (empty dependency array)
-  const [verb] = useState(() => verbOverride ?? getRandomVerb());
+  // Derive verb from reasoning state: "Reasoning" when thinking, "Composing" otherwise.
+  // verbOverride (e.g. from /compact) still takes precedence.
+  const verb = verbOverride ?? (thinkingMs != null && thinkingMs > 0 ? "Reasoning" : "Composing");
 
   useEffect(() => {
     const interval = setInterval(() => {
@@ -1133,7 +1694,8 @@ interface CompletionSummaryProps {
  */
 export function CompletionSummary({ durationMs, outputTokens, thinkingMs }: CompletionSummaryProps): React.ReactNode {
   const themeColors = useThemeColors();
-  const [verb] = useState(() => getRandomCompletionVerb());
+  // Deterministic verb: "Reasoned" when thinking was used, "Composed" otherwise.
+  const verb = thinkingMs != null && thinkingMs >= 1000 ? "Reasoned" : "Composed";
   const [spinChar] = useState(() => getCompletionChar());
 
   const parts: string[] = [`${verb} for ${formatCompletionDuration(durationMs)}`];
@@ -1236,6 +1798,11 @@ interface InputScrollbarState {
   thumbSize: number;
 }
 
+interface DeferredCommandMessage {
+  content: string;
+  skipUserMessage?: boolean;
+}
+
 // ============================================================================
 // ATOMIC HEADER COMPONENT
 // ============================================================================
@@ -1302,8 +1869,6 @@ export function AtomicHeader({
  */
 function getRenderableAssistantParts(
   message: ChatMessage,
-  taskItemsToShow: TaskItem[] | undefined,
-  inlineTaskExpansion: boolean | undefined,
   isLastMessage: boolean,
   hideAskUserQuestion: boolean,
 ): Part[] {
@@ -1312,38 +1877,20 @@ function getRenderableAssistantParts(
   // Keep ToolPart state synchronized with the source toolCalls array.
   parts = syncToolCallsIntoParts(parts, message.toolCalls ?? [], message.timestamp, message.id);
 
-  // Only merge parallel agents into parts if agent parts don't already exist.
-  // During streaming, agents are already added to parts via applyStreamPartEvent.
-  // This check prevents duplicate agent trees from being rendered.
-  if (message.parallelAgents && message.parallelAgents.length > 0) {
-    const hasExistingAgentParts = parts.some((part) => part.type === "agent");
-    if (!hasExistingAgentParts) {
-      parts = mergeParallelAgentsIntoParts(
-        parts,
-        message.parallelAgents,
-        message.timestamp,
-        shouldGroupSubagentTrees(message, isLastMessage),
-      );
-    }
-  }
-
-  const shouldRenderInlineTasks = taskItemsToShow && taskItemsToShow.length > 0 && inlineTaskExpansion !== false;
-  const existingTaskIdx = parts.findIndex((p) => p.type === "task-list");
-  if (shouldRenderInlineTasks) {
-    const taskPart: TaskListPart = {
-      id: existingTaskIdx >= 0 ? parts[existingTaskIdx]!.id : `task-list-${message.id}`,
-      type: "task-list",
-      items: taskItemsToShow!,
-      expanded: inlineTaskExpansion ?? false,
-      createdAt: existingTaskIdx >= 0 ? parts[existingTaskIdx]!.createdAt : message.timestamp,
-    };
-    if (existingTaskIdx >= 0) {
-      parts[existingTaskIdx] = taskPart;
-    } else {
-      parts.push(taskPart);
-    }
-  } else if (existingTaskIdx >= 0) {
-    parts.splice(existingTaskIdx, 1);
+  const effectiveParallelAgents = message.parallelAgents;
+  if (effectiveParallelAgents && effectiveParallelAgents.length > 0) {
+    parts = mergeParallelAgentsIntoParts(
+      parts,
+      effectiveParallelAgents,
+      message.timestamp,
+      shouldGroupSubagentTrees(
+        {
+          ...message,
+          parallelAgents: effectiveParallelAgents,
+        },
+        isLastMessage,
+      ),
+    );
   }
 
   if (message.mcpSnapshot) {
@@ -1433,8 +1980,26 @@ function getRenderableAssistantParts(
 
   return parts;
 }
-export function MessageBubble({ message, isLast, syntaxStyle, hideAskUserQuestion = false, hideLoading = false, todoItems, tasksExpanded = false, inlineTasksEnabled = true, ralphSessionDir, showTodoPanel = true, elapsedMs, collapsed = false, streamingMeta }: MessageBubbleProps): React.ReactNode {
+export function MessageBubble({
+  message,
+  isLast,
+  syntaxStyle,
+  hideAskUserQuestion = false,
+  hideLoading = false,
+  todoItems,
+  tasksExpanded = false,
+  workflowSessionDir,
+  workflowActive = false,
+  showTodoPanel = true,
+  elapsedMs,
+  collapsed = false,
+  streamingMeta,
+}: MessageBubbleProps): React.ReactNode {
   const themeColors = useThemeColors();
+  const persistentTaskPanelSessionDir = isLast && showTodoPanel && workflowSessionDir
+    ? workflowSessionDir
+    : null;
+  const shouldShowPersistentTaskPanel = persistentTaskPanelSessionDir !== null;
 
   // Collapsed mode: show compact single-line summary for each message
   // Spacing: user messages sit tight above their reply; assistant messages
@@ -1496,11 +2061,12 @@ export function MessageBubble({ message, isLast, syntaxStyle, hideAskUserQuestio
           </text>
         </box>
 
-        {/* Ralph persistent task list - also shown after user messages */}
-        {isLast && ralphSessionDir && showTodoPanel && (
+        {/* Workflow persistent task list - also shown after user messages */}
+        {persistentTaskPanelSessionDir && (
           <TaskListPanel
-            sessionDir={ralphSessionDir}
+            sessionDir={persistentTaskPanelSessionDir}
             expanded={tasksExpanded}
+            workflowActive={workflowActive}
           />
         )}
       </box>
@@ -1509,24 +2075,21 @@ export function MessageBubble({ message, isLast, syntaxStyle, hideAskUserQuestio
 
   // Assistant message: parts-based rendering only
   if (message.role === "assistant") {
-    const shouldRenderInlineTasks = inlineTasksEnabled && !message.tasksPinned;
-    const taskItemsToShow = shouldRenderInlineTasks
-      ? (message.streaming ? todoItems : message.taskItems)
-      : undefined;
-    const inlineTaskExpansion = shouldRenderInlineTasks ? (tasksExpanded || undefined) : false;
+    const assistantParts = getRenderableAssistantParts(
+      message,
+      Boolean(isLast),
+      hideAskUserQuestion,
+    );
     const renderableMessage = {
       ...message,
-      parts: getRenderableAssistantParts(
-        message,
-        taskItemsToShow,
-        inlineTaskExpansion,
-        Boolean(isLast),
-        hideAskUserQuestion,
-      ),
+      parts: shouldShowPersistentTaskPanel
+        ? assistantParts.filter((part) => part.type !== "task-list")
+        : assistantParts,
     };
 
     // Detect active background agents on this message
-    const hasActiveBackgroundAgents = getActiveBackgroundAgents(message.parallelAgents ?? []).length > 0;
+    const effectiveParallelAgents = message.parallelAgents;
+    const hasActiveBackgroundAgents = getActiveBackgroundAgents(effectiveParallelAgents ?? []).length > 0;
     const liveTaskItems = message.streaming ? todoItems : message.taskItems;
     const showLoadingIndicator = shouldShowMessageLoadingIndicator(message, liveTaskItems);
 
@@ -1539,24 +2102,31 @@ export function MessageBubble({ message, isLast, syntaxStyle, hideAskUserQuestio
       >
         <MessageBubbleParts message={renderableMessage} syntaxStyle={syntaxStyle} />
 
-        {/* Ralph persistent task list - pinned above streaming text in last message */}
-        {isLast && ralphSessionDir && showTodoPanel && (
+        {/* Workflow persistent task list - pinned above streaming text in last message */}
+        {persistentTaskPanelSessionDir && (
           <TaskListPanel
-            sessionDir={ralphSessionDir}
+            sessionDir={persistentTaskPanelSessionDir}
             expanded={tasksExpanded}
+            workflowActive={workflowActive}
           />
         )}
 
+        {/* Inline cancellation indicator — rendered below message parts, above spinner */}
+        {message.wasInterrupted && !message.streaming && (
+          <box marginTop={SPACING.ELEMENT}>
+            <text style={{ fg: themeColors.error }}>{STATUS.active} Operation cancelled by user</text>
+          </box>
+        )}
+
         {/* Loading spinner while work is active (stops once task progress is fully complete). */}
         {showLoadingIndicator && !hideLoading && (
           <box flexDirection="row" alignItems="flex-start" marginTop={renderableMessage.parts.length > 0 ? SPACING.ELEMENT : SPACING.NONE}>
             <text>
               <LoadingIndicator
-                speed={120}
                 verbOverride={message.spinnerVerb}
                 elapsedMs={elapsedMs}
-                outputTokens={streamingMeta?.outputTokens}
-                thinkingMs={streamingMeta?.thinkingMs}
+                outputTokens={streamingMeta?.outputTokens ?? message.outputTokens}
+                thinkingMs={streamingMeta?.thinkingMs ?? message.thinkingMs}
               />
             </text>
           </box>
@@ -1569,6 +2139,7 @@ export function MessageBubble({ message, isLast, syntaxStyle, hideAskUserQuestio
           </box>
         )}
 
+
       </box>
     );
   }
@@ -1615,6 +2186,7 @@ export function ChatApp({
   onResetSession,
   onInterrupt,
   onTerminateBackgroundAgents,
+  setStreamingState,
   placeholder: _placeholder = "Type a message...",
   title: _title,
   syntaxStyle: _syntaxStyle,
@@ -1623,19 +2195,11 @@ export function ChatApp({
   tier = "",
   workingDir = "~/",
   suggestion: _suggestion,
-  registerToolStartHandler,
-  registerToolCompleteHandler,
-  registerSkillInvokedHandler,
-  registerPermissionRequestHandler,
-  registerCtrlCWarningHandler,
   getSession,
-  registerAskUserQuestionHandler,
   onWorkflowResumeWithAnswer,
   agentType,
   modelOps,
   getModelDisplayInfo,
-  parallelAgents: initialParallelAgents = [],
-  registerParallelAgentHandler,
   createSubagentSession,
   initialPrompt,
   onModelChange,
@@ -1666,9 +2230,11 @@ export function ChatApp({
   // Ctrl+F confirmation state for terminating active background agents.
   const [backgroundTerminationCount, setBackgroundTerminationCount] = useState(0);
   const [ctrlFPressed, setCtrlFPressed] = useState(false);
+  const backgroundTerminationCountRef = useRef(0);
   const backgroundTerminationTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const backgroundTerminationInFlightRef = useRef(false);
   const clearBackgroundTerminationConfirmation = useCallback(() => {
+    backgroundTerminationCountRef.current = 0;
     setBackgroundTerminationCount(0);
     setCtrlFPressed(false);
     if (backgroundTerminationTimeoutRef.current) {
@@ -1701,15 +2267,34 @@ export function ChatApp({
     }
   }, [renderer]);
 
-  // Streaming state hook for tool executions and pending questions
-  const streamingState = useStreamingState();
+  // Pending questions queue for HITL flow
+  const [, setPendingQuestions] = useState<UserQuestion[]>([]);
+
+  const addPendingQuestion = useCallback((question: UserQuestion) => {
+    setPendingQuestions((prev) => [...prev, question]);
+  }, []);
+
+  const removePendingQuestion = useCallback((): UserQuestion | undefined => {
+    let removed: UserQuestion | undefined;
+    setPendingQuestions((prev) => {
+      if (prev.length === 0) return prev;
+      [removed] = prev;
+      return prev.slice(1);
+    });
+    return removed;
+  }, []);
 
   // Message queue for queuing messages during streaming
   const messageQueue = useMessageQueue();
+  // Internal queue for command-driven sends (e.g., workflow runtime calls).
+  // Unlike user queue entries, these are not shown in the queued-message UI.
+  const deferredCommandQueueRef = useRef<DeferredCommandMessage[]>([]);
 
   // Transcript mode: full-screen detailed transcript view (ctrl+o toggle)
   const [transcriptMode, setTranscriptMode] = useState(false);
 
+  // Verbose mode: shows timestamps, model info on messages (ctrl+e toggle)
+  const { toggle: toggleVerbose } = useVerboseMode();
 
   // State for showing user question dialog
   const [activeQuestion, setActiveQuestion] = useState<UserQuestion | null>(null);
@@ -1746,6 +2331,10 @@ export function ChatApp({
   const { theme, toggleTheme, setTheme } = useTheme();
   const themeColors = theme.colors;
 
+  // Event bus — used to publish sub-agent stream events and flush pending
+  // batched text deltas before stream finalization.
+  const { bus: eventBus, dispatcher: batchDispatcher } = useEventBusContext();
+
   // Component-scoped SyntaxStyle for textarea slash command and @ mention highlighting
   const inputSyntaxStyleRef = useRef<SyntaxStyle | null>(null);
   const commandStyleIdRef = useRef<number>(0);
@@ -1777,17 +2366,14 @@ export function ChatApp({
   );
 
   // State for parallel agents display
-  const [parallelAgents, setParallelAgents] = useState<ParallelAgent[]>(initialParallelAgents);
+  const [parallelAgents, setParallelAgents] = useState<ParallelAgent[]>([]);
   // Compaction state: stores summary text after /compact for Ctrl+O history
   const [compactionSummary, setCompactionSummary] = useState<string | null>(null);
   const [showCompactionHistory, setShowCompactionHistory] = useState(false);
-  const [autoCompactionIndicator, setAutoCompactionIndicator] = useState<AutoCompactionIndicatorState>(
-    AUTO_COMPACTION_INDICATOR_IDLE_STATE
-  );
+  const [isAutoCompacting, setIsAutoCompacting] = useState(false);
   const autoCompactionIndicatorRef = useRef<AutoCompactionIndicatorState>(
-    AUTO_COMPACTION_INDICATOR_IDLE_STATE
+    { status: "idle" }
   );
-  const autoCompactionTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   // TodoWrite persistent state
   const [todoItems, setTodoItems] = useState<NormalizedTodoItem[]>([]);
   const todoItemsRef = useRef<NormalizedTodoItem[]>([]);
@@ -1796,24 +2382,32 @@ export function ChatApp({
   // Resolver for streamAndWait: when set, handleComplete resolves the Promise instead of processing the queue
   const streamCompletionResolverRef = useRef<((result: import("./commands/registry.ts").StreamResult) => void) | null>(null);
   // Resolver for waitForUserInput: when set, handleSubmit resolves the Promise with the user's prompt
-  const waitForUserInputResolverRef = useRef<{ resolve: (prompt: string) => void; reject: (reason: Error) => void } | null>(null);
+  const waitForUserInputResolverRef = useRef<WorkflowInputResolver | null>(null);
   // When true, streaming chunks are accumulated but NOT rendered in the assistant message (for hidden workflow steps)
   const hideStreamContentRef = useRef(false);
   const [showTodoPanel, setShowTodoPanel] = useState(true);
   // Whether task list items are expanded (full content, no truncation)
   const [tasksExpanded, _setTasksExpanded] = useState(false);
-  // Ralph workflow persistent task list
-  const [ralphSessionDir, setRalphSessionDir] = useState<string | null>(null);
-  const ralphSessionDirRef = useRef<string | null>(null);
-  const [ralphSessionId, setRalphSessionId] = useState<string | null>(null);
-  const ralphSessionIdRef = useRef<string | null>(null);
-  // Known ralph task IDs from the planning phase.
+  // Workflow persistent task list
+  const [workflowSessionDir, setWorkflowSessionDir] = useState<string | null>(null);
+  const workflowSessionDirRef = useRef<string | null>(null);
+  const [workflowSessionId, setWorkflowSessionId] = useState<string | null>(null);
+  const workflowSessionIdRef = useRef<string | null>(null);
+  // Known workflow task IDs from the planning phase.
   // Used to guard TodoWrite persistence: only updates whose items match
   // these IDs are written to tasks.json, preventing sub-agent overwrites.
-  const ralphTaskIdsRef = useRef<Set<string>>(new Set());
+  const workflowTaskIdsRef = useRef<Set<string>>(new Set());
   // Tracks started tool names by toolCallId so completion handlers can
   // safely identify TodoWrite payloads (and ignore unrelated `input.todos`).
   const toolNameByIdRef = useRef<Map<string, string>>(new Map());
+  // Tracks the message a tool call belongs to so late tool.complete events can
+  // still be routed after streamingMessageIdRef is cleared.
+  const toolMessageIdByIdRef = useRef<Map<string, string>>(new Map());
+  // Tracks the message an agent belongs to so updates stay attached to the
+  // originating transcript location instead of drifting to the newest message.
+  const agentMessageIdByIdRef = useRef<Map<string, string>>(new Map());
+  // Tracks strict lifecycle ordering for each agent at runtime.
+  const agentLifecycleLedgerRef = useRef(createAgentLifecycleLedger());
   // State for input textarea scrollbar (shown only when input overflows)
   const [inputScrollbar, setInputScrollbar] = useState<InputScrollbarState>({
     visible: false,
@@ -1845,6 +2439,16 @@ export function ChatApp({
 
   // Refs for streaming message updates
   const streamingMessageIdRef = useRef<string | null>(null);
+  // Tracks the runId of the currently active stream.session.start event so
+  // stale lifecycle events from a prior run do not finalize a new message.
+  const activeStreamRunIdRef = useRef<number | null>(null);
+  // Captures the latest normalized turn finish reason so session.idle can
+  // decide whether to continue the parent loop or finalize the stream.
+  const lastTurnFinishReasonRef = useRef<SessionLoopFinishReason | null>(null);
+  // Persists the message ID after handleStreamComplete clears streamingMessageIdRef,
+  // so late-arriving bus events (stream.usage, stream.thinking.complete) can still
+  // bake metadata onto the completed message.
+  const lastStreamedMessageIdRef = useRef<string | null>(null);
   // Ref to track message ID for background agent updates after stream ends
   const backgroundAgentMessageIdRef = useRef<string | null>(null);
   // Ref to track when streaming started for duration calculation
@@ -1852,6 +2456,8 @@ export function ChatApp({
   // Ref to track streaming state synchronously (for immediate check in handleSubmit)
   // This avoids race conditions where React state hasn't updated yet
   const isStreamingRef = useRef(false);
+  // Ref to track workflow active state synchronously for async callbacks
+  const workflowActiveRef = useRef(false);
   // Ref to keep a synchronous copy of streaming meta for baking into message on completion
   const streamingMetaRef = useRef<StreamingMeta | null>(null);
   // Source keys closed by stream finalize/interrupt/error.
@@ -1874,18 +2480,20 @@ export function ChatApp({
   // Tracks whether the current stream is an @mention-only stream (no SDK onComplete).
   // Prevents the agent-only completion path from firing for SDK-spawned sub-agents.
   const isAgentOnlyStreamRef = useRef(false);
-  // Stream generation counter — incremented each time a new stream starts.
-  // handleComplete closures capture the generation at creation time and skip
-  // if it no longer matches, preventing stale callbacks from corrupting a
-  // newer stream's state (e.g., after round-robin injection).
-  const streamGenerationRef = useRef(0);
   // Ref to track whether any tool call is currently running (synchronous check
   // for keyboard handler to avoid stale closure issues with React state).
   const hasRunningToolRef = useRef(false);
+  // Set of blocking tool IDs currently running in this stream.
+  // Skill-loading tools are intentionally excluded because some SDKs do not
+  // emit a matching complete event for them.
+  const runningBlockingToolIdsRef = useRef<Set<string>>(new Set());
   // Track active ask_question tools so Enter can defer submit without clearing input.
   const runningAskQuestionToolIdsRef = useRef<Set<string>>(new Set());
   // Counter to trigger effect when tools complete (used for deferred completion logic)
   const [toolCompletionVersion, setToolCompletionVersion] = useState(0);
+  // Version counter that forces parallel-agent message sync when anchor refs/maps
+  // change without a parallelAgents state transition.
+  const [agentAnchorSyncVersion, setAgentAnchorSyncVersion] = useState(0);
   // Incremented when message-window overflow eviction happens.
   // Tracks which skills have been loaded in the current session to avoid duplicate indicators.
   const loadedSkillsRef = useRef<Set<string>>(new Set());
@@ -1893,6 +2501,81 @@ export function ChatApp({
   const scrollboxRef = useRef<ScrollBoxRenderable>(null);
   // Ref for deferred queue dispatch without circular callback deps
   const dispatchQueuedMessageRef = useRef<(queuedMessage: QueuedMessage) => void>(() => {});
+  // Ref for dispatching deferred command messages without circular callback deps
+  const dispatchDeferredCommandMessageRef = useRef<(message: DeferredCommandMessage) => void>(() => {});
+  // Serialize background-update session.send calls to preserve ordering.
+  const backgroundAgentSendChainRef = useRef<Promise<void>>(Promise.resolve());
+  const pendingBackgroundUpdatesRef = useRef<string[]>([]);
+  const backgroundUpdateFlushInFlightRef = useRef(false);
+  const backgroundProgressSnapshotRef = useRef<Map<string, {
+    toolUses: number;
+    currentTool?: string;
+  }>>(new Map());
+
+  const setStreamingMessageId = useCallback((messageId: string | null): void => {
+    if (streamingMessageIdRef.current === messageId) return;
+    streamingMessageIdRef.current = messageId;
+    setAgentAnchorSyncVersion((version) => version + 1);
+  }, []);
+
+  const setLastStreamedMessageId = useCallback((messageId: string | null): void => {
+    if (lastStreamedMessageIdRef.current === messageId) return;
+    lastStreamedMessageIdRef.current = messageId;
+    setAgentAnchorSyncVersion((version) => version + 1);
+  }, []);
+
+  const setBackgroundAgentMessageId = useCallback((messageId: string | null): void => {
+    if (backgroundAgentMessageIdRef.current === messageId) return;
+    backgroundAgentMessageIdRef.current = messageId;
+    setAgentAnchorSyncVersion((version) => version + 1);
+  }, []);
+
+  const setAgentMessageBinding = useCallback((agentId: string, messageId: string): void => {
+    if (agentMessageIdByIdRef.current.get(agentId) === messageId) return;
+    agentMessageIdByIdRef.current.set(agentId, messageId);
+    setAgentAnchorSyncVersion((version) => version + 1);
+  }, []);
+
+  const deleteAgentMessageBinding = useCallback((agentId: string): void => {
+    if (!agentMessageIdByIdRef.current.has(agentId)) return;
+    agentMessageIdByIdRef.current.delete(agentId);
+    setAgentAnchorSyncVersion((version) => version + 1);
+  }, []);
+
+  const asSessionLoopFinishReason = useCallback((value: unknown): SessionLoopFinishReason | null => {
+    if (typeof value !== "string") {
+      return null;
+    }
+    const token = value.trim();
+    if (
+      token === "tool-calls"
+      || token === "stop"
+      || token === "max-tokens"
+      || token === "max-turns"
+      || token === "error"
+      || token === "unknown"
+    ) {
+      return token;
+    }
+    return null;
+  }, []);
+
+  const hasPendingTaskResultContract = useCallback((): boolean => {
+    return todoItemsRef.current.some((task) => {
+      const isTerminalStatus = task.status === "completed" || task.status === "error";
+      if (!isTerminalStatus || task.taskResult) {
+        return false;
+      }
+
+      const canonicalId = task.identity?.canonicalId;
+      const hasProviderBindings = Boolean(
+        task.identity?.providerBindings
+        && Object.keys(task.identity.providerBindings).length > 0,
+      );
+
+      return Boolean(canonicalId) || hasProviderBindings;
+    });
+  }, []);
 
   const clearDeferredCompletion = useCallback(() => {
     pendingCompleteRef.current = null;
@@ -1908,11 +2591,14 @@ export function ChatApp({
     setStreamingMeta(null);
   }, []);
 
-  const finalizeThinkingSourceTracking = useCallback(() => {
+  const finalizeThinkingSourceTracking = useCallback((options?: {
+    preserveStreamingMeta?: boolean;
+  }) => {
+    const previousMeta = streamingMetaRef.current;
     const previousClosedSources = closedThinkingSourcesRef.current;
     const mergedClosedSources = mergeClosedThinkingSources(
       previousClosedSources,
-      streamingMetaRef.current,
+      previousMeta,
     );
     for (const sourceKey of mergedClosedSources) {
       if (!previousClosedSources.has(sourceKey)) {
@@ -1920,6 +2606,19 @@ export function ChatApp({
       }
     }
     closedThinkingSourcesRef.current = mergedClosedSources;
+
+    if (options?.preserveStreamingMeta && previousMeta) {
+      const preservedMeta: StreamingMeta = {
+        outputTokens: previousMeta.outputTokens,
+        thinkingMs: previousMeta.thinkingMs,
+        thinkingText: "",
+      };
+      const hasPreservedCounters = preservedMeta.outputTokens > 0 || preservedMeta.thinkingMs > 0;
+      streamingMetaRef.current = hasPreservedCounters ? preservedMeta : null;
+      setStreamingMeta(hasPreservedCounters ? preservedMeta : null);
+      return;
+    }
+
     streamingMetaRef.current = null;
     setStreamingMeta(null);
   }, []);
@@ -1952,6 +2651,21 @@ export function ChatApp({
   }, []);
 
   const continueQueuedConversation = useCallback(() => {
+    // Command-driven messages (workflow/runtime) dispatch first and stay out of
+    // the visible queued-message UI.
+    if (
+      shouldDispatchQueuedMessage({
+        isStreaming: isStreamingRef.current,
+        runningAskQuestionToolCount: runningAskQuestionToolIdsRef.current.size,
+      })
+    ) {
+      const nextDeferred = deferredCommandQueueRef.current.shift();
+      if (nextDeferred) {
+        dispatchDeferredCommandMessageRef.current(nextDeferred);
+        return;
+      }
+    }
+
     dispatchNextQueuedMessage<QueuedMessage>(
       () => messageQueue.dequeue(),
       (queuedMessage: QueuedMessage) => {
@@ -1966,25 +2680,134 @@ export function ChatApp({
     );
   }, [messageQueue]);
 
-  // Create macOS-style scroll acceleration for smooth mouse wheel scrolling
-  const scrollAcceleration = useMemo(() => new MacOSScrollAccel(), []);
+  const resolveAgentScopedMessageId = useCallback((agentId?: string): string | null => {
+    if (!agentId) {
+      return streamingMessageIdRef.current ?? lastStreamedMessageIdRef.current;
+    }
 
-  /**
-   * Update chat messages. Alias for setMessages kept to minimise call-site churn.
-   */
-  const setMessagesWindowed = useCallback((next: React.SetStateAction<ChatMessage[]>) => {
-    setMessages(next);
-  }, []);
+    const mappedMessageId = agentMessageIdByIdRef.current.get(agentId);
+    if (mappedMessageId) {
+      return mappedMessageId;
+    }
 
-  const hasLiveLoadingIndicator = useMemo(
-    () => hasAnyLiveLoadingIndicator(messages, todoItems),
-    [messages, todoItems],
-  );
+    const scopedAgent = parallelAgentsRef.current.find((agent) => agent.id === agentId);
+    const shouldPreferBackgroundMessage = scopedAgent ? isBackgroundAgent(scopedAgent) : false;
 
-  // Live elapsed time counter for the visible loading indicator.
-  useEffect(() => {
-    if (!hasLiveLoadingIndicator || !streamingStartRef.current) {
-      setStreamingElapsedMs(0);
+    if (shouldPreferBackgroundMessage) {
+      return (
+        backgroundAgentMessageIdRef.current
+        ?? streamingMessageIdRef.current
+        ?? lastStreamedMessageIdRef.current
+      );
+    }
+
+    return streamingMessageIdRef.current ?? lastStreamedMessageIdRef.current;
+  }, []);
+
+  const flushPendingBackgroundUpdatesToAgent = useCallback(() => {
+    if (!shouldStartBackgroundUpdateFlush({
+      hasFlushInFlight: backgroundUpdateFlushInFlightRef.current,
+      isStreaming: isStreamingRef.current,
+      pendingUpdateCount: pendingBackgroundUpdatesRef.current.length,
+    })) {
+      return;
+    }
+
+    const session = getSession?.();
+    if (!session?.send) return;
+
+    const updates = pendingBackgroundUpdatesRef.current.splice(0);
+    if (updates.length === 0) return;
+
+    const payload = `[Background updates]\n\n${updates.join("\n\n")}`;
+    let sendSucceeded = false;
+    backgroundUpdateFlushInFlightRef.current = true;
+    backgroundAgentSendChainRef.current = backgroundAgentSendChainRef.current
+      .catch(() => undefined)
+      .then(async () => {
+        try {
+          await session.send(payload);
+          sendSucceeded = true;
+        } catch (error) {
+          pendingBackgroundUpdatesRef.current.unshift(...updates);
+          console.debug("[background-update] failed to send to agent:", error);
+        }
+      })
+      .finally(() => {
+        backgroundUpdateFlushInFlightRef.current = false;
+        if (shouldScheduleBackgroundUpdateFollowUpFlush({
+          sendSucceeded,
+          isStreaming: isStreamingRef.current,
+          pendingUpdateCount: pendingBackgroundUpdatesRef.current.length,
+        })) {
+          queueMicrotask(() => {
+            flushPendingBackgroundUpdatesToAgent();
+          });
+        }
+      });
+  }, [getSession]);
+
+  // Create macOS-style scroll acceleration for smooth mouse wheel scrolling
+  const scrollAcceleration = useMemo(() => new MacOSScrollAccel(), []);
+
+  /**
+   * Update chat messages. Alias for setMessages kept to minimise call-site churn.
+   */
+  const setMessagesWindowed = useCallback((next: React.SetStateAction<ChatMessage[]>) => {
+    setMessages(next);
+  }, []);
+
+  const sendBackgroundMessageToAgent = useCallback((content: string) => {
+    const trimmed = content.trim();
+    if (!trimmed) return;
+
+    pendingBackgroundUpdatesRef.current.push(trimmed);
+    flushPendingBackgroundUpdatesToAgent();
+  }, [flushPendingBackgroundUpdatesToAgent]);
+
+
+  useEffect(() => {
+    if (!isStreaming) {
+      flushPendingBackgroundUpdatesToAgent();
+    }
+  }, [isStreaming, flushPendingBackgroundUpdatesToAgent]);
+
+  // Process background-agent state by updating the baked message directly.
+  const applyBackgroundAgentUpdate = useCallback((messageId: string, agents: ParallelAgent[]) => {
+    setMessagesWindowed((prev: ChatMessage[]) =>
+      prev.map((msg: ChatMessage, index: number) =>
+        msg.id === messageId
+          ? applyStreamPartEvent(msg, {
+              type: "parallel-agents",
+              agents,
+              isLastMessage: index === prev.length - 1,
+            })
+          : msg
+      )
+    );
+    // Clean up when all background agents reach terminal state
+    if (getActiveBackgroundAgents(agents).length === 0) {
+      setBackgroundAgentMessageId(null);
+      // Preserve streamingStartRef during workflow execution so the
+      // "Running workflow… (Xs)" timer survives agent completions.
+      if (!workflowActiveRef.current) {
+        streamingStartRef.current = null;
+      }
+    }
+  }, [setBackgroundAgentMessageId, setMessagesWindowed]);
+
+  const applyBackgroundAgentUpdateRef = useRef(applyBackgroundAgentUpdate);
+  applyBackgroundAgentUpdateRef.current = applyBackgroundAgentUpdate;
+
+  const hasLiveLoadingIndicator = useMemo(
+    () => hasAnyLiveLoadingIndicator(messages, todoItems),
+    [messages, todoItems],
+  );
+
+  // Live elapsed time counter for the visible loading indicator.
+  useEffect(() => {
+    if (!hasLiveLoadingIndicator || !streamingStartRef.current) {
+      setStreamingElapsedMs(0);
       return;
     }
     setStreamingElapsedMs(Math.floor((Date.now() - streamingStartRef.current) / 1000) * 1000);
@@ -2021,33 +2844,33 @@ export function ChatApp({
     clearBackgroundTerminationConfirmation,
   ]);
 
-  // Keep ralph session refs in sync with state
+  // Keep workflow session refs in sync with state
   useEffect(() => {
-    ralphSessionDirRef.current = ralphSessionDir;
-  }, [ralphSessionDir]);
+    workflowSessionDirRef.current = workflowSessionDir;
+  }, [workflowSessionDir]);
   useEffect(() => {
-    ralphSessionIdRef.current = ralphSessionId;
-  }, [ralphSessionId]);
+    workflowSessionIdRef.current = workflowSessionId;
+  }, [workflowSessionId]);
 
   /**
-   * Check whether a TodoWrite payload is a ralph task update (shares IDs
-   * with the known ralph planning-phase tasks). Returns false when the
+   * Check whether a TodoWrite payload is a workflow task update (shares IDs
+   * with the known workflow planning-phase tasks). Returns false when the
    * incoming items are from a sub-agent's independent todo list, which
-   * should NOT overwrite ralph's tasks.json.
+   * should NOT overwrite workflow's tasks.json.
    */
-  const isRalphTaskUpdate = useCallback((
+  const isWorkflowTaskUpdate = useCallback((
     todos: NormalizedTodoItem[],
     previousTodos: readonly NormalizedTodoItem[] = todoItemsRef.current,
   ): boolean => {
-    return hasRalphTaskIdOverlap(todos, ralphTaskIdsRef.current, previousTodos);
+    return hasWorkflowTaskIdOverlap(todos, workflowTaskIdsRef.current, previousTodos);
   }, []);
 
   /**
    * Clear stale TodoWrite state when starting a new stream, except during
-   * active /ralph workflows where task continuity must persist across turns.
+   * active workflow sessions where task continuity must persist across turns.
    */
   const resetTodoItemsForNewStream = useCallback(() => {
-    if (ralphSessionIdRef.current) return;
+    if (workflowSessionIdRef.current) return;
     todoItemsRef.current = [];
     setTodoItems([]);
   }, []);
@@ -2064,38 +2887,66 @@ export function ChatApp({
     todoItemsRef.current = updated;
     setTodoItems(updated);
 
-    // Persist to tasks.json only if the current items are ralph tasks
-    if (ralphSessionIdRef.current && isRalphTaskUpdate(updated)) {
-      void saveTasksToActiveSession(updated, ralphSessionIdRef.current);
+    // Persist to tasks.json only if the current items are workflow tasks
+    if (workflowSessionIdRef.current && isWorkflowTaskUpdate(updated)) {
+      void saveTasksToActiveSession(updated, workflowSessionIdRef.current);
     }
 
     return snapshotTaskItems(updated) as TaskItem[] | undefined;
-  }, [isRalphTaskUpdate]);
-
-  const clearAutoCompactionTimeout = useCallback(() => {
-    if (autoCompactionTimeoutRef.current) {
-      clearTimeout(autoCompactionTimeoutRef.current);
-      autoCompactionTimeoutRef.current = null;
-    }
-  }, []);
+  }, [isWorkflowTaskUpdate]);
 
   const applyAutoCompactionIndicator = useCallback((next: AutoCompactionIndicatorState) => {
-    clearAutoCompactionTimeout();
     autoCompactionIndicatorRef.current = next;
-    setAutoCompactionIndicator(next);
 
-    if (next.status === "completed" || next.status === "error") {
-      autoCompactionTimeoutRef.current = setTimeout(() => {
-        autoCompactionIndicatorRef.current = AUTO_COMPACTION_INDICATOR_IDLE_STATE;
-        setAutoCompactionIndicator(AUTO_COMPACTION_INDICATOR_IDLE_STATE);
-        autoCompactionTimeoutRef.current = null;
-      }, AUTO_COMPACTION_RESULT_VISIBILITY_MS);
+    if (next.status === "running") {
+      setIsAutoCompacting(true);
+      // Override spinner verb on current streaming message so the existing
+      // LoadingIndicator above the chatbox shows "Compacting" instead of
+      // rendering a separate indicator below.
+      const messageId = streamingMessageIdRef.current;
+      if (messageId) {
+        setMessagesWindowed((prev) =>
+          prev.map((msg) =>
+            msg.id === messageId ? { ...msg, spinnerVerb: "Compacting" } : msg
+          )
+        );
+      }
+    } else if (next.status === "completed") {
+      setIsAutoCompacting(false);
+      // Compaction succeeded: persist current messages as summary to history buffer,
+      // then clear chat and create a fresh streaming message so the active stream
+      // continues seamlessly into the new (compacted) context.
+      const newMsg = createMessage("assistant", "", true);
+      setStreamingMessageId(newMsg.id);
+      setMessagesWindowed((prev) => {
+        clearHistoryBuffer();
+        const summaryText = `[Auto-compaction completed at ${new Date().toISOString()}] Context was automatically compacted to reduce token usage.`;
+        appendCompactionSummary(summaryText);
+        setCompactionSummary(summaryText);
+        setShowCompactionHistory(false);
+        return [newMsg];
+      });
+    } else if (next.status === "error") {
+      setIsAutoCompacting(false);
+      // Clear the "Compacting" verb override so the spinner falls back to default
+      const messageId = streamingMessageIdRef.current;
+      if (messageId) {
+        setMessagesWindowed((prev) =>
+          prev.map((msg) =>
+            msg.id === messageId && msg.spinnerVerb === "Compacting"
+              ? { ...msg, spinnerVerb: undefined }
+              : msg
+          )
+        );
+      }
+    } else {
+      setIsAutoCompacting(false);
     }
-  }, [clearAutoCompactionTimeout]);
+  }, [setStreamingMessageId]);
 
   const stopSharedStreamState = useCallback((options?: {
     preserveStreamingStart?: boolean;
-    resetStreamingStateHook?: boolean;
+    preserveStreamingMeta?: boolean;
   }) => {
     const next = createStoppedStreamControlState(
       {
@@ -2110,18 +2961,25 @@ export function ChatApp({
       { preserveStreamingStart: options?.preserveStreamingStart },
     );
 
-    streamingMessageIdRef.current = next.streamingMessageId;
+    setStreamingMessageId(next.streamingMessageId);
     streamingStartRef.current = next.streamingStart;
-    streamingMetaRef.current = null;
+    if (!options?.preserveStreamingMeta) {
+      streamingMetaRef.current = null;
+    }
     pendingCompleteRef.current = null;
     isAgentOnlyStreamRef.current = next.isAgentOnlyStream;
     isStreamingRef.current = next.isStreaming;
     hasRunningToolRef.current = next.hasRunningTool;
-    if (options?.resetStreamingStateHook !== false) {
-      runningAskQuestionToolIdsRef.current.clear();
+    if (!next.isStreaming) {
+      activeStreamRunIdRef.current = null;
+      lastTurnFinishReasonRef.current = null;
     }
+    runningBlockingToolIdsRef.current.clear();
+    runningAskQuestionToolIdsRef.current.clear();
     setIsStreaming(next.isStreaming);
-    setStreamingMeta(null);
+    if (!options?.preserveStreamingMeta) {
+      setStreamingMeta(null);
+    }
 
     const nextCompactionState = clearRunningAutoCompactionIndicator(
       autoCompactionIndicatorRef.current,
@@ -2130,18 +2988,12 @@ export function ChatApp({
       applyAutoCompactionIndicator(nextCompactionState);
     }
 
-    if (options?.resetStreamingStateHook !== false) {
-      streamingState.reset();
-    }
-  }, [streamingState, applyAutoCompactionIndicator]);
-
-  const handleStreamStartupError = useCallback((error: unknown, expectedGeneration: number) => {
-    // Ignore stale failures from an older stream generation.
-    if (streamGenerationRef.current !== expectedGeneration) {
-      return;
-    }
+    // No longer need to reset streaming state hook (removed dead code)
+  }, [applyAutoCompactionIndicator, setStreamingMessageId]);
 
+  const handleStreamStartupError = useCallback((error: unknown) => {
     console.error("[stream] Failed to start stream:", error);
+    const errorMessage = error instanceof Error ? error.message : String(error ?? "Unknown error");
 
     const failedMessageId = streamingMessageIdRef.current;
     if (failedMessageId) {
@@ -2166,13 +3018,79 @@ export function ChatApp({
     stopSharedStreamState();
     finalizeThinkingSourceTracking();
 
+    setMessagesWindowed((prev: ChatMessage[]) => [
+      ...prev,
+      createMessage("system", `${STATUS.error} ${errorMessage}`),
+    ]);
+
+    const resolver = streamCompletionResolverRef.current;
+    streamCompletionResolverRef.current = null;
+    hideStreamContentRef.current = false;
+    if (resolver) {
+      resolver({ content: lastStreamingContentRef.current, wasInterrupted: true });
+    } else {
+      // Continue draining the message queue even after an error so queued
+      // messages are not silently dropped.
+      continueQueuedConversation();
+    }
+  }, [setMessagesWindowed, stopSharedStreamState, finalizeThinkingSourceTracking, continueQueuedConversation]);
+
+  const terminateStreamContractViolation = useCallback((args: {
+    errorMessage: string;
+    reason: ContractFailureTerminationReason;
+    code?: string;
+    eventType?: "stream.agent.start" | "stream.agent.update" | "stream.agent.complete";
+    agentId?: string;
+  }) => {
+    emitContractFailureTerminationObservability({
+      provider: agentType,
+      runId: activeStreamRunIdRef.current ?? undefined,
+      reason: args.reason,
+      errorMessage: args.errorMessage,
+      code: args.code,
+      eventType: args.eventType,
+      agentId: args.agentId,
+      eventBus,
+    });
+    stopSharedStreamState();
+    finalizeThinkingSourceTracking();
+    setMessagesWindowed((prev: ChatMessage[]) => [
+      ...prev,
+      createMessage("system", `${STATUS.error} ${args.errorMessage}`),
+    ]);
+
     const resolver = streamCompletionResolverRef.current;
     streamCompletionResolverRef.current = null;
     hideStreamContentRef.current = false;
     if (resolver) {
       resolver({ content: lastStreamingContentRef.current, wasInterrupted: true });
+      return;
     }
-  }, [setMessagesWindowed, stopSharedStreamState, finalizeThinkingSourceTracking]);
+
+    continueQueuedConversation();
+  }, [agentType, eventBus, continueQueuedConversation, finalizeThinkingSourceTracking, setMessagesWindowed, stopSharedStreamState]);
+
+  const terminateAgentLifecycleContractViolation = useCallback((args: {
+    code: AgentLifecycleViolationCode;
+    eventType: "stream.agent.start" | "stream.agent.update" | "stream.agent.complete";
+    agentId: string;
+  }) => {
+    emitAgentLifecycleContractObservability({
+      provider: agentType,
+      runId: activeStreamRunIdRef.current ?? undefined,
+      code: args.code,
+      eventType: args.eventType,
+      agentId: args.agentId,
+      eventBus,
+    });
+    terminateStreamContractViolation({
+      errorMessage: formatAgentLifecycleViolation(args),
+      reason: "agent_lifecycle_violation",
+      code: args.code,
+      eventType: args.eventType,
+      agentId: args.agentId,
+    });
+  }, [agentType, eventBus, terminateStreamContractViolation]);
 
   const enqueueShortcutLabel = useMemo(() => getEnqueueShortcutLabel(), []);
 
@@ -2206,22 +3124,33 @@ export function ChatApp({
   const handleToolStart = useCallback((
     toolId: string,
     toolName: string,
-    input: Record<string, unknown>
+    input: Record<string, unknown>,
+    agentId?: string,
   ) => {
-    const nextCompactionState = startAutoCompactionIndicator(
-      autoCompactionIndicatorRef.current,
-      toolName,
-    );
-    if (nextCompactionState !== autoCompactionIndicatorRef.current) {
-      applyAutoCompactionIndicator(nextCompactionState);
+    if (isAutoCompactionToolName(toolName) && autoCompactionIndicatorRef.current.status !== "running") {
+      applyAutoCompactionIndicator({ status: "running" });
     }
 
     toolNameByIdRef.current.set(toolId, toolName);
+    const syntheticStartedAt = new Date().toISOString();
+    setParallelAgents((current) =>
+      upsertSyntheticTaskAgentForToolStart({
+        agents: current,
+        provider: agentType,
+        toolName,
+        toolId,
+        input,
+        startedAt: syntheticStartedAt,
+        ...(agentId ? { agentId } : {}),
+      })
+    );
 
-    // Update streaming state
-    streamingState.handleToolStart(toolId, toolName, input);
-    // Track that a tool is running (synchronous ref for keyboard handler)
-    hasRunningToolRef.current = true;
+    // Tracking tool executions in streaming state was dead code (never read), removed
+    // Track blocking tool lifecycles synchronously for stream finalization.
+    if (shouldTrackToolAsBlocking(toolName)) {
+      runningBlockingToolIdsRef.current.add(toolId);
+      hasRunningToolRef.current = runningBlockingToolIdsRef.current.size > 0;
+    }
     if (isAskQuestionToolName(toolName)) {
       runningAskQuestionToolIdsRef.current.add(toolId);
     }
@@ -2234,8 +3163,9 @@ export function ChatApp({
     // If a tool call with the same ID already exists, update its input
     // (SDKs may send an initial event with empty input followed by a
     // populated one for the same logical tool call).
-    const messageId = streamingMessageIdRef.current;
+    const messageId = resolveAgentScopedMessageId(agentId);
     if (messageId) {
+      toolMessageIdByIdRef.current.set(toolId, messageId);
       setMessagesWindowed((prev) =>
         prev.map((msg) => {
           if (msg.id === messageId) {
@@ -2244,49 +3174,68 @@ export function ChatApp({
               toolId,
               toolName,
               input,
+              ...(agentId ? { agentId } : {}),
             });
           }
           return msg;
         })
       );
+    } else {
+      // Fallback: when streamingMessageIdRef is already null (e.g. race between
+      // stream.text.complete firing via direct bus subscription and batched
+      // tool-start events arriving via the 16ms batch dispatcher), find the most
+      // recent assistant message inside the state updater.
+      setMessagesWindowed((prev) => {
+        let targetId: string | undefined;
+        for (let i = prev.length - 1; i >= 0; i--) {
+          const msg = prev[i]!;
+          if (msg.role === "assistant") {
+            targetId = msg.id;
+            break;
+          }
+        }
+        if (!targetId) return prev;
+        toolMessageIdByIdRef.current.set(toolId, targetId);
+        return prev.map((msg) => {
+          if (msg.id === targetId) {
+            return applyStreamPartEvent(msg, {
+              type: "tool-start",
+              toolId,
+              toolName,
+              input,
+              ...(agentId ? { agentId } : {}),
+            });
+          }
+          return msg;
+        });
+      });
     }
 
     // Update persistent todo panel when TodoWrite is called
     if (isTodoWriteToolName(toolName) && input.todos && Array.isArray(input.todos)) {
       const previousTodos = todoItemsRef.current;
-      const todos = mergeBlockedBy(normalizeTodoItems(input.todos), previousTodos);
-      const taskStreamPinned = Boolean(ralphSessionIdRef.current);
-      const isRalphUpdate = isRalphTaskUpdate(todos, previousTodos);
+      const todos = reconcileTodoWriteItems(input.todos, previousTodos);
+      const isWorkflowUpdate = isWorkflowTaskUpdate(todos, previousTodos);
 
-      // During /ralph, ignore unrelated sub-agent TodoWrite payloads so they
-      // cannot replace the in-memory ralph task state.
-      const shouldApplyTodoState = !ralphSessionIdRef.current || isRalphUpdate;
+      // During workflow, ignore unrelated sub-agent TodoWrite payloads so they
+      // cannot replace the in-memory workflow task state.
+      const shouldApplyTodoState = !workflowSessionIdRef.current || isWorkflowUpdate;
       if (shouldApplyTodoState) {
         todoItemsRef.current = todos;
         setTodoItems(todos);
       }
 
-      // Persist to tasks.json only when the items are ralph task updates
-      // (share IDs with the planning-phase tasks). Sub-agent or independent
-      // TodoWrite lists must NOT overwrite ralph's persistent task state.
-      if (ralphSessionIdRef.current && isRalphUpdate) {
-        void saveTasksToActiveSession(todos, ralphSessionIdRef.current);
-      }
+      // During workflow: do NOT persist TodoWrite calls to tasks.json.
+      // The workflow (workflow-commands.ts) is the sole owner of tasks.json
+      // to prevent race conditions where sub-agent TodoWrite calls overwrite
+      // the workflow's status updates (e.g., marking a completed task back to in_progress).
+      // TodoWrite still updates in-memory UI state above for real-time display.
+      // 
+      // Before: if (workflowSessionIdRef.current && isWorkflowUpdate) { ... }
+      // Now: Never persist TodoWrite during active workflow.
 
-      if (messageId) {
-        setMessagesWindowed((prev) =>
-          prev.map((msg) =>
-            msg.id === messageId
-              ? {
-                  ...msg,
-                  tasksPinned: msg.tasksPinned ?? taskStreamPinned,
-                }
-              : msg
-          )
-        );
-      }
     }
-  }, [streamingState, isRalphTaskUpdate, applyAutoCompactionIndicator]);
+  }, [agentType, isWorkflowTaskUpdate, applyAutoCompactionIndicator, resolveAgentScopedMessageId]);
 
   /**
    * Handle tool execution complete event.
@@ -2295,32 +3244,33 @@ export function ChatApp({
    */
   const handleToolComplete = useCallback((
     toolId: string,
+    toolName: string,
     output: unknown,
     success: boolean,
     error?: string,
-    input?: Record<string, unknown>
+    input?: Record<string, unknown>,
+    agentId?: string,
   ) => {
-    const completedToolName = toolNameByIdRef.current.get(toolId);
-    if (completedToolName) {
-      const nextCompactionState = completeAutoCompactionIndicator(
-        autoCompactionIndicatorRef.current,
-        completedToolName,
-        success,
-        error,
+    const completedToolName = toolNameByIdRef.current.get(toolId) ?? toolName;
+    if (completedToolName && completedToolName !== "unknown" && isAutoCompactionToolName(completedToolName)) {
+      applyAutoCompactionIndicator(
+        success
+          ? { status: "completed" }
+          : { status: "error", errorMessage: error?.trim() || undefined },
       );
-      if (nextCompactionState !== autoCompactionIndicatorRef.current) {
-        applyAutoCompactionIndicator(nextCompactionState);
-      }
     }
 
-    const completedAskQuestion = completedToolName
-      ? isAskQuestionToolName(completedToolName)
-      : false;
-    if (completedToolName) {
-      toolNameByIdRef.current.delete(toolId);
-      if (completedAskQuestion) {
-        runningAskQuestionToolIdsRef.current.delete(toolId);
-      }
+    const completedAskQuestion = isAskQuestionToolName(completedToolName);
+    toolNameByIdRef.current.delete(toolId);
+    if (completedAskQuestion) {
+      runningAskQuestionToolIdsRef.current.delete(toolId);
+    }
+
+    const hadBlockingTool = hasRunningToolRef.current;
+    runningBlockingToolIdsRef.current.delete(toolId);
+    hasRunningToolRef.current = runningBlockingToolIdsRef.current.size > 0;
+    if (hadBlockingTool && !hasRunningToolRef.current && pendingCompleteRef.current) {
+      setToolCompletionVersion(v => v + 1);
     }
 
     if (
@@ -2334,15 +3284,14 @@ export function ChatApp({
       continueQueuedConversation();
     }
 
-    // Update streaming state
-    if (success) {
-      streamingState.handleToolComplete(toolId, output);
-    } else {
-      streamingState.handleToolError(toolId, error || "Unknown error");
-    }
+    // Tracking tool completion/error in streaming state was dead code (never read), removed
 
     // Update tool call in current streaming message
-    const messageId = streamingMessageIdRef.current;
+    const messageId =
+      streamingMessageIdRef.current
+      ?? toolMessageIdByIdRef.current.get(toolId)
+      ?? backgroundAgentMessageIdRef.current
+      ?? lastStreamedMessageIdRef.current;
     if (messageId) {
       setMessagesWindowed((prev) => {
         const updated = prev.map((msg) => {
@@ -2350,96 +3299,1061 @@ export function ChatApp({
             return applyStreamPartEvent(msg, {
               type: "tool-complete",
               toolId,
+              toolName: completedToolName,
               output,
               success,
               error,
               input,
+              ...(agentId ? { agentId } : {}),
             });
           }
           return msg;
         });
 
-        // Update hasRunningToolRef: check if any tool calls are still running
-        // in the current streaming message after this completion.
-        const streamMsg = updated.find((msg) => msg.id === messageId);
-        const stillRunning = streamMsg?.toolCalls?.some((tc) => tc.status === "running") ?? false;
-        const wasRunning = hasRunningToolRef.current;
-        hasRunningToolRef.current = stillRunning;
-
-        // If all tools completed and there's a pending complete, trigger effect
-        if (wasRunning && !stillRunning && pendingCompleteRef.current) {
-          setToolCompletionVersion(v => v + 1);
-        }
-
         return updated;
       });
     }
+    toolMessageIdByIdRef.current.delete(toolId);
+    setParallelAgents((current) => {
+      const completedAtMs = Date.now();
+      const withSyntheticFinalization = finalizeSyntheticTaskAgentForToolComplete({
+        agents: current,
+        provider: agentType,
+        toolName: completedToolName,
+        toolId,
+        success,
+        output,
+        error,
+        completedAtMs,
+        ...(agentId ? { agentId } : {}),
+      });
+      return finalizeCorrelatedSubagentDispatchForToolComplete({
+        agents: withSyntheticFinalization,
+        toolName: completedToolName,
+        toolId,
+        success,
+        error,
+        completedAtMs,
+        ...(agentId ? { agentId } : {}),
+      });
+    });
 
     // Update persistent todo panel when TodoWrite completes (handles late input)
     const isTodoWriteCompletion = isTodoWriteToolName(completedToolName);
     if (isTodoWriteCompletion && input && input.todos && Array.isArray(input.todos)) {
       const previousTodos = todoItemsRef.current;
-      const todos = mergeBlockedBy(normalizeTodoItems(input.todos), previousTodos);
-      const taskStreamPinned = Boolean(ralphSessionIdRef.current);
-      const isRalphUpdate = isRalphTaskUpdate(todos, previousTodos);
+      const todos = reconcileTodoWriteItems(input.todos, previousTodos);
+      const isWorkflowUpdate = isWorkflowTaskUpdate(todos, previousTodos);
 
-      // During /ralph, ignore unrelated sub-agent TodoWrite payloads so they
-      // cannot replace the in-memory ralph task state.
-      const shouldApplyTodoState = !ralphSessionIdRef.current || isRalphUpdate;
+      // During workflow, ignore unrelated sub-agent TodoWrite payloads so they
+      // cannot replace the in-memory workflow task state.
+      const shouldApplyTodoState = !workflowSessionIdRef.current || isWorkflowUpdate;
       if (shouldApplyTodoState) {
         todoItemsRef.current = todos;
         setTodoItems(todos);
       }
 
-      // Persist to tasks.json only when the items are ralph task updates
-      if (ralphSessionIdRef.current && isRalphUpdate) {
-        void saveTasksToActiveSession(todos, ralphSessionIdRef.current);
+      // During workflow: do NOT persist TodoWrite calls to tasks.json.
+      // The workflow (workflow-commands.ts) is the sole owner of tasks.json
+      // to prevent race conditions where sub-agent TodoWrite calls overwrite
+      // the workflow's status updates (e.g., marking a completed task back to in_progress).
+      // TodoWrite still updates in-memory UI state above for real-time display.
+      // 
+      // Before: if (workflowSessionIdRef.current && isWorkflowUpdate) { ... }
+      // Now: Never persist TodoWrite during active workflow.
+
+    }
+  }, [agentType, isWorkflowTaskUpdate, continueQueuedConversation, applyAutoCompactionIndicator]);
+
+  const handleStreamComplete = useCallback(function handleStreamCompleteImpl() {
+    const messageId = streamingMessageIdRef.current;
+    if (!messageId) {
+      return;
+    }
+
+    // Persist so late-arriving bus events (stream.usage) can still update this message
+    setLastStreamedMessageId(messageId);
+
+    const durationMs = streamingStartRef.current
+      ? Date.now() - streamingStartRef.current
+      : undefined;
+    const finalMeta = streamingMetaRef.current;
+
+    if (wasInterruptedRef.current) {
+      wasInterruptedRef.current = false;
+      setMessagesWindowed((prev: ChatMessage[]) =>
+        prev.map((msg: ChatMessage) =>
+          msg.id === messageId
+            ? {
+              ...finalizeStreamingReasoningInMessage(msg),
+              streaming: false,
+              durationMs,
+              modelId: currentModelRef.current,
+              outputTokens: finalMeta?.outputTokens || msg.outputTokens,
+              thinkingMs: finalMeta?.thinkingMs || msg.thinkingMs,
+              thinkingText: finalMeta?.thinkingText || msg.thinkingText || undefined,
+            }
+            : msg
+        )
+      );
+      setParallelAgents([]);
+      stopSharedStreamState();
+      finalizeThinkingSourceTracking();
+
+      const resolver = streamCompletionResolverRef.current;
+      if (resolver) {
+        streamCompletionResolverRef.current = null;
+        if (hideStreamContentRef.current && messageId) {
+          setMessagesWindowed((prev: ChatMessage[]) => prev.filter((msg: ChatMessage) => msg.id !== messageId));
+        }
+        hideStreamContentRef.current = false;
+        resolver({ content: lastStreamingContentRef.current, wasInterrupted: true });
+        return;
       }
 
-      if (messageId) {
-        setMessagesWindowed((prev) =>
-          prev.map((msg) =>
-            msg.id === messageId
-              ? {
-                  ...msg,
-                  tasksPinned: msg.tasksPinned ?? taskStreamPinned,
-                }
+      continueQueuedConversation();
+      return;
+    }
+
+    const hasActiveAgents = hasActiveForegroundAgents(parallelAgentsRef.current);
+    if (hasActiveAgents || hasRunningToolRef.current) {
+      const deferredMessageId = messageId;
+      let spawnTimeout: ReturnType<typeof setTimeout> | null = null;
+      const deferredComplete = () => {
+        if (spawnTimeout) {
+          clearTimeout(spawnTimeout);
+          spawnTimeout = null;
+        }
+        // Guard: skip if the streaming message changed (new user message sent)
+        if (streamingMessageIdRef.current !== deferredMessageId) {
+          pendingCompleteRef.current = null;
+          return;
+        }
+        handleStreamCompleteImpl();
+      };
+      pendingCompleteRef.current = deferredComplete;
+      spawnTimeout = setTimeout(() => {
+        if (pendingCompleteRef.current === deferredComplete
+            && parallelAgentsRef.current.length === 0) {
+          pendingCompleteRef.current = null;
+          if (hasRunningToolRef.current) {
+            const stalledToolIds = [...runningBlockingToolIdsRef.current];
+            hasRunningToolRef.current = false;
+            runningBlockingToolIdsRef.current.clear();
+            runningAskQuestionToolIdsRef.current.clear();
+            for (const stalledToolId of stalledToolIds) {
+              toolNameByIdRef.current.delete(stalledToolId);
+              toolMessageIdByIdRef.current.delete(stalledToolId);
+            }
+            setMessagesWindowed((prev: ChatMessage[]) =>
+              prev.map((msg: ChatMessage) =>
+                msg.id === messageId
+                  ? {
+                    ...msg,
+                    toolCalls: interruptRunningToolCalls(msg.toolCalls),
+                    parts: interruptRunningToolParts(msg.parts),
+                  }
+                  : msg
+              )
+            );
+            setToolCompletionVersion(v => v + 1);
+          }
+          deferredComplete();
+        }
+      }, 30_000);
+      return;
+    }
+
+    // Path 3: Normal completion — consolidate state updates.
+    // Read current agents from the ref (always in sync via useEffect) to
+    // avoid nesting setMessagesWindowed inside setParallelAgents, which
+    // previously caused an extra no-op state update and delayed renders.
+    const currentAgents = parallelAgentsRef.current;
+    const agentContinuationPayload = isAgentOnlyStreamRef.current
+      ? buildAgentContinuationPayload({
+        agents: currentAgents,
+        fallbackText: lastStreamingContentRef.current,
+      })
+      : null;
+    const continuationContractViolation = getAgentContinuationContractViolation({
+      isAgentOnlyStream: isAgentOnlyStreamRef.current,
+      continuationPayload: agentContinuationPayload,
+    });
+    const remaining = getActiveBackgroundAgents(currentAgents);
+    if (remaining.length > 0 && messageId) {
+      setBackgroundAgentMessageId(messageId);
+    }
+
+    // Single setMessagesWindowed call: reads existing agent IDs from the
+    // message being finalized AND applies the final streaming state in one
+    // updater, eliminating the previous no-op read-only state update.
+    setMessagesWindowed((prev: ChatMessage[]) => {
+      // Collect agent IDs already baked onto this message to filter out
+      // orphaned agents from previous messages.
+      const existingAgentIds = new Set<string>();
+      const targetMsg = prev.find((m) => m.id === messageId);
+      if (targetMsg?.parallelAgents) {
+        for (const agent of targetMsg.parallelAgents) {
+          existingAgentIds.add(agent.id);
+        }
+      }
+
+      const finalizedAgents = currentAgents.length > 0
+        ? currentAgents
+          .filter((a) => existingAgentIds.has(a.id)) // Only include agents that belong to this message
+          .map((a) => {
+            if (a.background) return a;
+            return a.status === "running" || a.status === "pending"
+              ? { ...a, status: "completed" as const, currentTool: undefined, durationMs: Date.now() - new Date(a.startedAt).getTime() }
+              : a;
+          })
+        : undefined;
+
+      return prev.map((msg: ChatMessage) =>
+        msg.id === messageId
+          ? {
+            ...finalizeStreamingReasoningInMessage(msg),
+            streaming: false,
+            durationMs,
+            modelId: currentModelRef.current,
+            // Prefer finalMeta values, but fall back to already-baked message values
+            // (bus subscriptions may have baked values before handleStreamComplete runs)
+            outputTokens: finalMeta?.outputTokens || msg.outputTokens,
+            thinkingMs: finalMeta?.thinkingMs || msg.thinkingMs,
+            thinkingText: finalMeta?.thinkingText || msg.thinkingText || undefined,
+            toolCalls: interruptRunningToolCalls(msg.toolCalls),
+            parts: interruptRunningToolParts(finalizeStreamingReasoningParts(msg.parts ?? [], finalMeta?.thinkingMs || msg.thinkingMs)),
+            parallelAgents: finalizedAgents,
+            taskItems: snapshotTaskItems(todoItemsRef.current) as TaskItem[] | undefined,
+          }
+          : msg
+      );
+    });
+
+    // Update parallel agents state back-to-back in the same synchronous
+    // block so React 18+ batches both into a single re-render.
+    // Eagerly update the ref so stopSharedStreamState reads the correct value.
+    parallelAgentsRef.current = remaining;
+    setParallelAgents(remaining);
+
+    if (continuationContractViolation) {
+      emitAgentMainContinuationObservability({
+        provider: agentType,
+        runId: activeStreamRunIdRef.current ?? undefined,
+        result: "missing",
+      });
+      terminateStreamContractViolation({
+        errorMessage: continuationContractViolation,
+        reason: "missing_agent_continuation",
+      });
+      return;
+    }
+
+    const hasRemainingBg = remaining.length > 0;
+    if (agentContinuationPayload) {
+      emitAgentMainContinuationObservability({
+        provider: agentType,
+        runId: activeStreamRunIdRef.current ?? undefined,
+        result: "forwarded",
+      });
+      sendBackgroundMessageToAgent(agentContinuationPayload);
+    }
+    stopSharedStreamState({
+      preserveStreamingStart: hasRemainingBg,
+      preserveStreamingMeta: hasRemainingBg,
+    });
+    finalizeThinkingSourceTracking({ preserveStreamingMeta: hasRemainingBg });
+
+    const resolver = streamCompletionResolverRef.current;
+    if (resolver) {
+      streamCompletionResolverRef.current = null;
+      if (hideStreamContentRef.current && messageId) {
+        setMessagesWindowed((prev: ChatMessage[]) => prev.filter((msg: ChatMessage) => msg.id !== messageId));
+      }
+      hideStreamContentRef.current = false;
+      resolver({ content: lastStreamingContentRef.current, wasInterrupted: false });
+      return;
+    }
+
+    continueQueuedConversation();
+  }, [agentType, continueQueuedConversation, finalizeThinkingSourceTracking, sendBackgroundMessageToAgent, setMessagesWindowed, setBackgroundAgentMessageId, setLastStreamedMessageId, stopSharedStreamState, terminateStreamContractViolation]);
+
+  const { resetConsumers, getCorrelationService } = useStreamConsumer((parts) => {
+    const updatesByMessageId = new Map<string, StreamPartEvent[]>();
+
+    const queueMessagePartUpdate = (messageId: string, update: StreamPartEvent): void => {
+      const queued = updatesByMessageId.get(messageId);
+      if (queued) {
+        queued.push(update);
+        return;
+      }
+      updatesByMessageId.set(messageId, [update]);
+    };
+
+    for (const part of parts) {
+      if (part.type === "tool-start") {
+        handleToolStart(part.toolId, part.toolName, part.input, part.agentId);
+        continue;
+      }
+      if (part.type === "tool-complete") {
+        handleToolComplete(part.toolId, part.toolName ?? "unknown", part.output, part.success, part.error, part.input, part.agentId);
+        continue;
+      }
+      if (part.type === "tool-partial-result") {
+        const messageId =
+          resolveAgentScopedMessageId(part.agentId)
+          ?? toolMessageIdByIdRef.current.get(part.toolId)
+          ?? streamingMessageIdRef.current
+          ?? backgroundAgentMessageIdRef.current
+          ?? lastStreamedMessageIdRef.current;
+        if (!messageId) continue;
+        queueMessagePartUpdate(messageId, {
+          type: "tool-partial-result",
+          toolId: part.toolId,
+          partialOutput: part.partialOutput,
+          ...(part.agentId ? { agentId: part.agentId } : {}),
+        });
+        continue;
+      }
+      if (part.type === "text-delta") {
+        // For agent-scoped text, always process — sub-agents manage their own
+        // stream lifecycle independently of the main chat stream state.
+        if (!part.agentId && !isStreamingRef.current) continue;
+        if (pendingCompleteRef.current) {
+          clearDeferredCompletion();
+        }
+        // Only accumulate main-stream content; sub-agent text is routed to
+        // agent inline parts and must not pollute the reconciliation ref.
+        if (!part.agentId) {
+          lastStreamingContentRef.current += part.delta;
+        }
+        if (hideStreamContentRef.current) continue;
+        const messageId = resolveAgentScopedMessageId(part.agentId);
+        if (!messageId) continue;
+        queueMessagePartUpdate(messageId, {
+          type: "text-delta",
+          delta: part.delta,
+          ...(part.agentId ? { agentId: part.agentId } : {}),
+        });
+        continue;
+      }
+      if (part.type === "text-complete") {
+        // Reconciliation: compare the authoritative fullText from the adapter
+        // with what we've accumulated via deltas. If any text was lost, apply
+        // the missing suffix through the normal text-delta path so both
+        // message.content and message.parts stay consistent.
+        const accumulated = lastStreamingContentRef.current;
+        const fullText = part.fullText;
+        if (fullText.length > accumulated.length && fullText.startsWith(accumulated)) {
+          const missing = fullText.slice(accumulated.length);
+          lastStreamingContentRef.current = fullText;
+          if (!hideStreamContentRef.current) {
+            const messageId = streamingMessageIdRef.current;
+            if (messageId) {
+              queueMessagePartUpdate(messageId, { type: "text-delta", delta: missing });
+            }
+          }
+        } else {
+          // Even if no missing text, update the ref to the authoritative value
+          lastStreamingContentRef.current = fullText;
+        }
+        // Do NOT call handleStreamComplete() here. During multi-turn agentic
+        // loops, message.complete SSE events fire after each assistant message
+        // update (not just at session end). Calling handleStreamComplete() on
+        // each text-complete would prematurely finalize the message before
+        // tools have started. Finalization is handled exclusively by the
+        // stream.session.idle lifecycle event.
+        continue;
+      }
+      if (part.type === "thinking-meta") {
+        const messageId = resolveAgentScopedMessageId(part.agentId);
+        if (!messageId) continue;
+        if (part.agentId) {
+          queueMessagePartUpdate(messageId, {
+            type: "thinking-meta",
+            thinkingSourceKey: part.thinkingSourceKey,
+            targetMessageId: part.targetMessageId,
+            streamGeneration: part.streamGeneration,
+            thinkingMs: part.thinkingMs,
+            thinkingText: part.thinkingText,
+            includeReasoningPart: true,
+            agentId: part.agentId,
+          });
+          continue;
+        }
+        const previousMeta = streamingMetaRef.current ?? {
+          outputTokens: 0,
+          thinkingMs: 0,
+          thinkingText: "",
+          thinkingTextBySource: {},
+          thinkingGenerationBySource: {},
+          thinkingMessageBySource: {},
+        };
+        const sourceKey = part.thinkingSourceKey;
+        const thinkingTextBySource = { ...previousMeta.thinkingTextBySource };
+        thinkingTextBySource[sourceKey] = `${thinkingTextBySource[sourceKey] ?? ""}${part.thinkingText}`;
+        const thinkingGenerationBySource = {
+          ...previousMeta.thinkingGenerationBySource,
+          [sourceKey]: part.streamGeneration,
+        };
+        const thinkingMessageBySource = {
+          ...previousMeta.thinkingMessageBySource,
+          // Use the resolved streaming message ID (from React state), not
+          // part.targetMessageId (adapter-level bus event ID).  These are
+          // independent UUIDs; resolveValidatedThinkingMetaEvent compares
+          // against expectedMessageId which is the React-state ID.
+          [sourceKey]: messageId,
+        };
+        const thinkingText = Object.values(thinkingTextBySource).join("");
+        const nextMeta: StreamingMeta = {
+          ...previousMeta,
+          thinkingSourceKey: sourceKey,
+          thinkingText,
+          thinkingTextBySource,
+          thinkingGenerationBySource,
+          thinkingMessageBySource,
+        };
+        streamingMetaRef.current = nextMeta;
+        setStreamingMeta(nextMeta);
+        const thinkingMetaEvent = resolveValidatedThinkingMetaEvent(
+          nextMeta,
+          messageId,
+          closedThinkingSourcesRef.current,
+          thinkingDropDiagnosticsRef.current,
+        );
+        if (!thinkingMetaEvent) continue;
+        queueMessagePartUpdate(messageId, {
+          type: "thinking-meta",
+          thinkingSourceKey: thinkingMetaEvent.thinkingSourceKey,
+          targetMessageId: thinkingMetaEvent.targetMessageId,
+          streamGeneration: thinkingMetaEvent.streamGeneration,
+          thinkingMs: nextMeta.thinkingMs,
+          thinkingText: thinkingMetaEvent.thinkingText,
+          includeReasoningPart: true,
+          ...(part.agentId ? { agentId: part.agentId } : {}),
+        });
+      }
+      // Route workflow runtime envelopes through the shared parts reducer so
+      // TaskList/TaskResult parts stay runtime-driven.
+      if (isRuntimeEnvelopePartEvent(part)) {
+        if (part.type === "workflow-step-complete") {
+          sendBackgroundMessageToAgent(toWorkflowStepCompletionMessage(part));
+          continue;
+        }
+        if (part.type === "workflow-step-start") {
+          continue;
+        }
+        // Send task results to the main agent so they are actionable, not decorative
+        if (part.type === "task-result-upsert") {
+          const env = part.envelope;
+          const resultText = env.envelope_text ?? env.output_text;
+          if (resultText.trim().length > 0) {
+            const statusLabel = env.status === "error" ? "failed" : "completed";
+            sendBackgroundMessageToAgent(
+              `Task "${env.title}" (${env.task_id}) ${statusLabel}:\n\n${resultText}`,
+            );
+          }
+        }
+        const messageId = resolveAgentScopedMessageId();
+        if (!messageId) continue;
+        queueMessagePartUpdate(messageId, part);
+        continue;
+      }
+    }
+
+    if (updatesByMessageId.size === 0) {
+      return;
+    }
+
+    setMessagesWindowed((prev: ChatMessage[]) =>
+      prev.map((msg: ChatMessage) => {
+        const updates = updatesByMessageId.get(msg.id);
+        if (!updates || updates.length === 0) {
+          return msg;
+        }
+
+        let nextMessage = msg;
+        for (const update of updates) {
+          nextMessage = applyStreamPartEvent(nextMessage, update);
+        }
+        return nextMessage;
+      })
+    );
+  });
+
+  // Turn lifecycle events — visual turn boundary markers emitted by OpenCode
+  // and Copilot adapters.  Claude sessions never fire these, so the handlers
+  // are defensive (guard on isStreamingRef).
+  useBusSubscription("stream.session.start", (event) => {
+    if (!isStreamingRef.current) {
+      return;
+    }
+    activeStreamRunIdRef.current = event.runId;
+    lastTurnFinishReasonRef.current = null;
+  });
+
+  useBusSubscription("stream.turn.start", (event) => {
+    const activeRunId = activeStreamRunIdRef.current;
+    if (activeRunId !== null && !shouldProcessStreamLifecycleEvent(activeRunId, event.runId)) {
+      return;
+    }
+
+    if (activeRunId === null) {
+      if (!isStreamingRef.current) {
+        return;
+      }
+      activeStreamRunIdRef.current = event.runId;
+    }
+
+    // Safety-net: ensure streaming state is active when the agent begins a
+    // turn.  Under normal flow startAssistantStream already sets this, but
+    // multi-turn agentic loops may fire additional turn.start events.
+    if (!isStreamingRef.current) {
+      isStreamingRef.current = true;
+      setIsStreaming(true);
+      if (!streamingStartRef.current) {
+        streamingStartRef.current = Date.now();
+      }
+    }
+
+    lastTurnFinishReasonRef.current = null;
+
+  });
+
+  useBusSubscription("stream.turn.end", (event) => {
+    if (!shouldProcessStreamLifecycleEvent(activeStreamRunIdRef.current, event.runId)) {
+      return;
+    }
+
+    // Flush pending batched events at the turn boundary so trailing content
+    // (e.g. tool-only responses) is delivered before session.idle finalizes.
+    if (isStreamingRef.current) {
+      batchDispatcher.flush();
+    }
+
+    lastTurnFinishReasonRef.current = asSessionLoopFinishReason(
+      (event.data as Record<string, unknown>).finishReason,
+    );
+  });
+
+  useBusSubscription("stream.session.idle", (event) => {
+    if (!shouldProcessStreamLifecycleEvent(activeStreamRunIdRef.current, event.runId)) {
+      return;
+    }
+
+    if (isStreamingRef.current) {
+      // Flush pending batched events BEFORE the continuation check so tool
+      // completion state is current.  Without this flush, adapters that do
+      // not emit stream.turn.end (e.g. Claude) may still have
+      // stream.tool.complete events pending in the batch dispatcher when
+      // session.idle fires, causing hasRunningToolRef to be stale (true)
+      // and shouldContinueParentSessionLoop to block queue processing.
+      //
+      // OpenCode / Copilot avoid this because stream.turn.end already
+      // triggers a dispatcher flush (see handler above), but Claude
+      // sessions never fire turn lifecycle events.
+      batchDispatcher.flush();
+
+      const idleReason = typeof event.data.reason === "string"
+        ? event.data.reason.trim().toLowerCase()
+        : "";
+      if (idleReason === "aborted") {
+        const interruptedToolIds = [...runningBlockingToolIdsRef.current];
+        if (interruptedToolIds.length > 0 || hasRunningToolRef.current) {
+          hasRunningToolRef.current = false;
+          runningBlockingToolIdsRef.current.clear();
+          runningAskQuestionToolIdsRef.current.clear();
+          for (const toolId of interruptedToolIds) {
+            toolNameByIdRef.current.delete(toolId);
+            toolMessageIdByIdRef.current.delete(toolId);
+          }
+
+          const interruptedMessageId =
+            streamingMessageIdRef.current
+            ?? lastStreamedMessageIdRef.current;
+          if (interruptedMessageId) {
+            setMessagesWindowed((prev: ChatMessage[]) =>
+              prev.map((msg: ChatMessage) =>
+                msg.id === interruptedMessageId
+                  ? {
+                    ...msg,
+                    toolCalls: interruptRunningToolCalls(msg.toolCalls),
+                    parts: interruptRunningToolParts(msg.parts),
+                  }
+                  : msg
+              )
+            );
+          }
+          setToolCompletionVersion((version) => version + 1);
+        }
+
+        const currentAgents = parallelAgentsRef.current;
+        const hasActiveAgents = currentAgents.some(
+          (agent) =>
+            agent.status === "running"
+            || agent.status === "pending"
+            || agent.status === "background",
+        );
+        if (hasActiveAgents) {
+          const now = Date.now();
+          const interruptedAgents = currentAgents.map((agent) => {
+            if (
+              agent.status !== "running"
+              && agent.status !== "pending"
+              && agent.status !== "background"
+            ) {
+              return agent;
+            }
+            const startedAtMs = new Date(agent.startedAt).getTime();
+            return {
+              ...agent,
+              status: "interrupted" as const,
+              currentTool: undefined,
+              durationMs: Number.isFinite(startedAtMs)
+                ? Math.max(0, now - startedAtMs)
+                : agent.durationMs,
+            };
+          });
+          parallelAgentsRef.current = interruptedAgents;
+          setParallelAgents(interruptedAgents);
+        }
+
+        handleStreamComplete();
+        return;
+      }
+
+      const continuationSignal = shouldContinueParentSessionLoop({
+        finishReason: lastTurnFinishReasonRef.current ?? undefined,
+        hasActiveForegroundAgents: hasActiveForegroundAgents(parallelAgentsRef.current),
+        hasRunningBlockingTool: hasRunningToolRef.current,
+        hasPendingTaskContract: hasPendingTaskResultContract(),
+      });
+
+      if (continuationSignal.shouldContinue) {
+        return;
+      }
+
+      handleStreamComplete();
+    }
+  });
+
+  useBusSubscription("stream.session.error", (event) => {
+    if (!shouldProcessStreamLifecycleEvent(activeStreamRunIdRef.current, event.runId)) {
+      return;
+    }
+
+    handleStreamStartupError(new Error(event.data.error));
+  });
+
+  // ── Session notification events ────────────────────────────────
+  // Info, warning, title, truncation, and compaction events emitted by
+  // OpenCode and Copilot adapters.  Surface them as system messages or
+  // feed them into existing indicator state machines.
+
+  useBusSubscription("stream.session.info", (event) => {
+    const { message, infoType } = event.data;
+    // Skip cancellation events — they are rendered inline on the interrupted
+    // assistant message (via wasInterrupted flag) rather than as a separate
+    // system message.  This also prevents duplicates when both the old and
+    // new adapters forward the same SDK cancellation event.
+    if (infoType === "cancellation") return;
+    if (message) {
+      setMessagesWindowed((prev) => [
+        ...prev,
+        createMessage("system", `${STATUS.active} ${message}`),
+      ]);
+    }
+  });
+
+  useBusSubscription("stream.session.warning", (event) => {
+    const { message } = event.data;
+    if (message) {
+      setMessagesWindowed((prev) => [
+        ...prev,
+        createMessage("system", `${MISC.warning} ${message}`),
+      ]);
+    }
+  });
+
+  useBusSubscription("stream.session.title_changed", (event) => {
+    const { title } = event.data;
+    if (title) {
+      // Update terminal window title via OSC escape sequence
+      process.stdout.write(`\x1b]2;${title}\x07`);
+    }
+  });
+
+  useBusSubscription("stream.session.truncation", (event) => {
+    const { tokensRemoved, messagesRemoved } = event.data;
+    setMessagesWindowed((prev) => [
+      ...prev,
+      createMessage(
+        "system",
+        formatSessionTruncationMessage(tokensRemoved, messagesRemoved),
+      ),
+    ]);
+  });
+
+  useBusSubscription("stream.session.compaction", (event) => {
+    if (!shouldProcessStreamLifecycleEvent(activeStreamRunIdRef.current, event.runId)) {
+      return;
+    }
+
+    const { phase, success, error } = event.data;
+    applyAutoCompactionIndicator(
+      getAutoCompactionIndicatorState(phase, success, error),
+    );
+  });
+
+  useBusSubscription("stream.usage", (event) => {
+
+    const usageAgentId = event.data.agentId;
+    const incoming = event.data.outputTokens ?? 0;
+
+    if (usageAgentId) {
+      setParallelAgents((current) =>
+        current.map((agent) =>
+          agent.id === usageAgentId
+            ? {
+              ...agent,
+              tokens: incoming > 0
+                ? Math.max(agent.tokens ?? 0, incoming)
+                : agent.tokens,
+            }
+            : agent
+        )
+      );
+
+      const scopedMessageId = resolveAgentScopedMessageId(usageAgentId);
+      if (scopedMessageId && incoming > 0) {
+        setMessagesWindowed((prev: ChatMessage[]) =>
+          prev.map((msg: ChatMessage) =>
+            msg.id === scopedMessageId
+              ? { ...msg, outputTokens: Math.max(msg.outputTokens ?? 0, incoming) }
               : msg
           )
         );
       }
+      return;
     }
-  }, [streamingState, isRalphTaskUpdate, continueQueuedConversation, applyAutoCompactionIndicator]);
 
-  /**
-   * Handle skill invoked event from SDK.
-   * Skill events are represented via normal tool.start/tool.complete rendering.
-   */
-  const handleSkillInvoked = useCallback((
-    _skillName: string,
-    _skillPath?: string
-  ) => {
-    // No-op: skill.invoked is intentionally not rendered as a separate indicator.
-  }, []);
+    const prevMeta = streamingMetaRef.current ?? {
+      outputTokens: 0,
+      thinkingMs: 0,
+      thinkingText: "",
+    };
+    // Adapters emit stream.usage with cumulative (running-total) outputTokens.
+    // Use the maximum of incoming and previous to handle out-of-order delivery.
+    const nextMeta: StreamingMeta = {
+      ...prevMeta,
+      outputTokens: Math.max(prevMeta.outputTokens, incoming > 0 ? incoming : 0),
+    };
+    streamingMetaRef.current = nextMeta;
+    setStreamingMeta(nextMeta);
+
+    // Bake outputTokens directly onto the message so the value survives
+    // React state batching AND late-arriving usage events (after handleStreamComplete).
+    // Falls back to lastStreamedMessageIdRef for events that arrive after
+    // stopSharedStreamState has nulled streamingMessageIdRef.
+    const messageId = resolveAgentScopedMessageId();
+    if (messageId && nextMeta.outputTokens > 0) {
+      setMessagesWindowed((prev: ChatMessage[]) =>
+        prev.map((msg: ChatMessage) =>
+          msg.id === messageId ? { ...msg, outputTokens: nextMeta.outputTokens } : msg
+        )
+      );
+    }
+  });
 
-  // Register tool event handlers with parent component
-  useEffect(() => {
-    if (registerToolStartHandler) {
-      registerToolStartHandler(handleToolStart);
+  useBusSubscription("stream.thinking.complete", (event) => {
+    const thinkingAgentId = event.data.agentId;
+
+    if (thinkingAgentId) {
+      setParallelAgents((current) =>
+        current.map((agent) =>
+          agent.id === thinkingAgentId
+            ? {
+              ...agent,
+              thinkingMs: Math.max(agent.thinkingMs ?? 0, event.data.durationMs),
+            }
+            : agent
+        )
+      );
+
+      const scopedMessageId = resolveAgentScopedMessageId(thinkingAgentId);
+      if (scopedMessageId && event.data.durationMs > 0) {
+        setMessagesWindowed((prev: ChatMessage[]) =>
+          prev.map((msg: ChatMessage) =>
+            msg.id === scopedMessageId
+              ? { ...msg, thinkingMs: Math.max(msg.thinkingMs ?? 0, event.data.durationMs) }
+              : msg
+          )
+        );
+      }
+      return;
     }
-  }, [registerToolStartHandler, handleToolStart]);
 
-  useEffect(() => {
-    if (registerToolCompleteHandler) {
-      registerToolCompleteHandler(handleToolComplete);
+    const prevMeta = streamingMetaRef.current ?? {
+      outputTokens: 0,
+      thinkingMs: 0,
+      thinkingText: "",
+    };
+    const nextMeta: StreamingMeta = {
+      ...prevMeta,
+      thinkingMs: Math.max(prevMeta.thinkingMs, event.data.durationMs),
+    };
+    streamingMetaRef.current = nextMeta;
+    setStreamingMeta(nextMeta);
+
+    // Bake thinkingMs directly onto the message (same late-arrival fallback).
+    const messageId = resolveAgentScopedMessageId();
+    if (messageId && nextMeta.thinkingMs > 0) {
+      setMessagesWindowed((prev: ChatMessage[]) =>
+        prev.map((msg: ChatMessage) =>
+          msg.id === messageId ? { ...msg, thinkingMs: nextMeta.thinkingMs } : msg
+        )
+      );
+    }
+  });
+
+  useBusSubscription("stream.agent.start", (event) => {
+
+    const data = event.data;
+    const correlationId = resolveSubagentStartCorrelationId(data);
+    const existingAgent = parallelAgentsRef.current.find((agent) => agent.id === data.agentId);
+    if (
+      agentLifecycleLedgerRef.current.has(data.agentId)
+      && existingAgent
+      && (existingAgent.status === "completed" || existingAgent.status === "error" || existingAgent.status === "interrupted")
+    ) {
+      terminateAgentLifecycleContractViolation({
+        code: "INVALID_TERMINAL_TRANSITION",
+        eventType: "stream.agent.start",
+        agentId: data.agentId,
+      });
+      return;
+    }
+    const lifecycleTransition = registerAgentLifecycleStart(agentLifecycleLedgerRef.current, data.agentId);
+    if (!lifecycleTransition.ok) {
+      terminateAgentLifecycleContractViolation({
+        code: lifecycleTransition.code,
+        eventType: "stream.agent.start",
+        agentId: data.agentId,
+      });
+      return;
+    }
+    const startedAt = new Date(event.timestamp).toISOString();
+    const status: ParallelAgent["status"] = data.isBackground ? "background" : "running";
+
+    const existingMessageId = agentMessageIdByIdRef.current.get(data.agentId);
+    const correlatedMessageId = correlationId
+      ? toolMessageIdByIdRef.current.get(correlationId)
+      : undefined;
+    const fallbackForegroundMessageId =
+      streamingMessageIdRef.current
+      ?? lastStreamedMessageIdRef.current;
+    const fallbackBackgroundMessageId =
+      backgroundAgentMessageIdRef.current
+      ?? fallbackForegroundMessageId;
+    const resolvedMessageId =
+      correlatedMessageId
+      ?? existingMessageId
+      ?? (data.isBackground ? fallbackBackgroundMessageId : fallbackForegroundMessageId);
+    if (resolvedMessageId) {
+      setAgentMessageBinding(data.agentId, resolvedMessageId);
+    }
+
+    if (data.isBackground) {
+      backgroundProgressSnapshotRef.current.set(data.agentId, {
+        toolUses: 0,
+        currentTool: data.agentType ? `Running ${data.agentType}...` : undefined,
+      });
+    }
+    setParallelAgents((current) => {
+      const existingIndex = current.findIndex((agent) => agent.id === data.agentId);
+      const correlatedIndex = existingIndex < 0 && correlationId
+        ? current.findIndex((agent) => agent.taskToolCallId === correlationId)
+        : -1;
+      const targetIndex = existingIndex >= 0 ? existingIndex : correlatedIndex;
+      if (targetIndex >= 0) {
+        const existing = current[targetIndex];
+        // If agent already has a terminal status (completed, error, interrupted),
+        // it's from a previous stream. Filter it out instead of preserving it.
+        if (existing && (existing.status === "completed" || existing.status === "error" || existing.status === "interrupted")) {
+          // Remove the old agent and add the new one
+          return [
+            ...current.filter((agent, index) => index !== targetIndex && agent.id !== data.agentId),
+            {
+              id: data.agentId,
+              taskToolCallId: correlationId,
+              name: data.agentType || "agent",
+              task: resolveIncomingSubagentTaskLabel(data.task, data.agentType),
+              status,
+              startedAt,
+              background: data.isBackground,
+              currentTool: undefined,
+            },
+          ];
+        }
+        // Update existing agent that's still active
+        return current.map((agent, index) =>
+          index === targetIndex
+            ? {
+              ...agent,
+              id: data.agentId,
+              name: data.agentType || agent.name,
+              task: mergeAgentTaskLabel(agent.task, data.task, data.agentType),
+              status,
+              background: data.isBackground || agent.background,
+              taskToolCallId: correlationId ?? agent.taskToolCallId,
+              currentTool: agent.currentTool,
+            }
+            : agent
+        );
+      }
+      return [
+        ...current,
+        {
+          id: data.agentId,
+          taskToolCallId: correlationId,
+          name: data.agentType || "agent",
+          task: resolveIncomingSubagentTaskLabel(data.task, data.agentType),
+          status,
+          startedAt,
+          background: data.isBackground,
+          currentTool: undefined,
+        },
+      ];
+    });
+  });
+
+  useBusSubscription("stream.agent.update", (event) => {
+
+    const data = event.data;
+    const lifecycleTransition = registerAgentLifecycleUpdate(
+      agentLifecycleLedgerRef.current,
+      data.agentId,
+    );
+    if (!lifecycleTransition.ok) {
+      terminateAgentLifecycleContractViolation({
+        code: lifecycleTransition.code,
+        eventType: "stream.agent.update",
+        agentId: data.agentId,
+      });
+      return;
+    }
+    const existingAgent = parallelAgentsRef.current.find((agent) => agent.id === data.agentId);
+    const nextCurrentTool = resolveAgentCurrentToolForUpdate({
+      incomingCurrentTool: data.currentTool,
+      existingCurrentTool: existingAgent?.currentTool,
+      agentName: existingAgent?.name,
+    });
+    const nextToolUses = data.toolUses ?? existingAgent?.toolUses;
+
+    let progressMessage: string | null = null;
+    if (existingAgent && isBackgroundAgent(existingAgent)) {
+      const snapshot = backgroundProgressSnapshotRef.current.get(existingAgent.id) ?? {
+        toolUses: existingAgent.toolUses ?? 0,
+        currentTool: existingAgent.currentTool,
+      };
+      const effectiveToolUses = nextToolUses ?? 0;
+      const toolUsesAdvanced = effectiveToolUses > snapshot.toolUses;
+      const toolChanged = typeof nextCurrentTool === "string" && nextCurrentTool !== snapshot.currentTool;
+
+      if (toolUsesAdvanced || (toolChanged && effectiveToolUses > 0)) {
+        const lines = [
+          `Background task "${existingAgent.name}" progress:`,
+          "",
+          `- Tool uses: ${effectiveToolUses}`,
+        ];
+        if (nextCurrentTool) {
+          lines.push(`- Current tool: ${nextCurrentTool}`);
+        }
+        progressMessage = lines.join("\n");
+      }
+
+      backgroundProgressSnapshotRef.current.set(existingAgent.id, {
+        toolUses: effectiveToolUses,
+        currentTool: nextCurrentTool,
+      });
+    }
+
+    setParallelAgents((current) =>
+      current.map((agent) =>
+        agent.id === data.agentId
+          ? {
+            ...agent,
+            currentTool: nextCurrentTool ?? agent.currentTool,
+            toolUses: nextToolUses ?? agent.toolUses,
+          }
+          : agent
+      )
+    );
+    if (progressMessage) {
+      sendBackgroundMessageToAgent(progressMessage);
+    }
+  });
+
+  useBusSubscription("stream.agent.complete", (event) => {
+
+    const data = event.data;
+    const lifecycleTransition = registerAgentLifecycleComplete(
+      agentLifecycleLedgerRef.current,
+      data.agentId,
+    );
+    if (!lifecycleTransition.ok) {
+      terminateAgentLifecycleContractViolation({
+        code: lifecycleTransition.code,
+        eventType: "stream.agent.complete",
+        agentId: data.agentId,
+      });
+      return;
+    }
+
+    // Check if the completing agent is a background agent before state update
+    const completingAgent = parallelAgentsRef.current.find(a => a.id === data.agentId);
+    const isBgAgent = completingAgent && isBackgroundAgent(completingAgent);
+
+    setParallelAgents((current) =>
+      current.map((agent) => {
+        if (agent.id !== data.agentId) return agent;
+        const startedAtMs = new Date(agent.startedAt).getTime();
+        return {
+          ...agent,
+          status: data.success ? "completed" : "error",
+          currentTool: undefined,
+          result: data.result ?? agent.result,
+          error: data.error,
+          durationMs: Number.isFinite(startedAtMs)
+            ? Math.max(0, Date.now() - startedAtMs)
+            : agent.durationMs,
+        };
+      })
+    );
+    backgroundProgressSnapshotRef.current.delete(data.agentId);
+
+    if (!isBgAgent) {
+      return;
+    }
+
+    const agentName = completingAgent?.name ?? data.agentId;
+    if (data.success) {
+      const result = data.result ?? completingAgent?.result;
+      if (typeof result === "string" && result.trim().length > 0) {
+        sendBackgroundMessageToAgent(`Background task "${agentName}" completed:\n\n${result}`);
+      } else {
+        sendBackgroundMessageToAgent(`Background task "${agentName}" completed.`);
+      }
+      return;
     }
-  }, [registerToolCompleteHandler, handleToolComplete]);
 
-  useEffect(() => {
-    if (registerSkillInvokedHandler) {
-      registerSkillInvokedHandler(handleSkillInvoked);
+    const errorText = data.error?.trim();
+    if (errorText) {
+      sendBackgroundMessageToAgent(`Background task "${agentName}" failed:\n\n${errorText}`);
+    } else {
+      sendBackgroundMessageToAgent(`Background task "${agentName}" failed.`);
     }
-  }, [registerSkillInvokedHandler, handleSkillInvoked]);
+  });
 
   // Cleanup timeouts on unmount
   useEffect(() => {
@@ -2450,19 +4364,72 @@ export function ChatApp({
       if (interruptTimeoutRef.current) {
         clearTimeout(interruptTimeoutRef.current);
       }
-      clearAutoCompactionTimeout();
       if (deferredCompleteTimeoutRef.current) {
         clearTimeout(deferredCompleteTimeoutRef.current);
       }
       if (backgroundTerminationTimeoutRef.current) {
         clearTimeout(backgroundTerminationTimeoutRef.current);
       }
+      backgroundProgressSnapshotRef.current.clear();
+      agentLifecycleLedgerRef.current.clear();
+      pendingBackgroundUpdatesRef.current = [];
     };
-  }, [clearAutoCompactionTimeout]);
+  }, []);
+
+  const startAssistantStream = useCallback((
+    content: string,
+    options?: import("./commands/registry.ts").StreamMessageOptions,
+  ) => {
+    if (!onStreamMessage) return;
+    isStreamingRef.current = true;
+    setIsStreaming(true);
+    streamingStartRef.current = Date.now();
+    activeStreamRunIdRef.current = null;
+    setLastStreamedMessageId(null);
+    resetThinkingSourceTracking();
+    resetTodoItemsForNewStream();
+    lastStreamingContentRef.current = "";
+    hasRunningToolRef.current = false;
+    runningBlockingToolIdsRef.current.clear();
+    runningAskQuestionToolIdsRef.current.clear();
+    toolNameByIdRef.current.clear();
+    toolMessageIdByIdRef.current.clear();
+    const activeAgentIds = new Set(
+      parallelAgentsRef.current
+        .filter((agent) => agent.status === "running" || agent.status === "pending" || agent.status === "background")
+        .map((agent) => agent.id),
+    );
+    for (const agentId of agentLifecycleLedgerRef.current.keys()) {
+      if (!activeAgentIds.has(agentId)) {
+        agentLifecycleLedgerRef.current.delete(agentId);
+      }
+    }
+    clearDeferredCompletion();
+    resetConsumers();
+
+    const assistantMessage = createMessage("assistant", "", true);
+    setStreamingMessageId(assistantMessage.id);
+    isAgentOnlyStreamRef.current = options?.isAgentOnlyStream ?? false;
+    setMessagesWindowed((prev: ChatMessage[]) => [...prev, assistantMessage]);
+
+    void Promise.resolve(onStreamMessage(content, options)).catch((error) => {
+      handleStreamStartupError(error);
+    });
+  }, [
+    onStreamMessage,
+    resetThinkingSourceTracking,
+    resetTodoItemsForNewStream,
+    clearDeferredCompletion,
+    resetConsumers,
+    setMessagesWindowed,
+    setLastStreamedMessageId,
+    setStreamingMessageId,
+    handleStreamStartupError,
+  ]);
 
   // Auto-start workflow when workflowActive becomes true with an initialPrompt.
   // This handles non-context-clear workflow starts (e.g., generic workflow commands).
-  // For /ralph step 1 → step 2 transitions, the command handler uses streamAndWait directly.
+  // For workflow step transitions, the command handler uses streamAndWait directly.
   const workflowStartedRef = useRef<string | null>(null);
   useEffect(() => {
     if (
@@ -2475,147 +4442,12 @@ export function ChatApp({
 
       const timeoutId = setTimeout(() => {
         if (isStreamingRef.current) return;
-
-        void (async () => {
-          try {
-            const promptToSend = workflowState.initialPrompt!;
-            // Clear stale todo items from previous turn when not in /ralph
-            resetTodoItemsForNewStream();
-            clearDeferredCompletion();
-
-          // Increment stream generation so stale handleComplete callbacks become no-ops
-          const currentGeneration = ++streamGenerationRef.current;
-          // Set streaming BEFORE calling onStreamMessage to prevent race conditions
-          setIsStreaming(true);
-          isStreamingRef.current = true;
-          resetThinkingSourceTracking();
-
-          // Call the stream handler - this is async but we don't await it
-          // The callbacks will handle state updates
-          void Promise.resolve(onStreamMessage?.(
-            promptToSend,
-            // onChunk: append to current message
-            (chunk) => {
-              // Drop chunks from stale streams (round-robin replaced this stream)
-              if (!isCurrentStreamCallback(streamGenerationRef.current, currentGeneration)) return;
-              if (pendingCompleteRef.current) {
-                clearDeferredCompletion();
-              }
-              setMessagesWindowed((prev) => {
-                const lastMsg = prev[prev.length - 1];
-                if (lastMsg && lastMsg.role === "assistant" && lastMsg.streaming) {
-                  return [
-                    ...prev.slice(0, -1),
-                    applyStreamPartEvent(lastMsg, { type: "text-delta", delta: chunk }),
-                  ];
-                }
-                // Create new streaming message
-                const newMessage = createMessage("assistant", chunk, true);
-                streamingMessageIdRef.current = newMessage.id;
-                isAgentOnlyStreamRef.current = false;
-                return [...prev, newMessage];
-              });
-            },
-            // onComplete: mark message as complete, finalize parallel agents
-            () => {
-              // Stale generation guard: if a newer stream started, this callback is a no-op
-              if (!isCurrentStreamCallback(streamGenerationRef.current, currentGeneration)) return;
-              // Finalize any still-running parallel agents and bake into message
-              setParallelAgents((currentAgents) => {
-                if (currentAgents.length > 0) {
-                  const finalizedAgents = currentAgents.map((a) => {
-                    // Skip background agents — they must not be finalized on stream completion
-                    if (a.background) return a;
-                    return a.status === "running" || a.status === "pending"
-                      ? { ...a, status: "completed" as const, currentTool: undefined, durationMs: Date.now() - new Date(a.startedAt).getTime() }
-                      : a;
-                  });
-                  // Bake finalized agents into the message
-                  setMessagesWindowed((prev) => {
-                    const lastMsg = prev[prev.length - 1];
-                    if (lastMsg && lastMsg.role === "assistant" && lastMsg.streaming) {
-                      return [
-                        ...prev.slice(0, -1),
-                        {
-                          ...finalizeStreamingReasoningInMessage(lastMsg),
-                          streaming: false,
-                          completedAt: new Date(),
-                          parallelAgents: finalizedAgents,
-                          taskItems: snapshotTaskItems(todoItemsRef.current) as TaskItem[] | undefined,
-                        },
-                      ];
-                    }
-                    return prev;
-                  });
-                  // Clear live agents since they're now baked into the message
-                  return [];
-                }
-                // No agents — just finalize the message normally
-                setMessagesWindowed((prev) => {
-                  const lastMsg = prev[prev.length - 1];
-                  if (lastMsg && lastMsg.role === "assistant" && lastMsg.streaming) {
-                    return [
-                      ...prev.slice(0, -1),
-                      {
-                        ...finalizeStreamingReasoningInMessage(lastMsg),
-                        streaming: false,
-                        completedAt: new Date(),
-                        taskItems: snapshotTaskItems(todoItemsRef.current) as TaskItem[] | undefined,
-                      },
-                    ];
-                  }
-                  return prev;
-                });
-                return currentAgents;
-              });
-              stopSharedStreamState();
-              finalizeThinkingSourceTracking();
-            },
-            // onMeta: update streaming metadata
-            (meta: StreamingMeta) => {
-              streamingMetaRef.current = meta;
-              setStreamingMeta(meta);
-              const messageId = streamingMessageIdRef.current;
-              if (!messageId) return;
-              const thinkingMetaEvent = resolveValidatedThinkingMetaEvent(
-                meta,
-                messageId,
-                currentGeneration,
-                closedThinkingSourcesRef.current,
-                thinkingDropDiagnosticsRef.current,
-              );
-              if (!thinkingMetaEvent) return;
-              setMessagesWindowed((prev: ChatMessage[]) =>
-                prev.map((msg: ChatMessage) =>
-                  msg.id === messageId
-                    ? applyStreamPartEvent(msg, {
-                        type: "thinking-meta",
-                        thinkingSourceKey: thinkingMetaEvent.thinkingSourceKey,
-                        targetMessageId: thinkingMetaEvent.targetMessageId,
-                        streamGeneration: thinkingMetaEvent.streamGeneration,
-                        thinkingMs: meta.thinkingMs,
-                        thinkingText: thinkingMetaEvent.thinkingText,
-                        includeReasoningPart: true,
-                      })
-                    : msg
-                )
-              );
-            }
-          )).catch((error) => {
-            handleStreamStartupError(error, currentGeneration);
-          });
-          } catch (error) {
-            // Prevent unhandled errors from crashing the TUI
-            console.error("[workflow auto-start] Error during context clear or streaming:", error);
-            stopSharedStreamState();
-            finalizeThinkingSourceTracking();
-          }
-        })();
+        startAssistantStream(workflowState.initialPrompt!);
       }, 100);
 
       return () => clearTimeout(timeoutId);
     }
-  }, [workflowState.workflowActive, workflowState.initialPrompt, isStreaming, onStreamMessage, handleStreamStartupError, stopSharedStreamState, finalizeThinkingSourceTracking, resetThinkingSourceTracking]);
+  }, [workflowState.workflowActive, workflowState.initialPrompt, isStreaming, startAssistantStream]);
 
   // Reset workflow started ref when workflow becomes inactive
   useEffect(() => {
@@ -2624,6 +4456,20 @@ export function ChatApp({
     }
   }, [workflowState.workflowActive]);
 
+  // Keep workflowActiveRef in sync for async callbacks (spawnSubagentParallel, addMessage)
+  useEffect(() => {
+    workflowActiveRef.current = workflowState.workflowActive;
+  }, [workflowState.workflowActive]);
+
+  useEffect(() => {
+    if (!workflowState.workflowActive) {
+      waitForUserInputResolverRef.current = rejectPendingWorkflowInput(
+        waitForUserInputResolverRef.current,
+        "Workflow ended before input was received",
+      );
+    }
+  }, [workflowState.workflowActive]);
+
   // Auto-hide task list panel when workflow ends naturally
   const syncTerminalTaskStateFromSession = useCallback((sessionDir: string) => {
     let diskTasks: NormalizedTodoItem[] = [];
@@ -2634,7 +4480,9 @@ export function ChatApp({
       // best effort: tasks.json may be absent during teardown
     }
 
-    const terminalTasks = preferTerminalTaskItems(todoItemsRef.current, diskTasks);
+    const terminalTasks = sortTasksTopologically(
+      preferTerminalTaskItems(todoItemsRef.current, diskTasks),
+    );
     if (terminalTasks.length === 0) return;
 
     todoItemsRef.current = terminalTasks;
@@ -2645,14 +4493,14 @@ export function ChatApp({
   }, [setMessagesWindowed]);
 
   useEffect(() => {
-    if (!workflowState.workflowActive && ralphSessionDir) {
-      syncTerminalTaskStateFromSession(ralphSessionDir);
-      setRalphSessionDir(null);
-      setRalphSessionId(null);
-      ralphSessionDirRef.current = null;
-      ralphSessionIdRef.current = null;
+    if (!workflowState.workflowActive && workflowSessionDir) {
+      syncTerminalTaskStateFromSession(workflowSessionDir);
+      setWorkflowSessionDir(null);
+      setWorkflowSessionId(null);
+      workflowSessionDirRef.current = null;
+      workflowSessionIdRef.current = null;
     }
-  }, [workflowState.workflowActive, ralphSessionDir, syncTerminalTaskStateFromSession]);
+  }, [workflowState.workflowActive, workflowSessionDir, syncTerminalTaskStateFromSession]);
 
   /**
    * Handle human_input_required signal.
@@ -2663,11 +4511,11 @@ export function ChatApp({
     // Only add to queue if there's already an active question
     // Otherwise, show directly
     if (activeQuestion) {
-      streamingState.addPendingQuestion(question);
+      addPendingQuestion(question);
     } else {
       setActiveQuestion(question);
     }
-  }, [streamingState, activeQuestion]);
+  }, [addPendingQuestion, activeQuestion]);
 
   // Store the respond callback for permission requests
   const permissionRespondRef = useRef<((answer: string | string[]) => void) | null>(null);
@@ -2783,41 +4631,57 @@ export function ChatApp({
     handleHumanInputRequired(userQuestion);
   }, [handleHumanInputRequired, workflowState.workflowActive, onWorkflowResumeWithAnswer]);
 
-  // Register askUserQuestion handler with parent component
-  useEffect(() => {
-    if (registerAskUserQuestionHandler) {
-      registerAskUserQuestionHandler(handleAskUserQuestion);
-    }
-  }, [registerAskUserQuestionHandler, handleAskUserQuestion]);
-
-  // Register permission request handler with parent component
-  useEffect(() => {
-    if (registerPermissionRequestHandler) {
-      registerPermissionRequestHandler(handlePermissionRequest);
-    }
-  }, [registerPermissionRequestHandler, handlePermissionRequest]);
+  useBusSubscription("stream.permission.requested", (event) => {
+    const data = event.data;
+    handlePermissionRequest(
+      data.requestId,
+      data.toolName,
+      data.question,
+      data.options,
+      data.respond ?? (() => {}),
+      data.header,
+      data.toolCallId,
+    );
+  });
 
-  // Register Ctrl+C warning handler with parent component
-  useEffect(() => {
-    if (registerCtrlCWarningHandler) {
-      registerCtrlCWarningHandler(setCtrlCPressed);
-    }
-  }, [registerCtrlCWarningHandler]);
+  useBusSubscription("stream.human_input_required", (event) => {
+    const data = event.data;
+    const askEvent: AskUserQuestionEventData = {
+      requestId: data.requestId,
+      question: data.question,
+      header: data.header,
+      options: data.options,
+      nodeId: data.nodeId,
+    };
+    handleAskUserQuestion(askEvent);
+  });
 
-  // Register parallel agent handler with parent component.
-  // Wraps setParallelAgents to also keep the synchronous ref in sync.
-  useEffect(() => {
-    if (registerParallelAgentHandler) {
-      registerParallelAgentHandler((agents: ParallelAgent[]) => {
-        parallelAgentsRef.current = agents;
-        setParallelAgents(agents);
-      });
-    }
-  }, [registerParallelAgentHandler]);
+  useBusSubscription("stream.skill.invoked", (event) => {
+    const { skillName } = event.data;
+    if (loadedSkillsRef.current.has(skillName)) return;
+    loadedSkillsRef.current.add(skillName);
+    const skillLoad: MessageSkillLoad = {
+      skillName,
+      status: "loaded",
+    };
+    setMessagesWindowed((prev) => {
+      const lastMsg = prev[prev.length - 1];
+      if (lastMsg && lastMsg.role === "assistant") {
+        return [
+          ...prev.slice(0, -1),
+          { ...lastMsg, skillLoads: [...(lastMsg.skillLoads || []), skillLoad] },
+        ];
+      }
+      const msg = createMessage("assistant", "");
+      msg.skillLoads = [skillLoad];
+      return [...prev, msg];
+    });
+  });
 
   // Keep live sub-agent updates anchored to the active streaming message so
   // they render in-order inside chat scrollback instead of as a last-row overlay.
-  // Also handles background agent completion updates after stream ends.
+  // After stream completion, keep background-agent updates synchronized into
+  // the baked snapshot message.
   useEffect(() => {
     if (parallelAgents.length === 0) return;
 
@@ -2826,10 +4690,28 @@ export function ChatApp({
     if (messageId) {
       setMessagesWindowed((prev: ChatMessage[]) =>
         prev.map((msg: ChatMessage, index: number) => {
-          if (msg.id === messageId && msg.streaming) {
+          if (msg.id === messageId) {
+            // Filter out terminal-status agents from previous messages.
+            // Only include agents that are active (running/pending/background)
+            // OR agents that just finished in THIS stream (no existing parallelAgents means they're new).
+            const existingAgentIds = new Set((msg.parallelAgents ?? []).map((a) => a.id));
+            const filteredAgents = parallelAgents.filter((agent) => {
+              const mappedMessageId = agentMessageIdByIdRef.current.get(agent.id);
+              if (mappedMessageId && mappedMessageId !== messageId) {
+                return false;
+              }
+              // Keep agents that are active
+              if (agent.status === "running" || agent.status === "pending" || agent.status === "background") {
+                return true;
+              }
+              // Keep agents with terminal status only if they were already in this message
+              // (they just finished in this stream)
+              return existingAgentIds.has(agent.id);
+            });
+            
             return applyStreamPartEvent(msg, {
               type: "parallel-agents",
-              agents: parallelAgents,
+              agents: filteredAgents,
               isLastMessage: index === prev.length - 1,
             });
           }
@@ -2839,29 +4721,46 @@ export function ChatApp({
       return;
     }
 
-    // After stream ends: update baked message for background agent completions
-    const bgMsgId = backgroundAgentMessageIdRef.current;
-    if (bgMsgId) {
+    // After streaming ends: bake agent status updates into the last streamed message
+    // so terminal statuses (completed/error) are reflected in the UI.
+    const lastMsgId = lastStreamedMessageIdRef.current;
+    if (lastMsgId) {
       setMessagesWindowed((prev: ChatMessage[]) =>
         prev.map((msg: ChatMessage, index: number) => {
-          if (msg.id === bgMsgId) {
+          if (msg.id === lastMsgId) {
+            const filteredAgents = parallelAgents.filter((agent) => {
+              const mappedMessageId = agentMessageIdByIdRef.current.get(agent.id);
+              return !mappedMessageId || mappedMessageId === lastMsgId;
+            });
             return applyStreamPartEvent(msg, {
               type: "parallel-agents",
-              agents: parallelAgents,
+              agents: filteredAgents,
               isLastMessage: index === prev.length - 1,
             });
           }
           return msg;
         })
       );
-      // Clear refs once all background agents have reached terminal state
-      const hasActiveBg = getActiveBackgroundAgents(parallelAgents).length > 0;
-      if (!hasActiveBg) {
-        backgroundAgentMessageIdRef.current = null;
-        streamingStartRef.current = null;
+      return;
+    }
+
+    if (backgroundAgentMessageIdRef.current) {
+      const filteredAgents = parallelAgents.filter((agent) => {
+        const mappedMessageId = agentMessageIdByIdRef.current.get(agent.id);
+        return !mappedMessageId || mappedMessageId === backgroundAgentMessageIdRef.current;
+      });
+      applyBackgroundAgentUpdateRef.current(backgroundAgentMessageIdRef.current, filteredAgents);
+    }
+  }, [parallelAgents, setMessagesWindowed, agentAnchorSyncVersion]);
+
+  useEffect(() => {
+    const activeAgentIds = new Set(parallelAgents.map((agent) => agent.id));
+    for (const agentId of Array.from(agentMessageIdByIdRef.current.keys())) {
+      if (!activeAgentIds.has(agentId)) {
+        deleteAgentMessageBinding(agentId);
       }
     }
-  }, [parallelAgents, setMessagesWindowed]);
+  }, [parallelAgents, deleteAgentMessageBinding]);
 
   // When all sub-agents/tools finish and a dequeue was deferred, trigger it.
   // This fires whenever parallelAgents changes (from SDK events OR interrupt handler)
@@ -2902,19 +4801,23 @@ export function ChatApp({
     // when all spawned sub-agents have completed and there is no pending SDK
     // stream completion.  Without this, the placeholder assistant message
     // would stay in the streaming state indefinitely.
+    const messageId = streamingMessageIdRef.current;
+    const messageAgents = messageId ? (messages.find((m) => m.id === messageId)?.parallelAgents ?? []) : [];
     if (
-      streamingMessageIdRef.current &&
-      isStreamingRef.current &&
-      isAgentOnlyStreamRef.current
+      shouldFinalizeAgentOnlyStream({
+        hasStreamingMessage: Boolean(messageId),
+        isStreaming: isStreamingRef.current,
+        isAgentOnlyStream: isAgentOnlyStreamRef.current,
+        liveAgentCount: parallelAgents.length,
+        messageAgentCount: messageAgents.length,
+      })
     ) {
-      const messageId = streamingMessageIdRef.current;
       const durationMs = streamingStartRef.current
         ? Date.now() - streamingStartRef.current
         : undefined;
       // SDK-side correlation cleanup may clear live parallelAgents before this
       // finalizer runs. Fall back to the agents already baked onto the message
       // so we can still stop streaming and preserve the final tree state.
-      const messageAgents = messages.find((m) => m.id === messageId)?.parallelAgents ?? [];
       const sourceAgents = parallelAgents.length > 0 ? parallelAgents : messageAgents;
       const finalizedAgents = sourceAgents.map((a) => {
         if (a.background) return a;
@@ -2934,6 +4837,14 @@ export function ChatApp({
         .map((a) => (typeof a.result === "string" ? normalizeMarkdownNewlines(a.result) : ""))
         .filter((result) => result.length > 0);
       const agentOutput = agentOutputParts.join("\n\n");
+      const agentContinuationPayload = buildAgentContinuationPayload({
+        agents: finalizedAgents,
+        fallbackText: agentOutput,
+      });
+      const continuationContractViolation = getAgentContinuationContractViolation({
+        isAgentOnlyStream: isAgentOnlyStreamRef.current,
+        continuationPayload: agentContinuationPayload,
+      });
 
       setMessagesWindowed((prev: ChatMessage[]) =>
         prev.map((msg: ChatMessage) =>
@@ -2950,16 +4861,42 @@ export function ChatApp({
             : msg
         )
       );
-      finalizeThinkingSourceTracking();
       // Keep background agents in live state for post-stream completion tracking
       const remainingBg = getActiveBackgroundAgents(parallelAgents);
+      if (continuationContractViolation) {
+        setParallelAgents([]);
+        parallelAgentsRef.current = [];
+        emitAgentMainContinuationObservability({
+          provider: agentType,
+          runId: activeStreamRunIdRef.current ?? undefined,
+          result: "missing",
+        });
+        terminateStreamContractViolation({
+          errorMessage: continuationContractViolation,
+          reason: "missing_agent_continuation",
+        });
+        return;
+      }
+      if (agentContinuationPayload) {
+        emitAgentMainContinuationObservability({
+          provider: agentType,
+          runId: activeStreamRunIdRef.current ?? undefined,
+          result: "forwarded",
+        });
+        sendBackgroundMessageToAgent(agentContinuationPayload);
+      }
       if (remainingBg.length > 0 && messageId) {
-        stopSharedStreamState({ preserveStreamingStart: true });
-        backgroundAgentMessageIdRef.current = messageId;
+        stopSharedStreamState({
+          preserveStreamingStart: true,
+          preserveStreamingMeta: true,
+        });
+        finalizeThinkingSourceTracking({ preserveStreamingMeta: true });
+        setBackgroundAgentMessageId(messageId);
         setParallelAgents(remainingBg);
         parallelAgentsRef.current = remainingBg;
       } else {
         stopSharedStreamState();
+        finalizeThinkingSourceTracking();
         setParallelAgents([]);
         parallelAgentsRef.current = [];
       }
@@ -2968,22 +4905,7 @@ export function ChatApp({
       // the SDK handleComplete callback, so we must dequeue here.
       continueQueuedConversation();
     }
-  }, [parallelAgents, continueQueuedConversation, toolCompletionVersion, messages, stopSharedStreamState, finalizeThinkingSourceTracking]);
-
-  // Initialize SubagentGraphBridge when createSubagentSession is available
-  useEffect(() => {
-    if (!createSubagentSession) {
-      setSubagentBridge(null);
-      return;
-    }
-
-    const bridge = new SubagentGraphBridge({ createSession: createSubagentSession });
-    setSubagentBridge(bridge);
-
-    return () => {
-      setSubagentBridge(null);
-    };
-  }, [createSubagentSession]);
+  }, [agentType, parallelAgents, continueQueuedConversation, toolCompletionVersion, messages, sendBackgroundMessageToAgent, setBackgroundAgentMessageId, stopSharedStreamState, finalizeThinkingSourceTracking, terminateStreamContractViolation]);
 
   /**
    * Handle user answering a question from UserQuestionDialog.
@@ -2997,7 +4919,7 @@ export function ChatApp({
     const normalizedHitl = normalizeHitlAnswer(answer);
 
     // Advance to the next pending question (if any).
-    const nextQuestion = streamingState.removePendingQuestion();
+    const nextQuestion = removePendingQuestion();
     setActiveQuestion(nextQuestion ?? null);
 
     // If there's a permission respond callback, call it (SDK permission requests)
@@ -3089,7 +5011,7 @@ export function ChatApp({
 
     // Don't add "User selected" messages - Claude Code doesn't show these
     // The streaming response continues automatically after the callback
-  }, [streamingState, updateWorkflowState, workflowState.workflowActive, onWorkflowResumeWithAnswer, getSession]);
+  }, [removePendingQuestion, updateWorkflowState, workflowState.workflowActive, onWorkflowResumeWithAnswer, getSession]);
 
   /**
    * Update workflow progress state (called by workflow execution).
@@ -3149,6 +5071,18 @@ export function ChatApp({
   // Ref for executeCommand to allow deferred message handling to spawn agents
   const executeCommandRef = useRef<((commandName: string, args: string, trigger?: CommandExecutionTrigger) => Promise<boolean>) | null>(null);
 
+  const dispatchDeferredCommandMessage = useCallback((message: DeferredCommandMessage) => {
+    if (sendMessageRef.current) {
+      sendMessageRef.current(
+        message.content,
+        message.skipUserMessage ? { skipUserMessage: true } : undefined,
+      );
+      return;
+    }
+    // Extremely defensive: restore message to the front if dispatch isn't ready yet.
+    deferredCommandQueueRef.current.unshift(message);
+  }, []);
+
   const dispatchQueuedMessage = useCallback((queuedMessage: QueuedMessage) => {
     const atMentions = parseAtMentions(queuedMessage.content);
     if (atMentions.length > 0 && executeCommandRef.current) {
@@ -3157,16 +5091,8 @@ export function ChatApp({
         setMessagesWindowed((prev: ChatMessage[]) => [...prev, createMessage("user", visibleContent)]);
       }
 
-      const assistantMsg = createMessage("assistant", "", true);
-      streamingMessageIdRef.current = assistantMsg.id;
-      isAgentOnlyStreamRef.current = true;
       isStreamingRef.current = true;
-      streamingStartRef.current = Date.now();
-      resetThinkingSourceTracking();
       setIsStreaming(true);
-      resetTodoItemsForNewStream();
-      setMessagesWindowed((prev: ChatMessage[]) => [...prev, assistantMsg]);
-
       for (const mention of atMentions) {
         void executeCommandRef.current(mention.agentName, mention.args, "mention");
       }
@@ -3179,12 +5105,16 @@ export function ChatApp({
         queuedMessage.skipUserMessage ? { skipUserMessage: true } : undefined
       );
     }
-  }, [resetThinkingSourceTracking, resetTodoItemsForNewStream]);
+  }, [setMessagesWindowed]);
 
   useEffect(() => {
     dispatchQueuedMessageRef.current = dispatchQueuedMessage;
   }, [dispatchQueuedMessage]);
 
+  useEffect(() => {
+    dispatchDeferredCommandMessageRef.current = dispatchDeferredCommandMessage;
+  }, [dispatchDeferredCommandMessage]);
+
   /**
    * Check if a character is a valid word boundary for @ mentions.
    * Includes whitespace and common punctuation that can precede mentions.
@@ -3202,6 +5132,9 @@ export function ChatApp({
    * or when "@" appears at any position near the cursor.
    */
   const handleInputChange = useCallback((rawValue: string, cursorOffset: number) => {
+    // Skip autocomplete logic during history navigation to prevent breaking history nav
+    if (historyNavigatingRef.current) return;
+    
     // Trim leading whitespace to prevent leading space from breaking slash command detection
     const value = rawValue.trimStart();
     // Check if input starts with "/" (slash command)
@@ -3329,9 +5262,79 @@ export function ChatApp({
    * Used by command execution context.
    */
   const addMessage = useCallback((role: "user" | "assistant" | "system", content: string) => {
-    const msg = createMessage(role, content);
-    setMessagesWindowed((prev) => [...prev, msg]);
-  }, []);
+    // When streaming is active and we're adding an assistant message,
+    // mark it as streaming so the LoadingIndicator and task animations render.
+    // This is essential for workflow commands (like /ralph or custom workflows) that use setStreaming(true)
+    // and addMessage together.
+    const streaming = role === "assistant" && isStreamingRef.current;
+    const msg = createMessage(role, content, streaming);
+    // During workflow execution, set the spinner verb and start the elapsed timer
+    // so the user sees "Running workflow… (Xs)" throughout the workflow lifecycle.
+    if (streaming && workflowActiveRef.current) {
+      msg.spinnerVerb = "Running workflow";
+      if (!streamingStartRef.current) {
+        streamingStartRef.current = Date.now();
+      }
+    }
+    // Set streamingMessageIdRef so downstream handlers (text-delta, parallel-agents sync,
+    // tool events) can target this message. Without this, workflow sub-agent events have
+    // no target message and get silently dropped.
+    if (streaming) {
+      setStreamingMessageId(msg.id);
+    }
+    setMessagesWindowed((prev) => {
+      // Finalize any previously streaming messages so only the newest one
+      // shows the spinner. This prevents stale spinners on earlier messages
+      // and ensures the spinner is always pinned above the chatbox.
+      const finalized = prev.map((m) =>
+        m.streaming
+          ? { ...finalizeStreamingReasoningInMessage(m), streaming: false, completedAt: new Date() }
+          : m,
+      );
+      return [...finalized, msg];
+    });
+  }, [setStreamingMessageId]);
+
+  /**
+   * Helper to set streaming state and optionally finalize the last streaming message.
+   * Used by command execution context.
+   */
+  const setStreamingWithFinalize = useCallback((streaming: boolean) => {
+    // When turning off streaming, finalize the last assistant message
+    if (!streaming && isStreamingRef.current) {
+      // Reset the elapsed timer so the next workflow/stream starts fresh.
+      streamingStartRef.current = null;
+      const activeStreamingMessageId = streamingMessageIdRef.current;
+      if (activeStreamingMessageId) {
+        setLastStreamedMessageId(activeStreamingMessageId);
+      }
+      setMessagesWindowed((prev) => {
+        if (!activeStreamingMessageId) {
+          return prev;
+        }
+        return prev.map((msg) =>
+          msg.id === activeStreamingMessageId && msg.role === "assistant" && msg.streaming
+            ? {
+                ...finalizeStreamingReasoningInMessage(msg),
+                streaming: false,
+                completedAt: new Date(),
+                taskItems: snapshotTaskItems(todoItemsRef.current) as TaskItem[] | undefined,
+              }
+            : msg
+        );
+      });
+      setStreamingMessageId(null);
+      activeStreamRunIdRef.current = null;
+    }
+
+    isStreamingRef.current = streaming;
+    setIsStreaming(streaming);
+    // Workflow-driven streams (set via CommandContext.setStreaming) do not
+    // go through SDK handleComplete, so drain queued messages here.
+    if (!streaming) {
+      continueQueuedConversation();
+    }
+  }, [continueQueuedConversation, setLastStreamedMessageId, setStreamingMessageId]);
 
   /**
    * Handle model selection from the ModelSelectorDialog.
@@ -3408,273 +5411,65 @@ export function ChatApp({
         success: false,
         trigger,
       });
-      return false;
-    }
-
-    // Create the command context
-    const contextState: CommandContextState = {
-      isStreaming,
-      messageCount: messages.length,
-      workflowActive: workflowState.workflowActive,
-      workflowType: workflowState.workflowType,
-      initialPrompt: workflowState.initialPrompt,
-      currentNode: workflowState.currentNode,
-      iteration: workflowState.iteration,
-      maxIterations: workflowState.maxIterations,
-      featureProgress: workflowState.featureProgress,
-      pendingApproval: workflowState.pendingApproval,
-      specApproved: workflowState.specApproved,
-      feedback: workflowState.feedback,
-    };
-
-    const context: CommandContext = {
-      session: getSession?.() ?? null,
-      state: contextState,
-      addMessage,
-      setStreaming: setIsStreaming,
-      sendMessage: (content: string) => {
-        // Use ref to call sendMessage without circular dependency
-        if (sendMessageRef.current) {
-          sendMessageRef.current(content);
-        }
-      },
-      sendSilentMessage: (content: string, options?: import("./commands/registry.ts").StreamMessageOptions) => {
-        // Send to agent without displaying as user message
-        // Call send handler (fire and forget)
-        if (onSendMessage) {
-          void Promise.resolve(onSendMessage(content));
-        }
-        // Handle streaming response if handler provided
-        if (onStreamMessage) {
-          // Finalize any previous streaming message before starting a new one.
-          // This prevents duplicate "Generating..." spinners when sendSilentMessage
-          // is called from an @mention handler that already created a placeholder.
-          const prevStreamingId = streamingMessageIdRef.current;
-          if (prevStreamingId) {
-            setMessagesWindowed((prev: ChatMessage[]) =>
-              prev.map((msg: ChatMessage) =>
-                msg.id === prevStreamingId && msg.streaming
-                  ? { ...finalizeStreamingReasoningInMessage(msg), streaming: false }
-                  : msg
-              ).filter((msg: ChatMessage) =>
-                // Remove the previous placeholder if it has no content
-                !(msg.id === prevStreamingId && !msg.content.trim())
-              )
-            );
-          }
-
-          // Increment stream generation so stale handleComplete callbacks become no-ops
-          const currentGeneration = ++streamGenerationRef.current;
-          isStreamingRef.current = true;
-          setIsStreaming(true);
-          streamingStartRef.current = Date.now();
-          resetThinkingSourceTracking();
-          // Clear stale todo items from previous turn when not in /ralph
-          resetTodoItemsForNewStream();
-          // Reset streaming content accumulator for step 1 → step 2 task parsing
-          lastStreamingContentRef.current = "";
-          // Reset tool tracking for the new stream
-          hasRunningToolRef.current = false;
-          clearDeferredCompletion();
-
-          // Create placeholder assistant message for the response
-          const assistantMessage = createMessage("assistant", "", true);
-          streamingMessageIdRef.current = assistantMessage.id;
-          isAgentOnlyStreamRef.current = false;
-          setMessagesWindowed((prev: ChatMessage[]) => [...prev, assistantMessage]);
-
-          const handleChunk = (chunk: string) => {
-            if (!isStreamingRef.current) return;
-            // Drop chunks from stale streams (round-robin replaced this stream)
-            if (!isCurrentStreamCallback(streamGenerationRef.current, currentGeneration)) return;
-            // If completion was deferred waiting on sub-agents/tools but the
-            // model resumes emitting chunks, cancel the deferred completion and
-            // keep the current stream alive.
-            if (pendingCompleteRef.current) {
-              clearDeferredCompletion();
-            }
-            // Accumulate content for step 1 → step 2 task parsing
-            lastStreamingContentRef.current += chunk;
-            // Skip rendering in message when content is hidden (e.g., step 1 JSON output)
-            if (hideStreamContentRef.current) return;
-            const messageId = streamingMessageIdRef.current;
-            if (messageId) {
-              setMessagesWindowed((prev: ChatMessage[]) =>
-                prev.map((msg: ChatMessage) => {
-                  if (msg.id === messageId) {
-                    return applyStreamPartEvent(msg, { type: "text-delta", delta: chunk });
-                  }
-                  return msg;
-                })
-              );
-            }
-          };
-
-          const handleComplete = () => {
-            // Stale generation guard — a newer stream has started (round-robin inject),
-            // so this callback must not touch any shared refs/state.
-            if (!isCurrentStreamCallback(streamGenerationRef.current, currentGeneration)) return;
-            const messageId = streamingMessageIdRef.current;
-            const durationMs = streamingStartRef.current
-              ? Date.now() - streamingStartRef.current
-              : undefined;
-            const finalMeta = streamingMetaRef.current;
-
-            // If the interrupt handler already finalized agents, skip overwriting
-            if (wasInterruptedRef.current) {
-              wasInterruptedRef.current = false;
-              // Just ensure streaming flags are cleared and message is finalized
-              if (messageId) {
-                setMessagesWindowed((prev: ChatMessage[]) =>
-                  prev.map((msg: ChatMessage) =>
-                    msg.id === messageId
-                      ? {
-                        ...finalizeStreamingReasoningInMessage(msg),
-                        streaming: false,
-                        durationMs,
-                        modelId: currentModelRef.current,
-                        outputTokens: finalMeta?.outputTokens,
-                        thinkingMs: finalMeta?.thinkingMs,
-                        thinkingText: finalMeta?.thinkingText || undefined,
-                      }
-                      : msg
-                  )
-                );
-              }
-              setParallelAgents([]);
-              stopSharedStreamState();
-              finalizeThinkingSourceTracking();
-              const resolver = streamCompletionResolverRef.current;
-              if (resolver) {
-                streamCompletionResolverRef.current = null;
-                // Remove the empty placeholder message when content was hidden
-                if (hideStreamContentRef.current && messageId) {
-                  setMessagesWindowed((prev: ChatMessage[]) => prev.filter((msg: ChatMessage) => msg.id !== messageId));
-                }
-                hideStreamContentRef.current = false;
-                resolver({ content: lastStreamingContentRef.current, wasInterrupted: true });
-                return;
-              }
-
-              continueQueuedConversation();
-              return;
-            }
-
-            // If foreground sub-agents or tools are still running, defer
-            // finalization until they complete (preserves correct state).
-            // Background agents are excluded — they must not block completion;
-            // they continue running after the main stream ends and are tracked
-            // separately via hasActiveBackgroundAgents.
-            const hasActiveAgents = hasActiveForegroundAgents(parallelAgentsRef.current);
-            if (hasActiveAgents || hasRunningToolRef.current) {
-              pendingCompleteRef.current = handleComplete;
-              return;
-            }
-
-            // Finalize running parallel agents and bake into message
-            setParallelAgents((currentAgents) => {
-              const finalizedAgents = currentAgents.length > 0
-                ? currentAgents.map((a) => {
-                  if (a.background) return a;
-                  return a.status === "running" || a.status === "pending"
-                    ? { ...a, status: "completed" as const, currentTool: undefined, durationMs: Date.now() - new Date(a.startedAt).getTime() }
-                    : a;
-                })
-                : undefined;
-
-              if (messageId) {
-                setMessagesWindowed((prev: ChatMessage[]) =>
-                  prev.map((msg: ChatMessage) =>
-                    msg.id === messageId
-                      ? {
-                        ...finalizeStreamingReasoningInMessage(msg),
-                        streaming: false,
-                        durationMs,
-                        modelId: currentModelRef.current,
-                        outputTokens: finalMeta?.outputTokens,
-                        thinkingMs: finalMeta?.thinkingMs,
-                        thinkingText: finalMeta?.thinkingText || undefined,
-                        toolCalls: interruptRunningToolCalls(msg.toolCalls),
-                        parallelAgents: finalizedAgents,
-                        taskItems: snapshotTaskItems(todoItemsRef.current) as TaskItem[] | undefined,
-                      }
-                      : msg
-                  )
-                );
-              }
-              // Keep background agents in live state for post-stream completion tracking
-              const remaining = getActiveBackgroundAgents(currentAgents);
-              if (remaining.length > 0 && messageId) {
-                backgroundAgentMessageIdRef.current = messageId;
-              }
-              return remaining;
-            });
-
-            // Preserve streamingStartRef when background agents are still running
-            // so the elapsed timer continues tracking total work duration
-            const hasRemainingBg = getActiveBackgroundAgents(parallelAgentsRef.current).length > 0;
-            stopSharedStreamState({ preserveStreamingStart: hasRemainingBg });
-            finalizeThinkingSourceTracking();
-
-            // If a streamAndWait call is pending, resolve its promise
-            // instead of processing the message queue.
-            const resolver = streamCompletionResolverRef.current;
-            if (resolver) {
-              streamCompletionResolverRef.current = null;
-              // Remove the empty placeholder message when content was hidden
-              if (hideStreamContentRef.current && messageId) {
-                setMessagesWindowed((prev: ChatMessage[]) => prev.filter((msg: ChatMessage) => msg.id !== messageId));
-              }
-              hideStreamContentRef.current = false;
-              resolver({ content: lastStreamingContentRef.current, wasInterrupted: false });
-              return;
-            }
-
-            continueQueuedConversation();
-          };
+      return false;
+    }
 
-          const handleMeta = (meta: StreamingMeta) => {
-            streamingMetaRef.current = meta;
-            setStreamingMeta(meta);
-            const messageId = streamingMessageIdRef.current;
-            if (!messageId) return;
-            const thinkingMetaEvent = resolveValidatedThinkingMetaEvent(
-              meta,
-              messageId,
-              currentGeneration,
-              closedThinkingSourcesRef.current,
-              thinkingDropDiagnosticsRef.current,
-            );
-            if (!thinkingMetaEvent) return;
-            setMessagesWindowed((prev: ChatMessage[]) =>
-              prev.map((msg: ChatMessage) =>
-                msg.id === messageId
-                  ? applyStreamPartEvent(msg, {
-                      type: "thinking-meta",
-                      thinkingSourceKey: thinkingMetaEvent.thinkingSourceKey,
-                      targetMessageId: thinkingMetaEvent.targetMessageId,
-                      streamGeneration: thinkingMetaEvent.streamGeneration,
-                      thinkingMs: meta.thinkingMs,
-                      thinkingText: thinkingMetaEvent.thinkingText,
-                      includeReasoningPart: true,
-                    })
-                  : msg
-              )
-            );
-          };
+    // Create the command context
+    const contextState: CommandContextState = {
+      isStreaming,
+      messageCount: messages.length,
+      workflowActive: workflowState.workflowActive,
+      workflowType: workflowState.workflowType,
+      initialPrompt: workflowState.initialPrompt,
+      currentNode: workflowState.currentNode,
+      iteration: workflowState.iteration,
+      maxIterations: workflowState.maxIterations,
+      featureProgress: workflowState.featureProgress,
+      pendingApproval: workflowState.pendingApproval,
+      specApproved: workflowState.specApproved,
+      feedback: workflowState.feedback,
+    };
 
-          void Promise.resolve(onStreamMessage(content, handleChunk, handleComplete, handleMeta, options)).catch((error) => {
-            handleStreamStartupError(error, currentGeneration);
-          });
+    const context: CommandContext = {
+      session: getSession?.() ?? null,
+      state: contextState,
+      addMessage,
+      setStreaming: setStreamingWithFinalize,
+      sendMessage: (content: string) => {
+        const trimmedContent = content.trim();
+        if (!trimmedContent) {
+          return;
         }
+        // Workflow/command runtime messages should not interrupt the active
+        // stream. Defer them and dispatch automatically when streaming settles.
+        if (shouldDeferComposerSubmit({
+          isStreaming: isStreamingRef.current,
+          runningAskQuestionToolCount: runningAskQuestionToolIdsRef.current.size,
+        })) {
+          deferredCommandQueueRef.current.push({ content: trimmedContent });
+          return;
+        }
+        // Use ref to call sendMessage without circular dependency
+        if (sendMessageRef.current) {
+          sendMessageRef.current(trimmedContent);
+        }
+      },
+      sendSilentMessage: (content: string, options?: import("./commands/registry.ts").StreamMessageOptions) => {
+        // Send to agent without displaying as user message
+        // Call send handler (fire and forget)
+        if (onSendMessage) {
+          void Promise.resolve(onSendMessage(content));
+        }
+        const prevStreamingId = streamingMessageIdRef.current;
+        if (prevStreamingId) {
+          setMessagesWindowed((prev: ChatMessage[]) => reconcilePreviousStreamingPlaceholder(prev, prevStreamingId));
+        }
+        startAssistantStream(content, options);
       },
       spawnSubagent: async (options) => {
         // Inject into main session — SDK's native sub-agent dispatch handles it.
         // Wait for the streaming response so the caller gets the actual result.
-        //
-        // IMPORTANT: For ralph review-fix loops, the sub-agent output must be
-        // clean JSON without additional commentary. We hide the stream content
-        // to avoid polluting the chat UI with intermediate steps.
+        // Stream content is rendered in the chat UI (same transcript + spinner as chat mode).
         const agentName = options.name ?? options.model ?? "general-purpose";
         const task = options.message;
 
@@ -3686,8 +5481,14 @@ export function ChatApp({
           // correct prompt parts without string encoding.
           instruction = task;
           silentOptions = { agent: agentName };
+        } else if (agentType === "claude") {
+          // Claude SDK dispatches sub-agents via `options.agent` on the
+          // query() call. Pass the agent name structurally so the client
+          // sets `options.agent = agentName`.
+          instruction = task;
+          silentOptions = { agent: agentName };
         } else {
-          // Claude SDK and Copilot SDK use the Task tool for sub-agent dispatch.
+          // Copilot SDK uses the Task tool for sub-agent dispatch.
           // Explicitly request the agent tool and ask for the complete output
           // to be passed through without additional commentary.
           instruction = `Invoke the "${agentName}" sub-agent with the following task. Return ONLY the sub-agent's complete output with no additional commentary or explanation.
@@ -3704,19 +5505,207 @@ Important: Do not add any text before or after the sub-agent's output. Pass thro
             previousResolver({ content: lastStreamingContentRef.current, wasInterrupted: true });
           }
           streamCompletionResolverRef.current = resolve;
-          // Hide stream content to keep chat UI clean (content is still accumulated)
-          hideStreamContentRef.current = true;
           context.sendSilentMessage(instruction, silentOptions);
         });
         
-        // Reset hideStreamContent for next stream
-        hideStreamContentRef.current = false;
-        
         return {
           success: !result.wasInterrupted,
           output: result.content,
         };
       },
+      spawnSubagentParallel: async (agents, externalAbortSignal) => {
+        if (!createSubagentSession) {
+          throw new Error("createSubagentSession not available. Cannot spawn parallel sub-agents.");
+        }
+
+        // Create an AbortController so Ctrl+C can cancel all sessions.
+        // Mark streaming as active so the Ctrl+C handler enters the abort path.
+        const parallelAbortController = new AbortController();
+        isStreamingRef.current = true;
+        setIsStreaming(true);
+        setStreamingState?.(true);
+
+        // Forward external abort signal if provided
+        if (externalAbortSignal) {
+          if (externalAbortSignal.aborted) {
+            parallelAbortController.abort();
+          } else {
+            externalAbortSignal.addEventListener(
+              "abort",
+              () => parallelAbortController.abort(),
+              { once: true },
+            );
+          }
+        }
+
+        // Register a stream completion resolver so Ctrl+C's streamResolver
+        // path can signal cancellation back to us.
+        const previousResolver = streamCompletionResolverRef.current;
+        streamCompletionResolverRef.current = (_result: import("./commands/registry.ts").StreamResult) => {
+          // Ctrl+C fires this resolver — abort all sessions
+          parallelAbortController.abort();
+        };
+
+        // Parent session ID for event bus publication — sub-agent events
+        // are published under the parent session so the correlation pipeline
+        // recognises them as owned events.
+        const parentSessionId = getSession?.()?.id ?? "workflow";
+        // Monotonic runId for staleness detection across all sub-agents
+        const subagentRunId = crypto.getRandomValues(new Uint32Array(1))[0]!;
+
+        // Register the parent session as owned so the correlation pipeline
+        // doesn't drop sub-agent events published with this sessionId.
+        const correlationServiceOuter = getCorrelationService();
+        correlationServiceOuter?.addOwnedSession(parentSessionId);
+
+        /**
+         * Spawn a single sub-agent by creating an isolated session,
+         * streaming its response through SubagentStreamAdapter, and
+         * destroying the session when done.
+         */
+        const spawnOne = async (options: SubagentSpawnOptions): Promise<SubagentStreamResult> => {
+          let session: import("../sdk/types.ts").Session | null = null;
+          const correlationService = getCorrelationService();
+          const startTime = Date.now();
+
+          try {
+            const sessionConfig: import("../sdk/types.ts").SessionConfig = {};
+            if (options.systemPrompt) sessionConfig.systemPrompt = options.systemPrompt;
+            if (options.model) sessionConfig.model = options.model;
+            if (options.tools) sessionConfig.tools = options.tools;
+
+            session = await createSubagentSession(sessionConfig);
+
+            // Set up per-agent abort controller with timeout support
+            const agentAbort = new AbortController();
+            let timeoutId: ReturnType<typeof setTimeout> | undefined;
+            if (options.timeout) {
+              timeoutId = setTimeout(() => agentAbort.abort(), options.timeout);
+            }
+            // Forward parent abort signal
+            const parentSignal = options.abortSignal ?? parallelAbortController.signal;
+            if (parentSignal.aborted) {
+              agentAbort.abort();
+            } else {
+              parentSignal.addEventListener("abort", () => agentAbort.abort(), { once: true });
+            }
+
+            // Ensure abort/timeout interrupts provider streams that are blocked
+            // awaiting SDK prompt completion (e.g. OpenCode sub-agent dispatch).
+            if (session.abort) {
+              const abortSession = () => {
+                void session?.abort?.().catch(() => {});
+              };
+              if (agentAbort.signal.aborted) {
+                abortSession();
+              } else {
+                agentAbort.signal.addEventListener("abort", abortSession, { once: true });
+              }
+            }
+
+            // Create SubagentStreamAdapter to bridge sub-agent SDK stream to the
+            // shared event bus. Events are published with the parent sessionId so
+            // the CorrelationService recognises and enriches them.
+            const adapter = new SubagentStreamAdapter({
+              bus: eventBus,
+              sessionId: parentSessionId,
+              agentId: options.agentId,
+              parentAgentId: parentSessionId,
+              runId: subagentRunId,
+              agentType: options.agentName,
+              task: options.task,
+            });
+
+            // Register with correlation service for event attribution
+            correlationService?.registerSubagent(options.agentId, {
+              parentAgentId: parentSessionId,
+              workflowRunId: String(subagentRunId),
+            });
+
+            try {
+              const stream = session.stream(options.task, {
+                agent: options.agentName,
+                abortSignal: agentAbort.signal,
+              });
+
+              // Adapter consumes stream, publishes events to the bus,
+              // and returns SubagentStreamResult with full metadata
+              const result = await adapter.consumeStream(stream, agentAbort.signal);
+
+              // If aborted, call session.abort() and refine the error message
+              if (agentAbort.signal.aborted && result.success) {
+                if (session.abort) {
+                  await session.abort().catch(() => {});
+                }
+                const wasExternalAbort = options.abortSignal?.aborted || parallelAbortController.signal.aborted;
+                return {
+                  ...result,
+                  success: false,
+                  error: wasExternalAbort
+                    ? `Sub-agent "${options.agentName}" was cancelled`
+                    : `Sub-agent "${options.agentName}" timed out after ${options.timeout}ms`,
+                };
+              }
+
+              return result;
+            } finally {
+              if (timeoutId) clearTimeout(timeoutId);
+              correlationService?.unregisterSubagent(options.agentId);
+            }
+          } catch (error) {
+            return {
+              agentId: options.agentId,
+              success: false,
+              output: "",
+              error: error instanceof Error ? error.message : String(error ?? "Unknown error"),
+              toolUses: 0,
+              durationMs: Date.now() - startTime,
+            };
+          } finally {
+            if (session) {
+              try { await session.destroy(); } catch { /* may already be destroyed */ }
+            }
+          }
+        };
+
+        try {
+          const results = await Promise.allSettled(
+            agents.map((agent) => spawnOne(agent))
+          );
+
+          return results.map((result, i) => {
+            if (result.status === "fulfilled") {
+              return result.value;
+            }
+            const agent = agents[i];
+            return {
+              agentId: agent?.agentId ?? `unknown-${i}`,
+              success: false,
+              output: "",
+              error: result.reason instanceof Error
+                ? result.reason.message
+                : String(result.reason ?? "Unknown error"),
+              toolUses: 0,
+              durationMs: 0,
+            };
+          });
+        } finally {
+          // Restore previous resolver (if any) and reset streaming flags
+          if (streamCompletionResolverRef.current === null) {
+            // Ctrl+C already cleared it — don't restore
+          } else {
+            streamCompletionResolverRef.current = previousResolver ?? null;
+          }
+          // During workflow execution, keep the streaming message alive so the
+          // spinner, sub-agent tree, and tool blocks continue rendering across
+          // graph step boundaries. The executor's setStreaming(false) call at
+          // workflow end handles final finalization.
+          if (!workflowActiveRef.current) {
+            setStreamingWithFinalize(false);
+            setStreamingState?.(false);
+          }
+        }
+      },
       streamAndWait: (prompt: string, options?: { hideContent?: boolean }) => {
         return new Promise<import("./commands/registry.ts").StreamResult>((resolve) => {
           const previousResolver = streamCompletionResolverRef.current;
@@ -3748,24 +5737,25 @@ Important: Do not add any text before or after the sub-agent's output. Pass thro
         // Restore todoItems (preserved across context clears)
         const saved = todoItemsRef.current;
         setTodoItems(saved);
-        // Restore ralph session state (preserved across context clears)
-        setRalphSessionDir(ralphSessionDirRef.current);
-        setRalphSessionId(ralphSessionIdRef.current);
+        // Restore workflow session state (preserved across context clears)
+        setWorkflowSessionDir(workflowSessionDirRef.current);
+        setWorkflowSessionId(workflowSessionIdRef.current);
       },
       setTodoItems: (items) => {
-        todoItemsRef.current = items;
-        setTodoItems(items);
+        const nextTodos = sortTasksTopologically(normalizeTodoItems(items));
+        todoItemsRef.current = nextTodos;
+        setTodoItems(nextTodos);
       },
-      setRalphSessionDir: (dir: string | null) => {
-        ralphSessionDirRef.current = dir;
-        setRalphSessionDir(dir);
+      setWorkflowSessionDir: (dir: string | null) => {
+        workflowSessionDirRef.current = dir;
+        setWorkflowSessionDir(dir);
       },
-      setRalphSessionId: (id: string | null) => {
-        ralphSessionIdRef.current = id;
-        setRalphSessionId(id);
+      setWorkflowSessionId: (id: string | null) => {
+        workflowSessionIdRef.current = id;
+        setWorkflowSessionId(id);
       },
-      setRalphTaskIds: (ids: Set<string>) => {
-        ralphTaskIdsRef.current = ids;
+      setWorkflowTaskIds: (ids: Set<string>) => {
+        workflowTaskIdsRef.current = ids;
       },
       updateWorkflowState: (update) => {
         updateWorkflowState(update);
@@ -3788,6 +5778,7 @@ Important: Do not add any text before or after the sub-agent's output. Pass thro
       setSessionMcpServers: (servers: McpServerConfig[]) => {
         onSessionMcpServersChange?.(servers);
       },
+      eventBus,
     };
 
     // Delayed spinner: show loading indicator if command takes >250ms
@@ -3816,7 +5807,7 @@ Important: Do not add any text before or after the sub-agent's output. Pass thro
           { messageId: msg.id, startedAt: Date.now() },
         );
 
-        streamingMessageIdRef.current = next.streamingMessageId;
+        setStreamingMessageId(next.streamingMessageId);
         streamingStartRef.current = next.streamingStart;
         streamingMetaRef.current = null;
         pendingCompleteRef.current = null;
@@ -3846,18 +5837,20 @@ Important: Do not add any text before or after the sub-agent's output. Pass thro
         // Reset UI state on session destroy (/clear)
         setCompactionSummary(null);
         setShowCompactionHistory(false);
-        applyAutoCompactionIndicator(AUTO_COMPACTION_INDICATOR_IDLE_STATE);
+        setIsAutoCompacting(false);
+        autoCompactionIndicatorRef.current = { status: "idle" };
         setParallelAgents([]);
+        backgroundProgressSnapshotRef.current.clear();
         setTranscriptMode(false);
         clearHistoryBuffer();
         loadedSkillsRef.current.clear();
-        // Reset ralph state on /clear (Copilot only)
+        // Reset workflow state on /clear (Copilot only)
         if (agentType === "copilot") {
-          setRalphSessionDir(null);
-          setRalphSessionId(null);
-          ralphSessionDirRef.current = null;
-          ralphSessionIdRef.current = null;
-          ralphTaskIdsRef.current = new Set();
+          setWorkflowSessionDir(null);
+          setWorkflowSessionId(null);
+          workflowSessionDirRef.current = null;
+          workflowSessionIdRef.current = null;
+          workflowTaskIdsRef.current = new Set();
           todoItemsRef.current = [];
           setTodoItems([]);
         }
@@ -3902,7 +5895,7 @@ Important: Do not add any text before or after the sub-agent's output. Pass thro
           pendingApproval: result.stateUpdate.pendingApproval !== undefined ? result.stateUpdate.pendingApproval : workflowState.pendingApproval,
           specApproved: result.stateUpdate.specApproved !== undefined ? result.stateUpdate.specApproved : workflowState.specApproved,
           feedback: result.stateUpdate.feedback !== undefined ? result.stateUpdate.feedback : workflowState.feedback,
-          ralphConfig: result.stateUpdate.ralphConfig !== undefined ? result.stateUpdate.ralphConfig : workflowState.ralphConfig,
+          workflowConfig: result.stateUpdate.workflowConfig !== undefined ? result.stateUpdate.workflowConfig : workflowState.workflowConfig,
         });
 
         // Also update isStreaming if specified
@@ -4015,7 +6008,7 @@ Important: Do not add any text before or after the sub-agent's output. Pass thro
         
         // Only reset streaming state if the current stream is still the spinner stream
         if (streamingMessageIdRef.current === msgId) {
-          stopSharedStreamState({ resetStreamingStateHook: false });
+          stopSharedStreamState();
         }
       }
 
@@ -4037,7 +6030,7 @@ Important: Do not add any text before or after the sub-agent's output. Pass thro
         
         // Only reset streaming state if the current stream is still the spinner stream
         if (streamingMessageIdRef.current === msgId) {
-          stopSharedStreamState({ resetStreamingStateHook: false });
+          stopSharedStreamState();
         }
       }
       // Handle execution error (as assistant message, not system)
@@ -4052,7 +6045,7 @@ Important: Do not add any text before or after the sub-agent's output. Pass thro
       });
       return false;
     }
-  }, [isStreaming, messages.length, workflowState, addMessage, updateWorkflowState, toggleTheme, setTheme, onSendMessage, onStreamMessage, getSession, model, onModelChange, onSessionMcpServersChange, onCommandExecutionTelemetry, mcpServerToggles, handleStreamStartupError, stopSharedStreamState, applyAutoCompactionIndicator]);
+  }, [isStreaming, messages.length, workflowState, addMessage, updateWorkflowState, toggleTheme, setTheme, onSendMessage, onStreamMessage, getSession, model, onModelChange, onSessionMcpServersChange, onCommandExecutionTelemetry, mcpServerToggles, handleStreamStartupError, setStreamingMessageId, stopSharedStreamState, applyAutoCompactionIndicator]);
 
   /**
    * Handle autocomplete selection (Tab for complete, Enter for execute).
@@ -4249,9 +6242,6 @@ Important: Do not add any text before or after the sub-agent's output. Pass thro
           // Use ref for immediate check — avoids stale closure when React
           // hasn't re-rendered after setIsStreaming(true)
           if (isStreamingRef.current) {
-            // Invalidate current stream callbacks before interrupting the SDK,
-            // so synchronous onComplete callbacks from an interrupt become stale.
-            streamGenerationRef.current = invalidateActiveStreamGeneration(streamGenerationRef.current);
             clearDeferredCompletion();
             // Abort the stream FIRST so chunks stop arriving immediately
             onInterrupt?.();
@@ -4269,6 +6259,11 @@ Important: Do not add any text before or after the sub-agent's output. Pass thro
 
             // Bake interrupted agents into message and stop streaming
             const interruptedId = streamingMessageIdRef.current;
+            // Capture duration before stopSharedStreamState nulls streamingStartRef
+            const durationMs = streamingStartRef.current
+              ? Date.now() - streamingStartRef.current
+              : undefined;
+            const finalMeta = streamingMetaRef.current;
             if (interruptedId) {
               setMessagesWindowed((prev: ChatMessage[]) =>
                 prev.map((msg: ChatMessage) =>
@@ -4277,9 +6272,14 @@ Important: Do not add any text before or after the sub-agent's output. Pass thro
                       ...finalizeStreamingReasoningInMessage(msg),
                       wasInterrupted: true,
                       streaming: false,
+                      durationMs,
+                      outputTokens: finalMeta?.outputTokens,
+                      thinkingMs: finalMeta?.thinkingMs,
+                      thinkingText: finalMeta?.thinkingText || undefined,
                       parallelAgents: interruptedAgents,
                       taskItems: interruptedTaskItems,
                       toolCalls: interruptRunningToolCalls(msg.toolCalls),
+                      parts: interruptRunningToolParts(finalizeStreamingReasoningParts(msg.parts ?? [], finalMeta?.thinkingMs || msg.thinkingMs)),
                     }
                     : msg
                 )
@@ -4374,6 +6374,7 @@ Important: Do not add any text before or after the sub-agent's output. Pass thro
                         parallelAgents: interruptedAgents,
                         taskItems: interruptedTaskItems,
                         toolCalls: interruptRunningToolCalls(msg.toolCalls),
+                        parts: interruptRunningToolParts(msg.parts),
                       }
                       : msg
                   )
@@ -4449,15 +6450,20 @@ Important: Do not add any text before or after the sub-agent's output. Pass thro
             return;
           }
 
+          if (backgroundTerminationInFlightRef.current) {
+            return;
+          }
+
           const currentAgents = parallelAgentsRef.current;
           const activeBackgroundAgents = getActiveBackgroundAgents(currentAgents);
-          const decision = getBackgroundTerminationDecision(
-            backgroundTerminationCount,
+          const pressEvaluation = evaluateBackgroundTerminationPress(
+            backgroundTerminationCountRef,
             activeBackgroundAgents.length,
           );
+          const decision = pressEvaluation.decision;
 
           console.debug("[background-termination] decision:", decision.action, {
-            pressCount: backgroundTerminationCount,
+            pressCount: pressEvaluation.pressCount,
             activeAgents: activeBackgroundAgents.length,
           });
 
@@ -4468,64 +6474,77 @@ Important: Do not add any text before or after the sub-agent's output. Pass thro
           }
 
           if (decision.action === "terminate") {
-            if (backgroundTerminationInFlightRef.current) {
-              return;
-            }
             backgroundTerminationInFlightRef.current = true;
             clearBackgroundTerminationConfirmation();
 
-            const { agents: interruptedAgents, interruptedIds } = interruptActiveBackgroundAgents(currentAgents);
-            if (interruptedIds.length === 0) {
-              backgroundTerminationInFlightRef.current = false;
-              return;
-            }
+            void executeBackgroundTermination({
+              getAgents: () => parallelAgentsRef.current,
+              onTerminateBackgroundAgents,
+            }).then((result) => {
+              if (result.status === "failed") {
+                console.error("[background-termination] parent callback failed:", result.error);
+                const errorMessage = result.error instanceof Error
+                  ? result.error.message
+                  : String(result.error ?? "Unknown error");
+                addMessage("system", `${STATUS.error} Failed to terminate background agents: ${errorMessage}`);
+                return;
+              }
 
-            console.debug("[background-termination] executing termination", {
-              interruptedIds,
-              remainingCount: currentAgents.filter((agent) => !new Set(interruptedIds).has(agent.id)).length,
-            });
+              if (result.status === "noop") {
+                return;
+              }
 
-            const interruptedIdSet = new Set(interruptedIds);
-            const remainingLiveAgents = currentAgents.filter((agent) => !interruptedIdSet.has(agent.id));
+              const interruptedIds = result.interruptedIds;
+              if (interruptedIds.length > 0) {
+                const interruptedIdSet = new Set(interruptedIds);
+                console.debug("[background-termination] executing termination", {
+                  interruptedIds,
+                  remainingCount: result.agents.filter((agent) => !interruptedIdSet.has(agent.id)).length,
+                });
 
-            const interruptedMessageId = backgroundAgentMessageIdRef.current ?? streamingMessageIdRef.current;
-            if (interruptedMessageId) {
-              setMessagesWindowed((prev: ChatMessage[]) =>
-                prev.map((msg: ChatMessage) =>
-                  msg.id === interruptedMessageId
-                    ? {
-                      ...msg,
-                      parallelAgents: interruptedAgents,
-                    }
-                    : msg
-                )
-              );
-            }
+                const remainingLiveAgents = result.agents.filter((agent) => !interruptedIdSet.has(agent.id));
+
+                const interruptedMessageId = backgroundAgentMessageIdRef.current
+                  ?? streamingMessageIdRef.current
+                  ?? lastStreamedMessageIdRef.current;
+                if (interruptedMessageId) {
+                  setMessagesWindowed((prev: ChatMessage[]) =>
+                    prev.map((msg: ChatMessage) =>
+                      msg.id === interruptedMessageId
+                        ? {
+                          ...msg,
+                          parallelAgents: result.agents,
+                        }
+                        : msg
+                    )
+                  );
+                }
 
-            parallelAgentsRef.current = remainingLiveAgents;
-            setParallelAgents(remainingLiveAgents);
-            backgroundAgentMessageIdRef.current = null;
-            streamingStartRef.current = null;
-            clearDeferredCompletion();
+                parallelAgentsRef.current = remainingLiveAgents;
+                setParallelAgents(remainingLiveAgents);
+                setBackgroundAgentMessageId(null);
+                // Preserve streamingStartRef during workflow so the timer persists.
+                if (!workflowActiveRef.current) {
+                  streamingStartRef.current = null;
+                }
+                clearDeferredCompletion();
+              }
 
-            void Promise.resolve(onTerminateBackgroundAgents?.()).catch((error) => {
-              console.error("[background-termination] parent callback failed:", error);
+              addMessage("system", `${STATUS.active} ${decision.message}`);
+            }).finally(() => {
+              backgroundTerminationInFlightRef.current = false;
             });
-            addMessage("assistant", `${STATUS.error} ${decision.message}`);
-            backgroundTerminationInFlightRef.current = false;
             return;
           }
 
           console.debug("[background-termination] armed: awaiting confirmation");
-          setBackgroundTerminationCount(1);
+          setBackgroundTerminationCount(pressEvaluation.nextPressCount);
           setCtrlFPressed(true);
           if (backgroundTerminationTimeoutRef.current) {
             clearTimeout(backgroundTerminationTimeoutRef.current);
           }
           backgroundTerminationTimeoutRef.current = setTimeout(() => {
-            setBackgroundTerminationCount(0);
-            setCtrlFPressed(false);
-            backgroundTerminationTimeoutRef.current = null;
+            clearBackgroundTerminationConfirmation();
           }, 1000);
           return;
         }
@@ -4536,6 +6555,12 @@ Important: Do not add any text before or after the sub-agent's output. Pass thro
           return;
         }
 
+        // Ctrl+E - toggle verbose mode (timestamps, model info on messages)
+        if (event.ctrl && event.name === "e") {
+          toggleVerbose();
+          return;
+        }
+
         // Ctrl+T - toggle todo list panel visibility
         if (event.ctrl && !event.shift && event.name === "t") {
           setShowTodoPanel(prev => !prev);
@@ -4573,9 +6598,6 @@ Important: Do not add any text before or after the sub-agent's output. Pass thro
           // Use ref for immediate check — avoids stale closure when React
           // hasn't re-rendered after setIsStreaming(true)
           if (isStreamingRef.current) {
-            // Invalidate current stream callbacks before interrupting the SDK,
-            // so synchronous onComplete callbacks from an interrupt become stale.
-            streamGenerationRef.current = invalidateActiveStreamGeneration(streamGenerationRef.current);
             clearDeferredCompletion();
             // Abort the stream FIRST so chunks stop arriving immediately
             onInterrupt?.();
@@ -4593,6 +6615,13 @@ Important: Do not add any text before or after the sub-agent's output. Pass thro
 
             // Bake interrupted agents into message and stop streaming
             const interruptedId = streamingMessageIdRef.current;
+            // Capture timing/meta BEFORE stopSharedStreamState() clears them
+            const frozenDurationMs = streamingStartRef.current
+              ? Date.now() - streamingStartRef.current
+              : undefined;
+            const frozenMeta = streamingMetaRef.current
+              ? { ...streamingMetaRef.current }
+              : undefined;
             if (interruptedId) {
               setMessagesWindowed((prev: ChatMessage[]) =>
                 prev.map((msg: ChatMessage) =>
@@ -4601,9 +6630,12 @@ Important: Do not add any text before or after the sub-agent's output. Pass thro
                       ...finalizeStreamingReasoningInMessage(msg),
                       wasInterrupted: true,
                       streaming: false,
+                      ...(frozenDurationMs != null && { durationMs: frozenDurationMs }),
+                      ...(frozenMeta && { streamingMeta: frozenMeta }),
                       parallelAgents: interruptedAgents,
                       taskItems: interruptedTaskItems,
                       toolCalls: interruptRunningToolCalls(msg.toolCalls),
+                      parts: interruptRunningToolParts(finalizeStreamingReasoningParts(msg.parts ?? [], frozenMeta?.thinkingMs || msg.thinkingMs)),
                     }
                     : msg
                 )
@@ -4660,6 +6692,7 @@ Important: Do not add any text before or after the sub-agent's output. Pass thro
                         parallelAgents: interruptedAgents,
                         taskItems: interruptedTaskItems,
                         toolCalls: interruptRunningToolCalls(msg.toolCalls),
+                        parts: interruptRunningToolParts(msg.parts),
                       }
                       : msg
                   )
@@ -4913,14 +6946,12 @@ Important: Do not add any text before or after the sub-agent's output. Pass thro
 
         // Shift+Enter or Alt+Enter - insert newline
         // (unless streaming + enqueue shortcut is used)
-        // Must be handled here (before autocomplete Enter handler) with stopPropagation
-        // to prevent the textarea's built-in "return → submit" key binding from firing.
-        // Ctrl+J (linefeed without shift) also inserts newline as a universal fallback
-        // for terminals that don't support the Kitty keyboard protocol.
-        // Fallback: some terminals send Shift+Enter as a Kitty-protocol escape sequence
-        // that gets misinterpreted (e.g., "/" extracted from the CSI sequence).
-        // Detect by checking event.raw for Enter codepoint (13/10) with a modifier.
-        if (isStreamingRef.current && shouldEnqueueMessageFromKeyEvent(event)) {
+        // Standard modifier+Enter newlines (Shift+Enter, Alt+Enter, Ctrl+J) are
+        // now handled by the OpenTUI textarea's keyBindings prop, so they are NOT
+        // intercepted here. Only the enqueue shortcut (Ctrl/Cmd+Shift+Enter) and
+        // terminal-specific fallbacks (CSI-u, modifyOtherKeys) are handled in
+        // this global hook with stopPropagation.
+        if (shouldEnqueueMessageFromKeyEvent(event)) {
           const textarea = textareaRef.current;
           const value = textarea?.plainText?.trim() ?? "";
           if (value) {
@@ -4934,6 +6965,8 @@ Important: Do not add any text before or after the sub-agent's output. Pass thro
               hasAgentMentions,
             });
             messageQueue.enqueue(value);
+            // Auto-dispatch if no stream is active (e.g. first message in session)
+            continueQueuedConversation();
             if (textarea) {
               textarea.gotoBufferHome();
               textarea.gotoBufferEnd({ select: true });
@@ -4944,7 +6977,11 @@ Important: Do not add any text before or after the sub-agent's output. Pass thro
           return;
         }
 
-        if (shouldInsertNewlineFromKeyEvent(event)) {
+        // Terminal-specific fallback: handle escape-sequence-based newlines
+        // (CSI-u / modifyOtherKeys) that the textarea's keyBindings can't match.
+        // Standard shift+enter / meta+enter / Ctrl+J newlines are delegated to
+        // the OpenTUI textarea's keyBindings (see textareaKeyBindings above).
+        if (shouldInsertNewlineFallbackFromKeyEvent(event)) {
           const textarea = textareaRef.current;
           if (textarea) {
             textarea.insertText("\n");
@@ -5125,7 +7162,6 @@ Important: Do not add any text before or after the sub-agent's output. Pass thro
         onTerminateBackgroundAgents,
         isStreaming,
         interruptCount,
-        backgroundTerminationCount,
         handleCopy,
         workflowState.showAutocomplete,
         workflowState.selectedSuggestionIndex,
@@ -5189,183 +7225,9 @@ Important: Do not add any text before or after the sub-agent's output. Pass thro
       if (onSendMessage) {
         void Promise.resolve(onSendMessage(content));
       }
-
-      // Handle streaming response if handler provided
-      if (onStreamMessage) {
-        // Increment stream generation so stale handleComplete callbacks become no-ops
-        const currentGeneration = ++streamGenerationRef.current;
-        // Set ref immediately (synchronous) so handleSubmit can check it
-        isStreamingRef.current = true;
-        setIsStreaming(true);
-        // Track when streaming started for duration calculation
-        streamingStartRef.current = Date.now();
-        // Reset streaming metadata
-        resetThinkingSourceTracking();
-        // Clear stale todo items from previous turn when not in /ralph
-        resetTodoItemsForNewStream();
-        // Reset tool tracking for the new stream
-        hasRunningToolRef.current = false;
-        clearDeferredCompletion();
-
-        // Create placeholder assistant message
-        const assistantMessage = createMessage("assistant", "", true);
-        streamingMessageIdRef.current = assistantMessage.id;
-        isAgentOnlyStreamRef.current = false;
-        setMessagesWindowed((prev: ChatMessage[]) => [...prev, assistantMessage]);
-
-        // Handle stream chunks — guarded by ref to drop post-interrupt chunks
-        const handleChunk = (chunk: string) => {
-          if (!isStreamingRef.current) return;
-          // Drop chunks from stale streams (round-robin replaced this stream)
-          if (!isCurrentStreamCallback(streamGenerationRef.current, currentGeneration)) return;
-          if (pendingCompleteRef.current) {
-            clearDeferredCompletion();
-          }
-          const messageId = streamingMessageIdRef.current;
-          if (messageId) {
-            setMessagesWindowed((prev: ChatMessage[]) =>
-              prev.map((msg: ChatMessage) => {
-                if (msg.id === messageId) {
-                  return applyStreamPartEvent(msg, { type: "text-delta", delta: chunk });
-                }
-                return msg;
-              })
-            );
-          }
-        };
-
-        // Handle stream completion - process next queued message after delay
-        const handleComplete = () => {
-          // Stale generation guard — a newer stream has started (round-robin inject),
-          // so this callback must not touch any shared refs/state.
-          if (!isCurrentStreamCallback(streamGenerationRef.current, currentGeneration)) return;
-          const messageId = streamingMessageIdRef.current;
-          // Calculate duration from streaming start
-          const durationMs = streamingStartRef.current
-            ? Date.now() - streamingStartRef.current
-            : undefined;
-          // Capture streaming meta before clearing
-          const finalMeta = streamingMetaRef.current;
-
-          // If the interrupt handler already finalized agents, skip overwriting
-          if (wasInterruptedRef.current) {
-            wasInterruptedRef.current = false;
-            if (messageId) {
-              setMessagesWindowed((prev: ChatMessage[]) =>
-                prev.map((msg: ChatMessage) =>
-                  msg.id === messageId
-                    ? {
-                      ...finalizeStreamingReasoningInMessage(msg),
-                      streaming: false,
-                      durationMs,
-                      modelId: currentModelRef.current,
-                      outputTokens: finalMeta?.outputTokens,
-                      thinkingMs: finalMeta?.thinkingMs,
-                      thinkingText: finalMeta?.thinkingText || undefined,
-                    }
-                    : msg
-                )
-              );
-            }
-            setParallelAgents([]);
-            stopSharedStreamState();
-            finalizeThinkingSourceTracking();
-            return;
-          }
-
-          // If foreground sub-agents or tools are still running, defer
-          // finalization until they complete (preserves correct state).
-          // Background agents are excluded — they must not block completion;
-          // they continue running after the main stream ends and are tracked
-          // separately via hasActiveBackgroundAgents.
-          const hasActiveAgents = hasActiveForegroundAgents(parallelAgentsRef.current);
-          if (hasActiveAgents || hasRunningToolRef.current) {
-            pendingCompleteRef.current = handleComplete;
-            return;
-          }
-
-          // Finalize running parallel agents and bake into message
-          setParallelAgents((currentAgents) => {
-            const finalizedAgents = currentAgents.length > 0
-              ? currentAgents.map((a) => {
-                if (a.background) return a;
-                return a.status === "running" || a.status === "pending"
-                  ? { ...a, status: "completed" as const, currentTool: undefined, durationMs: Date.now() - new Date(a.startedAt).getTime() }
-                  : a;
-              })
-              : undefined;
-
-            if (messageId) {
-              setMessagesWindowed((prev: ChatMessage[]) =>
-                prev.map((msg: ChatMessage) =>
-                  msg.id === messageId
-                    ? {
-                      ...finalizeStreamingReasoningInMessage(msg),
-                      streaming: false,
-                      durationMs,
-                      modelId: currentModelRef.current,
-                      outputTokens: finalMeta?.outputTokens,
-                      thinkingMs: finalMeta?.thinkingMs,
-                      thinkingText: finalMeta?.thinkingText || undefined,
-                      toolCalls: interruptRunningToolCalls(msg.toolCalls),
-                      parallelAgents: finalizedAgents,
-                      taskItems: snapshotTaskItems(todoItemsRef.current) as TaskItem[] | undefined,
-                    }
-                    : msg
-                )
-              );
-            }
-            // Keep background agents in live state for post-stream completion tracking
-            const remaining = getActiveBackgroundAgents(currentAgents);
-            if (remaining.length > 0 && messageId) {
-              backgroundAgentMessageIdRef.current = messageId;
-            }
-            return remaining;
-          });
-
-          const hasRemainingBg = getActiveBackgroundAgents(parallelAgentsRef.current).length > 0;
-          stopSharedStreamState({ preserveStreamingStart: hasRemainingBg });
-          finalizeThinkingSourceTracking();
-          continueQueuedConversation();
-        };
-
-        // Handle streaming metadata updates (tokens, thinking duration)
-        const handleMeta = (meta: StreamingMeta) => {
-          streamingMetaRef.current = meta;
-          setStreamingMeta(meta);
-          const messageId = streamingMessageIdRef.current;
-          if (!messageId) return;
-          const thinkingMetaEvent = resolveValidatedThinkingMetaEvent(
-            meta,
-            messageId,
-            currentGeneration,
-            closedThinkingSourcesRef.current,
-            thinkingDropDiagnosticsRef.current,
-          );
-          if (!thinkingMetaEvent) return;
-          setMessagesWindowed((prev: ChatMessage[]) =>
-            prev.map((msg: ChatMessage) =>
-              msg.id === messageId
-                ? applyStreamPartEvent(msg, {
-                    type: "thinking-meta",
-                    thinkingSourceKey: thinkingMetaEvent.thinkingSourceKey,
-                    targetMessageId: thinkingMetaEvent.targetMessageId,
-                    streamGeneration: thinkingMetaEvent.streamGeneration,
-                    thinkingMs: meta.thinkingMs,
-                    thinkingText: thinkingMetaEvent.thinkingText,
-                    includeReasoningPart: true,
-                  })
-                : msg
-            )
-          );
-        };
-
-        void Promise.resolve(onStreamMessage(content, handleChunk, handleComplete, handleMeta)).catch((error) => {
-          handleStreamStartupError(error, currentGeneration);
-        });
-      }
+      startAssistantStream(content);
     },
-    [onSendMessage, onStreamMessage, continueQueuedConversation, handleStreamStartupError, stopSharedStreamState, finalizeThinkingSourceTracking, resetThinkingSourceTracking]
+    [onSendMessage, setMessagesWindowed, startAssistantStream]
   );
 
   // Keep the sendMessageRef in sync with sendMessage callback
@@ -5491,13 +7353,13 @@ Important: Do not add any text before or after the sub-agent's output. Pass thro
       // Check if this is a slash command
       const parsed = parseSlashCommand(trimmedValue);
       if (parsed.isCommand) {
-        // Dismiss ralph panel when user sends a non-ralph slash command (Copilot only)
-        if (agentType === "copilot" && ralphSessionDirRef.current && parsed.name !== "ralph") {
-          setRalphSessionDir(null);
-          setRalphSessionId(null);
-          ralphSessionDirRef.current = null;
-          ralphSessionIdRef.current = null;
-          ralphTaskIdsRef.current = new Set();
+        // Dismiss workflow panel when user sends a non-workflow slash command (Copilot only)
+        if (agentType === "copilot" && workflowSessionDirRef.current && parsed.name !== "ralph") {
+          setWorkflowSessionDir(null);
+          setWorkflowSessionId(null);
+          workflowSessionDirRef.current = null;
+          workflowSessionIdRef.current = null;
+          workflowTaskIdsRef.current = new Set();
           todoItemsRef.current = [];
           setTodoItems([]);
         }
@@ -5512,20 +7374,25 @@ Important: Do not add any text before or after the sub-agent's output. Pass thro
       // If a workflow is waiting for user input (after Ctrl+C stream interrupt),
       // resolve the pending promise with the user's prompt instead of sending normally.
       if (waitForUserInputResolverRef.current) {
-        const { resolve } = waitForUserInputResolverRef.current;
-        waitForUserInputResolverRef.current = null;
-        addMessage("user", trimmedValue);
-        resolve(trimmedValue);
-        return;
+        const workflowInput = consumeWorkflowInputSubmission(
+          waitForUserInputResolverRef.current,
+          workflowState.workflowActive,
+          trimmedValue,
+        );
+        waitForUserInputResolverRef.current = workflowInput.nextResolver;
+        if (workflowInput.consumed) {
+          addMessage("user", trimmedValue);
+          return;
+        }
       }
 
-      // Dismiss ralph panel when user sends a non-ralph message (Copilot only)
-      if (agentType === "copilot" && ralphSessionDirRef.current && !trimmedValue.startsWith("/ralph")) {
-        setRalphSessionDir(null);
-        setRalphSessionId(null);
-        ralphSessionDirRef.current = null;
-        ralphSessionIdRef.current = null;
-        ralphTaskIdsRef.current = new Set();
+      // Dismiss workflow panel when user sends a non-workflow message (Copilot only)
+      if (agentType === "copilot" && workflowSessionDirRef.current && !trimmedValue.startsWith("/ralph")) {
+        setWorkflowSessionDir(null);
+        setWorkflowSessionId(null);
+        workflowSessionDirRef.current = null;
+        workflowSessionIdRef.current = null;
+        workflowTaskIdsRef.current = new Set();
         todoItemsRef.current = [];
         setTodoItems([]);
       }
@@ -5557,21 +7424,9 @@ Important: Do not add any text before or after the sub-agent's output. Pass thro
             hasAgentMentions: true,
           });
           addMessage("user", trimmedValue);
-
-          // Create a streaming assistant message immediately so the parallel
-          // agents tree view renders right away instead of waiting for the
-          // next user message.  The message acts as a placeholder that is
-          // finalised when all spawned sub-agents complete (see the
-          // parallelAgents useEffect).
-          const assistantMsg = createMessage("assistant", "", true);
-          streamingMessageIdRef.current = assistantMsg.id;
-          isAgentOnlyStreamRef.current = true;
+          // Set streaming state immediately so loading hints render on submit.
           isStreamingRef.current = true;
-          streamingStartRef.current = Date.now();
-          resetThinkingSourceTracking();
           setIsStreaming(true);
-          resetTodoItemsForNewStream();
-          setMessagesWindowed((prev) => [...prev, assistantMsg]);
 
           for (const mention of atMentions) {
             void executeCommand(mention.agentName, mention.args, "mention");
@@ -5584,22 +7439,18 @@ Important: Do not add any text before or after the sub-agent's output. Pass thro
       const { message: processedValue, filesRead } = processFileMentions(trimmedValue);
       const hasFileMentions = filesRead.length > 0;
 
-      // If streaming, interrupt: inject immediately unless sub-agents are active
+      // If streaming, always interrupt: cancel active stream and send new message immediately.
+      // Background agents are preserved — they continue running independently.
       if (isStreamingRef.current) {
-        // Defer interrupt if sub-agents are actively working — fires when they finish
-        // Background agents are excluded — they must not block interrupt.
-        const hasActiveSubagents = hasActiveForegroundAgents(parallelAgentsRef.current);
-        if (hasActiveSubagents) {
-          emitMessageSubmitTelemetry({
-            messageLength: trimmedValue.length,
-            queued: true,
-            fromInitialPrompt: false,
-            hasFileMentions,
-            hasAgentMentions: false,
-          });
-          messageQueue.enqueue(processedValue);
-          return;
-        }
+        clearDeferredCompletion();
+
+        // Separate foreground agents (interrupt) from background agents (preserve)
+        const currentAgents = parallelAgentsRef.current;
+        const { interruptedAgents, remainingLiveAgents } = separateAndInterruptAgents(currentAgents);
+
+        // Keep background agents alive in refs
+        parallelAgentsRef.current = remainingLiveAgents;
+        setParallelAgents(remainingLiveAgents);
 
         // Round-robin inject: finalize current stream and send new message immediately
         const interruptedId = streamingMessageIdRef.current;
@@ -5612,6 +7463,7 @@ Important: Do not add any text before or after the sub-agent's output. Pass thro
               msg.id === interruptedId
                 ? {
                   ...finalizeStreamingReasoningInMessage(msg),
+                  wasInterrupted: true,
                   streaming: false,
                   durationMs,
                   modelId: currentModelRef.current,
@@ -5619,14 +7471,14 @@ Important: Do not add any text before or after the sub-agent's output. Pass thro
                   thinkingMs: finalMeta?.thinkingMs,
                   thinkingText: finalMeta?.thinkingText || undefined,
                   toolCalls: interruptRunningToolCalls(msg.toolCalls),
+                  parts: interruptRunningToolParts(finalizeStreamingReasoningParts(msg.parts ?? [], finalMeta?.thinkingMs || msg.thinkingMs)),
                   taskItems: interruptedTaskItems,
+                  parallelAgents: interruptedAgents,
                 }
                 : msg
             )
           );
         }
-        // Invalidate callbacks for the interrupted stream before aborting.
-        streamGenerationRef.current = invalidateActiveStreamGeneration(streamGenerationRef.current);
         stopSharedStreamState();
         finalizeThinkingSourceTracking();
 
@@ -5667,72 +7519,50 @@ Important: Do not add any text before or after the sub-agent's output. Pass thro
       });
       sendMessage(processedValue);
     },
-    [workflowState.showAutocomplete, workflowState.argumentHint, updateWorkflowState, addMessage, executeCommand, messageQueue, sendMessage, model, onInterrupt, emitMessageSubmitTelemetry, finalizeTaskItemsOnInterrupt, stopSharedStreamState, finalizeThinkingSourceTracking, resetThinkingSourceTracking]
+    [workflowState.showAutocomplete, workflowState.argumentHint, updateWorkflowState, addMessage, executeCommand, messageQueue, sendMessage, model, onInterrupt, emitMessageSubmitTelemetry, finalizeTaskItemsOnInterrupt, stopSharedStreamState, finalizeThinkingSourceTracking, resetThinkingSourceTracking, clearDeferredCompletion, separateAndInterruptAgents]
   );
 
   // All messages are kept in memory; no windowing/eviction.
-  const renderMessages = messages;
+  // Hide stale empty assistant placeholders that only contain duplicated
+  // sub-agent task tool cards from older stream targeting races.
+  const activeMessageIds = new Set<string>();
+  if (streamingMessageIdRef.current) activeMessageIds.add(streamingMessageIdRef.current);
+  if (lastStreamedMessageIdRef.current) activeMessageIds.add(lastStreamedMessageIdRef.current);
+  if (backgroundAgentMessageIdRef.current) activeMessageIds.add(backgroundAgentMessageIdRef.current);
+  const renderMessages = messages.filter(
+    (message) => !shouldHideStaleSubagentToolPlaceholder(message, activeMessageIds),
+  );
   const footerBackgroundAgents = useMemo(
     () => resolveBackgroundAgentsForFooter(parallelAgents, messages),
     [parallelAgents, messages],
   );
 
-  // Auto-collapse boundary: messages before this index render as single-line summaries
-  const collapseBoundaryIndex = Math.max(0, renderMessages.length - EXPANDED_MESSAGE_COUNT);
-
   // Render message list (no empty state text)
   const messageContent = renderMessages.length > 0 ? (
     <>
-      {/* Collapsed messages (older, auto-collapsed to single-line summaries) */}
-      {renderMessages.slice(0, collapseBoundaryIndex).map((msg) => {
-        const liveTaskItems = msg.streaming ? todoItems : undefined;
-        const showLive = shouldShowMessageLoadingIndicator(msg, liveTaskItems);
-        return (
-        <MessageBubble
-          key={msg.id}
-          message={msg}
-          isLast={false}
-          syntaxStyle={markdownSyntaxStyle}
-          hideAskUserQuestion={activeQuestion !== null}
-          hideLoading={activeQuestion !== null}
-          todoItems={msg.streaming ? todoItems : undefined}
-          elapsedMs={showLive ? streamingElapsedMs : undefined}
-          streamingMeta={msg.streaming ? streamingMeta : null}
-          collapsed={!showLive}
-          tasksExpanded={tasksExpanded}
-          inlineTasksEnabled={!ralphSessionDir}
-          ralphSessionDir={ralphSessionDir}
-          showTodoPanel={showTodoPanel}
-        />
-        );
-      })}
-      {/* Separator between collapsed and expanded sections */}
-      {collapseBoundaryIndex > 0 && (
-        <box paddingLeft={SPACING.CONTAINER_PAD} marginBottom={SPACING.ELEMENT}>
-          <text style={{ fg: themeColors.dim }}>
-            {"─".repeat(3)} {collapseBoundaryIndex} earlier {"─".repeat(3)}
-          </text>
-        </box>
-      )}
-      {/* Expanded messages (recent, full rendering) */}
-      {renderMessages.slice(collapseBoundaryIndex).map((msg, index) => {
+      {renderMessages.map((msg, index) => {
         const liveTaskItems = msg.streaming ? todoItems : undefined;
         const showLive = shouldShowMessageLoadingIndicator(msg, liveTaskItems);
+        const scopedStreamingMeta = showLive
+          ? (streamingMessageIdRef.current
+              ? (msg.id === streamingMessageIdRef.current ? streamingMeta : null)
+              : streamingMeta)
+          : null;
         return (
         <MessageBubble
           key={msg.id}
           message={msg}
-          isLast={collapseBoundaryIndex + index === renderMessages.length - 1}
+          isLast={index === renderMessages.length - 1}
           syntaxStyle={markdownSyntaxStyle}
           hideAskUserQuestion={activeQuestion !== null}
           hideLoading={activeQuestion !== null}
           todoItems={msg.streaming ? todoItems : undefined}
           elapsedMs={showLive ? streamingElapsedMs : undefined}
-          streamingMeta={msg.streaming ? streamingMeta : null}
+          streamingMeta={scopedStreamingMeta}
           collapsed={false}
           tasksExpanded={tasksExpanded}
-          inlineTasksEnabled={!ralphSessionDir}
-          ralphSessionDir={ralphSessionDir}
+          workflowSessionDir={workflowSessionDir}
+          workflowActive={workflowState.workflowActive}
           showTodoPanel={showTodoPanel}
         />
         );
@@ -5760,7 +7590,6 @@ Important: Do not add any text before or after the sub-agent's output. Pass thro
         <TranscriptView
           messages={[...readHistoryBuffer(), ...messages]}
           liveThinkingText={streamingMeta?.thinkingText}
-          liveParallelAgents={parallelAgents}
           modelId={currentModelId ?? initialModelId ?? model}
           isStreaming={isStreaming}
           streamingMeta={streamingMeta}
@@ -5889,75 +7718,14 @@ Important: Do not add any text before or after the sub-agent's output. Pass thro
                 </box>
               )}
             </box>
-            {shouldShowAutoCompactionIndicator(autoCompactionIndicator) && (
-              <box paddingLeft={SPACING.CONTAINER_PAD} flexDirection="row" gap={SPACING.ELEMENT} flexShrink={0}>
-                <text style={{ fg: themeColors.muted }}>
-                  auto-compaction
-                </text>
-                <text style={{ fg: themeColors.muted }}>{MISC.separator}</text>
-                <text
-                  style={{
-                    fg: autoCompactionIndicator.status === "running"
-                      ? themeColors.accent
-                      : autoCompactionIndicator.status === "completed"
-                        ? themeColors.success
-                        : themeColors.error,
-                  }}
-                >
-                  {getAutoCompactionIndicatorLabel(autoCompactionIndicator)}
-                </text>
-              </box>
-            )}
-            {/* Streaming/workflow hints */}
-            {isStreaming && !workflowState.workflowActive ? (
-              <box paddingLeft={SPACING.CONTAINER_PAD} flexDirection="row" gap={SPACING.ELEMENT} flexShrink={0}>
-                <text style={{ fg: themeColors.muted }}>
-                  esc to interrupt
-                </text>
-                <text style={{ fg: themeColors.muted }}>{MISC.separator}</text>
-                <text style={{ fg: themeColors.muted }}>
-                  {enqueueShortcutLabel} enqueue
-                </text>
-                {footerBackgroundAgents.length > 0 && (
-                  <>
-                    <text style={{ fg: themeColors.muted }}>{MISC.separator}</text>
-                    <text style={{ fg: themeColors.accent }}>
-                      {formatBackgroundAgentFooterStatus(footerBackgroundAgents)}
-                    </text>
-                    <text style={{ fg: themeColors.dim }}>{MISC.separator} {BACKGROUND_FOOTER_CONTRACT.terminateHintText}</text>
-                  </>
-                )}
-              </box>
-            ) : null}
-            {/* Workflow mode label with hints - shown when workflow is active */}
-            {workflowState.workflowActive && (
-              <box paddingLeft={SPACING.CONTAINER_PAD} flexDirection="row" gap={SPACING.ELEMENT} flexShrink={0}>
-                <text style={{ fg: themeColors.accent }}>
-                  workflow
-                </text>
-                <text style={{ fg: themeColors.muted }}>{MISC.separator}</text>
-                <text style={{ fg: themeColors.muted }}>
-                  esc to interrupt
-                </text>
-                <text style={{ fg: themeColors.muted }}>{MISC.separator}</text>
-                <text style={{ fg: themeColors.muted }}>
-                  {enqueueShortcutLabel} enqueue
-                </text>
-                <text style={{ fg: themeColors.muted }}>{MISC.separator}</text>
-                <text style={{ fg: themeColors.muted }}>
-                  ctrl+c twice to exit workflow
-                </text>
-                {footerBackgroundAgents.length > 0 && (
-                  <>
-                    <text style={{ fg: themeColors.muted }}>{MISC.separator}</text>
-                    <text style={{ fg: themeColors.accent }}>
-                      {formatBackgroundAgentFooterStatus(footerBackgroundAgents)}
-                    </text>
-                    <text style={{ fg: themeColors.dim }}>{MISC.separator} {BACKGROUND_FOOTER_CONTRACT.terminateHintText}</text>
-                  </>
-                )}
-              </box>
-            )}
+            {/* Auto-compaction spinner is now shown via spinnerVerb override on the streaming message above */}
+            {/* Footer status bar */}
+            <FooterStatus
+              isStreaming={isStreaming}
+              workflowActive={workflowState.workflowActive}
+              enqueueShortcutLabel={enqueueShortcutLabel}
+              backgroundAgents={footerBackgroundAgents}
+            />
           </>
         )}
 
diff --git a/src/ui/chat.turn-lifecycle.test.ts b/src/ui/chat.turn-lifecycle.test.ts
new file mode 100644
index 0000000000..91a4f28bd9
--- /dev/null
+++ b/src/ui/chat.turn-lifecycle.test.ts
@@ -0,0 +1,118 @@
+/**
+ * Tests for turn lifecycle event wiring in chat.tsx
+ *
+ * Validates that useBusSubscription handlers for stream.turn.start and
+ * stream.turn.end behave correctly:
+ * - stream.turn.start: ensures streaming state is active (safety-net)
+ * - stream.turn.end: flushes batched events at the turn boundary
+ *
+ * These are unit tests of the handler logic patterns, not React component
+ * tests. The actual useBusSubscription hooks are integration-tested via
+ * the event bus integration test suite.
+ */
+
+import { describe, expect, test, mock, beforeEach } from "bun:test";
+
+// ---------------------------------------------------------------------------
+// Handler logic extracted from chat.tsx useBusSubscription patterns
+// ---------------------------------------------------------------------------
+
+interface TurnStartState {
+  isStreamingRef: { current: boolean };
+  streamingStartRef: { current: number | null };
+  setIsStreaming: (v: boolean) => void;
+}
+
+/**
+ * Mirrors the stream.turn.start handler in chat.tsx.
+ */
+function handleTurnStart(state: TurnStartState): void {
+  if (!state.isStreamingRef.current) {
+    state.isStreamingRef.current = true;
+    state.setIsStreaming(true);
+    if (!state.streamingStartRef.current) {
+      state.streamingStartRef.current = Date.now();
+    }
+  }
+}
+
+interface TurnEndState {
+  isStreamingRef: { current: boolean };
+  batchDispatcher: { flush: () => void };
+}
+
+/**
+ * Mirrors the stream.turn.end handler in chat.tsx.
+ */
+function handleTurnEnd(state: TurnEndState): void {
+  if (state.isStreamingRef.current) {
+    state.batchDispatcher.flush();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("stream.turn.start handler", () => {
+  let state: TurnStartState;
+
+  beforeEach(() => {
+    state = {
+      isStreamingRef: { current: false },
+      streamingStartRef: { current: null },
+      setIsStreaming: mock(() => {}),
+    };
+  });
+
+  test("activates streaming state when not already streaming", () => {
+    handleTurnStart(state);
+
+    expect(state.isStreamingRef.current).toBe(true);
+    expect(state.setIsStreaming).toHaveBeenCalledWith(true);
+    expect(state.streamingStartRef.current).toBeGreaterThan(0);
+  });
+
+  test("preserves existing streamingStartRef when already set", () => {
+    const existingStart = Date.now() - 5000;
+    state.streamingStartRef.current = existingStart;
+
+    handleTurnStart(state);
+
+    expect(state.isStreamingRef.current).toBe(true);
+    expect(state.streamingStartRef.current).toBe(existingStart);
+  });
+
+  test("is a no-op when already streaming", () => {
+    state.isStreamingRef.current = true;
+
+    handleTurnStart(state);
+
+    expect(state.setIsStreaming).not.toHaveBeenCalled();
+  });
+});
+
+describe("stream.turn.end handler", () => {
+  let state: TurnEndState;
+
+  beforeEach(() => {
+    state = {
+      isStreamingRef: { current: true },
+      batchDispatcher: { flush: mock(() => {}) },
+    };
+  });
+
+  test("flushes batch dispatcher when streaming", () => {
+    handleTurnEnd(state);
+
+    expect(state.batchDispatcher.flush).toHaveBeenCalledTimes(1);
+  });
+
+  test("does not flush when not streaming", () => {
+    state.isStreamingRef.current = false;
+
+    handleTurnEnd(state);
+
+    expect(state.batchDispatcher.flush).not.toHaveBeenCalled();
+  });
+});
diff --git a/src/ui/code-block.tsx b/src/ui/code-block.tsx
deleted file mode 100644
index 0d6d569c2d..0000000000
--- a/src/ui/code-block.tsx
+++ /dev/null
@@ -1,268 +0,0 @@
-/**
- * Code Block Component
- *
- * React component for syntax-highlighted code blocks using OpenTUI.
- * Supports streaming updates and language detection.
- *
- * Reference: Feature 18 - Add syntax-highlighted code blocks via CodeRenderable
- */
-
-import React from "react";
-import type { SyntaxStyle } from "@opentui/core";
-import { useThemeColors } from "./theme.tsx";
-
-// ============================================================================
-// TYPES
-// ============================================================================
-
-/**
- * Props for the CodeBlock component.
- */
-export interface CodeBlockProps {
-  /** The code content to display */
-  content: string;
-  /** Programming language for syntax highlighting (e.g., "typescript", "python") */
-  language?: string;
-  /** Whether the code is currently streaming */
-  streaming?: boolean;
-  /** Syntax style for highlighting (required for syntax highlighting) */
-  syntaxStyle?: SyntaxStyle;
-  /** Whether to show line numbers */
-  showLineNumbers?: boolean;
-  /** Title to display above the code block */
-  title?: string;
-}
-
-/**
- * Parsed code block from markdown content.
- */
-export interface ParsedCodeBlock {
-  /** The code content */
-  content: string;
-  /** Programming language identifier */
-  language: string;
-  /** Start index in original text */
-  startIndex: number;
-  /** End index in original text */
-  endIndex: number;
-}
-
-// ============================================================================
-// HELPER FUNCTIONS
-// ============================================================================
-
-/**
- * Map common language aliases to standard filetype identifiers.
- */
-export function normalizeLanguage(language: string): string {
-  const aliases: Record<string, string> = {
-    // JavaScript/TypeScript
-    js: "javascript",
-    ts: "typescript",
-    jsx: "javascript",
-    tsx: "typescript",
-
-    // Python
-    py: "python",
-    python3: "python",
-
-    // Shell
-    sh: "bash",
-    shell: "bash",
-    zsh: "bash",
-
-    // Web
-    html: "html",
-    htm: "html",
-    css: "css",
-    scss: "css",
-    sass: "css",
-    less: "css",
-
-    // Data formats
-    json: "json",
-    yaml: "yaml",
-    yml: "yaml",
-    xml: "xml",
-    toml: "toml",
-
-    // Other languages
-    rs: "rust",
-    go: "go",
-    rb: "ruby",
-    java: "java",
-    kt: "kotlin",
-    swift: "swift",
-    c: "c",
-    cpp: "cpp",
-    "c++": "cpp",
-    cs: "csharp",
-    "c#": "csharp",
-    php: "php",
-    sql: "sql",
-    md: "markdown",
-    markdown: "markdown",
-  };
-
-  const normalized = language.toLowerCase().trim();
-  return aliases[normalized] ?? normalized;
-}
-
-/**
- * Extract code blocks from markdown content.
- *
- * Parses markdown-style fenced code blocks (```language ... ```)
- * and returns an array of parsed code blocks with their positions.
- *
- * @example
- * ```ts
- * const markdown = `
- * Here's some code:
- * \`\`\`typescript
- * const x = 1;
- * \`\`\`
- * `;
- * const blocks = extractCodeBlocks(markdown);
- * // [{ content: "const x = 1;", language: "typescript", startIndex: 17, endIndex: 52 }]
- * ```
- */
-export function extractCodeBlocks(markdown: string): ParsedCodeBlock[] {
-  const blocks: ParsedCodeBlock[] = [];
-
-  // Regex to match fenced code blocks
-  // Matches: ```language\ncontent\n```
-  const codeBlockRegex = /```(\w*)\n([\s\S]*?)```/g;
-
-  let match: RegExpExecArray | null;
-  while ((match = codeBlockRegex.exec(markdown)) !== null) {
-    const [fullMatch, language, content] = match;
-    if (fullMatch && content !== undefined) {
-      blocks.push({
-        content: content.trimEnd(),
-        language: normalizeLanguage(language ?? ""),
-        startIndex: match.index,
-        endIndex: match.index + fullMatch.length,
-      });
-    }
-  }
-
-  return blocks;
-}
-
-/**
- * Check if a string contains any code blocks.
- */
-export function hasCodeBlocks(text: string): boolean {
-  return /```\w*\n[\s\S]*?```/.test(text);
-}
-
-/**
- * Extract inline code from text (single backticks).
- */
-export function extractInlineCode(text: string): string[] {
-  const matches = text.match(/`([^`]+)`/g);
-  if (!matches) return [];
-  return matches.map((match) => match.slice(1, -1));
-}
-
-// ============================================================================
-// CODE BLOCK COMPONENT
-// ============================================================================
-
-/**
- * Renders a syntax-highlighted code block.
- *
- * Uses OpenTUI's code renderable for syntax highlighting.
- * Falls back to plain text if no syntaxStyle is provided.
- *
- * @example
- * ```tsx
- * <CodeBlock
- *   content="const x = 1;"
- *   language="typescript"
- *   syntaxStyle={mySyntaxStyle}
- * />
- * ```
- */
-export function CodeBlock({
-  content,
-  language = "",
-  streaming = false,
-  syntaxStyle,
-  showLineNumbers = false,
-  title,
-}: CodeBlockProps): React.ReactNode {
-  const themeColors = useThemeColors();
-  const normalizedLanguage = normalizeLanguage(language);
-  const displayTitle = title ?? (normalizedLanguage ? normalizedLanguage : undefined);
-
-  // If no syntaxStyle provided, render as plain text in a box
-  if (!syntaxStyle) {
-    return (
-      <box
-        flexDirection="column"
-        borderStyle="single"
-        borderColor={themeColors.codeBorder}
-        paddingLeft={1}
-        paddingRight={1}
-        paddingTop={0}
-        paddingBottom={0}
-        marginTop={1}
-        marginBottom={1}
-      >
-        {displayTitle && (
-          <text fg={themeColors.codeTitle} attributes={2}>
-            {displayTitle}
-          </text>
-        )}
-        <text wrapMode="none" fg={themeColors.foreground}>
-          {content}
-        </text>
-      </box>
-    );
-  }
-
-  // Render with syntax highlighting
-  return (
-    <box
-      flexDirection="column"
-      borderStyle="single"
-      borderColor={themeColors.codeBorder}
-      paddingLeft={1}
-      paddingRight={1}
-      paddingTop={0}
-      paddingBottom={0}
-      marginTop={1}
-      marginBottom={1}
-    >
-      {displayTitle && (
-        <text fg={themeColors.codeTitle} attributes={2}>
-          {displayTitle}
-        </text>
-      )}
-      {showLineNumbers ? (
-        <line-number>
-          <code
-            content={content}
-            filetype={normalizedLanguage || undefined}
-            syntaxStyle={syntaxStyle}
-            streaming={streaming}
-          />
-        </line-number>
-      ) : (
-        <code
-          content={content}
-          filetype={normalizedLanguage || undefined}
-          syntaxStyle={syntaxStyle}
-          streaming={streaming}
-        />
-      )}
-    </box>
-  );
-}
-
-// ============================================================================
-// EXPORTS
-// ============================================================================
-
-export default CodeBlock;
diff --git a/src/ui/commands/agent-commands.test.ts b/src/ui/commands/agent-commands.test.ts
new file mode 100644
index 0000000000..f9459e778c
--- /dev/null
+++ b/src/ui/commands/agent-commands.test.ts
@@ -0,0 +1,57 @@
+import { describe, expect, mock, test } from "bun:test";
+import { createAgentCommand, type AgentInfo } from "./agent-commands.ts";
+import type { CommandContext } from "./registry.ts";
+
+function createContext(overrides: Partial<CommandContext>): CommandContext {
+  return {
+    session: null,
+    state: { isStreaming: false, messageCount: 0 },
+    addMessage: () => {},
+    setStreaming: () => {},
+    sendMessage: () => {},
+    sendSilentMessage: () => {},
+    spawnSubagent: async () => ({ success: true, output: "" }),
+    streamAndWait: async () => ({ content: "", wasInterrupted: false }),
+    clearContext: async () => {},
+    setTodoItems: () => {},
+    setWorkflowSessionDir: () => {},
+    setWorkflowSessionId: () => {},
+    setWorkflowTaskIds: () => {},
+    waitForUserInput: async () => "",
+    updateWorkflowState: () => {},
+    ...overrides,
+  };
+}
+
+describe("agent command routing", () => {
+  const baseAgent: AgentInfo = {
+    name: "worker",
+    description: "test agent",
+    source: "project",
+    filePath: ".claude/agents/worker.md",
+  };
+
+  test("routes OpenCode @agent as agent-only stream", () => {
+    const sendSilentMessage = mock(() => {});
+    const command = createAgentCommand(baseAgent);
+
+    command.execute("do work", createContext({ agentType: "opencode", sendSilentMessage }));
+
+    expect(sendSilentMessage).toHaveBeenCalledWith("do work", {
+      agent: "worker",
+      isAgentOnlyStream: true,
+    });
+  });
+
+  test("routes Claude @agent as agent-only stream", () => {
+    const sendSilentMessage = mock(() => {});
+    const command = createAgentCommand(baseAgent);
+
+    command.execute("do work", createContext({ agentType: "claude", sendSilentMessage }));
+
+    expect(sendSilentMessage).toHaveBeenCalledWith("do work", {
+      agent: "worker",
+      isAgentOnlyStream: true,
+    });
+  });
+});
diff --git a/src/ui/commands/agent-commands.ts b/src/ui/commands/agent-commands.ts
index 8ef7f83613..acaeaf091e 100644
--- a/src/ui/commands/agent-commands.ts
+++ b/src/ui/commands/agent-commands.ts
@@ -316,12 +316,22 @@ export function createAgentCommand(agent: AgentInfo): CommandDefinition {
         // OpenCode SDK dispatches sub-agents via AgentPartInput parts.
         // Pass the agent name structurally so the client can construct
         // the correct prompt parts without string encoding.
-        context.sendSilentMessage(task, { agent: agent.name });
+        context.sendSilentMessage(task, { agent: agent.name, isAgentOnlyStream: true });
+      } else if (context.agentType === "claude") {
+        // Claude SDK dispatches sub-agents via `options.agent` on the
+        // query() call. Pass the agent name structurally so the client
+        // sets `options.agent = agentName` and the SDK runs the query
+        // with that agent's prompt, tools, and model.
+        context.sendSilentMessage(task, { agent: agent.name, isAgentOnlyStream: true });
       } else {
-        // Claude SDK and Copilot SDK use the Task tool for sub-agent dispatch.
+        // Copilot SDK uses the Task tool for sub-agent dispatch.
         // Strongly steer the model to use Task-tool sub-agent dispatch so
         // sub-agent lifecycle events (and tree rendering) are emitted.
-        const instruction = `Use the Task tool to invoke the ${agent.name} sub-agent for this exact task: ${task}`;
+        // NOTE: Do NOT set isAgentOnlyStream here — these SDKs fire normal
+        // stream completion callbacks (handleStreamComplete). Setting it
+        // would trigger the premature agent-only finalizer, stopping the
+        // spinner while the main agent is still streaming its summary.
+        const instruction = `Use the Task tool to invoke the ${agent.name} sub-agent for this exact task: ${task}\n\nAfter the sub-agent completes, provide a concise summary of the outcome to the user.`;
         context.sendSilentMessage(instruction);
       }
 
diff --git a/src/ui/commands/builtin-commands.test.ts b/src/ui/commands/builtin-commands.test.ts
index eee6e9e233..b7dbfc67bd 100644
--- a/src/ui/commands/builtin-commands.test.ts
+++ b/src/ui/commands/builtin-commands.test.ts
@@ -35,9 +35,9 @@ function createMockContext(overrides?: Partial<CommandContext>): CommandContext
     waitForUserInput: async () => "",
     clearContext: async () => {},
     setTodoItems: () => {},
-    setRalphSessionDir: () => {},
-    setRalphSessionId: () => {},
-    setRalphTaskIds: () => {},
+    setWorkflowSessionDir: () => {},
+    setWorkflowSessionId: () => {},
+    setWorkflowTaskIds: () => {},
     updateWorkflowState: () => {},
     ...overrides,
   };
diff --git a/src/ui/commands/compact-ux-parity.e2e.test.ts b/src/ui/commands/compact-ux-parity.e2e.test.ts
new file mode 100644
index 0000000000..f5bd3fdbe2
--- /dev/null
+++ b/src/ui/commands/compact-ux-parity.e2e.test.ts
@@ -0,0 +1,138 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import type { AgentType } from "../../models";
+import type { CommandContext, CommandResult } from "./registry.ts";
+import { parseSlashCommand } from "./index.ts";
+import { globalRegistry } from "./registry.ts";
+import { registerBuiltinCommands } from "./builtin-commands.ts";
+import { getSpinnerVerbForCommand } from "../chat.tsx";
+import type { ChatMessage } from "../chat.tsx";
+import {
+  appendCompactionSummary,
+  appendToHistoryBuffer,
+  clearHistoryBuffer,
+  readHistoryBuffer,
+} from "../utils/conversation-history-buffer.ts";
+
+const PROVIDERS: AgentType[] = ["claude", "opencode", "copilot"];
+
+function makeChatMessages(count: number, prefix = "m"): ChatMessage[] {
+  return Array.from({ length: count }, (_, i) => ({
+    id: `${prefix}${i + 1}`,
+    role: "user" as const,
+    content: `message ${i + 1}`,
+    timestamp: new Date().toISOString(),
+  }));
+}
+
+function createMockContext(
+  agentType: AgentType,
+  summarize: () => Promise<void>,
+): CommandContext {
+  const mockSession = {
+    summarize,
+  } as Pick<NonNullable<CommandContext["session"]>, "summarize">;
+
+  return {
+    session: mockSession as NonNullable<CommandContext["session"]>,
+    state: {
+      isStreaming: false,
+      messageCount: 0,
+    },
+    addMessage: () => {},
+    setStreaming: () => {},
+    sendMessage: () => {},
+    sendSilentMessage: () => {},
+    spawnSubagent: async () => ({ success: true, output: "" }),
+    streamAndWait: async () => ({ content: "", wasInterrupted: false }),
+    clearContext: async () => {},
+    setTodoItems: () => {},
+    setWorkflowSessionDir: () => {},
+    setWorkflowSessionId: () => {},
+    setWorkflowTaskIds: () => {},
+    waitForUserInput: async () => "",
+    updateWorkflowState: () => {},
+    agentType,
+  };
+}
+
+async function executeCompactSlashCommand(
+  agentType: AgentType,
+  summarize: () => Promise<void>,
+): Promise<{ parsedName: string; result: CommandResult }> {
+  const parsed = parseSlashCommand("/compact");
+  expect(parsed.isCommand).toBe(true);
+
+  const command = globalRegistry.get(parsed.name);
+  expect(command).toBeDefined();
+
+  const context = createMockContext(agentType, summarize);
+  const result = await Promise.resolve(command!.execute(parsed.args, context));
+
+  return {
+    parsedName: parsed.name,
+    result,
+  };
+}
+
+describe("compact slash command e2e parity", () => {
+  beforeEach(() => {
+    globalRegistry.clear();
+    registerBuiltinCommands();
+    clearHistoryBuffer();
+  });
+
+  afterEach(() => {
+    clearHistoryBuffer();
+  });
+
+  test.each(PROVIDERS)(
+    "provider %s: /compact keeps spinner verb and command contract parity",
+    async (provider) => {
+      let summarizeCalls = 0;
+      const { parsedName, result } = await executeCompactSlashCommand(provider, async () => {
+        summarizeCalls += 1;
+      });
+
+      expect(getSpinnerVerbForCommand(parsedName)).toBe("Compacting");
+      expect(result.success).toBe(true);
+      expect(result.message).toBe("Conversation compacted (ctrl+o for history)");
+      expect(result.clearMessages).toBe(true);
+      expect(result.compactionSummary).toContain("Conversation context was compacted");
+      expect(summarizeCalls).toBe(1);
+    },
+  );
+
+  test.each(PROVIDERS)(
+    "provider %s: long-chat compact lifecycle preserves summary then continued history",
+    async (provider) => {
+      appendToHistoryBuffer(makeChatMessages(120, "long"));
+      expect(readHistoryBuffer()).toHaveLength(120);
+
+      const { result } = await executeCompactSlashCommand(provider, async () => {});
+      expect(result.success).toBe(true);
+      expect(result.clearMessages).toBe(true);
+      expect(result.compactionSummary).toBeDefined();
+
+      const shouldResetHistory = result.destroySession || Boolean(result.compactionSummary);
+      if (result.clearMessages && shouldResetHistory) {
+        clearHistoryBuffer();
+        if (result.compactionSummary) {
+          appendCompactionSummary(result.compactionSummary);
+        }
+      }
+
+      const compactedHistory = readHistoryBuffer();
+      expect(compactedHistory).toHaveLength(1);
+      expect(compactedHistory[0]?.id).toMatch(/^compact_/);
+      expect(compactedHistory[0]?.role).toBe("assistant");
+      expect(compactedHistory[0]?.content).toContain("Conversation context was compacted");
+
+      appendToHistoryBuffer(makeChatMessages(12, "post"));
+      const continuedHistory = readHistoryBuffer();
+      expect(continuedHistory).toHaveLength(13);
+      expect(continuedHistory[0]?.id).toMatch(/^compact_/);
+      expect(continuedHistory[1]?.id).toBe("post1");
+      expect(continuedHistory[12]?.id).toBe("post12");
+    },
+  );
+});
diff --git a/src/ui/commands/playwright-cli-e2e.test.ts b/src/ui/commands/playwright-cli-e2e.test.ts
new file mode 100644
index 0000000000..b38a75d111
--- /dev/null
+++ b/src/ui/commands/playwright-cli-e2e.test.ts
@@ -0,0 +1,117 @@
+import { beforeEach, describe, expect, test } from "bun:test";
+import type { AgentType } from "../../models";
+import { parseSlashCommand } from "./index.ts";
+import type { CommandContext, CommandResult } from "./registry.ts";
+import { globalRegistry } from "./registry.ts";
+import { registerBuiltinSkills } from "./skill-commands.ts";
+
+const PROVIDERS: AgentType[] = ["claude", "opencode", "copilot"];
+
+function createMockContext(
+  agentType: AgentType,
+  sentMessages: string[],
+): CommandContext {
+  return {
+    session: null,
+    state: {
+      isStreaming: false,
+      messageCount: 0,
+    },
+    addMessage: () => {},
+    setStreaming: () => {},
+    sendMessage: () => {},
+    sendSilentMessage: (content: string) => {
+      sentMessages.push(content);
+    },
+    spawnSubagent: async () => ({ success: true, output: "" }),
+    streamAndWait: async () => ({ content: "", wasInterrupted: false }),
+    clearContext: async () => {},
+    setTodoItems: () => {},
+    setWorkflowSessionDir: () => {},
+    setWorkflowSessionId: () => {},
+    setWorkflowTaskIds: () => {},
+    waitForUserInput: async () => "",
+    updateWorkflowState: () => {},
+    agentType,
+  };
+}
+
+async function executeSlashPlaywrightCommand(
+  rawCommand: string,
+  agentType: AgentType,
+): Promise<{ result: CommandResult; sentMessages: string[] }> {
+  const parsed = parseSlashCommand(rawCommand);
+  expect(parsed.isCommand).toBe(true);
+
+  const command = globalRegistry.get(parsed.name);
+  expect(command).toBeDefined();
+
+  const sentMessages: string[] = [];
+  const context = createMockContext(agentType, sentMessages);
+  const result = await Promise.resolve(command!.execute(parsed.args, context));
+
+  return { result, sentMessages };
+}
+
+describe("playwright-cli slash command E2E provider matrix", () => {
+  beforeEach(() => {
+    globalRegistry.clear();
+    registerBuiltinSkills();
+  });
+
+  test.each(PROVIDERS)(
+    "provider %s: /playwright-cli loads skill content and forwards user arguments",
+    async (provider) => {
+      const { result, sentMessages } = await executeSlashPlaywrightCommand(
+        "/playwright-cli fetch https://example.com",
+        provider,
+      );
+
+      expect(result.success).toBe(true);
+      expect(result.skillLoaded).toBe("playwright-cli");
+      expect(sentMessages).toHaveLength(1);
+      expect(sentMessages[0]).toContain('<skill-loaded name="playwright-cli">');
+      expect(sentMessages[0]).toContain("User request: fetch https://example.com");
+      expect(sentMessages[0]).toContain("playwright-cli open [url]");
+      expect(sentMessages[0]).not.toContain("WebFetch");
+      expect(sentMessages[0]).not.toContain("WebSearch");
+    },
+  );
+
+  test.each(PROVIDERS)(
+    "provider %s: /pw and /playwright aliases resolve to identical playwright-cli payloads",
+    async (provider) => {
+      const viaPw = await executeSlashPlaywrightCommand(
+        "/pw capture login flow",
+        provider,
+      );
+      const viaPlaywright = await executeSlashPlaywrightCommand(
+        "/playwright capture login flow",
+        provider,
+      );
+
+      expect(viaPw.result.success).toBe(true);
+      expect(viaPw.result.skillLoaded).toBe("playwright-cli");
+      expect(viaPlaywright.result.success).toBe(true);
+      expect(viaPlaywright.result.skillLoaded).toBe("playwright-cli");
+      expect(viaPw.sentMessages).toHaveLength(1);
+      expect(viaPlaywright.sentMessages).toHaveLength(1);
+      expect(viaPw.sentMessages[0]).toBe(viaPlaywright.sentMessages[0]);
+    },
+  );
+
+  test.each(PROVIDERS)(
+    "provider %s: /playwright-cli without arguments uses deterministic placeholder",
+    async (provider) => {
+      const { result, sentMessages } = await executeSlashPlaywrightCommand(
+        "/playwright-cli",
+        provider,
+      );
+
+      expect(result.success).toBe(true);
+      expect(result.skillLoaded).toBe("playwright-cli");
+      expect(sentMessages).toHaveLength(1);
+      expect(sentMessages[0]).toContain("User request: [no arguments provided]");
+    },
+  );
+});
diff --git a/src/ui/commands/registry.ts b/src/ui/commands/registry.ts
index f95ef1a40e..1850eb257f 100644
--- a/src/ui/commands/registry.ts
+++ b/src/ui/commands/registry.ts
@@ -11,6 +11,7 @@ import type { Session, ModelDisplayInfo, McpServerConfig } from "../../sdk/types
 import type { AgentType, ModelOperations } from "../../models";
 import type { TodoItem } from "../../sdk/tools/todo-write.ts";
 import type { McpServerToggleMap, McpSnapshotView } from "../utils/mcp-output.ts";
+import type { SubagentSpawnOptions, SubagentStreamResult } from "../../workflows/graph/types.ts";
 
 // ============================================================================
 // TYPES
@@ -33,8 +34,10 @@ export interface StreamResult {
  * to the underlying SDK session.
  */
 export interface StreamMessageOptions {
-  /** Sub-agent name for OpenCode dispatch via AgentPartInput. Ignored by Claude/Copilot. */
+  /** Sub-agent name for dispatch via SDK-native mechanisms. OpenCode uses AgentPartInput, Claude uses options.agent on query(). Copilot ignores this field. */
   agent?: string;
+  /** Marks this stream as @agent-only so completion can be finalized without SDK onComplete. */
+  isAgentOnlyStream?: boolean;
 }
 
 /**
@@ -96,6 +99,15 @@ export interface CommandContext {
    * @returns Promise with the sub-agent execution result
    */
   spawnSubagent: (options: SpawnSubagentOptions) => Promise<SpawnSubagentResult>;
+  /**
+   * Spawn multiple sub-agents concurrently using independent SDK sessions.
+   * Each sub-agent runs in its own session, so all
+   * agents can execute truly in parallel (unlike spawnSubagent which is serial).
+   *
+   * @param agents - Array of sub-agent spawn configurations
+   * @returns Promise with results for all agents (uses Promise.allSettled internally)
+   */
+  spawnSubagentParallel?: (agents: SubagentSpawnOptions[], abortSignal?: AbortSignal) => Promise<SubagentStreamResult[]>;
   /**
    * Send a message and wait for the streaming response to complete.
    * Returns the accumulated content and whether it was interrupted.
@@ -118,19 +130,19 @@ export interface CommandContext {
    */
   setTodoItems: (items: TodoItem[]) => void;
   /**
-   * Set the ralph workflow session directory for the persistent task list panel.
+   * Set the workflow session directory for the persistent task list panel.
    */
-  setRalphSessionDir: (dir: string | null) => void;
+  setWorkflowSessionDir: (dir: string | null) => void;
   /**
-   * Set the ralph workflow session ID for the persistent task list panel.
+   * Set the workflow session ID for the persistent task list panel.
    */
-  setRalphSessionId: (id: string | null) => void;
+  setWorkflowSessionId: (id: string | null) => void;
   /**
-   * Set the known ralph task IDs from the planning phase.
-   * Used to guard TodoWrite persistence so that only ralph-originated
+   * Set the known workflow task IDs from the planning phase.
+   * Used to guard TodoWrite persistence so that only workflow-originated
    * updates are written to tasks.json (prevents sub-agent overwrites).
    */
-  setRalphTaskIds: (ids: Set<string>) => void;
+  setWorkflowTaskIds: (ids: Set<string>) => void;
   /**
    * Wait for the user to type and submit a prompt.
    * Used by workflows after a stream interruption (Ctrl+C) to yield control
@@ -141,6 +153,8 @@ export interface CommandContext {
    * Update workflow state from a command handler.
    */
   updateWorkflowState: (update: Partial<CommandContextState>) => void;
+  /** The event bus for publishing/subscribing to streaming events */
+  eventBus?: import("../../events/event-bus.ts").EventBus;
   /** The type of agent currently in use (claude, opencode, copilot) */
   agentType?: AgentType;
   /** Model operations interface for listing, setting, and resolving models */
@@ -195,10 +209,11 @@ export interface CommandContextState {
   specApproved?: boolean;
   /** Feedback from spec rejection */
   feedback?: string | null;
-  /** Ralph-specific workflow configuration */
-  ralphConfig?: {
+  /** Workflow-specific configuration */
+  workflowConfig?: {
     userPrompt: string | null;
     sessionId?: string;
+    workflowName?: string;
   };
 }
 
diff --git a/src/ui/commands/skill-commands.test.ts b/src/ui/commands/skill-commands.test.ts
new file mode 100644
index 0000000000..828102cd67
--- /dev/null
+++ b/src/ui/commands/skill-commands.test.ts
@@ -0,0 +1,79 @@
+import { beforeEach, describe, expect, test } from "bun:test";
+import type { CommandContext } from "./registry.ts";
+import { globalRegistry } from "./registry.ts";
+import {
+    BUILTIN_SKILLS,
+    registerBuiltinSkills,
+} from "./skill-commands.ts";
+
+function createMockContext(overrides?: Partial<CommandContext>): CommandContext {
+    return {
+        session: null,
+        state: {
+            isStreaming: false,
+            messageCount: 0,
+        },
+        addMessage: () => {},
+        setStreaming: () => {},
+        sendMessage: () => {},
+        sendSilentMessage: () => {},
+        spawnSubagent: async () => ({ success: true, output: "" }),
+        streamAndWait: async () => ({ content: "", wasInterrupted: false }),
+        clearContext: async () => {},
+        setTodoItems: () => {},
+        setWorkflowSessionDir: () => {},
+        setWorkflowSessionId: () => {},
+        setWorkflowTaskIds: () => {},
+        waitForUserInput: async () => "",
+        updateWorkflowState: () => {},
+        ...overrides,
+    };
+}
+
+describe("skill-commands builtins", () => {
+    beforeEach(() => {
+        globalRegistry.clear();
+    });
+
+    test("includes playwright-cli in BUILTIN_SKILLS", () => {
+        const skill = BUILTIN_SKILLS.find((entry) => entry.name === "playwright-cli");
+        expect(skill).toBeDefined();
+        expect(skill?.aliases).toEqual(["pw", "playwright"]);
+    });
+
+    test("registerBuiltinSkills registers playwright-cli and aliases", () => {
+        registerBuiltinSkills();
+
+        const byName = globalRegistry.get("playwright-cli");
+        const byPwAlias = globalRegistry.get("pw");
+        const byPlaywrightAlias = globalRegistry.get("playwright");
+
+        expect(byName).toBeDefined();
+        expect(byPwAlias?.name).toBe("playwright-cli");
+        expect(byPlaywrightAlias?.name).toBe("playwright-cli");
+    });
+
+    test("playwright-cli builtin command expands arguments before dispatch", async () => {
+        registerBuiltinSkills();
+
+        const sentMessages: string[] = [];
+        const context = createMockContext({
+            sendSilentMessage: (content: string) => {
+                sentMessages.push(content);
+            },
+        });
+
+        const command = globalRegistry.get("playwright-cli");
+        expect(command).toBeDefined();
+
+        const result = await Promise.resolve(
+            command!.execute("capture login flow", context),
+        );
+
+        expect(result.success).toBe(true);
+        expect(result.skillLoaded).toBe("playwright-cli");
+        expect(sentMessages).toHaveLength(1);
+        expect(sentMessages[0]).toContain('<skill-loaded name="playwright-cli">');
+        expect(sentMessages[0]).toContain("User request: capture login flow");
+    });
+});
diff --git a/src/ui/commands/skill-commands.ts b/src/ui/commands/skill-commands.ts
index fc56f5b760..aa5e037961 100644
--- a/src/ui/commands/skill-commands.ts
+++ b/src/ui/commands/skill-commands.ts
@@ -89,6 +89,96 @@ export interface DiskSkillDefinition {
     requiredArguments?: string[];
 }
 
+export interface BuiltinSkillDefinition {
+    name: string;
+    description: string;
+    prompt: string;
+    aliases?: string[];
+    argumentHint?: string;
+    requiredArguments?: string[];
+}
+
+export const BUILTIN_SKILLS: BuiltinSkillDefinition[] = [
+    {
+        name: "playwright-cli",
+        aliases: ["pw", "playwright"],
+        description:
+            "Browser automation for web research, data extraction, and UI testing with Playwright CLI",
+        argumentHint: "[url-or-task]",
+        prompt: `# Browser Automation with playwright-cli
+
+Use this skill when the user asks to browse websites, validate UI flows, reproduce web bugs, fill forms, or capture page artifacts.
+
+User request: $ARGUMENTS
+
+## Standard workflow
+
+1. Open a browser session.
+2. Navigate to the target URL.
+3. Capture a snapshot to get element refs.
+4. Interact with page elements by ref.
+5. Capture evidence (snapshot/screenshot/pdf) when needed.
+6. Close the browser when done.
+
+## Command patterns
+
+### Navigation
+
+\`\`\`bash
+playwright-cli open [url]
+playwright-cli goto <url>
+playwright-cli go-back
+playwright-cli go-forward
+playwright-cli reload
+playwright-cli close
+\`\`\`
+
+### Interaction
+
+\`\`\`bash
+playwright-cli click <ref> [button]
+playwright-cli dblclick <ref> [button]
+playwright-cli fill <ref> <text>
+playwright-cli type <text>
+playwright-cli press <key>
+playwright-cli select <ref> <value>
+playwright-cli check <ref>
+playwright-cli uncheck <ref>
+playwright-cli hover <ref>
+playwright-cli drag <startRef> <endRef>
+playwright-cli upload <file>
+\`\`\`
+
+### Page state and artifacts
+
+\`\`\`bash
+playwright-cli snapshot
+playwright-cli screenshot
+playwright-cli pdf --filename=page.pdf
+playwright-cli eval "document.title"
+playwright-cli console
+playwright-cli network
+\`\`\`
+
+## Best practices
+
+- Run \`snapshot\` often to refresh refs before interacting.
+- Use element refs (\`e1\`, \`e2\`, ...) from the latest snapshot.
+- Keep actions incremental and verify after meaningful steps.
+- Use named sessions for multi-step workflows that need persistent state.
+
+## Fallback execution
+
+If global \`playwright-cli\` is unavailable, use Bun:
+
+\`\`\`bash
+bunx @playwright/cli open https://example.com
+bunx @playwright/cli snapshot
+\`\`\`
+`,
+    },
+];
+
 function shouldSkillOverride(
     newSource: SkillSource,
     existingSource: SkillSource,
@@ -232,6 +322,56 @@ function loadSkillContent(skillFilePath: string): string | null {
     }
 }
 
+function dispatchLoadedSkillPrompt(
+    skillName: string,
+    body: string,
+    skillArgs: string,
+    context: CommandContext,
+): CommandResult {
+    const expandedPrompt = expandArguments(body, skillArgs);
+    // Prepend a directive so the model acts on the already-expanded
+    // skill content rather than re-loading the raw skill via the SDK's
+    // built-in "skill" tool (which would lose the $ARGUMENTS expansion).
+    const directive =
+        `<skill-loaded name="${skillName}">\n` +
+        `The "${skillName}" skill has already been loaded with the user's arguments below. ` +
+        `Do NOT invoke the Skill tool for "${skillName}" — follow the instructions directly.\n` +
+        `</skill-loaded>\n\n`;
+    context.sendSilentMessage(directive + expandedPrompt);
+    return { success: true, skillLoaded: skillName };
+}
+
+function createBuiltinSkillCommand(skill: BuiltinSkillDefinition): CommandDefinition {
+    return {
+        name: skill.name,
+        description: skill.description,
+        category: "skill",
+        aliases: skill.aliases,
+        argumentHint: skill.argumentHint,
+        execute: (args: string, context: CommandContext): CommandResult => {
+            const skillArgs = args.trim();
+
+            // Validate required arguments from built-in definition
+            if (skill.requiredArguments?.length && !skillArgs) {
+                const argList = skill.requiredArguments
+                    .map((a) => `<${a}>`)
+                    .join(" ");
+                return {
+                    success: false,
+                    message: `Missing required argument.\nUsage: /${skill.name} ${argList}`,
+                };
+            }
+
+            return dispatchLoadedSkillPrompt(
+                skill.name,
+                skill.prompt,
+                skillArgs,
+                context,
+            );
+        },
+    };
+}
+
 function createDiskSkillCommand(skill: DiskSkillDefinition): CommandDefinition {
     return {
         name: skill.name,
@@ -263,22 +403,22 @@ function createDiskSkillCommand(skill: DiskSkillDefinition): CommandDefinition {
                 context.sendSilentMessage(invocationMessage);
                 return { success: true, skillLoaded: skill.name };
             }
-            const expandedPrompt = expandArguments(body, skillArgs);
-            // Prepend a directive so the model acts on the already-expanded
-            // skill content rather than re-loading the raw skill via the SDK's
-            // built-in "skill" tool (which would lose the $ARGUMENTS expansion).
-            const directive =
-                `<skill-loaded name="${skill.name}">\n` +
-                `The "${skill.name}" skill has already been loaded with the user's arguments below. ` +
-                `Do NOT invoke the Skill tool for "${skill.name}" — follow the instructions directly.\n` +
-                `</skill-loaded>\n\n`;
-            context.sendSilentMessage(directive + expandedPrompt);
-            return { success: true, skillLoaded: skill.name };
+            return dispatchLoadedSkillPrompt(skill.name, body, skillArgs, context);
         },
     };
 }
 
+export function registerBuiltinSkills(): void {
+    for (const skill of BUILTIN_SKILLS) {
+        if (globalRegistry.has(skill.name)) {
+            continue;
+        }
+        globalRegistry.register(createBuiltinSkillCommand(skill));
+    }
+}
+
 export async function discoverAndRegisterDiskSkills(): Promise<void> {
+    registerBuiltinSkills();
     const files = discoverSkillFiles();
 
     // Build map with priority resolution (project > user)
diff --git a/src/ui/commands/workflow-commands.test.ts b/src/ui/commands/workflow-commands.test.ts
index 767afe5b55..481c81f593 100644
--- a/src/ui/commands/workflow-commands.test.ts
+++ b/src/ui/commands/workflow-commands.test.ts
@@ -1,9 +1,18 @@
 import { describe, expect, test } from "bun:test";
-import { mkdtemp, writeFile as fsWriteFile, rm } from "fs/promises";
+import { mkdtemp, mkdir, writeFile as fsWriteFile, rm } from "fs/promises";
 import { tmpdir } from "os";
 import { join } from "path";
 import type { CommandContext } from "./registry.ts";
-import { getWorkflowCommands, parseRalphArgs, watchTasksJson } from "./workflow-commands.ts";
+import { EventBus } from "../../events/event-bus.ts";
+import { VERSION } from "../../version.ts";
+import {
+  CUSTOM_WORKFLOW_SEARCH_PATHS,
+  discoverWorkflowFiles,
+  getWorkflowCommands,
+  loadWorkflowsFromDisk,
+  parseRalphArgs,
+  watchTasksJson,
+} from "./workflow-commands.ts";
 
 function createMockContext(overrides?: Partial<CommandContext>): CommandContext {
   return {
@@ -18,18 +27,44 @@ function createMockContext(overrides?: Partial<CommandContext>): CommandContext
     sendMessage: () => {},
     sendSilentMessage: () => {},
     spawnSubagent: async () => ({ success: true, output: "" }),
+    spawnSubagentParallel: async (agents) =>
+      agents.map((a) => ({
+        agentId: a.agentId,
+        success: true,
+        output: "Done",
+        toolUses: 1,
+        durationMs: 100,
+      })),
     streamAndWait: async () => ({ content: "", wasInterrupted: false }),
     waitForUserInput: async () => "",
     clearContext: async () => {},
     setTodoItems: () => {},
-    setRalphSessionDir: () => {},
-    setRalphSessionId: () => {},
-    setRalphTaskIds: () => {},
+    setWorkflowSessionDir: () => {},
+    setWorkflowSessionId: () => {},
+    setWorkflowTaskIds: () => {},
     updateWorkflowState: () => {},
     ...overrides,
   };
 }
 
+async function withWorkflowSearchPaths(
+  paths: string[],
+  run: () => Promise<void>,
+): Promise<void> {
+  const originalPaths = [...CUSTOM_WORKFLOW_SEARCH_PATHS];
+  CUSTOM_WORKFLOW_SEARCH_PATHS.splice(0, CUSTOM_WORKFLOW_SEARCH_PATHS.length, ...paths);
+  try {
+    await run();
+  } finally {
+    CUSTOM_WORKFLOW_SEARCH_PATHS.splice(
+      0,
+      CUSTOM_WORKFLOW_SEARCH_PATHS.length,
+      ...originalPaths,
+    );
+    await loadWorkflowsFromDisk();
+  }
+}
+
 describe("parseRalphArgs", () => {
   test("parses a prompt argument", () => {
     const result = parseRalphArgs("Build a feature");
@@ -46,6 +81,9 @@ describe("parseRalphArgs", () => {
   });
 });
 
+describe("workflow metadata discovery", () => {
+});
+
 describe("watchTasksJson", () => {
   function createDeferred<T>() {
     let resolve!: (value: T) => void;
@@ -198,293 +236,225 @@ describe("workflow-commands /ralph", () => {
     expect(result.success).toBe(false);
     expect(result.message).toContain("A prompt argument is required");
   });
-});
 
-describe("review step in /ralph", () => {
-  test("spawns reviewer sub-agent when all tasks complete", async () => {
-    const spawnCalls: Array<{ name?: string; message: string }> = [];
-    let streamCallCount = 0;
-    let clearCallCount = 0;
+  test("forwards context.eventBus to executeWorkflow and publishes stream.session.start", async () => {
+    const bus = new EventBus();
+    const seenEvents: string[] = [];
+    const unsubscribe = bus.on("stream.session.start", () => {
+      seenEvents.push("stream.session.start");
+    });
 
-    // Mock tasks.json by creating a temp directory
-    const tempDir = await mkdtemp(join(tmpdir(), "ralph-test-"));
-    const tasksJson = JSON.stringify([
-      { id: "#1", content: "Test task", status: "completed", activeForm: "Testing" },
-    ]);
-    
-    // We need to write tasks.json to the session dir. But sessionId is random.
-    // So we'll track setRalphSessionDir to know the directory.
     let sessionDir: string | null = null;
-    
     const context = createMockContext({
-      streamAndWait: async (prompt: string, options?: { hideContent?: boolean }) => {
-        streamCallCount++;
-        if (streamCallCount === 1) {
-          // Step 1: Return task list
-          return {
-            content: JSON.stringify([
-              { id: "#1", content: "Test task", status: "pending", activeForm: "Testing" },
-            ]),
-            wasInterrupted: false,
-          };
-        }
-        // Step 2 and beyond: return empty (simulates agent doing work)
-        // After this, the loop reads tasks from disk
-        if (sessionDir) {
-          // Write completed tasks to disk so the loop sees completion
-          await fsWriteFile(
-            join(sessionDir, "tasks.json"),
-            JSON.stringify([
-              { id: "#1", content: "Test task", status: "completed", activeForm: "Testing" },
-            ])
-          );
-        }
-        return { content: "", wasInterrupted: false };
-      },
-      spawnSubagent: async (options) => {
-        spawnCalls.push({ name: options.name, message: options.message });
-        // Return a valid review with no actionable findings
-        return {
-          success: true,
-          output: JSON.stringify({
-            findings: [],
-            overall_correctness: "patch is correct",
-            overall_explanation: "All changes look good",
-            overall_confidence_score: 0.95,
-          }),
-        };
-      },
-      clearContext: async () => {
-        clearCallCount++;
-      },
-      setRalphSessionDir: (dir: string | null) => {
+      eventBus: bus,
+      setWorkflowSessionDir: (dir: string | null) => {
         sessionDir = dir;
-        // Create the directory for tasks.json
         if (dir) {
           const { mkdirSync } = require("fs");
           mkdirSync(dir, { recursive: true });
         }
       },
-      setRalphSessionId: () => {},
-      setRalphTaskIds: () => {},
-      updateWorkflowState: () => {},
     });
 
-    const ralphCommand = getWorkflowCommands().find((cmd) => cmd.name === "ralph");
-    expect(ralphCommand).toBeDefined();
-
-    const result = await ralphCommand!.execute("Build a feature", context);
-    expect(result.success).toBe(true);
-    
-    // Verify reviewer was spawned
-    expect(spawnCalls.length).toBeGreaterThanOrEqual(1);
-    expect(spawnCalls[0]?.name).toBe("reviewer");
-    expect(spawnCalls[0]?.message).toContain("Code Review Request");
-    
-    // Cleanup
-    await rm(tempDir, { recursive: true, force: true });
-    if (sessionDir) {
-      await rm(sessionDir, { recursive: true, force: true });
+    try {
+      const ralphCommand = getWorkflowCommands().find((cmd) => cmd.name === "ralph");
+      expect(ralphCommand).toBeDefined();
+
+      await ralphCommand!.execute("Build a feature", context);
+      expect(seenEvents.length).toBeGreaterThan(0);
+    } finally {
+      unsubscribe();
+      if (sessionDir) {
+        await rm(sessionDir, { recursive: true, force: true });
+      }
     }
   });
 
-  test("stops implementation loop when pending tasks are dependency-blocked", async () => {
-    let streamCallCount = 0;
-    let sessionDir: string | null = null;
+  test("publishes Ralph sub-agent completion events for successful execution", async () => {
+    const bus = new EventBus();
+    const agentStarts: Array<{ agentId: string; agentType: string }> = [];
+    const agentCompletes: Array<{
+      agentId: string;
+      success: boolean;
+      result?: string;
+      error?: string;
+    }> = [];
+    const sessionStarts: string[] = [];
+    const unsubscribeSession = bus.on("stream.session.start", () => {
+      sessionStarts.push("stream.session.start");
+    });
+    const unsubscribeStart = bus.on("stream.agent.start", (event) => {
+      agentStarts.push({
+        agentId: event.data.agentId,
+        agentType: event.data.agentType,
+      });
+    });
+    const unsubscribeComplete = bus.on("stream.agent.complete", (event) => {
+      agentCompletes.push({
+        agentId: event.data.agentId,
+        success: event.data.success,
+        result: event.data.result,
+        error: event.data.error,
+      });
+    });
 
+    let sessionDir: string | null = null;
     const context = createMockContext({
-      streamAndWait: async () => {
-        streamCallCount++;
-
-        if (streamCallCount === 1) {
+      eventBus: bus,
+      spawnSubagentParallel: async (agents) =>
+        agents.map((agent) => {
+          if (agent.agentName === "planner") {
+            return {
+              agentId: agent.agentId,
+              success: true,
+              output: JSON.stringify([
+                {
+                  id: "#1",
+                  content: "Add integration test for Claude sub-agent completion in Ralph",
+                  status: "pending",
+                  activeForm: "Adding integration test for Claude sub-agent completion in Ralph",
+                  blockedBy: [],
+                },
+              ]),
+              toolUses: 1,
+              durationMs: 100,
+            };
+          }
+          if (agent.agentName === "worker") {
+            return {
+              agentId: agent.agentId,
+              success: true,
+              output: "Implemented task #1",
+              toolUses: 2,
+              durationMs: 120,
+            };
+          }
+          if (agent.agentName === "reviewer") {
+            return {
+              agentId: agent.agentId,
+              success: true,
+              output: JSON.stringify({
+                findings: [],
+                overall_correctness: "patch is correct",
+                overall_explanation: "No issues found",
+              }),
+              toolUses: 1,
+              durationMs: 80,
+            };
+          }
           return {
-            content: JSON.stringify([
-              { id: "#1", content: "Failing root task", status: "pending", activeForm: "Working" },
-              {
-                id: "#2",
-                content: "Blocked follow-up",
-                status: "pending",
-                activeForm: "Waiting",
-                blockedBy: ["#1"],
-              },
-            ]),
-            wasInterrupted: false,
+            agentId: agent.agentId,
+            success: true,
+            output: "Done",
+            toolUses: 1,
+            durationMs: 100,
           };
-        }
-
-        if (streamCallCount === 2 && sessionDir) {
-          await fsWriteFile(
-            join(sessionDir, "tasks.json"),
-            JSON.stringify([
-              { id: "#1", content: "Failing root task", status: "error", activeForm: "Working" },
-              {
-                id: "#2",
-                content: "Blocked follow-up",
-                status: "pending",
-                activeForm: "Waiting",
-                blockedBy: ["#1"],
-              },
-            ])
-          );
-          return { content: "", wasInterrupted: false };
-        }
-
-        throw new Error("Implementation loop did not stop on dependency deadlock");
-      },
-      setRalphSessionDir: (dir: string | null) => {
+        }),
+      setWorkflowSessionDir: (dir: string | null) => {
         sessionDir = dir;
         if (dir) {
           const { mkdirSync } = require("fs");
           mkdirSync(dir, { recursive: true });
         }
       },
-      setRalphSessionId: () => {},
-      setRalphTaskIds: () => {},
-      updateWorkflowState: () => {},
     });
 
-    const ralphCommand = getWorkflowCommands().find((cmd) => cmd.name === "ralph");
-    const result = await ralphCommand!.execute("Build a feature", context);
-    expect(result.success).toBe(true);
-    expect(streamCallCount).toBe(2);
-
-    if (sessionDir) {
-      await rm(sessionDir, { recursive: true, force: true });
+    try {
+      const ralphCommand = getWorkflowCommands().find((cmd) => cmd.name === "ralph");
+      expect(ralphCommand).toBeDefined();
+
+      const result = await ralphCommand!.execute(
+        "Add integration test for Claude sub-agent completion in Ralph",
+        context,
+      );
+
+      expect(result.success).toBe(true);
+      expect(sessionStarts.length).toBeGreaterThan(0);
+      expect(
+        agentStarts.some(
+          (event) => event.agentType === "planner" && event.agentId.startsWith("planner-"),
+        ),
+      ).toBe(true);
+      expect(
+        agentCompletes.some(
+          (event) =>
+            event.agentId.startsWith("planner-")
+            && event.success
+            && event.result?.includes('"id":"#1"'),
+        ),
+      ).toBe(true);
+      expect(
+        agentCompletes.some(
+          (event) => event.agentId === "worker-#1" && event.success && event.result === "Implemented task #1",
+        ),
+      ).toBe(true);
+      expect(
+        agentCompletes.some(
+          (event) =>
+            event.agentId.startsWith("reviewer-")
+            && event.success
+            && event.result?.includes('"overall_correctness":"patch is correct"'),
+        ),
+      ).toBe(true);
+    } finally {
+      unsubscribeSession();
+      unsubscribeStart();
+      unsubscribeComplete();
+      if (sessionDir) {
+        await rm(sessionDir, { recursive: true, force: true });
+      }
     }
   });
+});
 
-  test("continues implementation loop when blockedBy uses non-prefixed IDs", async () => {
-    let streamCallCount = 0;
-    let sessionDir: string | null = null;
-
-    const context = createMockContext({
-      streamAndWait: async () => {
-        streamCallCount++;
+describe("review step in /ralph", () => {
 
-        if (streamCallCount === 1) {
-          return {
-            content: JSON.stringify([
-              { id: "#1", content: "Root task", status: "pending", activeForm: "Working" },
-              {
-                id: "#2",
-                content: "Dependent task",
-                status: "pending",
-                activeForm: "Waiting",
-                blockedBy: ["1"],
-              },
-            ]),
-            wasInterrupted: false,
-          };
-        }
 
-        if (streamCallCount === 2 && sessionDir) {
-          await fsWriteFile(
-            join(sessionDir, "tasks.json"),
-            JSON.stringify([
-              { id: "#1", content: "Root task", status: "completed", activeForm: "Working" },
-              {
-                id: "#2",
-                content: "Dependent task",
-                status: "pending",
-                activeForm: "Waiting",
-                blockedBy: ["1"],
-              },
-            ]),
-          );
-          return { content: "", wasInterrupted: false };
-        }
 
-        if (streamCallCount === 3 && sessionDir) {
-          await fsWriteFile(
-            join(sessionDir, "tasks.json"),
-            JSON.stringify([
-              { id: "#1", content: "Root task", status: "completed", activeForm: "Working" },
-              {
-                id: "#2",
-                content: "Dependent task",
-                status: "completed",
-                activeForm: "Waiting",
-                blockedBy: ["1"],
-              },
-            ]),
-          );
-          return { content: "", wasInterrupted: false };
-        }
 
-        throw new Error("Implementation loop stopped before dependency became actionable");
-      },
-      setRalphSessionDir: (dir: string | null) => {
-        sessionDir = dir;
-        if (dir) {
-          const { mkdirSync } = require("fs");
-          mkdirSync(dir, { recursive: true });
-        }
-      },
-      setRalphSessionId: () => {},
-      setRalphTaskIds: () => {},
-      updateWorkflowState: () => {},
-    });
 
-    const ralphCommand = getWorkflowCommands().find((cmd) => cmd.name === "ralph");
-    const result = await ralphCommand!.execute("Build a feature", context);
-    expect(result.success).toBe(true);
-    expect(streamCallCount).toBe(3);
-
-    if (sessionDir) {
-      await rm(sessionDir, { recursive: true, force: true });
-    }
-  });
 
   test("does not spawn reviewer when tasks are not all completed", async () => {
     const spawnCalls: Array<{ name?: string }> = [];
-    let streamCallCount = 0;
     let sessionDir: string | null = null;
 
     const context = createMockContext({
       streamAndWait: async () => {
-        streamCallCount++;
-        if (streamCallCount === 1) {
-          return {
-            content: JSON.stringify([
-              { id: "#1", content: "Test task", status: "pending", activeForm: "Testing" },
-            ]),
-            wasInterrupted: false,
-          };
-        }
-        // Write tasks with one still pending (not all completed)
-        if (sessionDir) {
-          await fsWriteFile(
-            join(sessionDir, "tasks.json"),
-            JSON.stringify([
-              { id: "#1", content: "Test task", status: "pending", activeForm: "Testing" },
-            ])
-          );
-        }
-        // After first iteration, return cancelled to stop loop
-        if (streamCallCount > 2) {
-          return { content: "", wasInterrupted: true, wasCancelled: true };
-        }
-        return { content: "", wasInterrupted: false };
+        return {
+          content: JSON.stringify([
+            { id: "#1", content: "Test task", status: "pending", activeForm: "Testing" },
+          ]),
+          wasInterrupted: false,
+        };
       },
+      spawnSubagentParallel: async (agents) =>
+        agents.map((a) => ({
+          agentId: a.agentId,
+          success: false,
+          output: "Error: failed",
+          toolUses: 0,
+          durationMs: 100,
+        })),
       spawnSubagent: async (options) => {
         spawnCalls.push({ name: options.name });
         return { success: true, output: "" };
       },
-      setRalphSessionDir: (dir: string | null) => {
+      setWorkflowSessionDir: (dir: string | null) => {
         sessionDir = dir;
         if (dir) {
           const { mkdirSync } = require("fs");
           mkdirSync(dir, { recursive: true });
         }
       },
-      setRalphSessionId: () => {},
-      setRalphTaskIds: () => {},
+      setWorkflowSessionId: () => {},
+      setWorkflowTaskIds: () => {},
       updateWorkflowState: () => {},
     });
 
     const ralphCommand = getWorkflowCommands().find((cmd) => cmd.name === "ralph");
     const result = await ralphCommand!.execute("Build a feature", context);
-    expect(result.success).toBe(true);
+    // When the planner subagent fails, the workflow should report failure
+    expect(result.success).toBe(false);
     
     // Reviewer should NOT be spawned since not all tasks completed
     expect(spawnCalls.length).toBe(0);
@@ -493,247 +463,10 @@ describe("review step in /ralph", () => {
       await rm(sessionDir, { recursive: true, force: true });
     }
   });
-
-  test("re-invokes ralph when review has actionable findings", async () => {
-    let streamCallCount = 0;
-    let sessionDir: string | null = null;
-    const spawnCalls: Array<{ name?: string; message: string }> = [];
-    let fixTasksDecomposed = false;
-
-    const context = createMockContext({
-      streamAndWait: async (prompt: string, options?: { hideContent?: boolean }) => {
-        streamCallCount++;
-        
-        if (streamCallCount === 1) {
-          // Step 1: Initial task decomposition
-          return {
-            content: JSON.stringify([
-              { id: "#1", content: "Initial task", status: "pending", activeForm: "Working" },
-            ]),
-            wasInterrupted: false,
-          };
-        }
-        
-        if (streamCallCount === 2) {
-          // Step 2: Implementation loop - write completed tasks
-          if (sessionDir) {
-            await fsWriteFile(
-              join(sessionDir, "tasks.json"),
-              JSON.stringify([
-                { id: "#1", content: "Initial task", status: "completed", activeForm: "Working" },
-              ])
-            );
-          }
-          return { content: "", wasInterrupted: false };
-        }
-        
-        if (streamCallCount === 3 && options?.hideContent) {
-          // Step 3: Fix task decomposition (after review)
-          fixTasksDecomposed = true;
-          return {
-            content: JSON.stringify([
-              { id: "#fix-1", content: "Fix error handling", status: "pending", activeForm: "Fixing" },
-            ]),
-            wasInterrupted: false,
-          };
-        }
-        
-        if (streamCallCount === 4) {
-          // Step 4: Fix implementation loop
-          if (sessionDir) {
-            await fsWriteFile(
-              join(sessionDir, "tasks.json"),
-              JSON.stringify([
-                { id: "#fix-1", content: "Fix error handling", status: "completed", activeForm: "Fixing" },
-              ])
-            );
-          }
-          return { content: "", wasInterrupted: false };
-        }
-        
-        return { content: "", wasInterrupted: true };
-      },
-      spawnSubagent: async (options) => {
-        spawnCalls.push({ name: options.name, message: options.message });
-        // Return review with actionable P1 finding
-        return {
-          success: true,
-          output: JSON.stringify({
-            findings: [
-              {
-                title: "[P1] Missing error handling",
-                body: "The function does not handle errors properly",
-                priority: 1,
-                confidence_score: 0.9,
-                code_location: {
-                  absolute_file_path: "/src/test.ts",
-                  line_range: { start: 10, end: 15 },
-                },
-              },
-            ],
-            overall_correctness: "patch is incorrect",
-            overall_explanation: "Missing error handling in critical path",
-            overall_confidence_score: 0.85,
-          }),
-        };
-      },
-      clearContext: async () => {},
-      setRalphSessionDir: (dir: string | null) => {
-        sessionDir = dir;
-        if (dir) {
-          const { mkdirSync } = require("fs");
-          mkdirSync(dir, { recursive: true });
-        }
-      },
-      setRalphSessionId: () => {},
-      setRalphTaskIds: () => {},
-      updateWorkflowState: () => {},
-    });
-
-    const ralphCommand = getWorkflowCommands().find((cmd) => cmd.name === "ralph");
-    const result = await ralphCommand!.execute("Build a feature", context);
-    expect(result.success).toBe(true);
-    
-    // Verify reviewer was spawned
-    expect(spawnCalls.length).toBe(1);
-    expect(spawnCalls[0]?.name).toBe("reviewer");
-    
-    // Verify fix tasks were decomposed (re-invocation happened)
-    expect(fixTasksDecomposed).toBe(true);
-    
-    // Verify review artifacts were saved
-    if (sessionDir) {
-      const { existsSync } = require("fs");
-      expect(existsSync(join(sessionDir, "review-0.json"))).toBe(true);
-      expect(existsSync(join(sessionDir, "fix-spec-0.md"))).toBe(true);
-      
-      await rm(sessionDir, { recursive: true, force: true });
-    }
-  });
-
-  test("stops fix loop when fix tasks are dependency-blocked", async () => {
-    let streamCallCount = 0;
-    let sessionDir: string | null = null;
-
-    const context = createMockContext({
-      streamAndWait: async (_prompt: string, options?: { hideContent?: boolean }) => {
-        streamCallCount++;
-
-        if (streamCallCount === 1) {
-          return {
-            content: JSON.stringify([
-              { id: "#1", content: "Initial task", status: "pending", activeForm: "Working" },
-            ]),
-            wasInterrupted: false,
-          };
-        }
-
-        if (streamCallCount === 2 && sessionDir) {
-          await fsWriteFile(
-            join(sessionDir, "tasks.json"),
-            JSON.stringify([
-              { id: "#1", content: "Initial task", status: "completed", activeForm: "Working" },
-            ])
-          );
-          return { content: "", wasInterrupted: false };
-        }
-
-        if (streamCallCount === 3 && options?.hideContent) {
-          return {
-            content: JSON.stringify([
-              { id: "#fix-1", content: "Fix root issue", status: "pending", activeForm: "Fixing" },
-              {
-                id: "#fix-2",
-                content: "Fix dependent issue",
-                status: "pending",
-                activeForm: "Waiting",
-                blockedBy: ["#fix-1"],
-              },
-            ]),
-            wasInterrupted: false,
-          };
-        }
-
-        if (streamCallCount === 4 && sessionDir) {
-          await fsWriteFile(
-            join(sessionDir, "tasks.json"),
-            JSON.stringify([
-              { id: "#fix-1", content: "Fix root issue", status: "error", activeForm: "Fixing" },
-              {
-                id: "#fix-2",
-                content: "Fix dependent issue",
-                status: "pending",
-                activeForm: "Waiting",
-                blockedBy: ["#fix-1"],
-              },
-            ])
-          );
-          return { content: "", wasInterrupted: false };
-        }
-
-        throw new Error("Fix loop did not stop on dependency deadlock");
-      },
-      spawnSubagent: async () => ({
-        success: true,
-        output: JSON.stringify({
-          findings: [
-            {
-              title: "[P1] Issue requiring fix",
-              body: "Needs follow-up task",
-              priority: 1,
-            },
-          ],
-          overall_correctness: "patch is incorrect",
-          overall_explanation: "Fix required",
-          overall_confidence_score: 0.9,
-        }),
-      }),
-      clearContext: async () => {},
-      setRalphSessionDir: (dir: string | null) => {
-        sessionDir = dir;
-        if (dir) {
-          const { mkdirSync } = require("fs");
-          mkdirSync(dir, { recursive: true });
-        }
-      },
-      setRalphSessionId: () => {},
-      setRalphTaskIds: () => {},
-      updateWorkflowState: () => {},
-    });
-
-    const ralphCommand = getWorkflowCommands().find((cmd) => cmd.name === "ralph");
-    const result = await ralphCommand!.execute("Build a feature", context);
-    expect(result.success).toBe(true);
-    expect(streamCallCount).toBe(4);
-
-    if (sessionDir) {
-      await rm(sessionDir, { recursive: true, force: true });
-    }
-  });
 });
 
 describe("workflow inline mode", () => {
-  test("workflow completion returns stateUpdate with workflowActive: false", async () => {
-    // Mock streamAndWait to return a valid task JSON response
-    const taskJson = JSON.stringify([
-      { id: "#1", content: "Test task", status: "completed", activeForm: "Testing" }
-    ]);
-    const commands = getWorkflowCommands();
-    const ralphCommand = commands.find((cmd) => cmd.name === "ralph");
-    expect(ralphCommand).toBeDefined();
-    
-    const context = createMockContext({
-      streamAndWait: async () => ({ content: taskJson, wasInterrupted: false }),
-      state: { isStreaming: false, messageCount: 0, workflowActive: false },
-    });
-    
-    const result = await ralphCommand!.execute("Build a feature", context);
-    expect(result.success).toBe(true);
-    expect(result.stateUpdate).toBeDefined();
-    expect(result.stateUpdate?.workflowActive).toBe(false);
-    expect(result.stateUpdate?.workflowType).toBeNull();
-    expect(result.stateUpdate?.initialPrompt).toBeNull();
-  });
+
 
   test("waitForUserInput is present in CommandContext interface", () => {
     const context = createMockContext();
@@ -748,383 +481,17 @@ describe("workflow inline mode", () => {
     expect(result).toBe("user typed this");
   });
 
-  test("clearContext is not called during workflow execution", async () => {
-    let clearContextCalled = false;
-    const taskJson = JSON.stringify([
-      { id: "#1", content: "Test task", status: "completed", activeForm: "Testing" }
-    ]);
-    const commands = getWorkflowCommands();
-    const ralphCommand = commands.find((cmd) => cmd.name === "ralph");
-    
-    const context = createMockContext({
-      streamAndWait: async () => ({ content: taskJson, wasInterrupted: false }),
-      clearContext: async () => { clearContextCalled = true; },
-      state: { isStreaming: false, messageCount: 0, workflowActive: false },
-    });
-    
-    await ralphCommand!.execute("Build a feature", context);
-    expect(clearContextCalled).toBe(false);
-  });
-
-  test("interrupted step1 waits for user input and continues", async () => {
-    const commands = getWorkflowCommands();
-    const ralphCommand = commands.find((cmd) => cmd.name === "ralph");
-    const prompts: string[] = [];
-    let streamCallCount = 0;
-    let waitForUserInputCalled = false;
 
-    const context = createMockContext({
-      waitForUserInput: async () => {
-        waitForUserInputCalled = true;
-        return "retry planning with smaller scope";
-      },
-      streamAndWait: async (prompt: string) => {
-        prompts.push(prompt);
-        streamCallCount++;
 
-        if (streamCallCount === 1) {
-          return { content: "", wasInterrupted: true };
-        }
 
-        if (streamCallCount === 2) {
-          return {
-            content: JSON.stringify([
-              {
-                id: "#1",
-                content: "Test task",
-                status: "completed",
-                activeForm: "Testing",
-              },
-            ]),
-            wasInterrupted: false,
-          };
-        }
-
-        return { content: "done", wasInterrupted: false };
-      },
-      state: { isStreaming: false, messageCount: 0, workflowActive: false },
-    });
-
-    const result = await ralphCommand!.execute("Build something", context);
-
-    expect(waitForUserInputCalled).toBe(true);
-    expect(streamCallCount).toBeGreaterThanOrEqual(2);
-    expect(prompts[1]).toContain("retry planning with smaller scope");
-    expect(result.success).toBe(true);
-    expect(result.stateUpdate).toBeDefined();
-    expect(result.stateUpdate?.workflowActive).toBe(false);
-  });
 });
 
 describe("workflow inline mode integration", () => {
-  test("#16 - Ralph end-to-end without clearContext calls", async () => {
-    let clearContextCalled = false;
-    let streamCallCount = 0;
-    let sessionDir: string | null = null;
-    const spawnCalls: Array<{ name?: string; message: string }> = [];
-
-    const context = createMockContext({
-      streamAndWait: async (prompt: string, options?: { hideContent?: boolean }) => {
-        streamCallCount++;
-
-        if (streamCallCount === 1) {
-          // Step 1: Initial task decomposition
-          return {
-            content: JSON.stringify([
-              { id: "#1", content: "Task 1", status: "pending", activeForm: "Working" },
-            ]),
-            wasInterrupted: false,
-          };
-        }
-
-        if (streamCallCount === 2) {
-          // Step 2: Implementation - write completed tasks
-          if (sessionDir) {
-            await fsWriteFile(
-              join(sessionDir, "tasks.json"),
-              JSON.stringify([
-                { id: "#1", content: "Task 1", status: "completed", activeForm: "Working" },
-              ])
-            );
-          }
-          return { content: "Task completed", wasInterrupted: false };
-        }
-
-        if (streamCallCount === 3 && options?.hideContent) {
-          // Step 3: Fix task decomposition (after review finds issues)
-          return {
-            content: JSON.stringify([
-              { id: "#fix-1", content: "Fix this", status: "pending", activeForm: "Fixing" },
-            ]),
-            wasInterrupted: false,
-          };
-        }
-
-        if (streamCallCount === 4) {
-          // Step 4: Fix implementation
-          if (sessionDir) {
-            await fsWriteFile(
-              join(sessionDir, "tasks.json"),
-              JSON.stringify([
-                { id: "#fix-1", content: "Fix this", status: "completed", activeForm: "Fixing" },
-              ])
-            );
-          }
-          return { content: "Fix completed", wasInterrupted: false };
-        }
-
-        return { content: "", wasInterrupted: false };
-      },
-      spawnSubagent: async (options) => {
-        spawnCalls.push({ name: options.name, message: options.message });
-        // Return reviewer output with findings
-        return {
-          success: true,
-          output: JSON.stringify({
-            findings: [
-              {
-                title: "[P1] Fix this",
-                body: "Details",
-                priority: 1,
-              },
-            ],
-            overall_correctness: "patch is incorrect",
-            overall_explanation: "Fix needed",
-            overall_confidence_score: 0.9,
-          }),
-        };
-      },
-      clearContext: async () => {
-        clearContextCalled = true;
-      },
-      setRalphSessionDir: (dir: string | null) => {
-        sessionDir = dir;
-        if (dir) {
-          const { mkdirSync } = require("fs");
-          mkdirSync(dir, { recursive: true });
-        }
-      },
-      setRalphSessionId: () => {},
-      setRalphTaskIds: () => {},
-      updateWorkflowState: () => {},
-    });
-
-    const ralphCommand = getWorkflowCommands().find((cmd) => cmd.name === "ralph");
-    expect(ralphCommand).toBeDefined();
-
-    const result = await ralphCommand!.execute("Build feature", context);
-
-    // Assert: clearContext was NEVER called
-    expect(clearContextCalled).toBe(false);
-    
-    // Assert: result.success is true
-    expect(result.success).toBe(true);
-    
-    // Assert: result.stateUpdate.workflowActive is false
-    expect(result.stateUpdate?.workflowActive).toBe(false);
-
-    // Cleanup
-    if (sessionDir) {
-      await rm(sessionDir, { recursive: true, force: true });
-    }
-  });
-
-  test("#17 - user prompt passthrough after Ctrl+C in workflow", async () => {
-    let streamCallCount = 0;
-    let sessionDir: string | null = null;
-    const streamPrompts: string[] = [];
-    let waitForUserInputCalled = false;
-
-    const context = createMockContext({
-      waitForUserInput: async () => {
-        waitForUserInputCalled = true;
-        return "please fix the button color";
-      },
-      streamAndWait: async (prompt: string) => {
-        streamCallCount++;
-        streamPrompts.push(prompt);
-
-        if (streamCallCount === 1) {
-          // Step 1: Initial decomposition with 2 tasks
-          return {
-            content: JSON.stringify([
-              { id: "#1", content: "Task 1", status: "pending", activeForm: "Working" },
-              { id: "#2", content: "Task 2", status: "pending", activeForm: "Working" },
-            ]),
-            wasInterrupted: false,
-          };
-        }
-
-        if (streamCallCount === 2) {
-          // Step 2: First task implementation - simulates Ctrl+C
-          if (sessionDir) {
-            await fsWriteFile(
-              join(sessionDir, "tasks.json"),
-              JSON.stringify([
-                { id: "#1", content: "Task 1", status: "completed", activeForm: "Working" },
-                { id: "#2", content: "Task 2", status: "pending", activeForm: "Working" },
-              ])
-            );
-          }
-          return { content: "Task 1 done", wasInterrupted: true };
-        }
-
-        if (streamCallCount === 3) {
-          // Step 3: Continue after user input - should contain user's prompt
-          if (sessionDir) {
-            await fsWriteFile(
-              join(sessionDir, "tasks.json"),
-              JSON.stringify([
-                { id: "#1", content: "Task 1", status: "completed", activeForm: "Working" },
-                { id: "#2", content: "Task 2", status: "completed", activeForm: "Working" },
-              ])
-            );
-          }
-          return { content: "Task 2 done", wasInterrupted: false };
-        }
-
-        return { content: "", wasInterrupted: false };
-      },
-      spawnSubagent: async () => {
-        // Return clean review (no actionable findings)
-        return {
-          success: true,
-          output: JSON.stringify({
-            findings: [],
-            overall_correctness: "correct",
-            overall_explanation: "All changes look good",
-            overall_confidence_score: 0.95,
-          }),
-        };
-      },
-      setRalphSessionDir: (dir: string | null) => {
-        sessionDir = dir;
-        if (dir) {
-          const { mkdirSync } = require("fs");
-          mkdirSync(dir, { recursive: true });
-        }
-      },
-      setRalphSessionId: () => {},
-      setRalphTaskIds: () => {},
-      updateWorkflowState: () => {},
-    });
-
-    const ralphCommand = getWorkflowCommands().find((cmd) => cmd.name === "ralph");
-    expect(ralphCommand).toBeDefined();
-
-    const result = await ralphCommand!.execute("Build feature", context);
-
-    // Verify waitForUserInput was called
-    expect(waitForUserInputCalled).toBe(true);
-
-    // Verify the third streamAndWait call's prompt contains the user's input
-    expect(streamPrompts.length).toBeGreaterThanOrEqual(3);
-    expect(streamPrompts[2]).toContain("please fix the button color");
 
-    // Verify result.success is true
-    expect(result.success).toBe(true);
 
-    // Cleanup
-    if (sessionDir) {
-      await rm(sessionDir, { recursive: true, force: true });
-    }
-  });
-
-  test("#18 - task list persists after Ctrl+C, hides on completion", async () => {
-    let streamCallCount = 0;
-    let sessionDir: string | null = null;
-    const setRalphSessionDirCalls: Array<string | null> = [];
-    const updateWorkflowStateCalls: Array<Partial<{ workflowActive: boolean }>> = [];
-
-    const context = createMockContext({
-      waitForUserInput: async () => "continue",
-      streamAndWait: async (prompt: string) => {
-        streamCallCount++;
-
-        if (streamCallCount === 1) {
-          // Step 1: Initial decomposition
-          return {
-            content: JSON.stringify([
-              { id: "#1", content: "Task 1", status: "pending", activeForm: "Working" },
-            ]),
-            wasInterrupted: false,
-          };
-        }
-
-        if (streamCallCount === 2) {
-          // Step 2: Ctrl+C during implementation
-          if (sessionDir) {
-            await fsWriteFile(
-              join(sessionDir, "tasks.json"),
-              JSON.stringify([
-                { id: "#1", content: "Task 1", status: "in_progress", activeForm: "Working" },
-              ])
-            );
-          }
-          return { content: "Working...", wasInterrupted: true };
-        }
-
-        if (streamCallCount === 3) {
-          // Step 3: Continue after user input
-          if (sessionDir) {
-            await fsWriteFile(
-              join(sessionDir, "tasks.json"),
-              JSON.stringify([
-                { id: "#1", content: "Task 1", status: "completed", activeForm: "Working" },
-              ])
-            );
-          }
-          return { content: "Task completed", wasInterrupted: false };
-        }
-
-        return { content: "", wasInterrupted: false };
-      },
-      spawnSubagent: async () => {
-        // Return clean review
-        return {
-          success: true,
-          output: JSON.stringify({
-            findings: [],
-            overall_correctness: "correct",
-            overall_explanation: "All good",
-            overall_confidence_score: 0.95,
-          }),
-        };
-      },
-      setRalphSessionDir: (dir: string | null) => {
-        setRalphSessionDirCalls.push(dir);
-        sessionDir = dir;
-        if (dir) {
-          const { mkdirSync } = require("fs");
-          mkdirSync(dir, { recursive: true });
-        }
-      },
-      updateWorkflowState: (state: Partial<{ workflowActive: boolean }>) => {
-        updateWorkflowStateCalls.push(state);
-      },
-      setRalphSessionId: () => {},
-      setRalphTaskIds: () => {},
-    });
-
-    const ralphCommand = getWorkflowCommands().find((cmd) => cmd.name === "ralph");
-    expect(ralphCommand).toBeDefined();
 
-    const result = await ralphCommand!.execute("Build feature", context);
 
-    // Verify setRalphSessionDir was called with a non-null path at start
-    expect(setRalphSessionDirCalls.length).toBeGreaterThan(0);
-    expect(setRalphSessionDirCalls[0]).not.toBeNull();
 
-    // Verify setRalphSessionDir(null) was NOT called during workflow
-    const nullCalls = setRalphSessionDirCalls.filter((dir) => dir === null);
-    expect(nullCalls.length).toBe(0);
 
-    // Verify result.stateUpdate.workflowActive is false (signals task list should hide)
-    expect(result.stateUpdate?.workflowActive).toBe(false);
 
-    // Cleanup
-    if (sessionDir) {
-      await rm(sessionDir, { recursive: true, force: true });
-    }
-  });
 });
diff --git a/src/ui/commands/workflow-commands.ts b/src/ui/commands/workflow-commands.ts
index 5b1eee5d59..dbd428604b 100644
--- a/src/ui/commands/workflow-commands.ts
+++ b/src/ui/commands/workflow-commands.ts
@@ -20,6 +20,10 @@ import type {
 } from "./registry.ts";
 import { globalRegistry } from "./registry.ts";
 import type { TodoItem } from "../../sdk/tools/todo-write.ts";
+import type {
+    WorkflowRuntimeFeatureFlagOverrides,
+    WorkflowRuntimeTaskResultEnvelope,
+} from "../../workflows/runtime-contracts.ts";
 
 import {
     normalizeTodoItem,
@@ -31,23 +35,11 @@ import {
     getWorkflowSessionDir,
     type WorkflowSession,
 } from "../../workflows/session.ts";
-import {
-    buildSpecToTasksPrompt,
-    buildBootstrappedTaskContext,
-    buildContinuePrompt,
-    buildReviewPrompt,
-    parseReviewResult,
-    buildFixSpecFromReview,
-} from "../../graph/nodes/ralph.ts";
-
-// ============================================================================
-// CONSTANTS
-// ============================================================================
-
-/** Maximum number of iterations for the main implementation loop to prevent infinite loops */
-const MAX_RALPH_ITERATIONS = 100;
-/** Maximum number of review-fix cycles to prevent infinite loops */
-const MAX_REVIEW_ITERATIONS = 1;
+import type { BaseState, NodeDefinition, Edge } from "../../workflows/graph/types.ts";
+import { VERSION } from "../../version.ts";
+import { executeWorkflow } from "../../workflows/executor.ts";
+import { createRalphWorkflow } from "../../workflows/ralph/graph.ts";
+import { ralphWorkflowDefinition } from "../../workflows/ralph/definition.ts";
 
 // ============================================================================
 // RALPH COMMAND PARSING
@@ -77,6 +69,14 @@ export function parseRalphArgs(args: string): RalphCommandArgs {
 // TYPES
 // ============================================================================
 
+/**
+ * State migration function exported by custom workflows.
+ */
+export type WorkflowStateMigrator = (
+    oldState: unknown,
+    fromVersion: number,
+) => BaseState;
+
 /**
  * Metadata for a workflow command definition.
  */
@@ -89,12 +89,99 @@ export interface WorkflowMetadata {
     aliases?: string[];
     /** Optional default configuration */
     defaultConfig?: Record<string, unknown>;
+    /** Workflow definition version (semver) */
+    version?: string;
+    /** Minimum SDK version required to run this workflow */
+    minSDKVersion?: string;
+    /** Workflow state schema version for migrations */
+    stateVersion?: number;
+    /** Optional state migrator for loading persisted state from older versions */
+    migrateState?: WorkflowStateMigrator;
     /** Source: built-in, global (~/.atomic/workflows), or local (.atomic/workflows) */
     source?: "builtin" | "global" | "local";
     /** Hint text showing expected arguments (e.g., "PROMPT [--yolo]") */
     argumentHint?: string;
 }
 
+/**
+ * Standard task interface for workflow task list UI.
+ * All task-list-capable workflows must use this shape.
+ */
+export interface WorkflowTask {
+    /** Unique task identifier */
+    id: string;
+    /** Human-readable task title */
+    title: string;
+    /** Task status */
+    status: "pending" | "in_progress" | "completed" | "failed" | "blocked";
+    /** Optional task dependencies (IDs of tasks that must complete first) */
+    blockedBy?: string[];
+    /** Optional error message if status is "failed" */
+    error?: string;
+}
+
+/**
+ * Declarative graph configuration exported by custom workflows.
+ * The framework compiles this into a CompiledGraph.
+ */
+export interface WorkflowGraphConfig<TState extends BaseState = BaseState> {
+    /** Node definitions for the graph */
+    nodes: NodeDefinition<TState>[];
+    /** Edge definitions connecting nodes */
+    edges: Edge<TState>[];
+    /** The starting node ID */
+    startNode: string;
+    /** Maximum iterations for loops (default: 100) */
+    maxIterations?: number;
+}
+
+/**
+ * Parameters passed to a workflow's createState() factory function.
+ */
+export interface WorkflowStateParams {
+    /** The user's prompt text */
+    prompt: string;
+    /** UUID session ID for this execution */
+    sessionId: string;
+    /** Session directory path */
+    sessionDir: string;
+    /** Maximum iterations (from workflow config or global default) */
+    maxIterations: number;
+}
+
+/**
+ * Extended workflow definition that includes execution logic.
+ * Backward-compatible with WorkflowMetadata (all new fields optional).
+ * Fully declarative — capabilities are inferred from the graph definition.
+ */
+export interface WorkflowDefinition extends WorkflowMetadata {
+    /**
+     * Declarative graph configuration for this workflow.
+     * The framework validates and compiles this into a CompiledGraph.
+     * If absent, the workflow falls back to the generic chat handler.
+     */
+    graphConfig?: WorkflowGraphConfig;
+
+    /**
+     * Factory function to create the initial state for graph execution.
+     * Receives the user's prompt and session context.
+     */
+    createState?: (params: WorkflowStateParams) => BaseState;
+
+    /**
+     * Map of node IDs to human-readable progress descriptions.
+     * Replaces the hardcoded getNodePhaseDescription().
+     * Nodes not in this map are silently skipped in UI progress.
+     * Example: { "planner": "🧠 Planning tasks...", "worker": "⚡ Implementing..." }
+     */
+    nodeDescriptions?: Record<string, string>;
+
+    /** Optional runtime configuration for execution-only behavior toggles. */
+    runtime?: {
+        featureFlags?: WorkflowRuntimeFeatureFlagOverrides;
+    };
+}
+
 // ============================================================================
 // WORKFLOW SESSION MANAGEMENT
 // ============================================================================
@@ -113,6 +200,13 @@ export function getActiveSession(): WorkflowSession | undefined {
     )[0];
 }
 
+/**
+ * Register an active workflow session for tracking.
+ */
+export function registerActiveSession(session: WorkflowSession): void {
+    activeSessions.set(session.sessionId, session);
+}
+
 /**
  * Complete and remove a session.
  */
@@ -169,6 +263,7 @@ export async function saveTasksToActiveSession(
         status: string;
         activeForm: string;
         blockedBy?: string[];
+        taskResult?: WorkflowRuntimeTaskResultEnvelope;
     }>,
     sessionId?: string,
 ): Promise<void> {
@@ -182,7 +277,7 @@ export async function saveTasksToActiveSession(
     }
     if (!sessionDir) {
         console.error(
-            "[ralph] saveTasksToActiveSession: no session directory found",
+            "[workflow] saveTasksToActiveSession: no session directory found",
         );
         return;
     }
@@ -195,7 +290,7 @@ export async function saveTasksToActiveSession(
         );
         await atomicWrite(tasksPath, content);
     } catch (error) {
-        console.error("[ralph] Failed to write tasks.json:", error);
+        console.error("[workflow] Failed to write tasks.json:", error);
     }
 }
 
@@ -257,6 +352,46 @@ function expandPath(path: string): string {
     return path;
 }
 
+const SEMVER_PATTERN =
+    /^v?\d+\.\d+\.\d+(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+
+function parseSemver(version: string): [number, number, number] | null {
+    const normalized = version.trim();
+
+    if (!SEMVER_PATTERN.test(normalized)) {
+        return null;
+    }
+
+    const coreVersion =
+        normalized.replace(/^v/i, "").split(/[+-]/, 1)[0] ?? "0.0.0";
+    const [major = "0", minor = "0", patch = "0"] = coreVersion.split(".");
+
+    return [
+        Number.parseInt(major, 10),
+        Number.parseInt(minor, 10),
+        Number.parseInt(patch, 10),
+    ];
+}
+
+function isWorkflowMinSdkNewerThanCurrent(
+    minSdkVersion: string,
+    currentSdkVersion: string,
+): boolean {
+    const minVersion = parseSemver(minSdkVersion);
+    const currentVersion = parseSemver(currentSdkVersion);
+
+    if (!minVersion || !currentVersion) {
+        return false;
+    }
+
+    const [minMajor, minMinor, minPatch] = minVersion;
+    const [curMajor, curMinor, curPatch] = currentVersion;
+
+    if (minMajor !== curMajor) return minMajor > curMajor;
+    if (minMinor !== curMinor) return minMinor > curMinor;
+    return minPatch > curPatch;
+}
+
 /**
  * Discover workflow files from disk.
  * Returns paths to .ts files that define workflows.
@@ -300,7 +435,7 @@ export function discoverWorkflowFiles(): {
  * Dynamically loaded workflows from disk.
  * Populated by loadWorkflowsFromDisk().
  */
-let loadedWorkflows: WorkflowMetadata[] = [];
+let loadedWorkflows: WorkflowDefinition[] = [];
 
 /**
  * Load workflow definitions from .ts files on disk.
@@ -309,6 +444,13 @@ let loadedWorkflows: WorkflowMetadata[] = [];
  * - `name`: Workflow name (optional, defaults to filename)
  * - `description`: Human-readable description (optional)
  * - `aliases`: Alternative names (optional)
+ * - `version`: Workflow version (optional)
+ * - `minSDKVersion`: Minimum required SDK version (optional)
+ * - `stateVersion`: Workflow state schema version (optional)
+ * - `migrateState(oldState, fromVersion)`: State migration handler (optional)
+ * - `graphConfig`: Declarative graph configuration (optional)
+ * - `createState`: Factory function to create initial state (optional)
+ * - `nodeDescriptions`: Map of node IDs to progress descriptions (optional)
  *
  * Example workflow file (.atomic/workflows/my-workflow.ts):
  * ```typescript
@@ -317,11 +459,11 @@ let loadedWorkflows: WorkflowMetadata[] = [];
  * export const aliases = ["mw"];
  * ```
  *
- * @returns Array of loaded workflow metadata (local workflows override global)
+ * @returns Array of loaded workflow definitions (local workflows override global)
  */
-export async function loadWorkflowsFromDisk(): Promise<WorkflowMetadata[]> {
+export async function loadWorkflowsFromDisk(): Promise<WorkflowDefinition[]> {
     const discovered = discoverWorkflowFiles();
-    const loaded: WorkflowMetadata[] = [];
+    const loaded: WorkflowDefinition[] = [];
     const loadedNames = new Set<string>();
 
     for (const { path, source } of discovered) {
@@ -339,20 +481,87 @@ export async function loadWorkflowsFromDisk(): Promise<WorkflowMetadata[]> {
                 continue;
             }
 
-            const metadata: WorkflowMetadata = {
+            const migrateState =
+                typeof module.migrateState === "function"
+                    ? (module.migrateState as WorkflowStateMigrator)
+                    : undefined;
+
+            // Extract new WorkflowDefinition fields (optional)
+            const graphConfig = module.graphConfig as WorkflowGraphConfig | undefined;
+            const createState = module.createState as ((params: WorkflowStateParams) => BaseState) | undefined;
+            const nodeDescriptions = module.nodeDescriptions as Record<string, string> | undefined;
+            const runtime = module.runtime as WorkflowDefinition["runtime"] | undefined;
+
+            // Validate graph config (Task #33)
+            if (graphConfig) {
+                const nodeIds = new Set(graphConfig.nodes.map(n => n.id));
+                
+                if (!nodeIds.has(graphConfig.startNode)) {
+                    console.warn(`[workflow:${name}] startNode "${graphConfig.startNode}" not found in nodes`);
+                }
+                
+                for (const edge of graphConfig.edges) {
+                    if (!nodeIds.has(edge.from)) {
+                        console.warn(`[workflow:${name}] edge from "${edge.from}" references unknown node`);
+                    }
+                    if (!nodeIds.has(edge.to)) {
+                        console.warn(`[workflow:${name}] edge to "${edge.to}" references unknown node`);
+                    }
+                }
+                
+                // Check for orphan nodes (nodes with no edges to/from them, except startNode)
+                const nodesWithEdges = new Set<string>();
+                for (const edge of graphConfig.edges) {
+                    nodesWithEdges.add(edge.from);
+                    nodesWithEdges.add(edge.to);
+                }
+                
+                for (const node of graphConfig.nodes) {
+                    if (node.id !== graphConfig.startNode && !nodesWithEdges.has(node.id)) {
+                        console.warn(`[workflow:${name}] node "${node.id}" is orphaned (no edges to/from it)`);
+                    }
+                }
+            }
+
+            const definition: WorkflowDefinition = {
                 name,
                 description: module.description ?? `Custom workflow: ${name}`,
                 aliases: module.aliases,
                 defaultConfig: module.defaultConfig,
+                version: module.version,
+                minSDKVersion: module.minSDKVersion,
+                stateVersion: module.stateVersion,
+                migrateState,
                 source,
+                graphConfig,
+                createState,
+                nodeDescriptions,
+                runtime,
             };
 
-            loaded.push(metadata);
+            if (typeof definition.minSDKVersion === "string") {
+                if (!parseSemver(definition.minSDKVersion)) {
+                    console.warn(
+                        `Workflow "${definition.name}" has invalid minSDKVersion "${definition.minSDKVersion}". Expected semver format like "1.2.3".`,
+                    );
+                } else if (
+                    isWorkflowMinSdkNewerThanCurrent(
+                        definition.minSDKVersion,
+                        VERSION,
+                    )
+                ) {
+                    console.warn(
+                        `Workflow "${definition.name}" requires SDK ${definition.minSDKVersion}, but current SDK is ${VERSION}.`,
+                    );
+                }
+            }
+
+            loaded.push(definition);
             loadedNames.add(name.toLowerCase());
 
             // Also track aliases
-            if (metadata.aliases) {
-                for (const alias of metadata.aliases) {
+            if (definition.aliases) {
+                for (const alias of definition.aliases) {
                     loadedNames.add(alias.toLowerCase());
                 }
             }
@@ -407,19 +616,9 @@ export function getAllWorkflows(): WorkflowMetadata[] {
 /**
  * Built-in workflow definitions.
  * These can be overridden by local or global workflows with the same name.
- *
- * The ralph workflow is a two-step workflow:
- *   1. decompose — Task list decomposition from user prompt
- *   2. implement — Main agent manually dispatches worker sub-agents
  */
-const BUILTIN_WORKFLOW_DEFINITIONS: WorkflowMetadata[] = [
-    {
-        name: "ralph",
-        description: "Start autonomous implementation workflow",
-        aliases: ["loop"],
-        argumentHint: '"<prompt-or-spec-path>"',
-        source: "builtin",
-    },
+const BUILTIN_WORKFLOW_DEFINITIONS: WorkflowDefinition[] = [
+    ralphWorkflowDefinition,
 ];
 
 // ============================================================================
@@ -428,16 +627,59 @@ const BUILTIN_WORKFLOW_DEFINITIONS: WorkflowMetadata[] = [
 
 /**
  * Create a command definition for a workflow.
+ * Handles both graph-based workflows (via executeWorkflow) and chat-based workflows.
  *
- * @param metadata - Workflow metadata
+ * @param metadata - Workflow metadata (may be a full WorkflowDefinition)
  * @returns Command definition for the workflow
  */
 function createWorkflowCommand(metadata: WorkflowMetadata): CommandDefinition {
-    // Use specialized handler for ralph workflow
-    if (metadata.name === "ralph") {
-        return createRalphCommand(metadata);
+    const definition = metadata as WorkflowDefinition;
+    const hasExecutionLogic = definition.createState || definition.graphConfig;
+
+    if (hasExecutionLogic) {
+        // Graph-based workflow — use executeWorkflow() for full lifecycle
+        return {
+            name: metadata.name,
+            description: metadata.description,
+            category: "workflow",
+            aliases: metadata.aliases,
+            argumentHint: metadata.argumentHint,
+            execute: async (
+                args: string,
+                context: CommandContext,
+            ): Promise<CommandResult> => {
+                if (context.state.workflowActive) {
+                    return {
+                        success: false,
+                        message: `A workflow is already active (${context.state.workflowType}).`,
+                    };
+                }
+
+                let parsed: RalphCommandArgs;
+                try {
+                    parsed = parseRalphArgs(args);
+                } catch (e) {
+                    return {
+                        success: false,
+                        message: e instanceof Error ? e.message : String(e),
+                    };
+                }
+
+                // Ralph uses builder pattern (createRalphWorkflow) instead of declarative graphConfig
+                const compiledGraph = definition.name === "ralph"
+                    ? createRalphWorkflow() as unknown as import("../../workflows/graph/types.ts").CompiledGraph<BaseState>
+                    : undefined;
+
+                return executeWorkflow(definition, parsed.prompt, context, {
+                    compiledGraph,
+                    saveTasksToSession: saveTasksToActiveSession,
+                    eventBus: context.eventBus,
+                });
+            },
+        };
     }
 
+    // Chat-based workflow — simple state update, no graph execution
     return {
         name: metadata.name,
         description: metadata.description,
@@ -445,7 +687,6 @@ function createWorkflowCommand(metadata: WorkflowMetadata): CommandDefinition {
         aliases: metadata.aliases,
         argumentHint: metadata.argumentHint,
         execute: (args: string, context: CommandContext): CommandResult => {
-            // Check if already in a workflow
             if (context.state.workflowActive) {
                 return {
                     success: false,
@@ -453,7 +694,6 @@ function createWorkflowCommand(metadata: WorkflowMetadata): CommandDefinition {
                 };
             }
 
-            // Extract the prompt from args
             const initialPrompt = args.trim() || null;
 
             if (!initialPrompt) {
@@ -463,13 +703,11 @@ function createWorkflowCommand(metadata: WorkflowMetadata): CommandDefinition {
                 };
             }
 
-            // Add a system message indicating workflow start
             context.addMessage(
                 "system",
                 `Starting **${metadata.name}** workflow...\n\nPrompt: "${initialPrompt}"`,
             );
 
-            // Return success with state updates
             return {
                 success: true,
                 message: `Workflow **${metadata.name}** initialized. Researching codebase...`,
@@ -486,402 +724,6 @@ function createWorkflowCommand(metadata: WorkflowMetadata): CommandDefinition {
     };
 }
 
-/**
- * Parse a JSON task list from streaming content.
- * Handles both raw JSON arrays and content with markdown fences or extra text.
- */
-function parseTasks(content: string): NormalizedTodoItem[] {
-    const trimmed = content.trim();
-    let parsed: unknown = null;
-    try {
-        parsed = JSON.parse(trimmed);
-    } catch {
-        const match = trimmed.match(/\[[\s\S]*\]/);
-        if (match) {
-            try {
-                parsed = JSON.parse(match[0]);
-            } catch {
-                /* ignore */
-            }
-        }
-    }
-    if (!Array.isArray(parsed) || parsed.length === 0) return [];
-    return normalizeTodoItems(parsed);
-}
-
-function hasActionableTasks(tasks: NormalizedTodoItem[]): boolean {
-    const normalizeTaskId = (id: string): string => {
-        const trimmed = id.trim().toLowerCase();
-        return trimmed.startsWith("#") ? trimmed.slice(1) : trimmed;
-    };
-
-    const completedIds = new Set(
-        tasks
-            .filter((task) => task.status === "completed")
-            .map((task) => task.id)
-            .filter((id): id is string => Boolean(id))
-            .map((id) => normalizeTaskId(id))
-            .filter((id): id is string => Boolean(id)),
-    );
-
-    return tasks.some((task) => {
-        if (task.status === "in_progress") {
-            return true;
-        }
-        if (task.status !== "pending") {
-            return false;
-        }
-
-        const dependencies = (task.blockedBy ?? [])
-            .map((dependency) => normalizeTaskId(dependency))
-            .filter((dependency) => dependency.length > 0);
-
-        if (dependencies.length === 0) {
-            return true;
-        }
-
-        return dependencies.every((dependency) => completedIds.has(dependency));
-    });
-}
-
-type StreamAndWaitResult = Awaited<ReturnType<CommandContext["streamAndWait"]>>;
-
-async function streamWithInterruptRecovery(
-    context: CommandContext,
-    initialPrompt: string,
-    options?: { hideContent?: boolean },
-    onInterrupted?: (
-        userPrompt: string,
-    ) => { prompt: string; options?: { hideContent?: boolean } },
-): Promise<StreamAndWaitResult> {
-    let prompt = initialPrompt;
-    let streamOptions = options;
-
-    while (true) {
-        const result = await context.streamAndWait(prompt, streamOptions);
-
-        if (result.wasCancelled || !result.wasInterrupted) {
-            return result;
-        }
-
-        const userPrompt = await context.waitForUserInput();
-
-        if (onInterrupted) {
-            const next = onInterrupted(userPrompt);
-            prompt = next.prompt;
-            streamOptions = next.options;
-        } else {
-            prompt = userPrompt;
-            streamOptions = undefined;
-        }
-    }
-}
-
-function createRalphCommand(metadata: WorkflowMetadata): CommandDefinition {
-    return {
-        name: metadata.name,
-        description: metadata.description,
-        category: "workflow",
-        aliases: metadata.aliases,
-        argumentHint: metadata.argumentHint,
-        execute: async (
-            args: string,
-            context: CommandContext,
-        ): Promise<CommandResult> => {
-            if (context.state.workflowActive) {
-                return {
-                    success: false,
-                    message: `A workflow is already active (${context.state.workflowType}).`,
-                };
-            }
-
-            let parsed: RalphCommandArgs;
-            try {
-                parsed = parseRalphArgs(args);
-            } catch (e) {
-                return {
-                    success: false,
-                    message: e instanceof Error ? e.message : String(e),
-                };
-            }
-
-            // ── Two-step workflow (async/await) ──────────────────────────────
-            // Step 1: Task decomposition via streamAndWait
-            // Step 2: Feature implementation via worker sub-agent
-            // ────────────────────────────────────────────────────────────────
-
-            // Initialize a workflow session via the SDK
-            const sessionId = crypto.randomUUID();
-            const sessionDir = getWorkflowSessionDir(sessionId);
-            void initWorkflowSession("ralph", sessionId).then((session) => {
-                activeSessions.set(session.sessionId, session);
-            });
-
-            context.updateWorkflowState({
-                workflowActive: true,
-                workflowType: metadata.name,
-                ralphConfig: { sessionId, userPrompt: parsed.prompt },
-            });
-
-            try {
-                // Step 1: Task decomposition (blocks until streaming completes)
-                // hideContent suppresses raw JSON rendering in the chat — content is still
-                // accumulated in StreamResult for parseTasks() and task-state persistence takes over.
-                const step1 = await streamWithInterruptRecovery(
-                    context,
-                    buildSpecToTasksPrompt(parsed.prompt),
-                    { hideContent: true },
-                    (userPrompt) => ({
-                        prompt: buildSpecToTasksPrompt(userPrompt),
-                        options: { hideContent: true },
-                    }),
-                );
-                if (step1.wasCancelled)
-                    return {
-                        success: true,
-                        stateUpdate: {
-                            workflowActive: false,
-                            workflowType: null,
-                            initialPrompt: null,
-                        },
-                    };
-
-                // Parse tasks from step 1 output and save to disk (file watcher handles UI)
-                const tasks = parseTasks(step1.content);
-                if (tasks.length > 0) {
-                    await saveTasksToActiveSession(tasks, sessionId);
-                    // Seed in-memory TodoWrite state so later payloads that omit IDs
-                    // can be reconciled against the planning-phase task list.
-                    context.setTodoItems(
-                        tasks.map((task) => ({
-                            ...task,
-                            status:
-                                task.status === "error"
-                                    ? "pending"
-                                    : task.status,
-                        })) as TodoItem[],
-                    );
-                }
-
-            // Track Ralph session metadata AFTER tasks.json exists on disk
-            context.setRalphSessionDir(sessionDir);
-            context.setRalphSessionId(sessionId);
-
-            // Register the planning-phase task IDs so the TodoWrite persistence
-            // guard can distinguish ralph task updates from sub-agent todo lists.
-            const taskIds = new Set(
-                tasks
-                    .map((t) => t.id)
-                    .filter((id): id is string => id != null && id.length > 0),
-            );
-            context.setRalphTaskIds(taskIds);
-
-            // Step 2: Execute tasks in a loop until all are completed.
-            // The agent's context is blank after Step 1 (hideContent suppressed the JSON),
-            // so inject the task list and instructions for worker dispatch, then loop
-            // until tasks.json shows all items completed.
-            if (tasks.length > 0) {
-                let iteration = 0;
-                let currentTasks: NormalizedTodoItem[] = tasks;
-
-                while (iteration < MAX_RALPH_ITERATIONS) {
-                    iteration++;
-                    const prompt =
-                        iteration === 1
-                            ? buildBootstrappedTaskContext(
-                                  currentTasks,
-                                  sessionId,
-                              )
-                            : buildContinuePrompt(currentTasks, sessionId);
-
-                    const result = await streamWithInterruptRecovery(
-                        context,
-                        prompt,
-                    );
-                    if (result.wasCancelled) break;
-
-                    // Read latest task state from disk after agent response
-                    const diskTasks = await readTasksFromDisk(sessionDir);
-                    if (diskTasks.length === 0) break;
-
-                    // Check if all tasks are completed
-                    const allCompleted = diskTasks.every(
-                        (t) => t.status === "completed",
-                    );
-                    if (allCompleted) break;
-
-                    // Check if remaining tasks are all stuck (including dependency deadlocks)
-                    const hasActionable = hasActionableTasks(diskTasks);
-                    if (!hasActionable) break;
-
-                    currentTasks = diskTasks;
-                }
-
-                // Step 3: Review & Fix phase
-                // Re-read tasks from disk to confirm final state
-                const finalTasks = await readTasksFromDisk(sessionDir);
-                const allTasksCompleted =
-                    finalTasks.length > 0 &&
-                    finalTasks.every((t) => t.status === "completed");
-
-                if (allTasksCompleted) {
-                    for (
-                        let reviewIteration = 0;
-                        reviewIteration < MAX_REVIEW_ITERATIONS;
-                        reviewIteration++
-                    ) {
-                        // Get current task state for review
-                        const reviewTasks = await readTasksFromDisk(sessionDir);
-                        const reviewPrompt = buildReviewPrompt(
-                            reviewTasks,
-                            parsed.prompt,
-                        );
-
-                        // Spawn reviewer sub-agent
-                        const reviewResult = await context.spawnSubagent({
-                            name: "reviewer",
-                            message: reviewPrompt,
-                        });
-
-                        if (!reviewResult.success || !reviewResult.output)
-                            break;
-
-                        // Parse review findings from reviewer output
-                        const review = parseReviewResult(reviewResult.output);
-                        if (!review) break;
-
-                        // Persist review artifacts to session directory
-                        const reviewArtifactPath = join(
-                            sessionDir,
-                            `review-${reviewIteration}.json`,
-                        );
-                        await writeFile(
-                            reviewArtifactPath,
-                            JSON.stringify(review, null, 2),
-                        );
-
-                        // Build fix specification from review findings
-                        const fixSpec = buildFixSpecFromReview(
-                            review,
-                            reviewTasks,
-                            parsed.prompt,
-                        );
-
-                        // If no actionable findings, we're done
-                        if (!fixSpec) break;
-
-                        // Persist fix spec to session directory
-                        const fixSpecPath = join(
-                            sessionDir,
-                            `fix-spec-${reviewIteration}.md`,
-                        );
-                        await writeFile(fixSpecPath, fixSpec);
-
-                        // Re-invoke ralph: decompose fix-spec into tasks (Step 1 again)
-                        const fixStep1 = await streamWithInterruptRecovery(
-                            context,
-                            buildSpecToTasksPrompt(fixSpec),
-                            { hideContent: true },
-                            (userPrompt) => ({
-                                prompt: buildSpecToTasksPrompt(userPrompt),
-                                options: { hideContent: true },
-                            }),
-                        );
-                        if (fixStep1.wasCancelled) break;
-
-                        const fixTasks = parseTasks(fixStep1.content);
-                        if (fixTasks.length === 0) break;
-
-                        // Save fix tasks and update tracking
-                        await saveTasksToActiveSession(fixTasks, sessionId);
-                        const fixTaskIds = new Set(
-                            fixTasks
-                                .map((t) => t.id)
-                                .filter(
-                                    (id): id is string =>
-                                        id != null && id.length > 0,
-                                ),
-                        );
-                        context.setRalphTaskIds(fixTaskIds);
-
-                        // Re-run implementation loop for fix tasks (Step 2 again)
-                        let fixIteration = 0;
-                        let currentFixTasks: NormalizedTodoItem[] = fixTasks;
-
-                        while (fixIteration < MAX_RALPH_ITERATIONS) {
-                            fixIteration++;
-                            const prompt =
-                                fixIteration === 1
-                                    ? buildBootstrappedTaskContext(
-                                          currentFixTasks,
-                                          sessionId,
-                                      )
-                                    : buildContinuePrompt(
-                                          currentFixTasks,
-                                          sessionId,
-                                      );
-
-                            const result = await streamWithInterruptRecovery(
-                                context,
-                                prompt,
-                            );
-                            if (result.wasCancelled) break;
-
-                            // Read latest task state from disk after agent response
-                            const diskTasks =
-                                await readTasksFromDisk(sessionDir);
-                            if (diskTasks.length === 0) break;
-
-                            // Check if all fix tasks are completed
-                            const allFixCompleted = diskTasks.every(
-                                (t) => t.status === "completed",
-                            );
-                            if (allFixCompleted) break;
-
-                            // Check if remaining fix tasks are all stuck (including dependency deadlocks)
-                            const hasActionable = hasActionableTasks(diskTasks);
-                            if (!hasActionable) break;
-
-                            currentFixTasks = diskTasks;
-                        }
-                    }
-                }
-            }
-
-            return {
-                success: true,
-                stateUpdate: {
-                    workflowActive: false,
-                    workflowType: null,
-                    initialPrompt: null,
-                },
-            };
-            } catch (error) {
-                // Silent exit for workflow cancellation (double Ctrl+C)
-                if (error instanceof Error && error.message === "Workflow cancelled") {
-                    return {
-                        success: true,
-                        stateUpdate: {
-                            workflowActive: false,
-                            workflowType: null,
-                            initialPrompt: null,
-                        },
-                    };
-                }
-                return {
-                    success: false,
-                    message: `Workflow failed: ${error instanceof Error ? error.message : String(error)}`,
-                    stateUpdate: {
-                        workflowActive: false,
-                        workflowType: null,
-                        initialPrompt: null,
-                    },
-                };
-            }
-        },
-    };
-}
-
 // ============================================================================
 // FILE WATCHER
 // ============================================================================
@@ -893,10 +735,19 @@ export function watchTasksJson(
         watchImpl?: (
             filename: string,
             listener:
-                | ((eventType: string, filename: string | Buffer | null) => void)
-                | ((eventType: string, filename: string | Buffer | null) => Promise<void>),
+                | ((
+                      eventType: string,
+                      filename: string | Buffer | null,
+                  ) => void)
+                | ((
+                      eventType: string,
+                      filename: string | Buffer | null,
+                  ) => Promise<void>),
         ) => FSWatcher;
-        readFileImpl?: (path: string, encoding: BufferEncoding) => Promise<string>;
+        readFileImpl?: (
+            path: string,
+            encoding: BufferEncoding,
+        ) => Promise<string>;
     },
 ): () => void {
     const tasksPath = join(sessionDir, "tasks.json");
@@ -908,7 +759,9 @@ export function watchTasksJson(
     const isTasksJsonEvent = (filename: string | Buffer | null): boolean => {
         if (filename == null) return true;
         const normalized =
-            typeof filename === "string" ? filename : filename.toString("utf-8");
+            typeof filename === "string"
+                ? filename
+                : filename.toString("utf-8");
         return normalized === "tasks.json";
     };
 
diff --git a/src/ui/commands/workflow-inline-mode-e2e.test.ts b/src/ui/commands/workflow-inline-mode-e2e.test.ts
index e665a27118..565478b1d6 100644
--- a/src/ui/commands/workflow-inline-mode-e2e.test.ts
+++ b/src/ui/commands/workflow-inline-mode-e2e.test.ts
@@ -13,6 +13,37 @@ import { mkdirSync, existsSync, readFileSync } from "fs";
 import type { CommandContext, CommandContextState } from "./registry.ts";
 import { getWorkflowCommands } from "./workflow-commands.ts";
 
+function createDeferred<T>() {
+  let resolve!: (value: T | PromiseLike<T>) => void;
+  const promise = new Promise<T>((res) => {
+    resolve = res;
+  });
+  return { promise, resolve };
+}
+
+async function withTimeout<T>(
+  promise: Promise<T>,
+  timeoutMs: number,
+  timeoutMessage: string,
+): Promise<T> {
+  let timeoutId: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      promise,
+      new Promise<never>((_resolve, reject) => {
+        timeoutId = setTimeout(
+          () => reject(new Error(timeoutMessage)),
+          timeoutMs,
+        );
+      }),
+    ]);
+  } finally {
+    if (timeoutId) {
+      clearTimeout(timeoutId);
+    }
+  }
+}
+
 function createMockContext(overrides?: Partial<CommandContext>): CommandContext {
   return {
     session: null,
@@ -26,13 +57,21 @@ function createMockContext(overrides?: Partial<CommandContext>): CommandContext
     sendMessage: () => {},
     sendSilentMessage: () => {},
     spawnSubagent: async () => ({ success: true, output: "" }),
+    spawnSubagentParallel: async (agents) =>
+      agents.map((a) => ({
+        agentId: a.agentId,
+        success: true,
+        output: "Done",
+        toolUses: 1,
+        durationMs: 100,
+      })),
     streamAndWait: async () => ({ content: "", wasInterrupted: false }),
     waitForUserInput: async () => "",
     clearContext: async () => {},
     setTodoItems: () => {},
-    setRalphSessionDir: () => {},
-    setRalphSessionId: () => {},
-    setRalphTaskIds: () => {},
+    setWorkflowSessionDir: () => {},
+    setWorkflowSessionId: () => {},
+    setWorkflowTaskIds: () => {},
     updateWorkflowState: () => {},
     ...overrides,
   };
@@ -48,14 +87,14 @@ describe("Workflow inline mode E2E", () => {
       updateWorkflowState: (update) => {
         workflowStateUpdates.push(update);
       },
-      setRalphSessionDir: (dir) => {
+      setWorkflowSessionDir: (dir) => {
         sessionDir = dir;
         if (dir && !existsSync(dir)) {
           mkdirSync(dir, { recursive: true });
         }
       },
       streamAndWait: async (prompt: string) => {
-        // Call 1: Return task JSON
+        // Step 1: Return task JSON
         if (prompt.includes("task list")) {
           return {
             content: JSON.stringify([
@@ -69,23 +108,7 @@ describe("Workflow inline mode E2E", () => {
             wasInterrupted: false,
           };
         }
-
-        // Call 2: Write tasks.json completed, return content
-        if (sessionDir) {
-          const tasksPath = join(sessionDir, "tasks.json");
-          await fsWriteFile(
-            tasksPath,
-            JSON.stringify([
-              {
-                id: "#1",
-                content: "Task 1",
-                status: "completed",
-                activeForm: "Working on task 1",
-              },
-            ]),
-          );
-        }
-        return { content: "Task completed", wasInterrupted: false };
+        return { content: "", wasInterrupted: false };
       },
       spawnSubagent: async () => ({
         success: true,
@@ -133,117 +156,100 @@ describe("Workflow inline mode E2E", () => {
     }
   });
 
-  test("Ctrl+C interruption triggers user prompt and continues workflow", async () => {
-    // Track calls
-    const streamAndWaitCalls: string[] = [];
-    let waitForUserInputCallCount = 0;
+
+
+  test("review with findings triggers fixer and completes within timeout", async () => {
+    // Track all spawnSubagentParallel calls
+    const spawnCalls: Array<{ agentName: string }> = [];
     const workflowStateUpdates: Array<Partial<CommandContextState>> = [];
     let sessionDir: string | null = null;
-
     const context = createMockContext({
       updateWorkflowState: (update) => {
         workflowStateUpdates.push(update);
       },
-      setRalphSessionDir: (dir) => {
+      setWorkflowSessionDir: (dir) => {
         sessionDir = dir;
         if (dir && !existsSync(dir)) {
           mkdirSync(dir, { recursive: true });
+          // Create progress.txt file that reviewer needs
+          const progressPath = join(dir, "progress.txt");
+          fsWriteFile(progressPath, "Test workflow in progress\n", "utf-8").catch(() => {});
         }
       },
-      streamAndWait: async (prompt: string) => {
-        streamAndWaitCalls.push(prompt);
-
-        // Call 1: return 2 tasks JSON (step1 decomposition)
-        if (streamAndWaitCalls.length === 1) {
-          return {
-            content: JSON.stringify([
-              {
-                id: "#1",
-                content: "Task 1",
-                status: "pending",
-                activeForm: "Working on task 1",
-              },
-              {
-                id: "#2",
-                content: "Task 2",
-                status: "pending",
-                activeForm: "Working on task 2",
-              },
-            ]),
-            wasInterrupted: false,
-          };
-        }
-
-        // Call 2: return wasInterrupted: true (Ctrl+C during task 1)
-        if (streamAndWaitCalls.length === 2) {
-          return { content: "", wasInterrupted: true };
-        }
-
-        // Call 3: should receive prompt containing user's follow-up text, write task 1 completed to tasks.json
-        if (streamAndWaitCalls.length === 3) {
-          if (sessionDir) {
-            const tasksPath = join(sessionDir, "tasks.json");
-            await fsWriteFile(
-              tasksPath,
-              JSON.stringify([
-                {
-                  id: "#1",
-                  content: "Task 1",
-                  status: "completed",
-                  activeForm: "Working on task 1",
-                },
-                {
-                  id: "#2",
-                  content: "Task 2",
-                  status: "pending",
-                  activeForm: "Working on task 2",
-                },
+      setWorkflowSessionId: () => {},
+      setWorkflowTaskIds: () => {},
+      spawnSubagentParallel: async (agents) => {
+        return agents.map((a) => {
+          const agentName = a.agentName ?? a.agentId ?? "unknown";
+          spawnCalls.push({ agentName });
+          
+          // Planner: return task list
+          if (agentName === "planner") {
+            return {
+              agentId: a.agentId,
+              success: true,
+              output: JSON.stringify([
+                { id: "#1", content: "Add auth module", status: "pending", activeForm: "Adding auth", blockedBy: [] },
               ]),
-            );
+              toolUses: 1,
+              durationMs: 100,
+            };
           }
-          return { content: "Task 1 completed with alignment fix", wasInterrupted: false };
-        }
-
-        // Call 4: write task 2 completed to tasks.json, return content
-        if (streamAndWaitCalls.length === 4) {
-          if (sessionDir) {
-            const tasksPath = join(sessionDir, "tasks.json");
-            await fsWriteFile(
-              tasksPath,
-              JSON.stringify([
-                {
-                  id: "#1",
-                  content: "Task 1",
-                  status: "completed",
-                  activeForm: "Working on task 1",
-                },
-                {
-                  id: "#2",
-                  content: "Task 2",
-                  status: "completed",
-                  activeForm: "Working on task 2",
-                },
-              ]),
-            );
+          
+          // Worker: succeed
+          if (agentName === "worker") {
+            return {
+              agentId: a.agentId,
+              success: true,
+              output: "Implemented auth module",
+              toolUses: 3,
+              durationMs: 500,
+            };
           }
-          return { content: "Task 2 completed", wasInterrupted: false };
-        }
-
-        return { content: "", wasInterrupted: false };
-      },
-      waitForUserInput: async () => {
-        waitForUserInputCallCount++;
-        return "fix the alignment issue";
+          
+          // Reviewer: return findings that trigger fixes
+          if (agentName === "reviewer") {
+            return {
+              agentId: a.agentId,
+              success: true,
+              output: JSON.stringify({
+                findings: [
+                  {
+                    file: "src/auth.ts",
+                    description: "Missing input validation",
+                    severity: "high",
+                    priority: 1,
+                  },
+                ],
+                overall_correctness: "patch is correct",
+                overall_explanation: "Missing input validation in auth handler",
+              }),
+              toolUses: 2,
+              durationMs: 200,
+            };
+          }
+          
+          // Fixer: succeed (agentName is "debugger" in the graph)
+          if (agentName === "debugger") {
+            return {
+              agentId: a.agentId,
+              success: true,
+              output: "Fixed input validation",
+              toolUses: 2,
+              durationMs: 300,
+            };
+          }
+          
+          // Default fallback
+          return {
+            agentId: a.agentId,
+            success: true,
+            output: "OK",
+            toolUses: 0,
+            durationMs: 10,
+          };
+        });
       },
-      spawnSubagent: async () => ({
-        success: true,
-        output: JSON.stringify({
-          findings: [],
-          overall_correctness: "correct",
-          overall_explanation: "LGTM",
-          overall_confidence_score: 1.0,
-        }),
-      }),
     });
 
     // Get the ralph command
@@ -251,180 +257,163 @@ describe("Workflow inline mode E2E", () => {
     const ralphCommand = commands.find((cmd) => cmd.name === "ralph");
     expect(ralphCommand).toBeDefined();
 
-    // Run workflow
-    const result = await ralphCommand!.execute("Build feature", context);
-
-    // Assert: waitForUserInput was called exactly once
-    expect(waitForUserInputCallCount).toBe(1);
-
-    // Assert: streamAndWait call 3 prompt includes user's follow-up text
-    expect(streamAndWaitCalls[2]).toContain("fix the alignment issue");
+    // Run workflow — should complete without hanging
+    const result = await withTimeout(
+      Promise.resolve(ralphCommand!.execute("Build auth feature", context)),
+      3_000,
+      "ralph workflow did not complete in time",
+    );
 
-    // Assert: result.success is true
+    // Assert: workflow completed successfully
     expect(result.success).toBe(true);
-
-    // Assert: result.stateUpdate.workflowActive is false
     expect(result.stateUpdate?.workflowActive).toBe(false);
 
-    // Assert: updateWorkflowState was called with workflowActive: true at start
+    // Assert: workflowActive was set to true at start
     const hasWorkflowActive = workflowStateUpdates.some(
       (update) => update.workflowActive === true,
     );
     expect(hasWorkflowActive).toBe(true);
 
+    // Assert: spawnSubagentParallel was called for planner, worker, reviewer, AND fixer
+    const agentNames = spawnCalls.map((c) => c.agentName);
+    expect(agentNames).toContain("planner");
+    expect(agentNames).toContain("worker");
+    expect(agentNames).toContain("reviewer");
+    expect(agentNames).toContain("debugger"); // fixer uses "debugger" agentName
+
+    // NOTE: Task tracking is now done via bus events (workflow.task.update)
+    // instead of context.setTodoItems(). This test doesn't verify bus events yet.
+
+    // Assert: session dir was set
+    expect(sessionDir).not.toBeNull();
+
     // Clean up temp dir
     if (sessionDir && existsSync(sessionDir)) {
       await rm(sessionDir, { recursive: true, force: true });
     }
   });
 
-  test("task list persists through interruption and tasks.json is maintained", async () => {
-    // Track calls
+  test("keeps TUI workflow state responsive while worker execution is in-flight", async () => {
+    const workflowStateUpdates: Array<Partial<CommandContextState>> = [];
+    const streamingTransitions: boolean[] = [];
+    const trackedSessionDirs: Array<string | null> = [];
+    const trackedSessionIds: Array<string | null> = [];
+    const trackedTaskIdSizes: number[] = [];
     let sessionDir: string | null = null;
-    let sessionId: string | null = null;
-    let setRalphSessionDirCallCount = 0;
-    let setRalphSessionIdCallCount = 0;
-    let setRalphTaskIdsCallCount = 0;
+
+    const workerStarted = createDeferred<void>();
+    const releaseWorker = createDeferred<void>();
 
     const context = createMockContext({
-      setRalphSessionDir: (dir) => {
-        setRalphSessionDirCallCount++;
+      updateWorkflowState: (update) => {
+        workflowStateUpdates.push(update);
+      },
+      setStreaming: (value) => {
+        streamingTransitions.push(value);
+      },
+      setWorkflowSessionDir: (dir) => {
+        trackedSessionDirs.push(dir);
         sessionDir = dir;
         if (dir && !existsSync(dir)) {
           mkdirSync(dir, { recursive: true });
+          const progressPath = join(dir, "progress.txt");
+          fsWriteFile(progressPath, "Test workflow in progress\n", "utf-8").catch(() => {});
         }
       },
-      setRalphSessionId: (id) => {
-        setRalphSessionIdCallCount++;
-        sessionId = id;
+      setWorkflowSessionId: (id) => {
+        trackedSessionIds.push(id);
       },
-      setRalphTaskIds: () => {
-        setRalphTaskIdsCallCount++;
+      setWorkflowTaskIds: (ids) => {
+        trackedTaskIdSizes.push(ids.size);
       },
-      streamAndWait: async (prompt: string, options) => {
-        // Call 1: return task JSON with 2 tasks (step1)
-        if (prompt.includes("task list")) {
-          return {
-            content: JSON.stringify([
-              {
-                id: "#1",
-                content: "Task 1",
-                status: "pending",
-                activeForm: "Working on task 1",
-              },
-              {
-                id: "#2",
-                content: "Task 2",
-                status: "pending",
-                activeForm: "Working on task 2",
-              },
+      spawnSubagentParallel: async (agents) => {
+        const firstAgent = agents[0];
+        const agentName = firstAgent?.agentName ?? firstAgent?.agentId ?? "unknown";
+
+        if (agentName === "planner") {
+          return [{
+            agentId: firstAgent?.agentId ?? "planner-1",
+            success: true,
+            output: JSON.stringify([
+              { id: "#1", content: "Implement auth", status: "pending", activeForm: "Implementing auth", blockedBy: [] },
+              { id: "#2", content: "Add tests", status: "pending", activeForm: "Adding tests", blockedBy: [] },
             ]),
-            wasInterrupted: false,
-          };
+            toolUses: 1,
+            durationMs: 100,
+          }];
         }
 
-        // Call 2: return wasInterrupted: true (Ctrl+C)
-        if (!sessionDir) {
-          return { content: "", wasInterrupted: true };
+        if (agentName === "worker") {
+          workerStarted.resolve(undefined);
+          await releaseWorker.promise;
+          return agents.map((agent, index) => ({
+            agentId: agent.agentId,
+            success: true,
+            output: `Completed worker task ${index + 1}`,
+            toolUses: 2,
+            durationMs: 200,
+          }));
         }
 
-        // Call 3: write task 1 completed to tasks.json, return content
-        const tasksPath = join(sessionDir, "tasks.json");
-        const currentTasks = existsSync(tasksPath)
-          ? JSON.parse(readFileSync(tasksPath, "utf-8"))
-          : [];
-
-        if (currentTasks.length === 2 && currentTasks[0].status === "pending") {
-          await fsWriteFile(
-            tasksPath,
-            JSON.stringify([
-              {
-                id: "#1",
-                content: "Task 1",
-                status: "completed",
-                activeForm: "Working on task 1",
-              },
-              {
-                id: "#2",
-                content: "Task 2",
-                status: "pending",
-                activeForm: "Working on task 2",
-              },
-            ]),
-          );
-          return { content: "Task 1 completed", wasInterrupted: false };
+        if (agentName === "reviewer") {
+          return [{
+            agentId: firstAgent?.agentId ?? "reviewer-1",
+            success: true,
+            output: JSON.stringify({
+              findings: [],
+              overall_correctness: "patch is correct",
+              overall_explanation: "No issues",
+            }),
+            toolUses: 1,
+            durationMs: 100,
+          }];
         }
 
-        // Call 4: write task 2 completed to tasks.json, return content
-        await fsWriteFile(
-          tasksPath,
-          JSON.stringify([
-            {
-              id: "#1",
-              content: "Task 1",
-              status: "completed",
-              activeForm: "Working on task 1",
-            },
-            {
-              id: "#2",
-              content: "Task 2",
-              status: "completed",
-              activeForm: "Working on task 2",
-            },
-          ]),
-        );
-        return { content: "Task 2 completed", wasInterrupted: false };
+        return agents.map((agent) => ({
+          agentId: agent.agentId,
+          success: true,
+          output: "OK",
+          toolUses: 0,
+          durationMs: 10,
+        }));
       },
-      waitForUserInput: async () => "keep going",
-      spawnSubagent: async () => ({
-        success: true,
-        output: JSON.stringify({
-          findings: [],
-          overall_correctness: "correct",
-          overall_explanation: "LGTM",
-          overall_confidence_score: 1.0,
-        }),
-      }),
     });
 
-    // Get the ralph command
     const commands = getWorkflowCommands();
     const ralphCommand = commands.find((cmd) => cmd.name === "ralph");
     expect(ralphCommand).toBeDefined();
 
-    // Run workflow
-    const result = await ralphCommand!.execute("Build feature", context);
-
-    // Assert: setRalphSessionDir was called with a non-null string (dir was set)
-    expect(setRalphSessionDirCallCount).toBeGreaterThan(0);
-    expect(sessionDir).not.toBeNull();
-    expect(typeof sessionDir).toBe("string");
-
-    // Assert: setRalphSessionId was called with a non-null string
-    expect(setRalphSessionIdCallCount).toBeGreaterThan(0);
-    expect(sessionId).not.toBeNull();
-    expect(typeof sessionId).toBe("string");
-
-    // Assert: setRalphTaskIds was called (tasks were tracked)
-    expect(setRalphTaskIdsCallCount).toBeGreaterThan(0);
-
-    // Assert: tasks.json exists in the session dir and contains task data
-    if (sessionDir) {
-      const tasksPath = join(sessionDir, "tasks.json");
-      expect(existsSync(tasksPath)).toBe(true);
-
-      const tasks = JSON.parse(readFileSync(tasksPath, "utf-8"));
-      expect(Array.isArray(tasks)).toBe(true);
-      expect(tasks.length).toBe(2);
+    const executionPromise = Promise.resolve(
+      ralphCommand!.execute("Build auth feature", context),
+    );
+    await withTimeout(workerStarted.promise, 1_000, "worker node did not start in time");
+
+    // While worker is still in-flight, the workflow should already have updated
+    // TUI state and session/task bindings.
+    expect(streamingTransitions[0]).toBe(true);
+    expect(workflowStateUpdates.some((update) => update.workflowActive === true)).toBe(true);
+    expect(trackedSessionDirs.length).toBeGreaterThan(0);
+    expect(trackedSessionIds.length).toBeGreaterThan(0);
+    expect(trackedTaskIdSizes.some((size) => size >= 2)).toBe(true);
+
+    let resolvedEarly = false;
+    void executionPromise.then(() => {
+      resolvedEarly = true;
+    });
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    expect(resolvedEarly).toBe(false);
 
-      // Assert: tasks.json has all tasks with status "completed"
-      expect(tasks.every((task: any) => task.status === "completed")).toBe(true);
-    }
+    releaseWorker.resolve(undefined);
 
-    // Assert: result.stateUpdate.workflowActive is false
+    const result = await withTimeout(
+      executionPromise,
+      3_000,
+      "ralph workflow did not finish after releasing worker",
+    );
+    expect(result.success).toBe(true);
     expect(result.stateUpdate?.workflowActive).toBe(false);
+    expect(streamingTransitions[streamingTransitions.length - 1]).toBe(false);
 
-    // Clean up temp dir
     if (sessionDir && existsSync(sessionDir)) {
       await rm(sessionDir, { recursive: true, force: true });
     }
diff --git a/src/ui/components/footer-status.tsx b/src/ui/components/footer-status.tsx
index f99b52eb6d..5f7558af8f 100644
--- a/src/ui/components/footer-status.tsx
+++ b/src/ui/components/footer-status.tsx
@@ -2,159 +2,58 @@
  * FooterStatus Component
  *
  * Displays a status bar at the bottom of the chat UI showing:
- * - Verbose mode toggle state
- * - Streaming status
- * - Queued message count
- * - Current model
- * - Permission mode
+ * - Streaming hints (esc to interrupt, enqueue keybind) when streaming
+ * - Workflow hints (ctrl+c twice to exit) when workflow is active
+ * - Background agent status (ctrl+f to kill) when background agents exist
  *
  * Reference: Task #4 - Create FooterStatus component
  */
 
 import React from "react";
 import { useTheme } from "../theme.tsx";
-import type { FooterState } from "../types.ts";
 import { SPACING } from "../constants/spacing.ts";
+import { MISC } from "../constants/icons.ts";
+import type { ParallelAgent } from "./parallel-agents-tree.tsx";
+import { formatBackgroundAgentFooterStatus } from "../utils/background-agent-footer.ts";
+import { BACKGROUND_FOOTER_CONTRACT } from "../utils/background-agent-contracts.ts";
 
 // ============================================================================
 // TYPES
 // ============================================================================
 
-/**
- * Internal props for the FooterStatus component.
- * Accepts either a state object or individual props.
- */
 export interface FooterStatusComponentProps {
-  /** Footer state object (alternative to individual props) */
-  state?: FooterState;
-  /** Whether verbose mode is enabled */
-  verboseMode?: boolean;
   /** Whether streaming is active */
   isStreaming?: boolean;
-  /** Number of queued messages */
-  queuedCount?: number;
-  /** Current model ID */
-  modelId?: string;
-  /** Permission mode */
-  permissionMode?: "auto" | "prompt" | "deny" | "bypass";
-  /** Agent type */
-  agentType?: string;
-}
-
-// ============================================================================
-// UTILITY FUNCTIONS
-// ============================================================================
-
-/**
- * Format verbose mode for display.
- */
-function formatVerboseMode(isVerbose: boolean): string {
-  return isVerbose ? "verbose" : "compact";
-}
-
-/**
- * Format queued count for display.
- */
-function formatQueuedCount(count: number): string {
-  if (count === 0) return "";
-  return ` · ${count} queued`;
-}
-
-/**
- * Format permission mode for display.
- */
-function formatPermissionMode(
-  mode: "auto" | "prompt" | "deny" | "bypass" | undefined,
-): string {
-  if (!mode || mode === "bypass") return "";
-  return ` · ${mode}`;
+  /** Whether a workflow is currently active */
+  workflowActive?: boolean;
+  /** Enqueue shortcut label (e.g. "ctrl+shift+enter") */
+  enqueueShortcutLabel?: string;
+  /** Active background agents */
+  backgroundAgents?: readonly ParallelAgent[];
 }
 
 // ============================================================================
 // FOOTER STATUS COMPONENT
 // ============================================================================
 
-/**
- * Status bar component for the chat UI footer.
- *
- * Displays real-time status information including:
- * - Model ID
- * - Streaming indicator
- * - Verbose mode toggle state
- * - Queued message count
- * - Permission mode
- *
- * @example
- * ```tsx
- * <FooterStatus
- *   state={{
- *     verboseMode: false,
- *     isStreaming: true,
- *     queuedCount: 2,
- *     modelId: "claude-sonnet-4",
- *   }}
- * />
- * ```
- */
 export function FooterStatus({
-  state,
-  verboseMode = false,
   isStreaming = false,
-  queuedCount = 0,
-  modelId = "",
-  permissionMode,
-  agentType,
+  workflowActive = false,
+  enqueueShortcutLabel = "ctrl+shift+enter",
+  backgroundAgents = [],
 }: FooterStatusComponentProps): React.ReactNode {
   const { theme } = useTheme();
   const colors = theme.colors;
 
-  // Use state object if provided, otherwise use individual props
-  const actualVerboseMode = state?.verboseMode ?? verboseMode;
-  const actualIsStreaming = state?.isStreaming ?? isStreaming;
-  const actualQueuedCount = state?.queuedCount ?? queuedCount;
-  const actualModelId = state?.modelId ?? modelId;
-  const actualPermissionMode = state?.permissionMode ?? permissionMode;
-  const actualAgentType = state?.agentType ?? agentType;
-
-  // Build status parts
-  const parts: string[] = [];
-
-  // Model ID (always shown)
-  if (actualModelId) {
-    parts.push(actualModelId);
-  }
-
-  // Streaming indicator
-  if (actualIsStreaming) {
-    parts.push("streaming");
-  }
-
-  // Verbose mode indicator with toggle hint
-  parts.push(formatVerboseMode(actualVerboseMode));
-
-  // Queue count
-  const queueText = formatQueuedCount(actualQueuedCount);
-  if (queueText) {
-    parts.push(`${actualQueuedCount} queued`);
-  }
+  const showStreamingHints = isStreaming && !workflowActive;
+  const showWorkflowHints = workflowActive;
+  const hasBackgroundAgents = backgroundAgents.length > 0;
 
-  // Permission mode
-  const permText = formatPermissionMode(actualPermissionMode);
-  if (permText) {
-    parts.push(actualPermissionMode!);
+  // Nothing to show when idle with no background agents
+  if (!showStreamingHints && !showWorkflowHints && !hasBackgroundAgents) {
+    return null;
   }
 
-  // Agent type
-  if (actualAgentType) {
-    parts.push(actualAgentType);
-  }
-
-  // Join with separator
-  const statusText = parts.join(" · ");
-
-  // Add Ctrl+O hint for verbose mode
-  const verboseHint = actualVerboseMode ? " (ctrl+o to collapse)" : " (ctrl+o to expand)";
-
   return (
     <box
       flexDirection="row"
@@ -162,12 +61,41 @@ export function FooterStatus({
       paddingRight={SPACING.CONTAINER_PAD}
       paddingTop={SPACING.NONE}
       paddingBottom={SPACING.NONE}
+      gap={SPACING.ELEMENT}
       flexShrink={0}
     >
-      <text style={{ fg: colors.muted }}>
-        {statusText}
-        <span style={{ fg: colors.dim }}>{verboseHint}</span>
-      </text>
+      {showWorkflowHints && (
+        <>
+          <text style={{ fg: colors.accent }}>workflow</text>
+          <text style={{ fg: colors.muted }}>{MISC.separator}</text>
+        </>
+      )}
+      {(showStreamingHints || showWorkflowHints) && (
+        <>
+          <text style={{ fg: colors.muted }}>esc to interrupt</text>
+          <text style={{ fg: colors.muted }}>{MISC.separator}</text>
+          <text style={{ fg: colors.muted }}>{enqueueShortcutLabel} enqueue</text>
+        </>
+      )}
+      {showWorkflowHints && (
+        <>
+          <text style={{ fg: colors.muted }}>{MISC.separator}</text>
+          <text style={{ fg: colors.muted }}>ctrl+c twice to exit workflow</text>
+        </>
+      )}
+      {hasBackgroundAgents && (
+        <>
+          {(showStreamingHints || showWorkflowHints) && (
+            <text style={{ fg: colors.muted }}>{MISC.separator}</text>
+          )}
+          <text style={{ fg: colors.accent }}>
+            {formatBackgroundAgentFooterStatus(backgroundAgents)}
+          </text>
+          <text style={{ fg: colors.dim }}>
+            {MISC.separator} {BACKGROUND_FOOTER_CONTRACT.terminateHintText}
+          </text>
+        </>
+      )}
     </box>
   );
 }
diff --git a/src/ui/components/parallel-agents-tree.test.ts b/src/ui/components/parallel-agents-tree.test.ts
index 3597c11097..d9803a093d 100644
--- a/src/ui/components/parallel-agents-tree.test.ts
+++ b/src/ui/components/parallel-agents-tree.test.ts
@@ -1,9 +1,20 @@
 import { describe, expect, test } from "bun:test";
 import {
   buildAgentHeaderLabel,
+  buildAgentInlinePrefix,
+  deduplicateAgents,
+  getForegroundHeaderText,
+  getAgentInlineDisplayParts,
   getAgentTaskLabel,
+  getBackgroundSubStatusText,
   getStatusIndicatorColor,
+  shouldAnimateAgentStatus,
 } from "./parallel-agents-tree.tsx";
+import type { Part } from "../parts/types.ts";
+import type { ParallelAgent } from "./parallel-agents-tree.tsx";
+import { PART_REGISTRY } from "./parts/registry.tsx";
+import { buildParallelAgentsHeaderHint } from "../utils/background-agent-tree-hints.ts";
+import { BACKGROUND_TREE_HINT_CONTRACT } from "../utils/background-agent-contracts.ts";
 
 describe("ParallelAgentsTree status indicator colors", () => {
   const colors = {
@@ -13,20 +24,32 @@ describe("ParallelAgentsTree status indicator colors", () => {
     error: "#ff0000",
   };
 
-  test("renders running and pending as muted static indicators", () => {
+  test("renders running and background as muted static indicators", () => {
     expect(getStatusIndicatorColor("running", colors)).toBe(colors.muted);
-    expect(getStatusIndicatorColor("pending", colors)).toBe(colors.muted);
     expect(getStatusIndicatorColor("background", colors)).toBe(colors.muted);
   });
 
-  test("renders completed as success and interrupted as warning", () => {
+  test("renders completed as success", () => {
     expect(getStatusIndicatorColor("completed", colors)).toBe(colors.success);
+  });
+
+  test("renders pending and interrupted as warning", () => {
+    expect(getStatusIndicatorColor("pending", colors)).toBe(colors.warning);
     expect(getStatusIndicatorColor("interrupted", colors)).toBe(colors.warning);
   });
 
   test("renders error as error color", () => {
     expect(getStatusIndicatorColor("error", colors)).toBe(colors.error);
   });
+
+  test("animates running-style statuses", () => {
+    expect(shouldAnimateAgentStatus("running")).toBe(true);
+    expect(shouldAnimateAgentStatus("background")).toBe(true);
+    expect(shouldAnimateAgentStatus("pending")).toBe(false);
+    expect(shouldAnimateAgentStatus("completed")).toBe(false);
+    expect(shouldAnimateAgentStatus("error")).toBe(false);
+    expect(shouldAnimateAgentStatus("interrupted")).toBe(false);
+  });
 });
 
 describe("ParallelAgentsTree labeling", () => {
@@ -52,4 +75,328 @@ describe("ParallelAgentsTree labeling", () => {
       })
     ).toBe("Research Rust TUI stacks");
   });
+
+  test("uses running-style header text for pending-only foreground trees", () => {
+    expect(
+      getForegroundHeaderText([
+        { status: "pending" },
+        { status: "pending" },
+      ])
+    ).toBe("Running 2 agents…");
+  });
+});
+
+describe("deduplicateAgents", () => {
+  function makeAgent(overrides: Partial<ParallelAgent> & { id: string }): ParallelAgent {
+    return {
+      name: "reviewer",
+      task: "Sub-agent task",
+      status: "running",
+      startedAt: "2026-01-01T00:00:00.000Z",
+      ...overrides,
+    };
+  }
+
+  test("returns same array when no duplicates exist", () => {
+    const agents: ParallelAgent[] = [
+      makeAgent({ id: "a1", taskToolCallId: "t1", task: "Review code" }),
+      makeAgent({ id: "a2", taskToolCallId: "t2", task: "Find bugs" }),
+    ];
+    expect(deduplicateAgents(agents)).toBe(agents);
+  });
+
+  test("merges two agents sharing the same taskToolCallId", () => {
+    const agents: ParallelAgent[] = [
+      makeAgent({ id: "tool_1", taskToolCallId: "tool_1", task: "", toolUses: 7, currentTool: "read" }),
+      makeAgent({ id: "sub_1", taskToolCallId: "tool_1", task: "Review snake TUI", status: "completed" }),
+    ];
+    const result = deduplicateAgents(agents);
+    expect(result.length).toBe(1);
+    expect(result[0]!.task).toBe("Review snake TUI");
+    expect(result[0]!.toolUses).toBe(7);
+    expect(result[0]!.status).toBe("completed");
+    expect(result[0]!.id).toBe("sub_1");
+  });
+
+  test("prefers non-tool_ id format", () => {
+    const agents: ParallelAgent[] = [
+      makeAgent({ id: "tool_123", taskToolCallId: "tool_123", task: "" }),
+      makeAgent({ id: "ses_abc", taskToolCallId: "tool_123", task: "Real task" }),
+    ];
+    const result = deduplicateAgents(agents);
+    expect(result[0]!.id).toBe("ses_abc");
+  });
+
+  test("preserves agents without taskToolCallId", () => {
+    const agents: ParallelAgent[] = [
+      makeAgent({ id: "a1", task: "Orphan task" }),
+      makeAgent({ id: "a2", taskToolCallId: "t1", task: "Grouped task" }),
+    ];
+    const result = deduplicateAgents(agents);
+    expect(result.length).toBe(2);
+  });
+
+  test("returns same array when only one agent", () => {
+    const agents = [makeAgent({ id: "a1", taskToolCallId: "t1" })];
+    expect(deduplicateAgents(agents)).toBe(agents);
+  });
+
+  test("takes result and error from either entry", () => {
+    const agents: ParallelAgent[] = [
+      makeAgent({ id: "tool_1", taskToolCallId: "tool_1", result: "All good" }),
+      makeAgent({ id: "sub_1", taskToolCallId: "tool_1", error: "Oops", status: "error" }),
+    ];
+    const result = deduplicateAgents(agents);
+    expect(result[0]!.result).toBe("All good");
+    expect(result[0]!.error).toBe("Oops");
+  });
+
+  test("merges uncorrelated generic+descriptive duplicates for same agent", () => {
+    const agents: ParallelAgent[] = [
+      makeAgent({
+        id: "agent-generic",
+        name: "debugger",
+        task: "Sub-agent task",
+        toolUses: 12,
+      }),
+      makeAgent({
+        id: "agent-real",
+        name: "debugger",
+        task: "Debug stuck spinner",
+        toolUses: 12,
+      }),
+    ];
+
+    const result = deduplicateAgents(agents);
+    expect(result).toHaveLength(1);
+    expect(result[0]!.task).toBe("Debug stuck spinner");
+    expect(result[0]!.toolUses).toBe(12);
+  });
+
+  test("does not merge uncorrelated descriptive tasks for same agent name", () => {
+    const agents: ParallelAgent[] = [
+      makeAgent({ id: "agent-1", name: "debugger", task: "Debug stuck spinner" }),
+      makeAgent({ id: "agent-2", name: "debugger", task: "Investigate login timeout" }),
+    ];
+
+    const result = deduplicateAgents(agents);
+    expect(result).toHaveLength(2);
+  });
+
+  test("merges mixed-correlation eager placeholder with descriptive SDK row", () => {
+    const agents: ParallelAgent[] = [
+      makeAgent({
+        id: "tool_42",
+        taskToolCallId: "tool_42",
+        name: "debugger",
+        task: "Sub-agent task",
+        toolUses: 12,
+        currentTool: "glob",
+      }),
+      makeAgent({
+        id: "subagent-42",
+        name: "debugger",
+        task: "Debug stuck spinner",
+        toolUses: 12,
+        currentTool: "glob",
+      }),
+    ];
+
+    const result = deduplicateAgents(agents);
+    expect(result).toHaveLength(1);
+    expect(result[0]!.id).toBe("subagent-42");
+    expect(result[0]!.task).toBe("Debug stuck spinner");
+    expect(result[0]!.toolUses).toBe(12);
+  });
+
+  test("does not merge mixed-correlation rows without eager placeholder shape", () => {
+    const agents: ParallelAgent[] = [
+      makeAgent({
+        id: "agent-tracked",
+        taskToolCallId: "external-call-1",
+        name: "debugger",
+        task: "Sub-agent task",
+        toolUses: 12,
+      }),
+      makeAgent({
+        id: "agent-untracked",
+        name: "debugger",
+        task: "Debug stuck spinner",
+        toolUses: 12,
+      }),
+    ];
+
+    const result = deduplicateAgents(agents);
+    expect(result).toHaveLength(2);
+  });
+});
+
+describe("getBackgroundSubStatusText", () => {
+  test("always returns background status text while active", () => {
+    const running: ParallelAgent = {
+      id: "bg-1",
+      name: "codebase-locator",
+      task: "Locate APIs",
+      status: "background",
+      background: true,
+      startedAt: "2026-01-01T00:00:00.000Z",
+      currentTool: "rg",
+      toolUses: 12,
+    };
+    expect(getBackgroundSubStatusText(running)).toBe("Running codebase-locator in background…");
+  });
+
+  test("returns terminal status text for completed, error, interrupted", () => {
+    const completed: ParallelAgent = {
+      id: "bg-2",
+      name: "debugger",
+      task: "Investigate",
+      status: "completed",
+      background: true,
+      startedAt: "2026-01-01T00:00:00.000Z",
+    };
+    const errored: ParallelAgent = {
+      ...completed,
+      id: "bg-3",
+      status: "error",
+      error: "Failed",
+    };
+    const interrupted: ParallelAgent = {
+      ...completed,
+      id: "bg-4",
+      status: "interrupted",
+    };
+
+    expect(getBackgroundSubStatusText(completed)).toBe("Done");
+    expect(getBackgroundSubStatusText(errored)).toBe("Failed");
+    expect(getBackgroundSubStatusText(interrupted)).toBe("Interrupted");
+  });
+});
+
+describe("buildParallelAgentsHeaderHint integration with ParallelAgent", () => {
+  function makeAgent(overrides: Partial<ParallelAgent> & { id: string }): ParallelAgent {
+    return {
+      name: "reviewer",
+      task: "Sub-agent task",
+      status: "running",
+      startedAt: "2026-01-01T00:00:00.000Z",
+      ...overrides,
+    };
+  }
+
+  test("returns running hint for active background agents", () => {
+    const agents: ParallelAgent[] = [
+      makeAgent({ id: "bg-1", background: true, status: "running" }),
+    ];
+    expect(buildParallelAgentsHeaderHint(agents, false)).toBe(
+      BACKGROUND_TREE_HINT_CONTRACT.whenRunning,
+    );
+  });
+
+  test("returns completion hint for completed background agents with showExpandHint", () => {
+    const agents: ParallelAgent[] = [
+      makeAgent({ id: "bg-1", background: true, status: "completed" }),
+    ];
+    expect(buildParallelAgentsHeaderHint(agents, true)).toBe(
+      BACKGROUND_TREE_HINT_CONTRACT.whenComplete,
+    );
+  });
+
+  test("returns default hint for foreground-only agents with showExpandHint", () => {
+    const agents: ParallelAgent[] = [
+      makeAgent({ id: "fg-1", status: "completed" }),
+    ];
+    expect(buildParallelAgentsHeaderHint(agents, true)).toBe(
+      BACKGROUND_TREE_HINT_CONTRACT.defaultHint,
+    );
+  });
+
+  test("returns empty string when no hint should show", () => {
+    const agents: ParallelAgent[] = [
+      makeAgent({ id: "fg-1", status: "completed" }),
+    ];
+    expect(buildParallelAgentsHeaderHint(agents, false)).toBe("");
+  });
+});
+
+describe("agent inline display helpers", () => {
+  const expectedInlinePartTypes: Array<Part["type"]> = [
+    "agent",
+    "compaction",
+    "mcp-snapshot",
+    "reasoning",
+    "skill-load",
+    "task-list",
+    "task-result",
+    "text",
+    "tool",
+    "workflow-step",
+  ];
+
+  const inlineParts: Part[] = [
+    {
+      id: "part-1",
+      type: "text",
+      createdAt: "2026-01-01T00:00:00.000Z",
+      content: "first",
+      isStreaming: false,
+    },
+    {
+      id: "part-2",
+      type: "reasoning",
+      createdAt: "2026-01-01T00:00:01.000Z",
+      content: "second",
+      durationMs: 0,
+      isStreaming: false,
+    },
+  ];
+
+  test("uses registry renderers for all supported inline part types", () => {
+    expect(Object.keys(PART_REGISTRY).sort()).toEqual(expectedInlinePartTypes);
+  });
+
+  test("suppresses tool and text parts from inline display", () => {
+    const mixedParts: Part[] = [
+      {
+        id: "part-text",
+        type: "text",
+        createdAt: "2026-01-01T00:00:00.000Z",
+        content: "hello",
+        isStreaming: false,
+      },
+      {
+        id: "part-tool",
+        type: "tool",
+        createdAt: "2026-01-01T00:00:01.000Z",
+        toolCallId: "tc-1",
+        toolName: "bash",
+        input: {},
+        state: { status: "pending" },
+      },
+      {
+        id: "part-reasoning",
+        type: "reasoning",
+        createdAt: "2026-01-01T00:00:02.000Z",
+        content: "thinking",
+        durationMs: 100,
+        isStreaming: false,
+      },
+    ] as Part[];
+    const result = getAgentInlineDisplayParts(mixedParts);
+    expect(result).toHaveLength(1);
+    expect(result[0]!.id).toBe("part-reasoning");
+  });
+
+  test("filters out text and tool parts in inline display", () => {
+    const result = getAgentInlineDisplayParts(inlineParts);
+    // part-1 is "text" (suppressed), part-2 is "reasoning" (kept)
+    expect(result).toHaveLength(1);
+    expect(result.map((part) => part.id)).toEqual(["part-2"]);
+    expect(result.every((part) => Boolean(PART_REGISTRY[part.type]))).toBe(true);
+  });
+
+  test("builds tree connector prefix for inline part rows", () => {
+    expect(buildAgentInlinePrefix("│ ")).toBe("│    ╰  ");
+    expect(buildAgentInlinePrefix("  ")).toBe("     ╰  ");
+  });
 });
diff --git a/src/ui/components/parallel-agents-tree.tsx b/src/ui/components/parallel-agents-tree.tsx
index 4720ef8ff1..a7ed5e273e 100644
--- a/src/ui/components/parallel-agents-tree.tsx
+++ b/src/ui/components/parallel-agents-tree.tsx
@@ -7,12 +7,17 @@
  * Reference: Issue #4 - Add UI for visualizing parallel agents
  */
 
-import React from "react";
+import React, { useEffect, useState } from "react";
+import type { SyntaxStyle } from "@opentui/core";
 import { useTheme, getCatppuccinPalette } from "../theme.tsx";
 import { formatDuration as formatDurationObj, truncateText } from "../utils/format.ts";
-import { buildParallelAgentsHeaderHint } from "../utils/background-agent-tree-hints.ts";
-import { STATUS, TREE, CONNECTOR } from "../constants/icons.ts";
+import { STATUS, TREE, CONNECTOR, MISC, ARROW } from "../constants/icons.ts";
 import { SPACING } from "../constants/spacing.ts";
+import { buildParallelAgentsHeaderHint } from "../utils/background-agent-tree-hints.ts";
+import type { Part, ToolPart } from "../parts/types.ts";
+import { PART_REGISTRY } from "./parts/registry.tsx";
+import { AnimatedBlinkIndicator } from "./animated-blink-indicator.tsx";
+import { buildPartRenderKeys, getConsumedTaskToolCallIds } from "./parts/message-bubble-parts.tsx";
 
 // Re-export for backward compatibility
 export { truncateText };
@@ -56,8 +61,12 @@ export interface ParallelAgent {
   toolUses?: number;
   /** Token count (for progress display) */
   tokens?: number;
+  /** Thinking/reasoning duration in milliseconds */
+  thinkingMs?: number;
   /** Current tool operation (e.g., "Bash: Find files...") */
   currentTool?: string;
+  /** Inline parts for agent-scoped streaming content */
+  inlineParts?: import("../parts/types").Part[];
 }
 
 /**
@@ -66,12 +75,18 @@ export interface ParallelAgent {
 export interface ParallelAgentsTreeProps {
   /** List of parallel agents */
   agents: ParallelAgent[];
+  /** Optional syntax style for markdown/code part renderers */
+  syntaxStyle?: SyntaxStyle;
   /** Whether to show in compact mode (default: false) */
   compact?: boolean;
   /** Maximum agents to show before collapsing (default: 5) */
   maxVisible?: number;
   /** Remove top margin (useful when the tree is the first element in a container) */
   noTopMargin?: boolean;
+  /** Render in background-agent mode (green header, "launched", background sub-status) */
+  background?: boolean;
+  /** Whether to show the expand/collapse keyboard hint (default: false) */
+  showExpandHint?: boolean;
 }
 
 // ============================================================================
@@ -129,6 +144,23 @@ export const AGENT_COLORS: Record<string, string> = getAgentColors(true);
  */
 const SUB_STATUS_PAD = "   ";
 
+/**
+ * Part types that should never be rendered inside the sub-agent tree.
+ * Tool calls and text blocks are suppressed to keep the tree compact.
+ */
+const SUPPRESSED_INLINE_PART_TYPES: ReadonlySet<Part["type"]> = new Set(["tool", "text"]);
+
+export function getAgentInlineDisplayParts(
+  parts: ReadonlyArray<Part>,
+): Part[] {
+  if (parts.length === 0) return [];
+  return parts.filter((p) => !SUPPRESSED_INLINE_PART_TYPES.has(p.type));
+}
+
+export function buildAgentInlinePrefix(continuationPrefix: string): string {
+  return `${continuationPrefix}${SUB_STATUS_PAD}${CONNECTOR.subStatus}  `;
+}
+
 // ============================================================================
 // UTILITY FUNCTIONS
 // ============================================================================
@@ -152,18 +184,26 @@ export function getStatusIcon(status: AgentStatus): string {
 
 /**
  * Get the color used for the status indicator dot.
- * Running/pending/background remain muted to avoid implying completion.
+ *
+ * - completed: green (success)
+ * - error: red (error)
+ * - pending/interrupted: yellow (warning)
+ * - running/background: muted (spinner animation conveys activity)
  */
 export function getStatusIndicatorColor(
   status: AgentStatus,
   colors: Pick<ThemeColors, "muted" | "success" | "warning" | "error">,
 ): string {
   if (status === "completed") return colors.success;
-  if (status === "interrupted") return colors.warning;
   if (status === "error") return colors.error;
+  if (status === "pending" || status === "interrupted") return colors.warning;
   return colors.muted;
 }
 
+export function shouldAnimateAgentStatus(status: AgentStatus): boolean {
+  return status === "running" || status === "background";
+}
+
 /**
  * Format duration in a human-readable way.
  */
@@ -172,6 +212,39 @@ export function formatDuration(ms: number | undefined): string {
   return formatDurationObj(ms).text;
 }
 
+function formatTokenCount(tokens: number): string {
+  if (tokens >= 1_000_000) return `${(tokens / 1_000_000).toFixed(1)}M`;
+  if (tokens >= 1000) return `${(tokens / 1000).toFixed(1)}k`;
+  return `${tokens}`;
+}
+
+function formatThinkingDuration(ms: number): string {
+  const totalSeconds = Math.floor(ms / 1000);
+  if (totalSeconds <= 0) return "1s";
+  const minutes = Math.floor(totalSeconds / 60);
+  const seconds = totalSeconds % 60;
+  if (minutes === 0) return `${seconds}s`;
+  if (seconds === 0) return `${minutes}m`;
+  return `${minutes}m ${seconds}s`;
+}
+
+function buildAgentProgressInfo(agent: ParallelAgent, nowMs: number): string {
+  const isActive = agent.status === "running" || agent.status === "pending" || agent.status === "background";
+  if (!isActive) return "";
+
+  const parts: string[] = [];
+  const elapsed = getElapsedTime(agent.startedAt, nowMs);
+  if (elapsed) parts.push(elapsed);
+  if ((agent.tokens ?? 0) > 0) {
+    parts.push(`${ARROW.down} ${formatTokenCount(agent.tokens!)} tokens`);
+  }
+  if ((agent.thinkingMs ?? 0) >= 1000) {
+    parts.push(`thought for ${formatThinkingDuration(agent.thinkingMs!)}`);
+  }
+  if (parts.length === 0) return "";
+  return ` (${parts.join(` ${MISC.separator} `)})`;
+}
+
 export function isGenericSubagentTask(task: string): boolean {
   const normalized = task.trim().toLowerCase();
   return normalized === "" || normalized === "sub-agent task" || normalized === "subagent task";
@@ -181,6 +254,184 @@ export function getAgentTaskLabel(agent: Pick<ParallelAgent, "task" | "name">):
   return isGenericSubagentTask(agent.task) ? agent.name : agent.task;
 }
 
+/**
+ * Status priority for deduplication: higher value wins.
+ */
+const STATUS_PRIORITY: Record<AgentStatus, number> = {
+  pending: 0,
+  running: 1,
+  background: 2,
+  completed: 3,
+  interrupted: 4,
+  error: 5,
+};
+
+/**
+ * Deduplicate duplicate logical sub-agents.
+ *
+ * Primary path: merge entries that share a `taskToolCallId`.
+ * Fallback path: merge near-duplicates when one row still carries the
+ * generic placeholder task and another row has the real task text.
+ * This also handles mixed-correlation rows (e.g. eager Task row + SDK row)
+ * when they clearly represent the same logical sub-agent.
+ */
+export function deduplicateAgents(agents: ParallelAgent[]): ParallelAgent[] {
+  if (agents.length <= 1) return agents;
+
+  const byToolCallId = new Map<string, ParallelAgent[]>();
+  const ungrouped: ParallelAgent[] = [];
+
+  for (const agent of agents) {
+    if (agent.taskToolCallId) {
+      const group = byToolCallId.get(agent.taskToolCallId) ?? [];
+      group.push(agent);
+      byToolCallId.set(agent.taskToolCallId, group);
+    } else {
+      ungrouped.push(agent);
+    }
+  }
+
+  let anyMerged = false;
+  const merged: ParallelAgent[] = [];
+
+  for (const group of byToolCallId.values()) {
+    if (group.length === 1) {
+      merged.push(group[0]!);
+      continue;
+    }
+
+    anyMerged = true;
+    // Merge all entries in the group into one
+    let best = group[0]!;
+    for (let i = 1; i < group.length; i++) {
+      const other = group[i]!;
+      best = mergeAgentPair(best, other);
+    }
+    merged.push(best);
+  }
+
+  const fallbackDeduped = deduplicateUncorrelatedAgents([...merged, ...ungrouped]);
+
+  if (!anyMerged && !fallbackDeduped.merged) return agents;
+  return anyMerged && !fallbackDeduped.merged
+    ? [...merged, ...ungrouped]
+    : fallbackDeduped.agents;
+}
+
+function mergeAgentPair(a: ParallelAgent, b: ParallelAgent): ParallelAgent {
+  // Prefer the entry with a real task description
+  const aHasTask = !isGenericSubagentTask(a.task);
+  const bHasTask = !isGenericSubagentTask(b.task);
+  const primary = bHasTask && !aHasTask ? b : a;
+  const secondary = primary === a ? b : a;
+
+  // Take the higher-priority status
+  const statusA = STATUS_PRIORITY[a.status] ?? 0;
+  const statusB = STATUS_PRIORITY[b.status] ?? 0;
+  const statusWinner = statusB > statusA ? b : a;
+
+  return {
+    ...primary,
+    // Use the real subagentId if available (non-toolId format)
+    id: primary.id.startsWith("tool_") ? secondary.id : primary.id,
+    task: aHasTask ? a.task : bHasTask ? b.task : primary.task,
+    status: statusWinner.status,
+    background: a.background || b.background,
+    toolUses: Math.max(a.toolUses ?? 0, b.toolUses ?? 0) || undefined,
+    currentTool: a.currentTool ?? b.currentTool,
+    result: a.result ?? b.result,
+    error: a.error ?? b.error,
+    durationMs: a.durationMs ?? b.durationMs,
+    tokens: Math.max(a.tokens ?? 0, b.tokens ?? 0) || undefined,
+    thinkingMs: Math.max(a.thinkingMs ?? 0, b.thinkingMs ?? 0) || undefined,
+  };
+}
+
+function isLikelyEagerPlaceholder(agent: ParallelAgent): boolean {
+  if (!agent.taskToolCallId) return false;
+  return (
+    agent.id === agent.taskToolCallId
+    || agent.id.startsWith("tool_")
+    || agent.taskToolCallId.startsWith("tool_")
+  );
+}
+
+function canMergeByTaskCorrelation(a: ParallelAgent, b: ParallelAgent): boolean {
+  const aTaskId = a.taskToolCallId;
+  const bTaskId = b.taskToolCallId;
+
+  if (aTaskId && bTaskId) {
+    return aTaskId === bTaskId;
+  }
+
+  if (!aTaskId && !bTaskId) {
+    return true;
+  }
+
+  const withTaskId = aTaskId ? a : b;
+  return isLikelyEagerPlaceholder(withTaskId);
+}
+
+function canMergeUncorrelatedDuplicate(a: ParallelAgent, b: ParallelAgent): boolean {
+  if (!canMergeByTaskCorrelation(a, b)) return false;
+  if (a.name !== b.name) return false;
+
+  const aGenericTask = isGenericSubagentTask(a.task);
+  const bGenericTask = isGenericSubagentTask(b.task);
+  if (aGenericTask === bGenericTask) return false;
+
+  if (Boolean(a.background) !== Boolean(b.background)) return false;
+  if (a.result && b.result && a.result !== b.result) return false;
+  if (a.error && b.error && a.error !== b.error) return false;
+  if (a.toolUses !== undefined && b.toolUses !== undefined && a.toolUses !== b.toolUses) return false;
+
+  return true;
+}
+
+function deduplicateUncorrelatedAgents(agents: ParallelAgent[]): {
+  agents: ParallelAgent[];
+  merged: boolean;
+} {
+  if (agents.length <= 1) {
+    return { agents, merged: false };
+  }
+
+  const consumed = new Set<number>();
+  const mergedAgents: ParallelAgent[] = [];
+  let merged = false;
+
+  for (let i = 0; i < agents.length; i++) {
+    if (consumed.has(i)) continue;
+    const current = agents[i];
+    if (!current) continue;
+
+    let matchIndex = -1;
+    for (let j = i + 1; j < agents.length; j++) {
+      if (consumed.has(j)) continue;
+      const candidate = agents[j];
+      if (!candidate) continue;
+      if (canMergeUncorrelatedDuplicate(current, candidate)) {
+        matchIndex = j;
+        break;
+      }
+    }
+
+    if (matchIndex >= 0) {
+      const match = agents[matchIndex];
+      if (match) {
+        mergedAgents.push(mergeAgentPair(current, match));
+        consumed.add(matchIndex);
+        merged = true;
+        continue;
+      }
+    }
+
+    mergedAgents.push(current);
+  }
+
+  return { agents: merged ? mergedAgents : agents, merged };
+}
+
 export function buildAgentHeaderLabel(count: number, dominantType: string): string {
   const normalized = dominantType.trim();
   const lower = normalized.toLowerCase();
@@ -197,13 +448,35 @@ export function buildAgentHeaderLabel(count: number, dominantType: string): stri
   return `${count} ${normalized} agent${plural ? "s" : ""}`;
 }
 
+export function getForegroundActiveAgentCount(
+  agents: ReadonlyArray<Pick<ParallelAgent, "status">>,
+): number {
+  return agents.filter(
+    (agent) => agent.status === "running" || agent.status === "pending" || agent.status === "background",
+  ).length;
+}
+
+export function getForegroundHeaderText(
+  agents: ReadonlyArray<Pick<ParallelAgent, "status">>,
+): string {
+  const activeCount = getForegroundActiveAgentCount(agents);
+  if (activeCount > 0) {
+    return `Running ${activeCount} agent${activeCount !== 1 ? "s" : ""}…`;
+  }
+  const completedCount = agents.filter((agent) => agent.status === "completed").length;
+  if (completedCount > 0) {
+    return `${completedCount} agent${completedCount !== 1 ? "s" : ""} finished`;
+  }
+  const pendingCount = agents.filter((agent) => agent.status === "pending").length;
+  return `${pendingCount} agent${pendingCount !== 1 ? "s" : ""} pending`;
+}
+
 /**
  * Get elapsed time since start.
  */
-export function getElapsedTime(startedAt: string): string {
+export function getElapsedTime(startedAt: string, nowMs: number = Date.now()): string {
   const start = new Date(startedAt).getTime();
-  const now = Date.now();
-  return formatDuration(now - start);
+  return formatDuration(nowMs - start);
 }
 
 /**
@@ -215,9 +488,11 @@ export function getSubStatusText(agent: ParallelAgent): string | null {
     return agent.currentTool;
   }
   switch (agent.status) {
+    case "background":
+      return "Running in the background (↓ to manage)";
     case "running":
     case "pending":
-      return "Initializing...";
+      return "Initializing…";
     case "completed":
       return "Done";
     case "error":
@@ -229,6 +504,13 @@ export function getSubStatusText(agent: ParallelAgent): string | null {
   }
 }
 
+export function getBackgroundSubStatusText(agent: ParallelAgent): string {
+  if (agent.status === "completed") return "Done";
+  if (agent.status === "error") return agent.error ?? "Error";
+  if (agent.status === "interrupted") return "Interrupted";
+  return `Running ${agent.name} in background…`;
+}
+
 // ============================================================================
 // CLAUDE CODE COLOR CONSTANTS (ANSI 256 compatible)
 // ============================================================================
@@ -259,200 +541,206 @@ interface AgentRowProps {
   agent: ParallelAgent;
   isLast: boolean;
   compact: boolean;
+  syntaxStyle?: SyntaxStyle;
   themeColors: ThemeColors;
+  nowMs: number;
 }
 
 /**
- * Format token count with k suffix.
+ * Props for AgentRow component.
  */
-function formatTokens(tokens: number | undefined): string {
-  if (tokens === undefined) return "";
-  if (tokens >= 1000) {
-    return `${(tokens / 1000).toFixed(1)}k tokens`;
-  }
-  return `${tokens} tokens`;
+interface BackgroundAgentRowProps {
+  agent: ParallelAgent;
+  isLast: boolean;
+  themeColors: ThemeColors;
+  nowMs: number;
 }
 
 /**
- * Single agent row in the tree view.
- * Follows Claude Code's parallel agent display style.
+ * Agent row for background-mode tree.
+ * Shows task name with ● indicator and "Running in the background" sub-status.
  */
-function AgentRow({ agent, isLast, compact, themeColors }: AgentRowProps): React.ReactNode {
+function BackgroundAgentRow({ agent, isLast, themeColors, nowMs }: BackgroundAgentRowProps): React.ReactNode {
   const treeChar = isLast ? TREE.lastBranch : TREE.branch;
+  const continuationPrefix = isLast ? TREE.space : TREE.vertical;
+  const subStatus = getBackgroundSubStatusText(agent);
+  const progressInfo = buildAgentProgressInfo(agent, nowMs);
+  const animateRowIndicator = shouldAnimateAgentStatus(agent.status);
 
-  // Build metrics text (tool uses and tokens) - Claude Code style
-  const metricsText = [
-    agent.toolUses !== undefined ? `${agent.toolUses} tool uses` : "",
-    agent.tokens !== undefined ? formatTokens(agent.tokens) : "",
-  ].filter(Boolean).join(" · ");
-
-  // Compute sub-status text (currentTool or default based on status)
-  const subStatus = getSubStatusText(agent);
-
-  if (compact) {
-    // Compact mode: Claude Code style - task · metrics
-    const isRunning = agent.status === "running" || agent.status === "pending";
-    const hasTask = agent.task.trim().length > 0;
-    // For running agents, append elapsed time to sub-status
-    const elapsedSuffix = isRunning ? ` (${getElapsedTime(agent.startedAt)})` : "";
-    const displaySubStatus = subStatus ? `${subStatus}${elapsedSuffix}` : null;
-
-    // Status indicator for the tree row
-    const rowIndicatorColor = getStatusIndicatorColor(agent.status, themeColors);
-
-    // Continuation line prefix for sub-status and hints
-    const continuationPrefix = isLast ? TREE.space : TREE.vertical;
-
-    if (!hasTask && displaySubStatus) {
-      // Empty task: show agent name + sub-status inline on the tree line
-      return (
-        <box flexDirection="column">
-          <box flexDirection="row">
-            <box flexShrink={0}><text style={{ fg: themeColors.muted }}>{treeChar} </text></box>
-            <box flexShrink={0}>
-              <text style={{ fg: rowIndicatorColor }}>●</text>
-            </box>
-            <text style={{ fg: themeColors.foreground }}> {agent.name} </text>
-            <text style={{ fg: themeColors.muted }}>
-              {truncateText(displaySubStatus, 50)}
-            </text>
-          </box>
-          {isRunning && agent.toolUses !== undefined && agent.toolUses > 0 && (
-            <box flexDirection="row">
-              <text style={{ fg: themeColors.muted }}>
-                {continuationPrefix}{SUB_STATUS_PAD}+{agent.toolUses} more tool use{agent.toolUses !== 1 ? "s" : ""}
-              </text>
-            </box>
-          )}
-        </box>
-      );
-    }
-
-    const displayTask = truncateText(getAgentTaskLabel(agent), 40);
-
-    return (
-      <box flexDirection="column">
-        <box flexDirection="row">
-          <box flexShrink={0}><text style={{ fg: themeColors.muted }}>{treeChar} </text></box>
-          <box flexShrink={0}>
-            <text style={{ fg: rowIndicatorColor }}>●</text>
-          </box>
-          <text style={{ fg: themeColors.foreground }}>
-            {" "}{displayTask}
-          </text>
-          {metricsText && (
-            <text style={{ fg: themeColors.muted }}> · {metricsText}</text>
+  return (
+    <box flexDirection="column">
+      <box flexDirection="row">
+        <box flexShrink={0}><text style={{ fg: themeColors.muted }}>{treeChar}</text></box>
+        <box flexShrink={0}>
+          {animateRowIndicator ? (
+            <text><AnimatedBlinkIndicator color={themeColors.success} speed={500} /></text>
+          ) : (
+            <text style={{ fg: themeColors.success }}>●</text>
           )}
         </box>
-        {/* Sub-status: current tool or default status text */}
-        {displaySubStatus && (
-          <box flexDirection="row">
-            <text style={{ fg: themeColors.muted }}>
-              {continuationPrefix}{SUB_STATUS_PAD}{CONNECTOR.subStatus}  {truncateText(displaySubStatus, 50)}
-            </text>
-          </box>
-        )}
-        {/* Collapsed tool uses hint */}
-        {isRunning && agent.toolUses !== undefined && agent.toolUses > 0 && (
-          <box flexDirection="row">
-            <text style={{ fg: themeColors.muted }}>
-              {continuationPrefix}{SUB_STATUS_PAD}+{agent.toolUses} more tool use{agent.toolUses !== 1 ? "s" : ""}
-            </text>
-          </box>
-        )}
+        <text style={{ fg: themeColors.foreground, attributes: 1 }}>
+          {" "}{getAgentTaskLabel(agent)}
+        </text>
       </box>
-    );
-  }
-
-  // Full mode: includes more details
-  const isRunningFull = agent.status === "running" || agent.status === "pending";
-  const isCompletedFull = agent.status === "completed";
-  const isErrorFull = agent.status === "error";
-  const isInterruptedFull = agent.status === "interrupted";
-  const hasTaskFull = agent.task.trim().length > 0;
-  const elapsedSuffixFull = isRunningFull ? ` (${getElapsedTime(agent.startedAt)})` : "";
-  const displaySubStatusFull = subStatus ? `${subStatus}${elapsedSuffixFull}` : null;
-
-  // Status indicator color for the tree row
-  const fullRowIndicatorColor = getStatusIndicatorColor(agent.status, themeColors);
-
-  // Continuation line prefix for sub-status lines
-  const fullContinuationPrefix = isLast ? TREE.space : TREE.vertical;
-
-  // If task is empty, show agent name + sub-status inline on the tree line
-  if (!hasTaskFull && displaySubStatusFull) {
-    return (
-      <box flexDirection="column">
+      {subStatus && (
         <box flexDirection="row">
-          <box flexShrink={0}><text style={{ fg: themeColors.muted }}>{treeChar} </text></box>
-          <box flexShrink={0}>
-            <text style={{ fg: fullRowIndicatorColor }}>●</text>
-          </box>
-          <text style={{ fg: themeColors.foreground }}> {agent.name} </text>
           <text style={{ fg: themeColors.muted }}>
-            {displaySubStatusFull}
+            {continuationPrefix}{SUB_STATUS_PAD}{CONNECTOR.subStatus}  {subStatus}{progressInfo}
           </text>
         </box>
-      </box>
-    );
+      )}
+    </box>
+  );
+}
+
+/**
+ * Single agent row in the tree view.
+ *
+ * Layout:
+ *   ├─● {task}
+ *   │    ╰  {agent-name}: ({N} tool uses)   — during execution
+ *   │      · {currentTool}                   — active tool on separate line
+ *
+ *   ├─● {task}
+ *   │    ╰  Initializing {agent-name}… (Ns)  — during initialization
+ */
+function AgentRow({ agent, isLast, compact, syntaxStyle, themeColors, nowMs }: AgentRowProps): React.ReactNode {
+  const treeChar = isLast ? TREE.lastBranch : TREE.branch;
+  const continuationPrefix = isLast ? TREE.space : TREE.vertical;
+  const isRunning = agent.status === "running" || agent.status === "pending";
+
+  const rowIndicatorColor = getStatusIndicatorColor(agent.status, themeColors);
+  const animateRowIndicator = shouldAnimateAgentStatus(agent.status);
+  const displayTask = truncateText(getAgentTaskLabel(agent), compact ? 40 : 50);
+  const progressInfo = buildAgentProgressInfo(agent, nowMs);
+
+  // Build sub-status text based on agent state
+  let subStatusText: string | null = null;
+  if (isRunning) {
+    if (agent.toolUses !== undefined && agent.toolUses > 0) {
+      subStatusText = `${agent.name}: (${agent.toolUses} tool use${agent.toolUses !== 1 ? "s" : ""})${progressInfo}`;
+    } else {
+      subStatusText = `Initializing ${agent.name}…${progressInfo}`;
+    }
+  } else if (agent.status === "completed") {
+    subStatusText = agent.result ? truncateText(agent.result, 60) : "Done";
+  } else if (agent.status === "error") {
+    subStatusText = agent.error ?? "Error";
+  } else if (agent.status === "interrupted") {
+    subStatusText = "Interrupted";
+  } else if (agent.status === "background") {
+    subStatusText = `Running ${agent.name} in background…${progressInfo}`;
   }
 
+  // Current tool shown on separate line only during active execution
+  const showCurrentTool = Boolean(agent.currentTool) && (
+    isRunning ? ((agent.toolUses ?? 0) > 0) : true
+  );
+
+  const inlineParts = agent.inlineParts ?? [];
+  const hasInlineParts = inlineParts.length > 0;
+
   return (
     <box flexDirection="column">
+      {/* Tree row: ├─● task */}
       <box flexDirection="row">
-        <box flexShrink={0}><text style={{ fg: themeColors.muted }}>{treeChar} </text></box>
+        <box flexShrink={0}><text style={{ fg: themeColors.muted }}>{treeChar}</text></box>
         <box flexShrink={0}>
-          <text style={{ fg: fullRowIndicatorColor }}>●</text>
+          {animateRowIndicator ? (
+            <text><AnimatedBlinkIndicator color={rowIndicatorColor} speed={500} /></text>
+          ) : (
+            <text style={{ fg: rowIndicatorColor }}>●</text>
+          )}
         </box>
-          <text style={{ fg: themeColors.foreground, attributes: 1 }}>
-            {" "}{getAgentTaskLabel(agent)}
-          </text>
-        {metricsText && (
-          <text style={{ fg: themeColors.muted }}> · {metricsText}</text>
-        )}
+        <text style={{ fg: themeColors.foreground, attributes: 1 }}>
+          {" "}{displayTask}
+        </text>
       </box>
-      {/* Sub-status: current tool or default status text */}
-      {displaySubStatusFull && (
-        <box flexDirection="row">
-          <text style={{ fg: themeColors.muted }}>
-            {fullContinuationPrefix}{SUB_STATUS_PAD}{CONNECTOR.subStatus}  {displaySubStatusFull}
-          </text>
-        </box>
-      )}
-      {/* Result summary for completed agents */}
-      {isCompletedFull && agent.result && (
+      {/* Sub-status line */}
+      {subStatusText && (
         <box flexDirection="row">
           <text style={{ fg: themeColors.muted }}>
-            {fullContinuationPrefix}{SUB_STATUS_PAD}</text>
-          <text style={{ fg: themeColors.success }}>
-            {CONNECTOR.subStatus}  {truncateText(agent.result, 60)}
+            {continuationPrefix}{SUB_STATUS_PAD}{CONNECTOR.subStatus}  {subStatusText}
           </text>
         </box>
       )}
-      {/* Error message for failed agents */}
-      {isErrorFull && agent.error && (
+      {/* Current tool on separate line */}
+      {showCurrentTool && (
         <box flexDirection="row">
           <text style={{ fg: themeColors.muted }}>
-            {fullContinuationPrefix}{SUB_STATUS_PAD}</text>
-          <text style={{ fg: themeColors.error }}>
-            {CONNECTOR.subStatus}  {truncateText(agent.error, 60)}
+            {continuationPrefix}{SUB_STATUS_PAD}  {MISC.separator} {agent.currentTool}
           </text>
         </box>
       )}
-      {/* Interrupted message for cancelled agents */}
-      {isInterruptedFull && (
-        <box flexDirection="row">
-          <text style={{ fg: themeColors.muted }}>
-            {fullContinuationPrefix}{SUB_STATUS_PAD}</text>
-          <text style={{ fg: themeColors.warning }}>
-            {CONNECTOR.subStatus}  Interrupted
-          </text>
-        </box>
+      {/* Inline parts from sub-agent */}
+      {hasInlineParts && (
+        <AgentInlinePartsDisplay
+          parts={inlineParts}
+          continuationPrefix={continuationPrefix}
+          syntaxStyle={syntaxStyle}
+          themeColors={themeColors}
+        />
       )}
     </box>
   );
 }
 
+// ============================================================================
+// AGENT INLINE PARTS (sub-agent streaming content)
+// ============================================================================
+
+/**
+ * Renders inline parts from a sub-agent's
+ * streaming content, nested under the agent row with tree connectors.
+ */
+function AgentInlinePartsDisplay({
+  parts,
+  continuationPrefix,
+  syntaxStyle,
+  themeColors,
+}: {
+  parts: Part[];
+  continuationPrefix: string;
+  syntaxStyle?: SyntaxStyle;
+  themeColors: ThemeColors;
+}): React.ReactNode {
+  const visibleParts = getAgentInlineDisplayParts(parts);
+  if (visibleParts.length === 0) return null;
+  const inlinePrefix = buildAgentInlinePrefix(continuationPrefix);
+  const consumedTaskIds = getConsumedTaskToolCallIds(visibleParts);
+  const renderKeys = buildPartRenderKeys(visibleParts);
+  const renderQueue = visibleParts.flatMap((part, index) => {
+    if (part.type === "tool" && consumedTaskIds.has((part as ToolPart).toolCallId)) {
+      return [];
+    }
+    return [{ part, index }];
+  });
+
+  return (
+    <box flexDirection="column">
+      {renderQueue.map(({ part, index }, renderedIndex) => {
+        const Renderer = PART_REGISTRY[part.type];
+        if (!Renderer) return null;
+
+        return (
+          <box key={renderKeys[index] ?? part.id} flexDirection="row">
+            <box flexShrink={0}>
+              <text style={{ fg: themeColors.muted }}>{inlinePrefix}</text>
+            </box>
+            <box flexGrow={1} flexShrink={1}>
+              <Renderer
+                part={part}
+                isLast={renderedIndex === renderQueue.length - 1}
+                syntaxStyle={syntaxStyle}
+              />
+            </box>
+          </box>
+        );
+      })}
+    </box>
+  );
+}
+
 // ============================================================================
 // ANIMATED HEADER ICON
 // ============================================================================
@@ -479,42 +767,41 @@ function AgentRow({ agent, isLast, compact, themeColors }: AgentRowProps): React
  */
 export function ParallelAgentsTree({
   agents,
+  syntaxStyle,
   compact = false,
   maxVisible = 5,
   noTopMargin = false,
+  background = false,
+  showExpandHint = false,
 }: ParallelAgentsTreeProps): React.ReactNode {
   const { theme } = useTheme();
+  const [nowMs, setNowMs] = useState(() => Date.now());
+  const hasActiveAgents = agents.some(
+    (agent) => shouldAnimateAgentStatus(agent.status) || agent.status === "pending",
+  );
+  useEffect(() => {
+    if (!hasActiveAgents) return;
+    setNowMs(Date.now());
+    const interval = setInterval(() => {
+      setNowMs(Date.now());
+    }, 1000);
+    return () => clearInterval(interval);
+  }, [hasActiveAgents]);
 
   // Don't render if no agents
   if (agents.length === 0) {
     return null;
   }
 
-  // Sort agents: running first, then pending, then completed, then error
-  const sortedAgents = [...agents].sort((a, b) => {
-    const order: Record<AgentStatus, number> = {
-      running: 0,
-      pending: 1,
-      background: 2,
-      completed: 3,
-      interrupted: 4,
-      error: 5,
-    };
-    return order[a.status] - order[b.status];
-  });
-
-  // Limit visible agents if needed
-  const visibleAgents = sortedAgents.slice(0, maxVisible);
-  const hiddenCount = sortedAgents.length - visibleAgents.length;
+  // Preserve arrival order for stable chronological rendering.
+  const visibleAgents = agents.slice(0, maxVisible);
+  const hiddenCount = agents.length - visibleAgents.length;
 
   // Count agents by status
-  const runningCount = agents.filter(a => a.status === "running" || a.status === "background").length;
+  const activeCount = getForegroundActiveAgentCount(agents);
   const completedCount = agents.filter(a => a.status === "completed").length;
-  const pendingCount = agents.filter(a => a.status === "pending").length;
 
-  // Get the dominant agent type for the header
-  const agentTypes = [...new Set(agents.map(a => a.name))];
-  const dominantType = agentTypes.length === 1 ? (agentTypes[0] ?? "agents") : "agents";
+  // Dominant type removed — header always says "Task" for background, "agents" for foreground
 
   // Theme colors
   const themeColors: ThemeColors = {
@@ -532,22 +819,68 @@ export function ParallelAgentsTree({
   // Count interrupted agents
   const interruptedCount = agents.filter(a => a.status === "interrupted").length;
 
+  // Background mode: green dot header with "N Task agents launched"
+  if (background) {
+    const bgHeaderColor = themeColors.success;
+    const hasActiveBackground = agents.some((agent) => shouldAnimateAgentStatus(agent.status));
+    const bgHeaderText = `${agents.length} Task agent${agents.length !== 1 ? "s" : ""} launched…`;
+    const bgHintText = buildParallelAgentsHeaderHint(agents, showExpandHint);
+
+    return (
+      <box
+        flexDirection="column"
+        paddingLeft={SPACING.CONTAINER_PAD}
+        marginTop={noTopMargin ? SPACING.NONE : SPACING.ELEMENT}
+      >
+        {/* Background header */}
+        <box flexDirection="row">
+          {hasActiveBackground ? (
+            <text><AnimatedBlinkIndicator color={bgHeaderColor} speed={500} /></text>
+          ) : (
+            <text style={{ fg: bgHeaderColor }}>●</text>
+          )}
+          <text style={{ fg: themeColors.foreground }}> {bgHeaderText}</text>
+          {bgHintText !== "" && (
+            <text style={{ fg: themeColors.muted }}> · {bgHintText}</text>
+          )}
+        </box>
+
+        {/* Background agent tree */}
+        {visibleAgents.map((agent, index) => (
+          <BackgroundAgentRow
+            key={agent.id}
+            agent={agent}
+            isLast={index === visibleAgents.length - 1 && hiddenCount === 0}
+            themeColors={themeColors}
+            nowMs={nowMs}
+          />
+        ))}
+
+        {/* Hidden count indicator */}
+        {hiddenCount > 0 && (
+          <box flexDirection="row">
+            <text style={{ fg: themeColors.muted }}>
+              {TREE.lastBranch} ...and {hiddenCount} more
+            </text>
+          </box>
+        )}
+      </box>
+    );
+  }
+
   // Build header text - Claude Code style: "● Running N {Type} agents…"
-  const headerIcon = runningCount > 0 ? "●" : completedCount > 0 ? "●" : "○";
-  const headerColor = runningCount > 0
+  const headerIcon = activeCount > 0 ? "●" : completedCount > 0 ? "●" : "○";
+  const headerColor = activeCount > 0
     ? themeColors.accent
     : interruptedCount > 0
       ? themeColors.warning
       : completedCount > 0
         ? themeColors.success
         : themeColors.muted;
-  const headerText = runningCount > 0
-    ? `Running ${buildAgentHeaderLabel(runningCount, dominantType)}…`
-    : completedCount > 0
-      ? `${buildAgentHeaderLabel(completedCount, dominantType)} finished`
-      : `${buildAgentHeaderLabel(pendingCount, dominantType)} pending`;
+  const headerText = getForegroundHeaderText(agents);
 
-  const headerHint = buildParallelAgentsHeaderHint(agents, runningCount === 0);
+  // Build header hint from background agent tree hints
+  const headerHintText = buildParallelAgentsHeaderHint(agents, showExpandHint);
 
   return (
     <box
@@ -557,9 +890,15 @@ export function ParallelAgentsTree({
     >
       {/* Header */}
       <box flexDirection="row">
-        <text style={{ fg: headerColor }}>{headerIcon}</text>
+        {activeCount > 0 ? (
+          <text><AnimatedBlinkIndicator color={headerColor} speed={500} /></text>
+        ) : (
+          <text style={{ fg: headerColor }}>{headerIcon}</text>
+        )}
         <text style={{ fg: headerColor }}> {headerText}</text>
-        {headerHint && <text style={{ fg: themeColors.muted }}> ({headerHint})</text>}
+        {headerHintText !== "" && (
+          <text style={{ fg: themeColors.muted }}> · {headerHintText}</text>
+        )}
       </box>
 
       {/* Agent tree */}
@@ -569,7 +908,9 @@ export function ParallelAgentsTree({
           agent={agent}
           isLast={index === visibleAgents.length - 1 && hiddenCount === 0}
           compact={compact}
+          syntaxStyle={syntaxStyle}
           themeColors={themeColors}
+          nowMs={nowMs}
         />
       ))}
 
diff --git a/src/ui/components/parts/agent-part-display.test.ts b/src/ui/components/parts/agent-part-display.test.ts
new file mode 100644
index 0000000000..258ce439c8
--- /dev/null
+++ b/src/ui/components/parts/agent-part-display.test.ts
@@ -0,0 +1,86 @@
+import { describe, expect, test } from "bun:test";
+import type { ParallelAgent } from "../parallel-agents-tree.tsx";
+import {
+  getAgentTreeDisplayMode,
+  getBackgroundTreeAgents,
+  getForegroundTreeAgents,
+  hasActiveForegroundTreeAgents,
+} from "./agent-part-display.tsx";
+
+function makeAgent(overrides: Partial<ParallelAgent> & { id: string }): ParallelAgent {
+  return {
+    name: "debugger",
+    task: "Inspect state",
+    status: "running",
+    startedAt: "2026-01-01T00:00:00.000Z",
+    ...overrides,
+    id: overrides.id,
+  };
+}
+
+describe("AgentPartDisplay tree partitioning", () => {
+  test("splits foreground and background agents", () => {
+    const agents: ParallelAgent[] = [
+      makeAgent({ id: "fg-1", status: "running" }),
+      makeAgent({ id: "bg-1", status: "background", background: true }),
+      makeAgent({ id: "bg-2", status: "running", background: true }),
+    ];
+
+    const foreground = getForegroundTreeAgents(agents);
+    const background = getBackgroundTreeAgents(agents);
+
+    expect(foreground.map((a) => a.id)).toEqual(["fg-1"]);
+    expect(background.map((a) => a.id).sort()).toEqual(["bg-1", "bg-2"]);
+  });
+
+  test("returns mixed mode when both foreground and background exist", () => {
+    const foreground = [makeAgent({ id: "fg-1", status: "running" })];
+    const background = [makeAgent({ id: "bg-1", status: "background", background: true })];
+    expect(getAgentTreeDisplayMode(foreground, background)).toBe("mixed");
+  });
+
+  test("returns background mode when only background exists", () => {
+    const background = [makeAgent({ id: "bg-1", status: "background", background: true })];
+    expect(getAgentTreeDisplayMode([], background)).toBe("background");
+  });
+
+  test("returns foreground mode when only foreground exists", () => {
+    const foreground = [makeAgent({ id: "fg-1", status: "running" })];
+    expect(getAgentTreeDisplayMode(foreground, [])).toBe("foreground");
+  });
+
+  test("filters shadow foreground agents when mirrored background agents exist", () => {
+    const startedAt = "2026-01-01T00:00:00.000Z";
+    const agents: ParallelAgent[] = [
+      makeAgent({
+        id: "tool_1",
+        taskToolCallId: "tool_1",
+        name: "codebase-analyzer",
+        task: "Analyze Ctrl+C interrupt handling",
+        status: "background",
+        background: true,
+        startedAt,
+      }),
+      makeAgent({
+        id: "subagent_1",
+        name: "codebase-analyzer",
+        task: "Analyzes codebase implementation details. Call ...",
+        status: "running",
+        startedAt,
+      }),
+    ];
+
+    const foreground = getForegroundTreeAgents(agents);
+    const background = getBackgroundTreeAgents(agents);
+
+    expect(foreground).toHaveLength(0);
+    expect(background.map((a) => a.id)).toEqual(["tool_1"]);
+    expect(getAgentTreeDisplayMode(foreground, background)).toBe("background");
+    expect(hasActiveForegroundTreeAgents(agents)).toBe(false);
+  });
+
+  test("foreground active check ignores background-only activity", () => {
+    const backgroundOnly = [makeAgent({ id: "bg-1", status: "background", background: true })];
+    expect(hasActiveForegroundTreeAgents(backgroundOnly)).toBe(false);
+  });
+});
diff --git a/src/ui/components/parts/agent-part-display.tsx b/src/ui/components/parts/agent-part-display.tsx
index 0a46b3c80b..99de14c9b5 100644
--- a/src/ui/components/parts/agent-part-display.tsx
+++ b/src/ui/components/parts/agent-part-display.tsx
@@ -1,34 +1,137 @@
 /**
- * AgentPartDisplay Component
- *
  * Renders an AgentPart using the existing ParallelAgentsTree component.
- * Supports background status display with correct compact mode detection.
+ * Foreground agents render as a tree, while background agents are
+ * surfaced via a separate background-mode tree.
  */
 
-import React from "react";
+import React, { useMemo } from "react";
+import type { SyntaxStyle } from "@opentui/core";
 import type { AgentPart } from "../../parts/types.ts";
-import { ParallelAgentsTree } from "../parallel-agents-tree.tsx";
+import { ParallelAgentsTree, deduplicateAgents } from "../parallel-agents-tree.tsx";
+import type { ParallelAgent } from "../parallel-agents-tree.tsx";
+import { isBackgroundAgent, isShadowForegroundAgent } from "../../utils/background-agent-footer.ts";
 
 export interface AgentPartDisplayProps {
   part: AgentPart;
   isLast: boolean;
+  syntaxStyle?: SyntaxStyle;
 }
 
-export function AgentPartDisplay({ part }: AgentPartDisplayProps): React.ReactNode {
-  const hasActiveAgents = part.agents.some(
-    a => a.status === "running" || a.status === "pending" || a.status === "background"
+export function getForegroundTreeAgents(
+  agents: readonly ParallelAgent[],
+): ParallelAgent[] {
+  return agents.filter(
+    (agent) => !isBackgroundAgent(agent) && !isShadowForegroundAgent(agent, agents),
   );
+}
 
-  return (
-    <box flexDirection="column">
+export function getBackgroundTreeAgents(
+  agents: readonly ParallelAgent[],
+): ParallelAgent[] {
+  return agents.filter((agent) => isBackgroundAgent(agent));
+}
+
+export function hasActiveForegroundTreeAgents(
+  agents: readonly ParallelAgent[],
+): boolean {
+  return agents.some(
+    (agent) =>
+      (agent.status === "running" || agent.status === "pending")
+      && !isShadowForegroundAgent(agent, agents),
+  );
+}
+
+export type AgentTreeDisplayMode = "foreground" | "background" | "mixed";
+
+export function getAgentTreeDisplayMode(
+  foregroundAgents: readonly ParallelAgent[],
+  backgroundAgents: readonly ParallelAgent[],
+): AgentTreeDisplayMode {
+  if (foregroundAgents.length === 0) return "background";
+  if (backgroundAgents.length === 0) return "foreground";
+  return "mixed";
+}
+
+function AgentPartDisplayInner({ part, syntaxStyle }: AgentPartDisplayProps): React.ReactNode {
+  // Deduplicate before splitting so eager+real entries merge and
+  // the `background` flag is preserved on the winner.
+  const allAgents = useMemo(() => deduplicateAgents(part.agents), [part.agents]);
+
+  if (allAgents.length === 0) {
+    return null;
+  }
+
+  const {
+    foregroundAgents,
+    backgroundAgents,
+    displayMode,
+    hasActiveAgents,
+  } = useMemo(() => {
+    const nextForegroundAgents = getForegroundTreeAgents(allAgents);
+    const nextBackgroundAgents = getBackgroundTreeAgents(allAgents);
+    return {
+      foregroundAgents: nextForegroundAgents,
+      backgroundAgents: nextBackgroundAgents,
+      displayMode: getAgentTreeDisplayMode(nextForegroundAgents, nextBackgroundAgents),
+      hasActiveAgents: hasActiveForegroundTreeAgents(nextForegroundAgents),
+    };
+  }, [allAgents]);
+
+  if (displayMode === "background") {
+    return (
       <ParallelAgentsTree
-        agents={part.agents}
-        compact={!hasActiveAgents}
+        agents={backgroundAgents}
+        syntaxStyle={syntaxStyle}
+        background
         maxVisible={5}
         noTopMargin
       />
-    </box>
+    );
+  }
+
+  if (displayMode === "mixed") {
+    return (
+      <box flexDirection="column">
+        <ParallelAgentsTree
+          agents={foregroundAgents}
+          syntaxStyle={syntaxStyle}
+          compact={!hasActiveAgents}
+          maxVisible={5}
+          noTopMargin
+        />
+        <ParallelAgentsTree
+          agents={backgroundAgents}
+          syntaxStyle={syntaxStyle}
+          background
+          maxVisible={5}
+        />
+      </box>
+    );
+  }
+
+  return (
+    <ParallelAgentsTree
+      agents={foregroundAgents}
+      syntaxStyle={syntaxStyle}
+      compact={!hasActiveAgents}
+      maxVisible={5}
+      noTopMargin
+    />
   );
 }
 
+const MemoizedAgentPartDisplay = React.memo(
+  AgentPartDisplayInner,
+  (prev, next) =>
+    prev.part === next.part
+    && prev.syntaxStyle === next.syntaxStyle
+    && prev.isLast === next.isLast,
+);
+
+MemoizedAgentPartDisplay.displayName = "AgentPartDisplay";
+
+export function AgentPartDisplay(props: AgentPartDisplayProps): React.ReactNode {
+  return <MemoizedAgentPartDisplay {...props} />;
+}
+
 export default AgentPartDisplay;
diff --git a/src/ui/components/parts/index.ts b/src/ui/components/parts/index.ts
index 0afabde863..b8fe16eff4 100644
--- a/src/ui/components/parts/index.ts
+++ b/src/ui/components/parts/index.ts
@@ -11,8 +11,9 @@ export { ToolPartDisplay, type ToolPartDisplayProps } from "./tool-part-display.
 export { SkillLoadPartDisplay, type SkillLoadPartDisplayProps } from "./skill-load-part-display.tsx";
 export { McpSnapshotPartDisplay, type McpSnapshotPartDisplayProps } from "./mcp-snapshot-part-display.tsx";
 export { CompactionPartDisplay, type CompactionPartDisplayProps } from "./compaction-part-display.tsx";
+export { TaskResultPartDisplay, type TaskResultPartDisplayProps } from "./task-result-part-display.tsx";
+export { WorkflowStepPartDisplay, type WorkflowStepPartDisplayProps } from "./workflow-step-part-display.tsx";
 export { AgentPartDisplay, type AgentPartDisplayProps } from "./agent-part-display.tsx";
 export { TaskListPartDisplay, type TaskListPartDisplayProps } from "./task-list-part-display.tsx";
-export { UserQuestionInline, type UserQuestionInlineProps, type PendingQuestion } from "./user-question-inline.tsx";
 export { PART_REGISTRY, type PartRenderer } from "./registry.tsx";
 export { MessageBubbleParts, type MessageBubblePartsProps } from "./message-bubble-parts.tsx";
diff --git a/src/ui/components/parts/message-bubble-parts.test.ts b/src/ui/components/parts/message-bubble-parts.test.ts
index 2a4ba4dbbe..3d876fc1b3 100644
--- a/src/ui/components/parts/message-bubble-parts.test.ts
+++ b/src/ui/components/parts/message-bubble-parts.test.ts
@@ -1,6 +1,7 @@
 import { describe, expect, test } from "bun:test";
-import type { Part, ReasoningPart, TextPart } from "../../parts/types.ts";
-import { buildPartRenderKeys } from "./message-bubble-parts.tsx";
+import type { Part, ReasoningPart, TextPart, ToolPart, AgentPart } from "../../parts/types.ts";
+import type { ParallelAgent } from "../parallel-agents-tree.tsx";
+import { buildPartRenderKeys, getConsumedTaskToolCallIds, orderPartsForTaskOutputDisplay } from "./message-bubble-parts.tsx";
 
 function createReasoningPart(id: string, thinkingSourceKey: string): ReasoningPart {
   return {
@@ -59,3 +60,238 @@ describe("buildPartRenderKeys", () => {
     ]);
   });
 });
+
+describe("orderPartsForTaskOutputDisplay", () => {
+  test("moves TaskOutput tool parts directly below agent parts", () => {
+    const parts: Part[] = [
+      createTextPart("text-1"),
+      createToolPart("taskoutput-1", "TaskOutput"),
+      createAgentPart([createAgent("task-tool-1", "explorer")]),
+      createToolPart("bash-1", "bash"),
+    ];
+
+    const ordered = orderPartsForTaskOutputDisplay(parts);
+    expect(ordered.map((part) => part.type === "tool" ? `${part.type}:${part.toolName}` : part.type)).toEqual([
+      "text",
+      "agent",
+      "tool:TaskOutput",
+      "tool:bash",
+    ]);
+  });
+
+  test("keeps ordering when no agent part exists", () => {
+    const parts: Part[] = [
+      createTextPart("text-1"),
+      createToolPart("taskoutput-1", "TaskOutput"),
+      createToolPart("bash-1", "bash"),
+    ];
+
+    const ordered = orderPartsForTaskOutputDisplay(parts);
+    expect(ordered).toEqual(parts);
+  });
+});
+
+// ============================================================================
+// getConsumedTaskToolCallIds
+// ============================================================================
+
+function createToolPart(toolCallId: string, toolName: string): ToolPart {
+  return {
+    id: `part_${toolCallId}`,
+    type: "tool",
+    toolCallId,
+    toolName,
+    input: { prompt: "test" },
+    state: { status: "running", startedAt: "2026-01-01T00:00:00.000Z" },
+    createdAt: "2026-01-01T00:00:00.000Z",
+  };
+}
+
+function createAgent(
+  taskToolCallId: string,
+  name: string,
+  inlineParts?: Part[],
+): ParallelAgent {
+  return {
+    id: `agent-${taskToolCallId}`,
+    taskToolCallId,
+    name,
+    task: `Task for ${name}`,
+    status: "running",
+    startedAt: "2026-01-01T00:00:00.000Z",
+    inlineParts,
+  };
+}
+
+function createAgentPart(agents: ParallelAgent[], parentToolPartId?: string): AgentPart {
+  return {
+    id: "agent-part-1",
+    type: "agent",
+    agents,
+    parentToolPartId,
+    createdAt: "2026-01-01T00:00:00.000Z",
+  };
+}
+
+describe("getConsumedTaskToolCallIds", () => {
+  test("consumes sub-agent dispatch tools even when no AgentParts exist", () => {
+    const parts: Part[] = [
+      createToolPart("tool-1", "task"),
+      createToolPart("tool-2", "task"),
+    ];
+    const consumed = getConsumedTaskToolCallIds(parts);
+    expect(consumed.size).toBe(2);
+    expect(consumed.has("tool-1")).toBe(true);
+    expect(consumed.has("tool-2")).toBe(true);
+  });
+
+  test("does not consume non-subagent tools when no AgentParts exist", () => {
+    const parts: Part[] = [
+      createToolPart("tool-1", "bash"),
+      createToolPart("tool-2", "read"),
+    ];
+    expect(getConsumedTaskToolCallIds(parts).size).toBe(0);
+  });
+
+  test("returns Task toolCallIds that have corresponding agents", () => {
+    const parts: Part[] = [
+      createToolPart("tool-1", "task"),
+      createToolPart("tool-2", "task"),
+      createAgentPart([
+        createAgent("tool-1", "explorer"),
+        createAgent("tool-2", "analyzer"),
+      ]),
+    ];
+    const consumed = getConsumedTaskToolCallIds(parts);
+    expect(consumed.size).toBe(2);
+    expect(consumed.has("tool-1")).toBe(true);
+    expect(consumed.has("tool-2")).toBe(true);
+  });
+
+  test("consumes any ToolPart whose toolCallId matches an AgentPart (Copilot agent-named tools)", () => {
+    const parts: Part[] = [
+      createToolPart("tool-1", "codebase-analyzer"),
+      createAgentPart([createAgent("tool-1", "explorer")]),
+    ];
+    const consumed = getConsumedTaskToolCallIds(parts);
+    expect(consumed.size).toBe(1);
+    expect(consumed.has("tool-1")).toBe(true);
+  });
+
+  test("still consumes sub-agent dispatch tools even when only some are matched to agents", () => {
+    const parts: Part[] = [
+      createToolPart("tool-1", "task"),
+      createToolPart("tool-2", "task"),
+      createAgentPart([createAgent("tool-1", "explorer")]),
+    ];
+    const consumed = getConsumedTaskToolCallIds(parts);
+    expect(consumed.size).toBe(2);
+    expect(consumed.has("tool-1")).toBe(true);
+    expect(consumed.has("tool-2")).toBe(true);
+  });
+
+  test("handles PascalCase Task tool name", () => {
+    const parts: Part[] = [
+      createToolPart("tool-1", "Task"),
+      createAgentPart([createAgent("tool-1", "explorer")]),
+    ];
+    const consumed = getConsumedTaskToolCallIds(parts);
+    expect(consumed.has("tool-1")).toBe(true);
+  });
+
+  test("consumes Copilot agent-name ToolPart when matching AgentPart exists", () => {
+    const parts: Part[] = [
+      createToolPart("tool-1", "general-purpose"),
+      createToolPart("tool-2", "codebase-analyzer"),
+      createToolPart("tool-3", "bash"),
+      createAgentPart([
+        createAgent("tool-1", "general-purpose"),
+        createAgent("tool-2", "codebase-analyzer"),
+      ]),
+    ];
+    const consumed = getConsumedTaskToolCallIds(parts);
+    expect(consumed.size).toBe(2);
+    expect(consumed.has("tool-1")).toBe(true);
+    expect(consumed.has("tool-2")).toBe(true);
+    // tool-3 (bash) has no matching AgentPart, so it should NOT be consumed
+    expect(consumed.has("tool-3")).toBe(false);
+  });
+
+  test("consumes top-level ToolPart duplicated by agent inline tool activity", () => {
+    const inlineTool = createToolPart("inline-tool-1", "bash");
+    const parts: Part[] = [
+      createToolPart("inline-tool-1", "bash"),
+      createToolPart("standalone-tool", "bash"),
+      createAgentPart([
+        createAgent("task-tool-1", "codebase-analyzer", [inlineTool]),
+      ]),
+    ];
+
+    const consumed = getConsumedTaskToolCallIds(parts);
+    expect(consumed.has("inline-tool-1")).toBe(true);
+    expect(consumed.has("standalone-tool")).toBe(false);
+  });
+
+  test("does not consume mirrored TaskOutput tool blocks", () => {
+    const inlineTaskOutput = createToolPart("taskoutput-1", "TaskOutput");
+    const parts: Part[] = [
+      createToolPart("taskoutput-1", "TaskOutput"),
+      createAgentPart([
+        createAgent("task-tool-1", "codebase-analyzer", [inlineTaskOutput]),
+      ]),
+    ];
+
+    const consumed = getConsumedTaskToolCallIds(parts);
+    expect(consumed.has("taskoutput-1")).toBe(false);
+  });
+
+  test("consumes task ToolPart when agent lacks taskToolCallId (Claude SDK fallback)", () => {
+    const agentWithoutId: ParallelAgent = {
+      id: "agent-no-id",
+      taskToolCallId: undefined,
+      name: "codebase-analyzer",
+      task: "Explore the repo",
+      status: "running",
+      startedAt: "2026-01-01T00:00:00.000Z",
+    };
+    const parts: Part[] = [
+      createToolPart("synth-tool-1", "Task"),
+      createAgentPart([agentWithoutId]),
+    ];
+    const consumed = getConsumedTaskToolCallIds(parts);
+    expect(consumed.size).toBe(1);
+    expect(consumed.has("synth-tool-1")).toBe(true);
+  });
+
+  test("consumes task ToolPart when agent taskToolCallId does not match any ToolPart", () => {
+    const parts: Part[] = [
+      createToolPart("synth-tool-1", "task"),
+      createAgentPart([createAgent("toolu_ABC", "explorer")]),
+    ];
+    const consumed = getConsumedTaskToolCallIds(parts);
+    expect(consumed.size).toBe(1);
+    expect(consumed.has("synth-tool-1")).toBe(true);
+  });
+
+  test("consumes all sub-agent dispatch tools regardless of fallback count", () => {
+    const agentWithoutId: ParallelAgent = {
+      id: "agent-no-id",
+      taskToolCallId: undefined,
+      name: "explorer",
+      task: "Explore",
+      status: "running",
+      startedAt: "2026-01-01T00:00:00.000Z",
+    };
+    const parts: Part[] = [
+      createToolPart("tool-1", "task"),
+      createToolPart("tool-2", "task"),
+      createToolPart("tool-3", "task"),
+      createAgentPart([agentWithoutId]),
+    ];
+    const consumed = getConsumedTaskToolCallIds(parts);
+    expect(consumed.size).toBe(3);
+    expect(consumed.has("tool-1")).toBe(true);
+    expect(consumed.has("tool-2")).toBe(true);
+    expect(consumed.has("tool-3")).toBe(true);
+  });
+});
diff --git a/src/ui/components/parts/message-bubble-parts.tsx b/src/ui/components/parts/message-bubble-parts.tsx
index 58ee0ebc32..d1c49bff6a 100644
--- a/src/ui/components/parts/message-bubble-parts.tsx
+++ b/src/ui/components/parts/message-bubble-parts.tsx
@@ -8,9 +8,143 @@
 import React from "react";
 import type { SyntaxStyle } from "@opentui/core";
 import type { ChatMessage } from "../../chat.tsx";
-import type { Part } from "../../parts/types.ts";
+import type { Part, ToolPart, AgentPart } from "../../parts/types.ts";
 import { PART_REGISTRY } from "./registry.tsx";
 import { SPACING } from "../../constants/spacing.ts";
+import { isSubagentToolName } from "../../parts/stream-pipeline.ts";
+
+function isTaskOutputToolName(toolName: string): boolean {
+  return toolName.trim().toLowerCase() === "taskoutput";
+}
+
+export function orderPartsForTaskOutputDisplay(parts: ReadonlyArray<Part>): Part[] {
+  const hasAgentPart = parts.some((part) => part.type === "agent");
+  if (!hasAgentPart) {
+    return [...parts];
+  }
+
+  const taskOutputParts: Part[] = [];
+  const remainingParts: Part[] = [];
+
+  for (const part of parts) {
+    if (part.type === "tool" && isTaskOutputToolName((part as ToolPart).toolName)) {
+      taskOutputParts.push(part);
+      continue;
+    }
+    remainingParts.push(part);
+  }
+
+  if (taskOutputParts.length === 0) {
+    return [...parts];
+  }
+
+  let lastAgentIndex = -1;
+  for (let i = 0; i < remainingParts.length; i++) {
+    if (remainingParts[i]?.type === "agent") {
+      lastAgentIndex = i;
+    }
+  }
+
+  if (lastAgentIndex < 0) {
+    return [...parts];
+  }
+
+  return [
+    ...remainingParts.slice(0, lastAgentIndex + 1),
+    ...taskOutputParts,
+    ...remainingParts.slice(lastAgentIndex + 1),
+  ];
+}
+
+/**
+ * Build a set of toolCallIds that are already represented by an AgentPart.
+ * These ToolParts should be hidden because the agent tree already displays
+ * the same information (task description, status, tool uses, result, and
+ * nested inline tool activity).
+ *
+ * The check is purely ID-based (agentTaskToolCallIds set) — no tool-name
+ * guard is needed because Copilot uses the agent's own name as the tool
+ * name (e.g., "general-purpose", "codebase-analyzer") rather than "task".
+ */
+export function getConsumedTaskToolCallIds(parts: ReadonlyArray<Part>): Set<string> {
+  const consumed = new Set<string>();
+
+  // Always hide sub-agent dispatch tool widgets (Task/Agent/launch_agent).
+  // The dedicated agent tree is the canonical visualization for these calls.
+  for (const part of parts) {
+    if (part.type !== "tool") continue;
+    const toolPart = part as ToolPart;
+    if (isSubagentToolName(toolPart.toolName)) {
+      consumed.add(toolPart.toolCallId);
+    }
+  }
+
+  const hasAgentPart = parts.some((p) => p.type === "agent");
+  if (!hasAgentPart) return consumed;
+
+  const agentTaskToolCallIds = new Set<string>();
+  const inlineToolCallIds = new Set<string>();
+  for (const part of parts) {
+    if (part.type !== "agent") continue;
+    for (const agent of (part as AgentPart).agents) {
+      if (agent.taskToolCallId) {
+        agentTaskToolCallIds.add(agent.taskToolCallId);
+      }
+      for (const inlinePart of agent.inlineParts ?? []) {
+        if (inlinePart.type !== "tool") continue;
+        const inlineToolCallId = (inlinePart as ToolPart).toolCallId;
+        if (inlineToolCallId) {
+          inlineToolCallIds.add(inlineToolCallId);
+        }
+      }
+    }
+  }
+
+  for (const part of parts) {
+    if (part.type !== "tool") continue;
+    const toolPart = part as ToolPart;
+    const duplicatedInlineTool = inlineToolCallIds.has(toolPart.toolCallId);
+    if (duplicatedInlineTool && isTaskOutputToolName(toolPart.toolName)) {
+      continue;
+    }
+    if (
+      agentTaskToolCallIds.has(toolPart.toolCallId)
+      || duplicatedInlineTool
+    ) {
+      consumed.add(toolPart.toolCallId);
+    }
+  }
+
+  // Fallback: count agents not matched to a consumed ToolPart.
+  // Handles (a) agents without taskToolCallId (e.g., Claude Agent SDK where
+  // SubagentStart hooks may not provide toolUseID), and (b) agents whose
+  // taskToolCallId doesn't match any ToolPart's toolCallId.
+  let unmatchedAgents = 0;
+  for (const part of parts) {
+    if (part.type !== "agent") continue;
+    for (const agent of (part as AgentPart).agents) {
+      if (!agent.taskToolCallId || !consumed.has(agent.taskToolCallId)) {
+        unmatchedAgents++;
+      }
+    }
+  }
+
+  if (unmatchedAgents > 0) {
+    let remaining = unmatchedAgents;
+    for (const part of parts) {
+      if (remaining <= 0) break;
+      if (part.type !== "tool") continue;
+      const toolPart = part as ToolPart;
+      if (consumed.has(toolPart.toolCallId)) continue;
+      if (isSubagentToolName(toolPart.toolName)) {
+        consumed.add(toolPart.toolCallId);
+        remaining--;
+      }
+    }
+  }
+
+  return consumed;
+}
 
 export interface MessageBubblePartsProps {
   message: ChatMessage;
@@ -65,16 +199,28 @@ export function buildPartRenderKeys(parts: ReadonlyArray<Part>): string[] {
  * separation can add marginTop internally.
  */
 export function MessageBubbleParts({ message, syntaxStyle }: MessageBubblePartsProps): React.ReactNode {
-  const parts = message.parts ?? [];
+  const parts = orderPartsForTaskOutputDisplay(message.parts ?? []);
   const renderKeys = buildPartRenderKeys(parts);
 
   if (parts.length === 0) {
     return null;
   }
 
+  // Task tool ToolParts that are represented by an AgentPart tree should be
+  // hidden to avoid redundant display (the tree already shows task
+  // description, status, tool uses, and result).
+  const consumedTaskIds = getConsumedTaskToolCallIds(parts);
+
   return (
     <box flexDirection="column" gap={SPACING.ELEMENT}>
       {parts.map((part, index) => {
+        // Skip Task ToolParts consumed by the agent tree
+        if (
+          part.type === "tool" &&
+          consumedTaskIds.has((part as ToolPart).toolCallId)
+        ) {
+          return null;
+        }
         const Renderer = PART_REGISTRY[part.type];
         if (!Renderer) return null;
         return (
diff --git a/src/ui/components/parts/reasoning-part-display.tsx b/src/ui/components/parts/reasoning-part-display.tsx
index 6f2d1ba325..bc69f9fe52 100644
--- a/src/ui/components/parts/reasoning-part-display.tsx
+++ b/src/ui/components/parts/reasoning-part-display.tsx
@@ -2,19 +2,37 @@
  * ReasoningPartDisplay Component
  *
  * Renders a ReasoningPart showing the model's reasoning/thinking process.
- * Uses <code filetype="markdown"> with a dimmed syntax style for visual
- * distinction from primary response content. If syntaxStyle is missing,
- * falls back to the same markdown code rendering with a local fallback style.
+ * Uses <markdown> with a dimmed syntax style for visual distinction from
+ * primary response content, matching TextPartDisplay's rendering path for
+ * consistent block formatting (spacing, tables, lists). Falls back to
+ * <code filetype="markdown"> when no syntaxStyle is provided.
  */
 
 import React, { useMemo } from "react";
-import type { SyntaxStyle } from "@opentui/core";
+import { MarkdownRenderable, type SyntaxStyle } from "@opentui/core";
 import type { ReasoningPart } from "../../parts/types.ts";
 import { createDimmedSyntaxStyle, createMarkdownSyntaxStyle, useTheme, useThemeColors } from "../../theme.tsx";
 import { SPACING } from "../../constants/spacing.ts";
 import { MISC } from "../../constants/icons.ts";
 import { normalizeMarkdownNewlines } from "../../utils/format.ts";
 
+// Patch MarkdownRenderable for text selection (same as TextPartDisplay).
+// MarkdownRenderable extends Renderable (not TextBufferRenderable), so its
+// shouldStartSelection() always returns false. This patch delegates to a
+// bounds check so selection can initiate inside child TextRenderable instances.
+if (!(MarkdownRenderable.prototype as any).__reasoningSelectionPatched) {
+  MarkdownRenderable.prototype.shouldStartSelection = function (
+    x: number,
+    y: number,
+  ) {
+    if (!this.selectable) return false;
+    const localX = x - this.x;
+    const localY = y - this.y;
+    return localX >= 0 && localX < this.width && localY >= 0 && localY < this.height;
+  };
+  (MarkdownRenderable.prototype as any).__reasoningSelectionPatched = true;
+}
+
 export interface ReasoningPartDisplayProps {
   part: ReasoningPart;
   isLast: boolean;
@@ -52,15 +70,26 @@ export function ReasoningPartDisplay({ part, syntaxStyle }: ReasoningPartDisplay
       </text>
       {normalizedContent && (
         <box marginLeft={SPACING.INDENT}>
-          <code
-            filetype="markdown"
-            drawUnstyledText={false}
-            streaming={part.isStreaming}
-            syntaxStyle={dimmedStyle}
-            content={normalizedContent}
-            conceal={true}
-            fg={colors.muted}
-          />
+          {syntaxStyle ? (
+            <markdown
+              content={normalizedContent}
+              syntaxStyle={dimmedStyle}
+              streaming={part.isStreaming}
+              conceal={true}
+              // @ts-expect-error selectable is a valid Renderable property but not typed in MarkdownOptions
+              selectable={true}
+            />
+          ) : (
+            <code
+              filetype="markdown"
+              drawUnstyledText={false}
+              streaming={part.isStreaming}
+              syntaxStyle={dimmedStyle}
+              content={normalizedContent}
+              conceal={true}
+              fg={colors.muted}
+            />
+          )}
         </box>
       )}
     </box>
diff --git a/src/ui/components/parts/registry.tsx b/src/ui/components/parts/registry.tsx
index 37bd0a172e..c40a400fee 100644
--- a/src/ui/components/parts/registry.tsx
+++ b/src/ui/components/parts/registry.tsx
@@ -16,6 +16,8 @@ import { TaskListPartDisplay } from "./task-list-part-display.tsx";
 import { SkillLoadPartDisplay } from "./skill-load-part-display.tsx";
 import { McpSnapshotPartDisplay } from "./mcp-snapshot-part-display.tsx";
 import { CompactionPartDisplay } from "./compaction-part-display.tsx";
+import { TaskResultPartDisplay } from "./task-result-part-display.tsx";
+import { WorkflowStepPartDisplay } from "./workflow-step-part-display.tsx";
 
 export type PartRenderer = (props: { part: any; isLast: boolean; syntaxStyle?: SyntaxStyle }) => React.ReactNode;
 
@@ -28,4 +30,6 @@ export const PART_REGISTRY: Record<Part["type"], PartRenderer> = {
   "skill-load": SkillLoadPartDisplay,
   "mcp-snapshot": McpSnapshotPartDisplay,
   "compaction": CompactionPartDisplay,
+  "task-result": TaskResultPartDisplay,
+  "workflow-step": WorkflowStepPartDisplay,
 };
diff --git a/src/ui/components/parts/task-list-part-display.tsx b/src/ui/components/parts/task-list-part-display.tsx
index 954b9ca5cd..4beb920f3e 100644
--- a/src/ui/components/parts/task-list-part-display.tsx
+++ b/src/ui/components/parts/task-list-part-display.tsx
@@ -8,6 +8,7 @@
 import React from "react";
 import type { TaskListPart } from "../../parts/types.ts";
 import { TaskListBox } from "../task-list-panel.tsx";
+import { sortTasksTopologically } from "../task-order.ts";
 import { SPACING } from "../../constants/spacing.ts";
 
 export interface TaskListPartDisplayProps {
@@ -16,10 +17,12 @@ export interface TaskListPartDisplayProps {
 }
 
 export function TaskListPartDisplay({ part }: TaskListPartDisplayProps): React.ReactNode {
+  const sortedItems = sortTasksTopologically(part.items);
+
   return (
     <box flexDirection="column" paddingLeft={SPACING.INDENT} paddingRight={SPACING.INDENT} marginTop={SPACING.SECTION}>
       <TaskListBox
-        items={part.items}
+        items={sortedItems}
         expanded={part.expanded}
         headerTitle="Todo Progress"
       />
diff --git a/src/ui/components/parts/task-result-part-display.tsx b/src/ui/components/parts/task-result-part-display.tsx
new file mode 100644
index 0000000000..8fab9f525e
--- /dev/null
+++ b/src/ui/components/parts/task-result-part-display.tsx
@@ -0,0 +1,42 @@
+import React from "react";
+import type { TaskResultPart } from "../../parts/types.ts";
+import { useThemeColors } from "../../theme.tsx";
+import { SPACING } from "../../constants/spacing.ts";
+import { STATUS } from "../../constants/icons.ts";
+
+export interface TaskResultPartDisplayProps {
+  part: TaskResultPart;
+  isLast: boolean;
+}
+
+export function TaskResultPartDisplay({ part }: TaskResultPartDisplayProps): React.ReactNode {
+  const colors = useThemeColors();
+  const isError = part.status === "error";
+  const statusColor = isError ? colors.error : colors.success;
+  const statusLabel = isError ? "error" : "completed";
+  const statusIcon = isError ? STATUS.error : STATUS.success;
+  const output = part.outputText.trim();
+
+  return (
+    <box flexDirection="column">
+      <text style={{ fg: statusColor }}>
+        {`${statusIcon} Task result ${part.taskId} (${statusLabel})`}
+      </text>
+      <box marginLeft={SPACING.INDENT}>
+        <text style={{ fg: colors.foreground }}>{part.title}</text>
+      </box>
+      {output.length > 0 && (
+        <box marginLeft={SPACING.INDENT}>
+          <text style={{ fg: colors.muted }}>{output}</text>
+        </box>
+      )}
+      {isError && part.error && (
+        <box marginLeft={SPACING.INDENT}>
+          <text style={{ fg: colors.error }}>{part.error}</text>
+        </box>
+      )}
+    </box>
+  );
+}
+
+export default TaskResultPartDisplay;
diff --git a/src/ui/components/parts/text-part-display.tsx b/src/ui/components/parts/text-part-display.tsx
index adb59957a4..3b500686fe 100644
--- a/src/ui/components/parts/text-part-display.tsx
+++ b/src/ui/components/parts/text-part-display.tsx
@@ -1,18 +1,37 @@
 /**
  * TextPartDisplay Component
  *
- * Renders a TextPart as markdown with optional throttling
- * during streaming to prevent UI thrashing. Uses <markdown>
- * when syntaxStyle is available, otherwise falls back to
- * <code filetype="markdown"> with conceal/streaming.
+ * Renders a TextPart as markdown with a ● bullet prefix per the
+ * UI design patterns. Uses <markdown> when syntaxStyle is available,
+ * otherwise falls back to <code filetype="markdown"> with conceal/streaming.
+ *
+ * Layout:
+ *   ● First line of markdown content
+ *     continuation lines are indented to align with text after the bullet
  */
 
 import React, { useMemo } from "react";
-import type { SyntaxStyle } from "@opentui/core";
+import { MarkdownRenderable, type SyntaxStyle } from "@opentui/core";
 import type { TextPart } from "../../parts/types.ts";
-import { useThrottledValue } from "../../hooks/use-throttled-value.ts";
 import { createMarkdownSyntaxStyle, useTheme, useThemeColors } from "../../theme.tsx";
 import { normalizeMarkdownNewlines } from "../../utils/format.ts";
+import { STATUS } from "../../constants/icons.ts";
+
+// Patch MarkdownRenderable to support text selection.
+// MarkdownRenderable extends Renderable (not TextBufferRenderable), so its
+// shouldStartSelection() always returns false, preventing selection from
+// starting when the hit test returns a MarkdownRenderable. This patch
+// delegates to a bounds check so selection can initiate and then walk into
+// the child TextRenderable instances that hold the actual text.
+MarkdownRenderable.prototype.shouldStartSelection = function (
+  x: number,
+  y: number,
+) {
+  if (!this.selectable) return false;
+  const localX = x - this.x;
+  const localY = y - this.y;
+  return localX >= 0 && localX < this.width && localY >= 0 && localY < this.height;
+};
 
 export interface TextPartDisplayProps {
   part: TextPart;
@@ -22,38 +41,46 @@ export interface TextPartDisplayProps {
 export function TextPartDisplay({ part, syntaxStyle }: TextPartDisplayProps) {
   const colors = useThemeColors();
   const { isDark } = useTheme();
-  const displayContent = useThrottledValue(part.content, part.isStreaming ? 100 : 0);
   const fallbackSyntaxStyle = useMemo(
     () => createMarkdownSyntaxStyle(colors, isDark),
     [colors, isDark],
   );
 
-  const normalizedContent = normalizeMarkdownNewlines(displayContent ?? "");
+  const normalizedContent = normalizeMarkdownNewlines(part.content ?? "");
 
   if (!normalizedContent) {
     return null;
   }
 
+  // Static ● bullet for text blocks (no blinking).
+  // Green ● is reserved for tool/agent blocks on success.
+  const bullet = <text style={{ fg: colors.foreground }}>{STATUS.active}</text>;
+
   return (
-    <box flexDirection="column">
-      {syntaxStyle ? (
-        <markdown
-          content={normalizedContent}
-          syntaxStyle={syntaxStyle}
-          streaming={part.isStreaming}
-          conceal={true}
-        />
-      ) : (
-        <code
-          content={normalizedContent}
-          filetype="markdown"
-          drawUnstyledText={false}
-          streaming={part.isStreaming}
-          syntaxStyle={syntaxStyle ?? fallbackSyntaxStyle}
-          fg={colors.foreground}
-          conceal={true}
-        />
-      )}
+    <box flexDirection="row">
+      <box flexShrink={0} width={2}>{bullet}</box>
+      <box flexGrow={1} flexShrink={1} flexDirection="column">
+        {syntaxStyle ? (
+          <markdown
+            content={normalizedContent}
+            syntaxStyle={syntaxStyle}
+            streaming={part.isStreaming}
+            conceal={true}
+            // @ts-expect-error selectable is a valid Renderable property but not typed in MarkdownOptions
+            selectable={true}
+          />
+        ) : (
+          <code
+            content={normalizedContent}
+            filetype="markdown"
+            drawUnstyledText={false}
+            streaming={part.isStreaming}
+            syntaxStyle={syntaxStyle ?? fallbackSyntaxStyle}
+            fg={colors.foreground}
+            conceal={true}
+          />
+        )}
+      </box>
     </box>
   );
 }
diff --git a/src/ui/components/parts/tool-part-display.tsx b/src/ui/components/parts/tool-part-display.tsx
index b181049ba4..4392fcfe7e 100644
--- a/src/ui/components/parts/tool-part-display.tsx
+++ b/src/ui/components/parts/tool-part-display.tsx
@@ -11,7 +11,7 @@ import { ToolResult } from "../tool-result.tsx";
 import { useThemeColors } from "../../theme.tsx";
 import { CONNECTOR, STATUS, TREE } from "../../constants/icons.ts";
 import type { ToolPart, ToolState } from "../../parts/types.ts";
-import type { ToolExecutionStatus } from "../../hooks/use-streaming-state.ts";
+import type { ToolExecutionStatus } from "../../parts/types.ts";
 import type { HitlResponseRecord } from "../../utils/hitl-response.ts";
 
 export interface ToolPartDisplayProps {
diff --git a/src/ui/components/parts/user-question-inline.tsx b/src/ui/components/parts/user-question-inline.tsx
deleted file mode 100644
index c163fe747f..0000000000
--- a/src/ui/components/parts/user-question-inline.tsx
+++ /dev/null
@@ -1,233 +0,0 @@
-/**
- * UserQuestionInline Component
- *
- * Renders HITL (Human-in-the-Loop) permission questions inline after
- * their associated ToolPart, rather than as a fixed-position overlay.
- *
- * This is the key architectural change from the parts-based rendering spec.
- * Inspired by OpenCode's QuestionPrompt at message-part.tsx:547-665.
- *
- * Features model-generated options with descriptions, plus "Type something"
- * and "Chat about this" options — matching the UserQuestionDialog style
- * used by OpenCode and Claude.
- */
-
-import React, { useState, useCallback, useMemo, useRef } from "react";
-import { useKeyboard } from "@opentui/react";
-import type { KeyEvent, TextareaRenderable } from "@opentui/core";
-import { useThemeColors } from "../../theme.tsx";
-import { STATUS, PROMPT, CONNECTOR } from "../../constants/icons.ts";
-import { SPACING } from "../../constants/spacing.ts";
-import { navigateUp, navigateDown } from "../../utils/navigation.ts";
-import type { PermissionOption } from "../../../sdk/types.ts";
-
-// Special option values — same as UserQuestionDialog
-const CUSTOM_INPUT_VALUE = "__custom_input__";
-const CHAT_ABOUT_THIS_VALUE = "__chat_about_this__";
-
-export interface PendingQuestion {
-  requestId: string;
-  header: string;
-  question: string;
-  options: PermissionOption[];
-  multiSelect: boolean;
-  respond: (answer: string | string[]) => void;
-}
-
-export interface UserQuestionInlineProps {
-  question: PendingQuestion;
-  onAnswer: (answer: string | string[]) => void;
-}
-
-export function UserQuestionInline({ question, onAnswer }: UserQuestionInlineProps): React.ReactNode {
-  const colors = useThemeColors();
-  const [highlightedIndex, setHighlightedIndex] = useState(0);
-  const [isEditingCustom, setIsEditingCustom] = useState(false);
-  const [isChatAboutThis, setIsChatAboutThis] = useState(false);
-  const textareaRef = useRef<TextareaRenderable>(null);
-
-  // Build the full options list including "Type something" and "Chat about this"
-  const allOptions = useMemo(() => {
-    const opts: Array<{ label: string; value: string; description?: string }> = [
-      ...question.options,
-      { label: "Type something.", value: CUSTOM_INPUT_VALUE, description: undefined },
-      { label: "Chat about this", value: CHAT_ABOUT_THIS_VALUE, description: undefined },
-    ];
-    return opts;
-  }, [question.options]);
-
-  const optionsCount = allOptions.length;
-  const regularOptionsCount = question.options.length;
-
-  const submitCustomText = useCallback(() => {
-    const text = textareaRef.current?.plainText ?? "";
-    const trimmed = text.trim();
-    if (trimmed || isChatAboutThis) {
-      onAnswer(trimmed);
-    }
-    setIsEditingCustom(false);
-    setIsChatAboutThis(false);
-  }, [onAnswer, isChatAboutThis]);
-
-  useKeyboard(
-    useCallback((event: KeyEvent) => {
-      const key = event.name ?? "";
-
-      // In custom input / chat mode, only handle escape and return
-      if (isEditingCustom || isChatAboutThis) {
-        if (key === "escape") {
-          event.stopPropagation();
-          setIsEditingCustom(false);
-          setIsChatAboutThis(false);
-          return;
-        }
-        if (key === "return") {
-          event.stopPropagation();
-          submitCustomText();
-          return;
-        }
-        return;
-      }
-
-      event.stopPropagation();
-
-      // Number keys 1-9 for direct selection of model-generated options
-      if (key >= "1" && key <= "9") {
-        const index = parseInt(key) - 1;
-        if (index < regularOptionsCount) {
-          const option = allOptions[index];
-          if (option) {
-            onAnswer(option.value);
-          }
-        }
-        return;
-      }
-
-      // Up navigation (also Ctrl+P, k)
-      if (key === "up" || (event.ctrl && key === "p") || key === "k") {
-        setHighlightedIndex((prev) => navigateUp(prev, optionsCount));
-        return;
-      }
-
-      // Down navigation (also Ctrl+N, j)
-      if (key === "down" || (event.ctrl && key === "n") || key === "j") {
-        setHighlightedIndex((prev) => navigateDown(prev, optionsCount));
-        return;
-      }
-
-      // Enter to select
-      if (key === "return") {
-        const option = allOptions[highlightedIndex];
-        if (!option) return;
-
-        if (option.value === CUSTOM_INPUT_VALUE) {
-          setIsEditingCustom(true);
-          return;
-        }
-        if (option.value === CHAT_ABOUT_THIS_VALUE) {
-          setIsChatAboutThis(true);
-          return;
-        }
-        onAnswer(option.value);
-        return;
-      }
-
-      // Escape to cancel/decline
-      if (key === "escape") {
-        onAnswer("deny");
-        return;
-      }
-    }, [isEditingCustom, isChatAboutThis, optionsCount, regularOptionsCount, highlightedIndex, allOptions, onAnswer, submitCustomText])
-  );
-
-  return (
-    <box flexDirection="column" marginTop={SPACING.SECTION}>
-      {/* Header badge — matches UserQuestionDialog style */}
-      {question.header && (
-        <box marginBottom={SPACING.SECTION}>
-          <text>
-            <span style={{ fg: colors.border }}>{CONNECTOR.roundedTopLeft}{CONNECTOR.horizontal}</span>
-            <span style={{ fg: colors.foreground }}> {STATUS.pending} {question.header} </span>
-            <span style={{ fg: colors.border }}>{CONNECTOR.horizontal}{CONNECTOR.roundedTopRight}</span>
-          </text>
-        </box>
-      )}
-
-      {/* Question text — bold for visibility */}
-      <text style={{ fg: colors.foreground, attributes: 1 }} wrapMode="word">
-        {question.question}
-      </text>
-
-      {/* Custom input / Chat about this mode */}
-      {(isEditingCustom || isChatAboutThis) ? (
-        <box flexDirection="column" marginTop={SPACING.ELEMENT}>
-          <box
-            border
-            borderStyle="rounded"
-            borderColor={colors.accent}
-            paddingLeft={SPACING.CONTAINER_PAD}
-            paddingRight={SPACING.CONTAINER_PAD}
-            flexDirection="row"
-            alignItems="center"
-          >
-            <text style={{ fg: colors.accent }}>{PROMPT.cursor} </text>
-            <textarea
-              ref={textareaRef}
-              placeholder={isChatAboutThis ? "Type your thoughts..." : "Type your answer..."}
-              focused={true}
-              minHeight={1}
-              maxHeight={5}
-              flexGrow={1}
-              wrapMode="word"
-            />
-          </box>
-          <text style={{ fg: colors.muted }}>
-            Enter to submit · Esc to go back
-          </text>
-        </box>
-      ) : (
-        <>
-          {/* Options list — model options + "Type something" + "Chat about this" */}
-          <box flexDirection="column" marginTop={SPACING.ELEMENT}>
-            {allOptions.map((opt, idx) => {
-              const isHighlighted = idx === highlightedIndex;
-              const labelColor = isHighlighted ? colors.accent : colors.foreground;
-              const descColor = isHighlighted ? colors.accent : colors.muted;
-              const displayNumber = idx + 1;
-
-              return (
-                <React.Fragment key={opt.value}>
-                  <text>
-                    <span style={{ fg: isHighlighted ? colors.accent : colors.muted }}>
-                      {isHighlighted ? `${PROMPT.cursor} ` : "  "}
-                    </span>
-                    <span style={{ fg: labelColor }}>
-                      {displayNumber}.{" "}
-                      <span style={{ fg: labelColor, attributes: isHighlighted ? 1 : undefined }}>
-                        {opt.label}
-                      </span>
-                    </span>
-                  </text>
-                  {opt.description && (
-                    <text style={{ fg: descColor }}>
-                      {"     "}{opt.description}
-                    </text>
-                  )}
-                </React.Fragment>
-              );
-            })}
-          </box>
-
-          {/* Footer hint */}
-          <box marginTop={SPACING.ELEMENT}>
-            <text style={{ fg: colors.muted }}>
-              Enter to select · ↑/↓ to navigate · Esc to cancel
-            </text>
-          </box>
-        </>
-      )}
-    </box>
-  );
-}
-
-export default UserQuestionInline;
diff --git a/src/ui/components/parts/workflow-step-part-display.tsx b/src/ui/components/parts/workflow-step-part-display.tsx
new file mode 100644
index 0000000000..ebfc73ab7c
--- /dev/null
+++ b/src/ui/components/parts/workflow-step-part-display.tsx
@@ -0,0 +1,43 @@
+import React from "react";
+import type { WorkflowStepPart } from "../../parts/types.ts";
+import { useThemeColors } from "../../theme.tsx";
+import { MISC, STATUS } from "../../constants/icons.ts";
+
+export interface WorkflowStepPartDisplayProps {
+  part: WorkflowStepPart;
+  isLast: boolean;
+}
+
+function formatStepDuration(durationMs?: number): string {
+  if (!durationMs || durationMs <= 0) return "";
+  return ` (${Math.max(1, Math.round(durationMs / 1000))}s)`;
+}
+
+function getStepStatusLabel(part: WorkflowStepPart): { icon: string; label: string; colorKey: "muted" | "success" | "error" | "warning" } {
+  switch (part.status) {
+    case "running":
+      return { icon: STATUS.active, label: "running", colorKey: "muted" };
+    case "completed":
+      return { icon: STATUS.success, label: "completed", colorKey: "success" };
+    case "error":
+      return { icon: STATUS.error, label: "error", colorKey: "error" };
+    case "skipped":
+      return { icon: STATUS.pending, label: "skipped", colorKey: "warning" };
+  }
+}
+
+export function WorkflowStepPartDisplay({ part }: WorkflowStepPartDisplayProps): React.ReactNode {
+  const colors = useThemeColors();
+  const status = getStepStatusLabel(part);
+  const color = colors[status.colorKey];
+
+  return (
+    <box flexDirection="column">
+      <text style={{ fg: color }}>
+        {`${MISC.separator} ${status.icon} Step: ${part.nodeName} ${status.label}${formatStepDuration(part.durationMs)} ${MISC.separator}`}
+      </text>
+    </box>
+  );
+}
+
+export default WorkflowStepPartDisplay;
diff --git a/src/ui/components/task-list-indicator.tsx b/src/ui/components/task-list-indicator.tsx
index 8ab20a49d1..a021105544 100644
--- a/src/ui/components/task-list-indicator.tsx
+++ b/src/ui/components/task-list-indicator.tsx
@@ -138,16 +138,28 @@ export function TaskListIndicator({
           ? ` › blocked by ${item.blockedBy!.map(id => id.startsWith("#") ? id : `#${id}`).join(", ")}`
           : "";
 
-        return (
+        return isActive ? (
+          // Active tasks use a row layout so the AnimatedBlinkIndicator
+          // lives in its own <text> node — OpenTUI re-renders it reliably
+          // when setInterval triggers a state change.
+          <box key={item.id ?? i} flexDirection="row">
+            <text wrapMode="none">
+              <span style={{ fg: themeColors.dim }}>{showConnector && i === 0 ? `${CONNECTOR.subStatus} ` : `${rail} `}</span>
+            </text>
+            <text><AnimatedBlinkIndicator color={color} speed={500} /></text>
+            <text wrapMode="none">
+              <span style={{ fg: contentColor }}>{` ${displayContent}`}</span>
+              {hasBlockers && (
+                <span style={{ fg: themeColors.muted }}>{blockersSuffix}</span>
+              )}
+            </text>
+          </box>
+        ) : (
           <text key={item.id ?? i} wrapMode="none">
             {/* Left rail */}
             <span style={{ fg: themeColors.dim }}>{showConnector && i === 0 ? `${CONNECTOR.subStatus} ` : `${rail} `}</span>
             {/* Status icon */}
-            {isActive ? (
-              <AnimatedBlinkIndicator color={color} speed={500} />
-            ) : (
-              <span style={{ fg: textColor }}>{icon}</span>
-            )}
+            <span style={{ fg: textColor }}>{icon}</span>
             {/* Content */}
             <span style={{ fg: contentColor }}>{` ${displayContent}`}</span>
             {/* Status label for active/error */}
diff --git a/src/ui/components/task-list-panel.tsx b/src/ui/components/task-list-panel.tsx
index 1f640aee6c..3497f24dc8 100644
--- a/src/ui/components/task-list-panel.tsx
+++ b/src/ui/components/task-list-panel.tsx
@@ -6,7 +6,7 @@
  * visual progress bar, numbered task rows, and status-aware styling.
  *
  * TaskListPanel: Persistent, file-driven wrapper that reads from tasks.json
- * via file watcher during /ralph workflow execution, feeding data to TaskListBox.
+ * via file watcher during workflow execution, feeding data to TaskListBox.
  *
  * Reference: specs/ralph-task-list-ui.md
  */
@@ -41,6 +41,8 @@ export interface TaskListPanelProps {
   sessionDir: string;
   /** Whether to show full task content without truncation */
   expanded?: boolean;
+  /** Whether the parent workflow is currently active */
+  workflowActive?: boolean;
 }
 
 // ============================================================================
@@ -151,12 +153,13 @@ export function TaskListBox({
 }
 
 // ============================================================================
-// TASK LIST PANEL (File-driven wrapper for /ralph workflow)
+// TASK LIST PANEL (File-driven wrapper for workflows)
 // ============================================================================
 
 export function TaskListPanel({
   sessionDir,
   expanded = false,
+  workflowActive = false,
 }: TaskListPanelProps): React.ReactNode {
   const [tasks, setTasks] = useState<TaskItem[]>([]);
 
@@ -169,7 +172,8 @@ export function TaskListPanel({
     return cleanup;
   }, [sessionDir]);
 
-  if (tasks.length === 0 || shouldAutoClearTaskPanel(tasks)) return null;
+  if (tasks.length === 0) return null;
+  if (!workflowActive && shouldAutoClearTaskPanel(tasks)) return null;
 
   return (
     <box flexDirection="column" paddingLeft={SPACING.INDENT} paddingRight={SPACING.INDENT} marginTop={SPACING.ELEMENT} flexShrink={0}>
diff --git a/src/ui/components/task-order.test.ts b/src/ui/components/task-order.test.ts
index 2e39cd8c4d..e53275f419 100644
--- a/src/ui/components/task-order.test.ts
+++ b/src/ui/components/task-order.test.ts
@@ -80,6 +80,19 @@ describe("sortTasksTopologically", () => {
     expect(sorted.map((t) => t.id)).toEqual(["#3", "#1", "#2"]);
   });
 
+  test("keeps dependency chains contiguous around in_progress items", () => {
+    const tasks: TaskItem[] = [
+      task("#3", "verify", ["#2"], "pending"),
+      task("#1", "plan", [], "completed"),
+      task("#2", "implement", ["#1"], "in_progress"),
+    ];
+
+    const sorted = sortTasksTopologically(tasks);
+
+    expect(sorted.map((t) => t.id)).toEqual(["#1", "#2", "#3"]);
+    expect(sorted[1]!.status).toBe("in_progress");
+  });
+
   test("appends tasks with missing or duplicate ids", () => {
     const tasks: TaskItem[] = [
       task("#1", "duplicate one"),
@@ -528,4 +541,3 @@ describe("detectDeadlock", () => {
     }
   });
 });
-
diff --git a/src/ui/components/task-order.ts b/src/ui/components/task-order.ts
index 2e126c0cdb..c4aa64171e 100644
--- a/src/ui/components/task-order.ts
+++ b/src/ui/components/task-order.ts
@@ -183,7 +183,7 @@ export function detectDeadlock(tasks: TaskItem[]): DeadlockDiagnostic {
  * Tasks with invalid dependency metadata (missing/duplicate IDs, unknown blockers,
  * or cycles) are appended at the end in their original relative order.
  */
-export function sortTasksTopologically(tasks: TaskItem[]): TaskItem[] {
+export function sortTasksTopologically<T extends TaskItem>(tasks: readonly T[]): T[] {
   if (tasks.length <= 1) return [...tasks];
 
   const normalizedIds = tasks.map((task) => normalizeTaskId(task.id));
diff --git a/src/ui/components/tool-result.tsx b/src/ui/components/tool-result.tsx
index 3174cad927..a5f0ea201b 100644
--- a/src/ui/components/tool-result.tsx
+++ b/src/ui/components/tool-result.tsx
@@ -17,7 +17,7 @@ import {
   type ToolRenderResult,
 } from "../tools/registry.ts";
 import { SkillLoadIndicator, type SkillLoadStatus } from "./skill-load-indicator.tsx";
-import type { ToolExecutionStatus } from "../hooks/use-streaming-state.ts";
+import type { ToolExecutionStatus } from "../parts/types.ts";
 import {
   MAIN_CHAT_TOOL_PREVIEW_LIMITS,
   getMainChatToolMaxLines,
@@ -44,6 +44,49 @@ export interface ToolSummary {
   count?: number;
 }
 
+function isTaskOutputToolName(toolName: string): boolean {
+  return toolName.trim().toLowerCase() === "taskoutput";
+}
+
+function resolveTaskOutputTarget(input: Record<string, unknown>): string {
+  const candidates = [
+    input.sub_agent_name,
+    input.subagent_name,
+    input.agent_name,
+    input.agent,
+    input.task_id,
+    input.taskId,
+  ];
+  for (const candidate of candidates) {
+    if (typeof candidate === "string" && candidate.trim().length > 0) {
+      return candidate.trim();
+    }
+  }
+  return "sub-agent";
+}
+
+function TaskOutputResult({
+  input,
+  status,
+}: {
+  input: Record<string, unknown>;
+  status: ToolExecutionStatus;
+}): React.ReactNode {
+  const { theme } = useTheme();
+  const target = resolveTaskOutputTarget(input);
+
+  return (
+    <box flexDirection="column">
+      <box flexDirection="row" gap={SPACING.ELEMENT}>
+        <StatusIndicator status={status} theme={theme} />
+        <text style={{ fg: theme.colors.accent }}>
+          {`TaskOutput: [${target}]`}
+        </text>
+      </box>
+    </box>
+  );
+}
+
 // ============================================================================
 // STATUS INDICATOR COMPONENT
 // ============================================================================
@@ -247,6 +290,10 @@ export function ToolResult({
   initialExpanded = false,
   maxCollapsedLines = 5,
 }: ToolResultProps): React.ReactNode {
+  if (isTaskOutputToolName(toolName)) {
+    return <TaskOutputResult input={input} status={status} />;
+  }
+
   // Skill tool: render SkillLoadIndicator directly, bypassing standard tool result layout
   const normalizedToolName = toolName.toLowerCase();
   if (normalizedToolName === "skill") {
diff --git a/src/ui/components/transcript-view.tsx b/src/ui/components/transcript-view.tsx
index 5474676740..a3d7fe2ec4 100644
--- a/src/ui/components/transcript-view.tsx
+++ b/src/ui/components/transcript-view.tsx
@@ -9,7 +9,6 @@ import React, { useMemo } from "react";
 import { useTheme } from "../theme.tsx";
 import { formatTranscript, type TranscriptLine, type TranscriptLineType } from "../utils/transcript-formatter.ts";
 import type { ChatMessage, StreamingMeta } from "../chat.tsx";
-import type { ParallelAgent } from "./parallel-agents-tree.tsx";
 import { SPACING } from "../constants/spacing.ts";
 
 // ============================================================================
@@ -19,7 +18,6 @@ import { SPACING } from "../constants/spacing.ts";
 export interface TranscriptViewProps {
   messages: ChatMessage[];
   liveThinkingText?: string;
-  liveParallelAgents?: ParallelAgent[];
   modelId?: string;
   isStreaming: boolean;
   streamingMeta?: StreamingMeta | null;
@@ -73,7 +71,6 @@ function getLineColor(type: TranscriptLineType, colors: ReturnType<typeof useThe
 export function TranscriptView({
   messages,
   liveThinkingText,
-  liveParallelAgents,
   modelId,
   isStreaming,
   streamingMeta,
@@ -84,11 +81,10 @@ export function TranscriptView({
   const transcriptLines = useMemo(() => formatTranscript({
     messages,
     liveThinkingText,
-    liveParallelAgents,
     streamingMeta,
     isStreaming,
     modelId,
-  }), [messages, liveThinkingText, liveParallelAgents, streamingMeta, isStreaming, modelId]);
+  }), [messages, liveThinkingText, streamingMeta, isStreaming, modelId]);
 
   return (
     <scrollbox
diff --git a/src/ui/copilot-parallel-subagent-tool-attribution.test.ts b/src/ui/copilot-parallel-subagent-tool-attribution.test.ts
new file mode 100644
index 0000000000..02accaf928
--- /dev/null
+++ b/src/ui/copilot-parallel-subagent-tool-attribution.test.ts
@@ -0,0 +1,455 @@
+/**
+ * Tests for Copilot SDK parallel sub-agent tool call attribution bug fix.
+ *
+ * Bug Description:
+ * When multiple Copilot sub-agents run in parallel, tool calls and counts were
+ * only showing up for the most recently started sub-agent. Earlier sub-agents
+ * showed no tool activity even though they were executing tools.
+ *
+ * Root Cause:
+ * 1. Copilot SDK client wasn't extracting parentToolCallId from tool events
+ * 2. UI layer used "most recently started running subagent" heuristic which
+ *    fails when multiple agents run simultaneously
+ *
+ * Fix:
+ * 1. Extract parentToolCallId from Copilot tool.execution_start/complete events
+ * 2. Use parentId to correctly attribute tool calls to their parent sub-agent
+ * 3. Fall back to "most recent" heuristic for SDKs without parentId (OpenCode/Claude)
+ *
+ * This test verifies:
+ * - Tool calls with parentId are attributed to the correct sub-agent
+ * - Tool counts increment correctly for each parallel sub-agent
+ * - currentTool is updated for the correct sub-agent
+ * - Fallback heuristic still works for events without parentId
+ */
+
+import { describe, expect, test } from "bun:test";
+
+// ============================================================================
+// TYPES (extracted from src/ui/components/parallel-agents-tree.tsx)
+// ============================================================================
+
+type AgentStatus = "pending" | "running" | "completed" | "error" | "background" | "interrupted";
+
+interface ParallelAgent {
+  id: string;
+  taskToolCallId?: string;
+  name: string;
+  task: string;
+  status: AgentStatus;
+  model?: string;
+  startedAt: string;
+  durationMs?: number;
+  background?: boolean;
+  error?: string;
+  result?: string;
+  toolUses?: number;
+  tokens?: number;
+  currentTool?: string;
+}
+
+// ============================================================================
+// TOOL ATTRIBUTION LOGIC (extracted from src/ui/index.ts)
+// ============================================================================
+
+interface ToolStartEvent {
+  toolName: string;
+  parentId?: string; // Copilot: parentToolCallId
+  sessionId?: string; // OpenCode: sub-agent session ID
+}
+
+/**
+ * Simulates the tool attribution logic from src/ui/index.ts (lines 729-770).
+ * 
+ * Returns the agent that should be credited with this tool call, or undefined
+ * if no matching agent is found.
+ */
+function findTargetAgentForTool(
+  parallelAgents: ParallelAgent[],
+  event: ToolStartEvent,
+  subagentSessionToAgentId: ReadonlyMap<string, string> = new Map(),
+): ParallelAgent | undefined {
+  const isBackground = (agent: ParallelAgent): boolean =>
+    agent.background === true || agent.status === "background";
+  const isAttributionCandidate = (agent: ParallelAgent): boolean =>
+    agent.status === "running" || agent.status === "pending" || isBackground(agent);
+
+  // Priority 1: Use parentId to find the parent sub-agent
+  if (event.parentId) {
+    const byParentId = parallelAgents.find(
+      (a) => isAttributionCandidate(a)
+        && (a.id === event.parentId || a.taskToolCallId === event.parentId)
+    );
+    if (byParentId) return byParentId;
+  }
+
+  // Priority 2: Use sub-agent session correlation for SDKs without parent IDs
+  if (event.sessionId) {
+    const mappedAgentId = subagentSessionToAgentId.get(event.sessionId);
+    if (mappedAgentId) {
+      const bySession = parallelAgents.find(
+        (a) => isAttributionCandidate(a) && a.id === mappedAgentId
+      );
+      if (bySession) return bySession;
+    }
+  }
+
+  // Priority 3: Fallback to most recently started active subagent
+  return [...parallelAgents]
+    .reverse()
+    .find((a) => isAttributionCandidate(a));
+}
+
+/**
+ * Applies a tool.start event to the parallel agents array.
+ */
+function applyToolStart(
+  parallelAgents: ParallelAgent[],
+  event: ToolStartEvent,
+  subagentSessionToAgentId: ReadonlyMap<string, string> = new Map(),
+): ParallelAgent[] {
+  const targetAgent = findTargetAgentForTool(parallelAgents, event, subagentSessionToAgentId);
+  if (!targetAgent) return parallelAgents;
+  if (targetAgent.background || targetAgent.status === "background") {
+    return parallelAgents;
+  }
+
+  return parallelAgents.map((a) =>
+    a.id === targetAgent.id
+      ? { 
+          ...a, 
+          currentTool: event.toolName, 
+          toolUses: (a.toolUses ?? 0) + 1 
+        }
+      : a
+  );
+}
+
+// ============================================================================
+// TESTS
+// ============================================================================
+
+describe("Copilot parallel sub-agent tool attribution", () => {
+  test("tool with parentId is attributed to correct sub-agent (not most recent)", () => {
+    // Setup: 3 parallel sub-agents all running
+    const agents: ParallelAgent[] = [
+      {
+        id: "subagent-1",
+        taskToolCallId: "task-1",
+        name: "codebase-analyzer",
+        task: "Analyze authentication flow",
+        status: "running",
+        startedAt: "2024-01-01T00:00:00Z",
+        toolUses: 0,
+      },
+      {
+        id: "subagent-2",
+        taskToolCallId: "task-2",
+        name: "codebase-locator",
+        task: "Find test files",
+        status: "running",
+        startedAt: "2024-01-01T00:00:01Z",
+        toolUses: 0,
+      },
+      {
+        id: "subagent-3",
+        taskToolCallId: "task-3",
+        name: "debugger",
+        task: "Investigate error",
+        status: "running",
+        startedAt: "2024-01-01T00:00:02Z",
+        toolUses: 0,
+      },
+    ];
+
+    // Tool event for subagent-1 (oldest agent, not most recent)
+    const toolEvent: ToolStartEvent = {
+      toolName: "grep",
+      parentId: "subagent-1",
+    };
+
+    const updated = applyToolStart(agents, toolEvent);
+
+    // Verify: Tool attributed to subagent-1, not subagent-3 (most recent)
+    expect(updated[0]?.toolUses).toBe(1);
+    expect(updated[0]?.currentTool).toBe("grep");
+    expect(updated[1]?.toolUses).toBe(0); // subagent-2 unchanged
+    expect(updated[2]?.toolUses).toBe(0); // subagent-3 unchanged
+  });
+
+  test("multiple tools with different parentIds are attributed correctly", () => {
+    const agents: ParallelAgent[] = [
+      {
+        id: "subagent-A",
+        taskToolCallId: "task-A",
+        name: "explore",
+        task: "Find API endpoints",
+        status: "running",
+        startedAt: "2024-01-01T00:00:00Z",
+        toolUses: 0,
+      },
+      {
+        id: "subagent-B",
+        taskToolCallId: "task-B",
+        name: "explore",
+        task: "Find database schema",
+        status: "running",
+        startedAt: "2024-01-01T00:00:01Z",
+        toolUses: 0,
+      },
+    ];
+
+    // Tool events for both sub-agents
+    let updated = applyToolStart(agents, { toolName: "grep", parentId: "subagent-A" });
+    updated = applyToolStart(updated, { toolName: "view", parentId: "subagent-A" });
+    updated = applyToolStart(updated, { toolName: "grep", parentId: "subagent-B" });
+    updated = applyToolStart(updated, { toolName: "glob", parentId: "subagent-B" });
+    updated = applyToolStart(updated, { toolName: "view", parentId: "subagent-B" });
+
+    // Verify: Each agent has correct tool count
+    expect(updated[0]?.toolUses).toBe(2); // subagent-A: 2 tools
+    expect(updated[0]?.currentTool).toBe("view"); // Last tool for A
+    expect(updated[1]?.toolUses).toBe(3); // subagent-B: 3 tools
+    expect(updated[1]?.currentTool).toBe("view"); // Last tool for B
+  });
+
+  test("parentId matches taskToolCallId (eager agent correlation)", () => {
+    // Scenario: Eager agent created from tool.start uses toolId as both
+    // id and taskToolCallId. Later, subagent.start updates the id but
+    // keeps taskToolCallId. Tool events use original toolCallId as parentId.
+    const agents: ParallelAgent[] = [
+      {
+        id: "real-subagent-id",
+        taskToolCallId: "tool_123",
+        name: "codebase-analyzer",
+        task: "Analyze code",
+        status: "running",
+        startedAt: "2024-01-01T00:00:00Z",
+        toolUses: 0,
+      },
+    ];
+
+    const toolEvent: ToolStartEvent = {
+      toolName: "bash",
+      parentId: "tool_123", // Matches taskToolCallId, not id
+    };
+
+    const updated = applyToolStart(agents, toolEvent);
+
+    expect(updated[0]?.toolUses).toBe(1);
+    expect(updated[0]?.currentTool).toBe("bash");
+  });
+
+  test("fallback to most recent active agent when parentId is missing (OpenCode/Claude)", () => {
+    const agents: ParallelAgent[] = [
+      {
+        id: "subagent-1",
+        name: "explore",
+        task: "Task 1",
+        status: "running",
+        startedAt: "2024-01-01T00:00:00Z",
+        toolUses: 0,
+      },
+      {
+        id: "subagent-2",
+        name: "explore",
+        task: "Task 2",
+        status: "running",
+        startedAt: "2024-01-01T00:00:01Z",
+        toolUses: 0,
+      },
+    ];
+
+    // Tool event WITHOUT parentId (OpenCode/Claude behavior)
+    const toolEvent: ToolStartEvent = {
+      toolName: "grep",
+      // parentId: undefined
+    };
+
+    const updated = applyToolStart(agents, toolEvent);
+
+    // Fallback: Most recent agent (subagent-2) gets the tool
+    expect(updated[0]?.toolUses).toBe(0);
+    expect(updated[1]?.toolUses).toBe(1);
+    expect(updated[1]?.currentTool).toBe("grep");
+  });
+
+  test("only running or background agents are considered", () => {
+    const agents: ParallelAgent[] = [
+      {
+        id: "subagent-1",
+        name: "explore",
+        task: "Task 1",
+        status: "completed", // Not running
+        startedAt: "2024-01-01T00:00:00Z",
+        toolUses: 5,
+      },
+      {
+        id: "subagent-2",
+        name: "explore",
+        task: "Task 2",
+        status: "running",
+        startedAt: "2024-01-01T00:00:01Z",
+        toolUses: 0,
+      },
+    ];
+
+    const toolEvent: ToolStartEvent = {
+      toolName: "view",
+      parentId: "subagent-1", // Points to completed agent
+    };
+
+    const updated = applyToolStart(agents, toolEvent);
+
+    // parentId match fails (agent not running), falls back to most recent
+    expect(updated[0]?.toolUses).toBe(5); // Unchanged
+    expect(updated[1]?.toolUses).toBe(1); // Fallback target
+  });
+
+  test("background agent tool events do not stream tool metadata", () => {
+    const agents: ParallelAgent[] = [
+      {
+        id: "bg-agent",
+        taskToolCallId: "bg-task",
+        name: "general-purpose",
+        task: "Long-running task",
+        status: "background",
+        background: true,
+        startedAt: "2024-01-01T00:00:00Z",
+        toolUses: 0,
+      },
+      {
+        id: "fg-agent",
+        name: "explore",
+        task: "Quick search",
+        status: "running",
+        startedAt: "2024-01-01T00:00:01Z",
+        toolUses: 0,
+      },
+    ];
+
+    const toolEvent: ToolStartEvent = {
+      toolName: "bash",
+      parentId: "bg-agent",
+    };
+
+    const updated = applyToolStart(agents, toolEvent);
+
+    // Background agent is attributed for filtering, but metadata is unchanged
+    expect(updated[0]?.toolUses).toBe(0);
+    expect(updated[0]?.currentTool).toBeUndefined();
+    expect(updated[1]?.toolUses).toBe(0);
+  });
+
+  test("session correlation attributes tool to the correct parallel branch", () => {
+    const agents: ParallelAgent[] = [
+      {
+        id: "subagent-A",
+        taskToolCallId: "task-A",
+        name: "codebase-locator",
+        task: "Locate APIs",
+        status: "running",
+        startedAt: "2024-01-01T00:00:00Z",
+        toolUses: 0,
+      },
+      {
+        id: "subagent-B",
+        taskToolCallId: "task-B",
+        name: "debugger",
+        task: "Analyze failures",
+        status: "running",
+        startedAt: "2024-01-01T00:00:01Z",
+        toolUses: 0,
+      },
+    ];
+
+    const sessionMap = new Map<string, string>([["ses_A", "subagent-A"]]);
+    const updated = applyToolStart(
+      agents,
+      { toolName: "rg", sessionId: "ses_A" },
+      sessionMap,
+    );
+
+    expect(updated[0]?.toolUses).toBe(1);
+    expect(updated[0]?.currentTool).toBe("rg");
+    expect(updated[1]?.toolUses).toBe(0);
+  });
+
+  test("no tool attribution when no running agents exist", () => {
+    const agents: ParallelAgent[] = [
+      {
+        id: "subagent-1",
+        name: "explore",
+        task: "Task 1",
+        status: "completed",
+        startedAt: "2024-01-01T00:00:00Z",
+        toolUses: 3,
+      },
+    ];
+
+    const toolEvent: ToolStartEvent = {
+      toolName: "grep",
+    };
+
+    const updated = applyToolStart(agents, toolEvent);
+
+    // No change - no running agents to attribute to
+    expect(updated).toEqual(agents);
+  });
+});
+
+describe("findTargetAgentForTool", () => {
+  test("returns undefined when agents array is empty", () => {
+    const result = findTargetAgentForTool([], { toolName: "grep" });
+    expect(result).toBeUndefined();
+  });
+
+  test("returns undefined when all agents are completed", () => {
+    const agents: ParallelAgent[] = [
+      {
+        id: "subagent-1",
+        name: "explore",
+        task: "Task",
+        status: "completed",
+        startedAt: "2024-01-01T00:00:00Z",
+      },
+    ];
+    const result = findTargetAgentForTool(agents, { toolName: "grep" });
+    expect(result).toBeUndefined();
+  });
+
+  test("returns agent when parentId matches id", () => {
+    const agents: ParallelAgent[] = [
+      {
+        id: "target-agent",
+        name: "explore",
+        task: "Task",
+        status: "running",
+        startedAt: "2024-01-01T00:00:00Z",
+      },
+    ];
+    const result = findTargetAgentForTool(agents, {
+      toolName: "grep",
+      parentId: "target-agent",
+    });
+    expect(result?.id).toBe("target-agent");
+  });
+
+  test("returns agent when parentId matches taskToolCallId", () => {
+    const agents: ParallelAgent[] = [
+      {
+        id: "real-id",
+        taskToolCallId: "tool-id",
+        name: "explore",
+        task: "Task",
+        status: "running",
+        startedAt: "2024-01-01T00:00:00Z",
+      },
+    ];
+    const result = findTargetAgentForTool(agents, {
+      toolName: "grep",
+      parentId: "tool-id",
+    });
+    expect(result?.id).toBe("real-id");
+  });
+});
diff --git a/src/ui/early-agent-completion.test.ts b/src/ui/early-agent-completion.test.ts
new file mode 100644
index 0000000000..d9d1dea5aa
--- /dev/null
+++ b/src/ui/early-agent-completion.test.ts
@@ -0,0 +1,188 @@
+/**
+ * Tests for early agent completion detection in stream.agent.complete handler
+ *
+ * Validates the eager deferred-completion resolution that fires inside the
+ * setParallelAgents updater when the last foreground agent completes.
+ * This avoids the slower React re-render → useEffect round-trip.
+ *
+ * The pattern under test (chat.tsx):
+ *   setParallelAgents((current) => {
+ *     const updated = current.map(…); // mark completing agent
+ *     if (pendingComplete && shouldFinalizeDeferredStream(updated, hasRunningTool)) {
+ *       queueMicrotask(() => pendingComplete());
+ *     }
+ *     return updated;
+ *   });
+ */
+
+import { describe, expect, test } from "bun:test";
+import type { ParallelAgent } from "./components/parallel-agents-tree.tsx";
+import {
+  hasActiveForegroundAgents,
+  shouldFinalizeDeferredStream,
+} from "./parts/guards.ts";
+
+// ---------------------------------------------------------------------------
+// Helpers — mirror the agent-update logic from the stream.agent.complete handler
+// ---------------------------------------------------------------------------
+
+function createAgent(overrides: Partial<ParallelAgent>): ParallelAgent {
+  return {
+    id: "agent-1",
+    name: "Test Agent",
+    task: "Test task",
+    status: "running",
+    startedAt: new Date(Date.now() - 2000).toISOString(),
+    background: false,
+    ...overrides,
+  };
+}
+
+/** Mirrors the map() inside setParallelAgents for stream.agent.complete */
+function applyAgentComplete(
+  agents: ParallelAgent[],
+  agentId: string,
+  success: boolean,
+): ParallelAgent[] {
+  return agents.map((agent) => {
+    if (agent.id !== agentId) return agent;
+    const startedAtMs = new Date(agent.startedAt).getTime();
+    return {
+      ...agent,
+      status: success ? ("completed" as const) : ("error" as const),
+      currentTool: undefined,
+      durationMs: Number.isFinite(startedAtMs)
+        ? Math.max(0, Date.now() - startedAtMs)
+        : agent.durationMs,
+    };
+  });
+}
+
+/**
+ * Simulates the early completion check inside the setParallelAgents updater.
+ * Returns true when deferred completion should be eagerly resolved.
+ */
+function shouldEagerlyResolve(
+  agents: ParallelAgent[],
+  completingAgentId: string,
+  success: boolean,
+  hasPendingComplete: boolean,
+  hasRunningTool: boolean,
+): boolean {
+  const updated = applyAgentComplete(agents, completingAgentId, success);
+  return hasPendingComplete && shouldFinalizeDeferredStream(updated, hasRunningTool);
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("Early agent completion detection", () => {
+  test("eagerly resolves when last foreground agent completes successfully", () => {
+    const agents = [createAgent({ id: "a1", status: "running" })];
+    expect(shouldEagerlyResolve(agents, "a1", true, true, false)).toBe(true);
+  });
+
+  test("eagerly resolves when last foreground agent errors", () => {
+    const agents = [createAgent({ id: "a1", status: "running" })];
+    expect(shouldEagerlyResolve(agents, "a1", false, true, false)).toBe(true);
+  });
+
+  test("does NOT resolve when another foreground agent is still running", () => {
+    const agents = [
+      createAgent({ id: "a1", status: "running" }),
+      createAgent({ id: "a2", status: "running" }),
+    ];
+    // Only a1 completes — a2 is still running
+    expect(shouldEagerlyResolve(agents, "a1", true, true, false)).toBe(false);
+  });
+
+  test("does NOT resolve when another foreground agent is pending", () => {
+    const agents = [
+      createAgent({ id: "a1", status: "running" }),
+      createAgent({ id: "a2", status: "pending" }),
+    ];
+    expect(shouldEagerlyResolve(agents, "a1", true, true, false)).toBe(false);
+  });
+
+  test("does NOT resolve when there is no pending completion", () => {
+    const agents = [createAgent({ id: "a1", status: "running" })];
+    expect(shouldEagerlyResolve(agents, "a1", true, false, false)).toBe(false);
+  });
+
+  test("does NOT resolve when tools are still running", () => {
+    const agents = [createAgent({ id: "a1", status: "running" })];
+    expect(shouldEagerlyResolve(agents, "a1", true, true, true)).toBe(false);
+  });
+
+  test("resolves when only background agents remain after last foreground completes", () => {
+    const agents = [
+      createAgent({ id: "fg1", status: "running", background: false }),
+      createAgent({ id: "bg1", status: "background", background: true }),
+    ];
+    expect(shouldEagerlyResolve(agents, "fg1", true, true, false)).toBe(true);
+  });
+
+  test("resolves when all other foreground agents are already terminal", () => {
+    const agents = [
+      createAgent({ id: "a1", status: "running" }),
+      createAgent({ id: "a2", status: "completed" }),
+      createAgent({ id: "a3", status: "error" }),
+    ];
+    expect(shouldEagerlyResolve(agents, "a1", true, true, false)).toBe(true);
+  });
+
+  test("resolves for mixed terminal + background agents", () => {
+    const agents = [
+      createAgent({ id: "fg1", status: "running", background: false }),
+      createAgent({ id: "fg2", status: "completed", background: false }),
+      createAgent({ id: "bg1", status: "background", background: true }),
+      createAgent({ id: "bg2", status: "running", background: true }),
+    ];
+    expect(shouldEagerlyResolve(agents, "fg1", true, true, false)).toBe(true);
+  });
+
+  test("does NOT resolve for non-existent agent id (no-op update)", () => {
+    const agents = [createAgent({ id: "a1", status: "running" })];
+    // "a2" doesn't exist — a1 stays running
+    expect(shouldEagerlyResolve(agents, "a2", true, true, false)).toBe(false);
+  });
+
+  test("resolves with empty agent list when pending completion exists", () => {
+    // Edge case: no agents at all, pending completion should resolve
+    expect(shouldEagerlyResolve([], "a1", true, true, false)).toBe(true);
+  });
+});
+
+describe("hasActiveForegroundAgents after agent completion update", () => {
+  test("returns false after sole foreground agent is marked completed", () => {
+    const agents = [createAgent({ id: "a1", status: "running" })];
+    const updated = applyAgentComplete(agents, "a1", true);
+    expect(hasActiveForegroundAgents(updated)).toBe(false);
+  });
+
+  test("returns true when one of two foreground agents completes", () => {
+    const agents = [
+      createAgent({ id: "a1", status: "running" }),
+      createAgent({ id: "a2", status: "running" }),
+    ];
+    const updated = applyAgentComplete(agents, "a1", true);
+    expect(hasActiveForegroundAgents(updated)).toBe(true);
+  });
+
+  test("returns false when background agents are the only remaining active ones", () => {
+    const agents = [
+      createAgent({ id: "fg1", status: "running", background: false }),
+      createAgent({ id: "bg1", status: "background", background: true }),
+    ];
+    const updated = applyAgentComplete(agents, "fg1", true);
+    expect(hasActiveForegroundAgents(updated)).toBe(false);
+  });
+
+  test("error status is treated as terminal", () => {
+    const agents = [createAgent({ id: "a1", status: "running" })];
+    const updated = applyAgentComplete(agents, "a1", false);
+    expect(updated[0]!.status).toBe("error");
+    expect(hasActiveForegroundAgents(updated)).toBe(false);
+  });
+});
diff --git a/src/ui/hooks/index.ts b/src/ui/hooks/index.ts
index 47f0fc19c9..cf19b230b7 100644
--- a/src/ui/hooks/index.ts
+++ b/src/ui/hooks/index.ts
@@ -6,32 +6,6 @@
  * Reference: Feature 14 - Create hooks module index with exports
  */
 
-// ============================================================================
-// USE STREAMING STATE
-// ============================================================================
-
-export {
-  // Hook
-  useStreamingState,
-  default as useStreamingStateDefault,
-
-  // Types
-  type StreamingState,
-  type ToolExecutionState,
-  type ToolExecutionStatus,
-  type ToolExecutionTimestamps,
-  type UseStreamingStateReturn,
-
-  // Utility functions
-  createInitialStreamingState,
-  generateToolExecutionId,
-  getCurrentTimestamp,
-  createToolExecution,
-  getActiveToolExecutions,
-  getCompletedToolExecutions,
-  getErroredToolExecutions,
-} from "./use-streaming-state.ts";
-
 // ============================================================================
 // USE MESSAGE QUEUE
 // ============================================================================
@@ -58,13 +32,3 @@ export {
   // Types
   type UseVerboseModeReturn,
 } from "./use-verbose-mode.ts";
-
-// ============================================================================
-// USE THROTTLED VALUE
-// ============================================================================
-
-export {
-  // Hook
-  useThrottledValue,
-  default as useThrottledValueDefault,
-} from "./use-throttled-value.ts";
diff --git a/src/ui/hooks/use-streaming-state.ts b/src/ui/hooks/use-streaming-state.ts
deleted file mode 100644
index b6c263350f..0000000000
--- a/src/ui/hooks/use-streaming-state.ts
+++ /dev/null
@@ -1,422 +0,0 @@
-/**
- * useStreamingState Hook for Real-time Updates
- *
- * Manages streaming state for chat interactions, including message
- * streaming, tool executions, and pending questions.
- *
- * Reference: Feature 13 - Create useStreamingState hook for real-time updates
- */
-
-import { useState, useCallback } from "react";
-import type { UserQuestion } from "../components/user-question-dialog.tsx";
-
-// ============================================================================
-// TYPES
-// ============================================================================
-
-/**
- * Status of a tool execution.
- */
-export type ToolExecutionStatus = "pending" | "running" | "completed" | "error" | "interrupted";
-
-/**
- * Timestamps for tool execution tracking.
- */
-export interface ToolExecutionTimestamps {
-  /** When the tool execution started */
-  startedAt: string;
-  /** When the tool execution completed (if completed) */
-  completedAt?: string;
-}
-
-/**
- * State for a single tool execution.
- */
-export interface ToolExecutionState {
-  /** Unique identifier for this tool execution */
-  id: string;
-  /** Name of the tool being executed */
-  toolName: string;
-  /** Current execution status */
-  status: ToolExecutionStatus;
-  /** Input parameters passed to the tool */
-  input: Record<string, unknown>;
-  /** Output from the tool (if completed) */
-  output?: unknown;
-  /** Error message (if status is 'error') */
-  error?: string;
-  /** Execution timestamps */
-  timestamps: ToolExecutionTimestamps;
-}
-
-/**
- * Overall streaming state for the chat interface.
- */
-export interface StreamingState {
-  /** Whether a message is currently being streamed */
-  isStreaming: boolean;
-  /** ID of the message currently being streamed */
-  streamingMessageId: string | null;
-  /** Map of active tool executions by ID */
-  toolExecutions: Map<string, ToolExecutionState>;
-  /** Queue of pending questions waiting for user input */
-  pendingQuestions: UserQuestion[];
-}
-
-/**
- * Return type for the useStreamingState hook.
- */
-export interface UseStreamingStateReturn {
-  /** Current streaming state */
-  state: StreamingState;
-  /** Start streaming a new message */
-  startStreaming: (messageId: string) => void;
-  /** Stop streaming the current message */
-  stopStreaming: () => void;
-  /** Handle a chunk of streamed content (returns the chunk for processing) */
-  handleChunk: (chunk: string) => string;
-  /** Handle tool execution start */
-  handleToolStart: (id: string, toolName: string, input: Record<string, unknown>) => void;
-  /** Handle tool execution completion */
-  handleToolComplete: (id: string, output: unknown) => void;
-  /** Handle tool execution error */
-  handleToolError: (id: string, error: string) => void;
-  /** Handle tool execution interruption */
-  handleToolInterrupt: (id: string) => void;
-  /** Add a pending question */
-  addPendingQuestion: (question: UserQuestion) => void;
-  /** Remove a pending question (after it's answered) */
-  removePendingQuestion: () => UserQuestion | undefined;
-  /** Clear all tool executions */
-  clearToolExecutions: () => void;
-  /** Reset all state to initial values */
-  reset: () => void;
-}
-
-// ============================================================================
-// INITIAL STATE
-// ============================================================================
-
-/**
- * Create initial streaming state.
- */
-export function createInitialStreamingState(): StreamingState {
-  return {
-    isStreaming: false,
-    streamingMessageId: null,
-    toolExecutions: new Map(),
-    pendingQuestions: [],
-  };
-}
-
-// ============================================================================
-// UTILITY FUNCTIONS
-// ============================================================================
-
-/**
- * Generate a unique tool execution ID.
- */
-export function generateToolExecutionId(): string {
-  return `tool_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`;
-}
-
-/**
- * Get current ISO timestamp.
- */
-export function getCurrentTimestamp(): string {
-  return new Date().toISOString();
-}
-
-/**
- * Create a new tool execution state.
- */
-export function createToolExecution(
-  id: string,
-  toolName: string,
-  input: Record<string, unknown>
-): ToolExecutionState {
-  return {
-    id,
-    toolName,
-    status: "running",
-    input,
-    timestamps: {
-      startedAt: getCurrentTimestamp(),
-    },
-  };
-}
-
-/**
- * Get all active (running) tool executions.
- */
-export function getActiveToolExecutions(
-  executions: Map<string, ToolExecutionState>
-): ToolExecutionState[] {
-  return Array.from(executions.values()).filter(
-    (exec) => exec.status === "running"
-  );
-}
-
-/**
- * Get all completed tool executions.
- */
-export function getCompletedToolExecutions(
-  executions: Map<string, ToolExecutionState>
-): ToolExecutionState[] {
-  return Array.from(executions.values()).filter(
-    (exec) => exec.status === "completed"
-  );
-}
-
-/**
- * Get all errored tool executions.
- */
-export function getErroredToolExecutions(
-  executions: Map<string, ToolExecutionState>
-): ToolExecutionState[] {
-  return Array.from(executions.values()).filter(
-    (exec) => exec.status === "error"
-  );
-}
-
-// ============================================================================
-// HOOK IMPLEMENTATION
-// ============================================================================
-
-/**
- * Hook for managing streaming state in the chat interface.
- *
- * Tracks message streaming, tool executions, and pending questions.
- * Provides callbacks for handling real-time updates from the AI.
- *
- * @returns Streaming state and handler callbacks
- *
- * @example
- * ```tsx
- * const {
- *   state,
- *   startStreaming,
- *   stopStreaming,
- *   handleChunk,
- *   handleToolStart,
- *   handleToolComplete,
- *   handleToolError,
- * } = useStreamingState();
- *
- * // Start streaming a message
- * startStreaming("msg_123");
- *
- * // Handle chunks as they arrive
- * const chunk = handleChunk("Hello");
- * appendToMessage(chunk);
- *
- * // Handle tool execution
- * handleToolStart("tool_1", "Read", { file: "test.ts" });
- * // ... tool executes ...
- * handleToolComplete("tool_1", { content: "file contents" });
- *
- * // Stop streaming when done
- * stopStreaming();
- * ```
- */
-export function useStreamingState(): UseStreamingStateReturn {
-  const [state, setState] = useState<StreamingState>(createInitialStreamingState);
-
-  /**
-   * Start streaming a new message.
-   */
-  const startStreaming = useCallback((messageId: string) => {
-    setState((prev) => ({
-      ...prev,
-      isStreaming: true,
-      streamingMessageId: messageId,
-    }));
-  }, []);
-
-  /**
-   * Stop streaming the current message.
-   */
-  const stopStreaming = useCallback(() => {
-    setState((prev) => ({
-      ...prev,
-      isStreaming: false,
-      streamingMessageId: null,
-    }));
-  }, []);
-
-  /**
-   * Handle a chunk of streamed content.
-   * Returns the chunk for the caller to process (e.g., append to message).
-   */
-  const handleChunk = useCallback((chunk: string): string => {
-    // No state update needed - just pass through the chunk
-    // The caller is responsible for updating message content
-    return chunk;
-  }, []);
-
-  /**
-   * Handle tool execution start.
-   */
-  const handleToolStart = useCallback(
-    (id: string, toolName: string, input: Record<string, unknown>) => {
-      setState((prev) => {
-        const newExecutions = new Map(prev.toolExecutions);
-        newExecutions.set(id, createToolExecution(id, toolName, input));
-        return {
-          ...prev,
-          toolExecutions: newExecutions,
-        };
-      });
-    },
-    []
-  );
-
-  /**
-   * Handle tool execution completion.
-   */
-  const handleToolComplete = useCallback((id: string, output: unknown) => {
-    setState((prev) => {
-      const newExecutions = new Map(prev.toolExecutions);
-      const existing = newExecutions.get(id);
-
-      if (existing) {
-        newExecutions.set(id, {
-          ...existing,
-          status: "completed",
-          output,
-          timestamps: {
-            ...existing.timestamps,
-            completedAt: getCurrentTimestamp(),
-          },
-        });
-      }
-
-      return {
-        ...prev,
-        toolExecutions: newExecutions,
-      };
-    });
-  }, []);
-
-  /**
-   * Handle tool execution error.
-   */
-  const handleToolError = useCallback((id: string, error: string) => {
-    setState((prev) => {
-      const newExecutions = new Map(prev.toolExecutions);
-      const existing = newExecutions.get(id);
-
-      if (existing) {
-        newExecutions.set(id, {
-          ...existing,
-          status: "error",
-          error,
-          timestamps: {
-            ...existing.timestamps,
-            completedAt: getCurrentTimestamp(),
-          },
-        });
-      }
-
-      return {
-        ...prev,
-        toolExecutions: newExecutions,
-      };
-    });
-  }, []);
-
-  /**
-   * Handle tool execution interruption.
-   */
-  const handleToolInterrupt = useCallback((id: string) => {
-    setState((prev) => {
-      const newExecutions = new Map(prev.toolExecutions);
-      const existing = newExecutions.get(id);
-
-      if (existing) {
-        newExecutions.set(id, {
-          ...existing,
-          status: "interrupted",
-          timestamps: {
-            ...existing.timestamps,
-            completedAt: getCurrentTimestamp(),
-          },
-        });
-      }
-
-      return {
-        ...prev,
-        toolExecutions: newExecutions,
-      };
-    });
-  }, []);
-
-  /**
-   * Add a pending question to the queue.
-   */
-  const addPendingQuestion = useCallback((question: UserQuestion) => {
-    setState((prev) => ({
-      ...prev,
-      pendingQuestions: [...prev.pendingQuestions, question],
-    }));
-  }, []);
-
-  /**
-   * Remove and return the first pending question from the queue.
-   */
-  const removePendingQuestion = useCallback((): UserQuestion | undefined => {
-    let removed: UserQuestion | undefined;
-
-    setState((prev) => {
-      if (prev.pendingQuestions.length === 0) {
-        return prev;
-      }
-
-      [removed] = prev.pendingQuestions;
-      return {
-        ...prev,
-        pendingQuestions: prev.pendingQuestions.slice(1),
-      };
-    });
-
-    return removed;
-  }, []);
-
-  /**
-   * Clear all tool executions.
-   */
-  const clearToolExecutions = useCallback(() => {
-    setState((prev) => ({
-      ...prev,
-      toolExecutions: new Map(),
-    }));
-  }, []);
-
-  /**
-   * Reset all state to initial values.
-   */
-  const reset = useCallback(() => {
-    setState(createInitialStreamingState());
-  }, []);
-
-  return {
-    state,
-    startStreaming,
-    stopStreaming,
-    handleChunk,
-    handleToolStart,
-    handleToolComplete,
-    handleToolError,
-    handleToolInterrupt,
-    addPendingQuestion,
-    removePendingQuestion,
-    clearToolExecutions,
-    reset,
-  };
-}
-
-// ============================================================================
-// EXPORTS
-// ============================================================================
-
-export default useStreamingState;
diff --git a/src/ui/hooks/use-throttled-value.test.ts b/src/ui/hooks/use-throttled-value.test.ts
deleted file mode 100644
index 673e8419b5..0000000000
--- a/src/ui/hooks/use-throttled-value.test.ts
+++ /dev/null
@@ -1,23 +0,0 @@
-/**
- * Tests for useThrottledValue hook
- * 
- * Note: These are basic validation tests. Full hook testing would require
- * a React testing environment with @testing-library/react.
- */
-import { describe, expect, test } from "bun:test";
-import { useThrottledValue } from "./use-throttled-value";
-
-describe("useThrottledValue", () => {
-  test("should export the hook function", () => {
-    expect(typeof useThrottledValue).toBe("function");
-  });
-
-  test("should accept at least one parameter", () => {
-    // Function length is 1 because intervalMs has a default value
-    expect(useThrottledValue.length).toBe(1);
-  });
-
-  test("should be a named export", () => {
-    expect(useThrottledValue.name).toBe("useThrottledValue");
-  });
-});
diff --git a/src/ui/hooks/use-throttled-value.ts b/src/ui/hooks/use-throttled-value.ts
deleted file mode 100644
index 66d12dfb67..0000000000
--- a/src/ui/hooks/use-throttled-value.ts
+++ /dev/null
@@ -1,47 +0,0 @@
-/**
- * useThrottledValue Hook
- *
- * Throttles rapid value updates to prevent UI thrashing during streaming.
- * Used primarily for TextPart content updates during rapid text deltas.
- *
- * Inspired by OpenCode's createThrottledValue() pattern.
- */
-
-import { useState, useEffect, useRef } from "react";
-
-/**
- * Returns a throttled version of the input value that updates at most
- * once per `intervalMs` milliseconds.
- *
- * @param value - The rapidly-changing source value
- * @param intervalMs - Minimum interval between updates (default: 100ms)
- * @returns The throttled value
- */
-export function useThrottledValue<T>(value: T, intervalMs: number = 100): T {
-  const [throttled, setThrottled] = useState(value);
-  const lastUpdateRef = useRef(0);
-  const pendingRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-
-  useEffect(() => {
-    const now = Date.now();
-    const elapsed = now - lastUpdateRef.current;
-    if (elapsed >= intervalMs) {
-      lastUpdateRef.current = now;
-      setThrottled(value);
-    } else {
-      if (pendingRef.current) clearTimeout(pendingRef.current);
-      pendingRef.current = setTimeout(() => {
-        lastUpdateRef.current = Date.now();
-        setThrottled(value);
-        pendingRef.current = null;
-      }, intervalMs - elapsed);
-    }
-    return () => {
-      if (pendingRef.current) clearTimeout(pendingRef.current);
-    };
-  }, [value, intervalMs]);
-
-  return throttled;
-}
-
-export default useThrottledValue;
diff --git a/src/ui/index.protocol-ordering.test.ts b/src/ui/index.protocol-ordering.test.ts
index 62f481d79d..c3dd20b6d8 100644
--- a/src/ui/index.protocol-ordering.test.ts
+++ b/src/ui/index.protocol-ordering.test.ts
@@ -18,7 +18,8 @@ interface ElementWithProps {
 
 function extractErrorBoundaryExit(rootElement: unknown): (() => void) | null {
   const themeProvider = rootElement as ElementWithProps;
-  const boundary = themeProvider.props?.children as ElementWithProps | undefined;
+  const eventBusProvider = themeProvider.props?.children as ElementWithProps | undefined;
+  const boundary = eventBusProvider?.props?.children as ElementWithProps | undefined;
   return boundary?.props?.onExit ?? null;
 }
 
diff --git a/src/ui/index.thinking-source-contract.test.ts b/src/ui/index.thinking-source-contract.test.ts
index 7a393a7382..6bc8b5ccc4 100644
--- a/src/ui/index.thinking-source-contract.test.ts
+++ b/src/ui/index.thinking-source-contract.test.ts
@@ -1,12 +1,16 @@
-import { describe, expect, mock, spyOn, test } from "bun:test";
+import { describe, expect, spyOn, test } from "bun:test";
 
 import type { CliRenderer } from "@opentui/core";
 import type { Root } from "@opentui/react";
 import * as opentuiCore from "@opentui/core";
 import * as opentuiReact from "@opentui/react";
 
-import type { AgentMessage, CodingAgentClient, Session } from "../sdk/types.ts";
-import type { ChatAppProps, StreamingMeta } from "./chat.tsx";
+import type {
+  AgentMessage,
+  CodingAgentClient,
+  Session,
+} from "../sdk/types.ts";
+import type { ChatAppProps } from "./chat.tsx";
 
 interface ElementWithProps {
   props?: {
@@ -14,30 +18,16 @@ interface ElementWithProps {
   };
 }
 
-interface StreamHarness {
-  onExit: NonNullable<ChatAppProps["onExit"]>;
-  onInterrupt: NonNullable<ChatAppProps["onInterrupt"]>;
-  onStreamMessage: NonNullable<ChatAppProps["onStreamMessage"]>;
+interface Harness {
+  chatAppProps: ChatAppProps;
   uiPromise: Promise<unknown>;
   restore: () => void;
 }
 
-type StreamIteratorResult = IteratorResult<AgentMessage, undefined>;
-
-interface ControlledAgentStream {
-  readonly iterable: AsyncIterable<AgentMessage>;
-  emit: (message: AgentMessage) => void;
-  end: () => void;
-}
-
-interface ControlledClientBundle {
-  client: CodingAgentClient;
-  streams: ControlledAgentStream[];
-}
-
 function extractChatAppProps(rootElement: unknown): ChatAppProps | null {
   const themeProvider = rootElement as ElementWithProps;
-  const boundary = themeProvider.props?.children as ElementWithProps | undefined;
+  const eventBusProvider = themeProvider.props?.children as ElementWithProps | undefined;
+  const boundary = eventBusProvider?.props?.children as ElementWithProps | undefined;
   const chatApp = boundary?.props?.children as { props?: ChatAppProps } | undefined;
   return chatApp?.props ?? null;
 }
@@ -50,15 +40,13 @@ async function waitFor(condition: () => boolean, attempts = 200): Promise<void>
   throw new Error("Condition not met in time");
 }
 
-function createFakeClient(streamMessages: AgentMessage[]): CodingAgentClient {
+function createClient(
+  streamImpl: (message: string, options?: { agent?: string }) => AsyncIterable<AgentMessage>,
+): CodingAgentClient {
   const session: Session = {
     id: "session-thinking-contract",
     send: async () => ({ type: "text", content: "", role: "assistant" }),
-    stream: async function* (): AsyncIterable<AgentMessage> {
-      for (const message of streamMessages) {
-        yield message;
-      }
-    },
+    stream: streamImpl,
     summarize: async () => {
       return;
     },
@@ -95,130 +83,7 @@ function createFakeClient(streamMessages: AgentMessage[]): CodingAgentClient {
   };
 }
 
-function createControlledAgentStream(): ControlledAgentStream {
-  const pending: StreamIteratorResult[] = [];
-  const resolvers: Array<(value: StreamIteratorResult) => void> = [];
-  let ended = false;
-
-  const flush = (result: StreamIteratorResult): void => {
-    const resolve = resolvers.shift();
-    if (resolve) {
-      resolve(result);
-      return;
-    }
-    pending.push(result);
-  };
-
-  const end = (): void => {
-    if (ended) {
-      return;
-    }
-    ended = true;
-    flush({ done: true, value: undefined });
-  };
-
-  const iterable: AsyncIterable<AgentMessage> = {
-    [Symbol.asyncIterator](): AsyncIterator<AgentMessage, undefined> {
-      return {
-        next(): Promise<StreamIteratorResult> {
-          if (pending.length > 0) {
-            const nextValue = pending.shift();
-            if (nextValue) {
-              return Promise.resolve(nextValue);
-            }
-          }
-          return new Promise<StreamIteratorResult>((resolve) => {
-            resolvers.push(resolve);
-          });
-        },
-        return(): Promise<IteratorReturnResult<undefined>> {
-          end();
-          return Promise.resolve({ done: true, value: undefined });
-        },
-      };
-    },
-  };
-
-  return {
-    iterable,
-    emit: (message: AgentMessage) => {
-      if (ended) {
-        return;
-      }
-      flush({ done: false, value: message });
-    },
-    end,
-  };
-}
-
-function createControlledClient(streamCount: number): ControlledClientBundle {
-  const streams = Array.from({ length: streamCount }, () => createControlledAgentStream());
-  let streamCallIndex = 0;
-  let activeStream: ControlledAgentStream | null = null;
-
-  const session: Session = {
-    id: "session-thinking-contract-controlled",
-    send: async () => ({ type: "text", content: "", role: "assistant" }),
-    stream: async function* (): AsyncIterable<AgentMessage> {
-      const stream = streams[streamCallIndex];
-      streamCallIndex += 1;
-      if (!stream) {
-        return;
-      }
-      activeStream = stream;
-      try {
-        for await (const message of stream.iterable) {
-          yield message;
-        }
-      } finally {
-        if (activeStream === stream) {
-          activeStream = null;
-        }
-      }
-    },
-    abort: async () => {
-      activeStream?.end();
-    },
-    summarize: async () => {
-      return;
-    },
-    getContextUsage: async () => ({
-      inputTokens: 0,
-      outputTokens: 0,
-      maxTokens: 1,
-      usagePercentage: 0,
-    }),
-    getSystemToolsTokens: () => 0,
-    destroy: async () => {
-      return;
-    },
-  };
-
-  return {
-    streams,
-    client: {
-      agentType: "claude",
-      createSession: async () => session,
-      resumeSession: async () => null,
-      on: () => () => {
-        return;
-      },
-      registerTool: () => {
-        return;
-      },
-      start: async () => {
-        return;
-      },
-      stop: async () => {
-        return;
-      },
-      getModelDisplayInfo: async () => ({ model: "test", tier: "test" }),
-      getSystemToolsTokens: () => null,
-    },
-  };
-}
-
-async function createStreamHarnessFromClient(client: CodingAgentClient): Promise<StreamHarness> {
+async function createHarness(client: CodingAgentClient): Promise<Harness> {
   let renderedTree: unknown = null;
 
   const fakeRenderer = {
@@ -236,30 +101,6 @@ async function createStreamHarnessFromClient(client: CodingAgentClient): Promise
     },
   } as Root;
 
-  mock.module("./chat.tsx", () => ({
-    ChatApp: () => null,
-    CompletionSummary: () => null,
-    LoadingIndicator: () => null,
-    StreamingBullet: () => null,
-    traceThinkingSourceLifecycle: () => {
-      return;
-    },
-    MAX_VISIBLE_MESSAGES: 100,
-    defaultWorkflowChatState: {},
-  }));
-
-  mock.module("./theme.tsx", () => ({
-    ThemeProvider: ({ children }: { children?: unknown }) => children ?? null,
-    useTheme: () => null,
-    useThemeColors: () => null,
-    darkTheme: { isDark: true },
-    lightTheme: { isDark: false },
-  }));
-
-  mock.module("./components/error-exit-screen.tsx", () => ({
-    AppErrorBoundary: ({ children }: { children?: unknown }) => children ?? null,
-  }));
-
   const createRendererSpy = spyOn(opentuiCore, "createCliRenderer").mockImplementation(
     (async () => fakeRenderer) as typeof opentuiCore.createCliRenderer,
   );
@@ -271,524 +112,87 @@ async function createStreamHarnessFromClient(client: CodingAgentClient): Promise
   try {
     const { startChatUI } = await import("./index.ts");
     const uiPromise = startChatUI(client);
-
     await waitFor(() => renderedTree !== null);
+
     const chatAppProps = extractChatAppProps(renderedTree);
     if (!chatAppProps?.onStreamMessage || !chatAppProps.onExit || !chatAppProps.onInterrupt) {
-      throw new Error("Failed to extract ChatApp stream callbacks");
+      throw new Error("Failed to extract ChatApp props");
     }
 
     return {
-      onExit: chatAppProps.onExit,
-      onInterrupt: chatAppProps.onInterrupt,
-      onStreamMessage: chatAppProps.onStreamMessage,
+      chatAppProps,
       uiPromise,
       restore: () => {
         createRendererSpy.mockRestore();
         createRootSpy.mockRestore();
-        mock.restore();
       },
     };
   } catch (error) {
     createRendererSpy.mockRestore();
     createRootSpy.mockRestore();
-    mock.restore();
     throw error;
   }
 }
 
-async function createStreamHarness(streamMessages: AgentMessage[]): Promise<StreamHarness> {
-  return createStreamHarnessFromClient(createFakeClient(streamMessages));
-}
-
-describe("startChatUI thinking source key contract", () => {
-  test("throws on thinking events that omit metadata.thinkingSourceKey", async () => {
-    const harness = await createStreamHarness([
-      {
-        type: "thinking",
-        content: "reasoning",
-        role: "assistant",
-        metadata: { provider: "claude" },
-      },
-    ]);
+describe("startChatUI stream contract", () => {
+  test("exposes callback-free onStreamMessage and removes legacy registration props", async () => {
+    const client = createClient(async function* () {
+      yield { type: "text", content: "ok", role: "assistant" };
+    });
+    const harness = await createHarness(client);
 
     try {
-      let onCompleteCalls = 0;
-      await expect(
-        harness.onStreamMessage("hello", () => {}, () => {
-          onCompleteCalls += 1;
-        }),
-      ).rejects.toThrow(
-        "Contract violation: thinking stream message is missing required metadata.thinkingSourceKey",
-      );
-      expect(onCompleteCalls).toBe(1);
+      expect(typeof harness.chatAppProps.onStreamMessage).toBe("function");
+      expect((harness.chatAppProps as Record<string, unknown>).registerToolStartHandler).toBeUndefined();
+      expect((harness.chatAppProps as Record<string, unknown>).registerToolCompleteHandler).toBeUndefined();
+      expect((harness.chatAppProps as Record<string, unknown>).registerPermissionRequestHandler).toBeUndefined();
+      expect((harness.chatAppProps as Record<string, unknown>).registerAskUserQuestionHandler).toBeUndefined();
+      expect((harness.chatAppProps as Record<string, unknown>).registerParallelAgentHandler).toBeUndefined();
     } finally {
-      await Promise.resolve(harness.onExit());
+      await Promise.resolve(harness.chatAppProps.onExit?.());
       await harness.uiPromise;
       harness.restore();
     }
   });
 
-  test("throws on thinking events with empty metadata.thinkingSourceKey", async () => {
-    const harness = await createStreamHarness([
-      {
-        type: "thinking",
-        content: "reasoning",
-        role: "assistant",
-        metadata: { provider: "claude", thinkingSourceKey: "   " },
-      },
-    ]);
+  test("passes stream options to session.stream", async () => {
+    let capturedOptions: { agent?: string } | undefined;
+    const client = createClient(async function* (_message: string, options?: { agent?: string }) {
+      capturedOptions = options;
+      yield { type: "text", content: "ok", role: "assistant" };
+    });
+    const harness = await createHarness(client);
 
     try {
       await expect(
-        harness.onStreamMessage("hello", () => {}, () => {
-          return;
-        }),
-      ).rejects.toThrow(
-        "Contract violation: thinking stream message is missing required metadata.thinkingSourceKey",
-      );
-    } finally {
-      await Promise.resolve(harness.onExit());
-      await harness.uiPromise;
-      harness.restore();
-    }
-  });
-
-  test("keeps non-thinking streams working without source identity", async () => {
-    const harness = await createStreamHarness([
-      {
-        type: "text",
-        content: "hello ",
-        role: "assistant",
-      },
-      {
-        type: "text",
-        content: "world",
-        role: "assistant",
-      },
-    ]);
-
-    try {
-      const chunks: string[] = [];
-      let onCompleteCalls = 0;
-      await expect(
-        harness.onStreamMessage(
-          "hello",
-          (chunk) => {
-            chunks.push(chunk);
-          },
-          () => {
-            onCompleteCalls += 1;
-          },
-        ),
+        harness.chatAppProps.onStreamMessage?.("hello", { agent: "codebase-analyzer" }),
       ).resolves.toBeUndefined();
-
-      expect(chunks.join("")).toBe("hello world");
-      expect(onCompleteCalls).toBe(1);
+      expect(capturedOptions?.agent).toBe("codebase-analyzer");
     } finally {
-      await Promise.resolve(harness.onExit());
+      await Promise.resolve(harness.chatAppProps.onExit?.());
       await harness.uiPromise;
       harness.restore();
     }
   });
 
-  test("preserves thinking metadata behavior when source identity is present", async () => {
-    const sourceKey = "claude:block-0";
-    const harness = await createStreamHarness([
-      {
+  test("accepts thinking streams without callback metadata hooks", async () => {
+    const client = createClient(async function* () {
+      yield {
         type: "thinking",
-        content: "analyzing",
-        role: "assistant",
-        metadata: {
-          provider: "claude",
-          thinkingSourceKey: sourceKey,
-          streamGeneration: 7,
-          targetMessageId: "msg-1",
-        },
-      },
-      {
-        type: "text",
-        content: "done",
-        role: "assistant",
-      },
-    ]);
-
-    try {
-      const metaEvents: StreamingMeta[] = [];
-
-      await expect(
-        harness.onStreamMessage(
-          "hello",
-          () => {
-            return;
-          },
-          () => {
-            return;
-          },
-          (meta) => {
-            metaEvents.push(meta);
-          },
-        ),
-      ).resolves.toBeUndefined();
-
-      const thinkingMeta = metaEvents.find((meta) => meta.thinkingSourceKey === sourceKey);
-      expect(thinkingMeta).toBeDefined();
-      if (!thinkingMeta) {
-        throw new Error("Expected thinking metadata event");
-      }
-      expect(thinkingMeta.thinkingTextBySource?.[sourceKey]).toBe("analyzing");
-      expect(thinkingMeta.thinkingGenerationBySource?.[sourceKey]).toBe(7);
-      expect(thinkingMeta.thinkingMessageBySource?.[sourceKey]).toBe("msg-1");
-    } finally {
-      await Promise.resolve(harness.onExit());
-      await harness.uiPromise;
-      harness.restore();
-    }
-  });
-
-  test("keeps source message binding stable when later chunks omit message IDs", async () => {
-    const sourceKey = "copilot:reasoning_7";
-    const harness = await createStreamHarness([
-      {
-        type: "thinking",
-        content: "step one",
-        role: "assistant",
-        metadata: {
-          provider: "copilot",
-          thinkingSourceKey: sourceKey,
-          streamGeneration: 4,
-          messageId: "msg-fallback",
-        },
-      },
-      {
-        type: "thinking",
-        content: " + step two",
-        role: "assistant",
-        metadata: {
-          provider: "copilot",
-          thinkingSourceKey: sourceKey,
-          streamGeneration: 4,
-        },
-      },
-      {
-        type: "text",
-        content: "done",
-        role: "assistant",
-      },
-    ]);
-
-    try {
-      const metaEvents: StreamingMeta[] = [];
-
-      await expect(
-        harness.onStreamMessage(
-          "hello",
-          () => {
-            return;
-          },
-          () => {
-            return;
-          },
-          (meta) => {
-            metaEvents.push(meta);
-          },
-        ),
-      ).resolves.toBeUndefined();
-
-      const thinkingMeta = [...metaEvents]
-        .reverse()
-        .find((meta) => meta.thinkingSourceKey === sourceKey);
-      expect(thinkingMeta).toBeDefined();
-      if (!thinkingMeta) {
-        throw new Error("Expected source-bound thinking metadata event");
-      }
-
-      expect(thinkingMeta.thinkingTextBySource?.[sourceKey]).toBe("step one + step two");
-      expect(thinkingMeta.thinkingGenerationBySource?.[sourceKey]).toBe(4);
-      expect(thinkingMeta.thinkingMessageBySource?.[sourceKey]).toBe("msg-fallback");
-    } finally {
-      await Promise.resolve(harness.onExit());
-      await harness.uiPromise;
-      harness.restore();
-    }
-  });
-
-  test("keeps generation and message bindings isolated across sources", async () => {
-    const sourceA = "claude:block-0";
-    const sourceB = "opencode:reasoning_part_9";
-    const harness = await createStreamHarness([
-      {
-        type: "thinking",
-        content: "alpha",
-        role: "assistant",
-        metadata: {
-          provider: "claude",
-          thinkingSourceKey: sourceA,
-          streamGeneration: 11,
-          targetMessageId: "msg-a",
-        },
-      },
-      {
-        type: "thinking",
-        content: "beta",
-        role: "assistant",
-        metadata: {
-          provider: "opencode",
-          thinkingSourceKey: sourceB,
-          streamGeneration: 12,
-          targetMessageId: "msg-b",
-        },
-      },
-      {
-        type: "text",
-        content: "done",
-        role: "assistant",
-      },
-    ]);
-
-    try {
-      const metaEvents: StreamingMeta[] = [];
-
-      await expect(
-        harness.onStreamMessage(
-          "hello",
-          () => {
-            return;
-          },
-          () => {
-            return;
-          },
-          (meta) => {
-            metaEvents.push(meta);
-          },
-        ),
-      ).resolves.toBeUndefined();
-
-      const thinkingMeta = [...metaEvents]
-        .reverse()
-        .find((meta) => meta.thinkingSourceKey === sourceB);
-      expect(thinkingMeta).toBeDefined();
-      if (!thinkingMeta) {
-        throw new Error("Expected multi-source thinking metadata event");
-      }
-
-      expect(thinkingMeta.thinkingTextBySource?.[sourceA]).toBe("alpha");
-      expect(thinkingMeta.thinkingTextBySource?.[sourceB]).toBe("beta");
-      expect(thinkingMeta.thinkingGenerationBySource?.[sourceA]).toBe(11);
-      expect(thinkingMeta.thinkingGenerationBySource?.[sourceB]).toBe(12);
-      expect(thinkingMeta.thinkingMessageBySource?.[sourceA]).toBe("msg-a");
-      expect(thinkingMeta.thinkingMessageBySource?.[sourceB]).toBe("msg-b");
-    } finally {
-      await Promise.resolve(harness.onExit());
-      await harness.uiPromise;
-      harness.restore();
-    }
-  });
-
-  test("regression: aggregates interleaved thinking chunks per source without concatenation bleed", async () => {
-    const sourceA = "claude:block-0";
-    const sourceB = "opencode:reasoning_1";
-    const harness = await createStreamHarness([
-      {
-        type: "thinking",
-        content: "alpha-1 ",
-        role: "assistant",
-        metadata: {
-          provider: "claude",
-          thinkingSourceKey: sourceA,
-          streamGeneration: 9,
-          targetMessageId: "msg-a",
-        },
-      },
-      {
-        type: "thinking",
-        content: "beta-1 ",
-        role: "assistant",
-        metadata: {
-          provider: "opencode",
-          thinkingSourceKey: sourceB,
-          streamGeneration: 10,
-          targetMessageId: "msg-b",
-        },
-      },
-      {
-        type: "thinking",
-        content: "alpha-2",
-        role: "assistant",
-        metadata: {
-          provider: "claude",
-          thinkingSourceKey: sourceA,
-          streamGeneration: 9,
-          targetMessageId: "msg-a",
-        },
-      },
-      {
-        type: "thinking",
-        content: "beta-2",
-        role: "assistant",
-        metadata: {
-          provider: "opencode",
-          thinkingSourceKey: sourceB,
-          streamGeneration: 10,
-          targetMessageId: "msg-b",
-        },
-      },
-      {
-        type: "text",
-        content: "final",
+        content: "reasoning",
         role: "assistant",
-      },
-    ]);
+        metadata: { provider: "claude", thinkingSourceKey: "source:1" },
+      };
+      yield { type: "text", content: "done", role: "assistant" };
+    });
+    const harness = await createHarness(client);
 
     try {
-      const metaEvents: StreamingMeta[] = [];
-
       await expect(
-        harness.onStreamMessage(
-          "hello",
-          () => {
-            return;
-          },
-          () => {
-            return;
-          },
-          (meta) => {
-            metaEvents.push(meta);
-          },
-        ),
+        harness.chatAppProps.onStreamMessage?.("hello"),
       ).resolves.toBeUndefined();
-
-      const latest = [...metaEvents]
-        .reverse()
-        .find((meta) => meta.thinkingSourceKey === sourceB);
-      expect(latest).toBeDefined();
-      if (!latest) {
-        throw new Error("Expected interleaved thinking metadata event");
-      }
-
-      expect(latest.thinkingTextBySource?.[sourceA]).toBe("alpha-1 alpha-2");
-      expect(latest.thinkingTextBySource?.[sourceB]).toBe("beta-1 beta-2");
-      expect(latest.thinkingTextBySource?.[sourceA]).not.toContain("beta");
-      expect(latest.thinkingTextBySource?.[sourceB]).not.toContain("alpha");
-      expect(latest.thinkingGenerationBySource?.[sourceA]).toBe(9);
-      expect(latest.thinkingGenerationBySource?.[sourceB]).toBe(10);
-      expect(latest.thinkingMessageBySource?.[sourceA]).toBe("msg-a");
-      expect(latest.thinkingMessageBySource?.[sourceB]).toBe("msg-b");
-    } finally {
-      await Promise.resolve(harness.onExit());
-      await harness.uiPromise;
-      harness.restore();
-    }
-  });
-
-  test("interrupt handoff drops stale late thinking and keeps next stream isolated", async () => {
-    const { client, streams } = createControlledClient(2);
-    const firstStream = streams[0];
-    const secondStream = streams[1];
-    if (!firstStream || !secondStream) {
-      throw new Error("Expected two controlled streams");
-    }
-
-    const harness = await createStreamHarnessFromClient(client);
-
-    try {
-      const firstMetaEvents: StreamingMeta[] = [];
-      let firstCompleteCalls = 0;
-
-      const firstPromise = harness.onStreamMessage(
-        "first",
-        () => {
-          return;
-        },
-        () => {
-          firstCompleteCalls += 1;
-        },
-        (meta) => {
-          firstMetaEvents.push(meta);
-        },
-      );
-
-      firstStream.emit({
-        type: "thinking",
-        content: "old-thought",
-        role: "assistant",
-        metadata: {
-          provider: "claude",
-          thinkingSourceKey: "source:old",
-          streamGeneration: 1,
-          targetMessageId: "msg-old",
-        },
-      });
-
-      await waitFor(() => firstMetaEvents.length === 1);
-
-      harness.onInterrupt();
-
-      firstStream.emit({
-        type: "thinking",
-        content: "+late-old",
-        role: "assistant",
-        metadata: {
-          provider: "claude",
-          thinkingSourceKey: "source:old",
-          streamGeneration: 1,
-          targetMessageId: "msg-old",
-        },
-      });
-      firstStream.end();
-      await firstPromise;
-
-      const secondMetaEvents: StreamingMeta[] = [];
-
-      const secondPromise = harness.onStreamMessage(
-        "second",
-        () => {
-          return;
-        },
-        () => {
-          return;
-        },
-        (meta) => {
-          secondMetaEvents.push(meta);
-        },
-      );
-
-      secondStream.emit({
-        type: "thinking",
-        content: "new-thought",
-        role: "assistant",
-        metadata: {
-          provider: "copilot",
-          thinkingSourceKey: "source:new",
-          streamGeneration: 2,
-          targetMessageId: "msg-new",
-        },
-      });
-      secondStream.emit({
-        type: "text",
-        content: "done",
-        role: "assistant",
-      });
-      secondStream.end();
-      await secondPromise;
-
-      expect(firstCompleteCalls).toBe(1);
-      expect(firstMetaEvents).toHaveLength(1);
-
-      const secondThinkingMeta = [...secondMetaEvents]
-        .reverse()
-        .find((meta) => meta.thinkingSourceKey === "source:new");
-      expect(secondThinkingMeta).toBeDefined();
-      if (!secondThinkingMeta) {
-        throw new Error("Expected next-stream thinking metadata");
-      }
-
-      expect(secondThinkingMeta.thinkingTextBySource?.["source:new"]).toBe("new-thought");
-      expect(secondThinkingMeta.thinkingTextBySource?.["source:old"]).toBeUndefined();
-      expect(secondThinkingMeta.thinkingGenerationBySource?.["source:old"]).toBeUndefined();
-      expect(secondThinkingMeta.thinkingMessageBySource?.["source:old"]).toBeUndefined();
     } finally {
-      await Promise.resolve(harness.onExit());
+      await Promise.resolve(harness.chatAppProps.onExit?.());
       await harness.uiPromise;
       harness.restore();
     }
diff --git a/src/ui/index.ts b/src/ui/index.ts
index c581e20523..c1c9acb6ab 100644
--- a/src/ui/index.ts
+++ b/src/ui/index.ts
@@ -12,22 +12,14 @@ import { createCliRenderer, type CliRenderer } from "@opentui/core";
 import { createRoot, type Root } from "@opentui/react";
 import {
   ChatApp,
-  type StreamingMeta,
-  type OnToolStart,
-  type OnToolComplete,
-  type OnSkillInvoked,
-  type OnPermissionRequest as ChatOnPermissionRequest,
-  type OnInterrupt,
   type OnTerminateBackgroundAgents,
-  type OnAskUserQuestion,
   type CommandExecutionTelemetry,
   type MessageSubmitTelemetry,
-  traceThinkingSourceLifecycle,
 } from "./chat.tsx";
-import type { ParallelAgent } from "./components/parallel-agents-tree.tsx";
 import { ThemeProvider, darkTheme, type Theme } from "./theme.tsx";
 import { AppErrorBoundary } from "./components/error-exit-screen.tsx";
 import { initializeCommandsAsync, globalRegistry } from "./commands/index.ts";
+import { EventBusProvider } from "../events/event-bus-provider.tsx";
 import type {
   CodingAgentClient,
   SessionConfig,
@@ -35,14 +27,21 @@ import type {
   AgentMessage,
 } from "../sdk/types.ts";
 import { UnifiedModelOperations } from "../models/model-operations.ts";
-import { parseTaskToolResult } from "./tools/registry.ts";
-import { normalizeMarkdownNewlines } from "./utils/format.ts";
 import {
   createTuiTelemetrySessionTracker,
   type TuiTelemetrySessionTracker,
 } from "../telemetry/index.ts";
-import { shouldFinalizeOnToolComplete } from "./parts/index.ts";
-import { getActiveBackgroundAgents, isBackgroundAgent } from "./utils/background-agent-footer.ts";
+import { EventBus } from "../events/event-bus.ts";
+import { BatchDispatcher } from "../events/batch-dispatcher.ts";
+import { OpenCodeStreamAdapter } from "../events/adapters/opencode-adapter.ts";
+import { ClaudeStreamAdapter } from "../events/adapters/claude-adapter.ts";
+import { CopilotStreamAdapter } from "../events/adapters/copilot-adapter.ts";
+import type { SDKStreamAdapter } from "../events/adapters/types.ts";
+import { registerAgentToolNames } from "./tools/registry.ts";
+import { attachDebugSubscriber } from "../events/debug-subscriber.ts";
+import { cleanupMcpBridgeScripts } from "../sdk/tools/opencode-mcp-bridge.ts";
+
+const FLUSH_FRAME_MS = 16;
 
 /**
  * Build a system prompt section describing all registered capabilities.
@@ -141,19 +140,6 @@ export interface ChatUIResult {
   duration: number;
 }
 
-/**
- * Handler for permission/HITL requests
- */
-export type OnPermissionRequest = (
-  requestId: string,
-  toolName: string,
-  question: string,
-  options: Array<{ label: string; value: string; description?: string }>,
-  respond: (answer: string | string[]) => void,
-  header?: string,
-  toolCallId?: string
-) => void;
-
 /**
  * Internal state for managing the chat UI lifecycle.
  */
@@ -164,40 +150,14 @@ interface ChatUIState {
   startTime: number;
   messageCount: number;
   cleanupHandlers: (() => void)[];
-  /** Registered handler for tool start events */
-  toolStartHandler: OnToolStart | null;
-  /** Registered handler for tool complete events */
-  toolCompleteHandler: OnToolComplete | null;
-  /** Registered handler for skill invoked events */
-  skillInvokedHandler: OnSkillInvoked | null;
-  /** Registered handler for permission/HITL requests */
-  permissionRequestHandler: OnPermissionRequest | null;
-  /** Registered handler for askUserQuestion events from workflow graphs */
-  askUserQuestionHandler: OnAskUserQuestion | null;
-  /** Tool ID counter for generating unique IDs */
-  toolIdCounter: number;
   /** Interrupt counter for double-press exit (shared between signal and UI) */
   interruptCount: number;
   /** Interrupt timeout ID */
   interruptTimeout: ReturnType<typeof setTimeout> | null;
-  /** Ctrl+C press state for double-press exit (deprecated, kept for signal handler compat) */
-  ctrlCPressed: boolean;
-  /** Ctrl+C timeout ID (deprecated, kept for signal handler compat) */
-  ctrlCTimeout: ReturnType<typeof setTimeout> | null;
-  /** Callback to show Ctrl+C warning in UI */
-  showCtrlCWarning: ((show: boolean) => void) | null;
-  /** Whether tool events are being received via hooks (to avoid duplicates from stream) */
-  toolEventsViaHooks: boolean;
-  /** Set of active tool IDs (for deduplication of duplicate events) */
-  activeToolIds: Set<string>;
   /** AbortController for the current stream (to interrupt on Escape/Ctrl+C) */
   streamAbortController: AbortController | null;
   /** Whether streaming is currently active */
   isStreaming: boolean;
-  /** Registered handler for parallel agent updates (from ChatApp's setParallelAgents) */
-  parallelAgentHandler: ((agents: ParallelAgent[]) => void) | null;
-  /** Current list of parallel agents tracked from SDK events */
-  parallelAgents: ParallelAgent[];
   /** Session IDs owned by this TUI instance (main + spawned subagent sessions) */
   ownedSessionIds: Set<string>;
   /** Promise lock to prevent concurrent session creation */
@@ -206,61 +166,14 @@ interface ChatUIState {
   runCounter: number;
   /** Active stream run owner ID. Null means no run currently owns hook events. */
   currentRunId: number | null;
-  /**
-   * Hook-scoped reset callback installed by subscribeToToolEvents().
-   * Clears correlation maps and live parallel tree state.
-   */
-  resetParallelTracking: ((reason: string) => void) | null;
-  /**
-   * Suppress streaming text that is a raw JSON echo of the Task tool result.
-   * When set, holds the result text so suppression is content-aware.
-   * Reset when the model produces non-echo text or starts a new tool.
-   */
-  suppressPostTaskResult: string | null;
   /** Native TUI telemetry tracker (null when telemetry is disabled or agent type is unknown) */
   telemetryTracker: TuiTelemetrySessionTracker | null;
-}
-
-function clearParallelAgents(state: ChatUIState) {
-  state.parallelAgents = [];
-  state.parallelAgentHandler?.(state.parallelAgents);
-}
-
-/**
- * Wraps an AsyncIterable so that each `iterator.next()` call races against an
- * AbortSignal. This ensures that abort takes effect immediately even while the
- * iterator is blocked waiting on the network (e.g. Claude extended thinking,
- * OpenCode 30s timeout, Copilot infinite wait).
- */
-async function* abortableAsyncIterable<T>(
-  iterable: AsyncIterable<T>,
-  signal: AbortSignal
-): AsyncGenerator<T> {
-  const iterator = iterable[Symbol.asyncIterator]();
-  const abortPromise = new Promise<never>((_, reject) => {
-    if (signal.aborted) {
-      reject(new DOMException("The operation was aborted", "AbortError"));
-      return;
-    }
-    signal.addEventListener(
-      "abort",
-      () => {
-        reject(new DOMException("The operation was aborted", "AbortError"));
-      },
-      { once: true }
-    );
-  });
-  try {
-    while (true) {
-      const result = await Promise.race([iterator.next(), abortPromise]);
-      if (result.done) break;
-      yield result.value;
-    }
-  } finally {
-    // Fire-and-forget: don't block abort propagation on iterator cleanup
-    // (SDK stream teardown may involve network I/O)
-    void iterator.return?.();
-  }
+  /** Singleton event bus shared across all streams */
+  bus: EventBus;
+  /** Singleton batch dispatcher for frame-aligned event batching */
+  dispatcher: BatchDispatcher;
+  /** Whether background agents were terminated via Ctrl+F (pending notification to model) */
+  backgroundAgentsTerminated: boolean;
 }
 
 // ============================================================================
@@ -327,6 +240,29 @@ export async function startChatUI(
       : undefined;
   const modelOps = agentType ? new UnifiedModelOperations(agentType, sdkSetModel, sdkListModels, sessionConfig?.model) : undefined;
 
+  // Initialize singleton event bus and batch dispatcher.
+  // Runtime validation is expensive on high-frequency streaming events,
+  // so keep it opt-in for diagnostics.
+  const sharedBus = new EventBus({
+    validatePayloads: process.env.ATOMIC_VALIDATE_BUS_EVENTS === "1",
+  });
+  const sharedDispatcher = new BatchDispatcher(
+    sharedBus,
+    FLUSH_FRAME_MS,
+  );
+
+  // Attach file-based debug subscriber when stream debug logging is enabled.
+  const debugSub = await attachDebugSubscriber(sharedBus);
+  if (debugSub.logDirPath) {
+    console.info(`[Atomic] Stream debug logs: ${debugSub.logDirPath}`);
+    if (debugSub.logPath) {
+      console.info(`[Atomic] Stream events log: ${debugSub.logPath}`);
+    }
+    if (debugSub.rawLogPath) {
+      console.info(`[Atomic] Stream raw log: ${debugSub.rawLogPath}`);
+    }
+  }
+
   // Initialize state
   const state: ChatUIState = {
     renderer: null,
@@ -335,29 +271,14 @@ export async function startChatUI(
     startTime: Date.now(),
     messageCount: 0,
     cleanupHandlers: [],
-    toolStartHandler: null,
-    toolCompleteHandler: null,
-    skillInvokedHandler: null,
-    permissionRequestHandler: null,
-    askUserQuestionHandler: null,
-    toolIdCounter: 0,
     interruptCount: 0,
     interruptTimeout: null,
-    ctrlCPressed: false,
-    ctrlCTimeout: null,
-    showCtrlCWarning: null,
-    toolEventsViaHooks: false,
-    activeToolIds: new Set(),
     streamAbortController: null,
     isStreaming: false,
-    parallelAgentHandler: null,
-    parallelAgents: [],
     ownedSessionIds: new Set(),
     sessionCreationPromise: null,
     runCounter: 0,
     currentRunId: null,
-    resetParallelTracking: null,
-    suppressPostTaskResult: null,
     telemetryTracker: agentType
       ? createTuiTelemetrySessionTracker({
         agentType,
@@ -365,6 +286,9 @@ export async function startChatUI(
         hasInitialPrompt: !!initialPrompt,
       })
       : null,
+    bus: sharedBus,
+    dispatcher: sharedDispatcher,
+    backgroundAgentsTerminated: false,
   };
 
   // Create a promise that resolves when the UI exits
@@ -379,7 +303,14 @@ export async function startChatUI(
   async function cleanup(): Promise<void> {
     state.currentRunId = null;
     state.isStreaming = false;
-    state.resetParallelTracking?.("cleanup");
+
+    // Dispose event bus infrastructure
+    await debugSub.unsubscribe();
+    state.dispatcher.dispose();
+    state.bus.clear();
+
+    // Remove generated MCP bridge scripts
+    cleanupMcpBridgeScripts();
 
     // Remove signal handlers
     for (const handler of state.cleanupHandlers) {
@@ -458,789 +389,6 @@ export async function startChatUI(
     state.messageCount++;
   }
 
-  /**
-   * Subscribe to tool events from the client.
-   * Handles both tool.start and tool.complete events from all SDK types.
-   * This is necessary for SDKs like OpenCode that emit tool events via SSE
-   * rather than through the message stream.
-   */
-  function subscribeToToolEvents(): () => void {
-    // Map tool names to IDs for SDKs that don't provide IDs
-    const toolNameToId = new Map<string, string>();
-
-    // Mark that we're receiving tool events via hooks
-    // This prevents duplicate tool events from stream processing
-    state.toolEventsViaHooks = true;
-
-    // Track tool name → stack of tool IDs (for concurrent same-name tools)
-    const toolNameToIds = new Map<string, string[]>();
-
-    // FIFO queue of pending Task tool calls consumed by subagent.start.
-    // Keeps prompt + internal toolId + mode + run ownership together.
-    const pendingTaskEntries: Array<{ toolId: string; prompt?: string; isBackground?: boolean; runId: number }> = [];
-
-    // Maps SDK-level correlation IDs to agent IDs for ID-based result attribution.
-    // Populated by subagent.start, consumed by tool.complete for Task tools.
-    // Keys: toolUseID (Claude), toolCallId (Copilot), internal toolId (FIFO fallback)
-    const toolCallToAgentMap = new Map<string, string>();
-
-    // Map SDK tool use IDs to internal tool IDs for deduplication.
-    // SDKs like OpenCode emit tool.start for both "pending" and "running"
-    // statuses of the same tool call — this map ensures we reuse the same
-    // internal ID and update the existing UI entry instead of creating a duplicate.
-    const sdkToolIdMap = new Map<string, string>();
-
-    // Tool IDs belonging to running sub-agents. These tools are tracked in
-    // the parallel agents tree but filtered out of the main chat UI and
-    // ctrl+o transcript to avoid duplicate display.
-    const subagentToolIds = new Set<string>();
-    const useStableSdkToolIds = agentType === "opencode";
-
-    // Internal run ownership tracking for hook events.
-    const toolIdToRunMap = new Map<string, number>();
-    const sdkCorrelationToRunMap = new Map<string, number>();
-    const agentIdToRunMap = new Map<string, number>();
-
-    const eventBelongsToOwnedSession = (eventSessionId: string): boolean => {
-      if (typeof eventSessionId !== "string" || eventSessionId.length === 0) return false;
-      if (state.ownedSessionIds.has(eventSessionId)) return true;
-      return false;
-    };
-
-    const detachToolIdFromNameStack = (toolName: string, toolId: string): void => {
-      const ids = toolNameToIds.get(toolName);
-      if (!ids || ids.length === 0) return;
-      const idx = ids.indexOf(toolId);
-      if (idx === -1) return;
-      ids.splice(idx, 1);
-      if (ids.length === 0) {
-        toolNameToIds.delete(toolName);
-        toolNameToId.delete(toolName);
-      } else {
-        toolNameToId.set(toolName, ids[0] as string);
-      }
-    };
-
-    const clearToolRunTracking = (toolId: string, sdkCorrelationId?: string): void => {
-      state.activeToolIds.delete(toolId);
-      subagentToolIds.delete(toolId);
-      toolIdToRunMap.delete(toolId);
-      if (sdkCorrelationId) {
-        sdkToolIdMap.delete(sdkCorrelationId);
-        sdkCorrelationToRunMap.delete(sdkCorrelationId);
-      }
-    };
-
-    const resetParallelTracking = (_reason: string): void => {
-      pendingTaskEntries.splice(0, pendingTaskEntries.length);
-      toolCallToAgentMap.clear();
-      sdkToolIdMap.clear();
-      subagentToolIds.clear();
-      toolIdToRunMap.clear();
-      sdkCorrelationToRunMap.clear();
-      agentIdToRunMap.clear();
-      toolNameToIds.clear();
-      toolNameToId.clear();
-      state.activeToolIds.clear();
-      state.suppressPostTaskResult = null;
-      clearParallelAgents(state);
-    };
-    state.resetParallelTracking = resetParallelTracking;
-
-    // Internal cleanup gate for correlation tracking.
-    // Keep completed agents around until late Task tool.complete events are consumed.
-    const tryFinalizeParallelTracking = (): void => {
-      const hasActiveAgents = state.parallelAgents.some(
-        (a) => a.status === "running" || a.status === "pending" || a.status === "background"
-      );
-      const hasPendingCorrelations =
-        pendingTaskEntries.length > 0 || toolCallToAgentMap.size > 0;
-      if (!hasActiveAgents && !hasPendingCorrelations) {
-        // Keep completed agents visible while the parent stream is still
-        // active so sequential Task calls in the same response can merge into
-        // one tree. Clear only after stream ownership ends/reset.
-        if (!state.isStreaming || state.currentRunId === null) {
-          clearParallelAgents(state);
-        }
-      }
-    };
-
-    // Subscribe to tool.start events
-    const unsubStart = client.on("tool.start", (event) => {
-      const data = event.data as {
-        toolName?: string;
-        toolInput?: unknown;
-        toolUseId?: string;
-        toolUseID?: string;
-        toolCallId?: string;
-      };
-      if (data.toolName) {
-        state.telemetryTracker?.trackToolStart(data.toolName);
-      }
-      if (!state.toolStartHandler || !data.toolName) return;
-
-      // Reject stale hook events when no active run owns the stream.
-      const activeRunId = state.currentRunId;
-      if (activeRunId === null || !state.isStreaming) return;
-
-      // Resolve SDK-provided tool use ID (OpenCode: toolUseId, Claude: toolUseID)
-      const sdkId = data.toolUseId ?? data.toolUseID ?? data.toolCallId;
-      const isTaskToolName = data.toolName === "Task" || data.toolName === "task";
-      const sessionOwned = eventBelongsToOwnedSession(event.sessionId);
-      if (!sessionOwned) {
-        const sdkRunId = sdkId ? sdkCorrelationToRunMap.get(sdkId) : undefined;
-        const correlatedToActiveRun =
-          sdkRunId !== undefined && sdkRunId === activeRunId;
-        if (!correlatedToActiveRun) return;
-      }
-      if (sdkId) {
-        const sdkRunId = sdkCorrelationToRunMap.get(sdkId);
-        if (sdkRunId !== undefined && sdkRunId !== activeRunId) return;
-      }
-
-      let toolId: string;
-      let isUpdate = false;
-      if (sdkId && sdkToolIdMap.has(sdkId)) {
-        // Same logical tool call — reuse internal ID and update input
-        toolId = sdkToolIdMap.get(sdkId)!;
-        isUpdate = true;
-        const mappedRunId = toolIdToRunMap.get(toolId);
-        if (mappedRunId !== undefined && mappedRunId !== activeRunId) return;
-      } else {
-        // New tool call — assign a fresh internal ID
-        toolId = useStableSdkToolIds && sdkId
-          ? `tool_${sdkId}`
-          : `tool_${++state.toolIdCounter}`;
-        if (sdkId) sdkToolIdMap.set(sdkId, toolId);
-      }
-
-      if (!toolIdToRunMap.has(toolId)) {
-        toolIdToRunMap.set(toolId, activeRunId);
-      }
-      if (sdkId) {
-        sdkCorrelationToRunMap.set(sdkId, activeRunId);
-      }
-
-      // Check for duplicate events (same toolId already tracked)
-      if (!isUpdate && state.activeToolIds.has(toolId)) {
-        return; // Skip duplicate event
-      }
-      state.activeToolIds.add(toolId);
-
-      // Track name → ID stack (allows concurrent same-name tools)
-      if (!isUpdate) {
-        const ids = toolNameToIds.get(data.toolName) ?? [];
-        ids.push(toolId);
-        toolNameToIds.set(data.toolName, ids);
-      }
-      toolNameToId.set(data.toolName, toolId);
-
-      // Capture Task tool prompts and toolIds for subagent.start correlation.
-      // Only queue on first logical start; SDK updates for the same call
-      // must not enqueue duplicates.
-      if (isTaskToolName && data.toolInput && !isUpdate) {
-        const input = data.toolInput as Record<string, unknown>;
-        const prompt = (input.prompt as string) ?? (input.description as string) ?? "";
-        const isBackground = input.run_in_background === true || input.mode === "background";
-        pendingTaskEntries.push({ toolId, prompt: prompt || undefined, isBackground, runId: activeRunId });
-
-        // Eagerly create a ParallelAgent so the tree appears immediately
-        // instead of waiting for the SDK's subagent.start event (which may
-        // arrive late or not at all). When subagent.start fires later, the
-        // entry is updated in-place with the real subagentId.
-        if (state.parallelAgentHandler) {
-          const agentType = (
-            (input.subagent_type as string)
-            ?? (input.agent_type as string)
-            ?? (input.agent as string)
-            ?? (input.name as string)
-            ?? "agent"
-          ).trim() || "agent";
-          const taskDescRaw = (
-            (input.description as string)
-            ?? (input.prompt as string)
-            ?? (input.task as string)
-            ?? prompt
-            ?? "Sub-agent task"
-          );
-          const taskDesc = taskDescRaw.trim() || "Sub-agent task";
-          const newAgent: ParallelAgent = {
-            id: toolId,
-            taskToolCallId: toolId,
-            name: agentType,
-            task: taskDesc,
-            status: isBackground ? "background" : "running",
-            background: isBackground || undefined,
-            startedAt: new Date().toISOString(),
-            currentTool: isBackground
-              ? `Running ${agentType} in background…`
-              : `Starting ${agentType}…`,
-          };
-          state.parallelAgents = [...state.parallelAgents, newAgent];
-          state.parallelAgentHandler(state.parallelAgents);
-          toolCallToAgentMap.set(toolId, toolId);
-          agentIdToRunMap.set(toolId, activeRunId);
-        }
-      }
-      if (isTaskToolName && data.toolInput && isUpdate && state.parallelAgentHandler) {
-        // OpenCode often sends Task as pending -> running with richer input in
-        // the running update. Refresh eager placeholder metadata so we don't
-        // keep generic labels like "agent" / "Sub-agent task".
-        const input = data.toolInput as Record<string, unknown>;
-        const agentType = (
-          (input.subagent_type as string)
-          ?? (input.agent_type as string)
-          ?? (input.agent as string)
-          ?? (input.name as string)
-          ?? "agent"
-        ).trim() || "agent";
-        const taskDescRaw = (
-          (input.description as string)
-          ?? (input.prompt as string)
-          ?? (input.task as string)
-          ?? "Sub-agent task"
-        );
-        const taskDesc = taskDescRaw.trim() || "Sub-agent task";
-        const isBackground = input.run_in_background === true || input.mode === "background";
-        const mappedAgentId = toolCallToAgentMap.get(toolId) ?? toolId;
-
-        state.parallelAgents = state.parallelAgents.map((a) =>
-          a.id === mappedAgentId || a.id === toolId
-            ? {
-                ...a,
-                name: agentType,
-                task: taskDesc,
-                status: isBackground ? "background" : a.status,
-                background: isBackground || a.background,
-                currentTool: isBackground
-                  ? `Running ${agentType} in background…`
-                  : `Running ${agentType}…`,
-              }
-            : a
-        );
-        state.parallelAgentHandler(state.parallelAgents);
-      }
-
-      // Reset post-task text suppression when the model invokes a new tool —
-      // the model has moved past any potential JSON echo of the previous
-      // task result and is generating new output.
-      state.suppressPostTaskResult = null;
-
-      // Propagate tool progress to running subagents in the parallel agents tree.
-      // SDK events (subagent.start / subagent.complete) don't carry intermediate
-      // tool-use updates, so we bridge that gap here by attributing each tool.start
-      // to the most recently started running subagent.
-      const isTaskTool = isTaskToolName;
-      let isSubagentTool = false;
-      if (!isTaskTool && state.parallelAgentHandler && state.parallelAgents.length > 0) {
-        const runningAgent = [...state.parallelAgents]
-          .reverse()
-          .find((a) => a.status === "running");
-        if (runningAgent) {
-          isSubagentTool = true;
-          subagentToolIds.add(toolId);
-          const updatedToolUses = (runningAgent.toolUses ?? 0) + 1;
-          state.parallelAgents = state.parallelAgents.map((a) =>
-            a.id === runningAgent.id
-              ? { ...a, currentTool: data.toolName!, toolUses: updatedToolUses }
-              : a
-          );
-          state.parallelAgentHandler(state.parallelAgents);
-        }
-      }
-
-      // Only dispatch to the main chat UI for non-subagent tools.
-      // Sub-agent tool calls are tracked in the parallel agents tree
-      // and filtered out of the main UI / ctrl+o transcript.
-      if (!isSubagentTool) {
-        state.toolStartHandler(
-          toolId,
-          data.toolName,
-          (data.toolInput as Record<string, unknown>) ?? {}
-        );
-      }
-    });
-
-    // Subscribe to tool.complete events
-    const unsubComplete = client.on("tool.complete", (event) => {
-      const data = event.data as { toolName?: string; toolResult?: unknown; success?: boolean; error?: string; toolInput?: Record<string, unknown>; toolUseID?: string; toolCallId?: string; toolUseId?: string };
-      if (data.toolName) {
-        state.telemetryTracker?.trackToolComplete(data.toolName, data.success ?? true);
-      }
-      if (!state.toolCompleteHandler) return;
-
-      const activeRunId = state.currentRunId;
-      if (activeRunId === null || !state.isStreaming) return;
-
-      // Resolve internal tool ID:
-      // 1) Prefer SDK correlation IDs for deterministic attribution
-      // 2) Fallback to tool-name FIFO for SDKs without stable IDs
-      const sdkCorrelationId = data.toolUseID ?? data.toolCallId ?? data.toolUseId;
-      const sessionOwned = eventBelongsToOwnedSession(event.sessionId);
-      if (!sessionOwned) {
-        const sdkRunId = sdkCorrelationId
-          ? sdkCorrelationToRunMap.get(sdkCorrelationId)
-          : undefined;
-        if (sdkRunId === undefined || sdkRunId !== activeRunId) {
-          return;
-        }
-      }
-      let toolId: string;
-      if (sdkCorrelationId && sdkToolIdMap.has(sdkCorrelationId)) {
-        toolId = sdkToolIdMap.get(sdkCorrelationId)!;
-        if (data.toolName) {
-          detachToolIdFromNameStack(data.toolName, toolId);
-        }
-      } else if (data.toolName) {
-        // Find the matching tool ID from the stack (FIFO order)
-        const ids = toolNameToIds.get(data.toolName);
-        toolId = ids?.shift() ?? toolNameToId.get(data.toolName) ?? `tool_${state.toolIdCounter}`;
-        if (ids && ids.length === 0) {
-          toolNameToIds.delete(data.toolName);
-          toolNameToId.delete(data.toolName);
-        } else if (ids && ids.length > 0) {
-          toolNameToId.set(data.toolName, ids[0] as string);
-        }
-      } else {
-        toolId = `tool_${state.toolIdCounter}`;
-      }
-
-      const runIdFromSdk = sdkCorrelationId ? sdkCorrelationToRunMap.get(sdkCorrelationId) : undefined;
-      const runIdFromTool = toolIdToRunMap.get(toolId);
-      const eventRunId = runIdFromSdk ?? runIdFromTool;
-
-      // Fail closed on stale or unowned completions.
-      if (eventRunId === undefined || eventRunId !== activeRunId) {
-        clearToolRunTracking(toolId, sdkCorrelationId);
-        return;
-      }
-
-      // Skip dispatching to main chat UI for sub-agent tools.
-      // They were never registered via toolStartHandler, so there's
-      // nothing to complete in the message parts or tool calls arrays.
-      const isSubagentTool = subagentToolIds.has(toolId);
-      if (!isSubagentTool) {
-        state.toolCompleteHandler(
-          toolId,
-          data.toolResult,
-          data.success ?? true,
-          data.error,
-          data.toolInput // Pass input to update if it wasn't available at start
-        );
-      }
-      subagentToolIds.delete(toolId);
-
-      const isTaskTool = data.toolName === "Task" || data.toolName === "task";
-      if (isTaskTool) {
-        // Task completion consumed this call even if output is empty.
-        // Remove unresolved FIFO entry to avoid stale correlation state.
-        const pendingIdx = pendingTaskEntries.findIndex(
-          (entry) => entry.toolId === toolId && entry.runId === activeRunId
-        );
-        if (pendingIdx !== -1) {
-          pendingTaskEntries.splice(pendingIdx, 1);
-        }
-      }
-
-      // Propagate Task tool result to the corresponding parallel agent.
-      // The subagent.complete event (from SubagentStop / step-finish hooks)
-      // doesn't carry the actual output text — only the PostToolUse /
-      // tool.execution_complete event for the "Task" tool has the result.
-      // Use ID-based correlation to attribute results to the correct agent,
-      // falling back to reverse heuristic for backward compatibility.
-      if (
-        isTaskTool &&
-        data.toolResult &&
-        state.parallelAgentHandler &&
-        state.parallelAgents.length > 0
-      ) {
-        // Extract clean result text using the shared parser
-        const parsed = parseTaskToolResult(data.toolResult);
-        const fallbackResultText = parsed.text ?? (typeof data.toolResult === "string"
-          ? data.toolResult
-          : JSON.stringify(data.toolResult));
-        const normalizedResult = normalizeMarkdownNewlines(fallbackResultText);
-        const resultStr = normalizedResult.length > 0 ? normalizedResult : undefined;
-
-        // Try ID-based correlation: SDK-level IDs first, then internal toolId
-        const taskSdkCorrelationId = data.toolUseID ?? data.toolCallId ?? data.toolUseId;
-        const agentId = (taskSdkCorrelationId && toolCallToAgentMap.get(taskSdkCorrelationId))
-          || toolCallToAgentMap.get(toolId);
-
-        if (agentId) {
-          // Fallback: if the tool result indicates async (e.g. { isAsync: true }),
-          // retroactively mark the agent as background so finalization is skipped.
-          if (parsed.isAsync) {
-            state.parallelAgents = state.parallelAgents.map((a) =>
-              a.id === agentId && !a.background
-                ? { ...a, background: true, status: "background" as const }
-                : a
-            );
-          }
-
-          // Set result AND finalize status — if subagent.complete never
-          // fired (eager agent path), this ensures the agent transitions
-          // from "running" → "completed" when the Task tool returns.
-          // Use shouldFinalizeOnToolComplete guard to prevent premature
-          // finalization of background agents.
-          state.parallelAgents = state.parallelAgents.map((a) =>
-            a.id === agentId
-              ? {
-                  ...a,
-                  result: resultStr,
-                  status: shouldFinalizeOnToolComplete(a)
-                    ? (a.status === "running" || a.status === "pending"
-                        ? "completed" as const
-                        : a.status)
-                    : a.status,
-                  currentTool: shouldFinalizeOnToolComplete(a)
-                    ? (a.status === "running" || a.status === "pending"
-                        ? undefined
-                        : a.currentTool)
-                    : a.currentTool,
-                  durationMs: shouldFinalizeOnToolComplete(a)
-                    ? (a.durationMs ?? (Date.now() - new Date(a.startedAt).getTime()))
-                    : a.durationMs,
-                }
-              : a
-          );
-          state.parallelAgentHandler(state.parallelAgents);
-          // Clean up consumed mappings
-          if (taskSdkCorrelationId) toolCallToAgentMap.delete(taskSdkCorrelationId);
-          toolCallToAgentMap.delete(toolId);
-        } else {
-          // Fallback: find the last completed-or-running agent without a result
-          // Use shouldFinalizeOnToolComplete guard to prevent premature
-          // finalization of background agents.
-          const agentToUpdate = [...state.parallelAgents]
-            .reverse()
-            .find((a) => (a.status === "completed" || a.status === "running") && !a.result && shouldFinalizeOnToolComplete(a));
-          if (agentToUpdate) {
-            state.parallelAgents = state.parallelAgents.map((a) =>
-              a.id === agentToUpdate.id
-                ? {
-                    ...a,
-                    result: resultStr,
-                    status: "completed" as const,
-                    currentTool: undefined,
-                    durationMs: a.durationMs ?? (Date.now() - new Date(a.startedAt).getTime()),
-                  }
-                : a
-            );
-            state.parallelAgentHandler(state.parallelAgents);
-          }
-        }
-
-        // Store the result text so we can content-match against it.
-        // The SDK model may echo back the raw tool_response JSON as
-        // streaming text — we suppress text that matches the result but
-        // allow the model's real follow-up response through.
-        state.suppressPostTaskResult = resultStr ?? null;
-      } else if (
-        isTaskTool &&
-        state.parallelAgentHandler &&
-        state.parallelAgents.length > 0
-      ) {
-        // Task tool completed without a result — still finalize any
-        // eagerly-created agent that hasn't been marked completed yet.
-        // Use shouldFinalizeOnToolComplete guard to prevent premature
-        // finalization of background agents.
-        const agentId = toolCallToAgentMap.get(toolId);
-        if (agentId) {
-          state.parallelAgents = state.parallelAgents.map((a) =>
-            a.id === agentId && (a.status === "running" || a.status === "pending") && shouldFinalizeOnToolComplete(a)
-              ? {
-                  ...a,
-                  status: "completed" as const,
-                  currentTool: undefined,
-                  durationMs: a.durationMs ?? (Date.now() - new Date(a.startedAt).getTime()),
-                }
-              : a
-          );
-          state.parallelAgentHandler(state.parallelAgents);
-          toolCallToAgentMap.delete(toolId);
-        }
-      }
-
-      clearToolRunTracking(toolId, sdkCorrelationId);
-      tryFinalizeParallelTracking();
-    });
-
-    // Subscribe to skill.invoked events
-    const unsubSkill = client.on("skill.invoked", (event) => {
-      if (!eventBelongsToOwnedSession(event.sessionId)) return;
-      const data = event.data as { skillName?: string; skillPath?: string };
-      if (state.skillInvokedHandler && data.skillName) {
-        state.skillInvokedHandler(data.skillName, data.skillPath);
-      }
-    });
-
-    // Subscribe to permission.requested events for HITL
-    const unsubPermission = client.on("permission.requested", (event) => {
-      if (!eventBelongsToOwnedSession(event.sessionId)) return;
-      const data = event.data as {
-        requestId?: string;
-        toolName?: string;
-        question?: string;
-        header?: string;
-        options?: Array<{ label: string; value: string; description?: string }>;
-        respond?: (answer: string | string[]) => void;
-        toolCallId?: string;
-      };
-
-      if (state.permissionRequestHandler && data.question && data.respond) {
-        state.permissionRequestHandler(
-          data.requestId ?? `perm_${Date.now()}`,
-          data.toolName ?? "Unknown Tool",
-          data.question,
-          data.options ?? [],
-          data.respond,
-          data.header,
-          data.toolCallId
-        );
-      }
-    });
-
-    // Subscribe to human_input_required events from workflow graphs (askUserNode)
-    const unsubHumanInput = client.on("human_input_required", (event) => {
-      if (!eventBelongsToOwnedSession(event.sessionId)) return;
-      const data = event.data as {
-        requestId?: string;
-        question?: string;
-        header?: string;
-        options?: Array<{ label: string; description?: string }>;
-        nodeId?: string;
-        respond?: (answer: string | string[]) => void;
-      };
-
-      if (state.askUserQuestionHandler && data.question && data.requestId && data.nodeId) {
-        state.askUserQuestionHandler({
-          requestId: data.requestId,
-          question: data.question,
-          header: data.header,
-          options: data.options,
-          nodeId: data.nodeId,
-        });
-      }
-    });
-
-    // Subscribe to subagent.start events to update ParallelAgentsTree
-    const unsubSubagentStart = client.on("subagent.start", (event) => {
-      const data = event.data as {
-        subagentId?: string;
-        subagentType?: string;
-        task?: string;
-        toolInput?: unknown;
-        toolUseID?: string; // Claude: parent Task tool's use ID
-        toolCallId?: string; // Copilot: same as subagentId
-      };
-
-      // Skip if stream already ended — late events should not revive cleared agents
-      if (!state.isStreaming) return;
-      const activeRunId = state.currentRunId;
-      if (activeRunId === null) return;
-
-      if (!state.parallelAgentHandler || !data.subagentId) return;
-
-      const sdkCorrelationId = data.toolUseID ?? data.toolCallId;
-      const sdkRunId = sdkCorrelationId ? sdkCorrelationToRunMap.get(sdkCorrelationId) : undefined;
-      if (sdkRunId !== undefined && sdkRunId !== activeRunId) return;
-      const correlatedToolId = sdkCorrelationId ? sdkToolIdMap.get(sdkCorrelationId) : undefined;
-      let pendingTaskEntry: { toolId: string; prompt?: string; isBackground?: boolean; runId: number } | undefined;
-      if (correlatedToolId) {
-        const entryIdx = pendingTaskEntries.findIndex(
-          (entry) => entry.toolId === correlatedToolId && entry.runId === activeRunId
-        );
-        if (entryIdx !== -1) {
-          pendingTaskEntry = pendingTaskEntries.splice(entryIdx, 1)[0];
-        }
-      }
-      if (!pendingTaskEntry && !sdkCorrelationId) {
-        const firstActiveIdx = pendingTaskEntries.findIndex(
-          (entry) => entry.runId === activeRunId
-        );
-        if (firstActiveIdx !== -1) {
-          pendingTaskEntry = pendingTaskEntries.splice(firstActiveIdx, 1)[0];
-        }
-      }
-      const hasSdkCorrelationMatch = sdkRunId !== undefined && sdkRunId === activeRunId;
-      const sessionOwned = eventBelongsToOwnedSession(event.sessionId);
-      if (!sessionOwned && !pendingTaskEntry && !hasSdkCorrelationMatch) return;
-      // Fail closed for uncorrelated events to prevent cross-run leakage,
-      // but allow flows with SDK correlation IDs even if no Task entry exists.
-      // Also allow session-owned events during active streaming — this supports
-      // SDKs like Copilot that dispatch custom agents without a Task tool.
-      if (!pendingTaskEntry && !hasSdkCorrelationMatch && !sessionOwned) return;
-
-      // Use task from event data, or dequeue a pending Task tool prompt
-      const fallbackInput = data.toolInput as Record<string, unknown> | undefined;
-      const fallbackPrompt = fallbackInput
-        ? ((fallbackInput.prompt as string) ?? (fallbackInput.description as string))
-        : undefined;
-      const task = data.task
-        || pendingTaskEntry?.prompt
-        || fallbackPrompt
-        || data.subagentType
-        || "Sub-agent";
-      const agentTypeName = (
-        data.subagentType
-        ?? (fallbackInput?.subagent_type as string | undefined)
-        ?? (fallbackInput?.agent_type as string | undefined)
-        ?? (fallbackInput?.agent as string | undefined)
-        ?? (fallbackInput?.name as string | undefined)
-        ?? "agent"
-      ).trim() || "agent";
-      const isBackground = pendingTaskEntry?.isBackground
-        ?? ((fallbackInput?.run_in_background === true)
-        || (fallbackInput?.mode === "background"));
-
-      // Check if an eager agent was already created from tool.start.
-      // If so, update it in-place with the real subagentId instead of
-      // creating a duplicate entry.
-      const eagerToolId = pendingTaskEntry?.toolId;
-      const hasEagerAgent = eagerToolId
-        ? state.parallelAgents.some(a => a.id === eagerToolId)
-        : false;
-
-      if (hasEagerAgent && eagerToolId) {
-        // Merge: update existing eager agent with real subagentId.
-        // Preserve background status and other fields from the eager agent.
-        state.parallelAgents = state.parallelAgents.map(a =>
-          a.id === eagerToolId
-            ? {
-                ...a,
-                id: data.subagentId!,
-                taskToolCallId: a.taskToolCallId ?? eagerToolId,
-                name: agentTypeName,
-                task: data.task || a.task,
-                currentTool: `Running ${agentTypeName}…`,
-              }
-            : a
-        );
-        // Re-point correlation: toolId now maps to the real subagentId
-        toolCallToAgentMap.set(eagerToolId, data.subagentId!);
-      } else if (state.parallelAgents.some(a => a.id === data.subagentId)) {
-        // Duplicate lifecycle event for an already-tracked agent (can happen
-        // when SDKs emit both "subtask" and "agent" parts). Update in-place.
-        state.parallelAgents = state.parallelAgents.map(a =>
-          a.id === data.subagentId
-            ? {
-                ...a,
-                name: agentTypeName,
-                task: data.task || a.task,
-                currentTool: isBackground
-                  ? `Running ${agentTypeName} in background…`
-                  : `Running ${agentTypeName}…`,
-              }
-            : a
-        );
-      } else {
-        // No eager agent — create fresh (backward compat for non-Task subagents)
-        // Use stored background status from pendingTaskEntry
-        const newAgent: ParallelAgent = {
-          id: data.subagentId,
-          taskToolCallId: pendingTaskEntry?.toolId,
-          name: agentTypeName,
-          task,
-          status: isBackground ? "background" : "running",
-          background: isBackground || undefined,
-          startedAt: event.timestamp ?? new Date().toISOString(),
-          currentTool: isBackground
-            ? `Running ${agentTypeName} in background…`
-            : `Running ${agentTypeName}…`,
-        };
-        state.parallelAgents = [...state.parallelAgents, newAgent];
-      }
-      state.parallelAgentHandler(state.parallelAgents);
-      agentIdToRunMap.set(data.subagentId, activeRunId);
-
-      // Build correlation mapping: SDK-level ID → agentId
-      // This allows tool.complete to attribute results to the correct agent.
-      if (sdkCorrelationId) {
-        toolCallToAgentMap.set(sdkCorrelationId, data.subagentId);
-      }
-      // FIFO fallback: consume pending Task toolId and map it to this agent
-      const fifoToolId = pendingTaskEntry?.toolId;
-      if (fifoToolId) {
-        toolCallToAgentMap.set(fifoToolId, data.subagentId);
-      }
-    });
-
-    // Subscribe to subagent.complete events to update ParallelAgentsTree
-    const unsubSubagentComplete = client.on("subagent.complete", (event) => {
-      const data = event.data as {
-        subagentId?: string;
-        success?: boolean;
-        result?: unknown;
-      };
-      const activeRunId = state.currentRunId;
-      if (activeRunId === null) return;
-
-      const sessionOwned = eventBelongsToOwnedSession(event.sessionId);
-      if (data.subagentId) {
-        const runId = agentIdToRunMap.get(data.subagentId);
-        if (!sessionOwned && (runId === undefined || runId !== activeRunId)) return;
-        if (runId !== undefined && runId !== activeRunId) return;
-      } else if (!sessionOwned) {
-        return;
-      }
-
-      // Skip if stream already ended, unless a background agent is completing
-      if (!state.isStreaming) {
-        const targetAgent = data.subagentId
-          ? state.parallelAgents.find((a) => a.id === data.subagentId)
-          : undefined;
-        if (!targetAgent?.background) return;
-      }
-
-      if (state.parallelAgentHandler && data.subagentId) {
-        const status = data.success !== false ? "completed" : "error";
-        const normalizedResult = data.result == null
-          ? undefined
-          : normalizeMarkdownNewlines(String(data.result));
-        state.parallelAgents = state.parallelAgents.map((a) =>
-          a.id === data.subagentId
-            ? {
-                ...a,
-                status,
-                // Clear currentTool so getSubStatusText falls through to
-                // the status-based default ("Done" / error message)
-                currentTool: undefined,
-                result: normalizedResult && normalizedResult.length > 0 ? normalizedResult : undefined,
-                durationMs: Date.now() - new Date(a.startedAt).getTime(),
-              }
-            : a
-        );
-        state.parallelAgentHandler(state.parallelAgents);
-
-        // Note: Do NOT clear parallelAgents here. The Task tool.complete
-        // events fire after subagent.complete and need parallelAgents to
-        // still be populated to propagate results. Cleanup is handled by
-        // chat.tsx's handleComplete / isAgentOnlyStream effect which properly
-        // bakes agents into the final message before clearing.
-        agentIdToRunMap.delete(data.subagentId);
-        for (const [correlationId, mappedAgentId] of toolCallToAgentMap) {
-          if (mappedAgentId === data.subagentId) {
-            toolCallToAgentMap.delete(correlationId);
-          }
-        }
-        tryFinalizeParallelTracking();
-      }
-    });
-
-    return () => {
-      unsubStart();
-      unsubComplete();
-      unsubSkill();
-      unsubPermission();
-      unsubHumanInput();
-      unsubSubagentStart();
-      unsubSubagentComplete();
-      if (state.resetParallelTracking === resetParallelTracking) {
-        state.resetParallelTracking = null;
-      }
-    };
-  }
 
   /**
    * Ensure a session exists, creating one if needed.
@@ -1255,18 +403,8 @@ export async function startChatUI(
     }
     state.sessionCreationPromise = (async () => {
       try {
-        // Subscribe to tool events BEFORE creating the session.
-        // Only subscribe once — handlers reference `state` so they stay
-        // up-to-date even across session resets (e.g., /clear).
-        if (!state.toolEventsViaHooks) {
-          const unsubscribe = subscribeToToolEvents();
-          state.cleanupHandlers.push(unsubscribe);
-        }
-
         // Clear stale tool tracking from any previous session
         state.currentRunId = null;
-        state.activeToolIds.clear();
-        state.resetParallelTracking?.("ensure_session");
 
         // Apply the actively selected model for ALL agent types
         if (modelOps && sessionConfig) {
@@ -1296,354 +434,89 @@ export async function startChatUI(
 
   /**
    * Handle streaming a message response from the agent.
-   * Handles text, tool_use, and tool_result messages from the stream.
-   * Supports interruption via AbortController (Escape/Ctrl+C during streaming).
+   * Delegates to the appropriate SDK adapter which publishes events to the bus.
+   * UI consumption happens via useStreamConsumer hook subscribed to bus events.
    */
   async function handleStreamMessage(
     content: string,
-    onChunk: (chunk: string) => void,
-    onComplete: () => void,
-    onMeta?: (meta: StreamingMeta) => void,
     options?: { agent?: string }
   ): Promise<void> {
     // Single-owner stream model: any new stream handoff resets previous
     // run-owned hook state before creating the next owner.
     state.currentRunId = null;
-    state.resetParallelTracking?.("stream_start");
 
     // Create session if needed (uses shared lock to prevent dual creation)
     try {
       await ensureSession();
     } catch (error) {
       console.error("Failed to create session:", error);
-      onComplete();
       return;
     }
 
+    // If background agents were terminated via Ctrl+F, prepend a system
+    // notification so the model knows not to reference killed agents.
+    let effectiveContent = content;
+    if (state.backgroundAgentsTerminated) {
+      state.backgroundAgentsTerminated = false;
+      effectiveContent =
+        "[System: All background agents were terminated by the user (Ctrl+F). " +
+        "Do not reference or wait for any previously running background agents.]\n\n" +
+        content;
+    }
+
     // Create AbortController for this stream so it can be interrupted
     state.streamAbortController = new AbortController();
     state.currentRunId = ++state.runCounter;
     state.isStreaming = true;
-    const thinkingTextBySourceMap = new Map<string, string>();
-    const thinkingGenerationBySourceMap = new Map<string, number>();
-    const thinkingMessageBySourceMap = new Map<string, string>();
-    const activeThinkingSources = new Set<string>();
-    const closedThinkingSources = new Set<string>();
-
-    const closeThinkingSourcesAndClearMaps = (): void => {
-      const finalizedSources = new Set<string>();
-      for (const sourceKey of thinkingTextBySourceMap.keys()) {
-        finalizedSources.add(sourceKey);
-      }
-      for (const sourceKey of thinkingGenerationBySourceMap.keys()) {
-        finalizedSources.add(sourceKey);
-      }
-      for (const sourceKey of thinkingMessageBySourceMap.keys()) {
-        finalizedSources.add(sourceKey);
-      }
-      for (const sourceKey of activeThinkingSources) {
-        finalizedSources.add(sourceKey);
-      }
-      for (const sourceKey of finalizedSources) {
-        if (!closedThinkingSources.has(sourceKey)) {
-          traceThinkingSourceLifecycle("finalize", sourceKey, "stream finalize");
-        }
-        closedThinkingSources.add(sourceKey);
-      }
-
-      thinkingTextBySourceMap.clear();
-      thinkingGenerationBySourceMap.clear();
-      thinkingMessageBySourceMap.clear();
-      activeThinkingSources.clear();
-    };
 
-    try {
-      // Stream the response, wrapped so abort takes effect immediately
-      // even while iterator.next() is blocked on the network
-      const stream = state.session!.stream(content, options);
-      const abortableStream = abortableAsyncIterable(
-        stream,
-        state.streamAbortController.signal
-      );
-
-      let sdkOutputTokens = 0;
-      let thinkingMs = 0;
-      let thinkingStartLocal: number | null = null;
-      // Map SDK tool use IDs to internal tool IDs for stream-path deduplication
-      const streamToolIdMap = new Map<string, string>();
-      const allowStreamToolEvents = !state.toolEventsViaHooks || agentType === "opencode";
-
-      // Reset the suppress state at the start of each stream
-      state.suppressPostTaskResult = null;
-
-      // Prefix-based accumulator for post-task text suppression.
-      // Tracks accumulated text so we can check if the model is echoing the
-      // sub-agent result (text arrives sequentially matching from the start)
-      // vs. generating genuine follow-up content.
-      let suppressAccumulator = "";
-      let suppressTarget: string | null = null;
-
-      const toStringRecord = (sourceMap: Map<string, string>): Record<string, string> => {
-        const record: Record<string, string> = {};
-        for (const [source, value] of sourceMap) {
-          record[source] = value;
-        }
-        return record;
-      };
+    // Create the appropriate SDK adapter based on agent type
+    let adapter: SDKStreamAdapter;
 
-      const toNumberRecord = (sourceMap: Map<string, number>): Record<string, number> => {
-        const record: Record<string, number> = {};
-        for (const [source, value] of sourceMap) {
-          record[source] = value;
-        }
-        return record;
-      };
-
-      const resolveThinkingSourceKey = (message: AgentMessage): string => {
-        const metadata = message.metadata as Record<string, unknown> | undefined;
-        const sourceFromMetadata = typeof metadata?.thinkingSourceKey === "string"
-          ? metadata.thinkingSourceKey.trim()
-          : "";
-        if (sourceFromMetadata.length > 0) {
-          return sourceFromMetadata;
-        }
-        const contractError = new Error(
-          "Contract violation: thinking stream message is missing required metadata.thinkingSourceKey"
-        );
-        contractError.name = "ThinkingSourceContractViolationError";
-        throw contractError;
-      };
+    if (agentType === "opencode") {
+      adapter = new OpenCodeStreamAdapter(state.bus, state.session!.id, client);
+    } else if (agentType === "claude") {
+      adapter = new ClaudeStreamAdapter(state.bus, state.session!.id, client);
+    } else {
+      adapter = new CopilotStreamAdapter(state.bus, client);
+    }
 
-      const bindThinkingSource = (sourceKey: string, message: AgentMessage): void => {
-        const metadata = message.metadata as Record<string, unknown> | undefined;
-        const generationFromMetadata = metadata?.streamGeneration;
-        const resolvedGeneration = typeof generationFromMetadata === "number"
-          && Number.isFinite(generationFromMetadata)
-          ? generationFromMetadata
-          : (state.currentRunId ?? state.runCounter);
-        thinkingGenerationBySourceMap.set(sourceKey, resolvedGeneration);
-
-        const targetMessageId = typeof metadata?.targetMessageId === "string"
-          ? metadata.targetMessageId
-          : (typeof metadata?.messageId === "string" ? metadata.messageId : undefined);
-        if (targetMessageId && targetMessageId.length > 0) {
-          thinkingMessageBySourceMap.set(sourceKey, targetMessageId);
-        }
-      };
+    const runId = state.currentRunId;
+    const messageId = crypto.randomUUID();
+    debugSub.writeRawLine(`❯ ${content}`, {
+      sessionId: state.session?.id,
+      runId,
+      component: "prompt",
+    });
 
-      const getThinkingTextSnapshot = (): string => {
-        let combined = "";
-        for (const text of thinkingTextBySourceMap.values()) {
-          combined += text;
-        }
-        return combined;
-      };
+    // Discover agent names for Copilot adapter + tool registry
+    const knownAgentNames = client.getKnownAgentNames?.() ?? [];
+    if (knownAgentNames.length > 0) {
+      registerAgentToolNames(knownAgentNames);
+    }
 
-      const createStreamingMetaSnapshot = (thinkingSourceKey?: string): StreamingMeta => ({
-        outputTokens: sdkOutputTokens,
-        thinkingMs,
-        thinkingText: getThinkingTextSnapshot(),
-        thinkingSourceKey,
-        thinkingTextBySource: toStringRecord(thinkingTextBySourceMap),
-        thinkingGenerationBySource: toNumberRecord(thinkingGenerationBySourceMap),
-        thinkingMessageBySource: toStringRecord(thinkingMessageBySourceMap),
+    try {
+      await adapter.startStreaming(state.session!, effectiveContent, {
+        runId,
+        messageId,
+        abortSignal: state.streamAbortController?.signal,
+        agent: options?.agent,
+        knownAgentNames,
       });
 
-      for await (const message of abortableStream) {
-        // Handle text content
-        if (message.type === "text" && typeof message.content === "string") {
-          // Accumulate thinking duration when transitioning away from thinking
-          if (thinkingStartLocal !== null) {
-            thinkingMs = thinkingMs + (Date.now() - thinkingStartLocal);
-            thinkingStartLocal = null;
-          }
-
-          // After a Task tool completes, the SDK model may echo back the raw
-          // tool_response as streaming text. Suppress only text that looks
-          // like the echoed result (starts with JSON delimiters or sequentially
-          // matches the stored result from the beginning). Once non-echo text
-          // arrives, clear the suppression so the model's real response flows.
-          const cachedResult = state.suppressPostTaskResult;
-          // Reset accumulator when suppression target changes
-          if (cachedResult !== suppressTarget) {
-            suppressAccumulator = "";
-            suppressTarget = cachedResult;
-          }
-          if (cachedResult !== null) {
-            const trimmed = message.content.trim();
-            if (trimmed.length === 0) {
-              // Accumulate whitespace while suppression is active
-              suppressAccumulator += message.content;
-              continue;
-            }
-            const isJsonEcho = trimmed.startsWith("{") || trimmed.startsWith("[");
-            if (isJsonEcho) {
-              continue;
-            }
-            // Check if accumulated text + current chunk is a prefix of the
-            // cached result. When the model echoes a result, text arrives
-            // sequentially matching from the start of the result string.
-            // The old substring check (`cachedResult.indexOf(trimmed) !== -1`)
-            // was too aggressive — small streaming chunks (single words) are
-            // almost always found as substrings of long result strings, which
-            // incorrectly suppressed the model's genuine follow-up text.
-            const candidate = (suppressAccumulator + message.content).trimStart();
-            if ((cachedResult as string).startsWith(candidate)) {
-              suppressAccumulator += message.content;
-              continue;
-            }
-            // Not an echo — clear suppression, let this chunk through.
-            // Accumulated text was part of the echo prefix and stays suppressed.
-            state.suppressPostTaskResult = null;
-            suppressTarget = null;
-            suppressAccumulator = "";
-          }
-
-          if (message.content.length > 0) {
-            onChunk(message.content);
-          }
-
-          // Use SDK-reported token counts when present
-          const stats = message.metadata?.streamingStats as
-            | { outputTokens?: number; thinkingMs?: number }
-            | undefined;
-          if (stats?.thinkingMs != null) {
-            thinkingMs = stats.thinkingMs;
-          }
-          if (stats?.outputTokens && stats.outputTokens > 0) {
-            sdkOutputTokens = stats.outputTokens;
-          }
-
-          onMeta?.(createStreamingMetaSnapshot());
-        }
-        // Handle thinking metadata from SDK
-        else if (message.type === "thinking") {
-          const thinkingSourceKey = resolveThinkingSourceKey(message);
-          if (closedThinkingSources.has(thinkingSourceKey)) {
-            traceThinkingSourceLifecycle("drop", thinkingSourceKey, "index closed-source rejection");
-            continue;
-          }
-          const isNewSource = !activeThinkingSources.has(thinkingSourceKey);
-          if (isNewSource) {
-            activeThinkingSources.add(thinkingSourceKey);
-            traceThinkingSourceLifecycle("create", thinkingSourceKey, "index first-seen thinking event");
-          } else {
-            traceThinkingSourceLifecycle("update", thinkingSourceKey, "index thinking event update");
-          }
-          bindThinkingSource(thinkingSourceKey, message);
-
-          // Start local wall-clock timer on first thinking message
-          if (thinkingStartLocal === null) {
-            thinkingStartLocal = Date.now();
-          }
-
-          // Capture thinking text content
-          if (typeof message.content === "string") {
-            const previous = thinkingTextBySourceMap.get(thinkingSourceKey) ?? "";
-            thinkingTextBySourceMap.set(thinkingSourceKey, previous + message.content);
-          }
-
-          const stats = message.metadata?.streamingStats as
-            | { thinkingMs?: number; outputTokens?: number }
-            | undefined;
-
-          if (stats?.thinkingMs != null) {
-            // Authoritative value from SDK — use it and reset local timer
-            thinkingMs = stats.thinkingMs;
-            thinkingStartLocal = null;
-          } else {
-            // Live estimation: accumulated + current block duration
-            thinkingMs = thinkingMs + (Date.now() - thinkingStartLocal);
-            // Don't reset thinkingStartLocal — keep accumulating
-          }
-
-          if (stats?.outputTokens && stats.outputTokens > 0) {
-            sdkOutputTokens = stats.outputTokens;
-          }
-          onMeta?.(createStreamingMetaSnapshot(thinkingSourceKey));
-        }
-        // Handle tool_use content - notify UI of tool invocation
-        // OpenCode can complete the stream before hook events flush; keep a
-        // stream-path fallback for it while preserving hook-first behavior elsewhere.
-        else if (message.type === "tool_use" && message.content && allowStreamToolEvents) {
-          const toolContent = message.content as { name?: string; input?: Record<string, unknown>; toolUseId?: string };
-          if (state.toolStartHandler && toolContent.name) {
-            state.telemetryTracker?.trackToolStart(toolContent.name);
-            // Deduplicate using SDK tool use ID (e.g., Claude's includePartialMessages
-            // emits multiple assistant messages for the same tool_use block)
-            const sdkId = toolContent.toolUseId
-              ?? (message.metadata as Record<string, unknown> | undefined)?.toolId as string | undefined;
-            let toolId: string;
-            if (sdkId && streamToolIdMap.has(sdkId)) {
-              toolId = streamToolIdMap.get(sdkId)!;
-            } else {
-              toolId = agentType === "opencode" && sdkId
-                ? `tool_${sdkId}`
-                : `tool_${++state.toolIdCounter}`;
-              if (sdkId) streamToolIdMap.set(sdkId, toolId);
-            }
-            state.toolStartHandler(
-              toolId,
-              toolContent.name,
-              toolContent.input ?? {}
-            );
-          }
-        }
-        // Handle tool_result content - notify UI of tool completion
-        else if (message.type === "tool_result" && allowStreamToolEvents) {
-          if (state.toolCompleteHandler) {
-            const metadata = message.metadata as Record<string, unknown> | undefined;
-            const toolNameFromMeta = typeof message.metadata?.toolName === "string"
-              ? message.metadata.toolName
-              : "unknown";
-            const sdkId = typeof metadata?.toolId === "string" ? metadata.toolId : undefined;
-            state.telemetryTracker?.trackToolComplete(toolNameFromMeta, true);
-            const toolId = sdkId
-              ? (streamToolIdMap.get(sdkId) ?? (agentType === "opencode" ? `tool_${sdkId}` : `tool_${state.toolIdCounter}`))
-              : `tool_${state.toolIdCounter}`;
-            if (sdkId && !streamToolIdMap.has(sdkId)) {
-              streamToolIdMap.set(sdkId, toolId);
-            }
-            state.toolCompleteHandler(
-              toolId,
-              message.content,
-              true
-            );
-          }
-        }
-      }
-
-      closeThinkingSourcesAndClearMaps();
       state.messageCount++;
-      onComplete();
     } catch (error) {
-      closeThinkingSourcesAndClearMaps();
-      // Ignore AbortError - this is expected when user interrupts
+      // AbortError is expected when user interrupts — finalize cleanly
       if (error instanceof Error && error.name === "AbortError") {
-        // Stream was intentionally aborted
-      } else if (error instanceof Error && error.name === "ThinkingSourceContractViolationError") {
         state.currentRunId = null;
-        state.resetParallelTracking?.("stream_error");
-        onComplete();
-        throw error;
+        return;
       }
       state.currentRunId = null;
-      state.resetParallelTracking?.("stream_error");
-      onComplete();
     } finally {
+      adapter.dispose();
       // Clear streaming state
       state.streamAbortController = null;
-      // Keep isStreaming true if sub-agents are still actively running so
-      // subagent.complete events continue to be processed.
-      // Only match agents that are actually active (running/pending/background),
-      // not completed background agents that happen to have background=true.
-      const hasActiveAgents = state.parallelAgents.some(
-        (a) => a.status === "running" || a.status === "pending" || a.status === "background"
-      );
-      if (!hasActiveAgents) {
-        state.isStreaming = false;
-        state.currentRunId = null;
-      }
+      state.isStreaming = false;
+      state.currentRunId = null;
     }
   }
 
@@ -1668,20 +541,10 @@ export async function startChatUI(
       state.isStreaming = false;
       state.currentRunId = null;
 
-      // Preserve background agents across the reset — resetParallelTracking
-      // calls clearParallelAgents() which wipes ALL agents from state.
-      const backgroundAgents = state.parallelAgents.filter(isBackgroundAgent);
-      state.resetParallelTracking?.("interrupt");
-      // Restore background agents that were cleared by resetParallelTracking
-      if (backgroundAgents.length > 0) {
-        state.parallelAgents = backgroundAgents;
-        state.parallelAgentHandler?.(state.parallelAgents);
-      }
-
       state.streamAbortController?.abort();
-      // NOTE: Do NOT call session.abort() here — it aborts the entire SDK
-      // session which kills ALL agents including background ones. The stream
-      // abort controller above is sufficient to cancel the foreground stream.
+      if (state.session?.abort) {
+        void state.session.abort().catch(() => {});
+      }
       state.telemetryTracker?.trackInterrupt(sourceType);
       // Reset interrupt state
       state.interruptCount = 0;
@@ -1689,9 +552,6 @@ export async function startChatUI(
         clearTimeout(state.interruptTimeout);
         state.interruptTimeout = null;
       }
-      if (state.showCtrlCWarning) {
-        state.showCtrlCWarning(false);
-      }
       return;
     }
 
@@ -1704,26 +564,17 @@ export async function startChatUI(
         clearTimeout(state.interruptTimeout);
         state.interruptTimeout = null;
       }
-      if (state.showCtrlCWarning) {
-        state.showCtrlCWarning(false);
-      }
       void cleanup();
       return;
     }
 
-    // First press - show warning and set timeout
-    if (state.showCtrlCWarning) {
-      state.showCtrlCWarning(true);
-    }
+    // First press - arm timeout for double-press exit
     if (state.interruptTimeout) {
       clearTimeout(state.interruptTimeout);
     }
     state.interruptTimeout = setTimeout(() => {
       state.interruptCount = 0;
       state.interruptTimeout = null;
-      if (state.showCtrlCWarning) {
-        state.showCtrlCWarning(false);
-      }
     }, 1000);
   }
 
@@ -1744,9 +595,6 @@ export async function startChatUI(
   state.cleanupHandlers.push(() => {
     process.off("SIGINT", sigintHandler);
     process.off("SIGTERM", sigtermHandler);
-    if (state.ctrlCTimeout) {
-      clearTimeout(state.ctrlCTimeout);
-    }
     if (state.interruptTimeout) {
       clearTimeout(state.interruptTimeout);
     }
@@ -1796,34 +644,26 @@ export async function startChatUI(
     // Create React root
     state.root = createRoot(state.renderer);
 
-    // Render the chat application
-    // Handler registration callbacks - ChatApp will call these with its internal handlers
-    const registerToolStartHandler = (handler: OnToolStart) => {
-      state.toolStartHandler = handler;
-    };
-
-    const registerToolCompleteHandler = (handler: OnToolComplete) => {
-      state.toolCompleteHandler = handler;
-    };
-
-    const registerSkillInvokedHandler = (handler: OnSkillInvoked) => {
-      state.skillInvokedHandler = handler;
-    };
-
-    const registerPermissionRequestHandler = (handler: ChatOnPermissionRequest) => {
-      state.permissionRequestHandler = handler;
-    };
+    // Render the chat application.
 
-    const registerAskUserQuestionHandler = (handler: OnAskUserQuestion) => {
-      state.askUserQuestionHandler = handler;
-    };
-
-    const registerParallelAgentHandler = (handler: (agents: ParallelAgent[]) => void) => {
-      state.parallelAgentHandler = handler;
-    };
+    /**
+     * Set the streaming state from the UI layer.
+     * Used by spawnSubagentParallel to flag that sub-agent sessions are
+     * streaming even though the main session is idle.
+     */
+    const setStreamingState = (isStreaming: boolean) => {
+      if (isStreaming) {
+        state.isStreaming = true;
+        // Bridge-driven sub-agent execution does not go through handleStreamMessage,
+        // so we must establish a run owner here to allow hook events.
+        if (state.currentRunId === null) {
+          state.currentRunId = ++state.runCounter;
+        }
+        return;
+      }
 
-    const registerCtrlCWarningHandler = (handler: (show: boolean) => void) => {
-      state.showCtrlCWarning = handler;
+      state.isStreaming = false;
+      state.currentRunId = null;
     };
 
     /**
@@ -1834,30 +674,39 @@ export async function startChatUI(
       handleInterrupt("ui");
     };
 
-    const handleTerminateBackgroundAgentsFromUI: OnTerminateBackgroundAgents = () => {
-      const activeAgents = getActiveBackgroundAgents(state.parallelAgents);
-      if (activeAgents.length === 0) {
-        state.telemetryTracker?.trackBackgroundTermination("noop", 0);
+    const handleTerminateBackgroundAgentsFromUI: OnTerminateBackgroundAgents = async () => {
+      // Prefer the selective abortBackgroundAgents method which targets only
+      // background agents. Falls back to full abort for clients that don't
+      // implement the selective method yet.
+      if (state.session?.abortBackgroundAgents) {
+        try {
+          await state.session.abortBackgroundAgents();
+          // Mark that background agents were terminated so the next user
+          // message includes a system notification in the model context.
+          state.backgroundAgentsTerminated = true;
+          state.telemetryTracker?.trackBackgroundTermination("execute", 1, 1);
+        } catch (error) {
+          console.error("Failed to abort background agents:", error);
+          throw error;
+        }
         return;
       }
 
-      const activeCount = activeAgents.length;
-
-      // Clear background agents from state tracking
-      state.parallelAgents = state.parallelAgents.filter(a => !isBackgroundAgent(a));
-      state.parallelAgentHandler?.(state.parallelAgents);
-
-      // Abort the SDK session to actually kill background agent processes.
-      // This is safe because ctrl+f only fires when NOT streaming (guarded
-      // by isStreamingRef.current check in chat.tsx), so no foreground work
-      // will be affected.
+      // Fallback: abort the entire session (safe because Ctrl+F only fires
+      // when NOT streaming, so no foreground work will be affected).
       if (state.session?.abort) {
-        void state.session.abort().catch((error) => {
+        try {
+          await state.session.abort();
+          state.backgroundAgentsTerminated = true;
+          state.telemetryTracker?.trackBackgroundTermination("fallback", 1, 1);
+        } catch (error) {
           console.error("Failed to abort session during background-agent termination:", error);
-        });
+          throw error;
+        }
+        return;
       }
 
-      state.telemetryTracker?.trackBackgroundTermination("execute", activeCount, activeCount);
+      state.telemetryTracker?.trackBackgroundTermination("noop", 0);
     };
 
     /**
@@ -1872,7 +721,6 @@ export async function startChatUI(
     const resetSession = async () => {
       state.currentRunId = null;
       state.isStreaming = false;
-      state.resetParallelTracking?.("reset_session");
       if (state.session) {
         try {
           await state.session.destroy();
@@ -1928,43 +776,44 @@ export async function startChatUI(
         {
           initialTheme: theme,
           children: React.createElement(
-            AppErrorBoundary,
+            EventBusProvider,
             {
-              onExit: () => { void cleanup(); },
-              isDark: theme.isDark,
-              children: React.createElement(ChatApp, {
-                title,
-                placeholder,
-                version,
-                model,
-                tier,
-                workingDir,
-                suggestion,
-                agentType,
-                modelOps,
-                initialModelId: sessionConfig?.model,
-                getModelDisplayInfo: (hint?: string) => client.getModelDisplayInfo(hint),
-                onSendMessage: handleSendMessage,
-                onStreamMessage: handleStreamMessage,
-                onExit: handleExit,
-                onResetSession: resetSession,
-                onInterrupt: handleInterruptFromUI,
-                onTerminateBackgroundAgents: handleTerminateBackgroundAgentsFromUI,
-                registerToolStartHandler,
-                registerToolCompleteHandler,
-                registerSkillInvokedHandler,
-                registerPermissionRequestHandler,
-                registerAskUserQuestionHandler,
-                registerParallelAgentHandler,
-                registerCtrlCWarningHandler,
-                getSession,
-                createSubagentSession,
-                initialPrompt,
-                onModelChange: handleModelChange,
-                onSessionMcpServersChange: handleSessionMcpServersChange,
-                onCommandExecutionTelemetry: handleCommandTelemetry,
-                onMessageSubmitTelemetry: handleMessageTelemetry,
-              }),
+              bus: state.bus,
+              dispatcher: state.dispatcher,
+              children: React.createElement(
+                AppErrorBoundary,
+                {
+                  onExit: () => { void cleanup(); },
+                  isDark: theme.isDark,
+                  children: React.createElement(ChatApp, {
+                    title,
+                    placeholder,
+                    version,
+                    model,
+                    tier,
+                    workingDir,
+                    suggestion,
+                    agentType,
+                    modelOps,
+                    initialModelId: sessionConfig?.model,
+                    getModelDisplayInfo: (hint?: string) => client.getModelDisplayInfo(hint),
+                    onSendMessage: handleSendMessage,
+                    onStreamMessage: handleStreamMessage,
+                    onExit: handleExit,
+                    onResetSession: resetSession,
+                    onInterrupt: handleInterruptFromUI,
+                    onTerminateBackgroundAgents: handleTerminateBackgroundAgentsFromUI,
+                    setStreamingState,
+                    getSession,
+                    createSubagentSession,
+                    initialPrompt,
+                    onModelChange: handleModelChange,
+                    onSessionMcpServersChange: handleSessionMcpServersChange,
+                    onCommandExecutionTelemetry: handleCommandTelemetry,
+                    onMessageSubmitTelemetry: handleMessageTelemetry,
+                  }),
+                }
+              ),
             }
           ),
         }
@@ -2097,8 +946,6 @@ export {
   type ChatMessage,
   type MessageToolCall,
   type WorkflowChatState,
-  type OnToolStart,
-  type OnToolComplete,
   type OnInterrupt,
   type OnTerminateBackgroundAgents,
   type OnAskUserQuestion,
@@ -2113,32 +960,9 @@ export {
   type Theme,
   type ThemeColors,
 } from "./theme.tsx";
-export {
-  default as CodeBlock,
-  type CodeBlockProps,
-  type ParsedCodeBlock,
-  normalizeLanguage,
-  extractCodeBlocks,
-  hasCodeBlocks,
-  extractInlineCode,
-} from "./code-block.tsx";
-
-// Hooks module
-export {
-  useStreamingState,
-  type StreamingState,
-  type ToolExecutionState,
-  type ToolExecutionStatus,
-  type ToolExecutionTimestamps,
-  type UseStreamingStateReturn,
-  createInitialStreamingState,
-  generateToolExecutionId,
-  getCurrentTimestamp,
-  createToolExecution,
-  getActiveToolExecutions,
-  getCompletedToolExecutions,
-  getErroredToolExecutions,
-} from "./hooks/index.ts";
+
+// Parts module - type exports for rendering system
+export { type ToolExecutionStatus } from "./parts/types.ts";
 
 // Tools module
 export {
@@ -2157,6 +981,7 @@ export {
   getRegisteredToolNames,
   hasCustomRenderer,
   getLanguageFromExtension,
+  registerAgentToolNames,
 } from "./tools/index.ts";
 
 // Commands module
diff --git a/src/ui/parts/concurrent-agent-inline-isolation.integration.test.ts b/src/ui/parts/concurrent-agent-inline-isolation.integration.test.ts
new file mode 100644
index 0000000000..521e4912e2
--- /dev/null
+++ b/src/ui/parts/concurrent-agent-inline-isolation.integration.test.ts
@@ -0,0 +1,354 @@
+import { beforeEach, describe, expect, test } from "bun:test";
+import { EventBus } from "../../events/event-bus.ts";
+import { BatchDispatcher } from "../../events/batch-dispatcher.ts";
+import { wireConsumers } from "../../events/consumers/wire-consumers.ts";
+import type { BusEvent, BusEventDataMap, BusEventType } from "../../events/bus-events.ts";
+import type { ChatMessage } from "../chat.tsx";
+import { getAgentInlineDisplayParts, type ParallelAgent } from "../components/parallel-agents-tree.tsx";
+import { _resetPartCounter } from "./id.ts";
+import { applyStreamPartEvent, type StreamPartEvent } from "./stream-pipeline.ts";
+
+const SESSION_ID = "concurrent-inline-session";
+const RUN_ID = 1;
+
+function createAssistantMessage(): ChatMessage {
+  return {
+    id: "msg-concurrent-inline",
+    role: "assistant",
+    content: "",
+    timestamp: new Date().toISOString(),
+    streaming: true,
+    parts: [],
+    toolCalls: [],
+  };
+}
+
+function createAgent(id: string, taskToolCallId: string, task: string): ParallelAgent {
+  return {
+    id,
+    taskToolCallId,
+    name: "codebase-analyzer",
+    task,
+    status: "running",
+    startedAt: new Date().toISOString(),
+  };
+}
+
+function publishEvent<T extends BusEventType>(
+  bus: EventBus,
+  type: T,
+  data: BusEventDataMap[T],
+): void {
+  const event: BusEvent<T> = {
+    type,
+    sessionId: SESSION_ID,
+    runId: RUN_ID,
+    timestamp: Date.now(),
+    data,
+  };
+  bus.publish(event);
+}
+
+async function flushMicrotasks(): Promise<void> {
+  await new Promise((resolve) => setTimeout(resolve, 0));
+}
+
+async function waitForBatchFlush(): Promise<void> {
+  await new Promise((resolve) => setTimeout(resolve, 25));
+}
+
+beforeEach(() => {
+  _resetPartCounter();
+});
+
+describe("concurrent agent inline part isolation (integration)", () => {
+  test("keeps interleaved concurrent agent events isolated per inlineParts branch", async () => {
+    const bus = new EventBus();
+    const dispatcher = new BatchDispatcher(bus);
+    const { pipeline, correlation, dispose } = wireConsumers(bus, dispatcher);
+    const streamEvents: StreamPartEvent[] = [];
+    pipeline.onStreamParts((events) => streamEvents.push(...events));
+
+    try {
+      correlation.startRun(RUN_ID, SESSION_ID);
+
+      let msg = createAssistantMessage();
+      msg = applyStreamPartEvent(msg, {
+        type: "tool-start",
+        toolId: "task_a",
+        toolName: "Task",
+        input: { description: "Analyze auth flow" },
+      });
+      msg = applyStreamPartEvent(msg, {
+        type: "tool-start",
+        toolId: "task_b",
+        toolName: "Task",
+        input: { description: "Analyze billing flow" },
+      });
+      msg = applyStreamPartEvent(msg, {
+        type: "parallel-agents",
+        agents: [
+          createAgent("agent_a", "task_a", "Analyze auth flow"),
+          createAgent("agent_b", "task_b", "Analyze billing flow"),
+        ],
+        isLastMessage: true,
+      });
+
+      publishEvent(bus, "stream.text.delta", {
+        delta: "agent-b answer",
+        messageId: "msg-concurrent-inline",
+        agentId: "agent_b",
+      });
+      publishEvent(bus, "stream.tool.start", {
+        toolId: "agent_a_tool_1",
+        toolName: "rg",
+        toolInput: { pattern: "auth" },
+        parentAgentId: "agent_a",
+      });
+      publishEvent(bus, "stream.text.delta", {
+        delta: "agent-a answer\n\n```ts\nconst authEnabled = true;\n```",
+        messageId: "msg-concurrent-inline",
+        agentId: "agent_a",
+      });
+      publishEvent(bus, "stream.tool.start", {
+        toolId: "agent_b_tool_1",
+        toolName: "glob",
+        toolInput: { pattern: "src/**/*.ts" },
+        parentAgentId: "agent_b",
+      });
+      publishEvent(bus, "stream.tool.complete", {
+        toolId: "agent_a_tool_1",
+        toolName: "rg",
+        toolResult: "found auth files",
+        success: true,
+        parentAgentId: "agent_a",
+      });
+      publishEvent(bus, "stream.tool.complete", {
+        toolId: "agent_b_tool_1",
+        toolName: "glob",
+        toolResult: ["a.ts", "b.ts"],
+        success: true,
+        parentAgentId: "agent_b",
+      });
+
+      await flushMicrotasks();
+      await waitForBatchFlush();
+
+      for (const event of streamEvents) {
+        msg = applyStreamPartEvent(msg, event);
+      }
+      msg = applyStreamPartEvent(msg, {
+        type: "thinking-meta",
+        thinkingSourceKey: "agent:a:thinking",
+        targetMessageId: "msg-concurrent-inline",
+        streamGeneration: 1,
+        thinkingMs: 210,
+        thinkingText: "agent-a reasoning",
+        includeReasoningPart: true,
+        agentId: "agent_a",
+      });
+      msg = applyStreamPartEvent(msg, {
+        type: "thinking-meta",
+        thinkingSourceKey: "agent:b:thinking",
+        targetMessageId: "msg-concurrent-inline",
+        streamGeneration: 1,
+        thinkingMs: 320,
+        thinkingText: "agent-b reasoning",
+        includeReasoningPart: true,
+        agentId: "agent_b",
+      });
+
+      expect(msg.content).toBe("");
+      expect((msg.parts ?? []).some((part) => part.type === "reasoning")).toBe(false);
+
+      const agentPart = (msg.parts ?? []).find((part) => part.type === "agent");
+      expect(agentPart?.type).toBe("agent");
+      if (agentPart?.type !== "agent") return;
+
+      const agentA = agentPart.agents.find((agent) => agent.id === "agent_a");
+      const agentB = agentPart.agents.find((agent) => agent.id === "agent_b");
+      expect(agentA).toBeDefined();
+      expect(agentB).toBeDefined();
+
+      const agentAReasoning = agentA?.inlineParts?.find((part) => part.type === "reasoning");
+      const agentAText = agentA?.inlineParts?.find((part) => part.type === "text");
+      const agentATool = agentA?.inlineParts?.find((part) => part.type === "tool");
+      expect(agentAReasoning?.type).toBe("reasoning");
+      expect(agentAText?.type).toBe("text");
+      expect(agentATool?.type).toBe("tool");
+      if (agentAReasoning?.type === "reasoning") {
+        expect(agentAReasoning.content).toBe("agent-a reasoning");
+      }
+      if (agentAText?.type === "text") {
+        expect(agentAText.content).toBe("agent-a answer\n\n```ts\nconst authEnabled = true;\n```");
+        expect(agentAText.content.includes("agent-b")).toBe(false);
+      }
+      if (agentATool?.type === "tool") {
+        expect(agentATool.toolCallId).toBe("agent_a_tool_1");
+        expect(agentATool.state.status).toBe("completed");
+      }
+
+      const agentBReasoning = agentB?.inlineParts?.find((part) => part.type === "reasoning");
+      const agentBText = agentB?.inlineParts?.find((part) => part.type === "text");
+      const agentBTool = agentB?.inlineParts?.find((part) => part.type === "tool");
+      expect(agentBReasoning?.type).toBe("reasoning");
+      expect(agentBText?.type).toBe("text");
+      expect(agentBTool?.type).toBe("tool");
+      if (agentBReasoning?.type === "reasoning") {
+        expect(agentBReasoning.content).toBe("agent-b reasoning");
+      }
+      if (agentBText?.type === "text") {
+        expect(agentBText.content).toBe("agent-b answer");
+        expect(agentBText.content.includes("agent-a")).toBe(false);
+      }
+      if (agentBTool?.type === "tool") {
+        expect(agentBTool.toolCallId).toBe("agent_b_tool_1");
+        expect(agentBTool.state.status).toBe("completed");
+      }
+
+      const agentAVerboseInline = getAgentInlineDisplayParts(agentA?.inlineParts ?? []);
+      expect(agentAVerboseInline.some((part) => part.type === "reasoning")).toBe(true);
+      // text and tool parts are suppressed from inline display
+      expect(agentAVerboseInline.some(
+        (part) => part.type === "text",
+      )).toBe(false);
+      expect(agentAVerboseInline.some((part) => part.type === "tool")).toBe(false);
+
+      const agentACompactInline = getAgentInlineDisplayParts(agentA?.inlineParts ?? []);
+      expect(agentACompactInline.map((part) => part.id)).toEqual(
+        agentAVerboseInline.map((part) => part.id),
+      );
+
+      const agentBVerboseInline = getAgentInlineDisplayParts(agentB?.inlineParts ?? []);
+      expect(agentBVerboseInline.some((part) => part.type === "reasoning")).toBe(true);
+      // text and tool parts are suppressed from inline display
+      expect(agentBVerboseInline.some((part) => part.type === "text")).toBe(false);
+      expect(agentBVerboseInline.some((part) => part.type === "tool")).toBe(false);
+
+      const agentBCompactInline = getAgentInlineDisplayParts(agentB?.inlineParts ?? []);
+      expect(agentBCompactInline.map((part) => part.id)).toEqual(
+        agentBVerboseInline.map((part) => part.id),
+      );
+    } finally {
+      dispose();
+    }
+  });
+
+  test("replays buffered agent events into the correct concurrent inline branches when agents appear", async () => {
+    const bus = new EventBus();
+    const dispatcher = new BatchDispatcher(bus);
+    const { pipeline, correlation, dispose } = wireConsumers(bus, dispatcher);
+    const streamEvents: StreamPartEvent[] = [];
+    pipeline.onStreamParts((events) => streamEvents.push(...events));
+
+    try {
+      correlation.startRun(RUN_ID, SESSION_ID);
+
+      let msg = createAssistantMessage();
+      msg = applyStreamPartEvent(msg, {
+        type: "tool-start",
+        toolId: "task_a",
+        toolName: "Task",
+        input: { description: "Buffer branch A" },
+      });
+      msg = applyStreamPartEvent(msg, {
+        type: "tool-start",
+        toolId: "task_b",
+        toolName: "Task",
+        input: { description: "Buffer branch B" },
+      });
+
+      publishEvent(bus, "stream.text.delta", {
+        delta: "buffered agent-a text",
+        messageId: "msg-concurrent-inline",
+        agentId: "agent_a",
+      });
+      publishEvent(bus, "stream.tool.start", {
+        toolId: "agent_a_tool_buffered",
+        toolName: "bash",
+        toolInput: { command: "echo buffered" },
+        parentAgentId: "agent_a",
+      });
+      publishEvent(bus, "stream.tool.complete", {
+        toolId: "agent_a_tool_buffered",
+        toolName: "bash",
+        toolResult: "buffered output",
+        success: true,
+        parentAgentId: "agent_a",
+      });
+      publishEvent(bus, "stream.text.delta", {
+        delta: "buffered agent-b text",
+        messageId: "msg-concurrent-inline",
+        agentId: "agent_b",
+      });
+      msg = applyStreamPartEvent(msg, {
+        type: "thinking-meta",
+        thinkingSourceKey: "agent:b:buffered",
+        targetMessageId: "msg-concurrent-inline",
+        streamGeneration: 1,
+        thinkingMs: 640,
+        thinkingText: "buffered agent-b reasoning",
+        includeReasoningPart: true,
+        agentId: "agent_b",
+      });
+
+      await flushMicrotasks();
+      await waitForBatchFlush();
+
+      for (const event of streamEvents) {
+        msg = applyStreamPartEvent(msg, event);
+      }
+
+      expect((msg.parts ?? []).some((part) => part.type === "agent")).toBe(false);
+      expect(msg.content).toBe("");
+
+      msg = applyStreamPartEvent(msg, {
+        type: "parallel-agents",
+        agents: [
+          createAgent("agent_a", "task_a", "Buffer branch A"),
+          createAgent("agent_b", "task_b", "Buffer branch B"),
+        ],
+        isLastMessage: true,
+      });
+
+      const agentPart = (msg.parts ?? []).find((part) => part.type === "agent");
+      expect(agentPart?.type).toBe("agent");
+      if (agentPart?.type !== "agent") return;
+
+      const agentA = agentPart.agents.find((agent) => agent.id === "agent_a");
+      const agentB = agentPart.agents.find((agent) => agent.id === "agent_b");
+
+      const agentAText = agentA?.inlineParts?.find((part) => part.type === "text");
+      const agentATool = agentA?.inlineParts?.find((part) => part.type === "tool");
+      expect(agentAText?.type).toBe("text");
+      expect(agentATool?.type).toBe("tool");
+      if (agentAText?.type === "text") {
+        expect(agentAText.content).toBe("buffered agent-a text");
+      }
+      if (agentATool?.type === "tool") {
+        expect(agentATool.toolCallId).toBe("agent_a_tool_buffered");
+        expect(agentATool.state.status).toBe("completed");
+      }
+
+      const agentBReasoning = agentB?.inlineParts?.find((part) => part.type === "reasoning");
+      const agentBText = agentB?.inlineParts?.find((part) => part.type === "text");
+      expect(agentBReasoning?.type).toBe("reasoning");
+      expect(agentBText?.type).toBe("text");
+      if (agentBReasoning?.type === "reasoning") {
+        expect(agentBReasoning.content).toBe("buffered agent-b reasoning");
+      }
+      if (agentBText?.type === "text") {
+        expect(agentBText.content).toBe("buffered agent-b text");
+      }
+
+      expect(agentA?.inlineParts?.some(
+        (part) => part.type === "reasoning" && part.content.includes("agent-b"),
+      )).toBe(false);
+      expect(agentB?.inlineParts?.some(
+        (part) => part.type === "text" && part.content.includes("agent-a"),
+      )).toBe(false);
+    } finally {
+      dispose();
+    }
+  });
+});
diff --git a/src/ui/parts/guards.test.ts b/src/ui/parts/guards.test.ts
index ce84b8cc26..75028460fc 100644
--- a/src/ui/parts/guards.test.ts
+++ b/src/ui/parts/guards.test.ts
@@ -84,6 +84,26 @@ describe("hasActiveForegroundAgents", () => {
     ];
     expect(hasActiveForegroundAgents(agents)).toBe(false);
   });
+
+  test("returns false for shadow foreground agent tied to active background agent", () => {
+    const agents = [
+      createMockAgent({
+        id: "bg-1",
+        name: "Researcher",
+        status: "background",
+        background: true,
+        taskToolCallId: "bg-1",
+      }),
+      createMockAgent({
+        id: "fg-shadow-1",
+        name: "Researcher",
+        status: "running",
+        background: false,
+        taskToolCallId: "bg-1",
+      }),
+    ];
+    expect(hasActiveForegroundAgents(agents)).toBe(false);
+  });
 });
 
 describe("shouldFinalizeDeferredStream", () => {
diff --git a/src/ui/parts/guards.ts b/src/ui/parts/guards.ts
index 54942ec83d..0005d90f33 100644
--- a/src/ui/parts/guards.ts
+++ b/src/ui/parts/guards.ts
@@ -7,6 +7,7 @@
  */
 
 import type { ParallelAgent } from "../components/parallel-agents-tree.tsx";
+import { isShadowForegroundAgent } from "../utils/background-agent-footer.ts";
 
 /**
  * Determines whether an agent should be finalized when a tool completes.
@@ -30,7 +31,8 @@ export function hasActiveForegroundAgents(agents: readonly ParallelAgent[]): boo
   return agents.some(
     (agent) =>
       (agent.status === "running" || agent.status === "pending")
-      && shouldFinalizeOnToolComplete(agent),
+      && shouldFinalizeOnToolComplete(agent)
+      && !isShadowForegroundAgent(agent, agents),
   );
 }
 
diff --git a/src/ui/parts/handlers.test.ts b/src/ui/parts/handlers.test.ts
index 25ff8ba8a8..37ce23e86d 100644
--- a/src/ui/parts/handlers.test.ts
+++ b/src/ui/parts/handlers.test.ts
@@ -25,8 +25,8 @@ describe("handleTextDelta", () => {
     expect((result.parts![0] as TextPart).content).toBe("Hello World");
   });
 
-  test("creates new TextPart when last TextPart is not streaming", () => {
-    // Simulate finalized TextPart (after tool boundary)
+  test("merges continuation into finalized TextPart when no paragraph break", () => {
+    // Simulate finalized TextPart (after tool boundary) with mid-sentence continuation
     const msg = {
       parts: [{
         id: "part_000000000001_0001" as any,
@@ -36,6 +36,38 @@ describe("handleTextDelta", () => {
         createdAt: new Date().toISOString(),
       }],
     } as unknown as ChatMessage;
+    const result = handleTextDelta(msg, " continuation");
+    expect(result.parts).toHaveLength(1);
+    expect((result.parts![0] as TextPart).content).toBe("Before tool continuation");
+    expect((result.parts![0] as TextPart).isStreaming).toBe(false);
+  });
+
+  test("creates new TextPart when delta starts with paragraph break", () => {
+    const msg = {
+      parts: [{
+        id: "part_000000000001_0001" as any,
+        type: "text",
+        content: "Before tool",
+        isStreaming: false,
+        createdAt: new Date().toISOString(),
+      }],
+    } as unknown as ChatMessage;
+    const result = handleTextDelta(msg, "\n\nAfter tool");
+    expect(result.parts).toHaveLength(2);
+    expect((result.parts![1] as TextPart).content).toBe("\n\nAfter tool");
+    expect((result.parts![1] as TextPart).isStreaming).toBe(true);
+  });
+
+  test("creates new TextPart when previous ends with paragraph break", () => {
+    const msg = {
+      parts: [{
+        id: "part_000000000001_0001" as any,
+        type: "text",
+        content: "Before tool\n\n",
+        isStreaming: false,
+        createdAt: new Date().toISOString(),
+      }],
+    } as unknown as ChatMessage;
     const result = handleTextDelta(msg, "After tool");
     expect(result.parts).toHaveLength(2);
     expect((result.parts![1] as TextPart).content).toBe("After tool");
diff --git a/src/ui/parts/handlers.ts b/src/ui/parts/handlers.ts
index a46a0bc353..0981ba7c5c 100644
--- a/src/ui/parts/handlers.ts
+++ b/src/ui/parts/handlers.ts
@@ -14,11 +14,9 @@ import { findLastPartIndex } from "./store.ts";
  * Handle text streaming delta with natural tool boundary splitting.
  *
  * - If the last TextPart is still streaming (isStreaming: true), append delta to it
- * - If the last TextPart is NOT streaming (finalized at tool boundary) or no TextPart exists,
- *   create a new TextPart
- *
- * This naturally handles tool-boundary text splitting where text before a tool
- * is in one TextPart and text after is in a new TextPart.
+ * - If the last TextPart is finalized but the delta is a mid-sentence continuation
+ *   (no \n\n paragraph break), merge back to avoid orphaned fragments
+ * - Otherwise create a new TextPart for text after a tool completes
  */
 export function handleTextDelta(msg: ChatMessage, delta: string): ChatMessage {
   const parts = [...(msg.parts ?? [])];
@@ -28,8 +26,19 @@ export function handleTextDelta(msg: ChatMessage, delta: string): ChatMessage {
     // Append to existing streaming TextPart
     const textPart = parts[lastTextIdx] as TextPart;
     parts[lastTextIdx] = { ...textPart, content: textPart.content + delta };
+  } else if (
+    lastTextIdx >= 0 &&
+    lastTextIdx === parts.length - 1 &&
+    !delta.startsWith("\n\n") &&
+    !(parts[lastTextIdx] as TextPart).content.endsWith("\n\n")
+  ) {
+    // The previous TextPart was finalized at a tool boundary but the new
+    // delta continues the same paragraph (no \n\n separator). Merge back
+    // to avoid orphaned text fragments (e.g., trailing ":" on its own line).
+    const textPart = parts[lastTextIdx] as TextPart;
+    parts[lastTextIdx] = { ...textPart, content: textPart.content + delta };
   } else {
-    // Create new TextPart (text after tool completes)
+    // Create new TextPart (new paragraph after tool completes)
     parts.push({
       id: createPartId(),
       type: "text" as const,
diff --git a/src/ui/parts/index.ts b/src/ui/parts/index.ts
index 249dcf941f..e75ba157b7 100644
--- a/src/ui/parts/index.ts
+++ b/src/ui/parts/index.ts
@@ -17,6 +17,8 @@ export {
   type SkillLoadPart,
   type McpSnapshotPart,
   type CompactionPart,
+  type TaskResultPart,
+  type WorkflowStepPart,
   type Part,
 } from "./types.ts";
 export { binarySearchById, upsertPart, findLastPartIndex } from "./store.ts";
@@ -31,6 +33,7 @@ export {
   type StreamPartEvent,
   applyStreamPartEvent,
   toToolState,
+  isSubagentToolName,
   shouldGroupSubagentTrees,
   mergeParallelAgentsIntoParts,
   syncToolCallsIntoParts,
diff --git a/src/ui/parts/stream-pipeline.test.ts b/src/ui/parts/stream-pipeline.test.ts
index dc8a92b8b2..e4394a35ea 100644
--- a/src/ui/parts/stream-pipeline.test.ts
+++ b/src/ui/parts/stream-pipeline.test.ts
@@ -56,6 +56,96 @@ describe("applyStreamPartEvent", () => {
     expect(next.parts).toHaveLength(0);
   });
 
+  test("maps workflow task updates with blockedBy into task-list parts", () => {
+    const msg = createAssistantMessage();
+    const next = applyStreamPartEvent(msg, {
+      type: "task-list-update",
+      tasks: [
+        { id: "#1", title: "Plan", status: "completed", blockedBy: [] },
+        { id: "#2", title: "Implement", status: "pending", blockedBy: ["#1"] },
+      ],
+    });
+
+    const taskListPart = next.parts?.find((part) => part.type === "task-list");
+    expect(taskListPart?.type).toBe("task-list");
+    if (taskListPart?.type === "task-list") {
+      expect(taskListPart.items).toEqual([
+        { id: "#1", content: "Plan", status: "completed", blockedBy: [] },
+        { id: "#2", content: "Implement", status: "pending", blockedBy: ["#1"] },
+      ]);
+    }
+  });
+
+  test("upserts task result parts from workflow task result envelopes", () => {
+    const msg = createAssistantMessage();
+    const withResult = applyStreamPartEvent(msg, {
+      type: "task-result-upsert",
+      envelope: {
+        task_id: "#7",
+        tool_name: "task",
+        title: "Implement registry",
+        status: "completed",
+        output_text: "Implemented",
+        envelope_text: "task_id: #7",
+      },
+    });
+
+    const taskResultPart = withResult.parts?.find((part) => part.type === "task-result");
+    expect(taskResultPart?.type).toBe("task-result");
+    if (taskResultPart?.type === "task-result") {
+      expect(taskResultPart.taskId).toBe("#7");
+      expect(taskResultPart.status).toBe("completed");
+      expect(taskResultPart.outputText).toBe("Implemented");
+    }
+
+    const updated = applyStreamPartEvent(withResult, {
+      type: "task-result-upsert",
+      envelope: {
+        task_id: "#7",
+        tool_name: "task",
+        title: "Implement registry",
+        status: "error",
+        output_text: "Failed",
+        error: "lint failed",
+      },
+    });
+
+    const updatedTaskResultPart = updated.parts?.find((part) => part.type === "task-result");
+    expect(updatedTaskResultPart?.type).toBe("task-result");
+    if (updatedTaskResultPart?.type === "task-result") {
+      expect(updatedTaskResultPart.status).toBe("error");
+      expect(updatedTaskResultPart.error).toBe("lint failed");
+      expect(updatedTaskResultPart.outputText).toBe("Failed");
+    }
+    expect((updated.parts ?? []).filter((part) => part.type === "task-result")).toHaveLength(1);
+  });
+
+  test("ignores workflow step events", () => {
+    const msg = createAssistantMessage();
+    const startedAt = "2026-03-01T00:00:00.000Z";
+    const completedAt = "2026-03-01T00:00:02.000Z";
+
+    const withStepStart = applyStreamPartEvent(msg, {
+      type: "workflow-step-start",
+      workflowId: "wf-1",
+      nodeId: "worker",
+      nodeName: "Worker Node",
+      startedAt,
+    });
+
+    expect(withStepStart.parts ?? []).toHaveLength(0);
+
+    const withStepComplete = applyStreamPartEvent(withStepStart, {
+      type: "workflow-step-complete",
+      workflowId: "wf-1",
+      nodeId: "worker",
+      status: "success",
+      completedAt,
+    });
+
+    expect(withStepComplete.parts ?? []).toHaveLength(0);
+  });
+
   test("streams thinking as a dedicated reasoning part when enabled", () => {
     let msg = createAssistantMessage();
     msg = applyStreamPartEvent(msg, {
@@ -297,7 +387,21 @@ describe("applyStreamPartEvent", () => {
     expect((next.parts ?? []).filter((part) => part.type === "reasoning")).toHaveLength(1);
   });
 
-  test("handles tool start by finalizing text and inserting a tool part", () => {
+  test("text-complete is a no-op in the reducer (reconciliation handled upstream)", () => {
+    const msg = createAssistantMessage();
+    const withDelta = applyStreamPartEvent(msg, { type: "text-delta", delta: "Hello" });
+    const next = applyStreamPartEvent(withDelta, {
+      type: "text-complete",
+      fullText: "Hello World",
+      messageId: "msg-test",
+    });
+
+    // The reducer returns the message unchanged — reconciliation happens in useStreamConsumer
+    expect(next).toBe(withDelta);
+    expect(next.content).toBe("Hello");
+  });
+
+  test("handles tool start by finalizing active text", () => {
     let msg = createAssistantMessage();
     msg = applyStreamPartEvent(msg, { type: "text-delta", delta: "Before tool" });
 
@@ -377,7 +481,51 @@ describe("applyStreamPartEvent", () => {
     }
   });
 
-  test("keeps thinking, pre-tool text, and post-tool text segmented", () => {
+  test("accumulates partial output on running tool part", () => {
+    let msg = createAssistantMessage();
+    msg = applyStreamPartEvent(msg, {
+      type: "tool-start",
+      toolId: "tool_1",
+      toolName: "bash",
+      input: { command: "ls -la" },
+    });
+
+    msg = applyStreamPartEvent(msg, {
+      type: "tool-partial-result",
+      toolId: "tool_1",
+      partialOutput: "file1.txt\n",
+    });
+
+    const toolPart1 = msg.parts?.find((p) => p.type === "tool" && p.toolCallId === "tool_1");
+    expect(toolPart1?.type).toBe("tool");
+    if (toolPart1?.type === "tool") {
+      expect(toolPart1.partialOutput).toBe("file1.txt\n");
+      expect(toolPart1.state.status).toBe("running");
+    }
+
+    msg = applyStreamPartEvent(msg, {
+      type: "tool-partial-result",
+      toolId: "tool_1",
+      partialOutput: "file2.txt\n",
+    });
+
+    const toolPart2 = msg.parts?.find((p) => p.type === "tool" && p.toolCallId === "tool_1");
+    if (toolPart2?.type === "tool") {
+      expect(toolPart2.partialOutput).toBe("file1.txt\nfile2.txt\n");
+    }
+  });
+
+  test("ignores partial result for unknown tool id", () => {
+    const msg = createAssistantMessage();
+    const next = applyStreamPartEvent(msg, {
+      type: "tool-partial-result",
+      toolId: "nonexistent",
+      partialOutput: "output",
+    });
+    expect(next.parts).toHaveLength(0);
+  });
+
+  test("keeps thinking, pre-tool text, and post-tool text segmented for visible tools", () => {
     let msg = createAssistantMessage();
     msg = applyStreamPartEvent(msg, {
       type: "thinking-meta",
@@ -424,6 +572,119 @@ describe("applyStreamPartEvent", () => {
     }
   });
 
+  test("splits text blocks when TodoWrite interleaves mid-stream", () => {
+    let msg = createAssistantMessage();
+    msg = applyStreamPartEvent(msg, { type: "text-delta", delta: "Draft answer" });
+
+    msg = applyStreamPartEvent(msg, {
+      type: "tool-start",
+      toolId: "tool_todo_1",
+      toolName: "TodoWrite",
+      input: { todos: [] },
+    });
+
+    msg = applyStreamPartEvent(msg, {
+      type: "tool-complete",
+      toolId: "tool_todo_1",
+      toolName: "TodoWrite",
+      output: { ok: true },
+      success: true,
+    });
+
+    const next = applyStreamPartEvent(msg, { type: "text-delta", delta: " after todo" });
+
+    expect(next.content).toBe("Draft answer after todo");
+    expect(next.parts?.map((part) => part.type)).toEqual(["text", "tool", "text"]);
+
+    const firstText = next.parts?.[0];
+    expect(firstText?.type).toBe("text");
+    if (firstText?.type === "text") {
+      expect(firstText.content).toBe("Draft answer");
+      expect(firstText.isStreaming).toBe(false);
+    }
+
+    const secondText = next.parts?.[2];
+    expect(secondText?.type).toBe("text");
+    if (secondText?.type === "text") {
+      expect(secondText.content).toBe(" after todo");
+      expect(secondText.isStreaming).toBe(true);
+    }
+  });
+
+  test("keeps sentence punctuation separated across TodoWrite boundaries", () => {
+    let msg = createAssistantMessage();
+    msg = applyStreamPartEvent(msg, {
+      type: "text-delta",
+      delta: "Now I have full context of the codebase. Let me set up the research plan and spawn parallel agents.",
+    });
+
+    msg = applyStreamPartEvent(msg, {
+      type: "tool-start",
+      toolId: "tool_todo_2",
+      toolName: "TodoWrite",
+      input: { todos: [{ content: "Spawn research agents", status: "in_progress" }] },
+    });
+
+    msg = applyStreamPartEvent(msg, {
+      type: "tool-complete",
+      toolId: "tool_todo_2",
+      toolName: "TodoWrite",
+      output: { ok: true },
+      success: true,
+    });
+
+    const next = applyStreamPartEvent(msg, {
+      type: "text-delta",
+      delta: "Now let me spawn parallel research agents.",
+    });
+
+    expect(next.content).toBe(
+      "Now I have full context of the codebase. Let me set up the research plan and spawn parallel agents.Now let me spawn parallel research agents.",
+    );
+    expect(next.parts?.map((part) => part.type)).toEqual(["text", "tool", "text"]);
+
+    const preToolText = next.parts?.[0];
+    expect(preToolText?.type).toBe("text");
+    if (preToolText?.type === "text") {
+      expect(preToolText.content).toBe(
+        "Now I have full context of the codebase. Let me set up the research plan and spawn parallel agents.",
+      );
+      expect(preToolText.isStreaming).toBe(false);
+    }
+
+    const postToolText = next.parts?.[2];
+    expect(postToolText?.type).toBe("text");
+    if (postToolText?.type === "text") {
+      expect(postToolText.content).toBe("Now let me spawn parallel research agents.");
+      expect(postToolText.isStreaming).toBe(true);
+    }
+  });
+
+  test("starts a separate block for TaskOutput tools", () => {
+    let msg = createAssistantMessage();
+    msg = applyStreamPartEvent(msg, { type: "text-delta", delta: "Waiting..." });
+
+    const next = applyStreamPartEvent(msg, {
+      type: "tool-start",
+      toolId: "task_output_1",
+      toolName: "TaskOutput",
+      input: { task_id: "agent-1", block: true },
+    });
+
+    expect(next.parts?.map((part) => part.type)).toEqual(["text", "tool"]);
+    const textPart = next.parts?.[0];
+    expect(textPart?.type).toBe("text");
+    if (textPart?.type === "text") {
+      expect(textPart.content).toBe("Waiting...");
+      expect(textPart.isStreaming).toBe(false);
+    }
+    const toolPart = next.parts?.[1];
+    expect(toolPart?.type).toBe("tool");
+    if (toolPart?.type === "tool") {
+      expect(toolPart.toolName).toBe("TaskOutput");
+    }
+  });
+
   test("stores HITL request and response on matching tool part", () => {
     let msg = createAssistantMessage();
     msg = applyStreamPartEvent(msg, {
@@ -501,6 +762,237 @@ describe("applyStreamPartEvent", () => {
     }
   });
 
+  test("routes agent thinking-meta into inlineParts", () => {
+    let msg = createAssistantMessage();
+    msg = applyStreamPartEvent(msg, {
+      type: "tool-start",
+      toolId: "task_1",
+      toolName: "Task",
+      input: { description: "Investigate" },
+    });
+    msg = applyStreamPartEvent(msg, {
+      type: "parallel-agents",
+      agents: [
+        {
+          id: "agent_1",
+          taskToolCallId: "task_1",
+          name: "researcher",
+          task: "Investigate",
+          status: "running",
+          startedAt: new Date().toISOString(),
+        },
+      ],
+      isLastMessage: true,
+    });
+
+    const next = applyStreamPartEvent(msg, {
+      type: "thinking-meta",
+      thinkingSourceKey: "agent:source",
+      targetMessageId: "msg-test",
+      streamGeneration: 1,
+      thinkingMs: 350,
+      thinkingText: "agent reasoning",
+      includeReasoningPart: true,
+      agentId: "agent_1",
+    });
+
+    expect((next.parts ?? []).some((part) => part.type === "reasoning")).toBe(false);
+    const agentPart = next.parts?.find((part) => part.type === "agent");
+    expect(agentPart?.type).toBe("agent");
+    if (agentPart?.type === "agent") {
+      const inlineReasoning = agentPart.agents[0]?.inlineParts?.find((part) => part.type === "reasoning");
+      expect(inlineReasoning?.type).toBe("reasoning");
+      if (inlineReasoning?.type === "reasoning") {
+        expect(inlineReasoning.content).toBe("agent reasoning");
+        expect(inlineReasoning.thinkingSourceKey).toBe("agent:source");
+        expect(inlineReasoning.durationMs).toBe(350);
+      }
+    }
+  });
+
+  test("keeps agent-scoped tool events out of top-level toolCalls", () => {
+    let msg = createAssistantMessage();
+    msg = applyStreamPartEvent(msg, {
+      type: "tool-start",
+      toolId: "task_1",
+      toolName: "Task",
+      input: { description: "Investigate" },
+    });
+    msg = applyStreamPartEvent(msg, {
+      type: "parallel-agents",
+      agents: [
+        {
+          id: "agent_1",
+          taskToolCallId: "task_1",
+          name: "researcher",
+          task: "Investigate",
+          status: "running",
+          startedAt: new Date().toISOString(),
+        },
+      ],
+      isLastMessage: true,
+    });
+
+    msg = applyStreamPartEvent(msg, {
+      type: "tool-start",
+      toolId: "agent_tool_1",
+      toolName: "Read",
+      input: { filePath: "src/ui/chat.tsx" },
+      agentId: "agent_1",
+    });
+    msg = applyStreamPartEvent(msg, {
+      type: "tool-complete",
+      toolId: "agent_tool_1",
+      toolName: "Read",
+      output: "ok",
+      success: true,
+      agentId: "agent_1",
+    });
+
+    expect(msg.toolCalls?.map((toolCall) => toolCall.id)).toEqual(["task_1"]);
+    const topLevelToolIds = (msg.parts ?? [])
+      .filter((part) => part.type === "tool")
+      .map((part) => part.toolCallId);
+    expect(topLevelToolIds).toEqual(["task_1"]);
+
+    const agentPart = msg.parts?.find((part) => part.type === "agent");
+    expect(agentPart?.type).toBe("agent");
+    if (agentPart?.type === "agent") {
+      const inlineTool = agentPart.agents[0]?.inlineParts?.find(
+        (part) => part.type === "tool" && part.toolCallId === "agent_tool_1",
+      );
+      expect(inlineTool?.type).toBe("tool");
+      if (inlineTool?.type === "tool") {
+        expect(inlineTool.state.status).toBe("completed");
+      }
+    }
+  });
+
+  test("mirrors agent-scoped TaskOutput into top-level tool blocks", () => {
+    let msg = createAssistantMessage();
+    msg = applyStreamPartEvent(msg, { type: "text-delta", delta: "Waiting for agents..." });
+
+    msg = applyStreamPartEvent(msg, {
+      type: "tool-start",
+      toolId: "task_output_agent_1",
+      toolName: "TaskOutput",
+      input: { task_id: "agent_1", block: true },
+      agentId: "agent_1",
+    });
+    msg = applyStreamPartEvent(msg, {
+      type: "tool-complete",
+      toolId: "task_output_agent_1",
+      toolName: "TaskOutput",
+      output: { retrieval_status: "timeout", task: null },
+      success: true,
+      agentId: "agent_1",
+    });
+
+    expect(msg.toolCalls?.map((toolCall) => toolCall.id)).toEqual(["task_output_agent_1"]);
+    expect(msg.parts?.map((part) => part.type)).toEqual(["text", "tool"]);
+
+    const textPart = msg.parts?.[0];
+    expect(textPart?.type).toBe("text");
+    if (textPart?.type === "text") {
+      expect(textPart.content).toBe("Waiting for agents...");
+      expect(textPart.isStreaming).toBe(false);
+    }
+
+    const toolPart = msg.parts?.[1];
+    expect(toolPart?.type).toBe("tool");
+    if (toolPart?.type === "tool") {
+      expect(toolPart.toolName).toBe("TaskOutput");
+      expect(toolPart.state.status).toBe("completed");
+    }
+  });
+
+  test("separates main-text updates after mirrored TaskOutput boundaries", () => {
+    let msg = createAssistantMessage();
+    msg = applyStreamPartEvent(msg, {
+      type: "text-delta",
+      delta: "Waiting for all agents to complete before synthesizing the findings into a comprehensive research document...",
+    });
+
+    msg = applyStreamPartEvent(msg, {
+      type: "tool-start",
+      toolId: "task_output_agent_2",
+      toolName: "TaskOutput",
+      input: { task_id: "agent_2", block: true },
+      agentId: "agent_2",
+    });
+
+    const next = applyStreamPartEvent(msg, {
+      type: "text-delta",
+      delta: "First agent completed. Waiting for the remaining three...",
+    });
+
+    expect(next.parts?.map((part) => part.type)).toEqual(["text", "tool", "text"]);
+    const preToolText = next.parts?.[0];
+    expect(preToolText?.type).toBe("text");
+    if (preToolText?.type === "text") {
+      expect(preToolText.content).toBe(
+        "Waiting for all agents to complete before synthesizing the findings into a comprehensive research document...",
+      );
+      expect(preToolText.isStreaming).toBe(false);
+    }
+    const postToolText = next.parts?.[2];
+    expect(postToolText?.type).toBe("text");
+    if (postToolText?.type === "text") {
+      expect(postToolText.content).toBe("First agent completed. Waiting for the remaining three...");
+      expect(postToolText.isStreaming).toBe(true);
+    }
+  });
+
+  test("replays buffered agent thinking-meta into inlineParts when agent appears", () => {
+    let msg = createAssistantMessage();
+    msg = applyStreamPartEvent(msg, {
+      type: "tool-start",
+      toolId: "task_1",
+      toolName: "Task",
+      input: { description: "Investigate" },
+    });
+
+    msg = applyStreamPartEvent(msg, {
+      type: "thinking-meta",
+      thinkingSourceKey: "agent:source",
+      targetMessageId: "msg-test",
+      streamGeneration: 1,
+      thinkingMs: 510,
+      thinkingText: "buffered agent reasoning",
+      includeReasoningPart: true,
+      agentId: "agent_1",
+    });
+
+    expect((msg.parts ?? []).some((part) => part.type === "reasoning")).toBe(false);
+
+    const next = applyStreamPartEvent(msg, {
+      type: "parallel-agents",
+      agents: [
+        {
+          id: "agent_1",
+          taskToolCallId: "task_1",
+          name: "researcher",
+          task: "Investigate",
+          status: "running",
+          startedAt: new Date().toISOString(),
+        },
+      ],
+      isLastMessage: true,
+    });
+
+    const agentPart = next.parts?.find((part) => part.type === "agent");
+    expect(agentPart?.type).toBe("agent");
+    if (agentPart?.type === "agent") {
+      const inlineReasoning = agentPart.agents[0]?.inlineParts?.find((part) => part.type === "reasoning");
+      expect(inlineReasoning?.type).toBe("reasoning");
+      if (inlineReasoning?.type === "reasoning") {
+        expect(inlineReasoning.content).toBe("buffered agent reasoning");
+        expect(inlineReasoning.thinkingSourceKey).toBe("agent:source");
+        expect(inlineReasoning.durationMs).toBe(510);
+      }
+    }
+  });
+
   test("returns to main text stream after subagent completion", () => {
     let msg = createAssistantMessage();
     msg = applyStreamPartEvent(msg, {
diff --git a/src/ui/parts/stream-pipeline.ts b/src/ui/parts/stream-pipeline.ts
index 786cb4e0c0..ca508cd528 100644
--- a/src/ui/parts/stream-pipeline.ts
+++ b/src/ui/parts/stream-pipeline.ts
@@ -9,6 +9,7 @@ import type { ChatMessage, MessageToolCall } from "../chat.tsx";
 import type { ParallelAgent } from "../components/parallel-agents-tree.tsx";
 import type { HitlResponseRecord } from "../utils/hitl-response.ts";
 import type { PermissionOption } from "../../sdk/types.ts";
+import type { WorkflowRuntimeTaskResultEnvelope } from "../../workflows/runtime-contracts.ts";
 import { type PartId, createPartId } from "./id.ts";
 import { upsertPart, findLastPartIndex } from "./store.ts";
 import { handleTextDelta } from "./handlers.ts";
@@ -17,6 +18,8 @@ import type {
   AgentPart,
   Part,
   ReasoningPart,
+  TaskResultPart,
+  TaskListPart,
   TextPart,
   ToolPart,
   ToolState,
@@ -30,20 +33,33 @@ interface ToolStartEvent {
   toolName: string;
   input: Record<string, unknown>;
   startedAt?: string;
+  /** Sub-agent ID if this event is scoped to a workflow sub-agent */
+  agentId?: string;
 }
 
 interface ToolCompleteEvent {
   type: "tool-complete";
   toolId: string;
+  toolName?: string;
   output: unknown;
   success: boolean;
   error?: string;
   input?: Record<string, unknown>;
+  /** Sub-agent ID if this event is scoped to a workflow sub-agent */
+  agentId?: string;
 }
 
 interface TextDeltaEvent {
   type: "text-delta";
   delta: string;
+  /** Sub-agent ID if this event is scoped to a workflow sub-agent */
+  agentId?: string;
+}
+
+interface TextCompleteEvent {
+  type: "text-complete";
+  fullText: string;
+  messageId: string;
 }
 
 export type ThinkingProvider = "claude" | "opencode" | "copilot" | "unknown";
@@ -55,6 +71,8 @@ export interface ThinkingMetaEvent {
   streamGeneration: number;
   thinkingText: string;
   thinkingMs: number;
+  /** Sub-agent ID if this event is scoped to a workflow sub-agent */
+  agentId?: string;
   /**
    * Off by default to keep current UI behavior until dedicated
    * reasoning rendering task is complete.
@@ -88,14 +106,61 @@ interface ParallelAgentsEvent {
   isLastMessage: boolean;
 }
 
+interface TaskListUpdateEvent {
+  type: "task-list-update";
+  tasks: Array<{
+    id: string;
+    title: string;
+    status: string;
+    blockedBy?: string[];
+  }>;
+}
+
+interface WorkflowStepStartEvent {
+  type: "workflow-step-start";
+  workflowId: string;
+  nodeId: string;
+  nodeName: string;
+  startedAt?: string;
+}
+
+interface WorkflowStepCompleteEvent {
+  type: "workflow-step-complete";
+  workflowId: string;
+  nodeId: string;
+  nodeName?: string;
+  status: "success" | "error" | "skipped";
+  result?: unknown;
+  completedAt?: string;
+}
+
+interface TaskResultUpsertEvent {
+  type: "task-result-upsert";
+  envelope: WorkflowRuntimeTaskResultEnvelope;
+}
+
+interface ToolPartialResultEvent {
+  type: "tool-partial-result";
+  toolId: string;
+  partialOutput: string;
+  /** Sub-agent ID if this event is scoped to a workflow sub-agent */
+  agentId?: string;
+}
+
 export type StreamPartEvent =
   | TextDeltaEvent
+  | TextCompleteEvent
   | ThinkingMetaEvent
   | ToolStartEvent
   | ToolCompleteEvent
+  | ToolPartialResultEvent
   | HitlRequestEvent
   | HitlResponseEvent
-  | ParallelAgentsEvent;
+  | ParallelAgentsEvent
+  | TaskListUpdateEvent
+  | WorkflowStepStartEvent
+  | WorkflowStepCompleteEvent
+  | TaskResultUpsertEvent;
 
 const reasoningPartIdBySourceRegistry = new WeakMap<ChatMessage, Map<string, PartId>>();
 
@@ -103,6 +168,10 @@ function isHitlToolName(toolName: string): boolean {
   return toolName === "AskUserQuestion" || toolName === "question" || toolName === "ask_user";
 }
 
+function isTaskOutputToolName(toolName: string | undefined): boolean {
+  return (toolName ?? "").trim().toLowerCase() === "taskoutput";
+}
+
 export function toToolState(
   status: ToolStatus,
   output: unknown,
@@ -131,8 +200,14 @@ export function toToolState(
           : (typeof output === "string" && output.trim() ? output : "Tool execution failed"),
         output,
       };
-    case "interrupted":
-      return { status: "interrupted", partialOutput: output };
+    case "interrupted": {
+      let durationMs: number | undefined;
+      if (existingState?.status === "running") {
+        const startedAtMs = new Date(existingState.startedAt).getTime();
+        durationMs = Number.isFinite(startedAtMs) ? Math.max(0, Date.now() - startedAtMs) : undefined;
+      }
+      return { status: "interrupted", partialOutput: output, durationMs };
+    }
   }
 }
 
@@ -151,28 +226,31 @@ function finalizeLastStreamingTextPart(parts: Part[]): Part[] {
   return updated;
 }
 
-export function finalizeStreamingReasoningParts(parts: Part[]): Part[] {
+export function finalizeStreamingReasoningParts(parts: Part[], fallbackDurationMs?: number): Part[] {
   let changed = false;
   const updated = parts.map((part) => {
     if (part.type !== "reasoning" || !part.isStreaming) {
       return part;
     }
     changed = true;
+    const rp = part as ReasoningPart;
     return {
-      ...part,
+      ...rp,
       isStreaming: false,
+      // Use existing durationMs if available, otherwise fall back to message-level thinkingMs
+      durationMs: rp.durationMs || fallbackDurationMs || 0,
     };
   });
 
   return changed ? updated : parts;
 }
 
-export function finalizeStreamingReasoningInMessage<T extends { parts?: Part[] }>(message: T): T {
+export function finalizeStreamingReasoningInMessage<T extends { parts?: Part[]; thinkingMs?: number }>(message: T): T {
   if (!message.parts || message.parts.length === 0) {
     return message;
   }
 
-  const finalizedParts = finalizeStreamingReasoningParts(message.parts);
+  const finalizedParts = finalizeStreamingReasoningParts(message.parts, message.thinkingMs);
   if (finalizedParts === message.parts) {
     return message;
   }
@@ -253,7 +331,11 @@ function upsertToolPartStart(parts: Part[], event: ToolStartEvent): Part[] {
     return updated;
   }
 
-  const finalized = finalizeLastStreamingTextPart(parts);
+  // Always finalize the currently streaming text part before a tool block.
+  // This preserves visible tool boundaries in the transcript and prevents
+  // punctuation/text from being merged across interleaved tool calls.
+  const baseParts = finalizeLastStreamingTextPart(parts);
+
   const toolPart: ToolPart = {
     id: createPartId(),
     type: "tool",
@@ -263,7 +345,7 @@ function upsertToolPartStart(parts: Part[], event: ToolStartEvent): Part[] {
     state: { status: "running", startedAt: event.startedAt ?? new Date().toISOString() },
     createdAt: new Date().toISOString(),
   };
-  return upsertPart(finalized, toolPart);
+  return upsertPart(baseParts, toolPart);
 }
 
 function upsertToolCallComplete(
@@ -278,8 +360,12 @@ function upsertToolCallComplete(
     const updatedInput = (event.input && Object.keys(toolCall.input).length === 0)
       ? event.input
       : toolCall.input;
+    const updatedToolName = toolCall.toolName === "unknown"
+      ? (event.toolName ?? "unknown")
+      : toolCall.toolName;
     return {
       ...toolCall,
+      toolName: updatedToolName,
       input: updatedInput,
       output: mergeToolCallOutput(toolCall, event.output),
       status: event.success ? ("completed" as const) : ("error" as const),
@@ -292,7 +378,7 @@ function upsertToolCallComplete(
     ...updated,
     {
       id: event.toolId,
-      toolName: "unknown",
+      toolName: event.toolName ?? "unknown",
       input: event.input ?? {},
       output: event.output,
       status: event.success ? ("completed" as const) : ("error" as const),
@@ -324,6 +410,7 @@ function upsertToolPartComplete(parts: Part[], event: ToolCompleteEvent): Part[]
     const updated = [...parts];
     updated[toolPartIdx] = {
       ...existing,
+      toolName: existing.toolName === "unknown" ? (event.toolName ?? "unknown") : existing.toolName,
       input: updatedInput,
       output: event.output,
       state: newState,
@@ -335,7 +422,7 @@ function upsertToolPartComplete(parts: Part[], event: ToolCompleteEvent): Part[]
     id: createPartId(),
     type: "tool",
     toolCallId: event.toolId,
-    toolName: "unknown",
+    toolName: event.toolName ?? "unknown",
     input: event.input ?? {},
     output: event.output,
     state: event.success
@@ -494,6 +581,51 @@ function upsertThinkingMeta(
   return nextMessage;
 }
 
+function upsertThinkingMetaPart(parts: Part[], event: ThinkingMetaEvent): Part[] {
+  if (!event.includeReasoningPart) {
+    return parts;
+  }
+
+  const existingIdx = parts.findIndex(
+    (part) => part.type === "reasoning" && (part as ReasoningPart).thinkingSourceKey === event.thinkingSourceKey,
+  );
+
+  if (existingIdx >= 0) {
+    const existing = parts[existingIdx] as ReasoningPart;
+    const updated = [...parts];
+    updated[existingIdx] = {
+      ...existing,
+      thinkingSourceKey: event.thinkingSourceKey,
+      content: event.thinkingText,
+      durationMs: event.thinkingMs,
+      isStreaming: true,
+    };
+    return updated;
+  }
+
+  if (event.thinkingText.trim().length === 0) {
+    return parts;
+  }
+
+  const reasoningPart: ReasoningPart = {
+    id: createPartId(),
+    type: "reasoning",
+    thinkingSourceKey: event.thinkingSourceKey,
+    content: event.thinkingText,
+    durationMs: event.thinkingMs,
+    isStreaming: true,
+    createdAt: new Date().toISOString(),
+  };
+  const updated = [...parts];
+  const firstTextIdx = updated.findIndex((part) => part.type === "text");
+  if (firstTextIdx >= 0) {
+    updated.splice(firstTextIdx, 0, reasoningPart);
+  } else {
+    updated.push(reasoningPart);
+  }
+  return updated;
+}
+
 function cloneReasoningPartRegistry(message: ChatMessage): Map<string, PartId> {
   const existing = reasoningPartIdBySourceRegistry.get(message);
   if (existing) {
@@ -521,18 +653,26 @@ function carryReasoningPartRegistry(from: ChatMessage, to: ChatMessage): ChatMes
   return to;
 }
 
-function isActiveParallelAgent(agent: ParallelAgent): boolean {
-  return (
-    agent.status === "running"
-    || agent.status === "pending"
-    || agent.status === "background"
-  );
+/**
+ * Check if a tool name represents a sub-agent dispatch tool.
+ *
+ * Different SDKs use different tool names for sub-agent invocation:
+ * - OpenCode / Copilot: "Task" or "task"
+ * - Claude Agent SDK:   "Agent" or "agent"
+ * - Claude SDK (alt):   "launch_agent"
+ *
+ * This helper centralises the check so that the pipeline correctly
+ * recognises sub-agent tools regardless of which SDK emitted the event.
+ */
+export function isSubagentToolName(toolName: string): boolean {
+  const normalized = toolName.toLowerCase();
+  return normalized === "task" || normalized === "agent" || normalized === "launch_agent";
 }
 
 function hasSubagentCall(message: Pick<ChatMessage, "parallelAgents" | "toolCalls">): boolean {
   if ((message.parallelAgents?.length ?? 0) > 0) return true;
   return (message.toolCalls ?? []).some(
-    (toolCall) => toolCall.toolName === "Task" || toolCall.toolName === "task",
+    (toolCall) => isSubagentToolName(toolCall.toolName),
   );
 }
 
@@ -564,38 +704,14 @@ function normalizeParallelAgents(agents: ParallelAgent[]): ParallelAgent[] {
   return changed ? normalizedAgents : agents;
 }
 
-function isGroupedAgentPart(part: Part): part is AgentPart {
-  return part.type === "agent" && part.parentToolPartId === undefined;
-}
-
 export function shouldGroupSubagentTrees(
   message: Pick<ChatMessage, "parallelAgents" | "toolCalls" | "parts">,
-  isLastMessage: boolean,
+  _isLastMessage: boolean,
 ): boolean {
-  if (!isLastMessage) return false;
   const agents = message.parallelAgents ?? [];
   if (agents.length === 0) return false;
   if (!hasSubagentCall(message)) return false;
-
-  const parts = message.parts ?? [];
-  let hasSeenTask = false;
-  for (const part of parts) {
-    if (part.type === "tool") {
-      const toolName = part.toolName;
-      if (toolName === "Task" || toolName === "task") {
-        hasSeenTask = true;
-      } else {
-        return false;
-      }
-    } else if (part.type === "text") {
-      if (hasSeenTask && part.content.trim().length > 0) {
-        return false;
-      }
-    }
-  }
-
-  if (agents.some(isActiveParallelAgent)) return true;
-  return (message.parts ?? []).some(isGroupedAgentPart);
+  return true;
 }
 
 function getAgentInsertIndex(parts: Part[]): number {
@@ -607,7 +723,7 @@ function getAgentInsertIndex(parts: Part[]): number {
     if (!part || part.type !== "tool") continue;
     lastToolIdx = i;
     const toolName = (part as ToolPart).toolName;
-    if (toolName === "Task" || toolName === "task") {
+    if (isSubagentToolName(toolName)) {
       lastTaskToolIdx = i;
     }
   }
@@ -634,6 +750,106 @@ function insertAgentPartAtTaskBoundary(parts: Part[], agentPart: AgentPart): Par
   ];
 }
 
+/**
+ * Buffer for agent-scoped events that arrive before the AgentPart is created.
+ * Keyed by agentId → array of pending StreamPartEvents.
+ * Replayed when the parallel-agents event creates the AgentPart.
+ */
+const agentEventBuffer = new Map<string, StreamPartEvent[]>();
+
+/** Buffer an event for later replay when agent appears in parts. */
+function bufferAgentEvent(agentId: string, event: StreamPartEvent): void {
+  const existing = agentEventBuffer.get(agentId) ?? [];
+  existing.push(event);
+  agentEventBuffer.set(agentId, existing);
+}
+
+/** Drain buffered events for an agent and apply them to parts. */
+function drainBufferedEvents(parts: Part[], agentId: string): Part[] {
+  const buffered = agentEventBuffer.get(agentId);
+  if (!buffered || buffered.length === 0) return parts;
+
+  agentEventBuffer.delete(agentId);
+  let currentParts = parts;
+  for (const event of buffered) {
+    if (event.type === "text-delta" && event.agentId) {
+      const routed = routeToAgentInlineParts(currentParts, event.agentId, (inlineParts) => {
+        const lastText = inlineParts.length > 0 ? inlineParts[inlineParts.length - 1] : undefined;
+        if (lastText && lastText.type === "text" && (lastText as TextPart).isStreaming) {
+          const updated = [...inlineParts];
+          updated[updated.length - 1] = {
+            ...(lastText as TextPart),
+            content: (lastText as TextPart).content + event.delta,
+          };
+          return updated;
+        }
+        return [...inlineParts, {
+          id: createPartId(),
+          type: "text",
+          content: event.delta,
+          isStreaming: true,
+          createdAt: new Date().toISOString(),
+        } as TextPart];
+      });
+      if (routed) currentParts = routed;
+    } else if (event.type === "tool-start" && event.agentId) {
+      const routed = routeToAgentInlineParts(currentParts, event.agentId, (inlineParts) => {
+        return upsertToolPartStart(inlineParts, event);
+      });
+      if (routed) currentParts = routed;
+    } else if (event.type === "tool-complete" && event.agentId) {
+      const routed = routeToAgentInlineParts(currentParts, event.agentId, (inlineParts) => {
+        return upsertToolPartComplete(inlineParts, event);
+      });
+      if (routed) currentParts = routed;
+    } else if (event.type === "tool-partial-result" && event.agentId) {
+      const routed = routeToAgentInlineParts(currentParts, event.agentId, (inlineParts) => {
+        const updatedInlineParts = [...inlineParts];
+        const toolPartIdx = updatedInlineParts.findIndex(
+          (part) => part.type === "tool" && (part as ToolPart).toolCallId === event.toolId,
+        );
+        if (toolPartIdx >= 0) {
+          const existing = updatedInlineParts[toolPartIdx] as ToolPart;
+          updatedInlineParts[toolPartIdx] = {
+            ...existing,
+            partialOutput: (existing.partialOutput ?? "") + event.partialOutput,
+          };
+        }
+        return updatedInlineParts;
+      });
+      if (routed) currentParts = routed;
+    } else if (event.type === "thinking-meta" && event.agentId) {
+      const routed = routeToAgentInlineParts(currentParts, event.agentId, (inlineParts) => {
+        return upsertThinkingMetaPart(inlineParts, event);
+      });
+      if (routed) currentParts = routed;
+    }
+  }
+  return currentParts;
+}
+
+/**
+ * Carry over inlineParts from existing agents when re-merging from
+ * parallelAgents state updates. Without this, every parallel-agents
+ * event would wipe out accumulated streaming content.
+ */
+function carryOverInlineParts(
+  agents: ParallelAgent[],
+  existingInlineParts: Map<string, Part[]>,
+): ParallelAgent[] {
+  if (existingInlineParts.size === 0) return agents;
+  let changed = false;
+  const result = agents.map((agent) => {
+    const existing = existingInlineParts.get(agent.id);
+    if (existing && existing.length > 0 && (!agent.inlineParts || agent.inlineParts.length === 0)) {
+      changed = true;
+      return { ...agent, inlineParts: existing };
+    }
+    return agent;
+  });
+  return changed ? result : agents;
+}
+
 export function mergeParallelAgentsIntoParts(
   parts: Part[],
   parallelAgents: ParallelAgent[],
@@ -644,7 +860,21 @@ export function mergeParallelAgentsIntoParts(
   const nonAgentParts: Part[] = parts.filter((part) => part.type !== "agent");
   const existingAgentParts = parts.filter((part): part is AgentPart => part.type === "agent");
 
-  if (normalizedAgents.length === 0) {
+  // Build a lookup of existing agents' inlineParts so we don't lose
+  // streaming content when re-merging from parallelAgents state updates.
+  const existingInlineParts = new Map<string, Part[]>();
+  for (const agentPart of existingAgentParts) {
+    for (const agent of agentPart.agents) {
+      if (agent.inlineParts && agent.inlineParts.length > 0) {
+        existingInlineParts.set(agent.id, agent.inlineParts);
+      }
+    }
+  }
+
+  // Also replay any buffered events for agents that are now present
+  const mergedAgents = carryOverInlineParts(normalizedAgents, existingInlineParts);
+
+  if (mergedAgents.length === 0) {
     return nonAgentParts;
   }
 
@@ -653,7 +883,7 @@ export function mergeParallelAgentsIntoParts(
     const groupedPart: AgentPart = {
       id: existingGroupedPart?.id ?? createPartId(),
       type: "agent",
-      agents: normalizedAgents,
+      agents: mergedAgents,
       parentToolPartId: undefined,
       createdAt: existingGroupedPart?.createdAt ?? messageTimestamp,
     };
@@ -668,7 +898,7 @@ export function mergeParallelAgentsIntoParts(
   }
 
   const agentsByToolCall = new Map<string | undefined, ParallelAgent[]>();
-  for (const agent of normalizedAgents) {
+  for (const agent of mergedAgents) {
     const toolCallId = agent.taskToolCallId;
     const grouped = agentsByToolCall.get(toolCallId) ?? [];
     grouped.push(agent);
@@ -686,7 +916,7 @@ export function mergeParallelAgentsIntoParts(
     if (!part) continue;
     finalParts.push(part);
 
-    if (part.type === "tool" && (part.toolName === "Task" || part.toolName === "task")) {
+    if (part.type === "tool" && isSubagentToolName(part.toolName)) {
       const toolPart = part as ToolPart;
       currentGroup.push(toolPart);
       const agents = agentsByToolCall.get(toolPart.toolCallId);
@@ -708,13 +938,15 @@ export function mergeParallelAgentsIntoParts(
           endsGroup = true;
         } else if (nextPart.type === "tool") {
           const toolName = (nextPart as ToolPart).toolName;
-          if (toolName !== "Task" && toolName !== "task") {
+          if (!isSubagentToolName(toolName)) {
             endsGroup = true;
           }
         } else if (nextPart.type === "text") {
           if ((nextPart as TextPart).content.trim().length > 0) {
             endsGroup = true;
           }
+        } else if (nextPart.type === "task-result") {
+          endsGroup = true;
         }
       }
     }
@@ -809,12 +1041,101 @@ export function syncToolCallsIntoParts(
   return nextParts;
 }
 
+/**
+ * Route a part event into a specific agent's inlineParts sub-array.
+ * Returns updated top-level parts array, or null if the agent was not found.
+ */
+function routeToAgentInlineParts(
+  parts: Part[],
+  agentId: string,
+  applyFn: (inlineParts: Part[]) => Part[],
+): Part[] | null {
+  for (let i = 0; i < parts.length; i++) {
+    const part = parts[i];
+    if (part?.type !== "agent") continue;
+    const agentPart = part as AgentPart;
+    const agentIdx = agentPart.agents.findIndex((a) => a.id === agentId);
+    if (agentIdx < 0) continue;
+
+    const agent = agentPart.agents[agentIdx]!;
+    const updatedInlineParts = applyFn(agent.inlineParts ?? []);
+    const updatedAgents = [...agentPart.agents];
+    updatedAgents[agentIdx] = { ...agent, inlineParts: updatedInlineParts };
+    const updatedParts = [...parts];
+    updatedParts[i] = { ...agentPart, agents: updatedAgents };
+    return updatedParts;
+  }
+  return null;
+}
+
+function upsertTaskResultPart(parts: Part[], event: TaskResultUpsertEvent): Part[] {
+  const existingIdx = parts.findIndex(
+    (part) => part.type === "task-result" && (part as TaskResultPart).taskId === event.envelope.task_id,
+  );
+
+  const basePart: Omit<TaskResultPart, "id" | "createdAt"> = {
+    type: "task-result",
+    taskId: event.envelope.task_id,
+    toolName: event.envelope.tool_name,
+    title: event.envelope.title,
+    status: event.envelope.status,
+    outputText: event.envelope.output_text,
+    ...(event.envelope.envelope_text ? { envelopeText: event.envelope.envelope_text } : {}),
+    ...(event.envelope.error ? { error: event.envelope.error } : {}),
+    ...(event.envelope.metadata ? { metadata: event.envelope.metadata } : {}),
+  };
+
+  if (existingIdx >= 0) {
+    const existing = parts[existingIdx] as TaskResultPart;
+    const updated = [...parts];
+    updated[existingIdx] = {
+      ...existing,
+      ...basePart,
+    };
+    return updated;
+  }
+
+  return upsertPart(parts, {
+    ...basePart,
+    id: createPartId(),
+    createdAt: new Date().toISOString(),
+  } satisfies TaskResultPart);
+}
+
 export function applyStreamPartEvent(
   message: ChatMessage,
   event: StreamPartEvent,
 ): ChatMessage {
   switch (event.type) {
     case "text-delta": {
+      // Agent-scoped routing: append text to agent's inline parts
+      if (event.agentId && message.parts) {
+        const routed = routeToAgentInlineParts(message.parts, event.agentId, (inlineParts) => {
+          const lastText = inlineParts.length > 0 ? inlineParts[inlineParts.length - 1] : undefined;
+          if (lastText && lastText.type === "text" && (lastText as TextPart).isStreaming) {
+            const updated = [...inlineParts];
+            updated[updated.length - 1] = {
+              ...(lastText as TextPart),
+              content: (lastText as TextPart).content + event.delta,
+            };
+            return updated;
+          }
+          return [...inlineParts, {
+            id: createPartId(),
+            type: "text",
+            content: event.delta,
+            isStreaming: true,
+            createdAt: new Date().toISOString(),
+          } as TextPart];
+        });
+        if (routed) {
+          const nextMessage: ChatMessage = { ...message, parts: routed };
+          return carryReasoningPartRegistry(message, nextMessage);
+        }
+        // Agent not yet in parts — buffer for replay when AgentPart is created
+        bufferAgentEvent(event.agentId, event);
+        return message;
+      }
       const withParts = handleTextDelta(message, event.delta);
       const nextMessage: ChatMessage = {
         ...withParts,
@@ -823,10 +1144,59 @@ export function applyStreamPartEvent(
       return carryReasoningPartRegistry(message, nextMessage);
     }
 
-    case "thinking-meta":
+    case "thinking-meta": {
+      if (event.agentId) {
+        const routed = message.parts
+          ? routeToAgentInlineParts(message.parts, event.agentId, (inlineParts) => {
+            return upsertThinkingMetaPart(inlineParts, event);
+          })
+          : null;
+        if (routed) {
+          const nextMessage: ChatMessage = { ...message, parts: routed };
+          return carryReasoningPartRegistry(message, nextMessage);
+        }
+        // Agent not yet in parts — buffer for replay when AgentPart is created
+        bufferAgentEvent(event.agentId, event);
+        return message;
+      }
       return upsertThinkingMeta(message, event);
+    }
 
     case "tool-start": {
+      // Agent-scoped routing: add tool to agent's inline parts
+      if (event.agentId && message.parts) {
+        const shouldMirrorTaskOutput = isTaskOutputToolName(event.toolName);
+        const routed = routeToAgentInlineParts(message.parts, event.agentId, (inlineParts) => {
+          return upsertToolPartStart(inlineParts, event);
+        });
+        if (routed) {
+          if (!shouldMirrorTaskOutput) {
+            // Keep non-TaskOutput sub-agent tool activity scoped to inline parts
+            // so it does not leak back into top-level main-chat tool rendering.
+            const nextMessage: ChatMessage = { ...message, parts: routed };
+            return carryReasoningPartRegistry(message, nextMessage);
+          }
+          // TaskOutput is a user-visible progress primitive and should render
+          // as a dedicated block in the main transcript as well.
+          const nextMessage: ChatMessage = {
+            ...message,
+            toolCalls: upsertToolCallStart(message.toolCalls, event),
+            parts: upsertToolPartStart(routed, event),
+          };
+          return carryReasoningPartRegistry(message, nextMessage);
+        }
+        // Agent not yet in parts — buffer for replay when AgentPart is created
+        bufferAgentEvent(event.agentId, event);
+        if (!shouldMirrorTaskOutput) {
+          return message;
+        }
+        const nextMessage: ChatMessage = {
+          ...message,
+          toolCalls: upsertToolCallStart(message.toolCalls, event),
+          parts: upsertToolPartStart(message.parts ?? [], event),
+        };
+        return carryReasoningPartRegistry(message, nextMessage);
+      }
       const nextToolCalls = upsertToolCallStart(message.toolCalls, event);
       const nextParts = upsertToolPartStart(message.parts ?? [], event);
       const nextMessage: ChatMessage = {
@@ -838,6 +1208,41 @@ export function applyStreamPartEvent(
     }
 
     case "tool-complete": {
+      // Agent-scoped routing: update tool in agent's inline parts
+      if (event.agentId && message.parts) {
+        const shouldMirrorTaskOutput = isTaskOutputToolName(event.toolName)
+          || (message.toolCalls ?? []).some(
+            (toolCall) => toolCall.id === event.toolId && isTaskOutputToolName(toolCall.toolName),
+          );
+        const routed = routeToAgentInlineParts(message.parts, event.agentId, (inlineParts) => {
+          return upsertToolPartComplete(inlineParts, event);
+        });
+        if (routed) {
+          if (!shouldMirrorTaskOutput) {
+            // Keep non-TaskOutput sub-agent tool activity scoped to inline parts
+            // so it does not leak back into top-level main-chat tool rendering.
+            const nextMessage: ChatMessage = { ...message, parts: routed };
+            return carryReasoningPartRegistry(message, nextMessage);
+          }
+          const nextMessage: ChatMessage = {
+            ...message,
+            toolCalls: upsertToolCallComplete(message.toolCalls, event),
+            parts: upsertToolPartComplete(routed, event),
+          };
+          return carryReasoningPartRegistry(message, nextMessage);
+        }
+        // Agent not yet in parts — buffer for replay when AgentPart is created
+        bufferAgentEvent(event.agentId, event);
+        if (!shouldMirrorTaskOutput) {
+          return message;
+        }
+        const nextMessage: ChatMessage = {
+          ...message,
+          toolCalls: upsertToolCallComplete(message.toolCalls, event),
+          parts: upsertToolPartComplete(message.parts ?? [], event),
+        };
+        return carryReasoningPartRegistry(message, nextMessage);
+      }
       const nextToolCalls = upsertToolCallComplete(message.toolCalls, event);
       const nextParts = upsertToolPartComplete(message.parts ?? [], event);
       const nextMessage: ChatMessage = {
@@ -848,6 +1253,45 @@ export function applyStreamPartEvent(
       return carryReasoningPartRegistry(message, nextMessage);
     }
 
+    case "tool-partial-result": {
+      if (event.agentId && message.parts) {
+        const routed = routeToAgentInlineParts(message.parts, event.agentId, (inlineParts) => {
+          const updatedInlineParts = [...inlineParts];
+          const toolPartIdx = updatedInlineParts.findIndex(
+            (part) => part.type === "tool" && (part as ToolPart).toolCallId === event.toolId,
+          );
+          if (toolPartIdx >= 0) {
+            const existing = updatedInlineParts[toolPartIdx] as ToolPart;
+            updatedInlineParts[toolPartIdx] = {
+              ...existing,
+              partialOutput: (existing.partialOutput ?? "") + event.partialOutput,
+            };
+          }
+          return updatedInlineParts;
+        });
+        if (routed) {
+          const nextMessage: ChatMessage = { ...message, parts: routed };
+          return carryReasoningPartRegistry(message, nextMessage);
+        }
+        bufferAgentEvent(event.agentId, event);
+        return message;
+      }
+
+      const parts = [...(message.parts ?? [])];
+      const toolPartIdx = parts.findIndex(
+        (part) => part.type === "tool" && (part as ToolPart).toolCallId === event.toolId,
+      );
+      if (toolPartIdx >= 0) {
+        const existing = parts[toolPartIdx] as ToolPart;
+        parts[toolPartIdx] = {
+          ...existing,
+          partialOutput: (existing.partialOutput ?? "") + event.partialOutput,
+        };
+      }
+      const nextMessage: ChatMessage = { ...message, parts };
+      return carryReasoningPartRegistry(message, nextMessage);
+    }
+
     case "tool-hitl-request": {
       const nextParts = upsertHitlRequest(message.parts ?? [], event);
       const nextMessage: ChatMessage = {
@@ -860,14 +1304,23 @@ export function applyStreamPartEvent(
     case "tool-hitl-response":
       return carryReasoningPartRegistry(message, applyHitlResponse(message, event));
 
+    case "text-complete":
+      // Reconciliation is handled in useStreamConsumer (chat.tsx) — the
+      // reducer does not need to act on this event directly.
+      return message;
+
     case "parallel-agents": {
       const normalizedAgents = normalizeParallelAgents(event.agents);
-      const nextParts = mergeParallelAgentsIntoParts(
+      let nextParts = mergeParallelAgentsIntoParts(
         message.parts ?? [],
         normalizedAgents,
         message.timestamp,
         shouldGroupSubagentTrees({ ...message, parallelAgents: normalizedAgents }, event.isLastMessage),
       );
+      // Drain any buffered events for agents that are now in parts
+      for (const agent of normalizedAgents) {
+        nextParts = drainBufferedEvents(nextParts, agent.id);
+      }
       const nextMessage: ChatMessage = {
         ...message,
         parallelAgents: normalizedAgents,
@@ -875,5 +1328,61 @@ export function applyStreamPartEvent(
       };
       return carryReasoningPartRegistry(message, nextMessage);
     }
+
+    case "task-list-update": {
+      const parts = [...(message.parts ?? [])];
+      const taskItems = event.tasks.map((t) => ({
+        id: t.id,
+        content: t.title,
+        status: normalizeTaskItemStatus(t.status),
+        blockedBy: t.blockedBy,
+      }));
+      const existingIdx = parts.findIndex((part) => part.type === "task-list");
+      if (existingIdx >= 0) {
+        const existing = parts[existingIdx] as TaskListPart;
+        parts[existingIdx] = { ...existing, items: taskItems };
+      } else {
+        const taskListPart: TaskListPart = {
+          id: createPartId(),
+          type: "task-list",
+          items: taskItems,
+          expanded: false,
+          createdAt: new Date().toISOString(),
+        };
+        parts.push(taskListPart);
+      }
+      const nextMessage: ChatMessage = { ...message, parts };
+      return carryReasoningPartRegistry(message, nextMessage);
+    }
+
+    case "workflow-step-start":
+    case "workflow-step-complete":
+      return message;
+
+    case "task-result-upsert": {
+      const nextParts = upsertTaskResultPart(message.parts ?? [], event);
+      const nextMessage: ChatMessage = { ...message, parts: nextParts };
+      return carryReasoningPartRegistry(message, nextMessage);
+    }
+  }
+
+  return message;
+}
+
+/** Map raw status strings from workflow.task.update to TaskItem status values. */
+function normalizeTaskItemStatus(status: string): "pending" | "in_progress" | "completed" | "error" {
+  switch (status) {
+    case "pending": return "pending";
+    case "in_progress": return "in_progress";
+    case "completed":
+    case "complete":
+    case "done":
+    case "success":
+      return "completed";
+    case "error":
+    case "failed":
+      return "error";
+    default:
+      return "pending";
   }
 }
diff --git a/src/ui/parts/text-splitting.test.ts b/src/ui/parts/text-splitting.test.ts
index c483b260ac..c5d4ad96bf 100644
--- a/src/ui/parts/text-splitting.test.ts
+++ b/src/ui/parts/text-splitting.test.ts
@@ -82,8 +82,8 @@ describe("Tool-boundary text splitting", () => {
     expect((msg.parts![0] as TextPart).content).toBe("Hello ");
   });
 
-  test("text after tool becomes new TextPart", () => {
-    // Simulate: text → tool.start → tool.complete → new text
+  test("text after tool creates new TextPart when tool part between", () => {
+    // When tool parts separate text, new TextPart is created for correct visual ordering
     let msg = createMockMessage();
     
     // Stream "Hello "
@@ -99,27 +99,42 @@ describe("Tool-boundary text splitting", () => {
     expect(msg.parts).toHaveLength(2);
     expect((msg.parts![0] as TextPart).isStreaming).toBe(false);
     
-    // Tool completes - now stream new text
+    // Text after tool creates new TextPart (tool between prevents merge)
     msg = handleTextDelta(msg, " World");
     
-    // Verify new TextPart was created
     expect(msg.parts).toHaveLength(3);
+    expect(msg.parts![0]!.type).toBe("text");
+    expect(msg.parts![1]!.type).toBe("tool");
     expect(msg.parts![2]!.type).toBe("text");
-    const newTextPart = msg.parts![2] as TextPart;
-    expect(newTextPart.content).toBe(" World");
-    expect(newTextPart.isStreaming).toBe(true);
+    expect((msg.parts![0] as TextPart).content).toBe("Hello ");
+    expect((msg.parts![2] as TextPart).content).toBe(" World");
+  });
+
+  test("new paragraph after tool creates new TextPart", () => {
+    // Simulate: text → tool.start → tool.complete → new paragraph
+    let msg = createMockMessage();
     
-    // Verify old TextPart is still finalized
-    expect((msg.parts![0] as TextPart).isStreaming).toBe(false);
+    msg = handleTextDelta(msg, "Hello ");
+    msg = finalizeLastTextPart(msg);
+    const toolPart = createToolPart("tool_123", "bash");
+    msg.parts = upsertPart(msg.parts!, toolPart);
+    
+    // New paragraph starts with \n\n → creates new TextPart
+    msg = handleTextDelta(msg, "\n\nNew section");
+    
+    expect(msg.parts).toHaveLength(3);
+    expect(msg.parts![2]!.type).toBe("text");
+    expect((msg.parts![2] as TextPart).content).toBe("\n\nNew section");
+    expect((msg.parts![2] as TextPart).isStreaming).toBe(true);
     expect((msg.parts![0] as TextPart).content).toBe("Hello ");
   });
 
-  test("multiple tool interruptions create multiple TextParts", () => {
-    // Simulate: text1 → tool1 → text2 → tool2 → text3
+  test("paragraph breaks between tools create separate TextParts", () => {
+    // Simulate: text1\n\n → tool1 → text2\n\n → tool2 → text3
     let msg = createMockMessage();
     
-    // Text 1
-    msg = handleTextDelta(msg, "First");
+    // Text 1 (ends with paragraph break)
+    msg = handleTextDelta(msg, "First\n\n");
     expect(msg.parts).toHaveLength(1);
     
     // Tool 1
@@ -128,8 +143,8 @@ describe("Tool-boundary text splitting", () => {
     msg.parts = upsertPart(msg.parts!, tool1);
     expect(msg.parts).toHaveLength(2);
     
-    // Text 2
-    msg = handleTextDelta(msg, "Second");
+    // Text 2 (new paragraph after tool → creates new TextPart)
+    msg = handleTextDelta(msg, "\n\nSecond\n\n");
     expect(msg.parts).toHaveLength(3);
     
     // Tool 2
@@ -138,19 +153,48 @@ describe("Tool-boundary text splitting", () => {
     msg.parts = upsertPart(msg.parts!, tool2);
     expect(msg.parts).toHaveLength(4);
     
-    // Text 3
-    msg = handleTextDelta(msg, "Third");
+    // Text 3 (new paragraph after tool → creates new TextPart)
+    msg = handleTextDelta(msg, "\n\nThird");
     expect(msg.parts).toHaveLength(5);
     
     // Verify 3 separate TextParts
+    const textParts = msg.parts!.filter(p => p.type === "text") as TextPart[];
+    expect(textParts).toHaveLength(3);
+    expect(textParts[0]!.content).toBe("First\n\n");
+    expect(textParts[1]!.content).toBe("\n\nSecond\n\n");
+    expect(textParts[2]!.content).toBe("\n\nThird");
+  });
+
+  test("continuations after tool boundaries create separate TextParts", () => {
+    // When tool parts intervene, continuations get their own TextParts for ordering
+    let msg = createMockMessage();
+    
+    // Text 1
+    msg = handleTextDelta(msg, "First");
+    
+    // Tool 1
+    msg = finalizeLastTextPart(msg);
+    const tool1 = createToolPart("tool_1", "bash");
+    msg.parts = upsertPart(msg.parts!, tool1);
+    
+    // New TextPart (tool between prevents merge)
+    msg = handleTextDelta(msg, " Second");
+    expect(msg.parts).toHaveLength(3);
+    expect((msg.parts![2] as TextPart).content).toBe(" Second");
+    
+    // Tool 2
+    msg = finalizeLastTextPart(msg);
+    const tool2 = createToolPart("tool_2", "view");
+    msg.parts = upsertPart(msg.parts!, tool2);
+    
+    // New TextPart (tool between prevents merge)
+    msg = handleTextDelta(msg, " Third");
+    
     const textParts = msg.parts!.filter(p => p.type === "text") as TextPart[];
     expect(textParts).toHaveLength(3);
     expect(textParts[0]!.content).toBe("First");
-    expect(textParts[0]!.isStreaming).toBe(false);
-    expect(textParts[1]!.content).toBe("Second");
-    expect(textParts[1]!.isStreaming).toBe(false);
-    expect(textParts[2]!.content).toBe("Third");
-    expect(textParts[2]!.isStreaming).toBe(true);
+    expect(textParts[1]!.content).toBe(" Second");
+    expect(textParts[2]!.content).toBe(" Third");
   });
 
   test("empty text before tool doesn't create empty TextPart", () => {
@@ -175,20 +219,20 @@ describe("Tool-boundary text splitting", () => {
     expect((textParts[0] as TextPart).content).toBe("After tool");
   });
 
-  test("tool part preserves order between text parts", () => {
-    // Simulate: text1 → tool → text2
+  test("tool part preserves order between text parts with paragraph breaks", () => {
+    // Simulate: text1\n\n → tool → \n\ntext2
     let msg = createMockMessage();
     
-    // Text 1
-    msg = handleTextDelta(msg, "Before");
+    // Text 1 (ends with paragraph break)
+    msg = handleTextDelta(msg, "Before\n\n");
     
     // Tool
     msg = finalizeLastTextPart(msg);
     const toolPart = createToolPart("tool_123", "bash");
     msg.parts = upsertPart(msg.parts!, toolPart);
     
-    // Text 2
-    msg = handleTextDelta(msg, "After");
+    // Text 2 (starts with paragraph break → new TextPart)
+    msg = handleTextDelta(msg, "\n\nAfter");
     
     // Verify order: [TextPart, ToolPart, TextPart]
     expect(msg.parts).toHaveLength(3);
@@ -197,9 +241,9 @@ describe("Tool-boundary text splitting", () => {
     expect(msg.parts![2]!.type).toBe("text");
     
     // Verify content
-    expect((msg.parts![0] as TextPart).content).toBe("Before");
+    expect((msg.parts![0] as TextPart).content).toBe("Before\n\n");
     expect((msg.parts![1] as ToolPart).toolCallId).toBe("tool_123");
-    expect((msg.parts![2] as TextPart).content).toBe("After");
+    expect((msg.parts![2] as TextPart).content).toBe("\n\nAfter");
   });
 
   test("streaming text accumulates in same TextPart", () => {
@@ -260,25 +304,41 @@ describe("Tool-boundary text splitting", () => {
     expect(finalizedContent).toBe("Test content 12345!@#$%");
   });
 
-  test("finalized TextPart cannot be streamed to", () => {
-    // Verify that once finalized, new deltas create a new TextPart
+  test("finalized TextPart merges continuations without paragraph break", () => {
+    // Verify that once finalized, continuations merge if no paragraph break
     let msg = createMockMessage();
     
     // Stream and finalize
     msg = handleTextDelta(msg, "First part");
     msg = finalizeLastTextPart(msg);
     
-    const firstPartId = msg.parts![0]!.id;
     expect((msg.parts![0] as TextPart).isStreaming).toBe(false);
     
-    // Try to stream more text
+    // Continuation merges back (no paragraph break)
     msg = handleTextDelta(msg, " Second part");
     
-    // Verify a new TextPart was created
+    // Verify merged into existing TextPart
+    expect(msg.parts).toHaveLength(1);
+    expect((msg.parts![0] as TextPart).content).toBe("First part Second part");
+  });
+
+  test("finalized TextPart creates new TextPart with paragraph break", () => {
+    // Verify that paragraph break after finalized TextPart creates new one
+    let msg = createMockMessage();
+    
+    // Stream and finalize
+    msg = handleTextDelta(msg, "First part");
+    msg = finalizeLastTextPart(msg);
+    
+    const firstPartId = msg.parts![0]!.id;
+    
+    // New paragraph creates new TextPart
+    msg = handleTextDelta(msg, "\n\nSecond part");
+    
     expect(msg.parts).toHaveLength(2);
-    expect(msg.parts![0]!.id).toBe(firstPartId); // Original part unchanged
+    expect(msg.parts![0]!.id).toBe(firstPartId);
     expect((msg.parts![0] as TextPart).content).toBe("First part");
-    expect((msg.parts![1] as TextPart).content).toBe(" Second part");
+    expect((msg.parts![1] as TextPart).content).toBe("\n\nSecond part");
   });
 
   test("empty string delta adds to streaming TextPart", () => {
diff --git a/src/ui/parts/types.ts b/src/ui/parts/types.ts
index cc220877ac..2cedabd51d 100644
--- a/src/ui/parts/types.ts
+++ b/src/ui/parts/types.ts
@@ -40,7 +40,13 @@ export type ToolState =
   | { status: "running"; startedAt: string }
   | { status: "completed"; output: unknown; durationMs: number }
   | { status: "error"; error: string; output?: unknown }
-  | { status: "interrupted"; partialOutput?: unknown };
+  | { status: "interrupted"; partialOutput?: unknown; durationMs?: number };
+
+/**
+ * Tool execution status union type.
+ * Extracted from ToolState for components that only need the status.
+ */
+export type ToolExecutionStatus = ToolState["status"];
 
 // ============================================================================
 // CONCRETE PART TYPES
@@ -69,6 +75,8 @@ export interface ToolPart extends BasePart {
   toolName: string;
   input: Record<string, unknown>;
   output?: unknown;
+  /** Incremental output streamed while tool is still running */
+  partialOutput?: string;
   state: ToolState;
   hitlResponse?: HitlResponseRecord;
 
@@ -110,6 +118,33 @@ export interface CompactionPart extends BasePart {
   summary: string;
 }
 
+export interface TaskResultPart extends BasePart {
+  type: "task-result";
+  taskId: string;
+  toolName: string;
+  title: string;
+  status: "completed" | "error";
+  outputText: string;
+  envelopeText?: string;
+  error?: string;
+  metadata?: {
+    sessionId?: string;
+    providerBindings?: Record<string, string>;
+  };
+}
+
+export interface WorkflowStepPart extends BasePart {
+  type: "workflow-step";
+  workflowId: string;
+  nodeId: string;
+  nodeName: string;
+  status: "running" | "completed" | "error" | "skipped";
+  startedAt: string;
+  completedAt?: string;
+  durationMs?: number;
+  result?: unknown;
+}
+
 // ============================================================================
 // PART UNION
 // ============================================================================
@@ -123,4 +158,6 @@ export type Part =
   | TaskListPart
   | SkillLoadPart
   | McpSnapshotPart
-  | CompactionPart;
+  | CompactionPart
+  | TaskResultPart
+  | WorkflowStepPart;
diff --git a/src/ui/subagent-tree-dedup-ordering.test.ts b/src/ui/subagent-tree-dedup-ordering.test.ts
new file mode 100644
index 0000000000..74e34d8657
--- /dev/null
+++ b/src/ui/subagent-tree-dedup-ordering.test.ts
@@ -0,0 +1,325 @@
+import { describe, expect, test } from "bun:test";
+
+type AgentStatus = "pending" | "running" | "completed" | "error" | "background" | "interrupted";
+
+interface ParallelAgent {
+  id: string;
+  taskToolCallId?: string;
+  name: string;
+  task: string;
+  status: AgentStatus;
+  startedAt: string;
+  background?: boolean;
+  currentTool?: string;
+}
+
+interface CorrelationState {
+  parallelAgents: ParallelAgent[];
+  toolCallToAgentMap: Map<string, string>;
+  correlationAliases: Map<string, string>;
+  pendingTaskCorrelations: string[];
+  pendingSubagentCorrelations: string[];
+  subagentCorrelationById: Map<string, string>;
+}
+
+function isGenericSubagentTask(task: string | undefined): boolean {
+  const normalized = (task ?? "").trim().toLowerCase();
+  return normalized === "" || normalized === "sub-agent task" || normalized === "subagent task";
+}
+
+function resolveCorrelationAlias(
+  state: CorrelationState,
+  correlationId: string | undefined,
+): string | undefined {
+  if (!correlationId) {
+    return undefined;
+  }
+
+  let resolved = correlationId;
+  const seen = new Set<string>();
+  while (!seen.has(resolved)) {
+    seen.add(resolved);
+    const next = state.correlationAliases.get(resolved);
+    if (!next || next === resolved) {
+      break;
+    }
+    resolved = next;
+  }
+
+  for (const alias of seen) {
+    state.correlationAliases.set(alias, resolved);
+  }
+  return resolved;
+}
+
+function registerAlias(
+  state: CorrelationState,
+  preferredCorrelationId: string,
+  ...aliases: Array<string | undefined>
+): void {
+  state.correlationAliases.set(preferredCorrelationId, preferredCorrelationId);
+  for (const alias of aliases) {
+    if (!alias) {
+      continue;
+    }
+    const canonicalAlias = resolveCorrelationAlias(state, alias) ?? alias;
+    state.correlationAliases.set(alias, preferredCorrelationId);
+    state.correlationAliases.set(canonicalAlias, preferredCorrelationId);
+  }
+}
+
+function enqueueUnique(queue: string[], value: string): void {
+  if (!queue.includes(value)) {
+    queue.push(value);
+  }
+}
+
+function removeFromQueue(queue: string[], value: string): void {
+  const index = queue.indexOf(value);
+  if (index >= 0) {
+    queue.splice(index, 1);
+  }
+}
+
+function applySubagentStart(
+  state: CorrelationState,
+  event: {
+    subagentId: string;
+    subagentType: string;
+    task?: string;
+    sdkCorrelationId?: string;
+  },
+): CorrelationState {
+  const task = event.task ?? "Sub-agent task";
+  let resolvedCorrelationId = resolveCorrelationAlias(state, event.sdkCorrelationId);
+
+  if (!resolvedCorrelationId) {
+    resolvedCorrelationId = resolveCorrelationAlias(
+      state,
+      state.subagentCorrelationById.get(event.subagentId),
+    );
+  }
+
+  if (resolvedCorrelationId) {
+    const sdkMappedAgentId = state.toolCallToAgentMap.get(resolvedCorrelationId);
+    if (!sdkMappedAgentId && state.pendingTaskCorrelations.length > 0) {
+      const inferredTaskCorrelationId = state.pendingTaskCorrelations[0]!;
+      registerAlias(state, inferredTaskCorrelationId, resolvedCorrelationId);
+      resolvedCorrelationId = inferredTaskCorrelationId;
+    }
+  }
+
+  const sdkMappedAgentId = resolvedCorrelationId
+    ? state.toolCallToAgentMap.get(resolvedCorrelationId)
+    : undefined;
+
+  if (sdkMappedAgentId && state.parallelAgents.some((a) => a.id === sdkMappedAgentId)) {
+    state.parallelAgents = state.parallelAgents.map((a) =>
+      a.id === sdkMappedAgentId
+        ? {
+            ...a,
+            id: event.subagentId,
+            taskToolCallId: resolvedCorrelationId ?? a.taskToolCallId,
+            name: event.subagentType,
+            task: isGenericSubagentTask(a.task) ? task : a.task,
+            currentTool: `Running ${event.subagentType}...`,
+          }
+        : a,
+    );
+  } else if (state.parallelAgents.some((a) => a.id === event.subagentId)) {
+    state.parallelAgents = state.parallelAgents.map((a) =>
+      a.id === event.subagentId
+        ? {
+            ...a,
+            taskToolCallId: resolvedCorrelationId ?? a.taskToolCallId,
+            name: event.subagentType,
+            task: isGenericSubagentTask(a.task) ? task : a.task,
+            currentTool: `Running ${event.subagentType}...`,
+          }
+        : a,
+    );
+  } else {
+    state.parallelAgents = [
+      ...state.parallelAgents,
+      {
+        id: event.subagentId,
+        taskToolCallId: resolvedCorrelationId,
+        name: event.subagentType,
+        task,
+        status: "running",
+        startedAt: "2026-01-01T00:00:00.000Z",
+        currentTool: `Running ${event.subagentType}...`,
+      },
+    ];
+  }
+
+  if (resolvedCorrelationId) {
+    state.toolCallToAgentMap.set(resolvedCorrelationId, event.subagentId);
+    state.subagentCorrelationById.set(event.subagentId, resolvedCorrelationId);
+    removeFromQueue(state.pendingTaskCorrelations, resolvedCorrelationId);
+    removeFromQueue(state.pendingSubagentCorrelations, resolvedCorrelationId);
+    enqueueUnique(state.pendingSubagentCorrelations, resolvedCorrelationId);
+  }
+
+  return state;
+}
+
+function applyTaskToolStart(
+  state: CorrelationState,
+  event: {
+    toolId: string;
+    sdkCorrelationId?: string;
+    agentType: string;
+    task: string;
+  },
+): CorrelationState {
+  let resolvedSdkCorrelationId = resolveCorrelationAlias(state, event.sdkCorrelationId);
+  let sdkMappedAgentId = resolvedSdkCorrelationId
+    ? state.toolCallToAgentMap.get(resolvedSdkCorrelationId)
+    : undefined;
+
+  if (!sdkMappedAgentId && resolvedSdkCorrelationId && state.pendingSubagentCorrelations.length > 0) {
+    const pendingSubagentCorrelationId = state.pendingSubagentCorrelations[0]!;
+    const pendingMappedAgentId = state.toolCallToAgentMap.get(
+      resolveCorrelationAlias(state, pendingSubagentCorrelationId) ?? pendingSubagentCorrelationId,
+    );
+    if (pendingMappedAgentId) {
+      registerAlias(state, resolvedSdkCorrelationId, pendingSubagentCorrelationId);
+      sdkMappedAgentId = pendingMappedAgentId;
+      removeFromQueue(state.pendingSubagentCorrelations, pendingSubagentCorrelationId);
+    }
+  }
+
+  const existingSdkMappedAgent = sdkMappedAgentId
+    ? state.parallelAgents.find((a) => a.id === sdkMappedAgentId)
+    : undefined;
+
+  if (existingSdkMappedAgent && sdkMappedAgentId) {
+    state.parallelAgents = state.parallelAgents.map((a) =>
+      a.id === sdkMappedAgentId
+        ? {
+            ...a,
+            taskToolCallId: event.toolId,
+            name: event.agentType,
+            task: isGenericSubagentTask(a.task) ? event.task : a.task,
+            currentTool: `Running ${event.agentType}...`,
+          }
+        : a,
+    );
+    state.toolCallToAgentMap.set(event.toolId, sdkMappedAgentId);
+    if (resolvedSdkCorrelationId) {
+      state.toolCallToAgentMap.set(resolvedSdkCorrelationId, sdkMappedAgentId);
+      state.subagentCorrelationById.set(sdkMappedAgentId, resolvedSdkCorrelationId);
+      removeFromQueue(state.pendingTaskCorrelations, resolvedSdkCorrelationId);
+    }
+    return state;
+  }
+
+  state.parallelAgents = [
+    ...state.parallelAgents,
+    {
+      id: event.toolId,
+      taskToolCallId: event.toolId,
+      name: event.agentType,
+      task: event.task,
+      status: "running",
+      startedAt: "2026-01-01T00:00:00.000Z",
+      currentTool: `Starting ${event.agentType}...`,
+    },
+  ];
+  state.toolCallToAgentMap.set(event.toolId, event.toolId);
+  resolvedSdkCorrelationId = resolvedSdkCorrelationId ?? event.sdkCorrelationId;
+  if (resolvedSdkCorrelationId) {
+    state.toolCallToAgentMap.set(resolvedSdkCorrelationId, event.toolId);
+    enqueueUnique(state.pendingTaskCorrelations, resolvedSdkCorrelationId);
+  }
+  return state;
+}
+
+function createState(): CorrelationState {
+  return {
+    parallelAgents: [],
+    toolCallToAgentMap: new Map<string, string>(),
+    correlationAliases: new Map<string, string>(),
+    pendingTaskCorrelations: [],
+    pendingSubagentCorrelations: [],
+    subagentCorrelationById: new Map<string, string>(),
+  };
+}
+
+describe("subagent tree dedup ordering", () => {
+  test("subagent.start before Task tool.start keeps a single row", () => {
+    const state = createState();
+
+    applySubagentStart(state, {
+      subagentId: "subagent-1",
+      subagentType: "debugger",
+      task: "Debug stuck spinner",
+      sdkCorrelationId: "call-1",
+    });
+
+    applyTaskToolStart(state, {
+      toolId: "tool_call-1",
+      sdkCorrelationId: "call-1",
+      agentType: "debugger",
+      task: "Sub-agent task",
+    });
+
+    expect(state.parallelAgents).toHaveLength(1);
+    expect(state.parallelAgents[0]?.id).toBe("subagent-1");
+    expect(state.parallelAgents[0]?.taskToolCallId).toBe("tool_call-1");
+    expect(state.parallelAgents[0]?.task).toBe("Debug stuck spinner");
+  });
+
+  test("duplicate subagent.start with same SDK correlation updates existing row", () => {
+    const state = createState();
+
+    applySubagentStart(state, {
+      subagentId: "agent-part-1",
+      subagentType: "debugger",
+      task: "Sub-agent task",
+      sdkCorrelationId: "call-2",
+    });
+
+    applySubagentStart(state, {
+      subagentId: "subtask-part-1",
+      subagentType: "debugger",
+      task: "Debug stuck spinner",
+      sdkCorrelationId: "call-2",
+    });
+
+    expect(state.parallelAgents).toHaveLength(1);
+    expect(state.parallelAgents[0]?.id).toBe("subtask-part-1");
+    expect(state.parallelAgents[0]?.task).toBe("Debug stuck spinner");
+  });
+
+  test("callId-first subagent with replayed missing-correlation start keeps one rendered branch", () => {
+    const state = createState();
+
+    applySubagentStart(state, {
+      subagentId: "agent-3",
+      subagentType: "debugger",
+      task: "Sub-agent task",
+      sdkCorrelationId: "call-3",
+    });
+
+    applyTaskToolStart(state, {
+      toolId: "tool-use-3",
+      sdkCorrelationId: "tool-use-3",
+      agentType: "debugger",
+      task: "Debug stuck spinner",
+    });
+
+    // Replayed subagent.start without callId/toolUseId should hydrate using prior linkage.
+    applySubagentStart(state, {
+      subagentId: "agent-3",
+      subagentType: "debugger",
+      task: "Debug stuck spinner",
+    });
+
+    expect(state.parallelAgents).toHaveLength(1);
+    expect(state.parallelAgents[0]?.id).toBe("agent-3");
+    expect(state.parallelAgents[0]?.taskToolCallId).toBe("tool-use-3");
+    expect(state.parallelAgents[0]?.task).toBe("Debug stuck spinner");
+  });
+});
diff --git a/src/ui/subagent-tree-orphan-fix.test.ts b/src/ui/subagent-tree-orphan-fix.test.ts
new file mode 100644
index 0000000000..5cb5099c6c
--- /dev/null
+++ b/src/ui/subagent-tree-orphan-fix.test.ts
@@ -0,0 +1,268 @@
+/**
+ * Test for sub-agent tree orphan fix
+ * 
+ * Verifies that stale terminal agent rows can be replaced by a new start event,
+ * while active-lifecycle terminal rows are blocked from transitioning back to running.
+ */
+
+import { describe, expect, test } from "bun:test";
+
+type AgentStatus = "pending" | "running" | "completed" | "error" | "background" | "interrupted";
+
+interface ParallelAgent {
+  id: string;
+  taskToolCallId?: string;
+  name: string;
+  task: string;
+  status: AgentStatus;
+  startedAt: string;
+  background?: boolean;
+  currentTool?: string;
+}
+
+/**
+ * Simulates the stream.agent.start handler logic.
+ * - Stale terminal rows (no active lifecycle entry) can be replaced.
+ * - Active lifecycle + terminal row blocks terminal->running transitions.
+ */
+function applyAgentStart(
+  current: ParallelAgent[],
+  event: {
+    agentId: string;
+    agentType: string;
+    task: string;
+    sdkCorrelationId?: string;
+    isBackground?: boolean;
+  },
+  hasActiveLifecycleEntry = false,
+): ParallelAgent[] {
+  const startedAt = new Date().toISOString();
+  const status: AgentStatus = event.isBackground ? "background" : "running";
+
+  const existingIndex = current.findIndex((agent) => agent.id === event.agentId);
+  if (existingIndex >= 0) {
+    const existing = current[existingIndex];
+    // If agent already has a terminal status (completed, error, interrupted),
+    // block active-lifecycle terminal->running transitions; otherwise replace
+    // stale rows from previous streams.
+    if (existing && (existing.status === "completed" || existing.status === "error" || existing.status === "interrupted")) {
+      if (hasActiveLifecycleEntry) {
+        return current;
+      }
+      // Remove the old agent and add the new one
+      return [
+        ...current.filter((agent) => agent.id !== event.agentId),
+        {
+          id: event.agentId,
+          taskToolCallId: event.sdkCorrelationId,
+          name: event.agentType,
+          task: event.task,
+          status,
+          startedAt,
+          background: event.isBackground,
+          currentTool: event.agentType ? `Running ${event.agentType}...` : undefined,
+        },
+      ];
+    }
+    // Update existing agent that's still active
+    return current.map((agent) =>
+      agent.id === event.agentId
+        ? {
+          ...agent,
+          name: event.agentType || agent.name,
+          task: event.task || agent.task,
+          status,
+          background: event.isBackground || agent.background,
+          taskToolCallId: event.sdkCorrelationId ?? agent.taskToolCallId,
+          currentTool: event.agentType ? `Running ${event.agentType}...` : agent.currentTool,
+        }
+        : agent
+    );
+  }
+  return [
+    ...current,
+    {
+      id: event.agentId,
+      taskToolCallId: event.sdkCorrelationId,
+      name: event.agentType,
+      task: event.task,
+      status,
+      startedAt,
+      background: event.isBackground,
+      currentTool: event.agentType ? `Running ${event.agentType}...` : undefined,
+    },
+  ];
+}
+
+describe("sub-agent tree orphan fix", () => {
+  test("terminal agent is not replaced when lifecycle entry is still active", () => {
+    const current: ParallelAgent[] = [
+      {
+        id: "agent-active",
+        name: "debugger",
+        task: "Completed task",
+        status: "completed",
+        startedAt: "2024-01-01T00:00:00.000Z",
+      },
+    ];
+
+    const result = applyAgentStart(current, {
+      agentId: "agent-active",
+      agentType: "debugger",
+      task: "Invalid restart",
+    }, true);
+
+    expect(result).toEqual(current);
+  });
+
+  test("completed agent is replaced when new start event arrives", () => {
+    const current: ParallelAgent[] = [
+      {
+        id: "agent-1",
+        name: "debugger",
+        task: "Old task",
+        status: "completed",
+        startedAt: "2024-01-01T00:00:00.000Z",
+      },
+    ];
+
+    const result = applyAgentStart(current, {
+      agentId: "agent-1",
+      agentType: "debugger",
+      task: "New task",
+      sdkCorrelationId: "call-1",
+    });
+
+    expect(result).toHaveLength(1);
+    expect(result[0]?.status).toBe("running");
+    expect(result[0]?.task).toBe("New task");
+    expect(result[0]?.startedAt).not.toBe("2024-01-01T00:00:00.000Z");
+  });
+
+  test("error agent is replaced when new start event arrives", () => {
+    const current: ParallelAgent[] = [
+      {
+        id: "agent-2",
+        name: "codebase-analyzer",
+        task: "Old failed task",
+        status: "error",
+        startedAt: "2024-01-01T00:00:00.000Z",
+      },
+    ];
+
+    const result = applyAgentStart(current, {
+      agentId: "agent-2",
+      agentType: "codebase-analyzer",
+      task: "Retry task",
+    });
+
+    expect(result).toHaveLength(1);
+    expect(result[0]?.status).toBe("running");
+    expect(result[0]?.task).toBe("Retry task");
+  });
+
+  test("interrupted agent is replaced when new start event arrives", () => {
+    const current: ParallelAgent[] = [
+      {
+        id: "agent-3",
+        name: "explore",
+        task: "Old interrupted task",
+        status: "interrupted",
+        startedAt: "2024-01-01T00:00:00.000Z",
+      },
+    ];
+
+    const result = applyAgentStart(current, {
+      agentId: "agent-3",
+      agentType: "explore",
+      task: "New task after interrupt",
+    });
+
+    expect(result).toHaveLength(1);
+    expect(result[0]?.status).toBe("running");
+    expect(result[0]?.task).toBe("New task after interrupt");
+  });
+
+  test("running agent is updated, not replaced", () => {
+    const originalStartTime = "2024-01-01T00:00:00.000Z";
+    const current: ParallelAgent[] = [
+      {
+        id: "agent-4",
+        name: "debugger",
+        task: "Running task",
+        status: "running",
+        startedAt: originalStartTime,
+      },
+    ];
+
+    const result = applyAgentStart(current, {
+      agentId: "agent-4",
+      agentType: "debugger",
+      task: "Updated task",
+    });
+
+    expect(result).toHaveLength(1);
+    expect(result[0]?.status).toBe("running");
+    expect(result[0]?.task).toBe("Updated task");
+    // Should preserve original start time for active agents
+    expect(result[0]?.startedAt).toBe(originalStartTime);
+  });
+
+  test("multiple completed agents are filtered out on new start", () => {
+    const current: ParallelAgent[] = [
+      {
+        id: "agent-1",
+        name: "debugger",
+        task: "Completed 1",
+        status: "completed",
+        startedAt: "2024-01-01T00:00:00.000Z",
+      },
+      {
+        id: "agent-2",
+        name: "explore",
+        task: "Completed 2",
+        status: "completed",
+        startedAt: "2024-01-01T00:01:00.000Z",
+      },
+    ];
+
+    const result = applyAgentStart(current, {
+      agentId: "agent-1",
+      agentType: "debugger",
+      task: "New task",
+    });
+
+    expect(result).toHaveLength(2);
+    const agent1 = result.find((a) => a.id === "agent-1");
+    const agent2 = result.find((a) => a.id === "agent-2");
+    
+    expect(agent1?.status).toBe("running");
+    expect(agent1?.task).toBe("New task");
+    expect(agent2?.status).toBe("completed");
+    expect(agent2?.task).toBe("Completed 2");
+  });
+
+  test("new agent is added when id doesn't exist", () => {
+    const current: ParallelAgent[] = [
+      {
+        id: "agent-1",
+        name: "debugger",
+        task: "Existing task",
+        status: "running",
+        startedAt: "2024-01-01T00:00:00.000Z",
+      },
+    ];
+
+    const result = applyAgentStart(current, {
+      agentId: "agent-2",
+      agentType: "explore",
+      task: "New agent task",
+    });
+
+    expect(result).toHaveLength(2);
+    const newAgent = result.find((a) => a.id === "agent-2");
+    expect(newAgent).toBeDefined();
+    expect(newAgent?.status).toBe("running");
+    expect(newAgent?.task).toBe("New agent task");
+  });
+});
diff --git a/src/ui/tools/index.ts b/src/ui/tools/index.ts
index 328c8f64f6..7e77805bab 100644
--- a/src/ui/tools/index.ts
+++ b/src/ui/tools/index.ts
@@ -33,4 +33,7 @@ export {
   getRegisteredToolNames,
   hasCustomRenderer,
   getLanguageFromExtension,
+
+  // Dynamic registration
+  registerAgentToolNames,
 } from "./registry.ts";
diff --git a/src/ui/tools/registry.test.ts b/src/ui/tools/registry.test.ts
index 99401591f6..2ee048e5fb 100644
--- a/src/ui/tools/registry.test.ts
+++ b/src/ui/tools/registry.test.ts
@@ -8,6 +8,7 @@ import {
   defaultToolRenderer,
   readToolRenderer,
   editToolRenderer,
+  applyPatchToolRenderer,
   bashToolRenderer,
   writeToolRenderer,
   globToolRenderer,
@@ -16,6 +17,8 @@ import {
   taskToolRenderer,
   todoWriteToolRenderer,
   parseTaskToolResult,
+  registerAgentToolNames,
+  TOOL_RENDERERS,
   type ToolRenderProps,
 } from "./registry";
 import { STATUS, CHECKBOX } from "../constants/icons";
@@ -28,6 +31,8 @@ describe("getToolRenderer", () => {
     expect(getToolRenderer("bash")).toBe(bashToolRenderer);
     expect(getToolRenderer("Task")).toBe(taskToolRenderer);
     expect(getToolRenderer("task")).toBe(taskToolRenderer);
+    expect(getToolRenderer("launch_agent")).toBe(taskToolRenderer);
+    expect(getToolRenderer("apply_patch")).toBe(applyPatchToolRenderer);
   });
 
   test("returns MCP renderer for MCP tool names", () => {
@@ -664,6 +669,120 @@ describe("editToolRenderer.render()", () => {
   });
 });
 
+describe("applyPatchToolRenderer.render()", () => {
+  test("shows empty apply patch block until patch text is available", () => {
+    const props: ToolRenderProps = {
+      input: {},
+      output: undefined,
+    };
+
+    const result = applyPatchToolRenderer.render(props);
+    expect(result.title).toBe("Apply patch");
+    expect(result.content).toEqual([]);
+    expect(result.expandable).toBe(false);
+  });
+
+  test("renders patchText content instead of unknown file placeholders", () => {
+    const props: ToolRenderProps = {
+      input: {
+        patchText: [
+          "*** Begin Patch",
+          "*** Update File: src/ui/chat.tsx",
+          "@@",
+          "-old line",
+          "+new line",
+          "*** End Patch",
+        ].join("\n"),
+      },
+    };
+
+    const result = applyPatchToolRenderer.render(props);
+    expect(result.title).toBe("chat.tsx");
+    expect(result.content).toContain("*** Update File: src/ui/chat.tsx");
+    expect(result.content).not.toContain("--- unknown");
+    expect(result.content).not.toContain("+++ unknown");
+  });
+
+  test("summarizes multi-file patches in title", () => {
+    const props: ToolRenderProps = {
+      input: {
+        patchText: [
+          "*** Begin Patch",
+          "*** Update File: src/a.ts",
+          "@@",
+          "-a",
+          "+b",
+          "*** Add File: src/new.ts",
+          "+export const v = 1;",
+          "*** End Patch",
+        ].join("\n"),
+      },
+    };
+
+    const result = applyPatchToolRenderer.render(props);
+    expect(result.title).toBe("2 files");
+    expect(result.content).toContain("*** Update File: src/a.ts");
+    expect(result.content).toContain("*** Add File: src/new.ts");
+  });
+
+  test("uses output metadata files when patchText is unavailable", () => {
+    const props: ToolRenderProps = {
+      input: {},
+      output: {
+        metadata: {
+          files: [
+            { relativePath: "src/one.ts", type: "update" },
+            { relativePath: "src/two.ts", type: "add" },
+          ],
+        },
+      },
+    };
+
+    const result = applyPatchToolRenderer.render(props);
+    expect(result.title).toBe("2 files");
+    expect(result.content).toContain("*** Update File: src/one.ts");
+    expect(result.content).toContain("*** Add File: src/two.ts");
+  });
+
+  test("extracts patch text from alternate input keys", () => {
+    const props: ToolRenderProps = {
+      input: {
+        patch_text: [
+          "*** Begin Patch",
+          "*** Update File: src/alt.ts",
+          "@@",
+          "-before",
+          "+after",
+          "*** End Patch",
+        ].join("\n"),
+      },
+    };
+
+    const result = applyPatchToolRenderer.render(props);
+    expect(result.title).toBe("alt.ts");
+    expect(result.content).toContain("*** Update File: src/alt.ts");
+    expect(result.content).not.toContain("--- unknown");
+    expect(result.content).not.toContain("+++ unknown");
+  });
+
+  test("parses metadata files from JSON string output", () => {
+    const props: ToolRenderProps = {
+      input: {},
+      output: JSON.stringify({
+        metadata: {
+          files: [
+            { relativePath: "src/three.ts", type: "update" },
+          ],
+        },
+      }),
+    };
+
+    const result = applyPatchToolRenderer.render(props);
+    expect(result.title).toBe("three.ts");
+    expect(result.content).toContain("*** Update File: src/three.ts");
+  });
+});
+
 describe("bashToolRenderer.render()", () => {
   test("renders command with string output", () => {
     const props: ToolRenderProps = {
@@ -1268,3 +1387,28 @@ describe("todoWriteToolRenderer.render()", () => {
     expect(result.title).toBe("0 tasks (0 done, 0 open)");
   });
 });
+
+describe("registerAgentToolNames", () => {
+  test("registers agent names as task tool renderers", () => {
+    registerAgentToolNames(["my-custom-agent"]);
+    expect(getToolRenderer("my-custom-agent")).toBe(taskToolRenderer);
+  });
+
+  test("does not overwrite existing renderer entries", () => {
+    // "Read" already maps to readToolRenderer
+    registerAgentToolNames(["Read"]);
+    expect(getToolRenderer("Read")).toBe(readToolRenderer);
+  });
+
+  test("registers multiple agent names at once", () => {
+    registerAgentToolNames(["agent-alpha", "agent-beta"]);
+    expect(getToolRenderer("agent-alpha")).toBe(taskToolRenderer);
+    expect(getToolRenderer("agent-beta")).toBe(taskToolRenderer);
+  });
+
+  test("handles empty array without error", () => {
+    registerAgentToolNames([]);
+    // No error thrown, existing registry unaffected
+    expect(getToolRenderer("Task")).toBe(taskToolRenderer);
+  });
+});
diff --git a/src/ui/tools/registry.ts b/src/ui/tools/registry.ts
index 250fb08008..9953261e90 100644
--- a/src/ui/tools/registry.ts
+++ b/src/ui/tools/registry.ts
@@ -214,6 +214,257 @@ export const editToolRenderer: ToolRenderer = {
   },
 };
 
+interface ApplyPatchOperation {
+  type: "add" | "update" | "delete";
+  path: string;
+  moveTo?: string;
+}
+
+function getApplyPatchText(props: ToolRenderProps): string | undefined {
+  const fromInput = extractApplyPatchText(props.input);
+  if (fromInput) {
+    return fromInput;
+  }
+
+  return extractApplyPatchText(props.output);
+}
+
+function isLikelyApplyPatchText(value: string): boolean {
+  return /\*\*\*\s+Begin Patch/.test(value)
+    || /^\*\*\*\s+(Update|Add|Delete) File:/m.test(value)
+    || /^\*\*\*\s+Move to:/m.test(value);
+}
+
+function extractApplyPatchText(value: unknown): string | undefined {
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    if (trimmed.length === 0) {
+      return undefined;
+    }
+
+    if (isLikelyApplyPatchText(trimmed)) {
+      return value;
+    }
+
+    try {
+      const parsed = JSON.parse(value);
+      return extractApplyPatchText(parsed);
+    } catch {
+      return undefined;
+    }
+  }
+
+  if (Array.isArray(value)) {
+    if (value.every((entry) => typeof entry === "string")) {
+      const joined = value.join("\n");
+      return isLikelyApplyPatchText(joined) ? joined : undefined;
+    }
+    return undefined;
+  }
+
+  if (!value || typeof value !== "object") {
+    return undefined;
+  }
+
+  const record = value as Record<string, unknown>;
+  const patchKeys = [
+    "patchText",
+    "patch_text",
+    "patch",
+    "diff",
+    "content",
+    "input",
+    "arguments",
+    "params",
+    "payload",
+    "data",
+  ];
+
+  for (const key of patchKeys) {
+    const candidate = extractApplyPatchText(record[key]);
+    if (candidate) {
+      return candidate;
+    }
+  }
+
+  return undefined;
+}
+
+function parseApplyPatchOperations(patchText: string): ApplyPatchOperation[] {
+  const operations: ApplyPatchOperation[] = [];
+  const lines = patchText.split("\n");
+
+  for (const line of lines) {
+    const updateMatch = line.match(/^\*\*\* Update File:\s+(.+)$/);
+    if (updateMatch?.[1]) {
+      operations.push({ type: "update", path: updateMatch[1].trim() });
+      continue;
+    }
+
+    const addMatch = line.match(/^\*\*\* Add File:\s+(.+)$/);
+    if (addMatch?.[1]) {
+      operations.push({ type: "add", path: addMatch[1].trim() });
+      continue;
+    }
+
+    const deleteMatch = line.match(/^\*\*\* Delete File:\s+(.+)$/);
+    if (deleteMatch?.[1]) {
+      operations.push({ type: "delete", path: deleteMatch[1].trim() });
+      continue;
+    }
+
+    const moveMatch = line.match(/^\*\*\* Move to:\s+(.+)$/);
+    if (moveMatch?.[1] && operations.length > 0) {
+      operations[operations.length - 1] = {
+        ...operations[operations.length - 1]!,
+        moveTo: moveMatch[1].trim(),
+      };
+    }
+  }
+
+  return operations;
+}
+
+function getApplyPatchOutputOperations(output: unknown): ApplyPatchOperation[] {
+  if (typeof output === "string") {
+    try {
+      const parsed = JSON.parse(output);
+      return getApplyPatchOutputOperations(parsed);
+    } catch {
+      return [];
+    }
+  }
+
+  if (!output || typeof output !== "object") {
+    return [];
+  }
+
+  const outputRecord = output as Record<string, unknown>;
+  const metadata = outputRecord.metadata;
+  const metadataRecord =
+    metadata && typeof metadata === "object"
+      ? metadata as Record<string, unknown>
+      : undefined;
+
+  const files = Array.isArray(outputRecord.files)
+    ? outputRecord.files
+    : Array.isArray(metadataRecord?.files)
+      ? metadataRecord?.files
+      : undefined;
+
+  if (!files) {
+    return [];
+  }
+
+  const operations: ApplyPatchOperation[] = [];
+  for (const file of files) {
+    if (!file || typeof file !== "object") continue;
+    const fileRecord = file as Record<string, unknown>;
+    const path =
+      (typeof fileRecord.relativePath === "string" && fileRecord.relativePath)
+      || (typeof fileRecord.filePath === "string" && fileRecord.filePath)
+      || (typeof fileRecord.path === "string" && fileRecord.path);
+
+    if (!path) continue;
+
+    const rawType =
+      typeof fileRecord.type === "string"
+        ? fileRecord.type.toLowerCase()
+        : "update";
+
+    const type: ApplyPatchOperation["type"] = rawType === "add" || rawType === "create"
+      ? "add"
+      : rawType === "delete" || rawType === "remove"
+        ? "delete"
+        : "update";
+
+    const moveTo = typeof fileRecord.movePath === "string"
+      ? fileRecord.movePath
+      : typeof fileRecord.moveTo === "string"
+        ? fileRecord.moveTo
+        : undefined;
+
+    operations.push({ type, path, moveTo });
+  }
+
+  return operations;
+}
+
+function getApplyPatchTitle(operations: ApplyPatchOperation[]): string {
+  if (operations.length === 0) {
+    return "Apply patch";
+  }
+
+  if (operations.length === 1) {
+    const onlyPath = operations[0]!.path;
+    const parts = onlyPath.split("/");
+    return parts[parts.length - 1] || onlyPath;
+  }
+
+  return `${operations.length} files`;
+}
+
+export const applyPatchToolRenderer: ToolRenderer = {
+  icon: "△",
+
+  getTitle(props: ToolRenderProps): string {
+    const patchText = getApplyPatchText(props);
+    if (patchText) {
+      return getApplyPatchTitle(parseApplyPatchOperations(patchText));
+    }
+
+    const outputOperations = getApplyPatchOutputOperations(props.output);
+    if (outputOperations.length > 0) {
+      return getApplyPatchTitle(outputOperations);
+    }
+
+    return getApplyPatchTitle([]);
+  },
+
+  render(props: ToolRenderProps): ToolRenderResult {
+    const patchText = getApplyPatchText(props);
+    if (patchText) {
+      return {
+        title: this.getTitle(props),
+        content: patchText.split("\n"),
+        language: "diff",
+        expandable: true,
+      };
+    }
+
+    const outputOperations = getApplyPatchOutputOperations(props.output);
+    if (outputOperations.length > 0) {
+      const content: string[] = [];
+      for (const operation of outputOperations) {
+        if (operation.type === "add") {
+          content.push(`*** Add File: ${operation.path}`);
+        } else if (operation.type === "delete") {
+          content.push(`*** Delete File: ${operation.path}`);
+        } else {
+          content.push(`*** Update File: ${operation.path}`);
+        }
+        if (operation.moveTo) {
+          content.push(`*** Move to: ${operation.moveTo}`);
+        }
+      }
+
+      return {
+        title: getApplyPatchTitle(outputOperations),
+        content,
+        language: "diff",
+        expandable: true,
+      };
+    }
+
+    return {
+      title: getApplyPatchTitle([]),
+      content: [],
+      language: "diff",
+      expandable: false,
+    };
+  },
+};
+
 // ============================================================================
 // BASH TOOL RENDERER
 // ============================================================================
@@ -827,9 +1078,17 @@ export const TOOL_RENDERERS: Record<string, ToolRenderer> = {
   todowrite: todoWriteToolRenderer,
   Task: taskToolRenderer,
   task: taskToolRenderer,
+  launch_agent: taskToolRenderer,
   // Copilot equivalents
   create: writeToolRenderer,
   view: readToolRenderer,
+  local_shell: bashToolRenderer,
+  powershell: bashToolRenderer,
+  str_replace_editor: editToolRenderer,
+  str_replace: editToolRenderer,
+  apply_patch: applyPatchToolRenderer,
+  show_file: readToolRenderer,
+  rg: grepToolRenderer,
   // Claude MultiEdit
   MultiEdit: editToolRenderer,
   multiedit: editToolRenderer,
@@ -838,6 +1097,20 @@ export const TOOL_RENDERERS: Record<string, ToolRenderer> = {
   skill: skillToolRenderer,
 };
 
+/**
+ * Dynamically register agent names as task tool renderers.
+ * Called when agent names are discovered from config directories
+ * (.github/agents/, ~/.copilot/agents/, ~/.atomic/.copilot/agents/).
+ * Existing entries are not overwritten.
+ */
+export function registerAgentToolNames(agentNames: string[]): void {
+  for (const name of agentNames) {
+    if (!TOOL_RENDERERS[name]) {
+      TOOL_RENDERERS[name] = taskToolRenderer;
+    }
+  }
+}
+
 // ============================================================================
 // HELPER FUNCTIONS
 // ============================================================================
diff --git a/src/ui/utils/agent-lifecycle-ledger.test.ts b/src/ui/utils/agent-lifecycle-ledger.test.ts
new file mode 100644
index 0000000000..82aee75109
--- /dev/null
+++ b/src/ui/utils/agent-lifecycle-ledger.test.ts
@@ -0,0 +1,111 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  createAgentLifecycleLedger,
+  formatAgentLifecycleViolation,
+  registerAgentLifecycleComplete,
+  registerAgentLifecycleStart,
+  registerAgentLifecycleUpdate,
+} from "./agent-lifecycle-ledger.ts";
+
+describe("agent lifecycle ledger", () => {
+  test("allows ordered start update complete transitions", () => {
+    const ledger = createAgentLifecycleLedger();
+
+    const started = registerAgentLifecycleStart(ledger, "agent-1");
+    const updated = registerAgentLifecycleUpdate(ledger, "agent-1");
+    const completed = registerAgentLifecycleComplete(ledger, "agent-1");
+
+    expect(started.ok).toBeTrue();
+    expect(updated.ok).toBeTrue();
+    expect(completed.ok).toBeTrue();
+    expect(ledger.get("agent-1")).toEqual({
+      started: true,
+      completed: true,
+      sequence: 3,
+    });
+  });
+
+  test("tracks lifecycle entries independently per agent", () => {
+    const ledger = createAgentLifecycleLedger();
+
+    registerAgentLifecycleStart(ledger, "agent-1");
+    registerAgentLifecycleStart(ledger, "agent-2");
+    registerAgentLifecycleUpdate(ledger, "agent-2");
+    registerAgentLifecycleComplete(ledger, "agent-2");
+
+    expect(ledger.get("agent-1")).toEqual({
+      started: true,
+      completed: false,
+      sequence: 1,
+    });
+    expect(ledger.get("agent-2")).toEqual({
+      started: true,
+      completed: true,
+      sequence: 3,
+    });
+  });
+
+  test("rejects update before start", () => {
+    const ledger = createAgentLifecycleLedger();
+
+    const result = registerAgentLifecycleUpdate(ledger, "agent-1");
+
+    expect(result).toEqual({ ok: false, code: "MISSING_START" });
+  });
+
+  test("rejects complete before start", () => {
+    const ledger = createAgentLifecycleLedger();
+
+    const result = registerAgentLifecycleComplete(ledger, "agent-1");
+
+    expect(result).toEqual({ ok: false, code: "MISSING_START" });
+  });
+
+  test("rejects update after complete", () => {
+    const ledger = createAgentLifecycleLedger();
+    registerAgentLifecycleStart(ledger, "agent-1");
+    registerAgentLifecycleComplete(ledger, "agent-1");
+
+    const result = registerAgentLifecycleUpdate(ledger, "agent-1");
+
+    expect(result).toEqual({ ok: false, code: "OUT_OF_ORDER_EVENT" });
+  });
+
+  test("rejects duplicate complete transition", () => {
+    const ledger = createAgentLifecycleLedger();
+    registerAgentLifecycleStart(ledger, "agent-1");
+    registerAgentLifecycleComplete(ledger, "agent-1");
+
+    const result = registerAgentLifecycleComplete(ledger, "agent-1");
+
+    expect(result).toEqual({ ok: false, code: "INVALID_TERMINAL_TRANSITION" });
+  });
+
+  test("rejects start after terminal completion", () => {
+    const ledger = createAgentLifecycleLedger();
+    registerAgentLifecycleStart(ledger, "agent-1");
+    registerAgentLifecycleComplete(ledger, "agent-1");
+
+    const restarted = registerAgentLifecycleStart(ledger, "agent-1");
+
+    expect(restarted).toEqual({ ok: false, code: "INVALID_TERMINAL_TRANSITION" });
+    expect(ledger.get("agent-1")).toEqual({
+      started: true,
+      completed: true,
+      sequence: 2,
+    });
+  });
+
+  test("formats violation diagnostics with event and agent details", () => {
+    const message = formatAgentLifecycleViolation({
+      code: "MISSING_START",
+      eventType: "stream.agent.start",
+      agentId: "agent-1",
+    });
+
+    expect(message).toBe(
+      '[stream.agent.contract_violation] MISSING_START: received stream.agent.start for agent "agent-1" without a valid lifecycle transition.',
+    );
+  });
+});
diff --git a/src/ui/utils/agent-lifecycle-ledger.ts b/src/ui/utils/agent-lifecycle-ledger.ts
new file mode 100644
index 0000000000..619ecdc5cc
--- /dev/null
+++ b/src/ui/utils/agent-lifecycle-ledger.ts
@@ -0,0 +1,84 @@
+export type AgentLifecycleViolationCode =
+  | "MISSING_START"
+  | "OUT_OF_ORDER_EVENT"
+  | "INVALID_TERMINAL_TRANSITION";
+
+export interface AgentLifecycleLedgerEntry {
+  started: boolean;
+  completed: boolean;
+  sequence: number;
+}
+
+export type AgentLifecycleLedger = Map<string, AgentLifecycleLedgerEntry>;
+
+export type AgentLifecycleTransitionResult =
+  | { ok: true; entry: AgentLifecycleLedgerEntry }
+  | { ok: false; code: AgentLifecycleViolationCode };
+
+export function createAgentLifecycleLedger(): AgentLifecycleLedger {
+  return new Map<string, AgentLifecycleLedgerEntry>();
+}
+
+export function registerAgentLifecycleStart(
+  ledger: AgentLifecycleLedger,
+  agentId: string,
+): AgentLifecycleTransitionResult {
+  const existing = ledger.get(agentId);
+  if (existing?.completed) {
+    return { ok: false, code: "INVALID_TERMINAL_TRANSITION" };
+  }
+  const entry: AgentLifecycleLedgerEntry = {
+    started: true,
+    completed: false,
+    sequence: (existing?.sequence ?? 0) + 1,
+  };
+  ledger.set(agentId, entry);
+  return { ok: true, entry };
+}
+
+export function registerAgentLifecycleUpdate(
+  ledger: AgentLifecycleLedger,
+  agentId: string,
+): AgentLifecycleTransitionResult {
+  const existing = ledger.get(agentId);
+  if (!existing || !existing.started) {
+    return { ok: false, code: "MISSING_START" };
+  }
+  if (existing.completed) {
+    return { ok: false, code: "OUT_OF_ORDER_EVENT" };
+  }
+  const entry: AgentLifecycleLedgerEntry = {
+    ...existing,
+    sequence: existing.sequence + 1,
+  };
+  ledger.set(agentId, entry);
+  return { ok: true, entry };
+}
+
+export function registerAgentLifecycleComplete(
+  ledger: AgentLifecycleLedger,
+  agentId: string,
+): AgentLifecycleTransitionResult {
+  const existing = ledger.get(agentId);
+  if (!existing || !existing.started) {
+    return { ok: false, code: "MISSING_START" };
+  }
+  if (existing.completed) {
+    return { ok: false, code: "INVALID_TERMINAL_TRANSITION" };
+  }
+  const entry: AgentLifecycleLedgerEntry = {
+    ...existing,
+    completed: true,
+    sequence: existing.sequence + 1,
+  };
+  ledger.set(agentId, entry);
+  return { ok: true, entry };
+}
+
+export function formatAgentLifecycleViolation(args: {
+  code: AgentLifecycleViolationCode;
+  eventType: "stream.agent.start" | "stream.agent.update" | "stream.agent.complete";
+  agentId: string;
+}): string {
+  return `[stream.agent.contract_violation] ${args.code}: received ${args.eventType} for agent "${args.agentId}" without a valid lifecycle transition.`;
+}
diff --git a/src/ui/utils/auto-compaction-lifecycle.test.ts b/src/ui/utils/auto-compaction-lifecycle.test.ts
index 2b6e072190..1bedce6405 100644
--- a/src/ui/utils/auto-compaction-lifecycle.test.ts
+++ b/src/ui/utils/auto-compaction-lifecycle.test.ts
@@ -59,7 +59,7 @@ describe("auto compaction lifecycle", () => {
       status: "error",
       errorMessage: "token limit exceeded",
     });
-    expect(getAutoCompactionIndicatorLabel(next)).toContain("failed");
+    expect(getAutoCompactionIndicatorLabel(next)).toBe("failed (token limit exceeded)");
     expect(shouldShowAutoCompactionIndicator(next)).toBe(true);
   });
 
diff --git a/src/ui/utils/background-agent-acceptance.test.ts b/src/ui/utils/background-agent-acceptance.test.ts
index 9e1e86554e..b9a132b98e 100644
--- a/src/ui/utils/background-agent-acceptance.test.ts
+++ b/src/ui/utils/background-agent-acceptance.test.ts
@@ -46,9 +46,9 @@ function createAgent(overrides: Partial<ParallelAgent>): ParallelAgent {
 describe("Issue #258 acceptance: background agent UX behavior", () => {
   
   describe("Acceptance: Footer behavior", () => {
-    test("footer shows terminate hint matching 'ctrl+f to kill agents'", () => {
+    test("footer shows terminate hint matching 'ctrl+f to kill all background tasks'", () => {
       // This is the exact text shown in the footer per issue #258
-      expect(BACKGROUND_FOOTER_CONTRACT.terminateHintText).toBe("ctrl+f to kill agents");
+      expect(BACKGROUND_FOOTER_CONTRACT.terminateHintText).toBe("ctrl+f to kill all background tasks");
     });
     
     test("footer becomes visible with 1+ active agents", () => {
@@ -139,9 +139,9 @@ describe("Issue #258 acceptance: background agent UX behavior", () => {
   });
   
   describe("Acceptance: Tree hint behavior", () => {
-    test("running agents hint contains 'background running' and 'ctrl+f to kill agents'", () => {
+    test("running agents hint contains 'background running' and 'ctrl+f to kill all background tasks'", () => {
       // Exact wording for running state hint per issue #258
-      expect(BACKGROUND_TREE_HINT_CONTRACT.whenRunning).toBe("background running · ctrl+f to kill agents");
+      expect(BACKGROUND_TREE_HINT_CONTRACT.whenRunning).toBe("background running · ctrl+f to kill all background tasks");
     });
     
     test("completed agents hint contains 'background complete' and 'ctrl+o to expand'", () => {
diff --git a/src/ui/utils/background-agent-contracts.ts b/src/ui/utils/background-agent-contracts.ts
index 4c9a9e006b..ac8fab5667 100644
--- a/src/ui/utils/background-agent-contracts.ts
+++ b/src/ui/utils/background-agent-contracts.ts
@@ -49,7 +49,7 @@ export interface BackgroundFooterContract {
 export const BACKGROUND_FOOTER_CONTRACT: BackgroundFooterContract = {
   showWhenAgentCountAtLeast: 1,
   includeTerminateHint: true,
-  terminateHintText: "ctrl+f to kill agents",
+  terminateHintText: "ctrl+f to kill all background tasks",
   countFormat: "agents",
 };
 
@@ -68,7 +68,7 @@ export interface BackgroundTreeHintContract {
 
 /** Canonical tree hint contract instance used at runtime. */
 export const BACKGROUND_TREE_HINT_CONTRACT: BackgroundTreeHintContract = {
-  whenRunning: "background running · ctrl+f to kill agents",
+  whenRunning: "background running · ctrl+f to kill all background tasks",
   whenComplete: "background complete · ctrl+o to expand",
   defaultHint: "ctrl+o to expand",
 };
diff --git a/src/ui/utils/background-agent-footer.test.ts b/src/ui/utils/background-agent-footer.test.ts
index 37a8e37573..6db17e4d09 100644
--- a/src/ui/utils/background-agent-footer.test.ts
+++ b/src/ui/utils/background-agent-footer.test.ts
@@ -3,6 +3,7 @@ import type { ParallelAgent } from "../components/parallel-agents-tree.tsx";
 import {
   formatBackgroundAgentFooterStatus,
   getActiveBackgroundAgents,
+  isShadowForegroundAgent,
   resolveBackgroundAgentsForFooter,
 } from "./background-agent-footer.ts";
 import { BACKGROUND_FOOTER_CONTRACT } from "./background-agent-contracts.ts";
@@ -46,6 +47,37 @@ describe("background agent footer helpers", () => {
     ]);
   });
 
+  test("detects uncorrelated foreground shadows when matching background agent exists", () => {
+    const startedAt = new Date("2026-01-01T12:00:00.000Z").toISOString();
+    const agents = [
+      createAgent({
+        id: "tool_1",
+        taskToolCallId: "tool_1",
+        name: "codebase-analyzer",
+        background: true,
+        status: "background",
+        startedAt,
+      }),
+      createAgent({ id: "real-subagent", name: "codebase-analyzer", status: "running", startedAt }),
+    ];
+
+    expect(isShadowForegroundAgent(agents[1]!, agents)).toBe(true);
+  });
+
+  test("does not treat correlated foreground agent with distinct taskToolCallId as shadow", () => {
+    const agents = [
+      createAgent({ id: "bg-1", name: "codebase-analyzer", background: true, status: "background" }),
+      createAgent({
+        id: "fg-1",
+        name: "codebase-analyzer",
+        status: "running",
+        taskToolCallId: "tool_fg_1",
+      }),
+    ];
+
+    expect(isShadowForegroundAgent(agents[1]!, agents)).toBe(false);
+  });
+
   test("prefers live background state when available", () => {
     const liveAgents = [
       createAgent({ id: "live", background: true, status: "background" }),
@@ -132,7 +164,7 @@ describe("background agent footer helpers", () => {
   test("footer contract defines expected canonical values", () => {
     expect(BACKGROUND_FOOTER_CONTRACT.showWhenAgentCountAtLeast).toBe(1);
     expect(BACKGROUND_FOOTER_CONTRACT.includeTerminateHint).toBe(true);
-    expect(BACKGROUND_FOOTER_CONTRACT.terminateHintText).toBe("ctrl+f to kill agents");
+    expect(BACKGROUND_FOOTER_CONTRACT.terminateHintText).toBe("ctrl+f to kill all background tasks");
     expect(BACKGROUND_FOOTER_CONTRACT.countFormat).toBe("agents");
   });
 
diff --git a/src/ui/utils/background-agent-footer.ts b/src/ui/utils/background-agent-footer.ts
index 7c4b95fcf6..33c62b0a5a 100644
--- a/src/ui/utils/background-agent-footer.ts
+++ b/src/ui/utils/background-agent-footer.ts
@@ -8,6 +8,66 @@ export function isBackgroundAgent(agent: ParallelAgent): boolean {
   return agent.background === true || agent.status === "background";
 }
 
+const BACKGROUND_SHADOW_MAX_START_DELTA_MS = 2 * 60 * 1000;
+
+function toEpochMs(iso: string): number | null {
+  const ms = Date.parse(iso);
+  return Number.isFinite(ms) ? ms : null;
+}
+
+/**
+ * Detects foreground "shadow" agents that are duplicate render artifacts
+ * for an already-tracked background agent.
+ *
+ * Shadow agents are treated as non-blocking and hidden from foreground trees.
+ */
+export function isShadowForegroundAgent(
+  agent: ParallelAgent,
+  allAgents: readonly ParallelAgent[],
+): boolean {
+  if (isBackgroundAgent(agent)) return false;
+  if (agent.status !== "running" && agent.status !== "pending") return false;
+
+  const activeBackgroundAgents = allAgents.filter((candidate) => {
+    if (!isBackgroundAgent(candidate)) return false;
+    return isActiveBackgroundStatus(candidate.status);
+  });
+  if (activeBackgroundAgents.length === 0) return false;
+
+  // Strong signal: explicit Task-tool correlation to a background entry.
+  if (agent.taskToolCallId) {
+    return activeBackgroundAgents.some(
+      (backgroundAgent) =>
+        backgroundAgent.id === agent.taskToolCallId
+        || backgroundAgent.taskToolCallId === agent.taskToolCallId,
+    );
+  }
+
+  const eagerBackgroundAgents = activeBackgroundAgents.filter(
+    (backgroundAgent) =>
+      typeof backgroundAgent.taskToolCallId === "string"
+      && backgroundAgent.taskToolCallId.length > 0
+      && backgroundAgent.id === backgroundAgent.taskToolCallId,
+  );
+
+  // Fallback for missing correlation IDs (provider parity edge case):
+  // same agent type/name launched within a short window, but only against
+  // eager Task placeholders (id === taskToolCallId).
+  if (eagerBackgroundAgents.length === 0) return false;
+
+  const normalizedName = agent.name.trim().toLowerCase();
+  if (normalizedName.length === 0) return false;
+  const foregroundStartMs = toEpochMs(agent.startedAt);
+  if (foregroundStartMs === null) return false;
+
+  return eagerBackgroundAgents.some((backgroundAgent) => {
+    if (backgroundAgent.name.trim().toLowerCase() !== normalizedName) return false;
+    const backgroundStartMs = toEpochMs(backgroundAgent.startedAt);
+    if (backgroundStartMs === null) return false;
+    return Math.abs(foregroundStartMs - backgroundStartMs) <= BACKGROUND_SHADOW_MAX_START_DELTA_MS;
+  });
+}
+
 function isActiveBackgroundStatus(status: ParallelAgent["status"]): boolean {
   return status === "background" || status === "running" || status === "pending";
 }
diff --git a/src/ui/utils/background-agent-provider-parity.test.ts b/src/ui/utils/background-agent-provider-parity.test.ts
index 003f00e926..4a709ca3aa 100644
--- a/src/ui/utils/background-agent-provider-parity.test.ts
+++ b/src/ui/utils/background-agent-provider-parity.test.ts
@@ -117,7 +117,7 @@ describe("Background agent provider parity matrix", () => {
         expect(BACKGROUND_FOOTER_CONTRACT).toEqual({
           showWhenAgentCountAtLeast: 1,
           includeTerminateHint: true,
-          terminateHintText: "ctrl+f to kill agents",
+          terminateHintText: "ctrl+f to kill all background tasks",
           countFormat: "agents",
         });
       },
@@ -177,7 +177,7 @@ describe("Background agent provider parity matrix", () => {
 
         // All providers see the same contract instance
         expect(BACKGROUND_TREE_HINT_CONTRACT).toEqual({
-          whenRunning: "background running · ctrl+f to kill agents",
+          whenRunning: "background running · ctrl+f to kill all background tasks",
           whenComplete: "background complete · ctrl+o to expand",
           defaultHint: "ctrl+o to expand",
         });
@@ -199,7 +199,7 @@ describe("Background agent provider parity matrix", () => {
 
         // When running
         expect(buildParallelAgentsHeaderHint(runningAgents, true)).toBe(
-          "background running · ctrl+f to kill agents",
+          "background running · ctrl+f to kill all background tasks",
         );
 
         // When complete
@@ -398,7 +398,7 @@ describe("Background agent provider parity matrix", () => {
         expect(activeBackground.map((a) => a.id).sort()).toEqual(["bg-1", "bg-2"]);
 
         const hint = buildParallelAgentsHeaderHint(agents, true);
-        expect(hint).toBe("background running · ctrl+f to kill agents");
+        expect(hint).toBe("background running · ctrl+f to kill all background tasks");
 
         const result = interruptActiveBackgroundAgents(agents);
         expect(result.interruptedIds.length).toBe(2);
diff --git a/src/ui/utils/background-agent-runtime-parity.test.ts b/src/ui/utils/background-agent-runtime-parity.test.ts
index 31213a42db..e93ca4c8fe 100644
--- a/src/ui/utils/background-agent-runtime-parity.test.ts
+++ b/src/ui/utils/background-agent-runtime-parity.test.ts
@@ -69,7 +69,7 @@ describe("Background agent runtime parity (dev/prod invariance)", () => {
       // Verify exact values
       expect(contract.showWhenAgentCountAtLeast).toBe(1);
       expect(contract.includeTerminateHint).toBe(true);
-      expect(contract.terminateHintText).toBe("ctrl+f to kill agents");
+      expect(contract.terminateHintText).toBe("ctrl+f to kill all background tasks");
       expect(contract.countFormat).toBe("agents");
 
       // Verify object stability (same reference across calls)
@@ -84,7 +84,7 @@ describe("Background agent runtime parity (dev/prod invariance)", () => {
       const contract = BACKGROUND_TREE_HINT_CONTRACT;
 
       // Verify exact values
-      expect(contract.whenRunning).toBe("background running · ctrl+f to kill agents");
+      expect(contract.whenRunning).toBe("background running · ctrl+f to kill all background tasks");
       expect(contract.whenComplete).toBe("background complete · ctrl+o to expand");
       expect(contract.defaultHint).toBe("ctrl+o to expand");
 
@@ -246,7 +246,7 @@ describe("Background agent runtime parity (dev/prod invariance)", () => {
 
     test("buildParallelAgentsHeaderHint produces identical outputs for identical inputs", () => {
       const testCases = [
-        [[createAgent({ status: "background" })], true, "background running · ctrl+f to kill agents"],
+        [[createAgent({ status: "background" })], true, "background running · ctrl+f to kill all background tasks"],
         [[createAgent({ status: "completed", background: true })], true, "background complete · ctrl+o to expand"],
         [[], true, "ctrl+o to expand"],
         [[], false, ""],
@@ -358,7 +358,7 @@ describe("Background agent runtime parity (dev/prod invariance)", () => {
 
       // All results must be identical
       for (const result of results) {
-        expect(result).toBe("background running · ctrl+f to kill agents");
+        expect(result).toBe("background running · ctrl+f to kill all background tasks");
       }
     });
   });
@@ -391,7 +391,7 @@ describe("Background agent runtime parity (dev/prod invariance)", () => {
 
       // Test hint building
       const hint = buildParallelAgentsHeaderHint(agents, true);
-      expect(hint).toBe("background running · ctrl+f to kill agents");
+      expect(hint).toBe("background running · ctrl+f to kill all background tasks");
 
       // Test active agent filtering
       const activeAgents = getActiveBackgroundAgents(agents);
@@ -532,7 +532,7 @@ describe("Background agent runtime parity (dev/prod invariance)", () => {
       const noAgents: ParallelAgent[] = [];
 
       expect(buildParallelAgentsHeaderHint(runningAgents, true)).toBe(
-        "background running · ctrl+f to kill agents",
+        "background running · ctrl+f to kill all background tasks",
       );
       expect(buildParallelAgentsHeaderHint(completedAgents, true)).toBe(
         "background complete · ctrl+o to expand",
@@ -567,12 +567,12 @@ describe("Background agent runtime parity (dev/prod invariance)", () => {
       expect(footerContract).toEqual({
         showWhenAgentCountAtLeast: 1,
         includeTerminateHint: true,
-        terminateHintText: "ctrl+f to kill agents",
+        terminateHintText: "ctrl+f to kill all background tasks",
         countFormat: "agents",
       });
 
       expect(treeContract).toEqual({
-        whenRunning: "background running · ctrl+f to kill agents",
+        whenRunning: "background running · ctrl+f to kill all background tasks",
         whenComplete: "background complete · ctrl+o to expand",
         defaultHint: "ctrl+o to expand",
       });
diff --git a/src/ui/utils/background-agent-termination-integration.test.ts b/src/ui/utils/background-agent-termination-integration.test.ts
index 1c5e5932a6..037b8ca2f8 100644
--- a/src/ui/utils/background-agent-termination-integration.test.ts
+++ b/src/ui/utils/background-agent-termination-integration.test.ts
@@ -329,7 +329,7 @@ describe("Ctrl+F double-press lifecycle integration", () => {
 
     // Verify footer contract includes terminate hint
     expect(BACKGROUND_FOOTER_CONTRACT.includeTerminateHint).toBe(true);
-    expect(BACKGROUND_FOOTER_CONTRACT.terminateHintText).toBe("ctrl+f to kill agents");
+    expect(BACKGROUND_FOOTER_CONTRACT.terminateHintText).toBe("ctrl+f to kill all background tasks");
 
     // Verify tree hint contract includes termination hint for running agents
     expect(BACKGROUND_TREE_HINT_CONTRACT.whenRunning).toContain("ctrl+f");
diff --git a/src/ui/utils/background-agent-termination.test.ts b/src/ui/utils/background-agent-termination.test.ts
index a6a9c8ad85..7ecec1c815 100644
--- a/src/ui/utils/background-agent-termination.test.ts
+++ b/src/ui/utils/background-agent-termination.test.ts
@@ -1,6 +1,8 @@
 import { describe, expect, test } from "bun:test";
 import type { ParallelAgent } from "../components/parallel-agents-tree.tsx";
 import {
+  evaluateBackgroundTerminationPress,
+  executeBackgroundTermination,
   getBackgroundTerminationDecision,
   interruptActiveBackgroundAgents,
   isBackgroundTerminationKey,
@@ -49,6 +51,23 @@ describe("background-agent termination keybinding", () => {
       action: "none",
     });
   });
+
+  test("handles two rapid Ctrl+F presses without waiting for React state flush", () => {
+    const pressCountRef = { current: 0 };
+
+    const firstPress = evaluateBackgroundTerminationPress(pressCountRef, 2);
+    expect(firstPress.decision.action).toBe("warn");
+    expect(firstPress.pressCount).toBe(0);
+    expect(firstPress.nextPressCount).toBe(1);
+
+    // Simulate a second key event in the same input frame.
+    // The synchronous ref mutation should make this a terminate action.
+    const secondPress = evaluateBackgroundTerminationPress(pressCountRef, 2);
+    expect(secondPress.decision.action).toBe("terminate");
+    expect(secondPress.pressCount).toBe(1);
+    expect(secondPress.nextPressCount).toBe(0);
+    expect(pressCountRef.current).toBe(0);
+  });
 });
 
 describe("background-agent termination flow", () => {
@@ -133,4 +152,87 @@ describe("background-agent termination flow", () => {
     expect(result.interruptedIds).toEqual([]);
     expect(result.agents).toEqual(agents);
   });
+
+  test("waits for parent abort callback before applying local interruption", async () => {
+    const agents: ParallelAgent[] = [
+      createAgent({ id: "bg-active", status: "background", background: true }),
+      createAgent({ id: "fg-running", status: "running", background: false }),
+    ];
+    const callbackOrder: string[] = [];
+
+    const result = await executeBackgroundTermination({
+      getAgents: () => agents,
+      onTerminateBackgroundAgents: async () => {
+        callbackOrder.push("callback");
+      },
+    });
+
+    callbackOrder.push("after");
+    expect(callbackOrder).toEqual(["callback", "after"]);
+    expect(result.status).toBe("terminated");
+    expect(result.interruptedIds).toEqual(["bg-active"]);
+    expect(result.agents.find((agent) => agent.id === "bg-active")?.status).toBe("interrupted");
+    expect(result.agents.find((agent) => agent.id === "fg-running")?.status).toBe("running");
+  });
+
+  test("returns failed result and preserves live agents when abort callback rejects", async () => {
+    const agents: ParallelAgent[] = [
+      createAgent({ id: "bg-active", status: "background", background: true }),
+    ];
+
+    const result = await executeBackgroundTermination({
+      getAgents: () => agents,
+      onTerminateBackgroundAgents: async () => {
+        throw new Error("abort failed");
+      },
+    });
+
+    expect(result.status).toBe("failed");
+    expect(result.interruptedIds).toEqual([]);
+    expect(result.agents).toEqual(agents);
+    if (result.status === "failed") {
+      expect(result.error).toBeInstanceOf(Error);
+      expect((result.error as Error).message).toBe("abort failed");
+    }
+  });
+
+  test("does not invoke parent callback when no active background agents exist", async () => {
+    const callbackInvoked = { current: false };
+    const agents: ParallelAgent[] = [
+      createAgent({ id: "done", status: "completed", background: true }),
+      createAgent({ id: "fg", status: "running", background: false }),
+    ];
+
+    const result = await executeBackgroundTermination({
+      getAgents: () => agents,
+      onTerminateBackgroundAgents: async () => {
+        callbackInvoked.current = true;
+      },
+    });
+
+    expect(result.status).toBe("noop");
+    expect(result.interruptedIds).toEqual([]);
+    expect(callbackInvoked.current).toBe(false);
+  });
+
+  test("re-evaluates live agents after callback to avoid stale snapshots", async () => {
+    const activeAgents: ParallelAgent[] = [
+      createAgent({ id: "bg-active", status: "background", background: true }),
+    ];
+    const completedAgents: ParallelAgent[] = [
+      createAgent({ id: "bg-active", status: "completed", background: true }),
+    ];
+    let snapshot = activeAgents;
+
+    const result = await executeBackgroundTermination({
+      getAgents: () => snapshot,
+      onTerminateBackgroundAgents: async () => {
+        snapshot = completedAgents;
+      },
+    });
+
+    expect(result.status).toBe("terminated");
+    expect(result.interruptedIds).toEqual([]);
+    expect(result.agents).toEqual(completedAgents);
+  });
 });
diff --git a/src/ui/utils/background-agent-termination.ts b/src/ui/utils/background-agent-termination.ts
index cabde4f098..5aedfb328f 100644
--- a/src/ui/utils/background-agent-termination.ts
+++ b/src/ui/utils/background-agent-termination.ts
@@ -17,6 +17,36 @@ export interface InterruptBackgroundAgentsResult {
   interruptedIds: string[];
 }
 
+export interface BackgroundTerminationPressEvaluation {
+  pressCount: number;
+  nextPressCount: number;
+  decision: BackgroundTerminationDecision;
+}
+
+export interface ExecuteBackgroundTerminationOptions {
+  getAgents: () => readonly ParallelAgent[];
+  onTerminateBackgroundAgents?: () => void | Promise<void>;
+  nowMs?: number;
+}
+
+export type ExecuteBackgroundTerminationResult =
+  | {
+    status: "noop";
+    agents: ParallelAgent[];
+    interruptedIds: [];
+  }
+  | {
+    status: "terminated";
+    agents: ParallelAgent[];
+    interruptedIds: string[];
+  }
+  | {
+    status: "failed";
+    agents: ParallelAgent[];
+    interruptedIds: [];
+    error: unknown;
+  };
+
 export function isBackgroundTerminationKey(event: BackgroundTerminationKeyEvent): boolean {
   return event.ctrl === true
     && event.shift !== true
@@ -45,6 +75,27 @@ export function getBackgroundTerminationDecision(
   };
 }
 
+/**
+ * Evaluate a Ctrl+F keypress using a synchronous mutable press counter.
+ *
+ * This intentionally mutates `pressCountRef.current` immediately so rapid
+ * key events in the same input frame do not read stale React state.
+ */
+export function evaluateBackgroundTerminationPress(
+  pressCountRef: { current: number },
+  activeBackgroundAgentCount: number,
+): BackgroundTerminationPressEvaluation {
+  const pressCount = pressCountRef.current;
+  const decision = getBackgroundTerminationDecision(pressCount, activeBackgroundAgentCount);
+  const nextPressCount = decision.action === "warn" ? pressCount + 1 : 0;
+  pressCountRef.current = nextPressCount;
+  return {
+    pressCount,
+    nextPressCount,
+    decision,
+  };
+}
+
 export function interruptActiveBackgroundAgents(
   agents: readonly ParallelAgent[],
   nowMs: number = Date.now(),
@@ -82,3 +133,44 @@ export function interruptActiveBackgroundAgents(
     interruptedIds,
   };
 }
+
+/**
+ * Execute confirmed background termination in two phases:
+ * 1) verify there is active work to terminate,
+ * 2) await runtime abort callback,
+ * 3) apply local interruption state against the latest agent snapshot.
+ */
+export async function executeBackgroundTermination(
+  options: ExecuteBackgroundTerminationOptions,
+): Promise<ExecuteBackgroundTerminationResult> {
+  const initialAgents = options.getAgents();
+  const hasActiveBackgroundAgents = getActiveBackgroundAgents(initialAgents).length > 0;
+  if (!hasActiveBackgroundAgents) {
+    return {
+      status: "noop",
+      agents: [...initialAgents],
+      interruptedIds: [],
+    };
+  }
+
+  try {
+    await Promise.resolve(options.onTerminateBackgroundAgents?.());
+  } catch (error) {
+    return {
+      status: "failed",
+      agents: [...options.getAgents()],
+      interruptedIds: [],
+      error,
+    };
+  }
+
+  const result = interruptActiveBackgroundAgents(
+    options.getAgents(),
+    options.nowMs ?? Date.now(),
+  );
+  return {
+    status: "terminated",
+    agents: result.agents,
+    interruptedIds: result.interruptedIds,
+  };
+}
diff --git a/src/ui/utils/background-agent-tree-hints.test.ts b/src/ui/utils/background-agent-tree-hints.test.ts
index 1880051d3e..40bffa5e16 100644
--- a/src/ui/utils/background-agent-tree-hints.test.ts
+++ b/src/ui/utils/background-agent-tree-hints.test.ts
@@ -100,7 +100,7 @@ describe("background agent tree hints", () => {
   });
 
   test("contract constants define expected canonical hint strings", () => {
-    expect(BACKGROUND_TREE_HINT_CONTRACT.whenRunning).toBe("background running · ctrl+f to kill agents");
+    expect(BACKGROUND_TREE_HINT_CONTRACT.whenRunning).toBe("background running · ctrl+f to kill all background tasks");
     expect(BACKGROUND_TREE_HINT_CONTRACT.whenComplete).toBe("background complete · ctrl+o to expand");
     expect(BACKGROUND_TREE_HINT_CONTRACT.defaultHint).toBe("ctrl+o to expand");
   });
diff --git a/src/ui/utils/background-update-flush.test.ts b/src/ui/utils/background-update-flush.test.ts
new file mode 100644
index 0000000000..bb78ab5b6e
--- /dev/null
+++ b/src/ui/utils/background-update-flush.test.ts
@@ -0,0 +1,74 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  shouldScheduleBackgroundUpdateFollowUpFlush,
+  shouldStartBackgroundUpdateFlush,
+} from "./background-update-flush.ts";
+
+describe("shouldStartBackgroundUpdateFlush", () => {
+  test("returns true when idle with pending updates", () => {
+    expect(shouldStartBackgroundUpdateFlush({
+      hasFlushInFlight: false,
+      isStreaming: false,
+      pendingUpdateCount: 2,
+    })).toBe(true);
+  });
+
+  test("returns false when a flush is already in flight", () => {
+    expect(shouldStartBackgroundUpdateFlush({
+      hasFlushInFlight: true,
+      isStreaming: false,
+      pendingUpdateCount: 2,
+    })).toBe(false);
+  });
+
+  test("returns false while streaming", () => {
+    expect(shouldStartBackgroundUpdateFlush({
+      hasFlushInFlight: false,
+      isStreaming: true,
+      pendingUpdateCount: 2,
+    })).toBe(false);
+  });
+
+  test("returns false when queue is empty", () => {
+    expect(shouldStartBackgroundUpdateFlush({
+      hasFlushInFlight: false,
+      isStreaming: false,
+      pendingUpdateCount: 0,
+    })).toBe(false);
+  });
+});
+
+describe("shouldScheduleBackgroundUpdateFollowUpFlush", () => {
+  test("returns true after a successful send with remaining queued updates", () => {
+    expect(shouldScheduleBackgroundUpdateFollowUpFlush({
+      sendSucceeded: true,
+      isStreaming: false,
+      pendingUpdateCount: 1,
+    })).toBe(true);
+  });
+
+  test("returns false after failed send", () => {
+    expect(shouldScheduleBackgroundUpdateFollowUpFlush({
+      sendSucceeded: false,
+      isStreaming: false,
+      pendingUpdateCount: 1,
+    })).toBe(false);
+  });
+
+  test("returns false while streaming", () => {
+    expect(shouldScheduleBackgroundUpdateFollowUpFlush({
+      sendSucceeded: true,
+      isStreaming: true,
+      pendingUpdateCount: 1,
+    })).toBe(false);
+  });
+
+  test("returns false when no queued updates remain", () => {
+    expect(shouldScheduleBackgroundUpdateFollowUpFlush({
+      sendSucceeded: true,
+      isStreaming: false,
+      pendingUpdateCount: 0,
+    })).toBe(false);
+  });
+});
diff --git a/src/ui/utils/background-update-flush.ts b/src/ui/utils/background-update-flush.ts
new file mode 100644
index 0000000000..eb5622edf1
--- /dev/null
+++ b/src/ui/utils/background-update-flush.ts
@@ -0,0 +1,27 @@
+export interface BackgroundUpdateFlushStartState {
+  hasFlushInFlight: boolean;
+  isStreaming: boolean;
+  pendingUpdateCount: number;
+}
+
+export function shouldStartBackgroundUpdateFlush(
+  state: BackgroundUpdateFlushStartState,
+): boolean {
+  return !state.hasFlushInFlight
+    && !state.isStreaming
+    && state.pendingUpdateCount > 0;
+}
+
+export interface BackgroundUpdateFlushFollowUpState {
+  sendSucceeded: boolean;
+  isStreaming: boolean;
+  pendingUpdateCount: number;
+}
+
+export function shouldScheduleBackgroundUpdateFollowUpFlush(
+  state: BackgroundUpdateFlushFollowUpState,
+): boolean {
+  return state.sendSucceeded
+    && !state.isStreaming
+    && state.pendingUpdateCount > 0;
+}
diff --git a/src/ui/utils/format.test.ts b/src/ui/utils/format.test.ts
index 68bfb50b25..ec3ddaffb2 100644
--- a/src/ui/utils/format.test.ts
+++ b/src/ui/utils/format.test.ts
@@ -2,11 +2,11 @@ import { describe, expect, test } from "bun:test";
 import { formatDuration, formatTimestamp, normalizeMarkdownNewlines, truncateText } from "./format";
 
 describe("formatDuration", () => {
-  test("formats milliseconds under 1 second", () => {
-    expect(formatDuration(0)).toEqual({ text: "0ms", ms: 0 });
-    expect(formatDuration(1)).toEqual({ text: "1ms", ms: 1 });
-    expect(formatDuration(500)).toEqual({ text: "500ms", ms: 500 });
-    expect(formatDuration(999)).toEqual({ text: "999ms", ms: 999 });
+  test("formats sub-second values as seconds", () => {
+    expect(formatDuration(0)).toEqual({ text: "0s", ms: 0 });
+    expect(formatDuration(1)).toEqual({ text: "1s", ms: 1 });
+    expect(formatDuration(500)).toEqual({ text: "1s", ms: 500 });
+    expect(formatDuration(999)).toEqual({ text: "1s", ms: 999 });
   });
 
   test("formats seconds (1000ms to 59999ms)", () => {
@@ -30,14 +30,14 @@ describe("formatDuration", () => {
   });
 
   test("handles negative values as zero", () => {
-    expect(formatDuration(-1)).toEqual({ text: "0ms", ms: 0 });
-    expect(formatDuration(-1000)).toEqual({ text: "0ms", ms: 0 });
-    expect(formatDuration(-99999)).toEqual({ text: "0ms", ms: 0 });
+    expect(formatDuration(-1)).toEqual({ text: "0s", ms: 0 });
+    expect(formatDuration(-1000)).toEqual({ text: "0s", ms: 0 });
+    expect(formatDuration(-99999)).toEqual({ text: "0s", ms: 0 });
   });
 
   test("handles boundary values", () => {
     // Just under 1 second
-    expect(formatDuration(999)).toEqual({ text: "999ms", ms: 999 });
+    expect(formatDuration(999)).toEqual({ text: "1s", ms: 999 });
     // Exactly 1 second
     expect(formatDuration(1000)).toEqual({ text: "1s", ms: 1000 });
     // Just under 1 minute
diff --git a/src/ui/utils/format.ts b/src/ui/utils/format.ts
index 0234c8381c..61e6b3314d 100644
--- a/src/ui/utils/format.ts
+++ b/src/ui/utils/format.ts
@@ -36,10 +36,11 @@ export interface FormattedTimestamp {
 // ============================================================================
 
 /**
- * Format a duration in milliseconds to a human-readable string.
+ * Format a duration in milliseconds to a human-readable string, always rounded to whole seconds.
  *
- * - Under 1000ms: Shows milliseconds (e.g., "500ms")
- * - Under 60000ms (1 minute): Shows seconds (e.g., "2.5s")
+ * - 0 or negative: Shows "0s"
+ * - Under 1000ms (but positive): Shows "1s" (rounds up)
+ * - Under 60000ms (1 minute): Shows seconds (e.g., "2s")
  * - 60000ms and above: Shows minutes and seconds (e.g., "1m 30s")
  *
  * @param ms - Duration in milliseconds
@@ -47,30 +48,25 @@ export interface FormattedTimestamp {
  *
  * @example
  * ```ts
- * formatDuration(500)    // { text: "500ms", ms: 500 }
- * formatDuration(2500)   // { text: "2.5s", ms: 2500 }
+ * formatDuration(500)    // { text: "1s", ms: 500 }
+ * formatDuration(2500)   // { text: "2s", ms: 2500 }
  * formatDuration(90000)  // { text: "1m 30s", ms: 90000 }
  * ```
  */
 export function formatDuration(ms: number): FormattedDuration {
-  // Handle negative values by treating as 0
-  if (ms < 0) {
-    return { text: "0ms", ms: 0 };
+  // Handle negative values and zero
+  if (ms <= 0) {
+    return { text: "0s", ms: 0 };
   }
 
-  // Under 1 second: show milliseconds
-  if (ms < 1000) {
-    return { text: `${Math.round(ms)}ms`, ms };
-  }
+  const totalSeconds = Math.max(1, Math.floor(ms / 1000));
 
   // Under 1 minute: show whole seconds
-  if (ms < 60000) {
-    const seconds = Math.floor(ms / 1000);
-    return { text: `${seconds}s`, ms };
+  if (totalSeconds < 60) {
+    return { text: `${totalSeconds}s`, ms };
   }
 
   // 1 minute and above: show minutes and seconds
-  const totalSeconds = Math.floor(ms / 1000);
   const minutes = Math.floor(totalSeconds / 60);
   const seconds = totalSeconds % 60;
 
diff --git a/src/ui/utils/index.ts b/src/ui/utils/index.ts
index ee5196bec6..ecb50eb2ce 100644
--- a/src/ui/utils/index.ts
+++ b/src/ui/utils/index.ts
@@ -34,10 +34,6 @@ export {
 } from "./task-status.ts";
 
 // Message window utilities
-export {
-  shouldCollapseMessage,
-} from "./message-window.ts";
-
 // Tool preview truncation utilities
 export {
   MAIN_CHAT_TOOL_PREVIEW_LIMITS,
diff --git a/src/ui/utils/loading-state.ts b/src/ui/utils/loading-state.ts
index b196fcd0b9..a380dfc5db 100644
--- a/src/ui/utils/loading-state.ts
+++ b/src/ui/utils/loading-state.ts
@@ -45,7 +45,13 @@ export function shouldShowMessageLoadingIndicator(
     (agent) => agent.background && agent.status === "background",
   );
 
-  return Boolean(message.streaming) || hasActiveBackgroundAgents;
+  // Also drive re-renders while foreground agents are running/pending
+  // so the elapsed timer in ParallelAgentsTree stays live.
+  const hasActiveForegroundAgents = (message.parallelAgents ?? []).some(
+    (agent) => !agent.background && (agent.status === "running" || agent.status === "pending"),
+  );
+
+  return Boolean(message.streaming) || hasActiveBackgroundAgents || hasActiveForegroundAgents;
 }
 
 export function hasLiveLoadingIndicator(
@@ -69,3 +75,4 @@ export function shouldShowCompletionSummary(
     && message.durationMs != null
     && message.durationMs >= 1000;
 }
+
diff --git a/src/ui/utils/message-window.test.ts b/src/ui/utils/message-window.test.ts
deleted file mode 100644
index 2ac0141000..0000000000
--- a/src/ui/utils/message-window.test.ts
+++ /dev/null
@@ -1,44 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import { shouldCollapseMessage } from "./message-window.ts";
-
-describe("shouldCollapseMessage", () => {
-  test("last N messages are expanded, earlier ones collapsed", () => {
-    // 10 messages, expandedCount=4 → indices 0-5 collapsed, 6-9 expanded
-    expect(shouldCollapseMessage(0, 10, 4, false)).toBe(true);
-    expect(shouldCollapseMessage(5, 10, 4, false)).toBe(true);
-    expect(shouldCollapseMessage(6, 10, 4, false)).toBe(false);
-    expect(shouldCollapseMessage(9, 10, 4, false)).toBe(false);
-  });
-
-  test("fewer messages than expanded count means all expanded", () => {
-    expect(shouldCollapseMessage(0, 3, 4, false)).toBe(false);
-    expect(shouldCollapseMessage(1, 3, 4, false)).toBe(false);
-    expect(shouldCollapseMessage(2, 3, 4, false)).toBe(false);
-  });
-
-  test("exactly equal to expanded count means all expanded", () => {
-    expect(shouldCollapseMessage(0, 4, 4, false)).toBe(false);
-    expect(shouldCollapseMessage(3, 4, 4, false)).toBe(false);
-  });
-
-  test("live messages are never collapsed regardless of position", () => {
-    expect(shouldCollapseMessage(0, 10, 4, true)).toBe(false);
-    expect(shouldCollapseMessage(1, 10, 4, true)).toBe(false);
-  });
-
-  test("zero messages edge case", () => {
-    expect(shouldCollapseMessage(0, 0, 4, false)).toBe(false);
-  });
-
-  test("single message over expanded count is collapsed", () => {
-    // 5 messages, expandedCount=4 → index 0 collapsed, 1-4 expanded
-    expect(shouldCollapseMessage(0, 5, 4, false)).toBe(true);
-    expect(shouldCollapseMessage(1, 5, 4, false)).toBe(false);
-  });
-
-  test("expandedCount=1 collapses all but the last", () => {
-    expect(shouldCollapseMessage(0, 5, 1, false)).toBe(true);
-    expect(shouldCollapseMessage(3, 5, 1, false)).toBe(true);
-    expect(shouldCollapseMessage(4, 5, 1, false)).toBe(false);
-  });
-});
diff --git a/src/ui/utils/message-window.ts b/src/ui/utils/message-window.ts
deleted file mode 100644
index 686f952f1b..0000000000
--- a/src/ui/utils/message-window.ts
+++ /dev/null
@@ -1,22 +0,0 @@
-/**
- * Message windowing utilities for the main chat view.
- *
- * Provides helpers for deciding which messages to auto-collapse
- * vs. keep fully expanded.
- */
-
-/**
- * Determine whether a message at the given index should be auto-collapsed.
- * Messages in the last `expandedCount` positions are kept fully expanded.
- * Messages that are live (streaming or have active background agents) are
- * never collapsed regardless of position.
- */
-export function shouldCollapseMessage(
-  index: number,
-  totalMessages: number,
-  expandedCount: number,
-  isLive: boolean
-): boolean {
-  if (isLive) return false;
-  return index < totalMessages - expandedCount;
-}
diff --git a/src/ui/utils/newline-strategies.test.ts b/src/ui/utils/newline-strategies.test.ts
index 911fce5283..e636b9415d 100644
--- a/src/ui/utils/newline-strategies.test.ts
+++ b/src/ui/utils/newline-strategies.test.ts
@@ -2,6 +2,7 @@ import { describe, expect, test } from "bun:test";
 
 import {
   getEnqueueShortcutLabel,
+  isBareLinefeedEvent,
   shouldApplyBackslashLineContinuation,
   shouldEnqueueMessageFromKeyEvent,
   shouldInsertNewlineFromKeyEvent,
@@ -97,4 +98,118 @@ describe("enqueue shortcut handling", () => {
     expect(getEnqueueShortcutLabel("linux")).toBe("ctrl+shift+enter");
     expect(getEnqueueShortcutLabel("win32")).toBe("ctrl+shift+enter");
   });
+
+  test("detects Ctrl+Shift+Enter from CSI-u raw sequence (non-mac)", () => {
+    // \x1b[13;6u = Enter codepoint 13, modifier 6 (Ctrl+Shift)
+    expect(
+      shouldEnqueueMessageFromKeyEvent(
+        { name: "undefined-key", raw: "\x1b[13;6u" },
+        "win32",
+      ),
+    ).toBe(true);
+    // Linefeed codepoint variant
+    expect(
+      shouldEnqueueMessageFromKeyEvent(
+        { name: "undefined-key", raw: "\x1b[10;6u" },
+        "linux",
+      ),
+    ).toBe(true);
+  });
+
+  test("detects Cmd+Shift+Enter from CSI-u raw sequence (macOS)", () => {
+    // modifier 10 = 0b1001 + 1 = meta + shift (mods-1 = 9 → shift=1, meta=8)
+    expect(
+      shouldEnqueueMessageFromKeyEvent(
+        { name: "undefined-key", raw: "\x1b[13;10u" },
+        "darwin",
+      ),
+    ).toBe(true);
+  });
+
+  test("detects Ctrl+Shift+Enter from modifyOtherKeys raw sequence", () => {
+    // \x1b[27;6;13~ = modifyOtherKeys modifier 6 (Ctrl+Shift), codepoint 13
+    expect(
+      shouldEnqueueMessageFromKeyEvent(
+        { name: "return", raw: "\x1b[27;6;13~" },
+        "win32",
+      ),
+    ).toBe(true);
+    expect(
+      shouldEnqueueMessageFromKeyEvent(
+        { name: "return", raw: "\x1b[27;6;10~" },
+        "linux",
+      ),
+    ).toBe(true);
+  });
+
+  test("does not detect enqueue from Shift-only CSI-u (no Ctrl)", () => {
+    // modifier 2 = Shift only (mods-1=1, shift=1, ctrl=0)
+    expect(
+      shouldEnqueueMessageFromKeyEvent(
+        { name: "undefined-key", raw: "\x1b[13;2u" },
+        "win32",
+      ),
+    ).toBe(false);
+  });
+
+  test("does not detect enqueue from bare linefeed", () => {
+    expect(
+      shouldEnqueueMessageFromKeyEvent(
+        { name: "linefeed", shift: false, ctrl: false, raw: "\n" },
+        "win32",
+      ),
+    ).toBe(false);
+  });
+});
+
+describe("isBareLinefeedEvent", () => {
+  test("returns true for bare linefeed with no modifiers and raw \\n", () => {
+    expect(isBareLinefeedEvent({
+      name: "linefeed",
+      shift: false,
+      ctrl: false,
+      meta: false,
+      raw: "\n",
+    })).toBe(true);
+  });
+
+  test("returns false when shift is set", () => {
+    expect(isBareLinefeedEvent({
+      name: "linefeed",
+      shift: true,
+      ctrl: false,
+      meta: false,
+      raw: "\n",
+    })).toBe(false);
+  });
+
+  test("returns false for meta-linefeed (ESC+\\n)", () => {
+    expect(isBareLinefeedEvent({
+      name: "linefeed",
+      shift: false,
+      ctrl: false,
+      meta: true,
+      raw: "\x1b\n",
+    })).toBe(false);
+  });
+
+  test("returns false for return events", () => {
+    expect(isBareLinefeedEvent({
+      name: "return",
+      shift: false,
+      ctrl: false,
+      meta: false,
+      raw: "\r",
+    })).toBe(false);
+  });
+
+  test("returns false when raw is an escape sequence, not bare \\n", () => {
+    expect(isBareLinefeedEvent({
+      name: "linefeed",
+      shift: false,
+      ctrl: false,
+      meta: false,
+      raw: "\x1b[10u",
+    })).toBe(false);
+  });
 });
diff --git a/src/ui/utils/newline-strategies.ts b/src/ui/utils/newline-strategies.ts
index bbd774de0f..d93484b77a 100644
--- a/src/ui/utils/newline-strategies.ts
+++ b/src/ui/utils/newline-strategies.ts
@@ -10,12 +10,48 @@ export function getEnqueueShortcutLabel(platform: NodeJS.Platform | string = pro
   return platform === "darwin" ? "cmd+shift+enter" : "ctrl+shift+enter";
 }
 
+/**
+ * Detect Ctrl+Shift+Enter (or Cmd+Shift+Enter on macOS) from a raw CSI-u or
+ * modifyOtherKeys escape sequence. This is a fallback for cases where the
+ * terminal sends an enhanced sequence but the parsed key event doesn't
+ * correctly reflect the modifier state.
+ */
+function isEnqueueFromRawSequence(raw: string, platform: string): boolean {
+  // CSI-u: \x1b[13;Mu or \x1b[10;Mu (Enter/Linefeed codepoint with modifiers)
+  const csiUMatch = raw.match(/^\x1b\[(?:13|10);(\d+)(?::\d+)*u$/);
+  if (csiUMatch) {
+    const mods = parseInt(csiUMatch[1]!, 10) - 1;
+    const hasShift = (mods & 1) !== 0;
+    const hasCtrl = (mods & 4) !== 0;
+    const hasMeta = (mods & 8) !== 0;
+    if (platform === "darwin") return hasShift && hasMeta && !hasCtrl;
+    return hasShift && hasCtrl && !hasMeta;
+  }
+  // modifyOtherKeys: \x1b[27;M;13~ or \x1b[27;M;10~
+  const modMatch = raw.match(/^\x1b\[27;(\d+);(?:13|10)~$/);
+  if (modMatch) {
+    const mods = parseInt(modMatch[1]!, 10) - 1;
+    const hasShift = (mods & 1) !== 0;
+    const hasCtrl = (mods & 4) !== 0;
+    const hasMeta = (mods & 8) !== 0;
+    if (platform === "darwin") return hasShift && hasMeta && !hasCtrl;
+    return hasShift && hasCtrl && !hasMeta;
+  }
+  return false;
+}
+
 export function shouldEnqueueMessageFromKeyEvent(
   event: NewlineKeyEventLike,
   platform: NodeJS.Platform | string = process.platform,
 ): boolean {
   const isEnterKey = event.name === "return" || event.name === "linefeed";
   if (!isEnterKey || !event.shift) {
+    // Fallback: check raw escape sequence for Ctrl+Shift+Enter when parsed
+    // modifiers are missing (e.g. terminal sends CSI-u but parser doesn't
+    // set shift/ctrl on the event object).
+    if (event.raw && isEnqueueFromRawSequence(event.raw, platform)) {
+      return true;
+    }
     return false;
   }
 
@@ -26,7 +62,28 @@ export function shouldEnqueueMessageFromKeyEvent(
   return Boolean(event.ctrl) && !event.meta;
 }
 
+/**
+ * Returns true when the key event is a bare linefeed (`\n`) with no modifier
+ * flags — the ambiguous encoding produced by non-Kitty terminals for both
+ * Ctrl+J and Ctrl+Shift+Enter. Callers can use this to suppress the event
+ * in the global hook so it doesn't reach the textarea's linefeed→newline
+ * binding and cause unwanted newline insertion on Ctrl+Shift+Enter.
+ */
+export function isBareLinefeedEvent(event: NewlineKeyEventLike): boolean {
+  return (
+    event.name === "linefeed"
+    && !event.shift
+    && !event.ctrl
+    && !event.meta
+    && event.raw === "\n"
+  );
+}
+
 export function shouldInsertNewlineFromKeyEvent(event: NewlineKeyEventLike): boolean {
+  // Never treat the enqueue shortcut (ctrl+shift+enter / cmd+shift+enter) as a newline
+  if (shouldEnqueueMessageFromKeyEvent(event)) {
+    return false;
+  }
   return (
     ((event.name === "return" || event.name === "linefeed") && (event.shift || event.meta)) ||
     (event.name === "linefeed" && !event.ctrl && !event.shift && !event.meta) ||
@@ -44,6 +101,41 @@ export function shouldInsertNewlineFromKeyEvent(event: NewlineKeyEventLike): boo
   );
 }
 
+/**
+ * Terminal-specific fallback newline detection for use in the global key handler.
+ *
+ * Standard shift+enter / meta+enter / Ctrl+J newlines are handled by the
+ * OpenTUI textarea's `keyBindings` prop (see `textareaKeyBindings` in chat.tsx).
+ * This function only matches escape-sequence-based edge cases that can't be
+ * expressed as simple keybindings — e.g. Kitty-protocol CSI-u sequences or
+ * modifyOtherKeys-style raw codes where the parsed key name / modifiers don't
+ * accurately reflect the original Shift+Enter press.
+ */
+export function shouldInsertNewlineFallbackFromKeyEvent(event: NewlineKeyEventLike): boolean {
+  if (shouldEnqueueMessageFromKeyEvent(event)) {
+    return false;
+  }
+
+  return (
+    // CSI-u escape sequence (Kitty protocol): raw ends with "u" and starts
+    // with ESC[13 or ESC[10 (Enter / Linefeed codepoints) with a modifier.
+    (event.name !== "return"
+      && event.name !== "linefeed"
+      && event.raw?.endsWith("u")
+      && /^\x1b\[(?:13|10)/.test(event.raw)
+      && event.raw.includes(";")) ||
+    // modifyOtherKeys-style shifted return: event.name is "return" but the
+    // shift flag isn't set; instead the raw sequence contains ";2" (shift
+    // modifier) and differs from a plain "\r" / "\n".
+    (event.name === "return"
+      && !event.shift
+      && event.raw != null
+      && event.raw !== "\r"
+      && event.raw !== "\n"
+      && event.raw.includes(";2"))
+  );
+}
+
 export function shouldApplyBackslashLineContinuation(value: string, kittyKeyboardDetected: boolean): boolean {
   return !kittyKeyboardDetected && value.endsWith("\\");
 }
diff --git a/src/ui/utils/shift-enter-regression-e2e.test.ts b/src/ui/utils/shift-enter-regression-e2e.test.ts
index 072cc9ce5c..ca5499ad41 100644
--- a/src/ui/utils/shift-enter-regression-e2e.test.ts
+++ b/src/ui/utils/shift-enter-regression-e2e.test.ts
@@ -4,6 +4,7 @@ import { getNextKittyKeyboardDetectionState } from "./kitty-keyboard-detection.t
 import {
   shouldApplyBackslashLineContinuation,
   shouldEnqueueMessageFromKeyEvent,
+  shouldInsertNewlineFallbackFromKeyEvent,
   shouldInsertNewlineFromKeyEvent,
   type NewlineKeyEventLike,
 } from "./newline-strategies.ts";
@@ -54,7 +55,7 @@ function createInputHarness(options: InputHarnessOptions = {}): InputHarness {
       return;
     }
 
-    if (state.isStreaming && shouldEnqueueMessageFromKeyEvent(event, state.platform)) {
+    if (shouldEnqueueMessageFromKeyEvent(event, state.platform)) {
       const trimmed = state.value.trim();
       if (trimmed) {
         state.enqueued.push(trimmed);
@@ -63,6 +64,15 @@ function createInputHarness(options: InputHarnessOptions = {}): InputHarness {
       return;
     }
 
+    // Terminal-specific fallback newline detection (global hook tier).
+    if (shouldInsertNewlineFallbackFromKeyEvent(event)) {
+      state.value += "\n";
+      return;
+    }
+
+    // Standard newline detection (OpenTUI textarea keyBindings tier).
+    // In the real app, shift+enter / meta+enter / Ctrl+J are handled by the
+    // textarea's keyBindings prop rather than the global hook.
     if (shouldInsertNewlineFromKeyEvent(event)) {
       state.value += "\n";
       return;
@@ -234,17 +244,17 @@ describe("Shift+Enter repeated newline regression E2E", () => {
     expect(input.value).toBe("");
   });
 
-  test("Cmd/Ctrl+Shift+Enter keeps newline behavior when not streaming", () => {
+  test("Cmd/Ctrl+Shift+Enter enqueues even when not streaming", () => {
     const macInput = createInputHarness({ platform: "darwin", isStreaming: false });
     macInput.typeText("mac line");
     macInput.pressKey({ name: "return", shift: true, meta: true, raw: "\r" });
-    expect(macInput.enqueued).toEqual([]);
-    expect(macInput.value).toBe("mac line\n");
+    expect(macInput.enqueued).toEqual(["mac line"]);
+    expect(macInput.value).toBe("");
 
     const linuxInput = createInputHarness({ platform: "linux", isStreaming: false });
     linuxInput.typeText("linux line");
     linuxInput.pressKey({ name: "return", shift: true, ctrl: true, raw: "\r" });
-    expect(linuxInput.enqueued).toEqual([]);
-    expect(linuxInput.value).toBe("linux line\n");
+    expect(linuxInput.enqueued).toEqual(["linux line"]);
+    expect(linuxInput.value).toBe("");
   });
 });
diff --git a/src/ui/utils/stream-continuation.test.ts b/src/ui/utils/stream-continuation.test.ts
index 0a189dedc2..b6e7506219 100644
--- a/src/ui/utils/stream-continuation.test.ts
+++ b/src/ui/utils/stream-continuation.test.ts
@@ -1,17 +1,25 @@
-import { describe, expect, test } from "bun:test";
+import { beforeEach, describe, expect, test } from "bun:test";
 import {
   createStartedStreamControlState,
   createStoppedStreamControlState,
   dispatchNextQueuedMessage,
   interruptRunningToolCalls,
   isAskQuestionToolName,
-  invalidateActiveStreamGeneration,
-  isCurrentStreamCallback,
+  shouldContinueParentSessionLoop,
+  shouldTrackToolAsBlocking,
   shouldDispatchQueuedMessage,
   shouldDeferComposerSubmit,
 } from "./stream-continuation.ts";
+import {
+  getRuntimeParityMetricsSnapshot,
+  resetRuntimeParityMetrics,
+} from "../../workflows/runtime-parity-observability.ts";
 
 describe("stream continuation helpers", () => {
+  beforeEach(() => {
+    resetRuntimeParityMetrics();
+  });
+
   test("dispatchNextQueuedMessage dispatches next queued item once", () => {
     const queue = ["first", "second"];
     const dispatched: string[] = [];
@@ -52,16 +60,20 @@ describe("stream continuation helpers", () => {
 
     expect(dispatchedAny).toBe(false);
     expect(dispatched).toEqual([]);
+
+    const metrics = getRuntimeParityMetricsSnapshot();
+    expect(metrics.counters["workflow.runtime.parity.queue_dispatch_total{mode=unguarded,result=no-op}"]).toBe(1);
   });
 
-  test("interrupt invalidation advances generation and makes old callback stale", () => {
-    const currentGeneration = 7;
-    const interruptedGeneration = invalidateActiveStreamGeneration(currentGeneration);
+  test("dispatchNextQueuedMessage fails on invalid delay invariants", () => {
+    expect(() => dispatchNextQueuedMessage(
+      () => "item",
+      () => {},
+      { delayMs: -1 },
+    )).toThrow("non-negative finite delay");
 
-    expect(interruptedGeneration).toBe(8);
-    expect(interruptedGeneration).not.toBe(currentGeneration);
-    expect(isCurrentStreamCallback(interruptedGeneration, currentGeneration)).toBe(false);
-    expect(isCurrentStreamCallback(interruptedGeneration, interruptedGeneration)).toBe(true);
+    const metrics = getRuntimeParityMetricsSnapshot();
+    expect(metrics.counters["workflow.runtime.parity.queue_dispatch_invariant_failures_total{reason=invalid_delay}"]).toBe(1);
   });
 
   test("guarded dispatch does not dequeue when streaming resumed", () => {
@@ -273,6 +285,19 @@ describe("stream continuation helpers", () => {
     expect(isAskQuestionToolName("read_page")).toBe(false);
   });
 
+  test("shouldTrackToolAsBlocking skips skill lifecycle tools", () => {
+    expect(shouldTrackToolAsBlocking("Skill")).toBe(false);
+    expect(shouldTrackToolAsBlocking("skill")).toBe(false);
+    expect(shouldTrackToolAsBlocking("deepwiki/skill")).toBe(false);
+    expect(shouldTrackToolAsBlocking("mcp__core__skill")).toBe(false);
+  });
+
+  test("shouldTrackToolAsBlocking keeps normal tools as blocking", () => {
+    expect(shouldTrackToolAsBlocking("Bash")).toBe(true);
+    expect(shouldTrackToolAsBlocking("Read")).toBe(true);
+    expect(shouldTrackToolAsBlocking("ask_question")).toBe(true);
+  });
+
   test("shouldDeferComposerSubmit keeps composer text during ask_question", () => {
     expect(shouldDeferComposerSubmit({
       isStreaming: true,
@@ -437,4 +462,54 @@ describe("stream continuation helpers", () => {
     expect(dispatched).toEqual(["queued-message"]);
     expect(queue).toEqual([]);
   });
+
+  test("parent loop continues on tool-calls finish reason", () => {
+    const signal = shouldContinueParentSessionLoop({
+      finishReason: "tool-calls",
+      hasActiveForegroundAgents: false,
+      hasRunningBlockingTool: false,
+      hasPendingTaskContract: false,
+    });
+
+    expect(signal).toEqual({
+      shouldContinue: true,
+      reason: "finish-reason",
+    });
+
+    const metrics = getRuntimeParityMetricsSnapshot();
+    expect(metrics.counters["workflow.runtime.parity.loop_decision_total{decision=continue,finishReason=tool-calls,reason=finish-reason}"]).toBe(1);
+  });
+
+  test("parent loop continues while pending work remains", () => {
+    const signal = shouldContinueParentSessionLoop({
+      finishReason: "stop",
+      hasActiveForegroundAgents: false,
+      hasRunningBlockingTool: true,
+      hasPendingTaskContract: false,
+    });
+
+    expect(signal).toEqual({
+      shouldContinue: true,
+      reason: "pending-work",
+    });
+  });
+
+  test("parent loop terminates on terminal finish reason with no pending work", () => {
+    const signal = shouldContinueParentSessionLoop({
+      finishReason: "stop",
+      hasActiveForegroundAgents: false,
+      hasRunningBlockingTool: false,
+      hasPendingTaskContract: false,
+    });
+
+    expect(signal).toEqual({
+      shouldContinue: false,
+      reason: "terminal",
+    });
+
+    const metrics = getRuntimeParityMetricsSnapshot();
+    expect(metrics.counters["workflow.runtime.parity.loop_decision_total{decision=stop,finishReason=stop,reason=terminal}"]).toBe(1);
+    expect(metrics.gauges["workflow.runtime.parity.loop_pending_task_contract{finishReason=stop}"]).toBe(0);
+    expect(metrics.histograms["workflow.runtime.parity.loop_pending_flags{finishReason=stop}"]).toEqual([0]);
+  });
 });
diff --git a/src/ui/utils/stream-continuation.ts b/src/ui/utils/stream-continuation.ts
index b6312b6c3f..9d618b02a7 100644
--- a/src/ui/utils/stream-continuation.ts
+++ b/src/ui/utils/stream-continuation.ts
@@ -1,3 +1,31 @@
+import type { Part, ToolPart } from "../parts/types.ts";
+import {
+  incrementRuntimeParityCounter,
+  observeRuntimeParityHistogram,
+  runtimeParityDebug,
+  setRuntimeParityGauge,
+} from "../../workflows/runtime-parity-observability.ts";
+
+export type SessionLoopFinishReason =
+  | "tool-calls"
+  | "stop"
+  | "max-tokens"
+  | "max-turns"
+  | "error"
+  | "unknown";
+
+export interface SessionLoopContinuationInput {
+  finishReason?: SessionLoopFinishReason;
+  hasActiveForegroundAgents: boolean;
+  hasRunningBlockingTool: boolean;
+  hasPendingTaskContract: boolean;
+}
+
+export interface SessionLoopContinuationSignal {
+  shouldContinue: boolean;
+  reason: "finish-reason" | "pending-work" | "terminal";
+}
+
 export interface QueueDispatchOptions {
   delayMs?: number;
   schedule?: (callback: () => void, delayMs: number) => void;
@@ -37,16 +65,83 @@ export interface QueueResumeGuardState {
 const DEFAULT_QUEUE_DISPATCH_DELAY_MS = 50;
 
 const ASK_QUESTION_TOOL_SUFFIX = "ask_question";
+const NON_BLOCKING_TOOL_SUFFIX = "skill";
 
-export function invalidateActiveStreamGeneration(currentGeneration: number): number {
-  return currentGeneration + 1;
-}
+const CONTINUE_FINISH_REASONS = new Set<SessionLoopFinishReason>([
+  "tool-calls",
+  "unknown",
+]);
 
-export function isCurrentStreamCallback(
-  activeGeneration: number,
-  callbackGeneration: number,
-): boolean {
-  return activeGeneration === callbackGeneration;
+export function shouldContinueParentSessionLoop(
+  input: SessionLoopContinuationInput,
+): SessionLoopContinuationSignal {
+  observeRuntimeParityHistogram(
+    "workflow.runtime.parity.loop_pending_flags",
+    Number(input.hasActiveForegroundAgents) + Number(input.hasRunningBlockingTool) + Number(input.hasPendingTaskContract),
+    { finishReason: input.finishReason ?? "unset" },
+  );
+  setRuntimeParityGauge(
+    "workflow.runtime.parity.loop_pending_task_contract",
+    input.hasPendingTaskContract ? 1 : 0,
+    { finishReason: input.finishReason ?? "unset" },
+  );
+
+  if (
+    input.hasActiveForegroundAgents
+    || input.hasRunningBlockingTool
+    || input.hasPendingTaskContract
+  ) {
+    incrementRuntimeParityCounter("workflow.runtime.parity.loop_decision_total", {
+      decision: "continue",
+      reason: "pending-work",
+      finishReason: input.finishReason ?? "unset",
+    });
+    runtimeParityDebug("loop_decision", {
+      decision: "continue",
+      reason: "pending-work",
+      finishReason: input.finishReason ?? "unset",
+      hasActiveForegroundAgents: input.hasActiveForegroundAgents,
+      hasRunningBlockingTool: input.hasRunningBlockingTool,
+      hasPendingTaskContract: input.hasPendingTaskContract,
+    });
+    return {
+      shouldContinue: true,
+      reason: "pending-work",
+    };
+  }
+
+  if (input.finishReason && CONTINUE_FINISH_REASONS.has(input.finishReason)) {
+    incrementRuntimeParityCounter("workflow.runtime.parity.loop_decision_total", {
+      decision: "continue",
+      reason: "finish-reason",
+      finishReason: input.finishReason,
+    });
+    runtimeParityDebug("loop_decision", {
+      decision: "continue",
+      reason: "finish-reason",
+      finishReason: input.finishReason,
+    });
+    return {
+      shouldContinue: true,
+      reason: "finish-reason",
+    };
+  }
+
+  incrementRuntimeParityCounter("workflow.runtime.parity.loop_decision_total", {
+    decision: "stop",
+    reason: "terminal",
+    finishReason: input.finishReason ?? "unset",
+  });
+  runtimeParityDebug("loop_decision", {
+    decision: "stop",
+    reason: "terminal",
+    finishReason: input.finishReason ?? "unset",
+  });
+
+  return {
+    shouldContinue: false,
+    reason: "terminal",
+  };
 }
 
 export function createStoppedStreamControlState(
@@ -92,6 +187,25 @@ export function interruptRunningToolCalls<T extends { status: string }>(
   );
 }
 
+/**
+ * Freeze running tool parts by transitioning them to "interrupted" with
+ * their elapsed duration captured, so tool timers stop on Ctrl+C / ESC.
+ */
+export function interruptRunningToolParts(parts?: readonly Part[]): Part[] | undefined {
+  if (!parts) return undefined;
+  return parts.map((part) => {
+    if (part.type === "tool") {
+      const toolPart = part as ToolPart;
+      if (toolPart.state.status === "running") {
+        const startedAtMs = new Date(toolPart.state.startedAt).getTime();
+        const durationMs = Number.isFinite(startedAtMs) ? Math.max(0, Date.now() - startedAtMs) : undefined;
+        return { ...toolPart, state: { status: "interrupted" as const, durationMs } };
+      }
+    }
+    return part;
+  });
+}
+
 export function isAskQuestionToolName(toolName: string): boolean {
   const normalized = toolName.trim().toLowerCase();
   return normalized === ASK_QUESTION_TOOL_SUFFIX
@@ -99,6 +213,22 @@ export function isAskQuestionToolName(toolName: string): boolean {
     || normalized.endsWith(`__${ASK_QUESTION_TOOL_SUFFIX}`);
 }
 
+/**
+ * Some lightweight lifecycle tools (for example Skill loaders) may emit start
+ * events without a matching complete event, depending on SDK/provider behavior.
+ * They should not block stream finalization.
+ */
+export function shouldTrackToolAsBlocking(toolName: string): boolean {
+  const normalized = toolName.trim().toLowerCase();
+  if (normalized.length === 0) {
+    return true;
+  }
+
+  return normalized !== NON_BLOCKING_TOOL_SUFFIX
+    && !normalized.endsWith(`/${NON_BLOCKING_TOOL_SUFFIX}`)
+    && !normalized.endsWith(`__${NON_BLOCKING_TOOL_SUFFIX}`);
+}
+
 export function shouldDeferComposerSubmit(state: ComposerSubmitGuardState): boolean {
   return state.isStreaming && state.runningAskQuestionToolCount > 0;
 }
@@ -113,6 +243,12 @@ export function dispatchNextQueuedMessage<T>(
   options?: QueueDispatchOptions,
 ): boolean {
   const delayMs = options?.delayMs ?? DEFAULT_QUEUE_DISPATCH_DELAY_MS;
+  if (!Number.isFinite(delayMs) || delayMs < 0) {
+    incrementRuntimeParityCounter("workflow.runtime.parity.queue_dispatch_invariant_failures_total", {
+      reason: "invalid_delay",
+    });
+    throw new Error(`dispatchNextQueuedMessage requires non-negative finite delay, received ${delayMs}`);
+  }
   const schedule = options?.schedule ?? ((callback: () => void, delay: number) => {
     setTimeout(callback, delay);
   });
@@ -121,6 +257,10 @@ export function dispatchNextQueuedMessage<T>(
   if (!options?.shouldDispatch) {
     const nextMessage = dequeue();
     if (!nextMessage) {
+      incrementRuntimeParityCounter("workflow.runtime.parity.queue_dispatch_total", {
+        result: "no-op",
+        mode: "unguarded",
+      });
       return false;
     }
 
@@ -128,19 +268,47 @@ export function dispatchNextQueuedMessage<T>(
       dispatch(nextMessage);
     }, delayMs);
 
+    incrementRuntimeParityCounter("workflow.runtime.parity.queue_dispatch_total", {
+      result: "scheduled",
+      mode: "unguarded",
+    });
+    runtimeParityDebug("queue_dispatch", {
+      mode: "unguarded",
+      delayMs,
+      scheduled: true,
+    });
+
     return true;
   }
 
   schedule(() => {
     if (!options.shouldDispatch?.()) {
+      incrementRuntimeParityCounter("workflow.runtime.parity.queue_dispatch_total", {
+        result: "guard_blocked",
+        mode: "guarded",
+      });
       return;
     }
     const nextMessage = dequeue();
     if (!nextMessage) {
+      incrementRuntimeParityCounter("workflow.runtime.parity.queue_dispatch_total", {
+        result: "empty_queue",
+        mode: "guarded",
+      });
       return;
     }
+    incrementRuntimeParityCounter("workflow.runtime.parity.queue_dispatch_total", {
+      result: "dispatched",
+      mode: "guarded",
+    });
     dispatch(nextMessage);
   }, delayMs);
 
+  runtimeParityDebug("queue_dispatch", {
+    mode: "guarded",
+    delayMs,
+    scheduled: true,
+  });
+
   return true;
 }
diff --git a/src/ui/utils/task-list-lifecycle.test.ts b/src/ui/utils/task-list-lifecycle.test.ts
index dab68a4368..bb7eac1450 100644
--- a/src/ui/utils/task-list-lifecycle.test.ts
+++ b/src/ui/utils/task-list-lifecycle.test.ts
@@ -1,7 +1,7 @@
 import { describe, expect, test } from "bun:test";
 
 import type { TaskItem } from "../components/task-list-indicator.tsx";
-import { preferTerminalTaskItems } from "./ralph-task-state.ts";
+import { preferTerminalTaskItems } from "./workflow-task-state.ts";
 import { shouldAutoClearTaskPanel } from "./task-list-lifecycle.ts";
 
 function task(status: TaskItem["status"]): TaskItem {
diff --git a/src/ui/utils/task-status.test.ts b/src/ui/utils/task-status.test.ts
index 2a6730a018..45949c97ba 100644
--- a/src/ui/utils/task-status.test.ts
+++ b/src/ui/utils/task-status.test.ts
@@ -7,6 +7,7 @@ import {
   normalizeTaskStatus,
   normalizeTodoItem,
   normalizeTodoItems,
+  reconcileTodoWriteItems,
   type NormalizedTaskItem,
 } from "./task-status.ts";
 
@@ -110,6 +111,46 @@ describe("task item normalization", () => {
       "pending",
     ]);
   });
+
+  test("preserves task result envelopes for persistence round-trip", () => {
+    const normalized = normalizeTodoItems([
+      {
+        id: "#3",
+        content: "Persist worker output",
+        status: "completed",
+        activeForm: "Persisting worker output",
+        taskResult: {
+          task_id: "#3",
+          tool_name: "task",
+          title: "Persist worker output",
+          metadata: {
+            sessionId: "session-3",
+            providerBindings: {
+              subagent_id: "worker-3",
+            },
+          },
+          status: "completed",
+          output_text: "done",
+          envelope_text: "task_id: #3",
+        },
+      },
+    ]);
+
+    expect(normalized[0]?.taskResult).toEqual({
+      task_id: "#3",
+      tool_name: "task",
+      title: "Persist worker output",
+      metadata: {
+        sessionId: "session-3",
+        providerBindings: {
+          subagent_id: "worker-3",
+        },
+      },
+      status: "completed",
+      output_text: "done",
+      envelope_text: "task_id: #3",
+    });
+  });
 });
 
 describe("mergeBlockedBy", () => {
@@ -181,6 +222,19 @@ describe("mergeBlockedBy", () => {
     expect(merged[0]!.blockedBy).toEqual(["#2"]);
   });
 
+  test("matches IDs with and without leading #", () => {
+    const previous: NormalizedTaskItem[] = [
+      { id: "#1", content: "A", status: "pending", blockedBy: ["#0"] },
+    ];
+
+    const updated: NormalizedTaskItem[] = [
+      { id: "1", content: "A", status: "in_progress" },
+    ];
+
+    const merged = mergeBlockedBy(updated, previous);
+    expect(merged[0]!.blockedBy).toEqual(["#0"]);
+  });
+
   test("restores missing IDs by matching task content", () => {
     const previous: NormalizedTaskItem[] = [
       { id: "#1", content: "Implement login flow", status: "pending", blockedBy: ["#0"] },
@@ -223,3 +277,89 @@ describe("mergeBlockedBy", () => {
     expect(merged[0]!.blockedBy).toBeUndefined();
   });
 });
+
+describe("reconcileTodoWriteItems", () => {
+  test("keeps todo updates topologically sorted by blockedBy", () => {
+    const previous = [
+      { id: "#1", content: "Plan", status: "completed" as const, activeForm: "Planning" },
+      {
+        id: "#2",
+        content: "Implement",
+        status: "pending" as const,
+        blockedBy: ["#1"],
+        activeForm: "Implementing",
+      },
+      {
+        id: "#3",
+        content: "Test",
+        status: "pending" as const,
+        blockedBy: ["#2"],
+        activeForm: "Testing",
+      },
+    ];
+
+    const incoming = [
+      { id: "#3", content: "Test", status: "pending", activeForm: "Testing" },
+      { id: "#1", content: "Plan", status: "completed", activeForm: "Planning" },
+      { id: "#2", content: "Implement", status: "in_progress", activeForm: "Implementing" },
+    ];
+
+    const reconciled = reconcileTodoWriteItems(incoming, previous);
+
+    expect(reconciled.map((item) => item.id)).toEqual(["#1", "#2", "#3"]);
+    expect(reconciled[1]!.status).toBe("in_progress");
+    expect(reconciled[1]!.blockedBy).toEqual(["#1"]);
+    expect(reconciled[2]!.blockedBy).toEqual(["#2"]);
+  });
+
+  test("restores missing ids/blockedBy before sorting follow-up updates", () => {
+    const previous = [
+      { id: "#1", content: "Plan", status: "completed" as const, activeForm: "Planning" },
+      {
+        id: "#2",
+        content: "Implement",
+        status: "in_progress" as const,
+        blockedBy: ["#1"],
+        activeForm: "Implementing",
+      },
+      {
+        id: "#3",
+        content: "Test",
+        status: "pending" as const,
+        blockedBy: ["#2"],
+        activeForm: "Testing",
+      },
+    ];
+
+    const incomingWithoutIds = [
+      { content: "Test", status: "pending", activeForm: "Testing" },
+      { content: "Implement", status: "completed", activeForm: "Implementing" },
+      { content: "Plan", status: "completed", activeForm: "Planning" },
+    ];
+
+    const reconciled = reconcileTodoWriteItems(incomingWithoutIds, previous);
+
+    expect(reconciled.map((item) => item.id)).toEqual(["#1", "#2", "#3"]);
+    expect(reconciled[1]!.blockedBy).toEqual(["#1"]);
+    expect(reconciled[2]!.blockedBy).toEqual(["#2"]);
+  });
+
+  test("keeps previous sibling order when blockedBy rank is equal", () => {
+    const previous = [
+      { id: "#1", content: "Setup", status: "completed" as const, activeForm: "Setting up" },
+      { id: "#2", content: "Lint", status: "pending" as const, activeForm: "Linting" },
+      { id: "#3", content: "Test", status: "pending" as const, activeForm: "Testing" },
+    ];
+
+    const incomingShuffled = [
+      { id: "#3", content: "Test", status: "in_progress", activeForm: "Testing" },
+      { id: "#1", content: "Setup", status: "completed", activeForm: "Setting up" },
+      { id: "#2", content: "Lint", status: "pending", activeForm: "Linting" },
+    ];
+
+    const reconciled = reconcileTodoWriteItems(incomingShuffled, previous);
+
+    expect(reconciled.map((item) => item.id)).toEqual(["#1", "#2", "#3"]);
+    expect(reconciled[2]!.status).toBe("in_progress");
+  });
+});
diff --git a/src/ui/utils/task-status.ts b/src/ui/utils/task-status.ts
index a5e55f13ac..a09ac34a9d 100644
--- a/src/ui/utils/task-status.ts
+++ b/src/ui/utils/task-status.ts
@@ -1,3 +1,6 @@
+import { sortTasksTopologically } from "../components/task-order.ts";
+import type { WorkflowRuntimeTaskResultEnvelope } from "../../workflows/runtime-contracts.ts";
+
 /**
  * Task status normalization helpers.
  *
@@ -39,6 +42,11 @@ export interface NormalizedTaskItem {
   content: string;
   status: TaskStatus;
   blockedBy?: string[];
+  identity?: {
+    canonicalId?: string;
+    providerBindings?: Record<string, string[]>;
+  };
+  taskResult?: WorkflowRuntimeTaskResultEnvelope;
 }
 
 export interface NormalizedTodoItem extends NormalizedTaskItem {
@@ -86,6 +94,179 @@ function normalizeBlockedBy(value: unknown): string[] | undefined {
   return normalized.length > 0 ? normalized : undefined;
 }
 
+function normalizeTaskIdentity(value: unknown): NormalizedTaskItem["identity"] {
+  if (typeof value !== "object" || value === null) {
+    return undefined;
+  }
+
+  const record = value as Record<string, unknown>;
+  const canonicalId = typeof record.canonicalId === "string" && record.canonicalId.length > 0
+    ? record.canonicalId
+    : undefined;
+
+  let providerBindings: Record<string, string[]> | undefined;
+  if (typeof record.providerBindings === "object" && record.providerBindings !== null) {
+    providerBindings = {};
+    for (const [provider, ids] of Object.entries(record.providerBindings as Record<string, unknown>)) {
+      if (!Array.isArray(ids) || provider.length === 0) {
+        continue;
+      }
+
+      const normalizedIds = Array.from(new Set(
+        ids
+          .filter((id) => id !== null && id !== undefined)
+          .map((id) => String(id))
+          .filter((id) => id.length > 0),
+      ));
+
+      if (normalizedIds.length > 0) {
+        providerBindings[provider] = normalizedIds;
+      }
+    }
+
+    if (Object.keys(providerBindings).length === 0) {
+      providerBindings = undefined;
+    }
+  }
+
+  if (!canonicalId && !providerBindings) {
+    return undefined;
+  }
+
+  return {
+    canonicalId,
+    providerBindings,
+  };
+}
+
+function normalizeTaskResultEnvelope(value: unknown): WorkflowRuntimeTaskResultEnvelope | undefined {
+  if (typeof value !== "object" || value === null) {
+    return undefined;
+  }
+
+  const record = value as Record<string, unknown>;
+  const taskId = typeof record.task_id === "string" && record.task_id.length > 0
+    ? record.task_id
+    : undefined;
+  if (!taskId) {
+    return undefined;
+  }
+
+  const toolName = typeof record.tool_name === "string" && record.tool_name.length > 0
+    ? record.tool_name
+    : "task";
+  const title = typeof record.title === "string" ? record.title : "";
+  const outputText = typeof record.output_text === "string" ? record.output_text : "";
+  const status: WorkflowRuntimeTaskResultEnvelope["status"] = record.status === "error" ? "error" : "completed";
+
+  let metadata: WorkflowRuntimeTaskResultEnvelope["metadata"];
+  if (typeof record.metadata === "object" && record.metadata !== null) {
+    const metadataRecord = record.metadata as Record<string, unknown>;
+    const sessionId = typeof metadataRecord.sessionId === "string" && metadataRecord.sessionId.length > 0
+      ? metadataRecord.sessionId
+      : undefined;
+
+    let providerBindings: Record<string, string> | undefined;
+    if (typeof metadataRecord.providerBindings === "object" && metadataRecord.providerBindings !== null) {
+      providerBindings = {};
+      for (const [provider, providerId] of Object.entries(metadataRecord.providerBindings as Record<string, unknown>)) {
+        const normalizedProvider = provider.trim();
+        const normalizedProviderId = typeof providerId === "string" ? providerId.trim() : String(providerId ?? "").trim();
+        if (normalizedProvider.length === 0 || normalizedProviderId.length === 0) {
+          continue;
+        }
+        providerBindings[normalizedProvider] = normalizedProviderId;
+      }
+      if (Object.keys(providerBindings).length === 0) {
+        providerBindings = undefined;
+      }
+    }
+
+    if (sessionId || providerBindings) {
+      metadata = {
+        ...(sessionId ? { sessionId } : {}),
+        ...(providerBindings ? { providerBindings } : {}),
+      };
+    }
+  }
+
+  const outputStructured = typeof record.output_structured === "object"
+    && record.output_structured !== null
+    && !Array.isArray(record.output_structured)
+    ? record.output_structured as Record<string, unknown>
+    : undefined;
+
+  return {
+    task_id: taskId,
+    tool_name: toolName,
+    title,
+    ...(metadata ? { metadata } : {}),
+    status,
+    output_text: outputText,
+    ...(outputStructured ? { output_structured: outputStructured } : {}),
+    ...(typeof record.error === "string" && record.error.length > 0 ? { error: record.error } : {}),
+    ...(typeof record.envelope_text === "string" && record.envelope_text.length > 0
+      ? { envelope_text: record.envelope_text }
+      : {}),
+  };
+}
+
+function normalizeStableTaskContent(content: string): string {
+  return content.trim().toLowerCase().replace(/\s+/g, " ");
+}
+
+function normalizeDependencyTaskId(id: string | undefined): string | undefined {
+  if (typeof id !== "string") return undefined;
+  const normalized = id.trim().toLowerCase().replace(/^#/, "");
+  return normalized.length > 0 ? normalized : undefined;
+}
+
+function getStableTaskKey(task: { id?: string; content: string }): string {
+  const normalizedId = task.id?.trim().toLowerCase();
+  if (normalizedId) {
+    return `id:${normalizedId}`;
+  }
+
+  const normalizedContent = normalizeStableTaskContent(task.content);
+  if (normalizedContent.length > 0) {
+    return `content:${normalizedContent}`;
+  }
+
+  return "";
+}
+
+function stabilizeByPreviousOrder<T extends NormalizedTaskItem>(
+  tasks: readonly T[],
+  previous: readonly NormalizedTaskItem[],
+): T[] {
+  if (tasks.length <= 1 || previous.length === 0) {
+    return [...tasks];
+  }
+
+  const previousRank = new Map<string, number>();
+  for (let index = 0; index < previous.length; index++) {
+    const task = previous[index];
+    if (!task) continue;
+    const key = getStableTaskKey(task);
+    if (!key || previousRank.has(key)) continue;
+    previousRank.set(key, index);
+  }
+
+  if (previousRank.size === 0) {
+    return [...tasks];
+  }
+
+  return [...tasks].sort((left, right) => {
+    const leftRank = previousRank.get(getStableTaskKey(left));
+    const rightRank = previousRank.get(getStableTaskKey(right));
+
+    if (leftRank === undefined && rightRank === undefined) return 0;
+    if (leftRank === undefined) return 1;
+    if (rightRank === undefined) return -1;
+    return leftRank - rightRank;
+  });
+}
+
 export function isTaskStatus(status: unknown): status is TaskStatus {
   if (typeof status !== "string") {
     return false;
@@ -112,11 +293,15 @@ export function isTodoWriteToolName(name: unknown): boolean {
 
 export function normalizeTaskItem(input: unknown): NormalizedTaskItem {
   const record = asRecord(input);
+  const identity = normalizeTaskIdentity(record.identity);
+  const taskResult = normalizeTaskResultEnvelope(record.taskResult ?? record.task_result);
   return {
     id: normalizeId(record.id),
     content: String(record.content ?? ""),
     status: normalizeTaskStatus(record.status),
     blockedBy: normalizeBlockedBy(record.blockedBy),
+    ...(identity ? { identity } : {}),
+    ...(taskResult ? { taskResult } : {}),
   };
 }
 
@@ -166,7 +351,7 @@ export function mergeBlockedBy<T extends NormalizedTaskItem>(
   const prevBlockedById = new Map<string, string[]>();
   const prevByContent = new Map<string, NormalizedTaskItem>();
   for (const task of previous) {
-    const id = task.id?.trim().toLowerCase();
+    const id = normalizeDependencyTaskId(task.id);
     if (id && task.blockedBy) {
       prevBlockedById.set(id, task.blockedBy);
     }
@@ -188,7 +373,7 @@ export function mergeBlockedBy<T extends NormalizedTaskItem>(
       : undefined;
 
     const restoredId = hasExplicitId ? task.id : prevByMatchingContent?.id;
-    const normalizedId = restoredId?.trim().toLowerCase();
+    const normalizedId = normalizeDependencyTaskId(restoredId);
 
     const restoredBlockedBy = task.blockedBy
       ?? (normalizedId ? prevBlockedById.get(normalizedId) : undefined)
@@ -205,3 +390,17 @@ export function mergeBlockedBy<T extends NormalizedTaskItem>(
     };
   });
 }
+
+/**
+ * Normalize a TodoWrite payload, restore missing dependency metadata, and
+ * apply a stable dependency-aware order for rendering.
+ */
+export function reconcileTodoWriteItems(
+  incomingTodos: unknown,
+  previous: readonly NormalizedTodoItem[] = [],
+): NormalizedTodoItem[] {
+  const normalized = normalizeTodoItems(incomingTodos);
+  const merged = mergeBlockedBy(normalized, previous);
+  const stabilized = stabilizeByPreviousOrder(merged, previous);
+  return sortTasksTopologically(stabilized);
+}
diff --git a/src/ui/utils/transcript-formatter.test.ts b/src/ui/utils/transcript-formatter.test.ts
index 1a7df30b06..564661db4c 100644
--- a/src/ui/utils/transcript-formatter.test.ts
+++ b/src/ui/utils/transcript-formatter.test.ts
@@ -648,8 +648,6 @@ describe("formatTranscript - Parallel Agents", () => {
     expect(rowLine).toBeDefined();
     expect(rowLine!.type).toBe("agent-row");
     expect(rowLine!.content).toContain("Searching for files");
-    expect(rowLine!.content).toContain("10 tool uses");
-    expect(rowLine!.content).toContain("5s");
   });
 
   test("renders agent-substatus with result text for completed agents", () => {
@@ -688,6 +686,7 @@ describe("formatTranscript - Parallel Agents", () => {
         status: "running",
         startedAt: new Date().toISOString(),
         currentTool: "Bash: Finding files...",
+        toolUses: 3,
       },
     ];
     const msg: ChatMessage = {
@@ -700,10 +699,10 @@ describe("formatTranscript - Parallel Agents", () => {
 
     const lines = formatTranscript({ messages: [msg], isStreaming: false });
 
-    const substatusLine = findFirstLineByType(lines, "agent-substatus");
-    expect(substatusLine).toBeDefined();
-    expect(substatusLine!.type).toBe("agent-substatus");
-    expect(substatusLine!.content).toContain("Bash: Finding files...");
+    const substatusLines = lines.filter(l => l.type === "agent-substatus");
+    expect(substatusLines.length).toBeGreaterThanOrEqual(1);
+    expect(substatusLines[0]!.content).toContain("Explore: (3 tool uses)");
+    expect(substatusLines[1]!.content).toContain("Bash: Finding files...");
   });
 
   test("renders agent-substatus with error message for errored agents", () => {
@@ -733,7 +732,7 @@ describe("formatTranscript - Parallel Agents", () => {
     expect(substatusLine!.content).toContain("File not found");
   });
 
-  test("uses liveParallelAgents during streaming when message has no baked agents", () => {
+  test("does not render live agent trees without baked message parallelAgents", () => {
     const msg: ChatMessage = {
       id: "m1",
       role: "assistant",
@@ -742,20 +741,13 @@ describe("formatTranscript - Parallel Agents", () => {
       streaming: true,
     };
 
-    const liveAgents: ParallelAgent[] = [
-      { id: "a1", name: "Live", task: "Live task", status: "running", startedAt: new Date().toISOString() },
-    ];
-
     const lines = formatTranscript({
       messages: [msg],
       isStreaming: true,
-      liveParallelAgents: liveAgents,
     });
 
     const headerLine = findFirstLineByType(lines, "agent-header");
-    expect(headerLine).toBeDefined();
-    expect(headerLine!.type).toBe("agent-header");
-    expect(headerLine!.content).toContain("Running 1 agent");
+    expect(headerLine).toBeUndefined();
   });
 });
 
@@ -782,7 +774,7 @@ describe("formatTranscript - Streaming Indicators", () => {
     expect(streamingLine).toBeDefined();
     expect(streamingLine!.type).toBe("separator");
     expect(streamingLine!.content).toContain("100 tokens");
-    expect(streamingLine!.content).toContain("thinking 500ms");
+    expect(streamingLine!.content).toContain("thinking 1s");
   });
 
   test("renders streaming separator without thinking label when thinkingMs is 0", () => {
diff --git a/src/ui/utils/transcript-formatter.ts b/src/ui/utils/transcript-formatter.ts
index 2e3ea554af..42aa0e5ed3 100644
--- a/src/ui/utils/transcript-formatter.ts
+++ b/src/ui/utils/transcript-formatter.ts
@@ -42,7 +42,6 @@ export interface TranscriptLine {
 export interface FormatTranscriptOptions {
   messages: ChatMessage[];
   liveThinkingText?: string;
-  liveParallelAgents?: ParallelAgent[];
   streamingMeta?: StreamingMeta | null;
   isStreaming: boolean;
   modelId?: string;
@@ -77,7 +76,7 @@ function line(type: TranscriptLineType, content: string, indent = 0): Transcript
  * - Footer: `──── Showing detailed transcript · ctrl+o to toggle`
  */
 export function formatTranscript(options: FormatTranscriptOptions): TranscriptLine[] {
-  const { messages, liveThinkingText, liveParallelAgents, streamingMeta, isStreaming, modelId } = options;
+  const { messages, liveThinkingText, streamingMeta, isStreaming, modelId } = options;
   const lines: TranscriptLine[] = [];
 
   for (const msg of messages) {
@@ -183,9 +182,7 @@ export function formatTranscript(options: FormatTranscriptOptions): TranscriptLi
       // Parallel agents (baked from completed message or live)
       const agents = msg.parallelAgents && msg.parallelAgents.length > 0
         ? msg.parallelAgents
-        : msg.streaming && liveParallelAgents && liveParallelAgents.length > 0
-          ? liveParallelAgents
-          : null;
+        : null;
 
       if (agents) {
         lines.push(line("blank", ""));
@@ -197,21 +194,26 @@ export function formatTranscript(options: FormatTranscriptOptions): TranscriptLi
         lines.push(line("agent-header", headerText));
 
         for (const agent of agents) {
-          const taskText = truncateText(agent.task, 60);
-          const metricsParts: string[] = [];
-          if (agent.toolUses !== undefined) metricsParts.push(`${agent.toolUses} tool uses`);
-          if (agent.durationMs !== undefined) metricsParts.push(formatDuration(agent.durationMs));
-          const metrics = metricsParts.length > 0 ? ` · ${metricsParts.join(" · ")}` : "";
+          const taskText = truncateText(agent.task || agent.name, 60);
 
           const agentIcon = agent.status === "completed" ? STATUS.active : agent.status === "running" ? STATUS.active : STATUS.pending;
-          lines.push(line("agent-row", `${TREE.branch} ${agentIcon} ${taskText}${metrics}`));
+          lines.push(line("agent-row", `${TREE.branch}${agentIcon} ${taskText}`));
 
           // Sub-status
           if (agent.status === "completed") {
             const resultText = agent.result ? truncateText(agent.result, 60) : "Done";
-            lines.push(line("agent-substatus", `${TREE.vertical} ${CONNECTOR.subStatus}  ${resultText}${metrics ? ` (${metricsParts.join(" · ")})` : ""}`));
-          } else if (agent.status === "running" && agent.currentTool) {
-            lines.push(line("agent-substatus", `${TREE.vertical} ${CONNECTOR.subStatus}  ${truncateText(agent.currentTool, 50)}`));
+            lines.push(line("agent-substatus", `${TREE.vertical} ${CONNECTOR.subStatus}  ${resultText}`));
+          } else if (agent.status === "running") {
+            if (agent.toolUses !== undefined && agent.toolUses > 0) {
+              lines.push(line("agent-substatus", `${TREE.vertical} ${CONNECTOR.subStatus}  ${agent.name}: (${agent.toolUses} tool use${agent.toolUses !== 1 ? "s" : ""})`));
+              if (agent.currentTool) {
+                lines.push(line("agent-substatus", `${TREE.vertical}   · ${truncateText(agent.currentTool, 50)}`));
+              }
+            } else if (agent.currentTool) {
+              lines.push(line("agent-substatus", `${TREE.vertical} ${CONNECTOR.subStatus}  Initializing ${agent.name}…`));
+            } else {
+              lines.push(line("agent-substatus", `${TREE.vertical} ${CONNECTOR.subStatus}  Initializing ${agent.name}…`));
+            }
           } else if (agent.status === "error" && agent.error) {
             lines.push(line("agent-substatus", `${TREE.vertical} ${CONNECTOR.subStatus}  ${truncateText(agent.error, 60)}`));
           }
diff --git a/src/ui/utils/workflow-input-resolver.test.ts b/src/ui/utils/workflow-input-resolver.test.ts
new file mode 100644
index 0000000000..8a58e6337f
--- /dev/null
+++ b/src/ui/utils/workflow-input-resolver.test.ts
@@ -0,0 +1,68 @@
+import { describe, expect, mock, test } from "bun:test";
+import {
+  consumeWorkflowInputSubmission,
+  rejectPendingWorkflowInput,
+  STALE_WORKFLOW_INPUT_REASON,
+} from "./workflow-input-resolver.ts";
+
+describe("consumeWorkflowInputSubmission", () => {
+  test("resolves pending workflow input when workflow is active", () => {
+    const resolve = mock((_prompt: string) => {});
+    const reject = mock((_error: Error) => {});
+
+    const result = consumeWorkflowInputSubmission(
+      { resolve, reject },
+      true,
+      "Continue with implementation",
+    );
+
+    expect(result).toEqual({ consumed: true, nextResolver: null });
+    expect(resolve).toHaveBeenCalledTimes(1);
+    expect(resolve).toHaveBeenCalledWith("Continue with implementation");
+    expect(reject).not.toHaveBeenCalled();
+  });
+
+  test("rejects stale pending workflow input when workflow is inactive", () => {
+    const resolve = mock((_prompt: string) => {});
+    const reject = mock((_error: Error) => {});
+
+    const result = consumeWorkflowInputSubmission(
+      { resolve, reject },
+      false,
+      "Follow-up message",
+    );
+
+    expect(result).toEqual({ consumed: false, nextResolver: null });
+    expect(resolve).not.toHaveBeenCalled();
+    expect(reject).toHaveBeenCalledTimes(1);
+    const rejectionError = reject.mock.calls[0]?.[0];
+    expect(rejectionError).toBeInstanceOf(Error);
+    expect((rejectionError as Error).message).toBe(STALE_WORKFLOW_INPUT_REASON);
+  });
+});
+
+describe("rejectPendingWorkflowInput", () => {
+  test("rejects and clears a pending resolver", () => {
+    const resolve = mock((_prompt: string) => {});
+    const reject = mock((_error: Error) => {});
+
+    const next = rejectPendingWorkflowInput(
+      { resolve, reject },
+      "Workflow ended before input was received",
+    );
+
+    expect(next).toBeNull();
+    expect(resolve).not.toHaveBeenCalled();
+    expect(reject).toHaveBeenCalledTimes(1);
+    const rejectionError = reject.mock.calls[0]?.[0];
+    expect(rejectionError).toBeInstanceOf(Error);
+    expect((rejectionError as Error).message).toBe(
+      "Workflow ended before input was received",
+    );
+  });
+
+  test("no-ops when resolver is already null", () => {
+    const next = rejectPendingWorkflowInput(null);
+    expect(next).toBeNull();
+  });
+});
diff --git a/src/ui/utils/workflow-input-resolver.ts b/src/ui/utils/workflow-input-resolver.ts
new file mode 100644
index 0000000000..b699a5d9e1
--- /dev/null
+++ b/src/ui/utils/workflow-input-resolver.ts
@@ -0,0 +1,34 @@
+export interface WorkflowInputResolver {
+  resolve: (prompt: string) => void;
+  reject: (reason: Error) => void;
+}
+
+export const STALE_WORKFLOW_INPUT_REASON = "Workflow is no longer active";
+
+export function consumeWorkflowInputSubmission(
+  resolver: WorkflowInputResolver | null,
+  workflowActive: boolean,
+  prompt: string,
+): { consumed: boolean; nextResolver: WorkflowInputResolver | null } {
+  if (!resolver) {
+    return { consumed: false, nextResolver: null };
+  }
+
+  if (!workflowActive) {
+    resolver.reject(new Error(STALE_WORKFLOW_INPUT_REASON));
+    return { consumed: false, nextResolver: null };
+  }
+
+  resolver.resolve(prompt);
+  return { consumed: true, nextResolver: null };
+}
+
+export function rejectPendingWorkflowInput(
+  resolver: WorkflowInputResolver | null,
+  reason: string = STALE_WORKFLOW_INPUT_REASON,
+): WorkflowInputResolver | null {
+  if (resolver) {
+    resolver.reject(new Error(reason));
+  }
+  return null;
+}
diff --git a/src/ui/utils/ralph-task-state.ts b/src/ui/utils/workflow-task-state.ts
similarity index 82%
rename from src/ui/utils/ralph-task-state.ts
rename to src/ui/utils/workflow-task-state.ts
index 2ed21987c4..1ef088a800 100644
--- a/src/ui/utils/ralph-task-state.ts
+++ b/src/ui/utils/workflow-task-state.ts
@@ -1,22 +1,22 @@
 /**
- * Ralph task-state helpers used by interrupt/resume and message snapshots.
+ * Workflow task-state helpers used by interrupt/resume and message snapshots.
  */
 
-export type RalphTaskStatus = "pending" | "in_progress" | "completed" | "error";
+export type WorkflowTaskStatus = "pending" | "in_progress" | "completed" | "error";
 
-export interface RalphTaskStateItem {
+export interface WorkflowTaskStateItem {
   id?: string;
   content: string;
-  status: RalphTaskStatus;
+  status: WorkflowTaskStatus;
   blockedBy?: string[];
 }
 
-export interface RalphTaskSnapshotMessage {
+export interface WorkflowTaskSnapshotMessage {
   role: string;
-  taskItems?: RalphTaskStateItem[];
+  taskItems?: WorkflowTaskStateItem[];
 }
 
-function normalizeRalphTaskId(id: string): string {
+function normalizeWorkflowTaskId(id: string): string {
   const trimmed = id.trim().toLowerCase();
   return trimmed.startsWith("#") ? trimmed.slice(1) : trimmed;
 }
@@ -46,10 +46,10 @@ function normalizeTaskContent(content: string): string {
 }
 
 /**
- * True when any incoming todo item belongs to the current ralph task set.
+ * True when any incoming todo item belongs to the current workflow task set.
  * ID matching is format-tolerant (`#1` and `1` are treated as equivalent).
  */
-export function hasRalphTaskIdOverlap<T extends { id?: string }>(
+export function hasWorkflowTaskIdOverlap<T extends { id?: string }>(
   todos: readonly T[],
   knownTaskIds: ReadonlySet<string>,
   previousTasks: readonly { content: string }[] = [],
@@ -59,7 +59,7 @@ export function hasRalphTaskIdOverlap<T extends { id?: string }>(
   const normalizedKnownIds = new Set(
     Array.from(knownTaskIds)
       .filter((id): id is string => typeof id === "string" && id.trim().length > 0)
-      .map(normalizeRalphTaskId),
+      .map(normalizeWorkflowTaskId),
   );
 
   const previousContentKeys = new Set(
@@ -73,7 +73,7 @@ export function hasRalphTaskIdOverlap<T extends { id?: string }>(
   for (const todo of todos) {
     const rawId = todo.id;
     if (typeof rawId === "string" && rawId.trim().length > 0) {
-      const normalizedId = normalizeRalphTaskId(rawId);
+      const normalizedId = normalizeWorkflowTaskId(rawId);
       if (normalizedKnownIds.size > 0 && !normalizedKnownIds.has(normalizedId)) {
         return false;
       }
@@ -112,7 +112,7 @@ export function hasRalphTaskIdOverlap<T extends { id?: string }>(
 /**
  * Convert interrupted in-progress work back to pending so it stays unchecked/retryable.
  */
-export function normalizeInterruptedTasks<T extends RalphTaskStateItem>(
+export function normalizeInterruptedTasks<T extends WorkflowTaskStateItem>(
   tasks: readonly T[],
 ): T[] {
   return tasks.map((task) =>
@@ -126,8 +126,8 @@ export function normalizeInterruptedTasks<T extends RalphTaskStateItem>(
  * Capture task items for message snapshots without mutating semantic status.
  */
 export function snapshotTaskItems(
-  tasks: readonly RalphTaskStateItem[],
-): RalphTaskStateItem[] | undefined {
+  tasks: readonly WorkflowTaskStateItem[],
+): WorkflowTaskStateItem[] | undefined {
   if (tasks.length === 0) return undefined;
   return tasks.map((task) => ({
     id: task.id,
@@ -137,7 +137,7 @@ export function snapshotTaskItems(
   }));
 }
 
-function hasInProgressTasks(tasks: readonly RalphTaskStateItem[]): boolean {
+function hasInProgressTasks(tasks: readonly WorkflowTaskStateItem[]): boolean {
   return tasks.some((task) => task.status === "in_progress");
 }
 
@@ -147,7 +147,7 @@ function hasInProgressTasks(tasks: readonly RalphTaskStateItem[]): boolean {
  * If one source still reports in_progress tasks while the other does not, prefer the
  * source without in_progress so stale last-item snapshots do not survive cleanup.
  */
-export function preferTerminalTaskItems<T extends RalphTaskStateItem>(
+export function preferTerminalTaskItems<T extends WorkflowTaskStateItem>(
   inMemoryTasks: readonly T[],
   diskTasks: readonly T[],
 ): T[] {
@@ -170,8 +170,8 @@ export function preferTerminalTaskItems<T extends RalphTaskStateItem>(
  * in_progress rows do not remain visible after workflow cleanup.
  */
 export function applyTaskSnapshotToLatestAssistantMessage<
-  TMessage extends RalphTaskSnapshotMessage,
-  TTask extends RalphTaskStateItem,
+  TMessage extends WorkflowTaskSnapshotMessage,
+  TTask extends WorkflowTaskStateItem,
 >(
   messages: readonly TMessage[],
   tasks: readonly TTask[],
diff --git a/src/utils/markdown.test.ts b/src/utils/markdown.test.ts
index 43d9534efb..4bcb1e24ed 100644
--- a/src/utils/markdown.test.ts
+++ b/src/utils/markdown.test.ts
@@ -1,4 +1,6 @@
 import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
 import { parseMarkdownFrontmatter } from "./markdown";
 
 describe("parseMarkdownFrontmatter", () => {
@@ -555,6 +557,15 @@ Body`;
       expect(result?.frontmatter.time).toBe("12:30:45");
     });
 
+    test("handles CRLF line endings (Windows)", () => {
+      const content = "---\r\nname: test-agent\r\ndescription: A test agent\r\n---\r\nBody content";
+      const result = parseMarkdownFrontmatter(content);
+      expect(result).not.toBeNull();
+      expect(result?.frontmatter.name).toBe("test-agent");
+      expect(result?.frontmatter.description).toBe("A test agent");
+      expect(result?.body).toBe("Body content");
+    });
+
     test("key with empty value followed by non-indented next line", () => {
       // Value is empty, next line exists but is not indented (not array/object)
       const content = `---
@@ -570,4 +581,5 @@ Body`;
       expect(result?.frontmatter.nextkey).toBe("hello");
     });
   });
+
 });
diff --git a/src/utils/markdown.ts b/src/utils/markdown.ts
index b59d51f6e4..161f40d980 100644
--- a/src/utils/markdown.ts
+++ b/src/utils/markdown.ts
@@ -15,8 +15,10 @@
 export function parseMarkdownFrontmatter(
   content: string
 ): { frontmatter: Record<string, unknown>; body: string } | null {
+  // Normalize CRLF to LF so the regex and line splitting work on all platforms
+  const normalized = content.replace(/\r\n/g, "\n");
   const frontmatterRegex = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/;
-  const match = content.match(frontmatterRegex);
+  const match = normalized.match(frontmatterRegex);
 
   if (!match) {
     return null;
diff --git a/src/utils/mcp-config.test.ts b/src/utils/mcp-config.test.ts
index c821afb0f8..29b3b80bf1 100644
--- a/src/utils/mcp-config.test.ts
+++ b/src/utils/mcp-config.test.ts
@@ -1,89 +1,3 @@
 import { expect, test } from "bun:test";
-import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
 
 import { discoverMcpConfigs } from "./mcp-config";
-
-test("discoverMcpConfigs finds Copilot MCP config in .vscode/mcp.json", async () => {
-  const root = await mkdtemp(join(tmpdir(), "atomic-mcp-config-"));
-  const previousHome = process.env.HOME;
-
-  try {
-    const projectRoot = join(root, "project");
-    const homeDir = join(root, "home");
-    await mkdir(homeDir, { recursive: true });
-    process.env.HOME = homeDir;
-
-    await mkdir(join(projectRoot, ".vscode"), { recursive: true });
-    await writeFile(
-      join(projectRoot, ".vscode", "mcp.json"),
-      JSON.stringify({
-        mcpServers: {
-          vscode_server: {
-            type: "local",
-            command: "bunx",
-            args: ["example-mcp"],
-          },
-        },
-      }),
-      "utf-8"
-    );
-
-    const servers = discoverMcpConfigs(projectRoot);
-    const server = servers.find((entry) => entry.name === "vscode_server");
-
-    expect(server).toBeDefined();
-    expect(server?.type).toBe("stdio");
-    expect(server?.command).toBe("bunx");
-    expect(server?.args).toEqual(["example-mcp"]);
-  } finally {
-    if (typeof previousHome === "string") {
-      process.env.HOME = previousHome;
-    } else {
-      delete process.env.HOME;
-    }
-    await rm(root, { recursive: true, force: true });
-  }
-});
-
-test("discoverMcpConfigs applies includeDisabled to .vscode/mcp.json", async () => {
-  const root = await mkdtemp(join(tmpdir(), "atomic-mcp-config-"));
-  const previousHome = process.env.HOME;
-
-  try {
-    const projectRoot = join(root, "project");
-    const homeDir = join(root, "home");
-    await mkdir(homeDir, { recursive: true });
-    process.env.HOME = homeDir;
-
-    await mkdir(join(projectRoot, ".vscode"), { recursive: true });
-    await writeFile(
-      join(projectRoot, ".vscode", "mcp.json"),
-      JSON.stringify({
-        mcpServers: {
-          disabled_server: {
-            type: "http",
-            url: "https://example.com/mcp",
-            enabled: false,
-          },
-        },
-      }),
-      "utf-8"
-    );
-
-    expect(discoverMcpConfigs(projectRoot)).toEqual([]);
-
-    const allServers = discoverMcpConfigs(projectRoot, { includeDisabled: true });
-    expect(allServers).toHaveLength(1);
-    expect(allServers[0]?.name).toBe("disabled_server");
-    expect(allServers[0]?.enabled).toBe(false);
-  } finally {
-    if (typeof previousHome === "string") {
-      process.env.HOME = previousHome;
-    } else {
-      delete process.env.HOME;
-    }
-    await rm(root, { recursive: true, force: true });
-  }
-});
diff --git a/src/utils/playwright-migration-verification.test.ts b/src/utils/playwright-migration-verification.test.ts
new file mode 100644
index 0000000000..a310fdb3ef
--- /dev/null
+++ b/src/utils/playwright-migration-verification.test.ts
@@ -0,0 +1,120 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "fs";
+import { join } from "path";
+
+const PROJECT_ROOT = process.cwd();
+
+const MIGRATION_TARGET_FILES = [
+  ".claude/agents/codebase-online-researcher.md",
+  ".claude/agents/debugger.md",
+  ".claude/agents/reviewer.md",
+  ".github/agents/codebase-online-researcher.md",
+  ".github/agents/debugger.md",
+  ".opencode/agents/codebase-online-researcher.md",
+  ".opencode/agents/debugger.md",
+  ".claude/skills/research-codebase/SKILL.md",
+  ".claude/skills/explain-code/SKILL.md",
+  ".github/skills/research-codebase/SKILL.md",
+  ".github/skills/explain-code/SKILL.md",
+  ".opencode/skills/research-codebase/SKILL.md",
+  ".opencode/skills/explain-code/SKILL.md",
+  "src/sdk/clients/claude.ts",
+  ".opencode/opencode.json",
+] as const;
+
+const LEGACY_WEB_TOKENS = ["WebFetch", "WebSearch", "webfetch"] as const;
+
+const GITHUB_AGENT_FILES = [
+  ".github/agents/codebase-online-researcher.md",
+  ".github/agents/debugger.md",
+] as const;
+
+const EXPLAIN_SKILL_FILES = [
+  ".claude/skills/explain-code/SKILL.md",
+  ".github/skills/explain-code/SKILL.md",
+  ".opencode/skills/explain-code/SKILL.md",
+] as const;
+
+const RESEARCH_SKILL_FILES = [
+  ".claude/skills/research-codebase/SKILL.md",
+  ".github/skills/research-codebase/SKILL.md",
+  ".opencode/skills/research-codebase/SKILL.md",
+] as const;
+
+const PLAYWRIGHT_SKILL_FILES = [
+  ".claude/skills/playwright-cli/SKILL.md",
+  ".github/skills/playwright-cli/SKILL.md",
+  ".opencode/skills/playwright-cli/SKILL.md",
+] as const;
+
+function readProjectFile(relativePath: string): string {
+  return readFileSync(join(PROJECT_ROOT, relativePath), "utf-8");
+}
+
+describe("Playwright web-tool migration verification", () => {
+  test("tracks exactly 15 migration target files", () => {
+    expect(MIGRATION_TARGET_FILES).toHaveLength(15);
+
+    for (const relativePath of MIGRATION_TARGET_FILES) {
+      expect(readProjectFile(relativePath).length).toBeGreaterThan(0);
+    }
+  });
+
+  test("removes legacy web-tool references from all migration target files", () => {
+    for (const relativePath of MIGRATION_TARGET_FILES) {
+      const content = readProjectFile(relativePath);
+
+      for (const token of LEGACY_WEB_TOKENS) {
+        expect(content.includes(token)).toBe(false);
+      }
+    }
+
+    for (const relativePath of GITHUB_AGENT_FILES) {
+      const content = readProjectFile(relativePath);
+      expect(content.includes('"web"')).toBe(false);
+    }
+  });
+
+  test("keeps playwright-cli guidance in migrated agent and skill files", () => {
+    expect(readProjectFile(".opencode/agents/codebase-online-researcher.md")).toContain(
+      "Playwright CLI"
+    );
+    expect(readProjectFile(".opencode/agents/debugger.md")).toContain("Playwright CLI");
+
+    for (const relativePath of EXPLAIN_SKILL_FILES) {
+      const content = readProjectFile(relativePath);
+      expect(content).toContain("`playwright-cli`");
+    }
+
+    for (const relativePath of RESEARCH_SKILL_FILES) {
+      const content = readProjectFile(relativePath);
+      expect(content).toContain("playwright-cli");
+    }
+  });
+});
+
+describe("Skill file parity", () => {
+  test("keeps explain-code SKILL.md identical across SDK directories", () => {
+    const canonical = readProjectFile(EXPLAIN_SKILL_FILES[0]);
+
+    for (const relativePath of EXPLAIN_SKILL_FILES.slice(1)) {
+      expect(readProjectFile(relativePath)).toBe(canonical);
+    }
+  });
+
+  test("keeps research-codebase SKILL.md identical across SDK directories", () => {
+    const canonical = readProjectFile(RESEARCH_SKILL_FILES[0]);
+
+    for (const relativePath of RESEARCH_SKILL_FILES.slice(1)) {
+      expect(readProjectFile(relativePath)).toBe(canonical);
+    }
+  });
+
+  test("keeps playwright-cli SKILL.md identical across SDK directories", () => {
+    const canonical = readProjectFile(PLAYWRIGHT_SKILL_FILES[0]);
+
+    for (const relativePath of PLAYWRIGHT_SKILL_FILES.slice(1)) {
+      expect(readProjectFile(relativePath)).toBe(canonical);
+    }
+  });
+});
diff --git a/src/workflows/executor-features.test.ts b/src/workflows/executor-features.test.ts
new file mode 100644
index 0000000000..9eb092fb33
--- /dev/null
+++ b/src/workflows/executor-features.test.ts
@@ -0,0 +1,346 @@
+/**
+ * Integration tests for executor features
+ * Tests #46, #47, #48 from the task list
+ */
+
+import { test, expect, describe } from "bun:test";
+import type { WorkflowTask, WorkflowDefinition } from "../ui/commands/workflow-commands.ts";
+import type { BaseState } from "./graph/types.ts";
+
+// ============================================================================
+// Task #46: Integration test — task list updates with WorkflowTask
+// ============================================================================
+
+describe("WorkflowTask interface shape", () => {
+    test("WorkflowTask has all required fields (id, title, status)", () => {
+        // Create a sample WorkflowTask object
+        const task: WorkflowTask = {
+            id: "#1",
+            title: "Implement feature X",
+            status: "pending",
+        };
+
+        // Verify required fields exist
+        expect(task.id).toBe("#1");
+        expect(task.title).toBe("Implement feature X");
+        expect(task.status).toBe("pending");
+    });
+
+    test("WorkflowTask allows all valid status values", () => {
+        // Test each valid status value
+        const statuses: Array<WorkflowTask["status"]> = [
+            "pending",
+            "in_progress",
+            "completed",
+            "failed",
+            "blocked",
+        ];
+
+        for (const status of statuses) {
+            const task: WorkflowTask = {
+                id: `#${status}`,
+                title: `Task with ${status} status`,
+                status,
+            };
+
+            expect(task.status).toBe(status);
+        }
+    });
+
+    test("WorkflowTask blockedBy field is optional", () => {
+        // Task without blockedBy
+        const task1: WorkflowTask = {
+            id: "#1",
+            title: "Independent task",
+            status: "pending",
+        };
+
+        expect(task1.blockedBy).toBeUndefined();
+
+        // Task with blockedBy
+        const task2: WorkflowTask = {
+            id: "#2",
+            title: "Dependent task",
+            status: "blocked",
+            blockedBy: ["#1"],
+        };
+
+        expect(task2.blockedBy).toEqual(["#1"]);
+    });
+
+    test("WorkflowTask error field is optional", () => {
+        // Task without error
+        const task1: WorkflowTask = {
+            id: "#1",
+            title: "Successful task",
+            status: "completed",
+        };
+
+        expect(task1.error).toBeUndefined();
+
+        // Task with error
+        const task2: WorkflowTask = {
+            id: "#2",
+            title: "Failed task",
+            status: "failed",
+            error: "Network timeout",
+        };
+
+        expect(task2.error).toBe("Network timeout");
+    });
+
+    test("WorkflowTask with all optional fields", () => {
+        // Complete task with all fields
+        const task: WorkflowTask = {
+            id: "#3",
+            title: "Complex task",
+            status: "blocked",
+            blockedBy: ["#1", "#2"],
+            error: "Waiting for dependencies",
+        };
+
+        expect(task.id).toBe("#3");
+        expect(task.title).toBe("Complex task");
+        expect(task.status).toBe("blocked");
+        expect(task.blockedBy).toEqual(["#1", "#2"]);
+        expect(task.error).toBe("Waiting for dependencies");
+    });
+
+    test("WorkflowTask array with mixed configurations", () => {
+        // Array of tasks with different configurations
+        const tasks: WorkflowTask[] = [
+            {
+                id: "#1",
+                title: "First task",
+                status: "completed",
+            },
+            {
+                id: "#2",
+                title: "Second task",
+                status: "in_progress",
+                blockedBy: ["#1"],
+            },
+            {
+                id: "#3",
+                title: "Third task",
+                status: "failed",
+                error: "Build error",
+            },
+            {
+                id: "#4",
+                title: "Fourth task",
+                status: "blocked",
+                blockedBy: ["#2", "#3"],
+                error: "Dependencies not met",
+            },
+        ];
+
+        expect(tasks).toHaveLength(4);
+        expect(tasks[0]!.status).toBe("completed");
+        expect(tasks[1]!.blockedBy).toEqual(["#1"]);
+        expect(tasks[2]!.error).toBe("Build error");
+        expect(tasks[3]!.status).toBe("blocked");
+    });
+});
+
+// ============================================================================
+// Task #47: Integration test — undescribed nodes silently skipped
+// ============================================================================
+
+describe("Undescribed nodes silently skipped", () => {
+    test("WorkflowDefinition with partial nodeDescriptions", () => {
+        interface TestState extends BaseState {
+            value: string;
+        }
+
+        // Create a WorkflowDefinition with nodeDescriptions that only covers some nodes
+        const definition: WorkflowDefinition = {
+            name: "test-workflow",
+            description: "Test workflow with partial node descriptions",
+            nodeDescriptions: {
+                "node1": "📝 Processing node 1...",
+                "node3": "✅ Processing node 3...",
+                // node2 is intentionally omitted - it should be silently skipped
+            },
+        };
+
+        // Verify that described nodes return descriptions
+        expect(definition.nodeDescriptions?.["node1"]).toBe("📝 Processing node 1...");
+        expect(definition.nodeDescriptions?.["node3"]).toBe("✅ Processing node 3...");
+
+        // Verify that undescribed nodes return undefined (silently skipped)
+        expect(definition.nodeDescriptions?.["node2"]).toBeUndefined();
+        expect(definition.nodeDescriptions?.["nonexistent"]).toBeUndefined();
+    });
+
+    test("WorkflowDefinition with no nodeDescriptions", () => {
+        // Create a WorkflowDefinition without nodeDescriptions
+        const definition: WorkflowDefinition = {
+            name: "simple-workflow",
+            description: "Simple workflow without node descriptions",
+        };
+
+        // Verify that nodeDescriptions is optional and undefined
+        expect(definition.nodeDescriptions).toBeUndefined();
+
+        // Verify that looking up any node returns undefined
+        expect(definition.nodeDescriptions?.["node1"]).toBeUndefined();
+        expect(definition.nodeDescriptions?.["any-node"]).toBeUndefined();
+    });
+
+    test("WorkflowDefinition with empty nodeDescriptions", () => {
+        // Create a WorkflowDefinition with empty nodeDescriptions
+        const definition: WorkflowDefinition = {
+            name: "empty-workflow",
+            description: "Workflow with empty node descriptions",
+            nodeDescriptions: {},
+        };
+
+        // Verify that nodeDescriptions is defined but empty
+        expect(definition.nodeDescriptions).toBeDefined();
+        expect(Object.keys(definition.nodeDescriptions!)).toHaveLength(0);
+
+        // Verify that looking up any node returns undefined
+        expect(definition.nodeDescriptions?.["node1"]).toBeUndefined();
+    });
+
+    test("Node description lookup behavior", () => {
+        interface TestState extends BaseState {
+            phase: string;
+        }
+
+        const definition: WorkflowDefinition = {
+            name: "multi-node-workflow",
+            description: "Workflow with multiple nodes",
+            nodeDescriptions: {
+                "planner": "🧠 Planning tasks...",
+                "worker": "⚙️ Working on tasks...",
+                "reviewer": "👀 Reviewing work...",
+                // "fixer" node is intentionally omitted
+            },
+        };
+
+        // Test described nodes
+        const nodeIds = ["planner", "worker", "reviewer", "fixer", "unknown"];
+        const results = nodeIds.map(nodeId => ({
+            nodeId,
+            description: definition.nodeDescriptions?.[nodeId],
+        }));
+
+        // Verify described nodes have descriptions
+        expect(results[0]!.description).toBe("🧠 Planning tasks...");
+        expect(results[1]!.description).toBe("⚙️ Working on tasks...");
+        expect(results[2]!.description).toBe("👀 Reviewing work...");
+
+        // Verify undescribed nodes are silently skipped (return undefined)
+        expect(results[3]!.description).toBeUndefined();
+        expect(results[4]!.description).toBeUndefined();
+    });
+});
+
+// ============================================================================
+// Task #48: Integration test — Ctrl+C cancellation for generic workflows
+// ============================================================================
+
+describe("Workflow cancellation error handling", () => {
+    test("executeWorkflow handles 'Workflow cancelled' error gracefully", () => {
+        // This test verifies the specific error message handling logic
+        // that's implemented in executeWorkflow() at lines 258-268
+
+        // Create a mock error that simulates Ctrl+C cancellation
+        const cancellationError = new Error("Workflow cancelled");
+
+        // Verify the error message
+        expect(cancellationError.message).toBe("Workflow cancelled");
+
+        // The executeWorkflow function should:
+        // 1. Catch this error
+        // 2. Check if error.message === "Workflow cancelled"
+        // 3. Return { success: true } instead of failing
+        // This is the "silent exit" behavior for workflow cancellation
+
+        // Test the error matching logic
+        const isCancellationError = 
+            cancellationError instanceof Error && 
+            cancellationError.message === "Workflow cancelled";
+
+        expect(isCancellationError).toBe(true);
+    });
+
+    test("Other errors are not treated as cancellations", () => {
+        // Create various error types that should NOT be treated as cancellations
+        const errors = [
+            new Error("Network error"),
+            new Error("Workflow failed"),
+            new Error("Task execution error"),
+            new Error("cancelled"), // Different message
+            new Error("Workflow Cancelled"), // Different case
+            new Error("The workflow was cancelled"), // Different wording
+        ];
+
+        for (const error of errors) {
+            const isCancellationError = 
+                error instanceof Error && 
+                error.message === "Workflow cancelled";
+
+            expect(isCancellationError).toBe(false);
+        }
+    });
+
+    test("Cancellation error should result in success: true", () => {
+        // This test documents the expected behavior when cancellation occurs
+        const cancellationError = new Error("Workflow cancelled");
+
+        // Simulate the executeWorkflow error handling logic
+        let result: { success: boolean; stateUpdate?: unknown };
+
+        try {
+            // Simulate workflow execution that gets cancelled
+            throw cancellationError;
+        } catch (error) {
+            // This matches the logic in executor.ts lines 258-268
+            if (error instanceof Error && error.message === "Workflow cancelled") {
+                result = {
+                    success: true,
+                    stateUpdate: {
+                        workflowActive: false,
+                        workflowType: null,
+                        initialPrompt: null,
+                    },
+                };
+            } else {
+                result = {
+                    success: false,
+                    stateUpdate: {
+                        workflowActive: false,
+                        workflowType: null,
+                        initialPrompt: null,
+                    },
+                };
+            }
+        }
+
+        // Verify that cancellation is treated as success
+        expect(result.success).toBe(true);
+    });
+
+    test("Workflow cancelled error cleans up state correctly", () => {
+        // Verify the state update structure for cancellation
+        const expectedStateUpdate = {
+            workflowActive: false,
+            workflowType: null,
+            initialPrompt: null,
+        };
+
+        // This is the structure returned by executeWorkflow on cancellation
+        const cancellationResult = {
+            success: true,
+            stateUpdate: expectedStateUpdate,
+        };
+
+        expect(cancellationResult.success).toBe(true);
+        expect(cancellationResult.stateUpdate.workflowActive).toBe(false);
+        expect(cancellationResult.stateUpdate.workflowType).toBe(null);
+        expect(cancellationResult.stateUpdate.initialPrompt).toBe(null);
+    });
+});
diff --git a/src/workflows/executor-integration.test.ts b/src/workflows/executor-integration.test.ts
new file mode 100644
index 0000000000..1f5e4ced0d
--- /dev/null
+++ b/src/workflows/executor-integration.test.ts
@@ -0,0 +1,449 @@
+/**
+ * Integration tests for workflow executor
+ * Tests the integration of workflow components working together
+ */
+
+import { test, expect, describe } from "bun:test";
+import { ralphWorkflowDefinition } from "./ralph/definition.ts";
+import { compileGraphConfig } from "./executor.ts";
+import type {
+    WorkflowDefinition,
+    WorkflowGraphConfig,
+    WorkflowStateParams,
+} from "../ui/commands/workflow-commands.ts";
+import type { BaseState, NodeDefinition, Edge } from "./graph/types.ts";
+import { createNode } from "./graph/builder.ts";
+
+// ============================================================================
+// Task #43: Integration test — Ralph through generic execution path
+// ============================================================================
+
+describe("Task #43: Ralph workflow through generic execution path", () => {
+    test("ralphWorkflowDefinition has expected properties", () => {
+        // Verify it's a valid WorkflowDefinition with required fields
+        expect(ralphWorkflowDefinition).toBeDefined();
+        expect(ralphWorkflowDefinition.name).toBe("ralph");
+        expect(ralphWorkflowDefinition.description).toBeTruthy();
+        expect(ralphWorkflowDefinition.version).toBeTruthy();
+    });
+
+    test("ralphWorkflowDefinition has createState factory", () => {
+        expect(ralphWorkflowDefinition.createState).toBeDefined();
+        expect(typeof ralphWorkflowDefinition.createState).toBe("function");
+    });
+
+    test("ralphWorkflowDefinition has nodeDescriptions", () => {
+        expect(ralphWorkflowDefinition.nodeDescriptions).toBeDefined();
+        expect(typeof ralphWorkflowDefinition.nodeDescriptions).toBe("object");
+    });
+
+    test("createState produces valid state with expected fields", () => {
+        if (!ralphWorkflowDefinition.createState) {
+            throw new Error("createState is not defined");
+        }
+
+        const params: WorkflowStateParams = {
+            prompt: "Test prompt",
+            sessionId: "test-session-123",
+            sessionDir: "/tmp/test-session",
+            maxIterations: 50,
+        };
+
+        const state = ralphWorkflowDefinition.createState(params);
+
+        // Verify state has BaseState fields
+        expect(state).toBeDefined();
+        expect(typeof state).toBe("object");
+
+        // Verify state has required Ralph-specific session fields
+        // Ralph uses ralphSessionId and ralphSessionDir as field names
+        expect(state).toHaveProperty("ralphSessionId");
+        expect(state).toHaveProperty("ralphSessionDir");
+        expect(state).toHaveProperty("maxIterations");
+        expect((state as any).ralphSessionId).toBe("test-session-123");
+        expect((state as any).ralphSessionDir).toBe("/tmp/test-session");
+        expect((state as any).maxIterations).toBe(50);
+    });
+
+    test("nodeDescriptions contains expected node IDs", () => {
+        const descriptions = ralphWorkflowDefinition.nodeDescriptions;
+
+        if (!descriptions) {
+            throw new Error("nodeDescriptions is not defined");
+        }
+
+        // Verify all expected Ralph workflow nodes are described
+        const expectedNodeIds = [
+            "planner",
+            "parse-tasks",
+            "select-ready-tasks",
+            "worker",
+            "reviewer",
+            "fixer",
+        ];
+
+        for (const nodeId of expectedNodeIds) {
+            expect(descriptions).toHaveProperty(nodeId);
+            const description = descriptions[nodeId];
+            expect(typeof description).toBe("string");
+            expect(description?.length ?? 0).toBeGreaterThan(0);
+        }
+    });
+
+    test("nodeDescriptions are human-readable", () => {
+        const descriptions = ralphWorkflowDefinition.nodeDescriptions;
+
+        if (!descriptions) {
+            throw new Error("nodeDescriptions is not defined");
+        }
+
+        // Verify descriptions contain expected content patterns
+        expect(descriptions["planner"]).toContain("Planning");
+        expect(descriptions["parse-tasks"]).toContain("Parsing");
+        expect(descriptions["select-ready-tasks"]).toContain("Selecting");
+        expect(descriptions["worker"]).toContain("Working");
+        expect(descriptions["reviewer"]).toContain("Review");
+        expect(descriptions["fixer"]).toContain("Fix");
+    });
+});
+
+// ============================================================================
+// Task #44: Integration test — custom workflow with graphConfig
+// ============================================================================
+
+describe("Task #44: Custom workflow with graphConfig", () => {
+    interface CustomWorkflowState extends BaseState {
+        input: string;
+        result: string;
+    }
+
+    test("compileGraphConfig compiles minimal workflow correctly", () => {
+        // Create a minimal WorkflowGraphConfig with 2 nodes and 1 edge
+        const graphConfig: WorkflowGraphConfig<CustomWorkflowState> = {
+            nodes: [
+                {
+                    id: "start-node",
+                    type: "tool",
+                    execute: async (ctx) => ({
+                        stateUpdate: { result: `Processed: ${ctx.state.input}` } as Partial<CustomWorkflowState>,
+                    }),
+                },
+                {
+                    id: "end-node",
+                    type: "agent",
+                    execute: async (ctx) => ({
+                        stateUpdate: { result: `${ctx.state.result} - Done` } as Partial<CustomWorkflowState>,
+                    }),
+                },
+            ],
+            edges: [{ from: "start-node", to: "end-node" }],
+            startNode: "start-node",
+        };
+
+        // Call compileGraphConfig
+        const compiled = compileGraphConfig(graphConfig);
+
+        // Verify the compiled graph has the correct structure
+        expect(compiled).toBeDefined();
+        expect(compiled.nodes).toBeDefined();
+        expect(compiled.edges).toBeDefined();
+        expect(compiled.startNode).toBeDefined();
+        expect(compiled.endNodes).toBeDefined();
+    });
+
+    test("compiled graph has correct nodes", () => {
+        const graphConfig: WorkflowGraphConfig<CustomWorkflowState> = {
+            nodes: [
+                {
+                    id: "node-a",
+                    type: "tool",
+                    execute: async () => ({ stateUpdate: {} }),
+                },
+                {
+                    id: "node-b",
+                    type: "agent",
+                    execute: async () => ({ stateUpdate: {} }),
+                },
+            ],
+            edges: [{ from: "node-a", to: "node-b" }],
+            startNode: "node-a",
+        };
+
+        const compiled = compileGraphConfig(graphConfig);
+
+        // Verify nodes are correctly mapped
+        expect(compiled.nodes.size).toBe(2);
+        expect(compiled.nodes.has("node-a")).toBe(true);
+        expect(compiled.nodes.has("node-b")).toBe(true);
+        expect(compiled.nodes.get("node-a")?.type).toBe("tool");
+        expect(compiled.nodes.get("node-b")?.type).toBe("agent");
+    });
+
+    test("compiled graph has correct edges", () => {
+        const graphConfig: WorkflowGraphConfig<CustomWorkflowState> = {
+            nodes: [
+                {
+                    id: "node-1",
+                    type: "tool",
+                    execute: async () => ({ stateUpdate: {} }),
+                },
+                {
+                    id: "node-2",
+                    type: "agent",
+                    execute: async () => ({ stateUpdate: {} }),
+                },
+            ],
+            edges: [{ from: "node-1", to: "node-2" }],
+            startNode: "node-1",
+        };
+
+        const compiled = compileGraphConfig(graphConfig);
+
+        // Verify edges are copied
+        expect(compiled.edges).toBeDefined();
+        expect(compiled.edges.length).toBe(1);
+        expect(compiled.edges[0]?.from).toBe("node-1");
+        expect(compiled.edges[0]?.to).toBe("node-2");
+    });
+
+    test("compiled graph has correct startNode", () => {
+        const graphConfig: WorkflowGraphConfig<CustomWorkflowState> = {
+            nodes: [
+                {
+                    id: "first",
+                    type: "tool",
+                    execute: async () => ({ stateUpdate: {} }),
+                },
+                {
+                    id: "second",
+                    type: "agent",
+                    execute: async () => ({ stateUpdate: {} }),
+                },
+            ],
+            edges: [{ from: "first", to: "second" }],
+            startNode: "first",
+        };
+
+        const compiled = compileGraphConfig(graphConfig);
+
+        // Verify startNode is set correctly
+        expect(compiled.startNode).toBe("first");
+    });
+
+    test("compiled graph detects correct endNodes", () => {
+        const graphConfig: WorkflowGraphConfig<CustomWorkflowState> = {
+            nodes: [
+                {
+                    id: "beginning",
+                    type: "tool",
+                    execute: async () => ({ stateUpdate: {} }),
+                },
+                {
+                    id: "finale",
+                    type: "agent",
+                    execute: async () => ({ stateUpdate: {} }),
+                },
+            ],
+            edges: [{ from: "beginning", to: "finale" }],
+            startNode: "beginning",
+        };
+
+        const compiled = compileGraphConfig(graphConfig);
+
+        // Verify endNodes are detected (nodes with no outgoing edges)
+        expect(compiled.endNodes.size).toBe(1);
+        expect(compiled.endNodes.has("finale")).toBe(true);
+        expect(compiled.endNodes.has("beginning")).toBe(false);
+    });
+
+    test("compiled graph handles maxIterations in config", () => {
+        const graphConfig: WorkflowGraphConfig<CustomWorkflowState> = {
+            nodes: [
+                {
+                    id: "loop-node",
+                    type: "tool",
+                    execute: async () => ({ stateUpdate: {} }),
+                },
+            ],
+            edges: [{ from: "loop-node", to: "loop-node", condition: () => true }],
+            startNode: "loop-node",
+            maxIterations: 25,
+        };
+
+        const compiled = compileGraphConfig(graphConfig);
+
+        // Verify maxIterations is set in config metadata
+        expect(compiled.config).toBeDefined();
+        expect(compiled.config.metadata).toBeDefined();
+        expect(compiled.config.metadata?.maxIterations).toBe(25);
+    });
+
+    test("compiled graph handles missing maxIterations", () => {
+        const graphConfig: WorkflowGraphConfig<CustomWorkflowState> = {
+            nodes: [
+                {
+                    id: "simple-node",
+                    type: "tool",
+                    execute: async () => ({ stateUpdate: {} }),
+                },
+            ],
+            edges: [],
+            startNode: "simple-node",
+            // No maxIterations specified
+        };
+
+        const compiled = compileGraphConfig(graphConfig);
+
+        // Verify config is empty object when maxIterations not provided
+        expect(compiled.config).toBeDefined();
+        // Either metadata is undefined, or maxIterations is undefined
+        if (compiled.config.metadata) {
+            expect(compiled.config.metadata.maxIterations).toBeUndefined();
+        }
+    });
+});
+
+// ============================================================================
+// Task #45: Integration test — workflow without graphConfig fallback
+// ============================================================================
+
+describe("Task #45: Workflow without graphConfig fallback", () => {
+    test("WorkflowMetadata without graphConfig is valid", () => {
+        // Create a test WorkflowMetadata without graphConfig or createState
+        const simpleWorkflow: WorkflowDefinition = {
+            name: "simple-chat",
+            description: "A simple chat-based workflow",
+            version: "1.0.0",
+            source: "builtin",
+            // No graphConfig, no createState
+        };
+
+        // Verify it's a valid WorkflowDefinition
+        expect(simpleWorkflow).toBeDefined();
+        expect(simpleWorkflow.name).toBe("simple-chat");
+        expect(simpleWorkflow.description).toBeTruthy();
+
+        // Verify optional fields are absent
+        expect(simpleWorkflow.graphConfig).toBeUndefined();
+        expect(simpleWorkflow.createState).toBeUndefined();
+        expect(simpleWorkflow.nodeDescriptions).toBeUndefined();
+    });
+
+    test("chat-based workflow can have basic metadata", () => {
+        // Create a chat-based workflow with just metadata
+        const chatWorkflow: WorkflowDefinition = {
+            name: "chat-helper",
+            description: "A workflow that uses chat interface",
+            aliases: ["help", "assist"],
+            version: "1.0.0",
+            argumentHint: "<question>",
+            source: "local",
+        };
+
+        // Verify all metadata fields are accessible
+        expect(chatWorkflow.name).toBe("chat-helper");
+        expect(chatWorkflow.description).toBe("A workflow that uses chat interface");
+        expect(chatWorkflow.aliases).toEqual(["help", "assist"]);
+        expect(chatWorkflow.version).toBe("1.0.0");
+        expect(chatWorkflow.argumentHint).toBe("<question>");
+        expect(chatWorkflow.source).toBe("local");
+    });
+
+    test("WorkflowDefinition supports optional defaultConfig", () => {
+        const workflowWithConfig: WorkflowDefinition = {
+            name: "configurable",
+            description: "A workflow with default config",
+            defaultConfig: {
+                temperature: 0.7,
+                maxTokens: 1000,
+                enableLogging: true,
+            },
+        };
+
+        expect(workflowWithConfig.defaultConfig).toBeDefined();
+        expect(workflowWithConfig.defaultConfig?.temperature).toBe(0.7);
+        expect(workflowWithConfig.defaultConfig?.maxTokens).toBe(1000);
+        expect(workflowWithConfig.defaultConfig?.enableLogging).toBe(true);
+    });
+
+    test("WorkflowDefinition can have both graphConfig and chat fallback metadata", () => {
+        // This tests backward compatibility - a workflow can have graphConfig
+        // but still have metadata for when it falls back to chat mode
+
+        const hybridWorkflow: WorkflowDefinition = {
+            name: "hybrid",
+            description: "Can work both ways",
+            argumentHint: "<input>",
+            // Note: graphConfig is optional and omitted here for simplicity
+            // This tests that a workflow can have metadata without graphConfig
+        };
+
+        // Verify it has metadata
+        expect(hybridWorkflow.name).toBe("hybrid");
+        expect(hybridWorkflow.argumentHint).toBe("<input>");
+        // graphConfig can be added later or omitted for chat-based workflows
+    });
+
+    test("WorkflowDefinition extends WorkflowMetadata (backward compatible)", () => {
+        // Test that all WorkflowMetadata fields are available in WorkflowDefinition
+        const definition: WorkflowDefinition = {
+            name: "test",
+            description: "test workflow",
+            aliases: ["t"],
+            defaultConfig: { key: "value" },
+            version: "1.0.0",
+            minSDKVersion: "0.1.0",
+            stateVersion: 1,
+            argumentHint: "<args>",
+            source: "global",
+        };
+
+        // All these should be accessible
+        expect(definition.name).toBe("test");
+        expect(definition.description).toBe("test workflow");
+        expect(definition.aliases).toEqual(["t"]);
+        expect(definition.defaultConfig).toEqual({ key: "value" });
+        expect(definition.version).toBe("1.0.0");
+        expect(definition.minSDKVersion).toBe("0.1.0");
+        expect(definition.stateVersion).toBe(1);
+        expect(definition.argumentHint).toBe("<args>");
+        expect(definition.source).toBe("global");
+    });
+
+    test("chat-based workflow supports state migrations", () => {
+        // Test that workflows without graphConfig can still have migrateState
+        const workflowWithMigration: WorkflowDefinition = {
+            name: "migrating",
+            description: "Supports state migrations",
+            stateVersion: 2,
+            migrateState: (oldState: unknown, fromVersion: number) => {
+                // Simple migration example
+                if (fromVersion === 1) {
+                    return {
+                        ...(oldState as object),
+                        upgraded: true,
+                        executionId: "",
+                        lastUpdated: new Date().toISOString(),
+                        outputs: {},
+                    } as BaseState;
+                }
+                return oldState as BaseState;
+            },
+        };
+
+        expect(workflowWithMigration.stateVersion).toBe(2);
+        expect(workflowWithMigration.migrateState).toBeDefined();
+        expect(typeof workflowWithMigration.migrateState).toBe("function");
+
+        // Test the migration function
+        if (workflowWithMigration.migrateState) {
+            const oldState = { data: "test" };
+            const migrated = workflowWithMigration.migrateState(oldState, 1);
+            expect(migrated).toHaveProperty("upgraded", true);
+            expect(migrated).toHaveProperty("data", "test");
+            expect(migrated).toHaveProperty("executionId");
+            expect(migrated).toHaveProperty("lastUpdated");
+            expect(migrated).toHaveProperty("outputs");
+        }
+    });
+});
diff --git a/src/workflows/executor.ctrlc-abort.integration.test.ts b/src/workflows/executor.ctrlc-abort.integration.test.ts
new file mode 100644
index 0000000000..46797d4443
--- /dev/null
+++ b/src/workflows/executor.ctrlc-abort.integration.test.ts
@@ -0,0 +1,89 @@
+import { describe, expect, test } from "bun:test";
+import { compileGraphConfig, executeWorkflow } from "./executor.ts";
+import type { BaseState } from "./graph/types.ts";
+
+function createMockContext(overrides?: Record<string, unknown>) {
+  const messages: Array<{ role: string; content: string }> = [];
+  let streaming = false;
+
+  return {
+    session: null,
+    state: {
+      isStreaming: false,
+      messageCount: 0,
+    },
+    addMessage: (role: string, content: string) => {
+      messages.push({ role, content });
+    },
+    setStreaming: (value: boolean) => {
+      streaming = value;
+    },
+    updateWorkflowState: () => {},
+    setTodoItems: () => {},
+    setWorkflowSessionDir: () => {},
+    setWorkflowSessionId: () => {},
+    setWorkflowTaskIds: () => {},
+    spawnSubagentParallel: async () => [],
+    _getMessages: () => messages,
+    _getStreaming: () => streaming,
+    ...overrides,
+  };
+}
+
+describe("executeWorkflow Ctrl+C integration", () => {
+  test("propagates abort signal to node execution and exits as cancellation", async () => {
+    let observedNodeAbortSignal: AbortSignal | undefined;
+    const workflowAbortController = new AbortController();
+    const context = createMockContext();
+
+    const compiledGraph = compileGraphConfig<BaseState>({
+      nodes: [
+        {
+          id: "spawn-node",
+          type: "tool",
+          execute: async (ctx) => {
+            observedNodeAbortSignal = ctx.abortSignal;
+            await new Promise((resolve) => setTimeout(resolve, 75));
+            if (ctx.abortSignal?.aborted) {
+              throw new Error("Workflow cancelled");
+            }
+            throw new Error("Abort signal was not propagated to node execution");
+          },
+        },
+      ],
+      edges: [],
+      startNode: "spawn-node",
+    });
+
+    const executionPromise = executeWorkflow(
+      {
+        name: "ctrlc-workflow",
+        description: "Abort chain integration test",
+      },
+      "run",
+      context as unknown as Parameters<typeof executeWorkflow>[2],
+      {
+        compiledGraph,
+        abortSignal: workflowAbortController.signal,
+      },
+    );
+
+    setTimeout(() => workflowAbortController.abort(), 25);
+
+    const result = await Promise.race([
+      executionPromise,
+      new Promise<never>((_resolve, reject) => {
+        setTimeout(() => reject(new Error("workflow did not abort in time")), 7_500);
+      }),
+    ]);
+
+    expect(result.success).toBe(true);
+    expect(observedNodeAbortSignal).toBe(workflowAbortController.signal);
+    expect(context._getStreaming()).toBe(false);
+    expect(
+      context._getMessages().some((m: { content: string }) =>
+        m.content.toLowerCase().includes("workflow failed"),
+      ),
+    ).toBe(false);
+  });
+});
diff --git a/src/workflows/executor.test.ts b/src/workflows/executor.test.ts
new file mode 100644
index 0000000000..8662b7211a
--- /dev/null
+++ b/src/workflows/executor.test.ts
@@ -0,0 +1,1628 @@
+/**
+ * Unit tests for workflow executor utilities
+ */
+
+import { describe, expect, test } from "bun:test";
+import {
+    compileGraphConfig,
+    inferHasSubagentNodes,
+    inferHasTaskList,
+    createSubagentRegistry,
+    executeWorkflow,
+} from "./executor.ts";
+import type { WorkflowGraphConfig } from "../ui/commands/workflow-commands.ts";
+import type { BaseState, NodeDefinition } from "./graph/types.ts";
+import {
+    getRuntimeParityMetricsSnapshot,
+    resetRuntimeParityMetrics,
+} from "./runtime-parity-observability.ts";
+
+describe("compileGraphConfig", () => {
+    test("converts node array to Map", () => {
+        interface TestState extends BaseState {
+            value: string;
+        }
+
+        const graphConfig: WorkflowGraphConfig<TestState> = {
+            nodes: [
+                {
+                    id: "node1",
+                    type: "agent",
+                    execute: async () => ({ stateUpdate: { value: "test" } as Partial<TestState> }),
+                },
+                {
+                    id: "node2",
+                    type: "tool",
+                    execute: async () => ({ stateUpdate: { value: "test2" } as Partial<TestState> }),
+                },
+            ],
+            edges: [{ from: "node1", to: "node2" }],
+            startNode: "node1",
+        };
+
+        const compiled = compileGraphConfig(graphConfig);
+
+        expect(compiled.nodes.size).toBe(2);
+        expect(compiled.nodes.has("node1")).toBe(true);
+        expect(compiled.nodes.has("node2")).toBe(true);
+        expect(compiled.nodes.get("node1")?.type).toBe("agent");
+        expect(compiled.nodes.get("node2")?.type).toBe("tool");
+    });
+
+    test("detects end nodes correctly", () => {
+        interface TestState extends BaseState {
+            value: string;
+        }
+
+        const graphConfig: WorkflowGraphConfig<TestState> = {
+            nodes: [
+                {
+                    id: "start",
+                    type: "agent",
+                    execute: async () => ({ stateUpdate: { value: "start" } as Partial<TestState> }),
+                },
+                {
+                    id: "middle",
+                    type: "tool",
+                    execute: async () => ({ stateUpdate: { value: "middle" } as Partial<TestState> }),
+                },
+                {
+                    id: "end",
+                    type: "agent",
+                    execute: async () => ({ stateUpdate: { value: "end" } as Partial<TestState> }),
+                },
+            ],
+            edges: [
+                { from: "start", to: "middle" },
+                { from: "middle", to: "end" },
+            ],
+            startNode: "start",
+        };
+
+        const compiled = compileGraphConfig(graphConfig);
+
+        expect(compiled.endNodes.size).toBe(1);
+        expect(compiled.endNodes.has("end")).toBe(true);
+        expect(compiled.endNodes.has("start")).toBe(false);
+        expect(compiled.endNodes.has("middle")).toBe(false);
+    });
+
+    test("handles multiple end nodes", () => {
+        interface TestState extends BaseState {
+            value: string;
+        }
+
+        const graphConfig: WorkflowGraphConfig<TestState> = {
+            nodes: [
+                {
+                    id: "start",
+                    type: "agent",
+                    execute: async () => ({ stateUpdate: { value: "start" } as Partial<TestState> }),
+                },
+                {
+                    id: "end1",
+                    type: "tool",
+                    execute: async () => ({ stateUpdate: { value: "end1" } as Partial<TestState> }),
+                },
+                {
+                    id: "end2",
+                    type: "agent",
+                    execute: async () => ({ stateUpdate: { value: "end2" } as Partial<TestState> }),
+                },
+            ],
+            edges: [
+                { from: "start", to: "end1" },
+                { from: "start", to: "end2" },
+            ],
+            startNode: "start",
+        };
+
+        const compiled = compileGraphConfig(graphConfig);
+
+        expect(compiled.endNodes.size).toBe(2);
+        expect(compiled.endNodes.has("end1")).toBe(true);
+        expect(compiled.endNodes.has("end2")).toBe(true);
+    });
+
+    test("sets startNode correctly", () => {
+        interface TestState extends BaseState {
+            value: string;
+        }
+
+        const graphConfig: WorkflowGraphConfig<TestState> = {
+            nodes: [
+                {
+                    id: "myStart",
+                    type: "agent",
+                    execute: async () => ({ stateUpdate: { value: "start" } as Partial<TestState> }),
+                },
+            ],
+            edges: [],
+            startNode: "myStart",
+        };
+
+        const compiled = compileGraphConfig(graphConfig);
+
+        expect(compiled.startNode).toBe("myStart");
+    });
+
+    test("copies edges array", () => {
+        interface TestState extends BaseState {
+            value: string;
+        }
+
+        const graphConfig: WorkflowGraphConfig<TestState> = {
+            nodes: [
+                {
+                    id: "node1",
+                    type: "agent",
+                    execute: async () => ({ stateUpdate: { value: "test" } as Partial<TestState> }),
+                },
+                {
+                    id: "node2",
+                    type: "tool",
+                    execute: async () => ({ stateUpdate: { value: "test2" } as Partial<TestState> }),
+                },
+            ],
+            edges: [{ from: "node1", to: "node2" }],
+            startNode: "node1",
+        };
+
+        const compiled = compileGraphConfig(graphConfig);
+
+        expect(compiled.edges).toHaveLength(1);
+        expect(compiled.edges[0]?.from).toBe("node1");
+        expect(compiled.edges[0]?.to).toBe("node2");
+        // Verify it's a copy, not the same array
+        expect(compiled.edges).not.toBe(graphConfig.edges);
+    });
+
+    test("sets maxIterations in config metadata", () => {
+        interface TestState extends BaseState {
+            value: string;
+        }
+
+        const graphConfig: WorkflowGraphConfig<TestState> = {
+            nodes: [
+                {
+                    id: "node1",
+                    type: "agent",
+                    execute: async () => ({ stateUpdate: { value: "test" } as Partial<TestState> }),
+                },
+            ],
+            edges: [],
+            startNode: "node1",
+            maxIterations: 50,
+        };
+
+        const compiled = compileGraphConfig(graphConfig);
+
+        expect(compiled.config.metadata?.maxIterations).toBe(50);
+    });
+
+    test("omits metadata when maxIterations is undefined", () => {
+        interface TestState extends BaseState {
+            value: string;
+        }
+
+        const graphConfig: WorkflowGraphConfig<TestState> = {
+            nodes: [
+                {
+                    id: "node1",
+                    type: "agent",
+                    execute: async () => ({ stateUpdate: { value: "test" } as Partial<TestState> }),
+                },
+            ],
+            edges: [],
+            startNode: "node1",
+        };
+
+        const compiled = compileGraphConfig(graphConfig);
+
+        expect(compiled.config.metadata).toBeUndefined();
+    });
+});
+
+describe("inferHasSubagentNodes", () => {
+    test("detects agent type nodes", () => {
+        interface TestState extends BaseState {
+            value: string;
+        }
+
+        const compiled = compileGraphConfig({
+            nodes: [
+                {
+                    id: "agent1",
+                    type: "agent" as const,
+                    execute: async () => ({ stateUpdate: { value: "test" } as Partial<TestState> }),
+                },
+            ],
+            edges: [],
+            startNode: "agent1",
+        });
+
+        expect(inferHasSubagentNodes(compiled)).toBe(true);
+    });
+
+    test("detects subagent in node ID", () => {
+        interface TestState extends BaseState {
+            value: string;
+        }
+
+        const compiled = compileGraphConfig({
+            nodes: [
+                {
+                    id: "my-subagent-node",
+                    type: "tool" as const,
+                    execute: async () => ({ stateUpdate: { value: "test" } as Partial<TestState> }),
+                },
+            ],
+            edges: [],
+            startNode: "my-subagent-node",
+        });
+
+        expect(inferHasSubagentNodes(compiled)).toBe(true);
+    });
+
+    test("returns false when no subagent nodes", () => {
+        interface TestState extends BaseState {
+            value: string;
+        }
+
+        const compiled = compileGraphConfig({
+            nodes: [
+                {
+                    id: "tool1",
+                    type: "tool" as const,
+                    execute: async () => ({ stateUpdate: { value: "test" } as Partial<TestState> }),
+                },
+            ],
+            edges: [],
+            startNode: "tool1",
+        });
+
+        expect(inferHasSubagentNodes(compiled)).toBe(false);
+    });
+});
+
+describe("inferHasTaskList", () => {
+    test("returns true when metadata.hasTaskList is true", () => {
+        interface TestState extends BaseState {
+            value: string;
+        }
+
+        const compiled = compileGraphConfig({
+            nodes: [
+                {
+                    id: "node1",
+                    type: "agent" as const,
+                    execute: async () => ({ stateUpdate: { value: "test" } as Partial<TestState> }),
+                },
+            ],
+            edges: [],
+            startNode: "node1",
+        });
+
+        // Manually set metadata for testing
+        compiled.config.metadata = { hasTaskList: true };
+
+        expect(inferHasTaskList(compiled)).toBe(true);
+    });
+
+    test("returns false when metadata.hasTaskList is false", () => {
+        interface TestState extends BaseState {
+            value: string;
+        }
+
+        const compiled = compileGraphConfig({
+            nodes: [
+                {
+                    id: "node1",
+                    type: "agent" as const,
+                    execute: async () => ({ stateUpdate: { value: "test" } as Partial<TestState> }),
+                },
+            ],
+            edges: [],
+            startNode: "node1",
+        });
+
+        // Manually set metadata for testing
+        compiled.config.metadata = { hasTaskList: false };
+
+        expect(inferHasTaskList(compiled)).toBe(false);
+    });
+
+    test("returns false when metadata is undefined", () => {
+        interface TestState extends BaseState {
+            value: string;
+        }
+
+        const compiled = compileGraphConfig({
+            nodes: [
+                {
+                    id: "node1",
+                    type: "agent" as const,
+                    execute: async () => ({ stateUpdate: { value: "test" } as Partial<TestState> }),
+                },
+            ],
+            edges: [],
+            startNode: "node1",
+        });
+
+        expect(inferHasTaskList(compiled)).toBe(false);
+    });
+});
+
+describe("createSubagentRegistry", () => {
+    test("creates a SubagentTypeRegistry", () => {
+        const registry = createSubagentRegistry();
+
+        expect(registry).toBeDefined();
+        // Verify it's the right type by checking for methods
+        expect(typeof registry.register).toBe("function");
+        expect(typeof registry.get).toBe("function");
+    });
+
+    test("populates registry with discovered agents", () => {
+        const registry = createSubagentRegistry();
+
+        // Should have at least the built-in agents
+        const allAgents = registry.getAll();
+        expect(allAgents.length).toBeGreaterThan(0);
+
+        // Check for some expected agents (actual names may vary by environment)
+        const agentNames = allAgents.map((a) => a.name);
+        // Just verify we have some common agents
+        expect(agentNames.length).toBeGreaterThan(0);
+    });
+});
+
+describe("executeWorkflow", () => {
+    // Create a minimal CommandContext mock
+    function createMockContext() {
+        const messages: Array<{ role: string; content: string }> = [];
+        const todoItems: any[] = [];
+        let streaming = false;
+        let workflowState: any = {};
+        let workflowSessionDir: string | null = null;
+        let workflowSessionId: string | null = null;
+        let workflowTaskIds: Set<string> = new Set();
+
+        return {
+            session: null,
+            state: {
+                isStreaming: false,
+                messageCount: 0,
+            },
+            addMessage: (role: string, content: string) => {
+                messages.push({ role, content });
+            },
+            setStreaming: (value: boolean) => {
+                streaming = value;
+            },
+            updateWorkflowState: (update: any) => {
+                workflowState = { ...workflowState, ...update };
+            },
+            setTodoItems: (items: any[]) => {
+                todoItems.push(...items);
+            },
+            setWorkflowSessionDir: (dir: string | null) => {
+                workflowSessionDir = dir;
+            },
+            setWorkflowSessionId: (id: string | null) => {
+                workflowSessionId = id;
+            },
+            setWorkflowTaskIds: (ids: Set<string>) => {
+                workflowTaskIds = ids;
+            },
+            spawnSubagentParallel: async () => [],
+            // Expose for testing
+            _getMessages: () => messages,
+            _getStreaming: () => streaming,
+            _getWorkflowState: () => workflowState,
+            _getSessionDir: () => workflowSessionDir,
+            _getSessionId: () => workflowSessionId,
+            _getTaskIds: () => workflowTaskIds,
+        };
+    }
+
+    test("returns error when no graphConfig or compiledGraph provided", async () => {
+        const context = createMockContext();
+        const definition = {
+            name: "test-workflow",
+            description: "Test workflow without graph",
+            command: "/test",
+            // No graphConfig or createState
+        };
+
+        const result = await executeWorkflow(definition, "test prompt", context as any);
+
+        expect(result.success).toBe(false);
+        expect(result.message).toContain("no graphConfig");
+        expect(context._getStreaming()).toBe(false);
+    });
+
+    test("successfully executes with a pre-compiled graph", async () => {
+        const context = createMockContext();
+        
+        interface TestState extends BaseState {
+            value: string;
+        }
+
+        // Create a simple compiled graph
+        const compiledGraph = compileGraphConfig<TestState>({
+            nodes: [
+                {
+                    id: "test-node",
+                    type: "tool",
+                    execute: async (ctx) => ({
+                        stateUpdate: { value: "executed" } as Partial<TestState>,
+                    }),
+                },
+            ],
+            edges: [],
+            startNode: "test-node",
+        });
+
+        const definition = {
+            name: "test-workflow",
+            description: "Test workflow with compiled graph",
+            command: "/test",
+        };
+
+        const result = await executeWorkflow(
+            definition,
+            "test prompt",
+            context as any,
+            { compiledGraph: compiledGraph as any }
+        );
+
+        expect(result.success).toBe(true);
+        expect(context._getStreaming()).toBe(false);
+        const messages = context._getMessages();
+        expect(messages.length).toBeGreaterThan(0);
+        expect(messages.some((m: any) => m.content.includes("Starting"))).toBe(true);
+        expect(messages.some((m: any) => m.content.includes("completed successfully"))).toBe(true);
+    });
+
+    test("uses nodeDescriptions for progress messages", async () => {
+        const context = createMockContext();
+        
+        interface TestState extends BaseState {
+            step: number;
+        }
+
+        const compiledGraph = compileGraphConfig<TestState>({
+            nodes: [
+                {
+                    id: "step1",
+                    type: "tool",
+                    execute: async (ctx) => ({
+                        stateUpdate: { step: 1 } as Partial<TestState>,
+                    }),
+                },
+                {
+                    id: "step2",
+                    type: "tool",
+                    execute: async (ctx) => ({
+                        stateUpdate: { step: 2 } as Partial<TestState>,
+                    }),
+                },
+            ],
+            edges: [{ from: "step1", to: "step2" }],
+            startNode: "step1",
+        });
+
+        const definition = {
+            name: "test-workflow",
+            description: "Test workflow with node descriptions",
+            command: "/test",
+            nodeDescriptions: {
+                step1: "Executing first step",
+                step2: "Executing second step",
+            },
+        };
+
+        const result = await executeWorkflow(
+            definition,
+            "test prompt",
+            context as any,
+            { compiledGraph: compiledGraph as any }
+        );
+
+        expect(result.success).toBe(true);
+        // Progress messages are now sent via bus events, not context.addMessage()
+        // Verify workflow still executes successfully with nodeDescriptions
+        const messages = context._getMessages();
+        expect(messages.some((m: any) => m.content.includes("Starting"))).toBe(true);
+        expect(messages.some((m: any) => m.content.includes("completed successfully"))).toBe(true);
+    });
+
+    test("threads workflow abort signal to subagent spawns", async () => {
+        const context = createMockContext();
+        const workflowAbortController = new AbortController();
+        let capturedParallelAbortSignal: AbortSignal | undefined;
+        let capturedAgentAbortSignal: AbortSignal | undefined;
+        let observedNodeAbortSignal: AbortSignal | undefined;
+
+        const contextWithCapture = {
+            ...context,
+            spawnSubagentParallel: async (agents: any[], abortSignal?: AbortSignal) => {
+                capturedParallelAbortSignal = abortSignal;
+                capturedAgentAbortSignal = agents[0]?.abortSignal;
+                return [{
+                    agentId: agents[0]?.agentId ?? "agent-1",
+                    success: true,
+                    output: "ok",
+                    toolUses: 0,
+                    durationMs: 1,
+                }];
+            },
+        };
+
+        interface TestState extends BaseState {
+            value: string;
+        }
+
+        const compiledGraph = compileGraphConfig<TestState>({
+            nodes: [
+                {
+                    id: "spawn-node",
+                    type: "tool",
+                    execute: async (ctx: any) => {
+                        observedNodeAbortSignal = ctx.abortSignal;
+                        const spawnSubagent = ctx.config.runtime?.spawnSubagent;
+                        if (!spawnSubagent) {
+                            throw new Error("spawnSubagent missing");
+                        }
+                        await spawnSubagent({
+                            agentId: "worker-1",
+                            agentName: "worker",
+                            task: "do work",
+                        });
+                        return { stateUpdate: { value: "done" } as Partial<TestState> };
+                    },
+                },
+            ],
+            edges: [],
+            startNode: "spawn-node",
+        });
+
+        const definition = {
+            name: "test-workflow",
+            description: "Abort signal propagation",
+            command: "/test",
+        };
+
+        const result = await executeWorkflow(
+            definition,
+            "test prompt",
+            contextWithCapture as any,
+            {
+                compiledGraph: compiledGraph as any,
+                abortSignal: workflowAbortController.signal,
+            },
+        );
+
+        expect(result.success).toBe(true);
+        expect(observedNodeAbortSignal).toBe(workflowAbortController.signal);
+        expect(capturedParallelAbortSignal).toBe(workflowAbortController.signal);
+        expect(capturedAgentAbortSignal).toBe(workflowAbortController.signal);
+    });
+
+    test("handles workflow cancellation error gracefully", async () => {
+        const context = createMockContext();
+        
+        interface TestState extends BaseState {
+            value: string;
+        }
+
+        // Create a graph that throws cancellation error
+        const compiledGraph = compileGraphConfig<TestState>({
+            nodes: [
+                {
+                    id: "cancel-node",
+                    type: "tool",
+                    execute: async () => {
+                        throw new Error("Workflow cancelled");
+                    },
+                },
+            ],
+            edges: [],
+            startNode: "cancel-node",
+        });
+
+        const definition = {
+            name: "test-workflow",
+            description: "Test workflow with cancellation",
+            command: "/test",
+        };
+
+        const result = await executeWorkflow(
+            definition,
+            "test prompt",
+            context as any,
+            { compiledGraph: compiledGraph as any }
+        );
+
+        // Should return success:true for cancellation (silent exit)
+        expect(result.success).toBe(true);
+        expect(context._getStreaming()).toBe(false);
+        expect(result.stateUpdate?.workflowActive).toBe(false);
+    });
+
+    test("returns failure message without adding a duplicate chat error line", async () => {
+        const context = createMockContext();
+
+        interface TestState extends BaseState {
+            value: string;
+        }
+
+        const compiledGraph = compileGraphConfig<TestState>({
+            nodes: [
+                {
+                    id: "failing-node",
+                    type: "tool",
+                    execute: async () => {
+                        throw new Error("Sub-agent \"reviewer\" failed: Claude Code process exited with code 1");
+                    },
+                },
+            ],
+            edges: [],
+            startNode: "failing-node",
+        });
+
+        const definition = {
+            name: "ralph",
+            description: "Test workflow failure surface",
+            command: "/ralph",
+        };
+
+        const result = await executeWorkflow(
+            definition,
+            "test prompt",
+            context as any,
+            { compiledGraph: compiledGraph as any },
+        );
+
+        expect(result.success).toBe(false);
+        expect(result.message).toBeUndefined();
+
+        const messages = context._getMessages();
+        const failureLines = messages.filter((m: { content: string }) =>
+            m.content.toLowerCase().includes("workflow failed at node"),
+        );
+        expect(failureLines).toHaveLength(1);
+        expect(failureLines[0]?.role).toBe("system");
+    });
+
+    test("creates state using createState factory when provided", async () => {
+        const context = createMockContext();
+        
+        interface TestState extends BaseState {
+            customValue: string;
+            sessionId: string;
+        }
+
+        let capturedParams: any = null;
+
+        const definition = {
+            name: "test-workflow",
+            description: "Test workflow with state factory",
+            command: "/test",
+            graphConfig: {
+                nodes: [
+                    {
+                        id: "test-node",
+                        type: "tool" as const,
+                        execute: async (ctx: any) => {
+                            // Verify state was created with factory
+                            expect((ctx.state as TestState).customValue).toBe("factory-created");
+                            return { stateUpdate: {} };
+                        },
+                    },
+                ],
+                edges: [],
+                startNode: "test-node",
+            },
+            createState: (params: any) => {
+                capturedParams = params;
+                return {
+                    executionId: params.sessionId,
+                    lastUpdated: new Date().toISOString(),
+                    outputs: {},
+                    customValue: "factory-created",
+                    sessionId: params.sessionId,
+                } as TestState;
+            },
+        };
+
+        const result = await executeWorkflow(
+            definition as any,
+            "test prompt",
+            context as any
+        );
+
+        expect(result.success).toBe(true);
+        expect(capturedParams).not.toBeNull();
+        expect(capturedParams.prompt).toBe("test prompt");
+        expect(capturedParams.sessionId).toBeDefined();
+        expect(capturedParams.sessionDir).toBeDefined();
+        expect(capturedParams.maxIterations).toBe(100); // DEFAULT_MAX_ITERATIONS
+    });
+
+    test("injects resolved runtime feature flags into graph runtime config", async () => {
+        const context = createMockContext();
+
+        interface TestState extends BaseState {
+            value: string;
+        }
+
+        let capturedFlags: unknown;
+        const compiledGraph = compileGraphConfig<TestState>({
+            nodes: [
+                {
+                    id: "feature-node",
+                    type: "tool",
+                    execute: async (ctx: any) => {
+                        capturedFlags = (ctx.config.runtime as any)?.featureFlags;
+                        return { stateUpdate: { value: "done" } as Partial<TestState> };
+                    },
+                },
+            ],
+            edges: [],
+            startNode: "feature-node",
+        });
+
+        const definition = {
+            name: "test-workflow",
+            description: "Feature flags test",
+            command: "/test",
+            runtime: {
+                featureFlags: {
+                    emitTaskStatusEvents: false,
+                },
+            },
+        };
+
+        const result = await executeWorkflow(
+            definition as any,
+            "test prompt",
+            context as any,
+            {
+                compiledGraph: compiledGraph as any,
+                featureFlags: {
+                    strictTaskContract: true,
+                },
+            },
+        );
+
+        expect(result.success).toBe(true);
+        expect(capturedFlags).toEqual({
+            emitTaskStatusEvents: false,
+            persistTaskStatusEvents: true,
+            strictTaskContract: true,
+        });
+    });
+
+    test("does not inject notifyTaskStatusChange when task status events are disabled", async () => {
+        const context = createMockContext();
+
+        interface TestState extends BaseState {
+            value: string;
+        }
+
+        let capturedNotifyFn: unknown;
+        const compiledGraph = compileGraphConfig<TestState>({
+            nodes: [
+                {
+                    id: "notify-node",
+                    type: "tool",
+                    execute: async (ctx: any) => {
+                        capturedNotifyFn = (ctx.config.runtime as any)?.notifyTaskStatusChange;
+                        return { stateUpdate: { value: "done" } as Partial<TestState> };
+                    },
+                },
+            ],
+            edges: [],
+            startNode: "notify-node",
+        });
+
+        const mockEventBus = {
+            publish: () => {},
+            on: () => () => {},
+            onAll: () => () => {},
+            clear: () => {},
+            hasHandlers: () => false,
+            get handlerCount() { return 0; },
+        };
+
+        const definition = {
+            name: "test-workflow",
+            description: "Disable status events",
+            command: "/test",
+            runtime: {
+                featureFlags: {
+                    emitTaskStatusEvents: false,
+                },
+            },
+        };
+
+        const result = await executeWorkflow(
+            definition as any,
+            "test prompt",
+            context as any,
+            {
+                compiledGraph: compiledGraph as any,
+                eventBus: mockEventBus as any,
+            },
+        );
+
+        expect(result.success).toBe(true);
+        expect(capturedNotifyFn).toBeUndefined();
+    });
+
+    test("debounces saveTasksToSession calls", async () => {
+        const context = createMockContext();
+        const saveCalls: Array<{ tasks: any[]; sessionId: string }> = [];
+        const saveTasksToSession = async (tasks: any[], sessionId: string) => {
+            saveCalls.push({ tasks, sessionId });
+        };
+        
+        interface TestState extends BaseState {
+            tasks: Array<{ id: string; content: string; status: string; activeForm: string }>;
+        }
+
+        // Create a graph that yields state with tasks across multiple steps
+        const compiledGraph = compileGraphConfig<TestState>({
+            nodes: [
+                {
+                    id: "step1",
+                    type: "tool",
+                    execute: async () => ({
+                        stateUpdate: {
+                            tasks: [
+                                { id: "t1", content: "Task 1", status: "pending", activeForm: "Task 1" },
+                            ],
+                        } as Partial<TestState>,
+                    }),
+                },
+                {
+                    id: "step2",
+                    type: "tool",
+                    execute: async () => ({
+                        stateUpdate: {
+                            tasks: [
+                                { id: "t1", content: "Task 1", status: "in_progress", activeForm: "Task 1" },
+                            ],
+                        } as Partial<TestState>,
+                    }),
+                },
+            ],
+            edges: [{ from: "step1", to: "step2" }],
+            startNode: "step1",
+        });
+
+        const definition = {
+            name: "test-workflow",
+            description: "Test debounce",
+            command: "/test",
+        };
+
+        const result = await executeWorkflow(
+            definition,
+            "test prompt",
+            context as any,
+            { compiledGraph: compiledGraph as any, saveTasksToSession }
+        );
+
+        expect(result.success).toBe(true);
+        // The debounce + flush should have saved at least once (the flush at the end)
+        expect(saveCalls.length).toBeGreaterThanOrEqual(1);
+        // The last save should contain the final task state
+        const lastSave = saveCalls[saveCalls.length - 1]!;
+        expect(lastSave.tasks.length).toBeGreaterThan(0);
+    });
+
+    test("notifyTaskStatusChange publishes workflow.task.statusChange event on eventBus", async () => {
+        const context = createMockContext();
+        const publishedEvents: any[] = [];
+
+        // Minimal event bus mock that records published events
+        const mockEventBus = {
+            publish: (event: any) => {
+                publishedEvents.push(event);
+            },
+            on: (_type: string, _handler: any) => {
+                return () => {}; // unsubscribe noop
+            },
+            onAll: () => () => {},
+            clear: () => {},
+            hasHandlers: () => false,
+            get handlerCount() { return 0; },
+        };
+
+        interface TestState extends BaseState {
+            value: string;
+        }
+
+        // Capture the notifyTaskStatusChange from runtime config
+        let capturedNotifyFn: any = null;
+        const compiledGraph = compileGraphConfig<TestState>({
+            nodes: [
+                {
+                    id: "test-node",
+                    type: "tool",
+                    execute: async (ctx: any) => {
+                        // Capture the notifyTaskStatusChange from runtime
+                        capturedNotifyFn = (ctx.config.runtime as any)?.notifyTaskStatusChange;
+                        return { stateUpdate: { value: "done" } as Partial<TestState> };
+                    },
+                },
+            ],
+            edges: [],
+            startNode: "test-node",
+        });
+
+        const definition = {
+            name: "test-workflow",
+            description: "Test notify",
+            command: "/test",
+        };
+
+        await executeWorkflow(
+            definition,
+            "test prompt",
+            context as any,
+            { compiledGraph: compiledGraph as any, eventBus: mockEventBus as any }
+        );
+
+        // Verify notifyTaskStatusChange was injected
+        expect(capturedNotifyFn).toBeDefined();
+        expect(typeof capturedNotifyFn).toBe("function");
+
+        // Call it and verify the event is published
+        capturedNotifyFn(
+            ["task-1", "task-2"],
+            "in_progress",
+            [
+                { id: "task-1", title: "First", status: "in_progress" },
+                { id: "task-2", title: "Second", status: "in_progress" },
+            ],
+        );
+
+        // Find the statusChange event among published events
+        const statusChangeEvents = publishedEvents.filter(
+            (e) => e.type === "workflow.task.statusChange"
+        );
+        expect(statusChangeEvents.length).toBe(1);
+        expect(statusChangeEvents[0].data.taskIds).toEqual(["task-1", "task-2"]);
+        expect(statusChangeEvents[0].data.newStatus).toBe("in_progress");
+        expect(statusChangeEvents[0].data.tasks).toHaveLength(2);
+    });
+
+    test("subscribes to workflow.task.statusChange and debounce-saves tasks", async () => {
+        const context = createMockContext();
+        const saveCalls: Array<{ tasks: any[]; sessionId: string }> = [];
+        const saveTasksToSession = async (tasks: any[], sessionId: string) => {
+            saveCalls.push({ tasks, sessionId });
+        };
+
+        // Track subscriptions to verify subscriber is registered
+        const subscriptions: Array<{ type: string; handler: any }> = [];
+        let unsubscribeCalled = false;
+
+        const mockEventBus = {
+            publish: (event: any) => {
+                // When a statusChange event is published, call the registered handler
+                for (const sub of subscriptions) {
+                    if (sub.type === event.type) {
+                        sub.handler(event);
+                    }
+                }
+            },
+            on: (type: string, handler: any) => {
+                subscriptions.push({ type, handler });
+                return () => { unsubscribeCalled = true; };
+            },
+            onAll: () => () => {},
+            clear: () => {},
+            hasHandlers: () => false,
+            get handlerCount() { return 0; },
+        };
+
+        interface TestState extends BaseState {
+            value: string;
+        }
+
+        const compiledGraph = compileGraphConfig<TestState>({
+            nodes: [
+                {
+                    id: "test-node",
+                    type: "tool",
+                    execute: async (ctx: any) => {
+                        // Simulate the worker node calling notifyTaskStatusChange
+                        const notifyFn = (ctx.config.runtime as any)?.notifyTaskStatusChange;
+                        if (notifyFn) {
+                            notifyFn(
+                                ["t1"],
+                                "in_progress",
+                                [{ id: "t1", title: "Task 1", status: "in_progress" }],
+                            );
+                        }
+                        return { stateUpdate: { value: "done" } as Partial<TestState> };
+                    },
+                },
+            ],
+            edges: [],
+            startNode: "test-node",
+        });
+
+        const definition = {
+            name: "test-workflow",
+            description: "Test subscriber",
+            command: "/test",
+        };
+
+        const result = await executeWorkflow(
+            definition,
+            "test prompt",
+            context as any,
+            {
+                compiledGraph: compiledGraph as any,
+                eventBus: mockEventBus as any,
+                saveTasksToSession,
+            }
+        );
+
+        expect(result.success).toBe(true);
+
+        // Verify the statusChange subscriber was registered
+        const statusChangeSubs = subscriptions.filter(
+            (s) => s.type === "workflow.task.statusChange"
+        );
+        expect(statusChangeSubs.length).toBe(1);
+
+        // Verify unsubscribe was called on completion
+        expect(unsubscribeCalled).toBe(true);
+
+        // The debounced save should have been called (via debounce timer or flush)
+        // Wait for any pending debounce timers
+        await new Promise((resolve) => setTimeout(resolve, 150));
+        expect(saveCalls.length).toBeGreaterThanOrEqual(1);
+
+        // Verify normalized data structure
+        const lastSave = saveCalls[saveCalls.length - 1]!;
+        expect(lastSave.tasks[0]).toMatchObject({
+            id: "t1",
+            content: "Task 1",
+            status: "in_progress",
+            activeForm: "Task 1",
+        });
+    });
+
+    test("preserves blockedBy when subsequent statusChange snapshots omit it", async () => {
+        const context = createMockContext();
+        const saveCalls: Array<{ tasks: any[]; sessionId: string }> = [];
+        const saveTasksToSession = async (tasks: any[], sessionId: string) => {
+            saveCalls.push({ tasks, sessionId });
+        };
+
+        const subscriptions: Array<{ type: string; handler: any }> = [];
+        const mockEventBus = {
+            publish: (event: any) => {
+                for (const sub of subscriptions) {
+                    if (sub.type === event.type) {
+                        sub.handler(event);
+                    }
+                }
+            },
+            on: (type: string, handler: any) => {
+                subscriptions.push({ type, handler });
+                return () => {};
+            },
+            onAll: () => () => {},
+            clear: () => {},
+            hasHandlers: () => false,
+            get handlerCount() { return 0; },
+        };
+
+        interface TestState extends BaseState {
+            value: string;
+        }
+
+        const compiledGraph = compileGraphConfig<TestState>({
+            nodes: [
+                {
+                    id: "test-node",
+                    type: "tool",
+                    execute: async (ctx: any) => {
+                        const notifyFn = (ctx.config.runtime as any)?.notifyTaskStatusChange;
+                        if (notifyFn) {
+                            notifyFn(
+                                ["#2"],
+                                "pending",
+                                [
+                                    { id: "#1", title: "Task 1", status: "completed", blockedBy: [] },
+                                    { id: "#2", title: "Task 2", status: "pending", blockedBy: ["#1"] },
+                                ],
+                            );
+                            notifyFn(
+                                ["2"],
+                                "in_progress",
+                                [
+                                    { id: "#1", title: "Task 1", status: "completed" },
+                                    { id: "2", title: "Task 2", status: "in_progress" },
+                                ],
+                            );
+                        }
+                        return { stateUpdate: { value: "done" } as Partial<TestState> };
+                    },
+                },
+            ],
+            edges: [],
+            startNode: "test-node",
+        });
+
+        const definition = {
+            name: "test-workflow",
+            description: "Test blockedBy preservation",
+            command: "/test",
+        };
+
+        const result = await executeWorkflow(
+            definition,
+            "test prompt",
+            context as any,
+            {
+                compiledGraph: compiledGraph as any,
+                eventBus: mockEventBus as any,
+                saveTasksToSession,
+            },
+        );
+
+        expect(result.success).toBe(true);
+        await new Promise((resolve) => setTimeout(resolve, 150));
+        expect(saveCalls.length).toBeGreaterThanOrEqual(1);
+
+        const lastSave = saveCalls[saveCalls.length - 1]!;
+        const task2 = lastSave.tasks.find((task: any) => task.id === "2" || task.id === "#2");
+        expect(task2).toBeDefined();
+        expect(task2.blockedBy).toEqual(["#1"]);
+    });
+
+    test("backfills task identity metadata when status snapshots are legacy", async () => {
+        const context = createMockContext();
+        const saveCalls: Array<{ tasks: any[]; sessionId: string }> = [];
+        const saveTasksToSession = async (tasks: any[], sessionId: string) => {
+            saveCalls.push({ tasks, sessionId });
+        };
+
+        const subscriptions: Array<{ type: string; handler: any }> = [];
+        const mockEventBus = {
+            publish: (event: any) => {
+                for (const sub of subscriptions) {
+                    if (sub.type === event.type) {
+                        sub.handler(event);
+                    }
+                }
+            },
+            on: (type: string, handler: any) => {
+                subscriptions.push({ type, handler });
+                return () => {};
+            },
+            onAll: () => () => {},
+            clear: () => {},
+            hasHandlers: () => false,
+            get handlerCount() { return 0; },
+        };
+
+        interface TestState extends BaseState {
+            value: string;
+        }
+
+        const compiledGraph = compileGraphConfig<TestState>({
+            nodes: [
+                {
+                    id: "test-node",
+                    type: "tool",
+                    execute: async (ctx: any) => {
+                        const notifyFn = (ctx.config.runtime as any)?.notifyTaskStatusChange;
+                        notifyFn?.(
+                            ["#7"],
+                            "in_progress",
+                            [{ id: "#7", title: "Legacy Task", status: "in_progress" }],
+                        );
+                        return { stateUpdate: { value: "done" } as Partial<TestState> };
+                    },
+                },
+            ],
+            edges: [],
+            startNode: "test-node",
+        });
+
+        const definition = {
+            name: "test-workflow",
+            description: "Task identity backfill",
+            command: "/test",
+        };
+
+        const result = await executeWorkflow(
+            definition,
+            "test prompt",
+            context as any,
+            {
+                compiledGraph: compiledGraph as any,
+                eventBus: mockEventBus as any,
+                saveTasksToSession,
+            },
+        );
+
+        expect(result.success).toBe(true);
+        await new Promise((resolve) => setTimeout(resolve, 150));
+
+        const lastSave = saveCalls[saveCalls.length - 1];
+        expect(lastSave).toBeDefined();
+        const task = lastSave?.tasks[0];
+        expect(task.identity?.canonicalId).toBe("#7");
+        expect(task.identity?.providerBindings?.task_id).toContain("#7");
+    });
+
+    test("persists task result envelopes from status snapshots", async () => {
+        resetRuntimeParityMetrics();
+        const context = createMockContext();
+        const saveCalls: Array<{ tasks: any[]; sessionId: string }> = [];
+        const saveTasksToSession = async (tasks: any[], sessionId: string) => {
+            saveCalls.push({ tasks, sessionId });
+        };
+
+        const subscriptions: Array<{ type: string; handler: any }> = [];
+        const mockEventBus = {
+            publish: (event: any) => {
+                for (const sub of subscriptions) {
+                    if (sub.type === event.type) {
+                        sub.handler(event);
+                    }
+                }
+            },
+            on: (type: string, handler: any) => {
+                subscriptions.push({ type, handler });
+                return () => {};
+            },
+            onAll: () => () => {},
+            clear: () => {},
+            hasHandlers: () => false,
+            get handlerCount() { return 0; },
+        };
+
+        interface TestState extends BaseState {
+            value: string;
+        }
+
+        const compiledGraph = compileGraphConfig<TestState>({
+            nodes: [
+                {
+                    id: "test-node",
+                    type: "tool",
+                    execute: async (ctx: any) => {
+                        const notifyFn = (ctx.config.runtime as any)?.notifyTaskStatusChange;
+                        notifyFn?.(
+                            ["#12"],
+                            "completed",
+                            [{
+                                id: "#12",
+                                title: "Persist envelope",
+                                status: "completed",
+                                identity: {
+                                    canonicalId: "#12",
+                                    providerBindings: {
+                                        subagent_id: ["worker-12"],
+                                    },
+                                },
+                                taskResult: {
+                                    task_id: "#12",
+                                    tool_name: "task",
+                                    title: "Persist envelope",
+                                    metadata: {
+                                        sessionId: "session-12",
+                                        providerBindings: {
+                                            subagent_id: "worker-12",
+                                        },
+                                    },
+                                    status: "completed",
+                                    output_text: "done",
+                                    envelope_text: "task_id: #12",
+                                },
+                            }],
+                        );
+                        return { stateUpdate: { value: "done" } as Partial<TestState> };
+                    },
+                },
+            ],
+            edges: [],
+            startNode: "test-node",
+        });
+
+        const definition = {
+            name: "test-workflow",
+            description: "Task result persistence",
+            command: "/test",
+        };
+
+        const result = await executeWorkflow(
+            definition,
+            "test prompt",
+            context as any,
+            {
+                compiledGraph: compiledGraph as any,
+                eventBus: mockEventBus as any,
+                saveTasksToSession,
+            },
+        );
+
+        expect(result.success).toBe(true);
+        await new Promise((resolve) => setTimeout(resolve, 150));
+
+        const lastSave = saveCalls[saveCalls.length - 1];
+        expect(lastSave).toBeDefined();
+        const task = lastSave?.tasks[0];
+        expect(task.taskResult).toMatchObject({
+            task_id: "#12",
+            tool_name: "task",
+            status: "completed",
+            metadata: {
+                providerBindings: {
+                    subagent_id: "worker-12",
+                },
+            },
+            output_text: "done",
+        });
+
+        const metrics = getRuntimeParityMetricsSnapshot();
+        expect(metrics.counters["workflow.runtime.parity.status_snapshot_total{phase=received,workflow=test-workflow}"]).toBe(1);
+        expect(metrics.counters["workflow.runtime.parity.status_snapshot_total{phase=persisted,workflow=test-workflow}"]).toBe(1);
+        expect(metrics.histograms["workflow.runtime.parity.status_snapshot_task_count{workflow=test-workflow}"]).toEqual([1]);
+    });
+
+    test("fails fast when task result task_id mismatches canonical identity", async () => {
+        resetRuntimeParityMetrics();
+        const context = createMockContext();
+
+        const subscriptions: Array<{ type: string; handler: any }> = [];
+        const mockEventBus = {
+            publish: (event: any) => {
+                for (const sub of subscriptions) {
+                    if (sub.type === event.type) {
+                        sub.handler(event);
+                    }
+                }
+            },
+            on: (type: string, handler: any) => {
+                subscriptions.push({ type, handler });
+                return () => {};
+            },
+            onAll: () => () => {},
+            clear: () => {},
+            hasHandlers: () => false,
+            get handlerCount() { return 0; },
+        };
+
+        interface TestState extends BaseState {
+            value: string;
+        }
+
+        const compiledGraph = compileGraphConfig<TestState>({
+            nodes: [
+                {
+                    id: "test-node",
+                    type: "tool",
+                    execute: async (ctx: any) => {
+                        const notifyFn = (ctx.config.runtime as any)?.notifyTaskStatusChange;
+                        notifyFn?.(
+                            ["#13"],
+                            "completed",
+                            [{
+                                id: "#13",
+                                title: "Mismatched envelope",
+                                status: "completed",
+                                identity: {
+                                    canonicalId: "#13",
+                                    providerBindings: {
+                                        subagent_id: ["worker-13"],
+                                    },
+                                },
+                                taskResult: {
+                                    task_id: "#14",
+                                    tool_name: "task",
+                                    title: "Mismatched envelope",
+                                    status: "completed",
+                                    output_text: "done",
+                                },
+                            }],
+                        );
+                        return { stateUpdate: { value: "done" } as Partial<TestState> };
+                    },
+                },
+            ],
+            edges: [],
+            startNode: "test-node",
+        });
+
+        const definition = {
+            name: "test-workflow",
+            description: "Task result mismatch",
+            command: "/test",
+        };
+
+        const result = await executeWorkflow(
+            definition,
+            "test prompt",
+            context as any,
+            {
+                compiledGraph: compiledGraph as any,
+                eventBus: mockEventBus as any,
+                saveTasksToSession: async () => {},
+            },
+        );
+
+        expect(result.success).toBe(false);
+        expect(
+            context
+                ._getMessages()
+                .some((m: { role: string; content: string }) =>
+                    m.role === "system" && m.content.includes("TaskResult envelope task_id mismatch: expected #13, received #14"),
+                ),
+        ).toBe(true);
+
+        const metrics = getRuntimeParityMetricsSnapshot();
+        expect(metrics.counters["workflow.runtime.parity.task_result_invariant_failures_total{reason=task_id_mismatch}"]).toBeGreaterThanOrEqual(1);
+        expect(metrics.counters["workflow.runtime.parity.task_result_normalization_failures_total{reason=invalid_envelope}"]).toBeGreaterThanOrEqual(1);
+        expect(metrics.counters["workflow.runtime.parity.execution_total{phase=failure,workflow=test-workflow}"]).toBe(1);
+    });
+
+    test("unsubscribes from statusChange events on error", async () => {
+        let unsubscribeCalled = false;
+
+        const mockEventBus = {
+            publish: () => {},
+            on: (_type: string, _handler: any) => {
+                return () => { unsubscribeCalled = true; };
+            },
+            onAll: () => () => {},
+            clear: () => {},
+            hasHandlers: () => false,
+            get handlerCount() { return 0; },
+        };
+
+        // Create a context where setWorkflowSessionDir throws to
+        // trigger the catch block after subscription is set up
+        const context = createMockContext();
+        const errorContext = {
+            ...context,
+            setWorkflowSessionDir: () => {
+                throw new Error("Session dir error");
+            },
+        };
+
+        interface TestState extends BaseState {
+            tasks: Array<{ id: string; content: string; status: string; activeForm: string }>;
+        }
+
+        // Graph that produces state with tasks, triggering setWorkflowSessionDir
+        const compiledGraph = compileGraphConfig<TestState>({
+            nodes: [
+                {
+                    id: "task-node",
+                    type: "tool",
+                    execute: async () => ({
+                        stateUpdate: {
+                            tasks: [
+                                { id: "t1", content: "Task 1", status: "pending", activeForm: "Task 1" },
+                            ],
+                        } as Partial<TestState>,
+                    }),
+                },
+            ],
+            edges: [],
+            startNode: "task-node",
+        });
+
+        const definition = {
+            name: "test-workflow",
+            description: "Test error cleanup",
+            command: "/test",
+        };
+
+        const result = await executeWorkflow(
+            definition,
+            "test prompt",
+            errorContext as any,
+            {
+                compiledGraph: compiledGraph as any,
+                eventBus: mockEventBus as any,
+                saveTasksToSession: async () => {},
+            }
+        );
+
+        // The setWorkflowSessionDir error causes the workflow to fail
+        expect(result.success).toBe(false);
+        expect(result.message).toBeUndefined();
+        expect(
+            context
+                ._getMessages()
+                .some((m: { role: string; content: string }) =>
+                    m.role === "system" && m.content.includes("Session dir error"),
+                ),
+        ).toBe(true);
+        // Verify unsubscribe was called even on error
+        expect(unsubscribeCalled).toBe(true);
+    });
+
+    test("publishes step completion status from actual terminal step state", async () => {
+        const context = createMockContext();
+        const publishedEvents: any[] = [];
+
+        const mockEventBus = {
+            publish: (event: any) => {
+                publishedEvents.push(event);
+            },
+            on: () => () => {},
+            onAll: () => () => {},
+            clear: () => {},
+            hasHandlers: () => false,
+            get handlerCount() { return 0; },
+        };
+
+        interface TestState extends BaseState {
+            value: string;
+        }
+
+        const compiledGraph = compileGraphConfig<TestState>({
+            nodes: [
+                {
+                    id: "step-1",
+                    type: "tool",
+                    execute: async () => ({
+                        stateUpdate: { value: "ok" } as Partial<TestState>,
+                    }),
+                },
+                {
+                    id: "step-2",
+                    type: "tool",
+                    execute: async () => {
+                        throw new Error("boom");
+                    },
+                },
+            ],
+            edges: [{ from: "step-1", to: "step-2" }],
+            startNode: "step-1",
+        });
+
+        const definition = {
+            name: "test-workflow",
+            description: "Step status parity",
+            command: "/test",
+        };
+
+        const result = await executeWorkflow(
+            definition,
+            "test prompt",
+            context as any,
+            {
+                compiledGraph: compiledGraph as any,
+                eventBus: mockEventBus as any,
+            },
+        );
+
+        expect(result.success).toBe(false);
+
+        const completionEvents = publishedEvents.filter(
+            (event) => event.type === "workflow.step.complete",
+        );
+        expect(completionEvents).toHaveLength(2);
+        expect(completionEvents[0].data.nodeId).toBe("step-1");
+        expect(completionEvents[0].data.status).toBe("success");
+        expect(completionEvents[1].data.nodeId).toBe("step-2");
+        expect(completionEvents[1].data.status).toBe("error");
+    });
+});
diff --git a/src/workflows/executor.ts b/src/workflows/executor.ts
new file mode 100644
index 0000000000..4b65cd4471
--- /dev/null
+++ b/src/workflows/executor.ts
@@ -0,0 +1,686 @@
+/**
+ * Generic workflow executor that replaces both createRalphCommand() and WorkflowSDK.
+ * Handles graph compilation, session initialization, state construction,
+ * bridge/registry setup, graph streaming with progress, and error handling.
+ */
+
+import type { BaseState, CompiledGraph, NodeDefinition, GraphConfig } from "./graph/types.ts";
+import { SubagentTypeRegistry } from "./graph/subagent-registry.ts";
+import { discoverAgentInfos } from "../ui/commands/agent-commands.ts";
+import { type WorkflowDefinition, type WorkflowGraphConfig, registerActiveSession } from "../ui/commands/workflow-commands.ts";
+import type { CommandContext, CommandResult } from "../ui/commands/registry.ts";
+import { streamGraph } from "./graph/compiled.ts";
+import {
+    initWorkflowSession,
+    getWorkflowSessionDir,
+} from "./session.ts";
+import type { NormalizedTodoItem, TaskStatus } from "../ui/utils/task-status.ts";
+import type { EventBus } from "../events/event-bus.ts";
+import { WorkflowEventAdapter } from "../events/adapters/workflow-adapter.ts";
+import {
+    resolveWorkflowRuntimeFeatureFlags,
+    toWorkflowRuntimeTask,
+    toWorkflowRuntimeTasks,
+    workflowRuntimeStrictTaskSchema,
+    type WorkflowRuntimeFeatureFlagOverrides,
+    type WorkflowRuntimeTask,
+} from "./runtime-contracts.ts";
+import { TaskIdentityService } from "./task-identity-service.ts";
+import {
+    incrementRuntimeParityCounter,
+    observeRuntimeParityHistogram,
+    runtimeParityDebug,
+} from "./runtime-parity-observability.ts";
+import { pipelineLog, pipelineError } from "../events/pipeline-logger.ts";
+
+/**
+ * Result of a workflow execution.
+ */
+export interface WorkflowExecutionResult {
+    success: boolean;
+    message?: string;
+    error?: Error;
+}
+
+/**
+ * Compiles a declarative WorkflowGraphConfig into a CompiledGraph.
+ * Converts node array to Map, detects end nodes, and builds the config.
+ */
+export function compileGraphConfig<TState extends BaseState>(
+    graphConfig: WorkflowGraphConfig<TState>,
+): CompiledGraph<TState> {
+    const nodeMap = new Map<string, NodeDefinition<TState>>();
+    for (const node of graphConfig.nodes) {
+        nodeMap.set(node.id, node);
+    }
+
+    // Detect end nodes: nodes with no outgoing edges
+    const nodesWithOutgoing = new Set(graphConfig.edges.map((e) => e.from));
+    const endNodes = new Set<string>();
+    for (const nodeId of nodeMap.keys()) {
+        if (!nodesWithOutgoing.has(nodeId)) {
+            endNodes.add(nodeId);
+        }
+    }
+
+    const config: GraphConfig<TState> = {};
+    if (graphConfig.maxIterations !== undefined) {
+        config.metadata = { maxIterations: graphConfig.maxIterations };
+    }
+
+    return {
+        nodes: nodeMap,
+        edges: [...graphConfig.edges],
+        startNode: graphConfig.startNode,
+        endNodes,
+        config,
+    };
+}
+
+/**
+ * Infers whether the compiled graph uses subagent nodes.
+ * Checks node types and IDs for subagent-related patterns.
+ */
+export function inferHasSubagentNodes<TState extends BaseState>(
+    compiled: CompiledGraph<TState>,
+): boolean {
+    for (const node of compiled.nodes.values()) {
+        if (
+            (node as NodeDefinition<TState>).type === "agent" ||
+            node.id.includes("subagent")
+        ) {
+            return true;
+        }
+    }
+    return false;
+}
+
+/**
+ * Infers whether the compiled graph's state schema includes a tasks field.
+ * Used to determine if the workflow supports task list UI updates.
+ */
+export function inferHasTaskList<TState extends BaseState>(
+    compiled: CompiledGraph<TState>,
+): boolean {
+    return compiled.config.metadata?.hasTaskList === true;
+}
+
+/**
+ * Creates and populates a SubagentTypeRegistry with discovered agent infos.
+ */
+export function createSubagentRegistry(): SubagentTypeRegistry {
+    const registry = new SubagentTypeRegistry();
+    for (const agent of discoverAgentInfos()) {
+        registry.register({
+            name: agent.name,
+            info: agent,
+            source: agent.source,
+        });
+    }
+    return registry;
+}
+
+/** Default max iterations for workflows */
+const DEFAULT_MAX_ITERATIONS = 100;
+
+/**
+ * Generic workflow executor that encapsulates the full execution lifecycle.
+ * Replaces the ~200-line createRalphCommand() with a reusable function.
+ *
+ * Handles: session init, state creation, graph compilation, bridge/registry
+ * setup, streaming with progress updates, task list sync, and error handling.
+ *
+ * @param definition - The workflow definition with metadata + execution config
+ * @param prompt - User's prompt text
+ * @param context - TUI CommandContext for UI updates
+ * @param options - Optional pre-compiled graph (for builder-pattern workflows like Ralph)
+ */
+export async function executeWorkflow(
+    definition: WorkflowDefinition,
+    prompt: string,
+    context: CommandContext,
+    options?: {
+        compiledGraph?: CompiledGraph<BaseState>;
+        saveTasksToSession?: (tasks: NormalizedTodoItem[], sessionId: string) => Promise<void>;
+        eventBus?: EventBus;
+        featureFlags?: WorkflowRuntimeFeatureFlagOverrides;
+        abortSignal?: AbortSignal;
+    },
+): Promise<CommandResult> {
+    // Phase 1: Session initialization
+    const sessionId = crypto.randomUUID();
+    const sessionDir = getWorkflowSessionDir(sessionId);
+    const workflowRunId = crypto.getRandomValues(new Uint32Array(1))[0]!;
+
+    // Construct WorkflowEventAdapter if event bus is available
+    const eventAdapter = options?.eventBus
+        ? new WorkflowEventAdapter(options.eventBus, sessionId, workflowRunId)
+        : undefined;
+
+    // Publish synthetic stream.session.start to register this session with the
+    // correlation pipeline so sub-agent events are recognized as owned.
+    if (options?.eventBus) {
+        options.eventBus.publish({
+            type: "stream.session.start",
+            sessionId,
+            runId: workflowRunId,
+            timestamp: Date.now(),
+            data: { config: { workflowName: definition.name } },
+        });
+    }
+
+    void initWorkflowSession(definition.name, sessionId).then((session) => {
+        registerActiveSession(session);
+    }).catch((err) => {
+        pipelineError("Workflow", "session_init_error", { workflow: definition.name, sessionId });
+        console.error("[workflow] Failed to initialize session:", err);
+    });
+
+    context.updateWorkflowState({
+        workflowActive: true,
+        workflowType: definition.name,
+        workflowConfig: { sessionId, userPrompt: prompt, workflowName: definition.name },
+    });
+
+    context.setStreaming(true);
+
+    let unsubscribeStatusChange: (() => void) | undefined;
+    pipelineLog("Workflow", "start", { workflow: definition.name, sessionId });
+    incrementRuntimeParityCounter("workflow.runtime.parity.execution_total", {
+        phase: "start",
+        workflow: definition.name,
+    });
+
+    try {
+        context.addMessage(
+            "assistant",
+            `Starting **${definition.name}** workflow with prompt: "${prompt}"`,
+        );
+
+        // Phase 2: Determine compiled graph
+        let compiled: CompiledGraph<BaseState>;
+        if (options?.compiledGraph) {
+            compiled = options.compiledGraph;
+        } else if (definition.graphConfig) {
+            compiled = compileGraphConfig(definition.graphConfig);
+        } else {
+            context.setStreaming(false);
+            return {
+                success: false,
+                message: `Workflow "${definition.name}" has no graphConfig or pre-compiled graph.`,
+                stateUpdate: {
+                    workflowActive: false,
+                    workflowType: null,
+                    initialPrompt: null,
+                },
+            };
+        }
+
+        // Phase 3: Create initial state
+        const maxIterations = definition.graphConfig?.maxIterations ?? DEFAULT_MAX_ITERATIONS;
+        const initialState = definition.createState
+            ? definition.createState({ prompt, sessionId, sessionDir, maxIterations })
+            : ({ executionId: sessionId, lastUpdated: new Date().toISOString(), outputs: {} } as BaseState);
+
+        const runtimeFeatureFlags = resolveWorkflowRuntimeFeatureFlags(
+            definition.runtime?.featureFlags,
+            options?.featureFlags,
+        );
+        const taskIdentity = new TaskIdentityService();
+        const workflowAbortSignal = options?.abortSignal ?? new AbortController().signal;
+
+        const toRuntimeTask = (task: unknown): WorkflowRuntimeTask => {
+            const normalized = toWorkflowRuntimeTask(task, () => crypto.randomUUID());
+            const withIdentity = taskIdentity.backfillTask(normalized);
+            return workflowRuntimeStrictTaskSchema.parse(withIdentity);
+        };
+
+        const toRuntimeTasks = (tasks: unknown): WorkflowRuntimeTask[] => {
+            const normalized = toWorkflowRuntimeTasks(tasks, () => crypto.randomUUID());
+            const strictTasks = normalized.map((task) => workflowRuntimeStrictTaskSchema.parse(task));
+            return taskIdentity.backfillTasks(strictTasks);
+        };
+
+        // Phase 4: Registry setup — pass TUI's spawnSubagentParallel directly
+        const registry = createSubagentRegistry();
+        const spawnFn = context.spawnSubagentParallel;
+        if (!spawnFn) {
+            throw new Error("spawnSubagentParallel is not available on CommandContext.");
+        }
+
+        compiled.config.runtime = {
+            ...compiled.config.runtime,
+            featureFlags: runtimeFeatureFlags,
+            spawnSubagent: async (agent, abortSignal) => {
+                const effectiveAbortSignal = agent.abortSignal ?? abortSignal ?? workflowAbortSignal;
+                // Publish agent start event if adapter is available
+                if (eventAdapter) {
+                    eventAdapter.publishAgentStart(
+                        agent.agentId,
+                        agent.agentName,
+                        agent.task,
+                        true, // Single workflow spawns also run as background agents
+                    );
+                }
+
+                const [result] = await spawnFn(
+                    [{ ...agent, abortSignal: effectiveAbortSignal }],
+                    effectiveAbortSignal,
+                );
+                if (!result) throw new Error("Subagent spawn returned no results");
+
+                // Publish agent complete event if adapter is available
+                if (eventAdapter) {
+                    eventAdapter.publishAgentComplete(
+                        agent.agentId,
+                        result.success,
+                        result.output,
+                        result.error,
+                    );
+                }
+
+                return result;
+            },
+            spawnSubagentParallel: async (agents, abortSignal) => {
+                const effectiveAbortSignal = abortSignal ?? workflowAbortSignal;
+                // Publish agent start events for all agents if adapter is available
+                if (eventAdapter) {
+                    for (const agent of agents) {
+                        eventAdapter.publishAgentStart(
+                            agent.agentId,
+                            agent.agentName,
+                            agent.task,
+                            true, // isBackground = true for parallel agent spawn
+                        );
+                    }
+                }
+
+                const results = await spawnFn(
+                    agents.map((agent) => ({
+                        ...agent,
+                        abortSignal: agent.abortSignal ?? effectiveAbortSignal,
+                    })),
+                    effectiveAbortSignal,
+                );
+
+                // Publish agent complete events for all agents if adapter is available
+                if (eventAdapter) {
+                    for (const result of results) {
+                        eventAdapter.publishAgentComplete(
+                            result.agentId,
+                            result.success,
+                            result.output,
+                            result.error,
+                        );
+                    }
+                }
+
+                return results;
+            },
+            taskIdentity,
+            subagentRegistry: registry,
+            notifyTaskStatusChange: options?.eventBus && runtimeFeatureFlags.emitTaskStatusEvents
+                ? (
+                    taskIds: string[],
+                    newStatus: string,
+                    tasks: WorkflowRuntimeTask[],
+                ) => {
+                    options.eventBus!.publish({
+                        type: "workflow.task.statusChange",
+                        sessionId,
+                        runId: workflowRunId,
+                        timestamp: Date.now(),
+                        data: {
+                            taskIds,
+                            newStatus,
+                            tasks: tasks.map(toRuntimeTask),
+                        },
+                    });
+                }
+                : undefined,
+        };
+
+        // Phase 5: Stream graph execution with progress
+        let sessionTracked = false;
+        let lastNodeId: string | null = null;
+        let lastNodeCompletionStatus: "success" | "error" | "skipped" = "success";
+        let lastStepStatus: string | null = null;
+        let lastStepError: string | undefined;
+        const nodeDescriptions = definition.nodeDescriptions;
+        const mapStepStatusToCompletionStatus = (
+            stepStatus: string,
+        ): "success" | "error" | "skipped" => {
+            switch (stepStatus) {
+                case "failed":
+                    return "error";
+                case "cancelled":
+                case "paused":
+                    return "skipped";
+                default:
+                    return "success";
+            }
+        };
+
+        // Debounced saveTasksToSession to avoid I/O contention during rapid updates
+        let saveDebounceTimer: ReturnType<typeof setTimeout> | null = null;
+        let pendingSaveTasks: NormalizedTodoItem[] | null = null;
+        const normalizeTaskKey = (taskId?: string): string | null => {
+            if (typeof taskId !== "string") return null;
+            const normalized = taskId.trim().toLowerCase().replace(/^#/, "");
+            return normalized.length > 0 ? normalized : null;
+        };
+        let latestWorkflowTasks: NormalizedTodoItem[] = [];
+        const debouncedSaveTasksToSession = options?.saveTasksToSession
+            ? (tasks: NormalizedTodoItem[], sid: string) => {
+                latestWorkflowTasks = tasks;
+                pendingSaveTasks = tasks;
+                if (saveDebounceTimer) clearTimeout(saveDebounceTimer);
+                saveDebounceTimer = setTimeout(async () => {
+                    if (pendingSaveTasks) {
+                        try {
+                            await options.saveTasksToSession!(pendingSaveTasks, sid);
+                        } catch (err) {
+                            pipelineError("Workflow", "task_save_error", { sessionId });
+                            console.error('[workflow] Failed to save tasks:', err);
+                        }
+                        pendingSaveTasks = null;
+                    }
+                    saveDebounceTimer = null;
+                }, 100);
+            }
+            : undefined;
+
+        // Subscribe to workflow.task.statusChange events for persistence.
+        // When a worker node publishes a status change (e.g., pending → in_progress)
+        // before spawning sub-agents, this subscriber persists the update immediately
+        // via the debounced save, so the file watcher can trigger UI updates.
+        if (
+            options?.eventBus &&
+            debouncedSaveTasksToSession &&
+            runtimeFeatureFlags.persistTaskStatusEvents
+        ) {
+            unsubscribeStatusChange = options.eventBus.on("workflow.task.statusChange", (event) => {
+                if (event.sessionId !== sessionId) return;
+                incrementRuntimeParityCounter("workflow.runtime.parity.status_snapshot_total", {
+                    phase: "received",
+                    workflow: definition.name,
+                });
+                runtimeParityDebug("status_snapshot_received", {
+                    sessionId,
+                    workflowRunId,
+                    workflow: definition.name,
+                    taskIds: event.data.taskIds,
+                    taskCount: event.data.tasks.length,
+                });
+
+                const runtimeTasks = toRuntimeTasks(event.data.tasks);
+                for (const runtimeTask of runtimeTasks) {
+                    const canonicalId = runtimeTask.identity?.canonicalId;
+                    if (!canonicalId || canonicalId.trim().length === 0) {
+                        incrementRuntimeParityCounter("workflow.runtime.parity.status_snapshot_failures_total", {
+                            reason: "missing_canonical_id",
+                            workflow: definition.name,
+                        });
+                        throw new Error(`workflow.task.statusChange invariant failed: task ${runtimeTask.id} missing canonical identity`);
+                    }
+
+                    if (runtimeTask.taskResult && runtimeTask.taskResult.task_id !== canonicalId) {
+                        incrementRuntimeParityCounter("workflow.runtime.parity.status_snapshot_failures_total", {
+                            reason: "task_result_identity_mismatch",
+                            workflow: definition.name,
+                        });
+                        throw new Error(
+                            `workflow.task.statusChange invariant failed: taskResult.task_id ${runtimeTask.taskResult.task_id} does not match canonical task identity ${canonicalId}`,
+                        );
+                    }
+                }
+
+                observeRuntimeParityHistogram(
+                    "workflow.runtime.parity.status_snapshot_task_count",
+                    runtimeTasks.length,
+                    { workflow: definition.name },
+                );
+
+                const previousById = new Map<string, NormalizedTodoItem>();
+                for (const task of latestWorkflowTasks) {
+                    const key = normalizeTaskKey(task.id);
+                    if (!key || previousById.has(key)) continue;
+                    previousById.set(key, task);
+                }
+
+                const normalized: NormalizedTodoItem[] = runtimeTasks.map((t) => {
+                    const taskKey = normalizeTaskKey(t.id);
+                    return {
+                        id: t.id,
+                        content: t.title,
+                        status: t.status as TaskStatus,
+                        activeForm: t.title,
+                        blockedBy: t.blockedBy
+                            ?? (taskKey ? previousById.get(taskKey)?.blockedBy : undefined),
+                        identity: t.identity,
+                        taskResult: t.taskResult,
+                    };
+                });
+                incrementRuntimeParityCounter("workflow.runtime.parity.status_snapshot_total", {
+                    phase: "persisted",
+                    workflow: definition.name,
+                });
+                debouncedSaveTasksToSession(normalized, sessionId);
+            });
+        }
+
+        for await (const step of streamGraph(compiled, { initialState, abortSignal: workflowAbortSignal })) {
+            const currentCompletionStatus = mapStepStatusToCompletionStatus(step.status);
+
+            // Track step status for failure detection
+            lastStepStatus = step.status;
+            lastStepError = step.error?.error instanceof Error ? step.error.error.message : step.error?.error;
+
+            // Show progress for node transitions
+            if (step.nodeId !== lastNodeId) {
+                const description = nodeDescriptions?.[step.nodeId];
+                
+                // Publish step complete event for previous node (if any)
+                if (lastNodeId !== null && eventAdapter) {
+                    eventAdapter.publishStepComplete(
+                        sessionId,
+                        nodeDescriptions?.[lastNodeId] ?? lastNodeId,
+                        lastNodeId,
+                        lastNodeCompletionStatus,
+                    );
+                }
+                
+                // Publish step start event for new node
+                if (eventAdapter) {
+                    eventAdapter.publishStepStart(
+                        sessionId,
+                        description ?? step.nodeId,
+                        step.nodeId,
+                    );
+                }
+                
+                lastNodeId = step.nodeId;
+            }
+
+            lastNodeCompletionStatus = currentCompletionStatus;
+
+            // Sync task list to UI and session
+            const state = step.state as BaseState & {
+                tasks?: Array<{
+                    id?: string;
+                    content: string;
+                    status: string;
+                    activeForm: string;
+                    blockedBy?: string[];
+                    identity?: WorkflowRuntimeTask["identity"];
+                    taskResult?: WorkflowRuntimeTask["taskResult"];
+                }>;
+            };
+            if (state.tasks && state.tasks.length > 0) {
+                if (debouncedSaveTasksToSession) {
+                    debouncedSaveTasksToSession(
+                        state.tasks as NormalizedTodoItem[],
+                        sessionId,
+                    );
+                }
+                
+                // Publish task update event
+                if (eventAdapter) {
+                    const formattedTasks = toRuntimeTasks(
+                        state.tasks.map((task) => ({
+                            id: task.id,
+                            title: task.content,
+                            status: task.status,
+                            blockedBy: task.blockedBy,
+                            identity: task.identity,
+                            taskResult: task.taskResult,
+                        })),
+                    );
+                    eventAdapter.publishTaskUpdate(sessionId, formattedTasks);
+                }
+
+                if (!sessionTracked) {
+                    context.setWorkflowSessionDir(sessionDir);
+                    context.setWorkflowSessionId(sessionId);
+                    const taskIds = new Set<string>(
+                        state.tasks
+                            .map((t) => t.id)
+                            .filter(
+                                (id): id is string =>
+                                    id != null && id.length > 0,
+                            ),
+                    );
+                    context.setWorkflowTaskIds(taskIds);
+                    sessionTracked = true;
+                }
+            }
+        }
+        
+        // Unsubscribe from statusChange events before cleanup
+        unsubscribeStatusChange?.();
+
+        // Flush any pending debounced save
+        if (saveDebounceTimer) {
+            clearTimeout(saveDebounceTimer);
+            if (pendingSaveTasks && options?.saveTasksToSession) {
+                try {
+                    await options.saveTasksToSession(pendingSaveTasks, sessionId);
+                } catch (err) {
+                    pipelineError("Workflow", "task_flush_error", { sessionId });
+                    console.error('[workflow] Failed to flush pending task save:', err);
+                }
+            }
+        }
+        
+        // Publish final step complete event
+        if (lastNodeId !== null && eventAdapter) {
+            eventAdapter.publishStepComplete(
+                sessionId,
+                nodeDescriptions?.[lastNodeId] ?? lastNodeId,
+                lastNodeId,
+                lastNodeCompletionStatus,
+            );
+        }
+
+        // Phase 6: Check execution status and report result
+        context.setStreaming(false);
+
+        // Silent exit for workflow cancellation (e.g., double Ctrl+C).
+        // Cancellation can surface as status "cancelled" (via AbortSignal) or
+        // status "failed" with "Workflow cancelled" error (thrown by node).
+        if (lastStepStatus === "cancelled" ||
+            (lastStepStatus === "failed" && lastStepError === "Workflow cancelled")) {
+            return {
+                success: true,
+                stateUpdate: {
+                    workflowActive: false,
+                    workflowType: null,
+                    initialPrompt: null,
+                },
+            };
+        }
+
+        if (lastStepStatus === "failed") {
+            const errorDetail = lastStepError ? `: ${lastStepError}` : "";
+            const failureMessage = `Workflow failed at node "${lastNodeId ?? "unknown"}"${errorDetail}`;
+            context.addMessage("system", failureMessage);
+            pipelineError("Workflow", "execution_failed", { workflow: definition.name, nodeId: lastNodeId ?? "unknown", error: lastStepError });
+            incrementRuntimeParityCounter("workflow.runtime.parity.execution_total", {
+                phase: "failure",
+                workflow: definition.name,
+            });
+            runtimeParityDebug("workflow_execution_failed", {
+                workflow: definition.name,
+                sessionId,
+                workflowRunId,
+                nodeId: lastNodeId,
+                error: lastStepError,
+            });
+            return {
+                success: false,
+                stateUpdate: {
+                    workflowActive: false,
+                    workflowType: null,
+                    initialPrompt: null,
+                },
+            };
+        }
+
+        context.addMessage(
+            "assistant",
+            `**${definition.name}** workflow completed successfully.`,
+        );
+        pipelineLog("Workflow", "complete", { workflow: definition.name, sessionId });
+        incrementRuntimeParityCounter("workflow.runtime.parity.execution_total", {
+            phase: "success",
+            workflow: definition.name,
+        });
+
+        return {
+            success: true,
+            stateUpdate: {
+                workflowActive: false,
+                workflowType: null,
+                initialPrompt: null,
+            },
+        };
+    } catch (error) {
+        unsubscribeStatusChange?.();
+        context.setStreaming(false);
+
+        // Silent exit for workflow cancellation (double Ctrl+C)
+        if (error instanceof Error && error.message === "Workflow cancelled") {
+            return {
+                success: true,
+                stateUpdate: {
+                    workflowActive: false,
+                    workflowType: null,
+                    initialPrompt: null,
+                },
+            };
+        }
+
+        const errorMessage = `Workflow failed: ${error instanceof Error ? error.message : String(error)}`;
+        context.addMessage("system", errorMessage);
+        pipelineError("Workflow", "execution_error", { workflow: definition.name, error: error instanceof Error ? error.message : String(error) });
+        incrementRuntimeParityCounter("workflow.runtime.parity.execution_total", {
+            phase: "failure",
+            workflow: definition.name,
+        });
+        runtimeParityDebug("workflow_execution_failed", {
+            workflow: definition.name,
+            sessionId,
+            workflowRunId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+
+        return {
+            success: false,
+            stateUpdate: {
+                workflowActive: false,
+                workflowType: null,
+                initialPrompt: null,
+            },
+        };
+    }
+}
diff --git a/src/workflows/graph/agent-providers.test.ts b/src/workflows/graph/agent-providers.test.ts
new file mode 100644
index 0000000000..579b9db7bd
--- /dev/null
+++ b/src/workflows/graph/agent-providers.test.ts
@@ -0,0 +1,174 @@
+import { describe, expect, test } from "bun:test";
+import type {
+  AgentMessage,
+  CodingAgentClient,
+  EventHandler,
+  EventType,
+  ModelDisplayInfo,
+  Session,
+  SessionConfig,
+  ToolDefinition,
+} from "../../sdk/types.ts";
+import {
+  ClientBackedAgentProvider,
+  createClaudeAgentProvider,
+  createCopilotAgentProvider,
+  createDefaultProviderRegistry,
+  createOpenCodeAgentProvider,
+} from "./agent-providers.ts";
+
+function createMockSession(id: string): Session {
+  return {
+    id,
+    async send(message: string): Promise<AgentMessage> {
+      return { type: "text", content: message, role: "assistant" };
+    },
+    async *stream(message: string): AsyncIterable<AgentMessage> {
+      yield { type: "text", content: message, role: "assistant" };
+    },
+    async summarize(): Promise<void> {},
+    async getContextUsage() {
+      return {
+        inputTokens: 1,
+        outputTokens: 1,
+        maxTokens: 1000,
+        usagePercentage: 0.2,
+      };
+    },
+    getSystemToolsTokens(): number {
+      return 0;
+    },
+    async destroy(): Promise<void> {},
+  };
+}
+
+interface MockClientState {
+  startCalls: number;
+  createSessionCalls: SessionConfig[];
+}
+
+function createMockClient(
+  agentType: CodingAgentClient["agentType"],
+): { client: CodingAgentClient; state: MockClientState } {
+  const state: MockClientState = {
+    startCalls: 0,
+    createSessionCalls: [],
+  };
+
+  const mockDisplay: ModelDisplayInfo = { model: "mock-model", tier: "mock-tier" };
+  const session = createMockSession(`${agentType}-session`);
+
+  const client: CodingAgentClient = {
+    agentType,
+    async createSession(config?: SessionConfig): Promise<Session> {
+      state.createSessionCalls.push(config ?? {});
+      return session;
+    },
+    async resumeSession(): Promise<Session | null> {
+      return null;
+    },
+    on<T extends EventType>(_eventType: T, _handler: EventHandler<T>): () => void {
+      return () => {};
+    },
+    registerTool(_tool: ToolDefinition): void {},
+    async start(): Promise<void> {
+      state.startCalls += 1;
+    },
+    async stop(): Promise<void> {},
+    async getModelDisplayInfo(): Promise<ModelDisplayInfo> {
+      return mockDisplay;
+    },
+    getSystemToolsTokens(): number | null {
+      return null;
+    },
+  };
+
+  return { client, state };
+}
+
+describe("ClientBackedAgentProvider", () => {
+  test("starts client lazily and delegates createSession", async () => {
+    const mock = createMockClient("claude");
+    const provider = new ClientBackedAgentProvider({
+      name: "claude",
+      client: mock.client,
+      supportedModels: ["sonnet"],
+    });
+
+    const first = await provider.createSession({ model: "anthropic/sonnet" });
+    const second = await provider.createSession({ model: "anthropic/opus" });
+
+    expect(first.id).toBe("claude-session");
+    expect(second.id).toBe("claude-session");
+    expect(mock.state.startCalls).toBe(1);
+    expect(mock.state.createSessionCalls).toEqual([
+      { model: "anthropic/sonnet" },
+      { model: "anthropic/opus" },
+    ]);
+  });
+
+  test("returns a defensive copy from supportedModels", () => {
+    const mock = createMockClient("claude");
+    const provider = new ClientBackedAgentProvider({
+      name: "claude",
+      client: mock.client,
+      supportedModels: ["opus", "sonnet"],
+    });
+
+    const models = provider.supportedModels();
+    models.push("unexpected-model");
+
+    expect(provider.supportedModels()).toEqual(["opus", "sonnet"]);
+  });
+});
+
+describe("agent provider factories", () => {
+  test("creates claude provider with default supported models", () => {
+    const mock = createMockClient("claude");
+    const provider = createClaudeAgentProvider({ client: mock.client });
+
+    expect(provider.name).toBe("claude");
+    expect(provider.supportedModels()).toEqual(["opus", "sonnet", "haiku"]);
+  });
+
+  test("creates opencode and copilot providers with provided models", () => {
+    const opencodeMock = createMockClient("opencode");
+    const copilotMock = createMockClient("copilot");
+
+    const opencode = createOpenCodeAgentProvider({
+      client: opencodeMock.client,
+      supportedModels: ["anthropic/claude-sonnet-4"],
+    });
+    const copilot = createCopilotAgentProvider({
+      client: copilotMock.client,
+      supportedModels: ["claude-opus-4.6", "gpt-5.2"],
+    });
+
+    expect(opencode.name).toBe("opencode");
+    expect(opencode.supportedModels()).toEqual(["anthropic/claude-sonnet-4"]);
+    expect(copilot.name).toBe("copilot");
+    expect(copilot.supportedModels()).toEqual(["claude-opus-4.6", "gpt-5.2"]);
+  });
+
+  test("creates registry containing all default providers", async () => {
+    const claudeMock = createMockClient("claude");
+    const opencodeMock = createMockClient("opencode");
+    const copilotMock = createMockClient("copilot");
+
+    const registry = createDefaultProviderRegistry({
+      claude: { client: claudeMock.client },
+      opencode: { client: opencodeMock.client },
+      copilot: { client: copilotMock.client },
+    });
+
+    expect(registry.list()).toEqual(["claude", "opencode", "copilot"]);
+
+    await registry.get("claude")?.createSession({});
+    await registry.get("opencode")?.createSession({});
+    await registry.get("copilot")?.createSession({});
+
+    expect(claudeMock.state.startCalls).toBe(1);
+    expect(opencodeMock.state.startCalls).toBe(1);
+    expect(copilotMock.state.startCalls).toBe(1);
+  });
+});
diff --git a/src/workflows/graph/agent-providers.ts b/src/workflows/graph/agent-providers.ts
new file mode 100644
index 0000000000..ba71aa5022
--- /dev/null
+++ b/src/workflows/graph/agent-providers.ts
@@ -0,0 +1,144 @@
+import {
+  createClaudeAgentClient,
+  createCopilotClient,
+  createOpenCodeClient,
+  type CopilotClientOptions,
+  type OpenCodeClientOptions,
+} from "../../sdk/clients/index.ts";
+import type { CodingAgentClient, Session, SessionConfig } from "../../sdk/types.ts";
+import type { AgentProvider } from "./provider-registry.ts";
+import { ProviderRegistry } from "./provider-registry.ts";
+
+const DEFAULT_CLAUDE_MODELS = ["opus", "sonnet", "haiku"] as const;
+
+interface ClientBackedProviderConfig {
+  name: string;
+  client: CodingAgentClient;
+  supportedModels?: readonly string[];
+}
+
+/**
+ * Wraps a CodingAgentClient as an AgentProvider.
+ * Starts the client lazily when the first session is created.
+ */
+export class ClientBackedAgentProvider implements AgentProvider {
+  readonly name: string;
+  private readonly client: CodingAgentClient;
+  private readonly models: readonly string[];
+  private startPromise: Promise<void> | null = null;
+
+  constructor(config: ClientBackedProviderConfig) {
+    this.name = config.name;
+    this.client = config.client;
+    this.models = [...(config.supportedModels ?? [])];
+  }
+
+  async createSession(config: SessionConfig): Promise<Session> {
+    await this.ensureStarted();
+    return this.client.createSession(config);
+  }
+
+  supportedModels(): string[] {
+    return [...this.models];
+  }
+
+  private async ensureStarted(): Promise<void> {
+    if (!this.startPromise) {
+      this.startPromise = this.client.start();
+    }
+
+    try {
+      await this.startPromise;
+    } catch (error) {
+      this.startPromise = null;
+      throw error;
+    }
+  }
+}
+
+/**
+ * Options for constructing the Claude provider.
+ */
+export interface ClaudeAgentProviderOptions {
+  client?: CodingAgentClient;
+  supportedModels?: readonly string[];
+}
+
+/**
+ * Options for constructing the OpenCode provider.
+ */
+export interface OpenCodeAgentProviderOptions {
+  client?: CodingAgentClient;
+  clientOptions?: OpenCodeClientOptions;
+  supportedModels?: readonly string[];
+}
+
+/**
+ * Options for constructing the Copilot provider.
+ */
+export interface CopilotAgentProviderOptions {
+  client?: CodingAgentClient;
+  clientOptions?: CopilotClientOptions;
+  supportedModels?: readonly string[];
+}
+
+/**
+ * Options for constructing the default provider registry.
+ */
+export interface DefaultProviderRegistryOptions {
+  claude?: ClaudeAgentProviderOptions;
+  opencode?: OpenCodeAgentProviderOptions;
+  copilot?: CopilotAgentProviderOptions;
+}
+
+/**
+ * Create an AgentProvider backed by the Claude client.
+ */
+export function createClaudeAgentProvider(
+  options: ClaudeAgentProviderOptions = {},
+): AgentProvider {
+  return new ClientBackedAgentProvider({
+    name: "claude",
+    client: options.client ?? createClaudeAgentClient(),
+    supportedModels: options.supportedModels ?? DEFAULT_CLAUDE_MODELS,
+  });
+}
+
+/**
+ * Create an AgentProvider backed by the OpenCode client.
+ */
+export function createOpenCodeAgentProvider(
+  options: OpenCodeAgentProviderOptions = {},
+): AgentProvider {
+  return new ClientBackedAgentProvider({
+    name: "opencode",
+    client: options.client ?? createOpenCodeClient(options.clientOptions),
+    supportedModels: options.supportedModels ?? [],
+  });
+}
+
+/**
+ * Create an AgentProvider backed by the Copilot client.
+ */
+export function createCopilotAgentProvider(
+  options: CopilotAgentProviderOptions = {},
+): AgentProvider {
+  return new ClientBackedAgentProvider({
+    name: "copilot",
+    client: options.client ?? createCopilotClient(options.clientOptions),
+    supportedModels: options.supportedModels ?? [],
+  });
+}
+
+/**
+ * Create a ProviderRegistry with Claude, OpenCode, and Copilot providers.
+ */
+export function createDefaultProviderRegistry(
+  options: DefaultProviderRegistryOptions = {},
+): ProviderRegistry {
+  return new ProviderRegistry({
+    claude: createClaudeAgentProvider(options.claude),
+    opencode: createOpenCodeAgentProvider(options.opencode),
+    copilot: createCopilotAgentProvider(options.copilot),
+  });
+}
diff --git a/src/graph/annotation.test.ts b/src/workflows/graph/annotation.test.ts
similarity index 99%
rename from src/graph/annotation.test.ts
rename to src/workflows/graph/annotation.test.ts
index ecaef1d48a..33365f555c 100644
--- a/src/graph/annotation.test.ts
+++ b/src/workflows/graph/annotation.test.ts
@@ -11,17 +11,16 @@ import {
   applyReducer,
   applyStateUpdate,
   createAtomicState,
-  createRalphState,
   getDefaultValue,
   initializeState,
   isAtomicWorkflowState,
   isFeature,
-  isRalphWorkflowState,
   Reducers,
   updateAtomicState,
-  updateRalphState,
 } from "./annotation.ts";
-import type { AtomicWorkflowState, Feature, RalphWorkflowState } from "./annotation.ts";
+import { createRalphState, isRalphWorkflowState, updateRalphState } from "../ralph/state.ts";
+import type { AtomicWorkflowState, Feature } from "./annotation.ts";
+import type { RalphWorkflowState } from "../ralph/state.ts";
 import type { DebugReport } from "./types.ts";
 
 describe("Reducers", () => {
@@ -408,6 +407,10 @@ function createTestRalphState(overrides: Partial<RalphWorkflowState> = {}): Ralp
     researchDoc: "",
     specDoc: "",
     specApproved: false,
+    tasks: [],
+    currentTasks: [],
+    reviewResult: null,
+    fixesApplied: false,
     featureList: [],
     currentFeature: null,
     allFeaturesPassing: false,
diff --git a/src/graph/annotation.ts b/src/workflows/graph/annotation.ts
similarity index 57%
rename from src/graph/annotation.ts
rename to src/workflows/graph/annotation.ts
index d2f7e44b5c..a8297ab5a0 100644
--- a/src/graph/annotation.ts
+++ b/src/workflows/graph/annotation.ts
@@ -11,9 +11,6 @@
  * Reference: Feature 10 - Create src/graph/annotation.ts with state annotation system
  */
 
-import { join } from "path";
-import { homedir } from "os";
-
 import type { ContextWindowUsage, DebugReport, NodeId } from "./types.ts";
 
 // ============================================================================
@@ -45,8 +42,7 @@ export interface Annotation<T> {
  * Root type for combining multiple annotations into a state schema.
  * Each key maps to an Annotation definition.
  */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export type AnnotationRoot = Record<string, Annotation<any>>;
+export type AnnotationRoot = Record<string, Annotation<any>>; // eslint-disable-line @typescript-eslint/no-explicit-any
 
 /**
  * Extract the value type from an Annotation.
@@ -307,7 +303,7 @@ export interface Feature {
 
 /**
  * Annotation schema for the Atomic workflow state.
- * Defines all fields needed for the Ralph loop and feature implementation.
+ * Defines all fields needed for Atomic workflow and feature implementation.
  */
 export const AtomicStateAnnotation = {
   // Base state fields (required by BaseState)
@@ -418,271 +414,3 @@ export function isAtomicWorkflowState(value: unknown): value is AtomicWorkflowSt
     typeof obj.iteration === "number"
   );
 }
-
-// ============================================================================
-// RALPH WORKFLOW STATE
-// ============================================================================
-
-/**
- * Ralph workflow state interface for the Ralph loop execution.
- *
- * This interface extends BaseState and includes all fields needed for
- * the Ralph autonomous feature implementation workflow. It combines:
- * - Base workflow state fields (executionId, lastUpdated, outputs)
- * - Research and specification tracking
- * - Feature list management
- * - Debug and error tracking
- * - PR management
- * - Context management
- * - Iteration tracking
- * - Ralph-specific session fields (yolo mode, session management)
- *
- * @example
- * ```typescript
- * const state: RalphWorkflowState = {
- *   executionId: "550e8400-e29b-41d4-a716-446655440000",
- *   lastUpdated: "2026-02-02T10:00:00.000Z",
- *   outputs: {},
- *   researchDoc: "# Research\n...",
- *   specDoc: "# Specification\n...",
- *   specApproved: true,
- *   featureList: [...],
- *   currentFeature: null,
- *   allFeaturesPassing: false,
- *   contextWindowUsage: null,
- *   iteration: 1,
- *   prUrl: null,
- *   debugReports: [],
- *   ralphSessionId: "abc123-def456",
- *   ralphSessionDir: "~/.atomic/workflows/sessions/abc123-def456",
- *   yolo: false,
- *   yoloPrompt: null,
- *   yoloComplete: false,
- *   maxIterations: 100,
- *   shouldContinue: true
- * };
- * ```
- */
-export interface RalphWorkflowState {
-  /** Unique identifier for this execution instance */
-  executionId: string;
-
-  /** ISO timestamp of last state update */
-  lastUpdated: string;
-
-  /** Map of node outputs keyed by node ID */
-  outputs: Record<NodeId, unknown>;
-
-  /** Research documentation content */
-  researchDoc: string;
-
-  /** Technical specification document content */
-  specDoc: string;
-
-  /** Whether the specification has been approved for implementation */
-  specApproved: boolean;
-
-  /** List of features to implement */
-  featureList: Feature[];
-
-  /** Currently active feature being implemented, or null */
-  currentFeature: Feature | null;
-
-  /** Whether all features have passed their tests */
-  allFeaturesPassing: boolean;
-
-  /** Current context window usage from agent sessions */
-  contextWindowUsage: ContextWindowUsage | null;
-
-  /** Current iteration number (increments each loop cycle) */
-  iteration: number;
-
-  /** URL of the pull request created by this workflow (if any) */
-  prUrl: string | null;
-
-  /** Array of debug reports generated during execution */
-  debugReports: DebugReport[];
-
-  // ============================================================================
-  // RALPH-SPECIFIC SESSION FIELDS
-  // ============================================================================
-
-  /** Ralph session unique identifier (UUID v4) */
-  ralphSessionId: string;
-
-  /** Path to the Ralph session directory (e.g., "~/.atomic/workflows/sessions/{uuid}") */
-  ralphSessionDir: string;
-
-  /**
-   * YOLO mode flag
-   * - true: Run without a feature list (autonomous exploration with prompt)
-   * - false: Follow the provided feature list
-   */
-  yolo: boolean;
-
-  /** Prompt provided in yolo mode (null if not in yolo mode) */
-  yoloPrompt: string | null;
-
-  /** Whether yolo mode has completed (agent signaled COMPLETE) */
-  yoloComplete: boolean;
-
-  /** Maximum number of iterations before the workflow stops (0 = infinite) */
-  maxIterations: number;
-
-  /** Whether the workflow should continue to the next iteration */
-  shouldContinue: boolean;
-
-  /** Git branch name for this session's work (undefined if not set) */
-  prBranch: string | undefined;
-
-  /** Array of completed feature IDs */
-  completedFeatures: string[];
-
-  /** Path to the source feature-list.json file (undefined if in yolo mode) */
-  sourceFeatureListPath: string | undefined;
-
-  /** Maximum iterations reached flag (for loop exit condition) */
-  maxIterationsReached: boolean | undefined;
-}
-
-/**
- * Annotation schema for the Ralph workflow state.
- * Defines all fields needed for the Ralph loop with appropriate reducers.
- */
-export const RalphStateAnnotation = {
-  // Base state fields (required by BaseState)
-  executionId: annotation<string>(""),
-  lastUpdated: annotation<string>(() => new Date().toISOString()),
-  outputs: annotation<Record<NodeId, unknown>>({}),
-
-  // Research and specification
-  researchDoc: annotation<string>(""),
-  specDoc: annotation<string>(""),
-  specApproved: annotation<boolean>(false),
-
-  // Feature list management
-  featureList: annotation<Feature[]>([], Reducers.mergeById<Feature>("description")),
-  currentFeature: annotation<Feature | null>(null),
-  allFeaturesPassing: annotation<boolean>(false),
-
-  // Debug and error tracking
-  debugReports: annotation<DebugReport[]>([], Reducers.concat),
-
-  // PR management
-  prUrl: annotation<string | null>(null),
-  prBranch: annotation<string | undefined>(undefined),
-
-  // Context management
-  contextWindowUsage: annotation<ContextWindowUsage | null>(null),
-
-  // Iteration tracking
-  iteration: annotation<number>(1),
-
-  // Ralph-specific session fields
-  ralphSessionId: annotation<string>(""),
-  ralphSessionDir: annotation<string>(""),
-  yolo: annotation<boolean>(false),
-  yoloPrompt: annotation<string | null>(null),
-  yoloComplete: annotation<boolean>(false),
-  maxIterations: annotation<number>(100),
-  shouldContinue: annotation<boolean>(true),
-  completedFeatures: annotation<string[]>([], Reducers.concat),
-  sourceFeatureListPath: annotation<string | undefined>(undefined),
-  maxIterationsReached: annotation<boolean | undefined>(undefined),
-};
-
-/**
- * Create a new Ralph workflow state with default values.
- *
- * @param executionId - Unique ID for this execution (auto-generated if not provided)
- * @param options - Optional initial values for Ralph-specific fields
- * @returns Initialized RalphWorkflowState
- *
- * @example
- * ```typescript
- * // Create with defaults
- * const state = createRalphState();
- *
- * // Create with specific options
- * const state = createRalphState("my-exec-id", {
- *   yolo: true,
- *   yoloPrompt: "Build a snake game in Rust",
- *   maxIterations: 0
- * });
- * ```
- */
-export function createRalphState(
-  executionId?: string,
-  options?: Partial<RalphWorkflowState>
-): RalphWorkflowState {
-  const state = initializeState(RalphStateAnnotation);
-  const ralphSessionId = options?.ralphSessionId ?? crypto.randomUUID();
-
-  return {
-    ...state,
-    executionId: executionId ?? crypto.randomUUID(),
-    lastUpdated: new Date().toISOString(),
-    ralphSessionId,
-    ralphSessionDir: options?.ralphSessionDir ?? `${join(homedir(), ".atomic", "workflows", "sessions", ralphSessionId)}`,
-    yolo: options?.yolo ?? false,
-    yoloPrompt: options?.yoloPrompt ?? null,
-    yoloComplete: options?.yoloComplete ?? false,
-    maxIterations: options?.maxIterations ?? 100,
-    shouldContinue: options?.shouldContinue ?? true,
-    completedFeatures: options?.completedFeatures ?? [],
-    sourceFeatureListPath: options?.sourceFeatureListPath,
-    maxIterationsReached: options?.maxIterationsReached,
-    prBranch: options?.prBranch,
-    ...options,
-  };
-}
-
-/**
- * Apply an update to a Ralph workflow state.
- *
- * @param current - Current state
- * @param update - Partial update to apply
- * @returns New state with updates applied
- */
-export function updateRalphState(
-  current: RalphWorkflowState,
-  update: Partial<RalphWorkflowState>
-): RalphWorkflowState {
-  const newState = applyStateUpdate(RalphStateAnnotation, current, update);
-  return {
-    ...newState,
-    lastUpdated: new Date().toISOString(),
-  };
-}
-
-/**
- * Type guard to check if a value is a valid RalphWorkflowState.
- */
-export function isRalphWorkflowState(value: unknown): value is RalphWorkflowState {
-  if (typeof value !== "object" || value === null) {
-    return false;
-  }
-  const obj = value as Record<string, unknown>;
-  return (
-    // Base state fields
-    typeof obj.executionId === "string" &&
-    typeof obj.lastUpdated === "string" &&
-    typeof obj.outputs === "object" &&
-    obj.outputs !== null &&
-    // Atomic workflow fields
-    typeof obj.researchDoc === "string" &&
-    typeof obj.specDoc === "string" &&
-    typeof obj.specApproved === "boolean" &&
-    Array.isArray(obj.featureList) &&
-    typeof obj.allFeaturesPassing === "boolean" &&
-    Array.isArray(obj.debugReports) &&
-    typeof obj.iteration === "number" &&
-    // Ralph-specific fields
-    typeof obj.ralphSessionId === "string" &&
-    typeof obj.ralphSessionDir === "string" &&
-    typeof obj.yolo === "boolean" &&
-    typeof obj.maxIterations === "number" &&
-    typeof obj.shouldContinue === "boolean" &&
-    Array.isArray(obj.completedFeatures)
-  );
-}
diff --git a/src/workflows/graph/builder.test.ts b/src/workflows/graph/builder.test.ts
new file mode 100644
index 0000000000..9fb57a4f21
--- /dev/null
+++ b/src/workflows/graph/builder.test.ts
@@ -0,0 +1,1367 @@
+/**
+ * Tests for GraphBuilder and graph construction
+ */
+
+import { describe, expect, test } from "bun:test";
+import { z } from "zod";
+import {
+  GraphBuilder,
+  graph,
+  createNode,
+  createDecisionNode,
+  createWaitNode,
+  type LoopConfig,
+  type ParallelConfig,
+  type IfConfig,
+  type SubAgentConfig,
+  type ToolBuilderConfig,
+} from "./builder.ts";
+import type { BaseState, NodeDefinition } from "./types.ts";
+
+// ============================================================================
+// TEST STATE INTERFACE
+// ============================================================================
+
+interface TestState extends BaseState {
+  count: number;
+  flag: boolean;
+  message: string;
+}
+
+const testStateSchema: z.ZodType<TestState> = z.object({
+  executionId: z.string(),
+  lastUpdated: z.string(),
+  outputs: z.record(z.string(), z.unknown()),
+  count: z.number(),
+  flag: z.boolean(),
+  message: z.string(),
+});
+
+// ============================================================================
+// TEST HELPER NODES
+// ============================================================================
+
+const testNode1: NodeDefinition<TestState> = {
+  id: "test1",
+  type: "tool",
+  execute: async () => ({ stateUpdate: { count: 1 } }),
+};
+
+const testNode2: NodeDefinition<TestState> = {
+  id: "test2",
+  type: "tool",
+  execute: async () => ({ stateUpdate: { count: 2 } }),
+};
+
+const testNode3: NodeDefinition<TestState> = {
+  id: "test3",
+  type: "tool",
+  execute: async () => ({ stateUpdate: { count: 3 } }),
+};
+
+// ============================================================================
+// GRAPH BUILDER: BASIC CONSTRUCTION
+// ============================================================================
+
+describe("GraphBuilder - basic construction", () => {
+  test("creates an empty builder via factory function", () => {
+    const builder = graph<TestState>();
+    expect(builder).toBeInstanceOf(GraphBuilder);
+  });
+
+  test("starts a graph with a single node", () => {
+    const builder = graph<TestState>().start(testNode1);
+    const compiled = builder.compile();
+
+    expect(compiled.startNode).toBe("test1");
+    expect(compiled.nodes.size).toBe(1);
+    expect(compiled.nodes.get("test1")).toEqual(testNode1);
+  });
+
+  test("chains nodes with then()", () => {
+    const builder = graph<TestState>().start(testNode1).then(testNode2).then(testNode3);
+    const compiled = builder.compile();
+
+    expect(compiled.nodes.size).toBe(3);
+    expect(compiled.edges.length).toBe(2);
+    expect(compiled.edges[0]).toMatchObject({ from: "test1", to: "test2" });
+    expect(compiled.edges[1]).toMatchObject({ from: "test2", to: "test3" });
+  });
+
+  test("marks terminal node with end()", () => {
+    const builder = graph<TestState>().start(testNode1).then(testNode2).end();
+    const compiled = builder.compile();
+
+    expect(compiled.endNodes.has("test2")).toBe(true);
+  });
+
+  test("infers end nodes when not explicitly marked", () => {
+    const builder = graph<TestState>().start(testNode1).then(testNode2);
+    const compiled = builder.compile();
+
+    // test2 has no outgoing edges, so it should be an end node
+    expect(compiled.endNodes.has("test2")).toBe(true);
+  });
+
+  test("throws error when starting graph twice", () => {
+    expect(() => {
+      graph<TestState>().start(testNode1).start(testNode2);
+    }).toThrow("Start node already set");
+  });
+
+  test("throws error when compiling without start node", () => {
+    expect(() => {
+      graph<TestState>().compile();
+    }).toThrow("Cannot compile graph without a start node");
+  });
+
+  test("throws error when adding duplicate node ID", () => {
+    const builder = graph<TestState>().start(testNode1);
+    
+    expect(() => {
+      builder.then(testNode1); // Same node ID
+    }).toThrow('Node with ID "test1" already exists');
+  });
+});
+
+// ============================================================================
+// GRAPH BUILDER: CONDITIONAL BRANCHES
+// ============================================================================
+
+describe("GraphBuilder - conditional branches", () => {
+  test("creates if/endif branch structure", () => {
+    const builder = graph<TestState>()
+      .start(testNode1)
+      .if((state) => state.flag === true)
+        .then(testNode2)
+      .endif()
+      .end();
+    
+    const compiled = builder.compile();
+
+    // Should have: test1, decision node, test2, merge node
+    expect(compiled.nodes.size).toBe(4);
+    
+    // Find the decision and merge nodes
+    const nodeIds = Array.from(compiled.nodes.keys());
+    const decisionNode = nodeIds.find(id => id.startsWith("decision_"));
+    const mergeNode = nodeIds.find(id => id.startsWith("merge_"));
+    
+    expect(decisionNode).toBeDefined();
+    expect(mergeNode).toBeDefined();
+    
+    // Check edges: test1 -> decision, decision -> test2, test2 -> merge
+    const edgeFromTest1 = compiled.edges.find(e => e.from === "test1");
+    expect(edgeFromTest1?.to).toBe(decisionNode);
+    
+    const edgeToTest2 = compiled.edges.find(e => e.to === "test2");
+    expect(edgeToTest2?.from).toBe(decisionNode);
+    expect(edgeToTest2?.label).toBe("if-true");
+    
+    const edgeFromTest2 = compiled.edges.find(e => e.from === "test2");
+    expect(edgeFromTest2?.to).toBe(mergeNode);
+  });
+
+  test("creates if/else/endif branch structure", () => {
+    const builder = graph<TestState>()
+      .start(testNode1)
+      .if((state) => state.flag === true)
+        .then(testNode2)
+      .else()
+        .then(testNode3)
+      .endif()
+      .end();
+    
+    const compiled = builder.compile();
+
+    // Should have: test1, decision, test2, test3, merge
+    expect(compiled.nodes.size).toBe(5);
+    
+    // Check that both branch nodes exist
+    expect(compiled.nodes.has("test2")).toBe(true);
+    expect(compiled.nodes.has("test3")).toBe(true);
+    
+    // Check edges to both branches
+    const edgeToTest2 = compiled.edges.find(e => e.to === "test2");
+    const edgeToTest3 = compiled.edges.find(e => e.to === "test3");
+    
+    expect(edgeToTest2?.label).toBe("if-true");
+    expect(edgeToTest3?.label).toBe("if-false");
+  });
+
+  test("throws error on else() without preceding if()", () => {
+    expect(() => {
+      graph<TestState>().start(testNode1).else();
+    }).toThrow("Cannot use else() without a preceding if()");
+  });
+
+  test("throws error on endif() without preceding if()", () => {
+    expect(() => {
+      graph<TestState>().start(testNode1).endif();
+    }).toThrow("Cannot use endif() without a preceding if()");
+  });
+
+  test("throws error on if() without preceding node", () => {
+    expect(() => {
+      graph<TestState>().if((state) => state.flag);
+    }).toThrow("Cannot use if() without a preceding node");
+  });
+
+  test("throws error on duplicate else()", () => {
+    expect(() => {
+      graph<TestState>()
+        .start(testNode1)
+        .if((state) => state.flag)
+          .then(testNode2)
+        .else()
+          .then(testNode3)
+        .else(); // Duplicate else
+    }).toThrow("Already in else branch");
+  });
+});
+
+// ============================================================================
+// GRAPH BUILDER: CONFIG-BASED CONDITIONAL
+// ============================================================================
+
+describe("GraphBuilder - config-based conditional", () => {
+  test("creates if config with then and else branches", () => {
+    const builder = graph<TestState>()
+      .start(testNode1)
+      .if({
+        condition: (state) => state.flag === true,
+        then: [testNode2],
+        else: [testNode3],
+      })
+      .end();
+    
+    const compiled = builder.compile();
+
+    // Should have: test1, decision, test2, test3, merge
+    expect(compiled.nodes.size).toBe(5);
+    
+    // Check that both branch nodes exist
+    expect(compiled.nodes.has("test2")).toBe(true);
+    expect(compiled.nodes.has("test3")).toBe(true);
+    
+    // Check edges to both branches
+    const edgeToTest2 = compiled.edges.find(e => e.to === "test2");
+    const edgeToTest3 = compiled.edges.find(e => e.to === "test3");
+    
+    expect(edgeToTest2?.label).toBe("if-true");
+    expect(edgeToTest3?.label).toBe("if-false");
+  });
+
+  test("creates if config with only then branch", () => {
+    const builder = graph<TestState>()
+      .start(testNode1)
+      .if({
+        condition: (state) => state.flag === true,
+        then: [testNode2],
+      })
+      .end();
+    
+    const compiled = builder.compile();
+
+    // Should have: test1, decision node, test2, merge node
+    expect(compiled.nodes.size).toBe(4);
+    
+    // Find the decision and merge nodes
+    const nodeIds = Array.from(compiled.nodes.keys());
+    const decisionNode = nodeIds.find(id => id.startsWith("decision_"));
+    const mergeNode = nodeIds.find(id => id.startsWith("merge_"));
+    
+    expect(decisionNode).toBeDefined();
+    expect(mergeNode).toBeDefined();
+    
+    // Check edges
+    const edgeToTest2 = compiled.edges.find(e => e.to === "test2");
+    expect(edgeToTest2?.from).toBe(decisionNode);
+    expect(edgeToTest2?.label).toBe("if-true");
+  });
+
+  test("creates if config with else_if branch", () => {
+    const testNode4: NodeDefinition<TestState> = {
+      id: "test4",
+      type: "tool",
+      execute: async () => ({ stateUpdate: { count: 4 } }),
+    };
+
+    const builder = graph<TestState>()
+      .start(testNode1)
+      .if({
+        condition: (state) => state.count > 10,
+        then: [testNode2],
+        else_if: [
+          {
+            condition: (state) => state.count > 5,
+            then: [testNode3],
+          },
+        ],
+        else: [testNode4],
+      })
+      .end();
+    
+    const compiled = builder.compile();
+
+    // Should have: test1, multiple decision/merge nodes, test2, test3, test4
+    expect(compiled.nodes.has("test1")).toBe(true);
+    expect(compiled.nodes.has("test2")).toBe(true);
+    expect(compiled.nodes.has("test3")).toBe(true);
+    expect(compiled.nodes.has("test4")).toBe(true);
+    
+    // Check that all branch nodes exist
+    const edgeToTest2 = compiled.edges.find(e => e.to === "test2");
+    const edgeToTest3 = compiled.edges.find(e => e.to === "test3");
+    const edgeToTest4 = compiled.edges.find(e => e.to === "test4");
+    
+    expect(edgeToTest2).toBeDefined();
+    expect(edgeToTest3).toBeDefined();
+    expect(edgeToTest4).toBeDefined();
+  });
+
+  test("creates if config with multiple else_if branches", () => {
+    const testNode4: NodeDefinition<TestState> = {
+      id: "test4",
+      type: "tool",
+      execute: async () => ({ stateUpdate: { count: 4 } }),
+    };
+
+    const testNode5: NodeDefinition<TestState> = {
+      id: "test5",
+      type: "tool",
+      execute: async () => ({ stateUpdate: { count: 5 } }),
+    };
+
+    const builder = graph<TestState>()
+      .start(testNode1)
+      .if({
+        condition: (state) => state.count > 20,
+        then: [testNode2],
+        else_if: [
+          {
+            condition: (state) => state.count > 15,
+            then: [testNode3],
+          },
+          {
+            condition: (state) => state.count > 10,
+            then: [testNode4],
+          },
+        ],
+        else: [testNode5],
+      })
+      .end();
+    
+    const compiled = builder.compile();
+
+    // All branch nodes should exist
+    expect(compiled.nodes.has("test1")).toBe(true);
+    expect(compiled.nodes.has("test2")).toBe(true);
+    expect(compiled.nodes.has("test3")).toBe(true);
+    expect(compiled.nodes.has("test4")).toBe(true);
+    expect(compiled.nodes.has("test5")).toBe(true);
+    
+    // Check that all branches are connected
+    expect(compiled.edges.find(e => e.to === "test2")).toBeDefined();
+    expect(compiled.edges.find(e => e.to === "test3")).toBeDefined();
+    expect(compiled.edges.find(e => e.to === "test4")).toBeDefined();
+    expect(compiled.edges.find(e => e.to === "test5")).toBeDefined();
+  });
+
+  test("creates if config with multiple nodes per branch", () => {
+    const testNode4: NodeDefinition<TestState> = {
+      id: "test4",
+      type: "tool",
+      execute: async () => ({ stateUpdate: { count: 4 } }),
+    };
+
+    const testNode5: NodeDefinition<TestState> = {
+      id: "test5",
+      type: "tool",
+      execute: async () => ({ stateUpdate: { count: 5 } }),
+    };
+
+    const builder = graph<TestState>()
+      .start(testNode1)
+      .if({
+        condition: (state) => state.flag === true,
+        then: [testNode2, testNode3],
+        else: [testNode4, testNode5],
+      })
+      .end();
+    
+    const compiled = builder.compile();
+
+    // All nodes should exist
+    expect(compiled.nodes.has("test2")).toBe(true);
+    expect(compiled.nodes.has("test3")).toBe(true);
+    expect(compiled.nodes.has("test4")).toBe(true);
+    expect(compiled.nodes.has("test5")).toBe(true);
+    
+    // test2 should be followed by test3
+    const edgeTest2ToTest3 = compiled.edges.find(e => e.from === "test2" && e.to === "test3");
+    expect(edgeTest2ToTest3).toBeDefined();
+    
+    // test4 should be followed by test5
+    const edgeTest4ToTest5 = compiled.edges.find(e => e.from === "test4" && e.to === "test5");
+    expect(edgeTest4ToTest5).toBeDefined();
+  });
+
+  test("can chain after config-based if", () => {
+    const testNode4: NodeDefinition<TestState> = {
+      id: "test4",
+      type: "tool",
+      execute: async () => ({ stateUpdate: { count: 4 } }),
+    };
+
+    const builder = graph<TestState>()
+      .start(testNode1)
+      .if({
+        condition: (state) => state.flag === true,
+        then: [testNode2],
+        else: [testNode3],
+      })
+      .then(testNode4)
+      .end();
+    
+    const compiled = builder.compile();
+
+    // test4 should be connected after the merge node
+    expect(compiled.nodes.has("test4")).toBe(true);
+    
+    // Find merge node and check it connects to test4
+    const nodeIds = Array.from(compiled.nodes.keys());
+    const mergeNode = nodeIds.find(id => id.startsWith("merge_"));
+    
+    expect(mergeNode).toBeDefined();
+    const edgeMergeToTest4 = compiled.edges.find(e => e.from === mergeNode && e.to === "test4");
+    expect(edgeMergeToTest4).toBeDefined();
+  });
+});
+
+// ============================================================================
+// GRAPH BUILDER: PARALLEL EXECUTION
+// ============================================================================
+
+describe("GraphBuilder - parallel execution", () => {
+  test("creates parallel execution structure", () => {
+    const parallelConfig: ParallelConfig<TestState> = {
+      branches: ["test2", "test3"],
+      strategy: "all",
+    };
+
+    const builder = graph<TestState>()
+      .start(testNode1)
+      .parallel(parallelConfig);
+    
+    const compiled = builder.compile();
+
+    // Should have test1 and a parallel node
+    expect(compiled.nodes.size).toBeGreaterThanOrEqual(2);
+    
+    // Find the parallel node
+    const parallelNode = Array.from(compiled.nodes.values()).find(n => n.type === "parallel");
+    expect(parallelNode).toBeDefined();
+    
+    // Check edge from test1 to parallel node
+    const edgeToParallel = compiled.edges.find(e => e.from === "test1");
+    expect(edgeToParallel?.to).toBe(parallelNode?.id);
+    
+    // Check edges to branches
+    const branchEdges = compiled.edges.filter(e => e.from === parallelNode?.id);
+    expect(branchEdges.length).toBe(2);
+    expect(branchEdges.map(e => e.to)).toContain("test2");
+    expect(branchEdges.map(e => e.to)).toContain("test3");
+  });
+
+  test("parallel execution can be used as start node", () => {
+    const parallelConfig: ParallelConfig<TestState> = {
+      branches: ["test1", "test2"],
+    };
+
+    const builder = graph<TestState>().parallel(parallelConfig);
+    const compiled = builder.compile();
+    
+    // Parallel node should be the start node
+    const parallelNode = Array.from(compiled.nodes.values()).find(n => n.type === "parallel");
+    expect(compiled.startNode).toBe(parallelNode!.id);
+  });
+});
+
+// ============================================================================
+// GRAPH BUILDER: LOOP CONSTRUCTS
+// ============================================================================
+
+describe("GraphBuilder - loop constructs", () => {
+  test("creates loop with single node body", () => {
+    const loopConfig: LoopConfig<TestState> = {
+      until: (state) => state.count >= 10,
+      maxIterations: 5,
+    };
+
+    const builder = graph<TestState>()
+      .start(testNode1)
+      .loop(testNode2, loopConfig);
+    
+    const compiled = builder.compile();
+
+    // Should have: test1, loop_start, test2, loop_check
+    expect(compiled.nodes.size).toBe(4);
+    
+    // Find loop nodes
+    const loopStartNode = Array.from(compiled.nodes.keys()).find(id => id.startsWith("loop_start_"));
+    const loopCheckNode = Array.from(compiled.nodes.keys()).find(id => id.startsWith("loop_check_"));
+    
+    expect(loopStartNode).toBeDefined();
+    expect(loopCheckNode).toBeDefined();
+    
+    // Check loop structure: loop_start -> test2 -> loop_check
+    const edgeToBody = compiled.edges.find(e => e.from === loopStartNode);
+    expect(edgeToBody?.to).toBe("test2");
+    
+    const edgeToCheck = compiled.edges.find(e => e.from === "test2");
+    expect(edgeToCheck?.to).toBe(loopCheckNode);
+    
+    // Check loop continuation edge
+    const continueEdge = compiled.edges.find(e => 
+      e.from === loopCheckNode && e.to === "test2" && e.label === "loop-continue"
+    );
+    expect(continueEdge).toBeDefined();
+    expect(continueEdge?.condition).toBeDefined();
+  });
+
+  test("creates loop with multi-node body", () => {
+    const loopConfig: LoopConfig<TestState> = {
+      until: (state) => state.flag === true,
+    };
+
+    const builder = graph<TestState>()
+      .start(testNode1)
+      .loop([testNode2, testNode3], loopConfig);
+    
+    const compiled = builder.compile();
+
+    // Should have: test1, loop_start, test2, test3, loop_check
+    expect(compiled.nodes.size).toBe(5);
+    
+    // Check body nodes are chained: test2 -> test3
+    const bodyEdge = compiled.edges.find(e => e.from === "test2" && e.to === "test3");
+    expect(bodyEdge).toBeDefined();
+    
+    // Check test3 connects to loop_check
+    const loopCheckNode = Array.from(compiled.nodes.keys()).find(id => id.startsWith("loop_check_"));
+    const edgeToCheck = compiled.edges.find(e => e.from === "test3");
+    expect(edgeToCheck?.to).toBe(loopCheckNode);
+  });
+
+  test("throws error on empty loop body", () => {
+    const loopConfig: LoopConfig<TestState> = {
+      until: (state) => state.flag === true,
+    };
+
+    expect(() => {
+      graph<TestState>().start(testNode1).loop([], loopConfig);
+    }).toThrow("Loop body must contain at least one node");
+  });
+
+  test("loop can be used as start node", () => {
+    const loopConfig: LoopConfig<TestState> = {
+      until: (state) => state.count >= 10,
+    };
+
+    const builder = graph<TestState>().loop(testNode1, loopConfig);
+    const compiled = builder.compile();
+    
+    // Loop start node should be the graph start
+    const loopStartNode = Array.from(compiled.nodes.keys()).find(id => id.startsWith("loop_start_"));
+    expect(compiled.startNode).toBe(loopStartNode!);
+  });
+});
+
+// ============================================================================
+// GRAPH BUILDER: WAIT NODES
+// ============================================================================
+
+describe("GraphBuilder - wait nodes", () => {
+  test("creates wait node from string prompt", () => {
+    const builder = graph<TestState>()
+      .start(testNode1)
+      .wait("Please provide input")
+      .end();
+    
+    const compiled = builder.compile();
+
+    // Should have: test1, wait node
+    expect(compiled.nodes.size).toBe(2);
+    
+    // Find the wait node
+    const waitNode = Array.from(compiled.nodes.values()).find(n => 
+      n.type === "wait" && n.id.startsWith("wait_")
+    );
+    expect(waitNode).toBeDefined();
+  });
+
+  test("creates wait node from node definition", () => {
+    const customWaitNode: NodeDefinition<TestState> = {
+      id: "custom_wait",
+      type: "wait",
+      execute: async () => ({
+        signals: [{ type: "human_input_required", message: "Custom wait" }],
+      }),
+    };
+
+    const builder = graph<TestState>()
+      .start(testNode1)
+      .wait(customWaitNode)
+      .end();
+    
+    const compiled = builder.compile();
+
+    expect(compiled.nodes.has("custom_wait")).toBe(true);
+    expect(compiled.nodes.get("custom_wait")?.type).toBe("wait");
+  });
+});
+
+// ============================================================================
+// GRAPH BUILDER: ERROR HANDLING
+// ============================================================================
+
+describe("GraphBuilder - error handling", () => {
+  test("registers error handler with catch()", () => {
+    const errorHandler: NodeDefinition<TestState> = {
+      id: "error_handler",
+      type: "tool",
+      execute: async () => ({ stateUpdate: { message: "Error handled" } }),
+    };
+
+    const builder = graph<TestState>()
+      .start(testNode1)
+      .then(testNode2)
+      .catch(errorHandler)
+      .end();
+    
+    const compiled = builder.compile();
+
+    // Error handler should be in nodes
+    expect(compiled.nodes.has("error_handler")).toBe(true);
+    
+    // Error handler ID should be in metadata
+    expect(compiled.config.metadata?.errorHandlerId).toBe("error_handler");
+  });
+});
+
+// ============================================================================
+// GRAPH BUILDER: HELPER FUNCTIONS
+// ============================================================================
+
+describe("createNode helper", () => {
+  test("creates a basic node definition", () => {
+    const node = createNode<TestState>(
+      "my_node",
+      "tool",
+      async () => ({ stateUpdate: { count: 42 } })
+    );
+
+    expect(node.id).toBe("my_node");
+    expect(node.type).toBe("tool");
+    expect(node.execute).toBeTypeOf("function");
+  });
+
+  test("creates node with optional fields", () => {
+    const node = createNode<TestState>(
+      "my_node",
+      "agent",
+      async () => ({}),
+      {
+        name: "My Node",
+        description: "Test node",
+        inputSchema: testStateSchema,
+        outputSchema: testStateSchema,
+        retry: { maxAttempts: 5, backoffMs: 500, backoffMultiplier: 2 },
+        isRecoveryNode: true,
+      }
+    );
+
+    expect(node.name).toBe("My Node");
+    expect(node.description).toBe("Test node");
+    expect(node.inputSchema).toBe(testStateSchema);
+    expect(node.outputSchema).toBe(testStateSchema);
+    expect(node.retry?.maxAttempts).toBe(5);
+    expect(node.isRecoveryNode).toBe(true);
+  });
+});
+
+describe("createDecisionNode helper", () => {
+  test("creates decision node with routes", () => {
+    const routes = [
+      { condition: (state: TestState) => state.count > 10, target: "high" },
+      { condition: (state: TestState) => state.count > 5, target: "medium" },
+    ];
+
+    const node = createDecisionNode<TestState>("decision", routes, "low");
+
+    expect(node.id).toBe("decision");
+    expect(node.type).toBe("decision");
+    expect(node.execute).toBeTypeOf("function");
+  });
+
+  test("decision node execute returns goto for matching condition", async () => {
+    const routes = [
+      { condition: (state: TestState) => state.count > 10, target: "high" },
+    ];
+
+    const node = createDecisionNode<TestState>("decision", routes, "low");
+    
+    const state: TestState = {
+      executionId: "test",
+      lastUpdated: new Date().toISOString(),
+      outputs: {},
+      count: 15,
+      flag: false,
+      message: "",
+    };
+
+    const result = await node.execute({ state, config: {}, errors: [] });
+    expect(result.goto).toBe("high");
+  });
+
+  test("decision node execute returns fallback when no condition matches", async () => {
+    const routes = [
+      { condition: (state: TestState) => state.count > 10, target: "high" },
+    ];
+
+    const node = createDecisionNode<TestState>("decision", routes, "low");
+    
+    const state: TestState = {
+      executionId: "test",
+      lastUpdated: new Date().toISOString(),
+      outputs: {},
+      count: 5,
+      flag: false,
+      message: "",
+    };
+
+    const result = await node.execute({ state, config: {}, errors: [] });
+    expect(result.goto).toBe("low");
+  });
+});
+
+describe("createWaitNode helper", () => {
+  test("creates wait node with prompt", () => {
+    const node = createWaitNode<TestState>("wait1", "Enter your name");
+
+    expect(node.id).toBe("wait1");
+    expect(node.type).toBe("wait");
+    expect(node.execute).toBeTypeOf("function");
+  });
+
+  test("wait node execute returns human_input_required signal", async () => {
+    const node = createWaitNode<TestState>("wait1", "Enter your name");
+    
+    const result = await node.execute({
+      state: {
+        executionId: "test",
+        lastUpdated: new Date().toISOString(),
+        outputs: {},
+        count: 0,
+        flag: false,
+        message: "",
+      },
+      config: {},
+      errors: [],
+    });
+
+    expect(result.signals).toBeDefined();
+    expect(result.signals?.length).toBe(1);
+    expect(result.signals?.[0]?.type).toBe("human_input_required");
+    expect(result.signals?.[0]?.message).toBe("Enter your name");
+  });
+});
+
+// ============================================================================
+// GRAPH BUILDER: QUERY METHODS
+// ============================================================================
+
+describe("GraphBuilder - query methods", () => {
+  test("getNode returns node by ID", () => {
+    const builder = graph<TestState>().start(testNode1).then(testNode2);
+    
+    expect(builder.getNode("test1")).toEqual(testNode1);
+    expect(builder.getNode("test2")).toEqual(testNode2);
+    expect(builder.getNode("nonexistent")).toBeUndefined();
+  });
+
+  test("getEdgesFrom returns outgoing edges", () => {
+    const builder = graph<TestState>()
+      .start(testNode1)
+      .then(testNode2)
+      .then(testNode3);
+    
+    const edges = builder.getEdgesFrom("test1");
+    expect(edges.length).toBe(1);
+    expect(edges[0]).toMatchObject({ from: "test1", to: "test2" });
+  });
+
+  test("getEdgesTo returns incoming edges", () => {
+    const builder = graph<TestState>()
+      .start(testNode1)
+      .then(testNode2)
+      .then(testNode3);
+    
+    const edges = builder.getEdgesTo("test2");
+    expect(edges.length).toBe(1);
+    expect(edges[0]).toMatchObject({ from: "test1", to: "test2" });
+  });
+
+  test("getEdgesFrom returns empty array for node with no outgoing edges", () => {
+    const builder = graph<TestState>().start(testNode1);
+    
+    const edges = builder.getEdgesFrom("test1");
+    expect(edges).toEqual([]);
+  });
+
+  test("getEdgesTo returns empty array for start node", () => {
+    const builder = graph<TestState>().start(testNode1).then(testNode2);
+    
+    const edges = builder.getEdgesTo("test1");
+    expect(edges).toEqual([]);
+  });
+});
+
+// ============================================================================
+// GRAPH BUILDER: .subagent() METHOD
+// ============================================================================
+
+describe("GraphBuilder - .subagent() method", () => {
+  test("creates a node with type 'agent' and correct ID", () => {
+    const builder = graph<TestState>().subagent({
+      id: "analyze-code",
+      agent: "codebase-analyzer",
+      task: "Analyze the codebase",
+    });
+
+    const compiled = builder.compile();
+
+    expect(compiled.nodes.has("analyze-code")).toBe(true);
+    const node = compiled.nodes.get("analyze-code");
+    expect(node?.type).toBe("agent");
+    expect(node?.id).toBe("analyze-code");
+  });
+
+  test("maps config.agent to agentName correctly", () => {
+    const builder = graph<TestState>().subagent({
+      id: "my-subagent",
+      agent: "codebase-analyzer",
+      task: "Do something",
+    });
+
+    const compiled = builder.compile();
+    const node = compiled.nodes.get("my-subagent");
+
+    // The node should exist with type "agent"
+    expect(node?.type).toBe("agent");
+    
+    // We can verify the agent name is used in the description
+    expect(node?.description).toContain("codebase-analyzer");
+  });
+
+  test("first .subagent() call auto-sets as start node (no .start() needed)", () => {
+    const builder = graph<TestState>().subagent({
+      id: "first-agent",
+      agent: "codebase-analyzer",
+      task: "First task",
+    });
+
+    const compiled = builder.compile();
+
+    expect(compiled.startNode).toBe("first-agent");
+  });
+
+  test("chaining: .subagent().subagent() creates two nodes with an edge", () => {
+    const builder = graph<TestState>()
+      .subagent({
+        id: "agent1",
+        agent: "codebase-analyzer",
+        task: "First task",
+      })
+      .subagent({
+        id: "agent2",
+        agent: "codebase-locator",
+        task: "Second task",
+      });
+
+    const compiled = builder.compile();
+
+    // Both nodes should exist
+    expect(compiled.nodes.has("agent1")).toBe(true);
+    expect(compiled.nodes.has("agent2")).toBe(true);
+
+    // Should have an edge from agent1 to agent2
+    const edge = compiled.edges.find((e) => e.from === "agent1" && e.to === "agent2");
+    expect(edge).toBeDefined();
+  });
+
+  test("config fields (name, description, retry) are passed through", () => {
+    const builder = graph<TestState>().subagent({
+      id: "my-agent",
+      agent: "codebase-analyzer",
+      task: "Analyze code",
+      name: "Code Analyzer",
+      description: "Analyzes the codebase structure",
+      retry: { maxAttempts: 3, backoffMs: 1000, backoffMultiplier: 2 },
+    });
+
+    const compiled = builder.compile();
+    const node = compiled.nodes.get("my-agent");
+
+    expect(node?.name).toBe("Code Analyzer");
+    expect(node?.description).toBe("Analyzes the codebase structure");
+    expect(node?.retry?.maxAttempts).toBe(3);
+    expect(node?.retry?.backoffMs).toBe(1000);
+  });
+
+  test("task can be a function that resolves from state", () => {
+    const builder = graph<TestState>().subagent({
+      id: "dynamic-agent",
+      agent: "codebase-analyzer",
+      task: (state) => `Analyze ${state.message}`,
+    });
+
+    const compiled = builder.compile();
+    const node = compiled.nodes.get("dynamic-agent");
+
+    expect(node).toBeDefined();
+    expect(node?.type).toBe("agent");
+  });
+
+  test("systemPrompt can be provided as string", () => {
+    const builder = graph<TestState>().subagent({
+      id: "custom-agent",
+      agent: "codebase-analyzer",
+      task: "Analyze",
+      systemPrompt: "Custom system prompt",
+    });
+
+    const compiled = builder.compile();
+    const node = compiled.nodes.get("custom-agent");
+
+    expect(node).toBeDefined();
+  });
+
+  test("model and tools can be specified", () => {
+    const builder = graph<TestState>().subagent({
+      id: "restricted-agent",
+      agent: "codebase-analyzer",
+      task: "Analyze",
+      model: "claude-opus-4",
+      tools: ["bash", "view"],
+    });
+
+    const compiled = builder.compile();
+    const node = compiled.nodes.get("restricted-agent");
+
+    expect(node).toBeDefined();
+    expect(node?.type).toBe("agent");
+  });
+
+  test("outputMapper can be provided", () => {
+    const builder = graph<TestState>().subagent({
+      id: "mapped-agent",
+      agent: "codebase-analyzer",
+      task: "Analyze",
+      outputMapper: (result, state) => ({ message: result.output }),
+    });
+
+    const compiled = builder.compile();
+    const node = compiled.nodes.get("mapped-agent");
+
+    expect(node).toBeDefined();
+  });
+});
+
+// ============================================================================
+// GRAPH BUILDER: .tool() METHOD
+// ============================================================================
+
+describe("GraphBuilder - .tool() method", () => {
+  test("creates a node with type 'tool' and correct ID", () => {
+    const builder = graph<TestState>().tool({
+      id: "fetch-data",
+      execute: async () => ({ data: "result" }),
+    });
+
+    const compiled = builder.compile();
+
+    expect(compiled.nodes.has("fetch-data")).toBe(true);
+    const node = compiled.nodes.get("fetch-data");
+    expect(node?.type).toBe("tool");
+    expect(node?.id).toBe("fetch-data");
+  });
+
+  test("defaults toolName to config.id when not specified", () => {
+    const builder = graph<TestState>().tool({
+      id: "my-tool",
+      execute: async () => ({}),
+    });
+
+    const compiled = builder.compile();
+    const node = compiled.nodes.get("my-tool");
+
+    expect(node).toBeDefined();
+    expect(node?.type).toBe("tool");
+    // The toolName should default to the id
+    expect(node?.name).toBe("my-tool");
+  });
+
+  test("uses explicit toolName when provided", () => {
+    const builder = graph<TestState>().tool({
+      id: "fetch-tool",
+      toolName: "http_fetch",
+      execute: async () => ({}),
+    });
+
+    const compiled = builder.compile();
+    const node = compiled.nodes.get("fetch-tool");
+
+    expect(node).toBeDefined();
+    expect(node?.name).toBe("http_fetch");
+  });
+
+  test("first .tool() call auto-sets as start node", () => {
+    const builder = graph<TestState>().tool({
+      id: "first-tool",
+      execute: async () => ({}),
+    });
+
+    const compiled = builder.compile();
+
+    expect(compiled.startNode).toBe("first-tool");
+  });
+
+  test("chaining: .tool().tool() creates two nodes with an edge", () => {
+    const builder = graph<TestState>()
+      .tool({
+        id: "tool1",
+        execute: async () => ({ result: 1 }),
+      })
+      .tool({
+        id: "tool2",
+        execute: async () => ({ result: 2 }),
+      });
+
+    const compiled = builder.compile();
+
+    // Both nodes should exist
+    expect(compiled.nodes.has("tool1")).toBe(true);
+    expect(compiled.nodes.has("tool2")).toBe(true);
+
+    // Should have an edge from tool1 to tool2
+    const edge = compiled.edges.find((e) => e.from === "tool1" && e.to === "tool2");
+    expect(edge).toBeDefined();
+  });
+
+  test("execute function is passed through correctly", () => {
+    const executeFn = async () => ({ data: "test" });
+    
+    const builder = graph<TestState>().tool({
+      id: "exec-tool",
+      execute: executeFn,
+    });
+
+    const compiled = builder.compile();
+    const node = compiled.nodes.get("exec-tool");
+
+    expect(node).toBeDefined();
+    expect(node?.execute).toBeTypeOf("function");
+  });
+
+  test("config fields (name, description, retry, timeout) are passed through", () => {
+    const builder = graph<TestState>().tool({
+      id: "my-tool",
+      execute: async () => ({}),
+      name: "Data Fetcher",
+      description: "Fetches data from API",
+      retry: { maxAttempts: 5, backoffMs: 500, backoffMultiplier: 2 },
+      timeout: 30000,
+    });
+
+    const compiled = builder.compile();
+    const node = compiled.nodes.get("my-tool");
+
+    expect(node?.name).toBe("Data Fetcher");
+    expect(node?.description).toBe("Fetches data from API");
+    expect(node?.retry?.maxAttempts).toBe(5);
+    expect(node?.retry?.backoffMs).toBe(500);
+  });
+
+  test("args can be a static object", () => {
+    const builder = graph<TestState>().tool({
+      id: "static-args-tool",
+      execute: async (args: { url: string }) => ({ data: args.url }),
+      args: { url: "https://example.com" },
+    });
+
+    const compiled = builder.compile();
+    const node = compiled.nodes.get("static-args-tool");
+
+    expect(node).toBeDefined();
+  });
+
+  test("args can be a function that resolves from state", () => {
+    const builder = graph<TestState>().tool({
+      id: "dynamic-args-tool",
+      execute: async (args: { message: string }) => ({ result: args.message }),
+      args: (state) => ({ message: state.message }),
+    });
+
+    const compiled = builder.compile();
+    const node = compiled.nodes.get("dynamic-args-tool");
+
+    expect(node).toBeDefined();
+  });
+
+  test("outputMapper can be provided", () => {
+    const builder = graph<TestState>().tool({
+      id: "mapped-tool",
+      execute: async () => ({ value: 42 }),
+      outputMapper: (result, state) => ({ count: result.value }),
+    });
+
+    const compiled = builder.compile();
+    const node = compiled.nodes.get("mapped-tool");
+
+    expect(node).toBeDefined();
+  });
+});
+
+// ============================================================================
+// GRAPH BUILDER: MIXED CHAINING
+// ============================================================================
+
+describe("GraphBuilder - mixed chaining", () => {
+  test(".subagent().tool().subagent() creates correct 3-node chain", () => {
+    const builder = graph<TestState>()
+      .subagent({
+        id: "agent1",
+        agent: "codebase-analyzer",
+        task: "Analyze",
+      })
+      .tool({
+        id: "tool1",
+        execute: async () => ({}),
+      })
+      .subagent({
+        id: "agent2",
+        agent: "codebase-locator",
+        task: "Locate",
+      });
+
+    const compiled = builder.compile();
+
+    // All three nodes should exist
+    expect(compiled.nodes.has("agent1")).toBe(true);
+    expect(compiled.nodes.has("tool1")).toBe(true);
+    expect(compiled.nodes.has("agent2")).toBe(true);
+
+    // Check edges: agent1 -> tool1 -> agent2
+    const edge1 = compiled.edges.find((e) => e.from === "agent1" && e.to === "tool1");
+    const edge2 = compiled.edges.find((e) => e.from === "tool1" && e.to === "agent2");
+
+    expect(edge1).toBeDefined();
+    expect(edge2).toBeDefined();
+
+    // Start node should be agent1
+    expect(compiled.startNode).toBe("agent1");
+  });
+
+  test(".tool().subagent().tool() creates correct 3-node chain", () => {
+    const builder = graph<TestState>()
+      .tool({
+        id: "tool1",
+        execute: async () => ({}),
+      })
+      .subagent({
+        id: "agent1",
+        agent: "codebase-analyzer",
+        task: "Analyze",
+      })
+      .tool({
+        id: "tool2",
+        execute: async () => ({}),
+      });
+
+    const compiled = builder.compile();
+
+    // All three nodes should exist
+    expect(compiled.nodes.has("tool1")).toBe(true);
+    expect(compiled.nodes.has("agent1")).toBe(true);
+    expect(compiled.nodes.has("tool2")).toBe(true);
+
+    // Check edges: tool1 -> agent1 -> tool2
+    const edge1 = compiled.edges.find((e) => e.from === "tool1" && e.to === "agent1");
+    const edge2 = compiled.edges.find((e) => e.from === "agent1" && e.to === "tool2");
+
+    expect(edge1).toBeDefined();
+    expect(edge2).toBeDefined();
+
+    // Start node should be tool1
+    expect(compiled.startNode).toBe("tool1");
+  });
+
+  test(".subagent().if(condition).then(node).endif().tool() works with conditionals", () => {
+    const builder = graph<TestState>()
+      .subagent({
+        id: "agent1",
+        agent: "codebase-analyzer",
+        task: "Analyze",
+      })
+      .if((state) => state.flag)
+        .then(testNode2)
+      .endif()
+      .tool({
+        id: "tool1",
+        execute: async () => ({}),
+      });
+
+    const compiled = builder.compile();
+
+    // All nodes should exist
+    expect(compiled.nodes.has("agent1")).toBe(true);
+    expect(compiled.nodes.has("test2")).toBe(true);
+    expect(compiled.nodes.has("tool1")).toBe(true);
+
+    // Should have decision and merge nodes
+    const nodeIds = Array.from(compiled.nodes.keys());
+    const decisionNode = nodeIds.find((id) => id.startsWith("decision_"));
+    const mergeNode = nodeIds.find((id) => id.startsWith("merge_"));
+
+    expect(decisionNode).toBeDefined();
+    expect(mergeNode).toBeDefined();
+
+    // tool1 should be connected after the merge node
+    const edgeToTool = compiled.edges.find((e) => e.from === mergeNode && e.to === "tool1");
+    expect(edgeToTool).toBeDefined();
+  });
+
+  test(".tool().if({ condition, then, else }).subagent() works with config-based conditionals", () => {
+    const builder = graph<TestState>()
+      .tool({
+        id: "tool1",
+        execute: async () => ({}),
+      })
+      .if({
+        condition: (state) => state.flag,
+        then: [testNode2],
+        else: [testNode3],
+      })
+      .subagent({
+        id: "agent1",
+        agent: "codebase-analyzer",
+        task: "Analyze",
+      });
+
+    const compiled = builder.compile();
+
+    // All nodes should exist
+    expect(compiled.nodes.has("tool1")).toBe(true);
+    expect(compiled.nodes.has("test2")).toBe(true);
+    expect(compiled.nodes.has("test3")).toBe(true);
+    expect(compiled.nodes.has("agent1")).toBe(true);
+
+    // agent1 should be connected after the conditional merge
+    const nodeIds = Array.from(compiled.nodes.keys());
+    const mergeNode = nodeIds.find((id) => id.startsWith("merge_"));
+    expect(mergeNode).toBeDefined();
+
+    const edgeToAgent = compiled.edges.find((e) => e.from === mergeNode && e.to === "agent1");
+    expect(edgeToAgent).toBeDefined();
+  });
+});
+
+// ============================================================================
+// GRAPH BUILDER: AUTO ENTRY-POINT DETECTION
+// ============================================================================
+
+describe("GraphBuilder - auto entry-point detection", () => {
+  test("starting with .subagent() (no .start()) sets it as the start node", () => {
+    const builder = graph<TestState>().subagent({
+      id: "entry-agent",
+      agent: "codebase-analyzer",
+      task: "Start here",
+    });
+
+    const compiled = builder.compile();
+
+    expect(compiled.startNode).toBe("entry-agent");
+  });
+
+  test("starting with .tool() (no .start()) sets it as the start node", () => {
+    const builder = graph<TestState>().tool({
+      id: "entry-tool",
+      execute: async () => ({}),
+    });
+
+    const compiled = builder.compile();
+
+    expect(compiled.startNode).toBe("entry-tool");
+  });
+
+  test("explicit .start() takes precedence over auto-detection", () => {
+    const builder = graph<TestState>()
+      .start(testNode1)
+      .subagent({
+        id: "agent1",
+        agent: "codebase-analyzer",
+        task: "Not the start",
+      });
+
+    const compiled = builder.compile();
+
+    expect(compiled.startNode).toBe("test1");
+  });
+
+  test("chaining after .subagent() does not change start node", () => {
+    const builder = graph<TestState>()
+      .subagent({
+        id: "agent1",
+        agent: "codebase-analyzer",
+        task: "First",
+      })
+      .tool({
+        id: "tool1",
+        execute: async () => ({}),
+      })
+      .subagent({
+        id: "agent2",
+        agent: "codebase-locator",
+        task: "Second",
+      });
+
+    const compiled = builder.compile();
+
+    // Start node should still be the first one (agent1)
+    expect(compiled.startNode).toBe("agent1");
+  });
+
+  test("chaining after .tool() does not change start node", () => {
+    const builder = graph<TestState>()
+      .tool({
+        id: "tool1",
+        execute: async () => ({}),
+      })
+      .subagent({
+        id: "agent1",
+        agent: "codebase-analyzer",
+        task: "Second",
+      })
+      .tool({
+        id: "tool2",
+        execute: async () => ({}),
+      });
+
+    const compiled = builder.compile();
+
+    // Start node should still be the first one (tool1)
+    expect(compiled.startNode).toBe("tool1");
+  });
+});
diff --git a/src/graph/builder.ts b/src/workflows/graph/builder.ts
similarity index 63%
rename from src/graph/builder.ts
rename to src/workflows/graph/builder.ts
index 9826dca99d..7548c1b042 100644
--- a/src/graph/builder.ts
+++ b/src/workflows/graph/builder.ts
@@ -25,6 +25,8 @@ import type {
   RetryConfig,
   NodeType,
 } from "./types.ts";
+import type { SubagentStreamResult } from "./types.ts";
+import { subagentNode, toolNode } from "./nodes.ts";
 
 // ============================================================================
 // LOOP CONFIGURATION
@@ -85,6 +87,97 @@ export interface ParallelConfig<TState extends BaseState = BaseState> {
   merge?: (results: Map<NodeId, unknown>, state: TState) => Partial<TState>;
 }
 
+// ============================================================================
+// SUBAGENT CONFIG (for .subagent() builder method)
+// ============================================================================
+
+/**
+ * Configuration for the .subagent() builder method.
+ * Creates a subagent node from a config object.
+ *
+ * @template TState - The state type for the workflow
+ */
+export interface SubAgentConfig<TState extends BaseState> {
+  /** Unique identifier for this node */
+  id: string;
+  /** Agent name resolved from SubagentTypeRegistry */
+  agent: string;
+  /** Task prompt — static string or state-derived function */
+  task: string | ((state: TState) => string);
+  /** Override the agent's system prompt */
+  systemPrompt?: string | ((state: TState) => string);
+  /** Model override */
+  model?: string;
+  /** Tool allowlist */
+  tools?: string[];
+  /** Map agent result to state update */
+  outputMapper?: (result: SubagentStreamResult, state: TState) => Partial<TState>;
+  /** Retry configuration */
+  retry?: RetryConfig;
+  /** Human-readable name */
+  name?: string;
+  /** Description of the node */
+  description?: string;
+}
+
+// ============================================================================
+// TOOL CONFIG (for .tool() builder method)
+// ============================================================================
+
+/**
+ * Configuration for the .tool() builder method.
+ * Creates a tool node from a config object.
+ *
+ * @template TState - The state type for the workflow
+ * @template TArgs - Tool argument type
+ * @template TResult - Tool result type
+ */
+export interface ToolBuilderConfig<TState extends BaseState, TArgs = unknown, TResult = unknown> {
+  /** Unique identifier for this node */
+  id: string;
+  /** Name of the tool being executed */
+  toolName?: string;
+  /** Tool execution function */
+  execute?: (args: TArgs, abortSignal?: AbortSignal) => Promise<TResult>;
+  /** Arguments — static object or state-derived function */
+  args?: TArgs | ((state: TState) => TArgs);
+  /** Map tool result to state update */
+  outputMapper?: (result: TResult, state: TState) => Partial<TState>;
+  /** Timeout in milliseconds */
+  timeout?: number;
+  /** Retry configuration */
+  retry?: RetryConfig;
+  /** Human-readable name */
+  name?: string;
+  /** Description of the node */
+  description?: string;
+}
+
+// ============================================================================
+// IF CONFIG (for .if() config-based builder method)
+// ============================================================================
+
+/**
+ * Configuration for the config-based .if() builder method.
+ * Encapsulates conditional logic with then/else_if/else branches containing
+ * NodeDefinition arrays, similar to how .loop() works.
+ *
+ * @template TState - The state type for the workflow
+ */
+export interface IfConfig<TState extends BaseState> {
+  /** Condition that determines which branch to take */
+  condition: (state: TState) => boolean;
+  /** Nodes to execute when condition is true */
+  then: NodeDefinition<TState>[];
+  /** Optional chained else_if conditions */
+  else_if?: {
+    condition: (state: TState) => boolean;
+    then: NodeDefinition<TState>[];
+  }[];
+  /** Nodes to execute when all conditions are false */
+  else?: NodeDefinition<TState>[];
+}
+
 // ============================================================================
 // CONDITIONAL BRANCH STATE
 // ============================================================================
@@ -155,6 +248,12 @@ export class GraphBuilder<TState extends BaseState = BaseState> {
   /** Counter for generating unique node IDs */
   private nodeCounter = 0;
 
+  /** Pending edge condition for the next then() call (used by loop exit) */
+  private pendingEdgeCondition?: EdgeCondition<TState>;
+
+  /** Pending edge label for the next then() call */
+  private pendingEdgeLabel?: string;
+
   /** Error handler node ID */
   private errorHandlerId: NodeId | null = null;
 
@@ -197,7 +296,11 @@ export class GraphBuilder<TState extends BaseState = BaseState> {
     options?: {
       name?: string;
       description?: string;
+      inputSchema?: NodeDefinition<TState>["inputSchema"];
+      outputSchema?: NodeDefinition<TState>["outputSchema"];
       retry?: RetryConfig;
+      onError?: NodeDefinition<TState>["onError"];
+      isRecoveryNode?: boolean;
     }
   ): NodeDefinition<TState> {
     return {
@@ -260,7 +363,10 @@ export class GraphBuilder<TState extends BaseState = BaseState> {
       }
     } else if (this.currentNodeId !== null) {
       // Normal case - connect from current node
-      this.addEdge(this.currentNodeId, node.id);
+      // Use pending edge condition if set (e.g., loop exit edge)
+      this.addEdge(this.currentNodeId, node.id, this.pendingEdgeCondition, this.pendingEdgeLabel);
+      this.pendingEdgeCondition = undefined;
+      this.pendingEdgeLabel = undefined;
     }
 
     this.currentNodeId = node.id;
@@ -274,32 +380,126 @@ export class GraphBuilder<TState extends BaseState = BaseState> {
    * @param condition - Function that returns true if the if-branch should be taken
    * @returns this for chaining
    */
-  if(condition: EdgeCondition<TState>): this {
-    if (this.currentNodeId === null) {
-      throw new Error("Cannot use if() without a preceding node. Use start() first.");
+  if(condition: EdgeCondition<TState>): this;
+
+  /**
+   * Begin a conditional branch using config-based syntax.
+   *
+   * @param config - Configuration object with condition, then, else_if, and else branches
+   * @returns this for chaining
+   */
+  if(config: IfConfig<TState>): this;
+
+  /**
+   * Begin a conditional branch (implementation).
+   *
+   * Supports two modes:
+   * 1. Function-based: .if(condition).then(...).else().then(...).endif()
+   * 2. Config-based: .if({ condition, then: [...], else_if: [...], else: [...] })
+   *
+   * @param conditionOrConfig - Either a condition function or a config object
+   * @returns this for chaining
+   */
+  if(conditionOrConfig: EdgeCondition<TState> | IfConfig<TState>): this {
+    // Check if it's a function (existing behavior) or object (config-based)
+    if (typeof conditionOrConfig === "function") {
+      // Function-based: existing implementation
+      if (this.currentNodeId === null) {
+        throw new Error("Cannot use if() without a preceding node. Use start() first.");
+      }
+
+      // Create a decision node
+      const decisionNodeId = this.generateNodeId("decision");
+      const decisionNode = this.createNode(decisionNodeId, "decision", async (_ctx) => {
+        // Decision nodes just mark decision points
+        // The actual routing is handled by edges with conditions
+        return {};
+      });
+
+      this.addNode(decisionNode);
+      this.addEdge(this.currentNodeId, decisionNodeId);
+
+      // Push branch state
+      this.conditionalStack.push({
+        decisionNodeId,
+        condition: conditionOrConfig,
+        inElseBranch: false,
+      });
+
+      // Current node is now the decision node, but we don't connect directly
+      // The first then() in the if branch will set ifBranchStart
+      this.currentNodeId = null;
+
+      return this;
     }
 
-    // Create a decision node
-    const decisionNodeId = this.generateNodeId("decision");
-    const decisionNode = this.createNode(decisionNodeId, "decision", async (_ctx) => {
-      // Decision nodes just mark decision points
-      // The actual routing is handled by edges with conditions
-      return {};
-    });
+    // Config-based: build conditional structure from config
+    const config = conditionOrConfig as IfConfig<TState>;
 
-    this.addNode(decisionNode);
-    this.addEdge(this.currentNodeId, decisionNodeId);
+    // Start the if statement with the main condition
+    this.if(config.condition);
 
-    // Push branch state
-    this.conditionalStack.push({
-      decisionNodeId,
-      condition,
-      inElseBranch: false,
-    });
+    // Add nodes from the 'then' branch
+    for (const node of config.then) {
+      this.then(node);
+    }
 
-    // Current node is now the decision node, but we don't connect directly
-    // The first then() in the if branch will set ifBranchStart
-    this.currentNodeId = null;
+    // Handle else_if chains and else branch
+    if (config.else_if && config.else_if.length > 0) {
+      // Start else branch of main if
+      this.else();
+
+      // Build nested if-else chain for else_if conditions
+      // Each else_if becomes: else { pass-through; if (cond) { ... } else { ... } }
+      
+      for (let i = 0; i < config.else_if.length; i++) {
+        const elseIf = config.else_if[i];
+        if (!elseIf) continue;
+        
+        // Add a pass-through node to set currentNodeId (needed before .if())
+        const passThroughId = this.generateNodeId("pass");
+        const passThroughNode = this.createNode(passThroughId, "decision", async () => ({}));
+        this.then(passThroughNode);
+        
+        // Start nested if for this else_if condition
+        this.if(elseIf.condition);
+        
+        // Add nodes from this else_if's then branch
+        for (const node of elseIf.then) {
+          this.then(node);
+        }
+        
+        // Check if there are more else_if entries or a final else
+        const hasMore = i < config.else_if.length - 1 || (config.else && config.else.length > 0);
+        
+        if (hasMore) {
+          // More conditions to check - start else branch for next iteration
+          this.else();
+        }
+      }
+      
+      // Handle final else branch (after all else_if conditions)
+      if (config.else && config.else.length > 0) {
+        // We're already in the else branch from the last iteration
+        for (const node of config.else) {
+          this.then(node);
+        }
+      }
+      
+      // Close all the nested if statements (one for each else_if)
+      for (let i = 0; i < config.else_if.length; i++) {
+        this.endif();
+      }
+    } else if (config.else && config.else.length > 0) {
+      // No else_if, just handle else
+      this.else();
+      for (const node of config.else) {
+        this.then(node);
+      }
+    }
+
+    // Close the main conditional
+    this.endif();
 
     return this;
   }
@@ -539,8 +739,15 @@ export class GraphBuilder<TState extends BaseState = BaseState> {
       "loop-continue"
     );
 
-    // The exit edge will be added by the next then() or end()
+    // The exit edge will be added by the next then() or end(), with a
+    // conditional guard so the reviewer only runs when the loop terminates.
     this.currentNodeId = loopCheckId;
+    this.pendingEdgeCondition = (state) => {
+      const iterationKey = `${loopStartId}_iteration`;
+      const currentIteration = (state.outputs[iterationKey] as number) ?? 0;
+      return config.until(state) || currentIteration >= maxIterations;
+    };
+    this.pendingEdgeLabel = "loop-exit";
 
     return this;
   }
@@ -573,6 +780,92 @@ export class GraphBuilder<TState extends BaseState = BaseState> {
     return this.then(waitNode);
   }
 
+  /**
+   * Add a subagent node using config object.
+   *
+   * This method creates a subagent node from the provided config and adds it to the chain.
+   * The config's `agent` field is mapped to `agentName` in SubagentNodeConfig.
+   *
+   * @param config - Configuration for the subagent node
+   * @returns this for chaining
+   *
+   * @example
+   * ```typescript
+   * builder.subagent({
+   *   id: "analyze-code",
+   *   agent: "codebase-analyzer",
+   *   task: "Analyze the current codebase structure",
+   *   outputMapper: (result, state) => ({ analysis: result.output })
+   * });
+   * ```
+   */
+  subagent(config: SubAgentConfig<TState>): this {
+    // Convert SubAgentConfig to SubagentNodeConfig
+    // Key mapping: config.agent → agentName
+    const nodeConfig = {
+      id: config.id,
+      agentName: config.agent,
+      task: config.task,
+      systemPrompt: config.systemPrompt,
+      model: config.model,
+      tools: config.tools,
+      outputMapper: config.outputMapper,
+      retry: config.retry,
+      name: config.name,
+      description: config.description,
+    };
+
+    // Create the node using subagentNode factory
+    const node = subagentNode(nodeConfig);
+
+    // Delegate to then() to add the node and connect edges
+    return this.then(node);
+  }
+
+  /**
+   * Add a tool node using config object.
+   *
+   * This method creates a tool node from the provided config and adds it to the chain.
+   * If toolName is not provided in config, it defaults to the node id.
+   *
+   * @param config - Configuration for the tool node
+   * @returns this for chaining
+   *
+   * @example
+   * ```typescript
+   * builder.tool({
+   *   id: "fetch-data",
+   *   toolName: "http_fetch",
+   *   execute: async (args) => fetch(args.url),
+   *   args: (state) => ({ url: state.targetUrl }),
+   *   outputMapper: (result, state) => ({ data: result })
+   * });
+   * ```
+   */
+  tool<TArgs = unknown, TResult = unknown>(
+    config: ToolBuilderConfig<TState, TArgs, TResult>
+  ): this {
+    // Convert ToolBuilderConfig to ToolNodeConfig
+    // Add toolName: config.toolName ?? config.id
+    const nodeConfig = {
+      id: config.id,
+      toolName: config.toolName ?? config.id,
+      execute: config.execute,
+      args: config.args,
+      outputMapper: config.outputMapper,
+      timeout: config.timeout,
+      retry: config.retry,
+      name: config.name,
+      description: config.description,
+    };
+
+    // Create the node using toolNode factory
+    const node = toolNode(nodeConfig);
+
+    // Delegate to then() to add the node and connect edges
+    return this.then(node);
+  }
+
   /**
    * Set an error handler node.
    *
@@ -705,7 +998,7 @@ export function graph<TState extends BaseState = BaseState>(): GraphBuilder<TSta
  * @param id - Node ID
  * @param type - Node type
  * @param execute - Execution function
- * @param options - Optional name, description, retry config
+ * @param options - Optional metadata, schemas, retry config, error hook, and recovery marker
  * @returns A NodeDefinition
  */
 export function createNode<TState extends BaseState = BaseState>(
@@ -715,7 +1008,11 @@ export function createNode<TState extends BaseState = BaseState>(
   options?: {
     name?: string;
     description?: string;
+    inputSchema?: NodeDefinition<TState>["inputSchema"];
+    outputSchema?: NodeDefinition<TState>["outputSchema"];
     retry?: RetryConfig;
+    onError?: NodeDefinition<TState>["onError"];
+    isRecoveryNode?: boolean;
   }
 ): NodeDefinition<TState> {
   return {
diff --git a/src/graph/checkpointer.ts b/src/workflows/graph/checkpointer.ts
similarity index 99%
rename from src/graph/checkpointer.ts
rename to src/workflows/graph/checkpointer.ts
index 8d48274ef5..abc55e5c92 100644
--- a/src/graph/checkpointer.ts
+++ b/src/workflows/graph/checkpointer.ts
@@ -593,14 +593,14 @@ export class ResearchDirSaver<TState extends BaseState = BaseState>
 // ============================================================================
 
 /**
- * Session directory checkpointer for Ralph sessions.
+ * Session directory checkpointer for workflow sessions.
  *
  * This checkpointer saves checkpoints to the session's checkpoints directory,
  * using sequential naming (node-001.json, node-002.json, etc.).
  *
  * Storage structure:
  * ```
- * .ralph/sessions/{sessionId}/
+ * .atomic/workflows/sessions/{sessionId}/
  *   checkpoints/
  *     node-001.json
  *     node-002.json
@@ -943,7 +943,7 @@ export interface CreateCheckpointerOptions<TState extends BaseState = BaseState>
  * const file = createCheckpointer("file", { baseDir: "/tmp/checkpoints" });
  * const research = createCheckpointer("research", { researchDir: "research" });
  * const session = createCheckpointer("session", {
- *   sessionDir: (state) => state.ralphSessionDir
+ *   sessionDir: (state) => state.sessionDir
  * });
  * ```
  */
diff --git a/src/graph/compiled.test.ts b/src/workflows/graph/compiled.test.ts
similarity index 57%
rename from src/graph/compiled.test.ts
rename to src/workflows/graph/compiled.test.ts
index 0ffa36c894..1cc5555e47 100644
--- a/src/graph/compiled.test.ts
+++ b/src/workflows/graph/compiled.test.ts
@@ -3,9 +3,11 @@
  */
 
 import { describe, expect, test } from "bun:test";
+import { z } from "zod";
 import { GraphExecutor, createExecutor, executeGraph, streamGraph, initializeExecutionState, mergeState } from "./compiled.ts";
 import { graph, createNode } from "./builder.ts";
 import type { BaseState, NodeResult, ExecutionContext } from "./types.ts";
+import { SchemaValidationError } from "./errors.ts";
 
 // Test state interface
 interface TestState extends BaseState {
@@ -15,6 +17,16 @@ interface TestState extends BaseState {
   errorCount?: number;
 }
 
+const testStateSchema: z.ZodType<TestState> = z.object({
+  executionId: z.string(),
+  lastUpdated: z.string(),
+  outputs: z.record(z.string(), z.unknown()),
+  counter: z.number().optional(),
+  messages: z.array(z.string()).optional(),
+  flag: z.boolean().optional(),
+  errorCount: z.number().optional(),
+});
+
 describe("initializeExecutionState", () => {
   test("creates a new state with executionId and timestamp", () => {
     const executionId = "test-exec-123";
@@ -446,6 +458,361 @@ describe("GraphExecutor - Error Handling", () => {
     expect(result.status).toBe("failed");
     expect(attempts).toBe(1); // Should not retry non-retryable error
   });
+
+  test("handles node-level onError retry action", async () => {
+    let attempts = 0;
+
+    const retryWithHook = createNode<TestState>(
+      "retry_with_hook",
+      "tool",
+      async () => {
+        attempts++;
+        if (attempts < 2) {
+          throw new Error("retry once");
+        }
+        return { stateUpdate: { counter: attempts } };
+      },
+      {
+        retry: {
+          maxAttempts: 3,
+          backoffMs: 10,
+          backoffMultiplier: 1,
+        },
+        onError: async () => ({ action: "retry", delay: 1 }),
+      }
+    );
+
+    const workflow = graph<TestState>()
+      .start(retryWithHook)
+      .end()
+      .compile();
+
+    const result = await executeGraph(workflow);
+
+    expect(result.status).toBe("completed");
+    expect(result.state.counter).toBe(2);
+    expect(attempts).toBe(2);
+  });
+
+  test("handles node-level onError skip action", async () => {
+    const skipOnErrorNode = createNode<TestState>(
+      "skip_on_error",
+      "tool",
+      async () => {
+        throw new Error("skip this node");
+      },
+      {
+        onError: async () => ({ action: "skip", fallbackState: { errorCount: 1 } }),
+      }
+    );
+
+    const afterSkipNode = createNode<TestState>("after_skip", "tool", async (ctx) => {
+      return { stateUpdate: { counter: (ctx.state.counter ?? 0) + 1 } };
+    });
+
+    const workflow = graph<TestState>()
+      .start(skipOnErrorNode)
+      .then(afterSkipNode)
+      .end()
+      .compile();
+
+    const result = await executeGraph(workflow);
+
+    expect(result.status).toBe("completed");
+    expect(result.state.errorCount).toBe(1);
+    expect(result.state.counter).toBe(1);
+  });
+
+  test("handles node-level onError abort action", async () => {
+    const abortOnErrorNode = createNode<TestState>(
+      "abort_on_error",
+      "tool",
+      async () => {
+        throw new Error("original error");
+      },
+      {
+        onError: async () => ({ action: "abort", error: new Error("aborted by hook") }),
+      }
+    );
+
+    const workflow = graph<TestState>()
+      .start(abortOnErrorNode)
+      .end()
+      .compile();
+
+    const result = await executeGraph(workflow);
+
+    expect(result.status).toBe("failed");
+    expect(result.snapshot.errors).toHaveLength(1);
+    const executionError = result.snapshot.errors[0]?.error;
+    expect(executionError).toBeInstanceOf(Error);
+    if (executionError instanceof Error) {
+      expect(executionError.message).toBe("aborted by hook");
+    }
+  });
+
+  test("handles node-level onError goto action", async () => {
+    const failAndGotoRecovery = createNode<TestState>(
+      "fail_then_goto",
+      "tool",
+      async () => {
+        throw new Error("trigger recovery");
+      },
+      {
+        onError: async () => ({ action: "goto", nodeId: "recovery" }),
+      }
+    );
+
+    const skippedNode = createNode<TestState>("skipped", "tool", async () => {
+      return { stateUpdate: { messages: ["skipped"] } };
+    });
+
+    const recoveryNode = createNode<TestState>(
+      "recovery",
+      "tool",
+      async () => {
+        return { stateUpdate: { messages: ["recovery"] } };
+      },
+      { isRecoveryNode: true }
+    );
+
+    const workflow = graph<TestState>()
+      .start(failAndGotoRecovery)
+      .then(skippedNode)
+      .then(recoveryNode)
+      .end()
+      .compile();
+
+    const result = await executeGraph(workflow);
+
+    expect(result.status).toBe("completed");
+    expect(result.state.messages).toEqual(["recovery"]);
+  });
+
+  test("fails on node-level onError goto when target is not a recovery node", async () => {
+    const failAndGotoNonRecovery = createNode<TestState>(
+      "fail_then_goto_non_recovery",
+      "tool",
+      async () => {
+        throw new Error("trigger invalid recovery");
+      },
+      {
+        onError: async () => ({ action: "goto", nodeId: "non_recovery" }),
+      }
+    );
+
+    const nonRecoveryNode = createNode<TestState>("non_recovery", "tool", async () => {
+      return { stateUpdate: { messages: ["non-recovery"] } };
+    });
+
+    const workflow = graph<TestState>()
+      .start(failAndGotoNonRecovery)
+      .then(nonRecoveryNode)
+      .end()
+      .compile();
+
+    const result = await executeGraph(workflow);
+
+    expect(result.status).toBe("failed");
+    expect(result.snapshot.errors).toHaveLength(1);
+    const executionError = result.snapshot.errors[0]?.error;
+    expect(executionError).toBeInstanceOf(Error);
+    if (executionError instanceof Error) {
+      expect(executionError.message).toContain(
+        'onError goto target "non_recovery" must set isRecoveryNode: true'
+      );
+    }
+  });
+
+  test("fails on node-level onError goto when target node does not exist", async () => {
+    const failAndGotoMissing = createNode<TestState>(
+      "fail_then_goto_missing",
+      "tool",
+      async () => {
+        throw new Error("trigger missing recovery");
+      },
+      {
+        onError: async () => ({ action: "goto", nodeId: "missing_recovery" }),
+      }
+    );
+
+    const workflow = graph<TestState>()
+      .start(failAndGotoMissing)
+      .end()
+      .compile();
+
+    const result = await executeGraph(workflow);
+
+    expect(result.status).toBe("failed");
+    expect(result.snapshot.errors).toHaveLength(1);
+    const executionError = result.snapshot.errors[0]?.error;
+    expect(executionError).toBeInstanceOf(Error);
+    if (executionError instanceof Error) {
+      expect(executionError.message).toContain(
+        'onError goto target "missing_recovery" not found in graph'
+      );
+    }
+  });
+});
+
+describe("GraphExecutor - ErrorAction Routing", () => {
+  test("routes retry action back to the failing node before continuing", async () => {
+    let attempts = 0;
+
+    const retryActionNode = createNode<TestState>(
+      "retry_action",
+      "tool",
+      async () => {
+        attempts++;
+        if (attempts === 1) {
+          throw new Error("retry once");
+        }
+        return { stateUpdate: { counter: attempts } };
+      },
+      {
+        retry: {
+          maxAttempts: 2,
+          backoffMs: 1,
+          backoffMultiplier: 1,
+        },
+        onError: async () => ({ action: "retry", delay: 0 }),
+      }
+    );
+
+    const afterRetry = createNode<TestState>("after_retry", "tool", async (ctx) => {
+      return { stateUpdate: { counter: (ctx.state.counter ?? 0) + 1 } };
+    });
+
+    const workflow = graph<TestState>()
+      .start(retryActionNode)
+      .then(afterRetry)
+      .end()
+      .compile();
+
+    const visited: string[] = [];
+    let finalState: TestState | undefined;
+
+    for await (const step of streamGraph(workflow)) {
+      visited.push(step.nodeId);
+      finalState = step.state;
+    }
+
+    expect(visited).toEqual(["retry_action", "after_retry"]);
+    expect(finalState?.counter).toBe(3);
+    expect(attempts).toBe(2);
+  });
+
+  test("routes skip action to downstream edge with fallback state", async () => {
+    const skipActionNode = createNode<TestState>(
+      "skip_action",
+      "tool",
+      async () => {
+        throw new Error("skip this");
+      },
+      {
+        onError: async () => ({ action: "skip", fallbackState: { messages: ["skipped"] } }),
+      }
+    );
+
+    const afterSkipRoute = createNode<TestState>("after_skip_route", "tool", async (ctx) => {
+      return { stateUpdate: { messages: [...(ctx.state.messages ?? []), "after"] } };
+    });
+
+    const workflow = graph<TestState>()
+      .start(skipActionNode)
+      .then(afterSkipRoute)
+      .end()
+      .compile();
+
+    const visited: string[] = [];
+    let finalState: TestState | undefined;
+
+    for await (const step of streamGraph(workflow)) {
+      visited.push(step.nodeId);
+      finalState = step.state;
+    }
+
+    expect(visited).toEqual(["skip_action", "after_skip_route"]);
+    expect(finalState?.messages).toEqual(["skipped", "after"]);
+  });
+
+  test("routes abort action to terminal failed status", async () => {
+    const abortActionNode = createNode<TestState>(
+      "abort_action",
+      "tool",
+      async () => {
+        throw new Error("original");
+      },
+      {
+        onError: async () => ({ action: "abort", error: new Error("abort now") }),
+      }
+    );
+
+    const shouldNotRun = createNode<TestState>("should_not_run", "tool", async () => {
+      return { stateUpdate: { counter: 999 } };
+    });
+
+    const workflow = graph<TestState>()
+      .start(abortActionNode)
+      .then(shouldNotRun)
+      .end()
+      .compile();
+
+    const visited: string[] = [];
+    let finalStatus: string | undefined;
+
+    for await (const step of streamGraph(workflow)) {
+      visited.push(step.nodeId);
+      finalStatus = step.status;
+    }
+
+    expect(visited).toEqual(["abort_action"]);
+    expect(finalStatus).toBe("failed");
+  });
+
+  test("routes goto action directly to recovery node", async () => {
+    const gotoActionNode = createNode<TestState>(
+      "goto_action",
+      "tool",
+      async () => {
+        throw new Error("route to recovery");
+      },
+      {
+        onError: async () => ({ action: "goto", nodeId: "recovery_route" }),
+      }
+    );
+
+    const normalPathNode = createNode<TestState>("normal_path", "tool", async () => {
+      return { stateUpdate: { messages: ["normal"] } };
+    });
+
+    const recoveryRoute = createNode<TestState>(
+      "recovery_route",
+      "tool",
+      async () => {
+        return { stateUpdate: { messages: ["recovery"] } };
+      },
+      { isRecoveryNode: true }
+    );
+
+    const workflow = graph<TestState>()
+      .start(gotoActionNode)
+      .then(normalPathNode)
+      .then(recoveryRoute)
+      .end()
+      .compile();
+
+    const visited: string[] = [];
+    let finalState: TestState | undefined;
+
+    for await (const step of streamGraph(workflow)) {
+      visited.push(step.nodeId);
+      finalState = step.state;
+    }
+
+    expect(visited).toEqual(["goto_action", "recovery_route"]);
+    expect(finalState?.messages).toEqual(["recovery"]);
+  });
 });
 
 describe("GraphExecutor - Signal Handling", () => {
@@ -571,6 +938,45 @@ describe("GraphExecutor - Streaming Execution", () => {
 
     expect(statuses).toEqual(["running", "completed"]);
   });
+
+  test("routes updates mode through GraphExecutor.stream", async () => {
+    const node = createNode<TestState>("node1", "tool", async () => {
+      return { stateUpdate: { counter: 1 } };
+    });
+
+    const workflow = graph<TestState>().start(node).end().compile();
+    const executor = createExecutor(workflow);
+    const events = [];
+
+    for await (const event of executor.stream({ modes: ["updates"] })) {
+      events.push(event);
+    }
+
+    expect(events).toHaveLength(1);
+    expect(events[0]?.mode).toBe("updates");
+    if (events[0]?.mode === "updates") {
+      expect(events[0].update.counter).toBe(1);
+    }
+  });
+
+  test("routes values mode when modes key is undefined", async () => {
+    const node = createNode<TestState>("node1", "tool", async () => {
+      return { stateUpdate: { counter: 1 } };
+    });
+
+    const workflow = graph<TestState>().start(node).end().compile();
+    const events = [];
+
+    for await (const event of streamGraph(workflow, { modes: undefined })) {
+      events.push(event);
+    }
+
+    expect(events).toHaveLength(1);
+    expect(events[0]?.mode).toBe("values");
+    if (events[0]?.mode === "values") {
+      expect(events[0].state.counter).toBe(1);
+    }
+  });
 });
 
 describe("GraphExecutor - Abort and Limits", () => {
@@ -772,3 +1178,145 @@ describe("GraphExecutor - Context Access", () => {
     expect(result.state.outputs.node2).toBe("received: result1");
   });
 });
+
+describe("GraphExecutor - State Validation", () => {
+  test("accepts execution when node inputSchema is satisfied", async () => {
+    const node = createNode<TestState>(
+      "validated-input",
+      "tool",
+      async (ctx) => {
+        return { stateUpdate: { counter: (ctx.state.counter ?? 0) + 1 } };
+      },
+      {
+        inputSchema: testStateSchema.refine(
+          (state) => typeof state.counter === "number" && state.counter >= 1,
+          { message: "counter must be >= 1", path: ["counter"] }
+        ),
+      }
+    );
+
+    const workflow = graph<TestState>()
+      .start(node)
+      .end()
+      .compile();
+
+    const result = await executeGraph(workflow, { initialState: { counter: 1 } });
+
+    expect(result.status).toBe("completed");
+    expect(result.state.counter).toBe(2);
+  });
+
+  test("fails execution when node inputSchema is violated", async () => {
+    let executed = false;
+
+    const node = createNode<TestState>(
+      "invalid-input",
+      "tool",
+      async () => {
+        executed = true;
+        return { stateUpdate: { counter: 5 } };
+      },
+      {
+        inputSchema: testStateSchema.refine(
+          (state) => typeof state.counter === "number" && state.counter >= 1,
+          { message: "counter must be >= 1", path: ["counter"] }
+        ),
+        retry: {
+          maxAttempts: 1,
+          backoffMs: 1,
+          backoffMultiplier: 1,
+        },
+      }
+    );
+
+    const workflow = graph<TestState>()
+      .start(node)
+      .end()
+      .compile();
+
+    const result = await executeGraph(workflow);
+
+    expect(result.status).toBe("failed");
+    expect(executed).toBe(false);
+    expect(result.snapshot.errors[0]?.error).toBeInstanceOf(SchemaValidationError);
+  });
+
+  test("fails execution when node outputSchema is violated", async () => {
+    const node = createNode<TestState>(
+      "invalid-node-output",
+      "tool",
+      async () => {
+        return { stateUpdate: { counter: 1 } };
+      },
+      {
+        outputSchema: testStateSchema.refine(
+          (state) => state.counter === undefined || state.counter >= 2,
+          { message: "counter must be >= 2", path: ["counter"] }
+        ),
+        retry: {
+          maxAttempts: 1,
+          backoffMs: 1,
+          backoffMultiplier: 1,
+        },
+      }
+    );
+
+    const workflow = graph<TestState>()
+      .start(node)
+      .end()
+      .compile();
+
+    const result = await executeGraph(workflow);
+
+    expect(result.status).toBe("failed");
+    expect(result.snapshot.errors[0]?.error).toBeInstanceOf(SchemaValidationError);
+  });
+
+  test("accepts valid state updates when outputSchema is configured", async () => {
+    const node = createNode<TestState>("valid", "tool", async () => {
+      return { stateUpdate: { counter: 2 } };
+    });
+
+    const workflow = graph<TestState>()
+      .start(node)
+      .end()
+      .compile({ outputSchema: testStateSchema });
+
+    const result = await executeGraph(workflow);
+
+    expect(result.status).toBe("completed");
+    expect(result.state.counter).toBe(2);
+  });
+
+  test("fails execution when state update violates outputSchema", async () => {
+    const node = createNode<TestState>(
+      "invalid",
+      "tool",
+      async () => {
+        return { stateUpdate: { counter: 1 } };
+      },
+      {
+        retry: {
+          maxAttempts: 1,
+          backoffMs: 1,
+          backoffMultiplier: 1,
+        },
+      }
+    );
+
+    const workflow = graph<TestState>()
+      .start(node)
+      .end()
+      .compile({
+        outputSchema: testStateSchema.refine(
+          (state) => state.counter === undefined || state.counter >= 2,
+          { message: "counter must be >= 2", path: ["counter"] }
+        ),
+      });
+
+    const result = await executeGraph(workflow);
+
+    expect(result.status).toBe("failed");
+    expect(result.snapshot.errors[0]?.error).toBeInstanceOf(SchemaValidationError);
+  });
+});
diff --git a/src/graph/compiled.ts b/src/workflows/graph/compiled.ts
similarity index 76%
rename from src/graph/compiled.ts
rename to src/workflows/graph/compiled.ts
index 2b355cfe2d..b3926160cf 100644
--- a/src/graph/compiled.ts
+++ b/src/workflows/graph/compiled.ts
@@ -33,7 +33,10 @@ import {
   trackWorkflowExecution,
   type WorkflowTracker,
   type WorkflowTelemetryConfig,
-} from "../telemetry/graph-integration.ts";
+} from "../../telemetry/graph-integration.ts";
+import { StateValidator } from "./state-validator.ts";
+import type { StreamEvent, StreamMode } from "./stream.ts";
+import { routeStream } from "./stream.ts";
 
 // ============================================================================
 // EXECUTION TYPES
@@ -87,6 +90,27 @@ export interface StepResult<TState extends BaseState = BaseState> {
 
   /** Any error that occurred */
   error?: ExecutionError;
+
+  /** Total execution time for this node in milliseconds */
+  executionTime?: number;
+
+  /** Number of retries before this step succeeded */
+  retryCount?: number;
+
+  /** Resolved model used for this node execution */
+  modelUsed?: string;
+
+  /** Custom events emitted by the node during execution */
+  emittedEvents?: EmittedEvent[];
+}
+
+/**
+ * Custom event emitted by a node execution context.
+ */
+export interface EmittedEvent {
+  type: string;
+  data: Record<string, unknown>;
+  timestamp: number;
 }
 
 /**
@@ -105,6 +129,22 @@ export interface ExecutionResult<TState extends BaseState = BaseState> {
   snapshot: ExecutionSnapshot<TState>;
 }
 
+interface NodeExecutionResult<TState extends BaseState = BaseState> {
+  result: NodeResult<TState>;
+  retryCount: number;
+  modelUsed?: string;
+  emittedEvents: EmittedEvent[];
+}
+
+type RoutedExecutionOptions<TState extends BaseState = BaseState> =
+  ExecutionOptions<TState> & { modes: StreamMode[] | undefined };
+
+function hasRoutedModes<TState extends BaseState = BaseState>(
+  options: ExecutionOptions<TState> | RoutedExecutionOptions<TState>
+): options is RoutedExecutionOptions<TState> {
+  return Object.prototype.hasOwnProperty.call(options, "modes");
+}
+
 // ============================================================================
 // HELPER FUNCTIONS
 // ============================================================================
@@ -213,6 +253,7 @@ export function mergeState<TState extends BaseState>(
 export class GraphExecutor<TState extends BaseState = BaseState> {
   private readonly graph: CompiledGraph<TState>;
   private readonly config: GraphConfig<TState>;
+  private readonly stateValidator: StateValidator<TState>;
 
   constructor(graph: CompiledGraph<TState>) {
     this.graph = graph;
@@ -221,6 +262,7 @@ export class GraphExecutor<TState extends BaseState = BaseState> {
       ...DEFAULT_GRAPH_CONFIG,
       ...graph.config,
     } as GraphConfig<TState>;
+    this.stateValidator = StateValidator.fromGraphConfig(this.config);
   }
 
   /**
@@ -261,9 +303,25 @@ export class GraphExecutor<TState extends BaseState = BaseState> {
    * Execute the graph as a stream, yielding after each node.
    *
    * @param options - Execution options
-   * @yields StepResult for each executed node
+   * @yields StepResult for each executed node by default
+   * @yields StreamEvent when stream modes are provided
    */
-  async *stream(options: ExecutionOptions<TState> = {}): AsyncGenerator<StepResult<TState>> {
+  stream(options?: ExecutionOptions<TState>): AsyncGenerator<StepResult<TState>>;
+  stream(options: RoutedExecutionOptions<TState>): AsyncGenerator<StreamEvent<TState>>;
+  async *stream(
+    options: ExecutionOptions<TState> | RoutedExecutionOptions<TState> = {}
+  ): AsyncGenerator<StepResult<TState> | StreamEvent<TState>> {
+    if (hasRoutedModes(options)) {
+      yield* routeStream(this.streamSteps(options), options.modes);
+      return;
+    }
+
+    yield* this.streamSteps(options);
+  }
+
+  private async *streamSteps(
+    options: ExecutionOptions<TState> = {}
+  ): AsyncGenerator<StepResult<TState>> {
     const executionId = options.executionId ?? generateExecutionId();
     const maxSteps = options.maxSteps ?? 1000;
     const workflowStartTime = Date.now();
@@ -350,11 +408,13 @@ export class GraphExecutor<TState extends BaseState = BaseState> {
       }
 
       // Execute node with retry
+      let executionResult: NodeExecutionResult<TState>;
       let result: NodeResult<TState>;
       let nodeError: ExecutionError | undefined;
 
       try {
-        result = await this.executeWithRetry(node, state, errors, options.abortSignal);
+        executionResult = await this.executeWithRetry(node, state, errors, options.abortSignal);
+        result = executionResult.result;
       } catch (error) {
         nodeError = {
           nodeId: currentNodeId,
@@ -414,6 +474,10 @@ export class GraphExecutor<TState extends BaseState = BaseState> {
             state,
             result,
             status: "paused",
+            executionTime: Date.now() - nodeStartTime,
+            retryCount: executionResult.retryCount,
+            modelUsed: executionResult.modelUsed,
+            emittedEvents: executionResult.emittedEvents,
           };
           return;
         }
@@ -471,6 +535,10 @@ export class GraphExecutor<TState extends BaseState = BaseState> {
         state,
         result,
         status: isEndNode ? "completed" : "running",
+        executionTime: Date.now() - nodeStartTime,
+        retryCount: executionResult.retryCount,
+        modelUsed: executionResult.modelUsed,
+        emittedEvents: executionResult.emittedEvents,
       };
 
       if (isEndNode) {
@@ -550,7 +618,7 @@ export class GraphExecutor<TState extends BaseState = BaseState> {
     errors: ExecutionError[],
     abortSignal?: AbortSignal,
     parentContext?: ExecutionContext<TState>
-  ): Promise<NodeResult<TState>> {
+  ): Promise<NodeExecutionResult<TState>> {
     const retryConfig = node.retry ?? DEFAULT_RETRY_CONFIG;
     let lastError: Error | undefined;
     let attempt = 0;
@@ -558,27 +626,40 @@ export class GraphExecutor<TState extends BaseState = BaseState> {
     while (attempt < retryConfig.maxAttempts) {
       attempt++;
 
-      try {
-        // Resolve model for this node
-        const resolvedModel = this.resolveModel(node, parentContext);
+      // Resolve model for this node
+      const resolvedModel = this.resolveModel(node, parentContext);
+      const emittedEvents: EmittedEvent[] = [];
 
-        // Build execution context
-        const context: ExecutionContext<TState> = {
-          state,
-          // Cast config to non-generic type for ExecutionContext compatibility
-          config: this.config as unknown as GraphConfig,
-          errors,
-          abortSignal,
-          model: resolvedModel,
-          emit: (_signal) => {
-            // Signals are collected in the result
-          },
-          getNodeOutput: (nodeId) => state.outputs[nodeId],
-        };
+      // Build execution context
+      const context: ExecutionContext<TState> = {
+        state,
+        // Cast config to non-generic type for ExecutionContext compatibility
+        config: this.config as unknown as GraphConfig,
+        errors,
+        abortSignal,
+        model: resolvedModel,
+        emit: (type: string, data?: Record<string, unknown>) => {
+          emittedEvents.push({
+            type,
+            data: data ?? {},
+            timestamp: Date.now(),
+          });
+        },
+        getNodeOutput: (nodeId) => state.outputs[nodeId],
+      };
+
+      try {
+        this.stateValidator.validateNodeInput(node.id, state, node.inputSchema);
 
         // Execute node
         const result = await node.execute(context);
 
+        if (result.stateUpdate) {
+          const nextState = mergeState(state, result.stateUpdate);
+          this.stateValidator.validateNodeOutput(node.id, nextState, node.outputSchema);
+          this.stateValidator.validate(nextState);
+        }
+
         // Emit progress
         if (this.config.onProgress) {
           this.config.onProgress({
@@ -589,10 +670,65 @@ export class GraphExecutor<TState extends BaseState = BaseState> {
           });
         }
 
-        return result;
+        return {
+          result,
+          retryCount: attempt - 1,
+          modelUsed: resolvedModel,
+          emittedEvents,
+        };
       } catch (error) {
         lastError = error instanceof Error ? error : new Error(String(error));
 
+        if (node.onError) {
+          const action = await node.onError(lastError, context);
+
+          if (action.action === "skip") {
+            return {
+              result: action.fallbackState ? { stateUpdate: action.fallbackState } : {},
+              retryCount: attempt - 1,
+              modelUsed: resolvedModel,
+              emittedEvents,
+            };
+          }
+
+          if (action.action === "abort") {
+            throw action.error ?? lastError;
+          }
+
+          if (action.action === "goto") {
+            const recoveryNode = this.graph.nodes.get(action.nodeId);
+            if (!recoveryNode) {
+              throw new Error(
+                `onError goto target "${action.nodeId}" not found in graph`
+              );
+            }
+            if (!recoveryNode.isRecoveryNode) {
+              throw new Error(
+                `onError goto target "${action.nodeId}" must set isRecoveryNode: true`
+              );
+            }
+            return {
+              result: { goto: action.nodeId },
+              retryCount: attempt - 1,
+              modelUsed: resolvedModel,
+              emittedEvents,
+            };
+          }
+
+          if (attempt >= retryConfig.maxAttempts) {
+            throw lastError;
+          }
+
+          const retryDelay =
+            action.delay ??
+            retryConfig.backoffMs *
+              Math.pow(retryConfig.backoffMultiplier, attempt - 1);
+          if (retryDelay > 0) {
+            await sleep(retryDelay);
+          }
+          continue;
+        }
+
         // Check if we should retry
         if (retryConfig.retryOn && !retryConfig.retryOn(lastError)) {
           throw lastError;
@@ -746,12 +882,21 @@ export async function executeGraph<TState extends BaseState = BaseState>(
  * @template TState - The state type
  * @param graph - The compiled graph
  * @param options - Execution options
- * @yields StepResult for each executed node
+ * @yields StepResult for each executed node by default
+ * @yields StreamEvent when stream modes are provided
  */
-export async function* streamGraph<TState extends BaseState = BaseState>(
+export function streamGraph<TState extends BaseState = BaseState>(
   graph: CompiledGraph<TState>,
   options?: ExecutionOptions<TState>
-): AsyncGenerator<StepResult<TState>> {
+): AsyncGenerator<StepResult<TState>>;
+export function streamGraph<TState extends BaseState = BaseState>(
+  graph: CompiledGraph<TState>,
+  options: RoutedExecutionOptions<TState>
+): AsyncGenerator<StreamEvent<TState>>;
+export async function* streamGraph<TState extends BaseState = BaseState>(
+  graph: CompiledGraph<TState>,
+  options?: ExecutionOptions<TState> | RoutedExecutionOptions<TState>
+): AsyncGenerator<StepResult<TState> | StreamEvent<TState>> {
   const executor = createExecutor(graph);
-  yield* executor.stream(options);
+  yield* executor.stream(options ?? {});
 }
diff --git a/src/graph/errors.ts b/src/workflows/graph/errors.ts
similarity index 100%
rename from src/graph/errors.ts
rename to src/workflows/graph/errors.ts
diff --git a/src/graph/index.ts b/src/workflows/graph/index.ts
similarity index 52%
rename from src/graph/index.ts
rename to src/workflows/graph/index.ts
index 727a3e921b..341fb160a8 100644
--- a/src/graph/index.ts
+++ b/src/workflows/graph/index.ts
@@ -1,224 +1,123 @@
 /**
- * Graph Execution Engine
+ * Graph execution engine public API.
  *
- * This module exports the graph-based workflow execution engine types and utilities.
- * Used for declarative workflow definitions with support for:
- * - Node-based execution (agents, tools, decisions, waits)
- * - State management with typed annotations
- * - Checkpointing and resumption
- * - Human-in-the-loop interactions
- * - Error handling and retry logic
+ * Exports are organized by category to keep the SDK surface easy to navigate.
  */
 
-// Type exports from types.ts
+// === Core graph types and utilities ===
 export type {
-  // Node types
   NodeId,
   NodeType,
   NodeDefinition,
   NodeExecuteFn,
-
-  // State management
   BaseState,
   ContextWindowUsage,
-
-  // Signals
   Signal,
   SignalData,
-
-  // Error handling
   ExecutionError,
+  ErrorAction,
   RetryConfig,
   DebugReport,
-
-  // Node execution
   NodeResult,
   ExecutionContext,
-
-  // Graph configuration
   ProgressEvent,
   GraphConfig,
   Checkpointer,
-
-  // Edge definitions
   EdgeCondition,
   Edge,
-
-  // Compiled graph
   CompiledGraph,
-
-  // Execution state
   ExecutionStatus,
   ExecutionSnapshot,
-
-  // Utility types
   StateOf,
   StateUpdate,
-
-  // Model specification
   ModelSpec,
-
-  // Workflow SDK context
   WorkflowToolContext,
+  CreateSessionFn,
+  SubagentSpawnOptions,
+  SubagentStreamResult,
+  SubagentToolDetail,
 } from "./types.ts";
-
-// Value exports from types.ts
 export {
-  // Type guards
   isNodeType,
   isSignal,
   isExecutionStatus,
   isBaseState,
   isNodeResult,
   isDebugReport,
-
-  // Default configurations
   DEFAULT_RETRY_CONFIG,
   DEFAULT_GRAPH_CONFIG,
   BACKGROUND_COMPACTION_THRESHOLD,
   BUFFER_EXHAUSTION_THRESHOLD,
 } from "./types.ts";
 
-// Type exports from annotation.ts
+// === State management and annotations ===
 export type {
-  // Annotation types
   Reducer,
   Annotation,
   AnnotationRoot,
   ValueOf,
   StateFromAnnotation,
-
-  // Atomic workflow types
   Feature,
   AtomicWorkflowState,
-
-  // Ralph workflow types
-  RalphWorkflowState,
 } from "./annotation.ts";
-
-// Value exports from annotation.ts
 export {
-  // Reducers
   Reducers,
-
-  // Annotation factory
   annotation,
   getDefaultValue,
   applyReducer,
-
-  // State management
   initializeState,
   applyStateUpdate,
-
-  // Atomic workflow
   AtomicStateAnnotation,
   createAtomicState,
   updateAtomicState,
-
-  // Ralph workflow
-  RalphStateAnnotation,
-  createRalphState,
-  updateRalphState,
-
-  // Type guards
   isFeature,
   isAtomicWorkflowState,
-  isRalphWorkflowState,
 } from "./annotation.ts";
 
-// Type exports from builder.ts
-export type {
-  // Loop and parallel configuration
-  LoopConfig,
-  MergeStrategy,
-  ParallelConfig,
-} from "./builder.ts";
-
-// Value exports from builder.ts
+// === Builder and node factories ===
+export type { LoopConfig, MergeStrategy, ParallelConfig, SubAgentConfig, ToolBuilderConfig, IfConfig } from "./builder.ts";
 export {
-  // GraphBuilder class
   GraphBuilder,
-
-  // Factory function
   graph,
-
-  // Helper functions
   createNode,
   createDecisionNode,
   createWaitNode,
 } from "./builder.ts";
-
-// Type exports from nodes.ts
 export type {
-  // Agent node types
-  AgentNodeAgentType,
   OutputMapper,
   AgentNodeConfig,
   ClientProvider,
-
-  // Tool node types
   ToolExecuteFn,
   ToolOutputMapper,
   ToolNodeConfig,
-
-  // Decision node types
   DecisionRoute,
   DecisionNodeConfig,
-
-  // Wait node types
   InputMapper,
   WaitNodeConfig,
-
-  // Clear context node types
   ClearContextNodeConfig,
-
-  // Ask user node types
   AskUserOption,
   AskUserOptions,
   AskUserNodeConfig,
   AskUserWaitState,
   AskUserQuestionEventData,
-
-  // Parallel node types
   ParallelMergeStrategy,
   ParallelMerger,
   ParallelNodeConfig,
   ParallelExecutionContext,
-
-  // Subgraph node types
   CompiledSubgraph,
   SubgraphRef,
   SubgraphNodeConfig,
   WorkflowResolver,
-
-  // Context monitoring types
   ContextCompactionAction,
   ContextMonitoringState,
   ContextMonitorNodeConfig,
   ContextCheckOptions,
-
-  // Custom tool node types
   CustomToolNodeConfig,
-
-  // Subagent node types (workflow SDK)
   SubagentNodeConfig,
   ParallelSubagentNodeConfig,
 } from "./nodes.ts";
-
-// Value exports from nodes.ts
 export {
-  // Client provider
-  setClientProvider,
-  getClientProvider,
-
-  // Workflow resolver for subgraph nodes
-  setWorkflowResolver,
-  getWorkflowResolver,
-
-  // Default configurations
   AGENT_NODE_RETRY_CONFIG,
-
-  // Node factory functions
   agentNode,
   toolNode,
   clearContextNode,
@@ -228,76 +127,78 @@ export {
   parallelNode,
   subgraphNode,
   contextMonitorNode,
-
-  // Context monitoring helpers
   getDefaultCompactionAction,
   toContextWindowUsage,
   isContextThresholdExceeded,
   checkContextUsage,
   compactContext,
-
-  // Custom tool node factory
   customToolNode,
-
-  // Subagent node factories
   subagentNode,
   parallelSubagentNode,
 } from "./nodes.ts";
 
-// Type exports from compiled.ts
+// === Workflow templates ===
+export type { MapReduceOptions, ReviewCycleOptions, TaskLoopOptions } from "./templates.ts";
+export { sequential, mapReduce, reviewCycle, taskLoop } from "./templates.ts";
+
+// === Execution and streaming ===
 export type {
-  // Execution types
   ExecutionOptions,
+  EmittedEvent,
   StepResult,
   ExecutionResult,
 } from "./compiled.ts";
-
-// Value exports from compiled.ts
 export {
-  // Helper functions
   isLoopNode,
   initializeExecutionState,
   mergeState,
-
-  // Executor class
   GraphExecutor,
-
-  // Factory functions
   createExecutor,
   executeGraph,
   streamGraph,
 } from "./compiled.ts";
+export type {
+  StreamMode,
+  StreamOptions,
+  CustomEvent,
+  DebugTrace,
+  StreamEvent,
+} from "./stream.ts";
+export { StreamRouter, routeStream } from "./stream.ts";
+
+// === Validation and errors ===
+export type { StateValidatorConfig } from "./state-validator.ts";
+export { StateValidator } from "./state-validator.ts";
+export type { ErrorFeedback } from "./errors.ts";
+export { SchemaValidationError, NodeExecutionError } from "./errors.ts";
 
-// Type exports from checkpointer.ts
+// === Checkpointing ===
 export type { CheckpointerType, CreateCheckpointerOptions } from "./checkpointer.ts";
-
-// Value exports from checkpointer.ts
 export {
-  // Checkpointer implementations
   MemorySaver,
   FileSaver,
   ResearchDirSaver,
   SessionDirSaver,
-
-  // Factory function
   createCheckpointer,
 } from "./checkpointer.ts";
 
-// Error types from errors.ts
-export type { ErrorFeedback } from "./errors.ts";
-export { SchemaValidationError, NodeExecutionError } from "./errors.ts";
-
-// Subagent registry from subagent-registry.ts
-export type { SubagentEntry } from "./subagent-registry.ts";
-export {
-  getSubagentRegistry,
-  setSubagentRegistry,
-  populateSubagentRegistry,
-} from "./subagent-registry.ts";
-
-// Subagent bridge from subagent-bridge.ts
+// === Providers ===
+export type { AgentProvider } from "./provider-registry.ts";
+export { ProviderRegistry } from "./provider-registry.ts";
+export type {
+  ClaudeAgentProviderOptions,
+  OpenCodeAgentProviderOptions,
+  CopilotAgentProviderOptions,
+  DefaultProviderRegistryOptions,
+} from "./agent-providers.ts";
 export {
-  SubagentGraphBridge,
-  setSubagentBridge,
-  getSubagentBridge,
-} from "./subagent-bridge.ts";
+  ClientBackedAgentProvider,
+  createClaudeAgentProvider,
+  createOpenCodeAgentProvider,
+  createCopilotAgentProvider,
+  createDefaultProviderRegistry,
+} from "./agent-providers.ts";
+
+// === Subagent orchestration ===
+export type { SubagentEntry } from "./subagent-registry.ts";
+export { SubagentTypeRegistry, populateSubagentRegistry } from "./subagent-registry.ts";
diff --git a/src/workflows/graph/nodes.test.ts b/src/workflows/graph/nodes.test.ts
new file mode 100644
index 0000000000..64159b28bd
--- /dev/null
+++ b/src/workflows/graph/nodes.test.ts
@@ -0,0 +1,270 @@
+import { describe, expect, test } from "bun:test";
+import { contextMonitorNode, parallelNode, parallelSubagentNode } from "./nodes.ts";
+import type { BaseState, ContextWindowUsage, ExecutionContext, SubagentStreamResult } from "./types.ts";
+import type { ContextUsage, Session } from "../../sdk/types.ts";
+
+interface TestState extends BaseState {
+  mapperSource?: string;
+}
+
+function createContext(
+  overrides: Partial<TestState> = {},
+  runtimeOverrides: Partial<NonNullable<ExecutionContext<TestState>["config"]["runtime"]>> = {},
+): ExecutionContext<TestState> {
+  return {
+    state: {
+      executionId: "exec-1",
+      lastUpdated: new Date(0).toISOString(),
+      outputs: {},
+      ...overrides,
+    },
+    config: {
+      runtime: runtimeOverrides,
+    },
+    errors: [],
+  };
+}
+
+function createMockSpawnParallel(results: SubagentStreamResult[]) {
+  return async (): Promise<SubagentStreamResult[]> => results;
+}
+
+interface MonitorState extends BaseState {
+  contextWindowUsage: ContextWindowUsage | null;
+}
+
+function createMonitorContext(
+  overrides: Partial<MonitorState> = {},
+): ExecutionContext<MonitorState> {
+  return {
+    state: {
+      executionId: "exec-monitor",
+      lastUpdated: new Date(0).toISOString(),
+      outputs: {},
+      contextWindowUsage: null,
+      ...overrides,
+    },
+    config: {},
+    errors: [],
+  };
+}
+
+function createMockMonitoringSession(options: {
+  usagePercentage: number;
+  hasAutoCompacted: boolean;
+  isCompacting?: boolean;
+}): { session: Session; getSummarizeCalls: () => number } {
+  let summarizeCalls = 0;
+  const usage: ContextUsage = {
+    inputTokens: 60,
+    outputTokens: 0,
+    maxTokens: 100,
+    usagePercentage: options.usagePercentage,
+  };
+  const session: Session = {
+    id: "ses_monitor",
+    send: async () => ({ type: "text", content: "" }),
+    stream: async function* () {},
+    summarize: async () => {
+      summarizeCalls += 1;
+    },
+    getContextUsage: async () => usage,
+    getSystemToolsTokens: () => 0,
+    getCompactionState: () => ({
+      isCompacting: options.isCompacting ?? false,
+      hasAutoCompacted: options.hasAutoCompacted,
+    }),
+    destroy: async () => {},
+  };
+  return {
+    session,
+    getSummarizeCalls: () => summarizeCalls,
+  };
+}
+
+describe("parallelNode mapper standardization", () => {
+  test("uses outputMapper when provided", async () => {
+    const outputMapper = (results: Map<string, unknown>) => ({ mapperSource: `size:${results.size}` });
+    const node = parallelNode<TestState>({
+      id: "parallel",
+      branches: ["branch-a"],
+      outputMapper,
+    });
+
+    const result = await node.execute(createContext());
+    const parallelOutput = result.stateUpdate?.outputs?.parallel;
+    expect(parallelOutput).toBeDefined();
+    const metadata = parallelOutput as {
+      outputMapper?: (results: Map<string, unknown>) => Partial<TestState>;
+      merge?: (results: Map<string, unknown>) => Partial<TestState>;
+    };
+
+    expect(result.goto).toEqual(["branch-a"]);
+    expect(metadata.outputMapper).toBe(outputMapper);
+    expect(metadata.merge).toBe(outputMapper);
+  });
+
+  test("keeps legacy merge as backward-compatible alias", async () => {
+    const merge = (results: Map<string, unknown>) => ({ mapperSource: `legacy:${results.size}` });
+    const node = parallelNode<TestState>({
+      id: "parallel",
+      branches: ["branch-a"],
+      merge,
+    });
+
+    const result = await node.execute(createContext());
+    const parallelOutput = result.stateUpdate?.outputs?.parallel;
+    expect(parallelOutput).toBeDefined();
+    const metadata = parallelOutput as {
+      outputMapper?: (results: Map<string, unknown>) => Partial<TestState>;
+      merge?: (results: Map<string, unknown>) => Partial<TestState>;
+    };
+
+    expect(metadata.outputMapper).toBe(merge);
+    expect(metadata.merge).toBe(merge);
+  });
+});
+
+describe("parallelSubagentNode mapper standardization", () => {
+  const mockResult: SubagentStreamResult = {
+    agentId: "agent-1",
+    success: true,
+    output: "ok",
+    toolUses: 0,
+    durationMs: 1,
+  };
+
+  test("uses outputMapper when provided", async () => {
+    const node = parallelSubagentNode<TestState>({
+      id: "parallel-subagents",
+      agents: [{ agentName: "worker", task: "do work" }],
+      outputMapper: (results) => ({
+        mapperSource: `outputMapper:${results.get("worker-0")?.output ?? "missing"}`,
+      }),
+    });
+
+    const result = await node.execute(createContext({}, {
+      spawnSubagentParallel: createMockSpawnParallel([mockResult]),
+    }));
+    expect(result.stateUpdate?.mapperSource).toBe("outputMapper:ok");
+  });
+
+  test("prefers outputMapper over legacy merge when both are provided", async () => {
+    const node = parallelSubagentNode<TestState>({
+      id: "parallel-subagents",
+      agents: [{ agentName: "worker", task: "do work" }],
+      outputMapper: () => ({ mapperSource: "outputMapper" }),
+      merge: () => ({ mapperSource: "merge" }),
+    });
+
+    const result = await node.execute(createContext({}, {
+      spawnSubagentParallel: createMockSpawnParallel([mockResult]),
+    }));
+    expect(result.stateUpdate?.mapperSource).toBe("outputMapper");
+  });
+
+  test("accepts legacy merge mapper", async () => {
+    const node = parallelSubagentNode<TestState>({
+      id: "parallel-subagents",
+      agents: [{ agentName: "worker", task: "do work" }],
+      merge: () => ({ mapperSource: "merge" }),
+    });
+
+    const result = await node.execute(createContext({}, {
+      spawnSubagentParallel: createMockSpawnParallel([mockResult]),
+    }));
+    expect(result.stateUpdate?.mapperSource).toBe("merge");
+  });
+
+  test("throws when neither outputMapper nor merge is provided", () => {
+    expect(() =>
+      parallelSubagentNode<TestState>({
+        id: "parallel-subagents",
+        agents: [{ agentName: "worker", task: "do work" }],
+      })
+    ).toThrow(/requires outputMapper/);
+  });
+});
+
+describe("contextMonitorNode compaction conflict guard", () => {
+  test("skips summarize when session has already auto-compacted", async () => {
+    const { session, getSummarizeCalls } = createMockMonitoringSession({
+      usagePercentage: 60,
+      hasAutoCompacted: true,
+    });
+    const node = contextMonitorNode<MonitorState>({
+      id: "context-monitor",
+      agentType: "opencode",
+      getSession: () => session,
+    });
+
+    const result = await node.execute(createMonitorContext());
+
+    expect(getSummarizeCalls()).toBe(0);
+    expect(result.stateUpdate?.contextWindowUsage?.usagePercentage).toBe(60);
+  });
+
+  test("summarizes when threshold is exceeded and no compaction conflict exists", async () => {
+    const { session, getSummarizeCalls } = createMockMonitoringSession({
+      usagePercentage: 60,
+      hasAutoCompacted: false,
+    });
+    const node = contextMonitorNode<MonitorState>({
+      id: "context-monitor",
+      agentType: "opencode",
+      getSession: () => session,
+    });
+
+    await node.execute(createMonitorContext());
+
+    expect(getSummarizeCalls()).toBe(1);
+  });
+
+  test("throws when summarize action is selected without a session", async () => {
+    const node = contextMonitorNode<MonitorState>({
+      id: "context-monitor",
+      agentType: "opencode",
+      getSession: () => null,
+      getContextUsage: async () => ({
+        inputTokens: 60,
+        outputTokens: 0,
+        maxTokens: 100,
+        usagePercentage: 60,
+      }),
+    });
+
+    await expect(node.execute(createMonitorContext())).rejects.toThrow(
+      /no session available for summarization/i,
+    );
+  });
+
+  test("surfaces summarize failures instead of downgrading to warning signals", async () => {
+    const session: Session = {
+      id: "ses_monitor_error",
+      send: async () => ({ type: "text", content: "" }),
+      stream: async function* () {},
+      summarize: async () => {
+        throw new Error("Compaction timed out");
+      },
+      getContextUsage: async () => ({
+        inputTokens: 60,
+        outputTokens: 0,
+        maxTokens: 100,
+        usagePercentage: 60,
+      }),
+      getSystemToolsTokens: () => 0,
+      getCompactionState: () => ({
+        isCompacting: false,
+        hasAutoCompacted: false,
+      }),
+      destroy: async () => {},
+    };
+    const node = contextMonitorNode<MonitorState>({
+      id: "context-monitor",
+      agentType: "opencode",
+      getSession: () => session,
+    });
+
+    await expect(node.execute(createMonitorContext())).rejects.toThrow(/compaction timed out/i);
+  });
+});
diff --git a/src/graph/nodes.ts b/src/workflows/graph/nodes.ts
similarity index 91%
rename from src/graph/nodes.ts
rename to src/workflows/graph/nodes.ts
index 677144bae5..3447334475 100644
--- a/src/graph/nodes.ts
+++ b/src/workflows/graph/nodes.ts
@@ -25,23 +25,22 @@ import type {
   ContextWindowUsage,
   WorkflowToolContext,
 } from "./types.ts";
-import type { SessionConfig, AgentMessage, CodingAgentClient, Session, ContextUsage } from "../sdk/types.ts";
+import type { SessionConfig, AgentMessage, CodingAgentClient, Session, ContextUsage } from "../../sdk/types.ts";
 import { DEFAULT_RETRY_CONFIG, BACKGROUND_COMPACTION_THRESHOLD, BUFFER_EXHAUSTION_THRESHOLD } from "./types.ts";
 import type { z } from "zod";
-import { getToolRegistry } from "../sdk/tools/registry.ts";
+import { getToolRegistry } from "../../sdk/tools/registry.ts";
 import { SchemaValidationError, NodeExecutionError } from "./errors.ts";
-import { getSubagentBridge } from "./subagent-bridge.ts";
-import { getSubagentRegistry } from "./subagent-registry.ts";
-import type { SubagentResult, SubagentSpawnOptions } from "./subagent-bridge.ts";
+import type { SubagentStreamResult, SubagentSpawnOptions } from "./types.ts";
+import { pipelineLog } from "../../events/pipeline-logger.ts";
 
 // ============================================================================
 // AGENT NODE
 // ============================================================================
 
 /**
- * Agent types supported by the agent node factory.
+ * Agent type identifier resolved by the client/provider registry.
  */
-export type AgentNodeAgentType = "claude" | "opencode" | "copilot";
+export type AgentNodeAgentType = string;
 
 /**
  * Function to map agent output to state updates.
@@ -106,30 +105,6 @@ export interface AgentNodeConfig<TState extends BaseState = BaseState> {
  */
 export type ClientProvider = (agentType: AgentNodeAgentType) => CodingAgentClient | null;
 
-/**
- * Global client provider for agent nodes.
- * Set this before executing agent nodes.
- */
-let globalClientProvider: ClientProvider | null = null;
-
-/**
- * Set the global client provider for agent nodes.
- *
- * @param provider - Function that returns a client for a given agent type
- */
-export function setClientProvider(provider: ClientProvider): void {
-  globalClientProvider = provider;
-}
-
-/**
- * Get the current global client provider.
- *
- * @returns The current client provider or null
- */
-export function getClientProvider(): ClientProvider | null {
-  return globalClientProvider;
-}
-
 /**
  * Default retry configuration for agent nodes.
  * Uses 3 attempts with 1 second initial backoff and 2x multiplier.
@@ -190,12 +165,12 @@ export function agentNode<TState extends BaseState = BaseState>(
     description,
     retry,
     execute: async (ctx: ExecutionContext<TState>): Promise<NodeResult<TState>> => {
-      const client = globalClientProvider?.(agentType);
+      const client = ctx.config.runtime?.clientProvider?.(agentType);
 
       if (!client) {
         throw new Error(
-          `No client provider set for agent type "${agentType}". ` +
-            "Call setClientProvider() before executing agent nodes."
+          `No client provider configured for agent type "${agentType}". ` +
+            "Initialize WorkflowSDK with providers before executing agent nodes."
         );
       }
 
@@ -864,13 +839,9 @@ export function askUserNode<TState extends BaseState & AskUserWaitState = BaseSt
         nodeId: id,
       };
 
-      // Emit signal if emit function is available
+      // Emit custom event for stream consumers if emit function is available
       if (ctx.emit) {
-        ctx.emit({
-          type: "human_input_required",
-          message: resolvedOptions.question,
-          data: eventData as unknown as Record<string, unknown>,
-        });
+        ctx.emit("human_input_required", eventData as unknown as Record<string, unknown>);
       }
 
       // Return state update with wait flags and emit signal
@@ -936,9 +907,15 @@ export interface ParallelNodeConfig<TState extends BaseState = BaseState> {
   strategy?: ParallelMergeStrategy;
 
   /**
-   * Function to merge branch results into state.
+   * Function to map parallel branch results into state.
    * If not provided, results are stored in outputs[nodeId].
    */
+  outputMapper?: ParallelMerger<TState>;
+
+  /**
+   * @deprecated Use outputMapper instead.
+   * Function to merge branch results into state.
+   */
   merge?: ParallelMerger<TState>;
 
   /** Human-readable name */
@@ -959,7 +936,10 @@ export interface ParallelExecutionContext<TState extends BaseState = BaseState>
   /** Strategy for handling completion */
   strategy: ParallelMergeStrategy;
 
-  /** Optional merge function */
+  /** Optional output mapper function */
+  outputMapper?: ParallelMerger<TState>;
+
+  /** @deprecated Use outputMapper instead */
   merge?: ParallelMerger<TState>;
 }
 
@@ -979,7 +959,7 @@ export interface ParallelExecutionContext<TState extends BaseState = BaseState>
  *   id: "gather-data",
  *   branches: ["fetch-api-1", "fetch-api-2", "fetch-api-3"],
  *   strategy: "all",
- *   merge: (results, state) => ({
+ *   outputMapper: (results, state) => ({
  *     allData: Array.from(results.values()),
  *   }),
  * });
@@ -988,7 +968,8 @@ export interface ParallelExecutionContext<TState extends BaseState = BaseState>
 export function parallelNode<TState extends BaseState = BaseState>(
   config: ParallelNodeConfig<TState>
 ): NodeDefinition<TState> {
-  const { id, branches, strategy = "all", merge, name, description } = config;
+  const { id, branches, strategy = "all", outputMapper, merge, name, description } = config;
+  const resolvedOutputMapper = outputMapper ?? merge;
 
   if (branches.length === 0) {
     throw new Error(`Parallel node "${id}" requires at least one branch`);
@@ -1004,7 +985,8 @@ export function parallelNode<TState extends BaseState = BaseState>(
       const parallelContext: ParallelExecutionContext<TState> = {
         branches,
         strategy,
-        merge,
+        outputMapper: resolvedOutputMapper,
+        merge: resolvedOutputMapper,
       };
 
       // The execution engine will handle actual parallel execution
@@ -1103,40 +1085,14 @@ export interface SubgraphNodeConfig<
  */
 export type WorkflowResolver = (name: string) => CompiledSubgraph<BaseState> | null;
 
-/**
- * Global workflow resolver function.
- * Set this before using subgraphNode with string workflow references.
- */
-let globalWorkflowResolver: WorkflowResolver | null = null;
-
-/**
- * Set the global workflow resolver for subgraph nodes.
- * This should be called during application initialization.
- *
- * @param resolver - Function that resolves workflow name to compiled graph
- */
-export function setWorkflowResolver(resolver: WorkflowResolver): void {
-  globalWorkflowResolver = resolver;
-}
-
-/**
- * Get the current global workflow resolver.
- *
- * @returns The current workflow resolver or null
- */
-export function getWorkflowResolver(): WorkflowResolver | null {
-  return globalWorkflowResolver;
-}
-
 /**
  * Create a subgraph node that executes a nested graph.
  *
  * The subgraph can be specified as:
  * - A CompiledGraph instance (direct execution)
- * - A workflow name string (resolved at runtime via the global workflow resolver)
+ * - A workflow name string (resolved at runtime via the WorkflowSDK resolver)
  *
- * When using a string workflow name, ensure setWorkflowResolver() has been called
- * during application initialization.
+ * When using a string workflow name, ensure the graph runs through WorkflowSDK.
  *
  * @template TState - The state type for the workflow
  * @template TSubState - The state type for the subgraph
@@ -1179,12 +1135,11 @@ export function subgraphNode<
       let resolvedSubgraph: CompiledSubgraph<TSubState>;
 
       if (typeof subgraph === "string") {
-        // Workflow name string - resolve via global resolver
-        const resolver = globalWorkflowResolver;
+        const resolver = ctx.config.runtime?.workflowResolver;
         if (!resolver) {
           throw new Error(
-            `Cannot resolve workflow "${subgraph}": No workflow resolver set. ` +
-              "Call setWorkflowResolver() during application initialization."
+            `Cannot resolve workflow "${subgraph}": No workflow resolver configured. ` +
+              "Execute this graph through WorkflowSDK.init()."
           );
         }
 
@@ -1432,39 +1387,19 @@ export function contextMonitorNode<TState extends ContextMonitoringState = Conte
         case "summarize": {
           // OpenCode: call session.summarize()
           const session = getSession?.(ctx.state);
-          if (session) {
-            try {
-              await session.summarize();
-              onCompaction?.(usage!, action);
-              
-              // Get updated usage after summarization
-              const newUsage = await session.getContextUsage();
-              stateUpdate.contextWindowUsage = newUsage ? toContextWindowUsage(newUsage) : null;
-            } catch (error) {
-              // If summarize fails, emit warning instead
-              signals.push({
-                type: "context_window_warning",
-                message: `Context compaction failed: ${error instanceof Error ? error.message : String(error)}`,
-                data: {
-                  usagePercentage: usage!.usagePercentage,
-                  threshold,
-                  action: "summarize",
-                  error: true,
-                },
-              });
-            }
-          } else {
-            // No session available, emit warning
-            signals.push({
-              type: "context_window_warning",
-              message: `Context usage at ${usage!.usagePercentage.toFixed(1)}% (no session for summarization)`,
-              data: {
-                usagePercentage: usage!.usagePercentage,
-                threshold,
-                action: "warn",
-              },
-            });
+          if (!session) {
+            throw new Error("Context compaction failed: no session available for summarization");
+          }
+          const compactionState = session.getCompactionState?.();
+          if (compactionState?.isCompacting || compactionState?.hasAutoCompacted) {
+            break;
           }
+          await session.summarize();
+          onCompaction?.(usage!, action);
+
+          // Get updated usage after summarization
+          const newUsage = await session.getContextUsage();
+          stateUpdate.contextWindowUsage = newUsage ? toContextWindowUsage(newUsage) : null;
           break;
         }
 
@@ -1693,7 +1628,7 @@ export interface SubagentNodeConfig<TState extends BaseState> {
   systemPrompt?: string | ((state: TState) => string);
   model?: string;
   tools?: string[];
-  outputMapper?: (result: SubagentResult, state: TState) => Partial<TState>;
+  outputMapper?: (result: SubagentStreamResult, state: TState) => Partial<TState>;
   retry?: RetryConfig;
 }
 
@@ -1717,17 +1652,24 @@ export function subagentNode<TState extends BaseState>(
     description: config.description ?? `Sub-agent: ${config.agentName}`,
     retry: config.retry,
     async execute(ctx: ExecutionContext<TState>): Promise<NodeResult<TState>> {
-      const bridge = getSubagentBridge();
-      if (!bridge) {
+      const spawnSubagent = ctx.config.runtime?.spawnSubagent;
+      if (!spawnSubagent) {
         throw new Error(
-          "SubagentGraphBridge not initialized. " +
-          "Ensure setSubagentBridge() is called before graph execution."
+          "spawnSubagent not initialized. " +
+          "Execute this graph through WorkflowSDK.init()."
         );
       }
 
-      const registry = getSubagentRegistry();
+      const registry = ctx.config.runtime?.subagentRegistry;
+      if (!registry) {
+        throw new Error(
+          "SubagentTypeRegistry not initialized. " +
+          "Execute this graph through WorkflowSDK.init()."
+        );
+      }
       const entry = registry.get(config.agentName);
       if (!entry) {
+        pipelineLog("Subagent", "registry_miss", { agentName: config.agentName });
         throw new Error(
           `Sub-agent "${config.agentName}" not found in registry. ` +
           `Available agents: ${registry.getAll().map(a => a.name).join(", ")}`
@@ -1742,7 +1684,7 @@ export function subagentNode<TState extends BaseState>(
         ? config.systemPrompt(ctx.state)
         : config.systemPrompt;
 
-      const result = await bridge.spawn({
+      const result = await spawnSubagent({
         agentId: `${config.id}-${ctx.state.executionId}`,
         agentName: config.agentName,
         task,
@@ -1751,6 +1693,8 @@ export function subagentNode<TState extends BaseState>(
         tools: config.tools,
       });
 
+      pipelineLog("Subagent", "spawn_complete", { agentName: config.agentName, success: result.success });
+
       if (!result.success) {
         throw new Error(
           `Sub-agent "${config.agentName}" failed: ${result.error ?? "Unknown error"}`
@@ -1784,7 +1728,9 @@ export interface ParallelSubagentNodeConfig<TState extends BaseState> {
     model?: string;
     tools?: string[];
   }>;
-  merge: (results: Map<string, SubagentResult>, state: TState) => Partial<TState>;
+  outputMapper?: (results: Map<string, SubagentStreamResult>, state: TState) => Partial<TState>;
+  /** @deprecated Use outputMapper instead */
+  merge?: (results: Map<string, SubagentStreamResult>, state: TState) => Partial<TState>;
   retry?: RetryConfig;
 }
 
@@ -1802,6 +1748,13 @@ export interface ParallelSubagentNodeConfig<TState extends BaseState> {
 export function parallelSubagentNode<TState extends BaseState>(
   config: ParallelSubagentNodeConfig<TState>,
 ): NodeDefinition<TState> {
+  const resolvedOutputMapper = config.outputMapper ?? config.merge;
+  if (!resolvedOutputMapper) {
+    throw new Error(
+      `Parallel sub-agent node "${config.id}" requires outputMapper (or legacy merge)`,
+    );
+  }
+
   return {
     id: config.id,
     type: "parallel",
@@ -1809,9 +1762,11 @@ export function parallelSubagentNode<TState extends BaseState>(
     description: config.description,
     retry: config.retry,
     async execute(ctx: ExecutionContext<TState>): Promise<NodeResult<TState>> {
-      const bridge = getSubagentBridge();
-      if (!bridge) {
-        throw new Error("SubagentGraphBridge not initialized.");
+      const spawnSubagentParallel = ctx.config.runtime?.spawnSubagentParallel;
+      if (!spawnSubagentParallel) {
+        throw new Error(
+          "spawnSubagentParallel not initialized. Execute this graph through WorkflowSDK.init().",
+        );
       }
 
       const spawnOptions: SubagentSpawnOptions[] = config.agents.map((agent, i) => ({
@@ -1823,15 +1778,19 @@ export function parallelSubagentNode<TState extends BaseState>(
         tools: agent.tools,
       }));
 
-      const results = await bridge.spawnParallel(spawnOptions);
+      pipelineLog("Subagent", "parallel_spawn", { count: spawnOptions.length, agents: spawnOptions.map(o => o.agentName) });
+
+      const results = await spawnSubagentParallel(spawnOptions);
+
+      pipelineLog("Subagent", "parallel_complete", { count: results.length });
 
-      const resultMap = new Map<string, SubagentResult>();
+      const resultMap = new Map<string, SubagentStreamResult>();
       results.forEach((result, i) => {
         const key = `${config.agents[i]!.agentName}-${i}`;
         resultMap.set(key, result);
       });
 
-      const stateUpdate = config.merge(resultMap, ctx.state);
+      const stateUpdate = resolvedOutputMapper(resultMap, ctx.state);
       return { stateUpdate };
     },
   };
diff --git a/src/graph/nodes/ralph.test.ts b/src/workflows/graph/nodes/ralph.test.ts
similarity index 86%
rename from src/graph/nodes/ralph.test.ts
rename to src/workflows/graph/nodes/ralph.test.ts
index b75836832b..4151aae2e9 100644
--- a/src/graph/nodes/ralph.test.ts
+++ b/src/workflows/graph/nodes/ralph.test.ts
@@ -1,15 +1,13 @@
 import { describe, expect, test } from "bun:test";
 import {
   buildSpecToTasksPrompt,
-  buildTaskListPreamble,
   buildWorkerAssignment,
-  buildBootstrappedTaskContext,
   buildReviewPrompt,
-  parseReviewResult,
   buildFixSpecFromReview,
+  parseReviewResult,
   type TaskItem,
   type ReviewResult,
-} from "./ralph.ts";
+} from "../../ralph/prompts.ts";
 
 describe("buildSpecToTasksPrompt", () => {
   test("includes spec content in the prompt", () => {
@@ -38,36 +36,6 @@ describe("buildSpecToTasksPrompt", () => {
   });
 });
 
-describe("buildTaskListPreamble", () => {
-  test("includes task list as JSON", () => {
-    const tasks = [
-      { id: "#1", content: "Task 1", status: "pending", activeForm: "Doing task 1", blockedBy: [] },
-      { id: "#2", content: "Task 2", status: "completed", activeForm: "Doing task 2" },
-    ];
-    
-    const preamble = buildTaskListPreamble(tasks);
-    
-    expect(preamble).toContain('"id": "#1"');
-    expect(preamble).toContain('"content": "Task 1"');
-    expect(preamble).toContain('"status": "pending"');
-  });
-
-  test("instructs to call TodoWrite first", () => {
-    const tasks = [{ id: "#1", content: "Test", status: "pending", activeForm: "Testing" }];
-    const preamble = buildTaskListPreamble(tasks);
-    
-    expect(preamble).toContain("TodoWrite");
-    expect(preamble).toContain("FIRST action MUST be");
-  });
-
-  test("handles empty task list", () => {
-    const preamble = buildTaskListPreamble([]);
-    
-    expect(preamble).toContain("[]");
-    expect(preamble).toContain("TodoWrite");
-  });
-});
-
 describe("buildWorkerAssignment", () => {
   test("includes task ID and content", () => {
     const task: TaskItem = {
@@ -423,66 +391,13 @@ describe("buildWorkerAssignment", () => {
   });
 });
 
-describe("buildBootstrappedTaskContext", () => {
-  test("includes session ID", () => {
-    const tasks: TaskItem[] = [
-      { id: "#1", content: "Task 1", status: "pending", activeForm: "Doing task 1" },
-    ];
-    const result = buildBootstrappedTaskContext(tasks, "abc-123");
-
-    expect(result).toContain("abc-123");
-  });
-
-  test("includes task list as JSON", () => {
-    const tasks: TaskItem[] = [
-      { id: "#1", content: "Setup project", status: "pending", activeForm: "Setting up", blockedBy: [] },
-      { id: "#2", content: "Add feature", status: "pending", activeForm: "Adding feature", blockedBy: ["#1"] },
-    ];
-    const result = buildBootstrappedTaskContext(tasks, "session-1");
-
-    expect(result).toContain('"id": "#1"');
-    expect(result).toContain('"content": "Setup project"');
-    expect(result).toContain('"id": "#2"');
-    expect(result).toContain('"blockedBy"');
-  });
-
-  test("includes implementation instructions", () => {
-    const tasks: TaskItem[] = [
-      { id: "#1", content: "Task", status: "pending", activeForm: "Doing" },
-    ];
-    const result = buildBootstrappedTaskContext(tasks, "session-1");
-
-    expect(result).toContain("Instructions");
-    expect(result).toContain("dependency order");
-    expect(result).toContain("blockedBy");
-  });
-
-  test("handles empty task list", () => {
-    const result = buildBootstrappedTaskContext([], "session-1");
-
-    expect(result).toContain("[]");
-    expect(result).toContain("session-1");
-  });
-
-  test("produces deterministic output", () => {
-    const tasks: TaskItem[] = [
-      { id: "#1", content: "Task 1", status: "pending", activeForm: "Doing 1" },
-      { id: "#2", content: "Task 2", status: "pending", activeForm: "Doing 2", blockedBy: ["#1"] },
-    ];
-    const result1 = buildBootstrappedTaskContext(tasks, "session-x");
-    const result2 = buildBootstrappedTaskContext(tasks, "session-x");
-
-    expect(result1).toBe(result2);
-  });
-});
-
 describe("buildReviewPrompt", () => {
   test("includes user prompt in review request", () => {
     const tasks: TaskItem[] = [
       { id: "#1", content: "Add login", status: "completed", activeForm: "Adding login" },
     ];
     const userPrompt = "Implement user authentication";
-    const prompt = buildReviewPrompt(tasks, userPrompt);
+    const prompt = buildReviewPrompt(tasks, userPrompt, "/tmp/progress.txt");
 
     expect(prompt).toContain("Implement user authentication");
     expect(prompt).toContain("<user_request>");
@@ -495,7 +410,7 @@ describe("buildReviewPrompt", () => {
       { id: "#2", content: "Add API", status: "completed", activeForm: "Adding API" },
       { id: "#3", content: "Not done yet", status: "pending", activeForm: "Working" },
     ];
-    const prompt = buildReviewPrompt(tasks, "Build backend");
+    const prompt = buildReviewPrompt(tasks, "Build backend", "/tmp/progress.txt");
 
     expect(prompt).toContain("#1");
     expect(prompt).toContain("Setup DB");
@@ -504,11 +419,20 @@ describe("buildReviewPrompt", () => {
     expect(prompt).not.toContain("Not done yet");
   });
 
+  test("includes progress file path", () => {
+    const tasks: TaskItem[] = [
+      { id: "#1", content: "Task", status: "completed", activeForm: "Working" },
+    ];
+    const prompt = buildReviewPrompt(tasks, "Test", "/session/progress.txt");
+
+    expect(prompt).toContain("/session/progress.txt");
+  });
+
   test("includes review focus areas", () => {
     const tasks: TaskItem[] = [
       { id: "#1", content: "Task", status: "completed", activeForm: "Working" },
     ];
-    const prompt = buildReviewPrompt(tasks, "Test");
+    const prompt = buildReviewPrompt(tasks, "Test", "/tmp/progress.txt");
 
     expect(prompt).toContain("Correctness of Logic");
     expect(prompt).toContain("Error Handling");
@@ -522,7 +446,7 @@ describe("buildReviewPrompt", () => {
     const tasks: TaskItem[] = [
       { id: "#1", content: "Task", status: "completed", activeForm: "Working" },
     ];
-    const prompt = buildReviewPrompt(tasks, "Test");
+    const prompt = buildReviewPrompt(tasks, "Test", "/tmp/progress.txt");
 
     expect(prompt).toContain("findings");
     expect(prompt).toContain("overall_correctness");
@@ -534,7 +458,7 @@ describe("buildReviewPrompt", () => {
     const tasks: TaskItem[] = [
       { id: "#1", content: "Task", status: "completed", activeForm: "Working" },
     ];
-    const prompt = buildReviewPrompt(tasks, "Test");
+    const prompt = buildReviewPrompt(tasks, "Test", "/tmp/progress.txt");
 
     expect(prompt).toContain("P0");
     expect(prompt).toContain("P1");
@@ -548,7 +472,7 @@ describe("buildReviewPrompt", () => {
     const tasks: TaskItem[] = [
       { content: "Unnamed task", status: "completed", activeForm: "Working" },
     ];
-    const prompt = buildReviewPrompt(tasks, "Test");
+    const prompt = buildReviewPrompt(tasks, "Test", "/tmp/progress.txt");
 
     expect(prompt).toContain("?");
     expect(prompt).toContain("Unnamed task");
@@ -788,7 +712,7 @@ describe("buildFixSpecFromReview", () => {
     expect(spec).toContain("minimal changes");
   });
 
-  test("includes rubric for each finding", () => {
+    test("includes rubric for each finding", () => {
     const review: ReviewResult = {
       findings: [
         {
diff --git a/src/workflows/graph/provider-registry.test.ts b/src/workflows/graph/provider-registry.test.ts
new file mode 100644
index 0000000000..622758dd9d
--- /dev/null
+++ b/src/workflows/graph/provider-registry.test.ts
@@ -0,0 +1,99 @@
+import { describe, expect, test } from "bun:test";
+import type { AgentMessage, Session, SessionConfig } from "../../sdk/types.ts";
+import { ProviderRegistry, type AgentProvider } from "./provider-registry.ts";
+
+function createMockSession(id: string): Session {
+  return {
+    id,
+    async send(message: string): Promise<AgentMessage> {
+      return { type: "text", content: message, role: "assistant" };
+    },
+    async *stream(message: string): AsyncIterable<AgentMessage> {
+      yield { type: "text", content: message, role: "assistant" };
+    },
+    async summarize(): Promise<void> {},
+    async getContextUsage() {
+      return {
+        inputTokens: 1,
+        outputTokens: 1,
+        maxTokens: 1000,
+        usagePercentage: 0.2,
+      };
+    },
+    getSystemToolsTokens(): number {
+      return 0;
+    },
+    async destroy(): Promise<void> {},
+  };
+}
+
+function createProvider(name: string): AgentProvider {
+  return {
+    name,
+    async createSession(_config: SessionConfig): Promise<Session> {
+      return createMockSession(`${name}-session`);
+    },
+    supportedModels(): string[] {
+      return [`${name}-model`];
+    },
+  };
+}
+
+describe("ProviderRegistry", () => {
+  test("returns undefined from get() for unknown providers", () => {
+    const registry = new ProviderRegistry({
+      claude: createProvider("claude"),
+    });
+
+    expect(registry.get("missing")).toBeUndefined();
+  });
+
+  test("stores and resolves providers by name", async () => {
+    const registry = new ProviderRegistry({
+      claude: createProvider("claude"),
+      copilot: createProvider("copilot"),
+    });
+
+    expect(registry.has("claude")).toBe(true);
+    expect(registry.has("copilot")).toBe(true);
+    expect(registry.has("opencode")).toBe(false);
+
+    const provider = registry.get("claude");
+    expect(provider?.name).toBe("claude");
+
+    const session = await provider?.createSession({ model: "claude-sonnet" });
+    expect(session?.id).toBe("claude-session");
+  });
+
+  test("returns provider names from list()", () => {
+    const registry = new ProviderRegistry({
+      claude: createProvider("claude"),
+      opencode: createProvider("opencode"),
+    });
+
+    expect(registry.list()).toEqual(["claude", "opencode"]);
+  });
+
+  test("does not change when source record mutates after construction", () => {
+    const providers: Record<string, AgentProvider> = {
+      claude: createProvider("claude"),
+    };
+    const registry = new ProviderRegistry(providers);
+
+    providers.opencode = createProvider("opencode");
+
+    expect(registry.has("opencode")).toBe(false);
+    expect(registry.list()).toEqual(["claude"]);
+  });
+
+  test("list() returns a copy, not internal mutable state", () => {
+    const registry = new ProviderRegistry({
+      claude: createProvider("claude"),
+    });
+
+    const providers = registry.list();
+    providers.push("opencode");
+
+    expect(registry.list()).toEqual(["claude"]);
+  });
+});
diff --git a/src/workflows/graph/provider-registry.ts b/src/workflows/graph/provider-registry.ts
new file mode 100644
index 0000000000..e61aea23d8
--- /dev/null
+++ b/src/workflows/graph/provider-registry.ts
@@ -0,0 +1,33 @@
+import type { Session, SessionConfig } from "../../sdk/types.ts";
+
+/**
+ * Provider abstraction for creating agent sessions from workflow graph nodes.
+ */
+export interface AgentProvider {
+  name: string;
+  createSession(config: SessionConfig): Promise<Session>;
+  supportedModels(): string[];
+}
+
+/**
+ * Immutable registry of available agent providers.
+ */
+export class ProviderRegistry {
+  private readonly providers: ReadonlyMap<string, AgentProvider>;
+
+  constructor(providers: Record<string, AgentProvider>) {
+    this.providers = new Map(Object.entries(providers));
+  }
+
+  get(name: string): AgentProvider | undefined {
+    return this.providers.get(name);
+  }
+
+  list(): string[] {
+    return Array.from(this.providers.keys());
+  }
+
+  has(name: string): boolean {
+    return this.providers.has(name);
+  }
+}
diff --git a/src/workflows/graph/removed-apis-compile-errors.test.ts b/src/workflows/graph/removed-apis-compile-errors.test.ts
new file mode 100644
index 0000000000..482f2b0244
--- /dev/null
+++ b/src/workflows/graph/removed-apis-compile-errors.test.ts
@@ -0,0 +1,49 @@
+import { expect, test } from "bun:test";
+import type { AgentNodeAgentType } from "./nodes.ts";
+
+type IsExactlyString<T> = [T] extends [string] ? ([string] extends [T] ? true : false) : false;
+
+const supportsCustomProvider: AgentNodeAgentType = "my-custom-provider";
+const assertAgentNodeAgentTypeIsString: IsExactlyString<AgentNodeAgentType> = true;
+void supportsCustomProvider;
+void assertAgentNodeAgentTypeIsString;
+
+// @ts-expect-error AgentNodeAgentType was removed from graph public API
+type RemovedAgentNodeAgentType = (typeof import("./index.ts"))["AgentNodeAgentType"];
+// @ts-expect-error setClientProvider was removed from graph public API
+type RemovedSetClientProvider = (typeof import("./index.ts"))["setClientProvider"];
+// @ts-expect-error getClientProvider was removed from graph public API
+type RemovedGetClientProvider = (typeof import("./index.ts"))["getClientProvider"];
+// @ts-expect-error setSubagentBridge was removed from graph public API
+type RemovedSetSubagentBridge = (typeof import("./index.ts"))["setSubagentBridge"];
+// @ts-expect-error getSubagentBridge was removed from graph public API
+type RemovedGetSubagentBridge = (typeof import("./index.ts"))["getSubagentBridge"];
+// @ts-expect-error setSubagentRegistry was removed from graph public API
+type RemovedSetSubagentRegistry = (typeof import("./index.ts"))["setSubagentRegistry"];
+// @ts-expect-error setWorkflowResolver was removed from graph public API
+type RemovedSetWorkflowResolver = (typeof import("./index.ts"))["setWorkflowResolver"];
+// @ts-expect-error getWorkflowResolver was removed from graph public API
+type RemovedGetWorkflowResolver = (typeof import("./index.ts"))["getWorkflowResolver"];
+
+// @ts-expect-error RalphWorkflowState was removed from graph public API
+type RemovedRalphWorkflowStateFromGraph = (typeof import("./index.ts"))["RalphWorkflowState"];
+// @ts-expect-error RalphStateAnnotation was removed from graph public API
+type RemovedRalphStateAnnotationFromGraph = (typeof import("./index.ts"))["RalphStateAnnotation"];
+// @ts-expect-error RalphWorkflowState was removed from graph/annotation.ts
+type RemovedRalphWorkflowState = (typeof import("./annotation.ts"))["RalphWorkflowState"];
+// @ts-expect-error RalphStateAnnotation was removed from graph/annotation.ts
+type RemovedRalphStateAnnotation = (typeof import("./annotation.ts"))["RalphStateAnnotation"];
+// @ts-expect-error createRalphState was removed from graph/annotation.ts
+type RemovedCreateRalphState = (typeof import("./annotation.ts"))["createRalphState"];
+// @ts-expect-error updateRalphState was removed from graph/annotation.ts
+type RemovedUpdateRalphState = (typeof import("./annotation.ts"))["updateRalphState"];
+// @ts-expect-error isRalphWorkflowState was removed from graph/annotation.ts
+type RemovedIsRalphWorkflowState = (typeof import("./annotation.ts"))["isRalphWorkflowState"];
+
+// @ts-expect-error AgentNodeAgentType must remain a string
+const invalidAgentType: AgentNodeAgentType = 123;
+void invalidAgentType;
+
+test("compile-time API removal contracts are enforced by typecheck", () => {
+  expect(supportsCustomProvider).toBe("my-custom-provider");
+});
diff --git a/src/workflows/graph/state-validator.test.ts b/src/workflows/graph/state-validator.test.ts
new file mode 100644
index 0000000000..041ffb71e8
--- /dev/null
+++ b/src/workflows/graph/state-validator.test.ts
@@ -0,0 +1,154 @@
+import { describe, expect, test } from "bun:test";
+import { z } from "zod";
+
+import { SchemaValidationError } from "./errors.ts";
+import { StateValidator } from "./state-validator.ts";
+import type { BaseState, GraphConfig } from "./types.ts";
+
+interface TestState extends BaseState {
+  counter?: number;
+  messages?: string[];
+}
+
+const testStateSchema: z.ZodType<TestState> = z.object({
+  executionId: z.string(),
+  lastUpdated: z.string(),
+  outputs: z.record(z.string(), z.unknown()),
+  counter: z.number().optional(),
+  messages: z.array(z.string()).optional(),
+});
+
+describe("StateValidator", () => {
+  test("returns state unchanged when no schema is configured", () => {
+    const validator = new StateValidator<TestState>();
+    const state: TestState = {
+      executionId: "exec-1",
+      lastUpdated: "2026-01-01T00:00:00.000Z",
+      outputs: {},
+      counter: 1,
+    };
+
+    expect(validator.validate(state)).toBe(state);
+  });
+
+  test("accepts valid state when schema is configured", () => {
+    const validator = new StateValidator<TestState>({ outputSchema: testStateSchema });
+    const state: TestState = {
+      executionId: "exec-1",
+      lastUpdated: "2026-01-01T00:00:00.000Z",
+      outputs: {},
+      counter: 1,
+    };
+
+    const result = validator.validate(state);
+    expect(result).toEqual(state);
+  });
+
+  test("throws SchemaValidationError for invalid state", () => {
+    const validator = new StateValidator<TestState>({
+      outputSchema: testStateSchema.refine(
+        (state) => state.counter === undefined || state.counter >= 2,
+        { message: "counter must be >= 2", path: ["counter"] }
+      ),
+    });
+    const invalidState: TestState = {
+      executionId: "exec-1",
+      lastUpdated: "2026-01-01T00:00:00.000Z",
+      outputs: {},
+      counter: 1,
+    };
+
+    expect(() => validator.validate(invalidState)).toThrow(SchemaValidationError);
+    expect(() => validator.validate(invalidState)).toThrow(
+      "State validation failed: counter: counter must be >= 2"
+    );
+  });
+
+  test("validates node input schemas", () => {
+    const validator = new StateValidator<TestState>();
+    const inputSchema = testStateSchema.refine(
+      (state) => state.counter === undefined || state.counter >= 2,
+      { message: "counter must be >= 2", path: ["counter"] }
+    );
+    const invalidState: TestState = {
+      executionId: "exec-1",
+      lastUpdated: "2026-01-01T00:00:00.000Z",
+      outputs: {},
+      counter: 1,
+    };
+
+    expect(() => validator.validateNodeInput("node-a", invalidState, inputSchema)).toThrow(
+      SchemaValidationError
+    );
+    expect(() => validator.validateNodeInput("node-a", invalidState, inputSchema)).toThrow(
+      'Node "node-a" input validation failed: counter: counter must be >= 2'
+    );
+  });
+
+  test("returns validated state for valid node input", () => {
+    const validator = new StateValidator<TestState>();
+    const inputSchema = testStateSchema.refine(
+      (state) => state.counter === undefined || state.counter >= 2,
+      { message: "counter must be >= 2", path: ["counter"] }
+    );
+    const validState: TestState = {
+      executionId: "exec-1",
+      lastUpdated: "2026-01-01T00:00:00.000Z",
+      outputs: {},
+      counter: 2,
+    };
+
+    expect(validator.validateNodeInput("node-a", validState, inputSchema)).toEqual(validState);
+  });
+
+  test("validates node output schemas", () => {
+    const validator = new StateValidator<TestState>();
+    const outputSchema = testStateSchema.refine(
+      (state) => state.counter === undefined || state.counter >= 2,
+      { message: "counter must be >= 2", path: ["counter"] }
+    );
+    const invalidState: TestState = {
+      executionId: "exec-1",
+      lastUpdated: "2026-01-01T00:00:00.000Z",
+      outputs: {},
+      counter: 1,
+    };
+
+    expect(() => validator.validateNodeOutput("node-b", invalidState, outputSchema)).toThrow(
+      SchemaValidationError
+    );
+    expect(() => validator.validateNodeOutput("node-b", invalidState, outputSchema)).toThrow(
+      'Node "node-b" output validation failed: counter: counter must be >= 2'
+    );
+  });
+
+  test("returns validated state for valid node output", () => {
+    const validator = new StateValidator<TestState>();
+    const outputSchema = testStateSchema.refine(
+      (state) => state.counter === undefined || state.counter >= 2,
+      { message: "counter must be >= 2", path: ["counter"] }
+    );
+    const validState: TestState = {
+      executionId: "exec-1",
+      lastUpdated: "2026-01-01T00:00:00.000Z",
+      outputs: {},
+      counter: 3,
+    };
+
+    expect(validator.validateNodeOutput("node-b", validState, outputSchema)).toEqual(validState);
+  });
+
+  test("creates a validator from GraphConfig", () => {
+    const config: GraphConfig<TestState> = {
+      outputSchema: testStateSchema,
+    };
+    const validator = StateValidator.fromGraphConfig(config);
+    const state: TestState = {
+      executionId: "exec-1",
+      lastUpdated: "2026-01-01T00:00:00.000Z",
+      outputs: {},
+    };
+
+    expect(validator.validate(state)).toEqual(state);
+  });
+});
diff --git a/src/workflows/graph/state-validator.ts b/src/workflows/graph/state-validator.ts
new file mode 100644
index 0000000000..eeddacaa15
--- /dev/null
+++ b/src/workflows/graph/state-validator.ts
@@ -0,0 +1,84 @@
+import type { z } from "zod";
+
+import { SchemaValidationError } from "./errors.ts";
+import type { BaseState, GraphConfig, NodeId } from "./types.ts";
+
+/**
+ * Runtime validation options used by {@link StateValidator}.
+ */
+export interface StateValidatorConfig<TState extends BaseState = BaseState> {
+  outputSchema?: z.ZodType<TState>;
+}
+
+function formatValidationIssues(
+  issues: Array<{ path: PropertyKey[]; message: string }>
+): string {
+  return issues
+    .map((issue) => {
+      const path =
+        issue.path.length > 0 ? issue.path.map((segment) => String(segment)).join(".") : "(root)";
+      return `${path}: ${issue.message}`;
+    })
+    .join("; ");
+}
+
+/**
+ * Validates graph state against node and graph output schemas.
+ */
+export class StateValidator<TState extends BaseState = BaseState> {
+  constructor(private readonly config: StateValidatorConfig<TState> = {}) {}
+
+  validateNodeInput(nodeId: NodeId, state: TState, inputSchema?: z.ZodType<TState>): TState {
+    if (!inputSchema) {
+      return state;
+    }
+
+    const parsed = inputSchema.safeParse(state);
+    if (!parsed.success) {
+      throw new SchemaValidationError(
+        `Node "${nodeId}" input validation failed: ${formatValidationIssues(parsed.error.issues)}`,
+        parsed.error
+      );
+    }
+
+    return parsed.data;
+  }
+
+  validateNodeOutput(nodeId: NodeId, state: TState, outputSchema?: z.ZodType<TState>): TState {
+    if (!outputSchema) {
+      return state;
+    }
+
+    const parsed = outputSchema.safeParse(state);
+    if (!parsed.success) {
+      throw new SchemaValidationError(
+        `Node "${nodeId}" output validation failed: ${formatValidationIssues(parsed.error.issues)}`,
+        parsed.error
+      );
+    }
+
+    return parsed.data;
+  }
+
+  validate(state: TState): TState {
+    if (!this.config.outputSchema) {
+      return state;
+    }
+
+    const parsed = this.config.outputSchema.safeParse(state);
+    if (!parsed.success) {
+      throw new SchemaValidationError(
+        `State validation failed: ${formatValidationIssues(parsed.error.issues)}`,
+        parsed.error
+      );
+    }
+
+    return parsed.data;
+  }
+
+  static fromGraphConfig<TState extends BaseState>(
+    config: GraphConfig<TState>
+  ): StateValidator<TState> {
+    return new StateValidator<TState>({ outputSchema: config.outputSchema });
+  }
+}
diff --git a/src/workflows/graph/stream.test.ts b/src/workflows/graph/stream.test.ts
new file mode 100644
index 0000000000..3c7d84c13e
--- /dev/null
+++ b/src/workflows/graph/stream.test.ts
@@ -0,0 +1,230 @@
+import { describe, expect, test } from "bun:test";
+import { graph, createNode } from "./builder.ts";
+import { streamGraph } from "./compiled.ts";
+import { askUserNode, type AskUserWaitState } from "./nodes.ts";
+import { routeStream } from "./stream.ts";
+import type { BaseState, ExecutionContext } from "./types.ts";
+
+interface StreamTestState extends BaseState {
+  counter?: number;
+}
+
+interface AskUserStreamState extends BaseState, AskUserWaitState {}
+
+describe("StreamRouter", () => {
+  test("defaults to values mode", async () => {
+    const node = createNode<StreamTestState>("node1", "tool", async () => {
+      return { stateUpdate: { counter: 1 } };
+    });
+
+    const workflow = graph<StreamTestState>().start(node).end().compile();
+    const events = [];
+
+    for await (const event of routeStream(streamGraph(workflow))) {
+      events.push(event);
+    }
+
+    expect(events).toHaveLength(1);
+    expect(events[0]?.mode).toBe("values");
+    if (events[0]?.mode === "values") {
+      expect(events[0].state.counter).toBe(1);
+    }
+  });
+
+  test("emits updates mode from state deltas", async () => {
+    const node1 = createNode<StreamTestState>("node1", "tool", async () => {
+      return { stateUpdate: { counter: 1 } };
+    });
+    const node2 = createNode<StreamTestState>("node2", "tool", async () => {
+      return {};
+    });
+
+    const workflow = graph<StreamTestState>()
+      .start(node1)
+      .then(node2)
+      .end()
+      .compile();
+
+    const events = [];
+    for await (const event of routeStream(streamGraph(workflow), ["updates"])) {
+      events.push(event);
+    }
+
+    expect(events).toHaveLength(1);
+    expect(events[0]?.mode).toBe("updates");
+    if (events[0]?.mode === "updates") {
+      expect(events[0].update.counter).toBe(1);
+    }
+  });
+
+  test("emits custom events mode from context emit", async () => {
+    const node = createNode<StreamTestState>(
+      "node1",
+      "tool",
+      async (ctx: ExecutionContext<StreamTestState>) => {
+        ctx.emit?.("progress", { step: 1, total: 1 });
+        return { stateUpdate: { counter: 1 } };
+      }
+    );
+
+    const workflow = graph<StreamTestState>().start(node).end().compile();
+    const events = [];
+
+    for await (const event of routeStream(streamGraph(workflow), ["events"])) {
+      events.push(event);
+    }
+
+    expect(events).toHaveLength(1);
+    expect(events[0]?.mode).toBe("events");
+    if (events[0]?.mode === "events") {
+      expect(events[0].event.type).toBe("progress");
+      expect(events[0].event.data).toEqual({ step: 1, total: 1 });
+      expect(typeof events[0].event.timestamp).toBe("number");
+    }
+  });
+
+  test("emits ask_user node event via context emit contract", async () => {
+    const node = askUserNode<AskUserStreamState>({
+      id: "ask-user",
+      options: {
+        question: "Continue?",
+        header: "Confirm",
+      },
+    });
+
+    const workflow = graph<AskUserStreamState>().start(node).end().compile();
+    const events = [];
+
+    for await (const event of routeStream(streamGraph(workflow), ["events"])) {
+      events.push(event);
+    }
+
+    expect(events).toHaveLength(1);
+    expect(events[0]?.mode).toBe("events");
+    if (events[0]?.mode === "events") {
+      expect(events[0].event.type).toBe("human_input_required");
+      expect(events[0].event.data).toMatchObject({
+        question: "Continue?",
+        header: "Confirm",
+        nodeId: "ask-user",
+      });
+      expect(typeof events[0].event.timestamp).toBe("number");
+    }
+  });
+
+  test("emits debug mode with retry and model metadata", async () => {
+    let attempts = 0;
+    const node = createNode<StreamTestState>(
+      "node1",
+      "tool",
+      async () => {
+        attempts += 1;
+        if (attempts === 1) {
+          throw new Error("retry once");
+        }
+        return { stateUpdate: { counter: attempts } };
+      },
+      {
+        retry: {
+          maxAttempts: 2,
+          backoffMs: 1,
+          backoffMultiplier: 1,
+        },
+      }
+    );
+
+    const workflow = graph<StreamTestState>()
+      .start(node)
+      .end()
+      .compile({ defaultModel: "test-model" });
+
+    const events = [];
+    for await (const event of routeStream(streamGraph(workflow), ["debug"])) {
+      events.push(event);
+    }
+
+    expect(events).toHaveLength(1);
+    expect(events[0]?.mode).toBe("debug");
+    if (events[0]?.mode === "debug") {
+      expect(events[0].trace.retryCount).toBe(1);
+      expect(events[0].trace.modelUsed).toBe("test-model");
+      expect(events[0].trace.executionTime).toBeGreaterThanOrEqual(0);
+    }
+  });
+
+  test("projects one step into multiple requested modes in order", async () => {
+    const node = createNode<StreamTestState>(
+      "node1",
+      "tool",
+      async (ctx: ExecutionContext<StreamTestState>) => {
+        ctx.emit?.("progress", { step: 1, total: 1 });
+        return { stateUpdate: { counter: 1 } };
+      }
+    );
+
+    const workflow = graph<StreamTestState>()
+      .start(node)
+      .end()
+      .compile({ defaultModel: "projection-model" });
+
+    const events = [];
+    for await (const event of routeStream(streamGraph(workflow), [
+      "values",
+      "updates",
+      "events",
+      "debug",
+    ])) {
+      events.push(event);
+    }
+
+    expect(events).toHaveLength(4);
+    expect(events.map((event) => event.mode)).toEqual([
+      "values",
+      "updates",
+      "events",
+      "debug",
+    ]);
+
+    if (events[0]?.mode === "values") {
+      expect(events[0].state.counter).toBe(1);
+    }
+
+    if (events[1]?.mode === "updates") {
+      expect(events[1].update.counter).toBe(1);
+    }
+
+    if (events[2]?.mode === "events") {
+      expect(events[2].event.type).toBe("progress");
+      expect(events[2].event.data).toEqual({ step: 1, total: 1 });
+      expect(typeof events[2].event.timestamp).toBe("number");
+    }
+
+    if (events[3]?.mode === "debug") {
+      expect(events[3].trace.modelUsed).toBe("projection-model");
+      expect(events[3].trace.retryCount).toBe(0);
+    }
+  });
+
+  test("projects only available payloads per step in multi-mode streams", async () => {
+    const node1 = createNode<StreamTestState>("node1", "tool", async () => {
+      return { stateUpdate: { counter: 1 } };
+    });
+    const node2 = createNode<StreamTestState>("node2", "tool", async () => {
+      return {};
+    });
+
+    const workflow = graph<StreamTestState>()
+      .start(node1)
+      .then(node2)
+      .end()
+      .compile();
+
+    const events = [];
+    for await (const event of routeStream(streamGraph(workflow), ["values", "updates"])) {
+      events.push(event);
+    }
+
+    expect(events.map((event) => event.mode)).toEqual(["values", "updates", "values"]);
+    expect(events).toHaveLength(3);
+  });
+});
diff --git a/src/workflows/graph/stream.ts b/src/workflows/graph/stream.ts
new file mode 100644
index 0000000000..3cabac927a
--- /dev/null
+++ b/src/workflows/graph/stream.ts
@@ -0,0 +1,128 @@
+import type { BaseState, NodeId } from "./types.ts";
+import type { ExecutionOptions, StepResult } from "./compiled.ts";
+
+/**
+ * Available stream projection modes.
+ */
+export type StreamMode = "values" | "updates" | "events" | "debug";
+
+/**
+ * Stream routing options layered on top of execution options.
+ */
+export interface StreamOptions<TState extends BaseState = BaseState>
+  extends ExecutionOptions<TState> {
+  modes?: StreamMode[];
+}
+
+/**
+ * Event emitted from a node via `ctx.emit()`.
+ */
+export interface CustomEvent {
+  type: string;
+  data: Record<string, unknown>;
+  timestamp: number;
+}
+
+/**
+ * Debug metadata for a streamed node execution step.
+ */
+export interface DebugTrace {
+  nodeId: NodeId;
+  executionTime: number;
+  retryCount: number;
+  modelUsed: string;
+  stateSnapshot: unknown;
+}
+
+/**
+ * Union of projected stream events returned by {@link StreamRouter}.
+ */
+export type StreamEvent<TState extends BaseState = BaseState> =
+  | { mode: "values"; nodeId: NodeId; state: TState }
+  | { mode: "updates"; nodeId: NodeId; update: Partial<TState> }
+  | { mode: "events"; nodeId: NodeId; event: CustomEvent }
+  | { mode: "debug"; nodeId: NodeId; trace: DebugTrace };
+
+function normalizeModes(modes?: StreamMode[]): StreamMode[] {
+  if (!modes || modes.length === 0) {
+    return ["values"];
+  }
+  return Array.from(new Set(modes));
+}
+
+/**
+ * Projects raw execution step output into typed stream modes.
+ */
+export class StreamRouter<TState extends BaseState = BaseState> {
+  private readonly modes: StreamMode[];
+
+  constructor(
+    private readonly source: AsyncIterable<StepResult<TState>>,
+    modes?: StreamMode[]
+  ) {
+    this.modes = normalizeModes(modes);
+  }
+
+  async *stream(): AsyncGenerator<StreamEvent<TState>> {
+    for await (const step of this.source) {
+      for (const mode of this.modes) {
+        if (mode === "values") {
+          yield {
+            mode: "values",
+            nodeId: step.nodeId,
+            state: step.state,
+          };
+          continue;
+        }
+
+        if (mode === "updates") {
+          if (step.result.stateUpdate) {
+            yield {
+              mode: "updates",
+              nodeId: step.nodeId,
+              update: step.result.stateUpdate,
+            };
+          }
+          continue;
+        }
+
+        if (mode === "events") {
+          for (const event of step.emittedEvents ?? []) {
+            yield {
+              mode: "events",
+              nodeId: step.nodeId,
+              event: {
+                type: event.type,
+                data: event.data,
+                timestamp: event.timestamp,
+              },
+            };
+          }
+          continue;
+        }
+
+        yield {
+          mode: "debug",
+          nodeId: step.nodeId,
+          trace: {
+            nodeId: step.nodeId,
+            executionTime: step.executionTime ?? 0,
+            retryCount: step.retryCount ?? 0,
+            modelUsed: step.modelUsed ?? "unknown",
+            stateSnapshot: step.state,
+          },
+        };
+      }
+    }
+  }
+}
+
+/**
+ * Create a routed stream from step results with selected modes.
+ */
+export function routeStream<TState extends BaseState = BaseState>(
+  source: AsyncIterable<StepResult<TState>>,
+  modes?: StreamMode[]
+): AsyncGenerator<StreamEvent<TState>> {
+  return new StreamRouter(source, modes).stream();
+}
diff --git a/src/graph/subagent-registry.ts b/src/workflows/graph/subagent-registry.ts
similarity index 59%
rename from src/graph/subagent-registry.ts
rename to src/workflows/graph/subagent-registry.ts
index 28edcba69f..60abf2cc1d 100644
--- a/src/graph/subagent-registry.ts
+++ b/src/workflows/graph/subagent-registry.ts
@@ -5,16 +5,18 @@
  * name-based lookup. Enables workflow authors to reference config-defined
  * agents by name within subagentNode() and parallelSubagentNode().
  *
- * Follows the existing setClientProvider() / setWorkflowResolver() global setter pattern.
  */
 
-import type { AgentInfo, AgentSource } from "../ui/commands/agent-commands.ts";
-import { discoverAgentInfos } from "../ui/commands/agent-commands.ts";
+import type { AgentInfo, AgentSource } from "../../ui/commands/agent-commands.ts";
+import { discoverAgentInfos } from "../../ui/commands/agent-commands.ts";
 
 // ============================================================================
 // Types
 // ============================================================================
 
+/**
+ * Registry entry for a discovered sub-agent.
+ */
 export interface SubagentEntry {
   name: string;
   info: AgentInfo;
@@ -25,6 +27,9 @@ export interface SubagentEntry {
 // Registry
 // ============================================================================
 
+/**
+ * In-memory registry for sub-agent definitions keyed by name.
+ */
 export class SubagentTypeRegistry {
   private agents = new Map<string, SubagentEntry>();
 
@@ -49,36 +54,14 @@ export class SubagentTypeRegistry {
   }
 }
 
-// ============================================================================
-// Singleton
-// ============================================================================
-
-let globalSubagentRegistry: SubagentTypeRegistry | null = null;
-
-export function getSubagentRegistry(): SubagentTypeRegistry {
-  if (!globalSubagentRegistry) {
-    globalSubagentRegistry = new SubagentTypeRegistry();
-  }
-  return globalSubagentRegistry;
-}
-
-export function setSubagentRegistry(registry: SubagentTypeRegistry): void {
-  globalSubagentRegistry = registry;
-}
-
-// ============================================================================
-// Population
-// ============================================================================
-
 /**
  * Populate the SubagentTypeRegistry with discovered agents from config directories.
  * Project-local agents overwrite user-global on name conflict.
  *
+ * @param registry - Registry instance to populate
  * @returns Number of agents in the registry after population
  */
-export async function populateSubagentRegistry(): Promise<number> {
-  const registry = getSubagentRegistry();
-
+export async function populateSubagentRegistry(registry: SubagentTypeRegistry): Promise<number> {
   const discovered = discoverAgentInfos();
   for (const agent of discovered) {
     registry.register({
diff --git a/src/workflows/graph/templates.test.ts b/src/workflows/graph/templates.test.ts
new file mode 100644
index 0000000000..e7732e7764
--- /dev/null
+++ b/src/workflows/graph/templates.test.ts
@@ -0,0 +1,394 @@
+import { describe, expect, test } from "bun:test";
+import { createNode } from "./builder.ts";
+import { executeGraph } from "./compiled.ts";
+import { mapReduce, reviewCycle, sequential, taskLoop } from "./templates.ts";
+import type { BaseState } from "./types.ts";
+
+interface ReviewState extends BaseState {
+  executed?: number;
+  reviewed?: number;
+  fixed?: number;
+  approved?: boolean;
+}
+
+interface SequentialState extends BaseState {
+  steps?: string[];
+}
+
+interface MapReduceState extends BaseState {
+  total?: number;
+}
+
+interface TaskLoopState extends BaseState {
+  planned?: number;
+  worked?: number;
+  reviewed?: number;
+  allTasksComplete?: boolean;
+}
+
+describe("mapReduce template", () => {
+  test("creates splitter-worker-reducer topology", () => {
+    const splitter = createNode<MapReduceState>("splitter", "tool", async () => ({}));
+    const worker = createNode<MapReduceState>("worker", "tool", async () => ({}));
+
+    const compiled = mapReduce<MapReduceState>({
+      splitter,
+      worker,
+      merger: () => ({ total: 0 }),
+    }).compile();
+
+    expect(compiled.startNode).toBe("splitter");
+    expect(compiled.nodes.has("splitter")).toBe(true);
+    expect(compiled.nodes.has("worker")).toBe(true);
+    expect(compiled.nodes.has("worker_reduce")).toBe(true);
+    expect(compiled.edges.some((edge) => edge.from === "splitter" && edge.to === "worker")).toBe(
+      true,
+    );
+    expect(
+      compiled.edges.some((edge) => edge.from === "worker" && edge.to === "worker_reduce"),
+    ).toBe(true);
+    expect(compiled.endNodes.has("worker_reduce")).toBe(true);
+  });
+
+  test("runs merger with worker output normalized to array", async () => {
+    const splitter = createNode<MapReduceState>("splitter", "tool", async (ctx) => ({
+      stateUpdate: {
+        outputs: { ...ctx.state.outputs, splitter: [1, 2, 3] },
+      },
+    }));
+
+    const worker = createNode<MapReduceState>("worker", "tool", async (ctx) => {
+      const items = (ctx.state.outputs.splitter as number[]) ?? [];
+      return {
+        stateUpdate: {
+          outputs: {
+            ...ctx.state.outputs,
+            worker: items.map((value) => ({ total: value })),
+          },
+        },
+      };
+    });
+
+    const compiled = mapReduce<MapReduceState>({
+      splitter,
+      worker,
+      merger: (results) => ({
+        total: results.reduce((sum, result) => sum + (result.total ?? 0), 0),
+      }),
+    }).compile();
+
+    const result = await executeGraph(compiled);
+    expect(result.status).toBe("completed");
+    expect(result.state.total).toBe(6);
+  });
+
+  test("applies default config and allows compile overrides", () => {
+    const splitter = createNode<MapReduceState>("splitter", "tool", async () => ({}));
+    const worker = createNode<MapReduceState>("worker", "tool", async () => ({}));
+
+    const compiled = mapReduce<MapReduceState>({
+      splitter,
+      worker,
+      merger: () => ({ total: 0 }),
+      config: { maxConcurrency: 2, timeout: 5_000 },
+    }).compile({ timeout: 10_000 });
+
+    expect(compiled.config.maxConcurrency).toBe(2);
+    expect(compiled.config.timeout).toBe(10_000);
+  });
+});
+
+describe("reviewCycle template", () => {
+  test("creates execute-review-fix loop topology", () => {
+    const executor = createNode<ReviewState>("executor", "tool", async () => ({}));
+    const reviewer = createNode<ReviewState>("reviewer", "tool", async () => ({}));
+    const fixer = createNode<ReviewState>("fixer", "tool", async () => ({}));
+
+    const compiled = reviewCycle<ReviewState>({
+      executor,
+      reviewer,
+      fixer,
+      until: (state) => state.approved === true,
+      maxIterations: 3,
+    }).compile();
+
+    expect(compiled.startNode.startsWith("loop_start_")).toBe(true);
+    expect(compiled.nodes.has("executor")).toBe(true);
+    expect(compiled.nodes.has("reviewer")).toBe(true);
+    expect(compiled.nodes.has("fixer")).toBe(true);
+    expect(compiled.edges.some((edge) => edge.from === "executor" && edge.to === "reviewer")).toBe(
+      true,
+    );
+    expect(compiled.edges.some((edge) => edge.from === "reviewer" && edge.to === "fixer")).toBe(
+      true,
+    );
+
+    const continueEdge = compiled.edges.find(
+      (edge) => edge.to === "executor" && edge.label === "loop-continue",
+    );
+    expect(continueEdge?.from.startsWith("loop_check_")).toBe(true);
+    expect(Array.from(compiled.endNodes).some((nodeId) => nodeId.startsWith("loop_check_"))).toBe(
+      true,
+    );
+  });
+
+  test("loops until the review condition is satisfied", async () => {
+    const executor = createNode<ReviewState>("executor", "tool", async (ctx) => ({
+      stateUpdate: { executed: (ctx.state.executed ?? 0) + 1 },
+    }));
+
+    const reviewer = createNode<ReviewState>("reviewer", "tool", async (ctx) => ({
+      stateUpdate: {
+        reviewed: (ctx.state.reviewed ?? 0) + 1,
+        approved: (ctx.state.executed ?? 0) >= 2,
+      },
+    }));
+
+    const fixer = createNode<ReviewState>("fixer", "tool", async (ctx) => ({
+      stateUpdate: { fixed: (ctx.state.fixed ?? 0) + 1 },
+    }));
+
+    const graph = reviewCycle<ReviewState>({
+      executor,
+      reviewer,
+      fixer,
+      until: (state) => state.approved === true,
+      maxIterations: 5,
+    }).compile();
+
+    const result = await executeGraph(graph);
+
+    expect(result.status).toBe("completed");
+    expect(result.state.executed).toBe(2);
+    expect(result.state.reviewed).toBe(2);
+    expect(result.state.fixed).toBe(2);
+    expect(result.state.approved).toBe(true);
+  });
+
+  test("stops at maxIterations when condition never passes", async () => {
+    const executor = createNode<ReviewState>("executor", "tool", async (ctx) => ({
+      stateUpdate: { executed: (ctx.state.executed ?? 0) + 1 },
+    }));
+
+    const reviewer = createNode<ReviewState>("reviewer", "tool", async (ctx) => ({
+      stateUpdate: {
+        reviewed: (ctx.state.reviewed ?? 0) + 1,
+        approved: false,
+      },
+    }));
+
+    const fixer = createNode<ReviewState>("fixer", "tool", async (ctx) => ({
+      stateUpdate: { fixed: (ctx.state.fixed ?? 0) + 1 },
+    }));
+
+    const graph = reviewCycle<ReviewState>({
+      executor,
+      reviewer,
+      fixer,
+      until: (state) => state.approved === true,
+      maxIterations: 2,
+    }).compile();
+
+    const result = await executeGraph(graph);
+
+    expect(result.status).toBe("completed");
+    expect(result.state.executed).toBe(2);
+    expect(result.state.reviewed).toBe(2);
+    expect(result.state.fixed).toBe(2);
+    expect(result.state.approved).toBe(false);
+  });
+
+  test("applies default graph config from options", () => {
+    const executor = createNode<ReviewState>("executor", "tool", async () => ({}));
+    const reviewer = createNode<ReviewState>("reviewer", "tool", async () => ({}));
+    const fixer = createNode<ReviewState>("fixer", "tool", async () => ({}));
+
+    const compiled = reviewCycle<ReviewState>({
+      executor,
+      reviewer,
+      fixer,
+      until: (state) => state.approved === true,
+      config: { maxConcurrency: 4, timeout: 5_000 },
+    }).compile({ timeout: 10_000 });
+
+    expect(compiled.config.maxConcurrency).toBe(4);
+    expect(compiled.config.timeout).toBe(10_000);
+  });
+});
+
+describe("sequential template", () => {
+  test("supports single-node topology", () => {
+    const only = createNode<SequentialState>("only", "tool", async () => ({}));
+
+    const compiled = sequential([only]).compile();
+
+    expect(compiled.startNode).toBe("only");
+    expect(compiled.edges).toHaveLength(0);
+    expect(compiled.endNodes.has("only")).toBe(true);
+  });
+
+  test("creates linear node topology", () => {
+    const first = createNode<SequentialState>("first", "tool", async () => ({}));
+    const second = createNode<SequentialState>("second", "tool", async () => ({}));
+    const third = createNode<SequentialState>("third", "tool", async () => ({}));
+
+    const compiled = sequential([first, second, third]).compile();
+
+    expect(compiled.startNode).toBe("first");
+    expect(compiled.edges).toHaveLength(2);
+    expect(compiled.edges[0]).toMatchObject({ from: "first", to: "second" });
+    expect(compiled.edges[1]).toMatchObject({ from: "second", to: "third" });
+    expect(compiled.endNodes.has("third")).toBe(true);
+  });
+
+  test("throws for empty node lists", () => {
+    expect(() => sequential<SequentialState>([])).toThrow(
+      "Sequential template requires at least one node",
+    );
+  });
+
+  test("applies default graph config from template options", () => {
+    const first = createNode<SequentialState>("first", "tool", async () => ({}));
+    const second = createNode<SequentialState>("second", "tool", async () => ({}));
+
+    const compiled = sequential([first, second], { maxConcurrency: 2 }).compile({ timeout: 4_000 });
+
+    expect(compiled.config.maxConcurrency).toBe(2);
+    expect(compiled.config.timeout).toBe(4_000);
+  });
+
+  test("supports extending the graph before compile", () => {
+    const first = createNode<SequentialState>("first", "tool", async (ctx) => ({
+      stateUpdate: { steps: [...(ctx.state.steps ?? []), "first"] },
+    }));
+    const second = createNode<SequentialState>("second", "tool", async (ctx) => ({
+      stateUpdate: { steps: [...(ctx.state.steps ?? []), "second"] },
+    }));
+    const third = createNode<SequentialState>("third", "tool", async (ctx) => ({
+      stateUpdate: { steps: [...(ctx.state.steps ?? []), "third"] },
+    }));
+
+    const graph = sequential([first, second]).then(third).compile();
+    const result = executeGraph(graph);
+
+    expect(graph.endNodes.has("third")).toBe(true);
+    expect(graph.endNodes.has("second")).toBe(false);
+    return expect(result).resolves.toMatchObject({
+      status: "completed",
+      state: { steps: ["first", "second", "third"] },
+    });
+  });
+});
+
+describe("taskLoop template", () => {
+  test("creates decompose-worker loop topology when reviewer is omitted", () => {
+    const decomposer = createNode<TaskLoopState>("decomposer", "tool", async () => ({}));
+    const worker = createNode<TaskLoopState>("worker", "tool", async () => ({}));
+
+    const compiled = taskLoop<TaskLoopState>({
+      decomposer,
+      worker,
+      maxIterations: 3,
+    }).compile();
+
+    const loopStart = compiled.edges.find((edge) => edge.from === "decomposer");
+    const loopCheck = compiled.edges.find((edge) => edge.from === "worker");
+    const continueEdge = compiled.edges.find(
+      (edge) => edge.to === "worker" && edge.label === "loop-continue",
+    );
+
+    expect(loopStart?.to.startsWith("loop_start_")).toBe(true);
+    expect(loopCheck?.to.startsWith("loop_check_")).toBe(true);
+    expect(continueEdge?.from.startsWith("loop_check_")).toBe(true);
+    expect(Array.from(compiled.endNodes).some((nodeId) => nodeId.startsWith("loop_check_"))).toBe(
+      true,
+    );
+  });
+
+  test("creates decompose-worker-review loop topology", () => {
+    const decomposer = createNode<TaskLoopState>("decomposer", "tool", async () => ({}));
+    const worker = createNode<TaskLoopState>("worker", "tool", async () => ({}));
+    const reviewer = createNode<TaskLoopState>("reviewer", "tool", async () => ({}));
+
+    const compiled = taskLoop<TaskLoopState>({
+      decomposer,
+      worker,
+      reviewer,
+      maxIterations: 3,
+    }).compile();
+
+    expect(compiled.startNode).toBe("decomposer");
+    expect(compiled.edges.some((edge) => edge.from === "decomposer" && edge.to.startsWith("loop_start_"))).toBe(
+      true,
+    );
+    expect(compiled.edges.some((edge) => edge.from === "worker" && edge.to === "reviewer")).toBe(true);
+    expect(compiled.edges.some((edge) => edge.to === "worker" && edge.label === "loop-continue")).toBe(true);
+  });
+
+  test("uses worker completion flags in default until condition", () => {
+    const decomposer = createNode<TaskLoopState>("decomposer", "tool", async () => ({}));
+    const worker = createNode<TaskLoopState>("worker", "tool", async () => ({}));
+
+    const compiled = taskLoop<TaskLoopState>({
+      decomposer,
+      worker,
+    }).compile();
+
+    const loopStartNodeId = Array.from(compiled.nodes.keys()).find((nodeId) =>
+      nodeId.startsWith("loop_start_"),
+    );
+    const continueEdge = compiled.edges.find(
+      (edge) => edge.to === "worker" && edge.label === "loop-continue",
+    );
+
+    expect(loopStartNodeId).toBeDefined();
+    expect(continueEdge?.condition).toBeDefined();
+    if (!loopStartNodeId) {
+      throw new Error("Expected loop start node");
+    }
+
+    const shouldContinue = continueEdge?.condition?.({
+      executionId: "exec-1",
+      lastUpdated: new Date().toISOString(),
+      outputs: {
+        [`${loopStartNodeId}_iteration`]: 0,
+        worker: { allTasksComplete: true },
+      },
+      allTasksComplete: false,
+    });
+
+    expect(shouldContinue).toBe(false);
+  });
+
+  test("runs until worker marks all tasks complete", async () => {
+    const decomposer = createNode<TaskLoopState>("decomposer", "tool", async (ctx) => ({
+      stateUpdate: { planned: (ctx.state.planned ?? 0) + 1 },
+    }));
+    const worker = createNode<TaskLoopState>("worker", "tool", async (ctx) => {
+      const worked = (ctx.state.worked ?? 0) + 1;
+      return {
+        stateUpdate: {
+          worked,
+          outputs: {
+            ...ctx.state.outputs,
+            worker: {
+              allTasksComplete: worked >= 2,
+            },
+          },
+        },
+      };
+    });
+
+    const result = await executeGraph(
+      taskLoop<TaskLoopState>({
+        decomposer,
+        worker,
+        maxIterations: 6,
+      }).compile(),
+    );
+
+    expect(result.status).toBe("completed");
+    expect(result.state.planned).toBe(1);
+    expect(result.state.worked).toBe(2);
+  });
+});
diff --git a/src/workflows/graph/templates.ts b/src/workflows/graph/templates.ts
new file mode 100644
index 0000000000..eb276b967b
--- /dev/null
+++ b/src/workflows/graph/templates.ts
@@ -0,0 +1,211 @@
+/**
+ * Workflow templates for common graph patterns.
+ */
+
+import { graph, type GraphBuilder } from "./builder.ts";
+import type { BaseState, GraphConfig, NodeDefinition } from "./types.ts";
+
+/**
+ * Configuration for the map-reduce workflow template.
+ */
+export interface MapReduceOptions<TState extends BaseState> {
+  splitter: NodeDefinition<TState>;
+  worker: NodeDefinition<TState>;
+  merger: (results: Partial<TState>[], state: TState) => Partial<TState>;
+  config?: Partial<GraphConfig<TState>>;
+}
+
+/**
+ * Configuration for the review-cycle workflow template.
+ */
+export interface ReviewCycleOptions<TState extends BaseState> {
+  executor: NodeDefinition<TState>;
+  reviewer: NodeDefinition<TState>;
+  fixer: NodeDefinition<TState>;
+  until: (state: TState) => boolean;
+  maxIterations?: number;
+  config?: Partial<GraphConfig<TState>>;
+}
+
+/**
+ * Configuration for the task-loop workflow template.
+ */
+export interface TaskLoopOptions<TState extends BaseState> {
+  decomposer: NodeDefinition<TState>;
+  worker: NodeDefinition<TState>;
+  reviewer?: NodeDefinition<TState>;
+  until?: (state: TState) => boolean;
+  maxIterations?: number;
+  config?: Partial<GraphConfig<TState>>;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function isCompletedStatus(status: string): boolean {
+  const normalized = status.trim().toLowerCase();
+  return normalized === "completed" || normalized === "complete" || normalized === "done";
+}
+
+function defaultTaskLoopUntil<TState extends BaseState>(state: TState, workerNodeId: string): boolean {
+  const stateRecord = state as Record<string, unknown>;
+  if (stateRecord.shouldContinue === false || stateRecord.allTasksComplete === true) {
+    return true;
+  }
+
+  const workerOutput = state.outputs[workerNodeId];
+  if (!isRecord(workerOutput)) {
+    return false;
+  }
+
+  if (workerOutput.shouldContinue === false || workerOutput.allTasksComplete === true) {
+    return true;
+  }
+
+  const tasks = workerOutput.tasks;
+  if (!Array.isArray(tasks) || tasks.length === 0) {
+    return false;
+  }
+
+  return tasks.every((task) => {
+    if (!isRecord(task)) {
+      return false;
+    }
+    return typeof task.status === "string" && isCompletedStatus(task.status);
+  });
+}
+
+function applyDefaultConfig<TState extends BaseState>(
+  builder: GraphBuilder<TState>,
+  defaultConfig?: Partial<GraphConfig<TState>>,
+): GraphBuilder<TState> {
+  if (!defaultConfig) {
+    return builder;
+  }
+
+  const originalCompile = builder.compile.bind(builder);
+  builder.compile = (config = {}) => {
+    const mergedConfig: GraphConfig<TState> = {
+      ...defaultConfig,
+      ...config,
+    };
+
+    if (defaultConfig.metadata || config.metadata) {
+      mergedConfig.metadata = {
+        ...defaultConfig.metadata,
+        ...config.metadata,
+      };
+    }
+
+    return originalCompile(mergedConfig);
+  };
+
+  return builder;
+}
+
+/**
+ * Create a linear node chain (node1 -> node2 -> ... -> nodeN).
+ */
+export function sequential<TState extends BaseState>(
+  nodes: NodeDefinition<TState>[],
+  config?: Partial<GraphConfig<TState>>,
+): GraphBuilder<TState> {
+  if (nodes.length === 0) {
+    throw new Error("Sequential template requires at least one node");
+  }
+
+  const [startNode, ...restNodes] = nodes;
+  const builder = graph<TState>().start(startNode!);
+
+  for (const node of restNodes) {
+    builder.then(node);
+  }
+
+  return applyDefaultConfig(builder, config);
+}
+
+function toStateUpdates<TState extends BaseState>(value: unknown): Partial<TState>[] {
+  if (Array.isArray(value)) {
+    return value.filter((entry): entry is Partial<TState> => typeof entry === "object" && entry !== null);
+  }
+
+  if (value instanceof Map) {
+    return Array.from(value.values()).filter(
+      (entry): entry is Partial<TState> => typeof entry === "object" && entry !== null,
+    );
+  }
+
+  if (typeof value === "object" && value !== null) {
+    return [value as Partial<TState>];
+  }
+
+  return [];
+}
+
+/**
+ * Create a splitter -> worker -> reducer graph.
+ *
+ * The reducer receives the worker output normalized to `Partial<TState>[]`.
+ * Worker output is read from `state.outputs[worker.id]`.
+ */
+export function mapReduce<TState extends BaseState>(
+  options: MapReduceOptions<TState>,
+): GraphBuilder<TState> {
+  const reducerNodeId = `${options.worker.id}_reduce`;
+
+  const reducerNode: NodeDefinition<TState> = {
+    id: reducerNodeId,
+    type: "tool",
+    execute: async (ctx) => {
+      const workerOutput = ctx.state.outputs[options.worker.id];
+      const mappedResults = toStateUpdates<TState>(workerOutput);
+      return {
+        stateUpdate: options.merger(mappedResults, ctx.state),
+      };
+    },
+  };
+
+  const builder = graph<TState>()
+    .start(options.splitter)
+    .then(options.worker)
+    .then(reducerNode);
+
+  return applyDefaultConfig(builder, options.config);
+}
+
+/**
+ * Create an execute -> review -> fix loop.
+ */
+export function reviewCycle<TState extends BaseState>(
+  options: ReviewCycleOptions<TState>,
+): GraphBuilder<TState> {
+  const builder = graph<TState>()
+    .loop([options.executor, options.reviewer, options.fixer], {
+      until: options.until,
+      maxIterations: options.maxIterations,
+    })
+    .end();
+
+  return applyDefaultConfig(builder, options.config);
+}
+
+/**
+ * Create a decompose -> worker -> optional reviewer loop.
+ */
+export function taskLoop<TState extends BaseState>(
+  options: TaskLoopOptions<TState>,
+): GraphBuilder<TState> {
+  const loopNodes = options.reviewer ? [options.worker, options.reviewer] : options.worker;
+  const until = options.until ?? ((state: TState) => defaultTaskLoopUntil(state, options.worker.id));
+
+  const builder = graph<TState>()
+    .start(options.decomposer)
+    .loop(loopNodes, {
+      until,
+      maxIterations: options.maxIterations,
+    })
+    .end();
+
+  return applyDefaultConfig(builder, options.config);
+}
diff --git a/src/graph/types.test.ts b/src/workflows/graph/types.test.ts
similarity index 100%
rename from src/graph/types.test.ts
rename to src/workflows/graph/types.test.ts
diff --git a/src/graph/types.ts b/src/workflows/graph/types.ts
similarity index 80%
rename from src/graph/types.ts
rename to src/workflows/graph/types.ts
index 484e2f2aa6..6427f4a490 100644
--- a/src/graph/types.ts
+++ b/src/workflows/graph/types.ts
@@ -1,3 +1,12 @@
+import type { z } from "zod";
+import type { CodingAgentClient, Session, SessionConfig } from "../../sdk/types.ts";
+import type { SubagentEntry } from "./subagent-registry.ts";
+import type {
+  WorkflowRuntimeFeatureFlags,
+  WorkflowRuntimeTask,
+  WorkflowRuntimeTaskIdentityRuntime,
+} from "../runtime-contracts.ts";
+
 /**
  * Graph Execution Engine Types
  *
@@ -194,6 +203,15 @@ export interface RetryConfig {
   retryOn?: (error: Error) => boolean;
 }
 
+/**
+ * Action returned by node-level error handlers.
+ */
+export type ErrorAction<TState extends BaseState = BaseState> =
+  | { action: "retry"; delay?: number }
+  | { action: "skip"; fallbackState?: Partial<TState> }
+  | { action: "abort"; error?: Error }
+  | { action: "goto"; nodeId: NodeId };
+
 /**
  * Debug report generated when an error occurs during execution.
  * Contains diagnostic information to help resolve the issue.
@@ -270,10 +288,10 @@ export interface ExecutionContext<TState extends BaseState = BaseState> {
   contextWindowThreshold?: number;
 
   /**
-   * Emit a signal during execution.
-   * @param signal - The signal data to emit
+   * Emit a custom stream event during execution.
+   * - `emit(type, data)` emits a custom stream event payload.
    */
-  emit?: (signal: SignalData) => void;
+  emit?: (type: string, data?: Record<string, unknown>) => void;
 
   /**
    * Get the output from a previously executed node.
@@ -316,9 +334,28 @@ export interface NodeDefinition<TState extends BaseState = BaseState> {
   /** Function to execute when the node is visited */
   execute: NodeExecuteFn<TState>;
 
+  /** Optional schema for validating node input state before execution */
+  inputSchema?: z.ZodType<TState>;
+
+  /** Optional schema for validating node output state after execution */
+  outputSchema?: z.ZodType<TState>;
+
   /** Optional retry configuration for error handling */
   retry?: RetryConfig;
 
+  /**
+   * Optional node-level error hook for custom recovery behavior.
+   */
+  onError?: (
+    error: Error,
+    context: ExecutionContext<TState>
+  ) => ErrorAction<TState> | Promise<ErrorAction<TState>>;
+
+  /**
+   * Marks this node as a valid recovery target for `onError` goto actions.
+   */
+  isRecoveryNode?: boolean;
+
   /** Human-readable name for the node (used in logging/UI) */
   name?: string;
 
@@ -356,6 +393,105 @@ export interface ProgressEvent<TState extends BaseState = BaseState> {
   timestamp: string;
 }
 
+export interface RuntimeSubgraph {
+  execute(state: BaseState): Promise<BaseState>;
+}
+
+// ============================================================================
+// SUBAGENT TYPES
+// ============================================================================
+
+/**
+ * Factory function that creates independent sessions for sub-agents.
+ */
+export type CreateSessionFn = (config?: SessionConfig) => Promise<Session>;
+
+/**
+ * Options for spawning a single sub-agent session.
+ */
+export interface SubagentSpawnOptions {
+  /** Unique identifier for this sub-agent */
+  agentId: string;
+  /** Display name (e.g., "codebase-analyzer", "debugger") */
+  agentName: string;
+  /** Task description to send to the sub-agent */
+  task: string;
+  /** Optional system prompt override */
+  systemPrompt?: string;
+  /** Optional model override */
+  model?: string;
+  /** Optional tool restrictions */
+  tools?: string[];
+  /** Optional timeout in milliseconds. When exceeded, the session is aborted. */
+  timeout?: number;
+  /** Optional external abort signal (e.g., from Ctrl+C) to cancel the sub-agent. */
+  abortSignal?: AbortSignal;
+}
+
+/**
+ * Detail record for a single tool invocation within a sub-agent session.
+ */
+export interface SubagentToolDetail {
+  /** Tool invocation ID */
+  toolId: string;
+  /** Tool name */
+  toolName: string;
+  /** Execution duration in milliseconds */
+  durationMs: number;
+  /** Whether the tool completed successfully */
+  success: boolean;
+}
+
+/**
+ * Result returned after a sub-agent completes or fails.
+ *
+ * Replaces the former SubagentResult with richer streaming metadata:
+ * full untruncated output, token usage, thinking duration, and tool details.
+ */
+export interface SubagentStreamResult {
+  /** Agent identifier matching SubagentSpawnOptions.agentId */
+  agentId: string;
+  /** Whether the sub-agent completed successfully */
+  success: boolean;
+  /** Full untruncated text output from the sub-agent */
+  output: string;
+  /** Error message if the sub-agent failed */
+  error?: string;
+  /** Number of tool invocations during execution */
+  toolUses: number;
+  /** Execution duration in milliseconds */
+  durationMs: number;
+  /** Token usage from the sub-agent session */
+  tokenUsage?: { inputTokens: number; outputTokens: number };
+  /** Total thinking/reasoning duration in milliseconds */
+  thinkingDurationMs?: number;
+  /** Per-tool invocation details */
+  toolDetails?: SubagentToolDetail[];
+}
+
+
+// ============================================================================
+// GRAPH RUNTIME DEPENDENCIES
+// ============================================================================
+
+export interface GraphRuntimeDependencies {
+  clientProvider?: (agentType: string) => CodingAgentClient | null;
+  workflowResolver?: (name: string) => RuntimeSubgraph | null;
+  spawnSubagent?: (agent: SubagentSpawnOptions, abortSignal?: AbortSignal) => Promise<SubagentStreamResult>;
+  spawnSubagentParallel?: (agents: SubagentSpawnOptions[], abortSignal?: AbortSignal) => Promise<SubagentStreamResult[]>;
+  taskIdentity?: WorkflowRuntimeTaskIdentityRuntime;
+  featureFlags?: WorkflowRuntimeFeatureFlags;
+  subagentRegistry?: {
+    get(name: string): SubagentEntry | undefined;
+    getAll(): SubagentEntry[];
+  };
+  notifyTaskStatusChange?: (
+    taskIds: string[],
+    newStatus: string,
+    tasks: WorkflowRuntimeTask[],
+  ) => void;
+}
+
 /**
  * Configuration for graph execution.
  *
@@ -410,6 +546,18 @@ export interface GraphConfig<TState extends BaseState = BaseState> {
    * Claude aliases (`opus`, `sonnet`, `haiku`) are also accepted.
    */
   defaultModel?: ModelSpec;
+
+  /**
+   * Optional runtime validation schema for workflow state.
+   * When provided, state updates are validated after each node execution.
+   */
+  outputSchema?: z.ZodType<TState>;
+
+  /**
+   * Runtime dependencies provided by WorkflowSDK.init().
+   * Used by node factories that require SDK services.
+   */
+  runtime?: GraphRuntimeDependencies;
 }
 
 // ============================================================================
diff --git a/src/workflows/index.ts b/src/workflows/index.ts
index f515fabb2b..be8fc5b8ff 100644
--- a/src/workflows/index.ts
+++ b/src/workflows/index.ts
@@ -1,8 +1,10 @@
 /**
  * Workflows Module
  *
- * This module exports workflow session management for the Atomic CLI.
- * Sessions are stored at ~/.atomic/workflows/sessions/{sessionId}/
+ * Unified barrel for the workflow engine. Re-exports:
+ * - graph/: Core graph execution engine (builder, executor, nodes, streaming)
+ * - session: Workflow session management
+ * - ralph/: Ralph autonomous workflow definitions
  */
 
 export {
@@ -14,3 +16,16 @@ export {
   saveWorkflowSession,
   saveSubagentOutput,
 } from "./session.ts";
+
+export {
+  buildTaskResultEnvelope,
+  formatTaskResultEnvelopeText,
+} from "./task-result-envelope.ts";
+
+// Graph execution engine
+export * from "./graph/index.ts";
+
+// Ralph workflow
+export * from "./ralph/state.ts";
+export * from "./ralph/prompts.ts";
+export * from "./ralph/graph.ts";
diff --git a/src/workflows/ralph/definition.test.ts b/src/workflows/ralph/definition.test.ts
new file mode 100644
index 0000000000..ee44471d18
--- /dev/null
+++ b/src/workflows/ralph/definition.test.ts
@@ -0,0 +1,87 @@
+/**
+ * Tests for Ralph Workflow Definition
+ */
+
+import { describe, test, expect } from "bun:test";
+import { ralphWorkflowDefinition, ralphNodeDescriptions } from "./definition.ts";
+import { VERSION } from "../../version.ts";
+import type { RalphWorkflowState } from "./state.ts";
+
+describe("Ralph Workflow Definition", () => {
+    test("exports ralphNodeDescriptions with all expected nodes", () => {
+        const expectedNodes = [
+            "planner",
+            "parse-tasks",
+            "select-ready-tasks",
+            "worker",
+            "reviewer",
+            "prepare-fix-tasks",
+            "fixer",
+        ];
+
+        expect(Object.keys(ralphNodeDescriptions)).toEqual(expectedNodes);
+
+        // Verify all descriptions are non-empty strings
+        for (const nodeId of expectedNodes) {
+            const description = ralphNodeDescriptions[nodeId];
+            expect(typeof description).toBe("string");
+            expect(description && description.length).toBeGreaterThan(0);
+        }
+    });
+
+    test("ralphWorkflowDefinition has correct metadata", () => {
+        expect(ralphWorkflowDefinition.name).toBe("ralph");
+        expect(ralphWorkflowDefinition.description).toBe("Start autonomous implementation workflow");
+        expect(ralphWorkflowDefinition.aliases).toEqual(["loop"]);
+        expect(ralphWorkflowDefinition.version).toBe("1.0.0");
+        expect(ralphWorkflowDefinition.minSDKVersion).toBe(VERSION);
+        expect(ralphWorkflowDefinition.stateVersion).toBe(1);
+        expect(ralphWorkflowDefinition.argumentHint).toBe('"<prompt-or-spec-path>"');
+        expect(ralphWorkflowDefinition.source).toBe("builtin");
+    });
+
+    test("ralphWorkflowDefinition includes createState factory", () => {
+        expect(typeof ralphWorkflowDefinition.createState).toBe("function");
+    });
+
+    test("ralphWorkflowDefinition includes nodeDescriptions", () => {
+        expect(ralphWorkflowDefinition.nodeDescriptions).toBe(ralphNodeDescriptions);
+    });
+
+    test("ralphWorkflowDefinition does not include graphConfig", () => {
+        // Ralph uses createRalphWorkflow() builder pattern, not declarative graphConfig
+        expect(ralphWorkflowDefinition.graphConfig).toBeUndefined();
+    });
+
+    test("createState factory produces valid RalphWorkflowState", () => {
+        const params = {
+            prompt: "Test prompt",
+            sessionId: "test-session-id",
+            sessionDir: "/test/session/dir",
+            maxIterations: 50,
+        };
+
+        const state = ralphWorkflowDefinition.createState!(params) as RalphWorkflowState;
+
+        expect(state.executionId).toBe(params.sessionId);
+        expect(state.yoloPrompt).toBe(params.prompt);
+        expect(state.ralphSessionId).toBe(params.sessionId);
+        expect(state.ralphSessionDir).toBe(params.sessionDir);
+        expect(state.maxIterations).toBe(params.maxIterations);
+
+        // Verify other expected fields are initialized
+        expect(state.tasks).toEqual([]);
+        expect(state.currentTasks).toEqual([]);
+        expect(state.iteration).toBe(1);
+        expect(typeof state.lastUpdated).toBe("string");
+        expect(state.yolo).toBe(false);
+    });
+
+    test("node descriptions match expected format", () => {
+        // All descriptions should have an emoji and descriptive text
+        for (const [nodeId, description] of Object.entries(ralphNodeDescriptions)) {
+            expect(description).toMatch(/^[⌕☰◎⚙◉⚒]/); // Starts with emoji
+            expect(description.length).toBeGreaterThan(10); // Has descriptive text
+        }
+    });
+});
diff --git a/src/workflows/ralph/definition.ts b/src/workflows/ralph/definition.ts
new file mode 100644
index 0000000000..834d0c419d
--- /dev/null
+++ b/src/workflows/ralph/definition.ts
@@ -0,0 +1,64 @@
+/**
+ * Ralph Workflow Definition
+ *
+ * Consolidates Ralph's metadata, graph config, state factory, and node descriptions
+ * into a single WorkflowDefinition object for the workflow registry.
+ */
+
+import type { WorkflowDefinition, WorkflowStateParams } from "../../ui/commands/workflow-commands.ts";
+import { createRalphState } from "./state.ts";
+import { VERSION } from "../../version.ts";
+
+/**
+ * Node descriptions for Ralph workflow progress UI.
+ * Extracted from the hardcoded getNodePhaseDescription() function.
+ * Maps node IDs to human-readable progress descriptions.
+ */
+export const ralphNodeDescriptions: Record<string, string> = {
+    planner: "⌕ Planning: Analyzing requirements and decomposing into tasks...",
+    "parse-tasks": "☰ Parsing: Extracting task structure from plan...",
+    "select-ready-tasks": "◎ Selecting: Identifying ready tasks for execution...",
+    worker: "⚙ Working: Implementing assigned task...",
+    reviewer: "◉ Reviewing: Evaluating completed work...",
+    "prepare-fix-tasks": "☰ Planning Fixes: Converting review findings into fix tasks...",
+    fixer: "⚒ Fixing: Applying review feedback...",
+};
+
+/**
+ * Factory function to create Ralph workflow state.
+ * Wraps createRalphState() with the standard WorkflowStateParams interface.
+ *
+ * @param params - Standard workflow state parameters
+ * @returns Initialized RalphWorkflowState
+ */
+function createRalphWorkflowState(params: WorkflowStateParams) {
+    return createRalphState(params.sessionId, {
+        yoloPrompt: params.prompt,
+        ralphSessionId: params.sessionId,
+        ralphSessionDir: params.sessionDir,
+        maxIterations: params.maxIterations,
+    });
+}
+
+/**
+ * Complete workflow definition for Ralph.
+ * Consolidates metadata, state factory, and node descriptions.
+ *
+ * Note: Ralph uses createRalphWorkflow() for its compiled graph (builder pattern),
+ * so no graphConfig is provided. The graphConfig field is for user-defined workflows
+ * that provide declarative config.
+ */
+export const ralphWorkflowDefinition: WorkflowDefinition = {
+    name: "ralph",
+    description: "Start autonomous implementation workflow",
+    aliases: ["loop"],
+    version: "1.0.0",
+    minSDKVersion: VERSION,
+    stateVersion: 1,
+    argumentHint: '"<prompt-or-spec-path>"',
+    source: "builtin",
+
+    // Execution logic
+    createState: createRalphWorkflowState,
+    nodeDescriptions: ralphNodeDescriptions,
+};
diff --git a/src/workflows/ralph/graph.test.ts b/src/workflows/ralph/graph.test.ts
new file mode 100644
index 0000000000..c2700c918c
--- /dev/null
+++ b/src/workflows/ralph/graph.test.ts
@@ -0,0 +1,1448 @@
+/**
+ * Integration tests for createRalphWorkflow()
+ *
+ * These tests verify the 3-phase flow of the Ralph workflow with mocked spawn functions:
+ * Phase 1: Planner subagent → parse-tasks tool (decompose prompt into task list)
+ * Phase 2: Worker loop (select ready tasks → worker subagent, repeats until all done)
+ * Phase 3: Reviewer subagent → conditional fixer subagent
+ */
+
+import { describe, expect, test } from "bun:test";
+import { executeGraph, streamGraph } from "../graph/compiled.ts";
+import type {
+  SubagentSpawnOptions,
+  SubagentStreamResult,
+} from "../graph/types.ts";
+import { createRalphWorkflow } from "./graph.ts";
+import { createRalphState } from "./state.ts";
+import type { RalphWorkflowState } from "./state.ts";
+import { TaskIdentityService } from "../task-identity-service.ts";
+
+// ============================================================================
+// MOCK SPAWN FUNCTIONS
+// ============================================================================
+
+/**
+ * Mock spawn functions for testing.
+ * Maps agent names to response handlers.
+ */
+function createMockSpawnFunctions(
+  responses: Map<
+    string,
+    (opts: SubagentSpawnOptions) => SubagentStreamResult | Promise<SubagentStreamResult>
+  >
+) {
+  async function spawnSubagent(agent: SubagentSpawnOptions): Promise<SubagentStreamResult> {
+    const handler = responses.get(agent.agentName);
+    if (!handler) {
+      return {
+        agentId: agent.agentId,
+        success: false,
+        output: "",
+        error: `No handler for agent: ${agent.agentName}`,
+        toolUses: 0,
+        durationMs: 0,
+      };
+    }
+    return await handler(agent);
+  }
+
+  async function spawnSubagentParallel(
+    agents: SubagentSpawnOptions[]
+  ): Promise<SubagentStreamResult[]> {
+    return Promise.all(agents.map((a) => spawnSubagent(a)));
+  }
+
+  return { spawnSubagent, spawnSubagentParallel };
+}
+
+/**
+ * Mock SubagentRegistry that returns a dummy entry for any requested agent.
+ */
+function createMockRegistry() {
+  return {
+    get(name: string) {
+      return {
+        name,
+        info: {
+          name,
+          description: `Mock agent: ${name}`,
+          source: "project" as const,
+          filePath: `/mock/${name}.md`,
+        },
+        source: "project" as const,
+      };
+    },
+    getAll() {
+      return [];
+    },
+  };
+}
+
+/**
+ * Helper to create a workflow with mock spawn functions and registry injected.
+ */
+function createWorkflowWithMockBridge(
+  responses: Map<
+    string,
+    (opts: SubagentSpawnOptions) => SubagentStreamResult | Promise<SubagentStreamResult>
+  >
+) {
+  const baseWorkflow = createRalphWorkflow();
+  const { spawnSubagent, spawnSubagentParallel } = createMockSpawnFunctions(responses);
+  return {
+    ...baseWorkflow,
+    config: {
+      ...baseWorkflow.config,
+      runtime: {
+        spawnSubagent,
+        spawnSubagentParallel,
+        taskIdentity: new TaskIdentityService(),
+        subagentRegistry: createMockRegistry(),
+      },
+    },
+  };
+}
+
+// ============================================================================
+// TESTS
+// ============================================================================
+
+describe("createRalphWorkflow - Basic Compilation", () => {
+  test("compiles without error", () => {
+    const workflow = createRalphWorkflow();
+
+    expect(workflow).toBeDefined();
+    expect(workflow.nodes.size).toBeGreaterThan(0);
+    expect(workflow.startNode).toBe("planner");
+    expect(workflow.nodes.has("planner")).toBe(true);
+    expect(workflow.nodes.has("parse-tasks")).toBe(true);
+    expect(workflow.nodes.has("select-ready-tasks")).toBe(true);
+    expect(workflow.nodes.has("worker")).toBe(true);
+    expect(workflow.nodes.has("reviewer")).toBe(true);
+    expect(workflow.nodes.has("prepare-fix-tasks")).toBe(true);
+    expect(workflow.nodes.has("fixer")).toBe(true);
+  });
+});
+
+describe("createRalphWorkflow - 3-Phase Flow", () => {
+  test("executes 3-phase flow with simple tasks", async () => {
+    const mockResponses = new Map<
+      string,
+      (opts: SubagentSpawnOptions) => SubagentStreamResult
+    >();
+
+    // Phase 1: Planner returns JSON task list with 2 independent tasks
+    mockResponses.set("planner", () => ({
+      agentId: "planner-1",
+      success: true,
+      output: JSON.stringify([
+        {
+          id: "#1",
+          content: "Task 1",
+          status: "pending",
+          activeForm: "Doing task 1",
+          blockedBy: [],
+        },
+        {
+          id: "#2",
+          content: "Task 2",
+          status: "pending",
+          activeForm: "Doing task 2",
+          blockedBy: [],
+        },
+      ]),
+      toolUses: 0,
+      durationMs: 10,
+    }));
+
+    // Phase 2: Worker completes tasks (will be called twice, once for each task)
+    let workerCallCount = 0;
+    mockResponses.set("worker", () => {
+      workerCallCount++;
+      return {
+        agentId: `worker-${workerCallCount}`,
+        success: true,
+        output: `Completed task ${workerCallCount}`,
+        toolUses: 2,
+        durationMs: 50,
+      };
+    });
+
+    // Phase 3: Reviewer returns "patch is correct"
+    mockResponses.set("reviewer", () => ({
+      agentId: "reviewer-1",
+      success: true,
+      output: JSON.stringify({
+        findings: [],
+        overall_correctness: "patch is correct",
+        overall_explanation: "All tasks completed successfully",
+      }),
+      toolUses: 1,
+      durationMs: 30,
+    }));
+
+    // Create compiled workflow with mock bridge
+    const workflow = createWorkflowWithMockBridge(mockResponses);
+
+    const initialState: Partial<RalphWorkflowState> = {
+      ...createRalphState("test-exec-1", { yoloPrompt: "test prompt" }),
+      maxIterations: 10,
+      ralphSessionDir: "/tmp/test-session",
+    };
+
+    const result = await executeGraph(workflow, {
+      initialState,
+      executionId: "test-exec-1",
+    });
+
+    expect(result.status).toBe("completed");
+    expect(result.state.tasks).toHaveLength(2);
+    expect(result.state.tasks[0]?.status).toBe("completed");
+    expect(result.state.tasks[1]?.status).toBe("completed");
+    expect(result.state.reviewResult).toBeDefined();
+    expect(result.state.reviewResult?.overall_correctness).toBe(
+      "patch is correct"
+    );
+    expect(result.state.fixesApplied).toBe(false);
+    // Worker is called once per task — each iteration dispatches ready[0]
+    // and only marks that single dispatched task as completed
+    expect(workerCallCount).toBe(2);
+  });
+
+  test("handles task dependencies in worker loop", async () => {
+    const mockResponses = new Map<
+      string,
+      (opts: SubagentSpawnOptions) => SubagentStreamResult
+    >();
+
+    // Phase 1: Planner returns tasks where #2 is blocked by #1
+    mockResponses.set("planner", () => ({
+      agentId: "planner-1",
+      success: true,
+      output: JSON.stringify([
+        {
+          id: "#1",
+          content: "Task 1",
+          status: "pending",
+          activeForm: "Doing task 1",
+          blockedBy: [],
+        },
+        {
+          id: "#2",
+          content: "Task 2",
+          status: "pending",
+          activeForm: "Doing task 2",
+          blockedBy: ["#1"],
+        },
+      ]),
+      toolUses: 0,
+      durationMs: 10,
+    }));
+
+    // Phase 2: Worker completes tasks
+    const executionOrder: string[] = [];
+    mockResponses.set("worker", (opts) => {
+      // Parse task from the worker assignment prompt
+      const taskMatch = opts.task.match(/\*\*Task ID:\*\* (#\d+)/);
+      const taskId = taskMatch?.[1] ?? "unknown";
+      executionOrder.push(taskId);
+
+      return {
+        agentId: `worker-${taskId}`,
+        success: true,
+        output: `Completed ${taskId}`,
+        toolUses: 2,
+        durationMs: 50,
+      };
+    });
+
+    // Phase 3: Reviewer
+    mockResponses.set("reviewer", () => ({
+      agentId: "reviewer-1",
+      success: true,
+      output: JSON.stringify({
+        findings: [],
+        overall_correctness: "patch is correct",
+        overall_explanation: "Dependencies respected",
+      }),
+      toolUses: 1,
+      durationMs: 30,
+    }));
+
+    const workflow = createWorkflowWithMockBridge(mockResponses);
+
+    const initialState: Partial<RalphWorkflowState> = {
+      ...createRalphState("test-exec-2", { yoloPrompt: "test prompt" }),
+      maxIterations: 10,
+      ralphSessionDir: "/tmp/test-session",
+    };
+
+    const result = await executeGraph(workflow, {
+      initialState,
+      executionId: "test-exec-2",
+    });
+
+    expect(result.status).toBe("completed");
+    expect(result.state.tasks).toHaveLength(2);
+    expect(result.state.tasks[0]?.status).toBe("completed");
+    expect(result.state.tasks[1]?.status).toBe("completed");
+
+    // Verify execution order: #1 must complete before #2
+    expect(executionOrder).toEqual(["#1", "#2"]);
+  });
+
+  test("triggers fixer when review has findings", async () => {
+    const mockResponses = new Map<
+      string,
+      (opts: SubagentSpawnOptions) => SubagentStreamResult
+    >();
+
+    // Phase 1: Planner
+    mockResponses.set("planner", () => ({
+      agentId: "planner-1",
+      success: true,
+      output: JSON.stringify([
+        {
+          id: "#1",
+          content: "Task 1",
+          status: "pending",
+          activeForm: "Doing task 1",
+          blockedBy: [],
+        },
+      ]),
+      toolUses: 0,
+      durationMs: 10,
+    }));
+
+    // Phase 2: Worker
+    mockResponses.set("worker", () => ({
+      agentId: "worker-1",
+      success: true,
+      output: "Completed task 1",
+      toolUses: 2,
+      durationMs: 50,
+    }));
+
+    // Phase 3: Reviewer returns findings with "patch is incorrect"
+    mockResponses.set("reviewer", () => ({
+      agentId: "reviewer-1",
+      success: true,
+      output: JSON.stringify({
+        findings: [
+          {
+            title: "[P0] Critical bug found",
+            body: "Logic error in implementation",
+            confidence_score: 0.95,
+            priority: 0,
+          },
+        ],
+        overall_correctness: "patch is incorrect",
+        overall_explanation: "Critical issues found",
+      }),
+      toolUses: 1,
+      durationMs: 30,
+    }));
+
+    // Fixer should be triggered
+    let fixerCalled = false;
+    mockResponses.set("debugger", () => {
+      fixerCalled = true;
+      return {
+        agentId: "fixer-1",
+        success: true,
+        output: "Applied fixes",
+        toolUses: 3,
+        durationMs: 100,
+      };
+    });
+
+    const workflow = createWorkflowWithMockBridge(mockResponses);
+
+    const initialState: Partial<RalphWorkflowState> = {
+      ...createRalphState("test-exec-3", { yoloPrompt: "test prompt" }),
+      maxIterations: 10,
+      ralphSessionDir: "/tmp/test-session",
+    };
+
+    const result = await executeGraph(workflow, {
+      initialState,
+      executionId: "test-exec-3",
+    });
+
+    expect(result.status).toBe("completed");
+    expect(result.state.reviewResult?.overall_correctness).toBe(
+      "patch is incorrect"
+    );
+    expect(result.state.reviewResult?.findings).toHaveLength(1);
+    expect(fixerCalled).toBe(true);
+    expect(result.state.fixesApplied).toBe(true);
+    const reviewFixTask = result.state.tasks.find((task: any) => task.id === "#review-fix-1");
+    expect(reviewFixTask).toBeDefined();
+    expect(reviewFixTask?.status).toBe("completed");
+  });
+
+  test("triggers fixer for actionable findings even when review says patch is correct", async () => {
+    const mockResponses = new Map<
+      string,
+      (opts: SubagentSpawnOptions) => SubagentStreamResult
+    >();
+
+    mockResponses.set("planner", () => ({
+      agentId: "planner-1",
+      success: true,
+      output: JSON.stringify([
+        {
+          id: "#1",
+          content: "Task 1",
+          status: "pending",
+          activeForm: "Doing task 1",
+          blockedBy: [],
+        },
+      ]),
+      toolUses: 0,
+      durationMs: 10,
+    }));
+
+    mockResponses.set("worker", () => ({
+      agentId: "worker-1",
+      success: true,
+      output: "Completed task 1",
+      toolUses: 2,
+      durationMs: 50,
+    }));
+
+    mockResponses.set("reviewer", () => ({
+      agentId: "reviewer-1",
+      success: true,
+      output: JSON.stringify({
+        findings: [
+          {
+            title: "[P2] Missing edge-case coverage",
+            body: "Add a guard test for malformed input",
+            confidence_score: 0.84,
+            priority: 2,
+          },
+        ],
+        overall_correctness: "patch is correct",
+        overall_explanation: "Feature works, but robustness can improve",
+      }),
+      toolUses: 1,
+      durationMs: 30,
+    }));
+
+    let fixerCalled = false;
+    mockResponses.set("debugger", () => {
+      fixerCalled = true;
+      return {
+        agentId: "fixer-1",
+        success: true,
+        output: "Applied robustness fix",
+        toolUses: 1,
+        durationMs: 60,
+      };
+    });
+
+    const workflow = createWorkflowWithMockBridge(mockResponses);
+
+    const initialState: Partial<RalphWorkflowState> = {
+      ...createRalphState("test-exec-3b", { yoloPrompt: "test prompt" }),
+      maxIterations: 10,
+      ralphSessionDir: "/tmp/test-session",
+    };
+
+    const result = await executeGraph(workflow, {
+      initialState,
+      executionId: "test-exec-3b",
+    });
+
+    expect(result.status).toBe("completed");
+    expect(result.state.reviewResult?.overall_correctness).toBe("patch is correct");
+    expect(result.state.reviewResult?.findings).toHaveLength(1);
+    expect(fixerCalled).toBe(true);
+    expect(result.state.fixesApplied).toBe(true);
+  });
+
+  test("skips fixer when review is clean", async () => {
+    const mockResponses = new Map<
+      string,
+      (opts: SubagentSpawnOptions) => SubagentStreamResult
+    >();
+
+    // Phase 1: Planner
+    mockResponses.set("planner", () => ({
+      agentId: "planner-1",
+      success: true,
+      output: JSON.stringify([
+        {
+          id: "#1",
+          content: "Task 1",
+          status: "pending",
+          activeForm: "Doing task 1",
+          blockedBy: [],
+        },
+      ]),
+      toolUses: 0,
+      durationMs: 10,
+    }));
+
+    // Phase 2: Worker
+    mockResponses.set("worker", () => ({
+      agentId: "worker-1",
+      success: true,
+      output: "Completed task 1",
+      toolUses: 2,
+      durationMs: 50,
+    }));
+
+    // Phase 3: Reviewer returns "patch is correct"
+    mockResponses.set("reviewer", () => ({
+      agentId: "reviewer-1",
+      success: true,
+      output: JSON.stringify({
+        findings: [],
+        overall_correctness: "patch is correct",
+        overall_explanation: "No issues found",
+      }),
+      toolUses: 1,
+      durationMs: 30,
+    }));
+
+    // Fixer should NOT be triggered
+    let fixerCalled = false;
+    mockResponses.set("debugger", () => {
+      fixerCalled = true;
+      return {
+        agentId: "fixer-1",
+        success: true,
+        output: "Applied fixes",
+        toolUses: 3,
+        durationMs: 100,
+      };
+    });
+
+    const workflow = createWorkflowWithMockBridge(mockResponses);
+
+    const initialState: Partial<RalphWorkflowState> = {
+      ...createRalphState("test-exec-4", { yoloPrompt: "test prompt" }),
+      maxIterations: 10,
+      ralphSessionDir: "/tmp/test-session",
+    };
+
+    const result = await executeGraph(workflow, {
+      initialState,
+      executionId: "test-exec-4",
+    });
+
+    expect(result.status).toBe("completed");
+    expect(result.state.reviewResult?.overall_correctness).toBe(
+      "patch is correct"
+    );
+    expect(fixerCalled).toBe(false);
+    expect(result.state.fixesApplied).toBe(false);
+  });
+});
+
+describe("createRalphWorkflow - Worker Loop", () => {
+  test("exits loop when no actionable tasks remain", async () => {
+    const mockResponses = new Map<
+      string,
+      (opts: SubagentSpawnOptions) => SubagentStreamResult
+    >();
+
+    // Phase 1: Planner returns tasks where #2 depends on #1, but #1 will error
+    mockResponses.set("planner", () => ({
+      agentId: "planner-1",
+      success: true,
+      output: JSON.stringify([
+        {
+          id: "#1",
+          content: "Task 1",
+          status: "pending",
+          activeForm: "Doing task 1",
+          blockedBy: [],
+        },
+        {
+          id: "#2",
+          content: "Task 2",
+          status: "pending",
+          activeForm: "Doing task 2",
+          blockedBy: ["#1"],
+        },
+      ]),
+      toolUses: 0,
+      durationMs: 10,
+    }));
+
+    // Phase 2: Worker fails for task #1
+    let workerCallCount = 0;
+    mockResponses.set("worker", () => {
+      workerCallCount++;
+      return {
+        agentId: `worker-${workerCallCount}`,
+        success: false,
+        output: "Failed to complete task",
+        error: "Task 1 failed",
+        toolUses: 1,
+        durationMs: 20,
+      };
+    });
+
+    // Phase 3: Reviewer
+    mockResponses.set("reviewer", () => ({
+      agentId: "reviewer-1",
+      success: true,
+      output: JSON.stringify({
+        findings: [],
+        overall_correctness: "patch is correct",
+        overall_explanation: "Some tasks incomplete",
+      }),
+      toolUses: 1,
+      durationMs: 30,
+    }));
+
+    const workflow = createWorkflowWithMockBridge(mockResponses);
+
+    const initialState: Partial<RalphWorkflowState> = {
+      ...createRalphState("test-exec-5", { yoloPrompt: "test prompt" }),
+      maxIterations: 10,
+      ralphSessionDir: "/tmp/test-session",
+    };
+
+    const result = await executeGraph(workflow, {
+      initialState,
+      executionId: "test-exec-5",
+      maxSteps: 50,
+    });
+
+    // Worker failure sets task #1 to "error", making #2 stuck (dependency on errored #1).
+    // Loop exits because hasActionableTasks returns false. Workflow completes (not fails).
+    expect(result.status).toBe("completed");
+    expect(workerCallCount).toBe(1);
+    // Task #1 should be "error", #2 should still be "pending" (blocked)
+    const task1 = result.state.tasks.find((t: any) => t.id === "#1");
+    const task2 = result.state.tasks.find((t: any) => t.id === "#2");
+    expect(task1?.status).toBe("error");
+    expect(task2?.status).toBe("pending");
+  });
+
+  test("respects maxIterations limit", async () => {
+    const mockResponses = new Map<
+      string,
+      (opts: SubagentSpawnOptions) => SubagentStreamResult
+    >();
+
+    // Phase 1: Planner returns 5 chained tasks (each blocked by previous)
+    mockResponses.set("planner", () => ({
+      agentId: "planner-1",
+      success: true,
+      output: JSON.stringify([
+        { id: "#1", content: "Task 1", status: "pending", activeForm: "Doing 1", blockedBy: [] },
+        { id: "#2", content: "Task 2", status: "pending", activeForm: "Doing 2", blockedBy: ["#1"] },
+        { id: "#3", content: "Task 3", status: "pending", activeForm: "Doing 3", blockedBy: ["#2"] },
+        { id: "#4", content: "Task 4", status: "pending", activeForm: "Doing 4", blockedBy: ["#3"] },
+        { id: "#5", content: "Task 5", status: "pending", activeForm: "Doing 5", blockedBy: ["#4"] },
+      ]),
+      toolUses: 0,
+      durationMs: 10,
+    }));
+
+    // Phase 2: Worker always succeeds but processes one task per iteration
+    let workerCallCount = 0;
+    mockResponses.set("worker", () => {
+      workerCallCount++;
+      return {
+        agentId: `worker-${workerCallCount}`,
+        success: true,
+        output: `Completed task ${workerCallCount}`,
+        toolUses: 1,
+        durationMs: 10,
+      };
+    });
+
+    // Phase 3: Reviewer
+    mockResponses.set("reviewer", () => ({
+      agentId: "reviewer-1",
+      success: true,
+      output: JSON.stringify({
+        findings: [],
+        overall_correctness: "patch is correct",
+        overall_explanation: "Iteration limit reached",
+      }),
+      toolUses: 1,
+      durationMs: 30,
+    }));
+
+    const workflow = createWorkflowWithMockBridge(mockResponses);
+
+    const initialState: Partial<RalphWorkflowState> = {
+      ...createRalphState("test-exec-6", { yoloPrompt: "test prompt" }),
+      maxIterations: 3, // Only allow 3 iterations out of 5 needed
+      ralphSessionDir: "/tmp/test-session",
+    };
+
+    const result = await executeGraph(workflow, {
+      initialState,
+      executionId: "test-exec-6",
+      maxSteps: 50,
+    });
+
+    // Loop exits after 3 iterations due to maxIterations limit
+    expect(result.status).toBe("completed");
+    expect(workerCallCount).toBe(3);
+    // 3 tasks completed, 2 still pending
+    const completed = result.state.tasks.filter((t: any) => t.status === "completed");
+    const pending = result.state.tasks.filter((t: any) => t.status === "pending");
+    expect(completed).toHaveLength(3);
+    expect(pending).toHaveLength(2);
+  });
+});
+
+describe("createRalphWorkflow - Edge Cases", () => {
+  test("handles empty task list from planner", async () => {
+    const mockResponses = new Map<
+      string,
+      (opts: SubagentSpawnOptions) => SubagentStreamResult
+    >();
+
+    // Phase 1: Planner returns empty array
+    mockResponses.set("planner", () => ({
+      agentId: "planner-1",
+      success: true,
+      output: "[]",
+      toolUses: 0,
+      durationMs: 10,
+    }));
+
+    // Phase 2: Worker should not be called
+    let workerCalled = false;
+    mockResponses.set("worker", () => {
+      workerCalled = true;
+      return {
+        agentId: "worker-1",
+        success: true,
+        output: "Should not be called",
+        toolUses: 0,
+        durationMs: 10,
+      };
+    });
+
+    // Phase 3: Reviewer
+    mockResponses.set("reviewer", () => ({
+      agentId: "reviewer-1",
+      success: true,
+      output: JSON.stringify({
+        findings: [],
+        overall_correctness: "patch is correct",
+        overall_explanation: "No tasks to review",
+      }),
+      toolUses: 1,
+      durationMs: 30,
+    }));
+
+    const workflow = createWorkflowWithMockBridge(mockResponses);
+
+    const initialState: Partial<RalphWorkflowState> = {
+      ...createRalphState("test-exec-7", { yoloPrompt: "test prompt" }),
+      maxIterations: 10,
+      ralphSessionDir: "/tmp/test-session",
+    };
+
+    const result = await executeGraph(workflow, {
+      initialState,
+      executionId: "test-exec-7",
+    });
+
+    expect(result.status).toBe("completed");
+    expect(result.state.tasks).toHaveLength(0);
+    // Worker node exits early when no tasks are ready (no spawnSubagent call)
+    expect(workerCalled).toBe(false);
+  });
+
+  test("filters out low-priority P3 findings", async () => {
+    const mockResponses = new Map<
+      string,
+      (opts: SubagentSpawnOptions) => SubagentStreamResult
+    >();
+
+    // Phase 1: Planner
+    mockResponses.set("planner", () => ({
+      agentId: "planner-1",
+      success: true,
+      output: JSON.stringify([
+        {
+          id: "#1",
+          content: "Task 1",
+          status: "pending",
+          activeForm: "Doing task 1",
+          blockedBy: [],
+        },
+      ]),
+      toolUses: 0,
+      durationMs: 10,
+    }));
+
+    // Phase 2: Worker
+    mockResponses.set("worker", () => ({
+      agentId: "worker-1",
+      success: true,
+      output: "Completed task 1",
+      toolUses: 2,
+      durationMs: 50,
+    }));
+
+    // Phase 3: Reviewer returns only P3 findings
+    mockResponses.set("reviewer", () => ({
+      agentId: "reviewer-1",
+      success: true,
+      output: JSON.stringify({
+        findings: [
+          {
+            title: "[P3] Minor style issue",
+            body: "Consider using const instead of let",
+            confidence_score: 0.8,
+            priority: 3,
+          },
+        ],
+        overall_correctness: "patch is correct",
+        overall_explanation: "Only minor style issues",
+      }),
+      toolUses: 1,
+      durationMs: 30,
+    }));
+
+    // Fixer should NOT be triggered (P3 filtered out)
+    let fixerCalled = false;
+    mockResponses.set("debugger", () => {
+      fixerCalled = true;
+      return {
+        agentId: "fixer-1",
+        success: true,
+        output: "Applied fixes",
+        toolUses: 3,
+        durationMs: 100,
+      };
+    });
+
+    const workflow = createWorkflowWithMockBridge(mockResponses);
+
+    const initialState: Partial<RalphWorkflowState> = {
+      ...createRalphState("test-exec-8", { yoloPrompt: "test prompt" }),
+      maxIterations: 10,
+      ralphSessionDir: "/tmp/test-session",
+    };
+
+    const result = await executeGraph(workflow, {
+      initialState,
+      executionId: "test-exec-8",
+    });
+
+    expect(result.status).toBe("completed");
+    // P3 findings should be filtered out by parseReviewResult
+    expect(result.state.reviewResult?.findings).toHaveLength(0);
+    expect(fixerCalled).toBe(false);
+  });
+});
+
+// ============================================================================
+// PARALLEL DISPATCH TESTS
+// ============================================================================
+
+describe("createRalphWorkflow - Parallel Worker Dispatch", () => {
+  test("dispatches all independent tasks in a single spawnSubagentParallel call", async () => {
+    const mockResponses = new Map<
+      string,
+      (opts: SubagentSpawnOptions) => SubagentStreamResult
+    >();
+
+    // Phase 1: Planner returns 3 independent tasks (no dependencies)
+    mockResponses.set("planner", () => ({
+      agentId: "planner-1",
+      success: true,
+      output: JSON.stringify([
+        { id: "#1", content: "Task 1", status: "pending", activeForm: "Doing 1", blockedBy: [] },
+        { id: "#2", content: "Task 2", status: "pending", activeForm: "Doing 2", blockedBy: [] },
+        { id: "#3", content: "Task 3", status: "pending", activeForm: "Doing 3", blockedBy: [] },
+      ]),
+      toolUses: 0,
+      durationMs: 10,
+    }));
+
+    // Phase 2: Worker succeeds for all
+    mockResponses.set("worker", (opts) => ({
+      agentId: opts.agentId,
+      success: true,
+      output: `Completed ${opts.agentId}`,
+      toolUses: 1,
+      durationMs: 10,
+    }));
+
+    // Phase 3: Reviewer
+    mockResponses.set("reviewer", () => ({
+      agentId: "reviewer-1",
+      success: true,
+      output: JSON.stringify({
+        findings: [],
+        overall_correctness: "patch is correct",
+        overall_explanation: "All good",
+      }),
+      toolUses: 1,
+      durationMs: 10,
+    }));
+
+    // Track spawnSubagentParallel calls to verify batching
+    const parallelCalls: SubagentSpawnOptions[][] = [];
+    const { spawnSubagent, spawnSubagentParallel } = createMockSpawnFunctions(mockResponses);
+
+    const trackingSpawnParallel = async (
+      agents: SubagentSpawnOptions[],
+      abortSignal?: AbortSignal
+    ): Promise<SubagentStreamResult[]> => {
+      parallelCalls.push([...agents]);
+      return spawnSubagentParallel(agents);
+    };
+
+    const workflow = createRalphWorkflow();
+    const workflowWithMocks = {
+      ...workflow,
+      config: {
+        ...workflow.config,
+        runtime: {
+          spawnSubagent,
+          spawnSubagentParallel: trackingSpawnParallel,
+          subagentRegistry: createMockRegistry(),
+        },
+      },
+    };
+
+    const initialState: Partial<RalphWorkflowState> = {
+      ...createRalphState("test-parallel-1", { yoloPrompt: "test prompt" }),
+      maxIterations: 10,
+      ralphSessionDir: "/tmp/test-session",
+    };
+
+    const result = await executeGraph(workflowWithMocks, {
+      initialState,
+      executionId: "test-parallel-1",
+    });
+
+    expect(result.status).toBe("completed");
+    expect(result.state.tasks).toHaveLength(3);
+    expect(result.state.tasks.every((t: any) => t.status === "completed")).toBe(true);
+
+    // All 3 independent tasks dispatched in one spawnSubagentParallel call (1 batch for workers)
+    const workerBatches = parallelCalls.filter(
+      (batch) => batch.some((a) => a.agentName === "worker")
+    );
+    expect(workerBatches).toHaveLength(1);
+    expect(workerBatches[0]).toHaveLength(3);
+    expect(workerBatches[0]!.map((a) => a.agentId).sort()).toEqual([
+      "worker-#1",
+      "worker-#2",
+      "worker-#3",
+    ]);
+  });
+
+  test("returns error when spawnSubagentParallel is not available", async () => {
+    const mockResponses = new Map<
+      string,
+      (opts: SubagentSpawnOptions) => SubagentStreamResult
+    >();
+
+    // Phase 1: Planner returns a task
+    mockResponses.set("planner", () => ({
+      agentId: "planner-1",
+      success: true,
+      output: JSON.stringify([
+        { id: "#1", content: "Task 1", status: "pending", activeForm: "Doing 1", blockedBy: [] },
+      ]),
+      toolUses: 0,
+      durationMs: 10,
+    }));
+
+    const { spawnSubagent } = createMockSpawnFunctions(mockResponses);
+
+    // Deliberately omit spawnSubagentParallel from runtime
+    const workflow = createRalphWorkflow();
+    const workflowWithMocks = {
+      ...workflow,
+      config: {
+        ...workflow.config,
+        runtime: {
+          spawnSubagent,
+          // spawnSubagentParallel intentionally NOT provided
+          subagentRegistry: createMockRegistry(),
+        },
+      },
+    };
+
+    const initialState: Partial<RalphWorkflowState> = {
+      ...createRalphState("test-no-parallel", { yoloPrompt: "test prompt" }),
+      maxIterations: 10,
+      ralphSessionDir: "/tmp/test-session",
+    };
+
+    // executeGraph catches errors and returns status "error"
+    const result = await executeGraph(workflowWithMocks, {
+      initialState,
+      executionId: "test-no-parallel",
+    });
+
+    expect(result.status).toBe("failed");
+    // Error is in the snapshot's errors array
+    const errorMessages = result.snapshot.errors.map((e: any) => {
+      const err = e.error;
+      return typeof err === "string" ? err : err?.message ?? "";
+    });
+    expect(errorMessages.some((m: string) => m.includes("spawnSubagentParallel not available in runtime config"))).toBe(true);
+  });
+
+  test("maps results independently — failed tasks get error, successful get completed", async () => {
+    const mockResponses = new Map<
+      string,
+      (opts: SubagentSpawnOptions) => SubagentStreamResult
+    >();
+
+    // Phase 1: Planner returns 3 independent tasks
+    mockResponses.set("planner", () => ({
+      agentId: "planner-1",
+      success: true,
+      output: JSON.stringify([
+        { id: "#1", content: "Task 1", status: "pending", activeForm: "Doing 1", blockedBy: [] },
+        { id: "#2", content: "Task 2", status: "pending", activeForm: "Doing 2", blockedBy: [] },
+        { id: "#3", content: "Task 3", status: "pending", activeForm: "Doing 3", blockedBy: [] },
+      ]),
+      toolUses: 0,
+      durationMs: 10,
+    }));
+
+    // Phase 2: Worker — #1 succeeds, #2 fails, #3 succeeds
+    mockResponses.set("worker", (opts) => {
+      const isTask2 = opts.agentId === "worker-#2";
+      return {
+        agentId: opts.agentId,
+        success: !isTask2,
+        output: isTask2 ? "Failed" : "Completed",
+        error: isTask2 ? "Task 2 failed" : undefined,
+        toolUses: 1,
+        durationMs: 10,
+      };
+    });
+
+    // Phase 3: Reviewer
+    mockResponses.set("reviewer", () => ({
+      agentId: "reviewer-1",
+      success: true,
+      output: JSON.stringify({
+        findings: [],
+        overall_correctness: "patch is correct",
+        overall_explanation: "Mixed results",
+      }),
+      toolUses: 1,
+      durationMs: 10,
+    }));
+
+    const workflow = createWorkflowWithMockBridge(mockResponses);
+
+    const initialState: Partial<RalphWorkflowState> = {
+      ...createRalphState("test-mixed-results", { yoloPrompt: "test prompt" }),
+      maxIterations: 10,
+      ralphSessionDir: "/tmp/test-session",
+    };
+
+    const result = await executeGraph(workflow, {
+      initialState,
+      executionId: "test-mixed-results",
+      maxSteps: 50,
+    });
+
+    expect(result.status).toBe("completed");
+    const task1 = result.state.tasks.find((t: any) => t.id === "#1");
+    const task2 = result.state.tasks.find((t: any) => t.id === "#2");
+    const task3 = result.state.tasks.find((t: any) => t.id === "#3");
+    expect(task1?.status).toBe("completed");
+    expect(task2?.status).toBe("error");
+    expect(task3?.status).toBe("completed");
+  });
+
+  test("assigns unique worker agent IDs when task IDs are duplicated", async () => {
+    const mockResponses = new Map<
+      string,
+      (opts: SubagentSpawnOptions) => SubagentStreamResult
+    >();
+
+    mockResponses.set("planner", () => ({
+      agentId: "planner-dup",
+      success: true,
+      output: JSON.stringify([
+        { id: "#1", content: "Task A", status: "pending", activeForm: "Doing A", blockedBy: [] },
+        { id: "#1", content: "Task B", status: "pending", activeForm: "Doing B", blockedBy: [] },
+        { id: "#2", content: "Task C", status: "pending", activeForm: "Doing C", blockedBy: [] },
+      ]),
+      toolUses: 0,
+      durationMs: 10,
+    }));
+
+    mockResponses.set("worker", (opts) => {
+      const secondDuplicate = opts.agentId.endsWith("-2");
+      return {
+        agentId: opts.agentId,
+        success: !secondDuplicate,
+        output: secondDuplicate ? "duplicate failed" : "ok",
+        error: secondDuplicate ? "duplicate failure" : undefined,
+        toolUses: 1,
+        durationMs: 10,
+      };
+    });
+
+    mockResponses.set("reviewer", () => ({
+      agentId: "reviewer-dup",
+      success: true,
+      output: JSON.stringify({
+        findings: [],
+        overall_correctness: "patch is correct",
+        overall_explanation: "All good",
+      }),
+      toolUses: 1,
+      durationMs: 10,
+    }));
+
+    const workerBatchAgentIds: string[] = [];
+    const { spawnSubagent, spawnSubagentParallel } = createMockSpawnFunctions(mockResponses);
+    const trackingSpawnParallel = async (agents: SubagentSpawnOptions[]) => {
+      if (agents.some((agent) => agent.agentName === "worker")) {
+        workerBatchAgentIds.push(...agents.map((agent) => agent.agentId));
+      }
+      return spawnSubagentParallel(agents);
+    };
+
+    const workflow = createRalphWorkflow();
+    const workflowWithMocks = {
+      ...workflow,
+      config: {
+        ...workflow.config,
+        runtime: {
+          spawnSubagent,
+          spawnSubagentParallel: trackingSpawnParallel,
+          subagentRegistry: createMockRegistry(),
+        },
+      },
+    };
+
+    const initialState: Partial<RalphWorkflowState> = {
+      ...createRalphState("test-duplicate-task-ids", { yoloPrompt: "test prompt" }),
+      maxIterations: 10,
+      ralphSessionDir: "/tmp/test-session",
+    };
+
+    const result = await executeGraph(workflowWithMocks, {
+      initialState,
+      executionId: "test-duplicate-task-ids",
+    });
+
+    expect(result.status).toBe("completed");
+    expect(workerBatchAgentIds.sort()).toEqual([
+      "worker-#1",
+      "worker-#1-2",
+      "worker-#2",
+    ]);
+    expect(result.state.tasks.map((task: any) => task.status)).toEqual([
+      "completed",
+      "error",
+      "completed",
+    ]);
+  });
+
+  test("increments iteration by 1 per batch, not per task", async () => {
+    const mockResponses = new Map<
+      string,
+      (opts: SubagentSpawnOptions) => SubagentStreamResult
+    >();
+
+    // Phase 1: Planner returns 4 independent tasks
+    mockResponses.set("planner", () => ({
+      agentId: "planner-1",
+      success: true,
+      output: JSON.stringify([
+        { id: "#1", content: "Task 1", status: "pending", activeForm: "Doing 1", blockedBy: [] },
+        { id: "#2", content: "Task 2", status: "pending", activeForm: "Doing 2", blockedBy: [] },
+        { id: "#3", content: "Task 3", status: "pending", activeForm: "Doing 3", blockedBy: [] },
+        { id: "#4", content: "Task 4", status: "pending", activeForm: "Doing 4", blockedBy: [] },
+      ]),
+      toolUses: 0,
+      durationMs: 10,
+    }));
+
+    // Phase 2: Worker succeeds
+    mockResponses.set("worker", (opts) => ({
+      agentId: opts.agentId,
+      success: true,
+      output: `Completed`,
+      toolUses: 1,
+      durationMs: 10,
+    }));
+
+    // Phase 3: Reviewer
+    mockResponses.set("reviewer", () => ({
+      agentId: "reviewer-1",
+      success: true,
+      output: JSON.stringify({
+        findings: [],
+        overall_correctness: "patch is correct",
+        overall_explanation: "All done",
+      }),
+      toolUses: 1,
+      durationMs: 10,
+    }));
+
+    const workflow = createWorkflowWithMockBridge(mockResponses);
+
+    const initialState: Partial<RalphWorkflowState> = {
+      ...createRalphState("test-iteration-count", { yoloPrompt: "test prompt" }),
+      maxIterations: 10,
+      ralphSessionDir: "/tmp/test-session",
+    };
+
+    const result = await executeGraph(workflow, {
+      initialState,
+      executionId: "test-iteration-count",
+    });
+
+    expect(result.status).toBe("completed");
+    expect(result.state.tasks).toHaveLength(4);
+    expect(result.state.tasks.every((t: any) => t.status === "completed")).toBe(true);
+    // All 4 independent tasks dispatched in 1 batch → 1 iteration
+    expect(result.state.iteration).toBe(1);
+  });
+
+  test("calls notifyTaskStatusChange with in_progress before spawning", async () => {
+    const mockResponses = new Map<
+      string,
+      (opts: SubagentSpawnOptions) => SubagentStreamResult
+    >();
+
+    // Phase 1: Planner returns 2 independent tasks
+    mockResponses.set("planner", () => ({
+      agentId: "planner-1",
+      success: true,
+      output: JSON.stringify([
+        { id: "#1", content: "Task 1", status: "pending", activeForm: "Doing 1", blockedBy: [] },
+        { id: "#2", content: "Task 2", status: "pending", activeForm: "Doing 2", blockedBy: [] },
+      ]),
+      toolUses: 0,
+      durationMs: 10,
+    }));
+
+    // Phase 2: Worker succeeds
+    mockResponses.set("worker", (opts) => ({
+      agentId: opts.agentId,
+      success: true,
+      output: "Completed",
+      toolUses: 1,
+      durationMs: 10,
+    }));
+
+    // Phase 3: Reviewer
+    mockResponses.set("reviewer", () => ({
+      agentId: "reviewer-1",
+      success: true,
+      output: JSON.stringify({
+        findings: [],
+        overall_correctness: "patch is correct",
+        overall_explanation: "Done",
+      }),
+      toolUses: 1,
+      durationMs: 10,
+    }));
+
+    // Track notifyTaskStatusChange calls
+    const statusChangeCalls: Array<{
+      taskIds: string[];
+      newStatus: string;
+      tasks: Array<{ id: string; title: string; status: string }>;
+    }> = [];
+
+    const { spawnSubagent, spawnSubagentParallel } = createMockSpawnFunctions(mockResponses);
+
+    const workflow = createRalphWorkflow();
+    const workflowWithMocks = {
+      ...workflow,
+      config: {
+        ...workflow.config,
+        runtime: {
+          spawnSubagent,
+          spawnSubagentParallel,
+          taskIdentity: new TaskIdentityService(),
+          subagentRegistry: createMockRegistry(),
+          notifyTaskStatusChange: (
+            taskIds: string[],
+            newStatus: string,
+            tasks: Array<{ id: string; title: string; status: string }>
+          ) => {
+            statusChangeCalls.push({ taskIds, newStatus, tasks });
+          },
+        },
+      },
+    };
+
+    const initialState: Partial<RalphWorkflowState> = {
+      ...createRalphState("test-status-change", { yoloPrompt: "test prompt" }),
+      maxIterations: 10,
+      ralphSessionDir: "/tmp/test-session",
+    };
+
+    const result = await executeGraph(workflowWithMocks, {
+      initialState,
+      executionId: "test-status-change",
+    });
+
+    expect(result.status).toBe("completed");
+
+    // notifyTaskStatusChange should have been called at least once with "in_progress"
+    const inProgressCalls = statusChangeCalls.filter((c) => c.newStatus === "in_progress");
+    expect(inProgressCalls.length).toBeGreaterThanOrEqual(1);
+
+    // The first in_progress call should include both task IDs
+    const firstCall = inProgressCalls[0]!;
+    expect(firstCall.taskIds.sort()).toEqual(["#1", "#2"]);
+    expect(firstCall.newStatus).toBe("in_progress");
+
+    // The tasks array should show in_progress status for the ready tasks
+    const inProgressTasks = firstCall.tasks.filter((t) => t.status === "in_progress");
+    expect(inProgressTasks).toHaveLength(2);
+
+    // Provider task bindings should be attached for runtime correlation.
+    const firstTaskIdentity = (inProgressTasks[0] as any)?.identity;
+    expect(firstTaskIdentity?.providerBindings?.subagent_id?.length ?? 0).toBeGreaterThan(0);
+  });
+
+  test("attaches task result envelope with canonical identity metadata", async () => {
+    const mockResponses = new Map<
+      string,
+      (opts: SubagentSpawnOptions) => SubagentStreamResult
+    >();
+
+    mockResponses.set("planner", () => ({
+      agentId: "planner-1",
+      success: true,
+      output: JSON.stringify([
+        { id: "#1", content: "Task 1", status: "pending", activeForm: "Doing 1", blockedBy: [] },
+      ]),
+      toolUses: 0,
+      durationMs: 10,
+    }));
+
+    mockResponses.set("worker", (opts) => ({
+      agentId: opts.agentId,
+      success: true,
+      output: "Completed Task 1",
+      toolUses: 1,
+      durationMs: 10,
+    }));
+
+    mockResponses.set("reviewer", () => ({
+      agentId: "reviewer-1",
+      success: true,
+      output: JSON.stringify({
+        findings: [],
+        overall_correctness: "patch is correct",
+        overall_explanation: "Done",
+      }),
+      toolUses: 1,
+      durationMs: 10,
+    }));
+
+    const workflow = createWorkflowWithMockBridge(mockResponses);
+    const result = await executeGraph(workflow, {
+      initialState: {
+        ...createRalphState("test-task-result-envelope", { yoloPrompt: "test prompt" }),
+        maxIterations: 10,
+        ralphSessionDir: "/tmp/test-session",
+      },
+      executionId: "test-task-result-envelope",
+    });
+
+    expect(result.status).toBe("completed");
+    const task = result.state.tasks.find((t: any) => t.id === "#1");
+    expect(task?.taskResult).toMatchObject({
+      task_id: "#1",
+      tool_name: "task",
+      status: "completed",
+      metadata: {
+        sessionId: "test-task-result-envelope",
+      },
+      output_text: "Completed Task 1",
+    });
+    expect(task?.taskResult?.metadata?.providerBindings?.subagent_id).toBe("worker-#1");
+    expect(task?.taskResult?.envelope_text).toContain("<task_result>");
+  });
+
+  test("worker prompt includes completed task context from previous batches", async () => {
+    const mockResponses = new Map<
+      string,
+      (opts: SubagentSpawnOptions) => SubagentStreamResult
+    >();
+
+    // Phase 1: Planner returns 2 tasks — #2 depends on #1
+    mockResponses.set("planner", () => ({
+      agentId: "planner-1",
+      success: true,
+      output: JSON.stringify([
+        { id: "#1", content: "Task 1", status: "pending", activeForm: "Doing 1", blockedBy: [] },
+        { id: "#2", content: "Task 2", status: "pending", activeForm: "Doing 2", blockedBy: ["#1"] },
+      ]),
+      toolUses: 0,
+      durationMs: 10,
+    }));
+
+    // Phase 2: Worker — capture the task prompt to verify task context
+    const workerPrompts: string[] = [];
+    mockResponses.set("worker", (opts) => {
+      workerPrompts.push(opts.task);
+      return {
+        agentId: opts.agentId,
+        success: true,
+        output: "Completed",
+        toolUses: 1,
+        durationMs: 10,
+      };
+    });
+
+    // Phase 3: Reviewer
+    mockResponses.set("reviewer", () => ({
+      agentId: "reviewer-1",
+      success: true,
+      output: JSON.stringify({
+        findings: [],
+        overall_correctness: "patch is correct",
+        overall_explanation: "Done",
+      }),
+      toolUses: 1,
+      durationMs: 10,
+    }));
+
+    const workflow = createWorkflowWithMockBridge(mockResponses);
+
+    const initialState: Partial<RalphWorkflowState> = {
+      ...createRalphState("test-progress-context", { yoloPrompt: "test prompt" }),
+      maxIterations: 10,
+      ralphSessionDir: "/tmp/test-session",
+    };
+
+    const result = await executeGraph(workflow, {
+      initialState,
+      executionId: "test-progress-context",
+    });
+
+    expect(result.status).toBe("completed");
+    // Worker called twice: first for #1 (batch 1), then for #2 (batch 2, after #1 completes)
+    expect(workerPrompts).toHaveLength(2);
+
+    // Second worker prompt (for task #2) should show task #1 as completed in context
+    // because buildWorkerAssignment receives the updated tasks after first batch completed
+    expect(workerPrompts[1]).toContain("#1");
+    expect(workerPrompts[1]).toContain("Task 1");
+    // The completed tasks section should be present in the second worker's prompt
+    expect(workerPrompts[1]).toContain("Completed");
+  });
+});
diff --git a/src/workflows/ralph/graph.ts b/src/workflows/ralph/graph.ts
new file mode 100644
index 0000000000..e036f6b171
--- /dev/null
+++ b/src/workflows/ralph/graph.ts
@@ -0,0 +1,530 @@
+/**
+ * Graph-based Ralph Workflow
+ * 
+ * Expresses the Ralph autonomous implementation workflow as a compiled graph:
+ * Phase 1: Task decomposition via planner sub-agent
+ * Phase 2: Worker loop — select ready tasks, dispatch workers in parallel
+ * Phase 3: Review & conditional fix
+ */
+
+import {
+  graph,
+  toolNode,
+} from "../graph/index.ts";
+import type { NodeDefinition, ExecutionContext, NodeResult } from "../graph/types.ts";
+import type { SubagentSpawnOptions } from "../graph/types.ts";
+import type { WorkflowRuntimeTask } from "../runtime-contracts.ts";
+import { buildTaskResultEnvelope } from "../task-result-envelope.ts";
+import type { RalphWorkflowState } from "./state.ts";
+import {
+  buildSpecToTasksPrompt,
+  buildWorkerAssignment,
+  buildReviewPrompt,
+  buildFixSpecFromReview,
+  parseReviewResult,
+  type TaskItem,
+} from "./prompts.ts";
+
+// ============================================================================
+// UTILITY FUNCTIONS
+// ============================================================================
+
+/**
+ * Parse LLM output containing a JSON task array into TaskItem[].
+ * Tries direct parse first, then regex extraction.
+ */
+function parseTasks(content: string): TaskItem[] {
+  const trimmed = content.trim();
+  let parsed: unknown = null;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch {
+    const match = trimmed.match(/\[[\s\S]*\]/);
+    if (match) {
+      try {
+        parsed = JSON.parse(match[0]);
+      } catch {
+        /* ignore */
+      }
+    }
+  }
+  if (!Array.isArray(parsed) || parsed.length === 0) return [];
+  return parsed as TaskItem[];
+}
+
+/**
+ * Get tasks that are ready to execute (pending with all dependencies met).
+ */
+function getReadyTasks(tasks: TaskItem[]): TaskItem[] {
+  const completedIds = new Set(
+    tasks
+      .filter((t) => t.status === "completed" || t.status === "complete" || t.status === "done")
+      .map((t) => t.id)
+      .filter((id): id is string => Boolean(id))
+      .map((id) => id.trim().toLowerCase().replace(/^#/, ""))
+  );
+
+  return tasks.filter((task) => {
+    if (task.status !== "pending") return false;
+    const deps = (task.blockedBy ?? [])
+      .map((d) => d.trim().toLowerCase().replace(/^#/, ""))
+      .filter((d) => d.length > 0);
+    return deps.every((d) => completedIds.has(d));
+  });
+}
+
+/**
+ * Check if there are any actionable tasks remaining.
+ */
+function hasActionableTasks(tasks: TaskItem[]): boolean {
+  return tasks.some((task) => {
+    if (task.status === "in_progress") return true;
+    if (task.status !== "pending") return false;
+    return getReadyTasks([...tasks]).some((t) => t.id === task.id);
+  });
+}
+
+function stripPriorityPrefix(title: string): string {
+  return title.replace(/^\s*\[(?:P\d|p\d)\]\s*/u, "").trim();
+}
+
+function toRuntimeTask(task: TaskItem, fallbackId: string): WorkflowRuntimeTask {
+  return {
+    id: task.id ?? fallbackId,
+    title: task.content,
+    status: task.status,
+    blockedBy: task.blockedBy,
+    identity: task.identity,
+    taskResult: task.taskResult,
+  };
+}
+
+function applyRuntimeTask(task: TaskItem, runtimeTask: WorkflowRuntimeTask): TaskItem {
+  const taskResult = runtimeTask.taskResult ?? task.taskResult;
+  return {
+    ...task,
+    id: runtimeTask.id,
+    status: runtimeTask.status,
+    blockedBy: runtimeTask.blockedBy,
+    identity: runtimeTask.identity,
+    ...(taskResult ? { taskResult } : {}),
+  };
+}
+
+function buildReviewFixTasks(findings: ReadonlyArray<{
+  title?: string;
+  body?: string;
+}>): TaskItem[] {
+  if (findings.length === 0) {
+    return [{
+      id: "#review-fix-1",
+      content: "Address review feedback",
+      status: "pending",
+      activeForm: "Addressing review feedback",
+      blockedBy: [],
+    }];
+  }
+
+  return findings.map((finding, index) => {
+    const fallback = `Address review finding ${index + 1}`;
+    const normalizedTitle = typeof finding.title === "string"
+      ? stripPriorityPrefix(finding.title)
+      : "";
+    const content = normalizedTitle.length > 0 ? normalizedTitle : fallback;
+
+    return {
+      id: `#review-fix-${index + 1}`,
+      content,
+      status: "pending",
+      activeForm: `Addressing ${content}`,
+      blockedBy: [],
+    } satisfies TaskItem;
+  });
+}
+
+// ============================================================================
+// RALPH GRAPH WORKFLOW
+// ============================================================================
+
+/**
+ * Create the Ralph workflow as a compiled graph.
+ *
+ * Three-phase flow:
+ * 1. Task Decomposition: Planner sub-agent decomposes spec into task list
+ * 2. Worker Loop: Iteratively select ready tasks and dispatch workers
+ * 3. Review & Fix: Reviewer evaluates, optional fixer applies corrections
+ */
+export function createRalphWorkflow() {
+  return graph<RalphWorkflowState>()
+    // Phase 1: Task Decomposition
+    .subagent({
+      id: "planner",
+      agent: "planner",
+      task: (state) => buildSpecToTasksPrompt(state.yoloPrompt ?? ""),
+      outputMapper: (result, _state) => ({
+        specDoc: result.output ?? "",
+      }),
+      name: "Planner",
+      description: "Decomposes user prompt into a task list",
+    })
+    .tool({
+      id: "parse-tasks",
+      toolName: "parse-tasks",
+      execute: async (args: { specDoc: string }) => parseTasks(args.specDoc),
+      args: (state: RalphWorkflowState) => ({ specDoc: state.specDoc }),
+      outputMapper: (tasks: TaskItem[], _state: RalphWorkflowState) => ({
+        tasks,
+        currentTasks: tasks,
+        iteration: 0,
+      }),
+      name: "Task Parser",
+      description: "Parse spec document into structured task list",
+    })
+
+    // Phase 2: Worker Loop
+    .loop(
+      [
+        toolNode<RalphWorkflowState, { tasks: TaskItem[] }, TaskItem[]>({
+          id: "select-ready-tasks",
+          toolName: "select-ready-tasks",
+          execute: async (args) => getReadyTasks(args.tasks),
+          args: (state) => ({ tasks: state.tasks }),
+          outputMapper: (readyTasks, _state) => ({
+            currentTasks: readyTasks,
+          }),
+          name: "Task Selector",
+          description: "Select tasks ready for execution",
+        }),
+        // Custom worker node: handles failures gracefully by setting task
+        // status to "error" instead of throwing (matches procedural handler).
+        {
+          id: "worker",
+          type: "agent",
+          name: "Worker",
+          description: "Implements assigned tasks",
+          retry: { maxAttempts: 1, backoffMs: 0, backoffMultiplier: 1 },
+          async execute(ctx: ExecutionContext<RalphWorkflowState>): Promise<NodeResult<RalphWorkflowState>> {
+            const spawnSubagentParallel = ctx.config.runtime?.spawnSubagentParallel;
+            if (!spawnSubagentParallel) {
+              throw new Error("spawnSubagentParallel not available in runtime config");
+            }
+            const taskIdentity = ctx.config.runtime?.taskIdentity;
+
+            const ready = ctx.state.currentTasks;
+            if (ready.length === 0) {
+              return { stateUpdate: { iteration: ctx.state.iteration + 1 } as Partial<RalphWorkflowState> };
+            }
+
+            // Build a stable ready-task index once so status/result mapping stays
+            // deterministic even when task IDs are missing or duplicated.
+            const readyIndexByTask = new Map<TaskItem, number>();
+            for (const [index, task] of ready.entries()) {
+              readyIndexByTask.set(task, index);
+            }
+
+            // Set all ready tasks to "in_progress" before dispatch
+            const tasksWithProgress = ctx.state.tasks.map((task) =>
+              readyIndexByTask.has(task)
+                ? { ...task, status: "in_progress" }
+                : task,
+            );
+
+            // Build spawn configs for ALL ready tasks.
+            // Keep IDs stable for normal flows while guaranteeing uniqueness
+            // when tasks have duplicate IDs.
+            const agentIdCounts = new Map<string, number>();
+            const spawnConfigs: SubagentSpawnOptions[] = ready.map((task, index) => {
+              const baseAgentId = `worker-${task.id ?? `${ctx.state.executionId}-${ctx.state.iteration}-${index}`}`;
+              const nextCount = (agentIdCounts.get(baseAgentId) ?? 0) + 1;
+              agentIdCounts.set(baseAgentId, nextCount);
+
+              return {
+                agentId: nextCount === 1 ? baseAgentId : `${baseAgentId}-${nextCount}`,
+                agentName: "worker",
+                task: buildWorkerAssignment(task, tasksWithProgress),
+              };
+            });
+
+            const readyTaskProviderBindings = new Map<TaskItem, string>();
+            for (const [index, task] of ready.entries()) {
+              const spawnConfig = spawnConfigs[index];
+              if (!spawnConfig) {
+                continue;
+              }
+              readyTaskProviderBindings.set(task, spawnConfig.agentId);
+            }
+
+            const identityBoundTasks = tasksWithProgress.map((task, taskIndex) => {
+              const sourceTask = ctx.state.tasks[taskIndex];
+              const providerTaskId = sourceTask ? readyTaskProviderBindings.get(sourceTask) : undefined;
+
+              if (!providerTaskId || !taskIdentity) {
+                return task;
+              }
+
+              const runtimeTask = toRuntimeTask(task, `${ctx.state.executionId}-${ctx.state.iteration}-${taskIndex}`);
+              const boundTask = taskIdentity.bindProviderId(runtimeTask, "subagent_id", providerTaskId);
+              return applyRuntimeTask(task, boundTask);
+            });
+
+            // Publish workflow.task.statusChange event before spawning.
+            // notifyTaskStatusChange is injected at runtime by the executor when an eventBus is available.
+            const notifyFn = ctx.config.runtime?.notifyTaskStatusChange;
+            notifyFn?.(
+              ready.map((r) => r.id).filter((id): id is string => Boolean(id)),
+              "in_progress",
+              identityBoundTasks.map((task, index) => {
+                const runtimeTask = toRuntimeTask(task, `${ctx.state.executionId}-${ctx.state.iteration}-${index}`);
+                return {
+                  id: task.id ?? "",
+                  title: task.content,
+                  status: task.status,
+                  blockedBy: task.blockedBy,
+                  identity: runtimeTask.identity,
+                };
+              }),
+            );
+
+            // Dispatch all concurrently via spawnSubagentParallel
+            const results = await spawnSubagentParallel(spawnConfigs, ctx.abortSignal);
+
+            const statusByCanonicalTaskId = new Map<string, "completed" | "error">();
+            const resultByCanonicalTaskId = new Map<string, { output: string; error?: string; success: boolean; agentId: string }>();
+            for (const result of results) {
+              const canonicalTaskId = taskIdentity?.resolveCanonicalTaskId("subagent_id", result.agentId);
+              if (!canonicalTaskId) {
+                continue;
+              }
+              statusByCanonicalTaskId.set(canonicalTaskId, result.success ? "completed" : "error");
+              resultByCanonicalTaskId.set(canonicalTaskId, {
+                output: result.output,
+                error: result.error,
+                success: result.success,
+                agentId: result.agentId,
+              });
+            }
+
+            // Map results back independently — each result corresponds to the
+            // matched ready task index from the precomputed map.
+            const updatedTasks = identityBoundTasks.map((task, taskIndex) => {
+              if (taskIdentity) {
+                const runtimeTask = toRuntimeTask(task, `${ctx.state.executionId}-${ctx.state.iteration}-${taskIndex}`);
+                const canonicalTaskId = runtimeTask.identity?.canonicalId ?? runtimeTask.id;
+                const nextStatus = statusByCanonicalTaskId.get(canonicalTaskId);
+                const mappedResult = resultByCanonicalTaskId.get(canonicalTaskId);
+                if (nextStatus) {
+                  const taskResult = mappedResult
+                    ? buildTaskResultEnvelope({
+                      task: runtimeTask,
+                      result: mappedResult,
+                      sessionId: ctx.state.executionId,
+                    })
+                    : runtimeTask.taskResult;
+                  return applyRuntimeTask(task, {
+                    ...runtimeTask,
+                    status: nextStatus,
+                    taskResult,
+                  });
+                }
+              }
+
+              const sourceTask = ctx.state.tasks[taskIndex];
+              if (!sourceTask) return task;
+              const readyIndex = readyIndexByTask.get(sourceTask);
+              if (readyIndex === undefined) return task;
+              const result = results[readyIndex];
+              if (!result) {
+                return task;
+              }
+
+              const runtimeTask = toRuntimeTask(task, `${ctx.state.executionId}-${ctx.state.iteration}-${taskIndex}`);
+              const terminalStatus = result.success ? "completed" : "error";
+              const taskResult = buildTaskResultEnvelope({
+                task: runtimeTask,
+                result,
+                sessionId: ctx.state.executionId,
+              });
+
+              return applyRuntimeTask(task, {
+                ...runtimeTask,
+                status: terminalStatus,
+                taskResult,
+              });
+            });
+
+            return {
+              stateUpdate: {
+                iteration: ctx.state.iteration + 1,
+                tasks: updatedTasks,
+              } as Partial<RalphWorkflowState>,
+            };
+          },
+        } satisfies NodeDefinition<RalphWorkflowState>,
+      ],
+      {
+        until: (state) =>
+          (state.tasks.length > 0 && state.tasks.every((t) => t.status === "completed" || t.status === "error")) ||
+          state.iteration >= state.maxIterations ||
+          (state.tasks.length > 0 && !hasActionableTasks(state.tasks)),
+        maxIterations: 100,
+      }
+    )
+
+    // Phase 3: Review & Fix
+    .subagent({
+      id: "reviewer",
+      agent: "reviewer",
+      task: (state) =>
+        buildReviewPrompt(
+          state.tasks,
+          state.yoloPrompt ?? "",
+          `${state.ralphSessionDir}/progress.txt`
+        ),
+      outputMapper: (result, _state) => ({
+        reviewResult: parseReviewResult(result.output ?? "") ?? {
+          findings: [],
+          overall_correctness: "patch is correct",
+          overall_explanation: "No review output available",
+        },
+      }),
+      name: "Reviewer",
+      description: "Reviews completed work",
+    })
+    // oxlint-disable-next-line unicorn/no-thenable -- `then` is part of the IfConfig API
+    .if({
+      condition: (state) =>
+        state.reviewResult !== null &&
+        state.reviewResult.findings.length > 0,
+      then: [
+        toolNode<RalphWorkflowState, { findings: NonNullable<RalphWorkflowState["reviewResult"]>["findings"] }, TaskItem[]>({
+          id: "prepare-fix-tasks",
+          toolName: "prepare-fix-tasks",
+          execute: async (args) => buildReviewFixTasks(args.findings),
+          args: (state) => ({ findings: state.reviewResult?.findings ?? [] }),
+          outputMapper: (fixTasks) => ({
+            tasks: fixTasks,
+            currentTasks: fixTasks,
+          }),
+          name: "Fix Task Planner",
+          description: "Converts review findings into actionable fix tasks",
+        }),
+        {
+          id: "fixer",
+          type: "agent",
+          name: "Fixer",
+          description: "Applies review fixes",
+          retry: { maxAttempts: 1, backoffMs: 0, backoffMultiplier: 1 },
+          async execute(ctx: ExecutionContext<RalphWorkflowState>): Promise<NodeResult<RalphWorkflowState>> {
+            const spawnSubagent = ctx.config.runtime?.spawnSubagent;
+            if (!spawnSubagent) {
+              throw new Error("spawnSubagent not available in runtime config");
+            }
+            const taskIdentity = ctx.config.runtime?.taskIdentity;
+
+            const review = ctx.state.reviewResult;
+            if (!review) {
+              return {
+                stateUpdate: {
+                  fixesApplied: false,
+                } as Partial<RalphWorkflowState>,
+              };
+            }
+
+            const fixSpec = buildFixSpecFromReview(
+              review,
+              ctx.state.tasks,
+              ctx.state.yoloPrompt ?? "",
+            );
+            if (!fixSpec.trim()) {
+              return {
+                stateUpdate: {
+                  fixesApplied: false,
+                } as Partial<RalphWorkflowState>,
+              };
+            }
+
+            const tasksInProgress = ctx.state.tasks.map((task) =>
+              task.status === "pending" ? { ...task, status: "in_progress" } : task,
+            );
+
+            const activeFixTaskIds = tasksInProgress
+              .filter((task) => task.status === "in_progress")
+              .map((task) => task.id)
+              .filter((id): id is string => Boolean(id));
+
+            const notifyFn = (ctx.config.runtime as Record<string, unknown> | undefined)
+              ?.notifyTaskStatusChange as
+              | ((
+                taskIds: string[],
+                newStatus: string,
+                tasks: Array<{ id: string; title: string; status: string; blockedBy?: string[]; identity?: WorkflowRuntimeTask["identity"] }>,
+              ) => void)
+              | undefined;
+            notifyFn?.(
+              activeFixTaskIds,
+              "in_progress",
+              tasksInProgress.map((task, index) => {
+                const runtimeTask = toRuntimeTask(task, `${ctx.state.executionId}-fix-${index}`);
+                return {
+                  id: task.id ?? "",
+                  title: task.content,
+                  status: task.status,
+                  blockedBy: task.blockedBy,
+                  identity: runtimeTask.identity,
+                };
+              }),
+            );
+
+            const fixerAgentId = `fixer-${ctx.state.executionId}`;
+            const identityBoundTasks = taskIdentity
+              ? tasksInProgress.map((task, index) => {
+                if (task.status !== "in_progress") {
+                  return task;
+                }
+
+                const runtimeTask = toRuntimeTask(task, `${ctx.state.executionId}-fix-${index}`);
+                const boundTask = taskIdentity.bindProviderId(runtimeTask, "subagent_id", fixerAgentId);
+                return applyRuntimeTask(task, boundTask);
+              })
+              : tasksInProgress;
+
+            const result = await spawnSubagent({
+              agentId: fixerAgentId,
+              agentName: "debugger",
+              task: fixSpec,
+              abortSignal: ctx.abortSignal,
+            }, ctx.abortSignal);
+
+            const terminalStatus = result.success ? "completed" : "error";
+            const finalizedTasks = identityBoundTasks.map((task, index) => {
+              if (task.status !== "in_progress") {
+                return task;
+              }
+
+              const runtimeTask = toRuntimeTask(task, `${ctx.state.executionId}-fix-${index}`);
+              const taskResult = buildTaskResultEnvelope({
+                task: runtimeTask,
+                result,
+                sessionId: ctx.state.executionId,
+              });
+
+              return applyRuntimeTask(task, {
+                ...runtimeTask,
+                status: terminalStatus,
+                taskResult,
+              });
+            });
+
+            return {
+              stateUpdate: {
+                tasks: finalizedTasks,
+                currentTasks: finalizedTasks,
+                fixesApplied: result.success,
+              } as Partial<RalphWorkflowState>,
+            };
+          },
+        } satisfies NodeDefinition<RalphWorkflowState>,
+      ],
+    })
+    .compile();
+}
diff --git a/src/graph/nodes/ralph.ts b/src/workflows/ralph/prompts.ts
similarity index 52%
rename from src/graph/nodes/ralph.ts
rename to src/workflows/ralph/prompts.ts
index 9fb524c53b..9165fd2e26 100644
--- a/src/graph/nodes/ralph.ts
+++ b/src/workflows/ralph/prompts.ts
@@ -3,7 +3,8 @@
  *
  * Provides the prompts used by the /ralph two-step workflow:
  *   Step 1: Task decomposition (buildSpecToTasksPrompt)
- *   Step 2: Worker sub-agent dispatch (buildBootstrappedTaskContext / buildWorkerAssignment)
+ *   Step 2: Worker sub-agent dispatch (buildWorkerAssignment)
+ *   Step 3: Review & Fix (buildReviewPrompt, buildFixSpecFromReview)
  *
  * The worker agent prompt lives in .claude/agents/worker.md (and equivalent
  * paths for OpenCode / Copilot). It is registered by each SDK at session
@@ -11,17 +12,28 @@
  * the task list as context.
  */
 
+import type {
+    WorkflowRuntimeTaskIdentity,
+    WorkflowRuntimeTaskResultEnvelope,
+} from "../runtime-contracts.ts";
+
 export interface TaskItem {
-  id?: string;
-  content: string;
-  status: string;
-  activeForm: string;
-  blockedBy?: string[];
+    id?: string;
+    content: string;
+    status: string;
+    activeForm: string;
+    blockedBy?: string[];
+    identity?: WorkflowRuntimeTaskIdentity;
+    taskResult?: WorkflowRuntimeTaskResultEnvelope;
 }
 
 function isCompletedStatus(status: string): boolean {
-  const normalized = status.trim().toLowerCase();
-  return normalized === "completed" || normalized === "complete" || normalized === "done";
+    const normalized = status.trim().toLowerCase();
+    return (
+        normalized === "completed" ||
+        normalized === "complete" ||
+        normalized === "done"
+    );
 }
 
 // ============================================================================
@@ -30,7 +42,7 @@ function isCompletedStatus(status: string): boolean {
 
 /** Build the spec-to-tasks prompt for decomposing a spec into TodoItem[] */
 export function buildSpecToTasksPrompt(specContent: string): string {
-  return `You are tasked with decomposing a feature specification into an ordered task list.
+    return `You are tasked with decomposing a feature specification into an ordered task list.
 
 Read the following specification and create a comprehensive and structured JSON array of tasks to be implemented in order of highest to lowest priority.
 
@@ -72,60 +84,49 @@ Produce a JSON array where each element follows this exact schema:
 }
 
 // ============================================================================
-// STEP 2: TASK LIST PREAMBLE
+// STEP 2: WORKER ASSIGNMENT
 // ============================================================================
 
-/** Build a preamble that includes the task list JSON for step 2 after context clearing */
-export function buildTaskListPreamble(tasks: TaskItem[]): string {
-  const taskListJson = JSON.stringify(tasks, null, 2);
-  return `# Task List from Planning Phase
-
-The following task list was created during the planning phase. Your FIRST action MUST be to call the TodoWrite tool with this exact task list to load it into the system.
-
-\`\`\`json
-${taskListJson}
-\`\`\`
-
-After calling TodoWrite with the above tasks, proceed with the implementation instructions below.
-
----
-
-`;
-}
-
 /** Build a prompt for assigning a single task to a worker sub-agent. */
-export function buildWorkerAssignment(task: TaskItem, allTasks: TaskItem[]): string {
-  const taskId = task.id ?? "unknown";
+export function buildWorkerAssignment(
+    task: TaskItem,
+    allTasks: TaskItem[],
+): string {
+    const taskId = task.id ?? "unknown";
 
-  const dependencies = (task.blockedBy ?? []).map((dependencyId) => {
-    const dependency = allTasks.find((candidate) => candidate.id === dependencyId);
-    if (!dependency) {
-      return `- ${dependencyId}: (not found)`;
-    }
-    return `- ${dependencyId}: ${dependency.content}`;
-  });
+    const dependencies = (task.blockedBy ?? []).map((dependencyId) => {
+        const dependency = allTasks.find(
+            (candidate) => candidate.id === dependencyId,
+        );
+        if (!dependency) {
+            return `- ${dependencyId}: (not found)`;
+        }
+        return `- ${dependencyId}: ${dependency.content}`;
+    });
 
-  const completedTasks = allTasks
-    .filter((candidate) => isCompletedStatus(candidate.status))
-    .map((candidate) => `- ${candidate.id ?? "?"}: ${candidate.content}`);
+    const completedTasks = allTasks
+        .filter((candidate) => isCompletedStatus(candidate.status))
+        .map((candidate) => `- ${candidate.id ?? "?"}: ${candidate.content}`);
 
-  const dependencySection = dependencies.length > 0
-    ? `# Dependencies
+    const dependencySection =
+        dependencies.length > 0
+            ? `# Dependencies
 
 ${dependencies.join("\n")}
 
 `
-    : "";
+            : "";
 
-  const completedSection = completedTasks.length > 0
-    ? `# Completed Tasks
+    const completedSection =
+        completedTasks.length > 0
+            ? `# Completed Tasks
 
 ${completedTasks.join("\n")}
 
 `
-    : "";
+            : "";
 
-  return `# Task Assignment
+    return `# Task Assignment
 
 **Task ID:** ${taskId}
 **Task:** ${task.content}
@@ -139,78 +140,42 @@ If blocked, record the issue and set the task status to "error".
 Begin implementation.`;
 }
 
-/** Build a bootstrap context for the main agent after the planning phase. */
-export function buildBootstrappedTaskContext(tasks: TaskItem[], sessionId: string): string {
-  const taskListJson = JSON.stringify(tasks, null, 2);
-  return `# Ralph Session Bootstrap
-
-Session ID: ${sessionId}
-
-The planning phase produced the task list below:
-
-\`\`\`json
-${taskListJson}
-\`\`\`
-
-# Instructions
-
-- Process tasks in dependency order.
-- Respect each task's blockedBy list before starting work.
-- Dispatch workers with explicit task assignments and update TodoWrite as progress changes.
-- Continue until all tasks are completed or an error/deadlock is surfaced.`;
-}
-
-/** Build a prompt to continue processing remaining tasks after a previous iteration. */
-export function buildContinuePrompt(tasks: TaskItem[], sessionId: string): string {
-  const taskListJson = JSON.stringify(tasks, null, 2);
-  const completed = tasks.filter((t) => isCompletedStatus(t.status)).length;
-  const total = tasks.length;
-  return `# Ralph Session Continue
-
-Session ID: ${sessionId}
-Progress: ${completed}/${total} tasks completed
-
-Current task state:
-
-\`\`\`json
-${taskListJson}
-\`\`\`
-
-Some tasks are still incomplete. Continue processing tasks in dependency order. Dispatch workers for ready tasks and update TodoWrite as progress changes. Continue until all tasks are completed or an error/deadlock is surfaced.`;
-}
-
 // ============================================================================
 // STEP 3: REVIEW & FIX
 // ============================================================================
 
 /** Represents a single finding from the code review */
 export interface ReviewFinding {
-  title: string;
-  body: string;
-  confidence_score?: number;
-  priority?: number;
-  code_location?: {
-    absolute_file_path: string;
-    line_range: { start: number; end: number };
-  };
+    title: string;
+    body: string;
+    confidence_score?: number;
+    priority?: number;
+    code_location?: {
+        absolute_file_path: string;
+        line_range: { start: number; end: number };
+    };
 }
 
 /** Represents the complete review result from the reviewer sub-agent */
 export interface ReviewResult {
-  findings: ReviewFinding[];
-  overall_correctness: string;
-  overall_explanation: string;
-  overall_confidence_score?: number;
+    findings: ReviewFinding[];
+    overall_correctness: string;
+    overall_explanation: string;
+    overall_confidence_score?: number;
 }
 
 /** Build a prompt for the reviewer sub-agent to review completed implementation */
-export function buildReviewPrompt(tasks: TaskItem[], userPrompt: string): string {
-  const completedTasks = tasks
-    .filter((t) => isCompletedStatus(t.status))
-    .map((t) => `- ${t.id ?? "?"}: ${t.content}`)
-    .join("\n");
+export function buildReviewPrompt(
+    tasks: TaskItem[],
+    userPrompt: string,
+    progressFilePath: string,
+): string {
+    const completedTasks = tasks
+        .filter((t) => isCompletedStatus(t.status))
+        .map((t) => `- ${t.id ?? "?"}: ${t.content}`)
+        .join("\n");
 
-  return `# Code Review Request
+    return `# Code Review Request
 
 ## Implementation Summary
 
@@ -228,7 +193,7 @@ ${completedTasks}
 
 ## Review Instructions
 
-Your task is to conduct a thorough code review of the changes made during this implementation. Use \`git diff\` to examine the actual code changes that were made.
+Your task is to conduct a thorough code review of the changes made during this implementation. Analyze the progress file in ${progressFilePath} to understand the changes that were made.
 
 ### Review Focus Areas
 
@@ -288,82 +253,23 @@ Produce your review findings in the following JSON format:
 Begin your review now.`;
 }
 
-/** Parse the reviewer's JSON output, handling various formats */
-export function parseReviewResult(content: string): ReviewResult | null {
-  try {
-    // First try: direct JSON parsing
-    const parsed = JSON.parse(content);
-    if (parsed.findings && parsed.overall_correctness) {
-      // Filter out low-priority findings (P3)
-      const actionableFindings = (parsed.findings as ReviewFinding[]).filter(
-        (f) => f.priority === undefined || f.priority <= 2
-      );
-      return {
-        ...parsed,
-        findings: actionableFindings,
-      };
-    }
-  } catch {
-    // Continue to next attempt
-  }
-
-  try {
-    // Second try: extract from markdown code fence
-    const codeBlockMatch = content.match(/```(?:json)?\s*\n([\s\S]*?)\n```/);
-    if (codeBlockMatch?.[1]) {
-      const parsed = JSON.parse(codeBlockMatch[1]);
-      if (parsed.findings && parsed.overall_correctness) {
-        const actionableFindings = (parsed.findings as ReviewFinding[]).filter(
-          (f) => f.priority === undefined || f.priority <= 2
-        );
-        return {
-          ...parsed,
-          findings: actionableFindings,
-        };
-      }
-    }
-  } catch {
-    // Continue to next attempt
-  }
-
-  try {
-    // Third try: extract JSON object from surrounding prose
-    const jsonObjectMatch = content.match(/\{[\s\S]*"findings"[\s\S]*\}/);
-    if (jsonObjectMatch) {
-      const parsed = JSON.parse(jsonObjectMatch[0]);
-      if (parsed.findings && parsed.overall_correctness) {
-        const actionableFindings = (parsed.findings as ReviewFinding[]).filter(
-          (f) => f.priority === undefined || f.priority <= 2
-        );
-        return {
-          ...parsed,
-          findings: actionableFindings,
-        };
-      }
-    }
-  } catch {
-    // All attempts failed
-  }
-
-  return null;
-}
-
 /** Build a fix specification document from review findings */
 export function buildFixSpecFromReview(
-  review: ReviewResult,
-  tasks: TaskItem[],
-  userPrompt: string
+    review: ReviewResult,
+    tasks: TaskItem[],
+    userPrompt: string,
 ): string {
-  // If no actionable findings or patch is correct, return empty string
-  if (
-    review.findings.length === 0 ||
-    (review.overall_correctness === "patch is correct" && review.findings.length === 0)
-  ) {
-    return "";
-  }
+    // If no actionable findings or patch is correct, return empty string
+    if (
+        review.findings.length === 0 ||
+        (review.overall_correctness === "patch is correct" &&
+            review.findings.length === 0)
+    ) {
+        return "";
+    }
 
-  // Build the fix specification
-  let fixSpec = `# Review Fix Specification
+    // Build the fix specification
+    let fixSpec = `# Review Fix Specification
 
 ## Original Implementation
 
@@ -379,21 +285,22 @@ ${review.overall_explanation}
 
 `;
 
-  // Sort findings by priority (P0 first, then P1, then P2)
-  const sortedFindings = [...review.findings].sort((a, b) => {
-    const priorityA = a.priority ?? 3;
-    const priorityB = b.priority ?? 3;
-    return priorityA - priorityB;
-  });
+    // Sort findings by priority (P0 first, then P1, then P2)
+    const sortedFindings = [...review.findings].sort((a, b) => {
+        const priorityA = a.priority ?? 3;
+        const priorityB = b.priority ?? 3;
+        return priorityA - priorityB;
+    });
 
-  // Add each finding as a section
-  sortedFindings.forEach((finding, index) => {
-    const priorityLabel = finding.priority !== undefined ? `P${finding.priority}` : "P2";
-    const location = finding.code_location
-      ? `${finding.code_location.absolute_file_path}:${finding.code_location.line_range.start}-${finding.code_location.line_range.end}`
-      : "Location not specified";
+    // Add each finding as a section
+    sortedFindings.forEach((finding, index) => {
+        const priorityLabel =
+            finding.priority !== undefined ? `P${finding.priority}` : "P2";
+        const location = finding.code_location
+            ? `${finding.code_location.absolute_file_path}:${finding.code_location.line_range.start}-${finding.code_location.line_range.end}`
+            : "Location not specified";
 
-    fixSpec += `### Finding ${index + 1}: ${finding.title}
+        fixSpec += `### Finding ${index + 1}: ${finding.title}
 
 - **Priority:** ${priorityLabel}
 - **Location:** ${location}
@@ -401,10 +308,10 @@ ${review.overall_explanation}
 - **Rubric:** The fix is complete when the issue described above is resolved, the code correctly handles this case, and existing tests continue to pass.
 
 `;
-  });
+    });
 
-  // Add fix guidelines
-  fixSpec += `## Fix Guidelines
+    // Add fix guidelines
+    fixSpec += `## Fix Guidelines
 
 - Address each finding in priority order (P0 first, then P1, then P2).
 - Run existing tests after each fix to verify no regressions.
@@ -412,5 +319,71 @@ ${review.overall_explanation}
 - If a finding cannot be addressed, document why and mark the task as blocked.
 `;
 
-  return fixSpec;
+    return fixSpec;
+}
+
+// ============================================================================
+// REVIEW RESULT PARSING
+// ============================================================================
+
+/** Parse the reviewer's JSON output, handling various formats */
+export function parseReviewResult(content: string): ReviewResult | null {
+    try {
+        // First try: direct JSON parsing
+        const parsed = JSON.parse(content);
+        if (parsed.findings && parsed.overall_correctness) {
+            // Filter out low-priority findings (P3)
+            const actionableFindings = (
+                parsed.findings as ReviewFinding[]
+            ).filter((f) => f.priority === undefined || f.priority <= 2);
+            return {
+                ...parsed,
+                findings: actionableFindings,
+            };
+        }
+    } catch {
+        // Continue to next attempt
+    }
+
+    try {
+        // Second try: extract from markdown code fence
+        const codeBlockMatch = content.match(
+            /```(?:json)?\s*\n([\s\S]*?)\n```/,
+        );
+        if (codeBlockMatch?.[1]) {
+            const parsed = JSON.parse(codeBlockMatch[1]);
+            if (parsed.findings && parsed.overall_correctness) {
+                const actionableFindings = (
+                    parsed.findings as ReviewFinding[]
+                ).filter((f) => f.priority === undefined || f.priority <= 2);
+                return {
+                    ...parsed,
+                    findings: actionableFindings,
+                };
+            }
+        }
+    } catch {
+        // Continue to next attempt
+    }
+
+    try {
+        // Third try: extract JSON object from surrounding prose
+        const jsonObjectMatch = content.match(/\{[\s\S]*"findings"[\s\S]*\}/);
+        if (jsonObjectMatch) {
+            const parsed = JSON.parse(jsonObjectMatch[0]);
+            if (parsed.findings && parsed.overall_correctness) {
+                const actionableFindings = (
+                    parsed.findings as ReviewFinding[]
+                ).filter((f) => f.priority === undefined || f.priority <= 2);
+                return {
+                    ...parsed,
+                    findings: actionableFindings,
+                };
+            }
+        }
+    } catch {
+        // All attempts failed
+    }
+
+    return null;
 }
diff --git a/src/workflows/ralph/state.ts b/src/workflows/ralph/state.ts
new file mode 100644
index 0000000000..1c7b0a177f
--- /dev/null
+++ b/src/workflows/ralph/state.ts
@@ -0,0 +1,209 @@
+import { join } from "path";
+import { homedir } from "os";
+
+import { applyStateUpdate, initializeState } from "../graph/annotation.ts";
+import type { Annotation, Feature, Reducer } from "../graph/annotation.ts";
+import type { ContextWindowUsage, DebugReport, NodeId } from "../graph/types.ts";
+import type { TaskItem, ReviewResult } from "./prompts.ts";
+
+function annotation<T>(defaultValue: T | (() => T), reducer?: Reducer<T>): Annotation<T> {
+  return {
+    default: defaultValue,
+    reducer,
+  };
+}
+
+function concatReducer<T>(current: T[], update: T[]): T[] {
+  const currentArray = Array.isArray(current) ? current : [];
+  const updateArray = Array.isArray(update) ? update : [];
+  return [...currentArray, ...updateArray];
+}
+
+function mergeByIdReducer<T extends object>(idField: keyof T): Reducer<T[]> {
+  return (current: T[], update: T[]): T[] => {
+    const currentArray = Array.isArray(current) ? current : [];
+    const updateArray = Array.isArray(update) ? update : [];
+    const idMap = new Map<unknown, T>();
+
+    for (const item of currentArray) {
+      const id = item[idField];
+      if (id !== undefined) {
+        idMap.set(id, item);
+      }
+    }
+
+    for (const item of updateArray) {
+      const id = item[idField];
+      if (id !== undefined) {
+        const existing = idMap.get(id);
+        if (existing) {
+          idMap.set(id, { ...existing, ...item });
+        } else {
+          idMap.set(id, item);
+        }
+      }
+    }
+
+    return Array.from(idMap.values());
+  };
+}
+
+export interface RalphWorkflowState {
+  executionId: string;
+  lastUpdated: string;
+  outputs: Record<NodeId, unknown>;
+  researchDoc: string;
+  specDoc: string;
+  specApproved: boolean;
+  tasks: TaskItem[];
+  currentTasks: TaskItem[];
+  reviewResult: ReviewResult | null;
+  fixesApplied: boolean;
+  featureList: Feature[];
+  currentFeature: Feature | null;
+  allFeaturesPassing: boolean;
+  contextWindowUsage: ContextWindowUsage | null;
+  iteration: number;
+  prUrl: string | null;
+  debugReports: DebugReport[];
+  ralphSessionId: string;
+  ralphSessionDir: string;
+  yolo: boolean;
+  yoloPrompt: string | null;
+  yoloComplete: boolean;
+  maxIterations: number;
+  shouldContinue: boolean;
+  prBranch: string | undefined;
+  completedFeatures: string[];
+  sourceFeatureListPath: string | undefined;
+  maxIterationsReached: boolean | undefined;
+}
+
+export const RalphStateAnnotation = {
+  executionId: annotation<string>(""),
+  lastUpdated: annotation<string>(() => new Date().toISOString()),
+  outputs: annotation<Record<NodeId, unknown>>({}),
+
+  researchDoc: annotation<string>(""),
+  specDoc: annotation<string>(""),
+  specApproved: annotation<boolean>(false),
+
+  tasks: annotation<TaskItem[]>([], mergeByIdReducer<TaskItem>("id")),
+  currentTasks: annotation<TaskItem[]>([], (current: TaskItem[], update: TaskItem[]) => update),
+  reviewResult: annotation<ReviewResult | null>(null),
+  fixesApplied: annotation<boolean>(false),
+
+  featureList: annotation<Feature[]>([], mergeByIdReducer<Feature>("description")),
+  currentFeature: annotation<Feature | null>(null),
+  allFeaturesPassing: annotation<boolean>(false),
+
+  debugReports: annotation<DebugReport[]>([], concatReducer),
+
+  prUrl: annotation<string | null>(null),
+  prBranch: annotation<string | undefined>(undefined),
+
+  contextWindowUsage: annotation<ContextWindowUsage | null>(null),
+
+  iteration: annotation<number>(1),
+
+  ralphSessionId: annotation<string>(""),
+  ralphSessionDir: annotation<string>(""),
+  yolo: annotation<boolean>(false),
+  yoloPrompt: annotation<string | null>(null),
+  yoloComplete: annotation<boolean>(false),
+  maxIterations: annotation<number>(100),
+  shouldContinue: annotation<boolean>(true),
+  completedFeatures: annotation<string[]>([], concatReducer),
+  sourceFeatureListPath: annotation<string | undefined>(undefined),
+  maxIterationsReached: annotation<boolean | undefined>(undefined),
+};
+
+/**
+ * Create a new Ralph workflow state with default values.
+ *
+ * @param executionId - Unique ID for this execution (auto-generated if not provided)
+ * @param options - Optional initial values for Ralph-specific fields
+ * @returns Initialized RalphWorkflowState
+ */
+export function createRalphState(
+  executionId?: string,
+  options?: Partial<RalphWorkflowState>
+): RalphWorkflowState {
+  const state = initializeState(RalphStateAnnotation);
+  const ralphSessionId = options?.ralphSessionId ?? crypto.randomUUID();
+
+  return {
+    ...state,
+    executionId: executionId ?? crypto.randomUUID(),
+    lastUpdated: new Date().toISOString(),
+    tasks: options?.tasks ?? [],
+    currentTasks: options?.currentTasks ?? [],
+    reviewResult: options?.reviewResult ?? null,
+    fixesApplied: options?.fixesApplied ?? false,
+    ralphSessionId,
+    ralphSessionDir: options?.ralphSessionDir ?? `${join(homedir(), ".atomic", "workflows", "sessions", ralphSessionId)}`,
+    yolo: options?.yolo ?? false,
+    yoloPrompt: options?.yoloPrompt ?? null,
+    yoloComplete: options?.yoloComplete ?? false,
+    maxIterations: options?.maxIterations ?? 100,
+    shouldContinue: options?.shouldContinue ?? true,
+    completedFeatures: options?.completedFeatures ?? [],
+    sourceFeatureListPath: options?.sourceFeatureListPath,
+    maxIterationsReached: options?.maxIterationsReached,
+    prBranch: options?.prBranch,
+    ...options,
+  };
+}
+
+/**
+ * Apply an update to a Ralph workflow state.
+ *
+ * @param current - Current state
+ * @param update - Partial update to apply
+ * @returns New state with updates applied
+ */
+export function updateRalphState(
+  current: RalphWorkflowState,
+  update: Partial<RalphWorkflowState>
+): RalphWorkflowState {
+  const newState = applyStateUpdate(RalphStateAnnotation, current, update);
+  return {
+    ...newState,
+    lastUpdated: new Date().toISOString(),
+  };
+}
+
+/**
+ * Type guard to check if a value is a valid RalphWorkflowState.
+ */
+export function isRalphWorkflowState(value: unknown): value is RalphWorkflowState {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const obj = value as Record<string, unknown>;
+  return (
+    // Base state fields
+    typeof obj.executionId === "string" &&
+    typeof obj.lastUpdated === "string" &&
+    typeof obj.outputs === "object" &&
+    obj.outputs !== null &&
+    // Atomic workflow fields
+    typeof obj.researchDoc === "string" &&
+    typeof obj.specDoc === "string" &&
+    typeof obj.specApproved === "boolean" &&
+    Array.isArray(obj.tasks) &&
+    Array.isArray(obj.currentTasks) &&
+    typeof obj.fixesApplied === "boolean" &&
+    Array.isArray(obj.featureList) &&
+    typeof obj.allFeaturesPassing === "boolean" &&
+    Array.isArray(obj.debugReports) &&
+    typeof obj.iteration === "number" &&
+    // Ralph-specific fields
+    typeof obj.ralphSessionId === "string" &&
+    typeof obj.ralphSessionDir === "string" &&
+    typeof obj.yolo === "boolean" &&
+    typeof obj.maxIterations === "number" &&
+    typeof obj.shouldContinue === "boolean" &&
+    Array.isArray(obj.completedFeatures)
+  );
+}
diff --git a/src/workflows/runtime-contracts.test.ts b/src/workflows/runtime-contracts.test.ts
new file mode 100644
index 0000000000..713e39bbb4
--- /dev/null
+++ b/src/workflows/runtime-contracts.test.ts
@@ -0,0 +1,210 @@
+import { describe, expect, test } from "bun:test";
+import {
+  DEFAULT_WORKFLOW_RUNTIME_FEATURE_FLAGS,
+  normalizeWorkflowRuntimeTaskStatus,
+  resolveWorkflowRuntimeFeatureFlags,
+  toWorkflowRuntimeTask,
+  workflowRuntimeStrictTaskSchema,
+} from "./runtime-contracts.ts";
+import {
+  getRuntimeParityMetricsSnapshot,
+  resetRuntimeParityMetrics,
+} from "./runtime-parity-observability.ts";
+
+describe("runtime-contracts", () => {
+  test("emits parity metrics when normalizing runtime tasks", () => {
+    resetRuntimeParityMetrics();
+    toWorkflowRuntimeTask(
+      {
+        id: "#m1",
+        title: "Metrics",
+        status: "completed",
+      },
+      () => "fallback-id",
+    );
+
+    const metrics = getRuntimeParityMetricsSnapshot();
+    expect(metrics.counters["workflow.runtime.parity.task_normalized_total{path=schema_parse}"]).toBe(1);
+    expect(metrics.histograms["workflow.runtime.parity.task_blocked_by_count{path=schema_parse}"]).toEqual([0]);
+  });
+
+  test("normalizes task status aliases", () => {
+    expect(normalizeWorkflowRuntimeTaskStatus("done")).toBe("completed");
+    expect(normalizeWorkflowRuntimeTaskStatus("in progress")).toBe("in_progress");
+    expect(normalizeWorkflowRuntimeTaskStatus("failure")).toBe("failed");
+    expect(normalizeWorkflowRuntimeTaskStatus("unexpected-value")).toBe("pending");
+  });
+
+  test("normalizes task objects into canonical runtime task shape", () => {
+    const task = toWorkflowRuntimeTask(
+      {
+        content: "Implement contract",
+        status: "done",
+        blockedBy: ["#1", "", null],
+      },
+      () => "generated-id",
+    );
+
+    expect(task).toEqual({
+      id: "generated-id",
+      title: "Implement contract",
+      status: "completed",
+      blockedBy: ["#1"],
+      error: undefined,
+      identity: {
+        canonicalId: "generated-id",
+        providerBindings: undefined,
+      },
+      taskResult: undefined,
+    });
+  });
+
+  test("normalizes task result envelopes on runtime tasks", () => {
+    const task = toWorkflowRuntimeTask(
+      {
+        id: "#4",
+        title: "Ship formatter",
+        status: "completed",
+        identity: {
+          canonicalId: "#4",
+          providerBindings: {
+            subagent_id: ["worker-4"],
+          },
+        },
+        taskResult: {
+          task_id: "#4",
+          tool_name: "task",
+          title: "Ship formatter",
+          metadata: {
+            sessionId: "session-1",
+            providerBindings: {
+              subagent_id: "worker-4",
+            },
+          },
+          status: "completed",
+          output_text: "done",
+          envelope_text: "task_id: #4",
+        },
+      },
+      () => "fallback-id",
+    );
+
+    expect(task.taskResult).toEqual({
+      task_id: "#4",
+      tool_name: "task",
+      title: "Ship formatter",
+      metadata: {
+        sessionId: "session-1",
+        providerBindings: {
+          subagent_id: "worker-4",
+        },
+      },
+      status: "completed",
+      output_text: "done",
+      envelope_text: "task_id: #4",
+    });
+
+    const metrics = getRuntimeParityMetricsSnapshot();
+    expect(metrics.counters["workflow.runtime.parity.task_result_normalized_total{status=completed}"]).toBe(1);
+    expect(metrics.gauges["workflow.runtime.parity.task_result_provider_bindings{taskId=#4}"]).toBe(1);
+  });
+
+  test("fails fast on task result envelope identity mismatch", () => {
+    resetRuntimeParityMetrics();
+
+    expect(() => toWorkflowRuntimeTask(
+      {
+        id: "#4",
+        title: "Mismatched envelope",
+        status: "completed",
+        identity: {
+          canonicalId: "#4",
+          providerBindings: {
+            subagent_id: ["worker-4"],
+          },
+        },
+        taskResult: {
+          task_id: "#4",
+          tool_name: "task",
+          title: "Mismatched envelope",
+          metadata: {
+            providerBindings: {
+              subagent_id: "other-worker",
+            },
+          },
+          status: "completed",
+          output_text: "done",
+        },
+      },
+      () => "fallback-id",
+    )).toThrow("provider binding mismatch");
+
+    const metrics = getRuntimeParityMetricsSnapshot();
+    expect(metrics.counters["workflow.runtime.parity.task_result_invariant_failures_total{provider=subagent_id,reason=provider_binding_mismatch}"]).toBe(1);
+    expect(metrics.counters["workflow.runtime.parity.task_result_normalization_failures_total{reason=invalid_envelope}"]).toBe(1);
+  });
+
+  test("fails fast on task_result task_id mismatch", () => {
+    resetRuntimeParityMetrics();
+
+    expect(() =>
+      toWorkflowRuntimeTask(
+        {
+          id: "#4",
+          title: "Mismatched task id",
+          status: "completed",
+          identity: {
+            canonicalId: "#4",
+          },
+          taskResult: {
+            task_id: "#5",
+            tool_name: "task",
+            title: "Mismatched task id",
+            status: "completed",
+            output_text: "done",
+          },
+        },
+        () => "fallback-id",
+      )).toThrow("task_id mismatch");
+
+    const metrics = getRuntimeParityMetricsSnapshot();
+    expect(metrics.counters["workflow.runtime.parity.task_result_invariant_failures_total{reason=task_id_mismatch}"]).toBe(1);
+    expect(metrics.counters["workflow.runtime.parity.task_result_normalization_failures_total{reason=invalid_envelope}"]).toBe(1);
+  });
+
+  test("strict schema accepts canonical statuses only", () => {
+    expect(() =>
+      workflowRuntimeStrictTaskSchema.parse({
+        id: "task-1",
+        title: "Implement",
+        status: "completed",
+      }),
+    ).not.toThrow();
+
+    expect(() =>
+      workflowRuntimeStrictTaskSchema.parse({
+        id: "task-2",
+        title: "Implement",
+        status: "not_a_status",
+      }),
+    ).toThrow();
+  });
+
+  test("feature flag resolver merges overrides in order", () => {
+    const resolved = resolveWorkflowRuntimeFeatureFlags(
+      { emitTaskStatusEvents: false },
+      { strictTaskContract: true },
+    );
+
+    expect(resolved).toEqual({
+      ...DEFAULT_WORKFLOW_RUNTIME_FEATURE_FLAGS,
+      emitTaskStatusEvents: false,
+      strictTaskContract: true,
+    });
+  });
+
+  test("enables strict task contract by default", () => {
+    const resolved = resolveWorkflowRuntimeFeatureFlags();
+    expect(resolved.strictTaskContract).toBe(true);
+  });
+});
diff --git a/src/workflows/runtime-contracts.ts b/src/workflows/runtime-contracts.ts
new file mode 100644
index 0000000000..1ccf3265a3
--- /dev/null
+++ b/src/workflows/runtime-contracts.ts
@@ -0,0 +1,416 @@
+import { z } from "zod";
+import {
+  incrementRuntimeParityCounter,
+  observeRuntimeParityHistogram,
+  runtimeParityDebug,
+  setRuntimeParityGauge,
+} from "./runtime-parity-observability.ts";
+
+const WORKFLOW_RUNTIME_TASK_STATUS_VALUES = [
+  "pending",
+  "in_progress",
+  "completed",
+  "failed",
+  "blocked",
+  "error",
+] as const;
+
+export type WorkflowRuntimeTaskStatus = (typeof WORKFLOW_RUNTIME_TASK_STATUS_VALUES)[number];
+
+const WORKFLOW_RUNTIME_TASK_STATUS_ALIASES: Record<string, WorkflowRuntimeTaskStatus> = {
+  pending: "pending",
+  todo: "pending",
+  open: "pending",
+  in_progress: "in_progress",
+  inprogress: "in_progress",
+  running: "in_progress",
+  doing: "in_progress",
+  complete: "completed",
+  completed: "completed",
+  done: "completed",
+  success: "completed",
+  failed: "failed",
+  failure: "failed",
+  blocked: "blocked",
+  error: "error",
+  errored: "error",
+};
+
+export const workflowRuntimeTaskStatusSchema = z.enum(WORKFLOW_RUNTIME_TASK_STATUS_VALUES);
+
+const workflowRuntimeLooseTaskStatusSchema = z.string().min(1);
+
+const workflowRuntimeTaskIdentitySchema = z.object({
+  canonicalId: z.string().min(1).optional(),
+  providerBindings: z.record(z.string(), z.array(z.string())).optional(),
+});
+
+export type WorkflowRuntimeTaskIdentity = z.infer<typeof workflowRuntimeTaskIdentitySchema>;
+
+const workflowRuntimeTaskResultEnvelopeSchema = z.object({
+  task_id: z.string().min(1),
+  tool_name: z.string().min(1),
+  title: z.string(),
+  metadata: z.object({
+    sessionId: z.string().min(1).optional(),
+    providerBindings: z.record(z.string(), z.string()).optional(),
+  }).optional(),
+  status: z.enum(["completed", "error"]),
+  output_text: z.string(),
+  output_structured: z.record(z.string(), z.unknown()).optional(),
+  error: z.string().optional(),
+  envelope_text: z.string().optional(),
+});
+
+export type WorkflowRuntimeTaskResultEnvelope = z.infer<typeof workflowRuntimeTaskResultEnvelopeSchema>;
+
+const workflowRuntimeTaskBaseSchema = z.object({
+  id: z.string().min(1),
+  title: z.string(),
+  status: workflowRuntimeLooseTaskStatusSchema,
+  blockedBy: z.array(z.string()).optional(),
+  error: z.string().optional(),
+  identity: workflowRuntimeTaskIdentitySchema.optional(),
+  taskResult: workflowRuntimeTaskResultEnvelopeSchema.optional(),
+});
+
+export const workflowRuntimeTaskSchema = workflowRuntimeTaskBaseSchema;
+
+export const workflowRuntimeStrictTaskSchema = workflowRuntimeTaskBaseSchema.extend({
+  status: workflowRuntimeTaskStatusSchema,
+});
+
+export type WorkflowRuntimeTask = z.infer<typeof workflowRuntimeTaskSchema>;
+
+export const workflowRuntimeStateTaskSchema = z.object({
+  id: z.string().min(1).optional(),
+  content: z.string(),
+  status: workflowRuntimeLooseTaskStatusSchema,
+  activeForm: z.string(),
+  blockedBy: z.array(z.string()).optional(),
+  error: z.string().optional(),
+});
+
+export type WorkflowRuntimeStateTask = z.infer<typeof workflowRuntimeStateTaskSchema>;
+
+export const workflowRuntimeTaskStatusChangeSchema = z.object({
+  taskIds: z.array(z.string()),
+  newStatus: workflowRuntimeLooseTaskStatusSchema,
+  tasks: z.array(workflowRuntimeTaskSchema),
+});
+
+export type WorkflowRuntimeTaskStatusChangePayload = z.infer<typeof workflowRuntimeTaskStatusChangeSchema>;
+
+export interface WorkflowRuntimeTaskIdentityRuntime {
+  backfillTask(task: WorkflowRuntimeTask): WorkflowRuntimeTask;
+  backfillTasks(tasks: WorkflowRuntimeTask[]): WorkflowRuntimeTask[];
+  bindProviderId(task: WorkflowRuntimeTask, provider: string, providerId: string): WorkflowRuntimeTask;
+  resolveCanonicalTaskId(provider: string, providerId: string): string | null;
+}
+
+export interface WorkflowRuntimeFeatureFlags {
+  emitTaskStatusEvents: boolean;
+  persistTaskStatusEvents: boolean;
+  strictTaskContract: boolean;
+}
+
+export type WorkflowRuntimeFeatureFlagOverrides = Partial<WorkflowRuntimeFeatureFlags>;
+
+export const DEFAULT_WORKFLOW_RUNTIME_FEATURE_FLAGS: WorkflowRuntimeFeatureFlags = {
+  emitTaskStatusEvents: true,
+  persistTaskStatusEvents: true,
+  strictTaskContract: true,
+};
+
+export function normalizeWorkflowRuntimeTaskStatus(status: unknown): WorkflowRuntimeTaskStatus {
+  if (typeof status !== "string") {
+    return "pending";
+  }
+
+  const normalized = status.trim().toLowerCase().replace(/[\s-]+/g, "_");
+  return WORKFLOW_RUNTIME_TASK_STATUS_ALIASES[normalized] ?? "pending";
+}
+
+function normalizeBlockedBy(value: unknown): string[] | undefined {
+  if (!Array.isArray(value)) {
+    return undefined;
+  }
+
+  const normalized = value
+    .filter((item) => item !== null && item !== undefined)
+    .map((item) => String(item).trim())
+    .filter((item) => item.length > 0);
+
+  return normalized.length > 0 ? normalized : undefined;
+}
+
+function asRecord(input: unknown): Record<string, unknown> {
+  return typeof input === "object" && input !== null
+    ? input as Record<string, unknown>
+    : {};
+}
+
+function normalizeProviderBindings(value: unknown): Record<string, string[]> | undefined {
+  if (typeof value !== "object" || value === null) {
+    return undefined;
+  }
+
+  const record = value as Record<string, unknown>;
+  const normalized: Record<string, string[]> = {};
+
+  for (const [provider, ids] of Object.entries(record)) {
+    const providerKey = provider.trim();
+    if (providerKey.length === 0 || !Array.isArray(ids)) {
+      continue;
+    }
+
+    const deduped = Array.from(new Set(
+      ids
+        .filter((id) => id !== null && id !== undefined)
+        .map((id) => String(id).trim())
+        .filter((id) => id.length > 0),
+    ));
+
+    if (deduped.length > 0) {
+      normalized[providerKey] = deduped;
+    }
+  }
+
+  return Object.keys(normalized).length > 0 ? normalized : undefined;
+}
+
+function normalizeTaskIdentity(value: unknown, fallbackCanonicalId: string): WorkflowRuntimeTaskIdentity {
+  const record = asRecord(value);
+  const canonicalId = typeof record.canonicalId === "string" && record.canonicalId.trim().length > 0
+    ? record.canonicalId
+    : fallbackCanonicalId;
+
+  return {
+    canonicalId,
+    providerBindings: normalizeProviderBindings(record.providerBindings),
+  };
+}
+
+function normalizeTaskResultEnvelope(
+  value: unknown,
+  fallbackTaskId: string,
+  fallbackTitle: string,
+  identity?: WorkflowRuntimeTaskIdentity,
+): WorkflowRuntimeTaskResultEnvelope | undefined {
+  if (typeof value !== "object" || value === null) {
+    return undefined;
+  }
+
+  const record = value as Record<string, unknown>;
+  const taskId = typeof record.task_id === "string" && record.task_id.trim().length > 0
+    ? record.task_id
+    : fallbackTaskId;
+  const toolName = typeof record.tool_name === "string" && record.tool_name.trim().length > 0
+    ? record.tool_name
+    : "task";
+  const title = typeof record.title === "string"
+    ? record.title
+    : fallbackTitle;
+  const status = record.status === "error" ? "error" : "completed";
+  const outputText = typeof record.output_text === "string"
+    ? record.output_text
+    : "";
+
+  let metadata: WorkflowRuntimeTaskResultEnvelope["metadata"];
+  if (typeof record.metadata === "object" && record.metadata !== null) {
+    const rawMetadata = record.metadata as Record<string, unknown>;
+    let providerBindings: Record<string, string> | undefined;
+    if (typeof rawMetadata.providerBindings === "object" && rawMetadata.providerBindings !== null) {
+      providerBindings = {};
+      for (const [provider, providerId] of Object.entries(rawMetadata.providerBindings as Record<string, unknown>)) {
+        const normalizedProvider = provider.trim();
+        if (normalizedProvider.length === 0 || providerId === null || providerId === undefined) {
+          continue;
+        }
+        const normalizedProviderId = String(providerId).trim();
+        if (normalizedProviderId.length === 0) {
+          continue;
+        }
+        providerBindings[normalizedProvider] = normalizedProviderId;
+      }
+      if (Object.keys(providerBindings).length === 0) {
+        providerBindings = undefined;
+      }
+    }
+
+    const sessionId = typeof rawMetadata.sessionId === "string" && rawMetadata.sessionId.trim().length > 0
+      ? rawMetadata.sessionId
+      : undefined;
+
+    if (sessionId || providerBindings) {
+      metadata = {
+        ...(sessionId ? { sessionId } : {}),
+        ...(providerBindings ? { providerBindings } : {}),
+      };
+    }
+  }
+
+  let outputStructured: Record<string, unknown> | undefined;
+  if (typeof record.output_structured === "object" && record.output_structured !== null && !Array.isArray(record.output_structured)) {
+    outputStructured = record.output_structured as Record<string, unknown>;
+  }
+
+  const normalized: WorkflowRuntimeTaskResultEnvelope = {
+    task_id: taskId,
+    tool_name: toolName,
+    title,
+    ...(metadata ? { metadata } : {}),
+    status,
+    output_text: outputText,
+    ...(outputStructured ? { output_structured: outputStructured } : {}),
+    ...(typeof record.error === "string" && record.error.length > 0 ? { error: record.error } : {}),
+    ...(typeof record.envelope_text === "string" && record.envelope_text.length > 0
+      ? { envelope_text: record.envelope_text }
+      : {}),
+  };
+
+  try {
+    const parsed = workflowRuntimeTaskResultEnvelopeSchema.parse(normalized);
+    const expectedTaskId = identity?.canonicalId ?? fallbackTaskId;
+    if (parsed.task_id !== expectedTaskId) {
+      incrementRuntimeParityCounter("workflow.runtime.parity.task_result_invariant_failures_total", {
+        reason: "task_id_mismatch",
+      });
+      throw new Error(
+        `TaskResult envelope task_id mismatch: expected ${expectedTaskId}, received ${parsed.task_id}`,
+      );
+    }
+
+    if (parsed.metadata?.providerBindings && identity?.providerBindings) {
+      for (const [provider, providerId] of Object.entries(parsed.metadata.providerBindings)) {
+        const identityBindings = identity.providerBindings[provider] ?? [];
+        if (!identityBindings.includes(providerId)) {
+          incrementRuntimeParityCounter("workflow.runtime.parity.task_result_invariant_failures_total", {
+            reason: "provider_binding_mismatch",
+            provider,
+          });
+          throw new Error(
+            `TaskResult envelope provider binding mismatch for ${provider}: expected one of [${identityBindings.join(", ")}], received ${providerId}`,
+          );
+        }
+      }
+    }
+
+    incrementRuntimeParityCounter("workflow.runtime.parity.task_result_normalized_total", {
+      status: parsed.status,
+    });
+    setRuntimeParityGauge(
+      "workflow.runtime.parity.task_result_provider_bindings",
+      Object.keys(parsed.metadata?.providerBindings ?? {}).length,
+      { taskId: parsed.task_id },
+    );
+    runtimeParityDebug("task_result_normalized", {
+      taskId: parsed.task_id,
+      status: parsed.status,
+      providers: Object.keys(parsed.metadata?.providerBindings ?? {}),
+    });
+    return parsed;
+  } catch (error) {
+    incrementRuntimeParityCounter("workflow.runtime.parity.task_result_normalization_failures_total", {
+      reason: "invalid_envelope",
+    });
+    runtimeParityDebug("task_result_normalization_failed", {
+      fallbackTaskId,
+      error: error instanceof Error ? error.message : String(error),
+    });
+    throw error;
+  }
+}
+
+export function toWorkflowRuntimeTask(
+  input: unknown,
+  fallbackId: () => string,
+): WorkflowRuntimeTask {
+  const parsed = workflowRuntimeTaskSchema.safeParse(input);
+  if (parsed.success) {
+    const rawRecord = asRecord(input);
+    const identity = normalizeTaskIdentity(parsed.data.identity, parsed.data.id);
+    incrementRuntimeParityCounter("workflow.runtime.parity.task_normalized_total", {
+      path: "schema_parse",
+    });
+    observeRuntimeParityHistogram(
+      "workflow.runtime.parity.task_blocked_by_count",
+      normalizeBlockedBy(parsed.data.blockedBy)?.length ?? 0,
+      { path: "schema_parse" },
+    );
+    runtimeParityDebug("task_normalized", {
+      taskId: parsed.data.id,
+      canonicalId: identity.canonicalId,
+      hasTaskResult: Boolean(parsed.data.taskResult || rawRecord.task_result),
+    });
+    return {
+      ...parsed.data,
+      status: normalizeWorkflowRuntimeTaskStatus(parsed.data.status),
+      blockedBy: normalizeBlockedBy(parsed.data.blockedBy),
+      identity,
+      taskResult: normalizeTaskResultEnvelope(
+        parsed.data.taskResult ?? rawRecord.task_result,
+        identity.canonicalId ?? parsed.data.id,
+        parsed.data.title,
+        identity,
+      ),
+    };
+  }
+
+  const record = asRecord(input);
+  const title = String(record.title ?? record.content ?? "");
+  const id = typeof record.id === "string" && record.id.trim().length > 0
+    ? record.id
+    : fallbackId();
+  const identity = normalizeTaskIdentity(record.identity, id);
+  incrementRuntimeParityCounter("workflow.runtime.parity.task_normalized_total", {
+    path: "fallback_parse",
+  });
+  observeRuntimeParityHistogram(
+    "workflow.runtime.parity.task_blocked_by_count",
+    normalizeBlockedBy(record.blockedBy)?.length ?? 0,
+    { path: "fallback_parse" },
+  );
+  runtimeParityDebug("task_normalized_fallback", {
+    taskId: id,
+    canonicalId: identity.canonicalId,
+    hasTaskResult: Boolean(record.taskResult ?? record.task_result),
+  });
+
+  return {
+    id,
+    title,
+    status: normalizeWorkflowRuntimeTaskStatus(record.status),
+    blockedBy: normalizeBlockedBy(record.blockedBy),
+    error: typeof record.error === "string" && record.error.length > 0
+      ? record.error
+      : undefined,
+    identity,
+    taskResult: normalizeTaskResultEnvelope(
+      record.taskResult ?? record.task_result,
+      id,
+      title,
+      identity,
+    ),
+  };
+}
+
+export function toWorkflowRuntimeTasks(
+  input: unknown,
+  fallbackId: () => string,
+): WorkflowRuntimeTask[] {
+  if (!Array.isArray(input)) {
+    return [];
+  }
+
+  return input.map((task) => toWorkflowRuntimeTask(task, fallbackId));
+}
+
+export function resolveWorkflowRuntimeFeatureFlags(
+  ...overrides: Array<WorkflowRuntimeFeatureFlagOverrides | undefined>
+): WorkflowRuntimeFeatureFlags {
+  return overrides.reduce<WorkflowRuntimeFeatureFlags>(
+    (resolved, next) => (next ? { ...resolved, ...next } : resolved),
+    { ...DEFAULT_WORKFLOW_RUNTIME_FEATURE_FLAGS },
+  );
+}
diff --git a/src/workflows/runtime-parity-observability.test.ts b/src/workflows/runtime-parity-observability.test.ts
new file mode 100644
index 0000000000..c990b04879
--- /dev/null
+++ b/src/workflows/runtime-parity-observability.test.ts
@@ -0,0 +1,82 @@
+import { beforeEach, describe, expect, spyOn, test } from "bun:test";
+import {
+  getRuntimeParityMetricsSnapshot,
+  incrementRuntimeParityCounter,
+  observeRuntimeParityHistogram,
+  resetRuntimeParityMetrics,
+  runtimeParityDebug,
+  setRuntimeParityGauge,
+} from "./runtime-parity-observability.ts";
+
+describe("runtime-parity-observability", () => {
+  beforeEach(() => {
+    resetRuntimeParityMetrics();
+  });
+
+  test("records counters, gauges, and histograms", () => {
+    incrementRuntimeParityCounter("workflow.runtime.parity.counter", { flow: "new" });
+    incrementRuntimeParityCounter("workflow.runtime.parity.counter", { flow: "new" });
+    setRuntimeParityGauge("workflow.runtime.parity.gauge", 3, { flow: "new" });
+    observeRuntimeParityHistogram("workflow.runtime.parity.histogram", 2, { flow: "new" });
+    observeRuntimeParityHistogram("workflow.runtime.parity.histogram", 5, { flow: "new" });
+
+    const snapshot = getRuntimeParityMetricsSnapshot();
+    expect(snapshot.counters["workflow.runtime.parity.counter{flow=new}"]).toBe(2);
+    expect(snapshot.gauges["workflow.runtime.parity.gauge{flow=new}"]).toBe(3);
+    expect(snapshot.histograms["workflow.runtime.parity.histogram{flow=new}"]).toEqual([2, 5]);
+  });
+
+  test("normalizes metric labels and supports custom increments", () => {
+    incrementRuntimeParityCounter(
+      "workflow.runtime.parity.counter",
+      { z: "last", a: "first", ignored: undefined },
+      3,
+    );
+
+    const snapshot = getRuntimeParityMetricsSnapshot();
+    expect(snapshot.counters["workflow.runtime.parity.counter{a=first,z=last}"]).toBe(3);
+  });
+
+  test("debug log stays gated unless debug flags are enabled", () => {
+    const originalDebug = process.env.DEBUG;
+    const originalWorkflowDebug = process.env.ATOMIC_WORKFLOW_DEBUG;
+    delete process.env.DEBUG;
+    delete process.env.ATOMIC_WORKFLOW_DEBUG;
+
+    const debugSpy = spyOn(console, "debug").mockImplementation(() => {});
+    runtimeParityDebug("phase", { ok: true });
+    expect(debugSpy).not.toHaveBeenCalled();
+
+    process.env.DEBUG = "1";
+    runtimeParityDebug("phase", { ok: true });
+    expect(debugSpy).toHaveBeenCalledTimes(1);
+
+    process.env.DEBUG = "0";
+    runtimeParityDebug("phase-disabled", { ok: "disabled" });
+    expect(debugSpy).toHaveBeenCalledTimes(1);
+
+    delete process.env.DEBUG;
+    process.env.ATOMIC_WORKFLOW_DEBUG = "1";
+    runtimeParityDebug("phase-workflow", { ok: "workflow" });
+    expect(debugSpy).toHaveBeenCalledTimes(2);
+
+    delete process.env.ATOMIC_WORKFLOW_DEBUG;
+    runtimeParityDebug("phase-disabled-2", { ok: "disabled" });
+    expect(debugSpy).toHaveBeenCalledTimes(2);
+    expect(debugSpy.mock.calls[1]?.[0]).toBe(
+      '[workflow.runtime.parity] phase-workflow {"ok":"workflow"}',
+    );
+
+    if (originalDebug === undefined) {
+      delete process.env.DEBUG;
+    } else {
+      process.env.DEBUG = originalDebug;
+    }
+    if (originalWorkflowDebug === undefined) {
+      delete process.env.ATOMIC_WORKFLOW_DEBUG;
+    } else {
+      process.env.ATOMIC_WORKFLOW_DEBUG = originalWorkflowDebug;
+    }
+    debugSpy.mockRestore();
+  });
+});
diff --git a/src/workflows/runtime-parity-observability.ts b/src/workflows/runtime-parity-observability.ts
new file mode 100644
index 0000000000..c8b3687300
--- /dev/null
+++ b/src/workflows/runtime-parity-observability.ts
@@ -0,0 +1,104 @@
+export interface RuntimeParityMetricsSnapshot {
+  counters: Record<string, number>;
+  gauges: Record<string, number>;
+  histograms: Record<string, number[]>;
+}
+
+interface RuntimeParityMetricsState {
+  counters: Map<string, number>;
+  gauges: Map<string, number>;
+  histograms: Map<string, number[]>;
+}
+
+const state: RuntimeParityMetricsState = {
+  counters: new Map(),
+  gauges: new Map(),
+  histograms: new Map(),
+};
+
+const DEBUG_ENABLED = () => {
+  const debugValue = process.env.DEBUG?.trim().toLowerCase();
+  if (debugValue) {
+    return debugValue === "1" || debugValue === "true" || debugValue === "on";
+  }
+  return process.env.ATOMIC_WORKFLOW_DEBUG === "1";
+};
+
+function metricKey(name: string, labels?: Record<string, string | number | boolean | undefined>): string {
+  if (!labels || Object.keys(labels).length === 0) {
+    return name;
+  }
+
+  const encoded = Object.entries(labels)
+    .filter(([, value]) => value !== undefined)
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([label, value]) => `${label}=${String(value)}`)
+    .join(",");
+
+  return encoded.length > 0 ? `${name}{${encoded}}` : name;
+}
+
+export function incrementRuntimeParityCounter(
+  name: string,
+  labels?: Record<string, string | number | boolean | undefined>,
+  amount = 1,
+): number {
+  const key = metricKey(name, labels);
+  const next = (state.counters.get(key) ?? 0) + amount;
+  state.counters.set(key, next);
+  return next;
+}
+
+export function setRuntimeParityGauge(
+  name: string,
+  value: number,
+  labels?: Record<string, string | number | boolean | undefined>,
+): void {
+  const key = metricKey(name, labels);
+  state.gauges.set(key, value);
+}
+
+export function observeRuntimeParityHistogram(
+  name: string,
+  value: number,
+  labels?: Record<string, string | number | boolean | undefined>,
+): void {
+  const key = metricKey(name, labels);
+  const values = state.histograms.get(key) ?? [];
+  values.push(value);
+  state.histograms.set(key, values);
+}
+
+export function getRuntimeParityMetricsSnapshot(): RuntimeParityMetricsSnapshot {
+  const counters: Record<string, number> = {};
+  const gauges: Record<string, number> = {};
+  const histograms: Record<string, number[]> = {};
+
+  for (const [key, value] of state.counters) {
+    counters[key] = value;
+  }
+  for (const [key, value] of state.gauges) {
+    gauges[key] = value;
+  }
+  for (const [key, value] of state.histograms) {
+    histograms[key] = [...value];
+  }
+
+  return { counters, gauges, histograms };
+}
+
+export function resetRuntimeParityMetrics(): void {
+  state.counters.clear();
+  state.gauges.clear();
+  state.histograms.clear();
+}
+
+export function runtimeParityDebug(
+  phase: string,
+  data: Record<string, unknown>,
+): void {
+  if (!DEBUG_ENABLED()) {
+    return;
+  }
+  console.debug(`[workflow.runtime.parity] ${phase} ${JSON.stringify(data)}`);
+}
diff --git a/src/workflows/session.ts b/src/workflows/session.ts
index 4ea96d7b62..589e57a385 100644
--- a/src/workflows/session.ts
+++ b/src/workflows/session.ts
@@ -8,7 +8,7 @@
 
 import { join } from "path";
 import { homedir } from "os";
-import type { SubagentResult } from "../graph/subagent-bridge.ts";
+import type { SubagentStreamResult } from "./graph/types.ts";
 
 // ============================================================================
 // Types
@@ -87,7 +87,7 @@ export async function saveWorkflowSession(session: WorkflowSession): Promise<voi
 export async function saveSubagentOutput(
   sessionDir: string,
   agentId: string,
-  result: SubagentResult,
+  result: SubagentStreamResult,
 ): Promise<string> {
   const outputPath = join(sessionDir, "agents", `${agentId}.json`);
   await Bun.write(outputPath, JSON.stringify(result, null, 2));
diff --git a/src/workflows/task-identity-service.test.ts b/src/workflows/task-identity-service.test.ts
new file mode 100644
index 0000000000..81110d5c97
--- /dev/null
+++ b/src/workflows/task-identity-service.test.ts
@@ -0,0 +1,58 @@
+import { describe, expect, test } from "bun:test";
+import { TaskIdentityService } from "./task-identity-service.ts";
+import type { WorkflowRuntimeTask } from "./runtime-contracts.ts";
+
+function createTask(overrides?: Partial<WorkflowRuntimeTask>): WorkflowRuntimeTask {
+  return {
+    id: "#1",
+    title: "Implement identity service",
+    status: "pending",
+    ...overrides,
+  };
+}
+
+describe("TaskIdentityService", () => {
+  test("creates provider binding and resolves canonical task id", () => {
+    const service = new TaskIdentityService();
+
+    const backfilled = service.backfillTask(createTask());
+    const bound = service.bindProviderId(backfilled, "subagent_id", "worker-#1");
+
+    expect(bound.identity?.providerBindings?.subagent_id).toEqual(["worker-#1"]);
+    expect(service.resolveCanonicalTaskId("subagent_id", "worker-#1")).toBe("#1");
+  });
+
+  test("backfills legacy tasks without identity metadata", () => {
+    const service = new TaskIdentityService();
+
+    const backfilled = service.backfillTask(createTask({ id: "#42", identity: undefined }));
+
+    expect(backfilled.identity?.canonicalId).toBe("#42");
+    expect(backfilled.identity?.providerBindings?.task_id).toContain("#42");
+    expect(backfilled.identity?.providerBindings?.task_id).toContain("42");
+    expect(service.resolveCanonicalTaskId("task_id", "42")).toBe("#42");
+  });
+
+  test("binding operations are idempotent", () => {
+    const service = new TaskIdentityService();
+
+    const first = service.bindProviderId(createTask(), "subagent_id", "worker-1");
+    const second = service.bindProviderId(first, "subagent_id", "worker-1");
+
+    expect(second.identity?.providerBindings?.subagent_id).toEqual(["worker-1"]);
+    expect(service.resolveCanonicalTaskId("subagent_id", "worker-1")).toBe("#1");
+  });
+
+  test("backfillTasks handles mixed task snapshots", () => {
+    const service = new TaskIdentityService();
+    const tasks = service.backfillTasks([
+      createTask({ id: "#1" }),
+      createTask({ id: "#2", title: "Second", status: "in_progress" }),
+    ]);
+
+    expect(tasks).toHaveLength(2);
+    expect(tasks[0]?.identity?.canonicalId).toBe("#1");
+    expect(tasks[1]?.identity?.canonicalId).toBe("#2");
+    expect(service.resolveCanonicalTaskId("task_id", "2")).toBe("#2");
+  });
+});
diff --git a/src/workflows/task-identity-service.ts b/src/workflows/task-identity-service.ts
new file mode 100644
index 0000000000..7df37ce8cf
--- /dev/null
+++ b/src/workflows/task-identity-service.ts
@@ -0,0 +1,205 @@
+import type {
+  WorkflowRuntimeTask,
+  WorkflowRuntimeTaskIdentity,
+  WorkflowRuntimeTaskIdentityRuntime,
+} from "./runtime-contracts.ts";
+
+const TASK_ID_PROVIDER = "task_id";
+
+function normalizeToken(value: string): string {
+  return value.trim();
+}
+
+function normalizeProvider(value: string): string {
+  return normalizeToken(value).toLowerCase();
+}
+
+function normalizeTaskKey(value: string): string {
+  return normalizeToken(value).toLowerCase();
+}
+
+function toCanonicalTaskAlias(taskId: string): string | null {
+  const normalized = normalizeTaskKey(taskId).replace(/^#/, "");
+  return normalized.length > 0 ? normalized : null;
+}
+
+function cloneProviderBindings(identity: WorkflowRuntimeTaskIdentity): Record<string, string[]> {
+  const cloned: Record<string, string[]> = {};
+  const bindings = identity.providerBindings;
+  if (!bindings) {
+    return cloned;
+  }
+
+  for (const [provider, ids] of Object.entries(bindings)) {
+    if (!Array.isArray(ids) || ids.length === 0) {
+      continue;
+    }
+
+    const normalizedProvider = normalizeProvider(provider);
+    if (normalizedProvider.length === 0) {
+      continue;
+    }
+
+    const deduped = Array.from(new Set(ids.map((id) => normalizeToken(id)).filter((id) => id.length > 0)));
+    if (deduped.length > 0) {
+      cloned[normalizedProvider] = deduped;
+    }
+  }
+
+  return cloned;
+}
+
+function upsertBinding(bindings: Record<string, string[]>, provider: string, providerId: string): boolean {
+  const providerKey = normalizeProvider(provider);
+  const providerValue = normalizeToken(providerId);
+  if (providerKey.length === 0 || providerValue.length === 0) {
+    return false;
+  }
+
+  const ids = bindings[providerKey] ?? [];
+  if (!ids.includes(providerValue)) {
+    bindings[providerKey] = [...ids, providerValue];
+    return true;
+  }
+
+  if (!bindings[providerKey]) {
+    bindings[providerKey] = ids;
+  }
+  return false;
+}
+
+/**
+ * Maintains canonical task IDs and provider-specific task ID bindings.
+ *
+ * Backfill behavior:
+ * - Pre-existing tasks without identity metadata are assigned canonical IDs.
+ * - `task_id` provider bindings are synthesized from task IDs.
+ * - Legacy `#id` and bare `id` aliases are both registered for lookup.
+ */
+export class TaskIdentityService implements WorkflowRuntimeTaskIdentityRuntime {
+  private readonly providerIdToCanonicalTaskId = new Map<string, string>();
+  private readonly canonicalAliases = new Map<string, string>();
+
+  backfillTask(task: WorkflowRuntimeTask): WorkflowRuntimeTask {
+    const canonicalId = normalizeToken(task.id);
+    const identity = this.withBackfilledIdentity(task.identity, canonicalId);
+
+    const normalizedTask: WorkflowRuntimeTask = {
+      ...task,
+      id: canonicalId,
+      identity,
+    };
+
+    this.registerTask(normalizedTask);
+    return normalizedTask;
+  }
+
+  backfillTasks(tasks: WorkflowRuntimeTask[]): WorkflowRuntimeTask[] {
+    return tasks.map((task) => this.backfillTask(task));
+  }
+
+  bindProviderId(task: WorkflowRuntimeTask, provider: string, providerId: string): WorkflowRuntimeTask {
+    const normalizedTask = this.backfillTask(task);
+    const bindings = cloneProviderBindings(normalizedTask.identity ?? { canonicalId: normalizedTask.id });
+    const changed = upsertBinding(bindings, provider, providerId);
+
+    if (!changed) {
+      this.registerTask(normalizedTask);
+      return normalizedTask;
+    }
+
+    const boundTask: WorkflowRuntimeTask = {
+      ...normalizedTask,
+      identity: {
+        canonicalId: normalizedTask.id,
+        providerBindings: bindings,
+      },
+    };
+
+    this.registerTask(boundTask);
+    return boundTask;
+  }
+
+  resolveCanonicalTaskId(provider: string, providerId: string): string | null {
+    const key = this.providerBindingKey(provider, providerId);
+    if (!key) {
+      return null;
+    }
+
+    const direct = this.providerIdToCanonicalTaskId.get(key);
+    if (direct) {
+      return direct;
+    }
+
+    if (normalizeProvider(provider) !== TASK_ID_PROVIDER) {
+      return null;
+    }
+
+    const alias = toCanonicalTaskAlias(providerId);
+    if (!alias) {
+      return null;
+    }
+
+    return this.canonicalAliases.get(alias) ?? null;
+  }
+
+  private withBackfilledIdentity(
+    rawIdentity: WorkflowRuntimeTaskIdentity | undefined,
+    canonicalId: string,
+  ): WorkflowRuntimeTaskIdentity {
+    const identity: WorkflowRuntimeTaskIdentity = {
+      canonicalId,
+      providerBindings: cloneProviderBindings(rawIdentity ?? { canonicalId }),
+    };
+
+    upsertBinding(identity.providerBindings ?? {}, TASK_ID_PROVIDER, canonicalId);
+
+    const alias = toCanonicalTaskAlias(canonicalId);
+    if (alias && alias !== normalizeTaskKey(canonicalId)) {
+      upsertBinding(identity.providerBindings ?? {}, TASK_ID_PROVIDER, alias);
+    }
+
+    if (identity.providerBindings && Object.keys(identity.providerBindings).length === 0) {
+      identity.providerBindings = undefined;
+    }
+
+    return identity;
+  }
+
+  private registerTask(task: WorkflowRuntimeTask): void {
+    const canonicalId = normalizeToken(task.id);
+    const alias = toCanonicalTaskAlias(canonicalId);
+    if (alias) {
+      if (!this.canonicalAliases.has(alias)) {
+        this.canonicalAliases.set(alias, canonicalId);
+      }
+      if (!this.canonicalAliases.has(normalizeTaskKey(canonicalId))) {
+        this.canonicalAliases.set(normalizeTaskKey(canonicalId), canonicalId);
+      }
+    }
+
+    const providerBindings = task.identity?.providerBindings;
+    if (!providerBindings) {
+      return;
+    }
+
+    for (const [provider, ids] of Object.entries(providerBindings)) {
+      for (const id of ids) {
+        const key = this.providerBindingKey(provider, id);
+        if (!key || this.providerIdToCanonicalTaskId.has(key)) {
+          continue;
+        }
+        this.providerIdToCanonicalTaskId.set(key, canonicalId);
+      }
+    }
+  }
+
+  private providerBindingKey(provider: string, providerId: string): string | null {
+    const normalizedProvider = normalizeProvider(provider);
+    const normalizedProviderId = normalizeToken(providerId);
+    if (normalizedProvider.length === 0 || normalizedProviderId.length === 0) {
+      return null;
+    }
+    return `${normalizedProvider}::${normalizedProviderId}`;
+  }
+}
diff --git a/src/workflows/task-result-envelope.test.ts b/src/workflows/task-result-envelope.test.ts
new file mode 100644
index 0000000000..41784db465
--- /dev/null
+++ b/src/workflows/task-result-envelope.test.ts
@@ -0,0 +1,84 @@
+import { describe, expect, test } from "bun:test";
+import type { WorkflowRuntimeTask } from "./runtime-contracts.ts";
+import {
+  buildTaskResultEnvelope,
+  formatTaskResultEnvelopeText,
+} from "./task-result-envelope.ts";
+
+function createTask(): WorkflowRuntimeTask {
+  return {
+    id: "#9",
+    title: "Implement task result envelope",
+    status: "in_progress",
+    identity: {
+      canonicalId: "#9",
+      providerBindings: {
+        task_id: ["#9", "9"],
+        subagent_id: ["worker-9"],
+      },
+    },
+  };
+}
+
+describe("task-result-envelope", () => {
+  test("formats canonical task result envelope text", () => {
+    expect(formatTaskResultEnvelopeText("#9", "All done")).toBe(
+      "task_id: #9 (for resuming to continue this task if needed)\n\n<task_result>\nAll done\n</task_result>",
+    );
+  });
+
+  test("builds envelope from task identity and provider binding", () => {
+    const envelope = buildTaskResultEnvelope({
+      task: createTask(),
+      result: {
+        agentId: "worker-9",
+        success: true,
+        output: "Implemented and tested.",
+      },
+      sessionId: "session-123",
+    });
+
+    expect(envelope).toMatchObject({
+      task_id: "#9",
+      tool_name: "task",
+      title: "Implement task result envelope",
+      metadata: {
+        sessionId: "session-123",
+        providerBindings: {
+          subagent_id: "worker-9",
+        },
+      },
+      status: "completed",
+      output_text: "Implemented and tested.",
+    });
+    expect(envelope.envelope_text).toContain("task_id: #9");
+    expect(envelope.envelope_text).toContain("<task_result>");
+  });
+
+  test("falls back to result agent id when provider binding is unavailable", () => {
+    const envelope = buildTaskResultEnvelope({
+      task: {
+        id: "task-a",
+        title: "Fallback",
+        status: "in_progress",
+        identity: {
+          canonicalId: "task-a",
+          providerBindings: {
+            task_id: ["task-a"],
+          },
+        },
+      },
+      result: {
+        agentId: "worker-a",
+        success: false,
+        output: "",
+        error: "Worker failed",
+      },
+      sessionId: "session-xyz",
+    });
+
+    expect(envelope.status).toBe("error");
+    expect(envelope.error).toBe("Worker failed");
+    expect(envelope.metadata?.providerBindings?.subagent_id).toBe("worker-a");
+  });
+});
diff --git a/src/workflows/task-result-envelope.ts b/src/workflows/task-result-envelope.ts
new file mode 100644
index 0000000000..3d43b84bfb
--- /dev/null
+++ b/src/workflows/task-result-envelope.ts
@@ -0,0 +1,80 @@
+import type { SubagentStreamResult } from "./graph/types.ts";
+import {
+  type WorkflowRuntimeTask,
+  workflowRuntimeTaskSchema,
+  type WorkflowRuntimeTaskResultEnvelope,
+} from "./runtime-contracts.ts";
+
+const DEFAULT_TOOL_NAME = "task";
+const DEFAULT_PROVIDER = "subagent_id";
+
+interface BuildTaskResultEnvelopeInput {
+  task: WorkflowRuntimeTask;
+  result: Pick<SubagentStreamResult, "success" | "output" | "error" | "agentId">;
+  sessionId?: string;
+  provider?: string;
+  toolName?: string;
+  outputStructured?: Record<string, unknown>;
+}
+
+function normalizeToken(value: string): string {
+  return value.trim();
+}
+
+function firstBinding(task: WorkflowRuntimeTask, provider: string): string | undefined {
+  const bindings = task.identity?.providerBindings;
+  if (!bindings) {
+    return undefined;
+  }
+  const key = provider.trim().toLowerCase();
+  for (const [bindingProvider, ids] of Object.entries(bindings)) {
+    if (bindingProvider.trim().toLowerCase() !== key) {
+      continue;
+    }
+    const first = ids[0];
+    if (typeof first === "string" && first.trim().length > 0) {
+      return first;
+    }
+  }
+  return undefined;
+}
+
+export function formatTaskResultEnvelopeText(taskId: string, outputText: string): string {
+  return [
+    `task_id: ${taskId} (for resuming to continue this task if needed)`,
+    "",
+    "<task_result>",
+    outputText,
+    "</task_result>",
+  ].join("\n");
+}
+
+export function buildTaskResultEnvelope(
+  input: BuildTaskResultEnvelopeInput,
+): WorkflowRuntimeTaskResultEnvelope {
+  const task = workflowRuntimeTaskSchema.parse(input.task);
+  const canonicalTaskId = task.identity?.canonicalId ?? task.id;
+  const provider = normalizeToken(input.provider ?? DEFAULT_PROVIDER);
+  const providerId = firstBinding(task, provider) ?? input.result.agentId;
+  const outputText = typeof input.result.output === "string" ? input.result.output : "";
+  const status: WorkflowRuntimeTaskResultEnvelope["status"] = input.result.success ? "completed" : "error";
+
+  return {
+    task_id: canonicalTaskId,
+    tool_name: normalizeToken(input.toolName ?? DEFAULT_TOOL_NAME) || DEFAULT_TOOL_NAME,
+    title: task.title,
+    ...(input.sessionId || providerId
+      ? {
+        metadata: {
+          ...(input.sessionId ? { sessionId: input.sessionId } : {}),
+          ...(providerId ? { providerBindings: { [provider || DEFAULT_PROVIDER]: providerId } } : {}),
+        },
+      }
+      : {}),
+    status,
+    output_text: outputText,
+    ...(input.outputStructured ? { output_structured: input.outputStructured } : {}),
+    ...(!input.result.success && input.result.error ? { error: input.result.error } : {}),
+    envelope_text: formatTaskResultEnvelopeText(canonicalTaskId, outputText),
+  };
+}