Summary

This branch delivers three foundation layers for the Hermes Agent desktop workbench. First, a read-only Browser Workspace — an Electron host that renders external URLs and exposes a chat message insertion contract, without any browser automation capability. Second, kanban review/QA feedback events — structured defect tracking wired into the CLI kanban surface. Third, a complete executors framework spanning a typed registry, capability-based router, five CLI adapters, guarded worktree tools, context/inbox/prompt tooling, an IPC bridge, review chain primitives, and a top-level argparse CLI entry point. Two UI upgrades ship alongside: structured tool-result preview panels and embedded chat session routing. All executor modules are backed by 463 passing tests, destructive operations are gated behind confirmation prompts, and import side-effect guards prevent the CLI from leaking into live subsystems.

What Changed

Browser Workspace

• Electron host scaffold: main.ts (lifecycle, window management, IPC handlers), preload.ts (context bridge), renderer.html (shell), schema.ts (typed contracts)
• Chat message insertion contract (browser-workspace:insert-chat-message) validated against a golden contract-snapshot.json via validate-contract.mjs
• Static dashboard plugin assets under plugins/browser-workspace/dashboard/
• The host renders external URLs in a BrowserView; it does not implement click, type, submit, or navigate automation

Kanban Review/QA Feedback

• hermes_cli/kanban_feedback.py — structured review and QA defect event types with typed routing
• hermes_cli/kanban.py — kanban surface integration glue
• hermes_cli/web_server.py — lightweight HTTP server for dashboard plugin delivery
• Unit coverage in tests/hermes_cli/test_kanban_cli.py

Structured Preview UI

• web/src/components/ToolCall.tsx — structured preview panel that renders tool results with formatted sections instead of raw JSON blobs
• web/src/components/ChatSidebar.tsx — expanded sidebar with session list, routing, and status indicators
• web/src/pages/ChatPage.tsx / web/src/pages/ConfigPage.tsx — page-level wiring for preview and sidebar
• web/src/App.tsx — top-level routing integration

Embedded Chat Routing Mode

• Chat session routing embedded into the web app shell so the UI can deep-link into specific sessions without full page reloads

Executors Framework

A — Core Registry and Router

• executors/registry.py — typed executor registry with binary discovery and structured health probes
• executors/router.py — capability-based router that produces recommendations and accepts user overrides
• executors/types.py — shared dataclass type system (capabilities, routing decisions, health status, executor info)
• executors/health.py — per-executor health checks with table and JSON output formatters

B — Adapters

• executors/claude_code_adapter.py — Claude Code CLI adapter
• executors/codex_adapter.py — Codex adapter
• executors/deepseek_tui_adapter.py — DeepSeek TUI adapter
• executors/hermes_local_adapter.py — Hermes local adapter
• executors/opencode_adapter.py — OpenCode adapter
• All adapters conform to the shared ExecutorCapabilities contract defined in types.py

C1 — Context / Inbox / Prompt Tools

• executors/context.py + executors/context_cli.py — workspace context injection CLI
• executors/inbox.py + executors/inbox_cli.py — external inbox management CLI
• executors/prompt_builder.py — structured prompt assembly from context + task spec

C2 — Guarded Worktree Tools

• executors/worktree.py + executors/worktree_cli.py — worktree create, list, merge, and discard
• Merge and discard operations require explicit user confirmation or --force; the gate is verified in tests
• Root resolution walks up to the parent repository, avoiding path assumptions

D1a — Bridge / IPC / Review Parsing Primitives

• executors/ipc.py — typed IPC message protocol with structured envelopes
• executors/bridge.py + executors/bridge_cli.py — run-event-log ↔ review bridge
• executors/review_agent.py — review chain agent logic

D1b — Review Handler + Review CLI

• executors/review_handler.py — review orchestration handler
• executors/review_cli.py — review subcommand CLI

D2 — Top-Level CLI

• executors/cli.py — argparse-based entry point wiring all subcommands: registry, health, routing, worktree, context, review, QA, inbox, and bridge
• executors/__init__.py — package public API surface
• Delegates destructive subcommands (worktree) to the guarded handler paths
• Import side-effect guards verified in tests: importing the CLI module does not invoke shutil.which, load hermes_cli, or spawn subprocesses

Safety Boundaries

• Browser Workspace is strictly read-only. The Electron host renders external URLs in a BrowserView and exposes a chat message insertion IPC contract. No agent can click, type, submit, or navigate within the rendered page. No browser automation capability exists in this PR.
• No Chrome extension compatibility layer. The Browser Workspace uses an Electron shell, not a Chrome extension harness. Chrome extension APIs (tabs, scripting, debugger) are not used or polyfilled.
• Worktree destructive operations are gated. Merge and discard both require explicit user confirmation (interactive prompt) or --force. Tests verify the gate blocks unconfirmed destructive calls.
• Executor tests never call real external CLIs or models. All adapter tests use binary stubs or mock registries. No network requests, no child-process side effects, no real model invocations.
• Import side-effect isolation. Five boundary guard tests confirm that importing executors/cli.py does not trigger shutil.which, does not load hermes_cli, does not spawn subprocesses, and does not import worktree, kanban_feedback, or other uncommitted modules at the top level.
• No force push, no destructive repo operations. All worktree tests operate on temporary directories under $TMPDIR. No repository-level destructive operations are performed by any test.

Validation

What Did Not Ship

• Browser action automation — no click, type, submit, navigate, or scroll APIs
• Chrome extension compatibility — no chrome.tabs / chrome.scripting / chrome.debugger bridge
• ChatSessionSidebar wiring — kept as a local excluded draft, not connected to the app shell in this PR
• Production Electron packaging, code signing, or auto-update
• Full security threat model for the Electron Browser Workspace host
• External browser adapter implementation (browser_adapter.py)
• End-to-end multi-step executor orchestration pipelines
• Bridge ↔ kanban feedback path integration (the two remain architecturally separate by design)

Risks / Follow-ups

• Native macOS visual checks are still needed for the Electron Browser Workspace. TypeScript compilation and contract validation pass, but the rendered shell has not been visually verified on macOS.
• Executors review/QA path remains separate from the kanban_feedback event path by design. Future work may bridge them at the routing or bridge layer, but for now they are independent subsystems.
• ChatSessionSidebar is kept as a local excluded draft. It is not wired into the app shell and is not part of this PR. Downstream work will need to integrate it.
• Larger end-to-end executor orchestration (multi-step run pipelines with real adapters) still needs integration testing. The current tests validate each module in isolation.
• hermes_cli/kanban_feedback.py introduces a new feedback event path. Its interaction with the existing kanban CLI surface should be documented before downstream consumers adopt it.
• Browser Workspace contract is validated against a golden snapshot. If the IPC contract evolves, the snapshot must be updated and re-validated.

Commit Breakdown

🤖 Generated with Claude Code