let-them-talk 5.4.0 → 5.4.1

package/README.md

@@ -1,158 +1,346 @@
 <p align="center">
-  <img src="logo.png" alt="Let Them Talk" width="120">
+  <img src="logo.png" alt="Let Them Talk" width="140">
 </p>
 
 <h1 align="center">Let Them Talk</h1>
 
 <p align="center">
-  Local multi-agent collaboration for AI CLI terminals and API adapters.
+  <strong>Let your AI agents actually work as a team.</strong><br>
+  Multi-agent collaboration for Claude Code, Gemini CLI, Codex CLI, Ollama, and API-backed agents — with a live operator dashboard and a 3D virtual office to watch it all happen.
 </p>
 
-Let Them Talk is a local MCP broker and operator dashboard. Claude Code, Gemini CLI, Codex CLI, and API-backed agents share one project runtime, exchange messages, manage work, and expose the same branch, session, and evidence model through a shared `.agent-bridge/` directory.
+<p align="center">
+  <a href="https://www.npmjs.com/package/let-them-talk"><img src="https://img.shields.io/npm/v/let-them-talk.svg?style=flat&color=58a6ff" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/let-them-talk"><img src="https://img.shields.io/npm/dm/let-them-talk.svg?style=flat&color=3fb950" alt="npm downloads"></a>
+  <a href="https://github.com/Dekelelz/let-them-talk/blob/master/LICENSE"><img src="https://img.shields.io/badge/License-BSL%201.1-f59e0b.svg?style=flat" alt="BSL 1.1"></a>
+  <a href="https://discord.gg/6Y9YgkFNJP"><img src="https://img.shields.io/discord/1482478651000885359?color=5865F2&label=Discord&logo=discord&logoColor=white&style=flat" alt="Discord"></a>
+  <a href="https://nodejs.org/"><img src="https://img.shields.io/node/v/let-them-talk.svg?color=3fb950&style=flat" alt="Node.js"></a>
+</p>
+
+<p align="center">
+  <a href="https://talk.unrealai.studio">Website</a> ·
+  <a href="#-quick-start">Quick Start</a> ·
+  <a href="#-features">Features</a> ·
+  <a href="#-installation">Install</a> ·
+  <a href="#-dashboard-tour">Dashboard</a> ·
+  <a href="#-core-concepts">Concepts</a> ·
+  <a href="#-architecture">Architecture</a> ·
+  <a href="https://discord.gg/6Y9YgkFNJP">Discord</a>
+</p>
+
+---
+
+## What it is
+
+Let Them Talk is a **local MCP broker and operator dashboard** that lets multiple AI CLI agents share one project runtime. Open Claude Code, Gemini CLI, or Codex CLI in separate terminals — they discover each other, exchange messages, assign tasks, review each other's work, coordinate through workflows, and coordinate branches, sessions, and evidence through a shared `.agent-bridge/` directory. A browser dashboard gives you real-time visibility with 12 tabs — including a 3D virtual office where chibi agent characters walk between desks, wave during broadcasts, and sleep when idle.
+
+If you want your agents to stop working in isolation and start collaborating like a real team, this is it.
 
-## Quick start
+---
+
+## 🚀 Quick Start
 
 ```bash
+# 1. Configure the MCP broker for every installed CLI (Claude / Gemini / Codex)
 npx let-them-talk init
+
+# 2. Launch the web dashboard (localhost:3000)
 node .agent-bridge/launch.js
 ```
 
-In each agent terminal:
+Now open your CLI in a second terminal and tell it to join:
+
+```
+You are "Alice". Call register("Alice","Claude"), then get_briefing(),
+then listen_group() and stay in the loop.
+```
+
+Open a third terminal, tell that agent to register as `Bob`, and the two will start talking. Everything is visible in the dashboard Messages tab, and you can reply directly from there.
+
+> **Skip the manual prompts** with `npx let-them-talk init --template team` — gives you Coordinator + Researcher + Coder prompts ready to paste.
+
+---
 
-1. Register an agent name.
-2. Call `get_briefing()` if you are joining existing work.
-3. Use `listen()` in direct mode, `listen_group()` in group or managed mode, or `get_work()` if you are running the proactive autonomy loop.
+## ⚡ Why Let Them Talk
 
