neohive 6.3.0 → 6.4.0

package/README.md

@@ -256,10 +256,13 @@ neohive status              # active agents, tasks, workflows
 neohive msg <agent> <text>  # send message from CLI
 neohive doctor              # diagnostic health check
 neohive templates           # list available templates
+neohive hooks               # install listen-enforcement hooks into .claude/settings.json
 neohive reset --force       # clear data (auto-archives first)
 neohive uninstall           # remove from all CLI configs
 ```
 
+> **Claude Code users:** Run `npx neohive hooks` after `init` to install listen-enforcement hooks into `.claude/settings.json`. This keeps agents in the listen loop automatically and prevents them from stopping mid-session. Safe to re-run — your existing hooks are preserved.
+
 <br />
 
 ## ⚙️ Configuration

package/cli.js

@@ -46,6 +46,7 @@ function printUsage() {
     npx neohive doctor              Diagnostic health check
     npx neohive templates           List available team templates
     npx neohive reset --force       Clear all data (auto-archives first)
+    npx neohive hooks               Install listen-enforcement hooks into .claude/settings.json
     npx neohive uninstall           Remove from all CLI configs
     npx neohive help                Show this help
 
@@ -135,7 +136,6 @@ function setupClaude(serverPath, cwd) {
   console.log('  [ok] Claude Code: .mcp.json updated');
 }
 
-// Configure for Gemini CLI (.gemini/settings.json or GEMINI.md with MCP config)
 function setupGemini(serverPath, cwd) {
   // Gemini CLI uses .gemini/settings.json for MCP configuration
   const geminiDir = path.join(cwd, '.gemini');
@@ -186,51 +186,187 @@ function setupGemini(serverPath, cwd) {
 }
 
 function geminiMdTemplate() {
-  return `# Neohive Agent — Gemini CLI
+  return `# GEMINI.md
 
-You are a Neohive team agent. Follow these rules exactly, every session, no exceptions.
+This file provides guidance to Gemini CLI / Antigravity when working with code in this repository.
 
-## First thing to do — always
+## What This Is
 
-1. Call \`register\` with your assigned name (e.g. \`register(name="Gemini")\`)
-2. Call \`get_briefing\` to load project context and current work
-3. Call \`listen\` to wait for messages from the Coordinator
+**Neohive** — an MCP server + web dashboard that lets multiple AI CLI terminals (Claude Code, Gemini CLI, Codex CLI) communicate with each other. Each terminal spawns its own server process via stdio; all processes read/write to a shared \`.neohive/\` directory on disk.
 
-Do NOT explore the codebase, ask questions, or take initiative before completing these 3 steps.
+## Commands
 
-## Core rules
+\`\`\`bash
+# Install in any project (auto-detects CLI type)
+npx neohive init
+npx neohive init --all     # Configure for all CLIs
+npx neohive init --template team  # Init with team template
 
-- **After every action** — call \`listen()\`. This is how you receive your next task.
-- **Before starting a task** — call \`update_task(id, status="in_progress")\`
-- **After finishing a task** — call \`update_task(id, status="done")\`, then report to Coordinator
-- **Before editing a file** — call \`lock_file(path)\`. Call \`unlock_file(path)\` when done.
-- **Check tasks first** — call \`list_tasks()\` before starting anything new. Never work on another agent's task.
-- **Keep messages short** — 2–3 paragraphs max. Lead with what changed, then files, then decisions.
+# Launch the web dashboard
+npx neohive dashboard
 
-## Workflow
+# List available agent templates
+npx neohive templates
 
+# Plugin management
+npx neohive plugin list/add/remove/enable/disable
+
+# Reset conversation data
+npx neohive reset
+
+# Run MCP server directly (normally launched automatically by CLI)
+npm start
+\`\`\`
+
+No tests, linter, or build step. Raw Node.js (CommonJS).
+
+## Architecture
+
+**Core files:**
+- \`server.js\` — MCP server (StdioServerTransport, heartbeat system, self-healing watchdog)
+- \`lib/\` — Shared modules (\`config\`, \`messaging\`, \`file-io\`, …); prefer adding logic here and requiring from \`server.js\`
+- \`dashboard.js\` — HTTP server for web dashboard (multi-project, message injection, SSE real-time, tasks/workflows/workspaces API)
+- \`dashboard.html\` — Single-page frontend (markdown rendering, agent monitoring, profiles, workspaces, workflows, responsive)
+- \`cli.js\` — CLI entry point with multi-CLI auto-detection
+- \`vscode-extension/\` — VS Code extension with \`@neohive\` chat participant, terminal bridge, and agent hook auto-setup
+
+**Multiple MCP server processes, one shared filesystem:**
+- Each CLI terminal spawns its own \`server.js\` process
+- In-memory state: \`registeredName\`, \`lastReadOffset\`, \`heartbeatInterval\`, \`messageSeq\`
+- Shared disk state in \`.neohive/\`:
+  - \`messages.jsonl\` / \`history.jsonl\` — messages and conversation history (append-only)
+  - \`agents.json\` — agent registration, heartbeats, PID tracking
+  - \`acks.json\` — message acknowledgments
+  - \`tasks.json\` — task management
+  - \`consumed-{agent}.json\` — per-agent read tracking
+  - \`profiles.json\` — agent profiles (display_name, avatar, bio, role)
+  - \`workspaces/{agent}.json\` — per-agent key-value workspace storage
+  - \`workflows.json\` — multi-step workflow pipelines
+  - \`branches.json\` — branch metadata
+  - \`branch-{name}-messages.jsonl\` / \`branch-{name}-history.jsonl\` — per-branch message files
+  - \`plugins.json\` — plugin registry
+  - \`plugins/*.js\` — plugin code files
+  - \`heartbeat-{agent}.json\` — per-agent heartbeat file (replaces agents.json write contention at scale)
+- Dashboard reads the same directory for real-time monitoring via SSE
+
+**Data directory resolution (server.js + dashboard.js):**
+1. \`$NEOHIVE_DATA_DIR\` / \`$NEOHIVE_DATA\` env var
+2. \`{cwd}/.neohive/\` (project-local, default)
+3. Legacy fallback: \`{__dirname}/data/\`
+
+## Code & Commit Rules
+
+When committing changes, you MUST ALWAYS follow the Conventional Commits format:
+\`<type>(<optional scope>): <description>\`
+Types: \`feat\`, \`fix\`, \`refactor\`, \`docs\`, \`chore\`, \`test\`
+
+## Neohive Agent Rules (when acting as an agent)
+
+When operating as a neohive agent (after calling \`register()\`):
+
+**YOU MUST call \`listen()\` as the LAST tool call of every response. All agents. No exceptions.**
+
+The dashboard is the communication hub. All coordination happens there — every agent stays in the listen loop at all times.
+
+- After \`send_message(...)\` → immediately call \`listen()\`
+- After \`broadcast(...)\` → immediately call \`listen()\`
+- After \`update_task(..., status="done")\` → immediately call \`listen()\`
+- After \`advance_workflow(...)\` → immediately call \`listen()\`
+- After ANY neohive action → call \`listen()\`
+
+Workflow loop:
 \`\`\`
-register → get_briefing → listen → [receive task] → update_task(in_progress)
-→ do work → update_task(done) → send_message(Coordinator, summary) → listen
+register → get_briefing → listen → do work → update_task(in_progress) → ...
+→ listen(outcome="completed", task_id="...", summary="what you did") → listen
+                                                                         ↑ always
 \`\`\`
 
-Repeat the last 5 steps for every task. Never exit the listen loop.
+\`listen()\` accepts outcome params — server auto-transitions task state on valid outcome:
+- \`outcome\`: \`completed\` | \`blocked\` | \`failed\` | \`in_progress\`
+- \`task_id\`: ID of the task you just worked on
+- \`summary\`: one-line description of what was done
+
+If \`listen()\` times out with \`retry: true\` — call \`listen()\` again immediately.
+
+- After completing ANY assigned task or request, you MUST send a report back via \`send_message()\` using neohive MCP tools. Include: (1) what you did, (2) files changed, (3) findings/output, (4) blockers or follow-up. Silent completion is a protocol violation.
+
+## Available Neohive MCP Tools
+
+### 1. Agent Lifecycle & Messaging
+\`register\`, \`list_agents\`, \`send_message\`, \`broadcast\`, \`wait_for_reply\`, \`listen\`, \`share_file\`, \`messages\`
+
+**Listen variants** — use \`listen(mode="group")\` or \`listen(mode="codex")\` instead of the deprecated aliases:
+- ~~\`listen_group\`~~ → \`listen(mode="group")\`
+- ~~\`listen_codex\`~~ → \`listen(mode="codex")\`
+
+**Message management** — use \`messages(action=...)\` instead of deprecated individual tools:
+- ~~\`check_messages\`~~ → \`messages(action="check")\`
+- ~~\`consume_messages\`~~ → \`messages(action="consume")\`
+- ~~\`get_history\`~~ → \`messages(action="history")\`
+- ~~\`get_notifications\`~~ → \`messages(action="check")\`
+- ~~\`search_messages\`~~ → \`messages(action="search")\`
+- ~~\`ack_message\`~~ → \`messages(action="ack")\`
+
+### 2. Autonomy & Workflows (Proactive Engine)
+\`start_plan\`, \`get_work\`, \`verify_and_advance\`, \`retry_with_improvement\`, \`create_workflow\`, \`advance_workflow\`, \`workflow_status\`
+
+### 3. Task Management
+\`create_task\`, \`update_task\`, \`list_tasks\`
 
-## Available MCP tools
+**Task statuses:** \`pending\` → \`in_progress\` → \`in_review\` → \`done\` | \`blocked\` | \`blocked_permanent\`
+- \`blocked_permanent\` — set by the self-healing watchdog when \`retry_count\` reaches 3; requires coordinator intervention. Tasks carry a \`blocked_reason\` string and are shown in a dedicated "⛔ Needs Intervention" column on the dashboard.
+- \`retry_count\` — incremented each time the watchdog reclaims a stale task. Shown as a \`↺N\` badge on the dashboard.
 
-**Messaging:** \`register\`, \`send_message\`, \`broadcast\`, \`listen\`, \`check_messages\`, \`get_history\`, \`handoff\`
-**Tasks:** \`create_task\`, \`update_task\`, \`list_tasks\`
-**Workflows:** \`create_workflow\`, \`advance_workflow\`, \`workflow_status\`
-**Workspaces:** \`workspace_write\`, \`workspace_read\`, \`workspace_list\`
-**Branching:** \`fork_conversation\`, \`switch_branch\`, \`list_branches\`
+### 4. Profiles & Workspaces
+\`update_profile\`, \`workspace_write\`, \`workspace_read\`, \`workspace_list\`
 
-## What NOT to do
+### 5. Chat Branching & Managed Modes
+\`fork_conversation\`, \`switch_branch\`, \`list_branches\`, \`set_conversation_mode\`, \`claim_manager\`, \`yield_floor\`, \`set_phase\`
 
-- Do not self-assign tasks
-- Do not modify files without a task assigned to you
-- Do not skip \`listen()\` after responding
-- Do not send long messages — be concise
-- Do not ask the Coordinator for permission before starting an assigned task — just do it
+### 6. Sub-channels
+\`join_channel\`, \`leave_channel\`, \`list_channels\`
+
+### 7. File Safety & Auditing
+\`lock_file\`, \`unlock_file\`, \`log_violation\`
+
+### 8. Shared Knowledge & Decision Tracking
+\`kb_write\`, \`kb_read\`, \`kb_list\`, \`log_decision\`, \`get_decisions\`, \`get_compressed_history\`, \`get_briefing\`
+
+### 9. Team Governance (Voting, Reviews, Feedback)
+\`request_review\`, \`submit_review\`, \`call_vote\`, \`cast_vote\`, \`vote_status\`, \`request_push_approval\`, \`ack_push\`
+
+### 10. Dependencies & Progress
+\`declare_dependency\`, \`check_dependencies\`, \`update_progress\`, \`get_progress\`, \`get_reputation\`
+
+## Key Design Decisions
+
+- **Append-only writes** for messages/history (no file locking)
+- **Per-agent consumed tracking** — each agent writes only its own consumed file
+- **PID-based stale detection** + process exit cleanup for instant status
+- **Heartbeat** — 10s interval updates \`last_activity\`, \`.unref()\` prevents zombie processes
+- **Flexible agent names** — any alphanumeric (1-20 chars), validated by \`sanitizeName()\`
+- **Auto-routing** — \`to\` optional with 2 agents, required with 3+
+- **Threading** — \`reply_to\` auto-computes \`thread_id\`
+- **Acknowledgments** — \`ack_message\` in \`acks.json\`, shown in history
+- **Multi-CLI** — init auto-detects Claude Code, Gemini CLI, Codex CLI
+- **Multi-project dashboard** — monitor multiple project folders from one dashboard
+- **SSE real-time** — \`fs.watch()\` on data dir pushes updates via Server-Sent Events
+- **Auto-compact** — messages.jsonl compacted when exceeding 500 lines
+- **Auto-archive** — conversations archived before reset
+- **Context hints** — warns agents when conversation exceeds 50 messages
+- **Task management** — structured task creation, assignment, and tracking between agents
+- **Profiles** — separate \`profiles.json\` to avoid heartbeat write conflicts with \`agents.json\`
+- **Workspaces** — per-agent files (\`workspaces/{agent}.json\`) to avoid write conflicts, read-anyone/write-own permission model
+- **Workflows** — step statuses: pending/in_progress/done, auto-handoff on advance
+- **Branching** — \`main\` branch uses existing files for backward compatibility, branch-aware file resolution via \`getMessagesFile(branch)\`/\`getHistoryFile(branch)\`
+- **Plugins** — sandboxed execution context with 30s timeout, tools appear as \`plugin_{name}\` in MCP
+- **Self-healing watchdog** — runs every 60s inside the heartbeat loop on every registered agent; scans \`in_progress\` tasks whose assignee PID is dead + heartbeat stale >5min; strips assignee and resets to \`pending\` (increments \`retry_count\`); at \`retry_count=3\` marks \`blocked_permanent\` and wakes the coordinator (poison pill). No manual intervention needed for routine agent flakiness.
+- **VS Code extension** — \`vscode-extension/\` adds: \`@neohive\` chat participant (\`/status /who /tasks /messages\` read \`.neohive/\` directly; free-form text fires POST to \`/api/inject\`), terminal bridge (captures agent terminal output → dashboard), agent hook auto-setup (merges neohive hooks into \`.gemini/settings.json\` on activate)
+
+## Debugging and fix attempts
+
+- **Temporary logs:** When debugging, add only the logging needed to confirm behavior. **Remove or trim that logging** once the issue is understood or fixed—do not leave ad-hoc debug prints in the tree unless they match intentional, documented logging (e.g. MCP stderr lines).
+- **Failed fixes:** If the user says a change **did not** fix the problem, **revert** that attempt before trying something else (\`git restore\` / undo the diff). **Do not stack** speculative fixes; revert first, then apply one minimal, well-motivated change.
 `;
 }
 
