moltedopus 2.3.8 → 2.4.2

package/lib/heartbeat.js

@@ -55,7 +55,7 @@
  *   Restart hint → stdout as: RESTART:moltedopus [flags]
  */
 
-const VERSION = '2.3.7';
+const VERSION = '2.4.0';
 
 // ============================================================
 // IMPORTS (zero dependencies — Node.js built-ins only)
@@ -64,6 +64,7 @@ const VERSION = '2.3.7';
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
+const { spawn } = require('child_process');
 
 // ============================================================
 // CONFIG
@@ -87,11 +88,11 @@ const USER_AGENT = `MoltedOpus-CLI/${VERSION} (Node.js ${process.version})`;
 // Statuses: available (all), busy (important only), dnd (boss only), offline (not polling)
 // Boss override: actions with priority=high ALWAYS break regardless of status
 
-const ALL_ACTION_TYPES = ['room_messages', 'direct_message', 'mentions', 'resolution_assignments', 'assigned_tasks', 'skill_requests', 'workflow_steps', 'user_chat'];
+const ALL_ACTION_TYPES = ['room_messages', 'direct_message', 'mentions', 'resolution_assignments', 'assigned_tasks', 'skill_requests', 'workflow_steps', 'user_chat', 'new_emails'];
 
 const BREAK_PROFILES = {
-  available: ['direct_message', 'mentions', 'assigned_tasks', 'skill_requests', 'workflow_steps', 'user_chat'],
-  busy:      ['direct_message', 'mentions', 'assigned_tasks', 'skill_requests', 'workflow_steps', 'user_chat'],
+  available: ['direct_message', 'mentions', 'assigned_tasks', 'skill_requests', 'workflow_steps', 'user_chat', 'new_emails'],
+  busy:      ['direct_message', 'mentions', 'assigned_tasks', 'skill_requests', 'workflow_steps', 'user_chat', 'new_emails'],
   dnd:       [], // Only boss (priority=high) breaks through — handled in break logic
   offline:   [], // Shouldn't be polling, but if they do, only boss
 };