-## Current runtime model
+| Without Let Them Talk | With Let Them Talk |
+|---|---|
+| One agent works, you copy-paste context to the next | Agents share one runtime and see each other's work automatically |
+| "Done" is just a message that says "done" | Completion requires structured evidence (summary, verification, files_changed, confidence) |
+| You babysit the loop all day | `get_work` / `verify_and_advance` + autonomy-v2 run the loop for you |
+| No visibility into what agents are doing | Dashboard with Messages, Tasks, Workflows, Graph, Plan, 3D Hub |
+| Provider lock-in | Claude Code, Gemini CLI, Codex CLI, Ollama, and custom API agents all first-class |
+| Coordination is "chat" | Branches are full execution contexts. Sessions are branch-scoped. Governance is event-backed. |
 
-- Canonical runtime state is broker-owned and event-backed under `.agent-bridge/runtime/`.
-- Legacy JSON and JSONL files remain compatibility projections during migration. They are not the authority model.
-- The runtime contract treats branches as full-context namespaces. In the shipped runtime today, branch-local guarantees already cover messages and history, delivery and read state, conversation control and non-general channels, sessions, evidence, tasks and workflows, and workspaces.
-- Branch-local guarantees now also cover the governance surfaces that used to remain compatibility-shared during migration: decisions, KB, reviews, dependencies, votes, rules, and progress.
-- Branch switches replace the whole migrated branch-local collaboration view at once.
-- Sessions are tied to one agent on one branch. Switching branches suspends one branch session and creates or resumes another, and forks copy historical session and evidence context without cloning live execution.
-- Terminal task and workflow completion is only authoritative when structured evidence is recorded, including `recorded_at` and `recorded_by_session` metadata.
-- Markdown workspace export writes to `.agent-bridge-markdown/` and stays non-authoritative. Editing exported markdown does not change runtime state.
+---
 
-Packaged docs and architecture references:
+## ✨ Features
 
-- `USAGE.md`
-- `docs/architecture/runtime-contract.md`
-- `docs/architecture/branch-semantics.md`
-- `docs/architecture/canonical-event-schema.md`
-- `docs/architecture/markdown-workspace.md`
-- `docs/architecture/runtime-migration-hardening.md`
+- **66 MCP tools** for the full coordination surface — `register`, `send_message`, `broadcast`, `listen_group`, `get_work`, `verify_and_advance`, `create_task`, `start_plan`, `advance_workflow`, `lock_file`, `log_decision`, `kb_write`, `call_vote`, `submit_review`, `handoff`, and 50+ more.
+- **Canonical runtime** — event-backed state under `.agent-bridge/runtime/` with replay, projections, and branch-local isolation.
+- **Branches as full execution contexts** — messages, tasks, workflows, sessions, evidence, governance (decisions, KB, reviews, votes, rules, progress) all switch together on a branch change.
+- **Sessions + evidence-backed completion** — first-class session records; "done" is authoritative only when structured evidence is recorded (`summary`, `verification`, `files_changed`, `confidence`, `recorded_at`, `recorded_by_session`).
+- **Explicit runtime descriptors** — `runtime_type`, `provider_id`, `model_id`, `capabilities` (chat, vision, image_generation, video_generation, texture_generation). Mixed-provider teams coordinate by capability, not guesswork.
+- **Autonomy-v2** — `get_work` picks the next item using canonical state + sessions + evidence + capabilities + contracts. Watchdog with idle detection, retry policy, circuit breakers, and bounded escalation.
+- **3D virtual office** — real-time chibi-style visualization of your team. Agents walk between desks, react to broadcasts, celebrate tasks, sleep when idle.
+- **Web dashboard** — 12 tabs: 3D Hub, Messages, Tasks, Workspaces, Workflows, Graph, Plan, Launch, Rules, Stats, Services, Docs.
+- **Managed mode** — structured turn-taking with a Manager agent (`claim_manager`, `yield_floor`, `set_phase`) — prevents 3+ agent chaos.
+- **Channels** — sub-team communication without flooding `#general`.
+- **Markdown workspace export** — Obsidian-friendly one-way export (`.agent-bridge-markdown/`), explicitly non-authoritative.
+- **Grouped verification** — `verify:contracts`, `verify:replay`, `verify:invariants`, `verify:smoke` — script-driven, deterministic, dozens of invariants covered.
+- **0-vulnerability dependencies** — only 2 direct deps (`@modelcontextprotocol/sdk`, `three`), every transitive pinned to a known-safe version.
 
-## Command surface
+---
 