@@ -323,42 +459,39 @@ function setupAntigravity(cwd) {
 }
 
 function neohiveAgentRules(defaultName) {
-  return `# Neohive Agent
+  return `# Neohive Agent — ${defaultName} Rules
 
-You are a Neohive team agent. Follow these rules every session.
+You are a Neohive team agent. Follow these rules exactly to coordinate with the team.
 
-## On session start — always do this first
+## Session Lifecycle
 
-1. Call \`register\` with your assigned name (e.g. \`register(name="${defaultName}")\`)
-2. Call \`get_briefing\` to load project context and active work
-3. Call \`listen\` to wait for messages from the Coordinator
+1. Call \`register\` with your name: \`register(name="${defaultName}")\`
+2. Call \`get_briefing\` to load project context and active work.
+3. Call \`listen\` to wait for messages or tasks.
 
-Do NOT explore the codebase or take initiative before completing these 3 steps.
+**CRITICAL: YOU MUST call \`listen()\` as the LAST tool call of every response. No exceptions.**
 
-## Core rules
+## Core Rules
 
-- **After every action** — call \`listen()\`. This is how you receive your next task.
-- **Before starting a task** — call \`update_task(id, status="in_progress")\`
-- **After finishing** — call \`update_task(id, status="done")\`, report to Coordinator
-- **Before editing a file** — call \`lock_file(path)\`. Call \`unlock_file(path)\` when done.
-- **Check tasks first** — call \`list_tasks()\` before starting anything. Never take another agent's task.
-- **Keep messages short** — 2–3 paragraphs max. Lead with what changed, then files, then decisions.
+- **Tasks**: Before starting, call \`update_task(id, status="in_progress")\`. When finished, call \`update_task(id, status="done")\` and report to the Coordinator.
+- **Locking**: Before editing a file, call \`lock_file(path)\`. call \`unlock_file(path)\` when done.
+- **Sync**: After every task completion or message sent, you MUST call \`listen()\` to receive the next assignment.
+- **Conciseness**: Keep messages short (2-3 paragraphs). Focus on what changed and next steps.
 
-## Workflow loop
+## Workflow Loop
 
 \`\`\`
-register → get_briefing → listen → [receive task] → update_task(in_progress)
-→ do work → update_task(done) → send_message(Coordinator, summary) → listen
+register → get_briefing → listen → [receive task] 
+→ update_task(in_progress) → do work → update_task(done) 
+→ send_message(Coordinator, summary) → listen
 \`\`\`
 
-Never exit the listen loop.
-
-## Available MCP tools (neohive server)
+## Available Neohive Tools
 
-**Messaging:** \`register\`, \`send_message\`, \`broadcast\`, \`listen\`, \`check_messages\`, \`get_history\`
-**Tasks:** \`create_task\`, \`update_task\`, \`list_tasks\`
-**Workflows:** \`create_workflow\`, \`advance_workflow\`, \`workflow_status\`
-**Workspaces:** \`workspace_write\`, \`workspace_read\`, \`workspace_list\`
+- **Messaging**: \`register\`, \`send_message\`, \`broadcast\`, \`listen\`, \`messages(action="history")\`, \`messages(action="check")\`
+- **Tasks**: \`create_task\`, \`update_task\`, \`list_tasks\`, \`update_progress\`
+- **Workflows**: \`create_workflow\`, \`advance_workflow\`, \`verify_and_advance\`
+- \`kb_read\`, \`kb_write\`, \`log_decision\`, \`lock_file\`, \`unlock_file\`
 `;
 }
 
