@dmsdc-ai/aigentry-deliberation 0.0.39 → 0.0.40

package/index.js

@@ -69,14 +69,159 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { execFileSync, spawn } from "child_process";
-import { createHash } from "crypto";
 import fs from "fs";
 import path from "path";
 import { fileURLToPath } from "url";
 import os from "os";
-import WebSocket from "ws";
 import { OrchestratedBrowserPort } from "./browser-control-port.js";
 import { getModelSelectionForTurn } from "./model-router.js";
+import {
+  initSpeakerDeps,
+  // Constants
+  DEFAULT_SPEAKERS,
+  DEFAULT_CLI_CANDIDATES,
+  MAX_AUTO_DISCOVERED_SPEAKERS,
+  DEFAULT_BROWSER_APPS,
+  DEFAULT_LLM_DOMAINS,
+  DEFAULT_WEB_SPEAKERS,
+  SPEAKER_SELECTION_FILE,
+  SPEAKER_SELECTION_TTL_MS,
+  CLI_INVOCATION_HINTS,
+  ROLE_KEYWORDS,
+  ROLE_HEADING_MARKERS,
+  DEGRADATION_TIERS,
+  TRANSPORT_TYPES,
+  // Utility
+  commandExistsInPath,
+  shellQuote,
+  // Speaker normalization & ordering
+  normalizeSpeaker,
+  dedupeSpeakers,
+  selectNextSpeaker,
+  loadRolePrompt,
+  inferSuggestedRole,
+  parseVotes,
+  loadRolePresets,
+  applyRolePreset,
+  loadExtensionProviderRegistry,
+  isExtensionLlmTab,
+  // Speaker selection tokens
+  createSelectionToken,
+  issueSpeakerSelectionToken,
+  loadSpeakerSelectionToken,
+  clearSpeakerSelectionToken,
+  validateSpeakerSelectionSnapshot,
+  confirmSpeakerSelectionToken,
+  validateSpeakerSelectionRequest,
+  // Browser participant helpers
+  hasExplicitBrowserParticipantSelection,
+  resolveIncludeBrowserSpeakers,
+  // CLI discovery
+  resolveCliCandidates,
+  checkCliLiveness,
+  discoverLocalCliSpeakers,
+  detectCallerSpeaker,
+  // URL / domain helpers
+  isLlmUrl,
+  dedupeBrowserTabs,
+  parseInjectedBrowserTabsFromEnv,
+  // CDP helpers
+  normalizeCdpEndpoint,
+  resolveCdpEndpoints,
+  fetchJson,
+  inferBrowserFromCdpEndpoint,
+  summarizeFailures,
+  // Browser LLM tab collection
+  collectBrowserLlmTabsViaCdp,
+  ensureCdpAvailable,
+  collectBrowserLlmTabsViaAppleScript,
+  collectBrowserLlmTabs,
+  // LLM provider inference
+  inferLlmProvider,
+  // Speaker candidate collection
+  collectSpeakerCandidates,
+  formatSpeakerCandidatesReport,
+  mapParticipantProfiles,
+  // Speaker ordering
+  buildSpeakerOrder,
+  normalizeSessionActors,
+  // Transport routing
+  resolveTransportForSpeaker,
+  formatTransportGuidance,
+  // Degradation
+  detectDegradationLevels,
+  formatDegradationReport,
+} from "./lib/speaker-discovery.js";
+import {
+  initSessionDeps,
+  generateSessionId,
+  generateTurnId,
+  detectContextDirs,
+  readContextFromDirs,
+  getArchiveDir,
+  findSessionRecord,
+  ensureDirs,
+  loadSession,
+  saveSession,
+  listActiveSessions,
+  resolveSessionId,
+  syncMarkdown,
+  cleanupSyncMarkdown,
+  formatSourceMetadataLine,
+  stateToMarkdown,
+  archiveState,
+  multipleSessionsError,
+  truncatePromptText,
+  getPromptBudgetForSpeaker,
+  formatRecentLogForPrompt,
+  buildActiveReportingSection,
+  buildClipboardTurnPrompt,
+  submitDeliberationTurn,
+} from "./lib/session.js";
+import {
+  initTransportDeps,
+  // Constants
+  TMUX_SESSION,
+  MONITOR_SCRIPT,
+  MONITOR_SCRIPT_WIN,
+  // Terminal management
+  tmuxWindowName,
+  appleScriptQuote,
+  tryExecFile,
+  resolveMonitorShell,
+  buildMonitorCommand,
+  buildMonitorCommandWindows,
+  hasTmuxSession,
+  hasTmuxWindow,
+  tmuxHasAttachedClients,
+  isTmuxWindowViewed,
+  tmuxWindowCount,
+  buildTmuxAttachCommand,
+  listPhysicalTerminalWindowIds,
+  openPhysicalTerminal,
+  spawnMonitorTerminal,
+  closePhysicalTerminal,
+  closeMonitorTerminal,
+  getSessionWindowIds,
+  closeAllMonitorTerminals,
+  // Browser port singleton
+  getBrowserPort,
+  // CLI auto-turn helpers
+  getCliAutoTurnTimeoutSec,
+  getCliExecArgs,
+  buildCliAutoTurnFailureText,
+  // Auto-turn execution core
+  runCliAutoTurnCore,
+  runBrowserAutoTurnCore,
+  runTeleptyBusAutoTurnCore,
+  runUntilBlockedCore,
+  generateAutoSynthesis,
+  runAutoHandoff,
+  // Review helpers
+  invokeCliReviewer,
+  buildReviewPrompt,
+  synthesizeReviews,
+} from "./lib/transport.js";
 import { readClipboardText, writeClipboardText, hasClipboardImage, captureClipboardImage } from "./clipboard.js";
 import {
   DECISION_STAGES, STAGE_TRANSITIONS,
@@ -86,6 +231,63 @@ import {
   loadTemplates, matchTemplate,
 } from "./decision-engine.js";
 import { detectLang, t } from "./i18n.js";
+import { checkToolEntitlement } from "./lib/entitlement.js";
+import {
+  initTeleptyDeps,
+  // Schemas
+  StructuredActionableTaskSchema,
+  StructuredExperimentOutcomeSchema,
+  StructuredSynthesisSchema,
+  StructuredExecutionContractSchema,
+  TeleptyEnvelopeSchema,
+  TeleptyTurnRequestPayloadSchema,
+  TeleptyTurnCompletedPayloadSchema,
+  TeleptyDeliberationCompletedPayloadSchema,
+  TELEPTY_ENVELOPE_PAYLOAD_SCHEMAS,
+  // Constants
+  TELEPTY_CONFIG_FILE,
+  TELEPTY_DEFAULT_HOST,
+  TELEPTY_PORT,
+  TELEPTY_TRANSPORT_TIMEOUT_MS,
+  TELEPTY_SEMANTIC_TIMEOUT_MS,
+  TELEPTY_BUS_RECONNECT_MS,
+  TELEPTY_SESSION_HEALTH_STALE_MS,
+  // State
+  teleptyBusState,
+  pendingTeleptyTurnRequests,
+  // Functions
+  hashPromptText,
+  sortJsonValue,
+  hashStructuredSynthesis,
+  buildExecutionContract,
+  createEnvelopeId,
+  validateTeleptyEnvelope,
+  resolveTeleptySourceHost,
+  buildTeleptyEnvelope,
+  buildTeleptyTurnRequestEnvelope,
+  buildTeleptyTurnCompletedEnvelope,
+  buildTeleptySynthesisEnvelope,
+  resolveTeleptyBusUrl,
+  cleanupPendingTeleptyTurn,
+  registerPendingTeleptyTurnRequest,
+  ackPendingTeleptyTurn,
+  completePendingTeleptySemantic,
+  updateTeleptySessionHealth,
+  getTeleptySessionHealth,
+  handleTeleptyBusMessage,
+  ensureTeleptyBusSubscriber,
+  callBrainIngest,
+  notifyTeleptyBus,
+  getDefaultOrchestratorSessionId,
+  buildTurnCompletionNotificationText,
+  notifyTeleptySessionInject,
+  dispatchTeleptyTurnRequest,
+  loadTeleptyAuthToken,
+  formatTeleptyHostLabel,
+  collectTeleptySessions,
+  scoreTeleptyProcessMatch,
+  collectTeleptyProcessLocators,
+} from "./lib/telepty.js";
 
 // ── Paths ──────────────────────────────────────────────────────
 
@@ -98,29 +300,6 @@ const GLOBAL_STATE_DIR = path.join(INSTALL_DIR, "state");
 const GLOBAL_RUNTIME_LOG = path.join(INSTALL_DIR, "runtime.log");
 const OBSIDIAN_VAULT = path.join(HOME, "Documents", "Obsidian Vault");
 const OBSIDIAN_PROJECTS = path.join(OBSIDIAN_VAULT, "10-Projects");
-const DEFAULT_SPEAKERS = ["agent-a", "agent-b"];
-const DEFAULT_CLI_CANDIDATES = [
-  "claude",
-  "codex",
-  "gemini",
-  "qwen",
-  "chatgpt",
-  "aider",
-  "llm",
-  "opencode",
-  "cursor-agent",
-  "cursor",
-  "continue",
-];
-const MAX_AUTO_DISCOVERED_SPEAKERS = 12;
-const TELEPTY_CONFIG_FILE = path.join(HOME, ".telepty", "config.json");
-const TELEPTY_DEFAULT_HOST = process.env.TELEPTY_HOST || "127.0.0.1";
-const TELEPTY_PORT = Number(process.env.TELEPTY_PORT || 3848);
-const TELEPTY_TRANSPORT_TIMEOUT_MS = 5_000;
-const TELEPTY_SEMANTIC_TIMEOUT_MS = 60_000;
-const TELEPTY_BUS_RECONNECT_MS = 5_000;
-const TELEPTY_SESSION_HEALTH_STALE_MS = 25_000;
-
 function loadDeliberationConfig() {
   const configPath = path.join(INSTALL_DIR, "config.json");
   try {
@@ -132,326 +311,16 @@ function loadDeliberationConfig() {
 
 function saveDeliberationConfig(config) {
   const configPath = path.join(INSTALL_DIR, "config.json");
+  fs.mkdirSync(INSTALL_DIR, { recursive: true });
   config.updated = new Date().toISOString();
   fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
 }
 
-const StructuredActionableTaskSchema = z.object({
-  id: z.number(),
-  task: z.string(),
-  files: z.array(z.string()).optional(),
-  project: z.string().optional(),
-  priority: z.enum(["high", "medium", "low"]).optional(),
-});
-
-const StructuredExperimentOutcomeSchema = z.object({
-  verdict: z.enum(["keep", "discard", "modify"]),
-  confidence: z.number().min(0).max(1).optional(),
-  measurement_window_hours: z.number().nonnegative().optional(),
-  patches: z.array(z.unknown()).optional(),
-  suggested_action: z.enum(["advance", "revert", "iterate"]).optional(),
-});
-
-const StructuredSynthesisSchema = z.object({
-  summary: z.string(),
-  decisions: z.array(z.string()),
-  actionable_tasks: z.array(StructuredActionableTaskSchema),
-  experiment_outcome: StructuredExperimentOutcomeSchema.optional(),
-});
-
-const StructuredExecutionContractSchema = z.object({
-  schema_version: z.number().int().positive(),
-  source_session_id: z.string().min(1),
-  deliberation_id: z.string().min(1),
-  summary: z.string(),
-  decisions: z.array(z.string()),
-  tasks: z.array(StructuredActionableTaskSchema),
-  experiment_outcome: StructuredExperimentOutcomeSchema.nullable().optional(),
-  unresolved_questions: z.array(z.string()),
-  artifact_refs: z.array(z.string()),
-  generated_from: z.object({
-    structured_synthesis_hash: z.string().length(40),
-  }),
-});
-
-const TeleptyEnvelopeSchema = z.object({
-  version: z.number().int().positive().optional(),
-  message_id: z.string().min(1),
-  session_id: z.string().min(1),
-  project: z.string().min(1),
-  kind: z.string().min(1),
-  source: z.string().min(1),
-  source_host: z.string().min(1).optional(),
-  target: z.string().min(1),
-  reply_to: z.string().nullable().optional(),
-  trace: z.array(z.string()),
-  payload: z.unknown(),
-  ts: z.string().min(1),
-});
-
-const TeleptyTurnRequestPayloadSchema = z.object({
-  turn_id: z.string().min(1),
-  round: z.number().int().positive(),
-  max_rounds: z.number().int().positive(),
-  speaker: z.string().min(1),
-  role: z.string().nullable().optional(),
-  prompt: z.string().min(1),
-  content: z.string().min(1).describe("PTY-compatible alias for prompt field"),
-  prompt_sha1: z.string().length(40),
-  history_entries: z.number().int().nonnegative().optional(),
-  transport_timeout_ms: z.number().int().positive(),
-  semantic_timeout_ms: z.number().int().positive(),
-});
-
-const TeleptyTurnCompletedPayloadSchema = z.object({
-  turn_id: z.string().nullable().optional(),
-  speaker: z.string().min(1),
-  round: z.number().int().positive(),
-  max_rounds: z.number().int().positive(),
-  next_speaker: z.string().min(1),
-  next_round: z.number().int().positive(),
-  status: z.string().min(1),
-  total_responses: z.number().int().nonnegative(),
-  channel_used: z.string().nullable().optional(),
-  fallback_reason: z.string().nullable().optional(),
-  orchestrator_session_id: z.string().nullable().optional(),
-});
-
-const TeleptyDeliberationCompletedPayloadSchema = z.object({
-  topic: z.string(),
-  synthesis: z.string(),
-  structured_synthesis: StructuredSynthesisSchema.nullable().optional(),
-  execution_contract: StructuredExecutionContractSchema.nullable().optional(),
-});
-
-const TELEPTY_ENVELOPE_PAYLOAD_SCHEMAS = {
-  turn_request: TeleptyTurnRequestPayloadSchema,
-  turn_completed: TeleptyTurnCompletedPayloadSchema,
-  deliberation_completed: TeleptyDeliberationCompletedPayloadSchema,
-};
-
-const DEFAULT_BROWSER_APPS = ["Google Chrome", "Brave Browser", "Arc", "Microsoft Edge", "Safari"];
-const DEFAULT_LLM_DOMAINS = [
-  "chatgpt.com",
-  "openai.com",
-  "claude.ai",
-  "anthropic.com",
-  "gemini.google.com",
-  "copilot.microsoft.com",
-  "poe.com",
-  "perplexity.ai",
-  "mistral.ai",
-  "huggingface.co/chat",
-  "deepseek.com",
-  "qwen.ai",
-  "notebooklm.google.com",
-];
-
-// Well-known web LLMs — always available as speaker candidates regardless of browser detection.
-// When a matching browser tab is detected, transport upgrades to browser_auto (CDP) or clipboard.
-// When no tab is detected, transport falls back to clipboard (manual paste).
-const DEFAULT_WEB_SPEAKERS = [
-  { speaker: "web-chatgpt", provider: "chatgpt", name: "ChatGPT", url: "https://chatgpt.com" },
-  { speaker: "web-claude", provider: "claude", name: "Claude", url: "https://claude.ai" },
-  { speaker: "web-gemini", provider: "gemini", name: "Gemini", url: "https://gemini.google.com" },
-  { speaker: "web-copilot", provider: "copilot", name: "Copilot", url: "https://copilot.microsoft.com" },
-  { speaker: "web-perplexity", provider: "perplexity", name: "Perplexity", url: "https://perplexity.ai" },
-  { speaker: "web-deepseek", provider: "deepseek", name: "DeepSeek", url: "https://chat.deepseek.com" },
-  { speaker: "web-mistral", provider: "mistral", name: "Mistral", url: "https://mistral.ai" },
-  { speaker: "web-poe", provider: "poe", name: "Poe", url: "https://poe.com" },
-  { speaker: "web-grok", provider: "grok", name: "Grok", url: "https://grok.com" },
-  { speaker: "web-qwen", provider: "qwen", name: "Qwen", url: "https://chat.qwen.ai" },
-  { speaker: "web-huggingchat", provider: "huggingchat", name: "HuggingChat", url: "https://huggingface.co/chat" },
-];
-
-let _extensionProviderRegistry = null;
-const __dirnameEsm = path.dirname(new URL(import.meta.url).pathname.replace(/^\/([A-Z]:)/, "$1"));
-function loadExtensionProviderRegistry() {
-  if (_extensionProviderRegistry) return _extensionProviderRegistry;
-  try {
-    const registryPath = path.join(__dirnameEsm, "selectors", "extension-providers.json");
-    _extensionProviderRegistry = JSON.parse(fs.readFileSync(registryPath, "utf-8"));
-    return _extensionProviderRegistry;
-  } catch (err) {
-    console.error("Failed to load extension-providers.json:", err.message);
-    _extensionProviderRegistry = { providers: [] };
-    return _extensionProviderRegistry;
-  }
-}
-
-function isExtensionLlmTab(url = "", title = "") {
-  if (!String(url).startsWith("chrome-extension://")) return false;
-  const registry = loadExtensionProviderRegistry();
-  const lowerTitle = String(title || "").toLowerCase();
-  if (!lowerTitle) return false;
-  return registry.providers.some(p =>
-    p.titlePatterns.some(pattern => lowerTitle.includes(pattern.toLowerCase()))
-  );
-}
-
-// ── Sprint 1: Smart Speaker Ordering + Persona Roles ────────────
-
-function selectNextSpeaker(session) {
-  const { speakers, current_speaker, log, ordering_strategy } = session;
-  switch (ordering_strategy || "cyclic") {
-    case "random":
-      return speakers[Math.floor(Math.random() * speakers.length)];
-    case "weighted-random": {
-      const window = log.slice(-(speakers.length * 2));
-      const counts = new Map(speakers.map(s => [s, 0]));
-      for (const entry of window) {
-        if (counts.has(entry.speaker)) counts.set(entry.speaker, counts.get(entry.speaker) + 1);
-      }
-      const maxCount = Math.max(...counts.values(), 1);
-      const weights = speakers.map(s => maxCount + 1 - counts.get(s));
-      const total = weights.reduce((a, b) => a + b, 0);
-      let r = Math.random() * total;
-      for (let i = 0; i < speakers.length; i++) {
-        r -= weights[i];
-        if (r <= 0) return speakers[i];
-      }
-      return speakers[speakers.length - 1];
-    }
-    case "cyclic":
-    default: {
-      const idx = speakers.indexOf(current_speaker);
-      return speakers[(idx + 1) % speakers.length];
-    }
-  }
-}
-
-function loadRolePrompt(role) {
-  if (!role || role === "free") return "";
-  try {
-    const promptPath = path.join(__dirnameEsm, "selectors", "roles", `${role}.md`);
-    return fs.readFileSync(promptPath, "utf-8").trim();
-  } catch {
-    return "";
-  }
-}
-
-const ROLE_KEYWORDS = {
-  critic: /문제|위험|실패|약점|리스크|반대|비판|결함|취약/,
-  implementer: /구현|코드|방법|설계|빌드|개발|함수|모듈|파일/,
-  mediator: /합의|정리|결론|종합|요약|중재|절충|균형/,
-  researcher: /사례|데이터|연구|벤치마크|비교|논문|참고/,
-};
-
-const ROLE_HEADING_MARKERS = {
-  critic: /^##?\s*(Critic|비판|약점|심각도|위험\s*분석|검증|평가|Review)/m,
-  implementer: /^##?\s*(코드\s*스케치|구현|Implementation|제안\s*코드)/m,
-  mediator: /^##?\s*(합의|종합|중재|Consensus|Mediation)/m,
-  researcher: /^##?\s*(조사\s*결과|비교\s*분석|Research|사례\s*연구|근거|데이터|Data)/m,
-};
-
-function inferSuggestedRole(text) {
-  const scores = {};
-  for (const [role, pattern] of Object.entries(ROLE_KEYWORDS)) {
-    const matches = (text.match(new RegExp(pattern, "g")) || []).length;
-    if (matches > 0) scores[role] = matches;
-  }
-  // Structural heading markers get extra weight (equivalent to 5 keyword matches)
-  for (const [role, pattern] of Object.entries(ROLE_HEADING_MARKERS)) {
-    if (pattern.test(text)) {
-      scores[role] = (scores[role] || 0) + 8;
-    }
-  }
-  if (Object.keys(scores).length === 0) return "free";
-  return Object.entries(scores).sort((a, b) => b[1] - a[1])[0][0];
-}
-
-function parseVotes(text) {
-  const votes = [];
-  for (const line of text.split("\n")) {
-    const agree = line.match(/\[AGREE\]/i);
-    const disagree = line.match(/\[DISAGREE\]/i);
-    const conditional = line.match(/\[CONDITIONAL:\s*(.+?)\]/i);
-    if (agree) votes.push({ line: line.trim(), vote: "agree" });
-    else if (disagree) votes.push({ line: line.trim(), vote: "disagree" });
-    else if (conditional) votes.push({ line: line.trim(), vote: "conditional", condition: conditional[1].trim() });
-  }
-  return votes;
-}
-
-let _rolePresetsCache = null;
-function loadRolePresets() {
-  if (_rolePresetsCache) return _rolePresetsCache;
-  try {
-    const presetsPath = path.join(__dirnameEsm, "selectors", "role-presets.json");
-    _rolePresetsCache = JSON.parse(fs.readFileSync(presetsPath, "utf-8"));
-    return _rolePresetsCache;
-  } catch {
-    _rolePresetsCache = { presets: {} };
-    return _rolePresetsCache;
-  }
-}
-
-function applyRolePreset(preset, speakers) {
-  const presets = loadRolePresets();
-  const presetDef = presets.presets[preset];
-  if (!presetDef) return {};
-
-  const roles = presetDef.roles;
-  const result = {};
-  for (let i = 0; i < speakers.length; i++) {
-    result[speakers[i]] = roles[i % roles.length];
-  }
-  return result;
-}
-
-// ── Graceful Degradation Matrix ──────────────────────────────────
-
-const DEGRADATION_TIERS = {
-  monitoring: {
-    tier1: { name: "tmux", description: "tmux real-time monitoring window", check: () => commandExistsInPath("tmux") },
-    tier2: { name: "logfile", description: "Log file tail monitoring", check: () => true },
-    tier3: { name: "silent", description: "No monitoring (log only)", check: () => true },
-  },
-  browser: {
-    tier1: { name: "cdp_auto", description: "CDP auto send/collect", check: async () => { try { const res = await fetch("http://127.0.0.1:9222/json/version", { signal: AbortSignal.timeout(2000) }); return res.ok; } catch { return false; } } },
-    tier2: { name: "clipboard", description: "Clipboard-based manual transfer", check: () => true },
-    tier3: { name: "manual", description: "Fully manual copy/paste", check: () => true },
-  },
-  terminal: {
-    tier1: { name: "auto_open", description: "Auto-open terminal app", check: () => process.platform === "darwin" || process.platform === "linux" || process.platform === "win32" },
-    tier2: { name: "none", description: "Cannot auto-open terminal", check: () => true },
-    tier3: { name: "none", description: "Cannot auto-open terminal", check: () => true },
-  },
-};
-
-async function detectDegradationLevels() {
-  const levels = {};
-  for (const [feature, tiers] of Object.entries(DEGRADATION_TIERS)) {
-    for (const tierKey of ["tier1", "tier2", "tier3"]) {
-      const tier = tiers[tierKey];
-      const available = await Promise.resolve(tier.check());
-      if (available) {
-        levels[feature] = { tier: tierKey, name: tier.name, description: tier.description };
-        break;
-      }
-    }
-  }
-  return levels;
-}
-
-function formatDegradationReport(levels) {
-  const lines = [];
-  for (const [feature, info] of Object.entries(levels)) {
-    const tierNum = parseInt(info.tier.replace("tier", ""));
-    const indicator = tierNum === 1 ? "🟢" : tierNum === 2 ? "🟡" : "🔴";
-    lines.push(`  ${indicator} **${feature}**: ${info.name} — ${info.description}`);
-  }
-  return lines.join("\n");
-}
-
 const PRODUCT_DISCLAIMER = "ℹ️ This tool does not permanently modify external websites. It reads browser context in read-only mode to route speakers.";
 const LOCKS_SUBDIR = ".locks";
 const LOCK_RETRY_MS = 25;
 const LOCK_TIMEOUT_MS = 8000;
 const LOCK_STALE_MS = 60000;
-const SPEAKER_SELECTION_FILE = "speaker-selection.json";
-const SPEAKER_SELECTION_TTL_MS = 10 * 60 * 1000;
-
 function getProjectSlug() {
   return path.basename(process.cwd());
 }
@@ -496,624 +365,8 @@ function listStateProjects() {
   }
 }
 
-function findSessionRecord(sessionRef, { preferProject, activeOnly = false } = {}) {
-  if (!sessionRef) return null;
-
-  if (typeof sessionRef === "object" && sessionRef !== null && sessionRef.id) {
-    const project = getSessionProject(sessionRef, preferProject);
-    const file = getSessionFile(sessionRef.id, project);
-    const state = readJsonFileSafe(file);
-    if (!state) return null;
-    const normalized = normalizeSessionActors(state);
-    if (activeOnly && normalized.status !== "active" && normalized.status !== "awaiting_synthesis") {
-      return null;
-    }
-    return { file, project, state: normalized };
-  }
-
-  const sessionId = String(sessionRef);
-  const preferred = normalizeProjectSlug(preferProject);
-  const projects = [...new Set([preferred, ...listStateProjects()])];
-  for (const project of projects) {
-    const file = getSessionFile(sessionId, project);
-    const state = readJsonFileSafe(file);
-    if (!state) continue;
-    const normalized = normalizeSessionActors(state);
-    if (activeOnly && normalized.status !== "active" && normalized.status !== "awaiting_synthesis") {
-      continue;
-    }
-    return { file, project: normalized.project || project, state: normalized };
-  }
-  return null;
-}
-
-const teleptyBusState = {
-  ws: null,
-  status: "idle",
-  connectPromise: null,
-  reconnectTimer: null,
-  lastError: null,
-  lastConnectedAt: null,
-  lastMessageAt: null,
-  healthBySession: new Map(),
-};
-
-const pendingTeleptyTurnRequests = new Map();
-
-function hashPromptText(value) {
-  return createHash("sha1").update(String(value || "")).digest("hex");
-}
-
-function sortJsonValue(value) {
-  if (Array.isArray(value)) {
-    return value.map(sortJsonValue);
-  }
-  if (value && typeof value === "object") {
-    return Object.keys(value)
-      .sort()
-      .reduce((acc, key) => {
-        acc[key] = sortJsonValue(value[key]);
-        return acc;
-      }, {});
-  }
-  return value;
-}
-
-function hashStructuredSynthesis(structured) {
-  return hashPromptText(JSON.stringify(sortJsonValue(structured || null)));
-}
-
-/**
- * Build a deterministic execution contract from structured synthesis.
- *
- * Data model canonical roles:
- * - structured_synthesis: human + reasoning canonical — rich context for
- *   human review (decisions rationale, experiment outcomes, full task descriptions).
- * - execution_contract: automation canonical — minimal, deterministic task list
- *   derived from structured_synthesis via SHA-1 hash for provenance tracking.
- *   Consumers (inbox-watcher, devkit, registry, orchestrator) MUST prefer
- *   execution_contract when available; fall back to structured_synthesis only
- *   when execution_contract is absent.
- */
-function buildExecutionContract({ state, structured }) {
-  if (!structured) return null;
-  return {
-    schema_version: 2,
-    source_session_id: state.id,
-    deliberation_id: state.id,
-    summary: structured.summary || "",
-    decisions: structured.decisions || [],
-    tasks: structured.actionable_tasks || [],
-    experiment_outcome: structured.experiment_outcome || null,
-    unresolved_questions: [],
-    artifact_refs: [],
-    generated_from: {
-      structured_synthesis_hash: hashStructuredSynthesis(structured),
-    },
-  };
-}
-
-function createEnvelopeId(prefix = "env") {
-  return `${prefix}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
-}
-
-function validateTeleptyEnvelope(envelope) {
-  const parsed = TeleptyEnvelopeSchema.parse(envelope);
-  const payloadSchema = TELEPTY_ENVELOPE_PAYLOAD_SCHEMAS[parsed.kind];
-  if (payloadSchema) {
-    payloadSchema.parse(parsed.payload);
-  }
-  return parsed;
-}
-
-function resolveTeleptySourceHost() {
-  const explicit = process.env.TELEPTY_SOURCE_HOST;
-  if (typeof explicit === "string" && explicit.trim()) {
-    return explicit.trim();
-  }
-  const hostname = os.hostname();
-  return typeof hostname === "string" && hostname.trim() ? hostname.trim() : undefined;
-}
-
-function buildTeleptyEnvelope({ session_id, project, kind, source, source_host = resolveTeleptySourceHost(), target, reply_to = null, trace = [], payload, ts = new Date().toISOString(), message_id = createEnvelopeId(kind) }) {
-  return validateTeleptyEnvelope({
-    version: 1,
-    message_id,
-    session_id,
-    project,
-    kind,
-    source,
-    source_host,
-    target,
-    reply_to,
-    trace,
-    payload,
-    ts,
-  });
-}
-
-function buildTeleptyTurnRequestEnvelope({ state, speaker, turnId, turnPrompt, includeHistoryEntries = 0, profile }) {
-  const role = (state.speaker_roles || {})[speaker] || null;
-  const target = profile?.telepty_host && !["127.0.0.1", "localhost"].includes(profile.telepty_host)
-    ? `${profile.telepty_session_id}@${profile.telepty_host}`
-    : profile?.telepty_session_id || speaker;
-  return buildTeleptyEnvelope({
-    session_id: state.id,
-    project: state.project || getProjectSlug(),
-    kind: "turn_request",
-    source: `deliberation:${state.id}`,
-    target,
-    reply_to: state.id,
-    trace: [
-      `project:${state.project || getProjectSlug()}`,
-      `speaker:${speaker}`,
-      `turn:${turnId}`,
-    ],
-    payload: {
-      turn_id: turnId,
-      round: state.current_round,
-      max_rounds: state.max_rounds,
-      speaker,
-      role,
-      prompt: turnPrompt,
-      content: turnPrompt,
-      prompt_sha1: hashPromptText(turnPrompt),
-      history_entries: includeHistoryEntries,
-      transport_timeout_ms: TELEPTY_TRANSPORT_TIMEOUT_MS,
-      semantic_timeout_ms: TELEPTY_SEMANTIC_TIMEOUT_MS,
-    },
-  });
-}
-
-function buildTeleptyTurnCompletedEnvelope({ state, entry }) {
-  return buildTeleptyEnvelope({
-    session_id: state.id,
-    project: state.project || getProjectSlug(),
-    kind: "turn_completed",
-    source: `deliberation:${state.id}`,
-    target: "telepty-bus",
-    reply_to: state.orchestrator_session_id || state.id,
-    trace: [
-      `project:${state.project || getProjectSlug()}`,
-      `speaker:${entry.speaker}`,
-      `turn:${entry.turn_id || "none"}`,
-    ],
-    payload: {
-      turn_id: entry.turn_id || null,
-      speaker: entry.speaker,
-      round: entry.round,
-      max_rounds: state.max_rounds,
-      next_speaker: state.current_speaker || "none",
-      next_round: state.current_round,
-      status: state.status,
-      total_responses: Array.isArray(state.log) ? state.log.length : 0,
-      channel_used: entry.channel_used || null,
-      fallback_reason: entry.fallback_reason || null,
-      orchestrator_session_id: state.orchestrator_session_id || null,
-    },
-  });
-}
-
-function buildTeleptySynthesisEnvelope({ state, synthesis, structured, executionContract }) {
-  const derivedExecutionContract =
-    executionContract !== undefined
-      ? executionContract
-      : (structured ? buildExecutionContract({ state, structured }) : (state.execution_contract || null));
-  return buildTeleptyEnvelope({
-    session_id: state.id,
-    project: state.project || getProjectSlug(),
-    kind: "deliberation_completed",
-    source: `deliberation:${state.id}`,
-    target: "telepty-bus",
-    reply_to: state.id,
-    trace: [
-      `project:${state.project || getProjectSlug()}`,
-      "stage:synthesis",
-    ],
-    payload: {
-      topic: state.topic,
-      synthesis,
-      structured_synthesis: structured || null,
-      execution_contract: derivedExecutionContract || null,
-    },
-  });
-}
-
-function resolveTeleptyBusUrl(host = TELEPTY_DEFAULT_HOST) {
-  const url = new URL(`ws://${host}:${TELEPTY_PORT}/api/bus`);
-  const token = loadTeleptyAuthToken();
-  if (token) {
-    url.searchParams.set("token", token);
-  }
-  return url.toString();
-}
-
-function cleanupPendingTeleptyTurn(messageId) {
-  const entry = pendingTeleptyTurnRequests.get(messageId);
-  if (!entry) return;
-  if (entry.transportTimer) clearTimeout(entry.transportTimer);
-  if (entry.semanticTimer) clearTimeout(entry.semanticTimer);
-  pendingTeleptyTurnRequests.delete(messageId);
-}
-
-function registerPendingTeleptyTurnRequest({ envelope, profile, speaker }) {
-  const nowMs = Date.now();
-  const entry = {
-    message_id: envelope.message_id,
-    deliberation_session_id: envelope.session_id,
-    project: envelope.project,
-    speaker,
-    turn_id: envelope.payload.turn_id,
-    target_session_id: profile?.telepty_session_id || speaker,
-    target_host: profile?.telepty_host || TELEPTY_DEFAULT_HOST,
-    prompt_sha1: envelope.payload.prompt_sha1,
-    published_at: envelope.ts,
-    transport_status: "pending",
-    semantic_status: "pending",
-    transport_deadline_at: new Date(nowMs + TELEPTY_TRANSPORT_TIMEOUT_MS).toISOString(),
-    semantic_deadline_at: new Date(nowMs + TELEPTY_SEMANTIC_TIMEOUT_MS).toISOString(),
-  };
-  entry.transportPromise = new Promise(resolve => {
-    entry.resolveTransport = resolve;
-  });
-  entry.semanticPromise = new Promise(resolve => {
-    entry.resolveSemantic = resolve;
-  });
-  entry.transportTimer = setTimeout(() => {
-    if (entry.transport_status !== "pending") return;
-    entry.transport_status = "timeout";
-    appendRuntimeLog("WARN", `TELEPTY_TRANSPORT_TIMEOUT: ${entry.deliberation_session_id} | speaker: ${entry.speaker} | target: ${entry.target_session_id}`);
-    entry.resolveTransport?.({ ok: false, code: "transport_timeout" });
-  }, TELEPTY_TRANSPORT_TIMEOUT_MS);
-  entry.semanticTimer = setTimeout(() => {
-    if (entry.semantic_status !== "pending") return;
-    entry.semantic_status = "timeout";
-    appendRuntimeLog("WARN", `TELEPTY_SEMANTIC_TIMEOUT: ${entry.deliberation_session_id} | speaker: ${entry.speaker} | target: ${entry.target_session_id}`);
-    entry.resolveSemantic?.({ ok: false, code: "semantic_timeout" });
-    setTimeout(() => cleanupPendingTeleptyTurn(entry.message_id), 5_000);
-  }, TELEPTY_SEMANTIC_TIMEOUT_MS);
-  pendingTeleptyTurnRequests.set(entry.message_id, entry);
-  return entry;
-}
-
-function ackPendingTeleptyTurn(event) {
-  const promptHash = hashPromptText(event?.content || "");
-  const targetSessionId = String(event?.target_agent || "");
-  const candidate = [...pendingTeleptyTurnRequests.values()]
-    .filter(entry =>
-      entry.transport_status === "pending"
-      && entry.target_session_id === targetSessionId
-      && entry.prompt_sha1 === promptHash
-    )
-    .sort((a, b) => Date.parse(b.published_at) - Date.parse(a.published_at))[0];
-  if (!candidate) return null;
-
-  candidate.transport_status = "ack";
-  candidate.inject_id = event.inject_id || null;
-  candidate.transport_acked_at = new Date().toISOString();
-  if (candidate.transportTimer) clearTimeout(candidate.transportTimer);
-  candidate.resolveTransport?.({
-    ok: true,
-    code: "inject_written",
-    inject_id: event.inject_id || null,
-  });
-  appendRuntimeLog("INFO", `TELEPTY_TRANSPORT_ACK: ${candidate.deliberation_session_id} | speaker: ${candidate.speaker} | target: ${candidate.target_session_id} | inject_id: ${event.inject_id || "n/a"}`);
-  return candidate;
-}
-
-function completePendingTeleptySemantic({ sessionId, speaker, turnId }) {
-  const candidate = [...pendingTeleptyTurnRequests.values()]
-    .filter(entry =>
-      entry.semantic_status === "pending"
-      && entry.deliberation_session_id === sessionId
-      && normalizeSpeaker(entry.speaker) === normalizeSpeaker(speaker)
-      && (!turnId || !entry.turn_id || entry.turn_id === turnId)
-    )
-    .sort((a, b) => Date.parse(b.published_at) - Date.parse(a.published_at))[0];
-  if (!candidate) return null;
-
-  candidate.semantic_status = "completed";
-  candidate.semantic_completed_at = new Date().toISOString();
-  if (candidate.semanticTimer) clearTimeout(candidate.semanticTimer);
-  candidate.resolveSemantic?.({ ok: true, code: "responded" });
-  appendRuntimeLog("INFO", `TELEPTY_SEMANTIC_COMPLETE: ${candidate.deliberation_session_id} | speaker: ${candidate.speaker} | target: ${candidate.target_session_id}`);
-  setTimeout(() => cleanupPendingTeleptyTurn(candidate.message_id), 5_000);
-  return candidate;
-}
-
-function updateTeleptySessionHealth(event) {
-  const sessionId = event?.session_id;
-  if (!sessionId) return null;
-  const health = {
-    session_id: sessionId,
-    payload: event.payload || {},
-    timestamp: event.timestamp || new Date().toISOString(),
-    seen_at: new Date().toISOString(),
-  };
-  teleptyBusState.healthBySession.set(sessionId, health);
-  return health;
-}
-
-function getTeleptySessionHealth(sessionId, nowMs = Date.now()) {
-  const entry = teleptyBusState.healthBySession.get(sessionId);
-  if (!entry) return null;
-  const seenAtMs = Date.parse(entry.seen_at || entry.timestamp || "");
-  const ageMs = Number.isFinite(seenAtMs) ? nowMs - seenAtMs : null;
-  return {
-    ...entry,
-    age_ms: ageMs,
-    stale: Number.isFinite(ageMs) ? ageMs > TELEPTY_SESSION_HEALTH_STALE_MS : true,
-  };
-}
-
-function handleTeleptyBusMessage(raw) {
-  let parsed = null;
-  try {
-    parsed = JSON.parse(String(raw));
-  } catch {
-    return null;
-  }
-  teleptyBusState.lastMessageAt = new Date().toISOString();
-  if (!parsed || typeof parsed !== "object") return null;
-
-  if (parsed.type === "inject_written") {
-    return ackPendingTeleptyTurn(parsed);
-  }
-  if (parsed.type === "session_health") {
-    return updateTeleptySessionHealth(parsed);
-  }
-  return parsed;
-}
-
-async function ensureTeleptyBusSubscriber() {
-  if (teleptyBusState.ws && teleptyBusState.ws.readyState === WebSocket.OPEN) {
-    return { ok: true, status: "open" };
-  }
-  if (teleptyBusState.connectPromise) {
-    return teleptyBusState.connectPromise;
-  }
-
-  teleptyBusState.connectPromise = new Promise((resolve) => {
-    try {
-      let settled = false;
-      const finish = (result) => {
-        if (settled) return;
-        settled = true;
-        resolve(result);
-      };
-      teleptyBusState.status = "connecting";
-      const ws = new WebSocket(resolveTeleptyBusUrl());
-      teleptyBusState.ws = ws;
-
-      ws.once("open", () => {
-        teleptyBusState.status = "open";
-        teleptyBusState.lastConnectedAt = new Date().toISOString();
-        teleptyBusState.lastError = null;
-        appendRuntimeLog("INFO", "TELEPTY_BUS_CONNECTED");
-        finish({ ok: true, status: "open" });
-      });
-
-      ws.on("message", (data) => {
-        handleTeleptyBusMessage(data.toString());
-      });
-
-      ws.on("error", (err) => {
-        teleptyBusState.lastError = String(err?.message || err);
-        appendRuntimeLog("WARN", `TELEPTY_BUS_ERROR: ${teleptyBusState.lastError}`);
-        if (ws.readyState !== WebSocket.OPEN) {
-          teleptyBusState.status = "error";
-          teleptyBusState.ws = null;
-          teleptyBusState.connectPromise = null;
-          finish({ ok: false, status: "error", error: teleptyBusState.lastError });
-        }
-      });
-
-      ws.on("close", () => {
-        teleptyBusState.status = "closed";
-        teleptyBusState.ws = null;
-        teleptyBusState.connectPromise = null;
-        if (!settled) {
-          finish({ ok: false, status: "closed", error: teleptyBusState.lastError || "socket closed" });
-        }
-        if (!teleptyBusState.reconnectTimer) {
-          teleptyBusState.reconnectTimer = setTimeout(() => {
-            teleptyBusState.reconnectTimer = null;
-            ensureTeleptyBusSubscriber().catch(() => {});
-          }, TELEPTY_BUS_RECONNECT_MS);
-        }
-      });
-    } catch (err) {
-      teleptyBusState.status = "error";
-      teleptyBusState.lastError = String(err?.message || err);
-      teleptyBusState.connectPromise = null;
-      resolve({ ok: false, status: "error", error: teleptyBusState.lastError });
-    }
-  });
-
-  const result = await teleptyBusState.connectPromise;
-  if (!result.ok) {
-    teleptyBusState.connectPromise = null;
-  } else if (teleptyBusState.ws?.readyState === WebSocket.OPEN) {
-    teleptyBusState.connectPromise = null;
-  }
-  return result;
-}
-
-async function callBrainIngest(executionContract) {
-  if (!executionContract) return { ok: false, reason: "no_contract" };
-  try {
-    const inboxDir = path.join(os.homedir(), ".aigentry", "inbox");
-    if (!fs.existsSync(inboxDir)) {
-      fs.mkdirSync(inboxDir, { recursive: true });
-    }
-    const fileName = `handoff-${executionContract.deliberation_id}.json`;
-    const filePath = path.join(inboxDir, fileName);
-    fs.writeFileSync(filePath, JSON.stringify(executionContract, null, 2), "utf8");
-    appendRuntimeLog("INFO", `BRAIN_INGEST: wrote handoff file ${filePath}`);
-    return { ok: true, path: filePath };
-  } catch (err) {
-    appendRuntimeLog("WARN", `BRAIN_INGEST: failed to write handoff file: ${err.message}`);
-    return { ok: false, error: err.message };
-  }
-}
-
-async function notifyTeleptyBus(event) {
-  const host = process.env.TELEPTY_HOST || "localhost";
-  const port = process.env.TELEPTY_PORT || "3848";
-  const token = loadTeleptyAuthToken();
-  try {
-    const res = await fetch(`http://${host}:${port}/api/bus/publish`, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        ...(token ? { "x-telepty-token": token } : {}),
-      },
-      body: JSON.stringify(event),
-    });
-    const data = await res.json().catch(() => null);
-    if (res.ok) {
-      appendRuntimeLog("INFO", `HANDOFF: Telepty bus notified: ${event.kind || event.type || "unknown"}`);
-      return { ok: true, delivered: data?.delivered ?? null };
-    }
-    return { ok: false, status: res.status, error: data?.error || `HTTP ${res.status}` };
-  } catch (err) {
-    appendRuntimeLog("WARN", `HANDOFF: Telepty bus notification failed: ${err.message}`);
-    return { ok: false, error: err.message };
-  }
-}
-
-function getDefaultOrchestratorSessionId() {
-  // Check multiple env vars that may indicate an orchestrator context
-  const candidates = [
-    process.env.TELEPTY_SESSION_ID,
-    process.env.DELIBERATION_ORCHESTRATOR_ID,
-    process.env.ORCHESTRATOR_SESSION_ID,
-  ];
-  for (const value of candidates) {
-    if (typeof value === "string" && value.trim()) return value.trim();
-  }
-  return null;
-}
-
-function buildTurnCompletionNotificationText(state, entry) {
-  const nextSpeaker = state.current_speaker || "none";
-  const turnId = entry.turn_id || "(none)";
-  if (state.status === "awaiting_synthesis") {
-    return [
-      `[deliberation turn complete]`,
-      `session_id: ${state.id}`,
-      `speaker: ${entry.speaker}`,
-      `turn_id: ${turnId}`,
-      `round: ${entry.round}/${state.max_rounds}`,
-      `status: awaiting_synthesis`,
-      `responses: ${state.log.length}`,
-      `all rounds complete; run deliberation_synthesize(session_id: "${state.id}")`,
-      `no further reply needed.`,
-    ].join("\n");
-  }
-
-  return [
-    `[deliberation turn complete]`,
-    `session_id: ${state.id}`,
-    `speaker: ${entry.speaker}`,
-    `turn_id: ${turnId}`,
-    `round: ${entry.round}/${state.max_rounds}`,
-    `status: ${state.status}`,
-    `next_speaker: ${nextSpeaker}`,
-    `next_round: ${state.current_round}/${state.max_rounds}`,
-    `responses: ${state.log.length}`,
-    `informational notification only.`,
-    `no further reply needed.`,
-  ].join("\n");
-}
-
-async function notifyTeleptySessionInject({ targetSessionId, prompt, fromSessionId, replyToSessionId = null, host = TELEPTY_DEFAULT_HOST }) {
-  if (!targetSessionId || !prompt) return { ok: false, error: "missing target or prompt" };
-  const token = loadTeleptyAuthToken();
-  if (!token) return { ok: false, error: "telepty auth token unavailable" };
-
-  try {
-    const response = await fetch(`http://${host}:${TELEPTY_PORT}/api/sessions/${encodeURIComponent(targetSessionId)}/inject`, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        "x-telepty-token": token,
-      },
-      body: JSON.stringify({
-        prompt,
-        from: fromSessionId || null,
-        reply_to: replyToSessionId || null,
-        deliberation_session_id: null,
-        thread_id: null,
-      }),
-    });
-    const data = await response.json().catch(() => null);
-    if (!response.ok) {
-      return { ok: false, error: data?.error || `HTTP ${response.status}` };
-    }
-    return { ok: true, inject_id: data?.inject_id || null };
-  } catch (err) {
-    return { ok: false, error: String(err?.message || err) };
-  }
-}
-
-async function dispatchTeleptyTurnRequest({ state, speaker, prompt = null, includeHistoryEntries = 4, awaitSemantic = false }) {
-  const { profile } = resolveTransportForSpeaker(state, speaker);
-  const turnId = state.pending_turn_id || generateTurnId();
-  const turnPrompt = buildClipboardTurnPrompt(state, speaker, prompt, includeHistoryEntries);
-  const busReady = await ensureTeleptyBusSubscriber();
-  const envelope = buildTeleptyTurnRequestEnvelope({
-    state,
-    speaker,
-    turnId,
-    turnPrompt,
-    includeHistoryEntries,
-    profile,
-  });
-  const pending = registerPendingTeleptyTurnRequest({ envelope, profile, speaker });
-  const publishResult = await notifyTeleptyBus(envelope);
-  const health = profile?.telepty_session_id ? getTeleptySessionHealth(profile.telepty_session_id) : null;
-
-  if (!publishResult.ok) {
-    cleanupPendingTeleptyTurn(envelope.message_id);
-    return {
-      ok: false,
-      stage: "publish",
-      envelope,
-      turnPrompt,
-      publishResult,
-      busReady,
-      health,
-    };
-  }
-
-  const transportResult = await pending.transportPromise;
-  let semanticResult = null;
-  if (awaitSemantic && transportResult.ok) {
-    semanticResult = await pending.semanticPromise;
-  }
-
-  return {
-    ok: !awaitSemantic ? transportResult.ok : Boolean(semanticResult?.ok),
-    stage: awaitSemantic ? (semanticResult?.ok ? "semantic" : (semanticResult?.code || "semantic_timeout")) : (transportResult.ok ? "transport" : (transportResult?.code || "transport_timeout")),
-    envelope,
-    turnPrompt,
-    publishResult,
-    transportResult,
-    semanticResult,
-    busReady,
-    health,
-  };
-}
-
-function getArchiveDir(projectSlug = getProjectSlug()) {
-  const slug = normalizeProjectSlug(projectSlug);
-  const obsidianDir = path.join(OBSIDIAN_PROJECTS, slug, "deliberations");
-  if (fs.existsSync(path.join(OBSIDIAN_PROJECTS, slug))) {
-    return obsidianDir;
-  }
-  return path.join(getProjectStateDir(slug), "archive");
-}
+// findSessionRecord — moved to lib/session.js
+// getArchiveDir — moved to lib/session.js
 
 function getLocksDir(projectSlug = getProjectSlug()) {
   return path.join(getProjectStateDir(projectSlug), LOCKS_SUBDIR);
@@ -1154,6 +407,15 @@ function appendRuntimeLog(level, message) {
 
 function safeToolHandler(toolName, handler) {
   return async (args) => {
+    const entitlement = checkToolEntitlement(toolName);
+    if (!entitlement.allowed) {
+      return {
+        content: [{
+          type: "text",
+          text: `⛔ ${entitlement.reason}. Current tier: ${entitlement.tier}.\nUpgrade: ${entitlement.upgrade_url || 'https://aigentry.dev/upgrade'}`,
+        }],
+      };
+    }
     try {
       return await handler(args);
     } catch (error) {
@@ -1251,2505 +513,51 @@ function withFileLock(lockPath, fn, options) {
 }
 
 function withProjectLock(projectSlug, fn, options) {
-  if (typeof projectSlug === "function") {
-    return withFileLock(path.join(getLocksDir(), "_project.lock"), projectSlug, fn);
-  }
-  return withFileLock(path.join(getLocksDir(projectSlug), "_project.lock"), fn, options);
-}
-
-function withSessionLock(sessionRef, fn, options) {
-  const sessionId = typeof sessionRef === "object" && sessionRef !== null ? sessionRef.id : sessionRef;
-  const explicitProject = typeof sessionRef === "object" && sessionRef !== null ? sessionRef.project : null;
-  const record = findSessionRecord(sessionRef, { preferProject: explicitProject || getProjectSlug() });
-  const projectSlug = explicitProject || record?.project || getProjectSlug();
-  const safeId = String(sessionId).replace(/[^a-zA-Z0-9가-힣._-]/g, "_");
-  return withFileLock(path.join(getLocksDir(projectSlug), `${safeId}.lock`), fn, options);
-}
-
-function normalizeSpeaker(raw) {
-  if (typeof raw !== "string") return null;
-  const normalized = raw.trim().toLowerCase();
-  if (!normalized || normalized === "none") return null;
-  return normalized;
-}
-
-function dedupeSpeakers(items = []) {
-  const out = [];
-  const seen = new Set();
-  for (const item of items) {
-    const normalized = normalizeSpeaker(item);
-    if (!normalized || seen.has(normalized)) continue;
-    seen.add(normalized);
-    out.push(normalized);
-  }
-  return out;
-}
-
-function createSelectionToken() {
-  return `sel-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
-}
-
-function issueSpeakerSelectionToken({ candidates, include_browser }) {
-  const selectionState = {
-    token: createSelectionToken(),
-    phase: "candidates",
-    created_at: new Date().toISOString(),
-    include_browser: !!include_browser,
-    candidate_speakers: dedupeSpeakers((candidates || []).map(c => typeof c === "string" ? c : c?.speaker)),
-  };
-  writeJsonFileAtomic(getSpeakerSelectionFile(), selectionState);
-  return selectionState;
-}
-
-function loadSpeakerSelectionToken() {
-  return readJsonFileSafe(getSpeakerSelectionFile());
-}
-
-function clearSpeakerSelectionToken() {
-  try {
-    fs.unlinkSync(getSpeakerSelectionFile());
-  } catch {
-    // ignore missing file
-  }
-}
-
-function validateSpeakerSelectionSnapshot({ selectionState, selection_token, speakers, includeBrowserSpeakers, nowMs = Date.now() }) {
-  if (!selection_token) {
-    return { ok: false, code: "missing_token" };
-  }
-  if (!selectionState?.token) {
-    return { ok: false, code: "missing_selection_state" };
-  }
-  if (selectionState.token !== selection_token) {
-    return { ok: false, code: "token_mismatch" };
-  }
-
-  const createdAtMs = Date.parse(selectionState.created_at || "");
-  if (!Number.isFinite(createdAtMs) || (nowMs - createdAtMs) > SPEAKER_SELECTION_TTL_MS) {
-    return { ok: false, code: "expired_token" };
-  }
-
-  if (!!selectionState.include_browser !== !!includeBrowserSpeakers) {
-    return { ok: false, code: "mode_mismatch" };
-  }
-
-  const availableSpeakers = new Set(dedupeSpeakers(selectionState.candidate_speakers || []));
-  const requestedSpeakers = dedupeSpeakers(speakers || []);
-  const missingSpeakers = requestedSpeakers.filter(speaker => !availableSpeakers.has(speaker));
-  if (missingSpeakers.length > 0) {
-    return { ok: false, code: "speaker_mismatch", missing_speakers: missingSpeakers };
-  }
-
-  return { ok: true };
-}
-
-function confirmSpeakerSelectionToken({ selectionState, selection_token, speakers, includeBrowserSpeakers, nowMs = Date.now(), persist = true }) {
-  const snapshotValidation = validateSpeakerSelectionSnapshot({
-    selectionState,
-    selection_token,
-    speakers,
-    includeBrowserSpeakers,
-    nowMs,
-  });
-  if (!snapshotValidation.ok) {
-    return snapshotValidation;
-  }
-
-  const confirmedSelection = {
-    token: createSelectionToken(),
-    phase: "confirmed",
-    created_at: new Date(nowMs).toISOString(),
-    include_browser: !!includeBrowserSpeakers,
-    candidate_speakers: dedupeSpeakers(selectionState.candidate_speakers || []),
-    selected_speakers: dedupeSpeakers(speakers || []),
-  };
-  if (persist) {
-    writeJsonFileAtomic(getSpeakerSelectionFile(), confirmedSelection);
-  }
-  return { ok: true, selectionState: confirmedSelection };
-}
-
-function validateSpeakerSelectionRequest({ selectionState, selection_token, speakers, includeBrowserSpeakers, nowMs = Date.now() }) {
-  const snapshotValidation = validateSpeakerSelectionSnapshot({
-    selectionState,
-    selection_token,
-    speakers,
-    includeBrowserSpeakers,
-    nowMs,
-  });
-  if (!snapshotValidation.ok) {
-    return snapshotValidation;
-  }
-
-  if (selectionState.phase !== "confirmed" || !Array.isArray(selectionState.selected_speakers)) {
-    return { ok: false, code: "selection_not_confirmed" };
-  }
-
-  const expectedSpeakers = dedupeSpeakers(selectionState.selected_speakers || []);
-  const requestedSpeakers = dedupeSpeakers(speakers || []);
-  if (
-    expectedSpeakers.length !== requestedSpeakers.length
-    || expectedSpeakers.some(speaker => !requestedSpeakers.includes(speaker))
-  ) {
-    return {
-      ok: false,
-      code: "selected_speakers_mismatch",
-      expected_speakers: expectedSpeakers,
-      requested_speakers: requestedSpeakers,
-    };
-  }
-
-  return { ok: true };
-}
-
-function hasExplicitBrowserParticipantSelection({ speakers, participant_types } = {}) {
-  const manualSpeakers = Array.isArray(speakers) ? speakers : [];
-  const hasBrowserSpeaker = manualSpeakers.some(speaker => {
-    const normalized = normalizeSpeaker(speaker);
-    return normalized?.startsWith("web-");
-  });
-  if (hasBrowserSpeaker) return true;
-
-  const overrides = participant_types && typeof participant_types === "object"
-    ? Object.entries(participant_types)
-    : [];
-
-  return overrides.some(([speaker, type]) => {
-    const normalized = normalizeSpeaker(speaker);
-    return normalized?.startsWith("web-") || type === "browser" || type === "browser_auto";
-  });
-}
-
-function resolveIncludeBrowserSpeakers({ include_browser_speakers, config, speakers, participant_types } = {}) {
-  if (include_browser_speakers !== undefined && include_browser_speakers !== null) {
-    return include_browser_speakers;
-  }
-  if (config?.include_browser_speakers !== undefined && config?.include_browser_speakers !== null) {
-    return config.include_browser_speakers;
-  }
-  return false;
-}
-
-function resolveCliCandidates() {
-  const fromEnv = (process.env.DELIBERATION_CLI_CANDIDATES || "")
-    .split(/[,\s]+/)
-    .map(v => v.trim())
-    .filter(Boolean);
-
-  // If config has enabled_clis, use that as the primary filter
-  const config = loadDeliberationConfig();
-  if (Array.isArray(config.enabled_clis) && config.enabled_clis.length > 0) {
-    return dedupeSpeakers([...fromEnv, ...config.enabled_clis]);
-  }
-
-  return dedupeSpeakers([...fromEnv, ...DEFAULT_CLI_CANDIDATES]);
-}
-
-function loadTeleptyAuthToken() {
-  try {
-    const raw = fs.readFileSync(TELEPTY_CONFIG_FILE, "utf-8");
-    const parsed = JSON.parse(raw);
-    return typeof parsed?.authToken === "string" && parsed.authToken.trim()
-      ? parsed.authToken.trim()
-      : null;
-  } catch {
-    return null;
-  }
-}
-
-function formatTeleptyHostLabel(host) {
-  return !host || host === "127.0.0.1" || host === "localhost" ? "Local" : host;
-}
-
-async function collectTeleptySessions() {
-  const token = loadTeleptyAuthToken();
-  if (!token) {
-    return { sessions: [], note: "telepty auth token not found." };
-  }
-
-  const host = TELEPTY_DEFAULT_HOST;
-  try {
-    const res = await fetch(`http://${host}:${TELEPTY_PORT}/api/sessions`, {
-      headers: { "x-telepty-token": token },
-      signal: AbortSignal.timeout(1500),
-    });
-    if (!res.ok) {
-      return { sessions: [], note: `telepty daemon unavailable (${res.status}).` };
-    }
-    const sessions = await res.json();
-    if (!Array.isArray(sessions)) {
-      return { sessions: [], note: "telepty session response format was invalid." };
-    }
-    ensureTeleptyBusSubscriber().catch(() => {});
-    return {
-      sessions: sessions.map(session => ({ host, ...session })),
-      note: null,
-    };
-  } catch {
-    return { sessions: [], note: null };
-  }
-}
-
-function scoreTeleptyProcessMatch(session, baseCommand = "", fullCommand = "") {
-  const base = String(baseCommand || "").toLowerCase();
-  const full = String(fullCommand || "").toLowerCase();
-  const wanted = String(session?.command || "").trim().toLowerCase();
-  let score = 0;
-
-  if (wanted && (base === wanted || full.startsWith(`${wanted} `) || full.includes(` ${wanted} `))) {
-    score += 10;
-  }
-  if (base === "node" || base === "telepty") {
-    score -= 2;
-  }
-  if (full.includes("mcp-deliberation") || full.includes("oh-my-claudecode") || full.includes("bridge/mcp-server")) {
-    score -= 3;
-  }
-  return score;
-}
-
-function collectTeleptyProcessLocators(sessions = []) {
-  const wantedSessions = new Map(
-    sessions
-      .filter(session => session?.id)
-      .map(session => [String(session.id), session])
-  );
-  if (wantedSessions.size === 0) {
-    return new Map();
-  }
-
-  try {
-    const env = {
-      HOME: process.env.HOME,
-      PATH: process.env.PATH,
-      SHELL: process.env.SHELL,
-      USER: process.env.USER,
-      LOGNAME: process.env.LOGNAME,
-      TERM: process.env.TERM,
-    };
-    const raw = execFileSync("ps", ["eww", "-axo", "pid=,tty=,comm=,command="], {
-      encoding: "utf-8",
-      windowsHide: true,
-      timeout: 2500,
-      maxBuffer: 8 * 1024 * 1024,
-      env,
-    });
-
-    const best = new Map();
-    for (const line of String(raw).split("\n")) {
-      if (!line.includes("TELEPTY_SESSION_ID=")) continue;
-      const match = line.match(/^\s*(\d+)\s+(\S+)\s+(\S+)\s+(.*)$/);
-      if (!match) continue;
-      const [, pid, tty, comm, command] = match;
-      const sessionIdMatch = command.match(/(?:^|\s)TELEPTY_SESSION_ID=([^\s]+)/);
-      const sessionId = sessionIdMatch?.[1];
-      if (!sessionId || !wantedSessions.has(sessionId)) continue;
-
-      const session = wantedSessions.get(sessionId);
-      const score = scoreTeleptyProcessMatch(session, comm, command);
-      const current = best.get(sessionId);
-      if (!current || score > current.score) {
-        best.set(sessionId, { pid: Number(pid), tty, score });
-      }
-    }
-
-    return new Map(
-      [...best.entries()].map(([sessionId, value]) => [
-        sessionId,
-        { pid: Number.isFinite(value.pid) ? value.pid : null, tty: value.tty || null },
-      ])
-    );
-  } catch {
-    return new Map();
-  }
-}
-
-function commandExistsInPath(command) {
-  if (!command || !/^[a-zA-Z0-9._-]+$/.test(command)) {
-    return false;
-  }
-
-  if (process.platform === "win32") {
-    try {
-      execFileSync("where", [command], { stdio: "ignore" });
-      return true;
-    } catch {
-      // keep PATH scan fallback for shells where "where" is unavailable
-    }
-  }
-
-  const pathVar = process.env.PATH || "";
-  const dirs = pathVar.split(path.delimiter).filter(Boolean);
-  if (dirs.length === 0) return false;
-
-  const extensions = process.platform === "win32"
-    ? ["", ".exe", ".cmd", ".bat", ".ps1"]
-    : [""];
-
-  for (const dir of dirs) {
-    for (const ext of extensions) {
-      const fullPath = path.join(dir, `${command}${ext}`);
-      try {
-        fs.accessSync(fullPath, fs.constants.X_OK);
-        return true;
-      } catch {
-        // ignore and continue
-      }
-    }
-  }
-  return false;
-}
-
-function shellQuote(value) {
-  return `'${String(value).replace(/'/g, "'\\''")}'`;
-}
-
-function checkCliLiveness(command) {
-  const hint = CLI_INVOCATION_HINTS[command];
-  const env = { ...process.env };
-  // Unset CLAUDECODE to avoid nested session errors
-  if (hint?.envPrefix?.includes("CLAUDECODE=")) {
-    delete env.CLAUDECODE;
-  }
-  try {
-    execFileSync(command, ["--version"], {
-      stdio: "ignore",
-      windowsHide: true,
-      timeout: 5000,
-      env,
-    });
-    return true;
-  } catch {
-    // --version failed, try --help as fallback
-    try {
-      execFileSync(command, ["--help"], {
-        stdio: "ignore",
-        windowsHide: true,
-        timeout: 5000,
-        env,
-      });
-      return true;
-    } catch {
-      return false;
-    }
-  }
-}
-
-function discoverLocalCliSpeakers() {
-  const found = [];
-  for (const candidate of resolveCliCandidates()) {
-    if (commandExistsInPath(candidate)) {
-      found.push(candidate);
-    }
-    if (found.length >= MAX_AUTO_DISCOVERED_SPEAKERS) {
-      break;
-    }
-  }
-  return found;
-}
-
-function detectCallerSpeaker() {
-  const hinted = normalizeSpeaker(process.env.DELIBERATION_CALLER_SPEAKER);
-  if (hinted) return hinted;
-
-  const envKeys = Object.keys(process.env).join(" ");
-  const pathHint = process.env.PATH || "";
-
-  // Codex detection
-  if (/\bCODEX_[A-Z0-9_]+\b/.test(envKeys) || pathHint.includes("/.codex/")) {
-    return "codex";
-  }
-
-  // Claude detection
-  if (/\bCLAUDE_[A-Z0-9_]+\b/.test(envKeys) || pathHint.includes("/.claude/")) {
-    return "claude";
-  }
-
-  // Gemini detection
-  if (/\bGOOGLE_GENAI_[A-Z0-9_]+\b/.test(envKeys) || /\bGEMINI_[A-Z0-9_]+\b/.test(envKeys) || pathHint.includes("/.gemini/")) {
-    return "gemini";
-  }
-
-  // Aider detection
-  if (/\bAIDER_[A-Z0-9_]+\b/.test(envKeys) || pathHint.includes("/aider/")) {
-    return "aider";
-  }
-
-  return null;
-}
-
-function isLlmUrl(url = "") {
-  const value = String(url || "").trim();
-  if (!value) return false;
-  try {
-    const parsed = new URL(value);
-    const host = parsed.hostname.toLowerCase();
-    return DEFAULT_LLM_DOMAINS.some(domain => host === domain || host.endsWith(`.${domain}`));
-  } catch {
-    const lowered = value.toLowerCase();
-    return DEFAULT_LLM_DOMAINS.some(domain => lowered.includes(domain));
-  }
-}
-
-function dedupeBrowserTabs(tabs = []) {
-  const out = [];
-  const seen = new Set();
-  for (const tab of tabs) {
-    const browser = String(tab?.browser || "").trim();
-    const title = String(tab?.title || "").trim();
-    const url = String(tab?.url || "").trim();
-    if (!url || (!isLlmUrl(url) && !isExtensionLlmTab(url, title))) continue;
-    // Dedup by title+url (ignore browser name) so that the same tab detected
-    // via both AppleScript and CDP is not duplicated. The first occurrence wins,
-    // so callers should add preferred sources first (e.g., CDP before AppleScript).
-    const key = `${title}\t${url}`;
-    if (seen.has(key)) continue;
-    seen.add(key);
-    out.push({
-      browser: browser || "Browser",
-      title: title || "(untitled)",
-      url,
-    });
-  }
-  return out;
-}
-
-function parseInjectedBrowserTabsFromEnv() {
-  const raw = process.env.DELIBERATION_BROWSER_TABS_JSON;
-  if (!raw) {
-    return { tabs: [], note: null };
-  }
-
-  try {
-    const parsed = JSON.parse(raw);
-    if (!Array.isArray(parsed)) {
-      return { tabs: [], note: "DELIBERATION_BROWSER_TABS_JSON format error: must be a JSON array." };
-    }
-
-    const tabs = dedupeBrowserTabs(parsed.map(item => ({
-      browser: item?.browser || "External Bridge",
-      title: item?.title || "(untitled)",
-      url: item?.url || "",
-    })));
-    return {
-      tabs,
-      note: tabs.length > 0 ? `Environment variable tab injection: ${tabs.length} tabs` : "No valid LLM URLs found in DELIBERATION_BROWSER_TABS_JSON.",
-    };
-  } catch (error) {
-    const reason = error instanceof Error ? error.message : "unknown error";
-    return { tabs: [], note: `Failed to parse DELIBERATION_BROWSER_TABS_JSON: ${reason}` };
-  }
-}
-
-function normalizeCdpEndpoint(raw) {
-  const value = String(raw || "").trim();
-  if (!value) return null;
-
-  const withProto = /^https?:\/\//i.test(value) ? value : `http://${value}`;
-  try {
-    const url = new URL(withProto);
-    if (!url.pathname || url.pathname === "/") {
-      url.pathname = "/json/list";
-    }
-    return url.toString();
-  } catch {
-    return null;
-  }
-}
-
-function resolveCdpEndpoints() {
-  const fromEnv = (process.env.DELIBERATION_BROWSER_CDP_ENDPOINTS || "")
-    .split(/[,\s]+/)
-    .map(v => normalizeCdpEndpoint(v))
-    .filter(Boolean);
-  if (fromEnv.length > 0) {
-    return [...new Set(fromEnv)];
-  }
-
-  const ports = (process.env.DELIBERATION_BROWSER_CDP_PORTS || "9222,9223,9333")
-    .split(/[,\s]+/)
-    .map(v => Number.parseInt(v, 10))
-    .filter(v => Number.isInteger(v) && v > 0 && v < 65536);
-
-  const endpoints = [];
-  for (const port of ports) {
-    endpoints.push(`http://127.0.0.1:${port}/json/list`);
-    endpoints.push(`http://localhost:${port}/json/list`);
-  }
-  return [...new Set(endpoints)];
-}
-
-async function fetchJson(url, timeoutMs = 900) {
-  if (typeof fetch !== "function") {
-    throw new Error("fetch API unavailable in current Node runtime");
-  }
-
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), timeoutMs);
-  try {
-    const response = await fetch(url, {
-      method: "GET",
-      signal: controller.signal,
-      headers: { "accept": "application/json" },
-    });
-    if (!response.ok) {
-      throw new Error(`HTTP ${response.status}`);
-    }
-    return await response.json();
-  } finally {
-    clearTimeout(timer);
-  }
-}
-
-function inferBrowserFromCdpEndpoint(endpoint) {
-  try {
-    const parsed = new URL(endpoint);
-    const port = Number.parseInt(parsed.port, 10);
-    if (port === 9222) return "Google Chrome (CDP)";
-    if (port === 9223) return "Microsoft Edge (CDP)";
-    if (port === 9333) return "Brave Browser (CDP)";
-    return `Browser (CDP:${parsed.host})`;
-  } catch {
-    return "Browser (CDP)";
-  }
-}
-
-function summarizeFailures(items = [], max = 3) {
-  if (!Array.isArray(items) || items.length === 0) return null;
-  const shown = items.slice(0, max);
-  const suffix = items.length > max ? ` and ${items.length - max} more` : "";
-  return `${shown.join(", ")}${suffix}`;
-}
-
-async function collectBrowserLlmTabsViaCdp() {
-  const endpoints = resolveCdpEndpoints();
-  const tabs = [];
-  const failures = [];
-
-  for (const endpoint of endpoints) {
-    try {
-      const payload = await fetchJson(endpoint);
-      if (!Array.isArray(payload)) {
-        throw new Error("unexpected payload");
-      }
-
-      const browser = inferBrowserFromCdpEndpoint(endpoint);
-      for (const item of payload) {
-        if (!item || String(item.type) !== "page") continue;
-        const url = String(item.url || "").trim();
-        const title = String(item.title || "").trim();
-        if (!isLlmUrl(url) && !isExtensionLlmTab(url, title)) continue;
-        tabs.push({
-          browser,
-          title: title || "(untitled)",
-          url,
-        });
-      }
-    } catch (error) {
-      const reason = error instanceof Error ? error.message : "unknown error";
-      failures.push(`${endpoint} (${reason})`);
-    }
-  }
-
-  const uniqTabs = dedupeBrowserTabs(tabs);
-  if (uniqTabs.length > 0) {
-    const failSummary = summarizeFailures(failures);
-    return {
-      tabs: uniqTabs,
-      note: failSummary ? `Some CDP endpoint access failed: ${failSummary}` : null,
-    };
-  }
-
-  const failSummary = summarizeFailures(failures);
-  return {
-    tabs: [],
-    note: `No LLM tabs found via CDP. Run browser with --remote-debugging-port=9222 or inject tab list via DELIBERATION_BROWSER_TABS_JSON.${failSummary ? ` (failed: ${failSummary})` : ""}`,
-  };
-}
-
-async function ensureCdpAvailable() {
-  const endpoints = resolveCdpEndpoints();
-
-  // First attempt: try existing CDP endpoints
-  for (const endpoint of endpoints) {
-    try {
-      const payload = await fetchJson(endpoint, 1500);
-      if (Array.isArray(payload)) {
-        return { available: true, endpoint };
-      }
-    } catch { /* not reachable */ }
-  }
-
-  // Auto-launch Chrome with CDP on macOS, Linux, and Windows
-  {
-    let chromeBin, chromeUserDataDir;
-
-    if (process.platform === "darwin") {
-      chromeBin = "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome";
-      chromeUserDataDir = path.join(os.homedir(), "Library", "Application Support", "Google", "Chrome");
-    } else if (process.platform === "linux") {
-      const chromeCandidates = ["google-chrome", "google-chrome-stable", "google-chrome-beta", "chromium-browser", "chromium"];
-      chromeBin = chromeCandidates.find(c => commandExistsInPath(c)) || null;
-      if (!chromeBin) {
-        return {
-          available: false,
-          reason: "Chrome/Chromium not found. Install google-chrome or chromium and run with --remote-debugging-port=9222.",
-        };
-      }
-      const googleDir = path.join(os.homedir(), ".config", "google-chrome");
-      const chromiumDir = path.join(os.homedir(), ".config", "chromium");
-      chromeUserDataDir = fs.existsSync(googleDir) ? googleDir : fs.existsSync(chromiumDir) ? chromiumDir : null;
-    } else if (process.platform === "win32") {
-      const programFiles = process.env.PROGRAMFILES || "C:\\Program Files";
-      const programFilesX86 = process.env["PROGRAMFILES(X86)"] || "C:\\Program Files (x86)";
-      const localAppData = process.env.LOCALAPPDATA || path.join(os.homedir(), "AppData", "Local");
-      const winCandidates = [
-        path.join(programFiles, "Google", "Chrome", "Application", "chrome.exe"),
-        path.join(programFilesX86, "Google", "Chrome", "Application", "chrome.exe"),
-        path.join(localAppData, "Google", "Chrome", "Application", "chrome.exe"),
-        path.join(programFilesX86, "Microsoft", "Edge", "Application", "msedge.exe"),
-        path.join(programFiles, "Microsoft", "Edge", "Application", "msedge.exe"),
-      ];
-      chromeBin = winCandidates.find(p => fs.existsSync(p)) || null;
-      if (!chromeBin) {
-        return {
-          available: false,
-          reason: "Chrome/Edge not found. Install Chrome or run with --remote-debugging-port=9222.",
-        };
-      }
-      const chromeDir = path.join(localAppData, "Google", "Chrome", "User Data");
-      const edgeDir = path.join(localAppData, "Microsoft", "Edge", "User Data");
-      chromeUserDataDir = fs.existsSync(chromeDir) ? chromeDir : fs.existsSync(edgeDir) ? edgeDir : null;
-    } else {
-      return {
-        available: false,
-        reason: "Cannot activate Chrome CDP. Run Chrome with --remote-debugging-port=9222.",
-      };
-    }
-
-    // Chrome 145+ requires --user-data-dir for CDP to work.
-    // The default data dir is rejected, so we copy the profile to ~/.chrome-cdp.
-    // Profile can be set via env DELIBERATION_CHROME_PROFILE or config.chrome_profile (e.g., "Profile 1").
-    const cdpDataDir = path.join(os.homedir(), ".chrome-cdp");
-    const cdpConfig = loadDeliberationConfig();
-    const profileDir = process.env.DELIBERATION_CHROME_PROFILE || cdpConfig.chrome_profile || "Default";
-
-    try {
-      if (chromeUserDataDir) {
-        const srcProfile = path.join(chromeUserDataDir, profileDir);
-        const dstProfile = path.join(cdpDataDir, profileDir);
-        // Track which profile was copied; re-copy if profile changed
-        const profileMarker = path.join(cdpDataDir, ".cdp-profile");
-        const lastProfile = fs.existsSync(profileMarker) ? fs.readFileSync(profileMarker, "utf8").trim() : null;
-        const needsCopy = !fs.existsSync(dstProfile) || (lastProfile && lastProfile !== profileDir);
-        if (needsCopy && fs.existsSync(srcProfile)) {
-          // Clean old profile if switching
-          if (lastProfile && lastProfile !== profileDir) {
-            const oldDst = path.join(cdpDataDir, lastProfile);
-            if (fs.existsSync(oldDst)) fs.rmSync(oldDst, { recursive: true, force: true });
-          }
-          fs.mkdirSync(cdpDataDir, { recursive: true });
-          execFileSync("cp", ["-R", srcProfile, dstProfile], { timeout: 30000, stdio: "ignore" });
-          fs.writeFileSync(profileMarker, profileDir);
-          // Create minimal Local State with single profile to avoid profile picker
-          const localStateSrc = path.join(chromeUserDataDir, "Local State");
-          if (fs.existsSync(localStateSrc)) {
-            const state = JSON.parse(fs.readFileSync(localStateSrc, "utf8"));
-            state.profile.profiles_created = 1;
-            state.profile.last_used = profileDir;
-            if (state.profile.info_cache) {
-              const kept = {};
-              if (state.profile.info_cache[profileDir]) kept[profileDir] = state.profile.info_cache[profileDir];
-              state.profile.info_cache = kept;
-            }
-            fs.writeFileSync(path.join(cdpDataDir, "Local State"), JSON.stringify(state));
-          }
-        }
-      }
-    } catch { /* proceed with launch attempt anyway */ }
-
-    const launchArgs = [
-      "--remote-debugging-port=9222",
-      "--remote-allow-origins=http://127.0.0.1:9222",
-      `--user-data-dir=${cdpDataDir}`,
-      `--profile-directory=${profileDir}`,
-      "--no-first-run",
-    ];
-
-    try {
-      const child = spawn(chromeBin, launchArgs, { stdio: "ignore", detached: true });
-      child.unref();
-    } catch {
-      return {
-        available: false,
-        reason: `Failed to auto-launch Chrome. Manually run Chrome with --remote-debugging-port=9222 --user-data-dir=~/.chrome-cdp.`,
-      };
-    }
-
-    // Wait for Chrome to initialize CDP
-    await new Promise(resolve => setTimeout(resolve, 5000));
-
-    // Retry CDP connection after launch
-    for (const endpoint of endpoints) {
-      try {
-        const payload = await fetchJson(endpoint, 2000);
-        if (Array.isArray(payload)) {
-          return { available: true, endpoint, launched: true };
-        }
-      } catch { /* still not reachable */ }
-    }
-
-    return {
-      available: false,
-      reason: "Chrome launched but cannot connect to CDP. Fully close Chrome and try again. (Restart required if Chrome was started without CDP)",
-    };
-  }
-
-  // Unreachable (all platforms handled above), but keep as safety net
-  return {
-    available: false,
-    reason: "Cannot activate Chrome CDP. Run Chrome with --remote-debugging-port=9222.",
-  };
-}
-
-function collectBrowserLlmTabsViaAppleScript() {
-  if (process.platform !== "darwin") {
-    return { tabs: [], note: "AppleScript tab scanning is only supported on macOS." };
-  }
-
-  const escapedDomains = DEFAULT_LLM_DOMAINS.map(d => d.replace(/"/g, '\\"'));
-  const escapedApps = DEFAULT_BROWSER_APPS.map(a => a.replace(/"/g, '\\"'));
-  const domainList = `{${escapedDomains.map(d => `"${d}"`).join(", ")}}`;
-  const appList = `{${escapedApps.map(a => `"${a}"`).join(", ")}}`;
-
-  // NOTE: Use stdin pipe (`osascript -`) instead of multiple `-e` flags
-  // because osascript's `-e` mode silently breaks with nested try/on error blocks.
-  // Also wrap dynamic `tell application` with `using terms from` so that
-  // Chrome-specific properties like `tabs` resolve via the scripting dictionary.
-  // Use ASCII character 9 for tab delimiter because `using terms from`
-  // shadows the built-in `tab` constant, turning it into the literal string "tab".
-  const scriptText = `set llmDomains to ${domainList}
-set browserApps to ${appList}
-set outText to ""
-set tabChar to ASCII character 9
-tell application "System Events"
-set runningApps to name of every application process
-end tell
-repeat with appName in browserApps
-if runningApps contains (appName as string) then
-try
-if (appName as string) is "Safari" then
-using terms from application "Safari"
-tell application (appName as string)
-repeat with w in windows
-try
-repeat with t in tabs of w
-set u to URL of t as string
-set matched to false
-repeat with d in llmDomains
-if u contains (d as string) then set matched to true
-end repeat
-if matched then set outText to outText & (appName as string) & tabChar & (name of t as string) & tabChar & u & linefeed
-end repeat
-end try
-end repeat
-end tell
-end using terms from
-else
-using terms from application "Google Chrome"
-tell application (appName as string)
-repeat with w in windows
-try
-repeat with t in tabs of w
-set u to URL of t as string
-set matched to false
-repeat with d in llmDomains
-if u contains (d as string) then set matched to true
-end repeat
-if matched then set outText to outText & (appName as string) & tabChar & (title of t as string) & tabChar & u & linefeed
-end repeat
-end try
-end repeat
-end tell
-end using terms from
-end if
-on error errMsg
-set outText to outText & (appName as string) & tabChar & "ERROR" & tabChar & errMsg & linefeed
-end try
-end if
-end repeat
-return outText`;
-
-  try {
-    const raw = execFileSync("osascript", ["-"], {
-      input: scriptText,
-      encoding: "utf-8",
-      timeout: 8000,
-      maxBuffer: 2 * 1024 * 1024,
-    });
-    const rows = String(raw)
-      .split("\n")
-      .map(line => line.trim())
-      .filter(Boolean)
-      .map(line => {
-        const [browser = "", title = "", url = ""] = line.split("\t");
-        return { browser, title, url };
-      });
-    const tabs = rows.filter(r => r.title !== "ERROR");
-    const errors = rows.filter(r => r.title === "ERROR");
-    return {
-      tabs,
-      note: errors.length > 0
-        ? `Some browser access failed: ${errors.map(e => `${e.browser} (${e.url})`).join(", ")}`
-        : null,
-    };
-  } catch (error) {
-    const reason = error instanceof Error ? error.message : "unknown error";
-    return {
-      tabs: [],
-      note: `Browser tab scan failed: ${reason}. Check macOS automation permissions (Terminal -> Browser control).`,
-    };
-  }
-}
-
-async function collectBrowserLlmTabs() {
-  const mode = (process.env.DELIBERATION_BROWSER_SCAN_MODE || "auto").trim().toLowerCase();
-  const tabs = [];
-  const notes = [];
-
-  const injected = parseInjectedBrowserTabsFromEnv();
-  tabs.push(...injected.tabs);
-  if (injected.note) notes.push(injected.note);
-
-  if (mode === "off") {
-    return {
-      tabs: dedupeBrowserTabs(tabs),
-      note: notes.length > 0 ? notes.join(" | ") : "Browser tab auto-scanning is disabled.",
-    };
-  }
-
-  // CDP first: CDP-detected tabs are preferred over AppleScript-detected ones
-  // because they carry CDP metadata (tab ID, WebSocket URL) for browser_auto transport.
-  // Since dedupeBrowserTabs keeps the first occurrence, CDP entries win the dedup.
-  const shouldUseCdp = mode === "auto" || mode === "cdp";
-  if (shouldUseCdp) {
-    const cdp = await collectBrowserLlmTabsViaCdp();
-    tabs.push(...cdp.tabs);
-    if (cdp.note) notes.push(cdp.note);
-  }
-
-  const shouldUseAppleScript = mode === "auto" || mode === "applescript";
-  if (shouldUseAppleScript && process.platform === "darwin") {
-    const mac = collectBrowserLlmTabsViaAppleScript();
-    tabs.push(...mac.tabs);
-    if (mac.note) notes.push(mac.note);
-  } else if (mode === "applescript" && process.platform !== "darwin") {
-    notes.push("AppleScript scanning is macOS only. Switch to CDP scanning.");
-  }
-
-  const uniqTabs = dedupeBrowserTabs(tabs);
-  return {
-    tabs: uniqTabs,
-    note: notes.length > 0 ? notes.join(" | ") : null,
-  };
-}
-
-function inferLlmProvider(url = "", title = "") {
-  const value = String(url).toLowerCase();
-  // Extension side panel: infer from title via registry
-  if (value.startsWith("chrome-extension://") && title) {
-    const registry = loadExtensionProviderRegistry();
-    const lowerTitle = String(title).toLowerCase();
-    for (const entry of registry.providers) {
-      if (entry.titlePatterns.some(p => lowerTitle.includes(p.toLowerCase()))) {
-        return entry.provider;
-      }
-    }
-    return "extension-llm";
-  }
-  if (value.includes("claude.ai") || value.includes("anthropic.com")) return "claude";
-  if (value.includes("chatgpt.com") || value.includes("openai.com")) return "chatgpt";
-  if (value.includes("gemini.google.com") || value.includes("notebooklm.google.com")) return "gemini";
-  if (value.includes("copilot.microsoft.com")) return "copilot";
-  if (value.includes("perplexity.ai")) return "perplexity";
-  if (value.includes("poe.com")) return "poe";
-  if (value.includes("mistral.ai")) return "mistral";
-  if (value.includes("huggingface.co/chat")) return "huggingchat";
-  if (value.includes("deepseek.com")) return "deepseek";
-  if (value.includes("qwen.ai")) return "qwen";
-  if (value.includes("grok.com")) return "grok";
-  return "web-llm";
-}
-
-async function collectSpeakerCandidates({ include_cli = true, include_browser = true } = {}) {
-  const candidates = [];
-  const seen = new Set();
-  let browserNote = null;
-
-  const add = (candidate) => {
-    const speaker = normalizeSpeaker(candidate?.speaker);
-    if (!speaker || seen.has(speaker)) return;
-    seen.add(speaker);
-    candidates.push({ ...candidate, speaker });
-  };
-
-  if (include_cli) {
-    for (const cli of discoverLocalCliSpeakers()) {
-      const live = checkCliLiveness(cli);
-      add({
-        speaker: cli,
-        type: "cli",
-        label: cli,
-        command: cli,
-        live,
-      });
-    }
-
-    const { sessions: teleptySessions, note: teleptyNote } = await collectTeleptySessions();
-    const locators = collectTeleptyProcessLocators(teleptySessions);
-    for (const session of teleptySessions) {
-      const locator = locators.get(session.id) || {};
-      add({
-        speaker: session.id,
-        type: "telepty",
-        label: session.id,
-        telepty_session_id: session.id,
-        telepty_host: session.host || TELEPTY_DEFAULT_HOST,
-        command: session.command || "wrapped",
-        cwd: session.cwd || null,
-        active_clients: session.active_clients ?? null,
-        runtime_pid: locator.pid ?? null,
-        runtime_tty: locator.tty ?? null,
-      });
-    }
-    if (teleptyNote) {
-      browserNote = browserNote ? `${browserNote} | ${teleptyNote}` : teleptyNote;
-    }
-  }
-
-  if (include_browser) {
-    // Ensure CDP is available before probing browser tabs
-    const cdpStatus = await ensureCdpAvailable();
-    if (cdpStatus.launched) {
-      browserNote = "Chrome CDP auto-launched (--remote-debugging-port=9222)";
-    }
-
-    const { tabs, note } = await collectBrowserLlmTabs();
-    browserNote = browserNote ? `${browserNote} | ${note || ""}`.replace(/ \| $/, "") : (note || null);
-    const providerCounts = new Map();
-    for (const tab of tabs) {
-      const provider = inferLlmProvider(tab.url, tab.title);
-      const count = (providerCounts.get(provider) || 0) + 1;
-      providerCounts.set(provider, count);
-      add({
-        speaker: `web-${provider}-${count}`,
-        type: "browser",
-        provider,
-        browser: tab.browser || "",
-        title: tab.title || "",
-        url: tab.url || "",
-      });
-    }
-
-    // CDP auto-detection: probe endpoints for matching tabs
-    const cdpEndpoints = resolveCdpEndpoints();
-    const cdpTabsMap = new Map(); // dedupe by tab ID (multiple endpoints may return same tabs)
-    for (const endpoint of cdpEndpoints) {
-      try {
-        const tabs = await fetchJson(endpoint, 2000);
-        if (Array.isArray(tabs)) {
-          for (const t of tabs) {
-            if (t.type === "page" && t.url && t.id && !cdpTabsMap.has(t.id)) {
-              cdpTabsMap.set(t.id, t);
-            }
-          }
-        }
-      } catch { /* endpoint not reachable */ }
-    }
-    const cdpTabs = [...cdpTabsMap.values()];
-
-    // Match CDP tabs with discovered browser candidates
-    for (const candidate of candidates) {
-      if (candidate.type !== "browser") continue;
-      // For extension candidates, match by title instead of hostname
-      const candidateUrl = String(candidate.url || "");
-      if (candidateUrl.startsWith("chrome-extension://")) {
-        const candidateTitle = String(candidate.title || "").toLowerCase();
-        if (candidateTitle) {
-          const matches = cdpTabs.filter(t =>
-            String(t.url || "").startsWith("chrome-extension://") &&
-            String(t.title || "").toLowerCase().includes(candidateTitle)
-          );
-          if (matches.length >= 1) {
-            candidate.cdp_available = true;
-            candidate.cdp_tab_id = matches[0].id;
-            candidate.cdp_ws_url = matches[0].webSocketDebuggerUrl;
-          }
-        }
-        continue;
-      }
-      let candidateHost = "";
-      try {
-        candidateHost = new URL(candidate.url).hostname.toLowerCase();
-      } catch { continue; }
-      if (!candidateHost) continue;
-      const matches = cdpTabs.filter(t => {
-        try {
-          return new URL(t.url).hostname.toLowerCase() === candidateHost;
-        } catch { return false; }
-      });
-      if (matches.length >= 1) {
-        candidate.cdp_available = true;
-        candidate.cdp_tab_id = matches[0].id;
-        candidate.cdp_ws_url = matches[0].webSocketDebuggerUrl;
-      }
-    }
-
-    // Auto-register well-known web LLMs that weren't already detected via browser scanning.
-    // This ensures web speakers are ALWAYS available regardless of browser detection success.
-    // If a browser tab for the same provider was already detected, skip auto-registration
-    // to avoid duplicates (e.g., detected "web-chatgpt-1" vs auto-registered "web-chatgpt").
-    const detectedProviders = new Set(
-      candidates.filter(c => c.type === "browser" && !c.auto_registered).map(c => c.provider)
-    );
-    // CDP is reachable if we got any tabs from the endpoints (attach() handles auto-tab-creation)
-    const cdpReachable = cdpTabs.length > 0 || cdpStatus.available;
-    for (const ws of DEFAULT_WEB_SPEAKERS) {
-      if (detectedProviders.has(ws.provider)) continue;
-      add({
-        speaker: ws.speaker,
-        type: "browser",
-        provider: ws.provider,
-        browser: "auto-registered",
-        title: ws.name,
-        url: ws.url,
-        auto_registered: true,
-        cdp_available: cdpReachable,
-      });
-    }
-
-    // Second pass: match auto-registered speakers to individual CDP tabs
-    // (they were added after the first matching pass and only got the global cdpReachable flag)
-    if (cdpTabs.length > 0) {
-      for (const candidate of candidates) {
-        if (!candidate.auto_registered || candidate.cdp_tab_id) continue;
-        let candidateHost = "";
-        try {
-          candidateHost = new URL(candidate.url).hostname.toLowerCase();
-        } catch { continue; }
-        if (!candidateHost) continue;
-        const matches = cdpTabs.filter(t => {
-          try {
-            const tabHost = new URL(t.url).hostname.toLowerCase();
-            // Exact match or subdomain match (e.g., chat.deepseek.com matches deepseek.com)
-            return tabHost === candidateHost || tabHost.endsWith("." + candidateHost);
-          } catch { return false; }
-        });
-        if (matches.length >= 1) {
-          candidate.cdp_available = true;
-          candidate.cdp_tab_id = matches[0].id;
-          candidate.cdp_ws_url = matches[0].webSocketDebuggerUrl;
-        }
-      }
-    }
-
-    // Third pass: upgrade browser-detected candidates that missed the first hostname match.
-    // When CDP is reachable, AppleScript-detected speakers should also get browser_auto
-    // transport. The OrchestratedBrowserPort will create/navigate tabs on demand if needed.
-    if (cdpReachable) {
-      for (const candidate of candidates) {
-        if (candidate.type !== "browser" || candidate.auto_registered) continue;
-        if (candidate.cdp_available) continue; // already matched
-        candidate.cdp_available = true;
-      }
-    }
-  }
-
-  return { candidates, browserNote };
-}
-
-function formatSpeakerCandidatesReport({ candidates, browserNote }) {
-  const cli = candidates.filter(c => c.type === "cli");
-  const telepty = candidates.filter(c => c.type === "telepty");
-  const detected = candidates.filter(c => c.type === "browser" && !c.auto_registered);
-  const autoReg = candidates.filter(c => c.type === "browser" && c.auto_registered);
-
-  let out = "## Selectable Speakers\n\n";
-  out += "### CLI\n";
-  if (cli.length === 0) {
-    out += "- (No local CLI detected)\n\n";
-  } else {
-    out += `${cli.map(c => {
-      const status = c.live === false ? " ❌ not executable" : c.live === true ? " ✅ executable" : "";
-      return `- \`${c.speaker}\` (command: ${c.command})${status}`;
-    }).join("\n")}\n\n`;
-  }
-
-  out += "### Telepty Sessions\n";
-  if (telepty.length === 0) {
-    out += "- (No active telepty sessions)\n\n";
-  } else {
-    out += `${telepty.map(c => {
-      const parts = [
-        `command: ${c.command || "wrapped"}`,
-        c.telepty_host ? `host: ${formatTeleptyHostLabel(c.telepty_host)}` : null,
-        Number.isFinite(c.runtime_pid) ? `pid: ${c.runtime_pid}` : null,
-        c.runtime_tty ? `tty: ${c.runtime_tty}` : null,
-      ].filter(Boolean).join(", ");
-      const cwdLine = c.cwd ? `\n  cwd: ${c.cwd}` : "";
-      return `- \`${c.speaker}\` (${parts})${cwdLine}`;
-    }).join("\n")}\n\n`;
-  }
-
-  out += "### Browser LLM (detected)\n";
-  if (detected.length === 0) {
-    out += "- (No LLM tabs detected in browser)\n";
-  } else {
-    out += `${detected.map(c => {
-      const icon = c.cdp_available ? "⚡auto" : "📋clipboard";
-      const extTag = String(c.url || "").startsWith("chrome-extension://") ? " [Extension]" : "";
-      return `- \`${c.speaker}\` [${icon}]${extTag} [${c.browser}] ${c.title}\n  ${c.url}`;
-    }).join("\n")}\n`;
-  }
-
-  out += "\n### Web LLM (auto-registered)\n";
-  out += `${autoReg.map(c => {
-    const icon = c.cdp_available ? "⚡auto" : "📋clipboard";
-    return `- \`${c.speaker}\` [${icon}] — ${c.title} (${c.url})`;
-  }).join("\n")}\n`;
-
-  if (browserNote) {
-    out += `\n\nℹ️ ${browserNote}`;
-  }
-  return out;
-}
-
-function mapParticipantProfiles(speakers, candidates, typeOverrides) {
-  const bySpeaker = new Map();
-  for (const c of candidates || []) {
-    const key = normalizeSpeaker(c.speaker);
-    if (key) bySpeaker.set(key, c);
-  }
-
-  const overrides = typeOverrides || {};
-
-  const profiles = [];
-  for (const raw of speakers || []) {
-    const speaker = normalizeSpeaker(raw);
-    if (!speaker) continue;
-
-    // Check for explicit type override
-    const overrideType = overrides[speaker] || overrides[raw];
-    if (overrideType) {
-      const candidate = bySpeaker.get(speaker);
-      profiles.push({
-        speaker,
-        type: overrideType,
-        ...(overrideType === "browser_auto" || overrideType === "browser" ? {
-          provider: candidate?.provider || null,
-          browser: candidate?.browser || null,
-          title: candidate?.title || null,
-          url: candidate?.url || null,
-        } : {}),
-      });
-      continue;
-    }
-
-    const candidate = bySpeaker.get(speaker);
-    if (!candidate) {
-      // Force CLI type if the speaker is available as a CLI command in PATH
-      if (commandExistsInPath(speaker)) {
-        profiles.push({
-          speaker,
-          type: "cli",
-          command: speaker,
-        });
-      } else {
-        profiles.push({
-          speaker,
-          type: "manual",
-        });
-      }
-      continue;
-    }
-
-    if (candidate.type === "cli") {
-      profiles.push({
-        speaker,
-        type: "cli",
-        command: candidate.command || speaker,
-      });
-      continue;
-    }
-
-    if (candidate.type === "telepty") {
-      profiles.push({
-        speaker,
-        type: "telepty",
-        command: candidate.command || null,
-        telepty_session_id: candidate.telepty_session_id || speaker,
-        telepty_host: candidate.telepty_host || null,
-        runtime_pid: Number.isFinite(candidate.runtime_pid) ? candidate.runtime_pid : null,
-      });
-      continue;
-    }
-
-    const effectiveType = candidate.cdp_available ? "browser_auto" : "browser";
-    profiles.push({
-      speaker,
-      type: effectiveType,
-      provider: candidate.provider || null,
-      browser: candidate.browser || null,
-      title: candidate.title || null,
-      url: candidate.url || null,
-    });
-  }
-  return profiles;
-}
-
-// ── Transport routing ─────────────────────────────────────────
-
-const TRANSPORT_TYPES = {
-  cli: "cli_respond",
-  telepty: "telepty_bus",
-  browser: "clipboard",
-  browser_auto: "browser_auto",
-  manual: "manual",
-};
-
-// BrowserControlPort singleton — initialized lazily on first use
-let _browserPort = null;
-function getBrowserPort() {
-  if (!_browserPort) {
-    const cdpEndpoints = resolveCdpEndpoints();
-    _browserPort = new OrchestratedBrowserPort({ cdpEndpoints });
-  }
-  return _browserPort;
-}
-
-function resolveTransportForSpeaker(state, speaker) {
-  const normalizedSpeaker = normalizeSpeaker(speaker);
-  if (!normalizedSpeaker || !state?.participant_profiles) {
-    return { transport: "manual", reason: "no_profile" };
-  }
-  const profile = state.participant_profiles.find(
-    p => normalizeSpeaker(p.speaker) === normalizedSpeaker
-  );
-  if (!profile) {
-    return { transport: "manual", reason: "speaker_not_in_profiles" };
-  }
-  const transport = TRANSPORT_TYPES[profile.type] || "manual";
-  return { transport, profile, reason: null };
-}
-
-// CLI-specific invocation flags for non-interactive execution
-const CLI_INVOCATION_HINTS = {
-  claude: { cmd: "claude", flags: '-p --output-format text', example: 'CLAUDECODE= claude -p --output-format text "prompt"', envPrefix: 'CLAUDECODE=', modelFlag: '--model', provider: 'claude' },
-  codex: { cmd: "codex", flags: 'exec -', example: 'echo "prompt" | codex exec -', stdinMode: true, modelFlag: '--model', defaultModel: 'default', provider: 'chatgpt' },
-  gemini: { cmd: "gemini", flags: '', example: 'gemini "prompt"', modelFlag: '--model', provider: 'gemini' },
-  aider: { cmd: "aider", flags: '--message', example: 'aider --message "prompt"', modelFlag: '--model', provider: 'chatgpt' },
-  cursor: { cmd: "cursor", flags: '', example: 'cursor "prompt"', modelFlag: null, provider: 'chatgpt' },
-};
-
-function formatTransportGuidance(transport, state, speaker) {
-  const sid = state.id;
-  const profile = (state.participant_profiles || []).find(
-    p => normalizeSpeaker(p.speaker) === normalizeSpeaker(speaker)
-  ) || null;
-  switch (transport) {
-    case "cli_respond": {
-      const hint = CLI_INVOCATION_HINTS[speaker] || null;
-      let invocationGuide = "";
-      let modelGuide = "";
-      if (hint) {
-        const prefix = hint.envPrefix || '';
-        invocationGuide = `\n\n**CLI invocation:** \`${hint.example}\`\n(flags: \`${prefix}${hint.cmd} ${hint.flags}\`)`;
-        if (hint.modelFlag && hint.provider) {
-          const cliModel = getModelSelectionForTurn(state, speaker, hint.provider);
-          if (cliModel.model !== 'default') {
-            modelGuide = `\n**Recommended model:** ${cliModel.model} (${cliModel.reason})\n**Model flag:** \`${hint.modelFlag} ${cliModel.model}\``;
-          }
-        }
-      }
-      return `CLI speaker. Respond directly via \`deliberation_respond(session_id: "${sid}", speaker: "${speaker}", content: "...")\`.${invocationGuide}${modelGuide}\n\n⛔ **No API calls**: Do not call LLM APIs directly via REST API, HTTP requests, urllib, requests, etc. Only use the CLI tools above.`;
-    }
-    case "clipboard":
-      return `Browser LLM speaker. Copy the prompt below and paste it into the browser LLM using **Cmd+V (ㅍ)**, then submit the response via \`deliberation_respond(session_id: "${sid}", speaker: "${speaker}", use_clipboard: true)\` after copying the LLM's response with **Cmd+C (ㅊ)**.\n\n` +
-             `📋 **Prompt has been copied to your clipboard.** (If not, copy the [turn_prompt] section below manually).\n` +
-             `🖼️ **To include an image:** Copy the image to your clipboard and use \`include_clipboard_image: true\` in \`deliberation_respond\`.\n\n` +
-             `⛔ **No API calls**: This speaker responds only via web browser. Do not call LLMs via REST API or HTTP requests.`;
-    case "browser_auto":
-      return `Auto browser speaker. Proceed automatically with \`deliberation_browser_auto_turn(session_id: "${sid}")\`. Inputs directly to browser LLM via CDP and reads responses.\n\n⛔ **No API calls**: Proceeds only via CDP automation. No REST API or HTTP requests.`;
-    case "telepty_bus":
-      return `Telepty session speaker. This turn will be published on the telepty bus as a structured \`turn_request\` envelope for the target session to consume.\n\n` +
-             `📡 **Bus delivery**: deliberation publishes a typed envelope instead of relying on raw PTY inject.\n` +
-             `⏱️ **Timeouts**: transport ack waits ${TELEPTY_TRANSPORT_TIMEOUT_MS / 1000}s, semantic self-submit waits ${TELEPTY_SEMANTIC_TIMEOUT_MS / 1000}s.\n` +
-             `⛔ **No proxy response**: the remote telepty session must answer for itself via \`deliberation_respond(...)\`.`;
-    case "manual":
-    default:
-      if (profile?.type === "telepty" && profile.telepty_session_id) {
-        const hostSuffix = profile.telepty_host && !["127.0.0.1", "localhost"].includes(profile.telepty_host)
-          ? `@${profile.telepty_host}`
-          : "";
-        const pidNote = Number.isFinite(profile.runtime_pid) ? ` (pid ${profile.runtime_pid})` : "";
-        return `Telepty-managed session speaker${pidNote}. Send the [turn_prompt] below to \`telepty inject ${profile.telepty_session_id}${hostSuffix} "<prompt>"\`, then have that remote session self-submit via \`deliberation_respond(session_id: "${sid}", speaker: "${speaker}", content: "...")\`.\n\n` +
-               `📋 **Recommended path**: inject the prompt into the telepty session and let the remote session answer for itself.\n` +
-               `⛔ **No proxy response**: Do not answer on behalf of this speaker from the orchestrator.`;
-      }
-      return `Manual speaker. Get a response from the LLM's **web UI or CLI tool** and submit via \`deliberation_respond(session_id: "${sid}", speaker: "${speaker}", content: "...")\`.\n\n` +
-             `📋 **Copy the [turn_prompt] section below** to the web UI.\n` +
-             `🖼️ **To include an image:** Copy the image to your clipboard and use \`include_clipboard_image: true\` in \`deliberation_respond\`.\n\n` +
-             `⛔ **Absolutely no API calls**: Calling LLM APIs directly via REST API, HTTP requests (urllib, requests, fetch, etc.) is forbidden. Only use web browser UI or CLI tools. Direct API key calls will result in deliberation participation being rejected.`;
-  }
-}
-
-function buildSpeakerOrder(speakers, fallbackSpeaker = DEFAULT_SPEAKERS[0], fallbackPlacement = "front") {
-  const ordered = [];
-  const seen = new Set();
-
-  const add = (candidate) => {
-    const speaker = normalizeSpeaker(candidate);
-    if (!speaker || seen.has(speaker)) return;
-    seen.add(speaker);
-    ordered.push(speaker);
-  };
-
-  if (fallbackPlacement === "front") {
-    add(fallbackSpeaker);
-  }
-
-  if (Array.isArray(speakers)) {
-    for (const speaker of speakers) {
-      add(speaker);
-    }
-  }
-
-  if (fallbackPlacement !== "front") {
-    add(fallbackSpeaker);
-  }
-
-  if (ordered.length === 0) {
-    for (const speaker of DEFAULT_SPEAKERS) {
-      add(speaker);
-    }
-  }
-
-  return ordered;
-}
-
-function normalizeSessionActors(state) {
-  if (!state || typeof state !== "object") return state;
-
-  const fallbackSpeaker = normalizeSpeaker(state.current_speaker)
-    || normalizeSpeaker(state.log?.[0]?.speaker)
-    || DEFAULT_SPEAKERS[0];
-  const speakers = buildSpeakerOrder(state.speakers, fallbackSpeaker, "end");
-  state.speakers = speakers;
-
-  const normalizedCurrent = normalizeSpeaker(state.current_speaker);
-  if (state.status === "active") {
-    state.current_speaker = (normalizedCurrent && speakers.includes(normalizedCurrent))
-      ? normalizedCurrent
-      : speakers[0];
-  } else if (normalizedCurrent) {
-    state.current_speaker = normalizedCurrent;
-  }
-
-  return state;
-}
-
-// ── Session ID generation ─────────────────────────────────────
-
-function generateSessionId(topic) {
-  const slug = topic
-    .replace(/[^a-zA-Z0-9가-힣\s-]/g, "")
-    .replace(/\s+/g, "-")
-    .toLowerCase()
-    .slice(0, 20);
-  const ts = Date.now().toString(36);
-  const rand = Math.random().toString(36).slice(2, 6);
-  return `${slug}-${ts}${rand}`;
-}
-
-function generateTurnId() {
-  return `t-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
-}
-
-// ── Context detection ──────────────────────────────────────────
-
-function detectContextDirs() {
-  const dirs = [];
-  const slug = getProjectSlug();
-
-  if (process.env.DELIBERATION_CONTEXT_DIR) {
-    dirs.push(process.env.DELIBERATION_CONTEXT_DIR);
-  }
-  dirs.push(process.cwd());
-
-  const obsidianProject = path.join(OBSIDIAN_PROJECTS, slug);
-  if (fs.existsSync(obsidianProject)) {
-    dirs.push(obsidianProject);
-  }
-
-  return [...new Set(dirs)];
-}
-
-function readContextFromDirs(dirs, maxChars = 15000) {
-  let context = "";
-  const seen = new Set();
-
-  for (const dir of dirs) {
-    if (!fs.existsSync(dir)) continue;
-
-    const files = fs.readdirSync(dir)
-      .filter(f => f.endsWith(".md") && !f.startsWith("_") && !f.startsWith("."))
-      .sort();
-
-    for (const file of files) {
-      if (seen.has(file)) continue;
-      seen.add(file);
-
-      const fullPath = path.join(dir, file);
-      let raw;
-      try { raw = fs.readFileSync(fullPath, "utf-8"); } catch { continue; }
-
-      let body = raw;
-      if (body.startsWith("---")) {
-        const end = body.indexOf("---", 3);
-        if (end !== -1) body = body.slice(end + 3).trim();
-      }
-
-      const truncated = body.length > 1200
-        ? body.slice(0, 1200) + "\n(...)"
-        : body;
-
-      context += `### ${file.replace(".md", "")}\n${truncated}\n\n---\n\n`;
-
-      if (context.length > maxChars) {
-        context = context.slice(0, maxChars) + "\n\n(...context truncated)";
-        return context;
-      }
-    }
-  }
-  return context || "(No context files found)";
-}
-
-// ── State helpers ──────────────────────────────────────────────
-
-function ensureDirs(projectSlug = getProjectSlug()) {
-  fs.mkdirSync(getSessionsDir(projectSlug), { recursive: true });
-  fs.mkdirSync(getArchiveDir(projectSlug), { recursive: true });
-  fs.mkdirSync(getLocksDir(projectSlug), { recursive: true });
-}
-
-function loadSession(sessionRef) {
-  const record = findSessionRecord(sessionRef);
-  return record?.state || null;
-}
-
-function saveSession(state) {
-  ensureDirs(state.project);
-  state.updated = new Date().toISOString();
-  writeTextAtomic(getSessionFile(state), JSON.stringify(state, null, 2));
-  syncMarkdown(state);
-}
-
-function listActiveSessions(projectSlug) {
-  const projects = projectSlug
-    ? [normalizeProjectSlug(projectSlug)]
-    : [...new Set([getProjectSlug(), ...listStateProjects()])];
-
-  return projects.flatMap(project => {
-    const dir = getSessionsDir(project);
-    if (!fs.existsSync(dir)) return [];
-
-    return fs.readdirSync(dir)
-      .filter(f => f.endsWith(".json"))
-      .map(f => {
-        try {
-          const data = JSON.parse(fs.readFileSync(path.join(dir, f), "utf-8"));
-          return normalizeSessionActors(data);
-        } catch {
-          return null;
-        }
-      })
-      .filter(s => s && (s.status === "active" || s.status === "awaiting_synthesis"));
-  });
-}
-
-function resolveSessionId(sessionId) {
-  // Use session_id directly if provided
-  if (sessionId) return sessionId;
-
-  // Auto-select when only one active session
-  const active = listActiveSessions();
-  if (active.length === 0) return null;
-  if (active.length === 1) return active[0].id;
-
-  // null if multiple (need to show list)
-  return "MULTIPLE";
-}
-
-function syncMarkdown(state) {
-  const filename = `deliberation-${state.id}.md`;
-  const mdPath = path.join(getProjectStateDir(state.project), filename);
-  try {
-    writeTextAtomic(mdPath, stateToMarkdown(state));
-  } catch { /* ignore sync failures */ }
-}
-
-function cleanupSyncMarkdown(state) {
-  const filename = `deliberation-${state.id}.md`;
-  const statePath = path.join(getProjectStateDir(state.project), filename);
-  try { fs.unlinkSync(statePath); } catch { /* ignore */ }
-  // Also clean up legacy files in CWD (from older versions)
-  const cwdPath = path.join(process.cwd(), filename);
-  try { fs.unlinkSync(cwdPath); } catch { /* ignore */ }
-}
-
-function formatSourceMetadataLine(meta) {
-  if (!meta || typeof meta !== "object") return "";
-  const parts = [];
-  if (meta.source_machine_id) parts.push(`machine: ${meta.source_machine_id}`);
-  if (meta.source_session_id) parts.push(`session: ${meta.source_session_id}`);
-  if (meta.transport_scope) parts.push(`transport: ${meta.transport_scope}`);
-  if (meta.reply_origin) parts.push(`origin: ${meta.reply_origin}`);
-  if (meta.timestamp) parts.push(`timestamp: ${meta.timestamp}`);
-  if (Array.isArray(meta.artifact_refs) && meta.artifact_refs.length > 0) {
-    parts.push(`artifacts: ${meta.artifact_refs.join(", ")}`);
-  }
-  return parts.length > 0 ? `> _source: ${parts.join(" | ")}_\n\n` : "";
-}
-
-function stateToMarkdown(s) {
-  const speakerOrder = buildSpeakerOrder(s.speakers, s.current_speaker, "end");
-  let md = `---
-title: "Deliberation - ${s.topic}"
-session_id: "${s.id}"
-created: ${s.created}
-updated: ${s.updated || new Date().toISOString()}
-type: deliberation
-status: ${s.status}
-project: "${s.project}"
-participants: ${JSON.stringify(speakerOrder)}
-rounds: ${s.max_rounds}
-current_round: ${s.current_round}
-current_speaker: "${s.current_speaker}"
-tags: [deliberation]
----
-
-# Deliberation: ${s.topic}
-
-**Session:** ${s.id} | **Project:** ${s.project} | **Status:** ${s.status} | **Round:** ${s.current_round}/${s.max_rounds} | **Next:** ${s.current_speaker}
-
----
-
-`;
-
-  if (s.synthesis) {
-    md += `## Synthesis\n\n${s.synthesis}\n\n---\n\n`;
-  }
-
-  if (s.structured_synthesis) {
-    md += `## Structured Synthesis\n\n\`\`\`json\n${JSON.stringify(s.structured_synthesis, null, 2)}\n\`\`\`\n\n---\n\n`;
-  }
-
-  if (s.execution_contract) {
-    md += `## Execution Contract\n\n\`\`\`json\n${JSON.stringify(s.execution_contract, null, 2)}\n\`\`\`\n\n---\n\n`;
-  }
-
-  md += `## Debate Log\n\n`;
-  for (const entry of s.log) {
-    md += `### ${entry.speaker} — Round ${entry.round}\n\n`;
-    if (entry.channel_used || entry.fallback_reason) {
-      const parts = [];
-      if (entry.channel_used) parts.push(`channel: ${entry.channel_used}`);
-      if (entry.fallback_reason) parts.push(`fallback: ${entry.fallback_reason}`);
-      md += `> _${parts.join(" | ")}_\n\n`;
-    }
-    md += formatSourceMetadataLine(entry.source_metadata);
-    md += `${entry.content}\n\n`;
-    if (entry.attachments && entry.attachments.length > 0) {
-      for (const att of entry.attachments) {
-        if (att.type === "image") {
-          md += `![Attachment](${att.path})\n\n`;
-        }
-      }
-    }
-    md += `---\n\n`;
-  }
-  return md;
-}
-
-function archiveState(state) {
-  ensureDirs(state.project);
-  const slug = state.topic
-    .replace(/[^a-zA-Z0-9가-힣\s-]/g, "")
-    .replace(/\s+/g, "-")
-    .slice(0, 30);
-  const ts = new Date().toISOString().slice(0, 16).replace(/:/g, "");
-  const filename = `deliberation-${ts}-${slug}.md`;
-  const dest = path.join(getArchiveDir(state.project), filename);
-  writeTextAtomic(dest, stateToMarkdown(state));
-
-  // Write machine-readable execution_contract sidecar for automation consumers
-  if (state.execution_contract) {
-    const contractDest = dest.replace(/\.md$/, ".contract.json");
-    writeTextAtomic(contractDest, JSON.stringify({
-      ...state.execution_contract,
-      _meta: {
-        archived_from: state.id,
-        project: state.project,
-        topic: state.topic,
-        archived_at: new Date().toISOString(),
-      },
-    }, null, 2));
-  }
-
-  return dest;
-}
-
-// ── Terminal management ────────────────────────────────────────
-
-const TMUX_SESSION = "deliberation";
-const MONITOR_SCRIPT = path.join(INSTALL_DIR, "session-monitor.sh");
-const MONITOR_SCRIPT_WIN = path.join(INSTALL_DIR, "session-monitor-win.js");
-
-function tmuxWindowName(sessionId) {
-  // Keep tmux window name short (remove last part, 20 chars)
-  return sessionId.replace(/[^a-zA-Z0-9가-힣-]/g, "").slice(0, 25);
-}
-
-function appleScriptQuote(value) {
-  return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
-}
-
-function tryExecFile(command, args = []) {
-  try {
-    execFileSync(command, args, { stdio: "ignore", windowsHide: true });
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-function resolveMonitorShell() {
-  if (commandExistsInPath("bash")) return "bash";
-  if (commandExistsInPath("sh")) return "sh";
-  return null;
-}
-
-function buildMonitorCommand(sessionId, project) {
-  const shell = resolveMonitorShell();
-  if (!shell) return null;
-  return `${shell} ${shellQuote(MONITOR_SCRIPT)} ${shellQuote(sessionId)} ${shellQuote(project)}`;
-}
-
-function buildMonitorCommandWindows(sessionId, project) {
-  return `node "${MONITOR_SCRIPT_WIN}" "${sessionId}" "${project}"`;
-}
-
-function hasTmuxSession(name) {
-  try {
-    execFileSync("tmux", ["has-session", "-t", name], { stdio: "ignore", windowsHide: true });
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-function hasTmuxWindow(sessionName, windowName) {
-  try {
-    const output = execFileSync("tmux", ["list-windows", "-t", sessionName, "-F", "#{window_name}"], {
-      encoding: "utf-8",
-      stdio: ["ignore", "pipe", "ignore"],
-      windowsHide: true,
-    });
-    return String(output).split("\n").map(s => s.trim()).includes(windowName);
-  } catch {
-    return false;
-  }
-}
-
-function tmuxHasAttachedClients(sessionName) {
-  try {
-    const output = execFileSync("tmux", ["list-clients", "-t", sessionName], {
-      encoding: "utf-8",
-      stdio: ["ignore", "pipe", "ignore"],
-      windowsHide: true,
-    });
-    return String(output).trim().split("\n").filter(Boolean).length > 0;
-  } catch {
-    return false;
-  }
-}
-
-function isTmuxWindowViewed(sessionName, windowName) {
-  try {
-    // List all clients and check for matching window name.
-    // Grouped sessions (created via 'new-session -t') share the same windows,
-    // so checking for the window name anywhere in the client list is sufficient.
-    const output = execFileSync("tmux", ["list-clients", "-F", "#{window_name}"], {
-      encoding: "utf-8",
-      stdio: ["ignore", "pipe", "ignore"],
-      windowsHide: true,
-    });
-    return String(output).split("\n").map(s => s.trim()).filter(Boolean).includes(windowName);
-  } catch {
-    return false;
-  }
-}
-
-function tmuxWindowCount(name) {
-  try {
-    const output = execFileSync("tmux", ["list-windows", "-t", name], {
-      encoding: "utf-8",
-      stdio: ["ignore", "pipe", "ignore"],
-      windowsHide: true,
-    });
-    return String(output)
-      .split("\n")
-      .map(line => line.trim())
-      .filter(Boolean)
-      .length;
-  } catch {
-    return 0;
-  }
-}
-
-function buildTmuxAttachCommand(sessionId) {
-  const winName = tmuxWindowName(sessionId);
-  // Use grouped session (new-session -t) so each terminal has independent active window.
-  // This prevents window-switching conflicts when multiple deliberations run concurrently.
-  return `tmux new-session -t ${shellQuote(TMUX_SESSION)} \\; select-window -t ${shellQuote(`${TMUX_SESSION}:${winName}`)}`;
-}
-
-function listPhysicalTerminalWindowIds() {
-  if (process.platform !== "darwin") {
-    return [];
-  }
-  try {
-    const output = execFileSync(
-      "osascript",
-      [
-        "-e",
-        'tell application "Terminal"',
-        "-e",
-        "if not running then return \"\"",
-        "-e",
-        "set outText to \"\"",
-        "-e",
-        "repeat with w in windows",
-        "-e",
-        "set outText to outText & (id of w as string) & linefeed",
-        "-e",
-        "end repeat",
-        "-e",
-        "return outText",
-        "-e",
-        "end tell",
-      ],
-      { encoding: "utf-8" }
-    );
-    return String(output)
-      .split("\n")
-      .map(s => Number.parseInt(s.trim(), 10))
-      .filter(n => Number.isInteger(n) && n > 0);
-  } catch {
-    return [];
-  }
-}
-
-function openPhysicalTerminal(sessionId) {
-  const winName = tmuxWindowName(sessionId);
-  // Use grouped session (new-session -t) for independent active window per client
-  const attachCmd = `tmux new-session -t "${TMUX_SESSION}" \\; select-window -t "${TMUX_SESSION}:${winName}"`;
-
-  // Prevent duplicate windows for the SAME session:
-  // If a client is already viewing this specific window, just activate Terminal.app
-  if (isTmuxWindowViewed(TMUX_SESSION, winName)) {
-    appendRuntimeLog("INFO", `TMUX_WINDOW_ALREADY_VIEWED: ${winName}. Activating existing Terminal.`);
-    if (process.platform === "darwin") {
-      try {
-        execFileSync("osascript", ["-e", 'tell application "Terminal" to activate'], { stdio: "ignore" });
-      } catch { /* ignore */ }
-    }
-    return { opened: true, windowIds: [] };
-  }
-
-  // If a terminal is already attached to OTHER windows, open a NEW grouped session
-  // instead of select-window (which would hijack all attached clients' views).
-  if (tmuxHasAttachedClients(TMUX_SESSION)) {
-    if (process.platform === "darwin") {
-      const groupAttachCmd = `tmux new-session -t "${TMUX_SESSION}" \\; select-window -t "${TMUX_SESSION}:${winName}"`;
-      try {
-        execFileSync(
-          "osascript",
-          [
-            "-e", 'tell application "Terminal"',
-            "-e", "activate",
-            "-e", `do script ${appleScriptQuote(groupAttachCmd)}`,
-            "-e", "end tell",
-          ],
-          { encoding: "utf-8" }
-        );
-        return { opened: true, windowIds: [] };
-      } catch { /* fall through to default behavior */ }
-    }
-    // Non-macOS or fallback: don't force select-window, just report success
-    // The monitor window already exists in tmux; user can switch manually
-    return { opened: true, windowIds: [] };
-  }
-
-  if (process.platform === "darwin") {
-    const before = new Set(listPhysicalTerminalWindowIds());
-    try {
-      const output = execFileSync(
-        "osascript",
-        [
-          "-e",
-          'tell application "Terminal"',
-          "-e",
-          "activate",
-          "-e",
-          `do script ${appleScriptQuote(attachCmd)}`,
-          "-e",
-          "delay 0.15",
-          "-e",
-          "return id of front window",
-          "-e",
-          "end tell",
-        ],
-        { encoding: "utf-8" }
-      );
-      const frontId = Number.parseInt(String(output).trim(), 10);
-      const after = listPhysicalTerminalWindowIds();
-      const opened = after.filter(id => !before.has(id));
-      if (opened.length > 0) {
-        return { opened: true, windowIds: [...new Set(opened)] };
-      }
-      if (Number.isInteger(frontId) && frontId > 0) {
-        return { opened: true, windowIds: [frontId] };
-      }
-      return { opened: false, windowIds: [] };
-    } catch {
-      return { opened: false, windowIds: [] };
-    }
-  }
-
-  if (process.platform === "linux") {
-    const shell = resolveMonitorShell() || "sh";
-    const launchCmd = `${buildTmuxAttachCommand(sessionId)}; exec ${shell}`;
-    const attempts = [
-      ["gnome-terminal", ["--", shell, "-lc", launchCmd]],
-      ["kgx", ["--", shell, "-lc", launchCmd]],
-      ["konsole", ["-e", shell, "-lc", launchCmd]],
-      ["x-terminal-emulator", ["-e", shell, "-lc", launchCmd]],
-      ["xterm", ["-e", shell, "-lc", launchCmd]],
-      ["alacritty", ["-e", shell, "-lc", launchCmd]],
-      ["kitty", [shell, "-lc", launchCmd]],
-      ["wezterm", ["start", "--", shell, "-lc", launchCmd]],
-    ];
-
-    for (const [command, args] of attempts) {
-      if (!commandExistsInPath(command)) continue;
-      if (tryExecFile(command, args)) {
-        return { opened: true, windowIds: [] };
-      }
-    }
-    return { opened: false, windowIds: [] };
-  }
-
-  if (process.platform === "win32") {
-    // Windows: monitor is launched directly by spawnMonitorTerminal (no tmux)
-    // Physical terminal opening is handled there, so just return success
-    return { opened: true, windowIds: [] };
-  }
-
-  return { opened: false, windowIds: [] };
-}
-
-function spawnMonitorTerminal(sessionId) {
-  // Windows: use Windows Terminal or PowerShell directly (no tmux needed)
-  if (process.platform === "win32") {
-    const project = getProjectSlug();
-    const monitorCmd = buildMonitorCommandWindows(sessionId, project);
-
-    // Try Windows Terminal (wt.exe)
-    if (commandExistsInPath("wt") || commandExistsInPath("wt.exe")) {
-      if (tryExecFile("wt", ["new-tab", "--title", "Deliberation Monitor", "cmd", "/c", monitorCmd])) {
-        return true;
-      }
-    }
-
-    // Fallback: new PowerShell window
-    const shell = ["pwsh.exe", "pwsh", "powershell.exe", "powershell"].find(c => commandExistsInPath(c));
-    if (shell) {
-      const escaped = monitorCmd.replace(/'/g, "''");
-      if (tryExecFile(shell, ["-NoProfile", "-Command", `Start-Process cmd -ArgumentList '/c','${escaped}'`])) {
-        return true;
-      }
-    }
-
-    return false;
-  }
-
-  // macOS/Linux: use tmux (existing logic)
-  if (!commandExistsInPath("tmux")) {
-    return false;
-  }
-
-  const project = getProjectSlug();
-  const winName = tmuxWindowName(sessionId);
-  const cmd = buildMonitorCommand(sessionId, project);
-  if (!cmd) {
-    return false;
-  }
-
-  try {
-    if (hasTmuxSession(TMUX_SESSION)) {
-      // Skip if a window with the same name already exists (prevents duplicates)
-      if (hasTmuxWindow(TMUX_SESSION, winName)) {
-        appendRuntimeLog("INFO", `TMUX_WINDOW_EXISTS: ${winName} in ${TMUX_SESSION}`);
-        return true;
-      }
-      execFileSync("tmux", ["new-window", "-t", TMUX_SESSION, "-n", winName, cmd], {
-        stdio: "ignore",
-        windowsHide: true,
-      });
-      appendRuntimeLog("INFO", `TMUX_WINDOW_CREATED: ${winName} in existing ${TMUX_SESSION}`);
-    } else {
-      execFileSync("tmux", ["new-session", "-d", "-s", TMUX_SESSION, "-n", winName, cmd], {
-        stdio: "ignore",
-        windowsHide: true,
-      });
-      appendRuntimeLog("INFO", `TMUX_SESSION_CREATED: ${TMUX_SESSION} with window ${winName}`);
-    }
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-function closePhysicalTerminal(windowId) {
-  if (process.platform !== "darwin") {
-    return false;
-  }
-  if (!Number.isInteger(windowId) || windowId <= 0) {
-    return false;
-  }
-
-  const windowExists = () => {
-    try {
-      const out = execFileSync(
-        "osascript",
-        [
-          "-e",
-          'tell application "Terminal"',
-          "-e",
-          `if exists window id ${windowId} then return "1"`,
-          "-e",
-          'return "0"',
-          "-e",
-          "end tell",
-        ],
-        { encoding: "utf-8" }
-      ).trim();
-      return out === "1";
-    } catch {
-      return false;
-    }
-  };
-
-  const dismissCloseDialogs = () => {
-    try {
-      execFileSync(
-        "osascript",
-        [
-          "-e",
-          'tell application "System Events"',
-          "-e",
-          'if exists process "Terminal" then',
-          "-e",
-          'tell process "Terminal"',
-          "-e",
-          "repeat with w in windows",
-          "-e",
-          "try",
-          "-e",
-          "if exists (sheet 1 of w) then",
-          "-e",
-          "if exists button \"종료\" of sheet 1 of w then",
-          "-e",
-          'click button "종료" of sheet 1 of w',
-          "-e",
-          "else if exists button \"Terminate\" of sheet 1 of w then",
-          "-e",
-          'click button "Terminate" of sheet 1 of w',
-          "-e",
-          "else if exists button \"확인\" of sheet 1 of w then",
-          "-e",
-          'click button "확인" of sheet 1 of w',
-          "-e",
-          "else",
-          "-e",
-          "click button 1 of sheet 1 of w",
-          "-e",
-          "end if",
-          "-e",
-          "end if",
-          "-e",
-          "end try",
-          "-e",
-          "end repeat",
-          "-e",
-          "end tell",
-          "-e",
-          "end if",
-          "-e",
-          "end tell",
-        ],
-        { stdio: "ignore" }
-      );
-    } catch {
-      // ignore
-    }
-  };
-
-  for (let i = 0; i < 5; i += 1) {
-    try {
-      execFileSync(
-        "osascript",
-        [
-          "-e",
-          'tell application "Terminal"',
-          "-e",
-          "activate",
-          "-e",
-          `if exists window id ${windowId} then`,
-          "-e",
-          "try",
-          "-e",
-          `do script "exit" in window id ${windowId}`,
-          "-e",
-          "end try",
-          "-e",
-          "delay 0.12",
-          "-e",
-          "try",
-          "-e",
-          `close (window id ${windowId})`,
-          "-e",
-          "end try",
-          "-e",
-          "end if",
-          "-e",
-          "end tell",
-        ],
-        { stdio: "ignore" }
-      );
-    } catch {
-      // ignore
-    }
-
-    dismissCloseDialogs();
-
-    if (!windowExists()) {
-      return true;
-    }
-  }
-
-  return !windowExists();
-}
-
-function closeMonitorTerminal(sessionId, terminalWindowIds = []) {
-  if (process.platform !== "win32") {
-    const winName = tmuxWindowName(sessionId);
-    try {
-      execFileSync("tmux", ["kill-window", "-t", `${TMUX_SESSION}:${winName}`], {
-        stdio: "ignore",
-        windowsHide: true,
-      });
-    } catch { /* ignore */ }
-
-    try {
-      if (tmuxWindowCount(TMUX_SESSION) === 0) {
-        execFileSync("tmux", ["kill-session", "-t", TMUX_SESSION], {
-          stdio: "ignore",
-          windowsHide: true,
-        });
-      }
-    } catch { /* ignore */ }
-  }
-
-  for (const windowId of terminalWindowIds) {
-    closePhysicalTerminal(windowId);
-  }
-}
-
-function getSessionWindowIds(state) {
-  if (!state || typeof state !== "object") {
-    return [];
-  }
-  const ids = [];
-  if (Array.isArray(state.monitor_terminal_window_ids)) {
-    for (const id of state.monitor_terminal_window_ids) {
-      if (Number.isInteger(id) && id > 0) {
-        ids.push(id);
-      }
-    }
-  }
-  if (Number.isInteger(state.monitor_terminal_window_id) && state.monitor_terminal_window_id > 0) {
-    ids.push(state.monitor_terminal_window_id);
-  }
-  return [...new Set(ids)];
-}
-
-function closeAllMonitorTerminals() {
-  try {
-    execFileSync("tmux", ["kill-session", "-t", TMUX_SESSION], { stdio: "ignore", windowsHide: true });
-  } catch { /* ignore */ }
-}
-
-function multipleSessionsError() {
-  const active = listActiveSessions();
-  const list = active.map(s => `- **${s.id}** [${s.project || "unknown"}]: "${s.topic}" (Round ${s.current_round}/${s.max_rounds}, next: ${s.current_speaker})`).join("\n");
-  return t(`Multiple active sessions found. Please specify session_id:\n\n${list}`, `여러 활성 세션이 있습니다. session_id를 지정하세요:\n\n${list}`, "en");
-}
-
-function truncatePromptText(text, maxChars) {
-  const value = String(text || "").trim();
-  if (!value || !Number.isFinite(maxChars) || maxChars <= 0 || value.length <= maxChars) {
-    return value;
-  }
-  const remaining = value.length - maxChars;
-  return `${value.slice(0, maxChars).trimEnd()}\n...(truncated ${remaining} chars)`;
-}
-
-function getPromptBudgetForSpeaker(speaker, includeHistoryEntries = 4) {
-  const defaultBudget = {
-    maxEntries: Math.max(0, includeHistoryEntries),
-    maxCharsPerEntry: 1600,
-    maxTotalChars: 6400,
-    maxTopicChars: 3200,
-  };
-  switch (speaker) {
-    case "codex":
-      return {
-        maxEntries: Math.min(Math.max(0, includeHistoryEntries), 3),
-        maxCharsPerEntry: 1200,
-        maxTotalChars: 3600,
-        maxTopicChars: 2200,
-      };
-    case "gemini":
-      return {
-        maxEntries: Math.min(Math.max(0, includeHistoryEntries), 4),
-        maxCharsPerEntry: 1400,
-        maxTotalChars: 5600,
-        maxTopicChars: 2800,
-      };
-    default:
-      return defaultBudget;
-  }
-}
-
-function formatRecentLogForPrompt(state, maxEntries = 4, options = {}) {
-  const entries = Array.isArray(state.log) ? state.log.slice(-Math.max(0, maxEntries)) : [];
-  if (entries.length === 0) {
-    return "(No previous responses yet)";
-  }
-  const maxCharsPerEntry = options.maxCharsPerEntry || 1600;
-  const maxTotalChars = options.maxTotalChars || maxCharsPerEntry * entries.length;
-  const rendered = [];
-  let usedChars = 0;
-
-  for (const entry of entries) {
-    const header = `- ${entry.speaker} (Round ${entry.round})`;
-    const remainingChars = Math.max(0, maxTotalChars - usedChars - header.length - 1);
-    const entryBudget = Math.max(200, Math.min(maxCharsPerEntry, remainingChars || maxCharsPerEntry));
-    const content = truncatePromptText(entry.content, entryBudget);
-    const block = `${header}\n${content}`;
-    rendered.push(block);
-    usedChars += block.length + 2;
-    if (usedChars >= maxTotalChars) {
-      break;
-    }
-  }
-
-  return rendered.join("\n\n");
-}
-
-function getCliAutoTurnTimeoutSec({ speaker, requestedTimeoutSec, promptLength, priorTurns }) {
-  const requested = Number.isFinite(requestedTimeoutSec) ? requestedTimeoutSec : 120;
-  if (speaker === "codex") {
-    let recommended = Math.max(requested, priorTurns === 0 ? 240 : 180);
-    if (promptLength > 6000) {
-      recommended = Math.max(recommended, 300);
-    }
-    if (promptLength > 10000 || priorTurns >= 1) {
-      recommended = Math.max(recommended, 420);
-    }
-    return recommended;
-  }
-  return priorTurns === 0 ? Math.max(requested, 180) : requested;
-}
-
-function getCliExecArgs(speaker) {
-  switch (speaker) {
-    case "claude":
-      return ["-p", "--output-format", "text"];
-    case "codex":
-      return [
-        "exec",
-        "--ephemeral",
-        "-c", 'approval_policy="never"',
-        "-c", 'sandbox_mode="read-only"',
-        "-c", 'model_reasoning_effort="low"',
-        "-",
-      ];
-    case "gemini":
-      return null;
-    default:
-      return null;
-  }
-}
-
-function buildCliAutoTurnFailureText({ state, speaker, hint, err, effectiveTimeout, promptLength, priorTurns }) {
-  const isTimeout = /CLI timeout \(/.test(String(err?.message || ""));
-  if (!isTimeout) {
-    return `❌ CLI auto-turn failed: ${err.message}\n\n**Speaker:** ${speaker}\n**CLI:** ${hint.cmd}\n\nYou can submit a manual response via deliberation_respond(speaker: "${speaker}", content: "...").`;
-  }
-
-  const retryTimeout = speaker === "codex"
-    ? Math.min(Math.max(effectiveTimeout, 420), 600)
-    : Math.min(effectiveTimeout + 60, 300);
-
-  return t(
-    `⏱️ CLI auto-turn timed out.\n\n` +
-    `**Speaker:** ${speaker}\n` +
-    `**CLI:** ${hint.cmd}\n` +
-    `**Timeout:** ${effectiveTimeout}s\n` +
-    `**Prompt size:** ${promptLength} chars\n` +
-    `**Prior turns by speaker:** ${priorTurns}\n` +
-    `**Session state:** still waiting on ${speaker} for Round ${state.current_round}\n\n` +
-    `This usually means the CLI stayed busy longer than the timeout. It does **not** necessarily mean the model is down.\n` +
-    `${speaker === "codex" ? `Codex is the slowest CLI in recent deliberation logs, especially when recent_log contains long prior responses.\n` : ""}` +
-    `Recommended next step: retry with \`deliberation_cli_auto_turn(session_id: "${state.id}", timeout_sec: ${retryTimeout})\`.\n` +
-    `Manual fallback: \`deliberation_respond(session_id: "${state.id}", speaker: "${speaker}", content: "...")\`.`,
-    `⏱️ CLI 자동 턴이 타임아웃되었습니다.\n\n` +
-    `**Speaker:** ${speaker}\n` +
-    `**CLI:** ${hint.cmd}\n` +
-    `**Timeout:** ${effectiveTimeout}s\n` +
-    `**Prompt 크기:** ${promptLength} chars\n` +
-    `**이 speaker의 이전 발언 수:** ${priorTurns}\n` +
-    `**세션 상태:** Round ${state.current_round}에서 아직 ${speaker} 응답을 기다리는 중\n\n` +
-    `이건 보통 CLI가 제한 시간 안에 응답을 끝내지 못했다는 뜻입니다. 모델이 완전히 죽었다는 의미는 아닙니다.\n` +
-    `${speaker === "codex" ? `최근 딜리버레이션 로그 기준으로 Codex는 이전 응답 전문이 길게 들어가면 가장 느린 편입니다.\n` : ""}` +
-    `권장 조치: \`deliberation_cli_auto_turn(session_id: "${state.id}", timeout_sec: ${retryTimeout})\` 로 재시도하세요.\n` +
-    `수동 대안: \`deliberation_respond(session_id: "${state.id}", speaker: "${speaker}", content: "...")\`.`,
-    state?.lang
-  );
-}
-
-function buildActiveReportingSection(state, speaker) {
-  const orchestratorSessionId = state?.orchestrator_session_id;
-  if (!orchestratorSessionId) return "";
-
-  return `\n[active_reporting_rule]
-- After you successfully submit this turn with \`deliberation_respond(...)\`, send a brief status update to the orchestrator session.
-- Primary method (telepty available):
-\`telepty inject --from \"$TELEPTY_SESSION_ID\" --reply-to ${orchestratorSessionId} ${orchestratorSessionId} \"[deliberation status] session_id: ${state.id} speaker: ${speaker} round: ${state.current_round}/${state.max_rounds} submitted. no further reply needed.\"\`
-- Fallback (telepty unavailable): Include the status in your next tool call or response context.
-- Keep it to one short line. Do not wait for a reply.
-- This rule applies regardless of transport type (CLI, browser, telepty_bus).
-[/active_reporting_rule]
-`;
-}
-
-function buildClipboardTurnPrompt(state, speaker, prompt, includeHistoryEntries = 4) {
-  const promptBudget = getPromptBudgetForSpeaker(speaker, includeHistoryEntries);
-  const recent = formatRecentLogForPrompt(state, promptBudget.maxEntries, promptBudget);
-  const extraPrompt = prompt ? `\n[Additional instructions]\n${prompt}\n` : "";
-  const topic = truncatePromptText(state.topic, promptBudget.maxTopicChars);
-  const noToolRule = speaker === "codex"
-    ? `\n- Do not inspect files, run shell commands, browse, or call tools. Answer only from the provided discussion context.`
-    : "";
-  const activeReportingSection = buildActiveReportingSection(state, speaker);
-
-  // Role prompt injection
-  const speakerRole = (state.speaker_roles || {})[speaker] || "free";
-  const rolePromptText = loadRolePrompt(speakerRole);
-  const roleSection = rolePromptText
-    ? `\n[role]\nrole: ${speakerRole}\n${rolePromptText}\n[/role]\n`
-    : "";
-
-  return `[deliberation_turn_request]
-session_id: ${state.id}
-project: ${state.project}
-topic: ${topic}
-round: ${state.current_round}/${state.max_rounds}
-target_speaker: ${speaker}
-required_turn: ${state.current_speaker}${roleSection}${activeReportingSection}
-
-[recent_log]
-${recent}
-[/recent_log]${extraPrompt}
-
-[response_rule]
-- Write only ${speaker}'s response for this turn reflecting the discussion context above
-- Output markdown body only (no unnecessary headers/footers)${speakerRole !== "free" ? `\n- Analyze and respond from the perspective of assigned role (${speakerRole})` : ""}
-- Keep the response concise and decision-oriented${noToolRule}
-- Must include one of [AGREE], [DISAGREE], or [CONDITIONAL: reason] at the end of response
-[/response_rule]
-[/deliberation_turn_request]
-`;
-}
-
-function submitDeliberationTurn({ session_id, speaker, content, turn_id, channel_used, fallback_reason, attachments, source_metadata }) {
-  const resolved = resolveSessionId(session_id);
-  if (!resolved) {
-    return { content: [{ type: "text", text: t("No active deliberation.", "활성 deliberation이 없습니다.", "en") }] };
-  }
-  if (resolved === "MULTIPLE") {
-    return { content: [{ type: "text", text: multipleSessionsError() }] };
-  }
-
-  let completionState = null;
-  let completionEntry = null;
-  const result = withSessionLock(resolved, () => {
-    const state = loadSession(resolved);
-    if (!state || state.status !== "active") {
-      return { content: [{ type: "text", text: t(`Session "${resolved}" is not active.`, `세션 "${resolved}"이 활성 상태가 아닙니다.`, "en") }] };
-    }
-
-    const normalizedSpeaker = normalizeSpeaker(speaker);
-    if (!normalizedSpeaker) {
-      return { content: [{ type: "text", text: t("Speaker value is empty. Please specify a speaker name.", "speaker 값이 비어 있습니다. 응답자 이름을 지정하세요.", "en") }] };
-    }
-
-    state.speakers = buildSpeakerOrder(state.speakers, state.current_speaker, "end");
-    const normalizedCurrentSpeaker = normalizeSpeaker(state.current_speaker);
-    if (!normalizedCurrentSpeaker || !state.speakers.includes(normalizedCurrentSpeaker)) {
-      state.current_speaker = state.speakers[0];
-    } else {
-      state.current_speaker = normalizedCurrentSpeaker;
-    }
-
-    if (state.current_speaker !== normalizedSpeaker) {
-      return {
-        content: [{
-          type: "text",
-          text: t(`[${state.id}] It is currently **${state.current_speaker}**'s turn. ${normalizedSpeaker} please wait.`, `[${state.id}] 지금은 **${state.current_speaker}** 차례입니다. ${normalizedSpeaker}는 대기하세요.`, state?.lang),
-        }],
-      };
-    }
-
-    // turn_id validation (optional — must match if provided)
-    if (turn_id && state.pending_turn_id && turn_id !== state.pending_turn_id) {
-      return {
-        content: [{
-          type: "text",
-          text: t(`[${state.id}] turn_id mismatch. Expected: "${state.pending_turn_id}", received: "${turn_id}". May be a stale request or duplicate submission.`, `[${state.id}] turn_id 불일치. 예상: "${state.pending_turn_id}", 수신: "${turn_id}". 오래된 요청이거나 중복 제출일 수 있습니다.`, state?.lang),
-        }],
-      };
-    }
+  if (typeof projectSlug === "function") {
+    return withFileLock(path.join(getLocksDir(), "_project.lock"), projectSlug, fn);
+  }
+  return withFileLock(path.join(getLocksDir(projectSlug), "_project.lock"), fn, options);
+}
 
-    const votes = parseVotes(content);
-    if (votes.length === 0) {
-      appendRuntimeLog("WARN", `INVALID_TURN: ${state.id} | R${state.current_round} | speaker: ${normalizedSpeaker} | reason: no_vote_marker`);
-    }
-    const suggestedRole = inferSuggestedRole(content);
-    const assignedRole = (state.speaker_roles || {})[normalizedSpeaker] || "free";
-    const roleDrift = assignedRole !== "free" && suggestedRole !== "free" && assignedRole !== suggestedRole;
-    const logEntry = {
-      round: state.current_round,
-      speaker: normalizedSpeaker,
-      content,
-      timestamp: new Date().toISOString(),
-      turn_id: state.pending_turn_id || null,
-      channel_used: channel_used || null,
-      fallback_reason: fallback_reason || null,
-      votes: votes.length > 0 ? votes : undefined,
-      suggested_next_role: suggestedRole !== "free" ? suggestedRole : undefined,
-      role_drift: roleDrift || undefined,
-      attachments: attachments || undefined,
-      source_metadata: source_metadata || undefined,
-    };
-    state.log.push(logEntry);
-    completePendingTeleptySemantic({
-      sessionId: state.id,
-      speaker: normalizedSpeaker,
-      turnId: state.pending_turn_id || turn_id || null,
-    });
-    appendRuntimeLog("INFO", `TURN: ${state.id} | R${state.current_round} | speaker: ${normalizedSpeaker} | votes: ${votes.length > 0 ? votes.map(v => v.vote).join(",") : "none"} | channel: ${channel_used || "respond"} | attachments: ${attachments ? attachments.length : 0}${source_metadata?.source_machine_id ? ` | source_machine: ${source_metadata.source_machine_id}` : ""}`);
+function withSessionLock(sessionRef, fn, options) {
+  const sessionId = typeof sessionRef === "object" && sessionRef !== null ? sessionRef.id : sessionRef;
+  const explicitProject = typeof sessionRef === "object" && sessionRef !== null ? sessionRef.project : null;
+  const record = findSessionRecord(sessionRef, { preferProject: explicitProject || getProjectSlug() });
+  const projectSlug = explicitProject || record?.project || getProjectSlug();
+  const safeId = String(sessionId).replace(/[^a-zA-Z0-9가-힣._-]/g, "_");
+  return withFileLock(path.join(getLocksDir(projectSlug), `${safeId}.lock`), fn, options);
+}
 
-    state.current_speaker = selectNextSpeaker(state);
+// Speaker/Candidate Discovery functions moved to lib/speaker-discovery.js
 
-    // Round transition: check if all speakers have spoken this round
-    const roundEntries = state.log.filter(e => e.round === state.current_round);
-    const spokeSpeakers = new Set(roundEntries.map(e => e.speaker));
-    const allSpoke = state.speakers.every(s => spokeSpeakers.has(s));
+// BrowserControlPort singleton — moved to lib/transport.js
+// Session ID generation, context detection, state helpers, markdown sync,
+// archival — all moved to lib/session.js
+// Terminal management — moved to lib/transport.js
 
-    if (allSpoke) {
-      if (state.current_round >= state.max_rounds) {
-        state.status = "awaiting_synthesis";
-        state.current_speaker = "none";
-        saveSession(state);
-        return {
-          content: [{
-            type: "text",
-            text: t(`✅ [${state.id}] ${normalizedSpeaker} Round ${state.log[state.log.length - 1].round} complete. Forum updated (${state.log.length} responses accumulated).\n\n🏁 **All rounds complete!**\nCreate a synthesis report with deliberation_synthesize(session_id: "${state.id}").`, `✅ [${state.id}] ${normalizedSpeaker} Round ${state.log[state.log.length - 1].round} 완료. Forum 업데이트됨 (${state.log.length}건 응답 축적).\n\n🏁 **모든 라운드 종료!**\ndeliberation_synthesize(session_id: "${state.id}")로 합성 보고서를 작성하세요.`, state?.lang),
-          }],
-        };
-      }
-      state.current_round += 1;
-    }
+// multipleSessionsError, truncatePromptText, getPromptBudgetForSpeaker,
+// formatRecentLogForPrompt — moved to lib/session.js
+// getCliAutoTurnTimeoutSec, getCliExecArgs, buildCliAutoTurnFailureText — moved to lib/transport.js
+// buildActiveReportingSection, buildClipboardTurnPrompt,
+// submitDeliberationTurn — moved to lib/session.js
 
-    if (state.status === "active") {
-      state.pending_turn_id = generateTurnId();
-    }
+// ── MCP Server ─────────────────────────────────────────────────
 
-    if (!state.orchestrator_session_id) {
-      state.orchestrator_session_id = getDefaultOrchestratorSessionId() || null;
+// Gracefully handle EPIPE on stdout/stderr (MCP client disconnect)
+for (const stream of [process.stdout, process.stderr]) {
+  stream.on("error", (err) => {
+    if (err?.code === "EPIPE" || err?.code === "ERR_STREAM_DESTROYED") {
+      process.exit(0);
     }
-    completionEntry = {
-      ...logEntry,
-      turn_id: logEntry.turn_id || turn_id || null,
-    };
-    completionState = {
-      ...state,
-      log: [...state.log],
-    };
-    saveSession(state);
-    return {
-      content: [{
-        type: "text",
-        text: t(`✅ [${state.id}] ${normalizedSpeaker} Round ${state.log[state.log.length - 1].round} complete. Forum updated (${state.log.length} responses accumulated).\n\n**Next:** ${state.current_speaker} (Round ${state.current_round})`, `✅ [${state.id}] ${normalizedSpeaker} Round ${state.log[state.log.length - 1].round} 완료. Forum 업데이트됨 (${state.log.length}건 응답 축적).\n\n**다음:** ${state.current_speaker} (Round ${state.current_round})`, state?.lang),
-      }],
-    };
   });
-
-  if (completionState && completionEntry) {
-    const envelope = buildTeleptyTurnCompletedEnvelope({ state: completionState, entry: completionEntry });
-    notifyTeleptyBus(envelope).catch(() => {});
-
-    const orchestratorSessionId = completionState.orchestrator_session_id || null;
-    if (orchestratorSessionId) {
-      const notificationText = buildTurnCompletionNotificationText(completionState, completionEntry);
-      notifyTeleptySessionInject({
-        targetSessionId: orchestratorSessionId,
-        prompt: notificationText,
-        fromSessionId: `deliberation:${completionState.id}`,
-      }).catch(() => {});
-    }
-  }
-
-  return result;
 }
 
-// ── MCP Server ─────────────────────────────────────────────────
-
 process.on("uncaughtException", (error) => {
+  // EPIPE = MCP client disconnected (normal shutdown). Exit cleanly.
+  if (error?.code === "EPIPE" || error?.code === "ERR_STREAM_DESTROYED") {
+    try { appendRuntimeLog("INFO", "Client disconnected (EPIPE). Shutting down."); } catch { /* noop */ }
+    process.exit(0);
+  }
   const message = formatRuntimeError(error);
   appendRuntimeLog("UNCAUGHT_EXCEPTION", message);
   try {
@@ -3760,6 +568,11 @@ process.on("uncaughtException", (error) => {
 });
 
 process.on("unhandledRejection", (reason) => {
+  // EPIPE = MCP client disconnected (normal shutdown). Exit cleanly.
+  if (reason?.code === "EPIPE" || reason?.code === "ERR_STREAM_DESTROYED") {
+    try { appendRuntimeLog("INFO", "Client disconnected (EPIPE). Shutting down."); } catch { /* noop */ }
+    process.exit(0);
+  }
   const message = formatRuntimeError(reason);
   appendRuntimeLog("UNHANDLED_REJECTION", message);
   try {
@@ -3773,6 +586,55 @@ process.on("unhandledRejection", (reason) => {
 const __pkgPath = path.join(path.dirname(fileURLToPath(import.meta.url)), "package.json");
 const __pkgVersion = JSON.parse(fs.readFileSync(__pkgPath, "utf-8")).version;
 
+// ── Initialize speaker-discovery module dependencies ──
+initSpeakerDeps({
+  appendRuntimeLog,
+  loadDeliberationConfig,
+  getProjectSlug,
+  readJsonFileSafe,
+  writeJsonFileAtomic,
+  getSpeakerSelectionFile,
+});
+
+// ── Initialize telepty module dependencies ──
+initTeleptyDeps({
+  appendRuntimeLog,
+  normalizeSpeaker,
+  getProjectSlug,
+  resolveTransportForSpeaker,
+  generateTurnId,
+  buildClipboardTurnPrompt,
+});
+
+// ── Initialize session module dependencies ──
+initSessionDeps({
+  appendRuntimeLog,
+  writeTextAtomic,
+  readJsonFileSafe,
+  writeJsonFileAtomic,
+  withSessionLock,
+  getProjectSlug,
+  normalizeProjectSlug,
+  getProjectStateDir,
+  getSessionsDir,
+  getSessionFile,
+  getSessionProject,
+  listStateProjects,
+  getLocksDir,
+  GLOBAL_STATE_DIR,
+  OBSIDIAN_PROJECTS,
+});
+
+// ── Initialize transport module dependencies ──
+initTransportDeps({
+  appendRuntimeLog,
+  getProjectSlug,
+  getSessionFile,
+  withSessionLock,
+  loadDeliberationConfig,
+  resolveCdpEndpoints,
+});
+
 const server = new McpServer({
   name: "mcp-deliberation",
   version: __pkgVersion,
@@ -4566,534 +1428,7 @@ server.tool(
   })
 );
 
-// ────────────────────────────────────────────────────────────────────────────
-// Auto-handoff orchestrator helpers
-// ────────────────────────────────────────────────────────────────────────────
-
-/**
- * Run a single CLI auto-turn for the given session and speaker.
- * Returns { ok: true, response, elapsedMs } or { ok: false, error }.
- */
-async function runCliAutoTurnCore(sessionId, speaker, timeoutSec = 120) {
-  const state = loadSession(sessionId);
-  if (!state || state.status !== "active") {
-    return { ok: false, error: "Session not active" };
-  }
-
-  const { transport } = resolveTransportForSpeaker(state, speaker);
-  if (transport !== "cli_respond") {
-    return { ok: false, error: `Speaker "${speaker}" is not CLI type` };
-  }
-
-  const hint = CLI_INVOCATION_HINTS[speaker];
-  if (!hint) return { ok: false, error: `No CLI hints for "${speaker}"` };
-  if (!checkCliLiveness(hint.cmd)) return { ok: false, error: `CLI "${hint.cmd}" not available` };
-
-  const turnId = state.pending_turn_id || generateTurnId();
-  const turnPrompt = buildClipboardTurnPrompt(state, speaker, null, 3);
-  const speakerPriorTurns = state.log.filter(e => e.speaker === speaker).length;
-  const effectiveTimeout = getCliAutoTurnTimeoutSec({
-    speaker,
-    requestedTimeoutSec: timeoutSec,
-    promptLength: turnPrompt.length,
-    priorTurns: speakerPriorTurns,
-  });
-
-  const startTime = Date.now();
-  try {
-    const response = await new Promise((resolve, reject) => {
-      const env = { ...process.env };
-      if (hint.envPrefix?.includes("CLAUDECODE=")) delete env.CLAUDECODE;
-
-      let child;
-      let stdout = "";
-      let stderr = "";
-      let settled = false;
-      let forceKillTimer = null;
-
-      const resolveOnce = (v) => { if (!settled) { settled = true; if (forceKillTimer) clearTimeout(forceKillTimer); resolve(v); } };
-      const rejectOnce = (e) => { if (!settled) { settled = true; if (forceKillTimer) clearTimeout(forceKillTimer); reject(e); } };
-
-      switch (speaker) {
-        case "claude":
-          child = spawn("claude", getCliExecArgs("claude"), { env, windowsHide: true });
-          child.stdin.write(turnPrompt);
-          child.stdin.end();
-          break;
-        case "codex":
-          child = spawn("codex", getCliExecArgs("codex"), { env, windowsHide: true });
-          child.stdin.write(turnPrompt);
-          child.stdin.end();
-          break;
-        case "gemini":
-          child = spawn("gemini", ["-p", turnPrompt], { env, windowsHide: true });
-          break;
-        default: {
-          const flags = hint.flags ? hint.flags.split(/\s+/) : [];
-          child = spawn(hint.cmd, [...flags, turnPrompt], { env, windowsHide: true });
-          break;
-        }
-      }
-
-      const timer = setTimeout(() => {
-        try { child.kill("SIGTERM"); } catch {}
-        forceKillTimer = setTimeout(() => { try { child.kill("SIGKILL"); } catch {} }, 5000);
-        if (typeof forceKillTimer?.unref === "function") forceKillTimer.unref();
-        rejectOnce(new Error(`CLI timeout (${effectiveTimeout}s)`));
-      }, effectiveTimeout * 1000);
-
-      child.stdout.on("data", (d) => { stdout += d.toString(); });
-      child.stderr.on("data", (d) => { stderr += d.toString(); });
-
-      child.on("close", (code) => {
-        clearTimeout(timer);
-        if (code !== 0 && !stdout.trim()) {
-          rejectOnce(new Error(`CLI exit code ${code}: ${stderr.slice(0, 500)}`));
-        } else {
-          resolveOnce(stdout.trim());
-        }
-      });
-
-      child.on("error", (err) => rejectOnce(err));
-    });
-
-    // Submit the turn
-    submitDeliberationTurn({
-      session_id: sessionId,
-      speaker,
-      content: response,
-      turn_id: turnId,
-      channel_used: "cli_auto",
-    });
-
-    return { ok: true, response, elapsedMs: Date.now() - startTime };
-  } catch (err) {
-    return { ok: false, error: err.message };
-  }
-}
-
-async function runBrowserAutoTurnCore(sessionId, speaker, timeoutSec = 45) {
-  const state = loadSession(sessionId);
-  if (!state || state.status !== "active") {
-    return { ok: false, error: "Session not active" };
-  }
-
-  const { transport, profile } = resolveTransportForSpeaker(state, speaker);
-  if (transport !== "browser_auto") {
-    return { ok: false, error: `Speaker "${speaker}" is not browser_auto type` };
-  }
-
-  const turnId = state.pending_turn_id || generateTurnId();
-  const port = getBrowserPort();
-  const effectiveProvider = profile?.provider || "chatgpt";
-  const modelSelection = getModelSelectionForTurn(state, speaker, effectiveProvider);
-  const turnPrompt = buildClipboardTurnPrompt(state, speaker, null, 3);
-  const startTime = Date.now();
-
-  try {
-    const attachResult = await port.attach(sessionId, {
-      provider: effectiveProvider,
-      url: profile?.url || undefined,
-    });
-    if (!attachResult.ok) {
-      return { ok: false, error: `attach failed: ${attachResult.error?.message || "unknown error"}` };
-    }
-
-    const loginCheck = await port.checkLogin(sessionId);
-    if (loginCheck && !loginCheck.loggedIn) {
-      await port.detach(sessionId);
-      return { ok: false, error: `login required: ${loginCheck.reason || "not logged in"}` };
-    }
-
-    if (modelSelection.model !== "default") {
-      await port.switchModel(sessionId, modelSelection.model);
-    }
-
-    const sendResult = await port.sendTurnWithDegradation(sessionId, turnId, turnPrompt);
-    if (!sendResult.ok) {
-      await port.detach(sessionId);
-      return { ok: false, error: `send failed: ${sendResult.error?.message || "unknown error"}` };
-    }
-
-    const waitResult = await port.waitTurnResult(sessionId, turnId, timeoutSec);
-    await port.detach(sessionId);
-    if (!waitResult.ok || !waitResult.data?.response) {
-      return { ok: false, error: waitResult.error?.message || "no response received" };
-    }
-
-    submitDeliberationTurn({
-      session_id: sessionId,
-      speaker,
-      content: waitResult.data.response,
-      turn_id: turnId,
-      channel_used: "browser_auto",
-    });
-
-    return {
-      ok: true,
-      response: waitResult.data.response,
-      elapsedMs: Date.now() - startTime,
-      model: modelSelection.model,
-      provider: effectiveProvider,
-    };
-  } catch (err) {
-    try { await port.detach(sessionId); } catch {}
-    return { ok: false, error: err?.message || String(err) };
-  }
-}
-
-async function runTeleptyBusAutoTurnCore(sessionId, speaker, includeHistoryEntries = 4) {
-  const state = loadSession(sessionId);
-  if (!state || state.status !== "active") {
-    return { ok: false, error: "Session not active" };
-  }
-
-  const { transport } = resolveTransportForSpeaker(state, speaker);
-  if (transport !== "telepty_bus") {
-    return { ok: false, error: `Speaker "${speaker}" is not telepty_bus type` };
-  }
-
-  const startTime = Date.now();
-  const dispatchResult = await dispatchTeleptyTurnRequest({
-    state,
-    speaker,
-    includeHistoryEntries,
-    awaitSemantic: true,
-  });
-  if (!dispatchResult.publishResult?.ok) {
-    return {
-      ok: false,
-      blocked: true,
-      error: dispatchResult.publishResult?.error || dispatchResult.publishResult?.status || "telepty bus publish failed",
-      envelope: dispatchResult.envelope,
-      turnPrompt: dispatchResult.turnPrompt,
-    };
-  }
-  if (!dispatchResult.transportResult?.ok) {
-    return {
-      ok: false,
-      blocked: true,
-      error: dispatchResult.transportResult?.code || "transport timeout",
-      envelope: dispatchResult.envelope,
-      turnPrompt: dispatchResult.turnPrompt,
-    };
-  }
-  if (!dispatchResult.semanticResult?.ok) {
-    return {
-      ok: false,
-      blocked: true,
-      error: dispatchResult.semanticResult?.code || "semantic timeout",
-      envelope: dispatchResult.envelope,
-      turnPrompt: dispatchResult.turnPrompt,
-    };
-  }
-
-  return {
-    ok: true,
-    elapsedMs: Date.now() - startTime,
-    envelope: dispatchResult.envelope,
-    publishResult: dispatchResult.publishResult,
-    transportResult: dispatchResult.transportResult,
-    semanticResult: dispatchResult.semanticResult,
-  };
-}
-
-async function runUntilBlockedCore(sessionId, {
-  maxTurns = 12,
-  cliTimeoutSec = 120,
-  browserTimeoutSec = 45,
-  includeHistoryEntries = 4,
-} = {}) {
-  const steps = [];
-
-  for (let iteration = 0; iteration < maxTurns; iteration += 1) {
-    const state = loadSession(sessionId);
-    if (!state) {
-      return { ok: false, status: "missing", error: "Session not found", steps };
-    }
-    if (state.status !== "active" || state.current_speaker === "none") {
-      return { ok: true, status: state.status, steps };
-    }
-
-    const speaker = state.current_speaker;
-    const { transport } = resolveTransportForSpeaker(state, speaker);
-    const callerSpeaker = detectCallerSpeaker();
-    if (transport === "cli_respond" && callerSpeaker && normalizeSpeaker(callerSpeaker) === normalizeSpeaker(speaker)) {
-      return {
-        ok: true,
-        status: "blocked",
-        block_reason: "self_turn",
-        speaker,
-        transport,
-        turn_prompt: buildClipboardTurnPrompt(state, speaker, null, includeHistoryEntries),
-        steps,
-      };
-    }
-
-    if (transport === "manual" || transport === "clipboard") {
-      return {
-        ok: true,
-        status: "blocked",
-        block_reason: "manual_transport",
-        speaker,
-        transport,
-        turn_prompt: buildClipboardTurnPrompt(state, speaker, null, includeHistoryEntries),
-        steps,
-      };
-    }
-
-    let result = null;
-    if (transport === "cli_respond") {
-      result = await runCliAutoTurnCore(sessionId, speaker, cliTimeoutSec);
-    } else if (transport === "browser_auto") {
-      result = await runBrowserAutoTurnCore(sessionId, speaker, browserTimeoutSec);
-    } else if (transport === "telepty_bus") {
-      result = await runTeleptyBusAutoTurnCore(sessionId, speaker, includeHistoryEntries);
-    } else {
-      return {
-        ok: true,
-        status: "blocked",
-        block_reason: "unsupported_transport",
-        speaker,
-        transport,
-        turn_prompt: buildClipboardTurnPrompt(state, speaker, null, includeHistoryEntries),
-        steps,
-      };
-    }
-
-    steps.push({
-      speaker,
-      transport,
-      ok: Boolean(result?.ok),
-      error: result?.error || null,
-      elapsedMs: result?.elapsedMs || null,
-      blocked: Boolean(result?.blocked),
-    });
-
-    if (!result?.ok) {
-      return {
-        ok: Boolean(result?.blocked),
-        status: result?.blocked ? "blocked" : "error",
-        block_reason: result?.blocked ? (result.error || "transport_blocked") : null,
-        speaker,
-        transport,
-        error: result?.error || null,
-        turn_prompt: result?.turnPrompt || null,
-        steps,
-      };
-    }
-  }
-
-  const finalState = loadSession(sessionId);
-  return {
-    ok: true,
-    status: finalState?.status === "active" ? "max_turns_reached" : (finalState?.status || "completed"),
-    steps,
-  };
-}
-
-/**
- * Generate structured synthesis by calling a CLI speaker with a synthesis prompt.
- */
-async function generateAutoSynthesis(sessionId) {
-  const state = loadSession(sessionId);
-  if (!state) return null;
-
-  const historyText = state.log.map(e => `[${e.speaker}] ${e.content}`).join("\n\n---\n\n");
-
-  const synthesisPrompt = `You are a deliberation synthesizer. Analyze this discussion and produce ONLY a JSON response (no markdown, no explanation).
-
-Topic: ${state.topic}
-Project: ${state.project}
-Rounds: ${state.max_rounds}
-
-Discussion:
-${historyText}
-
-Respond with EXACTLY this JSON structure:
-{
-  "summary": "Brief summary of the outcome",
-  "decisions": ["Decision 1", "Decision 2"],
-  "actionable_tasks": [
-    {"id": 1, "task": "What to do", "files": ["path/to/file.ts"], "project": "${state.project}", "priority": "high|medium|low"}
-  ],
-  "markdown_synthesis": "# Full synthesis in markdown\\n\\n..."
-}`;
-
-  // Use the first available CLI speaker to generate synthesis
-  const speaker = state.speakers.find(s => {
-    const hint = CLI_INVOCATION_HINTS[s];
-    return hint && checkCliLiveness(hint.cmd);
-  });
-
-  if (!speaker) return null;
-
-  const hint = CLI_INVOCATION_HINTS[speaker];
-
-  try {
-    const response = await new Promise((resolve, reject) => {
-      const env = { ...process.env };
-      if (hint.envPrefix?.includes("CLAUDECODE=")) delete env.CLAUDECODE;
-
-      let child;
-      let stdout = "";
-
-      switch (speaker) {
-        case "claude":
-          child = spawn("claude", getCliExecArgs("claude"), { env, windowsHide: true });
-          child.stdin.write(synthesisPrompt);
-          child.stdin.end();
-          break;
-        case "codex":
-          child = spawn("codex", getCliExecArgs("codex"), { env, windowsHide: true });
-          child.stdin.write(synthesisPrompt);
-          child.stdin.end();
-          break;
-        case "gemini":
-          child = spawn("gemini", ["-p", synthesisPrompt], { env, windowsHide: true });
-          break;
-        default: {
-          const flags = hint.flags ? hint.flags.split(/\s+/) : [];
-          child = spawn(hint.cmd, [...flags, synthesisPrompt], { env, windowsHide: true });
-          break;
-        }
-      }
-
-      const timer = setTimeout(() => {
-        try { child.kill("SIGTERM"); } catch {}
-        reject(new Error("Synthesis generation timeout"));
-      }, 180000); // 3 min timeout for synthesis
-
-      child.stdout.on("data", (d) => { stdout += d.toString(); });
-      child.on("close", (code) => {
-        clearTimeout(timer);
-        resolve(stdout.trim());
-      });
-      child.on("error", reject);
-    });
-
-    // Extract JSON from response (may have markdown wrapping)
-    const jsonMatch = response.match(/\{[\s\S]*\}/);
-    if (!jsonMatch) return { markdown_synthesis: response };
-
-    try {
-      return JSON.parse(jsonMatch[0]);
-    } catch {
-      return { markdown_synthesis: response };
-    }
-  } catch (err) {
-    appendRuntimeLog("ERROR", `AUTO_SYNTHESIS_FAILED: ${sessionId} | ${err.message}`);
-    return null;
-  }
-}
-
-/**
- * Orchestrate full auto-handoff: run all turns -> synthesize -> inbox -> telepty.
- * Called as fire-and-forget from deliberation_start when auto_execute is true.
- */
-async function runAutoHandoff(sessionId) {
-  appendRuntimeLog("INFO", `AUTO_HANDOFF_START: ${sessionId}`);
-
-  try {
-    // Phase 1: Run all deliberation turns
-    let maxIterations = 100; // safety limit
-    while (maxIterations-- > 0) {
-      const state = loadSession(sessionId);
-      if (!state) {
-        appendRuntimeLog("ERROR", `AUTO_HANDOFF: Session ${sessionId} disappeared`);
-        return;
-      }
-      if (state.status !== "active") {
-        appendRuntimeLog("INFO", `AUTO_HANDOFF: Session ${sessionId} status=${state.status}, turns done`);
-        break;
-      }
-
-      const speaker = state.current_speaker;
-      if (speaker === "none") break;
-
-      appendRuntimeLog("INFO", `AUTO_HANDOFF_TURN: ${sessionId} | speaker: ${speaker} | round: ${state.current_round}/${state.max_rounds}`);
-
-      const runResult = await runUntilBlockedCore(sessionId, { maxTurns: 1, includeHistoryEntries: 3 });
-      const step = runResult.steps.at(-1) || null;
-      if (!runResult.ok || runResult.status === "blocked") {
-        appendRuntimeLog("WARN", `AUTO_HANDOFF_TURN_BLOCKED: ${sessionId} | speaker: ${speaker} | ${runResult.block_reason || runResult.error || "unknown"}`);
-        break;
-      }
-
-      appendRuntimeLog("INFO", `AUTO_HANDOFF_TURN_OK: ${sessionId} | speaker: ${speaker} | ${step?.elapsedMs || 0}ms`);
-    }
-
-    // Phase 2: Generate structured synthesis
-    appendRuntimeLog("INFO", `AUTO_HANDOFF_SYNTHESIZE: ${sessionId}`);
-    let synthResult = await generateAutoSynthesis(sessionId);
-
-    // Phase 3: Call synthesize (reuse existing logic)
-    const state = loadSession(sessionId);
-    if (!state) return;
-
-    // Fallback: if synthesis generation failed, build a basic structure from the discussion
-    if (!synthResult || (!synthResult.summary && !synthResult.actionable_tasks)) {
-      appendRuntimeLog("WARN", `AUTO_HANDOFF_SYNTH_FALLBACK: ${sessionId} | Building fallback from discussion log`);
-      const turns = state.log || [];
-      const fallbackSummary = turns.length > 0
-        ? `Deliberation on "${state.topic}" completed with ${turns.length} turns from ${[...new Set(turns.map(t => t.speaker))].join(", ")}.`
-        : `Deliberation on "${state.topic}" completed.`;
-      synthResult = {
-        summary: fallbackSummary,
-        decisions: [`Discussed: ${state.topic}`],
-        actionable_tasks: [],
-        markdown_synthesis: `# Auto-generated synthesis (fallback)\n\n${fallbackSummary}\n\n## Discussion\n${turns.map(t => `**${t.speaker}**: ${typeof t.content === 'string' ? t.content.substring(0, 200) : '(no content)'}${t.content && t.content.length > 200 ? '...' : ''}`).join("\n\n")}`,
-      };
-    }
-
-    const markdownSynthesis = synthResult?.markdown_synthesis ||
-      `# Auto-generated synthesis\n\n${synthResult?.summary || "Deliberation completed."}\n\n## Decisions\n${(synthResult?.decisions || []).map(d => `- ${d}`).join("\n")}\n\n## Tasks\n${(synthResult?.actionable_tasks || []).map(t => `- [${t.priority}] ${t.task}`).join("\n")}`;
-
-    const structured = {
-      summary: synthResult.summary || "",
-      decisions: synthResult.decisions || [],
-      actionable_tasks: synthResult.actionable_tasks || [],
-    };
-
-    // Apply synthesis to session
-    withSessionLock(sessionId, () => {
-      const loaded = loadSession(sessionId);
-      if (!loaded) return;
-      loaded.synthesis = markdownSynthesis;
-      loaded.structured_synthesis = structured;
-      loaded.execution_contract = buildExecutionContract({ state: loaded, structured });
-      loaded.status = "completed";
-      loaded.current_speaker = "none";
-      saveSession(loaded);
-      archiveState(loaded);
-      cleanupSyncMarkdown(loaded);
-
-      const sessionFile = getSessionFile(loaded);
-      try { if (fs.existsSync(sessionFile)) fs.unlinkSync(sessionFile); } catch {}
-    });
-
-    closeMonitorTerminal(sessionId, getSessionWindowIds(state));
-
-    appendRuntimeLog("INFO", `AUTO_HANDOFF_SYNTHESIZED: ${sessionId}`);
-
-    // Phase 4: Notify telepty bus with full structured data for dustcraw to consume
-    if (state.auto_execute) {
-      const envelope = buildTeleptySynthesisEnvelope({
-        state,
-        synthesis: markdownSynthesis,
-        structured,
-      });
-      await notifyTeleptyBus(envelope).catch(() => {});
-      appendRuntimeLog("INFO", `AUTO_HANDOFF_NOTIFIED: ${sessionId} | telepty event sent`);
-    }
-
-    appendRuntimeLog("INFO", `AUTO_HANDOFF_COMPLETE: ${sessionId}`);
-  } catch (err) {
-    appendRuntimeLog("ERROR", `AUTO_HANDOFF_ERROR: ${sessionId} | ${err.message}`);
-  }
-}
-
-// ────────────────────────────────────────────────────────────────────────────
+// Auto-handoff orchestrator helpers — moved to lib/transport.js
 
 server.tool(
   "deliberation_cli_auto_turn",
@@ -5735,6 +2070,21 @@ server.tool(
     // Notify brain ingest if endpoint configured
     callBrainIngest(state.execution_contract).catch(() => {}); // fire-and-forget
 
+    // Emit lesson_learned events for orchestrator lessons.json auto-population
+    if (state.execution_contract?.decisions?.length > 0) {
+      const lessonEvent = {
+        type: "lesson_learned",
+        session_id: state.id,
+        timestamp: new Date().toISOString(),
+        project: state.project || getProjectSlug(),
+        category: "decision",
+        lesson: state.execution_contract.summary || state.synthesis?.slice(0, 200) || "",
+        decisions: state.execution_contract.decisions,
+      };
+      notifyTeleptyBus(lessonEvent).catch(() => {}); // fire-and-forget
+      appendRuntimeLog("INFO", `LESSON_LEARNED: ${state.id} | decisions: ${state.execution_contract.decisions.length} | project: ${lessonEvent.project}`);
+    }
+
     return {
       content: [{
         type: "text",
@@ -5959,92 +2309,7 @@ server.tool(
   })
 );
 
-// ── Request Review (auto-review) ───────────────────────────────
-
-function invokeCliReviewer(command, prompt, timeoutMs) {
-  const hint = CLI_INVOCATION_HINTS[command];
-  let args;
-  let opts = { encoding: "utf-8", timeout: timeoutMs, stdio: ["pipe", "pipe", "pipe"], maxBuffer: 10 * 1024 * 1024, windowsHide: true };
-  const env = { ...process.env };
-
-  switch (command) {
-    case "claude":
-      if (hint?.envPrefix?.includes("CLAUDECODE=")) delete env.CLAUDECODE;
-      args = ["-p", "--output-format", "text", "--no-input"];
-      opts.input = prompt;
-      break;
-    case "codex":
-      args = ["exec", "-"];
-      opts.input = prompt;
-      break;
-    case "gemini":
-      args = ["-p", prompt];
-      opts.stdio = ["ignore", "pipe", "pipe"];
-      break;
-    default: {
-      const flags = hint?.flags ? hint.flags.split(/\s+/).filter(Boolean) : ["-p"];
-      args = [...flags, prompt];
-      opts.stdio = ["ignore", "pipe", "pipe"];
-      break;
-    }
-  }
-
-  try {
-    const result = execFileSync(command, args, { ...opts, env });
-    let cleaned = result;
-    if (command === "codex") {
-      const lines = result.split("\n");
-      const codexLineIdx = lines.findIndex(l => l.trim() === "codex");
-      if (codexLineIdx !== -1) {
-        cleaned = lines.slice(codexLineIdx + 1)
-          .filter(line => !/^(tokens used$|^[0-9,]*$)/.test(line))
-          .join("\n");
-      }
-    }
-    return { ok: true, response: cleaned.trim() };
-  } catch (error) {
-    if (error && error.killed) {
-      return { ok: false, error: "timeout" };
-    }
-    const msg = error instanceof Error ? error.message : String(error);
-    return { ok: false, error: msg };
-  }
-}
-
-function buildReviewPrompt(context, question, priorReviews) {
-  let prompt = `You are a code reviewer. Provide a concise, structured review.\n\n`;
-  prompt += `## Context\n${context}\n\n`;
-  prompt += `## Review Question\n${question}\n\n`;
-  if (priorReviews.length > 0) {
-    prompt += `## Prior Reviews\n`;
-    for (const r of priorReviews) {
-      prompt += `### ${r.reviewer}\n${r.response}\n\n`;
-    }
-  }
-  prompt += `Respond with your review. Be specific about issues, risks, and suggestions.`;
-  return prompt;
-}
-
-function synthesizeReviews(context, question, reviews) {
-  if (reviews.length === 0) return "(No reviews completed)";
-
-  let synthesis = `## Review Synthesis\n\n`;
-  synthesis += `**Question:** ${question}\n`;
-  synthesis += `**Reviews:** ${reviews.length}\n\n`;
-
-  synthesis += `### Individual Reviews\n\n`;
-  for (const r of reviews) {
-    synthesis += `#### ${r.reviewer}\n${r.response}\n\n`;
-  }
-
-  if (reviews.length > 1) {
-    synthesis += `### Summary\n`;
-    synthesis += `${reviews.length} reviewer(s) provided feedback on: ${question}\n`;
-    synthesis += `Reviewers: ${reviews.map(r => r.reviewer).join(", ")}\n`;
-  }
-
-  return synthesis;
-}
+// invokeCliReviewer, buildReviewPrompt, synthesizeReviews — moved to lib/transport.js
 
 server.tool(
   "deliberation_request_review",
@@ -6563,6 +2828,21 @@ server.tool(
       actionPlan = state.actionPlan;
 
       appendRuntimeLog("INFO", `DECISION_COMPLETE: ${resolved} | conflicts_resolved: ${responses.length} | decision: ${(actionPlan?.decision || "").slice(0, 60)}`);
+
+      // Emit lesson_learned for decision outcomes
+      if (actionPlan?.decision) {
+        const lessonEvent = {
+          type: "lesson_learned",
+          session_id: resolved,
+          timestamp: new Date().toISOString(),
+          project: state.project || getProjectSlug(),
+          category: "decision",
+          lesson: actionPlan.decision,
+          decisions: actionPlan.decision ? [actionPlan.decision] : [],
+        };
+        notifyTeleptyBus(lessonEvent).catch(() => {}); // fire-and-forget
+        appendRuntimeLog("INFO", `LESSON_LEARNED: ${resolved} | decision: ${actionPlan.decision.slice(0, 60)}`);
+      }
     });
 
     if (synthesisText.startsWith("❌")) {
@@ -6719,4 +2999,4 @@ if (__entryFile && path.resolve(__currentFile) === __entryFile) {
 }
 
 // ── Test exports (used by vitest) ──
-export { selectNextSpeaker, loadRolePrompt, inferSuggestedRole, parseVotes, ROLE_KEYWORDS, ROLE_HEADING_MARKERS, loadRolePresets, applyRolePreset, detectDegradationLevels, formatDegradationReport, DEGRADATION_TIERS, DECISION_STAGES, STAGE_TRANSITIONS, createDecisionSession, advanceStage, buildConflictMap, parseOpinionFromResponse, buildOpinionPrompt, generateConflictQuestions, buildSynthesis, buildActionPlan, loadTemplates, matchTemplate, hasExplicitBrowserParticipantSelection, resolveIncludeBrowserSpeakers, confirmSpeakerSelectionToken, validateSpeakerSelectionRequest, truncatePromptText, getPromptBudgetForSpeaker, formatRecentLogForPrompt, getCliAutoTurnTimeoutSec, getCliExecArgs, buildCliAutoTurnFailureText, buildClipboardTurnPrompt, getProjectStateDir, loadSession, saveSession, listActiveSessions, multipleSessionsError, findSessionRecord, mapParticipantProfiles, formatSpeakerCandidatesReport, buildTeleptyTurnRequestEnvelope, buildTeleptyTurnCompletedEnvelope, buildTeleptySynthesisEnvelope, validateTeleptyEnvelope, registerPendingTeleptyTurnRequest, handleTeleptyBusMessage, completePendingTeleptySemantic, cleanupPendingTeleptyTurn, getTeleptySessionHealth, TELEPTY_TRANSPORT_TIMEOUT_MS, TELEPTY_SEMANTIC_TIMEOUT_MS };
+export { checkToolEntitlement, selectNextSpeaker, loadRolePrompt, inferSuggestedRole, parseVotes, ROLE_KEYWORDS, ROLE_HEADING_MARKERS, loadRolePresets, applyRolePreset, detectDegradationLevels, formatDegradationReport, DEGRADATION_TIERS, DECISION_STAGES, STAGE_TRANSITIONS, createDecisionSession, advanceStage, buildConflictMap, parseOpinionFromResponse, buildOpinionPrompt, generateConflictQuestions, buildSynthesis, buildActionPlan, loadTemplates, matchTemplate, hasExplicitBrowserParticipantSelection, resolveIncludeBrowserSpeakers, confirmSpeakerSelectionToken, validateSpeakerSelectionRequest, truncatePromptText, getPromptBudgetForSpeaker, formatRecentLogForPrompt, getCliAutoTurnTimeoutSec, getCliExecArgs, buildCliAutoTurnFailureText, buildClipboardTurnPrompt, getProjectStateDir, loadSession, saveSession, listActiveSessions, multipleSessionsError, findSessionRecord, mapParticipantProfiles, formatSpeakerCandidatesReport, buildTeleptyTurnRequestEnvelope, buildTeleptyTurnCompletedEnvelope, buildTeleptySynthesisEnvelope, validateTeleptyEnvelope, registerPendingTeleptyTurnRequest, handleTeleptyBusMessage, completePendingTeleptySemantic, cleanupPendingTeleptyTurn, getTeleptySessionHealth, TELEPTY_TRANSPORT_TIMEOUT_MS, TELEPTY_SEMANTIC_TIMEOUT_MS };