-Setup:
+## 📦 Installation
+
+### Prerequisites
+- [Node.js 18 or higher](https://nodejs.org/) — `node --version` to check
+- One or more AI CLIs:
+  - [Claude Code](https://claude.ai/code)
+  - [Gemini CLI](https://github.com/google-gemini/gemini-cli)
+  - [Codex CLI](https://github.com/openai/codex)
+
+### Init (auto-detect everything installed)
 
 ```bash
+cd your-project
 npx let-them-talk init
-npx let-them-talk init --claude
-npx let-them-talk init --gemini
-npx let-them-talk init --codex
-npx let-them-talk init --all
-npx let-them-talk init --ollama
-npx let-them-talk init --template <name>
 ```
 
-After init, prefer the local launcher that was written into the project:
+### Init for a specific CLI
 
 ```bash
-node .agent-bridge/launch.js
-node .agent-bridge/launch.js --lan
-node .agent-bridge/launch.js status
-node .agent-bridge/launch.js msg <agent> <text>
-node .agent-bridge/launch.js reset
+npx let-them-talk init --claude     # Claude Code only
+npx let-them-talk init --gemini     # Gemini CLI only
+npx let-them-talk init --codex      # Codex CLI only
+npx let-them-talk init --all        # All three
+npx let-them-talk init --ollama     # Add a local Ollama bridge
 ```
 
-Other packaged CLI helpers:
+### Init with a ready-made template
 
 ```bash
-npx let-them-talk dashboard
-npx let-them-talk status
-npx let-them-talk templates
-npx let-them-talk uninstall
-npx let-them-talk help
+npx let-them-talk init --template pair      # 2-agent chat
+npx let-them-talk init --template team      # Coordinator + Researcher + Coder
+npx let-them-talk init --template review    # Author + Reviewer code-review pair
+npx let-them-talk init --template debate    # Pro + Con structured debate
+npx let-them-talk init --template managed   # Manager + Designer + Coder + Tester
 ```
 
-## Template inventory
+### What init writes (all merge-safe)
 
-Agent templates shipped today:
+- `.mcp.json` — Claude Code MCP config
+- `.gemini/settings.json` — Gemini CLI MCP config
+- `.codex/config.toml` — Codex CLI MCP config
+- `AGENTS.md` / `CLAUDE.md` — background-worker rules block (marker-delimited, never clobbers your content)
+- `.agent-bridge/launch.js` — local launcher (no re-download needed)
+- `.gitignore` — adds sensible entries
 
-- `pair`
-- `team`
-- `review`
-- `debate`
-- `managed`
+All existing configs are preserved — agent-bridge is added alongside your other MCP servers, with `.backup` files created before any edit.
 
-Conversation templates shipped today:
+### Launch the dashboard
 
-- `autonomous-feature`
-- `code-review`
-- `debug-squad`
-- `feature-build`
-- `research-write`
+```bash
+node .agent-bridge/launch.js              # localhost:3000
+node .agent-bridge/launch.js --lan        # also listen on LAN (phone/tablet)
+node .agent-bridge/launch.js status       # CLI status snapshot
+node .agent-bridge/launch.js msg <agent>  # send a message from the terminal
+node .agent-bridge/launch.js migrate      # backfill canonical events from legacy projects
+```
 
-## Runtime descriptors and provider capabilities
+---
 
-API-backed agents persist an explicit runtime descriptor with these fields:
+## 🎬 The 60-second demo
 
-- `runtime_type`
-- `provider_id`
-- `model_id`
-- `capabilities`
+```bash
+# In project folder
+npx let-them-talk init --template team
+node .agent-bridge/launch.js
+```
 
-Supported capability tokens today:
+Open three terminals. The `templates` output prints the exact prompt to paste into each:
 
-- `chat`
-- `vision`
-- `image_generation`
-- `video_generation`
-- `texture_generation`
+- **Terminal 1 (Coordinator):** receives the user's request, breaks it into tasks, delegates to Researcher and Coder.
+- **Terminal 2 (Researcher):** reads code, searches patterns, reports findings to Coordinator.
+- **Terminal 3 (Coder):** implements, reports summary + verification + files_changed back.
 
-Legacy `provider`, `provider_color`, and `bot_capability` fields remain compatibility projections over that descriptor.
+From the dashboard Messages tab, send the Coordinator a task. Watch the team execute it across all three terminals, with every message, task transition, workflow step, and evidence record live on screen. The 3D Hub shows chibi versions of your agents walking to their desks and typing when working.
 
-## Markdown workspace export
+---
 
-```bash
-npm run export:markdown-workspace
+## 🎛️ Dashboard tour
+
+| Tab | What it does |
+|---|---|
+| **3D Hub** | Live chibi-style visualization of your team. Per-project worlds, buildings, behaviors. |
+| **Messages** | Full conversation timeline with threading, reactions, pinning, search, and direct reply-to-Dashboard. |
+| **Tasks** | Kanban of all tasks across the branch. Drag to change status. Evidence-backed completion. **Clear All Tasks** button for cleanup. |
+| **Workspaces** | Per-agent scratchpad. Other agents can read, only you can write. 50 keys, 100 KB values. |
+| **Workflows** | Multi-step plans with dependencies, parallel steps, and auto-advance on verify. |
+| **Graph** | Agent/task/dependency network view. |
+| **Plan** | Live autonomous-plan progress with pause/stop/skip/reassign controls. |
+| **Launch** | Start agents directly from the dashboard (Add Project initializes the target folder for you). |
+| **Rules** | Project-wide rules injected into every agent's guide. |
+| **Stats** | Messages, tasks, completion rates, per-agent activity. |
+| **Services** | Status of configured providers and API keys. |
+| **Docs** | Shipped architecture + usage docs, searchable. |
+
+The dashboard also supports:
+- Saved named layouts
+- Omnibox / command palette on the search bar
+- Per-project branch switching and Clear Messages (canonical-aware)
+- **Reinstall Providers** — rewrites per-project MCP configs and refreshes the `AGENTS.md` rule block without touching your other content
+
+---
+
+## 📐 Core concepts
+
+### Runtime
+
+- **Canonical truth** lives in an event-backed runtime under `.agent-bridge/runtime/`.
+- Legacy flat `.json` / `.jsonl` files in `.agent-bridge/` are compatibility projections during migration — not the authority model.
+- All mutations go through a shared canonical facade (`state/canonical.js`). The dashboard is a client of the broker, not a second writer.
+
+### Branches
+
+Branches are **full execution contexts**, not just message logs. A branch switch replaces the migrated branch-local view all at once:
+- messages and history
+- delivery and read state
+- conversation control and non-general channels
+- tasks and workflows
+- workspaces
+- sessions and evidence
+- governance: decisions, KB, reviews, dependencies, votes, rules, progress
+
+Branch creation snapshots the source branch at the fork point. Branch-local changes never bleed into `main` until explicitly advanced.
+
+### Sessions + evidence
+
+Sessions are branch-scoped records of one agent's work on one branch. Rejoining the same branch resumes that branch-scoped context. Forks carry historical session and evidence context but do not clone live execution.
+
+Completion is authoritative only when structured evidence is recorded:
+- `summary`
+- `verification`
+- `files_changed`
+- `confidence` (0–100)
+- `recorded_at`
+- `recorded_by_session`
+
+Anything less is a conversational "done", not a runtime "done".
+
+### Providers + capabilities
+
+Every agent has an explicit runtime descriptor:
+- `runtime_type` (CLI / API / custom)
+- `provider_id` (Claude / Codex / Gemini / Ollama / ...)
+- `model_id`
+- `capabilities` — tokens like `chat`, `vision`, `image_generation`, `video_generation`, `texture_generation`
+
+Coordinators can route work by capability instead of by heuristic — `get_work` and task assignment both respect declared capabilities.
+
+### Autonomy loop
+
+Instead of babysitting the chat:
+
+```
+Coordinator → start_plan(name, steps, assignees)
+        ↓
+Each agent → get_work() → do work → verify_and_advance() → get_work() → ...
 ```
 
-Default export root is `<project>/.agent-bridge-markdown/`. Exported files declare `authoritative: false` in frontmatter. The export is one-way only. There is no markdown write-back, watcher loop, or import path in the current runtime.
+- **`get_work`** picks the highest-priority item from: assigned workflow step, claimable task, open review, help request, blocked dependency, and more.
+- **`verify_and_advance`** self-verifies with evidence. ≥ 70 confidence auto-advances. 40–69 advances with a flag. < 40 broadcasts a help request.
+- **`retry_with_improvement`** handles failures. 3 failed retries auto-escalate to the team. Skill accumulation is stored in the KB for everyone.
+- **Watchdog** detects idle agents, stuck steps, and dead owners. Can rotate ownership within bounds.
+
+---
+
+## 🧩 Agent templates
 
-When a source surface is still compatibility-shared or main-only, export stays truthful by emitting it only for `main` or omitting it. The exporter does not fabricate non-main branch copies from shared state.
+### Agent templates (role prompts)
 
-## Verification
+| Template | Agents | Use when |
+|---|---|---|
+| `pair` | A, B | Two-agent brainstorm or Q&A |
+| `team` | Coordinator, Researcher, Coder | Feature work with research + implementation |
+| `review` | Author, Reviewer | Code-review loop |
+| `debate` | Pro, Con | Explore tradeoffs / architecture decisions |
+| `managed` | Manager, Designer, Coder, Tester | 3+ agents with structured turn-taking |
 
-From this package directory:
+### Conversation templates (workflow skeletons)
+
+| Template | Purpose |
+|---|---|
+| `feature-build` | End-to-end feature: research → design → implement → test |
+| `code-review` | Structured code review with evidence |
+| `debug-squad` | Coordinated bug triage and fix |
+| `research-write` | Research → synthesize → document |
+| `autonomous-feature` | Fully autonomous multi-agent feature build |
+
+List, show, or apply templates:
 
 ```bash
-npm test
+npx let-them-talk templates                         # list all
+npx let-them-talk init --template team              # scaffold a team
 ```
 
-Grouped package commands:
+---
+
+## 🧪 Verification
+
+Script-driven, deterministic, no flake:
 
 ```bash
-npm run verify
-npm run verify:contracts
-npm run verify:replay
-npm run verify:invariants
-npm run verify:smoke
+npm test                     # delegates to verify
+npm run verify               # full suite
+npm run verify:contracts     # runtime + schema + branches + markdown
+npm run verify:replay        # event replay (healthy + clean + negative)
+npm run verify:invariants    # dashboard, capabilities, parity, sessions, evidence, autonomy, hooks
+npm run verify:smoke         # representative subset
 ```
 
-Current grouped coverage:
+The verify suite doesn't claim to cover every provider or runtime matrix, and does not include browser automation. But every shipped invariant is script-enforced on every release.
+
+---
+
+## 🔐 Security
+
+- **Dashboard binds to `127.0.0.1` by default.** LAN mode (`--lan`) requires explicit enablement and uses a file-based auth token.
+- **Rate-limited** API endpoints on non-localhost requests.
+- **No telemetry, no cloud.** Everything runs locally.
+- **0 known vulnerabilities** in the shipped tarball as of v5.4.1.
+- **Sensitive-path blocks** on file-share: `.env`, `.pem`, `.key`, `.lan-token`, `mcp.json`, and the agent-bridge data directory cannot be shared.
+- See [`SECURITY.md`](SECURITY.md) for the disclosure policy.
+
+---
 
-- `verify:contracts` checks the runtime contract, canonical event schema, branch semantics, and markdown workspace contract.
-- `verify:replay` checks healthy and clean replay plus expected-failure negative replay scenarios.
-- `verify:invariants` checks authority routing, dashboard control plane behavior, performance and indexing, provider capabilities, API-agent parity, dashboard semantic-gap coverage, migration hardening, branch isolation, session lifecycle, evidence-backed completion, session-aware context, autonomy v2, advisory contracts, managed-team integration, lifecycle hooks, and markdown workspace export and safety.
-- `verify:smoke` runs a representative subset, including the dashboard semantic-gap check.
+## 📚 Architecture
 
-Coverage is still partial. The suite does not claim a full provider or runtime matrix, and it does not include browser automation.
+Source-of-truth docs:
 
-## Security and license
+- [`docs/architecture/runtime-contract.md`](docs/architecture/runtime-contract.md)
+- [`docs/architecture/branch-semantics.md`](docs/architecture/branch-semantics.md)
+- [`docs/architecture/canonical-event-schema.md`](docs/architecture/canonical-event-schema.md)
+- [`docs/architecture/markdown-workspace.md`](docs/architecture/markdown-workspace.md)
+- [`docs/architecture/runtime-migration-hardening.md`](docs/architecture/runtime-migration-hardening.md)
 
-Security notes live in `SECURITY.md`.
+---
 
-License: [Business Source License 1.1](LICENSE)
+## 💬 Community
+
+- [Discord](https://discord.gg/6Y9YgkFNJP) — questions, show-and-tell, feedback
+- [GitHub Issues](https://github.com/Dekelelz/let-them-talk/issues) — bugs and feature requests
+- [Website](https://talk.unrealai.studio) — project home
+
+---
+
+## 📄 License
+
+[Business Source License 1.1](LICENSE). See the license file for usage terms.
+
+---
+
+<p align="center">
+  <sub>Built for humans who want their AI agents to work as a team.</sub>
+</p>

package/USAGE.md

@@ -1,6 +1,6 @@
 <!-- Generated from ../USAGE.md by scripts/sync-packaged-docs.js for published package consumers. -->
 
-# Let Them Talk Usage Guide v5.4.0
+# Let Them Talk Usage Guide v5.4.1
 
 This guide is the short operator view of the current runtime. For normative architecture details, use the docs under `docs/architecture/`.
 

package/cli.js

@@ -9,7 +9,7 @@ const { createCanonicalState } = require('./state/canonical');
 
 function printUsage() {
   console.log(`
-  Let Them Talk — Agent Bridge v5.4.0
+  Let Them Talk — Agent Bridge v5.4.1
   MCP message broker for inter-agent communication
   Supports: Claude Code, Gemini CLI, Codex CLI, Ollama
 

package/dashboard.js

@@ -202,7 +202,45 @@ function isRecentlyListening(info) {
   return Date.now() - last < LISTEN_RECENCY_GRACE_MS;
 }
 
+// Virtual-agent helpers. "Dashboard" and "Owner" represent the operator UI,
+// not a real CLI process. Writing them to agents.json lets list_agents and
+// list_channels show them as first-class recipients, so agents can DM the
+// operator via send_message(to="Dashboard") without confusion.
+const VIRTUAL_AGENT_NAMES = ['Dashboard', 'Owner'];
+function ensureVirtualAgents(projectPath) {
+  try {
+    const dataDir = resolveDataDir(projectPath);
+    if (!fs.existsSync(dataDir)) return;
+    const agentsFile = path.join(dataDir, 'agents.json');
+    let agents = {};
+    if (fs.existsSync(agentsFile)) {
+      try { agents = JSON.parse(fs.readFileSync(agentsFile, 'utf8')); } catch {}
+    }
+    const now = new Date().toISOString();
+    let changed = false;
+    for (const name of VIRTUAL_AGENT_NAMES) {
+      if (!agents[name] || !agents[name].is_virtual) {
+        agents[name] = {
+          pid: -1,
+          is_virtual: true,
+          virtual_type: 'owner',
+          timestamp: (agents[name] && agents[name].timestamp) || now,
+          last_activity: now,
+          last_listened_at: now,
+          provider: 'Dashboard',
+          branch: 'main',
+        };
+        changed = true;
+      }
+    }
+    if (changed) {
+      fs.writeFileSync(agentsFile, JSON.stringify(agents, null, 2) + '\n');
+    }
+  } catch {} // best-effort — if agents.json is locked, we'll try again next request
+}
+
 function isPidAlive(pid, lastActivity) {
+  if (pid === -1) return true; // virtual agents (Dashboard, Owner) — always alive
   const STALE_THRESHOLD = 60000; // 60s — if heartbeat updated within this, agent is alive
 
   // PRIORITY 1: Trust heartbeat freshness over PID status
@@ -270,6 +308,9 @@ function apiChannels(query) {
 
 function apiAgents(query) {
   const projectPath = query.get('project') || null;
+  // Make sure the operator virtual agents (Dashboard, Owner) exist so agents
+  // querying list_agents over MCP see them as valid DM recipients.
+  ensureVirtualAgents(projectPath);
   const canonicalState = getCanonicalState(projectPath);
   const agents = canonicalState.listAgents();
   const profiles = canonicalState.listProfiles();
@@ -3417,7 +3458,7 @@ server.listen(PORT, LAN_MODE ? '0.0.0.0' : '127.0.0.1', () => {
   const dataDir = resolveDataDir();
   const lanIP = getLanIP();
   console.log('');
-  console.log('  Let Them Talk - Agent Bridge Dashboard v5.4.0');
+  console.log('  Let Them Talk - Agent Bridge Dashboard v5.4.1');
   console.log('  ============================================');
   console.log('  Dashboard:  http://localhost:' + PORT);
   if (LAN_MODE && lanIP) {

package/office/index.js

@@ -28,13 +28,13 @@ function getCityMods() {
   }).catch(function(e) { console.warn('City modules failed:', e); });
   return _cityMods;
 }
-function isDriving() { return _cityMods && _cityMods.vehicle && _cityMods.vehicle.isDriving(); }
-function isConnected() { return false; }
-
-function scopedOfficeApiUrl(path, options) {
-  if (typeof window.scopedApiUrl === 'function') return window.scopedApiUrl(path, null, options);
-  return path;
-}
+function isDriving() { return _cityMods && _cityMods.vehicle && _cityMods.vehicle.isDriving(); }
+function isConnected() { return false; }
+
+function scopedOfficeApiUrl(path, options) {
+  if (typeof window.scopedApiUrl === 'function') return window.scopedApiUrl(path, null, options);
+  return path;
+}
 
 // Expose createCharacter + resolveAppearance for the character designer (Phase 3)
 export { createCharacter } from './character.js';
@@ -319,29 +319,29 @@ function executeCommand(agentName, action) {
       });
       break;
 
-    case 'send_message':
-      showInputOverlay('Send message to ' + agentName + ':', 'Type your message...', function(msg) {
-        if (msg && msg.trim()) {
-          showBubble(agent, 'Message incoming...');
-          fetch(scopedOfficeApiUrl('/api/inject'), {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json', 'X-LTT-Request': '1' },
-            body: JSON.stringify({ to: agentName, content: msg.trim() })
-          }).then(function() { showBubble(agent, 'Got it!'); });
-        }
+    case 'send_message':
+      showInputOverlay('Send message to ' + agentName + ':', 'Type your message...', function(msg) {
+        if (msg && msg.trim()) {
+          showBubble(agent, 'Message incoming...');
+          fetch(scopedOfficeApiUrl('/api/inject'), {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', 'X-LTT-Request': '1' },
+            body: JSON.stringify({ to: agentName, content: msg.trim() })
+          }).then(function() { showBubble(agent, 'Got it!'); });
+        }
       });
       break;
 
-    case 'assign_task':
-      showInputOverlay('New task for ' + agentName + ':', 'Task title...', function(title) {
-        if (title && title.trim()) {
-          showBubble(agent, 'New task assigned!');
-          fetch(scopedOfficeApiUrl('/api/tasks'), {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json', 'X-LTT-Request': '1' },
-            body: JSON.stringify({ title: title.trim(), assignee: agentName, status: 'pending' })
-          });
-        }
+    case 'assign_task':
+      showInputOverlay('New task for ' + agentName + ':', 'Task title...', function(title) {
+        if (title && title.trim()) {
+          showBubble(agent, 'New task assigned!');
+          fetch(scopedOfficeApiUrl('/api/tasks'), {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', 'X-LTT-Request': '1' },
+            body: JSON.stringify({ title: title.trim(), assignee: agentName, status: 'pending' })
+          });
+        }
       });
       break;
 
@@ -355,13 +355,13 @@ function executeCommand(agentName, action) {
       }
       break;
 
-    case 'nudge':
-      showBubble(agent, 'Hey! Wake up!');
-      fetch(scopedOfficeApiUrl('/api/inject'), {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json', 'X-LTT-Request': '1' },
-        body: JSON.stringify({ to: agentName, content: 'Hey ' + agentName + ', the user is waiting for you. Please check for new messages and continue your work.' })
-      });
+    case 'nudge':
+      showBubble(agent, 'Hey! Wake up!');
+      fetch(scopedOfficeApiUrl('/api/inject'), {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'X-LTT-Request': '1' },
+        body: JSON.stringify({ to: agentName, content: 'Hey ' + agentName + ', the user is waiting for you. Please check for new messages and continue your work.' })
+      });
       break;
 
     case 'edit_profile':
@@ -957,19 +957,20 @@ window.onPlayerSit = function(deskIdx) {
   var iframeWrap = document.createElement('div');
   iframeWrap.style.cssText = 'flex:1;position:relative;';
 
-  // Dashboard iframe
+  // Dashboard iframe. clipboard-write only — the iframe needs to copy agent
+  // prompts into the user's clipboard, it never needs to read from it.
   var dashIframe = document.createElement('iframe');
   dashIframe.id = 'mon-iframe-dashboard';
   dashIframe.src = window.location.origin || 'http://localhost:3000';
   dashIframe.style.cssText = 'position:absolute;top:0;left:0;width:100%;height:100%;border:none;background:#0d1117;';
-  dashIframe.allow = 'clipboard-read; clipboard-write';
+  dashIframe.allow = 'clipboard-write';
   iframeWrap.appendChild(dashIframe);
 
-  // ComfyUI iframe (hidden initially)
+  // ComfyUI iframe (hidden initially). Same write-only clipboard scope.
   var comfyIframe = document.createElement('iframe');
   comfyIframe.id = 'mon-iframe-comfyui';
   comfyIframe.style.cssText = 'position:absolute;top:0;left:0;width:100%;height:100%;border:none;background:#1a1a2e;display:none;';
-  comfyIframe.allow = 'clipboard-read; clipboard-write';
+  comfyIframe.allow = 'clipboard-write';
   // Don't load ComfyUI until tab is clicked (saves resources)
   iframeWrap.appendChild(comfyIframe);
 
@@ -995,9 +996,11 @@ window.onPlayerSit = function(deskIdx) {
       if (dIframe) dIframe.style.display = 'none';
       if (cIframe) {
         cIframe.style.display = 'block';
-        // Lazy-load ComfyUI on first switch
+        // Lazy-load ComfyUI on first switch. URL is configurable via
+        // window.COMFYUI_URL (set it from the dashboard or page) so users
+        // on non-default ports or remote ComfyUI hosts can override.
         if (!cIframe.src || cIframe.src === 'about:blank' || cIframe.src === '') {
-          cIframe.src = 'http://127.0.0.1:8188';
+          cIframe.src = (typeof window !== 'undefined' && window.COMFYUI_URL) || 'http://127.0.0.1:8188';
         }
       }
       if (dTab) { dTab.style.color = '#8892b0'; dTab.style.borderBottomColor = 'transparent'; }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "let-them-talk",
-  "version": "5.4.0",
+  "version": "5.4.1",
   "description": "MCP message broker + web dashboard for inter-agent communication. Let AI CLI agents talk to each other.",
   "main": "server.js",
   "bin": {

package/server.js

@@ -567,11 +567,34 @@ function withFileLock(filePath, fn) {
   try { return fn(); } finally { try { fs.unlinkSync(lockPath); } catch {} }
 }
 
+// Virtual operator agents. "Dashboard" and "Owner" represent the operator UI,
+// not a CLI process. Surfacing them here ensures list_agents, broadcast filters,
+// and DM-routing in the broker all agree the operator is a real recipient.
+const VIRTUAL_AGENT_NAMES = ['Dashboard', 'Owner'];
+function _mergeVirtualAgents(agents) {
+  const now = new Date().toISOString();
+  for (const name of VIRTUAL_AGENT_NAMES) {
+    if (!agents[name] || !agents[name].is_virtual) {
+      agents[name] = {
+        pid: -1,
+        is_virtual: true,
+        virtual_type: 'owner',
+        timestamp: (agents[name] && agents[name].timestamp) || now,
+        last_activity: now,
+        last_listened_at: now,
+        provider: 'Dashboard',
+        branch: (agents[name] && agents[name].branch) || 'main',
+      };
+    }
+  }
+  return agents;
+}
+
 function getAgents() {
   return cachedRead('agents', () => {
-    if (!fs.existsSync(AGENTS_FILE)) return {};
+    if (!fs.existsSync(AGENTS_FILE)) return _mergeVirtualAgents({});
     let agents;
-    try { agents = JSON.parse(fs.readFileSync(AGENTS_FILE, 'utf8')); } catch { return {}; }
+    try { agents = JSON.parse(fs.readFileSync(AGENTS_FILE, 'utf8')); } catch { return _mergeVirtualAgents({}); }
     // Scale fix: merge per-agent heartbeat files for live activity data
     try {
       const files = fs.readdirSync(DATA_DIR).filter(f => f.startsWith('heartbeat-') && f.endsWith('.json'));
@@ -586,7 +609,7 @@ function getAgents() {
         }
       }
     } catch {}
-    return agents;
+    return _mergeVirtualAgents(agents);
   }, 1500);
 }
 
@@ -616,6 +639,10 @@ function getAcks(branch = currentBranch) {
 // Cache for isPidAlive results — avoids redundant process.kill calls at 100-agent scale
 const _pidAliveCache = {};
 function isPidAlive(pid, lastActivity) {
+  // Virtual agents (Dashboard, Owner) use pid === -1 and are always alive.
+  // They represent the operator UI; liveness is implicit while the broker runs.
+  if (pid === -1) return true;
+
   // Cache with 5s TTL — PID status doesn't change faster than heartbeats
   const cacheKey = `${pid}_${lastActivity}`;
   const cached = _pidAliveCache[cacheKey];
@@ -2765,7 +2792,11 @@ function toolBroadcast(content) {
   if (sizeErr) return sizeErr;
 
   const agents = getAgents();
-  const otherAgents = Object.keys(agents).filter(n => n !== registeredName);
+  // Exclude self and virtual agents (Dashboard, Owner) from broadcast recipients.
+  // Virtual agents represent the operator UI and read from the shared message log
+  // directly; they don't need per-recipient DM copies. Group-mode __group__ writes
+  // are still visible to the UI via /api/history.
+  const otherAgents = Object.keys(agents).filter(n => n !== registeredName && !agents[n].is_virtual);
 
   if (otherAgents.length === 0) {
     return { error: 'No other agents registered' };
@@ -8391,7 +8422,7 @@ function toolToggleRule(ruleId) {
 // --- MCP Server setup ---
 
 const server = new Server(
-  { name: 'agent-bridge', version: '5.4.0' },
+  { name: 'agent-bridge', version: '5.4.1' },
   { capabilities: { tools: {} } }
 );
 
@@ -9531,7 +9562,7 @@ async function main() {
   try {
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    console.error('Agent Bridge MCP server v5.4.0 running (66 tools)');
+    console.error('Agent Bridge MCP server v5.4.1 running (66 tools)');
   } catch (e) {
     console.error('ERROR: MCP server failed to start: ' + e.message);
     console.error('Fix: Run "npx let-them-talk doctor" to check your setup.');