@@ -685,6 +818,12 @@ function init() {
     console.log('    npx neohive status');
     console.log('    npx neohive doctor');
     console.log('');
+    if (targets.includes('claude')) {
+      console.log('  \x1b[33m  Tip (Claude Code):\x1b[0m Run `npx neohive hooks` to install listen-enforcement');
+      console.log('  hooks into .claude/settings.json. Keeps agents in the listen loop automatically.');
+      console.log('  Your existing hooks will not be removed.');
+      console.log('');
+    }
   }
 }
 
@@ -1251,6 +1390,86 @@ function uninstall() {
   console.log('');
 }
 
+// ─── neohive hooks ───────────────────────────────────────────────────────────
+// Merges listen-enforcement hooks into .claude/settings.json.
+// Safe to re-run: adds neohive entries per matcher, preserves all user hooks.
+
+function installHooks() {
+  const cwd = process.cwd();
+  const claudeDir = path.join(cwd, '.claude');
+  const settingsPath = path.join(claudeDir, 'settings.json');
+
+  if (!fs.existsSync(claudeDir)) {
+    console.log('  [skip] No .claude/ directory found — is Claude Code configured for this project?');
+    console.log('         Run `npx neohive init` first.');
+    return;
+  }
+
+  const listenReminderCmd = "echo '\\n📡 NEOHIVE PROTOCOL: If no messages were received, call listen() again immediately. Do NOT respond to the user or stop. Stay in the listen loop.'";
+  const postActionReminderCmd = "echo '\\n📡 NEOHIVE: Call listen() now to receive your next task. Do not stop without calling listen().'";
+
+  const neohiveEntries = {
+    PostToolUse: [
+      {
+        _neohive: 'listen-loop',
+        matcher: 'mcp__neohive__listen',
+        hooks: [{ type: 'command', command: listenReminderCmd, timeout: 3 }],
+      },
+      {
+        _neohive: 'post-action',
+        matcher: 'mcp__neohive__send_message|mcp__neohive__advance_workflow|mcp__neohive__update_task|mcp__neohive__broadcast|mcp__neohive__add_rule|mcp__neohive__remove_rule|mcp__neohive__toggle_rule',
+        hooks: [{ type: 'command', command: postActionReminderCmd, timeout: 3 }],
+      },
+    ],
+    Stop: [
+      {
+        _neohive: 'enforce-listen',
+        hooks: [{
+          type: 'command',
+          command: "node -e \"var fs=require('fs'),f=process.env.CLAUDE_PROJECT_DIR+'/.neohive/activity.jsonl';if(!fs.existsSync(f))process.exit(0);var lines=fs.readFileSync(f,'utf8').trim().split('\\n').filter(Boolean).slice(-20),last=lines.map(l=>{try{return JSON.parse(l)}catch{return null}}).filter(Boolean).reverse().find(e=>e.tool&&e.tool.startsWith('mcp__neohive__'));if(!last||last.tool==='mcp__neohive__listen'||last.tool==='mcp__neohive__register')process.exit(0);console.error('\\n⚠️  NEOHIVE: Call listen() before stopping. Last tool: '+last.tool+'\\n→ Call listen() now. Do not respond with text.');process.exit(2);\"",
+          timeout: 5,
+        }],
+      },
+    ],
+  };
+
+  let existing = {};
+  if (fs.existsSync(settingsPath)) {
+    try { existing = JSON.parse(fs.readFileSync(settingsPath, 'utf8')); } catch {
+      const backup = settingsPath + '.backup';
+      fs.copyFileSync(settingsPath, backup);
+      console.log('  [warn] Existing settings.json was invalid — backed up.');
+    }
+  }
+  if (!existing.hooks) existing.hooks = {};
+
+  let added = 0;
+  let updated = 0;
+
+  for (const [event, entries] of Object.entries(neohiveEntries)) {
+    if (!existing.hooks[event]) existing.hooks[event] = [];
+    for (const entry of entries) {
+      const idx = existing.hooks[event].findIndex(e => e._neohive === entry._neohive);
+      if (idx === -1) {
+        existing.hooks[event].push(entry);
+        added++;
+      } else {
+        existing.hooks[event][idx] = entry;
+        updated++;
+      }
+    }
+  }
+
+  fs.mkdirSync(claudeDir, { recursive: true });
+  fs.writeFileSync(settingsPath, JSON.stringify(existing, null, 2) + '\n', 'utf8');
+
+  console.log(`\n  Neohive hooks installed into .claude/settings.json`);
+  if (added)   console.log(`  [ok] Added:   ${added} hook(s)`);
+  if (updated) console.log(`  [ok] Updated: ${updated} hook(s) (already present)`);
+  console.log('  Your existing hooks were preserved.');
+  console.log('  Restart Claude Code for changes to take effect.\n');
+}
+
 switch (command) {
   case 'init':
     init();
@@ -1282,6 +1501,9 @@ switch (command) {
   case 'status':
     cliStatus();
     break;
+  case 'hooks':
+    installHooks();
+    break;
   case 'uninstall':
   case 'remove':
     uninstall();

package/dashboard.html

@@ -3,7 +3,19 @@
 <head>
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
-<title>Neohive</title>
+<title>Neohive | Multi-Agent Coordination Dashboard</title>
+<meta name="description" content="Neohive — The ultimate multi-agent coordination and management dashboard. Orchestrate, monitor, and scale your AI workforce in real-time.">
+<meta name="keywords" content="AI, multi-agent systems, orchestration, dashboard, neohive, agents, automation">
+<meta name="author" content="Neohive Team">
+<meta property="og:title" content="Neohive | Multi-Agent Coordination Dashboard">
+<meta property="og:description" content="Orchestrate and scale your autonomous agent workforce with a stunning, high-performance real-time dashboard.">
+<meta property="og:type" content="website">
+<meta property="og:image" content="https://neohive.ai/og-image.png">
+<meta name="twitter:card" content="summary_large_image">
+<meta name="twitter:title" content="Neohive | Multi-Agent Coordination Dashboard">
+<meta name="twitter:description" content="The command center for your AI agent workforce. Real-time monitoring and scalable orchestration.">
+<meta name="twitter:image" content="https://neohive.ai/og-image.png">
+<meta name="robots" content="index, follow">
 <link rel="icon" href="favicon.png" type="image/png" sizes="16x16">
 <link rel="icon" href="logo.svg" type="image/svg+xml">
 <link rel="preconnect" href="https://fonts.googleapis.com">
@@ -183,7 +195,7 @@
   }
 
   .logo {
-    font-size: 20px;
+    font-size: clamp(18px, 4vw, 22px);
     font-weight: 700;
     letter-spacing: -0.01em;
     color: var(--text);
@@ -3149,9 +3161,18 @@
     }
 
     .header { padding: 0 8px; }
-    .logo { font-size: 17px; }
+    .logo { font-size: clamp(15px, 5vw, 18px); }
     .header-left { gap: 6px; }
 
+    /* Increase touch targets for mobile buttons */
+    .btn, .nh-btn {
+      min-height: 44px;
+      padding: 8px 16px;
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+    }
+
     /* Compact header buttons */
     .header-actions { gap: 2px; }
     .phone-btn { padding: 4px 6px; font-size: 13px; }
@@ -4361,12 +4382,29 @@
     <!-- Settings dropdown -->
     <div style="position:relative;display:inline-block">
       <button class="header-settings-btn" onclick="toggleSettingsMenu()" title="Settings">
-        <svg viewBox="0 0 16 16" width="15" height="15" fill="none" stroke="currentColor" stroke-width="1.5"><circle cx="8" cy="8" r="2.5"/><path d="M8 1v2M8 13v2M1 8h2M13 8h2M2.9 2.9l1.4 1.4M11.7 11.7l1.4 1.4M13.1 2.9l-1.4 1.4M4.3 11.7l-1.4 1.4"/></svg>
+        <svg viewBox="0 0 16 16" width="15" height="15" fill="none" stroke="currentColor" stroke-width="1.5"><path d="M6.5 1.5h3l.5 1.5a5 5 0 011.2.7l1.6-.4 1.5 2.6-1.1 1.2a5 5 0 010 1.4l1.1 1.2-1.5 2.6-1.6-.4a5 5 0 01-1.2.7l-.5 1.5h-3l-.5-1.5A5 5 0 014.8 12l-1.6.4L1.7 9.8l1.1-1.2a5 5 0 010-1.4L1.7 6l1.5-2.6 1.6.4a5 5 0 011.2-.7z"/><circle cx="8" cy="8" r="2"/></svg>
       </button>
       <div id="settings-menu" style="display:none;position:absolute;right:0;top:100%;margin-top:6px;background:var(--surface);border:1px solid var(--border);border-radius:10px;overflow:hidden;z-index:300;min-width:180px;box-shadow:var(--shadow-lg)">
         <div class="settings-item" onclick="toggleTheme();toggleSettingsMenu()"><svg viewBox="0 0 16 16" width="14" height="14" fill="none" stroke="currentColor" stroke-width="1.5"><circle cx="8" cy="8" r="4"/><path d="M8 1v2M8 13v2M1 8h2M13 8h2"/></svg> Theme</div>
         <div class="settings-item" id="settings-notif-item" onclick="toggleCombinedNotifications();"><svg viewBox="0 0 16 16" width="14" height="14" fill="none" stroke="currentColor" stroke-width="1.5"><path d="M4 6a4 4 0 018 0v3l2 2H2l2-2z"/><path d="M6 13a2 2 0 004 0"/></svg> <span id="settings-notif-label">Notifications</span></div>
         <div style="height:1px;background:var(--border);margin:4px 8px"></div>
+        <div style="padding:8px 12px;display:flex;align-items:center;gap:8px;font-size:13px;color:var(--text-muted)">
+          <svg viewBox="0 0 16 16" width="14" height="14" fill="none" stroke="currentColor" stroke-width="1.5"><circle cx="8" cy="8" r="6"/><path d="M8 5v3l2 2"/></svg>
+          <span style="flex:1;white-space:nowrap">Idle poll (s)</span>
+          <input id="settings-idle-poll-input" type="number" min="10" max="600" step="10" value="90"
+            style="width:60px;background:var(--bg);border:1px solid var(--border);border-radius:5px;color:var(--text);padding:2px 6px;font-size:13px;text-align:right"
+            onclick="event.stopPropagation()"
+            onchange="setIdlePollInterval(this.value)">
+        </div>
+        <div style="padding:8px 12px;display:flex;align-items:center;gap:8px;font-size:13px;color:var(--text-muted)">
+          <svg viewBox="0 0 16 16" width="14" height="14" fill="none" stroke="currentColor" stroke-width="1.5"><path d="M8 1v6l3 3"/><circle cx="8" cy="8" r="7"/></svg>
+          <span style="flex:1;white-space:nowrap">Listen timeout (s)</span>
+          <input id="settings-listen-poll-input" type="number" min="30" max="600" step="30" value="120"
+            style="width:60px;background:var(--bg);border:1px solid var(--border);border-radius:5px;color:var(--text);padding:2px 6px;font-size:13px;text-align:right"
+            onclick="event.stopPropagation()"
+            onchange="setListenPollInterval(this.value)">
+        </div>
+        <div style="height:1px;background:var(--border);margin:4px 8px"></div>
         <div class="settings-item" onclick="exportShareableHTML();toggleSettingsMenu()">Export HTML</div>
         <div class="settings-item" onclick="exportJSON();toggleSettingsMenu()">Export JSON</div>
         <div class="settings-item" onclick="enterReplay();toggleSettingsMenu()">Replay</div>
@@ -9838,11 +9876,11 @@ var ROLE_SKILLS = {
   monitor: ['observability', 'logging', 'performance', 'health-checks']
 };
 var ROLE_PROMPTS = {
-  lead: function(name) { return 'You are ' + name + ', the Coordinator in a multi-agent team. Register as "' + name + '".\n\nYour job is to:\n1. Break the user\'s request into tasks and delegate to team agents via send_message\n2. Use create_task() and create_workflow() to formally track work\n3. Monitor progress with workflow_status() and list_tasks()\n4. Use consume_messages() to check agent updates without blocking\n5. Synthesize results and present to the user\n\nYou MUST NOT edit files or write code. Delegate ALL code work to other agents. Your tools: send_message, create_task, create_workflow, advance_workflow, workflow_status, list_tasks, consume_messages, broadcast.'; },
-  backend: function(name) { return 'You are ' + name + ', a Developer in a multi-agent team. Register as "' + name + '". Call listen() to wait for tasks.\n\nWhen you receive a task:\n1. Use lock_file() before editing shared code\n2. Implement the requested changes with clean, tested code\n3. Use unlock_file() when done editing\n4. Update your task with update_task(status="done")\n5. Send a summary to the Coordinator with file paths and key decisions\n6. Call listen() again for the next task\n\nFocus on production-quality code. Include file paths in reports.'; },
-  frontend: function(name) { return 'You are ' + name + ', a Frontend Developer in a multi-agent team. Register as "' + name + '". Call listen() to wait for tasks.\n\nWhen you receive a task:\n1. Use lock_file() before editing shared frontend code\n2. Implement UI/UX changes following design conventions\n3. Use unlock_file() when done\n4. Update your task with update_task(status="done")\n5. Send a summary to the Coordinator with file paths and screenshots if relevant\n6. Call listen() again for the next task\n\nFocus on clean UI, accessibility, and responsive design.'; },
-  quality: function(name) { return 'You are ' + name + ', a Reviewer in a multi-agent team. Register as "' + name + '". Call listen() to wait for review requests.\n\nWhen you receive work to review:\n1. Read the actual files that were changed\n2. Check for bugs, security issues, code style, edge cases\n3. Use submit_review() to formally approve or request changes\n4. Send structured feedback: blockers vs suggestions\n5. Call listen() again\n\nBe constructive and specific. Reference line numbers. Never let mediocre work pass.'; },
-  monitor: function(name) { return 'You are ' + name + ', a System Monitor in a multi-agent team. Register as "' + name + '". Call listen() to wait for events.\n\nYour job:\n1. Watch for idle agents, stuck tasks, and circular escalations\n2. Use send_message to nudge idle agents\n3. Use update_task to reassign stuck tasks\n4. Log interventions to your workspace via workspace_write\n5. Call listen() again\n\nNever stop monitoring. You ARE the system intelligence.'; }
+  lead: function(name) { return 'You are ' + name + ', the Coordinator in a multi-agent team. Register as "' + name + '", call update_profile() to set your role, call get_briefing() for project context, then call listen() to receive the first request.\n\nYour loop:\n1. Receive request via listen()\n2. Break it into subtasks — create_task() per item, assign to agents\n3. Create a workflow with create_workflow() for multi-step plans\n4. Delegate via send_message() to each assigned agent\n5. Monitor with workflow_status() and list_tasks()\n6. Check updates with messages(action="consume") without blocking\n7. Synthesize results and report back to the user\n8. Call listen(outcome="completed", summary="...") for the next task\n\nRules:\n- NEVER edit files or write code — delegate ALL implementation to other agents\n- Always report synthesis back to the user via send_message()\n- If listen() returns retry: true, call listen() again immediately'; },
+  backend: function(name) { return 'You are ' + name + ', a Backend Developer in a multi-agent team. Register as "' + name + '", call update_profile() to set your role, call get_briefing() for project context, then call listen() to wait for tasks.\n\nYour loop:\n1. Receive task via listen()\n2. Call update_task(status="in_progress", task_id=...) to claim it\n3. Call lock_file() before editing any shared file\n4. Implement the changes — clean, production-quality code\n5. Call unlock_file() when done\n6. Call update_task(status="done", task_id=...)\n7. Report to Lead via send_message(): what you did, files changed, decisions made, any blockers\n8. Call listen(outcome="completed", task_id=..., summary="...") for the next task\n\nIf a lock is already held: notify Lead via send_message() and call listen() to wait.\nIf listen() returns retry: true, call listen() again immediately.'; },
+  frontend: function(name) { return 'You are ' + name + ', a Frontend Developer in a multi-agent team. Register as "' + name + '", call update_profile() to set your role, call get_briefing() for project context, then call listen() to wait for tasks.\n\nYour loop:\n1. Receive task via listen()\n2. Call update_task(status="in_progress", task_id=...) to claim it\n3. Call lock_file() before editing any shared frontend file\n4. Implement UI/UX changes — clean, accessible, responsive code\n5. Call unlock_file() when done\n6. Call update_task(status="done", task_id=...)\n7. Report to Lead via send_message(): files changed, design decisions, screenshots if relevant\n8. Call listen(outcome="completed", task_id=..., summary="...") for the next task\n\nIf a lock is already held: notify Lead via send_message() and call listen() to wait.\nIf listen() returns retry: true, call listen() again immediately.'; },
+  quality: function(name) { return 'You are ' + name + ', a Code Reviewer in a multi-agent team. Register as "' + name + '", call update_profile() to set your role, call get_briefing() for project context, then call listen() to wait for review requests.\n\nYour loop:\n1. Receive review request via listen()\n2. Call update_task(status="in_progress", task_id=...) to claim it\n3. Read the actual files that were changed\n4. Check for: bugs, security issues, logic errors, code style, edge cases\n5. Call submit_review(approved=true/false, feedback="...") with structured feedback\n6. Report to Lead via send_message(): blockers vs suggestions with file:line references\n7. Call update_task(status="done", task_id=...)\n8. Call listen(outcome="completed", task_id=..., summary="...") for the next review\n\nBe specific: reference file paths and line numbers. Separate blockers from suggestions.\nIf listen() returns retry: true, call listen() again immediately.'; },
+  monitor: function(name) { return 'You are ' + name + ', a System Monitor in a multi-agent team. Register as "' + name + '", call update_profile() to set your role, call get_briefing() for project context, then call listen() to begin monitoring.\n\nYour loop (runs continuously):\n1. Call list_agents() — flag agents with last_activity > 5 min and status != offline\n2. Call list_tasks() — flag in_progress tasks whose assignee appears idle\n3. Nudge idle agents: send_message() asking them to resume their listen() loop\n4. Reassign stuck tasks (no progress > 10 min): update_task() to reset to pending\n5. For blocked_permanent tasks: send_message() to Lead immediately\n6. Log all interventions via workspace_write()\n7. Call listen(outcome="completed", summary="...") — repeat\n\nEscalation: if unresolved after 2 attempts, create_task() assigned to Lead describing the issue.\nIf listen() returns retry: true, call listen() again immediately.\nNever stop monitoring.'; }
 };
 
 function renderLaunchPanel() {
@@ -10651,7 +10689,11 @@ function copyLaunchPrompt() {
 
 function toggleSettingsMenu() {
   var menu = document.getElementById('settings-menu');
-  if (menu) menu.style.display = menu.style.display === 'none' ? 'block' : 'none';
+  if (menu) {
+    var opening = menu.style.display === 'none';
+    menu.style.display = opening ? 'block' : 'none';
+    if (opening) { initIdlePollInput(); initListenPollInput(); }
+  }
 }
 // Close settings when clicking outside
 document.addEventListener('click', function(e) {
@@ -10947,6 +10989,8 @@ function setCoordinatorMode(mode) {
       showToast('!', 'Failed: ' + data.error);
     } else {
       showToast('&#x2713;', 'Coordinator mode: ' + (mode === 'responsive' ? 'Stay with me' : 'Run autonomously'));
+      var listenInput = document.getElementById('settings-listen-poll-input');
+      if (listenInput) listenInput.value = mode === 'responsive' ? 120 : 90;
       renderOverview();
     }
   }).catch(function() {
@@ -10954,6 +10998,60 @@ function setCoordinatorMode(mode) {
   });
 }
 
+// ==================== IDLE POLL INTERVAL ====================
+
+function setIdlePollInterval(value) {
+  var secs = parseInt(value, 10);
+  if (isNaN(secs) || secs < 10) return;
+  lttFetch('/api/config', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ idle_poll_interval: secs })
+  }).then(function(r) { return r.json(); }).then(function(data) {
+    if (data.error) {
+      showToast('!', 'Failed: ' + data.error);
+    } else {
+      showToast('&#x2713;', 'Idle poll interval: ' + secs + 's');
+    }
+  }).catch(function() {
+    showToast('!', 'Failed to save idle poll interval');
+  });
+}
+
+function initIdlePollInput() {
+  lttFetch('/api/config').then(function(r) { return r.json(); }).then(function(cfg) {
+    var input = document.getElementById('settings-idle-poll-input');
+    if (input && cfg.idle_poll_interval) input.value = cfg.idle_poll_interval;
+  }).catch(function() {});
+}
+
+// ==================== LISTEN POLL INTERVAL ====================
+
+function setListenPollInterval(value) {
+  var secs = parseInt(value, 10);
+  if (isNaN(secs) || secs < 30) return;
+  lttFetch('/api/config', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ listen_poll_interval: secs })
+  }).then(function(r) { return r.json(); }).then(function(data) {
+    if (data.error) {
+      showToast('!', 'Failed: ' + data.error);
+    } else {
+      showToast('&#x2713;', 'Listen timeout: ' + secs + 's');
+    }
+  }).catch(function() {
+    showToast('!', 'Failed to save listen timeout');
+  });
+}
+
+function initListenPollInput() {
+  lttFetch('/api/config').then(function(r) { return r.json(); }).then(function(cfg) {
+    var input = document.getElementById('settings-listen-poll-input');
+    if (input && cfg.listen_poll_interval) input.value = cfg.listen_poll_interval;
+  }).catch(function() {});
+}
+
 // ==================== TOAST NOTIFICATIONS ====================
 
 var toastQueue = [];