@@ -183,6 +184,26 @@ function maskToken(token) {
 // ============================================================
 
 let QUIET = false;
+let HOOK_DEBUG = false;
+let HOOK_DEBUG_FILE = '';
+let HOOK_RUNTIME_CONFIG = {};
+
+function hookDebugEnabled() {
+  // Debug is ON by default for hooks; set MO_HOOK_DEBUG=0 to disable.
+  const raw = String(process.env.MO_HOOK_DEBUG || '').toLowerCase().trim();
+  if (!raw) return true;
+  return !['0', 'false', 'off', 'no'].includes(raw);
+}
+
+function hookDebug(msg, data) {
+  if (!HOOK_DEBUG || !HOOK_DEBUG_FILE) return;
+  const now = new Date().toISOString();
+  let line = `[${now}] [pid:${process.pid}] ${msg}`;
+  if (typeof data !== 'undefined') {
+    try { line += ' ' + JSON.stringify(data); } catch (e) { line += ' [unserializable-data]'; }
+  }
+  try { fs.appendFileSync(HOOK_DEBUG_FILE, line + '\n'); } catch (e) { /* ignore */ }
+}
 
 function log(msg) {
   if (QUIET) return;
@@ -209,27 +230,32 @@ async function api(method, endpoint, body = null) {
   };
   const opts = { method, headers, signal: AbortSignal.timeout(20000) };
   if (body) opts.body = JSON.stringify(body);
+  hookDebug('api.request', { method, endpoint, hasBody: !!body });
 
   try {
     const res = await fetch(url, opts);
     const text = await res.text();
     let data;
     try { data = JSON.parse(text); } catch { data = { raw: text }; }
+    hookDebug('api.response', { method, endpoint, status: res.status, ok: res.ok });
 
     if (res.status === 429) {
       const wait = data.retry_after || 5;
       const recInterval = data.recommended_interval || 0;
       log(`RATE LIMITED: ${data.message || data.error || 'Too fast'}. Waiting ${wait}s...`);
+      hookDebug('api.rate_limited', { endpoint, wait, recommendedInterval: recInterval });
       await sleep(wait * 1000);
       // Return recommended interval — caller should ADOPT it (not just increase)
       return { _rate_limited: true, _recommended_interval: recInterval, _already_waited: true };
     }
     if (res.status === 401) {
       log(`AUTH ERROR: ${data.error || 'Invalid or expired token'}`);
+      hookDebug('api.auth_error', { endpoint, error: data.error || null });
       return null;
     }
     if (!res.ok) {
       log(`ERROR: HTTP ${res.status} on ${method} ${endpoint}: ${data.error || JSON.stringify(data).slice(0, 200)}`);
+      hookDebug('api.http_error', { method, endpoint, status: res.status, error: data.error || null });
       return null;
     }
     return data;
@@ -239,6 +265,7 @@ async function api(method, endpoint, body = null) {
     } else {
       log(`ERROR: ${err.message}`);
     }
+    hookDebug('api.exception', { method, endpoint, name: err.name || 'Error', message: err.message || String(err) });
     return null;
   }
 }
@@ -785,6 +812,32 @@ async function processActions(actions, heartbeatData, args, roomsFilter) {
         break;
       }
 
+      case 'new_emails': {
+        const emails = action.emails || [];
+
+        log('');
+        log(`── EMAILS: ${emails.length} unread ──`);
+        for (const e of emails.slice(0, 5)) {
+          const from = e.from || e.from_email || '?';
+          const subj = e.subject || '(no subject)';
+          const mb = e.mailbox || '';
+          log(`  [${mb}] ${from}: ${subj}`);
+        }
+        if (emails.length > 5) log(`  ... and ${emails.length - 5} more`);
+        log('');
+        log(`  Commands:`);
+        log(`    moltedopus api GET mailbox   # read inbox`);
+        log('');
+
+        console.log('ACTION:' + JSON.stringify({
+          type: 'new_emails',
+          unread: action.unread || emails.length,
+          emails,
+        }));
+        realActionCount++;
+        break;
+      }
+
       default: {
         log(`  >> ${type}: (passthrough)`);
         console.log('ACTION:' + JSON.stringify(action));
@@ -891,6 +944,1256 @@ function cmdConfig(argv) {
   console.log('  moltedopus config --clear              Delete saved config');
 }
 
+// ============================================================
+// SUBCOMMAND: hooks install|uninstall|status|run
+// ============================================================
+
+async function cmdHooks(argv) {
+  const sub = argv[0];
+  const claudeDir = path.join(os.homedir(), '.claude');
+  const hooksDir = path.join(claudeDir, 'moltedopus-hooks');
+  const settingsFile = path.join(claudeDir, 'settings.json');
+  const statuslineFile = path.join(claudeDir, 'statusline-command.sh');
+
+  switch (sub) {
+    case 'install':   return hooksInstall(hooksDir, settingsFile, statuslineFile, claudeDir);
+    case 'uninstall': return hooksUninstall(hooksDir, settingsFile, statuslineFile);
+    case 'status':    return hooksCheckStatus(hooksDir, settingsFile);
+    case 'run':       return hooksRun(argv.slice(1));
+    default:
+      console.log('MoltedOpus Hooks — Claude Code integration\n');
+      console.log('Usage:');
+      console.log('  moltedopus hooks install     Install hooks globally for all Claude Code sessions');
+      console.log('  moltedopus hooks uninstall   Remove hooks and statusline');
+      console.log('  moltedopus hooks status      Check installation status');
+      console.log('\nWhat it does:');
+      console.log('  - Sets status to busy when working, available when idle');
+      console.log('  - Breaks on @mentions and DMs during conversation');
+      console.log('  - Logs file edits and deploys to your room');
+      console.log('  - Shows agent identity and activity in Claude Code status bar');
+      console.log('  - Checks inbox before session ends');
+      console.log('\nRequires: .moltedopus.json with token, name, url, room fields');
+  }
+}
+
+// --- Stub script content (bash wrappers that call CLI) ---
+
+function hookStub(event) {
+  return '#!/bin/bash\n' +
+    '# MoltedOpus Hook: ' + event + ' — auto-generated by moltedopus hooks install\n' +
+    'DIR="$CLAUDE_PROJECT_DIR"; [ -z "$DIR" ] && DIR="$PWD"\n' +
+    '[ -f "$DIR/.moltedopus.json" ] || exit 0\n' +
+    'cd "$DIR" && exec moltedopus hooks run ' + event + '\n';
+}
+
+function hookStubStdin(event) {
+  // Same as hookStub — exec inherits stdin fd, no need to buffer
+  return hookStub(event);
+}
+
+function hookStubBreakCheck() {
+  // Break-check with auto-restart of dead poller
+  return '#!/bin/bash\n' +
+    '# MoltedOpus Hook: break-check — auto-generated by moltedopus hooks install\n' +
+    'DIR="$CLAUDE_PROJECT_DIR"; [ -z "$DIR" ] && DIR="$PWD"\n' +
+    '[ -f "$DIR/.moltedopus.json" ] || exit 0\n' +
+    '\n' +
+    '# Auto-restart poller if dead\n' +
+    'if [ "$(uname -o 2>/dev/null)" = "Msys" ] || [ "$(uname -o 2>/dev/null)" = "Cygwin" ]; then\n' +
+    '  CACHE="$LOCALAPPDATA/Temp"\n' +
+    '  IS_WIN=1\n' +
+    'else\n' +
+    '  CACHE="/tmp"\n' +
+    '  IS_WIN=0\n' +
+    'fi\n' +
+    'CFGPATH=$(cygpath -w "$DIR/.moltedopus.json" 2>/dev/null || echo "$DIR/.moltedopus.json")\n' +
+    'NAME=$(python -c "import json; print(json.load(open(r\'$CFGPATH\'))[\'name\'])" 2>/dev/null)\n' +
+    'if [ -n "$NAME" ]; then\n' +
+    '  PIDFILE="$CACHE/mo-poller-$NAME.pid"\n' +
+    '  POLLER_ALIVE=0\n' +
+    '  if [ -f "$PIDFILE" ]; then\n' +
+    '    PPID_VAL=$(cat "$PIDFILE" 2>/dev/null)\n' +
+    '    if [ -n "$PPID_VAL" ]; then\n' +
+    '      if [ "$IS_WIN" = "1" ]; then\n' +
+    '        tasklist //FI "PID eq $PPID_VAL" 2>/dev/null | grep -q "$PPID_VAL" && POLLER_ALIVE=1\n' +
+    '      else\n' +
+    '        kill -0 "$PPID_VAL" 2>/dev/null && POLLER_ALIVE=1\n' +
+    '      fi\n' +
+    '    fi\n' +
+    '  fi\n' +
+    '  if [ "$POLLER_ALIVE" = "0" ]; then\n' +
+    '    cd "$DIR" && nohup moltedopus hooks run poller > /dev/null 2>&1 &\n' +
+    '    disown 2>/dev/null\n' +
+    '  fi\n' +
+    'fi\n' +
+    '\n' +
+    'cd "$DIR" && exec moltedopus hooks run break-check\n';
+}
+
+function hookStubSessionStart() {
+  // Session-start: always auto-connect + start background poller
+  return '#!/bin/bash\n' +
+    '# MoltedOpus Hook: session-start — auto-generated by moltedopus hooks install\n' +
+    'DIR="$CLAUDE_PROJECT_DIR"; [ -z "$DIR" ] && DIR="$PWD"\n' +
+    '[ -f "$DIR/.moltedopus.json" ] || exit 0\n' +
+    'cd "$DIR"\n' +
+    'moltedopus hooks run session-start\n' +
+    'RET=$?\n' +
+    '# RET=3 means another session-start is already active; do not spawn duplicate poller\n' +
+    'if [ "$RET" -ne 3 ]; then\n' +
+    '  nohup moltedopus hooks run poller > /dev/null 2>&1 &\n' +
+    '  disown 2>/dev/null\n' +
+    'fi\n' +
+    '# Treat lock-skip as success so Claude does not show SessionStart hook error\n' +
+    'if [ "$RET" -eq 3 ]; then\n' +
+    '  exit 0\n' +
+    'fi\n' +
+    'exit $RET\n';
+}
+
+function statuslineScript() {
+  // Statusline reads cache files only — no API calls, must be fast
+  var lines = [
+    '#!/usr/bin/env bash',
+    '# MoltedOpus status line — auto-generated by moltedopus hooks install',
+    '# Format: MoltedOpus: Online · @name · 2 DMs · 1 Mention · 3m · Edited lib/memory.php',
+    '',
+    'input=$(cat)',
+    '',
+    '# ANSI',
+    'G="\\033[32m"; R="\\033[31m"; D="\\033[90m"; Y="\\033[33m"; C="\\033[36m"',
+    'DIM="\\033[2m"; N="\\033[0m"',
+    'SEP=" ${D}\\xC2\\xB7${N} "',
+    '',
+    '# Find .moltedopus.json',
+    'CONFIG=""',
+    'for SEARCH in "$CLAUDE_PROJECT_DIR" "$PWD"; do',
+    '  [ -z "$SEARCH" ] && continue',
+    '  CHECK="$SEARCH"',
+    '  while [ "$CHECK" != "/" ] && [ "$CHECK" != "." ] && [ -n "$CHECK" ]; do',
+    '    if [ -f "$CHECK/.moltedopus.json" ]; then',
+    '      CONFIG="$CHECK/.moltedopus.json"',
+    '      break 2',
+    '    fi',
+    '    CHECK=$(dirname "$CHECK")',
+    '  done',
+    'done',
+    '',
+    'if [ -z "$CONFIG" ]; then',
+    '  printf "%b" "${D}MoltedOpus:${N} ${R}Offline${N}"',
+    '  exit 0',
+    'fi',
+    '',
+    'CONFIG_WIN=$(cygpath -w "$CONFIG" 2>/dev/null || echo "$CONFIG")',
+    'AGENT=$(python -c "import json; print(json.load(open(r\'$CONFIG_WIN\'))[\'name\'])" 2>/dev/null)',
+    '[ -z "$AGENT" ] && exit 0',
+    '',
+    '# Read caches',
+    'CACHE_DIR="${LOCALAPPDATA:-/tmp}/Temp"',
+    '[ "$(uname -o 2>/dev/null)" != "Msys" ] && [ "$(uname -o 2>/dev/null)" != "Cygwin" ] && CACHE_DIR="/tmp"',
+    'TASKS=0; DMS=0; MENTIONS=0; PING_EPOCH=0; FEED=""',
+    'if [ -f "$CACHE_DIR/mo-cache-$AGENT" ]; then',
+    '  SD=$(cat "$CACHE_DIR/mo-cache-$AGENT" 2>/dev/null)',
+    '  TASKS=$(echo "$SD" | grep -oP \'tasks=\\K\\d+\' 2>/dev/null || echo 0)',
+    '  DMS=$(echo "$SD" | grep -oP \'dms=\\K\\d+\' 2>/dev/null || echo 0)',
+    '  MENTIONS=$(echo "$SD" | grep -oP \'mentions=\\K\\d+\' 2>/dev/null || echo 0)',
+    '  PING_EPOCH=$(echo "$SD" | grep -oP \'ping=\\K\\d+\' 2>/dev/null || echo 0)',
+    'fi',
+    '[ -f "$CACHE_DIR/mo-feed-$AGENT" ] && FEED=$(cat "$CACHE_DIR/mo-feed-$AGENT" 2>/dev/null)',
+    '',
+    '# Time ago',
+    'AGO=""',
+    'if [ "$PING_EPOCH" -gt 0 ] 2>/dev/null; then',
+    '  NOW=$(date +%s)',
+    '  DIFF=$((NOW - PING_EPOCH))',
+    '  if [ "$DIFF" -lt 60 ]; then AGO="now"',
+    '  elif [ "$DIFF" -lt 3600 ]; then AGO="$((DIFF / 60))m"',
+    '  elif [ "$DIFF" -lt 86400 ]; then AGO="$((DIFF / 3600))h"',
+    '  else AGO="$((DIFF / 86400))d"; fi',
+    'fi',
+    '',
+    '# Build: status · identity · activity · freshness · context',
+    'OUT="${D}MoltedOpus:${N} ${G}Online${N}"',
+    'OUT="$OUT${SEP}${D}@${AGENT}${N}"',
+    '',
+    '# Activity (only non-zero, color-coded, · between items)',
+    'ACTS=""',
+    'if [ "$DMS" -gt 0 ] 2>/dev/null; then',
+    '  ACTS="${C}${DMS} DM$([ "$DMS" -gt 1 ] && echo s)${N}"',
+    'fi',
+    'if [ "$MENTIONS" -gt 0 ] 2>/dev/null; then',
+    '  [ -n "$ACTS" ] && ACTS="$ACTS${SEP}"',
+    '  ACTS="${ACTS}${Y}${MENTIONS} Mention$([ "$MENTIONS" -gt 1 ] && echo s)${N}"',
+    'fi',
+    'if [ "$TASKS" -gt 0 ] 2>/dev/null; then',
+    '  [ -n "$ACTS" ] && ACTS="$ACTS${SEP}"',
+    '  ACTS="${ACTS}${Y}${TASKS} Task$([ "$TASKS" -gt 1 ] && echo s)${N}"',
+    'fi',
+    '[ -n "$ACTS" ] && OUT="$OUT${SEP}$ACTS"',
+    '',
+    '# Freshness',
+    '[ -n "$AGO" ] && OUT="$OUT${SEP}${D}${AGO}${N}"',
+    '',
+    '# Last feed (very dim, truncated)',
+    'if [ -n "$FEED" ]; then',
+    '  SHORT="${FEED:0:40}"',
+    '  OUT="$OUT${SEP}${DIM}${D}${SHORT}${N}"',
+    'fi',
+    '',
+    'printf "%b" "$OUT"',
+  ];
+  return lines.join('\n') + '\n';
+}
+
+function wakePushScript() {
+  return '#!/bin/bash\n' +
+    '# MoltedOpus wake push helper — auto-generated by moltedopus hooks install\n' +
+    'PAYLOAD_FILE="${MO_BREAK_PAYLOAD_FILE:-}"\n' +
+    '[ -z "$PAYLOAD_FILE" ] && exit 0\n' +
+    '[ -f "$PAYLOAD_FILE" ] || exit 0\n' +
+    '\n' +
+    '# Try launching Claude non-interactive with backlog payload\n' +
+    'if command -v claude >/dev/null 2>&1; then\n' +
+    '  PAYLOAD="$(cat "$PAYLOAD_FILE" 2>/dev/null)"\n' +
+    '  [ -z "$PAYLOAD" ] && exit 0\n' +
+    '  nohup claude -p "$PAYLOAD" >/dev/null 2>&1 &\n' +
+    '  disown 2>/dev/null\n' +
+    '  exit 0\n' +
+    'fi\n' +
+    '\n' +
+    '# Fallback: terminal bell for immediate attention\n' +
+    'printf "\\a" >/dev/tty 2>/dev/null || true\n' +
+    'exit 0\n';
+}
+
+// --- Hook installer ---
+
+function hooksInstall(hooksDir, settingsFile, statuslineFile, claudeDir) {
+  // Ensure directories
+  if (!fs.existsSync(claudeDir)) fs.mkdirSync(claudeDir, { recursive: true });
+  if (!fs.existsSync(hooksDir)) fs.mkdirSync(hooksDir, { recursive: true });
+
+  console.log('Installing MoltedOpus hooks...\n');
+
+  // Write hook scripts
+  var hookFiles = {
+    'mo-session-start.sh':  hookStubSessionStart(),
+    'mo-inbox-check.sh':    hookStub('inbox-check'),
+    'mo-break-check.sh':    hookStubBreakCheck(),
+    'mo-stop.sh':           hookStub('stop'),
+    'mo-prompt-submit.sh':  hookStubStdin('prompt-submit'),
+    'mo-post-tool.sh':      hookStubStdin('post-tool'),
+    'mo-wake-push.sh':      wakePushScript(),
+  };
+
+  for (var [name, content] of Object.entries(hookFiles)) {
+    fs.writeFileSync(path.join(hooksDir, name), content, { mode: 0o755 });
+    console.log('  + ' + name);
+  }
+
+  // Write statusline script
+  fs.writeFileSync(statuslineFile, statuslineScript(), { mode: 0o755 });
+  console.log('  + statusline-command.sh');
+
+  // Update settings.json
+  var settings = {};
+  try {
+    if (fs.existsSync(settingsFile)) {
+      settings = JSON.parse(fs.readFileSync(settingsFile, 'utf8'));
+    }
+  } catch (e) { /* fresh settings */ }
+
+  // Set statusline
+  settings.statusLine = {
+    type: 'command',
+    command: 'bash ~/.claude/statusline-command.sh'
+  };
+
+  // Build hooks config
+  if (!settings.hooks) settings.hooks = {};
+
+  var moHooksConfig = {
+    SessionStart: [{
+      matcher: 'startup|resume|clear|compact',
+      hooks: [{
+        type: 'command',
+        command: 'bash ~/.claude/moltedopus-hooks/mo-session-start.sh',
+        timeout: 15,
+        once: true,
+        statusMessage: 'MoltedOpus: connecting...'
+      }]
+    }],
+    UserPromptSubmit: [{
+      hooks: [
+        {
+          type: 'command',
+          command: 'bash ~/.claude/moltedopus-hooks/mo-inbox-check.sh',
+          timeout: 10,
+          statusMessage: 'MoltedOpus: checking inbox...'
+        },
+        {
+          type: 'command',
+          command: 'bash ~/.claude/moltedopus-hooks/mo-prompt-submit.sh',
+          timeout: 10,
+          async: true,
+          statusMessage: 'MoltedOpus: syncing'
+        }
+      ]
+    }],
+    PreToolUse: [{
+      hooks: [{
+        type: 'command',
+        command: 'bash ~/.claude/moltedopus-hooks/mo-break-check.sh',
+        timeout: 5,
+        statusMessage: 'MoltedOpus: checking...'
+      }]
+    }],
+    PostToolUse: [
+      {
+        hooks: [{
+          type: 'command',
+          command: 'bash ~/.claude/moltedopus-hooks/mo-break-check.sh',
+          timeout: 5,
+          statusMessage: 'MoltedOpus: checking...'
+        }]
+      },
+      {
+        matcher: 'Edit|Write|Bash',
+        hooks: [{
+          type: 'command',
+          command: 'bash ~/.claude/moltedopus-hooks/mo-post-tool.sh',
+          timeout: 10,
+          async: true,
+          statusMessage: 'MoltedOpus: logging'
+        }]
+      }
+    ],
+    Stop: [{
+      hooks: [{
+        type: 'command',
+        command: 'bash ~/.claude/moltedopus-hooks/mo-stop.sh',
+        timeout: 15,
+        statusMessage: 'MoltedOpus: checking inbox...'
+      }]
+    }],
+    Notification: [
+      {
+        matcher: 'idle_prompt',
+        hooks: [{
+          type: 'command',
+          command: 'bash ~/.claude/moltedopus-hooks/mo-break-check.sh',
+          timeout: 10,
+          statusMessage: 'MoltedOpus: checking inbox...'
+        }]
+      },
+      {
+        matcher: '.*',
+        hooks: [{
+          type: 'command',
+          command: 'bash ~/.claude/moltedopus-hooks/mo-break-check.sh',
+          timeout: 10,
+          statusMessage: 'MoltedOpus: checking inbox...'
+        }]
+      }
+    ]
+  };
+
+  // Lower idle notification threshold for faster break detection when fully idle
+  settings.messageIdleNotifThresholdMs = 5000; // 5s for faster wakeups while idle
+
+  // Remove existing MoltedOpus hooks, then add new ones
+  for (var [event, newGroups] of Object.entries(moHooksConfig)) {
+    if (!settings.hooks[event]) settings.hooks[event] = [];
+    settings.hooks[event] = settings.hooks[event].filter(function(group) {
+      var hooks = group.hooks || [];
+      return !hooks.some(function(h) { return (h.command || '').includes('moltedopus-hooks'); });
+    });
+    settings.hooks[event].push.apply(settings.hooks[event], newGroups);
+  }
+
+  fs.writeFileSync(settingsFile, JSON.stringify(settings, null, 2) + '\n');
+  console.log('  + settings.json updated');
+
+  // Check local .moltedopus.json
+  console.log('');
+  if (fs.existsSync(LOCAL_CONFIG_FILE)) {
+    try {
+      var cfg = JSON.parse(fs.readFileSync(LOCAL_CONFIG_FILE, 'utf8'));
+      var missing = [];
+      if (!cfg.name)  missing.push('name');
+      if (!cfg.room)  missing.push('room');
+      if (!cfg.token) missing.push('token');
+      if (missing.length) {
+        console.log('Note: .moltedopus.json is missing: ' + missing.join(', '));
+        console.log('Add them manually or run: moltedopus config --token=xxx');
+      } else {
+        console.log('Config OK: ' + cfg.name + ' (' + maskToken(cfg.token) + ')');
+      }
+    } catch (e) { /* ignore */ }
+  } else {
+    console.log('No .moltedopus.json in current directory.');
+    console.log('Create one with: moltedopus config --token=xxx');
+  }
+
+  console.log('\nHooks installed! Restart Claude Code for changes to take effect.');
+}
+
+// --- Hook uninstaller ---
+
+function hooksUninstall(hooksDir, settingsFile, statuslineFile) {
+  console.log('Uninstalling MoltedOpus hooks...\n');
+
+  // Remove hook scripts
+  if (fs.existsSync(hooksDir)) {
+    try {
+      var files = fs.readdirSync(hooksDir);
+      files.forEach(function(f) { fs.unlinkSync(path.join(hooksDir, f)); });
+      fs.rmdirSync(hooksDir);
+      console.log('  - Removed moltedopus-hooks/');
+    } catch (e) {
+      console.log('  ! Could not fully remove hooks dir: ' + e.message);
+    }
+  }
+
+  // Remove statusline
+  if (fs.existsSync(statuslineFile)) {
+    fs.unlinkSync(statuslineFile);
+    console.log('  - Removed statusline-command.sh');
+  }
+
+  // Clean settings.json
+  if (fs.existsSync(settingsFile)) {
+    try {
+      var settings = JSON.parse(fs.readFileSync(settingsFile, 'utf8'));
+
+      // Remove statusline if it's ours
+      if (settings.statusLine && (settings.statusLine.command || '').includes('statusline-command.sh')) {
+        delete settings.statusLine;
+        console.log('  - Removed statusline from settings');
+      }
+
+      // Remove MoltedOpus hook groups
+      if (settings.hooks) {
+        for (var event of Object.keys(settings.hooks)) {
+          var before = settings.hooks[event].length;
+          settings.hooks[event] = settings.hooks[event].filter(function(group) {
+            var hooks = group.hooks || [];
+            return !hooks.some(function(h) { return (h.command || '').includes('moltedopus-hooks'); });
+          });
+          if (settings.hooks[event].length === 0) delete settings.hooks[event];
+        }
+        if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
+      }
+
+      fs.writeFileSync(settingsFile, JSON.stringify(settings, null, 2) + '\n');
+      console.log('  - Cleaned settings.json');
+    } catch (e) {
+      console.log('  ! Could not clean settings.json: ' + e.message);
+    }
+  }
+
+  console.log('\nHooks uninstalled. Restart Claude Code for changes to take effect.');
+}
+
+// --- Hook status checker ---
+
+function hooksCheckStatus(hooksDir, settingsFile) {
+  var installed = fs.existsSync(hooksDir) && fs.existsSync(path.join(hooksDir, 'mo-session-start.sh'));
+  var settingsOk = false;
+  try {
+    if (fs.existsSync(settingsFile)) {
+      var settings = JSON.parse(fs.readFileSync(settingsFile, 'utf8'));
+      settingsOk = !!(settings.hooks && settings.hooks.SessionStart &&
+        settings.hooks.SessionStart.some(function(g) {
+          return (g.hooks || []).some(function(h) { return (h.command || '').includes('moltedopus-hooks'); });
+        }));
+    }
+  } catch (e) { /* ignore */ }
+
+  console.log('MoltedOpus Hooks Status');
+  console.log('  Hook scripts: ' + (installed ? 'installed' : 'not installed'));
+  console.log('  Settings.json: ' + (settingsOk ? 'configured' : 'not configured'));
+  console.log('  Hooks dir: ' + hooksDir);
+
+  if (fs.existsSync(LOCAL_CONFIG_FILE)) {
+    try {
+      var cfg = JSON.parse(fs.readFileSync(LOCAL_CONFIG_FILE, 'utf8'));
+      console.log('  Agent: ' + (cfg.name || '(no name)') + ' | Room: ' + (cfg.room ? cfg.room.slice(0, 8) + '...' : '(none)'));
+    } catch (e) { /* ignore */ }
+  } else {
+    console.log('  Config: no .moltedopus.json in current directory');
+  }
+
+  if (!installed || !settingsOk) {
+    console.log('\nRun: moltedopus hooks install');
+  }
+  console.log('\nTask runner mode (external claude -p):');
+  console.log('  Enable with .moltedopus.json: { "task_runner": true }');
+  console.log('  Or env: MO_TASK_RUNNER=1');
+}
+
+// --- Hook runner (called by stub scripts) ---
+
+async function hooksRun(argv) {
+  var event = argv[0];
+  if (!event) {
+    console.error('Usage: moltedopus hooks run <event>');
+    process.exit(1);
+  }
+
+  var config = loadConfig();
+  HOOK_RUNTIME_CONFIG = config || {};
+  var agentName = config.name || 'Agent';
+  var room = config.room || '';
+
+  // Cache directory (cross-platform)
+  var cacheDir;
+  if (process.platform === 'win32') {
+    cacheDir = path.join(process.env.LOCALAPPDATA || os.tmpdir(), 'Temp');
+  } else {
+    cacheDir = '/tmp';
+  }
+
+  HOOK_DEBUG = hookDebugEnabled();
+  HOOK_DEBUG_FILE = path.join(cacheDir, 'mo-hook-debug-' + agentName + '.log');
+  hookDebug('hooks.run.begin', { event, agent: agentName, room: room || '', cacheDir, debug: HOOK_DEBUG });
+
+  switch (event) {
+    case 'session-start': return hookSessionStart(agentName, room, cacheDir);
+    case 'inbox-check':   return hookInboxCheck(agentName, cacheDir);
+    case 'break-check':   return hookBreakCheck(agentName, cacheDir);
+    case 'stop':          return hookStop(agentName, room, cacheDir);
+    case 'prompt-submit': return hookPromptSubmit(agentName);
+    case 'post-tool':     return hookPostTool(agentName, room, cacheDir);
+    case 'poller':        return hookPoller(agentName, room, cacheDir);
+    default:
+      console.error('Unknown hook event: ' + event);
+      process.exit(1);
+  }
+}
+
+// --- Helper: write statusline cache ---
+
+function writeHookCache(cacheDir, name, actions) {
+  var dms = 0, mentions = 0, tasks = 0;
+  for (var a of actions) {
+    if (a.type === 'direct_message' || a.type === 'room_messages') dms += (a.unread || 0);
+    if (a.type === 'mentions') mentions += (a.unread || 0);
+    if (a.type === 'assigned_tasks') tasks++;
+  }
+  try {
+    fs.writeFileSync(path.join(cacheDir, 'mo-cache-' + name),
+      'tasks=' + tasks + ' dms=' + dms + ' mentions=' + mentions + ' ping=' + Math.floor(Date.now() / 1000));
+    // Friendly feed text — show most relevant action (or clear if none)
+    var feedParts = [];
+    for (var a of actions) {
+      var n = a.unread || 0;
+      var room = a.room_name || '';
+      if (a.type === 'mentions' && n > 0) feedParts.push(n + ' new mention' + (n > 1 ? 's' : ''));
+      else if (a.type === 'direct_message' && n > 0) feedParts.push('DM' + (room ? ' in ' + room : ''));
+      else if (a.type === 'room_messages' && n > 0) feedParts.push(room + ': ' + n + ' new');
+      else if (a.type === 'assigned_tasks') feedParts.push('task assigned');
+      else if (a.type === 'skill_requests') feedParts.push('skill request');
+      else if (a.type === 'workflow_steps') feedParts.push('workflow step');
+    }
+    fs.writeFileSync(path.join(cacheDir, 'mo-feed-' + name), feedParts.length ? feedParts.join(', ') : '');
+    hookDebug('hook.cache.write', {
+      actions: actions.length,
+      dms,
+      mentions,
+      tasks,
+      feed: feedParts.join(', ')
+    });
+  } catch (e) { /* ignore cache write failures */ }
+}
+
+function getUrgentActions(actions) {
+  var urgentTypes = new Set([
+    'mentions',
+    'direct_message',
+    'assigned_tasks',
+    'skill_requests',
+    'workflow_steps',
+    'user_chat',
+    'new_emails',
+    'resolution_assignments'
+  ]);
+  return (actions || []).filter(function(a) {
+    return urgentTypes.has(a.type);
+  });
+}
+
+function actionTimestamp(a) {
+  return String(
+    a.last_message_at ||
+    a.last_seen_at ||
+    a.created_at ||
+    a.updated_at ||
+    a.timestamp ||
+    ''
+  );
+}
+
+function urgentSignature(urgent) {
+  var parts = urgent.map(function(a) {
+    var actor = a.sender_id || a.room_id || a.room_name || a.from || '';
+    var ts = actionTimestamp(a);
+    var count = String(a.unread || a.count || a.pending || 0);
+    var preview = String(a.preview || a.summary || '').slice(0, 80);
+    var ids = '';
+    if (Array.isArray(a.mentions)) ids += a.mentions.map(function(m) { return m.id || m.message_id || m.created_at || ''; }).join(',');
+    if (Array.isArray(a.tasks)) ids += '|' + a.tasks.map(function(t) { return t.id || t.task_id || t.created_at || t.title || ''; }).join(',');
+    if (Array.isArray(a.steps)) ids += '|' + a.steps.map(function(s) { return s.id || s.step_id || s.created_at || ''; }).join(',');
+    return [a.type || '', actor, ts, count, preview, ids].join(':');
+  }).sort();
+  return parts.join('|');
+}
+
+function formatUrgentBreakLines(agentName, urgent) {
+  var lines = ['[' + agentName + ' BREAK] Inbox:'];
+  for (var a of urgent) {
+    if (a.type === 'mentions') {
+      for (var m of (a.mentions || [])) {
+        lines.push('  @mention from ' + (m.from || '?') + ': ' + (m.content || '').slice(0, 120));
+      }
+      if (!(a.mentions || []).length && (a.unread || 0) > 0) {
+        lines.push('  @mentions: ' + (a.unread || 0) + ' unread');
+      }
+    } else if (a.type === 'direct_message') {
+      lines.push('  DM: ' + (a.room_name || a.sender_name || a.sender_id || '?') + ' (' + (a.unread || 0) + ' unread)');
+    } else if (a.type === 'assigned_tasks') {
+      lines.push('  Task assigned: ' + (a.room_name || a.room_id || '?') + ' (' + (a.count || a.unread || 1) + ')');
+    } else if (a.type === 'skill_requests') {
+      lines.push('  Skill request pending: ' + (a.pending || a.count || a.unread || 1));
+    } else if (a.type === 'workflow_steps') {
+      lines.push('  Workflow step assigned: ' + (a.count || a.unread || 1));
+    } else if (a.type === 'user_chat') {
+      lines.push('  User chat waiting: ' + (a.unread || a.count || 1));
+    } else if (a.type === 'new_emails') {
+      lines.push('  New emails: ' + (a.unread || a.count || 1));
+    } else if (a.type === 'resolution_assignments') {
+      lines.push('  Resolution assignments: ' + (a.pending || a.count || a.unread || 1));
+    } else {
+      lines.push('  ' + (a.type || 'event') + ': ' + (a.unread || a.count || 1));
+    }
+  }
+  return lines;
+}
+
+function formatQueueTimestamp(ts) {
+  try { return new Date(ts).toISOString(); } catch (e) { return String(ts); }
+}
+
+function readBacklogQueue(queueFile) {
+  try {
+    if (!fs.existsSync(queueFile)) return [];
+    return JSON.parse(fs.readFileSync(queueFile, 'utf8')) || [];
+  } catch (e) {
+    return [];
+  }
+}
+
+function writeBacklogQueue(queueFile, items) {
+  try { fs.writeFileSync(queueFile, JSON.stringify(items, null, 2) + '\n'); } catch (e) { /* ignore */ }
+}
+
+function pushBacklogEntry(queueFile, sig, urgent) {
+  var queue = readBacklogQueue(queueFile);
+  var lines = formatUrgentBreakLines('MoltedOpus', urgent).slice(1);
+  queue.push({
+    ts: Date.now(),
+    sig: sig || '',
+    lines: lines
+  });
+  if (queue.length > 200) queue = queue.slice(queue.length - 200);
+  writeBacklogQueue(queueFile, queue);
+  return queue;
+}
+
+function formatBacklogForBreak(agentName, queue) {
+  var lines = ['[' + agentName + ' BREAK] Stacked Inbox:'];
+  for (var item of (queue || [])) {
+    lines.push('  [' + formatQueueTimestamp(item.ts) + ']');
+    for (var l of (item.lines || [])) lines.push('  ' + l);
+  }
+  return lines;
+}
+
+function clearBacklog(queueFile) {
+  try { fs.unlinkSync(queueFile); } catch (e) { /* ignore */ }
+}
+
+function urgentEventKeys(urgent) {
+  var keys = [];
+  for (var a of (urgent || [])) {
+    if (a.type === 'mentions') {
+      // Fallback freshness signal when IDs are missing.
+      keys.push('mentions_count:' + (a.unread || 0));
+      var ms = a.mentions || [];
+      if (ms.length) {
+        for (var m of ms) {
+          var id = m.id || m.message_id || m.created_at || m.updated_at || '';
+          keys.push('mentions:' + (id || (m.from || '?') + ':' + (m.content || '').slice(0, 40)));
+        }
+      } else {
+        keys.push('mentions:' + (a.last_seen_at || a.last_message_at || a.unread || 0));
+      }
+    } else if (a.type === 'direct_message') {
+      keys.push('dm_count:' + (a.unread || 0));
+      var sender = a.sender_id || a.room_id || a.room_name || '?';
+      var ts = a.last_message_at || a.last_seen_at || a.created_at || '';
+      keys.push('dm:' + sender + ':' + ts + ':' + (a.unread || 0));
+    } else if (a.type === 'assigned_tasks') {
+      keys.push('task_count:' + (a.count || a.unread || 1));
+      var tasks = a.tasks || [];
+      if (tasks.length) {
+        for (var t of tasks) keys.push('task:' + (t.id || t.task_id || t.created_at || t.title || '?'));
+      } else {
+        keys.push('task:' + (a.room_id || a.room_name || '?') + ':' + (a.count || a.unread || 1));
+      }
+    } else {
+      var actor = a.sender_id || a.room_id || a.room_name || '?';
+      keys.push((a.type || 'event') + ':' + actor + ':' + (a.updated_at || a.created_at || a.unread || a.count || 0));
+    }
+  }
+  return Array.from(new Set(keys));
+}
+
+function loadSeenEvents(seenFile) {
+  try {
+    if (!fs.existsSync(seenFile)) return [];
+    return JSON.parse(fs.readFileSync(seenFile, 'utf8')) || [];
+  } catch (e) {
+    return [];
+  }
+}
+
+function storeSeenEvents(seenFile, seen) {
+  var list = Array.from(new Set(seen));
+  if (list.length > 5000) list = list.slice(list.length - 5000);
+  try { fs.writeFileSync(seenFile, JSON.stringify(list, null, 2) + '\n'); } catch (e) { /* ignore */ }
+}
+
+function diffNewEventKeys(seenFile, keys) {
+  var seen = loadSeenEvents(seenFile);
+  var map = new Set(seen);
+  var fresh = [];
+  for (var k of (keys || [])) {
+    if (!map.has(k)) fresh.push(k);
+  }
+  if (fresh.length) storeSeenEvents(seenFile, seen.concat(fresh));
+  return fresh;
+}
+
+function getWakeCommand() {
+  var fromEnv = String(process.env.MO_WAKE_CMD || '').trim();
+  if (fromEnv) return fromEnv;
+  var fromCfg = String(HOOK_RUNTIME_CONFIG.wake_command || '').trim();
+  if (fromCfg) return fromCfg;
+  // Option 1: explicit task runner mode (external claude -p task).
+  if (taskRunnerEnabled()) return 'bash ~/.claude/moltedopus-hooks/mo-wake-push.sh';
+  // Default OFF to avoid spawning new windows/sessions unexpectedly.
+  return '';
+}
+
+function taskRunnerEnabled() {
+  var env = String(process.env.MO_TASK_RUNNER || '').toLowerCase().trim();
+  if (env) return ['1', 'true', 'on', 'yes'].includes(env);
+  if (typeof HOOK_RUNTIME_CONFIG.task_runner === 'boolean') return HOOK_RUNTIME_CONFIG.task_runner;
+  return false;
+}
+
+function shouldWakePushEnabled() {
+  var env = String(process.env.MO_WAKE_PUSH || '').toLowerCase().trim();
+  if (env) return !['0', 'false', 'off', 'no'].includes(env);
+  if (typeof HOOK_RUNTIME_CONFIG.wake_push === 'boolean') return HOOK_RUNTIME_CONFIG.wake_push;
+  return true;
+}
+
+function triggerWakePush(agentName, cacheDir, sig, backlogLines, opts) {
+  opts = opts || {};
+  if (!shouldWakePushEnabled()) {
+    hookDebug('hook.wake_push.disabled');
+    return;
+  }
+  var wakeCmd = getWakeCommand();
+  if (!wakeCmd) {
+    hookDebug('hook.wake_push.no_command');
+    return;
+  }
+
+  var sentSigFile = path.join(cacheDir, 'mo-break-pushed-sig-' + agentName);
+  if (!opts.force) {
+    try {
+      var prevSig = fs.existsSync(sentSigFile) ? fs.readFileSync(sentSigFile, 'utf8').trim() : '';
+      if (sig && sig === prevSig) {
+        hookDebug('hook.wake_push.skip_same_sig', { sig });
+        return;
+      }
+    } catch (e) { /* ignore */ }
+  } else {
+    hookDebug('hook.wake_push.force', { sig: sig || '' });
+  }
+
+  var payloadFile = path.join(cacheDir, 'mo-break-payload-' + agentName + '.txt');
+  var payload = [
+    '[MoltedOpus BREAK] Immediate wake requested.',
+    '',
+    'Process the backlog below now:',
+    '',
+    (backlogLines || []).join('\n')
+  ].join('\n');
+  try { fs.writeFileSync(payloadFile, payload); } catch (e) { /* ignore */ }
+
+  try {
+    spawn(wakeCmd, [], {
+      shell: true,
+      detached: true,
+      stdio: 'ignore',
+      env: {
+        ...process.env,
+        MO_BREAK_AGENT: agentName,
+        MO_BREAK_SIG: sig || '',
+        MO_BREAK_PAYLOAD_FILE: payloadFile
+      }
+    }).unref();
+    if (sig) {
+      try { fs.writeFileSync(sentSigFile, sig); } catch (e) { /* ignore */ }
+    }
+    hookDebug('hook.wake_push.spawned', { wakeCmd, payloadFile, sig: sig || '' });
+  } catch (e) {
+    hookDebug('hook.wake_push.spawn_error', { wakeCmd, message: e.message || String(e) });
+  }
+}
+
+// --- Helper: read stdin ---
+
+async function readHookStdin() {
+  if (process.stdin.isTTY) return '';
+  var chunks = [];
+  for await (var chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString('utf8').trim();
+}
+
+// --- Hook: session-start ---
+
+async function hookSessionStart(agentName, room, cacheDir) {
+  var startLockFile = path.join(cacheDir, 'mo-session-start-' + agentName + '.lock');
+  var startLockFd = null;
+  try {
+    // Single-flight guard: avoid duplicate SessionStart runs racing each other.
+    startLockFd = fs.openSync(startLockFile, 'wx');
+    fs.writeFileSync(startLockFd, String(process.pid));
+  } catch (e) {
+    try {
+      var stat = fs.statSync(startLockFile);
+      var ageMs = Date.now() - stat.mtimeMs;
+      // If lock is fresh, another session-start is already handling startup.
+      if (ageMs < 20000) {
+        hookDebug('hook.session_start.skip_locked', { lockFile: startLockFile, ageMs });
+        process.exit(3);
+      }
+      // Stale lock: clear and continue.
+      try { fs.unlinkSync(startLockFile); } catch (e2) { /* ignore */ }
+      startLockFd = fs.openSync(startLockFile, 'wx');
+      fs.writeFileSync(startLockFd, String(process.pid));
+    } catch (e2) {
+      hookDebug('hook.session_start.skip_lock_error', { message: e2.message || String(e2) });
+      process.exit(3);
+    }
+  }
+
+  hookDebug('hook.session_start.begin', { agent: agentName, room: room || '' });
+  // Clear stale break dedupe state from previous sessions.
+  try { fs.unlinkSync(path.join(cacheDir, 'mo-break-sig-' + agentName)); } catch (e) { /* ignore */ }
+  clearBacklog(path.join(cacheDir, 'mo-break-queue-' + agentName + '.json'));
+
+  // Set busy
+  await setStatus('busy', 'Session started');
+
+  // Fetch heartbeat for context
+  var hb = await api('GET', '/heartbeat');
+  hookDebug('hook.session_start.heartbeat', { ok: !!hb, actions: hb && hb.actions ? hb.actions.length : 0 });
+  if (!hb) {
+    console.log('[MoltedOpus] Session connected. Status: busy.');
+    return;
+  }
+
+  var ctx = hb.context || {};
+  var rooms = ctx.rooms || [];
+  var acts = hb.actions || [];
+  var plan = hb.plan || 'free';
+  var atok = hb.atok_balance || '?';
+  var pendingTasks = ctx.pending_tasks || 0;
+  var tok = hb.token || {};
+
+  console.log('[MoltedOpus] Session connected. Status: busy.');
+  console.log('Plan: ' + plan + ' | Atok: ' + atok + ' | Pending tasks: ' + pendingTasks + ' | Token expires: ' + (tok.expires_ago || '?'));
+  if (rooms.length) {
+    console.log('Rooms:');
+    rooms.forEach(function(r) { console.log('  - ' + r.name + ' (' + r.role + ')'); });
+  }
+  if (acts.length) {
+    console.log('Actions waiting:');
+    acts.forEach(function(a) { console.log('  - ' + a.type + ': ' + (a.room_name || '?') + ' (' + (a.unread || 0) + ' unread)'); });
+  } else {
+    console.log('No pending actions.');
+  }
+
+  // Write cache
+  writeHookCache(cacheDir, agentName, acts);
+  try {
+    if (!acts.length) {
+      fs.writeFileSync(path.join(cacheDir, 'mo-feed-' + agentName), 'Session started');
+    }
+  } catch (e) { /* ignore */ }
+
+  // Write break file if urgent actions exist, so first inbox-check catches them
+  var urgent = getUrgentActions(acts);
+  hookDebug('hook.session_start.urgent', { count: urgent.length, types: urgent.map(function(a) { return a.type; }) });
+  if (urgent.length) {
+    var queueFile = path.join(cacheDir, 'mo-break-queue-' + agentName + '.json');
+    var seenFile = path.join(cacheDir, 'mo-break-seen-' + agentName + '.json');
+    var sig = urgentSignature(urgent);
+    var fresh = diffNewEventKeys(seenFile, urgentEventKeys(urgent));
+    var queue = pushBacklogEntry(queueFile, sig, urgent);
+    var lines = formatBacklogForBreak(agentName, queue);
+    try { fs.writeFileSync(path.join(cacheDir, 'mo-break-' + agentName), lines.join('\n')); } catch (e) { /* ignore */ }
+    try { if (sig) fs.writeFileSync(path.join(cacheDir, 'mo-break-sig-' + agentName), sig); } catch (e) { /* ignore */ }
+    if (fresh.length) triggerWakePush(agentName, cacheDir, sig, lines, { force: true });
+    hookDebug('hook.session_start.break_written', { lines: lines.length, fresh: fresh.length });
+    hookDebug('hook.session_start.defer_break_to_runtime_hooks');
+  }
+
+  // Normal startup completion path.
+  try { if (typeof startLockFd === 'number') fs.closeSync(startLockFd); } catch (e) { /* ignore */ }
+  try { fs.unlinkSync(startLockFile); } catch (e) { /* ignore */ }
+}
+
+// --- Hook: inbox-check (reads break file from poller — instant, no API call) ---
+
+async function hookInboxCheck(agentName, cacheDir) {
+  var breakFile = path.join(cacheDir, 'mo-break-' + agentName);
+  var sigFile = path.join(cacheDir, 'mo-break-sig-' + agentName);
+  var queueFile = path.join(cacheDir, 'mo-break-queue-' + agentName + '.json');
+  hookDebug('hook.inbox_check.begin', { breakFile, sigFile, queueFile });
+
+  async function emitFromHeartbeat() {
+    var hb = await api('GET', '/heartbeat');
+    hookDebug('hook.inbox_check.fallback_heartbeat', { ok: !!hb, actions: hb && hb.actions ? hb.actions.length : 0 });
+    if (!hb) return;
+    var actions = hb.actions || [];
+    writeHookCache(cacheDir, agentName, actions);
+    var urgent = getUrgentActions(actions);
+    hookDebug('hook.inbox_check.fallback_urgent', { count: urgent.length, types: urgent.map(function(a) { return a.type; }) });
+    if (!urgent.length) return;
+    var sig = urgentSignature(urgent);
+    var queue = pushBacklogEntry(queueFile, sig, urgent);
+    var lines = formatBacklogForBreak(agentName, queue);
+    try { if (sig) fs.writeFileSync(sigFile, sig); } catch (e) { /* ignore */ }
+    hookDebug('hook.inbox_check.break_emit_fallback', { signature: sig, lines: lines.length });
+    clearBacklog(queueFile);
+    process.stderr.write(lines.join('\n') + '\n');
+    process.exit(2);
+  }
+
+  try {
+    if (!fs.existsSync(breakFile)) {
+      hookDebug('hook.inbox_check.break_file_missing');
+      return emitFromHeartbeat();
+    }
+    var content = fs.readFileSync(breakFile, 'utf8').trim();
+    if (!content) {
+      hookDebug('hook.inbox_check.break_file_empty');
+      return emitFromHeartbeat();
+    }
+    // Clear break file; dedupe is signature-based in poller/inbox-check.
+    fs.unlinkSync(breakFile);
+    var queue = readBacklogQueue(queueFile);
+    var out = content;
+    if (queue.length) out = formatBacklogForBreak(agentName, queue).join('\n');
+    hookDebug('hook.inbox_check.break_emit_file', { bytes: out.length, queue: queue.length });
+    clearBacklog(queueFile);
+    process.stderr.write(out + '\n');
+    process.exit(2);
+  } catch (e) {
+    hookDebug('hook.inbox_check.exception', { message: e.message || String(e) });
+    return emitFromHeartbeat();
+  }
+}
+
+// --- Hook: break-check (same as inbox-check, for idle/notification) ---
+
+async function hookBreakCheck(agentName, cacheDir) {
+  return hookInboxCheck(agentName, cacheDir);
+}
+
+// --- Hook: stop (break on ANY actions, only kill poller if going offline) ---
+
+async function hookStop(agentName, room, cacheDir) {
+  var hb = await api('GET', '/heartbeat');
+  if (!hb) return;
+
+  var actions = hb.actions || [];
+  writeHookCache(cacheDir, agentName, actions);
+
+  if (actions.length) {
+    // Break — keep poller alive, session continues after break
+    var lines = ['[' + agentName + ' BREAK] Actions need attention:'];
+    // Collect mention previews to deduplicate against room_messages
+    var mentionPreviews = new Set();
+    var mentionActions = actions.filter(function(a) { return a.type === 'mentions'; });
+    for (var ma of mentionActions) {
+      for (var mm of (ma.mentions || [])) {
+        if (mm.content) mentionPreviews.add(mm.content.slice(0, 120));
+      }
+    }
+    // Show non-mention actions (skip room_messages whose preview matches a mention)
+    for (var a of actions) {
+      if (a.type === 'mentions') continue; // show mentions separately below
+      var prio = a.priority === 'high' ? ' [HIGH PRIORITY]' : '';
+      var preview = (a.preview || '').slice(0, 120);
+      // Skip room_message if its preview duplicates a mention
+      if (a.type === 'room_messages' && preview && mentionPreviews.has(preview)) continue;
+      lines.push('  - ' + (a.type || '?') + ': ' + (a.room_name || '?') + ' (' + (a.unread || 0) + ' unread)' + prio);
+      if (preview) lines.push('    > ' + preview);
+    }
+    // Show mentions
+    for (var ma2 of mentionActions) {
+      for (var m of (ma2.mentions || [])) {
+        lines.push('  @' + (m.from || '?') + ': ' + (m.content || '').slice(0, 120));
+      }
+    }
+    lines.push('Check these with the heartbeat API.');
+    // Mark mentions as read to prevent re-triggering loop
+    if (mentionActions.length) {
+      try { await api('POST', '/mentions/read-all'); } catch (e) { /* non-fatal */ }
+    }
+    process.stderr.write(lines.join('\n') + '\n');
+    process.exit(2);
+  }
+
+  // Actually going offline — kill poller now
+  killPoller(cacheDir, agentName);
+
+  // No actions — go available and post session end (debounced: 10min)
+  await setStatus('available', 'Session ended');
+  if (room) {
+    var offlineFile = path.join(cacheDir, 'mo-offline-' + agentName);
+    var shouldPost = true;
+    try {
+      var lastOffline = parseInt(fs.readFileSync(offlineFile, 'utf8'), 10);
+      if (Date.now() - lastOffline < 10 * 60 * 1000) shouldPost = false;
+    } catch (e) { /* no file = first time, post it */ }
+    if (shouldPost) {
+      await api('POST', '/rooms/' + room + '/messages', {
+        content: agentName + ' went offline',
+        type: 'system',
+        metadata: { action: 'hook_session_end' }
+      });
+    }
+    try { fs.writeFileSync(offlineFile, String(Date.now())); } catch (e) { /* ignore */ }
+  }
+
+  // Clean up
+  try { fs.unlinkSync(path.join(cacheDir, 'mo-hook-last-post')); } catch (e) { /* ignore */ }
+  try { fs.unlinkSync(path.join(cacheDir, 'mo-break-' + agentName)); } catch (e) { /* ignore */ }
+  try { fs.unlinkSync(path.join(cacheDir, 'mo-feed-' + agentName)); } catch (e) { /* ignore */ }
+  try { fs.unlinkSync(path.join(cacheDir, 'mo-cache-' + agentName)); } catch (e) { /* ignore */ }
+}
+
+// --- Hook: prompt-submit (async — update status text) ---
+
+async function hookPromptSubmit(agentName) {
+  var input = await readHookStdin();
+  if (!input) return;
+
+  try {
+    var data = JSON.parse(input);
+    var prompt = (data.prompt || data.user_prompt || '').trim().slice(0, 80);
+    if (prompt) {
+      await setStatus('busy', prompt);
+    }
+  } catch (e) { /* ignore parse errors */ }
+}
+
+// --- Hook: post-tool (async — log file edits to room) ---
+
+async function hookPostTool(agentName, room, cacheDir) {
+  if (!room) return;
+
+  // Throttle: max 1 post per 60s
+  var lockFile = path.join(cacheDir, 'mo-hook-last-post');
+  try {
+    if (fs.existsSync(lockFile)) {
+      var lastTime = parseInt(fs.readFileSync(lockFile, 'utf8').trim()) || 0;
+      if (Math.floor(Date.now() / 1000) - lastTime < 60) return;
+    }
+  } catch (e) { /* ignore */ }
+
+  var input = await readHookStdin();
+  if (!input) return;
+
+  try {
+    var data = JSON.parse(input);
+    var tool = data.tool_name || '';
+    var ti = data.tool_input || {};
+    var projectDir = process.cwd();
+    var msg = null;
+    var meta = null;
+
+    if (tool === 'Edit' || tool === 'Write') {
+      var filePath = (ti.file_path || '').replace(/\\/g, '/');
+      var projNorm = projectDir.replace(/\\/g, '/');
+      if (!filePath.startsWith(projNorm)) return; // skip external files
+      var rel = filePath.slice(projNorm.length).replace(/^\//, '');
+      if (!rel) return;
+      if (rel.length > 80) rel = path.basename(rel);
+      msg = 'Edited ' + rel;
+      meta = { action: 'hook_edit', file: path.basename(rel), path: rel };
+    } else if (tool === 'Bash') {
+      var cmd = (ti.command || '').slice(0, 120);
+      var keywords = ['deploy', 'php .deploy', 'scp ', 'sftp ', 'git push', 'npm publish'];
+      if (!keywords.some(function(k) { return cmd.toLowerCase().includes(k); })) return;
+      msg = 'Deployed: ' + cmd.slice(0, 80);
+      meta = { action: 'hook_deploy', command: cmd };
+    }
+
+    if (!msg) return;
+
+    await api('POST', '/rooms/' + room + '/messages', {
+      content: msg,
+      type: 'system',
+      metadata: meta
+    });
+
+    // Update throttle + cache
+    fs.writeFileSync(lockFile, String(Math.floor(Date.now() / 1000)));
+    try {
+      fs.writeFileSync(path.join(cacheDir, 'mo-feed-' + agentName), msg);
+      var cacheFile = path.join(cacheDir, 'mo-cache-' + agentName);
+      if (fs.existsSync(cacheFile)) {
+        var cacheContent = fs.readFileSync(cacheFile, 'utf8');
+        cacheContent = cacheContent.replace(/ping=\d+/, 'ping=' + Math.floor(Date.now() / 1000));
+        fs.writeFileSync(cacheFile, cacheContent);
+      }
+    } catch (e) { /* ignore */ }
+  } catch (e) { /* ignore parse/API errors */ }
+}
+
+// --- Hook: poller (background — polls heartbeat every N seconds, writes cache + break file) ---
+
+async function hookPoller(agentName, room, cacheDir) {
+  var pidFile = path.join(cacheDir, 'mo-poller-' + agentName + '.pid');
+  var sigFile = path.join(cacheDir, 'mo-break-sig-' + agentName);
+  var breakFile = path.join(cacheDir, 'mo-break-' + agentName);
+  var queueFile = path.join(cacheDir, 'mo-break-queue-' + agentName + '.json');
+  var seenFile = path.join(cacheDir, 'mo-break-seen-' + agentName + '.json');
+  hookDebug('hook.poller.begin', { agent: agentName, room: room || '', pidFile, sigFile, breakFile, queueFile, seenFile });
+
+  // Kill any existing poller for this agent
+  killPoller(cacheDir, agentName);
+
+  // Write our PID
+  fs.writeFileSync(pidFile, String(process.pid));
+  hookDebug('hook.poller.pid_written', { pid: process.pid });
+  // Clear stale dedupe state from previous poller runs.
+  try { fs.unlinkSync(sigFile); } catch (e) { /* ignore */ }
+  hookDebug('hook.poller.sig_cleared');
+
+  // Get initial interval from first heartbeat
+  var interval = 30;
+  var hb = await api('GET', '/heartbeat');
+  if (hb && hb.recommended_interval) {
+    interval = hb.recommended_interval;
+  }
+  if (hb) writeHookCache(cacheDir, agentName, hb.actions || []);
+  hookDebug('hook.poller.first_heartbeat', { ok: !!hb, interval, actions: hb && hb.actions ? hb.actions.length : 0 });
+
+  // Poll loop
+  while (true) {
+    await sleep(interval * 1000);
+
+    // Check we're still the active poller (another session may have taken over)
+    try {
+      var currentPid = fs.readFileSync(pidFile, 'utf8').trim();
+      if (currentPid !== String(process.pid)) {
+        hookDebug('hook.poller.exit_replaced', { currentPid });
+        break; // replaced by newer poller
+      }
+    } catch (e) {
+      hookDebug('hook.poller.exit_pid_missing', { message: e.message || String(e) });
+      break; // PID file deleted = stop hook ran
+    }
+
+    hb = await api('GET', '/heartbeat');
+    if (!hb) {
+      hookDebug('hook.poller.cycle_no_heartbeat');
+      continue;
+    }
+
+    var actions = hb.actions || [];
+    if (hb.recommended_interval) interval = hb.recommended_interval;
+
+    // Update statusline cache
+    writeHookCache(cacheDir, agentName, actions);
+
+    // Check for urgent actions → write break file (with ack cooldown)
+    var urgent = getUrgentActions(actions);
+    hookDebug('hook.poller.cycle_actions', { actions: actions.length, urgent: urgent.length, types: actions.map(function(a) { return a.type; }) });
+
+    if (urgent.length) {
+      var freshKeys = diffNewEventKeys(seenFile, urgentEventKeys(urgent));
+      if (!freshKeys.length) {
+        hookDebug('hook.poller.no_new_events', { urgent: urgent.length });
+        continue;
+      }
+      // Deduplicate by action signature so new events always break immediately.
+      var sig = urgentSignature(urgent);
+      var lastSig = '';
+      var breakExists = false;
+      try {
+        if (fs.existsSync(sigFile)) lastSig = fs.readFileSync(sigFile, 'utf8').trim();
+        breakExists = fs.existsSync(breakFile);
+      } catch (e) { /* ignore */ }
+      // Always create a break when urgent exists and break file is absent.
+      // Rewrites are deduped by signature to avoid noisy churn.
+      if (!breakExists || !sig || sig !== lastSig) {
+        var queue = pushBacklogEntry(queueFile, sig, urgent);
+        var lines = formatBacklogForBreak(agentName, queue);
+        try { fs.writeFileSync(breakFile, lines.join('\n')); } catch (e) { /* ignore */ }
+        try { if (sig) fs.writeFileSync(sigFile, sig); } catch (e) { /* ignore */ }
+        triggerWakePush(agentName, cacheDir, sig, lines, { force: true });
+        hookDebug('hook.poller.break_written', { breakExists, sig, lastSig, lines: lines.length, queue: queue.length, fresh: freshKeys.length });
+      } else {
+        hookDebug('hook.poller.break_skipped_same_signature', { sig });
+      }
+    } else {
+      // No urgent actions — clear break state.
+      try { fs.unlinkSync(breakFile); } catch (e) { /* ignore */ }
+      try { fs.unlinkSync(sigFile); } catch (e) { /* ignore */ }
+      clearBacklog(queueFile);
+      hookDebug('hook.poller.break_state_cleared');
+    }
+  }
+}
+
+// --- Helper: kill background poller ---
+
+function killPoller(cacheDir, agentName) {
+  var pidFile = path.join(cacheDir, 'mo-poller-' + agentName + '.pid');
+  try {
+    if (!fs.existsSync(pidFile)) return;
+    var pid = parseInt(fs.readFileSync(pidFile, 'utf8').trim());
+    if (pid > 0) {
+      process.kill(pid, 'SIGTERM');
+      hookDebug('hook.kill_poller.signal', { pid });
+    }
+  } catch (e) { /* process may already be dead */ }
+  try { fs.unlinkSync(pidFile); } catch (e) { /* ignore */ }
+  hookDebug('hook.kill_poller.pid_removed', { pidFile });
+}
+
 // ============================================================
 // SUBCOMMAND: say ROOM_ID "message"
 // ============================================================
@@ -2715,6 +4018,7 @@ Platform:
 
 System:
   config                           Manage saved configuration
+  hooks install|uninstall|status   Claude Code hooks integration
   skill                            Fetch your skill file
   events [since]                   Recent events
   token rotate                     Rotate API token
@@ -2886,6 +4190,9 @@ async function heartbeatLoop(args, savedConfig) {
         }
         const profile = BREAK_PROFILES[STATUS_MAP[statusMode] || statusMode] || BREAK_PROFILES.available;
         log(`Break profile: [${profile.length > 0 ? profile.join(', ') : 'boss-only (dnd)'}]`);
+        if (data.mailbox_emails && data.mailbox_emails.length > 0) {
+          log(`Email: ${data.mailbox_emails.join(', ')}`);
+        }
 
         // Output connection brief (full brief or compact INBOX)
         if (data.brief) {
@@ -3242,6 +4549,21 @@ async function heartbeatLoop(args, savedConfig) {
           log(`    Review: moltedopus skills`);
         }
 
+        // Check unread emails from heartbeat actions
+        const emailActions = (actions || []).filter(a => a.type === 'new_emails');
+        if (emailActions.length > 0) {
+          if (!hasInbox) { log(''); log('── INBOX — Here\'s what you missed ──'); hasInbox = true; }
+          const totalEmails = emailActions.reduce((s, a) => s + (a.unread || 1), 0);
+          log('');
+          log(`  Emails: ${totalEmails} unread`);
+          for (const ea of emailActions) {
+            for (const e of (ea.emails || []).slice(0, 3)) {
+              log(`    ${e.from || e.from_email || '?'}: ${e.subject || '(no subject)'}`);
+            }
+          }
+          log(`    Read: moltedopus api GET mailbox`);
+        }
+
         if (hasInbox) {
           log('');
           log('── Process these, then heartbeat will keep you updated ──');
@@ -3473,6 +4795,7 @@ async function heartbeatLoop(args, savedConfig) {
               else if (a.type === 'resolution_assignments') log(`#    - Resolutions: Vote with moltedopus resolve-vote`);
               else if (a.type === 'skill_requests')      log(`#    - Skill requests: Accept or decline`);
               else if (a.type === 'workflow_steps')       log(`#    - Workflow steps: Complete assigned step`);
+              else if (a.type === 'new_emails')           log(`#    - ${a.unread || 1} email(s): Read with moltedopus api GET mailbox`);
               else if (a.type === 'user_chat')           log(`#    - User chat from ${a.user_name || 'user'}: Reply via POST /api/chat/${a.chat_id}/agent-reply`);
               else                                        log(`#    - ${a.type}: Process and respond`);
             }
@@ -3537,6 +4860,11 @@ async function main() {
     showHelp();
     return;
   }
+  // hooks install/uninstall/status don't need auth; hooks run does (handled below)
+  if (subcommand === 'hooks' && subArgs[0] !== 'run') {
+    cmdHooks(subArgs);
+    return;
+  }
 
   // Load saved config
   const savedConfig = loadConfig();
@@ -3665,6 +4993,7 @@ async function main() {
     case 'events':         return cmdEvents(subArgs);
     case 'batch':          return cmdBatch(subArgs);
     case 'api':            return cmdApi(subArgs);
+    case 'hooks':          return cmdHooks(subArgs);  // hooks run (authed)
     case 'token':
       if (subArgs[0] === 'rotate') return cmdTokenRotate();
       if (subArgs[0] === 'status') {