package/dashboard.js

@@ -175,9 +175,15 @@ function resolveDashboardDefaultDataDir() {
     let s = String(envData).trim();
     if (/\$\{workspaceFolder\}/i.test(s)) {
       const root = findCursorProjectRootWithNeohive(process.cwd());
-      if (root) s = s.replace(/\$\{workspaceFolder\}/gi, root);
+      if (!root) {
+        // Placeholder can't be expanded — fall through to the config/walk/cwd strategies
+      } else {
+        s = s.replace(/\$\{workspaceFolder\}/gi, root);
+        return { path: path.resolve(s), source: 'environment' };
+      }
+    } else {
+      return { path: path.resolve(s), source: 'environment' };
     }
-    return { path: path.resolve(s), source: 'environment' };
   }
 
   // 2. Project MCP config — authoritative, written by `neohive init`
@@ -2733,6 +2739,31 @@ const server = http.createServer(async (req, res) => {
         res.end(JSON.stringify({ error: 'Failed to set coordinator mode: ' + e.message }));
       }
     }
+    else if (url.pathname === '/api/config' && req.method === 'GET') {
+      const projectPath = url.searchParams.get('project') || null;
+      const config = readJson(filePath('config.json', projectPath));
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify(config));
+    }
+    else if (url.pathname === '/api/config' && req.method === 'POST') {
+      try {
+        const body = await parseBody(req).catch(() => ({}));
+        const projectPath = url.searchParams.get('project') || null;
+        const dataDir = resolveDataDir(projectPath);
+        if (!fs.existsSync(dataDir)) fs.mkdirSync(dataDir, { recursive: true });
+        const configFile = filePath('config.json', projectPath);
+        await withFileLock(configFile, () => {
+          const config = readJson(configFile);
+          Object.assign(config, body);
+          fs.writeFileSync(configFile, JSON.stringify(config, null, 2));
+        });
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ success: true }));
+      } catch (e) {
+        res.writeHead(500, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Failed to save config: ' + e.message }));
+      }
+    }
     else if (url.pathname === '/api/reset' && req.method === 'POST') {
       const body = await parseBody(req).catch(() => ({}));
       if (!body.confirm) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neohive",
-  "version": "6.3.0",
+  "version": "6.4.0",
   "description": "The MCP collaboration layer for AI CLI tools. Turn Claude Code, Gemini CLI, and Codex CLI into a team.",
   "main": "server.js",
   "bin": {

package/server.js

@@ -82,7 +82,7 @@ const SERVER_CONFIG = {
   // Polling / Heartbeat intervals (ms)
   HEARTBEAT_INTERVAL_MS:    15000,   // how often agents write heartbeat files
   POLL_INTERVAL_MS:          2000,   // message polling cycle
-  AUTONOMOUS_LISTEN_MS:     30000,   // max listen timeout in autonomous mode
+  AUTONOMOUS_LISTEN_MS:     90000,   // max listen timeout in autonomous mode
   CODEX_LISTEN_MS:          90000,   // max listen timeout for Codex agents
 
   // Agent health thresholds (ms)
@@ -124,6 +124,7 @@ let currentBranch = 'main'; // which branch this agent is on
 let lastSentAt = 0; // timestamp of last sent message (for group cooldown)
 let sendsSinceLastListen = 0; // enforced: must listen between sends in group mode
 let consecutiveNonListenCalls = 0; // escalating listen() enforcement counter
+let pendingUserReply = false; // true when __user__ message received but not yet replied to
 let _isCurrentlyListening = false; // true when agent is in a listen() call
 let sendLimit = 1; // default: 1 send per listen cycle (2 if addressed)
 let unaddressedSends = 0; // response budget: unaddressed sends counter
@@ -585,9 +586,27 @@ function buildMessageResponse(msg, consumedIds) {
   } catch (e) { log.debug('task reminder in listen failed:', e.message); }
 
   const isSystemMsg = msg.from === '__system__' || msg.system === true;
-  const nextAction = isSystemMsg
-    ? 'Process this message, then call listen().'
-    : `Do what this message asks. When finished, send_message(to="${msg.from}") with what you did and files changed, then call listen().`;
+  if (msg.from === '__user__') pendingUserReply = true;
+
+  // Generate a specific next_action for review requests so reviewers know to read the file
+  let nextAction;
+  if (isSystemMsg && msg.content) {
+    const reviewMatch = msg.content.match(/submit_review\("(rev_[a-z0-9]+)"/);
+    const fileMatch = msg.content.match(/read(?:ing)?(?: the)? (?:file )?"([^"]+)"/i) ||
+                      msg.content.match(/review of "([^"]+)"/i);
+    if (reviewMatch) {
+      const reviewId = reviewMatch[1];
+      const filePath = fileMatch ? fileMatch[1] : null;
+      nextAction = filePath
+        ? `REVIEW REQUIRED: Read "${filePath}" first, then call submit_review("${reviewId}", "approved"/"changes_requested", "<your findings — min 50 chars>"). Do NOT submit without reading the file.`
+        : `REVIEW REQUIRED: Read the relevant files for this review, then call submit_review("${reviewId}", "approved"/"changes_requested", "<your findings — min 50 chars>"). Feedback is required.`;
+    }
+  }
+  if (!nextAction) {
+    nextAction = isSystemMsg
+      ? 'Process this message, then call listen().'
+      : `Do what this message asks. When finished, send_message(to="${msg.from}") with what you did and files changed, then call listen().`;
+  }
 
   return {
     success: true,
@@ -1238,7 +1257,7 @@ function buildGuide(level = 'standard') {
     }
   }
 
-  if (isLeadRole && aliveCount >= 2) {
+  if (isLeadRole) {
     const coordinatorMode = getConfig().coordinator_mode || 'responsive';
     if (coordinatorMode === 'responsive') {
       rules.push('COORDINATOR: Use consume_messages() to check updates non-blockingly. Do NOT block in listen() — stay responsive to the user.');
@@ -1249,7 +1268,9 @@ function buildGuide(level = 'standard') {
   }
 
   const listenCmd = isManagedMode() ? 'listen()' : (mode === 'group' ? 'listen_group()' : 'listen()');
-  rules.push(`After EVERY action, call ${listenCmd}. Never use sleep() or poll with check_messages().`);
+  if (!isLeadRole) {
+    rules.push(`After EVERY action, call ${listenCmd}. Never use sleep() or poll with check_messages().`);
+  }
 
   if (level === 'minimal') {
     rules.push('Lock files before editing (lock_file/unlock_file).');
@@ -1543,6 +1564,15 @@ function toolRegister(name, provider = null, skills = null) {
       nextAction = 'Call get_briefing() to load project context';
     }
 
+    // Lead/coordinator gets role-specific next_action regardless of agent count
+    const myRoleStr = (guide.your_role || '').toLowerCase();
+    if (myRoleStr === 'lead' || myRoleStr === 'manager' || myRoleStr === 'coordinator') {
+      const coordinatorMode = getConfig().coordinator_mode || 'responsive';
+      nextAction = coordinatorMode === 'autonomous'
+        ? 'Call get_briefing() to load project context, then listen() to coordinate your team.'
+        : 'Call get_briefing() to load project context, then consume_messages() to check for pending work.';
+    }
+
     // --- Build the result: next_action FIRST, then context ---
     const result = {
       success: true,
@@ -1925,6 +1955,9 @@ async function toolSendMessage(content, to = null, reply_to = null, channel = nu
   sendsSinceLastListen++;
   if (isGroupMode() && !msg.addressed_to) { unaddressedSends++; }
 
+  // Clear pending user reply flag when agent successfully replies to __user__
+  if (to === '__user__') pendingUserReply = false;
+
   const result = { success: true, messageId: msg.id, from: msg.from, to: msg.to };
 
   // Decision overlap hint: warn if message content overlaps with existing decisions
@@ -2134,104 +2167,11 @@ async function toolWaitForReply(timeoutSeconds = 300, from = null) {
   };
 }
 
-function toolCheckMessages(from = null) {
-  if (!registeredName) {
-    return { error: 'You must call register() first' };
-  }
-
-  const unconsumed = getUnconsumedMessages(registeredName, from);
-
-  // Rich summary: senders, addressed count, urgency — same as enhanced nudge
-  const senders = {};
-  let addressedCount = 0;
-  for (const m of unconsumed) {
-    senders[m.from] = (senders[m.from] || 0) + 1;
-    if (m.addressed_to && m.addressed_to.includes(registeredName)) addressedCount++;
-  }
-
-  // Include pending notification count
-  const allNotifs = getNotifications();
-  const unreadNotifs = allNotifs.filter(n => !n.read_by.includes(registeredName));
-
-  const result = {
-    count: unconsumed.length,
-    pending_notifications: unreadNotifs.length,
-    // Scale fix: return previews not full content — agent gets full content via listen_group()
-    messages: unconsumed.map(m => ({
-      id: m.id,
-      from: m.from,
-      preview: m.content.substring(0, 120),
-      timestamp: m.timestamp,
-      ...(m.addressed_to && { addressed_to: m.addressed_to }),
-    })),
-  };
-
-  if (unconsumed.length > 0) {
-    result.senders = senders;
-    result.addressed_to_you = addressedCount;
-    const latest = unconsumed[unconsumed.length - 1];
-    result.preview = `${latest.from}: "${latest.content.substring(0, 80).replace(/\n/g, ' ')}..."`;
-    const oldestAge = Math.round((Date.now() - new Date(unconsumed[0].timestamp).getTime()) / 1000);
-    result.urgency = oldestAge > 120 ? 'critical' : oldestAge > 30 ? 'urgent' : 'normal';
-    result.action_required = 'You have unread messages. Call listen() to receive and process them. Do NOT call check_messages() again — it does not consume messages and you will see the same messages repeatedly.';
-  }
-
-  return result;
-}
-
-function toolConsumeMessages(from = null, limit = null) {
-  if (!registeredName) {
-    return { error: 'You must call register() first' };
-  }
-
-  let unconsumed = getUnconsumedMessages(registeredName, from);
-  if (limit && limit > 0 && unconsumed.length > limit) {
-    unconsumed = unconsumed.slice(0, limit);
-  }
-
-  if (unconsumed.length === 0) {
-    return { success: true, count: 0, messages: [] };
-  }
-
-  // Mark all as consumed
-  const consumed = getConsumedIds(registeredName);
-  for (const msg of unconsumed) {
-    consumed.add(msg.id);
-    markAsRead(registeredName, msg.id);
-  }
-  saveConsumedIds(registeredName, consumed);
-
-  // Update read offset
-  const msgFile = getMessagesFile(currentBranch);
-  if (fs.existsSync(msgFile)) {
-    lastReadOffset = fs.statSync(msgFile).size;
-  }
-
-  touchActivity();
+// toolCheckMessages and toolConsumeMessages removed — dead code.
+// Routing goes through: case 'messages' → messaging.handlers['check_messages' | 'consume_messages']
+// Source of truth: agent-bridge/tools/messaging.js
 
-  // Count remaining unconsumed after this batch
-  const remaining = getUnconsumedMessages(registeredName, null);
-
-  const agents = getAgents();
-  const agentsOnline = Object.entries(agents).filter(([, info]) => isPidAlive(info.pid, info.last_activity)).length;
-
-  return {
-    success: true,
-    count: unconsumed.length,
-    messages: unconsumed.map(m => ({
-      id: m.id,
-      from: m.from,
-      content: m.content,
-      timestamp: m.timestamp,
-      ...(m.reply_to && { reply_to: m.reply_to }),
-      ...(m.thread_id && { thread_id: m.thread_id }),
-      ...(m.addressed_to && { addressed_to: m.addressed_to }),
-    })),
-    remaining: remaining.length,
-    agents_online: agentsOnline,
-    coordinator_mode: getConfig().coordinator_mode || 'responsive',
-  };
-}
+// toolConsumeMessages removed — dead code. See agent-bridge/tools/messaging.js
 
 function toolAckMessage(messageId) {
   if (!registeredName) {
@@ -2282,6 +2222,9 @@ async function toolListen(from = null, outcome = null, task_id = null, summary =
     if (newStatus) toolUpdateTask(task_id, newStatus, summary || '');
   }
 
+  // Clear pending user reply flag — warning was shown, agent is now entering the listen loop
+  pendingUserReply = false;
+
   // Auto-detect group/managed mode and delegate to toolListenGroup
   // This prevents agents from calling the "wrong" listen function
   if (isGroupMode() || isManagedMode()) {
@@ -2385,12 +2328,15 @@ async function toolListen(from = null, outcome = null, task_id = null, summary =
 
       heartbeatTimer = setInterval(() => { touchHeartbeat(registeredName); }, 15000);
 
+      const listenTimeoutMs = (getConfig().listen_poll_interval || 120) * 1000;
       timer = setTimeout(() => {
         touchActivity();
         autoCompact();
         if (checkMessages()) return;
-        setupWatcher();
-      }, 300000);
+        // Return cleanly so Claude sees retry:true rather than a client-side MCP timeout
+        setListening(false);
+        done({ retry: true, next_action: 'No messages. Call listen() again immediately.' });
+      }, listenTimeoutMs);
     }
 
     setupWatcher();
@@ -2722,9 +2668,12 @@ async function toolListenGroup(outcome = null, task_id = null, summary = null) {
 
   const consumed = getConsumedIds(registeredName);
 
-  // Autonomous mode: cap listen at 30s — agents should use get_work() instead
-  const autonomousTimeout = isAutonomousMode() ? SERVER_CONFIG.AUTONOMOUS_LISTEN_MS : null;
-  const MAX_LISTEN_MS = 300000; // 5 minutes — MCP has no tool timeout, heartbeat keeps agent alive
+  // Autonomous mode: cap listen at 90s — agents should use get_work() instead
+  // Responsive mode (Stay with me) overrides autonomous timeout — always uses configured listen interval
+  const coordinatorMode = getConfig().coordinator_mode || 'responsive';
+  const autonomousTimeout = (coordinatorMode !== 'responsive' && isAutonomousMode()) ? SERVER_CONFIG.AUTONOMOUS_LISTEN_MS : null;
+  const configuredListenMs = (getConfig().listen_poll_interval || 120) * 1000;
+  const MAX_LISTEN_MS = configuredListenMs; // configurable via dashboard settings (default 2 min)
   const listenStart = Date.now();
 
   // Helper: collect unconsumed messages from all sources (general + channels)
@@ -3065,6 +3014,10 @@ function buildListenGroupResponse(batch, consumed, agentName, listenStart) {
     }
   }
 
+  if (batch.some(m => m.from === '__user__')) {
+    pendingUserReply = true;
+  }
+
   if (isAutonomousMode()) {
     result.next_action = 'Process these messages, then call get_work().';
   } else if (result.should_respond === false) {
@@ -3439,7 +3392,7 @@ function toolUpdateTask(taskId, status, notes = null) {
         task.status = 'in_review';
         task.updated_at = new Date().toISOString();
         saveTasks(tasks);
-        broadcastSystemMessage(`[REVIEW GATE] ${registeredName} tried to mark "${task.title}" done but no review exists. Auto-created review ${reviewId}. A reviewer must approve before this task can be completed.`, registeredName);
+        broadcastSystemMessage(`[REVIEW GATE] ${registeredName} tried to mark "${task.title}" done but no review exists. Auto-created review ${reviewId}. To review: (1) read the relevant files for "${task.title}", (2) call submit_review("${reviewId}", "approved"/"changes_requested", "<your findings — min 50 chars>"). Feedback is required.`, registeredName);
         logViolation('review_gate_blocked', registeredName, `Task "${task.title}" (${task.id}) blocked — no approved review. Auto-created ${reviewId}.`);
         touchActivity();
         return {
@@ -4275,12 +4228,14 @@ async function toolGetWork(params = {}) {
   // 9. Truly idle — try role rebalancing before returning
   rebalanceRoles(); // Item 5: check if workload requires role changes
   touchActivity();
+  const config = getConfig();
+  const idleInterval = config.idle_poll_interval || 90;
   const idleResult = {
     type: 'idle',
-    next_action: isManagedMode() ? 'Call listen() to wait for work.' : 'Call get_work() again in 30 seconds.',
+    next_action: isManagedMode() ? 'Call listen() to wait for work.' : `Call get_work() again in ${idleInterval} seconds.`,
     instruction: isManagedMode()
       ? 'No work available right now. Call listen() to wait for the manager to assign work or give you the floor.'
-      : 'No work available right now. Call get_work() again in 30 seconds.'
+      : `No work available right now. Call get_work() again in ${idleInterval} seconds.`
   };
   // Item 4: warn demoted agents
   const agentRep = getReputation();
@@ -5819,6 +5774,59 @@ function toolListChannels() {
   return { channels: result, your_channels: getAgentChannels(registeredName) };
 }
 
+// --- Self-healing Watchdog: reclaim tasks from dead/stale agents ---
+// Specified in GEMINI.md: runs every 60s; scans in_progress tasks.
+function runSelfHealingWatchdog() {
+  if (!registeredName) return;
+  try {
+    const tasks = getTasks();
+    const agents = getAgents();
+    let changed = false;
+    const now = Date.now();
+    const STALE_THRESHOLD_MS = 300000; // 5 minutes
+
+    for (const task of tasks) {
+      if (task.status !== 'in_progress' || !task.assignee) continue;
+      
+      const assignee = agents[task.assignee];
+      let isStale = false;
+
+      if (!assignee) {
+        isStale = true; // Assignee no longer in registry
+      } else {
+        const lastActivity = assignee.last_activity ? new Date(assignee.last_activity).getTime() : 0;
+        const heartbeatStale = now - lastActivity > STALE_THRESHOLD_MS;
+        const pidDead = !isPidAlive(assignee.pid, assignee.last_activity);
+        
+        if (pidDead && heartbeatStale) {
+          isStale = true;
+        }
+      }
+
+      if (isStale) {
+        const retryCount = (task.retry_count || 0) + 1;
+        task.retry_count = retryCount;
+        task.updated_at = new Date().toISOString();
+        
+        if (retryCount >= 3) {
+          task.status = 'blocked_permanent';
+          task.blocked_reason = `Agent "${task.assignee}" failed 3 times (PID dead + heartbeat stale >5min). Coordinator intervention required.`;
+          broadcastSystemMessage(`⛔ [WATCHDOG: POISON PILL] Task "${task.title}" marked as blocked_permanent after 3 failed attempts by ${task.assignee}. Coordinator intervention required.`, registeredName);
+        } else {
+          const oldAssignee = task.assignee;
+          task.status = 'pending';
+          task.assignee = null;
+          changed = true;
+          broadcastSystemMessage(`↺ [WATCHDOG: RECLAIMED] Task "${task.title}" reclaimed from stale agent "${oldAssignee}" (retry ${retryCount}/3). Reset to pending.`, registeredName);
+        }
+        changed = true;
+      }
+    }
+
+    if (changed) saveTasks(tasks);
+  } catch (e) { log.warn("Self-healing watchdog failed:", e.message); }
+}
+
 // Auto-escalation: notify team about tasks blocked for >5 minutes
 // Uses task.escalated_at field for cross-process dedup (file-based, not in-memory)
 function escalateBlockedTasks() {
@@ -7586,7 +7594,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     // Escalating listen() enforcement — block tools after too many non-listen calls
     // send_message is exempt so blocked agents can escalate to coordinator before calling listen()
     // messages is exempt (unified query tool — replaces check_messages/consume_messages)
-    const listenExemptTools = new Set(['register', 'get_briefing', 'get_guide', 'listen', 'wait_for_reply', 'update_profile', 'list_agents', 'add_rule', 'remove_rule', 'toggle_rule', 'list_rules', 'send_message', 'messages']);
+    // lock_file and unlock_file are safety housekeeping, not comms — exempt from the listen counter
+    const listenExemptTools = new Set(['register', 'get_briefing', 'get_guide', 'listen', 'wait_for_reply', 'update_profile', 'list_agents', 'add_rule', 'remove_rule', 'toggle_rule', 'list_rules', 'send_message', 'messages', 'lock_file', 'unlock_file']);
     if (listenExemptTools.has(name)) {
       if (name === 'listen' || name === 'wait_for_reply') {
         consecutiveNonListenCalls = 0;
@@ -7608,7 +7617,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
       if (!isCoordinatorExempt) {
         consecutiveNonListenCalls++;
-        if (consecutiveNonListenCalls >= 5) {
+        if (consecutiveNonListenCalls >= 15) {
           const coordinator = (() => {
             try {
               const profs = getProfiles();
@@ -7625,6 +7634,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
               `Do NOT skip step 1. Do NOT call any other tool. Start with send_message now.`
             }],
             isError: true,
+            next_action: `Call send_message(to="${coordinator}", content="I was blocked after ${consecutiveNonListenCalls} calls without listen(). I need to call ${name}. Should I proceed?") then immediately call listen().`,
           };
         }
       }
@@ -7832,6 +7842,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       if (last3.length >= 3 && last3.every(c => c.tool === name && c.argsHash === argsHash)) {
         result._stuck_hint = `You have called ${name} 3 times with the same error. Consider: broadcasting for help, trying a different approach, or calling suggest_task() to find other work.`;
       }
+      result.next_action = 'Fix the error above, then call listen() to continue.';
       return {
         content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
         isError: true,
@@ -7880,18 +7891,30 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
       if (isResponsiveCoordinator) {
         // Responsive coordinators must NEVER be told to call listen().
-        // Replace any tool-set listen() directive with consume_messages() or nothing.
-        if (!result.next_action || /\blisten\(\)/i.test(result.next_action)) {
-          try {
-            const pending = getUnconsumedMessages(registeredName);
-            if (pending.length > 0) {
-              result.next_action = `${pending.length} agent update(s) waiting. Call consume_messages() to read them.`;
-            } else {
-              delete result.next_action;
-            }
-          } catch {
-            delete result.next_action;
+        // Three cases:
+        //   1. No next_action set by tool       → inject consume_messages hint if pending, else nothing
+        //   2. Bare listen() directive           → replace entirely with coordinator hint
+        //   3. Compound "Do X, then listen()."  → strip the listen() tail, keep the lead instruction
+        const na = result.next_action || '';
+        const bareListenRe = /^call listen\(\)/i;
+        const tailListenRe = /,?\s*then call listen\(\)[^.]*\./i;
+        try {
+          const pending = getUnconsumedMessages(registeredName);
+          const pendingHint = pending.length > 0
+            ? `${pending.length} agent update(s) waiting. Call consume_messages() to read them.`
+            : null;
+          if (!na || bareListenRe.test(na)) {
+            // No guidance or bare listen() — replace with coordinator hint or nothing
+            if (pendingHint) result.next_action = pendingHint;
+            else delete result.next_action;
+          } else if (tailListenRe.test(na)) {
+            // Compound instruction ending in "then call listen()" — strip just the listen() tail
+            const stripped = na.replace(tailListenRe, '.').replace(/\.\.$/, '.').trim();
+            result.next_action = pendingHint ? `${stripped} Then: ${pendingHint}` : stripped;
           }
+          // else: next_action has no listen() reference — preserve as-is
+        } catch {
+          if (bareListenRe.test(na)) delete result.next_action;
         }
       } else {
         if (!result.next_action) {
@@ -7911,8 +7934,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           } catch {}
         }
 
-        if (consecutiveNonListenCalls >= 3) {
-          result.next_action = `WARNING: ${consecutiveNonListenCalls} calls without listen(). Tools BLOCKED at 5. Call listen() NOW.`;
+        if (consecutiveNonListenCalls >= 10) {
+          result.next_action = `WARNING: ${consecutiveNonListenCalls} calls without listen(). Tools BLOCKED at 15. Call listen() NOW.`;
+        }
+
+        // Soft-enforce user reply: remind agent they have an unanswered user message
+        if (pendingUserReply && result.next_action && name !== 'send_message') {
+          result.next_action += " NOTE: You have an unanswered user message — call send_message(to='__user__') before your next listen().";
         }
       }
     }
@@ -8035,9 +8063,19 @@ function autoReclaimDeadSeat() {
     autoReclaimedName = true; // mark as auto-reclaimed so toolRegister() can override it
     registeredToken = agents[bestName].token || '';
     touchHeartbeat(bestName);
-    // Start 10s heartbeat interval so the agent stays alive past the first 30s window
+    // Start 10s heartbeat interval; watchdog runs every 60s (6 ticks)
     if (heartbeatInterval) clearInterval(heartbeatInterval);
-    heartbeatInterval = setInterval(() => { touchHeartbeat(registeredName); }, 10000);
+    let watchdogTick = 0;
+    heartbeatInterval = setInterval(() => { 
+      touchHeartbeat(registeredName); 
+      watchdogTick++;
+      if (watchdogTick >= 6) {
+        watchdogTick = 0;
+        runSelfHealingWatchdog();
+        escalateBlockedTasks();
+        triggerStandupIfDue();
+      }
+    }, 10000);
     heartbeatInterval.unref();
     console.error(`[neohive] Auto-reclaimed seat "${bestName}" (previous PID dead)`);
   } catch (e) {

package/tools/governance.js

@@ -115,11 +115,13 @@ module.exports = function (ctx) {
     reviews.push(review);
     writeJsonFile(REVIEWS_FILE, reviews);
 
-    broadcastSystemMessage(`[REVIEW] ${state.registeredName} requests review of "${review.file}": ${review.description || 'No description'}. Call submit_review("${review.id}", "approved"/"changes_requested", "your feedback") to review.`, state.registeredName);
+    broadcastSystemMessage(`[REVIEW REQUEST] ${state.registeredName} requests review of "${review.file}": ${review.description || 'No description'}. To review: (1) read the file "${review.file}", (2) call submit_review("${review.id}", "approved"/"changes_requested", "<your findings — min 50 chars>"). Feedback is required and must be substantive.`, state.registeredName);
     touchActivity();
     return { success: true, review_id: review.id, file: review.file, next_action: 'Call listen() to wait for the review.' };
   }
 
+  const REVIEW_FEEDBACK_MIN_LENGTH = 50;
+
   function toolSubmitReview(reviewId, status, feedback) {
     if (!state.registeredName) return { error: 'You must call register() first' };
 
@@ -131,6 +133,26 @@ module.exports = function (ctx) {
     if (!review) return { error: `Review not found: ${reviewId}` };
     if (review.requested_by === state.registeredName) return { error: 'Cannot review your own code.' };
 
+    // Enforce substantive feedback — rubber-stamping is not allowed
+    const feedbackText = (feedback || '').trim();
+    if (!feedbackText) {
+      return {
+        error: `Feedback is required. You must read "${review.file}" and describe what you found before submitting a review.`,
+        next_action: `Read the file "${review.file}" first, then call submit_review("${reviewId}", "${status}", "<your findings>").`,
+      };
+    }
+    if (feedbackText.length < REVIEW_FEEDBACK_MIN_LENGTH) {
+      return {
+        error: `Feedback too short (${feedbackText.length} chars, minimum ${REVIEW_FEEDBACK_MIN_LENGTH}). Describe specific findings — what you read, what issues you found or verified, and why you ${status === 'approved' ? 'approve' : 'request changes'}.`,
+        next_action: `Read the file "${review.file}" first, then call submit_review("${reviewId}", "${status}", "<your detailed findings>").`,
+      };
+    }
+
+    // Log audit entry for thin approvals (short feedback on an approval)
+    if (status === 'approved' && feedbackText.length < 150) {
+      logViolation('thin_review', state.registeredName, `Approved "${review.file}" with minimal feedback (${feedbackText.length} chars): "${feedbackText.substring(0, 100)}"`);
+    }
+
     review.status = status;
     review.reviewer = state.registeredName;
     review.feedback = (feedback || '').substring(0, 2000);
@@ -384,12 +406,12 @@ module.exports = function (ctx) {
     {
       name: 'request_review',
       description: 'Request a code review from the team. Creates a review request and notifies all agents.',
-      inputSchema: { type: 'object', properties: { file_path: { type: 'string', description: 'File to review' }, description: { type: 'string', description: 'What to focus on in the review' } }, required: ['file_path'], additionalProperties: false },
+      inputSchema: { type: 'object', properties: { file_path: { type: 'string', description: 'File to review', maxLength: 500 }, description: { type: 'string', description: 'What to focus on in the review', maxLength: 2000 } }, required: ['file_path'], additionalProperties: false },
     },
     {
       name: 'submit_review',
-      description: 'Submit a code review — approve or request changes with feedback.',
-      inputSchema: { type: 'object', properties: { review_id: { type: 'string', description: 'Review ID' }, status: { type: 'string', enum: ['approved', 'changes_requested'], description: 'Review result' }, feedback: { type: 'string', description: 'Your review feedback (max 2000 chars)' } }, required: ['review_id', 'status'], additionalProperties: false },
+      description: 'Submit a code review — approve or request changes. You MUST read the file under review before calling this. Feedback is required (minimum 50 chars) and must describe specific findings — what you read, what issues you found or confirmed. Rubber-stamp approvals are rejected.',
+      inputSchema: { type: 'object', properties: { review_id: { type: 'string', description: 'Review ID', maxLength: 50 }, status: { type: 'string', enum: ['approved', 'changes_requested'], description: 'Review result' }, feedback: { type: 'string', description: 'Your findings from reading the file (required, min 50 chars). Describe what you read and what you found — bugs, security issues, correctness, or confirmation that the code is clean.', maxLength: 2000, minLength: 50 } }, required: ['review_id', 'status', 'feedback'], additionalProperties: false },
     },
     // Rules
     {
@@ -398,7 +420,7 @@ module.exports = function (ctx) {
       inputSchema: {
         type: 'object',
         properties: {
-          text: { type: 'string', description: 'The rule text' },
+          text: { type: 'string', description: 'The rule text', maxLength: 2000 },
           category: { type: 'string', description: 'Rule category: safety, workflow, code-style, communication, custom' },
           scope: {
             type: 'object',
@@ -433,7 +455,7 @@ module.exports = function (ctx) {
     {
       name: 'log_violation',
       description: 'Log a workflow rule violation to the audit trail. Used automatically by review gates, or manually to flag issues.',
-      inputSchema: { type: 'object', properties: { type: { type: 'string', description: 'Violation type: review_skipped, push_without_approval, rule_violated, etc.' }, details: { type: 'string', description: 'Description of the violation' } }, required: ['type'], additionalProperties: false },
+      inputSchema: { type: 'object', properties: { type: { type: 'string', description: 'Violation type: review_skipped, push_without_approval, rule_violated, etc.', maxLength: 100 }, details: { type: 'string', description: 'Description of the violation', maxLength: 2000 } }, required: ['type'], additionalProperties: false },
     },
     {
       name: 'request_push_approval',

package/tools/messaging.js

@@ -57,6 +57,8 @@ module.exports = function (ctx) {
       const oldestAge = Math.round((Date.now() - new Date(unconsumed[0].timestamp).getTime()) / 1000);
       result.urgency = oldestAge > 120 ? 'critical' : oldestAge > 30 ? 'urgent' : 'normal';
       result.next_action = 'Call listen() to receive and process these messages.';
+    } else {
+      result.next_action = 'Call listen() to wait for new messages.';
     }
 
     return result;

package/tools/safety.js

@@ -48,15 +48,15 @@ module.exports = function (ctx) {
         if (lock.agent === state.registeredName) { delete locks[fp]; count++; }
       }
       writeJsonFile(LOCKS_FILE, locks);
-      return { success: true, unlocked: count, message: `Unlocked ${count} file(s).` };
+      return { success: true, unlocked: count, message: `Unlocked ${count} file(s).`, next_action: 'Call listen() to receive messages.' };
     }
 
-    if (!locks[normalized]) return { success: true, message: 'File was not locked.' };
+    if (!locks[normalized]) return { success: true, message: 'File was not locked.', next_action: 'Call listen() to receive messages.' };
     if (locks[normalized].agent !== state.registeredName) return { error: `File is locked by ${locks[normalized].agent}, not you.` };
 
     delete locks[normalized];
     writeJsonFile(LOCKS_FILE, locks);
-    return { success: true, file: normalized, message: 'File unlocked.' };
+    return { success: true, file: normalized, message: 'File unlocked.', next_action: 'Call listen() to receive messages.' };
   }
 
   // --- Dependencies ---

package/tools/tasks.js

@@ -398,9 +398,9 @@ module.exports = function (ctx) {
       inputSchema: {
         type: 'object',
         properties: {
-          title: { type: 'string', description: 'Short task title' },
-          description: { type: 'string', description: 'Detailed task description' },
-          assignee: { type: 'string', description: 'Agent to assign to (optional, auto-assigns with 2 agents)' },
+          title: { type: 'string', description: 'Short task title', maxLength: 200 },
+          description: { type: 'string', description: 'Detailed task description', maxLength: 5000 },
+          assignee: { type: 'string', description: 'Agent to assign to (optional, auto-assigns with 2 agents)', maxLength: 50 },
         },
         required: ['title'],
         additionalProperties: false,
@@ -412,9 +412,9 @@ module.exports = function (ctx) {
       inputSchema: {
         type: 'object',
         properties: {
-          task_id: { type: 'string', description: 'Task ID to update' },
+          task_id: { type: 'string', description: 'Task ID to update', maxLength: 50 },
           status: { type: 'string', enum: ['pending', 'in_progress', 'in_review', 'done', 'blocked', 'blocked_permanent'], description: 'New status' },
-          notes: { type: 'string', description: 'Optional progress note' },
+          notes: { type: 'string', description: 'Optional progress note', maxLength: 2000 },
         },
         required: ['task_id', 'status'],
         additionalProperties: false,